@odla-ai/cli 0.4.0 → 0.6.0

package/llms.txt

@@ -1,16 +1,19 @@
 # @odla-ai/cli — LLM context
 
-> Project-neutral CLI for provisioning odla apps, database schemas, AI settings, and local runtime files.
+> Agent-operable CLI for odla provisioning, scoped System AI administration, hosted security runs, Worker secrets, and smoke checks.
 
-> ⚠️ **Experimental — an agentic-coding experiment.** This package is built and
-> operated by autonomous coding agents as an experiment in agentic loops. APIs
-> change without notice and nothing here is production-hardened. **Use at your
-> own risk.**
+> ⚠️ **Early access — pre-1.0.** Agents work from bounded runbooks; humans
+> approve credentials, production changes, releases, and merges. APIs and exact
+> package availability can change. Review the documented guarantees and
+> limitations; this software is MIT-licensed and provided without warranty.
 
 Project-neutral provisioning CLI for odla apps. It creates and validates an
 `odla.config.mjs`, then uses that config to register an app, enable services,
-push odla-db schema/rules, configure platform AI, configure Clerk auth, record
-deployment links, and write local runtime credentials.
+push odla-db schema/rules, configure per-app BYOK AI, configure Clerk auth, record
+deployment links, provision o11y ingest credentials, and transfer local or
+deployed Worker secrets without printing them. It also gives platform admins a
+scoped System AI control surface and gives app owners a provider-key-free
+hosted security command.
 
 It does not know about any specific app. App identity, environments, services,
 schema, rules, auth, AI provider, and links all come from config.
@@ -28,7 +31,8 @@ For a project you keep working in, install it as a dev dependency so the
 shorter `npx odla-ai` form works and the version is pinned by your lockfile:
 
 ```bash
-npm i -D @odla-ai/cli
+npm view @odla-ai/cli@0.6.0 version
+npm i -D --save-exact @odla-ai/cli@0.6.0
 ```
 
 ## Prerequisites
@@ -48,12 +52,20 @@ npm i -D @odla-ai/cli
 ## Commands
 
 ```bash
+npx odla-ai setup
 npx odla-ai init --app-id my-app --name "My App"
 npx odla-ai doctor
+npx odla-ai capabilities --json
+# install SDKs, write the Worker, and create wrangler.jsonc before secret push
 npx odla-ai provision --dry-run
-npx odla-ai provision --write-dev-vars
+npx odla-ai provision --write-dev-vars --push-secrets
 npx odla-ai smoke --env dev
 npx odla-ai secrets push --env dev
+npx odla-ai security run . --env dev --ack-redacted-source
+npx odla-ai admin ai show
+npx odla-ai admin ai set security.discovery --provider anthropic --model claude-opus-4-8 --enabled
+npx odla-ai admin ai credentials
+npx odla-ai admin ai credential set anthropic --from-env ANTHROPIC_API_KEY
 npx odla-ai skill install
 npx odla-ai version
 ```
@@ -65,8 +77,16 @@ npx odla-ai version
 - `src/odla/rules.mjs`
 - `.gitignore` entries for local credentials
 
+New configs contain only the `dev` environment. Add `prod` explicitly after
+the development flow is healthy; `provision` refuses to mutate `prod` or
+`production` without `--yes` and supports `--dry-run` for review.
+
 `provision` performs the standard safe setup flow:
 
+When using `--push-secrets`, create the Worker and its Wrangler config first.
+The CLI checks that config and `wrangler whoami` before it issues or rotates a
+shown-once credential.
+
 1. Gets an `odla_dev_...` token by device handshake, or reuses
    `ODLA_DEV_TOKEN` / `.odla/dev-token.json`.
    In an interactive terminal it opens the approval page in your browser when
@@ -75,14 +95,28 @@ npx odla-ai version
    best-effort; the printed URL and code always remain the fallback.
 2. Creates the platform app if needed.
 3. Enables configured services in every configured environment.
-4. Mints or reuses each env's odla-db app key.
+4. Mints or reuses each env's configured service credentials: an odla-db app
+   key for `db` and an ingest token for `o11y`.
 5. Pushes the configured schema and rules.
 6. Configures platform AI and stores provider keys in the tenant vault when the
    configured key env var is set.
 7. Writes `.odla/credentials.local.json` with mode `0600`.
