Status: current
Index for humans and AI agents. Agents should start at AGENT_START_HERE.md every session.
| Folder | Purpose |
|---|---|
| AGENT_START_HERE.md | Session entry point: reading matrix by task, product/stack truth, drift |
| DESIGN_SYSTEM.md | UI design system (tokens, layout, copy) + architecture overview |
| architecture/index.html | Architecture docs (HTML) — system, deployment, security, API, ADRs |
| database-architecture.html | Database schema, indexes, data flows (HTML) |
| features/ | How each product system works today |
| operations/ | Local setup, env, database, deployment, verification |
| strategy/ | Roadmap and product direction (empty until added) |
| archive/ | Historical plans, reviews, superseded docs — do not treat as current |
| Doc | Topic |
|---|---|
| overview.md | Routes, API surface, app structure |
| auth.md | Better Auth + GitHub OAuth |
| release-ingestion.md | Cron, GitHub fetch, AI persist |
| release-feed.md | Dashboard feed, filters, read state |
| ai-summarization.md | OpenRouter summarisation + advice |
| public-stacks.md | /stacks SEO pages |
| agent-skill-updates.md | Curated skill revisions, durable ingestion, impact reports and rollout |
| digest-signup.md | Email capture (no sender yet) |
| server-actions.md | src/lib/actions.ts |
| Doc | Topic |
|---|---|
| local-development.md | Install, dev server, scripts |
| environment-variables.md | Full env reference |
| database.md | Schema, migrations, seed |
| deployment.md | Vercel, cron, production checks |
| verification.md | Typecheck, lint, build, manual checks |
| ai-workflow.md | Pinned and local agent skills, synchronization, CI guards and compatibility pilot |
| skill-staging-verification.md | Skill Updates isolation, live approval gates, budgets and rollout sequence |
| skill-openrouter-live-evaluation.md | Phase B live results, report quality and billing limitations |
| skill-phase-b-benchmark-readiness.md | Phase B semantic/diagnostic hardening and proposed fair model benchmarks |
| typescript.md | Why TypeScript 7 and 6 are both installed |
| navigation-and-caching.md | Cache Components, Partial Prefetching, Suspense, and cache policy |
Nothing archived yet. When a plan ships or a review goes stale, move it under:
archive/implementation/— completed implementation plansarchive/reviews/— audits and reviewsarchive/ui/— UI revamp / design docs superseded by shipped work
Mark archived files with Status: historical or Status: superseded in the header.
- One current doc per feature — no duplicate sources of truth.
- Status header on every doc:
current,planned,shipped,historical, orsuperseded. - Trust code — update docs when architecture, routes, env, schema, auth, cron, or user-visible behavior changes.
- Move, don't delete — completed plans go to
archive/. - Link from AGENT_START_HERE when adding a new feature or ops doc to the reading matrix.
- UI changes must follow DESIGN_SYSTEM.md for tokens, frames, typography, and badges.
- Relative links — use paths from the doc's location; run link checks after moves.
Root-level README.md stays the public-facing quick start; deep detail lives here.