@standards/cli 1.0.0-alpha.418 → 1.0.0-alpha.421

package/guide/agents.md

@@ -0,0 +1,162 @@
+# standards: agents
+
+Run Standards agents from the shell: configure where they run, start sessions on a harness, follow them, answer the decisions they stop on, and watch several at once.
+
+- An **environment** is where a session runs: accepted harnesses, repositories, machine size, image.
+- A **secret** is an environment variable a session's machine receives.
+- A **session** is a conversation with an agent on one harness: `claude-code`, `codex` or `cursor` (or `standards`, the built-in agent).
+- A **machine** runs a session's turns. A **link** is a URL a machine publishes (a dev server, a preview).
+- A **decision** is a question an agent parks on until someone answers it.
+
+`<env>` is an environment id or its name. A name two environments share is refused with both ids: pass the id.
+
+## 1. Environments
+
+```bash
+standards environments list
+standards environments get <env>
+standards environments harnesses             # each harness and its models
+standards environments create --name ci --harness claude-code,codex \
+  --repo acme/api --repo acme/web --size default --max-size large --image code
+standards environments create --name docs --harness standards --image documents
+standards environments update <env> --size large       # same flags as create
+standards environments build <env>
+standards environments archive <env> --yes
+```
+
+- `--harness standards` accepts the built-in agent only.
+- Sizes: `small`, `default`, `large`. Images: `code`, `documents`.
+- A shared environment needs `--visibility workspace --confirm-shared`; the default is private.
+
+## 2. Secrets
+
+The value is read from **stdin only**: never pass it as an argument, never type it at a prompt.
+
+```bash
+printf %s "$ANTHROPIC_API_KEY" | standards secrets set ANTHROPIC_API_KEY --environments all
+printf %s "$OPENAI_API_KEY"    | standards secrets set OPENAI_API_KEY --environments ci,staging
+printf %s "$TOKEN" | standards secrets set GITHUB_TOKEN --private          # only your sessions
+printf %s "$TOKEN" | standards secrets set NPM_TOKEN --env ci --repository acme/web
+printf %s "info"   | standards secrets set LOG_LEVEL --plain --environments all   # not sensitive
+standards secrets list [--private | --env <env>]                          # never prints a value
+standards secrets delete NPM_TOKEN --env ci --repository acme/web --yes
+```
+
+- Workspace scope is the default. A **new** workspace secret reaches only the environments `--environments` names (`all`, or a list); without it, it reaches none, and the CLI says so. An **existing** key keeps its environments.
+- `--private`: yours alone, every environment. `--env <env>`: one environment, optionally one `--repository`.
+- Harness keys: `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` (claude-code), `OPENAI_API_KEY` (codex), `CURSOR_API_KEY` (cursor).
+- A TTY stdin is refused. Run the command with a pipe.
+- Logins (password + TOTP) are set in the app, not here.
+
+## 3. Sessions
+
+```bash
+standards sessions start "Fix the failing test in api/" --harness claude-code --env ci \
+  [--model opus] [--size large] [--name fix-tests]
+standards sessions start "<task>" --harness codex --detach   # prints { id, url }, returns at once
+standards sessions send <id> "Now open a pull request"
+standards sessions follow <id>               # follow the running or next turn
+standards sessions list [--running] [--q <text>] [--limit 20]
+standards sessions get <id>                  # { session, phase, lastReply, waiting, machine, links, decisions }
+standards sessions messages <id> --last 5
+standards sessions cancel <id>
+standards sessions archive <id>
+```
+
+`start`, `send` and `follow` stream the turn and exit when it ends:
+
+| Exit | Meaning | Next |
+|---|---|---|
+| 0 | Turn completed. | Read the reply; `send` the next message. |
+| 1 | Turn failed, or `cancelled`. | `sessions get <id>`; `send` to retry. |
+| 1 | `The session stream did not open after 10 attempts` (the API was unreachable for about 40 s; the turn may still run). | `sessions follow <id>`. Never `send`. |
+| 3 | The agent parked on a decision; it is printed. | Answer it (§4), then `sessions follow <id>`. |
+
+- Human output: the reply text, `→ tool <name>` per tool call, `↺ retrying step` when a step restarts (drop the text before it).
+- `--format json`: NDJSON, `{"type":"text","text":…}`, `{"type":"tool","name":…}`, `{"type":"reset"}`, `{"type":"end","outcome":…}` (with `"phase":"parked"` when it parks), then one `{"type":"decision","decision":…}` per decision waiting.
+- The session id and its app URL go to stderr before the turn streams.
+- `follow` on an idle session with nothing waiting returns at once: 0 if its last turn completed, 1 otherwise.
+- A stream that drops reconnects by itself; following is never a reason to resend.
+- If `start` prints `Session created, message not sent`, run the `sessions send` command it names. Never `start` again.
+- `--detach` sends and returns. Follow later with `sessions follow <id>`.
+
+## 4. Decisions
+
+```bash
+standards decisions list [--all]       # open by default; options numbered from 1
+standards decisions show <id>          # title, why, change, questions, links
+standards decisions answer <id> …
+```
+
+Answer by the decision's kind:
+
+| Kind | Answer |
+|---|---|
+| approval | `answer <id> yes` / `answer <id> no --reason "too risky"` |
+| question | one answer per question, in order: an option number (`2`), an option label (`sqlite`), `1,3` for a multi-select, or free text; `--skip` to skip them all |
+| review | `answer <id> yes` / `answer <id> changes --feedback "tighten the tests"` |
+| agent setup | set what it asks for, then `answer <id> continue` (or `skip`) |
+| bundle setup | `answer <id> configure` |
+| anything else | answered in the app: the CLI prints its URL |
+
+- Quote a free-text answer: `answer <id> "Use Postgres 17"`.
+- **A secret is never an answer.** For a setup decision, `decisions show <id>` prints the exact `printf %s "$VALUE" | standards secrets set <KEY> …` command per missing variable. Run it, then `answer <id> continue`.
+- A decision no longer open is refused by the server; `decisions list` again.
+
+## 5. Machines and links
+
+```bash
+standards machines list [--env <env>]
+standards machines get <id>            # machine, lease, pilot, links
+standards machines runs <id>
+standards machines destroy <id> --yes
+standards links open <linkId>          # prints one URL
+standards links relaunch <linkId>      # rerun the link's command, waking the machine
+standards links extend <linkId> --for 2h   # 30m, 2h, 1d; at most 1d
+```
+
+- Find a session's links with `sessions get <id>` (`links`).
+- The URL `links open` prints carries a **single-use token valid 60 seconds**: it is a bearer credential. Open it right away. Never paste it into a message, a file, a log or a decision.
+
+## 6. Monitoring
+
+```bash
+standards status                       # sessions running or parked, open decisions, running machines + links
+standards --format json status         # one object { sessions, decisions, machines }
+standards watch [--interval 10s]       # one line per change, until interrupted
+standards watch --until decision       # exits 3 once a decision is open, one open at start included
+```
+
+- `watch` prints the current state as `snapshot` lines, then only transitions: `session <id> running→idle`, `session <id> → parked`, `session <id> failed`, `decision <id> opened "<title>"`, `decision <id> answered`, `link <slug> published <url>`, `machine <id> stopped`.
+- `--interval` is at least `2s`. A failed poll prints `poll failed: <message>` and retries; 5 in a row exit 1.
+- To wait for one session, use `sessions follow <id>`, not `watch`.
+- Run `watch` in the background (a Monitor or a background shell) and react to its lines; do not poll `status` in a loop.
+
+## 7. The loop end to end
+
+```bash
+printf %s "$ANTHROPIC_API_KEY" | standards secrets set ANTHROPIC_API_KEY --environments all
+standards environments create --name api --harness claude-code --repo acme/api
+standards sessions start "Upgrade the ORM and fix what breaks" --harness claude-code --env api
+# exit 3 → a decision waits
+standards decisions show <decisionId>
+standards decisions answer <decisionId> 1
+standards sessions follow <sessionId>
+# exit 0 → done
+standards sessions get <sessionId>     # lastReply, links
+```
+
+## 8. Several sessions in parallel
+
+```bash
+for task in "Fix issue 101" "Fix issue 102" "Fix issue 103"; do
+  standards sessions start "$task" --harness claude-code --env api --detach
+done                                   # each prints { id, url }
+standards watch --until decision       # in the background; exits 3 when one asks
+standards decisions list
+standards decisions answer <id> …
+standards watch --until decision       # start watching again
+standards status                       # where everything stands
+```
+
+Keep the session ids the `--detach` runs print; `sessions list --running` finds them again.

