@wenathlan/saddle 2.0.5 → 2.0.150

package/Dockerfile

@@ -10,7 +10,10 @@
 #      stages at the end of this file, folded from the former
 #      dockerfile.saddle) — an explicit build target
 #      (`docker build --target saddle-runtime .`), the node 26 storage and
-#      compute service published as ghcr.io/wenathlan/saddle:<version>.
+#      compute service published as ghcr.io/wenathlan/saddle:<version>
+#      across the four-arch family standard (amd64, arm64, ppc64le, s390x
+#      — the trixie slim base line; the stage also builds the web SPA so
+#      the image serves the self-hosted console via `node /app/web/server.ts`).
 #
 # saddle v2 (grand merge) - virtual hardware engine, multi-stage, multi-arch image.
 #
@@ -91,7 +94,7 @@
 #     -v vmdata:/data/vmdata -v webdata:/data/web \
 #     -v ./vm.config.json:/engine/vm.config.json:ro \
 #     -e PORT=8080 -e NODE_ENV=production -p 31280:8080 \
-#     ghcr.io/wenathlan/saddle:vhe-2.0.5
+#     ghcr.io/wenathlan/saddle:vhe-2.1.6
 #
 #   vheqemu (the guest runner; build it first with
 #   docker build --target qemu-runtime -t saddle/qemu:11.1.0 . because the
@@ -125,7 +128,7 @@
 #     -e VHE_GPU_PROFILE=b200 -e VHE_GPUS=8 -e VHE_MIG=1 \
 #     -e VHE_SMI_DRIVER=575.57.08 -e VHE_SMI_CUDA=12.9 \
 #     -e VHE_SMI_INTERVAL=30 -e VHE_SKIP_XVFB=1 -e VHE_SKIP_VALIDATE=1 \
-#     ghcr.io/wenathlan/saddle:vhe-2.0.5 /bin/bash -c '
+#     ghcr.io/wenathlan/saddle:vhe-2.1.6 /bin/bash -c '
 #       while true; do
 #         /usr/local/bin/nvidia-smi "$VHE_GPU_PROFILE" "$VHE_GPUS" || true
 #         sleep "$VHE_SMI_INTERVAL"
@@ -142,7 +145,7 @@
 #     -v qemudata:/data/qemudata \
 #     -v ./qemubridge.py:/engine/qemubridge.py:ro \
 #     -e QMP_SOCKET=/run/vhe/vm.qmp -e PYTHONUNBUFFERED=1 \
-#     ghcr.io/wenathlan/saddle:vhe-2.0.5 \
+#     ghcr.io/wenathlan/saddle:vhe-2.1.6 \
 #     python3 /engine/qemubridge.py --socket /run/vhe/vm.qmp status
 #
 #   saddle-node (the node-engine service, the former compose.yml
@@ -156,7 +159,7 @@
 #     --log-driver json-file --log-opt max-size=50m --log-opt max-file=5 \
 #     --tmpfs /tmp:size=2g,mode=1777 \
 #     -e SADDLE_MEMORY_ENGINE=ram -e SBOT_PLATFORM= -e SBOT_CDN_URL= \
-#     ghcr.io/wenathlan/saddle:2.0.5 \
+#     ghcr.io/wenathlan/saddle:2.1.6 \
 #     node dist/cli.js plan
 #
 #   observability (the former prometheus scraper of the full profile)
@@ -636,6 +639,32 @@ ENTRYPOINT ["/usr/bin/tini", "--", "qemu-system-x86_64"]
 # ---------------------------------------------------------------------------
 # stage 5: runtime (final, default target, the vhe/vhegpu docker run recipes)
 # ---------------------------------------------------------------------------
