primitive-admin 1.1.0-alpha.7 → 1.1.0-alpha.71

package/README.md

@@ -5,9 +5,13 @@ Command-line interface for administering Primitive applications. This CLI provid
 ## Installation
 
 ```bash
-npm install -g primitive-admin
+pnpm add -g primitive-admin
 ```
 
+pnpm is the recommended package manager. If you use npm instead, run
+`npm install -g primitive-admin` — install with one manager only, or you end up
+with two global copies.
+
 ### Development Setup
 
 From the **worklet root directory**:
@@ -71,11 +75,15 @@ primitive apps --help
 The CLI uses browser-based OAuth for authentication. When you run `primitive login`, it opens your browser to authenticate via Google OAuth and stores credentials locally.
 
 ```bash
-# Login to the default server
+# Login to the environment resolved from .primitive/config.json
+# (project mode), or the default/PRIMITIVE_SERVER_URL server (legacy mode)
 primitive login
 
-# Login to a custom server
-primitive login --server https://api.example.com
+# Login to a specific named environment
+primitive -e prod login
+
+# Login to a custom server without a project config (legacy mode)
+PRIMITIVE_SERVER_URL=https://api.example.com primitive login
 
 # View current session
 primitive whoami
@@ -129,17 +137,20 @@ Manage applications (requires admin access).
 
 ```bash
 primitive apps list                    # List all accessible apps
-primitive apps create "My App"         # Create a new app
+primitive apps create "My App"         # Create a new app (mints the app id)
 primitive apps get <app-id>            # Get app details
-primitive apps update <app-id> [opts]  # Update app settings
 primitive apps delete <app-id>         # Delete an app
 ```
 
-**Update options:**
-- `--name <name>` - App display name
-- `--mode <mode>` - Access mode: public, invite-only, waitlist
-- `--base-url <url>` - Application base URL
-- `--waitlist` / `--no-waitlist` - Enable/disable waitlist
+App settings are configuration, so they are authored in `app.toml` and applied
+with `config push` (issue #2645) — there is no `apps update`:
+
+```bash
+primitive apps get                       # what the server is running
+primitive config pull --only app         # write those settings into app.toml
+primitive config set app app.mode=invite-only
+primitive config push --only app         # apply the edit
+```
 - `--google-oauth` / `--no-google-oauth` - Enable/disable Google OAuth
 - `--passkey` / `--no-passkey` - Enable/disable passkey auth
 - `--magic-link` / `--no-magic-link` - Enable/disable magic link auth
@@ -150,12 +161,13 @@ Manage users within an app.
 
 ```bash
 primitive users list [app-id]                           # List users
+primitive users create <email> [--role admin|member]    # Create/add user by email
 primitive users invite [app-id] <email> [--role admin]  # Invite user
 primitive users remove [app-id] <user-id>               # Remove user
 primitive users set-role [app-id] <user-id> <role>      # Change role
 primitive users transfer-owner [app-id] <new-owner-id>  # Transfer ownership
-primitive users invitations list [app-id]               # List pending invitations
-primitive users invitations delete [app-id] <inv-id>    # Delete invitation
+primitive users mint-jwt <user-id> [--role <role>]      # Mint test JWT (dev/test only)
+primitive users invitations [app-id]                    # List pending invitations
 ```
 
 ### Waitlist
@@ -175,57 +187,72 @@ Manage HTTP integrations (external API connections).
 
 ```bash
 primitive integrations list [app-id]              # List integrations
-primitive integrations create [app-id] [options]  # Create integration
 primitive integrations get <integration-id>       # Get details
