unaltraweb 0.7.4 → 0.8.1

data/scripts/review_manual_context_pilots.py

@@ -0,0 +1,287 @@
+"""Opt-in, version-bound #121 review against the published 0.8.0 controller.
+
+Creates synthetic sources, invokes the REAL installed CLI without network/socket,
+and retains successes AND expected refusals. It does not repair the exporter,
+render figures, manufacture transport archives, or mount a teaching manual.
+Native computation locks below are explicitly synthetic check fixtures, not
+evidence that R/Python rendering took place. Itemarium checking is optional and
+uses its read-only source tree with a separately prepared Python interpreter.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import importlib.util
+import io
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import tarfile
+import uuid
+
+ROOT = Path(__file__).resolve().parent.parent
+IMAGE = "sha256:e0502369c85c59f9e512fbd9fdb17dbc128845d057a1423375425e68ce2e79a2"
+OLD_IMAGE = "sha256:ea14b1224382e47031b979d294f970b66773155584ac8f9eb94a33dc6421b0c9"
+SOURCE = "54afe7588c36e959a7eb75d5f52763a7456108d7"
+PRODUCER = "sha256:a678d2b2649e3479d0049ca0ca8a500aba5bb3f0a59b070cd7aaf5c0c6b466d0"
+SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="30" height="20"><rect width="30" height="20" fill="white"/><text x="1" y="12">Fixture</text></svg>'
+
+
+def sha(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+def save(path, value):
+    with path.open("x", encoding="utf-8") as stream:
+        json.dump(value, stream, indent=2, sort_keys=True, ensure_ascii=False)
+        stream.write("\n")
+
+
+def write(root, name, data):
+    path = root / name
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("xb") as stream:
+        stream.write(data.encode() if isinstance(data, str) else data)
+
+
+def command(argv, *, cwd=None, expected=0, env=None):
+    result = subprocess.run(argv, cwd=cwd, env=env, capture_output=True, text=True, timeout=180)
+    if expected is not None and result.returncode != expected:
+        raise RuntimeError(f"Command failed: {argv}: {result.returncode}\n{result.stderr[-4000:]}")
+    return result
+
+
+def cases(root):
+    from PIL import Image
+    import yaml
+    png = io.BytesIO()
+    Image.new("RGB", (2, 2), "navy").save(png, format="PNG")
+    encoded = base64.b64encode(png.getvalue()).decode()
+    rows = [
+        {"id": "baseline", "body": 'Text.\n\n![Alt](assets/img/plain.svg "Caption")\n', "ok": True},
+        {"id": "missing-id", "no_id": True, "error": "unaltraweb.manual.id"},
+        {"id": "missing-figure", "body": '![Alt](assets/img/missing.svg "Caption")\n', "error": "Missing editorial input"},
+        {"id": "public-input", "compute": "assets/data/input.gpkg", "ok": True},
+        {"id": "private-input", "compute": "_practices/fixture/data/input.gpkg", "error": "outside the public manual source roots"},
+        {"id": "private-input-other-chapter", "compute": "_practices/fixture/data/input.gpkg", "unreferenced": True,
+         "chapter": "first", "error": "outside the public manual source roots"},
+        {"id": "changed-public-input", "compute": "assets/data/input.gpkg", "changed_input": True,
+         "error": "source_or_environment_changed"},
+        {"id": "private-image", "body": '![Alt](_practices/fixture/private.png "Private")\n',
+         "extra": {"_practices/fixture/private.png": png.getvalue()}, "error": "outside the public manual source roots"},
+        {"id": "components", "body": '''{% include note.md %}
+
+{% cite fixture %}
+
+::: table "Table caption"
+| A | B |
+| --- | --- |
+| 1 | 2 |
+:::
+
+::: subfigures a+b "Group caption"
+![A]({{ site.baseurl }}/assets/img/plain.svg "Panel A")
+![B](assets/img/plain.svg "Panel B")
+:::
+''', "extra": {"_includes/note.md": "Term\n: Exact definition.\n\n>>>> Warning text.\n",
+               "_bibliography/manual.bib": '@book{fixture, title={Fixture reference}, author={Author, A}, year={2026}}'}, "ok": True},
+        {"id": "liquid-expression", "body": "Title: {{ page.title }}\n", "error": "unresolved Liquid/include"},
+        {"id": "include-parameters", "body": '{% include note.md label="Example" %}\n',
+         "extra": {"_includes/note.md": "A note."}, "error": "without parameters"},
+        {"id": "html-caption-code", "body": '<img src="assets/img/plain.svg" alt="Alt `code`" title="Caption `literal`">\n',
+         "ok": True, "expected_caption": "Caption `literal`"},
+        {"id": "embedded-raster", "body": '![Raster](assets/img/embedded.svg "Raster")\n',
+         "image": "assets/img/embedded.svg", "extra": {"assets/img/embedded.svg": '<svg xmlns="http://www.w3.org/2000/svg"><image href="data:image/png;base64,' + encoded + '" width="2" height="2"/></svg>'},
+         "error": "cannot receive SVG <image>"},
+        {"id": "external-raster", "body": '![Raster](assets/img/external.svg "Raster")\n',
+         "image": "assets/img/external.svg", "extra": {"assets/img/external.svg": '<svg xmlns="http://www.w3.org/2000/svg"><image href="https://example.invalid/image.png"/></svg>'},
+         "error": "cannot receive SVG <image>"},
+        {"id": "qgis-vector", "body": '![Map](assets/img/map.svg "Map")\n', "image": "assets/img/map.svg",
+         "extra": {"assets/img/map.svg": SVG.replace("<rect", '<metadata>{"producer":"unaltracaptura-qgis"}</metadata><rect')},
+         "error": "QGIS capture handoff is not supported"},
+        {"id": "qgis-untyped", "body": '![QGIS result](assets/img/map.svg "Authored static bytes")\n',
+         "image": "assets/img/map.svg", "extra": {"assets/img/map.svg": SVG}, "ok": True},
+    ]
+    for row in rows:
+        case = root / row["id"]
+        case.mkdir()
+        config = {"theme": "unaltraweb", "title": "Synthetic review", "default_lang": "ca", "languages": ["ca"],
+                  "exclude": ["tmp/", "_practices/"], "unaltraweb": {"site_profile": "unaltremanual", "manual": {"id": "review-121"}}}
+        if row.get("no_id"):
+            del config["unaltraweb"]["manual"]["id"]
+        write(case, "_config.yml", yaml.safe_dump(config))
+        write(case, ".gitignore", "/tmp/\n")
+        write(case, "assets/img/plain.svg", SVG)
+        body = row.get("body", 'Text.\n\n![Alt](assets/img/plain.svg "Caption")\n')
+        if row.get("compute"):
+            write(case, ".unaltraweb/computations.yml", "version: 1\nsource_roots: [assets/compute]\n")
+            write(case, row["compute"], b"OPAQUE SYNTHETIC FINGERPRINT INPUT; NOT A GIS VALIDITY TEST\n")
+            front = {"title": "Computed fixture", "lang": "ca", "ref": "computed-fixture", "unaltraweb_compute": {
+                "engine": "python", "mode": "figure", "inputs": [row["compute"]], "outputs": ["assets/img/result.svg"]}}
+            write(case, "assets/compute/figure.qmd", "---\n" + yaml.safe_dump(front) + "---\nSynthetic source; no computation execution.\n")
+            write(case, "assets/img/result.svg", SVG)
+            if not row.get("unreferenced"):
+                body = '![Computed](assets/compute/figure.qmd "Computed fixture")\n'
+        write(case, "_chapters/ca/first.md", "---\ntitle: First\nlang: ca\nref: first\n---\n" + body)
+        for name, data in row.pop("extra", {}).items():
+            write(case, name, data)
+        command(["git", "init", "-b", "fixture"], cwd=case)
+        paths = [p.relative_to(case).as_posix() for p in case.rglob("*") if p.is_file() and ".git" not in p.parts]
+        command(["git", "add", "--", *paths], cwd=case)
+        command(["git", "-c", "user.name=Fixture", "-c", "user.email=fixture@example.invalid", "commit", "-m", "Synthetic review sources"], cwd=case)
+    save(root / "cases.json", rows)
+
+
+def worker(root):
+    """Executed in the exact published image. No exporter function is replaced."""
+    from unaltraweb_mcp import __version__
+    from unaltraweb_mcp.manual_context import producer_identity
+    assert root == Path("/cases") and os.environ.get("UW_REVIEW_WORKER") == "1"
+    identity = producer_identity(Path("/opt/unaltraweb"))
+    assert __version__ == "0.8.0" and identity["revision"] == PRODUCER
+    rows = json.loads((root / "cases.json").read_text())
+    results = []
+    for row in rows:
+        case = root / row["id"]
+        native_status = None
+        if row.get("compute"):
+            spec = importlib.util.spec_from_file_location("review_native_compute", "/opt/unaltraweb/scripts/computations/render.py")
+            native = importlib.util.module_from_spec(spec)
+            spec.loader.exec_module(native)
+            config, config_path = native.load_config(case)
+            record, = native.discover_sources(case, config)
+            fingerprint, dependencies, image = native.fingerprint(case, config, config_path, record)
+            saved = {"fingerprint": fingerprint, "dependencies": dependencies, "image": image,
+                     "image_identity": native.inspect_image(image["image"]),
+                     "outputs": [{"path": p, **native.file_signature(case / p)} for p in record["output_paths"]]}
+            save(case / ".unaltraweb/computations.lock.json", {"version": 1, "records": {record["source_path"]: saved}})
+            native_status = native.status(case)
+            assert native_status["ok"], native_status
+            if row.get("changed_input"):
+                with (case / row["compute"]).open("ab") as stream:
+                    stream.write(b"CHANGED INPUT\n")
+        before = {p.relative_to(case).as_posix(): sha(p.read_bytes()) for p in case.rglob("*")
+                  if p.is_file() and ".git" not in p.parts and "tmp" not in p.relative_to(case).parts}
+        argv = [sys.executable, "-I", "-B", "-m", "unaltraweb_mcp.cli", "--project", str(case), "mcp",
+                "manual-context-export", "--name", "review", "--language", "ca"]
+        if row.get("chapter"):
+            argv += ["--chapter", row["chapter"]]
+        ran = command(argv, expected=None)
+        result = json.loads(ran.stdout)
+        expected = (ran.returncode == 0 and result.get("ok") is True) if row.get("ok") else (
+            ran.returncode == 1 and result.get("ok") is False and row["error"] in result.get("error", ""))
+        item = {"id": row["id"], "expected_behavior_observed": expected, "command": argv, "exit_code": ran.returncode,
+                "result": result, "stderr": ran.stderr, "source_hashes": before,
+                "synthetic_native_status": native_status, "renderer_executed": False}
+        archive = case / "tmp/manual-context/review/manual-context.tar.gz"
+        item["archive_created"] = archive.exists()
+        if result.get("ok"):
+            assert archive.is_file() and sha(archive.read_bytes()) == result["sha256"]
+            with tarfile.open(archive) as content:
+                members = {m.name: content.extractfile(m).read() for m in content.getmembers()}
+            manifest = json.loads(members.pop("manual-context.json"))
+            assert set(manifest["files"]) == set(members)
+            assert all(entry["sha256"] == sha(members[p]) and entry["size_bytes"] == len(members[p]) for p, entry in manifest["files"].items())
+            item["manifest"] = manifest
+            if row.get("expected_caption"):
+                item["expected_caption"] = row["expected_caption"]
+                item["caption_preserved"] = manifest["figures"][0]["caption"] == row["expected_caption"]
+        else:
+            assert not archive.exists(), "A refusal left a transport package"
+        assert all(sha((case / p).read_bytes()) == value for p, value in before.items())
+        save(root / (row["id"] + ".result.json"), item)
+        results.append(item)
+    save(root / "producer-review.json", {"ok": all(row["expected_behavior_observed"] for row in results),
+        "purpose": "Version-bound baseline review, not acceptance of known defects", "producer": identity,
+        "synthetic_only": True, "real_manual_mounted": False, "renderer_executed": False, "cases": results})
+
+
+RECEIVER = '''import json, sys
+from pathlib import Path
+import itemarium
+from itemarium.app.media import read_image
+from itemarium.app.manual_package import check_package
+from itemarium.runtime_identity import source_sha256
+root = Path(sys.argv[1]); engine = Path(itemarium.__file__).parent
+before = source_sha256(engine); results = []
+for case in json.loads((root/'cases.json').read_text()):
+    result = json.loads((root/(case['id']+'.result.json')).read_text())['result']
+    row = {'id':case['id']}
+    if result.get('ok'):
+        row['package_check'] = check_package(package_path=root/case['id']/result['path'], sha256=result['sha256'])
+    if case.get('image'):
+        try:
+            read_image(root/case['id']/case['image']); row['image_check'] = {'ok':True}
+        except ValueError as error:
+            row['image_check'] = {'ok':False, 'error':str(error)}
+    results.append(row)
+assert source_sha256(engine) == before
+report = {'engine_version':itemarium.__version__, 'engine_source_sha256':before, 'cases':results,
+          'imports_performed':False, 'manufacturer_of_alternate_packages':False,
+          'image_checks_are_member_validation_only':True}
+with (root/'receiver-review.json').open('x') as output:
+    json.dump(report, output, sort_keys=True, indent=2); output.write('\\n')
+'''
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path)
+    parser.add_argument("--receiver-python", type=Path)
+    parser.add_argument("--receiver-source", type=Path)
+    parser.add_argument("--worker", type=Path, help=argparse.SUPPRESS)
+    args = parser.parse_args()
+    if args.worker:
+        worker(args.worker)
+        return
+    if not args.output or bool(args.receiver_python) != bool(args.receiver_source):
+        parser.error("Supply --output; pair --receiver-python with --receiver-source")
+    if not (ROOT / "mcp-factory.yml").is_file():
+        parser.error("Run this review harness from the unaltraweb source checkout")
+    output = args.output.resolve()
+    if output != args.output or not output.is_relative_to(ROOT / "tmp") or not output.parent.is_dir():
+        parser.error("Use a new absolute output below this checkout's tmp, with an existing parent")
+    observed, = json.loads(command(["docker", "image", "inspect", IMAGE]).stdout)
+    assert observed["Id"] == IMAGE and observed["Config"]["Labels"]["org.opencontainers.image.revision"] == SOURCE
+    output.mkdir(mode=0o700)
+    cases(output)
+    name = "unaltraweb-review121-" + uuid.uuid4().hex
+    argv = ["docker", "run", "--rm", "--pull", "never", "--name", name, "--network", "none", "--read-only",
+            "--user", f"{os.getuid()}:{os.getgid()}", "--cpus", "2", "--memory", "2g", "--pids-limit", "256",
+            "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--tmpfs", "/tmp:rw,nosuid,nodev,size=268435456",
+            "-e", "HOME=/tmp", "-e", "PYTHONDONTWRITEBYTECODE=1", "-e", "UW_REVIEW_WORKER=1",
+            "--mount", f"type=bind,source={output},target=/cases",
+            "--mount", f"type=bind,source={Path(__file__).resolve()},target=/review.py,readonly",
+            "--entrypoint", "python3", IMAGE, "-I", "-B", "/review.py", "--worker", "/cases"]
+    for path in (output, Path(__file__).resolve()):
+        if any(c in str(path) for c in ",\r\n"):
+            raise ValueError("Review mount path needs a simple literal spelling")
+    ran = command(argv, expected=None)
+    save(output / "execution.json", {"command": argv, "exit_code": ran.returncode, "stdout": ran.stdout, "stderr": ran.stderr})
+    command(["docker", "info", "--format", "{{.ID}}"])
+    absent = command(["docker", "container", "inspect", name], expected=None)
+    assert absent.returncode == 1 and "No such" in absent.stderr, "Exact review container absence not established"
+    if ran.returncode:
+        raise RuntimeError(ran.stderr[-6000:])
+    report = json.loads((output / "producer-review.json").read_text())
+    assert report["ok"], "A scenario differed from the recorded 0.8.0 behavior; inspect retained results"
+    old, = json.loads(command(["docker", "image", "inspect", OLD_IMAGE]).stdout)
+    assert old["Id"] == OLD_IMAGE
+    old_result = command(["docker", "run", "--rm", "--pull", "never", "--network", "none", "--read-only",
+                          "--entrypoint", "unaltraweb-mcp", OLD_IMAGE, "mcp", "manual-context-export", "--name", "probe"], expected=None)
+    assert old_result.returncode == 2 and "invalid choice" in old_result.stderr
+    save(output / "old-runtime.json", {"image_id": OLD_IMAGE, "exit_code": old_result.returncode, "stderr": old_result.stderr})
+    if args.receiver_python:
+        environment = {**os.environ, "PYTHONPATH": str(args.receiver_source.resolve()), "PYTHONDONTWRITEBYTECODE": "1"}
+        # Keep a venv interpreter's spelling: resolving its python symlink would
+        # silently select the system interpreter and lose the prepared dependencies.
+        command([str(args.receiver_python.absolute()), "-B", "-c", RECEIVER, str(output)], env=environment)
+    print(json.dumps({"ok": True, "output": str(output), "cases": len(report["cases"]),
+                      "receipt_sha256": sha((output / "producer-review.json").read_bytes()), "exact_container_absent": True}, indent=2))
+
+
+if __name__ == "__main__":
+    main()

data/scripts/test_manual_context_export.py

@@ -0,0 +1,145 @@
+"""Retained fixture acceptance through the real producer MCP, never a fabricated tar.
+
+Run Itemarium's independent conformance command on the returned paths/hashes.
+This script itself has no Itemarium dependency and uses no teaching workspace.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import hashlib
+import json
+import os
+from pathlib import Path
+import sys
+import subprocess
+import uuid
+import tarfile
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+sys.path.insert(0, str(ROOT / "test"))
+from test_manual_context import fixture, write, commit, computation_fixture  # noqa: E402
+
+
+def save(path, value):
+    with path.open("x") as stream:
+        json.dump(value, stream, ensure_ascii=False, sort_keys=True, indent=2)
+        stream.write("\n")
+
+
+def verify_private_inputs_html(project, result):
+    with tarfile.open(project / result["path"]) as archive:
+        files = {entry.name: archive.extractfile(entry).read() for entry in archive.getmembers()}
+    manifest = json.loads(files["manual-context.json"])
+    assert manifest["figures"][0]["caption"] == "Caption `literal`"
+    assert manifest["figures"][0]["alt"] == "Alt `code`"
+    assert set(files) == {"manual-context.json", *manifest["files"]}
+    data = b"".join(files.values())
+    assert b"PRIVATE_CHECK_ONLY_SENTINEL" not in data and b"_practices/" not in data
+    assert b"UNALTRAWEBEXPORTPROTECTED" not in data
+
+
+async def export(project, name, image=""):
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+    def payload(result):
+        return result.structuredContent or json.loads("\n".join(row.text for row in result.content if hasattr(row, "text")))
+    parameters = StdioServerParameters(command=sys.executable,
+        args=["-B", "-m", "unaltraweb_mcp.cli", "mcp", "serve"],
+        env={"PATH": os.environ["PATH"], "HOME": str(project), "PYTHONPATH": str(ROOT / "src"),
+             "MCP_CONSUMER_WORKSPACE": str(project), "UNALTRAWEB_FACTORY_DIR": str(ROOT)})
+    container = ""
+    image_id = ""
+    if image:
+        from unaltraweb_mcp.docker_mount import docker_bind_mount
+        image_id = subprocess.run(["docker", "image", "inspect", image, "--format", "{{.Id}}"], check=True,
+                                  capture_output=True, text=True, timeout=20).stdout.strip()
+        container = "unaltraweb-context-121-" + uuid.uuid4().hex
+        parameters = StdioServerParameters(command="docker", args=["run", "--rm", "-i", "--pull", "never",
+            "--name", container, "--network", "none", "--read-only", "--user", f"{os.getuid()}:{os.getgid()}",
+            "--cpus", "2", "--memory", "2g", "--pids-limit", "256", "--tmpfs", "/tmp:rw,nosuid,nodev,size=268435456",
+            "--label", "io.context.mcp-factory=unaltraweb", "--label", "io.context.mcp-role=context-acceptance",
+            "--mount", docker_bind_mount(project, "/workspace"), "-e", "HOME=/tmp",
+            "-e", "UNALTRAWEB_DOCKER_ROOT=" + str(project), "-e", "UNALTRAWEB_MCP_IMAGE=" + image_id,
+            "--entrypoint", "unaltraweb-mcp", image_id, "--project", "/workspace", "mcp", "serve"])
+    async with stdio_client(parameters) as (incoming, outgoing):
+        async with ClientSession(incoming, outgoing) as client:
+            await client.initialize()
+            tools = await client.list_tools()
+            tool = next(row for row in tools.tools if row.name == "manual_context_export")
+            assert not {"root", "project", "workspace"} & tool.inputSchema["properties"].keys()
+            identity = payload(await client.call_tool("runtime_identity", {}))
+            result = payload(await client.call_tool("manual_context_export", {"name": name, "language": "ca"}))
+            assert result["ok"], result
+            again = payload(await client.call_tool("manual_context_export", {"name": name, "language": "ca"}))
+            assert not again["ok"] and "already exists" in again["error"], again
+            await client.call_tool("runtime_drain", {"confirm": True})
+            result["absolute_path"] = str(project / result["path"])
+            assert hashlib.sha256(Path(result["absolute_path"]).read_bytes()).hexdigest() == result["sha256"]
+            observed = {"identity": identity, "export": result, "create_only_refusal": again}
+    if image:
+        assert identity["package"]["mode"] == "installed" and not identity["package"]["drift"]
+        absent = subprocess.run(["docker", "container", "inspect", container], capture_output=True, timeout=20)
+        assert absent.returncode != 0, "Fixture MCP container remains after stdio close"
+        observed.update(image_id=image_id, exact_container_absent=True)
+    return observed
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", type=Path, required=True)
+    parser.add_argument("--single", action="store_true")
+    parser.add_argument("--image", default="", help="Already-built MCP image; pull-never, network-disabled fixture stdio")
+    parser.add_argument("--private-inputs-html", action="store_true", help="Exercise P1/P2 with explicitly synthetic native computation records")
+    args = parser.parse_args()
+    output = args.output.resolve()
+    if output != args.output or not output.is_relative_to(ROOT / "tmp") or not output.parent.is_dir():
+        raise ValueError("Use a new absolute output directory below the factory tmp with an existing parent")
+    output.mkdir(mode=0o700)
+    project = output / "manual-fixture"
+    project.mkdir()
+    fixture(project)
+    if args.private_inputs_html:
+        write(project, "_practices/fixture/data/input.csv", "PRIVATE_CHECK_ONLY_SENTINEL,1\n")
+        write(project, "_practices/fixture/data/parameters.yml", "defaults: &defaults {value: PRIVATE_CHECK_ONLY_SENTINEL}\nselected: *defaults\n")
+        computation_fixture(project, inputs=["_practices/fixture/data/input.csv", "_practices/fixture/data/parameters.yml"])
+        chapter = project / "_chapters/ca/first.md"
+        original = chapter.read_text()
+        original = original.replace('![Alt](assets/img/map.png "Mapa de prova"){: data-caption-source="Autoria sintètica"}',
+                                    '<img src="assets/img/map.png" alt="Alt `code`" title="Caption `literal`">')
+        write(project, "_chapters/ca/first.md", original)
+        commit(project, ["_practices/fixture/data/input.csv", "_practices/fixture/data/parameters.yml", ".unaltraweb/computations.yml", ".unaltraweb/computations.lock.json",
+                         "assets/compute/figure.qmd", "assets/img/figure.svg", "_chapters/ca/first.md"], "P1/P2 synthetic native check inputs")
+    first = asyncio.run(export(project, "v1", args.image))
+    if args.private_inputs_html:
+        verify_private_inputs_html(project, first["export"])
+    save(output / "producer-v1.json", first)
+    command = [sys.executable, "-B", "-m", "unaltraweb_mcp.cli", "--project", str(project), "mcp", "manual-context-export",
+               "--name", "cli-block", "--language", "ca", "--chapter", "first", "--section", "first#method"]
+    completed = subprocess.run(command, env={**os.environ, "PYTHONPATH": str(ROOT / "src"), "UNALTRAWEB_FACTORY_DIR": str(ROOT)},
+                               check=True, capture_output=True, text=True, timeout=120)
+    cli = json.loads(completed.stdout)
+    assert cli["ok"] and cli["sections"] == 1 and cli["figures"] == 1, cli
+    save(output / "producer-cli.json", {"command": command, "result": cli})
+    result = {"ok": True, "synthetic_manual": True, "producer_export_invoked": True, "transport": "mcp-stdio",
+              "first": first["export"], "cli_verified": True, "questions_generated": 0,
+              "private_inputs_html": args.private_inputs_html, "computation_render_executed": False}
+    if not args.single:
+        original = (project / "_chapters/ca/first.md").read_text()
+        write(project, "_chapters/ca/first.md", original + "\nSegona versió: text afegit.\n")
+        write(project, "_chapters/ca/second.md", "---\ntitle: Segon\nref: second\nlang: ca\nweight: 20\n---\nCapítol afegit en la segona versió.\n")
+        commit(project, ["_chapters/ca/first.md", "_chapters/ca/second.md"], "Second fixture revision")
+        second = asyncio.run(export(project, "v2", args.image))
+        if args.private_inputs_html:
+            verify_private_inputs_html(project, second["export"])
+        save(output / "producer-v2.json", second)
+        result["next"] = second["export"]
+        assert first["export"]["manual"]["id"] == second["export"]["manual"]["id"]
+        assert first["export"]["manual"]["revision"] != second["export"]["manual"]["revision"]
+    save(output / "producer-receipt.json", result)
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+
+
+if __name__ == "__main__":
+    main()

