# V1 Product Promise

The Product Promise is the contract V1 makes with everyone who builds it,
operates it, or uses it: that Oshun ships as **one coherent product** — a single
shell with continuous identity, memory, and trust signals across web, mobile,
assistant, and notifications — rather than a directory of disconnected domain
apps stitched together at launch. It is the north star that the domain pages,
the platform-substrate pages, and the [Subsystem Glossary](./glossary.md) all
serve. This page expands the promise into testable commitments, names the real
code that already encodes (or contradicts) each one, and is candid about where
the promise is aspirational rather than shipped.

This page is a product-shaped reading of the V1 execution backlog. The backlog
checklist at [`../TODOS.md`](../TODOS.md) remains the source of truth for
completion state; the promise below describes _what good looks like_, not what
is done. The companion
[Architecture, Platform Foundations, and Security](./platform-foundations-and-security.md)
page describes the runtime that has to carry it.

## The promise, restated

Oshun V1 must ship as a coherent product rather than a set of disconnected
domain apps. Concretely, the product should:

- **Present Tara as the experiential and thematic center** of the customer
  product. This is not marketing framing — it is encoded:
  `OSHUN_SHELL_PRIMARY_DOMAIN` is the literal value `'tara'` in
  `libs/oshun/domain-registry/src/registry.ts`, and Tara's registry summary
  calls it "the experiential spine of OSHUN, keeping presence, ritual, and
  return at the center before any other handoff."
