sidegraph 0.3.0__tar.gz → 0.4.0__tar.gz

{sidegraph-0.3.0 → sidegraph-0.4.0}/CHANGELOG.md

@@ -7,6 +7,45 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.4.0] — 2026-09-22
+
+### Fixed
+
+- **`supersede_decision` no longer half-applies when an anchor is invalid.** It wrote the
+  successor and closed the predecessor before checking the anchors, so an illegal `relation`
+  left an accepted successor with none, or only some, of its bindings: wholly or partly
+  invisible to task-seeded retrieval, and permanent in an append-only store. An anchor list
+  in which no anchor had a `name` reached the same state without any error.
+- **All five anchor-taking tools (`add_decision`, `supersede_decision`, `add_fact`,
+  `supersede_fact`, `add_anchors`) now validate the whole anchor list before their first
+  write.** An illegal `relation` is now rejected on every path; `supersede_decision` used to
+  accept it silently when no graph was present or the anchor had no `name`. Two cases are
+  newly rejected. The first is a `name` or `file_path` that is not a string, which used to
+  half-write on the fact paths and `add_anchors`, and on the decision paths whenever a graph
+  was present. The second is a non-empty list in which no anchor has a `name`, which used to
+  succeed while binding nothing. On `add_fact` it also bypassed the check that an anchorless
+  fact supports a live decision.
+
+## [0.3.1] — 2026-09-19
+
+### Fixed
+
+- **A session is now identified by its transcript, not by the host's `session_id`.** That
+  field does not mean the same thing on every host: Claude Code mints one per session (and
+  names the transcript after it), while Codex reports the *workspace* session — one id that
+  outlives a single session, survives `resume`, and is shared by every thread beneath it. On
+  Codex that put a whole store's history in one bucket (measured: 1928 of 1929 recorded events
+  in one live store, spanning 27 hours) and, worse, made every per-session guard fire once per
+  workspace instead of once per session: the second thread opened within a minute had its
+  context map dropped as a duplicate injection, and the first thread to finish spent the
+  capture nudge for all of them. All four hook sites now take the session from
+  `transcript_path`'s file name, falling back to `session_id` when no transcript is given.
+  On Claude Code this is the same string it already recorded — verified against a live store,
+  where all 74 recorded session ids are exactly transcript names — so nothing moves there.
+  The workspace session is kept beside it in the new `telemetry:session_group` meta key, as
+  the only link between sibling threads. See
+  [`docs/reference/hooks.md`](docs/reference/hooks.md#which-session-a-hook-is-in).
+
 ## [0.3.0] — 2026-09-19
 
 ### Added

{sidegraph-0.3.0 → sidegraph-0.4.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.3.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.4.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.3.0 → sidegraph-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.3.0
+Version: 0.4.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
@@ -63,11 +63,11 @@ Works cold: no existing ADRs required. No API key — the core loop is fully loc
 
 ```bash
 # 1. Install the graph engine and build a graph over your repo (code or markdown)
-uv tool install graphifyy                # double "y" — that's the PyPI name; CLI is `graphify`
+uv tool install "graphifyy==0.9.6"       # double "y" — that's the PyPI name; CLI is `graphify`
 cd /path/to/your/repo && graphify update .
 ```
 
-`[mcp]` is an **optional** extra on `graphifyy` (`uv tool install "graphifyy[mcp]"`) — it adds
+`[mcp]` is an **optional** extra on `graphifyy` (`uv tool install "graphifyy[mcp]==0.9.6"`) — it adds
 Graphify's *own* MCP server, a deeper structure-query layer over the same graph. Sidegraph
 only ever reads `graph.json`, so the plain install above is all it needs.
 
@@ -91,7 +91,8 @@ sidegraph-init
 
 4. **Name your domains** — turns the graph's communities into a described table of
    contents. Tell your agent *"name my domains"* (or run `/sidegraph:name-domains`) and
-   pick one of the 2–3 ready-made sets it proposes. CLI alternative for scripted/CI use:
+   review its proposed grouping (larger graphs may get 2–3 alternatives). CLI alternative
+   for scripted/CI use:
    `sidegraph-domains bootstrap` + `sidegraph-ratify` —
    see [naming your domains](docs/guides/naming-your-domains.md).
 

{sidegraph-0.3.0 → sidegraph-0.4.0}/README.md

@@ -35,11 +35,11 @@ Works cold: no existing ADRs required. No API key — the core loop is fully loc
 
 ```bash
 # 1. Install the graph engine and build a graph over your repo (code or markdown)
-uv tool install graphifyy                # double "y" — that's the PyPI name; CLI is `graphify`
+uv tool install "graphifyy==0.9.6"       # double "y" — that's the PyPI name; CLI is `graphify`
 cd /path/to/your/repo && graphify update .
 ```
 
-`[mcp]` is an **optional** extra on `graphifyy` (`uv tool install "graphifyy[mcp]"`) — it adds
+`[mcp]` is an **optional** extra on `graphifyy` (`uv tool install "graphifyy[mcp]==0.9.6"`) — it adds
 Graphify's *own* MCP server, a deeper structure-query layer over the same graph. Sidegraph
 only ever reads `graph.json`, so the plain install above is all it needs.
 
@@ -63,7 +63,8 @@ sidegraph-init
 
 4. **Name your domains** — turns the graph's communities into a described table of
    contents. Tell your agent *"name my domains"* (or run `/sidegraph:name-domains`) and
-   pick one of the 2–3 ready-made sets it proposes. CLI alternative for scripted/CI use:
+   review its proposed grouping (larger graphs may get 2–3 alternatives). CLI alternative
+   for scripted/CI use:
    `sidegraph-domains bootstrap` + `sidegraph-ratify` —
    see [naming your domains](docs/guides/naming-your-domains.md).
 

{sidegraph-0.3.0 → sidegraph-0.4.0}/SECURITY.md

@@ -16,9 +16,10 @@ Sidegraph is a local-only tool. Its entire data surface:
   (`.sidegraph/` by convention) — small, human-readable JSON record files meant to be
   committed to your repo, a derived and gitignored `index.db` (a local SQLite index
   rebuilt from those files for fast queries, never itself committed), a committed format
-  marker, and a `.gitignore` the store writes for itself. Opening a pre-0.4.0 single-file
-  store (`decisions.db`) triggers a one-time migration that renames the legacy file to
-  `decisions.db.migrated-backup` (kept, never deleted) alongside writing the new
+  marker, and a `.gitignore` the store writes for itself. Opening a legacy single-file
+  store (`decisions.db`, from before store schema 0.4.0) triggers a one-time migration
+  that renames the legacy file to `decisions.db.migrated-backup` (kept, never deleted)
+  alongside writing the new
   directory layout. Outside `.sidegraph/`, 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)

sidegraph-0.4.0/docs/README.md

@@ -0,0 +1,56 @@
+# Sidegraph documentation
+
+Sidegraph stores durable decisions and non-derivable facts beside the repository they
+describe. Start with the task you have now; [`llms.txt`](llms.txt) is the flat index for an
+agent.
+
+## Install and prove it works
+
+1. [Install Sidegraph and Graphify](getting-started/installation.md).
+2. Follow the [end-to-end quickstart](getting-started/quickstart.md).
+3. Use the recommended host path for [Claude Code](getting-started/claude-code-setup.md) or
+   [Codex](getting-started/codex-setup.md).
+4. Run the [four-case verification checklist](guides/verifying-your-setup.md).
+
+If the repository already has ADRs or specs, use the
+[preview-first bootstrap](getting-started/bootstrap.md) after installation.
+
+## Use it during normal work
+
+- [Retrieve context before editing](guides/retrieval-in-sessions.md).
+- [Capture decisions and supporting facts](guides/capturing-decisions.md).
+- [Name domains for the SessionStart table of contents](guides/naming-your-domains.md).
+- [Share and review the store as a team](guides/team-workflow.md).
+
+## Operate and maintain it
+
+- [Survive refactors and heal anchors](guides/surviving-refactors.md).
+- [Run CI and scheduled maintenance](guides/ci-cd-maintenance.md).
+- [Import decision-shaped documents](guides/semantic-docs.md).
+- [See runtime cost and operational boundaries](reference/operations.md).
+- [Cut a Sidegraph release](reference/releasing.md) (maintainers).
+
+The [pilot kit](pilot-kit/README.md) is an evaluation protocol for teams deciding whether to
+adopt Sidegraph. The engineering whitepaper is generated in the published snapshot at
+[`docs/whitepaper/index.md`](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/whitepaper/index.md);
+it is optional background on evidence, limits, and repository fit.
+
+## Understand the model
+
+- [Decision memory](concepts/decision-memory.md) — what belongs in the store.
+- [Mind model](concepts/mind-model.md) — domains, TOC, and drill-down.
+- [Data model](concepts/data-model.md) — persisted record shapes.
+- [Anchoring](concepts/anchoring.md) — how records stay attached to code and docs.
+- [Retrieval](concepts/retrieval.md) — ranking, trust quarantine, and budgets.
+
+## Look up an exact contract
+
+- [MCP tools](reference/mcp-tools.md)
+- [CLI](reference/cli.md)
+- [Hooks](reference/hooks.md)
+- [Configuration](reference/configuration.md)
+- [Store format](reference/store-format.md)
+- [Stability levels](reference/stability.md)
+- [Git bindings](reference/git-bindings.md)
+- Integrations: [Claude Code](integrations/claude-code.md),
+  [Codex](integrations/codex.md), [Graphify](integrations/graphify.md)

{sidegraph-0.3.0 → sidegraph-0.4.0}/docs/concepts/data-model.md

@@ -254,20 +254,24 @@ written; a garbled row raises and leaves the legacy file untouched) into the can
 file-per-record layout, stamped at the running code's current `SCHEMA_VERSION`; the legacy
 file is renamed to `<name>.migrated-backup` (never deleted) rather than removed. Both `0.2.0`
 and `0.3.0` sources go through this same export, not a stamp-only rewrite — see
