@odla-ai/cli 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,9 +1,63 @@
+/**
+ * Parse CLI arguments and dispatch to the matching command — the entry point
+ * `bin.ts` invokes. `argv` defaults to `process.argv.slice(2)`; the first
+ * positional selects the command and the rest are parsed into flags (supporting
+ * `--flag value`, `--flag=value`, boolean `--flag`, `--no-flag`, and repeated
+ * flags collected into arrays).
+ *
+ * Recognized commands: `version`/`-v`/`--version` and `help`/`-h`/`--help` print
+ * and return; `init` scaffolds a project (requires `--app-id` and `--name`);
+ * `doctor` validates config offline; `capabilities` prints the responsibility
+ * boundary; `provision` runs the full provision (including optional secret
+ * rotation, local vars, and deployed secret push); `smoke` checks a live env;
+ * `setup` and `skill install` install the bundled offline runbooks for Claude
+ * Code, Codex, Cursor, Copilot, Gemini, and `AGENTS.md`-aware agents; and
+ * `secrets push` pipes the env's configured db/o11y secrets into the Worker via
+ * Wrangler (requires `--env`). Throws on an unknown command/subcommand, unsupported option, extra
+ * positional argument, missing required value, or a dispatched command error.
+ *
+ * @param argv Argument vector without the node/script prefix (default
+ *   `process.argv.slice(2)`).
+ */
 declare function runCli(argv?: string[]): Promise<void>;
 
+/** Stable, machine-readable division of work between the CLI, coding agent,
+ * human operator, and Studio. Printed by `odla-ai capabilities --json`. */
+declare const CAPABILITIES: {
+    readonly cli: readonly ["register the app and enable configured services per environment", "issue, persist, and explicitly rotate configured service credentials", "write local Worker values and push deployed Worker secrets through Wrangler stdin", "push db schema/rules and configure platform AI, auth, and deployment links", "validate config offline and smoke-test a provisioned db environment"];
+    readonly agent: readonly ["install and import the selected odla SDKs", "wrap the Worker with withObservability and choose useful telemetry", "make application-specific schema, rules, auth, UI, and migration decisions"];
+    readonly human: readonly ["approve the odla device code and one-off third-party logins", "consent to production changes with --yes", "request destructive credential rotation explicitly", "review application semantics, security findings, releases, and merges"];
+    readonly studio: readonly ["view telemetry and environment state", "perform manual credential recovery when the CLI's local shown-once copy is unavailable"];
+};
+type Output = Pick<typeof console, "log">;
+/** Print the stable responsibility boundary for humans or agent tooling. */
+declare function printCapabilities(json?: boolean, out?: Output): void;
+
 interface DoctorOptions {
     configPath: string;
     stdout?: Pick<typeof console, "log" | "error">;
 }
