unaltraweb 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be599804b31390cca31133227e0e15f4ba623339a1072a441c74960b79c039fa
-  data.tar.gz: d70f999b0d814f6a579dbb06534c611034792a1cd29972b3015ecce5e21522a4
+  metadata.gz: 33193d7900939e3cf2e4e9769e8fd9443e0a7242eaa73aef1d93b8ffcee6e79b
+  data.tar.gz: 3ef63e4f55c4b369e0926be413eb2da4d3702f49ac733d84dedc952bb1ec563c
 SHA512:
-  metadata.gz: cb11d05e8660d167d311c7a9e1d03f895918d02c754e7189f52b25f1403f0056731aa94f77116b11cf30049c9d54b1ca6ffcae312c08d3127f942c756a1ed222
-  data.tar.gz: c7c798ce0e589fbd2fdaddfa9c4d632afd043ccfca6ecd65c780dfcae33932f6314da270968c665dfcdbac080f48e67022c66344b45961c8b87c1cfe0704ff9a
+  metadata.gz: eb799646f841a4444d315aa4a71d161ec83acacbef75f36fe00b8db7242699be40147c2829bedee18f249f3085b51328cd18a902f317196d518b4f2b8e11a9f2
+  data.tar.gz: cfe5a103146718d7bbae56c9821b2dabdc0fdf1bcde966779ee41ea96c468bd795446202844a56a0974919ce4bca33e2d90e5c6de98e8e95936b1335c44dca86

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.5.1
-MCP_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.1
-MCP_RELEASE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98
+MCP_RUNTIME_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.6.0
+MCP_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.6.0
+MCP_RELEASE_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:908b4ce54c7bdf355e14ed55b31ed4b9baae319e211af90004a680d1d1cb8692
 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.5.1
-MANUAL_PDF_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097
+DOCKER_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb:0.6.0
+MANUAL_PDF_IMAGE ?= ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:0ba267cb87f53ebaca4e31805fe00610cd61fdf97a8d2c3692f4655700dceaed
 MANUAL_PDF_DEV_IMAGE ?= unaltraweb-manual-pdf:dev
 MCP_SMOKE_MANUAL_PDF_IMAGE ?= $(MANUAL_PDF_IMAGE)
 MCP_SMOKE_PROJECT ?=
@@ -375,7 +375,7 @@ manual-pdf-image: ## Ensure the selected versioned Pandoc/XeLaTeX image is prese
 	@docker image inspect "$(MANUAL_PDF_IMAGE)" >/dev/null 2>&1 || docker pull "$(MANUAL_PDF_IMAGE)"
 
 manual-pdf-image-dev: ## Build the explicitly named maintainer PDF development image
-	docker build -f scripts/manual/Dockerfile -t "$(MANUAL_PDF_DEV_IMAGE)" scripts/manual
+	docker build -f scripts/manual/Dockerfile -t "$(MANUAL_PDF_DEV_IMAGE)" .
 
 define run_manual_pdf_worker
 	@set -e; set --; cidfile=""; \

