primitive-admin 1.1.0-alpha.3 → 1.1.0-alpha.30

package/README.md

@@ -150,12 +150,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
@@ -197,6 +198,26 @@ primitive integrations secrets add <id> --data '{"apiKey":"..."}'
 primitive integrations secrets archive <id> <secret-id>
 ```
 
+### Secrets
+
+Manage encrypted app secrets (API keys, tokens, credentials). Values are encrypted at rest and never displayed after creation.
+
+```bash
+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.
@@ -267,12 +288,13 @@ primitive tokens revoke <token-id> [app-id]                           # Revoke t
 
 ### Databases
 
-Manage online databases, permissions, and group permissions.
+Manage online databases and permissions. `list` returns databases the user has direct access to; group-shared databases are listed via `primitive groups databases`.
 
 ```bash
-primitive databases list [app-id]                     # List databases
+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,14 +305,68 @@ primitive databases permissions grant <database-id> --user-id <uid> --permission
 primitive databases permissions revoke <database-id> <user-id> [app-id]
 ```
 
-**Group permissions:**
+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.
+
+**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 export [app-id] <database-id> --output <dir>      # Export records, indexes, constraints
+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 sync` — run `sync push` on the target app before importing.
+
+### Documents
+
+Manage document ownership, group permissions, and export/import.
+
+```bash
+primitive documents transfer-owner [app-id] <document-id> <new-owner-id>  # Transfer ownership
+```
+
+**Group permissions on documents:**
+```bash
+primitive documents group-permissions list <document-id>
+primitive documents group-permissions grant <document-id> --group-type <type> --group-id <id> --permission <perm>
+primitive documents group-permissions revoke <document-id> <group-type> <group-id>
+```
+
+Permission values: `read-write`, `reader`
+
+**Export / Import:**
 ```bash
-primitive databases group-permissions list <database-id> [app-id]
-primitive databases group-permissions grant <database-id> --group-type <type> --group-id <id> --permission <perm> [app-id]
-primitive databases group-permissions revoke <database-id> <group-type> <group-id> [app-id]
+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
 ```
 
-Permission values: `owner`, `read-write`, `reader`
+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
 
@@ -317,20 +393,46 @@ primitive groups members set-role <group-type> <group-id> <user-id> <role> [app-
 primitive groups memberships <user-id> [app-id]          # List user's group memberships
 ```
 
+**Group resource access:**
+```bash
+primitive groups documents <group-type> <group-id>       # List documents a group can access
+```
+
+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)
 
@@ -545,11 +647,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
-    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

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