package/guide/core.md

@@ -0,0 +1,88 @@
+# standards: core
+
+The `standards` CLI drives a Standards workspace over its HTTP API. Every output is plain text or JSON. This guide matches the installed version; `standards guide --list` lists the other topics.
+
+## Connect
+
+```bash
+npm i -g @standards/cli                       # or: npx @standards/cli <command>
+standards login                               # a person at a terminal: browser login to hosted Standards
+standards login --url https://<host>/v1 --name prod --key "$STANDARDS_API_KEY"
+standards use prod                            # select a saved instance
+standards instances                           # list saved instances
+standards whoami                              # profile, API URL, key prefix; checks the key with one call
+standards logout [name]                       # forget an instance (the current one by default)
+```
+
+- Without `--key`, `login` opens the browser, stores a personal key and a profile named after the workspace. That key mirrors the person minus key management: it lists and revokes only itself, and cannot create or detach keys. Without a terminal it exits 2: an agent uses `STANDARDS_API_KEY` or `--key`.
+- With `--key`, `login` checks the key before saving it. Either way it selects the new instance.
+- `logout` revokes a browser-login key on the server before forgetting the profile; a `--key` key is only forgotten.
+- Profiles live in `~/.standards/config.json` (`STANDARDS_CONFIG_DIR` moves it).
+- Resolution: `--api-url`/`--api-key` → `--instance <name>` → the current instance → `STANDARDS_API_URL`/`STANDARDS_API_KEY`.
+- `login, use, instances, logout, help, init, guide` need no key. Every other command exits 2 when no instance is configured.
+
+## Global flags
+
+Put them before the command: `standards --format table records list contacts`.
+
+| Flag | Meaning |
+|---|---|
+| `--format json\|table\|csv` | Data commands default to `json` (pretty-printed). `table` truncates cells at 50 chars. |
+| `--instance <name>` | Use a saved instance for this call only. |
+| `--api-url <url>`, `--api-key <key>` | Bypass the saved profiles. |
+| `--tenant <id>` | Multi-tenant setups; defaults to the primary tenant. |
+
+Streaming commands (`sessions start|send|follow`, `watch`) and `status` write human text while `--format` is left at its default. Pass `--format json` explicitly to get NDJSON (streams) or one JSON object (`status`).
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success. |
+| 1 | Refused or failed. The reason is on stderr as `✗ Error: <message>` (`✗ Error (<status>): …` for an HTTP refusal). |
+| 2 | Not configured: no instance or key. Also `login` without a terminal and without `--key`. |
+| 3 | Streaming commands and `watch --until decision` only: a decision is waiting. Run `standards decisions list`. |
+
+One exception: `standards schema diff` exits 0 when equal, 1 when there are differences, 2 on error.
+
+## Output tips
+
+- Pipe JSON into `jq`: `standards records list contacts | jq '.data[].id'`.
+- Collections are `{ data, page: { hasMore, total, countMode } }`. For a row table, select `.data` first.
+- Single-quote JSON arguments: `--data '{"email":"a@b.com"}'`.
+- Destructive commands refuse without `--yes`. Preview first with `--dry-run` where it exists.
+- Never put a secret in argv. Pipe it: `printf %s "$VALUE" | standards secrets set KEY`.
+
+## Command groups
+
+| Group | What it does | Guide |
+|---|---|---|
+| `records` | CRUD, search, export, move, sharing of records | `records` |
+| `documents` | documents and their file packs | `records` |
+| `files` | upload, list, download and delete uploaded files | `records` |
+| `meetings` | read meetings and their transcripts | `records` |
+| `schema` | inspect objects; `pull` and `diff` deployed source vs runtime | `schema-and-bundles` |
+| `bundles` | sync, add and update bundles | `schema-and-bundles` |
+| `skills` | pull, push, search, add workspace skills | `schema-and-bundles` |
+| `mcp` | remote MCP servers mounted into agents | `schema-and-bundles` |
+| `connectors` | mail and calendar connections | `schema-and-bundles` |
+| `keys` | API keys: `list`, `create --name n [--role r] [--workspace] --yes`, `detach <id> --yes`, `revoke <id> --yes`. A browser-login profile only lists and revokes its own key. | |
+| `invitations` | `list`, `create --email e --role <roleId> --yes`, `resend <id>`, `revoke <id> --yes`. A browser-login profile only lists and revokes its own key. | |
+| `usage` | AI usage, wallet and quotas: `usage [--from <day>] [--to <day>] [--scope me\|workspace]` (current UTC month by default) | |
+| `environments`, `secrets`, `machines`, `links` | where agents run and what they hold | `agents` |
+| `sessions`, `decisions` | run agents and answer them | `agents` |
+| `status`, `watch` | monitor sessions, decisions, machines | `agents` |
+| `init`, `guide` | install the skill stub; print this guide | |
+
+`usage` prints `{ usage, wallet, quotas }`. A part you may not read is `null`, with its reason on stderr; the command still exits 0 while one part succeeds.
+
+`standards <group> --help` lists a group's commands and flags.
+
+## The agent loop
+
+1. `printf %s "$KEY" | standards secrets set ANTHROPIC_API_KEY --environments all` (once).
+2. `standards sessions start "<task>" --harness claude-code` streams the turn.
+3. Exit 0: done. Read the reply, or `standards sessions send <id> "<next>"`.
+4. Exit 3: `standards decisions list`, then `standards decisions answer <id> …`.
+5. `standards sessions follow <id>` resumes following after an answer.
+6. Details and every flag: `standards guide agents`.