-
-Pass `--rotate-keys` to mint fresh db keys. Pass `--no-write-credentials` to
-skip writing the local credentials file.
+8. With `--write-dev-vars`, writes the local Worker values to `.dev.vars`; with
+   `--push-secrets`, transfers the configured service secrets to the matching
+   deployed Worker environment over Wrangler stdin.
+
+Plain reruns are idempotent. Pass `--rotate-o11y-token` only when deliberately
+invalidating and replacing the o11y token; combine it with `--push-secrets` so
+the replacement reaches the Worker in the same run. `--rotate-keys` remains the
+broader credential rotation. Production mutation or secret transfer requires
+`--yes`. Pass `--no-write-credentials` to skip writing the local credentials
+file; it cannot be combined with an operation that would issue a shown-once
+credential.
+
+Rotation and Wrangler secret replacement are not a distributed transaction.
+The CLI preflights Wrangler first and persists the replacement before pushing;
+if that final push still fails, follow the printed `secrets push --env ...`
+retry. Do not run the rotation flag again.
 
 `smoke` verifies a provisioned environment from local credentials. It fetches
 the platform public config, checks the configured AI provider, fetches the live
@@ -90,23 +124,82 @@ odla-db schema with the tenant key, compares expected schema entities, and runs
 a count aggregate against the first entity. It fails early with a clear message
 when provisioning has not written `.odla/credentials.local.json`.
 
