unaltraweb 0.4.0 → 0.5.0

data/docs/_documentation/en/26-image-backgrounds.md

@@ -0,0 +1,103 @@
+---
+title: Check Image Backgrounds
+description: Read-only transparency warnings for raster images and self-contained SVG figures.
+lang: en
+ref: image_backgrounds
+profiles: [unaltredocs]
+documentation_profiles: [local-authors, site-designers, contributors, core-developers]
+section: Design And Customize
+weight: 318
+permalink: "/image-backgrounds/"
+nav_title: Image Backgrounds
+---
+
+Publication images should have an opaque background chosen for their content.
+Any opaque colour is valid. A transparent PNG can be just as difficult to read
+as a transparent SVG when enlarged over the website, so the check examines image
+content rather than assuming that one filename extension is safe.
+
+`image_background_check` is an **advisory**. It reports transparent and
+unverifiable images, without modifying files, painting them white, changing
+their dimensions or turning a style warning into a publication failure.
+
+## What Is Checked
+
+- PNG, including palette and RGB `tRNS` transparency, and supported JPEG, GIF,
+  WebP, BMP, TIFF and AVIF images are decoded with Pillow. A PNG with an alpha
+  channel whose values are all fully opaque passes the check.
+- Animated raster images are inspected frame by frame within a fixed budget.
+  A transparent frame is reported even if the first frame is opaque.
+- Self-contained SVG and SVGZ images are rasterised with CairoSVG into a bounded
+  viewport, with no supplied background colour. This samples the asset's own
+  background; a CSS background behind the image in the page does not count.
+- SVG embedded PNG/JPEG captures are supported. External resource loading is
+  disabled. Dynamic SVG, masks, filters and unsupported resources are reported
+  as unverifiable rather than assumed opaque.
+
+SVG inspection is a raster sample at a maximum side of 1536 pixels, not proof of
+opacity at every possible scale or under every SVG renderer. Raster inspection
+allows up to 16 megapixels per frame, 32 frames and 64 million frame-pixels in
+total. Files are limited to 32 MiB (8 MiB of SVG text), with a bounded project
+batch, decoder CPU/memory limits and timeouts. Oversized, malformed, missing or
+unsupported images produce explicit diagnostics.
+
+## Source And Rendered Views
+
+The default check inspects image references in published Markdown/HTML source,
+public image metadata and configured content collections. Code examples and
+comments are skipped. The source resolver follows the declared output of
+computation, capture, Mermaid/PlantUML and Vega references, prefers the supported
+author-edited override, and selects maintained language variants using the
+normal default-language fallback.
+
+The rendered-output check inspects HTML image references, including `srcset`,
+posters and icon links. It catches assets contributed by layouts or metadata
+that a static source projection cannot resolve. Remote, data-URL and
+fragment-selected references are not fetched or silently certified; inspect a
+local, self-contained output or review the exact rendered view.
+
+Findings identify the image path and referring document, include the inspected
+file hash when available, and name the authoritative source for generated
+figures. Repeated references to one asset are grouped.
+
+## Commands And MCP
+
+These consumer commands are available from the modular wheel:
+
+```bash
+unaltraweb-mcp --project /path/to/site mcp image-background-check
+unaltraweb-mcp --project /path/to/site mcp image-background-check --source assets/img/map.svg
+unaltraweb-mcp --project /path/to/site mcp image-background-check --source _chapters/en/maps.md
+unaltraweb-mcp --project /path/to/site mcp image-background-check --output-folder _site
+```
+
+The MCP tool is `image_background_check`, and the source report is also available
+at `web://image-backgrounds`. `site_check` includes the source check;
+`html_audit` adds the rendered check; the MCP PDF build returns source-image
+advisories. CLI checks print image warnings to stderr, so the package scaffold's
+normal build still surfaces them when its JSON output is redirected.
+
+The reusable deployment workflow runs the packaged native checker before build
+and against the output folder before upload. A native gem installation can use:
+
+```bash
+python /path/to/unaltraweb/scripts/image_background_check.py --project /path/to/site --output-folder _site
+```
+
+The checker requires Pillow, CairoSVG and the system Cairo library. The MCP image
+and native deployment workflow install them. A missing decoder is reported as
+unverifiable. A completed check with transparency warnings exits successfully;
+an invalid inspection request or source inventory returns a nonzero exit status.
+
+## Fixing A Warning
+
+Choose a background colour in the authoritative source or export settings. For
+example, Matplotlib exports can set `facecolor` and `transparent=False`, and
+`ggsave` can set `bg`. An SVG can use an opaque full-viewport background shape
+behind its artwork. Check the chosen text/background contrast on web and PDF.
+
+Keep the decision with the author: opaque white is one choice, not a forced
+default. Regenerate renderer-owned assets through their factory. Review an
+existing `.edited.svg` or unmanaged image before changing it, and preserve
+original captures and source material. The background check does not establish
+generation freshness, attribution or permission to replace an asset.

