unaltraweb 0.3.0 → 0.5.0

data/docs/agents/mcp-contract.md

@@ -8,15 +8,17 @@ The client registration should launch:
 make --silent --no-print-directory -C ${factoryRoot} mcp-stdio
 ```
 
-The opened workspace is the consumer website repository. The pending distribution contract selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.3.0` for the factory logic, without asserting that the remote image exists yet. The launcher reuses it locally or attempts to pull it; an unavailable pending release fails visibly rather than triggering a local fallback build. This is the canonical ContExt command from `mcp-factory.yml`; the transport also sets `MCP_CONSUMER_WORKSPACE=${workspaceFolder}` in the child environment:
+The opened workspace is the consumer website repository. gContExt preparation inspects or pulls the full public digest selected by `MCP_RELEASE_IMAGE`, and the launcher executes that exact image; it never falls back to an implicit source build. The pin advances in a separate post-release change only after a receipt records the new digest. This is the canonical gContExt command from `mcp-factory.yml`; the transport also sets `MCP_CONSUMER_WORKSPACE=${workspaceFolder}` in the child environment:
 
 ```bash
 MCP_CONSUMER_WORKSPACE="$PWD" make --silent --no-print-directory -C /path/to/unaltraweb mcp-stdio
 ```
 
-Replace `/path/to/unaltraweb` with the checkout's absolute path. The bootstrap canonicalizes the inherited environment value after process launch; neither Make nor generated shell source evaluates consumer path text. The declared launcher remains `make`, which ContExt permits for a container runtime without a `runtime.allowed_host_launchers` exception. Restart clients such as OpenCode after changing their MCP registration.
+Replace `/path/to/unaltraweb` with the checkout's absolute path. The bootstrap canonicalizes the inherited environment value after process launch; neither Make nor generated shell source evaluates consumer path text. The declared launcher remains `make`, which gContExt permits for a container runtime without a `runtime.allowed_host_launchers` exception. Restart clients such as OpenCode after changing their MCP registration.
 
-ContExt dependency preparation builds the runtime and required companions but does not initialize consumer content. The transport passes `${workspaceFolder}` only through `MCP_CONSUMER_WORKSPACE`; it never sets `transport.cwd` or embeds the consumer path in a Make assignment. The factory command may therefore use `make -C` without changing or reparsing the selected consumer root. Companion-aware checks and smoke tests include both required providers, while provider updates remain explicit. The manifest does not advertise an `init` command, and both companion dependencies set `init: false`. Use `new_web` explicitly when a new consumer site should be created. Restart long-lived MCP clients after registration, rebuilds, or provider upgrades so their stdio processes use the selected releases.
+gContExt dependency preparation ensures the selected MCP release image and prepares required companions but does not initialize consumer content. The transport passes `${workspaceFolder}` only through `MCP_CONSUMER_WORKSPACE`; it never sets `transport.cwd` or embeds the consumer path in a Make assignment. The factory command may therefore use `make -C` without changing or reparsing the selected consumer root. Companion-aware checks and smoke tests include both required providers, while provider updates remain explicit. The manifest does not advertise an `init` command, and both companion dependencies set `init: false`. Use `new_web` explicitly when a new consumer site should be created. Restart long-lived MCP clients after registration, release-pin changes, or provider upgrades so their stdio processes use the selected releases.
+
+Repository editing coordination remains a control-plane responsibility rather than an `unaltraweb` runtime feature. Request one top-level MCP and let the control plane select its declared dependency closure; unrelated user registrations remain configured until explicitly removed and clients reconnect. Before editing, the control plane runs its read-only checkout preflight against the one primary mutable checkout and, when required, holds a process-scoped cooperative lease through its `exec` wrapper. Only one editing session may be active per repository. The control plane must never create, switch to, move, prune, repair, or remove Git worktrees implicitly.
 
 For a new agent-driven workspace, create or select the empty Git repository first, open that directory in the IDE, register the factory, restart the client, and then call `new_web`. The tool remains confined to the configured project root and does not accept an arbitrary destination. Generated sites include user-owned `README.md` and `AGENTS.md`, profile-specific source directories, and a managed runtime baseline; `scaffold_sync` never rewrites those user-owned guidance or content files.
 
@@ -30,15 +32,42 @@ A version-1 receipt contains only the provider result contract: `schema_version`
 
 The request digest is SHA-256 over `unaltraweb-companion-receipt-v1\0OWNER\0`, followed for each sorted provider source by its UTF-8 project-relative path and bytes, each prefixed by an unsigned eight-byte big-endian length. Vega sources are the manifest and all project Vega/Vega-Lite specifications; diagram sources are all supported Mermaid and PlantUML files. Receipt publication remains provider-owned, but a provider cannot expand or reduce the input inventory accepted by unaltraweb.
 
+## Discovery Workspace Policies
+
+`mcp-factory.yml` declares schema-v1 `workspace_rule.path_policies` against the
+consumer root `.`. The central manager owns `workspace-check`; it is not an
+unaltraweb MCP tool and does not invoke `site_check`, `down`, rendering or any
+other provider command. It checks the complete `install: true` dependency closure,
+retaining each provider's own binding and root. The current selection is
+`diavisuals`, `vegavisuals`, then `unaltraweb` (three factories, two dependencies).
+
+Ignored paths require real Git ignore coverage and no indexed descendants;
+existing versioned files must be indexed and not ignored; absent versioned paths
+are allowed. `consumer` leaves the Git decision to the project. Cleanup metadata
+does not authorize deletion, and `generated_paths` alone conveys neither ignore
+nor cleanup policy. Optional computation/PDF paths do not initialize those
+features or require manual content in other profiles.
+
+The [path audit and consumer update procedure](../_documentation/en/43-workspace-path-policies.md)
+documents why `tmp`, Scimago inputs, PDF provenance, preview ownership, locks and
+recovery backups need explicit preservation decisions. Renderer receipts and Vega
+paths retain their provider policies; configurable outputs and edited visual
+assets have no blanket policy here. The initial adoption changes discovery only:
+the four v0.4.0 package scaffolds already meet these policies, and neither their
+baseline format nor runtime cleanup changes.
+
 ## Resources
 
 | Resource | Description |
 | --- | --- |
 | `web://distribution` | Package-owned component BOM plus offline, feature-aware doctor findings for the current factory and project. |
