Repository quality and release-readiness upgrade plan

Objective

Increase the repository's executable value by making every computational result, figure, and interactive kernel-method demonstration reproducible and tested.

Required work

• Define one clean command that validates and builds every book format and interactive asset.
• Add executable notebooks/scripts for core algorithms, worked examples, and figures with pinned environments and seeds.
• Add numerical tests for kernel validity, Gram matrices, solvers, approximations, Gaussian processes, and edge cases used in the text.
• Validate internal links, citations, bibliography entries, equation references, generated assets, and chapter provenance in CI.
• Add an interactive kernel laboratory for composing kernels, inspecting spectra, and comparing exact versus approximate methods.
• Add reproducible performance experiments for random features, Nyström methods, iterative solvers, and scalable kernels.
• Separate canonical source from generated publication output and document regeneration.
• Audit quotations, figures, datasets, and exercises for attribution and redistribution rights.
• Add accessibility checks for HTML, equations, figures, color usage, and navigation.
• Version releases of the manuscript, code, environment, and generated site together.

Acceptance criteria

• A clean clone builds the complete book and executable companion.
• Every computational claim/figure maps to tested runnable code.
• Provenance and permissions checks are green in CI.
• A tagged release archives source, environment, and generated outputs.

Path-specific implementation map

Canonical source and build graph

• Treat book.yml, manuscript/, bibliography.bib, provenance/, and permissions.yml as canonical inputs; document which of public/, publication/, tmp/, reports/, and reviews/ are generated, retained evidence, or disposable.
• Consolidate the many scripts under tools/ into a documented command runner with stages for validate, check examples, build web, build print, link/citation audit, accessibility, and package.
• Add a build manifest recording source commit, environment lock hash, tool versions, chapter hashes, generated artifact hashes, and warnings.
• Remove or ignore regenerable content in tmp/; fail CI when generated output is stale relative to canonical source.
• Add schema validation for book.yml, permissions.yml, every provenance/*.yml, bibliography-retained/unresolved files, and migration approvals.

Executable mathematical companion

• Turn individual checks/ch-*.py scripts into an importable kernelbook_checks/ package plus parameterized pytest suites; retain chapter/exercise IDs in test metadata.
• Move shared numerical logic out of check scripts into src/kernelbook/ modules for kernels, Gram validation, solvers, approximations, tests, Gaussian processes, and utilities.
• Add PSD/tolerance/property tests and explicitly mark conditionally positive, indefinite/Krein, approximate, randomized, and finite-precision cases.
• Make notebooks/labs/*.py deterministic apps/scripts with small default datasets, fixed seeds, expected metrics, and exportable results; keep notebooks/lab_utils.py limited to shared UI/helpers.
• Add a browser public/lab/ or source equivalent for kernel composition, Gram spectra, hyperparameters, random features, and Nyström approximations backed by small verified examples.
• In projects/*/, add dataset generation manifests, baseline tests, metric definitions, expected ranges, and clean-room reset commands.

Traceability and publication quality

• Generate a machine-readable matrix mapping manuscript theorem/example/figure IDs to provenance entries, permissions, executable checks, labs, and publication output.
• Extend .github/workflows/quality.yml to run schemas, mathematical tests, deterministic labs, citations, permissions, broken links, generated-output drift, and accessibility before deployment.
• Keep publish-kaggle.yml isolated from the canonical build and pin every dataset/kernel/environment reference.
• Add docs/BUILD_ARCHITECTURE.md, docs/NUMERICAL_TOLERANCES.md, docs/PROVENANCE_POLICY.md, and docs/RELEASE_PROCESS.md.
• Publish versioned source, web/print outputs, environment lockfiles, test report, provenance matrix, and checksums together.

Start by reading book.yml, the tools/ scripts, and .github/workflows/quality.yml to understand the current build and validation paths. The issue is a repository-wide plan rather than a bounded first contribution; completion requires the listed build, numerical, provenance, accessibility, and release criteria to pass together.