---

kind: record status: live

📚 Dioreo — Documentation Map

Read this if you're unsure which doc file does what, when to touch it, or how they relate. This is the front door to the project's records. It doesn't hold project content itself — it points at where each kind of content lives and who's responsible for keeping it current.

The one rule that ties them together: when you "document" a change (see the numbered rules in ~/.claude/WORKING-AGREEMENT.md), that means updating every relevant layer in the same turn — not just one. The changelog is the layer that historically keeps getting skipped. Under the Branch → Commit → Push → PR → Merge → Deploy workflow (adopted 2026-07-24 12:24 EDT, see project_git_workflow memory), docs ride IN the PR's diff — drafted on the branch as the change happens, finalized on the branch in the final pre-merge checkpoint (so they fold into the squash commit — see step 8). A merged PR in this repo isn't finished until CHANGELOG.md was touched (the doc-check hook now fires on gh pr merge, not on every branch checkpoint commit).

---

📁 First: which FOLDER does a thing belong in?

Settled 2026-08-06 08:33 EDT, after three reorganizations in two days that all had the same cause — a file sitting in a folder whose purpose it didn't match. The test is what KIND of thing it is, never what it is about. A Discord-rendering topic can legitimately belong in any of these.

Folder	It holds	Tense	It is NOT	When it goes out of date
reference/	Lookup docs — "read this to do the thing correctly." A legend, not a notebook.	Present, kept true	Not narrative · not open work · not a story	Correct it in place.
ideas/	Forward-looking and MAINTAINED — proposals, parked ideas, and the intake scratchpad.	Future / undecided	Not decided work (→ db-deferred-list.md) · never published	Edit it — the thinking moved.
superpowers/specs/	Dated design SNAPSHOTS — what was decided and why, on that date.	Frozen at its date	Not a live document	Write a NEW dated one. A stale spec is correct; don't "fix" it.
superpowers/plans/	Implementation plans — the approved way a piece of work gets built, each carrying the ## Audit log of its falsification pass (.claude/rules/plan-drafting.md).	Frozen once built (some stay live while the work is open)	Not a design snapshot (→ superpowers/specs/) · not a mockup	Mark it superseded and write a NEW dated plan.
superpowers/mockups/	Interactive mockup packages and their COMPANION.md. kind: reference — maintained, not frozen (the full row is in CLAUDE.md's docs/ folder table).	Present, kept true	Not a spec snapshot · not published	Update the COMPANION when the portal advances past the package.
claude/	Claude's tracked scratchpad — the one-off write-ups a session produces and a later one would want to find: lessons, audits, critiques, post-mortems, measured baselines. Sub-folders free.	Frozen at its date	Not short-lived working notes (→ local/) · not a design snapshot (→ superpowers/specs/)	Write a new dated one. A lesson that became a hook or a rule moves to claude/archive/.
pins2/	Portal pins batch 2 — everything Sessions 4 and 5 read, gathered in one folder: the plan and its spec, FINAL.md and Board 4's spec, Session 3's handoffs and intake log, the instruments, the board's kit and his cited screenshots. Its README.md is the index	Live for the plan, the index and the spec; frozen for dated records	Not a second scratchpad — a record about anything else still goes to claude/	Update the README's state table; regenerate the spec after a kit change
portal/	Portal working records with no other home — the pin log and its crops, swept pins under portal/archive/.	Present for the live log, frozen for the archive	Not lookup docs (→ reference/) · not plans or mockups	Sweep handled pins to portal/archive/.
archive/	Dead — swept intake, closed deferred items. Don't read by default.	Past, closed	Not a search target	Nothing here goes out of date; it is already history.
root records	CHANGELOG · CHANGELOG-SUMMARY · DEVLOG · ROADMAP · db-deferred-list · SESSION-START · this file	Append-only history, or live trackers	—	Never backdate. An old entry keeps the old name.

⚠️ ideas/ vs superpowers/specs/ is the pair that actually gets confused, and the whole difference is the last column: an ideas/ file you edit, a specs/ file you supersede. ⚠️ Narrative belongs in DEVLOG.md, not reference/. That is precisely why design-history was folded out on 2026-08-06 — it read as a reference doc and was a story. If a candidate for reference/ cannot be phrased as "read this to do X correctly," it is probably a DEVLOG entry. ⚠️ An open bug is never a reference/ entry. known-issues accumulated both for weeks; the split that fixed it is why platform-constraints.md has that name. (Both retired names are written without their .md on purpose — xref cannot distinguish a historical mention from a live broken link, so spelling one out costs a permanent audit warning.) Real defects go to db-deferred-list.md's 🐞 section, which is read and written far more often.

---

The records at a glance

File	What it is	When you touch it	Audience
../CLAUDE.md (repo root)	Invariants + navigation map (modularized 2026-07-22; deliberately short — wc -l it rather than trusting a number written here, which went stale at "~180" while the file was 287). The hard safety/architecture rules that must load every session, a platform cheat-sheet, and the 🗺️ nav map pointing to where each subsystem's detail lives.	When an invariant changes, or a subsystem's home moves. Keep the nav-map table in sync when you add/remove a rule file.	Claude (primarily), Harkirat

📋 Every tracked .md in this repo opens with YAML front matter (added 2026-08-08 12:05 EDT): kind: (which must match where the file lives), status: (live/frozen/superseded/dead), and published: true on the seven sources that render to dioreo.app. It is enforced by docs:audit's doc-frontmatter, so a file moved between folders without updating its kind fails CI instead of quietly sitting in the wrong place. Do not add description, updated, title or tags — this map already carries the descriptions, git already knows the dates, and a field nothing checks rots into confident misinformation.

Prose here is SOFT-WRAPPED — one logical line per paragraph, so rg can match a phrase. npm run docs:reflow enforces it as part of npm test. ⚠️ Line counts are therefore no longer a size signal for these files (docs/ROADMAP.md is 99 lines and 43KB); use wc -c or wc -w, both of which are wrap-invariant.

| ../.claude/rules/*.md | Path-scoped subsystem detail — the deep "why" for each subsystem, loaded into context ONLY when you read a matching file (paths: frontmatter glob). commands-overview, manage-panel, settings-and-expiry, admin-controls, interaction-router, admin-access-and-announcements, rendering-and-ui, accent-and-colors, loadouts, loadout-images-and-metadata, autobuild, draw-prices, design-decisions, models, scripts-and-migrations, legal-site, plan-drafting, hotpatch, operation-core, portal-editing, text-commands (@Dioreo today / d today: when Dioreo answers a message and when it stays silent), thinking-pass (the second rule with no paths: — the shape of a thinking pass, measured from 599 of his own instructions), silent-mode (the one rule with NO paths: -- it declares unconditional: true and loads at launch for every session, because the standing working style is an instruction rather than a subsystem trap; moved out of the auto-memory index 2026-09-02 16:04 EDT). The list is machine-checked by docs:audit's nav-map-sync, so it cannot rot — but the COUNT that used to sit in front of it was not checked and was stale within the hour legal-site.md was added, so it is gone. | When you change how that subsystem is built. Update the matching rule (the old "update CLAUDE.md" habit now splits by area). | Claude | | ROADMAP.md | The authoritative roadmap (v2 remaining · v3 · v4 · v5 · housekeeping) — detailed source of truth, full history/rationale. Moved out of CLAUDE.md 2026-07-22. The 🔮 Planned & Upcoming (CHANGELOG) and 🔜 Coming soon (SUMMARY) sections are synced VIEWS of it. The GitHub Projects board is a lightweight visual tracker manually refreshed FROM this file — not the other way around. | Every roadmap/planning change — sync all three (+ refresh the board when convenient). | Claude, Harkirat | | db-deferred-list.md | This project's own deferred work — 🐞 Active Bugs · 🔔 Reminders · 🗂️ Queued (own-session features) · 🧹 Someday/tech-debt · 🚫 Decided-no. NOT a copy of ROADMAP.md. Split out of the cross-project tracker 2026-07-25 15:56 EDT so it's tracked in-repo; renamed from deferred-items.md + completed 2026-07-25 21:43 EDT (that first pass left this project's bugs/reminders/resolved items behind in the cross-project file). | When something's deferred, found broken, or ships/drops. | Claude, Harkirat | | | On-demand reference docs: ( — Cloudinary tags and context, the prod collection and its fields, how the 93 draws were read, uploaded and checked, and what is still open; written 2026-11-01 01:05 EDT), ( — the five laws every badge animation follows, the family table, the procedure for a new badge family, and every rejected attempt with his words; written 2026-09-26 14:01 EDT; read it before designing or porting any badge motion), (stack, GCP VM/systemd/alerting, version tagging, — , , local Mongo, , emoji/data cloning; added 2026-07-26 13:45 EDT), (accepted limits — Components V2, the Discord client, system dependencies; renamed from 2026-08-06 08:15 EDT once the real open defects were split out to , since most of what it held were facts rather than bugs — and it carries a header warning that an entry is evidence, not a verdict, and must be re-tested before being cited), (the Conventional Commits subject format + branch/PR-title convention), (🔴 — every settled portal decision with a falsifier per row saying what would reopen it; it the moment you doubt something. It exists because three decisions were re-derived on 2026-08-31 whose answers already sat three lines from the code. ⚠️ — a row means , never ), (structure/provenance doc for the sibling — Harkirat's hand-authored full snapshot of Discord's nameplate + decoration collectibles catalog, 986 SKUs across 95 collections, recounted 2026-10-22; added 2026-08-15 01:00 EDT), (the "View Colors" panel in full — k-means extraction, swatch/gradient rendering, the label vocabulary and its two rejected attempts, V3, the Refresh cooldown, and every trap already paid for. Split byte-for-byte out of on 2026-09-02 15:54 EDT: a path-scoped rule is INJECTED in full the moment you read any file matching its globs, and at 144,650 B that one cost ~42k tokens to open . This half is REFERENCE — looked up, not needed in hand — so it lives here, where already indexes it for . ⚠️ Do not fold it back — though nothing currently enforces that: the byte-pin ratchet was rejected and removed 2026-09-02 21:06 EDT, see Problem 3 in ), (structure/provenance for the sibling — the real-money price of each of the six in-game CP bundles in all 41 currencies the official CODM web store sells in, captured 2026-08-15 16:29 EDT and validated against three known-real tables plus ten live re-fetches; it exists because Apple/Google prices are tier-locked PER STOREFRONT and are not proportional, so in 17 of the 41 currencies "buy the biggest pack" is the wrong advice), and (moved from memory files 2026-09-08, WP5b of the context-carriers plan — both had grown into 50-95KB journals better suited as tracked, versioned lookups than unversioned memory: the registry of every hook + the defect classes each one catches, and the measured behavior/gotchas of every MCP tool in use), (the family of conformance tools — , , , , — and their flags), (the web admin portal's production launch checklist) and (the per-script catalogue split out of ; how to add to ). Read when ops detail is needed, before designing one of the surfaces, or before writing any commit subject or branch name. ⚠️ used to sit here and failed that test; it was folded into as Part A's four earliest () entries and deleted 2026-08-06 08:24 EDT. · (how to prep a handoff or a compact — the steps, what NOT to re-run, the three carriers and their unequal reach, and a last-minute version) | When ops setup or a flagged issue changes. | Claude | | | — proposals and parked ideas that get as thinking changes, unlike , whose dated documents are snapshots that get . Holds (the intake scratchpad — its own row below; moved here from 2026-08-06 08:00 EDT, which also dropped the space from the filename that every hook reference had to quote around), (ideas rejected on TIMING rather than merit, each with the condition that would make it right; added 2026-08-02 22:53 EDT, moved here 2026-08-06 00:12 EDT), (the documentation-system guide — explicitly undecided and open), (the Armory manifest's By slot view, retired from Board 4 on 2026-10-01 and kept as possible future work), and Harkirat's private (gitignored, off-limits unless he says otherwise that session). — nothing here feeds the site build. | When an idea is parked, revisited, or its condition is met. | Claude, Harkirat | | | — one entry per merged PR, newest-first, incl. internal/housekeeping. Also holds the roadmap (synced from CLAUDE.md) and, at the very bottom, for the open branch/PR awaiting merge. | Every merge (draft the entry on the branch as work happens, finalize — real number + squash hash + tag — at merge). Graduate Unreleased → a numbered entry when it merges. | Claude, Harkirat | | | — player-facing. Represents (ops/docs-only ones get a one-line note, so none is ever skipped). ⚠️ — every release from v2.19.0 onward gets its OWN heading; the 7 surviving ranges are all v2.18.3-and-older and are left alone. in the docs audit enforces this (corrected 2026-07-28 22:10 EDT), but only real user-facing changes get a full bullet. Holds the roadmap view. | Same merge as CHANGELOG.md; add a friendly line for user-facing changes, a range/one-liner otherwise. | Harkirat / end-users | | | — the reasoning, dead-ends, root causes, and "note to future self." Part A = chronological story; Part B = thematic lessons ledger. Has its own ToC. | When a session produces real reasoning, a discovery, a walk-back, or a notable bug hunt. Not every commit. | Claude + Harkirat (us) | | | — where he jots thoughts between sessions. Has its own 🔑 Legend + header. It's a SCRATCHPAD, not a store: items get FILED into their real homes and marked/swept, so it shrinks. Its Graveyard is no longer a section inside it — resolved + ℋ-confirmed items sweep out to (split 2026-07-25 21:43 EDT). | Read at session start / when prompted / during a Document pass. Mark handled items IN-FILE the same session (see below). It is tracked in git and fully tidyable — no private section lives inside it anymore. | Harkirat (author), Claude (tidies) | | | — auto-loaded every session via a hook. Holds the NON-NEGOTIABLES glossary (commit/push/deploy/document). | When the session-start expectations change. Edit here directly; it's the single source (not duplicated in memory). | Claude | | (this file) | The docs map. | When a doc file is added, removed, or its role changes. | anyone | | | — (Terms of Service) and (Privacy Policy), both v1.0 as of 2026-07-28 21:36 EDT. , so these are live obligations, not internal notes. §2 + Appendix A describe the actual schema field-by-field. | Adding, removing, or repurposing a persisted user field makes the policy inaccurate until you update it in the same change. Also on any new third-party service, or a change to retention. | end-users, Discord, regulators | | (repo root) | Incorporated into by reference (§7.1). Carries each dependency's licence + copyright holder, the Apache-2.0 obligations (discord.js, xlsx), the trademark acknowledgement list, and the human-authorship assertion the copyright claim rests on. | — regenerate §1/§3 and re-check that no copyleft licence has entered the tree. | contributors, forkers, rights holders | | , , (repo root) | The custom — not open source; no deployment, no redistribution, no competing services, no AI/ML training. explains the CLA in plain English; is the credit ledger that discharges the credit obligation in LICENSE §5.6. | When licence terms change, or when an external contribution merges (credit it in the changelog entry). | contributors, forkers, anyone | | (repo root, NOT published to the site) | , the LICENSE §4.11 testing limits restated, scope, and an explicit no-SLA statement. Repo-only on purpose: GitHub reads it from there for the private "Report a vulnerability" flow, while readers reach the route through the redirect to the Contributing page. | When the reporting address changes, or when a new host or third-party service changes what is in or out of scope. | security researchers | | | (resolved + ℋ-confirmed intake swept out of the notes file), (closed entries from ), and the dated pre-tidy notes snapshot (pre-2026-07-18, largely superseded by git history). Renamed from and given its two archive files 2026-07-25 21:43 EDT. | Only when running a sweep, or looking something specific up. | reference |

Two authoritative records that live OUTSIDE this folder:

• Memory — ~/.claude/projects/-Applications-Claude-Code-Diors-Builds/memory/ (the repo-slug path; it MOVED here 2026-07-28 01:41 EDT — see CLAUDE.md's canonical-memory-path note). Standing rules for how to work. Start at user_working_agreement — its top "🔴 THE RULES THAT GET SKIPPED" checklist is the fastest way to load the non-negotiables. MEMORY.md is the index.
• /Applications/Claude Code/meta-deferred-list.md (outside this repo) — the cross-project tracker, and only that: cross-project bugs (the MarkEdit extensions, which live outside every repo), Claude/Anthropic product feedback, meta/architecture work, and the canonical Priority·Effort legend. Everything Dior's-Builds-specific — bugs, reminders, tech-debt — now lives in db-deferred-list.md above instead (2026-07-25 21:43 EDT). Renamed from deferred-items.md in the same pass.

---

How they relate (don't duplicate — sync)

• docs/ROADMAP.md is the source of truth for the roadmap (moved out of CLAUDE.md 2026-07-22). Its v2–v5 lists are authoritative; the 🔮 Planned & Upcoming (CHANGELOG) and 🔜 Coming soon (SUMMARY) sections are synced views of it — update all three together, or they silently drift (a real records bug).
• The notes file feeds the roadmap, it doesn't hold it. A feature idea lands in the notes as intake, gets FILED into docs/ROADMAP.md + the changelog roadmaps, then LEAVES the notes file. The roadmap is never duplicated in the notes file.
• Memory holds the rules; the docs hold the record. A workflow lesson → memory. A shipped change → changelog. The "why" behind the code → CLAUDE.md's invariants + the matching .claude/rules/*.md. The story of getting there → DEVLOG.
• ROADMAP.md / db-deferred-list.md are the record; the GitHub Projects board is a view. ⚠️ The board's 15 draft items were sourced 2026-07-25 21:35 EDT, minutes before the 21:43 EDT deferred-list restructure — so its items predate the rename, the bugs/reminders moving in-repo, and the resolved items moving to archive/. Re-sync it manually before trusting it. The board (Status/Priority/Effort/Model/Flags fields) exists for an at-a-glance visual snapshot — a Status kanban + a Priority table. It is refreshed manually and periodically from the docs, never the other way around: if the board and the docs ever disagree, the docs win. Don't let it silently drift into a second source of truth the way the notes-file/CLAUDE.md roadmap once did.

Responsibilities / chores checklist (per merge — moved from per-push 2026-07-24 12:24 EDT)

Which of these are machine-checked (re-audited 2026-07-28 20:50 EDT): items 1, 2, 3, 5, 8.2, 8.4, 8.5 fire a hook at gh pr merge (or at git tag). Item 4 is nudged when code under commands/utils/models/scripts changes without a CLAUDE.md/.claude/rules/*.md note. Items 6 (memory) and 7 (notes file) fire at gh pr create via .claude/hooks/records-close-check.sh.

⚠️ They surface as ADVISORY context, not as a permission prompt — changed 2026-08-02 17:55 EDT (v2.50.0), and the reason matters. These gates used to emit permissionDecision:"ask". Measured that day: an ask from a PreToolUse hook is silently auto-approved in the permission mode actually in use — the same gh pr create produced no prompt and no output, while running the hook by hand emitted a full finding. Seven gates were dead this way. additionalContext demonstrably does surface, so every judgement gate now uses it, and objective violations (impossible timestamp, squash without --body, tag/version mismatch, force:true artifact overwrite) were promoted to deny, which was verified to block hard. Never write a new gate as ask without re-testing that asks are visible.

⚠️ This paragraph used to say items 6 and 7 were "NOT checkable". That was wrong (corrected 2026-07-28 20:50 EDT, Harkirat's catch). A SessionStart hook had been counting the notes file's open items the entire time. The real defect was never absence, it was timing: that check fires at the moment of discovery, when nothing is filed yet and there is nothing to compare against, and never at the moment of closure — the identical shape to the DEVLOG failure measured at 8/22. The general lesson, worth more than the fix: "not checkable" is almost always "I haven't worked out what the derivable invariant is." For the records it turned out to be conservation — an item leaves an active list only by appearing in an archive, so a shrink with no matching grow is either unswept or silently deleted. What genuinely stays uncheckable is whether the judgment was right; a gate proves an artifact was opened, never that the right thing was written in it.

The tree-level invariants live in ../scripts/docs-audit.mjs (npm run docs:audit; --list prints the current roster, deliberately not counted here) — checks covering the doc map, cross-references, version coverage across all three records, the changelog hash-chain, the DEVLOG TOC, tag integrity, and the sweep/conservation rules above. It is a program, not a hook, deliberately: a hook only fires inside a Claude session on one Mac, so it runs as a CI gate on every PR too. ERROR findings fail the build; WARN findings never block, so a hotfix is never held up by prose. npm run docs:audit:test proves every check can actually fail — a guard nobody has watched fail is not a guard, and this repo has already shipped one that was silently dead.

Read the accounting line, not just the verdict. Every run reports N/M checks verified (K items examined), plus anything SKIPPED (it could not run — no memory store, a shallow clone) and anything that examined nothing. N checks passed used to hide all three: a check that matched zero items "passes" while verifying nothing, which is how a broken matcher survives indefinitely. A pass means no known failure mode tripped — never the records are correct. Novel drift, prose quality and judgement calls are outside what any of this can see, and it says so on every run.

It also runs at gh pr create via ../.claude/hooks/docs-audit-gate.sh, so failures surface while fixing them is still free. ⚠️ That local gate fires only on the literal gh pr create command inside a Claude Code session on this machine — a PR opened through the GitHub web UI bypasses it, and every other local hook with it, including the notes/memory closure check. CI is the guarantee; the hook is the convenience. Docs are drafted on the branch as the work happens (they ride in the PR's diff, reviewed alongside the code) and finalized on the branch in the final pre-merge checkpoint:

1. Bump the version per project_dior_builds_changelog_system (memory) — one number per MERGED PR, not per commit or push.
2. CHANGELOG.md: a numbered entry (draft it in Unreleased on the branch; finalize it with the real number + timestamp + PR number, no hash in the final pre-merge checkpoint — the hash is backfilled one release later, per step 8).
3. CHANGELOG-SUMMARY.md: a friendly line (user-facing) or a one-liner (ops/docs-only) under its OWN ## vX.Y.Z heading — never skip the number, and never fold new releases into a range (that convention is retired; see the records table above).
4. CLAUDE.md or the matching .claude/rules/*.md: update the design/architecture note the change affects (subsystem detail lives in the rule file now; invariants + the nav map live in root CLAUDE.md). Keep the root nav-map table current if you add/remove a rule file.
5. DEVLOG.md: a narrative entry by DEFAULT. Skip it only when the change is purely mechanical (a typo, a version bump, a lockfile) — and if you skip it, say so and say why. This used to read "if the work had real reasoning/discovery," and that conditional is exactly why DEVLOG coverage was 8/22 releases (36%) while the hook-checked CHANGELOG and its summary were 22/22 (measured 2026-07-28 14:15 EDT). A judgment call made at the moment you are trying to finish defaults to "no." Now hook-checked at gh pr merge like the changelog.
6. Memory: update any rule the session established or corrected.
7. diors-notes.md: mark/file/sweep anything the session handled — in-file, same session. Sweeps go to archive/graveyard.md, not to a section inside the notes file.
8. One commit + one tag per release — the 4-step lifecycle (adopted 2026-07-27 21:27 EDT):
   1. On the branch, as the final pre-merge checkpoint: write the changelog entry with the PR number and no hash — ## v2.36.0 — 2026-07-27 21:30 EDT (#33) — <title> — bump package.json, finalize CHANGELOG-SUMMARY.md + DEVLOG.md.
   2. In that same checkpoint, backfill the previous entry's hash: (#32) → (#32 · `f913975`). Additive-only — insert · `sha` and touch nothing else on the line; never edit the timestamp afterwards; never --amend, never force-push (this is an ordinary edit in a later commit).
   3. → commit on . No commit — it is retired.

Versioning

vMAJOR.MODERATE.MINOR (3-part, uniform throughout as of 2026-07-21). Full rules in CHANGELOG.md's versioning header and the project_dior_builds_changelog_system memory (the source of truth for the scheme). To find the current live version: git describe --tags or scripts/vmstatus.sh.

Date/time convention (all records)

Write dates with a time and timezone — YYYY-MM-DD HH:MM TZ (e.g. 2026-07-21 22:46 EDT), not a bare date (Harkirat's standing request, 2026-07-21 ~22:46 EDT). The time is a second factor for exact intra-day ordering when several things ship the same day; always state the timezone because the VM runs UTC while Harkirat is ET. Get the real clock time proactively, ONCE, before drafting any dated content — date "+%Y-%m-%d %H:%M %Z" — and reuse that value for every date written the rest of the turn. A PostToolUse hook flags a bare today-date after the fact, but it's a safety net for the rare miss, not license to fetch the time reactively every time (caught doing exactly that 2026-07-26 11:35 EDT — see feedback_docs_at_push_time / feedback_token_conscious_tool_routing memory).

Where the legal documents live, and why they are not all together

A reasonable question, asked 2026-08-02: there are four legal documents and they sit in two places. The split is forced by tooling, not chosen, and moving them breaks things:

Document	Location	Why there
LICENSE	repo root, no extension	GitHub renders a licence banner from a root file with this exact name; licence scanners look for it. Plain text, not Markdown.
NOTICE	repo root, no extension	The Apache-2.0 convention. It matters here because discord.js and xlsx are Apache-2.0 and their notices must be reproduced.
CONTRIBUTING.md · CONTRIBUTORS.md	repo root	GitHub surfaces CONTRIBUTING.md in the PR and issue flows.
SECURITY.md	repo root	GitHub reads it to power the private "Report a vulnerability" flow. Deliberately NOT published to the site; /security redirects to the Contributing page instead.
TERMS.md · PRIVACY.md	docs/legal/	No tool recognises these two. They are ordinary project documents, so they live with the other documents rather than cluttering the root.

So: root is "files a tool reads by name"; docs/ is everything else. Do not tidy this into one folder — it would cost the licence banner, the vulnerability-report flow and the contributor prompts.

And why LICENSE/NOTICE appear a second time under public/

Those two are copied verbatim, byte-for-byte, by buildCompanions() so the deployed site serves the unrendered originals at a stable URL. They are operative legal instruments, and putting a Markdown parser between a reader and the binding wording is a lossy transformation. Each therefore has two forms: /license to read (the rendered page), /LICENSE to rely on. CONTRIBUTING/CONTRIBUTORS get no such copy — they are prose about a process, not instruments.