-| `web://site-context` | Site profile, feature flags, content inventory, bibliography, bibliometrics, and build state. |
+| `web://site-context` | Site profile, feature flags, content inventory, bibliography, bibliometrics, build state, and offline consumer-update advisory. |
 | `web://site-doctor` | Read-only offline distribution, project-contract, freshness, scaffold-drift, and core-override findings. |
 | `web://starter-templates` | Starter website templates available to initialize a new workspace. |
 | `web://profile-contract` | Checks for `unaltreselfie`, `unaltreprojecte`, `unaltremanual`, and `unaltredocs`. |
+| `web://editorial-policy` | Effective common, profile, genre and local writing policy, supported languages and policy fingerprint. |
+| `web://editorial-status` | Anchored review passes, retained decisions and source/policy staleness; also available in `site_context.editorial`. |
+| `web://image-backgrounds` | Read-only source-image opacity advisories, generated-source ownership and explicit inspection limits. |
 | `web://profile-prune-plan` | Dry-run list of profile-specific content that can be removed from the active profile. |
 | `web://content-inventory` | Local editable collections, `_data/`, and assets. |
 | `web://language-policy` | Default language, configured languages, and editorial translation workflow settings. |
@@ -63,16 +92,24 @@ The request digest is SHA-256 over `unaltraweb-companion-receipt-v1\0OWNER\0`, f
 | `starter_templates` | List package-owned profile scaffolds under the legacy inventory name. |
 | `initialize_site` | Compatibility alias for `new_web`; external templates and overwrite mode are rejected. |
 | `detect_site` | Detect an unaltraweb consumer from `_config.yml` and `Gemfile`, and report whether its Makefile exposes the native build/serve contract. |
-| `site_context` | Read the main local state for an agent session. |
+| `site_context` | Read the main local state plus `update_status`: current/target package versions, planned paths, preserved customizations, conflicts and a reviewed-plan digest. |
 | `site_doctor` | Combine distribution doctor with strict project config, identity/language, generated Make contract, scaffold drift, required generated-output/receipt status, existing HTML audit, companion actions, and core override inventory. Unknown required status is blocking. Read-only and offline. |
-| `site_check` | Run profile, freshness, companion visualization/diagram receipt, bibliography, bibliometrics, and build-state checks without network. |
+| `site_check` | Run profile, publication-copy source diagnostics, freshness, companion visualization/diagram receipt, bibliography, bibliometrics, and build-state checks without network. |
 | `site_source_read` | Read one allowed UTF-8 site source and return its exact SHA-256. |
 | `site_source_write` | Dry-run or atomically create/update one allowed source. Creates require `create_only`; updates require the exact SHA-256 returned by a read. |
 | `site_source_delete` | Dry-run or delete one allowed source with exact SHA-256 and explicit confirmation. It never deletes `_config.yml` or directories. |
-| `scaffold_sync` | Dry-run or transactionally synchronize the nine package-managed scaffold controls, including the collaboration contract, Dependabot policy, pull-request template, dependency pins, and deploy caller, against `.unaltraweb/scaffold.json`; edited files are conflicts, exact current package bytes may be adopted without a rewrite, every output is staged, adopted and unchanged files are rechecked before and after the last manifest write, and rollback covers partial apply. README prose remains site-owned. |
+| `scaffold_sync` | Dry-run or transactionally synchronize the nine package-managed scaffold controls against `.unaltraweb/scaffold.json`; preserve local edits if the package file has not changed from baseline, reject conflicting edits and known version downgrades, and optionally require `expected_plan_sha256` from the reviewed proposal. Exact package bytes may be adopted without rewriting. Adopted, unchanged and preserved files are rechecked around the manifest-last transaction; rollback covers partial apply. README prose remains site-owned. |
 | `profile_check` | Check current profile and expected content/config paths. |
+| `prose_check` | Check a selected content target or all supported reader-facing sources and public metadata using shared profile/genre rules; no writes or model calls. |
+| `editorial_policy` | Inspect common guidance, profile defaults, genre overrides, local writing preferences and optional publication requirements. |
+| `editorial_status` | Inspect `context/editorial-state.json`, revision, review history and staleness without creating files. |
+| `editorial_review_prepare` | Prepare bounded source text, exact fragment anchors, source digest, editable owners and a structure/line/copy/evidence rubric. |
+| `editorial_review_record` | Explicitly record a report with exact quotes/anchors, current source digest and `expected_revision`; never edit prose or grant author approval. |
+| `editorial_review_resolve` | Record an accepted/rejected/resolved disposition with a reason and current revision; preserve prior decisions. |
+| `editorial_publication_check` | Check publication copy and opt-in fresh-review requirements; optional `output_folder` adds rendered HTML and private-context leakage checks. |
+| `image_background_check` | Warn about transparent or unverifiable raster/SVG images in a source selection or rendered output folder. Any opaque colour is valid; the tool never modifies files or fetches remote images. |
 | `manual_source_quality_check` | For `unaltremanual`, check captioned tables and figures, resolve local visual sources, compare embedded SVG text with body text on web/PDF, and suggest support-specific dimensions. |
-| `manual_editorial_quality_check` | Reject non-publishable metatext, user/agent instructions, workflow markers, drafting notes, and placeholders in manual bodies; return the editorial review checklist and local writing-profile path. |
+| `manual_editorial_quality_check` | Manual-scoped compatibility wrapper around shared prose rules; preserve the review checklist and writing-profile path while allowing legitimate quotations, examples and reader-facing language. |
 | `manual_authoring_capabilities` | Return the paragraph-development model and structured component catalogue an MCP writing assistant must use. |
 | `manual_computation_status` | Inspect executable manual sources, selected images, generated outputs, and freshness without executing code. |
 | `manual_computation_check` | Reject missing, modified, orphaned, or stale generated Markdown and figures. |
