unaltraweb 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8881f6168982bd26668967e8c6d5baa8b7a02cb3bc6427edf7fdd89169fd8e36
-  data.tar.gz: 47457791441af3403defd6e99e621ebde05ada5e5adb50f80ce141db3a80e72c
+  metadata.gz: e9b1d06c849d3893c28fa69a879e93f56acef7a742aa8e2d8ae7df78fa53d4a2
+  data.tar.gz: '0995fe545e4466b531edc89ed8c8a37ca707e847cc31a8a3acd3647d6b77ecdd'
 SHA512:
-  metadata.gz: b870af22e7562818aa3b1a3c45911daaf273cd34ca9f523e05fb995f71f62c44f8222cc9d3457e420683c563c0d675ea6869165d8d6df0100058e4b7d07e9f27
-  data.tar.gz: 6c50e56046cb84a0ea06e7690177be1709265a5f4d5422c3605ab600e45ff5926ec776b1c28b8a3b7d27a01b8503c513d3d74f24608514e34a8fc5746b17472b
+  metadata.gz: 06dd87a7428129eb5ab81655c892abddf159d223aefec27cbdf5e7b5512a72fe7940061313cec5ccee5032ac1b0343cc6b8390617106c59b76d979b109d73cfc
+  data.tar.gz: e2a1cc1fe578e4df0968d1f9b9fbc1abbb0cfed254d38c192e7ec24a55e254adf14c9ed57128255f5a18cbaacf68b4fc64a8c519c99d5f87e1a98798db42a1ca

data/Makefile

@@ -1,8 +1,9 @@
 PYTHON ?= python3
 override PROJECT := $${MCP_CONSUMER_WORKSPACE:?MCP_CONSUMER_WORKSPACE is required}
 override PROJECT_ROOT := $(PROJECT)
-MCP_RUNTIME_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.3.0
-MCP_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.3.0
+MCP_RUNTIME_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.5.0
+MCP_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.0
+MCP_RELEASE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9
 MCP_DOCKER_BUILD_NETWORK ?= default
 INIT_SITE_PROFILE ?= unaltreselfie
 NEW_WEB_PROFILE ?= unaltreselfie
@@ -35,22 +36,35 @@ WEB_CAPTURE_DOCKER_NETWORK ?=
 WEB_CAPTURE_SERVICE_HOST ?=
 WEB_CAPTURE_CONFIRM_OVERWRITE ?= 0
 WEB_CAPTURE_SCRIPT := $(CURDIR)/scripts/web_captures/render.py
-WEB_CAPTURE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-web-capture:0.3.0
+WEB_CAPTURE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-web-capture@sha256:0bf1bc67fe63e1440bffe708a168beefa11c54441650a871ab99380d362f7c1e
 WEB_CAPTURE_DEV_IMAGE ?= unaltraweb-web-capture:dev
 WEB_CAPTURE_DOCKER_BUILD_NETWORK ?= default
 VEGAVISUALS_CLI ?=
-DOCKER_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.3.0
-MANUAL_PDF_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf:0.3.0
+DOCKER_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.5.0
+MANUAL_PDF_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097
 MANUAL_PDF_DEV_IMAGE ?= unaltraweb-manual-pdf:dev
+MCP_SMOKE_MANUAL_PDF_IMAGE ?= $(MANUAL_PDF_IMAGE)
 MANUAL_PDF_LANG ?=
 MANUAL_PDF_PUBLISH_DRY_RUN ?= 1
+MANUAL_PDF_CONFIRM_PUBLISH ?= 0
+MANUAL_PDF_PUBLICATION_INTENT_SHA256 ?=
+MANUAL_PDF_PREVIEW_CLEAN_DRY_RUN ?= 1
+MANUAL_PDF_PREVIEW_CONFIRM_CLEAN ?= 0
+MANUAL_PDF_PREVIEW_RECEIPT_SHA256 ?=
 MANUAL_RELEASE_SELECTOR ?= latest
 MANUAL_RELEASE_DRY_RUN ?= 1
 MANUAL_RELEASE_CONFIRM_PREPARE ?= 0
 override MANUAL_RELEASE_SELECTOR := $(value MANUAL_RELEASE_SELECTOR)
 override MANUAL_RELEASE_DRY_RUN := $(value MANUAL_RELEASE_DRY_RUN)
 override MANUAL_RELEASE_CONFIRM_PREPARE := $(value MANUAL_RELEASE_CONFIRM_PREPARE)
-export MANUAL_RELEASE_SELECTOR
+override MANUAL_PDF_PREVIEW_CLEAN_DRY_RUN := $(value MANUAL_PDF_PREVIEW_CLEAN_DRY_RUN)
+override MANUAL_PDF_PREVIEW_CONFIRM_CLEAN := $(value MANUAL_PDF_PREVIEW_CONFIRM_CLEAN)
+override MANUAL_PDF_PREVIEW_RECEIPT_SHA256 := $(value MANUAL_PDF_PREVIEW_RECEIPT_SHA256)
+override MANUAL_PDF_LANG := $(value MANUAL_PDF_LANG)
+override MANUAL_PDF_PUBLISH_DRY_RUN := $(value MANUAL_PDF_PUBLISH_DRY_RUN)
+override MANUAL_PDF_CONFIRM_PUBLISH := $(value MANUAL_PDF_CONFIRM_PUBLISH)
+override MANUAL_PDF_PUBLICATION_INTENT_SHA256 := $(value MANUAL_PDF_PUBLICATION_INTENT_SHA256)
+export MANUAL_RELEASE_SELECTOR MANUAL_PDF_LANG MANUAL_PDF_PUBLISH_DRY_RUN MANUAL_PDF_CONFIRM_PUBLISH MANUAL_PDF_PUBLICATION_INTENT_SHA256 MANUAL_PDF_PREVIEW_CLEAN_DRY_RUN MANUAL_PDF_PREVIEW_CONFIRM_CLEAN MANUAL_PDF_PREVIEW_RECEIPT_SHA256
 UNALTRAWEB_WORKER_ROLE ?=
 UNALTRAWEB_WORKER_PROJECT ?=
 UNALTRAWEB_WORKER_TOKEN ?=
