@pikku/cli 0.12.91 → 0.12.93

package/dist/src/cli.wiring.js

@@ -29,6 +29,8 @@ import { scopesAudit } from './functions/commands/scopes-audit.js';
 import { scopesPrune } from './functions/commands/scopes-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 { pikkuVersionsInit } from './functions/commands/versions-init.js';
 import { pikkuEmailsInit } from './functions/commands/emails-init.js';
@@ -375,6 +377,27 @@ wireCLI({
                 }),
             },
         },
+        knowledge: {
+            description: 'Inspect and maintain the knowledge base — what this app is, in the language its users use',
+            subcommands: {
+                validate: pikkuCLICommand({
+                    func: knowledgeValidate,
+                    render: renderKnowledgeValidate,
+                    description: 'Check the knowledge base against the app-project profile, including every resource: reference',
+                }),
+                index: pikkuCLICommand({
+                    func: knowledgeIndex,
+                    render: renderKnowledgeIndex,
+                    description: 'Refresh every index.md so each section lists the notes actually in it',
+                    options: {
+                        check: {
+                            description: 'Report stale indexes without writing anything, for use as a CI gate',
+                            default: false,
+                        },
+                    },
+                }),
+            },
+        },
         workspace: {
             description: 'Workspace-level validation and maintenance commands',
             subcommands: {
@@ -427,6 +450,12 @@ wireCLI({
                             description: 'Keep every stack frame on a failure. Without it, only the project’s own frames are shown',
                             default: false,
                         },
+                        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",
+                        },
+                        appUrl: {
+                            description: "Override the environment's appUrl for this run (the frontend browser steps navigate against)",
+                        },
                     },
                 }),
                 list: pikkuCLICommand({

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 { isScenarioFunction, withoutScenarios, withoutScenarioWorkflows, } from '../../functions/wirings/scenarios/scenario-partition.js';
 export function analyzeDeployment(state, options) {
     const serverlessIncompatible = new Set(options.serverlessIncompatible ?? []);
     const defaultTarget = options.defaultTarget ?? 'serverless';
@@ -18,7 +19,13 @@ export function analyzeDeployment(state, options) {
     const agents = [];
     const mcpEndpoints = [];
     const workflows = [];
-    const functionsMeta = state.functions.meta;
+    // Scenarios, features and steps are test artifacts that happen to be built out
+    // of functions and workflows, so without this they analyze like application
+    // code: every scenario became its own unit, its own `WorkflowDefinition` and —
+    // because a scenario IS a workflow — a `wf-orchestrator-<scenario>` queue that
+    // a provider would then create in production.
+    const functionsMeta = withoutScenarios(state.functions.meta);
+    const graphMeta = withoutScenarioWorkflows(state.workflows.graphMeta);
     const httpMeta = state.http.meta;
     // ── Step 1: Create function units ──────────────────────────────────
     // Each function gets one unit. Collect all its triggers.
@@ -190,9 +197,19 @@ export function analyzeDeployment(state, options) {
         });
     }
     // ── Step 3: MCP gateway ────────────────────────────────────────────
-    const mcpToolIds = values(state.mcpEndpoints.toolsMeta).map((t) => t.pikkuFuncId);
-    const mcpResourceIds = values(state.mcpEndpoints.resourcesMeta).map((r) => r.pikkuFuncId);
-    const mcpPromptIds = values(state.mcpEndpoints.promptsMeta).map((p) => p.pikkuFuncId);
+    // The MCP metas are keyed by wiring, not by function, so they are the one
+    // place a scenario or step id can still arrive from raw state. A gateway that
+    // lists one would depend on a unit that was never emitted.
+    const deployableFuncId = (funcId) => !isScenarioFunction(state.functions.meta[funcId]);
+    const mcpToolIds = values(state.mcpEndpoints.toolsMeta)
+        .map((t) => t.pikkuFuncId)
+        .filter(deployableFuncId);
+    const mcpResourceIds = values(state.mcpEndpoints.resourcesMeta)
+        .map((r) => r.pikkuFuncId)
+        .filter(deployableFuncId);
+    const mcpPromptIds = values(state.mcpEndpoints.promptsMeta)
+        .map((p) => p.pikkuFuncId)
+        .filter(deployableFuncId);
     // Include functions explicitly marked mcp: true
     for (const [funcId, funcMeta] of entries(functionsMeta)) {
         if (funcMeta.mcp &&
@@ -248,7 +265,7 @@ export function analyzeDeployment(state, options) {
         });
     }
     // ── Step 5: Workflows ──────────────────────────────────────────────
-    buildWorkflows(state.workflows.graphMeta, functionsMeta, { ...state.rpc?.exposedMeta, ...state.rpc?.internalMeta }, httpMeta, units, workflows, queues, workflowQueues);
+    buildWorkflows(graphMeta, functionsMeta, { ...state.rpc?.exposedMeta, ...state.rpc?.internalMeta }, httpMeta, units, workflows, queues, workflowQueues);
     // ── Step 6: Ensure function units exist for gateway dependencies ───
     // Gateways depend on function units. If a function is only used via
     // a gateway (not directly wired to HTTP/queue/cron), it still needs

package/dist/src/deploy/build-pipeline.js

@@ -8,6 +8,7 @@ import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { mkdir, writeFile, copyFile } from 'node:fs/promises';
 import { analyzeDeployment } from './analyzer/index.js';
+import { withoutScenarios } from '../functions/wirings/scenarios/scenario-partition.js';
 import { generatePerUnitCodegen } from './codegen/per-unit-codegen.js';
 import { generateServerEntrySource, SERVER_DOCKERFILE, SERVER_DOCKERIGNORE, } from './server-entry.js';
 const MERGED_SERVER_UNIT_NAME = 'pikku-server-container';
@@ -63,7 +64,10 @@ export async function runBuildPipeline(options) {
             name: unitName,
             role: 'function',
             target: 'serverless',
-            functionIds: Object.keys(inspectorState.functions.meta),
+            // Scenarios and steps are excluded for the same reason the analyzer drops
+            // them: a single-unit bundle is still a deployment, and a test harness has
+            // no business inside one.
+            functionIds: Object.keys(withoutScenarios(inspectorState.functions.meta)),
             services: [],
             dependsOn: [],
             handlers: [],

package/dist/src/fabric/fabric-commands.d.ts

@@ -451,37 +451,65 @@ export declare const fabricCommands: {
                 value?: string | undefined;
                 force?: boolean | undefined;
             }, {
-                ok: boolean;
+                name: string;
+                keyId: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
                 name: string;
                 branch: string;
                 value?: string | undefined;
                 force?: boolean | undefined;
             }, {
-                ok: boolean;
+                name: string;
+                keyId: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
                 name: string;
                 branch: string;
                 value?: string | undefined;
                 force?: boolean | undefined;
             }, {
-                ok: boolean;
+                name: string;
+                keyId: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
             list: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
                 branch: string;
                 json?: boolean | undefined;
             }, {
-                names: string[];
+                secrets: {
+                    name: string;
+                    updatedAt: string;
+                }[];
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
                 branch: string;
                 json?: boolean | undefined;
             }, {
-                names: string[];
+                secrets: {
+                    name: string;
+                    updatedAt: string;
+                }[];
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
                 branch: string;
                 json?: boolean | undefined;
             }, {
-                names: string[];
+                secrets: {
+                    name: string;
+                    updatedAt: string;
+                }[];
+            }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
+            rotate: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
+                branch: string;
+                force?: boolean | undefined;
+            }, {
+                retiredKeyId: string;
+            }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
+                branch: string;
+                force?: boolean | undefined;
+            }, {
+                retiredKeyId: string;
+            }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
+                branch: string;
+                force?: boolean | undefined;
+            }, {
+                retiredKeyId: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
         };
     };