@@ -83,6 +120,8 @@ The request digest is SHA-256 over `unaltraweb-companion-receipt-v1\0OWNER\0`, f
 | `web_capture_render` | Start Jekyll and Chromium on an ephemeral internal Docker network, then publish original PNG plus editable annotated SVG from declared CSS selectors. |
 | `manual_pdf_status` | Inspect PDF configuration, sources, generated artefacts, published paths, selector, and freshness without Docker, network, or writes. |
 | `manual_pdf_build` | Build one or all configured language PDFs and first-page cover previews under `tmp/`; `release_selector` defaults to `latest` and is part of the PDF fingerprint. |
+| `manual_pdf_preview_prepare` | Build only stale `latest` PDF languages, then atomically stage ignored, untracked PDF and cover copies for local Jekyll review under a cleanup receipt. Always reports `publishes: false`; disabled PDF configuration is a no-op unless receipt-owned preview files still require cleanup. |
+| `manual_pdf_preview_clean` | Dry-run or remove only preview files whose path, Git state, content hash, and file identity still match the staging receipt. Real cleanup requires explicit confirmation plus the dry-run's exact `receipt_sha256` as `expected_receipt_sha256`, and never publishes. |
 | `manual_pdf_publish` | Copy built PDFs and covers to configured public assets. Defaults to dry-run; real publication requires explicit confirmation, and the selector must match the build. |
 | `manual_release_status` | Offline, read-only inspection of selector-bound build receipt, HTML audit, PDF evidence, stable policy, and local candidate state. |
 | `manual_release_check` | Fail unless the selector-bound candidate exactly matches the current verified source, site, PDF, cover, manifest, and checksums. |
@@ -107,11 +146,13 @@ The request digest is SHA-256 over `unaltraweb-companion-receipt-v1\0OWNER\0`, f
 | `preview_stop` | Remove only that project's labelled preview container. |
 | `http_check` | Probe bounded safe paths on the current project's owned labelled preview. The origin is derived internally; redirects and arbitrary origins are rejected. |
 
-Advanced computation, capture, PDF, and bibliometrics tools delegate to factory-owned Make targets against the consumer project. Fresh package scaffolds therefore do not need to copy those implementation targets into each website. A new `unaltremanual` does include a consumer-owned `.unaltraweb/computations.yml` that selects the release's R and Python workers; the first render reuses a local image or pulls that selected image automatically. The worker layers remain external distribution components and are not copied into the wheel or site. The tool names use `bibliometrics_*` even though factory Make targets retain `metrics-*` for backwards compatibility.
+Advanced computation, capture, PDF, and bibliometrics tools delegate to factory-owned Make targets against the consumer project. Fresh package scaffolds therefore do not copy worker implementation into each website. Their managed outer `build`, `test`, and `serve` targets call `manual_pdf_preview_prepare` in a short-lived controller before Jekyll starts. That controller mounts a locally available Docker socket when a stale PDF may need a nested worker, but can still execute a disabled or already-fresh operation when no socket is available; `build-native`, `test-native`, `serve-native`, and the persistent preview container remain socket-free. A new `unaltremanual` does include a consumer-owned `.unaltraweb/computations.yml` that selects the release's R and Python workers; the first render reuses a local image or pulls that selected image automatically. The worker layers remain external distribution components and are not copied into the wheel or site. The tool names use `bibliometrics_*` even though factory Make targets retain `metrics-*` for backwards compatibility.
 
 `distribution_doctor` findings always include `code`, `severity`, `expected`, `actual`, and `remediation`. Missing factory assets in a direct wheel install produce healthy limited wheel mode, not a false failure. When Docker checks are requested, doctor uses only `docker version` and `docker image inspect`; it does not pull, build, start, or remove anything.
 
-Manual PDF publication is a local workspace operation: it copies reviewed artefacts from `tmp/manual-pdf/` to configured paths such as `assets/pdf/` and `assets/img/`. It never commits, pushes, creates releases, or writes outside the consumer workspace. Use one selector consistently across `manual_pdf_build`, `manual_pdf_publish`, `build_site`, and `manual_release_prepare`. `latest` is the default; stable selectors use `vYYYY.MM(.N)` and require the consumer repository root to be an exact clean Git checkout without nested repositories, submodules, or clean/smudge filters. Stable Jekyll builds run in an MCP image selected by immutable digest, derive `SOURCE_DATE_EPOCH` from the consumer commit, and record both identities in their version-2 candidate manifest. Run `manual_source_quality_check`, `manual_editorial_quality_check`, `manual_pdf_status`, `manual_pdf_build`, and a `manual_pdf_publish` dry-run before calling `manual_pdf_publish(dry_run=false, confirm_publish=true)`. A stable caller additionally submits the SHA-256 of its checked local `tmp/manual-release/<selector>/release-manifest.json`; only the GitHub workflow has tag and release authority.
+Manual PDF preview staging is distinct from publication. `manual_pdf_preview_prepare` is fixed to `latest`, builds stale languages, requires the repository root plus ignored and untracked public destinations, writes its ignored receipt under `.cache/unaltraweb/`, and never commits, pushes, tags, releases, or deploys. It refuses unmanaged existing files and leaves each current generated-equivalent PDF or cover unowned and unchanged. Confirmed publication first writes expected hashes to `.cache/unaltraweb/manual-pdf-publication-intent.json`, then records non-owning file identity at `.cache/unaltraweb/manual-pdf-publication.json`; an interrupted or later preview cycle can replace only matching deployment products without granting cleanup authority over them. `manual_pdf_preview_clean` preserves any staged file that was edited, replaced, mode-changed, tracked, or made non-ignored and retains the receipt when cleanup conflicts. Its dry-run returns `receipt_sha256`; confirmed cleanup must submit that exact digest so a newly prepared generation cannot be deleted under an older review. Receipt-owned files must be cleaned before PDF output is disabled or real publication. The direct MCP sequence is prepare, `build_site`, `preview_start`, human browser/PDF review, cleanup dry-run, and digest-bound confirmed cleanup.
+
+Manual PDF publication is a local workspace operation: it copies reviewed artefacts from `tmp/manual-pdf/` to configured paths such as `assets/pdf/` and `assets/img/`. It never commits, pushes, creates releases, or writes outside the consumer workspace. Use one selector consistently across `manual_pdf_build`, `manual_pdf_publish`, `build_site`, and `manual_release_prepare`. `latest` is the default; stable selectors use `vYYYY.MM(.N)` and require the consumer repository root to be an exact clean Git checkout without nested repositories, submodules, or clean/smudge filters. Stable Jekyll builds run in an MCP image selected by immutable digest, derive `SOURCE_DATE_EPOCH` from the consumer commit, and record both identities in their version-2 candidate manifest. Run `manual_source_quality_check`, `manual_editorial_quality_check`, `manual_pdf_status`, `manual_pdf_preview_prepare`, browser/PDF review, confirmed preview cleanup, and a `manual_pdf_publish` dry-run before calling `manual_pdf_publish(dry_run=false, confirm_publish=true)`. A stable caller additionally submits the SHA-256 of its checked local `tmp/manual-release/<selector>/release-manifest.json`; only the GitHub workflow has tag and release authority.
 
 ## New Site Initialization
 
