how-this-works

How this KB works §

This borrows the agent-first knowledge-base method used for a code repository. Most of it transfers. Four things do not, because the subject is different.

The inversion §

In a code repository the KB is instrumental. The code is the source of truth, the KB records what code cannot express, and sync-on-write is funded by code tasks: you finish a feature, you update the docs it invalidated.

Here the knowledge is the end. The vault is not a system the KB documents in order to help build something else — the notes are the product. That changes four things.

1. There is no “the code wins” rule §

In the code KB, when a doc and the code disagree, the code wins and the doc needs a sync. Here there is no equivalent authority to defer to for the content of the garden, because this KB does not describe that content and must not start.

What this KB describes is the machinery: quartz.config.ts, the Quartz plugins, .obsidian/ configuration, the Templates, the CLI. For those, the rule holds normally — the config wins, and a doc that disagrees needs a sync.

The practical line: if a claim would still be true after the user deleted every note and kept the repo, it belongs here. If it depends on what a note says, it does not.

2. Counts are the fastest-drifting claim §

The user writes in this vault continuously, and Obsidian Sync applies changes from other devices with no commit and no signal. So “325 public notes”, “48 Inbox notes”, “26 of 48 have no outbound links” are all true only at the moment they were measured.

Mark every count with a date, or write the command that recomputes it. Prefer the command. A count with a command next to it stays useful after it goes stale; a bare number becomes a quiet lie.

.claude/skills/garden-publish-check/scripts/publish_audit.py is the canonical recount for anything publish-related. Run it rather than trusting a number here.

3. sources points at machinery, never at notes §

sources exists to make drift-checking mechanical: list the paths a doc describes, then check commits against them. That works for quartz/plugins/filters/explicit.ts. It does not work for the vault content, for two reasons — the notes are not what these docs claim things about, and vault changes arrive through Sync without commits, so a git window would miss them anyway.

So: sources may list quartz.config.ts, quartz/plugins/**, digital-garden/.obsidian/*.json, digital-garden/Templates/. It should not list digital-garden/Notes/.

A doc whose subject is genuinely vault-wide shape (folder taxonomy, frontmatter conventions) can list digital-garden/ as a source, but its watermark then means only “the shape was checked”, never “the notes were read”.

4. Habit 1 fires on garden operations, not code commits §

Sync-on-write still funds the system, but the triggering event is different. There are no feature branches here. The moments that invalidate a doc are:

• a change to quartz.config.ts or a Quartz plugin
• a change to .obsidian/ config, or an Obsidian plugin update
• a bulk operation on the vault (a cleanup, a promotion, a frontmatter sweep)
• a new skill, or a change to one

After any of those: update the doc it invalidated, bump last_verified, and add a dated log in work.

What carries over unchanged §

• Indexes as decision tables. Every directory gets an index.md with a when-to-open line per file. Two hops from the root index to the right doc.
• description states answerable questions. Not “covers publishing” but “which notes go live, and why a missing key publishes one”.
• The labyrinth. Record rejected alternatives and dead ends. A decision without its rejected options is a prescription nobody can challenge.
• Watermark discipline. Never bump last_verified after spot-checking one claim — that hides every unreviewed change from all future checks. Do bump it when a check comes back clean. description + sources with no last_verified is an honest state.
• Autonomy asymmetry. Write freely in Claude/. Everywhere else in the vault, propose and wait. Do not commit or push the repo unless asked.

Doc types in use here §

Kept deliberately short. Add one when a doc genuinely does not fit.

Type	Lifecycle
index	Updated whenever its directory changes.
reference	Living. How the machinery works now. Must carry sources and be kept in sync.
log	Append-only, dated. What was done to the vault in a session, including what was skipped and what stayed unverified.

When to stop §

The garden is one person’s, low-churn, and small. Overrun looks like: a doc that restates CLAUDE.md, a domain directory holding one file, or a count nobody will recompute. Backlog those instead of writing them.