@@ -622,21 +650,21 @@ export declare const fabricCommands: {
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>, import("../../.pikku/pikku-types.gen.js").PikkuMiddleware, (services: import("../../types/application-types.js").SingletonServices, data: any, session?: import("../../types/application-types.js").UserSession | undefined) => void | Promise<void>, string>;
             add: import("@pikku/core/cli").CoreCLICommandConfig<import("../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
                 hostname: string;
-                target?: "api" | "app" | undefined;
+                target?: "app" | "api" | undefined;
                 apiUrl?: string | undefined;
             }, {
                 hostname: string;
                 cnameTarget: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
                 hostname: string;
-                target?: "api" | "app" | undefined;
+                target?: "app" | "api" | undefined;
                 apiUrl?: string | undefined;
             }, {
                 hostname: string;
                 cnameTarget: string;
             }, "rpc" | "session", import("../../.pikku/pikku-types.gen.js").WiredServices> | import("../../.pikku/pikku-types.gen.js").PikkuFunction<{
                 hostname: string;
-                target?: "api" | "app" | undefined;
+                target?: "app" | "api" | undefined;
                 apiUrl?: string | undefined;
             }, {
                 hostname: string;

package/dist/src/fabric/fabric-commands.js

@@ -31,6 +31,7 @@ import { FabricDbSchema, renderDbSchema, } from './functions/db-schema.function.
 import { FabricRollback } from './functions/rollback.function.js';
 import { FabricSecretsSet } from './functions/secrets-set.function.js';
 import { FabricSecretsList } from './functions/secrets-list.function.js';
+import { FabricSecretsRotate } from './functions/secrets-rotate.function.js';
 import { FabricLogs } from './functions/logs.function.js';
 import { FabricMetrics } from './functions/metrics.function.js';
 import { FabricTrace } from './functions/trace.function.js';
@@ -241,6 +242,17 @@ export const fabricCommands = defineCLICommands({
                     json: { description: 'Machine-readable output', default: false },
                 },
             }),
+            rotate: pikkuCLICommand({
+                func: FabricSecretsRotate,
+                description: "Retire a stage's sealing key (secrets must be set again)",
+                options: {
+                    branch: { description: 'Target branch', short: 'b' },
+                    force: {
+                        description: 'Confirm that existing secrets become unreadable',
+                        default: false,
+                    },
+                },
+            }),
         },
     },
     logs: pikkuCLICommand({

package/dist/src/fabric/functions/domains-add.function.d.ts

@@ -2,8 +2,8 @@ import { z } from 'zod';
 export declare const FabricDomainsAddInput: z.ZodObject<{
     hostname: z.ZodString;
     target: z.ZodOptional<z.ZodEnum<{
-        api: "api";
         app: "app";
+        api: "api";
     }>>;
     apiUrl: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
@@ -13,21 +13,21 @@ export declare const FabricDomainsAddOutput: z.ZodObject<{
 }, z.core.$strip>;
 export declare const FabricDomainsAdd: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
     hostname: string;
-    target?: "api" | "app" | undefined;
+    target?: "app" | "api" | undefined;
     apiUrl?: string | undefined;
 }, {
     hostname: string;
     cnameTarget: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
     hostname: string;
-    target?: "api" | "app" | undefined;
+    target?: "app" | "api" | undefined;
     apiUrl?: string | undefined;
 }, {
     hostname: string;
     cnameTarget: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
     hostname: string;
-    target?: "api" | "app" | undefined;
+    target?: "app" | "api" | undefined;
     apiUrl?: string | undefined;
 }, {
     hostname: string;

package/dist/src/fabric/functions/secrets-list.function.d.ts

@@ -4,21 +4,33 @@ export declare const FabricSecretsListInput: z.ZodObject<{
     json: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const FabricSecretsListOutput: z.ZodObject<{
-    names: z.ZodArray<z.ZodString>;
+    secrets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const FabricSecretsList: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
     branch: string;
     json?: boolean | undefined;
 }, {
-    names: string[];
+    secrets: {
+        name: string;
+        updatedAt: string;
+    }[];
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
     branch: string;
     json?: boolean | undefined;
 }, {
-    names: string[];
+    secrets: {
+        name: string;
+        updatedAt: string;
+    }[];
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
     branch: string;
     json?: boolean | undefined;
 }, {
-    names: string[];
+    secrets: {
+        name: string;
+        updatedAt: string;
+    }[];
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/secrets-list.function.js

@@ -2,13 +2,16 @@ import { z } from 'zod';
 import { pikkuSessionlessFunc } from '../../../.pikku/pikku-types.gen.js';
 import { resolveApiContext } from '../lib/config.js';
 import { getFabricRPC } from '../lib/http.js';
+import { resolveStageId } from '../lib/stage.js';
 export const FabricSecretsListInput = z.object({
     branch: z.string(),
     json: z.boolean().optional(),
 });
-export const FabricSecretsListOutput = z.object({ names: z.array(z.string()) });
+export const FabricSecretsListOutput = z.object({
+    secrets: z.array(z.object({ name: z.string(), updatedAt: z.string() })),
+});
 export const FabricSecretsList = pikkuSessionlessFunc({
-    description: 'List secret names visible to a stage (values never leave the server).',
+    description: 'List the secrets set on a stage, by name. Values are sealed to the stage and never leave it.',
     input: FabricSecretsListInput,
     output: FabricSecretsListOutput,
     func: async (_services, { branch, json }) => {
@@ -18,19 +21,18 @@ export const FabricSecretsList = pikkuSessionlessFunc({
         if (!ctx.projectId)
             throw new Error('No fabric project linked. Run `pikku fabric link` first.');
         const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
-        const result = await rpc.invoke('listStageSecrets', {
-            projectId: ctx.projectId,
-            branch,
-        });
+        const stageId = await resolveStageId(rpc, ctx.projectId, branch);
+        const result = await rpc.invoke('listStageSecretNames', { stageId });
         if (json) {
-            console.log(JSON.stringify({ branch, names: result.names }, null, 2));
+            console.log(JSON.stringify({ branch, secrets: result.secrets }, null, 2));
         }
-        else if (result.names.length === 0) {
+        else if (result.secrets.length === 0) {
             console.log(`[fabric] no secrets set on ${branch}`);
         }
         else {
-            for (const name of result.names)
-                console.log(name);
+            for (const { name, updatedAt } of result.secrets) {
+                console.log(`${name}\t${updatedAt}`);
+            }
         }
         return result;
     },

package/dist/src/fabric/functions/secrets-rotate.function.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+export declare const FabricSecretsRotateInput: z.ZodObject<{
+    branch: z.ZodString;
+    force: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const FabricSecretsRotateOutput: z.ZodObject<{
+    retiredKeyId: z.ZodString;
+}, z.core.$strip>;
+export declare const FabricSecretsRotate: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
+    branch: string;
+    force?: boolean | undefined;
+}, {
+    retiredKeyId: string;
+}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
+    branch: string;
+    force?: boolean | undefined;
+}, {
+    retiredKeyId: string;
+}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
+    branch: string;
+    force?: boolean | undefined;
+}, {
+    retiredKeyId: string;
+}, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/secrets-rotate.function.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { pikkuSessionlessFunc } from '../../../.pikku/pikku-types.gen.js';
+import { resolveApiContext } from '../lib/config.js';
+import { getFabricRPC } from '../lib/http.js';
+import { resolveStageId } from '../lib/stage.js';
+export const FabricSecretsRotateInput = z.object({
+    branch: z.string(),
+    force: z.boolean().optional(),
+});
+export const FabricSecretsRotateOutput = z.object({
+    retiredKeyId: z.string(),
+});
+export const FabricSecretsRotate = pikkuSessionlessFunc({
+    description: "Retire a stage's sealing key so the next deploy issues a new one. Secrets sealed to the old key must be set again.",
+    input: FabricSecretsRotateInput,
+    output: FabricSecretsRotateOutput,
+    func: async (_services, { branch, force }) => {
+        const ctx = await resolveApiContext();
+        if (!ctx.token)
+            throw new Error('Not logged in. Run `pikku fabric login` first.');
+        if (!ctx.projectId)
+            throw new Error('No fabric project linked. Run `pikku fabric link` first.');
+        if (!force) {
+            // Not a confirmation for politeness — this is the one operation here
+            // that destroys access to data. Fabric cannot read the sealed values, so
+            // it cannot carry them over, and nobody can undo it afterwards.
+            throw new Error(`Rotating the sealing key on ${branch} makes every secret already set on it unreadable — fabric cannot re-seal values it cannot open, so each one must be set again after the next deploy. Re-run with --force if that is what you want.`);
+        }
+        const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
+        const stageId = await resolveStageId(rpc, ctx.projectId, branch);
+        const result = await rpc.invoke('rotateStageSealingKey', { stageId });
+        console.log(`[fabric] retired sealing key ${result.retiredKeyId} on ${branch}`);
+        console.log('[fabric] deploy the stage to issue a new key, then set its secrets again');
+        return result;
+    },
+});

package/dist/src/fabric/functions/secrets-set.function.d.ts

@@ -6,7 +6,8 @@ export declare const FabricSecretsSetInput: z.ZodObject<{
     force: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export declare const FabricSecretsSetOutput: z.ZodObject<{
-    ok: z.ZodBoolean;
+    name: z.ZodString;
+    keyId: z.ZodString;
 }, z.core.$strip>;
 export declare const FabricSecretsSet: import("../../../.pikku/pikku-types.gen.js").PikkuFunctionConfig<{
     name: string;
@@ -14,19 +15,22 @@ export declare const FabricSecretsSet: import("../../../.pikku/pikku-types.gen.j
     value?: string | undefined;
     force?: boolean | undefined;
 }, {
-    ok: boolean;
+    name: string;
+    keyId: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").PikkuFunctionSessionless<{
     name: string;
     branch: string;
     value?: string | undefined;
     force?: boolean | undefined;
 }, {
-    ok: boolean;
+    name: string;
+    keyId: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices> | import("../../../.pikku/pikku-types.gen.js").PikkuFunction<{
     name: string;
     branch: string;
     value?: string | undefined;
     force?: boolean | undefined;
 }, {
-    ok: boolean;
+    name: string;
+    keyId: string;
 }, "rpc" | "session", import("../../../.pikku/pikku-types.gen.js").WiredServices>, undefined, undefined>;

package/dist/src/fabric/functions/secrets-set.function.js

@@ -3,15 +3,20 @@ import { pikkuSessionlessFunc } from '../../../.pikku/pikku-types.gen.js';
 import { resolveApiContext } from '../lib/config.js';
 import { getFabricRPC } from '../lib/http.js';
 import { promptSecret } from '../lib/prompt.js';
+import { resolveStageId } from '../lib/stage.js';
+import { seal, serializeSealedValue } from '../lib/sealed-box.js';
 export const FabricSecretsSetInput = z.object({
     name: z.string(),
     branch: z.string(),
     value: z.string().optional(),
     force: z.boolean().optional(),
 });
-export const FabricSecretsSetOutput = z.object({ ok: z.boolean() });
+export const FabricSecretsSetOutput = z.object({
+    name: z.string(),
+    keyId: z.string(),
+});
 export const FabricSecretsSet = pikkuSessionlessFunc({
-    description: 'Set a stage-scoped secret. Encrypted with the stage KEK and stored in the project D1.',
+    description: 'Set a stage-scoped secret. Sealed here to the stage public key — the plaintext never leaves this machine.',
     input: FabricSecretsSetInput,
     output: FabricSecretsSetOutput,
     func: async (_services, { name, branch, value }) => {
@@ -24,13 +29,19 @@ export const FabricSecretsSet = pikkuSessionlessFunc({
         if (!plaintext)
             throw new Error('Empty secret value — aborting.');
         const rpc = getFabricRPC({ apiUrl: ctx.apiUrl, token: ctx.token });
-        const result = await rpc.invoke('setStageSecret', {
-            projectId: ctx.projectId,
-            branch,
+        const stageId = await resolveStageId(rpc, ctx.projectId, branch);
+        // Fabric holds only the public half of this keypair. The private half went
+        // to the stage's worker at deploy time and was dropped there, so the value
+        // sealed below can be opened by that worker and by nothing else — including
+        // by the fabric process that stores it.
+        const key = await rpc.invoke('getStageSealingKey', { stageId });
+        const sealed = seal(key.publicKey, key.keyId, plaintext);
+        const result = await rpc.invoke('setStageSealedSecret', {
+            stageId,
             name,
-            value: plaintext,
+            sealedValue: serializeSealedValue(sealed),
         });
-        console.log(`[fabric] ${name} set on ${branch}.`);
+        console.log(`[fabric] ${name} sealed to ${result.keyId} and set on ${branch}.`);
         return result;
     },
 });

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']),
@@ -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,7 +677,10 @@ 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) {

package/dist/src/fabric/lib/http.d.ts

@@ -1,4 +1,10 @@
+/**
+ * Type-safe RPC client backed by the snapshot SDK in `../sdk/`. The map is
+ * a copy of fabric's generated rpc-map at the time of the addon's last
+ * release — versioning bumps are taken by republishing this package.
+ */
+import { PikkuRPC } from '../sdk/pikku-rpc.gen.js';
 export declare function getFabricRPC(opts: {
     apiUrl: string;
     token: string | null;
-}): any;
+}): PikkuRPC;

package/dist/src/fabric/lib/sealed-box.d.ts

@@ -0,0 +1,16 @@
+/** Algorithm tag carried by every sealed value. Must match fabric's. */
+export declare const SEALED_BOX_ALGORITHM = "sealed-x25519-v1";
+export interface SealedValue {
+    alg: typeof SEALED_BOX_ALGORITHM;
+    /** The `encryption_key` row whose public key sealed this. */
+    kid: string;
+    /** Ephemeral public key, SPKI DER as base64. */
+    epk: string;
+    iv: string;
+    ct: string;
+    tag: string;
+}
+/** Seal a value to a stage's public key. */
+export declare function seal(publicKey: string, keyId: string, plaintext: string): SealedValue;
+/** Wire form. Fabric stores exactly this string. */
+export declare function serializeSealedValue(sealed: SealedValue): string;