@@ -79,8 +93,8 @@ ifneq ($(strip $(SCIMAGO_INPUT)),)
 SCIMAGO_ARGS += --input "$(SCIMAGO_INPUT)"
 endif
 
-.PHONY: distribution-check distribution-release-check distribution-doctor workflow-check wheel-check gem-check reproducible-site-check docs-build docs-serve docs-publish docs-down metrics-scimago-fetch metrics-update metrics-update-all metrics-check manual-pdf-image manual-pdf-image-dev manual-pdf-preflight manual-pdf-status manual-pdf-check manual-pdf-build manual-pdf-publish manual-pdf-sync manual-release-status manual-release-check manual-release-prepare manual-compute-status manual-compute-check manual-compute-render manual-compute-render-figures manual-compute-image-python manual-compute-image-r manual-compute-images manual-compute-rstudio compute-base-image-python compute-base-image-r web-capture-status web-capture-check web-capture-render web-capture-image visualization-status visualization-check visualization-render
-.PHONY: mcp-runtime-image mcp-image mcp-build mcp-check mcp-smoke mcp-smoke-prebuilt mcp-stdio mcp-down mcp-down-all mcp-list-tools mcp-starter-templates mcp-new-web mcp-initialize-site mcp-site-context mcp-profile-check mcp-manual-source-quality-check mcp-manual-editorial-quality-check mcp-manual-authoring-capabilities mcp-manual-computation-status mcp-manual-computation-check mcp-manual-computation-render mcp-manual-computation-render-figures mcp-web-capture-status mcp-web-capture-check mcp-web-capture-render mcp-manual-pdf-status mcp-manual-pdf-build mcp-manual-pdf-publish mcp-manual-release-status mcp-manual-release-check mcp-manual-release-prepare mcp-profile-prune-plan mcp-profile-prune mcp-content-inventory mcp-language-policy mcp-content-approval-inventory mcp-translation-plan mcp-bibliography-inventory mcp-bibliometrics-check mcp-build-health
+.PHONY: distribution-check distribution-release-check distribution-doctor workflow-check wheel-check gem-check reproducible-site-check docs-build docs-serve docs-publish docs-down metrics-scimago-fetch metrics-update metrics-update-all metrics-check manual-pdf-image manual-pdf-image-dev manual-pdf-preflight manual-pdf-status manual-pdf-check manual-pdf-build manual-pdf-publish manual-pdf-publish-worker manual-pdf-sync manual-release-status manual-release-check manual-release-prepare manual-compute-status manual-compute-check manual-compute-render manual-compute-render-figures manual-compute-image-python manual-compute-image-r manual-compute-images manual-compute-rstudio compute-base-image-python compute-base-image-r web-capture-status web-capture-check web-capture-render web-capture-image visualization-status visualization-check visualization-render
+.PHONY: mcp-runtime-image mcp-image mcp-build mcp-check mcp-smoke mcp-smoke-prebuilt mcp-stdio mcp-down mcp-down-all mcp-list-tools mcp-starter-templates mcp-new-web mcp-initialize-site mcp-site-context mcp-profile-check mcp-manual-source-quality-check mcp-manual-editorial-quality-check mcp-manual-authoring-capabilities mcp-manual-computation-status mcp-manual-computation-check mcp-manual-computation-render mcp-manual-computation-render-figures mcp-web-capture-status mcp-web-capture-check mcp-web-capture-render mcp-manual-pdf-status mcp-manual-pdf-build mcp-manual-pdf-preview-prepare mcp-manual-pdf-preview-clean mcp-manual-pdf-publish mcp-manual-release-status mcp-manual-release-check mcp-manual-release-prepare mcp-profile-prune-plan mcp-profile-prune mcp-content-inventory mcp-language-policy mcp-content-approval-inventory mcp-translation-plan mcp-bibliography-inventory mcp-bibliometrics-check mcp-build-health
 
 REPOSITORY_CONTEXT_TARGETS := distribution-doctor manual-compute-status manual-compute-check manual-compute-render manual-compute-render-figures manual-compute-image-python manual-compute-image-r manual-compute-images manual-compute-rstudio web-capture-status web-capture-check web-capture-render visualization-status visualization-check visualization-render manual-pdf-preflight manual-pdf-status manual-pdf-check manual-pdf-build manual-pdf-publish manual-pdf-sync manual-release-status manual-release-check manual-release-prepare metrics-scimago-fetch metrics-update metrics-update-all metrics-check
 $(REPOSITORY_CONTEXT_TARGETS): override PROJECT = $${MCP_CONSUMER_WORKSPACE:-$$PWD}
@@ -107,19 +121,24 @@ gem-check: ## Build the gem and verify its package-owned contract files
 reproducible-site-check: ## Build the same fixed-epoch Jekyll fixture twice and compare every output
 	@DOCKER_IMAGE="$(DOCKER_IMAGE)" $(PYTHON) scripts/test_reproducible_jekyll_build.py
 
-mcp-runtime-image: ## Build the reusable Jekyll runtime used by the MCP
+mcp-runtime-image mcp-image mcp-check mcp-smoke: MCP_RUNTIME_IMAGE = unaltraweb:dev
+mcp-runtime-image mcp-image mcp-check mcp-smoke: MCP_IMAGE = unaltraweb-mcp:dev
+mcp-smoke: MCP_SMOKE_MANUAL_PDF_IMAGE = $(MANUAL_PDF_DEV_IMAGE)
+
+mcp-runtime-image: ## Build the local development Jekyll runtime used by the MCP
 	docker build --network "$(MCP_DOCKER_BUILD_NETWORK)" -t "$(MCP_RUNTIME_IMAGE)" .
 
-mcp-image: mcp-runtime-image ## Build the Dockerized FastMCP control plane
+mcp-image: mcp-runtime-image ## Build the local development FastMCP control plane
 	docker build --network "$(MCP_DOCKER_BUILD_NETWORK)" --build-arg "UNALTRAWEB_RUNTIME_IMAGE=$(MCP_RUNTIME_IMAGE)" -t "$(MCP_IMAGE)" -f Dockerfile.mcp .
 