data/docs/_documentation/en/31-template.md

@@ -21,7 +21,7 @@ nav_title: Core And Template
 - It consumes `unaltraweb` as an external dependency.
 - It contains realistic demo content for `unaltreselfie`, `unaltreprojecte`, `unaltremanual` and `unaltredocs` profiles.
 - It exercises richer local Docker and browser-test orchestration than the clean package scaffolds.
-- The currently published fixture uses `ghcr.io/dosquartsdedocs/unaltraweb:0.3.0`; it should align with the `0.4.0` candidate only after coordinated publication, and mutable `main` remains reserved for maintainer testing.
+- The currently published fixture uses `ghcr.io/dosquartsdedocs/unaltraweb:0.3.0`; coordinated `v0.4.0` is now public, so the fixture can align in a separate reviewed change, while mutable `main` remains reserved for maintainer testing.
 - It runs Playwright smoke tests and screenshots across profiles, themes and responsive layouts.
 - It keeps rich demo content out of clean profile scaffolds.
 

data/docs/_documentation/en/32-development.md

@@ -65,7 +65,7 @@ docker compose -f docker-compose.yml down --remove-orphans
 
 This can be resource-heavy because the inherited demo build minifies JavaScript and can generate many responsive WebP images.
 
-The currently public base Dockerfile image is `ghcr.io/dosquartsdedocs/unaltraweb:0.3.0`. Published generated consumers select the higher-level `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.3.0`, which adds the reviewed core and Python control plane. The `v0.4.0` candidate checkout selects matching `0.4.0` images, but downstream consumers must remain on `v0.3.0` until coordinated publication completes. Their Make targets use `/opt/unaltraweb` as a path gem; the RubyGems package remains the optional native Bundler channel. ContExt prepares the full post-release `MCP_RELEASE_IMAGE` digest with `mcp-build`, while `mcp-image`, `mcp-check` and `mcp-smoke` reserve local `:dev` names for source testing. Mutable `:main` channels remain explicit maintainer paths.
+The currently public base Dockerfile image is `ghcr.io/dosquartsdedocs/unaltraweb:0.4.0`. Published generated consumers select the higher-level `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0`, which adds the reviewed core and Python control plane. Their Make targets use `/opt/unaltraweb` as a path gem; the RubyGems package remains the optional native Bundler channel. gContExt prepares the full post-release `MCP_RELEASE_IMAGE` digest with `mcp-build`, while `mcp-image`, `mcp-check` and `mcp-smoke` reserve local `:dev` names for source testing. Mutable `:main` channels remain explicit maintainer paths.
 
 The root core build excludes `docs/`. The reference site is published from the `docs/` folder through a dedicated workflow so its root-relative permalinks do not collide with the inherited core demo build.
 

data/docs/_documentation/en/40-distribution.md

@@ -25,17 +25,37 @@ The template is the better place to validate gem consumption, centralized styles
 
 ## Component Contract
 
