@workser/cli 0.3.1 → 0.6.0

package/dist/index.js

@@ -3655,6 +3655,141 @@ var import_picocolors2 = __toESM(require_picocolors(), 1);
 
 // src/help-content.ts
 var HELP_TOPICS = [
+  {
+    topic: "analysis",
+    title: "Analysis \u2014 running Python on this project's data",
+    summary: "Run pandas locally under a sandbox and a clock, so the code, the output and the timing land in the task where the owner can see them.",
+    commands: ["analysis"],
+    source: "skills/workser/reference/analysis.md",
+    body: `# Analysis \u2014 running Python on this project's data
+
+\`\`\`
+workser analysis runtime [--app <webAppId>]
+workser analysis run --app <webAppId> --file report.py [--timeout <ms>]
+workser analysis run --app <webAppId> --code 'print(1)'
+\`\`\`
+
+## Why not just run \`python\` yourself
+
+Two reasons, and the second matters more.
+
+It runs inside the same OS sandbox a structured agent run gets, scoped to the
+app's own folder \u2014 so a script that goes wrong goes wrong in one directory.
+
+And it is **recorded**. The code, the output and how long it took land in the
+task, where the owner can see them. An analysis nobody can see is an assertion,
+which is the same problem \`workser api call\` solves for a service with no
+screen. If a number is going to end up in front of the customer, run it here.
+
+## Check the runtime before you write the script
+
+\`\`\`
+workser analysis runtime --app <id> --json
+\`\`\`
+
+It reports the interpreter that would be used \u2014 the app's own \`.venv\` first, if
+it has one \u2014 and whether \`pandas\` and \`matplotlib\` are importable. Exit code is
+non-zero when Python is missing, so you find out in a second rather than after
+writing a hundred lines.
+
+## Limits, said plainly
+
+Five minutes by default, fifteen at most. Output is capped per stream and
+truncation is reported. Nothing is silently dropped.
+
+These are local limits and they are the right ones: this work does **not** go in
+a deployed function. \`maxDuration\` is for a slow request; an analysis reads a lot
+of rows and takes as long as it takes, so putting it behind a serverless timeout
+means the useful analyses are exactly the ones that fail.
+
+## What counts as evidence
+
+A number on its own is not a finding. When you report a result, say what the
+query was, how many rows it covered, and what window of time \u2014 a figure with no
+denominator is the easiest thing in this product to get wrong and the hardest
+for the owner to check.
+`
+  },
+  {
+    topic: "api",
+    title: "Services \u2014 calling one, and describing it",
+    summary: "Call this project's API through the same console the owner sees, and make sure every route it serves is written down before you call the task done.",
+    commands: ["api"],
+    source: "skills/workser/reference/api.md",
+    body: `# Services \u2014 calling one, and describing it
+
+A service has no screen. Everything else you build can be looked at; an API can
+only be *called* \u2014 so unless the calls go somewhere the owner can see, "the API
+works" is an assertion with nothing behind it.
+
+\`\`\`
+workser api list  [--app <webAppId>]
+workser api call <path> [--app <id>] [--method <verb>] [--body <text>]
+                        [--header 'Name: value'] [--env local|preview|production]
+workser api spec  [--check]
+\`\`\`
+
+## Call it through the console, not through curl
+
+\`workser api call\` goes through the same request console the owner has open. The
+status, the timing and the body you see are the ones they see, and the
+credentials come from the app's own environment rather than from your command
+line \u2014 so a token never lands in a transcript.
+
+\`\`\`
+workser api call /orders --app <id> --json
+workser api call /orders --app <id> --method POST --body '{"item":"latte"}' --json
+\`\`\`
+
+\`--env\` picks which copy to call. \`local\` is the dev server on this machine and
+is the default; \`preview\` and \`production\` are the deployments. The host always
+comes from that choice \u2014 a path is a path, never a URL, and passing one is
+refused.
+
+Exit code: non-zero only when nothing answered. A 404 or a 422 is a *successful*
+call with an informative answer, so checking that a route correctly rejects bad
+input works exactly as you would expect.
+
+## Save the calls that matter
+
+Requests saved at \`api/requests.json\` in the service's repo show up in the
+owner's console. Write the handful that describe what the service does \u2014 not a
+test suite:
+
+\`\`\`json
+[
+  { "id": "list-orders", "name": "List today's orders", "method": "GET",
+    "path": "/api/orders", "note": "What the shop screen loads." },
+  { "id": "place-order", "name": "Place an order", "method": "POST",
+    "path": "/api/orders", "body": "{\\"item\\":\\"latte\\"}" }
+]
+\`\`\`
+
+They are in the repo on purpose: a call worth saving outlives the session that
+saved it, and it shows up in the diff.
+
+## Describe every route before you call it done
+
+\`\`\`
+workser api spec --check
+\`\`\`
+
+It compares the routes the repo actually serves \u2014 read from the file layout, so
+it cannot be fooled by a comment \u2014 with the paths your OpenAPI document
+declares, and fails when one is missing. Write the document at
+\`api/openapi.json\` (YAML also works).
+
+It is not an OpenAPI validator and does not check schemas or responses. It asks
+one question, so that it is cheap enough to run every time: is every route
+written down. A health probe is exempt. A path in the spec that the repo does
+not serve is reported but does not fail \u2014 you may be documenting something
+built next.
+
+Run it alongside \`workser verify\` before declaring an API task finished. An API
+somebody can call and an API somebody can integrate with are different products,
+and the spec is the difference.
+`
+  },
   {
     topic: "automation",
     title: "Workflows & connected apps",
@@ -3770,6 +3905,39 @@ other surface the brand feeds.
 
 For generating artwork *in* the brand's palette, see \`workser help images\` \u2014
 put the colours from \`design show\` into the prompt.
+
+## The three places design lives \u2014 and which one you are in
+
+They are separate on purpose, and confusing them is the commonest mistake here.
+
+| What | Scope | Where |
+| --- | --- | --- |
+| **Brand** \u2014 colours, fonts, logo | The **project** | \`business_settings\`, read with \`design show\` |
+| **Design files** \u2014 the \`.fig\` work | The **project**, many files | the project's design workspace folder |
+| **Layout options** \u2014 choices to show the owner | **One app** | \`design/options.json\` in that app's folder |
+
+**Design is not an app.** It has no port, no URL, nothing to deploy. Never create
+an app for it.
+
+When you write \`design/options.json\`, put the design file each option came from
+in a \`source\` field:
+
+\`\`\`json
+{ "options": [
+  { "id": "warm", "name": "Warm and simple", "route": "/",
+    "note": "Bigger type, more space.", "source": "hero-v2.fig" }
+] }
+\`\`\`
+
+\`source\` is a path **inside the project's design workspace** \u2014 relative, no
+\`..\`, no absolute paths, no URLs. Anything else is dropped. Leave it out when the
+option was written straight into code with no design file behind it; that is an
+ordinary case and inventing a source is worse than omitting one.
+
+Why it matters: the owner picks an option in one app and later opens the design
+workspace. Without \`source\`, nothing connects the decision they just made to the
+file it came from, and "why does the site look like this?" has three unrelated
+answers.
 `
   },
   {
@@ -3822,6 +3990,77 @@ copy is the current one.
 \`workser business\` is how **you** inspect and fix data while building. The app reads
 the same records at runtime through \`workser.business\` in \`@workser/app\` \u2014 see the
 \`workser-sdk\` skill. An app shelling out to this CLI per request is wrong.
+`
+  },
+  {
+    topic: "checks",
+    title: "Checks \u2014 is it safe, and is it still up",
+    summary: "Scan the code for leaked secrets, known-bad dependencies and over-broad permissions, and check that what you published is still answering.",
+    commands: ["scan", "health"],
+    source: "skills/workser/reference/checks.md",
+    body: `# Checks \u2014 is it safe, and is it still up
+
+Two questions nothing else in this CLI asks. \`verify\` tells you the code
+compiles. These tell you it is not dangerous, and that it is still working an
+hour after you shipped it.
+
+Run both before you say a task is done.
+
+\`\`\`
+workser scan                      # deps \xB7 secrets \xB7 permissions, over this folder
+workser scan --check              # same, but exits non-zero on anything serious
+workser scan --only secrets       # one check: deps, secrets, permissions
+workser scan --staged             # look at staged changes only
+
+workser health                    # is every published app still answering?
+workser health --app <webAppId>   # just one
+\`\`\`
+
+## scan
+
+Three checks, all local \u2014 no login, no project, no network except for \`deps\`.
+
+**secrets** looks at what your changes ADD (\`git diff HEAD\`), not at the whole
+tree, so it fires on the key you just wrote rather than on every example file
+forever. It knows the shapes that are actually credentials \u2014 AWS, GitHub,
+Stripe, OpenAI, Anthropic, Google, Slack, private keys, database URLs with a
+password in them, and \`API_KEY = "\u2026"\` with something real on the right. It
+ignores placeholders (\`your-api-key\`, \`process.env.X\`, \`<REPLACE_ME>\`) and
+example, fixture and lockfile paths.
+
+**deps** runs \`npm audit\` and reports high and critical only. Moderate and low
+advisories on transitive dev dependencies are real and are not worth a report
+nobody finishes reading.
+
+**permissions** catches three specific mistakes: a \`NEXT_PUBLIC_\u2026SECRET\`
+compiled into the browser bundle, an API that accepts credentialed requests
+from any website, and a real \`.env\` committed to the repository.
+
+**A check that could not run says so.** Offline, \`deps\` reports "not checked"
+with the reason \u2014 never "nothing found". If you are quoting a scan result, quote
+what it checked as well as what it found.
+
+If it finds a secret: move the value to \`workser env set\`, and treat the old one
+as leaked. Rotating it is the owner's decision, not yours \u2014 say so and let them.
+
+## health
+
+Probes the stable preview and production addresses of every app in the project
+and reports up or down, with the round trip. It exits non-zero if anything is
+down, so a step can gate on it.
+
+Two things worth knowing:
+
+* It is the same check the desktop runs on a timer. Both fold into one streak,
+  so a run of yours counts toward the same total.
+* After three failed checks in a row on a **production** address that has
+  worked before, an incident task is opened on the owner's board automatically.
+  A preview address is checked and reported but never escalated \u2014 it is not
+  customer-facing, and waking the owner for it teaches them to ignore the ones
+  that are.
+
+An app that has never been published has no address, so there is nothing to
+check. That is reported as a note, not as a pass.
 `
   },
   {
@@ -3916,6 +4155,7 @@ them.
 \`\`\`
 workser artifact add <path> [--kind <k>] [-d <text>]  # record a finished deliverable
 workser artifact add --url <url> --kind app           # record a deployed app
+workser artifact add <path> --kind <shape> --data <json> [--promote]
 workser artifact run                                  # which task you're attached to
 
 workser ask "<question>" [--type <t>] [--option <o>]  # ask the user, WAIT for the answer
@@ -3942,6 +4182,43 @@ are detected automatically); pass it explicitly for \`app\` / \`url\`.
 To publish an app: \`workser deploy\` (preview) or \`workser deploy --prod\` (live), then
 register the URL it returns as an \`app\` artifact so the user can open it from the task.
 
+## The shapes the task draws as cards
+
+Most kinds say what kind of FILE something is. A few say what the user **asked
+for**, and those get a card of their own on the task:
+
+| \`--kind\` | What the card shows | \`--data\` it reads |
+|---|---|---|
+| \`report\` | the chart behind a number | \u2014 |
+| \`walkthrough\` | the flow, as frames | \`frames\` |
+| \`before_after\` | a wipe between two pictures | \`shots: [{url,label}, \u2026]\` |
+| \`checks\` | what was tested | \`passed\`, \`total\` |
+| \`web_app\` | a published app | \`deployedAt\`, \`pagesChanged\` |
+| \`service\` | a job and what it reaches | \`nextRun\` |
+| \`design\` | a layout | \u2014 |
+
+\`\`\`
+workser artifact add ./checks.json --kind checks --data '{"passed":12,"total":12}'
+workser artifact add --url https://acme.workser.app --kind web_app \\
+  --data '{"deployedAt":"2026-08-20T14:02:00Z","pagesChanged":3}'
+\`\`\`
+
+**Every \`--data\` field is optional, and a missing one is left off the card \u2014 it
+is never drawn as zero.** \`0 pages changed\` is a claim you cannot support and
+reads as "it did nothing"; saying nothing reads as "not measured", which is
+true. Only pass a figure you actually counted.
+
+## Handing something up to the task
+
+\`--promote\` marks an artifact as one of the things the user asked for, so it
+appears on the task itself instead of inside your step.
+
+Use it when you know: the report they wanted, the app you published, the
+document explaining what changed. Do **not** promote working material \u2014
+screenshots you took to check your own work, intermediate exports, a scratch
+file. A task that hands up everything buries the six things they wanted under
+sixty they did not.
+
 ## Ask the user something (and get an answer back)
 
 When you're blocked \u2014 a missing value, an ambiguous requirement, permission for
@@ -3970,42 +4247,62 @@ without you ever seeing it).
   },
   {
     topic: "deploy",
-    title: "Deploy, environment variables & logs",
-    summary: "Ship the app, configure it, and find out why it is down.",
-    commands: ["deploy", "env", "logs", "versions", "domain", "open", "verify"],
+    title: "Deploy, addresses & logs",
+    summary: "Ship the app, find its address, and find out why it is down.",
+    commands: ["deploy", "logs", "versions", "urls", "deployments", "domain", "open", "verify"],
     source: "skills/workser/reference/deploy.md",
     body: `# Deploy, environment variables & logs
 
 Getting the app online and configured, and finding out why it isn't.
 
 \`\`\`
-workser deploy [--prod] [--watch]   # deploy (git \u2192 Vercel); --watch waits for live URL
+workser deploy [--env production] [--watch]   # deploy (git \u2192 Vercel); default is preview
 workser deploy status [id]          # status of a deploy (default: latest)
-workser logs [-n 100] [-f]          # recent logs
-workser versions                    # deploy history
-workser domain list                 # custom domains (read)
+workser urls                        # every app's stable preview + live address
+workser logs [-n 100] [-f] [--env production] [--app <id>]
+workser versions [--env production] # history; the badge says which env is live
+workser deployments list [--env production] [--app <id>]
+workser deployments inspect <id> [--logs]
+workser deployments promote         # ship the latest build (the owner confirms)
+workser deployments rollback <version>  # put an earlier one back (the owner confirms)
+workser domain list                 # custom domains
+workser domain add shop.co.th       # attach one (the owner confirms)
+workser domain add app.shop.co.th --app <webAppId>
+workser domain rm shop.co.th        # detach one (the owner confirms)
 workser open                        # open the live app
 workser verify                      # run typecheck/lint/build
 
-workser env set KEY=VALUE [K2=V2\u2026]  # set env vars
-workser env list                    # list keys (values masked)
-workser env get KEY                 # one value (sensitive)
 \`\`\`
 
+Settings \u2014 \`workser env\` \u2014 are their own topic: \`workser help env\`.
+
 ## Notes that matter
 
 - **\`verify\` gates "done".** Run \`workser verify --json\` before you say a task is
   finished. \`"ok": false\` means fix the listed errors and re-run \u2014 a green build is
   the bar, not your reading of the diff.
-- **\`deploy\` without \`--prod\` is a preview.** Preview first when the change is
-  risky; \`--prod\` puts it in front of real users.
+- **\`deploy\` without \`--env\` is a preview.** Preview first when the change is
+  risky; \`--env production\` (or the older \`--prod\`, which means the same) puts it
+  in front of real users. Passing both, disagreeing, is refused rather than
+  resolved.
+- **\`urls\` is where the address comes from \u2014 not the deploy response.** The host
+  in a deploy response is per-build and the next deploy retires it. \`urls\`
+  returns the stable ones, and says why an app has none rather than printing a
+  blank.
+- **\`promote\` and \`rollback\` are the same upstream call and two commands on
+  purpose.** Promote ships the newest build; rollback puts version N back. Both
+  ask the owner and return exit 7 (\`awaiting_approval\`) until they answer \u2014 and
+  that gate holds even on a "just do it" run.
+- **There is no \`deployments cancel\`.** Nothing upstream can stop a build that is
+  already running. Wait for it and then promote or roll back.
 - **\`--watch\` blocks until there's a live URL.** Without it you get a deploy id and
   have to poll \`deploy status\`.
-- **\`env set\` writes a value you never see.** That's the point \u2014 when the user has
-  a secret, have them run it (or set it in Orbit) rather than pasting it to you.
-- **\`env get\` returns a secret.** Don't echo it into the conversation.
-- **\`env rm\` and \`domain set\` are owner-only** (exit 6). Tell the user to do it in
-  Orbit; don't look for a workaround.
+- **\`domain add\` and \`domain rm\` ask the owner to confirm** and return exit 7
+  (\`awaiting_approval\`) until they do \u2014 tell them to approve, then retry the same
+  command. Domains Workser owns (\`workser.ai\` and its subdomains) and hostnames
+  the hosting provider assigns (\`*.vercel.app\`) are refused outright: those are
+  not attachable, and the app's own preview and live URLs already exist without
+  attaching anything.
 
 ## After a successful deploy
 
@@ -4016,13 +4313,178 @@ workser artifact add --url https://acme.workser.app --kind app -t "Storefront"
 \`\`\`
 
 See \`reference/deliverables.md\`.
+`
+  },
+  {
+    topic: "docs",
+    title: "Project documents",
+    summary: "Write and revise the project's pages, keep the markdown mirror readable, and put the diagram in the document rather than in your reply.",
+    commands: ["doc"],
+    source: "skills/workser/reference/docs.md",
+    body: `# Project documents
+
+A document is a page in the project's Docs panel and a git-tracked markdown
+mirror at \`.workser/docs/<id>.md\`. Both are the same document: the panel renders
+the rich text, the mirror is what you, git and the next agent can read as text.
+
+\`\`\`
+workser doc list [--work-item <id>]
+workser doc show <id> [--markdown]
+workser doc create <title> [--work-item <id>] [--markdown <text>]
+                            [--content-json <json>]
+workser doc update <id> [--title <text>] [--markdown <text>]
+workser doc diagram <id> [--check]
+\`\`\`
+
+## Revise the page that exists
+
+The project outlives your session, and a second copy of a page is worse than no
+page \u2014 nobody can tell which one is current.
+
+\`\`\`
+workser doc list --json                       # is there already a page for this?
+workser doc update <id> --markdown "$(cat updated.md)"
+\`\`\`
+
+\`workser doc show <id> --markdown\` reports the mirror's path so you can open the
+file with your normal tools instead of reconstructing prose from blocks.
+
+\`--work-item <id>\` links a document to a Board card (a card has at most one). A
+linked document renders on its card and is *hidden* from the Docs panel, so a
+plan spanning several phases should stay unlinked \u2014 it belongs to the project,
+not to phase 1.
+
+## Put the diagram in the document
+
+A page explaining how something fits together should contain the picture, not a
+paragraph describing one. Write it as a \`\`\`mermaid fence in the markdown: the
+Docs panel renders it, \`git diff\` shows it as changed lines, and the next agent
+reads it without a screenshot.
+
+\`\`\`
+workser doc diagram <id> --check     # exits non-zero when the page has none
+\`\`\`
+
+Use \`--check\` on any page whose job is to explain a structure \u2014 an architecture
+page, a data model, a flow. It reads the mirror on disk rather than the block
+content, which is deliberate: a diagram that exists in the editor but not in the
+mirror is invisible to git, to you, and to whoever opens the file next.
+`
+  },
+  {
+    topic: "env",
+    title: "Settings \u2014 cloud, per environment, and on this computer",
+    summary: "Set and read an app's settings, hold a different value in production, and pull them onto this computer without clobbering local ones.",
+    commands: ["env"],
+    source: "skills/workser/reference/env.md",
+    body: `# Settings \u2014 cloud, per environment, and on this computer
+
+\`\`\`
+workser env set KEY=VALUE [K2=V2\u2026] [--env production]
+workser env list [--env production]      # keys, masked; marks where they differ
+workser env get KEY [--env production]   # one value (sensitive)
+workser env pull [--env production] [--overwrite]
+\`\`\`
+
+## \`--env\` \u2014 say which environment you mean
+
+\`deploy\`, \`logs\` and \`versions\` take \`--env preview\` or \`--env production\`.
+\`env set\` takes those and \`--env development\` as well.
+
+Without it: \`deploy\` builds a preview, \`logs\` and \`versions\` talk about
+whichever deployment is newest, and \`env set\` writes to all three environments.
+Those are the old defaults and they have not changed.
+
+**There is no development deployment.** Nothing is ever built into it \u2014 it is
+the environment the app uses when it runs on this computer \u2014 so \`deploy --env
+development\` and \`logs --env development\` are refused rather than quietly shown
+preview.
+
+**A key can now hold a different value per environment.** \`env set --env
+production DATABASE_URL=\u2026\` writes an override; every other environment keeps
+the shared value. \`env list --env production\` and \`env get KEY --env production\`
+read it back.
 
-## Local vs cloud environment
+Without \`--env\` you get the **shared** value \u2014 what the key is everywhere unless
+overridden \u2014 and \`env list\` marks which keys differ:
 
-\`env set\` configures the **cloud** environment (production and preview). The \`.env\`
-files in the app folder configure **this computer** \u2014 the user edits those in Orbit
-under Settings \u2192 "On this computer", and saving there restarts the dev server. Don't
-hand-edit \`.env.local\` to change cloud behaviour; they are different environments.
+\`\`\`
+API_KEY = sk-\u2022\u2022\u2022   (different in production)
+\`\`\`
+
+That marker is the one to read before changing anything: editing the shared
+value will not touch production if production has its own.
+
+\`env rm KEY --env production\` removes just that override and the key keeps its
+shared value. \`env rm KEY\` removes the key entirely.
+
+## Local settings are this computer's, and are not overwritten
+
+\`env pull\` writes into the app folder's own env file \u2014 \`.env\` for most runtimes,
+\`.env.local\` for Next.js, because that is the file each one actually reads.
+
+**It fills in what is missing and leaves what is already there alone.** A local
+\`DATABASE_URL\` usually points at the developer's own database on purpose;
+replacing it because somebody asked to pull one missing key destroys work
+Workser cannot give back. Keys it left alone are **named** in the output.
+
+\`\`\`
+workser env pull                    # fill the gaps, touch nothing else
+workser env pull --env production   # fill them from production's values
+workser env pull --overwrite        # replace local values too
+\`\`\`
+
+Starting an app for the first time does the same thing automatically, with the
+same rule.
+
+## A key can hold a different value per environment
+
+\`workser env set --env production DATABASE_URL=\u2026\` writes an override; every
+other environment keeps the shared value.
+
+Without \`--env\` you get the **shared** value \u2014 what the key is everywhere unless
+overridden \u2014 and \`env list\` marks which keys differ:
+
+\`\`\`
+API_KEY = sk-\u2022\u2022\u2022   (different in production)
+\`\`\`
+
+Read that marker before changing anything: editing the shared value will not
+touch production if production has its own.
+
+\`env rm KEY --env production\` removes just that override and the key keeps its
+shared value. \`env rm KEY\` removes the key entirely.
+
+## Local settings are this computer's, and are not overwritten
+
+\`env pull\` writes into the app folder's own env file \u2014 \`.env\` for most runtimes,
+\`.env.local\` for Next.js, because that is the file each one actually reads.
+
+**It fills in what is missing and leaves what is already there alone.** A local
+\`DATABASE_URL\` usually points at the developer's own database on purpose;
+replacing it because somebody asked to pull one missing key destroys work
+Workser cannot give back. Keys it left alone are **named** in the output.
+
+\`\`\`
+workser env pull                    # fill the gaps, touch nothing else
+workser env pull --env production   # fill them from production's values
+workser env pull --overwrite        # replace local values too
+\`\`\`
+
+Starting an app for the first time does the same thing automatically, with the
+same rule.
+
+## Notes that matter
+
+- **\`env set\` writes a value you never see.** That's the point \u2014 when the user
+  has a secret, have them run it (or set it in Orbit) rather than pasting it to
+  you.
+- **\`env get\` returns a secret.** Don't echo it into the conversation.
+- **\`env rm\` is owner-only** (exit 6). Tell the user to do it in Orbit; don't
+  look for a workaround.
+- **Cloud and local are different environments.** \`env set\` configures the
+  cloud; the files in the app folder configure this computer. Don't hand-edit
+  one to change the other.
 `
   },
   {
@@ -4098,18 +4560,31 @@ can \`memory search\` and find it.
   },
   {
     topic: "neon",
-    title: "The project's own Neon backend",
-    summary: "Neon-branch object storage and functions. Dedicated tenancy only.",
+    title: "The project's own database",
+    summary: "Branches, databases, compute, plus Neon-branch object storage and functions. Dedicated tenancy only.",
     commands: ["neon"],
     source: "skills/workser/reference/neon-backend.md",
-    body: `# The project's own Neon backend
+    body: `# The project's own database
 
-S3-compatible object storage and Node.js HTTP functions on the project's own Neon
-branch \u2014 they branch with the database. **Additive** infrastructure, not a
-replacement for \`workser storage\`.
+The project's database, run the way an operator runs one: branches (copies of
+the data), the databases on them, and the compute that serves them. Plus
+S3-compatible object storage and Node.js HTTP functions on the same branch.
 
 \`\`\`
 workser neon status                       # tenancy + toggles + region verdict
+
+workser neon branch list                  # copies of the data; the live one is marked
+workser neon branch create qa-run         # a copy to work on, made in a second
+workser neon branch create qa --from <id> --no-compute
+workser neon branch reset <branchId>      # throw its changes away (asks the owner)
+workser neon branch rm <branchId>         # delete it and its data (asks the owner)
+
+workser neon database list [--branch <id>]
+workser neon database create <name> [--branch <id>] [--owner <role>]
+workser neon database rm <name> [--branch <id>]   # asks the owner
+
+workser neon endpoints                    # what compute is running, and idle
+
 workser neon storage list | create <name> | rm <bucket>
 workser neon storage ls <bucket> [prefix]
 workser neon storage put <bucket> <local> [key]
@@ -4127,6 +4602,24 @@ Region is fixed when the project is created. \`regionSupportsNeonBackend: false\
 **final, not retryable** \u2014 no amount of waiting or retrying changes it. When you see
 it, say so plainly and fall back to \`workser storage\` (the default bucket).
 
+## Branches are the useful one
+
+A branch is a **full copy of the data**, made in about a second, costing almost
+nothing until something writes to it. That is what lets a check run against real
+data without being able to damage it \u2014 give a QA step its own branch instead of
+pointing it at the live database.
+
+Two things cannot happen at all, whatever anyone approves: **the branch the app
+runs on cannot be deleted or reset**, and neither can **the database it connects
+to**. Those refusals come from the server, not from the approval prompt. If you
+meant to reset a copy and got that message, you named the live one.
+
+\`reset\` deletes nothing by name and destroys just as much: it replaces a
+branch's contents with its source's. It asks the owner for exactly that reason.
+
+\`--no-compute\` makes a branch with no compute. It is cheaper and **nothing can
+connect to it** \u2014 useful as a snapshot, useless as somewhere to run tests.
+
 ## Notes that matter
 
 - **\`neon storage rm <bucket>\` deletes the bucket and everything in it.** Not
@@ -4135,8 +4628,11 @@ it, say so plainly and fall back to \`workser storage\` (the default bucket).
   through Workser.
 - **Functions deploy from a zip.** Build the bundle first, then
   \`workser neon functions deploy <slug> <zip>\`.
-- **Most apps don't need this.** If the user just wants to store uploads, the default
-  bucket in \`reference/storage.md\` is the answer.
+- **\`neon endpoints\` is the cost question.** \`active\` means it is billing;
+  \`idle\` means it is not. It is the only place in the product that answers "what
+  is this database costing me while nothing is happening".
+- **Most apps never need the storage or functions half.** If the user just wants
+  to store uploads, the default bucket in \`reference/storage.md\` is the answer.
 `
   },
   {
@@ -4189,16 +4685,16 @@ real scope, not just a repeat of the task.
   },
   {
     topic: "sdlc-entities",
-    title: "Board cards, decisions, requirements, and docs",
+    title: "Board cards, decisions and requirements",
     summary: "Read what this project already tracks and decided, keep the Board honest as you work, and record what a future maintainer will need.",
-    commands: ["board", "decision", "requirement", "doc"],
+    commands: ["board", "decision", "requirement"],
     source: "skills/workser/reference/sdlc-entities.md",
-    body: `# Board cards, decisions, requirements, and docs
+    body: `# Board cards, decisions and requirements
 
 These are the project's memory across sessions. They write to the **same tables**
-the Orbit desktop's Board, Project Memory, and Docs panels use, so anything here
-appears there too \u2014 and (when this CLI runs inside an Orbit-spawned agent run)
-as an inline card in the conversation you're working in.
+the Orbit desktop's Board and Project Memory panels use, so anything here appears
+there too \u2014 and, inside an Orbit-spawned run, as an inline card in the
+conversation. Documents have their own guide: \`workser help docs\`.
 
 \`\`\`
 workser board list [--status <value>] [--label <value>] [--limit <n>]
@@ -4221,11 +4717,6 @@ workser requirement show <id>
 workser requirement create <title> --body <text> [--status <text>]
 workser requirement update <id> [--title <text>] [--body <text>] [--status <text>]
 
-workser doc list [--work-item <id>]
-workser doc show <id> [--markdown]
-workser doc create <title> [--work-item <id>] [--markdown <text>]
-                            [--content-json <json>]
-workser doc update <id> [--title <text>] [--markdown <text>]
 \`\`\`
 
 ## Read first \u2014 this is the part that matters
@@ -4254,7 +4745,6 @@ workser board create "Phase 1 \u2014 schema + migration" \\
   --description "Add orders/line_items tables and the migration." \\
   --status in-progress --json
 workser board create "Phase 2 \u2014 checkout API" --description "\u2026" --json
-workser board create "Phase 3 \u2014 cart UI"      --description "\u2026" --json
 
 # the plan itself, ONE doc, deliberately NOT linked to a card
 workser doc create "Checkout \u2014 implementation plan" --markdown "$(cat plan.md)" --json
@@ -4264,8 +4754,8 @@ workser decision create "Carts live server-side" --context "\u2026" --decision "
 \`\`\`
 
 **Don't pass \`--work-item\` for a multi-phase plan.** A linked document renders on
-its card and is *hidden* from the Docs panel; a plan spanning three phases belongs
-to the project, not to phase 1.
+its card and is *hidden* from the Docs panel; a plan spanning three phases
+belongs to the project, not to phase 1.
 
 The bar: if the user closed this conversation now, the Board should still show
 what's left and the doc should still explain the plan to whoever continues it.
@@ -4291,22 +4781,19 @@ workser board create "Fix the login bug" --status in-progress --priority high \\
 \`\`\`
 
 \`board update\` replaces the labels you pass rather than merging them, and
-touches only the fields you name. There is no \`board delete\` \u2014 \`done\` is the
-terminal state for finished work, and removing a card the user filed is theirs
-to do in Orbit.
+touches only the fields you name. There is no \`board delete\`: \`done\` is the
+terminal state, and removing a card the user filed is theirs to do in Orbit.
 
 ## Decisions are append-only
 
 \`decision create\` is for something with real tradeoffs worth a paper trail:
-\`--context\` is why it came up, \`--decision\` is what was decided,
-\`--consequences\` is the follow-on effects. There is deliberately **no
-\`decision update\`** \u2014 a decision record states what was decided at a point in
-time. When it stops being right, record a new decision that supersedes it and
-say so in its \`--context\`. Editing the history is how a decision log stops
-being worth reading.
+\`--context\` is why it came up, \`--decision\` what was decided, \`--consequences\`
+the follow-on effects. There is deliberately **no \`decision update\`** \u2014 a record
+states what was decided at a point in time. When it stops being right, record a
+new decision that supersedes it and say so in its \`--context\`. Editing the
+history is how a decision log stops being worth reading.
 
-Requirements are different: they legitimately move along, so they do have
-\`update\`.
+Requirements legitimately move along, so they do have \`update\`.
 
 \`\`\`
 workser requirement create "Support SSO" --body "Enterprise customers need SAML." \\
@@ -4317,25 +4804,11 @@ workser requirement update <id> --status done
 ## Docs
 
 \`--markdown\` is the normal way to write one. The body is stored both as the
-rich-text content the Docs panel renders and as a git-tracked markdown mirror
-at \`.workser/docs/<id>.md\` \u2014 \`workser doc show <id> --markdown\` reports that
-path so you can read the file with your normal tools.
-
-Revise the page that exists rather than creating a second copy of it:
-
-\`\`\`
-workser doc list --json                       # is there already a page for this?
-workser doc update <id> --markdown "$(cat updated.md)"
-\`\`\`
-
-\`--work-item <id>\` links a document to a Board card (a card has at most one).
-
-## When to record, and when not to
+rich text the Docs panel renders and as a git-tracked mirror at
+\`.workser/docs/<id>.md\`; \`workser doc show <id> --markdown\` reports that path so
+you can read the file with your normal tools.
 
-Record what a future maintainer would need: follow-up work you found but didn't
-do, a choice between real alternatives, a behaviour worth writing down. Don't
-narrate every small step \u2014 and never treat filing a card as a substitute for the
-work. A card saying "fix the bug" is not fixing the bug.
+Revise trd saying "fix the bug" is not fixing the bug.
 `
   },
   {
@@ -4429,6 +4902,7 @@ workser task subtask add <title> [--role <value>] [--kind <value>]
 workser task subtask list [taskId]
 workser task subtask update <id> [--title|--note|--role|--kind|--scope]
 workser task subtask remove <id>
+workser task subtask send-back <id> --note <text>   # redo it, and say why
 
 workser task can-start [id]             # may work begin? refuses until approved
 workser task approval request           # tell the owner the plan is ready
@@ -4487,6 +4961,75 @@ workser task done --summary "The report now shows cost per KOL, with six months
 \`\`\`
 
 Write the summary for someone who runs a business and does not read code.
+
+## Sending a step back
+
+A step that finished but is not good enough is **sent back**, not replaced:
+
+\`\`\`
+workser task subtask send-back 3f2a\u2026 --note "The totals ignore refunds."
+\`\`\`
+
+That puts it in the queue again as a **second attempt** on the same step. Two
+reasons it matters that this is not a new step:
+
+- The owner's screen can then say *"1 send-back, fixed \u2014 2nd run passed"*. A
+  replacement step says only that two steps exist, which tells them nothing
+  about whether their team caught its own mistake.
+- \`--note\` is the reason, and it is recorded against the attempt being
+  rejected. Without it the history can say a step ran twice but not why.
+
+It refuses a step that is still working. Let it finish first \u2014 the run is
+still writing to it.
+`
+  },
+  {
+    topic: "usage",
+    title: "Usage \u2014 what is being used, against the plan",
+    summary: "How much database, file storage, projects and apps are in use, and how close that is to what the plan allows.",
+    commands: ["usage"],
+    source: "skills/workser/reference/usage.md",
+    body: `# Usage \u2014 what is being used, against the plan
+
+\`\`\`
+workser usage        # storage, projects, apps \u2014 and how close each is to the limit
+\`\`\`
+
+Run it before you propose anything that adds to a count. "Create another
+project" is a plan you can only sensibly make if you know the plan allows two
+and two already exist.
+
+## Two scopes in one answer, on purpose
+
+* **Database and files are ORGANISATION-wide.** One pool across every project.
+  There is no per-project storage limit, and reporting one would invent it.
+* **Projects, and apps in this project, are counted where they apply.** These
+  are the limits people actually hit.
+
+## Two kinds of limit, which do not mean the same thing
+
+* **Hard cap** \u2014 projects, apps. Going over is **refused**. \`workser usage\`
+  exits non-zero when one is reached, so a step can gate on it.
+* **Soft allowance** \u2014 database, files. Going over is **billed as extra**,
+  never blocked. It does not fail the command, because a customer growing past
+  their allowance should not have their automation start breaking that day.
+
+## "not measured" is not zero
+
+A figure that could not be read prints as \`not measured\`, with the reason, and
+draws no bar. Do not report it as \`0\`, and do not tell the user they have room
+based on it \u2014 nobody looked.
+
+If a scan comes back with a figure missing, say which one and why. "Your
+database is using 2.5 GB of 10; the file total could not be read" is a useful
+sentence. "You are using 2.5 GB of 20" is not, and it is wrong.
+
+## What to do with it
+
+- Near a **soft** limit: tell the owner what the extra will cost them, and what
+  is taking the space. Do not delete anything to make a number look better.
+- At a **hard** cap: say which plan raises it. Do not attempt the create \u2014 it
+  will be refused, and a failed attempt reads to the owner as a broken product.
 `
   },
   {
@@ -4746,6 +5289,18 @@ Commands that only read your account (projects, env, db, logs, status) work as n
     { code: "needs_local_app" }
   );
 }