-mcp-build: mcp-image ## Prepare the Docker images used by MCP sessions, builds, and previews
+mcp-build: ## Prepare the reviewed release image used by MCP sessions, builds, and previews
+	@docker image inspect "$(MCP_RELEASE_IMAGE)" >/dev/null 2>&1 || docker pull "$(MCP_RELEASE_IMAGE)" >/dev/null
 
 mcp-check: mcp-image ## Verify the Dockerized MCP CLI contract
 	docker run --rm --entrypoint unaltraweb-mcp "$(MCP_IMAGE)" version
 
-mcp-smoke: mcp-build ## Build and prove a real MCP stdio connection
-	@$(MAKE) --silent --no-print-directory mcp-smoke-prebuilt MCP_IMAGE="$(MCP_IMAGE)"
+mcp-smoke: mcp-image manual-pdf-image-dev ## Build and prove a real MCP stdio connection
+	@$(MAKE) --silent --no-print-directory mcp-smoke-prebuilt MCP_IMAGE="$(MCP_IMAGE)" MCP_SMOKE_MANUAL_PDF_IMAGE="$(MCP_SMOKE_MANUAL_PDF_IMAGE)"
 
 mcp-smoke-prebuilt: ## Prove a real MCP stdio connection using the selected prebuilt MCP image
 	docker run --rm --user "$(LOCAL_UID):$(LOCAL_GID)" -e HOME=/tmp --entrypoint python3 "$(MCP_IMAGE)" /opt/unaltraweb/test/mcp_smoke.py
@@ -128,16 +147,18 @@ mcp-smoke-prebuilt: ## Prove a real MCP stdio connection using the selected preb
 	image_id=$$(docker image inspect --format '{{.Id}}' "$(MCP_IMAGE)"); \
 	socket_mount=$$(/bin/sh "$(DOCKER_MOUNT_SCRIPT)" "$$docker_socket" /var/run/docker.sock); \
 	project_mount=$$(/bin/sh "$(DOCKER_MOUNT_SCRIPT)" "$(CURDIR)/tmp/mcp-preview-smoke" /workspace); \
+	mirror_mount=$$(/bin/sh "$(DOCKER_MOUNT_SCRIPT)" "$(CURDIR)/tmp/mcp-preview-smoke" "$(CURDIR)/tmp/mcp-preview-smoke"); \
 	docker run --rm --user "$(LOCAL_UID):$(LOCAL_GID)" --group-add "$$socket_group" \
 	  -e HOME=/tmp -e "UNALTRAWEB_DOCKER_ROOT=$(CURDIR)/tmp/mcp-preview-smoke" \
 	  -e "UNALTRAWEB_PROJECT_USER=$(LOCAL_UID):$(LOCAL_GID)" -e "UNALTRAWEB_MCP_IMAGE=$$image_id" \
+	  -e "MANUAL_PDF_IMAGE=$(MCP_SMOKE_MANUAL_PDF_IMAGE)" \
 	  --mount "$$socket_mount" \
-	  --mount "$$project_mount" -w /workspace \
+	  --mount "$$project_mount" --mount "$$mirror_mount" -w /workspace \
 	  --entrypoint python3 "$$image_id" /opt/unaltraweb/test/mcp_preview_smoke.py
 
 mcp-stdio: ## Serve MCP_CONSUMER_WORKSPACE through the Dockerized stdio MCP
 	@test -n "$${MCP_CONSUMER_WORKSPACE:-}" || { printf '%s\n' 'MCP_CONSUMER_WORKSPACE is required' >&2; exit 2; }
-	@exec "$(CURDIR)/scripts/unaltraweb-mcp-bootstrap.sh" --image "$(MCP_IMAGE)"
+	@exec "$(CURDIR)/scripts/unaltraweb-mcp-bootstrap.sh" --image "$(MCP_RELEASE_IMAGE)"
 
 mcp-down: ## Remove MCP resources owned by MCP_CONSUMER_WORKSPACE or MCP_PROJECT_ID
 	@exec "$(CURDIR)/scripts/unaltraweb-mcp-cleanup.sh"
@@ -202,6 +223,12 @@ mcp-manual-pdf-status: ## Inspect manual PDF state for PROJECT
 mcp-manual-pdf-build: ## Build the manual PDF for PROJECT
 	@PYTHONPATH="$(CURDIR)/src" $(PYTHON) -m unaltraweb_mcp.cli --project "$(PROJECT)" mcp manual-pdf-build --language "$(MANUAL_PDF_LANG)"
 
+mcp-manual-pdf-preview-prepare: ## Stage ignored PDF and cover copies for local Jekyll review
+	@PYTHONPATH="$(CURDIR)/src" $(PYTHON) -m unaltraweb_mcp.cli --project "$(PROJECT)" mcp manual-pdf-preview-prepare
+
+mcp-manual-pdf-preview-clean: ## Dry-run cleanup of receipt-owned PDF preview copies
+	@PYTHONPATH="$(CURDIR)/src" $(PYTHON) -m unaltraweb_mcp.cli --project "$(PROJECT)" mcp manual-pdf-preview-clean $(if $(filter 0 false FALSE no NO n N,$(MANUAL_PDF_PREVIEW_CLEAN_DRY_RUN)),--apply,) $(if $(filter 1 true TRUE yes YES y Y,$(MANUAL_PDF_PREVIEW_CONFIRM_CLEAN)),--confirm-clean,) --expected-receipt-sha256 "$${MANUAL_PDF_PREVIEW_RECEIPT_SHA256}"
+
 mcp-manual-pdf-publish: ## Dry-run manual PDF publication for PROJECT
 	@PYTHONPATH="$(CURDIR)/src" $(PYTHON) -m unaltraweb_mcp.cli --project "$(PROJECT)" mcp manual-pdf-publish --language "$(MANUAL_PDF_LANG)"
 
@@ -365,10 +392,23 @@ manual-pdf-check: ## Reject stale or unpublished manual PDF artefacts without Do
 manual-pdf-build: manual-pdf-preflight ## Build manual PDFs and cover previews under tmp
 	$(call run_manual_pdf_worker,build)
 
