kaloko 0.4.4 → 0.4.8

package/README.md

@@ -64,6 +64,23 @@ npx kaloko share --pr                 # upload to kaloko.app, comment on the PR
 `npx kaloko help` lists every command. When something does not work (Chrome,
 token, environment URL, evaluator key), `npx kaloko doctor` says what to fix.
 
+## Review only what changed
+
+After `kaloko share`, steps that look exactly as they did in the last accepted
+run (same screenshots, same criteria, automatic checks passing) keep the
+approval a person gave them, with who and when. The rest waits in review
+mode: one step at a time on the canvas, `J`/`K` to move, `A` to approve, `R`
+to return with a note. The share says it in one line:
+
+```
+12 steps unchanged, approvals carried over; 5 need review: https://kaloko.app/acme/runs/…/#review
+```
+
+`npx kaloko review` (or `--json`, or MCP `get_review_queue`) tells an agent
+what still waits for a person, so it can pass the link on. Agents never
+approve for people: their decisions are marked and do not count as a
+person's.
+
 ## Design (Kaloko Design)
 
 Design the screens of a flow as live HTML with your own agent and skills, in the same scenario that development
@@ -121,8 +138,9 @@ captured HTML, page text and console output.
 - **E-mails**: built-in Mailpit client; any other mailbox through a small
   adapter module (`provider: script`, example in `templates/mail/`), or hand a
   message over with `npx kaloko mail --step <id> --file message.eml`.
