@docyrus/docyrus 0.0.45 → 0.0.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docyrus/docyrus",
-  "version": "0.0.45",
+  "version": "0.0.48",
   "private": false,
   "description": "Docyrus API CLI",
   "main": "./main.js",

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

@@ -1,7 +1,6 @@
 import { execFile } from "node:child_process";
 import { existsSync } from "node:fs";
 import { dirname, join, relative, resolve as resolvePath } from "node:path";
-import { Type } from "@sinclair/typebox";
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
@@ -10,17 +9,14 @@ import type {
   TurnEndEvent,
 } from "@mariozechner/pi-coding-agent";
 import { getMarkdownTheme, keyHint } from "@mariozechner/pi-coding-agent";
-import type { Theme } from "@mariozechner/pi-tui";
 import { Box, Markdown, Text } from "@mariozechner/pi-tui";
 
-const PREVIEW_LINES = 4;
 const KNOWLEDGE_STATE_TYPE = "knowledge-session";
 const KNOWLEDGE_WIDGET_KEY = "knowledge";
 const KNOWLEDGE_REMINDER_INTERVAL_MS = 10 * 60 * 1000;
 
 type Scope = "local" | "global";
 type KnowledgeSeverity = "ok" | "watch" | "drift" | "critical";
-type KnowledgeToolName = "read" | "write" | "edit";
 
 interface ICliEnvironment {
   executable: string;
@@ -156,34 +152,6 @@ async function runCliJson<TValue>(environment: ICliEnvironment, args: string[],
   };
 }
 
