Start user-docs/ with the architecture page, and design the site around it

[kiwifellows]

What and why

D-10 chose user-docs/, plain Markdown, and a renderer decided later. This starts the directory and tests that choice against the hardest page in the plan rather than the easiest — an explainer with three complex SVG diagrams, written for security reviewers evaluating TOPS for their AWS organisation.

The choice holds. CommonMark plus tables carried the whole page. The full requirement list turns out to be: Markdown with tables, static assets served alongside, and a theme whose image CSS is one rule away from correct. Every MkDocs- or Docsify-class renderer meets that. Nothing found here argues for a framework, so the deferral stands.

User story

Not a feature. Documentation plus design, against the roadmap's User documentation site workstream and D-10.

What is in here

Four pages written, the priority-1 set from the content map:

Page	For
start-here/how-tops-connects-to-aws.md	Security reviewers approving TOPS for an AWS org
aws-accounts/what-the-iam-role-can-do.md	The same reviewers, once they ask what the permissions grant
using-tops/reading-a-finding.md	Whoever just ran their first scan
using-tops/resolving-a-finding.md	The same person, once they have fixed something

Plus

Path
SECURITY.md	Vulnerability policy. There was none, and README said "open an issue"
user-docs/assets/diagrams/*.svg	Three standalone, self-theming diagrams at a 900px viewBox
user-docs/README.md	Conventions: diagram rules, the seven voice rules, a link check
design/docs-site/information-architecture.md	34 pages across 8 sections, mapped against what exists
design/docs-site/archetypes/*.md	Copyable skeletons with guidance inline
design/docs-site/wireframes.html	Shell, three page archetypes, content map
design/architecture/	The exploration that produced the first page, marked non-canonical
deleted docs/quick-start.md	253 lines describing a Nuxt/Serverless/Prisma stack that is not the product

Findings worth reading before writing the next page

Two bugs that only exist once a diagram is standalone. Both fail as a broken image, which reads as a missing file rather than a syntax error:

• HTML named entities are undefined in XML. A standalone .svg is parsed as XML, so — makes the file fail to render entirely. All numeric references now.
• Angle brackets anywhere in the SVG's CSS, including inside comments, parse as tags.

The diagrams were re-authored at a 900px viewBox. Carried over at 1160px from the full-bleed HTML page, they scaled to 7.5px body text in a docs column — unreadable. At 900px with larger type and zones stacked vertically, they hold above 10px down to an 820px viewport:

viewBox	Layout	Body text	Readable
1160px	Standard column	7.5px	No
1160px	Wide variant @1680px	11.9px	Only above ~1600px
900px	Standard @1440px	12.4px	Yes
900px	Standard @820px	10.6px	Yes

This withdraws a recommendation the design itself first made. An earlier draft proposed a wide-layout variant for explainer pages; it was compensating for over-wide diagrams. With them sized correctly the standard layout is enough and the site keeps one layout instead of two.

Theme requirement, in full: main p:has(> img) { max-width: none } (Markdown wraps images in a <p>, so the prose measure silently caps every diagram at 686px), plus the usual responsive breakpoints. That is all.

How it was tested

No application code changed, so no test suite ran. The page and diagrams were verified by measurement, not by eye:

• All three SVGs parse as XML (xml.etree.ElementTree) — this is what caught both entity bugs.
• Rendered through a deliberately minimal harness (python-markdown + ~60 lines of CSS, no framework) and measured at 1680 / 1440 / 1100 / 820px viewports.
• Geometry checked by comparing every getBBox() against its containing rectangle: found a 4px card overlap and a text run escaping its card, both invisible in review, both fixed. Final state is clean — no overflow, no collisions, nothing outside the viewBox.
• Both colour schemes resolve; no horizontal page scroll at any tested width.

---

Quality gate

• Acceptance criteria are met — the first slice's page-one item, plus the design that sequences the rest
• Solves the user problem simply — Markdown and three SVGs; the framework decision stays deferred
• Follows the practices in docs/practices/ — no page written for a feature that does not exist, verified against PROGRESS.md
• Tests written and passing — none. Documentation and design only
• Documentation updated — this PR is documentation
• No obvious performance issues — three static SVGs, ~8 KB each
• Ready for production — the site is not deployed. Cloudflare Pages is not connected yet

Practices check

• Security — no secrets. The page describes only what is already public in the templates
• Simplicity — the wide-layout variant was removed once it proved unnecessary

Multi-tenancy, Database and Scan definitions are untouched.

Out of scope

• Cloudflare Pages / DNS. docs.teemops.com does not resolve yet.
• Trimming README.md's setup section to link into user-docs/. Worth doing once there is an install page to link to; doing it now would point at nothing.
• teemops.com marketing site — different worktree, per the brief.
• The other 30 pages. Mapped and prioritised, not written.

Two decisions for the reviewer

1. A proposed amendment to D-10, suggested as D-13. D-10 scoped user-docs/ to start from "you're logged in", with README.md canonical for install. That holds for operators but not for reviewers, who read before anything is installed and will not open a GitHub README to do it. The proposal: user-docs/ owns evaluate and use; README.md stays canonical for the commands and the site links out. Not recorded in the log yet — that is your call.
2. This page makes no claim that the SNS topic is locked down, deliberately, because #101 is open. It will want one sentence either way once that lands.

Findings from writing the pages

Both came from reading the code rather than restating the specs, and both changed what the docs say.

The child IAM role's write permissions are not used by anything. TOPS instantiates only STS, SNS and SQS clients — there is no SecurityHub, GuardDuty, Macie, Inspector, Config or CloudTrail code in the repository, and all 36 operations declared across rules/tasks/*/tasks.json are list, get or describe. So the role asks customers for write access across eight services on behalf of features that do not exist. Both pages say so, and show how to strip them. Worth its own issue: trim the template to what is used.

Also: s3:ListAllMyBuckets in TopsS3Bucket can never authorise — it does not support resource-level permissions and the statement scopes it to arn:aws:s3:::tops-config-*. Inert, but a reviewer would find it.

Two gaps closed. SECURITY.md now exists, and the dead docs/quick-start.md is deleted with its four inbound links repointed at the README.

Two blockers on SECURITY.md

The policy names two channels and neither answers yet:

1. GitHub private vulnerability reporting is disabled on this repo — the "Report a vulnerability" link 404s until it is enabled in Settings → Security.
2. security@teemops.com does not exist and needs routing.

🤖 Generated with Claude Code