This library collects the documentation maintained across Fairy Fox's work: an overview of how the projects fit together, how this site itself is built, and the shared engineering standards the repositories follow. Every project also keeps its own full documentation site — reached straight from its card on the projects page.
Overview
This site
How fairyfox.io is built
The stack, the repository layout, and the three concerns that share one repo.
The system map
The four cooperating systems — website, updates, hub, and cross-project sync — and how they relate.
Build and deployment
How the site builds and deploys itself through GitHub Actions, with no manual publish step.
Updates and cross-project round-ups
How update posts are written, including the round-ups that report what changed across the projects.
Design decisions
The key structural choices behind the site and hub — and a few things deliberately not done.
Principles and voice
What the site and repository value — and the writing voice the whole site holds to.
Shared standards
Git workflow
The shared git-flow branch model, no-fast-forward merges, and the safety rules used across repositories.
Versioning
Semantic Versioning with a single source of truth in a VERSION file.
The living-notes system
A structured notes/ tree that keeps each repository self-documenting.
Cross-project sync
How the hub and the projects share standards through git, without coupling.
AI context (CLAUDE.md)
A root entry-point file that orients an AI assistant opening a repository.
Documentation and house style
The documentation set each repository keeps, and the plain house style used to write it.
New-project setup
Bootstrapping a fresh repository fully into the mesh — branches, templates, notes, standards, and registration.
Onboarding an existing project
Folding an established repository into the mesh by reconciling the standard onto it, not overwriting it.
Adopting updates
How a project already in the mesh checks for, and applies, later changes from the hub — on request, report-first.
Docs-site design system
The shared chrome, look, and structure that make every project's documentation site appear as a page of fairyfox.io.
Process reports
After every run of a hub procedure, a project writes an honest report of how it went; the hub reads those reports to improve the standards.
Standards compliance audit
One on-request pass that runs every standard's own check at once and reports, per standard, whether a repository follows it.
Deployment
Where each kind of project deploys — static content to GitHub Pages on the shared domain, built apps to Netlify, with games as a recorded exception.
Planning
Plan non-trivial work in detail before executing it — a mesh-wide default, for execution reliability rather than paperwork.
Supply-chain hardening
Baseline GitHub-repo security hygiene every project ships — least-privilege workflows, pinned actions, branch protection, a SECURITY.md, and signed releases.
Dependencies
Upgrade aggressively — including majors — behind a real test gate. Fixing an upgrade is cheaper than deferring it.
Legal docs
Every project ships self-hosted, code-accurate Privacy, Terms, and Cookies pages — written against what the code actually does.
Agent tooling
How an AI assistant operates a repository here — PowerShell and the file tools rather than the sandbox, and doing the work rather than handing over a script.
README badges
Every README opens with a status-badge block — as many applicable badges as the project supports, so its health, release, and security posture are legible at a glance.
Coins
A light, shared reading-engagement layer across the mesh — subtle, never a gate, never the point.
Testing and verification
Every project proves its work — real, layered tests that run before shipping, and a visual change previewed with human eyes first.
Engineering quality
The standing quality bar every project holds to — clean, correct, finished work, documented and tested, with no rough-in left for "later".
Repo hygiene
Small mechanical guardrails so drift, stranded files, and branch litter fail loudly instead of accumulating.
Docs lifecycle
One distinction every project applies the same way — current-state docs get swept on a change; dated history is left alone.
Research capture
If you understood something you didn't understand before, write it down — in the notes, the same session, without being asked.
Working rhythm
The shared working agreements for AI-driven work — track it, stay out of the owner's way while working, and don't build past the brief.
Self-hosted assets
A published mesh site makes no third-party requests for its own presentation — fonts and controlled assets are served from its own origin.
Farm operating model
What a "farm" — a growing collection tended on a schedule — owes, so a third farm inherits the shape instead of reinventing it.
Maintenance sweep
A documented, repeatable whole-repo tidy that returns a project to a clean shipped baseline — audit-first, act only on go-ahead.
Checklists are contracts
A checklist is a contract, not a summary — every item is owed an outcome, recorded individually, before any "done" is claimed.
Owner mandates become ledgers
An owner's multi-part directive is transcribed verbatim into tracked entries, so no clause quietly becomes optional between one message and the next.
CI service secrets
The three per-repo GitHub Actions secrets that make the code-quality, coverage, and Scorecard integrations light up — named, sourced, and provisioned by a tool.
Docker — local-first build, test, and setup
Use Docker to run the Linux half of a project locally — build, test, and setup — instead of deferring it to online CI to discover whether it passes.
README structure & cross-linking
A project's README travels far beyond the site — GitHub, npm, plugin registries, mirrors — where the site chrome doesn't exist, so it must carry the mesh links in its own text — a docs link near the top, a grouped "Get it" section, and a fairyfox.io footer near the bottom.