-function collapsibleResult(
-  result: { content: Array<{ type: string; text?: string }> },
-  options: { expanded: boolean; isPartial: boolean },
-  theme: Theme,
-) {
-  const text = result.content?.[0]?.type === "text" ? (result.content[0] as { type: "text"; text: string }).text : "";
-  if (!text) {
-    return new Text(theme.fg("dim", "(empty)"), 0, 0);
-  }
-  if (options.isPartial) {
-    return new Text(theme.fg("dim", "…"), 0, 0);
-  }
-
-  const markdownTheme = getMarkdownTheme();
-  if (options.expanded) {
-    return new Markdown(text, 0, 0, markdownTheme);
-  }
-
-  const lines = text.split("\n");
-  if (lines.length <= PREVIEW_LINES) {
-    return new Markdown(text, 0, 0, markdownTheme);
-  }
-
-  const preview = lines.slice(0, PREVIEW_LINES).join("\n");
-  const remaining = lines.length - PREVIEW_LINES;
-  const hint = keyHint("expandTools", "to expand");
-  return new Text(`${preview}\n${theme.fg("dim", `… ${remaining} more lines (${hint})`)}`, 0, 0);
-}
 
 function normalizeTrackedPath(pathValue: string, cwd: string): string {
   const trimmed = pathValue.trim();
@@ -419,36 +387,6 @@ function trackToolResult(pi: ExtensionAPI, ctx: ExtensionContext, event: ToolRes
   updateKnowledgeWidget(ctx, next);
 }
 
-function registerKnowledgeTool(
-  pi: ExtensionAPI,
-  name: string,
-  label: string,
-  description: string,
-  argsBuilder: (params: Record<string, unknown>) => string[],
-  schema: object,
-  preview: (args: Record<string, unknown>, theme: Theme) => string,
-) {
-  pi.registerTool({
-    name,
-    label,
-    description,
-    promptSnippet: description,
-    parameters: schema,
-    async execute(_id, params) {
-      const environment = readCliEnvironment();
-      const result = await runCli(environment, argsBuilder(params as Record<string, unknown>), process.cwd(), false);
-      const text = result.stdout.trim() || summarizeFailure(result);
-      return {
-        content: [{ type: "text", text }],
-        ...(result.code && result.code !== 0 ? { isError: true } : {}),
-      };
-    },
-    renderCall(args, theme) {
-      return new Text(preview(args as Record<string, unknown>, theme), 0, 0);
-    },
-    renderResult: collapsibleResult,
-  });
-}
 
 function parseCommandArgs(rawArgs: string): string | null {
   const trimmed = rawArgs.trim();
@@ -456,97 +394,6 @@ function parseCommandArgs(rawArgs: string): string | null {
 }
 
 export default function(pi: ExtensionAPI) {
-  registerKnowledgeTool(
-    pi,
-    "docyrus_knowledge_search",
-    "knowledge search",
-    "Semantic search across docyrus/knowledge sections",
-    (params) => {
-      const args = ["knowledge", "search"];
-      if (typeof params.query === "string" && params.query.trim().length > 0) {
-        args.push(params.query);
-      }
-      if (typeof params.limit === "number") {
-        args.push("--limit", String(params.limit));
-      }
-      return args;
-    },
-    Type.Object({
-      query: Type.String({ description: "Search query in natural language" }),
-      limit: Type.Optional(Type.Number({ description: "Maximum matches", default: 5 })),
-    }),
-    (args, theme) => `${theme.fg("toolTitle", theme.bold("knowledge search "))}${theme.fg("dim", `"${String(args.query || "")}"`)}`,
-  );
-
-  registerKnowledgeTool(
-    pi,
-    "docyrus_knowledge_section",
-    "knowledge section",
-    "Show a full knowledge section with refs and backlinks",
-    (params) => ["knowledge", "section", String(params.query || "")],
-    Type.Object({
-      query: Type.String({ description: "Section id or heading query" }),
-    }),
-    (args, theme) => `${theme.fg("toolTitle", theme.bold("knowledge section "))}${theme.fg("dim", `"${String(args.query || "")}"`)}`,
-  );
-
-  registerKnowledgeTool(
-    pi,
-    "docyrus_knowledge_locate",
-    "knowledge locate",
-    "Find knowledge sections by exact, short, or fuzzy match",
-    (params) => ["knowledge", "locate", String(params.query || "")],
-    Type.Object({
-      query: Type.String({ description: "Section id or heading query" }),
-    }),
-    (args, theme) => `${theme.fg("toolTitle", theme.bold("knowledge locate "))}${theme.fg("dim", `"${String(args.query || "")}"`)}`,
-  );
-
-  registerKnowledgeTool(
-    pi,
-    "docyrus_knowledge_refs",
-    "knowledge refs",
-    "Find markdown and code references to a knowledge section or source symbol",
-    (params) => {
-      const args = ["knowledge", "refs", String(params.query || "")];
-      if (typeof params.scope === "string" && params.scope.length > 0) {
-        args.push("--scope", params.scope);
-      }
-      return args;
-    },
-    Type.Object({
-      query: Type.String({ description: "Section id, source file, or source symbol query" }),
-      scope: Type.Optional(Type.String({ description: "md, code, or md+code" })),
-    }),
-    (args, theme) => `${theme.fg("toolTitle", theme.bold("knowledge refs "))}${theme.fg("dim", `"${String(args.query || "")}"`)}`,
-  );
-
-  registerKnowledgeTool(
-    pi,
-    "docyrus_knowledge_expand",
-    "knowledge expand",
-    "Expand [[refs]] into resolved section context",
-    (params) => ["knowledge", "expand", String(params.text || "")],
-    Type.Object({
-      text: Type.String({ description: "Text containing [[refs]]" }),
-    }),
-    (args, theme) => {
-      const text = String(args.text || "");
-      const preview = text.length > 60 ? `${text.slice(0, 60)}…` : text;
-      return `${theme.fg("toolTitle", theme.bold("knowledge expand "))}${theme.fg("dim", `"${preview}"`)}`;
-    },
-  );
-
-  registerKnowledgeTool(
-    pi,
-    "docyrus_knowledge_check",
-    "knowledge check",
-    "Validate the repo knowledge graph",
-    () => ["knowledge", "check"],
-    Type.Object({}),
-    (_args, theme) => `${theme.fg("toolTitle", theme.bold("knowledge check"))}`,
-  );
-
   pi.registerCommand("knowledge-init", {
     description: "Bootstrap docyrus/knowledge from the current repo and install hook guidance",
     handler: async(rawArgs, ctx: ExtensionCommandContext) => {

package/resources/pi-agent/extensions/server-auto-commit.ts

@@ -0,0 +1,105 @@
+/**
+ * Server Auto-Commit Extension (server-only)
+ *
+ * Automatically commits and pushes all changes after each agent turn
+ * when auto-commit is enabled for the session.
+ *
+ * Enable at session creation:
+ *   POST /api/sessions  { "autoCommit": true }
+ *
+ * Toggle on an active session:
+ *   PATCH /api/sessions/:sessionId/config  { "autoCommit": true|false }
+ *
+ * Check current config:
+ *   GET /api/sessions/:sessionId/config
+ *
+ * Config is stored at: <agentDir>/session-config/<sessionId>.json
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { execFile as execFileCb } from "node:child_process";
+import { promises as fs } from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { promisify } from "node:util";
+
+const execFile = promisify(execFileCb);
+
+interface IExecResult {
+  stdout: string;
+  stderr: string;
+  code: number;
+}
+
+async function runGit(args: string[], cwd: string): Promise<IExecResult> {
+  try {
+    const result = await execFile("git", args, { cwd });
+    return { stdout: result.stdout, stderr: result.stderr, code: 0 };
+  } catch (error: unknown) {
+    const err = error as { stdout?: string; stderr?: string; code?: number };
+    return {
+      stdout: err.stdout ?? "",
+      stderr: err.stderr ?? "",
+      code: err.code ?? 1,
+    };
+  }
+}
+
+function expandUserPath(p: string): string {
+  if (p === "~") {return os.homedir();}
+  if (p.startsWith("~/")) {return path.join(os.homedir(), p.slice(2));}
+  return p;
+}
+
+function getScopedAgentDir(): string {
+  for (const key of ["PI_CODING_AGENT_DIR", "TAU_CODING_AGENT_DIR"]) {
+    const value = process.env[key]?.trim();
+    if (value) {return expandUserPath(value);}
+  }
+  return path.join(os.homedir(), ".pi", "agent");
+}
+
+async function isAutoCommitEnabled(sessionId: string): Promise<boolean> {
+  try {
+    const configFile = path.join(getScopedAgentDir(), "session-config", `${sessionId}.json`);
+    const raw = await fs.readFile(configFile, "utf-8");
+    return (JSON.parse(raw) as { autoCommit?: boolean }).autoCommit === true;
+  } catch {
+    return false;
+  }
+}
+
+export default function(_pi: ExtensionAPI) {
+  _pi.on("agent_end", async(_event, ctx) => {
+    const sessionId = ctx.sessionManager.getSessionId();
+    if (!(await isAutoCommitEnabled(sessionId))) {return;}
+
+    const status = await runGit(["status", "--porcelain"], ctx.cwd);
+    if (status.code !== 0 || !status.stdout.trim()) {return;}
+
+    const timestamp = new Date().toISOString();
+
+    const add = await runGit(["add", "-A"], ctx.cwd);
+    if (add.code !== 0) {
+      process.stderr.write(`[server-auto-commit] git add failed: ${add.stderr}\n`);
+      return;
+    }
+
+    const commit = await runGit(
+      ["commit", "--no-verify", "-m", `auto: agent turn ${timestamp}`],
+      ctx.cwd,
+    );
+    if (commit.code !== 0) {
+      process.stderr.write(`[server-auto-commit] git commit failed: ${commit.stderr}\n`);
+      return;
+    }
+
+    const push = await runGit(["push", "--no-verify"], ctx.cwd);
+    if (push.code !== 0) {
+      process.stderr.write(`[server-auto-commit] git push failed: ${push.stderr}\n`);
+      return;
+    }
+
+    process.stderr.write(`[server-auto-commit] committed and pushed at ${timestamp}\n`);
+  });
+}

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

@@ -1,21 +1,8 @@
 import { execFile } from "node:child_process";
-import { StringEnum } from "@mariozechner/pi-ai";
-import { Type } from "@sinclair/typebox";
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
 } from "@mariozechner/pi-coding-agent";
-import type { Theme } from "@mariozechner/pi-tui";
-import { Text } from "@mariozechner/pi-tui";
-
-type ITasksAction =
-  | "show"
-  | "get"
-  | "create-section"
-  | "create-feature"
-  | "create-task"
-  | "set-status"
-  | "create-linked-todo";
 
 interface ICliEnvironment {
   executable: string;
@@ -70,28 +57,6 @@ interface IProjectPlanShowPayload {
   };
 }
 
-const TaskParams = Type.Object({
-  action: StringEnum([
-    "show",
-    "get",
-    "create-section",
-    "create-feature",
-    "create-task",
-    "set-status",
-    "create-linked-todo",
-  ] as const),
-  taskId: Type.Optional(Type.String({ description: "Canonical task id" })),
-  featureId: Type.Optional(Type.String({ description: "Canonical feature id" })),
-  sectionId: Type.Optional(Type.String({ description: "Project plan section id" })),
-  title: Type.Optional(Type.String({ description: "Section, feature, or task title" })),
-  summary: Type.Optional(Type.String({ description: "Section, feature, or task summary" })),
-  slug: Type.Optional(Type.String({ description: "Section or feature slug" })),
-  type: Type.Optional(Type.String({ description: "Task type" })),
-  assignee: Type.Optional(Type.String({ description: "Task assignee" })),
-  status: Type.Optional(Type.String({ description: "Task status" })),
-  acceptanceCriteria: Type.Optional(Type.Array(Type.String({ description: "Acceptance criterion" }))),
-});
-
 function readCliEnvironment(env: NodeJS.ProcessEnv = process.env): ICliEnvironment {
   const executable = env.DOCYRUS_CLI_EXECUTABLE?.trim();
   const entryPath = env.DOCYRUS_CLI_ENTRY?.trim();
@@ -326,197 +291,6 @@ async function tasksCommandHandler(pi: ExtensionAPI, ctx: ExtensionCommandContex
 }
 
 export default function tasksExtension(pi: ExtensionAPI) {
-  pi.registerTool({
-    name: "project_task",
-    label: "Project Task",
-    description: "Manage the canonical repo-tracked project-plan graph and linked local subtasks.",
-    parameters: TaskParams,
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const environment = readCliEnvironment();
-      const action = params.action as ITasksAction;
-
-      switch (action) {
-        case "show": {
-          const payload = await runCliJson<IProjectPlanShowPayload>(environment, ["project-plan", "show"], ctx.cwd);
-          const text = formatHierarchySummary(payload);
-          return {
-            content: [{ type: "text", text }],
-            details: payload,
-          };
-        }
-
-        case "get": {
-          if (!params.taskId) {
-            return {
-              content: [{ type: "text", text: "taskId required" }],
-              isError: true,
-            };
-          }
-          const payload = await runCliJson<Record<string, unknown>>(environment, [
-            "project-plan",
-            "get-task",
-            "--taskId",
-            String(params.taskId),
-          ], ctx.cwd);
-          return {
-            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
-            details: payload,
-          };
-        }
-
-        case "create-section": {
-          if (!params.title) {
-            return {
-              content: [{ type: "text", text: "title required" }],
-              isError: true,
-            };
-          }
-          const args = [
-            "project-plan",
-            "upsert-section",
-            "--title",
-            String(params.title),
-          ];
-          if (params.slug) {
-            args.push("--slug", String(params.slug));
-          }
-          if (params.summary) {
-            args.push("--summary", String(params.summary));
-          }
-          const payload = await runCliJson<Record<string, unknown>>(environment, args, ctx.cwd);
-          return {
-            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
-            details: payload,
-          };
-        }
-
-        case "create-feature": {
-          if (!params.sectionId || !params.title) {
-            return {
-              content: [{ type: "text", text: "sectionId and title required" }],
-              isError: true,
-            };
-          }
-          const args = [
-            "project-plan",
-            "upsert-feature",
-            "--sectionId",
-            String(params.sectionId),
-            "--title",
-            String(params.title),
-          ];
-          if (params.slug) {
-            args.push("--slug", String(params.slug));
-          }
-          if (params.summary) {
-            args.push("--summary", String(params.summary));
-          }
-          const payload = await runCliJson<Record<string, unknown>>(environment, args, ctx.cwd);
-          return {
-            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
-            details: payload,
-          };
-        }
-
-        case "create-task": {
-          if (!params.featureId || !params.title || !params.type || !params.assignee) {
-            return {
-              content: [{ type: "text", text: "featureId, title, type, and assignee required" }],
-              isError: true,
-            };
-          }
-          const args = [
-            "project-plan",
-            "upsert-task",
-            "--featureId",
-            String(params.featureId),
-            "--title",
-            String(params.title),
-            "--type",
-            String(params.type),
-            "--assignee",
-            String(params.assignee),
-          ];
-          if (params.sectionId) {
-            args.push("--sectionId", String(params.sectionId));
-          }
-          if (params.summary) {
-            args.push("--summary", String(params.summary));
-          }
-          if (params.status) {
-            args.push("--status", String(params.status));
-          }
-          if (Array.isArray(params.acceptanceCriteria) && params.acceptanceCriteria.length > 0) {
-            args.push("--acceptanceCriteria", JSON.stringify(params.acceptanceCriteria));
-          }
-          const payload = await runCliJson<Record<string, unknown>>(environment, args, ctx.cwd);
-          return {
-            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
-            details: payload,
-          };
-        }
-
-        case "set-status": {
-          if (!params.taskId || !params.status) {
-            return {
-              content: [{ type: "text", text: "taskId and status required" }],
-              isError: true,
-            };
-          }
-          const payload = await runCliJson<Record<string, unknown>>(environment, [
-            "project-plan",
-            "set-task-status",
-            "--taskId",
-            String(params.taskId),
-            "--status",
-            String(params.status),
-          ], ctx.cwd);
-          return {
-            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
-            details: payload,
-          };
-        }
-
-        case "create-linked-todo": {
-          if (!params.taskId) {
-            return {
-              content: [{ type: "text", text: "taskId required" }],
-              isError: true,
-            };
-          }
-          const args = [
-            "project-plan",
-            "create-linked-todo",
-            "--taskId",
-            String(params.taskId),
-          ];
-          if (params.title) {
-            args.push("--title", String(params.title));
-          }
-          if (params.summary) {
-            args.push("--body", String(params.summary));
-          }
-          const payload = await runCliJson<Record<string, unknown>>(environment, args, ctx.cwd);
-          return {
-            content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
-            details: payload,
-          };
-        }
-      }
-    },
-    renderCall(args, theme: Theme) {
-      return new Text(
-        `${theme.fg("toolTitle", theme.bold("project task "))}${theme.fg("muted", String(args.action || "show"))}`,
-        0,
-        0,
-      );
-    },
-    renderResult(result, _options, _theme) {
-      const text = result.content[0];
-      return new Text(text?.type === "text" ? text.text : "", 0, 0);
-    },
-  });
-
   pi.registerCommand("tasks", {
     description: "Browse project-plan sections, features, and tasks",
     handler: async(args, ctx) => {

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

@@ -27,13 +27,18 @@ Docyrus concepts you should understand and use accurately:
 
 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 (standalone groupings like phases or feature areas), features, and tasks. A derived `PROJECT_PLAN.md` is always kept in sync. Features are also synced into the knowledge base features document when it exists.
+The project-plan is a repo-tracked work graph stored at `docyrus/project-plan/project-plan.json`. It organizes work into sections (standalone groupings like phases or feature areas), features, and tasks. A derived `PROJECT_PLAN.md` is always kept in sync. Features are also synced into the knowledge base features document when it exists. Sections, features, and tasks each support an optional integer `order` field that controls display sequence (lower = first; entities without an order sort after ordered ones).
 
-- `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 show --json` — view the full hierarchy with statuses; returns `{ graph, hierarchy }`
+- `docyrus project-plan get-task --taskId <id> --json` — 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 upsert-section --title <title>` — create or update a section
-- `docyrus project-plan check` — validate that all section references and task fields are consistent
+- `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-section --title <title> [--id <id>] [--slug <slug>] [--summary <summary>] [--order <n>]` — create or update a section
+- `docyrus project-plan upsert-feature --sectionId <id> --title <title> [--featureId <id>] [--slug <slug>] [--summary <summary>] [--order <n>]` — create or update a feature
+- `docyrus project-plan upsert-task --featureId <id> --title <title> --type <type> --assignee <assignee> [--taskId <id>] [--status <status>] [--summary <summary>] [--acceptanceCriteria <json-array>] [--order <n>]` — create or update a task
+- `docyrus project-plan set-order --sectionId|--featureId|--taskId <id> --order <n>` — set display order on an existing entity (lower = first; unordered items sort last)
+- `docyrus project-plan check` — validate section references and graph integrity
+- `docyrus project-plan ensure` — initialize an empty project-plan graph if it does not yet exist
 
 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.
 

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

@@ -72,17 +72,18 @@ Schema-first workflow for new Docyrus-backed apps and major features:
 
 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 (standalone groupings like phases or feature areas), features, and tasks. Features are also synced into the knowledge base features document when it exists. 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.
+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 (standalone groupings like phases or feature areas), features, and tasks. Features are also synced into the knowledge base features document when it exists. 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. Sections, features, and tasks each support an optional integer `order` field that controls display sequence (lower = first; entities without an order sort after ordered ones).
 
 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-section --title <title> --slug <slug> --summary <summary>` — create or update a section
-- `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 show --json` — view the full hierarchy with feature and task statuses; returns `{ graph, hierarchy }`
+- `docyrus project-plan get-task --taskId <id> --json` — inspect a specific 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 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-section --title <title> [--id <id>] [--slug <slug>] [--summary <summary>] [--order <n>]` — create or update a section
+- `docyrus project-plan upsert-feature --sectionId <id> --title <title> [--featureId <id>] [--slug <slug>] [--summary <summary>] [--order <n>]` — create or update a feature
+- `docyrus project-plan upsert-task --featureId <id> --title <title> --type <type> --assignee <assignee> [--taskId <id>] [--status <status>] [--summary <summary>] [--acceptanceCriteria <json-array>] [--order <n>]` — create or update a task
+- `docyrus project-plan set-order --sectionId|--featureId|--taskId <id> --order <n>` — set display order on an existing entity (lower = first; unordered items sort last)
 - `docyrus project-plan check` — validate section references and graph integrity
 - `docyrus project-plan ensure` — initialize an empty project-plan graph if it does not yet exist