docs: two-voice (civic staff + IT) overhaul with architecture diagrams - #11
Merged
Conversation
…th architecture diagrams
All audience-facing docs now have a clearly separated civic-staff (plain English)
section and an IT/technical section with architecture drawings:
- USER-MANUAL.md: Part 1 (civic staff) + Part 2 (IT) with 3 Mermaid diagrams
(deployment, trust-flow sequence, data-model ER), full API table, security, ops.
- docs/index.html: civic panels + a "For IT & technical staff" section with an
inline SVG deployment diagram and an at-a-glance table.
- README.md / README.txt: two-voice split; README.txt carries an ASCII architecture
sketch. USER-MANUAL.txt mirrors the two-part structure in plain text.
- docs/github-discussions-seed.md: civic-staff posts + technical posts (with a
Mermaid diagram and a v0.4.0 change summary).
Also corrects stale facts the old docs carried (SQLite-as-default, missing /analyze,
the write token, and audit events) to match the shipped v0.4.0 behavior.
Adversarial 3-lens doc review (accuracy-vs-code, consistency/honesty, clerk
readability) run before commit; all findings fixed: added the missing `disclaimer`
column to the data-model diagram; removed "token"/raw-URL-path jargon from the
clerk sections (now "staff password" + named surfaces); fixed a landing-page
overclaim ("every check" -> "every review you save"); quoted Mermaid edge labels.
Co-Authored-By: Claude Opus 4.8 <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.
Every audience-facing doc now has two clearly separated voices — a civic-staff (plain-English) section and an IT/technical section with architecture drawings.
docs/index.html) — civic panels + a "For IT & technical staff" section with an inline SVG deployment diagram..txtcarries an ASCII architecture sketch.USER-MANUAL.txtmirrors the two-part structure.Also corrects stale facts (SQLite-as-default, missing
/analyze, write token, audit events) to match shipped v0.4.0.An adversarial 3-lens doc review (accuracy-vs-code, consistency/honesty, clerk readability) ran before this PR; the technical lens confirmed the docs match the code, and all findings (1 data-model diagram drift + clerk-jargon polish) were fixed. verify-docs + version-surface gates pass locally.
🤖 Generated with Claude Code