Development context

The things a contributor needs to know that don't fit neatly into a guide — where the codebase came from, the decisions that shape it, and the conventions that make review predictable.

Where this came from

The Hub is a consolidation: a root Next.js + Payload + PostgreSQL application (formerly hub-v2) with the member interface as App Router routes backed by src/member/, and the content MCP in mcp-content/ as an independent service. An earlier Vite/Express stack — and the interim wouter SPA that succeeded it — was retired; YMC-v2 is historical context, not somewhere to add features. The most consequential recent changes were the authority consolidation (two overlapping stores collapsed into the single authority_records model documented in Organisation and permissions) and the member interface's absorption into the App Router. If you find code that looks like it handles "the old way", it's probably a migration artefact, not live logic.

The decisions that shape the code

• No admin UI. Staff operations run through API endpoints and terminal scripts. Every surface is defended explicitly; there is no generated CRUD panel to accidentally expose.
• One authority store. authority_records is the single source of truth — no parallel ledgers, no denormalised mirrors. When the model needs a new fact, it goes on the record or the registry, not into a second table to sync.
• Deny, never widen. Unknown role strings, out-of-scope grants, rows the registry doesn't recognise — all resolve to no authority, visibly, rather than being guessed at.
• Structure in git, data in databases. The repository is operational with zero data; nothing about real members is committed.
• Every write is audited. Transitions go through endpoints and services that record who did what — a change that leaves no trail is incomplete.
• The MCP is a client. Agents hold member credentials and call the API; they get no DATABASE_URL and no privileged path.

Conventions

• British English in docs, interface copy, comments and review text. Preserve official titles, identifiers and API names verbatim.
• Endpoint naming — transitions are named verbs (/present, /close, /review), not PATCHes to a status field.
• Migrations are append-only, timestamped, idempotent where possible, and contain transforms (INSERT…SELECT), never row literals.
• The lock contract — multi-record writes acquire advisory locks on all involved accounts, ascending and deduplicated, then row-lock inside the transaction. withAuthorityLock is the only implementation.
• src/shared/ stays isomorphic — mcp-content loads it under plain node, so it is .js only, with no Node-only APIs or process.env.
• Prettier formats everything — run npm run format before pushing; CI checks it.

Working agreements

• Changes go through pull requests — CONTRIBUTING.md is the process.
• AGENTS.md in the repo is the binding statement of invariants; when you change architecture, update it in the same PR.
• Agent contributors get their grounding from .agents/skills/ (per-domain recipes — authority, endpoints, member UI, data, MCP) and share session memory through the memory MCP server (Hindsight bank youngo-hub: recall tagged project:youngo-hub before work, retain verified findings after). There is no local file vault — npm run sync:mcp writes the server into local agent configs from HINDSIGHT_API_KEY (never committed).
• Review is a conversation, not a gate — CodeRabbit and humans both leave threads; resolve them by changing code or explaining why not, not by dismissing.