README.md

DebateLab documentation

Start with the smallest document that answers the task instead of loading every file.

Freshness labels

• Current: maintained guidance. Update it in the same change as the source it describes.
• Plan: intended work. Revalidate it against the current branch before executing it.

npm run docs:check checks every Markdown file for broken local links and retired checkout paths, except generated output and plan files under plans/. The plan index plans/README.md is still checked.

Understand the system

• Architecture, current. Open before changing subsystem boundaries or tracing browser, Current Debate, data, AI, auth, billing, observability, or PWA flows.
• Agent guide, current. Always-loaded commands, safety rules, and routing.
• Root README, current. Product overview and quick start.

Write and review code

• Coding standards, current. Review rules drawn from accepted review findings, split by area under standards/. Read by reviewers; open an area file when a review finding cites it.

Set up and develop

• Development guide, current. Open for installation, environment behavior, linked worktrees, frontend, backend, or database workflows.
• Supabase backend, current. Open before changing Edge Functions, shared backend modules, migrations, RLS, RPCs, or backend secrets.
• Collaboration service, current. Only for the hidden Workspace.

Test and verify

• Testing guide, current. Open before running coverage, Edge Function, database, browser, agentic, WebKit, live-provider, canary, or protected staging gates.
• package.json owns npm script definitions.
• vitest.config.ts and playwright.config.ts own test selection and browser behavior.

Operate or deploy

• Operations guide, current. Open before changing CI, Vercel hosting, staging, CORS, migrations, Edge Function deployment, rollback, or production state.
• Staging, current. How to get into staging, the seeded accounts, and the VPS timer that syncs it with main.
• .github/workflows/ is the CI source of truth.

Plans

• Plan index, plan. What is in progress, the backlog, what is on hold, and what shipped.

Maintenance rule

Each operational fact has one owner:

• scripts and runtime versions: package.json
• routes: src/App.tsx
• test behavior: Vitest and Playwright config
• CI behavior: .github/workflows/
• database behavior: supabase/migrations/ and database tests
• Edge Function behavior: supabase/functions/
• hosting and HTTP policy: vercel.json

When an owner changes, update only the focused document that explains that fact. Prefer links over copied catalogs.