Skip to main content

Appendix J — Release Editions and Audience Profiles

The living book has three audiences:

The public GitHub Pages book remains the canonical live artifact. Major versions can produce additional editions, but those editions are derived from the live source rather than maintained as independent books.

The live site now has two persistent reading modes. AI view is the default canonical view with the full live/research scaffold, including raw core-claim markers and repeated support-state boilerplate. Human view hides the same repeated live-only chapter sections, page-TOC entries, visible section numbers, raw bracketed core-claim markers, and repeated support boilerplate used by the reader-release strip policy, so a reader can stay on the site and read the prose spine without downloading a separate EPUB, PDF, or DOCX. A chapter can also be opened directly in either projection with ?view=human or ?view=ai. Every manifest chapter now carries one .asi-human-only Human Reading Path bridge for human-specific orientation; reader generation unwraps those blocks, removes .asi-ai-only AI/research-only notes, strips raw core-claim markers and repeated support boilerplate while preserving claim text and an inline support-state boundary, preserves one reader-facing Handoff section per generated chapter, and validates section-level word/prose-paragraph floors after stripping. This is a convenience projection of the live book, not a reviewed major-version reader release.

J.1 Content Layers

The project serves all three audiences by separating layers inside one canonical source tree:

Layer Canonical location Edition rule
reader_spine Ordinary chapter prose outside live-only headings. Retain for reader releases and adapt for audio.
live_research_scaffold Chapter status, drafting guardrails, Codex test plans, proof hooks, source crosswalks, and claim-source mapping sections. Retain for live/research releases; strip or summarize for reader/audio releases.
evidence_matrices Appendices, source notes, schemas, release records, proof manifest, test specs, Corben’s sources/local projects, external literature by other authors, implementation horizons, changelog, and lineage. Retain for live/research releases; include selected human-useful appendices in reader releases.
machine_contracts book_structure.json, docs/book_outline.md, inventories, schemas, scripts, Lean modules, and validation commands. Canonical for AI/writing agents; exclude from reader/audio manuscripts except when explained in prose.
reader_review_matrix editions/reader_manuscript/v1_0/chapter_review_matrix.json and docs/reader_chapter_review_matrix.md. Preserves the frozen v1.0 chapter-review history and blockers; current all-chapter coverage is derived from the live manifest.
reader_format_review_matrix editions/reader_manuscript/v1_0/format_review_matrix.json and docs/reader_format_review_matrix.md. Tracks local render evidence, structural inspection, spot checks, application/e-reader review, residual blockers, and release-record status before any reader format is approved.
curated_reader_format_probe editions/reader_manuscript/v1_0/curated_format_probe_manifest.json and docs/curated_reader_format_artifact_probe.md. Records the tracked curated-reader HTML/EPUB/DOCX/PDF structural probe and DOCX/PDF figure-raster fallback state without approving any reader artifact.
curated_reader_blocked_candidate release_records/2026-07-05-v1-curated-reader-blocked-3e59bde3.json and scripts/validate_curated_reader_blocked_release_record.py. Preserves exact historical local HTML, EPUB, DOCX, PDF, e-reader, and audio blockers for that partial candidate; it does not approve, publish, or describe the current book.
reader_epub_probe_manifest editions/reader_manuscript/v1_0/epub_probe_manifest.json and docs/reader_epub_probe_manifest.md. Records exact local EPUB metadata, navigation, spine, and source-card sampling evidence, including e-reader-specific blockers, without approving an EPUB artifact.
reader_docx_probe_manifest editions/reader_manuscript/v1_0/docx_probe_manifest.json and docs/reader_docx_probe_manifest.md. Records exact local DOCX LibreOffice conversion metrics and sampled-page residuals, including DOCX-specific blockers, without approving a DOCX artifact.
reader_pdf_probe_manifest editions/reader_manuscript/v1_0/pdf_probe_manifest.json and docs/reader_pdf_probe_manifest.md. Records exact local UTF-8 PDF probe metrics and sampled-page residuals, including PDF-specific blockers, without approving a PDF artifact.
reader_audio_script_probe_manifest editions/reader_manuscript/v1_0/audio_script_probe_manifest.json and docs/reader_audio_script_probe_manifest.md. Records exact local audio-script review-workspace facts, spoken-treatment counts, and audio-specific blockers without approving narration, MP3, M4B, or audio-embedded EPUB artifacts.
release_derivatives Ignored build workspaces and explicitly recorded release artifacts. Non-canonical outputs; record only artifacts that were actually generated or rendered.
audio_adaptation Audio-script and future audio release workspaces. Derive from a reviewed reader release, not directly from the live book.
companion_material Generated reader/audio companion notes for diagrams, images, tables, code, schemas, omitted dense matrices, and audio-embedded EPUB packaging checks. Use as human-consumption review aids; do not treat them as evidence ledgers or proof that release artifacts exist.