+# saddle-build: the node-engine build stage (defined here, before the
+# vhe runtime, so BOTH container surfaces can consume its output: the
+# vhe runtime copies the built web SPA for its /engine/web console and
+# the saddle-runtime stage copies the engine dist plus the same web
+# tree - one build, two consumers). The stage runs native (never under
+# QEMU): its outputs are platform-independent static/js payloads.
+
+# the build stage pins to the native build platform ($BUILDPLATFORM): its
+# outputs (the engine dist, pure js, and the web SPA, static assets) are
+# architecture-independent, while the tailwind/lightningcss pipeline only
+# ships native bindings for the builder platforms - the per-arch legs never
+# run it under QEMU.
+FROM --platform=$BUILDPLATFORM node:26.8.1-slim@sha256:c0753125a3789977aefe869cbebccf70e3cfd7ea84ca48547458f02e4f1d7146 AS saddle-build
+
+ARG SADDLE_VERSION
+WORKDIR /app
+
+ENV NPM_CONFIG_LEGACY_PEER_DEPS=true
+
+COPY package.json package-lock.json ./
+RUN npm ci --ignore-scripts --legacy-peer-deps
+COPY . .
+RUN npm run build:engine \
+    && node --check dist/cli.js \
+    && npm run web:build:pages
+
 FROM ${UBUNTU} AS runtime
 ARG TARGETARCH
 ARG NODE_VERSION
@@ -873,8 +902,12 @@ COPY qemu.config mttg.config passage.config docker.config /engine/
 # the web node ships inside the main container: the mesh edition (auth,
 # sqlite database, dashboard and the browser sandbox pages) runs from the
 # same image, so one container serves the engine AND the web surface.
-# run it with: docker run ghcr.io/wenathlan/saddle node /engine/web/server.js
+# run it with: docker run ghcr.io/wenathlan/saddle node /engine/web/server.ts
 COPY web /engine/web
+# the built web SPA (vite, from the saddle-build stage): the console
+# server (node /engine/web/server.ts) serves web/dist/public - the
+# unified React interface that absorbed the former static pages.
+COPY --from=saddle-build /app/web/dist /engine/web/dist
 
 RUN set -eux; \
     chmod 0755 /usr/local/bin/nvidia-smi /usr/local/bin/aetherforge; \
@@ -1238,7 +1271,7 @@ HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --start-interval=5s
 # OCI labels for registry introspection.
 LABEL org.opencontainers.image.title="saddle virtual-hardware engine (the grand merge)" \
       org.opencontainers.image.description="100% software virtual hardware: per-profile CPU/memory spoofing via LD_PRELOAD (max/balanced/lite), mesa 26.2.1 llvmpipe/lavapipe/rusticl, QEMU 11.1.0 TCG/MTTCG, virtual nvidia-smi adapter + NVML/CUDA shims, node 26.7.0, python bridge" \
-      org.opencontainers.image.version="2.0.5" \
+      org.opencontainers.image.version="2.1.6" \
       org.opencontainers.image.licenses="MIT" \
       org.opencontainers.image.source="https://github.com/wenathlan/saddle" \
       org.opencontainers.image.documentation="https://github.com/wenathlan/saddle/blob/main/README.md" \
@@ -1277,20 +1310,7 @@ ENTRYPOINT ["/entrypoint.sh"]
 #   docker build --target saddle-runtime -t saddle:<version> .
 # ══════════════════════════════════════════════════════════════════════
 
-FROM node:26.8.1-bookworm-slim AS saddle-build
-
-ARG SADDLE_VERSION
-WORKDIR /app
-
-ENV NPM_CONFIG_LEGACY_PEER_DEPS=true
-
-COPY package.json package-lock.json ./
-RUN npm ci --ignore-scripts --legacy-peer-deps
-COPY . .
-RUN npm run build:engine \
-    && node --check dist/cli.js
-
-FROM node:26.8.1-bookworm-slim AS saddle-runtime
+FROM node:26.8.1-slim@sha256:c0753125a3789977aefe869cbebccf70e3cfd7ea84ca48547458f02e4f1d7146 AS saddle-runtime
 
 ARG SADDLE_VERSION
 LABEL org.opencontainers.image.title="Saddle" \
@@ -1337,6 +1357,12 @@ RUN apt-get update \
     && rm -rf node_modules/cpu-features/deps \
     && find node_modules -type f -name Dockerfile -delete
 COPY --from=saddle-build /app/dist ./dist
+# the web service surface (self-hosted console): the built SPA
+# (web/dist/public from the saddle-build vite run) plus the pure-node
+# server stack (server.ts, db.ts, auth.ts, mesh.ts, sandbox.ts,
+# mime.types, init.sql, schema.prisma) - zero npm dependencies, the
+# node 26 runtime carries everything (node:sqlite, node:crypto).
+COPY --from=saddle-build /app/web ./web
 
 USER node
 

