docs: align README + governance docs with current state (uninstall, files, ADR index, ship-archive) - #59
Merged
Conversation
…iles, ADR index, ship-archive) Multiple documentation polish items rolled into one PR (one layer: "docs alignment with current state"). ### README.md - **Uninstall section** added between Server Setup and Client Setup (was missing — `node uninstall.mjs` exists but went undocumented). - **OpenClaw definition** added as a footnote on first README mention (the architecture diagram and Supported Tools table both reference OpenClaw without ever defining it). - **Repository Layout section** added before Security — table of top-level files (server.mjs, setup.mjs, uninstall.mjs, keys.mjs, models.json, ocp/ocp-connect, dashboard.html, scripts/, .claude/skills/, ocp-plugin/, docs/adr/, ALIGNMENT.md, AGENTS.md, CLAUDE.md) so a new contributor knows what each file does. - **LICENSE link** added to the License section footer. ### docs/adr/README.md (new) - Index of the three published ADRs (0002, 0003, 0004) with a one-line description each. - Explains the `0001` placeholder (early internal proposal that was superseded; numbering deliberately starts at `0002`). - Guidance on when to write a new ADR vs. when a commit message suffices. ### Spec/plan housekeeping - `specs/.gitkeep` removed (the empty `specs/` placeholder confused the picture; canonical paths are `docs/superpowers/plans/` for active plans and `docs/superpowers/specs/` for long-lived design docs that other code references). - Shipped plans moved to `docs/superpowers/plans/shipped/`: - `2026-04-10-lan-mode.md` (shipped: README LAN mode section) - `2026-04-25-47-sse-heartbeat-plan.md` (shipped: v3.12.0 per CHANGELOG) - `2026-04-25-47-sse-heartbeat-design.md` left in `docs/superpowers/specs/` unchanged because both `server.mjs:565` and `CHANGELOG.md:7` link to that exact path; moving it would require a `server.mjs` edit, which needs `cli.js` citation per ALIGNMENT.md Rule 1. ### AGENTS.md - Updated "Key files to know" to add `docs/adr/README.md`, `docs/superpowers/plans/`, and `memory/constitution.md`. - Note explaining `memory/constitution.md` is spec-kit's standard location, distinct from `~/.cc-rules/memory/` and `ALIGNMENT.md`. - Updated "Handoff expectations" item 5 from `docs/superpowers/specs/*/tasks.md` (which never matched anything — there were no `tasks.md` files there) to `docs/superpowers/plans/` (excluding `shipped/`). ### Coordination with PR #53 PR #53 is open and adds "Why OCP?", "Comparison", and "Governance" sections to README. This PR deliberately avoids those areas — only edits the Supported Tools table footnote, inserts Uninstall before Client Setup, inserts Repository Layout before Security, and updates the License footer. No expected merge conflict. Refs: audit findings M6, M8, M9, M11, L2, L3, L6.
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
2 participants
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.
Summary
One layer of doc polish (audit findings M6, M8, M9, M11, L2, L3, L6 rolled up).
README.md additions
node uninstall.mjsexists but was undocumenteddocs/adr/README.md(new)ADR index for the three published records (0002, 0003, 0004), explanation of why numbering starts at 0002, and a "when to write a new ADR" guide.
Spec / plan housekeeping
specs/.gitkeepdocs/superpowers/plans/shipped/:2026-04-10-lan-mode.md(shipped: README LAN mode section is live)2026-04-25-47-sse-heartbeat-plan.md(shipped: v3.12.0 per CHANGELOG)2026-04-25-47-sse-heartbeat-design.mdbecauseserver.mjs:565andCHANGELOG.md:7both link to that exact path. Moving it would require aserver.mjsedit, which needscli.jscitation per ALIGNMENT.md Rule 1. Left in place; documented this caveat in AGENTS.md.AGENTS.mdupdatesdocs/adr/README.md,docs/superpowers/plans/, andmemory/constitution.mdto "Key files to know"docs/superpowers/specs/*/tasks.mdtodocs/superpowers/plans/Coordination with PR #53
PR #53 (open) adds "Why OCP?", "Comparison", and "Governance" README sections. This PR deliberately avoids those areas — only edits the Supported Tools table footnote, inserts Uninstall + Repository Layout in non-overlapping spots, and updates the License footer line. Expected: no merge conflict. If conflict surfaces, this PR can rebase trivially.
Test plan
git statusclean post-commitdocs/superpowers/specs/2026-04-25-47-sse-heartbeat-design.mdstill exists at the pathserver.mjs:565andCHANGELOG.md:7referencespecs/ordocs/superpowers/specs/*/tasks.mduninstall.mjsdoes (handles legacy + current service names, does not delete~/.openclaw/or~/.ocp/)