sidegraph 0.12.0__tar.gz → 0.13.0__tar.gz

{sidegraph-0.12.0 → sidegraph-0.13.0}/.github/workflows/ci.yml

@@ -192,6 +192,9 @@ jobs:
             tests/test_server_result_contract.py tests/test_server_invocation_policy.py `
             tests/test_verify_git_stdin.py tests/test_seed_paths_portable.py `
             tests/test_repo_relative_paths_portable.py `
+            tests/test_command_windows.py `
+            tests/test_hook_payload_encoding.py `
+            tests/test_git_output_utf8.py `
             $privateTests `
             tests/test_installed_wheel_smoke.py
           if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }

{sidegraph-0.12.0 → sidegraph-0.13.0}/CHANGELOG.md

@@ -7,6 +7,48 @@ interfaces, exactly, and what each one promises: [`docs/reference/stability.md`]
 
 ## [Unreleased]
 
+## [0.13.0] — 2026-10-14
+
+### Fixed
+
+- On Windows, hooks misread the payload the host sends when a path in it has a non-ASCII
+  character (an accented or Cyrillic user name or project folder). The Stop capture reminder
+  never fired, PreToolUse delivered no records, and for some names SessionStart and
+  SubagentStart printed nothing.
+- On Windows, a non-ASCII git user name, branch name or repository path was read back garbled:
+  a ratified record could carry a garbled name in its provenance, and `sidegraph-verify
+  --against` failed or reported false changes for records containing non-ASCII text.
+- A change to a file whose name has non-ASCII characters, spaces or quotes was missed by the
+  drift check and the commit-trailer candidates, because git escaped the name.
+- On Windows, a Codex hook started from a subdirectory of a repository whose path has non-ASCII
+  characters now runs from the repository root.
+- A default Git for Windows install no longer breaks the MCP server. Its installer puts only
+  `Git\cmd` on PATH, which has no `sh`, so the server, which started with `sh`, did not start.
+  The Codex hooks have a Windows command for the same reason (see Changed).
+- The project's ratify policy now applies under Codex. `sidegraph-init` commits it to
+  `.claude/settings.json`, which Codex does not read, so under Codex every agent proposal
+  waited for review whatever the team chose. The plugin's MCP server now reads the committed
+  value when its environment sets none; an explicit `SIDEGRAPH_RATIFY_POLICY` still wins.
+
+### Changed
+
+- The plugins launch without `sh` on PATH. Both MCP launchers start `uvx` (`uv` in the
+  development manifest) directly, and `sidegraph-mcp --repo-root` anchors the server to the
+  project: `CLAUDE_PROJECT_DIR`, else the git top-level, else the working directory. The Codex
+  hooks gain a PowerShell `commandWindows` that Windows PowerShell 5.1 parses. On native Windows
+  you need no PATH change and no PowerShell 7; Git for Windows at its default options is
+  enough. The Codex hooks need a Codex release that supports `commandWindows` (verified with
+  0.162.1). The Windows hook definition changes, so approve the changed hooks once in `/hooks`
+  on Windows; other platforms are unaffected.
+- The optional terminal CLI now installs from the same place as the plugin, the public
+  repository's `main` branch: `uv tool install git+https://github.com/SantyagoSeaman/sidegraph.git@main`,
+  updated after each release with `uv tool upgrade sidegraph`. The docs no longer send you to
+  PyPI for it; PyPI still carries every release for pinning an exact version. The `path-skew`
+  SessionStart line now offers `uv tool install --reinstall git+https://github.com/SantyagoSeaman/sidegraph.git@main`,
+  which moves an older install from PyPI, pinned or not, to the latest release.
+- README: the Quickstart is one numbered sequence with the plugin commands inline, a teammate
+  path, and the rarer options below it; "How it works" is a numbered list instead of a diagram.
+
 ## [0.12.0] — 2026-10-12
 
 ### Fixed

