unaltraweb 0.3.0

data/docs/_documentation/en/33-reusable-workflows.md

@@ -0,0 +1,136 @@
+---
+title: Use Reusable GitHub Workflows
+description: GitHub Actions workflows provided by the unaltraweb core.
+lang: en
+ref: reusable_workflows
+profiles:
+- unaltredocs
+documentation_profiles:
+- github-publishers
+- contributors
+- core-developers
+section: Publish With GitHub
+weight: 70
+permalink: "/reusable-workflows/"
+nav_title: GitHub Workflows
+---
+Child sites should keep workflow files thin and call reusable workflows from the core repository.
+
+These wrappers should normally be manual-only. Use `workflow_dispatch` so a push or Dependabot pull request does not start a deploy unless someone explicitly asks for it.
+
+## Site deploy
+
+{% raw %}
+```yaml
+jobs:
+  validate:
+    # Generated callers fail unless reviewed_sha equals the selected main commit.
+    # Keep this generated job unchanged.
+  deploy:
+    uses: dosquartsdedocs/unaltraweb/.github/workflows/site-deploy.yml@<reviewed-commit-sha>
+    with:
+      reviewed_sha: "${{ inputs.reviewed_sha }}"
+      manual-pdf-image: "ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:<reviewed-digest>"
+      check-manual-pdf: false
+      sync-manual-pdf: true
+      vegavisuals-sha: "<reviewed-vegavisuals-commit-sha>"
+```
+{% endraw %}
+
+Pin the reusable workflow to a reviewed commit because it receives Pages and OIDC permissions. The generated caller accepts only `workflow_dispatch`, requires the full locally reviewed SHA, and fails unless the selected ref is `refs/heads/main` at exactly that SHA. The reusable workflow repeats that source check, requires the PDF worker by immutable GHCR digest, rejects configured PDF/cover outputs already tracked by Git, installs Ruby dependencies, rejects stale computations, web captures and manifest-backed Vega visualizations, builds with the `unaltraweb` gem config and deploys to GitHub Pages. The checks are no-ops when their source configuration is absent. Set `check-computations`, `check-web-captures` or `check-visualizations` to `false` only when another freshness gate intentionally owns that source type.
+
+A site with `.vegavisuals.yml` must pass `vegavisuals-sha` as the full lowercase 40-character SHA of a reviewed commit. The workflow installs that exact revision from the fixed public repository URL before checking freshness; it does not accept a mutable tag, branch, or caller-supplied URL. Deployment only checks committed visualization outputs; run `make visualization-render` locally rather than rendering in CI.
+
+For `unaltremanual`, the `latest` channel is a manual-only deployment from the reviewed `main` branch. PDF output is disabled in a fresh manual scaffold until a maintainer configures it. When enabled, deployment deterministically rebuilds every configured language and places the current PDF and cover into the site artifact before Jekyll publishes it. The default `assets/pdf/manual-<lang>.pdf` and `assets/img/manual-cover-<lang>.png` outputs are generated deployment products and are not committed. Existing tracked copies require a reviewed one-time `git rm --cached`. The resulting website and PDF display `latest`; release checks reject generated `legacy/` or `sandbox/` content.
+
+Clean package scaffolds include a manual GitHub Pages wrapper pinned to a reviewed workflow revision. It has no push deployment trigger: a maintainer runs it only after local checks/renders and human review. The optional integration template retains additional local publishing experiments, but generated sites do not publish from local validation targets.
+
+The `consumer_integration` object in `src/unaltraweb_mcp/component-contract.json` is the single source for the reviewed core revision, workflow path, attested manual PDF image digest, and Vega renderer revision. The scaffold renders that tuple atomically into `Gemfile`, `Gemfile.lock`, and the packaged caller. The caller passes the existing `reviewed_sha` input through to the provider, so the reviewed `main` source is checked independently at both caller and provider boundaries.
+
+This pin-only integration follows the required M -> D -> B order: D was built from M's permanent identity before the caller recorded either value. Repeat that order for future provider updates; never use `@main` or substitute a mutable/version-tagged image for D.
+
+## Stable manual releases
+
+`.github/workflows/site-release.yml` is a separate `workflow_call`-only boundary for future `vYYYY.MM` and `vYYYY.MM.N` releases. Its preparation job has only `contents: read`: it checks the reviewed `main` SHA, checks out an immutable core revision, requires digest-pinned manual PDF and MCP site-build images, records the Python runtime from the site-build image, derives `SOURCE_DATE_EPOCH` from the reviewed consumer commit, and runs Jekyll offline inside the same MCP image used for local candidate review. When `.vegavisuals.yml` exists, the job runs the freshness check from the exact reviewed vegavisuals checkout rather than merely recording its SHA. It then requires the rebuilt version-2 `release-manifest.json` SHA-256 to equal the locally reviewed candidate digest supplied by the caller, assembles a deterministic web archive, writes checksums, and uploads a same-run Actions artifact. Only the dependent `publish` job receives `contents: write`. That job requires the `stable-release` GitHub environment and consists only of pinned artifact download, immutable verifier checkout, exact Python setup, and the reviewed publisher. The publisher verifies the asset allowlist, source/runtime identity, site tree fingerprint and PDF hashes, creates a lightweight tag at the reviewed source SHA, and addresses one matching draft by numeric release ID. A retry resets that draft's canonical metadata and assets, downloads them, compares every byte with the prepared candidate, confirms that the remote asset inventory and tag have not changed, and publishes the draft last.
+
+Prepare and check the stable candidate locally from the exact clean `main` commit, then obtain the caller input with `sha256sum tmp/manual-release/<selector>/release-manifest.json`. CI is the authoritative offline rebuild; any network-dependent local difference changes the manifest digest and fails before any job has publication authority. Before enabling a stable caller, protect `main` against direct changes, enable immutable releases in repository settings, protect `v*` tags while allowing only the approved release workflow to create them, and configure required reviewers with self-review and bypass disabled for the repository's `stable-release` environment. Restrict that environment to protected `main`. No stable caller is installed by the current scaffold because the reusable workflow must first exist at a reviewed immutable commit. Use two commits:
+
+1. Merge the reusable workflow and every helper it executes; call the resulting permanent commit `A`.
+2. In a follow-up change, add the consumer caller and pin both its `uses:` and `core_sha` to `A`. Require `reviewed_sha`, `candidate_manifest_sha256`, and the reviewed PDF and MCP site-build image digests as dispatch inputs. Never use `@main`, and do not squash or rebase `A` away.
+
+This is deliberate: a workflow cannot truthfully pin itself to the commit being created. Preparing a local candidate or passing the read-only job is evidence, not publication authorization. Do not dispatch a stable release until a stable edition is intentionally approved.
+
+A future caller should keep the reviewed core revision static and grant write authority only to the reusable job:
+
+{% raw %}
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      selector:
+        required: true
+        type: string
+      reviewed_sha:
+        required: true
+        type: string
+      candidate_manifest_sha256:
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  release:
+    permissions:
+      contents: write
+    uses: dosquartsdedocs/unaltraweb/.github/workflows/site-release.yml@<commit-A>
+    with:
+      selector: "${{ inputs.selector }}"
+      reviewed_sha: "${{ inputs.reviewed_sha }}"
+      candidate_manifest_sha256: "${{ inputs.candidate_manifest_sha256 }}"
+      core_sha: "<commit-A>"
+      manual_pdf_image: "ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf@sha256:<reviewed-digest>"
+      site_build_image: "ghcr.io/dosquartsdedocs/unaltraweb-mcp@sha256:<reviewed-digest>"
+```
+{% endraw %}
+
+## Publication metrics
+
+```yaml
+jobs:
+  metrics:
+    uses: dosquartsdedocs/unaltraweb/.github/workflows/metrics-update.yml@main
+```
+
+Metrics updates are manual and explicit. Normal site deploys remain static.
+
+## Project computation images
+
+Projects that extend a core computation image can publish a separate GHCR package without copying the factory workflow:
+
+```yaml
+name: Publish Python computation image
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  packages: write
+
+jobs:
+  image:
+    uses: dosquartsdedocs/unaltraweb/.github/workflows/project-compute-image.yml@<reviewed-commit-sha>
+    with:
+      engine: python
+      image: example-compute-python
+      dockerfile: Dockerfile.compute-python
+      context: .
+      base_image: ghcr.io/dosquartsdedocs/unaltraweb-compute-python@sha256:<digest>
+      test_command: make test-compute-image
+```
+
+Pin the reusable workflow to a reviewed commit because it receives the caller's package-write token. The provider checkout is bound to the defining job's `workflow_repository` and `workflow_sha`, not caller-controlled workflow identity. Before a login is possible, default-branch candidate publication checks that provider revision with `distribution-check`, while an exact `vX.Y.Z` tag publication uses `distribution-release-check`. The workflow also requires a digest-pinned `base_image`, validates confined build paths and the selected ref, runs the optional project test command, and completes a no-push image build. Only the dependent publication job can publish `main` and `sha-*` under the consumer repository owner or semver/release-tag metadata from a release tag. Published images include SBOM and provenance attestations. Keep engine-specific dependencies and lockfiles in that project; for example, a TIGIT site should publish `tigit-compute-r`, not a TIGIT variant of the core package.
+
+After publication, make the package public or authenticate Docker, select its full GHCR digest in `.unaltraweb/computations.yml`, run `manual-compute-render`, and commit the updated generated artifacts and computation lock. Publishing an extension does not select or rerender it automatically.

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

@@ -0,0 +1,164 @@
+---
+title: Understand The Distribution Model
+description: Core/template split and update model for unaltraweb.
+lang: en
+ref: distribution_model
+profiles:
+- unaltredocs
+documentation_profiles:
+- core-developers
+section: Core Development
+weight: 620
+permalink: "/distribution/"
+nav_title: Distribution Model
+---
+`unaltraweb` is the source of truth for reusable code. Template repositories should stay thin and contain only site-specific content, local overrides and small integration files.
+
+## Repository Roles
+
+- `unaltraweb`: layouts, includes, Sass, assets, Jekyll plugins, Python and shell tooling, reusable GitHub Actions workflows, documentation, small internal examples and the shared Docker runtime image.
+- `unaltraweb_mcp` package scaffolds: clean profile-specific config, localized home pages, content roots, and native build/serve files used by new sites.
+- `unaltraweb-template`: multi-profile demo assets, local Docker workflow, Dependabot config, workflow wrapper and Playwright integration tests.
+- `docs/` in `unaltraweb`: public reference site for the platform itself.
+
+The template is the better place to validate gem consumption, centralized styles and shared logic because it runs as a child site. It is not required to create a site: package scaffolds are the supported clean starting point.
+
+## Component Contract
+
+`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 only its Python control/inspection modules, schema/BOM, and clean package-owned scaffolds. In particular it does not contain Ruby theme assets, Docker image layers, factory Make/scripts/docs, TeX, Chromium, computation environments, `diavisuals`, or `vegavisuals`.
+
+For the selected release, the core-owned container references use `0.3.0`; the BOM selects the published `diavisuals v0.3.1` and `vegavisuals v0.3.1` releases. Current checkouts can be used through `suggested_path`, while immutable release references remain the distribution contract. `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 the final same-commit candidates is `ready`, while an already-published component is `released`.
+
+## Wheel And Doctor
+
+A clean `unaltraweb-mcp` wheel works without a factory checkout for `version`, `new-web`, top-level `doctor`, constrained source management, scaffold synchronization, `site-doctor`, HTML audit, and pure inspection where feasible. Examples include `mcp list-tools`, `starter-templates`, `detect-site`, `site-context`, `profile-check`, content/language/bibliography inventories, and `build-health`.
+
+```bash
+unaltraweb-mcp doctor
+unaltraweb-mcp doctor --project /path/to/site
+unaltraweb-mcp doctor --project /path/to/site --docker
+```
+
+Doctor performs no network requests. It reports limited wheel mode as an informational healthy state, reads `_config.yml`, Gemfile/lock, Make pins, computation settings, capture recipes, PDF enablement, and companion manifests when a project is supplied, and checks only components relevant to those features. `release_ready` is separate from operational `ok`, so any pending or unavailable component release is visible without making package-only inspection unusable. Companion-specific findings retain their stable companion codes; core package and image releases use the generic release codes. `--docker` optionally inspects local Docker and selected image presence; it never pulls or builds. Every finding has stable `code`, `severity`, `expected`, `actual`, and `remediation` fields.
+
+Factory-backed MCP serving, site preflight/build, computations, captures, PDF operations, bibliometrics, and prompt loading still require the checkout or the selected MCP image. A wheel invocation fails those commands explicitly and tells the caller to set `UNALTRAWEB_FACTORY_DIR`; it does not pretend the factory assets were bundled.
+
+## User Paths
+
+### GitHub-only editing
+
+Users can push a site created by `new_web` and edit small content changes in the GitHub web UI. The generated README requires an assigned issue or accepted file reservation, one task branch, one active editor per file, and a small Draft pull request. Editors never change `main` directly; they stop and ask a maintainer when work overlaps or conflicts.
+
+This path is intended for small content edits, bibliography updates, course/manual chapter edits and configuration changes. It does not require Docker, Make or a local development environment. A maintainer checks and renders the branch locally, reviews it, merges it, and only then starts deployment manually.
+
+For `unaltremanual`, `latest` is a manual-only deployment from reviewed `main`; a push does not deploy it. The caller requires the exact locally reviewed commit SHA and an immutable manual PDF worker digest. When PDF output is enabled, its default PDF and cover are generated for deployment rather than versioned. The website marker and PDF both identify the selected channel/version. Stable `vYYYY.MM(.N)` editions use explicit immutable releases, bind the rebuilt assets to the locally reviewed candidate manifest, and reject generated private/runtime trees.
+
+### Local editing
+
+Users who need larger edits can clone their generated site repository and use its package-scaffolded Docker workflow:
+
+```bash
+make serve
+make build
+make test
+make down
+```
+
+Local editing requires Git, Docker and GNU Make. On Windows, use WSL2 with Docker Desktop and run the same commands inside the WSL Linux shell.
+
+Theme development can happen side by side by pointing the template at a local core checkout:
+
+```bash
+make serve LOCAL_CORE=../unaltraweb
+make build LOCAL_CORE=../unaltraweb
+make test LOCAL_CORE=../unaltraweb SITE_PROFILE=unaltreprojecte
+```
+
+## Demo Strategy
+
+- Template demo: realistic content for `unaltreselfie`, `unaltreprojecte`, `unaltremanual` and `unaltredocs`, used to validate the gem consumer path.
+- Core docs: the `unaltraweb` reference site, focused on concepts, profile capabilities, syntax, customization points, tools and links to the template.
+- Avoid duplicating full demo content between the two repositories.
+
+## Core Docs Publishing
+
+The core repository deploy workflow is manual. It builds only `docs/` and publishes it with GitHub Pages Actions. The root core Jekyll build excludes `docs/`, so the reference site can use its own root-relative permalinks without colliding with the internal core demo build.
+
+Reference deployment, link checks, Docker image publishing and publication metrics run manually from GitHub or locally. Repository CI runs for pushes and pull requests, and CodeQL runs for pull requests, default-branch pushes and a weekly schedule. Neither automatic workflow deploys or publishes.
+
+## Updates
+
+Repositories created from a GitHub template are not linked to the template as forks, so template changes are not automatically proposed to users.
+
+For that reason:
+
+- normal improvements should ship through the `unaltraweb` gem or reusable workflows;
+- site repositories can enable Dependabot for Bundler and GitHub Actions, but deploy workflows should remain manual;
+- breaking changes should be released with migration notes;
+- scaffold changes should be rare; generated sites can explicitly dry-run `scaffold_sync`, which updates only unchanged baseline runtime files (including the pull-request template), creates newly managed missing files, reports conflicts, never deletes paths, stages every output, rechecks adopted and unchanged files around the manifest write, rolls the whole transaction back on failure, and commits its manifest last. Generated README prose is site-owned and is not overwritten by synchronization.
+
+## Docker Runtime
+
+The pending `0.3.0` contract names the intended semver runtime target. Before release, a maintainer may manually run the Docker workflow from the final reviewed default-branch commit. Its credential-separated build, test, and promotion jobs publish SHA-only candidates, verify and test their exact signed digests without write authority, and only then assign `main` and `latest` from a non-executing package-write job. Local maintainer images use explicit names such as `unaltraweb:dev`.
+
+The same candidate rule applies to workers. The Python and R computation workers are already released and selected by immutable digest; the gem, wheel, runtime, MCP, web-capture worker, and manual PDF worker remain truthfully `pending`. The final reviewed source commit marks only candidate components `ready` before default-branch publication. For runtime, MCP, and manual PDF, `build-candidates` builds each image once under only its SHA tag, builds MCP from the runtime digest, and creates a GitHub-signed build-provenance attestation for each exact digest while retaining BuildKit SBOM and maximum provenance. It never runs those images. `test-candidates` has only read permissions, verifies registry-stored attestations against the exact repository, workflow, and source commit, pulls and checks all revision labels, logs out of GHCR, and then runs every Ruby test, all manual PDF integrations, reproducibility, MCP smoke, and docs against digest references without exposing `GH_TOKEN`. Only its successful digest outputs reach `promote-candidates`, which has package write but executes no candidate and points `sha-*`, `main`, and `latest` to those digests without rebuilding. A failure can leave a reviewable SHA candidate but cannot move broad aliases.
+
+The pre-build absence lookup is not an atomic no-clobber guarantee: GHCR exposes separate read and tag-write operations, not compare-and-swap. A package administrator could race the lookup or later retagging. Immediate equality checks and post-promotion verification bound that risk, while the signed, source-bound digest tested by the read-only job remains the evidence to record. An immediately following `release-candidates.json` child commit records immutable image digests and package checksums while changing no other path. Validation requires the parent to belong to the default branch, requires each image digest to use the component's declared GHCR repository, and checks exact package names. Before semver promotion, the tag-only job proves that each source commit's SHA tag still resolves to the recorded digest, verifies its GitHub-signed attestation with `receipt.source_commit` as the source digest, and requires the image revision label to equal that commit. It then uses `docker buildx imagetools create` to add and verify semver aliases without rebuilding, executing, or trusting a mutable source tag. Excluding the receipt from image and package contents avoids an impossible self-digest for the MCP. Publication workflows require the reviewed manual PDF image by full digest; this candidate state does not assert that a remote `v0.3.0` image exists. Separate worker images keep Chromium, TeX, and computation environments out of ordinary site and wheel installs.
+
+The image is not the source of layouts or styles. Child sites still get those from the `unaltraweb` gem declared in their `Gemfile`. This keeps updates centralized in two places:
+
+- gem updates change reusable site behaviour, layouts, Sass, plugins and scripts;
+- Docker image updates change the local build/runtime environment.
+
+Before recommending the local Docker workflow to unauthenticated users, complete this first-publish checklist:
+
+- Mark the components `ready` in the final reviewed source commit.
+- Run the image and package-preparation workflows from that exact default-branch commit to publish `sha-<full-commit>` images and prepare the gem/wheel candidates without creating a release tag. For runtime, MCP, and manual PDF, preserve the workflow summary that pairs the source commit with all three signed and read-only-tested digests; `main` and `latest` move only from the dependent promotion job after those tests pass.
+- Add only `release-candidates.json` in the next commit, recording the parent source SHA, immutable image references, package basenames and SHA-256 checksums.
+- Run `make distribution-release-check`, create the exact release tag on the receipt commit, then run the image workflows from the tag to promote the recorded manifests to semver aliases.
+- Open the `ghcr.io/dosquartsdedocs/unaltraweb` package settings in GitHub.
+- Make the package public.
+- Confirm that `docker pull ghcr.io/dosquartsdedocs/unaltraweb:0.3.0` works without `docker login`.
+- Make the `ghcr.io/dosquartsdedocs/unaltraweb-mcp` package public after its first publication.
+- Confirm that `docker pull ghcr.io/dosquartsdedocs/unaltraweb-mcp:0.3.0` works without `docker login`.
+
+The receipt uses a full source commit and different evidence by component kind. This abbreviated example shows both forms; the real `components` object must contain exactly every component marked `ready`:
+
+```json
+{
+  "schema_version": 1,
+  "release": "v0.3.0",
+  "source_commit": "0123456789abcdef0123456789abcdef01234567",
+  "components": {
+    "runtime": {
+      "reference": "ghcr.io/dosquartsdedocs/unaltraweb@sha256:<64 lowercase hex characters>"
+    },
+    "gem": {
+      "artifact": "unaltraweb-0.3.0.gem",
+      "sha256": "<64 lowercase hex characters>"
+    }
+  }
+}
+```
+
+This checklist describes future publication verification; changing the contract does not publish, tag, or release any artifact.
+
+## CI And Release Gates
+
+Automatic `.github/workflows/ci.yml` uses `distribution-check`. It validates schema/version/reference parity and release-status declarations, but permits a selected component to remain explicitly `pending` or `unavailable`. It also runs Python compile/unit/diff checks, wheel/gem checks, workflow policy, MCP smoke and the docs build. CodeQL is an independent automatic security check for JavaScript/TypeScript, Python and Ruby.
+
+`distribution-release-check` is the strict coordinated-release gate. The final reviewed source commit marks authorized candidate components `ready`; already-published components may be `released`, and released containers except MCP must use digest references. Core artifact workflows keep source/package preflights unprivileged and without registry access. Runtime, MCP, and manual PDF use separate signing/package-write build, read-only test, and non-executing package-write promotion jobs. Every SHA-only build gets a GitHub-signed provenance attestation; tests verify its exact digest, signer workflow, and source commit before removing registry credentials and running it; broad aliases receive only successful test-job digest outputs. The receipt-only child commit binds every `ready` component to an immutable image digest or package checksum and binds those candidates to its parent source SHA. An exact semver release tag is rejected unless that complete evidence is valid. Tag jobs reverify SHA-tag equality, signed source provenance, and revision labels before promoting the receipt's manifests rather than rebuilding or executing them, preserving their SBOM and provenance attestations. The MCP candidate consumes the exact runtime digest emitted by the candidate runtime build.
+
+The manual `.github/workflows/package-prepare.yml` builds and checks the gem and wheel, writes `SHA256SUMS`, and uploads an immutable workflow artifact whose name includes the source commit SHA. It does not call RubyGems, PyPI or GitHub Releases. Passing CI, preparing candidates, and later passing the strict coordinated-release gate are evidence for a release, not authorization to publish: tagging, starting a credentialed image workflow, uploading language packages and creating a GitHub release remain separate explicit maintainer approvals.
+
+## Verification
+
+Core changes should be validated in two layers:
+
+- Run `make workflow-check`, `make distribution-check`, `make wheel-check`, and `make gem-check` for workflow publication policy, version/schema parity, selected release metadata, CLI/wheel boundaries, clean wheel installation, and built-gem content. Run `make distribution-release-check` after all final-commit candidates are verified and before creating the coordinated tag. `gem-check` uses local RubyGems or an already-local selected runtime image and never pulls implicitly.
+- Build the core repository to catch internal Jekyll errors.
+- Build or test `../unaltraweb-template` with `LOCAL_CORE=../unaltraweb` to catch consumer-path regressions.
+
+Template Playwright tests and screenshot generation are intentionally heavier than a Jekyll build. Run targeted profiles when machine resources are limited.

data/docs/_documentation/en/41-bibliometrics.md

@@ -0,0 +1,137 @@
+---
+title: Maintain The Metrics Pipeline
+description: Static bibliometric metrics workflow for unaltraweb sites.
+lang: en
+ref: bibliometrics
+profiles:
+- unaltredocs
+documentation_profiles:
+- contributors
+- core-developers
+section: Core Development
+weight: 630
+permalink: "/bibliometrics/"
+nav_title: Metrics Pipeline
+---
+This project uses a data-first bibliometrics workflow:
+
+- metrics are fetched and written into BibTeX fields (`x_*` + `note`) in a pre-build step,
+- aggregated totals are generated into `_data/metrics.yml`,
+- Jekyll render remains static (no API calls during `jekyll build`).
+
+## Files
+
+- `scripts/biblio/metrics_update.py`
+- `scripts/biblio/metrics_merge_meta.py`
+- `scripts/biblio/fetch_scimago_csv.sh`
+- `_data/metrics-overrides.yml`
+- `_data/metrics.yml` (generated summary; useful for metrics summary components)
+
+## Local data cache (not versioned)
+
+- `.cache/scimago/scimagojr.csv`
+
+Large Scimago datasets are intentionally excluded from git.
+
+## Scimago source
+
+`make metrics-scimago-fetch` downloads the public `sjrdata` R dataset and converts it to CSV:
+
+- source: `https://raw.githubusercontent.com/ikashnitsky/sjrdata/master/data/sjr_journals.rda`
+- output: full CSV (all available Scimago columns). Required minimum columns: `year,issn,sjr,sjr_best_quartile,categories`
+
+You can also pass local files:
+
+- `./scripts/biblio/fetch_scimago_csv.sh --input path/to/sjr_journals.rda`
+- `./scripts/biblio/fetch_scimago_csv.sh --input path/to/scimagojr.csv`
+
+## Commands
+
+From repository root:
+
+```bash
+make metrics-scimago-fetch
+make metrics-update
+make metrics-update-all
+make metrics-check
+```
+
+Local commands accept extra script arguments:
+
+```bash
+make metrics-update METRICS_ARGS="--strict-external --require-scimago"
+make metrics-check METRICS_ARGS="--require-scimago"
+make metrics-scimago-fetch SCIMAGO_INPUT=path/to/scimagojr.csv
+```
+
+Equivalent direct commands:
+
+```bash
+./scripts/biblio/fetch_scimago_csv.sh
+python3 scripts/biblio/metrics_update.py
+python3 scripts/biblio/metrics_update.py --offline --dry-run
+```
+
+## GitHub workflow
+
+Publication metrics are not part of automatic CI. Use the manual/reusable `.github/workflows/metrics-update.yml` workflow when you want GitHub to update or check metrics.
+
+The workflow keeps generated Scimago files and diagnostics out of pull requests. When PR creation is enabled, PRs include only versionable generated data: BibTeX changes under `_bibliography/` and the aggregate `_data/metrics.yml` summary.
+
+Child repositories can add a thin manual wrapper:
+
+```yaml
+name: Update publication metrics
+
+on:
+  workflow_dispatch:
+
+jobs:
+  metrics:
+    uses: dosquartsdedocs/unaltraweb/.github/workflows/metrics-update.yml@main
+    with:
+      fetch_scimago: true
+      create_pull_request: true
+```
+
+Useful workflow inputs:
+
+- `fetch_scimago`: downloads and validates the local Scimago CSV cache before updating metrics.
+- `offline`: skips OpenAlex and Crossref calls.
+- `dry_run`: avoids rewriting BibTeX entries while still writing diagnostics.
+- `strict_external`: fails the workflow if OpenAlex or Crossref requests fail.
+- `require_scimago`: fails when the Scimago CSV is unavailable.
+- `create_pull_request`: opens a PR with generated versionable changes.
+
+If `create_pull_request` is `false`, the workflow uploads `_data/metrics.yml` and diagnostics as artifacts but does not persist generated changes.
+
+## Failure modes
+
+- Missing Scimago cache: entries are marked with `scimago-missing` unless `--require-scimago` is set.
+- Broken Scimago URL or blocked network: `fetch_scimago` fails with a message suggesting a local `--input` file.
+- OpenAlex/Crossref outage: entries are marked with `api-error`, diagnostics include request errors, and `--strict-external` makes the command fail non-zero.
+
+## Overrides
+
+Use `_data/metrics-overrides.yml` to force IDs and values when automatic matching fails.
+Supported examples:
+
+- `openalex_id`
+- `crossref_cited_by`
+- `gs_id`, `gs_cited_by`
+- `x_scimago_*`
+
+## Diagnostics
+
+The update script produces:
+
+- `tmp/metrics-report.json`
+- `tmp/metrics-unmatched.tsv`
+
+Use these files to review unmatched DOI/ISSN items and stale Scimago matches.
+
+## Build/deploy note
+
+Because metrics are precomputed and saved in repo files, site build does not need runtime access to OpenAlex, Crossref, Scimago, or Google Scholar APIs.
+
+If deploying with GitHub Pages and `jekyll-scholar`, keep using a custom GitHub Actions build (not the restricted native Pages build).

