# OSHUN V1 Nisaba Content Tone Standards

Status: Accepted v1.0  
Owner: OSHUN Design + Product + Engineering  
Last Updated: March 26, 2026  
Implements: `V1-UX-038`  
Related:

- `docs/releases/v1/design/ux-principles.md`
- `docs/releases/v1/design/readability-standards.md`
- `docs/releases/v1/scope/immersive-vs-utilitarian-posture-rules.md`
- `docs/releases/v1/scope/scan-first-content-hierarchy-rules.md`
- `docs/releases/v1/specs/web-app-admin-v1-prd.md`
- `docs/adr/ADR-0054-oshun-nisaba-first-class-customer-domain.md`
- `apps/oshun/web/src/components/domains/NisabaSurface.tsx`
- `apps/oshun/web/src/components/library/LibraryDashboard.tsx`
- `apps/oshun/web/src/components/library/ResearchPracticeJourneyRail.tsx`
- `apps/oshun/web/src/components/search/search-config.ts`
- `apps/oshun/mobile/src/assistant/mobile-assistant-model.ts`
- `apps/oshun/mobile/src/safety/guidance.ts`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical content tone for Nisaba scholarly surfaces
in OSHUN V1.

Nisaba is the product's textual depth layer. Its role is to support reading,
comparison, annotation, manuscripts, translations, concept lineage, and source
trails across traditions.

The Nisaba tone standard exists so study surfaces feel:

- scholarly
- quiet
- precise
- contextual
- respectful of complexity

without becoming:

- theatrical
- preachy
- quote-farm inspirational
- jargon-thick
- falsely definitive

## 2. Current Repo Signals And Gap

Current implementation review already shows a recognizable Nisaba voice:

- `NisabaSurface.tsx` uses grounded study framing such as `Nisaba study layer`,
  `Primary texts, commentary, and comparative study`, `Open library`,
  `Compare translations`, `Open notebook`, and
  `Trace how different traditions treat disciplined action`.
- `LibraryDashboard.tsx` and `ResearchPracticeJourneyRail.tsx` already use
  language like `Parallel passage set`, `commentary notes`,
  `compare-mode anchors`, and
  `Grounded study should end in a ritual, a commitment, or a note worth returning to.`
- `search-config.ts` uses scholarly search prompts such as
  `Compare "translation notes"` and `Find "study notebook"`.
- `mobile-assistant-model.ts` frames Nisaba as
  `text-grounded study and comparison`.
- `safety/guidance.ts` already treats Nisaba content with contextual care,
  explicitly warning that study material is not professional advice and that
  difficult passages may need pacing.
- `OSHUN_WEB_APP_ADMIN_V1_PRD.md` defines Nisaba as
  `textual depth, lineage, scholarship, and comparative wisdom`.
- `OSHUN_V1_IMMERSIVE_VS_UTILITARIAN_POSTURE_RULES.md` says Nisaba immersion
  should feel `scholarly and quiet, never theatrical`.

The gap is canonical tone governance. Nisaba has strong local copy patterns, but
no single rule set for how its scholarly voice should handle interpretation,
tradition-specific vocabulary, comparison, caution, and cross-domain handoffs.

## 3. Canonical Tone Thesis

Nisaba should sound like a thoughtful study companion and a careful research
guide.

The canonical Nisaba voice is:

- serious without stiffness
- interpretive without overclaiming
- accessible without oversimplifying
- reverent toward sources without sounding devotional by default
- context-rich without becoming a wall of prose

Nisaba is allowed to feel contemplative.

Nisaba is not allowed to sound like:

- a sermon
- a self-help slogan generator
- a dissertation abstract dropped into product UI
- a mystical oracle claiming the one true reading of a text

## 4. Tone Pillars

### 4.1 Scholarship Over Atmosphere

Nisaba's sense of depth comes from text, lineage, and comparison, not from
dramatic language.

When in doubt, make the copy more exact, not more grand.

### 4.2 Context Matters

Nisaba copy should respect:

- source traditions
- translation differences
- commentary layers
- historical setting
- interpretive limits

The UI should not pretend a passage means the same thing in every setting.

### 4.3 Interpretive Humility

Nisaba can compare, explain, and connect ideas.

It should not imply that one short UI sentence has exhausted the meaning of a
primary text or resolved every interpretive dispute.

### 4.4 Quiet Precision

Nisaba copy should feel studious and concentrated.

This means:

- low hype
- low ornament
- high signal
- calm transitions into deeper reading

### 4.5 Accessible Scholarship

Nisaba should respect serious readers without excluding newer ones.

Specialized terms are acceptable, but first use should usually include enough
plain-language support that the reader is not stranded.

## 5. Language Rules

### 5.1 Sentence Shape

- Headings should usually identify the study object or study action.
- Supporting text should explain why the item matters in one or two sentences.
- Comparative guidance should state the dimension of comparison clearly.
- Long contextual explanation belongs in expandable or dedicated reading space,
  not every card or chip.

### 5.2 Preferred Verbs

Prefer verbs such as:

- read
- compare
- trace
- annotate
- examine
- interpret
- contextualize
- revisit
- translate
- cross-link
- preserve

These verbs fit the real work Nisaba supports.

### 5.3 Reference And Source Language

