docs: full currency sweep — the docs were three releases behind - #128
Merged
Conversation
The repository's documentation still described a platform at initial-public-release readiness. Three releases and ~25 shipped features later, several claims were flatly wrong rather than merely stale. Corrections, in order of how badly they misled: - README announced "Password auth only for now; SSO/LDAP ... deliberately not built yet". OIDC shipped in #58. The feature tables were also missing ticket attachments, API tokens, email verification, rules/CoC, the submissions browser, announcement targeting, retention purge and spectator insights; the GHCR examples were pinned to v1.1.0. - UI-INTEGRATION-NOTES described SSO as deferred in two places and said AI was "off the roadmap" (it's milestoned v1.4.0). Adds the 13 surfaces built after the handoff. - ARCHITECTURE §7.1 was missing manage_auth_providers and view_submissions — found by diffing the doc against auth.permissions rather than reading it (the 67 event types all matched). §11.3 predicted SSO would be an *optional* module; it shipped required-core, because module state is per-competition and authentication is a property of the install. That wrong prediction is now recorded next to the real 19-module inventory. - ARCHITECTURE gains §13.4 (outbound network calls). The update check added in #111 had no coverage in the binding design doc at all, which is a poor place for "what does this send where" to be undocumented. - adr/README.md never listed ADR-0021. - CONTRIBUTING said "all four checks". CI runs five, and the missing one is `npm run build` — the only one that exercises prerendering, and the one that broke PR #119. - The in-app AI tab said "Deferred past MVP"; it's scheduled, not dropped. ROADMAP was structurally stale, not just factually: it ended at Tier 3 with no notion of the release milestones that replaced tiers as the unit of planning. Adds a Post-1.0 section covering v1.0.0-v1.2.0 as shipped and v1.3.0-v1.5.0 as planned. Note that `#N` means a roadmap item in the tier half and a GitHub issue in the new half, and the two collide (roadmap item 23 is analytics, issue #23 is insight cards) — called out rather than renumbered, since renumbering would break every inbound reference. CLAUDE.md is restructured rather than extended, 951 -> 331 lines. It had become an append-only build log, ~810 lines of it restating what git log, the ADRs and ARCHITECTURE.md already record — and it had still drifted past 25 features, because nobody rereads 900 lines to check. Appending would have made the failure mode worse. What replaces it: current status, a subsystem map, a "Things that will bite you" section for the traps the code doesn't reveal (commit-before-emit, models/__init__ completeness, migrations-vs-tests, the Y.js singleton pin, MinIO having no local backend, the OIDC proxy/SSRF env traps), and an ADR lookup table. It also still told readers to "work the phases in order", so docs/claude_plans/ gains a README marking those plans finished. Counts asserted in the new text were verified against code, not prose: 38 permissions, 67 event types, 19 modules of which 3 are optional. Likewise the claim that the audit consumer opens its own session (utils/audit_log.py line 28), which is what makes commit-before-emit load-bearing. VISION.md gets a header marking it the founding document — intent, not status — and a note on the two design docs it required that were folded into ARCHITECTURE.md instead of being written. Verified: tsc, eslint, npm run build and 167/167 vitest tests pass. Backend is untouched, so pytest was not run. Co-Authored-By: Claude <noreply@anthropic.com>
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
1 participant
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.
Why
The repository's documentation still described a platform at initial-public-release readiness. Three releases and ~25 shipped features later, several claims were flatly wrong rather than merely stale — the README's headline paragraph told readers OIDC didn't exist.
This is a complete sweep of the platform repository's docs (not flagpost-website).
The corrections that mattered
Ordered by how badly each misled a reader:
README.md:25UI-INTEGRATION-NOTES.md×2ARCHITECTURE.md§7.1manage_auth_providers,view_submissionsARCHITECTURE.md§11.3ARCHITECTURE.mdadr/README.mdCONTRIBUTING.mdnpm run buildMethod note: §7.1 and the event catalogue were checked by diffing the doc against
auth.permissionsandutils.event_catalogin a REPL, not by reading. The 67 event types all matched; two permissions did not.The §11.3 prediction is worth a look — SSO shipped required-core because module state is per-competition and authentication is a property of the install, so an optional
ssomodule would have meant "OIDC works in this competition but not that one". Any future site-wide module (SAML #100, LDAP #101) inherits that shape.ROADMAP
Structurally stale, not just factually: it ended at Tier 3 with no notion of the release milestones that replaced tiers as the unit of planning. Adds a Post-1.0 section — v1.0.0–v1.2.0 as shipped, v1.3.0–v1.5.0 as planned.
#Nmeans a roadmap item in the tier half and a GitHub issue in the new half, and the two collide (roadmap item 23 = analytics, issue #23 = insight cards). Called out in a note rather than renumbered, since renumbering breaks every inbound reference.CLAUDE.md: restructured, not extended (951 → 331 lines)
The one judgement call here, flagged for review.
It had become an append-only build log — ~810 lines restating what git log, the ADRs and
ARCHITECTURE.mdalready record — and it had still drifted past ~25 features, because nobody rereads 900 lines to check. Appending would have made the failure mode worse.What replaces it: current status, a subsystem map, a "Things that will bite you" section for traps the code doesn't reveal (commit-before-emit,
models/__init__completeness, migrations-vs-tests, the Y.js singleton pin, MinIO having no local-filesystem backend, the OIDC proxy/SSRF env traps), setup/dev/demo, and an ADR lookup table.It also still instructed readers to "work the phases in order", so
docs/claude_plans/gains a README marking those plans finished and historical.Accuracy
Counts asserted in the new text were verified against code, not prose: 38 permissions, 67 event types, 19 modules of which 3 are optional. Likewise the claim that the audit consumer opens its own session (
utils/audit_log.py:28) — that's what makes commit-before-emit load-bearing rather than a style preference.Also corrected throughout: v1.2.0 is not tagged. Latest tag is
v1.1.1; the milestone is complete onmainand awaiting a tag. The docs now say that rather than implying a release exists.Verification
tsc --noEmitclean ·eslintclean ·npm run buildsucceeds · 167/167 vitest tests pass.Backend is untouched, so pytest was not run.
🤖 Generated with Claude Code