@danypops/papyrus 0.22.0 → 0.24.0

package/README.md

@@ -122,6 +122,7 @@ Agent-facing domain tools own lifecycle invariants and sit above this store API:
 - **`docs`** — create/update/list/show, activate/archive/reopen, and document-safe graph links; Note mutations remain behind the Notes facade
 - **`rules`** — create/update/list/show/preview, enable/disable, and attach governance gates to tasks
 - **`skills`** — create/update/list/show/invoke/run, enable/disable, create compatibility templates, and atomically instantiate parameterized workflow runs
+- **`playbooks`** — a completely different beast from Skills, not a subtype: a trigger and an ordered list of steps an agent reads and follows, never mechanically instantiated and never composed the way Skills call other Skills. create/update/list/show/invoke, enable/disable
 
 Every tool operation is registered in the daemon’s `/api/v1/ops` registry; parity is verified in tests. The task consumer uses the `tasks.graph` operation, which returns task nodes with explicit parent, child, and dependency IDs rather than leaking SQLite rows or asking the UI to reconstruct relationships.
 
@@ -143,6 +144,8 @@ Tasks, Docs, Rules, and Skills all support first-class `update` (title/body/labe
 - `/docs` — searchable non-Note documents, lifecycle, details, edit, and graph links
 - `/rules` — severity/condition rows, exact injection preview, edit, enable/disable, and task gating
 - `/skills` — trigger/tools rows, edit, invocation into the editor, and artifact templates
+- `/playbooks` — trigger/tools rows, edit, invocation into the editor, and graph links
+- `/playbook <name>` — tab-completes active playbook titles and places that one's invocation directly in the editor, one step instead of browse-then-select; no argument falls back to the full `/playbooks` browser
 
 All frontends use daemon-backed domain operations; none opens SQLite from the Pi process. **Show details** opens a bounded navigable view across Tasks, Notes, Docs, Rules, legacy Skills, templates, and workflow Skills. User-authored bodies render as width-aware Markdown with headings, emphasis, links, quotes, lists, tables, inline/fenced code, syntax highlighting, and every color/decorative style derived dynamically from the active Pi theme. Generated lifecycle, metadata, checklist, gate, history, and relationship sections keep explicit semantic theme colors. `↑/↓` scrolls, `←/→` pans wide relationships, and Esc returns to the browser; non-interactive clients receive stable source text.
 

package/extension/src/artifact-status-presentation.ts

@@ -36,6 +36,11 @@ export const SKILL_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
 	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
 };
 
