@danypops/papyrus 0.60.1 → 0.60.3

package/src/cli/binders-command.ts

@@ -0,0 +1,340 @@
+import type { CommandContext } from "@stricli/core";
+import { buildApplication, buildCommand, buildRouteMap, numberParser } from "@stricli/core";
+import type { PapyrusClient } from "../client.ts";
+import type { OperationName } from "../service.ts";
+import { artifactLabel, type CliArtifact } from "./shared.ts";
+import { runStricliToString } from "./stricli-run.ts";
+
+type BindersClient = Pick<PapyrusClient, "call">;
+
+interface BindersContext extends CommandContext {
+	readonly client: BindersClient;
+	readonly json: boolean;
+}
+
+function parseStringArray(value: string): string[] {
+	const parsed = JSON.parse(value) as unknown;
+	if (!Array.isArray(parsed) || parsed.some((entry) => typeof entry !== "string")) throw new Error("value must be a JSON string array");
+	return parsed as string[];
+}
+
+function render(this: BindersContext, result: unknown, human: string): void {
+	this.process.stdout.write(this.json ? JSON.stringify(result) : human);
+}
+
+const createCommand = buildCommand({
+	func: async function (
+		this: BindersContext,
+		flags: { title: string; labelsJson?: string[]; parentId?: string; projectRoot?: string; projectsJson?: string[] },
+	) {
+		const binder = await this.client.call<Record<string, unknown>, CliArtifact>("binders.create", {
+			title: flags.title,
+			labels: flags.labelsJson,
+			parent_id: flags.parentId,
+			project_root: flags.projectRoot,
+			projects: flags.projectsJson,
+		});
+		render.call(this, binder, `Created Binder: ${artifactLabel(binder)}`);
+	},
+	parameters: {
+		flags: {
+			title: { brief: "Binder name", kind: "parsed", parse: String, placeholder: "text" },
+			labelsJson: {
+				brief: "JSON string array of inherited labels",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+			parentId: { brief: "Parent Binder id", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			projectRoot: { brief: "Project context", kind: "parsed", parse: String, placeholder: "path", optional: true },
+			projectsJson: { brief: "JSON project-reference array", kind: "parsed", parse: parseStringArray, placeholder: "json", optional: true },
+		},
+	},
+	docs: { brief: "Create a Binder" },
+});
+
+const listCommand = buildCommand({
+	func: async function (this: BindersContext, flags: { text?: string; limit?: number; projectRoot?: string; applicable?: boolean }) {
+		const rows = await this.client.call<Record<string, unknown>, CliArtifact[]>("binders.list", {
+			text: flags.text,
+			limit: flags.limit,
+			project_root: flags.projectRoot,
+			applicable: flags.applicable,
+		});
+		render.call(this, rows, rows.length === 0 ? "No Binders found." : rows.map(artifactLabel).join("\n"));
+	},
+	parameters: {
+		flags: {
+			text: { brief: "Substring match", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			limit: { brief: "Maximum Binders", kind: "parsed", parse: numberParser, optional: true },
+			projectRoot: { brief: "Project context", kind: "parsed", parse: String, placeholder: "path", optional: true },
+			applicable: { brief: "Include global and project-applicable Binders", kind: "boolean", optional: true },
+		},
+	},
+	docs: { brief: "List Binders" },
+});
+
+interface CliBinderTree {
+	nodes: Array<{ binder: CliArtifact; path: string; effectiveLabels: string[] }>;
+	artifacts: Array<{ artifactId: string; binderId?: string; inheritedLabels: string[]; effectiveLabels: string[] }>;
+}
+
+const treeCommand = buildCommand({
+	func: async function (this: BindersContext, flags: { projectRoot?: string; artifactIdsJson?: string[] }) {
+		const tree = await this.client.call<Record<string, unknown>, CliBinderTree>("binders.tree", {
+			project_root: flags.projectRoot,
+			artifact_ids: flags.artifactIdsJson,
+		});
+		const lines = tree.nodes.map((node) => `${node.path}${node.effectiveLabels.length ? ` [${node.effectiveLabels.join(", ")}]` : ""}`);
+		render.call(this, tree, lines.length === 0 ? "/ (no Binders)" : lines.join("\n"));
+	},
+	parameters: {
+		flags: {
+			projectRoot: { brief: "Project context", kind: "parsed", parse: String, placeholder: "path", optional: true },
+			artifactIdsJson: {
+				brief: "JSON artifact-id array to project",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+		},
+	},
+	docs: { brief: "Show Binder hierarchy and effective labels" },
+});
+
+const showCommand = buildCommand({
+	func: async function (this: BindersContext, flags: { projectRoot?: string }, id: string) {
+		const node = await this.client.call<Record<string, unknown>, { binder: CliArtifact; path: string; effectiveLabels: string[] }>(
+			"binders.show",
+			{
+				id,
+				project_root: flags.projectRoot,
+			},
+		);
+		render.call(this, node, `${node.path}${node.effectiveLabels.length ? ` [${node.effectiveLabels.join(", ")}]` : ""}`);
+	},
+	parameters: {
+		flags: { projectRoot: { brief: "Project context", kind: "parsed", parse: String, placeholder: "path", optional: true } },
+		positional: { kind: "tuple", parameters: [{ brief: "Binder id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Show one Binder" },
+});
+
+const updateCommand = buildCommand({
+	func: async function (this: BindersContext, flags: { title?: string; labelsJson?: string[]; projectRoot?: string }, id: string) {
+		if (flags.title === undefined && flags.labelsJson === undefined) throw new Error("binders update requires --title or --labels-json");
+		const binder = await this.client.call<Record<string, unknown>, CliArtifact>("binders.update", {
+			id,
+			title: flags.title,
+			labels: flags.labelsJson,
+			project_root: flags.projectRoot,
+		});
+		render.call(this, binder, artifactLabel(binder));
+	},
+	parameters: {
+		flags: {
+			title: { brief: "New Binder name", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			labelsJson: { brief: "Replacement direct-label array", kind: "parsed", parse: parseStringArray, placeholder: "json", optional: true },
+			projectRoot: { brief: "Project context", kind: "parsed", parse: String, placeholder: "path", optional: true },
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Binder id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Rename or relabel a Binder" },
+});
+
+const moveCommand = buildCommand({
+	func: async function (this: BindersContext, flags: { projectRoot?: string }, id: string, parentId?: string) {
+		const node = await this.client.call<Record<string, unknown>, { path: string }>("binders.move", {
+			id,
+			parent_id: parentId,
+			project_root: flags.projectRoot,
+		});
+		render.call(this, node, `Moved ${id} to ${node.path}`);
+	},
+	parameters: {
+		flags: { projectRoot: { brief: "Project context", kind: "parsed", parse: String, placeholder: "path", optional: true } },
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Binder id", parse: String, placeholder: "id" },
+				{ brief: "Parent Binder id; omit for root", parse: String, placeholder: "parent-id", optional: true },
+			],
+		},
+	},
+	docs: { brief: "Move a Binder" },
+});
+
+const fileCommand = buildCommand({
+	func: async function (this: BindersContext, flags: { projectRoot?: string }, artifactId: string, binderId: string) {
+		const placement = await this.client.call<Record<string, unknown>, { effectiveLabels: string[] }>("binders.file", {
+			artifact_id: artifactId,
+			binder_id: binderId,
+			project_root: flags.projectRoot,
+		});
+		render.call(this, placement, `Filed ${artifactId} in ${binderId}`);
+	},
+	parameters: {
+		flags: { projectRoot: { brief: "Project context", kind: "parsed", parse: String, placeholder: "path", optional: true } },
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Artifact id", parse: String, placeholder: "artifact-id" },
+				{ brief: "Binder id", parse: String, placeholder: "binder-id" },
+			],
+		},
+	},
+	docs: { brief: "File an artifact in a Binder" },
+});
+
+const unfileCommand = buildCommand({
+	func: async function (this: BindersContext, flags: { projectRoot?: string }, artifactId: string) {
+		const placement = await this.client.call<Record<string, unknown>, unknown>("binders.unfile", {
+			artifact_id: artifactId,
+			project_root: flags.projectRoot,
+		});
+		render.call(this, placement, `Moved ${artifactId} to root`);
+	},
+	parameters: {
+		flags: { projectRoot: { brief: "Project context", kind: "parsed", parse: String, placeholder: "path", optional: true } },
+		positional: { kind: "tuple", parameters: [{ brief: "Artifact id", parse: String, placeholder: "artifact-id" }] },
+	},
+	docs: { brief: "Move an artifact to Binder root" },
+});
+
+const removeCommand = buildCommand({
+	func: async function (this: BindersContext, flags: { projectRoot?: string; reason?: string }, id: string) {
+		const result = await this.client.call<Record<string, unknown>, unknown>("binders.remove", {
+			id,
+			project_root: flags.projectRoot,
+			reason: flags.reason,
+		});
+		render.call(this, result, `Removed empty Binder ${id}`);
+	},
+	parameters: {
+		flags: {
+			projectRoot: { brief: "Project context", kind: "parsed", parse: String, placeholder: "path", optional: true },
+			reason: { brief: "Audit reason", kind: "parsed", parse: String, placeholder: "text", optional: true },
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Binder id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Remove an empty Binder" },
+});
+
+interface CliScope {
+	artifactId: string;
+	mode: string;
+	members: Array<{ type: string; id: string }>;
+}
+
+function scopeLabel(scope: CliScope): string {
+	return scope.mode === "all" ? "global" : `${scope.mode}: ${scope.members.map((member) => `${member.type}:${member.id}`).join(", ")}`;
+}
+
+function unaryScopeCommand(operation: "scope" | "set_global" | "set_none", brief: string) {
+	return buildCommand({
+		func: async function (this: BindersContext, _flags: Record<string, never>, id: string) {
+			const scope = await this.client.call<Record<string, unknown>, CliScope>(`binders.${operation}` as OperationName, { id });
+			render.call(this, scope, scopeLabel(scope));
+		},
+		parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Binder id", parse: String, placeholder: "id" }] } },
+		docs: { brief },
+	});
+}
+
+function memberCommand(operation: "add_project" | "remove_project" | "add_group" | "remove_group") {
+	const key = operation.endsWith("project") ? "project" : "group";
+	return buildCommand({
+		func: async function (this: BindersContext, _flags: Record<string, never>, id: string, member: string) {
+			const scope = await this.client.call<Record<string, unknown>, CliScope>(`binders.${operation}` as OperationName, {
+				id,
+				[key]: member,
+			});
+			render.call(this, scope, scopeLabel(scope));
+		},
+		parameters: {
+			flags: {},
+			positional: {
+				kind: "tuple",
+				parameters: [
+					{ brief: "Binder id", parse: String, placeholder: "id" },
+					{ brief: `${key} reference`, parse: String, placeholder: key },
+				],
+			},
+		},
+		docs: { brief: `${operation.startsWith("add") ? "Add" : "Remove"} a ${key}` },
+	});
+}
+
+function replaceMembersCommand(operation: "replace_projects" | "replace_groups") {
+	const key = operation === "replace_projects" ? "projects" : "groups";
+	const flag = operation === "replace_projects" ? "projectsJson" : "groupsJson";
+	return buildCommand({
+		func: async function (this: BindersContext, flags: { projectsJson?: string[]; groupsJson?: string[] }, id: string) {
+			const values = flags[flag];
+			if (!values) throw new Error(`--${operation === "replace_projects" ? "projects-json" : "groups-json"} is required`);
+			const scope = await this.client.call<Record<string, unknown>, CliScope>(`binders.${operation}` as OperationName, {
+				id,
+				[key]: values,
+			});
+			render.call(this, scope, scopeLabel(scope));
+		},
+		parameters: {
+			flags: {
+				projectsJson: {
+					brief: "JSON project reference array",
+					kind: "parsed",
+					parse: parseStringArray,
+					placeholder: "json",
+					optional: true,
+				},
+				groupsJson: {
+					brief: "JSON scope-group reference array",
+					kind: "parsed",
+					parse: parseStringArray,
+					placeholder: "json",
+					optional: true,
+				},
+			},
+			positional: { kind: "tuple", parameters: [{ brief: "Binder id", parse: String, placeholder: "id" }] },
+		},
+		docs: { brief: `Replace Binder ${key}` },
+	});
+}
+
+const app = buildApplication(
+	buildRouteMap({
+		routes: {
+			create: createCommand,
+			list: listCommand,
+			tree: treeCommand,
+			show: showCommand,
+			update: updateCommand,
+			move: moveCommand,
+			file: fileCommand,
+			unfile: unfileCommand,
+			remove: removeCommand,
+			scope: unaryScopeCommand("scope", "Show Binder scope"),
+			"set-global": unaryScopeCommand("set_global", "Make a Binder global"),
+			"set-none": unaryScopeCommand("set_none", "Hide a Binder"),
+			"add-project": memberCommand("add_project"),
+			"remove-project": memberCommand("remove_project"),
+			"replace-projects": replaceMembersCommand("replace_projects"),
+			"add-group": memberCommand("add_group"),
+			"remove-group": memberCommand("remove_group"),
+			"replace-groups": replaceMembersCommand("replace_groups"),
+		},
+		docs: { brief: "Binder hierarchy and inherited-label operations" },
+	}),
+	{ name: "binders", scanner: { caseStyle: "allow-kebab-for-camel" } },
+);
+
+export async function runBindersCli(args: string[], client: BindersClient): Promise<string> {
+	const json = args.includes("--json");
+	return runStricliToString(
+		app,
+		args.filter((argument) => argument !== "--json"),
+		{ client, json },
+	);
+}

package/src/cli/note-command.ts

@@ -59,6 +59,34 @@ const listCommand = buildCommand({
 	docs: { brief: "List open (draft/active) notes, or a specific status" },
 });
 
+const listPageCommand = buildCommand({
+	func: async function (
+		this: NoteContext,
+		flags: { status?: string; text?: string; limit?: number; cursor?: string; allProjects?: boolean },
+	) {
+		const page = (await this.client.call("notes.list_page", {
+			...(flags.allProjects ? {} : { project_root: this.projectRoot }),
+			...(flags.status ? { status: flags.status } : {}),
+			...(flags.text ? { text: flags.text } : {}),
+			...(flags.limit === undefined ? {} : { limit: flags.limit }),
+			...(flags.cursor ? { cursor: flags.cursor } : {}),
+		})) as { items: CliArtifact[]; nextCursor?: string };
+		const lines = page.items.map((note) => `[${note.status}] ${artifactLabel(note)}`);
+		if (page.nextCursor) lines.push(`Next cursor: ${page.nextCursor}`);
+		renderResult.call(this, page, lines.length > 0 ? lines.join("\n") : "No open notes.");
+	},
+	parameters: {
+		flags: {
+			status: { brief: "Filter by status (draft|active|archived)", kind: "parsed", parse: String, placeholder: "status", optional: true },
+			text: { brief: "Substring match against title/body", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			limit: { brief: "Page size", kind: "parsed", parse: numberParser, optional: true },
+			cursor: { brief: "Opaque nextCursor from the preceding page", kind: "parsed", parse: String, placeholder: "cursor", optional: true },
+			allProjects: { brief: "Inventory Notes across every project", kind: "boolean", optional: true },
+		},
+	},
+	docs: { brief: "Cursor-paginate a stable Note inventory" },
+});
+
 const showCommand = buildCommand({
 	func: async function (this: NoteContext, _flags: Record<string, never>, id: string) {
 		const result = (await this.client.call("notes.show", { id, project_root: this.projectRoot })) as CliArtifact;
@@ -168,6 +196,7 @@ const app = buildApplication(
 		routes: {
 			capture: captureCommand,
 			list: listCommand,
+			page: listPageCommand,
 			show: showCommand,
 			history: historyCommand,
 			consume: consumeCommand,

package/src/cli/task-command.ts

@@ -456,6 +456,56 @@ const listCommand = buildCommand({
 	docs: { brief: "List Tasks" },
 });
 
+const listPageCommand = buildCommand({
+	func: async function (
+		this: TaskContext,
+		flags: {
+			status?: string;
+			text?: string;
+			limit?: number;
+			labelsJson?: string[];
+			scope?: "project" | "graph" | "all";
+			rootTaskId?: string;
+			sessionId?: string;
+			cursor?: string;
+		},
+	) {
+		const page = await this.client.call<Record<string, unknown>, { items: CliArtifact[]; nextCursor?: string }>("tasks.list_page", {
+			status: flags.status,
+			text: flags.text,
+			limit: flags.limit,
+			labels: flags.labelsJson,
+			project_root: this.projectRoot,
+			scope: flags.scope,
+			root_task_id: flags.rootTaskId,
+			session_id: flags.sessionId,
+			cursor: flags.cursor,
+		});
+		const rows = page.items.map((row) => artifactLabel(row));
+		if (page.nextCursor) rows.push(`Next cursor: ${page.nextCursor}`);
+		render.call(this, page, rows.length === 0 ? "No tasks found." : rows.join("\n"));
+	},
+	parameters: {
+		flags: {
+			status: { brief: "Filter by status", kind: "parsed", parse: String, placeholder: "status", optional: true },
+			text: { brief: "Substring match against title/body", kind: "parsed", parse: String, placeholder: "text", optional: true },
+			limit: { brief: "Page size", kind: "parsed", parse: numberParser, optional: true },
+			labelsJson: {
+				brief: "JSON string array of labels to filter by",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+				optional: true,
+			},
+			scope: { brief: "project|graph|all", kind: "enum", values: ["project", "graph", "all"], optional: true },
+			rootTaskId: { brief: "Root task id, required with graph scope", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			sessionId: { brief: "Scope to one agent session", kind: "parsed", parse: String, placeholder: "id", optional: true },
+			cursor: { brief: "Opaque nextCursor from the preceding page", kind: "parsed", parse: String, placeholder: "cursor", optional: true },
+		},
+	},
+	docs: { brief: "Cursor-paginate a stable Task inventory" },
+});
+
 const showCommand = buildCommand({
 	func: async function (this: TaskContext, _flags: Record<string, never>, id: string) {
 		const artifact = await this.client.call<Record<string, unknown>, CliArtifact>("tasks.show", { id });
@@ -963,6 +1013,7 @@ const app = buildApplication(
 			"mutation-status": mutationStatusCommand,
 			create: createCommand,
 			list: listCommand,
+			page: listPageCommand,
 			show: showCommand,
 			"run-gates": runGatesCommand,
 			"set-checklist": setChecklistCommand,

package/src/cli.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 import { createNodeServiceInstallDeps, generateSystemdUnit, installUserService, type ServiceSpec } from "@danypops/vehicle-server/service";
 import { runArtifactCli } from "./cli/artifact-command.ts";
 import { runBatchCli } from "./cli/batch-command.ts";
+import { runBindersCli } from "./cli/binders-command.ts";
 import { runDaemonCli } from "./cli/daemon-command.ts";
 import { runDiscussCli } from "./cli/discuss-command.ts";
 import { runDocsCli } from "./cli/docs-command.ts";
@@ -114,6 +115,13 @@ const USAGE = `Usage:
   papyrus artifact restore <id> [--json]
   papyrus artifact trash-status <id> [--json]
   papyrus artifact trash-list [--json]
+  papyrus binders create --title <name> [--labels-json <json>] [--parent-id <id>] [--project-root <path>] [--json]
+  papyrus binders list|tree [--project-root <path>] [--json]
+  papyrus binders show|remove <id> [--project-root <path>] [--json]
+  papyrus binders update <id> [--title <name>] [--labels-json <json>] [--project-root <path>] [--json]
+  papyrus binders move <id> [parent-id] [--project-root <path>] [--json]
+  papyrus binders file <artifact-id> <binder-id> [--project-root <path>] [--json]
+  papyrus binders unfile <artifact-id> [--project-root <path>] [--json]
   papyrus docs create --title <title> [--body <body>] [--subtype <subtype>] [--labels-json <json>] [--extra-json <json>] [--template-id <id>] [--project-root <path>] [--json]
   papyrus docs list [--status <status>] [--text <query>] [--limit <count>] [--project-root <path>] [--json]
   papyrus docs show <id> [--json]
@@ -144,6 +152,7 @@ const USAGE = `Usage:
   papyrus playbooks undepend <id> <dependency-id> [--json]
   papyrus notes capture <request> [--title <title>] [--json]
   papyrus notes list [--status <draft|active|archived>] [--text <query>] [--limit <count>] [--json]
+  papyrus notes page [--status <draft|active|archived>] [--text <query>] [--limit <count>] [--cursor <cursor>] [--all-projects] [--json]
   papyrus notes show <id> [--json]
   papyrus notes consume <id> [--reason <reason>] [--json]
   papyrus notes promote <id> <target-id> [--reason <reason>] [--json]
@@ -196,6 +205,7 @@ const USAGE = `Usage:
   papyrus tasks uncontain <parent-id> <child-id> [--reason <reason>] [--session-id <id>] [--json]
   papyrus tasks create --title <title> [--body <body>] [--status <status>] [--labels-json <json>] [--extra-json <json>] [--gates-json <json>] [--checklist-json <json>] [--template-id <id>] [--parent-id <id>] [--depends-on-json <json>] [--session-id <id>] [--json]
   papyrus tasks list [--status <status>] [--text <query>] [--limit <count>] [--scope <project|graph|all>] [--root-task-id <id>] [--session-id <id>] [--json]
+  papyrus tasks page [--status <status>] [--text <query>] [--limit <count>] [--cursor <cursor>] [--scope <project|graph|all>] [--root-task-id <id>] [--session-id <id>] [--json]
   papyrus tasks show <id> [--json]
   papyrus tasks run-gates <id> [--json]
   papyrus tasks set-checklist <id> --checklist-json <json> [--json]
@@ -355,6 +365,7 @@ export function runIdMigrationCli(args: string[]): string {
 export {
 	runArtifactCli,
 	runBatchCli,
+	runBindersCli,
 	runDiscussCli,
 	runDocsCli,
 	runGatesCli,
@@ -381,6 +392,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runTaskCli(args.slice(1), client));
 		return;
 	}
+	if (command === "binders") {
+		const client = await connectPapyrusClient();
+		console.log(await runBindersCli(args.slice(1), client));
+		return;
+	}
 	if (command === "playbooks") {
 		const client = await connectPapyrusClient();
 		console.log(await runPlaybooksCli(args.slice(1), client));

package/src/constants.ts

@@ -17,7 +17,7 @@ export const DAEMON_PROBE_TIMEOUT_MS = 800;
 export const DAEMON_UNIT_NAME = "papyrus.service";
 export const DAEMON_DIR_ENV = "PAPYRUS_DAEMON_DIR";
 export const SQLITE_BUSY_TIMEOUT_MS = 5_000;
-export const SQLITE_SCHEMA_VERSION = 30;
+export const SQLITE_SCHEMA_VERSION = 31;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -163,6 +163,11 @@ export const PLAYBOOK_INVOCATION_MAX_CREATED_TASKS = 200;
 export const TASK_CANCEL_SUBTREE_MAX_NODES = 500;
 /** artifact.remove_subtree walks `contains` transitively across any artifact kind (a task tree, or a playbook's own nested-playbook children) -- same bound rationale as TASK_CANCEL_SUBTREE_MAX_NODES, kept separate since the two traversals serve different operations. */
 export const ARTIFACT_REMOVE_SUBTREE_MAX_NODES = 500;
+/** Filesystem-style Binder projection bounds. A tree is one project-context view, never an unbounded graph export. */
+export const BINDER_TREE_MAX_ARTIFACTS = 1_000;
+export const BINDER_TREE_MAX_RELATIONSHIPS = 10_000;
+export const BINDER_TREE_MAX_DEPTH = 32;
+export const BINDER_EFFECTIVE_LABEL_MAX_COUNT = 256;
 
 /**
  * At the core, a workflow Skill creates Tasks and begins a pipeline -- an Ansible playbook or
@@ -303,6 +308,9 @@ export const SESSION_IDENTITY_MAX_ROWS = 2_000;
 export const ARTIFACT_TRASH_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 /** Persisted project and focused-graph Task view bounds. */
 export const TASK_SCOPE_MAX_TASKS = 1_000;
+/** Cursor-paged Task inventory bounds; pages stay comfortably below Vehicle response limits. */
+export const TASK_LIST_PAGE_DEFAULT_LIMIT = 100;
+export const TASK_LIST_PAGE_MAX_LIMIT = 200;
 /** Docs/Rules/Skills project scope listing bound, mirroring TASK_SCOPE_MAX_TASKS. */
 export const ARTIFACT_SCOPE_MAX_ARTIFACTS = 1_000;
 /** How many distinct registered projects a single Doc/Rule/Playbook may belong to at once, in "projects" scope mode. Kept alongside ARTIFACT_SCOPE_MAX_MEMBERS_PER_ARTIFACT (identical value) for the pure-project call sites/tests that predate mixed project+group membership. */

package/src/db.ts

@@ -361,6 +361,7 @@ INSERT OR IGNORE INTO kinds VALUES ('doc','Knowledge — what we know (specs, de
 INSERT OR IGNORE INTO kinds VALUES ('task','Work — what we are doing (objectives, steps, checklists)');
 INSERT OR IGNORE INTO kinds VALUES ('rule','Governance — when doing X, follow Y');
 INSERT OR IGNORE INTO kinds VALUES ('playbook','Reusable procedure — a trigger and an ordered list of steps an agent reads and follows, not a mechanically instantiated blueprint');
+INSERT OR IGNORE INTO kinds VALUES ('binder','Organizational directory — a stable path segment for browsing artifacts without changing their identity');
 INSERT OR IGNORE INTO statuses VALUES ('draft','doc');
 INSERT OR IGNORE INTO statuses VALUES ('active','doc');
 INSERT OR IGNORE INTO statuses VALUES ('archived','doc');
@@ -375,6 +376,7 @@ INSERT OR IGNORE INTO statuses VALUES ('active','rule');
 INSERT OR IGNORE INTO statuses VALUES ('deprecated','rule');
 INSERT OR IGNORE INTO statuses VALUES ('active','playbook');
 INSERT OR IGNORE INTO statuses VALUES ('deprecated','playbook');
+INSERT OR IGNORE INTO statuses VALUES ('active','binder');
 INSERT OR IGNORE INTO relation_names VALUES ('references','Source material (doc→doc, doc→task, doc→rule)');
 INSERT OR IGNORE INTO relation_names VALUES ('implements','This work satisfies that (task→doc, task→rule)');
 INSERT OR IGNORE INTO relation_names VALUES ('follows','This work obeys that (task→rule, task→playbook)');
@@ -387,6 +389,8 @@ INSERT OR IGNORE INTO relation_names VALUES ('gates','This rule gates that task
 INSERT OR IGNORE INTO relation_names VALUES ('triggers','This playbook run applies to that work (playbook→task)');
 INSERT OR IGNORE INTO relation_names VALUES ('contains','Parent contains a nested artifact (any→any)');
 INSERT OR IGNORE INTO relation_names VALUES ('part_of','Artifact belongs to a parent artifact (any→any)');
+INSERT OR IGNORE INTO relation_names VALUES ('organizes','Binder provides an organizational location for an artifact without execution semantics');
+INSERT OR IGNORE INTO relation_names VALUES ('filed_in','Artifact is filed in a Binder; reverse of organizes');
 CREATE INDEX IF NOT EXISTS edges_to_id_idx ON edges(to_id);
 `;
 
@@ -436,6 +440,11 @@ const CORE_LEDGER_VERSIONS: ReadonlyArray<{ version: number; name: string; check
 	{ version: 6, name: "artifact-trash", checksum: "4a75dbec2892deb54bcc1afdf0d51d81f03a8d10861787d083784a29e5c7e8f9" },
 	{ version: 7, name: "discuss-native", checksum: "ab7bdd04824bd93681917807b817d6e08b9825af90161e3ccd6d6663021dc6a0" },
 	{ version: 8, name: "discuss-options", checksum: "ba1fc5ab7cfe9166d71cc1842f13bc32a0905d08696006cec202196a70c832e8" },
+	{
+		version: 9,
+		name: "binder-hierarchy-and-label-inheritance",
+		checksum: "fbd0c8059363ab4acea78a151262da73ef87766755fe799586cb63a6405d9e3c",
+	},
 ];
 
 export function migrationLedger(db: Db): ModuleMigrationRow[] {
@@ -1047,6 +1056,20 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			}
 		},
 	},
+	{
+		version: 31,
+		name: "binder-hierarchy-and-label-inheritance",
+		// Binders reuse the existing artifacts/edges/scope stores. Only the kind/status vocabulary
+		// and organizational relation pair are new; paths and inherited labels stay computed views.
+		up: (db) => {
+			db.exec(`
+				INSERT OR IGNORE INTO kinds VALUES ('binder','Organizational directory — a stable path segment for browsing artifacts without changing their identity');
+				INSERT OR IGNORE INTO statuses VALUES ('active','binder');
+				INSERT OR IGNORE INTO relation_names VALUES ('organizes','Binder provides an organizational location for an artifact without execution semantics');
+				INSERT OR IGNORE INTO relation_names VALUES ('filed_in','Artifact is filed in a Binder; reverse of organizes');
+			`);
+		},
+	},
 ];
 
 /**

package/src/handlers/artifact-trash.ts

@@ -8,6 +8,7 @@ import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { removeArtifactSubtree } from "../artifact/artifact-subtree.ts";
 import type { ArtifactTrashStore } from "../artifact/artifact-trash-store.ts";
+import { BINDER_KIND } from "../binder/binder.ts";
 import { looseObjectSchema, numberProp, passthroughOutput, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "artifact";
@@ -30,6 +31,14 @@ function requireId(input: Record<string, unknown>): string {
 	return id;
 }
 
+function requireGenericTrashId(artifacts: ArtifactStore, input: Record<string, unknown>): string {
+	const id = requireId(input);
+	if (artifacts.get(id)?.kind === BINDER_KIND) {
+		throw validationError("Binder removal requires binders.remove so a non-empty directory cannot be orphaned");
+	}
+	return id;
+}
+
 export function registerArtifactTrashOperations(registry: VehicleRegistry, artifacts: ArtifactStore & ArtifactTrashStore): void {
 	const define = (
 		action: string,
@@ -72,12 +81,12 @@ export function registerArtifactTrashOperations(registry: VehicleRegistry, artif
 
 	define(
 		"remove",
-		"Moves any artifact to a time-gated trash, excluded from list/query but still directly showable, restorable via artifact.restore until the purge deadline.",
+		"Moves a non-Binder artifact to a time-gated trash, excluded from list/query but still directly showable, restorable via artifact.restore until the purge deadline. Binders require binders.remove so non-empty directories are protected.",
 		"local-write",
 		{ id: stringProp, reason: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
 		["id"],
 		(input) =>
-			artifacts.trash(requireId(input), {
+			artifacts.trash(requireGenericTrashId(artifacts, input), {
 				reason: typeof input.reason === "string" ? input.reason : undefined,
 				context: eventContext(input),
 			}),
@@ -90,7 +99,7 @@ export function registerArtifactTrashOperations(registry: VehicleRegistry, artif
 		{ id: stringProp, reason: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
 		["id"],
 		(input) =>
-			removeArtifactSubtree(artifacts, requireId(input), {
+			removeArtifactSubtree(artifacts, requireGenericTrashId(artifacts, input), {
 				reason: typeof input.reason === "string" ? input.reason : undefined,
 				context: eventContext(input),
 			}),