-`secrets push --env <env>` moves the env's odla-db key from
-`.odla/credentials.local.json` into the deployed Worker by piping it over
-stdin to `wrangler secret put ODLA_API_KEY` — the value never appears on
-argv, in output, or in an agent's transcript. It preflights `wrangler whoami`
-and the presence of a wrangler config file. The env `prod`/`production`
-targets the top-level wrangler environment (no `--env` flag is passed to
-wrangler) and requires `--yes`; every other env maps to wrangler's
-`--env <name>`. `--dry-run` prints a redacted plan without spawning anything.
-
-`skill install` copies the Claude Code skills bundled with this package
-(currently `odla-migrate`, the phased GitHub Pages → odla migration
-procedure) into the project's `.claude/skills/`, or into `~/.claude/skills/`
-with `--global`. Re-runs are idempotent; a locally modified skill file is
-never overwritten without `--force`. The skill's reference runbook is served
-at <https://odla.ai/llms-migrate.txt>; the human companion — "Moving your site
-to odla" (accounts, the approval code, costs) — lives in the odla docs after
-sign-in.
+The bundled build/migration skills add a passive pre-ship gate with
+`@odla-ai/security`: after the exact-version availability check, run
+`npm i -D --save-exact @odla-ai/security@0.2.0`, then
+`npx odla-security scan . --profile odla --out .odla/security/pre-ship --fail-on high --fail-on-candidates critical`.
+The passive scan remains a separate binary: it makes no model calls and does
+not execute target code. After explicit redacted-source approval,
+`odla-ai security run . --env dev --ack-redacted-source` adds hosted discovery
+and independent validation. The CLI obtains/reuses app-owner auth and the
+platform supplies bounded role grants; it never requests provider keys.
+Early-access run ceilings are rolling; a `429` includes the platform's safe
+retry hint, which the CLI surfaces without echoing arbitrary response text.
+Before installing the exact release, require
+`npm view @odla-ai/security@0.2.0 version` to succeed before installation. An
+exact-version `E404` means the release is unavailable, not that the security
+preflight passed, and does not prove the package name is absent. odla's own
+engineering environment uses an equivalent internal gate; customer projects
+should use the published `odla-security` command above.
+
+`admin ai show|set|credentials|credential set` manages platform-funded System
+AI (`o11y.triage`, `security.discovery`, `security.validation`). It uses a
+separate, mode-`0600` `.odla/admin-token.local.json` cache. Studio displays the
+exact scope, only an admin can approve it, and it expires after ~15 minutes;
+the token never becomes ambient admin. Credential writes accept only
+`--from-env <NAME>` or `--stdin` and never place the value in argv, output, or
+the cache. System AI and each app's BYOK AI are separate vault/funding paths.
+
+`secrets push --env <env>` is the narrower recovery/retry command. It moves the
+configured env's odla-db key and/or o11y ingest token from
+`.odla/credentials.local.json` into the deployed Worker by piping each value
+over stdin to `wrangler secret put`; values never appear on argv, in output, or
+in an agent's transcript. It preflights `wrangler whoami` and the presence of a
+wrangler config file. The env `prod`/`production` targets the top-level
+wrangler environment (no `--env` flag is passed to Wrangler) and requires
+`--yes`; every other env maps to `wrangler --env <name>`. `--dry-run` prints a
+redacted plan without spawning anything. For the normal path, use
+`provision --write-dev-vars --push-secrets` so service enablement, credential
+issuance, local config, and deployed secret transfer stay one composition.
+
+## Who does what
+
+If a change is deterministic from `odla.config.mjs`, the CLI owns it: app and
+service enablement, credential issuance and local persistence, `.dev.vars`,
+schema/rules/auth/AI configuration, and Wrangler secret transfer. The coding
+agent owns application semantics: installing `@odla-ai/o11y`, wrapping the
+Worker with `withObservability`, and choosing useful spans, metrics, errors, and
+LLM-usage records. The human owns the device approval, production consent, and
+explicit destructive rotation. Studio is where people view telemetry and
+perform manual recovery, configure System AI, and inspect app/run-attributed
+platform usage; its o11y token control is not the normal setup path.
+Run `npx odla-ai capabilities` for the human-readable contract or add `--json`
+when an agent or tool needs to branch on it without scraping prose.
+
+`setup` (and `skill install`) installs one complete offline runbook bundle at
+`.agents/skills/`, then adds thin native adapters for Claude Code
+(`.claude/skills/`), Codex, Cursor (`.cursor/rules/`), GitHub Copilot
+(`.github/copilot-instructions.md`), Gemini CLI (`GEMINI.md`), and portable
+`AGENTS.md` agents. The default is `--agent all`; select one or more with
+`--agent claude,codex` or repeated `--agent` flags. A global install supports
+the native Claude and Codex roots only.
+
+Existing `AGENTS.md`, `GEMINI.md`, and Copilot instructions are preserved. The
+installer appends a bounded odla-managed section, is idempotent, refuses
+symlink-redirection and locally changed managed content, and lets `--force`
+replace only odla-owned content. The local bundle includes build, migration,
+and observability-debug procedures plus every reference they need; agents do
+not need online docs or access to odla's private service source after setup.
+
+After running setup, the whole prompt can be: “Set up odla in this repo using
+the installed local odla runbook. Decide whether this is a new app or an
+existing site to migrate, then drive it end to end. Ask me only for the device
+approval and other human-only checkpoints.”
+
+For programmatic callers, `installSkill()` keeps `targetDir`, `written`, and
+`unchanged` as one unambiguous primary-root view: the latter two contain paths
+relative to `targetDir` only. Use the additive absolute `writtenPaths` and
+`unchangedPaths` fields to inspect every shared-bundle and adapter artifact.
 
 `doctor` also lints for common footguns: permission rules that are literally
 `"true"` (public writes always warn; a public `view` warns unless the
@@ -124,8 +217,8 @@ export default {
   platformUrl: process.env.ODLA_PLATFORM_URL ?? "https://odla.ai",
   dbEndpoint: process.env.ODLA_ENDPOINT ?? process.env.ODLA_DB_ENDPOINT ?? "https://db.odla.ai",
   app: { id: "my-app", name: "My App" },
-  envs: ["prod", "dev"],
-  services: ["db", "ai"],
+  envs: ["dev"], // add "prod" deliberately; provisioning it requires --yes
+  services: ["db", "ai", "o11y"],
   db: {
     schema: "./src/odla/schema.mjs",
     rules: "./src/odla/rules.mjs",
@@ -137,6 +230,8 @@ export default {
     keyEnv: "ANTHROPIC_API_KEY",
   },
   auth: {
+    // Publishable key (public). Created + pulled by the Clerk CLI (`npx clerk`);
+    // See the installed odla-migrate phase 3. Inline `pk_…` or "$ENV_VAR".
     clerk: {
       dev: "$CLERK_PUBLISHABLE_KEY",
       prod: "$CLERK_PUBLISHABLE_KEY",
@@ -156,15 +251,123 @@ If schema is present and rules are omitted, `defaultRules: "deny"` generates
 deny-all rules for every schema entity. That is the safe default for Workers
 that mediate reads and writes with an app key.
 
-## API reference (generated from dist/index.d.ts, v0.4.0)
+## API reference (generated from dist/index.d.ts, v0.6.0)
 
 ```ts
+import { SecurityReport, PlatformSecurityRun } from '@odla-ai/security';
+
+/**
+ * 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; `admin ai` reads/updates purpose-specific platform AI policies and
+ * write-only credentials through a short-lived exact-scope device grant;
+ * `security run` performs an explicitly acknowledged, app-attributed hosted
+ * reasoning pass; `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>;
 
+/** Hosted platform purposes whose provider, model, and budgets an admin may route. */
+declare const SYSTEM_AI_PURPOSES: readonly ["o11y.triage", "security.discovery", "security.validation"];
+/** One catalog-validated, platform-funded System AI purpose. */
+type SystemAiPurpose = (typeof SYSTEM_AI_PURPOSES)[number];
+/** Inputs for one System AI read, policy update, credential-status read, or
+ * write-only credential transfer. Provider values may come only from a named
+ * environment variable or stdin. */
+interface AdminAiOptions {
+    action: "show" | "set" | "credentials" | "credential-set";
+    purpose?: string;
+    provider?: string;
+    model?: string;
+    enabled?: boolean;
+    maxInputBytes?: number;
+    maxOutputTokens?: number;
+    maxCallsPerRun?: number;
+    platform?: string;
+    token?: string;
+    json?: boolean;
+    open?: boolean;
+    fetch?: typeof fetch;
+    stdout?: Pick<typeof console, "log">;
+    openApprovalUrl?: (url: string) => Promise<void>;
+    credentialProvider?: string;
+    fromEnv?: string;
+    stdin?: boolean;
+    readStdin?: () => Promise<string>;
+    /** Separate short-lived admin-token cache; never reuses the app developer-token file. */
+    tokenFile?: string;
+}
+/** Inputs for obtaining one short-lived, exact-scope platform device grant. */
+interface ScopedPlatformTokenOptions {
+    platform: string;
+    scope: "platform:ai:read" | "platform:ai:write" | "platform:security:self";
+    open?: boolean;
+    fetch?: typeof fetch;
+    stdout?: Pick<typeof console, "log">;
+    openApprovalUrl?: (url: string) => Promise<void>;
+    tokenFile?: string;
+}
+/** Obtain/cache one exact platform scope without granting ambient admin. */
+declare function getScopedPlatformToken(options: ScopedPlatformTokenOptions): Promise<string>;
+/** Read or update platform-funded AI routing. Authentication is a short-lived,
+ * explicitly scoped device grant; ordinary app developer tokens never become
+ * platform admins. Credential writes accept values only from a named env var
+ * or stdin, transfer them once, and never place them in argv, output, or the
+ * scoped-token cache. */
+declare function adminAi(options: AdminAiOptions): 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", "run app-attributed hosted security discovery and independent validation without provider keys", "let admins manage system AI routes/credentials through short-lived exact-scope approval"];
+    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", "approve redacted-source disclosure before hosted security reasoning"];
+    readonly studio: readonly ["view telemetry and environment state", "perform manual credential recovery when the CLI's local shown-once copy is unavailable", "configure system AI purposes and view app/environment/run-attributed usage"];
+};
+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 {
@@ -178,8 +381,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;
@@ -192,6 +431,7 @@ interface ClerkAuthConfig {
     audience?: string;
     mode?: "client" | "full";
 }
+/** Authored `odla.config.mjs` contract consumed by doctor and provision. */
 interface OdlaProjectConfig {
     platformUrl?: string;
     dbEndpoint?: string;
@@ -238,6 +478,7 @@ interface OdlaProjectConfig {
         gitignore?: boolean;
     };
 }
+/** Normalized project config with resolved paths, endpoints, envs, and services. */
 interface LoadedProjectConfig extends OdlaProjectConfig {
     configPath: string;
     rootDir: string;
@@ -252,6 +493,7 @@ interface LoadedProjectConfig extends OdlaProjectConfig {
         gitignore: boolean;
     };
 }
+/** Private mode-0600 local state written by provision and never committed. */
 interface LocalCredentials {
     appId: string;
     platformUrl: string;
@@ -263,10 +505,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;
@@ -276,10 +523,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;
@@ -291,6 +542,7 @@ interface ProvisionPlan {
     hasRules: boolean;
     aiProvider?: string;
 }
+/** Inputs for a read-only live environment smoke check. */
 interface SmokeOptions {
     configPath: string;
     env?: string;
@@ -298,21 +550,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;
@@ -323,38 +604,145 @@ 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>;
 
+/** Built-in security coverage profile selected for a hosted reasoning run. */
+type HostedSecurityProfile = "odla" | "cloudflare-app" | "generic";
+/** Exact attribution and authorization need supplied to a lazy token callback. */
+interface HostedSecurityTokenRequest {
+    platform: string;
+    appId: string;
+    env: string;
+    selfAudit: boolean;
+    /** Self-audit asks the caller for an explicitly scoped platform credential. */
+    /** Ordinary app runs use owner authority and therefore request no platform scope. */
+    scope: "platform:security:self" | null;
+}
+/** Local snapshot/orchestration controls for an app-attributed hosted security
+ * run. The platform supplies model routes and provider credentials. */
+interface RunHostedSecurityOptions {
+    /** Project config; loaded for customer-app runs and ignored for self-audit. */
+    configPath?: string;
+    /** Scan odla itself under the protected odla-ai/prod identity. */
+    selfAudit?: boolean;
+    /** Repository directory to snapshot. Defaults to the config root or cwd for self-audit. */
+    target?: string;
+    /** Private artifact directory. Defaults to `<target>/.odla/security/hosted`. */
+    out?: string;
+    /** Customer environment. Must be declared in config. Self-audit always uses prod. */
+    env?: string;
+    profile?: HostedSecurityProfile;
+    maxHuntTasks?: number;
+    /** Exact acknowledgement required before any source capture or network call. */
+    sourceDisclosureAck?: "redacted";
+    /** Optional client correlation id; the platform returns the authoritative run id. */
+    runId?: string;
+    /** Platform override. Customer runs otherwise use config.platformUrl. */
+    platform?: string;
+    /** Injected app credential; for self-audit this must be explicitly scoped by the caller. */
+    token?: string;
+    /** Lazy token acquisition. Receives the exact app/env and required scope. */
+    getToken?: (request: HostedSecurityTokenRequest) => string | Promise<string>;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+    stdout?: Pick<typeof console, "log" | "error">;
+}
+/** Completed local report, public platform run metadata, and private artifact path. */
+interface HostedSecurityResult {
+    report: SecurityReport;
+    run: Readonly<PlatformSecurityRun>;
+    output: string;
+}
+/**
+ * Run the hosted, redacted-source security harness for an odla app or odla's
+ * protected self-audit identity. Provider/model selection and provider secrets
+ * remain platform-owned; this function accepts only an app/scoped bearer and
+ * the opaque role grants remain inside @odla-ai/security's reasoner closures.
+ */
+declare function runHostedSecurity(options: RunHostedSecurityOptions): Promise<HostedSecurityResult>;
+
+/** 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 AdminAiOptions, type AgentHarness, type AgentHarnessSelector, CAPABILITIES, type HarnessInstallResult, type HostedSecurityProfile, type HostedSecurityResult, type HostedSecurityTokenRequest, type LoadedProjectConfig, type LocalCredentials, type OdlaProjectConfig, type ProvisionOptions, type ProvisionPlan, type RunHostedSecurityOptions, SYSTEM_AI_PURPOSES, type ScopedPlatformTokenOptions, type SecretsPushOptions, type SkillInstallOptions, type SkillInstallResult, type SmokeOptions, type SystemAiPurpose, adminAi, doctor, getScopedPlatformToken, initProject, installSkill, printCapabilities, provision, redactSecrets, runCli, runHostedSecurity, secretsPush, smoke };
 ```