@danypops/papyrus 0.39.0 → 0.40.0

package/README.md

@@ -80,7 +80,7 @@ papyrus skills run <skill-id> \
   --json
 ```
 
-The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it through the `skills` tool's `instantiate` action with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
+The existing `artifact-template` skill subtype remains a compatibility mechanism for one-artifact templates with metadata `{targetKind, defaults, required}`. Instantiate it via the `skills.instantiate` operation with `template_id`; defaults merge recursively, explicit arrays replace defaults, required paths such as `extra.owner` are validated, and target-kind mismatches are rejected.
 
 ### Removing an artifact
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],
@@ -34,7 +34,7 @@
   },
   "files": ["src", "README.md"],
   "dependencies": {
-    "@danypops/vehicle-core": "^0.1.1",
+    "@danypops/vehicle-core": "^0.2.0",
     "@danypops/vehicle-client": "^0.1.1",
     "@danypops/vehicle-server": "^0.3.2"
   }

package/src/modules/skills.ts

@@ -17,12 +17,15 @@
  * extraction.
  */
 import type { AuthorityRegistry } from "../authority-registry.ts";
-import { assignSkillProject, createArtifactTemplate, createSkill, listSkills, showSkill, skillInvocation, transitionSkill, updateSkill } from "../domain-services.ts";
+import type { Artifact, CreateArtifactInput } from "../domain/artifact.ts";
+import type { ArtifactEventContext } from "../domain/artifact-event.ts";
+import { assignSkillProject, createArtifactTemplate, createSkill, instantiateTemplate, listSkills, showSkill, skillInvocation, transitionSkill, updateSkill } 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";
 import type { TaskEventStore } from "../ports/task-event-store.ts";
 import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { Tasks, TaskStatus } from "../task-service.ts";
 import { instantiateSkillWorkflow } from "../workflow-execution.ts";
 
 const MODULE_ID = "skills";
@@ -76,6 +79,45 @@ export interface SkillsModuleDeps {
 	authority: AuthorityRegistry;
 }
 
+function normalizeCreateInput(input: OperationInput): CreateArtifactInput {
+	const { template_id, ...rest } = input;
+	return { ...rest, templateId: typeof template_id === "string" ? template_id : undefined } as CreateArtifactInput;
+}
+
+/**
+ * skills.instantiate's own branching logic (compatibility-template creation vs. a
+ * task-target template's tasks.create() call) -- shared between service.ts's raw RPC
+ * forwarder and skills-vehicle.ts's Vehicle operation, the two real callers, instead
+ * of reimplemented in each. Takes `tasks: Tasks` directly rather than through
+ * SkillsModuleDeps: a genuine cross-module dependency, the same category as
+ * rules.injectable and the module comment's own reason skills.instantiate isn't
+ * registered as an operation here.
+ */
+export interface InstantiateSkillDeps {
+	artifacts: ArtifactStore;
+	tasks: Tasks;
+	authority: AuthorityRegistry;
+}
+
+export function instantiateSkillOrTemplate(deps: InstantiateSkillDeps, input: OperationInput, context?: ArtifactEventContext): Artifact {
+	const templateId = string(input, "template_id");
+	const template = deps.artifacts.get(templateId);
+	// Note ownership for a non-task template target is enforced inside instantiateTemplate's
+	// own rejectsNoteTemplate for the non-task branch below -- nothing else currently claims
+	// an unresolved (pre-template-resolution) kind, so there is no check to perform here.
+	if (template?.extra["targetKind"] !== "task") return instantiateTemplate(deps.artifacts, templateId, normalizeCreateInput(input), deps.authority, context);
+	return deps.tasks.create({
+		title: optionalString(input, "title") as string,
+		body: optionalString(input, "body"),
+		status: optionalString(input, "status") as TaskStatus | undefined,
+		labels: input["labels"] as string[] | undefined,
+		extra: input["extra"] as Record<string, unknown> | undefined,
+		templateId,
+		projectRoot: string(input, "project_root"),
+		projectSource: "cwd",
+	}, context);
+}
+
 /** Registers every skills.* operation except skills.instantiate (see module comment). Behavior is unchanged from the prior inline handlers in src/service.ts. */
 /** 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. skills.instantiate is deliberately absent -- see the module comment above. */
 export const SKILLS_OPERATION_NAMES = [

package/src/service.ts

@@ -24,7 +24,6 @@ import type { TaskEventStore } from "./ports/task-event-store.ts";
 import type { TaskScopeStore } from "./ports/task-scope-store.ts";
 import { Tasks, type TaskStatus } from "./task-service.ts";
 import {
-	instantiateTemplate,
 	listInjectableRules,
 } from "./domain-services.ts";
 import { Notes, NOTE_SUBTYPE } from "./note-service.ts";
@@ -40,7 +39,7 @@ 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 { skillsOperations, SKILLS_OPERATION_NAMES } from "./modules/skills.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";
@@ -432,24 +431,7 @@ function handlers(
 		"playbooks.uncontain": forwardToModule("playbooks.uncontain"),
 		"playbooks.depend": forwardToModule("playbooks.depend"),
 		"playbooks.undepend": forwardToModule("playbooks.undepend"),
-		"skills.instantiate": (input) => {
-			const templateId = string(input, "template_id");
-			const template = artifacts.get(templateId);
-			// Note ownership for a non-task template target is enforced inside instantiateTemplate's
-			// own rejectsNoteTemplate for the non-task branch below -- nothing else currently claims
-			// an unresolved (pre-template-resolution) kind, so there is no check to perform here.
-			if (template?.extra["targetKind"] !== "task") return instantiateTemplate(artifacts, templateId, normalizeCreateInput(input), authority, eventContext(input));
-			return tasks.create({
-				title: optionalString(input, "title") as string,
-				body: optionalString(input, "body"),
-				status: optionalString(input, "status") as TaskStatus | undefined,
-				labels: input["labels"] as string[] | undefined,
-				extra: input["extra"] as Record<string, unknown> | undefined,
-				templateId,
-				projectRoot: string(input, "project_root"),
-				projectSource: "cwd",
-			}, eventContextFor(input, "template-instantiation"));
-		},
+		"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"),
@@ -486,7 +468,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	const sessionIdentity = new SessionIdentity(new SQLiteSessionIdentityStore(db));
 	const discussions = new Discussions(artifacts, new SQLiteDiscussionRoundStore(db));
 	const authority = createAuthorityRegistry();
-	const vehicle = createPapyrusVehicleRegistry({ artifacts, scopes: artifactScopes, authority, notes });
+	const vehicle = createPapyrusVehicleRegistry({ artifacts, scopes: artifactScopes, authority, notes, events, taskScopes: scopes, tasks, sessionIdentity });
 	const moduleRegistry = new OperationRegistry();
 	moduleRegistry.registerAll(notesOperations(notes));
 	moduleRegistry.registerAll(logsOperations(logs));

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

@@ -3,8 +3,10 @@
  * VehicleRegistry projection (notes-vehicle.ts, rules-vehicle.ts, docs-vehicle.ts,
  * artifact-trash-vehicle.ts).
  */
-import { defineVehicleSchema, type VehicleSchemaCodec } from "@danypops/vehicle-core";
+import { defineVehicleSchema, type VehicleSchemaCodec, type VehicleContentBlock } from "@danypops/vehicle-core";
 import type { Artifact } from "../domain/artifact.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { TaskExecutionPlan } from "../task-execution.ts";
 
 /**
  * VehicleRegistry only ever calls a schema's own safeParse -- jsonSchema is
@@ -42,6 +44,17 @@ export const passthroughOutput: VehicleSchemaCodec<unknown> = defineVehicleSchem
 export const stringProp = { type: "string" } as const;
 export const numberProp = { type: "number" } as const;
 
+/** A known LLM tool-calling quirk: a nested-object field arrives JSON-stringified rather than as a real object. Mutates input[key] in place when it's a string, leaves it untouched otherwise. */
+export function normalizeJsonEncodedField(input: Record<string, unknown>, key: string): void {
+	const value = input[key];
+	if (typeof value !== "string") return;
+	try {
+		input[key] = JSON.parse(value);
+	} catch {
+		throw new Error(`${key} must be valid JSON`);
+	}
+}
+
 /** Exact match semantics as the Pi-extension helper this replaces (domain-tools.ts's matchArtifactByName) -- case-insensitive exact title match, refuses to guess between ambiguous matches. */
 export function matchArtifactByName(candidates: readonly Artifact[], name: string): string {
 	const needle = name.trim().toLowerCase();
@@ -67,3 +80,47 @@ export function resolveArtifactIdWidened(name: string, fetchCandidates: () => re
 		return matchArtifactByName(fetchWidened(), name);
 	}
 }
+
+/** Synchronous equivalent of pi-papyrus's own artifactLabelsById -- server-side, a direct ArtifactStore.get() replaces the extra RPC round-trip that helper needed client-side. Disambiguates same-titled artifacts by appending their id. */
+export function labelsById(artifacts: ArtifactStore, ids: readonly string[]): Map<string, string> {
+	const uniqueIds = [...new Set(ids)];
+	const resolved = uniqueIds.map((id) => artifacts.get(id)).filter((artifact): artifact is Artifact => artifact !== null);
+	const titleCounts = new Map<string, number>();
+	for (const artifact of resolved) titleCounts.set(artifact.title, (titleCounts.get(artifact.title) ?? 0) + 1);
+	return new Map(resolved.map((artifact) => [artifact.id, (titleCounts.get(artifact.title) ?? 0) > 1 ? `${artifact.title} (${artifact.id})` : artifact.title]));
+}
+
+export interface WorkflowRunNarrativeInput {
+	runId: string;
+	created: { docs: readonly string[]; rules: readonly string[]; tasks: readonly string[] };
+	rootTaskIds: readonly string[];
+	execution: TaskExecutionPlan;
+}
+
+/**
+ * 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.
+ */
+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]));
+	const rootLabels = input.rootTaskIds.map((id) => nodeById.get(id)?.title ?? "unknown task");
+	const createdLabels = labelsById(artifacts, [...input.created.docs, ...input.created.rules]);
+	const titleCounts = new Map<string, number>();
+	for (const node of input.execution.nodes) titleCounts.set(node.title, (titleCounts.get(node.title) ?? 0) + 1);
+	const executionLines = input.execution.nodes
+		.map((node) => ((titleCounts.get(node.title) ?? 0) > 1 ? `  [${node.state}] ${node.title} (${node.id})` : `  [${node.state}] ${node.title}`))
+		.join("\n");
+	const text = [
+		headline,
+		...extraLines,
+		`Ready roots: ${rootLabels.join(", ") || "none"}.`,
+		`Context docs: ${input.created.docs.map((id) => createdLabels.get(id) ?? "unknown document").join(", ") || "none"}.`,
+		`Scoped rules: ${input.created.rules.map((id) => createdLabels.get(id) ?? "unknown rule").join(", ") || "none"}.`,
+		...(executionLines ? ["Execution:", executionLines] : []),
+	].join("\n");
+	return { type: "text", text };
+}

package/src/vehicle/papyrus-vehicle.ts

@@ -1,11 +1,12 @@
 /**
  * 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.*, artifact.*), so
- * merging costs nothing and avoids a separate registry/mount/client per domain.
+ * 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.
  *
- * skills, playbooks, discuss, and tasks still register via pi-papyrus's own
- * pi.registerTool() in domain-tools.ts, not here.
+ * 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.
  */
 import { VehicleRegistry } from "@danypops/vehicle-server";
 import type { AuthorityRegistry } from "../authority-registry.ts";
@@ -13,16 +14,26 @@ import type { Notes } from "../note-service.ts";
 import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
 import type { ArtifactStore } from "../ports/artifact-store.ts";
 import type { ArtifactTrashStore } from "../ports/artifact-trash-store.ts";
+import type { SessionIdentity } from "../session-identity-service.ts";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { Tasks } from "../task-service.ts";
 import { registerArtifactTrashOperations } from "./artifact-trash-vehicle.ts";
 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";
 
 export interface PapyrusVehicleDeps {
 	artifacts: ArtifactStore & ArtifactTrashStore;
 	scopes: ArtifactScopeStore;
 	authority: AuthorityRegistry;
 	notes: Notes;
+	events: TaskEventStore;
+	taskScopes: TaskScopeStore;
+	tasks: Tasks;
+	sessionIdentity: SessionIdentity;
 }
 
 export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleRegistry {
@@ -30,6 +41,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 });
 	registerArtifactTrashOperations(registry, deps.artifacts);
 	return registry;
 }

package/src/vehicle/playbooks-vehicle.ts

@@ -0,0 +1,243 @@
+/**
+ * Playbooks projected as a real VehicleRegistry: one VehicleOperation per real action.
+ * Wraps modules/playbooks.ts's operation definitions. remove/restore/remove_subtree are
+ * not duplicated here -- see ./artifact-trash-vehicle.ts.
+ *
+ * playbooks.invoke's own module handler calls tasks.focus() directly (bypassing the
+ * guarded tasks.focus operation, per modules/playbooks.ts's own doc comment) and re-runs
+ * that exact guard itself via sessionIdentity.assertAuthorized(session_id, session_secret).
+ * Those two fields never belong in this operation's model-visible inputSchema -- a model
+ * has no business knowing or supplying a session secret. Instead they travel through
+ * VehicleInvocationOptions.principal.claims, populated by pi-papyrus's own
+ * resolveInvocation hook (see vehicle-notes-client.ts) from its own already-cached
+ * session_secret, the same value the hand-rolled tool used to thread through as a raw
+ * input field. A caller with no cached secret for this session (unregistered, or a non-Pi
+ * Vehicle client) simply gets the guard's own no-op-when-unset default, unchanged.
+ *
+ * invoke's output carries its own `content` block (see @danypops/vehicle-core's
+ * WithVehicleContent) built from the same execution-DAG summary pi-papyrus's hand-rolled
+ * tool used to build client-side.
+ */
+import { bindVehicleOperation, defineVehicleOperation, type VehicleOperationContext } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import { listPlaybooks } from "../domain-services.ts";
+import { playbooksOperations } from "../modules/playbooks.ts";
+import type { PlaybookInvocationResult, PlaybookMissingArguments } from "../playbook-execution.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { SessionIdentity } from "../session-identity-service.ts";
+import type { Tasks } from "../task-service.ts";
+import { buildWorkflowRunContent, looseObjectSchema, normalizeJsonEncodedField, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+
+const OWNER = "playbooks";
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+export interface PlaybooksVehicleDeps {
+	artifacts: ArtifactStore;
+	events: TaskEventStore;
+	scopes: TaskScopeStore;
+	artifactScopes: ArtifactScopeStore;
+	tasks: Tasks;
+	sessionIdentity: SessionIdentity;
+}
+
+/** Unscoped resolution -- a Playbook is commonly cross-project (e.g. a lab-deploy playbook), matching the hand-rolled tool's own resolutionRequest choice. */
+function resolvePlaybookId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: unknown, name: unknown): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) throw new Error("id or name is required");
+	return resolveArtifactIdWidened(name, () => listPlaybooks(artifacts, scopes, { text: name }));
+}
+
+export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, deps: PlaybooksVehicleDeps): void {
+	const { artifacts, events, scopes, artifactScopes, tasks, sessionIdentity } = deps;
+	const moduleOperations = new Map(playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity }).map((op) => [op.name, op]));
+	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
+
+	const define = (
+		action: string,
+		description: string,
+		effect: "read" | "local-write",
+		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		required: readonly string[],
+		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
+		execute?: (input: Record<string, unknown>, context: VehicleOperationContext<Record<string, unknown>>) => unknown,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `playbooks.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["playbooks:read", "playbooks:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => (execute ?? ((input: Record<string, unknown>) => call(`playbooks.${action}`, input)))(resolve(context.input), context)));
+	};
+
+	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).",
+		"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"],
+		(input) => {
+			normalizeJsonEncodedField(input, "arguments");
+			return input;
+		},
+	);
+
+	define(
+		"list",
+		"Lists Playbooks matching an optional status/text filter, scoped to project_root when given.",
+		"read",
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		[],
+		(input) => input,
+	);
+
+	define(
+		"show",
+		"Shows one Playbook by id or title.",
+		"read",
+		{ id: stringProp, name: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"preview",
+		"Renders a Playbook's whole composition tree as text, with no side effects.",
+		"read",
+		{ id: stringProp, name: stringProp, arguments: { type: "object" } },
+		[],
+		(input) => {
+			normalizeJsonEncodedField(input, "arguments");
+			return { ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) };
+		},
+	);
+
+	define(
+		"invoke",
+		"Compiles the Playbook's steps and composition tree into real Tasks wired with dependsOn, and focuses the first one -- one step surfaces at a time as it becomes focused, exactly like any other Task. `arguments` supplies known values as {name: value}; if a declared REQUIRED argument is still missing, nothing is created and missingArguments is returned instead -- ask the human for these (discuss tool, live:true) and invoke again, never guess. Drive the returned entryTaskId forward with the tasks tool (start/submit/complete).",
+		"local-write",
+		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: { type: "object" }, project_root: stringProp },
+		[],
+		(input) => {
+			normalizeJsonEncodedField(input, "arguments");
+			return { ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) };
+		},
+		(input, context) => {
+			const claims = context.principal?.claims as { sessionId?: string; sessionSecret?: string } | undefined;
+			const invocation = call("playbooks.invoke", {
+				...input,
+				session_id: claims?.sessionId,
+				session_secret: claims?.sessionSecret,
+			}) as PlaybookInvocationResult | PlaybookMissingArguments;
+			if ("missingArguments" in invocation) {
+				const text = `Missing required argument(s): ${invocation.missingArguments.join(", ")}. Nothing was created -- ask the human for these (discuss tool, live:true), then invoke again.`;
+				return { ...invocation, content: [{ type: "text" as const, text }] };
+			}
+			const nodeById = new Map(invocation.execution.nodes.map((node) => [node.id, node]));
+			const entryLabel = nodeById.get(invocation.entryTaskId)?.title ?? invocation.entryTaskId;
+			const content = buildWorkflowRunContent(
+				artifacts,
+				`Invoked playbook run ${invocation.runId}: ${invocation.created.tasks.length} task(s), ${invocation.created.rules.length} rule(s), ${invocation.created.docs.length} doc(s) created.`,
+				invocation,
+				[`Entry task now focused: ${entryLabel}. Drive it forward with the tasks tool (start/submit/complete) -- contains/depends_on wiring auto-focuses each next step.`],
+			);
+			return { ...invocation, content: [content] };
+		},
+	);
+
+	define(
+		"enable",
+		"Enables a Playbook.",
+		"local-write",
+		{ id: stringProp, name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"disable",
+		"Disables a Playbook.",
+		"local-write",
+		{ id: stringProp, name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"assign_project",
+		"Reassigns a Playbook's project_root, or unscopes it when project_root is omitted.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"update",
+		"Changes a Playbook's title/body/labels (at least one required). Refused for a read-only external projection.",
+		"local-write",
+		{ id: stringProp, name: stringProp, title: stringProp, body: stringProp, labels: { type: "array" }, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name) }),
+	);
+
+	define(
+		"contain",
+		"Nests a child Playbook inside a parent -- the child's steps run AFTER the parent's own. Prefer parent_name/child_name over parent_id/child_id -- resolved server-side.",
+		"local-write",
+		{ parent_id: stringProp, parent_name: stringProp, child_id: stringProp, child_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			parent_id: resolvePlaybookId(artifacts, artifactScopes, input.parent_id, input.parent_name),
+			child_id: resolvePlaybookId(artifacts, artifactScopes, input.child_id, input.child_name),
+		}),
+	);
+
+	define(
+		"uncontain",
+		"Removes a parent/child Playbook nesting. Idempotent -- a no-op if the edge is already absent.",
+		"local-write",
+		{ parent_id: stringProp, parent_name: stringProp, child_id: stringProp, child_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			parent_id: resolvePlaybookId(artifacts, artifactScopes, input.parent_id, input.parent_name),
+			child_id: resolvePlaybookId(artifacts, artifactScopes, input.child_id, input.child_name),
+		}),
+	);
+
+	define(
+		"depend",
+		"Chains a prerequisite Playbook before another -- it must fully complete FIRST. Prefer dependency_name over dependency_id.",
+		"local-write",
+		{ id: stringProp, name: stringProp, dependency_id: stringProp, dependency_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name),
+			dependency_id: resolvePlaybookId(artifacts, artifactScopes, input.dependency_id, input.dependency_name),
+		}),
+	);
+
+	define(
+		"undepend",
+		"Removes a Playbook dependency. Idempotent -- a no-op if the edge is already absent.",
+		"local-write",
+		{ id: stringProp, name: stringProp, dependency_id: stringProp, dependency_name: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({
+			...input,
+			id: resolvePlaybookId(artifacts, artifactScopes, input.id, input.name),
+			dependency_id: resolvePlaybookId(artifacts, artifactScopes, input.dependency_id, input.dependency_name),
+		}),
+	);
+}

