# Content, Localization, Documentation, Launch, and Exit Criteria

This page describes the cross-cutting readiness layer that decides whether Oshun
V1 is allowed to ship: launch-quality content per domain, a real localization
catalog, the documentation and runbook corpus, the beta/GA launch gates, and the
end-state exit criteria that define "feature-complete." It serves release
captains, content and localization owners, quality and security leads, and
anyone signing a go/no-go decision. Unlike the domain pages (which describe what
a customer can do), this page describes what has to be true _across all the
domains_ before launch. The page is also unusual in V1: much of what it
describes is encoded as machine-readable, test-locked manifests in
`libs/oshun/analytics/` rather than living only in prose. The companion runtime
doc is
[Architecture, Platform Foundations, and Security](./platform-foundations-and-security.md);
the backlog of record is [../features.md](../features.md) and `V1/TODOS.md`.

## Where this sits in V1

Most of the readiness layer is concrete, tested code rather than spec-only
intent. The localization catalog (`libs/oshun/i18n`), the analytics taxonomies
and evaluation/launch manifests (`libs/oshun/analytics`), the design tokens
(`libs/oshun/design-tokens`), the UI component library (`libs/oshun/ui`), and
the design-language audit modules (`libs/oshun/design-language`) are all real,
sizable, and covered by tests. What remains genuinely operational — and
therefore _not_ verifiable purely from source in this repository — is the
execution of the launch drills themselves: the rollback/residency/DSAR/red-team
rehearsals, the penetration-test sign-off, and the human beta and GA go/no-go
decisions. Several launch-readiness _manifests_ exist that enumerate and lock
those obligations (`v1-33-launch-gate-signoff`, `v1-launch-readiness-manifest`,
`v1-security-readiness-manifest`), but the manifests record _what must be done
and where its evidence lives_, not that the drills were already run. This page
is candid about that boundary: a locked manifest entry is a real, drift-failing
contract; it is not the same thing as a completed operational rehearsal.

## Content readiness per domain

V1 ships launch-quality content across the six customer domains — Tara, Veritas,
Nyx, Arete, Nisaba, and Metis — at two committed tiers (minimum-viable and
launch-quality) plus a premium tier where the product charges for depth. These
bundle definitions are not loose prose: they are locked verbatim in
`libs/oshun/analytics/src/v1-32-content-localization-documentation.ts` as
`OSHUN_V1_32_CONTENT_BUNDLE_GATES`, one `V132ContentBundleGate` per domain. Each
gate carries the `minimumViable`, `launchQuality`, and `premium` content lists,
a `reviewChecklist`, a structured `accessibilityPlan`, the per-tier
`localeCommitments`, and a `seedEvidence` pointer to the domain's database seed.
Because the array is `as const` and asserted by a sibling test, drift in any of
these counts or checklist items fails CI closed.

| Domain  | Minimum-viable bundle (excerpt)                                                                         | Launch-quality bundle (excerpt)                                                     | Seed evidence                                                          |
| ------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Tara    | 24 ritual templates across 6 archetypes, canonical transcripts, certified teacher lineage               | 60 templates, multi-track reflection prompts, launch-quarter live event calendar    | `libs/tara/database/prisma/seed.ts`                                    |
| Veritas | 30 daily-briefing stories, canonical claim/source/counterclaim packs, bound retraction-cascade fixtures | 100 stories, per-claim confidence band, per-source attribution paths                | `libs/veritas/database/src/seed.ts`                                    |
| Nyx     | 40 launch-quarter sky events, calendar-sync metadata, per-event observation window                      | aurora + meteor-shower modeling, lat-long-aware push, multi-event rituals           | `libs/nyx/database/src/migrations/20260118000007_seed_initial_data.ts` |
| Arete   | 30 habits with check-ins, 12 goal archetype templates, weekly-review template                           | coach-tone customization, habit-chain templates, assistant-bound nudges             | `libs/arete/core/src/db-seed.ts`                                       |
| Nisaba  | 200 passages from 8 source manuscripts, canonical editions + 2 translations per passage                 | 1,000 passages, 5 manuscripts with rights-cleared full-image scans, citation export | `libs/nisaba/database/prisma/seed.ts`                                  |
| Metis   | 12 BYOM source bundles, 12 generated courses, 12 lesson sets, 12 tutor personas                         | 60 courses across six core domains, per-course pedagogy bands                       | `services/metis/tests/test_curriculum_seed_pack_helpers.py`            |

Every gate's `reviewChecklist` is domain-specific rather than generic — Tara
requires "lineage attribution verified" and "crisis-content disclosure
reviewed"; Veritas requires "every claim bound to a source" and "counterclaim
view rendered before publish"; Nisaba requires "rights confirmed for every scan"
and "provenance manifest signed." This is the editorial gate that the authoring
tooling enforces; see
[Creator Roles and the Authoring Workspace](./authoring-workspace-and-roles.md)
and [Review, Compliance, and Trust & Safety](./review-trust-safety.md).

