Eve library

Oshun Documentation Standards

Spec

Revision 1

On this page

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