-manual-pdf-publish: manual-pdf-preflight ## Copy built PDF artefacts to configured public paths
+manual-pdf-publish-worker: ## Internal worker target used by provenance-aware publication
+	@if test -z "$(filter 1 true TRUE yes YES y Y,$(MANUAL_PDF_PUBLISH_DRY_RUN))"; then \
+	  test "$(MANUAL_PDF_CONFIRM_PUBLISH)" = 1 || { printf '%s\n' 'Real publication workers require MANUAL_PDF_CONFIRM_PUBLISH=1.' >&2; exit 2; }; \
+	  test -n "$(UNALTRAWEB_WORKER_TOKEN)" || { printf '%s\n' 'Real publication workers must be launched by the provenance-aware controller.' >&2; exit 2; }; \
+	  test -n "$(MANUAL_PDF_PUBLICATION_INTENT_SHA256)" || { printf '%s\n' 'Real publication workers require a controller publication intent.' >&2; exit 2; }; \
+	  PYTHONPATH="$(CURDIR)/src" /usr/bin/python3 -c 'import sys; from pathlib import Path; from unaltraweb_mcp.manual_pdf_preview import validate_publication_worker; validate_publication_worker(Path(sys.argv[1]), sys.argv[2], sys.argv[3])' "$(PROJECT_ROOT)" "$(MANUAL_PDF_PUBLICATION_INTENT_SHA256)" "$(MANUAL_PDF_LANG)"; \
+	fi
+	@$(MAKE) --silent --no-print-directory manual-pdf-preflight
+	@if test -z "$(filter 1 true TRUE yes YES y Y,$(MANUAL_PDF_PUBLISH_DRY_RUN))"; then \
+	  PYTHONPATH="$(CURDIR)/src" /usr/bin/python3 -c 'import sys; from pathlib import Path; from unaltraweb_mcp.manual_pdf_preview import validate_publication_worker; validate_publication_worker(Path(sys.argv[1]), sys.argv[2], sys.argv[3])' "$(PROJECT_ROOT)" "$(MANUAL_PDF_PUBLICATION_INTENT_SHA256)" "$(MANUAL_PDF_LANG)"; \
+	fi
 	$(call run_manual_pdf_worker,publish,$(if $(filter 1 true TRUE yes YES y Y,$(MANUAL_PDF_PUBLISH_DRY_RUN)),--dry-run,))
 
-manual-pdf-sync: manual-pdf-preflight ## Build and copy changed manual PDFs to their public paths
+manual-pdf-publish: ## Copy built PDF artefacts through provenance-aware MCP orchestration
+	@PYTHONPATH="$(CURDIR)/src" $(PYTHON) -m unaltraweb_mcp.cli --project "$(PROJECT_ROOT)" mcp manual-pdf-publish --language "$${MANUAL_PDF_LANG}" --release-selector "$${MANUAL_RELEASE_SELECTOR}" $(if $(filter 0 false FALSE no NO n N,$(MANUAL_PDF_PUBLISH_DRY_RUN)),--apply,) $(if $(filter 1 true TRUE yes YES y Y,$(MANUAL_PDF_CONFIRM_PUBLISH)),--confirm-publish,)
+
+manual-pdf-sync: manual-pdf-preflight ## Build and copy only changed manual PDFs; disabled configurations remain a no-op
 	$(call run_manual_pdf_worker,sync)
 
 define run_manual_release_worker

data/README.md

@@ -26,17 +26,20 @@ See [Edit Safely In GitHub Web](docs/_documentation/en/06-github-web-editing.md)
 
 ## Technical Overview
 
-The core packages shared layouts, includes, Sass, assets, Jekyll plugins, bibliometric tooling, multilingual behaviour, theme modes and reusable GitHub Actions workflows. Child sites should stay thin and consume this core through the `unaltraweb` gem.
+The core packages shared layouts, includes, Sass, assets, Jekyll plugins, bibliometric tooling, multilingual behaviour, theme modes and reusable GitHub Actions workflows. Child sites stay thin: they keep content, configuration and local assets while reusable implementation remains in this repository.
+
+The default distribution is Docker-first. Generated sites run their normal build, serve and test commands in the published `unaltraweb-mcp` image, which contains the Python control plane and the reviewed core at `/opt/unaltraweb`. The `unaltraweb` gem on RubyGems and the `unaltraweb-mcp` wheel on PyPI remain supported native interoperability channels, not additional requirements for the Docker path.
 
 `unaltremanual` sites can also build language-specific PDF editions and matching web-cover images in an isolated Pandoc/XeLaTeX container. PDF status is offline; build and local review are available through Make and the MCP control plane. When PDF output is enabled, default generated PDF and cover outputs are not versioned. The selected `latest` or stable selector is rendered into both the website and PDF metadata.
 
 ## Current Status
 
-- The core builds successfully as a standalone Jekyll site through Docker.
-- The repository is packaged as the `unaltraweb` gem and publishes the shared Docker runtime image as `ghcr.io/dosquartsdedocs/unaltraweb`.
-- The modular MCP wheel contains profile-specific scaffolds, the versioned component BOM, doctor, and local inspection; it does not bundle the gem, factory checkout, worker images, or companion renderers.
+- Public release `v0.4.0` provides the Docker images, Ruby gem and Python wheel as one receipt-bound distribution.
+- `ghcr.io/dosquartsdedocs/unaltraweb-mcp` is the canonical normal local runtime for generated sites; `ghcr.io/dosquartsdedocs/unaltraweb` is its lower-level Jekyll runtime base.
+- The Ruby gem supports native Bundler/Jekyll consumers. The modular MCP wheel supports native creation and inspection, and does not bundle the gem, factory checkout, worker images or companion renderers.
+- PDF, browser-capture and computation environments remain separate images so the normal site image does not carry every heavy toolchain.
 - The companion `../unaltraweb-template` repository remains the full-profile integration fixture and visual demo.
-- The project is still pre-release. Some inherited `al-folio` implementation details remain while the core is being generalized.
+- The project is in its early `0.x` release series. Some inherited `al-folio` implementation details remain while the core is being generalized.
 
 ## Repository Roles
 
@@ -65,7 +68,19 @@ unaltraweb:
 
 ## Quick Start
 
