unaltraweb 0.5.0 → 0.6.0

data/docs/agents/owner-preparation-2026-09-29.md

@@ -0,0 +1,254 @@
+# Checkout-free MCP launcher: owner preparation report
+
+Date: 2026-09-29. Hub handoff: **unaltraweb owner preparation**, following
+`gacontext/src/bash/mcp_factories/handoffs/owner-preparation-prompts.md` and its
+existing-manual baseline. Tracking: [issue 76](https://github.com/dosquartsdedocs/unaltraweb/issues/76).
+
+## Source and delivery status
+
+- Primary checkout: `unaltraweb`; branch `feat/76-distributed-mcp-launcher`.
+- Base/source checkpoint: `260271e41b17be0f95dcb8047014c35cb97142ee`.
+- Implementation is an **uncommitted owner working-tree change**, not a release,
+  tag, pushed branch or PR. The hub can ingest this report without changing its
+  catalogue or activating a client registration.
+- The full published 0.5.0 GHCR runtime already contains the factory and supports
+  checkout-free site work. No replacement image release is needed to run it.
+- The published 0.5.0 wheel lacks the standalone host launcher. The new wheel
+  contents require a future reviewed package release under a new version. The
+  local test wheel still reports source version 0.5.0 and must never replace the
+  published wheel of that name.
+
+Changed paths:
+
+```text
+Makefile
+pyproject.toml
+packaging/launcher/Makefile
+src/unaltraweb_mcp/docker_launcher.py
+scripts/unaltraweb-mcp-bootstrap.sh
+scripts/test_wheel_install.py
+scripts/validate_distribution.py
+test/test_distributed_launcher.py
+test/distributed_launcher_smoke.py
+docs/_documentation/en/40-distribution.md
+docs/agents/mcp-contract.md
+docs/agents/owner-preparation-2026-09-29.md
+```
+
+The source `mcp-factory.yml`, component BOM/schema, published receipt, managed
+consumer scaffolds and their version selections are unchanged. Preserved hashes:
+
+| File | SHA-256 |
+| --- | --- |
+| `src/unaltraweb_mcp/component-contract.json` | `f3de4b289fc6ae66ddc86bf6a701b3a2cfaed66ab6303f64252c92639a7aab98` |
+| `release-candidates.json` | `e57a9dbb041c1e7fcd781cd1524f4de0317382e0f7303bb36bfa59c0b6d1cb9b` |
+
+## Native installed profile and capability boundary
+
+The wheel installs `share/unaltraweb-launcher/Makefile`, the **byte-identical native
+schema-v1 `mcp-factory.yml`**, and the existing bootstrap, project-ID, CSV mount and
+cleanup scripts under `scripts/`. It uses the current `runtime.kind: container`,
+`runtime.package_manager: docker`, consumer binding, `transport.command` with
+`make -C ${factoryRoot} mcp-stdio`, and inherited `MCP_CONSUMER_WORKSPACE`.
+Here `${factoryRoot}` names the installed launcher directory. No new H1 fields or
+alternative central schema were introduced. Companion lifecycle flags and exact
+tool/resource inventories remain those in the native manifest.
+
+`unaltraweb-mcp-docker path` resolves that directory from installed wheel metadata.
+`manifest` prints the descriptor. `prepare`, `check`, `smoke`, `serve` and `down`
+delegate to packaged shell scripts. Preparation may pull; check/smoke require a
+local image, use its immutable local ID and mount neither source nor consumer.
+Serve requires an explicit consumer and preserves both canonical host-path mounts
+and the original factory/project labels. Cleanup retains its exact project scope.
+
+The profile directory is independently relocatable with Make, POSIX shell, Linux
+core utilities and Docker. The console adapter requires Python. The native
+`unaltraweb-mcp` CLI retains the BOM's exact package-only and factory-required
+inventories: shipping a Docker adapter does not put Ruby/core/TeX/Chromium or
+worker/companion implementations into the wheel. `new-web`, doctor and inspection
+remain usable natively; full MCP serving and build/PDF orchestration execute in
+the selected GHCR image.
+
+## Published identities and dependency closure
+
+Native identities use existing BOM `kind`, `version`, `release`, `reference` and
+`image_repository`, and manifest `mcp_dependencies[].uv_spec`. Container references
+below are in `ghcr.io/dosquartsdedocs/`; each hash is an OCI repository digest,
+not a Docker image configuration ID.
+
+| Component / repository | Version | Exact selected digest |
+| --- | --- | --- |
+| Full MCP `unaltraweb-mcp` | 0.5.0 | `sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98` |
+| Base Ruby/Jekyll `unaltraweb` (receipt) | 0.5.0 | `sha256:4c7bfa51b8f936993ca5a1350d8b63ac3af77f88e97065a9b4a223583528fa8e` |
+| PDF `unaltraweb-manual-pdf` | 0.5.0 | `sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097` |
+| Python `unaltraweb-compute-python` | 0.4.0 | `sha256:18cb269811bd4005800382da25a480ec2bca7eac8d0501ad1ef36bad1c0f8cd9` |
+| R `unaltraweb-compute-r` | 0.4.0 | `sha256:928ffb93f221e09e8b929157dee473b838e061915a2eb67224e4124b85f81837` |
+| Chromium `unaltraweb-web-capture` | 0.4.0 | `sha256:0bf1bc67fe63e1440bffe708a168beefa11c54441650a871ab99380d362f7c1e` |
+| Historical full MCP `unaltraweb-mcp` | 0.4.0 | `sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9` |
+| Historical PDF `unaltraweb-manual-pdf` | 0.4.0 tuple | `sha256:bb3e373f8a512495eeed684c23ad904d298c2e20a6dc3ade0d0a60c7ec9a9f11` |
+
+The runtime layer is embedded in the full MCP image. The four workers remain
+separate feature-selected containers; compute/capture were inventoried, not
+rendered again in this preparation. Companions remain separate MCP servers:
+
+| Companion | Native selected wheel and SHA-256 |
+| --- | --- |
+| Diavisuals 0.4.0 | `diavisuals[mcp] @ https://github.com/dosquartsdedocs/diavisuals/releases/download/v0.4.0/diavisuals-0.4.0-py3-none-any.whl#sha256=bfedcc9e2554f25ce4a1c33e556f352210848fccb8da800d1c3900dd86c48c93` |
+| Vegavisuals 0.4.0 | `vegavisuals[mcp] @ https://github.com/dosquartsdedocs/vegavisuals/releases/download/v0.4.0/vegavisuals-0.4.0-py3-none-linux_x86_64.whl#sha256=b52ffa743643dd6b5e0320e7a9aa0cd500ea06262b7d5098c0c3f94a379bc0ea` |
+
+Both dependencies retain `required/install/build/check/smoke: true` and
+`init/update: false`. Their renderer archive identities and earlier real receipt
+acceptance are in [visual-companions-0.4.0.md](visual-companions-0.4.0.md); that
+2026-09-26 evidence is not presented as a new rendering run here. Historical core
+0.4.0 selects companions 0.3.1; the 0.5.0 receipt verifier does not promise to accept
+those older provider identities.
+
+## Synthetic acceptance and isolation
+
+Platform: Linux/amd64, host Python 3.12, Docker 27.2.0. A non-editable wheel was
+installed with `--no-deps --no-index` into
+`/tmp/opencode/unaltraweb-owner-20260929/venv`. Its launcher metadata resolved
+outside the source checkout. The retained test wheel SHA-256 is
+`a8b2136ffb23970980b86b70e64d509e2e24500f1e032b023f857cde22a7988f`.
+
+All acceptance consumers, Git indexes, caches, generated PDFs and Jekyll outputs
+are synthetic under `/tmp/opencode/unaltraweb-owner-20260929/`. No host core was
+mounted. Preview inspection verified only the synthetic consumer bind and no
+Docker socket. Ports were allocated on loopback; preview stop and digest-bound
+PDF preview cleanup passed. Full stdio sessions used the installed launcher.
+
+| Scaffold / host build | Active MCP / PDF | Profile coverage | Result |
+| --- | --- | --- | --- |
+| 0.5.0 / MCP build | 0.5.0 / 0.5.0 | All four profiles | Empty detection, creation, site check, build, preview, HTTP and HTML audit pass; manual PDF/cover pass. Ports 32770–32773. |
+| 0.4.0 / 0.4.0 host build | 0.4.0 / historical pinned PDF | `unaltremanual` | Host build/PDF, MCP build, preview, HTTP and HTML audit pass. Port 32776. New image-background and update-advisory tools are absent as expected. |
+| 0.4.0 / no earlier host build cache | 0.5.0 / 0.5.0 | `unaltremanual` | Pass with fresh synthetic runtime cache, port 32774. Update advisory reports `update_available`; no sync is applied. |
+| 0.4.0 / successful 0.4.0 host build first | 0.5.0 / 0.5.0 | `unaltremanual` | Site check and PDF pass; MCP build fails because retained `tmp/Gemfile.local.lock` selects `google-protobuf (4.36.1)`, unavailable in the 0.5.0 image. No automatic cache deletion or pin migration. |
+
+Evidence directories are `released-050-full`, `released-040-manual-full`,
+`mixed-fresh-040-050`, and `mixed-retained-lock-final`. Runs retain `evidence.json`,
+server stderr and actual outputs, including the reproduced mixed-cache failure's
+MCP response, host-build log and generated lock. The initial
+four-profile run hit the terminal's 120-second limit after one profile; its owned
+test session was cleaned by exact consumer identity and the complete run passed
+with a 600-second outer limit. An initial historical runner call to the newer
+`image_background_check` was corrected to inspect actual capabilities; it was a
+test-driver mismatch, not a claimed 0.4.0 feature.
+
+Retained PDF hashes:
+
+- 0.5.0 and fresh 0.4.0-scaffold/0.5.0 runtime:
+  `4e6e405ed690caf075ec33ea04090d2a5c4bfbf0fb0a49a35cdab819c6f40939`.
+- Historical host/runtime 0.4.0:
+  `68f067addf5e009364edb42042de2410af5ce8c38543556852d4498bd9663a75`.
+
+Both covers were visually inspected. The 0.5.0 PDF has nine pages including the
+synthetic Coordinates chapter, contents and expected draft marker. This is
+technical acceptance, not human publication approval.
+
+## Owner gates and exact reproduction
+
+Passed:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s test -p 'test_*.py'
+make distribution-check
+make workflow-check
+make wheel-check
+make mcp-check mcp-smoke \
+  MCP_RUNTIME_IMAGE=unaltraweb-owner-76-runtime:20260929 \
+  MCP_IMAGE=unaltraweb-owner-76-mcp:20260929-final \
+  MANUAL_PDF_DEV_IMAGE=unaltraweb-owner-76-pdf:20260929 \
+  MCP_SMOKE_MANUAL_PDF_IMAGE=unaltraweb-owner-76-pdf:20260929 \
+  MCP_SMOKE_PROJECT=/tmp/opencode/unaltraweb-owner-20260929/owner-preview-final
+docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp \
+  --entrypoint make unaltraweb-owner-76-mcp:20260929 -C /opt/unaltraweb gem-check
+make --silent --no-print-directory \
+  -C /tmp/opencode/unaltraweb-owner-20260929/venv/share/unaltraweb-launcher \
+  mcp-check mcp-smoke
+PYTHONPATH=src python3 -m unaltraweb_mcp.cli --project docs mcp prose-check \
+  --target _documentation/en/40-distribution.md
+make docs-build DOCKER_IMAGE=unaltraweb-owner-76-runtime:20260929
+git diff --check
+```
+
+Unit suite: **553 tests, 30 optional skips**. `wheel-check` verifies all four
+factory-free native scaffolds and every byte of the launcher/helper closure.
+The installed-profile smoke uses the published image, no socket/source mount and
+`--network none`. Owner source smoke additionally runs a real stale PDF worker and
+a socket-free persistent preview. Docker's content-addressed build cache reused
+existing layers; test image tags and consumer/Python/Jekyll caches were separate.
+The owner smoke now creates a fresh unique fixture by default and refuses any
+existing explicit `MCP_SMOKE_PROJECT`, preventing its fixture reset from touching
+prior work. Prose check reports only one pre-existing informational long-sentence
+finding in the publication-workflow paragraph; docs build and diff check pass.
+Existing `:dev`, manual build and TIGIT local worker image IDs were rechecked and
+preserved. Test image configuration IDs:
+
+- `unaltraweb-owner-76-runtime:20260929`: `sha256:df6a55511b5e40c3fde8a10326263cc7a87723b8c090e8333d64bf848c3a853f`.
+- `unaltraweb-owner-76-mcp:20260929`: `sha256:dd795ad90dc30547ae09c9175e06f296af1072f4277a2b02d8122000c7378e07`.
+- Final source gate `unaltraweb-owner-76-mcp:20260929-final`: `sha256:1ef3d4e7ac5fbb60b66103415c87c30bb432802016ccc30b46b896de3bf35a1b`.
+- `unaltraweb-owner-76-pdf:20260929`: `sha256:6c7c5411b4f570fcdcfb1f984a9d9a0e36cc54d606bf459ca67929af0bc0d145`.
+
+The host `make gem-check` initially refused the absent semver-tagged base image;
+the exact gate then passed inside the isolated owner image using its local Ruby.
+`make distribution-release-check` correctly **fails** at this post-release source
+checkpoint: it is not the receipt-only child of the recorded candidate source.
+The published receipt is preserved rather than rewritten to make a source
+preparation look publication-ready.
+
+Acceptance driver (fresh output directories are required):
+
+```bash
+L=/tmp/opencode/unaltraweb-owner-20260929/venv/bin/unaltraweb-mcp-docker
+MCP05=ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98
+MCP04=ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9
+python3 test/distributed_launcher_smoke.py --launcher "$L" --image "$MCP05" \
+  --output /tmp/opencode/unaltraweb-owner-20260929/released-050-full
+python3 test/distributed_launcher_smoke.py --launcher "$L" --image "$MCP04" \
+  --profiles unaltremanual --host-build \
+  --output /tmp/opencode/unaltraweb-owner-20260929/released-040-manual-full
+python3 test/distributed_launcher_smoke.py --launcher "$L" --image "$MCP05" \
+  --scaffold-image "$MCP04" --profiles unaltremanual \
+  --output /tmp/opencode/unaltraweb-owner-20260929/mixed-fresh-040-050
+python3 test/distributed_launcher_smoke.py --launcher "$L" --image "$MCP05" \
+  --scaffold-image "$MCP04" --profiles unaltremanual --host-build \
+  --output /tmp/opencode/unaltraweb-owner-20260929/mixed-retained-lock-final
+```
+
+The final command intentionally reproduces the retained-lock failure in a new
+output directory. The original `mixed-040-050` run used the driver's then-default
+host-build step before that option was made explicit.
+
+## Range adoption points, gaps and next action for the hub
+
+1. **Install/discovery:** map the installed `path` and existing descriptor into the
+   accepted hub contract. Do not treat a source checkout's `make mcp-check` (which
+   builds) as equivalent to the installed profile's prepared-image check.
+2. **Compatibility versus exact selection:** `mcp_dependencies` and
+   `distribution.py:companion_dependency_requirements` currently select exact
+   provider versions/wheels; `site_tools.py` receipt validation also requires exact
+   provider version/release. A future accepted range must be tested there without
+   weakening request/input/artifact hashes or equating wheel hashes with images.
+3. **Consumer tuple:** `consumer_integration`, scaffold rendering/update planning,
+   the Make image selection and native Gemfile pins remain atomic reviewed
+   selections. Preserve their concrete revision and hashes after any future range
+   resolution. Fix/test runtime-specific generated Bundler-cache handling before
+   promising transparent switching across the mixed 0.4.0/0.5.0 tuple.
+4. **Coverage:** tested endpoints are 0.4.0 and 0.5.0, not a promised `[0.4,0.6)`
+   interval. The other three 0.4.0 profiles, non-Linux/amd64 platforms, independent
+   new compute/capture/companion rendering and stable publication channels were
+   not covered by this preparation.
+5. **Delivery:** review the owner diff, assign a new package version through the
+   normal release procedure, bind final artifacts to new receipt evidence, then
+   adopt the installed profile in a separate synthetic hub pilot. The full 0.5.0
+   image can remain selected. Client activation and each real-manual upgrade need
+   their own later owner session.
+
+TIG/TIGIT retain 0.4.0 build defaults; Geodisseny retains 0.5.0. Their sources,
+generated artifacts, registrations and worker identities were not migrated.
+During this session the author separately approved storage cleanup: five stopped
+old test containers were removed, and exact unused/unshared unaltraweb cache IDs
+were submitted to BuildKit pruning (131.1 kB actually reclaimed). Active stdio
+containers, manual previews, images and volumes were not removed by that cleanup.
+Other concurrent Docker activity changed disk availability; its reclaimed space
+is not attributed to this preparation.

data/docs/agents/retained-letter-import.md

@@ -0,0 +1,231 @@
+# Native retained-letter import — issue 80
+
+## Scope and release state
+
+This is a separate 0.6.0 development increment after the administrative closeout
+of issue 76. Gem, wheel, runtime, MCP and PDF worker are pending. The 0.5.1 release,
+receipt and active checkout launcher pin remain unchanged. Consumer core/PDF
+integration and publication need their own reviewed immutable selections. The
+tested computation, capture and visual companion selections remain 0.4.0.
+
+The native receiver accepts Carta 0.3.0rc1 leaf `letter-pdf-v1` units. It retains
+the entire bundle, maps the original PDF byte for byte, creates a native draft
+page/chapter and checks its source and rendered references. The manual PDF
+builder includes all pages with `pdfpages`; every retained dependency and checker
+contributes to freshness. Nothing executes the retained producer recipe.
+Composite profiles, edited PDF variants and Diapora are outside this acceptance.
+
+## Protocol and provenance
+
+The wire v1 verifier and schema are byte-identical copies pinned to hub revision
+`9167e3efb5968a64bb9100792163a179c1491860` (integration
+`fc8745db950b04013c73eb49acf6781a26eb83f8`). Their respective SHA-256 values are
+`48368035f242f4d4446cbbe1363f8a01a7c17fa164ffef21abadd878b288d82d` and
+`b52a32b3bcfeed28cf34a9ec1557665a94466b51c451ccad47d2e87f6e23f9aa`.
+No envelope fields were added. `binding.json` is a separate native record.
+The integration actor identifies the importer by a hash of its code inventory,
+not an invented or uncommitted Git revision.
+
+Acceptance uses the final published
+[Carta v0.3.0rc1 packet](https://github.com/dosquartsdedocs/unaltracarta/releases/tag/v0.3.0rc1),
+revision `84258b6869689ea5f1a49a55abc2b865573fb512`:
+
+| Artifact | SHA-256 |
+| --- | --- |
+| `distribution.json` | `9d94b918db086b445e4d8a3ece2435622e0f9f9893bcd50708b4d13f5ca0ad44` |
+| `acceptance-0.3.0rc1.json` | `1bc7c467f3e35abf9fa5c27583dd8cc3ad4d4372f930c4be60ed142122158504` |
+| `acceptance-0.3.0rc1.tar.gz` | `8764a717bda33e15b48b3a06fe6fbe5dc075abedf4fd52bd37fdf4ed70896179` |
+| Published wheel | `0afab176ea0815d242f6e19021232bafdc63f9bb68cbacbd63b73f99b666b7c3` |
+| Wheel bundle manifest | `aeaa757ee1be19bfe56dc9af8dd1178032929b4a2bec2dad2ebb621b158ad999` |
+| Retained original PDF | `4a661740a18fe1cf75b84aa0d8532511fd105eb5484a5af700e11e8e30828ea4` |
+
+The original producer job was
+`.unaltracarta-handoff/jobs/a0794f7909a943eb844c87bb14002691/bundle/`.
+Its renderer identity is
+`sha256:ba2453fb42542433f68efd8888d628b95f256cefb9c545b3b35034d33296e340`.
+The installed test authenticates the packet before bounded extraction and checks
+every declared evidence file. Earlier release-candidate bytes are not inputs.
+
+## Installed acceptance
+
+`test/artifact_import_smoke.py` uses a wheel-installed CLI and Docker launcher,
+without a host factory dependency. It creates a synthetic manual, imports the
+published wheel bundle, edits surrounding prose, verifies an identical reimport
+preserves that prose and removes both the extracted producer copy and incoming
+copy. It then builds the web and PDF, checks the served page/PDF, moves the
+receiver, runs both native and generic v1 checks, and explicitly rebuilds the
+PDF in the moved receiver. Every original page must occur in order in the
+composed PDF; comparison uses the original font encoding, including ligatures.
+
+The passing local run is retained at
+`/tmp/opencode/unaltraweb-import-80/installed-proof-final/evidence.json`.
+Its receiver is `relocated-receiver/` in that directory. This is local owner
+evidence from development images, not a signed release receipt.
+
+| Tested identity | Value |
+| --- | --- |
+| Installed unaltraweb wheel SHA-256 | `407b1275d1de558da891f391454287d1b3e76fbef0e45460695e9731932b9e39` |
+| Controller image ID | `sha256:81f1da616455c7378ba3400b9d638eb8e67fce9605f18353d49a796020d9b6fa` |
+| PDF worker image ID | `sha256:b7b8f5b774a528cadb2ab7aa313b9ddbffa6d54c9d3b42bd6ff59a664be8ccf6` |
+| Integration record SHA-256 | `79ede9c8701eedf6ca4f182dc4fd1c9df3b56581138c677e0315310d8b998d1c` |
+| Composed PDF before and after relocation | `14b0ef586874704b6d1b045d6dde1f32ee08c8a9107006e06cfe2e8147f54621` |
+
+The receiver retains all 12 seal files under
+`.unaltraweb/artifacts/carta/bundle/`. Its mapping is
+`payload/output/letter.pdf` → `assets/documents/carta.pdf`, with native content at
+`_chapters/en/carta.md` and permalink `/en/retained/carta/` under `/letter-proof`.
+The original one-page letter appears on page 10 of the 11-page composed manual.
+Both web/HTTP checks passed; the non-web archive was absent from `_site`.
+Generic verification after relocation passed with one bundle, one mapping and
+14 verified files. Preview copies were cleaned through their exact receipts.
+
+Intermediate failures are retained separately: missing explicit gem plugin
+registration, an overly broad rendered-HTML scan, mismatched controller/worker
+checker bytes, and an assertion that ignored the original PDF's ligature
+encoding. Corrections preserve strict integrity/freshness gates. In particular,
+the installed-image fixture force-reinstalls its supplied wheel even when its
+development version equals the base image's version.
+
+## Reproduction and boundaries
+
+Prepare an installed wheel, the matching source-containing MCP image, and a PDF
+worker built from the repository root with `scripts/manual/Dockerfile`. The test
+controller in `test/artifact_import.Dockerfile` binds `MANUAL_PDF_IMAGE` to the
+worker image ID. Then run:
+
+```bash
+python test/artifact_import_smoke.py \
+  --packet "$PUBLISHED_CARTA_PACKET" --output "$NEW_EVIDENCE_DIRECTORY" \
+  --cli "$INSTALLED/bin/unaltraweb-mcp" \
+  --launcher "$INSTALLED/bin/unaltraweb-mcp-docker" \
+  --image "$TEST_CONTROLLER" --pdf-image "$TEST_PDF_WORKER"
+```
+
+The output directory must not exist. Only copies created by the test are retired.
+Unit-test bundles in `test/test_artifact_imports.py` are synthetic security and
+transaction fixtures, not published-producer acceptance. They cover tampering,
+incomplete resources, hidden references, symlinks/hardlinks, no-overwrite,
+interruption/retry, generated-source ownership, PDF action aliases/chains,
+rendered URL binding, native PDF inclusion and dependency closure.
+
+The imported unit is portable because its seal, record, mapped PDF and content
+all use receiver-relative paths. The integration does not depend on the incoming
+directory, producer process, absolute source location or ignored recovery tree.
+Failed publication retains prepared and partial files; there is no destructive
+rollback. Reimport adopts only identical existing bytes and preserves authored
+prose when the binding remains valid.
+
+Final release gates must additionally bind the reviewed core/PDF consumer tuple
+and same-source package/image candidates. A local acceptance run does not update
+those pins, authenticate a public 0.6.0 release, authorize real-manual adoption,
+or grant author approval to the draft content.
+
+The gem and PDF worker include a regular Python package initializer and its
+stdlib-only version/contract module. This prevents an unrelated installed wheel
+from shadowing the gem's helpers. The extracted-gem gate asserts the actual
+module paths. Checker code and schemas enter PDF freshness; the validated BOM's
+worker/self pins do not, avoiding a worker that would need to contain its own
+future digest. The integration actor separately hashes the full BOM metadata.
+
+## Owner regression gates
+
+- Python suite: 584 tests, 30 environment-dependent skips, no failures. The
+  focused importer suite covers 22 cases; the PDF builder suite covers 88.
+- Ruby plugin suites: 64 tests and 334 assertions, no failures.
+- Actual PDF toolchain integrations: 16 tests, no failures.
+- `distribution-check`, `workflow-check`, `wheel-check`, `gem-check`,
+  `mcp-check`, `mcp-smoke`, `docs-build`, and fixed-epoch
+  `reproducible-site-check` passed on local owner resources. Distribution remains
+  structurally valid and explicitly not release-ready.
+- The extracted-gem package gate exercises synthetic native retention using only
+  the gem's Python helper closure, with isolated Python and no wheel/core path.
+  Native deployment installs its parser dependencies before PDF/Jekyll checks.
+- Populated Bundler roundtrip passed for `unaltreselfie`, `unaltreprojecte`,
+  `unaltredocs` and `unaltremanual`, with two builds and a preview per runtime.
+  It first reproduces the published unpatched 0.5.0 `google-protobuf (4.36.1)`
+  failure on a separate copy, then tests 0.4.0 → development 0.6.0 → 0.4.0.
+  The historical driver labels its patched step `fixed-050`; the recorded
+  image is the 0.6.0 test controller. All six retained author/cache paths keep
+  their initial hashes; no cache cleaning is used to obtain a pass.
+
+Roundtrip evidence is retained at
+`/tmp/opencode/unaltraweb-import-80/bundler-roundtrip-final/evidence.json`, using
+the same final controller and worker IDs as the installed letter acceptance.
+The source discovery descriptor additionally declares `.unaltraweb/artifacts`
+as optional versioned source state with `cleanup: never`; `tmp` keeps its existing
+ignored, explicit-cleanup policy. This final metadata-only addition is checked by
+the path-policy and fresh-wheel gates and does not alter the tested import code.
+
+## Closeout review — 2026-10-02
+
+The owner explicitly authorized the full 0.6.0 commit/PR/integration, signed
+candidate, gated publication and post-release pin flow. The session preflight
+reported only the known unit-80 working tree and no competing session. Review
+covered every tracked/untracked unit path; no unrelated changes were identified.
+
+The two vendored protocol files match the exact established Git pin. The pinned
+reference tests and fixture payloads were also checked (the later fixture README
+only renames the integrated contract), and all 26 conformance tests pass. These
+generic synthetic tests do not add a composite domain to the native importer.
+The retained installed wheel/PDF hashes above and the moved receiver's native
+web/PDF mapping were independently rechecked before editing.
+
+Resolved review findings:
+
+- Metadata could contain a local link or image while retained Pandoc evidence
+  remained stale. Renderable metadata now receives the independent text-reference
+  check; effective metadata rejects render-option fields outside the supported
+  author/stamp projection. Malformed Pandoc link evidence returns a structured
+  domain failure instead of an uncaught indexing error.
+- A PDF OpenAction internal destination array was treated as an action array.
+  Internal destinations are supported while chained action arrays retain their
+  stricter checks. Regression tests cover both cases.
+- The acceptance driver required a derived test-controller image. It now also
+  verifies the immutable PDF selection declared by the actual installed MCP image
+  and records the exact image references and source label, allowing signed bytes
+  to be exercised directly.
+
+The corrected source passes 587 Python tests (30 optional skips), including 25
+native import cases, plus distribution/workflow/fresh-wheel gates. The historical
+local evidence above remains retained; signed-candidate and public-download
+acceptance must record their own revisions and hashes. The consumer core/PDF
+tuple is closed only after the reviewed integrated core and signed PDF digest
+exist; no guessed source or self-digest is inserted into the BOM.
+
+## Reviewed immutable consumer tuple
+
+PR [81](https://github.com/dosquartsdedocs/unaltraweb/pull/81) integrated reviewed
+implementation `7af652fb83629e959af05c407a34a2f5a15f7936` as
+`5cf9817489c8dc47cee726bfe42fe3071cd32b85`. Protected PR CI
+[37027921742](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37027921742)
+and CodeQL [37027922332](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37027922332)
+passed, followed by integrated-source CI
+[37028677932](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37028677932)
+and CodeQL [37028678347](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37028678347).
+The PR contains an explicit agent review, not an attributed human approval.
+
+Signed image workflow
+[37029374441](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/37029374441)
+then published, attested and tested the PDF from that exact source. Its read-only
+test job verified the signer workflow/source digest before executing the exact
+image, including 16 PDF integrations and real MCP preparation. The selected
+PDF 0.6.0 identity is
+`ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:0ba267cb87f53ebaca4e31805fe00610cd61fdf97a8d2c3692f4655700dceaed`.
+The BOM and Make contract now select that same digest and integrated core SHA.
+
+That public signed PDF is recorded as `released` and reused by digest. The four
+core/package components are `ready` for final same-commit candidates; their strict
+gate still requires a new receipt-only child of the final artifact source.
+Subsequent verification-only PDF builds are not substituted for this selected
+worker or promoted under an assumed identity. The earlier 0.5.1 receipt and
+active launcher pin remain intact until the authorized 0.6.0 closeout completes.
+
+The tuple was exercised before its pin PR using an installed wheel and a local
+MCP containing the new BOM with the actual signed PDF above. Evidence is retained
+at `/tmp/opencode/unaltraweb-closeout-060/tuple-letter-proof/evidence.json`:
+integration `ebe07ee10ad740a2bbbd36d532f336374cf4bb19ccb373b6590b2279f664a222`,
+composed PDF `416e96f66bb6608b1e20bf5e36b6b16133bd4018c17e6c079e8987b736fe9cae`
+both before and after the forced relocated rebuild. The PDF's inspected local
+image ID is `sha256:d7e7d3243616270fc9e6eed7f8238c412dbe3d9ffc18d2832d17d66ca630d139`,
+with the exact integrated source revision label. This preparation proof does not
+substitute for the final signed MCP and downloaded package acceptance.

data/docs/agents/visual-companions-0.4.0.md

@@ -1,6 +1,11 @@
 # Published visual companions: native acceptance and release handoff
 
 Tracking: [issue 67](https://github.com/dosquartsdedocs/unaltraweb/issues/67).
+Publication update: the acceptance is included in
+[unaltraweb v0.5.0](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.5.0),
+receipt `3fa855378dcc61dc7b84b8b03812698042e02fed`, and the post-release launcher
+selects MCP digest `36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98`.
+The preparation notes and original 0.4.0 image below retain their historical context.
 Owner branch: `fix/67-published-visual-companions`, based on
 `bfabaa2738ddd24725f5e386d60b58a9a8294316` after an eligible primary-checkout
 preflight. This is next-release source, not a replacement for published core 0.4.0.

data/lib/unaltraweb.rb

@@ -21,6 +21,7 @@ require_relative "unaltraweb/version"
   content_search_index
   manual_release_metadata
   reproducible_build_time
+  retained_documents
   profile-pages
   remove-accents
   search-data

data/requirements.txt

@@ -3,3 +3,5 @@ scholarly
 requests
 bibtexparser
 rdata
+pypdf>=6,<7
+markdown-it-py>=3,<5

data/scripts/manual/Dockerfile

@@ -23,9 +23,12 @@ RUN printf '%s\n' \
     && rm -rf /var/lib/apt/lists/* \
     && pip install --no-cache-dir PyYAML==6.0.2
 
-COPY build_pdf.py /opt/unaltraweb/manual/build_pdf.py
-COPY Dockerfile /opt/unaltraweb/manual/Dockerfile
-COPY filters /opt/unaltraweb/manual/filters
-COPY templates /opt/unaltraweb/manual/templates
+RUN pip install --no-cache-dir 'pypdf>=6,<7' 'markdown-it-py>=3,<5'
+COPY scripts/manual/build_pdf.py /opt/unaltraweb/manual/build_pdf.py
+COPY scripts/manual/Dockerfile /opt/unaltraweb/manual/Dockerfile
+COPY scripts/manual/filters /opt/unaltraweb/manual/filters
+COPY scripts/manual/templates /opt/unaltraweb/manual/templates
+COPY src/unaltraweb_mcp/__init__.py src/unaltraweb_mcp/distribution.py src/unaltraweb_mcp/component-contract.json src/unaltraweb_mcp/component-contract.schema.json src/unaltraweb_mcp/artifact_handoff_v1.py src/unaltraweb_mcp/artifact-handoff-v1.schema.json src/unaltraweb_mcp/artifact_imports.py src/unaltraweb_mcp/letter_bundle.py src/unaltraweb_mcp/pdf_probe.py src/unaltraweb_mcp/processes.py /opt/unaltraweb/src/unaltraweb_mcp/
+ENV PYTHONPATH=/opt/unaltraweb/src
 
 ENTRYPOINT ["python3", "/opt/unaltraweb/manual/build_pdf.py"]

data/scripts/manual/build_pdf.py

@@ -26,6 +26,10 @@ except ImportError as exc:  # pragma: no cover - supplied by the builder image
 
 
 SCRIPT_ROOT = Path(__file__).resolve().parent
+for _source_root in (SCRIPT_ROOT.parent.parent / "src", SCRIPT_ROOT.parent / "src"):
+    if (_source_root / "unaltraweb_mcp" / "artifact_imports.py").is_file():
+        sys.path.insert(0, str(_source_root))
+        break
 DEFAULT_DOCKERFILE = SCRIPT_ROOT / "Dockerfile"
 DEFAULT_TEMPLATE = SCRIPT_ROOT / "templates" / "manual.tex"
 DEFAULT_BIBLIOGRAPHY_FILTER = SCRIPT_ROOT / "filters" / "bibliography.lua"
@@ -36,6 +40,7 @@ BIB_CUSTOM_URL_RE = re.compile(r'(?im)^\s*(?:manual_url|website)\s*=\s*(?:\{([^}
 FRONT_MATTER_RE = re.compile(r"\A---[ \t]*\r?\n(.*?)^---[ \t]*(?:\r?\n|\Z)", re.MULTILINE | re.DOTALL)
 CITE_RE = re.compile(r"{%\s*cite\s+([^%]+?)\s*%}")
 INCLUDE_RE = re.compile(r"{%\s*include\s+([^%]+?)\s*%}")
+RETAINED_DOCUMENT_RE = re.compile(r"{%\s*retained_document\s+([a-z][a-z0-9-]{0,63})\s*%}")
 LIQUID_RE = re.compile(r"({[{%].*?[}%]})", re.DOTALL)
 INLINE_CODE_RE = re.compile(r"<code>(.*?)</code>", re.IGNORECASE | re.DOTALL)
 FENCED_CODE_BLOCK_RE = re.compile(r"^[ \t]*(`{3,}|~{3,})[^\n]*\n.*?^[ \t]*\1[ \t]*$", re.MULTILINE | re.DOTALL)