data/_plugins/retained_documents.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+require "open3"
+require "timeout"
+
+module UnaltrawebRetainedDocuments
+  def self.verify(site, output = nil)
+    return { "imports" => [] } unless File.exist?(File.join(site.source, ".unaltraweb", "artifacts"))
+
+    source = File.expand_path("../src", __dir__)
+    command = ["python3", "-m", "unaltraweb_mcp.artifact_imports", "--project", File.expand_path(site.source)]
+    command += ["--output-folder", output] if output
+    stdout, stderr, status = Timeout.timeout(120) { Open3.capture3({ "PYTHONPATH" => source }, *command) }
+    result = JSON.parse(stdout)
+    raise Jekyll::Errors::FatalException, "Retained document check failed: #{result['error'] || stderr}" unless status.success? && result["ok"] == true
+
+    result
+  end
+
+  class Generator < Jekyll::Generator
+    safe true
+    priority :highest
+
+    def generate(site)
+      site.config["unaltraweb_retained_documents"] = UnaltrawebRetainedDocuments.verify(site)["imports"].to_h { |item| [item["id"], item] }
+    end
+  end
+
+  class DocumentTag < Liquid::Tag
+    def initialize(name, markup, tokens)
+      super
+      @id = markup.strip
+      raise ArgumentError, "retained_document requires one import ID" unless @id.match?(/\A[a-z][a-z0-9-]{0,63}\z/)
+    end
+
+    def render(context)
+      site = context.registers[:site]
+      item = (site.config["unaltraweb_retained_documents"] || {})[@id]
+      raise Jekyll::Errors::FatalException, "Unverified retained document #{@id}" unless item
+
+      path = site.config["baseurl"].to_s.sub(%r{/\z}, "") + "/" + item.fetch("pdf")
+      url = CGI.escapeHTML(path)
+      page = context["page"]
+      title = CGI.escapeHTML(((page && page["title"]) || @id).to_s)
+      %(<figure class="retained-document"><object data-retained-document="#{@id}" data="#{url}" type="application/pdf" aria-label="#{title}" style="width:100%;height:70vh"><a href="#{url}">#{title}</a></object><figcaption><a href="#{url}">#{title} (PDF)</a></figcaption></figure>)
+    end
+  end
+end
+
+Liquid::Template.register_tag("retained_document", UnaltrawebRetainedDocuments::DocumentTag)
+
+Jekyll::Hooks.register :site, :post_write do |site|
+  source = File.expand_path(site.source)
+  destination = File.expand_path(site.dest)
+  if destination.start_with?(source + "/")
+    UnaltrawebRetainedDocuments.verify(site, destination.delete_prefix(source + "/"))
+  elsif !(site.config["unaltraweb_retained_documents"] || {}).empty?
+    raise Jekyll::Errors::FatalException, "Retained documents require a project-confined site destination"
+  end
+end

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

@@ -25,9 +25,48 @@ The template is the better place to validate gem consumption, centralized styles
 
 ## Component Contract
 
-### Published 0.5.0 release
-
-The coordinated core release is [**0.5.0**](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.5.0). It groups the integrated editorial
+### Pending 0.6.0 retained-letter increment
+
+The source branch prepares a separate 0.6.0 identity for native
+[retained-letter import]({{ '/retained-documents/' | relative_url }}).
+Gem, wheel, base runtime and MCP are authorized as `ready` for final same-source
+candidates. The consumer core selects reviewed integration
+`5cf9817489c8dc47cee726bfe42fe3071cd32b85`; the PDF 0.6.0 worker is already
+published, signed and tested at immutable digest
+`sha256:0ba267cb87f53ebaca4e31805fe00610cd61fdf97a8d2c3692f4655700dceaed`.
+The PDF worker changes to include complete retained documents and the same
+integrity checkers used by its controller. Computation, capture and visual
+companions retain their tested 0.4.0 selections.
+
+The checkout's active launcher remains pinned to the published 0.5.1 MCP digest.
+Its receipt and package bytes remain unchanged. Local development images and an
+installed wheel exercise the new import without claiming a public 0.6.0 release
+or changing real consumer sites. The
+[owner acceptance record](https://github.com/dosquartsdedocs/unaltraweb/blob/main/docs/agents/retained-letter-import.md)
+records the authenticated Carta packet, receiver mapping and relocation proof.
+
+### Published 0.5.1 release
+
+[**0.5.1**](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.5.1)
+delivers the installed Docker launcher and runtime-specific generated Bundler
+state. Source `aab5a7b030cd711b40770a3f44ad3a356eab90da` produced the signed
+images and verified gem/wheel. Receipt/tag commit
+`e842c733c8a274279dd5efdc3618e20669f29037` changes only the receipt from that
+first parent. Strict release/publication gates passed before promotion, and
+anonymous registry downloads match the receipt. The checkout launcher now selects
+`ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:908b4ce54c7bdf355e14ed55b31ed4b9baae319e211af90004a680d1d1cb8692`.
+
+The four-profile populated-cache roundtrip also passed against the actual signed
+candidate. The selected PDF stays at its published 0.5.0 digest, and computation,
+capture and visual companions retain 0.4.0. See the
+[delivery report](https://github.com/dosquartsdedocs/unaltraweb/blob/main/docs/agents/owner-closeout-76.md)
+and [issue 76](https://github.com/dosquartsdedocs/unaltraweb/issues/76).
+Strict release validation applies to the receipt/tag revision; subsequent
+post-release launcher changes are ordinary source revisions, not new receipts.
+
+### Previous 0.5.0 release
+
+The previous coordinated core release is [**0.5.0**](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.5.0). It groups the integrated editorial
 review, guided scaffold updates, caption-credit/image behavior and published
 Diavisuals/Vegavisuals 0.4.0 acceptance. Source-bound image/package workflows,
 tag promotion and both Trusted Publishing jobs passed. Anonymous package downloads
@@ -42,7 +81,7 @@ at source `d857f8c9f5fea90cf450c0b30b4e77a37b541275` and is selected by digest
 `sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097` in
 both the factory and the consumer tuple. It is already published and tested, so
 final candidate receipts cover the remaining ready package/core components.
-The post-release factory launcher selects the MCP digest recorded in receipt
+The 0.5.0 post-release factory launcher selected the MCP digest recorded in receipt
 `3fa855378dcc61dc7b84b8b03812698042e02fed`:
 `sha256:36d17edbade77edb40a687f6a744203c6329acb33fbc2eb255e88d9ff1a42c98`.
 See [issue 69](https://github.com/dosquartsdedocs/unaltraweb/issues/69) for the
@@ -50,27 +89,27 @@ candidate, receipt, tag and package evidence.
 
 `src/unaltraweb_mcp/component-contract.json` is the canonical versioned bill of materials. Its `consumer_integration` object is the sole source for the reviewed core Git revision, reusable deploy workflow, manual PDF image digest, and Vega renderer revision. Scaffold templates render that tuple atomically into consumer `Gemfile`, `Gemfile.lock`, and deploy workflow files. `component-contract.schema.json` defines schema version 1. Runtime loading and `scripts/validate_distribution.py` validate the complete document against that schema, then enforce semantic parity between versions, release tags, repositories, references, wheel contents, CLI availability, and consumer integration pins.
 
-The BOM is an interoperability contract, not a bundle. The wheel contains its Python control/inspection modules, schema/BOM, and clean package-owned scaffolds. Next-release source also packages a small host Docker launcher, described below. Neither includes Ruby theme assets, Docker image layers, the factory's build/worker implementations, TeX, Chromium, computation environments, `diavisuals`, or `vegavisuals`.
+The BOM is an interoperability contract, not a bundle. The wheel contains its Python control/inspection modules, schema/BOM, clean package-owned scaffolds and a small host Docker launcher, described below. It does not include Ruby theme assets, Docker image layers, the factory's build/worker implementations, TeX, Chromium, computation environments, `diavisuals`, or `vegavisuals`.
 
-The selected public core release is `0.5.0`; earlier distributions remain immutable. Its BOM reuses immutable compute and web-capture worker digests and selects published `diavisuals v0.4.0` and `vegavisuals v0.4.0` through SHA-256-pinned wheel URLs. Companion references can describe either a provider/release-matching Git reference or a provider/release/version-matching wheel with its content hash. The wheel boundary remains external. The scaffold's Vega revision is the published `68c0b231402ae9485cc34ce530dc5239cb0ec194` commit. `distribution-check` validates structural integrity for normal CI. `distribution-release-check` blocks coordinated publication while any component is `pending` or `unavailable`; reviewed source authorized to produce final same-commit candidates is `ready`, while an already-published component is `released`. Final receipt values remain immutable after publication.
+The selected public core release is `0.5.1`; earlier distributions remain immutable. Its BOM reuses immutable PDF, compute and web-capture worker digests and selects published `diavisuals v0.4.0` and `vegavisuals v0.4.0` through SHA-256-pinned wheel URLs. Companion references can describe either a provider/release-matching Git reference or a provider/release/version-matching wheel with its content hash. The wheel boundary remains external. The scaffold's Vega revision is the published `68c0b231402ae9485cc34ce530dc5239cb0ec194` commit. `distribution-check` validates structural integrity for normal CI. `distribution-release-check` blocks coordinated publication while any component is `pending` or `unavailable`; reviewed source authorized to produce final same-commit candidates is `ready`, while an already-published component is `released`. Final receipt values remain immutable after publication.
 
 ## Docker-First Hybrid Policy
 
-### 0.5.1 preparation
+### 0.5.1 component selection
 
-The next coordinated core identity is **0.5.1**: gem, wheel, base runtime and MCP
-image candidates change together. The installed host launcher and runtime-aware
+The coordinated core identity is **0.5.1**: gem, wheel, base runtime and MCP
+images were published together. The installed host launcher and runtime-aware
 generated Bundler state are included. The unchanged PDF worker retains its
 published 0.5.0 digest, alongside the 0.4.0 computation/capture workers and visual
 companions. A released PDF can be reused only by full digest; new/pending workers
 still require the coordinated version. The historical 0.5.0 receipt remains
-unchanged. Final signed image/package receipts and promotion are later gates;
-the launcher continues selecting the last published MCP digest until its normal
-post-release update.
+unchanged. Signed image/package evidence is recorded in the 0.5.1 receipt;
+promotion and anonymous-download checks passed before the post-release launcher
+pin was advanced.
 
 ### Local delivery
 
-GHCR is the canonical delivery channel for normal local use. The released package scaffold selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.0`; existing sites can remain on their immutable previous release until deliberately updated. Its `make build`, `make serve` and `make test` targets mount the thin child site and run inside that image. The image contains both the installed Python control plane and the reviewed factory source at `/opt/unaltraweb`, so those targets load the theme as a path gem without downloading PyPI or RubyGems packages.
+GHCR is the canonical delivery channel for normal local use. The released package scaffold selects `ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.5.1`; existing sites can remain on their immutable previous release until deliberately updated. Its `make build`, `make serve` and `make test` targets mount the thin child site and run inside that image. The image contains both the installed Python control plane and the reviewed factory source at `/opt/unaltraweb`, so those targets load the theme as a path gem without downloading PyPI or RubyGems packages.
 
 Factory registration uses a stricter pin. gContExt runs `mcp-build`, which inspects or pulls the full `MCP_RELEASE_IMAGE` digest, and `mcp-stdio` launches that exact image. Checkout builds use local `:dev` names by default through `mcp-image`, `mcp-check` and `mcp-smoke`, so they do not shadow public semver references unless a maintainer explicitly overrides them. The digest is advanced in a separate post-release change after each new receipt exists; candidate source continues to select the last completed release instead of attempting to embed an unknown self-digest.
 
@@ -86,7 +125,7 @@ These remain real package boundaries: the MCP image installs the Python package
 
 ### Installed Docker launcher
 
-0.5.1 source adds **`unaltraweb-mcp-docker`** and a complete host launcher
+0.5.1 ships **`unaltraweb-mcp-docker`** and a complete host launcher
 under the installation prefix's `share/unaltraweb-launcher/`. The published 0.5.0
 wheel predates this addition; its receipt and bytes remain unchanged. An installed
 wheel containing the launcher can use the already-published full GHCR runtime
@@ -132,7 +171,7 @@ the host, register a client, update a consumer scaffold, or change an active MCP
 The site Makefile's `MCP_IMAGE`, native Gem/core revision, PDF worker, global MCP
 registration and companion selections are separate parts of an effective tuple.
 TIG/TIGIT retain build defaults 0.4.0; Geodisseny retains 0.5.0. A global MCP
-selection of 0.5.0 does not rewrite those defaults. Tests use synthetic sites,
+selection does not rewrite those defaults. Tests use synthetic sites,
 image-specific test resources and dynamically allocated loopback preview ports.
 
 Compatibility evidence is a set of tested tuples, not a continuous version range.
@@ -245,7 +284,7 @@ For that reason:
 
 ## Docker Runtime
 
-Release `0.5.0` publishes the selected base/MCP runtime and packages while pinning the verified PDF worker and reusing unchanged specialized workers. Local maintainers continue to use explicit development names such as `unaltraweb:dev`; generated sites select the reviewed semver MCP image rather than `main` or `latest`.
+Release `0.5.1` publishes the selected base/MCP runtime and packages while pinning the verified PDF worker and reusing unchanged specialized workers. Local maintainers continue to use explicit development names such as `unaltraweb:dev`; generated sites select the reviewed semver MCP image rather than `main` or `latest`.
 
 The base runtime owns Ruby, Jekyll and system dependencies. The MCP image builds on its exact candidate digest and adds the full reviewed factory plus the Python package. Specialized workers remain separate. This keeps each layer focused without adding Chromium, TeX or computation stacks to every site; the coordinated core-image workflow still rebuilds and verifies runtime, MCP and manual PDF candidates together.
 

data/docs/_documentation/en/45-retained-documents.md

@@ -0,0 +1,138 @@
+---
+title: Import A Retained Letter
+description: Verify and retain a Carta letter bundle, display its PDF on the web and include it in a manual.
+lang: en
+ref: retained_documents
+profiles:
+- unaltredocs
+documentation_profiles:
+- local-authors
+- core-developers
+section: Build A Site
+weight: 240
+permalink: /retained-documents/
+nav_title: Retained Documents
+---
+
+A retained letter combines its original PDF with the source, rendering inputs and
+provenance needed to inspect its origin. The importer keeps that complete unit in
+the receiving repository and creates a native page or chapter referencing the PDF.
+The website displays the original; a manual PDF includes all its pages.
+
+This capability belongs to the **0.6.0 development increment**. It requires a
+containing Python package and Jekyll core, plus the matching PDF worker for manual
+output. The published 0.5.1 runtime predates it. Changing the global MCP selection
+does not update a site's Gemfile, Makefile or PDF-worker selection.
+
+Native gem builds need Python with `PyYAML>=6,<7`, `pypdf>=6,<7` and
+`markdown-it-py>=3,<5`. The containing MCP/PDF images provide these dependencies;
+the containing reusable deployment workflow installs the PDF/text parsers when
+retained imports are present.
+
+## Supported Input
+
+The receiving profile accepts leaf `letter-pdf-v1` bundles from **Carta
+0.3.0rc1**, using the existing artifact handoff v1 envelope. Verification covers
+the supplied sender SHA-256, complete file inventory, retained render recipe,
+templates, source references, drawable resources and renderer identity. PDF
+inspection is bounded and rejects encrypted files, embedded or external files,
+JavaScript and unsupported actions. Internal destinations and textual HTTP,
+HTTPS and email links are supported.
+
+Renderable metadata is checked independently of the retained Pandoc AST. A
+resealed bundle with an unretained local link in a subject or author field is
+rejected even when its older parsing evidence does not mention that link.
+
+Limits are 64 MiB for the payload unit, 32 MiB for the PDF and 1–64 pages. The
+supported source subset excludes body images, raw markup, TeX, math and citations;
+attachments remain text labels. Composite bundles, edited PDF variants and
+Diapora composition require separate receiving profiles.
+
+Obtain the bundle's expected SHA-256 through the sender's trusted handoff. A hash
+computed only from an unknown local manifest establishes consistency, not its
+origin. Importing never executes the retained recipe or contacts the producer.
+
+## Import Into A Consumer
+
+Start with an initialized consumer Git repository. Place the complete incoming
+bundle under a workspace-relative directory such as `tmp/incoming/letter/`.
+The recovery area under `tmp/` must be ignored and untracked; durable destinations
+must be eligible for version control.
+
+Review a plan using the installed CLI. Here `BUNDLE_SHA` is the sender's verified
+manifest digest:
+
+```bash
+unaltraweb-mcp --project /absolute/consumer mcp import-artifact-bundle \
+  --path tmp/incoming/letter/bundle.json --sha256 "$BUNDLE_SHA" \
+  --import-id correspondence --content-path _chapters/en/correspondence.md \
+  --title "Retained correspondence"
+```
+
+To apply the reviewed request, repeat it with `--apply --confirm-import`.
+The MCP equivalent is `import_artifact_bundle` with `dry_run=false` and
+`confirm_import=true`; its default is a read-only plan.
+
+Choose a new Markdown destination under `_pages/`, or `_chapters/` for a manual,
+or `_documentation/` for a documentation site. An executable source owning the
+same Markdown basename blocks creation. The generated document starts as a draft
+in the consumer's default language, with a literal local permalink.
+
+The resulting paths are:
+
+| Path | Purpose |
+| --- | --- |
+| `.unaltraweb/artifacts/correspondence/bundle/` | Complete, unchanged incoming seal, outside the web output |
+| `.unaltraweb/artifacts/correspondence/integration.json` | Standard v1 integration record and byte-preserving PDF mapping |
+| `.unaltraweb/artifacts/correspondence/binding.json` | Native content path and integration-record digest |
+| `assets/documents/correspondence.pdf` | Public PDF, identical to the retained original |
+| `_chapters/en/correspondence.md` | Native chapter with the retained-document component |
+
+Version the complete durable unit together. The incoming directory and ignored
+recovery journal are not runtime dependencies. The retained archive is excluded
+from website output, but remains ordinary repository content.
+
+## Edit And Render The Native Document
+
+Add explanatory prose to the generated page or chapter while preserving its
+literal permalink and component:
+
+{% raw %}
+```liquid
+{% retained_document correspondence %}
+```
+{% endraw %}
+
+On the web, the component renders a PDF object with a labelled download link.
+The build checks the bound page's exact local PDF URL and the emitted PDF bytes.
+Exposing the retained archive in the website is an error. In a manual, the PDF
+builder includes every original page and fingerprints the entire retained unit
+and its checker implementation. A controller/worker mismatch therefore fails
+freshness verification rather than silently accepting an older checker.
+
+Run `artifact_import_check` or the CLI equivalent before building:
+
+```bash
+unaltraweb-mcp --project /absolute/consumer mcp artifact-import-check
+unaltraweb-mcp --project /absolute/consumer mcp artifact-import-check --output-folder _site
+```
+
+`site_check` and `site_doctor` include the native integrity check. For a local
+manual review, use `manual_pdf_preview_prepare`, then `build_site` and
+`preview_start`. Review the web page and composed PDF, then clean only the
+receipt-owned preview copies through `manual_pdf_preview_clean`.
+
+## Preservation And Recovery
+
+An identical reimport preserves authored prose. A changed mapped PDF, conflicting
+destination, unsafe path or modified seal blocks the operation; existing files
+are never overwritten. After an interrupted import, unchanged partial files may
+be adopted by an explicit retry of the same request. Differing partial files
+require inspection. The operation retains its prepared tree and journal under
+`tmp/unaltraweb-artifact-imports/` and performs no destructive rollback.
+
+The native check verifies references and content after the incoming producer copy
+has been removed or the receiving repository has moved. It also detects missing
+content, incomplete retention and altered mappings. The generic v1 verifier can
+independently inspect `integration.json`; it does not replace the native source
+and rendered-output checks.

data/docs/agents/mcp-contract.md

@@ -16,7 +16,7 @@ MCP_CONSUMER_WORKSPACE="$PWD" make --silent --no-print-directory -C /path/to/una
 
 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.
 
-Next-release wheels also install this native descriptor and its complete host
+Released 0.5.1 wheels also install this native descriptor and its complete host
 helper closure under `share/unaltraweb-launcher`. For that installed profile,
 `${factoryRoot}` is the path returned by `unaltraweb-mcp-docker path`, rather than
 a core checkout. Its small Makefile implements `mcp-build`, `mcp-check`,
@@ -32,6 +32,11 @@ it to an image ID before execution. The source checkout's digest pin is separate
 it advances only after a new receipt exists. Explicit `--image` (or the console
 adapter's `UNALTRAWEB_MCP_IMAGE`) permits a reviewed immutable selection.
 
+The post-release checkout pin selects published 0.5.1 MCP digest
+`sha256:908b4ce54c7bdf355e14ed55b31ed4b9baae319e211af90004a680d1d1cb8692`.
+Existing processes keep their running image until clients reconnect. Site build
+defaults and customized Makefiles remain separate, explicitly reviewed selections.
+
 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.
@@ -97,6 +102,7 @@ baseline format nor runtime cleanup changes.
 | `web://manual-authoring-components` | Supported prose structures and component syntax, including callouts, definition lists, figure layouts, tables, diagrams, citations, and web/PDF compatibility. |
 | `web://manual-computations` | Executable manual sources, selected runtime images, generated outputs, and freshness state. |
 | `web://web-captures` | Selector-based screenshot recipes, original PNGs, editable SVG layers, edited overrides, and freshness. |
+| `web://artifact-imports` | Native retained-letter bindings, complete seal/mapping integrity and source references; read-only. |
 | `web://new-web-scaffolds` | Package-owned scaffold availability and contract paths for every supported site profile. |
 
 ## Tools
@@ -111,6 +117,8 @@ baseline format nor runtime cleanup changes.
 | `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, publication-copy source diagnostics, freshness, companion visualization/diagram receipt, bibliography, bibliometrics, and build-state checks without network. |
+| `import_artifact_bundle` | Plan or explicitly apply a create-only Carta 0.3.0rc1 `letter-pdf-v1` import with the sender SHA-256, complete retained seal, standard v1 integration record and native content binding. Defaults to dry-run; apply requires `confirm_import=true`. |
+| `artifact_import_check` | Verify retained domains, mappings and native source references; optional `output_folder` checks the bound rendered page and exact emitted PDF bytes. |
 | `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. |
@@ -172,6 +180,33 @@ Manual PDF publication is a local workspace operation: it copies reviewed artefa
 
 ## New Site Initialization
 
+### Retained Letter Integration
+
+The 0.6.0 development increment adds package-only import/check commands and the
+`web://artifact-imports` resource. Web rendering needs its containing Jekyll core;
+manual inclusion also needs the matching PDF worker. Published 0.5.1 components
+do not acquire this capability from a launcher-pin change.
+
+The complete seal lives at `.unaltraweb/artifacts/<id>/bundle/`, alongside an
+unchanged-schema v1 integration record and a separate native `binding.json`.
+Only the byte-identical mapped PDF under `assets/documents/` is public. A new
+draft page/chapter binds it using the `retained_document` Liquid tag and a literal
+permalink. `site_check`, `site_doctor`, Jekyll and manual PDF preparation verify
+the corresponding domain, seal, mapping and native reference; the PDF fingerprint
+includes every retained dependency and checker. Producer sources are never run.
+
+Writes require the consumer Git root, ignored/untracked recovery staging and
+non-ignored durable paths. They are descriptor-relative and create-only, with
+preflight and final integrity checks. The project/import locks coordinate with
+native readers and the PDF controller. An interrupted operation retains its
+prepared tree and partial files, without destructive rollback. An explicit retry
+may adopt identical bytes; conflicts preserve existing content. Successful
+identical reimport preserves authored prose. See the
+[author reference](../_documentation/en/45-retained-documents.md) and
+[owner acceptance record](retained-letter-import.md) for bounds and evidence.
+
+### Package-Owned Initialization
+
 `new_web` is intended for empty or nearly-empty website repositories. It creates common runtime files, profile-specific configuration, localized home pages, the content paths required by the selected profile, and `.unaltraweb/scaffold.json`. All scaffold assets are shipped inside the `unaltraweb_mcp` Python package and MCP Docker image; environment variables, sibling checkouts, and arbitrary template paths are not consulted.
 
 The `unaltremanual` scaffold also creates `context/writing-profile.md` with a usable default editorial policy and `.unaltraweb/computations.yml` with both BOM-selected workers, `_chapters` and `assets/quarto` source roots, and a generated-asset root. Customize the writing profile for the manual's audience, voice, terminology, evidence policy, language workflow, and review requirements. Computation configuration is consumer-owned rather than scaffold-managed so a project can add lockfiles, dependency paths, or extension Dockerfiles without creating scaffold-sync conflicts. PDF generation and Vega manifests remain opt-in project configuration.