@pikku/cli 0.12.114 → 0.12.116

package/dist/src/functions/wirings/functions/serialize-function-types.js

@@ -49,8 +49,21 @@ ${rpcMapTypeImport}
 ${requiredServicesTypeImport}
 ${workflowImport}
 
+/**
+ * The services that live for the process — the ones built once in \`createConfig\`/
+ * \`createSingletonServices\` and shared by every request.
+ */
 ${singletonServicesTypeName !== 'SingletonServices' ? `export type SingletonServices = ${singletonServicesTypeName}` : `export type { ${singletonServicesTypeName} as SingletonServices }`}
+/**
+ * Everything a function is handed as its first argument: the singleton services
+ * plus whatever is built per request. This is the type to widen when you add a
+ * service.
+ */
 ${wireServicesTypeName !== 'Services' ? `export type Services = ${wireServicesTypeName}` : `export type { ${wireServicesTypeName} as Services }`}
+/**
+ * The signed-in user as this project defines it. Reached on the wire as
+ * \`session\`, and replaced with \`setSession\`.
+ */
 ${userSessionTypeName !== 'Session' ? `export type Session = ${userSessionTypeName}` : `export type { ${userSessionTypeName} as Session }`}
 
 /**
@@ -257,21 +270,7 @@ type PikkuFunctionConfigWithSchema<
  * @param config - Function definition with \`input\`/\`output\` Zod schemas and \`func\`.
  * @returns The normalized configuration object
  *
- * @example
- * \`\`\`typescript
- * const createUserInput = z.object({ name: z.string(), email: z.string() })
- * const createUserOutput = z.object({ id: z.number() })
- *
- * const createUser = pikkuFunc({
- *   input: createUserInput,
- *   output: createUserOutput,
- *   func: async ({db}, input) => {
- *     // input is typed as { name: string, email: string }
- *     const user = await db.users.create(input)
- *     return { id: user.id } // must match output schema
- *   }
- * })
- * \`\`\`
+ * @example snippet: sessionFunction
  */
 export function pikkuFunc<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
@@ -288,6 +287,13 @@ export function pikkuFunc(func: any) {
   return typeof func === 'function' ? { func } : func
 }
 
+/**
+ * A \`pikkuFunc\` whose input and output are already the shared list shape —
+ * filters, sort, paging in; rows and a total out — so a listing endpoint pages
+ * the same way everywhere.
+ *
+ * @example snippet: listFunction
+ */
 export const pikkuListFunc = <
   F extends Record<string, unknown> = {},
   Row = unknown,
@@ -348,19 +354,7 @@ type PikkuFunctionSessionlessConfigWithSchema<
  * @param config - Function definition with \`input\`/\`output\` Zod schemas and \`func\`.
  * @returns The normalized configuration object
  *
- * @example
- * \`\`\`typescript
- * const greetInput = z.object({ name: z.string() })
- * const greetOutput = z.object({ message: z.string() })
- *
- * const greet = pikkuSessionlessFunc({
- *   input: greetInput,
- *   output: greetOutput,
- *   func: async (_services, { name }) => {
- *     return { message: \`Hello, \${name}!\` }
- *   }
- * })
- * \`\`\`
+ * @example snippet: readFunction
  */
 export function pikkuSessionlessFunc<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
@@ -385,14 +379,7 @@ export function pikkuSessionlessFunc(func: any) {
  * @param func - Function definition, either direct function or configuration object
  * @returns The normalized configuration object
  *
- * @example
- * \`\`\`typescript
- * const cleanupTempFiles = pikkuVoidFunc(async ({fileSystem, logger}) => {
- *     logger.info('Starting cleanup of temporary files')
- *     await fileSystem.deleteDirectory('/tmp/uploads')
- *     logger.info('Cleanup completed')
- * })
- * \`\`\`
+ * @example snippet: cleanupFunction
  */
 export const pikkuVoidFunc = (
   func:

package/dist/src/functions/wirings/http/serialize-http-types.js

@@ -33,6 +33,8 @@ type HTTPWiring<In, Out, Route extends string> = CoreHTTPFunctionWiring<In, Out,
  * @template Out - Output type for the HTTP wiring
  * @template Route - String literal type for the HTTP path (e.g., "/users/:id")
  * @param httpWiring - HTTP wiring definition with handler, method, and optional middleware
+ *
+ * @example snippet: httpSingleRoute
  */
 export const wireHTTP = <In, Out, Route extends string>(
   httpWiring: HTTPWiring<In, Out, Route> & AssertHTTPWiringParams<In, Route>
@@ -87,6 +89,8 @@ type TypedWireHTTPRoutesConfig = TypedHTTPRoutesGroupConfig & {
 `}
 /**
  * Type-safe helper for defining route contracts that can be composed.
+ *
+ * @example snippet: wireHttp
  */
 export function defineHTTPRoutes<T extends TypedHTTPRouteMap>(routes: T): TypedHTTPRouteContract<T>
 export function defineHTTPRoutes<T extends TypedHTTPRouteMap>(config: TypedHTTPRoutesGroupConfig & { routes: T }): TypedHTTPRouteContract<T>
