@zerotal/arch 1.7.0 → 1.7.3

package/CHANGELOG.md

@@ -7,6 +7,63 @@ All notable changes to this package are documented here. The format is
 **Maturity: beta.** The API is close to final and breaking changes are rare, called out
 here with migration steps — but a minor release may still contain one.
 
+## [Unreleased]
+
+## [1.7.1] — 2026-08-16
+
+### Fixed
+
+Faults that only appear once the surface is installed into a real app, found by installing
+it into this repo's own `apps/docs` and calling every tool.
+
+- **`search_docs` ranked a generated page above the right answer.** Scoring was raw term
+  frequency weighted by field, with no length normalisation — so `components.md`, one
+  generated page covering 53 components and long enough to mention nearly everything, came
+  first for both "send an email" and "how do I write a test for a controller". Now BM25 over
+  a small inverted index built when the corpus is read: length normalisation, inverse
+  document frequency and term saturation, with title/description/heading matches scored as
+  separate fields _outside_ the saturation, since folded in BM25 flattens a title hit to
+  about twice a passing mention. Plus light stemming, so "test" meets "testing", and
+  hyphenated terms indexed whole and in parts, so "soft deletes" finds `soft-delete`.
+
+  Measured on fourteen questions an agent would actually ask, top-1 relevance went from
+  roughly three in ten to twelve in fourteen. The remaining two return related pages rather
+  than the best one; tuning further against a list that size fits the list, not the corpus.
+
+- **`last_error` dropped the error.** The framework logs an exception's class in `error`,
+  its trace in `stack` and the request it belongs to in `requestId`. The parser named the
+  six fields it knew about and discarded the rest, so the tool whose entire job is saying
+  _why_ something failed returned the generic `"Unhandled error"` that wraps the real one —
+  a line that says nothing. Entries now carry every field the logger wrote, and
+  `last_error` renders the exception, the request id and the trace. `logs` shows the first
+  two but not the trace: a stack on each of two hundred entries buries the sequence the
+  caller asked for.
+
+- **`baselines` reported a ceiling smaller than the command's count, without saying so.**
+  The cast baseline ratchets per file and exempts designated boundary modules, so it reads
+  455 where `cast:check` prints 466. A reader comparing the two saw debt that had appeared
+  between them. The reading now carries a `note` naming the exempt modules.
+
+- **Packages in a workspace were invisible.** `node_modules/@zerotal/*` is a symlink in
+  every workspace — this monorepo, `bun link`, any app developed against a checkout — and
+  `Bun.Glob` will not descend into one, `followSymlinks` or not. `installedPackages()`
+  returned nothing for an app with seventeen packages, so `app_info` reported an empty list
+  and `arch:install` wrote generic guidance with none of the per-package sections that are
+  the reason it is composed rather than canned. Listed with `readdir` now, which sees the
+  link, and read through `Bun.file`, which follows it.
+
+- **The generated Markdown failed the formatter.** `arch:install` wrote files that did not
+  pass the `prettier --check .` the project it had just installed into already runs. The
+  markers now sit on their own lines with blank lines around them — which is correctness
+  before it is formatting, since Markdown parses text pressed against an HTML comment as
+  part of that raw-HTML block.
+
+- **`arch:update` fought the formatter over `.mcp.json`.** `JSON.stringify(…, 2)` expands a
+  one-element array where a formatter collapses it, so the command rewrote a file it had no
+  change to make to, and the next `prettier --write` put it back. Idempotence is now
+  measured on the parsed data: when the config already says what it should, the file is
+  returned exactly as it was found, in whatever shape its owner keeps it.
+
 ## [1.7.0] — 2026-08-16
 
 ### Added

package/docs/about.md

@@ -43,7 +43,7 @@ a theme.
 
 ### 1. Bun-native, source-only
 
-Zerotal runs **only on Bun** (≥ 1.1) and leans on Bun's APIs throughout — `Bun.sql`
+Zerotal runs **only on Bun** (≥ 1.3.14) and leans on Bun's APIs throughout — `Bun.sql`
 for the database, `Bun.CryptoHasher` for hashing, `Bun.build` for bundling. Because
 Bun runs and type-strips TypeScript natively, packages ship as **`.ts` source with no
 compiled `dist/`**. You always read real source and get accurate types; there's
