unaltraweb 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f06f4a02759cbf9874ee57a4a15f26f4eb0f5247bad7778b04811b47f7d0cbce
-  data.tar.gz: 8ca81f6f199be8023e4651efe8886499ef67ecf49fbcac6f202a760d0dbfbbcc
+  metadata.gz: e9b1d06c849d3893c28fa69a879e93f56acef7a742aa8e2d8ae7df78fa53d4a2
+  data.tar.gz: '0995fe545e4466b531edc89ed8c8a37ca707e847cc31a8a3acd3647d6b77ecdd'
 SHA512:
-  metadata.gz: e3950450a0339c08473ec1ff3dd1edcdfb5336982990a441c80c94928b9e606bb51a5f4247fa8e09ab89a7621e56debeac4e479b98cdadbb68081caac7253552
-  data.tar.gz: 7253948b9cb8adf42e43cdf45b92c67ed179b3c84d35ceccd280e883727369573e3e01e787b9df98eaf3970f5446b20be2bb17b3e0368f843da36106de9a43d1
+  metadata.gz: 06dd87a7428129eb5ab81655c892abddf159d223aefec27cbdf5e7b5512a72fe7940061313cec5ccee5032ac1b0343cc6b8390617106c59b76d979b109d73cfc
+  data.tar.gz: e2a1cc1fe578e4df0968d1f9b9fbc1abbb0cfed254d38c192e7ec24a55e254adf14c9ed57128255f5a18cbaacf68b4fc64a8c519c99d5f87e1a98798db42a1ca

data/Makefile

@@ -1,9 +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.4.0
-MCP_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0
-MCP_RELEASE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:f3ab5542e6ece56487d4b8238a5e7abd89f36a0b8d87bf7bab19645e3ced1e58
+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
@@ -40,8 +40,8 @@ WEB_CAPTURE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-web-capture@sha256:0bf1b
 WEB_CAPTURE_DEV_IMAGE ?= unaltraweb-web-capture:dev
 WEB_CAPTURE_DOCKER_BUILD_NETWORK ?= default
 VEGAVISUALS_CLI ?=
-DOCKER_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.4.0
-MANUAL_PDF_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf:0.4.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 ?=

data/README.md

@@ -34,7 +34,7 @@ The default distribution is Docker-first. Generated sites run their normal build
 
 ## Current Status
 
-- Public release `v0.3.0` provides the Docker images, Ruby gem and Python wheel as one receipt-bound distribution.
+- 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.
@@ -74,11 +74,11 @@ Create a child site directly with the public Docker image:
 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:f3ab5542e6ece56487d4b8238a5e7abd89f36a0b8d87bf7bab19645e3ced1e58 \
+  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.3.0` receipt, and `--network none` keeps scaffold generation offline.
+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:
 
@@ -92,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
 ```
 
-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. 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:
 
@@ -127,7 +129,7 @@ make docs-serve DOCKER_IMAGE=unaltraweb:dev
 make docs-build DOCKER_IMAGE=unaltraweb:dev
 ```
 
-The candidate distribution contract selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.4.0` for normal generated-site commands after coordinated publication. Until that release completes, `v0.3.0` and the digest-pinned `MCP_RELEASE_IMAGE` remain the public runtime. The mutable `:main` channel is reserved for explicit maintainer testing; locally built core images use the `:dev` name.
+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.
 
@@ -165,7 +167,7 @@ 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 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. ContExt 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:
+`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-image
@@ -174,7 +176,7 @@ make mcp-smoke-prebuilt MCP_IMAGE=unaltraweb-mcp:dev
 
 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.
 
-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. 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:
+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
@@ -195,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.

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 currently published integration template uses the shared `v0.3.0` 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 `v0.4.0` candidate source selects matching `0.4.0` runtime and MCP images for package-generated sites, but consumers must not adopt those references until coordinated publication completes. 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`.

data/docs/_documentation/en/03-usage.md