package/src/vehicle/skills-vehicle.ts

@@ -0,0 +1,194 @@
+/**
+ * Skills projected as a real VehicleRegistry: one VehicleOperation per real action.
+ * Wraps modules/skills.ts's operation definitions plus skills.instantiate (composition-
+ * root-only in the module -- see instantiateSkillOrTemplate's own doc comment).
+ * remove/restore/remove_subtree are not duplicated here -- see ./artifact-trash-vehicle.ts.
+ *
+ * skills.run's output carries its own `content` block (see @danypops/vehicle-core's
+ * WithVehicleContent) built from the same execution-DAG summary pi-papyrus's hand-rolled
+ * tool used to build client-side -- the model reads a summary, not the raw node/layer/
+ * cycleId structure.
+ */
+import { bindVehicleOperation, defineVehicleOperation } from "@danypops/vehicle-core";
+import type { VehicleRegistry } from "@danypops/vehicle-server";
+import type { AuthorityRegistry } from "../authority-registry.ts";
+import { listSkills } from "../domain-services.ts";
+import { instantiateSkillOrTemplate, skillsOperations } from "../modules/skills.ts";
+import type { ArtifactScopeStore } from "../ports/artifact-scope-store.ts";
+import type { ArtifactStore } from "../ports/artifact-store.ts";
+import type { TaskEventStore } from "../ports/task-event-store.ts";
+import type { TaskScopeStore } from "../ports/task-scope-store.ts";
+import type { Tasks } from "../task-service.ts";
+import type { WorkflowRunResult } from "../workflow-execution.ts";
+import { buildWorkflowRunContent, looseObjectSchema, numberProp, passthroughOutput, resolveArtifactIdWidened, stringProp } from "./artifact-vehicle-shared.ts";
+
+const OWNER = "skills";
+const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+export interface SkillsVehicleDeps {
+	artifacts: ArtifactStore;
+	events: TaskEventStore;
+	scopes: TaskScopeStore;
+	artifactScopes: ArtifactScopeStore;
+	authority: AuthorityRegistry;
+	/** Only for skills.instantiate's task-target branch -- see instantiateSkillOrTemplate. */
+	tasks: Tasks;
+}
+
+function resolveSkillId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, projectRoot: string | undefined, id: unknown, name: unknown): string {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) throw new Error("id or name is required");
+	return resolveArtifactIdWidened(
+		name,
+		() => listSkills(artifacts, scopes, { text: name, projectRoot }),
+		projectRoot === undefined ? undefined : () => listSkills(artifacts, scopes, { text: name }),
+	);
+}
+
+function resolveTemplateId(artifacts: ArtifactStore, scopes: ArtifactScopeStore, projectRoot: string | undefined, id: unknown, name: unknown): string | undefined {
+	if (typeof id === "string" && id.length > 0) return id;
+	if (typeof name !== "string" || name.length === 0) return undefined;
+	return resolveArtifactIdWidened(
+		name,
+		() => listSkills(artifacts, scopes, { text: name, projectRoot }),
+		projectRoot === undefined ? undefined : () => listSkills(artifacts, scopes, { text: name }),
+	);
+}
+
+export function registerSkillsVehicleOperations(registry: VehicleRegistry, deps: SkillsVehicleDeps): void {
+	const { artifacts, events, scopes, artifactScopes, authority, tasks } = deps;
+	const moduleOperations = new Map(skillsOperations({ artifacts, events, scopes, artifactScopes, authority }).map((op) => [op.name, op]));
+	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
+
+	const define = (
+		action: string,
+		description: string,
+		effect: "read" | "local-write",
+		properties: Record<string, { type: string; enum?: readonly string[] }>,
+		required: readonly string[],
+		resolve: (input: Record<string, unknown>) => Record<string, unknown>,
+		execute?: (input: Record<string, unknown>) => unknown,
+	): void => {
+		const operation = defineVehicleOperation({
+			name: `skills.${action}`,
+			version: 1,
+			description,
+			input: looseObjectSchema(properties, required),
+			output: passthroughOutput,
+			permissions: ["skills:read", "skills:write"],
+			effect,
+			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
+			limits: LIMITS,
+		});
+		registry.register(OWNER, bindVehicleOperation(operation, () => async (context) => (execute ?? ((input: Record<string, unknown>) => call(`skills.${action}`, input)))(resolve(context.input))));
+	};
+
+	define(
+		"create",
+		"Creates a Skill -- a parameterized Task/Rule/Doc bundle, distinct from a prompt-only skill. project_root is optional (omitted = unscoped).",
+		"local-write",
+		{ title: stringProp, body: stringProp, trigger: stringProp, steps: { type: "array" }, tools: { type: "array" }, definition: { type: "object" }, labels: { type: "array" }, extra: { type: "object" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["title"],
+		(input) => input,
+	);
+
+	define(
+		"create_template",
+		"Creates a compatibility artifact-template (defaults/required fields for a target kind), distinct from a workflow Skill.",
+		"local-write",
+		{ title: stringProp, target_kind: stringProp, defaults: { type: "object" }, required: { type: "array" }, body: stringProp, labels: { type: "array" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["title", "target_kind"],
+		(input) => input,
+	);
+
+	define(
+		"list",
+		"Lists Skills matching an optional status/text filter, scoped to project_root when given.",
+		"read",
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		[],
+		(input) => input,
+	);
+
+	define(
+		"show",
+		"Shows one Skill by id or title.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"invoke",
+		"Renders a Skill's own preview text with no side effects.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"run",
+		"Validates arguments and atomically creates one scoped workflow run: real Tasks/Rules/Docs wired with dependsOn, one step surfacing at a time as it becomes focused -- no text dump. project_root is required here (no ambient cwd server-side); pass it explicitly.",
+		"local-write",
+		{ id: stringProp, name: stringProp, run_id: stringProp, arguments: { type: "object" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["project_root"],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+		(input) => {
+			const run = call("skills.run", input) as WorkflowRunResult;
+			const content = buildWorkflowRunContent(artifacts, `Created Skill run ${run.runId}: ${run.created.tasks.length} tasks, ${run.created.rules.length} rules, ${run.created.docs.length} docs.`, run);
+			return { ...run, content: [content] };
+		},
+	);
+
+	define(
+		"enable",
+		"Enables a Skill.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"disable",
+		"Disables a Skill.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"instantiate",
+		"Instantiates a compatibility artifact-template (template_id/template_name) -- a task-target template calls tasks.create() directly; any other target creates a plain artifact. project_root is required here (no ambient cwd server-side).",
+		"local-write",
+		{ template_id: stringProp, template_name: stringProp, title: stringProp, body: stringProp, status: stringProp, labels: { type: "array" }, extra: { type: "object" }, subtype: stringProp, kind: stringProp, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		["title", "project_root"],
+		(input) => {
+			const templateId = resolveTemplateId(artifacts, artifactScopes, input.project_root as string | undefined, input.template_id, input.template_name);
+			if (!templateId) throw new Error("template_id or template_name is required");
+			return { ...input, template_id: templateId };
+		},
+		(input) => instantiateSkillOrTemplate({ artifacts, tasks, authority }, input, { actor: input.actor as string | undefined, source: input.source as string | undefined, sessionId: (input.session_id ?? input.sessionId) as string | undefined }),
+	);
+
+	define(
+		"assign_project",
+		"Reassigns a Skill's project_root, or unscopes it when project_root is omitted.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, undefined, input.id, input.name) }),
+	);
+
+	define(
+		"update",
+		"Changes a Skill's title/body/labels (at least one required). Refused for a read-only external projection.",
+		"local-write",
+		{ id: stringProp, name: stringProp, title: stringProp, body: stringProp, labels: { type: "array" }, project_root: stringProp, actor: stringProp, source: stringProp, session_id: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveSkillId(artifacts, artifactScopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+}