@@ -123,15 +164,72 @@ It sets `lang`, `default_lang`, and `languages` so a new site has an explicit so
 
 Before writing, it validates every managed path, rejects destination symlinks, and compares existing files with the complete rendered scaffold through bounded regular-file reads. Identical files make repeated calls idempotent. Any differing file or file/directory collision detected during preflight aborts the whole operation before website files are written. Descriptor-relative, no-clobber writes and a final descriptor-relative content check prevent raced paths from being followed or overwritten; overwrite mode is not available. The baseline manifest is created after every other scaffold file.
 
-The baseline records exactly `.gitignore`, `.unaltraweb/docker-mount.sh`, `.github/CONTRIBUTING.md`, `.github/dependabot.yml`, `Makefile`, `Gemfile`, `Gemfile.lock`, `.github/pull_request_template.md`, and `.github/workflows/deploy.yml`. `scaffold_sync` updates one of these while its bytes still match the recorded baseline, adopts it when its bytes already equal the current package payload, creates a newly managed path only when it is absent, and reports other local edits or deletions as conflicts. Any conflict prevents every apply. It removes retired paths only from the baseline and never deletes their project files; it also never changes site-owned README/agent guidance, config, seed content, bibliography, data, or assets. A real synchronization requires `dry_run=false` and `confirm_sync=true`; adopted and unchanged files are included in the final rechecks around the manifest-last commit.
+The baseline records exactly `.gitignore`, `.unaltraweb/docker-mount.sh`, `.github/CONTRIBUTING.md`, `.github/dependabot.yml`, `Makefile`, `Gemfile`, `Gemfile.lock`, `.github/pull_request_template.md`, and `.github/workflows/deploy.yml`. `scaffold_sync` updates one of these while its bytes still match the recorded baseline, adopts it when its bytes already equal the current package payload, and creates a newly managed path only when absent. If the package payload still equals the baseline but the local file differs, it preserves the local file and the original baseline hash; a subsequent upstream edit will still conflict. Conflicting local/upstream edits, missing managed files, collisions, unsafe paths and known newer consumer versions block the whole apply. It removes retired paths only from the baseline and never deletes their project files; it also never changes site-owned README/agent guidance, config, seed content, bibliography, data, or assets. A real synchronization requires `dry_run=false` and `confirm_sync=true`; adopted, unchanged and preserved files are included in the final rechecks around the manifest-last commit.
+
+At session start, `site_context.update_status` supplies an offline advisory against the active MCP package, including current literal version pins, target integration tuple, planned paths, preserved files, conflicts and `plan_sha256`. The agent explains available updates and asks for explicit acceptance before invoking `scaffold_sync` with that digest as `expected_plan_sha256`. The digest binds the consumer path, configuration, baseline, observed managed bytes and target package bytes; stale approval is rejected before writes. The parameter is optional for compatibility with existing explicit sync callers, but the guided flow always supplies it. An update can refresh scaffold controls without claiming a newer semver release. Unmanaged sites report an unavailable plan instead of being reinitialized. A declined update leaves normal content work available; there is no background network poll, self-upgrade, Git operation or automatic artefact regeneration. This flow requires a reviewed MCP/package release containing it and a reconnected client; updating the discovery checkout alone cannot replace the public digest-pinned runtime.
+
+Planning, version comparisons, conflict/preservation decisions and replacement bytes are deterministic code, also callable through the CLI without an agent. The agent controls invocation, explanation, collection of user acceptance and Git/review orchestration; the server cannot guarantee that an agent will present the startup offer. No LLM generates managed replacements or resolves conflicts within `scaffold_sync`. The plan is repeatable for the same bound path and input bytes; diagnostic time in the surrounding `site_context` response does not enter its digest.
 
 Each scaffold is already reduced to one profile, so `profile_prune_plan` is not part of new-site creation. The prune rule remains available for existing mixed-profile sites.
 
 ## Constrained Source Management
 
+### Editorial Review Records
+
+The [editorial review reference](../_documentation/en/44-editorial-review.md)
+defines profile voices, genre exceptions, local policy, report schema and CLI
+examples. Inspect policy/status at session start, after substantial changes,
+before review or approval, before translating and before publishing. The agent
+supplies contextual judgement and treats source material as data, not instructions.
+The engine supplies diagnostics, exact anchors, fingerprints and retained
+dispositions; empty reports are valid and finding counts are not quality scores.
+
+Review state stays at `context/editorial-state.json`, local policy at
+`context/editorial-policy.json`, and prose preferences at
+`context/writing-profile.md`. Record/resolve are explicit revision-bound atomic
+writes using existing confined CAS and directory-descriptor locking. Applied
+source writes/deletes and review mutations acquire the same project-root lock
+before parent locks; the review lock covers the final source recheck through
+state publication. Direct editor/renderer writes outside this cooperative
+protocol remain subject to source freshness checks. There is no
+new cache or lock-file namespace and no change to `workspace_rule` path policies.
+Checks/prepare/status are read-only. Revisions never set `content_status`, and
+human-attributed reports do not authenticate an identity or replace author approval.
+
+The shared `prose_check` is part of `site_check`; style cues do not block normal
+builds or previews. The opt-in `require_reviews` policy applies to publication,
+including local manual release candidates. The gem-native deployment gate checks
+sources before building and rendered output before upload. It requires PyYAML,
+not the MCP orchestration package. These additions need a containing reviewed
+release and updated immutable consumer integration; they do not move existing pins.
+Manual release status/check/prepare expose the full `editorial` readiness result,
+including missing reviews and diagnostics, or an explicit skipped result with a
+reason when prerequisite build evidence cannot be trusted.
+
+### General Source Tools
+
 The source tools are not generic filesystem operations. Their complete write scope is `_config.yml`; Markdown/HTML under the known content collections; YAML, JSON, or CSV below `_data/`; and Markdown below `context/`. Workflows, Makefiles, Gemfiles, layouts, includes, plugins, Sass, bibliography, binary assets, generated paths, symlinks, directories, absolute paths, and traversal are outside this API.
 
