Current Documentation State
Status: Generated Last reviewed: Generated from repository state by yarn docs:generateScope: Authority map for TwoMore documentation. This page describes which docs should be trusted for current work and which docs are historical, planning, or stale-risk context.
Use this with Current Project State: that page answers "where is the codebase now?"; this page answers "which docs should I believe?"
Inventory Snapshot
| Inventory item | Count | Source |
|---|---|---|
| Markdown files in the audited docs surface | 221 | root docs + docs/ + web README + eslint-plugin docs |
| Files with an explicit status marker | 212 | metadata scan |
| Files with status or review metadata | 212 | metadata scan |
| Files missing status markers | 9 | metadata scan |
| Active/accepted docs missing review metadata | 23 | metadata scan |
| ESLint rule docs | 53 | packages/eslint-plugin/docs/rules/*.md |
| Exported ESLint rules | 53 | packages/eslint-plugin/index.js |
The most important doc-health finding: many useful docs still do not declare a status. Do not treat every Markdown file as equally authoritative.
Authority Order
When docs conflict, use this order:
- Machine-readable contracts: AGENTS.md wins for enforceable agent rules and architecture constraints.
- Generated current snapshots: Current Project State and this page win for generated repository facts.
- Current launch and operations docs: README.md, Production Readiness, and Pre-launch Checklist.
- Active operating guides: DEVELOPMENT_GUIDELINES.md, Shared Client Architecture, Supabase Integration, Builds & Deployment, Scale & Connection Limits, and Credentials.
- ADRs: accepted decisions and tradeoffs. If an ADR contains measured counts, verify them against generated state before reusing them.
- Historical logs: Rebuild Log, v1 Learnings, and the CLAUDE.md Milestone Archive. These are chronology, not current instruction.
- Draft/planning docs: specifications, counsel prep, roadmap ideas, and research artifacts. They can guide implementation only after checking current source and constraints.
Current Active Docs
These are the primary entry points for current work:
| Doc | Role |
|---|---|
| AGENTS.md | Canonical machine-readable contract for agents |
| README.md | Short project status, stack, quickstart, and doc links |
| DEVELOPMENT_GUIDELINES.md | Development rules and architecture conventions |
| CLAUDE.md | Rationale, workflow rules, enforcement stack, and roadmap context |
| Current Project State | Generated codebase/runtime/enforcement snapshot |
| Current Documentation State | Generated documentation authority and hygiene snapshot |
| Project Cockpit | VitePress entry point for current state, roadmap, blockers, and operating model |
| Change Routing Workflow | Change-type routing and multi-agent coordination |
| Release Versioning And OTA Workflow | Git/EAS release classification, versioning, OTA/build evidence, and rollout rules |
| Release Evidence Ledger | Durable ledger for release artifacts, hosted smokes, failed attempts, and no-artifact decisions |
| Claude Agent Ingestion Brief | Fast startup path for Claude agents ingesting the current docs/tracker system |
| Execute A Roadmap Slice | Copyable prompt contract for bounded roadmap slice execution |
| TwoMore Roadmap | Active product and engineering sequence with acceptance gates |
| Roadmap Implementation Plan | Concrete roadmap slices with allowed surfaces, acceptance proof, and verification |
| R1 Activation Source Pack | Source-grounded R1 onboarding, club discovery, invite, share, deep-link, and smoke inventory |
| Product Spec Sheet | Product definition, personas, scope, and success metrics |
| App Functionality Map | Source-grounded map of tabs, feature surfaces, and backend capabilities |
| Market And Revenue Research | Competitor landscape, revenue hypotheses, and market-backed roadmap implications |
| Sports Club Administration Opportunity Audit | App-to-market gap analysis and improvement plan for the club-admin niche |
| Production Readiness | Launch-readiness ledger |
| External Blockers Register | Owner/vendor/platform gates that normal repo edits cannot close alone |
| Pre-launch Checklist | Owner/external launch gates |
| Shared Client Architecture | Mobile/web sharing model and package boundaries |
| Supabase Integration | Supabase client, RLS, Edge Function, and freshness posture |
| Builds & Deployment | EAS Build, OTA, environment handling |
| Status & Recruitment Conventions | Canonical status-badge palette, status invariants, and derived recruitment rules (agent + human reference) |
| Session Surface Conventions | SessionCard 2×2 grid, chip-strip logic, viewer context threading, SessionInfoModel projections, SessionCompactRow, and session-detail IA (agent + human reference) |
| Korean Market Conventions | Korean market phone, discovery, KakaoTalk share, payment, Alimtalk, PIPA, marketing push, and LBS conventions (agent + human reference) |
| Tamagui & Styling Conventions | Tamagui-only rules, 4px-grid spacing system, typography roles, icon discipline, ModalPanel overlay contract, visual-consistency canon, and React-Compiler-first render performance (agent + human reference) |
| Architecture Conventions | Hex-architecture layer boundaries, write operations, tables, adapters, mappers, edge functions, and Zustand store hygiene (agent + human reference) |
| Component Conventions | Card tones, clickable primitives, participation/capacity indicators, text & badge roles, empty/loading states, home feed, tabs & chips, list virtualization, shells, wizards, confirms, and query boundaries (agent + human reference) |
| Data & Hooks Conventions | Formatting utilities, mutation/query hook discipline, port/adapter/mapper layer, telemetry & perf instrumentation, mock data, key rotation, tier display, cross-query cache writes, PII/consent obligations, and SQL migration footguns (agent + human reference) |
| Networking Conventions | Freshness tiers (LIVE/NOTIFY/AMBIENT/ON-DEMAND), fan-out protocols A–F, foreground UX protocols G–L, and composer hooks (useLiveSessionData, useClubContext, usePlayerProfileData) (agent + human reference) |
| Notification Conventions | 정보성 vs 광고성 classification (§50), Android channel setup, iOS soft-prompt timing, and server-enforced frequency caps (agent + human reference) |
| Club Surface Conventions | Club card v3 FOUR-ZONE composition canon: banner hero, members cluster, ClubScheduleBlock, chip strip, SessionCompactRow next-session row, avatar privacy, role-grouped member list (agent + human reference) |
| Multi-Agent Operating Model | Claude Code + Codex sync contract, canon layering, handoff protocol, drift prevention |
| Engineering Soundness Masterfile | Living reference for the R3-6 engineering-soundness track: the five-audit ledger, the 10 gate-enforced invariants, current state, and the roadmap. The Cockpit is the tracker; this is the deep evidence (agent + human reference) |
| Surface System Masterfile | Owner-approved execution spec for the clubs + sessions surface unification (ClubInfoModel, projections, CTA canon); the next R3 design-led build track, spec-approved but not started (agent + human reference) |
| UX Residual Owner Queue | The 10 UX-audit items awaiting owner decisions: 5 wireframe-first features, 2 external blockers, 2 data-layer tasks, 1 hygiene item — each with reason + effort (owner backlog) |
| Working-Model Retro | Living, evidence-based collaboration feedback: what works, what does not, owner-throughput levers, and the assistant self-critique (shared retro) |
Tracker Reference Libraries
The VitePress sidebar keeps current and next work primary, then groups reference docs into compact libraries instead of listing every active doc in navigation.
Historical Or Context Docs
These docs are useful but should not be used as current implementation truth without checking active docs and source:
| Doc | Current interpretation |
|---|---|
| Rebuild Log | Chronological implementation history |
| v1 Learnings | Historical lessons from the prior app |
| Drift Prevention | Historical strategy; current substrate is AGENTS.md + ESLint + ArchUnitTS + metrics |
| Networking Foundation Plan | Historical phased plan with current corrections; persistent realtime is retired |
| Club Growth Completion Slices | Historical club-growth evidence packet; current roadmap slices live in the implementation plan |
| CLAUDE.md Milestone Archive | Historical milestone ledger; generated current-state docs supersede older claims |
Draft Or Planning Docs
These are not automatic implementation authority:
| Doc family | Use |
|---|---|
docs/specifications/* | Product and model specs; verify against current domain code and migrations before implementation |
docs/architecture/foundational-schema-* | Research and decided direction; not always a migration batch |
docs/architecture/international-data-model.md | Approved design, build pending |
docs/history/counsel-prep-brief.md | Draft for counsel review |
docs/guides/api-expo-notifications.md | Planned guide; verify against current notification implementation before using |
Doc Hygiene Rules
When updating docs:
- Prefer generated/source-command-backed facts over copied counts.
- Run
yarn docs:generateafter changes that affect generated state. - Add or update
Statusand review metadata on active docs touched for current work. - Mark historical plans as
Historicalrather than rewriting chronology. - Keep launch blockers in Pre-launch Checklist or Production Readiness, then link to them.
- Keep hard constraints in AGENTS.md, not in narrative-only docs.
- Keep active/historical/draft doc routing metadata in
scripts/doc-state-config.mjs; do not maintain parallel authority lists.
Known Doc Refactors Still Worth Doing
These are docs-only improvements that would make the project easier to maintain:
- Expand
yarn docs:lint-stalewhen new high-risk facts become frequent enough to justify mechanical checks.
Refresh Procedure
bash
yarn docs:generate
yarn docs:check