primitive-admin 1.2.0-alpha.1 → 1.2.0-alpha.11

package/README.md

@@ -1,6 +1,6 @@
 # primitive-admin CLI
 
-Command-line interface for administering Primitive applications. This CLI provides full control over your Primitive apps, including user management, integrations, prompts, workflows, and configuration sync.
+Command-line interface for administering Primitive applications. This CLI provides full control over your Primitive apps, including user management, integrations, prompts, server functions, and configuration sync.
 
 ## Installation
 
@@ -93,11 +93,15 @@ primitive logout
 ```
 
 Inside a project, credentials are stored per environment in the gitignored
-`<projectRoot>/.primitive/credentials.json`; a `login` run outside a project
-writes `~/.primitive/credentials.json`. Both are mode 0600. Only `login`,
-`logout`, `bootstrap` and `init` work outside a project — every other command
-stops with an error naming the missing `primitive/config.json`, rather than
-reading the global file (see [Outside a project](#outside-a-project)).
+`<projectRoot>/.primitive/credentials.json`, each with the server that issued
+it; a command refuses a stored login whose server is no longer the
+environment's `apiUrl`. In a linked git worktree the file is the main
+worktree's for the same project, so every worktree shares one login (and one
+`logout`). A `login` run outside a project writes
+`~/.primitive/credentials.json`. Both are mode 0600. Only `login`,
+`logout`, `bootstrap`, `init` and `apps delete` work outside a project — every
+other command stops with an error naming the missing `primitive/config.json`,
+rather than reading the global file (see [Outside a project](#outside-a-project)).
 
 ## App Context
 
@@ -123,19 +127,32 @@ primitive users list 01HXYZ...
 
 Commands with other required arguments use `--app`:
 ```bash
-primitive workflows get <workflow-id> --app 01HXYZ...
+primitive prompts get <prompt-id> --app 01HXYZ...
 ```
 
 ### Outside a project
 
 With no project config up the directory tree there is no environment, so there
 is nothing for an app-scoped command to target. Only `login`, `logout`,
-`bootstrap` and `init` work there; everything else (`whoami`, `apps list`,
-`env add`, `config pull`, …) exits non-zero with an error that names the
-missing `primitive/config.json` and points at `primitive init`. The CLI never
-falls back to `~/.primitive/credentials.json` for those commands, and no flag
-redirects a command at another project's tree — run it from inside the project
-whose environment names the app.
+`bootstrap`, `init`, `apps delete` and `whoami` work there; everything else
+(`apps list`, `apps get`, `env add`, `config pull`, …) exits non-zero with an
+error that names the missing `primitive/config.json` and points at
+`primitive init`. The CLI never falls back to `~/.primitive/credentials.json`
+for those commands, and no flag redirects a command at another project's tree
+— run it from inside the project whose environment names the app.
+
+`apps delete <app-id>` deletes an app by id with the login and step-up held
+for the server `PRIMITIVE_SERVER_URL` names, or the default server when it is
+unset — the server `login` signs in to there. A stored login another server
+issued is refused and its tokens are not sent. `whoami` reports that server,
+where it came from, and the login or `PRIMITIVE_TOKEN` it would use:
+
+```bash
+PRIMITIVE_SERVER_URL=https://api.example.com primitive login --app all
+PRIMITIVE_SERVER_URL=https://api.example.com primitive login --step-up --scope admin --app 01HXY...
+PRIMITIVE_SERVER_URL=https://api.example.com primitive whoami
+PRIMITIVE_SERVER_URL=https://api.example.com primitive apps delete 01HXY... --confirm "My App"
+```
 
 ## Commands
 
@@ -169,10 +186,11 @@ 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 create <email> [--role admin|member] [--name <name>] [--avatar-url <url>]  # 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 set-profile [app-id] <user-id> [--name <name>] [--avatar-url <url> | --clear-avatar]  # Set display name/avatar
 primitive users transfer-owner [app-id] <new-owner-id>  # Transfer ownership
 primitive users mint-jwt <user-id> [--role <role>]      # Mint test JWT (dev/test only)
 primitive users invitations [app-id]                    # List pending invitations
@@ -234,7 +252,7 @@ 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.
+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 integration request templates and `secrets.KEY` in CEL rules.
 
 ### Prompts
 
@@ -263,68 +281,22 @@ primitive prompts configs list <prompt-id>
 primitive prompts configs get <prompt> <config>
 ```
 
