letmeknow-cli 0.6.1 → 0.8.0

package/README.md

@@ -1,98 +1,53 @@
 # LetMeKnow
 
-LetMeKnow gives an agent a temporary public browser surface and structured human feedback. The agent edits an ordinary folder, explicitly publishes coherent revisions, and pulls form submissions as JSON. The CLI connects outbound to the hosted relay and does not listen on a network port.
+LetMeKnow gives an agent a temporary public browser surface for structured human feedback. The agent serves ordinary HTML and static assets, receives browser submissions, and can push ordered HTML replacements.
 
-## Start a session
+## Quick start
 
-Node.js 22.12 or newer is required. Create a dedicated directory containing only public files, then keep the server running:
+Create a directory with an `index.html`, then run:
 
 ```bash
 npx letmeknow-cli serve ./preview
 ```
 
-The server prints one JSON line containing the public bearer URL and initial workspace revision:
+The CLI prints one JSON line containing the public bearer URL:
 
 ```json
-{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/","workspace":"…","workspace_sequence":1}
+{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/","page_event":0,"page_hash":"…"}
 ```
 
-Anyone with the URL can view the published workspace and submit its forms. A graceful stop closes the session; an unexpected relay disconnect can reconnect for up to ten minutes. Diagnostics go to stderr.
+Give the URL to the human. Anyone with the URL can view the page and submit its forms.
 
-## Publish revisions
+## Commands
 
-`serve` snapshots the initial folder. Later filesystem changes remain private until explicitly published:
-
-```bash
-npx letmeknow-cli pull ./preview --wait 30
-npx letmeknow-cli push ./preview --based-on <batch-token>
-```
-
-`pull` returns pending browser interactions, the current workspace, and an opaque batch token:
-
-```json
-{
-  "ok": true,
-  "type": "batch",
-  "token": "…",
-  "workspace": "…",
-  "workspace_sequence": 1,
-  "frontier": 1,
-  "events": [
-    {
-      "type": "submit",
-      "id": "…",
-      "form_id": "decision",
-      "values": {"decision":"approve"},
-      "based_on": "…",
-      "context": {"based_on":"…","current":"…","relationship":"current"}
-    }
-  ]
-}
+```text
+serve <dir>
+show <dir>
+pull <dir> [--wait seconds]
+push <dir> --batch TOKEN [--updates FILE|-]
 ```
 
-A repeated pull returns uncommitted events again. `push` atomically snapshots the folder, commits the batch, and reloads connected browsers once. Events arriving while the agent works remain for the next pull. A push can also publish independent work from an empty batch.
-
-If a batch requires no workspace change, commit it without publishing:
-
-```bash
-npx letmeknow-cli ack ./preview --based-on <batch-token>
-```
+`serve` reads `index.html` once as the canonical page. Other files are served live from the directory. `show` prints the accepted canonical HTML. `pull` returns browser events without consuming them; `push` commits a pulled batch, optionally with ordered replacements. See [`SKILL.md`](SKILL.md) for the complete workflow and protocol.
 
-`push` and `ack` are idempotent for a token. They fail if another command has moved the workspace or event cursor first.
+## Page updates
 
-The commands communicate with `serve` through a private local Unix socket. `--skill` prints agent instructions without starting a session.
-
-## Workspace behavior
-
-A published workspace is an immutable temporary snapshot of the selected folder. It may contain HTML, CSS, JavaScript, images, data, and linked pages. The relay injects a small runtime into HTML and serves all files from the same workspace revision.
-
-A successful push sends one revision notification. Browsers reload and preserve scroll position plus the values, checked state, and selected state of controls with stable unique IDs. Missing pages and connection-status pages remain live and recover on a later publication or reconnect.
-
-## Forms
-
-Use native same-origin GET or POST forms:
+Use stable IDs as replacement boundaries:
 
 ```html
-<form id="decision" action="/decide" method="post">
-  <label>Comment <textarea id="comment" name="comment"></textarea></label>
-  <button name="decision" value="approve">Approve</button>
-  <button name="decision" value="reject">Reject</button>
-</form>
+<output id="counter">41</output>
 ```
 
-Before delivery, the runtime gives each logical submission an opaque UUID and persists the serialized request in IndexedDB. Network retries and page reloads reuse that UUID. The CLI deduplicates accepted events, so a transport retry does not become another interaction. Distinct intentional submissions receive distinct IDs.
-
-The runtime displays **Sending…** or **Uploading…**, followed by **Sent. Waiting for an update…** or an error. Add `[data-letmeknow-status]` to choose the status location. Native validation runs before submission. Repeated field names become arrays.
-
-POST forms may include files within the 1 MiB total request limit. `pull` events contain attachment metadata and private temporary paths. Attachments remain available until `serve` stops and are not public unless deliberately copied into the workspace and pushed.
+```json
+{"updates":[{"target":"counter","html":"<output id=\"counter\">42</output>"}]}
+```
 
-Every submission records the exact workspace revision shown to the user. Its derived `context.relationship` is `current`, `stale`, or `unknown`, allowing the agent to decide whether to apply, rebase, or reject old feedback.
+Each replacement must contain one element with the target's ID and cannot contain scripts. Replacements in one push are applied in order and atomically. Replacing `letmeknow-root` is the broad page-update case and intentionally discards browser-local state inside that root.
 
-## Security
+## Session and security basics
 
-The URL is a bearer capability. The relay receives published files and submitted values. Keep secrets and unrelated files outside the preview directory.
+Sessions are temporary and held in memory by the CLI and relay. The service may expire a session at any time. If the producer disconnects, reconnect is best-effort and may be available only for a limited period; clients should handle disconnects without assuming that reconnect will succeed.
 
-The CLI excludes `.env`, `.git`, SSH keys, private-key files, and database files, and prevents symlink escapes. Processes that can write the workspace and invoke `push` are trusted publishers. Browser values, filenames, media types, and attachment contents remain untrusted input.
+The public URL is a bearer capability: anyone who has it can view the page and submit forms. Treat browser values as untrusted input and escape them before placing them in HTML. Keep secrets and unrelated files outside the served directory.
 
 ## Development
 
@@ -104,4 +59,4 @@ npm run dev
 npm run deploy
 ```
 
-The browser test requires Firefox and geckodriver. `npm run dev` and `npm run deploy` operate the Cloudflare relay.
+The browser smoke test requires Firefox and geckodriver. `npm run dev` and `npm run deploy` operate the Cloudflare relay. For the detailed agent workflow, forms, event causality, reconnect behavior, and static-asset guidance, read [`SKILL.md`](SKILL.md).

package/SKILL.md

@@ -1,89 +1,206 @@
 ---
 name: letmeknow
