@danypops/papyrus 0.21.6 → 0.23.0

package/README.md

@@ -119,9 +119,10 @@ Agent-facing domain tools own lifecycle invariants and sit above this store API:
 
 - **`tasks`** — create/update/list/show/plan, manage the singleton active focus, replace evidence-bearing checklists, hierarchy/dependencies, lifecycle transitions, non-blocking gates, and review completion that focuses one deterministic ready successor without claiming effort
 - **`notes`** — capture/list/show deferred human intent, mark it consumed, promote it to an existing Task/Doc/Rule/Skill, or archive it with an explicit disposition
-- **`docs`** — create/list/show, activate/archive/reopen, and document-safe graph links; Note mutations remain behind the Notes facade
-- **`rules`** — create/list/show/preview, enable/disable, and attach governance gates to tasks
-- **`skills`** — create/list/show/invoke/run, enable/disable, create compatibility templates, and atomically instantiate parameterized workflow runs
+- **`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.
 
@@ -131,14 +132,19 @@ Internally, application services depend on the `ArtifactStore` and `GateRunner`
 
 Every agent domain tool (tasks, docs, rules, skills, notes, discuss) addresses its artifacts by `name` (the exact title) wherever `id` would otherwise be required -- `dependency_name`/`parent_name`/`child_name`/`root_task_name`/`depends_on_names` (tasks), `target_name` (docs link, searches every kind since a link target can be any of them), `task_name` (rules gate, discuss block/unblock), `template_name` (skills instantiate), and `blocks_task_names` (discuss open) are the name-based equivalents of their `*_id` counterparts. Resolution is an exact, case-insensitive, trimmed title match scoped like a plain list call; an unmatched or ambiguous name fails with a clear error (ambiguous names list the real ids, since that's the one point disambiguation genuinely needs them). Results returned to the agent likewise lead with name and status, never id, unless two artifacts in the same result share a title -- id is a backend implementation detail, not a conversational handle. `id` itself still works exactly as before for every action, in every tool.
 
+### Mutability
+
+Tasks, Docs, Rules, and Skills all support first-class `update` (title/body/labels, at least one required) alongside creation -- a Doc's body is no longer immutable once created. Every update is bounded the same way creation is (Rules keep their own stricter combined condition+action+body ceiling; Docs/Skills share Tasks' own length bounds) and recorded on the artifact's append-only mutation history, queryable via `graph.history`. An artifact carrying a `source:<system>` label (e.g. `source:web-spider` on an ingested page) is a read-only projection from a system Papyrus doesn't own the source of; updating one is refused with a clear error rather than silently forking it -- capture a correction as a new linked Doc instead until a write-back capability to that system exists. Notes stay behind their own facade for any content change, same as every other Notes mutation.
+
 ## Interactive frontends
 
 - `/tasks` — project/focused-graph scope, task lifecycle, append-only history, gates, dependencies, and nested metadata
 - `/note <request>` — directly capture one project-scoped deferred request without creating a Task
 - `/notes` — searchable project Notes inbox with consume, promote, and disposition-aware archive actions
-- `/docs` — searchable non-Note documents, lifecycle, details, and graph links
-- `/rules` — severity/condition rows, exact injection preview, enable/disable, and task gating
-- `/skills` — trigger/tools rows, invocation into the editor, and artifact templates
+- `/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
 
 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/discussion-picker.ts

@@ -6,12 +6,12 @@
  * anywhere in @earendil-works/pi-coding-agent or pi-tui (checked both) -- so this is a small,
  * genuinely domain-specific checkbox-list component, not a generic library replacement.
  */
-import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { matchesKey, truncateToWidth } from "@earendil-works/pi-tui";
 import type { DiscussionOptionsMode } from "../../src/domain/discussion.ts";
 
 /** Toggle with space, confirm with enter (refuses an empty confirm -- at least one pick is required), cancel with escape. */
