From 4c1d61e9050b16208549206a15696e180078e47b Mon Sep 17 00:00:00 2001
From: mpmedia <mpm@mpmedia.tv>
Date: Tue, 16 Jun 2026 19:50:43 -0500
Subject: [PATCH] docs: add reference/bootstrap.md (sanitized)

---
 .../goldbrain-memory/references/bootstrap.md  | 39 +++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 skills/goldbrain-memory/references/bootstrap.md

diff --git a/skills/goldbrain-memory/references/bootstrap.md b/skills/goldbrain-memory/references/bootstrap.md
new file mode 100644
index 0000000..e7a9ef2
--- /dev/null
+++ b/skills/goldbrain-memory/references/bootstrap.md
@@ -0,0 +1,39 @@
+# Bootstrap Procedure
+
+The goldbrain vault ships its **own** `BOOTSTRAP.md` at the vault root — that file is the canonical preflight/repair manifest. This plugin defers to it rather than duplicating the logic.
+
+> **Structure vs. procedure.** This file (and the vault's `BOOTSTRAP.md`/`STRUCTURE.md`) own *structure* — what folders and seed files must exist. Day-to-day *procedure* — parallel loading, search-before-write, append idempotency, project lifecycle transitions, scope switching, vault health, and the em-dash-safe PATCH rules — lives in `SKILL.md`. When repairing, ensure the four project-lifecycle folders exist: `projects/{incubating,active,on-hold,archived}/`.
+
+## Normal case — vault already bootstrapped
+
+At session start, read the in-vault manifest:
+
+```bash
+curl -s \
+  -H "Authorization: Bearer <OBSIDIAN_BEARER_TOKEN>" \
+  "https://goldbrainapi.mpm.to/vault/BOOTSTRAP.md"
+```
+
+If it returns content (200), the vault is set up. Skim its preflight checklist, then read `CLAUDE.md` for the operating contract and proceed with the loading procedure in `SKILL.md`. The in-vault `BOOTSTRAP.md` describes how to repair any missing folders/files; follow it if something is absent. **Never overwrite an existing file** during repair — generate only what is missing.
+
+## Fresh-vault case — BOOTSTRAP.md returns 404
+
+This means the REST API is pointed at an empty vault. Confirm with the operator once:
+
+> "The goldbrain vault looks empty — there's no `BOOTSTRAP.md`. The standard scaffold (control docs, folder tree, templates, seed notes) needs to be loaded before I can use it as memory. Want me to create the core seed files now?"
+
+If yes, create the minimum viable seed with `PUT` (the API creates intermediate directories automatically), then let the vault's own structure grow from there:
+
+1. `CLAUDE.md` — operating contract and session protocol
+2. `BOOTSTRAP.md` — preflight/repair manifest
+3. `STRUCTURE.md` — layout, taxonomy, frontmatter standard
+4. `index.md` — navigation hub
+5. `_agent/memory/semantic/operator-preferences.md` — operator profile (empty, no fabricated facts)
+6. `_agent/context/current-context.md` — empty context bundle
+7. `inbox/captures/inbox.md` — capture file
+
+Prefer copying the full prepared scaffold into the Obsidian vault folder over reconstructing it by hand — it is the source of truth for goldbrain's structure.
+
+## After bootstrap
+
+Tell the operator briefly what was created, append a line to the daily note's **Agent Log**, and write a session log in `_agent/sessions/`. Do not over-explain — they can browse the vault.