+/**
+ * Validate and summarize an odla project config entirely offline — no network
+ * calls and no file writes. Loads `configPath`, builds the provision plan, and
+ * resolves the schema and rules (synthesizing deny-all rules from the schema
+ * when `db.rules` is omitted and `db.defaultRules` isn't `false`), then prints a
+ * summary line for the app, envs, services, schema entity count, rules namespace
+ * count, and AI provider.
+ *
+ * It then collects warnings for the mistakes provision can't fix silently: a
+ * schema with no entities, a rules namespace with no matching entity, the `ai`
+ * service enabled without an `ai.provider`, `auth.clerk` entries that reference
+ * an unset env var (`$FOO`), an `ai.keyEnv` that isn't set (provider key upload
+ * will be skipped), and — when `o11y` is enabled — any env whose local
+ * credentials lack an ingest token. It also folds in the shared rule linter,
+ * git-tracked secret-shaped files, and wrangler config warnings. Prints `ok`
+ * when clean, otherwise the warning list. Purely advisory: never throws on
+ * warnings and never mutates anything.
+ *
+ * @param options.configPath Path to the `odla.config.mjs` to inspect.
+ * @param options.stdout Optional console-like sink (defaults to `console`).
+ */
 declare function doctor(options: DoctorOptions): Promise<void>;
 
 interface InitOptions {
@@ -17,8 +71,44 @@ interface InitOptions {
     force?: boolean;
     stdout?: Pick<typeof console, "log" | "error">;
 }
+/**
+ * Scaffold a new odla project into `rootDir` (default: cwd). Writes an
+ * `odla.config.mjs` (default name, overridable via `configPath`) plus starter
+ * `src/odla/schema.mjs` (a single `notes` entity) and `src/odla/rules.mjs`
+ * (deny-all), and creates the `src/odla` and `.odla` directories. Also runs
+ * `ensureGitignore` so the local token/credentials paths are ignored.
+ *
+ * Fully local and synchronous — no network calls. The config file is only
+ * written when it doesn't already exist unless `force` is set (otherwise it
+ * throws); the schema/rules files are written only when missing (never
+ * overwritten, even with `force`). `appId` must match `^[a-z0-9][a-z0-9-]*$` or
+ * it throws. Defaults: `envs` → `["dev"]`, `services` → `["db","ai"]`,
+ * `aiProvider` → `"anthropic"` (which also picks the `keyEnv`, e.g.
+ * `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`/`GOOGLE_API_KEY`).
+ *
+ * @param options.appId Slug for the app (lowercase alphanumerics and hyphens).
+ * @param options.name Human-readable app name embedded in the config.
+ * @param options.rootDir Project root (defaults to `process.cwd()`).
+ * @param options.configPath Config filename relative to root (default `odla.config.mjs`).
+ * @param options.envs Environment names (default `["dev"]`; production is an explicit opt-in).
+ * @param options.services Enabled services (default `["db","ai"]`).
+ * @param options.aiProvider AI provider slug (default `"anthropic"`).
+ * @param options.force Overwrite an existing config file instead of throwing.
+ * @param options.stdout Optional console-like sink (defaults to `console`).
+ */
 declare function initProject(options: InitOptions): void;
 
+interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Subprocess seam: injectable in tests, `defaultRunner` in production. */
+type CommandRunner = (cmd: string, args: string[], opts?: {
+    input?: string;
+    cwd?: string;
+}) => Promise<RunResult>;
+
 type OdlaEnvName = string;
 type AppRules = Record<string, {
     view?: string;
@@ -31,6 +121,7 @@ interface ClerkAuthConfig {
     audience?: string;
     mode?: "client" | "full";
 }
+/** Authored `odla.config.mjs` contract consumed by doctor and provision. */
 interface OdlaProjectConfig {
     platformUrl?: string;
     dbEndpoint?: string;
@@ -77,6 +168,7 @@ interface OdlaProjectConfig {
         gitignore?: boolean;
     };
 }
+/** Normalized project config with resolved paths, endpoints, envs, and services. */
 interface LoadedProjectConfig extends OdlaProjectConfig {
     configPath: string;
     rootDir: string;
@@ -91,6 +183,7 @@ interface LoadedProjectConfig extends OdlaProjectConfig {
         gitignore: boolean;
     };
 }
+/** Private mode-0600 local state written by provision and never committed. */
 interface LocalCredentials {
     appId: string;
     platformUrl: string;
@@ -102,10 +195,15 @@ interface LocalCredentials {
         o11yToken?: string;
     }>;
 }
+/** Controls one dev-first provisioning run; production mutation requires `yes`. */
 interface ProvisionOptions {
     configPath: string;
     dryRun?: boolean;
     rotateKeys?: boolean;
+    /** Rotate only the o11y ingest token; leaves db keys unchanged. */
+    rotateO11yToken?: boolean;
+    /** Push configured Worker secrets to every configured env after provisioning. */
+    pushSecrets?: boolean;
     writeCredentials?: boolean;
     writeDevVars?: string | boolean;
     token?: string;
@@ -115,10 +213,14 @@ interface ProvisionOptions {
     interactive?: boolean;
     /** Test/embedding override for opening the approval URL. Defaults to the OS browser opener. */
     openApprovalUrl?: (url: string) => Promise<void>;
+    /** Explicit consent for a non-dry-run plan containing `prod` or `production`. */
     yes?: boolean;
     fetch?: typeof fetch;
+    /** Test/embedding override for Wrangler subprocesses used by `pushSecrets`. */
+    secretRunner?: CommandRunner;
     stdout?: Pick<typeof console, "log" | "error">;
 }
+/** Human-reviewable, secret-free plan printed by `provision({ dryRun: true })`. */
 interface ProvisionPlan {
     appId: string;
     appName: string;
@@ -130,6 +232,7 @@ interface ProvisionPlan {
     hasRules: boolean;
     aiProvider?: string;
 }
+/** Inputs for a read-only live environment smoke check. */
 interface SmokeOptions {
     configPath: string;
     env?: string;
@@ -137,21 +240,50 @@ interface SmokeOptions {
     stdout?: Pick<typeof console, "log" | "error">;
 }
 
+/**
+ * Provision an app end-to-end from its config — the primary deploy path, and
+ * (apart from key rotation) idempotent, so re-running is safe. Obtains a
+ * developer token, creates the registry app when absent, enables each service
+ * per env (AI also gets `setAi` with the configured provider/model), configures
+ * Clerk auth and links, then per env mints or reuses credentials only for the
+ * configured services, pushes the schema with the db key and the
+ * rules with the developer token, and stores the provider key in the tenant
+ * vault when `ai.keyEnv` is set and present. Finally writes the credentials file
+ * (mode 0600, gitignored) and, when requested, `.dev.vars`.
+ *
+ * The developer token comes from (in order) `options.token`, `$ODLA_DEV_TOKEN`,
+ * the cached `.odla` token, or a fresh device handshake — which prints a user
+ * code + approval URL and, in interactive terminals, auto-opens the browser
+ * (`open: true`/`false` forces/suppresses it). Network error bodies pass through
+ * `redactSecrets` before display.
+ *
+ * @param options.dryRun Print the resolved plan and return before any network call/write.
+ * @param options.rotateKeys Rotate db keys and o11y tokens.
+ * @param options.rotateO11yToken Rotate only the o11y token.
+ * @param options.pushSecrets Preflight Wrangler, then push each env's configured
+ *   Worker secrets immediately after credential provisioning.
+ * @param options.writeDevVars `true`/a path writes `.dev.vars`; `writeCredentials: false` skips the creds file.
+ * @param options.yes Required for a non-dry-run plan containing `prod` or
+ *   `production`; callers must show and review `dryRun` output first.
+ * @throws When a production plan is executed without `yes`, configuration is
+ *   invalid, authorization fails, or a provisioning operation fails.
+ */
 declare function provision(options: ProvisionOptions): Promise<void>;
 
+/**
+ * Return `value` with every secret-shaped substring replaced by a `[redacted]`
+ * placeholder that keeps the identifying prefix (e.g. `sk_live_[redacted]`).
+ * Matches odla db keys (`odla_sk_`/`odla_dev_`), Clerk secret keys
+ * (`sk_live_`/`sk_test_`), OpenAI keys (`sk-`), webhook signing secrets
+ * (`whsec_`), o11y tokens (`o11y_`), GitHub tokens (`ghp_`/`gho_`/`github_pat_`),
+ * and AWS access-key ids (`AKIA…`). Clerk publishable keys (`pk_test_`/
+ * `pk_live_`) are public by design and intentionally left untouched. Used to
+ * sanitize anything the CLI echoes (notably network error bodies) before it
+ * reaches stdout/stderr. Non-matching input is returned unchanged.
+ */
 declare function redactSecrets(value: string): string;
 
-interface RunResult {
-    code: number;
-    stdout: string;
-    stderr: string;
-}
-/** Subprocess seam: injectable in tests, `defaultRunner` in production. */
-type CommandRunner = (cmd: string, args: string[], opts?: {
-    input?: string;
-    cwd?: string;
-}) => Promise<RunResult>;
-
+/** Moves locally stored configured service credentials to one Wrangler environment over stdin. */
 interface SecretsPushOptions {
     configPath: string;
     env: string;
@@ -162,37 +294,89 @@ interface SecretsPushOptions {
     stdout?: Pick<typeof console, "log" | "error">;
 }
 /**
- * Moves the env's odla-db key from `.odla/credentials.local.json` into the
- * Worker via `wrangler secret put ODLA_API_KEY`, piping the value over stdin
- * so it never appears on argv, in output, or in the conversation transcript.
+ * Moves the env's configured db and/or o11y credentials from the private local
+ * credentials file into the Worker, piping values over stdin so they never
+ * appear on argv, in output, or in the conversation transcript.
  */
 declare function secretsPush(options: SecretsPushOptions): Promise<void>;
 
+/** Agent harnesses with a first-class local adapter. */
+declare const AGENT_HARNESSES: readonly ["claude", "codex", "cursor", "copilot", "gemini", "agents"];
+/** A supported coding-agent harness. `agents` is the portable `AGENTS.md` adapter. */
+type AgentHarness = (typeof AGENT_HARNESSES)[number];
+/** A harness name accepted by setup; `all` expands to every project-local adapter. */
+type AgentHarnessSelector = AgentHarness | "all";
+/** Controls project-local or global installation of the bundled agent runbooks. */
 interface SkillInstallOptions {
-    /** Project directory receiving `.claude/skills/`. Defaults to cwd. Ignored with `global`. */
+    /** Project directory receiving the shared runbooks and harness adapters. Defaults to cwd. */
     dir?: string;
-    /** Install into `~/.claude/skills/` instead of the project. */
+    /** Install user-wide Claude and/or Codex skills instead of project adapters. */
     global?: boolean;
-    /** Overwrite locally modified skill files. */
+    /** Harnesses to install. The programmatic compatibility default is `claude`; the CLI passes `all`. */
+    harnesses?: AgentHarnessSelector[];
+    /** Overwrite locally modified odla-managed files or managed instruction sections. */
     force?: boolean;
     /** Test/embedding override for the home directory. */
     homeDir?: string;
+    /** Test/embedding override for `$CODEX_HOME`. */
+    codexHomeDir?: string;
     /** Test/embedding override for the bundled skills directory. */
     sourceDir?: string;
     stdout?: Pick<typeof console, "log" | "error">;
 }
+/** One harness adapter and the directories or files through which it discovers odla. */
+interface HarnessInstallResult {
+    harness: AgentHarness;
+    targets: string[];
+}
+/** Files written or left unchanged by an idempotent agent-runbook installation. */
 interface SkillInstallResult {
+    /** Primary native skill directory, retained for compatibility with earlier callers. */
     targetDir: string;
+    /** Files changed directly under `targetDir`, relative to that directory. */
     written: string[];
+    /** Files already current directly under `targetDir`, relative to that directory. */
     unchanged: string[];
+    /** Absolute paths of every changed shared-runbook or adapter file. */
+    writtenPaths: string[];
+    /** Absolute paths of every already-current shared-runbook or adapter file. */
+    unchangedPaths: string[];
+    harnesses: HarnessInstallResult[];
 }
 /**
- * Copies the skills bundled with this package into `.claude/skills/` so the
- * user's agent picks them up. Idempotent: unchanged files are skipped, and a
- * locally modified file is never overwritten without `force`.
+ * Installs one shared offline runbook tree plus thin native adapters for the
+ * selected coding-agent harnesses. Project installs use `.agents/skills/` as
+ * the canonical bundle; Claude Code, Cursor, Copilot, Gemini, and generic
+ * `AGENTS.md` adapters point to it. Global installs support the native Claude
+ * and Codex skill roots only.
+ *
+ * Installation is idempotent and planned before any write: an odla-managed
+ * file changed by the user aborts the whole operation unless `force` is set.
+ * Existing `AGENTS.md`, `GEMINI.md`, and Copilot instructions are preserved;
+ * only the bounded odla-managed section is appended or replaced.
  */
 declare function installSkill(options?: SkillInstallOptions): SkillInstallResult;
 
+/**
+ * Verify a live, already-provisioned environment end-to-end. Resolves the target
+ * env (`options.env`, else `dev`, else the first declared env) and requires it to
+ * be declared in the config. Reads the local credentials file and checks that it
+ * belongs to this app and holds a `tenantId` + `dbKey` for the env — otherwise it
+ * throws pointing the user at `odla-ai provision --write-dev-vars`.
+ *
+ * It then makes real network calls: fetches the registry public-config (and, when
+ * `ai.provider` is configured, asserts the live provider matches), fetches the
+ * live db schema with the db key and asserts every entity from the local schema
+ * is present, and runs a `count` aggregate against the first entity to confirm
+ * the db answers queries. Progress lines are printed and it ends with `ok`.
+ * Read-only — it writes nothing and throws on the first mismatch or failed
+ * request.
+ *
+ * @param options.configPath Path to the `odla.config.mjs`.
+ * @param options.env Env to check (default `dev`, else the first declared env).
+ * @param options.fetch Injectable `fetch` (for tests/embedding).
+ * @param options.stdout Optional console-like sink (defaults to `console`).
+ */
 declare function smoke(options: SmokeOptions): Promise<void>;
 
-export { type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type SecretsPushOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, doctor, initProject, installSkill, provision, redactSecrets, runCli, secretsPush, smoke };
+export { AGENT_HARNESSES, type AgentHarness, type AgentHarnessSelector, CAPABILITIES, type HarnessInstallResult, type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type SecretsPushOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, doctor, initProject, installSkill, printCapabilities, provision, redactSecrets, runCli, secretsPush, smoke };

package/dist/index.d.ts

@@ -1,9 +1,63 @@
+/**
+ * Parse CLI arguments and dispatch to the matching command — the entry point
+ * `bin.ts` invokes. `argv` defaults to `process.argv.slice(2)`; the first
+ * positional selects the command and the rest are parsed into flags (supporting
+ * `--flag value`, `--flag=value`, boolean `--flag`, `--no-flag`, and repeated
+ * flags collected into arrays).
+ *
+ * Recognized commands: `version`/`-v`/`--version` and `help`/`-h`/`--help` print
+ * and return; `init` scaffolds a project (requires `--app-id` and `--name`);
+ * `doctor` validates config offline; `capabilities` prints the responsibility
+ * boundary; `provision` runs the full provision (including optional secret
+ * rotation, local vars, and deployed secret push); `smoke` checks a live env;
+ * `setup` and `skill install` install the bundled offline runbooks for Claude
+ * Code, Codex, Cursor, Copilot, Gemini, and `AGENTS.md`-aware agents; and
+ * `secrets push` pipes the env's configured db/o11y secrets into the Worker via
+ * Wrangler (requires `--env`). Throws on an unknown command/subcommand, unsupported option, extra
+ * positional argument, missing required value, or a dispatched command error.
+ *
+ * @param argv Argument vector without the node/script prefix (default
+ *   `process.argv.slice(2)`).
+ */
 declare function runCli(argv?: string[]): Promise<void>;
 
+/** Stable, machine-readable division of work between the CLI, coding agent,
+ * human operator, and Studio. Printed by `odla-ai capabilities --json`. */
+declare const CAPABILITIES: {
+    readonly cli: readonly ["register the app and enable configured services per environment", "issue, persist, and explicitly rotate configured service credentials", "write local Worker values and push deployed Worker secrets through Wrangler stdin", "push db schema/rules and configure platform AI, auth, and deployment links", "validate config offline and smoke-test a provisioned db environment"];
+    readonly agent: readonly ["install and import the selected odla SDKs", "wrap the Worker with withObservability and choose useful telemetry", "make application-specific schema, rules, auth, UI, and migration decisions"];
+    readonly human: readonly ["approve the odla device code and one-off third-party logins", "consent to production changes with --yes", "request destructive credential rotation explicitly", "review application semantics, security findings, releases, and merges"];
+    readonly studio: readonly ["view telemetry and environment state", "perform manual credential recovery when the CLI's local shown-once copy is unavailable"];
+};
+type Output = Pick<typeof console, "log">;
+/** Print the stable responsibility boundary for humans or agent tooling. */
+declare function printCapabilities(json?: boolean, out?: Output): void;
+
 interface DoctorOptions {
     configPath: string;
     stdout?: Pick<typeof console, "log" | "error">;
 }
+/**
+ * Validate and summarize an odla project config entirely offline — no network
+ * calls and no file writes. Loads `configPath`, builds the provision plan, and
+ * resolves the schema and rules (synthesizing deny-all rules from the schema
+ * when `db.rules` is omitted and `db.defaultRules` isn't `false`), then prints a
+ * summary line for the app, envs, services, schema entity count, rules namespace
+ * count, and AI provider.
+ *
+ * It then collects warnings for the mistakes provision can't fix silently: a
+ * schema with no entities, a rules namespace with no matching entity, the `ai`
+ * service enabled without an `ai.provider`, `auth.clerk` entries that reference
+ * an unset env var (`$FOO`), an `ai.keyEnv` that isn't set (provider key upload
+ * will be skipped), and — when `o11y` is enabled — any env whose local
+ * credentials lack an ingest token. It also folds in the shared rule linter,
+ * git-tracked secret-shaped files, and wrangler config warnings. Prints `ok`
+ * when clean, otherwise the warning list. Purely advisory: never throws on
+ * warnings and never mutates anything.
+ *
+ * @param options.configPath Path to the `odla.config.mjs` to inspect.
+ * @param options.stdout Optional console-like sink (defaults to `console`).
+ */
 declare function doctor(options: DoctorOptions): Promise<void>;
 
 interface InitOptions {
@@ -17,8 +71,44 @@ interface InitOptions {
     force?: boolean;
     stdout?: Pick<typeof console, "log" | "error">;
 }
+/**
+ * Scaffold a new odla project into `rootDir` (default: cwd). Writes an
+ * `odla.config.mjs` (default name, overridable via `configPath`) plus starter
+ * `src/odla/schema.mjs` (a single `notes` entity) and `src/odla/rules.mjs`
+ * (deny-all), and creates the `src/odla` and `.odla` directories. Also runs
+ * `ensureGitignore` so the local token/credentials paths are ignored.
+ *
+ * Fully local and synchronous — no network calls. The config file is only
+ * written when it doesn't already exist unless `force` is set (otherwise it
+ * throws); the schema/rules files are written only when missing (never
+ * overwritten, even with `force`). `appId` must match `^[a-z0-9][a-z0-9-]*$` or
+ * it throws. Defaults: `envs` → `["dev"]`, `services` → `["db","ai"]`,
+ * `aiProvider` → `"anthropic"` (which also picks the `keyEnv`, e.g.
+ * `ANTHROPIC_API_KEY`/`OPENAI_API_KEY`/`GOOGLE_API_KEY`).
+ *
+ * @param options.appId Slug for the app (lowercase alphanumerics and hyphens).
+ * @param options.name Human-readable app name embedded in the config.
+ * @param options.rootDir Project root (defaults to `process.cwd()`).
+ * @param options.configPath Config filename relative to root (default `odla.config.mjs`).
+ * @param options.envs Environment names (default `["dev"]`; production is an explicit opt-in).
+ * @param options.services Enabled services (default `["db","ai"]`).
+ * @param options.aiProvider AI provider slug (default `"anthropic"`).
+ * @param options.force Overwrite an existing config file instead of throwing.
+ * @param options.stdout Optional console-like sink (defaults to `console`).
+ */
 declare function initProject(options: InitOptions): void;
 
+interface RunResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+/** Subprocess seam: injectable in tests, `defaultRunner` in production. */
+type CommandRunner = (cmd: string, args: string[], opts?: {
+    input?: string;
+    cwd?: string;
+}) => Promise<RunResult>;
+
 type OdlaEnvName = string;
 type AppRules = Record<string, {
     view?: string;
@@ -31,6 +121,7 @@ interface ClerkAuthConfig {
     audience?: string;
     mode?: "client" | "full";
 }
+/** Authored `odla.config.mjs` contract consumed by doctor and provision. */
 interface OdlaProjectConfig {
     platformUrl?: string;
     dbEndpoint?: string;
@@ -77,6 +168,7 @@ interface OdlaProjectConfig {
         gitignore?: boolean;
     };
 }
+/** Normalized project config with resolved paths, endpoints, envs, and services. */
 interface LoadedProjectConfig extends OdlaProjectConfig {
     configPath: string;
     rootDir: string;
@@ -91,6 +183,7 @@ interface LoadedProjectConfig extends OdlaProjectConfig {
         gitignore: boolean;
     };
 }
+/** Private mode-0600 local state written by provision and never committed. */
 interface LocalCredentials {
     appId: string;
     platformUrl: string;
@@ -102,10 +195,15 @@ interface LocalCredentials {
         o11yToken?: string;
     }>;
 }
+/** Controls one dev-first provisioning run; production mutation requires `yes`. */
 interface ProvisionOptions {
     configPath: string;
     dryRun?: boolean;
     rotateKeys?: boolean;
+    /** Rotate only the o11y ingest token; leaves db keys unchanged. */
+    rotateO11yToken?: boolean;
+    /** Push configured Worker secrets to every configured env after provisioning. */
+    pushSecrets?: boolean;
     writeCredentials?: boolean;
     writeDevVars?: string | boolean;
     token?: string;
@@ -115,10 +213,14 @@ interface ProvisionOptions {
     interactive?: boolean;
     /** Test/embedding override for opening the approval URL. Defaults to the OS browser opener. */
     openApprovalUrl?: (url: string) => Promise<void>;
+    /** Explicit consent for a non-dry-run plan containing `prod` or `production`. */
     yes?: boolean;
     fetch?: typeof fetch;
+    /** Test/embedding override for Wrangler subprocesses used by `pushSecrets`. */
+    secretRunner?: CommandRunner;
     stdout?: Pick<typeof console, "log" | "error">;
 }
+/** Human-reviewable, secret-free plan printed by `provision({ dryRun: true })`. */
 interface ProvisionPlan {
     appId: string;
     appName: string;
@@ -130,6 +232,7 @@ interface ProvisionPlan {
     hasRules: boolean;
     aiProvider?: string;
 }
+/** Inputs for a read-only live environment smoke check. */
 interface SmokeOptions {
     configPath: string;
     env?: string;
@@ -137,21 +240,50 @@ interface SmokeOptions {
     stdout?: Pick<typeof console, "log" | "error">;
 }
 
+/**
+ * Provision an app end-to-end from its config — the primary deploy path, and
+ * (apart from key rotation) idempotent, so re-running is safe. Obtains a
+ * developer token, creates the registry app when absent, enables each service
+ * per env (AI also gets `setAi` with the configured provider/model), configures
+ * Clerk auth and links, then per env mints or reuses credentials only for the
+ * configured services, pushes the schema with the db key and the
+ * rules with the developer token, and stores the provider key in the tenant
+ * vault when `ai.keyEnv` is set and present. Finally writes the credentials file
+ * (mode 0600, gitignored) and, when requested, `.dev.vars`.
+ *
+ * The developer token comes from (in order) `options.token`, `$ODLA_DEV_TOKEN`,
+ * the cached `.odla` token, or a fresh device handshake — which prints a user
+ * code + approval URL and, in interactive terminals, auto-opens the browser
+ * (`open: true`/`false` forces/suppresses it). Network error bodies pass through
+ * `redactSecrets` before display.
+ *
+ * @param options.dryRun Print the resolved plan and return before any network call/write.
+ * @param options.rotateKeys Rotate db keys and o11y tokens.
+ * @param options.rotateO11yToken Rotate only the o11y token.
+ * @param options.pushSecrets Preflight Wrangler, then push each env's configured
+ *   Worker secrets immediately after credential provisioning.
+ * @param options.writeDevVars `true`/a path writes `.dev.vars`; `writeCredentials: false` skips the creds file.
+ * @param options.yes Required for a non-dry-run plan containing `prod` or
+ *   `production`; callers must show and review `dryRun` output first.
+ * @throws When a production plan is executed without `yes`, configuration is
+ *   invalid, authorization fails, or a provisioning operation fails.
+ */
 declare function provision(options: ProvisionOptions): Promise<void>;
 
+/**
+ * Return `value` with every secret-shaped substring replaced by a `[redacted]`
+ * placeholder that keeps the identifying prefix (e.g. `sk_live_[redacted]`).
+ * Matches odla db keys (`odla_sk_`/`odla_dev_`), Clerk secret keys
+ * (`sk_live_`/`sk_test_`), OpenAI keys (`sk-`), webhook signing secrets
+ * (`whsec_`), o11y tokens (`o11y_`), GitHub tokens (`ghp_`/`gho_`/`github_pat_`),
+ * and AWS access-key ids (`AKIA…`). Clerk publishable keys (`pk_test_`/
+ * `pk_live_`) are public by design and intentionally left untouched. Used to
+ * sanitize anything the CLI echoes (notably network error bodies) before it
+ * reaches stdout/stderr. Non-matching input is returned unchanged.
+ */
 declare function redactSecrets(value: string): string;
 
-interface RunResult {
-    code: number;
-    stdout: string;
-    stderr: string;
-}
-/** Subprocess seam: injectable in tests, `defaultRunner` in production. */
-type CommandRunner = (cmd: string, args: string[], opts?: {
-    input?: string;
-    cwd?: string;
-}) => Promise<RunResult>;
-
+/** Moves locally stored configured service credentials to one Wrangler environment over stdin. */
 interface SecretsPushOptions {
     configPath: string;
     env: string;
@@ -162,37 +294,89 @@ interface SecretsPushOptions {
     stdout?: Pick<typeof console, "log" | "error">;
 }
 /**
- * Moves the env's odla-db key from `.odla/credentials.local.json` into the
- * Worker via `wrangler secret put ODLA_API_KEY`, piping the value over stdin
- * so it never appears on argv, in output, or in the conversation transcript.
+ * Moves the env's configured db and/or o11y credentials from the private local
+ * credentials file into the Worker, piping values over stdin so they never
+ * appear on argv, in output, or in the conversation transcript.
  */
 declare function secretsPush(options: SecretsPushOptions): Promise<void>;
 
+/** Agent harnesses with a first-class local adapter. */
+declare const AGENT_HARNESSES: readonly ["claude", "codex", "cursor", "copilot", "gemini", "agents"];
+/** A supported coding-agent harness. `agents` is the portable `AGENTS.md` adapter. */
+type AgentHarness = (typeof AGENT_HARNESSES)[number];
+/** A harness name accepted by setup; `all` expands to every project-local adapter. */
+type AgentHarnessSelector = AgentHarness | "all";
+/** Controls project-local or global installation of the bundled agent runbooks. */
 interface SkillInstallOptions {
-    /** Project directory receiving `.claude/skills/`. Defaults to cwd. Ignored with `global`. */
+    /** Project directory receiving the shared runbooks and harness adapters. Defaults to cwd. */
     dir?: string;
-    /** Install into `~/.claude/skills/` instead of the project. */
+    /** Install user-wide Claude and/or Codex skills instead of project adapters. */
     global?: boolean;
-    /** Overwrite locally modified skill files. */
+    /** Harnesses to install. The programmatic compatibility default is `claude`; the CLI passes `all`. */
+    harnesses?: AgentHarnessSelector[];
+    /** Overwrite locally modified odla-managed files or managed instruction sections. */
     force?: boolean;
     /** Test/embedding override for the home directory. */
     homeDir?: string;
+    /** Test/embedding override for `$CODEX_HOME`. */
+    codexHomeDir?: string;
     /** Test/embedding override for the bundled skills directory. */
     sourceDir?: string;
     stdout?: Pick<typeof console, "log" | "error">;
 }
+/** One harness adapter and the directories or files through which it discovers odla. */
+interface HarnessInstallResult {
+    harness: AgentHarness;
+    targets: string[];
+}
+/** Files written or left unchanged by an idempotent agent-runbook installation. */
 interface SkillInstallResult {
+    /** Primary native skill directory, retained for compatibility with earlier callers. */
     targetDir: string;
+    /** Files changed directly under `targetDir`, relative to that directory. */
     written: string[];
+    /** Files already current directly under `targetDir`, relative to that directory. */
     unchanged: string[];
+    /** Absolute paths of every changed shared-runbook or adapter file. */
+    writtenPaths: string[];
+    /** Absolute paths of every already-current shared-runbook or adapter file. */
+    unchangedPaths: string[];
+    harnesses: HarnessInstallResult[];
 }
 /**
- * Copies the skills bundled with this package into `.claude/skills/` so the
- * user's agent picks them up. Idempotent: unchanged files are skipped, and a
- * locally modified file is never overwritten without `force`.
+ * Installs one shared offline runbook tree plus thin native adapters for the
+ * selected coding-agent harnesses. Project installs use `.agents/skills/` as
+ * the canonical bundle; Claude Code, Cursor, Copilot, Gemini, and generic
+ * `AGENTS.md` adapters point to it. Global installs support the native Claude
+ * and Codex skill roots only.
+ *
+ * Installation is idempotent and planned before any write: an odla-managed
+ * file changed by the user aborts the whole operation unless `force` is set.
+ * Existing `AGENTS.md`, `GEMINI.md`, and Copilot instructions are preserved;
+ * only the bounded odla-managed section is appended or replaced.
  */
 declare function installSkill(options?: SkillInstallOptions): SkillInstallResult;
 
+/**
+ * Verify a live, already-provisioned environment end-to-end. Resolves the target
+ * env (`options.env`, else `dev`, else the first declared env) and requires it to
+ * be declared in the config. Reads the local credentials file and checks that it
+ * belongs to this app and holds a `tenantId` + `dbKey` for the env — otherwise it
+ * throws pointing the user at `odla-ai provision --write-dev-vars`.
+ *
+ * It then makes real network calls: fetches the registry public-config (and, when
+ * `ai.provider` is configured, asserts the live provider matches), fetches the
+ * live db schema with the db key and asserts every entity from the local schema
+ * is present, and runs a `count` aggregate against the first entity to confirm
+ * the db answers queries. Progress lines are printed and it ends with `ok`.
+ * Read-only — it writes nothing and throws on the first mismatch or failed
+ * request.
+ *
+ * @param options.configPath Path to the `odla.config.mjs`.
+ * @param options.env Env to check (default `dev`, else the first declared env).
+ * @param options.fetch Injectable `fetch` (for tests/embedding).
+ * @param options.stdout Optional console-like sink (defaults to `console`).
+ */
 declare function smoke(options: SmokeOptions): Promise<void>;
 
-export { type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type SecretsPushOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, doctor, initProject, installSkill, provision, redactSecrets, runCli, secretsPush, smoke };
+export { AGENT_HARNESSES, type AgentHarness, type AgentHarnessSelector, CAPABILITIES, type HarnessInstallResult, type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type SecretsPushOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, doctor, initProject, installSkill, printCapabilities, provision, redactSecrets, runCli, secretsPush, smoke };