Full hub-standards audit — 2026-07-20

Complete itemized expectation list compiled from the hub clone (assets/references/fairyfox.io, standards as of chrome bundle 2.2.1 / hub VERSION at clone). Requested by Fairy Fox: list every expectation, audit each, apply gaps. Applying is pre-authorized by the standing ledger grant adopt-standards-by-default (covers hub/standards/ + hub/templates/); safety floor kept (reconcile-not-clobber, verification before/after, process report, reviewable commit).

Status key: ✅ pass · ❌ gap (fix now) · 🔶 gap (recorded, follow-up) · N/A (reason recorded) · 🔹 pass-by-construction (comes verbatim from the vendored chrome bundle 2.2.1, version matches hub).

A. Docs site — tokens & colour (08 §Tokens)

✅🔹 Dark theme = exact dark palette (vendored main.css, 2.2.1 = hub 2.2.1)
✅🔹 Light theme implemented, exact palette (bundle)
✅🔹 OS-driven scheme, dark default, :not([data-theme]) guard (bundle)
✅🔹 Sepia theme (data-theme="sepia") (bundle)
✅🔹 Lifecycle status fixed hues (bundle)
✅ Accent only on brand/links/highlights (verified in adopt-docs-chrome pass, 2026-07-20)

B. Typography (08 §Typography)

✅🔹 Fraunces / Inter / JetBrains Mono at specified weights (bundle head.html)
✅🔹 Base size / heading scale match tokens (bundle)
✅🔹 Fonts preconnected, no reflow (bundle)

C. Shell & layout (08 §Shell)

✅ Sticky 64px translucent header (verified in-browser 2026-07-20)
✅ Footer multi-column structure (verified; deviation recorded: sits in Dokka content column)
✅ main grows, footer at bottom on short pages
✅ Centred container at --maxw + --gutter
✅ API pages: Dokka's own grouped sidebar + capped measure (generator-owned)

D. Components (08 §Components)

✅🔹 Buttons/cards/chips/badges/code/tables per spec (bundle CSS)
✅🔹 Reader "Aa" menu, fairyfox:reader key, applied before first paint; spacing/width story-locked (bundle reader.js)
✅🔹 Coin button via shared coins.js, fairyfox:coins:a key; nothing coin-gated (bundle)
✅🔹 :focus-visible accent outline (bundle)

E. Chrome, cross-linking & branding (08 §Chrome + 05)

✅ Chrome is the vendored chrome/ bundle, not a lookalike; VERSION 2.2.1 recorded
✅ Shared header, global primary nav in fixed order Home · Projects · Farms(Stories·Games) · Docs · Updates · About
✅ Brand + Home link to https://fairyfox.io/; no back-button
❌ Active primary-nav item must be Projects — always, only Projects. Currently Docs is marked .active aria-current="page" in docs-theme/dokka-templates/includes/header.ftl. → FIX: move .active to Projects.
🔶 Site reachable at fairyfox.io/papermc-despawned-items/ + registry docs:/repo: accurate — registry lives hub-side; verify entry on next hub sync (node cannot edit the hub).
❌ Subnav canonical three-zone shape [name=overview] · Notes · Tutorials · Changelog · API · Download · [Repository ↗], include only pages that exist, no invented names, centre links must be real chrome-wearing pages. Currently: invented "Guide" item; Guide/Changelog point at raw GitHub (not chrome-wearing pages); no API item; subnav-home unconditionally active. → FIX: [PaperMC Despawned Items] · API(active) · Download · [Repository ↗]; drop Guide + raw-GitHub Changelog; themed Changelog page recorded as follow-up (plans/future.md).
✅ Footer links repo/notes/main-site sections (bundle footer, slots filled)
🔶 Breadcrumb/locator near page top — recommended, absent; Dokka breadcrumbs exist on API pages; acceptable, note for future.
✅ Project-forward branding via subnav locator; membership carried by chrome

F. Seamlessness (08 §Seamlessness)

✅🔹 Header metrics/fonts/theme-color/favicon match (bundle head.html)
✅🔹 Reader menu + key identical (bundle)
✅ Same-origin direct links, no redirect bounce

G. Content & organization (08 §Content + 06)

