docs: reorganize docs into maintainer-first structure

Author: Lemonawa

docs/README.md

@@ -0,0 +1,24 @@
+# Documentation Index
+
+This `docs/` tree is optimized for maintainer use: quick retrieval, low noise, and explicit lifecycle.
+
+## Layout
+
+- `docs/runbooks/`: repeatable operational procedures (deploy, rollback, emergency checks)
+- `docs/decisions/`: durable architecture/product decisions (ADR-style notes)
+- `docs/plans/active/`: plans currently in progress
+- `docs/plans/archive/`: completed or superseded plans (grouped by year)
+- `docs/perf/`: benchmark artifacts and performance snapshots
+
+## Lifecycle Rules
+
+1. Draft plans in `docs/plans/active/`.
+2. When work is done or abandoned, move the plan to `docs/plans/archive/<year>/`.
+3. Record long-term rationale in `docs/decisions/` instead of leaving it only in plan files.
+4. Keep runbooks task-oriented and executable; avoid narrative-only docs.
+
+## Naming
+
+- Plans: `YYYY-MM-DD-<topic>.md`
+- Decisions: `YYYY-MM-DD-<topic>-decision.md`
+- Runbooks: `<topic>-runbook.md`

docs/decisions/README.md

@@ -0,0 +1,11 @@
+# Decisions
+
+Use this folder for durable decisions (ADR-like records), not implementation plans.
+
+Template suggestion:
+
+- Context
+- Decision
+- Trade-offs
+- Consequences
+- Revisit trigger

docs/plans/README.md

@@ -0,0 +1,14 @@
+# Plans
+
+Plans are temporary execution artifacts.
+
+## Folders
+
+- `active/`: only currently actionable plans
+- `archive/<year>/`: historical plans
+
+## Operator Rules
+
+- Never keep finished plans in `active/`.
+- If a plan is replaced by a newer version, archive the old one immediately.
+- If a plan drives permanent policy, extract that policy into `docs/decisions/`.

docs/plans/active/README.md

@@ -0,0 +1,5 @@
+# Active Plans
+
+Put only ongoing plans here.
+
+A plan is considered active when there are still planned steps not executed yet.