@danypops/papyrus 0.40.0 → 0.42.0

package/src/playbook-definition.ts

@@ -1,19 +1,22 @@
 /**
  * playbook-definition.ts — compiles a Playbook's own steps/trigger/tools/arguments, plus its
- * `contains` (nested) and `depends_on` (prerequisite) composition tree, into an in-memory
- * SkillDefinition. This is the "recycle Papyrus Skills -> Playbooks" half of the redesign:
- * rather than a second graph-materialization engine, a Playbook becomes prose that compiles
- * down to the exact blueprint shape workflow Skills already use, then hands off to
- * workflow-execution.ts's shared materializeWorkflowDefinition for the actual Task creation.
+ * `contains` (nested) and `depends_on` (prerequisite) whole-artifact composition tree, into
+ * an in-memory BlueprintDefinition. Rather than a second graph-materialization engine, a
+ * Playbook becomes a definition that compiles down to the exact Blueprint shape a
+ * workflow-definition target already uses, then hands off to workflow-execution.ts's shared
+ * materializeWorkflowDefinition for the actual artifact creation.
  *
  * One task blueprint per playbook-node root (a container, never itself gated) plus one per
  * step (chained by sequential dependsOn); `contains`-linked playbooks nest their own root
  * under the parent root and continue the parent's own step chain ("run as part of this one",
  * after the parent's own steps); `depends_on`-linked playbooks compile as independent
- * subtrees whose tails gate this node's first step ("complete this FIRST"). No SkillCallBlueprint
- * indirection is used -- everything is inlined into one flat definition, since a Playbook's
- * composition tree is fully known and owned at compile time, unlike a workflow Skill's nested
- * pipeline step (which references another SKILL by id, resolved and executed independently).
+ * subtrees whose tails gate this node's first step ("complete this FIRST"). That whole-artifact
+ * composition tree is fully known and owned at compile time and is always inlined directly
+ * (no CallBlueprint indirection). A step-level `call` (one step within a single playbook
+ * node, not the composition tree above) is the one place this compiler DOES emit a
+ * CallBlueprint -- a finer-grained, in-blueprint nested-run reference resolved and executed
+ * independently by workflow-execution.ts, exactly like a workflow-definition target's own
+ * nested pipeline step, since its target's own definition is not knowable at this compile time.
  */
 import {
 	PLAYBOOK_INVOCATION_MAX_CALL_DEPTH,
@@ -21,9 +24,9 @@ import {
 	PLAYBOOK_INVOCATION_MAX_LINKED_ARTIFACTS,
 } from "./constants.ts";
 import type { Artifact } from "./domain/artifact.ts";
-import type { SkillDefinition, SkillInputDefinition, SkillTaskBlueprint } from "./domain/skill-definition.ts";
-import { validateSkillDefinition } from "./domain/skill-definition.ts";
-import type { PlaybookArgument } from "./domain-services.ts";
+import type { CallBlueprint, BlueprintDefinition, DocBlueprint, BlueprintInputDefinition, RuleBlueprint, TaskBlueprint } from "./domain/blueprint-definition.ts";
+import { validateBlueprintDefinition } from "./domain/blueprint-definition.ts";
+import type { PlaybookArgument, PlaybookStep } from "./domain-services.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 
 /** A non-composing edge touching a playbook node, to be mirrored onto that node's generated root task once real task ids exist -- e.g. a Rule `gates` this playbook, or this playbook `references`/`documents` a Doc. Direction is preserved exactly: `from`/`to` name whichever side is NOT the playbook, and `ownerIsFrom` says which side the playbook (now the generated root task) occupies. */
@@ -36,7 +39,7 @@ export interface PlaybookExternalLink {
 }
 
 export interface CompiledPlaybook {
-	definition: SkillDefinition;
+	definition: BlueprintDefinition;
 	/** The very first real leaf task in the whole tree's reading order -- what a caller should focus once materialized. */
 	entryRef: string;
 	externalLinks: PlaybookExternalLink[];
@@ -56,8 +59,8 @@ function requirePlaybook(artifacts: ArtifactStore, id: string): Artifact {
 	return playbook;
 }
 
-function stepsOf(playbook: Artifact): string[] {
-	return Array.isArray(playbook.extra["steps"]) ? playbook.extra["steps"].filter((step): step is string => typeof step === "string") : [];
+function stepsOf(playbook: Artifact): PlaybookStep[] {
+	return Array.isArray(playbook.extra["steps"]) ? (playbook.extra["steps"] as PlaybookStep[]) : [];
 }
 
 function toolsOf(playbook: Artifact): string[] {
@@ -87,8 +90,11 @@ function stepTitle(step: string): string {
 }
 
 interface CompileContext {
-	tasks: SkillTaskBlueprint[];
-	inputs: Record<string, SkillInputDefinition>;
+	docs: DocBlueprint[];
+	rules: RuleBlueprint[];
+	tasks: TaskBlueprint[];
+	skills: CallBlueprint[];
+	inputs: Record<string, BlueprintInputDefinition>;
 	externalLinks: PlaybookExternalLink[];
 	refCounter: { n: number };
 }
@@ -101,9 +107,18 @@ interface CompileNodeResult {
 	tailRef: string;
 }
 
-function mergeArgument(inputs: Record<string, SkillInputDefinition>, argument: PlaybookArgument): void {
+/** A composition tree can declare the same argument name from more than one node (e.g. two prerequisite playbooks both need a `target`); required OR-accumulates the same way it always did, but the type must agree everywhere -- silently picking one node's type over another's would compile a definition whose placeholder substitution disagrees with what one of the two authors actually declared. */
+function mergeArgument(inputs: Record<string, BlueprintInputDefinition>, argument: PlaybookArgument): void {
 	const existing = inputs[argument.name];
-	inputs[argument.name] = { type: "string", required: (existing?.required ?? false) || argument.required };
+	if (existing && existing.type !== argument.type) {
+		throw new Error(`playbook composition declares conflicting types for argument "${argument.name}" (${existing.type} vs ${argument.type})`);
+	}
+	inputs[argument.name] = {
+		type: argument.type,
+		required: (existing?.required ?? false) || argument.required,
+		...(argument.enum ? { enum: argument.enum } : {}),
+		...(argument.default !== undefined ? { default: argument.default } : {}),
+	};
 }
 
 function compileNode(
@@ -123,7 +138,7 @@ function compileNode(
 	for (const argument of argumentsOf(playbook)) mergeArgument(ctx.inputs, argument);
 
 	const rootRef = `pb${ctx.refCounter.n++}`;
-	const rootBlueprint: SkillTaskBlueprint = { ref: rootRef, title: playbook.title, body: rootTaskBody(playbook), ...(parentRef ? { parent: parentRef } : {}) };
+	const rootBlueprint: TaskBlueprint = { ref: rootRef, title: playbook.title, body: rootTaskBody(playbook), ...(parentRef ? { parent: parentRef } : {}) };
 	ctx.tasks.push(rootBlueprint);
 	if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS) throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
 
@@ -148,15 +163,46 @@ function compileNode(
 		if (headRef === undefined) headRef = result.headRef;
 	}
 
+	// Doc/rule steps are not gated tasks (DocBlueprint/RuleBlueprint have no dependsOn/parent of
+	// their own -- workflow-execution.ts always creates them unconditionally alongside the run)
+	// -- they do not touch cursorPrecedingRefs/headRef/tailRef at all. A task or call step DOES
+	// occupy a position in the sequential chain, exactly as a plain-string step always did.
 	let cursorPrecedingRefs = [...incomingPrecedingRefs, ...prerequisiteTailRefs];
 	let tailRef = rootRef;
 	for (const [index, step] of stepsOf(playbook).entries()) {
-		const stepRef = `${rootRef}-s${index}`;
-		ctx.tasks.push({ ref: stepRef, title: stepTitle(step), body: step, parent: rootRef, dependsOn: cursorPrecedingRefs });
-		if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS) throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
-		if (headRef === undefined) headRef = stepRef;
-		cursorPrecedingRefs = [stepRef];
-		tailRef = stepRef;
+		if (typeof step === "string" || step.kind === "task") {
+			const body = typeof step === "string" ? step : step.body;
+			const title = typeof step === "string" ? stepTitle(step) : (step.title ?? stepTitle(body));
+			const stepRef = `${rootRef}-s${index}`;
+			ctx.tasks.push({ ref: stepRef, title, body, parent: rootRef, dependsOn: cursorPrecedingRefs });
+			if (ctx.tasks.length > PLAYBOOK_INVOCATION_MAX_CREATED_TASKS) throw new Error(`playbook invocation exceeds ${PLAYBOOK_INVOCATION_MAX_CREATED_TASKS} tasks`);
+			if (headRef === undefined) headRef = stepRef;
+			cursorPrecedingRefs = [stepRef];
+			tailRef = stepRef;
+		} else if (step.kind === "doc") {
+			const stepRef = `${rootRef}-d${index}`;
+			ctx.docs.push({ ref: stepRef, title: step.title, ...(step.body ? { body: step.body } : {}), ...(step.subtype ? { subtype: step.subtype } : {}), ...(step.labels ? { labels: step.labels } : {}) });
+		} else if (step.kind === "rule") {
+			const stepRef = `${rootRef}-r${index}`;
+			ctx.rules.push({
+				ref: stepRef,
+				title: step.title,
+				...(step.body ? { body: step.body } : {}),
+				...(step.condition ? { condition: step.condition } : {}),
+				...(step.action ? { action: step.action } : {}),
+				...(step.severity ? { severity: step.severity } : {}),
+				...(step.labels ? { labels: step.labels } : {}),
+			});
+		} else {
+			// kind === "call": nests another Playbook's (or a workflow-definition target's) run as
+			// a pipeline step -- shares the same dependsOn chain as a task step, resolved
+			// polymorphically at execution time by workflow-execution.ts based on the target's kind.
+			const stepRef = `${rootRef}-c${index}`;
+			ctx.skills.push({ ref: stepRef, title: step.title, targetId: step.playbookId, ...(step.arguments ? { arguments: step.arguments } : {}), parent: rootRef, dependsOn: cursorPrecedingRefs });
+			if (headRef === undefined) headRef = stepRef;
+			cursorPrecedingRefs = [stepRef];
+			tailRef = stepRef;
+		}
 	}
 
 	for (const nestedId of nestedIds) {
@@ -172,12 +218,12 @@ function compileNode(
 
 /** Pure and read-only: creates no artifacts. Cycle/depth-bounded exactly like playbookInvocation's own traversal, but a composition cycle here is a hard error (real Tasks would be created, unlike a text render degrading to a marker). */
 export function compilePlaybookDefinition(artifacts: ArtifactStore, playbookId: string): CompiledPlaybook {
-	const ctx: CompileContext = { tasks: [], inputs: {}, externalLinks: [], refCounter: { n: 0 } };
+	const ctx: CompileContext = { docs: [], rules: [], tasks: [], skills: [], inputs: {}, externalLinks: [], refCounter: { n: 0 } };
 	const { headRef } = compileNode(artifacts, playbookId, ctx, new Set(), 0, undefined, []);
-	const definition = validateSkillDefinition({
+	const definition = validateBlueprintDefinition({
 		version: 1,
 		inputs: ctx.inputs,
-		blueprints: { docs: [], rules: [], tasks: ctx.tasks, skills: [] },
+		blueprints: { docs: ctx.docs, rules: ctx.rules, tasks: ctx.tasks, skills: ctx.skills },
 		links: [],
 	});
 	return { definition, entryRef: headRef, externalLinks: ctx.externalLinks };

package/src/playbook-execution.ts

@@ -1,17 +1,17 @@
 /**
  * playbook-execution.ts — playbooks.invoke's real implementation: compile the Playbook's
- * composition tree (playbook-definition.ts) into a SkillDefinition, materialize it through
+ * composition tree (playbook-definition.ts) into a BlueprintDefinition, materialize it through
  * workflow-execution.ts's shared engine, mirror any pre-existing Rule/Doc links onto the
  * generated root task, and report which task to focus. No text is rendered here -- every
  * step is its own Task, and only the currently-focused one is ever surfaced to an agent
  * (via the existing Task Focus system-prompt pointer), which is what actually avoids the
  * old text-dump problem: one page at a time, not the whole book at once.
  */
-import type { SkillArgumentValue } from "./domain/skill-definition.ts";
+import type { BlueprintArgumentValue } from "./domain/blueprint-definition.ts";
 import { compilePlaybookDefinition } from "./playbook-definition.ts";
 import type { ArtifactStore } from "./ports/artifact-store.ts";
 import { requireAtomicArtifactStore } from "./ports/atomic-artifact-store.ts";
-import { materializeWorkflowDefinition, type WorkflowRunHistory } from "./workflow-execution.ts";
+import { applyPlaybookExternalLinks, materializeWorkflowDefinition, resolveRefToTaskId, type WorkflowRunHistory } from "./workflow-execution.ts";
 import type { TaskExecutionPlan } from "./task-execution.ts";
 
 export interface InvokePlaybookInput {
@@ -22,7 +22,7 @@ export interface InvokePlaybookInput {
 export interface PlaybookInvocationResult {
 	playbookId: string;
 	runId: string;
-	arguments: Record<string, SkillArgumentValue>;
+	arguments: Record<string, BlueprintArgumentValue>;
 	created: { docs: string[]; rules: string[]; tasks: string[] };
 	rootTaskIds: string[];
 	/** The one task to focus -- the first real leaf in the whole composition tree's reading order (deepest prerequisite's own first step, or this playbook's own first step, or its first nested child's, or the container task itself when there is nothing else). */
@@ -36,24 +36,12 @@ export interface PlaybookMissingArguments {
 	missingArguments: string[];
 }
 
-function missingRequiredInputs(inputs: Record<string, { required?: boolean; default?: SkillArgumentValue }>, provided: Record<string, unknown>): string[] {
+function missingRequiredInputs(inputs: Record<string, { required?: boolean; default?: BlueprintArgumentValue }>, provided: Record<string, unknown>): string[] {
 	return Object.entries(inputs)
 		.filter(([name, input]) => input.required && provided[name] === undefined && input.default === undefined)
 		.map(([name]) => name);
 }
 
-/** Reads each newly-created task's own playbookRun.ref tag back off the store -- avoids threading an extra ref-to-id map out of materializeWorkflowDefinition's existing, already-stable return shape. */
-function resolveRefToTaskId(artifacts: ArtifactStore, taskIds: string[]): Map<string, string> {
-	const map = new Map<string, string>();
-	for (const taskId of taskIds) {
-		const lineage = artifacts.get(taskId)?.extra["playbookRun"];
-		if (typeof lineage !== "object" || lineage === null || Array.isArray(lineage)) continue;
-		const ref = (lineage as Record<string, unknown>)["ref"];
-		if (typeof ref === "string") map.set(ref, taskId);
-	}
-	return map;
-}
-
 export function invokePlaybook(
 	artifacts: ArtifactStore,
 	playbookId: string,
@@ -75,13 +63,8 @@ export function invokePlaybook(
 			new Set(),
 			0,
 		);
-		const refToTaskId = resolveRefToTaskId(artifacts, result.created.tasks);
-		for (const link of compiled.externalLinks) {
-			const taskId = refToTaskId.get(link.rootRef);
-			if (!taskId) continue; // defensive -- every rootRef this compiler emits is always materialized
-			if (link.ownerIsFrom) artifacts.link({ from: taskId, relation: link.relation, to: link.otherArtifactId });
-			else artifacts.link({ from: link.otherArtifactId, relation: link.relation, to: taskId });
-		}
+		const refToTaskId = resolveRefToTaskId(artifacts, result.created.tasks, "playbookRun");
+		applyPlaybookExternalLinks(artifacts, compiled.externalLinks, refToTaskId);
 		return {
 			playbookId,
 			runId: result.runId,

package/src/ports/artifact-scope-store.ts

@@ -1,7 +1,7 @@
 import type { TaskScopeSource } from "../domain/task-scope.ts";
 
 /**
- * Project scoping for Docs/Rules/Skills, mirroring TaskScopeStore's shape (task_scopes) but
+ * Project scoping for Docs/Rules/Playbooks, mirroring TaskScopeStore's shape (task_scopes) but
  * kept as its own table/port rather than folding non-Task kinds into Task-named
  * infrastructure. TaskScopeSource ("cwd" | "explicit" | "unscoped") is already kind-agnostic
  * and reused as-is -- no reason to redefine the same three values under a new name.

package/src/service.ts

@@ -39,7 +39,6 @@ import { graphProjectionOperations, GRAPH_PROJECTION_OPERATION_NAMES } from "./m
 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 { instantiateSkillOrTemplate, 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";
@@ -51,9 +50,8 @@ import { SQLiteDiscussionRoundStore } from "./adapters/sqlite-discussion-round-s
  * Operations with no registered module: the generic, cross-cutting kernel surface
  * (artifact create/query/show, graph link/unlink/tree/status/history, gates run --
  * no domain owns creation/linking/traversal for every kind, the same way system.migrate
- * has no owning module) and two permanent composition-root exceptions (rules.injectable
- * needs tasks.active(); skills.instantiate branches into tasks.create()) -- see
- * src/modules/rules.ts and src/modules/skills.ts's module comments. Discourse's own
+ * has no owning module) and one permanent composition-root exception (rules.injectable
+ * needs tasks.active()) -- see src/modules/rules.ts's own module comment. Discourse's own
  * Papyrus-embedded storage (discourse.store) was removed entirely -- zero real callers
  * were ever confirmed against it; Discourse's real home is the standalone
  * @danypops/discourse package plus host adapters.
@@ -62,7 +60,7 @@ const COMPOSITION_ROOT_OPERATION_NAMES = [
 	"system.migrate", "artifact.create", "artifact.query", "artifact.show",
 	"artifact.remove", "artifact.remove_subtree", "artifact.restore", "artifact.trash_status", "artifact.trash_list",
 	"graph.link", "graph.unlink", "graph.tree", "graph.status", "graph.history", "gates.run",
-	"rules.injectable", "skills.instantiate",
+	"rules.injectable",
 ] as const;
 
 /**
@@ -80,7 +78,6 @@ export const EXPECTED_OPERATION_NAMES = [
 	...DOCS_OPERATION_NAMES,
 	...NOTES_OPERATION_NAMES,
 	...RULES_OPERATION_NAMES,
-	...SKILLS_OPERATION_NAMES,
 	...PLAYBOOKS_OPERATION_NAMES,
 	...GRAPH_PROJECTION_OPERATION_NAMES,
 	...LOGS_OPERATION_NAMES,
@@ -170,11 +167,11 @@ const tasksAuthorityClaim: AuthorityClaim = {
 
 /**
  * The same status-bypass protection Tasks and Notes already have, extended to every other kind
- * with its own validated transition set (Doc's draft/active/archived, Rule/Skill/Playbook's
+ * with its own validated transition set (Doc's draft/active/archived, Rule/Playbook's
  * active/deprecated) -- graph.status previously let a caller jump straight to any status string,
  * skipping e.g. Doc's draft-must-go-through-active-before-archived rule entirely.
  */
-function lifecycleAuthorityClaim(owner: "docs" | "rules" | "skills" | "playbooks", kind: string): AuthorityClaim {
+function lifecycleAuthorityClaim(owner: "docs" | "rules" | "playbooks", kind: string): AuthorityClaim {
 	return {
 		owner,
 		matchesArtifact: (candidateKind, subtype) => candidateKind === kind && !(kind === "doc" && subtype === NOTE_SUBTYPE),
@@ -190,7 +187,6 @@ export function createAuthorityRegistry(): AuthorityRegistry {
 		tasksAuthorityClaim,
 		lifecycleAuthorityClaim("docs", "doc"),
 		lifecycleAuthorityClaim("rules", "rule"),
-		lifecycleAuthorityClaim("skills", "skill"),
 		lifecycleAuthorityClaim("playbooks", "playbook"),
 	]);
 	return authority;
@@ -408,16 +404,6 @@ function handlers(
 		"rules.gate": forwardToModule("rules.gate"),
 		"rules.assign_project": forwardToModule("rules.assign_project"),
 		"rules.update": forwardToModule("rules.update"),
-		"skills.create": forwardToModule("skills.create"),
-		"skills.create_template": forwardToModule("skills.create_template"),
-		"skills.list": forwardToModule("skills.list"),
-		"skills.show": forwardToModule("skills.show"),
-		"skills.invoke": forwardToModule("skills.invoke"),
-		"skills.run": forwardToModule("skills.run"),
-		"skills.enable": forwardToModule("skills.enable"),
-		"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"),
@@ -431,7 +417,6 @@ function handlers(
 		"playbooks.uncontain": forwardToModule("playbooks.uncontain"),
 		"playbooks.depend": forwardToModule("playbooks.depend"),
 		"playbooks.undepend": forwardToModule("playbooks.undepend"),
-		"skills.instantiate": (input) => instantiateSkillOrTemplate({ artifacts, tasks, authority }, input, eventContextFor(input, "template-instantiation")),
 		"graph_projection.apply": forwardToModule("graph_projection.apply"),
 		"graph_projection.checkpoint": forwardToModule("graph_projection.checkpoint"),
 		"logs.append": forwardToModule("logs.append"),
@@ -477,7 +462,6 @@ export function createPapyrusService(path: string): PapyrusService {
 	moduleRegistry.registerAll(tasksOperations(tasks, artifacts, sessionIdentity));
 	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority));
 	moduleRegistry.registerAll(rulesOperations(artifacts, artifactScopes));
-	moduleRegistry.registerAll(skillsOperations({ artifacts, events, scopes, artifactScopes, authority }));
 	moduleRegistry.registerAll(playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity }));
 	moduleRegistry.registerAll(graphProjectionOperations(artifacts, projections, authority));
 	const registry = handlers(artifacts, gates, tasks, notes, events, scopes, () => migrateDb(db), moduleRegistry, authority);

package/src/task-service.ts

@@ -462,7 +462,7 @@ export class Tasks {
 
 	/**
 	 * Cancels a task and every task in its containment subtree (`contains` edges, transitively) --
-	 * a whole materialized playbook/skill run can be torn down in one call instead of enumerating
+	 * a whole materialized playbook run can be torn down in one call instead of enumerating
 	 * every task id by hand. A task already in a terminal state (done/canceled) is skipped, not
 	 * treated as an error, matching how a mixed-status subtree is the normal case (some steps
 	 * genuinely finished before the rest needed to be abandoned). Does not follow `depends_on` --

package/src/vehicle/artifact-trash-vehicle.ts

@@ -55,7 +55,7 @@ export function registerArtifactTrashOperations(registry: VehicleRegistry, artif
 
 	define(
 		"show",
-		"Shows any artifact (doc, task, rule, skill, playbook) by id, regardless of kind.",
+		"Shows any artifact (doc, task, rule, playbook) by id, regardless of kind.",
 		"read",
 		{ id: stringProp, tree: { type: "boolean" } as unknown as { type: string }, depth: numberProp, max_nodes: numberProp },
 		["id"],

package/src/vehicle/artifact-vehicle-shared.ts

@@ -98,12 +98,10 @@ export interface WorkflowRunNarrativeInput {
 }
 
 /**
- * Shared between skills.run and playbooks.invoke's Vehicle operations -- both produce the
- * same shaped narrative (ready roots, context docs, scoped rules, an execution tree), only
- * the headline and whether an "entry task focused" line is present differ. Builds the model-
- * facing `content` text directly, so the model reads a summary instead of the raw execution
- * DAG -- the same shape pi-papyrus's own hand-rolled skills/playbooks tools built client-side,
- * now built once here where the run result is actually produced.
+ * Builds the model-facing `content` text for a workflow run result (ready roots, context docs,
+ * scoped rules, an execution tree) directly, so the model reads a summary instead of the raw
+ * execution DAG -- the same shape pi-papyrus's own hand-rolled playbooks tool built
+ * client-side, now built once here where the run result is actually produced.
  */
 export function buildWorkflowRunContent(artifacts: ArtifactStore, headline: string, input: WorkflowRunNarrativeInput, extraLines: readonly string[] = []): VehicleContentBlock {
 	const nodeById = new Map(input.execution.nodes.map((node) => [node.id, node]));

package/src/vehicle/docs-vehicle.ts

@@ -25,7 +25,7 @@ function resolveDocId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, proj
 	);
 }
 
-/** Cross-kind resolution for a link target -- can be a doc, task, rule, or skill. Unscoped, matching the exact behavior of the artifact.query-backed resolution it replaces. */
+/** Cross-kind resolution for a link target -- can be a doc, task, rule, or playbook. Unscoped, matching the exact behavior of the artifact.query-backed resolution it replaces. */
 function resolveTargetId(artifacts: ArtifactStore, id: unknown, name: unknown): string {
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) throw new Error("target_id or target_name is required");
@@ -114,7 +114,7 @@ export function registerDocsVehicleOperations(registry: VehicleRegistry, artifac
 
 	define(
 		"link",
-		"Links a Doc to another artifact via a typed relation. Prefer target_name over target_id -- resolved server-side, searching every kind since a link target can be a doc, task, rule, or skill.",
+		"Links a Doc to another artifact via a typed relation. Prefer target_name over target_id -- resolved server-side, searching every kind since a link target can be a doc, task, rule, or playbook.",
 		"local-write",
 		{ id: stringProp, name: stringProp, relation: { type: "string", enum: ["references", "documents", "supersedes", "relates_to", "contains", "part_of"] }, target_id: stringProp, target_name: stringProp, project_root: stringProp },
 		["relation"],

package/src/vehicle/notes-vehicle.ts

@@ -25,7 +25,7 @@ function resolveNoteId(notes: Notes, projectRoot: string, id: unknown, name: unk
 	return resolveArtifactIdWidened(name, () => notes.list({ projectRoot, text: name }));
 }
 
-/** Cross-kind equivalent for a promotion target -- a target can be a task, doc, rule, or skill, not just a note. Unscoped by project, matching the exact behavior of the artifact.query-backed resolution it replaces. */
+/** Cross-kind equivalent for a promotion target -- a target can be a task, doc, rule, or playbook, not just a note. Unscoped by project, matching the exact behavior of the artifact.query-backed resolution it replaces. */
 function resolveArtifactId(artifacts: ArtifactStore, id: unknown, name: unknown): string {
 	if (typeof id === "string" && id.length > 0) return id;
 	if (typeof name !== "string" || name.length === 0) throw new Error("target_id or target_name is required");
@@ -113,7 +113,7 @@ export function registerNotesVehicleOperations(registry: VehicleRegistry, notes:
 
 	define(
 		"promote",
-		"Links a note to the Task, Doc, Rule, or Skill it was promoted into, then archives it.",
+		"Links a note to the Task, Doc, Rule, or Playbook it was promoted into, then archives it.",
 		"local-write",
 		{
 			id: stringProp,

package/src/vehicle/papyrus-vehicle.ts

@@ -1,12 +1,11 @@
 /**
  * Composition root for every domain projected onto Vehicle -- one VehicleRegistry,
  * one HTTP mount (see service.ts's createApp). Operation names are already globally
- * unique via their own dotted prefix (notes.*, rules.*, docs.*, skills.*, playbooks.*,
- * artifact.*), so merging costs nothing and avoids a separate registry/mount/client
- * per domain.
+ * unique via their own dotted prefix (notes.*, rules.*, docs.*, playbooks.*, artifact.*),
+ * so merging costs nothing and avoids a separate registry/mount/client per domain.
  *
- * discuss and tasks still register via pi-papyrus's own pi.registerTool() in
- * domain-tools.ts, not here -- see the papyrus Vehicle migration task for why.
+ * discuss still registers via pi-papyrus's own pi.registerTool() in domain-tools.ts,
+ * not here -- see the papyrus Vehicle migration task for why.
  */
 import { VehicleRegistry } from "@danypops/vehicle-server";
 import type { AuthorityRegistry } from "../authority-registry.ts";
@@ -23,7 +22,7 @@ import { registerDocsVehicleOperations } from "./docs-vehicle.ts";
 import { registerNotesVehicleOperations } from "./notes-vehicle.ts";
 import { registerPlaybooksVehicleOperations } from "./playbooks-vehicle.ts";
 import { registerRulesVehicleOperations } from "./rules-vehicle.ts";
-import { registerSkillsVehicleOperations } from "./skills-vehicle.ts";
+import { registerTasksVehicleOperations } from "./tasks-vehicle.ts";
 
 export interface PapyrusVehicleDeps {
 	artifacts: ArtifactStore & ArtifactTrashStore;
@@ -41,8 +40,8 @@ export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleR
 	registerNotesVehicleOperations(registry, deps.notes, deps.artifacts);
 	registerRulesVehicleOperations(registry, deps.artifacts, deps.scopes);
 	registerDocsVehicleOperations(registry, deps.artifacts, deps.scopes, deps.authority);
-	registerSkillsVehicleOperations(registry, { artifacts: deps.artifacts, events: deps.events, scopes: deps.taskScopes, artifactScopes: deps.scopes, authority: deps.authority, tasks: deps.tasks });
 	registerPlaybooksVehicleOperations(registry, { artifacts: deps.artifacts, events: deps.events, scopes: deps.taskScopes, artifactScopes: deps.scopes, tasks: deps.tasks, sessionIdentity: deps.sessionIdentity });
+	registerTasksVehicleOperations(registry, { tasks: deps.tasks, artifacts: deps.artifacts, sessionIdentity: deps.sessionIdentity });
 	registerArtifactTrashOperations(registry, deps.artifacts);
 	return registry;
 }

package/src/vehicle/playbooks-vehicle.ts

@@ -80,7 +80,7 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 
 	define(
 		"create",
-		"Creates a Playbook -- prose: a trigger and an ordered list of steps. `arguments` declares named inputs: [{name, description?, required?}] (required defaults true), referenced in step text as {{name}}. project_root is optional (omitted = unscoped).",
+		"Creates a Playbook -- a trigger and an ordered list of steps. Each step is either a plain prose string (a task), or a structured object: {kind:'doc',title,body?,subtype?,labels?} creates a Doc, {kind:'rule',title,body?,condition?,action?,severity?,labels?} creates a Rule, {kind:'call',title,playbookId,arguments?} nests another Playbook's own run as a pipeline step gated in the same sequence, {kind:'task',title?,body} is an explicit task step. `arguments` declares named inputs: [{name, description?, required?, type?('string'|'number'|'boolean', default 'string'), enum?, default?}] (required defaults true), referenced in step text/call arguments as {{name}}. project_root is optional (omitted = unscoped).",
 		"local-write",
 		{ title: stringProp, body: stringProp, trigger: stringProp, steps: { type: "array" }, tools: { type: "array" }, arguments: { type: "array" }, labels: { type: "array" }, extra: { type: "object" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
 		["title"],