@astrale-os/adapter-cloudflare 0.1.8 → 0.1.10

package/src/params.ts

@@ -55,37 +55,38 @@ export interface CloudflareParams {
    * worker-entry codegen and aren't supported through this field yet.
    */
   wrangler?: Record<string, unknown>
-}
-
-/** Params for the Astrale-managed adapter (`astrale(envs)`). */
-export interface AstraleParams {
   /**
-   * Target instance slug the domain installs onto (e.g. `'bryan-e2e5'`).
-   * Required for `deploy` (managed publish + install); ignored by `watch`
-   * (local dev) — so dev-only envs may omit it.
-   */
-  instance?: string
-  /** Catalog package name. Default: the origin's first DNS label. */
-  name?: string
-  /** Admin kernel URL the publish calls target. Default the platform admin. */
-  adminUrl?: string
-  /** Routing region of the `.svc` service URL. Default `'eu'`. */
-  region?: string
-  /** CLI identity (`--as`) for the publish calls. Default: the CLI's active identity. */
-  identity?: string
-  /** Gitignored secrets file. `watch`: injected into local wrangler dev. `deploy`: shipped on the install call and applied to the managed service env (encrypted at rest platform-side; platform keys win precedence). */
-  secrets?: string
-  /** Local dev port for `wrangler dev`. Default 8787. */
-  port?: number
-  /**
-   * Public URL the dev server is reached through (tunnel / sandbox preview /
-   * reverse proxy), e.g. `'https://my-box.preview.dev'`. Sets BOTH effects an
-   * off-localhost dev needs: wrangler binds 0.0.0.0 (reachable from outside)
-   * and `WORKER_URL` is pinned to this URL so the worker's per-request-Host
-   * identity (`iss`) doesn't drift to the proxy's internal hostname.
-   * Usually injected by `pnpm dev --host <url>` rather than written here.
+   * Route subrequests to platform INSTANCE hostnames through a service binding
+   * instead of the public edge. A Cloudflare Worker can't fetch a same-zone
+   * hostname served by another Worker — Cloudflare 522s it — so without this the
+   * worker can't fetch an instance kernel's JWKS to verify an inbound credential
+   * from that instance, and every cross-instance call (install hooks, the GUI's
+   * delegated calls, authed views) fails with `2002 Credential verification
+   * failed`. Point it at a router Worker that reaches those hosts internally
+   * (Astrale: `admin-router`).
+   *
+   * Wires BOTH halves the SDK needs: the `<binding>` service binding in the
+   * generated wrangler config, and a `routeSubrequest` predicate in the worker
+   * entry that diverts matching hosts through it.
+   *
+   * ON BY DEFAULT (targets `admin-router`) so every adapter-deployed worker can
+   * verify cross-instance credentials out of the box. Pass `false` to disable
+   * (a domain that never talks to another instance, or an account without a
+   * router), or an object to override the target / binding name / host match.
+   *
+   *   router: false                      // opt out
+   *   router: { service: 'my-router' }   // override target
    */
-  host?: string
-  /** Extra plain vars for local `watch`. */
-  vars?: Record<string, string>
+  router?:
+    | false
+    | {
+        /** Router Worker the binding targets. Default `'admin-router'`. */
+        service?: string
+        /** Service-binding name the worker reads. Default `'ROUTER'`. */
+        binding?: string
+        /** Host suffix that marks an instance host. Default `'.astrale.ai'`. */
+        hostSuffix?: string
+        /** Min dot-separated label count for an instance host. Default `4` (`<slug>.<region>.astrale.ai`). */
+        minLabels?: number
+      }
 }

package/src/parse-output.ts

@@ -14,7 +14,7 @@ const WORKERS_DEV_RE = /(https:\/\/[^\s]+\.workers\.dev)/i
  * The fallback (when no explicit "Ready on" line) only accepts a localhost URL
  * on the EXPECTED port — wrangler may print unrelated localhost URLs (e.g. an
  * inspector/devtools endpoint on a different port) before readiness, and taking
