feat(stats): add v1 immersion stats dashboard (#19)

docs/knowledge-base/README.md

@@ -0,0 +1,35 @@
+<!-- read_when: changing internal docs structure, adding guidance, or debugging doc drift -->
+
+# Knowledge Base Rules
+
+Status: active  
+Last verified: 2026-03-13  
+Owner: Kyle Yasuda  
+Read when: maintaining the internal doc system itself
+
+This section defines how the internal knowledge base is organized and maintained.
+
+## Read Next
+
+- [Core Beliefs](./core-beliefs.md) - agent-first operating principles
+- [Catalog](./catalog.md) - indexed docs and verification status
+- [Quality](./quality.md) - current doc and architecture quality grades
+
+## Policy
+
+- `AGENTS.md` is an entrypoint only.
+- `docs/` is the internal system of record.
+- `docs-site/` is user-facing; do not treat it as canonical internal design or workflow storage.
+- Internal docs should be short, cross-linked, and specific.
+- Every core internal doc should include:
+  - `Status`
+  - `Last verified`
+  - `Owner`
+  - `Read when`
+
+## Maintenance
+
+- Update the relevant internal doc when behavior or workflow changes.
+- Add new docs to the [Catalog](./catalog.md).
+- Record architectural quality drift in [Quality](./quality.md).
+- Keep stale docs obvious; do not leave ambiguity about whether a page is trustworthy.

docs/knowledge-base/catalog.md

@@ -0,0 +1,29 @@
+<!-- read_when: you need to know what internal docs exist, whether they are current, or what should be updated -->
+
+# Documentation Catalog
+
+Status: active  
+Last verified: 2026-03-13  
+Owner: Kyle Yasuda  
+Read when: finding internal docs or checking verification status
+
+| Area | Path | Status | Last verified | Notes |
+| --- | --- | --- | --- | --- |
+| KB home | `docs/README.md` | active | 2026-03-13 | internal entrypoint |
+| Architecture index | `docs/architecture/README.md` | active | 2026-03-13 | top-level runtime map |
+| Domain ownership | `docs/architecture/domains.md` | active | 2026-03-13 | runtime and feature ownership |
+| Layering rules | `docs/architecture/layering.md` | active | 2026-03-13 | dependency direction and smells |
+| KB rules | `docs/knowledge-base/README.md` | active | 2026-03-13 | maintenance policy |
+| Core beliefs | `docs/knowledge-base/core-beliefs.md` | active | 2026-03-13 | agent-first principles |
+| Quality scorecard | `docs/knowledge-base/quality.md` | active | 2026-03-13 | quality grades and gaps |
+| Workflow index | `docs/workflow/README.md` | active | 2026-03-13 | execution map |
+| Planning guide | `docs/workflow/planning.md` | active | 2026-03-13 | lightweight vs execution plans |
+| Verification guide | `docs/workflow/verification.md` | active | 2026-03-13 | maintained verification lanes |
+| Release guide | `docs/RELEASING.md` | active | 2026-03-13 | release checklist |
+| Active plans | `docs/plans/` | active | 2026-03-13 | task-scoped design and implementation artifacts |
+
+## Update Rules
+
+- Add a row when introducing a new core internal doc.
+- Update `Status` and `Last verified` when a page is materially revised.
+- If a page is known inaccurate, mark it stale immediately instead of leaving silent drift.

docs/knowledge-base/core-beliefs.md

@@ -0,0 +1,25 @@
+<!-- read_when: deciding how much context to inject, where docs should live, or how agents should navigate the repo -->
+
+# Core Beliefs
+
+Status: active  
+Last verified: 2026-03-13  
+Owner: Kyle Yasuda  
+Read when: making decisions about agent ergonomics, doc structure, or repository guidance
+
+## Agent-First Principles
+
+- Progressive disclosure beats giant injected context.
+- `AGENTS.md` should map the territory, not duplicate it.
+- Canonical internal guidance belongs in versioned docs near the code.
+- Plans are first-class while active work is happening.
+- Mechanical checks beat social convention when the boundary matters.
+- Small focused docs are easier to trust, update, and verify.
+- User-facing docs and internal operating docs should not blur together.
+
+## What This Means Here
+
+- Start from `AGENTS.md`, then move into `docs/`.
+- Prefer links to canonical docs over repeating long instructions.
+- Keep architecture and workflow docs in separate pages so updates stay targeted.
+- When a page becomes long or multi-purpose, split it.

docs/knowledge-base/quality.md

@@ -0,0 +1,40 @@
+<!-- read_when: assessing architecture health, doc gaps, or where cleanup effort should go next -->
+
+# Quality Scorecard
+
+Status: active  
+Last verified: 2026-03-13  
+Owner: Kyle Yasuda  
+Read when: triaging internal quality gaps or deciding where follow-up work is needed
+
+Grades are directional, not ceremonial. The point is to keep gaps visible.
+
+## Product / Runtime Domains
+
+| Area | Grade | Notes |
+| --- | --- | --- |
+| Desktop runtime composition | B | strong modularization; still easy for `main` wiring drift to reappear |
+| Launcher CLI | B | focused surface; generated/stale artifact hazards need constant guarding |
+| mpv plugin | B | modular, but Lua/runtime coupling still specialized |
+| Overlay renderer | B | improved modularity; interaction complexity remains |
+| Config system | A- | clear defaults/definitions split and good validation surface |
+| Immersion / AniList / Jellyfin surfaces | B- | growing product scope; ownership spans multiple services |
+| Internal docs system | B | new structure in place; needs habitual maintenance |
+| Public docs site | B | strong user docs; must stay separate from internal KB |
+
+## Architectural Layers
+
+| Layer | Grade | Notes |
+| --- | --- | --- |
+| `src/main.ts` composition root | B | direction good; still needs vigilance against logic creep |
+| `src/main/` runtime adapters | B | mostly clear; can accumulate wiring debt |
+| `src/core/services/` | B+ | good extraction pattern; some domains remain broad |
+| `src/renderer/` | B | cleaner than before; UI/runtime behavior still dense |
+| `launcher/` | B | clear command boundaries |
+| `docs/` internal KB | B | structure exists; enforcement now guards core rules |
+
+## Current Gaps
+
+- Some deep architecture detail still lives in `docs-site/architecture.md` and may merit later migration.
+- Quality grading is manual and should be refreshed when major refactors land.
+- Active plans can accumulate without lifecycle cleanup if humans do not prune them.