Skip to content

docs: rewrite the README as a landing page, extract the manual into docs/ (#92) - #94

Merged
2000game merged 1 commit into
mainfrom
docs/readme-overhaul-92
Aug 10, 2026
Merged

2000game merged 1 commit into
mainfrom
docs/readme-overhaul-92

Conversation

@2000game

Copy link
Copy Markdown
Member

Closes #92. Stacked on #93 (the Handbuch split) — merge that first.

The README was 572 lines. It read as a manual, not a front page: the environments story, the entire CI section, the auth handshake and every per-feature detail lived inline, and the actual hook — a config plus the plan it produces — sat around line 140.

After

~210 lines, in the order a newcomer reads:

  1. What it is — structure-as-code, plan/apply, people never managed
  2. Why — a "clicking vs ct" table (audit trail, repeatability, rehearsal env, drift, preview)
  3. Show me — a zero-id config and the ct plan output it produces
  4. Install → first run
  5. What it manages — one table, each row linking to its guide
  6. Environments and CI — four commands, then links
  7. Guardrails, two-repo model, docs index, development, status

The plan output in "Show me" is real renderPlan output, produced by running the renderer over a plan object — not hand-written to look plausible.

Nothing deleted, only relocated

From README To
Environments, protected envs, dev→prod promotion docs/environments.md (new)
CI auth, the auth handshake, --detailed-exitcode, --json shape, drift-vs-config attribution, the PR-comment job docs/ci.md (new)
Portable references, campus assignment, allowDuplicateName, stdout/stderr convention docs/configuration.md (new)
The phase-by-phase status list Deleted — it duplicated #1 and #19, which are linked instead

Verification

  • Every relative link in the README resolves to a file that exists (checked mechanically).
  • Every DSL name in the "What it manages" table checked against ConfigContext — including ct.ageGroup / ct.targetGroup / ct.relationshipType, which the old README never mentioned.
  • npm run lint, npm run typecheck, npm test (570 passed, 5 skipped) → green.

Both claims that had to stay above the fold did: people are never managed, and only explicitly declared or adopted resources are ever touched.

https://claude.ai/code/session_01KPxjSEkqMiU7WE3vg6C3am

…ocs/ (#92)

The README had grown to 572 lines — the environments story, the whole CI
section, the auth handshake and every per-feature detail inline. Someone landing
on the repo could not tell in thirty seconds what this is or how to try it, and
the hook (a config plus the plan it produces) sat around line 140.

README is now ~210 lines in reading order: what it is → why you'd want it (a
clicking-vs-`ct` table) → a config and its real `ct plan` output → install →
first run → what it manages → environments/CI → guardrails → docs → status. The
plan output in "Show me" is genuine `renderPlan` output, not hand-written.

Nothing was dropped; it moved:
- environments + dev→prod promotion  -> docs/environments.md
- CI usage, auth model, --detailed-exitcode, --json shape, PR-comment job -> docs/ci.md
- portable references, campus assignment, allowDuplicateName, output
  conventions -> docs/configuration.md
- the phase-by-phase status list -> the epics it was duplicating (#1, #19)

Claude-Session: https://claude.ai/code/session_01KPxjSEkqMiU7WE3vg6C3am
@2000game
2000game merged commit 8c42830 into main Aug 10, 2026
1 check passed
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.

docs: overhaul the README into a real open-project landing page

1 participant