- * one of those would point `astrale instance install <url>` at a dead endpoint.
+ * one of those would point `astrale domain install <url>` at a dead endpoint.
  */
 export function parseDevReadyUrl(text: string, port: number): string | undefined {
   const ready = READY_RE.exec(text)

package/template/.agents/skills/astrale-cli/SKILL.md

@@ -38,6 +38,7 @@ astrale logs <service>
 astrale status
 astrale browser
 astrale instance ...
+astrale domain ...
 astrale admin ...
 astrale identity ...
 astrale auth ...
@@ -50,7 +51,7 @@ Command groups:
 |---|---|
 | Kernel | `call`, `token`, `get`, `ls`, `describe`, `query`, `logs` |
 | Context | `status`, `whoami`, `use` |
-| Management | `admin`, `instance`, `identity`, `auth`, `idp`, `update` |
+| Management | `admin`, `instance`, `domain`, `identity`, `auth`, `idp`, `update` |
 | Agent | `browser` |
 
 Shared kernel options are merged onto kernel-touching commands at registration
@@ -90,7 +91,7 @@ Examples:
 
 ```bash
 astrale call /:blog.acme.com:class.Author:list
-astrale call /:blog.acme.com:interface.NoteOps:createNote title=Hello
+astrale call /:blog.acme.com:interface.MonitorOps:watch url=https://astrale.ai
 astrale call /blog.acme.com/alice::deactivate
 astrale call @f00d...::deactivate
 ```
@@ -148,7 +149,6 @@ astrale instance use my-app
 astrale instance active
 astrale instance bookmark staging --url https://kernel.example.com
 astrale instance forget staging
-astrale instance install https://domain.example.com
 ```
 
 Important distinctions:
@@ -164,23 +164,37 @@ Important distinctions:
 ## Domain Dev Workflow
 
 **The `astrale` CLI is connect-only — it does not build, run, or deploy
-domains.** There is no `astrale domain …` command group. Domain development
-lives in two separate tools:
+domains.** The `astrale domain` group manages the admin catalog and installs a
+running domain onto an instance (`list`, `publish`, `install`); it does NOT
+build or run domains. `astrale domain list` shows the published catalog (add
+`--check` to probe each URL's reachability, `--default-only` for the
+install-on-every-instance set, `-q` to pipe install URLs). Building, running,
+and deploying live in two separate tools:
 
 - **`create-astrale-domain`** scaffolds a new standalone domain project
   (`pnpm create astrale-domain <slug>`), writing an `astrale.config.ts`.
-- **`astrale-domain`** (the `@astrale-os/devkit` bin, behind the project's
+- **`astrale-domain`** (the `@astrale-os/sdk` bin, behind the project's
   `pnpm dev` / `pnpm prod` scripts) runs `dev | prod | deploy <env> | build`.
 
-Domains are **installed by URL**, never from a file: run or deploy the domain
-worker, then `astrale instance install <url> -i <slug>` — the kernel fetches a
-signed install bundle from the running worker. There is no committed
-`spec.json` and no `astrale domain install`; install lives under the
-`instance` group because it operates on an instance graph.
+Domains are **installed by URL or catalog origin**, never from a file (there is
+no committed `spec.json`). `astrale domain install` has two modes:
+
+- **default (via admin)** — `astrale domain install <origin|url> -i <slug>`
+  installs a PUBLISHED domain through the admin control plane
+  (`DomainEntry.install`), addressed by its catalog `origin` (the unique
+  registry key) or `url`. Run it bare to pick from the catalog interactively.
+  The target instance is the active one or `-i <slug>` and **must be
+  admin-managed** (otherwise it fails loudly and points you at `--direct`).
+- **`--direct`** — `astrale domain install <url> --direct` installs a url
+  straight onto the instance kernel (`Root.installDomain`), bypassing the
+  catalog. Works on ANY instance you can authenticate to (managed, bookmarked,
+  or local), using your own authority, and is the only mode that runs the
+  identity-override consent gate. Use it for dev/local instances and
+  freshly-deployed, not-yet-published workers.
 
 With the **managed (`astrale`) adapter**, `pnpm prod` publishes the bundle
 through the platform AND installs it on the configured instance in one step —
-no manual `instance install`. The service serves at
+no manual `domain install`. The service serves at
 `https://<name>-<hash>.svc.<region>.astrale.ai` (the CLI session is the auth).
 
 For authoring domains end-to-end (schema, handlers, external APIs, deploys),

package/template/.agents/skills/astrale-domain/SKILL.md

@@ -36,14 +36,21 @@ pnpm prod     # deploy + (astrale adapter) auto-install on your instance
 Project anatomy (the scaffold is the reference — read its comments):
 
 ```
-astrale.config.ts   # THE manifest: schema + postInstall + adapter (where it ships)
+domain.ts           # THE manifest — wires it ALL: defineDomain({ schema, methods,
+                    #   deps, views, functions, client }) + origin/postInstall.
+                    #   Modules are imported & passed EXPLICITLY (no folder magic);
+                    #   a renamed module is a compile error here, not a missing route.
+astrale.config.ts   # binds the domain to its deploy adapter (deploy(domain, …)) — node-only
 schema/             # classes/interfaces/edges — the contract (zod props, fn signatures)
-methods/            # handler logic (transport-agnostic fns) + thin wiring (index.ts)
-services/           # RECOMMENDED: ports + factories for external APIs (see §4)
+                    #   + index.ts exports D = compileDomain(schema) (resolved paths/keys)
+core/<context>/     # pure, transport-agnostic logic per bounded context (e.g. core/monitor: keys/health/node)
+integrations/       # external-API ports + adapters + a lazy registry (see §4) — what deps is built from
+runtime/index.ts    # composition root: the methods map; each execute resolves deps → calls core logic
 functions/          # standalone remote functions (webhook-shaped endpoints)
 views/              # iframe-mountable UI declarations (defineView)
 client/             # the SPA served under /ui (vite)
-env.ts              # typed worker env — config + secrets arrive here, as ctx.deps
+deps.ts             # env → typed Deps container (the seam defineDomain({ deps }) mounts)
+env.ts              # typed worker env — config + secrets arrive here, mapped by deps.ts → ctx.deps
 ```
 
 Iteration loop: edit → `pnpm prod` → call it. Managed redeploys keep the same
@@ -97,9 +104,10 @@ Conventions and rules:
 
 ## 2 · Handlers
 
-Separate LOGIC from WIRING. Logic = plain async functions taking the kernel
-client + ports + params (testable with fakes). Wiring = `method()` /
-`classMethods()` / `interfaceMethods()` in `methods/index.ts`:
+Separate LOGIC from WIRING. Logic = plain async functions in `core/` taking the
+kernel client + ports + params (testable with fakes). Wiring = `method()` /
+`classMethods()` / `interfaceMethods()` in `runtime/index.ts` (the composition
+root — the only place request context + `deps` meet the `core/` logic):
 
 ```ts
 const kickoff = method(schema, 'Project', 'kickoff', {
@@ -113,9 +121,11 @@ const kickoff = method(schema, 'Project', 'kickoff', {
 
 Handler context: `kernel` (callback client bound to the composed credential —
 caller's delegated authority ∪ this function's own), `self` (instance methods),
-`params` (zod-validated), `deps` (your typed `Env`), `auth` (principal,
-verified claims). Construct external clients from `deps` per request — NEVER
-at module load (workers must be import-side-effect-free).
+`params` (zod-validated), `deps` (your typed `Deps` from `deps.ts`; raw `Env` if
+you omit the mapper), `auth` (principal, verified claims). Resolve ports from
+`deps` per request (`deps.prober()` — the registry builds + caches them per
+isolate) — NEVER construct external clients at module load (workers must be
+import-side-effect-free).
 
 ## 3 · Talking to the kernel (and other domains)
 
@@ -155,16 +165,20 @@ Almost every real domain wraps an external API (payment, calendar, LLM
 gateway, cloud provider). The shape (see admin/domain for the full-scale
 example — Scaleway/WorkOS/KV):
 
-1. **Port** — a narrow interface declaring only what the logic needs
-   (`WeatherClient { forecast(city) }`). Logic depends on the port, never on
-   fetch/SDKs/env.
-2. **Factory** — `createXClient(env)` in `services/`: reads config + secrets
-   from `env`, validates LOUDLY (`if (!env.X_API_KEY) throw`), sets base URLs
-   (overridable so tests point at a stub), timeouts (`AbortSignal.timeout`),
-   and maps upstream failures to meaningful errors with the upstream detail in
-   `cause` (the kernel threads cause chains to callers).
-3. **Wiring** — the `execute` hook builds the client from `deps` per request
-   and passes it to the logic.
+1. **Port** — a narrow interface in `integrations/<feature>/port.ts` declaring
+   only what the logic needs (`WeatherClient { forecast(city) }`, the scaffold's
+   `Prober { probe(url) }`). `core/` logic depends on the port, never
+   on fetch/SDKs/env.
+2. **Adapter(s) + registry** — `createXClient(config)` in
+   `integrations/<feature>/` (one per backend), plus a `registry.ts` that reads
+   config + secrets from `env`, validates LOUDLY (`if (!env.X_API_KEY) throw`),
+   sets base URLs (overridable so tests point at a stub), timeouts
+   (`AbortSignal.timeout`), and maps upstream failures to errors with the
+   upstream detail in `cause`. The registry builds the chosen adapter LAZILY +
+   caches it per isolate (a worker never validates an unused backend's env).
+3. **Wiring** — `deps.ts` mounts the registry (`defineDomain({ deps })`); the
+   `execute` hook resolves the PORT from `deps` (`deps.prober()`) per
+   request and passes it to the `core/` logic.
 
 Secrets & config:
 - Declare every var as a typed field on `Env` in `env.ts`. Secrets ship via
@@ -202,8 +216,10 @@ Anti-patterns (all observed in production code — don't):
 ## 5 · Views & standalone functions (webhooks)
 
 - `defineView({ auth, mount: '/ui/contact', viewFor: selfOf(Contact) })` in
-  `views/` + register in `views/index.ts` — the MAP KEY is the view's node
-  slug (`'ui-contact'` → `/<origin>/core/views/ui-contact`). Installs a View
+  `views/`, collected into the `views` map in `views/index.ts`, which
+  `astrale.config.ts` imports and passes to `defineDomain({ views })`. The MAP
+  KEY is the view's node slug (`'ui-contact'` → `/<origin>/core/views/ui-contact`).
+  Installs a View
   node whose binding URL = `<serving url><mount>` (managed:
   `https://<slug>.svc.<region>.astrale.ai/ui/contact`). The client/ SPA
   serves `/ui/*` — BOTH adapters ship it (cloudflare via Workers Assets;
@@ -276,12 +292,13 @@ capture when the sender's shape is fixed (see distribution's proxy functions).
 
 ## 7 · Deploy & install
 
-Adapter choice in `astrale.config.ts`:
-- `cloudflare({...})` — your CF account; `dev` (wrangler dev), `prod` (route or
-  workers.dev); ships secrets + SPA assets; extra bindings via a deep-merged
-  `wrangler` block.
-- `astrale({ dev: {...}, prod: { instance: '<slug>' } })` — managed (the
-  scaffold's DEFAULT): publishes
+Adapter choice in `astrale.config.ts` (each adapter is its OWN package — swap
+BOTH the import and the call):
+- `cloudflare({...})` from `@astrale-os/adapter-cloudflare` — your CF account;
+  `dev` (wrangler dev), `prod` (route or workers.dev); ships secrets + SPA
+  assets; extra bindings via a deep-merged `wrangler` block.
+- `astrale({ dev: {...}, prod: { instance: '<slug>' } })` from
+  `@astrale-os/adapter-astrale` — managed (the scaffold's DEFAULT): publishes
   the bundle THROUGH the platform and installs it as a host-local service next
   to your instance (`https://<name>-<hash>.svc.<region>.astrale.ai`). No CF
   account; auth = your `astrale auth login` session. Ships the client SPA
@@ -303,7 +320,7 @@ service URL stable).
 (`/:origin:class.X:seed`; tree paths are rejected) and MUST be idempotent
 (catch path-conflicts). Seed folders, defaults, and demo data here.
 
-Manual install of any served domain: `astrale instance install <url>`.
+Manual install of any served domain: `astrale domain install <url> --direct`.
 
 The managed catalog surface (what `pnpm prod` shells into) is callable
 directly — useful for recovery and inspection:

package/template/.env.example

@@ -4,3 +4,9 @@
 # prod. These files are gitignored — copy this to `.env.dev` and fill in.
 #
 # EXAMPLE_API_KEY=sk-...
+#
+# ── Prober (the example external-API integration) ──────────────────────────
+# The scaffold probes monitor targets with a real, KEYLESS HTTP request by
+# default (no secret needed). These knobs are optional config, not secrets:
+# PROBER=http                # `http` (default) | `mock` (offline/deterministic)
+# PROBE_TIMEOUT_MS=10000

package/template/README.md

@@ -19,20 +19,35 @@ calls), use the `astrale-cli` skill.
 ```bash
 pnpm install
 pnpm dev                          # wrangler dev → prints a local URL
-astrale instance install <url>    # mount it on an instance (CLI)
+astrale domain install <url> --direct    # mount it on an instance (CLI)
 pnpm prod                         # deploy prod → prints a URL
 ```
 
-## What you write (★)
+## What you write
 
 ```
-schema/      ★ classes + interfaces (the data model)
-methods/     ★ the execute() handlers
-views/       ★ iframe-mountable UIs
-functions/   ★ standalone Functions (e.g. the post-install seed)
-astrale.config.ts   identity (origin) · requires · postInstall · adapter
+schema/        classes + interfaces (the data model) + compiled accessors
+core/<context>/ pure, transport-agnostic logic per bounded context (e.g. core/monitor)
+integrations/  external-API ports + adapters + a lazy registry (built into deps)
+runtime/       the execute() handlers — the composition root (the methods map)
+views/         iframe-mountable UIs
+functions/     standalone Functions (e.g. webhooks)
+client/        the SPA served under /ui
+deps.ts        env → typed Deps container (what handlers read as ctx.deps)
+domain.ts      wires it all together — the worker-safe definition
+astrale.config.ts   binds the domain to its deploy adapter (node-only)
 ```
 
+`domain.ts` is the one place everything is declared: it imports the modules
+above and passes them to `defineDomain({ schema, methods, deps, views,
+functions, client, … })` alongside the identity (`origin`, `requires`,
+`postInstall`). Nothing is discovered by folder name — a renamed or mistyped
+module is a compile error at that call, never a silently-missing route. Drop a
+field (`deps`, `views`, `functions`, `client`) when the domain has none.
+`astrale.config.ts` then binds that domain to a deploy adapter with
+`deploy(domain, cloudflare({ … }))` — keeping the node-only adapter (wrangler,
+filesystem) out of the worker bundle.
+
 Everything else — the Worker entry, the wrangler config, the signing identity —
 is generated under `.astrale/` (gitignored) by the adapter. You never edit it.
 
@@ -72,9 +87,9 @@ adapter-owned keys `name`, `main`, `assets`, `routes` are rejected (use
 
 ## The loop
 
-- **Edit a handler** (`methods/`) → hot-reloads at the same URL. Nothing to reinstall.
-- **Edit the schema** (`schema/`) → rebuilds the graph; reinstall with `astrale instance install <url>`.
-- **`postInstall`** (the static `Note.seed` method) runs once after install, as
+- **Edit a handler** (`core/` logic or `runtime/` wiring) → hot-reloads at the same URL. Nothing to reinstall.
+- **Edit the schema** (`schema/`) → rebuilds the graph; reinstall with `astrale domain install <url> --direct`.
+- **`postInstall`** (the static `Monitor.seed` method) runs once after install, as
   the system identity, so the domain can seed itself and set its own grants. It
   must be a class-hosted static addressed by a typed colon-path
   (`/:origin:class.X:seed`) — the kernel refuses tree paths here.

package/template/astrale.config.ts

@@ -1,43 +1,37 @@
 /**
- * astrale.config.ts — the single source of truth for this domain's identity and
- * deployment. `origin` defaults to `schema.domain`; `postInstall` points at the
- * static `Note.seed` method the kernel runs after install (a typed colon-path —
- * the kernel refuses tree paths here, since they can't prove their origin);
- * `adapter` chooses the target.
+ * astrale.config.ts — binds the worker-safe domain (`domain.ts`) to its deploy
+ * adapter for the `astrale-domain` CLI. This is a NODE-only module: it imports
+ * the adapter (wrangler + filesystem). The generated worker never imports this
+ * file — it imports `domain.ts` directly — so the adapter stays out of the bundle.
+ *
+ * This variant deploys to YOUR OWN Cloudflare account (the `cloudflare` adapter).
  *
  *   pnpm dev                       # wrangler dev → prints a local URL
- *   astrale instance install <url> # mount the dev URL on an instance
- *   pnpm prod                      # managed deploy → prints a URL + installs
+ *   astrale domain install <url> --direct # mount the dev URL on an instance
+ *   pnpm prod                      # deploy to your Cloudflare account
  */
-import { astrale } from '@astrale-os/adapter-cloudflare'
-import { defineDomain } from '@astrale-os/devkit'
-// Have your own Cloudflare account and prefer deploying there directly? Swap
-// the adapter — same bundle, shipped with wrangler under YOUR account (then
-// mount it yourself: `astrale instance install <url>`). Extra bindings (KV,
-// R2, D1, queues, …) ride a `wrangler` block on any env (deep-merged):
+import { cloudflare } from '@astrale-os/adapter-cloudflare'
+import { deploy } from '@astrale-os/sdk'
+// No Cloudflare account? Swap the adapter for the Astrale-managed one — it
+// publishes the same bundle THROUGH the platform and installs it on your
+// instance (auth = your `astrale auth login` session):
 //
-//   import { cloudflare } from '@astrale-os/adapter-cloudflare'
-//   adapter: cloudflare({
-//     dev: { secrets: '.env.dev' },              // local wrangler dev, unchanged
-//     prod: { route: 'astrale-domain.example.dev', secrets: '.env.prod' },
-//   }),
+//   import { astrale } from '@astrale-os/adapter-astrale'
+//   export default deploy(domain, astrale({
+//     dev: { secrets: '.env.dev' },               // local wrangler dev, unchanged
+//     prod: { instance: '<your-instance-slug>' }, // pnpm prod → managed deploy
+//   }))
 
-import { schema } from './schema'
+import { domain } from './domain'
 
-export default defineDomain({
-  schema,
-  // origin defaults to `schema.domain`. Set it to another domain's origin to
-  // deliberately alias that identity (you'll get a DANGER prompt at install).
-  postInstall: `/:${schema.domain}:class.Note:seed`,
-  adapter: astrale({
+export default deploy(
+  domain,
+  cloudflare({
     // Local dev: `wrangler dev`. No route → URL is http://localhost:8787.
     dev: { secrets: '.env.dev' },
-    // Managed deploy: `pnpm prod` publishes the bundle through the platform and
-    // installs the domain on this instance — no Cloudflare account needed
-    // (auth = your `astrale auth login` session). The slug comes from
-    // `astrale instance create <slug>` / `astrale instance status`.
-    prod: { instance: 'my-instance-slug' },
-    // Author secrets ship via `secrets: '.env.prod'` on any env (encrypted at
-    // rest platform-side, re-applied on redeploys; omit = keep, `{}` = clear).
+    // Custom-domain prod. Drop `route` to ship to *.workers.dev instead.
+    prod: { route: 'astrale-domain.example.dev', secrets: '.env.prod' },
+    // Author secrets ship via `secrets: '.env.prod'` on any env. Extra bindings
+    // (KV, R2, D1, queues, …) ride a `wrangler` block on any env (deep-merged).
   }),
-})
+)

package/template/client/README.md

@@ -1,46 +1,72 @@
 # astrale-domain-client — SPA for domain views
 
-A small React + Vite SPA that renders the domain's `ui-note` View. It is loaded
-inside an iframe mounted by the Astrale shell, runs the shell handshake to learn
-its target node id and a delegation token, fetches that Note from the kernel,
-and renders its title/body. Built into `../dist-client/` and served by the
-generated worker (`.astrale/`) under `/ui/*` via its `ASSETS` binding.
-
-## Self-contained on purpose
-
-This client depends only on `react`, `react-dom`, `vite`, and
-`@vitejs/plugin-react` — all on public npm. It does **not** import
-`@astrale-os/shell`, `@astrale-os/kernel-client`, or `@astrale-os/ui-components`,
-so the template builds with no registry auth and no workspace `link:`s. Two
-small subsets are reimplemented inline:
-
-- the shell child-handshake (`src/lib/shell.ts`), and
-- a minimal JSON kernel client (`src/lib/kernel.ts`).
+A small React + Vite SPA that renders the domain's Views. It is loaded inside an
+iframe mounted by the Astrale shell, runs the shell handshake (via the real
+`@astrale-os/shell`) to learn its target node id and a kernel session, fetches
+that node from the kernel, and renders it. The bundled `ui-monitor` view loads a
+Monitor and renders its status/url/latency, with a "Check now" button that calls
+the Monitor's `check` instance method and reloads the node. Built into `../.dist/`
+and served by the generated worker (`.astrale/`) under `/ui/*` via its `ASSETS`
+binding.
+
+## Built on the real shell SDK
+
+This client consumes `@astrale-os/shell` for the child handshake AND the kernel
+client: `src/shell/use-shell.ts` boots `createShell({ mode: 'sandboxed' })`, and
+feature hooks call kernel methods through `shell.kernel` (token refresh, codec
+negotiation, redirect following, and delegation are all handled by the SDK — no
+inline wire code). `@` is aliased to `src/` (mirrors `tsconfig` paths), so feature
+code imports `@/shell`, `@/ui`, `@/monitor`.
 
 ## Layout
 
+Feature-first: each feature owns its types/api/mappers/hooks/components. The
+`shell/` and `ui/` folders are the generic, domain-neutral seams every feature
+builds on.
+
 ```
 src/
   main.tsx              # entry → createRoot(App)
-  app.tsx               # the ui-note view (renders the loaded Note)
-  lib/
-    shell.ts            # inline shell child handshake (postMessage + MessagePort)
-    use-shell.ts        # React hook over the handshake (status + live session)
-    kernel.ts           # inline kernel JSON client (kernelCall + prop readers)
-    use-node.ts         # React hook: fetch a node via @<id>::get
-  styles.css            # self-contained styles (no Tailwind)
+  app.tsx               # path router: ROUTES { '/ui/monitor': MonitorView }
+  styles.css            # self-contained styles (no Tailwind), design tokens
+  shell/                # GENERIC kernel/shell adapter on @astrale-os/shell
+    client.ts           #   prop readers (PROP, readProp, readPropBySuffix) + errors
+    invoke.ts           #   callMethod / invokeNode (@<id>::<method>) / nodeAddr
+    use-shell.ts        #   useShell() → createShell({ mode: 'sandboxed' })
+    use-node.ts         #   useNode(session, id) → @<id>::get (+ reload)
+    use-async.ts        #   generic reloadable async resource
+    use-capability.ts   #   write lifecycle (idle → running → done/failed)
+    transformers.ts     #   qualified-prop / link / node-array shaping
+    view-router.tsx     #   resolveView(routes) + ViewFrame (handshake gate)
+    index.ts            #   barrel → @/shell
+  ui/                   # PURE presentation — no kernel, no hooks
+    surface.tsx         #   Panel / ErrorBanner / EmptyState / Spinner
+    badge.tsx           #   StatusBadge (up | down | unknown)
+    value.tsx           #   KV / Mono / ExternalLink
+    format.ts           #   relativeTime
+    index.ts            #   barrel → @/ui
+  monitor/              # THE Monitor feature (template example)
+    monitor.types.ts    #   MonitorRecord
+    monitor.api.ts      #   check(session, id) → @<id>::check
+    monitor.mappers.ts  #   monitorFromNode (node → record)
+    hooks/              #   useMonitor.query / useCheck.mutation
+    components/         #   MonitorCard (container: hooks + @/ui)
+    index.ts            #   barrel → @/monitor
+  views/
+    monitor.tsx         #   MonitorView = <ViewFrame>…<MonitorCard/></ViewFrame>
 __tests__/
-  harness.ts            # fake shell parent + fake kernel (fetch stub)
-  app.test.tsx          # handshake → render → setTarget → tokenRefresh
-  kernel.test.ts        # kernelCall wire shape + prop readers
+  harness.ts            # fake shell parent (real protocol) + fake kernel (fetch stub)
+  app.test.tsx          # handshake → render → check now → setTarget → fallback
+  seam.test.tsx         # pure @/ui + @/monitor hooks in isolation (no handshake)
+  kernel.test.ts        # pure helpers: prop readers, mapper, relativeTime
 ```
 
 ## Dev loops
 
 ```bash
-pnpm dev       # vite build --watch → ../dist-client/ (worker auto-reloads, no HMR)
+pnpm dev       # vite build --watch → ../.dist/ (worker auto-reloads, no HMR)
 pnpm dev:hmr   # vite dev on http://127.0.0.1:5173/ (React fast-refresh)
-pnpm test      # vitest run (happy-dom; fake parent + fake kernel, JSON-only)
+pnpm test      # vitest run (happy-dom; fake parent speaks the real shell protocol)
 ```
 
 For HMR, set `VIEW_DEV_URL=http://127.0.0.1:5173` in the worker's `.dev.vars`;
@@ -48,38 +74,29 @@ the generated worker forwards `/ui/*` to vite.
 
 ## How it connects
 
-1. The domain declares the View in `../views/note.ts` with `mount: '/ui/note'`.
-   The SDK points the View node's iframe at `<serving url>/ui/note`.
-2. The shell mounts that iframe and completes the handshake: it transfers a
-   `MessagePort` and sends a `ctrl:handshake` carrying `kernelUrl`, a
-   `delegationToken` (+ `tokenExpiresAt`), and the `targetNodeId`. `useShell()`
-   surfaces a live session and tracks `setTarget` hot-swaps.
-3. `useNode(session, nodeId)` POSTs `@<id>::get` to `kernelUrl` with the
-   delegation token as `authorization` and renders the Note's `title`/`body`
-   (props are read by key suffix, since the domain origin is unknown at build
-   time). The iframe authenticates with the handshake token ONLY — the parent
-   minted it for this kernel, so the audience already matches (no cookie, no
-   whoami, no client-side minting).
-
-### Token refresh
-
-The parent pushes a fresh credential over the port as `ctrl:tokenRefresh`
-before the current one expires. `shell.ts` swaps it into a mutable `currentToken`
-so the next `kernelCall` (e.g. on the next `setTarget` or remount) uses it —
-`getToken()` always returns the live token, never the one captured at handshake.
-
-## Deferred — kept minimal on purpose
-
-The inline kernel client is **JSON-only** and read-only for this template:
-
-- no msgpack codec (the `application/vnd.astrale.kernel+msgpack` body),
-- no streaming (`output: 'stream'`) or binary (`output: 'binary'`) responses,
-- no redirect following — a `{ redirect }` envelope (remote-domain Functions)
-  throws rather than re-minting against the target worker,
-- no client-side credential minting / `whoami` (the handshake token is used
-  as-is), and
-- no writes — only `@<id>::get`.
-
-These all live in `@astrale-os/kernel-client` / `@astrale-os/shell`. To grow
-past the template, pull those in (and `link:` them in dev) instead of extending
-the inline subset.
+1. The domain declares each View in `../views/` with `mount: '/ui/<path>'`. The
+   SDK points the View node's iframe at `<serving url>/ui/<path>`.
+2. The shell mounts that iframe and completes the handshake (a transferred
+   `MessagePort` + a `ctrl:handshake` carrying `kernelUrl`, the delegation token,
+   and the `targetNodeId`). `useShell()` boots `@astrale-os/shell`, surfaces the
+   kernel session, and tracks `setTarget` hot-swaps.
+3. A feature loads its node through the session: `useNode(session, nodeId)` calls
+   `@<id>::get` over `shell.kernel`, and a mapper (`monitorFromNode`) projects it
+   to a typed record. Domain props are read by key SUFFIX (`.property.url`, …)
+   because the domain origin is unknown at build time; the name uses the kernel
+   `Named.name` key.
+4. Writes go through `useCapability`: "Check now" runs `@<id>::check`, then calls
+   `useMonitor`'s `reload()` so the fresh status/latency re-render. The shell's
+   kernel client owns the credential and refreshes it before expiry — features
+   never touch the token.
+
+## Adding a view
+
+1. Write a `ViewComponent` (usually wrapping `ViewFrame`) under `src/views/`.
+2. Add a `ROUTES` entry keyed by its mount path in `src/app.tsx`.
+3. Register a matching `defineView({ mount: '/ui/<path>' })` in the domain's
+   `views/` so the shell mounts an iframe there.
+
+For a NEW feature, mirror `src/monitor/`: a `*.types.ts`, `*.api.ts`,
+`*.mappers.ts`, a `hooks/` folder of `.query`/`.mutation` hooks, and a
+`components/` folder of containers that compose `@/ui`.