chore: docs, CI, tooling, and dotli integration for the Rust core

.changeset/rename-provider-to-wireprovider.md

@@ -1,5 +1,5 @@
 ---
-"@parity/truapi": patch
+"@parity/truapi": minor
 ---
 
 Rename the exported `Provider` transport type to `WireProvider` to make its role explicit. It is the low-level SCALE-wire-frame pipe (a `MessagePort` or iframe `postMessage` channel) that `createTransport` runs on. The `createIframeProvider` / `createMessagePortProvider` factories are unchanged; only the type name moves. Consumers importing `Provider` should import `WireProvider` instead.

.changeset/truapi-sandbox-bootstrap.md

@@ -1,5 +1,5 @@
 ---
-"@parity/truapi": patch
+"@parity/truapi": minor
 ---
 
 Add the `@parity/truapi/sandbox` entry point: host-environment detection (`isCorrectEnvironment`), a lazily-built cached client (`getClientSync`, `null` outside a host container), and a `subscribeConnectionStatus` connected/disconnected listener. Browser-embedded hosts can bootstrap a client without assembling the transport by hand.

.gitattributes

@@ -0,0 +1,2 @@
+rust/crates/truapi-codegen/tests/golden/* linguist-generated=true
+rust/crates/truapi-server/src/generated/* linguist-generated=true

.github/workflows/check-rfc.yml

@@ -14,7 +14,7 @@ jobs:
     if: github.event.pull_request.user.login != 'github-actions[bot]'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false

.github/workflows/ci.yml

@@ -3,7 +3,7 @@ name: CI
 on:
   pull_request:
   push:
-    branches: [main, release/v0.3.2]
+    branches: [main, release/v0.3.0]
   merge_group:
   workflow_dispatch:
 
@@ -21,7 +21,7 @@ jobs:
     env:
       RUSTFLAGS: "-D warnings"
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -52,7 +52,7 @@ jobs:
     name: Dependency licenses
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -65,7 +65,7 @@ jobs:
     name: Codegen
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -100,6 +100,7 @@ jobs:
             js/packages/truapi/src/playground/codegen
             js/packages/truapi/src/explorer/codegen
             js/packages/truapi/src/explorer/versions.ts
+            js/packages/truapi-host-wasm/src/generated
             playground/test/generated
 
   ts-client:
@@ -109,7 +110,7 @@ jobs:
     env:
       TRUAPI_REQUIRE_GENERATED: 1
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -142,7 +143,7 @@ jobs:
     env:
       TRUAPI_REQUIRE_GENERATED: 1
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -187,7 +188,7 @@ jobs:
     env:
       TRUAPI_REQUIRE_GENERATED: 1
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 
@@ -227,7 +228,7 @@ jobs:
     env:
       TRUAPI_REQUIRE_GENERATED: 1
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           submodules: recursive
           persist-credentials: false

.github/workflows/deploy-docs.yml

@@ -20,7 +20,7 @@ jobs:
       pages: write
       id-token: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 

.github/workflows/deploy-playground.yml

@@ -27,7 +27,7 @@ jobs:
   deploy-playground:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 

.github/workflows/diagnosis-report.yml

@@ -25,7 +25,7 @@ jobs:
     if: github.event.label.name == 'diagnosis-report'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 

.github/workflows/number-rfc.yml

@@ -14,7 +14,7 @@ jobs:
   number-rfc:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           persist-credentials: false

.github/workflows/release-version-check.yml

@@ -12,7 +12,7 @@ jobs:
     if: startsWith(github.event.pull_request.title, 'release:')
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           persist-credentials: false
 

.github/workflows/release.yml

@@ -10,7 +10,7 @@ on:  # zizmor: ignore[dangerous-triggers]
   workflow_run:
     workflows: ["CI"]
     types: [completed]
-    branches: [main, release/v0.3.2]
+    branches: [main, release/v0.3.0]
 
 permissions:
   contents: read
@@ -30,7 +30,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
         with:
           fetch-depth: 0
           ref: ${{ github.event.workflow_run.head_sha }}
@@ -80,13 +80,11 @@ jobs:
 
       - name: Tag release
         if: steps.version.outputs.proceed == 'true'
+        run: |
+          git tag "${STEPS_VERSION_OUTPUTS_TAG}"
+          git push origin "${STEPS_VERSION_OUTPUTS_TAG}"
         env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           STEPS_VERSION_OUTPUTS_TAG: ${{ steps.version.outputs.tag }}
-        run: |
-          gh api repos/${{ github.repository }}/git/refs \
-            -f ref="refs/tags/${STEPS_VERSION_OUTPUTS_TAG}" \
-            -f sha="${{ github.event.workflow_run.head_sha }}"
 
       - name: Pack package
         if: steps.version.outputs.proceed == 'true'

CLAUDE.md

@@ -8,30 +8,67 @@ This repo is the single source of truth for the TrUAPI protocol. It vendors `dot
 
 ```
 rust/crates/
-  truapi/                Rust trait + type definitions for protocol versions v0.1 and v0.2
+  truapi/                Rust trait + type definitions for protocol versions v0.1 and v0.2 (canonical)
   truapi-codegen/        rustdoc JSON → TypeScript client + Rust dispatcher
   truapi-macros/         #[wire(id = N)] proc-macro
+  truapi-platform/       Host syscall traits (storage, navigation, consent, ...)
+  truapi-server/         Rust runtime hosts implement; ships as WASM (browser/node)
 js/packages/
-  truapi/         @parity/truapi TS package; generated TS lives under ignored paths
-playground/              Next.js interactive playground; deploys to truapi-playground.dot
-hosts/dotli/             dotli submodule
-docs/                    design docs, RFCs, feature proposals
-scripts/codegen.sh       regenerate the TS client from the Rust crate
+  truapi/                  @parity/truapi TS package; generated TS lives under ignored paths
+  truapi-host-wasm/        @parity/truapi-host-wasm: WASM-backed host runtime. Subpath entries:
+	                           `.` (shared host types), `/web` (iframe + Web
+	                           Worker), `/worker-runtime` (Worker entry).
+	                           WASM bundle (gitignored) under dist/wasm/web/, built via `make wasm`
+playground/                Next.js interactive playground; deploys to truapi-playground.dot
+hosts/dotli/               dotli submodule
+docs/                      design docs, RFCs, feature proposals
+scripts/codegen.sh         regenerate the TS client from the Rust crate
 ```
 
+### Crate + binding invariants
+
+- `truapi` is canonical; runtime crates re-export rather than redefine. New
+  syscall traits and host-side runtime types live in `truapi-platform` and
+  `truapi-server`, not in `truapi`. Any additions to `truapi` itself are limited
+  to additive `Display` impls.
+- All types exposed by `truapi-platform` and `truapi-server` come from
+  `truapi::versioned::*` and `truapi::v01::*`. The runtime crates re-export
+  rather than redefine.
+- `truapi-server` WASM artifacts live under
+  `js/packages/truapi-host-wasm/dist/wasm/web/` and are gitignored.
+  Build them locally with `make wasm` (rerun whenever
+  `rust/crates/truapi-server/` changes); CI builds the bundle fresh from the
+  Rust source on every run.
+
 ## Code style
 
 - Every `pub` Rust item (functions, methods, types, traits, modules, constants) carries a doc comment (`///` or `//!`).
   Keep it short and focused on intent or invariants, not on what the signature already says.
 - Do not add code comments or doc comments that narrate migrations, compatibility shims, or historical changes. Comments should describe only the current code.
 - Remove legacy compatibility code by default. Keep or add it only when explicitly requested.
 - In Rust format strings, prefer inlined variables: `"log value: {value:?}"` over `"log value: {:?}", value`.
+- For Rust modules, prefer `foo.rs` plus an optional `foo/` directory for
+  child modules. Do not introduce new `foo/mod.rs` files unless preserving
+  generated output or an existing external convention.
+- In runtime Rust code, prefer `core::` over `std::` for types that are
+  available in `core` (`core::pin::Pin`, `core::task::Poll`, `core::fmt`, and
+  similar). Keep `std::` for std-only APIs, tests, and std-only programs such
+  as `truapi-codegen`.
 - **No `any` in TypeScript types**: If a type can't be expressed cleanly, stop and ask the user whether to (a) refactor or import the right type or (b) add a scoped `// eslint-disable-next-line @typescript-eslint/no-explicit-any` exception. Never silently leave `any`.
 - Don't introduce typealias chains that just rename a public type from another crate (e.g. `pub type StorageError = crate::v01::HostLocalStorageReadError`). Use the canonical name directly. A typealias is only worth its indirection when it captures a real abstraction.
-- After any code change, update `README.md` (and CLAUDE.md if the layout changed) so the top-level docs reflect what the repo actually contains. Stale docs are a regression.
+- After any code change, update `README.md` (and CLAUDE.md if the layout changed) so the top-level docs reflect what the repo actually contains. Stale docs are a regression. When moving or removing docs, `rg` for the old path and update or remove stale links in README files, agent notes, skills, comments, and design docs.
 - In codegen emitters, prefer `indoc::writedoc!` / `formatdoc!` over chains of `writeln!`. A single `writedoc!` with a multi-line raw string keeps the emitted shape visible in source instead of fragmenting it across one-line `writeln!` calls. Reserve `writeln!` for the genuinely-one-line case (a single import, a single statement inside a loop).
 - In PR descriptions, issue comments, and other artifacts that outlive the conversation: describe the resulting state, not the transition between commits. Avoid "previously X, now Y", "we removed", "the old shim is gone", "this PR replaces", those read as ephemeral history once the PR is squash-merged. Write what the system _does_ after the change, not what each commit _changed_ on the way there. (Commit messages are the place for transition narrative; they survive in `git log` even after the squash.)
 
+## Explanation style
+
+- For architecture, event-flow, and debugging explanations, start with a short
+  direct summary of the model before diving into long details. Prefer simple
+  statements like "the host sends a dirty signal; the core re-reads and derives
+  auth state" before listing each hop.
+- Use diagrams only when they clarify ownership or message flow. Keep them
+  layered and label what is per-tab, shared, host-owned, and core-owned.
+
 ## First-time setup
 
 ```bash
@@ -116,6 +153,90 @@ submodule init + `bun install` and the per-pane `cd` discipline).
 Alternatively, with a deployed Polkadot Desktop Host installed, navigate to
 `https://dot.li/localhost:3000` from within it.
 
+#### Local dotli + playground E2E notes
+
+Use `make dev DEBUG=1` from the repo root for the local host stack. It prepares
+the ignored WASM/build artifacts, verifies dotli can resolve
+`@parity/truapi-host-wasm`, then starts dotli on `:5173` and the playground on
+`:3000`. Open `http://localhost:5173/localhost:3000`.
+
+When automating with Playwright, block service workers for smoke tests unless
+the test is explicitly about SW behavior. Stale host/product bundles can mask
+runtime fixes. Use a fresh cache-busting query string on
+`http://localhost:5173/localhost:3000?...`, collect `pageerror` and
+`console` messages, and fail on unexpected page errors.
+
+For interactive SSO checks, prefer a persistent headed Chrome profile and reuse
+the same browser context across checks. SSO pairing needs a real phone QR scan,
+and signing/resource-allocation flows may need web or mobile confirmation; if
+the human or companion app is unavailable, skip those methods and record the
+skip instead of treating it as a protocol failure. Non-interactive checks should
+still verify that the playground renders, the TrUAPI debug panel receives
+host/product events, generated examples can call non-confirmation methods, and
+logout/relogin does not restore a stale session.
+
+The dotli Playwright e2e suite under `hosts/dotli/apps/host/tests/e2e/`
+pairs through the signer-bot service. It requires `SIGNER_BOT_SVC_TOKEN`;
+`SIGNER_BOT_BASE_URL` and `SIGNER_BOT_NETWORK` default to dotli CI's
+`https://signing-bot-dev.novasama-tech.org/` and `paseo-next-v2`. Without the
+token, do not treat the full suite as locally runnable. Use
+`E2E_DOTLI_SMOKE=1 make e2e-dotli` for the no-phone QR smoke path.
+If those signer-bot variables are not available in a worktree, check for a
+repo-root `.env` and load or copy the values from there before falling back to
+smoke mode. Prefer the current worktree's `.env` when it exists.
+
+For a fully automated local playground diagnosis run, use:
+
+```bash
+SIGNER_BOT_SVC_TOKEN=... \
+make e2e-dotli
+```
+
+`make e2e-dotli` starts dotli preview and the playground, signs out any
+restored host session, signs in through signer-bot by extracting the QR payload,
+runs the playground Diagnosis screen, auto-accepts host-side Allow/Sign modals,
+and writes `hosts/dotli/test-results/e2e-dotli/diagnosis-report.md`.
+
+Root CI runs the same target when it can read the private dotli submodule. It
+needs `DOTLI_CHECKOUT_TOKEN` for submodule checkout; without that token, the
+job warns and skips dotli e2e rather than failing unrelated PR checks. With
+dotli access but without `SIGNER_BOT_SVC_TOKEN`, CI runs the no-phone smoke
+path only.
+
+A useful no-phone smoke assertion is:
+
+```bash
+E2E_DOTLI_SMOKE=1 make e2e-dotli
+```
+
+For manual debugging of that smoke path:
+
+1. Start `make dev DEBUG=1`.
+2. Open `http://localhost:5173/localhost:3000?debug=truapi&cachebust=<ts>` with
+   service workers blocked.
+3. Wait for `globalThis.__truapi?.setLogLevel`, call
+   `__truapi.setLogLevel("debug")`, and confirm the console logs
+   `[truapi worker] logLevel=debug providers=0`.
+4. Click `#auth-button`, wait for `#auth-modal-backdrop.open`, and confirm:
+   the modal shows `Login with Polkadot Mobile`, `__truapi.getProviderCount()`
+   is greater than zero, worker frame/callback logs appear, and there are no
+   page errors.
+
+If `make dev` reports `EADDRINUSE` on `:5173` or the playground moves from
+`:3000` to `:3001`, kill stale `preview-server.ts` / `next dev` processes and
+restart the tmux session. Port drift causes false-negative local e2e results.
+
+Useful debug signals:
+
+```js
+__truapi.setLogLevel("debug");
+sessionStorage.setItem("dotli:truapi-debug", "1");
+```
+
+Reload after setting the debug-panel flag. Watch for `Unknown wire discriminant`, missing
+`@parity/truapi-host-wasm` imports, worker WASM instantiation failures, and
+debug-panel traffic disappearing when the login popup opens.
+
 ## Deployment
 
 Pushes to `main` trigger `.github/workflows/deploy-playground.yml`, which builds `playground/` and publishes the static export to `truapi-playground.dot` via `bulletin-deploy`.