# Nisaba expansion: source review and learning routes

Reviewed on 2026-09-06 against the immutable source revision
`1ceae52c7896a59ac74a4429d410f3218f0b91c6`. This is an unpublished authoring
map, not completed teaching coverage. All 621 lines of
`V1/features/domain-nisaba.md` were read alongside the current nine-slide
orientation. The page contributes 29 meaningful units and one structural unit;
none gains a reviewed assignment merely by appearing here.

## Reconcile the source before expanding the guide

The feature page says **22 sub-packages**, but the pinned `libs/nisaba/` tree
has **23 direct package manifests**. Its list omits `study-adapter`, whose
manifest names `@nisaba/study-adapter`. The remaining 22 package names match the
page's list. The current overview does not repeat the incorrect count.

The language root's export surface also needs precise treatment. Hebrew is
exported flat, while many other languages are namespaced. Tokenization exists at
`languages/src/tokenization/index.ts`, but the root `src/index.ts` does not
re-export that module. Teach the actual supported import boundary instead of
converting a directory's existence into a root-API claim.

The omitted study adapter is material, not just a counting difference. Its
source contains notebook/card authoring and revision operations, plus a
PostgreSQL-backed store for the `nisaba_study` schema. Default capability
discovery reports persistent notebooks unavailable; injecting a notebook store
changes that descriptor to supported and enables the corresponding operations.
The separate `persistNotebook()` method still unconditionally returns an
unavailable response at this pin. Explain these method-specific paths; neither
the default descriptor nor the legacy method describes every adapter call.

The inspected store validates records, maintains revision rows and rejects a
stale predecessor update. This is not proof of a deployed client, caller
authorization, cross-device UI behavior or transaction safety. Trace its
composing service and actual database tests before making those claims. The
adapter explicitly leaves authorization for permission changes and rights
evaluation for publication to its caller. Media-study selectors remain a
separate unsupported contract in this adapter.

These findings qualify the feature page's dated 2026-06-23 shell/stub account;
they do not erase it or prove that the scholarly reader's particular paths are
fully integrated. Keep the consumer shell, philology engines and study-adapter
consumers distinct. The presentation's existing narration already labels its
maturity observations as historical rather than a fresh availability probe.

## Learning sequence and required teaching depth

The outcomes below are not a fixed guide count. Give mechanisms, worked examples
and reference-heavy comparisons as much room as they need. Retain the current
orientation, then introduce prerequisites before granular internals.

| Learning route                                     | Feature-page units to teach                                            | Essential outcome                                                                                                                                   |
| -------------------------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Purpose, packages and surfaces                     | Opening; codebase; surfaces; V1 scope                                  | Identify the reader/scholar journeys, 23 package boundaries, consumer routes, dynamic power-user route and release/implementation distinctions.     |
| Scholarly identity and contract vocabulary         | Canonical-contract introduction; shared enums; CanonicalReference      | Follow a scheme-aware reference into an identified reading object; explain every enum and why the long-tail scripts/directions matter.              |
| Passage, witness, edition and translation          | The four object sections                                               | Preserve lineage and rights, teach each field/invariant, and compare valid and rejected records.                                                    |
| Lexicon, morphology and concept evidence           | Lexicon/morphology; concept graph                                      | Trace a word to an attested parse, distinguish provenance from confidence, and use the real node/relation vocabulary.                               |
| Annotation, notebooks, plans and scholar authority | Annotation/notebook/plan/citation section; ScholarProfile              | Walk private interpretation, ordered study, citation approval and credential-dependent authority without conflating schema and runtime enforcement. |
| Shell adapter, search and recommendations          | Shell adapter; search modes; cross-domain wiring; study-plan re-export | Trace adapter calls, target identities, ranking/deduplication, shared-concept aliases and the study engine's actual entry points.                   |
| Language and criticism mechanisms                  | Languages; criticism/IIIF                                              | Teach the distinct scripts and handlers, concrete computation, collation/apparatus methods and image-position mappings with worked inputs.          |
| Reading, daily study, scholar mode and export      | All five workflow subsections                                          | Show usable journeys, source-backed interpretation, declared continuation behavior, rights-aware export and cross-domain handoff.                   |
| Integration and evidence boundaries                | External binding; honest status; related sources                       | Separate in-process standards support, actual clients, injected stores, source-update propagation, UI evidence and dated gaps.                      |