@@ -660,9 +660,9 @@ The [README](../README.md) has a package-by-package table with links.
   scaffolding, migrations, the dev server, the worker, and tests all run through it.
 - **No build, ever.** `bun run dev` / `bun test` / `bun run typecheck`. No compile
   step to remember.
-- **Reference apps are the best teacher.** Full working apps under `apps/` exercise the
-  framework end-to-end — a Flow-based finance app and a Flow + Auth + ORM starter
-  are the most complete real-world examples. Read them alongside the docs.
+- **Starters are the fastest way in.** `bun create zerotal my-app` scaffolds a working
+  app from one of six starters — `api`, `admin`, `flow`, `react`, `vue`, or `minimal`.
+  Read the generated code alongside the docs.
 - **Conventions are documented, not magic.** When something "just works" (a model you
   never registered, a policy suddenly enforced), [Conventions](/docs/conventions)
   explains exactly what the framework discovered and why.

package/docs/broadcasting/channels.md

@@ -122,7 +122,7 @@ the wire; a Pusher-protocol client surfaces them to your code under the `pusher:
 
 > **Note** — The native `ws`/`redis` drivers use the equivalent
 > `subscription_succeeded` / `presence:member_added` / `presence:member_removed` events; the
-> first-party `Socket` client maps them to Echo's `here`/`joining`/`leaving` callbacks for you.
+> first-party `Socket` client maps them to Socket's `here`/`joining`/`leaving` callbacks for you.
 
 ## Typed channels
 

package/docs/broadcasting/client.md

@@ -9,8 +9,20 @@ description: Subscribe from the browser and react to events as they arrive.
 
 `@zerotal/client` ships a small, dependency-free `Socket` that speaks the native broadcast
 protocol and exposes a familiar realtime-client API — no external client library, and it works
-with the lightweight `ws` and `redis` drivers (no Pusher credentials needed). It's also a drop-in
-for `window.Echo`, so Flow's [`@on('echo:…')`](/docs/flow/events) listeners work against it.
+with the lightweight `ws` and `redis` drivers (no Pusher credentials needed).
+
+**Flow apps need none of this.** The client is bundled into `/__flow/runtime.js` and created the
+first time a page declares a [`@on('socket:…')`](/docs/flow/events) listener, so those listeners
+are live with no script of your own. Read on only if you want a configured client — a different
+host, your own auth endpoint — or if you are subscribing from code that is not a Flow component.
+
+> **The package root is fine to import in browser code.** It used to be a bundle error: the root
+> also exports `ClientProvider`, which reaches the CLI commands and `await import("bun")`, and a
+> browser bundler rejects that during resolution — before tree-shaking can discard the half you
+> did not want. `@zerotal/client` now resolves to a browser-safe entry under the `browser`
+> condition, so a bundler gets `Socket`, `ApiClient` and `CircuitBreaker` and none of the
+> server-side exports. `@zerotal/client/Socket` still works and is still the leanest import if
+> `Socket` is all you need.
 
 ```ts
 // in your client code
@@ -34,8 +46,9 @@ socket
   .leaving((m) => removeOnline(m))
   .listen("Message", (e) => append(e));
 
-// Use it as Echo for Flow @on('echo:…') listeners:
-window.Echo = socket;
+// Only if you need Flow's listeners to use *this* client rather than the bundled
+// one — assign before the runtime loads and it is used as-is:
+window.Socket = socket;
 ```
 
 Private and presence channels are authorized with a **per-subscription HMAC signature** (the same

package/docs/broadcasting/events.md

@@ -64,7 +64,7 @@ Broadcast.send(new OrderShipmentStatusUpdated(order));
 ```
 
 `broadcast(event).toOthers()` excludes the connection that triggered the request (read from the
-`X-Socket-ID` header your Echo client sends), so the user who just made an optimistic UI update
+`X-Socket-ID` header your Socket client sends), so the user who just made an optimistic UI update
 doesn't receive a duplicate.
 
 `broadcast()` returns a `PendingBroadcast` — a thenable that sends itself on the next
@@ -181,7 +181,7 @@ The wire event name defaults to `${ModelName}${Event}` (e.g. `OrderUpdated`) and
 
 ```ts
 // in your client code
-Echo.private(`orders.${id}`).listen("OrderUpdated", (e) => render(e.order));
+Socket.private(`orders.${id}`).listen("OrderUpdated", (e) => render(e.order));
 ```
 
 ## Next steps

