@pikku/cli 0.12.93 → 0.12.99

package/dist/.pikku/workflow/pikku-workflow-types.gen.d.ts

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.93
+ * This file was generated by @pikku/cli@0.12.99
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';
@@ -11,8 +11,8 @@ import type { FlattenedRPCMap } from '../rpc/pikku-rpc-wirings-map.internal.gen.
 import type { FlattenedWorkflowMap } from './pikku-workflow-map.gen.d.js';
 import type { AgentMap as FlattenedAgentMap } from '../agent/pikku-agent-map.gen.d.js';
 import type { FlattenedScenarioStepMap } from './pikku-scenario-step-map.gen.d.js';
-import type { TypedScenarioActors } from './pikku-scenario-actors.gen.js';
-export type { TypedScenarioActors };
+import type { TypedPersonas } from './pikku-personas.gen.js';
+export type { TypedPersonas };
 export { template };
 export interface TypedWorkflow extends PikkuWorkflowWire {
     do<K extends keyof FlattenedRPCMap>(stepName: string, rpcName: K, data: FlattenedRPCMap[K]['input'], options?: WorkflowStepOptions): Promise<FlattenedRPCMap[K]['output']>;
@@ -20,12 +20,12 @@ export interface TypedWorkflow extends PikkuWorkflowWire {
     do<T>(stepName: string, fn: () => T | Promise<T>, options?: WorkflowStepOptions): Promise<T>;
 }
 /**
- * The typed half of a scenario wire: `step` and its `given`/`when`/`then`
- * sugar, narrowed to the names declared by `pikkuScenarioStep` in this project.
- * The phase only changes the prose the reporter renders.
+ * The typed half of a scenario wire: `given`/`when`/`then`, narrowed to the
+ * names declared by `pikkuScenarioStep` in this project. `given` and `when`
+ * differ only in the prose the reporter renders; `then` additionally makes the
+ * step's bindings witnesses rather than alternatives.
  */
 export interface TypedScenarioSteps {
-    step<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
     given<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
     when<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
     then<K extends keyof FlattenedScenarioStepMap>(stepName: string, stepFunc: K, data?: FlattenedScenarioStepMap[K]['input'], options?: ScenarioStepOptions): Promise<FlattenedScenarioStepMap[K]['output']>;
@@ -171,9 +171,16 @@ export type PikkuFeatureConfig<Scenarios extends readonly unknown[]> = {
  * ```
  */
 export declare function pikkuFeature<const Scenarios extends readonly unknown[]>(config: PikkuFeatureConfig<Scenarios>): PikkuFeatureConfig<Scenarios>;
-export type PikkuFunctionScenarioStep<In = unknown, Out = never, B extends boolean = false> = PikkuFunctionSessionless<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>;
-export type PikkuScenarioStepConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, B extends boolean = false> = {
-    /** Registered name — this is the string `scenario.step()` references. */
+/**
+ * One surface's implementation of a step.
+ *
+ * Each binding is typed independently, so a browser binding gets a non-optional
+ * `wire.browser` and a cli binding a non-optional `wire.cli` without either
+ * leaking into the other.
+ */
+export type PikkuFunctionScenarioStep<In = unknown, Out = never, Surface extends 'browser' | 'cli' | 'default' = 'default'> = PikkuFunctionSessionless<In, Out, Surface extends 'default' ? 'scenarioStep' : 'scenarioStep' | Surface>;
+export type PikkuScenarioStepConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = {
+    /** Registered name — this is the string `scenario.given()` references. */
     name: string;
     /**
      * What this step does, for the console and for whoever reads the source. It
@@ -190,32 +197,102 @@ export type PikkuScenarioStepConfigWithSchema<InputSchema extends StandardSchema
      * sentence per call site.
      */
     template?: string;
-    /**
-     * This step drives a browser. The runner provisions one for the step's actor
-     * before calling it — which also makes an actor mandatory — and `wire.browser`
-     * is non-optional inside `func`.
-     */
-    browser?: B;
     title?: string;
     tags?: string[];
     input?: InputSchema;
     output?: OutputSchema;
     errors?: Array<typeof PikkuError>;
-    func: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B>;
+    /**
+     * Drive this step through a real browser, as a human would. The runner
+     * provisions a window for the step's actor first — which makes an actor
+     * mandatory — and `wire.browser` is non-optional inside it.
+     *
+     * Compose shared utilities here rather than writing raw clicks: the step says
+     * what the actor is doing, the utilities say how.
+     */
+    browser?: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'browser'>;
+    /** Drive this step remotely, over the websocket. */
+    cli?: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'cli'>;
+    /**
+     * The server-side path — the fast suite, and the floor every other surface
+     * falls back to.
+     *
+     * On a `then`, this is not an alternative to the other bindings but a second
+     * **witness**: the run executes every binding it has and fails if they
+     * disagree, because "the row says paid" and "the page says paid" are different
+     * claims and the gap between them is the bug nobody catches.
+     */
+    default?: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>;
 };
-export type PikkuScenarioStepConfig<In, Out, B extends boolean = false> = Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined, B>, 'func' | 'input' | 'output'> & {
-    func: PikkuFunctionScenarioStep<In, Out, B>;
+export type PikkuScenarioStepConfig<In, Out> = Omit<PikkuScenarioStepConfigWithSchema<undefined, undefined>, 'browser' | 'cli' | 'default' | 'input' | 'output'> & {
+    browser?: PikkuFunctionScenarioStep<In, Out, 'browser'>;
+    cli?: PikkuFunctionScenarioStep<In, Out, 'cli'>;
+    default?: PikkuFunctionScenarioStep<In, Out, 'default'>;
 };
 /**
- * A named, reusable scenario step. Unlike `scenario.do`, which can only name an
- * RPC, a step's body is an ordinary pikku function — so it may drive a browser,
- * invoke RPCs as its actor, or run a workflow.
+ * A named, reusable scenario step, declaring one implementation per surface an
+ * actor can drive it through.
+ *
+ * The step's identity is what the actor is trying to do; which surface carries
+ * it out is a binding. That is what lets one ladder run through a real browser,
+ * over the websocket, or entirely server-side — and what makes "how much of this
+ * flow can a human actually reach" a number rather than a guess.
  *
  * Steps are deliberately NOT registered as RPCs: a browser-driving step must
  * never be network-callable.
  */
-export declare function pikkuScenarioStep<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined, B extends boolean = false>(config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema, B>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, B>, InputSchema, OutputSchema>;
-export declare function pikkuScenarioStep<In, Out = unknown, B extends boolean = false>(config: PikkuScenarioStepConfig<In, Out, B>): PikkuFunctionConfig<In, Out, B extends true ? 'scenarioStep' | 'browser' : 'scenarioStep'>;
+export declare function pikkuScenarioStep<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep' | 'browser' | 'cli', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'browser' | 'cli' | 'default'>, InputSchema, OutputSchema>;
+export declare function pikkuScenarioStep<In, Out = unknown>(config: PikkuScenarioStepConfig<In, Out>): PikkuFunctionConfig<In, Out, 'scenarioStep' | 'browser' | 'cli'>;
+/**
+ * What a step declares when nobody drives it: one implementation, and no
+ * surfaces to choose between.
+ *
+ * `func` rather than `default` is the point. `default` means *the fallback when
+ * no other surface applies*, which implies others could exist; `func` says
+ * structurally that there is one way this happens. That also keeps the phase
+ * rule coherent — an assertion runs every witness it has and fails if they
+ * disagree, and this has exactly one by construction.
+ */
+export type PikkuSubjectScenarioStepConfigWithSchema<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined> = Omit<PikkuScenarioStepConfigWithSchema<InputSchema, OutputSchema>, 'browser' | 'cli' | 'default'> & {
+    func: PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>;
+};
+export type PikkuSubjectScenarioStepConfig<In, Out> = Omit<PikkuScenarioStepConfig<In, Out>, 'browser' | 'cli' | 'default'> & {
+    func: PikkuFunctionScenarioStep<In, Out, 'default'>;
+};
+/**
+ * A step in which the app acts on itself — "Given the platform has expired the
+ * trial".
+ *
+ * The grammatical subject of that sentence is not a user of your app; it **is**
+ * your app, which is why it is its own declaration rather than a persona with an
+ * asterisk. A persona is a person.
+ *
+ * Local-test-only, and never in a virtual user's catalogue: a virtual user that
+ * could expire its own trial is manufacturing the outcome it exists to discover.
+ */
+export declare function pikkuPlatformScenarioStep<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema>): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>;
+export declare function pikkuPlatformScenarioStep<In, Out = unknown>(config: PikkuSubjectScenarioStepConfig<In, Out>): PikkuFunctionConfig<In, Out, 'scenarioStep'>;
+/**
+ * A step in which a third-party system acts — "Given Stripe's webhook arrives",
+ * "When Mailgun bounces it".
+ *
+ * `addon` names the addon that wraps that service, the same name its
+ * `wireAddon` declares. These steps *are* the mock its consumers currently
+ * hand-write: shipped by the addon author, maintained with the addon, and the
+ * same artifact that appears in the prose.
+ *
+ * Note that arranging and asserting are different — "Stripe's webhook arrives"
+ * stubs, "Then Stripe was charged" asserts, and only the first is a stub.
+ *
+ * Local-test-only, and never in a virtual user's catalogue: one that could
+ * invoke this would forge its own payment success.
+ */
+export declare function pikkuAddonScenarioStep<InputSchema extends StandardSchemaV1 | undefined = undefined, OutputSchema extends StandardSchemaV1 | undefined = undefined>(config: PikkuSubjectScenarioStepConfigWithSchema<InputSchema, OutputSchema> & {
+    addon: string;
+}): PikkuFunctionConfig<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'scenarioStep', PikkuFunctionScenarioStep<InputSchema extends StandardSchemaV1 ? InferSchemaOutput<InputSchema> : unknown, OutputSchema extends StandardSchemaV1 ? InferSchemaOutput<OutputSchema> : unknown, 'default'>, InputSchema, OutputSchema>;
+export declare function pikkuAddonScenarioStep<In, Out = unknown>(config: PikkuSubjectScenarioStepConfig<In, Out> & {
+    addon: string;
+}): PikkuFunctionConfig<In, Out, 'scenarioStep'>;
 type TypedRef<T> = {
     $ref: string;
     path?: string;

package/dist/.pikku/workflow/pikku-workflow-types.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.93
+ * This file was generated by @pikku/cli@0.12.99
  */
 import { WorkflowCancelledException } from '@pikku/core/workflow';
 import { template } from '@pikku/core/workflow';
@@ -51,7 +51,27 @@ export function pikkuFeature(config) {
     return config;
 }
 export function pikkuScenarioStep(config) {
-    return config;
+    const surfaces = ['browser', 'cli', 'default'].filter((surface) => typeof config[surface] === 'function');
+    if (surfaces.length === 0) {
+        throw new Error(`[scenario] step '${config.name}' declares no surface bindings. Add at least a \`default\` (server-side) implementation.`);
+    }
+    return {
+        ...config,
+        surfaces,
+        // The runner sets the surface on the wire and calls this once per binding it
+        // resolved — every witness of a `then`, exactly one for an action step.
+        func: (services, data, wire) => {
+            const surface = wire?.scenarioStep?.surface ?? 'default';
+            const binding = config[surface] ?? config.default;
+            return binding(services, data, wire);
+        },
+    };
+}
+export function pikkuPlatformScenarioStep(config) {
+    return { ...config, surfaces: ['default'] };
+}
+export function pikkuAddonScenarioStep(config) {
+    return { ...config, surfaces: ['default'] };
 }
 export function pikkuWorkflowGraph(config) {
     return corePikkuWorkflowGraph(config);

package/dist/.pikku/workflow/pikku-workflow-wirings-meta.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.93
+ * This file was generated by @pikku/cli@0.12.99
  */
 import { pikkuState } from '@pikku/core/internal';
 import allWorkflowMeta from './meta/allWorkflow.gen.json' with { type: 'json' };

package/dist/.pikku/workflow/pikku-workflow-wirings.gen.js

@@ -1,5 +1,5 @@
 /**
- * This file was generated by @pikku/cli@0.12.93
+ * This file was generated by @pikku/cli@0.12.99
  */
 import { addWorkflow } from '@pikku/core/workflow';
 import './pikku-workflow-wirings-meta.gen.js';

package/dist/bin/pikku-bin.mjs

@@ -11,8 +11,8 @@ async function checkForUpdate() {
     })
     if (!res.ok) return
     const { version: latest } = await res.json()
