docs(agents): Update project guidance

.agents/skills/cryptad-architecture/SKILL.md

@@ -69,6 +69,9 @@ Use this skill when you need to:
     AppHost core)
   - `:platform-app-ui` → `network.crypta.platform.appui` (app-owned static UI route and asset
     resolution helpers)
+  - `:platform-sdk-js` → browser SDK resource for app-owned static UI bootstrap, Platform API
+    transport helpers, mutation form handling, error parsing, and conservative fragment
+    sanitization
   - `:platform-appdist` → `network.crypta.platform.appdist` (signed local app bundle digest,
     signature, manifest, verifier, trusted-key, and distribution tooling)
   - `:platform-appcatalog` → `network.crypta.platform.appcatalog` (signed catalog sources,
@@ -128,8 +131,9 @@ Use this skill when you need to:
   `:kernel-routing` owns the compile-neutral phase-1 routing/helper slice,
   `:platform-api` owns the transport-neutral Platform API surface, `:platform-apphost` owns the
   transport-neutral AppHost core, `:platform-app-ui` owns app-owned static UI route helpers,
-  `:platform-appdist` owns signed local bundle distribution, `:platform-appcatalog` owns signed
-  catalog sources and verified staging, `:platform-web-shell` owns the browser-facing
+  `:platform-sdk-js` owns the browser SDK resource, `:platform-appdist` owns signed local bundle
+  distribution, `:platform-appcatalog` owns signed catalog sources and verified staging,
+  `:platform-web-shell` owns the browser-facing
   node-management shell, `:runtime-alerts` owns the extracted alert/feed model subset,
   `:runtime-node` owns the
   remaining runtime/node/client/support body, `:adapter-fcp` owns the FCP adapter tree,
@@ -163,8 +167,9 @@ Use this skill when you need to:
   `RuntimeNodeKernelSplitPrepBoundaryTest`, `KernelContentBoundaryTest`,
   `KernelTransportBoundaryTest`, `KernelRoutingBoundaryTest`, `PlatformApiBoundaryTest`,
   `AdapterFcpBoundaryTest`, `BridgeFcpRuntimeBoundaryTest`, `AppHostBoundaryTest`,
-  `WebShellBoundaryTest`, `HttpLegacyAdminBoundaryTest`, `LegacyHttpBrowseBoundaryTest`, and
-  `BridgeHttpRuntimeBoundaryTest` guard leaf ownership/import rules. The runtime, kernel,
+  `CryptaPlatformSdkBoundaryTest`, `WebShellBoundaryTest`, `HttpLegacyAdminBoundaryTest`,
+  `LegacyHttpBrowseBoundaryTest`, and `BridgeHttpRuntimeBoundaryTest` guard leaf
+  ownership/import rules. The runtime, kernel,
   platform, FCP, and HTTP boundary suites also require `package-info.java` in the production
   packages they own.
 
@@ -290,6 +295,9 @@ Use this skill when you need to:
   - `SecurityLevelsToadlet` uses `SecurityLevelsPort` for detached page state, warning HTML, and
     master-password mutation flows.
   - `PageMaker` reads shared shell status through `PageChromePort`.
+  - `LegacyAdminRetirementRegistry` maps replaced legacy admin surfaces, and
+    `LegacyAdminUsageRecorder` feeds process-local legacy-page counters into Platform API
+    diagnostics without storing query strings, form bodies, tokens, or remote addresses.
   - `network.crypta.clients.http.updater.CoreActionToadlet` reaches updater availability,
     download triggers, and installer-path validation through `CoreUpdateActionPort`.
   - `FirstTimeWizardToadlet` and `FirstTimeWizardNewToadlet` use `FirstTimeWizardPort` for
@@ -316,15 +324,22 @@ Use this skill when you need to:
 - `:platform-api` owns the transport-neutral Platform API v1 under `network.crypta.platform.api`.
   It exposes node/config/peer/connectivity/security, queue, updates, wizard, alerts, diagnostics,
   apps, and app-catalog control-plane families and is currently mounted at `/api/v1/` by the
-  legacy HTTP adapter.
+  legacy HTTP adapter. It also owns the central app-token authorization matrix and bounded
+  process-local app audit log for AppHost-originated API requests.
 - `:platform-apphost` owns the transport-neutral out-of-process AppHost v1 under
   `network.crypta.platform.apphost`. It validates staged local app bundles, owns the immutable
   installed-bundle layout plus mutable data/cache/run directories, and provides local
-  install/list/describe/start/stop/update/uninstall operations.
+  install/list/describe/start/stop/update/uninstall operations, per-launch app tokens, minimal
+  launch environments, token-redacted process-log snapshots, and in-session restart attempts for
+  manifests that opt in.
 - `:platform-app-ui` owns `network.crypta.platform.appui`, the transport-neutral app-owned static
   UI path layer. It maps installed static UI manifests to `/apps/{appId}/`, preserves nested entry
   base URLs, resolves bundle assets, rejects traversal/symlink/reparse escapes, and supplies
   deterministic content-type and security-header helpers for HTTP adapters.
+- `:platform-sdk-js` owns the dependency-free browser SDK resource staged into first-party static
+  app bundles. It wraps route bootstrap, same-origin Platform API reads, form-password mutations,
+  error parsing, and conservative legacy HTML fragment sanitization; it is not an authority or
+  isolation boundary.
 - `:platform-appdist` owns `network.crypta.platform.appdist`, the signed local bundle
   distribution layer. It parses normalized app manifests, writes deterministic SHA-256 digest
   sidecars, verifies Ed25519 signatures, rejects reserved sidecars as executable/UI entries, and
@@ -346,8 +361,8 @@ Use this skill when you need to:
   `QueueCompletionPort`, `QueuePagePort`, `QueueDownloadPort`, `QueueInsertPort`,
   `QueueMutationPort`, `StatisticsPort`, `SecurityLevelsPort`, `PageChromePort`,
   `CoreUpdateActionPort`, `FirstTimeWizardPort`, `ToadletSymlinkPort`, `WelcomePagePort`,
-  `WelcomeActionPort`, `AlertFeedPort`, `AlertMutationPort`, `RequestQueuePort`, `NodeInfoPort`,
-  and `PeerPort`
+  `WelcomeActionPort`, `AlertFeedPort`, `AlertMutationPort`, `LegacyAdminUsagePort`,
+  `RequestQueuePort`, `NodeInfoPort`, and `PeerPort`
 - Detached DTOs include config, connectivity, peer, darknet-friends, node-reference, queue,
   security-level, shared shell, first-time-wizard, symlinker, welcome-page, alert, and
   statistics/report snapshot types such as
@@ -356,7 +371,8 @@ Use this skill when you need to:
   `QueuePageSnapshot`, `QueuePersistenceStatusSnapshot`, `QueueInsertOutcome`,
   `SecurityLevelsSnapshot`, `PageChromeSnapshot`, `FirstTimeWizardSnapshot`,
   `FirstTimeWizardCurrentBandwidthLimits`, `ToadletSymlinkEntry`, `WelcomePageSnapshot`,
-  `AlertListSnapshot`, `AlertSnapshot`, and `AlertSeverity`
+  `AlertListSnapshot`, `AlertSnapshot`, `AlertSeverity`, `LegacyAdminUsageSnapshot`, and
+  `LegacyAdminSurfaceUsage`
 - Daemon-backed adapters in `network.crypta.runtime.core` (currently in `:runtime-node`):
   `LegacyRuntimePorts`, `LegacyConfigPort`,
   `LegacyConnectivityPort`, `LegacyNodeInfoPort`, `LegacyPeerPort`, `LegacyRequestQueuePort`,
@@ -453,6 +469,7 @@ Use this skill when you need to:
 - `:platform-api`: `network.crypta.platform.api`
 - `:platform-apphost`: `network.crypta.platform.apphost`
 - `:platform-app-ui`: `network.crypta.platform.appui`
+- `:platform-sdk-js`: browser SDK resource under `network/crypta/platform/sdk/js`
 - `:platform-appdist`: `network.crypta.platform.appdist`
 - `:platform-appcatalog`: `network.crypta.platform.appcatalog`
 - `:platform-web-shell`: `network.crypta.platform.webshell`
@@ -486,6 +503,9 @@ Use this skill when you need to:
 2. `RequestScheduler` manages queues and priorities
 3. `SendableRequest` implementations perform request types
 4. Routing uses location-based algorithms for discovery
+- `ClientRequestSelector` returns the earliest useful cooldown wakeup, and
+  `ClientRequestScheduler#scheduleWakeStarterAt` coalesces starter wakeup jobs. Selector code
+  should not queue duplicate ticker wakeups directly.
 
 ### Update system (high level)
 - `NodeUpdateManager` coordinates updates.

.agents/skills/cryptad-build-test/SKILL.md

@@ -23,7 +23,7 @@ Use this skill when you need to:
   `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:kernel-content`,
   `:kernel-transport`, `:kernel-routing`, `:runtime-spi`, `:platform-api`,
   `:platform-apphost`, `:platform-app-ui`, `:platform-appdist`, `:platform-appcatalog`,
-  `:platform-web-shell`, `:runtime-alerts`, `:runtime-node`, `:adapter-fcp`,
+  `:platform-sdk-js`, `:platform-web-shell`, `:runtime-alerts`, `:runtime-node`, `:adapter-fcp`,
   `:bridge-fcp-runtime`, `:bridge-http-runtime`,
   `:adapter-http-legacy-admin`, `:adapter-http-legacy-browse`, `:thirdparty-onion`,
   `:thirdparty-legacy`, and `:launcher-desktop`.
@@ -81,9 +81,10 @@ Use this skill when you need to:
   `RuntimeNodeKernelSplitPrepBoundaryTest`, `KernelContentBoundaryTest`,
   `KernelTransportBoundaryTest`, `KernelRoutingBoundaryTest`, `PlatformApiBoundaryTest`,
   `AdapterFcpBoundaryTest`, `BridgeFcpRuntimeBoundaryTest`, `AppHostBoundaryTest`,
-  `WebShellBoundaryTest`, `HttpLegacyAdminBoundaryTest`, `LegacyHttpBrowseBoundaryTest`, and
-  `BridgeHttpRuntimeBoundaryTest` are the focused regression checks for leaf ownership/import
-  boundaries. The runtime, kernel, platform, FCP, and HTTP boundary suites also enforce
+  `CryptaPlatformSdkBoundaryTest`, `WebShellBoundaryTest`, `HttpLegacyAdminBoundaryTest`,
+  `LegacyHttpBrowseBoundaryTest`, and `BridgeHttpRuntimeBoundaryTest` are the focused regression
+  checks for leaf ownership/import boundaries. The runtime, kernel, platform, FCP, and HTTP
+  boundary suites also enforce
   `package-info.java` coverage for the production packages they own.
 - `:runtime-spi` is the JDK-only runtime/config API leaf. Its focused unit tests still live in the
   root test tree and run through the root build.
@@ -98,6 +99,8 @@ Use this skill when you need to:
 - `:platform-appcatalog` owns signed catalog source parsing, verification, artifact download,
   safe ZIP extraction, and verified staging code plus focused tests under
   `platform-appcatalog/src/test/java`.
+- `:platform-sdk-js` owns the dependency-free browser SDK resource and focused resource/boundary
+  tests under `platform-sdk-js/src/test/java`.
 - `:platform-web-shell` owns the browser-facing Web Shell leaf and its focused leaf tests under
   `platform-web-shell/src/test/java`.
 - `:runtime-alerts` owns the extracted leaf-safe `network.crypta.runtime.alerts` feed/model
@@ -158,6 +161,7 @@ When running ./gradlew test via OpenCode bash, set timeout ≥ 15 minutes (≥ 9
   - `./gradlew :platform-app-ui:test`
   - `./gradlew :platform-appdist:test`
   - `./gradlew :platform-appcatalog:test`
+  - `./gradlew :platform-sdk-js:test`
   - `./gradlew :platform-web-shell:test`
   - `./gradlew :kernel-content:test`
   - `./gradlew :kernel-transport:test`
@@ -223,6 +227,9 @@ When running ./gradlew test via OpenCode bash, set timeout ≥ 15 minutes (≥ 9
   - `./gradlew :platform-appdist:compileJava`
 - Compile the app catalog leaf when you touched `network.crypta.platform.appcatalog`:
   - `./gradlew :platform-appcatalog:compileJava`
+- Process and test the Platform SDK resource leaf when you touched
+  `platform-sdk-js/src/main/resources/network/crypta/platform/sdk/js/crypta-platform.js`:
+  - `./gradlew :platform-sdk-js:processResources :platform-sdk-js:test`
 - Compile the Web Shell leaf when you touched `network.crypta.platform.webshell`:
   - `./gradlew :platform-web-shell:compileJava`
 - Compile the extracted runtime-alerts leaf when you touched `network.crypta.runtime.alerts`:
@@ -246,7 +253,8 @@ When running ./gradlew test via OpenCode bash, set timeout ≥ 15 minutes (≥ 9
   - `./gradlew compileJava compileTestJava`
 
 ## First-party app bundle checks
-- Stage first-party app bundles:
+- Stage first-party app bundles, especially after changing `:platform-sdk-js` because Queue
+  Manager and Publisher copy the SDK into staged static assets:
   - `./gradlew stageFirstPartyApps`
 - Run app project tests:
   - `./gradlew :apps:queue-manager:test`

.agents/skills/cryptad-core-updater/SKILL.md

@@ -50,6 +50,9 @@ Use this skill when working on:
 - Actions: `download`, `install`, `openStore`
 - UI: alerts panel shows progress percent when available.
   - Failures surface clear retry guidance (non-fatal errors relabel to “Retry”).
+- `NodeUpdater` intentionally delays retries for `FetchExceptionMode.RECENTLY_FAILED` instead of
+  rescheduling immediately while the key is still in the recently-failed table. Preserve that
+  throttle unless replacing it with an explicit, tested retry policy.
 - Request parsing, redirects, `AppEnv` checks, and OS-specific installer or store-launching now
   live in the HTTP adapter layer at `network.crypta.clients.http.updater.CoreActionToadlet`,
   currently packaged in `:adapter-http-legacy-admin`.

.agents/skills/cryptad-interop-performance-gates/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: cryptad-interop-performance-gates
+description: "Maintain Cryptad's Hyphanet interop and performance regression gates under tools/interop, tools/perf, CI jobs, and release-readiness documentation."
+---
+
+# Cryptad interop and performance gates
+
+Use this skill before changing `tools/interop`, `tools/perf`, related CI jobs, or release-gate
+documentation.
+
+## Read first
+
+- Hyphanet interop gate: `tools/interop/README.md`
+- Performance regression gate: `tools/perf/README.md`
+- Release readiness gates: `docs/cryptad-release-workflow-and-runbook.md`
+- Phase 3 platform closeout context: `docs/phase-3-platform-primacy-closeout.md`
+
+## Hyphanet interop gate
+
+- Tier 1 smoke is the release-readiness compatibility gate. It is Linux-only and runs a packaged
+  Cryptad node against a pinned Hyphanet baseline.
+- Tier 2 extended soak runs locally or through scheduled/manual CI when compatibility-sensitive
+  behavior changed. It adds long-lived `SubscribeUSK`, persistent request replay, optional opennet
+  plumbing, and longer diagnostics.
+- Normal local commands:
+
+```bash
+python3 tools/interop/interop_smoke.py --self-test
+tools/interop/run-hyphanet-interop-smoke.sh
+INTEROP_SKIP_BUILD=1 tools/interop/run-hyphanet-interop-smoke.sh
+INTEROP_MODE=extended INTEROP_SKIP_BUILD=1 tools/interop/run-hyphanet-interop-smoke.sh
+```
+
+- Do not publish `artifacts/private-insert-uris.json`; it contains temporary insert keys and CI
+  excludes it from uploads.
+- Preserve `build/interop-smoke/` or `build/interop-extended/` when a gate fails or when a release
+  record needs compatibility evidence.
+
+## Performance regression gate
+
+- The performance gate records lightweight packaged-node startup, local FCP/Platform API timing,
+  distribution size, Web Shell asset size, SDK asset size, and first-party static app asset size
+  signals. It is not a broad benchmark suite.
+- The runner requires Python 3.12 or newer.
+- Normal local commands:
+
+```bash
+python3 tools/perf/perf_smoke.py --self-test
+tools/perf/run-performance-smoke.sh
+PERF_SKIP_BUILD=1 tools/perf/run-performance-smoke.sh
+PERF_MODE=collect PERF_SKIP_BUILD=1 tools/perf/run-performance-smoke.sh
+```
+
+- Deterministic asset-size failures are release blockers unless a maintainer records an accepted
+  baseline update or waiver. Environment-sensitive timing regressions need comparable hardware or
+  runner evidence before promotion decisions.
+- Do not update `tools/perf/baselines/performance-smoke.json` only to silence a regression. Record
+  before/after summaries, host or runner details, Java version, commit SHA, and the rationale.
+
+## CI and release notes
+
+- `.github/workflows/ci.yml` runs `interop-smoke` on push/PR, `interop-extended` on schedule/manual,
+  interop self-tests on the multi-OS matrix, performance self-tests on the multi-OS matrix, and
+  `performance-smoke` on schedule/manual.
+- Release notes should mention interop/performance gate changes only when they affect release
+  readiness, operator confidence, app/platform behavior, or packager workflows.

.agents/skills/cryptad-packaging/SKILL.md

@@ -25,7 +25,7 @@ Use this skill when working on:
   `:foundation-config`, `:foundation-fs`, `:foundation-compat`, `:kernel-content`,
   `:kernel-transport`, `:kernel-routing`, `:runtime-spi`, `:platform-api`,
   `:platform-apphost`, `:platform-app-ui`, `:platform-appdist`, `:platform-appcatalog`,
-  `:platform-web-shell`, `:runtime-alerts`, `:runtime-node`, `:adapter-fcp`,
+  `:platform-sdk-js`, `:platform-web-shell`, `:runtime-alerts`, `:runtime-node`, `:adapter-fcp`,
   `:bridge-fcp-runtime`, `:bridge-http-runtime`,
   `:adapter-http-legacy-admin`, `:adapter-http-legacy-browse`, `:thirdparty-onion`,
   `:thirdparty-legacy`, and `:launcher-desktop`.
@@ -48,6 +48,8 @@ Use this skill when working on:
   trusted-key, and distribution-tool classes used by first-party app tasks and AppHost validation.
 - The `:platform-appcatalog` JAR contributes signed catalog source parsing, verification,
   artifact download, safe ZIP extraction, and verified staging support.
+- The `:platform-sdk-js` JAR contributes the browser SDK resource staged into first-party static
+  app bundles and loaded by app-owned UIs under `/apps/{appId}/`.
 - The `:platform-web-shell` JAR contributes the browser-facing node-management shell HTML, CSS,
   JavaScript, and bootstrap resources that the legacy HTTP adapter mounts at `/app/node/`.
 - The `:runtime-alerts` JAR contributes the detached alert/feed model subset, including the
@@ -72,7 +74,8 @@ Use this skill when working on:
 - First-party app projects such as `:apps:queue-manager` and `:apps:publisher` provide staged app
   bundles through their `stageApp`, `signApp`, and `verifyApp` tasks. Those bundles are release
   artifacts and AppHost install inputs; they are not daemon entrypoints inside
-  `build/cryptad-dist`.
+  `build/cryptad-dist`. Their static UI staging copies the current `:platform-sdk-js` browser
+  resource into each bundle's `static/` assets.
 
 ## Distributions and Windows wrapper sources
 - `assembleCryptadDist` creates a portable layout under `build/cryptad-dist` with `bin/`, `lib/`, and `conf/`.