-- **Service and evaluator**: `KALOKO_TOKEN` for `share`, `feedback`, `inbox` and clean-up (`runs`, `trash`, `prune`, `keep`, `archive`)
-  (create it in your organization's settings); `TYPESAFE_API_KEY` for the
+- **Service and evaluator**: `KALOKO_TOKEN` for `share`, `feedback`, `review`, `inbox` and clean-up (`runs`, `trash`, `prune`, `keep`, `archive`)
+  (`npx kaloko login` approves one in the browser and saves it to `~/.config/kaloko/.env`, or create it in your
+  organization's settings); `TYPESAFE_API_KEY` for the
   semantic evaluator (optional). Both names can be changed in the config.
 
 `npx kaloko doctor` checks that every variable the config names is set and that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kaloko",
-  "version": "0.4.4",
+  "version": "0.4.8",
   "description": "See what your AI agents built: every screen, language and device walked, assessed and approved on one canvas.",
   "keywords": [
     "qa",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test --test-timeout=300000 test/*.test.mjs worker/test/*.test.mjs"
+    "test": "node --test --test-timeout=900000 test/*.test.mjs worker/test/*.test.mjs"
   },
   "dependencies": {
     "ajv": "^8.20.0",

package/skills/kaloko/SKILL.md

@@ -28,8 +28,9 @@ the canvas, storage and collaboration are the service.
   `kaloko capture` run `kaloko evaluate`) and `kaloko build` ran; you report the summary line,
   failing criteria with evidence, and the preview path (or shared URL).
 - When the run was shared, its URL and the summary are in the issue or PR
-  the work belongs to, and you read `kaloko feedback` and `kaloko inbox`
-  before continuing on that task.
+  the work belongs to, the person got the review-mode link with what waits
+  for them (`kaloko share` prints it; `kaloko review` repeats it), and you
+  read `kaloko feedback` and `kaloko inbox` before continuing on that task.
 - Changes to intent are written back to `ACCEPTANCE.md` (change log row).
 - On a design environment: the folder follows the bundle rules and
   `kaloko design lint` shows no error, `kaloko walk` and `kaloko sync` ran,
@@ -56,12 +57,17 @@ a step in a sync conflict (`--mine`), turning on `html_view`, a real clean-up
 (`kaloko prune --yes`), trashing someone else's run, archiving a scenario, and
 anything the environment profile blocks. Never trash an accepted run, a
 baseline, a run with review comments, or a run linked from an open PR or issue
-comment. Ask the person
+comment. Never approve a
+step or accept a run on a person's behalf; report what waits for them
+(`kaloko review`, MCP `get_review_queue`) instead. Ask the person
 for secret values (passwords, tokens, gate credentials) and for sign-ins only
 they can do; never write secrets into the config, a scenario or a script.
 
 ## Where to look
 
+- A new project or an organization without runs of its own (install, sign in,
+  the sample run, the first flow from a URL or a task, share, point the person
+  to the canvas): [reference/first-run.md](reference/first-run.md)
 - Writing or updating the plan and scenario: [reference/acceptance.md](reference/acceptance.md)
 - Android, iOS (Simulator), Electron and macOS apps, or screens captured by
   another tool (Maestro, Appium, XCUITest) with their UI tree:
@@ -75,8 +81,9 @@ they can do; never write secrets into the config, a scenario or a script.
 - Environments, access (gates, accounts, sign-in), e-mails, readonly and
   production rules, and what is yours to arrange for the project's stack:
   [reference/environments.md](reference/environments.md)
-- Sharing, reviewer feedback, mentions, inbox, verdicts and baselines, and
-  cleaning up runs (trash, prune, keep, archive):
+- Sharing, review mode and approvals carried over unchanged steps, reviewer
+  feedback, mentions, inbox, verdicts and baselines, and cleaning up runs
+  (trash, prune, keep, archive):
   [reference/collaboration.md](reference/collaboration.md)
 - Reading runs, feedback and the inbox over MCP instead of the CLI:
   [reference/mcp.md](reference/mcp.md)

package/skills/kaloko/reference/collaboration.md

@@ -4,7 +4,10 @@ A run is only worth something once the people who decide have seen it. The
 loop teams use:
 
 1. **Share the run** (`kaloko share`, tester token, after asking). The
-   command prints the canvas URL.
+   command prints the canvas URL and one line on what waits for a person,
+   e.g. `12 steps unchanged, approvals carried over; 5 need review: <link>`.
+   Give the person that review-mode link (it ends in `#review`) with the
+   counts, not just the canvas.
 2. **Put the link where the work is tracked.** When the branch has a pull
    request and `gh` is signed in, `kaloko share --pr` posts one comment per
    scenario on it (summary line, canvas link, criteria that need attention
@@ -19,7 +22,10 @@ loop teams use:
    that waits for review and turns green or red with the verdict; do not
    report it as passed before a person accepted the run.
 3. **Read feedback before continuing.** `kaloko feedback` lists the run
-   verdict, open rejections and comments, and failed manual criteria.
+   verdict, returned steps first (with the reviewer's note), open comments,
+   failed manual criteria and how many steps still wait for a person.
+   `kaloko review` (or MCP `get_review_queue`) says exactly what a person
+   still has to decide; see *Review mode* below.
    `kaloko inbox` lists what needs your attention across runs: mentions,
    returned runs, rejected steps in your runs, new runs of scenarios you
    reviewed, and expiry warnings. Both take `--json`; `kaloko inbox --read`
@@ -31,6 +37,34 @@ loop teams use:
    reply in the tracker with the new link. The reviewer who returned it is
    told about the new run automatically.
 
+## Review mode
+
+Reviewers decide in **review mode** on the canvas (`Q`, the Review button,
+or a link ending in `#review`): one step at a time, the steps that need a
+person first (failed, returned, the AI was unsure or did not evaluate,
+changed since the last accepted run, open comments), with the accepted run
+beside it. `J`/`K` move, `A` approves, `R` returns with a note, `C`
+comments; at the end they accept or return the run.
+
+- **Approvals carry over unchanged steps.** When a new run is shared, a step
+  whose screenshots are byte-identical to the last accepted run, whose
+  criteria are the same and whose deterministic checks pass keeps the
+  approval a person gave it there, with its origin (who, when, which run).
+  Only changed or failing steps go to the queue. Anyone can revoke a carried
+  approval; the step then waits again. Organizations on Business can turn
+  this off (Settings → Approvals).
+- A carried approval never accepts the run and never counts for required
+  approvers: the run verdict is always a person's decision.
+- **Report what waits**, do not decide it: run `kaloko review` (add `--json`
+  for the data, `--run <id>` for another run) or MCP `get_review_queue` and
+  tell the person how many steps wait and give them `review_url`.
+- **Never approve or accept on a person's behalf.** Decisions by tokens and
+  agents (MCP `decide_step`, `add_comment` with `approved`) are recorded as
+  yours, shown apart, and do not count as a person's unless the organization
+  allows it. Return a step only when you found a real problem, with a note.
+- Returned steps are feedback: fix them, share a new run, and resolve the
+  thread with what changed (see below).
+
 ## Processing feedback
 
 Comments are threads in three places:
@@ -195,6 +229,15 @@ Settings → Storage (keep the newest N per scenario and environment).
 Everything above is available over the API with an organization token:
 
 - `GET /api/v1/orgs/<org>/feedback?run=<id|latest>[&scenario=<id>]`
+- `GET /api/v1/orgs/<org>/runs/<id>/review-queue` (or
+  `GET /api/v1/orgs/<org>/review-queue?run=<id|latest>&scenario=<id>`):
+  `items` in review order with `reasons`, `decision` (approved, returned or
+  carried, with who and how), `unconfirmed` (an agent's or token's decision
+  that does not count), `changed`, criteria with evidence, `screenshots` and
+  `ref_screenshots`; `carried` with provenance; `counts` (`queue`,
+  `decided`, `pending`, `carried`, `clear`); `reference` (the accepted run);
+  `review_url`. Decisions use the comment and verdict routes;
+  `POST …/runs/<id>/carried/<step>/revoke` revokes a carried approval.
 - `GET|POST /api/v1/orgs/<org>/runs/<id>/comments` (a step: `node_id`;
   the whole run: `node_id: ""`), `GET|POST …/scenarios/<id>/comments`
   (the whole flow), and per comment `PATCH`, `DELETE`, `POST …/<cid>/resolve`

package/skills/kaloko/reference/evaluation.md

@@ -61,3 +61,8 @@ it was not evaluated.
 
 `needs_review` is not a failure: look at the screenshot and state your
 reading, or leave it to the reviewer.
+
+After a share, steps that did not change since the last accepted run keep a
+person's approval; only the rest waits in review mode. Report it as the
+share prints it ("12 steps unchanged, approvals carried over; 5 need review:
+<link>") and never call a carried or agent approval a person's acceptance.

package/skills/kaloko/reference/first-run.md

@@ -0,0 +1,51 @@
+# First run in a new project
+
+Use this when the project has no `kaloko.config.yml` yet, or the organization
+has no shared run of its own. The goal is one real flow on the canvas, shared,
+with a person who knows where to approve it.
+
+## Where the organization stands
+
+- `GET /api/v1/orgs/<org>/getting-started` (MCP tool `get_started`) answers
+  `stage` (`empty`, `sample`, `active`), the sample run's URL, how many real
+  runs exist, the next steps and a prompt to start from.
+- Every new organization has a **sample run**: a tea-shop checkout in Czech
+  and English on desktop and mobile, with one failing step per language, one
+  overflow on the phone and one criterion waiting for a person. It does not
+  count toward the plan and expires after 30 days. `<service>/<org>/sample`
+  opens it; it carries a short guide for the person (open a step, approve,
+  return with a note, share).
+- If the person has never reviewed a run, send them the sample link first:
+  they learn the canvas there, not on your first draft. When it is gone,
+  `POST /api/v1/orgs/<org>/sample` (MCP `add_sample_run`, needs an upload or
+  full token) adds it again. Do not delete it unless asked
+  (`DELETE /api/v1/orgs/<org>/sample`).
+
+## From zero to a first shared run
+
+1. `npm install --save-dev kaloko`, then
+   `npx kaloko init --agent claude --org <org>` (it prints the sample link
+   and these steps). Fill `environments` in `kaloko.config.yml` with the URL
+   the app runs on.
+2. `npx kaloko login`: the person approves a token in the browser. Ask them
+   to; never create or paste tokens yourself.
+3. `npx kaloko doctor` and fix what it marks ✕.
+4. Draft the first scenario:
+   - public pages: `npx kaloko draft <url> [url…]` writes a read-only
+     production scenario and a plan; sharpen purposes and criteria;
+   - a task or the main flow of the app: write `ACCEPTANCE.md` and
+     `qa/scenario.yml` as in [acceptance.md](acceptance.md). Pick the flow a
+     person would show a client (sign-up, checkout, the main form), not every
+     page.
+5. `npx kaloko validate qa/scenario.yml`, then
+   `npx kaloko start --scenario qa/scenario.yml --env local`, `kaloko walk`,
+   `kaloko build`. Fix scenario mechanics until every step has a capture.
+6. Ask before `kaloko share` (see *Ask first* in SKILL.md). After sharing,
+   give the person the canvas URL and say what to look at: the failing
+   criteria with their evidence and the steps that need a decision.
+7. Read `kaloko feedback` when they have looked; fix what they returned and
+   walk again.
+
+Done means: the scenario validates, the run is shared, its URL and summary
+line are in your reply (and in the issue or PR the work belongs to), and the
+person knows whether the sample or this run is what they should open.

package/skills/kaloko/reference/mcp.md

@@ -28,8 +28,13 @@ file.
 | `list_notifications` | the token owner's inbox (`unread_only`, `limit`) |
 | `list_projects` | projects of the organization with counts; the slug is the `project` filter of `list_runs` and the value for `project:` in a scenario |
 | `get_criteria_verdicts` | reviewer verdicts on manual or overridden criteria of a run |
+| `get_review_queue` | what a person still has to decide in a run (`run_id`, or `scenario` / nothing for the newest run): steps in review order with reasons, decisions, approvals carried over unchanged steps with their origin, counts and `review_url` to give the person |
+| `decide_step` | records your (the agent's) decision on a step: `approve`, or `return` with a `note`; marked as an agent's and not counted as a person's. Never use it to approve for a person |
+| `revoke_carried_approval` | revokes an approval carried over to a step that looks unchanged but should be looked at again (`run_id`, `step`) |
 | `get_step_assets` | documentation layer (Business): newest capture of every step of a scenario with stable image, HTML and metadata URLs (`scenario`, `step`, `locale`, `viewport`, `accepted`) |
 | `list_step_changes` | documentation layer: steps whose capture or status changed since the previous accepted run or `since` (`scenario`, `since`, `accepted`); see [documentation.md](documentation.md) |
+| `get_started` | where the organization stands (`empty`, `sample`, `active`), its sample run, the next steps and a prompt; call it in a new project, see [first-run.md](first-run.md) |
+| `add_sample_run` | adds the sample run (or returns the one there is); needs an upload or full token and the Developer / Tester role |
 
 ## Comment tools
 

package/src/cli.mjs

@@ -1,6 +1,7 @@
 import { writeFile, access, readFile, mkdir } from 'node:fs/promises'
 import { existsSync } from 'node:fs'
 import { gzipSync } from 'node:zlib'
+import { createHash } from 'node:crypto'
 import { join, resolve, relative, dirname } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import yaml from 'js-yaml'
@@ -29,8 +30,11 @@ import { resolveItems, fieldsOf, DEFAULT_LIMIT } from './lib/stack.mjs'
 import { DEFAULTS as JEV_DEFAULTS } from './lib/jev.mjs'
 import { expandPacks } from './lib/packs.mjs'
 import { upsertPrComment } from './lib/pr.mjs'
+import { formatReviewQueue, shareReviewLine } from './lib/review.mjs'
 import { htmlViewAllowed } from './lib/htmlview.mjs'
-import { service } from './lib/service.mjs'
+import { service, serviceUrl } from './lib/service.mjs'
+import { login } from './lib/login.mjs'
+import { initNextSteps, loginNextSteps } from './lib/onboarding.mjs'
 import { walkDesign, syncDesign, publishVersion, historyCmd, referenceCmd, tokensCmd, exportLive, localRevisions, branchCmd, uploadBlobs } from './lib/design-cli.mjs'
 import { designDir, readBase, headKey } from './lib/design.mjs'
 import { lintDesign, formatLint } from './lib/design-lint.mjs'
@@ -51,6 +55,10 @@ Project
                                     pages (title, description, H1) with the seo, a11y, perf and console packs
   init [--agent claude|codex|all] [--org <slug>]
                                     Create ${CONFIG_FILE} and install the kaloko skill for your agent
+  login [--org <slug>] [--url <service>] [--print] [--no-open]
+                                    Sign this machine in through the browser: approve the code on kaloko.app, choose
+                                    the organization and what the token may do; the token (at most 30 days) goes to
+                                    ~/.config/kaloko/.env, or is printed with --print
   doctor [--json] [--fix]           Check Node, Chrome, config, environments, browser ports, token, evaluator key
                                     and app tools; --fix asks macOS for the desktop capture permissions
   validate <scenario.yml>... [--coverage [--source ACCEPTANCE.md]]
@@ -106,7 +114,11 @@ Results
   share [--expires 30] [--pr]       Upload the run to kaloko.app (KALOKO_TOKEN, tester role);
                                     --pr adds or updates one comment on the branch's pull request via gh
   feedback [--run id] [--scenario id] [--json]
-                                    Open threads from reviewers (steps, the whole run, the whole flow) with ids and replies
+                                    Open threads from reviewers (steps, the whole run, the whole flow) with ids and replies;
+                                    returned steps first, with their notes
+  review [--run id] [--scenario id] [--json]
+                                    What a person still has to decide on a shared run (failed, unsure, changed, returned,
+                                    commented steps), approvals carried over unchanged steps, and the review-mode link
   comment [--step id | --flow] --note "…" [--status rejected|approved] [--run id] [--scenario id]
   comment --reply|--resolve|--reopen|--edit|--delete <id> [--note "…"] [--flow]
                                     Comment, answer and close feedback from the CLI (resolve with "Fixed in <commit>")
@@ -558,7 +570,13 @@ const commands = {
       await cp(join(packageRoot, 'templates', 'steps', 'consent.mjs'), consentStep)
       say('Added qa/flows/steps/consent.mjs (accepts the consent dialog, if the site has one)')
     }
-    say(`Next: create a tester token in the app (Settings → API tokens) and put KALOKO_TOKEN into .env.\nScenario template: ${join(packageRoot, 'templates', 'scenario.yml')}`)
+    // the organization's sample run and the way to a first real flow (src/lib/onboarding.mjs)
+    let written = ''
+    try { written = await readFile(existsSync(file) ? file : join(cwd, LEGACY_CONFIG_FILE), 'utf8') } catch {}
+    const org = typeof args.org === 'string' ? args.org : (written.match(/^org:\s*["']?([a-z0-9-]+)["']?\s*$/m) || [])[1]
+    const base = serviceUrl({ share: { url: (written.match(/^share:[ \t]*\n(?:[ \t]+.*\n)*?[ \t]+url:[ \t]*["']?(https?:\/\/[^\s"']+)/m) || [])[1] } })
+    say(initNextSteps({ base, org }).join('\n'))
+    say(`Scenario template: ${join(packageRoot, 'templates', 'scenario.yml')}`)
   },
 
   async validate (args) {
@@ -995,9 +1013,10 @@ const commands = {
     const body = async (p) => { const raw = await readFile(join(run.dir, p)); const gz = /\.(html|json)$/.test(p) && raw.length > 512; return { data: gz ? gzipSync(raw, { level: 6 }) : raw, gz } }
     // the file list goes first: the service checks limits once and each upload is then a plain write
     // (an older service without the plan answers 404/405 and every upload checks itself, as before)
-    if (files.size > 20) {
+    // screenshots name their SHA-256: the service checks it on arrival and compares unchanged steps with it
+    if (files.size) {
       const plan = []
-      for (const p of files) plan.push({ path: p, bytes: (await body(p)).data.length })
+      for (const p of files) { const { data } = await body(p); plan.push({ path: p, bytes: data.length, ...(/\.(png|webp|jpe?g)$/i.test(p) ? { sha256: createHash('sha256').update(data).digest('hex') } : {}) }) }
       await client.request('POST', `/orgs/${config.org}/runs/${manifest.id}/files`, { files: plan }).catch((e) => { if (!/HTTP (404|405)/.test(e.message)) throw e })
     }
     const queue = [...files]
@@ -1031,6 +1050,9 @@ const commands = {
     meta.shared = { url: fin.url, at: new Date().toISOString(), expires_days: created.expires_days }
     await writeFile(join(run.dir, 'meta.json'), JSON.stringify(meta, null, 2) + '\n')
     say(`Shared ${manifest.id} (${files.size} files, expires in ${created.expires_days} days)\n${fin.url}`)
+    // what waits for a person, with the review-mode link to give them (approvals of unchanged steps carry over)
+    const review = shareReviewLine(fin.review)
+    if (review) say(review)
     const capped = expiryNote(days, created.expires_days)
     if (capped) say(`Note: ${capped}`)
     if (args.pr) {
@@ -1127,12 +1149,38 @@ const commands = {
       for (const x of r.replies || []) say(`      ↳ ${x.email}${x.agent ? ` via ${x.agent}` : ''}: ${x.deleted ? '(deleted)' : x.note}`)
     }
     const flow = data.flow_comments || []
+    // how many steps still wait for a person (review mode); an older service answers 404 and the line is left out
+    const queue = await client.request('GET', `/orgs/${config.org}/review-queue?run=${encodeURIComponent(data.run.id)}`).catch(() => null)
+    if (queue?.counts) say(`  review: ${queue.counts.pending} of ${queue.counts.queue} step(s) wait for a person${queue.counts.carried ? `, ${queue.counts.carried} unchanged kept their approval` : ''} (kaloko review; review mode: ${queue.review_url})`)
     if (!data.items.length && !flow.length) { say('  No open rejections or comments.'); return }
-    for (const r of data.items) thread(r, r.node_id ? `step ${r.node_id}` : 'whole run')
+    // returned steps first: a reviewer said what should change
+    const returned = data.items.filter((r) => r.status === 'rejected')
+    if (returned.length) say(`Returned steps (${returned.length}), fix these first:`)
+    for (const r of returned) thread(r, r.node_id ? `step ${r.node_id}` : 'whole run')
+    if (returned.length && data.items.length > returned.length) say('Comments:')
+    for (const r of data.items.filter((x) => x.status !== 'rejected')) thread(r, r.node_id ? `step ${r.node_id}` : 'whole run')
     for (const r of flow) thread(r, 'whole flow')
     say(`\nAnswer with: kaloko comment --reply <id> --note "…"; close with: kaloko comment --resolve <id> --note "Fixed in <commit>"${flow.length ? ' (add --flow for flow comments)' : ''}`)
   },
 
+  /**
+   * What a person still has to decide on a shared run: the service's review queue (failed, unsure, changed since the
+   * accepted run, returned, commented), the approvals carried over unchanged steps, and the review-mode link. For
+   * agents: report it to the person; never approve on their behalf.
+   */
+  async review (args) {
+    const { config, root } = await context(args)
+    const client = service(config)
+    let runId = typeof args.run === 'string' ? args.run : null
+    let scenarioId = typeof args.scenario === 'string' ? args.scenario : null
+    if (!runId && !scenarioId) {
+      try { const r = await resolveRun({ root, output: config.output }); if (r.meta.shared) runId = r.meta.id; else scenarioId = r.meta.scenario.id } catch {}
+    }
+    const q = new URLSearchParams({ run: runId || 'latest', ...(scenarioId ? { scenario: scenarioId } : {}) })
+    const data = await client.request('GET', `/orgs/${config.org}/review-queue?${q}`)
+    say(args.json ? JSON.stringify(data, null, 2) : formatReviewQueue(data))
+  },
+
   /**
    * Comments from the CLI: on a step (--step), the whole run (default) or the whole flow (--flow); reply, resolve
    * (with a closing note), reopen, edit and delete by id. Targets the shared run (--run, default the current one).
@@ -1218,6 +1266,25 @@ const commands = {
     say(args.undo ? `✓ ${args._[0]} is active again` : `✓ ${args._[0]} archived: hidden from the scenario list, its runs stay reachable (kaloko archive ${args._[0]} --undo)`)
   },
 
+  async login (args) {
+    // a project is optional: it only names the service URL, the organization and the token variable
+    let config = {}
+    const shell = { ...process.env } // before the project and user .env files are read
+    try { ({ config } = await context(args)) } catch (e) { if (!(e instanceof UserError)) throw e }
+    const tokenEnv = config.share?.token_env || 'KALOKO_TOKEN'
+    const inShell = shell[tokenEnv]
+    const base = typeof args.url === 'string' ? args.url : serviceUrl(config)
+    const version = JSON.parse(await readFile(join(packageRoot, 'package.json'), 'utf8')).version
+    const r = await login(base, { org: typeof args.org === 'string' ? args.org : config.org || null, print: !!args.print, open: !args['no-open'], tokenEnv, version, say })
+    if (args.print) return
+    say(`✓ Signed in to ${r.org_name || r.org} as ${r.email} (${r.scope}; expires ${String(r.expires_at || '').slice(0, 10)}). ${tokenEnv} saved to ${r.file}.`)
+    if (config.org && r.org && config.org !== r.org) say(`! ${CONFIG_FILE} names the organization ${config.org}; the token is for ${r.org}.`)
+    for (const line of loginNextSteps({ base, org: r.org })) say(line)
+    let projectEnv = ''
+    try { projectEnv = await readFile(join(process.cwd(), '.env'), 'utf8') } catch {}
+    if (inShell || new RegExp(`^\\s*(export\\s+)?${tokenEnv}\\s*=`, 'm').test(projectEnv)) say(`! ${tokenEnv} is also set ${inShell ? 'in your shell' : 'in this project\'s .env'}, which wins over ~/.config/kaloko/.env. Remove it there to use the new token.`)
+  },
+
   async inbox (args) {
     const { config } = await context(args)
     const client = service(config)

package/src/lib/doctor.mjs

@@ -107,7 +107,7 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
   const tokenEnv = config.share?.token_env || 'KALOKO_TOKEN'
   const token = env[tokenEnv]
   const service = serviceUrl(config, env)
-  if (!token) add('token', false, `${tokenEnv} not set`, `Create a tester token in ${service}/${config.org || '<org>'}/settings and put ${tokenEnv}=… into .env (or ~/.config/kaloko/.env).`)
+  if (!token) add('token', false, `${tokenEnv} not set`, `Run kaloko login, or create a tester token in ${service}/${config.org || '<org>'}/settings and put ${tokenEnv}=… into .env (or ~/.config/kaloko/.env).`)
   else {
     try {
       const res = await fetchImpl(`${service}/api/v1/me`, { headers: { Authorization: `Bearer ${token}` } })
@@ -115,8 +115,10 @@ export async function doctor ({ config, root, file = null, fetchImpl = fetch, la
       else {
         const me = await res.json()
         const sameOrg = !config.org || me.org === config.org
-        add('token', sameOrg, `${me.email} · ${me.role} · org ${me.org}${me.role === 'viewer' ? ' (viewer tokens cannot share runs)' : ''}`, sameOrg ? '' : `The token belongs to organization "${me.org}" but the config says "${config.org}".`)
-        if (me.role === 'viewer') add('token role', false, 'viewer', 'kaloko share needs a tester token.')
+        // sharing runs needs the Developer / Tester role (or admin) and, on tokens with scope sets, the upload scope
+        const canShare = ['tester', 'admin'].includes(me.role) && (!Array.isArray(me.scopes) || me.scopes.includes('upload'))
+        add('token', sameOrg, `${me.email} · ${me.role} · org ${me.org}${canShare ? '' : ' (this token cannot share runs)'}`, sameOrg ? '' : `The token belongs to organization "${me.org}" but the config says "${config.org}".`)
+        if (!canShare) add('token role', false, Array.isArray(me.scopes) ? `${me.role} · ${me.scopes.join(', ')}` : me.role, 'kaloko share needs a Developer / Tester token with the upload scope.')
       }
     } catch (e) { add('token', false, `${service} unreachable: ${e.message}`, 'Check your network; KALOKO_URL overrides the service URL.') }
   }

package/src/lib/login.mjs

@@ -0,0 +1,70 @@
+// kaloko login: signs this machine in through the browser instead of pasting a token. The service hands out a code
+// (POST /cli/device), a signed-in person approves it at /cli/authorize for one organization with the scopes their
+// role allows, and the next poll (POST /cli/token) returns a personal token that expires within 30 days. The token
+// goes to ~/.config/kaloko/.env (or is printed with --print).
+import { readFile, writeFile, mkdir, chmod } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { homedir, hostname } from 'node:os'
+import { spawn } from 'node:child_process'
+import { UserError } from './util.mjs'
+
+export const userEnvFile = (home = homedir()) => join(home, '.config', 'kaloko', '.env')
+
+/** Sets NAME=value in a .env text, replacing an earlier line of the same name; keeps everything else. */
+export function setEnvLine (text, name, value) {
+  const lines = String(text || '').split('\n').filter((l, i, all) => !(i === all.length - 1 && l === ''))
+  const re = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=`)
+  const at = lines.findIndex((l) => re.test(l))
+  if (at >= 0) lines[at] = `${name}=${value}`
+  else lines.push(`${name}=${value}`)
+  return lines.join('\n') + '\n'
+}
+
+function openBrowser (url) {
+  const [cmd, args] = process.platform === 'darwin' ? ['open', [url]] : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]] : ['xdg-open', [url]]
+  try { spawn(cmd, args, { stdio: 'ignore', detached: true }).on('error', () => {}).unref() } catch {}
+}
+
+/**
+ * Runs the device flow against `base` (the service URL). Returns { token, org, email, scope, expires_at, file? }.
+ * Options: org (preselected in the browser), print (do not write the file), open (launch the browser), tokenEnv
+ * (the variable name, share.token_env), home, version, say, fetchImpl, sleep.
+ */
+export async function login (base, { org = null, print = false, open = true, tokenEnv = 'KALOKO_TOKEN', home = homedir(), version = '', say = console.log, fetchImpl = fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  base = base.replace(/\/$/, '')
+  const post = async (path, body) => {
+    let res
+    try { res = await fetchImpl(`${base}${path}`, { method: 'POST', headers: { 'Content-Type': 'application/json', Accept: 'application/json' }, body: JSON.stringify(body) }) } catch (e) { throw new UserError(`Cannot reach ${base}: ${e.message}`) }
+    return { status: res.status, body: await res.json().catch(() => ({})) }
+  }
+  const start = await post('/cli/device', { client: `kaloko${version ? ` ${version}` : ''} on ${hostname()}`.slice(0, 60) })
+  if (start.status !== 200 || !start.body.device_code) throw new UserError(`${base} did not start the sign-in (HTTP ${start.status}${start.body.error ? `: ${start.body.error}` : ''}). Is this a Kaloko service?`)
+  const { device_code: device, user_code: code, verification_uri_complete: complete, expires_in: ttl = 600 } = start.body
+  let interval = Math.max(1, Number(start.body.interval) || 5)
+  const link = org ? `${complete}&org=${encodeURIComponent(org)}` : complete
+  say(`Open this page and approve the sign-in:\n  ${link}\nCheck that it shows the code ${code}.`)
+  if (open) openBrowser(link)
+  const until = Date.now() + ttl * 1000
+  while (Date.now() < until) {
+    await sleep(interval * 1000)
+    const r = await post('/cli/token', { device_code: device })
+    if (r.status === 200 && r.body.access_token) {
+      const out = { token: r.body.access_token, org: r.body.org, org_name: r.body.org_name, email: r.body.email, scope: r.body.scope, expires_at: r.body.expires_at }
+      if (print) { say(`${tokenEnv}=${out.token}`); return out }
+      const file = userEnvFile(home)
+      await mkdir(dirname(file), { recursive: true })
+      let text = ''
+      try { text = await readFile(file, 'utf8') } catch {}
+      await writeFile(file, setEnvLine(text, tokenEnv, out.token), { mode: 0o600 })
+      await chmod(file, 0o600).catch(() => {})
+      return { ...out, file }
+    }
+    const error = r.body.error
+    if (error === 'authorization_pending') continue
+    if (error === 'slow_down') { interval += 5; continue }
+    if (error === 'access_denied') throw new UserError('The sign-in was declined in the browser.')
+    if (error === 'expired_token') throw new UserError('The code expired. Run kaloko login again.')
+    throw new UserError(`Sign-in failed (HTTP ${r.status}${error ? `: ${error}` : ''}).`)
+  }
+  throw new UserError('The code expired before it was approved. Run kaloko login again.')
+}

package/src/lib/onboarding.mjs

@@ -0,0 +1,33 @@
+// What `kaloko init` and `kaloko login` print next: the organization's sample run (every new organization gets one,
+// a reviewed checkout to try the canvas on) and the way to a first real flow. No service call: the sample link is a
+// stable address that opens the organization's sample run, or its home page when there is none.
+
+export const FIRST_FLOW_PROMPT = 'Use the Kaloko skill: draft a scenario for the main flow of this app on the local environment, walk it in every locale on desktop and mobile, share it and send me the canvas link.'
+
+/** The organization slug from a config, unless it is still the template's placeholder. */
+export const realOrg = (org) => (typeof org === 'string' && /^[a-z0-9][a-z0-9-]{1,40}$/.test(org) && org !== 'my-org' ? org : null)
+
+/** Address of the organization's sample run on the service. */
+export const sampleUrl = (base, org) => `${String(base).replace(/\/$/, '')}/${org}/sample`
+
+/** Lines printed at the end of `kaloko init`. */
+export function initNextSteps ({ base, org, loggedIn = false }) {
+  const o = realOrg(org)
+  return [
+    'Next:',
+    loggedIn ? '  1. Signed in already (KALOKO_TOKEN found).' : '  1. npx kaloko login   (approve a token in the browser; or put KALOKO_TOKEN from Settings → API tokens into .env)',
+    o ? `  2. Try a review on the sample run: ${sampleUrl(base, o)}` : '  2. Set org: in kaloko.config.yml, then open <service>/<org>/sample to try a review on the sample run.',
+    '  3. Your first real flow: npx kaloko draft <your app URL>   (public pages), or ask your agent:',
+    `     "${FIRST_FLOW_PROMPT}"`
+  ]
+}
+
+/** Lines printed after a successful `kaloko login`. */
+export function loginNextSteps ({ base, org }) {
+  const o = realOrg(org)
+  if (!o) return []
+  return [
+    `Sample run to try a review on: ${sampleUrl(base, o)}`,
+    'First real flow: npx kaloko draft <your app URL>, or ask your agent to walk the main flow and share it.'
+  ]
+}

package/src/lib/review.mjs

@@ -0,0 +1,69 @@
+// The service's review queue in words for the terminal (`kaloko review`, `kaloko share`, `kaloko feedback`): what a
+// person still has to decide on a shared run, so an agent can tell them what waits and where. Agents never decide
+// for people; they point them to the review mode link.
+
+const REASON = {
+  fail: 'failed',
+  returned: 'returned',
+  needs_review: 'needs a person’s judgement',
+  not_evaluated: 'not evaluated',
+  revoked: 'carried approval revoked',
+  changed: 'changed since the accepted run',
+  new: 'new',
+  comments: 'open comments'
+}
+const plural = (n, one, many) => `${n} ${n === 1 ? one : many}`
+const day = (iso) => (iso ? String(iso).slice(0, 10) : '')
+const cut = (s, n = 140) => { const t = String(s ?? '').replace(/\s+/g, ' ').trim(); return t.length > n ? `${t.slice(0, n - 1)}…` : t }
+
+/** One line after `kaloko share`: "12 steps unchanged, approvals carried over; 5 need review: <link>". */
+export function shareReviewLine (r) {
+  if (!r || r.queue == null) return null
+  const carried = r.carried ? `${plural(r.carried, 'step', 'steps')} unchanged, approvals carried over; ` : ''
+  if (!r.pending) return `${carried}no step waits for a person; the run still needs its verdict: ${r.url}`
+  return `${carried}${r.pending} ${r.pending === 1 ? 'needs' : 'need'} review: ${r.url}`
+}
+
+/** Who decided and how, in a few words. */
+function decisionText (d) {
+  if (!d) return 'waiting for a person'
+  const via = d.via === 'agent' ? ' (agent)' : d.via === 'token' ? ' (token)' : ''
+  if (d.state === 'carried') return `approval carried over: ${d.by}${via} approved it on ${day(d.at)} in run ${d.from_run}`
+  if (d.state === 'approved') return `approved by ${d.by}${via} on ${day(d.at)}`
+  return `returned by ${d.by}${via} on ${day(d.at)}: ${cut(d.note, 200)}`
+}
+
+/** The whole queue for the terminal. */
+export function formatReviewQueue (q) {
+  if (!q?.run) return 'No published run found.'
+  const c = q.counts || {}
+  const out = []
+  out.push(`Review of ${q.run.id} (${q.run.scenario}${q.run.environment ? `, ${q.run.environment}` : ''}): ${c.decided || 0} of ${plural(c.queue || 0, 'step', 'steps')} decided, ${c.pending || 0} waiting for a person${c.carried ? `; ${plural(c.carried, 'unchanged step', 'unchanged steps')} kept ${c.carried === 1 ? 'its' : 'their'} approval` : ''}`)
+  out.push(q.reference
+    ? `Compared with the accepted run ${q.reference.id} (accepted${q.reference.accepted_by ? ` by ${q.reference.accepted_by}` : ''}${q.reference.accepted_at ? ` on ${day(q.reference.accepted_at)}` : ''})`
+    : 'No accepted run of this scenario yet: every step is new to the reviewers.')
+  if (!q.policy?.carry_over) out.push('Approvals do not carry over in this organization (Settings → Approvals).')
+  for (const it of q.items || []) {
+    const mark = !it.decision ? '○' : it.decision.state === 'returned' ? '↩' : '✓'
+    out.push(`  ${mark} ${it.step}${it.title ? `  ${typeof it.title === 'string' ? it.title : Object.values(it.title)[0]}` : ''} — ${it.reasons.map((r) => REASON[r] || r).join(', ')}`)
+    if (it.changed?.captures?.length) out.push(`      changed: ${it.changed.captures.map((x) => `${x.locale}/${x.viewport}${x.why !== 'pixels' ? ` (${x.why})` : ''}`).join(', ')}${it.changed.criteria ? ' · criteria changed' : ''}`)
+    else if (it.changed?.criteria) out.push('      changed: criteria')
+    for (const cr of (it.criteria || []).filter((x) => x.cells?.length).slice(0, 4)) {
+      const cell = cr.cells.find((x) => x.verdict === 'fail') || cr.cells[0]
+      out.push(`      ${cr.id} [${cell.locale}/${cell.viewport}] ${cell.verdict}${cell.evidence ? `: ${cut(cell.evidence)}` : ''}`)
+    }
+    out.push(`      ${decisionText(it.decision)}`)
+    if (it.unconfirmed) out.push(`      not counted: ${decisionText(it.unconfirmed)}`)
+    if (it.open_comments) out.push(`      ${plural(it.open_comments, 'open comment', 'open comments')} (kaloko feedback)`)
+  }
+  if (!(q.items || []).length) out.push('  Nothing waits for a person on the steps.')
+  if (q.carried?.length) {
+    out.push(`Approvals carried over (${q.carried.length}):`)
+    for (const x of q.carried.slice(0, 12)) out.push(`  ✓ ${x.step} — ${x.approved_by}${x.approved_via && x.approved_via !== 'session' ? ` (${x.approved_via})` : ''}, ${day(x.approved_at)}, ${x.kind === 'run' ? 'accepted run' : 'step approved in'} ${x.from_run}`)
+    if (q.carried.length > 12) out.push(`  … and ${q.carried.length - 12} more`)
+  }
+  const v = q.verdict || {}
+  out.push(`Run verdict: ${v.verdict || 'pending'}${v.by ? ` by ${v.by}${v.via && v.via !== 'session' ? ` (${v.via})` : ''}` : ''}${v.awaiting?.length ? ` · awaiting approval from ${v.awaiting.join(', ')}` : ''}`)
+  out.push(`Review mode for a person: ${q.review_url}`)
+  return out.join('\n')
+}