-All operations use project-confined descriptor-relative no-follow traversal. Nonblocking open rejects FIFOs/devices before reading, size is checked before allocation, and files/proposed content are limited to 1 MiB. Text must be UTF-8 without NUL bytes; YAML and JSON reject duplicate keys, and JSON rejects non-finite numbers. Reads return SHA-256. Existing writes require that exact digest; new writes require `create_only=true`. Apply takes an advisory parent lock, moves the expected object to a private backup, verifies content and identity before and after publication, and restores the backup when a final-window edit is detected. Deletes use the equivalent verified tombstone flow. `_config.yml` is never deletable.
+All operations use project-confined descriptor-relative no-follow traversal. Nonblocking open rejects FIFOs/devices before reading, size is checked before allocation, and files/proposed content are limited to 1 MiB. Text must be UTF-8 without NUL bytes; YAML and JSON reject duplicate keys, and JSON rejects non-finite numbers. Reads return SHA-256. Existing writes require that exact digest; new writes require `create_only=true`. Apply takes the project-root advisory lock before the parent lock, moves the expected object to a private backup, verifies content and identity before and after publication, and restores the backup when a final-window edit is detected. Deletes use the same root-before-parent ordering and the equivalent verified tombstone flow. `_config.yml` is never deletable.
+
+## Image Backgrounds And Companion Linking
+
+Image background checks are advisory and share one CLI/MCP/native implementation.
+`site_check` includes source references, `html_audit` includes rendered image
+references, and MCP PDF builds expose source-image advisories. Report warnings to
+the author; do not silently flatten assets onto white. The decoder runs in a
+bounded child process, disallows external SVG resources and reports unsupported
+cases as unverifiable. The [image background reference](../_documentation/en/26-image-backgrounds.md)
+documents supported formats, sampling limits and the native gem command.
+
+For companion linking, compare the selected BOM and dependency capabilities with
+each running provider's `factory_manifest`, `compatibility_status` and release
+evidence. A development checkout announcing a future version is not a published
+release or evidence that a long-lived MCP process has upgraded. The current
+published companion selections are `diavisuals v0.3.1` and `vegavisuals v0.3.1`.
+Advance them only after their immutable releases exist and their receipt/tool
+contracts have been verified; source-checkout version drift remains an explicit
+control-plane finding, not a reason to weaken receipt validation.
 
 ## Language And Translation Discipline
 
@@ -145,13 +243,13 @@ Translations are a pre-publication task. They should preserve `ref`, citations,
 
 ## Docker Runtime And Preview
 
-`make mcp-build` builds `ghcr.io/dosquartsdedocs/unaltraweb:0.3.0` and then `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.3.0` locally. `make mcp-smoke` runs a real MCP client/server stdio exchange, compiles a temporary minimal site, and exercises preview start/status/stop. `mcp-stdio` remains dormant until a client launches it; dependency preparation never invokes it.
+`make mcp-build` prepares only the immutable public image selected by `MCP_RELEASE_IMAGE`; it does not build source. `make mcp-image`, `make mcp-check` and `make mcp-smoke` build checkout source under local `unaltraweb:dev` and `unaltraweb-mcp:dev` names. The smoke target also builds `unaltraweb-manual-pdf:dev`, runs a real MCP client/server stdio exchange, builds a stale manual PDF through the short-lived socket-enabled controller, and verifies preview start/status/stop against a persistent container that has no Docker socket. `mcp-stdio` remains dormant until a client launches it; dependency preparation never invokes it.
 
 Run `site_doctor` and `site_check`, then resolve any blocking validation result before compiling. `build_site` reuses the active MCP container and the consumer's `build-native` target, and runs the local HTML audit after a successful Jekyll process. The generated `test-native` target also runs `html_audit`. This is intentionally different from the consumer's normal host-side `make build`, which starts a Jekyll container and would create a nested runtime when called from MCP.
 
 Make delegation and feasible Docker control calls use one bounded subprocess runner. Status and control commands have short deadlines, builds/renders have target-specific longer deadlines, timeout terminates the process group and returns code `124`, and retained stdout/stderr is capped with explicit truncation fields. Factory commands that promise JSON fail closed when output is empty, malformed, non-object, non-finite, or truncated. Every bind source and target is encoded as a quoted Docker CSV field, so commas or quotes in host paths cannot introduce duplicate mount fields; carriage-return and newline path characters are rejected before canonicalization or mount construction. Computation, capture, and PDF containers carry factory, worker-role, project, and invocation-token labels plus cidfiles; after timeout cleanup selects all four labels and cannot remove unrelated containers.
 
