# Subsystem Glossary

This glossary fixes the vocabulary used across the entire V1 feature set. Each
entry names a subsystem and the product responsibility it owns, and — because
the names are also the names of real code — points at the actual library or app
that backs it. It serves anyone reading the domain, substrate, surface, or
governance pages who needs to know exactly what "Sophia" or "Aje" or "Studio"
refers to. The glossary is about **product responsibility and code grounding**,
not architecture internals; the runtime layout lives in
[Architecture, Platform Foundations, and Security](./platform-foundations-and-security.md).

A note on grounding before the entries: every named subsystem below corresponds
to real code verified by reading its `package.json` (for the `@oshun/*` adapter
libs) or its directory layout (for the substrate monorepos). Nothing here is a
fabricated capability. Where the _framing_ has historically over-flattened
reality — most notably by implying all six customer domains launch at parity —
this page is candid and points at the code tiering that is authoritative.

## How to read a substrate name

There is a deliberate two-layer pattern you will see throughout, and it is worth
internalizing once: the **deep substrate** and the **thin adapter** are not the
same package.

- The deep substrates `libs/sophia`, `libs/iris`, `libs/psyche`, `libs/lilith`,
  and `libs/isis` are each a sprawling multi-package monorepo with **no root
  `package.json`** — they are _not_ importable as `@oshun/*` packages. For
  example, `libs/sophia/` contains `agents/`, `citation-analysis/`,
  `citation-graph/`, `credibility/`, `corpus/`, `crawling/`, and many more
  subpackages.
- What V1 actually consumes are the **thin adapter libraries** under
  `libs/oshun/`, named with an `@oshun/<verb>-<substrate>` convention:
  `@oshun/evidence-sophia`, `@oshun/memory-iris`, `@oshun/embodiment-psyche`,
  `@oshun/persona-policy-lilith`, `@oshun/generation-control-isis`. These are
  the V1-consumed implementations.

So when a page says "ground through Sophia," the product-surface code path runs
through `@oshun/evidence-sophia`, which adapts the deep `libs/sophia` substrate.
Keep this in mind for every substrate entry below.

## Customer-facing domains

These are the six domains the customer experience is built from, all registered
in `@oshun/domain-registry` (`libs/oshun/domain-registry`). The canonical id
list is `OSHUN_DOMAIN_IDS = ['tara','veritas','nyx','arete','nisaba','metis']`,
and each domain has a real implementation lib under `libs/oshun/domain-*`.

- **Tara** — Rituals, practices, breathwork, meditation, teachers, and
  contemplative continuity. The experiential and thematic center of V1;
  `OSHUN_SHELL_PRIMARY_DOMAIN` is fixed to `'tara'`. Lib: `@oshun/domain-tara`.
  See [Domain Tara](./domain-tara.md).
- **Arete** — Goals, habits, routines, journaling, reflection, weekly review,
  and humane streak/recovery coaching. Capabilities in the registry: `check-in`,
  `goals`, `habits`, `journal`, `coach`. Lib: `@oshun/domain-arete`. See
  [Domain Arete](./domain-arete.md).
- **Veritas** — Grounded stories, claims, sources, evidence, counterclaims,
  topic hubs, timelines, and explainers. Registry capabilities: `claims`,
  `sources`, `reading-list`, `alerts`. Lib: `@oshun/domain-veritas`. See
  [Domain Veritas](./domain-veritas.md).
- **Nyx** — Sky events, observation windows, awe-and-perspective context, and
  calendar integrations. Registry capabilities: `highlights`, `events`,
  `sky-map`, `observations`. Lib: `@oshun/domain-nyx`. See
  [Domain Nyx](./domain-nyx.md).
- **Nisaba** — Scholarly passages, sources, manuscripts, editions, translations,
  lexicon and morphology, concept graph, notebooks, and study plans. Registry
  capabilities: `library`, `parallel-reader`, `annotations`, `workspace`,
  `research`. Lib: `@oshun/domain-nisaba`. See
  [Domain Nisaba](./domain-nisaba.md).