+export const PLAYBOOK_STATUS_PRESENTATION: Record<string, StatusPresentation> = {
+	active: { label: "active", glyph: "●", color: "success" },
+	deprecated: { label: "deprecated", glyph: "○", color: "muted" },
+};
+
 /**
  * Keyed by extra.discussion.state, not the shared Doc status column -- a settled Discussion's
  * doc.status becomes "archived", but a deferred one stays "active" at the doc level (see

package/extension/src/domain-tools.ts

@@ -521,6 +521,52 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "playbooks",
+		label: "Playbooks",
+		description: "Playbook domain tool -- a completely different beast from the skills tool, not a subtype of it. A Playbook is a trigger and an ordered list of steps an agent reads and follows; it is never mechanically instantiated the way a Skill's artifact-template or workflow blueprint is, and it never composes other Playbooks. ACTIONS: create, list, show, invoke, enable, disable, assign_project, update, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. invoke renders the trigger/steps/tools into guidance plus any real linked artifacts. update changes title/body/labels (at least one required) and is refused for a read-only external projection. remove moves a Playbook to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the playbook's exact title) over `id` -- id is a backend implementation detail, resolved from name automatically.",
+		parameters: Type.Object({
+			action: Type.String(), id: Type.Optional(Type.String()), name: Type.Optional(Type.String()), title: Type.Optional(Type.String()),
+			body: Type.Optional(Type.String()), trigger: Type.Optional(Type.String()), steps: Type.Optional(Type.Array(Type.String())),
+			tools: Type.Optional(Type.Array(Type.String())), labels: Type.Optional(Type.Array(Type.String())),
+			extra: Type.Optional(Type.Record(Type.String(), Type.Unknown())), status: Type.Optional(Type.String()),
+			text: Type.Optional(Type.String()), limit: Type.Optional(Type.Number()),
+			project_root: Type.Optional(Type.String()), reason: Type.Optional(Type.String()),
+		}),
+		renderCall(args, theme) { return renderPapyrusToolCall("Playbooks", args, theme); },
+		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
+		async execute(_id, rawParams) {
+			try {
+				const params: Record<string, unknown> = { ...rawParams };
+				const action = params.action;
+				await resolveNameFields(params, [
+					{ nameKey: "name", idKey: "id", listOperation: "playbooks.list", baseRequest: { project_root: params.project_root } },
+				]);
+				if (action === "create") {
+					const artifact = await callService<Record<string, unknown>, Artifact>("playbooks.create", params);
+					return text(`Created playbook ${artifactLine(artifact)}`, createArtifactDetails("playbooks.create", artifact));
+				}
+				if (action === "list") {
+					const rows = await callService<Record<string, unknown>, Artifact[]>("playbooks.list", params);
+					return text(rows.length ? artifactLines(rows).join("\n") : "No playbooks found.", createArtifactListDetails("playbooks.list", rows));
+				}
+				if (action === "invoke") {
+					const invocation = await callService<Record<string, unknown>, string>("playbooks.invoke", params);
+					return text(invocation, createPreviewDetails("playbooks.invoke", "Playbook invocation", invocation));
+				}
+				const trashResult = await handleArtifactRemoveRestore(action, params);
+				if (trashResult) return trashResult;
+				const operations = { show: "playbooks.show", enable: "playbooks.enable", disable: "playbooks.disable", assign_project: "playbooks.assign_project", update: "playbooks.update" } as const;
+				const operation = operations[action as keyof typeof operations];
+				if (!operation) throw new Error(`unknown playbooks action: ${action}`);
+				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
+				return text(`${artifactLine(artifact)}${action === "show" ? `\n\n${artifact.body}` : ""}`, createArtifactDetails(operation, artifact));
+			} catch (error) {
+				throw new Error(`playbooks failed: ${error instanceof Error ? error.message : error}`);
+			}
+		},
+	});
+
 	pi.registerTool({
 		name: "skills",
 		label: "Skills",

package/extension/src/index.ts

@@ -22,6 +22,7 @@ import type { GateResult } from "../../src/domain/gate.ts";
 import { formatMetadata } from "./artifact-format.ts";
 import { callService } from "./service-client.ts";
 import { registerDomainTools } from "./domain-tools.ts";
+import { registerPlaybookBridge } from "./playbook-bridge.ts";
 import type { TaskGraph, TaskStatus } from "../../src/task-service.ts";
 import { ActiveTaskContinuation, automaticPauseReason, shouldResumeFocusOnHumanInput, type ActiveTaskMarker } from "./active-task-continuation.ts";
 import { buildTaskWidgetProjection, type TaskWidgetProjection } from "./task-widget.ts";
@@ -159,6 +160,7 @@ class TaskOverlay {
 export default async function (pi: ExtensionAPI) {
 	setTaskFocusEventBus(pi);
 	registerDomainTools(pi);
+	registerPlaybookBridge(pi);
 	let contextInjectionSequence = 0;
 	const contextInjectionProducerId = randomUUID();
 	let previousContextInjectionFingerprint: string | undefined;
@@ -416,12 +418,13 @@ export default async function (pi: ExtensionAPI) {
 	// ── Interactive artifact browsers ──────────────────────────────────
 
 	// Lazy imports keep TUI components out of non-interactive startup paths.
-	const [tasksModule, docsModule, notesModule, rulesModule, skillsModule, discussModule] = await Promise.all([
+	const [tasksModule, docsModule, notesModule, rulesModule, skillsModule, playbooksModule, discussModule] = await Promise.all([
 		import("./tasks.ts"),
 		import("./docs.ts"),
 		import("./notes.ts"),
 		import("./rules.ts"),
 		import("./skills.ts"),
+		import("./playbooks.ts"),
 		import("./discuss.ts"),
 	]);
 	let overlay: TaskOverlay | undefined;
@@ -455,6 +458,15 @@ export default async function (pi: ExtensionAPI) {
 		description: "Browse and invoke Papyrus skills and templates (interactive)",
 		handler: async (_args, ctx) => { await skillsModule.showSkills(ctx); },
 	});
+	pi.registerCommand("playbooks", {
+		description: "Browse, edit, and invoke Papyrus playbooks -- trigger/steps guidance an agent reads and follows (interactive)",
+		handler: async (_args, ctx) => { await playbooksModule.showPlaybooks(ctx); },
+	});
+	pi.registerCommand("playbook", {
+		description: "Open one Papyrus playbook directly by name (tab-completes active playbook titles) and place its invocation in the editor; no argument opens the full /playbooks browser instead",
+		getArgumentCompletions: (argumentPrefix) => playbooksModule.playbookArgumentCompletions(argumentPrefix),
+		handler: async (args, ctx) => { await playbooksModule.openPlaybookByName(args, ctx); },
+	});
 	pi.registerCommand("discuss", {
 		description: "Browse Papyrus Discussions and reply, defer, resume, settle, or block/unblock a task (interactive)",
 		handler: async (_args, ctx) => { await discussModule.showDiscussions(ctx); },

package/extension/src/playbook-bridge.ts

@@ -0,0 +1,90 @@
+/**
+ * playbook-bridge.ts — materializes active Papyrus Playbooks as real SKILL.md files so they
+ * show up in Pi's own native skill catalog and become /skill:name-invocable, through Pi's
+ * unmodified, documented resources_discover mechanism (no Pi source touched).
+ *
+ * Playbooks live in SQLite, not on disk, so they can't satisfy Pi's skill-loading pipeline
+ * directly (Skill.filePath is required there). This bridges the gap the other direction:
+ * on every resources_discover (session start and /reload), wipe and rebuild a cache directory
+ * from the current playbooks.list, so a disabled/removed/renamed Playbook's stale file is never
+ * served. Any failure degrades to "no extra skills this cycle" -- a Papyrus daemon hiccup must
+ * never break Pi's own resource discovery.
+ */
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import { callService } from "./service-client.ts";
+
+const PLAYBOOK_BRIDGE_MAX_PLAYBOOKS = 100;
+const PLAYBOOK_BRIDGE_DESCRIPTION_MAX_CHARACTERS = 1000;
+
+function slugify(title: string): string {
+	const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 64);
+	return slug.length > 0 ? slug : "playbook";
+}
+
+function playbookCacheDir(): string {
+	const base = process.env["XDG_CACHE_HOME"] ?? join(homedir(), ".cache");
+	return join(base, "papyrus", "playbooks");
+}
+
+function stringList(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === "string") : [];
+}
+
+function playbookSkillMarkdown(playbook: Artifact): string {
+	const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
+	const steps = stringList(playbook.extra["steps"]);
+	const tools = stringList(playbook.extra["tools"]);
+	const description = trigger.replace(/\n/g, " ").slice(0, PLAYBOOK_BRIDGE_DESCRIPTION_MAX_CHARACTERS);
+	return [
+		"---",
+		`name: ${slugify(playbook.title)}`,
+		`description: ${description}`,
+		"---",
+		"",
+		`# ${playbook.title}`,
+		"",
+		`Materialized from a live Papyrus playbook; edits here are lost on the next refresh. Edit the playbook itself instead (the playbooks tool, action=update), then /reload.`,
+		"",
+		`Trigger: ${trigger}`,
+		"",
+		...(playbook.body ? [`Context: ${playbook.body}`, ""] : []),
+		...(steps.length > 0 ? ["## Steps", "", ...steps.map((step, index) => `${index + 1}. ${step}`), ""] : []),
+		...(tools.length > 0 ? [`Tools: ${tools.join(", ")}`, ""] : []),
+	].join("\n");
+}
+
+/** Exported for direct testing without a real ExtensionAPI. */
+export async function materializePlaybookSkillPaths(): Promise<string[]> {
+	const dir = playbookCacheDir();
+	if (existsSync(dir)) rmSync(dir, { recursive: true, force: true });
+	const playbooks = await callService<Record<string, unknown>, Artifact[]>("playbooks.list", { status: "active", limit: PLAYBOOK_BRIDGE_MAX_PLAYBOOKS });
+	if (playbooks.length === 0) return [];
+	mkdirSync(dir, { recursive: true });
+	const usedSlugs = new Set<string>();
+	const paths: string[] = [];
+	for (const playbook of playbooks) {
+		let slug = slugify(playbook.title);
+		if (usedSlugs.has(slug)) slug = `${slug}-${playbook.id.slice(0, 8)}`; // a real title collision, not the common case
+		usedSlugs.add(slug);
+		const skillDir = join(dir, slug);
+		mkdirSync(skillDir, { recursive: true });
+		const filePath = join(skillDir, "SKILL.md");
+		writeFileSync(filePath, playbookSkillMarkdown(playbook), "utf8");
+		paths.push(filePath);
+	}
+	return paths;
+}
+
+export function registerPlaybookBridge(pi: ExtensionAPI): void {
+	pi.on("resources_discover", async () => {
+		try {
+			return { skillPaths: await materializePlaybookSkillPaths() };
+		} catch {
+			return {};
+		}
+	});
+}