-A preview must outlive one MCP tool invocation, so it runs in a separate container made from the same MCP/Jekyll image. Its deterministic name is derived from the canonical host project path and it carries the factory, role, and project labels. Its isolated container always listens on port `4000`; the default host port is allocated atomically by Docker on loopback and is reported as `preview_status.port`, preventing the old cross-project collision on host port `4000`. Starting an already-running preview probes it again instead of creating a duplicate. A preview created under the former fixed-port default is accepted as compatible with the new automatic default until it is stopped; its next start uses dynamic allocation. Changing an explicit requested port or profile still requires stopping first. Stdio session containers intentionally have Docker-generated names so independent clients can run simultaneously, but carry the same stable project ID and labels as previews and capture resources. Stop and cleanup operations select ownership labels before removing anything.
+A preview must outlive one MCP tool invocation, so it runs in a separate container made from the same MCP/Jekyll image. Its deterministic name is derived from the canonical host project path and it carries the factory, role, and project labels. Its isolated container always listens on port `4000`; the default host port is allocated atomically by Docker on loopback and is reported as `preview_status.port`, preventing the old cross-project collision on host port `4000`. Starting an already-running preview probes it again instead of creating a duplicate. A preview created under the former fixed-port default is accepted as compatible with the new automatic default until it is stopped; its next start uses dynamic allocation. Changing an explicit requested port or profile still requires stopping first. Stdio session containers intentionally have Docker-generated names so independent clients can run simultaneously, but carry the same stable project ID and labels as previews and capture resources. That process-level capability does not authorize concurrent editing sessions in one repository. Stop and cleanup operations select ownership labels before removing anything.
 
 `preview_status.url` is the browser URL published on host loopback. `preview_status.internal_url` is informational; callers do not pass it to `http_check`. That tool verifies preview ownership, derives the exact container-internal HTTP origin, disables environment proxies, accepts at most 20 local paths within a bounded timeout and response-read budget, and rejects absolute URLs, protocol-relative forms, traversal, fragments, hostile characters, non-2xx results, and redirects. Preview readiness checks the configured home permalink and generated root candidates rather than guessing a language route. `MCP_CONSUMER_WORKSPACE=/canonical/consumer/path make mcp-down` removes containers and networks selected by both `io.context.mcp-factory=unaltraweb` and the stable project label. A simultaneous `MCP_PROJECT_ID` must match that canonical live path. If the original path has moved or disappeared, pass the absent path with the retained ID or explicitly clear `MCP_CONSUMER_WORKSPACE`; only then is the retained ID accepted without path access. `make mcp-down-all` is the explicit maintainer cleanup for every resource carrying the factory label. Neither target deletes images or touches unlabelled resources.
 

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

