# Oshun Documentation Standards

Last updated: May 8, 2026

This standard enforces a uniform organization for all Oshun-local domain
documentation under `docs/releases/v1/domains/`. The goal is not only
consistency, but also expert-quality writing that separates implemented
capability from planned scope without losing completeness.

## Oshun Documentation Structure

- `docs/releases/v1/specs/readme.md`: Oshun implementation guide and top-level
  documentation map
- `docs/adr/`: architecture decision records (consolidated)
- `docs/releases/v1/audits/`: audit and review artifacts
- `docs/releases/v1/domains/`: one folder per domain represented in `TODOS.md`
- `docs/releases/v1/reports/domain-doc-remediation-checklist.md`: cross-domain
  completion checklist for this remediation program

## Required Domain Folder Contract

Every folder under `docs/releases/v1/domains/<domain>/` must contain:

- `README.md`: domain overview, evidence profile, capability pillars, and source
  precedence
- `feature-inventory.md`: exhaustive feature scope derived from repository
  evidence, standalone docs, and mapped TODO phases
- `implementation-map.md`: repository footprint, API roots, tests, integration
  points, and remaining gaps

## Source Precedence Rules

1. Prefer actual repository implementation under `apps/`, `libs/`, `services/`,
   `openapi/`, and tests
2. Use `TODOS.md` phase sections to capture planned or incomplete feature scope
3. Use `docs/domains/<domain>/` as supporting canonical documentation where it
   exists
4. Do not state a feature as implemented when the only evidence is TODO scope;
   identify it as checklist-derived or planned scope
5. Prefer polished prose, readable tables, and clear capability taxonomies over
   raw inventory dumps

## Uniform Section Expectations

- Each domain `README.md` must declare slug, aliases, TODO phases, repository
  status, Oshun integration status, evidence profile, and capability pillars
- Each `feature-inventory.md` must include an overview, source hierarchy,
  capability pillars, implementation-derived surfaces, canonical standalone
  coverage, and full mapped TODO phase detail
- Each `implementation-map.md` must enumerate applications, libraries, services,
  API roots, standalone docs, tests, Oshun integration references, and explicit
  documentation gaps

## Naming And Organization Rules

- Use one lowercase slug per domain folder
- Preserve repo-native slugs where they already exist (for example `kuanyin`,
  `aphrodite`, `project-obsidian`)
- Keep generated domain docs inside `docs/releases/v1/domains/`; do not scatter
  per-domain Oshun docs back into the root

## Maintenance

Regenerate this structure after TODO phase changes or major domain
implementation changes:

```bash
node tools/docs/generate-oshun-domain-reference.mjs
```
