# Oshun V1 Phase-2 Documentation Index

**Owner:** eng-platform &nbsp;**Implements:** V1-P2-0370 &nbsp;**Updated:**
2026-04-27

This directory holds the per-decision detail files behind the V1 Phase-2 work
tracked in [`docs/releases/v1/specs/todos-p2.md`](../OSHUN_V1_TODOS_P2.md).
Every Phase-2 ticket whose verification mentions a strategy decision, vendor
audit, or contract sketch resolves to a file in this directory. The backlog file
is the source of truth for status; the docs here are the source of truth for
rationale.

> **Conventions in this directory.** Each doc opens with a metadata block
> (`Date`, `Owner`, `Backlog item`, `Status`), states the decision in the first
> paragraph, and follows up with constraints, alternatives considered, and a
> verification section. Do not write design without a backlog ticket — the
> backlog is what drives prioritisation. New docs land alongside the ticket flip
> from `[ ]` to `[x]`.

## Per-domain detail files

Grouped by Phase-2 work area. Each line links the doc, the originating ticket,
and the one-line decision summary. Click through for the full design.

### Isis (LLM gateway, cost, determinism)

- [Isis LLM Gateway Audit](./isis-llm-gateway-audit.md) — V1-P2-0001 — audit the
  existing `libs/isis/llm-providers/` implementation; identify gaps before the
  Tier-A replacement work begins.
- [Isis Cost-Tracking and Quota Contract](./isis-cost-tracking-contract.md) —
  V1-P2-0005 — token-accounting + per-tenant quota model the cost middleware
  must enforce.
- [Isis Deterministic-Mode Contract](./isis-deterministic-mode.md) — V1-P2-0021
  — replay/snapshot semantics for golden-test runs.

### ML / on-device runtime (V1-P2-021x family)

- [On-Device ML Runtime Strategy](./ml-runtime-strategy.md) — V1-P2-0210 — ONNX
  Runtime Web (browser) + ONNX Runtime Node (server); WASM for fallback.
- [Pose Estimation Provider](./pose-estimation-provider.md) — V1-P2-0211 —
  default provider + accuracy/latency contract.
- [Object Detection Provider](./object-detection-provider.md) — V1-P2-0212 —
  ONNX YOLOv8 (`n` and `s`) as the real-time default.
- [ASR / VAD Provider](./asr-vad-provider.md) — V1-P2-0213 — ONNX Whisper family
  (`tiny.en`/`base.en`/`small.en`/`medium.en`).
- [Speaker Identification Provider](./speaker-id-provider.md) — V1-P2-0214 —
  selected speaker-ID stack and accuracy budget.
- [Emotion Detection Provider](./emotion-detection-provider.md) — V1-P2-0215 —
  voice (wav2vec2-emotion) + image (FER) provider choice.
- [Cross-Encoder Reranker](./cross-encoder-reranker.md) — V1-P2-0216 — BAAI
  BGE-Reranker (`bge-reranker-v2-m3` / `v2-large`) for the rerank stage.

### Iris (semantic / privacy / desktop / docs)

- [Embedding Provider Stack Decision](./embeddings-provider-decision.md) —
  V1-P2-0030 — `IrisEmbeddingClient` provider chain (BGE / OpenAI / fallback).
- [OCR Strategy Decision](./ocr-strategy.md) — V1-P2-0060 — selected OCR engine
  and per-page latency budget.
- [Vision LLM Strategy Decision](./vision-llm-strategy.md) — V1-P2-0064 —
  vision-LLM provider with accuracy/cost/refusal-mode contract.
- [Document Layout Analysis Strategy](./document-layout-analysis-strategy.md) —
  V1-P2-0066 — DLA pipeline for ingested PDFs / scans / screenshots.
- [Desktop Automation Stack Decision](./desktop-automation-strategy.md) —
  V1-P2-0090 — pointer/keyboard/clipboard/screen-capture stack.
