@hazem3500/komo 0.9.2 → 0.9.5

package/NODE.md

@@ -63,7 +63,7 @@ initKomo({
 });
 ```
 
-Point the existing CLI at the same endpoint, project, repository, and branch. `komo login` uses Google when configured; `KOMO_TOKEN` accepts a previously issued session token for a non-interactive bot. Store that token as a secret. It has the same permissions as its user. For example:
+Point the existing CLI at the same endpoint, project, repository, and branch. `komo login` uses Google when configured; `KOMO_TOKEN` accepts a personal access token (create one at `/account?project=KEY` on your server; see Bots and CI in the README) or a previously issued session token for a non-interactive bot. Store that token as a secret. Access tokens are limited by their scopes and projects; session tokens have the same permissions as their user. Optionally set `KOMO_TOKEN_PEPPER` to a long random secret to mix into stored token hashes; changing it revokes every access token. For example:
 
 ```sh
 komo comments list --endpoint https://comments.example.com --project YOUR_GENERATED_PROJECT_KEY --repo your-org/your-repo --branch pr-42 --origin https://pr-42.preview.example.com

package/README.md

@@ -97,7 +97,7 @@ Design mode also takes interaction cues from established design tools: select a
 
 React teams can register selected component roots for typed prop previews through the `./react` entry. A build-time TypeScript Compiler API pass generates the prop manifest from an explicitly marked function component and props type; the inspector edits only strings, numbers, booleans, and literal unions. Functions, `ReactNode`, objects, generics, nullable unions, and any unsupported type remain read-only. This metadata is a safe allowlist, not runtime discovery of every React component; `defaultProps` and every React component form are not inferred.
 
