Release 0.14.0: public /docs user guide (DOCS.md served at /docs)
Ships DOCS.md and the /docs route — a plain-prose translation of SPEC.md for users, distinct from the binding spec. Originating need was the admin-vs-owner role distinction on /admin/users (§6.1); response is a single guide that covers the framework's user-facing surfaces end-to-end (roles, proposing, branches, PRs, graduation, notifications). Mirrors /philosophy: markdown file at repo root + sibling backend loader + MarkdownPreview render. No schema migration. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -23,6 +23,79 @@ skip versions are the composition of each intervening adjacent
|
||||
release's steps in order — no A-to-B path is pre-computed beyond
|
||||
that.
|
||||
|
||||
## 0.14.0 — 2026-05-28
|
||||
|
||||
**Minor — no operator action required; new optional env var.** This
|
||||
release ships `DOCS.md` and the `/docs` route — a public-facing user
|
||||
guide that translates `SPEC.md` into plain prose for readers,
|
||||
proposers, and contributors. The originating need was the
|
||||
admin-vs-owner distinction on the `/admin/users` surface (the §6.1
|
||||
role separation was load-bearing but only documented in spec voice);
|
||||
the response was a single guide that covers the framework's user-
|
||||
facing surfaces end-to-end. Mirrors `/philosophy` end-to-end: a
|
||||
markdown file checked into the repo root, served by a sibling backend
|
||||
loader, rendered with `MarkdownPreview`. No schema migration. No
|
||||
required env-var changes. The new "Docs" header link sits alongside
|
||||
the persistent "About" link from §14.3 and is reachable by anonymous
|
||||
viewers per the same v0.3.0 anonymous-read contract.
|
||||
|
||||
### Added
|
||||
|
||||
- **`DOCS.md`** at the repo root — the user-facing guide. Covers
|
||||
reading anonymously, signing in, proposing an RFC, super-drafts vs
|
||||
active RFCs, the discussion-vs-contribution distinction (§10.10),
|
||||
working on a branch (contribute mode, AI proposals, manual edits,
|
||||
flags, branch visibility, contribute grants, hygiene), opening and
|
||||
reviewing PRs, graduation (§13), withdrawal and reopening, the AI
|
||||
participant (§6.6 / §6.7 / §18), notifications and watch states
|
||||
(§15), and the full roles-and-permissions story (§6 in plain
|
||||
prose: anonymous / contributor / admin / owner, per-RFC
|
||||
owners + arbiters, per-branch contribute grants, the write-mute,
|
||||
and the three structurally distinct "mutes"). Framework-neutral —
|
||||
no deployment-specific names or corpus references; consistent with
|
||||
`CLAUDE.md`'s separation-of-concerns rule.
|
||||
- **`backend/app/docs.py`** — sibling loader for `philosophy.py`.
|
||||
Reads `DOCS.md` from the repo root with the same disk-first,
|
||||
in-process-cached, `refresh()`-on-demand shape. Optional
|
||||
`DOCS_PATH` env var points at an alternative source (e.g. a
|
||||
meta-repo working-tree clone) for deployments that prefer that.
|
||||
- **`§17` endpoint** — `GET /api/docs` returns
|
||||
`{ "body": "<DOCS.md verbatim>" }`. Anonymous-reachable, same
|
||||
contract as `GET /api/philosophy`.
|
||||
- **`frontend/src/components/Docs.jsx`** — the `/docs` reading
|
||||
surface. Mirrors `Philosophy.jsx`: chrome with Back / "USER GUIDE" /
|
||||
Home affordances, body rendered through `MarkdownPreview`.
|
||||
|
||||
### Changed
|
||||
|
||||
- **`backend/app/api.py`** — imports `docs as docs_mod` alongside
|
||||
`philosophy` in the relative-import block; registers the new
|
||||
`GET /api/docs` handler immediately after `GET /api/philosophy`.
|
||||
- **`frontend/src/api.js`** — exports `getDocs()` alongside
|
||||
`getPhilosophy()`. Same fetch shape, different endpoint path.
|
||||
- **`frontend/src/App.jsx`** — imports `Docs` alongside `Philosophy`,
|
||||
registers the `/docs` route alongside `/philosophy`, adds the
|
||||
persistent "Docs" header link alongside "About", and adds the
|
||||
`DocsWithSidebar` chrome wrapper alongside `PhilosophyWithSidebar`.
|
||||
|
||||
### Upgrade steps (from 0.13.0)
|
||||
|
||||
- You **MUST** rebuild the frontend and restart the backend after
|
||||
upgrading so the new `/docs` route, the new endpoint, and the new
|
||||
loader are picked up. `frontend/package.json#version` and `VERSION`
|
||||
both move to `0.14.0`. No schema migration; the new endpoint
|
||||
serves a checked-in file.
|
||||
- You **MAY** set `DOCS_PATH` to an absolute path if your deployment
|
||||
hosts `DOCS.md` outside the framework's repo (e.g. as a sync target
|
||||
from a content repo). Unset is supported — the framework's
|
||||
`DOCS.md` at the repo root is the default, mirroring how
|
||||
`PHILOSOPHY_PATH` works for `/api/philosophy`.
|
||||
- You **MAY** customize `DOCS.md` for your deployment if you want
|
||||
deployment-specific phrasing layered on top of the framework's
|
||||
guide. The file is a regular markdown source; standard `vim`/`git`
|
||||
edits suffice. Framework upgrades that ship a new `DOCS.md` will
|
||||
show as a normal merge in your deployment-overlay layer.
|
||||
|
||||
## 0.13.0 — 2026-05-28
|
||||
|
||||
**Minor — schema migration required; new optional env vars.** This
|
||||
|
||||
Reference in New Issue
Block a user