-Create a child site with the `new_web` MCP tool or the package CLI:
+Create a child site directly with the public Docker image:
+
+```bash
+mkdir my-site && \
+docker run --rm --network none --user "$(id -u):$(id -g)" -e HOME=/tmp \
+  --mount "type=bind,src=${PWD}/my-site,dst=/workspace" \
+  ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:389bc585cdb4fc89d3372f4896a55fe26e15df38b46bc114ce44fdb3f1c8deb9 \
+  --project /workspace new-web --site-profile unaltreselfie --title "My site" --default-lang en
+```
+
+The chained `mkdir` requires a new destination, the digest binds creation to the reviewed `v0.4.0` receipt, and `--network none` keeps scaffold generation offline.
+
+If Python package tooling is already available, the PyPI adapter exposes the equivalent native command:
 
 ```bash
 unaltraweb-mcp --project ./my-site new-web --site-profile unaltreselfie --title "My site" --default-lang en
@@ -77,7 +92,9 @@ From this factory checkout, the equivalent command is:
 MCP_CONSUMER_WORKSPACE=./my-site make mcp-new-web NEW_WEB_PROFILE=unaltreselfie SITE_TITLE="My site" DEFAULT_LANG=en
 ```
 
-The operation uses only assets shipped in `unaltraweb_mcp`, preflights all managed paths, writes `.unaltraweb/scaffold.json`, and never overwrites differing files. Later `scaffold_sync` calls can update unchanged baseline controls or adopt exact current package bytes, including the collaboration contract, Dependabot policy, pull-request template, dependency pins, and deploy caller. They never touch config, README prose, agent guidance, or content. `dosquartsdedocs/unaltraweb-template` remains available when a full multi-profile demo with Playwright tests is more useful than a clean profile-specific site.
+All three creation paths use only assets shipped in `unaltraweb_mcp`, either in the image, wheel or factory checkout. They preflight all managed paths, write `.unaltraweb/scaffold.json`, and never overwrite differing files. Later `scaffold_sync` calls can update unchanged baseline controls or adopt exact current package bytes, including the collaboration contract, Dependabot policy, pull-request template, dependency pins, and deploy caller. Local customizations are preserved when the package has not changed that file since the baseline; conflicting local/upstream changes remain blocked. Synchronization never touches config, README prose, agent guidance, or content. `dosquartsdedocs/unaltraweb-template` remains available when a full multi-profile demo with Playwright tests is more useful than a clean profile-specific site.
+
+The guided update flow reports `site_context.update_status` at session start so the agent can explain available package/scaffold changes and ask whether to apply them. Accepted updates use the existing `scaffold_sync` transaction with the reviewed `plan_sha256` as `expected_plan_sha256`; an older MCP cannot downgrade known newer consumer pins. See [Guided Consumer Updates](docs/_documentation/en/03-usage.md#guided-consumer-updates). This functionality needs a reviewed MCP/package release containing it: updating a discovery checkout alone does not replace the already-running or digest-pinned public image.
 
 After creation, there are two supported editing paths:
 
@@ -112,11 +129,13 @@ make docs-serve DOCKER_IMAGE=unaltraweb:dev
 make docs-build DOCKER_IMAGE=unaltraweb:dev
 ```
 
-The pending distribution contract selects `ghcr.io/dosquartsdedocs/unaltraweb:0.3.0` as the eventual consumer runtime; it does not assert that this remote tag exists yet. The mutable `:main` channel is reserved for explicit maintainer testing; locally built core images use the `:dev` name. The gem remains the source of theme code.
+The public distribution contract selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0` for normal generated-site commands. `MCP_RELEASE_IMAGE` pins the reviewed MCP digest from the same `v0.4.0` receipt for gContExt (formerly ContExt), the GNOME Shell extension. The mutable `:main` channel is reserved for explicit maintainer testing; locally built core images use the `:dev` name.
+
+The lower-level `unaltraweb` image supplies Ruby, Jekyll and runtime dependencies. The MCP image layers the full reviewed factory and installed Python package on top; generated Make targets load the theme as a path gem from `/opt/unaltraweb`. Native Bundler consumers can instead resolve the independently published gem, and native Python users can install the wheel.
 
 The independent manual PDF runtime is built from `scripts/manual/Dockerfile`; it is deliberately separate from the Jekyll image so normal site builds do not carry Pandoc and TeX Live.
 
-The GHCR image is a shared runtime, not the source of the theme. Publish it only through the manual Docker image workflow when runtime dependencies change. That workflow does not receive package-write permissions until its strict release preflight, source/package tests, image builds, MCP smoke test and docs build have all passed.
+Publish images only through the manual Docker workflows. A core-code change requires a new MCP image, while a base-runtime change also requires a new lower-level runtime image. Candidate builds receive package-write authority only after preflight and never execute their outputs; broad aliases move only after a separate read-only job tests the exact digests, and the final package-write job executes no candidate.
 
 When running the core and the template profiles together, keep `unaltraweb` on port `4000` and the template profile servers on `4001` through `4004`.
 
@@ -148,14 +167,16 @@ Doctor is offline. The optional `--docker` mode only calls local Docker version/
 
 ## Global Dockerized MCP
 
-`unaltraweb` provides one global, on-demand stdio MCP whose containers are scoped to the current consumer workspace. Each client session gets an independent Docker-generated container name plus stable factory, role, and project labels, so concurrent sessions for the same project do not collide. The launcher reuses or attempts to pull the selected `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.3.0` image; while that component is `pending`, the pull may fail rather than silently building under the remote release reference. To build and test the image explicitly from this checkout instead:
+`unaltraweb` provides one global, on-demand stdio MCP whose containers are scoped to the current consumer workspace. Each client session gets an independent Docker-generated container name plus stable factory, role, and project labels, so concurrent processes for the same project do not collide. This runtime capability does not authorize overlapping editors: the collaboration control plane uses one primary mutable checkout and one active editing session per repository. gContExt runs `mcp-build` to prepare the exact public image selected by `MCP_RELEASE_IMAGE`, and `mcp-stdio` launches that same digest. To build and test a development image explicitly from this checkout instead:
 
 ```bash
-make mcp-build
-make mcp-smoke
+make mcp-image
+make mcp-smoke-prebuilt MCP_IMAGE=unaltraweb-mcp:dev
 ```
 
-ContExt reads the canonical manifest transport `make -C ${factoryRoot} mcp-stdio` and supplies `MCP_CONSUMER_WORKSPACE=${workspaceFolder}` through the process environment. The manifest continues to use `make`, an allowed container host launcher, but no consumer path is parsed by Make or interpolated into shell source. An equivalent direct launch is:
+Source builds use the explicit local names `unaltraweb:dev` and `unaltraweb-mcp:dev` by default, avoiding shadowed public references. After each coordinated release, `MCP_RELEASE_IMAGE` advances to its recorded digest in a separate post-release change; candidate source never embeds its unknown future self-digest.
+
+gContExt reads the canonical manifest transport `make -C ${factoryRoot} mcp-stdio` and supplies `MCP_CONSUMER_WORKSPACE=${workspaceFolder}` through the process environment. The manifest continues to use `make`, an allowed container host launcher, but no consumer path is parsed by Make or interpolated into shell source. The collaboration control plane requests one top-level MCP, selects its declared dependency closure, preserves unrelated user registrations, and runs a read-only checkout preflight before editing. When a process-held cooperative lease is required, it launches the editing command through its `exec` wrapper; it never manipulates Git worktrees implicitly. An equivalent direct MCP launch is:
 
 ```bash
 MCP_CONSUMER_WORKSPACE="$PWD" make --silent --no-print-directory -C /path/to/unaltraweb mcp-stdio
@@ -163,7 +184,7 @@ MCP_CONSUMER_WORKSPACE="$PWD" make --silent --no-print-directory -C /path/to/una
 
 Replace `/path/to/unaltraweb` with this checkout's absolute path and restart the client after changing its configuration. Each session canonicalizes the inherited workspace after launch, then mounts it at `/workspace` and at its canonical host path, so Docker-backed authoring tools pass valid bind paths to the host daemon. `build_site` runs Jekyll directly in that MCP runtime and returns the offline HTML audit. `preview_start`, `preview_status`, and `preview_stop` manage one labelled preview container per project. By default, Docker publishes container port `4000` on a free loopback host port, so previews from distinct workspaces can run concurrently; pass a nonzero `port` only when a fixed host port is required. A running preview created by the former fixed-port default remains idempotently usable until stopped, after which the dynamic default applies. `http_check` derives its origin only from that owned preview and never accepts an arbitrary URL.
 
-Dependency preparation builds images and required companions only; it does not initialize a consumer website, and companion `init` aggregation is disabled. Create a site explicitly with the `new_web` MCP tool. To clean up one consumer project, pass the same canonical project path used at launch:
+Dependency preparation ensures the selected release image and prepares required companions only; it does not initialize a consumer website, and companion `init` aggregation is disabled. Create a site explicitly with the `new_web` MCP tool. To clean up one consumer project, pass the same canonical project path used at launch:
 
 ```bash
 MCP_CONSUMER_WORKSPACE=/path/to/consumer make mcp-down
@@ -176,6 +197,16 @@ env -u MCP_CONSUMER_WORKSPACE MCP_PROJECT_ID=0123456789abcdef make mcp-down
 When the workspace is live, a supplied `MCP_PROJECT_ID` must match its canonical path. A retained ID is accepted only without a live workspace, making stale-resource cleanup explicit. Cleanup selects only resources carrying both `io.context.mcp-factory=unaltraweb` and that project's stable `io.context.mcp-project` label. Maintainers can deliberately clean every labelled unaltraweb MCP resource with `make mcp-down-all`; neither target deletes images or touches unlabelled containers and networks.
 Replace the example retained ID with the 16-hex value from that project's `io.context.mcp-project` Docker label.
 
+## Workspace Path Policies
+
+For consumer filesystem ownership, the discovery manifest declares literal
+`workspace_rule.path_policies`. The central manager's read-only `workspace-check`
+checks the selected consumer plus the installable `diavisuals` and `vegavisuals`
+dependency closure. It does not run provider commands or clean files. In
+particular, ignored PDF recovery state and `tmp` require explicit review, not
+blanket deletion. See [Workspace Path Policies And Consumer Updates](docs/_documentation/en/43-workspace-path-policies.md)
+for the audited paths, package/scaffold compatibility and migration procedure.
+
 ## Bibliometrics
 
 Normal Jekyll builds must stay static. External metrics are fetched only through explicit update commands and written back to local data files before build time.
@@ -221,6 +252,8 @@ CodeQL separately analyzes JavaScript/TypeScript, Python and Ruby on pull reques
 
 Core artifact workflows run `distribution-check` while selected candidates are truthfully `pending`, validate the selected ref against the BOM version, and keep their preflight jobs credential-free. Once the final source and release intent are reviewed, mark its components `ready` and commit that state. Runtime, MCP, and manual PDF publication separates authority across a signing/package-write build job that never runs candidates, a read-only test job that verifies GitHub-signed digest/source provenance and removes GHCR credentials before execution, and a package-write promotion job that executes no candidate. Every image is built once under only its SHA tag; only the exact digests that pass all Ruby, PDF, reproducibility, MCP, and docs gates can reach verified `sha-*`, `main`, and `latest` aliases. GHCR does not make the initial absence lookup and later tag write atomic, so the signed tested digest, not a claim of compare-and-swap no-clobber, is the trust anchor. Record those digests and package checksums in a versioned `release-candidates.json` child commit; validation requires that receipt to be the only change. After `distribution-release-check`, tag the receipt commit. The tag-only job verifies SHA-tag equality, signed provenance and the revision label against the receipt's `source_commit`, then promotes only the receipt's manifests to checked semver aliases without rebuilding or executing them. `released` remains available for already-published components; released containers other than the self-describing MCP must be digest-pinned. Package preparation never uploads to RubyGems or PyPI, creates a GitHub release, tags the repository or publishes an image; those operations require separate explicit maintainer approval.
 
+After tagging, maintainers can use the manual `Publish language packages` workflow with PyPI and RubyGems Trusted Publishing. Its read-only job binds a successful package-preparation run and immutable artifact to the release receipt, verifies the exact file inventory and SHA-256 values, and only then passes one wheel and one gem to separate environment-protected OIDC jobs. Those jobs do not checkout source, rebuild candidates, receive repository write authority, or use stored registry tokens. See [Distribution](docs/_documentation/en/40-distribution.md) for the one-time publisher setup and dispatch inputs.
+
 ## Attribution
 
 `unaltraweb` started from the open-source `al-folio` Jekyll theme and is being refactored into a self-owned reusable core for `dosquartsdedocs` sites. Retain upstream attribution where inherited code remains relevant.

data/_plugins/figure_captions.rb

@@ -8,6 +8,7 @@ module Unaltraweb
 
     PANEL_SEQUENCE = ("a".."z").to_a.freeze
     FENCED_CODE_BLOCK = /^[ \t]*(`{3,}|~{3,})[^\n]*\n.*?^[ \t]*\1[ \t]*$/m.freeze
+    CAPTION_SOURCE_ATTRIBUTE = /(?:\A|\s)data-caption-source\s*=\s*(?:"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|[^\s}]+)/.freeze
 
     def enabled?(site)
       config = config_for(site)
@@ -104,6 +105,7 @@ module Unaltraweb
               out << figure_html(
                 img: %(<img src="#{h(url.strip)}" alt="#{h(strip_liquid(alt))}"#{attrs.empty? ? "" : " #{attrs}"}>),
                 caption: render_inline_markdown(caption),
+                source: render_inline_markdown(kramdown_attr_value(attrs_raw, "data-caption-source")),
                 label: label,
                 lang: lang,
                 count: count,
@@ -196,7 +198,7 @@ module Unaltraweb
 
       line_end = source.index("\n", start_index) || source.length
       opening = source[start_index...line_end]
-      match = opening.match(/\A:::\s*subfigures(?:\s+([^\s"]+))?(?:\s+"([^"]+)")?\s*\z/)
+      match = opening.match(/\A:::\s*subfigures(?:\s+([^\s"{]+))?(?:\s+"([^"]+)")?(?:\s+(\{:[^\n]*\}))?\s*\z/)
       return nil unless match
 
       body_start = line_end == source.length ? line_end : line_end + 1
@@ -206,6 +208,7 @@ module Unaltraweb
       {
         layout: match[1].to_s,
         caption: match[2].to_s,
+        attrs: match[3],
         body: source[body_start...closing.begin(0)],
         raw: source[start_index...closing.end(0)],
         end_idx: closing.end(0)
@@ -217,7 +220,7 @@ module Unaltraweb
 
       line_end = source.index("\n", start_index) || source.length
       opening = source[start_index...line_end]
-      match = opening.match(/\A:::\s*table(?:\s+"([^"]+)")?\s*\z/)
+      match = opening.match(/\A:::\s*table(?:\s+"([^"]+)")?(?:\s+(\{:[^\n]*\}))?\s*\z/)
       return nil unless match
 
       body_start = line_end == source.length ? line_end : line_end + 1
@@ -226,6 +229,7 @@ module Unaltraweb
 
       {
         caption: match[1].to_s,
+        attrs: match[2],
         body: source[body_start...closing.begin(0)],
         raw: source[start_index...closing.end(0)],
         end_idx: closing.end(0)
@@ -271,7 +275,7 @@ module Unaltraweb
           image = images[slot[:index]]
           attrs = kramdown_attrs_to_html(image[:attrs])
           panel_attrs = subfigure_panel_attrs(image[:attrs])
-          caption = render_inline_markdown(image[:caption])
+          caption = caption_content(render_inline_markdown(image[:caption]), render_inline_markdown(kramdown_attr_value(image[:attrs], "data-caption-source")))
           panel = h(slot[:label])
           caption_html = caption.to_s.strip.empty? ? "" : %Q{<p class="md-subfigure-caption"><span class="md-subfigure-label">#{panel}</span> #{caption}</p>}
           %Q{<div class="md-subfigure" data-panel="#{panel}"#{panel_attrs}>#{caption_html}<img src="#{h(image[:url].strip)}" alt="#{h(strip_liquid(image[:alt]))}"#{attrs.empty? ? "" : " #{attrs}"}></div>}
@@ -279,7 +283,7 @@ module Unaltraweb
         %Q{<div class="md-subfigure-row" data-count="#{row.length}">\n#{cells}\n</div>}
       end.join("\n")
 
-      clean_caption = render_inline_markdown(block[:caption]).to_s.strip
+      clean_caption = caption_content(render_inline_markdown(block[:caption]), render_inline_markdown(kramdown_attr_value(block[:attrs], "data-caption-source")))
       figcaption = clean_caption.empty? ? "" : %(<figcaption class="md-figcaption"><span class="figlabel">#{h(label)} #{count}.</span> #{clean_caption}</figcaption>)
 
       html = <<~HTML.strip
@@ -301,7 +305,7 @@ module Unaltraweb
       return [block[:raw], count] unless parsed_table
 
       count += 1
-      caption = render_inline_markdown(block[:caption]).to_s.strip
+      caption = caption_content(render_inline_markdown(block[:caption]), render_inline_markdown(kramdown_attr_value(block[:attrs], "data-caption-source")))
       caption_html = caption.empty? ? "" : %(<figcaption class="md-table-caption"><span class="figlabel">#{h(label)} #{count}.</span> #{caption}</figcaption>)
       thead = table_row_html(parsed_table[:headers], "th", parsed_table[:alignments])
       tbody = parsed_table[:rows].map { |row| table_row_html(row, "td", parsed_table[:alignments]) }.join("\n")
@@ -520,7 +524,7 @@ module Unaltraweb
 
       attrs_raw = nil
       if source[index] == "{"
-        close_index = source.index("}", index)
+        close_index = attribute_block_end(source, index)
         return nil unless close_index
 
         attrs_raw = source[index..close_index].sub(/\A\{:\s*/, "{").strip
@@ -530,6 +534,28 @@ module Unaltraweb
       { alt: alt, url_and_title: url_and_title, attrs: attrs_raw, end_idx: index }
     end
 
+    def attribute_block_end(source, index)
+      quote = nil
+      index += 1
+      while index < source.length
+        char = source[index]
+        if char == "\\"
+          index += 2
+          next
+        elsif quote
+          quote = nil if char == quote
+        elsif char == '"' || char == "'"
+          quote = char
+        elsif char == "}"
+          return index
+        elsif char == "\n"
+          return nil
+        end
+        index += 1
+      end
+      nil
+    end
+
     def read_balanced(source, index, open_char, close_char)
       depth = 1
       start = index
@@ -594,10 +620,10 @@ module Unaltraweb
 
     def kramdown_attr_value(raw, name)
       source = raw.to_s.strip.sub(/\A\{:\s*/, "").sub(/\A\{\s*/, "").sub(/\s*\}\z/, "")
-      match = source.match(/(?:\A|\s)#{Regexp.escape(name)}\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s}]+))/)
+      match = source.match(/(?:\A|\s)#{Regexp.escape(name)}\s*=\s*(?:"((?:\\.|[^"\\])*)"|'((?:\\.|[^'\\])*)'|([^\s}]+))/)
       return nil unless match
 
-      match[1] || match[2] || match[3]
+      (match[1] || match[2] || match[3]).gsub(/\\(["'\\])/, '\1')
     end
 
     def split_url_and_title(value)
@@ -630,6 +656,7 @@ module Unaltraweb
         figure_html(
           img: img_tag,
           caption: render_inline_markdown(CGI.unescapeHTML(caption)),
+          source: render_inline_markdown(CGI.unescapeHTML(extract_attr(img_tag, "data-caption-source").to_s)),
           label: label,
           lang: lang,
           count: count,
@@ -639,10 +666,17 @@ module Unaltraweb
       end
     end
 
-    def figure_html(img:, caption:, label:, lang:, count:, classes: ["md-figure"], attrs: "")
+    def caption_content(caption, source = "")
+      parts = []
+      parts << %(<span class="md-caption-text">#{caption.to_s.strip}</span>) unless caption.to_s.strip.empty?
+      parts << %(<span class="md-caption-source">#{source.to_s.strip}</span>) unless source.to_s.strip.empty?
+      parts.join(" ")
+    end
+
+    def figure_html(img:, caption:, label:, lang:, count:, classes: ["md-figure"], attrs: "", source: "")
       classes = Array(classes)
       classes = ["md-figure"] if classes.empty?
-      clean_caption = caption.to_s.strip
+      clean_caption = caption_content(caption, source)
       figcaption = if clean_caption.empty?
         ""
       else
@@ -736,6 +770,9 @@ module Unaltraweb
       source = raw.to_s.strip.sub(/\A\{:\s*/, "").sub(/\A\{\s*/, "").sub(/\s*\}\z/, "")
       return "" if source.empty?
 
+      # Credits are visible caption content, not attributes that can acquire
+      # nested HTML quotes when Liquid citations are expanded later.
+      source = source.gsub(CAPTION_SOURCE_ATTRIBUTE, " ")
       source = source.tr("“”’‘", %q{""''})
       classes = []
       id = nil

data/_sass/_documentation.scss

@@ -1461,7 +1461,9 @@ html[data-theme="cafe"] .site-profile-unaltredocs .documentation-sidebar-logo-ca
   flex: 1 0 auto;
 }
 
-.documentation-content table {
+// Rouge uses a table for its gutter and code. Its preformatted whitespace and
+// sizing belong to .uw-code-block, not to prose/data-table wrapping rules.
+.documentation-content table:not(.rouge-table) {
   display: block;
   width: max-content;
   min-width: 100%;
@@ -1470,8 +1472,8 @@ html[data-theme="cafe"] .site-profile-unaltredocs .documentation-sidebar-logo-ca
   overflow-x: auto;
 }
 
-.documentation-content table th,
-.documentation-content table td {
+.documentation-content table:not(.rouge-table) th,
+.documentation-content table:not(.rouge-table) td {
   overflow-wrap: normal;
   word-break: normal;
 }
@@ -1485,8 +1487,8 @@ html[data-theme="cafe"] .site-profile-unaltredocs .documentation-sidebar-logo-ca
   overflow: visible;
 }
 
-.documentation-content table a,
-.documentation-content table code {
+.documentation-content table:not(.rouge-table) a,
+.documentation-content table:not(.rouge-table) code {
   white-space: normal;
   overflow-wrap: break-word;
   word-break: normal;

data/_sass/_manual.scss

@@ -1201,6 +1201,13 @@ html[data-theme="dark"] .md-table {
   text-align: center;
 }
 
+.md-caption-source {
+  font-size: 0.92em;
+  font-style: italic;
+  font-weight: normal;
+  color: var(--global-text-color);
+}
+
 .figlabel {
   display: inline-flex;
   min-height: 1.45rem;

data/docs/_documentation/en/02-tools.md

@@ -27,13 +27,13 @@ nav_title: Local Tools
 
 ## Local Runtime
 
-The template uses the shared runtime image by default:
+The current public core runtime image is:
 
 ```bash
-ghcr.io/dosquartsdedocs/unaltraweb:0.3.0
+ghcr.io/dosquartsdedocs/unaltraweb:0.4.0
 ```
 
-That image provides Ruby, Bundler, Jekyll system dependencies, ImageMagick, Node for ExecJS and Python tooling needed by local commands. The GHCR package must be public before unauthenticated users can pull it.
+That image provides Ruby, Bundler, Jekyll system dependencies, ImageMagick, Node for ExecJS and Python tooling needed by local commands. Package-generated `v0.4.0` sites select the matching public MCP image for normal local commands. The external integration fixture can advance from its older release pin independently.
 
 ## Generated Site Commands
 
@@ -143,4 +143,4 @@ When the core docs and all template profiles are running together, use this conv
 - Keep deploy workflows as thin `workflow_dispatch` wrappers pinned to a reviewed full commit SHA of `dosquartsdedocs/unaltraweb/.github/workflows/site-deploy.yml`.
 - The optional integration template may retain its local `gh-pages` publishing target for testing that separate workflow.
 - After the first Docker publish, make `ghcr.io/dosquartsdedocs/unaltraweb` public.
-- Confirm `docker pull ghcr.io/dosquartsdedocs/unaltraweb:0.3.0` works without `docker login`.
+- Confirm `docker pull ghcr.io/dosquartsdedocs/unaltraweb:0.4.0` works without `docker login`.