The companion content-readiness audits per domain are locked in
`OSHUN_V1_LAUNCH_READINESS_MANIFEST`
(`libs/oshun/analytics/src/v1-launch-readiness-manifest.ts`) under
`V1-CONT-001..005`, each pointing at the shipped `libs/oshun/domain-*`
integration package (for example, Tara's audit cites 43 source files; Nisaba's
cites 14). The bundle definitions, premium definitions, review checklists, and
localization/accessibility plans are documented in `docs/content/v1-bundles.md`
(`V1-CONT-006..009`), and the seed-data fixtures are mapped to real Playwright
and Maestro fixtures under `V1-CONT-010..015`.

### Accessibility plans are part of content readiness

Accessibility is not a separate launch checklist item bolted on at the end — it
is a field on every content bundle gate. Each `V132AccessibilityPlan` declares
six obligations: `transcript`, `captions`, `altText`, `reducedMotion`,
`largeTextReview` (a 200% text-zoom review across all domains), and
`screenReader`. The phrasing is content-specific: Nisaba requires "alt text for
every manuscript scan" and "passage and annotation regions exposed"; Tara
requires a "full alternative pacing variant" for reduced motion and "ritual
stages announced as headings." The runtime accessibility checks that police
these in the shipped product are described in
[Design System and Experience Quality](./design-system.md) and
[Analytics, Observability, Testing, and Security](./analytics-and-testing.md).

## Localization and internationalization

The localization story is materially richer than "externalized strings." The
canonical shared-string catalog lives at `libs/oshun/i18n/src/index.ts` and
ships a complete, typed, fully translated message catalog plus a fallback,
formatting, and layout-budget API. In the web shell this catalog sits _under_
`next-intl`: `apps/oshun/web/package.json` depends on `next-intl` (a `catalog:`
ref), `apps/oshun/web/src/i18n/request.ts` is the `getRequestConfig` provider,
and `apps/oshun/web/src/i18n/config.ts` derives its `locales`, `localeLabels`,
and `rtlLocales` directly from the `@oshun/i18n` exports
(`OSHUN_LAUNCH_LANGUAGE_PREFERENCES`, `LANGUAGE_PREFERENCE_LABELS`,
`RTL_LOCALES`, `languagePreferenceToLaunchLocale`). So the architecture is two
layers: `next-intl` handles Next.js message loading and routing, and
`@oshun/i18n` is the cross-platform source of truth for the launch locale set,
the customer message catalog, fallback semantics, RTL metadata, and the
expansion budgets that mobile (Expo) and admin reuse.

### Launch locales

`OSHUN_LAUNCH_LOCALES` is a frozen 8-locale set, with `en-US` as
`OSHUN_DEFAULT_LAUNCH_LOCALE`. `ar` and `he` are the right-to-left members in
`RTL_LOCALES`; `localeDirection()` derives `'ltr' | 'rtl'` from that set.

| Locale  | Direction | Expansion budget (× en-US) | V1-32 coverage tier |
| ------- | --------- | -------------------------- | ------------------- |
| `en-US` | ltr       | 1.0                        | launch-quality      |
| `es-US` | ltr       | 1.25                       | launch-quality      |
| `fr-FR` | ltr       | 1.3                        | launch-quality      |
| `de-DE` | ltr       | 1.4 (widest)               | launch-quality      |
| `ar`    | rtl       | 1.2                        | minimum-viable      |
| `he`    | rtl       | 1.15                       | minimum-viable      |
| `ja-JP` | ltr       | 0.7 (narrowest)            | launch-quality      |
| `pt-BR` | ltr       | 1.3                        | launch-quality      |

`LOCALE_EXPANSION_BUDGET` is the contract layout QA enforces: a German string
may render up to 1.4× the `en-US` baseline length and must still fit the same
shell without truncating, wrapping into a new line, or breaking grid columns.
Japanese, by contrast, is expected to be _shorter_ (0.7×). The coverage tiers
above are not the same as the budget — they come from
`OSHUN_V1_32_LOCALE_COVERAGE` in the v1-32 manifest, which records, per locale,
the `customerCoverage` and `adminCoverage` surface lists and the launch tier.
Note an honest nuance: `LOCALE_CALENDAR` pins every launch locale (including
`ja-JP`) to the `gregory` calendar in the Oshun shells; the Japanese imperial
calendar is reserved for specific cultural surfaces that opt in per piece of
content.

### The customer message catalog

