docs: Give every rule an address — specs, invariants, and an indexed AGENTS.md

[korya]

Problem

An agent (or human) landing in this repo met an 80-line AGENTS.md rulebook — excellent, incident-anchored rules, but with no stable IDs to cite in PRs or tests, no separation between product behavior, system invariants, architecture and process, and no index saying what to load when. Today's work added five more rules to the pile and made the missing structure obvious.

Solution

Relocate, don't rewrite: every rule keeps its prose and its incident citation, and gains a stable address.

AGENTS.md (50 lines: pitch · stack · layout · doc index with load-when hints · process digest)
└── docs/
    ├── architecture.md        layers, mechanisms, tech choices
    ├── guidelines.md          lint/test, planning checklist, 5-whys regression protocol, releases
    ├── plans/                 (untouched — append-only dated blueprints)
    └── product-specs/
        ├── invariants.md      INV-1..18   the relocated rulebook, citations intact
        ├── app.md             APP-1..14   workspace behavior
        ├── agents.md          AGENT-1..9  MCP tools + skill contract
        └── site.md            SITE-1..8   discovery surface

• Specs are behavioral and self-evidently testable — "Exports include the 4-module quiet zone", never "the function returns". Feature specs that named internals were rewritten until they didn't.
• Invariants keep their voice. INV-1 ("plausible output is the characteristic bug") through INV-18 are the AGENTS.md paragraphs, lightly merged where bullets described one rule, with Empty vCard form still counts as encodable content (READY + export enabled) #36/History Delete and Clear all are instant, irreversible, and unconfirmed #41/Only the most recent destructive action can be undone #57/The storage-full notice can render below the fold on short viewports #61/Flaky: 'keeps a design that arrived as a share link' failed once in ~20 runs #65/fix(web): Hold the QR code still when an advisory appears below it #66/Crawlers that do not run JavaScript see an empty page #78/Every visit loads fonts from Google while the page promises data never leaves the machine #81 receipts preserved.
• IDs are stable forever — never reused or renumbered; deletions leave holes. PRs and tests can now cite INV-14 or SITE-3 and mean something durable.
• Scope was user-confirmed before writing: full relocate-and-index, three minimal spec files.

No behavior change anywhere — this PR is entirely markdown. just lint formats it; the full suite passes untouched.

Other Changes

• The docs index in AGENTS.md now names .agents/skills/ and tools/ in the layout tree, which the old file had only partially.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Xdn1qjhVf458uJ42tjKC6m

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
qr-code-generator	Ready	Preview	Aug 11, 2026 7:37pm