package/extension/src/playbooks.ts

@@ -0,0 +1,97 @@
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import type { ExtensionCommandContext, Theme } from "@earendil-works/pi-coding-agent";
+import type { Artifact } from "../../src/domain/artifact.ts";
+import { showArtifactBrowser, showArtifactDetails } from "./artifact-browser.ts";
+import { PLAYBOOK_STATUS_PRESENTATION } from "./artifact-status-presentation.ts";
+import { matchArtifactByName } from "./domain-tools.ts";
+import { callService } from "./service-client.ts";
+
+const PLAYBOOK_COMPLETION_MAX_CANDIDATES = 100;
+
+async function activePlaybooks(): Promise<Artifact[]> {
+	return callService<Record<string, unknown>, Artifact[]>("playbooks.list", { status: "active", limit: PLAYBOOK_COMPLETION_MAX_CANDIDATES });
+}
+
+/** `/playbook <tab>` completions -- title-prefix match, since that's what a human actually types, not a full-text search of body content. */
+export async function playbookArgumentCompletions(argumentPrefix: string): Promise<AutocompleteItem[] | null> {
+	try {
+		const needle = argumentPrefix.trim().toLowerCase();
+		const rows = await activePlaybooks();
+		return rows
+			.filter((row) => row.title.toLowerCase().startsWith(needle))
+			.sort((a, b) => a.title.localeCompare(b.title))
+			.map((row) => ({ value: row.title, label: row.title, description: typeof row.extra["trigger"] === "string" ? row.extra["trigger"] : undefined }));
+	} catch {
+		return null; // a Papyrus daemon hiccup degrades to "no suggestions", never breaks the command line
+	}
+}
+
+/** `/playbook <name>` (no args opens the full browser instead): resolves by exact title, then places its invocation directly in the editor -- one step, not browse-then-select-then-invoke. */
+export async function openPlaybookByName(name: string, ctx: ExtensionCommandContext): Promise<void> {
+	if (!name.trim()) { await showPlaybooks(ctx); return; }
+	try {
+		const id = matchArtifactByName(await activePlaybooks(), name);
+		const invocation = await callService<Record<string, unknown>, string>("playbooks.invoke", { id });
+		ctx.ui.setEditorText(invocation);
+		ctx.ui.notify(`"${name.trim()}" invocation placed in the editor`, "info");
+	} catch (error) {
+		ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+	}
+}
+
+const PLAYBOOK_RELATIONS = ["references", "documents", "relates_to", "contains", "part_of"];
+
+function strings(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+export function playbookRowMeta(playbook: Artifact): string {
+	const trigger = typeof playbook.extra["trigger"] === "string" ? `when ${playbook.extra["trigger"]}` : "manual invocation";
+	const tools = strings(playbook.extra["tools"]);
+	return [trigger, tools.join(", ")].filter(Boolean).join(" \u00b7 ");
+}
+
+export async function showPlaybooks(ctx: ExtensionCommandContext): Promise<void> {
+	await showArtifactBrowser(ctx, {
+		kind: "playbook",
+		title: "Playbooks",
+		listOperation: "playbooks.list",
+		statusOrder: ["active", "deprecated"],
+		presentation: PLAYBOOK_STATUS_PRESENTATION,
+		rowMeta: playbookRowMeta,
+		actions: (playbook) => ["Show details", "Edit", "Invoke", "Link artifact", playbook.status === "active" ? "Disable" : "Enable"],
+		handleAction: async (choice, playbook, commandCtx) => {
+			if (choice === "Show details") {
+				await showArtifactDetails(commandCtx, playbook.id, "playbooks.show");
+				return;
+			}
+			if (choice === "Edit") {
+				const title = await commandCtx.ui.input("Title:", playbook.title);
+				if (title === undefined) return; // canceled
+				const body = await commandCtx.ui.input("Body:", playbook.body);
+				if (body === undefined) return; // canceled
+				const updated = await callService<Record<string, unknown>, Artifact>("playbooks.update", { id: playbook.id, title, body });
+				commandCtx.ui.notify(`Updated "${updated.title}"`, "info");
+				return;
+			}
+			if (choice === "Invoke") {
+				const invocation = await callService<Record<string, unknown>, string>("playbooks.invoke", { id: playbook.id });
+				commandCtx.ui.setEditorText(invocation);
+				commandCtx.ui.notify("Invocation placed in the editor", "info");
+				return;
+			}
+			if (choice === "Link artifact") {
+				const targetId = await commandCtx.ui.input("Target artifact id:", "");
+				if (!targetId) return;
+				const relation = await commandCtx.ui.select("Relation", PLAYBOOK_RELATIONS);
+				if (!relation) return;
+				await callService("graph.link", { from: playbook.id, relation, to: targetId });
+				commandCtx.ui.notify(`Linked ${playbook.id} --${relation}--> ${targetId}`, "info");
+				return;
+			}
+			const operation = choice === "Disable" ? "playbooks.disable" : "playbooks.enable";
+			const updated = await callService<Record<string, unknown>, Artifact>(operation, { id: playbook.id });
+			commandCtx.ui.notify(`${updated.id} \u2192 [${updated.status}]`, "info");
+		},
+	});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/cli.ts

@@ -112,6 +112,13 @@ const USAGE = `Usage:
   papyrus skills instantiate <template-id> [--title <title>] [--body <body>] [--status <status>] [--labels-json <json>] [--extra-json <json>] [--json]
   papyrus skills assign-project <id> [project-root] [--json]
   papyrus skills update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--json]
+  papyrus playbooks create --title <title> [--body <body>] [--trigger <text>] [--steps-json <json>] [--tools-json <json>] [--labels-json <json>] [--extra-json <json>] [--project-root <path>] [--json]
+  papyrus playbooks list [--status <status>] [--text <query>] [--limit <count>] [--project-root <path>] [--json]
+  papyrus playbooks show <id> [--json]
+  papyrus playbooks invoke <id> [--json]
+  papyrus playbooks enable|disable <id> [--json]
+  papyrus playbooks assign-project <id> [project-root] [--json]
+  papyrus playbooks update <id> [--title <title>] [--body <body>] [--labels-json <json>] [--json]
   papyrus notes capture <request> [--title <title>] [--json]
   papyrus notes list [--status <draft|active|archived>] [--text <query>] [--limit <count>] [--json]
   papyrus notes show <id> [--json]
@@ -769,6 +776,104 @@ export async function runRulesCli(args: string[], client: TaskCliClient, project
 	return json ? JSON.stringify(result) : human;
 }
 
+export async function runPlaybooksCli(args: string[], client: TaskCliClient): Promise<string> {
+	const json = args.includes("--json");
+	const positional: string[] = [];
+	let title: string | undefined;
+	let body: string | undefined;
+	let trigger: string | undefined;
+	let steps: string[] | undefined;
+	let tools: string[] | undefined;
+	let labels: string[] | undefined;
+	let extra: Record<string, unknown> | undefined;
+	let status: string | undefined;
+	let text: string | undefined;
+	let limit: number | undefined;
+	let playbookProjectRoot: string | undefined;
+	for (let index = 0; index < args.length; index++) {
+		const argument = args[index]!;
+		if (argument === "--json") continue;
+		if (argument === "--title") { title = args[++index]; if (title === undefined) throw new Error("--title requires a value"); continue; }
+		if (argument === "--body") { body = args[++index]; if (body === undefined) throw new Error("--body requires a value"); continue; }
+		if (argument === "--trigger") { trigger = args[++index]; if (trigger === undefined) throw new Error("--trigger requires a value"); continue; }
+		if (argument === "--steps-json") { steps = parseJsonStringArrayFlag(args[++index], "--steps-json"); continue; }
+		if (argument === "--tools-json") { tools = parseJsonStringArrayFlag(args[++index], "--tools-json"); continue; }
+		if (argument === "--labels-json") { labels = parseJsonStringArrayFlag(args[++index], "--labels-json"); continue; }
+		if (argument === "--extra-json") { extra = parseJsonObjectFlag(args[++index], "--extra-json"); continue; }
+		if (argument === "--status") { status = args[++index]; if (!status) throw new Error("--status requires a value"); continue; }
+		if (argument === "--text") { text = args[++index]; if (text === undefined) throw new Error("--text requires a value"); continue; }
+		if (argument === "--project-root") { playbookProjectRoot = args[++index]; if (!playbookProjectRoot) throw new Error("--project-root requires a value"); continue; }
+		if (argument === "--limit") {
+			const value = args[++index];
+			if (!value || Number.isNaN(Number(value))) throw new Error("--limit requires a numeric value");
+			limit = Number(value);
+			continue;
+		}
+		if (argument.startsWith("--")) throw new Error(`unknown playbooks option ${argument}`);
+		positional.push(argument);
+	}
+	const [action, id, second] = positional;
+	let result: unknown;
+	let human: string;
+	switch (action) {
+		case "create": {
+			if (id) throw new Error("playbooks create accepts no positional arguments");
+			if (!title) throw new Error("playbooks create requires --title");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.create", { title, body, trigger, steps, tools, labels, extra, project_root: playbookProjectRoot });
+			result = artifact;
+			human = `Created playbook: ${artifactLabel(artifact)}`;
+			break;
+		}
+		case "list": {
+			if (id) throw new Error("playbooks list accepts no positional arguments");
+			const rows = await client.call<Record<string, unknown>, CliArtifact[]>("playbooks.list", { status, text, limit, project_root: playbookProjectRoot });
+			result = rows;
+			human = rows.length === 0 ? "No playbooks found." : rows.map((row) => artifactLabel(row)).join("\n");
+			break;
+		}
+		case "show": {
+			if (!id || second) throw new Error("playbooks show requires exactly one playbook id");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.show", { id });
+			result = artifact;
+			human = `${artifactLabel(artifact)}\n\n${artifact.body ?? ""}`;
+			break;
+		}
+		case "invoke": {
+			if (!id || second) throw new Error("playbooks invoke requires exactly one playbook id");
+			const invocation = await client.call<Record<string, unknown>, string>("playbooks.invoke", { id });
+			result = invocation;
+			human = invocation;
+			break;
+		}
+		case "enable":
+		case "disable": {
+			if (!id || second) throw new Error(`playbooks ${action} requires exactly one playbook id`);
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>(`playbooks.${action}`, { id });
+			result = artifact;
+			human = `${artifactLabel(artifact)}`;
+			break;
+		}
+		case "assign-project": {
+			if (!id || second === undefined && positional.length > 2) throw new Error("playbooks assign-project requires <id> [project-root]");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.assign_project", { id, project_root: second });
+			result = artifact;
+			human = second ? `Assigned ${id} to ${second}` : `Unscoped ${id}`;
+			break;
+		}
+		case "update": {
+			if (!id || second) throw new Error("playbooks update requires exactly one playbook id");
+			if (title === undefined && body === undefined && labels === undefined) throw new Error("playbooks update requires --title, --body, or --labels-json");
+			const artifact = await client.call<Record<string, unknown>, CliArtifact>("playbooks.update", { id, title, body, labels });
+			result = artifact;
+			human = `${artifactLabel(artifact)}`;
+			break;
+		}
+		default:
+			throw new Error("playbooks action must be create, list, show, invoke, enable, disable, assign-project, or update");
+	}
+	return json ? JSON.stringify(result) : human;
+}
+
 export async function runArtifactCli(args: string[], client: TaskCliClient, projectRoot: string = process.cwd()): Promise<string> {
 	const json = args.includes("--json");
 	const positional: string[] = [];
@@ -1532,6 +1637,11 @@ export async function main(args: string[] = process.argv.slice(2)): Promise<void
 		console.log(await runSkillCli(args.slice(1), client));
 		return;
 	}
+	if (command === "playbooks") {
+		const client = await connectPapyrusClient();
+		console.log(await runPlaybooksCli(args.slice(1), client));
+		return;
+	}
 	if (command === "notes") {
 		const client = await connectPapyrusClient();
 		console.log(await runNoteCli(args.slice(1), client));

package/src/constants.ts

@@ -7,7 +7,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 = 17;
+export const SQLITE_SCHEMA_VERSION = 18;
 export const SERVICE_MAX_BODY_BYTES = 1_048_576;
 
 export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
@@ -99,6 +99,7 @@ export const SKILL_MAX_RENDERED_BYTES = 1_048_576;
  */
 export const SKILL_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
 export const SKILL_INVOCATION_MAX_CALL_DEPTH = 4;
+export const PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS = 20;
 
 /**
  * At the core, a workflow Skill creates Tasks and begins a pipeline -- an Ansible playbook or

package/src/db.ts

@@ -253,6 +253,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 ('skill','Parameterized workflow bundle — inputs and templates load tasks, rules, and docs');
+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 statuses VALUES ('draft','doc');
 INSERT OR IGNORE INTO statuses VALUES ('active','doc');
 INSERT OR IGNORE INTO statuses VALUES ('archived','doc');
@@ -266,6 +267,8 @@ INSERT OR IGNORE INTO statuses VALUES ('active','rule');
 INSERT OR IGNORE INTO statuses VALUES ('deprecated','rule');
 INSERT OR IGNORE INTO statuses VALUES ('active','skill');
 INSERT OR IGNORE INTO statuses VALUES ('deprecated','skill');
+INSERT OR IGNORE INTO statuses VALUES ('active','playbook');
+INSERT OR IGNORE INTO statuses VALUES ('deprecated','playbook');
 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→skill)');
@@ -504,6 +507,23 @@ const FUTURE_MIGRATIONS: ReadonlyArray<PapyrusMigration> = [
 			`);
 		},
 	},