@@ -0,0 +1,74 @@
+# Published visual companions: native acceptance and release handoff
+
+Tracking: [issue 67](https://github.com/dosquartsdedocs/unaltraweb/issues/67).
+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.
+
+## Selected artifacts
+
+| Provider | Integrated published source | Wheel SHA-256 |
+| --- | --- | --- |
+| Diavisuals v0.4.0 | `1e842967eabbad4cdb7dcb081493c1c25772dc5f` | `bfedcc9e2554f25ce4a1c33e556f352210848fccb8da800d1c3900dd86c48c93` |
+| Vegavisuals v0.4.0 | `68c0b231402ae9485cc34ce530dc5239cb0ec194` | `b52ffa743643dd6b5e0320e7a9aa0cd500ea06262b7d5098c0c3f94a379bc0ea` |
+
+Canonical URLs are in `components.<provider>.reference`; dependency `uv_spec`
+values derive from them. Validation binds a wheel's repository, release path,
+package/version filename and nonzero SHA-256. Existing exact Git references
+remain accepted. No additional component-contract field or wire version is needed.
+The published Vega wheel/renderer archive targets Linux/amd64.
+
+Native lifecycle flags, tools/resources and the complete dependency closure are
+preserved. Vega consumer scaffold revision now comes from its published commit.
+The current native receipts retain their original provider-owned semantics.
+This unit does not add a v1 artifact importer or claim domain bundle compatibility.
+
+## Executed acceptance — 2026-09-26
+
+- `make distribution-check`: passed.
+- `PYTHONPATH=src python3 -m unittest discover -s test -p 'test_*.py'`:
+  544 discovered, 515 passed, 29 optional cases skipped.
+- `make wheel-check`: passed against a clean factory-free installed wheel.
+- `make mcp-check mcp-smoke`: passed through the owner Docker development images,
+  including real stdio and preview/manual-PDF paths.
+- `make docs-build`: passed in the published core runtime.
+- `test/published_companion_smoke.py`: passed with separate installed published
+  wheel CLIs, their tested renderer images and a new temporary consumer with spaces.
+  It renders Mermaid, PlantUML, Vega-Lite with retained CSV data, and raw Vega;
+  checks actual provider receipts through `site_check`; rejects modified data and
+  diagram bytes; then accepts the relocated consumer. No receipt is fabricated.
+- `git diff --check`: passed.
+
+Reproduce the provider acceptance after installing the exact BOM wheel URLs and
+loading/verifying the renderer archives from their releases:
+
+```bash
+PYTHONPATH=src python3 test/published_companion_smoke.py \
+  --diavisuals /absolute/published-diavisuals/bin/diavisuals \
+  --vegavisuals /absolute/published-vegavisuals/bin/vegavisuals
+```
+
+Tested renderer IDs:
+`sha256:5a6887b372a0e1c386a7b54981d11ae1910215baeb6a12dfd0706b3e85ef0846`
+(Diavisuals) and
+`sha256:695125943d0fbc3aa7c877babb9a11a6501bbc7ac265b0975bb5657c60439d98`
+(Vega). These identify the release archives' images, not OCI registry RepoDigests.
+
+## Activation and publication order
+
+1. Review/integrate this owner PR and choose the next coordinated core release
+   version. Do not rebuild or republish the existing 0.4.0 artifacts under this
+   changed BOM. Keep other already integrated editorial/scaffold changes in scope
+   when preparing that coherent release.
+2. Run the normal candidate/receipt/signing/package release procedure in
+   `docs/_documentation/en/40-distribution.md`. Verify installed runtime and
+   native receipts against the exact candidate digests; unchanged workers can
+   retain their existing reviewed identities.
+3. Advance `MCP_RELEASE_IMAGE` only in the normal post-release change, using its
+   new receipt. It currently remains
+   `ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9`.
+   A green development manifest does not mean that this older running image has
+   acquired the new companion contract.
+4. Reconcile hub dependency state and repair the existing unaltraweb client drift
+   through normal dependency-aware installation. Reconnect clients and inspect the
+   selected runtime's own manifest before updating real consumer scaffolds.

data/docs/assets/img/caption-credits-demo.svg

@@ -0,0 +1,19 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="640" height="180" viewBox="0 0 640 180" role="img" aria-labelledby="title desc">
+  <title id="title">Three linked stages</title>
+  <desc id="desc">Three labelled boxes, A, B and C, connected from left to right.</desc>
+  <rect width="640" height="180" fill="#fff"/>
+  <g fill="#eaf1f7" stroke="#315a75" stroke-width="2">
+    <rect x="35" y="45" width="150" height="90" rx="8"/>
+    <rect x="245" y="45" width="150" height="90" rx="8"/>
+    <rect x="455" y="45" width="150" height="90" rx="8"/>
+  </g>
+  <g fill="none" stroke="#315a75" stroke-width="3">
+    <path d="M185 90h50m-10-8 10 8-10 8"/>
+    <path d="M395 90h50m-10-8 10 8-10 8"/>
+  </g>
+  <g fill="#213f56" font-family="sans-serif" font-size="18" text-anchor="middle">
+    <text x="110" y="97">A</text>
+    <text x="320" y="97">B</text>
+    <text x="530" y="97">C</text>
+  </g>
+</svg>

data/scripts/editorial_check.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Run the gem's offline editorial publication check without an MCP checkout."""
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from unaltraweb_mcp.editorial import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/image_background_check.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python3
+"""Run the packaged image background advisory without an MCP factory runtime."""
+from pathlib import Path
+import sys
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from unaltraweb_mcp.image_backgrounds import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

data/scripts/manual/build_pdf.py

@@ -45,11 +45,18 @@ DISPLAY_MATH_BLOCK_RE = re.compile(
     re.MULTILINE | re.DOTALL,
 )
 BASEURL_RE = re.compile(r"\{\{\s*site\.baseurl\s*\}\}")
+KRAMDOWN_ATTRS = r'''\{:(?:[^{}"'\n]|"(?:\\.|[^"\\\n])*"|'(?:\\.|[^'\\\n])*')*\}'''
+CAPTION_SOURCE_ATTR_RE = re.compile(
+    r'''(?:\A|\s)data-caption-source\s*=\s*(?:"(?P<double>(?:\\.|[^"\\])*)"|'(?P<single>(?:\\.|[^'\\])*)'|(?P<bare>[^\s}]+))'''
+)
 IMAGE_RE = re.compile(
     r"!\[(?P<alt>[^\]]*)\]\((?P<path>\S+?)(?:\s+(?:\"(?P<double_title>[^\"]*)\"|'(?P<single_title>[^']*)'))?\)"
-    r"(?P<attrs>\{:[^}\n]*\})?"
+    rf"(?:[ \t]*(?P<attrs>{KRAMDOWN_ATTRS}))?"
+)
+TABLE_DIV_RE = re.compile(
+    rf'''^:::\s*table\s+(?P<quote>["'])(?P<caption>[^\n]+?)(?P=quote)(?:[ \t]+(?P<attrs>{KRAMDOWN_ATTRS}))?[ \t]*\n(?P<body>.*?)^:::\s*$''',
+    re.MULTILINE | re.DOTALL,
 )
-TABLE_DIV_RE = re.compile(r'^::: table\s+["\'](.+?)["\']\s*\n(.*?)^:::\s*$', re.MULTILINE | re.DOTALL)
 LISTING_DIV_RE = re.compile(
     r'^:::\s*listing\s+"(?P<caption>[^"]+)"\s*\n(?P<body>.*?)^:::\s*$',
     re.MULTILINE | re.DOTALL,
@@ -61,7 +68,7 @@ TABLE_GUARD_AFTER_HEADING_RE = re.compile(
     re.MULTILINE,
 )
 SUBFIGURES_DIV_RE = re.compile(
-    r'^:::\s*subfigures(?:\s+(?P<layout>[^\s"]+))?(?:\s+"(?P<caption>[^"]*)")?\s*\n'
+    rf'^:::\s*subfigures(?:[ \t]+(?P<layout>[^\s"{{]+))?(?:[ \t]+"(?P<caption>[^"]*)")?(?:[ \t]+(?P<attrs>{KRAMDOWN_ATTRS}))?[ \t]*\n'
     r'(?P<body>.*?)^:::\s*$',
     re.MULTILINE | re.DOTALL,
 )
@@ -787,6 +794,60 @@ def resolve_visual_source(
     raise ManualPdfError(f"No printable SVG found for diagram source: {path}")
 
 
+def caption_source_attribute(raw: str) -> tuple[str, str]:
+    """Consume the caption-only field before emitting image attributes."""
+    source = raw.strip().removeprefix("{:").removesuffix("}").strip()
+    match = CAPTION_SOURCE_ATTR_RE.search(source)
+    if not match:
+        return "", raw
+    credit = next(value for value in match.group("double", "single", "bare") if value is not None)
+    credit = re.sub(r'''\\(["'\\])''', r"\1", credit).strip()
+    remaining = (source[:match.start()] + " " + source[match.end():]).strip()
+    return credit, "{: " + remaining + "}" if remaining else ""
+
+
+def caption_with_source(caption: str, source: str) -> str:
+    return caption + f" [{source}]{{.uw-caption-source}}" if source else caption
+
+
+def image_destinations(markdown: str) -> list[str]:
+    """Find assets after transformation, including nested caption spans/cites.
+
+    The source IMAGE_RE cannot represent arbitrary nested inline brackets. Asset
+    freshness must still include every image consumed by Pandoc, including an
+    inline image nested in another image's caption.
+    """
+    paths = []
+    for opening in re.finditer(r"(?<!\\)!\[", markdown):
+        index, depth = opening.end(), 1
+        while index < len(markdown) and depth:
+            character = markdown[index]
+            if character == "\\":
+                index += 2
+                continue
+            if character == "[":
+                depth += 1
+            elif character == "]":
+                depth -= 1
+            index += 1
+        if depth or index >= len(markdown) or markdown[index] != "(":
+            continue
+        start = index = index + 1
+        parentheses = 0
+        while index < len(markdown):
+            character = markdown[index]
+            if character.isspace() or (character == ")" and not parentheses):
+                break
+            if character == "(":
+                parentheses += 1
+            elif character == ")":
+                parentheses -= 1
+            index += 1
+        if index > start:
+            paths.append(markdown[start:index])
+    return paths
+
+
 def pandoc_image_attributes(raw: str) -> str:
     source = raw.strip()
     if not source:
@@ -887,7 +948,9 @@ def transform_markdown(
         return "[" + "; ".join(f"@{key}" for key in keys) + "]"
 
     def table(match: re.Match[str]) -> str:
-        body = match.group(2).strip()
+        body = match.group("body").strip()
+        credit, _ = caption_source_attribute(match.group("attrs") or "")
+        caption = caption_with_source(match.group("caption").strip(), credit)
         rows = [
             re.sub(r"\s+", " ", line.strip().strip("|"))
             for line in body.splitlines()
@@ -898,7 +961,7 @@ def transform_markdown(
         page_guard = r"\clearpage" if required_baselines >= 40 else f"\\Needspace{{{required_baselines}\\baselineskip}}"
         return (
             f"```{{=latex}}\n{page_guard}\n```\n\n"
-            f"Table: {match.group(1).strip()}\n\n{body}"
+            f"Table: {caption}\n\n{body}"
         )
 
     def listing(match: re.Match[str]) -> str:
@@ -957,8 +1020,9 @@ def transform_markdown(
             default_language=visual_default_language,
             languages=[str(value) for value in configured_visual_languages],
         )
-        caption = title or alt
-        attributes = pandoc_image_attributes(match.group("attrs") or "")
+        credit, raw_attrs = caption_source_attribute(match.group("attrs") or "")
+        caption = caption_with_source(title or alt, credit)
+        attributes = pandoc_image_attributes(raw_attrs)
         return f"![{caption}]({printable}){attributes}"
 
     def callout(match: re.Match[str]) -> str:
@@ -991,6 +1055,14 @@ def transform_markdown(
             padding = " " if value.startswith("`") or value.endswith("`") else ""
             return f"{fence}{padding}{value}{padding}{fence}{{=latex}}"
 
+        def credited_caption(caption: str, credit: str) -> str:
+            # Leave credit-bearing captions as Pandoc inlines so citeproc and
+            # links see them before the figure filter styles the credit span.
+            # Separate an authored closing code fence from the generated raw
+            # fence; adjacent backticks would change the Markdown tokenisation.
+            return (raw_latex_inline(r"\caption[{") + caption + " " + raw_latex_inline("}]{")
+                    + caption_with_source(caption, credit) + raw_latex_inline("}"))
+
         images = list(IMAGE_RE.finditer(match.group("body")))
         if not images:
             raise ManualPdfError(f"Subfigures block contains no images in {source.relative_to(project)}")
@@ -1008,13 +1080,16 @@ def transform_markdown(
             )
 
         overall_caption = latex_caption(match.group("caption") or "")
+        overall_credit, _ = caption_source_attribute(match.group("attrs") or "")
         figure_start = "```{=latex}\n\\begin{figure}[H]\n\\centering\n"
-        if overall_caption:
+        if overall_caption and not overall_credit:
             figure_start += (
                 f"\\caption{{{overall_caption}}}\n"
                 "{\\color{ManualMuted!45}\\rule{\\linewidth}{0.35pt}}\\par\\medskip\n"
             )
         rendered = [figure_start + "```"]
+        if overall_credit:
+            rendered.append(credited_caption(match.group("caption") or "", overall_credit))
         image_index = 0
         max_image_height = f"{0.52 / len(row_sizes):.3f}".rstrip("0").rstrip(".")
         for row_index, row_size in enumerate(row_sizes):
@@ -1031,7 +1106,8 @@ def transform_markdown(
                     default_language=visual_default_language,
                     languages=[str(value) for value in configured_visual_languages],
                 )
-                attributes = pandoc_image_attributes(item.group("attrs") or "")
+                credit, raw_attrs = caption_source_attribute(item.group("attrs") or "")
+                attributes = pandoc_image_attributes(raw_attrs)
                 row.extend([
                     raw_latex_inline(
                         f"\\begin{{subfigure}}[t]{{{panel_width}\\linewidth}}"
@@ -1041,10 +1117,11 @@ def transform_markdown(
                     f"![]({printable}){attributes}",
                 ])
                 separator = r"\hfill" if column_index < row_size - 1 else ""
-                row.append(raw_latex_inline(
-                    f"\\caption{{{latex_caption(caption)}}}"
-                    f"\\end{{subfigure}}{separator}"
-                ))
+                if credit:
+                    row.append(credited_caption(caption, credit))
+                else:
+                    row.append(raw_latex_inline(f"\\caption{{{latex_caption(caption)}}}"))
+                row.append(raw_latex_inline(f"\\end{{subfigure}}{separator}"))
             rendered.append("".join(row))
             if row_index < len(row_sizes) - 1:
                 rendered.append("```{=latex}\n\\par\\medskip\n```")
@@ -1246,7 +1323,9 @@ def assemble(project: Path, config: dict[str, Any], lang: str, paths: dict[str,
     metadata["include-home"] = includes_home
     metadata["has-listings"] = "data-listing-caption=" in assembled_markdown
     prose_markdown = FENCED_CODE_BLOCK_RE.sub("", assembled_markdown)
-    metadata["has-figures"] = bool(IMAGE_RE.search(prose_markdown) or r"\begin{figure}" in prose_markdown)
+    # Transformed image captions can contain nested credit spans/citations;
+    # IMAGE_RE is the source reader, not a parser for those Pandoc inlines.
+    metadata["has-figures"] = bool(image_destinations(MARKDOWN_INLINE_CODE_RE.sub("", prose_markdown)) or r"\begin{figure}" in prose_markdown)
     metadata["has-tables"] = bool(re.search(r"^Table:\s+\S", prose_markdown, re.MULTILINE))
     return metadata, source_paths, assembled_markdown
 
@@ -1410,8 +1489,7 @@ def build_dependencies(project: Path, metadata: dict[str, Any], source_paths: li
             dependencies.append((f"asset:{path.relative_to(project)}", path))
     dependency_markdown = FENCED_CODE_BLOCK_RE.sub("", markdown)
     dependency_markdown = MARKDOWN_INLINE_CODE_RE.sub("", dependency_markdown)
-    for match in IMAGE_RE.finditer(dependency_markdown):
-        raw = match.group("path")
+    for raw in image_destinations(dependency_markdown):
         if raw.startswith(("http://", "https://", "data:", "#")):
             continue
         local_path, _ = split_url_decoration(raw)