chore: comment cleanup and layered architecture docs

[JArmandoAnaya]

Documentation-only work in two independent workstreams. No runtime behaviour, test assertion,
type, or generated artifact changes.

A — Comment and docstring cleanup

Code comments and docstrings across src/visionset/, frontend/, tests/, scripts/ and
examples/ cite issue and PR numbers as their explanation. A bare number is a pointer, not a
reason: a reader in an editor, in a vendored copy, or in a fork cannot follow it, so the comment
carries nothing on its own.

The rule applied to every such comment, exactly one of:

1. The prose already explains itself and the number is a breadcrumb — drop the number, keep and
   tighten the prose.
2. The meaning depends on the referenced issue — read it, carry the actual reason into one or two
   compact sentences, then drop the number. A reference survives only where the history itself is
   the point, and only after a self-contained explanation.
3. The comment is noise — it restates the code or narrates a past refactor with no surviving
   lesson — delete it.

Independently of references, verbose comments get shortened: one to three sentences for a
rationale, and a docstring states what the thing does and why it exists rather than how it came
to be. A comment encoding a real invariant or a non-obvious constraint is never deleted, only
rewritten shorter.

Out of scope: README.md, DESIGN.md, AGENTS.md, CONTRIBUTING.md, everything under docs/,
.agents/skills/, CHANGELOG.md, and generated artifacts (openapi.json,
frontend/ui-core/src/generated/). Prose documents cite issues deliberately.

B — Layered architecture documentation

A new docs/architecture/ tree that can be walked top-down: an entry point with a system
overview, then a page per layer, each with a Mermaid diagram GitHub renders natively. Backend
pages cover the kernel and its purity contract, the FastAPI adapter, the CLI and MCP surfaces,
the exporter plugin system, and the shared wire shapes. Frontend pages cover the headless
annotator boundary, ui-core, and the router shell. A cross-cutting page collects the two
machine-enforced boundaries, the capabilities contract, and the batch lifecycle at a glance.

Existing pages under docs/ are not rewritten — the new tree links to them, and to the skills
under .agents/skills/ and to DESIGN.md, which stay authoritative for their topics. A restated
rule becomes stale misinformation. docs/README.md gains an index entry for the tree.

Every claim is verified against HEAD — the import-linter contracts in pyproject.toml, the
workspace package.json files, the lint gates — before it is written.