# Oshun Documentation

This is the index. Most docs live one or two clicks away under the canonical
homes below; nothing of substance lives at this level.

## Start here

- **[Getting Started](reference/getting-started.md)** — environment setup and
  first build
- **[Architecture](reference/architecture.md)** — system overview, domain
  boundaries, shared infra
- **[Contributing](CONTRIBUTING.md)** — PR process, code review, conventions

## Canonical homes

| What                                                                                                                          | Where                      |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| Cross-cutting reference (architecture, contracts, standards, runbooks, inventories)                                           | [`reference/`](reference/) |
| Per-domain docs (one folder per domain — README, architecture, features, developer-guide, database, api, audits, runbooks, …) | [`domains/`](domains/)     |
| Architecture Decision Records (single global numbering, 0001–0072)                                                            | [`adr/`](adr/)             |
| Open proposals (pre-decision; accepted ones become ADRs)                                                                      | [`proposals/`](proposals/) |
| Release-cycle artifacts (V1 audits, scope, specs, design, runbooks, reports; P2 strategy work)                                | [`releases/`](releases/)   |
| How-to guides (adding a library, debugging a domain, etc.)                                                                    | [`guides/`](guides/)       |

## Other top-level dirs

- [`api/`](api/) — API surface index and protocol references
- [`compliance/`](compliance/) — compliance artifacts (SOC2, GDPR, audit trails)
- [`conventions/`](conventions/) — repo-wide conventions outside the
  `coding-standards.md` core
- [`infrastructure/`](infrastructure/) — deployment topology, ECS, RunPod,
  observability stack diagrams
- [`integrations/`](integrations/) — third-party integrations (ElevenLabs,
  ComfyUI, CivitAI, …)
- [`migration/`](migration/) — domain migration guides
- [`performance/`](performance/) — performance baselines and budgets
- [`research/`](research/) — research notes, mediator-AI, gap analyses for
  upcoming work
- [`training/`](training/) — onboarding materials and workshops

## Generated content

These are auto-regenerated and are tracked-but-don't-edit:

- [`kalika/`](kalika/) — Kalika API reference and tutorial notebooks
  (`pnpm kalika:api-reference` and `kalika:tutorial-notebooks` rebuild the
  `generated/` subtrees, which are gitignored)
- [`domains/lilith/extras/generated/`](domains/lilith/extras/generated/) —
  frozen output from a generator pipeline that does not run in this monorepo;
  treat as source-of-truth for downstream consumers (e.g., `libs/lilith/sdk`
  reads `master-openapi.yaml` from here)

## Reorg history

The current layout was reached over an 11-commit reorganization (Phases 0–8).
The plan, regex rules, and per-phase rationale live in
[`reference/REORG_PLAN.md`](reference/REORG_PLAN.md). The migration tool —
`tools/docs/reorg.mjs` — is preserved and can be re-run for incremental
cleanups.
