@anchrd/intel-api 0.2.1 → 0.3.1

package/dist/adapters/cloudflare/cloudflare.js

@@ -143,6 +143,7 @@ export default {
                     throw error;
                 }
             },
+            folderAccess: async (actor, folderId) => await knowledge.folderAccess(actor, folderId),
             toolFingerprint: async (actor, toolName) => {
                 const catalog = await tools
                     .catalog({ id: actor.id, email: actor.email, canExecute: true })

package/dist/adapters/db/db-flows.js

@@ -1,5 +1,5 @@
 import { Flow, FlowGraph, FlowRun, FlowVersion, } from "@anchrd/intel-contract";
-const flowColumns = `id, title, description, owner_id, current_version_id,
+const flowColumns = `id, parent_id, title, description, owner_id, current_version_id,
   published_version_id, created_at, updated_at, archived_at`;
 const runColumnNames = [
     "id",
@@ -39,6 +39,7 @@ function accessBindings(actor, now, roles = []) {
 function mapFlow(row) {
     return Flow.parse({
         id: row.id,
+        parentId: row.parent_id,
         title: row.title,
         description: row.description,
         ownerId: row.owner_id,
@@ -103,12 +104,20 @@ function mapGrant(row) {
 export function createFlowRepository(deps) {
     const visible = accessPredicate();
     return {
-        async listVisible(actor) {
+        async listVisible(actor, input = {}) {
+            // An absent `parentId` asks for every visible flow; `null` asks for the root of the shared
+            // tree. `IS ?` would collapse the two, so the two cases are separate SQL rather than one
+            // binding that silently means both.
+            const scope = input.parentId === undefined
+                ? { clause: "", bindings: [] }
+                : input.parentId === null
+                    ? { clause: "AND flow.parent_id IS NULL", bindings: [] }
+                    : { clause: "AND flow.parent_id = ?", bindings: [input.parentId] };
             const result = await deps.db
                 .prepare(`SELECT ${flowColumns} FROM flows flow
-          WHERE ${visible} AND flow.archived_at IS NULL
+          WHERE ${visible} AND flow.archived_at IS NULL ${scope.clause}
           ORDER BY lower(flow.title), flow.id`)
-                .bind(...accessBindings(actor, deps.now().toISOString()))
+                .bind(...accessBindings(actor, deps.now().toISOString()), ...scope.bindings)
                 .all();
             return (result.results ?? []).map(mapFlow);
         },
@@ -159,10 +168,10 @@ export function createFlowRepository(deps) {
                 await deps.db.batch([
                     deps.db
                         .prepare(`INSERT INTO flows (
-              id, title, description, owner_id, current_version_id, published_version_id,
+              id, parent_id, title, description, owner_id, current_version_id, published_version_id,
               created_at, updated_at, archived_at
-            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-                        .bind(flow.id, flow.title, flow.description, flow.ownerId, flow.currentVersionId, flow.publishedVersionId, flow.createdAt, flow.updatedAt, flow.archivedAt),
+            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+                        .bind(flow.id, flow.parentId, flow.title, flow.description, flow.ownerId, flow.currentVersionId, flow.publishedVersionId, flow.createdAt, flow.updatedAt, flow.archivedAt),
                     deps.db
                         .prepare(`INSERT INTO idempotency_keys (
               actor_id, operation, idempotency_key, resource_id, created_at
@@ -189,6 +198,52 @@ export function createFlowRepository(deps) {
                 throw error;
             }
         },
+        // Renaming and moving touch the flow row and nothing else. `current_version_id` and
+        // `published_version_id` are deliberately absent from the SET list: organization must not be
+        // able to change what a flow does (ADR-0004).
+        async updateFlow(input) {
+            const flow = input.flow;
+            try {
+                await deps.db.batch([
+                    deps.db
+                        .prepare(`UPDATE flows SET parent_id = ?, title = ?, description = ?, updated_at = ?
+              WHERE id = ? AND updated_at = ?`)
+                        .bind(flow.parentId, flow.title, flow.description, flow.updatedAt, flow.id, input.baseUpdatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO idempotency_keys (
+              actor_id, operation, idempotency_key, resource_id, created_at
+            ) SELECT ?, 'flows.update', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM flows
+              WHERE id = ? AND parent_id IS ? AND title = ? AND description IS ? AND updated_at = ?
+            )`)
+                        .bind(input.actorId, input.idempotencyKey, flow.id, flow.updatedAt, flow.id, flow.parentId, flow.title, flow.description, flow.updatedAt),
+                    deps.db
+                        .prepare(`INSERT INTO audit_events (
+              id, actor_id, action, resource_type, resource_id, metadata_json, occurred_at
+            ) SELECT ?, ?, 'flows.update', 'flow', ?, ?, ?
+            WHERE EXISTS (
+              SELECT 1 FROM idempotency_keys
+              WHERE actor_id = ? AND operation = 'flows.update'
+                AND idempotency_key = ? AND resource_id = ?
+            )`)
+                        .bind(input.auditId, input.actorId, flow.id, JSON.stringify({ parentId: flow.parentId, title: flow.title }), flow.updatedAt, input.actorId, input.idempotencyKey, flow.id),
+                ]);
+            }
+            catch (error) {
+                if (!(await this.findIdempotent(input.actorId, "flows.update", input.idempotencyKey))) {
+                    throw error;
+                }
+            }
+            const replayed = await this.findIdempotent(input.actorId, "flows.update", input.idempotencyKey);
+            if (!replayed)
+                return "conflict";
+            const row = await deps.db
+                .prepare(`SELECT ${flowColumns} FROM flows WHERE id = ?`)
+                .bind(replayed)
+                .first();
+            return row ? mapFlow(row) : "conflict";
+        },
         async getVersion(versionId) {
             const row = await deps.db
                 .prepare(`SELECT id, flow_id, sequence, graph_json, created_by, created_at

package/dist/cli/cli.js

@@ -8,7 +8,10 @@ const interfaces = [
         functions: ["read", "create", "write", "publish", "run", "approve", "share"],
     },
     { handle: "tools", functions: ["read", "test", "execute", "admin"] },
-    { handle: "intel-tools", functions: ["connect"] },
+    // `mcp:connect` heisst bei jedem MCP-Dienst dieser Installation gleich. Ein eigener Name fuer
+    // dieselbe Sache zwingt den Betreiber, pro Dienst nachzusehen, welches Recht den Portal-Zugang
+    // traegt.
+    { handle: "mcp", functions: ["connect"] },
 ];
 const usage = `Usage: intel <prepare|bootstrap|build|doctor|reindex>
   intel prepare    Copy versioned D1 migrations to .intel/migrations

package/dist/flows/flows.js

@@ -103,6 +103,23 @@ export function createFlows(deps) {
         }
         return flow;
     }
+    // A flow's parent is a Knowledge folder, so the answer comes from Knowledge rather than from a
+    // second permission model here. `null` is the root and needs no permission of its own — the same
+    // as creating a folder at the root does.
+    async function requireFolder(actor, parentId) {
+        if (parentId === null)
+            return;
+        const access = await deps.folderAccess(actor, parentId);
+        if (access === "missing") {
+            throw new IntelError(404, "flow_parent_not_found", "Parent folder was not found");
+        }
+        if (access === "not-a-folder") {
+            throw new IntelError(409, "parent_not_folder", "A flow's parent must be a folder");
+        }
+        if (access === "forbidden") {
+            throw new IntelError(403, "knowledge_forbidden", "Destination folder cannot be edited");
+        }
+    }
     async function requireVersion(versionId, flowId) {
         const version = await deps.repository.getVersion(versionId);
         if (!version || (flowId && version.flowId !== flowId)) {
@@ -116,8 +133,8 @@ export function createFlows(deps) {
         return { run, node: nodeFor(version, run.currentNodeId) };
     }
     return {
-        async list(actor) {
-            return { items: await deps.repository.listVisible(actor) };
+        async list(actor, input = {}) {
+            return { items: await deps.repository.listVisible(actor, input) };
         },
         async get(actor, flowId) {
             const flow = await requireFlow(actor, flowId);
@@ -132,10 +149,12 @@ export function createFlows(deps) {
             const replayed = await deps.repository.findIdempotent(actor.id, "flows.create", input.idempotencyKey);
             if (replayed)
                 return await requireFlow(actor, replayed);
+            await requireFolder(actor, input.parentId);
             const occurredAt = deps.now().toISOString();
             return await deps.repository.insertFlow({
                 flow: {
                     id: deps.id(),
+                    parentId: input.parentId,
                     title: input.title,
                     description: input.description,
                     ownerId: actor.id,
@@ -150,6 +169,34 @@ export function createFlows(deps) {
                 auditId: deps.id(),
             });
         },
+        // Rename and move. It reads and writes the flow row alone: no version is appended, no published
+        // version is touched and no run is signalled, so tidying up the tree cannot change what a flow
+        // does (ADR-0004).
+        async update(actor, input) {
+            const current = await requireEdit(actor, input.flowId);
+            const replayed = await deps.repository.findIdempotent(actor.id, "flows.update", input.idempotencyKey);
+            if (replayed)
+                return await requireFlow(actor, replayed);
+            if (input.parentId !== undefined)
+                await requireFolder(actor, input.parentId);
+            const updated = await deps.repository.updateFlow({
+                flow: {
+                    ...current,
+                    parentId: input.parentId === undefined ? current.parentId : input.parentId,
+                    title: input.title ?? current.title,
+                    description: input.description === undefined ? current.description : input.description,
+                    updatedAt: deps.now().toISOString(),
+                },
+                baseUpdatedAt: input.baseUpdatedAt,
+                actorId: actor.id,
+                idempotencyKey: input.idempotencyKey,
+                auditId: deps.id(),
+            });
+            if (updated === "conflict") {
+                throw new IntelError(409, "flow_update_conflict", "Flow was changed by another editor");
+            }
+            return updated;
+        },
         async save(actor, input) {
             const replayed = await deps.repository.findIdempotent(actor.id, "flows.save", input.idempotencyKey);
             if (replayed) {

package/dist/flows/flows.types.d.ts

@@ -1,13 +1,13 @@
-import type { CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowRun, FlowRunStep, FlowVersion, PublishFlowInput, ResourceGrant, RevokeFlowGrantInput, SaveFlowVersionInput, ShareFlowInput, StartFlowRunInput } from "@anchrd/intel-contract";
+import type { CompleteFlowRunStepInput, CreateFlowInput, Flow, FlowDocument, FlowGraph, FlowRun, FlowRunStep, FlowVersion, ListFlowsInput, PublishFlowInput, ResourceGrant, RevokeFlowGrantInput, SaveFlowVersionInput, ShareFlowInput, StartFlowRunInput, UpdateFlowInput } from "@anchrd/intel-contract";
 export interface FlowActor {
     id: string;
     email: string;
     canRun: boolean;
     canApprove: boolean;
 }
-export type FlowOperation = "flows.create" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete" | "flows.share" | "flows.revoke";
+export type FlowOperation = "flows.create" | "flows.update" | "flows.save" | "flows.publish" | "flows.run" | "flows.complete" | "flows.share" | "flows.revoke";
 export interface FlowRepository {
-    listVisible(actor: FlowActor): Promise<Flow[]>;
+    listVisible(actor: FlowActor, input?: ListFlowsInput): Promise<Flow[]>;
     getVisible(actor: FlowActor, flowId: string): Promise<Flow | null>;
     canEdit(actor: FlowActor, flowId: string): Promise<boolean>;
     canManage(actor: FlowActor, flowId: string): Promise<boolean>;
@@ -19,6 +19,13 @@ export interface FlowRepository {
         idempotencyKey: string;
         auditId: string;
     }): Promise<Flow>;
+    updateFlow(input: {
+        flow: Flow;
+        baseUpdatedAt: string;
+        actorId: string;
+        idempotencyKey: string;
+        auditId: string;
+    }): Promise<"conflict" | Flow>;
     getVersion(versionId: string): Promise<FlowVersion | null>;
     insertVersion(input: {
         version: FlowVersion;
@@ -80,15 +87,18 @@ export interface FlowDeps {
     id(): string;
     now(): Date;
     knowledgeExists(actor: FlowActor, resourceId: string): Promise<boolean>;
+    folderAccess(actor: FlowActor, folderId: string): Promise<FolderAccess>;
     toolFingerprint(actor: FlowActor, toolName: string): Promise<string | null>;
     unavailableTools(actor: FlowActor, toolNames: string[]): Promise<string[]>;
 }
+export type FolderAccess = "ok" | "missing" | "not-a-folder" | "forbidden";
 export interface FlowService {
-    list(actor: FlowActor): Promise<{
+    list(actor: FlowActor, input?: ListFlowsInput): Promise<{
         items: Flow[];
     }>;
     get(actor: FlowActor, flowId: string): Promise<FlowDocument>;
     create(actor: FlowActor, input: CreateFlowInput): Promise<Flow>;
+    update(actor: FlowActor, input: UpdateFlowInput): Promise<Flow>;
     save(actor: FlowActor, input: SaveFlowVersionInput): Promise<FlowDocument>;
     publish(actor: FlowActor, input: PublishFlowInput): Promise<Flow>;
     start(actor: FlowActor, input: StartFlowRunInput): Promise<FlowRunStep>;

package/dist/http/http.js

@@ -1,4 +1,4 @@
-import { ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeLinkInput, CreateKnowledgeNodeInput, DeleteKnowledgeLinkInput, ExecuteToolInput, KnowledgeGraphInput, ListKnowledgeNodesInput, PublishFlowInput, RevokeFlowGrantInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareFlowInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
+import { ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeLinkInput, CreateKnowledgeNodeInput, DeleteKnowledgeLinkInput, ExecuteToolInput, KnowledgeGraphInput, ListFlowsInput, ListKnowledgeNodesInput, PublishFlowInput, RevokeFlowGrantInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareFlowInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
 import { Hono } from "hono";
 import { z } from "zod";
 import { authorizeBearer, bearer } from "../shared/gate-authorization/gate-authorization.js";
@@ -64,6 +64,16 @@ export function createHttp(deps) {
         }
         return authorization;
     }
+    // The caller's own identity, so the shell can name who is signed in. It needs no capability —
+    // the answer is the token's own subject — and it returns nothing but id, email, and name.
+    app.get("/session", (context) => {
+        const { identity } = context.get("authorization");
+        return context.json({
+            id: identity.id,
+            email: identity.email,
+            name: identity.name ?? null,
+        });
+    });
     app.get("/knowledge", async (context) => {
         const auth = requireCapability(context, "knowledge", "read");
         const url = new URL(context.req.url);
@@ -200,7 +210,20 @@ export function createHttp(deps) {
     });
     app.get("/flows", async (context) => {
         const auth = requireCapability(context, "flows", "read");
-        return context.json(await deps.flows.list(asFlowActor(auth)));
+        const url = new URL(context.req.url);
+        const unknownQuery = [];
+        url.searchParams.forEach((_value, key) => {
+            if (key !== "parentId")
+                unknownQuery.push(key);
+        });
+        if (unknownQuery.length) {
+            throw new IntelError(400, "invalid_request", `Unknown query parameters: ${unknownQuery.join(", ")}`);
+        }
+        // Absent means "every flow I may see"; present but empty means the root of the shared tree.
+        // Without that distinction a tree level and a full list would be the same request.
+        const parentId = url.searchParams.get("parentId");
+        const input = ListFlowsInput.parse(url.searchParams.has("parentId") ? { parentId: parentId === "" ? null : parentId } : {});
+        return context.json(await deps.flows.list(asFlowActor(auth), input));
     });
     app.get("/flows/:flowId", async (context) => {
         const auth = requireCapability(context, "flows", "read");
@@ -232,6 +255,14 @@ export function createHttp(deps) {
         const input = CreateFlowInput.parse(await context.req.json().catch(() => null));
         return context.json(await deps.flows.create(asFlowActor(auth), input), 201);
     });
+    app.patch("/flows/:flowId", async (context) => {
+        const auth = requireCapability(context, "flows", "write");
+        const input = UpdateFlowInput.parse(await context.req.json().catch(() => null));
+        if (input.flowId !== context.req.param("flowId")) {
+            throw new IntelError(400, "flow_id_mismatch", "Path and body flow IDs differ");
+        }
+        return context.json(await deps.flows.update(asFlowActor(auth), input));
+    });
     app.post("/flows/:flowId/versions", async (context) => {
         const auth = requireCapability(context, "flows", "write");
         const input = SaveFlowVersionInput.parse(await context.req.json().catch(() => null));

package/dist/knowledge/knowledge.js

@@ -97,6 +97,17 @@ export function createKnowledge(deps) {
         async get(actor, nodeId) {
             return await getDocument(await requireVisible(actor, nodeId));
         },
+        // Knowledge and Flows share one folder tree (ADR-0004), so Flows has to ask one question about
+        // it: may this actor file something in that folder. The answer stays here, with the tree and
+        // its ACLs, rather than being reimplemented on the flow side.
+        async folderAccess(actor, folderId) {
+            const folder = await deps.repository.getVisible(actor, folderId);
+            if (!folder || folder.archivedAt)
+                return "missing";
+            if (folder.kind !== "folder")
+                return "not-a-folder";
+            return (await deps.repository.canEdit(actor, folder.id)) ? "ok" : "forbidden";
+        },
         async create(actor, input) {
             const existingId = await deps.repository.findIdempotentNode(actor.id, "knowledge.create", input.idempotencyKey);
             if (existingId)

package/dist/knowledge/knowledge.types.d.ts

@@ -108,11 +108,13 @@ export interface KnowledgeDeps {
     };
     semantic?: SemanticIndex | undefined;
 }
+export type FolderAccess = "ok" | "missing" | "not-a-folder" | "forbidden";
 export interface KnowledgeService {
     list(actor: Actor, input: ListKnowledgeNodesInput): Promise<{
         items: KnowledgeNode[];
     }>;
     get(actor: Actor, nodeId: string): Promise<KnowledgeDocument>;
+    folderAccess(actor: Actor, folderId: string): Promise<FolderAccess>;
     create(actor: Actor, input: CreateKnowledgeNodeInput): Promise<KnowledgeNode>;
     save(actor: Actor, input: SaveKnowledgeVersionInput): Promise<KnowledgeDocument>;
     saveAttachment(actor: Actor, input: SaveKnowledgeAttachmentInput): Promise<KnowledgeDocument>;

package/dist/mcp/mcp.js

@@ -1,4 +1,4 @@
-import { ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeLinkInput, CreateKnowledgeNodeInput, DeleteKnowledgeLinkInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetKnowledgeNodeInput, KnowledgeGraphInput, ListFlowGrantsInput, ListKnowledgeGrantsInput, ListKnowledgeNodesInput, PublishFlowInput, RevokeFlowGrantInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareFlowInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
+import { ArchiveKnowledgeNodeInput, CompleteFlowRunStepInput, CreateFlowInput, CreateKnowledgeLinkInput, CreateKnowledgeNodeInput, DeleteKnowledgeLinkInput, ExecuteToolInput, GetFlowInput, GetFlowRunInput, GetKnowledgeNodeInput, KnowledgeGraphInput, ListFlowGrantsInput, ListFlowsInput, ListKnowledgeGrantsInput, ListKnowledgeNodesInput, PublishFlowInput, RevokeFlowGrantInput, RevokeKnowledgeGrantInput, SaveFlowVersionInput, SaveKnowledgeAttachmentInput, SaveKnowledgeVersionInput, SearchKnowledgeInput, ShareFlowInput, ShareKnowledgeInput, StartFlowRunInput, TestToolInput, UpdateFlowInput, UpdateKnowledgeNodeInput, } from "@anchrd/intel-contract";
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { z } from "zod";
@@ -295,8 +295,8 @@ export async function handleMcp(request, deps) {
     if (deps.authorization.can("flows", "read")) {
         server.registerTool("flows_list", {
             title: "List flows",
-            description: "List authorized company flows by title and description.",
-            inputSchema: EmptyInput,
+            description: "List authorized flows, either all of them or the ones filed in one folder of the shared Knowledge tree.",
+            inputSchema: ListFlowsInput,
             annotations: {
                 title: "List flows",
                 readOnlyHint: true,
@@ -304,7 +304,7 @@ export async function handleMcp(request, deps) {
                 idempotentHint: true,
                 openWorldHint: false,
             },
-        }, async () => text(await deps.flows.list(flowActor)));
+        }, async (input) => text(await deps.flows.list(flowActor, input)));
         server.registerTool("flow_get", {
             title: "Get flow",
             description: "Load one authorized flow and its current immutable graph on demand.",
@@ -383,6 +383,18 @@ export async function handleMcp(request, deps) {
         }, async (input) => text(await deps.flows.create(flowActor, input)));
     }
     if (deps.authorization.can("flows", "write")) {
+        server.registerTool("flow_update", {
+            title: "Rename or move flow",
+            description: "Rename a flow, change its description, or move it to another folder of the shared Knowledge tree. Never changes what the flow does.",
+            inputSchema: UpdateFlowInput,
+            annotations: {
+                title: "Rename or move flow",
+                readOnlyHint: false,
+                destructiveHint: false,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        }, async (input) => text(await deps.flows.update(flowActor, input)));
         server.registerTool("flow_save", {
             title: "Save flow",
             description: "Append a validated immutable flow graph version with optimistic concurrency.",

package/dist/tools/tools.js

@@ -86,7 +86,20 @@ export function createTools(deps) {
             // An unconnected portal is a normal state, not an error: the UI shows a connect prompt.
             if (!stored)
                 return { portalConnected: false, items: [] };
-            return { portalConnected: true, items: await capabilities(actor) };
+            try {
+                return { portalConnected: true, items: await capabilities(actor) };
+            }
+            catch (error) {
+                // A token that is gone or beyond renewal is the same answer as never having connected, so
+                // reading the catalog reports it as a state. Only a portal that does not answer stays an
+                // error — the view has to tell "connect the portal" apart from "the portal failed", and a
+                // 401 here would otherwise look like an expired Intel session to the browser.
+                if (error instanceof IntelError &&
+                    (error.code === "portal_not_connected" || error.code === "portal_reconnect_required")) {
+                    return { portalConnected: false, items: [] };
+                }
+                throw error;
+            }
         },
         execute: async (actor, input) => await call(actor, input),
         async test(actor, input) {

package/migrations/0002_flows_in_the_knowledge_tree.sql

@@ -0,0 +1,34 @@
+-- ADR-0004: Knowledge and Flows share one folder tree. A flow gains `parent_id` into the existing
+-- `knowledge_nodes` tree; the contents stay two tables, because versions, the R2 body and the
+-- Vectorize entry belong to the document while the graph, runs and approvals belong to the flow.
+
+-- SQLite only accepts an added REFERENCES column when its default is NULL, which is exactly what an
+-- unfiled flow needs: `NULL` is the root of the same tree Knowledge uses.
+ALTER TABLE flows ADD COLUMN parent_id TEXT REFERENCES knowledge_nodes(id);
+
+CREATE INDEX flows_parent_idx ON flows(parent_id, archived_at, title);
+
+-- Existing flows land in a defined folder rather than scattered across the root. One folder per
+-- owner, with a derived ID so a re-run finds the same row: the narrow reading of an ambiguous case,
+-- as the ADR requires. A single shared folder would have to belong to someone, and its owner would
+-- gain sight of everyone else's flows — a migration must never widen access.
+INSERT INTO knowledge_nodes (
+  id, parent_id, kind, title, description, context_policy, owner_id,
+  current_version_id, created_at, updated_at, archived_at
+)
+SELECT
+  'folder-flows-' || flow.owner_id,
+  NULL,
+  'folder',
+  'Flows',
+  'Flows that existed before Knowledge and Flows shared one tree.',
+  'explicit',
+  flow.owner_id,
+  NULL,
+  '2026-08-01T00:00:00.000Z',
+  '2026-08-01T00:00:00.000Z',
+  NULL
+FROM flows flow
+GROUP BY flow.owner_id;
+
+UPDATE flows SET parent_id = 'folder-flows-' || owner_id WHERE parent_id IS NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-api",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {