sidegraph 0.3.1__tar.gz → 0.5.0__tar.gz

{sidegraph-0.3.1 → sidegraph-0.5.0}/.github/workflows/ci.yml

@@ -105,7 +105,6 @@ jobs:
             exit 0
           fi
           uv sync --locked
-          git fetch origin "$GITHUB_BASE_REF"
           base="$(git merge-base "origin/$GITHUB_BASE_REF" HEAD)"
           uv run sidegraph-verify --against "$base" --json
 

{sidegraph-0.3.1 → sidegraph-0.5.0}/CHANGELOG.md

@@ -7,6 +7,86 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.5.0] — 2026-09-23
+
+### Changed
+
+- **The public `main`, which the plugin manifests install from, moves only at releases.**
+  The plugin runs whatever `main` holds, so a snapshot pushed between releases used to reach
+  every plugin user at once. The release script now pushes `main` only for a release: it
+  refuses unless the version it carries is untagged in the public repository and
+  `CHANGELOG.md` dates it.
+
+### Fixed
+
+- **`sidegraph-init` now says to restart the Claude Code session after it writes
+  `SIDEGRAPH_RATIFY_POLICY`.** The Sidegraph MCP server reads the policy from the
+  environment it started with, so a server started before `sidegraph-init` kept proposing
+  under the old policy until the session restarted, and nothing said so.
+- **`sidegraph-verify --against` no longer flags a ratification of an already-committed
+  proposal, or a supersede/drop that touches a record written before a later schema addition
+  (`Provenance.commit`, `Domain.seed_anchors`/`path_prefixes`) existed.** Ratifying a
+  decision, fact, or domain stamps `ratified_at`/`ratified_by`, and neither field was on the
+  transition layer's mutable allow-list, so the stamp alone was reported as an illegal field
+  change. Separately, rewriting an old record that predates a field added to its schema
+  serializes that field back in as its default, which a plain top-level or whole-list
+  comparison also read as a change. The ratifier stamp may now be set once, from a proposed
+  record, landing on any state reached through accepted within the diffed range; an absent
+  field now counts as the same value as an explicit `null` or an empty list/object, at every
+  nesting depth and inside list items. A field whose default is a non-empty value is not
+  covered by this.
+- **`sidegraph-import --docs` no longer aborts on a file that is not valid UTF-8.** It
+  decoded every document as strict UTF-8 with no handler, so one document saved in
+  `cp1251` (or carrying a stray non-UTF-8 byte) raised and stopped the whole run, with
+  nothing after it imported and no report printed. The file is now a named skip
+  (`skipped_undecodable`) instead: the run continues, and both the real run and
+  `--dry-run` print the skipped path(s), last.
+- **`sidegraph-import --docs` now reads a UTF-8 document that starts with a byte-order mark
+  (BOM).** The BOM used to survive into the parsed text, so the H1 and any frontmatter never
+  matched, and a real decision document was silently counted `skipped_not_decision`. It is
+  now stripped before parsing. `sidegraph-bootstrap` still reads such a file without
+  stripping it.
+
+  Re-importing a BOM document that an earlier version did import can change its record,
+  once:
+  - On the `openspec` profile, a BOM `proposal.md` had imported under a title built from its
+    path. The re-import supersedes it with the real H1 title.
+  - Frontmatter the BOM hid is now honoured. A document marked `status: superseded` now
+    counts `skipped_superseded_frontmatter`, and its earlier live record stays as it is.
+  - A document marked as a draft, proposed, pending or under review keeps its earlier
+    `accepted` record: a re-import compares content, not status, and the content is
+    unchanged.
+
+  Retiring or re-proposing such a record is manual.
+
+### Security
+
+- **The lockfile moves `anyio` from 4.14.1 to 4.15.1**, past three advisories fixed in
+  4.14.2: TLS certificate spoofing through IDNA 2003 host-name encoding (critical),
+  `run_process` keeping the parent's supplementary groups (high), and process-pool workers
+  blocking on undrained stderr (moderate). The published package does not pin `anyio`, so
+  this changes development and CI environments and installs made from `uv.lock`; a fresh
+  install already resolves a fixed version.
+
+## [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

{sidegraph-0.3.1 → sidegraph-0.5.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.1) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.5.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.1 → sidegraph-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sidegraph
-Version: 0.3.1
+Version: 0.5.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.
 
@@ -84,14 +84,16 @@ only ever reads `graph.json`, so the plain install above is all it needs.
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
-# Prefer the latest unreleased build straight from git instead of PyPI? Swap step 3 for:
+# Prefer running straight from git instead of PyPI? Swap step 3 for:
 #   uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init
-#   `@main` is a mutable ref — it moves under you. Pin a tag or a SHA for CI.
+#   `@main` moves only when a release is cut. It is still a mutable ref: a later cache refresh can
+#   install a newer one. Pin a tag or a SHA for CI.
 ```
 
 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.1 → sidegraph-0.5.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.
 
@@ -56,14 +56,16 @@ only ever reads `graph.json`, so the plain install above is all it needs.
 uv tool install sidegraph        # from PyPI — puts sidegraph-init / sidegraph-mcp / … on PATH
 sidegraph-init
 
-# Prefer the latest unreleased build straight from git instead of PyPI? Swap step 3 for:
+# Prefer running straight from git instead of PyPI? Swap step 3 for:
 #   uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init
-#   `@main` is a mutable ref — it moves under you. Pin a tag or a SHA for CI.
+#   `@main` moves only when a release is cut. It is still a mutable ref: a later cache refresh can
+#   install a newer one. Pin a tag or a SHA for CI.
 ```
 
 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.1 → sidegraph-0.5.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.5.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.1 → sidegraph-0.5.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.1 → sidegraph-0.5.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.1 → sidegraph-0.5.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.1 → sidegraph-0.5.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.1 → sidegraph-0.5.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.1 → sidegraph-0.5.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.