-    if (latest !== '0.12.93') {
-      process.stderr.write(`\n  Update available  0.12.93 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
+    if (latest !== '0.12.99') {
+      process.stderr.write(`\n  Update available  0.12.99 → ${latest}\n  brew upgrade pikku  or  npm install -g @pikku/cli\n\n`)
     }
   } catch {}
 }

package/dist/src/cli.wiring.js

@@ -22,16 +22,19 @@ import { dbCodegen } from './functions/commands/db-codegen.js';
 import { dbCheck } from './functions/commands/db-check.js';
 import { dbBaseline } from './functions/commands/db-baseline.js';
 import { dbExport } from './functions/commands/db-export.js';
-import { dbSeed } from './functions/commands/db-seed.js';
 import { dbReset } from './functions/commands/db-reset.js';
 import { dbAudit } from './functions/commands/db-audit.js';
 import { scopesAudit } from './functions/commands/scopes-audit.js';
 import { scopesPrune } from './functions/commands/scopes-prune.js';
+import { rolesAudit } from './functions/commands/roles-audit.js';
+import { rolesPrune } from './functions/commands/roles-prune.js';
 import { pikkuAudit } from './functions/commands/audit.js';
 import { workspaceValidate, renderWorkspaceValidate, } from './functions/commands/workspace-validate.js';
 import { knowledgeValidate, renderKnowledgeValidate, } from './functions/commands/knowledge-validate.js';
 import { knowledgeIndex, renderKnowledgeIndex, } from './functions/commands/knowledge-index.js';
 import { scenarioRun, scenarioList } from './functions/commands/scenario.js';
+import { personaList, personaRun } from './functions/commands/persona.js';
+import { personaSync } from './functions/commands/persona-sync.js';
 import { pikkuVersionsInit } from './functions/commands/versions-init.js';
 import { pikkuEmailsInit } from './functions/commands/emails-init.js';
 import { pikkuVersionsCheck } from './functions/commands/versions-check.js';
@@ -92,6 +95,10 @@ wireCLI({
             description: 'Fail the build on critical diagnostics. Always on; accepted for symmetry with --fail-on-error/--fail-on-warn.',
             default: true,
         },
+        strictMeta: {
+            description: "Fail the build when an AI agent's tool has no description. Without one the model is offered the tool under its own name, so this is a quality gate rather than a correctness one — hence off by default. A 'title' does not satisfy it.",
+            default: false,
+        },
         tsc: {
             description: "After codegen, run a real tsc --noEmit over the project's tsconfig and fail on type errors. Prints full diagnostics with code frames. Off by default.",
             default: false,
@@ -343,13 +350,15 @@ wireCLI({
                     func: dbExport,
                     description: "Publish this package's schema so projects consuming it as an addon can create its tables",
                 }),
-                seed: pikkuCLICommand({
-                    func: dbSeed,
-                    description: 'Apply db/seed.sql to the dev database',
-                }),
                 reset: pikkuCLICommand({
                     func: dbReset,
-                    description: 'Wipe and recreate the dev database (migrate + seed)',
+                    description: 'Wipe and recreate the dev database: migrate, then apply db/<engine>-dev-seed.sql. Dev only — it refuses to run in production',
+                    options: {
+                        noSeed: {
+                            description: 'Stop after migrating, leaving the database empty. For working on an empty-state or onboarding flow the test data would hide',
+                            default: false,
+                        },
+                    },
                 }),
                 audit: pikkuCLICommand({
                     func: dbAudit,
@@ -377,6 +386,26 @@ wireCLI({
                 }),
             },
         },
+        roles: {
+            description: 'Inspect and maintain the roles declared with defineSystemRole',
+            subcommands: {
+                audit: pikkuCLICommand({
+                    func: rolesAudit,
+                    description: 'Report system roles in the database that are no longer declared in code, and how many people hold them',
+                }),
+                prune: pikkuCLICommand({
+                    func: rolesPrune,
+                    description: 'Remove system roles that are no longer declared in code, cascading them out of every user grant',
+                    options: {
+                        yes: {
+                            description: 'Actually delete. Without it, prune only reports the blast radius',
+                            short: 'y',
+                            default: false,
+                        },
+                    },
+                }),
+            },
+        },
         knowledge: {
             description: 'Inspect and maintain the knowledge base — what this app is, in the language its users use',
             subcommands: {
@@ -413,7 +442,7 @@ wireCLI({
             subcommands: {
                 run: pikkuCLICommand({
                     func: scenarioRun,
-                    description: 'Run scenarios against a configured environment (scenarios.environments in pikku.config.json). Actor secret comes from SCENARIO_ACTOR_SECRET.',
+                    description: 'Run scenarios against a configured environment (environments in pikku.config.json). Actor secret comes from SCENARIO_ACTOR_SECRET.',
                     parameters: '<environment>',
                     options: {
                         flows: {
@@ -435,9 +464,17 @@ wireCLI({
                             default: false,
                         },
                         browser: {
-                            description: 'Run scenarios with browser steps. --no-browser skips them (they are reported as skipped, not failed)',
+                            description: 'Shorthand for --run default when false: takes the server-side path instead of driving a browser',
                             default: true,
                         },
+                        run: {
+                            description: "Which surface every actor drives the system through: 'browser' (as a human), 'cli' (over the websocket), or 'default' (server-side, the fast path)",
+                            default: 'default',
+                        },
+                        strict: {
+                            description: 'Fail rather than pass a `then` that has no witness for --run, i.e. an assertion nobody checked on the surface its prose claims',
+                            default: false,
+                        },
                         spawn: {
                             description: "Start `pikku dev` on the environment's apiUrl for the run and stop it afterwards. Without it, the environment must already be serving",
                             default: false,
@@ -464,6 +501,69 @@ wireCLI({
                 }),
             },
         },
+        persona: {
+            description: 'The people this app is for, and running one against a real stage',
+            subcommands: {
+                run: pikkuCLICommand({
+                    func: personaRun,
+                    description: 'Sign in as a declared persona and work the API in character against a configured environment. Not a test runner: it asserts nothing and reports what came back that should not have. The sign-in secret comes from SCENARIO_ACTOR_SECRET.',
+                    parameters: '<environment> <persona>',
+                    options: {
+                        disposition: {
+                            description: 'How they behave: realistic (default), careless, newcomer, stale, auditor, adversarial',
+                            short: 'd',
+                        },
+                        goals: {
+                            description: "Comma-separated goals in your own words, run alongside the persona's own and the ones derived from scenarios",
+                        },
+                        steps: {
+                            description: 'Model turns before it stops (default 40)',
+                        },
+                        mutations: {
+                            description: 'Non-read calls before it stops',
+                        },
+                        duration: {
+                            description: "Wall clock before it stops, e.g. '30m'",
+                        },
+                        seed: {
+                            description: 'Replay a previous run — the same seed schedules the same run',
+                        },
+                        model: {
+                            description: 'Model they think with. Defaults to scenarios.model in pikku.config.json',
+                        },
+                        allowApproval: {
+                            description: 'Offer the endpoints the app marked as needing a human\u2019s approval. Off by default: those are the ones that spend money',
+                        },
+                        skipRoleCheck: {
+                            description: 'Start without verifying the declared roles against the stage. For a target whose auth reports roles somewhere pikku cannot read — findings from an unverified run may be seed drift rather than product bugs',
+                        },
+                        apiUrl: {
+                            description: "Override the environment's apiUrl for this run — for a target that only exists at run time, such as a freshly deployed sandbox",
+                        },
+                        out: {
+                            description: 'Write the whole run — every step, response and finding — as JSON to this path',
+                        },
+                    },
+                }),
+                sync: pikkuCLICommand({
+                    func: personaSync,
+                    description: "Provision the declared personas into an environment: create each account and apply the roles it declares. Additive — it never revokes. Needs both the environment's API (to sign in) and its database (to write the grants), and the sign-in secret from SCENARIO_ACTOR_SECRET.",
+                    parameters: '<environment>',
+                    options: {
+                        dryRun: {
+                            description: 'Report who would be provisioned, with which roles, and why anyone was skipped — without touching anything',
+                        },
+                        apiUrl: {
+                            description: "Override the environment's apiUrl — for a target that only exists at run time, such as a freshly deployed sandbox",
+                        },
+                    },
+                }),
+                list: pikkuCLICommand({
+                    func: personaList,
+                    description: 'List the declared personas — who each one is, what they may do, and what they are trying to get done',
+                }),
+            },
+        },
         fabric: {
             description: 'PikkuFabric commands (login, link, deploy, domains, secrets, logs, …)',
             subcommands: fabricCommands,

package/dist/src/deploy/analyzer/analyzer.js

@@ -7,6 +7,7 @@
  * Workflow orchestrators dispatch to step units via queue or RPC (inline).
  */
 import { resolveDeployTarget, } from '@pikku/inspector';
+import { relative } from 'node:path';
 import { isScenarioFunction, withoutScenarios, withoutScenarioWorkflows, } from '../../functions/wirings/scenarios/scenario-partition.js';
 export function analyzeDeployment(state, options) {
     const serverlessIncompatible = new Set(options.serverlessIncompatible ?? []);
@@ -353,10 +354,22 @@ export function analyzeDeployment(state, options) {
         }
     }
     // ── Secrets & Variables ────────────────────────────────────────────
+    const readSecretIds = new Set();
+    const unresolvedSecretReads = [];
+    for (const [file, usage] of state.secrets.usage ?? []) {
+        for (const key of usage.keys) {
+            readSecretIds.add(key);
+        }
+        for (const read of usage.dynamic) {
+            unresolvedSecretReads.push(`${relative(state.rootDir, file)}:${read}`);
+        }
+    }
     const secrets = state.secrets.definitions.map((s) => ({
         secretId: s.secretId,
         displayName: s.displayName,
         description: s.description,
+        allowedHosts: s.allowedHosts,
+        read: readSecretIds.has(s.secretId),
     }));
     const variables = state.variables.definitions.map((v) => ({
         variableId: v.variableId,
@@ -374,6 +387,7 @@ export function analyzeDeployment(state, options) {
         mcpEndpoints,
         workflows,
         secrets,
+        unresolvedSecretReads: unresolvedSecretReads.sort(),
         variables,
     };
 }

package/dist/src/deploy/analyzer/manifest.d.ts

@@ -101,7 +101,13 @@ export interface SecretDeclaration {
     secretId: string;
     displayName: string;
     description?: string;
+    /** Hosts this secret may be sent to. Absent means unrestricted. */
+    allowedHosts?: string[];
+    /** True when some code reads this secret with a statically resolvable key. */
+    read?: boolean;
 }
+/** Secret reads whose key the inspector could not resolve, as `file:line:source`. */
+export type UnresolvedSecretRead = string;
 export interface VariableDeclaration {
     variableId: string;
     displayName: string;
@@ -118,5 +124,10 @@ export interface DeploymentManifest {
     mcpEndpoints: MCPEndpointDefinition[];
     workflows: WorkflowDefinition[];
     secrets: SecretDeclaration[];
+    /**
+     * Reads with a non-literal key. A deployment can only narrow a unit's secret
+     * scope to the declared set when this is empty.
+     */
+    unresolvedSecretReads: UnresolvedSecretRead[];
     variables: VariableDeclaration[];
 }