@@ -947,6 +952,17 @@ def transform_markdown(
             citation_keys.extend(key for key in keys if key not in citation_keys)
         return "[" + "; ".join(f"@{key}" for key in keys) + "]"
 
+    def retained_document(match: re.Match[str]) -> str:
+        from unaltraweb_mcp.artifact_imports import check_imports
+
+        result = check_imports(project, match.group(1))
+        if result.get("ok") is not True:
+            raise ManualPdfError(f"Retained document verification failed: {result.get('error')}")
+        path = result["imports"][0]["pdf"]
+        # The native import layout uses an ASCII slug and fixed project-relative
+        # path; no bundle text is interpolated into TeX or executed.
+        return protect("```{=latex}\n\\includepdf[pages=-,pagecommand={}]" + "{" + path + "}\n```")
+
     def table(match: re.Match[str]) -> str:
         body = match.group("body").strip()
         credit, _ = caption_source_attribute(match.group("attrs") or "")
@@ -1137,6 +1153,7 @@ def transform_markdown(
     transformed = transformed.replace(r"\begin{equation\*}", r"\begin{equation*}")
     transformed = transformed.replace(r"\end{equation\*}", r"\end{equation*}")
     transformed = BASEURL_RE.sub("", transformed)
+    transformed = RETAINED_DOCUMENT_RE.sub(retained_document, transformed)
     transformed = transformed.replace("{% include manual-bibliography.liquid %}", "::: {#refs}\n:::")
     transformed = CITE_RE.sub(citations, transformed)
     transformed = CALLOUT_BLOCK_RE.sub(callout, transformed)
@@ -1481,6 +1498,17 @@ def build_dependencies(project: Path, metadata: dict[str, Any], source_paths: li
     ]
     for path in source_paths:
         dependencies.append((f"source:{path.relative_to(project)}", path))
+    if any(RETAINED_DOCUMENT_RE.search(path.read_text(encoding="utf-8")) for path in source_paths if path.suffix.lower() == ".md"):
+        from unaltraweb_mcp import artifact_imports
+
+        imports = artifact_imports.check_imports(project)
+        if imports.get("ok") is not True:
+            raise ManualPdfError(f"Retained document verification failed: {imports.get('error')}")
+        for item in imports["imports"]:
+            dependencies.extend((f"retained:{relative}", project / relative) for relative in item["inputs"])
+        checker_root = Path(artifact_imports.__file__).parent
+        for name in artifact_imports.CHECKER_FILES:
+            dependencies.append((f"import-check:{name}", checker_root / name))
     if csl:
         dependencies.append((f"csl:{csl.relative_to(project)}", csl))
     for key in ["cover-image", "cover-logo", "series-logo"]:

data/scripts/manual/templates/manual.tex

@@ -10,6 +10,7 @@
 \usepackage{float}
 \usepackage{framed}
 \usepackage{graphicx}
+\usepackage{pdfpages}
 \usepackage{grffile}
 \usepackage{longtable}
 \usepackage{array}