-### Workflows
+### Workflows (retained history)
 
-Manage multi-step workflow definitions.
+DSL workflows are retired (#3190): nothing creates, changes or runs one. Write
+the logic as a server function (`primitive config create function <key>`). The
+definitions, configurations and revisions an app stored stay readable until
+their retention expires:
 
 ```bash
-primitive workflows list [app-id]                  # List workflows
-primitive workflows get <workflow-id>              # Get details
-primitive workflows preview <id> --input '{}'      # Preview execution
-primitive workflows disable <id>                   # Take it out of service now
-primitive workflows enable <id>                    # Put it back
+primitive workflows list [app-id]                          # Retained definitions
+primitive workflows get <workflow-id-or-key>               # One, with configs and revisions
+primitive workflows configs list <workflow-id-or-key>      # Its configurations
+primitive workflows configs get <workflow-id-or-key> <config-id>
 ```
 
-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 config tree that still holds `workflows/` or `transforms/` is refused by
+`config push` and reported by `config diff`, naming the migration page.
 
 **A configuration object's field surface has ONE definition (issue #2644):**
 `src/config-surface/` on the server records, per configuration object, which
@@ -348,23 +320,6 @@ 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
 
@@ -440,7 +395,9 @@ primitive databases export [app-id] <database-id> --output <dir>      # Export r
 primitive databases import [app-id] <path> --overwrite --dry-run      # Import from export directory
 ```
 
-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.
+Export creates a directory with `metadata.json`, `records.jsonl`, `indexes.json`, and `constraints.json`. Import restores records, indexes, and constraints into a new or existing database; it reads every file first, so a malformed export fails without creating a database. Database type config (operations, triggers, access rules) is managed separately via `primitive config` — run `config push` on the target app before importing.
+
+A database the target app doesn't have is created with a new id. `databases import --json` lists each database in `databases[]` with `sourceDatabaseId`, `title`, `action` (`created`, `updated`, `skipped`), `targetDatabaseId` (the id written to; absent for skipped entries and under `--dry-run`), and `reason` for a skip (`exists`, `no metadata.json`). The human output prints `Imported database <source> (<title>) as <target>` when the id changed.
 
 ### Documents
 
@@ -466,7 +423,7 @@ primitive documents export-all [app-id] --user-id <id> --owned-only      # Expor
 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).
+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). A document whose permissions, aliases or blob list can't be read (anything but a 404, after retrying transient failures) is not exported: the command names it and exits non-zero, and `export-all` still exports the rest and leaves it out of `manifest.json`.
 
 ### Collections
 
@@ -502,34 +459,36 @@ primitive collections import <path> --owner <userId-or-email>  # one owner for e
 
 Both verbs are for admin tokens. Owners and members are recorded as emails, because app users are scoped to their app and a source app's user id means nothing in the target. The import reads before it writes: it resolves every owner, member, document and group, plans `create`/`merge`/`skip`/`refused` per collection, then applies group grants, members and documents in that order. Matching is by name; `--overwrite` merges only into a collection whose owner, type and context id match, since none of those can change after creation. A group grant the target holds at another level is updated to the level the file records, and effective access follows it — except above 200 documents, where the server refuses a collection-wide group change whole (`COLLECTION_FANOUT_LIMIT`) and the import reports it as a `group` problem. Per-item problems go to stderr and to `--json.problems`; the exit code is 1 when any was reported. Collection ids are not preserved, and the groups themselves, collection resource metadata and pending member invitations do not travel.
 
+A group grant is resolved by the `groupId` the file records. Into the app it was exported from, that is the same group. Into another app, create the groups there first — each create returns that app's own id — then set each `groups[].groupId` in `collections.json` to the id the target app returned before you import; a grant whose group the target lacks is reported as a `group` problem and skipped.
+
 ### Groups
 
-Manage groups, members, and memberships.
+Manage groups, members, and memberships. A group is named by its id, which the server assigns on `create` and prints (`--json` answers it as `groupId`); its custodian is the app or the user who holds its `owner` membership.
 
 ```bash
-primitive groups list [app-id]                           # List groups
-primitive groups create [app-id] --type <type> --id <id> --name <name>  # Create group
-primitive groups get <group-type> <group-id> [app-id]    # Get details
-primitive groups update <group-type> <group-id> [app-id] # Update group
-primitive groups delete <group-type> <group-id> [app-id] # Delete group
+primitive groups list [app-id] [--custodian app|user:<user-id>]   # List groups, or one custodian's
+primitive groups create --name <name> [--owner <user-id>] [--member-list members|managers]  # Create group
+primitive groups get <group-id>                                   # Get details
+primitive groups update <group-id> [--name] [--description] [--member-list]  # Update group
+primitive groups delete <group-id>                                # Delete group
 ```
 
 **Members:**
 ```bash
-primitive groups members list <group-type> <group-id> [app-id]
-primitive groups members add <group-type> <group-id> <user-id> [app-id]
-primitive groups members remove <group-type> <group-id> <user-id> [app-id]
-primitive groups members set-role <group-type> <group-id> <user-id> <role> [app-id]
+primitive groups members list <group-id>                          # With each member's role
+primitive groups members add <group-id> <user-id> [--role manager|member]
+primitive groups members set-role <group-id> <user-id> <role>
+primitive groups members remove <group-id> <user-id>
 ```
 
 **Memberships:**
 ```bash
-primitive groups memberships <user-id> [app-id]          # List user's group memberships
+primitive groups memberships <user-id> [app-id]          # List user's group memberships, with roles
 ```
 
 **Group resource access:**
 ```bash
-primitive groups documents <group-type> <group-id>       # List documents a group can access
+primitive groups documents <group-id>                    # List documents a group can access
 ```
 
 Group permissions on documents are managed via `primitive documents group-permissions` (see [Documents](#documents) above).
@@ -557,13 +516,12 @@ primitive analytics events-grouped [app-id]            # Events grouped by dimen
 
 # 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
 ```
 
 **Common options:**
 - `--window-days <n>` - Time window in days (default varies per command)
-- `--limit <n>` - Result limit (top-users, workflows, prompts)
+- `--limit <n>` - Result limit (top-users, 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
@@ -634,8 +592,9 @@ primitive/<env>/
     weather-api.toml       # Integration configs
   prompts/
     summarizer.toml        # Prompt configs with all variations
-  workflows/
-    process-doc.toml       # Workflow definitions
+  functions/
+    process-doc.toml       # Server function declarations
+    process-doc.ts         # …and the TypeScript their `entry` reaches
 ```
 
 ### Example: app.toml
@@ -854,47 +813,59 @@ CLI).
 
 ### `primitive-admin/validators` — TOML validators
 
-The TOML validators that `config push` runs as its load-bearing gate are exported
+The operations validator that `config push` runs as its load-bearing gate is 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:
+Both are **pure functions over already-parsed TOML** — they do *not* read files
+or parse TOML. The consumer parses (e.g. with `smol-toml`); there is **no
+coupling on a specific TOML parser version**: pass whatever `operations[]` you
+already have. (The workflow validators the subpath also exported retired with
+DSL workflows, #3190.)
 
-- **`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.
+Internal helpers (`collectParamRefs`, `declaredParamNames`,
+`locateOperationLine`) are intentionally **not** exported.
 
-- **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.
+### `primitive-admin/vite` — the Primitive environment Vite plugin
 
-  ```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));
-  ```
+`primitiveEnv()` resolves the project's Primitive environment at Vite config
+time, in the same order every `primitive` command uses (`--primitive-env` /
+`PRIMITIVE_ENV`, then `primitive env use`, then `defaultEnvironment`, then the
+sole environment), and fills the identity a web app reads:
 
-Internal helpers (`collectParamRefs`, `declaredParamNames`,
-`locateOperationLine`) are intentionally **not** exported.
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import { primitiveEnv } from "primitive-admin/vite";
+
+export default defineConfig({
+  plugins: [primitiveEnv(), vue()],
+});
+```
+
+- It defines `import.meta.env.VITE_APP_ID`, `VITE_API_URL`, `VITE_WS_URL`,
+  `VITE_APP_NAME` and `VITE_PRIMITIVE_ENV`, and publishes the same keys into
+  `process.env` so vitest sees them too.
+- An explicit `VITE_*` identity key in a `.env` file or the shell wins, with a
+  warning naming it.
+- `VITE_EXPECTED_PRIMITIVE_ENV` in `.env.<mode>` pins that mode to one
+  Primitive environment; a run that resolves another stops at config time.
+
+The subpath exports `primitiveEnv`, `resolvePrimitiveEnv` (the same resolution
+for a script: `resolvePrimitiveEnv({ root, env, primitiveEnv })`) and
+`PrimitiveEnvError` (its `kind` says what was wrong). It is built on the CLI's
+own resolver, so the plugin and the `primitive` binary of one install always
+agree. `vite` is an optional peer dependency: the plugin imports only its
+types and never loads it at runtime.
 
 ## Exit Codes
 
@@ -904,7 +875,7 @@ Internal helpers (`collectParamRefs`, `declaredParamNames`,
 
 ## Environment Variables
 
-- `PRIMITIVE_SERVER_URL` - Server URL for `login` outside a project (defaults to `https://primitiveapi.com`)
+- `PRIMITIVE_SERVER_URL` - Server URL for `login` and `apps delete` outside a project (defaults to `https://primitiveapi.com`); ignored inside a project
 
 **Login server resolution:**
 1. Project mode (`primitive/config.json` present): the active environment's

package/assets/skill/skills/primitive-platform/SKILL.md

@@ -3,7 +3,7 @@ name: primitive-platform
 description: >
   Fetches the Primitive platform's agent guides and applies them. MUST be used whenever the user
   is writing or reviewing code that uses js-bao, js-bao-wss-client, primitive-app,
-  primitive-functions, or any Primitive platform feature (documents, databases, server functions,
+  primitive-functions, or any Primitive platform feature (databases, server functions,
   prompts, integrations, blobs, authentication, users/groups), and before running any `primitive`
   CLI command. All development guidance lives in the guides this skill fetches; after writing or
   modifying code that touches Primitive APIs, it cross-references the code against those guides
@@ -49,7 +49,7 @@ primitive guides get <topic>           # the topic's default variant
 - **Freshness.** Guides are cached under `~/.primitive/guides/` for 24 hours. After upgrading the
   CLI or the libraries, pass `--refresh` on the first `list` and `get`.
 - **Where to start.** `configuration` covers projects, environments, and pushing config;
-  `data-modeling` covers choosing where data lives; `inspecting-and-debugging` covers reading a
+  `databases` covers storing and partitioning data; `inspecting-and-debugging` covers reading a
   running app. For a CLI command you have not used, fetch the guide for its feature first.
 
 ## Writing code
@@ -63,6 +63,32 @@ primitive guides get <topic>           # the topic's default variant
 4. Before running a `primitive` command that changes server state, read the `Env | App | Server`
    header every command prints and confirm it names the environment you intend. The
    `configuration` guide explains projects and environments.
+   If the change needs a `config push` to test and that environment is shared — with other
+   developers, live users, or the user's own work in another worktree — recommend a child app
+   instead, and follow the `configuration` guide's "Child apps" workflow.
+5. A plain `primitive login` holds the default scope, which cannot delete apps other than
+   `internal` ones (every child app is `internal`), cannot delete databases or change roles,
+   and cannot write to an app whose protection level is `protected`. In a project it is pinned
+   to the project's apps on that server. When a command is refused with a 403, act on its
+   `code`, not on the command it prints:
+   - `INSUFFICIENT_SCOPE`: it prints the exact `primitive login …` command that grants the
+     missing scope (a missing `admin` prints `primitive login --step-up --scope … --app <id>`).
+     Ask the user to run it (a step-up opens the browser), then retry once.
+   - `PROTECTED_APP_STEP_UP_REQUIRED`: the app is protected. Ask the user to run the printed
+     `primitive login --step-up --scope … --app <id>` command, then retry once. Never lower the
+     app's `protection` to get past it.
+   - `APP_NOT_PINNED`: the login's pins do not reach the app or route the command named. First
+     confirm the command targets the app you intended (`primitive whoami` shows the pins); only
+     then ask the user to run the `primitive -e <env> login` the error names, or the printed
+     command. Never ask for `primitive login --app all` to get around a pin.
+   - `PROTECTION_OWNER_ONLY` or `PROTECTION_FIXED_ON_CHILD`: the push changes a protection level
+     this login may not change. Unless the user asked for the change, restore the `protection`
+     line that `primitive config pull --only app` writes.
+
+   If a command says *Your login predates scoped sessions*, ask the user to run
+   `primitive login`. An unattended run uses a CI session the user creates with
+   `primitive auth sessions create` and passes in `PRIMITIVE_TOKEN`; never create one yourself.
+   The `configuration` guide has the details.
 
 ## Reviewing code (automatic, after every change)
 
@@ -176,7 +202,11 @@ a grep:
   sources, not its dependencies.
 - **The configuration tree.** A deprecated key or spelling in the app's `primitive/`
   TOML is reported when the tree is pushed; the `configuration` guide explains how to
-  check a tree without applying it.
+  check a tree without applying it. When the upgrade changes the tree and the
+  environment it is pushed to is shared — with other developers, live users, or the
+  user's own work in another worktree — push it to a child app first and verify it
+  there, following the `configuration` guide's "Child apps" workflow; push to the
+  shared environment once the upgrade is merged.
 
 A surface an earlier scan reported as deprecated may since have been removed, and a
 removed surface is not a lint warning but a build error, a refused request or a
@@ -249,7 +279,10 @@ guides for the app's feature areas. Compare against what the app actually does:
 
 Run the app's tests, apply the post-change review above to everything modified, and
 update the feedback doc's upgrade stamp (date, channel, versions, and the template
-commit synced in Step 6).
+commit synced in Step 6). If the upgrade changed the configuration tree and the
+environment is shared, verify against the child app from Step 4, not the shared
+environment; the `configuration` guide's "Child apps" workflow covers applying the
+merged tree to the parent and deleting the child.
 
 ### The platform feedback doc
 

package/dist/bin/primitive.js

@@ -9,10 +9,9 @@ import { registerAppsCommands } from "../src/commands/apps.js";
 import { registerUsersCommands } from "../src/commands/users.js";
 import { registerWaitlistCommands } from "../src/commands/waitlist.js";
 import { registerIntegrationsCommands } from "../src/commands/integrations.js";
-import { registerWebhooksCommands } from "../src/commands/webhooks.js";
 import { registerConnectionsCommands } from "../src/commands/connections.js";
 import { registerSessionsCommands } from "../src/commands/sessions.js";
-import { registerCronTriggersCommands } from "../src/commands/cron-triggers.js";
+import { registerAgentSessionsCommands } from "../src/commands/agent-sessions.js";
 import { registerLocksCommands } from "../src/commands/locks.js";
 import { registerMetadataCommands } from "../src/commands/metadata.js";
 import { registerPromptsCommands } from "../src/commands/prompts.js";
@@ -30,14 +29,14 @@ import { registerTokensCommands } from "../src/commands/tokens.js";
 import { registerDatabasesCommands } from "../src/commands/databases.js";
 import { registerGroupsCommands } from "../src/commands/groups.js";
 import { registerRuleSetsCommands } from "../src/commands/rule-sets.js";
-import { registerGroupTypeConfigsCommands } from "../src/commands/group-type-configs.js";
 import { registerDatabaseTypeConfigsCommands } from "../src/commands/database-type-configs.js";
 import { registerGuidesCommands } from "../src/commands/guides.js";
 import { registerDocumentsCommands } from "../src/commands/documents.js";
+import { registerDb3Commands } from "../src/commands/db3.js";
+import { registerDb3TypesCommands } from "../src/commands/db3-types.js";
 import chalk from "chalk";
 import { registerEmailTemplatesCommands } from "../src/commands/email-templates.js";
 import { registerCollectionsCommands } from "../src/commands/collections.js";
-import { registerCollectionTypeConfigsCommands } from "../src/commands/collection-type-configs.js";
 import { registerMetadataCategoryConfigsCommands } from "../src/commands/metadata-category-configs.js";
 import { error } from "../src/lib/output.js";
 import { installGlobalCrashHandlers } from "../src/lib/crash-handlers.js";
@@ -50,7 +49,7 @@ import { registerSecretsCommands } from "../src/commands/secrets.js";
 import { registerVarsCommands } from "../src/commands/vars.js";
 import { registerBlobBucketsCommands } from "../src/commands/blob-buckets.js";
 import { registerEnvCommands } from "../src/commands/env.js";
-import { setCurrentEnvName, getCurrentEnvNameSafe, getProjectConfig, PrimitiveEnvError, } from "../src/lib/env-resolver.js";
+import { setCurrentEnvName, getCurrentEnvNameSafe, getCurrentEnvironment, getProjectConfig, PrimitiveEnvError, } from "../src/lib/env-resolver.js";
 import { ProjectConfigError, PROJECT_CONFIG_DISPLAY_NAME, findProjectConfigPath } from "../src/lib/project-config.js";
 // Install global crash handlers first thing. Without these, an error that
 // escapes the top-level `.catch` below — e.g. ERR_USE_AFTER_CLOSE thrown from
@@ -183,6 +182,11 @@ catch (err) {
 // Skipped when the layout is refused: the file that would name the
 // environments is the one the CLI will not read, and the refusal below is the
 // answer to every command that cares.
+//
+// The check is the resolver's own, so `--env` reaches every environment the
+// resolver knows — the committed ones and this machine's machine-local ones
+// (#4117) — and an unknown name is refused with the one message that lists
+// them all.
 if (preParsedEnv && !staleLayoutRefusal) {
     try {
         const project = getProjectConfig();
@@ -190,14 +194,10 @@ if (preParsedEnv && !staleLayoutRefusal) {
             error(`--env was given but no ${PROJECT_CONFIG_DISPLAY_NAME} was found in this directory or any parent.`);
             process.exit(1);
         }
-        if (!project.environments[preParsedEnv]) {
-            const available = Object.keys(project.environments).join(", ") || "(none)";
-            error(`Environment "${preParsedEnv}" is not defined in ${PROJECT_CONFIG_DISPLAY_NAME}. Available: ${available}`);
-            process.exit(1);
-        }
+        getCurrentEnvironment();
     }
     catch (err) {
-        if (err instanceof ProjectConfigError) {
+        if (err instanceof ProjectConfigError || err instanceof PrimitiveEnvError) {
             error(err.message);
             process.exit(1);
         }
@@ -213,16 +213,22 @@ if (!skipHeader) {
     // parsed (#3273's shape). In project mode the URL comes from the config;
     // outside a project there is nothing to show.
     //
-    // The app is the environment's, and nothing else's (#3152) — read straight
-    // from the config, so the header is right before login as well as after.
+    // The app is the environment's, and nothing else's (#3152) — read from the
+    // resolved environment, so the header is right before login as well as
+    // after, and a machine-local environment shows its own app and server
+    // (#4117). Every resolver error is swallowed: the command reports it.
     const envNameForHeader = getCurrentEnvNameSafe();
     let headerAppId;
     let headerAppName;
+    // The active environment's apiUrl, so the header stays correct even before
+    // you have logged in.
+    let server;
     if (envNameForHeader) {
         try {
-            const envCfg = getProjectConfig()?.environments[envNameForHeader];
+            const envCfg = getCurrentEnvironment()?.config;
             headerAppId = envCfg?.appId;
             headerAppName = envCfg?.appName;
+            server = envCfg?.apiUrl;
         }
         catch {
             // ignore
@@ -231,19 +237,6 @@ if (!skipHeader) {
     const appInfo = headerAppName
         ? `${headerAppName} (${headerAppId})`
         : headerAppId || "None set";
-    // The active environment's apiUrl, so the header stays correct even before
-    // you have logged in.
-    let server;
-    if (envNameForHeader) {
-        try {
-            const env = getProjectConfig()?.environments[envNameForHeader];
-            if (env)
-                server = env.apiUrl;
-        }
-        catch {
-            // fall through
-        }
-    }
     server = server || "Not configured";
     let projectConfigPath = null;
     try {
@@ -308,14 +301,17 @@ Project configuration (primitive/config.json):
   the CLI operates in project mode: each environment's committed configuration
   is at <projectRoot>/primitive/<env>/, this machine's credentials and
   selection live under <projectRoot>/.primitive/, and each named environment is
-  isolated. Without a primitive/config.json only login, logout, bootstrap and
-  init work; every other command stops and names the missing project config
-  (create one with 'primitive init'). There is no global fallback.
+  isolated. Without a primitive/config.json only login, logout, bootstrap,
+  init and 'apps delete' work; every other command stops and names the missing
+  project config (create one with 'primitive init'). 'apps delete' there uses
+  the login for PRIMITIVE_SERVER_URL, or the default server when it is unset.
 
 Primitive environment selection (project mode):
   1. --env <name> flag
   2. PRIMITIVE_ENV env var
-  3. This machine's selection in .primitive/local.json ('primitive env use')
+  3. This machine's selection in .primitive/local.json ('primitive env use'),
+     which may name a machine-local environment registered in the same file:
+     a child app that uses a committed environment's tree
   4. "defaultEnvironment" in primitive/config.json (the committed team default)
   5. The only environment, if there's exactly one
 
@@ -336,10 +332,9 @@ registerAppsCommands(program);
 registerUsersCommands(program);
 registerWaitlistCommands(program);
 registerIntegrationsCommands(program);
-registerWebhooksCommands(program);
 registerConnectionsCommands(program);
 registerSessionsCommands(program);
-registerCronTriggersCommands(program);
+registerAgentSessionsCommands(program);
 registerLocksCommands(program);
 registerMetadataCommands(program);
 registerPromptsCommands(program);
@@ -359,13 +354,13 @@ registerTokensCommands(program);
 registerDatabasesCommands(program);
 registerGroupsCommands(program);
 registerRuleSetsCommands(program);
-registerGroupTypeConfigsCommands(program);
 registerDatabaseTypeConfigsCommands(program);
 registerGuidesCommands(program);
 registerDocumentsCommands(program);
+registerDb3Commands(program);
+registerDb3TypesCommands(program);
 registerEmailTemplatesCommands(program);
 registerCollectionsCommands(program);
-registerCollectionTypeConfigsCommands(program);
 registerMetadataCategoryConfigsCommands(program);
 registerSkillCommands(program);
 registerSecretsCommands(program);