-primitive integrations update <id> [options]      # Update integration
-primitive integrations delete <id>                # Soft delete
 primitive integrations test <id>                  # Test connection
 primitive integrations logs <id>                  # View invocation logs
 ```
 
-**Create options:**
-- `--from-file <path>` - Load from TOML file
-- `--key <key>` - Integration key (identifier)
-- `--name <name>` - Display name
-- `--base-url <url>` - Base URL for API calls
-- `--timeout <ms>` - Request timeout in milliseconds
+An integration is authored in `integrations/<key>.toml` and applied with
+`config push` — creating, updating and deleting one are all edits to that file:
+
+```bash
+primitive config fields integration               # its keys, types, defaults
+primitive config create integration weather-api      # scaffold the file
+primitive config push --only integration/weather-api
+```
 
 **Secrets management:**
+
+Integration-scoped secrets are **retired** — the `primitive integrations secrets`
+command group no longer exists. Use app-level secrets instead
+(`primitive secrets set <KEY> --value <value>`) and reference them in integration
+config via `{{secrets.KEY}}`. See the **Secrets** section below.
+
+### Secrets
+
+Manage encrypted app secrets (API keys, tokens, credentials). Values are encrypted at rest and never displayed after creation.
+
 ```bash
-primitive integrations secrets list <integration-id>
-primitive integrations secrets add <id> --data '{"apiKey":"..."}'
-primitive integrations secrets archive <id> <secret-id>
+primitive secrets list [--app <app-id>]                            # List secrets (values never shown)
+primitive secrets set <KEY> --value <value> [--summary <text>]     # Create or update a secret
+primitive secrets delete <KEY>                                      # Delete a secret
 ```
 
+**Examples:**
+```bash
+primitive secrets set OPENAI_API_KEY --value "sk-..." --summary "Production key"
+primitive secrets set STRIPE_SECRET --value "sk_live_..."
+primitive secrets list --json
+primitive secrets delete STRIPE_SECRET
+```
+
+Keys must be uppercase letters, digits, and underscores (e.g., `OPENAI_API_KEY`). Max 100 secrets per app, 2 KB per value. The `set` command is an upsert — it creates or updates automatically. Use `{{secrets.KEY}}` in workflows and `secrets.KEY` in CEL rules.
+
 ### Prompts
 
 Manage LLM prompt configurations.
 
 ```bash
 primitive prompts list [app-id]             # List prompts
-primitive prompts create [app-id] [options] # Create prompt
 primitive prompts get <prompt-id>           # Get details
-primitive prompts update <id> [options]     # Update prompt
-primitive prompts delete <id>               # Soft delete
 primitive prompts execute <id> --vars '{}'  # Execute prompt
 primitive prompts preview <id> --vars '{}'  # Preview rendered template
 ```
 
-**Create options:**
-- `--from-file <path>` - Load from TOML file
-- `--key <key>` - Prompt key (identifier)
-- `--name <name>` - Display name
-- `--provider <provider>` - LLM provider (openrouter, gemini)
-- `--model <model>` - Model name
-- `--system-prompt <text>` - System prompt
-- `--user-template <text>` - User prompt template
+A prompt is authored in `prompts/<key>.toml` and applied with `config push`:
+
+```bash
+primitive config create prompt summarizer
+primitive config push --only prompt/summarizer
+```
+
+**Configs (prompt variations)** are `[[configs]]` entries in that same file —
+`active = true` marks the live one, `status = "archived"` retires one, and
+duplicating is copying the block under a new `name`. The CLI reads them:
 
-**Configs (prompt variations):**
 ```bash
 primitive prompts configs list <prompt-id>
-primitive prompts configs create <prompt-id> [options]
-primitive prompts configs activate <prompt-id> <config-id>
-primitive prompts configs duplicate <prompt-id> <config-id>
+primitive prompts configs get <prompt> <config>
 ```
 
 ### Workflows
@@ -234,20 +261,103 @@ Manage multi-step workflow definitions.
 
 ```bash
 primitive workflows list [app-id]                  # List workflows
-primitive workflows create [app-id] --from-file wf.toml  # Create workflow
 primitive workflows get <workflow-id>              # Get details
-primitive workflows update <id> [options]          # Update metadata
-primitive workflows draft update <id> --from-file wf.toml  # Update draft
-primitive workflows publish <id>                   # Publish draft
 primitive workflows preview <id> --input '{}'      # Preview execution