+function requireDaemon(ctx, what, why) {
+  if (ctx.mode === "daemon") return;
+  throw new WorkserError(
+    `\`workser ${what}\` ${why}, so it needs the Workser app running on this computer.
+
+This shell is talking to ${ctx.endpoint} instead of a local app.
+
+  \u2022 On your own computer: open Workser and try again.
+  \u2022 On a computer without Workser: install it from https://workser.ai/download and sign in.`,
+    { code: "needs_local_app" }
+  );
+}
 function requireProject(ctx) {
   if (!ctx.projectId) {
     throw new WorkserError(
@@ -5335,7 +5890,7 @@ import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
 import { basename as basename2 } from "path";
 function registerNeon(program3) {
   const neon = program3.command("neon").description(
-    "The project's own Neon backend: object storage buckets and functions"
+    "The project's own database: branches, databases, compute, storage and functions"
   );
   neon.command("status").description(
     "Whether this project can use Neon storage/functions (tenancy, toggles, region)"
@@ -5557,70 +6112,321 @@ function registerNeon(program3) {
       ok(res, () => success(`Deleted function ${args[0]}.`));
     })
   );
-}
-async function presign(ctx, projectId, bucket, key, operation, expiresInSeconds) {
-  const res = await api(
-    ctx,
-    `/v1/projects/${projectId}/neon-storage/buckets/${encodeURIComponent(bucket)}/presign`,
-    { body: { key, operation, expiresInSeconds } }
-  );
-  const url = res?.url ?? res?.signedUrl ?? res?.presignedUrl;
-  if (!url) {
-    throw new WorkserError(
-      `The daemon did not return a presigned URL for ${key}.`,
-      { code: "unexpected_response", details: res }
-    );
-  }
-  return { url, headers: res?.headers };
-}
-
-// src/commands/env.ts
-var import_picocolors9 = __toESM(require_picocolors(), 1);
-import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
-function appQuery(opts) {
-  const app = typeof opts?.app === "string" ? opts.app : "";
-  return app ? `?webAppId=${encodeURIComponent(app)}` : "";
-}
-var APP_FLAG_HELP = "Which web app to target (defaults to the project's primary app)";
-function registerEnv(program3) {
-  const env = program3.command("env").description("Manage web app environment variables");
-  env.command("set <pairs...>").description("Set one or more KEY=VALUE variables").option("--app <webAppId>", APP_FLAG_HELP).action(
-    action(async ({ ctx, args, opts }) => {
+  const branch = neon.command("branch").description("Copies of the project's data, to work on without touching it");
+  branch.command("list").description("Every branch, with the one the app runs on marked").action(
+    action(async ({ ctx }) => {
       const projectId = requireProject(ctx);
-      const pairs = args[0].map((p) => {
-        const i = p.indexOf("=");
-        if (i < 0) throw new WorkserError(`Invalid pair "${p}". Use KEY=VALUE.`, { code: "bad_input" });
-        return { key: p.slice(0, i), value: p.slice(i + 1) };
-      });
-      const res = await api(ctx, `/v1/projects/${projectId}/env${appQuery(opts)}`, {
-        body: { vars: pairs }
-      });
-      const count = typeof res?.count === "number" ? res.count : pairs.length;
-      ok(res, () => {
-        success(`Set ${count} variable(s): ${pairs.map((p) => p.key).join(", ")}`);
-        if (res?.usedDefault && res?.webAppName) {
-          line(import_picocolors9.default.dim(`on ${res.webAppName} (primary app) \u2014 use --app to target another`));
+      const items = await api(ctx, `/v1/projects/${projectId}/neon-branches`);
+      ok(items, () => {
+        if (!items?.length) return line(import_picocolors8.default.dim("No branches."));
+        for (const b of items) {
+          const mark = b.isProjectBranch ? import_picocolors8.default.green("  \u2190 the app runs on this") : "";
+          line(
+            `${import_picocolors8.default.bold(b.name ?? "?")}  ${import_picocolors8.default.dim(b.id ?? "")}${b.parent_id ? import_picocolors8.default.dim("  from " + b.parent_id) : ""}${mark}`
+          );
         }
       });
     })
   );
-  env.command("get <key>").description("Print one variable's value (sensitive)").option("--app <webAppId>", APP_FLAG_HELP).action(
+  branch.command("create <name>").description("Make a copy of the data to work on").option("--from <branchId>", "copy this branch instead of the one in use").option(
+    "--no-compute",
+    "create it without compute \u2014 cheaper, and nothing can connect to it"
+  ).action(
     action(async ({ ctx, args, opts }) => {
       const projectId = requireProject(ctx);
-      const res = await api(
-        ctx,
-        `/v1/projects/${projectId}/env/${encodeURIComponent(args[0])}${appQuery(opts)}`
+      const noCompute = opts.compute === false;
+      const res = await api(ctx, `/v1/projects/${projectId}/neon-branches`, {
+        body: {
+          name: args[0],
+          ...opts.from ? { fromBranchId: String(opts.from) } : {},
+          // Commander turns `--no-compute` into `compute: false`. The typed
+          // opts bag is loose here, so the comparison is written against the
+          // value rather than the declared type.
+          ...noCompute ? { withEndpoint: false } : {}
+        }
+      });
+      ok(res, () => {
+        success(`Created branch ${args[0]}.`);
+        const id = res?.branch?.id ?? res?.id;
+        if (id) line(import_picocolors8.default.dim(id));
+        if (noCompute) {
+          line(
+            import_picocolors8.default.dim(
+              "It has no compute, so nothing can connect to it until one is added."
+            )
+          );
+        }
+      });
+    })
+  );
+  branch.command("reset <branchId>").description("Throw away a branch's changes and take its source data again (asks for approval)").action(
+    action(async ({ ctx, args }) => {
+      const projectId = requireProject(ctx);
+      const res = await api(
+        ctx,
+        `/v1/projects/${projectId}/neon-branches/${encodeURIComponent(args[0])}/reset`,
+        { body: {} }
+      );
+      ok(res, () => success(`Reset ${args[0]} to its source.`));
+    })
+  );
+  branch.command("rm <branchId>").description("Delete a branch and its data (asks for approval)").action(
+    action(async ({ ctx, args }) => {
+      const projectId = requireProject(ctx);
+      const res = await api(
+        ctx,
+        `/v1/projects/${projectId}/neon-branches/${encodeURIComponent(args[0])}`,
+        { method: "DELETE" }
+      );
+      ok(res, () => success(`Deleted branch ${args[0]}.`));
+    })
+  );
+  const database = neon.command("database").description("Databases on a branch");
+  database.command("list").description("Databases on a branch (default: the one the app uses)").option("--branch <branchId>", "look at another branch").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      const items = await api(ctx, `/v1/projects/${projectId}/neon-databases`, {
+        query: opts.branch ? { branchId: String(opts.branch) } : void 0
+      });
+      ok(items, () => {
+        if (!items?.length) return line(import_picocolors8.default.dim("No databases."));
+        for (const d of items) {
+          const mark = d.isProjectDatabase ? import_picocolors8.default.green("  \u2190 the app connects to this") : "";
+          line(`${import_picocolors8.default.bold(d.name ?? "?")}${import_picocolors8.default.dim("  owner " + (d.owner_name ?? "?"))}${mark}`);
+        }
+      });
+    })
+  );
+  database.command("create <name>").description("Create a database on a branch").option("--branch <branchId>", "which branch (default: the one the app uses)").option("--owner <role>", "which role owns it (default: the branch's own owner)").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const res = await api(ctx, `/v1/projects/${projectId}/neon-databases`, {
+        body: {
+          name: args[0],
+          ...opts.branch ? { branchId: String(opts.branch) } : {},
+          ...opts.owner ? { ownerName: String(opts.owner) } : {}
+        }
+      });
+      ok(res, () => success(`Created database ${args[0]}.`));
+    })
+  );
+  database.command("rm <name>").description("Delete a database and every table in it (asks for approval)").option("--branch <branchId>", "which branch (default: the one the app uses)").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const res = await api(
+        ctx,
+        `/v1/projects/${projectId}/neon-databases/${encodeURIComponent(args[0])}`,
+        {
+          method: "DELETE",
+          query: opts.branch ? { branchId: String(opts.branch) } : void 0
+        }
+      );
+      ok(res, () => success(`Deleted database ${args[0]}.`));
+    })
+  );
+  neon.command("endpoints").description("The compute that runs the database \u2014 what is on, and what it costs idle").action(
+    action(async ({ ctx }) => {
+      const projectId = requireProject(ctx);
+      const items = await api(ctx, `/v1/projects/${projectId}/neon-endpoints`);
+      ok(items, () => {
+        if (!items?.length) {
+          return line(
+            import_picocolors8.default.dim("No compute endpoints \u2014 nothing can connect to this database.")
+          );
+        }
+        for (const e of items) {
+          const state = e.current_state === "active" ? import_picocolors8.default.green("active") : import_picocolors8.default.dim(e.current_state ?? "?");
+          line(
+            `${import_picocolors8.default.bold(e.type ?? "endpoint")}  ${state}  ${import_picocolors8.default.dim(e.branch_id ?? "")}` + (e.host ? "  " + import_picocolors8.default.cyan(e.host) : "")
+          );
+        }
+      });
+    })
+  );
+}
+async function presign(ctx, projectId, bucket, key, operation, expiresInSeconds) {
+  const res = await api(
+    ctx,
+    `/v1/projects/${projectId}/neon-storage/buckets/${encodeURIComponent(bucket)}/presign`,
+    { body: { key, operation, expiresInSeconds } }
+  );
+  const url = res?.url ?? res?.signedUrl ?? res?.presignedUrl;
+  if (!url) {
+    throw new WorkserError(
+      `The daemon did not return a presigned URL for ${key}.`,
+      { code: "unexpected_response", details: res }
+    );
+  }
+  return { url, headers: res?.headers };
+}
+
+// src/commands/env.ts
+var import_picocolors9 = __toESM(require_picocolors(), 1);
+import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+
+// src/environments.ts
+var ENVIRONMENTS = ["development", "preview", "production"];
+var DEPLOY_ENVIRONMENTS = ["preview", "production"];
+var ALIASES2 = {
+  dev: "development",
+  development: "development",
+  local: "development",
+  preview: "preview",
+  staging: "preview",
+  stage: "preview",
+  test: "preview",
+  prod: "production",
+  production: "production",
+  live: "production",
+  main: "production"
+};
+function parseEnvironment(raw) {
+  if (raw === void 0 || raw === null || raw === "") return { ok: true };
+  const text = String(raw).trim().toLowerCase();
+  const value = ALIASES2[text];
+  if (!value) {
+    return {
+      ok: false,
+      error: `--env takes ${ENVIRONMENTS.join(", ")} (or dev/prod). "${raw}" is not one of them.`
+    };
+  }
+  return { ok: true, value };
+}
+function parseDeployEnvironment(raw, verb) {
+  const parsed = parseEnvironment(raw);
+  if (!parsed.ok || !parsed.value) return parsed;
+  if (parsed.value === "development") {
+    return {
+      ok: false,
+      error: `Nothing is ever deployed to development \u2014 it is the environment your app uses when it runs on this computer. \`${verb}\` can address preview or production.`
+    };
+  }
+  return parsed;
+}
+function envTargets(environment) {
+  if (!environment) return [...ENVIRONMENTS];
+  if (environment === "preview") return ["preview", "development"];
+  return [environment];
+}
+function targetSummary(environment) {
+  if (!environment) return "in every environment";
+  if (environment === "preview") return "in preview and development";
+  return `in ${environment}`;
+}
+function urlRows(apps) {
+  const rows = [];
+  for (const app of apps) {
+    const appId = typeof app?.id === "string" ? app.id : "";
+    if (!appId) continue;
+    const appName = (app.name ?? "").trim() || "Untitled app";
+    for (const environment of DEPLOY_ENVIRONMENTS) {
+      const url = environment === "production" ? app.productionUrl : app.previewUrl;
+      rows.push({
+        appId,
+        appName,
+        environment,
+        url: url && url.trim() ? url.trim() : null,
+        note: url && url.trim() ? null : noteFor(environment)
+      });
+    }
+  }
+  return rows;
+}
+function noteFor(environment) {
+  return environment === "production" ? "not live yet \u2014 `workser deploy --env production` publishes it" : "no preview yet \u2014 `workser deploy` builds one";
+}
+function urlsSummary(rows) {
+  if (!rows.length) return "This project has no apps yet.";
+  const live = rows.filter((r) => r.environment === "production" && r.url).length;
+  const apps = new Set(rows.map((r) => r.appId)).size;
+  if (!live) {
+    return `${apps} ${apps === 1 ? "app" : "apps"}, none live yet.`;
+  }
+  return `${apps} ${apps === 1 ? "app" : "apps"} \u2014 ${live} live.`;
+}
+
+// src/commands/env.ts
+function appQuery(opts, environment) {
+  const params = new URLSearchParams();
+  if (typeof opts?.app === "string" && opts.app) params.set("webAppId", opts.app);
+  if (environment) params.set("environment", environment);
+  const query = params.toString();
+  return query ? `?${query}` : "";
+}
+var APP_FLAG_HELP = "Which web app to target (defaults to the project's primary app)";
+var ENV_FLAG_HELP = "Which environment: production, preview or development (default: all three)";
+function readEnv(opts) {
+  const parsed = parseEnvironment(opts?.env);
+  if (!parsed.ok) throw new WorkserError(parsed.error, { code: "bad_input" });
+  return parsed.value;
+}
+function registerEnv(program3) {
+  const env = program3.command("env").description("Manage web app environment variables");
+  env.command("set <pairs...>").description("Set one or more KEY=VALUE variables").option("--app <webAppId>", APP_FLAG_HELP).option("--env <environment>", ENV_FLAG_HELP).action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const environment = readEnv(opts);
+      const pairs = args[0].map((p) => {
+        const i = p.indexOf("=");
+        if (i < 0) throw new WorkserError(`Invalid pair "${p}". Use KEY=VALUE.`, { code: "bad_input" });
+        return {
+          key: p.slice(0, i),
+          value: p.slice(i + 1),
+          // Sent only when asked for. Omitted means all three, which is what
+          // this command has always done — and quietly narrowing that default
+          // would have un-set production for every script the day it shipped.
+          ...environment ? { target: envTargets(environment) } : {}
+        };
+      });
+      const res = await api(ctx, `/v1/projects/${projectId}/env${appQuery(opts)}`, {
+        body: { vars: pairs }
+      });
+      const count = typeof res?.count === "number" ? res.count : pairs.length;
+      ok(res, () => {
+        success(
+          `Set ${count} variable(s) ${targetSummary(environment)}: ` + pairs.map((p) => p.key).join(", ")
+        );
+        if (res?.usedDefault && res?.webAppName) {
+          line(import_picocolors9.default.dim(`on ${res.webAppName} (primary app) \u2014 use --app to target another`));
+        }
+      });
+    })
+  );
+  env.command("get <key>").description("Print one variable's value (sensitive)").option("--app <webAppId>", APP_FLAG_HELP).option("--env <environment>", ENV_FLAG_HELP).action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const environment = readEnv(opts);
+      const res = await api(
+        ctx,
+        `/v1/projects/${projectId}/env/${encodeURIComponent(args[0])}${appQuery(opts, environment)}`
       );
       ok(res, () => line(res.value ?? ""));
     })
   );