@@ -0,0 +1,167 @@
+---
+name: primitive-platform
+description: >
+  Expert guide for building applications on the Primitive platform. MUST be used whenever the user
+  is writing code that uses js-bao, js-bao-wss-client, primitive-app components, or any Primitive
+  platform feature (documents, databases, workflows, prompts, integrations, blobs, authentication,
+  users/groups). Also trigger whenever about to run any `primitive` CLI command (e.g., primitive sync, primitive integrations, primitive apps, primitive use) to ensure Step 0 CLI verification is performed first. After writing or modifying code that touches Primitive
+  APIs, this skill cross-references the implementation against official guides and automatically
+  corrects common mistakes. Use this skill even if the user doesn't explicitly ask for it —
+  any Primitive-related code should be validated against current best practices.
+allowed-tools: Bash, Read, Edit, Write, Glob, Grep, Agent
+---
+
+# Primitive Platform Development Guide
+
+You are an expert on the Primitive platform. Your job is to help developers write correct,
+idiomatic Primitive code by leveraging the CLI's built-in guide system and enforcing best practices.
+
+**The CLI guides are the single source of truth.** Never hardcode or memorize guide content —
+always fetch the latest from the CLI.
+
+## Step 0: Verify CLI Configuration
+
+The Primitive CLI maintains state for the **currently active server endpoint and app**. Before
+running any CLI commands, confirm you're targeting the correct environment:
+
+1. **Check for a `.env` file** in the project root (e.g., `.env`, `.env.local`, `.env.development`).
+   It typically contains `PRIMITIVE_API_URL` or similar variables that set the server endpoint,
+   and may reference a specific app ID.
+2. **Run a CLI command and read its output.** The CLI prints the active server URL and app context
+   at the top of most command outputs — verify these match the project's intended environment.
+3. **Use inspection commands** to confirm current state:
+
+```bash
+primitive whoami       # Shows authenticated user, app ID, and server endpoint
+```
+
+**Why this matters:** If the CLI is pointed at the wrong server (e.g., production instead of
+development) or the wrong app, commands like `primitive sync push` will modify the wrong
+environment. Always verify before running mutating operations.
+
+## Step 1: Discover Available Guides
+
+Before writing or reviewing any Primitive code, run:
+
+```bash
+primitive guides list
+```
+
+This returns the full list of available guide topics with descriptions, keywords, and use cases.
+Use this output to determine which guides are relevant to the current task.
+
+## Step 2: Fetch the Relevant Guides
+
+For each relevant topic identified in Step 1, fetch the full guide:
+
+```bash
+primitive guides get <topic>
+```
+
+**Always fetch guide(s) BEFORE writing code.** If multiple features are involved, fetch multiple
+guides. The guides contain:
+- Complete API documentation with method signatures
+- Working code examples (TypeScript/JavaScript)
+- Common patterns and anti-patterns
+- Configuration examples (TOML files for `primitive sync`)
+- Decision frameworks for architecture choices
+
+**Do not guess or assume API patterns.** If you're unsure about a method signature, parameter,
+or pattern, fetch the guide. The guides are comprehensive and authoritative.
+
+## Step 3: Write Code Following Guide Patterns
+
+When writing Primitive code:
+
+1. **Follow the patterns from the fetched guides exactly** — method names, argument order, lifecycle patterns
+2. **Use `primitive sync`** for all backend configuration (workflows, prompts, integrations, databases)
+3. **Configuration lives in TOML files** in version control, pushed via `primitive sync push`
+4. **Run `pnpm codegen`** after creating or modifying js-bao models
+
+## Step 4: Post-Code Review (Automatic)
+
+After writing or modifying Primitive-related code, **automatically perform this review**:
+
+### 4a. Identify What Was Written
+Determine which Primitive features the new/modified code touches by scanning for:
+- Import statements from `js-bao`, `js-bao-wss-client`, or `primitive-app`
+- Primitive API calls (documents.open, databases.connect, workflows, etc.)
+- Model definitions, schemas, queries
+- Configuration files (TOML for sync)
+
+### 4b. Fetch and Cross-Reference
+Run `primitive guides list` to identify which guides cover the features used, then fetch each one:
+```bash
+primitive guides get <topic>
+```
+
+Compare the written code against the guide content:
+- **API usage patterns** — Are methods called correctly with proper arguments?
+- **Lifecycle management** — Are documents opened before queries? Is auth checked first?
+- **Access control** — Are CEL expressions or permissions configured properly?
+- **Anti-patterns** — Does the code do anything the guide explicitly warns against?
+- **Missing steps** — Does the code need `pnpm codegen`, `primitive sync push`, or other follow-up?
+
+### 4c. Report and Fix
+If issues are found:
+1. **Explain the issue** — cite the specific guide section that applies
+2. **Show the fix** — provide corrected code
+3. **Apply the fix** — edit the file directly (don't just suggest, actually fix it)
+4. **Note any CLI commands needed** — e.g., `pnpm codegen` or `primitive sync push`
+
+If no issues are found, briefly confirm the code follows best practices.
+
+## CLI Quick Reference
+
+Remind users of these essential commands when relevant:
+
+```bash
+# Verify current configuration (DO THIS FIRST)
+primitive whoami                   # Check authenticated user, app ID, and server endpoint
+primitive status                   # Check active app context and server
+# Also check .env / .env.local / .env.development in the project for
+# PRIMITIVE_API_URL or app ID settings — these control which server the CLI targets.
+
+# Setup
+npm install -g primitive-admin    # Install CLI
+primitive login                    # Authenticate
+primitive use "My App"             # Set app context
+
+# Guides (the most important commands for development)
+primitive guides list              # See all available guides with topics and descriptions
+primitive guides get <topic>       # Read detailed guide for a specific topic
+
+# Configuration as Code
+primitive sync init --dir ./config # Initialize config directory
+primitive sync pull --dir ./config # Pull config from server
+primitive sync push --dir ./config # Push config to server
+primitive sync diff --dir ./config # Preview changes before push
+
+# Common operations
+primitive apps list                # List apps
+primitive apps create "Name"       # Create app
+```
+
+## When the User is Starting a New Feature
+
+If the user describes a new feature they want to build:
+
+1. **Verify CLI configuration** per Step 0 — confirm the server endpoint and app ID match the
+   project's intended environment before running any commands
+2. **Run `primitive guides list`** to discover available topics
+3. **Identify which guides are relevant** to their feature from the list output
+4. **Fetch those guides** with `primitive guides get <topic>`
+5. **Recommend a data modeling approach** based on the guide content. If requirements are unclear or ambiguous, **ask the user clarifying questions before proceeding** — it's much easier to get the data model right upfront than to migrate later
+6. **Outline the implementation steps** referencing specific patterns from the guides
+7. **Write the code** following the patterns exactly
+8. **Review automatically** per Step 4 above
+
+## When the User Asks "How Do I...?"
+
+For any question about Primitive platform capabilities:
+
+1. **Run `primitive guides list`** to find the relevant topic
+2. **Fetch the guide**: `primitive guides get <topic>`
+3. **Answer from the guide content** — don't guess or make up APIs
+4. **Include working code examples** from the guide
+5. **Point the user to the guide** for further reading: "You can see more examples by running `primitive guides get <topic>`"

package/dist/bin/primitive.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { Command } from "commander";
+import { Command, CommanderError } from "commander";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, resolve } from "path";
@@ -9,6 +9,8 @@ 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 { registerCronTriggersCommands } from "../src/commands/cron-triggers.js";
 import { registerPromptsCommands } from "../src/commands/prompts.js";
 import { registerWorkflowsCommands } from "../src/commands/workflows.js";
 import { registerAdminsCommands } from "../src/commands/admins.js";