## Worked examples that the orientation does not yet supply

- Follow a canonical reference through its five allowed schemes, normalized
  form, optional URN, work identity and division path of up to twelve levels.
  Compare passage identity with the selected edition rather than merely saying
  that a reference is stable.
- Validate a passage's ordered, non-overlapping segments and its published
  citation requirement. For witnesses, cover the full material/digitization
  vocabulary, coherent date range, unique passage links, image-manifest and
  non-public-domain licence rules. A schema field is not a rights clearance.
- Reject an apparatus witness absent from its edition's declared witnesses;
  check publication dates and approved-review metadata. Compare all five
  translation modes and the different-source/target-language rule.
- Contrast lexicon senses and attested morphology: citations, self-reference,
  feature deduplication, human/rule/model/import provenance, and the named
  reviewer requirement for human parsing. Cover all 12 parts of speech and 14
  morphology features at the appropriate depth.
- Use all ten concept-node kinds and nine real relation values. Reject self
  edges and unsupported high-confidence edges; explicitly retire the four
  illustrative labels corrected by the source. A high-confidence label needs
  evidence and does not itself establish truth.
- Trace all annotation kinds/targets and selector/body requirements, notebook
  kinds/items/collaborators, all nine ordered study-step kinds, lifecycle
  timestamps and citation subject/source/style/verification fields. Review
  credentials, attribution, disclosure and every authority field. Work both a
  valid review and a missing-credential denial.
- Compare all six philological search modes, five entity filters and returned
  target identities. Follow the three explicit local-concept aliases into shared
  threads, then explain recommendation base scores, index decay, target-domain
  deduplication and default cap. Link the distinct Metis scores without calling
  a ranking constant a measured relevance result.
- Teach each language/script family's unique transformations and limitations,
  including the ATF parser/generator/Unicode bridge, transliteration,
  tokenization and lexicon lookup. A handler list or broad "30+" phrase is not
  coverage of its algorithms.
- Follow collation, apparatus generation, stemmatics, CBGM, Lachmannian
  reconstruction, witness classification, scribal errors, Leiden conventions and
  sigla. For IIIF, trace witness → manifest → canvas/text range → annotation
  region, including multiple imaging sessions and unresolved mappings. The local
  registry does not establish that an external source was fetched.
- Walk reading comparison, image/transcription, lexicon/morphology, daily
  passage, continuation, scholar gating and export with actual UI captures.
  Distinguish the singular notebook editor from the plural notebook index and
  the dynamic `/domains/nisaba` route from a dedicated folder. Capture loading,
  absent data, authorization, unresolved anchors and successful return states.
- Reconcile the newer study-adapter paths with the feature page: no store,
  injected store, unknown notebook/card, stale revision, invalid publication,
  permission change and unsupported media selector. Trace caller authority,
  persistence, partial failure and real service/UI evidence; do not collapse
  these into one generic notebook capability.

## Evidence and publication work still required

Review the canonical domain deep dives, architecture, curation/privacy/export
sources, full implementations and their tests, not just this feature page.
Extend discovery to the omitted package and its consumers. Verify the source's
external-client and source-invalidation statements against actual owning code
before repeating an absence claim as a current fact.

For every finished explanation, bind the full source unit to exact assembled
slide hashes with a substantive rationale. The current overview omits many
fields, enum values, routes and algorithms above, so its citations cannot count
as complete teaching of those units. Reconcile duplicated source contexts
individually rather than exempting them.

Use native relationship/sequence diagrams and readable comparisons. Actual
screen captures need route, revision, viewport and state provenance; label
proposals separately. Narration should teach each worked case and guide visual
attention. Finish standalone/embedded/mobile/PDF review and normal-speed
listening before treating a resulting guide as complete.