This means the live book can remain useful to AIs and researchers without making the human-reader editions carry every matrix, guardrail, or proof hook. Meaning-critical uncertainty still belongs in ordinary chapter prose so the reader release does not overstate claims after live-only scaffolding is removed.

J.2 Major-Version Artifact Ladder

Each major version should move through a single derivation ladder:

  1. The tagged live book remains the canonical artifact for AIs and human researchers.
  2. The reader source is generated from that tag and strips repeated live-workflow scaffolding.
  3. EPUB, PDF, DOCX, and reader HTML are rendered from the reviewed reader source and recorded one format at a time.
  4. Optional AZW3, MOBI, Markdown, or plain-text files are downstream conversions from the reviewed reader source or reviewed EPUB.
  5. Audio starts only after reader review. MP3, M4B, and audio-embedded EPUB releases need a reviewed narration script, generated audio, spot checks, metadata, and an edition release record.

A listed format is a target, not proof that an artifact exists. The release record has to name the actual render, conversion, or audio package.

J.3 Human Consumption Bundle

A major version can produce a human-consumption bundle after the live-book tag passes its validation gate. The bundle has four artifact classes:

Class Formats Gate
Reader formats HTML, EPUB, PDF, DOCX Render from the reviewed reader source, then record each successful artifact separately.
Optional e-reader conversions AZW3, MOBI, Markdown, plain text Convert from a reviewed reader source or reviewed EPUB, then spot-check navigation, figures, tables, and wrapping.
Audio artifacts MP3, M4B Generate from a reviewed narration script and spot-check against that script.
Audio embedded in EPUB audio-embedded EPUB Open the packaged EPUB and verify the reviewed audio is present and playable before listing it as produced.

The reader manuscript is the human source for the bundle. The audio script is downstream of that manuscript. The live book remains canonical for AIs and researchers after any human bundle is produced.

J.4 Edition Profiles

The tracked profile source is editions/release_profiles.json.

The operational runbook for packaging a tagged major version is docs/major_version_release_runbook.md. The profile file defines the contract; the runbook gives the ordered release procedure.

Profile Primary audience Purpose Default formats
live_book AIs and human researchers Current Quarto/GitHub Pages book with matrices, source crosswalks, proof hooks, schemas, release records, and guardrails. HTML
research_release Human researchers and AIs Frozen major-version snapshot that keeps the evidence machinery intact for audit and citation. HTML, PDF when rendered
reader_release Interested human readers Clean human manuscript derived from the live source while removing per-chapter workflow scaffolding. HTML, EPUB, PDF, DOCX when rendered
audio_release Interested human listeners Narration-ready script and audio package derived from the reviewed reader release. MP3, M4B, audio-embedded EPUB when produced

None of these profiles claims an artifact exists by naming it. A format exists only after the corresponding render, audio generation, and release-record checks have run.

J.5 Reader Release Boundary

The reader release strips live-only sections by heading name:

  • chapter status tables
  • drafting guardrails
  • Codex test plans
  • formalization hooks
  • claim-source mapping status blocks
  • external-literature queues
  • source crosswalks
  • preface sections that explain Codex-test machinery

It keeps the main argument, diagrams, problem statements, mechanisms, interfaces, invariants, failure modes, minimal implementation discussion, summaries, glossary, Corben corpus/local-project path, and separate external-literature path. The result should read as a book while still preserving uncertainty in the prose itself.