@@ -20,46 +22,189 @@ import { registerComparisonsCommands } from "../src/commands/comparisons.js";
 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 { registerDatabaseTypesCommands } from "../src/commands/database-types.js";
 import { registerGuidesCommands } from "../src/commands/guides.js";
 import { registerDocumentsCommands } from "../src/commands/documents.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 { error } from "../src/lib/output.js";
 import { ApiError } from "../src/lib/api-client.js";
+import { checkForUpdate } from "../src/lib/version-check.js";
+import { loadCredentials } from "../src/lib/config.js";
+import { checkSkillStatus } from "../src/lib/skill-installer.js";
+import { registerSkillCommands } from "../src/commands/skill.js";
+import { registerSecretsCommands } from "../src/commands/secrets.js";
+import { registerBlobBucketsCommands } from "../src/commands/blob-buckets.js";
+import { registerEnvCommands } from "../src/commands/env.js";
+import { setCurrentEnvName, getCurrentEnvNameSafe, getProjectConfig, } from "../src/lib/env-resolver.js";
+import { ProjectConfigError, PROJECT_CONFIG_DISPLAY_NAME, findProjectConfigPath } from "../src/lib/project-config.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(resolve(__dirname, "../../package.json"), "utf-8"));
+const isVersionFlag = process.argv.includes("--version") || process.argv.includes("-V");
+const subcommand = process.argv[2];
+const isJsonOutput = process.argv.includes("--json");
+const skipHeader = isVersionFlag || isJsonOutput || subcommand === "login" || subcommand === "logout" || subcommand === "token";
+// --env <name> is a global option that must be applied BEFORE any command
+// code runs, because loadCredentials() and getServerUrl() both consult the
+// active environment. Commander only parses options during .parse(), so we
+// pre-extract it here via a tiny manual scan. The actual option is still
+// registered on the program below so it appears in --help.
+function preParseEnvFlag() {
+    const argv = process.argv;
+    for (let i = 2; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--env" || a === "-e") {
+            return argv[i + 1] || null;
+        }
+        if (a.startsWith("--env="))
+            return a.slice("--env=".length);
+    }
+    return null;
+}
+const preParsedEnv = preParseEnvFlag();
+if (preParsedEnv) {
+    setCurrentEnvName(preParsedEnv);
+}
+// Surface project-config errors loudly and early. A broken config file
+// should fail fast with a clear message rather than producing cryptic
+// "Not logged in" errors deeper in.
+try {
+    getProjectConfig();
+}
+catch (err) {
+    if (err instanceof ProjectConfigError) {
+        error(err.message);
+        if (err.path)
+            error(`  at ${err.path}`);
+        process.exit(1);
+    }
+    throw err;
+}
+// If the user explicitly passed --env <name>, verify it resolves to a
+// real environment NOW so we don't silently fall back to legacy creds.
+if (preParsedEnv) {
+    try {
+        const project = getProjectConfig();
+        if (!project) {
+            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);
+        }
+    }
+    catch (err) {
+        if (err instanceof ProjectConfigError) {
+            error(err.message);
+            process.exit(1);
+        }
+        throw err;
+    }
+}
+if (!skipHeader) {
+    const creds = loadCredentials();
+    // In project mode the env may declare an appId even before login.
+    // Show that so the header is useful during `env add` / `login` flows.
+    const envNameForHeader = getCurrentEnvNameSafe();
+    let headerAppId = creds?.currentAppId;
+    let headerAppName = creds?.currentAppName;
+    if (envNameForHeader && (!headerAppId || !headerAppName)) {
+        try {
+            const envCfg = getProjectConfig()?.environments[envNameForHeader];
+            headerAppId = headerAppId || envCfg?.appId;
+            headerAppName = headerAppName || envCfg?.appName;
+        }
+        catch {
+            // ignore
+        }
+    }
+    const appInfo = headerAppName
+        ? `${headerAppName} (${headerAppId})`
+        : headerAppId || "None set";
+    // Prefer the active environment's apiUrl so the header stays correct
+    // even before you've logged in. Only fall back to credentials' serverUrl
+    // in legacy mode.
+    let server = creds?.serverUrl;
+    if (envNameForHeader) {
+        try {
+            const env = getProjectConfig()?.environments[envNameForHeader];
+            if (env)
+                server = env.apiUrl;
+        }
+        catch {
+            // fall through
+        }
+    }
+    server = server || "Not configured";
+    const projectConfigPath = findProjectConfigPath();
+    const envLabel = envNameForHeader
+        ? ` | Env: ${envNameForHeader}`
+        : projectConfigPath
+            ? " | Env: (none selected)"
+            : "";
+    console.log(chalk.dim(`CLI Version: ${pkg.version}${envLabel} | App: ${appInfo} | Server: ${server}`));
+    console.log();
+}
 const program = new Command();
 program
     .name("primitive")