package/docs/broadcasting/index.md

@@ -50,7 +50,7 @@ The provider exposes one HTTP route and one WebSocket upgrade path:
 
 - `POST /broadcasting/auth` — the private/presence channel auth endpoint (a real `Router` route).
 - The WebSocket upgrade is served at the configured `path` (default `/app/ws`) via Bun's
-  WebSocket handler — it is _not_ a separate `Router` route. Pusher/Echo clients connect to
+  WebSocket handler — it is _not_ a separate `Router` route. Pusher/Socket clients connect to
   `ws://host/app/{appKey}`.
 
 ## Configuration

package/docs/changelog.md

@@ -17,12 +17,114 @@ summary across the suite.
 Each version lists changes under three headings:
 
 - **Added** — new features and APIs (safe to adopt incrementally).
-- **Changed** — behavior changes; **breaking** ones are called out explicitly and
-  appear only in major releases.
+- **Changed** — behavior changes; **breaking** ones are called out explicitly, in
+  bold, as **BREAKING**.
 - **Fixed** — bug fixes.
 
-Patch and minor releases are backward compatible. Before taking a **major** release,
-read its section here and apply each migration note.
+Breaking changes belong in major releases, and while the 1.x line is young they may
+also land in a minor or a patch — always labelled, always with migration steps. Read
+the section for every version you cross and apply its migration notes, not only the
+majors. [Releases and versioning](/docs/support-policy#releases-and-versioning) explains
+when that carve-out ends.
+
+## 1.7.3 — 2026-08-20
+
+Two fields that accepted input and threw it away, and a CI job that was testing nothing.
+
+### Fixed
+
+- **A boolean column could not hold a boolean on PostgreSQL.** `table.boolean()` compiled to
+  `INTEGER` on every engine — right for SQLite, which has no boolean type, and rejected by
+  PostgreSQL, which has a real one:
+
+  ```text
+  column "active" is of type integer but expression is of type boolean   (42804)
+  ```
+
+  Every insert of `true` failed, and so did every `where("active", true)`. The storage type
+  now comes from the dialect, as the auto-increment column already did. SQLite and MySQL are
+  unchanged — MySQL's `BOOLEAN` is a synonym for `TINYINT(1)` and `INTEGER` takes 0/1 either
+  way, so there was nothing broken there to fix.
+
+  **Existing PostgreSQL tables keep their integer columns.** New tables get `BOOLEAN`; a table
+  already created needs an `ALTER` if you want the column converted:
+
+  ```sql
+  ALTER TABLE posts ALTER COLUMN active TYPE boolean USING active <> 0;
+  ```
+
+- **A bound password field discarded every keystroke.** Flow's client-writable set was
+  `fillable` minus `hidden`, which conflates two allow-lists answering different questions:
+  `fillable` governs what may be _written_, `hidden` governs what may be _shown_. A password
+  is in both, so subtracting made it unwritable — `<input type="password"
+value={this.user.password} blur />` accepted typing and dropped it on arrival.
+
+  `hidden` is no longer subtracted. It is still never sent: the stored hash does not leave the
+  server and the field arrives empty. A hidden value **the client supplied** survives until
+  save; one **the server produced** is never echoed back, and a half-typed one is stripped
+  from the durable snapshot before it is persisted.
+
+### Changed
+
+- **The PostgreSQL CI job blocks merges.** It had been running the ORM suite beside a Postgres
+  container without connecting to it, so it reported success without testing anything. A smoke
+  suite now exercises schema DDL, identity columns, CRUD, type round-trips, row locks and
+  transaction rollback against a real PostgreSQL 16, and a failure fails the build. The
+  boolean defect above is what it found on its first real run.
+
+### Documented
+
+- **Flow pages take their model from the route, not from a query.** The docs opened every
+  model example by fetching the record in `onMount()`, which predates a route being able to
+  hand a component the record. `models.md` leads with the bound form; `lifecycle.md` no longer
+  presents the old id-plus-`onHydrate`-re-query as the correct pattern. The old shape still
+  works — it is simply two fields and a query doing what one field now does.
+
+## 1.7.2 — 2026-08-18
+
+Realtime that works without being wired up, and three ways a socket could go quiet without
+saying so.
+
+### Changed
+
+- **BREAKING — Flow's `@on` broadcast listeners use a `socket:` prefix.** `echo:`,
+  `echo-private:` and `echo-presence:` are now `socket:`, `socket-private:` and
+  `socket-presence:`; the browser global is `window.Socket`, not `window.Echo`. There is no
+  alias — an unrenamed listener never matches, and never subscribes.
+
+  ```diff
+  - @on("echo-private:issues.5,CommentPosted")
+  + @on("socket-private:issues.5,CommentPosted")
+  ```
+
+  Shipped in a patch release deliberately, on the judgement that the old prefix has no
+  meaningful use in the wild. If you are on it, the upgrade is a find-and-replace of `echo:`
+  → `socket:` in your `@on` listeners and `window.Echo` → `window.Socket` in any client code.
+
+### Added
+
+- **Flow bundles the socket client into its runtime.** A page that declares a `socket:`
+  listener is live with no script of your own. Flow apps own no bundle entry, so the contract
+  used to be "publish `window.Socket` yourself" — and when you didn't, the listeners were
+  _silently inert_: no error, no warning, no subscription, so a live feature with no script
+  looked exactly like a live feature that was never written. An app that needs a configured
+  client still assigns `window.Socket` before the runtime loads and that one is used as-is; a
+  page with no listeners opens no connection at all.
+
+### Fixed
+
+- **A patch no longer writes back into a file input.** A file input's `value` belongs to the
+  user agent, and assigning anything but `""` throws `InvalidStateError`. The write was legal
+  while the bound property was empty and threw on the very patch carrying an upload's result
+  — and the throw escaped the frame handler, so the DOM never updated _and_ the action's ack
+  never resolved. Since frames are chained per component, every later action queued behind a
+  promise that would never settle: the page rendered correctly and ignored every click for
+  the rest of its life.
+
+- **WebSocket connections get an explicit 120s `idleTimeout`.** Bun closes an idle socket
+  after 10 seconds; the client pings every 30. A connection that was merely quiet got cut
+  before it had reason to speak, taking its channel subscriptions with it — so anyone who had
+  been reading a page for more than ten seconds silently stopped receiving broadcasts.
 
 ## 1.7.0 — 2026-08-16
 

package/docs/commands.md

@@ -210,23 +210,32 @@ running, restarting, or has given up:
 ─────────────────────────────────────────────────
  GET / 200 4ms
  GET /posts 200 11ms
- 1-9 tab · ←/→ cycle · r restart · c clear · / search · t time · s stream · q quit
+ 1-9 tab · ←/→ cycle · ↑/↓ scroll · r restart · c clear · / search · t time · s stream · q quit
 ```
 
-| Key           | Does                                                             |
-| ------------- | ---------------------------------------------------------------- |
-| `1`–`9`       | Select that tab                                                  |
-| `←` `→` `Tab` | Cycle through tabs                                               |
-| `r`           | Restart the focused process                                      |
-| `c`           | Clear the focused tab's output                                   |
-| `/`           | Search within the focused tab (`Enter` keeps it, `Esc` drops it) |
-| `t`           | Toggle per-line timestamps                                       |
-| `s`           | Switch to stream mode                                            |
-| `PgUp` `PgDn` | Scroll the focused tab                                           |
-| `q`           | Quit — stops every process and restores your shell               |
+| Key           | Does                                                              |
+| ------------- | ----------------------------------------------------------------- |
+| `1`–`9`       | Select that tab                                                   |
+| `←` `→` `Tab` | Cycle through tabs                                                |
+| `↑` `↓`       | Scroll the focused tab a line at a time — as does the mouse wheel |
+| `PgUp` `PgDn` | Scroll it a screen at a time                                      |
+| `Home` `End`  | Jump to the oldest line, or back to the newest                    |
+| `r`           | Restart the focused process                                       |
+| `c`           | Clear the focused tab's output                                    |
+| `/`           | Search within the focused tab (`Enter` keeps it, `Esc` drops it)  |
+| `t`           | Toggle per-line timestamps                                        |
+| `s`           | Switch to stream mode                                             |
+| `q`           | Quit — stops every process and restores your shell                |
 
 Scrollback belongs to the deck rather than to your terminal, which is what makes
 per-tab history and search possible. It keeps the last 5,000 lines per process.
+Your terminal's own scrollbar does nothing while the deck is up — it has no
+history to move, because the deck holds it all. Use the keys above (or the
+wheel, which the terminal sends the deck as `↑`/`↓`).
+
+Scrolling up parks the view where you left it: the process behind the tab keeps
+printing, but what you stopped to read stays on screen until you scroll back
+down to the newest line.
 
 **A process that dies never takes the server with it.** It restarts on its own —
 three times, backing off between attempts — and if it still will not start, that

package/docs/contributing.md

@@ -8,7 +8,7 @@ description: Get the Zerotal monorepo running locally and pass the checks your c
 Zerotal is a Bun-native monorepo of composable packages. This guide covers getting the
 repo running locally, the project layout, and the checks your change needs to pass.
 
-> **Warning** — Bun ≥ 1.1 is required. Node.js is not supported; Zerotal uses `Bun.sql`, `Bun.CryptoHasher`, `Bun.build`, and other Bun-native APIs throughout.
+> **Warning** — Bun ≥ 1.3.14 is required. Node.js is not supported; Zerotal uses `Bun.sql`, `Bun.CryptoHasher`, `Bun.build`, and other Bun-native APIs throughout.
 
 ## Getting set up
 
@@ -32,7 +32,7 @@ packages/        # the framework — one directory per @zerotal/* package
   auth/  cache/  queue/  …  # feature packages
   testing/       #   factories, fakes, test app harness
   create-zerotal/ #   the `bun create zerotal` scaffolder
-apps/            # example apps used for end-to-end testing and the docs site
+apps/            # applications in this workspace
   docs/          #   this documentation site
 docs/            # the markdown documentation (what you're reading)
 ```

package/docs/errors.md

@@ -77,6 +77,28 @@ The full set exported from `zerotal`:
 > and `ServiceUnavailableError(reason, retryAfter)` populate the `Allow` and
 > `Retry-After` response headers for you when you pass those arguments.
 
+## Errors the framework raises
+
+The errors above are the ones you throw. These the framework throws at you, and
+each is written to name the fix rather than only the symptom. Most surface at
+boot, before a request is ever served:
+
+| Class                        | `code`                       | Raised when                                                                                                                              |
+| ---------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `BootCheckError`             | `E_BOOT_CHECK_FAILED`        | The boot-time doctor found one or more wiring problems.                                                                                  |
+| `ConfigValidationError`      | `E_CONFIG_VALIDATION_FAILED` | Config validation refused a production boot, listing every fatal issue by namespace.                                                     |
+| `FacadeBindingMissingError`  | `E_FACADE_BEFORE_BOOT`       | A facade was used after boot but nothing provides its binding — almost always a `ServiceProvider` missing from `bootstrap/providers.ts`. |
+| `ContextOutsideRequestError` | `E_CONTEXT_OUTSIDE_REQUEST`  | `RequestContext` was read with no request in scope, such as from module-level code or a background task. Renders as a 500.               |
+
+`BootCheckError` carries the whole list rather than the first failure it hit. Its
+`failures` array holds one `BootCheckFailure` per culprit — the `token`, the
+`provider` that declared it in `static provides`, and the `reason` — so a single
+restart tells you everything there is to fix.
+
+These four are not re-exported from `zerotal`, because throwing them yourself is
+not the point. Catch one by class from `@zerotal/core/errors`, or match on `code`
+the way you would any other framework error.
+
 ## Custom exception classes
 
 Extend `ZerotalError` for domain errors, or `HttpError` for HTTP errors. The

package/docs/flow/components.md

@@ -29,6 +29,13 @@ import { Link } from "@zerotal/flow";
   Posts
 </Link>;
 
+{
+  /* Prefetch on pointer-down instead — for a row in a long list */
+}
+<Link href="/posts/42" down>
+  One post
+</Link>;
+
 {
   /* Disable automatic data-current (e.g. always-active home links) */
 }
@@ -37,6 +44,14 @@ import { Link } from "@zerotal/flow";
 </Link>;
 ```
 
+Choose between `hover` and `down` by how many of the link there are. `hover` prefetches after a
+short dwell, which is free speed on a handful of stable links — a navigation rail, a breadcrumb.
+On a dense list it inverts: the pointer crosses every row between where it is and where it is
+going, so scrolling a hundred-row table asks the server for a hundred pages nobody chose. `down`
+fires on `pointerdown` instead — once, on the link the reader has committed to, and still ahead
+of the click by however long the button is held. Both may be set; the target is fetched once and
+cached either way.
+
 `data-current` matches by **prefix** — a link to `/posts` stays active on `/posts/42` — which is what you want for a section parent. For an index link that should be active only on its own exact URL (an "Overview" tab that shouldn't light up on the section's sub-pages), add `exact`:
 
 ```tsx
@@ -456,6 +471,14 @@ import { Tabs } from "@zerotal/flow";
 
 `<Tabs>` emits `role="tablist"` / `"tab"` / `"tabpanel"` with roving arrow-key navigation.
 
+> **Note** — selection is client-only and not addressable. The active tab lives in Alpine state,
+> always starts on the first item, and there is no prop to bind or read it, so `?tab=settings`
+> cannot be made to work and the back button does not step between panels. The tab strip's own
+> classes are fixed (`border-gray-800`, `text-white`, `border-indigo-500`); only the outer wrapper
+> takes `class`, so on a light surface the selected tab is white on white. For a tab set that has
+> to be linkable or has to match a design system, drive the panels from a `@url` property and
+> write the strip out — it is a dozen lines, and you keep both.
+
 ## File upload component
 
 ### FileUpload + FileUploads mixin
@@ -466,25 +489,21 @@ A dropzone bound to an `@expose` property. Choosing a file POSTs the bytes to `/
 import { Component, expose, FileUpload, FileUploads, TemporaryUploadedFile } from "@zerotal/flow";
 
 export class AvatarPage extends Component.using(FileUploads) {
+  @locked user!: User; // /users/:user/avatar — the record, already found
   @expose photo: TemporaryUploadedFile | null = null;
-  @locked photoUrl: string = "";
-
-  override async onMount() {
-    const user = await User.find(this.userId);
-    this.photoUrl = user?.avatarUrl ?? "";
-  }
 
   @expose async save(): Promise<void> {
     if (!this.photo) return;
     const path = await this.photo.store("avatars"); // moves to permanent storage
-    await User.query().where("id", this.userId).update({ avatarUrl: path });
+    this.user.avatarUrl = path;
+    await this.user.save();
     this.flash("Avatar updated.", "success");
   }
 
   override async render() {
     return (
       <div class="space-y-4">
-        {this.photoUrl && <img src={this.photoUrl} class="h-24 w-24 rounded-full" />}
+        {this.user.avatarUrl && <img src={this.user.avatarUrl} class="h-24 w-24 rounded-full" />}
 
         <FileUpload bind={this.photo} accept="image/*" maxSize="5mb" />
 

package/docs/flow/decorators.md

@@ -42,18 +42,19 @@ Only `@expose` properties are two-way: the client can push updates back to the s
 
 Sent to the client for display, but the client cannot mutate it. Included in the snapshot so it survives WebSocket round-trips without re-loading from the database.
 
+An ORM model is the exception: only its id travels in the snapshot and the row is re-read on every round-trip, so what the page shows is always current. See [Models in Components](/docs/flow/models).
+
 A `value={this.x}` binding on a `@locked` property renders as a read-only display — not an editable field.
 
-Use `@locked` for data loaded in `onMount()` that the server controls: model results, user info, computed totals, child props from the parent:
+Use `@locked` for anything the server owns: a record the route resolved, results loaded in `onMount()`, computed totals, child props from the parent:
 
 ```tsx
 export class PostsPage extends Component {
+  @locked user!: User; // /users/:user — the record, already found
   @locked posts: Post[] = [];
-  @locked user: User | null = null;
   @locked total: number = 0;
 
   override async onMount() {
-    this.user = await User.findOrFail(this.userId);
     this.posts = await Post.query()
       .where("user_id", this.user.id)
       .where("status", "published")
@@ -65,7 +66,7 @@ export class PostsPage extends Component {
   override async render() {
     return (
       <div>
-        <h1>Posts by {this.user?.name}</h1>
+        <h1>Posts by {this.user.name}</h1>
         <p>{this.total} posts</p>
         <ul>
           {this.posts.map((p) => (
@@ -133,9 +134,13 @@ You can also pass rules directly to `this.validate()` — they override the deco
 
 ### Real-time validation
 
-When a `@validate` field is bound with `flow:model.live` (or `.blur`), each change is validated on
+When a `@validate` field is bound `live` (or `blur`), each change is validated on
 the server as it arrives. The field's error appears (and clears)
-as the user edits, with no action call and without affecting any other field:
+as the user edits, with no action call and without affecting any other field.
+
+> **Note** — `live` is the prop you write; `flow:model.live` is what it compiles to. The compiled
+> form is not writable in TSX: the `.` in an attribute name is a parse error (`TS1003`), so
+> copying it out of the emitted HTML into a component will not build.
 
 ```tsx
 @expose @validate((rule) => rule.required().email()) email = "";
@@ -143,7 +148,7 @@ as the user edits, with no action call and without affecting any other field:
 async render() {
   return (
     <div>
-      <input type="email" value={this.email} flow:model.live />
+      <input type="email" value={this.email} live />
       <span error={this.errors.email} />
     </div>
   );
@@ -265,7 +270,8 @@ An `@expose`d method that runs on the server but **skips the re-render cycle**.
 }
 
 @expose @renderless async archivePost(): Promise<void> {
-  await Post.where("id", this.postId).update({ status: "archived" });
+  this.post.status = "archived"; // this.post came from the route
+  await this.post.save();
   this.redirect("/posts");
 }
 ```
@@ -289,13 +295,22 @@ async refreshUser(data: { userId: number }): Promise<void> {
 }
 
 // Listen for real-time WebSocket broadcasts (see Events doc for channel formats)
-@on("echo:orders,OrderPlaced")
+@on("socket:orders,OrderPlaced")
 async onOrderPlaced(payload: { id: number }): Promise<void> {
   this.orderCount++;
   this.flash("New order received!", "success");
 }
+
+// A channel naming a record needs a resolver — the string form is read off the
+// class, so `"socket:orders.${this.id},…"` would subscribe to that literal text.
+@on((self) => `socket-private:orders.${self.orderId},OrderCancelled`)
+async onOrderCancelled(payload: { id: number }): Promise<void> {
+  this.orderCount--;
+}
 ```
 
+Both forms are a `ListenerName`: the event string itself, or a resolver handed the component instance that returns one.
+
 See [Events & Broadcasting](/docs/flow/events) for dispatch methods, targeting, broadcasting, and native event integration.
 
 ## The @reactive decorator
@@ -385,7 +400,8 @@ See [Layouts & Composition](/docs/flow/layouts#two-way-props) for the full `@mod
 | `@expose method`                                | Callable from the browser via WebSocket                               |
 | `@expose @renderless method`                    | Callable from browser; skips re-render cycle                          |
 | `@on("event") method`                           | Listens for cross-component events (auto-exposed)                     |
-| `@on("echo:channel,Event") method`              | Listens for real-time server broadcasts                               |
+| `@on("socket:channel,Event") method`            | Listens for real-time server broadcasts                               |
+| `@on((self) => "socket:…") method`              | Same, with the channel resolved per instance (record ids)             |
 | `@reactive prop`                                | Child prop; parent re-pushes on change, child re-renders              |
 | `@modelable prop`                               | Two-way child prop; writes from child flow back to parent             |
 
@@ -409,13 +425,13 @@ this.redirectIntended("/dashboard"); // back to where AuthMiddleware intercepted
 // Force onMount() to re-run this round-trip (useful for reloading stale data)
 this.refresh();
 
-// Update the document title in the browser tab
-this.title("Edit post — My App");
+// The document title is `static title` on the class, not an action — see Routing.
 
-// Run raw JavaScript in the browser after the DOM patch is applied
-this.client("$refs.titleInput.focus()");
-this.client("window.scrollTo({ top: 0, behavior: 'smooth' })");
-this.client(`$dispatch('toast', { message: 'Done!' })`);
+// Run JavaScript in the browser after the DOM patch is applied. `$` is a tagged
+// template, so interpolated values are encoded for you.
+this.$`$refs.titleInput.focus()`;
+this.$`window.scrollTo({ top: 0, behavior: 'smooth' })`;
+this.$`$dispatch('toast', { message: ${this.message} })`;
 
 // Trigger a file download in the browser
 this.download("report.csv", csvContent, "text/csv;charset=utf-8");