# Comprehensive library expansion

The current machine-transfer plan and exact remaining work are maintained in
[TODOS.md](TODOS.md). That checklist supersedes older progress descriptions;
this document records the expansion method and inventory foundation.

The delivered Eve/V1 library is the first completed part: 35 guides, 349 unique
slides, measured narration and individual PDFs. The expanded library is still
being authored. Its final presentation count follows coherent learning outcomes
and the source inventory; 35 is not a limit.

## Required scope and sequence

1. Account for every V1–V10 source and every authored and generated Docs Center
   surface. Include the supporting documentation exposed by Domains and
   generated references. Preserve dated design, implementation, wiring and
   acceptance distinctions.
2. Decompose the material into focused presentations. Teach the purpose, owning
   boundaries, mechanics, worked cases, recovery and evidence of each subject.
   Preserve detailed contracts and inventories in usable explanations. Sequence
   prerequisites before dependent guides, give each guide a canonical home and
   cross-link related subjects.
3. Keep guide narration times and every ancestor total derived from current
   audio. Mark incomplete narration explicitly. Extend the existing sidebar,
   search, mobile navigation and guide details as the hierarchy grows.
4. Integrate Eve with the selected guide, slide and source context. Support
   grounded questions, persisted notes, proposed changes, preview, history and
   actual edits through the existing Eve authority and execution boundaries.
   Regenerate affected slides, narration and PDFs and test the real workflow.
5. Perform the final Domains audit against the registry, domain directories,
   code-root mappings and planned roots. Every domain needs an appropriate
   presentation home under Domains and links to related product/shared guides.
   Planned-only systems remain visible with their actual status.
6. Review every slide visually after the content, Eve and Domains work. Add
   diagrams wherever they make the explanation clearer, including relationships,
   sequences, state changes, ownership, decisions and worked flows. Introduce
   additional diagram slides when a separate visual explanation is useful.
   Preserve readable labels, a clear reading order, accessible descriptions and
   meaningful narration. Verify every affected desktop/mobile slide and PDF.

The original long presentation stays decomposed. New guides enrich their topics;
they do not merely cut the original slide sequence into arbitrary chunks.
Narration retains the requested **oh-shuhn** pronunciation and deliberate
sentence, heading and paragraph pauses, verified in the encoded audio.

## Inventory and teaching evidence

`inventory/` is a generated accounting artifact, separate from the delivered
catalog. It does not create placeholder presentations or claim that inventoried
material has been taught. The existing source/guide map still documents the
Eve/V1 library; section-level teaching assignments are an additional, stricter
review that must be backfilled for those guides as well as new ones.

The collector checks out the exact source commit in a disposable worktree, skips
Git LFS asset downloads and runs the existing `tools/docs_center/cli.py:build`.
The generator writes only inside that disposable checkout. Its actual emitted
reference pages supply the generated inventory, including families outside
`manifest.pages`. The full authored corpus comes from **all** `manifest.pages`,
all tracked V1–V10 Markdown, all tracked domain Markdown and local Markdown
links exposed by generated reference content.

Markdown units retain heading ancestry, occurrence, exact line span and a
content hash. Every line belongs to a unit. A heading without its own content is
structural; child sections are separately accountable. Tables and fenced code
remain intact. Generated units retain every main-content heading, normalized
text hash and link destinations. The search index's capped headings never limit
coverage. Missing reader shells cause collection to fail instead of losing a
reference page silently.

Unit identity excludes line numbers and content hashes. An unrelated line
insertion therefore preserves an assignment, while a changed explanation makes
it stale. Renamed headings and changes to repeated identical heading positions
require reassignment. Exact repeated units are recorded as review candidates;
they are not automatically exempted, because the same wording may serve a
different source context.

Assignments in `assignments/*.json` connect each meaningful unit to specific
slides within specific guides. Reviewed explanations require the exact source
hash, exact slide fingerprints (including diagrams and inherited scope), source
citations whose excerpts include that section, and a rationale describing what
those slides teach. A mere source reference cannot pass. The validator checks
the integrity of these assertions; editorial source review is still necessary to
establish that an explanation is faithful and complete.

An assignment file also declares the exact source revision used by its slide
evidence. When that revision differs from the primary inventory, the coverage
gate reads the cited file from that committed Git snapshot and requires the
complete bytes to match the primary inventory's pinned source-file hash. This
narrow bridge allows unchanged Markdown to retain one unit identity across a
later delivery snapshot. It rejects a changed file, a stale slide hash, a
mismatched assignment revision, source path or heading, and any uncommitted
working-tree substitute. Changed supplemental sources require their own
inventory review before they can close a unit.