+### 0.5.0 release preparation
+
+The next coordinated core release is **0.5.0**. It groups the integrated editorial
+review, guided scaffold updates, caption-credit/image behavior and published
+Diavisuals/Vegavisuals 0.4.0 acceptance. Package, core/MCP and manual PDF candidates
+are verified through the existing source-bound workflows before publication.
+Unchanged already-published computation and web-capture workers retain their own
+0.4.0 versions and digests. New/pending worker candidates must still match the
+coordinated release; an old mutable alias cannot qualify for reuse. The selected
+consumer tuple must use a reviewed 0.5.0 core revision and tested PDF worker.
+The PDF worker passed the
+[signed candidate workflow](https://github.com/dosquartsdedocs/unaltraweb/actions/runs/36272762057)
+at source `d857f8c9f5fea90cf450c0b30b4e77a37b541275` and is selected by digest
+`sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097` in
+both the factory and the consumer tuple. It is already published and tested, so
+final candidate receipts cover the remaining ready package/core components.
+The factory launcher remains on its previous published image until the normal
+post-release pin update. Follow [issue 69](https://github.com/dosquartsdedocs/unaltraweb/issues/69)
+for the candidate, receipt, tag and package evidence.
+
 `src/unaltraweb_mcp/component-contract.json` is the canonical versioned bill of materials. Its `consumer_integration` object is the sole source for the reviewed core Git revision, reusable deploy workflow, manual PDF image digest, and Vega renderer revision. Scaffold templates render that tuple atomically into consumer `Gemfile`, `Gemfile.lock`, and deploy workflow files. `component-contract.schema.json` defines schema version 1. Runtime loading and `scripts/validate_distribution.py` validate the complete document against that schema, then enforce semantic parity between versions, release tags, repositories, references, wheel contents, CLI availability, and consumer integration pins.
 
 The BOM is an interoperability contract, not a bundle. The wheel contains only its Python control/inspection modules, schema/BOM, and clean package-owned scaffolds. In particular it does not contain Ruby theme assets, Docker image layers, factory Make/scripts/docs, TeX, Chromium, computation environments, `diavisuals`, or `vegavisuals`.
 
-The selected candidate release is `0.4.0`; `v0.3.0` remains the public distribution until coordinated publication finishes. The BOM reuses immutable compute and web-capture worker digests and selects the published `diavisuals v0.3.1` and `vegavisuals v0.3.1` releases. Current checkouts can be used through `suggested_path`, while immutable release references remain the distribution contract. `distribution-check` validates structural integrity for normal CI. `distribution-release-check` blocks coordinated publication while any component is `pending` or `unavailable`; reviewed source authorized to produce the final same-commit candidates is `ready`, while an already-published component is `released`.
+The selected public core release is `0.4.0`; `v0.3.0` remains the immutable previous distribution. The next-release source BOM reuses immutable compute and web-capture worker digests and selects published `diavisuals v0.4.0` and `vegavisuals v0.4.0` through SHA-256-pinned wheel URLs. Companion references can describe either a provider/release-matching Git reference or a provider/release/version-matching wheel with its content hash. The wheel boundary remains external. The scaffold's Vega revision is the published `68c0b231402ae9485cc34ce530dc5239cb0ec194` commit. These source changes require a new coordinated core release; they do not alter the already published `0.4.0` artifacts or the factory's `MCP_RELEASE_IMAGE` digest. `distribution-check` validates structural integrity for normal CI. `distribution-release-check` blocks coordinated publication while any component is `pending` or `unavailable`; reviewed source authorized to produce the final same-commit candidates is `ready`, while an already-published component is `released`.
 
 ## Docker-First Hybrid Policy
 
-GHCR is the canonical delivery channel for normal local use. The candidate package scaffold selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0`, which must not be adopted by consumers until coordinated publication completes; published `v0.3.0` sites remain supported during preparation. Its `make build`, `make serve` and `make test` targets mount the thin child site and run inside that image. The image contains both the installed Python control plane and the reviewed factory source at `/opt/unaltraweb`, so those targets load the theme as a path gem without downloading PyPI or RubyGems packages.
+GHCR is the canonical delivery channel for normal local use. The released package scaffold selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0`; existing `v0.3.0` sites can remain on their immutable previous release until deliberately updated. Its `make build`, `make serve` and `make test` targets mount the thin child site and run inside that image. The image contains both the installed Python control plane and the reviewed factory source at `/opt/unaltraweb`, so those targets load the theme as a path gem without downloading PyPI or RubyGems packages.
 
-Factory registration uses a stricter pin. ContExt runs `mcp-build`, which inspects or pulls the full `MCP_RELEASE_IMAGE` digest, and `mcp-stdio` launches that exact image. Checkout builds use local `:dev` names by default through `mcp-image`, `mcp-check` and `mcp-smoke`, so they do not shadow public semver references unless a maintainer explicitly overrides them. The digest is advanced in a separate post-release change after each new receipt exists; candidate source continues to select the last completed release instead of attempting to embed an unknown self-digest.
+Factory registration uses a stricter pin. gContExt runs `mcp-build`, which inspects or pulls the full `MCP_RELEASE_IMAGE` digest, and `mcp-stdio` launches that exact image. Checkout builds use local `:dev` names by default through `mcp-image`, `mcp-check` and `mcp-smoke`, so they do not shadow public semver references unless a maintainer explicitly overrides them. The digest is advanced in a separate post-release change after each new receipt exists; candidate source continues to select the last completed release instead of attempting to embed an unknown self-digest.
 
 The distribution keeps native channels for interoperability rather than making them Docker prerequisites:
 
@@ -115,11 +135,11 @@ For that reason:
 - normal local-runtime improvements should ship through a versioned MCP image; native consumers receive corresponding gem or wheel releases when their package boundary changes;
 - site repositories can enable Dependabot for Bundler and GitHub Actions, but deploy workflows should remain manual;
 - breaking changes should be released with migration notes;
-- scaffold changes should be rare; generated sites can explicitly dry-run `scaffold_sync`, which updates only unchanged baseline runtime files (including the pull-request template), creates newly managed missing files, reports conflicts, never deletes paths, stages every output, rechecks adopted and unchanged files around the manifest write, rolls the whole transaction back on failure, and commits its manifest last. Generated README prose is site-owned and is not overwritten by synchronization.
+- scaffold changes should be rare; generated sites can explicitly dry-run `scaffold_sync`, which updates unchanged baseline runtime files (including the pull-request template), creates newly managed missing files, and preserves local edits when the upstream file still equals its original baseline. Conflicting local/upstream edits remain blocked. The transaction never deletes paths, stages every output, rechecks adopted, unchanged and preserved files around the manifest write, rolls back on failure, and commits its manifest last. `site_context.update_status` guides the agent's version/update offer; `expected_plan_sha256` binds confirmation to the reviewed proposal. Generated README prose is site-owned and is not overwritten by synchronization.
 
 ## Docker Runtime
 
-Release `0.3.0` publishes the selected base runtime, MCP runtime and specialized workers. Local maintainers continue to use explicit development names such as `unaltraweb:dev`; generated sites select the reviewed semver MCP image rather than `main` or `latest`.
+Release `0.4.0` publishes the selected base runtime, MCP runtime and specialized workers. Local maintainers continue to use explicit development names such as `unaltraweb:dev`; generated sites select the reviewed semver MCP image rather than `main` or `latest`.
 
 The base runtime owns Ruby, Jekyll and system dependencies. The MCP image builds on its exact candidate digest and adds the full reviewed factory plus the Python package. Specialized workers remain separate. This keeps each layer focused without adding Chromium, TeX or computation stacks to every site; the coordinated core-image workflow still rebuilds and verifies runtime, MCP and manual PDF candidates together.
 

data/docs/_documentation/en/42-docker-image.md

@@ -13,23 +13,23 @@ weight: 140
 permalink: "/docker-image/"
 nav_title: Docker Images
 ---
-Release `v0.3.0` currently publishes two core images. Published generated sites select the self-contained MCP/site image for normal local commands:
+Release `v0.4.0` currently publishes two core images. Published generated sites select the self-contained MCP/site image for normal local commands:
 
 ```text
-ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.3.0
+ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0
 ```
 
 It contains the Python control plane and the reviewed factory at `/opt/unaltraweb`. Its lower-level base is:
 
 ```text
-ghcr.io/dosquartsdedocs/unaltraweb:0.3.0
+ghcr.io/dosquartsdedocs/unaltraweb:0.4.0
 ```
 
 The base provides Ruby, Bundler, Jekyll system dependencies, ImageMagick, Node for ExecJS and Python tooling. Generated Make targets run in the MCP image and load layouts, styles and plugins as a path gem from `/opt/unaltraweb`. RubyGems remains an optional native Bundler channel rather than a download required by the local Docker path.
 
-The `v0.4.0` candidate source selects matching `unaltraweb:0.4.0` and `unaltraweb-mcp:0.4.0` references. Those tags remain candidate intent, not public installation instructions, until the coordinated receipt, tag, and promotion sequence completes.
+The `v0.4.0` receipt binds matching `unaltraweb:0.4.0` and `unaltraweb-mcp:0.4.0` references to their tested immutable digests. The semver aliases were promoted only after the coordinated receipt and tag checks completed.
 
-ContExt prepares and launches the MCP image through the full digest in `MCP_RELEASE_IMAGE`. That post-release pin is separate from the semver scaffold reference and cannot be shadowed by checkout builds, which use local `:dev` names. A new release advances the pin only after its receipt records the published digest.
+gContExt prepares and launches the MCP image through the full digest in `MCP_RELEASE_IMAGE`. That post-release pin is separate from the semver scaffold reference and cannot be shadowed by checkout builds, which use local `:dev` names. A new release advances the pin only after its receipt records the published digest.
 
 The GHCR package is kept because it makes the local Docker workflow cheap and repeatable. Publishing is manual. Its unprivileged `preflight` job performs package and source checks without a registry login or Docker build. A default-branch run then crosses three separate credential boundaries:
 
@@ -58,7 +58,7 @@ make mcp-image
 make mcp-smoke-prebuilt MCP_IMAGE=unaltraweb-mcp:dev
 ```
 
-Both core GHCR packages are public, and unauthenticated `v0.3.0` pulls have been verified.
+Both core GHCR packages are public, and unauthenticated `v0.4.0` pulls have been verified.
 
 ## Computation Images
 
@@ -190,6 +190,6 @@ ghcr.io/dosquartsdedocs/unaltraweb-web-capture@sha256:0bf1bc67fe63e1440bffe708a1
 
 The `v0.4.0` contract reuses this already-published worker by immutable digest. The image contains pinned Playwright/Chromium, the capture worker, the Python status controller, and the core visual sources used in fingerprints. `make web-capture-image` builds the explicitly named `unaltraweb-web-capture:dev` maintainer image; set `WEB_CAPTURE_IMAGE` to that name when testing it. The manual `Web capture image` workflow publishes default-branch, commit, and semver/release tags to GHCR.
 
-Published `v0.3.0` sites consume `ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf:0.3.0`. The candidate source selects `ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf:0.4.0`, which must not be adopted until coordinated publication. `manual-pdf-image` reuses or pulls the selected image instead of rebuilding it locally. Maintainers use `make manual-pdf-image-dev` and then pass `MANUAL_PDF_IMAGE=unaltraweb-manual-pdf:dev` for local PDF runtime changes.
+Published `v0.4.0` sites consume `ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf:0.4.0`. `manual-pdf-image` reuses or pulls the selected image instead of rebuilding it locally. Maintainers use `make manual-pdf-image-dev` and then pass `MANUAL_PDF_IMAGE=unaltraweb-manual-pdf:dev` for local PDF runtime changes.
 
 Rendering creates an ephemeral Docker `--internal` network shared only by Jekyll and Chromium, keeps browser requests on the preview origin, blocks service workers, popups, and WebSockets, drops Linux capabilities, uses a read-only container root and bounded resources, and writes only the declared PNG/SVG outputs under the mounted project. Ordinary checks run without browser execution or network access.

data/docs/_documentation/en/43-workspace-path-policies.md

@@ -0,0 +1,232 @@
+---
+title: Workspace Path Policies And Consumer Updates
+description: File ownership, Git expectations, PDF recovery and safe consumer migration.
+lang: en
+ref: workspace_path_policies
+profiles:
+- unaltredocs
+documentation_profiles:
+- core-developers
+section: Core Development
+weight: 625
+permalink: "/workspace-path-policies/"
+nav_title: Workspace Path Policies
+---
+
+The discovery manifest `mcp-factory.yml` declares literal consumer-relative
+`workspace_rule.path_policies`, under schema version 1, `binding: consumer` and
+`consumer_root: .`. The central `my-scripts-factory` manager checks these policies
+without launching a provider. `MCP_CONSUMER_WORKSPACE` still carries the absolute
+consumer workspace through the `make -C` stdio launcher; the factory checkout
+does not become the consumer.
+
+## Policy Meaning
+
+- `git: ignored` requires actual Git ignore coverage, including inherited parent
+  rules, and rejects indexed files anywhere under that path. Merely adding an
+  ignore rule does not untrack files.
+- `git: versioned` permits an absent path. An existing path must be indexed and
+  not ignored. Stage reviewed source files before checking a freshly created site.
+- `git: consumer` reports the observed Git state without imposing a decision.
+- `cleanup: disposable`, `explicit` and `never` are descriptive metadata, not
+  deletion authority. `workspace-check` never performs cleanup. `down` manages
+  labelled runtime resources, not the consumer filesystem.
+
+Missing optional paths do not enable a feature or create files. An absent ignored
+directory still needs an ignore rule; a trailing-slash rule works before that
+directory exists. In a non-Git directory the manager reports `not_applicable`,
+which is not evidence that a future Git repository is compliant.
+
+## Adopted Literal Paths
+
+| Path | Type | Role | Git | Cleanup |
+| --- | --- | --- | --- | --- |
+| `_site` | directory | jekyll-build-output | ignored | disposable |
+| `tmp` | directory | build-staging-and-local-release-evidence | ignored | explicit |
+| `.cache/scimago` | directory | external-bibliometrics-input-cache | ignored | explicit |
+| `.cache/unaltraweb/manual-pdf-publication-intent.json` | file | pdf-publication-recovery-intent | ignored | explicit |
+| `.cache/unaltraweb/manual-pdf-publication.json` | file | pdf-publication-provenance | ignored | explicit |
+| `.cache/unaltraweb/manual-pdf-preview.json` | file | pdf-preview-ownership-receipt | ignored | explicit |
+| `.cache/unaltraweb/manual-pdf-preview.lock` | file | pdf-preview-coordination-lock | ignored | explicit |
+| `.cache/unaltraweb/manual-pdf-preview-recovery` | directory | pdf-preview-retained-recovery-backups | ignored | explicit |
+| `_config.yml` | file | consumer-site-configuration | versioned | never |
+| `.unaltraweb/scaffold.json` | file | managed-scaffold-baseline | versioned | never |
+| `.unaltraweb/docker-mount.sh` | file | managed-docker-mount-helper | versioned | never |
+| `.unaltraweb/computations.yml` | file | optional-consumer-computation-configuration | versioned | never |
+| `.unaltraweb/computations.lock.json` | file | computation-output-provenance | consumer | explicit |
+
+`_site` is the normal Jekyll output and can be rebuilt from retained sources,
+inputs and runtimes. It is not the authoritative copy of editorial assets. This
+does not promise byte-identical rebuilds after external inputs or runtimes change,
+nor extend the policy to a custom Jekyll destination. Removing `_site` invalidates
+any site-build evidence that refers to its previous contents.
+
+`tmp` mixes Bundler files, render staging and locks, draft PDFs, the site-build
+receipt (`tmp/.unaltraweb/site-build.json`) and local release candidates
+(`tmp/manual-release`). A candidate may be the only retained record of reviewed
+bytes. Review and preserve evidence and finish active operations before deliberate
+cleanup; the entire tree is not unconditionally regenerable. The existing
+consumer `make clean` is a separate explicit operation and refuses to discard
+drafts while a preview receipt remains.
+
+Scimago is downloaded from a mutable upstream URL or supplied as a local input.
+Deleting `.cache/scimago` can lose the exact dataset used for bibliometrics. The
+cache's default path is fixed, but scripts can select another input/output path;
+this declaration does not cover such alternatives. Preserve the needed bytes and
+provenance before cleanup. Normal builds do not fetch metrics.
+
+`_config.yml` is consumer-owned. The scaffold baseline and Docker mount helper
+are package-managed controls; the baseline is essential to distinguish package
+updates from local edits. Computation configuration is created only for the
+manual profile and stays consumer-owned so it can declare project inputs and
+worker extensions. Its lock records output hashes, source fingerprints and image
+identity; it is generated metadata, not a disposable execution lock. Consumers
+usually version it with generated Markdown/figures, but this rollout does not
+force that choice.
+
+## PDF Recovery Is Not Disposable Cache
+
+`src/unaltraweb_mcp/manual_pdf_preview.py` owns the five fixed PDF-state paths:
+
+1. Publication intent records expected hashes before a confirmed copy, allowing
+   interrupted publication to be reconciled even if draft artefacts disappear.
+2. Publication provenance records the identity of deployment products without
+   granting preview cleanup ownership over those products.
+3. The preview receipt records exactly which ignored, untracked copies the
+   preview operation owns. Cleanup requires a dry-run, explicit confirmation and
+   that receipt's SHA-256, then rechecks identity, hashes, modes and Git state.
+4. The visible lock and an advisory lock on the project directory coordinate
+   operations. Removing the lock marker is not an unlock or recovery procedure.
+5. Recovery backups preserve originals or concurrent edits when rollback cannot
+   safely restore them. Failures can also report retained backups beside an
+   output; those configurable locations are not covered by a broad asset policy.
+
+Keep receipts, recovery files and their corresponding outputs together until the
+owning operation is reconciled. Use `manual_pdf_preview_clean` for unchanged
+receipt-owned copies, and inspect reported recovery paths when automatic recovery
+fails. Never delete receipts to make an unmanaged collision disappear. This
+adoption does not change confirmation, no-clobber, locking or rollback behavior.
+
+## Provider And Editorial Boundaries
+
+The installable dependency closure is `diavisuals`, `vegavisuals`, `unaltraweb`:
+`factory_count: 3`, `dependency_factory_count: 2`. Each manifest keeps its own
+binding and root. Unaltraweb does not redeclare these provider policies:
+
+- Diavisuals owns `.cache/diavisuals` (ignored/disposable) and
+  `.unaltraweb/receipts/diavisuals.json` (consumer/explicit).
+- Vegavisuals owns `.cache/vegavisuals` (ignored/explicit, including publication
+  recovery), `.vegavisuals.yml` (versioned/never), `.vegavisuals.lock.json` and
+  `.unaltraweb/receipts/vegavisuals.json` (both consumer/explicit).
+
+Receipts prove freshness; their presence in `generated_paths` does not imply
+ignored or disposable state. `site_check` still validates their contents when
+sources require them. Workspace compliance does not establish rendering freshness.
+
+The initial selection deliberately leaves these paths without new policies:
+
+- PDF and cover destinations and PDF build directories are configurable. The
+  runtime checks the actual paths; the manual scaffold renders exact ignore rules
+  from configuration. No `assets/pdf` or `assets/img` blanket policy is safe.
+- Computation outputs, rendered diagrams, original capture PNGs, annotated SVGs
+  and author-owned edited variants have source-dependent destinations. Preserve
+  originals and edited variants and regenerate only through the owning tool after
+  reviewing freshness and overwrite requirements. No glob is a literal policy.
+- `.unaltraweb/web-captures.lock.json` remains runtime-managed provenance under
+  the existing consumer versioning decision, outside this initial minimal list.
+- Other Jekyll/Quarto caches retain existing ignore rules without a new universal
+  cleanup declaration. Neither `assets`, `.cache` nor `.unaltraweb` is classified
+  as one disposable tree.
+
+## What Needs Updating
+
+| Change | Required action |
+| --- | --- |
+| This discovery-policy adoption | Use a reviewed unaltraweb factory revision containing these declarations and a central manager with path-policy and installable-closure support. |
+| Current v0.4.0 package/image | Already compatible; no rebuild, republish or pin change is required solely for workspace checks. The wheel does not ship the root discovery manifest. |
+| Runtime or package scaffold changes in a later release | Install/select the reviewed package or MCP image containing those changes; reconnect an already-running MCP. Updating a discovery checkout alone does not replace its pinned runtime. |
+| Older or drifted consumer controls | Review `scaffold_sync` against the selected package. Apply only after resolving conflicts deliberately. |
+| Local ignores, tracked cache files, computation locks, renderer receipts or edited outputs | Consumer decision, in its own issue/branch and reviewed diff. No automatic migration or mass regeneration. |
+
+The four v0.4.0 profile scaffolds already ignore `_site/`, `tmp/` and `.cache/`.
+That parent rule also covers both renderer caches, including absent directories.
+They create the common versioned controls; only `unaltremanual` creates
+`.unaltraweb/computations.yml`. The optional `.vegavisuals.yml` is not required in
+other profiles. This change leaves package assets, the managed file set and
+`.unaltraweb/scaffold.json` schema/hashes unchanged.
+
+## Existing Consumer Procedure
+
+1. In that consumer's own session, inspect root, branch, status, upstream and
+   existing reservations. Run session preflight on a clean short-lived branch.
+   Preserve unrelated local work. Record the reviewed discovery commit and
+   central manager revision in the integration issue.
+2. Inspect `Makefile` (`MCP_IMAGE`, `MANUAL_PDF_IMAGE`), `Gemfile`, `Gemfile.lock`,
+   `.github/workflows/deploy.yml`, `.unaltraweb/scaffold.json` and
+   `distribution_doctor`. Use the published v0.4.0 package/image for the existing
+   compatible scaffold, or a later explicitly reviewed release. Do not move the
+   immutable v0.4.0 release or install an unpublished branch as a consumer runtime.
+3. Call `scaffold_sync(dry_run=true)`. It manages exactly `.gitignore`,
+   `.unaltraweb/docker-mount.sh`, `.github/CONTRIBUTING.md`,
+   `.github/dependabot.yml`, `.github/pull_request_template.md`,
+   `.github/workflows/deploy.yml`, `Makefile`, `Gemfile` and `Gemfile.lock`, with
+   `.unaltraweb/scaffold.json` written last. Reserve the actual changed paths.
+   `_config.yml`, README, AGENTS and editorial files are not synchronized.
+4. In an MCP with the guided update flow, a customized `.gitignore` or other
+   managed file is preserved when the incoming package still equals its recorded
+   baseline. Conflicting local/upstream changes prevent the entire apply. The
+   original v0.4.0 synchronizer was stricter and reported all differing local
+   edits as conflicts. Compare current bytes with the recorded baseline and
+   package proposal; preserve local rules and ask the owner which changes to integrate.
+   Do not forge baseline hashes, force overwrites, or remove a colliding local
+   artefact. Exact current package bytes can be adopted; remaining customizations
+   may intentionally remain conflicts. Policy compliance does not require
+   overwriting a customized file merely to obtain a clean sync report.
+5. Where the reviewed plan is conflict-free, call
+   `scaffold_sync(dry_run=false, confirm_sync=true, expected_plan_sha256=<reviewed digest>)`
+   when using the guided flow. A current v0.4.0 consumer
+   needs no scaffold writes for this policy adoption. Inspect Git ignore matches
+   and indexed descendants of every ignored policy. Decisions to untrack existing
+   files require consumer review; keep the actual files and any recovery evidence.
+6. Stage only reviewed versioned sources/controls (including an optional Vega
+   manifest if present). Run the manager against the absolute consumer path:
+
+   ```bash
+   python3 /path/to/my-scripts-factory/src/bash/mcp_factories/mcp-factory-manager.py \
+     workspace-check --dir /path/to/factories --factory unaltraweb \
+     --workspace /absolute/consumer --json
+   ```
+
+   Expect all three factories with zero findings/errors. Do not bypass the
+   installable dependencies. Inspect each resolved root. The command is read-only;
+   it does not stage sources, repair ignores, build images or run provider checks.
+7. Run `site_check` and resolve blocking findings before `build_site` or
+   `make test`. For a local manual PDF review, call
+   `manual_pdf_preview_prepare` before a direct MCP build/preview (managed Make
+   targets already do this). Review the website/PDF, then dry-run and confirm
+   receipt-bound `manual_pdf_preview_clean`. If an unmanaged PDF/cover already
+   exists, preserve it and resolve ownership rather than deleting it automatically.
+8. No artefact needs regeneration merely because discovery metadata changed.
+   If actual inputs, sources or runtimes changed, inspect computation/capture and
+   provider status and explicitly render only affected outputs under a separate
+   accepted reservation. Complete the consumer PR and human review; publication
+   remains a separate manual action.
+
+## Maintainer Verification
+
+Normal unit tests cover declarations, all four packaged profiles and sync conflict
+preservation. Central-manager integration tests are opt-in so the package does
+not acquire a sibling-checkout runtime dependency:
+
+```bash
+UNALTRAWEB_FACTORY_MANAGER=/path/to/my-scripts-factory/src/bash/mcp_factories/mcp-factory-manager.py \
+UNALTRAWEB_FACTORIES_DIR=/path/to/factories \
+PYTHONPATH=src python3 -m unittest discover -s test -p 'test_workspace_path_policies.py' -v
+```
+
+`test/workspace_consumer_smoke.py` exercises the actual `make -C` Docker stdio
+launcher with an external temporary consumer, all four `new_web` profiles,
+`scaffold_sync`, indexed policy sources, closure snapshots, `site_check` and a
+representative `build_site`. Use its explicit manager/discovery paths and image
+arguments; it never registers an MCP or edits a real consumer. Existing PDF
+preview/recovery unit tests and Docker PDF integrations remain the recovery gates.