docs: correct stale README claims, and signpost store migration from the tutorial path - #259
Open
blarghmatey wants to merge 2 commits into
Open
docs: correct stale README claims, and signpost store migration from the tutorial path#259blarghmatey wants to merge 2 commits into
blarghmatey wants to merge 2 commits into
Conversation
An audit of all 38 READMEs, prompted by two `witan-core` claims the #255 review caught. The mechanical half — checking that every referenced path resolves — found one real breakage; the rest came from reading claims against the code. **`packages/witan-core/README.md` was describing an earlier package.** - It listed **2 of 5 extras**. Added `remote`, `observability`, and `sentry`, with the note that `sentry` is additive to `observability` rather than an alternative: `telemetry.py` imports `observability.logging`, which imports `structlog` at module scope, so `sentry` alone is an ImportError. - Its "what's here" list covered **9 of 22 modules**. Documented the missing ones: `cli`, `identity`, `remote/`, `observability/`, `omnigraph_http`, `chunking`, `caching`. - It ended with "still local to each server: the CLI scaffolding", which is now the opposite of the truth — `witan_core.cli` provides `make_app`, `resolve_author`, and `report_install` to both servers. **`witan-code` is no longer local-only, in three places.** The README described the code graph as a "per-repo, local-only" store and its table said "**no — local only**" under Synced. A code graph can now live on a shared `omnigraph-server` — `WITAN_CODE_SERVER` in-cluster, or through the deployed witan MCP tier from outside it — where a CI indexer owns each repo's default view and other writers get per-actor branch views. The bridge store has a cluster graph id (`code-bridge`) for the same reason. `mcp/servers/witan`'s README repeated the claim in passing; corrected there too, keeping the distinction it was actually drawing, which is that those stores are *re-derivable*, not that they are local. **`packages/agent-kit/README.md` quoted floors that had moved** — `witan-council>=0.2.0`, `witan-code>=0.2.0` against a real `>=0.7.2` and `>=0.8.0`. Rather than restate values that will drift again, it now says what the floors are *for* and points at `pyproject.toml`, since duplicating a number that lives elsewhere is what caused this. **The root README predated witan.** Its structure block listed neither `packages/witan-core/`, `docs/`, `docker/`, nor `bin/`, and filed the two servers under a generic "install helpers for common MCP servers" line — the three published packages that are now the repo's main artifacts were invisible. **One genuinely broken path**: `mcp/servers/witan/policy/README.md` cited `tests/../test_render_groups.py`, which resolves to the parent directory rather than `../tests/`. Also corrected a claim I introduced myself yesterday: `AGENTS.md` linked `https://witan-context.readthedocs.io` as though it were live. That project is not registered yet, so both it and the new root-README pointer now say the site is set up to publish there rather than asserting a URL that 404s today. Left alone deliberately: cross-repo references (`ol-infrastructure` paths, upstream omnigraph docs), package-root-relative module shorthand, and `packages/witan-core/CHANGELOG.md`'s `docs/design/…` path, which records where the file was at the time. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017oVnpzjRJQVWq9hJGE2Rs7
The site documented local→shared migration thoroughly and then hid it. The migration runbook was reachable only from the guides index and an ADR, while the natural journey — install locally, use it for a while, then move onto the team's shared store — starts in Get started, which pointed at `deployed-witan.md` and nothing else. Those two guides answer different questions, and conflating them is the reason the gap was easy to miss: `deployed-witan.md` points your *client* at a deployment, `migration-runbook.md` brings your *data* there. Someone who followed the tutorial and accumulated a graph needs the second, and had to already know it existed to find it. - Get started now names both jobs, before the reader has a graph worth keeping, and links the runbook's "Local → shared: the cutover" section directly. - The guides index's "Things people commonly need" table gains a row for each, phrased as the question someone actually arrives with rather than the document's title. The migration row also carries the one fact that makes this a procedure rather than a file copy — a store cannot be moved by copying the directory — because that is the thing a reader most needs to learn *before* they try it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_017oVnpzjRJQVWq9hJGE2Rs7
blarghmatey
force-pushed
the
witan-readme-accuracy
branch
from
August 19, 2026 19:34
feaa4fe to
2916358
Compare
blarghmatey
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
Updates repository documentation to reflect current witan packaging, shared storage, migration, and publishing behavior.
Changes:
- Expands package and repository-structure documentation.
- Corrects stale storage, dependency, and path claims.
- Signposts local-to-shared migration guidance.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
README.md |
Expands repository and package overview. |
packages/witan-core/README.md |
Documents extras and shared modules. |
packages/agent-kit/README.md |
Removes duplicated dependency floors. |
mcp/servers/witan/README.md |
Revises code-store durability wording. |
mcp/servers/witan/policy/README.md |
Corrects a test path. |
mcp/servers/witan-code/README.md |
Documents shared code graphs. |
docs/guides/index.md |
Adds deployment and migration links. |
docs/getting-started/index.md |
Explains migration and client setup. |
AGENTS.md |
Corrects Read the Docs status. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+3
to
+4
| A shared toolkit of AI agent utilities for the team. It holds three published | ||
| Python packages — [`witan-council`](./mcp/servers/witan/README.md), |
| reads, an HTTP endpoint one service serves and another calls, a package one repo | ||
| publishes and others import. The bridge records these as **interface bindings** | ||
| in a single shared, local-only store (`_bridge.omni`, a sibling of the per-repo | ||
| in a single shared store (`_bridge.omni` locally, a sibling of the per-repo |
Comment on lines
+174
to
+176
| (re-derivable caches `branches --prune` may destroy at any time — shareable | ||
| now, but still rebuildable from the source tree, which is the distinction that | ||
| matters here). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
An audit of all 38 READMEs, prompted by two
witan-coreclaims the #255 reviewcaught. The mechanical half — checking that every referenced path resolves —
found one real breakage; the rest came from reading claims against the code.
packages/witan-core/README.mdwas describing an earlier package.remote,observability, andsentry,with the note that
sentryis additive toobservabilityrather than analternative:
telemetry.pyimportsobservability.logging, which importsstructlogat module scope, sosentryalone is an ImportError.ones:
cli,identity,remote/,observability/,omnigraph_http,chunking,caching.the opposite of the truth —
witan_core.cliprovidesmake_app,resolve_author, andreport_installto both servers.witan-codeis no longer local-only, in three places. The README describedthe code graph as a "per-repo, local-only" store and its table said
"no — local only" under Synced. A code graph can now live on a shared
omnigraph-server—WITAN_CODE_SERVERin-cluster, or through the deployedwitan MCP tier from outside it — where a CI indexer owns each repo's default
view and other writers get per-actor branch views. The bridge store has a
cluster graph id (
code-bridge) for the same reason.mcp/servers/witan'sREADME repeated the claim in passing; corrected there too, keeping the
distinction it was actually drawing, which is that those stores are
re-derivable, not that they are local.
packages/agent-kit/README.mdquoted floors that had moved —witan-council>=0.2.0,witan-code>=0.2.0against a real>=0.7.2and>=0.8.0. Rather than restate values that will drift again, it now says whatthe floors are for and points at
pyproject.toml, since duplicating a numberthat lives elsewhere is what caused this.
The root README predated witan. Its structure block listed neither
packages/witan-core/,docs/,docker/, norbin/, and filed the twoservers under a generic "install helpers for common MCP servers" line — the
three published packages that are now the repo's main artifacts were invisible.
One genuinely broken path:
mcp/servers/witan/policy/README.mdcitedtests/../test_render_groups.py, which resolves to the parent directory ratherthan
../tests/.Also corrected a claim I introduced myself yesterday:
AGENTS.mdlinkedhttps://witan-context.readthedocs.ioas though it were live. That project isnot registered yet, so both it and the new root-README pointer now say the site
is set up to publish there rather than asserting a URL that 404s today.
Left alone deliberately: cross-repo references (
ol-infrastructurepaths,upstream omnigraph docs), package-root-relative module shorthand, and
packages/witan-core/CHANGELOG.md'sdocs/design/…path, which records wherethe file was at the time.
Co-Authored-By: Claude Opus 5 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_017oVnpzjRJQVWq9hJGE2Rs7
Stack created with GitHub Stacks CLI • Give Feedback 💬