sidegraph 0.9.0__tar.gz → 0.10.0__tar.gz

{sidegraph-0.9.0 → sidegraph-0.10.0}/.agents/plugins/marketplace.json

@@ -8,7 +8,7 @@
         "source": "local",
         "path": "./plugin/sidegraph"
       },
-      "description": "Durable decision/lessons memory over your code graph — captured in-session, human-ratified, retrieved mistakes-first, surviving refactors."
+      "description": "Durable decision/lessons memory over your code graph — captured in-session, ratified before it is trusted, retrieved mistakes-first, surviving refactors."
     }
   ]
 }

{sidegraph-0.9.0 → sidegraph-0.10.0}/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     {
       "name": "sidegraph",
       "source": "./plugin/sidegraph",
-      "description": "Durable decision/lessons memory over your code graph — captured in-session, human-ratified, retrieved mistakes-first, surviving refactors.",
+      "description": "Durable decision/lessons memory over your code graph — captured in-session, ratified before it is trusted, retrieved mistakes-first, surviving refactors.",
       "homepage": "https://github.com/SantyagoSeaman/sidegraph"
     }
   ]

{sidegraph-0.9.0 → sidegraph-0.10.0}/CHANGELOG.md

@@ -7,6 +7,110 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.10.0] — 2026-10-04
+
+### Added
+
+- **Every MCP tool now carries annotations, so a host's auto-reviewer stops rejecting memory
+  reads.** In the field, Codex's auto-reviewer rejected 20 `get_task_context` calls, and each
+  one lost memory for that step: an unannotated tool takes the MCP defaults (destructive,
+  open-world), and the review's verdict then depends on the prompt. The seven tools that never
+  change a tracked file are read-only; the other 17 are non-destructive, closed-world local
+  writes. No tool sends anything off the machine and none deletes a record. A test runs the
+  read-only tools on a store where a lazy sync would adopt a moved symbol, and fails if one of
+  them changes a tracked file, so the annotation cannot drift from what the tool does. See the
+  [reference](docs/reference/mcp-tools.md#annotations) and the
+  [Codex page](docs/integrations/codex.md#the-auto-reviewer-and-memory-reads).
+- **The seed tools accept the argument names agents try, and every tool names its parameters in
+  an error.** `get_task_context`, `query_structure` and `query_decisions` accept `paths` (as
+  `files`) and `seeds`; each seed goes to `files` when it looks like a path and to `entities`
+  otherwise. `task` is refused with a line saying there is no free-text query. Any other
+  unknown argument, on any tool, is an error that names it and lists the tool's real parameters;
+  FastMCP's own error named the argument but not the parameters.
+
+### Changed
+
+- **`retrieve_decisions` no longer returns the whole store.** One call returned a full dump of
+  every visible decision: about 143,000 tokens on a store of 260 records, more than a host would
+  show, and in a field report most agents passed `include_superseded: true` and then either
+  printed the dump or filtered it by hand. The call now has two answers.
+  - With no narrowing filter it returns an **overview**: the total, counts by status and kind
+    (superseded and rejected records included, so the counts say that history exists), and the
+    newest records as compact rows (`id`, `kind`, `status`, `title`, `valid_from`).
+  - With a narrowing filter it returns **full records**, gotchas and lessons first and newest
+    first, cut at `limit` (default 25, at most 100) or `budget_chars` (default 24,000, at most
+    60,000), whichever comes first. A `hint` says what cut the list, or why it is empty.
+  - The filters are new arguments, and they combine with AND: `status` and `kind` (a string or a
+    list), `files`, `query` (every word must occur in the record's text) and `ids` (exact record
+    ids, superseded ones too). `include_superseded` keeps its meaning: it widens the overview's
+    `newest` and a filtered call that has no `status`.
+  - `files` are read the way `get_task_context` reads them: a basename, a suffix, a directory or
+    a letter-case slip works. `unresolved_files` lists, for each path nothing could read (at most
+    ten, with `unresolved_omitted` counting the rest), why (`ambiguous`, `directory-too-large`,
+    `not-in-graph` or `no-graph`) and the candidates to pass instead.
+  - **The return type changed from a list to a JSON object, sent once as a single text block
+    with no structured copy**, so `budget_chars` is the real cost on every host. A client that
+    read the list now reads `decisions` of a filtered answer. The proposal policy is unchanged
+    and applies to every shape.
+  - The `check-plan`, `explain-why`, `triage-drift` and `heal-anchors` skills now call it with a
+    filter, and a test fails if a skill calls it without one. See the
+    [reference](docs/reference/mcp-tools.md#retrieve_decisions).
+
+### Fixed
+
+- **A fault converting a reviewed item in `sidegraph-bootstrap` now prints the RESUME line.** The
+  conversion of each reviewed item, and the check that its ref still matches the candidate,
+  ran outside the per-item error handling. A fault there, after an earlier item had been
+  written, left `apply_review` without a report: an `AssertionError` ended the run as a
+  traceback, a `ValueError` was reported as a failure before anything was written, and neither
+  printed `RESUME`, though canonical files were already on disk. The fault now takes the path a
+  write error takes: the run stops, reports `partial-recoverable` with the durable candidates and
+  the failing ref, and prints the resume command. A fault on the first item, before anything is
+  written, now exits 2 with `STORE incomplete`, the failing ref and the resume command, where a
+  `ValueError` used to exit 1 with an `ERROR` line; the terminal shows the failing ref and not the
+  reason.
+- **`sidegraph-import --dry-run` now says what auto-ratification would do.** Both import paths
+  decided auto-ratification only after a real write, so under a non-`manual`
+  `SIDEGRAPH_RATIFY_POLICY` a dry run could not show which records a real run would land
+  accepted without a human: on one fixture it reported 0 where the real run auto-ratified 2. The
+  dry run now runs the same eligibility gate on the record the write would produce and reports
+  the result in a new `would_auto_ratify` field on `ImportReport` and `DocImportReport`, and as
+  `auto_ratify_eligible` on each dry-run item. `auto_ratified` keeps its meaning, transitions
+  that actually happened, so it stays 0 in a dry run.
+  - **Behaviour change:** under a non-`manual` policy the summary line gains `would
+    auto-ratify M` before `(skipped:` and an eligible item line ends with ` [auto]`. Under
+    `manual` both are unchanged. A dry run still never carries the real run's `auto-ratified K`.
+  - The count is eligibility, not a guarantee: a real run's transition can still fail, for
+    example on a race or a refused cascade.
+  - A key repeated within one run no longer counts twice in the dry run. Two rationales with the
+    same title in one file count once. A document ref met more than once (one file named twice, a
+    directory plus a file inside it, or a live and an archived copy that a profile maps to one
+    ref) is classified against the records the earlier copies would have left there, as the real
+    run sees them: an identical repeat is skipped, a differing one supersedes, and a copy after a
+    `rejected` first copy is a fresh write. Two rare shapes can still differ in the
+    `superseded`/`skipped` split, not in the eligibility count where checked: a ref met three
+    times with the first content returning, under an auto policy, and a repeat with no anchor of
+    its own.
+- **`find_entity` no longer calls a dangling record a decision.** Each binding was labelled
+  `fact` if a fact lookup found it and `decision` otherwise, so a binding whose record exists in
+  neither table (a record file removed by hand, or lost in a merge) came back as a decision that
+  `get_decision` could not fetch, and each binding cost a query of its own. The types of all of an
+  entity's bindings now come from one read of the index, and a binding with no record reports
+  `record_type: "unknown"`. The value is additive: a client that handles `decision` and `fact`
+  is unaffected. `get_entity_history` uses the same read and still skips such a binding. See the
+  [reference](docs/reference/mcp-tools.md#find_entity).
+- **A document status like `should not be rejected` no longer lands `rejected`.** The check for
+  a turned-down status saw a negation only as `not` and one space directly before the word, so
+  `should not be rejected`, `not  rejected` (two spaces), `never rejected` and `isn't rejected`
+  all read as rejections, and a false `rejected` lands closed and invisible to retrieval. A
+  negation is now `not`, `never` or a word ending `n't` within the three words before the word in
+  the same clause. A clause ends at `,` `;` `.` `:`, a pipe, a slash, an em or en dash, or a spaced
+  hyphen or `->`, so `not reviewed, rejected`, `Not accepted — rejected` and `Won't do / rejected`
+  still read as rejections, as does `not rejected, rejected`. A conjunction does not end a
+  clause: `Not adopted and rejected` reads as negated, and lands accepted unless `--propose` or
+  a draft marker sends it to the ratification queue. See the
+  [reference](docs/reference/cli.md#sidegraph-import).
+
 ## [0.9.0] — 2026-10-04
 
 ### Added

{sidegraph-0.9.0 → sidegraph-0.10.0}/CLAUDE.md

@@ -13,7 +13,7 @@ task-aware retrieval + decision memory riding on the engine's entity graph.
 continuing participant in the project. A core feature must preserve, organize, or deliver
 accumulated project understanding. Document search by itself is not the product.
 
-Sidegraph is pre-1.0 (v0.9.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.10.0) — the full loop (capture, ratification, mistakes-first
 retrieval, refactor-surviving re-anchoring, semantic docs layer, mind-model domains, and the
 facts evidence layer) ships and is exercised end-to-end, but interfaces may still move before
 a stable release. See

{sidegraph-0.9.0 → sidegraph-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.9.0
+Version: 0.10.0
 Summary: Own the memory, rent the graph — a durable decision/lessons layer as a sidecar over a code-graph engine.
 Project-URL: Homepage, https://github.com/SantyagoSeaman/sidegraph
 Project-URL: Repository, https://github.com/SantyagoSeaman/sidegraph
@@ -82,7 +82,9 @@ only ever reads `graph.json`, so the plain install above is all it needs.
 
 ```bash
 # 3. Install the CLIs + MCP server, then bootstrap the store in your repo
-#    (creates .sidegraph/, prints setup instructions)
+#    (creates .sidegraph/, prints setup instructions). In a terminal it also asks
+#    whether to install a git hook that rebuilds the code graph after each commit,
+#    merge and branch switch; `sidegraph-init --remove-hooks` takes it out again
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
@@ -172,6 +174,10 @@ projects the full store, history included, into an OKF v0.1 bundle any OKF consu
  Read / Edit / Bash read ──▶ the file's records delivered in the call (once per file per agent)
 ```
 
+Subagents get the memory too: on Claude Code a hook appends the decisions for the files a
+subagent's brief names to that brief, and on Claude Code and Codex another hook tells each new
+subagent that decision memory exists and how to ask it.
+
 Two layers age differently: the **structure** layer (the code graph — entities,
 dependencies, communities: *the what*) and the **decision** layer on top (*the why*). The
 graph is disposable — the engine regenerates it from source at any moment. The memory must
@@ -215,7 +221,7 @@ dropping a decision carries its still-pending facts along in the same verdict. D
 | `add_decision` / `supersede_decision` | Append / reverse a decision (nothing is ever deleted) |
 | `add_fact` / `supersede_fact` | Append / falsify a non-derivable fact — evidence for a decision, or standalone |
 | `find_entity` / `get_entity_history` | Which decisions *and facts* touch this entity, and how they evolved |
-| `retrieve_decisions` / `list_facts` | List current decisions / current facts |
+| `retrieve_decisions` / `list_facts` | Filter decisions (bounded) / list current facts |
 | `propose_decisions` / `propose_domains` / `add_domain` | Draft a decision (plus attached or standalone facts) or name a domain, from a session or by hand |
 | `supersede_domain` | Lineage-correct rename/re-scope of a domain: closes the old, writes a `proposed` successor |
 | `list_proposed` / `ratify` | The human gate (see `SIDEGRAPH_RATIFY_POLICY` in the configuration reference): review pending decisions, facts, *and* domains, accept/drop (a decision's verdict cascades to its still-pending facts) |
@@ -247,16 +253,22 @@ retrieval a richer graph to anchor against. Walkthrough:
 
 - **Everything is local.** Sidegraph reads your repo and the engine's `graph.json`
   (strictly read-only) and writes small human-readable JSON records inside your repo,
-  plus a local, gitignored index it can always rebuild. **Nothing leaves your machine** —
+  plus a local, gitignored index it can always rebuild. Two things sit outside the store:
+  the git hooks that `sidegraph-init` can install to keep the graph fresh (a helper and
+  three hooks under `.git/hooks/`) and one cache file, `sidegraph/launch-commit`, under
+  `${XDG_CACHE_HOME:-~/.cache}`. [SECURITY.md](SECURITY.md) lists every write.
+  **Nothing leaves your machine** —
   no network calls, no remote telemetry, no account. Sidegraph does keep local usage
   diagnostics in that gitignored index (which stored memory was shown, and which files a
   session touched afterwards) so you can see which memory was shown and which files
   those sessions then touched; they never travel, and `SIDEGRAPH_TELEMETRY=off` disables them.
 - **Secrets don't enter memory.** Proposed decisions and facts pass redaction before they
-  are stored. A ratification gate controls what the agent's drafts can persist: human for
-  `adr`/`constraint` decisions and domains always, and, if you answer yes to `sidegraph-init`'s
-  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), an auto-ratification stamp for lessons,
-  gotchas, and standalone facts instead of a person's review.
+  are stored. A ratification gate controls which of the agent's drafts become trusted
+  memory. Under the default `manual` policy a person ratifies them. A proposal is stored first
+  and waits as `proposed` until then. If you answer yes to `sidegraph-init`'s
+  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), eligible records ratify themselves
+  at write time with a stamp that says so: lessons, gotchas, and standalone facts under
+  `auto-low-risk`, and also ADRs, constraints, and domains under `auto-all`.
 - **Nothing is silently rewritten.** The store is append-only; every change of mind is
   recorded as a supersession with its reason.
 
@@ -269,7 +281,8 @@ The engine is optional at runtime: without a graph, records anchor to file paths
 domains and retrieval still works, but symbol-level anchors, communities, and moved-code
 resolution need it (see the [operations reference](docs/reference/operations.md#the-graph-dependency-stated-plainly)).
 Everything the engine produces is derived and regenerated on every rebuild; everything
-Sidegraph stores is deliberate, ratified, and permanent. **Own the memory, rent the graph.**
+Sidegraph stores is deliberate and permanent, and it is trusted only once ratified (by a
+person, or by the opt-in policy). **Own the memory, rent the graph.**
 
 ## Status
 

{sidegraph-0.9.0 → sidegraph-0.10.0}/README.md

@@ -52,7 +52,9 @@ only ever reads `graph.json`, so the plain install above is all it needs.
 
 ```bash
 # 3. Install the CLIs + MCP server, then bootstrap the store in your repo
-#    (creates .sidegraph/, prints setup instructions)
+#    (creates .sidegraph/, prints setup instructions). In a terminal it also asks
+#    whether to install a git hook that rebuilds the code graph after each commit,
+#    merge and branch switch; `sidegraph-init --remove-hooks` takes it out again
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
@@ -142,6 +144,10 @@ projects the full store, history included, into an OKF v0.1 bundle any OKF consu
  Read / Edit / Bash read ──▶ the file's records delivered in the call (once per file per agent)
 ```
 
+Subagents get the memory too: on Claude Code a hook appends the decisions for the files a
+subagent's brief names to that brief, and on Claude Code and Codex another hook tells each new
+subagent that decision memory exists and how to ask it.
+
 Two layers age differently: the **structure** layer (the code graph — entities,
 dependencies, communities: *the what*) and the **decision** layer on top (*the why*). The
 graph is disposable — the engine regenerates it from source at any moment. The memory must
@@ -185,7 +191,7 @@ dropping a decision carries its still-pending facts along in the same verdict. D
 | `add_decision` / `supersede_decision` | Append / reverse a decision (nothing is ever deleted) |
 | `add_fact` / `supersede_fact` | Append / falsify a non-derivable fact — evidence for a decision, or standalone |
 | `find_entity` / `get_entity_history` | Which decisions *and facts* touch this entity, and how they evolved |
-| `retrieve_decisions` / `list_facts` | List current decisions / current facts |
+| `retrieve_decisions` / `list_facts` | Filter decisions (bounded) / list current facts |
 | `propose_decisions` / `propose_domains` / `add_domain` | Draft a decision (plus attached or standalone facts) or name a domain, from a session or by hand |
 | `supersede_domain` | Lineage-correct rename/re-scope of a domain: closes the old, writes a `proposed` successor |
 | `list_proposed` / `ratify` | The human gate (see `SIDEGRAPH_RATIFY_POLICY` in the configuration reference): review pending decisions, facts, *and* domains, accept/drop (a decision's verdict cascades to its still-pending facts) |
@@ -217,16 +223,22 @@ retrieval a richer graph to anchor against. Walkthrough:
 
 - **Everything is local.** Sidegraph reads your repo and the engine's `graph.json`
   (strictly read-only) and writes small human-readable JSON records inside your repo,
-  plus a local, gitignored index it can always rebuild. **Nothing leaves your machine** —
+  plus a local, gitignored index it can always rebuild. Two things sit outside the store:
+  the git hooks that `sidegraph-init` can install to keep the graph fresh (a helper and
+  three hooks under `.git/hooks/`) and one cache file, `sidegraph/launch-commit`, under
+  `${XDG_CACHE_HOME:-~/.cache}`. [SECURITY.md](SECURITY.md) lists every write.
+  **Nothing leaves your machine** —
   no network calls, no remote telemetry, no account. Sidegraph does keep local usage
   diagnostics in that gitignored index (which stored memory was shown, and which files a
   session touched afterwards) so you can see which memory was shown and which files
   those sessions then touched; they never travel, and `SIDEGRAPH_TELEMETRY=off` disables them.
 - **Secrets don't enter memory.** Proposed decisions and facts pass redaction before they
-  are stored. A ratification gate controls what the agent's drafts can persist: human for
-  `adr`/`constraint` decisions and domains always, and, if you answer yes to `sidegraph-init`'s
-  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), an auto-ratification stamp for lessons,
-  gotchas, and standalone facts instead of a person's review.
+  are stored. A ratification gate controls which of the agent's drafts become trusted
+  memory. Under the default `manual` policy a person ratifies them. A proposal is stored first
+  and waits as `proposed` until then. If you answer yes to `sidegraph-init`'s
+  question (or set `SIDEGRAPH_RATIFY_POLICY` yourself), eligible records ratify themselves
+  at write time with a stamp that says so: lessons, gotchas, and standalone facts under
+  `auto-low-risk`, and also ADRs, constraints, and domains under `auto-all`.
 - **Nothing is silently rewritten.** The store is append-only; every change of mind is
   recorded as a supersession with its reason.
 
@@ -239,7 +251,8 @@ The engine is optional at runtime: without a graph, records anchor to file paths
 domains and retrieval still works, but symbol-level anchors, communities, and moved-code
 resolution need it (see the [operations reference](docs/reference/operations.md#the-graph-dependency-stated-plainly)).
 Everything the engine produces is derived and regenerated on every rebuild; everything
-Sidegraph stores is deliberate, ratified, and permanent. **Own the memory, rent the graph.**
+Sidegraph stores is deliberate and permanent, and it is trusted only once ratified (by a
+person, or by the opt-in policy). **Own the memory, rent the graph.**
 
 ## Status
 

{sidegraph-0.9.0 → sidegraph-0.10.0}/SECURITY.md

@@ -25,10 +25,21 @@ Sidegraph is a local-only tool. Its entire data surface:
   the visualization, OKF export and bootstrap-report commands write to the output paths you
   give them; and the optional `sidegraph-prepare-commit-msg` git hook, once you install it,
   adds commented decision trailers to the commit message file git hands it
-  (normally `.git/COMMIT_EDITMSG`). Beyond those, the only filesystem writes are the standard config
-  snippets you install yourself (`.mcp.json`, hook entries) — Sidegraph touches nothing
-  else. See [`docs/reference/store-format.md`](docs/reference/store-format.md) for the full
-  layout.
+  (normally `.git/COMMIT_EDITMSG`). Three more writes sit outside the repository's own
+  files. `sidegraph-init --hooks` (or a yes to its refresh question) writes a helper script
+  and a marked block in three git hooks (`post-commit`, `post-merge`, `post-checkout`) under
+  `.git/hooks/`. When `core.hooksPath` is set, `sidegraph-init` writes only the helper (to
+  `.git/hooks/`) and prints the lines to add to your hooks by hand. While it runs, the helper
+  also keeps a lock, a flag file and a log in the git directory. `sidegraph-init --no-hooks`
+  writes the git config key `sidegraph.graphRefresh` to the repository's own config, and
+  `sidegraph-init --remove-hooks` takes the blocks, the helper and that key out again. The
+  SessionStart hook writes one 40-character commit id to
+  `${XDG_CACHE_HOME:-~/.cache}/sidegraph/launch-commit`, and only when the running package was
+  installed from the canonical `git+https://github.com/SantyagoSeaman/sidegraph.git@main`. That
+  covers the plugin and the manual `uvx --from …@main` recipe. A PyPI, tag, SHA or editable
+  install never writes it. Beyond those, the only filesystem writes are the standard config
+  snippets you install yourself (`.mcp.json`, hook entries). See
+  [`docs/reference/store-format.md`](docs/reference/store-format.md) for the full layout.
 - **Network:** none. No remote telemetry, no phone-home, nothing leaves your machine. Local
   retrieval telemetry is recorded in the gitignored `index.db` by default (which records
   were shown and which files were touched, never uploaded); set `SIDEGRAPH_TELEMETRY=off` to

{sidegraph-0.9.0 → sidegraph-0.10.0}/docs/concepts/mind-model.md

@@ -105,7 +105,7 @@ write below — the three raw authoring paths underneath it are:
    asked to) names a domain directly, optionally nesting it under a `parent_slug`.
 
 All three land `status=proposed`. **Every path passes through the same ratification gate** —
-the unified `ratify` MCP tool (`ratify_decisions` is a deprecated alias, kept for one release)
+the unified `ratify` MCP tool (`ratify_decisions` is a deprecated alias, still kept)
 and the `sidegraph-ratify` CLI, which list and accept/drop decisions *and* domains side by
 side. By default no path bypasses human review, including bootstrap: a fresh repo can
 propose dozens of domains from its community structure in one command, but nothing is named

{sidegraph-0.9.0 → sidegraph-0.10.0}/docs/concepts/retrieval.md

@@ -15,7 +15,8 @@ whether the store has any accepted domains yet:
 - **`render_toc(cache)`** — the real, domain-named table of contents (activated the moment the
   first domain is ratified — no sync required, see [below](#when-the-toc-goes-live)): one line
   per accepted domain (title, one-line summary truncated to 100 characters, mistake count,
-  subdomain count when non-zero), then initiatives, then global mistakes. This is what "the
+  subdomain count when non-zero), then initiatives, then global mistakes, then any proposed
+  global mistakes under `## Unratified proposals`. This is what "the
   mind model comes alive" means in practice. The per-domain mistake count is what
   [`drill_down`](#drill_downdomain_slug--the-axis-1-operation) would serve for that domain:
   the accepted `gotcha`/`lesson`/`constraint` decisions in the union of those tagged to the
@@ -25,8 +26,12 @@ whether the store has any accepted domains yet:
   (the ratify and capture paths) leaves out the document branch until the next sync pass that
   has one.
 - **`top_tier_map(store, reader)`** — the legacy, nameless fallback: top communities by member
-  count (labeled only by god-node name), initiatives, global mistakes. Runs on demand (no
-  cache) whenever the store has zero accepted domains — a fresh repo, or one that hasn't
+  count (labeled only by god-node name), initiatives, global mistakes, then up to 10 other
+  accepted decisions under `## Recorded decisions`, up to 10 accepted facts under
+  `## Known facts`, and the proposals inside the surfacing window under
+  `## Unratified proposals`. The last three are what keep a store that has recorded its first
+  decisions and named no domain yet from showing an agent only engine communities. Runs on
+  demand (no cache) whenever the store has zero accepted domains — a fresh repo, or one that hasn't
   bootstrapped/ratified any domains yet, sees exactly the same output as before this layer
   existed.
 
@@ -38,8 +43,14 @@ covers every search surface, not just `Read`/`Grep`: *"When you need to find or
 code in this project, call `get_task_context(files=[…])` with repo-relative paths before any
 grep or file search — decisions, gotchas and a domain map are indexed here. Before a
 non-trivial change, run the sidegraph check-plan skill if it is available. If the tool is
-listed only by name, load it first."* Both degrade gracefully — an empty
-store still gets the instruction plus just the header. The `SessionStart` hook itself never
+listed only by name, load it first."* A `Sidegraph X.Y.Z` line follows it, so a session
+that launched an old install says so in its own context. Both degrade gracefully — an empty
+store still gets the instruction, the version line and the header. After the map the hook
+appends the integrity checks' status lines (records awaiting ratification, code drift, a stale
+or missing graph, uncommitted store files and the rest), and sends a notice to the person for
+the problems that need one; the texts and the order are in the
+[hooks reference](../reference/hooks.md#sidegraph-session-start) and
+[troubleshooting](../guides/troubleshooting.md). The `SessionStart` hook itself never
 blocks startup: any failure, or a cache it can't parse, falls back to `top_tier_map` rather
 than crashing; any failure in *that* prints `{}` and exits 0.
 
@@ -105,7 +116,8 @@ path with a stray `./`, a wrong prefix or a bare file name, a directory, and a `
 with no file. Every rewrite is a guess and is named as one in the reply, the seeds that resolved
 as written come first, and a guess that could mean several things is listed and never read (see
 [`get_task_context`](../reference/mcp-tools.md#seeds-are-read-tolerantly)). The rule is still
-exact matching, never similarity.
+exact matching, never similarity. `query_structure` and `query_decisions` have no such ladder:
+they take a seed exactly as written, so a loosely spelled path finds nothing there.
 
 A seed reaches the store's entities two ways, and both count: a named seed that matches a
 stored anchor name is that entity directly (whatever the graph calls the node, so a stored
@@ -297,9 +309,9 @@ and the old truncation behavior is unchanged, byte-for-byte.
 `query_structure(seeds, budget_chars)` and `query_decisions(seeds, budget_chars)` are
 `get_task_context` split down the middle — the structural-map half and the decision-memory half
 (mistakes, decisions, facts, related), exposed as their own MCP tools for a cheap follow-up once the
-caller already has one half and just needs the other. Both reuse the exact same seed-resolution
-and ranking code as `get_task_context` — they're thinner call surfaces, not a different
-algorithm. `query_structure` needs a reader (no graph, no structural map — it says so rather
+caller already has one half and just needs the other. Both reuse the same seed-resolution
+and ranking code as `get_task_context`, but not its [tolerant seed reading](#seeds): they match
+seeds exactly as written. They're thinner call surfaces, not a different algorithm. `query_structure` needs a reader (no graph, no structural map — it says so rather
 than crashing); `query_decisions` degrades like `get_task_context` always has: named-seed
 resolution needs a reader, but `scope: global` decisions still surface without one.
 
@@ -352,8 +364,35 @@ not a normalized repo-relative path to a file (check it). In a linked worktree t
 main checkout's graph, a file that exists only on the branch gets one sentence saying the graph
 does not hold it, and the rebuild advice for any other file names the main checkout. With no graph
 at all and at least one seed, a `## No code graph` block names the path looked at and says to build
-it (or, when the graph is there and cannot be read, that it is not readable). `render()` itself
-does not produce either block.
+it (or, when the graph is there and cannot be read, that it is not readable). A file seed with
+no current record of its own, and anchored files near it, gets a `## Nearest anchored` sentence
+that names those files (under `## Why this is empty` when the answer is empty). When the answer
+holds no decision memory at all, the records of the named files follow under
+`## Nearest anchored records (not anchored to your files)`; see
+[the nearest anchored records](../reference/mcp-tools.md#the-nearest-anchored-records).
+`render()` itself produces none of these blocks.
+
+## Records that arrive without a query
+
+An agent does not always call `get_task_context`, and a subagent starts without the session's
+context. So the read path has three more channels, all wired as hooks and all reading the
+store's index directly (see [hooks](../reference/hooks.md)):
+
+- **At the point of reading.** When a `Read`, `Edit`, `Write` or `Grep` call, or a Bash `sed`,
+  `grep`, `rg` or `cat` line, names a file that decisions are anchored to, the `PreToolUse` hook
+  hands the agent the top decisions for that file in the same tool call, mistakes first. Each file
+  is delivered once per agent. `SIDEGRAPH_GREP_NUDGE=off` stops it.
+- **In a subagent's brief.** On an `Agent` call, the hook reads the files the brief names, and
+  the files named in a plan or notes document it names, and appends the decisions anchored to them
+  to the brief. The subagent sees the block in its first message; the parent's transcript keeps
+  the prompt it wrote. `SIDEGRAPH_AGENT_BRIEF=off` stops it.
+- **At the start of a subagent.** The `SubagentStart` hook tells the new subagent that decision
+  memory exists, how to ask it, and how many decisions, files and mistakes it holds. It carries no
+  records. `SIDEGRAPH_SUBAGENT_BRIEF=off` stops it.
+
+The first two deliver decisions only: their index reader has no fact query, so facts reach an
+agent through `get_task_context`. The first two are Claude Code only. `SubagentStart` runs on Claude Code and on Codex. The day to
+day view is in [retrieval in sessions](../guides/retrieval-in-sessions.md#memory-without-asking).
 
 ## See also
 

{sidegraph-0.9.0 → sidegraph-0.10.0}/docs/getting-started/claude-code-setup.md

@@ -207,8 +207,9 @@ The env vars are inlined into the command because Claude Code hook entries have
   ids, and a line naming `get_task_context` for the rest. Each file arrives once per agent, at
   most three files per call and ten per agent, and the session's own agent and every subagent it
   starts count separately; a file with no records prints nothing. Bash is wired as four entries
-  (`if` is `Bash(sed *)`, `Bash(grep *)`, `Bash(rg *)`, `Bash(cat *)`) with the same command, and
-  needs Claude Code 2.1.89 for correct matching. Set `SIDEGRAPH_GREP_NUDGE=off` (alongside the
+  (`if` is `Bash(sed *)`, `Bash(grep *)`, `Bash(rg *)`, `Bash(cat *)`) with the same command.
+  The `if` field exists from Claude Code 2.1.85, and matching on compound command lines is
+  correct from 2.1.89, so use 2.1.89 or later. Set `SIDEGRAPH_GREP_NUDGE=off` (alongside the
   other env vars in the command) to turn off all of it. See
   [`reference/hooks.md`](../reference/hooks.md#sidegraph-pre-tool-use).
 - The `Agent|Task` group runs that same command when the agent spawns a subagent. It appends the
@@ -238,5 +239,17 @@ start (a stub if the store is empty — that's expected). Then follow the
 
 ## Reset / cleanup
 
-Everything Sidegraph owns in the target repo is `.sidegraph/`; everything Graphify owns is
-`graphify-out/`. Delete both to start over — your source files are never touched.
+The store is `.sidegraph/`; everything Graphify owns is `graphify-out/`. Delete both to
+start over. Your source files are never touched. Sidegraph can also leave a few things
+outside those two directories:
+
+- If you installed the graph refresh hook (`sidegraph-init --hooks`, or a yes to its
+  question), run `sidegraph-init --remove-hooks` first. Deleting the directories does not
+  remove the helper and the three hook blocks in `.git/hooks/`.
+- `sidegraph-init --no-hooks` records the git config key `sidegraph.graphRefresh`.
+  `--remove-hooks` clears it.
+- `sidegraph-init` may have written `SIDEGRAPH_RATIFY_POLICY` into `.claude/settings.json`.
+- The SessionStart hook keeps `${XDG_CACHE_HOME:-~/.cache}/sidegraph/launch-commit`, one
+  file shared by every project on the machine.
+
+[SECURITY.md](../../SECURITY.md) lists every write.

{sidegraph-0.9.0 → sidegraph-0.10.0}/docs/getting-started/codex-setup.md

@@ -15,15 +15,18 @@ and AGENTS.md registered separately, for fine control or a source checkout).
 
 ## Option A: plugin (recommended)
 
-Inside a Codex CLI session, in that repo:
+From a terminal, in that repo:
 
 The commands below follow the current development branch. For durable environments, see
 [how to pin mutable development references](installation.md#mutable-development-references).
 
+```bash
+codex plugin marketplace add SantyagoSeaman/sidegraph
+codex plugin add sidegraph@sidegraph
 ```
-/plugin marketplace add SantyagoSeaman/sidegraph
-/plugin install sidegraph@sidegraph
-```
+
+These are shell commands, not slash commands typed inside a Codex session. The marketplace
+source takes `owner/repo[@ref]`, a local path or a Git URL.
 
 Installs the MCP server, the `SessionStart`/`Stop`/`SubagentStart` hooks, and all 12 skills in one step,
 pointed at `SIDEGRAPH_DIR=.sidegraph`/`SIDEGRAPH_GRAPH=graphify-out/graph.json` by default.

{sidegraph-0.9.0 → sidegraph-0.10.0}/docs/getting-started/installation.md

@@ -38,13 +38,20 @@ name, so `--from sidegraph` is required (a bare `uvx sidegraph-mcp` will not res
 
 ### Option B — host plugin (recommended for Claude Code and Codex)
 
-Inside an interactive host session, in the repo you want memory over:
+In the repo you want memory over. In Claude Code, inside an interactive session:
 
 ```
 /plugin marketplace add SantyagoSeaman/sidegraph
 /plugin install sidegraph@sidegraph
 ```
 
+In Codex, from a terminal:
+
+```bash
+codex plugin marketplace add SantyagoSeaman/sidegraph
+codex plugin add sidegraph@sidegraph
+```
+
 The Claude Code host installs the MCP server and all four hooks (`SessionStart`, `Stop`,
 `PreToolUse`, `SubagentStart`). Codex installs the MCP server, `SessionStart`/`Stop`/
 `SubagentStart`, and the bundled skills;
@@ -127,7 +134,7 @@ setup, scripted/CI use, and the two deliberately human-run jobs (`sidegraph-impo
 | `sidegraph-pre-tool-use` | `PreToolUse` hook — hands the agent the records anchored to a file when it reads or edits it (`Read`, `Grep`, `Edit`, `Write`, and `sed`/`grep`/`rg`/`cat` in Bash). |
 | `sidegraph-subagent-start` | `SubagentStart` hook — tells a starting subagent that decision memory exists and how to ask it. |
 | `sidegraph-bootstrap` | Guided CLI — scan one of six supported ADR/spec profiles, preview and review candidates, write only after confirmation, verify anchors/host integration, and prove production retrieval. |
-| `sidegraph-init` | CLI — bootstrap `.sidegraph/` in a repo: create the store, check for the graph, print the plugin install path (and the no-plugin `claude mcp add` alternative). |
+| `sidegraph-init` | CLI — bootstrap `.sidegraph/` in a repo: create the store, check for the graph, ask (in a terminal) whether to install the git hook that keeps the graph fresh (`--hooks`, `--no-hooks`, `--remove-hooks`), print the plugin install path (and the no-plugin `claude mcp add` alternative). |
 | `sidegraph-ratify` | CLI — review/accept/drop proposed decisions, facts, and domains. |
 | `sidegraph-sync` | CLI — re-anchor the store after a Graphify rebuild. |
 | `sidegraph-import` | CLI — bootstrap decisions from Graphify rationale nodes (code docstrings, or ADR/SAD prose after a semantic pass), or from existing ADR/spec markdown directly (`--docs`). |

{sidegraph-0.9.0 → sidegraph-0.10.0}/docs/getting-started/quickstart.md

@@ -17,18 +17,32 @@ sidegraph-init
 it. `sidegraph-init` creates the repo-committed `.sidegraph/` record directories and a
 gitignored derived `index.db`. Both commands are safe to run again.
 
+In a terminal, `sidegraph-init` also asks whether to keep the code graph fresh. Yes installs a
+helper and a marked block in the `post-commit`, `post-merge` and `post-checkout` git hooks, which
+rebuild `graphify-out/graph.json` in the background. It never replaces a hook you already have.
+`sidegraph-init --hooks` answers yes without asking, `--no-hooks` answers no and stops the
+reminder, and `--remove-hooks` takes the hook out. Without a terminal it does not ask. See
+[keeping the graph fresh](../integrations/graphify.md#keeping-the-graph-fresh-git-hooks).
+
 If the repository already contains ADRs or supported flow specs, you can now switch to the
 [preview-first bootstrap](bootstrap.md). Otherwise continue here.
 
 ## 2. Connect your host
 
-The plugin is the recommended route for both Claude Code and Codex:
+The plugin is the recommended route for both Claude Code and Codex. In Claude Code:
 
 ```text
 /plugin marketplace add SantyagoSeaman/sidegraph
 /plugin install sidegraph@sidegraph
 ```
 
+In Codex, from a terminal:
+
+```bash
+codex plugin marketplace add SantyagoSeaman/sidegraph
+codex plugin add sidegraph@sidegraph
+```
+
 Start a new interactive session in the repository and approve the hook trust prompt. For a
 manual or source-checkout setup, use the host-specific page:
 [Claude Code](claude-code-setup.md) or [Codex](codex-setup.md).
@@ -71,8 +85,11 @@ git status --short
 sidegraph-verify
 ```
 
-Commit `.sidegraph/format`, `.sidegraph/.gitignore`, and the canonical JSON directories.
-Do not commit `.sidegraph/index.db`; it is derived and already ignored.
+Commit the whole `.sidegraph/` directory (`git add .sidegraph`). Its own `.gitignore` already
+leaves out `index.db` (the derived index, with its SQLite sidecar files) and `*.tmp` files, so what
+gets staged is what should travel: the `format` marker, `stamping_live_since`, `.gitignore` and the
+record directories. A store file left uncommitted for a day is reported by
+[`store-uncommitted`](../guides/troubleshooting.md#store-uncommitted).
 
 The loop is now working. Next, run the short
 [verification checklist](../guides/verifying-your-setup.md), then

{sidegraph-0.9.0 → sidegraph-0.10.0}/docs/guides/capturing-decisions.md

@@ -103,9 +103,11 @@ guide is the checklist for.
 
 ## 2. The automated path: Stop hook → distill → propose → ratify
 
-At the end of a session, the `Stop` hook fires a one-time nudge (see
+At the end of a session, the `Stop` hook fires a nudge (see
 [`reference/hooks.md`](../reference/hooks.md)) asking the agent to review the session for
-anything durable. The agent — not a separate LLM call, the same in-session agent — distills
+anything durable. The first nudge comes once the session looks substantial. A session that
+keeps working is nudged again, but only after at least 30 minutes and 10 new commits since the
+last nudge ([re-arm](../reference/hooks.md#re-arm-after-more-work)). The agent — not a separate LLM call, the same in-session agent — distills
 what happened into one or more **What / Why / Where / Learned** drafts and calls
 `propose_decisions(drafts=[...])`.
 
@@ -134,9 +136,9 @@ The write pipeline (`src/sidegraph/capture.py`) is deterministic — no LLM key
 4. **Anchor** best-effort via the same multi-anchor resolution as `add_decision` (orphaned
    leaf if no graph is present).
 
-Proposed decisions are **not silently invisible**: they do surface in `get_task_context` and
-`retrieve_decisions`, but every rendered line is tagged `[unratified]` so you always know a
-draft hasn't been reviewed yet (see
+Proposed decisions are **not silently invisible**: they do surface in `get_task_context`,
+where every rendered line is tagged `[unratified]`, and in `retrieve_decisions`, where every
+record carries its `status`, so you always know a draft hasn't been reviewed yet (see
 [`guides/retrieval-in-sessions.md`](retrieval-in-sessions.md)). Ratification is what removes
 that tag, not what makes the record appear.
 
@@ -148,8 +150,8 @@ Ratify without leaving the session. `SessionStart` tells you when something is w
 is two MCP tools: `list_proposed()` (human-readable render of everything pending) and
 `ratify(accept=[...], drop=[...])` — the unified tool that ratifies decisions *and* domains
 through one gate (see [mind model](../concepts/mind-model.md#domain-lifecycle)).
-`ratify_decisions(accept=[...], drop=[...])` still works but is a **deprecated alias**, kept
-for one release for existing callers only — prefer `ratify` in new code.
+`ratify_decisions(accept=[...], drop=[...])` still works but is a **deprecated alias** (since
+0.1.0, still kept) for existing callers only — prefer `ratify` in new code.
 
 - **Accept** flips `proposed → accepted`. The record now reads untagged everywhere.
 - **Drop** is append-only, like everything else in the store: it sets `valid_to` and flips