@@ -99,6 +103,8 @@ ${addon
         : `
 /**
  * Wires multiple HTTP routes from a nested map or array configuration.
+ *
+ * @example snippet: httpRoutesWiring
  */
 export const wireHTTPRoutes = (config: TypedWireHTTPRoutesConfig): void => {
   wireHTTPRoutesCore(config as any)

package/dist/src/functions/wirings/mcp/serialize-mcp-types.js

@@ -43,6 +43,8 @@ ${addon
  * @template In - Input type for the resource request
  * @template URI - URI template string for compile-time parameter validation
  * @param mcpResource - MCP resource definition with data provider function
+ *
+ * @example snippet: mcpResource
  */
 export const wireMCPResource = <In, URI extends string>(
   mcpResource: MCPResourceWiring<In, URI> & AssertMCPResourceURIParams<In, URI>
@@ -56,6 +58,8 @@ export const wireMCPResource = <In, URI extends string>(
  *
  * @template In - Input type for the prompt parameters
  * @param mcpPrompt - MCP prompt definition with template function
+ *
+ * @example snippet: mcpPrompt
  */
 export const wireMCPPrompt = <In>(
   mcpPrompt: MCPPromptWiring<In>
@@ -83,6 +87,8 @@ type MCPPromptFuncConfigWithSchema<InputSchema extends StandardSchemaV1> = {
  * @template In - Input type for the prompt parameters (inferred from schema if provided)
  * @param func - Function definition, either direct function or configuration object
  * @returns The unwrapped function for internal use
+ *
+ * @example snippet: mcpPrompt
  */
 export function pikkuMCPPromptFunc<InputSchema extends StandardSchemaV1>(
   config: MCPPromptFuncConfigWithSchema<InputSchema>
@@ -125,6 +131,8 @@ type MCPToolFuncConfigWithSchema<InputSchema extends StandardSchemaV1> = {
  * @template In - Input type for the tool invocation (inferred from schema if provided)
  * @param func - Function definition, either direct function or configuration object
  * @returns The unwrapped function for internal use
+ *
+ * @example snippet: mcpSingleTool
  */
 export function pikkuMCPToolFunc<InputSchema extends StandardSchemaV1>(
   config: MCPToolFuncConfigWithSchema<InputSchema>
@@ -167,6 +175,8 @@ type MCPResourceFuncConfigWithSchema<InputSchema extends StandardSchemaV1> = {
  * @template In - Input type for the resource request (inferred from schema if provided)
  * @param func - Function definition, either direct function or configuration object
  * @returns The unwrapped function for internal use
+ *
+ * @example snippet: mcpResource
  */
 export function pikkuMCPResourceFunc<InputSchema extends StandardSchemaV1>(
   config: MCPResourceFuncConfigWithSchema<InputSchema>

package/dist/src/functions/wirings/middleware/serialize-middleware-types.js

@@ -24,7 +24,7 @@ import type { PikkuAgentMiddlewareHooks } from '@pikku/core/agent'
 import type { Services, SingletonServices } from '${functionTypesImportPath}'
 ${requiredServicesTypeImport}
 
-export { cors } from '@pikku/core/middleware'
+export { cors, authAPIKey, authBearer, authCookie } from '@pikku/core/middleware'
 export type { MiddlewarePriority }
 
 /**
@@ -90,18 +90,7 @@ export const pikkuMiddleware = <RequiredServices extends SingletonServices = Wir
  * Factory function for creating middleware factories
  * Use this when your middleware needs configuration/input parameters
  *
- * @example
- * \`\`\`typescript
- * export const logMiddleware = pikkuMiddlewareFactory<LogOptions>(({
- *   message,
- *   level = 'info'
- * }) => {
- *   return pikkuMiddleware(async ({ logger }, next) => {
- *     logger[level](message)
- *     await next()
- *   })
- * })
- * \`\`\`
+ * @example snippet: middlewareFactory
  */
 export const pikkuMiddlewareFactory = <In = any>(
   factory: (input: In) => PikkuMiddleware
@@ -125,8 +114,7 @@ export const addGlobalMiddleware = (middleware: PikkuMiddleware[]) => {
 /**
  * Tag-scoped middleware. Applies to any wiring that carries the matching tag.
  *
- * @example
- * addTagMiddleware('admin', [adminMiddleware])
+ * @example snippet: tagMiddleware
  */
 export const addTagMiddleware = (tag: string, middleware: PikkuMiddleware[]) => {
   addTagMiddlewareCore(tag, middleware as any, ${packageNameValue})
@@ -141,14 +129,7 @@ export const addTagMiddleware = (tag: string, middleware: PikkuMiddleware[]) =>
  * @param routeOrMiddleware - Either a global middleware array or a route pattern string
  * @param middleware - The middleware array to apply when a route pattern is specified
  *
- * @example
- * \`\`\`typescript
- * // Add global HTTP middleware
- * addHTTPMiddleware([authMiddleware, loggingMiddleware])
- *
- * // Add route-specific middleware
- * addHTTPMiddleware('/api/admin/*', [adminAuthMiddleware])
- * \`\`\`
+ * @example snippet: httpMiddleware
  */
 export const addHTTPMiddleware = (
   routeOrMiddleware: PikkuMiddleware[] | string,
@@ -157,23 +138,51 @@ export const addHTTPMiddleware = (
   addHTTPMiddlewareCore(routeOrMiddleware as any, middleware as any)
 }
 
+/**
+ * The shape of channel middleware — it runs around the connection and its
+ * messages rather than around a single request.
+ */
 export type PikkuChannelMiddleware<RequiredServices extends Services = Services, Event = unknown> = CorePikkuChannelMiddleware<RequiredServices, Event>
 
+/**
+ * Declares middleware for a channel — it runs around the connection and its
+ * messages rather than around a single request.
+ *
+ * @example snippet: channelMiddleware
+ */
 export const pikkuChannelMiddleware = <RequiredServices extends Services = Services, Event = unknown>(
   middleware: PikkuChannelMiddleware<RequiredServices, Event>
 ): PikkuChannelMiddleware<RequiredServices, Event> => {
   return middleware
 }
 
+/**
+ * Declares channel middleware that takes options, so one definition can be
+ * wired several times with different configuration.
+ *
+ * @example snippet: channelMiddlewareFactory
+ */
 export const pikkuChannelMiddlewareFactory = <In = any>(
   factory: CorePikkuChannelMiddlewareFactory<In>
 ): CorePikkuChannelMiddlewareFactory<In> => {
   return factory
 }
 
+/**
+ * Attaches channel middleware to every channel carrying the given tag, so the
+ * channels themselves stay free of the wiring.
+ *
+ * @example snippet: addChannelMiddleware
+ */
 export const addChannelMiddleware = (tag: string, middleware: PikkuChannelMiddleware[]) =>
   addChannelMiddlewareCore(tag, middleware, ${packageNameValue})
 
+/**
+ * Declares middleware for an agent run — hooks around the model call, its tool
+ * calls and the run's state.
+ *
+ * @example snippet: agentMiddleware
+ */
 export const pikkuAgentMiddleware = <
   State extends Record<string, unknown> = Record<string, unknown>,
   RequiredServices extends SingletonServices = WiredSingletonServices,

package/dist/src/functions/wirings/queue/serialize-queue-types.js

@@ -25,6 +25,8 @@ type QueueWiring<In, Out> = CoreQueueWorker<PikkuFunctionConfig<In, Out, 'sessio
  * Workers process background jobs from queues.
  *
  * @param queueWorker - Queue worker definition with job handler
+ *
+ * @example snippet: wireQueue
  */
 export const wireQueueWorker = (queueWorker: QueueWiring<any, any>) => {
   wireQueueWorkerCore(queueWorker as any)

package/dist/src/functions/wirings/scheduler/serialize-scheduler-types.js

@@ -25,6 +25,8 @@ type SchedulerWiring = CoreScheduledTask<PikkuFunctionConfig<void, void, 'sessio
  * Tasks run based on cron expressions and are sessionless.
  *
  * @param task - Scheduled task definition with cron expression and handler
+ *
+ * @example snippet: wireScheduler
  */
 export const wireScheduler = (task: SchedulerWiring) => {
   wireSchedulerCore(task as any)

package/dist/src/functions/wirings/secrets/serialize-secrets-types.js

@@ -61,6 +61,10 @@ import './pikku-secrets-meta.gen.json' with { type: 'json' }`);
     }
     return `${imports.join('\n')}
 
+/**
+ * Every secret this project declares with \`defineSecret\`, keyed by name. It is
+ * what gives \`secrets.getSecret('NAME')\` a real type.
+ */
 export type CredentialsMap = {
 ${mapEntries.join('\n')}
 }
@@ -69,6 +73,10 @@ const CREDENTIALS_META: Record<string, CredentialMeta> = {
 ${metaEntries.join(',\n')}
 }
 
+/**
+ * The \`secrets\` service as this project sees it: \`getSecret('NAME')\` resolves
+ * the value's type from \`CredentialsMap\` instead of returning \`unknown\`.
+ */
 export class TypedSecretService extends CoreTypedSecretService<CredentialsMap> {
   constructor(secrets: SecretService) {
     super(secrets, CREDENTIALS_META)

package/dist/src/functions/wirings/setup/serialize-setup-types.d.ts

@@ -4,4 +4,4 @@
  * the function types keeps `#pikku/function` to what a feature imports every
  * day and `#pikku/setup` to what bootstrap imports and never touches again.
  */