- **Metis** — Educational substrate for courses, tutoring,
  bring-your-own-material study, assessments, knowledge-graph promotion, and
  standards-based institutional delivery. Registry capabilities: `courses`,
  `assessments`, `tutoring`, `progress`, `creation`. Lib: `@oshun/domain-metis`.
  **Metis is `planned`, not launch-enabled** — see
  [Domain availability is tiered](#domain-availability-is-tiered-not-flat) below
  and [Domain Metis](./domain-metis.md).

### Domain availability is tiered, not flat

The glossary historically implied the six domains are co-equal "first-class
Oshun domains with no tiering." That framing is over-flattened. The code in
`libs/oshun/domain-registry/src/registry.ts` defines a real tiering via the
`DomainAvailability` type — `'active' | 'beta' | 'planned'` — and assigns each
domain a tier:

| Domain  | `availability` | `registry.ts` line | 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**          |

This tiering is load-bearing. `getAvailableDomains()` filters out `planned`
domains:

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

while `getShellNavigationDomains()` returns the full list, so a `planned` domain
stays _visible in navigation_ but is excluded from launch configuration. The
registry test makes the contract explicit: it asserts Metis is absent from
`getAvailableDomains()`, and the test itself is titled "exposes planned Metis in
shell navigation without enabling it for launch configuration"
(`libs/oshun/domain-registry/src/index.test.ts`). Reconciliation note: earlier
prose called Metis "Launch-blocking V1 scope," which contradicts the registry's
`planned` status. The code is authoritative — **Metis is planned and not
launch-enabled.** The accurate summary: the six domains are peers in vocabulary
and navigation; five are peers in launch scope.

## Platform substrates

Six substrates provide the cross-cutting capabilities the domains build on. Each
deep substrate is consumed through a thin `@oshun/*` adapter (see
[How to read a substrate name](#how-to-read-a-substrate-name)).

- **Sophia** — Grounded answers, evidence packs, citation trails,
  retrieval-vs-synthesis labeling, fact-check and contradiction loops, and the
  research/authoring orchestration that backs them. Deep monorepo: `libs/sophia`
  (no root `package.json`). V1 adapter: `@oshun/evidence-sophia`. See
  [Sophia Grounding](./sophia-grounding.md).
- **Iris** — Assistant memory and identity boundaries: profile/session/notebook
  memory, consent records, deletion and export, privacy-aware suppression, and
  policy-controlled admin inspection. Deep monorepo: `libs/iris` (no root
  `package.json`). V1 adapter: `@oshun/memory-iris`. See
  [Iris Memory and Identity](./iris-memory-identity.md).
- **Psyche** — Real-time text, voice, and avatar runtime: session envelope,
  turn-taking, interruption, transcript sync, lip sync, expression coherence,
  and continuity under reconnect. Deep monorepo: `libs/psyche` (no root
  `package.json`). V1 adapter: `@oshun/embodiment-psyche`. See
  [Psyche Real-Time Runtime](./psyche-realtime-runtime.md).
- **Lilith** — Contemplative tone policy, teacher persona safety, crisis-aware
  behavior, voice-quality and voice-abuse policy, and spiritual-domain
  boundaries. Deep monorepo: `libs/lilith` (no root `package.json`). V1 adapter:
  `@oshun/persona-policy-lilith`. See
  [Lilith Persona Policy](./lilith-persona-policy.md).
- **Isis** — Governed generation control plane: workflow templates, model and
  provider registries, environment promotion, provenance bundles, release gates,
  failover, and rollback. Deep monorepo: `libs/isis` (no root `package.json`).
  V1 adapter: `@oshun/generation-control-isis`. See
  [Isis Generation Control](./isis-generation-control.md).
- **Aje** — Library-only blockchain and Web3 payment substrate (named for the
  Yoruba orisha of wealth, commerce, and the marketplace): non-custodial
  settlement, merchant invoices, per-chain providers, and wallet management. Aje
  is a large standalone Web3 monorepo at `libs/aje` with **no root
  `package.json`** and 30+ subdomains — including `chains/`, `contracts/`,
  `payments/`, `settlement-escrow/`, `wallets/`, `defi/`, `nft/`, `zkp/`, and
  `account-abstraction/`. V1 consumes it Oshun-side through
  `@oshun/payments-bridge` (`libs/oshun/payments-bridge`), whose `src/` contains
  `admin-surface/`, `customer-surface/`, `entitlement-bus/`,
  `oracle-aggregator/`, `receipt-signer/`, `security-gates/`, `state-mapper.ts`,
  and `cold-spend-queue/`. See
  [Crypto Payments — Non-Custodial Entitlement Settlement](./crypto-payments.md).

## Cross-domain support (Studio creation substrates and services)

These substrates are referenced where Metis, persona, and content-creation work
interlock. All exist as top-level multi-package monorepos under `libs/`
(`libs/aja`, `libs/yemaya`, `libs/themis`, `libs/bellona`, `libs/hathor`,
`libs/neith`), none with a root `package.json`.

- **Aja** — Embodied-instruction services that Metis hooks into for movement-
  and practice-based pedagogy. The V1 adapter `@oshun/embodiment-aja`
  (`libs/oshun/embodiment-aja`) declares `SUPPORTED_DOMAINS` of `fitness`,
  `yoga`, `dance`, `martial-arts`, `sports`, and `rehabilitation`, and imports
  its contracts from `@oshun/contracts/aja/index.js`. Its consumers are typed as
  `metis`, `assistant`, `studio`, and `admin`.
- **Yemaya** — Rendering substrate for media surfaces consumed by Metis and
  other domains (`libs/yemaya`).
- **Themis** — Academic-integrity adjudication referenced by Metis assessments
  and tutoring (`libs/themis`).
- **Bellona** — Engine-bridge and build substrate for Studio creation: live
  bridges to Unity, Unreal, Godot, Blender, and DaVinci; OpenUSD asset
  interchange; the build/export pipeline; and XR / virtual-production support
  (`libs/bellona`).
- **Hathor** — Narrative, world, and lore-authoring substrate for Studio
  storytelling: characters, factions, locations, timelines, quests, dialogue,
  economy/politics simulation, and lore validation (causality, contradictions,
  timeline, taxonomy) (`libs/hathor`).
- **Neith** — Inverse-modeling substrate: image-to-parameter estimation (feature
  extraction, parameter estimation, confidence scoring) feeding Studio asset and
  motion pipelines (`libs/neith`).

> Bellona, Hathor, and Neith are **Studio-only V1 substrates** — they have no
> dedicated customer-facing surface. Their surfaces are inventoried under
> `WALKTHROUGH/studio/domain-bridges/`. (Historical changelog note now folded
> into current state: they were absent from the early domain lists until the V1
> route scope was reconciled; they are in-scope today.)

## Surfaces

- **Oshun Web** and **Oshun Mobile** — The two customer-facing consumer apps.
  Both render from the same `@oshun/domain-registry` configuration; the web
  app's `apps/oshun/web/src/app/domains/[domainId]/page.tsx` catch-all serves
  the domain shell (including `beta` domains like nisaba and the `planned`
  metis, since shell navigation lists all six). The BFF (`apps/oshun/bff`) backs
  both and mounts a `registerDomainsRoutes` registrar plus per-domain registrars
  such as `registerTaraRoutes`, `registerAreteRoutes`, and
  `registerNisabaRoutes`. The canonical per-domain route prefix is
  `/v1/<domain>/*` — e.g. `/v1/tara/sessions/:sessionId/guidance` in
  `apps/oshun/bff/src/tara/ambient-audio-routes.ts`. (A
  `/api/oshun/domains/veritas/...` path exists only for the Veritas retraction
  cascade in `apps/oshun/bff/src/veritas/retraction-cascade-runtime.ts`; it is
  not the generic per-domain prefix.) See
  [Product Surfaces](./product-surfaces.md).
- **Oshun Admin (Web)** and **Oshun Admin (Mobile)** — Operator products for
  review, safety, support, privacy, persona/model/rights/provenance operations,
  incidents, and launch governance. See [Admin Products](./admin-products.md).
- **Oshun Studio** — Creator, curator, editor, scholar, teacher, and translator
  workspace for content authoring, editorial workflow, asset and taxonomy
  curation, localization, and governed agentic AI invocation. Builds on Sophia,
  Isis, Lilith, and Iris and is consumed by both customer-side creators and
  operator-side editors. See
  [Creator Roles and the Authoring Workspace](./authoring-workspace-and-roles.md).
- **Oshun Tenant Console** — Tenant-scoped admin shell for institutions,
  schools, research labs, partner organizations, and managed cohorts: members,
  roles, content scopes, identity/SSO/SCIM, audit, integrations, and lifecycle
  communications. Strictly isolated from operator-only Oshun Admin. See
  [Tenant, Institution, and Operator Toolkit](./tenant-toolkit.md).
- **Public Web and Distribution** — Marketing site, app-store listings, deep
  links, public status page, and the public-to-app conversion surface.

### Metis is the only domain with its own dedicated app and service stack

A surface-layer detail worth recording because it is easy to miss: Metis is the
single V1 domain that carries its own application stack beneath `apps/metis/`.
That directory contains **five** entries — `admin`, `api-gateway`, `mobile`,
`web`, and `worker` — and the `mobile` app is real even though it is sometimes
omitted from surface enumerations. On the library side, `libs/metis/` is its own
package family (`adaptive`, `assessment`, `course`, `gradebook`,
`knowledge-graph`, `llm-client`, an `api-client` subpackage, and more). This
rich infrastructure coexists with the `planned` launch tier: Metis is _built
out_ but _not customer-launched_ in V1.

## Localization vocabulary

Launch locales are a fixed, code-defined set, not an open-ended list. From
`libs/oshun/i18n/src/index.ts`, `OSHUN_LAUNCH_LOCALES` is the 8-locale array
`['en-US','es-US','fr-FR','de-DE','ar','he','ja-JP','pt-BR']`, with
`OSHUN_DEFAULT_LAUNCH_LOCALE = 'en-US'`. Two of the locales are right-to-left
(`ar`, `he`), which is why bidirectional layout is a launch concern rather than
a later enhancement. See
[Taxonomy, Localization, and Versioning](./taxonomy-localization-versioning.md).

## Cross-reference convention

A bare `§N` / `§N.M` resolves to a numbered section of the V1 backlog
[`../TODOS.md`](../TODOS.md); `deps§N` resolves to a section of
[`../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 and symbols are shown in
backticks.

## Related

- [V1 Product Promise](./product-promise.md) — the commitments this vocabulary
  is stated in
- [Product Surfaces](./product-surfaces.md) — the surfaces enumerated above, in
  depth
- [Domain Metis — Education and Tutoring](./domain-metis.md) — the `planned`
  domain and its dedicated app/service stack
- [Sophia Grounding](./sophia-grounding.md),
  [Iris Memory and Identity](./iris-memory-identity.md),
  [Psyche Real-Time Runtime](./psyche-realtime-runtime.md),
  [Lilith Persona Policy](./lilith-persona-policy.md),
  [Isis Generation Control](./isis-generation-control.md),
  [Crypto Payments](./crypto-payments.md) — the six platform substrates
- [Taxonomy, Localization, and Versioning](./taxonomy-localization-versioning.md)
  — the launch-locale set
- [Architecture, Platform Foundations, and Security](./platform-foundations-and-security.md)
  — the runtime and package layout
- [`../features.md`](../features.md) — feature hub