{sidegraph-0.12.0 → sidegraph-0.13.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.12.0) — the full loop (capture, ratification, mistakes-first
+Sidegraph is pre-1.0 (v0.13.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.13.0/PKG-INFO

@@ -0,0 +1,310 @@
+Metadata-Version: 2.5
+Name: sidegraph
+Version: 0.13.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
+Project-URL: Documentation, https://github.com/SantyagoSeaman/sidegraph/tree/main/docs
+Project-URL: Issues, https://github.com/SantyagoSeaman/sidegraph/issues
+Project-URL: Changelog, https://github.com/SantyagoSeaman/sidegraph/blob/main/CHANGELOG.md
+Author: SantyagoSeaman
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: adr,agent-memory,claude-code,code-graph,codex,coding-agents,decision-log,decision-records,developer-tools,knowledge-graph,mcp,mcp-server,team-memory
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.13
+Requires-Dist: anyio>=4
+Requires-Dist: fastmcp<4,>=3.4.2
+Requires-Dist: mcp<2,>=1.24
+Requires-Dist: pydantic>=2.9
+Requires-Dist: python-ulid>=3.0
+Description-Content-Type: text/markdown
+
+# Sidegraph
+
+[![tests](https://img.shields.io/github/actions/workflow/status/SantyagoSeaman/sidegraph/ci.yml?label=tests)](https://github.com/SantyagoSeaman/sidegraph/actions/workflows/ci.yml)
+[![release](https://img.shields.io/github/v/release/SantyagoSeaman/sidegraph)](https://github.com/SantyagoSeaman/sidegraph/releases)
+![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue)
+![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)
+[![Windows x64 full plugin session checked](https://img.shields.io/badge/Windows%20x64-full%20plugin%20session%20checked-blue)](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/getting-started/installation.md#platform-coverage)
+[![macOS arm64 full plugin session checked](https://img.shields.io/badge/macOS%20arm64-full%20plugin%20session%20checked-blue)](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/getting-started/installation.md#platform-coverage)
+
+Sidegraph is a local MCP server and CLI for preserving engineering decisions and
+facts alongside your code. It records why a design was chosen, which alternatives were
+rejected, and what was learned during implementation, then retrieves that context for
+the files and symbols an agent is working on.
+
+Records live in your repository as reviewable JSON files. A derived SQLite index supports
+retrieval; [Graphify](https://github.com/safishamsi/graphify) supplies the code and document
+graph used to anchor records. Claude Code and Codex plugins connect capture and retrieval
+to coding sessions.
+
+- Keep decisions, rejected alternatives, and evidence with their provenance and history.
+- Hand the agent the relevant mistakes and constraints before it edits, sized to fit its context.
+- Review agent proposals before accepting them, or let low-risk ones be accepted automatically.
+- Follow code through refactors, and flag records whose code changed or disappeared.
+
+[Documentation](docs/README.md) · [Installation](docs/getting-started/installation.md) ·
+[Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
+
+## Quickstart
+
+### Set up a repository (once)
+
+**You need** Git, Claude Code or Codex, and [uv](https://docs.astral.sh/uv/getting-started/installation/),
+which also downloads Python 3.13 if you do not have it. On Windows you also need
+[Git for Windows](https://gitforwindows.org/) with its default options
+([details](docs/getting-started/installation.md#windows)); run the commands below in
+PowerShell, using the Windows line where one is given. No API keys and no existing ADRs are required.
+
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh                                     # uv on macOS, Linux
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # uv on Windows
+```
+
+**1. Build the code graph.** [Graphify](https://github.com/safishamsi/graphify) maps your
+functions, classes and files, so a record can point at the exact function it is about.
+
+```sh
+uv tool install "graphifyy==0.9.6"   # two y's in the package name; the command is graphify
+cd /path/to/your/repo
+graphify update .
+echo "graphify-out/" >> .gitignore   # the graph is rebuilt from your code; keep it out of git
+Add-Content .gitignore "graphify-out/"   # the same line on Windows (PowerShell); do not use >> there
+```
+
+**2. Create the store**, the `.sidegraph/` directory that holds the records:
+
+```sh
+uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init
+```
+
+It asks two questions. Both default to yes, so press Enter twice.
+
+- *Keep the code graph fresh?* Yes installs a git hook that rebuilds the graph after each commit.
+- *Auto-ratify low-risk records?* Yes means the lessons, gotchas and facts the agent proposes
+  are accepted without review. Other proposals still wait for you. The answer is saved in
+  `.claude/settings.json`, which you commit. The plugin applies it in Claude Code and in Codex,
+  so it covers the whole team.
+
+Details: [`sidegraph-init`](docs/reference/cli.md#sidegraph-init).
+
+**3. Install the plugin.** It gives the agent the memory at session start and asks it to save
+new decisions at the end of a session. It updates itself: each new session downloads and runs
+the latest Sidegraph release.
+
+In Claude Code, run these inside a session in the repository, then start a new session:
+
+```text
+/plugin marketplace add SantyagoSeaman/sidegraph
+/plugin install sidegraph@sidegraph
+```
+
+In Codex, run these in a terminal in the repository, then start `codex` and approve the
+Sidegraph hooks when it asks:
+
+```sh
+codex plugin marketplace add SantyagoSeaman/sidegraph
+codex plugin add sidegraph@sidegraph
+```
+
+**4. Record a decision.** In a session, ask the agent, naming a real file and function:
+
+> Record this gotcha: the upstream API limits batch requests to 100 items. We rejected
+> a single unbounded request because it fails for larger imports. Anchor it to
+> `import_batch` in `src/importer.py`.
+
+It is saved right away. Records the agent proposes on its own may wait for your review: run
+`/sidegraph:ratify-decisions` in Claude Code, or ask Codex to "review pending decisions".
+
+**5. Check and commit.** Start a new session and ask: "Before I edit `src/importer.py`, what
+should I know?" The agent should show the gotcha. Then commit `.sidegraph/` and `.gitignore`,
+and `.claude/settings.json` if step 2 created or changed it. The index file inside
+`.sidegraph/` is git-ignored automatically.
+
+### Each teammate
+
+After cloning, each teammate runs steps 1, 2 and 3. In a clone, step 2 leaves the committed
+records and settings alone. It only installs the graph hook there.
+
+Next, [name your domains](docs/guides/naming-your-domains.md) to give the memory a table of
+contents, or import existing ADRs and design specs with the
+[preview-first bootstrap](docs/getting-started/bootstrap.md). The
+[verification checklist](docs/guides/verifying-your-setup.md) covers the whole workflow.
+
+### Other options
+
+- **Without the graph.** Skip step 1 and answer no to the first question in step 2. Records
+  then attach to whole files instead of functions.
+- **Versions.** You always run the latest release. The plugin and the step 2 command install
+  Sidegraph from the public repository on GitHub, whose `main` branch changes only when a
+  release is published. To pin a version instead, see
+  [pinning](docs/getting-started/installation.md#mutable-development-references).
+- **Sidegraph commands in your own terminal.** Optional:
+  `uv tool install git+https://github.com/SantyagoSeaman/sidegraph.git@main`, from the same place as the plugin. It does not update itself, so
+  after each release run `uv tool upgrade sidegraph`
+  ([details](docs/getting-started/installation.md#option-a--the-cli-on-your-path)).
+- **Other MCP clients.** Run `sidegraph-mcp` over stdio; see the
+  [MCP reference](docs/reference/mcp-tools.md) and [configuration](docs/reference/configuration.md).
+  Automatic memory needs a host with hooks, such as Claude Code or Codex.
+- **Windows details**, including what the plugins need from Git for Windows:
+  [Windows setup](docs/getting-started/installation.md#windows).
+
+## Why
+
+Code describes the current implementation, but often omits the alternatives a team
+tried, operational constraints it discovered, and reasons for changing direction.
+Sidegraph captures that reasoning and links it to the code and planning documents it
+concerns. It works alongside an existing ADR or specification process.
+
+The useful starting point is a project with decisions worth retaining and people willing
+to review them. Memory quality depends on capture, review, and whether the agent actually
+retrieves it. Small tasks answerable directly from code may gain little from the extra
+context. The [engineering whitepaper](docs/whitepaper/index.md) describes the evidence,
+negative results, and adoption criteria; the [pilot kit](docs/pilot-kit/README.md) helps
+evaluate it on your own repository.
+
+## How it works
+
+1. **Capture.** During a session the agent saves a decision when you ask for one. At the end of
+   a session the plugin reminds it to propose the decisions worth keeping. Secrets are redacted
+   before anything is written.
+2. **Review.** You accept or drop what the agent proposed; Sidegraph calls this *ratifying*.
+   Records are JSON files in `.sidegraph/`, committed with your code.
+3. **Anchoring.** Each record is linked to the functions, classes, files or document headings it
+   is about, using the graph Graphify builds from your code. When a refactor moves code,
+   Sidegraph follows the move; when it cannot tell where the code went, it flags the record for
+   review.
+4. **Recall.** At the start of the next session the agent gets a short table of contents of the
+   project's areas, called *domains*. Before changing a file it asks for that file's records,
+   with known mistakes first. In Claude Code, the agent also receives a file's records the
+   first time it reads or edits that file.
+5. **Subagents.** In Claude Code, when the agent hands a task to a subagent, the records for the
+   files named in that task are added to it. In Claude Code and Codex, each new subagent is told
+   that the memory exists and how to use it.
+
+Domains are named by you or proposed by the agent; each one says what an area is for and which
+code belongs to it. See the [mind model](docs/concepts/mind-model.md) and the
+[anchoring model](docs/concepts/anchoring.md).
+
+## What gets stored
+
+| Record | What it is |
+|---|---|
+| `Decision` | Kind (`adr`, `lesson`, `constraint`, or `gotcha`), context, choice, rejected alternatives, consequences, validity, history, and provenance |
+| `Fact` | A benchmark, external constraint, or observed finding that supports a decision or stands alone |
+| `Entity` | A stable ID for a function, class, file or heading, kept when the graph is rebuilt |
+| `AnchorBinding` | The link between a decision or fact and an entity it is about |
+| `Domain` | A named area with a purpose, membership rules, and optional subdomains |
+
+Nothing is ever deleted. A reversed decision is closed and replaced by a new one, so *"tried
+before, abandoned because…"* stays retrievable with `get_entity_history`. Dropping a proposal
+marks it rejected; it stays in the history too.
+
+Facts follow the same review and history rules as decisions. Accepting or dropping a decision also accepts or drops
+the pending facts attached to it. Details:
+[docs/concepts/data-model.md](docs/concepts/data-model.md) and
+[docs/guides/capturing-decisions.md#facts-the-evidence-layer](docs/guides/capturing-decisions.md#facts-the-evidence-layer).
+
+## MCP tools
+
+The `sidegraph-mcp` stdio server exposes retrieval, capture, review and maintenance tools.
+The ones an agent uses most: `get_task_context` (the records for the files or functions it is
+working on), `drill_down` (everything in one domain), `get_entity_history` (every decision
+ever made about one function or file, including reversed ones), `propose_decisions` (drafts
+for review) and `ratify` (accept or drop drafts).
+
+See the [MCP reference](docs/reference/mcp-tools.md) for the complete tool set, schemas,
+return shapes, and side effects. The [CLI reference](docs/reference/cli.md) covers setup,
+scripted use, and CI maintenance. Tool names and return shapes are
+[provisional before 1.0](docs/reference/stability.md).
+
+## Works on code and on docs
+
+Anchor decisions to functions and classes, or to **headings in your architecture documents**;
+Graphify builds both graphs without an LLM. `sidegraph-bootstrap` turns existing ADRs and
+design specs into anchored decisions, also without an LLM.
+
+An optional **semantic pass** (`graphify extract`, which needs an API key for its model
+provider and caches results per file) goes deeper on documentation: it turns prose into
+concepts and themes that records can anchor to. Walkthrough:
+[docs/guides/semantic-docs.md](docs/guides/semantic-docs.md).
+
+## Trust & privacy
+
+- **Local runtime:** Sidegraph reads repository files and the graph, and writes records,
+  a derived index, and optional setup or export files. It makes no network calls of its own
+  and sends nothing anywhere. Installing and updating it downloads it from GitHub. What the agent
+  does with Sidegraph's answers is up to your agent host, which sends them to its model
+  provider like any other context. Graphify's optional semantic pass uses its own model
+  provider. See [SECURITY.md](SECURITY.md) for the data boundary.
+- **Reviewable capture:** text is redacted before storage using best-effort patterns.
+  Review drafts and scan the committed store for secrets. Agent proposals wait for human
+  review unless the project answered yes to auto-ratify in `sidegraph-init`; even then,
+  architecture decisions and domains wait. See the
+  [ratification policy](docs/reference/configuration.md).
+- **Preserved history:** a reversal closes the old record and adds a new one. Only two things
+  change a record in place: review sets its status, and a confirmed file move updates where
+  its anchor points.
+- **Local counts:** for `sidegraph-stats`, Sidegraph counts how often memory was shown. The
+  counts stay in `.sidegraph/index.db`, which is git-ignored and never leaves your machine.
+  To stop counting, set `SIDEGRAPH_TELEMETRY=off`.
+
+## The engine underneath
+
+The graph of your code and documents comes from
+[Graphify](https://github.com/safishamsi/graphify), built without an LLM. Sidegraph only reads
+it and never writes into it. Without a graph, records anchor to files and domains, and recall
+still works. Three things need the graph: anchoring a record to a function, grouping related
+code automatically, and following moved code (see the
+[operations reference](docs/reference/operations.md#the-graph-dependency-stated-plainly)).
+The graph and the local index can be rebuilt at any time. The JSON records in `.sidegraph/`
+cannot: they are the source of truth, so keep them in your repository and backups.
+
+## Status
+
+Sidegraph is in beta. Read the [stability policy](docs/reference/stability.md) before
+building automation against it. By default the plugin follows the latest release; for
+reproducible deployments, [pin a version](docs/getting-started/installation.md#mutable-development-references).
+The [changelog](CHANGELOG.md) records release changes.
+
+The platform badges at the top summarize the 0.13.0 release checks of 2026-10-14: Windows x64
+and macOS arm64 both ran the full plugin session for Claude Code and Codex. The badges are not
+live CI status; see [Platform coverage](docs/getting-started/installation.md#platform-coverage).
+
+## Contributing and support
+
+Bug reports, questions, and feature requests are welcome in
+[GitHub Issues](https://github.com/SantyagoSeaman/sidegraph/issues). Include the commands
+you ran, expected and actual behavior, and package versions; remove secrets from logs.
+For patches, see [Contributing](CONTRIBUTING.md) and the
+[Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities through the private
+channel in [SECURITY.md](SECURITY.md).
+
+The public repository holds the released code; development happens in a private repository.
+Contributions are reviewed here and carried over, with attribution, before the next release.
+
+## Documentation
+
+[Getting started](docs/getting-started/installation.md) ·
+[Concepts](docs/concepts/decision-memory.md) ·
+[Guides](docs/guides/capturing-decisions.md) ·
+[Reference](docs/reference/mcp-tools.md) ·
+[Integrations](docs/integrations/graphify.md) (Graphify · Claude Code · Codex) ·
+[Verify your setup](docs/guides/verifying-your-setup.md) ·
+[Operations](docs/reference/operations.md) ·
+[Pilot kit](docs/pilot-kit/README.md) ·
+[Engineering whitepaper](docs/whitepaper/index.md)
+
+## License
+
+[Apache-2.0](LICENSE).

sidegraph-0.13.0/README.md

@@ -0,0 +1,280 @@
+# Sidegraph
+
+[![tests](https://img.shields.io/github/actions/workflow/status/SantyagoSeaman/sidegraph/ci.yml?label=tests)](https://github.com/SantyagoSeaman/sidegraph/actions/workflows/ci.yml)
+[![release](https://img.shields.io/github/v/release/SantyagoSeaman/sidegraph)](https://github.com/SantyagoSeaman/sidegraph/releases)
+![Python 3.13+](https://img.shields.io/badge/python-3.13%2B-blue)
+![License](https://img.shields.io/badge/license-Apache--2.0-green)
+![MCP](https://img.shields.io/badge/MCP-server-8A2BE2)
+[![Windows x64 full plugin session checked](https://img.shields.io/badge/Windows%20x64-full%20plugin%20session%20checked-blue)](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/getting-started/installation.md#platform-coverage)
+[![macOS arm64 full plugin session checked](https://img.shields.io/badge/macOS%20arm64-full%20plugin%20session%20checked-blue)](https://github.com/SantyagoSeaman/sidegraph/blob/main/docs/getting-started/installation.md#platform-coverage)
+
+Sidegraph is a local MCP server and CLI for preserving engineering decisions and
+facts alongside your code. It records why a design was chosen, which alternatives were
+rejected, and what was learned during implementation, then retrieves that context for
+the files and symbols an agent is working on.
+
+Records live in your repository as reviewable JSON files. A derived SQLite index supports
+retrieval; [Graphify](https://github.com/safishamsi/graphify) supplies the code and document
+graph used to anchor records. Claude Code and Codex plugins connect capture and retrieval
+to coding sessions.
+
+- Keep decisions, rejected alternatives, and evidence with their provenance and history.
+- Hand the agent the relevant mistakes and constraints before it edits, sized to fit its context.
+- Review agent proposals before accepting them, or let low-risk ones be accepted automatically.
+- Follow code through refactors, and flag records whose code changed or disappeared.
+
+[Documentation](docs/README.md) · [Installation](docs/getting-started/installation.md) ·
+[Changelog](CHANGELOG.md) · [Contributing](CONTRIBUTING.md)
+
+## Quickstart
+
+### Set up a repository (once)
+
+**You need** Git, Claude Code or Codex, and [uv](https://docs.astral.sh/uv/getting-started/installation/),
+which also downloads Python 3.13 if you do not have it. On Windows you also need
+[Git for Windows](https://gitforwindows.org/) with its default options
+([details](docs/getting-started/installation.md#windows)); run the commands below in
+PowerShell, using the Windows line where one is given. No API keys and no existing ADRs are required.
+
+```sh
+curl -LsSf https://astral.sh/uv/install.sh | sh                                     # uv on macOS, Linux
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # uv on Windows
+```
+
+**1. Build the code graph.** [Graphify](https://github.com/safishamsi/graphify) maps your
+functions, classes and files, so a record can point at the exact function it is about.
+
+```sh
+uv tool install "graphifyy==0.9.6"   # two y's in the package name; the command is graphify
+cd /path/to/your/repo
+graphify update .
+echo "graphify-out/" >> .gitignore   # the graph is rebuilt from your code; keep it out of git
+Add-Content .gitignore "graphify-out/"   # the same line on Windows (PowerShell); do not use >> there
+```
+
+**2. Create the store**, the `.sidegraph/` directory that holds the records:
+
+```sh
+uvx --from git+https://github.com/SantyagoSeaman/sidegraph.git@main sidegraph-init
+```
+
+It asks two questions. Both default to yes, so press Enter twice.
+
+- *Keep the code graph fresh?* Yes installs a git hook that rebuilds the graph after each commit.
+- *Auto-ratify low-risk records?* Yes means the lessons, gotchas and facts the agent proposes
+  are accepted without review. Other proposals still wait for you. The answer is saved in
+  `.claude/settings.json`, which you commit. The plugin applies it in Claude Code and in Codex,
+  so it covers the whole team.
+
+Details: [`sidegraph-init`](docs/reference/cli.md#sidegraph-init).
+
+**3. Install the plugin.** It gives the agent the memory at session start and asks it to save
+new decisions at the end of a session. It updates itself: each new session downloads and runs
+the latest Sidegraph release.
+
+In Claude Code, run these inside a session in the repository, then start a new session:
+
+```text
+/plugin marketplace add SantyagoSeaman/sidegraph
+/plugin install sidegraph@sidegraph
+```
+
+In Codex, run these in a terminal in the repository, then start `codex` and approve the
+Sidegraph hooks when it asks:
+
+```sh
+codex plugin marketplace add SantyagoSeaman/sidegraph
+codex plugin add sidegraph@sidegraph
+```
+
+**4. Record a decision.** In a session, ask the agent, naming a real file and function:
+
+> Record this gotcha: the upstream API limits batch requests to 100 items. We rejected
+> a single unbounded request because it fails for larger imports. Anchor it to
+> `import_batch` in `src/importer.py`.
+
+It is saved right away. Records the agent proposes on its own may wait for your review: run
+`/sidegraph:ratify-decisions` in Claude Code, or ask Codex to "review pending decisions".
+
+**5. Check and commit.** Start a new session and ask: "Before I edit `src/importer.py`, what
+should I know?" The agent should show the gotcha. Then commit `.sidegraph/` and `.gitignore`,
+and `.claude/settings.json` if step 2 created or changed it. The index file inside
+`.sidegraph/` is git-ignored automatically.
+
+### Each teammate
+
+After cloning, each teammate runs steps 1, 2 and 3. In a clone, step 2 leaves the committed
+records and settings alone. It only installs the graph hook there.
+
+Next, [name your domains](docs/guides/naming-your-domains.md) to give the memory a table of
+contents, or import existing ADRs and design specs with the
+[preview-first bootstrap](docs/getting-started/bootstrap.md). The
+[verification checklist](docs/guides/verifying-your-setup.md) covers the whole workflow.
+
+### Other options
+
+- **Without the graph.** Skip step 1 and answer no to the first question in step 2. Records
+  then attach to whole files instead of functions.
+- **Versions.** You always run the latest release. The plugin and the step 2 command install
+  Sidegraph from the public repository on GitHub, whose `main` branch changes only when a
+  release is published. To pin a version instead, see
+  [pinning](docs/getting-started/installation.md#mutable-development-references).
+- **Sidegraph commands in your own terminal.** Optional:
+  `uv tool install git+https://github.com/SantyagoSeaman/sidegraph.git@main`, from the same place as the plugin. It does not update itself, so
+  after each release run `uv tool upgrade sidegraph`
+  ([details](docs/getting-started/installation.md#option-a--the-cli-on-your-path)).
+- **Other MCP clients.** Run `sidegraph-mcp` over stdio; see the
+  [MCP reference](docs/reference/mcp-tools.md) and [configuration](docs/reference/configuration.md).
+  Automatic memory needs a host with hooks, such as Claude Code or Codex.
+- **Windows details**, including what the plugins need from Git for Windows:
+  [Windows setup](docs/getting-started/installation.md#windows).
+
+## Why
+
+Code describes the current implementation, but often omits the alternatives a team
+tried, operational constraints it discovered, and reasons for changing direction.
+Sidegraph captures that reasoning and links it to the code and planning documents it
+concerns. It works alongside an existing ADR or specification process.
+
+The useful starting point is a project with decisions worth retaining and people willing
+to review them. Memory quality depends on capture, review, and whether the agent actually
+retrieves it. Small tasks answerable directly from code may gain little from the extra
+context. The [engineering whitepaper](docs/whitepaper/index.md) describes the evidence,
+negative results, and adoption criteria; the [pilot kit](docs/pilot-kit/README.md) helps
+evaluate it on your own repository.
+
+## How it works
+
+1. **Capture.** During a session the agent saves a decision when you ask for one. At the end of
+   a session the plugin reminds it to propose the decisions worth keeping. Secrets are redacted
+   before anything is written.
+2. **Review.** You accept or drop what the agent proposed; Sidegraph calls this *ratifying*.
+   Records are JSON files in `.sidegraph/`, committed with your code.
+3. **Anchoring.** Each record is linked to the functions, classes, files or document headings it
+   is about, using the graph Graphify builds from your code. When a refactor moves code,
+   Sidegraph follows the move; when it cannot tell where the code went, it flags the record for
+   review.
+4. **Recall.** At the start of the next session the agent gets a short table of contents of the
+   project's areas, called *domains*. Before changing a file it asks for that file's records,
+   with known mistakes first. In Claude Code, the agent also receives a file's records the
+   first time it reads or edits that file.
+5. **Subagents.** In Claude Code, when the agent hands a task to a subagent, the records for the
+   files named in that task are added to it. In Claude Code and Codex, each new subagent is told
+   that the memory exists and how to use it.
+
+Domains are named by you or proposed by the agent; each one says what an area is for and which
+code belongs to it. See the [mind model](docs/concepts/mind-model.md) and the
+[anchoring model](docs/concepts/anchoring.md).
+
+## What gets stored
+
+| Record | What it is |
+|---|---|
+| `Decision` | Kind (`adr`, `lesson`, `constraint`, or `gotcha`), context, choice, rejected alternatives, consequences, validity, history, and provenance |
+| `Fact` | A benchmark, external constraint, or observed finding that supports a decision or stands alone |
+| `Entity` | A stable ID for a function, class, file or heading, kept when the graph is rebuilt |
+| `AnchorBinding` | The link between a decision or fact and an entity it is about |
+| `Domain` | A named area with a purpose, membership rules, and optional subdomains |
+
+Nothing is ever deleted. A reversed decision is closed and replaced by a new one, so *"tried
+before, abandoned because…"* stays retrievable with `get_entity_history`. Dropping a proposal
+marks it rejected; it stays in the history too.
+
+Facts follow the same review and history rules as decisions. Accepting or dropping a decision also accepts or drops
+the pending facts attached to it. Details:
+[docs/concepts/data-model.md](docs/concepts/data-model.md) and
+[docs/guides/capturing-decisions.md#facts-the-evidence-layer](docs/guides/capturing-decisions.md#facts-the-evidence-layer).
+
+## MCP tools
+
+The `sidegraph-mcp` stdio server exposes retrieval, capture, review and maintenance tools.
+The ones an agent uses most: `get_task_context` (the records for the files or functions it is
+working on), `drill_down` (everything in one domain), `get_entity_history` (every decision
+ever made about one function or file, including reversed ones), `propose_decisions` (drafts
+for review) and `ratify` (accept or drop drafts).
+
+See the [MCP reference](docs/reference/mcp-tools.md) for the complete tool set, schemas,
+return shapes, and side effects. The [CLI reference](docs/reference/cli.md) covers setup,
+scripted use, and CI maintenance. Tool names and return shapes are
+[provisional before 1.0](docs/reference/stability.md).
+
+## Works on code and on docs
+
+Anchor decisions to functions and classes, or to **headings in your architecture documents**;
+Graphify builds both graphs without an LLM. `sidegraph-bootstrap` turns existing ADRs and
+design specs into anchored decisions, also without an LLM.
+
+An optional **semantic pass** (`graphify extract`, which needs an API key for its model
+provider and caches results per file) goes deeper on documentation: it turns prose into
+concepts and themes that records can anchor to. Walkthrough:
+[docs/guides/semantic-docs.md](docs/guides/semantic-docs.md).
+
+## Trust & privacy
+
+- **Local runtime:** Sidegraph reads repository files and the graph, and writes records,
+  a derived index, and optional setup or export files. It makes no network calls of its own
+  and sends nothing anywhere. Installing and updating it downloads it from GitHub. What the agent
+  does with Sidegraph's answers is up to your agent host, which sends them to its model
+  provider like any other context. Graphify's optional semantic pass uses its own model
+  provider. See [SECURITY.md](SECURITY.md) for the data boundary.
+- **Reviewable capture:** text is redacted before storage using best-effort patterns.
+  Review drafts and scan the committed store for secrets. Agent proposals wait for human
+  review unless the project answered yes to auto-ratify in `sidegraph-init`; even then,
+  architecture decisions and domains wait. See the
+  [ratification policy](docs/reference/configuration.md).
+- **Preserved history:** a reversal closes the old record and adds a new one. Only two things
+  change a record in place: review sets its status, and a confirmed file move updates where
+  its anchor points.
+- **Local counts:** for `sidegraph-stats`, Sidegraph counts how often memory was shown. The
+  counts stay in `.sidegraph/index.db`, which is git-ignored and never leaves your machine.
+  To stop counting, set `SIDEGRAPH_TELEMETRY=off`.
+
+## The engine underneath
+
+The graph of your code and documents comes from
+[Graphify](https://github.com/safishamsi/graphify), built without an LLM. Sidegraph only reads
+it and never writes into it. Without a graph, records anchor to files and domains, and recall
+still works. Three things need the graph: anchoring a record to a function, grouping related
+code automatically, and following moved code (see the
+[operations reference](docs/reference/operations.md#the-graph-dependency-stated-plainly)).
+The graph and the local index can be rebuilt at any time. The JSON records in `.sidegraph/`
+cannot: they are the source of truth, so keep them in your repository and backups.
+
+## Status
+
+Sidegraph is in beta. Read the [stability policy](docs/reference/stability.md) before
+building automation against it. By default the plugin follows the latest release; for
+reproducible deployments, [pin a version](docs/getting-started/installation.md#mutable-development-references).
+The [changelog](CHANGELOG.md) records release changes.
+
+The platform badges at the top summarize the 0.13.0 release checks of 2026-10-14: Windows x64
+and macOS arm64 both ran the full plugin session for Claude Code and Codex. The badges are not
+live CI status; see [Platform coverage](docs/getting-started/installation.md#platform-coverage).
+
+## Contributing and support
+
+Bug reports, questions, and feature requests are welcome in
+[GitHub Issues](https://github.com/SantyagoSeaman/sidegraph/issues). Include the commands
+you ran, expected and actual behavior, and package versions; remove secrets from logs.
+For patches, see [Contributing](CONTRIBUTING.md) and the
+[Code of Conduct](CODE_OF_CONDUCT.md). Report vulnerabilities through the private
+channel in [SECURITY.md](SECURITY.md).
+
+The public repository holds the released code; development happens in a private repository.
+Contributions are reviewed here and carried over, with attribution, before the next release.
+
+## Documentation
+
+[Getting started](docs/getting-started/installation.md) ·
+[Concepts](docs/concepts/decision-memory.md) ·
+[Guides](docs/guides/capturing-decisions.md) ·
+[Reference](docs/reference/mcp-tools.md) ·
+[Integrations](docs/integrations/graphify.md) (Graphify · Claude Code · Codex) ·
+[Verify your setup](docs/guides/verifying-your-setup.md) ·
+[Operations](docs/reference/operations.md) ·
+[Pilot kit](docs/pilot-kit/README.md) ·
+[Engineering whitepaper](docs/whitepaper/index.md)
+
+## License
+
+[Apache-2.0](LICENSE).