package/guide/records.md

@@ -0,0 +1,100 @@
+# standards: records, documents, meetings
+
+Record data of the workspace's objects. Find object names with `standards schema list`.
+
+## Read
+
+```bash
+standards records list contacts --limit 20 --offset 0 --sort created_at:desc \
+  --filter '{"and":[{"attribute":"status","operator":"eq","value":"active"}]}'
+standards records list contacts --fields company,owner     # hydrate only these references
+standards records list contacts --fields ""                # hydrate no reference
+standards records list contacts --count exact               # ask for page.total
+standards records search contacts --query "alice" --limit 10
+standards records get contacts <id>
+standards records export contacts --columns name,email,company -o contacts.csv
+```
+
+- `list` and `search` return `{ data, page: { hasMore, total, countMode } }`. Paging is offset only.
+- `--sort` takes one `attribute:asc|desc` rule.
+- `--filter` is the full filter state JSON. Single-quote it.
+- `--count none|estimated|exact`: totals are opt-in; without it `page.total` is `null`. An unknown mode is refused.
+- `export` writes CSV to stdout (or `-o <file>`): `--columns` in order, optional `--query`, `--filter`, `--sort`, `--timezone` (defaults to this machine's).
+
+## Write
+
+```bash
+standards records create contacts --data '{"firstname":"Alice","email":"a@example.com"}'
+standards records create pages --data '{"title":"Child"}' --parent <parentId>   # hierarchical objects
+standards records create contacts --data '{"firstname":"Alice"}' --metadata '{"brevoId":"42"}'
+standards records update contacts <id> --data '{"firstname":"Alicia"}'
+standards records set-logo companies <id> acme.com
+standards records attach-document contacts <id> --file ./contract.pdf [--attribute <attr>] [--title <t>]
+standards records attach-file contacts <id> --file-id <fileId> [--attribute <attr>] [--document-id <docId>] [--title <t>]
+```
+
+- `--metadata` is a JSON object of application state beside the values, set at creation. Filter on it with `metadata.<key>` (dotted for nested keys) and `is`, `is_not`, `is_empty`, `is_not_empty`.
+- `attach-file` attaches a file already uploaded with `files upload`; `--document-id` appends it to that pack instead of creating one.
+
+## Delete and move: preview first
+
+```bash
+standards records delete contacts <id1> <id2> --dry-run   # broken links and descendants, deletes nothing
+standards records delete contacts <id1> <id2>             # one id: delete; several: bulk delete
+standards records move pages <id> --parent <newParentId> --dry-run   # who gains and loses access
+standards records move pages <id> --parent <newParentId>
+standards records move pages <id> --top-level
+```
+
+- `move` needs exactly one of `--parent` or `--top-level`. It moves the subtree; the children take the new root's visibility, owner and grants.
+- `move` does not ask. Run it with `--dry-run` first.
+
+## Share a private record
+
+```bash
+standards records access list contacts <id>
+standards records access grant contacts <id> <actorId> --role reader|editor
+standards records access revoke contacts <id> <actorId>
+standards records access clear contacts <id>             # remove every manual share
+```
+
+## Documents
+
+A document lives on a record's document attribute and holds a pack of files.
+
+```bash
+standards documents list --limit 20
+standards documents get <docId>
+standards documents create --title "Q1 report" --object contacts --record <id> --attribute files
+standards documents update <docId> --title "Q1 report (final)"
+standards documents delete <docId>
+standards documents files <docId>                        # the pack, in position order
+standards documents add-file <docId> --file-id <fileId>
+standards documents remove-file <docId> <fileId>
+standards documents content <docId>                      # aggregated OCR text
+standards documents preview <docId>
+```
+
+To upload a local file, use `records attach-document`.
+
+## Files
+
+```bash
+standards files upload ./a.pdf ./b.png                   # private; prints the stored files and their ids
+standards files list --limit 20 [--folder <path>] [--mime-type application/pdf]
+standards files list --ids <id1>,<id2>                   # exactly those you can see, in that order
+standards files get <fileId>
+standards files content <fileId> -o ./a.pdf              # the bytes (stdout without -o)
+standards files delete <fileId> --yes                    # your own loose files only; a pack member is a 409
+```
+
+## Meetings (read only)
+
+```bash
+standards meetings list --search kickoff --since 2026-08-01T00:00:00Z --order asc --limit 20
+standards meetings get <meetingId>
+standards meetings for-record <recordId> --email-attributes email,work_email [--count exact]
+standards meetings transcript <meetingId>
+```
+
+`for-record` returns nothing until at least one email attribute is named.

package/guide/schema-and-bundles.md

@@ -0,0 +1,94 @@
+# standards: schema, bundles, skills, MCP, connectors
+
+## Schema (read only)
+
+```bash
+standards schema list                    # every object
+standards schema inspect contacts        # attributes, types, views (name or id)
+standards schema groups                  # bundles that own objects, with their label
+standards schema pull                    # deployed source vs shared runtime, as reconciliation guidance
+standards schema diff                    # the differences, one per line
+```
+
+- `pull` and `diff` read what is deployed, not unbuilt local TypeScript.
+- `--format json` makes `pull` print the canonical shared state and `diff` the canonical differences.
+- `schema diff` exits 0 when equal, 1 when there are differences, 2 on error (the CLI's one exception to its exit codes).
+- The CLI never changes schema directly. Change the project's bundles and sync them.
+
+## Bundles
+
+A bundle declares objects, views, pages and agents.
+
+```bash
+standards bundles sync [--cwd ./apps/crm]   # discover standards/bundles/*.ts, order by `uses`, sync each
+standards bundles list                       # installed: name, mode, origin, short hash, installedAt
+standards bundles status                     # current, update or repair, and what depends on each
+standards bundles available --locale fr      # bundles the workspace may add as copies it owns
+```
+
+Add and update in two steps: plan with `--dry-run`, then apply with the plan's `fingerprint`.
+
+```bash
+standards bundles add crm --with-samples --dry-run          # plan: new and colliding pieces + fingerprint
+standards bundles add crm --with-samples --fingerprint <fp> \
+  --decision <pieceId>=bind --decision <pieceId>=rename:opportunities --decision <pieceId>=skip
+standards bundles update crm --dry-run                      # pieces by group + fingerprint
+standards bundles update crm --fingerprint <fp> --take deals --skip-missing notes --decision companies=bind
+standards bundles remove <name> --yes
+```
+
+- Without `--dry-run`, `--fingerprint` is required. Pass the same names and flags as the plan.
+- The server refuses a stale fingerprint: the workspace changed since the plan. Plan again.
+- `--decision` settles one collision: `bind`, `skip` or `rename:<name>`.
+- `update` keeps a piece you changed unless `--take` names it, restores a missing piece unless `--skip-missing` names it, and never removes a piece.
+- `remove` demotes a synced bundle's objects to workspace-owned and deletes nothing. An added bundle is uninstalled from the app's Bundles window.
+- `sync` prints `<name> applied|unchanged <hash7>` per bundle. A 409 names the owner of the conflicting piece.
+
+## Skills
+
+Workspace skills are Agent Skills folders (`SKILL.md` and its files).
+
+```bash
+standards skills pull ./skills [--name onboarding]          # write each skill as <dir>/<name>/
+standards skills push ./skills [--replace]                   # import folders, all or nothing
+standards skills search "invoice follow-up"                  # the official catalogue
+standards skills search "invoice follow-up" --community      # skills.sh
+standards skills search --community [--trending]             # skills.sh leaderboard, no query
+standards skills add acme/skills@invoice-followup --dry-run  # what the source would install
+standards skills add acme/skills@invoice-followup[#ref]
+standards skills update invoice-followup [--discard-changes]
+standards skills refresh                                     # check private catalogue skills against their sources
+```
+
+- A search without a query needs `--community`.
+- A result's `state` is `available`, `installed`, `name_taken` or `unavailable` (see `reason`).
+- `push` skips hidden entries and symbolic links and reports each one.
+
+## MCP servers
+
+Remote MCP servers whose tools are mounted into the workspace's agents.
+
+```bash
+standards mcp list
+standards mcp catalog
+standards mcp connect --slug context7 --name Context7 --url https://mcp.context7.com/mcp \
+  [--catalog-entry context7] [--visibility workspace|private] \
+  [--auth-type header --header-name X-API-KEY --secret "$TOKEN"]
+standards mcp refresh <id>            # re-discover tools
+standards mcp rename <id> "New name"  # the slug and tool prefix never change
+standards mcp trust <id> [--revoke]   # run its tools without per-call approval
+standards mcp disconnect <id> --yes
+```
+
+## Connectors
+
+Mail and calendar connections. The account itself is connected from the app (Connectors in the sidebar), never from the terminal.
+
+```bash
+standards connectors providers                   # providers this deployment can connect
+standards connectors list [--scope tenant|actor]
+standards connectors connect --provider gmail [--capabilities modify,send] [--yes]   # checks, then points to the app
+standards connectors disconnect <id> --yes [--remove-imported]
+```
+
+`disconnect` keeps what the connection imported unless `--remove-imported` is passed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@standards/cli",
-  "version": "1.0.0-alpha.418",
+  "version": "1.0.0-alpha.421",
   "description": "CLI tool to interact with Standards API",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
   "types": "./dist/index.d.mts",
   "files": [
     "dist",
+    "guide",
     "LICENSE",
     "README.md"
   ],
@@ -23,12 +24,14 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@standards/client": "1.0.0-alpha.418",
-    "@standards/constants": "1.0.0-alpha.418",
-    "@standards/schema": "1.0.0-alpha.418",
+    "@standards/client": "1.0.0-alpha.421",
+    "@standards/constants": "1.0.0-alpha.421",
+    "@standards/schema": "1.0.0-alpha.421",
     "cli-table3": "^0.6.5",
     "commander": "^13.1.0",
-    "jiti": "2.7.0"
+    "jiti": "2.7.0",
+    "oauth4webapi": "3.8.8",
+    "open": "11.0.4"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",