The report distinguishes **unassigned**, **assigned**, **reviewed**, **stale**
and **structural** units. A complete claim is blocked while meaningful units are
unassigned, only assigned, stale or invalid. Inventory counts are not an
estimate of how many presentations a reader should need.

## Reproduction

Use the dependencies in `tools/presentations/requirements.txt`. The isolated
collector needs local Git objects for the pinned source and roughly 3 GiB of
temporary disk space. Run it with the existing resource supervisor; it launches
no web/mobile build, browser, model or provider.

```sh
python tools/presentations/run-supervised.py python tools/presentations/inventory-center.py
python tools/presentations/check-center-coverage.py
python -m unittest discover -s tools/presentations/tests -p 'test_inventory.py'
```

`inventory-center.py --check` recollects the pinned corpus and compares every
shard. `check-center-coverage.py --check` verifies report freshness.
`check-center-coverage.py --require-complete` is the final teaching-coverage
gate; it deliberately fails during the expansion while coverage is incomplete.

Neither an inventory pass nor the earlier Eve/V1 verification completes the
V1–V10 expansion, Eve integration or final Domains audit.

The [final freshness policy](FRESHNESS.md) now defines an explicit immutable
source cutoff on `origin/main` and a descendant claim revision. All inventory
families must be rebuilt at that cutoff, and any later tracked change outside
the Presentation Center implementation paths forces a new cutoff and another
source review. The current working pin remains an expansion baseline; it is not
a claim about the moving branch.

## Inventory verification

Two independent collections of the pinned checkout matched all 105 inventory
shards: 9,262 authored sources and 319 generated pages. All 34 presentation-tool
tests passed, including 16 new coverage regressions. Ruff, scoped formatting,
report freshness and existing library freshness passed. The 42 tested library
artifact hashes and all 35 PDF hashes remained unchanged.

The final teaching gate correctly returned an incomplete result for the 103,326
meaningful units awaiting section-level review. That is a verified rejection of
a premature complete claim. The
[inventory verification record](verification/inventory.json) links the actual
collection, test and gate logs.

The preliminary Domains source-of-truth check found 13 existing registry issues:
eight generated HTML TODO mirrors are misclassified as authored sources, and
five newer root TODO ledgers lack registry ownership entries. These remain
explicitly recorded for the final Domains audit; they are not reported as a
passing domain check. All 54 domain entries in the pinned inventory have their
three canonical Markdown sources.

## Whole-repository discovery beyond documentation

[The Git-backed discovery index](inventory/repository/README.md) now accounts
for all 140,123 tracked entries at the same source pin, including
dot-directories, code, configuration, workflows, tests, assets, one symlink and
one gitlink. Its 43 root groups retain exact file identities, while 3,324
package and 3,505 project manifests provide declared structural context. No raw
command bodies or external asset payloads are exported.

The comparison finds 130,861 paths outside the documentation-source inventory.
This is not a count of meaningful non-Markdown units: it includes uncatalogued
documentation and other file families too. Forty-four non-root package manifests
sit outside the declared pnpm patterns, and ten names occur in multiple
directories. Fixtures, embedded packages and tool-specific workspaces make these
review candidates, not automatic runtime defects.

`inventory-repository.py --check` verifies the pinned file/manifest projection;
it does not run an effective Nx/pnpm graph, inspect submodule/LFS payloads or
establish teaching completeness. Meaningful code/configuration/workflow/asset
units, ownership and implementation review, and substantive assignments remain
required. The existing documentation gate and its source-unit backlog remain
unchanged; neither inventory alone closes whole-monorepo coverage.

## Non-Markdown workflow declaration units

The [workflow inventory](inventory/workflows/README.md) now retains 3,718
meaningful units from all 106 pinned workflow files and two action definitions.
Exact settings, ordered steps and complementary source context account for every
byte of those 108 files. Whole-file context binding invalidates review when
inherited permissions, environment, triggers or matrices change. No source
command bodies or general scalar values are exported.

`inventory-workflows.py --check` verifies this source family;
`check-workflow-coverage.py --check --require-complete` rejects its currently
3,718 unassigned units. This extends beyond Markdown without treating parsed
declarations as taught material. Shell semantics, actual CI runs, ownership,
implementation review and the remaining repository families are still open. Keep
this gate separate from the documentation gate and require both; neither alone
establishes whole-monorepo teaching.
