Repository navigation
[Tracking] Docs and README review 2026-10-14 fixes #487
Description
Summary
This tracker holds the fixes from the docs and README review of 2026-10-14. Five review agents read the README, the community files, the first-run path, the API and runbook docs, and the extension docs. A separate agent checked each finding against the code and tried to refute it. 42 of 46 findings survived. After 2 duplicates were merged, the 40 left are grouped into the issues below.
A link check ran first. Every relative link and heading anchor in the 98 public Markdown files resolves. The repository review of the same day is tracked in #479.
Child issues, in priority order
| Priority | Issue | Why |
|---|---|---|
| 1 | #480 | The Discord invite has expired. It is in 11 places, 3 of them in code. |
| 2 | #481 | security@docs.plus very likely cannot receive mail, and it is the only reporting channel. |
| 3 | #482 | make up-dev cannot serve the webapp, the backend cannot reach Supabase on Linux, and no service gets a push key. |
| 4 | #483 | The first-run docs miss steps and run a demo seed in a hosted project. |
| 5 | #484 | The API docs disagree with the server, and one retry rule can append twice. |
| 6 | #485 | The extension docs disagree with the 2.x code. |
| 7 | #486 | Contributor docs, templates and internal READMEs need small fixes. |
Already tracked
These older issues overlap a child issue. They stay open on their own.
- Correct three stale API documentation claims #235 corrects the service-role sentences in
docs/api/authentication.md. Correct the API, WebSocket and runbook docs where they disagree with the server #484 item 5 edits the same paragraph. - Run the local setup from a clean clone and report every point of friction #149 asks for a clean-clone setup report. Fix the full-Docker dev stack: no webapp source in the container, and no host.docker.internal on Linux #482 and Fix the first-run docs: Supabase Cloud steps, full-Docker order, and local setup gaps #483 are findings of that kind.
- Let docker-compose.dev.yml scale rest-api past one container #236 lets the dev
rest-apiservice scale. Fix the full-Docker dev stack: no webapp source in the container, and no host.docker.internal on Linux #482 item 2 edits the same service block. - Run only reviewed main-branch workflows on the production runner #437 pins the stage runner group to
refs/heads/dev. Tidy the contributor docs, templates and internal package READMEs #486 item 5 shows that branch does not exist. - Write the docs.plus documentation set, phase one: self-hosting and the API #170 is the umbrella for the
docs/api/pages. Correct the API, WebSocket and runbook docs where they disagree with the server #484 corrects some of them.
What only the maintainer can do
- Create the new Discord invite (Replace the expired Discord invite in the docs and the app #480).
- Make
security@docs.plusreceive mail, or drop it, and confirm the Severity table times (Make the security reporting channel reachable, and make SECURITY.md agree with itself #481). - Rule on the dead
.github/CODEOWNERSline (Tidy the contributor docs, templates and internal package READMEs #486).
Not filed
The review checked these and dropped them:
- A version line in the README. The release badge and the Releases page cover it.
- A Status line in ADR 0001. The house ADR format allows its short form.
execwithout--indexafter a rolling deploy. Compose handles that case.- A Windows line-ending risk. Inside WSL2, Linux git does the clone.
Generated by Claude Code
Activity
HMarzban commentedon Oct 21, 2026
Closing, 2026-10-21
Every child is closed: #480, #481, #482, #483, #484, #485 and #486. The three maintainer items are done: the new Discord invite (#480), the security reporting channel (#481), and the dead CODEOWNERS line (#486). The repository review of the same day stays tracked in #479.