unaltraweb 0.7.0 → 0.7.2

data/docs/agents/deploy-provenance-86.md

@@ -0,0 +1,86 @@
+# Independent PDF worker provenance — issue 86
+
+[Owner issue 86](https://github.com/dosquartsdedocs/unaltraweb/issues/86) records
+TIG's failed latest deployment at consumer
+`a87eb4fc7fe58f072413a99356d2465b36d05136`. Its published PDF 0.5.0 was produced
+from `d857f8c9f5fea90cf450c0b30b4e77a37b541275`, whereas its reusable workflow
+was pinned to `02af70001bf8085af860fd57f8d7e75ec96a89c7`. Comparing those two
+different component identities blocked the build before Pages publication.
+
+The original gates were re-executed with real published images: canonical 0.5.0,
+0.5.1 and 0.7.0 tuples fail; the 0.6.0 tuple passes because its two revisions
+happen to coincide. Retained diagnostic evidence is
+`/tmp/opencode/unaltraweb-deploy-86/matrix/evidence.json`, SHA-256
+`8640b7b68456b1bce42b9a0a271fe1c4853fde181eff9b3a130c990bd119142f`.
+
+## Corrected trust binding
+
+The reviewed provider workflow now owns these exact digest/producer records:
+
+| PDF worker | OCI digest | Producer commit |
+| --- | --- | --- |
+| 0.5.0 | `sha256:9e0b3a45753c170b795e9a9d6df61580085c113436beac5bf6c8de69b6562097` | `d857f8c9f5fea90cf450c0b30b4e77a37b541275` |
+| 0.6.0 | `sha256:0ba267cb87f53ebaca4e31805fe00610cd61fdf97a8d2c3692f4655700dceaed` | `5cf9817489c8dc47cee726bfe42fe3071cd32b85` |
+
+Both references use the fixed repository
+`ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf`. The gate first checks the defining
+provider repository and full workflow SHA, rejects an unrecorded digest before
+Docker access, pulls the exact digest and compares its actual revision label
+with the recorded producer. The worker may have been released before the workflow.
+The expected producer is not an input supplied by the consumer, and an inherited
+environment value cannot replace it. Failed pull/inspection stops the step.
+
+The deployment's reviewed-main guard, input interface and publication checks are
+unchanged. The gate uses the already-reviewed immutable artifact identity; this
+change does not introduce or claim a new live signature-verification service.
+Release preparation's existing signed-image evidence remains separate.
+
+Static workflow policy binds the whole gate, including its records and step
+controls, to reviewed canonical JSON. It rejects disabled/error-tolerant gates
+and refuses a BOM default whose worker has no approved record. A new worker
+requires an explicit provider review, updated policy and published-image tests.
+
+## Regression coverage
+
+`test/test_deploy_provenance.py` executes the actual shell blocks from the reusable
+workflow. Unit cases cover earlier legitimate producers, unknown digests with
+plausible labels, mutable/foreign references, missing/wrong labels, a label that
+matches the workflow instead of the worker, attempted expected-revision override,
+foreign/unbound provider authority, pull/inspection failure and reviewed-main
+ref/SHA rejection.
+
+The independently gated Docker case executes real pulls and inspections for both
+published workers against a later workflow revision. The ordinary CI distribution
+job must run this case; static policy rejects silently disabling it:
+
+```bash
+UNALTRAWEB_DEPLOY_PROVENANCE_DOCKER=1 PYTHONPATH=test \
+  python -m unittest test_deploy_provenance.PublishedDeployProvenanceTests
+PYTHONPATH=src python3 -m unittest discover -s test -p 'test_*.py'
+make workflow-check distribution-check
+git diff --check
+```
+
+Local checks passed 619 Python cases, with 30 optional/environment skips, plus
+the explicitly enabled real-Docker case. The actual image configuration IDs were
+`sha256:c1998dc3345444cb3994ac0cd649ad80ac88dde127dec1dd9f09c719aafe170a`
+for PDF 0.5.0 and
+`sha256:d7e7d3243616270fc9e6eed7f8238c412dbe3d9ffc18d2832d17d66ca630d139`
+for PDF 0.6.0. These tests exercise provenance gates without deploying a consumer.
+Protected PR/integration results and the exact delivery commit are recorded in
+issue 86 after integration.
+
+## Urgent consumer adoption
+
+The owner authorized a reviewed workflow-only delivery, independently of a new
+gem/wheel/image release. TIG can retain its approved 0.5.0 Gem/core, PDF digest
+and Vega selection and change only the `deploy.uses` revision in
+`.github/workflows/deploy.yml` to the corrected provider's immutable merge SHA.
+This is a reviewed local caller override; a later scaffold update must preserve
+or explicitly reconcile it rather than resetting it to an older packaged pin.
+
+In the TIG checkout, open the integration PR, verify that the content remains at
+its approved baseline, repeat the local publication checks, merge, then dispatch
+with the exact newly reviewed `main` SHA. Confirm the hosted build, Pages site
+and downloadable PDF. The provider gate proof alone does not replace TIG's full
+311-page manual validation or successful hosted deployment.

data/docs/agents/deployment-integration-0.7.1.md

@@ -0,0 +1,142 @@
+# Consolidated deployment integration — 0.7.1
+
+Published [v0.7.1](https://github.com/dosquartsdedocs/unaltraweb/releases/tag/v0.7.1)
+on 2026-10-07. The [final delivery report](owner-closeout-93.md) supersedes the
+chronological preparation states below and binds the accepted published bytes.
+
+Owner: [issue 93](https://github.com/dosquartsdedocs/unaltraweb/issues/93), following
+the workflow-only [issue 86 correction](deploy-provenance-86.md). The owner
+authorized implementation, review/integration and gated 0.7.1 publication.
+Current source preparation is distinct from a published distribution; final
+source, receipts, installed-byte evidence and publication are recorded in issue 93.
+
+## One package-owned contract
+
+The BOM now carries two additive schema-v1 fields:
+
+- `consumer_integration.site_deploy_workflow_sha`, independent of the Gem's
+  `core_sha`. Legacy records default to their core revision.
+- `deployment_contract`, with exact `manual_pdf_workers` digest/producer records
+  and bounded `caller_migrations` describing reviewed baseline/current hash pairs.
+
+The package schema and semantic checks validate repository confinement, unique
+records, nonzero identities, the selected PDF's membership and exact migration
+identities. Existing packages, receipts and the issue-86 workflow pin remain
+unchanged. PDF 0.6.0, computation/capture 0.4.0 and the accepted visual-helper
+combination are reused rather than introducing additional component upgrades.
+
+The workflow fetches at most 256 KiB of JSON from its **defining provider commit**
+on the fixed canonical GitHub repository. It does not read a consumer-supplied
+contract or producer SHA. Strict JSON rejects duplicate/non-finite values; records
+have bounded inventory and exact digest/source syntax. Fetch, lookup, pull and
+inspection failures stop publication. A selected immutable digest is checked
+against its recorded producer, not a later workflow commit. Its temporary metadata
+file is invocation-owned and removed on exit.
+
+Static policy binds the generic gate code, while approved artifacts live in the
+contract. Ready-source validation resolves the actual workflow Git pin, checks
+its gate and compares its own producer record with the package selection.
+The CI Docker test additionally creates a package caller and executes the
+preflight blocks of the workflow that caller really selects. Checking only the
+current checkout's YAML is insufficient.
+
+## Reviewed hotfix migration
+
+Only `.github/workflows/deploy.yml` is eligible for the issue-86 migration:
+
+| Identity | SHA-256 |
+| --- | --- |
+| Original package baseline | `a789870542614d5817d30ea4328c7d1ad38d27443c009c68a48ad5aaa3106b8e` |
+| Exact reviewed one-line hotfix | `c632a548d0782867be20a2a52fe03469cf63066b7364bace77fd54a226cb3b18` |
+
+Both must match. The dry-run lists `deploy-provenance-86` in `migrations`, proposes
+the new package-generated caller and binds that authorization to `plan_sha256`.
+The existing confinement, CAS rechecks, private staging, rollback and final
+manifest commit remain in force. Any additional author edit remains a conflict;
+removing the migration authority changes the plan hash. This is not a general
+force-sync or semantic rewrite of authored workflow YAML.
+
+## Acceptance stages
+
+- Unit/schema/workflow tests cover independent core/workflow pins, legacy metadata,
+  invalid or ambiguous records, exact migration, preservation of additional edits,
+  plan binding, provider-only contract acquisition and fail-closed network/Docker
+  errors.
+- `test/test_deploy_provenance.py` tests actual published PDF workers and a generated
+  caller's selected workflow. CI obtains the reviewed source SHA explicitly for
+  source-bound metadata access.
+- `test/deployment_integration_smoke.py` uses installed launchers and owned synthetic
+  manuals: fresh, populated 0.5.0 upgrade and exact reviewed hotfix. It preserves
+  author/cache hashes, applies the reviewed plan, builds PDF/web, probes HTTP and
+  executes the exact remotely pinned workflow's source/provenance gates.
+- Final acceptance must use the downloaded same-source wheel and signed MCP
+  candidate. The driver does not dispatch Pages or claim a hosted real-manual
+  deployment. TIG's authorized deployment is a separate consumer-session proof.
+
+The implementation is integrated before the containing source selects its final
+reviewed core/workflow revisions. Candidate components remain pending until that
+selection; release readiness and publication keep their existing strict receipt,
+ancestry, signing and immutable-byte gates.
+
+## Reviewed source selection
+
+Implementation `2133b8fa2f668e14d603a36d15584eed63e4386a` is integrated through
+[PR 94](https://github.com/dosquartsdedocs/unaltraweb/pull/94) at
+`2ff27f27c274eb09b2c53ef8bd374f333702d8ee`. PR CI `37526811887` and CodeQL
+`37526811747` passed, including actual provider-record acquisition and generated
+caller provenance checks. The review is agent-attributed.
+
+The containing candidate now selects this integration for both independent
+core/workflow fields and marks gem, wheel, runtime and MCP ready for same-source
+candidate preparation. The selected workflow's own contract records the reused
+PDF 0.6.0 producer correctly; no worker version change is needed.
+
+Local source validation passed 629 cases with 31 optional/environment skips,
+fresh-wheel and owned-image MCP checks/smoke, docs and prose checks. The installed
+development new/upgrade/hotfix manual proof is retained at
+`/tmp/opencode/unaltraweb-071-93/local-integration/evidence.json`, SHA-256
+`d98c0fb56d2b74839a7132cc9dc7ab3f65a9802087837af1a13070a51316a14a`.
+That development proof still used the earlier reviewed workflow pin; final
+signed-candidate acceptance must exercise the now-selected integration above.
+
+## Final-byte gate: retained-document worker closure
+
+The first candidates from `b7ec1d7a139c65b3b0b88699cdbeb19080f13be1` passed normal
+manual upgrades but failed retained-Carta freshness with the reused PDF 0.6.0.
+The manifest fingerprints `artifact_imports.CHECKER_FILES`, including the changed
+distribution module and component schema. Successful PDF generation alone was
+not sufficient: the old worker and new controller calculated different identities.
+Those first core candidates are retained diagnostic evidence and are not promoted
+as the 0.7.1 release.
+
+The signed PDF specialization already built/tested by run `37530306398` contains
+the matching 0.7.1 checker closure:
+`ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:1bb3f2dafd741e96c28639ec1cc8ccaeb81cbaa73e649f787c0b4ef59997bd4b`.
+Its configuration ID is
+`sha256:618163d3f924439792b2306617bd9612f566c5881166102fa544b4e782d569fa`,
+its producer revision is the first candidate source above and its native package
+reports 0.7.1. The changed checker files match the controller byte for byte.
+
+A local controller overlay selecting only that exact worker passed the complete
+Carta import, copied-producer retirement, receiver relocation and forced PDF
+rebuild. Both 11-page PDFs have hash
+`eb693ced023efafe36a926dd38a1bf1c85399a1b114551cc0ff32e652144c496`; original Carta
+bytes remain unchanged. Diagnostic evidence:
+`/tmp/opencode/unaltraweb-071-93/pdf071-carta-probe/evidence.json`, SHA-256
+`c076f988e43ddb474132e58f5027931085bd734242757b84fb50289ef68cde25`.
+The overlay is not a signed final MCP identity.
+
+The worker record is integrated before a follow-up selection pins its containing
+workflow and PDF. Core components return to pending during this preparation.
+Ready-source CI now requires the exact selected core, controller and PDF worker
+to agree on every retained-document checker file. This catches this class of
+incompatibility before final publication; the final signed core candidates must
+still repeat the complete composed acceptance.
+
+The producer record and checker-closure regression were integrated through
+[PR 96](https://github.com/dosquartsdedocs/unaltraweb/pull/96) at
+`3332e0b93933f12317e05f1ce8d38ce80046feab`. This is the final reviewed core/workflow
+selection. The tuple selects the verified PDF specialization above as 0.7.1,
+published by its immutable digest, and the four core components return to ready.
+Their new same-source candidates replace the rejected first core tuple in the
+eventual release receipt. No earlier release or worker is overwritten.

data/docs/agents/manual-authoring-components.md

@@ -2,6 +2,29 @@
 
 This is the component contract for MCP agents drafting or reviewing `unaltremanual` content. Read it together with the consumer site's `context/writing-profile.md`.
 
+## Private practice readings
+
+Standalone practice readings live in `practiques/<slug>/<lang>/<alumnat|docent>/`,
+using `LLEGIU-ME.md` (ca), `LEEME.md` (es) or `README.md` (en). Use
+`manual_practice_pdf_build` with an explicit practice version to produce a
+private A4-landscape PDF under an ignored, retained `sandbox/practiques/` job.
+The source requires front-matter `title`; `lang` must agree with the path.
+Use `#` for body sections and `##` for subsections. Keep a table's `Table:`
+caption and each standalone image's descriptive caption with its source.
+
+The practice wrapper reuses site metadata and manual typography. Course codes
+appear in parentheses beside the subject; the practice version is shown without
+the academic year. Logos occur only on the first page. Figures are centred and
+automatically fit the usable page after reserving the caption and its spacing.
+
+The initial reading API accepts ordinary Pandoc Markdown, local PNG/JPEG/PDF
+images, links, maths, fenced code and captioned tables. Use provider-rendered
+printable images rather than executable or remote visual sources. Liquid,
+manual-only component wrappers and automatic bibliography assembly are outside
+this reading syntax. Its private source paths are not added to the public
+editorial/translation inventories. Review the returned PDF explicitly; a layout
+approval does not change source `content_status` or authorize publication.
+
 ## Paragraph development
 
 Diagnose paragraph function before polishing sentences. A paragraph should normally have one primary job and, when the material warrants it, develop this sequence:

data/docs/agents/mcp-contract.md

@@ -1,9 +1,10 @@
 # MCP Contract
 
-The D0 additions require a containing 0.7.0 runtime. Their pinned requirements,
+The D0 additions ship in the published 0.7.0 runtime. Their pinned requirements,
 exact API mapping, lifecycle scopes and external helper-identity blocker are
 documented in [the owner contract](d0-runtime-identity.md). A source descriptor
-does not upgrade an already-running 0.6.0 connection.
+does not upgrade an already-running 0.6.0 connection. Exact public identities and
+installed acceptance are recorded in [the delivery report](owner-closeout-85.md).
 
 `unaltraweb` exposes one global, on-demand stdio MCP server for website workspaces. Every client session starts an independently named Dockerized MCP process and mounts its current consumer project at `/workspace` and at its canonical host path. Stable factory, role, and project labels preserve project-scoped lifecycle control without forcing concurrent sessions to share a deterministic container name. The image includes both FastMCP and the Jekyll runtime, so the host does not need Python, the optional `mcp` package, Ruby, or Bundler.
 
@@ -37,8 +38,10 @@ 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.6.0 MCP digest
-`sha256:736c4ddd0a543454e3edaeac2e9cfd97a1279ce472923ac54e326c1281b2ba05`.
+The post-release checkout pin selects published 0.7.1 MCP digest
+`sha256:6aa20cff86c3891a876e37ba0548fa36f3c5633c9f22ba672e9f50123d677cf6`.
+The [0.7.1 delivery report](owner-closeout-93.md) records the consolidated deployment
+contract, exact hotfix migration and matching PDF verifier closure.
 Existing processes keep their running image until clients reconnect. Site build
 defaults and customized Makefiles remain separate, explicitly reviewed selections.
 
@@ -86,6 +89,8 @@ baseline format nor runtime cleanup changes.
 
 | Resource | Description |
 | --- | --- |
+| `web://practice-edition-schema` | Versioned Web recipient/edition configuration, separate from the producer-owned GIS descriptor. |
+| `web://practice-verifier-runtime` | Static private controller/package/profile identities and distinct release metadata; acquisition belongs to the hub. |
 | `web://runtime-identity` | Bounded identity of this serving process: startup/current code, instance/PID namespaces, binding, runtime selections and cooperative lifecycle. |
 | `web://distribution` | Package-owned component BOM plus offline, feature-aware doctor findings for the current factory and project. |
 | `web://site-context` | Site profile, feature flags, content inventory, bibliography, bibliometrics, build state, and offline consumer-update advisory. |
@@ -113,8 +118,68 @@ baseline format nor runtime cleanup changes.
 
 ## Tools
 
+Private teaching editions use `manual_practice_compose(config, dry_run=false)`
+(CLI `mcp manual-practice-compose`, factory Make `manual-practice-compose`).
+`web://practice-edition-schema` supplies the versioned Web composition contract.
+The editor invokes the native CLI of the hub-prepared private QGIS controller, validates the full common
+bundle, selects explicit IDs with their complete producer closure, and retains
+one independent PDF and one ZIP per recipient, plus external receipts, under
+`dist/practiques/`. The PDF is copied from the sealed reading job and has exactly
+the same bytes as its ZIP member; no second render occurs. The entire edition
+directory is installed atomically and never replaces an existing edition. GIS parsing,
+execution and offline project reopening remain producer-owned.
+
+Each PDF build returns its original PDF and receipt hashes. Composition captures
+and checks that seal before building the other recipient, then copies only those
+sealed bytes. A changed PDF or replaced/resealed receipt fails before publication.
+
+`packages.<recipient>` retains its ZIP fields and adds `pdf` with the independent
+PDF path/hash/bytes and its own receipt path/hash. Names share the same stem:
+`<slug>[-docent]-<version>-<lang>.pdf` and `.zip`. Source/reading code remains
+versioned; data, PDFs, ZIPs and their retained sandbox/dist jobs remain ignored
+deliveries for Moodle, not Git publication. The paired PDF keeps ZIP-relative
+resource links; extract the ZIP beside it for those links to resolve locally.
+
+An edition's `gis.profile` explicitly selects `qgis-practice-v1` or
+`qgis-practice-v2` and its matching producer schema hash. Omitted profile is the
+legacy v1 case only. New configurations explicitly select verifier origin
+`prepared-image`, its image ID, native installed-package revision and schema hash.
+Legacy installed-wheel configuration shapes remain readable but are not silently
+converted or executed by this public Web runtime. Schema discovery invokes the
+requested profile in the private image. The selected bundle check must return
+that same profile. V2 map exports and their font/symbol/sidecar closures retain
+producer-declared roles and paths; the editor does not inspect their native formats.
+
+The public Web image contains no private QGIS package. The hub prepares the
+authenticated private image before activation; missing/mismatched images produce
+a concrete blocker without pull/build. Native calls reuse bounded processes,
+mount encoding and exact worker lifecycle. `practice_verifier` is a startup-fixed
+worker selection. Release wheel hashes and release producer revisions are declared
+provenance, separate from observed image/package identity; no `direct_url` is
+fabricated. Public CI reports private checks as `not_run`.
+See [private-practice-verifier-98.md](private-practice-verifier-98.md).
+
+Existing private readings can be declared once in `_config.yml` under
+`unaltraweb.practices.readings`, with exact `source`, `slug`, `lang`, `recipient`.
+Only Markdown beneath `practiques/` or `_practices/` is accepted. The same resolver
+serves PDF preparation and targeted `prose_check` / `editorial_review_prepare`.
+Private targets include draft/unpublished prose and retain original anchors;
+they are excluded from the default public corpus. Mapping does not approve copy
+or expose private directories through Jekyll.
+
+Reading mappings and edition readings accept the same optional `bindings` list:
+`reference`, exactly one `path` or selected `product`, required `sha256`, and
+optional portable `destination`. One practice resolver uses these declarations
+for both image snapshots and prose links. It never searches sandbox directories.
+Composition normalizes a prose href relative to the original source and emits
+only the authorised recipient's ZIP destination; bound files/maps and effective
+Pandoc sources are fingerprinted and receipted. Normal filesystem validators stay
+strict. Standalone PDFs allow explicit image bindings but refuse local file links
+without a portable edition context; HTTPS and internal anchors remain intact.
+
 | Tool | Notes |
 | --- | --- |
+| `manual_practice_compose` | One versioned consumer configuration selects GIS roots, two approved reading hashes and optional declared editable-SVG resources; delivers an independent PDF and ZIP per recipient with complete closure and create-only receipts. |
 | `runtime_identity` | Observe the actual serving instance, startup/current package evidence and selected/observed images; never prepare a runtime or inspect site content. |
 | `runtime_drain` | With `confirm=true`, stop admission on this connection; then close stdio and verify exact container/session resource termination. It is not workspace-wide down. |
 | `distribution_doctor` | Return offline component/factory/project findings with stable codes and optional local Docker image inspection that never pulls. |
@@ -130,7 +195,7 @@ baseline format nor runtime cleanup changes.
 | `site_source_read` | Read one allowed UTF-8 site source and return its exact SHA-256. |
 | `site_source_write` | Dry-run or atomically create/update one allowed source. Creates require `create_only`; updates require the exact SHA-256 returned by a read. |
 | `site_source_delete` | Dry-run or delete one allowed source with exact SHA-256 and explicit confirmation. It never deletes `_config.yml` or directories. |
-| `scaffold_sync` | Dry-run or transactionally synchronize the nine package-managed scaffold controls against `.unaltraweb/scaffold.json`; preserve local edits if the package file has not changed from baseline, reject conflicting edits and known version downgrades, and optionally require `expected_plan_sha256` from the reviewed proposal. Exact package bytes may be adopted without rewriting. Adopted, unchanged and preserved files are rechecked around the manifest-last transaction; rollback covers partial apply. README prose remains site-owned. |
+| `scaffold_sync` | Dry-run or transactionally synchronize the ten package-managed scaffold controls against `.unaltraweb/scaffold.json`; preserve local edits if the package file has not changed from baseline, reject conflicting edits and known version downgrades, and optionally require `expected_plan_sha256` from the reviewed proposal. Exact package bytes may be adopted without rewriting. Adopted, unchanged and preserved files are rechecked around the manifest-last transaction; rollback covers partial apply. README prose and source-CI project policy remain site-owned. |
 | `profile_check` | Check current profile and expected content/config paths. |
 | `prose_check` | Check a selected content target or all supported reader-facing sources and public metadata using shared profile/genre rules; no writes or model calls. |
 | `editorial_policy` | Inspect common guidance, profile defaults, genre overrides, local writing preferences and optional publication requirements. |
@@ -152,6 +217,7 @@ baseline format nor runtime cleanup changes.
 | `web_capture_render` | Start Jekyll and Chromium on an ephemeral internal Docker network, then publish original PNG plus editable annotated SVG from declared CSS selectors. |
 | `manual_pdf_status` | Inspect PDF configuration, sources, generated artefacts, published paths, selector, and freshness without Docker, network, or writes. |
 | `manual_pdf_build` | Build one or all configured language PDFs and first-page cover previews under `tmp/`; `release_selector` defaults to `latest` and is part of the PDF fingerprint. |
+| `manual_practice_pdf_build` | Build one private A4-landscape reading from `practiques/<slug>/<lang>/<audience>/` into an ignored, retained sandbox job. Reuse manual metadata/logos; require a prepared PDF toolchain; never publish or package course data. `dry_run` plans without writes and `run` names an explicit retained attempt. |
 | `manual_pdf_preview_prepare` | Build only stale `latest` PDF languages, then atomically stage ignored, untracked PDF and cover copies for local Jekyll review under a cleanup receipt. Always reports `publishes: false`; disabled PDF configuration is a no-op unless receipt-owned preview files still require cleanup. |
 | `manual_pdf_preview_clean` | Dry-run or remove only preview files whose path, Git state, content hash, and file identity still match the staging receipt. Real cleanup requires explicit confirmation plus the dry-run's exact `receipt_sha256` as `expected_receipt_sha256`, and never publishes. |
 | `manual_pdf_publish` | Copy built PDFs and covers to configured public assets. Defaults to dry-run; real publication requires explicit confirmation, and the selector must match the build. |
@@ -188,6 +254,36 @@ Manual PDF publication is a local workspace operation: it copies reviewed artefa
 
 ## New Site Initialization
 
+### Private Practice Readings
+
+`manual_practice_pdf_build(source, version, run="", dry_run=false)` delegates to
+the factory target `manual-practice-pdf-build`. Source paths are
+`practiques/<slug>/<ca|es|en>/<alumnat|docent>/<localized-name>.md`, using
+`LLEGIU-ME`, `LEEME` and `README`. The consumer must exclude `practiques/`,
+`sandbox/` and `dist/` from Jekyll and ignore `sandbox/practiques/` in Git.
+`profile_check` blocks a manual with practice sources and missing exclusions.
+
+The controller reuses manual metadata normalization and its authoritative
+typographic preamble, with a factory-owned A4-landscape article wrapper. It
+snapshots only the selected Markdown, local PNG/JPEG/PDF images, logos, template
+and filters. Its network-disabled, read-only worker receives that snapshot and
+one writable output directory; it receives neither checkout nor Docker socket.
+The already-prepared PDF toolchain is resolved to an exact image ID and never
+pulled implicitly. Session/project/token worker labels retain the existing D0
+ownership and timeout-cleanup contract.
+
+Jobs under `sandbox/practiques/` are create-only and sealed last. Repeat calls
+verify and reuse the exact job when its effective inputs match. Changed source,
+assets, rendering controls or image identity select another job; a nominal MCP
+version change alone does not. Edited, incomplete or conflicting jobs are
+retained. The optional `run` name provides an explicit retry/review identity.
+Every result reports `publishes: false`.
+
+This API compiles a reading, not a GIS job, public chapter or Moodle ZIP. The
+larger producer-handoff and package contract remains under issue #98. See
+[private practice PDFs](../_documentation/en/47-private-practice-pdfs.md) for
+supported syntax and adoption in an existing manual.
+
 ### Retained Letter Integration
 
 The published 0.6.0 release adds package-only import/check commands and the
@@ -223,7 +319,17 @@ It sets `lang`, `default_lang`, and `languages` so a new site has an explicit so
 
 Before writing, it validates every managed path, rejects destination symlinks, and compares existing files with the complete rendered scaffold through bounded regular-file reads. Identical files make repeated calls idempotent. Any differing file or file/directory collision detected during preflight aborts the whole operation before website files are written. Descriptor-relative, no-clobber writes and a final descriptor-relative content check prevent raced paths from being followed or overwritten; overwrite mode is not available. The baseline manifest is created after every other scaffold file.
 
-The baseline records exactly `.gitignore`, `.unaltraweb/docker-mount.sh`, `.github/CONTRIBUTING.md`, `.github/dependabot.yml`, `Makefile`, `Gemfile`, `Gemfile.lock`, `.github/pull_request_template.md`, and `.github/workflows/deploy.yml`. `scaffold_sync` updates one of these while its bytes still match the recorded baseline, adopts it when its bytes already equal the current package payload, and creates a newly managed path only when absent. If the package payload still equals the baseline but the local file differs, it preserves the local file and the original baseline hash; a subsequent upstream edit will still conflict. Conflicting local/upstream edits, missing managed files, collisions, unsafe paths and known newer consumer versions block the whole apply. It removes retired paths only from the baseline and never deletes their project files; it also never changes site-owned README/agent guidance, config, seed content, bibliography, data, or assets. A real synchronization requires `dry_run=false` and `confirm_sync=true`; adopted, unchanged and preserved files are included in the final rechecks around the manifest-last commit.
+The baseline records exactly `.gitignore`, `.unaltraweb/docker-mount.sh`, `.github/CONTRIBUTING.md`, `.github/dependabot.yml`, `Makefile`, `Gemfile`, `Gemfile.lock`, `.github/pull_request_template.md`, `.github/workflows/deploy.yml`, and `.github/workflows/source-checks.yml`. `scaffold_sync` updates one of these while its bytes still match the recorded baseline, adopts it when its bytes already equal the current package payload, and creates a newly managed path only when absent. If the package payload still equals the baseline but the local file differs, it preserves the local file and the original baseline hash; a subsequent upstream edit will still conflict. Conflicting local/upstream edits, missing managed files, collisions, unsafe paths and known newer consumer versions block the whole apply. It removes retired paths only from the baseline and never deletes their project files; it also never changes site-owned README/agent guidance, config, seed content, bibliography, data, assets, or `.unaltraweb/source-checks.json`. A real synchronization requires `dry_run=false` and `confirm_sync=true`; adopted, unchanged and preserved files are included in the final rechecks around the manifest-last commit.
+
+Source CI is a separate host entrypoint, `unaltraweb-source-checks` (equivalently
+`python -I -m unaltraweb_mcp.source_checks`), not another MCP server. One packaged
+workflow control calls it for all profiles; only the bounded Git-versioned JSON
+policy differs by project. It wraps the public `profile-check` and `prose-check`
+commands and observes the existing approval inventory without granting approval.
+Read-only clone mounts, no Docker socket, network-none checkers, explicit partial
+coverage and base-to-head inventory checks preserve the distinction between
+source conservation and retained-input/domain validation. See
+[source-ci-98.md](source-ci-98.md) for activation and the public/private GitHub boundary.
 
 At session start, `site_context.update_status` supplies an offline advisory against the active MCP package, including current literal version pins, target integration tuple, planned paths, preserved files, conflicts and `plan_sha256`. The agent explains available updates and asks for explicit acceptance before invoking `scaffold_sync` with that digest as `expected_plan_sha256`. The digest binds the consumer path, configuration, baseline, observed managed bytes and target package bytes; stale approval is rejected before writes. The parameter is optional for compatibility with existing explicit sync callers, but the guided flow always supplies it. An update can refresh scaffold controls without claiming a newer semver release. Unmanaged sites report an unavailable plan instead of being reinitialized. A declined update leaves normal content work available; there is no background network poll, self-upgrade, Git operation or automatic artefact regeneration. This flow requires a reviewed MCP/package release containing it and a reconnected client; updating the discovery checkout alone cannot replace the public digest-pinned runtime.