The live-site Human view uses the same strip-heading list at render time. scripts/validate_reading_mode_toggle.py checks that the toggle asset, view-mode classes, local-storage key, URL query parameter, live-TOC marker, section-number hiding, raw core-claim marker hiding, support-boilerplate hiding, reader-overlay runtime-count hooks, assistive description/status contract, release policy, and generated Quarto config stay aligned with reader_release.strip_headings. scripts/validate_human_reading_paths.py checks that each chapter has exactly one Human Reading Path bridge and that reader generation unwraps it into ordinary prose. scripts/validate_reader_evidence_boundaries.py checks that reader generation strips raw machine claim markers and repeated support boilerplate while preserving claim text and support boundaries. scripts/validate_reader_spine.py also checks reader-section word floors, substantial prose-paragraph floors, and repeated evidence-boundary paragraph openers so the generated human version cannot pass as one long but hollow chapter or fall back into visible scaffold cadence. scripts/validate_live_human_view.py runs after HTML render and checks that every rendered book page includes the toggle, URL mode contract, marker/support-boundary wrapping hooks, and assistive status strings, while rendered chapter pages also expose the live-only headings, TOC targets, and source view-mode block classes such as .asi-human-only needed for runtime hiding. scripts/validate_live_human_view_browser.js then exercises representative rendered pages by default, or every manifest chapter across desktop and mobile viewports with --all-chapters --all-viewports, in a real browser when Playwright/Chrome is available, checking URL modes, local persistence, live-section hiding, TOC hiding, raw marker and support-boilerplate hiding/restoration, human bridge visibility, rendered Mermaid visibility, reading-mode control visibility, reader-overlay payload availability and runtime operation-count processing, page-level horizontal overflow, and AI-view restoration without claiming a reviewed reader artifact exists.

The generator is:

python3 scripts/build_reader_edition.py --check
python3 scripts/sync_reader_overlay_asset.py --check
python3 scripts/validate_reader_overlays.py --check
python3 scripts/sync_reader_chapter_review_matrix.py --check
python3 scripts/validate_human_reading_paths.py
python3 scripts/validate_reader_spine.py --check
python3 scripts/build_reader_edition.py

It writes derived Quarto source under build/reader_edition/, which is ignored by git. The generated manuscript is a candidate for human review, not the canonical source of truth.

scripts/validate_reader_spine.py --check derives the manuscript in a temporary workspace and checks that every current chapter still has a substantial human-readable spine, required reader headings, one chapter-specific Handoff after Summary, no retained view-mode markers, and no live-only scaffolding after stripping. scripts/sync_reader_overlay_asset.py --check confirms that the live Human-view overlay payload is current. scripts/validate_reader_overlays.py --check confirms that the tracked semantic overlay manifest under editions/reader_overlays/ applies cleanly and that generation writes a reader delta report. The v1.0 review matrix remains a frozen edition-specific record rather than current coverage authority. A non-check spine run writes build/reader_spine_report.json for major-version review; that report is local and does not claim any ebook or audio artifact exists.

The generated reader workspace includes reader_manifest.json with the source profile, target formats, content-layer policy, stripped-heading policy, view-block processing counts, reader-overlay status, reader-spine validation policy, Handoff continuity review requirement, e-reader quality checks, optional downstream-format notes, companion-material policy, and non-claims. It also includes READER_RELEASE_CHECKLIST.md, which records continuity, Handoff review, overlay delta review, typography, figure, EPUB, DOCX, PDF, optional AZW3/MOBI, companion-note, residual, and release-record checks. companion_notes.md records stripped live-only section counts and reader/audio treatment tasks for dense material. Tracked companion notes can also live under editions/reader_manuscript/v1_0/companion_notes/; the current drafting set supports Circle proof receipts, executable-specification proof lanes, and artifact-steward project objects without approving any e-reader or audio artifact. reader_delta_report.md records the generator transformations, editable overlay source, loaded operation files, a zero-active-operation note when appropriate, operation content digests, before/after review excerpts, review checklist, and any section-anchored overlay operations that produced the current human-reader source. The tracked overlay files under editions/reader_overlays/ are the editable delta source; the generated report is reviewed, not manually patched. The live site embeds the same active overlay operations in assets/reader-overlays.html before loading the reading-mode toggle, so Human view can project reader-only section deltas without changing AI view while exposing runtime operation counts for validation. Reader generation also humanizes mechanical scaffold terms such as source crosswalk, Codex workflow, and hyphenated source-note forms where they would otherwise leak into the relaxed manuscript. These generated files do not imply that EPUB, PDF, DOCX, or HTML artifacts have been rendered.

