@docyrus/docyrus 0.0.41 → 0.0.43

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",
@@ -12,9 +12,9 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@hono/node-server": "^1.14.1",
-    "@mariozechner/pi-ai": "0.64.0",
-    "@mariozechner/pi-coding-agent": "0.64.0",
+    "@hono/node-server": "^1.19.13",
+    "@mariozechner/pi-ai": "0.65.0",
+    "@mariozechner/pi-coding-agent": "0.65.0",
     "@modelcontextprotocol/ext-apps": "^1.2.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@mozilla/readability": "^0.6.0",
@@ -23,8 +23,8 @@
     "@repomix/tree-sitter-wasms": "^0.1.16",
     "@sinclair/typebox": "^0.34.48",
     "@xterm/headless": "^5.5.0",
-    "diff": "^8.0.2",
-    "hono": "^4.7.10",
+    "diff": "^8.0.4",
+    "hono": "^4.12.12",
     "ignore-walk": "^8.0.0",
     "incur": "^0.1.6",
     "jsdom": "^29.0.1",
@@ -40,13 +40,14 @@
     "strip-ansi": "^7.1.0",
     "turndown": "^7.2.2",
     "turndown-plugin-gfm": "^1.0.2",
-    "undici": "^7.16.0",
+    "undici": "^7.24.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "web-tree-sitter": "0.25.10",
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@types/node": "^24.12.2",
     "@types/react": "^19.1.13"
   },
   "engines": {

package/resources/pi-agent/extensions/architect.ts

@@ -746,8 +746,8 @@ async function architectHandler(pi: ExtensionAPI, ctx: ExtensionCommandContext,
 }
 
 export default function architectExtension(pi: ExtensionAPI) {
-  pi.registerCommand("architect", {
-    description: "Analyze tenant data sources and plan Docyrus schema artifacts for an app idea",
+  pi.registerCommand("plan", {
+    description: "Discover tenant state and start a planning-only branch for an app idea or task",
     handler: async(args, ctx) => {
       await architectHandler(pi, ctx, args);
     },

package/resources/pi-agent/extensions/control.ts

@@ -1087,14 +1087,6 @@ export default function(pi: ExtensionAPI) {
     }
   });
 
-  pi.on("session_switch", async(_event, ctx) => {
-    await refreshServer(ctx);
-  });
-
-  pi.on("session_fork", async(_event, ctx) => {
-    await refreshServer(ctx);
-  });
-
   pi.on("session_shutdown", async() => {
     if (state.aliasTimer) {
       clearInterval(state.aliasTimer);

package/resources/pi-agent/extensions/knowledge.ts

@@ -621,13 +621,6 @@ export default function(pi: ExtensionAPI) {
     });
   });
 
-  pi.on("session_switch", async(_event, ctx) => {
-    await refreshKnowledgeState(pi, ctx, {
-      runCheck: false,
-      allowReminder: true,
-    });
-  });
-
   pi.on("turn_end", async(_event: TurnEndEvent, ctx) => {
     await refreshKnowledgeState(pi, ctx, {
       runCheck: false,

package/resources/pi-agent/extensions/loop.ts

@@ -8,7 +8,7 @@
 
 import { Type } from "@sinclair/typebox";
 import { complete, type Api, type Model, type UserMessage } from "@mariozechner/pi-ai";
-import type { ExtensionAPI, ExtensionContext, SessionSwitchEvent } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
 import { compact } from "@mariozechner/pi-coding-agent";
 import { Container, type SelectItem, SelectList, Text } from "@mariozechner/pi-tui";
 import { DynamicBorder } from "@mariozechner/pi-coding-agent";
@@ -439,8 +439,4 @@ export default function loopExtension(pi: ExtensionAPI): void {
   pi.on("session_start", async(_event, ctx) => {
     await restoreLoopState(ctx);
   });
-
-  pi.on("session_switch", async(_event: SessionSwitchEvent, ctx) => {
-    await restoreLoopState(ctx);
-  });
 }

package/resources/pi-agent/extensions/pi-bash-live-view/package.json

@@ -40,7 +40,7 @@
     "test": "node --test tests/*.test.mjs"
   },
   "dependencies": {
-    "@mariozechner/pi-coding-agent": "^0.64.0",
+    "@mariozechner/pi-coding-agent": "^0.65.0",
     "@sinclair/typebox": "^0.34.38",
     "@xterm/headless": "^5.5.0",
     "node-pty": "^1.0.0",

package/resources/pi-agent/extensions/pi-custom-compaction/events/register-events.ts

@@ -208,16 +208,6 @@ export function registerEvents(pi: ExtensionAPI, runtime: IRuntimeServices): voi
     initializeSessionStatus(ctx, runtime);
   });
 
-  pi.on("session_switch", async(_event, ctx) => {
-    runtime.clearSessionScopedState(ctx);
-    initializeSessionStatus(ctx, runtime);
-  });
-
-  pi.on("session_fork", async(_event, ctx) => {
-    runtime.clearSessionScopedState(ctx);
-    initializeSessionStatus(ctx, runtime);
-  });
-
   pi.on("session_tree", async(_event, ctx) => {
     runtime.clearSessionScopedState(ctx);
     initializeSessionStatus(ctx, runtime);

package/resources/pi-agent/extensions/pi-custom-compaction/package.json

@@ -43,10 +43,10 @@
     "test": "tsx --test test/**/*.test.ts"
   },
   "devDependencies": {
-    "@mariozechner/pi-agent-core": "^0.64.0",
-    "@mariozechner/pi-ai": "^0.64.0",
-    "@mariozechner/pi-coding-agent": "^0.64.0",
-    "@mariozechner/pi-tui": "^0.64.0",
+    "@mariozechner/pi-agent-core": "^0.65.0",
+    "@mariozechner/pi-ai": "^0.65.0",
+    "@mariozechner/pi-coding-agent": "^0.65.0",
+    "@mariozechner/pi-tui": "^0.65.0",
     "tsx": "^4.20.5"
   },
   "pi": {

package/resources/pi-agent/extensions/pi-mcp-adapter/package.json

@@ -2,16 +2,6 @@
   "name": "pi-mcp-adapter",
   "version": "2.2.0",
   "description": "MCP (Model Context Protocol) adapter extension for Pi coding agent",
-  "type": "module",
-  "license": "MIT",
-  "author": "Nico Bailon",
-  "bin": {
-    "pi-mcp-adapter": "./cli.js"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/nicobailon/pi-mcp-adapter"
-  },
   "keywords": [
     "pi-package",
     "pi",
@@ -23,16 +13,15 @@
     "claude",
     "llm"
   ],
-  "scripts": {
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage"
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nicobailon/pi-mcp-adapter"
   },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ],
-    "video": "https://github.com/nicobailon/pi-mcp-adapter/raw/refs/heads/main/pi-mcp.mp4"
+  "license": "MIT",
+  "author": "Nico Bailon",
+  "type": "module",
+  "bin": {
+    "pi-mcp-adapter": "./cli.js"
   },
   "files": [
     "cli.js",
@@ -68,18 +57,29 @@
     "CHANGELOG.md",
     "LICENSE"
   ],
+  "scripts": {
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:watch": "vitest"
+  },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.2.2",
     "@modelcontextprotocol/sdk": "^1.25.1",
     "@sinclair/typebox": "^0.32.0",
     "zod": "^3.25.0 || ^4.0.0"
   },
-  "peerDependencies": {
-    "zod": "^3.25.0 || ^4.0.0"
-  },
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.0.0",
     "vitest": "^3.0.0"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.0 || ^4.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "video": "https://github.com/nicobailon/pi-mcp-adapter/raw/refs/heads/main/pi-mcp.mp4"
   }
 }

package/resources/pi-agent/extensions/plan.ts

@@ -511,7 +511,7 @@ function buildPlanPromptOverlay(state: IPlanSessionState): string {
   const task = state.task?.trim() || "(unknown task)";
   const model = state.planModel ? `Planning model: ${state.planModel}` : "Planning model: current session model";
   const artifact = state.artifactPath ? `Artifact path: ${state.artifactPath}` : "Artifact path: unavailable";
-  const modeLabel = state.mode === "architect" ? "Docyrus `/architect` planning mode." : "Docyrus `/plan` mode.";
+  const modeLabel = "Docyrus `/plan` mode.";
   return [
     modeLabel,
     PLAN_MODE_SYSTEM_PROMPT,
@@ -735,7 +735,115 @@ export function isPotentiallyMutatingShellCommand(command: string): boolean {
 }
 
 function buildBlockedToolReason(detail: string): string {
-  return `A planning session is active. ${detail} Exit with /end-plan or /end-architect before implementing.`;
+  return `A planning session is active. ${detail} Exit with /end-plan before implementing.`;
+}
+
+const READONLY_STATE_TYPE = "readonly-session";
+const READONLY_WIDGET_KEY = "readonly-mode";
+
+interface IReadOnlySessionState {
+  active: boolean;
+  startedAt?: string;
+}
+
+let currentReadOnlyState: IReadOnlySessionState | undefined;
+
+const READONLY_MODE_SYSTEM_PROMPT = [
+  "You are in Docyrus `/read-only` mode.",
+  "",
+  "You MUST NOT modify any files or remote state.",
+  "You can read files, search code, analyze, summarize, and answer questions.",
+  "Write and edit tools are disabled.",
+  "",
+  "Exit read-only mode with /end-read-only to resume normal operation.",
+].join("\n");
+
+function getReadOnlyState(ctx: ExtensionContext): IReadOnlySessionState | undefined {
+  let state: IReadOnlySessionState | undefined;
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type === "custom" && entry.customType === READONLY_STATE_TYPE) {
+      state = entry.data as IReadOnlySessionState | undefined;
+    }
+  }
+
+  if (state?.active) {
+    return state;
+  }
+
+  return undefined;
+}
+
+function setReadOnlyWidget(ctx: ExtensionContext, state: IReadOnlySessionState | undefined): void {
+  if (!ctx.hasUI) {
+    return;
+  }
+
+  if (!state?.active) {
+    ctx.ui.setWidget(READONLY_WIDGET_KEY, undefined);
+    return;
+  }
+
+  ctx.ui.setWidget(READONLY_WIDGET_KEY, (_tui, theme) => {
+    const lines = [
+      theme.fg("accent", theme.bold("Read-only mode active")),
+      theme.fg("muted", "Write & edit tools disabled"),
+      theme.fg("warning", "Exit with /end-read-only"),
+    ];
+
+    const container = new Container();
+    container.addChild(new DynamicBorder((value: string) => theme.fg("accent", value)));
+    container.addChild(new Text(lines.join("\n"), 0, 0));
+    return container;
+  });
+}
+
+function buildBlockedReadOnlyReason(detail: string): string {
+  return `Read-only mode is active. ${detail} Exit with /end-read-only to resume editing.`;
+}
+
+function handleToolCallDuringReadOnly(event: ToolCallEvent, ctx: ExtensionContext): { block: boolean; reason: string } | undefined {
+  if (!getReadOnlyState(ctx)?.active) {
+    return undefined;
+  }
+
+  if (event.toolName === "edit" || event.toolName === "write") {
+    return {
+      block: true,
+      reason: buildBlockedReadOnlyReason(`The ${event.toolName} tool is disabled in read-only mode.`),
+    };
+  }
+
+  if (event.toolName === "bash" && isRecord(event.input) && typeof event.input.command === "string") {
+    if (isPotentiallyMutatingShellCommand(event.input.command)) {
+      return {
+        block: true,
+        reason: buildBlockedReadOnlyReason(`Mutating bash commands are disabled in read-only mode (${event.input.command}).`),
+      };
+    }
+  }
+
+  if (event.toolName === "todo" && isRecord(event.input) && typeof event.input.action === "string") {
+    if (shouldBlockTodoAction(event.input.action)) {
+      return {
+        block: true,
+        reason: buildBlockedReadOnlyReason(`Todo action "${event.input.action}" is disabled in read-only mode.`),
+      };
+    }
+  }
+
+  return undefined;
+}
+
+function handleUserBashDuringReadOnly(event: UserBashEvent, ctx: ExtensionContext) {
+  if (!getReadOnlyState(ctx)?.active) {
+    return undefined;
+  }
+
+  if (!isPotentiallyMutatingShellCommand(event.command)) {
+    return undefined;
+  }
+
+  return buildBlockedUserBashResult(`Mutating shell commands are disabled in read-only mode (${event.command}).`);
 }
 
 function buildBlockedUserBashResult(detail: string) {
@@ -900,7 +1008,11 @@ export async function startPlanningWorkflow(params: IPlanningStartParams): Promi
   }
 
   try {
-    await ensureArtifactFile(artifactPath, params.task ?? mode);
+    if (mode === "architect") {
+      await fs.mkdir(artifactPath, { recursive: true });
+    } else {
+      await ensureArtifactFile(artifactPath, params.task ?? mode);
+    }
   } catch (error) {
     if (ctx.hasUI) {
       const message = error instanceof Error ? error.message : String(error);
@@ -968,32 +1080,13 @@ export async function startPlanningWorkflow(params: IPlanningStartParams): Promi
 
   if (ctx.hasUI) {
     const profileHint = profileName ? ` (profile: ${profileName})` : "";
-    const modeLabel = mode === "architect" ? "Architect mode" : "Plan mode";
-    ctx.ui.notify(`${modeLabel} active${profileHint}. Writing updates to ${artifactPath}`, "info");
+    ctx.ui.notify(`Plan mode active${profileHint}. Writing updates to ${artifactPath}`, "info");
   }
 
   pi.sendUserMessage(initialPrompt);
   return true;
 }
 
-async function planHandler(pi: ExtensionAPI, ctx: ExtensionCommandContext, args: string): Promise<void> {
-  const task = parsePlanTask(args) ?? undefined;
-  const artifactPath = createPlanArtifactPath({
-    cwd: ctx.cwd,
-    task: task ?? "plan",
-    date: new Date(),
-  });
-
-  await startPlanningWorkflow({
-    pi,
-    ctx,
-    mode: "plan",
-    task,
-    artifactPath,
-    initialPrompt: buildInitialPlanPrompt(task),
-  });
-}
-
 export async function endPlanningWorkflow(pi: ExtensionAPI, ctx: ExtensionCommandContext): Promise<void> {
   const state = getPlanState(ctx);
   if (!state?.active || !state.originId) {
@@ -1208,13 +1301,6 @@ function handleUserBashDuringPlan(event: UserBashEvent, ctx: ExtensionContext) {
 }
 
 export default function planExtension(pi: ExtensionAPI) {
-  pi.registerCommand("plan", {
-    description: "Start a planning-only branch with an optional dedicated planning model",
-    handler: async(args, ctx) => {
-      await planHandler(pi, ctx, args);
-    },
-  });
-
   pi.registerCommand("end-plan", {
     description: "Leave plan mode, summarize the plan branch, and return to the original branch",
     handler: async(_args, ctx) => {
@@ -1222,37 +1308,85 @@ export default function planExtension(pi: ExtensionAPI) {
     },
   });
 
-  pi.registerCommand("end-architect", {
-    description: "Leave architect mode, summarize the architect branch, and return to the original branch",
+  pi.registerCommand("plan-policy", {
+    description: "Show effective planning-model policy and the resolved planning model",
     handler: async(_args, ctx) => {
-      await endPlanningWorkflow(pi, ctx);
+      await planPolicyHandler(pi, ctx);
     },
   });
 
-  pi.registerCommand("plan-policy", {
-    description: "Show effective planning-model policy and the resolved planning model",
+  pi.registerCommand("read-only", {
+    description: "Enter read-only mode — write and edit tools are disabled, analysis and search remain available",
     handler: async(_args, ctx) => {
-      await planPolicyHandler(pi, ctx);
+      if (getReadOnlyState(ctx)?.active) {
+        if (ctx.hasUI) {
+          ctx.ui.notify("Read-only mode is already active. Exit with /end-read-only first.", "warning");
+        }
+        return;
+      }
+
+      const state: IReadOnlySessionState = {
+        active: true,
+        startedAt: new Date().toISOString(),
+      };
+      pi.appendEntry(READONLY_STATE_TYPE, state);
+      currentReadOnlyState = state;
+      setReadOnlyWidget(ctx, state);
+
+      if (ctx.hasUI) {
+        ctx.ui.notify("Read-only mode active. Write & edit tools disabled. Exit with /end-read-only.", "info");
+      }
+    },
+  });
+
+  pi.registerCommand("end-read-only", {
+    description: "Exit read-only mode and resume normal operation",
+    handler: async(_args, ctx) => {
+      if (!getReadOnlyState(ctx)?.active) {
+        if (ctx.hasUI) {
+          ctx.ui.notify("No active read-only session was found.", "info");
+        }
+        return;
+      }
+
+      pi.appendEntry(READONLY_STATE_TYPE, { active: false });
+      currentReadOnlyState = undefined;
+      setReadOnlyWidget(ctx, undefined);
+
+      if (ctx.hasUI) {
+        ctx.ui.notify("Read-only mode ended. Normal operation resumed.", "info");
+      }
     },
   });
 
   pi.on("before_agent_start", (event, ctx) => {
-    const state = getPlanState(ctx);
-    if (!state?.active) {
+    const planState = getPlanState(ctx);
+    const readOnlyState = getReadOnlyState(ctx);
+    const overlays: string[] = [];
+
+    if (planState?.active) {
+      overlays.push(buildPlanPromptOverlay(planState));
+    }
+
+    if (readOnlyState?.active) {
+      overlays.push(READONLY_MODE_SYSTEM_PROMPT);
+    }
+
+    if (overlays.length === 0) {
       return;
     }
 
     return {
-      systemPrompt: [event.systemPrompt, buildPlanPromptOverlay(state)].filter(Boolean).join("\n\n"),
+      systemPrompt: [event.systemPrompt, ...overlays].filter(Boolean).join("\n\n"),
     };
   });
 
   pi.on("tool_call", (event, ctx) => {
-    return handleToolCallDuringPlan(event, ctx);
+    return handleToolCallDuringPlan(event, ctx) ?? handleToolCallDuringReadOnly(event, ctx);
   });
 
   pi.on("user_bash", (event, ctx) => {
-    return handleUserBashDuringPlan(event, ctx);
+    return handleUserBashDuringPlan(event, ctx) ?? handleUserBashDuringReadOnly(event, ctx);
   });
 
   pi.on("agent_end", async(event, ctx) => {
@@ -1275,18 +1409,22 @@ export default function planExtension(pi: ExtensionAPI) {
 
   pi.on("session_start", async(_event, ctx) => {
     await syncPlanState(pi, ctx);
-  });
-
-  pi.on("session_switch", async(_event, ctx) => {
-    await syncPlanState(pi, ctx);
+    const readOnlyState = getReadOnlyState(ctx);
+    currentReadOnlyState = readOnlyState;
+    setReadOnlyWidget(ctx, readOnlyState);
   });
 
   pi.on("session_tree", async(_event, ctx) => {
     await syncPlanState(pi, ctx);
+    const readOnlyState = getReadOnlyState(ctx);
+    currentReadOnlyState = readOnlyState;
+    setReadOnlyWidget(ctx, readOnlyState);
   });
 
   pi.on("session_shutdown", async(_event, ctx) => {
     currentPlanState = undefined;
     setPlanWidget(ctx, undefined);
+    currentReadOnlyState = undefined;
+    setReadOnlyWidget(ctx, undefined);
   });
 }

package/resources/pi-agent/extensions/prompt-editor.ts

@@ -1267,24 +1267,6 @@ export default function(pi: ExtensionAPI) {
     applyEditor(pi, ctx);
   });
 
-  pi.on("session_switch", async(_event, ctx) => {
-    lastObservedModel = { provider: ctx.model?.provider, modelId: ctx.model?.id };
-    await ensureRuntime(pi, ctx);
-    customOverlay = null;
-
-    const inferred = inferModeFromSelection(ctx, pi, runtime.data);
-    if (inferred) {
-      runtime.currentMode = inferred;
-      runtime.lastRealMode = inferred;
-    } else {
-      runtime.currentMode = CUSTOM_MODE_NAME;
-      customOverlay = getCurrentSelectionSpec(pi, ctx);
-    }
-
-    applyEditor(pi, ctx);
-  });
-
-
   pi.on("model_select", async(event: ModelSelectEvent, ctx) => {
 		// Always track the last observed model for overlay/store correctness.
     lastObservedModel = { provider: event.model.provider, modelId: event.model.id };

package/resources/pi-agent/extensions/prompt-url-widget.ts

@@ -108,10 +108,6 @@ export default function promptUrlWidgetExtension(pi: ExtensionAPI) {
     });
   });
 
-  pi.on("session_switch", async(_event, ctx) => {
-    rebuildFromSession(ctx);
-  });
-
   const getUserText = (content: string | { type: string; text?: string }[] | undefined): string => {
     if (!content) {return "";}
     if (typeof content === "string") {return content;}

package/resources/pi-agent/extensions/review.ts

@@ -938,10 +938,6 @@ export default function reviewExtension(pi: ExtensionAPI) {
     applyAllReviewState(ctx);
   });
 
-  pi.on("session_switch", (_event, ctx) => {
-    applyAllReviewState(ctx);
-  });
-
   pi.on("session_tree", (_event, ctx) => {
     applyAllReviewState(ctx);
   });

package/resources/pi-agent/prompts/agent-system.md

@@ -9,6 +9,7 @@ Core behavior:
 - Start by inspecting real tenant state before making claims about apps, data sources, users, environments, auth state, or API shape.
 - If the repository contains `docyrus/knowledge/`, use `docyrus knowledge search`, `docyrus knowledge section`, and `docyrus knowledge expand` before broader repo exploration.
 - When `docyrus/knowledge/` exists, keep it updated and finish local work with `docyrus knowledge check`.
+- If the repository contains `docyrus/project-plan/project-plan.json`, use `docyrus project-plan show` to understand current work scope and `docyrus project-plan get-task` to inspect individual tasks before starting work. Update task status with `docyrus project-plan set-task-status` as work progresses.
 - Use the installed Docyrus skills as your command and workflow reference.
 - Be careful with tenant-scoped mutations. Confirm real identifiers and current context before changing state.
 - Treat auth files, tokens, and `.docyrus` contents as sensitive.
@@ -24,4 +25,15 @@ Docyrus concepts you should understand and use accurately:
 - discover commands and tenant OpenAPI inspection
 - raw API access via the CLI when needed
 
+Project plan system:
+
+The project-plan is a repo-tracked work graph stored at `docyrus/project-plan/project-plan.json`. It organizes work into sections (anchored to knowledge graph section IDs), features, and tasks. A derived `PROJECT_PLAN.md` is always kept in sync.
+
+- `docyrus project-plan show` — view the full hierarchy with statuses
+- `docyrus project-plan get-task --taskId <id>` — inspect a task and its linked local subtasks
+- `docyrus project-plan set-task-status --taskId <id> --status <status>` — advance task status (`planned` → `in_progress` → `done`, or `blocked`)
+- `docyrus project-plan check` — validate that all section references and task fields are consistent
+
+When working on a repo that has a project plan, read it at the start of a session to understand scope and priorities. Update task status as work progresses and after it completes.
+
 You are not a generic shell assistant first. You are a Docyrus-first operator that happens to have local tools.

package/resources/pi-agent/prompts/coder-system.md

@@ -20,6 +20,7 @@ Core behavior:
 - Use the local `docyrus` CLI for Docyrus platform state, tenant context, schema inspection, app and data-source operations, API discovery, and data verification.
 - If the repository contains `docyrus/knowledge/`, use `docyrus knowledge search`, `docyrus knowledge section`, and `docyrus knowledge expand` before coding so you start from documented repo intent rather than only source inspection.
 - When `docyrus/knowledge/` exists, keep it in sync with behavior changes and finish with `docyrus knowledge check`.
+- If the repository contains `docyrus/project-plan/project-plan.json`, read it at session start with `docyrus project-plan show` to understand current priorities and work scope. Update task status with `docyrus project-plan set-task-status` as work begins and finishes. Use `docyrus project-plan create-linked-todo` to break agent-assigned tasks into local subtasks when needed.
 - Prefer `--json` whenever command output needs to be parsed, compared, or fed back into reasoning.
 - Start from real state before making claims about apps, data sources, users, fields, enums, environments, auth state, API shape, or deployment context.
 - Distinguish clearly between local code changes and remote Docyrus platform mutations.
@@ -69,6 +70,23 @@ Schema-first workflow for new Docyrus-backed apps and major features:
 - After schema changes, verify the resulting metadata and runtime behavior with `docyrus ds get`, `docyrus ds list`, and `docyrus discover`.
 - When the project uses generated collections or codegen from the OpenAPI spec, resync or regenerate those artifacts after schema changes if the repo workflow requires it.
 
+Project plan system:
+
+The project-plan is a repo-tracked work graph stored at `docyrus/project-plan/project-plan.json` with a derived `PROJECT_PLAN.md` always kept in sync. Work is organized into sections (anchored to knowledge graph section IDs), features, and tasks. Tasks have a type (`new-implementation`, `bug-fix`, `api-test`, `browser-automation-test`, `work`), an assignee (`agent` or `user`), a status (`planned`, `in_progress`, `blocked`, `done`), and optional acceptance criteria.
+
+Key commands:
+
+- `docyrus project-plan show` — view the full hierarchy with feature and task statuses
+- `docyrus project-plan get-task --taskId <id>` — inspect a specific task and its linked local subtasks
+- `docyrus project-plan set-task-status --taskId <id> --status <status>` — advance task status
+- `docyrus project-plan create-linked-todo --taskId <id> --title <title> --body <body>` — create a local `.pi/todos` subtask linked to an agent-assigned canonical task
+- `docyrus project-plan upsert-feature --sectionId <id> --title <title> --slug <slug>` — create or update a feature
+- `docyrus project-plan upsert-task --featureId <id> --title <title> --type <type> --assignee <assignee>` — create or update a task
+- `docyrus project-plan check` — validate section references and graph integrity
+- `docyrus project-plan ensure` — initialize the graph from knowledge sections if it does not yet exist
+
+Workflow: read the project plan at session start → set relevant tasks to `in_progress` before beginning → create linked todos for complex implementation tasks → set tasks to `done` after work is verified.
+
 Docyrus CLI workflows you should rely on:
 
 - Use `docyrus auth who`, `docyrus auth accounts ...`, `docyrus auth tenants ...`, and `docyrus env ...` to confirm active identity, tenant, and environment.