@workser/cli 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workser/cli",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Workser CLI — give your local AI agent native DevOps & infrastructure on Workser. The agent runs `workser …` to provision, deploy, and manage real apps.",
   "license": "MIT",
   "type": "module",
@@ -29,8 +29,9 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "npm run build:help && tsup",
+    "build:help": "node scripts/build-help.mjs",
+    "dev": "npm run build:help && tsup --watch",
     "typecheck": "tsc --noEmit",
     "lint": "eslint \"src/**/*.ts\"",
     "format": "prettier --write \"src/**/*.ts\"",

package/skills/workser/SKILL.md

@@ -11,7 +11,48 @@ Neon Postgres database, deploy it, manage its env vars and bucket, provision aut
 and read its logs — **on the user's own account**, through the Workser Orbit app
 (which handles auth and shows the user what you're doing).
 
+For writing code, keep using your normal tools. Use `workser` for the last mile.
+
+## Read one guide, not all of them
+
+This page is the index. The detail lives in the CLI itself — `workser help <topic>`
+prints one focused guide, about a screen long. Find your row, run that **one**
+command. Don't print them all; you are paying for every line you load.
+
+| You need to… | Commands | Run |
+| --- | --- | --- |
+| Provision or query Postgres; list end users | `db …`, `auth …` | `workser help database` |
+| Deploy, set env vars, read logs, check a domain | `deploy`, `env …`, `logs`, `versions`, `domain`, `open` | `workser help deploy` |
+| Put files in the project's bucket | `storage …` | `workser help storage` |
+| Read or write products, orders, customers, deals | `business …` | `workser help business` |
+| Use the project's own Neon buckets or functions | `neon …` | `workser help neon` |
+| Build an automation, or use Gmail/Slack/Stripe/Sheets | `workflow …`, `app …` | `workser help automation` |
+| Generate an image | `image …` | `workser help images` |
+| Hand a subtask to another agent | `agent …` | `workser help roles` |
+| Remember or recall something across conversations | `memory …` | `workser help memory` |
+| Record finished output, or ask the user a question | `artifact …`, `ask` | `workser help deliverables` |
+| Control this machine — files, shell, screen, browser | `tool …` | `workser help computer-use` |
+
+`workser help` with no topic lists them. **The CLI is the source of truth**: it ships
+these guides with itself, so they match the version you are running. For exact flags
+on any command, `workser <command> --help` is generated from the implementation and
+cannot be out of date.
+
+## Orientation (no guide needed)
+
+```
+workser status                # connection + pinned project + latest deploy
+workser whoami                # who am I / which workspace
+workser project show          # the project pinned to this directory
+workser project list          # the workspace's projects (read)
+workser verify                # run typecheck/lint/build — gate "done" on this
+workser doctor                # resolved endpoint, mode, token presence, project
+workser login                 # authenticate outside Orbit (CI/standalone)
+workser logout                # clear a saved standalone session
+```
+
 ## Scope (read this)
+
 You operate on **one project's own infrastructure**. You *can* provision and use it:
 create the Neon database, read its connection string, browse its tables / rows / run
 SQL, provision the bucket + auth, deploy, set env vars, manage files. Sensitive
@@ -24,25 +65,18 @@ Those return `error.code = "owner_only"` (exit 6) — tell the user it's an owne
 action to do in Orbit, then continue with what you can do. The project is already
 selected; you don't pick or switch it.
 
-## When to use this
-Reach for `workser` whenever the task involves **running** the current app, not just writing it:
-- "deploy this", "put it online", "give me a URL"
-- "set an API key / env var", "what's the database URL?"
-- "upload this file", "list what's in storage"
-- "is it deployed?", "show logs", "why is it down?"
-
-For writing code, keep using your normal tools. Use `workser` for the last mile.
+Owner-only, for reference: `project create` · `project use` · `env rm` · `domain set`.
 
 ## Golden rules
+
 1. **Always pass `--json`.** Output is then a single stable line:
    `{"ok":true,"data":...}` or `{"ok":false,"error":{"code","message",...}}`. Parse it.
 2. **Orient first.** Run `workser status --json` to see the connection, the pinned
    project, and the latest deploy before acting. You don't pick or switch projects.
-3. **Stay in your lane.** `error.code = "owner_only"` (exit 6) means the action
-   (creating/switching projects, deleting env vars, attaching domains) is reserved
-   for the owner in Orbit. Don't retry or look for a workaround — tell the user, then
-   continue. Provisioning the *pinned project's own* db / bucket / auth is allowed
-   (it may be approval-gated, not owner-only).
+3. **Stay in your lane.** `error.code = "owner_only"` (exit 6) means the action is
+   reserved for the owner in Orbit. Don't retry or look for a workaround — tell the
+   user, then continue. Provisioning the *pinned project's own* db / bucket / auth is
+   allowed (it may be approval-gated, not owner-only).
 4. **Approvals are normal.** Some allowed actions may return
    `{"error":{"code":"awaiting_approval"}}` (exit 5) while the user approves in the
    Orbit UI. Tell the user to approve, then retry — do **not** try to bypass it.
@@ -55,158 +89,8 @@ For writing code, keep using your normal tools. Use `workser` for the last mile.
    `git reset --hard`, `DROP`/`TRUNCATE`, `curl | sh`, …) are refused by Workser's
    safety policy — don't attempt them; use migrations + scoped changes instead.
 