@@ -88,6 +88,67 @@ The generated repository contains one profile. Create a separate temporary site
 - Reusable workflow updates change optional GitHub build and deploy behavior.
 - Package scaffold changes affect newly generated sites. Existing generated repositories can review `scaffold_sync`, which manages 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` from `.unaltraweb/scaffold.json`. It can adopt bytes that already equal the current package payload without rewriting the file. A conflict aborts the entire apply, and retired entries are removed from the baseline without deleting project files. Synchronization never changes site-owned README/agent guidance, config, or content.
 
+### Guided Consumer Updates
+
+At the start of a site session, the agent inspects `site_context.update_status`.
+The MCP compares the consumer's literal MCP/gem pins and managed baseline with
+the package active in this session. It reports the target version and integration
+tuple, planned paths, preserved customizations, conflicts and a `plan_sha256`.
+This is an offline check, not a query for the newest version on GitHub or PyPI.
+A change to documentation or the factory discovery manifest alone does not imply
+that the consumer needs updating.
+
+When changes are available, the agent explains them and asks whether to proceed.
+After acceptance and the normal issue, branch and path reservation, it calls:
+
+```text
+scaffold_sync(dry_run=false, confirm_sync=true, expected_plan_sha256=<reviewed plan_sha256>)
+```
+
+The equivalent native CLI flow is:
+
+```bash
+unaltraweb-mcp --project . mcp site-context
+unaltraweb-mcp --project . mcp scaffold-sync
+unaltraweb-mcp --project . mcp scaffold-sync --apply --confirm-sync --expected-plan-sha256 <reviewed-sha256>
+```
+
+The confirmation is bound to that consumer, package proposal, configuration and
+managed-file snapshot. If the plan changes, inspect it again before confirming.
+After applying, inspect context again, run `site_check`, then `build_site` or the
+appropriate local build. Manual PDF review still uses managed preparation and
+cleanup. The update does not commit, publish or regenerate editorial artefacts.
+Declining the offer leaves the repository untouched and lets content work continue.
+
+An extra local ignore rule need not block a runtime-pin update: if the incoming
+`.gitignore` still equals its recorded baseline, synchronization preserves the
+customized file and its original package baseline. The same rule applies to other
+managed files. If both the local file and the incoming package changed, there is
+a genuine conflict; no file is overwritten and the entire apply is blocked.
+New-path collisions and missing/unsafe baselines also need review. Known newer
+consumer versions are never silently downgraded by an older MCP. Custom image
+digests and non-literal version expressions are not guessed or resolved online.
+
+The planner and transaction are deterministic Python code. For the same consumer
+path, package/BOM, configuration, baseline and managed bytes, they produce the same
+plan digest and intended control-file bytes. No model generates the replacement
+files. Diagnostic timestamps such as `site_context.generated_at`, temporary names
+and filesystem timestamps are not reproducibility guarantees of the plan.
+
+The agent initiates the check, presents its result, asks for acceptance and
+coordinates the normal Git/review workflow. An automatic offer therefore depends
+on the agent following the session instructions; the MCP does not force a popup
+or run a background update. The CLI commands above use the same engine without
+an agent. Reconciliation of a genuine conflict is a separate reviewed change,
+after which the engine computes a new plan.
+
+Existing consumers receive this flow
+when they reconnect to an MCP release that includes it; their site-owned AGENTS
+and README do not need to be replaced. Publishing that new MCP/package release
+and advancing its reviewed runtime pin remain maintainer actions. An already
+running v0.4.0 image will not gain the feature simply because the factory checkout
+was updated.
+
 ## Safe MCP Editing
 
 `site_source_read`, `site_source_write`, and `site_source_delete` are deliberately restricted to `_config.yml`, Markdown/HTML content collections, YAML/JSON/CSV below `_data/`, and Markdown below `context/`. They do not expose generic filesystem access and cannot mutate workflows, runtime files, core overrides, bibliography, assets, or generated output. Writes default to dry-run and use SHA-256 optimistic concurrency; destructive deletes additionally require explicit confirmation and can never remove `_config.yml`.

data/docs/_documentation/en/13-unaltremanual.md

@@ -166,7 +166,7 @@ Deleting or disabling a source leaves its lock record and generated artifacts as
 
 Static Vega-Lite and Vega figures use `*.vl.json` and `*.vg.json` sources declared in `.vegavisuals.yml`. A chapter references the specification as a captioned Markdown image; Jekyll and the PDF builder resolve it to the same single manifest output without changing the caption or figure attributes. Prefer SVG when the figure must work identically on the web and in print.
 
-Use the required companion `vegavisuals` MCP and its `initialize_project`, `visualization_status`, `render_visualizations`, and `visualization_check` tools for the source-to-output lifecycle. ContExt registers the companion separately rather than copying it into the site. Run `visualization_check` before PDF status, build, or publication when a manifest exists; the unaltraweb PDF tool does not proxy the separate MCP. Commit the manifest, lock, provider receipt, source data, and generated outputs together.
+Use the required companion `vegavisuals` MCP and its `initialize_project`, `visualization_status`, `render_visualizations`, and `visualization_check` tools for the source-to-output lifecycle. gContExt registers the companion separately rather than copying it into the site. Run `visualization_check` before PDF status, build, or publication when a manifest exists; the unaltraweb PDF tool does not proxy the separate MCP. Commit the manifest, lock, provider receipt, source data, and generated outputs together.
 
 ## PDF Edition
 

data/docs/_documentation/en/20-syntax.md

@@ -102,6 +102,16 @@ For pages with figure captions enabled, use the Markdown image title as the capt
 ![Digitizing workflow]({{ site.baseurl }}/assets/img/workflow.svg "Main editing steps")
 ```
 
