# ADR-0066: OSHUN Disclosure And Synthetic Indicator UI Behavior

- Status: Accepted
- Date: 2026-03-24

## Context

OSHUN already had roadmap and PRD requirements around explicit AI identity,
memory-state visibility, disclosure overlays, and synthetic voice/avatar
signaling, but the visual behavior was not yet governed by one shared contract:

- the global assistant shell did not expose a persistent disclosure grammar for
  AI identity and memory scope
- synthetic voice and avatar surfaces had no shared shell-level indicator model
- Studio design-language tooling could inspect core foundation tokens, domain
  accents, and grounded evidence behavior, but not disclosure behavior itself

The V1 TODO list explicitly requires the visual rules for disclosure and
synthetic indicators to be defined, and the admin PRD requires users to always
know when they are speaking with AI, what memory is active, and when voice or
avatar output is synthetic.

## Decision

Publish one canonical disclosure-and-synthetic-indicator behavior contract from
`libs/oshun/design-tokens/src/tokens.ts` and make the web shell consume it
through tokenized CSS variables, disclosure helpers, Studio inspection surfaces,
the global assistant shell, and representative avatar/text-to-speech governance
surfaces.

The shell contract is:

1. Explicit identity
   - every assistant or generated experience clearly states that the experience
     is AI-mediated before it can be mistaken for a human interaction

2. Visible memory scope
   - disclosure copy always resolves memory to explicit states such as memory
     off, session memory, or profile memory

3. Synthetic modality signals
   - synthetic voice, avatar, and generated-media states stay visible on the
     active surface rather than living only in settings or documentation

4. Embodied-session escalation
   - voice and avatar sessions escalate from compact chips to persistent
     overlays because mistaken human attribution is a higher-risk failure mode

5. Plain-language companion copy
   - compact indicators always pair with short readable text explaining what is
     synthetic and what memory scope is active

## Consequences

- `oshun-v1-foundation` now includes a disclosure behavior contract in addition
  to the existing core, domain-accent, and grounded-evidence contracts.
- `apps/oshun/web/src/design-system/globals-v2.css` now defines shared
  disclosure tones, indicator colors, persistent-strip, inline-chip, and
  session-overlay variables.
- `apps/oshun/web/src/design-system/disclosure.ts` now provides the canonical
  web helper layer for disclosure labels, descriptions, and assistant disclosure
  state derivation.
- Studio design-language tooling can now inspect disclosure indicators and role
  rules as first-class governed artifacts.
- The global assistant shell and representative avatar/TTS Studio surfaces now
  consume the same disclosure grammar instead of styling disclosure locally or
  omitting it entirely.

## Implementation

- Shared contract:
  - `libs/oshun/design-tokens/src/tokens.ts`
  - `libs/oshun/design-tokens/src/tokens.test.ts`
- Web adapter and CSS:
  - `apps/oshun/web/src/design-system/tokens.ts`
  - `apps/oshun/web/src/design-system/index.ts`
  - `apps/oshun/web/src/design-system/disclosure.ts`
  - `apps/oshun/web/src/design-system/globals-v2.css`
  - `apps/oshun/web/src/design-system/__tests__/tokens.test.ts`
  - `apps/oshun/web/src/design-system/__tests__/disclosure.test.ts`
- Web disclosure surfaces:
  - `apps/oshun/web/src/components/assistant/AssistantPanel.tsx`
  - `apps/oshun/web/src/components/studio/StudioAjaAvatarPreviewUiWorkspace.tsx`
  - `apps/oshun/web/src/components/studio/StudioIsisTextToSpeechWorkspace.tsx`
- Studio inspection and browser verification:
  - `apps/oshun/web/src/components/studio/StudioDesignLanguageWorkspace.tsx`
  - `apps/oshun/web/src/components/__tests__/StudioDesignLanguageWorkspace.test.tsx`
  - `apps/oshun/web/e2e/studio-design-language-smoke.spec.ts`
  - `apps/oshun/web/e2e/assistant-continuity-journey.spec.ts`
  - `apps/oshun/web/e2e/studio-aja-avatar-preview-ui-smoke.spec.ts`
  - `apps/oshun/web/e2e/studio-isis-text-to-speech-smoke.spec.ts`

## Verification

This slice is complete when:

1. shared design-token tests pass
2. targeted web disclosure, assistant, and Studio tests pass
3. targeted eslint passes for the changed shared, web, and e2e files
4. Playwright verifies Studio disclosure governance plus live
   assistant/avatar/TTS disclosure surfaces