-description: Publish a temporary browser workspace, pull structured human feedback, and push coherent agent revisions.
+description: Serve a temporary live HTML page, collect structured human feedback, and push ordered HTML replacements.
 ---
 
 # LetMeKnow
 
-Use LetMeKnow when a human should inspect or interact with an agent-managed page, report, dashboard, approval, quiz, table, or prototype.
+Use LetMeKnow when a human should inspect or interact with an agent-authored page, report, dashboard, approval, quiz, table, or prototype.
 
 ## Start
 
-Create a dedicated directory containing only public files and keep the server running:
+Create a directory containing the public files and an initial `index.html`, then run:
 
 ```bash
 npx letmeknow-cli serve ./preview
 ```
 
-Node.js 22.12 or newer is required. The first stdout JSON line contains the bearer URL and initial workspace revision:
+`serve` reads `index.html` once as the initial canonical dynamic page and serves it at `/`. Other files—such as CSS, JavaScript, images, and data—are served live from the directory. The first stdout JSON line contains the public bearer URL and initial page metadata:
 
 ```json
-{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/","workspace":"…","workspace_sequence":1}
+{"type":"ready","url":"https://0123456789abcdef0123.letmeknow.dev/","page_event":0,"page_hash":"…"}
 ```
 
-Give the URL to the human. Anyone with it can view the workspace and submit forms. The CLI connects outbound and opens no network port. Diagnostics go to stderr.
+The initial page should have a stable shell and a dynamic root:
+
+```html
+<body>
+  <main id="letmeknow-root">
+    ...
+  </main>
+  <script type="module" src="/app.js"></script>
+</body>
+```
+
+The runtime is injected into the page separately. Keep agent-authored scripts and the runtime outside normal replacement targets.
+
+## Session lifetime and reconnect
+
+A producer must successfully send `open` shortly after connecting. Sessions are temporary and may be expired by the service at any time.
+
+If an opened producer disconnects, reconnect is best-effort and may be available only for a limited period. A reconnect uses the existing session credential, but clients must handle disconnects without assuming that reconnect will succeed. When the service expires a session, the session and its browser connections end.
 
 ## Agent loop
 
-Filesystem writes are private drafts. Explicitly pull feedback and publish coherent revisions:
+Pull browser events, update one or more HTML fragments, and push the replacements:
 
 ```bash
-npx letmeknow-cli pull ./preview --wait 30
-# validate feedback and edit files
-npx letmeknow-cli push ./preview --based-on <batch-token>
+batch=$(npx letmeknow-cli pull ./preview --wait 30)
+token=$(printf '%s\n' "$batch" | jq -r .token)
+# inspect events and write fragments such as counter.html and status.html
+npx letmeknow-cli push ./preview --batch "$token" --updates updates.json
 ```
 
-`pull` returns pending events, their derived causal context, the current workspace, and an opaque token. Pulling does not consume events; they are returned again after a crash. A successful `push` atomically snapshots the folder, commits that batch, and reloads connected browsers once. Feedback that arrives while you work remains for the next pull.
+Commands:
 
-When a batch needs no visible workspace change:
+```text
+serve <dir>
+show <dir>
+pull <dir> [--wait seconds]
+push <dir> --batch TOKEN [--updates FILE|-]
+```
+
+`show` returns the current canonical page without changing the event stream:
 
 ```bash
-npx letmeknow-cli ack ./preview --based-on <batch-token>
+npx letmeknow-cli show ./preview > current.html
 ```
 
-Both commands are idempotent for a token. Do not edit while `push` is snapshotting. Do not write commands to the long-running server's stdin.
+The public URL is the visual preview. `show` returns canonical HTML, not a browser's local focus, open disclosures, unsent input, scroll position, or JavaScript state.
 
-A push may publish independent work from an empty batch. Use the token returned by an empty `pull`.
+## Push updates
 
-## Build the workspace
+A push accepts one JSON document:
 
-Use ordinary HTML, CSS, JavaScript, images, and relative links. Give forms stable IDs and controls meaningful names. Give editable controls stable unique IDs so values and scroll position survive published revisions.
+```json
+{
+  "updates": [
+    {"target": "counter", "file": "counter.html"},
+    {"target": "status", "html": "<output id=\"status\">Saved</output>"}
+  ]
+}
+```
 
-Use native same-origin GET or POST forms:
+Each update must contain exactly one of `html` or `file`. A file supplies the replacement HTML. The normal operation is direct replacement of one element identified by its unique stable `id`:
 
 ```html
-<form id="review" action="/review" method="post">
-  <label>Comment <textarea id="comment" name="comment"></textarea></label>
-  <button name="decision" value="approve">Approve</button>
-  <button name="decision" value="reject">Reject</button>
-</form>
+<output id="counter">41</output>
+```
+
+```json
+{"updates":[{"target":"counter","html":"<output id=\"counter\">42</output>"}]}
+```
+
+The replacement must contain exactly one element, and that element must have the same ID as the target. Replacement HTML cannot contain scripts. The target must exist when the replacement is applied.
+
+Use small output regions for ordinary updates. The replacement is destructive inside its target but leaves the rest of the page alone, so a counter update does not disturb a form or button elsewhere.
+
+The document root is just another target. To intentionally replace all dynamic content, target the root:
+
+```html
+<main id="letmeknow-root">
+  ...
+</main>
+```
+
+```json
+{"updates":[{"target":"letmeknow-root","file":"root.html"}]}
+```
+
+Replacing the root intentionally discards browser-local state inside it. Use it when that is acceptable, not for every small change.
+
+A single push may contain many replacements. They are applied in the order listed. Later replacements may target elements introduced by earlier replacements in the same push, so introduce a target before updating it. Conversely, a replacement that removes a later target makes a following update invalid. The CLI validates the complete ordered batch before committing anything.
+
+Each replacement becomes its own `update_ui` event with its own global event number. The complete push is still atomic: either all replacements and the pulled browser-event batch commit, or none do. Connected browsers receive committed replacements in order.
+
+A push without `--updates` commits the pulled browser events without changing the page:
+
+```bash
+npx letmeknow-cli push ./preview --batch "$token"
 ```
 
-The browser persists each serialized submission before delivery and retries it with the same opaque UUID after network failures or reloads. The CLI deduplicates retries. Distinct intentional submissions remain distinct. Native validation and repeated field names work normally.
+There is no separate acknowledgement command and no `--page` mode. Replacing `letmeknow-root` provides the broad page-update case.
 
-A pulled event includes the workspace the human saw:
+## Event stream and page causality
+
+Browser submissions and CLI page replacements share one ordered, in-memory event stream:
+
+```text
+submit       browser
+submit       browser
+update_ui    CLI: replace #counter
+update_ui    CLI: replace #status
+```
+
+The CLI assigns event numbers in acceptance order. They do not claim to be the physical order in which people clicked. Browser submissions are delivered to the agent through `pull`; raw submissions are not broadcast to other browsers. Page replacements are broadcast to all connected browsers.
+
+`pull` returns an opaque batch token, current-page metadata, and browser events not yet committed by the agent. Pulling does not consume events. Events arriving while the agent works remain for a later pull.
 
 ```json
 {
-  "type": "submit",
-  "id": "…",
-  "form_id": "review",
-  "values": {"comment":"Looks good","decision":"approve"},
-  "based_on": "…",
-  "context": {
-    "based_on": "…",
-    "current": "…",
-    "relationship": "current"
-  }
+  "token": "…",
+  "frontier": 7,
+  "page_event": 5,
+  "page_hash": "…",
+  "events": [
+    {
+      "type": "submit",
+      "id": "…",
+      "event_number": 7,
+      "page_event": 5,
+      "form_id": "decision",
+      "action": "/decide",
+      "trigger": {"name": "decision", "value": "approve"},
+      "values": {"comment": "Looks good", "decision": "approve"}
+    }
+  ]
 }
 ```
 
-Treat `stale` feedback deliberately: apply its intent to current state when safe, or show that the artifact changed and ask the human to review again. Never reconstruct the workspace from stale form values.
+`page_event` is the page-update event number displayed when the browser submitted. Compare each event's `page_event` with the batch's current page before applying old input to the current HTML. `frontier` is the latest global event number, including events that are not browser submissions.
+
+The token identifies exactly the browser-event frontier the agent saw. A successful push commits that frontier and its ordered replacements together. Browser events accepted after the pull remain for the next batch.
+
+## Forms
+
+Use ordinary same-origin forms with stable IDs and meaningful field names:
+
+```html
+<form id="decision" action="/decide" method="post">
+  <label>Comment <textarea id="comment" name="comment"></textarea></label>
+  <button name="decision" value="approve">Approve</button>
+  <button name="decision" value="reject">Reject</button>
+</form>
+```
+
+The runtime converts native form submission into a JSON `submit` event. It assigns an opaque UUID, stores each event in a durable browser outbox before delivery, retries after connection failures, and reuses the UUID on retry. The CLI deduplicates repeated delivery of the same event. Distinct intentional submissions remain distinct, including rapid repeated clicks. File uploads are not supported.
+
+Treat pulled values as untrusted input. Validate them and escape them before putting them into HTML.
+
+## Browser and HTML rules
+
+Normal updates are direct replacements, not DOM morphs. Stable IDs are therefore important for naming update boundaries, not for preserving DOM nodes.
+
+- The CLI owns content inside replacement targets.
+- The browser owns local focus, open/closed disclosure state, and hide/show behavior outside deliberately replaced targets.
+- A root replacement can destroy all local state inside the root.
+- Load agent-authored JavaScript from the initial page as a static asset.
+- Use delegated event listeners because replaced elements are new DOM nodes.
+- Scripts in update fragments are not executed.
+- Do not have browser JavaScript and pushed HTML independently own the same state.
+
+When a session ends, the browser shows a permanent closed status and discards unsent submissions rather than retrying them.
+
+## Static assets
+
+CSS, JavaScript, images, and other non-`index.html` files are served live. Finish writing an asset before pushing HTML that references it. Write assets atomically, and use versioned filenames or cache-busting URLs when the browser must fetch a changed asset with the page update.
+
+This design intentionally does not provide atomic publication of the whole directory. The dynamic page changes through ordered replacements; other files can change as soon as they are written.
 
-POST forms may upload files within the 1 MiB request limit. Attachment events contain private temporary paths valid until `serve` stops. Validate names, media types, sizes, contents, actions, and IDs. Copy only deliberate outputs into the public workspace.
+## Security
 
-Escape untrusted text before placing it in HTML.
+The URL is a bearer capability. Anyone who has it can view the page and submit forms. Keep secrets and unrelated files outside the served directory. Browser values are untrusted input; escape them before placing them in HTML.
 
 ## Stop
 
-Send `SIGINT` or `SIGTERM` to `serve`. A graceful stop closes the public session and removes temporary snapshots, attachments, and the local control socket. `--skill` prints these instructions.
+Send `SIGINT` or `SIGTERM` to `serve`. The temporary session ends when the process stops.

package/bin/letmeknow.js

@@ -1,25 +1,31 @@
 #!/usr/bin/env node
 