+    .exitOverride()
     .description(`CLI for administering Primitive applications.
 
 Manage apps, users, integrations, prompts, workflows, and more from the command line.
 Supports TOML-based configuration sync for version-controlled app settings.`)
     .version(pkg.version)
+    // Global --env flag. Parsed above in preParseEnvFlag too; declaring it
+    // here so commander shows it in help output and forwards it to
+    // subcommands.
+    .option("-e, --env <name>", "Named environment from .primitive/config.json (e.g. dev, prod)")
     .addHelpText("after", `
 Examples:
-  $ primitive login                    # Authenticate via browser OAuth
-  $ primitive use "My App"             # Set working app context
-  $ primitive users list               # List users (uses current app)
-  $ primitive integrations list --json # JSON output for scripting
-  $ primitive sync pull --dir ./config # Export config to TOML files
+  $ primitive init my-app                # Scaffold a new project + .primitive/config.json
+  $ primitive env list                   # Show environments
+  $ primitive env add prod --api-url ... # Add a new environment
+  $ primitive --env prod users list      # Run a command against a specific env
+  $ primitive login                      # Authenticate via browser OAuth
+  $ primitive sync pull                  # Pull config (auto per-env path)
 
-Authentication:
-  Credentials are stored in ~/.primitive/credentials.json
+Project configuration (.primitive/config.json):
+  In a directory with a .primitive/config.json (or any subdirectory of one),
+  the CLI operates in project mode: credentials and sync state live under
+  <projectRoot>/.primitive/ and each named environment is isolated.
+  Without a .primitive/config.json the CLI runs in legacy mode, reading
+  credentials from ~/.primitive/credentials.json.
+
+Environment selection (project mode):
+  1. --env <name> flag
+  2. PRIMITIVE_ENV env var
+  3. "defaultEnvironment" in .primitive/config.json
+  4. The only environment, if there's exactly one
 
 App Context:
-  Set with 'primitive use <app>' to avoid passing --app to every command.
-  Most commands accept --app flag to override the current context.
+  Bind an app to an environment via "appId" in .primitive/config.json, or
+  run 'primitive use <app>' to set one in credentials. Most commands accept
+  --app to override.
 
 Documentation:
   See https://primitive-labs.github.io/primitive-docs/ for full documentation.
 `);
 // Register all command groups (init first, then logically grouped)
 registerInitCommand(program);
