Skip to content

The notebook on the web — plans readable from anywhere

Status: built and live 2026-09-13 at https://notebook.embeddedera.com. Asked for while planning: "it will be nice that I can access this plan and see it in the home page from anywhere."

The problem

Every plan, decision and server card lives in ~/Notes, which means it lives on machines Angel happens to be sitting at. The SOPs already solved this — MkDocs Material, Cloudflare Pages, behind Access, published by sop-deploy — and nothing about that machinery is specific to SOPs.

So: do not invent anything. Point the same machinery at the rest of the vault.

Shape

A second MkDocs site, notebook.embeddedera.com, built from the vault and deployed by a notebook-deploy that mirrors sop-deploy line for line. Same brand CSS, same three-state theme, same Home link, same Access gate. Read-only: editing stays in Obsidian and in Claude sessions, and the site is a view of the committed state, never a second copy to drift.

Sections, one per vault folder that is worth reading on a phone:

Section Folder Who
Plans projects/ Administration, Engineering
Decisions decisions/ everyone with the token — this is the "never re-argue this" shelf
Hardware hardware/ Engineering, Production
The server map/ Administration
Tasks tasks.md already exported nightly; links through to the board

Not published: rules/ (it is Claude's instructions, not documentation), meetings/ (quarterly numbers and personnel matters — those stay in the vault and in the quarterly pack), and anything under a private/ folder, which the build treats as a hard exclude.

The three things that need actual work

  1. Wikilinks. [task-board](../projects/task-board.md) is Obsidian syntax and MkDocs does not resolve it. A link plugin handles this, and every unresolved link should fail the build rather than render as dead text — a notebook full of broken links stops being read.
  2. A secret scan before publish. The vault is written casually and the site is a published surface, gated or not. notebook-deploy refuses to publish if the build output matches an account number, a routing number, an API key shape or a private key header. Cheap to write, and the one thing that turns a convenience into an incident.
  3. Access gating is coarse. One Access app is one policy, so the per-section "who" column above is honest intent, not enforcement — everyone holding the notebook token sees all of it. That is acceptable for Plans, Decisions and Hardware. It is the reason meetings/ stays out. If per-section gating is ever genuinely needed, the notebook moves onto the assistant service like home is doing, and reads departments.yml.

Joins to what is already planned

  • A Notebook tile on the home page, in the "ours" group, from task-board's tile list — and a notebook token in departments.yml like every other gated app, with the Access app built by onboard access-app from the registry. Not cloned from a saved policy; that is how the gate drifted last time.
  • Deploy on the same trigger as the SOP site: after notes-sync pushes. Publishing is not a thing to remember.
  • Search comes free with MkDocs Material, and is most of the value — "what did we decide about X" answered from a phone in a supplier's car park.

As built

  • notebook-build stages the vault into ~/Notes/notebook/build, resolves wikilinks and runs the secret scan. notebook-deploy builds with MkDocs Material and publishes to the Pages project embeddedera-notebook, mirroring sop-deploy line for line.
  • Published: projects/, decisions/, hardware/, map/, brand/, and tasks.md. Excluded, deliberately: rules/, meetings/, sops/ (its own site), roles/, skills/ and anything under private/.
  • The secret scan is proven, not assumed: a note containing a routing number was staged on purpose and the build refused, deleted the staging directory and exited non-zero.
  • One deviation from the plan. The plan said an unresolved wikilink should fail the build. It does not: the house rules say linking to a note that does not exist yet is deliberate — "it marks something worth writing later" — so failing would fight the way the vault is written. Unresolved links render as plain text and the build lists them (23 today) so they stay visible instead of becoming dead links.
  • Two Access apps, both built from the registry by onboard access-app: the site and its pages.dev previews. notebook is a token in the registry like every other app.

Kill criterion

Six weeks after it is published: if notebook.embeddedera.com has not been opened from a phone or a machine that is not this server, it is not solving the problem it was built for. Turn it off and keep reading the vault in Obsidian. Nothing depends on it, which is what makes the exit free — that is a property to preserve, not an accident.

Cost

Half a day, most of it the secret scan and the link checking. It reuses a proven pipeline, adds no service to the server, and costs nothing to run.

Related: task-board, company-end-state.

Log

  • 2026-09-13: written.