Reader format renders can be attempted and recorded with:

python3 scripts/render_reader_formats.py --check
python3 scripts/render_reader_formats.py --formats html epub docx
python3 scripts/inspect_reader_format_artifacts.py
LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 python3 scripts/render_reader_formats.py --formats html epub docx pdf

Those helpers write reader_render_report.json in the generated reader workspace, snapshot successful formats under build/reader_edition/format_artifacts/ for local review, and can write reader_artifact_inspection_report.json after structural inspection. These reports record local render and inspection outcomes only; they are not major-version release records.

The reader-facing spine is the ordinary chapter prose outside the stripped headings. Any uncertainty that changes the meaning of a claim belongs in that spine, not only in a guardrail, source crosswalk, proof hook, or test-plan section that a reader edition removes.

Images and diagrams stay in the reader path when they carry meaning. For audio, they need a concise spoken walkthrough or a companion-note route before an audiobook or audio-embedded EPUB is claimed.

J.6 Audio Release Boundary

Audio should be generated only from a reviewed reader-release script. Dense tables, schema blocks, code, and proof hooks should become concise spoken summaries or companion notes. The audio release needs:

  • chapter markers and metadata
  • a pronunciation glossary for ASI Stack terms and source IDs
  • spot checks against the reviewed script
  • explicit records for which audio formats were actually produced
  • no silent removal of uncertainty that changes a claim’s meaning

Embedding audio into an EPUB is a future release target, not a current claim.

The script-preparation tool is:

python3 scripts/build_audio_script.py --check
python3 scripts/build_audio_script.py --source-mode curated_reader_manuscript

It creates build/audio_script/ and a pronunciation glossary for review. It does not synthesize audio and does not produce MP3, M4B, or audio-embedded EPUB artifacts.

The generated audio workspace includes audio_manifest.json with the tracked curated reader generation summary, source mode, audio profile, content-layer policy, implementation-horizon script status, script files, companion-treatment counts, pronunciation glossary, proof/equation reading rules, chapter markers, audio review checklist, review status, and non-claims. companion_notes.md counts tables, diagrams, code/schema blocks, and images by script file. proof_equation_reading_rules.md tells a future narrator how to speak theorem IDs, support states, equations, schemas, hashes, and negative controls without turning them into broader proof than the book records. AUDIO_RELEASE_CHECKLIST.md keeps the narration-review and packaging gate explicit so dense tables, diagrams, source IDs, schemas, and proof hooks are either spoken clearly or moved to companion notes rather than silently omitted.

docs/reader_audio_script_probe_manifest.md records the current tracked audio-script probe: 49 generated script files, preserved implementation horizons, 5 table treatment notes, 50 Mermaid diagram notes, 11 image notes, and all MP3/M4B/audio-embedded EPUB targets still marked target_not_generated. It is a review-workspace probe, not an audiobook or audio release record.

J.7 Major Version Gate

A major version should have a release record that says exactly what was validated and produced. For a reader release, the minimum gate is:

  • live-book validation passed at the source commit
  • reader-edition generation check passed
  • human manuscript review recorded remaining residuals
  • EPUB render passed if EPUB is listed as produced
  • DOCX render passed if DOCX is listed as produced
  • PDF render passed only when local PDF dependencies are available and the render actually succeeded
  • human-consumption gate records continuity, layout, diagram/image, relaxed-reading, and companion-note review
  • audiobook gate records reviewed script, spoken-treatment, chapter-marker, spot-check, and embedded-EPUB status when audio is in scope
  • audio release is separate unless narration files and metadata are generated and checked

This keeps the live book useful for AI and research work while giving human readers clean editions that do not ask them to wade through every internal evidence scaffold.