-  env.command("list").description("List variable keys (values masked)").option("--app <webAppId>", APP_FLAG_HELP).action(
+  env.command("list").description("List variable keys (values masked)").option("--app <webAppId>", APP_FLAG_HELP).option("--env <environment>", ENV_FLAG_HELP).action(
     action(async ({ ctx, opts }) => {
       const projectId = requireProject(ctx);
-      const items = await api(ctx, `/v1/projects/${projectId}/env${appQuery(opts)}`);
+      const environment = readEnv(opts);
+      const items = await api(
+        ctx,
+        `/v1/projects/${projectId}/env${appQuery(opts, environment)}`
+      );
       ok(items, () => {
-        if (!items?.length) return line(import_picocolors9.default.dim("No variables set."));
-        for (const v of items) line(`${v.key}${import_picocolors9.default.dim(" = " + (v.masked ?? "\u2022\u2022\u2022\u2022"))}`);
+        if (!items?.length) {
+          return line(
+            import_picocolors9.default.dim(
+              environment ? `No variables apply in ${environment}.` : "No variables set."
+            )
+          );
+        }
+        for (const v of items) {
+          const differs = !environment && v.overriddenIn?.length ? import_picocolors9.default.yellow(`  (different in ${v.overriddenIn.join(", ")})`) : "";
+          line(`${v.key}${import_picocolors9.default.dim(" = " + (v.masked ?? "\u2022\u2022\u2022\u2022"))}${differs}`);
+        }
+        if (environment) {
+          line(import_picocolors9.default.dim(`
+Showing the values that apply in ${environment}.`));
+        }
       });
     })
   );
@@ -5633,12 +6439,17 @@ function registerEnv(program3) {
       })
     )
   );