data/docs/_documentation/en/42-docker-image.md

@@ -0,0 +1,185 @@
+---
+title: Use The Docker Image
+description: Runtime image used by local unaltraweb workflows.
+lang: en
+ref: docker_image
+profiles:
+- unaltredocs
+documentation_profiles:
+- local-authors
+- core-developers
+section: Work Locally
+weight: 140
+permalink: "/docker-image/"
+nav_title: Docker Image
+---
+The pending distribution contract selects this eventual shared image, which is published manually from the core repository and may not exist remotely yet:
+
+```text
+ghcr.io/dosquartsdedocs/unaltraweb:0.3.0
+```
+
+It provides the runtime environment: Ruby, Bundler, Jekyll system dependencies, ImageMagick, Node for ExecJS and Python tooling.
+
+The image is not the source of layouts and styles. Those come from the `unaltraweb` gem in the child site's `Gemfile`.
+
+The GHCR package is kept because it makes the local Docker workflow cheap and repeatable. Publishing is manual. Its unprivileged `preflight` job performs package and source checks without a registry login or Docker build. A default-branch run then crosses three separate credential boundaries:
+
+1. `build-candidates` has package-write, attestation-write, and OIDC signing authority but never executes a candidate. It checks that the runtime, MCP, and manual PDF `sha-<full-commit>` tags are absent, builds and pushes each image exactly once under only its SHA tag, and builds MCP from the runtime build's exact digest. Each build retains BuildKit SBOM and maximum provenance and is immediately followed by a GitHub-signed SLSA build-provenance attestation for the exact repository and digest, stored with the image in GHCR.
+2. `test-candidates` has only read permissions. It authenticates to GHCR with its read-scoped token, verifies each exact digest's registry-stored attestation against repository `dosquartsdedocs/unaltraweb`, signer workflow `dosquartsdedocs/unaltraweb/.github/workflows/docker-image.yml`, and the current source commit, then pulls and checks the OCI revision labels. It explicitly logs out and destroys its dedicated Docker credential directory before candidate execution. No `GH_TOKEN` is present while it runs every `test/**/*_test.rb` file from a read-only source mount, all manual PDF integration tests, reproducibility and MCP smoke with the MCP digest, and docs with the runtime digest. Only digests that pass every gate become job outputs.
+3. `promote-candidates` regains package-write authority but never executes a candidate. It rechecks the signed attestations, SHA tags, and revision labels, then points `sha-<full-commit>`, `main`, and `latest` at the tested digests with `docker buildx imagetools create` and verifies all resulting tag digests. A failed test run therefore cannot advance broad aliases, and no image is rebuilt after testing.
+
+GHCR does not provide this workflow with a compare-and-swap tag update. The absence check before the build and the equality checks before and after promotion reduce accidental clobbering, but a package administrator can still race those separate registry operations. The durable evidence is the signed, source-bound digest that the read-only job tested, not a claim that the SHA tag update is atomic.
+
+A receipt-only child commit records the immutable candidate digests outside the image contents. On the exact release tag, the package-write `promote-release` job executes no candidate and performs no rebuild. It requires each receipt-derived SHA tag to resolve to the recorded digest, verifies the GitHub-signed provenance with `--source-digest` set to `receipt.source_commit`, checks the revision label against that same commit, and only then creates and verifies version aliases. The hosted runner uses the following verification shape for each digest; an OCI verification requires read authentication to GHCR:
+
+```bash
+gh attestation verify oci://ghcr.io/dosquartsdedocs/unaltraweb@sha256:<digest> \
+  --bundle-from-oci \
+  --repo dosquartsdedocs/unaltraweb \
+  --signer-workflow dosquartsdedocs/unaltraweb/.github/workflows/docker-image.yml \
+  --source-digest <source-commit>
+```
+
+During local core development, use the locally built image:
+
+```bash
+docker build -t unaltraweb:dev .
+make docs-serve DOCKER_IMAGE=unaltraweb:dev
+```
+
+After the first GHCR publish, make the package public and confirm unauthenticated pulls work.
+
+## Computation Images
+
+Executable manual chapters use separate images from the Jekyll runtime and PDF builder:
+
+```text
+ghcr.io/dosquartsdedocs/unaltraweb-compute-python@sha256:18cb269811bd4005800382da25a480ec2bca7eac8d0501ad1ef36bad1c0f8cd9
+ghcr.io/dosquartsdedocs/unaltraweb-compute-r@sha256:928ffb93f221e09e8b929157dee473b838e061915a2eb67224e4124b85f81837
+```
+
+The Python image provides Quarto, Jupyter, NumPy, pandas, Matplotlib, GeoPandas, and geospatial libraries. The R image builds on `rocker/geospatial`, preserves RStudio Server, and adds Quarto, `knitr`, `rmarkdown`, `renv`, and the computation driver.
+
+Prepare the selected images with:
+
+```bash
+make manual-compute-image-python
+make manual-compute-image-r
+make manual-compute-images
+```
+
+An image already available locally is reused. Otherwise the target pulls a selected published image or builds a configured project extension. New `unaltremanual` sites select both release workers in `.unaltraweb/computations.yml`, and `manual_computation_render` performs this preparation automatically for each engine that has discovered sources.
+
+The factory owns the `manual-compute-*` Make targets and exposes them to child repositories through the MCP computation tools. Package-created sites keep a small build/serve Makefile instead of copying the computation implementation. Rendering and project image preparation run through the factory because they need the core scripts and Docker contracts.
+
+Do not use host `quarto render` for publishable manual computations. Missing Jupyter packages, read-only runtime directories such as `/run/user/...`, and local socket restrictions are host-environment failures; use `manual_computation_render` instead so the selected computation image supplies Quarto/Jupyter and records provenance.
+
+### Select An Image
+
+Image resolution uses this precedence:
+
+1. `COMPUTE_PYTHON_IMAGE` or `COMPUTE_R_IMAGE` from Make or the environment.
+2. `engines.<engine>.environments.<COMPUTE_ENV>` in `computations.yml`.
+3. A configured `local_image` with a project Dockerfile in the local environment.
+4. `engines.<engine>.image` in `computations.yml`.
+5. The corresponding core GHCR image.
+
+`COMPUTE_ENV` defaults to `ci` when `CI` is true and to `local` otherwise. Keep environment selection in `computations.yml`:
+
+```yaml
+engines:
+  python:
+    environments:
+      local: my-manual-compute-python:local
+      ci: ghcr.io/example/my-manual-compute-python@sha256:<digest>
+```
+
+Use `COMPUTE_PYTHON_IMAGE` or `COMPUTE_R_IMAGE` only as an explicit one-command override. Prefer digest-pinned CI images when the remote image identity must be independently reproducible.
+
+### Extend An Image
+
+Keep project-specific packages outside the core. Configure a Dockerfile and version its dependency lock:
+
+```yaml
+engines:
+  python:
+    dockerfile: Dockerfile.compute-python
+    context: .
+    base_image: ghcr.io/dosquartsdedocs/unaltraweb-compute-python@sha256:<digest>
+    local_image: example-compute-python:local
+    lockfiles:
+      - requirements-compute.txt
+```
+
+```dockerfile
+ARG BASE_IMAGE
+FROM ${BASE_IMAGE}
+
+COPY requirements-compute.txt /tmp/requirements-compute.txt
+RUN python3 -m pip install --no-cache-dir -r /tmp/requirements-compute.txt
+```
+
+The builder passes `BASE_IMAGE`, defaults the context to the project root, and builds a lowercase, Docker-safe `<project>-compute-<engine>:local` name when `local_image` is omitted. Pin the base image by digest when reproducible project-image builds matter. The Dockerfile and declared lockfiles participate in freshness checks. Extend the base image instead of copying the core renderer.
+
+### Figure-Only Sources
+
+Use `unaltraweb_compute.mode: figure` when a Quarto, R, Python, or notebook source owns reusable figures but not a generated manual chapter. Declare every versioned output explicitly:
+
+```yaml
+title: Palette reference
+lang: en
+ref: palette_reference
+unaltraweb_compute:
+  engine: python
+  mode: figure
+  outputs:
+    - assets/img/generated/en/palette-reference.svg
+```
+
+The renderer executes the source in the selected computation image, verifies the declared outputs exist, records their signatures in `.unaltraweb/computations.lock.json`, and marks them stale if source code, inputs, Dockerfiles, lockfiles, image identity, or output bytes change.
+
+If a local Docker installation cannot reach package repositories through its default bridge, select another build network explicitly rather than hard-coding it in the Dockerfile:
+
+```bash
+make manual-compute-image-r COMPUTE_DOCKER_BUILD_NETWORK=host
+```
+
+### Offline Execution
+
+Source execution uses `--network none`, a read-only container root, dropped Linux capabilities, `no-new-privileges`, process/CPU/memory limits, a temporary `/tmp`, a read-write project mount, and a staging directory under `tmp/manual-computations`. Pulling or building an image can require network access, but the actual render cannot fetch remote data. The project mount means trusted source code can still modify repository files; review the working tree after execution. Prepare images and version local inputs before an offline session.
+
+Ordinary web and PDF builds need only committed Markdown and figures. Their freshness check can run without Docker by using the image identity recorded at render time as a provenance trust anchor and validating artifact signatures. It does not resolve a mutable remote tag without network access. A locally available image takes precedence and detects a rebuilt mutable tag; use a digest-pinned image when remote identity must also be immutable.
+
+### RStudio Server
+
+Start the selected R image as a loopback-only authoring environment:
+
+```bash
+make manual-compute-rstudio
+make manual-compute-rstudio RSTUDIO_PORT=8788
+```
+
+The target prepares the image, mounts the project at `/home/rstudio/project`, maps the current user and group, and starts Rocker's `/init` with authentication disabled. Keep the `127.0.0.1` bind. RStudio is an authoring aid; publishable results must still come from `manual-compute-render` and pass `manual-compute-check`.
+
+### Publish To GHCR
+
+Core maintainers publish both base images with the manual `Compute images` workflow in `.github/workflows/compute-images.yml`. Its strict, no-credentials preflight and no-push build matrix must complete before its package-write matrix can start. Candidate Python and R images carry SBOM/provenance and default-branch `main` plus full-commit `sha-*` channels; release-tag runs promote a recorded immutable digest instead of rebuilding. Consumer defaults use the digest-pinned references selected by the BOM. Packages intended for child sites must allow unauthenticated pulls.
+
+Projects can call `.github/workflows/project-compute-image.yml` to publish their own extension package. Use a separate package name such as `example-compute-r`; do not encode project dependencies as variants of `unaltraweb-compute-r`.
+
+The current publication workflows build `linux/amd64` images. ARM authors need Docker emulation or a separately published compatible image; image IDs recorded in the computation lock are platform-specific.
+
+## Web Capture Image
+
+Selector-based screenshot authoring uses a separate Playwright image rather than adding Chromium to the Jekyll runtime:
+
+```text
+ghcr.io/dosquartsdedocs/unaltraweb-web-capture:0.3.0
+```
+
+The image contains pinned Playwright/Chromium, the capture worker, the Python status controller, and the core visual sources used in fingerprints. `make web-capture-image` builds the explicitly named `unaltraweb-web-capture:dev` maintainer image; set `WEB_CAPTURE_IMAGE` to that name when testing it. The manual `Web capture image` workflow publishes default-branch, commit, and semver/release tags to GHCR.
+
+Manual PDF commands similarly consume `ghcr.io/dosquartsdedocs/unaltraweb-manual-pdf:0.3.0` by default. `manual-pdf-image` reuses or pulls that selected image instead of rebuilding it locally. A pending release may therefore fail to pull until it is actually published. Maintainers use `make manual-pdf-image-dev` and then pass `MANUAL_PDF_IMAGE=unaltraweb-manual-pdf:dev` for local PDF runtime changes.
+
+Rendering creates an ephemeral Docker `--internal` network shared only by Jekyll and Chromium, keeps browser requests on the preview origin, blocks service workers, popups, and WebSockets, drops Linux capabilities, uses a read-only container root and bounded resources, and writes only the declared PNG/SVG outputs under the mounted project. Ordinary checks run without browser execution or network access.