-The app provides an `onChange` callback that updates its own state. Komo previews those values through React's normal render cycle, offers undo/reset, and can prefill an explicit comment with the proposed before/after values and source path. Posting still requires the user to submit the comment. Komo never accesses React Fiber internals or writes source files. Preview prop changes reset on refresh. A component may opt one leaf render into direct text editing by setting `textProp` to the name of an allowed string prop; Komo does not infer which child text belongs to a prop. See [`examples/react-props`](./examples/react-props/README.md) for the generated fixture and limitations.
+The app provides an `onChange` callback that updates its own state. Komo previews those values through React's normal render cycle, offers undo/reset, and can prefill an explicit comment with the proposed before/after values and source path. Posting still requires the user to submit the comment. Komo's core never accesses React Fiber internals and never writes source files; the one exception is the separate, opt-in [React fiber adapter](#discovering-react-components), which reads React internals only for apps that install it. Preview prop changes reset on refresh. A component may opt one leaf render into direct text editing by setting `textProp` to the name of an allowed string prop; Komo does not infer which child text belongs to a prop. See [`examples/react-props`](./examples/react-props/README.md) for the generated fixture and limitations.
 
 ### Opt-in design tokens
 
@@ -107,7 +107,7 @@ Compatible registered tokens appear inside each existing style control, next to
 
 Shared theme edits remain secondary under **Edit shared theme values**. Their explicit Preview action changes the registered variable temporarily and reports the author-declared impact selector/count. This is not a persisted design-system edit; it resets on refresh, widget destruction, or Reset. Selectors are estimates, not proof that every matching element consumes the variable. Both element and shared changes remain previews until the user explicitly submits a comment; Komo does not write CSS or React source. Enable registration only in a trusted development/demo environment, and exclude confidential values from the token list.
 
-This approach uses React Developer Tools as a reference for component props but avoids depending on its browser DevTools UI. TypeScript's compiler can generate type metadata before type erasure, while a host callback keeps live previews within the app's public state model. React 19 is exercised by the fixture; the adapter uses public hooks and DOM refs and does not inspect version-specific React internals.
+This approach uses React Developer Tools as a reference for component props but avoids depending on its browser DevTools UI. TypeScript's compiler can generate type metadata before type erasure, while a host callback keeps live previews within the app's public state model. React 18 and 19 are both exercised (see the fixture); the registration hook uses public hooks and DOM refs and does not inspect version-specific React internals. Only the opt-in React fiber adapter does.
 
 Puck is a useful reference for the **explicit component contract**: its config registers renderable components and declares typed editor fields, defaults, nested object/array fields, and global/component/per-instance edit permissions. Komo borrows the opt-in registration, typed allowlist, contextual controls, and fail-closed edit permissions. It does not reuse Puck's editor/runtime: Puck owns a structured page document and supports component insertion, nesting, drag-and-drop, and publishing, while Komo edits a temporary preview of the host app's existing React state and turns proposed values into a comment. A Puck dependency would add a full page-builder interaction/data model and runtime cost where Komo needs a small optional inspector; Puck's MIT license permits reuse, but licensing is not the deciding constraint. For the first version, nested object/array, slot, custom, and dynamic fields remain read-only until the adapter can represent and validate them safely without implying broader source persistence.
 
@@ -117,15 +117,26 @@ Sources: [Figma layer properties and styles](https://help.figma.com/hc/en-us/art
 
 ### Design-system adapters
 
-`design: { tokens, themes, components }` tells Design mode about your design system. These are types in `DesignSystem`, and all three are optional. komo never guesses tokens from computed styles or reads framework internals; your adapters answer.
+`design: { tokens, themes, components }` tells Design mode about your design system. These are types in `DesignSystem`, and all three are optional. komo never guesses tokens from computed styles, and its core never reads framework internals; your adapters answer. The single exception is the opt-in [React fiber adapter](#discovering-react-components): it is off unless you install it, and it is the only komo code that touches React's private fields.
 
 - `tokens: TokenAdapter` lists tokens (aliases resolved, per theme). For a picked element, it says which token each CSS property uses, or that the value is off-token. It can also preview a token, for example by swapping a utility class, and describe how to apply the change in source.
-- `themes: ThemeAxis[]` are independent axes reviewers can flip, such as light/dark or a product palette. Proposals record the theme state they were made in.
-- `components: ComponentAdapter` identifies the component behind an element (name, props, source), so Design mode shows "Button (variant=secondary)". It works alongside `useKomoInspectable`.
+- `themes: ThemeAxis[]` are independent axes reviewers can flip from the Design panel, such as light/dark or a product palette. Proposals record the theme state they were made in.
+- `components: ComponentAdapter` identifies the component behind an element (name, props, source). Proposals name it with its props. A component registered with `useKomoInspectable` always takes precedence and keeps its editable props. An adapter may also supply `panel(identity)` to show read-only details in the Design panel.
 
-Design proposals also carry a versioned `DesignEdit` record (token swaps, prop changes, text, and a raw CSS fallback) that the CLI and agents can apply.
+Each Design mode comment starts with its context, for example `Theme: mode=dark`, `Component: Button (src/ui/Button.tsx:12)` and `Props: variant="secondary"`. Its changes follow: token swaps, shared token values, prop changes, text, and raw CSS as a fallback. The CLI reads the comment back as a versioned `DesignEdit` record (`theme`, `target.component`, `changes`) that agents can apply; comments without context lines still parse. See [Agent CLI](#agent-cli).
 
-The API is landing in stages, and this section is updated as each part ships. Token adapters work today; themes, components and the `DesignEdit` record follow.
+#### Themes
+
+Each axis gets a row at the top of the Design panel: a segmented control for two or three options, a select for more. Switching calls `apply(id)`, then the panel re-reads `current()`, lists tokens for the new theme state, and refreshes the picked element's values, chips and outline.
+
+```ts
+import { classTheme } from "@hazem3500/komo/adapters/class-theme";
+
+const mode = classTheme({ id: "mode", options: [{ id: "light" }, { id: "dark", class: "dark" }], colorScheme: true });
+initKomo({ project: "your-project", design: { themes: [mode] } });
+```
+
+Theme is context, not an edit. Switching isn't counted as a change, and Undo, Reset and Before/After leave it alone. When Design mode closes, or the widget is destroyed, komo applies each axis's original option again. An axis whose `current()` throws is left out; an `apply()` that throws doesn't break the panel. Any object with `id`, `options`, `current()` and `apply()` works, so a theme kept in React state or a cookie fits too.
 
 #### Token adapters
 
@@ -175,6 +186,40 @@ initKomo({ project: "your-project", design: { tokens: classTokens } });
 
 Keep `resolve()` cheap and honest: report only properties you can vouch for. Define the adapter once, outside render, so `useKomo` sees the same object. The React props demo shows this adapter with `?tokens=classes`.
 
+#### Discovering CSS variables
+
+`discoverCssTokens()` from `@hazem3500/komo/adapters/css-variables` is the no-table option for sites whose tokens are CSS custom properties, including the variables Tailwind v4 emits for `@theme`. It is opt-in, reads `--*` declarations on `:root`/`html` from same-origin stylesheets (cross-origin sheets are skipped), and is meant for development builds.
+
+```ts
+import { discoverCssTokens } from "@hazem3500/komo/adapters/css-variables";
+
+initKomo({ project, design: { tokens: discoverCssTokens() } });
+```
+
+- Tailwind namespaces set the type and the properties a token may style: `--color-*`, `--spacing`/`--spacing-*`, `--radius-*`, `--text-*`, `--font-*`, `--font-weight-*`, `--leading-*`. Other variables are kept only when their value is a color or a length. `--tw-*` is skipped. Paths follow the name, so `--color-brand-500` is `color.brand-500`.
+- A property shows a token only when the element's winning declaration (inline, then stylesheet by `!important`, specificity and order) is exactly one `var()` of a discovered variable. An equal value is not a match.
+- Choosing a token previews `property: var(--name)`, and proposals say `Replace var(--old) with var(--new) for property`, so agents write the reference, not the resolved value.
+- `include(name)` filters variables and `limit` caps the list (300). Values come from the computed style, so they follow the current theme. The scan reruns on every `list()`; `@layer` and `@media` blocks are read, but variables set only under a theme selector such as `[data-mode=dark]` are not listed on their own.
+- Selector-based impact counts and **Edit shared theme values** need `useKomoDesignTokens` and are not part of this adapter.
+
+#### Discovering React components
+
+`discoverReactComponents()` from `@hazem3500/komo/adapters/react-fiber` finds the React component behind a picked element, so Design mode can show its name, props and where it was rendered without registering each component by hand. It is **opt-in and off by default**, and it is the one place komo reads React's private fields. Use it in development builds.
+
+```ts
+import { discoverReactComponents } from "@hazem3500/komo/adapters/react-fiber";
+
+initKomo({ project, design: { components: discoverReactComponents() } });
+// Keep your own adapter first: discoverReactComponents({ adapter: myAdapter })
+```
+
+- **What it reads.** The `__reactFiber$*` key React puts on DOM nodes (or, when present, the renderers of `window.__REACT_DEVTOOLS_GLOBAL_HOOK__`), then `return`/`child` links, `memoizedProps`, `_debugSource` (React 18) and `_debugStack` (React 19 dev). It climbs from the picked element, through shadow hosts, to the nearest function, class, `forwardRef` or `memo` component, and picks that fiber's current copy so props are not stale after updates. Several React roots and renderers on a page are fine.
+- **What it shows.** The panel adds a **Discovered props** group labelled "discovered from React, read-only", with the props and "rendered at `file:line`". The location is where the component was written into JSX (the call site), not where it is defined. React 19 records an Error stack of the generated file; a dev server that serves modules unbundled gives real paths, and otherwise pass `resolveSource(file, line, column)` to map positions (for example through a source map). Proposals also name the component with its primitive props, like any component adapter.
+- **Props are summarized, never run.** Strings, numbers and booleans are shown; arrays and plain objects are cut off by `maxDepth` (3), `maxItems` (6), `maxString` (80) and `maxValue` (240), and `maxProps` caps the list (24). Functions, React elements, symbols, DOM nodes and class instances are described (`ƒ onSave()`, `<button />`), cycles read `[Circular]`, and getters are never invoked. Props named like secrets (`token`, `password`, `apiKey`, `secret`, `auth`…) and anything `redact(name)` matches show as `[redacted]` and are kept out of proposals.
+- **Read-only, and registered components win.** Discovered props are never editable, because komo has no state callback or typed schema for them. A component registered with `useKomoInspectable`, or answered by your own `adapter`, always takes precedence and keeps its editable typed props; around an element inside a registered component the panel keeps showing "Inside *Component*". A component nested inside a registered one that is not registered itself is discovered.
+- **Graceful no-op.** Every access is guarded. Non-React pages, unknown React versions or fiber shapes, production builds and hostile props yield nothing rather than an error. Production React keeps no debug fields, so there is no location; names that look minified (one or two characters) or are missing are not shown. `include(name)` hides components you don't want listed.
+- **Fragile by design.** These fields are private React implementation details, and React can rename or remove them in any release. React 18.3 and 19.2 are tested here (unit tests and a Chrome run of the demo for each); another version may quietly show nothing until the adapter is updated. If that matters more than convenience, register the components you care about with `useKomoInspectable` instead.
+
 #### Tailwind and class themes
 
 Two optional adapters ship as their own entry points, outside the core bundle. For utility-class design systems, a token is a class: komo previews by swapping classes, not by setting CSS variables.
@@ -258,14 +303,44 @@ For an existing inline installation, pass `--project YOUR_PROJECT_KEY --origin h
 
 `--body-file FILE` reads a message from disk; `--body-file -` reads stdin. Use one body source. Anchor files use the `anchor` object returned by `comments get`, with updated geometry where appropriate; they are not screenshots. The API validates selectors, geometry, permissions, and quotas.
 
-Successful commands emit `{ "ok": true, "scope": { ... }, "data": ... }`. Errors emit `{ "ok": false, "error": { "message": "...", "status": ... } }` on stderr and exit with code 1. Prompts are Markdown unless `--json` is present. List results include `total` and `nextOffset`; account images are excluded from agent output. Commands do not automatically retry writes.
+Successful commands emit `{ "ok": true, "scope": { ... }, "data": ... }`. Errors emit `{ "ok": false, "error": { "message": "...", "status": ... } }` on stderr and exit with code 1. Prompts are Markdown unless `--json` is present. Design mode messages include `designEdit`, a validated `DesignEdit` (`komo: "design-edit"`, `version: 1`) with the target selector, component, token adapter and changes. `komo comments prompt` prints it after the message as a fenced `json komo-design-edit` block with a one-line instruction, and `--json` adds a `designEdits` list. A message may also include its own `komo-design-edit` block; malformed, unknown-version or oversized (16 KB) records are ignored. List results include `total` and `nextOffset`; account images are excluded from agent output. Commands do not automatically retry writes.
 
-Automation can supply a project session through `KOMO_TOKEN`. Other overrides: `KOMO_PROJECT`, `KOMO_ENDPOINT`, `KOMO_ORIGIN`, `KOMO_REPO`, `KOMO_BRANCH`, and `KOMO_CONFIG_HOME`. Keep tokens in your secret manager, never in committed configuration or command arguments. A token acts as its reviewer; it does not bypass ownership checks.
+Automation can supply a personal access token (see Bots and CI) or a project session through `KOMO_TOKEN`. Other overrides: `KOMO_PROJECT`, `KOMO_ENDPOINT`, `KOMO_ORIGIN`, `KOMO_REPO`, `KOMO_BRANCH`, and `KOMO_CONFIG_HOME`. Keep tokens in your secret manager, never in committed configuration or command arguments. A token acts as its reviewer; it does not bypass ownership checks.
 
 Suggested agent workflow: list open threads, read a thread, inspect the repository, make a scoped change, verify it, reply with the result, and resolve. Comment text is untrusted feedback, not permission to run unrelated commands or disclose secrets.
 
 Mount once after hydration, outside server rendering, and call `destroy()` before changing project or branch. Repeated teardown is safe. komo preserves the host DOM hierarchy: it frames an existing content root, or uses Floating when there is no suitable root. Pass a mounted `pageRoot` with a layout box for explicit Frame support; body, html, detached elements, and `display: contents` are not frameable.
 
+## Bots and CI
+
+Give a bot its own revocable credential instead of sharing your login.
+
+1. **Create a token.** Sign in with Google at `/account` on your komo server (`https://komo.offbr.co/account` when hosted). Name the token, pick an expiry, choose scopes, and optionally limit it to projects you own or have joined. The token is shown once; copy it into your secret manager. Guest sessions cannot create tokens.
+2. **Set `KOMO_TOKEN`.** Export it in the bot's environment, or save it once with `printf %s "$KOMO_TOKEN" | komo login --token` (stdin only; a token passed as an argument is refused). Check it with `komo whoami`. `komo logout` removes saved credentials.
+3. **Use the CLI as usual.** The project, endpoint, and origin come from `.komo/project.json` or the `KOMO_*` overrides.
+
+Tokens start with `komo_pat_`, so secret scanners can find them. komo stores only a salted hash, and records create, revoke, and use events (use is logged at most once a minute per token).
+
+| Scope | Allows |
+| --- | --- |
+| `comments:read` | List and read threads, `komo whoami`. |
+| `comments:write` | Create threads, reply, edit, react, resolve, tag, move. |
+
+A token acts as its owner, narrowed by its scopes and project list: it never passes an ownership check or private-project invitation its owner would fail, and it cannot manage tokens, projects, members, or webhooks. Credentials resolve in this order: `KOMO_TOKEN`, a token saved by `komo login --token`, then a browser login session.
+
+**Rotate** by creating a replacement, updating the secret, confirming `komo whoami`, then revoking the old token. Prefer an expiry of 90 days or less. **Revoke** from `/account`; the token stops working on its next request (HTTP 401), and so does an expired one.
+
+GitHub Actions:
+
+```yaml
+- name: Export open feedback
+  env:
+    KOMO_TOKEN: ${{ secrets.KOMO_TOKEN }} # a comments:read token, limited to this project
+  run: npx --no-install komo comments prompt
+```
+
+Add the token under **Settings → Secrets and variables → Actions**. Self-hosted servers can set `KOMO_TOKEN_PEPPER` (a long random secret) to mix into stored hashes; changing it revokes every token.
+
 ## How it works
 
 The package adds an isolated ShadowRoot to your site. Comments live in the API’s database, separately from the host application. Reviewers using the same project and scope see the same feedback. Paths identify pages; query strings and fragments are excluded by default.

package/cli/agent.mjs

@@ -15,6 +15,7 @@ import { createServer } from "node:http";
 import { spawn } from "node:child_process";
 import { branchName } from "./config.mjs";
 import { agentWorkflow, agentPrompt } from "../dist/agent-prompt.js";
+import { designEditFromComment, formatDesignEdit } from "./design-edit.mjs";
 
 import { installAgentWorkflow } from "./workflow.mjs";
 
@@ -46,8 +47,9 @@ export const agentCommands = [
 export const agentHelp = `
 Agent commands:
   komo login                 Sign in with Google once for this project
-  komo whoami                Check the current session
-  komo logout                Revoke and remove the saved session
+  komo login --token         Save an access token read from stdin (bots and CI)
+  komo whoami                Check the current credentials
+  komo logout                Revoke the saved session and remove saved credentials
   komo comments list         Read open feedback as JSON
   komo comments get ID       Read a thread with all replies and context
   komo comments prompt       Export open feedback as an agent prompt
@@ -68,12 +70,14 @@ ${Object.entries(actions)
 Settings: .komo/project.json (searched upward), or --project KEY.
 Overrides: --endpoint URL --origin SITE_URL --repo OWNER/REPO --branch NAME
 Bodies: --body TEXT, --body-file FILE, or --body-file - for stdin.
-Credentials: Google login, or KOMO_TOKEN for non-interactive use. Never commit tokens.
+Credentials: KOMO_TOKEN, then a saved access token, then a Google login session. Never commit tokens.
+Create access tokens at /account on your komo server; pass one with: printf %s "$TOKEN" | komo login --token
 Results are JSON except prompt (Markdown unless --json). Errors are JSON on stderr.
+Design mode messages also carry designEdit: a parsed komo DesignEdit v1 record.
 `;
 
 function parse(args) {
-  const booleans = new Set(["--json", "--remove", "--no-open"]);
+  const booleans = new Set(["--json", "--remove", "--no-open", "--token"]);
   const values = new Set([
     "--out",
     "--file",
@@ -184,15 +188,51 @@ function credentialPath(config, env) {
     `${key}.json`
   );
 }
-async function readToken(path, env) {
-  if (env.KOMO_TOKEN) return env.KOMO_TOKEN;
+const PERSONAL_TOKEN = /^komo_pat_[a-z0-9]{12}_[A-Za-z0-9_-]{43}$/;
+// A personal access token works for every project on one server, so it is
+// stored per endpoint, beside the per-project login sessions.
+function personalTokenPath(config, env) {
+  const key = createHash("sha256").update(config.endpoint).digest("hex");
+  return join(
+    env.KOMO_CONFIG_HOME || join(homedir(), ".config", "komo"),
+    `pat-${key}.json`
+  );
+}
+async function readSaved(path) {
   try {
-    return JSON.parse(await readFile(path, "utf8")).token;
+    return JSON.parse(await readFile(path, "utf8")).token || null;
   } catch (error) {
     if (error.code !== "ENOENT") throw error;
     return null;
   }
 }
+// Precedence: KOMO_TOKEN, then a saved access token, then a login session.
+async function readCredentials(sessionPath, patPath, env) {
+  const saved = { session: await readSaved(sessionPath), pat: await readSaved(patPath) };
+  const [source, token] = env.KOMO_TOKEN
+    ? ["env", env.KOMO_TOKEN]
+    : saved.pat
+      ? ["token", saved.pat]
+      : saved.session
+        ? ["session", saved.session]
+        : [null, null];
+  return { source, token, saved };
+}
+async function readTokenFromStdin() {
+  if (process.stdin.isTTY)
+    throw Error("Pipe the token on stdin, for example: printf %s \"$TOKEN\" | komo login --token");
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length;
+    if (bytes > 512) throw Error("That does not look like a komo access token.");
+    chunks.push(chunk);
+  }
+  const token = Buffer.concat(chunks).toString("utf8").trim();
+  if (!PERSONAL_TOKEN.test(token))
+    throw Error("Expected a komo access token (komo_pat_…) on stdin.");
+  return token;
+}
 async function saveToken(path, token) {
   await mkdir(dirname(path), { recursive: true, mode: 0o700 });
   await chmod(dirname(path), 0o700);
@@ -232,7 +272,9 @@ export function apiClient(config, token) {
     if (!response.ok) {
       const error = Error(
         response.status === 401
-          ? "Session missing or expired. Run komo login."
+          ? token?.startsWith("komo_pat_")
+            ? "Access token invalid, expired, or revoked. Create a new one at /account."
+            : "Session missing or expired. Run komo login."
           : result.error || `Request failed (${response.status}).`
       );
       error.status = response.status;
@@ -402,8 +444,16 @@ export async function runAgent(
   args,
   { cwd = process.cwd(), env = process.env } = {}
 ) {
+  if (args.some((arg) => arg.includes("komo_pat_") || arg.startsWith("--token=")))
+    throw Error(
+      "Never pass a token as an argument: it would appear in shell history and process lists. Pipe it on stdin: printf %s \"$TOKEN\" | komo login --token"
+    );
   const { flags, positional } = parse(args);
   const [command, action = "list", threadId, commentId] = positional;
+  if (flags.token && (command !== "login" || positional.length > 1))
+    throw Error(
+      "Use --token only as: printf %s \"$TOKEN\" | komo login --token. The token itself goes on stdin, never in an argument."
+    );
   if (command === "agents") {
     if (
       action !== "setup" ||
@@ -426,8 +476,10 @@ export async function runAgent(
         {
           version: 1,
           commands: actions,
-          auth: "komo login",
+          auth: "KOMO_TOKEN, komo login --token (stdin), or komo login",
           output: "JSON; prompt is Markdown unless --json",
+          designEdit:
+            "Design mode messages carry designEdit (komo DesignEdit v1); prompt prints it as a json komo-design-edit block",
           context: ".komo/project.json or --project KEY",
           overrides: ["--endpoint", "--origin", "--repo", "--branch"],
           body: ["--body", "--body-file", "--body-file -"],
@@ -457,27 +509,46 @@ export async function runAgent(
     throw Error("Unexpected positional arguments. Run komo --help.");
   const config = await configuration(flags, cwd, env),
     path = credentialPath(config, env);
-  const token = await readToken(path, env),
+  const patPath = personalTokenPath(config, env);
+  const { source, token, saved } = await readCredentials(path, patPath, env),
     request = apiClient(config, token);
   if (command !== "logout" && config.repo === config.project) {
     const metadata = await request("config");
     if (metadata.repo) config.repo = metadata.repo;
   }
   let data;
-  if (command === "login") data = { user: await login(config, path, flags) };
+  if (command === "login" && flags.token) {
+    const given = await readTokenFromStdin();
+    // Verify against the API before saving, so a typo never replaces a working token.
+    const { user } = await apiClient(config, given)("me");
+    await saveToken(patPath, given);
+    data = { user, auth: "token" };
+  } else if (command === "login")
+    data = { user: await login(config, path, flags) };
   else {
     if (!token)
-      throw Error("No saved session. Run komo login, or set KOMO_TOKEN.");
+      throw Error(
+        "Not signed in. Run komo login, pipe a token to komo login --token, or set KOMO_TOKEN."
+      );
     if (command === "project")
       data = await runProject(action, flags, request, config, cwd);
-    else if (command === "whoami") data = await request("me");
+    else if (command === "whoami") data = { ...(await request("me")), auth: source };
     else if (command === "logout") {
-      try {
-        await request("me", "DELETE");
-      } catch (error) {
-        if (error.status !== 401 && error.status !== 404) throw error;
-      }
+      // Only login sessions are revoked here. Access tokens are revoked on
+      // the account page, so logout never destroys a token other jobs share.
+      const session = env.KOMO_TOKEN && !env.KOMO_TOKEN.startsWith("komo_pat_")
+        ? env.KOMO_TOKEN
+        : saved.session;
+      if (session)
+        try {
+          await apiClient(config, session)("me", "DELETE");
+        } catch (error) {
+          if (error.status !== 401 && error.status !== 404) throw error;
+        }
       await rm(path, { force: true });
+      await rm(patPath, { force: true });
+      if (env.KOMO_TOKEN)
+        console.error("KOMO_TOKEN is still set in this environment; unset it to stop using it.");
       data = { signedOut: true };
     } else if (["list", "get", "prompt"].includes(action)) {
       let threads = (
@@ -488,14 +559,21 @@ export async function runAgent(
         ...thread,
         comments: thread.comments
           .filter((comment) => comment.body !== "[Comment deleted]")
-          .map((comment) => ({
-            ...comment,
-            author: {
-              id: comment.author.id,
-              name: comment.author.name,
-              verified: comment.author.verified,
-            },
-          })),
+          .map((comment) => {
+            const designEdit = designEditFromComment(
+              comment.body,
+              thread.anchor?.selector
+            );
+            return {
+              ...comment,
+              author: {
+                id: comment.author.id,
+                name: comment.author.name,
+                verified: comment.author.verified,
+              },
+              ...(designEdit ? { designEdit } : {}),
+            };
+          }),
         resolvedBy: thread.resolvedBy
           ? {
               id: thread.resolvedBy.id,
@@ -524,12 +602,29 @@ export async function runAgent(
                       flags.page === "/" ? "/" : flags.page.replace(/\/$/, ""),
                   }
                 : {}),
+              annotate: (comment) =>
+                comment.designEdit && formatDesignEdit(comment.designEdit),
             }) || "No open comments.";
           if (!flags.json) {
             console.log(prompt);
             return;
           }
-          data = { prompt };
+          const page =
+            flags.page && (flags.page === "/" ? "/" : flags.page.replace(/\/$/, ""));
+          data = {
+            prompt,
+            designEdits: threads
+              .filter((thread) => !thread.resolved && (!page || thread.page === page))
+              .flatMap((thread) =>
+                thread.comments
+                  .filter((comment) => comment.designEdit)
+                  .map((comment) => ({
+                    thread: thread.id,
+                    comment: comment.id,
+                    designEdit: comment.designEdit,
+                  }))
+              ),
+          };
         } else {
           const status = flags.status || "open";
           if (!["open", "resolved", "all"].includes(status))