repackage

2026-06-10 20:16:34 -05:00
parent d3cb722935
commit 7619ef7c2c
35 changed files with 1433 additions and 29 deletions
@@ -0,0 +1,398 @@
+---
+name: quicksilver
+description: Use the Quicksilver Obsidian vault as the operator's persistent memory across Claude/CoWork sessions. Use whenever the operator asks to remember, save, note, log, or capture anything durable — facts, preferences, decisions, commitments — or asks what Claude knows about them, what was discussed or decided before, to check their notes, load their memory/context, add to their inbox, or track a project. Trigger even without memory phrasing when the request implies recalling or persisting state across sessions ("pick up where we left off", "anything on X before my meeting?"). Also use at the start of substantive sessions to load context and at the end to log outcomes. Do NOT use for Obsidian/REST-API development questions, "memory" meaning RAM, timed reminders, email or local-file lookups, or generic second-brain advice.
+---
+
+# Quicksilver Memory
+
+Use the **Quicksilver** Obsidian vault as persistent memory. Read context accumulated across sessions; write things the operator asks to be remembered.
+
+The vault belongs to a single **operator**, whose name and role are captured at first run (stored in the local config file and the vault marker's `operator:` field, and seeded into `operator-preferences.md`). Write memory in third person using the operator's name (e.g. "Alex prefers X", not "I prefer X") so the vault stays readable by humans and other agents.
+
+## Configuration & First Run
+
+Credentials are **not hardcoded**. They live in a local config file:
+
+```
+~/.quicksilver/quicksilver-config.json          (macOS/Linux)
+%USERPROFILE%\.quicksilver\quicksilver-config.json   (Windows)
+```
+
+At session start, **read this file** (use the Read tool — no `jq` needed) and set, for every call below:
+
+```bash
+BASE="<endpoint from config>"            # e.g. https://obsidian.example.com
+AUTH="Authorization: Bearer <api_key from config>"
+```
+
+**If the config file is absent, this is a fresh install** — run the first-run flow in `references/bootstrap.md` (prompt the operator for endpoint FQDN, API key, and name/role; verify; write the config file) **before** any vault call. Do not invent an endpoint. The endpoint is expected to present a **valid TLS certificate**, so `-k` is not needed (add it only if the operator's endpoint uses a self-signed cert). Always pass the `Authorization: Bearer` header. Paths address the vault **at its root** (e.g. `/vault/_agent/...`).
+
+**The plugin is the single source of truth.** The vault holds data only — no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md` control docs live there. All structure and procedure ship here:
+
+- Durable principles, memory model, and safety rules: `references/operating-contract.md`
+- First-run config, bootstrapping an empty vault, repair, and schema migrations: `references/bootstrap.md`
+- Vault layout and frontmatter conventions: `references/vault-layout.md`
+- Full API reference with every endpoint pattern and the memory routing map: `references/api-reference.md`
+
+## Operating Contract & Safety
+
+The vault is the **system of record** for long-term memory, not a scratchpad. Default to **additive updates, explicit status changes, and traceable summaries**. Keep agent-managed content (`agent_written: true` + `source_notes`) separable from human-authored content. Non-negotiable safety rules:
+
+- Do not fabricate facts, relationships, or prior decisions.
+- Do not mass-restructure the vault unless explicitly asked.
+- Do not delete notes unless deletion is explicitly requested and clearly safe.
+- Never store secrets or API keys inside a vault note. (The API key lives only in the local config file.)
+
+Full contract (principles, agent role, memory model): `references/operating-contract.md`.
+
+## When to Load Memory
+
+Load at the start of any substantive conversation — anything beyond a single quick factual question. The signal: the operator is starting work, planning, asking for help with something that has state, or referencing prior discussions.
+
+### Loading procedure
+
+**Step 0 — ensure the install is configured.** Read the local config file (above). If it's missing, run the first-run flow in `references/bootstrap.md` first. Otherwise load `$BASE`, the bearer key, and the operator's name.
+
+Then the cold-start reads are independent — **issue them in parallel** (one batch of 4–5 GETs), not sequentially. Parallel loading is ~3× faster wall-clock for the same call count.
+
+| # | GET | Notes |
+|---|-----|-------|
+| 1 | `/vault/_agent/quicksilver-vault.md` | The bootstrap marker. 404 → vault not set up; follow `references/bootstrap.md`. 200 → check its `schema_version` and migrate if older. |
+| 2 | `/vault/_agent/memory/semantic/operator-preferences.md` | The operator's profile |
+| 3 | `/vault/_agent/context/current-context.md` | Active scope + Scope History |
+| 4 | `/vault/_agent/sessions/` (listing) | Pick the ~5 most recent by reverse lex sort (filenames `YYYY-MM-DD-HHMM-<slug>.md`, so lex == chrono); only read the ones whose slugs look relevant |
+| 5 | `/vault/journal/daily/YYYY-MM-DD.md` | Today's note; 404 is fine — it's created on first agent activity |
+
+Do not read every session log — older sessions are reachable via `POST /search/simple/?query=...` when needed.
+
+**If a specific project is in play**, follow up with a **search across all lifecycle subfolders** (`active/`, `incubating/`, `on-hold/`, `archived/`) — searching one folder at a time misses notes filed elsewhere. Search by **both the slug AND any human title** the operator used in this conversation:
+
+```bash
+# slug
+curl -s -X POST -H "$AUTH" "$BASE/search/simple/?query=<slug>"
+
+# human title (avoids missing notes filed under a different name)
+curl -s -X POST -H "$AUTH" "$BASE/search/simple/?query=<human+title>"
+```
+
+Then read whichever match lives at `projects/<lifecycle>/<slug>.md`.
+
+Do NOT narrate this loading. Reading memory is expected behavior.
+
+## Inbox Triage
+
+`inbox/captures/inbox.md` is the catch-all for "save this somewhere — figure out where later." Without triage it grows forever and durable facts get stranded there.
+
+At the start of a substantive session, GET `inbox/captures/inbox.md`. If it contains lines older than ~7 days that haven't been routed elsewhere, surface them once:
+
+> "Three captures from last week are still in the inbox — want to route them now or leave them?"
+
+When routing accepted items, send each to its proper home:
+
+- Preference / pattern → PATCH-append under `operator-preferences.md::Observations`
+- Project idea → PUT `projects/incubating/<slug>.md`
+- Durable fact → PUT `_agent/memory/semantic/<slug>.md`
+- Person fact → PUT/PATCH `resources/people/<name>.md`
+
+Then record the move in `inbox/processing-log/YYYY-MM-DD.md` (one line per item: `- <original line> → <destination path>`). Don't delete the original capture unless the operator explicitly asks — the processing log is the audit trail.
+
+## Project Lifecycle
+
+Projects move through four folders under `projects/`. The folder name and the `status:` frontmatter field MUST agree — they are two views of the same state.
+
+| Folder | `status:` | Meaning |
+|--------|-----------|---------|
+| `projects/incubating/` | `incubating` | Idea captured; not actively worked. Promote when work starts. |
+| `projects/active/`     | `active`     | Current work. The default state for anything in motion. |
+| `projects/on-hold/`    | `on-hold`    | Paused but still tracked. Resumable. |
+| `projects/archived/`   | `archived`   | Done, abandoned, or rolled into something else. Not deleted. |
+
+**Promotion / transition rule:** move the file to the new folder AND update `status:` in the same change. A file in `projects/active/` with `status: on-hold` is broken state — fix it when you see it.
+
+**Searching:** `POST /search/simple/?query=<slug>` covers all four subfolders in one call. Always search before creating a new note (see the pre-write rule below).
+
+## When to Write Memory
+
+Write when the operator:
+
+- States a fact, preference, or commitment worth keeping ("I prefer X", "we use uv not pip", "standup is Tuesday at 10")
+- Makes a non-obvious decision worth recording
+- Says "remember that", "save this", "log this", "add to memory", "note that"
+- Finishes a meaningful working session future sessions should pick up
+
+Write in third person about the operator (by name). Every note carries the canonical frontmatter (see below). Agent-generated notes set `agent_written: true`.
+
+### Before you write — search first (MANDATORY for new notes)
+
+**Before creating any new note at `projects/<lifecycle>/<slug>.md`, `_agent/memory/semantic/<slug>.md`, `resources/people/<name>.md`, or any other slug-addressed location, search the whole vault for that slug.** Listing a single folder (e.g. `projects/active/`) is NOT sufficient — a note with the same slug may exist in `projects/on-hold/`, `projects/incubating/`, `projects/archived/`, or under a different folder entirely.
+
+```bash
+curl -s -X POST -H "$AUTH" "$BASE/search/simple/?query=<slug>"
+```
+
+If a match is found:
+- In a non-active project subfolder (`on-hold/`, `incubating/`, `archived/`): **promote/merge** — PUT the merged content to `projects/active/<slug>.md` with `status: active`, then DELETE the old location. Preserve the earliest `created:` date.
+- In the same folder you intended to write: **update in place** (PATCH or merged PUT). Never silently overwrite — fold the existing content in first.
+- Elsewhere (e.g. a stale duplicate under `resources/`): tell the operator and ask which should be canonical before writing.
+
+**Search both the slug AND any human title** the operator used (e.g. slug `quicksilver` and title `Quicksilver plugin`). Slug-only searches miss notes filed under a different naming scheme. Two cheap `POST /search/simple/?query=...` calls beat one expensive cleanup pass later.
+
+Only after the search comes back empty (or you've decided to merge) is it safe to create a new note. This rule prevents the most common duplication bug: a note exists in `on-hold/` but the agent only checked `active/` and created a parallel record.
+
+### Before you append — read first (idempotency)
+
+POST appends to the end of a file. It is **not idempotent** — running the same write twice (network retry, replay, re-trigger) produces duplicate lines that grow files silently. Before any POST that adds an entry to:
+
+- `inbox/captures/inbox.md`
+- a daily note's `## Agent Log` section
+- a `## Fact / Pattern` / `## Observations` / `## Log` heading
+
+…GET the target file (or the heading, via `/heading/...`) and substring-search for the exact line you're about to write. If present, skip the POST. The extra GET is cheap and pays for itself within a few sessions.
+
+This rule does **not** apply to PUT (which is fully replacing the file) or PATCH `replace` (which is overwriting a section by design).
+
+### Append to a file (default — additive entries)
+
+Write content to a temp file first to handle multi-line markdown cleanly, then POST:
+
+```bash
+cat > /tmp/obs_entry.md << 'OBSEOF'
+- 2026-06-05: <your entry here>
+OBSEOF
+
+curl -s -X POST -H "$AUTH" \
+  -H "Content-Type: text/markdown" \
+  --data-binary @/tmp/obs_entry.md \
+  "$BASE/vault/inbox/captures/inbox.md"
+```
+
+POST appends to the end of a file (creating it if absent). Use it for inbox captures and log sections.
+
+### Patch a specific heading (targeted update)
+
+**Heading targets use the FULL heading path, `::`-delimited from the top-level heading** — a bare subheading name fails with `400 invalid-target` and the write is lost. For example, `## Fact / Pattern` under the `# Operator Preferences` H1 is targeted as `Operator Preferences::Fact / Pattern`.
+
+**Default: GET the document map first** (every first PATCH to a file in a session — cache the result mentally for subsequent PATCHes to the same file). This eliminates the most common failure mode of PATCH:
+
+```bash
+curl -s -H "$AUTH" \
+  -H "Accept: application/vnd.olrapi.document-map+json" \
+  "$BASE/vault/_agent/memory/semantic/operator-preferences.md"
+```
+
+Returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }`. Copy the heading string verbatim into `Target`. Only skip the doc-map GET if you wrote the file yourself in this session (you already know its structure).
+
+Then PATCH:
+
+```bash
+cat > /tmp/obs_patch.md << 'OBSEOF'
+<Operator> prefers status updates that lead with the decision.
+OBSEOF
+
+curl -s -X PATCH -H "$AUTH" \
+  -H "Operation: append" \
+  -H "Target-Type: heading" \
+  -H "Target: Operator Preferences::Fact / Pattern" \
+  -H "Content-Type: text/markdown" \
+  --data-binary @/tmp/obs_patch.md \
+  "$BASE/vault/_agent/memory/semantic/operator-preferences.md"
+```
+
+Use `Operation: replace` to overwrite a section entirely (e.g. a project's `Project Name::Current status`). Percent-encode non-ASCII characters in the `Target` header; spaces are fine.
+
+### Bump `updated:` after meaningful changes
+
+When a PATCH or PUT changes meaningful content (status update, decision recorded, current-status replacement, scope switch), also PATCH the frontmatter `updated:` field to today's date. This keeps stale-detection queries honest.
+
+```bash
+curl -s -X PATCH -H "$AUTH" \
+  -H "Operation: replace" -H "Target-Type: frontmatter" -H "Target: updated" \
+  -H "Content-Type: application/json" --data '"2026-06-06"' \
+  "$BASE/vault/projects/active/<slug>.md"
+```
+
+Skip the bump for **routine log appends** — adding an Agent Log line, an inbox capture, or a timestamped Observations bullet doesn't constitute a meaningful content change. Bump on substance, not on heartbeat.
+
+### Create or overwrite a file (PUT)
+
+```bash
+cat > /tmp/obs_file.md << 'OBSEOF'
+---
+type: project
+status: active
+created: 2026-06-05
+updated: 2026-06-05
+tags: []
+agent_written: true
+source_notes: []
+---
+
+# Project Name
+
+## Current status
+...
+
+## Related
+- [[journal/daily/2026-06-05]]
+OBSEOF
+
+curl -s -X PUT -H "$AUTH" \
+  -H "Content-Type: text/markdown" \
+  --data-binary @/tmp/obs_file.md \
+  "$BASE/vault/projects/active/my-project.md"
+```
+
+The API creates intermediate directories automatically.
+
+### Search the vault
+
+```bash
+curl -s -X POST -H "$AUTH" \
+  "$BASE/search/simple/?query=your+search+terms"
+```
+
+## Scope Switching (`current-context.md`)
+
+`_agent/context/current-context.md` tracks a single active scope. The operator may shift scope several times within a day.
+
+When scope changes:
+
+1. PATCH `prepend` a dated bullet to `## Scope History` capturing the **prior** scope (one line: `- 2026-06-06: <prior scope summary>`). If `## Scope History` doesn't exist yet, POST the heading first, same pattern as the daily-note Agent Log.
+2. PATCH `replace` `## Scope` with the new scope.
+3. PATCH the frontmatter `updated:` field.
+
+This keeps a rolling trail of recent scopes in one file instead of spawning separate stash notes. Trim Scope History to the last ~10 entries when it grows past that.
+
+## Vault Health (monthly)
+
+On the first substantive session of a calendar month, run a quick health pass and write findings to `reviews/monthly/YYYY-MM-vault-health.md`. Don't auto-fix without asking.
+
+Checks:
+
+1. **Stale active projects** — for each note in `projects/active/`, check `updated:` >30 days. Likely belongs in `on-hold/`.
+2. **Unprocessed inbox** — GET `inbox/captures/inbox.md`. List items older than 14 days that never moved through the triage protocol.
+3. **Duplicate slugs across lifecycle folders** — any slug appearing in more than one of `active/`, `incubating/`, `on-hold/`, `archived/` is broken state.
+4. **Broken-heading risk** — sample 2–3 frequently-PATCHed files; confirm `## Agent Log`, `## Scope`, `## Fact / Pattern`, `## Observations` headings still exist.
+
+The pass is cheap (a few searches + a directory listing) and pays for itself by catching drift before it requires a reorg.
+
+## Daily Note — Agent Log
+
+After substantive activity, write a one-line entry to today's daily note's `## Agent Log` heading. The daily-note **template** (`journal/templates/daily-note-template.md`) defines this heading, but ad-hoc daily notes created without the template don't have it — so PATCH can fail with `invalid-target` if the note exists but lacks the heading.
+
+**Procedure (resilient):**
+
+1. Try to GET `journal/daily/YYYY-MM-DD.md`.
+2. If 404 — PUT a fresh daily note from the template, then PATCH.
+3. If 200 but `## Agent Log` is missing — POST `\n\n## Agent Log\n` to the file to add the heading, then PATCH. **Detect the heading by grepping the raw markdown for an anchored `^## Agent Log` line — do NOT grep the document-map JSON, whose headings are full `::`-delimited paths (e.g. `"2026-06-07::Agent Log"`); a bare `"Agent Log"` match fails there and a duplicate heading gets appended.**
+4. PATCH-append the entry under the target `<YYYY-MM-DD>::Agent Log` (the H1 of a daily note is the date, so that's the full target path).
+
+```bash
+# $BASE and $AUTH come from the local config file (see Configuration & First Run)
+DATE=$(date +%Y-%m-%d)
+DAILY="$BASE/vault/journal/daily/${DATE}.md"
+
+# 1+2: ensure the daily note exists (PUT from template if missing)
+HTTP=$(curl -s -o /dev/null -w "%{http_code}" -H "$AUTH" "$DAILY")
+if [ "$HTTP" = "404" ]; then
+  curl -s -H "$AUTH" "$BASE/vault/journal/templates/daily-note-template.md" \
+    | sed "s/{{date:YYYY-MM-DD}}/${DATE}/g" \
+    | curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" --data-binary @- "$DAILY"
+fi
+
+# 3: ensure the `## Agent Log` heading exists.
+# Grep the RAW markdown for an anchored heading line. Do NOT grep the document-map
+# JSON: its headings are full "::"-delimited paths (e.g. "2026-06-07::Agent Log"), so a
+# bare '"Agent Log"' match never matches and a DUPLICATE heading gets appended each time.
+if ! curl -s -H "$AUTH" "$DAILY" | grep -q '^## Agent Log'; then
+  printf '\n\n## Agent Log\n' | curl -s -X POST -H "$AUTH" -H "Content-Type: text/markdown" --data-binary @- "$DAILY"
+fi
+
+# 4: PATCH-append the entry
+cat > /tmp/agent_log.md << OBSEOF
+- ${DATE}: <one-line entry here>
+OBSEOF
+
+curl -s -X PATCH -H "$AUTH" \
+  -H "Operation: append" \
+  -H "Target-Type: heading" \
+  -H "Target: ${DATE}::Agent Log" \
+  -H "Content-Type: text/markdown" \
+  --data-binary @/tmp/agent_log.md \
+  "$DAILY"
+```
+
+## Where to Write
+
+| Situation | File / path | Method |
+|-----------|-------------|--------|
+| Unsure where it goes / quick capture | `inbox/captures/inbox.md` (date-prefixed line) | POST |
+| Operator preference or durable fact | `_agent/memory/semantic/operator-preferences.md` (append under the right heading) | PATCH |
+| Other durable facts / patterns | `_agent/memory/semantic/<slug>.md` | PUT |
+| What happened (event record) | `_agent/memory/episodic/<slug>.md` | PUT |
+| Short-lived working state | `_agent/memory/working/<slug>.md` | PUT |
+| Task-scoped context / focus | `_agent/context/current-context.md` | PATCH / PUT |
+| Working session ended with substance | `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md` | PUT |
+| Long-running project state | `projects/<lifecycle>/<slug>.md` (see Project Lifecycle) | PUT + PATCH |
+| Non-obvious decision (ADR) | `decisions/by-date/YYYY-MM-DD-<slug>.md` (see mirror note below) | PUT |
+| Person context | `resources/people/<name>.md` | PUT / PATCH |
+| Concept / reference note | `resources/concepts/` or `resources/references/` | PUT |
+| Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` — see **Daily Note — Agent Log** above | PATCH (with auto-create) |
+
+**Decision mirrors:** if the decision belongs to an existing note in `projects/active/`, add a `[[wikilink]]` to the ADR under that project's `## Key Decisions` heading (PATCH). If no matching project note exists, skip the mirror — the by-date ADR is sufficient; do not invent topical mirror files in `decisions/by-project/`.
+
+Never delete files unless the operator explicitly asks. Memory is append-friendly; deletion is destructive.
+
+## Session Logging
+
+At the end of substantive conversations (ones that produced decisions, artifacts, or commitments), create a session log. Ask once if unsure: "Want me to log a session note for this?"
+
+**Filename format is canonical: `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md`.** Always include the four-digit local-time HHMM component — it makes filenames lexically sort in true chronological order, which is what Step 3 of loading relies on. Older session logs without the HHMM part exist; leave them alone, but every new one must use the full form.
+
+See `references/session-log-template.md` for the body format.
+
+```bash
+cat > /tmp/obs_session.md << 'OBSEOF'
+<session log content — see references/session-log-template.md>
+OBSEOF
+
+curl -s -X PUT -H "$AUTH" \
+  -H "Content-Type: text/markdown" \
+  --data-binary @/tmp/obs_session.md \
+  "$BASE/vault/_agent/sessions/2026-06-05-1430-my-session.md"
+```
+
+Then add a one-line entry to today's daily note via the **Daily Note — Agent Log** procedure above.
+
+## Vault Unreachable
+
+If the API returns a connection error, timeout, or `502`, tell the operator once that the memory vault is unreachable (a `502` usually means Obsidian/the REST plugin is not running on the backend), then proceed without memory. Do not retry repeatedly.
+
+## Style Rules
+
+- Write in third person about the operator, by name: "<Operator> prefers X", not "I prefer X".
+- One vault, one operator. Do not cross-write into another operator's vault; this skill's configured endpoint owns this operator's memory.
+- **Anchor relative dates on the conversation's `currentDate`** before writing. "Today" → `currentDate`. "Thursday" / "next week" → resolve to an absolute `YYYY-MM-DD`. Never guess from training-data knowledge of the current year.
+- Every memory file has canonical YAML frontmatter — see `references/vault-layout.md`.
+- Set `agent_written: true` on agent-generated notes and list `source_notes` (plain relative paths, not links).
+- **`created:` is the earliest known date the entity was tracked anywhere in the vault, not "today".** When merging notes (e.g. promoting `on-hold/` → `active/`), preserve the earliest `created:` and only bump `updated:`.
+- **`source_notes` lists the note(s) that *triggered* or *supplied content for* this one** — e.g. the session log that produced a project update, or the daily note where a captured fact originated. It is a *backward* link to inputs. Forward links (this note → other notes it references) belong in the `## Related` section in the note body, never in frontmatter.
+- **Never put `[[wikilinks]]` in frontmatter** — YAML parses them as nested lists and the links break in Obsidian's reading view. Put all cross-references in a `## Related` section in the note **body** as a bulleted list of `[[links]]`.
+- Use Obsidian wiki links (`[[note name]]`) freely in the note **body** for cross-references.
+- Keep entries short and focused. Fewer, sharper entries beat many noisy ones — default to concision.
+- About to write something large or sensitive? Show the operator the content first and confirm.
+
+## operator-preferences.md — Rules vs Observations
+
+`_agent/memory/semantic/operator-preferences.md` separates two kinds of content:
+
+- `## Fact / Pattern` — **promoted, deduped rules.** No date prefix. These are timeless: "<Operator> prefers concise communication." Append here only when a rule is stable.
+- `## Observations` — **timestamped raw observations.** Date-prefixed: `- 2026-06-06: <Operator> chose X over Y because Z.` This is where new evidence goes by default.
+
+During monthly Vault Health or when an observation stabilizes, promote it from `## Observations` into `## Fact / Pattern` (drop the date) and remove the duplicate from Observations. Trim Observations to the last ~30 entries when it grows past that — the rest live in session logs.
+
+## What This Skill Does Not Do
+
+- Does not replace reasoning. The vault is reference material — apply judgment.
+- Does not auto-summarize the whole vault. Read targeted files, not everything.
+- Does not store passwords or secrets, and never writes the API key into a vault note. If asked to "remember my password is X", decline and suggest a password manager.
@@ -0,0 +1,205 @@
+# Quicksilver — Obsidian Local REST API Reference
+
+Server and key are **not hardcoded** — they come from the local config file
+(`~/.quicksilver/quicksilver-config.json`; see `references/bootstrap.md`). Load them once
+per session and use them in every call:
+
+```bash
+BASE="<endpoint from config>"            # e.g. https://obsidian.example.com
+AUTH="Authorization: Bearer <api_key from config>"
+```
+
+The examples below use `$BASE` and the `$AUTH` header. The endpoint is expected to present a
+**valid TLS certificate** — `-k` is not required (add it only if the operator's endpoint uses a
+self-signed cert). Paths address the vault at its **root**.
+
+---
+
+## Reading Files
+
+```bash
+# Read any file by vault path
+curl -s -H "$AUTH" "$BASE/vault/_agent/context/current-context.md"
+```
+
+Returns raw file content (text/markdown). On 404, the file does not exist.
+
+```bash
+# Read a specific heading's content only
+curl -s -H "$AUTH" \
+  "$BASE/vault/_agent/memory/semantic/operator-preferences.md/heading/Operator"
+```
+
+Nested headings: separate levels with `::` (URL-encode spaces as `%20`):
+```
+/vault/path/to/note.md/heading/Work%3A%3AMeetings
+```
+
+---
+
+## Listing Directories
+
+```bash
+# List contents of a directory (trailing slash required)
+curl -s -H "$AUTH" "$BASE/vault/_agent/sessions/"
+```
+
+Returns JSON: `{ "files": [...], "folders": [...] }`.
+
+---
+
+## Appending Content (POST)
+
+`POST` appends to the **end** of an existing file. Creates the file if it doesn't exist.
+
+```bash
+cat > /tmp/obs_entry.md << 'OBSEOF'
+- 2026-06-05: your entry here
+OBSEOF
+
+curl -s -X POST -H "$AUTH" \
+  -H "Content-Type: text/markdown" \
+  --data-binary @/tmp/obs_entry.md \
+  "$BASE/vault/inbox/captures/inbox.md"
+```
+
+---
+
+## Creating or Overwriting Files (PUT)
+
+`PUT` creates a new file or fully overwrites an existing one. Intermediate directories are created automatically.
+
+```bash
+cat > /tmp/obs_file.md << 'OBSEOF'
+---
+type: session-log
+status: complete
+created: 2026-06-05
+updated: 2026-06-05
+tags: [agent, session]
+agent_written: true
+source_notes: []
+---
+
+# content here
+
+## Related
+- [[projects/active/some-project]]
+OBSEOF
+
+curl -s -X PUT -H "$AUTH" \
+  -H "Content-Type: text/markdown" \
+  --data-binary @/tmp/obs_file.md \
+  "$BASE/vault/_agent/sessions/2026-06-05-1430-my-session.md"
+```
+
+---
+
+## Patching a Specific Section (PATCH)
+
+`PATCH` edits inside a file without rewriting it. Target and operation are set via headers.
+
+### Append under a heading
+
+**Heading targets must be the FULL heading path, `::`-delimited from the top-level heading.** A bare subheading name returns `400 invalid-target` (errorCode 40080). Example: `## Fact / Pattern` nested under `# Operator Preferences` → `Target: Operator Preferences::Fact / Pattern`. Percent-encode non-ASCII characters (e.g. `H%C3%A9llo`); spaces are fine.
+
+```bash
+cat > /tmp/obs_patch.md << 'OBSEOF'
+The operator prefers concise status updates — lead with the decision.
+OBSEOF
+
+curl -s -X PATCH -H "$AUTH" \
+  -H "Operation: append" \
+  -H "Target-Type: heading" \
+  -H "Target: Operator Preferences::Fact / Pattern" \
+  -H "Content-Type: text/markdown" \
+  --data-binary @/tmp/obs_patch.md \
+  "$BASE/vault/_agent/memory/semantic/operator-preferences.md"
+```
+
+### Discover heading / block / frontmatter targets
+
+When unsure of the exact heading path, GET the note with the document-map Accept header:
+
+```bash
+curl -s -H "$AUTH" \
+  -H "Accept: application/vnd.olrapi.document-map+json" \
+  "$BASE/vault/_agent/memory/semantic/operator-preferences.md"
+```
+
+Returns `{ "headings": [...], "blocks": [...], "frontmatterFields": [...] }`. Copy the heading string verbatim into `Target`.
+
+### Replace a heading's content entirely
+
+Same call with `Operation: replace` — e.g. to refresh a project's `Project Name::Current status`.
+
+### Prepend under a heading
+
+Same call with `Operation: prepend`.
+
+### Patch a frontmatter field
+
+```bash
+curl -s -X PATCH -H "$AUTH" \
+  -H "Operation: replace" \
+  -H "Target-Type: frontmatter" \
+  -H "Target: updated" \
+  -H "Content-Type: application/json" \
+  --data '"2026-06-05"' \
+  "$BASE/vault/projects/active/vault-foundation.md"
+```
+
+---
+
+## Searching
+
+```bash
+curl -s -X POST -H "$AUTH" \
+  "$BASE/search/simple/?query=weekly+review"
+```
+
+Returns an array of `{ filename, score, matches: [{ context, match }] }`.
+
+---
+
+## Deleting Files
+
+```bash
+curl -s -X DELETE -H "$AUTH" \
+  "$BASE/vault/archive/notes/old-note.md"
+```
+
+Only on explicit operator request. Deletion is destructive.
+
+---
+
+## URL-Encoding Notes
+
+- Path separators (`/`) in the vault path are **literal** — do not encode them.
+- Spaces in filenames or heading targets in a URL: use `%20`.
+- Nested heading levels in a URL path: use `%3A%3A` for `::`.
+- Heading text in the `Target:` header: the **full heading path** joined by `::` (e.g. `Operator Preferences::Fact / Pattern`), no `#`; spaces are fine; percent-encode non-ASCII.
+
+---
+
+## Memory Routing Map
+
+| Situation | Vault path | Method |
+|-----------|-----------|--------|
+| Quick capture / unsorted | `inbox/captures/inbox.md` (date-prefixed line) | POST |
+| Raw imported material | `inbox/imports/` | PUT |
+| Operator preference / durable fact | `_agent/memory/semantic/operator-preferences.md` | PATCH |
+| Other durable facts, patterns | `_agent/memory/semantic/<slug>.md` | PUT |
+| Event record (what happened) | `_agent/memory/episodic/<slug>.md` | PUT |
+| Short-lived, time-boxed state | `_agent/memory/working/<slug>.md` | PUT |
+| Task-scoped context / focus | `_agent/context/current-context.md` | PATCH / PUT |
+| Working-session log | `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md` | PUT |
+| Long-running project state | `projects/<lifecycle>/<slug>.md` (lifecycle: `incubating` → `active` → `on-hold`/`archived`; folder and `status:` MUST agree) | PUT + PATCH |
+| Non-obvious decision (ADR) | `decisions/by-date/YYYY-MM-DD-<slug>.md` (mirror only into an existing project note's `## Decisions`; otherwise skip) | PUT |
+| Person context | `resources/people/<name>.md` | PUT / PATCH |
+| Concept / reference note | `resources/concepts/` or `resources/references/` | PUT |
+| Daily activity / Agent Log | `journal/daily/YYYY-MM-DD.md` | POST / PATCH |
+| Periodic review | `reviews/{weekly,monthly,quarterly,annual}/` | PUT |
+| Bootstrap marker (plugin-owned) | `_agent/quicksilver-vault.md` (`schema_version`, bootstrap date, operator) — the "is this vault set up?" probe | GET / PUT |
+
+**Slug rules:** kebab-case, ASCII, ~40 chars max. Every file carries canonical frontmatter (see `vault-layout.md`).
@@ -0,0 +1,193 @@
+# First-run, Bootstrap & Repair
+
+The **plugin is the single source of truth** for Quicksilver's structure. Everything needed to stand up a vault ships in this skill under `scaffold/` — there is no dependency on any in-vault control doc and no external/local re-seed path. This makes the vault portable: point the REST API at any empty Obsidian vault, run this procedure, and it becomes a working Quicksilver vault.
+
+The vault holds **data only**. It carries no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` / `index.md`. The "is this vault set up?" signal is a small marker file, `_agent/quicksilver-vault.md`.
+
+There are **two layers** of setup, probed in order:
+
+1. **Local config** — is *this install* configured with an endpoint + key? (Step 0 below.)
+2. **Vault marker** — is the *vault* that endpoint points at scaffolded? (the Probe + Fresh bootstrap below.)
+
+---
+
+## Step 0 — Client configuration (first run)
+
+Credentials live in a **local config file**, never in the plugin source and never in the vault:
+
+```
+~/.quicksilver/quicksilver-config.json          (macOS/Linux)
+%USERPROFILE%\.quicksilver\quicksilver-config.json   (Windows)
+```
+
+At session start, **read this file** (use the Read tool — no `jq` needed). Its shape:
+
+```json
+{
+  "schema": 1,
+  "endpoint": "https://obsidian.example.com",
+  "api_key": "<bearer-token>",
+  "operator": { "name": "Alex Rivera", "role": "Network Engineer" },
+  "configured_at": "YYYY-MM-DD",
+  "verified_at": "YYYY-MM-DD"
+}
+```
+
+- **File present →** load `endpoint` (use as `$BASE`), `api_key` (use as the bearer), and `operator`. Proceed to the vault-marker probe below. No prompts.
+- **File absent → FRESH INSTALL.** Tell the operator this looks like a first run, then prompt for:
+  1. **API endpoint FQDN** (e.g. `https://obsidian.example.com`)
+  2. **API key** (the Local REST API bearer token)
+  3. **Operator name + role** (used to personalize memory)
+
+  Verify the endpoint before saving — probe the marker path:
+
+  ```bash
+  BASE="https://obsidian.example.com"        # from the operator
+  AUTH="Authorization: Bearer <key-from-operator>"
+  curl -s -o /dev/null -w "%{http_code}" -H "$AUTH" "$BASE/vault/_agent/quicksilver-vault.md"
+  ```
+
+  - `200` or `404` → reachable and authorized (`404` just means the vault isn't bootstrapped yet — expected on a brand-new vault). Write the config file.
+  - connection error / `401` / `403` → tell the operator what failed and re-prompt. Do **not** write the config file.
+
+  On success, write the config file with the Write tool (set permissions to `0600` where the platform supports it), stamping `configured_at` / `verified_at` with today's date (from `currentDate`):
+
+  ```json
+  {
+    "schema": 1,
+    "endpoint": "https://obsidian.example.com",
+    "api_key": "<bearer-token>",
+    "operator": { "name": "Alex Rivera", "role": "Network Engineer" },
+    "configured_at": "{{DATE}}",
+    "verified_at": "{{DATE}}"
+  }
+  ```
+
+From here on, every call in this skill uses `$BASE` (the configured endpoint) and an `$AUTH` header built from `api_key`:
+
+```bash
+BASE="<endpoint from config>"
+AUTH="Authorization: Bearer <api_key from config>"
+```
+
+---
+
+## Probe — is the vault bootstrapped?
+
+With `$BASE` / `$AUTH` set, GET the marker:
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" -H "$AUTH" "$BASE/vault/_agent/quicksilver-vault.md"
+```
+
+- **200** → bootstrapped. Read the marker's `schema_version`; if it is **less than** the plugin's current schema (1), run a migration pass (see *Migrations* below), otherwise proceed straight to the loading procedure in `SKILL.md`.
+- **404** → empty/unconfigured vault. Run **Fresh bootstrap** below. (If you expected an existing vault, confirm with the operator once that the REST API is pointed at the right vault before seeding.)
+
+---
+
+## Fresh bootstrap (empty vault)
+
+Idempotent and additive. **Never overwrite an existing file** — GET-probe each path and skip any that already returns `200`. The marker is written **last**, so the vault is only flagged "set up" after every piece is in place.
+
+Throughout, `{{DATE}}` means today's date (`YYYY-MM-DD`), resolved from the conversation's `currentDate`. Substitute it before PUTting any scaffold file or anchor seed.
+
+### 1. Folder tree
+
+The REST API auto-creates parent directories on PUT, so creating the tree = seeding a file into each leaf. Obsidian and git both ignore empty dirs, so drop a one-line `README.md` into any leaf that wouldn't otherwise receive a file. Required tree (leaves marked `→ README`):
+
+```
+inbox/captures  inbox/imports  inbox/processing-log
+journal/daily  journal/weekly  journal/monthly  journal/templates
+projects/active  projects/incubating  projects/on-hold  projects/archived
+areas/business  areas/personal  areas/learning  areas/systems
+resources/concepts  resources/references  resources/people  resources/meetings  resources/source-material
+decisions/by-date
+reviews/weekly  reviews/monthly  reviews/quarterly  reviews/annual
+archive/notes  archive/projects  archive/imports
+_agent/context  _agent/memory/working  _agent/memory/episodic  _agent/memory/semantic
+_agent/sessions  _agent/templates  _agent/heartbeat
+_agent/skills/active  _agent/skills/archived
+_agent/outputs/briefs  _agent/outputs/drafts  _agent/outputs/summaries  _agent/outputs/synthesis
+```
+
+> `decisions/by-project/` is intentionally **not** created — it is retired. A project-relevant decision is mirrored as a `[[wikilink]]` under that project's `## Key Decisions` heading instead.
+
+A leaf README is just a one-liner, e.g.:
+
+```bash
+printf '# %s\n\nMemory vault folder. See the quicksilver plugin for conventions.\n' "captures" \
+ | curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" --data-binary @- \
+   "$BASE/vault/inbox/captures/README.md"
+```
+
+### 2. Templates
+
+PUT every file under this skill's `scaffold/templates/` to its mirrored vault path. The tree mirrors 1:1:
+
+| Scaffold file | Vault path |
+|---|---|
+| `scaffold/templates/_agent/templates/session-log-template.md` | `_agent/templates/session-log-template.md` |
+| `scaffold/templates/_agent/templates/context-bundle-template.md` | `_agent/templates/context-bundle-template.md` |
+| `scaffold/templates/_agent/templates/working-memory-template.md` | `_agent/templates/working-memory-template.md` |
+| `scaffold/templates/_agent/templates/semantic-memory-template.md` | `_agent/templates/semantic-memory-template.md` |
+| `scaffold/templates/journal/templates/daily-note-template.md` | `journal/templates/daily-note-template.md` |
+| `scaffold/templates/journal/templates/weekly-review-template.md` | `journal/templates/weekly-review-template.md` |
+| `scaffold/templates/projects/project-template.md` | `projects/project-template.md` |
+| `scaffold/templates/decisions/decision-template.md` | `decisions/decision-template.md` |
+
+Templates keep their Obsidian Templater tokens (`{{date:YYYY-MM-DD}}` etc.) verbatim — those are resolved by Templater / by the skill's daily-note routine, not at seed time.
+
+```bash
+curl -s -X PUT -H "$AUTH" -H "Content-Type: text/markdown" \
+  --data-binary @scaffold/templates/journal/templates/daily-note-template.md \
+  "$BASE/vault/journal/templates/daily-note-template.md"
+```
+
+### 3. Anchor seeds (only if absent — no fabricated facts)
+
+Substitute `{{DATE}}` → today, and in the operator-preferences seed substitute `{{OPERATOR}}` / `{{ROLE}}` → the name and role captured in Step 0. Then PUT each:
+
+| Scaffold file | Vault path |
+|---|---|
+| `scaffold/anchors/operator-preferences.seed.md` | `_agent/memory/semantic/operator-preferences.md` |
+| `scaffold/anchors/current-context.seed.md` | `_agent/context/current-context.md` |
+| `scaffold/anchors/inbox.seed.md` | `inbox/captures/inbox.md` |
+
+Beyond the name/role captured at first run, the operator-preferences seed is deliberately empty — **do not invent preferences.** Real facts accrue through use.
+
+### 4. Vault README (human signpost)
+
+Substitute `{{DATE}}` if present, then PUT `scaffold/README.vault.md` → `/vault/README.md`. This is the only human-facing control doc in the vault and is **not** read by the agent for routing.
+
+### 5. Marker (write last)
+
+Substitute `{{DATE}}` and `{{OPERATOR}}` (the operator's name from Step 0), then PUT `scaffold/quicksilver-vault.md` → `/vault/_agent/quicksilver-vault.md`. The marker records schema version, bootstrap date, and operator name only — **never the key.** Once this returns `200`, the vault is bootstrapped.
+
+### 6. First-run trace
+
+Create today's daily note from `journal/templates/daily-note-template.md` (resolve the `{{date:…}}` tokens to today), append a one-line `## Agent Log` entry noting the bootstrap, and write a session log in `_agent/sessions/YYYY-MM-DD-HHMM-bootstrap.md`. Tell the operator briefly what was created.
+
+---
+
+## Repair (existing vault, something missing)
+
+Run the same steps 1–5, but GET-probe each path first and **only create what is missing**. Never overwrite. If a file exists but looks malformed, flag it in the session log rather than replacing it. Repair is safe to run any time and is the right response if the loading procedure hits an unexpected `404` on a structural path.
+
+---
+
+## Migrations (`schema_version` mismatch)
+
+When the marker's `schema_version` is older than the plugin's, apply the migration steps for each intervening version, then PATCH the marker's `schema_version` frontmatter to the new value.
+
+- **0 → 1** (control-docs-in-plugin): the vault previously carried root control docs (`CLAUDE.md`, `BOOTSTRAP.md`, `STRUCTURE.md`, `index.md`). Back them up outside the vault, DELETE them, PUT the thin `scaffold/README.vault.md` over the old verbose `README.md`, write the marker, and scrub now-dangling `[[CLAUDE]]`/`[[BOOTSTRAP]]`/`[[STRUCTURE]]`/`[[index]]` links from the `## Related` sections of `operator-preferences.md` and `current-context.md` (leave historical session logs alone). Confirm with the operator before deleting.
+
+### Marker rename (legacy `echo-vault.md` → `quicksilver-vault.md`)
+
+A vault bootstrapped by the older `echo-memory` plugin has its marker at `_agent/echo-vault.md`. On probe, if `_agent/quicksilver-vault.md` is `404` **but** `_agent/echo-vault.md` is `200`, treat it as a rename migration rather than a fresh bootstrap:
+
+1. GET `_agent/echo-vault.md`, preserve its `schema_version` / `bootstrapped` / `operator` values.
+2. PUT the current `scaffold/quicksilver-vault.md` to `_agent/quicksilver-vault.md` with those values carried over.
+3. DELETE `_agent/echo-vault.md`.
+4. Scrub any dangling `[[echo-vault]]` links from `## Related` sections (leave historical session logs alone).
+
+Confirm with the operator before deleting the old marker.
@@ -0,0 +1,36 @@
+# Quicksilver — Operating Contract
+
+The durable, client-independent contract for any agent operating against the Quicksilver vault. These principles and safety rules formerly lived in the vault's `CLAUDE.md`; they now live in the plugin so they survive regardless of what is (or isn't) in the vault. Day-to-day *procedure* — loading order, search-first, triage, scope switching, PATCH/append rules — is owned by `SKILL.md`. This file holds the things that don't change between sessions or clients.
+
+## What this agent is
+
+You are an agent operating against an Obsidian vault that functions as a shared, long-term memory substrate for human work, Claude Code / CoWork sessions, and future REST/MCP clients. Your role is to read context, synthesize across notes, produce structured outputs, update memory carefully, and leave durable traces in the vault rather than keeping important state only in the conversation. The vault is the **system of record**, not a scratchpad.
+
+## Core principles
+
+- Treat the vault as the system of record for long-term memory.
+- Prefer Markdown, YAML frontmatter, wiki-links, and stable folder conventions over proprietary structures.
+- Write notes so both humans and agents can understand them without hidden context.
+- Preserve history instead of silently overwriting important decisions, summaries, or inferred preferences.
+- Keep agent-managed content (`agent_written: true` + `source_notes`) clearly separated from human-authored content.
+- Default to **additive updates, explicit status changes, and traceable summaries.**
+- Optimize for portability: the same vault should work across Claude Code, CoWork, MCP-compatible tools, and REST API clients.
+
+## Memory model (where things live)
+
+- **Working** → `_agent/memory/working/` — transient, time-boxed.
+- **Episodic** → `_agent/memory/episodic/` — what happened, when.
+- **Semantic** → `_agent/memory/semantic/` — durable facts, patterns, preferences (`operator-preferences.md`).
+- **Context bundles** → `_agent/context/` — task-focused reading lists and active state.
+
+## Safety rules
+
+- Do not fabricate facts, relationships, or prior decisions.
+- Do not mass-restructure the vault unless explicitly asked.
+- Do not delete notes unless deletion is explicitly requested and clearly safe.
+- Do not store secrets or API keys inside the vault, and never write the API key into a vault note.
+- Default to additive updates and explicit status changes over destructive edits.
+
+## REST/API readiness
+
+Assume clients may operate without filesystem access, through the Obsidian Local REST API. Keep paths predictable, frontmatter parseable, titles stable, and all state stored in notes rather than hidden conversation memory. Structure must stay portable: a fresh, empty vault is brought fully online by the plugin's bootstrap (`references/bootstrap.md`), so nothing essential should depend on files existing in the vault ahead of time.
@@ -0,0 +1,110 @@
+# Session Log Template
+
+Session logs go in: `_agent/sessions/YYYY-MM-DD-HHMM-<slug>.md`
+
+**Filename format is canonical and not optional.** The four-digit local-time HHMM component is what makes session filenames lex-sort in true chronological order — the loading procedure depends on it. Before PUT-ing a new session log, validate the filename matches `^\d{4}-\d{2}-\d{2}-\d{4}-[a-z0-9-]+\.md$`. Legacy session logs without HHMM exist in the vault; do not edit their names, but every new write must use the full form.
+
+The slug describes what the session was about in 2–5 words, kebab-case.
+Examples: `2026-06-05-1430-quicksilver-plugin-build.md`, `2026-05-14-0900-q1-review-prep.md`.
+
+Keep logs focused. Capture the goal, what was read/done, decisions, outputs, open threads, and the next step. This matches the vault's `_agent/templates/session-log-template.md`.
+
+---
+
+## Template
+
+```markdown
+---
+type: session-log
+status: complete
+created: 2026-06-05T14:30
+updated: 2026-06-05T14:30
+tags: [agent, session]
+agent_written: true
+source_notes: []
+session_date: 2026-06-05
+client: claude-code
+---
+
+# Session Log
+
+## Goal
+One line — what this session set out to do.
+
+## Notes Read
+- [[note]] — why it was relevant
+(omit if none)
+
+## Actions Taken
+Brief narrative or bullets of what was done.
+
+## Decisions Made
+- Decision — why
+(omit section if none)
+
+## Outputs Created
+- `path/or/filename` — what it is
+(omit section if none)
+
+## Open Threads
+- [ ] unresolved question or next step
+(omit section if none)
+
+## Suggested Next Step
+One sentence: what to do first next time on this topic.
+
+## Related
+- [[wikilinks go here, in the body — never in frontmatter]]
+```
+
+---
+
+## Example
+
+```markdown
+---
+type: session-log
+status: complete
+created: 2026-06-05T14:30
+updated: 2026-06-05T14:30
+tags: [agent, session, plugin]
+agent_written: true
+source_notes: ["resources/references/obsidian-local-rest-api.md"]
+session_date: 2026-06-05
+client: claude-code
+---
+
+# Session Log
+
+## Goal
+Build and package the quicksilver CoWork plugin against the live vault.
+
+## Notes Read
+- [[_agent/memory/semantic/operator-preferences]]
+
+## Actions Taken
+Verified the REST API end-to-end, confirmed the scaffold copied into the live vault,
+created missing empty folders, and built the plugin (SKILL + reference files).
+
+## Decisions Made
+- Vault addressed at root — Quicksilver is a dedicated vault.
+- Credentials read from the local config file (`~/.quicksilver/quicksilver-config.json`); the API key is never stored in the vault.
+
+## Outputs Created
+- `quicksilver.plugin` — installable CoWork plugin
+
+## Open Threads
+- [ ] Validate Claude Code direct filesystem access to the vault host.
+
+## Suggested Next Step
+Install the plugin and run a live load/write through it to confirm the skill triggers.
+
+## Related
+- [[projects/active/vault-foundation]]
+- [[resources/references/obsidian-local-rest-api]]
+```
+
+After writing the log, append a one-line entry to the daily note's **Agent Log** section.
+
+> **Reminder:** wiki links go in the body (e.g. this `## Related` section), never in YAML
+> frontmatter. `source_notes` in frontmatter holds plain relative path strings, not `[[links]]`.
@@ -0,0 +1,160 @@
+# Vault Layout & Frontmatter Conventions
+
+**This document is canonical.** The Quicksilver vault holds data only — there are no `CLAUDE.md` / `STRUCTURE.md` / `BOOTSTRAP.md` / `index.md` control docs in it. Layout, taxonomy, and frontmatter conventions live here in the plugin; the bootstrap procedure (`references/bootstrap.md`) builds the tree below into any empty vault.
+
+## Folder Map (root-addressed)
+
+```
+/vault/
+├── README.md          ← thin human signpost (NOT read for routing)
+├── inbox/
+│   ├── captures/      ← quick captures (inbox.md), date-prefixed lines
+│   ├── imports/       ← raw imported material
+│   └── processing-log/
+├── journal/
+│   ├── daily/         ← YYYY-MM-DD.md (has an "Agent Log" section)
+│   ├── weekly/  monthly/
+│   └── templates/
+├── projects/         ← lifecycle: incubating → active → on-hold/archived
+│   ├── active/        ← current work (status: active)
+│   ├── incubating/    ← idea captured, not yet started (status: incubating)
+│   ├── on-hold/       ← paused but kept (status: on-hold)
+│   ├── archived/      ← done / abandoned (status: archived)
+│   └── project-template.md
+├── areas/             ← business / personal / learning / systems
+├── resources/
+│   ├── concepts/  references/  meetings/  source-material/
+│   └── people/        ← <name>.md
+├── decisions/
+│   ├── by-date/       ← YYYY-MM-DD-<slug>.md (ADR-style) — the canonical home
+│   └── decision-template.md
+│   (decisions/by-project/ exists in the legacy scaffold but is not used —
+│    mirror an ADR into a project's `## Decisions` heading instead)
+├── reviews/           ← weekly / monthly / quarterly / annual
+├── archive/           ← notes / projects / imports
+└── _agent/
+    ├── quicksilver-vault.md  ← bootstrap marker: schema_version + bootstrap date (plugin-owned; the "is this vault set up?" probe)
+    ├── context/       ← current-context.md and task bundles
+    ├── memory/
+    │   ├── working/   ← transient, time-boxed
+    │   ├── episodic/  ← what happened, when
+    │   └── semantic/  ← durable facts/patterns (operator-preferences.md)
+    ├── sessions/      ← YYYY-MM-DD-HHMM-<slug>.md
+    ├── templates/     ← canonical note templates
+    ├── outputs/       ← briefs / drafts / summaries / synthesis
+    ├── skills/        ← active / archived
+    └── heartbeat/     ← single-line pointers (e.g. last-session.md → most-recent session log path)
+```
+
+**Heartbeat:** `_agent/heartbeat/last-session.md` is a one-line pointer file an agent MAY write at session end (`<session-log-path> @ <ISO-timestamp>`). Reading it at session start is cheaper than listing the sessions directory; use it as a hint, not a source of truth — fall back to the directory listing if it's missing or stale.
+
+**Slug rules:** kebab-case, ASCII only, truncate to ~40 chars.
+
+---
+
+## Canonical Frontmatter
+
+Every note starts with this block. Fill what applies; leave the rest empty rather than guessing.
+
+```yaml
+---
+type:            # see Note Types below
+status:          # active | draft | done | archived | complete
+created:         # YYYY-MM-DD (or YYYY-MM-DDTHH:mm for sessions)
+updated:         # YYYY-MM-DD
+tags: []
+agent_written: false
+source_notes: []   # plain relative paths as strings — NEVER [[wikilinks]]
+---
+```
+
+`agent_written: true` + a populated `source_notes` is the key signal separating
+agent-managed content from human-authored content. When appending with POST, do
+not rewrite frontmatter — the append goes after existing content. To change
+`updated:` or `status:`, use PATCH with `Target-Type: frontmatter`.
+
+**Frontmatter field semantics:**
+
+- `created:` is the **earliest known date** the entity was tracked in the vault — *not* "today". When merging notes (e.g. promoting an `on-hold/` project into `active/`), preserve the earliest `created:` from any merged source and only update `updated:`.
+- `source_notes` is a **backward link** — the note(s) that triggered or supplied content for this one (e.g. the session log a project update came from). Forward links go in the `## Related` body section, never here.
+- `status:` for a project MUST match its folder under `projects/` (`active`, `incubating`, `on-hold`, `archived`). Moving the file and updating `status:` are the same operation.
+
+> **No `[[wikilinks]]` in frontmatter.** YAML parses `[[...]]` as nested lists, so wiki
+> links there break and never render as clickable links in reading view. Put all
+> cross-references in a **`## Related`** section in the note **body** (bulleted `[[links]]`).
+> Frontmatter holds scalar/string metadata only; `source_notes` values are plain relative
+> paths, not links.
+
+## Note Types
+
+`daily-note`, `weekly-note`, `monthly-note`, `project`, `project-update`, `area`,
+`concept`, `reference`, `person`, `meeting`, `decision`, `review`, `session-log`,
+`working-memory`, `episodic-memory`, `semantic-memory`, `context-bundle`, `skill`,
+`draft`, `inbox-item`.
+
+---
+
+## File-Specific Conventions
+
+### operator-preferences.md (`_agent/memory/semantic/`)
+
+The profile analog. Canonical headings:
+
+- `## Operator` — who the operator is (one paragraph), captured at first run
+- `## Fact / Pattern` — **promoted, deduped rules.** No date prefix. Timeless.
+- `## Observations` — **timestamped raw observations.** Date-prefixed lines (`- 2026-06-06: ...`). Default landing zone for new evidence.
+- `## Evidence` — citations/links supporting the rules
+- `## Recommendation or Implication` — how the rules should shape behavior
+- `## Review Notes` — confidence / last review date
+
+Append observed facts under `## Observations` by default. Promote to `## Fact / Pattern` (dropping the date) once a pattern stabilizes. The operator's name is captured at first run (stored in the local config file and the vault marker's `operator:` field); write memory in third person using that name.
+
+### projects/active/\<slug\>.md
+
+```markdown
+---
+type: project
+status: active
+created: 2026-06-05
+updated: 2026-06-05
+tags: []
+agent_written: false
+source_notes: []
+---
+
+# Project Name
+
+## Current status
+One paragraph, kept fresh via PATCH replace.
+
+## Decisions
+- [[YYYY-MM-DD-decision-slug]] — one-line summary
+
+## Open threads
+- [ ] unresolved thing
+
+## Log
+- 2026-06-05: observation or update
+
+## Related
+- [[areas/business/business-ops]]
+```
+
+### sessions/YYYY-MM-DD-HHMM-\<slug\>.md
+
+See `session-log-template.md`. Quicksilver uses an **HHMM time component** in the filename — this is **canonical, not optional**. The four-digit local-time component makes filenames lex-sort in true chronological order, which the loading procedure relies on. Older session logs without HHMM exist; leave them alone, but every new one must use the full `YYYY-MM-DD-HHMM-<slug>.md` form.
+
+### decisions/by-date/YYYY-MM-DD-\<slug\>.md
+
+ADR-style: Context → Decision → Consequences. If the decision belongs to an existing project, PATCH-append the wikilink into that project's `## Decisions` heading. Don't use `decisions/by-project/` — it's legacy scaffolding that's intentionally left empty.
+
+### people/\<name\>.md
+
+`type: person`. Use lowercase kebab-case for the slug (e.g. `alex-rivera.md`).
+
+---
+
+## Cross-References
+
+Use Obsidian wiki links freely: `[[note-name]]` or `[[folder/note]]`. The REST API
+doesn't resolve them, but Obsidian does when the operator browses the vault.
@@ -0,0 +1,12 @@
+# Quicksilver Memory Vault
+
+This Obsidian vault is the persistent memory substrate ("second brain") for its operator. It is read and written across Claude / CoWork sessions through the Obsidian Local REST API.
+
+**This vault holds data, not logic.** All operating procedure — how the vault is bootstrapped, how notes are routed, the taxonomy, frontmatter conventions, and safety rules — lives in the **`quicksilver` plugin**, which is the single source of truth. There are intentionally no `CLAUDE.md` / `BOOTSTRAP.md` / `STRUCTURE.md` control docs in this vault; updating or porting Quicksilver means updating or installing the plugin, not editing files here.
+
+- **Layout:** see the plugin's `references/vault-layout.md`.
+- **Operating contract & safety:** see the plugin's `references/operating-contract.md`.
+- **Bootstrap / repair:** see the plugin's `references/bootstrap.md`.
+- **Version marker:** `_agent/quicksilver-vault.md` records the schema version and bootstrap date.
+
+Folders: `inbox/`, `journal/`, `projects/`, `areas/`, `resources/`, `decisions/`, `reviews/`, `archive/`, and the agent subtree `_agent/`.
@@ -0,0 +1,25 @@
+---
+type: context-bundle
+status: active
+created: "{{DATE}}"
+updated: "{{DATE}}"
+tags: [agent, context]
+agent_written: true
+source_notes: []
+scope:
+refresh_strategy: on-demand
+---
+
+# Current Context
+
+## Scope
+<!-- The single active scope. Replaced (PATCH replace) on each scope switch. -->
+
+## Scope History
+<!-- Dated bullets of prior scopes, newest first: `- {{DATE}}: <prior scope summary>`. Trim to ~10. -->
+
+## Active Priorities
+
+## Open Questions
+
+## Related
@@ -0,0 +1,3 @@
+# Inbox — Captures
+
+Quick captures land here as date-prefixed lines (`- {{DATE}}: <thing>`), one per line, via POST. Triage routes durable items to their proper home (see the quicksilver skill's Inbox Triage). Don't delete originals on triage — the processing log is the audit trail.
@@ -0,0 +1,32 @@
+---
+type: semantic-memory
+status: active
+created: "{{DATE}}"
+updated: "{{DATE}}"
+tags: [agent, semantic-memory, operator]
+agent_written: true
+source_notes: []
+confidence: low
+last_reviewed: "{{DATE}}"
+---
+
+# Operator Preferences
+
+## Operator
+{{OPERATOR}} — {{ROLE}}.
+<!-- Captured at first run. Expand to one paragraph as facts are confirmed; do not fabricate beyond what the operator stated. -->
+
+## Fact / Pattern
+<!-- Promoted, deduped, timeless rules. No date prefix. Add only when a rule is stable. -->
+
+## Observations
+<!-- Timestamped raw observations. Default landing zone for new evidence: `- {{DATE}}: ...` -->
+
+## Evidence
+
+## Recommendation or Implication
+
+## Review Notes
+Seeded empty at bootstrap ({{DATE}}). Raise confidence once preferences are confirmed through day-to-day use.
+
+## Related
@@ -0,0 +1,22 @@
+---
+type: reference
+status: active
+created: "{{DATE}}"
+updated: "{{DATE}}"
+tags: [agent, system, marker]
+agent_written: true
+source_notes: []
+schema_version: 1
+bootstrapped: "{{DATE}}"
+managed_by: quicksilver-plugin
+operator: "{{OPERATOR}}"
+---
+
+# Quicksilver Vault Marker
+
+This file marks the vault as bootstrapped by the **quicksilver plugin** and records its schema version. The plugin's loading procedure GETs this file as its "is this vault set up?" probe; a `404` triggers a fresh bootstrap.
+
+- `schema_version` — bumped by the plugin when the vault layout changes; a mismatch is the hook for a migration pass (see `references/bootstrap.md`).
+- `operator` — the vault owner's name, captured at first run. Non-secret identity only.
+- **No secret is ever stored here.** The API endpoint and key live in the local config file (`~/.quicksilver/quicksilver-config.json`), never in the vault.
+- Do not hand-edit. The plugin owns this file.
@@ -0,0 +1,27 @@
+---
+type: context-bundle
+status: active
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
+tags: [agent, context]
+agent_written: true
+source_notes: []
+scope:
+refresh_strategy: on-demand
+---
+
+# Context Bundle Title
+
+## Scope
+
+## Active Priorities
+
+## Relevant Entities
+
+## Key Decisions
+
+## Open Questions
+
+## Source Notes
+
+## Related
@@ -0,0 +1,23 @@
+---
+type: semantic-memory
+status: active
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
+tags: [agent, semantic-memory]
+agent_written: true
+source_notes: []
+confidence: high
+last_reviewed: "{{date:YYYY-MM-DD}}"
+---
+
+# Semantic Memory Title
+
+## Fact / Pattern
+
+## Evidence
+
+## Recommendation or Implication
+
+## Review Notes
+
+## Related
@@ -0,0 +1,29 @@
+---
+type: session-log
+status: complete
+created: "{{date:YYYY-MM-DDTHH:mm}}"
+updated: "{{date:YYYY-MM-DDTHH:mm}}"
+tags: [agent, session]
+agent_written: true
+source_notes: []
+session_date: "{{date:YYYY-MM-DD}}"
+client: claude-code
+---
+
+# Session Log
+
+## Goal
+
+## Notes Read
+
+## Actions Taken
+
+## Decisions Made
+
+## Outputs Created
+
+## Open Threads
+
+## Suggested Next Step
+
+## Related
@@ -0,0 +1,22 @@
+---
+type: working-memory
+status: active
+created: "{{date:YYYY-MM-DDTHH:mm}}"
+updated: "{{date:YYYY-MM-DDTHH:mm}}"
+tags: [agent, working-memory]
+agent_written: true
+source_notes: []
+expires_after: 48h
+---
+
+# Working Context
+
+## Active Focus
+
+## Recent Decisions
+
+## Open Threads
+
+## Relevant Links
+
+## Related
@@ -0,0 +1,25 @@
+---
+type: decision
+status: complete
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
+tags: [decision]
+agent_written: true
+source_notes: []
+decision_date: "{{date:YYYY-MM-DD}}"
+impact: medium
+---
+
+# Decision Title
+
+## Context
+
+## Decision
+
+## Rationale
+
+## Consequences
+
+## Follow-Up
+
+## Related
@@ -0,0 +1,25 @@
+---
+type: daily-note
+status: active
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
+tags: [daily, journal]
+agent_written: false
+source_notes: []
+---
+
+# {{date:YYYY-MM-DD}}
+
+## Top Priorities
+
+## Schedule / Commitments
+
+## Open Loops
+
+## Notes
+
+## Context for AI
+
+## Agent Log
+
+## Related
@@ -0,0 +1,26 @@
+---
+type: review
+status: active
+created: "{{date:gggg-[W]WW}}"
+updated: "{{date:gggg-[W]WW}}"
+tags: [review, weekly]
+agent_written: true
+source_notes: []
+period: weekly
+---
+
+# Weekly Review
+
+## Completed Work
+
+## Open Loops
+
+## Stale Projects
+
+## Decisions
+
+## Priorities Next Week
+
+## Agent Notes
+
+## Related
@@ -0,0 +1,31 @@
+---
+type: project
+status: active
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
+tags: [project]
+agent_written: false
+source_notes: []
+owner:
+review_cycle: weekly
+---
+
+# Project Name
+
+## Purpose
+
+## Status
+
+## Goals
+
+## Current Context
+
+## Open Loops
+
+## Key Decisions
+
+## Related Notes
+
+## Session History
+
+## Related
@@ -1,6 +1,6 @@
 ---
 name: quicksilver
-description: Use the Quicksilver Obsidian vault as the operator's persistent memory across Claude/CoWork sessions. Use whenever the operator asks to remember, save, note, log, or capture anything durable — facts, preferences, decisions, schedule changes, commitments — or asks what Claude knows about them, what was discussed or decided before, to check their notes, load their memory/profile/context, add to their inbox, or to track a new project. Trigger even without memory phrasing when the request implies recalling or persisting state across sessions ("pick up where we left off", "anything on X before my meeting?"). Also use proactively at the start of substantive work sessions to load context and at the end to log outcomes. Do NOT use for a different operator's vault, Obsidian/REST-API development questions, "memory" meaning RAM, timed reminders, email or local-file lookups, generic second-brain advice, or notes the operator routes to a specific other file or app.
+description: Use the Quicksilver Obsidian vault as the operator's persistent memory across Claude/CoWork sessions. Use whenever the operator asks to remember, save, note, log, or capture anything durable — facts, preferences, decisions, commitments — or asks what Claude knows about them, what was discussed or decided before, to check their notes, load their memory/context, add to their inbox, or track a project. Trigger even without memory phrasing when the request implies recalling or persisting state across sessions ("pick up where we left off", "anything on X before my meeting?"). Also use at the start of substantive sessions to load context and at the end to log outcomes. Do NOT use for Obsidian/REST-API development questions, "memory" meaning RAM, timed reminders, email or local-file lookups, or generic second-brain advice.
 ---

 # Quicksilver Memory
@@ -1,8 +1,8 @@
 ---
 type: context-bundle
 status: active
-created: {{DATE}}
-updated: {{DATE}}
+created: "{{DATE}}"
+updated: "{{DATE}}"
 tags: [agent, context]
 agent_written: true
 source_notes: []
@@ -1,13 +1,13 @@
 ---
 type: semantic-memory
 status: active
-created: {{DATE}}
-updated: {{DATE}}
+created: "{{DATE}}"
+updated: "{{DATE}}"
 tags: [agent, semantic-memory, operator]
 agent_written: true
 source_notes: []
 confidence: low
-last_reviewed: {{DATE}}
+last_reviewed: "{{DATE}}"
 ---

 # Operator Preferences
@@ -1,15 +1,15 @@
 ---
 type: reference
 status: active
-created: {{DATE}}
-updated: {{DATE}}
+created: "{{DATE}}"
+updated: "{{DATE}}"
 tags: [agent, system, marker]
 agent_written: true
 source_notes: []
 schema_version: 1
-bootstrapped: {{DATE}}
+bootstrapped: "{{DATE}}"
 managed_by: quicksilver-plugin
-operator: {{OPERATOR}}
+operator: "{{OPERATOR}}"
 ---

 # Quicksilver Vault Marker
@@ -1,8 +1,8 @@
 ---
 type: context-bundle
 status: active
-created: {{date:YYYY-MM-DD}}
-updated: {{date:YYYY-MM-DD}}
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
 tags: [agent, context]
 agent_written: true
 source_notes: []
@@ -1,13 +1,13 @@
 ---
 type: semantic-memory
 status: active
-created: {{date:YYYY-MM-DD}}
-updated: {{date:YYYY-MM-DD}}
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
 tags: [agent, semantic-memory]
 agent_written: true
 source_notes: []
 confidence: high
-last_reviewed: {{date:YYYY-MM-DD}}
+last_reviewed: "{{date:YYYY-MM-DD}}"
 ---

 # Semantic Memory Title
@@ -1,12 +1,12 @@
 ---
 type: session-log
 status: complete
-created: {{date:YYYY-MM-DDTHH:mm}}
-updated: {{date:YYYY-MM-DDTHH:mm}}
+created: "{{date:YYYY-MM-DDTHH:mm}}"
+updated: "{{date:YYYY-MM-DDTHH:mm}}"
 tags: [agent, session]
 agent_written: true
 source_notes: []
-session_date: {{date:YYYY-MM-DD}}
+session_date: "{{date:YYYY-MM-DD}}"
 client: claude-code
 ---

@@ -1,8 +1,8 @@
 ---
 type: working-memory
 status: active
-created: {{date:YYYY-MM-DDTHH:mm}}
-updated: {{date:YYYY-MM-DDTHH:mm}}
+created: "{{date:YYYY-MM-DDTHH:mm}}"
+updated: "{{date:YYYY-MM-DDTHH:mm}}"
 tags: [agent, working-memory]
 agent_written: true
 source_notes: []
@@ -1,12 +1,12 @@
 ---
 type: decision
 status: complete
-created: {{date:YYYY-MM-DD}}
-updated: {{date:YYYY-MM-DD}}
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
 tags: [decision]
 agent_written: true
 source_notes: []
-decision_date: {{date:YYYY-MM-DD}}
+decision_date: "{{date:YYYY-MM-DD}}"
 impact: medium
 ---

@@ -1,8 +1,8 @@
 ---
 type: daily-note
 status: active
-created: {{date:YYYY-MM-DD}}
-updated: {{date:YYYY-MM-DD}}
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
 tags: [daily, journal]
 agent_written: false
 source_notes: []
@@ -1,8 +1,8 @@
 ---
 type: review
 status: active
-created: {{date:gggg-[W]WW}}
-updated: {{date:gggg-[W]WW}}
+created: "{{date:gggg-[W]WW}}"
+updated: "{{date:gggg-[W]WW}}"
 tags: [review, weekly]
 agent_written: true
 source_notes: []
@@ -1,8 +1,8 @@
 ---
 type: project
 status: active
-created: {{date:YYYY-MM-DD}}
-updated: {{date:YYYY-MM-DD}}
+created: "{{date:YYYY-MM-DD}}"
+updated: "{{date:YYYY-MM-DD}}"
 tags: [project]
 agent_written: false
 source_notes: []