-async function pickMultiple(ctx: ExtensionCommandContext, title: string, options: string[]): Promise<string[] | undefined> {
+async function pickMultiple(ctx: ExtensionContext, title: string, options: string[]): Promise<string[] | undefined> {
 	return ctx.ui.custom<string[] | undefined>((tui, theme, _keybindings, done) => {
 		const checked = new Set<number>();
 		let selectedIndex = 0;
@@ -49,8 +49,13 @@ async function pickMultiple(ctx: ExtensionCommandContext, title: string, options
 	});
 }
 
-/** Picks one (single) or several (multi) of the given options, or undefined if the user cancels. */
-export async function pickDiscussionOptions(ctx: ExtensionCommandContext, mode: DiscussionOptionsMode, options: string[]): Promise<string[] | undefined> {
+/**
+ * Picks one (single) or several (multi) of the given options, or undefined if the user cancels.
+ * Takes the base ExtensionContext (just .ui) rather than the wider ExtensionCommandContext, since
+ * a tool's execute() only ever receives the former -- the discuss tool's own live mode reuses
+ * this same picker, not just the /discuss TUI panel.
+ */
+export async function pickDiscussionOptions(ctx: ExtensionContext, mode: DiscussionOptionsMode, options: string[]): Promise<string[] | undefined> {
 	if (mode === "single") {
 		const pick = await ctx.ui.select("Pick one:", options);
 		return pick ? [pick] : undefined;

package/extension/src/docs.ts

@@ -24,12 +24,21 @@ export async function showDocs(ctx: ExtensionCommandContext): Promise<void> {
 		statusOrder: ["draft", "active", "archived"],
 		presentation: DOC_STATUS_PRESENTATION,
 		rowMeta: documentRowMeta,
-		actions: (document) => ["Show details", "Link artifact", ...(DOC_ACTIONS[document.status] ?? [])],
+		actions: (document) => ["Show details", "Edit", "Link artifact", ...(DOC_ACTIONS[document.status] ?? [])],
 		handleAction: async (choice, document, commandCtx) => {
 			if (choice === "Show details") {
 				await showArtifactDetails(commandCtx, document.id, "docs.show");
 				return;
 			}
+			if (choice === "Edit") {
+				const title = await commandCtx.ui.input("Title:", document.title);
+				if (title === undefined) return; // canceled
+				const body = await commandCtx.ui.input("Body:", document.body);
+				if (body === undefined) return; // canceled
+				const updated = await callService<Record<string, unknown>, Artifact>("docs.update", { id: document.id, title, body });
+				commandCtx.ui.notify(`Updated "${updated.title}"`, "info");
+				return;
+			}
 			if (choice === "Link artifact") {
 				const targetId = await commandCtx.ui.input("Target artifact id:", "");
 				if (!targetId) return;

package/extension/src/domain-tools.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type { Artifact } from "../../src/domain/artifact.ts";
 import { PROOF_TYPES } from "../../src/domain/checklist.ts";
@@ -8,7 +8,8 @@ import type { TaskHistoryPage } from "../../src/domain/task-event.ts";
 import type { TaskCompletion, TaskGraph } from "../../src/task-service.ts";
 import type { SkillWorkflowRunResult } from "../../src/skill-execution.ts";
 import type { DiscussionAndRounds } from "../../src/discussion-service.ts";
-import type { DiscussionRound } from "../../src/domain/discussion.ts";
+import { readDiscussionExtra, type DiscussionRound } from "../../src/domain/discussion.ts";
+import { pickDiscussionOptions } from "./discussion-picker.ts";
 import type { OperationName } from "../../src/service.ts";
 import { emitTaskFocusEvent } from "./task-focus-events.ts";
 import { sessionSecretField } from "./session-identity.ts";
@@ -30,6 +31,24 @@ function text(message: string, details: unknown = {}) {
 	return { content: [{ type: "text" as const, text: modelContent.text }], details };
 }
 
+/**
+ * live:true's synchronous half: renders the same picker /discuss's own "Reply" action uses when
+ * the just-created round posed a structured choice, or a plain freeform prompt otherwise -- so
+ * "ask" covers both a completely open question and a choice tied to this specific Discussion.
+ * Returns undefined on cancel or when no interactive UI is available, never throws -- an
+ * unanswered live prompt still leaves the round it already recorded intact.
+ */
+async function liveAnswer(ctx: ExtensionContext, discussion: Artifact): Promise<{ content: string; selected?: string[] } | undefined> {
+	if (!ctx.hasUI) return undefined;
+	const pending = (() => { try { return readDiscussionExtra(discussion.extra); } catch { return undefined; } })();
+	if (pending?.pendingOptions && pending.pendingOptions.length > 0 && pending.pendingOptionsMode) {
+		const selected = await pickDiscussionOptions(ctx, pending.pendingOptionsMode, pending.pendingOptions);
+		return selected ? { content: selected.join(", "), selected } : undefined;
+	}
+	const content = await ctx.ui.input(`Reply to "${discussion.title}":`, "");
+	return content ? { content } : undefined;
+}
+
 /**
  * Every domain tool's primary interfacing point is an artifact's NAME, not its id -- id is a
  * backend implementation detail (a stable key other operations need, and titles aren't
@@ -397,7 +416,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "docs",
 		label: "Documents",
-		description: "Document domain tool. ACTIONS: create, list, show, activate, archive, reopen, link, assign_project, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. remove moves a Doc to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the doc's exact title) over `id`, and `target_name` over `target_id` for link -- both are backend implementation details, resolved from name automatically (target_name searches across every kind, since a link target can be a doc, task, rule, or skill). Prefer this over low-level papyrus_* tools for document work.",
+		description: "Document domain tool. ACTIONS: create, list, show, activate, archive, reopen, link, 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. update changes title/body/labels (at least one required) and is refused for a read-only external projection (e.g. web-spider-ingested Docs) -- capture a correction as a new linked Doc instead. remove moves a Doc to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the doc's exact title) over `id`, and `target_name` over `target_id` for link -- both are backend implementation details, resolved from name automatically (target_name searches across every kind, since a link target can be a doc, task, rule, or skill). Prefer this over low-level papyrus_* tools for document work.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -443,7 +462,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				}
 				const trashResult = await handleArtifactRemoveRestore(action, params);
 				if (trashResult) return trashResult;
-				const operations = { activate: "docs.activate", archive: "docs.archive", reopen: "docs.reopen", link: "docs.link", assign_project: "docs.assign_project" } as const;
+				const operations = { activate: "docs.activate", archive: "docs.archive", reopen: "docs.reopen", link: "docs.link", assign_project: "docs.assign_project", update: "docs.update" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown docs action: ${action}`);
 				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
@@ -457,7 +476,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "rules",
 		label: "Rules",
-		description: "Rule domain tool. ACTIONS: create, list, show, preview, enable, disable, gate, assign_project, remove, restore. project_root is optional at creation (omitted = unscoped); assign_project reassigns it later, or unscopes when project_root is omitted. Active rules inject into the agent system prompt. remove moves a Rule to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the rule's exact title) over `id`, and `task_name` over `task_id` for gate -- both are backend implementation details, resolved from name automatically.",
+		description: "Rule domain tool. ACTIONS: create, list, show, preview, enable, disable, gate, 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. Active rules inject into the agent system prompt. update changes title/body/labels (at least one required); body updates still enforce the same combined condition+action+body context-tax bound as creation, and are refused for a read-only external projection. remove moves a Rule to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the rule's exact title) over `id`, and `task_name` over `task_id` for gate -- both are backend implementation details, 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()), condition: Type.Optional(Type.String()), rule_action: Type.Optional(Type.String()),
@@ -491,7 +510,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				}
 				const trashResult = await handleArtifactRemoveRestore(action, params);
 				if (trashResult) return trashResult;
-				const operations = { show: "rules.show", enable: "rules.enable", disable: "rules.disable", gate: "rules.gate", assign_project: "rules.assign_project" } as const;
+				const operations = { show: "rules.show", enable: "rules.enable", disable: "rules.disable", gate: "rules.gate", assign_project: "rules.assign_project", update: "rules.update" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown rules action: ${action}`);
 				const artifact = await callService<Record<string, unknown>, Artifact>(operation, params);
@@ -502,10 +521,56 @@ 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",
-		description: "Papyrus Skill workflow and compatibility-template domain tool. Papyrus Skills are parameterized Task/Rule/Doc bundles, distinct from prompt-only skills. ACTIONS: create, create_template, list, show, invoke, run, enable, disable, instantiate, assign_project, remove, restore. run validates arguments and atomically creates one scoped workflow run. project_root is optional at creation (omitted = unscoped) for create/create_template; assign_project reassigns it later, or unscopes when project_root is omitted. remove moves a Skill to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the skill's exact title) over `id`, and `template_name` over `template_id` for instantiate -- both are backend implementation details, resolved from name automatically.",
+		description: "Papyrus Skill workflow and compatibility-template domain tool. Papyrus Skills are parameterized Task/Rule/Doc bundles, distinct from prompt-only skills. ACTIONS: create, create_template, list, show, invoke, run, enable, disable, instantiate, assign_project, update, remove, restore. run validates arguments and atomically creates one scoped workflow run. project_root is optional at creation (omitted = unscoped) for create/create_template; assign_project reassigns it later, or unscopes when project_root is omitted. update changes title/body/labels (at least one required) and is refused for a read-only external projection. remove moves a Skill to a time-gated trash, excluded from list/query but still directly showable, restorable via restore until the purge deadline. PREFER `name` (the skill's exact title) over `id`, and `template_name` over `template_id` for instantiate -- both are backend implementation details, 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())),
@@ -570,7 +635,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 				}
 				const trashResult = await handleArtifactRemoveRestore(action, params);
 				if (trashResult) return trashResult;
-				const operations = { show: "skills.show", enable: "skills.enable", disable: "skills.disable", instantiate: "skills.instantiate", assign_project: "skills.assign_project" } as const;
+				const operations = { show: "skills.show", enable: "skills.enable", disable: "skills.disable", instantiate: "skills.instantiate", assign_project: "skills.assign_project", update: "skills.update" } as const;
 				const operation = operations[action as keyof typeof operations];
 				if (!operation) throw new Error(`unknown skills action: ${action}`);
 				const artifact = await callService<Record<string, unknown>, Artifact>(operation, action === "instantiate" ? request : params);
@@ -584,7 +649,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "discuss",
 		label: "Discuss",
-		description: "Native Papyrus deliberation with a real lifecycle -- distinct from a one-shot ask: a Discussion persists, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. ACTIONS: open, reply, defer, resume, settle, block, unblock, show, rounds, list. open starts round 1 and optionally blocks_task_ids immediately. reply is refused once deferred or settled -- resume first. defer is explicitly non-blocking (paused, resumable); settle is terminal and archives the discussion. block/unblock manage the blocking relationship to a task independently of open. A task's completion is refused while any active Discussion blocks it. open/reply can pose a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several); reply answers a currently pending choice via selected, validated against it. PREFER `name` (the discussion's exact title) over `id`, `task_name`/`blocks_task_names` over `task_id`/`blocks_task_ids` -- all are backend implementation details, resolved from name automatically.",
+		description: "Native Papyrus deliberation with a real lifecycle -- distinct from a one-shot ask: a Discussion persists, takes multiple rounds, and can genuinely block a Task's completion until settled or deferred. ACTIONS: open, reply, defer, resume, settle, block, unblock, show, rounds, list. open starts round 1 and optionally blocks_task_ids immediately. reply is refused once deferred or settled -- resume first. defer is explicitly non-blocking (paused, resumable); settle is terminal and archives the discussion. block/unblock manage the blocking relationship to a task independently of open. A task's completion is refused while any active Discussion blocks it. open/reply can pose a structured choice via options (2-10 entries) + options_mode ('single' mutually exclusive, 'multi' allows several); reply answers a currently pending choice via selected, validated against it. Pass live:true on open or reply to get the human's answer synchronously in this same call, via an interactive prompt (the pending choice's picker if one was posed, otherwise a freeform question) -- covers a completely open question with no artifact (open with no prior discussion) and a question tied to a specific existing artifact (reply, addressed by name) alike. Only takes effect with an interactive UI available; otherwise degrades silently to the normal async round. PREFER `name` (the discussion's exact title) over `id`, `task_name`/`blocks_task_names` over `task_id`/`blocks_task_ids` -- all are backend implementation details, resolved from name automatically.",
 		parameters: Type.Object({
 			action: Type.String(),
 			id: Type.Optional(Type.String()),
@@ -606,6 +671,7 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 			options: Type.Optional(Type.Array(Type.String())),
 			options_mode: Type.Optional(Type.String()),
 			selected: Type.Optional(Type.Array(Type.String())),
+			live: Type.Optional(Type.Boolean()),
 		}),
 		renderCall(args, theme) { return renderPapyrusToolCall("Discuss", args, theme); },
 		renderResult(result, options, theme, context) { return renderPapyrusToolResult(result, options, theme, context); },
@@ -619,13 +685,19 @@ export function registerDomainTools(pi: ExtensionAPI): void {
 					{ nameKey: "task_name", idKey: "task_id", listOperation: "tasks.list", baseRequest: taskScope },
 				]);
 				await resolveNameArrayField(params, "blocks_task_names", "blocks_task_ids", "tasks.list", taskScope);
-				if (action === "open") {
-					const result = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.open", params);
-					return text(`Opened discussion ${artifactLine(result.discussion)}`, createArtifactDetails("discuss.open", result.discussion));
-				}
-				if (action === "reply") {
-					const result = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.reply", params);
-					return text(`Round ${result.rounds[0]?.roundNumber} added to "${result.discussion.title}"`, createArtifactDetails("discuss.reply", result.discussion));
+				if (action === "open" || action === "reply") {
+					const operation = action === "open" ? "discuss.open" : "discuss.reply";
+					const result = await callService<Record<string, unknown>, DiscussionAndRounds>(operation, params);
+					const fallback = action === "open"
+						? text(`Opened discussion ${artifactLine(result.discussion)}`, createArtifactDetails("discuss.open", result.discussion))
+						: text(`Round ${result.rounds[0]?.roundNumber} added to "${result.discussion.title}"`, createArtifactDetails("discuss.reply", result.discussion));
+					if (params.live !== true) return fallback;
+					const answer = await liveAnswer(ctx, result.discussion);
+					if (!answer) return fallback;
+					const answered = await callService<Record<string, unknown>, DiscussionAndRounds>("discuss.reply", {
+						id: result.discussion.id, actor: "human", content: answer.content, ...(answer.selected ? { selected: answer.selected } : {}), source: "discuss-live",
+					});
+					return text(`"${answered.discussion.title}": ${answer.content}`, createArtifactDetails("discuss.reply", answered.discussion));
 				}
 				if (action === "block" || action === "unblock") {
 					const operation = action === "block" ? "discuss.block" : "discuss.unblock";

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,10 @@ 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("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,62 @@
+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 { callService } from "./service-client.ts";
+
+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/extension/src/rules.ts

@@ -25,10 +25,17 @@ export async function showRules(ctx: ExtensionCommandContext): Promise<void> {
 		statusOrder: ["active", "deprecated"],
 		presentation: RULE_STATUS_PRESENTATION,
 		rowMeta: ruleRowMeta,
-		actions: (rule) => ["Show details", "Preview injection", "Link gated task", rule.status === "active" ? "Disable" : "Enable"],
+		actions: (rule) => ["Show details", "Edit", "Preview injection", "Link gated task", rule.status === "active" ? "Disable" : "Enable"],
 		handleAction: async (choice, rule, commandCtx) => {
 			if (choice === "Show details") await showArtifactDetails(commandCtx, rule.id, "rules.show");
-			else if (choice === "Preview injection") {
+			else if (choice === "Edit") {
+				const title = await commandCtx.ui.input("Title:", rule.title);
+				if (title === undefined) return; // canceled
+				const body = await commandCtx.ui.input("Body:", rule.body);
+				if (body === undefined) return; // canceled
+				const updated = await callService<Record<string, unknown>, Artifact>("rules.update", { id: rule.id, title, body });
+				commandCtx.ui.notify(`Updated "${updated.title}"`, "info");
+			} else if (choice === "Preview injection") {
 				const preview = await callService<Record<string, unknown>, string>("rules.preview", { id: rule.id });
 				commandCtx.ui.notify(preview, "info");
 			} else if (choice === "Link gated task") {

package/extension/src/skills.ts

@@ -76,12 +76,20 @@ export async function showSkills(ctx: ExtensionCommandContext): Promise<void> {
 		rowMeta: skillRowMeta,
 		actions: (skill) => [
 			"Show details",
+			"Edit",
 			skill.subtype === "artifact-template" ? "Use template" : skill.subtype === "workflow" ? "Run workflow" : "Invoke skill",
 			skill.status === "active" ? "Disable" : "Enable",
 		],
 		handleAction: async (choice, skill, commandCtx) => {
 			if (choice === "Show details") await showArtifactDetails(commandCtx, skill.id, "skills.show");
-			else if (choice === "Run workflow") {
+			else if (choice === "Edit") {
+				const title = await commandCtx.ui.input("Title:", skill.title);
+				if (title === undefined) return; // canceled
+				const body = await commandCtx.ui.input("Body:", skill.body);
+				if (body === undefined) return; // canceled
+				const updated = await callService<Record<string, unknown>, Artifact>("skills.update", { id: skill.id, title, body });
+				commandCtx.ui.notify(`Updated "${updated.title}"`, "info");
+			} else if (choice === "Run workflow") {
 				const source = await commandCtx.ui.input("Workflow arguments JSON:", "{}");
 				if (source === undefined) return;
 				try {

package/package.json

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

package/src/authority-registry.ts

@@ -22,7 +22,7 @@ import type { ArtifactEventContext } from "./domain/artifact-event.ts";
 import type { Artifact, ArtifactLink } from "./domain/artifact.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 
-export type ArtifactAction = "create" | "link" | "status";
+export type ArtifactAction = "create" | "link" | "status" | "update";
 
 export interface AuthorityClaim {
 	/** Module id that owns this kind/subtype/relation, e.g. "notes", "tasks". */