✅ Pages cover roles: overview (Dokka module page w/ module docs), reference (API). Getting started lives in README; themed Tutorials page = follow-up (plans/future.md).
✅ API docs generated, themed, boundaried; only in API section
✅ API linked from subnav as clear boundary (after fix #24)
❌→verify Generator sidebar lists ONLY API pages — audit every regen (generators re-add). → Verify in this pass's regenerated output.
❌→verify Generator's own footer gone — footer.ftl overridden; confirm no Dokka footer renders in output.
N/A Notes-on-site rules — project does not render notes/ on the docs site (Dokka-only site). If Notes are ever published: single Notes item, landing + full sidebar, README excluded.
✅ Reader gating: API/index pages omit data-read (correct — none carry it); Downloads page (new) is designed/navigational → omits data-read.
❌ Downloads page is REQUIRED (project ships release jars). Must be a real chrome-wearing page linked as Download, sourced from GitHub Releases, with a perma-latest section. Currently Download points at raw GitHub releases. → FIX: add themed downloads.html with Latest (releases/latest) + all-releases sections.
✅ No orphan pages / no raw link dumps (after fix #24 removes raw-GitHub subnav links)
✅ Public voice; parent referred to as Fairy Fox / fairyfox.io

H. Accessibility (08 §A11y)

✅🔹 AA contrast both themes (bundle palette; accent unchanged)
✅🔹 Focus visible, keyboard-operable nav (bundle)
✅🔹 prefers-reduced-motion honoured (bundle)
❌→verify Landmarks/heading order on the new Downloads page; decorative imgs hidden.

I. Sign-off (08 §Sign-off)

✅ Deviations recorded (decisions/architecture.md: footer-in-column, Dokka reference bar kept)
❌→verify Check light/dark/sepia after this pass's changes
N/A Master-copy manual-review rule (fairyfox.io repo only)

J. Git workflow (git-workflow.md §Verify — all 8 checks)

✅ Stable branch is main
✅ Every main commit is a tagged --no-ff release merge (verify at next release)
✅ dev contains main (rev-list origin/dev..origin/main = 0; branch-sync.yml guard present)
✅ No content authored on main
❌ PR-based releases on a protected repo — main is NOT branch-protected (checked via gh api: 404). supply-chain-hardening makes protection MANDATORY. → FIX: apply canonical solo config; releases move to the PR path (gh pr create → checks → merge --merge → back-merge). "Just merge dev to main" locally is retired.
✅ No force-push/rewrite of published history
✅ No spent support branches lingering
✅ Releases ride green dev CI (ci.yml on dev)
✅ CI-owns-tag check: release.yml reacts to hand-pushed tags (documented in file header) — by-hand tagging is correct here.
✅ Release posture: green-and-CI-gated auto-proceed (mesh default; no stricter local override).

K. Supply-chain hardening (§Verify — all items)

✅ Actions SHA-pinned with version comments; dependabot github-actions ecosystem on
✅ Root SECURITY.md with private reporting path
❌ release.yml lacks build-provenance attestation (actions/attest-build-provenance, id-token+attestations at job scope). → FIX: add step, SHA-pinned.
❌ Branch protection missing (same as #52). → FIX now.
✅ Dependency-vuln posture: dependabot on; no open findings
🔶 Solo ceiling / badge-lag acknowledgement — add line to notes (this file records it: the OpenSSF solo ceiling ~8 and badge lag are accepted, not chased).

L. Versioning (versioning.md)

✅ VERSION file present, PATCH-default, tag matches at release
✅ Changelog rides inside the commit atop notes/version/2026-07.md

M. Hub standards adoption state (27 standards; grant makes adoption the default)

#	Standard	State	Action
66	adopting-updates	✅ adopted, current	—
67	agent-tooling	❌ referenced by CLAUDE.md but not copied	copy to notes/reference/
68	ai-context	❌ not adopted	copy; CLAUDE.md shape already conforms
69	badges	❌ not adopted	copy; audit README badges after
70	coins	❌ not adopted (coins.js already live in chrome)	copy
71	compliance	❌ not adopted	copy (this audit is its first run)
72	cross-project-sync	✅ current	—
73	dependencies	❌ not adopted	copy
74	deployment	❌ not adopted	copy
75	docs-lifecycle	❌ not adopted	copy; check-links/check-tidy templates = follow-up
76	docs-site (13 modules)	🔶 chrome adopted; full standard audited here	fixes #22/#24/#34/#35/#38
77	engineering-quality	❌ not adopted	copy
78	farm-operating-model	N/A — story/game farms only; this is a plugin repo	record
79	git-workflow	✅ current	—
80	legal-docs	N/A — docs live under fairyfox.io origin; hub serves /legal/	record
81	maintenance-sweep	❌ not adopted	copy
82	new-project-setup	N/A — one-time runbook, project exists	record
83	notes-system	✅ current	—
84	onboarding-existing-project	N/A — already onboarded 2026-07-19	record
85	planning	❌ referenced by CLAUDE.md but not copied	copy
86	process-reports	❌ in active use but not copied	copy
87	repo-hygiene	❌ not adopted	copy; settings audit = follow-up
88	research-capture	❌ not adopted	copy
89	self-hosted-assets	❌ not adopted	copy; note: brand logo hot-links fairyfox.io (#91)
90	supply-chain-hardening	✅ current; impl gaps #60/#61	fix
91	testing	❌ not adopted	copy; MockBukkit plan already in plans/testing.md
92	versioning	✅ current	—
93	working-rhythm	❌ not adopted	copy

N. Cross-cutting items found during audit

🔶 header.ftl hot-links the brand logo from https://fairyfox.io/assets/icons/fox.png — self-hosted-assets standard says vendor it. Follow-up: vendor the icon via vendorChromeAssets.
✅ Reference clone read-only + git-ignored
✅ Fairyfox reports written for both prior procedures
❌ This pass itself: write process report + changelog + VERSION bump + session log + status.md.

O. Testing standard — detail checks (added mid-audit on Fairy Fox's flag)

✅ Core/logic separated from rendering, unit-tested headlessly — 13 test classes across config/despawn/limit/location; MockBukkit mocks the live server (no real server needed)
✅ Multi-layer, real tests — unit + property/fuzz + database (SQLite/JDBC) + performance (LocationStoreBench) + mocked-server integration (PluginEnableTest); ~49 tests gate build
🔶 Regression-test-per-bug-fix — practice held during the July refactor (fixes landed with tests); standing rule now in notes/reference/testing.md; spot-check at each release
✅ Full suite green before release — build runs check → test; CI on dev is the gate
✅ Truth oracle — MockBukkit (mocked Paper) + the headless real-server smoke runs (1.21.11 + 26.1.2 boots recorded in status.md) are the oracle pair
N/A Visual-preview rule — no visual surface in the plugin; docs pages verified in-browser

P. Repo-hygiene standard — detail checks (same flag)

✅→APPLIED Broken-link gate: scripts/check-links.mjs copied from hub/templates, wired into ci.yml before the build step
✅→APPLIED Uncommitted-file guard: scripts/check-tidy.mjs copied; run at session end
✅ No stranded files — git status clean of non-ignored ?? after this pass's commit
✅ Current-state docs swept — status.md/CLAUDE.md updated in this pass (stale "cut 1.1.0" next-step removed)
✅→APPLIED Branch auto-delete ON (delete_branch_on_merge=true); dev deletion+force-push protected via branch protection

Correction round (2026-07-20, later — after Fairy Fox caught the lenient reading)

The first "fix" of #24 satisfied the letter by shrinking the subnav to existing pages instead of building the pages the standard expects, left the Dokka module page as the site's default page (the left pill must be a real overview/landing), and kept the generator as the whole site rather than boundarying it. Same class of failure the audit itself documents (F1/F5). Corrected properly (v1.3.4):

#24 → full canonical subnav on every page: [name] · Notes · Tutorials · Changelog · API · Download · [Repository ↗], all real chrome-wearing pages, per-page active marks. RE-FIXED ✅
Default page → overview landing (index.html), section cards; API root no longer the landing. ✅
#31 → Tutorials page (getting started) now exists, data-read. ✅
#36 → Notes rendered on the site after all (06 shape: one door, landing = root note + sections, sidebar lists every note, READMEs excluded, note pages data-read, landing not). Was N/A-by-choice; the choice is reversed. ✅ (44 pages)
#32/#33 → API now truly boundaried under /api/, subnav API item active on generated pages, way-back via homepageLink → overview. ✅
#34/#35 → re-verified on the restructured output (sidebar API-only; one footer). ✅
#94 → fox icon vendored (root + api); zero fairyfox.io asset hot-links remain in the built site. Manifest self-hosted-assets row → implemented. ✅
Changelog page generated from notes/version/*.md at build (follow-up delivered early; future.md updated).
Verification caught a malformed home-pill attribute (class="subnav-home" active) before commit — fixed; zero malformed actives in output.

Still open after this round (honest list): #23 (hub-side registry check — hub's act), #26 breadcrumb (recommended, absent — Dokka breadcrumbs exist on API pages only), #46 in-browser three-theme + mobile sign-off on the live deploy (fetch/inspect after ship), #100 regression-per-fix (ongoing practice), notes section READMEs excluded from sidebar by name — revisit if they gain real content.

Applied in this pass (2026-07-20)

#22, #24 → header.ftl fixed (Projects active; canonical subnav) ✅
#38 → downloads.html created + vendorChromeAssets wiring ✅
#52/#61 → main protected (solo config verified via API response); #108 dev protected ✅
#60 → release.yml: attest-build-provenance @977bb373 (v3) + job-scope permissions ✅
#67–#93 copies → 17 standards into notes/reference/ ✅; 4 N/A recorded in table M
#104/#105 → hygiene gates in ✅
#97 → changelog v1.3.3 + VERSION + decisions + status + CLAUDE.md release path ✅
Remaining open: #23 (hub-side registry check), #26/#31/#94 + themed Changelog page (plans/future.md), #100 (ongoing practice), #34/#35/#44/#46 (verified below at regen)

Execution order (this pass)

Fixes #22, #24 (header.ftl) · #38 (downloads page + build wiring)
#52/#61 branch protection · #60 attestation step
M-table copies (14 standards) + 4 N/A recorded here
Regenerate docs; verify #34, #35, #44, #46
#97 bookkeeping; commit on dev; PR-release eligible when green