-## Command reference
-```
-workser status                      # connection + pinned project + latest deploy
-workser whoami                      # who am I / which workspace
-workser project show                # the project pinned to this directory
-workser project list                # the workspace's projects (read)
-
-workser db create                   # provision the Neon Postgres database (idempotent)
-workser db url                      # connection string (sensitive; least-privilege role)
-workser db list                     # database status
-workser db tables                   # list tables in the database
-workser db schema <table>           # a table's columns
-workser db data <table> [-n N] [--offset N]   # read rows
-workser db query "<sql>"            # run SQL (writes are approval-gated)
-workser auth enable                 # provision auth for the project (idempotent)
-workser auth status                 # is auth enabled? + Neon auth mode
-
-workser env set KEY=VALUE [K2=V2…]  # set env vars
-workser env list                    # list keys (values masked)
-workser env get KEY                 # one value (sensitive)
-
-workser storage create [name]       # provision the bucket (idempotent)
-workser storage list                # the project's bucket
-workser storage ls [prefix]         # list objects in the bucket
-workser storage put <local> <key>   # upload a file into the bucket
-workser storage get <key> [dest]    # download an object (or print its URL)
-
-workser deploy [--prod] [--watch]   # deploy (git → Vercel); --watch waits for live URL
-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 open                        # open the live app
-workser verify                      # run typecheck/lint/build — gate "done" on this passing
-
-workser agent list                  # main agent + configured roles (+ which are runnable)
-workser agent run <role> "<task>"   # delegate a focused subtask to a role (runs isolated)
-workser agent main                  # show the configured main agent
-
-workser workflow list | create <name> [--body <json>] | get <id>
-workser workflow activate <id> | deactivate <id> | run <id> [--wait] [--body <json>]
-workser workflow runs <id>          # past executions of a workflow
-workser workflow nodes [query]      # search the node-type catalog
-workser app list [--toolkit <slug>] # connectable + connected third-party apps
-workser app connect <toolkit> | disconnect <connectionId>
-workser app tools <toolkit>         # a connected app's callable actions
-workser app run <toolSlug> [--body <json>]  # execute one action (e.g. GOOGLESHEETS_APPEND_ROW)
-
-workser tool list                   # computer-use tools available to you right now
-workser tool run <name> [--body <json>]  # filesystem/shell/screenshot/input/clipboard/browser
-
-workser memory add "<content>" [--metadata <json>]  # remember something across future conversations
-workser memory search "<query>" [--limit N]         # recall what you (or a cloud agent) learned before
-workser memory forget <memoryId>                    # soft-delete an outdated/incorrect memory
-
-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 run                                 # which task you're attached to
-
-workser ask "<question>" [--type <t>] [--option <o>] # ask the user, WAIT for the answer
-
-# owner-only (return owner_only / exit 6 — ask the user to do these in Orbit):
-#   project create · project use · env rm · domain set
-```
-
-## Memory (remember across conversations, not just this one)
-Every conversation you run is otherwise a fresh start — no memory of what you or the
-user decided last time. `workser memory add "<content>"` fixes that: it stores durable,
-searchable memory for the CURRENT PROJECT, and it's the SAME memory space Workser's own
-cloud agents write to for this project — so add something here and a cloud agent (or
-your own next conversation) can `workser memory search` and find it. Use it for things
-worth remembering past this one conversation: user preferences, decisions made,
-important context, requirements — not routine chatter. Before assuming you don't know
-something about this project, `workser memory search "<topic>"` first; it may already be
-recorded. `forget` soft-deletes a specific memory if it's wrong or outdated — the
-content stays retrievable by ID but excluded from future searches.
-
-## Record what you produced (deliverables)
-Workser shows the user a **Deliverables** list on the task. If you don't say what you
-made, it has to guess — it watches your file edits and treats any path it sees as a
-deliverable, so scratch files and half-finished drafts show up next to the real output,
-and things that aren't files at all (a folder of results, an app you deployed) can't
-show up correctly. Fix that by declaring finished output:
-```
-workser artifact add ./report.pdf -d "Q3 sales summary"
-workser artifact add ./exports --kind folder -d "generated CSVs"
-workser artifact add --url https://acme.workser.app --kind app -t "Storefront"
-```
-Only register FINISHED output the user should get — not temp files, not intermediate
-steps. `--kind` is inferred from the path when you omit it (directories are detected
-automatically); pass it explicitly for `app` / `url`. `workser artifact run` shows which
-task you're currently attached to.
-
-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.
-
-## Ask the user something (and get an answer back)
-When you're blocked — a missing value, an ambiguous requirement, permission for
-something consequential — don't guess and don't just write the question into your
-final message. Run:
-```
-workser ask "Which email should order confirmations come from?"
-workser ask "Which plan should I wire up?" --option Free --option Pro --option Team
-workser ask "Delete the 1,240 archived rows?" --type approval
-```
-This shows the user a real card in the conversation and **blocks until they answer**,
-then prints their answer — so you ask, read the reply, and keep working in the same
-turn. Types: `input` (default, free text), `choice` (with `--option`), `approval`
-(permission), `confirmation` (check an assumption), `information` (FYI, no answer
-needed). It times out (default 10 min) rather than hanging forever; if it does, carry
-on and state clearly what you assumed.
-
-**Never ask for a secret value this way** — the answer is stored and displayed. Ask
-where a key should go, then have the user set it (`workser env set` writes it without
-you ever seeing it).
-
-## Computer-use tools (your hands on this machine)
-`workser tool list` shows what's available — filesystem (read/write/list/delete/move),
-shell (run a command/Python/Node), screenshots and screen info, mouse/keyboard input,
-clipboard, notifications, and basic browser control (open a URL, read the page, click/
-fill/type, screenshot). This is the SAME engine Workser's cloud Computer Use agent uses
-when it controls a user's machine remotely — you're getting it locally, gated by the
-same safety policy (blocked paths like `~/.ssh`, blocked destructive commands, rate
-limits). Sensitive actions (writing/deleting files, running a shell command, clicking/
-typing) may return `awaiting_approval` (exit 5) — same handling as any other gated
-action: tell the user to approve in Orbit, then retry. This is a curated subset, not
-full desktop automation — check `workser tool list` rather than assuming a capability
-exists.
-
-## Workflow automation & app integrations
-Beyond one-shot code, wire up **automations** that keep running after you're done:
-`workser workflow create` builds an event-driven, multi-step automation (the same
-engine Workser's own web Workflow tab uses) — nodes/connections/triggers go in
-`--body` as JSON; browse `workser workflow nodes` first. Before an automation (or you,
-directly) can use a third-party app (Gmail, Slack, Stripe, Google Sheets, ...), the
-user connects it once via `workser app connect <toolkit>` — this opens an OAuth link,
-ask the user to complete it, then continue. After that, `workser app run <toolSlug>
---body '{"...":...}'` calls any of its actions. Check `workser app list` before
-assuming you need to ask the user to connect something new.
-
-## Delegate to roles
-The user can configure **roles** — named specialists each backed by a local CLI agent
-(e.g. `qa` → codex, `designer` → claude_code). Delegate a focused subtask with
-`workser agent run <role> "<task>" --json`; the role runs as an **isolated local
-subagent** (its own context) and returns `{role, agent, output, exitCode}`.
-
-- Run `workser agent list --json` first to see which roles are configured + runnable.
-- Hand off focused subtasks (review this diff, design this screen) to keep your own
-  context lean and get a specialized second perspective. A non-zero `exitCode` means
-  the role's run failed — surface that, don't silently ignore it.
-
 ## Typical flow: build → ship
+
 ```bash
 workser status --json                       # 1. orient (project is already pinned)
 workser db create --json                    # 2. provision infra the app needs (idempotent)
@@ -214,11 +98,13 @@ workser env set STRIPE_KEY=sk_live_… --json # 3. configure it
 # … you write the app code with your normal tools …
 workser deploy --prod --watch --json        # 4. ship; returns the live URL
 ```
+
 Provisioning the pinned project's own database / bucket / auth is yours to do
 (`db create`, `storage create`, `auth enable`) — the user may need to approve it in
 Orbit (`awaiting_approval`). Only a **custom domain** is an owner action.
 
 ## Reading results
+
 - Success: use `.data` (e.g. `.data.url` after deploy, `.data` array after `list`).
 - Failure: check `.error.code`:
   - `not_connected` → tell the user to open Workser Orbit (or `workser login` for CI).
@@ -229,3 +115,10 @@ Orbit (`awaiting_approval`). Only a **custom domain** is an owner action.
 
 Keep the user informed in plain language ("Provisioned a database and deployed —
 it's live at <url>"), not raw JSON.
+
+## Writing app code, not operating the app
+
+`workser db query` is for **you** to inspect the database while building. It is not
+how the app reads its own data at runtime — that's `@workser/app`, covered by the
+`workser-sdk` skill. Using the CLI where the SDK belongs is the most common mistake
+here.

package/skills/workser/reference/automation.md

@@ -0,0 +1,55 @@
+---
+topic: automation
+title: Workflows & connected apps
+summary: Build automations that outlive the run; use Gmail, Slack, Stripe, Sheets.
+commands: [workflow, app]
+---
+
+# Workflows & connected apps
+
+Wire up **automations** that keep running after you're done, and use third-party
+accounts (Gmail, Slack, Stripe, Google Sheets) the project has connected.
+
+```
+workser workflow list | create <name> [--body <json>] | get <id>
+workser workflow activate <id> | deactivate <id> | run <id> [--wait] [--body <json>]
+workser workflow runs <id>          # past executions of a workflow
+workser workflow nodes [query]      # search the node-type catalog
+
+workser app list [--toolkit <slug>] # connectable + connected third-party apps
+workser app connect <toolkit> | disconnect <connectionId>
+workser app tools <toolkit>         # a connected app's callable actions
+workser app run <toolSlug> [--body <json>]  # execute one action
+```
+
+## Building a workflow
+
+`workser workflow create` builds an event-driven, multi-step automation — the same
+engine Workser's own web Workflow tab uses. Nodes, connections and triggers go in
+`--body` as JSON.
+
+**Browse `workser workflow nodes` first.** Inventing a node type that doesn't exist
+produces a workflow that saves and then never runs.
+
+Created workflows start inactive: `workser workflow activate <id>` when it's ready.
+
+## Using a connected app
+
+1. `workser app list` — check what's already connected before asking for anything.
+2. If it isn't: `workser app connect <toolkit>` returns an OAuth link. The **user**
+   must open it; you cannot complete OAuth on their behalf. Wait, then continue.
+3. `workser app tools <toolkit>` — read the argument schema rather than guessing
+   field names.
+4. `workser app run <toolSlug> --body '{"…":…}'` — e.g. `GOOGLESHEETS_APPEND_ROW`,
+   `GMAIL_SEND_EMAIL`.
+
+**A `run` is a real side effect in someone's real account.** Sending an email or
+charging a card is not a dry run — say what you're about to do before you do it.
+
+## The half people forget
+
+A workflow-backed feature is two-way. Triggering it is the outbound half; when the
+workflow produces a result the app needs, its final node has to POST back to a
+webhook route in the app. Build only the trigger and the workflow runs perfectly
+while nothing ever appears in the product. The app-side receiver is covered in the
+`workser-sdk` skill under workflows.

package/skills/workser/reference/business-data.md

@@ -0,0 +1,51 @@
+---
+topic: business
+title: Business hub data
+summary: Products, orders, customers, sales, content, marketing, support, analytics.
+commands: [business]
+---
+
+# Business hub data
+
+The project's own commerce and CRM records — the **same rows** the Orbit desktop
+Business tab and workser-web's Business hub show. One generic CRUD surface across
+every resource rather than a command per domain.
+
+```
+workser business resources                        # the known resource names
+workser business list <resource> [subpath]        # list/read  (--query '<json>')
+workser business get <resource> <id>
+workser business create <resource> --body '<json>'
+workser business update <resource> <id> --body '<json>'
+workser business delete <resource> <id>
+workser business action <resource> <id> <verb>    # POST .../<id>/<verb>
+```
+
+## Resources
+
+`business-config`, `business-settings`, `products`, `collections`, `navigations`,
+`orders`, `customers`, `sales-pipelines`, `sales-deals`, `pages`, `blog-posts`,
+`media`, `campaigns`, `email-templates`, `discounts`, `seo-configs`,
+`social-accounts`, `support-conversations`, `automation-rules`, `analytics`.
+
+Run `workser business resources --json` rather than trusting this list — the CLI's
+copy is the current one.
+
+## Notes that matter
+
+- **Sales and Support nest.** `sales-deals` maps to `/sales/deals`,
+  `support-conversations` to `/support/conversations`. Use the dashed names above;
+  the flat `resource/id` shape then works for `get`/`update`/`delete`/`action`.
+- **`list` takes a raw subpath** for anything the map doesn't cover:
+  `workser business list sales-pipelines <id>/stages`.
+- **`action` is for named verbs** — `workser business action orders <id> cancel`,
+  `workser business action sales-deals <dealId> win`. Check the resource's routes
+  before inventing a verb.
+- **These are real business records.** Cancelling an order or deleting a customer is
+  not a dry run. Say what you're about to do first.
+
+## This is for you, not for the app
+
+`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` — see the
+`workser-sdk` skill. An app shelling out to this CLI per request is wrong.

package/skills/workser/reference/computer-use.md

@@ -0,0 +1,35 @@
+---
+topic: computer-use
+title: Computer-use tools
+summary: Files, shell, screen, input, clipboard and browser on this machine.
+commands: [tool]
+---
+
+# Computer-use tools — your hands on this machine
+
+```
+workser tool list                        # what's available to you right now
+workser tool run <name> [--body <json>]  # run one
+```
+
+`workser tool list` shows what's available — filesystem (read/write/list/delete/move),
+shell (run a command / Python / Node), screenshots and screen info, mouse and keyboard
+input, clipboard, notifications, and basic browser control (open a URL, read the page,
+click, fill, type, screenshot).
+
+This is the **same engine** Workser's cloud Computer Use agent uses when it controls a
+user's machine remotely — you're getting it locally, gated by the same safety policy.
+
+## Notes that matter
+
+- **Check `tool list` rather than assuming a capability exists.** This is a curated
+  subset, not full desktop automation.
+- **The safety policy applies.** Blocked paths (`~/.ssh` and friends), blocked
+  destructive commands, rate limits. Refusals are the policy working, not a bug to
+  route around.
+- **Sensitive actions are approval-gated.** Writing or deleting files, running a shell
+  command, clicking or typing may return `awaiting_approval` (exit 5) — tell the user
+  to approve in Orbit, then retry.
+- **You already have your own tools.** For editing files in this repo, use them. Reach
+  for `workser tool` when you need something *outside* the project — the screen, the
+  clipboard, a browser, another app on the machine.

package/skills/workser/reference/database.md

@@ -0,0 +1,41 @@
+---
+topic: database
+title: Database & end users
+summary: Provision Postgres, browse tables, run SQL, provision auth.
+commands: [db, auth]
+---
+
+# Database & end users
+
+The project's Postgres (Neon behind Workser) and its end-user auth. Provisioning is
+idempotent — running `create` twice is safe.
+
+```
+workser db create                   # provision the Neon Postgres database (idempotent)
+workser db url                      # connection string (sensitive; least-privilege role)
+workser db list                     # database status
+workser db tables                   # list tables in the database
+workser db schema <table>           # a table's columns
+workser db data <table> [-n N] [--offset N]   # read rows
+workser db query "<sql>"            # run SQL (writes are approval-gated)
+
+workser auth enable                 # provision auth for the project (idempotent)
+workser auth status                 # is auth enabled? + Neon auth mode
+```
+
+## Notes that matter
+
+- **`db url` is a credential.** Don't print it into the conversation, don't paste it
+  into a file the user will commit. The app gets it from its environment already.
+- **Writes are approval-gated.** A `db query` that mutates may return
+  `awaiting_approval` (exit 5). Ask the user to approve in Orbit, then retry.
+- **`DROP` / `TRUNCATE` are refused** by the safety policy. Change schema with a
+  migration in the app's own migration folder, not with a destructive one-off.
+- **The database is the project's, not the app's.** Sibling apps in the same project
+  share it. Don't assume a table is yours because you created it.
+
+## Reading rows vs. reading data at runtime
+
+`db data` / `db query` are for **you**, inspecting while you build. The app itself
+should read through `@workser/app` (`workser.db`, `workser.business`) — see the
+`workser-sdk` skill. An app that shells out to the CLI at request time is wrong.

package/skills/workser/reference/deliverables.md

@@ -0,0 +1,65 @@
+---
+topic: deliverables
+title: Deliverables & asking the user
+summary: Record finished output on the task, and ask a blocking question.
+commands: [artifact, ask]
+---
+
+# Deliverables & asking the user
+
+Two things that reach the user directly: what you produced, and what you need from
+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 run                                  # which task you're attached to
+
+workser ask "<question>" [--type <t>] [--option <o>]  # ask the user, WAIT for the answer
+```
+
+## Record what you produced
+
+Workser shows the user a **Deliverables** list on the task. If you don't say what you
+made, it has to guess — it watches your file edits and treats any path it sees as a
+deliverable, so scratch files and half-finished drafts show up next to the real
+output, and things that aren't files at all (a folder of results, a deployed app)
+can't show up correctly.
+
+```
+workser artifact add ./report.pdf -d "Q3 sales summary"
+workser artifact add ./exports --kind folder -d "generated CSVs"
+workser artifact add --url https://acme.workser.app --kind app -t "Storefront"
+```
+
+Only register **finished** output the user should get — not temp files, not
+intermediate steps. `--kind` is inferred from the path when you omit it (directories
+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.
+
+## Ask the user something (and get an answer back)
+
+When you're blocked — a missing value, an ambiguous requirement, permission for
+something consequential — don't guess, and don't just write the question into your
+final message where nobody will answer it.
+
+```
+workser ask "Which email should order confirmations come from?"
+workser ask "Which plan should I wire up?" --option Free --option Pro --option Team
+workser ask "Delete the 1,240 archived rows?" --type approval
+```
+
+This shows the user a real card in the conversation and **blocks until they answer**,
+then prints their answer — so you ask, read the reply, and keep working in the same
+turn.
+
+Types: `input` (default, free text), `choice` (with `--option`), `approval`
+(permission), `confirmation` (check an assumption), `information` (FYI, no answer
+needed). It times out (default 10 min) rather than hanging forever; if it does, carry
+on and state clearly what you assumed.
+
+**Never ask for a secret value this way** — the answer is stored and displayed. Ask
+*where* a key should go, then have the user set it (`workser env set` writes it
+without you ever seeing it).

package/skills/workser/reference/deploy.md

@@ -0,0 +1,56 @@
+---
+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]
+---
+
+# Deploy, environment variables & logs
+
+Getting the app online and configured, and finding out why it isn't.
+
+```
+workser deploy [--prod] [--watch]   # deploy (git → Vercel); --watch waits for live URL
+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 open                        # open the live app
+workser verify                      # run typecheck/lint/build
+
+workser env set KEY=VALUE [K2=V2…]  # set env vars
+workser env list                    # list keys (values masked)
+workser env get KEY                 # one value (sensitive)
+```
+
+## 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 — 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.
+- **`--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 — 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.
+
+## After a successful deploy
+
+Register the URL so it shows up on the user's task:
+
+```
+workser artifact add --url https://acme.workser.app --kind app -t "Storefront"
+```
+
+See `reference/deliverables.md`.
+
+## Local vs cloud environment
+
+`env set` configures the **cloud** environment (production and preview). The `.env`
+files in the app folder configure **this computer** — the user edits those in Orbit
+under Settings → "On this computer", and saving there restarts the dev server. Don't
+hand-edit `.env.local` to change cloud behaviour; they are different environments.

package/skills/workser/reference/images.md

@@ -0,0 +1,35 @@
+---
+topic: images
+title: Image generation
+summary: Generate images from a prompt, optionally conditioned on existing images.
+commands: [image]
+---
+
+# Image generation
+
+```
+workser image generate "<prompt>"            # alias: workser image gen
+  -r, --reference <url...>                   # condition on existing images (up to 4)
+  -o, --output <path>                        # also download the first image locally
+```
+
+Returns the generated image's public URL, so the usual move is to generate, then use
+that URL directly in the app.
+
+```bash
+workser image generate "flat illustration of a farm delivery van, brand colors" --json
+workser image gen "same van, from the side" -r https://… -o ./public/van.png --json
+```
+
+## Notes that matter
+
+- **Reference images are image-to-image conditioning**, not attachments. Up to 4;
+  anything beyond that is dropped.
+- **The model sometimes narrates instead of drawing** — a refusal or a clarifying
+  question comes back as text rather than an image. Check that you actually got an
+  image before wiring the URL into a page; an empty result is not a transport error
+  to retry.
+- **`--output` writes only the first image.** If you asked for several, the rest
+  exist only as URLs.
+- **Placeholder art is not a deliverable.** Generating a hero image to unblock a
+  layout is fine; shipping it as the user's brand asset without asking is not.

package/skills/workser/reference/memory.md

@@ -0,0 +1,34 @@
+---
+topic: memory
+title: Memory across conversations
+summary: Store and recall durable project knowledge shared with cloud agents.
+commands: [memory]
+---
+
+# Memory — remember across conversations, not just this one
+
+```
+workser memory add "<content>" [--metadata <json>]  # remember for future conversations
+workser memory search "<query>" [--limit N]         # recall what was learned before
+workser memory forget <memoryId>                    # soft-delete an outdated memory
+```
+
+## Why this exists
+
+Every conversation you run is otherwise a fresh start — no memory of what you or the
+user decided last time. This stores durable, searchable memory for the **current
+project**, and it is the **same memory space** Workser's cloud agents write to for
+this project. Add something here and a cloud agent — or your own next conversation —
+can `memory search` and find it.
+
+## Using it well
+
+- **Search before assuming you don't know.** Before concluding something about this
+  project is undocumented, run `workser memory search "<topic>"`. It may already be
+  recorded.
+- **Store decisions, not chatter.** User preferences, decisions made, constraints,
+  requirements — things worth knowing next week. Not "the build passed".
+- **`forget` is a soft delete.** The content stays retrievable by id but is excluded
+  from future searches. Use it when something is wrong or outdated, rather than
+  adding a contradicting memory on top.
+- **Never store a secret.** Memory is retrievable and displayable.