+Separate attribution from the description with `data-caption-source`:
+
+```markdown
+![Accessible description](assets/img/map.svg "Distribution by municipality"){: data-caption-source="Source: verified dataset. Credits: map creator."}
+```
+
+The label/number, description and credits have separate web elements. The source
+continues inline with differentiated styling; PDF lists include the description
+without its credits. See the [rendered caption and credit examples]({{ '/caption-credits/' | relative_url }}).
+
 To narrow the space assigned to one figure without changing its height, set a
 CSS width with `data-figure-width`. The figure remains centred and cannot exceed
 the available width. The PDF builder maps `rem` values against its 60-rem
@@ -137,6 +147,10 @@ Manual chapters can number teaching tables with localized labels:
 :::
 ```
 
+Tables accept the same field on the opening line:
+`::: table "Weekly work rhythm" {: data-caption-source="Source: course plan."}`.
+Existing captions remain valid and are not automatically split.
+
 Cells may contain inline code spans such as `` `=SUM(A2:A10)` ``. The manual renderer preserves these as inline `<code>` elements on the web; if a consumer project still shows literal backticks inside numbered tables, update its `unaltraweb` lock file or use explicit HTML `<code>` as a temporary compatibility fallback.
 
 ## Diagram Sources

data/docs/_documentation/en/25-caption-credits.md

@@ -0,0 +1,120 @@
+---
+title: Figure And Table Captions With Credits
+description: Separate automatic numbering, descriptive captions and source credits, with concise PDF indexes.
+lang: en
+ref: caption_credits
+profiles: [unaltredocs]
+documentation_profiles: [github-publishers, local-authors, site-designers, contributors]
+section: Design And Customize
+weight: 315
+permalink: "/caption-credits/"
+nav_title: Captions And Credits
+---
+
+A caption has three distinct parts: its automatic label and number, the
+description of the figure or table, and optional source or creator credits.
+Credits remain part of the visible caption but use a smaller italic style. In a
+manual PDF, only the number and description enter the list of figures or tables.
+
+## Figure
+
+Keep the descriptive caption in the Markdown image title and add
+`data-caption-source` to its attribute block. Alternative text describes the
+image independently of its caption and credits.
+
+```markdown
+![Three boxes connected from left to right](assets/img/caption-credits-demo.svg "Three linked stages"){: data-figure-width-web="34rem" data-figure-width-pdf="78%" data-caption-source="Source: original schematic for this example. Credits: unaltraweb."}
+```
+
+![Three boxes A, B and C connected from left to right]({{ site.baseurl }}/assets/img/caption-credits-demo.svg "Three linked stages"){: data-figure-width-web="34rem" data-figure-width-pdf="78%" data-caption-source="Source: original schematic for this example. Credits: unaltraweb."}
+
+The label receives the numbering style, the description is normal caption text,
+and the source continues inline in its own styled span. Normal wrapping can move
+the source onto the next line; it is not a separate numbered item.
+
+## Table
+
+Use the same attribute after the opening caption. This example contains
+synthetic values solely to illustrate the presentation.
+
+```markdown
+::: table "Example values" {: data-caption-source="Source: synthetic demonstration data. Credits: unaltraweb."}
+| Element | Value |
+| --- | ---: |
+| A | 10 |
+| B | 25 |
+| C | 40 |
+:::
+```
+
+::: table "Example values" {: data-caption-source="Source: synthetic demonstration data. Credits: unaltraweb."}
+| Element | Value |
+| --- | ---: |
+| A | 10 |
+| B | 25 |
+| C | 40 |
+:::
+
+## Links And Attribution
+
+The credit field accepts inline Markdown, including links and emphasis, and the
+existing bibliography citation syntax. Supply the label appropriate to the
+content language, such as “Source”, “Font”, “Fuente” or “Credits”. Attribution
+must describe the actual origin and licence of the material.
+
+::: table "Caption components" {: data-caption-source="Credits: [unaltraweb](https://github.com/dosquartsdedocs/unaltraweb), documentation example."}
+| Component | Purpose |
+| --- | --- |
+| Label and number | Automatically identify the figure or table |
+| Description | Explain what the reader should observe |
+| Source or credits | Identify origin, authorship or licence |
+:::
+
+Use single quotes around the attribute if the credit text contains literal double
+quotes. Liquid citations such as `{% raw %}{% cite verifiedKey %}{% endraw %}`
+follow the usual verified-bibliography workflow. Keep credits in the attribute,
+rather than concatenating them into the descriptive title.
+
+## Multi-Panel Figures
+
+The attribute can credit the whole group or an individual panel:
+
+```markdown
+::: subfigures a+b "Two views of the same schematic" {: data-caption-source="Source: original demonstration schematic."}
+![First view](assets/img/caption-credits-demo.svg "First view"){: data-caption-source="Credits: unaltraweb."}
+![Second view](assets/img/caption-credits-demo.svg "Second view")
+:::
+```
+
+::: subfigures a+b "Two views of the same schematic" {: data-caption-source="Source: original demonstration schematic."}
+![First view]({{ site.baseurl }}/assets/img/caption-credits-demo.svg "First view"){: data-caption-source="Credits: unaltraweb."}
+![Second view]({{ site.baseurl }}/assets/img/caption-credits-demo.svg "Second view")
+:::
+
+## Existing Captions
+
+Existing captions remain valid. The renderer does not guess where a source starts
+in an old caption, since words such as “source” can be part of the description.
+Move attribution into `data-caption-source` explicitly to obtain separate styling
+and shorter PDF index entries.
+
+::: table "A caption without separate credits"
+| Element | Category |
+| --- | --- |
+| A | Initial |
+| B | Intermediate |
+:::
+
+## PDF Index Entries
+
+For the figure above, the list of figures contains **Three linked stages**. Its
+source and creator attribution remain beside the full caption in the chapter.
+For the first table, the list of tables contains **Example values**, without the
+synthetic-data attribution. Figure/table numbering continues to follow the
+manual's normal chapter numbering.
+
+The web exposes `.figlabel`, `.md-caption-text` and `.md-caption-source` for these
+roles. The PDF renderer preserves inline formatting and links in the full caption
+and supplies a description-only short caption to LaTeX. These semantics apply to
+normal images, diagrams and generated figures referenced through the same image
+syntax; source generation and freshness remain owned by their respective tools.