`CUSTOMER_MESSAGES` is the translation catalog, keyed by message key first and
locale second so per-key audits ("which locales does this key cover, where is
fallback firing") are trivial. It contains roughly 29 `CustomerMessageKey`
entries, and every key carries a real human translation in all 8 launch locales
— for example `shell.nav.home`, `assistant.disclosure.ai`,
`evidence.provenance.open`, `evidence.confidence.low`, `offline.write.deferred`,
`auth.minimum_version_required`, and `privacy.dsar_received`. These are not
placeholders: `assistant.disclosure.ai` in German reads "KI-unterstützte
Oshun-Antwort. Prüfen Sie verlinkte Quellen für wichtige Entscheidungen." and in
Arabic carries the full RTL string. The set spans the shell, assistant
disclosures and memory toggles, evidence/provenance affordances, offline state,
error and status banners, auth, and privacy — the small high-traffic surface
that must never fall back silently.

### Fallback chain and critical-message detection

`resolveFallbackChain(locale)` returns the ordered candidate list
`requested → language-only → en-US`. `es-US` resolves to
`['es-US', 'es', 'en-US']`; `ar` to `['ar', 'en-US']`; `en-US` short-circuits to
`['en-US']`. `translate(key, locale, options)` walks that chain and returns a
`TranslationResult` of `{ value, resolvedLocale, fallbackApplied }`, so a
call-site can detect when it received a fallback without changing shape. When a
fallback fires, `translate` emits a `TranslationFallbackEvent` through the
optional `onFallback` callback, carrying the `key`, `requestedLocale`,
`resolvedLocale`, `fallbackChain`, `surface`, and a `critical` flag. The
`critical` flag defaults to `isCriticalMessageKey(key)`, which is `true` for any
key under the prefixes `assistant.disclosure.`, `evidence.`,
`auth.minimum_version_required`, or `privacy.` — exactly the strings where a
silent English fallback in a localized session would be a trust or safety
problem. This turns "translation gap" into an observable telemetry event rather
than a silent regression.

`findFallbackGaps()` is the launch-blocking audit helper: it walks every key ×
every launch locale through `translate` and returns the `<key, locale>` pairs
that resolved via fallback rather than a direct hit. A non-empty result means a
real translation gap remains. The catalog test
(`libs/oshun/i18n/src/index.test.ts`, locked by `V1-I18N-010`) asserts that
`findFallbackGaps()` returns empty — i.e. every key covers every locale —
alongside direction metadata, expansion budgets, and formatting.

### Locale-aware formatting

`formatForLocale(input: FormatInput)` is the single place where locale-aware
date/time/timezone, number, currency, and region formatting is centralized. It
composes `Intl.DateTimeFormat` (medium date, short time, combined date-time, and
a long timezone name resolved via `formatToParts`), `Intl.NumberFormat` for both
currency (`style: 'currency'`) and plain number formatting, `Intl.DisplayNames`
for the region label, and a closed-over `Intl.RelativeTimeFormat` exposed as the
`relativeTime(value, unit)` function on the returned `FormatOutput`. The input
carries an explicit `timezone`, `currency`, and `regionCode` so formatting is
never inferred from a server default. This backs the `V1-I18N-003` and
`V1-I18N-004` launch-readiness entries.

The localization workflow (glossary ownership, translation review sign-off,
localization provenance, and the steps to add a new launch locale) is documented
in `docs/launch/translation-workflow.md` (`V1-I18N-005`), and the locale
architecture overview lives in `docs/launch/locale-coverage.md`
(`V1-I18N-001/008/009`). For how the localization layer interacts with content
taxonomy and versioning, see
[Taxonomy, Localization, and Versioning](./taxonomy-localization-versioning.md).

## Design tokens and the experience-quality surface

The visual foundation is `libs/oshun/design-tokens/src/tokens.ts`, the single
source of truth for color, spacing, type, motion, and elevation. It is worth
correcting a long-standing documentation inversion here, because the readiness
layer depends on naming the canonical surface accurately.

The **canonical** Oshun token color system is a cool, dark blue/teal-plus-gold
palette, not "cream-paper + terracotta." The canonical scales are `ink` and
`fog` (neutrals), `aqua` and `amber` (brand), and `success` and `danger`
(status), with anchor values such as `ink[950] = '#040B16'`,
`aqua[500] = '#20C9D8'`, and `amber[600] = '#DD8618'`. The default theme
exported in code is `defaultOshunTheme = oshunThemes.dark` — a dark theme, which
the high-level design narrative does not mention. The foundation bundle is
identified by `OSHUN_V1_FOUNDATION_TOKEN_BUNDLE_ID = 'oshun-v1-foundation'` at
`OSHUN_V1_FOUNDATION_TOKEN_BUNDLE_VERSION = '1.0.0'`.

The "cream-paper-and-ink" manuscript palette with terracotta domain hues lives
in the **Lilith register** — the `color.domain.*` block of `oshunTokenSchema`
(around line 1103). That block's own comment describes domain accents "mapped
into the Lilith register … from the manuscript palette … so the sidebar reads as
the same cream-paper-and-ink language." Those domain hues are `tara: '#5A7A3F'`
(Lilith green), `veritas: '#9A3E1C'` (burnt rust), `nyx: '#3B3325'`,
`arete: '#3F5E2B'`, `nisaba: '#C89657'` (honey), and `metis: '#6B5A44'`. So the
relationship the docs sometimes state backwards is: the cool dark ink/aqua
system is the canonical surface; cream-paper + terracotta is the Lilith register
applied at the persona-policy boundary, not the default skin. The persona-policy
mechanics are covered in [Lilith Persona Policy](./lilith-persona-policy.md).

Beyond color, the token module also exports `oshunSpacingScale`,
`oshunFontWeights`, `oshunTypographyRamp`, `oshunMotionDurationScale`,
`oshunMotionTokens`, `oshunElevationTokens`, `oshunDomainAccents`, and a set of
behavior contracts — `oshunDomainAccentBehavior`,
`oshunGroundedEvidenceUiBehavior`, `oshunDisclosureUiBehavior`,
`oshunAssistantPersonaSwitchingUiBehavior`, and `oshunTrustSignalUiBehavior` —
that encode _how_ trust, disclosure, and persona-switch affordances must behave,
not just how they look. Theme resolution helpers (`getThemeByName`,
`getSemanticTokens`, `createCssVariables`) and the high-contrast variants
(`highContrastLight`, `highContrastDark`) round out the set.

### The component library and design-language audits

`libs/oshun/ui` is the shipped component library; its `src/index.ts` re-exports
`components`, `motion`, and `theme`. The components directory contains 21 real
`.tsx` components — `ActionSheet`, `Badge`, `Banner`, `BottomNav`,
`BottomSheet`, `Box`, `Button`, `Card`, `Chip`, `CommandPalette`,
`DomainSwitcher`, `EmptyState`, `ErrorState`, `IconButton`, `ListRow`, `Modal`,
`Stack`, `StatTile`, `Text`, `Toast`, and `TopBar` — grouped into primitives,
data-display, feedback, navigation, and overlays, each with a `.stories.tsx` and
a `.test.tsx`, plus a cross-cutting `accessibility-snapshots.test.tsx`.

`libs/oshun/design-language` ships the audit modules that police the component
surface against the design contract. `component-catalog.ts` exports
`OSHUN_COMPONENT_CATALOG_VERSION = 'component-catalog-v1'`, the
`OSHUN_COMPONENT_CATALOG` itself, and `OSHUN_REQUIRED_COMPONENT_REQUIREMENTS`
with a coverage function that asserts every required capability is met by a
cataloged component. Siblings cover the rest of the experience-quality bar —
`scorecards.ts`, `ergonomics.ts`, `responsive-system.ts`, `surface-language.ts`,
`voice-and-tone.ts`, `ai-disclosure-copy.ts`, `failure-copy.ts`, `visual-qa.ts`,
and `completion-audit.ts` — each with a matching `.test.ts`. None of these are
named in the architecture narrative, but they are the mechanism that keeps the
shipped UI honest against the design language. See
[Design System and Experience Quality](./design-system.md) for the full
treatment.

### Performance budgets

Front-end performance is gated by `apps/oshun/web/lighthouse-budget.json`, a
per-route budget file. For the root route the timing budgets are
first-contentful-paint 1800ms, largest-contentful-paint 2500ms,
`max-potential-fid` 200ms, cumulative-layout-shift 0.1, total-blocking-time
250ms, and speed-index 3000ms, with resource budgets of 450KB total and 400KB
script (tighter on `/search` and `/domains/nisaba`). One precise correction for
the architecture wording: the responsiveness budget the file actually encodes is
`max-potential-fid: 200` (first input delay, the older proxy), not `INP`.
Lighthouse's `budgets.json` schema has no INP timing metric; "INP ≤ 200ms" is
the conceptual responsiveness target, but the enforced key is the FID proxy. LCP
(2.5s) and CLS (0.1) match the stated targets exactly.

Observability under the hood is real, too: `@oshun/logging` is built on Pino
(`pino ^8.18.0`) with middleware, sampling, and transports, and `@oshun/metrics`
wraps `prom-client` through its `registry.ts`/`server.ts`. The adversarial
stub-indicator scan referenced by the architecture quality gates is the actual
script `scripts/stub-indicator-scan.sh`.

## Analytics taxonomies and the evaluation pipeline

The analytics package (`libs/oshun/analytics`) is far richer than a generic
"customer event taxonomy" line implies. Its `src/index.ts` re-exports roughly 37
V1 modules — the customer/admin/assistant/flows/release taxonomies, the
experimentation and evaluation manifests, the tracing/alerts/incident-ownership
manifests, the QA coverage matrices and governance/enforcement module, the
web-Playwright and mobile-e2e CI-coverage manifests, the
accessibility-and-lighthouse CI coverage, and the V1 sign-off manifests
(`v1-31-testing-qa-signoff`, `v1-launch-readiness-manifest`,
`v1-security-readiness-manifest`, `v1-release-and-exit-criteria-manifest`). The
same package also carries a large block of V3-era budget manifests
(`v3-ue-desktop/mobile/vr-fps-budget`, `v3-pixel-streaming-rtt-budget`,
`v3-voice-latency-budget`, `v3-cold-join-budget`, `v3-music-sync-drift-budget`,
and more); these are present in the package even though they are out of V1
design-system scope, and are noted here only so the inventory is honest.

### Customer event taxonomy

`libs/oshun/analytics/src/customer-taxonomy.ts` is the source of truth for every
analytics event a customer surface may emit in V1. It defines 18 event families
(`OSHUN_V1_CUSTOMER_EVENT_FAMILIES`: lifecycle, auth, onboarding, profile,
navigation, continuity, engagement, value_action, search, recommendation,
notification, study, performance, error, privacy, commerce, accessibility,
preferences), 7 namespaces (`OSHUN_V1_CUSTOMER_EVENT_NAMESPACES`: oshun, tara,
veritas, nyx, arete, nisaba, metis), and the concrete surface enum
`OSHUN_V1_CUSTOMER_SURFACES` (web/mobile/PWA shells and their tabs, deep-link,
notification handler, background, and domain apps). Every event is a fully
specified `CustomerEventDefinition` in `OSHUN_V1_CUSTOMER_EVENT_TAXONOMY` — for
example `oshun.app.opened` declares `family: 'lifecycle'`, `kpi: true`,
`consentRequired: false`, typed `properties` (an `entry` enum of `cold | warm`,
a high-cardinality `startup_ms`, and more), an `implementationStatus`, and a
`payloadKey` linking it to the typed payload map.

Two migration affordances matter for launch. First, each definition can carry
`legacyNames` (e.g. `oshun.app.opened` lists
`['shell_opened', 'oshun.app_opened']`), and
`resolveLegacyEventName(legacyName)` maps an old snake_case name to the
canonical `<namespace>.<entity>.<action>` name so adapters migrate cleanly.
Second, `OSHUN_V1_CANONICAL_KPI_EVENT_NAMES` pins the nine launch KPI events —
`oshun.app.opened`, `oshun.auth.completed`, `oshun.profile.initialized`,
`oshun.domain.launched`, `oshun.value_action.completed`, `oshun.item.saved`,
`oshun.item.resumed`, `oshun.search.executed`, `oshun.notification.opened` — so
launch dashboards lock against the taxonomy rather than against ad-hoc strings.
The detailed discovery/recommendation behavior these events feed is described in
[Search, Discovery, Recommendations, and Knowledge Graph](./search-discovery-recommendations.md).

### Evaluation pipeline manifest

`libs/oshun/analytics/src/evaluation-manifest.ts` is the canonical evaluation
contract. It declares 12 `OSHUN_V1_EVALUATION_SCOPES` — `grounded_answers`,
`citation_integrity`, `assistant_quality`, `assistant_safety`, `search_quality`,
`recommendation_quality`, `persona_quality`, `voice_quality`, `avatar_quality`,
`metis_pedagogy`, `generation_quality`, and `generated_artifact_quality` — and a
7-stage pipeline in `OSHUN_V1_EVALUATION_PIPELINE_STAGES`:
`select_dataset → run_inference → apply_metrics → compare_to_baseline → check_thresholds → publish_summary → attach_to_release_readiness`.
The final stage is the one that makes evaluation operationally load-bearing:
results are attached to the corresponding release-readiness record so they
appear in admin readiness views.

Each scope is backed by a registered `OSHUN_V1_BENCHMARK_DATASETS` entry (with
an owner team, a `minSampleSize`, and a `refreshCadence`), a set of
`OSHUN_V1_PROMOTION_THRESHOLDS`, and a set of
`OSHUN_V1_REGRESSION_BLOCKING_RULES`. The thresholds and rules carry real,
domain-specific numbers, not round placeholders:

| Scope                      | Promotion threshold (example)                                 | Regression rule (example)                                     |
| -------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------- |
| grounded_answers           | `exact_match_rate ≥ 0.7`, `mean_confidence ≥ 0.6`             | block if exact-match drops > 2 pts (blocks merge + promotion) |
| citation_integrity         | `stance_accuracy ≥ 0.85`, `broken_link_rate ≤ 0.005`          | block if stance accuracy drops > 1 pt                         |
| assistant_safety           | `refusal_correctness ≥ 0.95`, `unsafe_pass_rate ≤ 0.001`      | block on any measurable rise in unsafe-pass rate              |
| search_quality             | `ndcg_at_10 ≥ 0.82`, `zero_result_false_positive_rate ≤ 0.01` | block if nDCG@10 drops > 2 pts                                |
| voice_quality              | `mos_estimate ≥ 4.0`                                          | block promotion if MOS regresses ≥ 0.05 (promotion only)      |
| avatar_quality             | `psnr ≥ 32.5`                                                 | block promotion if PSNR regresses ≥ 1 dB (promotion only)     |
| generation_quality         | `fid_score ≤ 30`                                              | block promotion if FID worsens ≥ 5 (promotion only)           |
| generated_artifact_quality | `package_completeness ≥ 0.99`, `provenance_integrity ≥ 0.995` | block on measurable provenance/watermark regression           |

The runtime evaluator `evaluateScopeRun()` resolves the dataset, applies each
threshold and regression check, and returns an `EvaluationRunSummary` with a
three-state `gateStatus` (`pass | fail | needs_data`). Crucially, missing
baseline data yields `needs_data` and is treated as blocking promotion rather
than silently passing — a fail-loud default.
`buildEvaluationAdminReadinessSummary()` rolls multiple runs into an
admin-facing readiness record. Some rules block merge _and_ production promotion
(grounding, citation, safety, assistant quality, search, recommendation,
persona, Metis pedagogy, generated-artifact provenance), while
perceptual-quality rules (voice MOS, avatar PSNR, generation FID) block
production promotion only. The experimentation side
(`experimentation-manifest.ts`) defines `ExperimentDefinition` with arms,
`successMetrics`, `guardrails`, and an `allocationStrategy`. How this gates
generated content is detailed in
[Isis Generation Control](./isis-generation-control.md); how it gates the
assistant is in [Assistant Experience](./assistant-experience.md).

## Documentation, runbooks, and training

The documentation corpus required for launch is enumerated in two places that
agree by construction. `OSHUN_V1_32_DOCUMENTATION_ARTIFACTS` lists the
architecture, consumer-IA, admin-IA, data-model, testing-strategy,
evaluation-pipeline, release-gate, and launch-readiness docs with concrete paths
(for example
`docs/adr/ADR-0007-oshun-shell-architecture-and-domain-adapters.md`,
`docs/oshun/data-model.md`, `docs/testing/automation-matrix.md`,
`docs/launch/go-no-go.md`). The launch-readiness manifest restates the same set
under `V1-DOC-001..007` and adds the operator-enablement layer.

V1 commits to ten on-call runbooks, encoded as `OSHUN_V1_32_RUNBOOKS`. Each is a
`V132RunbookArtifact` with an `id`, `title`, `owner`, `path`, and a fixed
`requiredSections` list — `## Scope`, `## Severity classification`,
`## Detection signals`, `## Communication cadence`, `## Escalation`, and
`## Recovery verification` — so a runbook that omits a required heading fails
the sign-off check:

| Runbook                        | Owner                             | Path                                              |
| ------------------------------ | --------------------------------- | ------------------------------------------------- |
| Shell outage                   | reliability                       | `docs/runbooks/shell-outage.md`                   |
| Grounding failure              | platform_engineering / sophia     | `docs/runbooks/grounding-failure.md`              |
| Assistant failure              | assistant_product                 | `docs/runbooks/assistant-failure.md`              |
| Provider failover              | reliability                       | `docs/runbooks/provider-failover.md`              |
| Moderation surge               | trust_safety                      | `docs/runbooks/moderation-surge.md`               |
| Privacy incident               | compliance + security             | `docs/runbooks/privacy-incident.md`               |
| Model/workflow rollback        | platform_engineering / model-ops  | `docs/runbooks/model-workflow-rollback.md`        |
| Persona rollback               | trust_safety                      | `docs/runbooks/persona-rollback.md`               |
| Provenance failure             | platform_engineering / compliance | `docs/runbooks/provenance-failure.md`             |
| Watermark verification failure | platform_engineering / security   | `docs/runbooks/watermark-verification-failure.md` |

Training programs follow the same pattern in `OSHUN_V1_32_TRAINING_PROGRAMS`:
nine `V132TrainingArtifact` entries (support, moderators, reviewers,
persona-operators, model-operators, privacy-operators, compliance-operators,
product, launch-support), each with a fixed `requiredSections` list that
includes `## Scenario rehearsal`, `## Certification criteria`, and
`## Tabletop drills`. These map to `V1-DOC-017..021` in the launch-readiness
manifest. The point of encoding runbooks and training as manifests with
required-section contracts is that "the runbook exists" can be machine-checked
against "the runbook contains the sections an on-call would actually need."

## Launch readiness: drills, beta, and go/no-go

The launch gate proper is `OSHUN_V1_33_LAUNCH_GATE_SIGNOFF` in
`libs/oshun/analytics/src/v1-33-launch-gate-signoff.ts`, organized into four
sections: `33.1_pre_launch_drills`, `33.2_go_no_go`,
`33.3_critical_journey_verification`, and `33.4_exit_criteria_signoff`. Each
`V133LaunchGateEntry` carries `checklistText`, an `owner`, and a list of
`V133LaunchGateEvidenceRef`s typed by kind (`repo_doc`, `code`, `playwright`,
`mobile_e2e`, `unit_or_integration`, `ci_workflow`), with optional
`assertionIncludes` text that the evidence must contain. For example, the 30-day
internal dogfood drill (owner: Release Captain) cites
`docs/launch/dogfood-drill.md` asserting "30 consecutive calendar days" plus the
three e2e CI workflows; the safety review pass (owner: Security Lead) cites the
security-readiness manifest and the `security-dast.yml` /
`security-deps-and-secrets.yml` workflows.

This is exactly where the candor caveat applies. These entries are real,
drift-failing contracts that _name where the evidence must live_ — the dogfood
drill doc, the joint safety sign-off, the eval thresholds. They are not, by
themselves, proof that the 30-day drill was run, that the pen-test cleared, or
that a human go/no-go board met. The rollout/rollback plans (`V1-RLS-015`) are
codified in `docs/releases/v1/scope/partial-failure-and-degraded-mode-rules.md`
and the per-release rollback specs; the post-deploy synthetic-monitoring and
canary signals (`V1-RLS-036`) are wired through
`.github/workflows/oshun-web-deploy.yml` and the alerts manifest; the
app-security scanning and pentest gate (`V1-RLS-037`) is delegated to the
security-readiness manifest. Whether each of these operational rehearsals has
actually been executed is a process fact this repository's source does not by
itself establish — treat the manifests as the checklist, not the completion
certificate.

The beta and GA criteria live in `OSHUN_V1_RELEASE_AND_EXIT_CRITERIA_MANIFEST`
(`libs/oshun/analytics/src/v1-release-and-exit-criteria-manifest.ts`) under the
`pre_launch_gate` (`V1-RLS-001..018`), `beta_and_ga` (`V1-RLS-019..028`), and
`verification_completion` (`V1-RLS-029..042`) groups. Private-beta success
thresholds and beta metrics (retention, reliability, trust, assistant quality,
disclosure compliance, grounding/citation, moderation/support, provenance) are
each mapped to a concrete dashboard or spec; GA approval (`V1-RLS-028`) is gated
by the `qa-governance-and-enforcement` `V1-QA-058` merge/RC blocker plus the
explicit release-gate definitions, and requires every blocking criterion from
`V1-RLS-001..027` to pass first.

## V1 exit criteria — the end-state contract

"Feature-complete" for V1 is defined as the set of end-state exit criteria
captured verbatim in [../features.md](../features.md) and encoded as the
`customer_product_exit`, `admin_product_exit`, `platform_exit`, `quality_exit`,
and `platform_integration_exit` groups of the release-and-exit manifest
(`V1-EXIT-001..059`). Each entry maps a backlog item to the canonical artifact
that confirms it. The full prose list is reproduced below from the source; the
manifest is the machine-checkable form of the same contract.

Oshun V1 is feature-complete only when:

- Customer web and mobile feel like one coherent product across Tara, Arete,
  Veritas, Nyx, Nisaba, and Metis (`V1-EXIT-001/002`, locked through
  `web-playwright-journey-coverage` and `mobile-e2e-journey-coverage` mapping
  all 16 V1 critical journeys).
- Tara is visibly the product center (`V1-EXIT-003`,
  `home-tara-centering-continuity.spec.ts`).
- Nisaba and Metis are fully integrated, not merely exposed as routes
  (`V1-EXIT-004` cites `libs/oshun/domain-nisaba` plus Playwright/Maestro
  coverage; `V1-EXIT-022/023` cite the Metis gap-analysis report).
- Sophia grounding is visible wherever evidence matters (`V1-EXIT-005`,
  `library-provenance-grounding.spec.ts` plus the assistant Inspect Evidence
  overlay). See [Sophia Grounding](./sophia-grounding.md).
- Cross-domain continuity is useful, credible, and tested (`V1-EXIT-006`,
  `activity-cross-domain-continuity.spec.ts`).
- Admin web and admin mobile can operate all review, safety, support, privacy,
  persona, model, rights, provenance, research-integrity, incident, editorial,
  agentic-AI, tenant, and Metis governance workflows (`V1-EXIT-007/008`, citing
  `apps/oshun/admin` and `apps/oshun/admin-mobile`). See
  [Admin Products — Web and Mobile](./admin-products.md).
- Oshun Studio supports authoring, editorial calendar, asset, taxonomy,
  versioning, localization, collaboration, and customer curation across every
  content domain, with grounded source binding, persona/tone policy, and
  release-gate enforcement.
- Agentic AI Studio agents, multi-agent pipelines, run dashboards, replay,
  budgets, kill switches, capability audits, gold sets, and customer- and
  creator-facing invocation surfaces are operational with governance gates
  enforced and tenant-scoped budgets honored. See
  [Agent Registry, Job Orchestration, and Multi-Agent Plans](./agentic-registry-jobs-plans.md).
- Oshun Tenant Console supports tenant administration, SSO/SCIM/OneRoster
  provisioning, role customization, audit explorer, bulk operations, API keys,
  webhooks, lifecycle communications, help center authoring, and status/banner
  publishing — strictly isolated from operator-only Oshun Admin. See
  [Tenant, Institution, and Operator Toolkit](./tenant-toolkit.md).
- Iris, Psyche, Lilith, Sophia, Isis, and Metis ownership is true in the
  implemented product, not only in docs (`V1-EXIT-010..015`, each citing a real
  Playwright spec). See [Iris Memory and Identity](./iris-memory-identity.md),
  [Psyche Real-Time Runtime](./psyche-realtime-runtime.md), and
  [Lilith Persona Policy](./lilith-persona-policy.md).
- External model sources cannot bypass review, rights, safety, provenance, or
  Isis release gates (`V1-EXIT-015`, ADR-0029 audit/compliance surfaces). See
  [External Model Intelligence and Execution Providers](./external-models-and-execution.md).
- Metis high-stakes outputs emit claim-level evidence and pass grounding,
  pedagogy, safety, rights, academic-integrity, standards, and drift gates
  (`V1-EXIT-026..037`, gated by the evaluation manifest). See
  [Metis — Education and Tutoring](./domain-metis.md).
- Public website, app store listings, deep links, and the public status page are
  ready for launch (`V1-EXIT-058`, `V1-PUB-001..011`).
- Recommendation candidate generation, signal ingestion, offline evaluation, and
  observability are operational (`V1-EXIT-057`,
  `home-mixed-domain-recommendations.spec.ts`).
- Aja embodied-instruction services required by Metis are ready or explicitly
  deferred with approved scope boundaries (`V1-EXIT-059`, confirmed via the
  Metis corrective tickets). (Note: the platform substrates are commonly written
  as Sophia, Iris, Psyche, Lilith, Isis, and **Aje** in the hub; the
  embodied-instruction service for Metis is **Aja** — distinct names, both
  real.)
- All critical customer, creator, admin, tenant-admin, mobile, assistant,
  platform, service, contract, persistence, privacy, safety, grounding,
  recommendation, agentic, editorial, integration, billing, Metis, and release
  workflows have risk-tiered automated verification (`V1-EXIT-016/017/038`,
  governed by `qa-coverage-matrices` + `verification-layer-coverage`).
- Accessibility, performance, security, resilience, observability,
  documentation, training, runbooks, canaries, rollback triggers, and
  post-deploy monitors satisfy the launch gates (`V1-EXIT-018/019/047` and the
  verification-completion group).

`listReleaseExitByMandate(id)` and `listReleaseExitByGroup(group)` are the
helpers admin readiness views use to slice this manifest;
`listLaunchReadinessByCategory`, `listLaunchReadinessByMandate`,
`listPromotionThresholdsByScope`, and `listRegressionBlockingRulesByScope` are
the equivalents for the launch-readiness and evaluation manifests. The security
side of the same contract is detailed in
[Analytics, Observability, Testing, and Security](./analytics-and-testing.md)
and the security-readiness manifest (`V1-SEC-001..025`).

## Honest status summary

- Implemented and tested: the i18n catalog and formatting/fallback API, the
  customer/evaluation/launch/security/exit manifests, the design tokens, the UI
  component library, and the design-language audit modules.
- Encoded as drift-failing contracts but operationally process-gated: the
  pre-launch drills, beta/GA go/no-go, pen-test sign-off, and
  rollback/residency/DSAR/red-team rehearsals. The manifests say what must be
  done and where the evidence lives; they do not assert the rehearsal already
  ran.
- Corrected here against stale narrative: cream-paper + terracotta is the Lilith
  register, not the canonical surface (canonical is the dark `ink`/`fog` +
  `aqua`/`amber` system, `defaultOshunTheme = oshunThemes.dark`); the enforced
  responsiveness budget is `max-potential-fid: 200`, with INP as the conceptual
  target only.

## Related

- [Design System and Experience Quality](./design-system.md)
- [Analytics, Observability, Testing, and Security](./analytics-and-testing.md)
- [Taxonomy, Localization, and Versioning](./taxonomy-localization-versioning.md)
- [Review, Compliance, and Trust & Safety](./review-trust-safety.md)
- [Architecture, Platform Foundations, and Security](./platform-foundations-and-security.md)
- [../features.md](../features.md)