- [Crypto Replacement Targets](./crypto-replacement-targets.md) — V1-P2-0176 —
  sites in `libs/aje/`, `libs/aphrodite/`, `libs/airmid/`,
  `libs/iris/memory/privacy/`, `libs/iris/a2a/`,
  `libs/iris/privacy/security/dlp/` whose stub crypto must move to the real
  primitives, and the migration order.

### TTS / multimedia gateway

- [OSHUN TTS Gateway Audit](./tts-gateway-audit.md) — V1-P2-0140 — state of the
  existing TTS gateway and the work needed before the Tier-A replacement lands.

### Aja (motion, GPU pipeline)

- [Aja Readiness Audit](./aja-readiness-audit.md) — V1-P2-0330 — full inventory
  of `libs/aja/*` and `apps/aja/*` against the §2.6 quality bar.
- [Aja V1 Descope Decision](./aja-descope-decision.md) — V1-P2-0331 — what stays
  in V1 vs. what slips to V2, driven by the readiness audit.
- [Aja Kubernetes Runtime Strategy](./aja-runtime-strategy.md) — V1-P2-0333 — V1
  deployment posture for Aja services.
- [Aja GPU Pipeline Strategy](./aja-gpu-pipeline-strategy.md) — V1-P2-0334 —
  per-stage GPU pipeline, batching, and back-pressure plan.

### Persistence / database

- [Drizzle / Persistence Completion Targets](./drizzle-completion-targets.md) —
  V1-P2-0233 — the sites under `libs/` and `apps/` whose `Drizzle`/persistence
  layer is currently a placeholder, and the order in which they migrate.

### Quality / scanner conventions

- [Stub-Indicator Allow-List Conventions](./stub-indicator-allowlist.md) —
  V1-P2-0353 — `// stub:legitimate <reason>` / `// random:legitimate <reason>`
  conventions consumed by `scripts/stub-indicator-scan.sh`. Companion to the
  `stub-indicator-scan` (V1-P2-0350) and `silent-random-scan` (V1-P2-0351) CI
  jobs.

## Cross-cutting templates

These templates are intentionally generic — every Tier-A subsystem fills out its
own copy.

- [Architecture Overview](./architecture-overview.md) — V1-P2-0371 — the
  canonical data-flow map across domains after foundational work lands. Read
  this first when joining a new domain.
- [Runbook Template](./runbook-template.md) — V1-P2-0372 — mandatory sections
  (rate limits, outage drill, escalation contacts, vendor SLA, cost guardrails)
  that every operationally-owned subsystem must complete.
- [Threat Model Template](./threat-model-template.md) — V1-P2-0373 —
  STRIDE-aligned template for per-Tier-A subsystem threat models.

## Strategy decisions / ADRs

Phase-2 decisions that span multiple domains live as Architecture Decision
Records under [`docs/adr/`](../../adr/) (72 ADRs as of 2026-04-27 covering shell
architecture, web/PWA strategy, cross-domain routing, identity, analytics,
design system, observability, etc.). Use the index in [`docs/adr/`](../../adr/)
and the corresponding ticket in the backlog as your starting point.

## Dashboards

Operational signals for every Phase-2 subsystem land in the Grafana stack at
`docker/observability/grafana/`. The dashboards below are the authoritative live
views; runbooks (V1-P2-0372) link directly to the relevant board for each alert
/ SLO.

### Per-domain Grafana dashboards

Source: `docker/observability/grafana/dashboards/`.

- `bellona/migration-orchestrator.json` — Bellona migration runs: per-stage
  queue depth, attempt counts, retry budgets, failure rates.
- `hathor/narrative-lattice.json` — Hathor lattice: graph-traversal latencies,
  cache hit rate, contradictions surfaced.
- `isis/asset-lifecycle.json` — Isis assets: queued → generating → rendered →
  published transitions, per-tenant counts.