data/scripts/unaltraweb-mcp-bootstrap.sh

@@ -15,7 +15,7 @@ Managed mode requires an immutable reference or an expected full image ID.
 USAGE
 }
 
-image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:8183e7117f5902fc0ad4d930b757d874b2da1f93d5ef4db102ae4c1b03e357a3}"
+image="${UNALTRAWEB_MCP_IMAGE:-ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:8b41abacad9ca2894755db7f3587a6b47c8fa8f536d88a151bdfc4ae53ba7f08}"
 project="${MCP_CONSUMER_WORKSPACE:-${UNALTRAWEB_PROJECT:-}}"
 operation=serve
 expected_image="${UNALTRAWEB_EXPECTED_IMAGE_ID:-}"

data/src/unaltraweb_mcp/component-contract.json

@@ -2,8 +2,8 @@
   "$schema": "component-contract.schema.json",
   "schema_version": 1,
   "release": {
-    "version": "0.7.4",
-    "tag": "v0.7.4"
+    "version": "0.8.1",
+    "tag": "v0.8.1"
   },
   "consumer_integration": {
     "schema_version": 1,
@@ -55,17 +55,17 @@
     "package_only_commands": ["doctor", "import-calibre", "new-web", "version"],
     "factory_required_commands": ["factory-dir"],
     "package_only_mcp": ["artifact-import-check", "import-artifact-bundle", "bibliography-add-entry", "bibliography-inventory", "build-health", "content-approval-inventory", "content-freshness-check", "content-inventory", "detect-site", "editorial-policy", "editorial-publication-check", "editorial-review-prepare", "editorial-review-record", "editorial-review-resolve", "editorial-status", "html-audit", "http-check", "image-background-check", "initialize-site", "language-policy", "list-tools", "manual-authoring-capabilities", "manual-editorial-quality-check", "manual-pdf-preview-clean", "manual-source-quality-check", "new-web", "preview-start", "preview-status", "preview-stop", "profile-check", "profile-prune", "profile-prune-plan", "prose-check", "scaffold-sync", "site-context", "site-doctor", "site-source-delete", "site-source-read", "site-source-write", "starter-templates", "translation-plan"],
-    "factory_required_mcp": ["bibliometrics-check", "bibliometrics-fetch-scimago", "bibliometrics-update", "build-site", "manual-computation-check", "manual-computation-render", "manual-computation-render-figures", "manual-computation-status", "manual-pdf-build", "manual-pdf-preview-prepare", "manual-pdf-publish", "manual-pdf-status", "manual-practice-compose", "manual-practice-pdf-build", "manual-release-check", "manual-release-prepare", "manual-release-status", "prompts", "serve", "site-check", "web-capture-check", "web-capture-render", "web-capture-status"],
+    "factory_required_mcp": ["bibliometrics-check", "bibliometrics-fetch-scimago", "bibliometrics-update", "build-site", "manual-computation-check", "manual-computation-render", "manual-computation-render-figures", "manual-computation-status", "manual-context-export", "manual-pdf-build", "manual-pdf-preview-prepare", "manual-pdf-publish", "manual-pdf-status", "manual-practice-compose", "manual-practice-pdf-build", "manual-release-check", "manual-release-prepare", "manual-release-status", "prompts", "serve", "site-check", "web-capture-check", "web-capture-render", "web-capture-status"],
     "not_bundled": ["gem", "runtime", "mcp", "compute_python", "compute_r", "web_capture", "manual_pdf", "diavisuals", "vegavisuals", "qgis_practice_verifier"]
   },
   "components": {
     "gem": {
       "kind": "gem",
       "name": "unaltraweb",
-      "version": "0.7.4",
-      "release": "v0.7.4",
+      "version": "0.8.1",
+      "release": "v0.8.1",
       "release_status": "ready",
-      "reference": "unaltraweb (= 0.7.4)",
+      "reference": "unaltraweb (= 0.8.1)",
       "repository": "https://github.com/dosquartsdedocs/unaltraweb",
       "included_in_wheel": false,
       "features": ["jekyll-core", "site-build"]
@@ -73,10 +73,10 @@
     "wheel": {
       "kind": "python-wheel",
       "name": "unaltraweb-mcp",
-      "version": "0.7.4",
-      "release": "v0.7.4",
+      "version": "0.8.1",
+      "release": "v0.8.1",
       "release_status": "ready",
-      "reference": "unaltraweb-mcp==0.7.4",
+      "reference": "unaltraweb-mcp==0.8.1",
       "repository": "https://github.com/dosquartsdedocs/unaltraweb",
       "included_in_wheel": true,
       "features": ["calibre-import", "doctor", "new-web", "offline-inspection", "mcp-control-plane", "source-ci"]
@@ -84,10 +84,10 @@
     "runtime": {
       "kind": "container",
       "name": "unaltraweb runtime",
-      "version": "0.7.4",
-      "release": "v0.7.4",
+      "version": "0.8.1",
+      "release": "v0.8.1",
       "release_status": "ready",
-      "reference": "ghcr.io/dosquartsdedocs/unaltraweb:0.7.4",
+      "reference": "ghcr.io/dosquartsdedocs/unaltraweb:0.8.1",
       "image_repository": "ghcr.io/dosquartsdedocs/unaltraweb",
       "repository": "https://github.com/dosquartsdedocs/unaltraweb",
       "included_in_wheel": false,
@@ -96,10 +96,10 @@
     "mcp": {
       "kind": "container",
       "name": "unaltraweb MCP runtime",
-      "version": "0.7.4",
-      "release": "v0.7.4",
+      "version": "0.8.1",
+      "release": "v0.8.1",
       "release_status": "ready",
-      "reference": "ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.7.4",
+      "reference": "ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.8.1",
       "image_repository": "ghcr.io/dosquartsdedocs/unaltraweb-mcp",
       "repository": "https://github.com/dosquartsdedocs/unaltraweb",
       "included_in_wheel": false,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: unaltraweb
 version: !ruby/object:Gem::Version
-  version: 0.7.4
+  version: 0.8.1
 platform: ruby
 authors:
 - dosquartsdedocs
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-26 00:00:00.000000000 Z
+date: 2026-11-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: classifier-reborn
@@ -783,6 +783,7 @@ files:
 - docs/_documentation/en/44-editorial-review.md
 - docs/_documentation/en/45-retained-documents.md
 - docs/_documentation/en/46-live-runtime.md
+- docs/_documentation/en/47-manual-context.md
 - docs/_documentation/en/47-private-practice-pdfs.md
 - docs/_documentation/en/50-faq.md
 - docs/_pages/ca/index.md
@@ -806,6 +807,9 @@ files:
 - docs/agents/deploy-provenance-86.md
 - docs/agents/deployment-integration-0.7.1.md
 - docs/agents/manual-authoring-components.md
+- docs/agents/manual-context-121.md
+- docs/agents/manual-context-fix-121.md
+- docs/agents/manual-context-pilot-review-121.md
 - docs/agents/mcp-contract.md
 - docs/agents/owner-closeout-76.md
 - docs/agents/owner-closeout-80.md
@@ -857,7 +861,9 @@ files:
 - scripts/manual/verify_release_assets.py
 - scripts/prepare_practice_candidate.py
 - scripts/prepare_practice_editions_candidate.py
+- scripts/review_manual_context_pilots.py
 - scripts/test_gem_build.py
+- scripts/test_manual_context_export.py
 - scripts/test_reproducible_jekyll_build.py
 - scripts/test_scaffold_release.py
 - scripts/test_wheel_install.py