Skip to content

docs: overhaul README around the ground-and-govern positioning#21

Merged
saldestechnology merged 1 commit into
mainfrom
docs/readme-overhaul
Jul 10, 2026
Merged

docs: overhaul README around the ground-and-govern positioning#21
saldestechnology merged 1 commit into
mainfrom
docs/readme-overhaul

Conversation

@saldestechnology

Copy link
Copy Markdown
Collaborator

Why

The docs site (docs.agentis.tools) and docs/messaging.md were repositioned around a single thesis — ctx is the local quality authority for AI-written code — but the README had fallen out of step. Its opening already carried the new positioning, yet the body was stale: organized as "Two Tools in One" (the old mental model), 830 lines of per-command flag dumps that now duplicate the docs site, and the killer workflow (ctx harness init wiring ctx into Claude Code) barely mentioned.

What changed

Rewrote README.md as a lean front door (~285 lines) that quickly conveys what ctx is and why to care, and stays accurate to the v0.3.1 CLI.

  • Lede — pain + thesis, aligned verbatim with docs/messaging.md, unpacked into scannable Ground / Govern bullets with a concrete proof number (~8k tokens instead of 233k).
  • The loop: index → ground → govern — one real terminal session; ctx index first; proof numbers woven in.
  • One model, two jobs — replaces "Two Tools in One". Context generation (ctx src/ | pbcopy) folded in as one capability under Ground. The 0/1/2/3 exit-code table as the integration API.
  • Drop it into Claude Code — the harness loop (SessionStart→map, PostToolUse→index+check, Stop→score) is now a headline, including the permission guardrails.
  • Compact command table linking to docs, replacing ~25 expanded flag sections.
  • Accuracy fixes — MCP flagged feature-gated; canonical check/score --fail-on vocabulary (no stale audit --min-score/--incremental showcase); every doc link verified against a real page.

Verification

  • All commands, flags, and exit codes cross-checked against src/cli.rs / src/exit.rs.
  • Taglines match docs/messaging.md (the source of truth).
  • All 18 documentation links resolve to existing pages.
  • ctx check passes clean (docs-only change).

Rewrite the README from an 830-line reference manual into a lean ~285-line
front door aligned with docs.agentis.tools and the canonical positioning in
docs/messaging.md.

- Lead with the pain + 'local quality authority for AI-written code' thesis,
  unpacked into scannable Ground/Govern bullets with a concrete proof number.
- Replace the stale 'Two Tools in One' framing with 'One model, two jobs';
  fold context generation in as one capability under Ground.
- Feature the Claude Code harness loop (ctx harness init) as a headline.
- Compact command table linking to the docs instead of ~25 per-command flag
  dumps; flag MCP as feature-gated; use check/score gate vocabulary.
- Correct to the v0.3.1 CLI surface (commands, flags, 0/1/2/3 exit codes).
@saldestechnology
saldestechnology merged commit 18ab34f into main Jul 10, 2026
@saldestechnology
saldestechnology deleted the docs/readme-overhaul branch July 10, 2026 22:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant