letmeknow-cli 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,8 @@
 # LetMeKnow
 
-LetMeKnow gives an agent a temporary, interactive web surface for a human. The agent sends semantic HTML, receives normalized user actions, and responds with HTML fragments. A constrained HTMX-like runtime handles forms, targets, swaps, pending state, and duplicate submissions in the browser.
+LetMeKnow gives an agent a temporary HTML and CSS workspace for a human. The agent renders a page, receives normalized form and button actions, and responds with HTML fragments. The browser runtime handles validation, form serialization, pending state, and targeted updates.
 
-It is not a localhost proxy, static file server, or arbitrary HTTP tunnel.
+It is not a localhost proxy or a programmable frontend. Agents provide presentation and semantic actions, not JavaScript or HTTP handlers.
 
 ## CLI
 
@@ -20,7 +20,7 @@ LETMEKNOW_URL=http://localhost:8787 npx letmeknow-cli
 
 stdin contains one compact JSON command per line. stdout contains one JSON event per line. Diagnostics go to stderr.
 
-Print the agent-facing instructions without opening a connection:
+Print the agent instructions without connecting:
 
 ```bash
 npx letmeknow-cli --skill
@@ -40,77 +40,136 @@ The CLI emits its temporary URL:
 {"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
 ```
 
-Render the interface:
+The URL immediately serves a styled shell with a waiting message. Send the initial HTML and optional CSS with `render`; a browser that is already open receives it without polling:
 
 ```json
-{"type":"render","id":"render-1","body":"<h1>Approve expense?</h1><dl><dt>Amount</dt><dd>$420</dd></dl><form id=\"decision\" hx-post=\"decide\"><label>Comment<textarea name=\"comment\" required></textarea></label><button hx-post=\"approve\" name=\"decision\" value=\"approve\">Approve</button><button hx-post=\"reject\" name=\"decision\" value=\"reject\">Reject</button></form>"}
+{"type":"render","id":"render-1","body":"<h1>Search invoices</h1><form id=\"search\" action=\"search\" method=\"post\" data-lmk-target=\"results\"><label>Customer<input name=\"customer\" required></label><button>Search</button></form><section id=\"results\"><p>Enter a customer.</p></section>","css":"#results { margin-top: 2rem; }"}
 ```
 
-A successful render is assigned a revision:
+A successful render receives a revision:
 
 ```json
 {"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
 ```
 
-When the human clicks Approve, the CLI emits one normalized action:
+Submitting the form produces one normalized action:
 
 ```json
-{"type":"action","id":"event-1","client_id":"8c05cc18-f503-4d1b-aad9-acde3a41c983","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","method":"POST","action_id":"approve","form_id":"decision","target":"#lmk-view","swap":"innerHTML","trigger":{"id":null,"name":"decision","value":"approve"},"values":{"comment":"Looks good","decision":"approve"}}
+{"type":"action","id":"event-1","client_id":"8c05cc18-f503-4d1b-aad9-acde3a41c983","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","action_id":"search","form_id":"search","target_id":"results","trigger":{"id":null,"name":null,"value":null},"values":{"customer":"Acme Ltd"}}
 ```
 
-Respond with an HTML fragment. The default target is the whole view, so this replaces its contents:
+Respond with HTML for the target's contents:
 
 ```json
-{"type":"response","id":"response-1","request_id":"event-1","body":"<h1>Approved</h1><p>The expense was approved.</p>"}
+{"type":"response","id":"response-1","request_id":"event-1","body":"<table><tr><th>Invoice</th><th>Amount</th></tr><tr><td>INV-42</td><td>$800</td></tr></table>"}
 ```
 
-The response receives a new render revision in its acknowledgement.
+The runtime assigns a new render revision and places the fragment inside `#results`. If `data-lmk-target` had been omitted, it would replace the contents of the whole workspace.
 
-## HTML interaction profile
+## HTML actions
 
-LetMeKnow renders standard semantic HTML with a built-in stylesheet. It recognizes only four HTMX-like attributes:
+### Forms
 
-- `hx-get="action"`
-- `hx-post="action"`
-- `hx-target="#element-id"`
-- `hx-swap="innerHTML|outerHTML"`
+Interactive forms use standard HTML:
 
-Action names contain letters, digits, `.`, `_`, `:`, or `-`. They are identifiers, not URLs. The default target is `#lmk-view` and the default swap is `innerHTML`.
+```html
+<form id="decision" action="decide" method="post">
+  <label>
+    Comment
+    <textarea name="comment"></textarea>
+  </label>
+  <button name="decision" value="approve" formaction="approve">Approve</button>
+  <button name="decision" value="reject" formaction="reject">Reject</button>
+</form>
+```
+
+Requirements:
+
+- `method="post"`
+- A stable form `id`
+- A relative action identifier such as `search`, `approve`, or `invoice:inspect`
+- Meaningful control `name` values
+
+A submit button's standard `formaction` overrides the form's `action`. Native `required`, input types, ranges, and patterns validate locally. `FormData(form, submitter)` is captured before the form is disabled, so selected controls and the clicked submit button are included. Repeated names become string arrays.
+
+### Standalone actions
+
+A button can invoke an action without a form:
+
+```html
+<button type="button" data-lmk-action="refresh-status" data-lmk-target="status">
+  Refresh
+</button>
+```
+
+Its event has `form_id: null`, empty `values`, and the button's optional `id`, `name`, and `value` in `trigger`.
+
+### Targeted updates
+
+`data-lmk-target` accepts one element ID without `#`:
+
+```html
+<button data-lmk-action="load-more" data-lmk-target="results">Load more</button>
+<section id="results"></section>
+```
+
+All updates use `innerHTML`. There are no alternate swap modes or arbitrary selector targets. The default target is the runtime-owned `lmk-view`, which means the whole workspace.
 
-Use ordinary HTML forms and named controls. On submission, LetMeKnow sends the complete form values and identifies the exact submit button through `trigger`. Repeated field names become string arrays. File values are not currently sent.
+Typing, focusing, expanding `<details>`, native validation, scrolling, and other local browser behavior produce no agent events.
 
-The browser handles typing, focus, native validation, and selection locally. These do not produce protocol traffic. Only a completed `hx-get` or `hx-post` interaction reaches the agent.
+## CSS
 
-One interaction per browser client and form may be pending at a time. The runtime disables that form while waiting, and the service rejects duplicate submissions. Different forms and browser tabs remain independent. Every action includes the browser-tab `client_id` and the `render_id` that produced it.
+`render` accepts page-level CSS in its `css` field. A `response` may include `css` to replace the current page CSS; omitting it preserves the current CSS.
 
-Scripts, inline handlers, external styles, frames, external form submissions, and arbitrary browser connections are blocked by the page's Content Security Policy. Other HTMX attributes and extensions have no effect.
+Normal modern CSS is supported, including grid, flexbox, media queries, variables, transitions, and print styles. External stylesheets, `@import`, scripts, inline event handlers, and inline `style` attributes are blocked. CSS and images may reference session assets with relative URLs.
+
+## Assets
+
+`put` stores or replaces passive resources only under `/assets/`:
+
+```json
+{"type":"put","id":"logo","path":"/assets/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
+```
+
+Reference them relatively so local path-based sessions also work:
+
+```html
+<img src="assets/logo.png" alt="Company logo">
+```
+
+Assets answer only `GET` and `HEAD`. Each body is limited to 1 MiB. A session accepts at most 100 assets and 10 MiB of decoded asset data. Assets are removed with the session; there is no `delete` command.
 
 ## Protocol
 
 ### Commands
 
 - `open`: create the session; it must be first.
-- `render`: replace the HTML shown on a fresh visit or refresh.
-- `response`: answer one pending action with an HTML fragment.
-- `close`: immediately destroy the session.
-
-Commands accept an optional string `id`. Successful `render`, `response`, and `close` commands emit a correlated `ack`. `render` and `response` acknowledgements also contain the assigned `render_id`.
+- `render`: set the initial/current HTML and CSS for fresh clients.
+- `put`: store an asset under `/assets/`.
+- `response`: answer one pending action with HTML and optional CSS.
+- `close`: destroy the session immediately.
 
-HTML bodies are UTF-8 strings limited to 1 MiB. Up to 32 interactions may be pending across independent clients and forms. Action request bodies have a 30-second read deadline, and an agent response may take up to five minutes.
+Commands accept an optional string `id`. Successful commands emit correlated `ack` events. `render` and `response` acknowledgements also include the generated `render_id`.
 
 ### Events
 
 - `session`: the public URL and disconnect grace period.
-- `action`: one normalized user interaction.
+- `action`: a normalized form or standalone-button action.
 - `ack`: command completion.
 - `error`: invalid command or protocol state.
 - `closing`: explicit session destruction.
 
-## Lifecycle
+One interaction per browser client, render, form, and target may be pending at a time. Conflicting submissions are rejected, while independent forms and targets can proceed concurrently. Match responses by action ID rather than event order.
+
+HTML, CSS, asset, and action bodies are each limited to 1 MiB. Up to 32 independent actions may be pending. Action bodies have a 30-second read deadline, and an agent response may take up to five minutes.
+
+## Security and lifecycle
+
+HTML fragments are sanitized. Scripts, style elements, inline event handlers, HTMX attributes, frames, active metadata, external form actions, and invalid LetMeKnow attributes are removed. A strict Content Security Policy blocks arbitrary browser connections and external resources. Agent CSS is installed separately in a nonce-protected style element.
 
-The active CLI connection owns the session. It receives a private reconnect credential and automatically reconnects after an unexpected disconnect. The credential never appears on protocol stdout.
+The URL is a bearer secret. Share it only with the intended human.
 
-The rendered interface remains visible during the ten-minute disconnect grace period, but interactions return `503`. Browser traffic does not extend the grace period. `close` destroys everything immediately.
+The CLI owns the session and automatically reconnects after an unexpected disconnect. The shell, current render, and assets remain available during the ten-minute disconnect grace period, but actions fail. Browser traffic does not extend the grace period. `close` destroys everything immediately.
 
 ## Development
 

package/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: letmeknow
-description: Show a human a temporary semantic HTML interface and handle normalized form actions through the LetMeKnow NDJSON CLI.
+description: Show a human a temporary HTML and CSS workspace and handle normalized form or button actions through the LetMeKnow NDJSON CLI.
 ---
 
 # LetMeKnow
 
-Use LetMeKnow when a human needs a temporary rich interface, form, choice, approval, table, or status view. The agent sends HTML and receives only completed semantic actions; typing and other local browser state do not create events.
+Use LetMeKnow when a human needs a temporary rich document, dashboard, report, preview, form, approval, quiz, table, or status view. The agent supplies semantic HTML and CSS. The browser sends only declared actions; typing and other local state do not create events.
 
-LetMeKnow is not a localhost proxy, file server, or arbitrary HTTP tunnel. Do not send JavaScript, CSS, raw HTTP handlers, or application code.
+LetMeKnow is not a localhost proxy, persistent application, or arbitrary JavaScript environment.
 
 ## Start
 
@@ -31,84 +31,128 @@ Wait for the session URL:
 {"type":"session","id":"open-1","url":"https://0123456789abcdef0123.letmeknow.dev/","expires_after_disconnect":600}
 ```
 
-## Render semantic HTML
+The URL immediately serves a shell with a waiting message. It is safe for the human to open it before the first render.
 
-Send an HTML fragment with `render`:
+## Render HTML and CSS
+
+Send an HTML fragment and optional page CSS:
 
 ```json