- `isis/generation-pipeline.json` — Isis generation pipeline: token accounting,
  per-provider latency, cost-quota burn, deterministic-mode divergences.
- `lilith/event-handlers.json` — Lilith handlers: per-handler latency
  histograms, retry/circuit-breaker state.
- `lilith/experience.json` — Lilith experience: session-quality metrics
  (frame-time, audio underruns, motion-tracking confidence).
- `oshun/platform-overview.json` — top-of-funnel view across all domains: SLOs,
  error rate, deploy markers.
- `oshun/infrastructure.json` — node/pod/networking signals at the cluster
  level.
- `sophia/research.json` — Sophia research workflows: query latency, rerank
  quality, ingestion lag.
- `yemaya/creative-studio.json` — Yemaya studio: project-open latency,
  asset-load throughput, autosave health.
- `yemaya/collaboration.json` — Yemaya collaboration: per-room presence, CRDT op
  latency, conflict-resolution counts.
- `infrastructure/{node,elasticsearch,kafka,postgres,redis}.json` — baseline
  infrastructure fleet signals.

### Other observability surfaces

- Kibana — error tracking and request tracing, dashboards under
  `deploy/elk/kibana-dashboards/` (`error-tracking-dashboard.json`,
  `performance-monitoring-dashboard.json`, `service-overview-dashboard.json`).
- CloudWatch — managed AWS metrics; dashboards declared in Terraform at
  `infra/terraform/cloudwatch/dashboards.tf`.
- Saraswati — additional Grafana dashboards declared in
  `docker/observability/saraswati-grafana-dashboards.yml` (loaded by the
  observability profile).

## Quality / scanner workflows

These CI jobs gate the §2.6 quality bar; their detail docs live in this
directory or in the workflow files themselves.

- [`stub-indicator-scan`](../../../.github/workflows/stub-indicator-scan.yml) —
  V1-P2-0350 / V1-P2-0351 / V1-P2-0356 / V1-P2-0357 — qualitative + silent
  random + pre-commit verification + sticky PR comment. Allow-list documented in
  [`stub-indicator-allowlist.md`](./stub-indicator-allowlist.md).
- [`adversarial-grep-trend`](../../../.github/workflows/adversarial-grep-trend.yml)
  — V1-P2-0355 — nightly per-domain stub-marker count + week-over-week delta.
  Snapshot artifact retains 90 days.
- [`test-coherence-check`](../../../.github/workflows/test-coherence-check.yml)
  — V1-P2-0352 — vitest assertion classification (SHAPE / BOOLEAN / COMPUTED /
  OTHER) and per-file coherence score.
- [`external-api-guard`](../../../.github/workflows/external-api-guard.yml) —
  V1-P2-0358 — fail any PR introducing a new outbound HTTP call without retry +
  circuit breaker + telemetry. Allow-list documented inline in
  `scripts/external-api-guard.mjs` (file-level imports + path allow-list +
  `// http:guarded <reason>` inline comment).

## Adding a new entry

1. Pick the next backlog ticket from
   [`OSHUN_V1_TODOS_P2.md`](../OSHUN_V1_TODOS_P2.md). The ticket text states the
   deliverable; this directory holds the rationale.
2. Create a new file in this directory using kebab-case (
   `<domain>-<topic>.md`). The first heading must include the ticket ID
   (`# <Title> — V1-P2-NNNN`) so the doc is grep-able by ticket.
3. Open with a metadata block: `Status`, `Date`, `Owner`, `Backlog item`,
   `Audience`. Keep all five fields populated, even if the value is "n/a — see
   linked ADR".
4. Add an entry to the appropriate group above. The line format is
   `- [Title](./file.md) — V1-P2-NNNN — one-sentence summary.`. Keep the summary
   readable in a 100-column terminal.
5. Land the doc in the same PR that flips the ticket to `[x]`. The verification
   note in the backlog should reference the doc by relative path so reviewers
   can read both in one click.
