primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.41

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

@@ -0,0 +1,281 @@
+---
+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 env) 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 is **project-scoped**, and project mode is **strongly preferred** for any work
+inside a repo. Each project has a `.primitive/config.json` (committed to the repo) that defines
+named environments (`dev`, `prod`, `staging`, …), where each environment binds an `apiUrl` and
+(optionally) an `appId`. Per-environment auth tokens live in `.primitive/credentials.json`
+(gitignored). There is no global "currently active app" — the active environment determines the
+server *and* the app.
+
+The legacy global fallback (`~/.primitive/credentials.json`) exists only for one-off use outside a
+project. **Inside a project, treat its absence as a setup gap to fix, not a mode to operate in.**
+
+**Before running any CLI commands**, your *first* check is whether the project is in project mode:
+
+```bash
+ls .primitive/config.json   # exists at project root or any ancestor?
+```
+
+The two branches below are not equivalent — pick the one that matches reality and follow it.
+
+### Branch A — `.primitive/config.json` exists (project mode)
+
+The active environment is resolved in this order:
+1. `--env <name>` flag on the command
+2. `PRIMITIVE_ENV` environment variable
+3. `defaultEnvironment` in `.primitive/config.json`
+4. The sole environment, if exactly one is defined
+
+Confirm you're targeting the correct environment:
+
+1. **Read the CLI header.** Every command prints `Env | App | Server` at the top of its output —
+   verify these match the project's intended target.
+2. **Inspect the project config:**
+
+   ```bash
+   primitive env list           # All environments (default marked with *)
+   primitive env show           # Details for the currently-resolved env
+   primitive whoami             # Authenticated user + resolved server/app
+   ```
+
+**To switch environments** for a one-off command, pass `--env <name>`. To change the project
+default, run `primitive env use <name>`. To switch the *app* an env points at, edit the env's
+`appId` in `.primitive/config.json` (or re-run `primitive env add`). `primitive use <app>` is a
+no-op when the active env already pins an `appId`.
+
+### Branch B — no `.primitive/config.json` (project mode NOT set up)
+
+Without project config the CLI silently falls back to global state in `~/.primitive/credentials.json`
+(legacy mode). Commands run against whatever app/server happens to be globally active — which the
+agent didn't set and the user may have forgotten about. **This is a footgun, not a supported way to
+work inside a project.** Do not proceed silently, and do not treat the global fallback as the
+default path.
+
+**Your default action is to set up project mode.** Stop and prompt the user to create the project
+config before doing anything else. Don't bury the recommendation behind an equal-weight "or proceed
+against global state" option — make setting up project config the clear, recommended next step.
+
+First gather the context you'll propose (so the prompt is concrete, not abstract):
+
+```bash
+primitive whoami   # current global server + app, if any — shows what the fallback WOULD target
+```
+
+Then prompt the user, e.g.:
+
+> "This project has no `.primitive/config.json`, so the CLI isn't in project mode. I recommend
+> setting up project-scoped config so this repo pins its own environment instead of relying on your
+> global state (currently `<server>` / `<app from whoami>`, which I didn't set). I'll add an env
+> with:
+>
+> ```bash
+> primitive env add dev --api-url <url> --app-id <id>
+> ```
+>
+> Does this look right, or should I adjust the env name / URL / app?"
+
+If you need the user to pick the env name, server, or app, ask them. Confirm the values before
+running `env add` — but the question to resolve is *which* project config to create, not *whether*
+to create one.
+
+`primitive env add` is additive and safe — it only writes an entry to `.primitive/config.json`
+(creating the file if needed). It does not touch source code, create apps on the server, or install
+dependencies.
+
+**Only fall back to global state if the user explicitly declines project setup** after you've
+recommended it. Even then, name the exact server/app the command will hit and get clear
+confirmation before running anything mutating (`primitive sync push`, `primitive apps create`, etc.).
+A read-only command (`whoami`, `guides list`) against global state is fine while you're still
+working out the config.
+
+Do not rely on `.env` files like `PRIMITIVE_API_URL` to control CLI targeting — those are not
+read by the CLI in project mode, and the project config is the source of truth.
+
+**Why this matters:** If the CLI is pointed at the wrong environment (e.g., prod instead of dev),
+commands like `primitive sync push` will modify the wrong server. Silent fallback to global state
+makes this exact mistake easy to commit. Setting up project config is the durable fix — verify and
+surface 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.
+The `COMBINATIONS` column shows which `(language, platform)` variants each guide is available in
+(e.g. `ts; swift`). Use this output to determine which guides are relevant to the current task —
+and which language/platform variant to request in Step 2.
+
+### Determine the project's language and platform
+
+Figure out what the project you're working in targets, then request the matching variant when
+fetching guides:
+
+- A `Package.swift`, `*.xcodeproj`, or `project.yml` → `--language swift` (plus `--platform ios`
+  or `--platform macos` as appropriate).
+- A Vite/React/Node web app (`package.json`, `js-bao-wss-client`) → `--language ts --platform web`.
+
+If you can't tell, omit the flags — every guide has a default variant, so a bare
+`primitive guides get <topic>` always returns something useful.
+
+## Step 2: Fetch the Relevant Guides
+
+For each relevant topic identified in Step 1, fetch the full guide, passing the project's
+language/platform so you get the right variant:
+
+```bash
+primitive guides get <topic> --language <ts|swift> --platform <web|ios|macos>
+# or, when the project's language/platform is unknown or doesn't matter:
+primitive guides get <topic>
+```
+
+`--language` accepts aliases (`typescript`/`javascript`/`js` → `ts`). These flags **never fail**:
+an unknown value or an unavailable combination falls back to the guide's default variant rather
+than erroring, so it's always safe to pass your best guess.
+
+**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 in the requested language (e.g. TypeScript or Swift)
+- 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
+in the project's language/platform:
+```bash
+primitive guides get <topic> --language <ts|swift> --platform <web|ios|macos>
+```
+
+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 env list                 # List environments in .primitive/config.json (default marked *)
+primitive env show                 # Details for the currently-resolved env (api URL, app ID)
+primitive whoami                   # Authenticated user + resolved server/app
+
+# Switching environments
+primitive env use <name>           # Change the project's default environment
+primitive --env <name> <command>   # One-off override for a single command
+PRIMITIVE_ENV=<name> <command>     # Override via env var (useful in scripts/CI)
+
+# Setup — existing project (most common: adopting Primitive in an existing repo)
+npm install -g primitive-admin                          # Install CLI
+primitive env add dev --api-url <url> --app-id <id>     # Add env to .primitive/config.json
+primitive env add prod --api-url <url> --app-id <id>    # (creates the file if missing)
+primitive login                                         # Authenticate (tokens stored per-env)
+
+# Setup — brand-new project (greenfield only)
+primitive init my-new-app                               # Scaffolds template, creates a new app
+                                                        # on the server, runs pnpm install.
+                                                        # Do NOT run inside an existing repo.
+
+# Guides (the most important commands for development)
+primitive guides list              # See all guides: topics, descriptions, available (lang,platform) combinations
+primitive guides get <topic>       # Read a guide's default variant
+primitive guides get <topic> --language swift --platform ios   # Read a specific language/platform variant
+
+# 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 on the active env's server
+primitive apps create "Name"       # Create an app (does NOT auto-bind to an env;
+                                   # edit .primitive/config.json or use `env add` to bind)
+```
+
+## 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 active environment in
+   `.primitive/config.json` (and its bound `apiUrl` / `appId`) match the project's intended target
+   before running any commands
+2. **Run `primitive guides list`** to discover available topics and their `(language, platform)` combinations
+3. **Identify which guides are relevant** to their feature from the list output
+4. **Fetch those guides** with `primitive guides get <topic> --language <lang> --platform <platform>`
+   (using the project's language/platform; omit the flags if unknown)
+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 (and its available language/platform combinations)
+2. **Fetch the guide**: `primitive guides get <topic> --language <lang> --platform <platform>` (omit the flags if the language/platform is unknown)
+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.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/primitive.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { Command } from "commander";
-import { readFileSync } from "fs";
+import { Command, CommanderError } from "commander";
+import { readFileSync, writeSync } from "fs";
 import { fileURLToPath } from "url";
 import { dirname, resolve } from "path";
 import { registerInitCommand } from "../src/commands/init.js";
@@ -9,7 +9,11 @@ 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 { registerMetadataCommands } from "../src/commands/metadata.js";
 import { registerPromptsCommands } from "../src/commands/prompts.js";
+import { registerScriptsCommands } from "../src/commands/scripts.js";
 import { registerWorkflowsCommands } from "../src/commands/workflows.js";
 import { registerAdminsCommands } from "../src/commands/admins.js";
 import { registerCatalogCommands } from "../src/commands/catalog.js";
@@ -20,47 +24,231 @@ 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 { installGlobalCrashHandlers } from "../src/lib/crash-handlers.js";
+import { buildCliManifest } from "../src/lib/cli-manifest.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";
+import { maybeWarnLegacyMigration } from "../src/lib/migration-nag.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
+// inside an inquirer event callback when stdin isn't a usable TTY — makes Node
+// print only its bare `Node.js vX` banner and die with no message (issue #972).
+installGlobalCrashHandlers();
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const pkg = JSON.parse(readFileSync(resolve(__dirname, "../../package.json"), "utf-8"));
+/**
+ * Write a string to a file descriptor synchronously, in full, before
+ * returning. Handles two pitfalls of a single `fs.writeSync` on a pipe:
+ *  - partial writes: `writeSync` may write fewer bytes than requested (e.g.
+ *    only what fits in the OS pipe buffer), so we loop on the returned count;
+ *  - `EAGAIN` on a non-blocking fd with a slow/full consumer: retry instead of
+ *    throwing.
+ * This guarantees the whole payload reaches the kernel before the caller
+ * exits, with no dependency on the event loop draining stdout.
+ */
+function writeAllSync(fd, text) {
+    const buf = Buffer.from(text, "utf-8");
+    let offset = 0;
+    while (offset < buf.length) {
+        try {
+            offset += writeSync(fd, buf, offset, buf.length - offset);
+        }
+        catch (err) {
+            // Retry on EAGAIN (non-blocking fd, consumer not ready yet). Rethrow
+            // anything else.
+            if (err.code === "EAGAIN")
+                continue;
+            throw err;
+        }
+    }
+}
+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();
+}
+// Nudge legacy-mode users (no .primitive/config.json, but a working
+// `~/.primitive/credentials.json` + a sync marker in CWD) to migrate.
+// Wholly self-contained: rate-limited to once per 24h, opt-out via
+// PRIMITIVE_NO_MIGRATE_NAG=1, silent in CI / non-TTY. See #552.
+maybeWarnLegacyMigration({ argv: process.argv });
 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)
+
+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.
 
-Authentication:
-  Credentials are stored in ~/.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);
+registerMetadataCommands(program);
 registerPromptsCommands(program);
+registerScriptsCommands(program);
 registerWorkflowsCommands(program);
 registerAdminsCommands(program);
 registerCatalogCommands(program);
@@ -71,24 +259,88 @@ 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);
+// `primitive help --json` — machine-readable command manifest (issue #983).
+//
+// Mechanism: a pre-parse argv guard, NOT a registered `help` subcommand.
+// Commander already injects its own built-in `help [command]`; registering our
+// own would risk clobbering `primitive help <command>`. By special-casing the
+// invocation here — after every register*Commands() call so the full tree is
+// built — we serialize commander's public accessors and exit before parseAsync.
+// It is auth-free, runs offline (no project config / credentials / network),
+// and `--json` already suppresses the header, skill-status nag, and update
+// check (see `isJsonOutput` above), so stdout carries pure JSON.
+//
+// Hidden/undocumented: there is no visible `help --json` entry in human help
+// output; it's discoverable for tooling/agents that know to ask for it.
+if (process.argv[2] === "help" && process.argv.includes("--json")) {
+    // Emit the full manifest synchronously, then exit. The naive form — the
+    // async `json()` helper (`console.log`) followed by an immediate
+    // `process.exit(0)` — races the flush on the documented `primitive help
+    // --json | jq` pipe path: the ~365KB manifest far exceeds the 64KB OS pipe
+    // buffer, so exiting before the kernel drains it truncates the JSON for
+    // piped consumers.
+    //
+    // Robust fix: write to fd 1 with `fs.writeSync` in a loop. A single
+    // `writeSync` is NOT enough — on a non-blocking pipe fd it returns after a
+    // *partial* write (only what currently fits in the pipe buffer) without
+    // looping, silently dropping the tail; and on a slow consumer it can throw
+    // `EAGAIN`. Looping over the returned byte count and retrying on `EAGAIN`
+    // guarantees every byte is handed to the kernel before `process.exit(0)`,
+    // independent of the event loop. Output is byte-identical to `json()`: the
+    // same `JSON.stringify(..., null, 2)` plus a single trailing newline.
+    writeAllSync(1, JSON.stringify(buildCliManifest(program, pkg.version), null, 2) + "\n");
+    process.exit(0);
+}
 // 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