Stables Project Wiki
What this covers / who it's for. The charter for the project wiki: what the wiki is, where it sits in the documentation stack, the rules every page follows, and the master table of contents for the two sub-wikis. Read this first if you are adding or changing wiki content — human or AI.
The wiki is the curated narrative and navigation layer of this repository's documentation: the "why", the end-to-end journeys, the system-wide views, the onboarding paths, and the cross-module maps. It serves two audiences through two sub-wikis:
wiki/product/— product eyes: what the platform does, for whom, why, and the under-the-hood mechanics a product person needs to reason about behavior, dependencies, and failure modes.wiki/engineering/— engineering eyes: how the system is built, how it behaves at runtime, and how to change it safely.
The source-of-truth hierarchy
Code is the only source of truth. Every documentation layer describes the code, each at a different altitude, and each defers to the layer below it. The wiki is the top (widest) layer:
| Layer | Home | Role | Defer to it for |
|---|---|---|---|
| Code | app-modules/, config/, migrations | Truth | Everything — when any doc disagrees, the code wins and fixing the doc is part of your change |
| Module READMEs | app-modules/<m>/README.md | Current specifics of one module | Public surface, data model, config keys, gotchas |
| Skills | packages/stables/skills/resources/boost/skills/ | Cross-cutting direction for agents | Patterns, seams, "when to use what", workflows |
| ADRs | wiki/engineering/decisions/ (D-numbered, one file per decision; three historical clusters share a file) | Decision rationale | Why a choice was made; reversing one needs the user |
| Tracking | docs/tracking/ | Deferred work register | What was consciously not built yet |
| Generated artifacts | docs/EVENTS.md, openapi/, .claude//.agents//.cursor/ mirrors | Machine-produced | Never hand-edited; regenerate instead |
| Wiki (this) | wiki/ | Narrative + navigation across all of the above | The why, journeys, system-wide maps, onboarding |
The no-duplication rule. The wiki links down into module READMEs, skills, ADRs, and code for specifics — it does not restate them. Where a detail lives in a README, link to it. Short summaries that make a page readable standalone are fine; exhaustive restatement is a bug, because the copy will drift. Enumerable facts that the wiki does carry (tables of modules, retention windows, schedules, statuses) exist because they are cross-module views no single README can hold — each cites where the underlying fact lives.
The maintenance contract
The wiki is continuously maintained, not periodically rewritten:
- Every shipped change updates the wiki pages it touches, in the same change — alongside
the module README and skill sync. This is wired into the repo's definition of done
(
CLAUDE.md→ "Definition of done", theagent-workflowskill, and the.ai/guidelines/docs-sync-workflow.mddurable guideline). - The
wiki-maintenanceskill (in the skills package) teaches how to decide which pages a diff touches, how to add a page, and the structural rules. Activate it for any wiki work. - No dead links, no orphan pages. Every page links back to its index; every index links
every page.
make wiki-checkverifies wiki-internal links and structure.
Reading the wiki as a site
The wiki doubles as a browsable documentation site, built with
Docusaurus. The site is fully self-contained under wiki/ —
its package.json, docusaurus.config.js, theme assets, node_modules, and build/ output all
live here and nothing outside wiki/ is required to build or host it.
make wiki-dev— run the hot-reloading dev server (first run:make wiki-install).make wiki-build— produce the static site inwiki/build/.make wiki-serve— serve the built site locally.
Deployment (Cloudflare Workers)
The site deploys to Cloudflare Workers as an assets-only Worker (stables-core-app-wiki on
core-app.wiki.dev-stables.xyz; config in wiki/wrangler.jsonc). The production path is
Workers Builds — Cloudflare's own
CI/CD, which builds and deploys on every push. Because the site lives in a subdirectory, the
dashboard build settings are:
| Setting | Value |
|---|---|
| Root directory | wiki |
| Build command | npm run build |
| Deploy command | npx wrangler deploy (the default — leave as-is) |
Dependencies install automatically (npm is detected from wiki/package-lock.json), so the build
command does not need an install step. Manual deploys are also available:
make wiki-deploy (build + publish; needs a CLOUDFLARE_API_TOKEN or wrangler login) and
make wiki-deploy-check (validate without publishing).
The markdown files remain the source of truth and stay plain, GitHub-renderable, and
tooling-agnostic — Docusaurus is only a presentation layer over them. Two build-time conveniences
bridge the gap: .md files are parsed as CommonMark (not MDX), so angle-bracket placeholders such
as app-modules/<module>/README.md render literally; and links that point down out of wiki/
into code, module READMEs, skills, or ADRs elsewhere in the repo are rewritten to their canonical
GitHub source (src/remark/repo-links.js), so the same relative links work both on GitHub and in
the site.
Page conventions
Every wiki page follows the same shape, so both humans and AI consumers can navigate cheaply:
- A front-matter-style header (plain markdown, no tooling dependency):
title,audience(product|engineering|both),related(repo-relative or wiki-relative paths). - A 2–4 line "What this covers / who it's for" preamble immediately after the H1.
- kebab-case file names, one topic per file; subdirectories only where a topic cluster
warrants it (currently:
product/mechanics/). - Tables for enumerable facts, Mermaid for architecture/flows/state machines, code blocks for commands and payload shapes — used where they clarify, never as decoration.
- A backlink to the sub-wiki index at the end of each page.
- Pages earn their length: exhaustive in coverage, not padded.
Master table of contents
Product wiki — wiki/product/
| Page | What it answers |
|---|---|
| Platform overview | What Stables is, for whom, and the capability map |
| Personas & access | Client users vs operators; teams, roles, MFA |
| Tenant lifecycle | Register → verify → KYB/KYC → active → frozen/closed |
| Plans & entitlements | Tiers, jurisdictions, quotas — who gets what, where |
| Money movement | Accounts, deposits, payouts, orders, FX as user journeys |
| Compliance & trust | Cases, freezes, SAR/CTR, audit trail, document vault as product guarantees |
| Notifications & comms | Inbox, email, preferences, what is recorded |
| Operator backoffice | What central operators can do today |
| Capability → module map | The bridge into the engineering wiki |
| Glossary | Domain terms and every user-visible status |
| Mechanics cluster | Under-the-hood facts at a mechanics level, for product reasoning: |
| Providers & rails | What we execute vs offload to the finance rail; the mirror model |
| Where data lives | Postgres, object storage, WORM exports, what reaches the provider |
| Async by design | What is deliberately not instant, and how request-then-poll feels |
| Communications delivery | How email/notifications leave the system; logging and retention |
| Dependencies & failure modes | Capability → dependency → user-visible impact → what to check first |
| Data lifecycle guarantees | Retention, pruning, RTBF, freeze/closure effects as commitments |
Engineering wiki — wiki/engineering/
| Page | What it answers |
|---|---|
| Engineering index & onboarding path | Where to start, in what order |
| Architecture & runtime flows | The whole-app map: modules, request path, mirror ingest, async platforms, audit/DLP seams |
| Module catalog | Every module: purpose, surface, seams, README link |
| Tenancy & RLS | Central vs tenant, the session variable, isolation verification |
| The CQRS bus | Command/query lifecycle and every middleware seam |
| Auth & RBAC | Both guards, the permission registry, roles-as-UX |
| API conventions | JSON:API, id conventions, idempotency, OpenAPI |
| Data model | Schema conventions and the cross-module domain map |
| Async platforms | Queues/Horizon vs task-runner vs async-requests — when to use which |
| Provider integration | Outbound rails seam, inbound webhook mirroring, reconciliation |
| Testing & the gates | The suite, the arch guards, the four gates |
| Local development | The Docker stack, make targets, ports |
| Observability & ops | Horizon, scheduled work, pruning, failure surfaces |
| Decision log (ADRs) | The D-numbered ADR log — index + per-decision files (historical clusters grouped) |
| How a change ships | Branch → gates → review → docs+wiki sync → PR |
Charter decisions
Judgment calls made when this wiki was established (2026-07-05), recorded so future sessions don't relitigate them:
- Relocations.
docs/architecture-flow.mdanddocs/DEVELOPER_GUIDE.mdmoved into the wiki (the former as the engineering runtime map, the latter absorbed into the engineering index), and the D-numbered ADR log moved fromdocs/tenancy/decisions.mdintowiki/engineering/decisions/— split into per-decision files (three historical clusters grouped) with an index, where all future ADRs are recorded.docs/tracking/deliberately stays where it is: work registers are append-only records, not narrative. - The mechanics cluster is product-facing. Provider/storage/async/retention mechanics are written for product reasoning (behavior, latency, failure modes), never as implementation guidance — the engineering wiki and module READMEs carry the implementation view.
- Ship-state honesty. Pages state what the code does today (e.g. config-gated features that ship disabled, retention prunes that ship inert, seams awaiting a real backend) rather than the intended production posture; deploy-bound posture is called out as such.
- ADR references use D-numbers sparingly. D82–D93 carry
RENUMBER-ON-MERGEmarkers; wiki pages cite them by topic + number and accept a renumber sweep at merge time (the same rule the rest of the repo follows). - Ops runbooks stay out.
docs/production-release-checklist.md, GitHub/environment setup, and preview-access guides remain indocs/— they are procedures tied to specific infrastructure, not platform narrative.