@pikku/cli 0.12.92 → 0.12.96

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[];
 }

package/dist/src/fabric/functions/validate.function.js

@@ -6,6 +6,7 @@ import { createRequire } from 'node:module';
 import { pikkuSessionlessFunc } from '../../../.pikku/pikku-types.gen.js';
 import { added, changed, removed, dim } from '../lib/output.js';
 import { typeCheckFrontends } from '../lib/frontend-typecheck.js';
+import { runKnowledgeValidate } from '@pikku/knowledge';
 const FindingSchema = z.object({
     id: z.string(),
     severity: z.enum(['error', 'warn', 'info']),
@@ -243,7 +244,7 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
                 key: 'console',
                 severity: 'error',
                 surface: 'app introspection (console:getFunctionsMeta and friends) — the sandbox builder shows no functions',
-                value: '"auth"',
+                value: 'true',
             },
             {
                 key: 'rpc',
@@ -255,13 +256,13 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
                 key: 'agent',
                 severity: 'error',
                 surface: 'the agent endpoints (/rpc/agent/:agentName) — the agent playground 404s',
-                value: '"no-auth"',
+                value: 'true',
             },
             {
                 key: 'workflow',
                 severity: 'error',
                 surface: 'the workflow endpoints (/workflow/:workflowName/start) — triggering a workflow 404s',
-                value: '"no-auth"',
+                value: 'true',
             },
             {
                 key: 'events',
@@ -312,16 +313,21 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
     // ── required project files ────────────────────────────────────────────
     // These files must exist and be committed — they are seeded from the sandbox
     // but belong to the project so the AI agent can read and update them.
-    for (const relPath of [
-        'db/annotations.ts',
-        'knowledge/design-language.md',
-        'knowledge/security.md',
-        'knowledge/technology.md',
-    ]) {
+    for (const relPath of ['db/annotations.ts']) {
         if (!existsSync(join(root, relPath))) {
             w(`missing-required-file-${relPath.replace(/[^a-z0-9]/gi, '-')}`, `${relPath} is missing — this file must be committed to the project`, join(root, relPath), lines(`Create ${relPath} and commit it.`, 'The starter-template ships a stub you can copy as a starting point.'));
         }
     }
+    // ── knowledge base ─────────────────────────────────────────────────────
+    // Delegated to the shared checker rather than asserting a list of filenames.
+    // The three flat files this used to require (design-language.md, security.md,
+    // technology.md) are not a knowledge base — they are three documents nothing
+    // can link into, and the profile now organises the same content into sections
+    // of notes. Fabric adds decisions/design/ on top of what is checked here.
+    const knowledge = await runKnowledgeValidate(root, join(root, typeof pikkuConfig?.outDir === 'string' ? pikkuConfig.outDir : '.pikku'));
+    for (const finding of knowledge.findings) {
+        findings.push({ ...finding, path: join(root, finding.path) });
+    }
     const rootPkgPath = join(root, 'package.json');
     const rootPkg = await readJsonSafe(rootPkgPath);
     if (!rootPkg) {
@@ -671,11 +677,14 @@ export async function runValidate(startDir = process.cwd(), opts = {}) {
             // nothing — flagging it told every fresh scaffold to import a dialect it
             // must not use.
             const constructsKysely = /new\s+Kysely\s*[<(]/.test(servicesText);
-            if (dbEngine !== 'postgres' && usesKysely && constructsKysely && !usesLibsql) {
+            if (dbEngine !== 'postgres' &&
+                usesKysely &&
+                constructsKysely &&
+                !usesLibsql) {
                 e('services-wrong-db-adapter', 'services.ts uses Kysely but not LibsqlWebDialect — Fabric injects a Turso/libSQL DATABASE_URL at runtime, not a PostgreSQL URL', servicesPath, 'Import LibsqlWebDialect from @pikku/kysely-sqlite and replace the dialect: new Kysely({ dialect: new LibsqlWebDialect({ url: databaseUrl }) })');
             }
             if (usesProcessEnv) {
-                info('services-process-env', 'services.ts reads process.env directly — prefer variables.get() for portable secret/variable access', servicesPath, 'Replace process.env.SOME_VAR with await variables.get("SOME_VAR") — declare the binding with wireVariable/wireSecret; process.env is fine for optional/non-secret config');
+                info('services-process-env', 'services.ts reads process.env directly — prefer variables.get() for portable secret/variable access', servicesPath, 'Replace process.env.SOME_VAR with await variables.get("SOME_VAR") — declare the binding with defineVariable/defineSecret; process.env is fine for optional/non-secret config');
             }
             if (dbEngine !== 'postgres' &&
                 usesLibsql &&

package/dist/src/functions/commands/bootstrap.js

@@ -5,6 +5,9 @@ export const bootstrap = pikkuVoidFunc({
         await getInspectorState(false, true, true);
         // Before function types: they import ScopeId from the scopes codegen.
         await rpc.invoke('pikkuScopes', { bootstrap: true });
+        // Before function types too: personas import SystemRoleName.
+        await rpc.invoke('pikkuRoles', { bootstrap: true });
+        await rpc.invoke('pikkuPersonas', { bootstrap: true });
         await rpc.invoke('pikkuFunctionTypesSplit', { bootstrap: true });
         // Stub auth.types.ts (if better-auth is used) so the pikkuBetterAuth
         // re-export resolves before any user file is imported.

package/dist/src/functions/commands/dev-ai-runner.d.ts

@@ -7,10 +7,22 @@ import type { AIAgentRunnerService } from '@pikku/core/services';
  * has no equivalent, so agents 503 with AIProviderNotConfiguredError unless we
  * construct one here. When an OpenAI-compatible base URL + key are present
  * (fabric injects LITELLM_PROXY_URL/LITELLM_API_KEY; the standard OPENAI_*
- * vars are also honored) we point a single openai-compatible provider at it and
- * register it under every common provider prefix. Returns undefined when no AI
- * env is configured (agents stay disabled, with the clear downstream error) or
- * when the AI SDK packages aren't installed in the project.
+ * vars are also honored) we point one provider at it and register it under
+ * `'*'`, so every provider prefix resolves to it. The CLI ships the SDK rather
+ * than asking the project for it — behind a proxy one openai-compatible
+ * provider answers for `openai/…`, `anthropic/…` and `google/…` alike, so there
+ * was never a per-vendor package worth making somebody install. The project's
+ * own copies still win when it has them. Returns undefined when no AI env is
+ * configured (agents stay disabled, with the clear downstream error) or when
+ * the SDK packages cannot be loaded from either place.
+ *
+ * Audio does not work here: `@ai-sdk/openai-compatible` exposes only
+ * language/embedding/image models, so a voice agent under `pikku dev` throws
+ * `Provider does not support transcription models`. Fixing that means the full
+ * `@ai-sdk/openai` provider, which assumes OpenAI's own request specifics — a
+ * bad default for a path whose entire purpose is fronting arbitrary gateways.
+ * If it becomes worth it, delegate just `transcription`/`speech` to the full
+ * provider and leave everything else on this one.
  */
 export declare function createDevAIAgentRunner({ logger, projectRoot, variables, }: {
     logger: Logger;

package/dist/src/functions/commands/dev-ai-runner.js

@@ -1,19 +1,6 @@
 import { createRequire } from 'module';
 import { join } from 'path';
 import { pathToFileURL } from 'url';
-// Provider prefixes a fabric/proxy baseURL fronts. Models are written as
-// `openai/gpt-4o-mini`, `openai/deepseek-v4-flash`, etc. — the runner splits on
-// the first `/`, so the prefix only selects the provider entry and the bare
-// model name is forwarded to the OpenAI-compatible proxy, which routes it.
-const PROXY_PROVIDER_NAMES = [
-    'openai',
-    'anthropic',
-    'google',
-    'gemini',
-    'deepseek',
-    'xai',
-    'litellm',
-];
 /**
  * Build the AI agent runner for `pikku dev` from env.
  *
@@ -21,10 +8,22 @@ const PROXY_PROVIDER_NAMES = [
  * has no equivalent, so agents 503 with AIProviderNotConfiguredError unless we
  * construct one here. When an OpenAI-compatible base URL + key are present
  * (fabric injects LITELLM_PROXY_URL/LITELLM_API_KEY; the standard OPENAI_*
- * vars are also honored) we point a single openai-compatible provider at it and
- * register it under every common provider prefix. Returns undefined when no AI
- * env is configured (agents stay disabled, with the clear downstream error) or
- * when the AI SDK packages aren't installed in the project.
+ * vars are also honored) we point one provider at it and register it under
+ * `'*'`, so every provider prefix resolves to it. The CLI ships the SDK rather
+ * than asking the project for it — behind a proxy one openai-compatible
+ * provider answers for `openai/…`, `anthropic/…` and `google/…` alike, so there
+ * was never a per-vendor package worth making somebody install. The project's
+ * own copies still win when it has them. Returns undefined when no AI env is
+ * configured (agents stay disabled, with the clear downstream error) or when
+ * the SDK packages cannot be loaded from either place.
+ *
+ * Audio does not work here: `@ai-sdk/openai-compatible` exposes only
+ * language/embedding/image models, so a voice agent under `pikku dev` throws
+ * `Provider does not support transcription models`. Fixing that means the full
+ * `@ai-sdk/openai` provider, which assumes OpenAI's own request specifics — a
+ * bad default for a path whose entire purpose is fronting arbitrary gateways.
+ * If it becomes worth it, delegate just `transcription`/`speech` to the full
+ * provider and leave everything else on this one.
  */
 export async function createDevAIAgentRunner({ logger, projectRoot, variables, }) {
     // Pair the URL with its matching key — coalescing each var independently could
@@ -43,28 +42,63 @@ export async function createDevAIAgentRunner({ logger, projectRoot, variables, }
         logger.debug('pikku dev: no AI provider env (OPENAI_BASE_URL/OPENAI_API_KEY or LITELLM_PROXY_URL/LITELLM_API_KEY) — AI agents disabled');
         return undefined;
     }
-    // Resolve from the project's node_modules — the AI SDK packages are the
-    // project's deps, not the CLI's, so they share the project's `ai` version.
-    const require = createRequire(pathToFileURL(join(projectRoot, 'package.json')).href);
+    // The project's own copies win, so an app that pins an `ai` version gets a
+    // runner built from that one rather than a second copy alongside it. The
+    // CLI's are the fallback: this function exists for projects that have not
+    // installed an AI SDK at all, and behind a proxy a single openai-compatible
+    // provider reaches every model, so making someone add three packages before
+    // agents work in dev buys nothing.
+    const fromProject = createRequire(pathToFileURL(join(projectRoot, 'package.json')).href);
+    //
+    // Both come from the same place or neither does. A provider built against one
+    // copy of `@ai-sdk/provider` handed to a runner built against another is the
+    // one combination that fails at call time rather than at load time, with an
+    // error about the model spec that names neither package.
+    const loadPair = async () => {
+        const project = ['@pikku/ai-vercel', '@ai-sdk/openai-compatible'].map((name) => {
+            try {
+                return pathToFileURL(fromProject.resolve(name)).href;
+            }
+            catch {
+                return undefined;
+            }
+        });
+        const [runner, provider] = project.every(Boolean)
+            ? project
+            : ['@pikku/ai-vercel', '@ai-sdk/openai-compatible'];
+        return Promise.all([import(runner), import(provider)]);
+    };
     let VercelAIAgentRunner;
     let createOpenAICompatible;
     try {
-        ;
-        ({ VercelAIAgentRunner } = await import(pathToFileURL(require.resolve('@pikku/ai-vercel')).href));
-        ({ createOpenAICompatible } = await import(pathToFileURL(require.resolve('@ai-sdk/openai-compatible')).href));
+        const [runnerModule, providerModule] = await loadPair();
+        ({ VercelAIAgentRunner } = runnerModule);
+        ({ createOpenAICompatible } = providerModule);
     }
     catch (error) {
-        logger.warn(`pikku dev: AI provider env is set but the AI SDK packages could not be loaded (install @pikku/ai-vercel, @ai-sdk/openai-compatible, and ai) — AI agents disabled: ${error instanceof Error ? error.message : String(error)}`);
+        logger.warn(`pikku dev: AI provider env is set but the AI SDK packages could not be loaded — AI agents disabled: ${error instanceof Error ? error.message : String(error)}`);
         return undefined;
     }
-    const buildProviders = (key) => {
-        const provider = createOpenAICompatible({
+    // One provider under '*', so every prefix a model might name resolves to the
+    // proxy — including ones nobody thought to list. This was a hardcoded array
+    // of seven names, which silently excluded everything else.
+    //
+    // `supportsStructuredOutputs` defaults to false, and the default fails in the
+    // worst available way: an `outputSchema` is dropped, the call degrades to
+    // bare `json_object`, and the model returns well-formed JSON with whatever
+    // keys it felt like. Nothing errors — the caller reads `undefined` off every
+    // field it asked for and behaves as though the model said nothing. Anything
+    // fronting this URL that is worth calling speaks `json_schema`; the ones that
+    // do not now fail loudly on the first schema'd call, which is the outcome we
+    // want over silently ignoring the schema.
+    const buildProviders = (key) => ({
+        '*': createOpenAICompatible({
             name: 'pikku-dev',
             baseURL,
             apiKey: key,
-        });
-        return Object.fromEntries(PROXY_PROVIDER_NAMES.map((name) => [name, provider]));
-    };
+            supportsStructuredOutputs: true,
+        }),
+    });
     logger.info(`pikku dev: AI agent runner wired to ${baseURL}`);
     return new VercelAIAgentRunner(buildProviders(apiKey), buildProviders);
 }

package/dist/src/functions/commands/dev.js

@@ -16,6 +16,8 @@ import { startCoverageService } from './start-coverage.js';
 import { createDevAIAgentRunner } from './dev-ai-runner.js';
 import { resolveConsoleMount } from './serve-console.js';
 import { serverReadyLine } from '../../server/server-ready.js';
+import { createEphemeralContentSigningJWT } from '../../server/content-signing-jwt.js';
+import { resolveScaffoldFeature } from '../../utils/resolve-scaffold-feature.js';
 export const dev = pikkuSessionlessFunc({
     remote: true,
     func: async ({ logger, config, getInspectorState, invalidateInspectorState, variables, devServerRunner, }, { port, watch, hmr, coverage, test }, { rpc }) => {
@@ -122,7 +124,7 @@ export const dev = pikkuSessionlessFunc({
         // project — an app bootstrap is what a deployed bundle imports, and coverage
         // endpoints have no business in one.
         if (config.scaffold?.scenarios) {
-            registerScenarioInstrumentation(config.scaffold.scenarios === 'auth');
+            registerScenarioInstrumentation(resolveScaffoldFeature('scenarios', config.scaffold.scenarios).auth);
         }
         const configModule = await loadUserModule(pikkuConfigFactory.file);
         const servicesModule = await loadUserModule(singletonServicesFactory.file);
@@ -150,8 +152,11 @@ export const dev = pikkuSessionlessFunc({
                 sizeLimit: userConfig.content.sizeLimit,
             }
             : undefined;
-        const localContent = localContentConfig
-            ? new LocalContent(localContentConfig, logger)
+        const contentSigningJWT = localContentConfig
+            ? createEphemeralContentSigningJWT()
+            : undefined;
+        const localContent = localContentConfig && contentSigningJWT
+            ? new LocalContent(localContentConfig, logger, contentSigningJWT)
             : undefined;
         const schedulerService = new InMemorySchedulerService();
         const aiStorage = kysely
@@ -239,7 +244,7 @@ export const dev = pikkuSessionlessFunc({
             port: resolvedPort,
             content: localContentConfig,
             ...(consoleMount ? { staticMounts: [consoleMount] } : {}),
-        }, logger);
+        }, logger, { contentSigningJWT });
         const lifecycle = await loadLifecycle();
         await pikkuServer.init();
         await lifecycle?.beforeStart?.(resolvedServices);

package/dist/src/functions/commands/enable.js

@@ -1,15 +1,12 @@
 import { readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
 import { pikkuVoidFunc } from '#pikku';
-const FEATURE_DEFAULTS = {
-    rpc: 'auth',
-    agent: 'auth',
-    console: 'auth',
-    scenarios: 'auth',
-    workflow: 'auth',
-    events: 'auth',
-    remoteRpc: 'no-auth',
-};
+/**
+ * Remote RPC workers carry no auth dimension — `serialize-remote-rpc.ts`
+ * hardcodes `auth: false` on what it generates — so enabling it writes a bare
+ * `true` and there is nothing to opt out of.
+ */
+const NO_AUTH_DIMENSION = new Set(['remoteRpc']);
 async function enableFeature(feature, logger, config, data) {
     const noAuth = data?.noAuth ?? false;
     const configPath = join(config.configDir, 'pikku.config.json');
@@ -21,18 +18,17 @@ async function enableFeature(feature, logger, config, data) {
     if (!json.scaffold.pikkuDir) {
         json.scaffold.pikkuDir = 'pikku';
     }
-    // The console is an admin surface — every RPC requires a session, so it can
-    // never be scaffolded no-auth (the --no-auth flag is ignored for it).
-    const value = feature === 'webhook'
-        ? true
-        : feature === 'console'
-            ? 'auth'
-            : noAuth
-                ? 'no-auth'
-                : FEATURE_DEFAULTS[feature];
+    // `true` is enabled AND authenticated. Only an explicit --no-auth writes the
+    // object form, so a feature can never be turned on public by accident.
+    //
+    // The console is an admin surface — every RPC requires a session, so
+    // --no-auth is ignored for it.
+    const wantsPublic = noAuth && feature !== 'console' && !NO_AUTH_DIMENSION.has(feature);
+    const value = feature === 'webhook' ? true : wantsPublic ? { auth: false } : true;
     json.scaffold[feature] = value;
     await writeFile(configPath, JSON.stringify(json, null, 2) + '\n', 'utf-8');
-    logger.info(`Enabled scaffold.${feature} = '${value}' in ${configPath}`);
+    logger.info(`Enabled scaffold.${feature} = ${JSON.stringify(value)} in ${configPath}` +
+        (wantsPublic ? ' (public — no session required)' : ''));
 }
 export const enableRpc = pikkuVoidFunc({
     func: async ({ logger, config }, data) => enableFeature('rpc', logger, config, data),

package/dist/src/functions/commands/{scenario-environment.d.ts → environment.d.ts}

@@ -1,22 +1,25 @@
 /**
- * Resolving `pikku scenario run <environment>` to the URLs the run targets.
+ * Resolving `pikku scenario run <environment>` and `pikku persona run
+ * <environment>` to the URLs the run targets.
  *
  * The configured environment is the base; `--api-url`/`--app-url` override it
  * for one invocation, which is what makes a suite runnable against a target
  * that only exists at run time (a freshly provisioned sandbox) without writing
  * a pikku.config.json per deployment.
  */
-/** One entry of `scenarios.environments` in pikku.config.json. */
-export interface ScenarioEnvironment {
+/** One entry of `environments` in pikku.config.json. */
+export interface PikkuEnvironment {
     apiUrl: string;
     signInPath?: string;
     rpcPath?: string;
     appUrl?: string;
+    /** Real consequences: only an `accountable` persona may run against it. */
+    production?: boolean;
 }
-export interface ResolveScenarioEnvironmentOptions {
+export interface ResolveEnvironmentOptions {
     /** The name given on the command line. Must exist in config. */
     environment: string;
-    environments: Record<string, ScenarioEnvironment>;
+    environments: Record<string, PikkuEnvironment>;
     /** `--api-url`, overriding the configured `apiUrl`. */
     apiUrl?: string;
     /** `--app-url`, overriding the configured `appUrl`. */
@@ -29,4 +32,4 @@ export interface ResolveScenarioEnvironmentOptions {
  * all see the same target. The environment is still looked up by name: the
  * flags override fields on a configured environment, they do not invent one.
  */
-export declare const resolveScenarioEnvironment: ({ environment, environments, apiUrl, appUrl, spawn, }: ResolveScenarioEnvironmentOptions) => ScenarioEnvironment;
+export declare const resolveEnvironment: ({ environment, environments, apiUrl, appUrl, spawn, }: ResolveEnvironmentOptions) => PikkuEnvironment;

package/dist/src/functions/commands/{scenario-environment.js → environment.js}

@@ -1,5 +1,6 @@
 /**
- * Resolving `pikku scenario run <environment>` to the URLs the run targets.
+ * Resolving `pikku scenario run <environment>` and `pikku persona run
+ * <environment>` to the URLs the run targets.
  *
  * The configured environment is the base; `--api-url`/`--app-url` override it
  * for one invocation, which is what makes a suite runnable against a target
@@ -35,14 +36,14 @@ const assertAbsoluteUrl = (flag, value) => {
  * all see the same target. The environment is still looked up by name: the
  * flags override fields on a configured environment, they do not invent one.
  */
-export const resolveScenarioEnvironment = ({ environment, environments, apiUrl, appUrl, spawn = false, }) => {
+export const resolveEnvironment = ({ environment, environments, apiUrl, appUrl, spawn = false, }) => {
     const configured = environments[environment];
     if (!configured) {
         const known = Object.keys(environments);
-        throw new Error(`Unknown scenario environment '${environment}'. ` +
+        throw new Error(`Unknown environment '${environment}'. ` +
             (known.length
                 ? `Configured environments: ${known.join(', ')}`
-                : `Add scenarios.environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
+                : `Add environments to pikku.config.json, e.g. { "${environment}": { "apiUrl": "https://app.example.com/api" } }`));
     }
     const resolved = { ...configured };
     if (apiUrl !== undefined) {

package/dist/src/functions/commands/knowledge-index.d.ts

@@ -0,0 +1,30 @@
+import { renderKnowledgeIndex } from '../knowledge/render.js';
+export declare const knowledgeIndex: import("#pikku").PikkuFunctionConfig<{
+    check?: boolean | undefined;
+}, {
+    ok: boolean;
+    check: boolean;
+    files: {
+        path: string;
+        action: "unchanged" | "created" | "updated";
+    }[];
+}, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<{
+    check?: boolean | undefined;
+}, {
+    ok: boolean;
+    check: boolean;
+    files: {
+        path: string;
+        action: "unchanged" | "created" | "updated";
+    }[];
+}, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<{
+    check?: boolean | undefined;
+}, {
+    ok: boolean;
+    check: boolean;
+    files: {
+        path: string;
+        action: "unchanged" | "created" | "updated";
+    }[];
+}, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export { renderKnowledgeIndex };

package/dist/src/functions/commands/knowledge-index.js

@@ -0,0 +1,11 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { runKnowledgeIndex } from '@pikku/knowledge';
+import { renderKnowledgeIndex } from '../knowledge/render.js';
+import { KnowledgeIndexInputSchema, KnowledgeIndexOutputSchema, } from '../knowledge/schemas.js';
+export const knowledgeIndex = pikkuSessionlessFunc({
+    description: "Refresh every index.md so each section lists the notes actually in it, replacing only the generated block and leaving each index's prose alone.",
+    input: KnowledgeIndexInputSchema,
+    output: KnowledgeIndexOutputSchema,
+    func: async ({ config }, { check }) => runKnowledgeIndex(config.rootDir, check ?? false),
+});
+export { renderKnowledgeIndex };

package/dist/src/functions/commands/knowledge-validate.d.ts

@@ -0,0 +1,33 @@
+import { renderKnowledgeValidate } from '../knowledge/render.js';
+export declare const knowledgeValidate: import("#pikku").PikkuFunctionConfig<Record<string, never>, {
+    ok: boolean;
+    notes: number;
+    findings: {
+        id: string;
+        severity: "warn" | "error" | "info";
+        message: string;
+        path: string;
+        fixHint: string;
+    }[];
+}, "rpc" | "session", import("#pikku").PikkuFunctionSessionless<Record<string, never>, {
+    ok: boolean;
+    notes: number;
+    findings: {
+        id: string;
+        severity: "warn" | "error" | "info";
+        message: string;
+        path: string;
+        fixHint: string;
+    }[];
+}, "rpc" | "session", import("#pikku").WiredServices> | import("#pikku").PikkuFunction<Record<string, never>, {
+    ok: boolean;
+    notes: number;
+    findings: {
+        id: string;
+        severity: "warn" | "error" | "info";
+        message: string;
+        path: string;
+        fixHint: string;
+    }[];
+}, "rpc" | "session", import("#pikku").WiredServices>, undefined, undefined>;
+export { renderKnowledgeValidate };

package/dist/src/functions/commands/knowledge-validate.js

@@ -0,0 +1,11 @@
+import { pikkuSessionlessFunc } from '#pikku';
+import { runKnowledgeValidate } from '@pikku/knowledge';
+import { renderKnowledgeValidate } from '../knowledge/render.js';
+import { KnowledgeValidateInputSchema, KnowledgeValidateOutputSchema, } from '../knowledge/schemas.js';
+export const knowledgeValidate = pikkuSessionlessFunc({
+    description: 'Check the knowledge base against the app-project profile: every note typed, every section indexed, every slice gated, and every resource: pointing at something that still exists.',
+    input: KnowledgeValidateInputSchema,
+    output: KnowledgeValidateOutputSchema,
+    func: async ({ config }) => runKnowledgeValidate(config.rootDir, config.outDir),
+});
+export { renderKnowledgeValidate };

package/dist/src/functions/commands/new-addon.d.ts

@@ -9,6 +9,24 @@
  * the only option there.
  */
 export declare function resolveAddonDepProtocol(baseDir: string): string;
+export interface AddonVars {
+    name: string;
+    camelName: string;
+    pascalName: string;
+    screamingName: string;
+    displayName: string;
+    description: string;
+    category: string;
+    addonDepProtocol: string;
+}
+export declare function getAddonFiles(vars: AddonVars, flags: {
+    secret: boolean;
+    variable: boolean;
+    oauth: boolean;
+    credential?: 'apikey' | 'bearer' | 'oauth2';
+    /** Delegated login: credential is the upstream token + expiry, checked per call. */
+    delegated?: boolean;
+}): Record<string, string>;
 export declare const pikkuNewAddon: import("#pikku").PikkuFunctionConfig<{
     name: string;
     displayName?: string;