-{"type":"render","id":"render-1","body":"<h1>Approve expense?</h1><dl><dt>Amount</dt><dd>$420</dd></dl><form id=\"decision\" hx-post=\"decide\"><label>Comment<textarea name=\"comment\" required></textarea></label><button hx-post=\"approve\" name=\"decision\" value=\"approve\">Approve</button><button hx-post=\"reject\" name=\"decision\" value=\"reject\">Reject</button></form>"}
+{"type":"render","id":"render-1","body":"<h1>Search invoices</h1><form id=\"search\" action=\"search\" method=\"post\" data-lmk-target=\"results\"><label>Customer<input name=\"customer\" required></label><button>Search</button></form><section id=\"results\"><p>Enter a customer.</p></section>","css":"#results { margin-top: 2rem; }"}
 ```
 
-Wait for its acknowledgement before directing the human to the URL:
+A browser already waiting at the URL receives the render. Wait for the acknowledgement:
 
 ```json
 {"type":"ack","id":"render-1","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa"}
 ```
 
-Use ordinary semantic HTML: headings, paragraphs, lists, tables, `dl`, forms, labels, inputs, buttons, progress, and images. A built-in stylesheet makes these presentable. Do not include `<html>`, `<head>`, `<body>`, `<main id="lmk-view">`, scripts, inline event handlers, stylesheets, iframes, or external forms.
+Use semantic HTML such as headings, sections, paragraphs, lists, tables, `dl`, forms, labels, controls, buttons, `details`, progress, and images. Do not include `<html>`, `<head>`, `<body>`, `<main id="lmk-view">`, scripts, style elements, inline event handlers, inline `style`, iframes, or HTMX attributes.
+
+The built-in stylesheet makes unstyled HTML usable. The optional `css` field supports normal modern CSS, including grid, flexbox, media queries, variables, transitions, and print styles. External stylesheets, `@import`, and remote resources do not work. Use relative asset URLs.
+
+## Forms
 
-HTML bodies are limited to 1 MiB.
+Interactive forms use standard HTML:
 
-## Declare interactions
+```html
+<form id="decision" action="decide" method="post">
+  <label>Reason<textarea name="reason" required></textarea></label>
+  <button name="decision" value="approve" formaction="approve">Approve</button>
+  <button name="decision" value="reject" formaction="reject">Reject</button>
+</form>
+```
 
-Only these HTMX-like attributes are supported:
+Rules:
 
-- `hx-get="action"`
-- `hx-post="action"`
-- `hx-target="#element-id"`
-- `hx-swap="innerHTML"` or `hx-swap="outerHTML"`
+- Use `method="post"`.
+- Give every interactive form a stable, unique `id`.
+- Give controls meaningful `name` values.
+- Use a relative action identifier containing letters, digits, `.`, `_`, `:`, or `-`.
+- A submit button's standard `formaction` may override the form action.
+- Native `required`, input types, ranges, and patterns validate locally.
 
-Action values are identifiers, not URLs. Use letters, digits, `.`, `_`, `:`, and `-`. Other HTMX attributes and extensions do nothing.
+The runtime captures `FormData(form, submitter)` before disabling the form. Selected radio buttons, checked boxes, ordinary controls, and the clicked submit button are therefore included. Repeated names become string arrays. File values are not currently sent.
 
-The default target is `#lmk-view`, the runtime-owned whole-view container. The default swap is `innerHTML`. Usually omit both and respond with the complete next interface fragment.
+## Standalone actions
 
-Put `hx-get` or `hx-post` on a form, button, or link. A submit button's attribute overrides its form's attribute, allowing distinct actions:
+Use a button when an action does not need a form:
 
 ```html
-<form id="decision" hx-post="decide">
-  <label>Reason<textarea name="reason" required></textarea></label>
-  <button hx-post="approve" name="decision" value="approve">Approve</button>
-  <button hx-post="reject" name="decision" value="reject">Reject</button>
+<button type="button" data-lmk-action="refresh-status" data-lmk-target="status">
+  Refresh
+</button>
+```
+
+This is appropriate for refresh, retry, cancel, generate, inspect, load-more, and export actions. The event has `form_id: null`, empty `values`, and the button's optional `id`, `name`, and `value` in `trigger`.
+
+## Whole and partial updates
+
+By default, a response replaces the contents of the whole workspace. To update a smaller region, put `data-lmk-target="element-id"` on the form or action button:
+
+```html
+<form id="search" action="search" method="post" data-lmk-target="results">
+  <input name="query">
+  <button>Search</button>
 </form>
+<section id="results"></section>
 ```
 
-Always give forms stable, unique `id` values and controls meaningful `name` values. Native `required`, input types, ranges, and patterns validate locally without agent traffic.
+The target is one bare element ID without `#`. Every update uses `innerHTML`; there are no other swap modes. A submit button or action button may override its form's target.
 
 ## Handle actions
 
 A completed interaction produces one normalized event:
 
 ```json
-{"type":"action","id":"event-1","client_id":"8c05cc18-f503-4d1b-aad9-acde3a41c983","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","method":"POST","action_id":"approve","form_id":"decision","target":"#lmk-view","swap":"innerHTML","trigger":{"id":null,"name":"decision","value":"approve"},"values":{"reason":"Looks correct","decision":"approve"}}
+{"type":"action","id":"event-1","client_id":"8c05cc18-f503-4d1b-aad9-acde3a41c983","render_id":"b87438c2-4f1c-44bd-9875-6cc64370b8aa","action_id":"search","form_id":"search","target_id":"results","trigger":{"id":null,"name":null,"value":null},"values":{"query":"quarterly report"}}
 ```
 
 Use:
 