-export declare const serializeSetupTypes: (functionTypesImportPath: string, configTypeImport: string, configTypeName: string | undefined, requiredServicesTypeImport: string) => string;
+export declare const serializeSetupTypes: (functionTypesImportPath: string, configTypeImport: string, configTypeName: string | undefined, requiredServicesTypeImport: string, allowShadowedServices?: string[]) => string;

package/dist/src/functions/wirings/setup/serialize-setup-types.js

@@ -4,7 +4,7 @@
  * the function types keeps `#pikku/function` to what a feature imports every
  * day and `#pikku/setup` to what bootstrap imports and never touches again.
  */
-export const serializeSetupTypes = (functionTypesImportPath, configTypeImport, configTypeName, requiredServicesTypeImport) => {
+export const serializeSetupTypes = (functionTypesImportPath, configTypeImport, configTypeName, requiredServicesTypeImport, allowShadowedServices = []) => {
     return `/**
  * Config and service factory definitions, declared once per application
  */
@@ -14,6 +14,10 @@ import { CreateWireServices } from '@pikku/core/types'
 import type { SingletonServices } from '${functionTypesImportPath}'
 ${configTypeImport}
 ${requiredServicesTypeImport}
+/**
+ * This project's own config — whatever \`createConfig\` returns. Every singleton
+ * service is built from it.
+ */
 ${!configTypeName ? 'export type Config = any' : configTypeName === 'Config' ? 'export type { Config }' : `export type { ${configTypeName} as Config }`}
 
 /**
@@ -23,15 +27,7 @@ ${!configTypeName ? 'export type Config = any' : configTypeName === 'Config' ? '
  * @param func - Config factory function that returns your application's config
  * @returns The config factory function
  *
- * @example
- * \`\`\`typescript
- * export const createConfig = pikkuConfig(async () => {
- *   return {
- *     apiUrl: process.env.API_URL || 'http://localhost:3000',
- *     dbUrl: process.env.DATABASE_URL
- *   }
- * })
- * \`\`\`
+ * @example snippet: pikkuConfig
  */
 export const pikkuConfig = (
   func: (variables?: any, ...args: any[]) => Promise<Config>
@@ -61,6 +57,18 @@ export const pikkuServices = (
   return async (config: Config, existingServices: Partial<SingletonServices> = {}) => {
     const createdServices = await func(config, existingServices)
     const services = { ...existingServices, ...createdServices }
+    const allowedToShadow = new Set<string>(${JSON.stringify(allowShadowedServices)})
+    const shadowed = Object.keys(createdServices).filter(
+      (name) =>
+        !allowedToShadow.has(name) &&
+        (existingServices as any)[name] !== undefined &&
+        (existingServices as any)[name] !== (createdServices as any)[name]
+    )
+    if (shadowed.length > 0) {
+      ;(services as any).logger?.warn?.(
+        \`createSingletonServices returned its own \${shadowed.join(', ')}, discarding what the host passed in. A host only passes a service it has already configured — a \\\`secrets\\\` holding this deployment's values, a \\\`kysely\\\` bound to its database — so the replacement starts empty and fails later somewhere unrelated. Write \\\`existingServices.<name> ?? new Own...\\\` to take the host's when there is one and still work standalone, or list the name under \\\`allowShadowedServices\\\` in pikku.config.json if replacing it is deliberate.\`
+      )
+    }
     const authFactory = __pikkuState(null, 'package', 'authFactory')
     if (authFactory) {
       let authInstance: Promise<unknown> | undefined
@@ -87,15 +95,7 @@ export const pikkuServices = (
  * @param func - Wire services factory function
  * @returns The wire services factory function
  *
- * @example
- * \`\`\`typescript
- * export const createWireServices = pikkuWireServices(async (services, wire) => {
- *   const session = await wire.session?.get()
- *   return {
- *     userCache: new UserCache(session?.userId)
- *   }
- * })
- * \`\`\`
+ * @example snippet: shopWireServices
  */
 export const pikkuWireServices = (
   func: (

package/dist/src/functions/wirings/triggers/serialize-trigger-types.js

@@ -147,6 +147,8 @@ ${addon
  * Runs everywhere — inspector extracts at build time.
  *
  * @param trigger - Trigger definition with name and function config
+ *
+ * @example snippet: wireTrigger
  */
 export const wireTrigger = (
   trigger: TriggerWiring
@@ -160,6 +162,8 @@ export const wireTrigger = (
  * Only imported in the trigger worker process.
  *
  * @param source - Trigger source with name, func, and input
+ *
+ * @example snippet: wireTriggerSource
  */
 export const wireTriggerSource = <TInput = unknown, TOutput = unknown>(
   source: TriggerSource<TInput, TOutput>

package/dist/src/functions/wirings/variables/serialize-variables-types.js

@@ -52,6 +52,10 @@ import './pikku-variables-meta.gen.json' with { type: 'json' }`);
     }
     return `${imports.join('\n')}
 
+/**
+ * Every variable this project declares with \`defineVariable\`, keyed by name. It
+ * is what gives \`variables.get('NAME')\` a real type.
+ */
 export interface VariablesMap {
 ${mapEntries.join('\n')}
 }
@@ -60,6 +64,10 @@ const TYPED_VARIABLES_META: Record<string, VariableMeta> = {
 ${metaEntries.join(',\n')}
 }
 
+/**
+ * The \`variables\` service as this project sees it: \`get('NAME')\` resolves the
+ * value's type from \`VariablesMap\` instead of returning \`unknown\`.
+ */
 export class TypedVariablesService extends CoreTypedVariablesService<VariablesMap> {
   constructor(variables: VariablesService) {
     super(variables, TYPED_VARIABLES_META)

package/dist/src/functions/wirings/workflow/serialize-personas.js

@@ -28,6 +28,10 @@ export type PersonaName = keyof typeof personaConfigs
 export const personaList: ResolvedPersona[] = Object.values(personaConfigs)
 
 export type AgentName = keyof AgentMap & string
+/**
+ * The personas this project declares, keyed by name — the \`actors\` a scenario
+ * step runs as.
+ */
 export type TypedPersonas = Record<
   PersonaName,
   ScenarioPersona<AgentName, FlattenedRPCMap>

package/dist/src/functions/wirings/workflow/serialize-scenario-types.js

@@ -159,6 +159,8 @@ export type PikkuScenarioHook<
  * Declares a scenario hook. Returns the function verbatim — a hook is never
  * registered, so this exists purely to give an inline hook a call site to be
  * contextually typed from, the way every other pikku primitive is.
+ *
+ * @example snippet: scenarioHook
  */
 export function pikkuScenarioHook<In = unknown, Ctx = unknown>(
   hook: PikkuFunctionScenario<In, void, Ctx>
@@ -171,6 +173,8 @@ export function pikkuScenarioHook<In = unknown, Ctx = unknown>(
  * Steps run as actors over the REAL transport — \`scenario.do(step, rpc,
  * data, { actor: actors.yasser })\` — so flows double as e2e tests and
  * staged/production health checks (no state reset; scope what you create).
+ *
+ * @example snippet: scenarioBasics
  */
 export function pikkuScenario<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
@@ -252,6 +256,8 @@ type PikkuFeatureConfig<Scenarios extends readonly unknown[]> = {
  *   ],
  * })
  * \`\`\`
+ *
+ * @example snippet: scenarioFeature
  */
 export function pikkuFeature<const Scenarios extends readonly unknown[]>(
   config: PikkuFeatureConfig<Scenarios>
@@ -376,6 +382,8 @@ type PikkuScenarioStepConfig<In, Out, HasActor extends boolean = false> =
  *
  * Steps are deliberately NOT registered as RPCs: a browser-driving step must
  * never be network-callable.
+ *
+ * @example snippet: scenarioStepDefinition
  */
 export function pikkuScenarioStep<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
@@ -466,6 +474,8 @@ type PikkuSubjectScenarioStepConfig<In, Out> =
  *
  * 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.
+ *
+ * @example snippet: platformStep
  */
 export function pikkuPlatformScenarioStep<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
@@ -494,6 +504,8 @@ export function pikkuPlatformScenarioStep(config: any) {
  *
  * Local-test-only, and never in a virtual user's catalogue: one that could
  * invoke this would forge its own payment success.
+ *
+ * @example snippet: addonStep
  */
 export function pikkuAddonScenarioStep<
   InputSchema extends StandardSchemaV1 | undefined = undefined,

package/dist/src/functions/wirings/workflow/serialize-workflow-types.js

@@ -17,6 +17,10 @@ import type { FlattenedRPCMap } from '${rpcMapImportPath}'
 import type { FlattenedWorkflowMap } from '${workflowMapImportPath}'
 import type { AgentMap as FlattenedAgentMap } from '${agentMapImportPath}'
 
+/**
+ * The wire a workflow step is handed: \`step\` to run one durably, plus sleeping,
+ * waiting for a signal and asking for approval.
+ */
 export interface TypedWorkflow extends PikkuWorkflowWire {
   do<K extends keyof FlattenedRPCMap>(
     stepName: string,
@@ -47,6 +51,9 @@ import type { ScopeId } from '${scopesImportPath}'
 import { PikkuError } from '@pikku/core/errors'
 import type { CorePermissionGroup } from '@pikku/core/function'
 
+/**
+ * The shape of a workflow's body — services, input, and the workflow wire.
+ */
 export type PikkuFunctionWorkflow<
   In = unknown,
   Out = never
@@ -70,6 +77,13 @@ ${sharedWorkflowConfigFields}
   permissions?: InputSchema extends StandardSchemaV1 ? CorePermissionGroup<PikkuPermission<InferSchemaOutput<InputSchema>>> : undefined
 }
 
+/**
+ * Declares a workflow: the DSL form, where each step is awaited in order and
+ * the runner persists progress between them so a restart resumes rather than
+ * replays. The default choice for a workflow.
+ *
+ * @example snippet: workflowSteps
+ */
 export function pikkuWorkflowFunc<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
@@ -85,6 +99,13 @@ export function pikkuWorkflowFunc(func: any) {
   return typeof func === 'function' ? { func } : func
 }
 
+/**
+ * Declares a workflow whose control flow the DSL cannot express - a loop whose
+ * bound is only known at runtime, or branching that rejoins. An escape hatch:
+ * reach for \`pikkuWorkflowFunc\` unless the shape genuinely needs this.
+ *
+ * @example snippet: workflowComplexFunc
+ */
 export function pikkuWorkflowComplexFunc<
   InputSchema extends StandardSchemaV1 | undefined = undefined,
   OutputSchema extends StandardSchemaV1 | undefined = undefined
@@ -167,6 +188,13 @@ type GraphNodeConfigMap<FuncMap extends Record<string, string>> = {
 
 type NextConfig<NodeIds extends string> = NodeIds | NodeIds[] | { if: string; then: NodeIds; else?: NodeIds }
 
+/**
+ * Declares a workflow as an explicit node graph, for a genuine cyclic
+ * dependency or a Node-only import the DSL cannot carry. The last resort of the
+ * three.
+ *
+ * @example snippet: workflowGraph
+ */
 export function pikkuWorkflowGraph<
   const FuncMap extends Record<
     string,

package/dist/src/services.js

@@ -69,12 +69,14 @@ export const defaultCLIRenderer = pikkuCLIRender((_services, data) => {
 /**
  * Commands that must work in a directory that is not a Pikku project.
  * `skills install` writes agent skills into a repo that has no pikku.config.json
- * yet — that is the whole point of it — so it cannot require one to start.
+ * yet — that is the whole point of it — so it cannot require one to start, and
+ * `doc` answers from the surface shipped inside the CLI rather than the project.
  */
 const CONFIG_FREE_COMMANDS = new Set([
     'skills',
     'skills.list',
     'skills.install',
+    'doc',
 ]);
 export const createConfig = async (_variablesService, data, commandPath = []) => {
     // Determine log level based on CLI flags with precedence:
@@ -166,6 +168,10 @@ export const createSingletonServices = async (config) => {
     let unfilteredStateIsSetupOnly = false;
     let inspectedTsGeneration;
     let inspectorInvalidated = false;
+    const releaseProgram = (state) => {
+        if (state)
+            state.program = undefined;
+    };
     /**
      * `unfiltered` is for commands that RUN the project rather than generate from
      * it. The CLI filters narrow what gets written out, which is meaningless to a
@@ -304,6 +310,7 @@ export const createSingletonServices = async (config) => {
             logger.debug(`Inspector took ${Date.now() - inspectStart}ms`);
             inspectedTsGeneration = tsGenerationAtInspect;
             inspectorInvalidated = false;
+            releaseProgram(unfilteredState);
             if ('diagnostics' in unfilteredState &&
                 unfilteredState.diagnostics.length > 0) {
                 processDiagnostics(unfilteredState.diagnostics, config.lint);

package/dist/src/utils/persona-credentials.js

@@ -19,7 +19,11 @@ export const CREATE_MISSING_VARIABLE = 'PIKKU_PERSONA_CREATE_MISSING';
 export const resolvePersonaCredentials = async (variables, what) => {
     const token = await variables.get(OPERATOR_TOKEN_VARIABLE);
     if (token) {
-        const createMissing = (await variables.get(CREATE_MISSING_VARIABLE)) === 'true';
+        // `variables.get` JSON-parses, so `PIKKU_PERSONA_CREATE_MISSING=true`
+        // arrives as the boolean `true` and never equalled the string. The
+        // operator token survives the same parse only because a JWT is not
+        // valid JSON.
+        const createMissing = String(await variables.get(CREATE_MISSING_VARIABLE)) === 'true';
         return { operator: { token, createMissing } };
     }
     const secret = await variables.get(ACTOR_SECRET_VARIABLE);