@danypops/papyrus 0.49.0 → 0.50.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.49.0",
+  "version": "0.50.0",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "main": "./src/index.ts",

package/src/cli/docs-command.ts

@@ -114,6 +114,93 @@ const showCommand = buildCommand({
 	docs: { brief: "Show one Doc" },
 });
 
+interface CliArtifactScope {
+	artifactId: string;
+	mode: string;
+	projectIds: string[];
+	source: string;
+}
+
+function renderScope(scope: CliArtifactScope): string {
+	return scope.mode === "global" ? "global (applies to every project)" : `projects: ${scope.projectIds.join(", ")}`;
+}
+
+const scopeCommand = buildCommand({
+	func: async function (this: DocsContext, _flags: Record<string, never>, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("docs.scope", { id });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Document id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Show a Doc's real project scope" },
+});
+
+const setGlobalCommand = buildCommand({
+	func: async function (this: DocsContext, _flags: Record<string, never>, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("docs.set_global", { id });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: { flags: {}, positional: { kind: "tuple", parameters: [{ brief: "Document id", parse: String, placeholder: "id" }] } },
+	docs: { brief: "Make a Doc apply in every project" },
+});
+
+const addProjectCommand = buildCommand({
+	func: async function (this: DocsContext, _flags: Record<string, never>, id: string, project: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("docs.add_project", { id, project });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Document id", parse: String, placeholder: "id" },
+				{ brief: "Project id/name/alias/root to add", parse: String, placeholder: "project" },
+			],
+		},
+	},
+	docs: { brief: "Add one project to a Doc's membership" },
+});
+
+const removeProjectCommand = buildCommand({
+	func: async function (this: DocsContext, _flags: Record<string, never>, id: string, project: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("docs.remove_project", { id, project });
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {},
+		positional: {
+			kind: "tuple",
+			parameters: [
+				{ brief: "Document id", parse: String, placeholder: "id" },
+				{ brief: "Project id/name/alias/root to remove", parse: String, placeholder: "project" },
+			],
+		},
+	},
+	docs: { brief: "Remove one project from a Doc's membership" },
+});
+
+const replaceProjectsCommand = buildCommand({
+	func: async function (this: DocsContext, flags: { projectsJson: string[] }, id: string) {
+		const scope = await this.client.call<Record<string, unknown>, CliArtifactScope>("docs.replace_projects", {
+			id,
+			projects: flags.projectsJson,
+		});
+		render.call(this, scope, renderScope(scope));
+	},
+	parameters: {
+		flags: {
+			projectsJson: {
+				brief: "JSON string array of project id/name/alias/root references",
+				kind: "parsed",
+				parse: parseStringArray,
+				placeholder: "json",
+			},
+		},
+		positional: { kind: "tuple", parameters: [{ brief: "Document id", parse: String, placeholder: "id" }] },
+	},
+	docs: { brief: "Replace a Doc's entire project membership" },
+});
+
 function buildStatusTransitionCommand(action: "activate" | "archive" | "reopen") {
 	return buildCommand({
 		func: async function (this: DocsContext, _flags: Record<string, never>, id: string) {
@@ -173,6 +260,11 @@ const app = buildApplication(
 			create: createCommand,
 			list: listCommand,
 			"assign-project": assignProjectCommand,
+			scope: scopeCommand,
+			"set-global": setGlobalCommand,
+			"add-project": addProjectCommand,
+			"remove-project": removeProjectCommand,
+			"replace-projects": replaceProjectsCommand,
 			show: showCommand,
 			activate: buildStatusTransitionCommand("activate"),
 			archive: buildStatusTransitionCommand("archive"),

package/src/docs/docs-service.ts

@@ -6,9 +6,11 @@
 
 import { type Artifact, requireLocallyOwnedContent } from "../artifact/artifact.ts";
 import type { ArtifactEventContext } from "../artifact/artifact-event.ts";
-import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
+import type { ArtifactScope, ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { ArtifactAction, AuthorityRegistry } from "../authority-registry.ts";
+import { ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT } from "../constants.ts";
+import { resolveProjectReference } from "../domain/project-registry.ts";
 import { normalizeProjectRoot } from "../domain/task-scope.ts";
 import {
 	assertBodyBounds,
@@ -23,6 +25,7 @@ import {
 	type UpdateContentInput,
 } from "../domain-service-shared.ts";
 import { NOTE_SUBTYPE } from "../note/note-service.ts";
+import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
 
 function rejectsNoteTemplate(artifacts: ArtifactStore, templateId: string | undefined, subtype: string | undefined): boolean {
 	if (subtype === NOTE_SUBTYPE) return true;
@@ -68,6 +71,8 @@ export interface CreateDocumentInput {
 	templateId?: string;
 	/** Optional at creation, unlike Tasks -- omitting it leaves the Doc in the unscoped bucket, matching today's default behavior for every existing caller. */
 	projectRoot?: string;
+	/** Bounded exact registered project references (id/name/alias/root) -- fail-closed unlike projectRoot's auto-register-by-root legacy form. Takes precedence over projectRoot when both are given. */
+	projectReferences?: string[];
 }
 
 export type UpdateDocumentInput = UpdateContentInput;
@@ -87,9 +92,13 @@ export function createDocument(
 	input: CreateDocumentInput,
 	authority: AuthorityRegistry,
 	context?: ArtifactEventContext,
+	registry?: ProjectRegistryStore,
 ): Artifact {
 	if (rejectsNoteTemplate(artifacts, input.templateId, input.subtype)) requireNotesFacade(authority, "docs");
 	authority.requireArtifactAllowed("doc", input.subtype ?? templateSubtype(artifacts, input.templateId), "create", "docs");
+	if (input.projectReferences !== undefined && input.projectReferences.length > 0 && registry === undefined) {
+		throw new Error("projectReferences requires a project registry");
+	}
 	const projectRoot = input.projectRoot === undefined ? undefined : normalizeProjectRoot(input.projectRoot);
 	const document = artifacts.create(
 		{
@@ -107,7 +116,15 @@ export function createDocument(
 		},
 		context,
 	);
-	scopes.assign(document.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	if (input.projectReferences !== undefined && input.projectReferences.length > 0) {
+		if (input.projectReferences.length > ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
+			throw new Error(`projectReferences may include at most ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} entries`);
+		}
+		const ids = input.projectReferences.map((reference) => resolveProjectReference(registry!, reference).id);
+		scopes.replaceProjects(document.id, ids, "explicit");
+	} else {
+		scopes.assign(document.id, projectRoot, projectRoot === undefined ? "unscoped" : "explicit");
+	}
 	return document;
 }
 
@@ -130,6 +147,65 @@ export function assignDocumentProject(
 	return artifacts.get(id)!;
 }
 
+/**
+ * The multi-project scope surface docs.assign_project cannot express (more than one membership,
+ * or exact fail-closed reference resolution instead of assign's auto-register-by-root). Mirrors
+ * rules.ts's own ruleScope/setRuleGlobal/replaceRuleProjects/addRuleProject/removeRuleProject --
+ * id is resolved through requireDocument so these reject the same way against a non-Doc, unknown
+ * id, or a Note as every other docs.* mutation; the project REFERENCE (name/alias/root) is
+ * resolved through the shared registry's resolveProjectReference, so an unknown or ambiguous
+ * project fails closed with bounded candidates rather than silently creating a new registration.
+ */
+export function docScope(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string): ArtifactScope {
+	requireDocument(artifacts, id);
+	return scopes.scope(id);
+}
+
+export function setDocGlobal(artifacts: ArtifactStore, scopes: ArtifactScopeStore, id: string): ArtifactScope {
+	requireDocument(artifacts, id);
+	return scopes.setGlobal(id, "explicit");
+}
+
+export function replaceDocProjects(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	id: string,
+	projectReferences: readonly string[],
+): ArtifactScope {
+	requireDocument(artifacts, id);
+	if (projectReferences.length === 0) throw new Error("projectReferences must be non-empty; use docs.set_global to clear scoping");
+	if (projectReferences.length > ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT) {
+		throw new Error(`projectReferences may include at most ${ARTIFACT_SCOPE_MAX_PROJECTS_PER_ARTIFACT} entries`);
+	}
+	const ids = projectReferences.map((reference) => resolveProjectReference(registry, reference).id);
+	return scopes.replaceProjects(id, ids, "explicit");
+}
+
+export function addDocProject(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	id: string,
+	projectReference: string,
+): ArtifactScope {
+	requireDocument(artifacts, id);
+	const project = resolveProjectReference(registry, projectReference);
+	return scopes.addProject(id, project.id, "explicit");
+}
+
+export function removeDocProject(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	registry: ProjectRegistryStore,
+	id: string,
+	projectReference: string,
+): ArtifactScope {
+	requireDocument(artifacts, id);
+	const project = resolveProjectReference(registry, projectReference);
+	return scopes.removeProject(id, project.id);
+}
+
 function requireDocument(artifacts: ArtifactStore, id: string): Artifact {
 	const document = requireKind(artifacts, id, "doc");
 	if (document.subtype === NOTE_SUBTYPE) throw new Error("note access requires a notes.* operation");

package/src/domain-service-shared.ts

@@ -53,8 +53,10 @@ export interface ListFilter {
 	status?: string;
 	text?: string;
 	limit?: number;
-	/** When supplied, results are limited to artifacts scoped to this project (or the unscoped bucket, for an empty string is not accepted -- use assignArtifactProject's own validation). */
+	/** When supplied, results are limited to artifacts with EXACT membership in this project (or the unscoped bucket) -- audit semantics, never includes a global artifact unless it happens to also carry this exact membership (it never does; global and "projects" are mutually exclusive modes). Mutually exclusive with applicableToProjectRoot -- pass at most one. */
 	projectRoot?: string;
+	/** When supplied instead of projectRoot, results are APPLICABLE to this project: every global artifact, plus every artifact whose bounded membership set includes this registered project root -- "would this show up for someone working in this project", not "is this project its only home". Distinct from projectRoot's exact-membership audit semantics. An empty string is not accepted -- use normalizeProjectRoot's own validation. */
+	applicableToProjectRoot?: string;
 }
 
 /**
@@ -62,7 +64,8 @@ export interface ListFilter {
  * via ArtifactScopeStore first and post-filter by kind/status/text (mirrors Tasks.list's
  * established scoped-listing shape); otherwise fall back to the existing unscoped query
  * path unchanged, so every caller that predates project scoping keeps working exactly as
- * before.
+ * before. filter.applicableToProjectRoot takes a separate, additive branch -- see its own
+ * doc comment on ListFilter for why this is not the same query as filter.projectRoot.
  */
 export function listScoped(
 	artifacts: ArtifactStore,
@@ -71,6 +74,23 @@ export function listScoped(
 	filter: ListFilter,
 	excludeSubtype?: string,
 ): Artifact[] {
+	if (filter.applicableToProjectRoot !== undefined) {
+		const limit = filter.limit ?? ARTIFACT_SCOPE_MAX_ARTIFACTS;
+		if (!Number.isInteger(limit) || limit < 1 || limit > ARTIFACT_SCOPE_MAX_ARTIFACTS) {
+			throw new Error(`list limit must be between 1 and ${ARTIFACT_SCOPE_MAX_ARTIFACTS}`);
+		}
+		const projectRoot = normalizeProjectRoot(filter.applicableToProjectRoot);
+		// Bounded (not a genuinely unlimited table scan) by capping the underlying query at
+		// ARTIFACT_SCOPE_MAX_ARTIFACTS before the applicability filter -- the same bounded-
+		// approximation tradeoff listInjectableRules already makes for "active rules," accepted
+		// here since a real kind/status/text-matching artifact count beyond that bound is not a
+		// realistic Papyrus deployment shape.
+		return artifacts
+			.query({ kind, excludeSubtype, status: filter.status, text: filter.text, limit: ARTIFACT_SCOPE_MAX_ARTIFACTS })
+			.filter((artifact) => scopes.appliesToProjectRoot(artifact.id, projectRoot))
+			.sort((left, right) => right.updated_at.localeCompare(left.updated_at) || left.id.localeCompare(right.id))
+			.slice(0, limit);
+	}
 	if (filter.projectRoot === undefined)
 		return artifacts.query({ kind, excludeSubtype, status: filter.status, text: filter.text, limit: filter.limit });
 	const limit = filter.limit ?? ARTIFACT_SCOPE_MAX_ARTIFACTS;

package/src/handlers/docs.ts

@@ -9,10 +9,21 @@ import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
 import { listDocuments } from "../docs/docs-service.ts";
 import { docsOperations } from "../modules/docs.ts";
+import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
 import { booleanProp, createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "docs";
 
+/**
+ * Resolves a doc's id from either an explicit id or its title. When project_root is given and
+ * the project-scoped search finds nothing, widens only to a doc that actually APPLIES to this
+ * project (global, or explicitly scoped to it via applicableToProjectRoot) -- never to a
+ * same-named doc that belongs to a different project. A prior version widened to every doc of
+ * that name across every project unconditionally once the scoped search came up empty, silently
+ * leaking a name-based mutation across project boundaries (the same real bug rules.ts's own
+ * resolveRuleId had before its own fix). A caller wanting a genuine all-project search can
+ * already get it by omitting project_root entirely -- unchanged, unscoped behavior.
+ */
 function resolveDocId(
 	artifacts: ArtifactStore,
 	scopes: ArtifactScopeStore,
@@ -26,7 +37,7 @@ function resolveDocId(
 		artifacts,
 		name,
 		() => listDocuments(artifacts, scopes, { text: name, projectRoot }),
-		projectRoot === undefined ? undefined : () => listDocuments(artifacts, scopes, { text: name }),
+		projectRoot === undefined ? undefined : () => listDocuments(artifacts, scopes, { text: name, applicableToProjectRoot: projectRoot }),
 	);
 }
 
@@ -42,14 +53,15 @@ export function registerDocsVehicleOperations(
 	artifacts: ArtifactStore,
 	scopes: ArtifactScopeStore,
 	authority: AuthorityRegistry,
+	projectRegistry: ProjectRegistryStore,
 ): void {
-	const moduleOperations = new Map(docsOperations(artifacts, scopes, authority).map((op) => [op.name, op]));
+	const moduleOperations = new Map(docsOperations(artifacts, scopes, authority, projectRegistry).map((op) => [op.name, op]));
 	const call = (name: string, input: Record<string, unknown>): unknown => moduleOperations.get(name)!.execute(input);
 	const define = createOperationDefiner(registry, OWNER, "docs", ["docs:read", "docs:write"], call);
 
 	define(
 		"create",
-		"Creates a Doc -- descriptive knowledge, not actionable work. project_root is optional (omitted = unscoped).",
+		"Creates a Doc -- descriptive knowledge, not actionable work. project_root is optional (omitted = unscoped). projects (a list of exact registered project id/name/alias/root references) creates it bounded to several projects at once instead, taking precedence over project_root when both are given.",
 		"local-write",
 		{
 			title: stringProp,
@@ -59,6 +71,7 @@ export function registerDocsVehicleOperations(
 			extra: { type: "object" } as unknown as { type: string },
 			template_id: stringProp,
 			project_root: stringProp,
+			projects: { type: "array" } as unknown as { type: string },
 		},
 		["title"],
 		(input) => input,
@@ -66,9 +79,9 @@ export function registerDocsVehicleOperations(
 
 	define(
 		"list",
-		"Lists Docs matching an optional status/text filter, scoped to project_root when given. Returns a lean summary (no body) by default -- pass full: true for the complete artifact.",
+		"Lists Docs matching an optional status/text filter. project_root alone scopes to EXACT membership in that project (audit semantics); project_root plus applicable:true instead lists every Doc APPLICABLE to it (global Docs plus Docs whose membership includes it). Returns a lean summary (no body) by default -- pass full: true for the complete artifact.",
 		"read",
-		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, full: booleanProp },
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, applicable: booleanProp, full: booleanProp },
 		[],
 		(input) => input,
 	);
@@ -134,6 +147,68 @@ export function registerDocsVehicleOperations(
 		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, undefined, input.id, input.name) }),
 	);
 
+	define(
+		"scope",
+		"Shows a Doc's real project scope: global (applies everywhere) or the bounded set of registered projects it applies to.",
+		"read",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"set_global",
+		"Makes a Doc apply in every project, clearing any project membership. The only way to widen a project-bound Doc back to global -- removing its last membership through remove_project is rejected instead.",
+		"local-write",
+		{ id: stringProp, name: stringProp, project_root: stringProp },
+		[],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"add_project",
+		"Adds one registered project (exact id, name, alias, or root) to a Doc's membership, switching it from global to project-bound if it was global. Idempotent if the project is already a member.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			project: { ...stringProp, description: "Exact project id, name, alias, or registered root to add." },
+			project_root: stringProp,
+		},
+		["project"],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"remove_project",
+		"Removes one registered project from a Doc's membership. Rejected while it is the Doc's only remaining membership -- call set_global first if the Doc should stop being project-bound entirely.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			project: { ...stringProp, description: "Exact project id, name, alias, or registered root to remove." },
+			project_root: stringProp,
+		},
+		["project"],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
+	define(
+		"replace_projects",
+		"Replaces a Doc's entire project membership with exactly this bounded, non-empty list of registered project references (id/name/alias/root). Use set_global instead to clear scoping entirely.",
+		"local-write",
+		{
+			id: stringProp,
+			name: stringProp,
+			projects: { type: "array", description: "Non-empty list of exact project id/name/alias/root references." } as unknown as {
+				type: string;
+			},
+			project_root: stringProp,
+		},
+		["projects"],
+		(input) => ({ ...input, id: resolveDocId(artifacts, scopes, input.project_root as string | undefined, input.id, input.name) }),
+	);
+
 	define(
 		"update",
 		"Changes a Doc's title/body/labels (at least one required). Refused for a read-only external projection (e.g. web-spider-ingested Docs) -- capture a correction as a new linked Doc instead.",

package/src/handlers/registry.ts

@@ -51,7 +51,7 @@ export function createPapyrusVehicleRegistry(deps: PapyrusVehicleDeps): VehicleR
 	registry.setExposeHandlerFailureDetails(true);
 	registerNotesVehicleOperations(registry, deps.notes, deps.artifacts);
 	registerRulesVehicleOperations(registry, deps.artifacts, deps.scopes, deps.projectRegistry);
-	registerDocsVehicleOperations(registry, deps.artifacts, deps.scopes, deps.authority);
+	registerDocsVehicleOperations(registry, deps.artifacts, deps.scopes, deps.authority, deps.projectRegistry);
 	registerPlaybooksVehicleOperations(registry, {
 		artifacts: deps.artifacts,
 		events: deps.events,

package/src/modules/docs.ts

@@ -12,16 +12,22 @@ import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
 import {
+	addDocProject,
 	assignDocumentProject,
 	createDocument,
 	type DocumentRelation,
+	docScope,
 	linkDocument,
 	listDocuments,
+	removeDocProject,
+	replaceDocProjects,
+	setDocGlobal,
 	showDocument,
 	transitionDocument,
 	updateDocument,
 } from "../docs/docs-service.ts";
 import type { OperationDefinition } from "../module-registry.ts";
+import type { ProjectRegistryStore } from "../ports/project-registry-store.ts";
 import { type OperationInput, optionalBoolean, optionalNumber, optionalString, string } from "./operation-input.ts";
 
 const MODULE_ID = "docs";
@@ -32,12 +38,23 @@ const eventContext = (input: OperationInput) => ({
 	sessionId: optionalString(input, "session_id") ?? optionalString(input, "sessionId"),
 });
 
-const artifactFilter = (input: OperationInput) => ({
-	status: optionalString(input, "status"),
-	text: optionalString(input, "text"),
-	limit: optionalNumber(input, "limit"),
-	projectRoot: optionalString(input, "project_root"),
-});
+/**
+ * applicable=true switches project_root's meaning from exact-membership audit listing to
+ * applicable listing (global Docs plus Docs whose bounded membership includes this project) --
+ * see ListFilter's own doc comment on projectRoot vs applicableToProjectRoot for why these are
+ * two distinct, non-overlapping query modes rather than one.
+ */
+const artifactFilter = (input: OperationInput) => {
+	const projectRoot = optionalString(input, "project_root");
+	const applicable = optionalBoolean(input, "applicable") === true;
+	if (applicable && projectRoot === undefined) throw new Error("applicable requires project_root");
+	return {
+		status: optionalString(input, "status"),
+		text: optionalString(input, "text"),
+		limit: optionalNumber(input, "limit"),
+		...(applicable ? { applicableToProjectRoot: projectRoot } : { projectRoot }),
+	};
+};
 
 /** Registers every docs.* operation against the shared ArtifactStore port. 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. */
@@ -50,10 +67,20 @@ export const DOCS_OPERATION_NAMES = [
 	"docs.reopen",
 	"docs.link",
 	"docs.assign_project",
+	"docs.scope",
+	"docs.set_global",
+	"docs.add_project",
+	"docs.remove_project",
+	"docs.replace_projects",
 	"docs.update",
 ] as const;
 
-export function docsOperations(artifacts: ArtifactStore, scopes: ArtifactScopeStore, authority: AuthorityRegistry): OperationDefinition[] {
+export function docsOperations(
+	artifacts: ArtifactStore,
+	scopes: ArtifactScopeStore,
+	authority: AuthorityRegistry,
+	registry: ProjectRegistryStore,
+): OperationDefinition[] {
 	const define = <Input, Output>(name: string, execute: (input: Input) => Output): OperationDefinition<Input, Output> => ({
 		name,
 		moduleId: MODULE_ID,
@@ -72,9 +99,11 @@ export function docsOperations(artifacts: ArtifactStore, scopes: ArtifactScopeSt
 					extra: input.extra as Record<string, unknown> | undefined,
 					templateId: optionalString(input, "template_id") ?? optionalString(input, "templateId"),
 					projectRoot: optionalString(input, "project_root"),
+					projectReferences: input.projects as string[] | undefined,
 				},
 				authority,
 				eventContext(input),
+				registry,
 			),
 		),
 		define("docs.list", (input: OperationInput) => {
@@ -104,6 +133,17 @@ export function docsOperations(artifacts: ArtifactStore, scopes: ArtifactScopeSt
 		define("docs.assign_project", (input: OperationInput) =>
 			assignDocumentProject(artifacts, scopes, string(input, "id"), optionalString(input, "project_root")),
 		),
+		define("docs.scope", (input: OperationInput) => docScope(artifacts, scopes, string(input, "id"))),
+		define("docs.set_global", (input: OperationInput) => setDocGlobal(artifacts, scopes, string(input, "id"))),
+		define("docs.add_project", (input: OperationInput) =>
+			addDocProject(artifacts, scopes, registry, string(input, "id"), string(input, "project")),
+		),
+		define("docs.remove_project", (input: OperationInput) =>
+			removeDocProject(artifacts, scopes, registry, string(input, "id"), string(input, "project")),
+		),
+		define("docs.replace_projects", (input: OperationInput) =>
+			replaceDocProjects(artifacts, scopes, registry, string(input, "id"), (input.projects as string[] | undefined) ?? []),
+		),
 		define("docs.update", (input: OperationInput) =>
 			updateDocument(
 				artifacts,

package/src/ops.ts

@@ -599,22 +599,34 @@ function readBoundedGateFile(path: string): string {
 	return readFileSync(path, "utf-8") as string;
 }
 
-/** Shared by the sync and async process-gate runners so "test" is never a second, independently
- * maintained copy of "command"'s own command-template/timeout selection. */
+/**
+ * Shared by the sync and async process-gate runners so "test" is never a second, independently
+ * maintained copy of "command"'s own command-template selection.
+ *
+ * "test" runs `gate.target` verbatim, exactly like "command" -- the only real difference is a
+ * more generous default timeout (GATE_TEST_TIMEOUT_MS vs GATE_COMMAND_TIMEOUT_MS), since a test
+ * suite routinely runs longer than an arbitrary command. It previously wrapped target in
+ * `npx vitest run ${target} --reporter=dot`, silently wrong for every real consumer in this
+ * ecosystem (all Bun-native, none use vitest): a target that was itself a full command (e.g.
+ * `bun test path/to.test.ts`, exactly what every existing gate/checklist example here has always
+ * shown) got parsed by vitest as three separate positional args, triggering vitest's own broad
+ * discovery across the whole repo instead of running the intended command at all -- a real
+ * incident (task ab1463e2) that produced an unrelated multi-suite vitest failure cascade instead
+ * of the actual target ever running.
+ */
 function processGateCommand(gate: Gate): { command: string; timeout: number } {
-	if (gate.type === "test")
-		return { command: `npx vitest run ${gate.target} --reporter=dot`, timeout: gate.timeoutMs ?? GATE_TEST_TIMEOUT_MS };
+	if (gate.type === "test") return { command: gate.target, timeout: gate.timeoutMs ?? GATE_TEST_TIMEOUT_MS };
 	return { command: gate.target, timeout: gate.timeoutMs ?? GATE_COMMAND_TIMEOUT_MS };
 }
 
 /**
  * spawnSync + manual stdout/stderr concatenation, not execSync: execSync's return value is stdout
- * only. Many real commands (bun test's own per-test lines and its pass/fail summary among them, and
- * vitest's own "test" gate output) write their actual output to stderr, so an execSync-based match
- * against gate.expect saw only the first line of a banner and never the result -- every such gate
- * failed regardless of whether the command actually passed. This one function now serves both
- * "command" and "test" gates; previously "test" was a second, separately-maintained execSync path
- * that never checked gate.expect at all.
+ * only. Many real commands (bun test's own per-test lines and its pass/fail summary among them)
+ * write their actual output to stderr, so an execSync-based match against gate.expect saw only the
+ * first line of a banner and never the result -- every such gate failed regardless of whether the
+ * command actually passed. This one function now serves both "command" and "test" gates;
+ * previously "test" was a second, separately-maintained execSync path that never checked
+ * gate.expect at all.
  */
 function runProcessGateSync(gate: Gate, cwd?: string): GateResult {
 	const { spawnSync } = require_("node:child_process");

package/src/service.ts

@@ -406,6 +406,11 @@ function handlers(
 		"docs.reopen": forwardToModule("docs.reopen"),
 		"docs.link": forwardToModule("docs.link"),
 		"docs.assign_project": forwardToModule("docs.assign_project"),
+		"docs.scope": forwardToModule("docs.scope"),
+		"docs.set_global": forwardToModule("docs.set_global"),
+		"docs.add_project": forwardToModule("docs.add_project"),
+		"docs.remove_project": forwardToModule("docs.remove_project"),
+		"docs.replace_projects": forwardToModule("docs.replace_projects"),
 		"docs.update": forwardToModule("docs.update"),
 		"notes.capture": forwardToModule("notes.capture"),
 		"notes.list": forwardToModule("notes.list"),
@@ -498,7 +503,7 @@ export function createPapyrusService(path: string): PapyrusService {
 	moduleRegistry.registerAll(sessionIdentityOperations(sessionIdentity));
 	moduleRegistry.registerAll(discussOperations(discussions));
 	moduleRegistry.registerAll(tasksOperations(tasks, artifacts, sessionIdentity));
-	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority));
+	moduleRegistry.registerAll(docsOperations(artifacts, artifactScopes, authority, projectRegistry));
 	moduleRegistry.registerAll(rulesOperations(artifacts, artifactScopes, projectRegistry));
 	moduleRegistry.registerAll(playbooksOperations({ artifacts, events, scopes, artifactScopes, tasks, sessionIdentity }));
 	moduleRegistry.registerAll(graphProjectionOperations(artifacts, projections, authority));