+registerEnvCommands(program);
 registerAuthCommands(program);
 registerAppsCommands(program);
 registerUsersCommands(program);
 registerWaitlistCommands(program);
 registerIntegrationsCommands(program);
+registerWebhooksCommands(program);
+registerCronTriggersCommands(program);
 registerPromptsCommands(program);
 registerWorkflowsCommands(program);
 registerAdminsCommands(program);
@@ -71,24 +216,56 @@ registerComparisonsCommands(program);
 registerTokensCommands(program);
 registerDatabasesCommands(program);
 registerGroupsCommands(program);
+registerRuleSetsCommands(program);
+registerGroupTypeConfigsCommands(program);
+registerDatabaseTypesCommands(program);
 registerGuidesCommands(program);
 registerDocumentsCommands(program);
+registerEmailTemplatesCommands(program);
+registerCollectionsCommands(program);
+registerCollectionTypeConfigsCommands(program);
+registerSkillCommands(program);
+registerSecretsCommands(program);
+registerBlobBucketsCommands(program);
 // Global error handler
 program.hook("preAction", () => {
     // Reset API client state before each command
 });
+// Commands that should never show post-command messages (update check, skill status)
+const suppressPostMessages = isJsonOutput || subcommand === "token";
+async function runPostCommandMessages() {
+    if (suppressPostMessages)
+        return;
+    // Claude Code skill: auto-update if installed, or show hint if not.
+    // Skip for `init` (handles its own prompt), `skill` (explicit management),
+    // and non-interactive contexts (--json, --version, token, etc.).
+    if (!skipHeader && subcommand !== "skill" && subcommand !== "init") {
+        await checkSkillStatus();
+    }
+    await checkForUpdate(pkg.version);
+}
 // Parse and execute
-program.parseAsync(process.argv).catch((err) => {
+program.parseAsync(process.argv)
+    .then(async () => {
+    await runPostCommandMessages();
+})
+    .catch(async (err) => {
+    // Commander throws CommanderError for help display, version flag, etc.
+    // Run post-command messages then exit with the intended code.
+    if (err instanceof CommanderError) {
+        await runPostCommandMessages();
+        process.exit(err.exitCode);
+    }
     if (err instanceof ApiError) {
         error(err.message);
         if (err.statusCode === 401) {
             error("Try running 'primitive login' to authenticate.");
         }
+        await runPostCommandMessages();
         process.exit(err.statusCode === 401 ? 2 : 1);
     }
-    else {
-        error(err.message || "An unexpected error occurred");
-        process.exit(1);
-    }
+    error(err.message || "An unexpected error occurred");
+    await runPostCommandMessages();
+    process.exit(1);
 });
 //# sourceMappingURL=primitive.js.map