@docyrus/docyrus 0.0.42 → 0.0.44

package/package.json

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

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/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 planPolicyHandler(pi, ctx);
+    },
+  });
+
+  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 endPlanningWorkflow(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("plan-policy", {
-    description: "Show effective planning-model policy and the resolved planning model",
+  pi.registerCommand("end-read-only", {
+    description: "Exit read-only mode and resume normal operation",
     handler: async(_args, ctx) => {
-      await planPolicyHandler(pi, 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,14 +1409,22 @@ export default function planExtension(pi: ExtensionAPI) {
 
   pi.on("session_start", 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/tasks.ts

@@ -11,6 +11,7 @@ import { Text } from "@mariozechner/pi-tui";
 type ITasksAction =
   | "show"
   | "get"
+  | "create-section"
   | "create-feature"
   | "create-task"
   | "set-status"
@@ -53,9 +54,10 @@ interface IProjectFeatureSummary {
 }
 
 interface IProjectSectionSummary {
-  sectionId: string;
-  heading: string;
-  filePath: string;
+  id: string;
+  title: string;
+  slug: string;
+  summary: string;
   status: string;
   featureCount: number;
   taskCount: number;
@@ -72,6 +74,7 @@ const TaskParams = Type.Object({
   action: StringEnum([
     "show",
     "get",
+    "create-section",
     "create-feature",
     "create-task",
     "set-status",
@@ -79,10 +82,10 @@ const TaskParams = Type.Object({
   ] 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: "Knowledge section id" })),
-  title: Type.Optional(Type.String({ description: "Feature or task title" })),
-  summary: Type.Optional(Type.String({ description: "Feature or task summary" })),
-  slug: Type.Optional(Type.String({ description: "Feature slug" })),
+  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" })),
@@ -175,7 +178,7 @@ function formatHierarchySummary(payload: IProjectPlanShowPayload): string {
 
   const lines: string[] = [];
   for (const section of populatedSections) {
-    lines.push(`${section.heading} (${section.status})`);
+    lines.push(`${section.title} (${section.status})`);
     for (const feature of section.features) {
       lines.push(`  - ${feature.title} (${feature.status})`);
       for (const task of feature.tasks) {
@@ -212,21 +215,21 @@ async function tasksCommandHandler(pi: ExtensionAPI, ctx: ExtensionCommandContex
 
   const query = rawArgs.trim().toLowerCase();
   const sections = payload.hierarchy.sections.filter((section) => section.features.length > 0)
-    .filter((section) => !query || section.heading.toLowerCase().includes(query) || section.sectionId.toLowerCase().includes(query));
+    .filter((section) => !query || section.title.toLowerCase().includes(query) || section.id.toLowerCase().includes(query));
   if (sections.length === 0) {
     ctx.ui.notify("No project-plan sections with tasks were found.", "info");
     return;
   }
 
   const selectedSectionId = await selectFromOptions(ctx, "Project Sections", sections.map((section) => ({
-    label: `${section.heading} (${section.status})`,
-    value: section.sectionId,
+    label: `${section.title} (${section.status})`,
+    value: section.id,
   })));
   if (!selectedSectionId) {
     return;
   }
 
-  const section = sections.find((item) => item.sectionId === selectedSectionId);
+  const section = sections.find((item) => item.id === selectedSectionId);
   if (!section) {
     return;
   }
@@ -361,6 +364,32 @@ export default function tasksExtension(pi: ExtensionAPI) {
           };
         }
 
+        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 {

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,16 @@ 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 (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.
+
+- `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 upsert-section --title <title>` — create or update a section
+- `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,24 @@ 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 (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.
+
+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 check` — validate section references and graph integrity
+- `docyrus project-plan ensure` — initialize an empty project-plan graph 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.

package/resources/pi-agent/skills/docyrus-app-dev-react/SKILL.md

@@ -24,7 +24,7 @@ Use this skill when you are:
 - Setting up authentication with `@docyrus/signin`
 - Bootstrapping tenant-aware runtime utilities with `@docyrus/app-utils`
 - Fetching or mutating data with generated collections or `@docyrus/api-client`
-- Persisting app-level config or saved grid views with `AppConfig` and `DataViews`
+- Persisting app-level config or user-level config or saved grid views with `AppConfig`, `UserAppConfig`, and `DataViews`
 - Building record sharing, role management, or ACL-driven UI flows
 - Designing feature UIs such as dashboards, forms, tables, layouts, dialogs, analytics, or detail pages
 - Selecting between shadcn, diceui, animate-ui, docyrus-ui, and reui components
@@ -36,7 +36,7 @@ Use this skill when you are:
 2. Bootstrap `TenantPreferences`, date/number utilities, and shared app runtime helpers from `@docyrus/app-utils`.
 3. Use generated Docyrus collection hooks or the REST client for data access.
 4. Define `columns`, filters, formulas, child queries, and mutations correctly.
-5. Use `AppConfig` for per-app persisted settings and `DataViews` for saved grid views.
+5. Use `AppConfig` for per-app persisted settings, `UserAppConfig` for per-user per-app settings, and `DataViews` for saved grid views.
 6. Check preferred UI components before building anything custom.
 7. Use Docyrus form and detail patterns for create, edit, item detail, and editable grid flows.
 8. Connect UI actions to TanStack Query mutations and invalidate relevant queries.
@@ -81,6 +81,7 @@ Use `@docyrus/app-utils` as the default runtime layer for tenant-level formattin
 ```tsx
 import {
   createAppConfigClient,
+  createUserAppConfigClient,
   createDataViewClient,
   createDateUtils,
   createNumberUtils,
@@ -109,6 +110,7 @@ function useAppRuntime(appId: string) {
         }),
         numberUtils: createNumberUtils({ preferences }),
         appConfig: createAppConfigClient(client!, appId),
+        userConfig: createUserAppConfigClient(client!, appId),
         dataViews: createDataViewClient(client!, appId),
       }
     },
@@ -121,6 +123,7 @@ Use this runtime to:
 - Format dates and datetimes with tenant format strings and the user's timezone.
 - Format numbers, currency-like values, and decimals using tenant separators and precision.
 - Read and upsert the app's single persisted `AppConfig` document.
+- Read and upsert the current user's `UserAppConfig` document (per-user per-app settings).
 - Read and persist saved grid views through `DataViews`.
 
 ### Data fetching with generated collections
@@ -187,17 +190,18 @@ Use `DataGridViewSelect` as the default saved-view UI for Docyrus grids, and per
 8. **Initialize `TenantPreferences` once per app runtime** and create shared `dateUtils` / `numberUtils` instances from `@docyrus/app-utils`.
 9. **Formatting functions from `@docyrus/app-utils` are regionalized** — do not hardcode locale, date format, decimal separator, thousand separator, or decimal precision when tenant preferences should drive them.
 10. **Use `createAppConfigClient(client, appId)`** for the app's single persisted config document; `upsert` is the default write path.
-11. **Use `createDataViewClient(client, appId)`** for saved grid-view CRUD.
-12. **Use `DataViews` with `DataGridViewSelect`** to show, create, edit, reorder, hide, unhide, soft-delete, and hard-delete saved data grid views.
-13. **`DataGridViewSelect` needs a TanStack table instance** and should receive `fields` when you want the built-in filter builder/editor experience.
-14. **Data view creation requires `name` and `tenant_data_source_id`**.
-15. **Use `dataViews.update(viewId, { archived: true })` for soft-delete** and `dataViews.remove(viewId)` only for irreversible hard-delete.
-16. **Regenerate collections after schema changes** by rebuilding the tenant OpenAPI spec, downloading the latest `openapi.json`, and re-running the collection generator.
-17. **ACL endpoints are usually raw-client integrations** — use `useDocyrusClient()` or `RestApiClient` for roles, user-role assignments, role queries, record sharing, and ownership transfer.
-18. **Prefer role `uid` values** for ACL role writes, user-role `roleIds`, and role-query `roleIds`.
-19. **Treat `PUT /v1/users/acl/users/:userId/roles` as full replacement** and `POST /v1/users/acl/users/:userId/roles` as additive.
-20. **Send role-query `query` as raw JSON** and omit `tenantAppId` when `dataSourceId` is present; backend derives it.
-21. **After deleting a role, invalidate dependent app queries** for role lists, user-role lists, role-query lists, and any UI that renders primary-role labels.
+11. **Use `createUserAppConfigClient(client, appId)`** for the current user's persisted config document scoped to an app (e.g. theme, layout preferences, sidebar state); `upsert` is the default write path.
+12. **Use `createDataViewClient(client, appId)`** for saved grid-view CRUD.
+13. **Use `DataViews` with `DataGridViewSelect`** to show, create, edit, reorder, hide, unhide, soft-delete, and hard-delete saved data grid views.
+14. **`DataGridViewSelect` needs a TanStack table instance** and should receive `fields` when you want the built-in filter builder/editor experience.
+15. **Data view creation requires `name` and `tenant_data_source_id`**.
+16. **Use `dataViews.update(viewId, { archived: true })` for soft-delete** and `dataViews.remove(viewId)` only for irreversible hard-delete.
+17. **Regenerate collections after schema changes** by rebuilding the tenant OpenAPI spec, downloading the latest `openapi.json`, and re-running the collection generator.
+18. **ACL endpoints are usually raw-client integrations** — use `useDocyrusClient()` or `RestApiClient` for roles, user-role assignments, role queries, record sharing, and ownership transfer.
+19. **Prefer role `uid` values** for ACL role writes, user-role `roleIds`, and role-query `roleIds`.
+20. **Treat `PUT /v1/users/acl/users/:userId/roles` as full replacement** and `POST /v1/users/acl/users/:userId/roles` as additive.
+21. **Send role-query `query` as raw JSON** and omit `tenantAppId` when `dataSourceId` is present; backend derives it.
+22. **After deleting a role, invalidate dependent app queries** for role lists, user-role lists, role-query lists, and any UI that renders primary-role labels.
 
 ## Critical UI/UX Rules