-  env.command("pull").description("Write this app's cloud env vars into a local file (default .env.local)").option("--app <webAppId>", APP_FLAG_HELP).option("--out <file>", "Local file to write", ".env.local").action(
+  env.command("pull").description("Write this app's cloud env vars into a local file (default .env.local)").option("--app <webAppId>", APP_FLAG_HELP).option("--env <environment>", ENV_FLAG_HELP).option("--out <file>", "Local file to write", ".env.local").option(
+    "--overwrite",
+    "replace values this computer already has (default: fill in only what is missing)",
+    false
+  ).action(
     action(async ({ ctx, opts }) => {
       const projectId = requireProject(ctx);
+      const environment = readEnv(opts);
       const items = await api(
         ctx,
-        `/v1/projects/${projectId}/env${appQuery(opts)}`
+        `/v1/projects/${projectId}/env${appQuery(opts, environment)}`
       );
       const outPath = typeof opts?.out === "string" ? opts.out : ".env.local";
       if (!items?.length) {
@@ -5651,38 +6462,66 @@ function registerEnv(program3) {
       for (const item of items) {
         const res = await api(
           ctx,
-          `/v1/projects/${projectId}/env/${encodeURIComponent(item.key)}${appQuery(opts)}`
+          `/v1/projects/${projectId}/env/${encodeURIComponent(item.key)}${appQuery(opts, environment)}`
         );
         pulled.push({ key: item.key, value: res?.value ?? "" });
       }
-      await mergeEnvFile(outPath, pulled);
+      const result = await mergeEnvFile(outPath, pulled, {
+        overwrite: !!opts.overwrite
+      });
       ok(
-        { file: outPath, pulled: pulled.map((p) => p.key) },
-        () => success(
-          `Pulled ${pulled.length} variable(s) into ${import_picocolors9.default.bold(outPath)}.`
-        )
+        {
+          file: outPath,
+          pulled: result.written,
+          skipped: result.skipped,
+          overwrite: !!opts.overwrite
+        },
+        () => {
+          success(
+            `Pulled ${result.written.length} variable(s) into ${import_picocolors9.default.bold(outPath)}.`
+          );
+          if (result.skipped.length) {
+            line(
+              import_picocolors9.default.dim(
+                `Left alone (this computer already has ${result.skipped.length === 1 ? "it" : "them"}): ${result.skipped.join(", ")}`
+              )
+            );
+            line(import_picocolors9.default.dim("Use --overwrite to replace them."));
+          }
+        }
       );
     })
   );
 }
 var ENV_KEY_LINE = /^([A-Za-z_][A-Za-z0-9_]*)=/;
-async function mergeEnvFile(path, vars) {
+async function mergeEnvFile(path, vars, opts = {}) {
   const existing = await readFile3(path, "utf8").catch(() => "");
   const lines = existing.length ? existing.split(/\r?\n/) : [];
   const remaining = new Map(vars.map((v) => [v.key, v.value]));
+  const skipped = [];
+  const replaced = [];
   const merged = lines.map((rawLine) => {
     const match = ENV_KEY_LINE.exec(rawLine);
     if (!match || !remaining.has(match[1])) return rawLine;
     const key = match[1];
+    if (!opts.overwrite) {
+      remaining.delete(key);
+      skipped.push(key);
+      return rawLine;
+    }
     const value = remaining.get(key);
     remaining.delete(key);
+    replaced.push(key);
     return `${key}=${formatEnvValue(value)}`;
   });
   while (merged.length && merged[merged.length - 1] === "") merged.pop();
+  const written = [...replaced];
   for (const [key, value] of remaining) {
     merged.push(`${key}=${formatEnvValue(value)}`);
+    written.push(key);
   }
   await writeFile3(path, merged.join("\n") + "\n", "utf8");
+  return { written, skipped };
 }
 function formatEnvValue(value) {
   return /[\s"'#]/.test(value) ? JSON.stringify(value) : value;
@@ -5692,16 +6531,30 @@ function formatEnvValue(value) {
 var import_picocolors10 = __toESM(require_picocolors(), 1);
 var TERMINAL = /* @__PURE__ */ new Set(["ready", "live", "success", "error", "failed", "canceled"]);
 function registerDeploy(program3) {
-  const deploy = program3.command("deploy").description("Deploy the current project to Workser (git \u2192 Vercel) and return a live URL").option("--prod", "deploy to production", false).option("--watch", "wait for the deploy to finish, streaming status", false).option(
+  const deploy = program3.command("deploy").description("Deploy the current project to Workser (git \u2192 Vercel) and return a live URL").option("--prod", "deploy to production (same as --env production)", false).option(
+    "--env <environment>",
+    "which environment to deploy: preview (default) or production"
+  ).option("--watch", "wait for the deploy to finish, streaming status", false).option(
     "--app <webAppId>",
     "which app to publish (default: the app this folder is linked to)"
   ).action(
     action(async ({ ctx, opts }) => {
       requireLocalApp(ctx, "deploy");
       const projectId = requireProject(ctx);
+      const parsedEnv = parseDeployEnvironment(opts.env, "deploy");
+      if (!parsedEnv.ok) {
+        throw new WorkserError(parsedEnv.error, { code: "bad_input" });
+      }
+      if (opts.prod && parsedEnv.value === "preview") {
+        throw new WorkserError(
+          "`--prod` and `--env preview` ask for different things. Pass one.",
+          { code: "bad_input" }
+        );
+      }
+      const prod = Boolean(opts.prod) || parsedEnv.value === "production";
       const dep = await api(ctx, `/v1/projects/${projectId}/deploy`, {
         body: {
-          prod: Boolean(opts.prod),
+          prod,
           cwd: ctx.cwd,
           ...opts.app ? { webAppId: opts.app } : {}
         }
@@ -5743,10 +6596,22 @@ function printDeploy(dep) {
 // src/commands/versions.ts
 var import_picocolors11 = __toESM(require_picocolors(), 1);
 function registerVersions(program3) {
-  program3.command("versions").description("List the Workser-managed versions of the project (deploy history)").action(
-    action(async ({ ctx }) => {
+  program3.command("versions").description("List the Workser-managed versions of the project (deploy history)").option("--app <webAppId>", "which app (defaults to the primary app)").option(
+    "--env <environment>",
+    "which environment `deployed` should mean: preview or production"
+  ).action(
+    action(async ({ ctx, opts }) => {
       const projectId = requireProject(ctx);
-      const items = await api(ctx, `/v1/projects/${projectId}/versions`);
+      const parsed = parseDeployEnvironment(opts.env, "versions");
+      if (!parsed.ok) {
+        throw new WorkserError(parsed.error, { code: "bad_input" });
+      }
+      const items = await api(ctx, `/v1/projects/${projectId}/versions`, {
+        query: {
+          ...opts.app ? { webAppId: String(opts.app) } : {},
+          ...parsed.value ? { environment: parsed.value } : {}
+        }
+      });
       ok(items, () => {
         if (!items?.length) return line(import_picocolors11.default.dim("No versions yet. `workser deploy` to create one."));
         for (const v of items) {
@@ -5760,7 +6625,7 @@ function formatVersion(v) {
   const ref = import_picocolors11.default.yellow(shortRef(v.ref));
   const when = import_picocolors11.default.dim(formatTime(v.createdAt));
   const msg = (v.message ?? "").trim() || import_picocolors11.default.dim("(no message)");
-  const badge = v.deployed ? "  " + import_picocolors11.default.green("deployed") : "";
+  const badge = v.deployed ? "  " + import_picocolors11.default.green(v.deployedEnvironment ? `live in ${v.deployedEnvironment}` : "deployed") : "";
   const url = v.url ? "  " + import_picocolors11.default.cyan(v.url) : "";
   return `${ref}  ${when}  ${msg}${badge}${url}`;
 }
@@ -5775,19 +6640,30 @@ function formatTime(t) {
 }
 
 // src/commands/logs.ts
+var import_picocolors12 = __toESM(require_picocolors(), 1);
 function registerLogs(program3) {
-  program3.command("logs").description("Show recent logs for the project's app").option("-n, --lines <n>", "number of lines", "100").option("-f, --follow", "keep streaming new logs", false).action(
+  program3.command("logs").description("Show the build logs of the latest deployment").option("-n, --lines <n>", "number of lines", "100").option("-f, --follow", "keep streaming new logs", false).option("--app <webAppId>", "which app (defaults to the primary app)").option("--env <environment>", "preview or production (default: whichever deployed last)").action(
     action(async ({ ctx, opts }) => {
       const projectId = requireProject(ctx);
+      const parsed = parseDeployEnvironment(opts.env, "logs");
+      if (!parsed.ok) {
+        throw new WorkserError(parsed.error, { code: "bad_input" });
+      }
+      const scope = {
+        ...opts.app ? { webAppId: String(opts.app) } : {},
+        ...parsed.value ? { environment: parsed.value } : {}
+      };
       const first = await api(ctx, `/v1/projects/${projectId}/logs`, {
-        query: { lines: opts.lines }
+        query: { lines: opts.lines, ...scope }
       });
-      ok(first, () => (first.entries ?? []).forEach((e) => line(formatLog(e))));
+      ok(first, () => print(first));
       if (opts.follow && !isJson()) {
         let cursor = first.cursor;
         for (; ; ) {
           await sleep(2e3);
-          const next = await api(ctx, `/v1/projects/${projectId}/logs`, { query: { after: cursor } });
+          const next = await api(ctx, `/v1/projects/${projectId}/logs`, {
+            query: { after: cursor, ...scope }
+          });
           (next.entries ?? []).forEach((e) => line(formatLog(e)));
           if (next.cursor) cursor = next.cursor;
         }
@@ -5795,31 +6671,112 @@ function registerLogs(program3) {
     })
   );
 }
+function print(res) {
+  const entries = res?.entries ?? [];
+  for (const e of entries) line(formatLog(e));
+  if (!entries.length && res?.note) line(import_picocolors12.default.dim(res.note));
+  if (entries.length && res?.deploymentId) {
+    const where = res.environment ? ` (${res.environment})` : "";
+    line(import_picocolors12.default.dim(`\u2014 build ${res.deploymentId}${where}`));
+  }
+}
 function formatLog(e) {
   if (typeof e === "string") return e;
   return `${e.ts ?? ""} ${e.level ? `[${e.level}] ` : ""}${e.message ?? ""}`.trim();
 }
 
 // src/commands/domain.ts
-var import_picocolors12 = __toESM(require_picocolors(), 1);
+var import_picocolors13 = __toESM(require_picocolors(), 1);
+
+// src/reserved-domains.ts
+var RESERVED_APEX = [
+  "workser.ai",
+  "workser.app",
+  "workser.dev"
+];
+var PROVIDER_HOSTS = ["vercel.app", "neon.tech", "expo.dev"];
+function normaliseDomain(input) {
+  return input.trim().toLowerCase().replace(/^https?:\/\//, "").replace(/\/.*$/, "").replace(/:\d+$/, "").replace(/\.$/, "");
+}
+function isUnder(host, suffix) {
+  return host === suffix || host.endsWith(`.${suffix}`);
+}
+function checkDomain(input) {
+  const host = normaliseDomain(input);
+  if (!host) {
+    return { allowed: false, reason: "No domain given." };
+  }
+  if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/.test(host)) {
+    return {
+      allowed: false,
+      reason: `"${input}" is not a valid domain name.`
+    };
+  }
+  for (const apex of RESERVED_APEX) {
+    if (isUnder(host, apex)) {
+      return {
+        allowed: false,
+        reason: `${host} belongs to Workser and cannot be attached to a project. Use a domain the customer owns. Workser's own preview and live addresses are assigned automatically \u2014 there is nothing to attach.`
+      };
+    }
+  }
+  for (const provider of PROVIDER_HOSTS) {
+    if (isUnder(host, provider)) {
+      return {
+        allowed: false,
+        reason: `${host} is assigned by the hosting provider, not attached as a custom domain. If you were trying to find where this app is already served, read its URLs instead of adding a domain.`
+      };
+    }
+  }
+  return { allowed: true };
+}
+function assertDomainAllowed(input) {
+  const verdict = checkDomain(input);
+  if (!verdict.allowed) throw new Error(verdict.reason);
+  return normaliseDomain(input);
+}
+
+// src/commands/domain.ts
 function registerDomain(program3) {
-  const domain = program3.command("domain").description("Inspect the project's custom domains");
-  domain.command("set <domain>").description("(owner-only) Attach a custom domain \u2014 do this in Workser Orbit").action(
-    action(
-      () => ownerOnly({
-        action: "domain set",
-        reason: "attaching a custom domain",
-        owner: "add the domain (and verify DNS)"
-      })
-    )
+  const domain = program3.command("domain").description("Manage the project's custom domains");
+  domain.command("add <domain>").description("Attach a custom domain or subdomain (asks the owner to confirm)").option("--app <webAppId>", "Which app to attach it to").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const host = assertDomainAllowed(String(args[0]));
+      const result = await api(
+        ctx,
+        opts.app ? `/v1/projects/${projectId}/web-apps/${opts.app}/domains` : `/v1/projects/${projectId}/domains`,
+        { method: "POST", body: { domain: host } }
+      );
+      ok(result, () => {
+        line(`${import_picocolors13.default.green("Attached")} ${host}`);
+        line(
+          import_picocolors13.default.dim(
+            "It goes live once DNS points at us. Run `workser domain list` to see its status."
+          )
+        );
+      });
+    })
+  );
+  domain.command("rm <domain>").description("Detach a custom domain (asks the owner to confirm)").option("--app <webAppId>", "Which app it is attached to").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const host = String(args[0]).trim().toLowerCase();
+      const result = await api(
+        ctx,
+        opts.app ? `/v1/projects/${projectId}/web-apps/${opts.app}/domains/${encodeURIComponent(host)}` : `/v1/projects/${projectId}/domains/${encodeURIComponent(host)}`,
+        { method: "DELETE" }
+      );
+      ok(result, () => line(`${import_picocolors13.default.yellow("Detached")} ${host}`));
+    })
   );
   domain.command("list").description("List domains attached to the project").action(
     action(async ({ ctx }) => {
       const projectId = requireProject(ctx);
       const items = await api(ctx, `/v1/projects/${projectId}/domains`);
       ok(items, () => {
-        if (!items?.length) return line(import_picocolors12.default.dim("No custom domains."));
-        for (const d of items) line(`${d.domain}${import_picocolors12.default.dim("  " + (d.status ?? ""))}`);
+        if (!items?.length) return line(import_picocolors13.default.dim("No custom domains."));
+        for (const d of items) line(`${d.domain}${import_picocolors13.default.dim("  " + (d.status ?? ""))}`);
       });
     })
   );
@@ -5851,7 +6808,7 @@ function openUrl(url) {
 }
 
 // src/commands/doctor.ts
-var import_picocolors13 = __toESM(require_picocolors(), 1);
+var import_picocolors14 = __toESM(require_picocolors(), 1);
 import { spawnSync } from "child_process";
 function registerDoctor(program3) {
   program3.command("doctor").description("Print the resolved endpoint, mode, token presence (masked), and current project").action(
@@ -5863,14 +6820,14 @@ function registerDoctor(program3) {
       const tokenSource = opts.token ? "--token" : process.env.WORKSER_TOKEN ? "$WORKSER_TOKEN" : session.token ? "session" : void 0;
       const endpointSource = opts.endpoint ? "--endpoint" : process.env.WORKSER_DAEMON_URL ? "$WORKSER_DAEMON_URL" : session.endpoint ? "session" : process.env.WORKSER_API_URL ? "$WORKSER_API_URL" : `cloud-default: ${env}`;
       const projectSource = opts.project ? "--project" : link?.projectId ? ".workser link" : session.defaultProjectId ? "session" : void 0;
-      const git = gitVersion();
+      const git2 = gitVersion();
       const report = {
         endpoint: ctx.endpoint,
         endpointSource,
         env,
         envIgnored,
         mode: ctx.mode,
-        git: { present: git !== null, version: git },
+        git: { present: git2 !== null, version: git2 },
         token: {
           present: Boolean(ctx.token),
           masked: ctx.token ? maskToken(ctx.token) : null,
@@ -5885,29 +6842,29 @@ function registerDoctor(program3) {
         workspace: session.workspaceName ?? null
       };
       ok(report, () => {
-        line(import_picocolors13.default.bold("workser doctor"));
-        line(`  endpoint:  ${ctx.endpoint} ${import_picocolors13.default.dim(`(${endpointSource})`)}`);
+        line(import_picocolors14.default.bold("workser doctor"));
+        line(`  endpoint:  ${ctx.endpoint} ${import_picocolors14.default.dim(`(${endpointSource})`)}`);
         line(
-          `  env:       ${env === "prod" ? import_picocolors13.default.yellow(env) : env}` + import_picocolors13.default.dim(process.env.WORKSER_ENV ? "  ($WORKSER_ENV)" : "  (default)")
+          `  env:       ${env === "prod" ? import_picocolors14.default.yellow(env) : env}` + import_picocolors14.default.dim(process.env.WORKSER_ENV ? "  ($WORKSER_ENV)" : "  (default)")
         );
         line(`  mode:      ${ctx.mode}`);
         line(
-          `  token:     ${ctx.token ? `${maskToken(ctx.token)} ${import_picocolors13.default.dim(`(${tokenSource})`)}` : import_picocolors13.default.yellow("none \u2014 run `workser login`")}`
+          `  token:     ${ctx.token ? `${maskToken(ctx.token)} ${import_picocolors14.default.dim(`(${tokenSource})`)}` : import_picocolors14.default.yellow("none \u2014 run `workser login`")}`
         );
         line(
-          `  project:   ${ctx.projectId ?? import_picocolors13.default.dim("none")}` + (link?.name ? `  ${import_picocolors13.default.dim(`(${link.name})`)}` : "") + (projectSource ? import_picocolors13.default.dim(`  [${projectSource}]`) : "")
+          `  project:   ${ctx.projectId ?? import_picocolors14.default.dim("none")}` + (link?.name ? `  ${import_picocolors14.default.dim(`(${link.name})`)}` : "") + (projectSource ? import_picocolors14.default.dim(`  [${projectSource}]`) : "")
         );
         line(`  cwd:       ${ctx.cwd}`);
-        line(`  git:       ${git ?? import_picocolors13.default.dim("not on this shell's PATH")}`);
-        if (!git) {
+        line(`  git:       ${git2 ?? import_picocolors14.default.dim("not on this shell's PATH")}`);
+        if (!git2) {
           line("");
           line(
-            import_picocolors13.default.dim(
+            import_picocolors14.default.dim(
               "  Workser brings its own git, so syncing and publishing still work."
             )
           );
           line(
-            import_picocolors13.default.dim(
+            import_picocolors14.default.dim(
               `  Only needed if you want to run git yourself here. ${GIT_INSTALL_HINT}`
             )
           );
@@ -5915,16 +6872,16 @@ function registerDoctor(program3) {
         if (envIgnored) {
           line("");
           line(
-            import_picocolors13.default.yellow(
+            import_picocolors14.default.yellow(
               `  WORKSER_ENV=${env} is not in effect \u2014 ${endpointSource} wins.`
             )
           );
           line(
-            import_picocolors13.default.dim(
+            import_picocolors14.default.dim(
               `  Re-run \`workser login\` to switch (the saved token is tied to ${ctx.endpoint}),`
             )
           );
-          line(import_picocolors13.default.dim(`  or pass --endpoint ${ENV_BASE_URLS[env]}.`));
+          line(import_picocolors14.default.dim(`  or pass --endpoint ${ENV_BASE_URLS[env]}.`));
         }
       });
     })
@@ -5954,7 +6911,7 @@ function maskToken(token) {
 }
 
 // src/commands/agent.ts
-var import_picocolors14 = __toESM(require_picocolors(), 1);
+var import_picocolors15 = __toESM(require_picocolors(), 1);
 var SPAWNABLE_AGENTS = ["claude_code", "codex", "kimi", "opencode", "grok"];
 function registerAgent(program3) {
   const agent = program3.command("agent").description("Delegate focused subtasks to your configured agent roles (each runs isolated)");
@@ -5962,20 +6919,20 @@ function registerAgent(program3) {
     action(async ({ ctx }) => {
       const cfg = await api(ctx, "/v1/agents");
       ok(cfg, () => {
-        line(import_picocolors14.default.bold("main agent:") + " " + (cfg?.mainAgent ?? import_picocolors14.default.dim("none")));
-        line(import_picocolors14.default.bold("backup agent:") + " " + (cfg?.backupAgent ?? import_picocolors14.default.dim("none")));
+        line(import_picocolors15.default.bold("main agent:") + " " + (cfg?.mainAgent ?? import_picocolors15.default.dim("none")));
+        line(import_picocolors15.default.bold("backup agent:") + " " + (cfg?.backupAgent ?? import_picocolors15.default.dim("none")));
         if (cfg?.effectiveMainAgent && cfg.effectiveMainAgent !== cfg.mainAgent) {
           line(
-            import_picocolors14.default.yellow(
+            import_picocolors15.default.yellow(
               `  \u2937 failover active: runs use ${cfg.effectiveMainAgent} (main not available)`
             )
           );
         }
         const roles = cfg?.roles ?? [];
         if (!roles.length) {
-          line(import_picocolors14.default.dim("No subagents configured. Add them in the Workser Orbit Agents screen."));
+          line(import_picocolors15.default.dim("No subagents configured. Add them in the Workser Orbit Agents screen."));
         } else {
-          line(import_picocolors14.default.bold("subagents:"));
+          line(import_picocolors15.default.bold("subagents:"));
           for (const r of roles) line("  " + formatRole(r));
         }
         const detected = cfg?.detected ?? [];
@@ -5983,7 +6940,7 @@ function registerAgent(program3) {
           (d) => d?.installed && d?.authed !== false
         );
         line(
-          import_picocolors14.default.bold("spawnable (workser agent spawn <agent>):") + " " + (spawnable.length ? spawnable.map((d) => toContractId(d.id)).join(", ") : import_picocolors14.default.dim("none connected"))
+          import_picocolors15.default.bold("spawnable (workser agent spawn <agent>):") + " " + (spawnable.length ? spawnable.map((d) => toContractId(d.id)).join(", ") : import_picocolors15.default.dim("none connected"))
         );
       });
     })
@@ -5997,8 +6954,8 @@ function registerAgent(program3) {
           backupAgent: cfg?.backupAgent ?? null
         },
         () => {
-          line(import_picocolors14.default.bold("main agent:") + " " + (cfg?.mainAgent ?? import_picocolors14.default.dim("none")));
-          line(import_picocolors14.default.bold("backup agent:") + " " + (cfg?.backupAgent ?? import_picocolors14.default.dim("none")));
+          line(import_picocolors15.default.bold("main agent:") + " " + (cfg?.mainAgent ?? import_picocolors15.default.dim("none")));
+          line(import_picocolors15.default.bold("backup agent:") + " " + (cfg?.backupAgent ?? import_picocolors15.default.dim("none")));
         }
       );
     })
@@ -6052,21 +7009,21 @@ function toContractId(id) {
   return id === "claude" ? "claude_code" : id;
 }
 function formatRole(r) {
-  const label = import_picocolors14.default.yellow(r.role);
-  const agent = import_picocolors14.default.dim("\xB7 " + (r.agent ?? "?"));
-  const enabled = r.enabled === false ? import_picocolors14.default.red("disabled") : import_picocolors14.default.green("enabled");
+  const label = import_picocolors15.default.yellow(r.role);
+  const agent = import_picocolors15.default.dim("\xB7 " + (r.agent ?? "?"));
+  const enabled = r.enabled === false ? import_picocolors15.default.red("disabled") : import_picocolors15.default.green("enabled");
   const runnable = r.installed && r.authed !== false;
-  const ready = runnable ? import_picocolors14.default.green("runnable") : import_picocolors14.default.dim("not runnable");
+  const ready = runnable ? import_picocolors15.default.green("runnable") : import_picocolors15.default.dim("not runnable");
   const extras = [];
   if (r.model) extras.push(`model ${r.model}`);
   if (Array.isArray(r.apps) && r.apps.length) extras.push(`apps: ${r.apps.join(",")}`);
   if (Array.isArray(r.mcp) && r.mcp.length) extras.push(`mcp: ${r.mcp.length}`);
-  const tail = extras.length ? "  " + import_picocolors14.default.dim(extras.join(" \xB7 ")) : "";
+  const tail = extras.length ? "  " + import_picocolors15.default.dim(extras.join(" \xB7 ")) : "";
   return `${label}  ${agent}  ${enabled}  ${ready}${tail}`;
 }
 
 // src/commands/verify.ts
-var import_picocolors15 = __toESM(require_picocolors(), 1);
+var import_picocolors16 = __toESM(require_picocolors(), 1);
 function registerVerify(program3) {
   program3.command("verify").description(
     "Run the project's checks (typecheck/lint/build) \u2014 use before declaring a task done"
@@ -6088,23 +7045,23 @@ function registerVerify(program3) {
 function printVerify(res) {
   if (!res) return;
   if (!res.checks?.length) {
-    line(import_picocolors15.default.dim(res.note ?? "No checks detected."));
+    line(import_picocolors16.default.dim(res.note ?? "No checks detected."));
     return;
   }
   for (const c of res.checks) {
     line(
-      `  ${c.ok ? import_picocolors15.default.green("\u2713") : import_picocolors15.default.red("\u2717")} ${c.name}${c.ok ? "" : import_picocolors15.default.dim(` (exit ${c.exitCode})`)}`
+      `  ${c.ok ? import_picocolors16.default.green("\u2713") : import_picocolors16.default.red("\u2717")} ${c.name}${c.ok ? "" : import_picocolors16.default.dim(` (exit ${c.exitCode})`)}`
     );
   }
   if (res.ok) success("All checks passed");
   else
     line(
-      import_picocolors15.default.red("Some checks failed \u2014 fix the errors above and re-run ") + import_picocolors15.default.bold("workser verify") + import_picocolors15.default.red(".")
+      import_picocolors16.default.red("Some checks failed \u2014 fix the errors above and re-run ") + import_picocolors16.default.bold("workser verify") + import_picocolors16.default.red(".")
     );
 }
 
 // src/commands/checkpoint.ts
-var import_picocolors16 = __toESM(require_picocolors(), 1);
+var import_picocolors17 = __toESM(require_picocolors(), 1);
 function registerCheckpoint(program3) {
   program3.command("checkpoint [label]").description(
     "Save the current state of this folder so you can come back to it"
@@ -6121,8 +7078,8 @@ function registerCheckpoint(program3) {
       ok(res, () => {
         const p = res?.point;
         success(`Saved a checkpoint${p?.label ? `: ${p.label}` : ""}`);
-        if (p?.ref) line(import_picocolors16.default.dim(`  ${p.ref.slice(0, 7)}`));
-        line(import_picocolors16.default.dim("  Come back to it with `workser restore`."));
+        if (p?.ref) line(import_picocolors17.default.dim(`  ${p.ref.slice(0, 7)}`));
+        line(import_picocolors17.default.dim("  Come back to it with `workser restore`."));
       });
     })
   );
@@ -6148,12 +7105,12 @@ function registerCheckpoint(program3) {
         );
         if (res?.filesChanged) {
           line(
-            import_picocolors16.default.dim(
+            import_picocolors17.default.dim(
               `  ${res.filesChanged} file${res.filesChanged === 1 ? "" : "s"} changed`
             )
           );
         }
-        line(import_picocolors16.default.dim("  This is reversible: `workser restore` again."));
+        line(import_picocolors17.default.dim("  This is reversible: `workser restore` again."));
       });
     })
   );
@@ -6170,25 +7127,25 @@ function registerCheckpoint(program3) {
 function printPoints(points) {
   if (!points.length) {
     info("No checkpoints yet for this folder.");
-    line(import_picocolors16.default.dim("  Take one with `workser checkpoint`."));
+    line(import_picocolors17.default.dim("  Take one with `workser checkpoint`."));
     return;
   }
-  line(import_picocolors16.default.bold("Checkpoints"));
+  line(import_picocolors17.default.bold("Checkpoints"));
   for (const p of points) {
     const when = p.at ? new Date(p.at).toLocaleString() : "";
     line(
-      `  ${import_picocolors16.default.dim(p.ref.slice(0, 7))}  ${p.label}${when ? import_picocolors16.default.dim(`  ${when}`) : ""}`
+      `  ${import_picocolors17.default.dim(p.ref.slice(0, 7))}  ${p.label}${when ? import_picocolors17.default.dim(`  ${when}`) : ""}`
     );
   }
   line(
-    import_picocolors16.default.dim(
+    import_picocolors17.default.dim(
       "\nGo back with `workser restore <ref>`, or just `workser restore` for the newest."
     )
   );
 }
 
 // src/commands/sync.ts
-var import_picocolors17 = __toESM(require_picocolors(), 1);
+var import_picocolors18 = __toESM(require_picocolors(), 1);
 function registerSync(program3) {
   program3.command("sync").description(
     "Reconcile this folder with the copy Workser holds (pull, then push)"
@@ -6215,7 +7172,7 @@ function registerSync(program3) {
           warn(res?.message ?? "Couldn't sync this folder.");
           if (res?.state === "diverged") {
             line(
-              import_picocolors17.default.dim(
+              import_picocolors18.default.dim(
                 "  This folder and Workser's copy have both changed. Open Workser to resolve it."
               )
             );
@@ -6227,7 +7184,7 @@ function registerSync(program3) {
           return;
         }
         success("Synced");
-        if (res?.ref) line(import_picocolors17.default.dim(`  ${String(res.ref).slice(0, 7)}`));
+        if (res?.ref) line(import_picocolors18.default.dim(`  ${String(res.ref).slice(0, 7)}`));
       });
       if (refused) process.exitCode = 1;
     })
@@ -6235,7 +7192,7 @@ function registerSync(program3) {
 }
 
 // src/commands/workflow.ts
-var import_picocolors18 = __toESM(require_picocolors(), 1);
+var import_picocolors19 = __toESM(require_picocolors(), 1);
 function registerWorkflow(program3) {
   const wf = program3.command("workflow").description("Create, run, and inspect workflow automations for the project");
   wf.command("list").description("List the project's workflows").action(
@@ -6243,10 +7200,10 @@ function registerWorkflow(program3) {
       const projectId = requireProject(ctx);
       const items = await api(ctx, `/v1/projects/${projectId}/workflows`);
       ok(items, () => {
-        if (!items?.length) return line(import_picocolors18.default.dim("No workflows yet. `workser workflow create`."));
+        if (!items?.length) return line(import_picocolors19.default.dim("No workflows yet. `workser workflow create`."));
         for (const w of items) {
-          const status = w.is_active ? import_picocolors18.default.green("active") : import_picocolors18.default.dim("inactive");
-          line(`${w.id}  ${import_picocolors18.default.bold(w.name ?? "Untitled")}  ${status}`);
+          const status = w.is_active ? import_picocolors19.default.green("active") : import_picocolors19.default.dim("inactive");
+          line(`${w.id}  ${import_picocolors19.default.bold(w.name ?? "Untitled")}  ${status}`);
         }
       });
     })
@@ -6258,7 +7215,7 @@ function registerWorkflow(program3) {
       const res = await api(ctx, `/v1/projects/${projectId}/workflows`, {
         body: { name: args[0], ...extra }
       });
-      ok(res, () => line(`Created workflow ${import_picocolors18.default.bold(res.id)}.`));
+      ok(res, () => line(`Created workflow ${import_picocolors19.default.bold(res.id)}.`));
     })
   );
   wf.command("get <id>").description("Show a workflow's full definition").action(
@@ -6293,8 +7250,8 @@ function registerWorkflow(program3) {
     action(async ({ ctx, args }) => {
       const items = await api(ctx, `/v1/workflows/${args[0]}/executions`);
       ok(items, () => {
-        if (!items?.length) return line(import_picocolors18.default.dim("No runs yet."));
-        for (const e of items) line(`${e.id}  ${e.status ?? ""}  ${import_picocolors18.default.dim(e.started_at ?? "")}`);
+        if (!items?.length) return line(import_picocolors19.default.dim("No runs yet."));
+        for (const e of items) line(`${e.id}  ${e.status ?? ""}  ${import_picocolors19.default.dim(e.started_at ?? "")}`);
       });
     })
   );
@@ -6302,15 +7259,15 @@ function registerWorkflow(program3) {
     action(async ({ ctx, args }) => {
       const items = await api(ctx, `/v1/node-types`, { query: { q: args[0] } });
       ok(items, () => {
-        if (!items?.length) return line(import_picocolors18.default.dim("No matching node types."));
-        for (const n of items) line(`${n.name ?? n.type}  ${import_picocolors18.default.dim(n.category ?? "")}`);
+        if (!items?.length) return line(import_picocolors19.default.dim("No matching node types."));
+        for (const n of items) line(`${n.name ?? n.type}  ${import_picocolors19.default.dim(n.category ?? "")}`);
       });
     })
   );
 }
 
 // src/commands/app.ts
-var import_picocolors19 = __toESM(require_picocolors(), 1);
+var import_picocolors20 = __toESM(require_picocolors(), 1);
 function registerApp(program3) {
   const appCmd = program3.command("app").description("Connect and use third-party app integrations (Gmail, Slack, Stripe, ...)");
   appCmd.command("list").description("List connectable toolkits and this project's existing connections").option("--toolkit <slug>", "filter connections to one toolkit").action(
@@ -6323,8 +7280,8 @@ function registerApp(program3) {
       ok({ catalog, connections }, () => {
         const connected = new Set((connections ?? []).map((c) => c.toolkit ?? c.composio_app));
         for (const t of catalog ?? []) {
-          const status = connected.has(t.slug) ? import_picocolors19.default.green("connected") : import_picocolors19.default.dim("not connected");
-          line(`${t.slug}  ${import_picocolors19.default.bold(t.name ?? t.slug)}  ${status}`);
+          const status = connected.has(t.slug) ? import_picocolors20.default.green("connected") : import_picocolors20.default.dim("not connected");
+          line(`${t.slug}  ${import_picocolors20.default.bold(t.name ?? t.slug)}  ${status}`);
         }
       });
     })
@@ -6341,7 +7298,7 @@ function registerApp(program3) {
       });
       ok(
         res,
-        () => res.oauth_url ? line(`Open this URL to finish connecting: ${import_picocolors19.default.underline(res.oauth_url)}`) : line(`Connection ${res.connection_id} is ${res.status}.`)
+        () => res.oauth_url ? line(`Open this URL to finish connecting: ${import_picocolors20.default.underline(res.oauth_url)}`) : line(`Connection ${res.connection_id} is ${res.status}.`)
       );
     })
   );
@@ -6359,8 +7316,8 @@ function registerApp(program3) {
       const projectId = requireProject(ctx);
       const items = await api(ctx, `/v1/projects/${projectId}/integrations/${args[0]}/tools`);
       ok(items, () => {
-        if (!items?.length) return line(import_picocolors19.default.dim("No tools found."));
-        for (const t of items) line(`${t.slug}  ${import_picocolors19.default.dim(t.description ?? "")}`);
+        if (!items?.length) return line(import_picocolors20.default.dim("No tools found."));
+        for (const t of items) line(`${t.slug}  ${import_picocolors20.default.dim(t.description ?? "")}`);
       });
     })
   );
@@ -6376,7 +7333,7 @@ function registerApp(program3) {
 }
 
 // src/commands/tool.ts
-var import_picocolors20 = __toESM(require_picocolors(), 1);
+var import_picocolors21 = __toESM(require_picocolors(), 1);
 function registerTool(program3) {
   const tool = program3.command("tool").description(
     "Computer-use tools: filesystem, shell, screenshot, input control, clipboard, notifications, basic browser"
@@ -6385,7 +7342,7 @@ function registerTool(program3) {
     action(async ({ ctx }) => {
       const tools = await api(ctx, "/v1/tool/list");
       ok(tools, () => {
-        if (!tools?.length) return line(import_picocolors20.default.dim("No tools available."));
+        if (!tools?.length) return line(import_picocolors21.default.dim("No tools available."));
         const byCategory = /* @__PURE__ */ new Map();
         for (const t of tools) {
           const list = byCategory.get(t.category) ?? [];
@@ -6393,9 +7350,9 @@ function registerTool(program3) {
           byCategory.set(t.category, list);
         }
         for (const [category, items] of byCategory) {
-          line(import_picocolors20.default.bold(category) + ":");
+          line(import_picocolors21.default.bold(category) + ":");
           for (const t of items) {
-            line(`  ${t.name}  ${import_picocolors20.default.dim(t.description ?? "")}`);
+            line(`  ${t.name}  ${import_picocolors21.default.dim(t.description ?? "")}`);
           }
         }
       });
@@ -6413,7 +7370,7 @@ function registerTool(program3) {
 }
 
 // src/commands/memory.ts
-var import_picocolors21 = __toESM(require_picocolors(), 1);
+var import_picocolors22 = __toESM(require_picocolors(), 1);
 function registerMemory(program3) {
   const memory = program3.command("memory").description("Durable, cross-conversation project memory (shared with cloud agents on the same project)");
   memory.command("add <content>").description("Store something worth remembering across future conversations").option("--metadata <json>", "extra metadata for filtering, as a JSON string").option("--id <customId>", "custom id for dedup/updates").action(
@@ -6437,9 +7394,9 @@ function registerMemory(program3) {
       });
       ok(res, () => {
         const results = res?.results ?? res ?? [];
-        if (!results?.length) return line(import_picocolors21.default.dim("No matching memories."));
+        if (!results?.length) return line(import_picocolors22.default.dim("No matching memories."));
         for (const r of results) {
-          line(`${import_picocolors21.default.dim(r.id ?? "?")}  ${r.memory ?? r.content ?? ""}`);
+          line(`${import_picocolors22.default.dim(r.id ?? "?")}  ${r.memory ?? r.content ?? ""}`);
         }
       });
     })
@@ -6456,7 +7413,7 @@ function registerMemory(program3) {
 }
 
 // src/commands/business.ts
-var import_picocolors22 = __toESM(require_picocolors(), 1);
+var import_picocolors23 = __toESM(require_picocolors(), 1);
 var RESOURCE_PATHS = {
   "business-config": "business-config",
   "business-settings": "business-settings",
@@ -6516,7 +7473,7 @@ function registerBusiness(program3) {
       const projectId = requireProject(ctx);
       const [resource] = args;
       const res = await api(ctx, businessPath(projectId, resource), { body: JSON.parse(opts.body) });
-      ok(res, () => line(`Created ${resource} ${import_picocolors22.default.bold(res?.id ?? "")}.`));
+      ok(res, () => line(`Created ${resource} ${import_picocolors23.default.bold(res?.id ?? "")}.`));
     })
   );
   biz.command("update <resource> <id>").description("Update a record by id (PATCH/PUT \u2014 matches the underlying route)").option("--body <json>", "changed fields as a JSON object string", "{}").action(
@@ -6558,7 +7515,7 @@ function businessPath(projectId, resource, subpath) {
 }
 
 // src/commands/artifact.ts
-var import_picocolors23 = __toESM(require_picocolors(), 1);
+var import_picocolors24 = __toESM(require_picocolors(), 1);
 import { existsSync as existsSync2, statSync } from "fs";
 import { resolve as resolve2, basename as basename3 } from "path";
 var KINDS = [
@@ -6575,14 +7532,28 @@ var KINDS = [
   "audio",
   "document",
   "archive",
-  "other"
+  "other",
+  // Deliverable shapes — see above.
+  "report",
+  "walkthrough",
+  "before_after",
+  "checks",
+  "web_app",
+  "service",
+  "design"
 ];
 function registerArtifact(program3) {
   const artifact = program3.command("artifact").description("Record the files, folders and apps this task produced");
   artifact.command("add [path]").description("Register a deliverable so it shows on the task").option(
     "-k, --kind <kind>",
     `what it is: ${KINDS.join(" | ")} (default: inferred from the path)`
-  ).option("-t, --title <title>", "display name (default: the file name)").option("-d, --description <text>", "one line on what it is / what it's for").option("-u, --url <url>", "a hosted deliverable (deployed app, public file)").action(
+  ).option("-t, --title <title>", "display name (default: the file name)").option("-d, --description <text>", "one line on what it is / what it's for").option("-u, --url <url>", "a hosted deliverable (deployed app, public file)").option(
+    "--data <json>",
+    `figures the card shows, as JSON \u2014 e.g. '{"passed":12,"total":12}'`
+  ).option(
+    "--promote",
+    "hand it straight to the task as one of the things the owner asked for"
+  ).action(
     action(async ({ ctx, opts, args }) => {
       const rawPath = args[0];
       const url = opts.url;
@@ -6612,19 +7583,36 @@ function registerArtifact(program3) {
           { code: "bad_request" }
         );
       }
+      let data;
+      if (opts.data) {
+        try {
+          const parsed = JSON.parse(String(opts.data));
+          if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("not an object");
+          }
+          data = parsed;
+        } catch (err) {
+          throw new WorkserError(
+            `--data must be a JSON object. ${err instanceof Error ? err.message : String(err)}`,
+            { code: "bad_request" }
+          );
+        }
+      }
       const res = await api(ctx, `/v1/runs/${runTarget(ctx)}/artifacts`, {
         body: {
           path: absPath,
           url,
           kind,
           title: opts.title || (absPath ? basename3(absPath) : url),
-          description: opts.description
+          description: opts.description,
+          data,
+          promote: opts.promote ? true : void 0
         }
       });
       ok(
         res,
         () => success(
-          `Recorded ${import_picocolors23.default.bold(res?.title ?? "artifact")}${res?.kind ? import_picocolors23.default.dim(` (${res.kind})`) : ""}`
+          `Recorded ${import_picocolors24.default.bold(res?.title ?? "artifact")}${res?.kind ? import_picocolors24.default.dim(` (${res.kind})`) : ""}`
         )
       );
     })
@@ -6638,11 +7626,11 @@ function registerArtifact(program3) {
 }
 function printRun(run) {
   if (!run) return;
-  line(`  run      ${import_picocolors23.default.bold(run.runId)}`);
+  line(`  run      ${import_picocolors24.default.bold(run.runId)}`);
   if (run.taskId) line(`  task     ${run.taskId}`);
   if (run.conversationId) line(`  chat     ${run.conversationId}`);
   if (run.projectId) line(`  project  ${run.projectId}`);
-  if (run.cwd) line(`  folder   ${import_picocolors23.default.dim(run.cwd)}`);
+  if (run.cwd) line(`  folder   ${import_picocolors24.default.dim(run.cwd)}`);
 }
 
 // src/commands/image.ts
@@ -6716,7 +7704,7 @@ async function download(url, output) {
 }
 
 // src/commands/ask.ts
-var import_picocolors24 = __toESM(require_picocolors(), 1);
+var import_picocolors25 = __toESM(require_picocolors(), 1);
 var TYPES = [
   "input",
   "choice",
@@ -6767,7 +7755,7 @@ function registerAsk(program3) {
           code: "bad_request"
         });
       }
-      info(import_picocolors24.default.dim("Waiting for the user to answer\u2026"));
+      info(import_picocolors25.default.dim("Waiting for the user to answer\u2026"));
       const res = await api(ctx, `/v1/runs/${runTarget(ctx)}/ask`, {
         body: {
           type,
@@ -6793,12 +7781,12 @@ function deriveTitle(message) {
 function printAnswer(res) {
   if (!res) return;
   if (res.status === "answered") {
-    line(`  ${import_picocolors24.default.green("answered")}`);
+    line(`  ${import_picocolors25.default.green("answered")}`);
     const value = extract(res.response);
     if (value) line(`  ${value}`);
     return;
   }
-  line(`  ${import_picocolors24.default.yellow(res.status)}  ${import_picocolors24.default.dim(res.reason ?? "")}`);
+  line(`  ${import_picocolors25.default.yellow(res.status)}  ${import_picocolors25.default.dim(res.reason ?? "")}`);
 }
 function extract(response) {
   if (response == null) return "";
@@ -6817,7 +7805,7 @@ function extract(response) {
 }
 
 // src/commands/search.ts
-var import_picocolors25 = __toESM(require_picocolors(), 1);
+var import_picocolors26 = __toESM(require_picocolors(), 1);
 function registerSearch(program3) {
   program3.command("search <query>").description("Search the web (Google-grounded, server-side)").option("-n, --max-results <n>", "max results", "5").action(
     action(async ({ ctx, args, opts }) => {
@@ -6830,9 +7818,9 @@ function registerSearch(program3) {
           line("");
         }
         const results = res?.results ?? [];
-        if (!results.length) return line(import_picocolors25.default.dim("No results."));
+        if (!results.length) return line(import_picocolors26.default.dim("No results."));
         for (const r of results) {
-          line(`${r.title || import_picocolors25.default.dim("(untitled)")}  ${import_picocolors25.default.dim(r.url)}`);
+          line(`${r.title || import_picocolors26.default.dim("(untitled)")}  ${import_picocolors26.default.dim(r.url)}`);
         }
       });
     })
@@ -6840,7 +7828,7 @@ function registerSearch(program3) {
 }
 
 // src/commands/board.ts
-var import_picocolors26 = __toESM(require_picocolors(), 1);
+var import_picocolors27 = __toESM(require_picocolors(), 1);
 
 // src/commands/record-step.ts
 async function recordEntityStep(ctx, opts) {
@@ -6879,7 +7867,7 @@ function registerBoard(program3) {
       }
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors26.default.dim("No cards on the Board yet."));
+          line(import_picocolors27.default.dim("No cards on the Board yet."));
           return;
         }
         for (const r of rows) line(formatRow(r));
@@ -6894,7 +7882,7 @@ function registerBoard(program3) {
         `/v1/projects/${projectId}/work-items/${args[0]}`
       );
       ok(row, () => {
-        line(`${import_picocolors26.default.bold(row.title)}  ${import_picocolors26.default.dim(row.id)}`);
+        line(`${import_picocolors27.default.bold(row.title)}  ${import_picocolors27.default.dim(row.id)}`);
         line(`${statusTag(row.status)}  priority ${row.priority}`);
         if (row.ownerHuman) line(`owner: ${row.ownerHuman}`);
         if (row.labels?.length) line(`labels: ${row.labels.join(", ")}`);
@@ -6935,7 +7923,7 @@ ${row.description}`);
         refId: row?.id,
         output: { workItem: row }
       });
-      ok(row, () => line(`Created work item ${import_picocolors26.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Created work item ${import_picocolors27.default.bold(row?.id ?? "")} \u2014 ${title}`));
     })
   );
   board.command("update <id>").description("Change fields on a card \u2014 pass only what changes").option("--title <text>", "new title").option("--description <text>", "new description").option("--status <value>", STATUSES.join(" | ")).option("--priority <value>", PRIORITIES.join(" | ")).option(
@@ -6969,7 +7957,7 @@ ${row.description}`);
         );
       }
       const row = await patchItem(ctx, projectId, String(args[0]), body);
-      ok(row, () => line(`Updated ${import_picocolors26.default.bold(row.id)} \u2014 ${row.title} ${statusTag(row.status)}`));
+      ok(row, () => line(`Updated ${import_picocolors27.default.bold(row.id)} \u2014 ${row.title} ${statusTag(row.status)}`));
     })
   );
   board.command("move <id> <status>").description(
@@ -6980,14 +7968,14 @@ ${row.description}`);
       const status = String(args[1]);
       assertStatus(status);
       const row = await patchItem(ctx, projectId, String(args[0]), { status });
-      ok(row, () => line(`Moved ${import_picocolors26.default.bold(row.title)} \u2192 ${statusTag(row.status)}`));
+      ok(row, () => line(`Moved ${import_picocolors27.default.bold(row.title)} \u2192 ${statusTag(row.status)}`));
     })
   );
   board.command("close <id>").description("Shorthand for `board move <id> done`").action(
     action(async ({ ctx, args }) => {
       const projectId = requireProject(ctx);
       const row = await patchItem(ctx, projectId, String(args[0]), { status: "done" });
-      ok(row, () => line(`Closed ${import_picocolors26.default.bold(row.title)} ${statusTag(row.status)}`));
+      ok(row, () => line(`Closed ${import_picocolors27.default.bold(row.title)} ${statusTag(row.status)}`));
     })
   );
 }
@@ -7020,23 +8008,23 @@ function assertPriority(value) {
   }
 }
 function formatRow(r) {
-  const labels = r.labels?.length ? import_picocolors26.default.dim(` [${r.labels.join(", ")}]`) : "";
-  const owner = r.ownerHuman ? import_picocolors26.default.dim(` @${r.ownerHuman}`) : "";
-  return `${import_picocolors26.default.dim(r.id)}  ${statusTag(r.status)}  ${r.title}${labels}${owner}`;
+  const labels = r.labels?.length ? import_picocolors27.default.dim(` [${r.labels.join(", ")}]`) : "";
+  const owner = r.ownerHuman ? import_picocolors27.default.dim(` @${r.ownerHuman}`) : "";
+  return `${import_picocolors27.default.dim(r.id)}  ${statusTag(r.status)}  ${r.title}${labels}${owner}`;
 }
 function statusTag(status) {
   const label = status.padEnd(11);
-  if (status === "done") return import_picocolors26.default.green(label);
-  if (status === "in-progress") return import_picocolors26.default.yellow(label);
-  if (status === "in-review") return import_picocolors26.default.cyan(label);
-  return import_picocolors26.default.dim(label);
+  if (status === "done") return import_picocolors27.default.green(label);
+  if (status === "in-progress") return import_picocolors27.default.yellow(label);
+  if (status === "in-review") return import_picocolors27.default.cyan(label);
+  return import_picocolors27.default.dim(label);
 }
 function collect2(value, previous) {
   return [...previous, value];
 }
 
 // src/commands/task.ts
-var import_picocolors27 = __toESM(require_picocolors(), 1);
+var import_picocolors28 = __toESM(require_picocolors(), 1);
 var STATUSES2 = ["todo", "working", "checking", "ready", "accepted", "archived"];
 var ROLES = ["pm", "architect", "web", "api", "automation", "qa"];
 var KINDS2 = ["data_reports", "web", "mobile", "service", "automation", "docs"];
@@ -7055,7 +8043,7 @@ function registerTask(program3) {
       }) ?? [];
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors27.default.dim("No tasks on the board yet."));
+          line(import_picocolors28.default.dim("No tasks on the board yet."));
           return;
         }
         for (const r of rows) line(formatRow2(r));
@@ -7096,8 +8084,8 @@ function registerTask(program3) {
         }
       });
       ok(row, () => {
-        line(`${import_picocolors27.default.green("added")} ${import_picocolors27.default.bold(row.title)}  ${import_picocolors27.default.dim(row.key ?? row.id)}`);
-        if (row.role) line(import_picocolors27.default.dim(`role: ${row.role}`));
+        line(`${import_picocolors28.default.green("added")} ${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.key ?? row.id)}`);
+        if (row.role) line(import_picocolors28.default.dim(`role: ${row.role}`));
       });
     })
   );
@@ -7108,7 +8096,7 @@ function registerTask(program3) {
       const rows = row.subtasks ?? [];
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors27.default.dim("No steps yet."));
+          line(import_picocolors28.default.dim("No steps yet."));
           return;
         }
         rows.forEach((r, i) => line(formatSubtask(r, i + 1)));
@@ -7133,7 +8121,7 @@ function registerTask(program3) {
           }
         }
       );
-      ok(row, () => line(`${import_picocolors27.default.green("updated")} ${import_picocolors27.default.bold(row.title)}`));
+      ok(row, () => line(`${import_picocolors28.default.green("updated")} ${import_picocolors28.default.bold(row.title)}`));
     })
   );
   subtask.command("remove <id>").description("Drop a step from the plan (only before the work starts)").action(
@@ -7141,7 +8129,7 @@ function registerTask(program3) {
       await api(ctx, `/v1/project-tasks/${encodeURIComponent(args[0])}`, {
         method: "DELETE"
       });
-      ok({ removed: args[0] }, () => line(import_picocolors27.default.green("removed")));
+      ok({ removed: args[0] }, () => line(import_picocolors28.default.green("removed")));
     })
   );
   task.command("move <id> <status>").description(`Move a task or step along the board (${STATUSES2.join(" | ")})`).action(
@@ -7152,7 +8140,27 @@ function registerTask(program3) {
         `/v1/project-tasks/${encodeURIComponent(args[0])}/move`,
         { body: { status: args[1] } }
       );
-      ok(row, () => line(`${import_picocolors27.default.green("moved")} ${import_picocolors27.default.bold(row.title)} \u2192 ${args[1]}`));
+      ok(row, () => line(`${import_picocolors28.default.green("moved")} ${import_picocolors28.default.bold(row.title)} \u2192 ${args[1]}`));
+    })
+  );
+  subtask.command("send-back <id>").description("Send a finished step back to be done again, with the reason").requiredOption("--note <text>", "what was wrong with it").action(
+    action(async ({ ctx, args, opts }) => {
+      const row = await api(
+        ctx,
+        `/v1/project-subtasks/${encodeURIComponent(String(args[0]))}/reopen`,
+        { method: "POST", body: { note: opts.note } }
+      );
+      ok(row, () => {
+        if (row?.reopened) {
+          line(`${import_picocolors28.default.green("sent back")} \u2014 it will be picked up again`);
+          return;
+        }
+        line(
+          import_picocolors28.default.yellow(
+            row?.reason === "already_open" ? "already waiting to be picked up \u2014 nothing to send back" : row?.reason === "still_working" ? "still working \u2014 let it finish before sending it back" : "could not send that step back"
+          )
+        );
+      });
     })
   );
   task.command("can-start [id]").description("Ask whether work on this task may begin. Refuses until the owner approves.").action(
@@ -7163,7 +8171,7 @@ function registerTask(program3) {
         `/v1/project-tasks/${encodeURIComponent(id)}/dispatch-check`,
         { method: "POST" }
       );
-      ok(row, () => line(import_picocolors27.default.green("approved \u2014 you may start")));
+      ok(row, () => line(import_picocolors28.default.green("approved \u2014 you may start")));
     })
   );
   task.command("approval").description("Ask the owner to approve the plan, or record their decision").argument("<request|approve|decline>").option("--task <id>", "defaults to the task this run is inside").option("--note <text>", "why").action(
@@ -7177,7 +8185,7 @@ function registerTask(program3) {
         );
         ok({ awaiting: row2.approval_state === "awaiting", task: row2 }, () => {
           line(
-            row2.approval_state === "awaiting" ? import_picocolors27.default.yellow("The plan is waiting on the owner. They see it in the task.") : `Already ${row2.approval_state}.`
+            row2.approval_state === "awaiting" ? import_picocolors28.default.yellow("The plan is waiting on the owner. They see it in the task.") : `Already ${row2.approval_state}.`
           );
         });
         return;
@@ -7198,7 +8206,7 @@ function registerTask(program3) {
           }
         }
       );
-      ok(row, () => line(`${import_picocolors27.default.green(row.approval_state)} ${import_picocolors27.default.bold(row.title)}`));
+      ok(row, () => line(`${import_picocolors28.default.green(row.approval_state)} ${import_picocolors28.default.bold(row.title)}`));
     })
   );
   task.command("done [id]").description("Record what a step produced, and move it to ready").option("--summary <text>", "what changed, in the owner's words").action(
@@ -7213,7 +8221,7 @@ function registerTask(program3) {
         `/v1/project-tasks/${encodeURIComponent(id)}/move`,
         { body: { status: "ready" } }
       );
-      ok(row, () => line(`${import_picocolors27.default.green("ready")} ${import_picocolors27.default.bold(row.title)}`));
+      ok(row, () => line(`${import_picocolors28.default.green("ready")} ${import_picocolors28.default.bold(row.title)}`));
     })
   );
 }
@@ -7258,19 +8266,19 @@ function assertOneOf(flag, value, allowed) {
   }
 }
 function formatRow2(r) {
-  const key = import_picocolors27.default.dim((r.key ?? r.id.slice(0, 8)).padEnd(10));
-  const steps = r.subtaskTotal ? import_picocolors27.default.dim(` ${r.subtaskDone}/${r.subtaskTotal}`) : "";
-  const gate = r.approval_state === "awaiting" ? import_picocolors27.default.yellow(" awaiting approval") : "";
+  const key = import_picocolors28.default.dim((r.key ?? r.id.slice(0, 8)).padEnd(10));
+  const steps = r.subtaskTotal ? import_picocolors28.default.dim(` ${r.subtaskDone}/${r.subtaskTotal}`) : "";
+  const gate = r.approval_state === "awaiting" ? import_picocolors28.default.yellow(" awaiting approval") : "";
   return `${key} ${statusTag2(r.status)} ${r.title}${steps}${gate}`;
 }
 function formatSubtask(r, index) {
-  const n = import_picocolors27.default.dim(String(index).padStart(2, "0"));
-  const role = r.role ? import_picocolors27.default.dim(` [${r.role}]`) : "";
-  const scope = r.scope_paths?.length ? import_picocolors27.default.dim(`  owns: ${r.scope_paths.join(", ")}`) : "";
+  const n = import_picocolors28.default.dim(String(index).padStart(2, "0"));
+  const role = r.role ? import_picocolors28.default.dim(` [${r.role}]`) : "";
+  const scope = r.scope_paths?.length ? import_picocolors28.default.dim(`  owns: ${r.scope_paths.join(", ")}`) : "";
   return `${n} ${statusTag2(r.status)} ${r.title}${role}${scope}`;
 }
 function printTask(row) {
-  line(`${import_picocolors27.default.bold(row.title)}  ${import_picocolors27.default.dim(row.key ?? row.id)}`);
+  line(`${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.key ?? row.id)}`);
   line(`${statusTag2(row.status)}  approval: ${row.approval_state}`);
   if (row.summary) line(`
 ${row.summary}`);
@@ -7282,26 +8290,26 @@ touches: ${row.targets.map((t) => t.appName ?? t.ref ?? t.kind).join(", ")}`
   }
   if (row.subtasks?.length) {
     line(`
-${import_picocolors27.default.bold("steps")}`);
+${import_picocolors28.default.bold("steps")}`);
     row.subtasks.forEach((s, i) => line(formatSubtask(s, i + 1)));
   } else {
-    line(import_picocolors27.default.dim("\nNo steps yet."));
+    line(import_picocolors28.default.dim("\nNo steps yet."));
   }
 }
 function statusTag2(status) {
   switch (status) {
     case "ready":
-      return import_picocolors27.default.green("[ready]");
+      return import_picocolors28.default.green("[ready]");
     case "working":
-      return import_picocolors27.default.blue("[working]");
+      return import_picocolors28.default.blue("[working]");
     case "checking":
-      return import_picocolors27.default.cyan("[checking]");
+      return import_picocolors28.default.cyan("[checking]");
     case "accepted":
-      return import_picocolors27.default.green("[accepted]");
+      return import_picocolors28.default.green("[accepted]");
     case "archived":
-      return import_picocolors27.default.dim("[archived]");
+      return import_picocolors28.default.dim("[archived]");
     default:
-      return import_picocolors27.default.dim("[todo]");
+      return import_picocolors28.default.dim("[todo]");
   }
 }
 
@@ -7322,7 +8330,22 @@ var READS = [
   "auth",
   "project",
   "open",
-  "doctor"
+  "doctor",
+  // Both READ and report. `scan` reads files and shells out to npm; `health`
+  // makes a GET request to an address that is already public. Neither can
+  // change anything, which is why the roles that exist to look — qa, security,
+  // sre, analyst — get them without getting anything else.
+  "scan",
+  "health",
+  // Read-only views of what is running. Added with Phase 6a: an SRE that can
+  // read logs but cannot list deployments or read the app's address is being
+  // asked to diagnose an outage with one eye shut.
+  "urls",
+  "deployments",
+  // Reading the plan and what is used against it. An agent proposing "add
+  // another project" can only sensibly propose it if it can find out the plan
+  // allows two and two already exist.
+  "usage"
 ];
 var BUILDS = [
   ...READS,
@@ -7355,6 +8378,12 @@ var ROLE_VERBS = {
   analyst: READS,
   sre: [...READS, "deploy", "domain", "versions"],
   devops: [...BUILDS, "deploy", "domain", "versions"]
+  // NOTE: `deployments` reaches READS above, so every role can LIST and
+  // INSPECT. That is correct — history is a read. The two verbs that change
+  // production (`promote`, `rollback`) are not gated here at all, and must not
+  // be: they are gated in the DAEMON, as `deploy.prod`, which is a door "just
+  // do it" cannot open. A second, verb-name-based rule here would be a weaker
+  // copy of a control that already works.
 };
 var NEVER = {
   // Approving is the owner's, full stop. An agent that can approve the plan it
@@ -7381,7 +8410,7 @@ function assertRoleMayRun(argv) {
 }
 
 // src/commands/decision.ts
-var import_picocolors28 = __toESM(require_picocolors(), 1);
+var import_picocolors29 = __toESM(require_picocolors(), 1);
 function registerDecision(program3) {
   const decision = program3.command("decision").description("Read and record the project's architecture decisions");
   decision.command("list").description("Every decision on record \u2014 read this before changing how something works").option("--limit <n>", "cap the number returned (newest first)").action(
@@ -7394,11 +8423,11 @@ function registerDecision(program3) {
       rows = applyLimit(rows, opts.limit);
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors28.default.dim("No decisions recorded yet."));
+          line(import_picocolors29.default.dim("No decisions recorded yet."));
           return;
         }
         for (const r of rows) {
-          line(`${import_picocolors28.default.dim(r.id)}  ${import_picocolors28.default.dim(shortDate(r.createdAt))}  ${r.title}`);
+          line(`${import_picocolors29.default.dim(r.id)}  ${import_picocolors29.default.dim(shortDate(r.createdAt))}  ${r.title}`);
           line(`    ${truncate(r.decision, 100)}`);
         }
       });
@@ -7412,16 +8441,16 @@ function registerDecision(program3) {
         `/v1/projects/${projectId}/architecture-decisions/${args[0]}`
       );
       ok(row, () => {
-        line(`${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.id)}`);
-        line(import_picocolors28.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
+        line(`${import_picocolors29.default.bold(row.title)}  ${import_picocolors29.default.dim(row.id)}`);
+        line(import_picocolors29.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
         line(`
-${import_picocolors28.default.bold("Context")}
+${import_picocolors29.default.bold("Context")}
 ${row.context}`);
         line(`
-${import_picocolors28.default.bold("Decision")}
+${import_picocolors29.default.bold("Decision")}
 ${row.decision}`);
         if (row.consequences) line(`
-${import_picocolors28.default.bold("Consequences")}
+${import_picocolors29.default.bold("Consequences")}
 ${row.consequences}`);
       });
     })
@@ -7450,7 +8479,7 @@ ${row.consequences}`);
         refId: row?.id,
         output: { decision: row }
       });
-      ok(row, () => line(`Recorded decision ${import_picocolors28.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Recorded decision ${import_picocolors29.default.bold(row?.id ?? "")} \u2014 ${title}`));
     })
   );
   const requirement = program3.command("requirement").description("Read and record the project's requirements");
@@ -7462,11 +8491,11 @@ ${row.consequences}`);
       rows = applyLimit(rows, opts.limit);
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors28.default.dim("No requirements recorded yet."));
+          line(import_picocolors29.default.dim("No requirements recorded yet."));
           return;
         }
         for (const r of rows) {
-          line(`${import_picocolors28.default.dim(r.id)}  ${r.status.padEnd(9)}  ${r.title}`);
+          line(`${import_picocolors29.default.dim(r.id)}  ${r.status.padEnd(9)}  ${r.title}`);
         }
       });
     })
@@ -7479,8 +8508,8 @@ ${row.consequences}`);
         `/v1/projects/${projectId}/requirements/${args[0]}`
       );
       ok(row, () => {
-        line(`${import_picocolors28.default.bold(row.title)}  ${import_picocolors28.default.dim(row.id)}`);
-        line(import_picocolors28.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
+        line(`${import_picocolors29.default.bold(row.title)}  ${import_picocolors29.default.dim(row.id)}`);
+        line(import_picocolors29.default.dim(`${row.status} \xB7 ${shortDate(row.createdAt)}`));
         line(`
 ${row.body}`);
       });
@@ -7506,7 +8535,7 @@ ${row.body}`);
         refId: row?.id,
         output: { requirement: row }
       });
-      ok(row, () => line(`Recorded requirement ${import_picocolors28.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Recorded requirement ${import_picocolors29.default.bold(row?.id ?? "")} \u2014 ${title}`));
     })
   );
   requirement.command("update <id>").description(
@@ -7535,7 +8564,7 @@ ${row.body}`);
           code: "bad_request"
         });
       }
-      ok(row, () => line(`Updated requirement ${import_picocolors28.default.bold(row.id)} \u2014 ${row.title} (${row.status})`));
+      ok(row, () => line(`Updated requirement ${import_picocolors29.default.bold(row.id)} \u2014 ${row.title} (${row.status})`));
     })
   );
 }
@@ -7558,7 +8587,41 @@ function shortDate(iso) {
 }
 
 // src/commands/doc.ts
-var import_picocolors29 = __toESM(require_picocolors(), 1);
+var import_picocolors30 = __toESM(require_picocolors(), 1);
+
+// src/mermaid-fences.ts
+function hasDiagram(code) {
+  if (!code) return false;
+  return code.split("\n").some((line2) => {
+    const text = line2.trim();
+    return !!text && !text.startsWith("%%");
+  });
+}
+function diagramKind(code) {
+  if (!code) return null;
+  for (const line2 of code.split("\n")) {
+    const text = line2.trim();
+    if (!text || text.startsWith("%%")) continue;
+    const match = /^([A-Za-z][A-Za-z-]*)/.exec(text);
+    return match ? match[1] : null;
+  }
+  return null;
+}
+function extractDiagrams(markdown) {
+  if (!markdown) return [];
+  const out = [];
+  const pattern = /^[ \t]*```[ \t]*mermaid[^\n]*\n([\s\S]*?)^[ \t]*```[ \t]*$/gm;
+  let match;
+  while ((match = pattern.exec(markdown)) !== null) {
+    const body = match[1].replace(/\s+$/, "");
+    if (hasDiagram(body)) out.push(body);
+  }
+  return out;
+}
+
+// src/commands/doc.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { isAbsolute, join as join2 } from "path";
 function registerDoc(program3) {
   const doc = program3.command("doc").description("Read and write project documents");
   doc.command("list").description("List the project's documents \u2014 check here before writing a new one").option("--work-item <id>", "the document linked to this card, if there is one").action(
@@ -7569,13 +8632,13 @@ function registerDoc(program3) {
       }) ?? [];
       ok(rows, () => {
         if (!rows.length) {
-          line(import_picocolors29.default.dim("No documents yet."));
+          line(import_picocolors30.default.dim("No documents yet."));
           return;
         }
         for (const r of rows) {
-          const link = r.workItemId ? import_picocolors29.default.dim(` \u21B3 ${r.workItemId}`) : "";
-          const file = r.filePath ? import_picocolors29.default.dim(`  ${r.filePath}`) : "";
-          line(`${import_picocolors29.default.dim(r.id)}  ${r.title}${link}${file}`);
+          const link = r.workItemId ? import_picocolors30.default.dim(` \u21B3 ${r.workItemId}`) : "";
+          const file = r.filePath ? import_picocolors30.default.dim(`  ${r.filePath}`) : "";
+          line(`${import_picocolors30.default.dim(r.id)}  ${r.title}${link}${file}`);
         }
       });
     })
@@ -7589,17 +8652,17 @@ function registerDoc(program3) {
       );
       if (opts.markdown) {
         ok({ id: row.id, title: row.title, filePath: row.filePath }, () => {
-          line(`${import_picocolors29.default.bold(row.title)}  ${import_picocolors29.default.dim(row.id)}`);
+          line(`${import_picocolors30.default.bold(row.title)}  ${import_picocolors30.default.dim(row.id)}`);
           line(
-            row.filePath ? `Read it at ${import_picocolors29.default.bold(row.filePath)} (relative to the project folder).` : import_picocolors29.default.dim("This document has no markdown mirror on disk yet.")
+            row.filePath ? `Read it at ${import_picocolors30.default.bold(row.filePath)} (relative to the project folder).` : import_picocolors30.default.dim("This document has no markdown mirror on disk yet.")
           );
         });
         return;
       }
       ok(row, () => {
-        line(`${import_picocolors29.default.bold(row.title)}  ${import_picocolors29.default.dim(row.id)}`);
-        if (row.workItemId) line(import_picocolors29.default.dim(`linked to work item ${row.workItemId}`));
-        if (row.filePath) line(import_picocolors29.default.dim(`markdown mirror: ${row.filePath}`));
+        line(`${import_picocolors30.default.bold(row.title)}  ${import_picocolors30.default.dim(row.id)}`);
+        if (row.workItemId) line(import_picocolors30.default.dim(`linked to work item ${row.workItemId}`));
+        if (row.filePath) line(import_picocolors30.default.dim(`markdown mirror: ${row.filePath}`));
         line("");
         line(row.contentJson);
       });
@@ -7628,7 +8691,54 @@ function registerDoc(program3) {
         refId: row?.id,
         output: { document: row }
       });
-      ok(row, () => line(`Created document ${import_picocolors29.default.bold(row?.id ?? "")} \u2014 ${title}`));
+      ok(row, () => line(`Created document ${import_picocolors30.default.bold(row?.id ?? "")} \u2014 ${title}`));
+    })
+  );
+  doc.command("diagram <id>").description(
+    "List the diagrams in a document \u2014 `--check` fails when it has none"
+  ).option("--check", "exit non-zero when the document contains no diagram").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const row = await api(
+        ctx,
+        `/v1/projects/${projectId}/documents/${args[0]}`
+      );
+      if (!row) {
+        throw new WorkserError(`No document with id "${args[0]}" on this project.`, {
+          code: "bad_request"
+        });
+      }
+      const markdown = readMirror(ctx.cwd, row.filePath);
+      const diagrams = markdown === null ? [] : extractDiagrams(markdown);
+      const payload = {
+        id: row.id,
+        title: row.title,
+        filePath: row.filePath,
+        diagrams: diagrams.map((code) => ({ kind: diagramKind(code), code }))
+      };
+      ok(payload, () => {
+        line(`${import_picocolors30.default.bold(row.title)}  ${import_picocolors30.default.dim(row.id)}`);
+        if (markdown === null) {
+          line(
+            import_picocolors30.default.dim(
+              row.filePath ? `Could not read ${row.filePath} from this folder.` : "This document has no markdown mirror on disk yet."
+            )
+          );
+        } else if (!diagrams.length) {
+          line(import_picocolors30.default.dim("No diagrams in this document."));
+        } else {
+          for (const [i, code] of diagrams.entries()) {
+            const kind = diagramKind(code) ?? "diagram";
+            line(`${import_picocolors30.default.dim(String(i + 1))}  ${kind}  ${import_picocolors30.default.dim(`${code.split("\n").length} lines`)}`);
+          }
+        }
+      });
+      if (opts.check && !diagrams.length) {
+        throw new WorkserError(
+          markdown === null ? `"${row.title}" has no markdown on disk to check. Save it from the Docs panel, or write it with \`workser doc update ${row.id} --markdown ...\`.` : `"${row.title}" has no diagram. Add one with a \`\`\`mermaid fence describing how the pieces fit together.`,
+          { code: "bad_request" }
+        );
+      }
     })
   );
   doc.command("update <id>").description("Revise an existing document rather than creating a second copy of it").option("--title <text>", "new title").option("--markdown <text>", "replace the body with this markdown").option("--content-json <json>", "replace the body with this rich-text content JSON").action(
@@ -7655,13 +8765,21 @@ function registerDoc(program3) {
           code: "bad_request"
         });
       }
-      ok(row, () => line(`Updated document ${import_picocolors29.default.bold(row.id)} \u2014 ${row.title}`));
+      ok(row, () => line(`Updated document ${import_picocolors30.default.bold(row.id)} \u2014 ${row.title}`));
     })
   );
 }
+function readMirror(cwd, filePath) {
+  if (!filePath) return null;
+  try {
+    return readFileSync2(isAbsolute(filePath) ? filePath : join2(cwd, filePath), "utf8");
+  } catch {
+    return null;
+  }
+}
 
 // src/commands/design.ts
-var import_picocolors30 = __toESM(require_picocolors(), 1);
+var import_picocolors31 = __toESM(require_picocolors(), 1);
 function registerDesign(program3) {
   const design = program3.command("design").description("Read the project's brand (colours, fonts, logo)");
   design.command("show").description("Show this project's brand \u2014 read it before writing any UI").option("--raw", "print the generated token files verbatim instead of a summary").action(
@@ -7675,11 +8793,11 @@ function registerDesign(program3) {
       if (opts.raw) {
         ok(files, () => {
           if (!files.length) {
-            line(import_picocolors30.default.dim("No brand set for this project."));
+            line(import_picocolors31.default.dim("No brand set for this project."));
             return;
           }
           for (const f of files) {
-            line(import_picocolors30.default.bold(f.path));
+            line(import_picocolors31.default.bold(f.path));
             line(f.contents);
             line("");
           }
@@ -7696,21 +8814,21 @@ function registerDesign(program3) {
       } : { hasBrand: false, colors: {}, fonts: {}, brand: {}, files: [] };
       ok(summary, () => {
         if (!tokens) {
-          line(import_picocolors30.default.dim("No brand set for this project \u2014 choose sensible styling yourself."));
+          line(import_picocolors31.default.dim("No brand set for this project \u2014 choose sensible styling yourself."));
           return;
         }
         for (const [name, value] of Object.entries(tokens.brand)) {
-          line(`${import_picocolors30.default.dim(name.padEnd(12))} ${value}`);
+          line(`${import_picocolors31.default.dim(name.padEnd(12))} ${value}`);
         }
         for (const [name, value] of Object.entries(tokens.color)) {
-          line(`${import_picocolors30.default.dim(`color.${name}`.padEnd(12))} ${value}`);
+          line(`${import_picocolors31.default.dim(`color.${name}`.padEnd(12))} ${value}`);
         }
         for (const [name, value] of Object.entries(tokens.font)) {
-          line(`${import_picocolors30.default.dim(`font.${name}`.padEnd(12))} ${value}`);
+          line(`${import_picocolors31.default.dim(`font.${name}`.padEnd(12))} ${value}`);
         }
         line("");
         line(
-          import_picocolors30.default.dim(
+          import_picocolors31.default.dim(
             `Generated into the working tree as ${files.map((f) => f.path).join(", ")} \u2014 wire those in, never edit them.`
           )
         );
@@ -7740,9 +8858,1005 @@ function unwrap(group) {
   );
 }
 
+// src/commands/api.ts
+var import_picocolors32 = __toESM(require_picocolors(), 1);
+import { readdirSync, readFileSync as readFileSync3, statSync as statSync2 } from "fs";
+import { join as join3, relative, sep } from "path";
+
+// src/api-spec.ts
+var SPEC_FILES = [
+  "api/openapi.json",
+  "openapi.json",
+  "api/openapi.yaml",
+  "openapi.yaml",
+  "api/openapi.yml",
+  "openapi.yml"
+];
+function fromNextRoute(file) {
+  const match = /^app\/(.*\/)?route\.(t|j)sx?$/.exec(file);
+  if (!match) return null;
+  const segments = (match[1] ?? "").split("/").filter(Boolean).filter((s) => !(s.startsWith("(") && s.endsWith(")"))).map((s) => {
+    const dynamic = /^\[\.{0,3}(.+?)\]$/.exec(s);
+    return dynamic ? `{${dynamic[1]}}` : s;
+  });
+  return `/${segments.join("/")}`.replace(/\/+$/, "") || "/";
+}
+function fromPythonFile(file) {
+  const match = /^api\/(.+)\.py$/.exec(file);
+  if (!match) return null;
+  const stem = match[1];
+  if (stem === "index") return "/api";
+  if (stem.endsWith("/index")) return `/api/${stem.slice(0, -"/index".length)}`;
+  return `/api/${stem}`;
+}
+function discoverRoutes(files) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const raw of files) {
+    const file = raw.replace(/^\.\//, "");
+    const path = fromNextRoute(file) ?? fromPythonFile(file);
+    if (!path) continue;
+    if (!seen.has(path)) seen.set(path, { path, file });
+  }
+  return [...seen.values()].sort((a, b) => a.path.localeCompare(b.path));
+}
+function specPaths(text) {
+  if (!text) return [];
+  const trimmed = text.trim();
+  if (!trimmed) return [];
+  if (trimmed.startsWith("{")) {
+    try {
+      const parsed = JSON.parse(trimmed);
+      const paths = parsed?.paths;
+      if (!paths || typeof paths !== "object") return [];
+      return Object.keys(paths).filter((k) => k.startsWith("/")).sort();
+    } catch {
+      return [];
+    }
+  }
+  const out = [];
+  let inPaths = false;
+  let indent = 0;
+  for (const line2 of trimmed.split(/\r?\n/)) {
+    if (!line2.trim() || line2.trim().startsWith("#")) continue;
+    const leading = line2.length - line2.trimStart().length;
+    if (!inPaths) {
+      if (/^paths\s*:/.test(line2.trim()) && leading === 0) {
+        inPaths = true;
+        indent = -1;
+      }
+      continue;
+    }
+    if (indent === -1) {
+      if (leading === 0) break;
+      indent = leading;
+    }
+    if (leading < indent) break;
+    if (leading > indent) continue;
+    const key = /^\s*["']?(\/[^"':]*)["']?\s*:/.exec(line2);
+    if (key) out.push(key[1].trim());
+  }
+  return [...new Set(out)].sort();
+}
+var EXEMPT = /* @__PURE__ */ new Set(["/api/health", "/health", "/api", "/"]);
+function specReport(routes, documented) {
+  const declared = new Set(documented);
+  const served = new Set(routes.map((r) => r.path));
+  const missing = routes.filter(
+    (r) => !declared.has(r.path) && !EXEMPT.has(r.path)
+  );
+  const stale = documented.filter((p) => !served.has(p)).sort();
+  return {
+    routes,
+    documented: [...declared].sort(),
+    missing,
+    stale,
+    ok: missing.length === 0
+  };
+}
+function specSummary(report, specFile) {
+  if (!specFile) {
+    return `This service has no API description. Write one at ${SPEC_FILES[0]} listing the routes it serves.`;
+  }
+  if (report.ok) {
+    const n = report.routes.length;
+    return n === 1 ? `The one route this service has is described in ${specFile}.` : `All ${n} routes are described in ${specFile}.`;
+  }
+  const names = report.missing.map((m) => m.path).join(", ");
+  return `${report.missing.length} route${report.missing.length === 1 ? " is" : "s are"} not described in ${specFile}: ${names}`;
+}
+
+// src/commands/api.ts
+function registerApi(program3) {
+  const cmd = program3.command("api").description("Call this service and check it describes its own routes");
+  cmd.command("list").description("The requests saved with this service, in api/requests.json").option("--app <webAppId>", "the service, when this folder holds more than one").action(
+    action(async ({ ctx, opts }) => {
+      const appId = requireApp(opts.app);
+      const res = await api(ctx, `/v1/apps/${encodeURIComponent(appId)}/api/requests`);
+      ok(res, () => {
+        for (const note of res?.notes ?? []) line(import_picocolors32.default.dim(note));
+        for (const r of res?.requests ?? []) {
+          line(
+            `${import_picocolors32.default.dim(r.method.padEnd(6))}${r.path}${r.note ? import_picocolors32.default.dim(`  ${r.note}`) : ""}`
+          );
+        }
+      });
+    })
+  );
+  cmd.command("call <path>").description(
+    `workser api call /orders --method POST --body '{"item":1}' [--env local|preview|production]`
+  ).option("--app <webAppId>", "the service, when this folder holds more than one").option("--method <verb>", "GET by default").option("--body <text>", "request body, already serialised").option(
+    "--header <name:value>",
+    "extra header; repeat for more than one",
+    collectHeader,
+    {}
+  ).option(
+    "--env <name>",
+    "local (default), preview or production \u2014 the host comes from here, never from the path"
+  ).action(
+    action(async ({ ctx, args, opts }) => {
+      const appId = requireApp(opts.app);
+      const res = await api(
+        ctx,
+        `/v1/apps/${encodeURIComponent(appId)}/api/call`,
+        {
+          body: {
+            environment: opts.env,
+            method: opts.method,
+            path: args[0],
+            headers: opts.header,
+            body: opts.body
+          }
+        }
+      );
+      ok(res, () => {
+        if (!res?.ok) {
+          line(import_picocolors32.default.red(res?.error ?? "The service did not answer."));
+          return;
+        }
+        const code = `${res.status}${res.statusText ? ` ${res.statusText}` : ""}`;
+        const colour2 = res.status && res.status < 300 ? import_picocolors32.default.green : res.status && res.status < 500 ? import_picocolors32.default.yellow : import_picocolors32.default.red;
+        line(`${colour2(code)}  ${import_picocolors32.default.dim(`${res.durationMs}ms  ${res.url}`)}`);
+        if (res.body) line(res.body);
+        if (res.truncated) line(import_picocolors32.default.dim("(answer truncated)"));
+      });
+      if (!res?.ok) process.exitCode = 1;
+    })
+  );
+  cmd.command("spec").description(
+    "Compare the routes this repo serves with the ones it documents \u2014 `--check` fails on a gap"
+  ).option("--check", "exit non-zero when a route has no entry in the spec").action(
+    action(async ({ ctx, opts }) => {
+      requireLocalApp(ctx, "api spec");
+      const files = listRepoFiles(ctx.cwd);
+      const routes = discoverRoutes(files);
+      const specFile = SPEC_FILES.find((f) => files.includes(f)) ?? null;
+      const documented = specFile ? specPaths(readIfPresent(join3(ctx.cwd, specFile))) : [];
+      const report = specReport(routes, documented);
+      const summary = specSummary(report, specFile);
+      ok({ ...report, specFile, summary }, () => {
+        for (const r of report.routes) {
+          const known = report.missing.some((m) => m.path === r.path);
+          line(
+            `${known ? import_picocolors32.default.yellow("undocumented") : import_picocolors32.default.green("documented  ")}  ${r.path}${import_picocolors32.default.dim(`  ${r.file}`)}`
+          );
+        }
+        for (const p of report.stale) {
+          line(`${import_picocolors32.default.dim("in spec only ")}  ${p}`);
+        }
+        line("");
+        if (report.ok && specFile) success(summary);
+        else line(import_picocolors32.default.yellow(summary));
+      });
+      if (opts.check && !report.ok) {
+        throw new WorkserError(summary, { code: "bad_request" });
+      }
+      if (opts.check && !specFile) {
+        throw new WorkserError(summary, { code: "bad_request" });
+      }
+    })
+  );
+}
+function collectHeader(raw, previous) {
+  const at = raw.indexOf(":");
+  if (at <= 0) return previous;
+  return { ...previous, [raw.slice(0, at).trim()]: raw.slice(at + 1).trim() };
+}
+function requireApp(app) {
+  const value = typeof app === "string" ? app.trim() : "";
+  if (value) return value;
+  throw new WorkserError(
+    "Which service? Pass --app <webAppId>; `workser app list` shows them.",
+    { code: "bad_request" }
+  );
+}
+function readIfPresent(file) {
+  try {
+    return readFileSync3(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+function listRepoFiles(root, maxDepth = 8) {
+  const SKIP = /* @__PURE__ */ new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    "dist",
+    "build",
+    ".vercel",
+    "__pycache__",
+    ".venv",
+    "venv"
+  ]);
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > maxDepth || out.length > 5e3) return;
+    let entries;
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (name.startsWith(".") && name !== ".well-known") continue;
+      if (SKIP.has(name)) continue;
+      const full = join3(dir, name);
+      let isDir = false;
+      try {
+        isDir = statSync2(full).isDirectory();
+      } catch {
+        continue;
+      }
+      if (isDir) walk(full, depth + 1);
+      else out.push(relative(root, full).split(sep).join("/"));
+    }
+  };
+  walk(root, 0);
+  return out;
+}
+
+// src/commands/analysis.ts
+var import_picocolors33 = __toESM(require_picocolors(), 1);
+import { readFileSync as readFileSync4 } from "fs";
+function registerAnalysis(program3) {
+  const cmd = program3.command("analysis").description("Run Python analysis locally, recorded in the task");
+  cmd.command("runtime").description("Is Python here, and does it have what an analysis needs?").option("--app <webAppId>", "check the interpreter this app would use").action(
+    action(async ({ ctx, opts }) => {
+      const path = opts.app ? `/v1/apps/${encodeURIComponent(String(opts.app))}/analysis/runtime` : "/v1/analysis/runtime";
+      const res = await api(ctx, path);
+      ok(res, () => {
+        line(
+          `${res?.available ? import_picocolors33.default.green("python") : import_picocolors33.default.red("python")}  ${res?.version ?? "not found"}  ${import_picocolors33.default.dim(res?.python ?? "")}`
+        );
+        for (const lib of res?.libraries ?? []) {
+          line(
+            `${lib.present ? import_picocolors33.default.green(lib.name) : import_picocolors33.default.yellow(lib.name)}${import_picocolors33.default.dim(lib.present ? "" : "  missing")}`
+          );
+        }
+        for (const note of res?.notes ?? []) line(import_picocolors33.default.dim(note));
+      });
+      if (!res?.available) process.exitCode = 1;
+    })
+  );
+  cmd.command("run").description(
+    "workser analysis run --app <id> --file report.py   (or --code '<python>')"
+  ).requiredOption("--app <webAppId>", "the app whose folder the script runs in").option("--file <path>", "a Python file to run").option("--code <python>", "the script itself, for something short").option("--timeout <ms>", "how long to allow, capped at 15 minutes").action(
+    action(async ({ ctx, opts }) => {
+      const code = readCode(opts.file, opts.code);
+      const res = await api(
+        ctx,
+        `/v1/apps/${encodeURIComponent(String(opts.app))}/analysis/run`,
+        {
+          body: {
+            code,
+            timeoutMs: opts.timeout ? Number(opts.timeout) : void 0
+          }
+        }
+      );
+      ok(res, () => {
+        if (res?.stdout) line(res.stdout.replace(/\n$/, ""));
+        if (res?.stderr) line(import_picocolors33.default.dim(res.stderr.replace(/\n$/, "")));
+        if (res?.truncated) line(import_picocolors33.default.dim("(output truncated)"));
+        const took = `${Math.round((res?.durationMs ?? 0) / 100) / 10}s`;
+        line(
+          res?.ok ? import_picocolors33.default.green(`\u2713 ${res.summary ?? "It finished."}`) + import_picocolors33.default.dim(`  ${took}`) : import_picocolors33.default.yellow(res?.summary ?? "It did not finish.") + import_picocolors33.default.dim(`  ${took}`)
+        );
+        if (res && !res.sandboxed) {
+          line(
+            import_picocolors33.default.dim(
+              "This platform has no OS sandbox, so the script ran with your own file access."
+            )
+          );
+        }
+      });
+      if (!res?.ok) process.exitCode = 1;
+    })
+  );
+}
+function readCode(file, inline) {
+  if (typeof inline === "string" && inline.trim()) return inline;
+  if (typeof file === "string" && file.trim()) {
+    try {
+      return readFileSync4(file, "utf8");
+    } catch (err) {
+      throw new WorkserError(
+        `Could not read ${file}: ${err instanceof Error ? err.message : String(err)}`,
+        { code: "bad_request" }
+      );
+    }
+  }
+  throw new WorkserError("Pass --file <path> or --code '<python>'.", {
+    code: "bad_request"
+  });
+}
+
+// src/commands/scan.ts
+var import_picocolors34 = __toESM(require_picocolors(), 1);
+import { spawnSync as spawnSync2 } from "child_process";
+import { existsSync as existsSync3, readFileSync as readFileSync5, readdirSync as readdirSync2, statSync as statSync3 } from "fs";
+import { join as join4, relative as relative2, sep as sep2 } from "path";
+
+// src/scan.ts
+var SECRET_PATTERNS = [
+  { name: "a private key", re: /-----BEGIN[A-Z ]*PRIVATE KEY-----/, severity: "high" },
+  { name: "an AWS access key", re: /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/, severity: "high" },
+  { name: "a GitHub token", re: /\bgh[pousr]_[A-Za-z0-9]{36,}\b/, severity: "high" },
+  { name: "a Stripe live key", re: /\b[sr]k_live_[A-Za-z0-9]{16,}\b/, severity: "high" },
+  { name: "an OpenAI key", re: /\bsk-(?:proj-)?[A-Za-z0-9_-]{32,}\b/, severity: "high" },
+  { name: "an Anthropic key", re: /\bsk-ant-[A-Za-z0-9_-]{32,}\b/, severity: "high" },
+  { name: "a Google API key", re: /\bAIza[0-9A-Za-z_-]{35}\b/, severity: "high" },
+  { name: "a Slack token", re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/, severity: "high" },
+  {
+    name: "a database password in a connection string",
+    re: /\b(?:postgres|postgresql|mysql|mongodb(?:\+srv)?|redis|amqp):\/\/[^\s:@/]+:[^\s:@/]+@/,
+    severity: "high"
+  },
+  {
+    // The everyday one: `API_KEY = "…"` with something real on the right.
+    name: "a secret written into the code",
+    re: /(?:secret|password|passwd|api[_-]?key|access[_-]?token|auth[_-]?token|private[_-]?key)\s*[:=]\s*["'`][^"'`\s]{12,}["'`]/i,
+    severity: "high"
+  }
+];
+var PLACEHOLDER = /(?:example|placeholder|changeme|your[_-]?|xxx+|\.\.\.|<[^>]+>|\$\{|process\.env|os\.environ|REPLACE|dummy|sample|test[_-]?key|fake)/i;
+var SECRET_EXEMPT = /(?:\.example$|\.sample$|\.template$|(?:^|\/)(?:fixtures?|__fixtures__|__tests__|test|tests|spec|mocks?)\/|\.(?:test|spec)\.[jt]sx?$|(?:^|\/)(?:package-lock\.json|yarn\.lock|pnpm-lock\.yaml)$|(?:^|\/)workser-scan\.md$)/;
+function addedLines(diff) {
+  const out = [];
+  let file = null;
+  let lineNo = 0;
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      const path = raw.slice(4).trim();
+      file = path === "/dev/null" ? null : path.replace(/^b\//, "");
+      continue;
+    }
+    if (raw.startsWith("--- ") || raw.startsWith("diff --git")) continue;
+    const hunk = raw.match(/^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/);
+    if (hunk) {
+      lineNo = Number(hunk[1]);
+      continue;
+    }
+    if (!file) continue;
+    if (raw.startsWith("+")) {
+      out.push({ file, line: lineNo, text: raw.slice(1) });
+      lineNo++;
+      continue;
+    }
+    if (raw.startsWith(" ")) lineNo++;
+  }
+  return out;
+}
+function secretFindings(diff) {
+  const findings = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const added of addedLines(diff)) {
+    if (SECRET_EXEMPT.test(added.file)) continue;
+    for (const pattern of SECRET_PATTERNS) {
+      if (!pattern.re.test(added.text)) continue;
+      if (PLACEHOLDER.test(added.text)) continue;
+      const key = `${added.file}:${pattern.name}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      findings.push({
+        check: "secrets",
+        severity: pattern.severity,
+        title: `This change adds ${pattern.name} to the code`,
+        file: added.file,
+        line: added.line,
+        fix: "Move the value into an environment setting (`workser env set`) and use it from there. If it has already been committed, treat it as leaked and replace it at the source."
+      });
+      break;
+    }
+  }
+  return findings;
+}
+function depFindings(auditJson) {
+  if (!auditJson) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(auditJson);
+  } catch {
+    return [];
+  }
+  const vulns = parsed?.vulnerabilities;
+  if (!vulns || typeof vulns !== "object") return [];
+  const findings = [];
+  for (const [name, raw] of Object.entries(vulns)) {
+    const severity = String(raw?.severity ?? "").toLowerCase();
+    if (severity !== "high" && severity !== "critical") continue;
+    const direct = raw?.isDirect === true;
+    const fixable = raw?.fixAvailable;
+    findings.push({
+      check: "deps",
+      severity: "high",
+      title: `${name} has a known ${severity} security problem`,
+      fix: fixable === true ? `Run \`npm audit fix\`${direct ? "" : " \u2014 it is pulled in by another package"}.` : typeof fixable === "object" && fixable?.name ? `Fixing it means moving to ${fixable.name}@${fixable.version}, which is a breaking change. Decide it deliberately.` : "There is no published fix yet. Decide whether this package is worth keeping."
+    });
+  }
+  return findings.sort((a, b) => a.title.localeCompare(b.title));
+}
+function permissionFindings(files, trackedFiles = []) {
+  const findings = [];
+  for (const file of files) {
+    for (const match of file.content.matchAll(
+      /NEXT_PUBLIC_[A-Z0-9_]*(?:SECRET|PASSWORD|TOKEN|API_KEY|PRIVATE)[A-Z0-9_]*/g
+    )) {
+      findings.push({
+        check: "permissions",
+        severity: "high",
+        title: `${match[0]} is sent to every visitor's browser`,
+        file: file.path,
+        fix: "Anything named NEXT_PUBLIC_ is public by design. Rename it without that prefix and read it on the server only."
+      });
+    }
+    if (/["']Access-Control-Allow-Origin["']\s*[:,]\s*["']\*["']/.test(file.content) && /Access-Control-Allow-Credentials/.test(file.content)) {
+      findings.push({
+        check: "permissions",
+        severity: "high",
+        title: "This service accepts credentialed requests from any website",
+        file: file.path,
+        fix: "Name the sites allowed to call it instead of `*`, or stop sending credentials."
+      });
+    }
+  }
+  for (const tracked of trackedFiles) {
+    const base = tracked.split("/").pop() ?? tracked;
+    if (!/^\.env(\.[a-z0-9-]+)?$/i.test(base)) continue;
+    if (/\.(example|sample|template)$/i.test(base)) continue;
+    findings.push({
+      check: "permissions",
+      severity: "high",
+      title: `${tracked} is committed to the repository`,
+      file: tracked,
+      fix: "Add it to .gitignore, remove it from the repo, and treat every value in it as leaked."
+    });
+  }
+  return findings;
+}
+function buildReport(input) {
+  const counts = { high: 0, medium: 0, low: 0 };
+  for (const f of input.findings) counts[f.severity]++;
+  return {
+    findings: [...input.findings].sort(
+      (a, b) => rank(b.severity) - rank(a.severity) || a.title.localeCompare(b.title)
+    ),
+    checked: input.checked,
+    skipped: input.skipped,
+    counts,
+    ok: counts.high === 0
+  };
+}
+function rank(s) {
+  return s === "high" ? 3 : s === "medium" ? 2 : 1;
+}
+function scanSummary(report) {
+  const ran = report.checked.length;
+  if (!ran) return "Nothing could be checked \u2014 see the reasons above.";
+  const what = report.checked.join(", ");
+  const total = report.findings.length;
+  if (!total) {
+    return `Checked ${what} \u2014 nothing found.`;
+  }
+  const high = report.counts.high;
+  return `Checked ${what} \u2014 ${total} ${total === 1 ? "thing" : "things"} to look at` + (high ? `, ${high} of them serious.` : ".");
+}
+
+// src/commands/scan.ts
+function registerScan(program3) {
+  program3.command("scan").description("Check this folder for known-bad dependencies, leaked secrets and over-broad permissions").option("--check", "exit non-zero if anything serious is found", false).option(
+    "--only <checks>",
+    "comma-separated subset: deps, secrets, permissions"
+  ).option(
+    "--staged",
+    "look at staged changes only, rather than everything not yet committed",
+    false
+  ).action(
+    action(async ({ ctx, opts }) => {
+      const only = parseOnly(opts.only);
+      const findings = [];
+      const checked = [];
+      const skipped = [];
+      if (only.has("secrets")) runSecrets(ctx.cwd, !!opts.staged, findings, checked, skipped);
+      if (only.has("deps")) runDeps(ctx.cwd, findings, checked, skipped);
+      if (only.has("permissions")) runPermissions(ctx.cwd, findings, checked, skipped);
+      const report = buildReport({ findings, checked, skipped });
+      const summary = scanSummary(report);
+      ok({ ...report, summary }, () => print2(report, summary));
+      if (opts.check && !report.ok) {
+        throw new WorkserError(summary, { code: "bad_request" });
+      }
+    })
+  );
+}
+function parseOnly(raw) {
+  const all = ["deps", "secrets", "permissions"];
+  if (typeof raw !== "string" || !raw.trim()) return new Set(all);
+  const wanted = raw.split(",").map((s) => s.trim().toLowerCase()).filter((s) => all.includes(s));
+  if (!wanted.length) {
+    throw new WorkserError(
+      `--only takes any of: ${all.join(", ")}.`,
+      { code: "bad_request" }
+    );
+  }
+  return new Set(wanted);
+}
+function runSecrets(cwd, staged, findings, checked, skipped) {
+  const args = staged ? ["diff", "--cached", "--unified=0"] : (
+    // Against HEAD, so it covers both staged and unstaged work: the agent
+    // that just wrote the key has not staged anything.
+    ["diff", "HEAD", "--unified=0"]
+  );
+  const diff = git(cwd, args);
+  if (diff === null) {
+    skipped.push({
+      check: "secrets",
+      reason: "This folder isn\u2019t a git repository yet, so there are no changes to look through."
+    });
+    return;
+  }
+  checked.push("secrets");
+  findings.push(...secretFindings(diff));
+}
+function runDeps(cwd, findings, checked, skipped) {
+  const hasLock = ["package-lock.json", "npm-shrinkwrap.json"].some(
+    (f) => existsSync3(join4(cwd, f))
+  );
+  if (!hasLock) {
+    skipped.push({
+      check: "deps",
+      reason: existsSync3(join4(cwd, "package.json")) ? "There\u2019s no package-lock.json, so the exact versions in use aren\u2019t known. Run `npm install` once." : "This folder has no npm packages to check."
+    });
+    return;
+  }
+  const res = spawnSync2("npm", ["audit", "--json", "--audit-level=high"], {
+    cwd,
+    encoding: "utf8",
+    timeout: 6e4,
+    stdio: ["ignore", "pipe", "pipe"]
+    // `npm audit` exits 1 when it FINDS something, which is a successful run.
+    // The failures that matter are the ones with no JSON on stdout.
+  });
+  const out = (res.stdout || "").trim();
+  if (!out || res.error) {
+    skipped.push({
+      check: "deps",
+      reason: "Couldn\u2019t reach the package registry, so known problems in your dependencies weren\u2019t checked. This needs an internet connection."
+    });
+    return;
+  }
+  checked.push("deps");
+  findings.push(...depFindings(out));
+}
+function runPermissions(cwd, findings, checked, skipped) {
+  const paths = listRepoFiles2(cwd).filter(isReadable);
+  const files = [];
+  for (const path of paths.slice(0, 1500)) {
+    try {
+      const content = readFileSync5(join4(cwd, path), "utf8");
+      if (content.length > 4e5) continue;
+      files.push({ path, content });
+    } catch {
+    }
+  }
+  const tracked = git(cwd, ["ls-files"]);
+  checked.push("permissions");
+  findings.push(
+    ...permissionFindings(
+      files,
+      tracked === null ? [] : tracked.split("\n").filter(Boolean)
+    )
+  );
+  if (tracked === null) {
+    skipped.push({
+      check: "permissions",
+      reason: "Not a git repository, so we couldn\u2019t check whether a .env file has been committed."
+    });
+  }
+}
+function print2(report, summary) {
+  for (const s of report.skipped) {
+    line(`${import_picocolors34.default.yellow("not checked")}  ${s.check}${import_picocolors34.default.dim(` \u2014 ${s.reason}`)}`);
+  }
+  for (const f of report.findings) {
+    const where = f.file ? import_picocolors34.default.dim(`  ${f.file}${f.line ? `:${f.line}` : ""}`) : "";
+    line(`${severityTag(f.severity)}  ${f.title}${where}`);
+    line(`             ${import_picocolors34.default.dim(f.fix)}`);
+  }
+  if (report.findings.length || report.skipped.length) line("");
+  if (report.ok && !report.skipped.length) success(summary);
+  else if (report.ok) line(import_picocolors34.default.yellow(summary));
+  else line(import_picocolors34.default.red(summary));
+}
+function severityTag(severity) {
+  if (severity === "high") return import_picocolors34.default.red("serious    ");
+  if (severity === "medium") return import_picocolors34.default.yellow("worth fixing");
+  return import_picocolors34.default.dim("minor      ");
+}
+function git(cwd, args) {
+  try {
+    const res = spawnSync2("git", args, {
+      cwd,
+      encoding: "utf8",
+      timeout: 2e4,
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    if (res.error || res.status !== 0) return null;
+    return res.stdout || "";
+  } catch {
+    return null;
+  }
+}
+var READABLE = /\.(?:[jt]sx?|mjs|cjs|json|ya?ml|toml|env|py|rb|go|rs|java|php|sh|sql|md|txt|html|css)$/i;
+function isReadable(path) {
+  return READABLE.test(path);
+}
+function listRepoFiles2(root, maxDepth = 8) {
+  const SKIP = /* @__PURE__ */ new Set([
+    "node_modules",
+    ".git",
+    ".next",
+    "dist",
+    "build",
+    ".vercel",
+    "__pycache__",
+    ".venv",
+    "venv"
+  ]);
+  const out = [];
+  const walk = (dir, depth) => {
+    if (depth > maxDepth || out.length > 5e3) return;
+    let entries;
+    try {
+      entries = readdirSync2(dir);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (SKIP.has(name)) continue;
+      if (name.startsWith(".") && !name.startsWith(".env")) continue;
+      const full = join4(dir, name);
+      let isDir = false;
+      try {
+        isDir = statSync3(full).isDirectory();
+      } catch {
+        continue;
+      }
+      if (isDir) walk(full, depth + 1);
+      else out.push(relative2(root, full).split(sep2).join("/"));
+    }
+  };
+  walk(root, 0);
+  return out;
+}
+
+// src/commands/health.ts
+var import_picocolors35 = __toESM(require_picocolors(), 1);
+function registerHealth(program3) {
+  program3.command("health").description("Check that the published apps in this project are still answering").option("--app <webAppId>", "check one app rather than all of them").action(
+    action(async ({ ctx, opts }) => {
+      requireDaemon(ctx, "health", "checks your published sites from this computer");
+      const path = opts.app ? `/v1/apps/${encodeURIComponent(String(opts.app))}/health` : `/v1/health`;
+      const res = await api(ctx, path);
+      ok(res, () => print3(res));
+      if (res?.checks?.some((c) => !c.ok)) process.exitCode = 1;
+    })
+  );
+}
+function print3(res) {
+  if (!res?.checks?.length) {
+    line(import_picocolors35.default.dim(res?.note ?? "Nothing to check."));
+    return;
+  }
+  for (const c of res.checks) {
+    const mark = c.ok ? import_picocolors35.default.green("up  ") : import_picocolors35.default.red("down");
+    const timing = import_picocolors35.default.dim(`${c.ms}ms`);
+    const detail = c.ok ? timing : import_picocolors35.default.dim(`${c.error ?? "no answer"}${c.failures > 1 ? ` \xB7 ${c.failures} in a row` : ""}`);
+    line(`  ${mark}  ${c.appName} ${import_picocolors35.default.dim(`(${c.environment})`)}  ${c.url}  ${detail}`);
+    if (c.incidentOpened) {
+      line(import_picocolors35.default.yellow(`        An incident has been opened on the board for this.`));
+    }
+  }
+  const down = res.checks.filter((c) => !c.ok);
+  line("");
+  if (!down.length) {
+    success(
+      `Everything published is answering (${res.checks.length} ${res.checks.length === 1 ? "address" : "addresses"} checked).`
+    );
+    return;
+  }
+  const production = down.filter((c) => c.environment === "production").length;
+  line(
+    import_picocolors35.default.red(
+      `${down.length} of ${res.checks.length} not answering` + (production ? ` \u2014 ${production} customer-facing.` : " (preview only).")
+    )
+  );
+}
+
+// src/commands/urls.ts
+var import_picocolors36 = __toESM(require_picocolors(), 1);
+function registerUrls(program3) {
+  program3.command("urls").description("The stable preview and production addresses of every app in this project").option("--app <webAppId>", "just one app").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      const apps = await api(ctx, `/v1/apps`, {
+        query: { project: projectId }
+      });
+      const list = Array.isArray(apps) ? apps : apps?.apps ?? [];
+      const wanted = opts.app ? list.filter((a) => a.id === String(opts.app)) : list;
+      const rows = urlRows(wanted);
+      const summary = urlsSummary(rows);
+      ok({ rows, summary }, () => {
+        for (const row of rows) {
+          const label = import_picocolors36.default.dim(row.environment.padEnd(10));
+          const value = row.url ? import_picocolors36.default.cyan(row.url) : import_picocolors36.default.dim(row.note ?? "not published");
+          line(`  ${row.appName.padEnd(22)} ${label} ${value}`);
+        }
+        line("");
+        if (rows.some((r) => r.url)) success(summary);
+        else line(import_picocolors36.default.yellow(summary));
+      });
+    })
+  );
+}
+
+// src/commands/deployments.ts
+var import_picocolors37 = __toESM(require_picocolors(), 1);
+function registerDeployments(program3) {
+  const cmd = program3.command("deployments").description("Deployment history, and putting a build in front of customers");
+  cmd.command("list").description("What has been built, newest first").option("--app <webAppId>", "just one app (default: every app in the project)").option("--env <environment>", "preview or production").option("--limit <n>", "how many to show", "20").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      const environment = readEnv2(opts.env, "deployments list");
+      const res = await api(ctx, `/v1/projects/${projectId}/deployments`, {
+        query: {
+          ...opts.app ? { webAppId: String(opts.app) } : {},
+          ...environment ? { environment } : {},
+          limit: String(opts.limit ?? "20")
+        }
+      });
+      const items = res?.deployments ?? [];
+      ok(res, () => {
+        if (!items.length) {
+          return line(
+            import_picocolors37.default.dim(
+              environment ? `Nothing has been deployed to ${environment} yet.` : "Nothing has been deployed yet. `workser deploy` builds the first one."
+            )
+          );
+        }
+        for (const d of items) line(formatDeployment(d));
+      });
+    })
+  );
+  cmd.command("inspect <id>").description("One deployment in full, with its build log").option("--logs", "include the build output", false).action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const id = String(args[0]);
+      const dep = await api(ctx, `/v1/deployments/${encodeURIComponent(id)}`);
+      const logs = opts.logs ? await api(
+        ctx,
+        `/v1/projects/${projectId}/deployments/${encodeURIComponent(id)}/logs`
+      ).catch(() => null) : null;
+      ok({ ...dep, logs }, () => {
+        line(formatDeployment(dep));
+        if (dep?.error_message) line(import_picocolors37.default.red(`  ${dep.error_message}`));
+        const events = logs?.events ?? [];
+        for (const e of events) {
+          line(`  ${import_picocolors37.default.dim(String(e.type ?? "log"))}  ${e.text ?? ""}`);
+        }
+        if (opts.logs && !events.length) {
+          line(import_picocolors37.default.dim("  That build produced no output."));
+        }
+      });
+    })
+  );
+  cmd.command("promote").description("Put the latest ready build in front of customers (asks you first)").option("--app <webAppId>", "which app (defaults to the primary app)").action(
+    action(async ({ ctx, opts }) => {
+      const projectId = requireProject(ctx);
+      const res = await api(ctx, `/v1/projects/${projectId}/deployments/promote`, {
+        body: { ...opts.app ? { webAppId: String(opts.app) } : {} }
+      });
+      ok(res, () => printPromoted(res, null));
+    })
+  );
+  cmd.command("rollback <version>").description("Put an earlier version back in front of customers (asks you first)").option("--app <webAppId>", "which app (defaults to the primary app)").action(
+    action(async ({ ctx, args, opts }) => {
+      const projectId = requireProject(ctx);
+      const version = Number(args[0]);
+      if (!Number.isInteger(version) || version < 1) {
+        throw new WorkserError(
+          `"${args[0]}" is not a version number. \`workser deployments list\` shows them.`,
+          { code: "bad_input" }
+        );
+      }
+      const res = await api(ctx, `/v1/projects/${projectId}/deployments/promote`, {
+        body: {
+          version,
+          ...opts.app ? { webAppId: String(opts.app) } : {}
+        }
+      });
+      ok(res, () => printPromoted(res, version));
+    })
+  );
+}
+function readEnv2(raw, verb) {
+  const parsed = parseDeployEnvironment(raw, verb);
+  if (!parsed.ok) throw new WorkserError(parsed.error, { code: "bad_input" });
+  return parsed.value;
+}
+function printPromoted(res, version) {
+  if (!res) return;
+  const what = version === null ? "the latest build" : `version ${version}`;
+  const url = res.url ?? res.vercel_url;
+  success(`Production is being rebuilt from ${what}.`);
+  if (url) line(import_picocolors37.default.dim(`It will be at ${url}`));
+  line(import_picocolors37.default.dim("`workser deploy status` follows it."));
+}
+function formatDeployment(d) {
+  if (!d) return "";
+  const version = d.version !== void 0 ? import_picocolors37.default.yellow(`v${d.version}`) : import_picocolors37.default.dim("v?");
+  const env = import_picocolors37.default.dim((d.environment ?? "?").padEnd(10));
+  const app = d.webAppName ? `${d.webAppName}  ` : "";
+  const when = import_picocolors37.default.dim(formatTime2(d.created_at));
+  const url = d.url ? "  " + import_picocolors37.default.cyan(d.url) : "";
+  return `${version}  ${env} ${colorStatus(d.status ?? "")}  ${app}${when}${url}`;
+}
+function formatTime2(t) {
+  if (!t) return "\u2014";
+  const d = new Date(t);
+  return Number.isNaN(d.getTime()) ? String(t) : d.toISOString().replace("T", " ").replace(/\.\d+Z$/, "Z");
+}
+
+// src/commands/usage.ts
+var import_picocolors38 = __toESM(require_picocolors(), 1);
+
+// src/usage.ts
+var NEAR_LIMIT_FRACTION = 0.8;
+function isUnlimited(limit) {
+  return limit === null || limit === void 0 || !Number.isFinite(limit) || limit >= Number.MAX_SAFE_INTEGER;
+}
+function fractionUsed(d) {
+  if (d.used === null) return null;
+  if (isUnlimited(d.limit)) return null;
+  const limit = d.limit;
+  if (limit <= 0) return d.used > 0 ? 1 : 0;
+  return d.used / limit;
+}
+function usageState(d) {
+  if (d.used === null) return "unknown";
+  const fraction = fractionUsed(d);
+  if (fraction === null) return "fine";
+  if (fraction >= 1) return "over";
+  if (fraction >= NEAR_LIMIT_FRACTION) return "near";
+  return "fine";
+}
+function formatAmount(value, unit) {
+  if (unit === "count") return String(Math.round(value));
+  if (Number.isInteger(value)) return `${value} GB`;
+  if (value < 0.01) return "<0.01 GB";
+  if (value < 10) return `${value.toFixed(2)} GB`;
+  return `${value.toFixed(1)} GB`;
+}
+function bar(d, width = 20) {
+  const fraction = fractionUsed(d);
+  if (fraction === null) return "";
+  const filled = Math.min(width, Math.round(fraction * width));
+  return "\u2588".repeat(filled) + "\u2591".repeat(width - filled);
+}
+function dimensionLine(d) {
+  if (d.used === null) {
+    return `${d.label}: not measured${d.note ? ` \u2014 ${d.note}` : ""}`;
+  }
+  const used = formatAmount(d.used, d.unit);
+  if (isUnlimited(d.limit)) return `${d.label}: ${used} (no limit on this plan)`;
+  const limit = formatAmount(d.limit, d.unit);
+  if (usageState(d) === "over") {
+    return d.kind === "hard" ? `${d.label}: ${used} of ${limit} \u2014 at the limit` : `${d.label}: ${used} of ${limit} included \u2014 the rest is billed as extra`;
+  }
+  return `${d.label}: ${used} of ${limit}`;
+}
+function usageSummary(report) {
+  const dims = report.dimensions ?? [];
+  const unknown = dims.filter((d) => d.used === null);
+  const over = dims.filter((d) => usageState(d) === "over");
+  const near = dims.filter((d) => usageState(d) === "near");
+  const parts = [];
+  if (over.length) {
+    parts.push(
+      `${over.length === 1 ? "One thing is" : `${over.length} things are`} over the ${report.tier} plan's limit`
+    );
+  } else if (near.length) {
+    parts.push(
+      `${near.length === 1 ? "One thing is" : `${near.length} things are`} close to the ${report.tier} plan's limit`
+    );
+  } else if (dims.some((d) => d.used !== null)) {
+    parts.push(`Everything is comfortably inside the ${report.tier} plan`);
+  }
+  if (unknown.length) {
+    parts.push(
+      `${unknown.length} ${unknown.length === 1 ? "figure" : "figures"} could not be read`
+    );
+  }
+  if (!parts.length) return "Nothing could be measured.";
+  return `${parts.join("; ")}.`;
+}
+function shouldFail(report) {
+  return (report.dimensions ?? []).some(
+    (d) => d.kind === "hard" && usageState(d) === "over"
+  );
+}
+
+// src/commands/usage.ts
+function registerUsage(program3) {
+  program3.command("usage").description("What this project and your plan are using \u2014 storage, projects, apps").action(
+    action(async ({ ctx }) => {
+      const projectId = requireProject(ctx);
+      const report = await api(
+        ctx,
+        `/v1/projects/${projectId}/usage`
+      );
+      ok(report, () => print4(report));
+      if (shouldFail(report)) process.exitCode = 1;
+    })
+  );
+}
+function print4(report) {
+  const dims = report.dimensions ?? [];
+  if (!dims.length) {
+    return line(import_picocolors38.default.dim("Nothing to measure for this project yet."));
+  }
+  const width = Math.max(...dims.map((d) => d.label.length));
+  for (const d of dims) {
+    line(`  ${colour(d)(dimensionLine(d).padEnd(0))}${gauge(d, width)}`);
+  }
+  line("");
+  const summary = usageSummary(report);
+  const worst = dims.map(usageState);
+  if (worst.includes("over")) line(import_picocolors38.default.red(summary));
+  else if (worst.includes("near") || worst.includes("unknown"))
+    line(import_picocolors38.default.yellow(summary));
+  else success(summary);
+}
+function gauge(d, _labelWidth) {
+  const drawn = bar(d);
+  return drawn ? `  ${import_picocolors38.default.dim(drawn)}` : "";
+}
+function colour(d) {
+  switch (usageState(d)) {
+    case "over":
+      return d.kind === "hard" ? import_picocolors38.default.red : import_picocolors38.default.yellow;
+    case "near":
+      return import_picocolors38.default.yellow;
+    case "unknown":
+      return import_picocolors38.default.dim;
+    default:
+      return (s) => s;
+  }
+}
+
 // src/index.ts
 var pkg = {
-  version: true ? "0.3.1" : "0.0.0-dev"
+  version: true ? "0.6.0" : "0.0.0-dev"
 };
 var program2 = new Command();
 program2.name("workser").description(
@@ -7775,6 +9889,13 @@ registerOpen(program2);
 registerDoctor(program2);
 registerAgent(program2);
 registerVerify(program2);
+registerApi(program2);
+registerAnalysis(program2);
+registerScan(program2);
+registerHealth(program2);
+registerUrls(program2);
+registerDeployments(program2);
+registerUsage(program2);
 registerCheckpoint(program2);
 registerSync(program2);
 registerWorkflow(program2);