+	{
+		version: 18,
+		name: "playbook-kind",
+		// Playbooks (trigger/steps/tools guidance an agent reads and follows) were a subtype-less
+		// shape squeezed into the "skill" kind alongside artifact-templates and workflow blueprints
+		// -- fundamentally different mechanisms (mechanical multi-artifact instantiation) from a flat
+		// step list. Split into its own kind; only rows with no subtype move -- artifact-template and
+		// workflow rows stay exactly where they are.
+		up: (db) => {
+			db.exec(`
+				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 statuses VALUES ('active','playbook');
+				INSERT OR IGNORE INTO statuses VALUES ('deprecated','playbook');
+				UPDATE artifacts SET kind = 'playbook' WHERE kind = 'skill' AND (subtype IS NULL OR subtype = '');
+			`);
+		},
+	},
 ];
 
 /**

package/src/domain-services.ts

@@ -4,6 +4,7 @@ import {
 	ARTIFACT_LABEL_MAX_LENGTH,
 	ARTIFACT_SCOPE_MAX_ARTIFACTS,
 	ARTIFACT_TITLE_MAX_LENGTH,
+	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
 	RULE_TEXT_HARD_LIMIT_CHARACTERS,
 	SKILL_INVOCATION_MAX_CALL_DEPTH,
 	SKILL_INVOCATION_MAX_LINKED_ARTIFACTS,
@@ -514,3 +515,95 @@ export function transitionSkill(artifacts: ArtifactStore, id: string, action: Sk
 	if (skill.status !== expected) throw new Error(`cannot ${action} skill from ${skill.status}`);
 	return artifacts.setStatus(id, target, context)!;
 }
+
+/**
+ * Playbooks: a trigger and an ordered list of steps an agent reads and follows -- a completely
+ * different beast from Skills, not a subtype of one. A Skill (artifact-template or workflow) is
+ * mechanically instantiated into other artifacts; a Playbook is never instantiated, it's read
+ * and followed, and it never composes other Playbooks the way a Skill can call another Skill.
+ */
+export interface CreatePlaybookInput {
+	title: string;
+	body?: string;
+	trigger?: string;
+	steps?: string[];
+	tools?: string[];
+	labels?: string[];
+	extra?: Record<string, unknown>;
+	projectRoot?: string;
+}
+
+export type PlaybookTransition = "enable" | "disable";
+export type UpdatePlaybookInput = UpdateContentInput;
+
+export function createPlaybook(artifacts: ArtifactStore, scopes: ArtifactScopeStore, input: CreatePlaybookInput, context?: ArtifactEventContext): Artifact {
+	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
+	const playbook = artifacts.create({
+		kind: "playbook",
+		status: "active", // explicit; see createDocument for why defaultStatusFor is not trusted here
+		title: input.title,
+		body: input.body,
+		labels: input.labels,
+		extra: {
+			...(input.extra ?? {}),
+			...(input.trigger ? { trigger: input.trigger } : {}),
+			...(input.steps ? { steps: input.steps } : {}),
+			...(input.tools ? { tools: input.tools } : {}),
+		},
+	}, context);
+	scopes.assign(playbook.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	return playbook;
+}
+
+export function listPlaybooks(artifacts: ArtifactStore, scopes: ArtifactScopeStore, filter: ListFilter): Artifact[] {
+	return listScoped(artifacts, scopes, "playbook", filter);
+}
+
+export function assignPlaybookProject(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string, projectRoot: string | undefined): Artifact {
+	return assignArtifactProject(artifacts, scopes, id, "playbook", projectRoot);
+}
+
+export function showPlaybook(artifacts: ArtifactStore, id: string): Artifact {
+	requireKind(artifacts, id, "playbook");
+	return artifacts.get(id, { tree: true })!;
+}
+
+export function updatePlaybook(artifacts: ArtifactStore, id: string, input: UpdatePlaybookInput, context?: ArtifactEventContext): Artifact {
+	requireContentUpdateFields(input);
+	assertTitleBounds(input.title);
+	assertBodyBounds(input.body);
+	assertLabelsBounds(input.labels);
+	const playbook = requireLocallyOwnedContent(requireKind(artifacts, id, "playbook"));
+	const updated = artifacts.updateContent(playbook.id, input, context);
+	if (!updated) throw new Error(`playbook "${id}" not found`);
+	return updated;
+}
+
+export function transitionPlaybook(artifacts: ArtifactStore, id: string, action: PlaybookTransition, context?: ArtifactEventContext): Artifact {
+	const playbook = requireKind(artifacts, id, "playbook");
+	const expected = action === "enable" ? "deprecated" : "active";
+	const target = action === "enable" ? "active" : "deprecated";
+	if (playbook.status !== expected) throw new Error(`cannot ${action} playbook from ${playbook.status}`);
+	return artifacts.setStatus(id, target, context)!;
+}
+
+/** Renders trigger/steps/tools into readable guidance, plus any real linked artifacts. No nested playbook-calls-playbook composition -- a Playbook is a flat procedure, not a composable bundle. */
+export function playbookInvocation(artifacts: ArtifactStore, id: string): string {
+	const playbook = requireKind(artifacts, id, "playbook");
+	const trigger = typeof playbook.extra["trigger"] === "string" ? playbook.extra["trigger"] : "manual invocation";
+	const steps = Array.isArray(playbook.extra["steps"]) ? playbook.extra["steps"].filter((step): step is string => typeof step === "string") : [];
+	const tools = Array.isArray(playbook.extra["tools"]) ? playbook.extra["tools"].filter((tool): tool is string => typeof tool === "string") : [];
+	const sections = [[
+		`Apply Papyrus playbook "${playbook.title}" (${playbook.id}).`,
+		`Trigger: ${trigger}`,
+		...(playbook.body ? [`Context: ${playbook.body}`] : []),
+		...(steps.length ? ["Steps:", ...steps.map((step, index) => `${index + 1}. ${step}`)] : []),
+		...(tools.length ? [`Tools: ${tools.join(", ")}`] : []),
+	].join("\n")];
+	const edges = artifacts.relationships({ artifactIds: [id] }).filter((edge) => edge.from === id).slice(0, PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS);
+	const linkedLines = edges
+		.map((edge) => { const target = artifacts.get(edge.to); return target ? `- ${edge.relation} ${target.kind} "${target.title}" (${target.id})` : undefined; })
+		.filter((line): line is string => line !== undefined);
+	if (linkedLines.length > 0) sections.push(["Linked context (query Papyrus for full detail before proceeding):", ...linkedLines].join("\n"));
+	return sections.join("\n\n");
+}

package/src/modules/playbooks.ts

@@ -0,0 +1,77 @@
+/**
+ * modules/playbooks.ts — Playbooks as a Papyrus-native registered module.
+ *
+ * A Playbook (trigger + ordered steps an agent reads and follows) is a completely different
+ * beast from a Skill (a mechanically instantiated artifact-template or workflow blueprint) --
+ * its own kind, not a subtype squeezed into "skill". See domain-services.ts's Playbook section
+ * for the full rationale.
+ */
+import { assignPlaybookProject, createPlaybook, listPlaybooks, playbookInvocation, showPlaybook, transitionPlaybook, updatePlaybook } from "../domain-services.ts";
+import type { OperationDefinition } from "../module-registry.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+
+const MODULE_ID = "playbooks";
+
+type OperationInput = Record<string, unknown>;
+
+function string(input: OperationInput, key: string): string {
+	const value = input[key];
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
+	return value;
+}
+
+function optionalString(input: OperationInput, key: string): string | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "string") throw new Error(`${key} must be a string`);
+	return value;
+}
+
+function optionalNumber(input: OperationInput, key: string): number | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a number`);
+	return value;
+}
+
+const eventContext = (input: OperationInput) => ({
+	actor: optionalString(input, "actor"),
+	source: optionalString(input, "source"),
+	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
+});
+
+const artifactFilter = (input: OperationInput) => ({
+	status: optionalString(input, "status"),
+	text: optionalString(input, "text"),
+	limit: optionalNumber(input, "limit"),
+	projectRoot: optionalString(input, "project_root"),
+});
+
+/** This module's own operation names, the single source of truth src/service.ts's EXPECTED_OPERATION_NAMES spreads in rather than re-listing by hand. */
+export const PLAYBOOKS_OPERATION_NAMES = [
+	"playbooks.create", "playbooks.list", "playbooks.show", "playbooks.invoke", "playbooks.enable", "playbooks.disable", "playbooks.assign_project", "playbooks.update",
+] as const;
+
+export function playbooksOperations(artifacts: ArtifactStore, scopes: ArtifactScopeStore): OperationDefinition[] {
+	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
+		name, moduleId: MODULE_ID, execute,
+	});
+	return [
+		define("playbooks.create", (input: OperationInput) => createPlaybook(artifacts, scopes, {
+			title: string(input, "title"), body: optionalString(input, "body"), trigger: optionalString(input, "trigger"),
+			steps: input["steps"] as string[] | undefined, tools: input["tools"] as string[] | undefined,
+			labels: input["labels"] as string[] | undefined, extra: input["extra"] as Record<string, unknown> | undefined,
+			projectRoot: optionalString(input, "project_root"),
+		}, eventContext(input))),
+		define("playbooks.list", (input: OperationInput) => listPlaybooks(artifacts, scopes, artifactFilter(input))),
+		define("playbooks.show", (input: OperationInput) => showPlaybook(artifacts, string(input, "id"))),
+		define("playbooks.invoke", (input: OperationInput) => playbookInvocation(artifacts, string(input, "id"))),
+		define("playbooks.enable", (input: OperationInput) => transitionPlaybook(artifacts, string(input, "id"), "enable", eventContext(input))),
+		define("playbooks.disable", (input: OperationInput) => transitionPlaybook(artifacts, string(input, "id"), "disable", eventContext(input))),
+		define("playbooks.assign_project", (input: OperationInput) => assignPlaybookProject(artifacts, scopes, string(input, "id"), optionalString(input, "project_root"))),
+		define("playbooks.update", (input: OperationInput) => updatePlaybook(artifacts, string(input, "id"), {
+			title: optionalString(input, "title"), body: optionalString(input, "body"), labels: input["labels"] as string[] | undefined,
+		}, eventContext(input))),
+	];
+}

package/src/service.ts

@@ -33,6 +33,7 @@ import { logsOperations, LOGS_OPERATION_NAMES } from "./modules/logs.ts";
 import { notesOperations, NOTES_OPERATION_NAMES } from "./modules/notes.ts";
 import { rulesOperations, RULES_OPERATION_NAMES } from "./modules/rules.ts";
 import { skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.ts";
+import { playbooksOperations, PLAYBOOKS_OPERATION_NAMES } from "./modules/playbooks.ts";
 import { sessionIdentityOperations, SESSION_IDENTITY_OPERATION_NAMES } from "./modules/session-identity.ts";
 import { discussOperations, DISCUSS_OPERATION_NAMES } from "./modules/discuss.ts";
 import { tasksOperations, TASKS_OPERATION_NAMES } from "./modules/tasks.ts";
@@ -73,6 +74,7 @@ export const EXPECTED_OPERATION_NAMES = [
 	...NOTES_OPERATION_NAMES,
 	...RULES_OPERATION_NAMES,
 	...SKILLS_OPERATION_NAMES,
+	...PLAYBOOKS_OPERATION_NAMES,
 	...GRAPH_PROJECTION_OPERATION_NAMES,
 	...LOGS_OPERATION_NAMES,
 	...SESSION_IDENTITY_OPERATION_NAMES,
@@ -368,6 +370,14 @@ function handlers(
 		"skills.disable": forwardToModule("skills.disable"),
 		"skills.assign_project": forwardToModule("skills.assign_project"),
 		"skills.update": forwardToModule("skills.update"),
+		"playbooks.create": forwardToModule("playbooks.create"),
+		"playbooks.list": forwardToModule("playbooks.list"),
+		"playbooks.show": forwardToModule("playbooks.show"),
+		"playbooks.invoke": forwardToModule("playbooks.invoke"),
+		"playbooks.enable": forwardToModule("playbooks.enable"),
+		"playbooks.disable": forwardToModule("playbooks.disable"),
+		"playbooks.assign_project": forwardToModule("playbooks.assign_project"),
+		"playbooks.update": forwardToModule("playbooks.update"),
 		"skills.instantiate": (input) => {
 			const templateId = string(input, "template_id");
 			const template = artifacts.get(templateId);
@@ -429,6 +439,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority));
 	moduleRegistry.registerAll(rulesOperations(artifacts, artifactScopes));
 	moduleRegistry.registerAll(skillsOperations({ artifacts, events, scopes, artifactScopes, authority }));
+	moduleRegistry.registerAll(playbooksOperations(artifacts, artifactScopes));
 	moduleRegistry.registerAll(graphProjectionOperations(artifacts, projections, authority));
 	const registry = handlers(artifacts, gates, tasks, notes, events, scopes, () => migrateDb(db), moduleRegistry, authority);
 	const state = (): SchemaState => {