docs(readme): rewrite as concrete show-dont-tell description#3190
Conversation
|
Warning Review limit reached
Next review available in: 29 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: ASSERTIVE Plan: Pro Run ID: ⛔ Files ignored due to path filters (8)
📒 Files selected for processing (3)
📝 WalkthroughWalkthroughREADME.md was substantially rewritten to present current demo commands, archive workflows, interfaces, installation steps, project status, development commands, and security guidance in a shorter structure. ChangesREADME rewrite
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 70-74: Update the tool-activity example in README.md to use the
documented CLI structure of find QUERY followed by the action pipeline,
replacing the current direct pipeline invocation while preserving its filtering,
grouping, and count behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro
Run ID: c81c6883-eb7d-4b82-8a0d-2172d4f2bd78
📒 Files selected for processing (1)
README.md
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ac596c7e09
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| Each origin is captured at full fidelity — roles, prose, thinking, tool calls | ||
| and results, attachments, session metadata — as far as the source provides |
There was a problem hiding this comment.
For users relying on Polylogue as a complete archive, this promises more than the importers preserve: docs/providers/claude-code.md:48-50 says workspace file-history snapshots are retained only as metadata, and polylogue/sources/parsers/antigravity.py:44-50 explicitly models partial exports where sessions can be dropped. Restore the removed uneven-fidelity caveat rather than claiming every origin is captured at full fidelity.
Useful? React with 👍 / 👎.
| opt-in (`--semantic`) that requires configuring an embedding provider — | ||
| that is the only path where any text leaves your machine, and | ||
| `polylogue ops embed preflight` shows the cost before anything is sent. |
There was a problem hiding this comment.
For deployments enabling a non-default Sinex mirror or primary mode, semantic embeddings are not the only path that can transmit archived text: polylogue/sinex/material_adapter.py:498-517 places message text and blocks in publication payloads, and polylogue/sinex/service.py:315-320 sends those payload bytes through the configured transport. Scope this privacy claim to the default standalone configuration or disclose the Sinex publication path.
Useful? React with 👍 / 👎.
|
HOLD until the v42 rebuild promotes (operator direction): the show-blocks currently use the synthetic demo corpus, which reads as contrived. Once the restored archive is promoted and verified, the "See it work" outputs get regenerated from the REAL archive (operator authorized: standard dev content is not private by default; curate/redact judiciously) — cross-origin find hits, a real transcript, real error-by-tool counts — with the demo-seed commands demoted to a runnable-demo note beside Install. Do not merge before that swap. |
#3202) ## Summary Collapses the MCP server's role ladder (`read < write < review < admin`) into independent, config-only capability opt-ins per polylogue-800m: the server is read-only by default; write (`write`/`run`), judge (`judge`), and maintenance (`maintenance`) are each an explicit, independent boolean opt-in resolved once at server startup from `polylogue.toml` `[mcp]` or `POLYLOGUE_MCP_*_ENABLED` env vars. There is no ladder — enabling one capability never implies another — and no `--role` CLI flag anywhere in the stack. ## Problem The operator decided (2026-07-20, polylogue-800m) that the MCP role ladder is not a product concept worth keeping: `--role read/write/review/admin` modeled an ordered tier where each level silently included the previous one's authority, which is both more machinery than the actual requirement (independent per-capability opt-in) and a worse security default (enabling `review` to unlock `judge` also silently re-exposed `write`/`run`). Per the repo's no-compat doctrine this is a hard removal, not a deprecation. ## Solution - **`polylogue/config.py`**: three new layered config keys following the existing single-resolver (`PolylogueConfig`) pattern — `mcp_write_enabled`/`mcp_judge_enabled`/`mcp_maintenance_enabled` (`[mcp]` TOML table, `POLYLOGUE_MCP_*_ENABLED` env, all default `False`). - **`polylogue/mcp/declarations/models.py`**: new `MCPCapabilities` frozen dataclass (three independent booleans + `.allows(required)`) replaces `MCPRole`/`MCP_ROLE_ORDER`/`mcp_role_allows`. Every declaration's `minimum_role: MCPRole` becomes `required_capability: MCPCapabilityFlag | None` (`None` = always-on read tool). - **`polylogue/mcp/declarations/{registry,adapter}.py`**, **`polylogue/mcp/{server,server_cutover,server_support,cli}.py`**: the 10-dispatcher registration/gating (6 read + `write`/`run` behind `write`, `judge` behind `judge`, `maintenance` behind `maintenance`) now reads `MCPCapabilities` instead of a role string. `polylogue-mcp` (`mcp/cli.py`) drops `--role` entirely and resolves capabilities from `load_polylogue_config()` at startup — config is the sole authority, not a launch argument. - **`polylogue/agent_integration/{spec,manifest,installer}.py`**, **`polylogue/cli/commands/agent.py`**: the parallel "role" vocabulary in the native-client installer/manifest system (`ROLES`/`ROLE_ORDER`, `polylogue agent manifest/install --role`) collapses the same way — `polylogue agent manifest/install` gained `--enable-write`/`--enable-judge`/`--enable-maintenance` flags. The installer now emits `POLYLOGUE_MCP_WRITE_ENABLED=1` etc. into the generated MCP client entry's `env` block instead of `args: ["--role", ...]` — this is real wiring (the client launches `polylogue-mcp` with that env, which `load_polylogue_config()` picks up), not just a renamed no-op. `InstallOptions`' on-disk state schema bumped `STATE_SCHEMA_VERSION` 1→2 (role→capabilities field shape) so stale state fails closed via the existing integrity gate instead of silently exposing a missing field. - **`nix/agent-integration-module.nix`**: `mcpRole` enum option replaced by three independent `mcpEnableWrite`/`mcpEnableJudge`/`mcpEnableMaintenance` booleans (Home Manager module), each off by default. - **Docs**: `docs/mcp-reference.md`, `docs/mcp-integration.md`, `docs/architecture-spine.md` (decision log entry), `docs/daemon-threat-model.md`, `docs/architecture-hotspots.md` — role/`--role` prose replaced with the config-opt-in description. `docs/agent-manual.md`, `docs/agent-integration-reference.md`, and the packaged `polylogue/agent_integration/data/*.{md,json}` assets regenerated via `devtools render agent-manual`/`render mcp-equivalence`/`render mcp-tool-index`. - **Registration traps** (all four): `tests/infra/mcp.py::EXPECTED_TOOL_NAMES` (now derived from `declared_tool_names(ALL_CAPABILITIES)`), the `TOOL_CONTRACT` envelope tests, `docs/generated/mcp-equivalence.json` (`render mcp-equivalence`), and `docs/mcp-reference.md`'s generated tool-index appendix (`render mcp-tool-index`) — all regenerated and green. - **Tests**: `tests/unit/mcp/test_privileged_tools.py`'s `TestRoleGating` became `TestCapabilityGating`, asserting the *independent-flag* behavior directly (e.g. `judge=True` alone must not also expose `write`/`run` — the old ladder-based test asserted the opposite). All other `build_server(role=...)`/`declared_tool_names("admin")`-style call sites across `tests/unit/mcp/`, `tests/unit/agent_integration/`, `tests/unit/{maintenance,storage,cost,archive/query}/`, `tests/integration/test_mcp.py`, and `devtools/verify_agent_integration.py` updated to the capability model. **Design note (deferred, not built here):** the second half of polylogue-800m — assertion judgment at agent scale (policy/automation-driven, human review reserved for escalations, replacing the per-assertion human-review pipeline that doesn't scale) — is design-only per the task brief. Summary for the coordinator to bead separately: the `judge` MCP dispatcher and `judge_assertion_candidates` API already support bulk, policy-shaped decisions (accept/reject/defer/supersede with reason + provenance); what's missing is an *automation* actor that calls `judge` on a schedule/trigger using declared acceptance policy per `AssertionKind`, with an explicit escalation path (a `defer`+flag that routes specifically to human review) rather than every candidate defaulting to human attention. That's a new policy-engine + trigger surface, not a schema or MCP-surface change, and is out of scope for this PR. **Sequencing with #3190:** #3190 (README rewrite, branch `docs/readme-rewrite`, currently open) contains an MCP config example using `--role read`. That branch was intentionally not touched here per the task brief. Whichever of #3190 / this PR merges second should rebase and drop the `--role` flag from its README example — the flag no longer exists after this PR merges. ## Verification - `devtools render all --check` → sync OK, no drift (all generated MCP/agent docs and JSON assets committed after regeneration). - `devtools verify --quick` → ruff format/check, `mypy --strict`, render all, topology, layering, closure-matrix, manifests, ci-workflows, doc-commands, docs-coverage, test-infra-currency, test-clock-hygiene, pytest-timeout-overrides, degrade-loudly — all exit 0. - `devtools test tests/unit/mcp tests/unit/agent_integration` → 214 passed, 1 pre-existing unrelated failure (`test_manual_contract.py::test_generated_continuation_token_decodes_to_the_bound_result` asserts a stale `q1.` continuation-token prefix against the current `q2` codec; reproduced identically on unmodified `master`, unrelated to this change). - `devtools test tests/unit/maintenance tests/unit/storage/{test_query_parity,test_retrieval_readiness_laws,test_surface_parity_adapters} tests/unit/cost/test_contract_suite.py tests/unit/archive/query/test_continuation_surface_parity.py tests/integration/test_mcp.py` → pre-existing unrelated failures only (`KeyError: 'search'`/`'list_sessions'`/`'list_tags'` — these tests call individual MCP tool names retired by the earlier six-tool cutover, unrelated to the role→capability collapse; same failures reproduce on unmodified `master`). Ref polylogue-800m --------- Co-authored-by: Claude <noreply@anthropic.com>
Regenerate the See it work section against the author's own live Polylogue archive (v42 rebuild, promoted) instead of the synthetic demo-seed corpus: cross-origin find hits, a real transcript excerpt, and real error-by-tool counts from this repo's own dev sessions. Demote demo seed/demo verify to a runnable-demo note beside Install. Ref polylogue-93cp
ac596c7 to
54d8f86
Compare
|
Real-output swap done (v42 rebuild promoted, per the HOLD above). Ref polylogue-93cp. What changed: the three "See it work" blocks now run against the author's own live archive (
The CodeRabbit's inline suggestion (use Real excerpts included (full list for privacy audit — all are this repo's own development content, no credentials/PII/other-person content):
Rebase: branch was ~25 commits behind Verification: Not merging — leaving for operator review per the standing hold. |
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QUsH3Rhq6oAZpYPWcsZqnZ
The rewrite (deliberately) dropped the 'local evidence system' epistemology sentence, which orphaned the projected category.local-evidence-system claim (quick-gate public-claims failure: 'projected claim is not covered by a public-surface marker'). Re-attach the marker to the rewrite's category sentence and update the declared publication wording to match; claim key stays stable. Generated public-claims views re-rendered. Ref polylogue-93cp Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QUsH3Rhq6oAZpYPWcsZqnZ
|
Coordinator wrap: hold condition (real-output swap) satisfied by the lane; coordinator privacy audit of every real excerpt passed (all content is this repo's own dev history — operator-authorized; no credentials/PII/third-party/off-project content). The CI-only quick-gate failure was the public-claims gate: the rewrite orphaned category.local-evidence-system by dropping its marker — fixed by re-attaching the marker to the rewrite's category sentence and aligning the declared publication wording (claim key stable), claim views re-rendered. Merging on green gate. |
## Summary Iteration 2 of the README (operator-directed: richer, more impressive real examples, better readability/aesthetics). Adds: archive-scale framing (83K sessions / 4.7M messages), per-year histogram, pytest-by-exit-status block (shows the structural `unknown` lane), and a Mermaid data-flow diagram. All outputs are real, captured against the live archive 2026-07-22 and privacy-reviewed (aggregates + this repo's own dev content only). ## Problem The rewritten README (#3190) shows real outputs but stays narrow: three examples, no visual structure, no sense of archive scale. ## Solution - Mermaid flowchart: sources → source.db → index.db (+user.db) → CLI/MCP/HTTP/Python. - Scale sentence verified against the daemon heartbeat (83,198 / 4,761,552). - Year histogram with an honest note: dated top-level sessions only — fact-checking this surfaced a real P1 (`polylogue-m3p9`: 79% of sessions have NULL sort_key, so `since:` silently excludes them). - pytest outcome aggregate: 12,861 ok / 1,039 failed / 115 unknown. ## Verification - `devtools verify public-claims --json` → ok: true (marker intact). - `devtools verify --quick` → exit 0. - Every console block re-run verbatim before inclusion. Ref polylogue-93cp 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01QUsH3Rhq6oAZpYPWcsZqnZ <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated the “See it work” section with a Mermaid diagram illustrating the ingestion-to-surfaces workflow. * Refreshed example descriptions to clarify that they use real archive commands. * Added an example showing tool activity grouped by actual `pytest` exit status, including unknown results. * **Bug Fixes** * Recorded completion of a maintenance optimization for bulk search-index deletions, with verification and regression coverage. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
1 participant
Ref polylogue-93cp (follow-up: operator judged the incremental fix insufficient — full rewrite, reasoned from structure).
Summary
Complete README rewrite. The old README was an argument about the project's epistemology ("local evidence system", "bounded contract proof", "construct-valid", claim-ledger links) written in internal QA vocabulary, led with the nichest demo (
demo receiptson synthetic data — also the hero image's content), and showed almost no actual output. The new README is a concrete description of what the tool is, ordered by a cold reader's questions, with real command output shown at every step.Structure (reasoned, not predicted)
demo seed, cross-originfind,read --view transcript,actions where is_error … | group by tool | count). Every output block was executed against a fresh scratch demo archive during writing; nothing is invented.init→polylogued run→import), origin table with how each source arrives.Removed
evidence-receipt.png) — its content was the receipts demo, which is not what the product is; the core loop is now shown as text output directly. The asset remains under docs/examples for docs/visual-evidence.md.read --first --view messagesuses a--firstflag the read verb does not have (verified againstpolylogue read --help; the chain silently degrades to a hit list). All commands in the rewrite are copy-paste-verified.Verification
POLYLOGUE_ARCHIVE_ROOTscratch demo seed; outputs pasted from real runs (trimmed with...only).devtools render all --check→ exit 0, no "out of sync" (public-claims view regenerates identically — it derives from the assertion store, not README markers).devtools verify --quick→ exit 0 (16/16).Summary by CodeRabbit