+primitive workflows disable <id>                   # Take it out of service now
+primitive workflows enable <id>                    # Put it back
 ```
 
+A workflow is authored in `workflows/<key>.toml` (named config bodies in
+`workflows/<key>.configs/<name>.toml`) and applied with `config push`:
+
+```bash
+primitive config create workflow process-doc
+primitive config push --only workflow/process-doc
+```
+
+Revisions are read-only history from the retired legacy path (issue #2768:
+`workflows publish` and its endpoint are gone). A workflow created before the
+configuration model — one with no active config — is migrated by authoring
+`workflows/<key>.configs/<name>.toml`, setting `activeConfigName = "<name>"` in
+`workflows/<key>.toml`, and pushing.
+
 **Run management:**
 ```bash
 primitive workflows runs list <workflow-id>
 primitive workflows runs status <workflow-id> <run-id>
 ```
 
+**Workflow TOML push-time validation (issue #685):** `primitive config push` —
+the only command that sends a workflow TOML since #2645 — runs the
+file through `cli/src/lib/workflow-toml-validator.ts` before sending it to
+the server. For a step whose `kind` the CLI knows about, the validator
+rejects any top-level field outside the allowlist — most commonly catching
+the footgun where `[steps.<id>.request]` is written under `[[steps]]` (TOML
+places the sub-table under `steps[N][<id>]`, not the intended
+`steps[N].request`, so the runtime silently runs the step with an empty
+`request` block). The correct form for the most-recent step is
+`[steps.request]`. For a step whose `kind` the CLI does NOT know (an older
+CLI run against a newer server that registered a new step kind), the
+per-field check is skipped — so a valid new-kind field is never falsely
+rejected — while the kind-agnostic misnested-header footgun detector still
+fires (issue #998).
+
+**The allowlist is generated, not hand-maintained (issue #998):** The field
+union and the known-kind set live in the committed artifact
+`cli/src/lib/generated-allowlist.ts`, generated from the server step runners
+(`src/workflows/steps/*.ts`) and the universal `BaseStepDefinition` shape by
+`cli/scripts/gen-allowlist.mjs`. The generator runs automatically at CLI
+`prebuild`; regenerate manually with `node cli/scripts/gen-allowlist.mjs`
+(or `pnpm -C cli gen:allowlist`). The union is derived from what each runner
+*reads* off the step config — not from what the `*StepDefinition` type
+declares (types over-declare and would weaken the footgun detector). A
+freshness guard (`node cli/scripts/gen-allowlist.mjs --check`, also asserted
+by `cli/tests/unit/workflow-toml-validator-drift-guard.test.ts`) fails if the
+committed artifact drifts from a fresh scan, so the historical hand-edit
+drift (#685/#802/#971) cannot recur. When you add a new step kind or a runner
+starts reading a new field, just regenerate and commit the artifact — there is
+no hand-maintained list to update.
+
+**A configuration object's field surface has ONE definition (issue #2644):**
+`src/config-surface/` on the server records, per configuration object, which
+`models.yaml` fields exist, which TOML key each carries, which modes the server
+accepts it in, and — for a field with real behavior — the handler that owns it.
+The server's create/update handlers take their accepted key set from it
+(`pickWritableFields`), and `cli/scripts/gen-config-surfaces.mjs` vendors the
+same modules into the committed artifact
+`cli/src/lib/generated-config-surfaces.ts`, which the CLI's push builder, pull
+serializer and TOML key validation read. The generator runs automatically at CLI
+`prebuild`; regenerate manually with `node cli/scripts/gen-config-surfaces.mjs`
+(or `pnpm -C cli gen:config-surfaces`).
+
+Three hard-fail checks live in `cli/tests/unit/config-surface-drift-guard.test.ts`:
+freshness (`--check`, a byte comparison), coverage (every model field of every
+registered object is either exposed or classified `notExposed` **with a
+reason**), and registry existence (every `SYNC_RESOURCE_TYPES` label has a
+definition — the migration's `PENDING_MIGRATION` exemption list is gone, so
+there is nowhere to park one). Add a
+field to `models.yaml` and the CLI unit suite fails until you regenerate and
+classify it — so the CLI can no longer silently drop a new server-side field.
+This supersedes the workflow-only descriptor and generator from #2326.
+
+**Template expressions are linted at push time (issue #2689):** the validator
+also inspects every `{{ }}` expression on a step and rejects the ones that can
+never resolve — an unknown root (`{{ inputs.userId }}`; the valid roots are
+`input`, `steps`, `outputs`, `meta`, `secrets`, `vars`, plus the contextual
+`selected`/`user`/`md`, the built-ins `now`/`today`/`uuid`/`ulid`, and — inside a
+forEach step's body only — `iteration`/`loop` and the loop's binding name) or a
+reference to a `steps.<id>` / `outputs.<name>` the file does not declare. An
+expression that is only sometimes present is marked optional with
+`| default: ''` or a trailing `|| ''`, and anything statically undecidable (a
+dynamic bracket key) is left to the run-time check. The lint itself is a
+verbatim generated copy of the server module
+`src/workflows/runner/template-static-lint.ts` at
+`cli/src/lib/generated-template-lint.ts` (`cli/scripts/gen-template-lint.mjs`,
+run at `prebuild`, with a `--check` freshness mode asserted by
+`cli/tests/unit/template-lint-drift-guard.test.ts`), so the CLI's push-time
+verdict and the server's save-time verdict come from the same code.
+
+
 ### Tokens
 
 Manage long-lived API access tokens for headless/server authentication.
@@ -263,7 +373,7 @@ primitive tokens revoke <token-id> [app-id]                           # Revoke t
 **Create options:**
 - `--name <name>` - Token name (required)
 - `--user <user-id>` - App user ID to associate the token with (required)
-- `--ttl <duration>` - Token lifetime (e.g., 7d, 30d, 4w, 3m, 1y). Omit for never-expiring
+- `--ttl <duration>` - Token lifetime (e.g., 30m, 2h, 7d, 30d, 4w, 3mo, 1y). Omit for never-expiring. Units: `m`/`min`=minutes (≤1440), `h`=hours (≤24), `d`=days, `w`=weeks, `mo`=months, `y`=years. **Note:** as of #420 `m` means minutes (was months); use `mo` for months.
 
 ### Databases
 
@@ -273,6 +383,7 @@ Manage online databases and permissions. `list` returns databases the user has d
 primitive databases list [app-id]                     # List databases (direct access)
 primitive databases create <title> [app-id]           # Create database
 primitive databases get <database-id> [app-id]        # Get details
+primitive databases update <database-id> [options]    # Update title or type
 primitive databases delete <database-id> [app-id]     # Delete database
 ```
 
@@ -283,18 +394,48 @@ primitive databases permissions grant <database-id> --user-id <uid> --permission
 primitive databases permissions revoke <database-id> <user-id> [app-id]
 ```
 
-**Group permissions on databases:**
+Permission values: `owner` (set at creation), `manager`
+
+**Metadata:**
+```bash
+primitive databases metadata update <database-id> --data '{"key":"value"}'  # Merge-update metadata
+```
+
+**Operations:**
+```bash
+primitive databases operations list <database-id> [app-id]                     # List registered operations
+primitive databases operations execute <database-id> <op-name> --params '{}'   # Execute operation
+primitive databases operations execute <database-id> <op-name> --token <jwt>   # Execute as specific user
+```
+
+The `--token` flag lets you execute an operation as a specific user using a test JWT from `users mint-jwt`. Useful for testing access rules.
+
+Under `--json`, the printed shape is the operation's own. A `query` — and a `pipeline` whose `returnField` names a query step — prints the CLI's list envelope `{ items, hasMore, nextCursor? }`, the same shape as `databases records query --json`. Every other operation type prints unchanged: `count` → `{ count }`, `aggregate` → `{ result }`, mutation → `{ results }`, `applyToQuery` → `{ matched, affected, failed, … }`, and a `returnField = "all"` pipeline → `{ steps: { … } }` with each step's own keys left alone. `--timing` adds `_timing` alongside whichever shape you get.
+
+**Records (schema introspection):**
+```bash
+primitive databases records models <database-id> [app-id]            # List model names
+primitive databases records describe <database-id> <model> [app-id]  # Show inferred schema
+```
+
+**Indexes:**
+```bash
+primitive databases indexes list <database-id> [--model <name>]       # List indexes
+primitive databases indexes create <database-id> <model> <field> [options]  # Create index
+primitive databases indexes drop <database-id> <model> <field>        # Drop index
+```
+
+**Export / Import:**
 ```bash
-primitive databases group-permissions list <database-id>
-primitive databases group-permissions grant <database-id> --group-type <type> --group-id <id> --permission <perm>
-primitive databases group-permissions revoke <database-id> <group-type> <group-id>
+primitive databases export [app-id] <database-id> --output <dir>      # Export records, indexes, constraints
+primitive databases import [app-id] <path> --overwrite --dry-run      # Import from export directory
 ```
 
-Permission values: `owner`, `read-write`, `reader`
+Export creates a directory with `metadata.json`, `records.jsonl`, `indexes.json`, and `constraints.json`. Import restores records and indexes into a new or existing database. Database type config (operations, triggers, access rules) is managed separately via `primitive config` — run `config push` on the target app before importing.
 
 ### Documents
 
-Manage document ownership and group permissions.
+Manage document ownership, group permissions, and export/import.
 
 ```bash
 primitive documents transfer-owner [app-id] <document-id> <new-owner-id>  # Transfer ownership
@@ -309,6 +450,15 @@ primitive documents group-permissions revoke <document-id> <group-type> <group-i
 
 Permission values: `read-write`, `reader`
 
+**Export / Import:**
+```bash
+primitive documents export [app-id] <document-id> --output <dir>         # Export Yjs state, blobs, permissions, aliases
+primitive documents export-all [app-id] --user-id <id> --owned-only      # Export all docs for a user
+primitive documents import [app-id] <path> --overwrite --aliases overwrite|skip --dry-run  # Import from export
+```
+
+Export creates a directory per document with `metadata.json`, `document.yjs` (Yjs state), `permissions.json` (for reference), and `blobs/` (attachments). Permissions are exported for reference but not restored during import — the importing admin is the new owner and manages sharing in the target app. Document IDs are preserved across import. User-scoped aliases can be restored with `--aliases overwrite` (update existing) or `--aliases skip` (keep existing, default).
+
 ### Groups
 
 Manage groups, members, and memberships.
@@ -336,26 +486,44 @@ primitive groups memberships <user-id> [app-id]          # List user's group mem
 
 **Group resource access:**
 ```bash
-primitive groups databases <group-type> <group-id>       # List databases a group can access
 primitive groups documents <group-type> <group-id>       # List documents a group can access
 ```
 
-Group permissions on databases and documents are managed via `primitive databases group-permissions` and `primitive documents group-permissions` respectively (see [Databases](#databases) and [Documents](#documents) above).
+Group permissions on documents are managed via `primitive documents group-permissions` (see [Documents](#documents) above).
 
 ### Analytics
 
 View usage analytics for an app.
 
 ```bash
-primitive analytics overview [app-id]              # Activity overview
-primitive analytics top-users [app-id]             # Most active users
-primitive analytics user [app-id] <user-ulid>      # User activity details
-primitive analytics integrations [app-id]          # Integration metrics
+# Overview & active users
+primitive analytics overview [app-id]                  # DAU / WAU / MAU + growth
+primitive analytics daily-active [app-id]              # Daily active users time series
+primitive analytics rolling-active [app-id]            # Rolling active users (28 points)
+primitive analytics cohort-retention [app-id]          # Weekly cohort retention matrix
+
+# Users
+primitive analytics top-users [app-id]                 # Most active users
+primitive analytics user-search [app-id] --query <q>   # Search by email or ULID
+primitive analytics user-detail <user-ulid> [app-id]   # User activity breakdown
+primitive analytics user-snapshot <user-ulid> [app-id] # Latest context snapshot
+
+# Events
+primitive analytics events [app-id]                    # Paginated event feed
+primitive analytics events-grouped [app-id]            # Events grouped by dimension
+
+# Features
+primitive analytics integrations [app-id]              # Integration usage metrics
+primitive analytics workflows [app-id]                 # Top workflows by runs
+primitive analytics prompts [app-id]                   # Top prompts by executions
 ```
 
-**Options:**
-- `--window-days <n>` - Time window (default: 30)
-- `--limit <n>` - Result limit for top-users
+**Common options:**
+- `--window-days <n>` - Time window in days (default varies per command)
+- `--limit <n>` - Result limit (top-users, workflows, prompts)
+- `--group-by <dim>` - Dimension for events-grouped (action, feature, route, country, deviceType, plan, day)
+- `--page <n>` - Page number for events feed (0-based)
+- `--json` - Output raw JSON
 
 ### Admins (Super-Admin Only)
 
@@ -392,15 +560,15 @@ primitive catalog integrations update <catalog-id> [options]
 primitive catalog integrations delete <catalog-id>
 ```
 
-### Sync (TOML Configuration)
+### Config (TOML Configuration)
 
-Sync app configuration to/from TOML files for version control.
+Author app configuration as TOML files and reconcile them with the server.
 
 ```bash
-primitive sync init [app-id] --dir ./config    # Initialize config directory
-primitive sync pull [app-id] --dir ./config    # Pull remote config to local
-primitive sync push [app-id] --dir ./config    # Push local config to remote
-primitive sync diff [app-id] --dir ./config    # Show differences
+primitive config init [app-id] --dir ./config    # Initialize config directory
+primitive config pull [app-id] --dir ./config    # Pull remote config to local
+primitive config push [app-id] --dir ./config    # Push local config to remote
+primitive config diff [app-id] --dir ./config    # Show differences
 ```
 
 **Options:**
@@ -436,7 +604,9 @@ baseUrl = "https://myapp.com"
 [auth]
 googleOAuthEnabled = true
 passkeyEnabled = true
-magicLinkEnabled = false
+emailSignInEnabled = true              # one email carrying a code and a link
+appleSignInEnabled = true              # Sign in with Apple
+appleAudiences = ["com.example.MyApp"] # allowed Apple audiences
 
 [cors]
 mode = "custom"
@@ -444,6 +614,19 @@ allowedOrigins = ["https://myapp.com"]
 allowCredentials = true
 ```
 
+Notes on `[auth]`:
+
+- Only keys you actually list are pushed. Omitting a key leaves the server's
+  current value untouched — it is **not** reset to `false`. To turn a method
+  off, set it explicitly (e.g. `emailSignInEnabled = false`).
+- An unrecognized `[auth]` key (for example a typo like `googleOauthEnabled`)
+  produces a warning on `push` and is ignored, rather than being silently
+  dropped. The push still applies the recognized keys.
+- `appleAudiences = []` and an omitted `appleAudiences` both mean "no
+  audiences" (the server stores them the same way), so `pull` omits the key
+  when there are no audiences. A `[] ` round-trip reading back as an omitted
+  key is expected, not data loss.
+
 ### Example: integrations/weather-api.toml
 
 ```toml
@@ -451,7 +634,6 @@ allowCredentials = true
 key = "weather-api"
 displayName = "Weather API"
 description = "OpenWeatherMap integration"
-status = "active"
 timeoutMs = 30000
 
 [requestConfig]
@@ -467,7 +649,6 @@ allowedPaths = ["/weather", "/forecast"]
 key = "summarizer"
 displayName = "Text Summarizer"
 description = "Summarizes input text"
-status = "active"
 
 [[configs]]
 name = "default"
@@ -500,6 +681,133 @@ primitive apps list
 primitive apps list --json | jq '.[0].appId'
 ```
 
+### Stdout vs. stderr
+
+The CLI follows the same convention as `git`, `kubectl`, `aws`, and `gh`:
+
+- **stdout** carries the *data* the command produced — JSON documents under
+  `--json`, tabular listings (`apps list`), raw values (`primitive token`),
+  and the primary `label: value` fields a `get` / `show` / `describe` command
+  emits (e.g. `primitive integrations get <id>`).
+- **stderr** carries *diagnostics* — status text (`✓ Created…`,
+  `i Waiting for completion...`), warnings (`!` markers), progress lines, and
+  the `key: value` summaries shown *after* a side-effecting command runs
+  (e.g. the `Webhook ID: …` confirmation printed by `webhooks create`).
+
+This means `primitive <cmd> --json | jq` always works, regardless of any
+status / warning / progress text the command may print along the way.
+It also means `primitive integrations get <id> > out.txt` writes the
+integration's fields to `out.txt` while the status diagnostics still appear
+on the terminal via stderr.
+
+Conversely, redirecting stderr (`primitive <cmd> 2>/dev/null`) silences
+diagnostics — including success checkmarks like `✓ Pushed 3 changes` — so
+prefer `2>&1 >file.txt` if you want the full transcript.
+
+For contributors writing new commands, the output helpers in
+`cli/src/lib/output.ts` make the data-vs-diagnostic split explicit: use
+`json()` and `result(label, value)` for data the caller asked for, and
+`success()` / `info()` / `warn()` / `keyValue()` / `divider()` / `heading()`
+for diagnostics about what the command did.
+
+## Programmatic surfaces
+
+### `primitive help --json` — command manifest
+
+`primitive help --json` prints a machine-readable manifest of the full command
+tree (commands, subcommands, positional args, options, aliases, global options,
+and the CLI version) to **stdout** as a single JSON document, then exits `0`. It
+is hidden/undocumented in human `--help` output, auth-free, and runs entirely
+offline (no project config, no credentials, no network) — so it works in any
+directory, including one with no `.primitive/`.
+
+```bash
+primitive help --json | jq '.commands[] | select(.name=="sync") | .commands[].name'
+```
+
+Shape (`schemaVersion: 1`):
+
+```jsonc
+{
+  "schemaVersion": 1,
+  "name": "primitive",
+  "version": "1.0.49",
+  "globalOptions": [ { "flags": "-e, --env <name>", "description": "…", "required": true, "defaultValue": null, "hidden": false } ],
+  "commands": [
+    {
+      "name": "sync",
+      "description": "…",
+      "aliases": [],
+      "args": [],
+      "options": [],
+      "commands": [
+        {
+          "name": "push",
+          "description": "…",
+          "aliases": [],
+          "args": [ { "name": "app-id", "required": false, "variadic": false, "description": "…" } ],
+          "options": [ { "flags": "--dir <path>", "description": "…", "required": true, "defaultValue": null, "hidden": false } ],
+          "commands": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+`hidden` marks a deprecated alias that still works but is not part of the
+supported surface (it is omitted from human `--help` too). Tooling that treats
+the manifest as an allowlist — the docs CLI gate does — should skip those flags.
+
+`schemaVersion` is the contract knob: consumers assert the shape they understand
+and fail loud if a future CLI bumps it (a breaking change for downstream tooling
+such as docs CI that drift-gates documented invocations against the published
+CLI).
+
+### `primitive-admin/validators` — TOML validators
+
+The TOML validators that `config push` runs as its load-bearing gate are exported
+from the `primitive-admin/validators` subpath (ESM-only, with types) so external
+tooling can validate exactly the way the published CLI does — instead of
+re-implementing the flow and silently drifting.
+
+```ts
+import {
+  validateWorkflowTomlSource, // source-level wrapper (parse → expand → validate)
+  validateWorkflowToml,        // raw: pure fn over already-parsed TOML
+  formatWorkflowTomlErrors,
+  validateOperations,          // raw: pure fn over already-parsed operations[]
+  formatIssue,
+} from "primitive-admin/validators";
+```
+
+Two contracts:
+
+- **`validateWorkflowTomlSource(raw, filePath)`** — pass the **raw TOML source
+  string** and the workflow's path. It runs the *identical* parse →
+  `expandWorkflowTomlData()` (`include` fragment expansion) → `validateWorkflowToml`
+  → `formatWorkflowTomlErrors` path that `config push` runs, so it cannot diverge
+  from `config push` on workflow `include` fragments. Returns
+  `{ errors, formatted }` (`formatted` is `null` when valid). Fragment files
+  resolve relative to `<filePath>/../../workflow-fragments/`, matching the CLI.
+
+- **The raw validators** (`validateWorkflowToml`, `validateOperations`,
+  `formatWorkflowTomlErrors`, `formatIssue`) are **pure functions over
+  already-parsed TOML** — they do *not* read files or parse TOML. The consumer
+  parses (e.g. with `smol-toml`) and, for workflows, performs any `include`
+  expansion itself. There is **no coupling on a specific TOML parser version**:
+  pass whatever parsed object / `operations[]` you already have.
+
+  ```ts
+  import * as TOML from "smol-toml";
+  const data = TOML.parse(raw);
+  const errs = validateWorkflowToml(data);
+  if (errs.length) throw new Error(formatWorkflowTomlErrors(path, errs));
+  ```
+
+Internal helpers (`collectParamRefs`, `declaredParamNames`,
+`locateOperationLine`) are intentionally **not** exported.
+
 ## Exit Codes
 
 - `0` - Success
@@ -508,15 +816,30 @@ primitive apps list --json | jq '.[0].appId'
 
 ## Environment Variables
 
-- `PRIMITIVE_SERVER_URL` - Server URL for login (defaults to `https://primitiveapi.com`)
+- `PRIMITIVE_SERVER_URL` - Server URL for login in legacy mode (defaults to `https://primitiveapi.com`)
+
+**Login server resolution:**
+1. Project mode (`.primitive/config.json` present): the active environment's
+   `apiUrl`. Select the environment with `-e <name>`, `PRIMITIVE_ENV`,
+   `primitive env use <name>` (this machine's selection, stored in the
+   gitignored `.primitive/local.json`), or the committed `defaultEnvironment`
+   — in that order. An unresolvable environment fails loudly — `login`
+   never silently falls back to production.
+2. Legacy mode (no project config): `PRIMITIVE_SERVER_URL`, else the default
+   `https://primitiveapi.com`.
 
-**Server URL priority:**
-1. `--server` flag (highest priority)
-2. `PRIMITIVE_SERVER_URL` environment variable
-3. Default: `https://primitiveapi.com`
+> `login` no longer accepts `-s/--server` (removed in a breaking change). Use
+> `-e <env>` in a project, or `PRIMITIVE_SERVER_URL` for local dev / scripts.
+> `init` and `bootstrap` keep their own `-s/--server` (they run before a
+> project config exists).
 
 ## Development
 
+Before adding or changing a command, read [`docs/cli-design.md`](../docs/cli-design.md)
+in the repo root — the CLI's design rules (which verbs each kind of noun carries,
+TOML-only authoring, deletion and naming rules, what a breaking change obliges).
+It is internal maintainer guidance and is not published.
+
 ```bash
 # Run without building (uses tsx)
 pnpm run cli:dev -- login
@@ -570,12 +893,13 @@ cli/tests/
     config.test.ts    # Credentials and config management
     output.test.ts    # Output formatting functions
   integration/
-    api-client.test.ts  # API client HTTP tests
-    commands.test.ts    # CLI command tests
-    tokens.test.ts      # Token lifecycle tests
-    databases.test.ts   # Database CRUD, permissions, group permissions tests
-    documents.test.ts   # Document group permissions, group resource listing tests
-    groups.test.ts      # Group CRUD, members, memberships tests
+    api-client.test.ts      # API client HTTP tests
+    commands.test.ts        # CLI command tests
+    tokens.test.ts          # Token lifecycle tests
+    databases.test.ts       # Database CRUD, permissions, group permissions tests
+    documents.test.ts       # Document group permissions, group resource listing tests
+    groups.test.ts          # Group CRUD, members, memberships tests
+    classroom-e2e.test.ts   # End-to-end classroom app workflow (types, rules, operations, access)
 ```
 
 ## Troubleshooting