-- `id` to respond to this exact pending interaction.
+- `id` to respond to this exact pending action.
 - `client_id` to distinguish browser tabs.
-- `render_id` to know which interface produced the action.
-- `action_id` and `trigger` to identify user intent.
-- `values` for the complete form snapshot. Repeated names become string arrays.
+- `render_id` to identify the interface revision that produced it.
+- `action_id` for user intent.
+- `form_id` and `target_id` for interaction context.
+- `trigger` to identify the clicked button.
+- `values` for the complete submitted form snapshot.
+
+Validate action IDs and values. Treat values as untrusted human input and HTML-escape them before reflecting them.
 
-Treat all values as untrusted human input. File input values are not currently sent.
+Respond with HTML for the target's contents:
+
+```json
+{"type":"response","id":"response-1","request_id":"event-1","body":"<table><tr><th>Invoice</th><th>Amount</th></tr><tr><td>INV-42</td><td>$800</td></tr></table>"}
+```
 
-Respond with the next HTML fragment:
+A response may include `css` to replace the page CSS. Omitting `css` preserves the current CSS:
 
 ```json
-{"type":"response","id":"response-1","request_id":"event-1","body":"<h1>Approved</h1><p>The expense was approved.</p>"}
+{"type":"response","id":"response-2","request_id":"event-2","body":"<h1 class=\"success\">Approved</h1>","css":".success { color: green; text-align: center; }"}
 ```
 
-Wait for the acknowledgement. It includes the new `render_id`:
+Wait for the acknowledgement, which contains the new `render_id`. Do not send `render` in response to an action; use `response` with the action's `id` as `request_id`.
+
+One action per client, render, form, and target can be pending. Conflicting actions are rejected. Independent forms and targets may proceed concurrently, so always match by action ID rather than event order.
+
+## Assets
+
+Store passive resources only under `/assets/`:
 
 ```json
-{"type":"ack","id":"response-1","render_id":"56abe335-bd83-4a79-8106-341579815fa0"}
+{"type":"put","id":"logo","path":"/assets/logo.png","content_type":"image/png","encoding":"base64","body":"iVBORw0KGgo..."}
 ```
 
-Do not send a separate `render` in response to an action. `response` both resolves the pending browser request and updates that browser's interface. Use `render` only to replace the interface served on a fresh visit or refresh.
+Reference them relatively:
+
+```html
+<img src="assets/logo.png" alt="Company logo">
+```
 
-One action per client and form can be pending. The browser disables that form while waiting, and duplicate submissions are rejected. Different forms and clients can have independent pending actions. Respond using request IDs rather than assuming event order.
+`encoding` is `utf8` by default or `base64` for binary data. Assets answer only `GET` and `HEAD`. There is no `delete`; replacement uses another `put`, and `close` removes all assets.
 
-## Close
+## Close and limits
 
 Destroy the session when finished:
 
@@ -116,8 +160,8 @@ Destroy the session when finished:
 {"type":"close","id":"close-1"}
 ```
 
-Wait for `ack` and `closing`. Closing stdin only disconnects the producer and does not replace explicit `close`.
+Wait for `ack` and `closing`. Closing stdin only disconnects the producer.
 
-The CLI automatically reconnects during a ten-minute disconnect grace period. The interface remains readable while disconnected, but interactions fail. Never expose the private reconnect credential. Treat the public session URL as a bearer secret and share it only with the intended human.
+HTML, CSS, asset, and action bodies are each limited to 1 MiB. A session accepts 100 assets, 10 MiB decoded asset data, and 32 pending actions. Action bodies have a 30-second read deadline; the agent has five minutes to respond.
 
-Limits: 1 MiB per HTML or action body, 32 pending interactions, 30 seconds to read an action body, and five minutes for the agent to respond.
+The CLI reconnects during a ten-minute disconnect grace period. The shell, current render, and assets remain readable while disconnected, but actions fail. Treat the URL as a bearer secret. Never expose the private reconnect credential.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letmeknow-cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A temporary interactive web surface for agents.",
   "files": [
     "bin",