- Prefer exact references, edition names, and source labels when available.
- Use terms like `passage`, `commentary`, `concept thread`, `edition`,
  `translation`, `notebook`, and `compare workspace` directly.
- When summarizing a text, distinguish the passage from the commentary about the
  passage.

### 5.4 Vocabulary To Use Carefully

Tradition-specific language is allowed when accurate, but it should not be used
as decorative seasoning.

Use specialized terms only when they help the reader understand the source,
concept lineage, or translation issue.

### 5.5 Vocabulary To Avoid

Avoid language such as:

- `ancient secret`
- `timeless hack`
- `the universe is telling you`
- `this quote will change your life`
- `the text clearly proves`
- `the definitive meaning`
- `scholarly masterpiece` as empty praise

Also avoid flattening all traditions into interchangeable inspiration snippets.

## 6. Surface-Specific Tone Rules

### 6.1 Landing And Study-Path Surfaces

Goal:

- orient the reader into a mode of study

Rules:

- Lead with the study object, workspace, or action.
- Use language that signals text depth and continuity.
- Do not market the surface like a lifestyle homepage.
- Make the study path explicit: open passage, compare translation, resume
  notebook, follow concept thread.

### 6.2 Passage And Reading Surfaces

Goal:

- keep the text primary

Rules:

- Passage framing should stay quiet and exact.
- Context should support the reading rather than dominate it.
- Do not bury the reference, source, edition, or translation context.
- Avoid inspirational paraphrase that replaces the actual text.

### 6.3 Comparison And Translation Surfaces

Goal:

- help the reader compare responsibly

Rules:

- Name what is being compared: edition, translation, commentary stance,
  morphology, lineage, or interpretation.
- Use language that invites examination, not winner-picking.
- When differences are meaningful, say that directly.
- Do not imply a single authoritative resolution unless the scholarship truly
  supports it.

### 6.4 Annotation, Highlights, And Notebooks

Goal:

- support durable study continuity

Rules:

- Notebook and annotation copy should be precise and workmanlike.
- Labels such as `Open notebook`, `Resume passage`, and
  `Translation compare workspace` are canonical because they tell the truth.
- Reflection prompts may be present, but they should stay connected to the
  source material rather than drifting into generic journaling language.

### 6.5 Concept Threads And Explanatory Summaries

Goal:

- connect ideas across texts without overclaiming

Rules:

- Concept-thread summaries should explain the comparative thread in plain
  language.
- Use phrasing like `trace how`, `compare how`, or `see how` rather than
  `discover the true meaning`.
- If multiple traditions or commentaries disagree, the copy should make room for
  that difference instead of smoothing it away.

### 6.6 Assistant And Search Support Inside Nisaba

Goal:

- accelerate study without pretending to replace it

Rules:

- Search and assistant prompts should orient toward passages, references,
  notebooks, and concept threads.
- Assistant explanations should cite, compare, and contextualize.
- Do not let the assistant sound like a guru or an unquestionable authority.
- If the assistant is synthesizing commentary, that synthesis should sound
  provisional and source-aware.

### 6.7 Cross-Domain Handoffs

Goal:

- connect study to practice or verification without losing textual integrity

Rules:

- When Nisaba hands off to Tara, Arete, or Veritas, the copy should explain the
  connection without reducing the text to a motivational slogan.
- Cross-domain bridges should sound like continuity, not conversion.

Good:

- `Carry this passage into a reflection note.`
- `Compare the source trail before promoting the insight to routine.`

### 6.8 Sensitive Passages And Context Warnings

Goal:

- preserve seriousness and reader safety

Rules:

- Difficult passages should be described plainly, not sensationally.
- Context warnings should stay grounded, humane, and non-alarmist.
- Never romanticize grief, violence, moral injury, or historical harm in the
  name of gravitas.
- Remind the reader that pacing and context are legitimate parts of study.

## 7. Do And Do Not Examples

| Scenario               | Do                                                                           | Do not                                                    |
| ---------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------- |
| study hero             | `Primary texts, commentary, and comparative study`                           | `Unlock ancient wisdom through immersive cosmic learning` |
| passage CTA            | `Resume passage`                                                             | `Enter the sacred quote portal`                           |
| compare prompt         | `Compare four translations and note where discipline is framed differently.` | `Find out which version is the most enlightened.`         |
| concept thread         | `Trace how different traditions treat disciplined action.`                   | `Discover the universal truth hidden in all teachings.`   |
| notebook label         | `Open notebook`                                                              | `Continue your soul archive`                              |
| sensitive text warning | `Some passages address grief, violence, or moral injury.`                    | `Brace yourself for dark and powerful truths.`            |
| cross-domain handoff   | `Preserve this note, then return to Tara practice.`                          | `Turn this verse into your next life-hack ritual.`        |

## 8. Definition Of Done For Nisaba Copy

Nisaba copy meets the OSHUN V1 tone standard only when it is:

- scholarly without pomposity
- precise without overloading the reader
- contextual without losing scanability
- interpretive without pretending certainty
- respectful of tradition and source lineage
- quiet enough to support concentration
- careful with sensitive or difficult material

If a Nisaba surface sounds like a marketing page, a motivational quote app, or
an academic paper that forgot it was a product surface, it is off-tone.