-[store format: migration to 0.4.0](../reference/store-format.md#migration-to-040-from-02x-and-03x)
+[store format: migration to schema 0.4.0](../reference/store-format.md#migration-to-schema-040-from-schema-02x-and-03x)
 for the full four-step sequence. Any other mismatch (a version older than `0.2.0`, a
 newer/future version, or an unrecognized string) is a hard rejection: use a fresh store.
 
 ## `Initiative` — the Tier-0 grouping container
 
-Not a record type in its own right: a flat label a decision can be bound to at tier 0, so
-"everything decided during the retry-hardening work" is retrievable as a set even when
-those decisions touch unrelated code. Created implicitly at capture (a draft's
-`initiative` field, or the git branch name when one is not given).
+The high-level capture APIs use an initiative as a flat Tier-0 abstract entity named
+`initiative:<label>`. Passing a draft's `initiative` field creates that entity and binding;
+omitting it creates neither. Capture may derive the label from a branch before it reaches
+this step, but the storage layer does not do so implicitly.
+
+The `Initiative` model below is a separate low-level persisted record supported by
+`Store.upsert_initiative`. Current MCP capture paths do not create one, so do not expect an
+`initiatives/<id>.json` file merely because a decision has an `initiative:*` binding.
 
 | Field | Type | Meaning |
 |---|---|---|
 | `id` | ULID | Record identity. |
 | `name` | str | The label as written at capture — a branch name or a short phrase. |
 | `description` | str \| `null` | Optional one-liner; usually absent for branch-derived initiatives. |
-| `tags` | list[str] | Free-text tags, slugified into `tag:<slug>` entities like a decision's own. |
+| `tags` | list[str] | Stored strings on the low-level record; `upsert_initiative` does not slugify them or create `tag:*` entities. |

{sidegraph-0.3.0 → sidegraph-0.4.0}/docs/concepts/mind-model.md

@@ -187,7 +187,7 @@ Three ways to group decisions across entities exist now, and they answer differe
 |---|---|---|---|
 | **Tag** (`tag:<slug>`) | "which decisions carry this cross-cutting label?" | a bare slug, no prose | none — get-or-create, no ratification, no supersession |
 | **Domain** | "what is this named area of the system, and what do I need to know about it?" | slug + title + required WHY-IT-EXISTS summary + optional parent/communities/path_prefixes | full record: proposed → accepted, append-only supersession to revise |
-| **Initiative** | "which decisions belong to this piece of work?" | a name + optional description | flat container, no ratification gate of its own |
+| **Initiative** (`initiative:<label>`) | "which decisions belong to this piece of work?" | a Tier-0 label on captured decisions | flat grouping, no ratification gate of its own |
 
 A tag is the cheapest of the three — free-form text slugified into a durable entity at capture
 (`add_decision(tags=[...])`, or a draft's `tags` field), many-to-many, tier-0, no lifecycle to
@@ -196,7 +196,8 @@ describing *why performance work exists here* — that's what a domain's summary
 domain is the only one of the three that is itself ratified content: it has a required summary,
 it can be superseded, and it is what the TOC and `drill_down` are built from. An initiative
 groups decisions around a unit of *work* (a branch, a project) rather than a unit of the
-*system* — it has no summary field and nothing renders a description-first view of it the way
+*system*. Current capture paths implement it as an abstract entity and binding, not as an
+`Initiative` record with a description; nothing renders a description-first view of it the way
 `drill_down` does for a domain.
 
 ## See also

{sidegraph-0.3.0 → sidegraph-0.4.0}/docs/concepts/retrieval.md

@@ -55,12 +55,12 @@ at two points:
    rebuild it.
 2. **Every `ratify` call (MCP tool or `sidegraph-ratify` CLI) that actually accepted or dropped
    at least one domain** — immediately, without waiting for the next sync. This is what makes
-   `bootstrap → ratify` visibly turn the TOC on in the very same session: a lazy sync alone
-   only refreshes `last_synced_graph_version`, never the TOC cache, so without this the domain
-   layer would look inert until the next real graph rebuild.
+   `bootstrap → ratify` visibly turn the TOC on in the very same session, even when no graph
+   sync is needed.
 
-A decisions-only ratify (no domain ids in the batch) leaves the cache untouched — it wouldn't
-change the TOC anyway.
+A decisions-only ratify (no domain ids in the batch) does not rebuild the cache immediately.
+It can change a rendered mistake count; the next completed or skipped sync refreshes that
+count. Domain acceptance is the special case refreshed in the ratify operation itself.
 
 ## `drill_down(domain_slug)` — the Axis-1 operation
 
@@ -104,8 +104,10 @@ render actually deliver on real ADR-scale content instead of dropping it.)
 
 ### Ranking buckets, and why mistakes come first
 
-Decisions are gathered from seeds outward and ranked into ordered buckets, each sorted by
-recency (`valid_from` descending) within itself:
+Decisions are gathered from seeds outward and ranked into ordered buckets. Each source list
+(a seed entity, community/domain, peripheral entity, or global scope) is sorted by recency
+before it is appended; the implementation does not perform a second global recency sort across
+all sources in the same bucket.
 
 | Bucket | Section | Contents |
 |---|---|---|
@@ -154,20 +156,19 @@ not the other way around.
 A `Fact` rides the same `memory_chars` budget as decisions, spent strictly after them, in two
 forms:
 
-- **Inline evidence.** In buckets B-D, the moment a decision line is placed
-  (`rank_decisions.add()`), its live supporting facts (`store.facts_for_decision` — "live" =
-  status `accepted` or `proposed`, `valid_to` unset; a `superseded` fact never renders
-  inline, only its successor does, via its own anchors) render immediately as adjacent
-  `  evidence: <statement> [<source>]` lines directly under that decision, tagged
-  `[unratified]` when still `proposed` (a decision line can also carry `[drifted]` — see
-  the code-drift marker below). Bucket A (mistakes) defers this to a second pass
+- **Inline evidence.** In buckets B-D, the moment an accepted decision line is placed
+  (`rank_decisions.add()`), its live **accepted** supporting facts render immediately as
+  adjacent `  evidence: <statement> [<source>]` lines. A live proposed supporting fact is
+  quarantined in the final **Unratified proposals** section instead; a superseded fact does
+  not render. Bucket A (mistakes) defers accepted evidence to a second pass
   instead of rendering it immediately — see the mistakes-budget guarantee below for why.
   Either way, evidence lines degrade/drop with their decision under budget pressure — a fact
   only ever renders next to a decision that itself made the cut.
 - **The Known-facts bucket** (`## Known facts`, rendered right after `## Decisions`, ahead of
-  the structural map). Standalone facts — ones not already rendered inline under a decision
-  above — bound to a seed or peripheral entity, walked in the same seed-then-peripheral order
-  every other bucket uses, sorted by fact id for determinism. Populated only AFTER every
+  the structural map). Accepted standalone facts — ones not already rendered inline under a
+  decision above — bound to a seed or peripheral entity, walked in the same
+  seed-then-peripheral order every other bucket uses, sorted by fact id for determinism.
+  Proposed facts go to **Unratified proposals**. This bucket is populated only AFTER every
   decision bucket (A-D) and the superseded one-liners have already had first claim on the
   budget.
 
@@ -304,9 +305,10 @@ too (see [mind model](mind-model.md#how-domains-relate-to-engine-communities)).
 ### Rendering
 
 `TaskContext.render()` emits, in order: **Known mistakes & gotchas**, **Decisions** (with any
-inline `evidence:` lines nested under the decision they support), **Known facts** (standalone
-facts — see above), **Structural map** (the budgeted subgraph around the seeds, rendered as
-pointers — `- name (file_type) [file_path:line]`, never inlined code), then **Related**.
+accepted inline `evidence:` lines nested under the decision they support), **Known facts**
+(accepted standalone facts — see above), **Structural map** (the budgeted subgraph around the
+seeds, rendered as pointers — `- name (file_type) [file_path:line]`, never inlined code),
+**Related**, then **Unratified proposals**.
 Missing sections are omitted; an empty result renders `"No context found."`.
 
 ## See also

{sidegraph-0.3.0 → sidegraph-0.4.0}/docs/getting-started/bootstrap.md

@@ -152,12 +152,8 @@ supported-document path against it:
 > cannot run today. This is the intended reproduction path once it ships; there is no working
 > substitute before then.
 
-> **`@main` is a mutable ref.** Every `git+…@main` command on this page tracks the
-> branch: what you install today is not what you installed yesterday, and a `uvx` cache
-> refresh can change it under you. Fine for trying Sidegraph out; for anything you depend
-> on — CI, a shared team setup, a pilot you intend to measure — replace `@main` with a
-> commit SHA (`git+https://github.com/SantyagoSeaman/sidegraph@<sha>`) so the version is a
-> decision you made rather than whatever HEAD happened to be. See [`reference/stability.md`](../reference/stability.md) for what each surface promises.
+This command follows the current development branch. For durable environments, see
+[how to pin mutable development references](installation.md#mutable-development-references).
 
 ```bash
 git clone --branch demo https://github.com/SantyagoSeaman/sidegraph.git sidegraph-demo

{sidegraph-0.3.0 → sidegraph-0.4.0}/docs/getting-started/claude-code-setup.md

@@ -13,12 +13,8 @@ Run these in the repo you want memory over (not the Sidegraph checkout).
 
 Inside a Claude Code session, in that repo:
 
-> **`@main` is a mutable ref.** Every `git+…@main` command on this page tracks the
-> branch: what you install today is not what you installed yesterday, and a `uvx` cache
-> refresh can change it under you. Fine for trying Sidegraph out; for anything you depend
-> on — CI, a shared team setup, a pilot you intend to measure — replace `@main` with a
-> commit SHA (`git+https://github.com/SantyagoSeaman/sidegraph@<sha>`) so the version is a
-> decision you made rather than whatever HEAD happened to be. See [`reference/stability.md`](../reference/stability.md) for what each surface promises.
+The commands below follow the current development branch. For durable environments, see
+[how to pin mutable development references](installation.md#mutable-development-references).
 
 ```
 /plugin marketplace add SantyagoSeaman/sidegraph
@@ -73,10 +69,10 @@ flag if you want a private, user-local registration instead.
 `uv run --project /ABSOLUTE/PATH/TO/sidegraph sidegraph-mcp` (CLI form: `-- uv run --project
 /ABSOLUTE/PATH/TO/sidegraph sidegraph-mcp`).
 
-> **Once Sidegraph is published to PyPI**, both shorten further, to `uvx --from sidegraph
-> sidegraph-mcp` — see
-> [`integrations/claude-code.md`](../integrations/claude-code.md#plugin-install-path)
-> for the pin-at-1.0 policy.
+The released package is available from PyPI, so both shorten further, to `uvx --from
+sidegraph sidegraph-mcp` — see
+[`integrations/claude-code.md`](../integrations/claude-code.md#plugin-install-path)
+for the pinning policy. Use `sidegraph==X.Y.Z` in automation.
 
 The store (`SIDEGRAPH_DIR`) is meant to live **inside the repo it documents** — commit
 `.sidegraph/` alongside your code (its committed record directories, not the gitignored

{sidegraph-0.3.0 → sidegraph-0.4.0}/docs/getting-started/codex-setup.md

@@ -17,12 +17,8 @@ and AGENTS.md registered separately, for fine control or a source checkout).
 
 Inside a Codex CLI session, in that repo:
 
-> **`@main` is a mutable ref.** Every `git+…@main` command on this page tracks the
-> branch: what you install today is not what you installed yesterday, and a `uvx` cache
-> refresh can change it under you. Fine for trying Sidegraph out. For anything you depend
-> on, such as CI, a shared team setup, or a pilot you intend to measure, replace `@main`
-> with a commit SHA (`git+https://github.com/SantyagoSeaman/sidegraph@<sha>`) so the version
-> is a decision you made rather than whatever HEAD happened to be. See [`reference/stability.md`](../reference/stability.md) for what each surface promises.
+The commands below follow the current development branch. For durable environments, see
+[how to pin mutable development references](installation.md#mutable-development-references).
 
 ```
 /plugin marketplace add SantyagoSeaman/sidegraph
@@ -47,7 +43,7 @@ Skip to [Verify](#verify) once installed.
 
 ## Option B: manual registration
 
-Prefer explicit `config.toml`/`.codex/hooks/hooks.json` files (e.g. for review in a PR), or
+Prefer explicit `.codex/config.toml`/`.codex/hooks.json` files (e.g. for review in a PR), or
 want to point at a source checkout? Register the pieces yourself.
 
 ### 1. Register the MCP server
@@ -58,7 +54,7 @@ Via the CLI:
 codex mcp add sidegraph -- bash -lc "cd /ABSOLUTE/PATH/TO/your-repo && SIDEGRAPH_DIR=.sidegraph SIDEGRAPH_GRAPH=graphify-out/graph.json uv run --project /ABSOLUTE/PATH/TO/sidegraph sidegraph-mcp"
 ```
 
-Or add directly to `~/.codex/config.toml`:
+Or add it to the repo's `.codex/config.toml` (recommended for project-specific setup):
 
 ```toml
 [mcp_servers.sidegraph]
@@ -69,9 +65,10 @@ args = [
 ]
 ```
 
-`config.toml` is a single global file, not per-project, so the `cd` wrapper pins each
-registration to the repo whose `.sidegraph/` it should read — use a distinct
-`[mcp_servers.*]` name per repo if you wire up more than one.
+Codex also reads `~/.codex/config.toml`. Use the project file when the registration belongs
+to this repository; use the global file only when you intentionally want the server in every
+project. The `cd` wrapper remains useful in either scope because Sidegraph's relative paths
+must resolve against the repository whose memory it serves.
 
 ### 2. Tell the agent about Sidegraph
 
@@ -89,7 +86,7 @@ first. When you make a real decision or hit a hard-won gotcha, call `propose_dec
 
 ### 3. Add the hooks
 
-Create `.codex/hooks/hooks.json` in the repo:
+Create `.codex/hooks.json` in the repo:
 
 ```json
 {
@@ -125,9 +122,9 @@ working on a non-git corpus too (Sidegraph doesn't require the corpus to be a gi
 [`integrations/graphify.md`](../integrations/graphify.md#non-git-and-doc-only-corpora)), where a
 bare `git rev-parse --show-toplevel` would fail and leave `cd` with no argument.
 
-No `PreToolUse` entry is included above: Codex CLI's `PreToolUse` event (as of this writing)
-only intercepts Bash/patch/MCP tool calls, not file-read tools like `Read`/`Grep`, so Claude
-Code's Read/Grep redirect nudge
+No `PreToolUse` entry is included above. Codex can invoke that event for local function tools,
+but it has no stable `Read`/`Grep` tool pair to which Sidegraph's Claude-specific redirect can
+attach. Therefore Claude Code's Read/Grep redirect nudge
 (`sidegraph-pre-tool-use`) has no Codex counterpart to wire up yet — see
 [`integrations/codex.md`](../integrations/codex.md) for details.
 

{sidegraph-0.3.0 → sidegraph-0.4.0}/docs/getting-started/installation.md

@@ -11,6 +11,15 @@ Sidegraph has two parts: **Sidegraph itself** (the decision store + MCP server +
 - An MCP- and hooks-capable agent host: [Claude Code](claude-code-setup.md) or
   [OpenAI Codex CLI](codex-setup.md).
 
+## Mutable development references
+
+The `git+…@main` examples below track a mutable branch: a later `uvx` cache refresh can
+install different code. That is useful while trying Sidegraph. For CI, shared setup, or a
+measured pilot, replace `@main` with a release tag or commit SHA, for example
+`git+https://github.com/SantyagoSeaman/sidegraph.git@<sha>`. The plugin marketplace is the
+exception: its public manifests intentionally track `main`. See
+[`reference/stability.md`](../reference/stability.md) for the promises made by each surface.
+
 ## Install Sidegraph
 
 ### Option A — PyPI (recommended for the package + CLIs)
@@ -26,28 +35,24 @@ That puts `sidegraph-mcp` and every `sidegraph-*` CLI on your PATH. Pin a versio
 `uvx --from sidegraph sidegraph-mcp` works — the entry-point name differs from the package
 name, so `--from sidegraph` is required (a bare `uvx sidegraph-mcp` will not resolve).
 
-### Option B — Claude Code plugin (recommended for Claude Code — auto-wires the hooks)
-
-Inside a Claude Code session, in the repo you want memory over:
+### Option B — host plugin (recommended for Claude Code and Codex)
 
-> **`@main` is a mutable ref.** Every `git+…@main` command on this page tracks the
-> branch: what you install today is not what you installed yesterday, and a `uvx` cache
-> refresh can change it under you. Fine for trying Sidegraph out; for anything you depend
-> on — CI, a shared team setup, a pilot you intend to measure — replace `@main` with a
-> commit SHA (`git+https://github.com/SantyagoSeaman/sidegraph@<sha>`) so the version is a
-> decision you made rather than whatever HEAD happened to be. See [`reference/stability.md`](../reference/stability.md) for what each surface promises.
+Inside an interactive host session, in the repo you want memory over:
 
 ```
 /plugin marketplace add SantyagoSeaman/sidegraph
 /plugin install sidegraph@sidegraph
 ```
 
-Installs the MCP server and all three hooks (`SessionStart`, `Stop`, `PreToolUse`)
-automatically. The plugin's bundled config runs everything via `uvx --from
-git+https://github.com/SantyagoSeaman/sidegraph.git@main`, so it builds straight from this
-repository with `uv` — **no PyPI publish needed, works today**. See
-[the plugin install path](../integrations/claude-code.md#plugin-install-path) for what the
-bundled `.mcp.json`/`hooks.json` actually run, and the cwd-pinning details.
+The Claude Code host installs the MCP server and all three hooks (`SessionStart`, `Stop`,
+`PreToolUse`). Codex installs the MCP server, `SessionStart`/`Stop`, and the bundled skills;
+its tool surface has no equivalent target for the Claude-specific Read/Grep nudge. The
+plugin's bundled config runs everything via `uvx --from
+git+https://github.com/SantyagoSeaman/sidegraph.git@main`: unlike the package install, the
+plugin deliberately follows the public repository's `main` branch and does not use the
+PyPI package. See
+the integration details for [Claude Code](../integrations/claude-code.md#plugin-install-path)
+or [Codex](../integrations/codex.md#plugin-install-path).
 
 ### Option C — uvx directly from git (latest / unreleased)
 
@@ -92,7 +97,7 @@ runs against Sidegraph's own `.venv`. Silence it with `uv run --no-active --proj
 deactivating the other venv first.
 
 
-### Entry points
+## Entry points
 
 This table is the terminal reference. In day-to-day use you rarely type any of it: everyday
 operations (recording, ratifying, syncing, domain work) run conversationally inside a
@@ -109,25 +114,23 @@ setup, scripted/CI use, and the two deliberately human-run jobs (`sidegraph-impo
 | `sidegraph-pre-tool-use` | `PreToolUse` hook — redirects a blind `Read`/`Grep` toward `get_task_context`/`drill_down`. |
 | `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-ratify` | CLI — review/accept/drop proposed decisions and domains. |
+| `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-domains` | CLI — author Domain proposals: `bootstrap` from graph communities, or `add` manually. |
 | `sidegraph-compact` | CLI — pack terminal-status (superseded/rejected/dropped) decisions and domains into an immutable archive segment. |
 | `sidegraph-verify` | CLI — lint the store's canonical files against its write-path invariants (schema, validity windows, referential integrity, ULID uniqueness); `--against <git-ref>` additionally checks that every store file changed vs that ref was mutated legally (CI mode). |
 | `sidegraph-doctor` | CLI — one-stop store health: composes `sidegraph-verify`'s strict lint with an advisory curation pass (stale proposals, dangling/degraded/orphaned records, never-surfaced decisions); `--check` also fails on advisory findings. |
-| `sidegraph-viz` | CLI — render a read-only interactive HTML graph of the decision/fact store (nodes = decisions + facts + anchored entities; edges colored by anchor status; supersede + fact→decision links) plus a JSON sibling. |
+| `sidegraph-viz` | CLI — render an interactive HTML/JSON view of decisions, facts, entities, anchor status, supersession, and evidence links. |
 | `sidegraph-export-okf` | CLI — project the store into a deterministic [Open Knowledge Format v0.1](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf) bundle any OKF-aware tool can read; strictly one-way, the store stays the source of truth. |
 | `sidegraph-stats` | CLI — one screen of local usage statistics from the gitignored index (how often memory was asked for, how much of the code worked on has memory anchored to it, what the store holds, anchor health); read-only, never creates the index, `--json` for the same report as data. Reachable in a session as `/sidegraph:stats`. |
-| `sidegraph-prepare-commit-msg` | `prepare-commit-msg` git hook — comments candidate `Sidegraph-Decision:` trailers into the commit message template for the human/agent to uncomment; never blocks or stalls `git commit`. See [`reference/git-bindings.md`](../reference/git-bindings.md). |
+| `sidegraph-prepare-commit-msg` | `prepare-commit-msg` git hook — comments candidate `Sidegraph-Decision:` trailers into the commit message template; fail-open with bounded git/SQLite stages. See [`reference/git-bindings.md`](../reference/git-bindings.md). |
 | `sidegraph-blame` | CLI — `git blame` a file, joined to the decisions/facts each hunk's commit carries (commit trailers + `provenance.commit`). See [`reference/git-bindings.md`](../reference/git-bindings.md). |
 
-All of them read `SIDEGRAPH_GRAPH` (default `graphify-out/graph.json`) from the environment,
-resolved relative to the process's working directory. Same for `SIDEGRAPH_DIR` — every command
-(`sidegraph-mcp`, the three hooks, and every `cli.py` subcommand including `sidegraph-init`)
-resolves the store directory through the same shared precedence: an explicit `--db` flag,
-then `$SIDEGRAPH_DIR`, then the deprecated `$SIDEGRAPH_DB`, then an existing `.sidegraph/`,
-then the default `.sidegraph` — see
+Commands that need the graph use `SIDEGRAPH_GRAPH` (default
+`graphify-out/graph.json`). Store-aware entry points resolve `SIDEGRAPH_DIR` through the same
+shared precedence: an explicit `--db` flag where available, then `$SIDEGRAPH_DIR`, then the
+deprecated `$SIDEGRAPH_DB`, then an existing `.sidegraph/`, then the default `.sidegraph` — see
 [`reference/configuration.md`](../reference/configuration.md#store-path-resolution) for the
 exact rules.
 
@@ -150,7 +153,7 @@ Fallback if you don't use `uv`: `pip install 'graphifyy==0.9.6'`.
 `[mcp]` is an **optional** extra (`uv tool install "graphifyy[mcp]==0.9.6"`) that adds Graphify's
 *own* MCP server — a deeper structure-query layer over the same `graph.json`. It coexists
 fine with Sidegraph; Sidegraph only ever reads `graph.json` directly and doesn't need it. Add
-`[pdf]` if your corpus includes PDFs (extras compose: `"graphifyy[mcp,pdf]"`).
+`[pdf]` if your corpus includes PDFs (extras compose: `"graphifyy[mcp,pdf]==0.9.6"`).
 
 See [`integrations/graphify.md`](../integrations/graphify.md) for how Sidegraph reads
 Graphify's output, corpus types, and troubleshooting.
@@ -161,8 +164,5 @@ Continue to the [quickstart](quickstart.md) for the shortest path to a first cap
 retrieved decision. If the repository already contains ADRs or supported flow specs, use the
 [Bootstrap existing rationale guide](bootstrap.md) for the preview-first path instead. Once
 you've done that, run through
-[verifying your setup](../guides/verifying-your-setup.md) — a nine-case checklist that
-proves domain onboarding, domain management, durability, mistakes-first retrieval, quiet
-capture, refactor survival, git-native merges, facts evidence and cascade, and your own usage statistics
-actually work on your repo, each with an exact command and an observable
-result.
+[verifying your setup](../guides/verifying-your-setup.md) — a four-case checklist for host
+wiring, durable capture/retrieval, ratification with evidence, and sync/repository hygiene.

sidegraph-0.4.0/docs/getting-started/quickstart.md

@@ -0,0 +1,71 @@
+# Quickstart
+
+This is one complete loop: build the graph, create the store, connect one host, record one
+anchored gotcha, and retrieve it in a new session. It assumes the package and Graphify are
+installed as described in [Installation](installation.md).
+
+Run the shell commands from the repository that Sidegraph should remember.
+
+## 1. Build the graph and store
+
+```bash
+graphify update .
+sidegraph-init
+```
+
+`graphify update .` creates `graphify-out/graph.json`; Sidegraph reads it but never writes to
+it. `sidegraph-init` creates the repo-committed `.sidegraph/` record directories and a
+gitignored derived `index.db`. Both commands are safe to run again.
+
+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:
+
+```text
+/plugin marketplace add SantyagoSeaman/sidegraph
+/plugin install 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).
+
+## 3. Record one real gotcha
+
+Choose a real file or symbol in the repository. Tell the agent:
+
+> Record this gotcha against `<real path or symbol>`: caching parser output by file path
+> failed because the same path can identify different content across branches; key it by a
+> content hash instead.
+
+This human-requested path calls `add_decision`, so the record lands accepted. Confirm that a
+new JSON file exists under `.sidegraph/decisions/` and that its binding points at the file or
+symbol you named.
+
+## 4. Retrieve it from a fresh session
+
+Start another session in the same repository and ask:
+
+> Before I edit `<the same path or symbol>`, retrieve the Sidegraph task context. What should
+> I know?
+
+The agent should call `get_task_context` with that path or entity. The gotcha appears in
+**Known mistakes & gotchas**, ahead of accepted ADRs and related memory.
+
+## 5. Commit the durable part
+
+```bash
+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.
+
+The loop is now working. Next, run the short
+[verification checklist](../guides/verifying-your-setup.md), then
+[name domains](../guides/naming-your-domains.md) if you want a human-readable SessionStart
+table of contents.