-import { constants, existsSync, readFileSync, statSync, writeSync } from "node:fs";
-import { chmod, copyFile, lstat, mkdtemp, mkdir, open, readdir, readlink, realpath, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
+import { constants, createReadStream, existsSync, readFileSync, statSync, writeSync } from "node:fs";
+import { chmod, open, readFile, realpath, stat, unlink } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 import net from "node:net";
-import { dirname, extname, join, relative, resolve, sep } from "node:path";
+import { dirname, join, relative, resolve, sep } from "node:path";
 import { tmpdir } from "node:os";
 import { parseArgs } from "node:util";
+import { parse, parseFragment, serialize } from "parse5";
 import { lookup } from "mrmime";
 
 const MAX_BODY_BYTES = 1024 * 1024;
-const GRACE_SECONDS = 10 * 60;
+const UPDATE_BATCH_MAX_BYTES = 16 * MAX_BODY_BYTES;
+const MAX_BATCH_TOKENS = 100_000;
+const MAX_UNIQUE_SUBMISSIONS = 100_000;
+const MAX_RETAINED_SUBMISSION_BYTES = 256 * 1024 * 1024;
+const CONTROL_MAX_BYTES = UPDATE_BATCH_MAX_BYTES * 2;
+const RECONNECT_RETRY_SECONDS = 10 * 60;
 const CONNECTION_TIMEOUT = 10_000;
 const CONTROL_TIMEOUT = 35_000;
-const MAX_RETRY_DELAY = 5_000;
 const CONTROL_PREFIX = "letmeknow-control-";
-const SNAPSHOT_PREFIX = "letmeknow-snapshot-";
 const CONTROL_URL = "https://letmeknow.dev";
 const credentialPattern = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
 const privateNames = new Set([".env", ".git", ".ssh", "id_rsa", "id_ed25519", "id_ecdsa", "id_dsa"]);
 const privateFilePattern = /^\.env\.|\.(?:key|pem|p12|ppk|p8|sqlite|sqlite3|db|db3)$|-(?:wal|shm|journal)$/i;
+const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const forbiddenUpdateTargets = new Set(["html", "head", "body", "script"]);
 
 function getMimeType(filename) {
   const type = lookup(filename);
@@ -34,17 +40,6 @@ function header(packet, name) {
   return typeof entry?.[1] === "string" && entry[1] !== "" ? entry[1] : null;
 }
 
-function encodedHeader(packet, name) {
-  const value = header(packet, name);
-  if (value === null) return null;
-  try { return decodeURIComponent(value); } catch { return null; }
-}
-
-function addValue(values, name, value) {
-  if (Object.prototype.hasOwnProperty.call(values, name)) values[name] = Array.isArray(values[name]) ? [...values[name], value] : [values[name], value];
-  else values[name] = value;
-}
-
 function response(packet, status, body = Buffer.alloc(0), headers = {}) {
   if (body.byteLength > MAX_BODY_BYTES) return response(packet, 413, Buffer.from("response body is too large"), { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store" });
   const outputHeaders = { "Cache-Control": "no-store", ...headers };
@@ -93,12 +88,15 @@ function requestUrl(packet) {
   return { pathname, encodedPathname: url.pathname, search: url.search };
 }
 
-async function staticResponse(root, packet, workspaceId) {
-  const published = (status, body = Buffer.alloc(0), headers = {}) => response(packet, status, body, { ...headers, "X-LetMeKnow-Workspace": workspaceId });
+async function staticResponse(root, packet, page, pageEvent) {
+  const published = (status, body = Buffer.alloc(0), headers = {}) => response(packet, status, body, headers);
   const method = typeof packet.method === "string" ? packet.method.toUpperCase() : "";
   if (method !== "GET" && method !== "HEAD") return errorResponse(packet, 405, "method not allowed");
   let request;
   try { request = requestUrl(packet); } catch { return errorResponse(packet, 400, "bad request"); }
+  if (request.pathname === "/" || request.pathname === "/index.html") {
+    return published(200, Buffer.from(page), { "Content-Type": "text/html; charset=utf-8", "X-LetMeKnow-Page-Event": String(pageEvent) });
+  }
   if (deniedPath(request.pathname)) return errorResponse(packet, 403, "forbidden");
   const candidate = resolve(root, "." + request.pathname);
   if (!inside(root, candidate)) return errorResponse(packet, 403, "forbidden");
@@ -151,69 +149,157 @@ async function staticResponse(root, packet, workspaceId) {
   }
 }
 
-async function multipartSubmission(body, contentType, getAttachmentInbox) {
-  const formData = await new Request("http://letmeknow.local", {
-    method: "POST",
-    headers: { "Content-Type": contentType },
-    body
-  }).formData();
-  const values = Object.create(null);
-  const attachments = [];
-  for (const [name, value] of formData) {
-    if (typeof value === "string") {
-      addValue(values, name, value);
-      continue;
+async function readInitialPage(root) {
+  const candidate = join(root, "index.html");
+  const target = await safeRealpath(root, candidate);
+  if (target === null || target === undefined || deniedPath("/" + relative(root, target).split(sep).join("/"))) throw new Error("index.html is required");
+  const info = await stat(target);
+  if (!info.isFile()) throw new Error("index.html must be a file");
+  if (info.size > MAX_BODY_BYTES) throw new Error("index.html is too large");
+  return (await readFile(target)).toString("utf8");
+}
+
+function nodeId(node) {
+  return node.attrs?.find(attribute => attribute.name === "id")?.value;
+}
+
+function elementsWithId(node, id, matches = []) {
+  if (node.nodeName !== "#text" && node.nodeName !== "#comment" && nodeId(node) === id) matches.push(node);
+  for (const child of node.childNodes || []) elementsWithId(child, id, matches);
+  return matches;
+}
+
+function containsScript(node) {
+  if (node.nodeName === "script") return true;
+  if (node.content && containsScript(node.content)) return true;
+  return (node.childNodes || []).some(containsScript);
+}
+
+function updateFragment(target, html, context) {
+  const fragment = parseFragment(context, html);
+  const meaningful = (fragment.childNodes || []).filter(node => node.nodeName !== "#text" || node.value.trim() !== "");
+  if (meaningful.length !== 1 || meaningful[0].nodeName === "#comment" || meaningful[0].nodeName?.startsWith("#")) throw new Error(`update for ${target} must contain exactly one root element`);
+  const root = meaningful[0];
+  if (containsScript(root)) throw new Error(`update for ${target} cannot contain script elements`);
+  if (nodeId(root) !== target) throw new Error(`update root ID must be ${target}`);
+  return root;
+}
+
+function replaceElement(document, target, html) {
+  if (forbiddenUpdateTargets.has(target.nodeName)) throw new Error(`cannot update ${target.nodeName} element`);
+  const parent = target.parentNode;
+  const index = parent?.childNodes.indexOf(target);
+  if (!parent || index === undefined || index < 0) throw new Error("update target has no parent");
+  const replacement = updateFragment(nodeId(target), html, parent);
+  parent.childNodes[index] = replacement;
+  replacement.parentNode = parent;
+  target.parentNode = null;
+}
+
+function validateUpdates(updates) {
+  if (!Array.isArray(updates)) throw new Error("updates must be an array");
+  let bytes = 0;
+  for (const update of updates) {
+    if (!update || typeof update !== "object" || Array.isArray(update)) throw new Error("each update must be an object");
+    if (typeof update.target !== "string" || update.target.trim() === "") throw new Error("update target must be a non-empty ID");
+    if (typeof update.html !== "string") throw new Error("update html must be text");
+    bytes += Buffer.byteLength(update.html, "utf8");
+    if (bytes > UPDATE_BATCH_MAX_BYTES) throw new Error("updates are too large");
+  }
+  return updates;
+}
+
+function applyUpdates(page, updates) {
+  validateUpdates(updates);
+  const document = parse(page);
+  for (const update of updates) {
+    const matches = elementsWithId(document, update.target);
+    if (matches.length !== 1) throw new Error(`update target ${update.target} must match exactly one element`);
+    replaceElement(document, matches[0], update.html);
+  }
+  const result = serialize(document);
+  if (Buffer.byteLength(result, "utf8") > MAX_BODY_BYTES) throw new Error("updated page is too large");
+  return result;
+}
+
+async function readInput(filename) {
+  const chunks = [];
+  let length = 0;
+  const input = filename === "-" ? process.stdin : createReadStream(filename);
+  for await (const chunk of input) {
+    const value = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    length += value.byteLength;
+    if (length > UPDATE_BATCH_MAX_BYTES) throw new Error("updates are too large");
+    chunks.push(value);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function readUpdatesInput(filename) {
+  const manifest = await readInput(filename);
+  let value;
+  try { value = JSON.parse(manifest); } catch { throw new Error("invalid updates JSON"); }
+  if (!value || typeof value !== "object" || Array.isArray(value) || !Array.isArray(value.updates)) throw new Error("updates must be an object with an updates array");
+  const base = filename === "-" ? process.cwd() : dirname(resolve(filename));
+  const updates = [];
+  let bytes = 0;
+  for (const item of value.updates) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error("each update must be an object");
+    if (typeof item.target !== "string" || item.target.trim() === "") throw new Error("update target must be a non-empty ID");
+    const hasHtml = Object.prototype.hasOwnProperty.call(item, "html");
+    const hasFile = Object.prototype.hasOwnProperty.call(item, "file");
+    if (hasHtml === hasFile) throw new Error(`update for ${item.target} must have exactly one of html or file`);
+    let html;
+    if (hasHtml) {
+      if (typeof item.html !== "string") throw new Error(`update html for ${item.target} must be text`);
+      html = item.html;
+    } else {
+      if (typeof item.file !== "string" || item.file === "") throw new Error(`update file for ${item.target} must be a path`);
+      const file = resolve(base, item.file);
+      const info = await stat(file);
+      if (!info.isFile()) throw new Error(`update file for ${item.target} must be a regular file`);
+      if (info.size > UPDATE_BATCH_MAX_BYTES - bytes) throw new Error("updates are too large");
+      html = (await readFile(file)).toString("utf8");
     }
-    if (value.name === "") continue;
-    const bytes = Buffer.from(await value.arrayBuffer());
-    const path = join(await getAttachmentInbox(), randomUUID());
-    await writeFile(path, bytes, { mode: 0o600, flag: "wx" });
-    attachments.push({ field: name, name: value.name, type: value.type, size: bytes.byteLength, path });
+    bytes += Buffer.byteLength(html, "utf8");
+    if (bytes > UPDATE_BATCH_MAX_BYTES) throw new Error("updates are too large");
+    updates.push({ target: item.target, html });
   }
-  return { values, attachments };
+  return updates;
+}
+
+function updatesHash(updates) {
+  return createHash("sha256").update(JSON.stringify(updates)).digest("hex");
 }
 
-async function submission(packet, getAttachmentInbox, recordInteraction) {
-  const url = requestUrl(packet);
+async function submission(packet, recordInteraction) {
+  const request = requestUrl(packet);
   const method = typeof packet.method === "string" ? packet.method.toUpperCase() : "";
-  const values = Object.create(null);
-  let attachments;
-  if (method === "GET") {
-    for (const [name, value] of new URLSearchParams(url.search)) addValue(values, name, value);
-  } else if (method === "POST") {
-    const body = Buffer.from(typeof packet.body === "string" ? packet.body : "", "base64");
-    if (body.byteLength > MAX_BODY_BYTES) throw new Error("submission is too large");
-    const contentTypeHeader = header(packet, "content-type");
-    const contentType = contentTypeHeader?.split(";", 1)[0].trim().toLowerCase();
-    if (contentType === "application/x-www-form-urlencoded") {
-      for (const [name, value] of new URLSearchParams(body.toString("utf8"))) addValue(values, name, value);
-    } else if (contentType === "multipart/form-data" && contentTypeHeader) {
-      const parsed = await multipartSubmission(body, contentTypeHeader, getAttachmentInbox);
-      Object.assign(values, parsed.values);
-      attachments = parsed.attachments;
-    } else throw new Error("unsupported submission encoding");
-  } else throw new Error("unsupported submission method");
-  const event = {
-    type: "submit",
-    id: encodedHeader(packet, "x-letmeknow-id") || randomUUID(),
-    method,
-    action: encodedHeader(packet, "x-letmeknow-action") || url.pathname,
-    form_id: encodedHeader(packet, "x-letmeknow-form-id"),
-    trigger: { id: encodedHeader(packet, "x-letmeknow-trigger-id"), name: encodedHeader(packet, "x-letmeknow-trigger-name"), value: encodedHeader(packet, "x-letmeknow-trigger-value") },
-    values
-  };
-  const basedOn = encodedHeader(packet, "x-letmeknow-based-on");
-  if (basedOn !== null) event.based_on = basedOn;
-  if (attachments?.length) event.attachments = attachments;
-  await recordInteraction(event);
+  if (method !== "POST" || request.pathname !== "/_letmeknow/submit") throw new Error("invalid submission endpoint");
+  const contentType = header(packet, "content-type")?.split(";", 1)[0].trim().toLowerCase();
+  if (contentType !== "application/json") throw new Error("JSON submission is required");
+  const body = Buffer.from(typeof packet.body === "string" ? packet.body : "", "base64");
+  if (body.byteLength > MAX_BODY_BYTES) throw new Error("submission is too large");
+  let value;
+  try { value = JSON.parse(body.toString("utf8")); } catch { throw new Error("invalid submission JSON"); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("submission must be an object");
+  if (typeof value.id !== "string" || !uuidPattern.test(value.id)) throw new Error("submission id must be a UUID");
+  if (!Number.isSafeInteger(value.page_event) || value.page_event < 0) throw new Error("page_event must be a non-negative integer");
+  if (value.form_id !== null && typeof value.form_id !== "string") throw new Error("form_id must be text or null");
+  if (typeof value.action !== "string") throw new Error("action is required");
+  if (value.trigger !== null && (typeof value.trigger !== "object" || Array.isArray(value.trigger))) throw new Error("trigger must be an object or null");
+  if (!value.values || typeof value.values !== "object" || Array.isArray(value.values)) throw new Error("values are required");
+  await recordInteraction({ type: "submit", id: value.id, page_event: value.page_event, form_id: value.form_id, action: value.action, trigger: value.trigger, values: value.values }, body.byteLength);
   return response(packet, 202);
 }
 
-async function handleRequest(root, workspaceId, packet, getAttachmentInbox, recordInteraction) {
-  if (header(packet, "x-letmeknow-submission") === "1") {
-    try { return await submission(packet, getAttachmentInbox, recordInteraction); } catch (cause) { return errorResponse(packet, cause?.message === "submission is too large" ? 413 : 400, cause instanceof Error ? cause.message : "invalid submission"); }
+async function handleRequest(root, page, pageEvent, packet, recordInteraction) {
+  let request;
+  try { request = requestUrl(packet); } catch { return errorResponse(packet, 400, "bad request"); }
+  if (request.pathname === "/_letmeknow/submit") {
+    try { return await submission(packet, recordInteraction); } catch (cause) { return errorResponse(packet, cause?.message === "submission is too large" ? 413 : 400, cause instanceof Error ? cause.message : "invalid submission"); }
   }
-  return staticResponse(root, packet, workspaceId);
+  return staticResponse(root, packet, page, pageEvent);
 }
 
 function options(directory) {
@@ -227,41 +313,6 @@ function controlPath(root) {
   return join(tmpdir(), `${CONTROL_PREFIX}${key}.sock`);
 }
 
-async function copyDirectory(source, target, root, visited = new Set()) {
-  const sourceReal = await realpath(source);
-  if (visited.has(sourceReal)) return;
-  visited.add(sourceReal);
-  await mkdir(target, { recursive: true });
-  for (const entry of await readdir(sourceReal, { withFileTypes: true })) {
-    const candidate = join(sourceReal, entry.name);
-    const pathname = "/" + relative(root, candidate).split(sep).join("/");
-    if (deniedPath(pathname)) continue;
-    const targetPath = join(target, entry.name);
-    const targetReal = await safeRealpath(root, candidate);
-    if (targetReal === null) {
-      if ((await lstat(candidate)).isSymbolicLink()) await symlink(await readlink(candidate), targetPath);
-      continue;
-    }
-    if (targetReal === undefined) continue;
-    if (deniedPath("/" + relative(root, targetReal).split(sep).join("/"))) continue;
-    const info = await stat(targetReal);
-    if (info.isDirectory()) await copyDirectory(targetReal, targetPath, root, visited);
-    else if (info.isFile()) await copyFile(targetReal, targetPath);
-  }
-  visited.delete(sourceReal);
-}
-
-async function snapshotDirectory(root) {
-  const snapshot = await mkdtemp(join(tmpdir(), SNAPSHOT_PREFIX));
-  try {
-    await copyDirectory(root, snapshot, root);
-    return snapshot;
-  } catch (cause) {
-    await rm(snapshot, { recursive: true, force: true });
-    throw cause;
-  }
-}
-
 function mutateQueue() {
   let chain = Promise.resolve();
   return operation => {
@@ -303,20 +354,20 @@ function connectControl(root, packet) {
   });
 }
 
+function pageHash(page) {
+  return createHash("sha256").update(page).digest("hex");
+}
+
 async function start(directory) {
   const { root } = await options(directory);
-  let attachmentInboxPromise;
-  const getAttachmentInbox = () => {
-    attachmentInboxPromise ??= mkdtemp(join(tmpdir(), "letmeknow-attachments-"));
-    return attachmentInboxPromise;
-  };
-  const socketPath = controlPath(root);
-  let publishedRoot = await snapshotDirectory(root);
-  let workspaceId = randomUUID();
-  let workspaceSequence = 1;
-  const workspaceIds = new Set([workspaceId]);
-  const eventLog = [];
-  let committedCursor = 0;
+  let page = await readInitialPage(root);
+  let pageEvent = 0;
+  let eventNumber = 0;
+  const currentPageHash = () => pageHash(page);
+  const browserEvents = [];
+  const browserEventBytes = [];
+  let retainedSubmissionBytes = 0;
+  let committedBrowserCursor = 0;
   const seenEvents = new Set();
   const tokens = new Map();
   const pendingTokens = new Map();
@@ -333,32 +384,28 @@ async function start(directory) {
   let retryUntil = 0;
   let stopped = false;
   let ready = false;
-  let initialPublished = false;
+  let stopSession = () => {};
 
   const batch = () => {
-    const start = committedCursor;
-    const end = eventLog.length;
-    const key = `${workspaceId}:${start}:${end}`;
-    const existing = pendingTokens.get(key);
-    if (existing) return existing;
-    const token = randomUUID();
-    const events = eventLog.slice(start, end).map(event => ({
-      ...event,
-      context: {
-        based_on: event.based_on ?? null,
-        current: workspaceId,
-        relationship: event.based_on === workspaceId ? "current" : workspaceIds.has(event.based_on) ? "stale" : "unknown"
+    const start = committedBrowserCursor;
+    const end = start + browserEvents.length;
+    const key = `${pageEvent}:${start}:${end}`;
+    let token = pendingTokens.get(key)?.token;
+    if (!token) {
+      if (tokens.size >= MAX_BATCH_TOKENS) {
+        stopSession();
+        throw new Error("session batch token limit exceeded");
       }
-    }));
-    tokens.set(token, { start, end, parent: workspaceId, status: "pending", key });
-    const result = { ok: true, type: "batch", token, workspace: workspaceId, workspace_sequence: workspaceSequence, frontier: end, events };
-    pendingTokens.set(key, result);
-    return result;
+      token = randomUUID();
+      tokens.set(token, { start, end, page_event: pageEvent, status: "pending", key, updates_hash: null });
+      pendingTokens.set(key, { token });
+    }
+    return { ok: true, type: "batch", token, frontier: eventNumber, page_event: pageEvent, page_hash: currentPageHash(), events: browserEvents.slice() };
   };
 
   const notifyPullWaiters = () => {
     for (const waiter of [...pullWaiters]) {
-      if (eventLog.length === committedCursor) continue;
+      if (browserEvents.length === 0) continue;
       pullWaiters.delete(waiter);
       clearTimeout(waiter.timer);
       waiter.resolve(batch());
@@ -366,53 +413,71 @@ async function start(directory) {
   };
 
   const pull = waitSeconds => {
-    if (eventLog.length > committedCursor || waitSeconds <= 0) return Promise.resolve(batch());
+    if (browserEvents.length > 0 || waitSeconds <= 0) return Promise.resolve(batch());
     return new Promise(resolve => {
       const waiter = { resolve, timer: setTimeout(() => { pullWaiters.delete(waiter); resolve(batch()); }, waitSeconds * 1_000) };
       pullWaiters.add(waiter);
     });
   };
 
-  const commit = async (token, publish) => {
+  const commit = async (token, requestedUpdates) => {
     const record = tokens.get(token);
     if (!record) return { ok: false, error: "unknown batch token" };
-    if (record.status !== "pending") return record.result;
-    if (record.start < committedCursor && record.end <= committedCursor) {
-      pendingTokens.delete(record.key);
-      record.status = "committed";
-      record.result = { ok: true, type: "already_committed", token, workspace: workspaceId, workspace_sequence: workspaceSequence, frontier: committedCursor };
-      return record.result;
+    const updates = validateUpdates(requestedUpdates);
+    const requestedUpdatesHash = updatesHash(updates);
+    if (record.status !== "pending") {
+      if (record.updates_hash === requestedUpdatesHash) return record.result;
+      return { ok: false, error: "batch was already committed with a different updates payload" };
     }
-    if (record.parent !== workspaceId || record.start !== committedCursor) {
+    if (record.page_event !== pageEvent || record.start !== committedBrowserCursor) {
+      record.updates_hash = requestedUpdatesHash;
       pendingTokens.delete(record.key);
       record.status = "failed";
-      record.result = { ok: false, error: "batch is based on an old workspace or cursor", current_workspace: workspaceId, frontier: committedCursor };
+      record.result = { ok: false, error: "batch is based on an old page or browser cursor", frontier: eventNumber, page_event: pageEvent, page_hash: currentPageHash() };
       return record.result;
     }
-    if (publish) {
-      const nextRoot = await snapshotDirectory(root);
-      const previousRoot = publishedRoot;
-      publishedRoot = nextRoot;
-      workspaceId = randomUUID();
-      workspaceIds.add(workspaceId);
-      workspaceSequence += 1;
-      record.result = { ok: true, type: "published", token, workspace: workspaceId, workspace_sequence: workspaceSequence, parent: record.parent, frontier: record.end, events: eventLog.slice(record.start, record.end).map(event => event.id) };
-      void rm(previousRoot, { recursive: true, force: true }).catch(() => {});
-    } else {
-      record.result = { ok: true, type: "acknowledged", token, workspace: workspaceId, workspace_sequence: workspaceSequence, frontier: record.end, events: eventLog.slice(record.start, record.end).map(event => event.id) };
+    let nextPage = page;
+    try { if (updates.length) nextPage = applyUpdates(page, updates); } catch (cause) {
+      throw new Error(cause instanceof Error ? cause.message : "invalid page updates");
+    }
+    const committedCount = record.end - record.start;
+    const committedEvents = browserEvents.slice(0, committedCount).map(event => event.id);
+    retainedSubmissionBytes -= browserEventBytes.slice(0, committedCount).reduce((total, bytes) => total + bytes, 0);
+    const updateEvents = [];
+    for (const update of updates) {
+      eventNumber += 1;
+      updateEvents.push({ type: "update_ui", event_number: eventNumber, target: update.target, html: update.html });
     }
-    committedCursor = record.end;
+    page = nextPage;
+    pageEvent = updateEvents.at(-1)?.event_number ?? pageEvent;
+    browserEvents.splice(0, committedCount);
+    browserEventBytes.splice(0, committedCount);
+    committedBrowserCursor = record.end;
     pendingTokens.delete(record.key);
     record.status = "committed";
-    if (publish) send({ type: "revision" });
+    record.updates_hash = requestedUpdatesHash;
+    record.result = {
+      ok: true,
+      type: "committed",
+      token,
+      frontier: eventNumber,
+      page_event: pageEvent,
+      page_hash: currentPageHash(),
+      events: committedEvents,
+      updates: updateEvents.map(({ event_number, target }) => ({ event_number, target }))
+    };
+    for (const update of updateEvents) send(update);
     return record.result;
   };
 
   const dispatchControl = async request => {
     if (!request || typeof request !== "object") return { ok: false, error: "invalid control request" };
     if (request.type === "pull") return pull(Number.isFinite(request.wait_seconds) ? Math.max(0, request.wait_seconds) : 0);
-    if (request.type === "push") return commit(typeof request.token === "string" ? request.token : "", true);
-    if (request.type === "ack") return commit(typeof request.token === "string" ? request.token : "", false);
+    if (request.type === "show") return { ok: true, type: "page", page_event: pageEvent, page_hash: currentPageHash(), html: page };
+    if (request.type === "push") {
+      if (typeof request.token !== "string") return { ok: false, error: "batch token is required" };
+      return commit(request.token, request.updates === undefined ? [] : request.updates);
+    }
     return { ok: false, error: "unknown control request" };
   };
 
@@ -424,7 +489,7 @@ async function start(directory) {
     let handled = false;
     connection.on("data", async chunk => {
       input += chunk;
-      if (input.length > MAX_BODY_BYTES || handled) return;
+      if (Buffer.byteLength(input, "utf8") > CONTROL_MAX_BYTES || handled) return;
       const newline = input.indexOf("\n");
       if (newline < 0) return;
       handled = true;
@@ -440,20 +505,25 @@ async function start(directory) {
   });
   await new Promise((resolveListen, reject) => {
     controlServer.once("error", reject);
-    controlServer.listen(socketPath, async () => {
-      try { await chmod(socketPath, 0o600); } catch (cause) { controlServer.close(() => reject(cause)); return; }
+    controlServer.listen(controlPath(root), async () => {
+      try { await chmod(controlPath(root), 0o600); } catch (cause) { controlServer.close(() => reject(cause)); return; }
       controlServer.off("error", reject);
       resolveListen();
     });
-  }).catch(async cause => {
-    await rm(publishedRoot, { recursive: true, force: true });
-    throw new Error(`cannot start local control channel: ${cause.message}`);
-  });
+  }).catch(cause => { throw new Error(`cannot start local control channel: ${cause.message}`); });
 
-  const recordInteraction = event => mutate(async () => {
+  const recordInteraction = (event, bytes) => mutate(async () => {
     if (seenEvents.has(event.id)) return;
+    if (seenEvents.size >= MAX_UNIQUE_SUBMISSIONS || retainedSubmissionBytes + bytes > MAX_RETAINED_SUBMISSION_BYTES) {
+      stopSession();
+      throw new Error("session submission limit exceeded");
+    }
     seenEvents.add(event.id);
-    eventLog.push(event);
+    retainedSubmissionBytes += bytes;
+    eventNumber += 1;
+    const numbered = { ...event, event_number: eventNumber };
+    browserEvents.push(numbered);
+    browserEventBytes.push(bytes);
     notifyPullWaiters();
   });
 
@@ -466,20 +536,17 @@ async function start(directory) {
     try { socket?.close(); } catch {}
     for (const connection of controlConnections) connection.destroy();
     await new Promise(resolveClose => controlServer.close(() => resolveClose()));
-    await unlink(socketPath).catch(() => {});
-    await rm(publishedRoot, { recursive: true, force: true });
-    if (attachmentInboxPromise) {
-      try { await rm(await attachmentInboxPromise, { recursive: true, force: true }); } catch {}
-    }
+    await unlink(controlPath(root)).catch(() => {});
     process.exit(code);
   };
+  stopSession = () => { void stop(1); };
   process.once("SIGINT", () => void stop(0));
   process.once("SIGTERM", () => void stop(0));
 
   const retry = () => {
     if (stopped || Date.now() >= retryUntil) return void stop(1);
     retryTimer = setTimeout(() => { retryTimer = undefined; connect(); }, retryDelay);
-    retryDelay = Math.min(retryDelay * 2, MAX_RETRY_DELAY);
+    retryDelay = Math.min(retryDelay * 2, 5_000);
   };
 
   const connect = () => {
@@ -512,15 +579,11 @@ async function start(directory) {
       } else if (packet.type === "session") {
         if (!validSessionUrl(packet.url)) return void stop(1);
         sessionUrl = packet.url;
-        if (!initialPublished) {
-          initialPublished = true;
-          send({ type: "revision" });
-        }
-        if (!ready) { ready = true; process.stdout.write(`${JSON.stringify({ type: "ready", url: sessionUrl, workspace: workspaceId, workspace_sequence: workspaceSequence })}\n`); }
+        if (!ready) { ready = true; process.stdout.write(`${JSON.stringify({ type: "ready", url: sessionUrl, page_event: pageEvent, page_hash: currentPageHash() })}\n`); }
       } else if (packet.type === "http_request") {
-        const requestRoot = publishedRoot;
-        const requestWorkspace = workspaceId;
-        void handleRequest(requestRoot, requestWorkspace, packet, getAttachmentInbox, recordInteraction).then(result => send(result)).catch(() => send(errorResponse(packet, 500, "preview request failed")));
+        const requestPage = page;
+        const requestPageEvent = pageEvent;
+        void handleRequest(root, requestPage, requestPageEvent, packet, recordInteraction).then(result => send(result)).catch(() => send(errorResponse(packet, 500, "preview request failed")));
       } else if (packet.type === "closed") {
         void stop(0);
       } else if (packet.type === "error") {
@@ -534,7 +597,7 @@ async function start(directory) {
       send = () => false;
       socket = undefined;
       if (!credential || !sessionUrl) return void stop(1);
-      if (!retryUntil) retryUntil = Date.now() + GRACE_SECONDS * 1_000;
+      if (!retryUntil) retryUntil = Date.now() + RECONNECT_RETRY_SECONDS * 1_000;
       retry();
     });
   };
@@ -564,7 +627,7 @@ function validSessionUrl(value) {
 }
 
 function usage() {
-  return "Usage:\n  npx letmeknow-cli serve <directory>\n  npx letmeknow-cli pull <directory> [--wait <seconds>]\n  npx letmeknow-cli push <directory> --based-on <token>\n  npx letmeknow-cli ack <directory> --based-on <token>\n";
+  return "Usage:\n  npx letmeknow-cli serve <directory>\n  npx letmeknow-cli show <directory>\n  npx letmeknow-cli pull <directory> [--wait <seconds>]\n  npx letmeknow-cli push <directory> --batch <token> [--updates <file|->]\n";
 }
 
 function commandArgs() {
@@ -576,7 +639,8 @@ function commandArgs() {
         skill: { type: "boolean" },
         help: { type: "boolean", short: "h" },
         wait: { type: "string" },
-        "based-on": { type: "string" }
+        batch: { type: "string" },
+        updates: { type: "string" }
       },
       allowPositionals: true,
       strict: true
@@ -585,24 +649,25 @@ function commandArgs() {
     throw new Error(cause instanceof Error ? cause.message : "invalid arguments");
   }
   if (parsed.values.skill || parsed.values.help) {
-    if (parsed.positionals.length || parsed.values.wait !== undefined || parsed.values["based-on"] !== undefined) throw new Error(usage());
+    if (parsed.positionals.length || parsed.values.wait !== undefined || parsed.values.batch !== undefined || parsed.values.updates !== undefined) throw new Error(usage());
     return { command: parsed.values.skill ? "skill" : "help" };
   }
   const [command, directory, ...extra] = parsed.positionals;
   if (!command || !directory || extra.length) throw new Error(usage());
-  if (command === "serve" && (parsed.values.wait !== undefined || parsed.values["based-on"] !== undefined)) throw new Error(usage());
-  if (command === "pull" && parsed.values["based-on"] !== undefined) throw new Error(usage());
-  if ((command === "push" || command === "ack") && parsed.values.wait !== undefined) throw new Error(usage());
-  if (!["serve", "pull", "push", "ack"].includes(command)) throw new Error(usage());
+  if (!["serve", "show", "pull", "push"].includes(command)) throw new Error(usage());
+  if ((command === "serve" || command === "show") && (parsed.values.wait !== undefined || parsed.values.batch !== undefined || parsed.values.updates !== undefined)) throw new Error(usage());
+  if (command === "pull" && (parsed.values.batch !== undefined || parsed.values.updates !== undefined)) throw new Error(usage());
+  if (command === "push" && parsed.values.wait !== undefined) throw new Error(usage());
   let wait = 0;
   if (parsed.values.wait !== undefined) {
     wait = Number(parsed.values.wait);
     if (!Number.isFinite(wait) || wait < 0) throw new Error("--wait must be a non-negative number");
   }
-  if ((command === "push" || command === "ack") && typeof parsed.values["based-on"] !== "string") throw new Error("--based-on is required");
-  return { command, directory, wait, token: parsed.values["based-on"] };
+  if (command === "push" && typeof parsed.values.batch !== "string") throw new Error("--batch is required");
+  return { command, directory, wait, token: parsed.values.batch, updates: parsed.values.updates };
 }
 
+
 let command;
 try {
   command = commandArgs();
@@ -611,8 +676,15 @@ try {
   else if (command.command === "serve") await start(command.directory);
   else {
     const { root } = await options(command.directory);
-    const result = await connectControl(root, command.command === "pull" ? { type: "pull", wait_seconds: command.wait } : { type: command.command, token: command.token });
-    process.stdout.write(`${JSON.stringify(result)}\n`);
+    let packet;
+    if (command.command === "pull") packet = { type: "pull", wait_seconds: command.wait };
+    else if (command.command === "show") packet = { type: "show" };
+    else {
+      packet = { type: "push", token: command.token, updates: command.updates === undefined ? [] : await readUpdatesInput(command.updates) };
+    }
+    const result = await connectControl(root, packet);
+    if (command.command === "show" && result.ok) process.stdout.write(result.html);
+    else process.stdout.write(`${JSON.stringify(result)}\n`);
     if (!result.ok) process.exitCode = 1;
   }
 } catch (cause) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "letmeknow-cli",
-  "version": "0.6.1",
-  "description": "A live static preview with agent-readable form submissions.",
+  "version": "0.8.0",
+  "description": "A live agent-authored page with structured browser feedback.",
   "files": [
     "bin",
     "SKILL.md"
@@ -30,6 +30,7 @@
     "ws": "^8.21.3"
   },
   "dependencies": {
-    "mrmime": "^2.0.1"
+    "mrmime": "^2.0.1",
+    "parse5": "^8.0.1"
   }
 }