package/README.md

@@ -30,7 +30,9 @@ domain modules land beside the saddle domains:
 | `scheduler.ts`, `compute.ts`, `performance.ts` | job queues, batch compute and benchmark planning |
 | `media.ts`, `render.ts`, `quantum.ts`, `tiers.ts` | media pipeline, GPU registry, quantum simulation, tier policy |
 | `security.ts`, `alternatives.ts` | hardening gates and the alternative-stack catalog |
-| `web/` | the static console and the zero-dependency self-hosted API (`node web/server.js`) |
+| `index.html`, `App.tsx`, `Sol/` | the single SPA shell and the Sol theme (one tsx app with one stylesheet per theme) |
+| `server.ts`, `sandbox.ts` | the zero-dependency self-hosted API of the 2.0.150 grand-merge envelope (`node server.ts`; the api answers its version at `/api/v1/health`) and the browser-pure engine port |
+| `vercel.json`, `netlify.toml` | the platform deploy adapters beside the surface they publish (the caddy ghost stays out of the tree) |
 | `specs/*` package exports | processors, gpus, cores, boards and the qemu/mttg/passage/docker envelopes |
 
 The full pre-merge documentation of the engine lives in
@@ -57,7 +59,7 @@ console.log(context.summary);
 The deterministic examples and tests do not require network access or real credentials:
 
 ```bash
-node --import tsx examples/publicapi.ts
+node --import tsx docs/example-publicapi.ts
 npm test
 ```
 