- **Treat Arete, Veritas, Nyx, Nisaba, and Metis as Oshun domains** that share
  the same shell, the same memory, and the same trust surfaces — not as silos.
  (See
  [Domains are peers in vocabulary, not in launch tier](#domains-are-peers-in-vocabulary-not-in-launch-tier)
  for the important honesty caveat: they are peers in _naming and navigation_,
  but the code tiers them by readiness.)
- **Preserve continuity** across web, mobile, assistant, notifications, library,
  profile, and activity history, so a session begun on one surface is legible on
  every other.
- **Ground claims and high-stakes outputs through Sophia** — every educational,
  research, and evidence-sensitive answer must be retrieval-anchored and
  citation-bearing rather than free-form synthesis. See
  [Sophia Grounding](./sophia-grounding.md).
- **Make memory, consent, provenance, synthetic media, and grounding state
  visible** wherever they affect user trust, never hidden behind a frictionless
  veneer. See [Iris Memory and Identity](./iris-memory-identity.md) and
  [Privacy, Consent, Data Portability, and User Controls](./privacy-consent-portability.md).
- **Provide operator-grade admin tooling for every launch-critical governance
  workflow** — review, safety, support, privacy, research integrity, persona,
  model, rights, provenance, incidents, and launch readiness. See
  [Admin Products — Web and Mobile](./admin-products.md) and
  [Review, Compliance, and Trust & Safety](./review-trust-safety.md).
- **Provide first-class authoring, curation, editorial, asset, taxonomy,
  versioning, and localization tooling** for creators, scholars, teachers,
  translators, and operators across every content domain. See
  [Creator Roles and the Authoring Workspace](./authoring-workspace-and-roles.md).
- **Provide first-class agentic AI surfaces** for content development, research,
  tutoring, education, and operations, with full registry, orchestration,
  budget, kill-switch, audit, and feedback machinery. See
  [Agent Registry, Job Orchestration, and Multi-Agent Plans](./agentic-registry-jobs-plans.md).
- **Treat institutions, schools, research labs, partner organizations, and
  managed cohorts as first-class tenants** with isolated admin, identity
  provisioning, audit, integrations, and lifecycle communications. See
  [Tenant, Institution, and Operator Toolkit](./tenant-toolkit.md).
- **Support premium personas, voices, avatars, generated media, and educational
  assets only through governed approval paths** — never an ungoverned generation
  free-for-all. See [Isis Generation Control](./isis-generation-control.md).
- **Degrade safely** under subsystem outages, weak grounding, partial responses,
  provider failures, offline states, and interrupted sessions — failure is a
  first-class design surface, not an afterthought.
- **Launch only with automated verification, observability, runbooks, release
  gates, rollback plans, and post-deploy monitoring in place.** See
  [Content, Localization, Documentation, Launch, and Exit Criteria](./content-localization-launch-exit.md)
  and the V1 Exit Criteria section of [`../TODOS.md`](../TODOS.md).

## How the promise maps to code today

The point of a product promise is to be checkable. Each commitment below is
anchored to a real symbol, path, or constant so a reviewer can confirm it
without trusting the prose.

| Promise                            | Where it is encoded                                                                                                            | Status in code                                                               |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Tara is the center                 | `OSHUN_SHELL_PRIMARY_DOMAIN = 'tara'` in `libs/oshun/domain-registry/src/registry.ts`                                          | Encoded — shell primary domain is fixed to Tara                              |
| Domains share one shell            | `getShellNavigationDomains()` returns every domain in `OSHUN_DOMAIN_IDS` (`['tara','veritas','nyx','arete','nisaba','metis']`) | Encoded — all six are navigable                                              |
| Launch scope is gated by readiness | `getAvailableDomains()` filters `availability !== 'planned'`                                                                   | Encoded — Metis (`planned`) is excluded from launch config                   |
| Grounding through Sophia           | `@oshun/evidence-sophia` adapter under `libs/oshun/`                                                                           | Adapter present; see [Sophia Grounding](./sophia-grounding.md)               |
| Memory/consent visible             | `@oshun/memory-iris` adapter under `libs/oshun/`                                                                               | Adapter present; see [Iris Memory and Identity](./iris-memory-identity.md)   |
| Governed generation only           | `@oshun/generation-control-isis` adapter under `libs/oshun/`                                                                   | Adapter present; see [Isis Generation Control](./isis-generation-control.md) |
| Governed payment settlement        | `@oshun/payments-bridge` over the `libs/aje` Web3 monorepo                                                                     | Adapter present; see [Crypto Payments](./crypto-payments.md)                 |
| Per-domain customer routes         | BFF mounts `/v1/<domain>/*` (e.g. `/v1/tara/sessions/:sessionId/guidance`)                                                     | Live in `apps/oshun/bff/`                                                    |
| Multi-locale launch                | `OSHUN_LAUNCH_LOCALES` (8 locales) in `libs/oshun/i18n/src/index.ts`                                                           | Encoded — `en-US`, `es-US`, `fr-FR`, `de-DE`, `ar`, `he`, `ja-JP`, `pt-BR`   |

## Domains are peers in vocabulary, not in launch tier

The most important honesty caveat in this promise: the prose historically said
V1 treats all six domains as "co-equal first-class Oshun domains with no
tiering." **That is not what the code does, and the docs are being reconciled to
match reality.** `libs/oshun/domain-registry/src/registry.ts` defines a
three-value `DomainAvailability` type — `'active' | 'beta' | 'planned'` — and
assigns each domain a real tier:

| Domain  | `availability` | Source line (`registry.ts`) | Launch-enabled? |
| ------- | -------------- | --------------------------- | --------------- |
| Tara    | `active`       | 166                         | Yes             |
| Veritas | `active`       | 225                         | Yes             |
| Arete   | `active`       | 355                         | Yes             |
| Nyx     | `beta`         | 290                         | Yes (beta)      |
| Nisaba  | `beta`         | 420                         | Yes (beta)      |
| Metis   | `planned`      | 489                         | **No**          |

The selection logic makes the tiering load-bearing rather than decorative:

```ts
// libs/oshun/domain-registry/src/registry.ts
export function getAvailableDomains(): DomainMetadata[] {
  return listDomainMetadata().filter(
    (domain) => domain.availability !== 'planned'
  );
}
```

`getAvailableDomains()` is what launch domain configuration is built from, so a
`planned` domain is _visible in shell navigation_ (via
`getShellNavigationDomains()`, which returns the full list) but is **not enabled
for launch**. The registry's own test fixes this contract precisely: one case
asserts `getAvailableDomains()` excludes Metis
(`available.some((item) => item.id === 'metis')` is `false`), and a second is
titled "exposes planned Metis in shell navigation without enabling it for launch
configuration" (`libs/oshun/domain-registry/src/index.test.ts`).

So the accurate statement of the promise is: **all six domains are first-class
in vocabulary, shell navigation, and memory/identity continuity; five are
first-class in launch scope.** Metis is the one domain whose customer launch is
deferred. This directly resolves a contradiction the earlier docs carried — the
[Subsystem Glossary](./glossary.md) labeled Metis "Launch-blocking V1 scope,"
while the registry marks it `planned` and excludes it from launch. The code is
authoritative: Metis is **planned, not launch-blocking**. Its infrastructure
(the `apps/metis/` microservice stack and the `libs/metis/` package family) is
real and developed, but its _customer-facing launch_ is held back behind the
`planned` gate. See [Metis — Education and Tutoring](./domain-metis.md) for the
full picture.

## Why coherence is engineered, not asserted

Coherence is a structural property of how the codebase is laid out, not a
promise that has to be kept by convention:

- **One registry, one vocabulary.** `@oshun/domain-registry` is the single
  source of domain identity — `OshunDomainId`, display names, routes,
  capabilities, availability, and launch targets all live in one place, so the
  shell, the BFF, the assistant, and notifications cannot drift apart on what a
  domain _is_.
- **Thin adapters over deep substrates.** The six platform substrates are not
  monolithic packages — `libs/sophia`, `libs/iris`, `libs/psyche`,
  `libs/lilith`, and `libs/isis` are each sprawling multi-package monorepos with
  **no root `package.json`** (they are not importable `@oshun/*` packages). V1
  consumes them through deliberately thin adapter libraries —
  `@oshun/evidence-sophia`, `@oshun/memory-iris`, `@oshun/embodiment-psyche`,
  `@oshun/persona-policy-lilith`, `@oshun/generation-control-isis` — all under
  `libs/oshun/`. The promise of "ground through Sophia" is kept by an adapter
  boundary, which is what lets the substrate evolve without breaking the product
  surface.
- **Continuity is a shared shell, not a shared codebase per surface.** Web and
  mobile both render from the same domain configuration, the same primary-domain
  rule, and the same memory/consent contracts, which is what makes cross-surface
  continuity a guarantee rather than a hope.

## Degrade-safely and launch-readiness are part of the promise

Two commitments are easy to under-weight because they describe the unhappy path,
but they are explicit in the promise and are treated as features, not caveats:

- **Safe degradation.** Weak grounding, provider failures, partial responses,
  offline states, and interrupted sessions must each have a defined, legible
  fallback — for example, grounding-state visibility (the Sophia commitment)
  exists precisely so that a _degraded_ grounded answer is shown as degraded
  rather than passed off as authoritative. The substrate-adapter boundary is
  also a degradation boundary: a substrate outage surfaces as an adapter-level
  failure the product can render honestly.
- **Launch only behind verification.** "Launch only with automated verification,
  observability, runbooks, release gates, rollback plans, and post-deploy
  monitoring in place" is the gate that the `planned`/`beta`/`active` tiering
  exists to enforce. A domain does not graduate to launch by assertion; it
  graduates by moving its registry `availability` value, which is test-guarded.

## Cross-reference convention

Cross-references on this page follow the repository-wide convention: a bare `§N`
or `§N.M` points at a numbered section of the V1 backlog
[`../TODOS.md`](../TODOS.md); `deps§N` points at
[`../DEPENDENCIES.md`](../DEPENDENCIES.md); sibling feature pages are linked as
`[Title](./<slug>.md)`; companion architecture pages as
`[Title](../architecture/<slug>.md)`; and the feature hub is
[`../features.md`](../features.md). Real code paths are shown in backticks.

## Related

- [Subsystem Glossary](./glossary.md) — the vocabulary every promise above is
  stated in
- [Domain Metis — Education and Tutoring](./domain-metis.md) — the one `planned`
  domain, and why its launch is deferred
- [Domain Tara — Rituals and Contemplative Practice](./domain-tara.md) — the
  experiential center the promise names first
- [Sophia Grounding](./sophia-grounding.md),
  [Iris Memory and Identity](./iris-memory-identity.md),
  [Isis Generation Control](./isis-generation-control.md) — the trust-bearing
  substrates the promise commits to
- [Content, Localization, Documentation, Launch, and Exit Criteria](./content-localization-launch-exit.md)
  — the launch-readiness gate
- [Architecture, Platform Foundations, and Security](./platform-foundations-and-security.md)
  — the runtime that carries the promise
- [`../features.md`](../features.md) — feature hub