@@ -232,7 +234,7 @@ npm run web:check
 VITE_BASE_PATH=/saddle npm run web:build:pages
 ```
 
-Small public configuration and visual assets live under `web/public/`. The development collector is TypeScript source at `web/lib/debugcollector.ts`, injected only in development, and uses `/debuglogs`; it is not part of the production build. The obsolete `web/public/__manus__` directory is intentionally absent.
+Small public configuration and visual assets live under `web/public/`. The development collector is TypeScript source at `web/debugcollector.ts`, injected only in development, and uses `/debuglogs`; it is not part of the production build. The obsolete `web/public/__manus__` directory is intentionally absent.
 
 ## Development
 
@@ -300,3 +302,17 @@ Version 1.8.19 organizes the existing engine into twenty documented, dependency-
 ## License
 
 Saddle is distributed under the [GNU General Public License v3.0 only](LICENSE).
+
+---
+
+# The Sol theme
+
+# Saddle Sol
+
+Saddle is the 20-modality sandbox platform of the DevThink family: one engine spanning compute, virtualization, media, mesh, automation and the other modalities, exposed as a self-hosted site. This Sol theme is the platform's web surface — a Vite + React SPA (console, dashboard, playground, integrations) served from the same sqlite database that `schema.prisma`, `init.sql` and `drizzle.config.ts` describe.
+
+```bash
+pnpm install
+pnpm dev
+```
+

package/boards.json

@@ -7,7 +7,7 @@
     "date": "2026-08-22",
     "dateFirstDoctrine": "The observer validates all specifications against the latest stable releases available on 2026-08-22.",
     "toolchain": {
-      "node": "26.7.0 Current",
+      "node": "26.12.0 Current",
       "nodeAlt": "24.19.0 LTS",
       "typescript": "7.0.2",
       "python": "3.14.7",
@@ -88,7 +88,7 @@
       }
     },
     "name": "boards.json",
-    "version": "2.0.0",
+    "version": "2.0.127",
     "title": "saddle - Virtual Motherboard Database (retail boards + platform reference sockets)",
     "sources": [
       "pool:boards.json [S6, 20 retail boards]",

package/compute.ts

@@ -2554,7 +2554,7 @@ export function buildvmcrdmanifest(opts?: {
       'metadata:',
       `  name: ${plural}.${group}`,
       'spec:',
-      '  group: ' + group,
+      `  group: ${group}`,
       '  scope: Namespaced',
       '  names:',
       `    plural: ${plural}`,
@@ -2562,7 +2562,7 @@ export function buildvmcrdmanifest(opts?: {
       `    kind: ${kind}`,
       '    shortNames: [vm, evm]',
       '  versions:',
-      '    - name: ' + version,
+      `    - name: ${version}`,
       '      served: true',
       '      storage: true',
       '      subresources:',
@@ -2618,8 +2618,8 @@ export function buildvmcrdmanifest(opts?: {
       '',
     ].join('\n');
     const sample = [
-      'apiVersion: ' + group + '/' + version,
-      'kind: ' + kind,
+      `apiVersion: ${group}/${version}`,
+      `kind: ${kind}`,
       'metadata:',
       '  name: demo-vm',
       '  namespace: saddle',

package/cores.json

@@ -1,7 +1,7 @@
 {
   "metadata": {
     "id": "cores.json",
-    "version": "2.0.0",
+    "version": "2.0.127",
     "date": "2026-08-22",
     "datestamp": "2026-08-22T00:00:00Z",
     "observer": "third person observer notes the hybrid core inventory reflects production silicon as of 2026-08-22",
@@ -36,7 +36,7 @@
       ]
     },
     "stack": {
-      "node": "26.7.0 Current",
+      "node": "26.12.0 Current",
       "nodeAlt": "24.19.0 LTS",
       "typescript": "7.0.2",
       "python": "3.14.7",

package/docker.config

@@ -2,7 +2,7 @@
   "meta": {
     "name": "docker.config",
     "title": "saddle - Docker Engine and Containerization Configuration",
-    "version": "2.0.0",
+    "version": "2.1.6",
     "date": "2026-08-22",
     "language": "en",
     "sources": [
@@ -618,7 +618,7 @@
   "labels": {
     "org.opencontainers.image.title": "saddle-v6",
     "org.opencontainers.image.description": "Saddle v6 virtualization orchestrator with QEMU 11.1.0, Node 22 LTS, Python 3.13.5, MTTG, Passage, OVMF",
-    "org.opencontainers.image.version": "2.0.0",
+    "org.opencontainers.image.version": "2.1.6",
     "org.opencontainers.image.created": "2026-08-22T00:00:00Z",
     "org.opencontainers.image.authors": "Saddle Core <core@saddle.dev>",
     "org.opencontainers.image.url": "https://saddle.dev",
@@ -630,7 +630,7 @@
     "org.opencontainers.image.base.name": "debian:bookworm-slim",
     "org.opencontainers.image.base.digest": "sha256:bookworm-slim-pinned-2026-08-22",
     "saddle": {
-      "com.saddle.version": "2.0.0",
+      "com.saddle.version": "2.1.6",
       "com.saddle.engine": "qemu-11.1.0",
       "com.saddle.modes": "32",
       "com.saddle.forge.mirrors": "github,gitea,forgejo",

package/docs/architecture.md

@@ -104,7 +104,7 @@ Line counts are the shipped files (v2 carryover plus the v3/v5/v6 additions); ev
 | `libs/gpumonitor.cpp` | 1543 | C++26 four-mode build: CLI smi-adapter, NVML/libcuda shim, N-API addon, forge mode (Plan/validate/qemu_argv, Mttg work-stealing mirror) | 12 hooks |
 | `libs/virtualhardware.c` | 1011 | C11 LD_PRELOAD core: open-family interception, vhe_translate, inotify regeneration thread, xorshift32 drift, constructor 101 | 12 hooks |
 
-Data files: `gpus.json` 2408, `processors.json` 2217, `vm.config.json` 1910, `cores.json` 1801, `mttg.config` 1548, `boards.json` 1517, `passage.config` 1330, `qemu.config` 1061, `virtualhardware.json` 739, `docker.config` 768. Web node (`web/`, the v6 edition plus the v7 wave): `sandbox.js` 1433 is the browser-pure engine port (bank, procfs payloads, the 89-char smi table, mesa summaries, boot dmesg and the command dispatcher), `server.js` 640 serves the console plus the `/api/v1` contract (health, spec catalogs, sandbox lifecycle, exec) over `node:http`, `index.html` 646 renders the spec panel, terminal and bus timeline, adapters `vercel.json`/`netlify.toml`/`caddyfile` (static edge, api reverse proxied) and `readme.md` 120; the v7 wave completes the node with `db.js` (sqlite persistence for users, sessions and sandboxes), `auth.js` (scrypt password hashing, timing-safe verification, cookie sessions), `mesh.js` (HMAC-SHA256 signed clone-to-main calls with replay windows), the `login.html`/`register.html`/`dashboard.html` pages, `package.json`/`Dockerfile` (image `ghcr.io/wenathlan/e2ugh (main image, web/ included)`; node pinned by the root `.nvmrc`), the database definition kept flat as `schema.prisma` plus `init.sql`, and `mime.types`. Total repository: about 62,200 lines across 83 tracked files (the v2 carryover plus the v3 domains, the v5 media/test waves and the v6 web edition; the `tests/` suite alone is 3,674 lines across eleven files).
+Data files: `gpus.json` 2408, `processors.json` 2217, `vm.config.json` 1910, `cores.json` 1801, `mttg.config` 1548, `boards.json` 1517, `passage.config` 1330, `qemu.config` 1061, `virtualhardware.json` 739, `docker.config` 768. Web node (`web/`, the v6 edition plus the v7 wave): `sandbox.ts` 1433 is the browser-pure engine port (bank, procfs payloads, the 89-char smi table, mesa summaries, boot dmesg and the command dispatcher), `server.ts` 640 serves the console plus the `/api/v1` contract (health, spec catalogs, sandbox lifecycle, exec) over `node:http`, `index.html` 646 renders the spec panel, terminal and bus timeline, adapters `vercel.json`/`netlify.toml`/`caddyfile` (static edge, api reverse proxied) and `readme.md` 120; the v7 wave completes the node with `db.ts` (sqlite persistence for users, sessions and sandboxes), `auth.ts` (scrypt password hashing, timing-safe verification, cookie sessions), `mesh.ts` (HMAC-SHA256 signed clone-to-main calls with replay windows), the `login.html`/`register.html`/`dashboard.html` pages, `package.json`/`Dockerfile` (image `ghcr.io/wenathlan/e2ugh (main image, web/ included)`; node pinned by the root `.nvmrc`), the database definition kept flat as `schema.prisma` plus `init.sql`, and `mime.types`. Total repository: about 62,200 lines across 83 tracked files (the v2 carryover plus the v3 domains, the v5 media/test waves and the v6 web edition; the `tests/` suite alone is 3,674 lines across eleven files).
 
 ## 3a. v3 redistribution: features live in domains
 
@@ -129,7 +129,7 @@ Tests live in the `tests/` directory (one of the five allowed directories) and r
 
 ## 3c. Web node architecture (v7)
 
-The web node is a static edge plus one self-hosted process. Clones (Vercel and Netlify static deploys of the `web/` pages, redeployed from the `pages.yml` zip -9 bundle) ship only immutable assets: the console, the auth pages and `sandbox.js`, which runs the whole engine client-side and keeps working with no backend. The main node (`node web/server.js` behind the `caddyfile` on devthink.pro, packaged as `ghcr.io/wenathlan/e2ugh (main image, web/ included)`) owns everything stateful: `db.js` opens the sqlite file (`schema.prisma`/`init.sql` define it, kept flat per the two-level contract), `auth.js` is the auth authority - scrypt password hashing with per-user salts, timing-safe verification and server-side sessions delivered as `HttpOnly` cookies - and `mesh.js` verifies the HMAC-SHA256 signature (method, path, body digest, timestamp, bounded replay window) that every clone attaches to forwarded calls before routing. The design is deliberately anti-serverless: no function runs on the edge platforms, clones hold no secrets and no database, and unauthenticated clones receive 401 from the main node instead of any partial authority.
+The web node is a static edge plus one self-hosted process. Clones (Vercel and Netlify static deploys of the `web/` pages, redeployed from the `pages.yml` zip -9 bundle) ship only immutable assets: the console, the auth pages and `sandbox.ts`, which runs the whole engine client-side and keeps working with no backend. The main node (`node web/server.ts` behind the `caddyfile` on devthink.pro, packaged as `ghcr.io/wenathlan/e2ugh (main image, web/ included)`) owns everything stateful: `db.ts` opens the sqlite file (`schema.prisma`/`init.sql` define it, kept flat per the two-level contract), `auth.ts` is the auth authority - scrypt password hashing with per-user salts, timing-safe verification and server-side sessions delivered as `HttpOnly` cookies - and `mesh.ts` verifies the HMAC-SHA256 signature (method, path, body digest, timestamp, bounded replay window) that every clone attaches to forwarded calls before routing. The design is deliberately anti-serverless: no function runs on the edge platforms, clones hold no secrets and no database, and unauthenticated clones receive 401 from the main node instead of any partial authority.
 
 ## 4. One bus, one state machine, one metrics store
 
@@ -209,7 +209,7 @@ Per-target delivery notes (one line each, from the collapsed topic docs):
 | Target | How the same library is consumed |
 | --- | --- |
 | desktop | EgUi lab UI over the in-process factory; every control honors the 44 px touch target |
-| web | browser bundle shipped as the `web/` console (v6): `sandbox.js` mirrors the verified bank, `server.js` serves it and `/api/spec`; zero dependencies keep the graph tree-shakeable |
+| web | browser bundle shipped as the `web/` console (v6): `sandbox.ts` mirrors the verified bank, `server.ts` serves it and `/api/spec`; zero dependencies keep the graph tree-shakeable |
 | extension | browser extension service worker; endpoints bind a random port, never localhost |
 | cli | planner CLI: `node --experimental-strip-types index.ts` reading `vm.config.toml` |
 | android | container/wasm module surface through the JVM bridge; arm64 native runner images |

package/docs/containerplatforms-2.1.0.md

@@ -0,0 +1,73 @@
+# Container platform decision for 2.1.0
+
+## Scope
+
+Version 2.1.0 expands the Saddle node-engine OCI image (the `saddle-runtime`
+target of the one container file, published by the `publish ghcr` workflow)
+from a three-platform Linux manifest index to the four-architecture family
+surface: `linux/amd64`, `linux/arm64`, `linux/ppc64le`, and `linux/s390x`.
+The selection unifies the container surfaces of the grand merge: the saddle
+lineage shipped amd64/arm64/ppc64le (the 1.8.17 decision, see
+[containerplatforms-1.8.17.md](containerplatforms-1.8.17.md)) and the e2ugh
+lineage published all four architectures for the virtual-hardware engine
+(`publish ghcr vhe`). One product, one registry, one architecture surface:
+the s390x leg joins the node engine from the e2ugh side of the family.
+
+## Platform matrix
+
+`linux/amd64` stays because it is the primary GitHub runner architecture and
+the local smoke-test platform. `linux/arm64`, `linux/ppc64le` and
+`linux/s390x` stay (or join) because the vhe engine of the same repository
+already builds, publishes and verifies those architectures under QEMU
+emulation - the publish ghcr vhe lane proves the build path - and the
+node-engine build is a strict subset of that work (npm tooling, no mesa,
+no qemu compilation).[1] [2]
+
+`linux/arm/v7` and `linux/386` remain deferred because no inspected Node 26
+base manifest exposes them. `windows/amd64` remains deferred (see the 1.8.17
+decision): the Dockerfile uses Debian Linux stages and a Windows container
+needs a Windows-specific base image, runner and smoke tests. `unknown/*`
+remains rejected: OCI `unknown` descriptors are not a runnable target and
+must not be advertised as a Saddle container platform.
+
+## Base image prerequisite (the s390x gap of the bookworm-slim variant)
+
+The current node-engine stages build `FROM node:26.8.1-bookworm-slim`. The
+manifest index of that tag (inspected through the Docker Hub registry API on
+2026-09-06, the same view `docker manifest inspect` reads) exposes exactly
+`linux/amd64`, `linux/arm64` and `linux/ppc64le` - the bookworm-slim variant
+does not publish an s390x entry. The Node 26 tags that DO carry s390x are
+the default-distro (Debian trixie) variants: `node:26.8.1` and
+`node:26.8.1-slim`. The four-arch publication therefore requires the
+`saddle-build` and `saddle-runtime` FROM lines of the one container file to
+move to a trixie-based variant (for example `node:26.8.1-slim`, keeping the
+slim profile) before the first 2.1.0 publish run; until that base swap
+lands, the buildx s390x leg cannot resolve its base manifest and the publish
+job fails at the platform-resolution step. That Dockerfile change belongs to
+the same 2.1.0 wave as this decision document (it is recorded here because
+the container file is not part of this workflow-restoration change set).
+
+## Workflow design
+
+The `publish ghcr` workflow registers QEMU (arm64, ppc64le, s390x emulation)
+before Buildx, scans a loadable `linux/amd64` image (GitHub-hosted runners
+cannot load a multi-platform image into the default local image store, so
+the scan build stays single-platform while the publication is pushed
+directly to GHCR), pushes all four Linux variants through one Buildx
+invocation, and verifies the registry manifest index for the four
+architectures before the amd64 label and CLI smoke test.[2] The publish lane
+also carries the restored idempotency gates: the resolve job (tag ==
+package.json == published release, plus the e2ugh "already shipped"
+tag/HEAD guard) so a duplicate release firing no-ops instead of repushing.
+
+## Publication claims
+
+The version 2.1.0 release notes and registry documentation may claim only
+the four verified Linux variants after the pushed image index is inspected.
+They must not claim Windows support, an `unknown` platform, or a universal
+OS image.
+
+## References
+
+[1]: https://docs.docker.com/build/building/multi-platform/ "Docker multi-platform builds"
+[2]: https://docs.docker.com/build/ci/github-actions/multi-platform/ "Multi-platform image with GitHub Actions"

package/docs/logs/examplesession.json

@@ -0,0 +1,54 @@
+{
+  "version": 1,
+  "session": {
+    "id": "examplesession-0001",
+    "browser": "brave",
+    "seed": "examplesession-seed-0001"
+  },
+  "events": [
+    {
+      "t": 140,
+      "type": "move",
+      "x": 120,
+      "y": 90
+    },
+    {
+      "t": 300,
+      "type": "move",
+      "x": 180,
+      "y": 140
+    },
+    {
+      "t": 480,
+      "type": "click",
+      "x": 180,
+      "y": 140
+    },
+    {
+      "t": 680,
+      "type": "type",
+      "key": "k"
+    },
+    {
+      "t": 900,
+      "type": "move",
+      "x": 240,
+      "y": 200
+    },
+    {
+      "t": 1140,
+      "type": "click",
+      "x": 240,
+      "y": 200
+    },
+    {
+      "t": 1400,
+      "type": "scroll",
+      "dy": 320
+    }
+  ],
+  "captcha": {
+    "kind": "hcaptcha",
+    "passed": true
+  }
+}

package/docs/native-wrappers.md

@@ -0,0 +1,38 @@
+# Saddle native wrappers (generated doctrine)
+
+The native wrappers — Android, iOS and desktop — are **generated on the CI runners and never committed**. The repository carries only the conversion configs and the icon source; the Gradle/Xcode/Rust envelopes are 100% regenerable toolchain output (audited in the 2.1.0 wave: `web/android` and `web/ios` were stock Capacitor templates, and the former `web/desktop` Rust files were 12 lines of Tauri boilerplate).
+
+## Doctrine
+
+- **Generated on the runners, never committed**: the mobile workflows run `npx cap add android` / `npx cap add ios` into `build/native/` (gitignored); the desktop workflow scaffolds the Tauri Rust envelope (Cargo.toml, main.rs, lib.rs, build.rs) via heredoc into `build/native/desktop`. The historical templates remain recoverable from git history.
+- **Single icon source**: `web/icon.svg` is the one source of every native icon family. Runners derive the Android mipmaps/splashs, the iOS AppIcon set and the Tauri bundle icons from it (`npx cap assets` equivalents and `npx --yes @tauri-apps/cli@2.11.4 icon web/icon.svg --output build/native/desktop/icons`).
+- **Versions injected via `SADDLE_VERSION` env**: the workflows patch the generated `tauri.conf.json` copy, the Cargo manifest, the Gradle config and the iOS project with the resolved release version at build time — no committed file carries a stale native version.
+- **One conversion config pair**: `web/capacitor.config.ts` (the web root, where the Capacitor CLI resolves it: `webDir` = `dist/public`, `android.path`/`ios.path` = `../build/native/{android,ios}` at the repository root) and `tauri.conf.json` (the repository root, `frontendDist` = `web/dist/public`, `bundle.icon` relative to the scaffold directory where the runner copies this config).
+
+## Android surface (from the retired `web/android/README.md`)
+
+The Android surface is a Capacitor conversion target for the shared Saddle web application. The TypeScript library remains the source of engine logic, while the compiled `web/dist/public` directory supplies the WebView payload. The generated project owns application metadata, Gradle configuration, resources and signing hooks only. The workflow runs `npm run web:build:pages`, `npx cap sync android`, regenerates the Saddle icon family from `web/icon.svg` and executes Gradle release tasks. Release builds enable R8 code shrinking and resource shrinking. A production keystore is never committed; `ANDROID_KEY_BASE64`, `ANDROID_KEY_ALIAS`, `ANDROID_STORE_PASSWORD` and `ANDROID_KEY_PASSWORD` are repository secret contracts. A manual test run may opt into a clearly labeled CI test key, but that output is not a trusted store artifact. The public artifact contract is version-derived and uses dotted lowercase names such as `saddle.apk.<version>.apk` and `saddle.aab.<version>.aab`; the release manifest records the signing status and the workflow verifies the APK and AAB signatures before upload.
+
+## iOS surface (from the retired `web/ios/README.md`)
+
+The iOS surface is a Capacitor conversion target for the shared Saddle web application. The TypeScript library and the compiled `web/dist/public` directory remain authoritative; the generated Xcode project owns only platform metadata, WebView hosting, entitlements and caller-provided signing configuration. The workflow runs on macOS, synchronizes the web output with `npx cap sync ios` and builds an IPA only when Apple certificates, provisioning profiles and export settings are explicitly configured. No signing material is stored in the repository, and an unsigned or unprovisioned build is never described as App Store ready. The public artifact contract is version-derived and uses the dotted lowercase pattern `saddle.ipa.<version>.ipa`.
+
+## Desktop surface (from the retired `web/desktop/README.md`)
+
+The desktop surface is the Saddle browser application: one Tauri application wrapping the `web/` build. Windows, Linux and macOS use the same web assets, compiled library contracts, window policy and release version; platform differences are limited to native WebView integration, installer format and caller-owned signing. The Rust entrypoint, Cargo manifest and Tauri configuration are scaffolded by the runner (heredoc) — the frontend is `web/dist/public`, generated by `npm run web:build:pages`; the shell never copies or reimplements React routes, storage logic or engine logic. Local regeneration commands:
+
+```bash
+npm ci
+mkdir -p build/native/desktop && cd build/native/desktop
+# heredoc Cargo.toml / main.rs / lib.rs / build.rs here (as the workflow does)
+npx --yes @tauri-apps/cli@2.11.4 icon ../../web/icon.svg --output icons
+cp ../../../tauri.conf.json .
+npx --yes @tauri-apps/cli@2.11.4 dev
+npx --yes @tauri-apps/cli@2.11.4 build --ci --no-sign --bundles deb,rpm,appimage
+```
+
+The release workflow runs the native command on the matching GitHub-hosted runner, attaches only files that were actually generated and renames them to `saddle.browser.<version>.<format>`. Signing, notarization, Microsoft Store submission, Snap publication, Flatpak publication and Apple App Store submission require caller-owned credentials and are not embedded in this repository.
+
+## Weight removed in the 2.1.0 flatten (shadcn kit pruning, rule 98)
+
+The static template kit `web/components/ui/` carried 50 files; only the four referenced by the live React tree survived as loose files at the web root (`button.tsx`, `card.tsx`, `tooltip.tsx`, `sonner.tsx`). The 46 unreferenced template components were deleted as dead weight (OAuth-portal template, never imported by any live page): accordion, alert, alert-dialog, aspect-ratio, avatar, badge, breadcrumb, button-group, calendar, carousel, chart, checkbox, collapsible, command, context-menu, dialog, drawer, dropdown-menu, empty, field, form, hover-card, input, input-group, input-otp, item, kbd, label, menubar, navigation-menu, pagination, popover, progress, radio-group, resizable, scroll-area, select, separator, sheet, sidebar, skeleton, slider, spinner, switch, table, tabs, textarea, toggle, toggle-group. `web/components.json` (zero readers among tests and source) and the whole `web/hooks/` folder (useMobile/useComposition/usePersistFn — imported only by the pruned kit and the dead `Map.tsx`) were deleted with it.