pi-monofold 0.1.1 → 0.3.0

package/README.md

@@ -1,5 +1,11 @@
 # Pi Monofold
 
+[![npm version](https://img.shields.io/npm/v/pi-monofold?color=cb3837&logo=npm)](https://www.npmjs.com/package/pi-monofold)
+[![Publish to npm](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/publish.yml)
+[![Auto Release](https://github.com/eiei114/pi-monofold/actions/workflows/auto-release.yml/badge.svg)](https://github.com/eiei114/pi-monofold/actions/workflows/auto-release.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+[![Pi Package](https://img.shields.io/badge/Pi-package-6f42c1)](https://github.com/eiei114/pi-monofold)
+
 Pi Monofold (`pi-monofold`) is a Pi Coding Agent extension that folds multiple local repositories and folders into a guarded **Virtual Monorepo** for AI agents.
 
 It keeps repositories physically separate, while giving Pi a lightweight manifest, routed writes, workspace-aware reads, guarded commands, and explicit git flows.
@@ -98,11 +104,17 @@ defaults:
     created: "{{date}}"
     source: "pi-monofold"
 
+focusPresets:
+  - id: control
+    label: Control workspace focus
+    targets:
+      - targetTags: [control]
+
 workspaces:
   - name: "Product docs"
     path: "../business"
     tags: [business, markdown, planning]
-    capabilities: [read, writeDocs, gitCommit]
+    capabilities: [read, writeDocs, git]
     contextFiles: [README.md, CONTEXT.md]
     routes:
       default: "Notes"
@@ -123,44 +135,57 @@ workspaces:
   - name: "Application"
     path: "../app"
     tags: [development, app]
-    capabilities: [read, editCode, runCommands, gitCommit, gitPush]
+    capabilities: [read, editCode, runCommands, git]
     contextFiles: [README.md, AGENTS.md]
 ```
 
-## Tools
+## Focus presets
 
-- `monofold_list`: show manifest and git status summary.
-- `monofold_read`: read files, search text, or show a tree inside readable workspaces.
-- `monofold_write`: create routed Markdown outputs by `routeType`, `title`, and `body`.
-- `monofold_git`: run guarded workspace git `status`, `commit`, or `push`.
-- `monofold_init`: queue `/monofold:init`.
+Optional `focusPresets` define tag-based focus targets for the control workspace. Preset `id` values must be unique. Each target uses `targetTags`, matching workspace tags the same way as other Monofold target selectors. Targets that match zero configured workspaces are allowed in config and emit a runtime warning when the active preset is applied.
+
+Active focus (the selected preset id) lives in extension session memory only. It resets when Pi restarts. When `focusPresets` is non-empty, the first preset in YAML order becomes active at session start unless a later slice changes it.
+
+The example above includes a generic seed preset `control`. Add matching workspace tags in your own config when you adopt it.
 
 ## Commands
 
-- `/monofold:list` or `/monofold_list`: show manifest and git status summary.
-- `/monofold:add <path> --name "Name" --tags tag1,tag2 --capabilities read,editCode,runCommands,gitCommit`: add a workspace to `.pi/monofold.yaml`.
-- `/monofold:project-add <path> --parent "Name" --tags project,slug`: add a Project Workspace under a parent workspace.
-- `/monofold:update [natural language request]`: migrate legacy config to `.pi/monofold.yaml`, normalize YAML, validate the manifest, and optionally hand a config-change request to the agent.
-- `/monofold:read file <path> --target #0.1`: read a file from a workspace or project target.
-- `/monofold:tree [path] --target #0.1 --depth 2`: show a target tree.
-- `/monofold:search <query> --target #0.1`: search a target.
-- `/monofold:write --route progress --title "Title" --body "Markdown body"`: write routed Markdown.
-- `/monofold:git status|commit|push --target #0.1`: run guarded target git.
+Human-facing commands accept natural-language arguments and hand off interpretation to the Pi agent:
+
+- `/monofold:explore [request]`: list, read, search, or inspect workspace trees.
+- `/monofold:write [request]`: create routed Markdown outputs.
+- `/monofold:config [request]`: add or change Workspaces and Project Workspaces.
+- `/monofold:git [request]`: run git status, commit, push, or commit+push workflows.
+- `/monofold:guide`: start an interactive guide for Explore, Write, Config, Git, init, and update flows.
+- `/monofold:init`: create or update `.pi/monofold.yaml` with an interactive wizard.
+- `/monofold:update [request]`: migrate/clean up legacy config and optionally hand a config-change request to the agent.
 
 Examples:
 
 ```text
-/monofold:add C:/Projects/app --name "Application" --tags development,app --capabilities read,editCode,runCommands,gitCommit --context README.md,AGENTS.md
-/monofold:add ../business --name "Product Docs" --tags business,docs --capabilities read,writeDocs,gitCommit --routes default=Notes,progress=Progress,research=Research
-/monofold:project-add Projects/Launch --parent "Product Docs" --tags project,launch --routes default=.,progress=Progress
-/monofold:update rename the Product Docs workspace to Business Notes and add tag docs
+/monofold:explore show the project workspaces
+/monofold:write write today's progress note for Pi Monofold
+/monofold:config add 4_Project/NewApp as a Project Workspace under Obsidian Vault with tag project,newapp
+/monofold:git commit and push the pi-monofold dev workspace
+/monofold:guide
 ```
 
+Fine-grained legacy commands such as `/monofold:list`, `/monofold:read`, `/monofold:search`, `/monofold:tree`, `/monofold:add`, `/monofold:project-add`, and underscore aliases are not part of the human command surface.
+
+## Agent API
+
+Pi agents use strict `monofold_*` tools behind the natural-language command surface:
+
+- `monofold_list`: show manifest and git status summary.
+- `monofold_read`: read files, search text, or show a tree inside readable workspaces.
+- `monofold_write`: create routed Markdown outputs by `routeType`, `title`, and `body`.
+- `monofold_git`: run guarded workspace git `status`, `commit`, `push`, or `commitPush`.
+- `monofold_init`: queue `/monofold:init`.
+
 Project Workspaces are listed under `workspaces[].projects`. Their `path` is relative to the parent workspace, `tags` are combined with parent tags, `capabilities` inherit unless explicitly replaced, and missing routes default to `default: "."` when the effective target has `writeDocs`.
 
 ## Updating configuration
 
-`.pi/monofold.yaml` is the canonical config file. Legacy `.pi/monofold.yml` is still readable, but `/monofold:update` migrates it to `.pi/monofold.yaml`, writes a timestamped backup such as `.pi/monofold.yml.bak-20260524-153012`, and removes the legacy file after a successful write. If both `.yaml` and `.yml` exist, Pi Monofold stops with a conflict error so you can choose the correct file manually.
+`.pi/monofold.yaml` is the canonical config file. Legacy `.pi/monofold.yml` is still readable. Intent commands try to migrate a legacy-only config automatically, show a notice, and continue with the legacy config if migration fails. `/monofold:update` migrates or cleans up legacy config, writes timestamped backups such as `.pi/monofold.yml.bak-20260524-153012`, and removes the legacy file after a successful write. If both `.yaml` and `.yml` exist, normal intent commands prefer canonical `.yaml`; `/monofold:update` handles legacy cleanup.
 
 `/monofold:update` is a configuration migration command, not a Pi package updater. Use `pi update`, `pi update --extensions`, or `pi install ...@new-ref` for package updates.
 
@@ -178,4 +203,4 @@ When `.pi/monofold.yaml` or legacy `.pi/monofold.yml` exists, Pi Monofold guards
 - Docs write: requires `writeDocs`.
 - Code edit: requires `editCode`.
 - Bash: requires workspace cwd and `runCommands`.
-- Git commit/push via bash: blocked; use `monofold_git`.
+- Git commit/push via bash: blocked; use `/monofold:git` or the `monofold_git` agent tool.

package/focus-preset.ts

@@ -0,0 +1,133 @@
+import { assertKnownKeys, asStringArray, isRecord, uniqueStrings } from "./validation.js";
+
+export type FocusPresetTarget = {
+  targetTags: string[];
+};
+
+export type FocusPreset = {
+  id: string;
+  label: string;
+  targets: FocusPresetTarget[];
+};
+
+export type FocusMatchableWorkspace = {
+  tags: string[];
+};
+
+const FOCUS_PRESET_KEYS = new Set(["id", "label", "targets"]);
+const FOCUS_PRESET_TARGET_KEYS = new Set(["targetTags"]);
+
+/** Parses and validates focus preset configuration from YAML/JSON input. */
+export function parseFocusPresets(value: unknown, label = "focusPresets"): FocusPreset[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array`);
+  const presets: FocusPreset[] = [];
+  const seenIds = new Set<string>();
+  for (let index = 0; index < value.length; index += 1) {
+    const item = value[index];
+    const itemLabel = `${label}[${index}]`;
+    if (!isRecord(item)) throw new Error(`${itemLabel} must be an object`);
+    assertKnownKeys(itemLabel, item, FOCUS_PRESET_KEYS);
+    if (typeof item.id !== "string" || item.id.trim() === "") {
+      throw new Error(`${itemLabel}.id must be a non-empty string`);
+    }
+    if (typeof item.label !== "string" || item.label.trim() === "") {
+      throw new Error(`${itemLabel}.label must be a non-empty string`);
+    }
+    if (!Array.isArray(item.targets) || item.targets.length === 0) {
+      throw new Error(`${itemLabel}.targets must be a non-empty array`);
+    }
+    const targets: FocusPresetTarget[] = [];
+    for (let targetIndex = 0; targetIndex < item.targets.length; targetIndex += 1) {
+      const target = item.targets[targetIndex];
+      const targetLabel = `${itemLabel}.targets[${targetIndex}]`;
+      if (!isRecord(target)) throw new Error(`${targetLabel} must be an object`);
+      assertKnownKeys(targetLabel, target, FOCUS_PRESET_TARGET_KEYS);
+      const targetTags = uniqueStrings(asStringArray(`${targetLabel}.targetTags`, target.targetTags));
+      if (targetTags.length === 0) {
+        throw new Error(`${targetLabel}.targetTags must contain at least one non-empty string`);
+      }
+      targets.push({ targetTags });
+    }
+    if (seenIds.has(item.id)) throw new Error(`${label} has duplicate preset id: ${item.id}`);
+    seenIds.add(item.id);
+    presets.push({ id: item.id, label: item.label, targets });
+  }
+  return presets;
+}
+
+/** Returns the first preset id, or null when no focus preset is available. */
+export function pickDefaultFocusPresetId(focusPresets: FocusPreset[] | undefined): string | null {
+  if (!focusPresets || focusPresets.length === 0) return null;
+  return focusPresets[0]?.id ?? null;
+}
+
+/** Finds a focus preset by stable id. */
+export function findFocusPresetById(focusPresets: FocusPreset[] | undefined, id: string): FocusPreset | undefined {
+  return focusPresets?.find((preset) => preset.id === id);
+}
+
+/** Returns true when every requested focus tag is present on a workspace. */
+export function matchesFocusTarget(workspace: FocusMatchableWorkspace, targetTags: string[]): boolean {
+  if (targetTags.length === 0) return false;
+  return targetTags.every((tag) => workspace.tags.includes(tag));
+}
+
+/** Counts workspaces matched by a focus target's tag set. */
+export function countMatchingWorkspaces(
+  workspaces: FocusMatchableWorkspace[],
+  targetTags: string[],
+): number {
+  return workspaces.filter((workspace) => matchesFocusTarget(workspace, targetTags)).length;
+}
+
+/** Emits warnings for a preset's targets that do not match any configured workspace. */
+export function warnZeroTargetMatchesForPreset(
+  preset: FocusPreset,
+  workspaces: FocusMatchableWorkspace[],
+  warn: (message: string) => void,
+): void {
+  for (const target of preset.targets) {
+    if (countMatchingWorkspaces(workspaces, target.targetTags) === 0) {
+      warn(
+        `Focus preset "${preset.id}" target [${target.targetTags.join(", ")}] matches no configured workspace`,
+      );
+    }
+  }
+}
+
+let activeFocusPresetId: string | null = null;
+let activeFocusInitialized = false;
+
+/** Initializes the active focus preset once per process/session. */
+export function ensureActiveFocusInitialized(focusPresets: FocusPreset[] | undefined): void {
+  if (activeFocusInitialized) return;
+  activeFocusInitialized = true;
+  activeFocusPresetId = pickDefaultFocusPresetId(focusPresets);
+}
+
+/** Returns the current active focus preset id, if any. */
+export function getActiveFocusPresetId(): string | null {
+  return activeFocusPresetId;
+}
+
+/** Sets the active focus preset after validating that the id exists. */
+export function setActiveFocusPresetId(id: string, focusPresets: FocusPreset[] | undefined): void {
+  if (!findFocusPresetById(focusPresets, id)) {
+    throw new Error(`Unknown focus preset id: ${id}`);
+  }
+  activeFocusPresetId = id;
+  activeFocusInitialized = true;
+}
+
+/** Clears the active focus preset for the current process/session. */
+export function clearActiveFocusPresetId(): void {
+  activeFocusPresetId = null;
+  activeFocusInitialized = true;
+}
+
+/** Resets in-memory session state (for tests and process restart). */
+export function resetActiveFocusSessionState(): void {
+  activeFocusPresetId = null;
+  activeFocusInitialized = false;
+}

package/index.ts

@@ -4,8 +4,19 @@ import { execFile } from "node:child_process";
 import { access, copyFile, mkdir, readFile, readdir, realpath, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import YAML from "yaml";
-
-type CapabilityTag = "read" | "writeDocs" | "editCode" | "runCommands" | "gitCommit" | "gitPush";
+import {
+  type FocusPreset,
+  ensureActiveFocusInitialized,
+  findFocusPresetById,
+  getActiveFocusPresetId,
+  parseFocusPresets,
+  warnZeroTargetMatchesForPreset,
+} from "./focus-preset.js";
+import { assertKnownKeys, asStringArray, isRecord, uniqueStrings } from "./validation.js";
+
+type CapabilityTag = "read" | "writeDocs" | "editCode" | "runCommands" | "git";
+type LegacyCapabilityTag = CapabilityTag | "gitCommit" | "gitPush";
+type IntentCategory = "Explore" | "Write" | "Config" | "Git";
 type RouteType = "default" | "prd" | "design" | "progress" | "issue" | "research" | "decision";
 
 type RouteConfig = {
@@ -40,6 +51,7 @@ type MultiWorkspaceConfig = {
     filenameTemplate?: string;
     metadata?: Record<string, unknown>;
   };
+  focusPresets?: FocusPreset[];
   workspaces: WorkspaceConfig[];
 };
 
@@ -93,6 +105,9 @@ type ConfigMigrationPlan = {
   targetRelativePath: string;
   backupPath?: string;
   backupRelativePath?: string;
+  cleanupLegacyPath?: string;
+  cleanupLegacyBackupPath?: string;
+  cleanupLegacyBackupRelativePath?: string;
   normalizedText: string;
   loaded: LoadedConfig;
   actions: string[];
@@ -101,7 +116,8 @@ type ConfigMigrationPlan = {
 const CONFIG_RELATIVE_PATH = path.join(".pi", "monofold.yaml");
 const LEGACY_CONFIG_RELATIVE_PATH = path.join(".pi", "monofold.yml");
 const ROUTE_TYPES: RouteType[] = ["default", "prd", "design", "progress", "issue", "research", "decision"];
-const CAPABILITIES: CapabilityTag[] = ["read", "writeDocs", "editCode", "runCommands", "gitCommit", "gitPush"];
+const CAPABILITIES: CapabilityTag[] = ["read", "writeDocs", "editCode", "runCommands", "git"];
+const LEGACY_CAPABILITIES: LegacyCapabilityTag[] = [...CAPABILITIES, "gitCommit", "gitPush"];
 const DOC_EXTENSIONS = new Set([".md", ".mdx", ".txt", ".rst", ".adoc"]);
 const CODE_EXTENSIONS = new Set([
   ".ts",
@@ -129,26 +145,16 @@ const CODE_EXTENSIONS = new Set([
   ".scss",
   ".html",
 ]);
-const ROOT_KEYS = new Set(["version", "defaults", "workspaces"]);
+const ROOT_KEYS = new Set(["version", "defaults", "focusPresets", "workspaces"]);
 const DEFAULT_KEYS = new Set(["contextFiles", "filenameTemplate", "metadata"]);
 const WORKSPACE_KEYS = new Set(["name", "path", "tags", "capabilities", "contextFiles", "routes", "projects"]);
 const PROJECT_KEYS = new Set(["name", "path", "tags", "capabilities", "contextFiles", "routes"]);
 const ROUTE_KEYS = new Set(["path", "filenameTemplate", "metadata"]);
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-
 function normalizeSlashes(value: string): string {
   return value.replace(/\\/g, "/");
 }
 
-function assertKnownKeys(label: string, value: Record<string, unknown>, allowed: Set<string>): void {
-  for (const key of Object.keys(value)) {
-    if (!allowed.has(key)) throw new Error(`${label} has unknown key: ${key}`);
-  }
-}
-
 function isInside(parent: string, child: string): boolean {
   const relative = path.relative(parent, child);
   return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
@@ -168,26 +174,16 @@ function assertProjectPath(label: string, value: string): void {
   }
 }
 
-function uniqueStrings(items: string[]): string[] {
-  return [...new Set(items.filter(Boolean))];
-}
-
-function asStringArray(label: string, value: unknown, required = true): string[] {
-  if (value === undefined && !required) return [];
-  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
-    throw new Error(`${label} must be an array of strings`);
-  }
-  return value;
-}
-
 function asCapabilityArray(value: unknown): CapabilityTag[] {
   const items = asStringArray("capabilities", value);
+  const normalized: CapabilityTag[] = [];
   for (const item of items) {
-    if (!CAPABILITIES.includes(item as CapabilityTag)) {
+    if (!LEGACY_CAPABILITIES.includes(item as LegacyCapabilityTag)) {
       throw new Error(`Unknown capability: ${item}`);
     }
+    normalized.push(item === "gitCommit" || item === "gitPush" ? "git" : (item as CapabilityTag));
   }
-  return items as CapabilityTag[];
+  return uniqueStrings(normalized) as CapabilityTag[];
 }
 
 function asOptionalCapabilityArray(value: unknown): CapabilityTag[] | undefined {
@@ -238,11 +234,16 @@ async function pathExists(targetPath: string): Promise<boolean> {
   }
 }
 
-async function resolveConfigFile(cwd: string, allowMissing = false): Promise<{ configPath: string; relativePath: string; kind: "canonical" | "legacy" | "missing" }> {
+async function resolveConfigFile(
+  cwd: string,
+  allowMissing = false,
+  options: { preferCanonicalOnConflict?: boolean } = {},
+): Promise<{ configPath: string; relativePath: string; kind: "canonical" | "legacy" | "missing" }> {
   const canonicalPath = path.join(cwd, CONFIG_RELATIVE_PATH);
   const legacyPath = path.join(cwd, LEGACY_CONFIG_RELATIVE_PATH);
   const [hasCanonical, hasLegacy] = await Promise.all([pathExists(canonicalPath), pathExists(legacyPath)]);
   if (hasCanonical && hasLegacy) {
+    if (options.preferCanonicalOnConflict) return { configPath: canonicalPath, relativePath: CONFIG_RELATIVE_PATH, kind: "canonical" };
     throw new Error(`Configuration file conflict: both ${CONFIG_RELATIVE_PATH} and ${LEGACY_CONFIG_RELATIVE_PATH} exist. Remove one before continuing.`);
   }
   if (hasCanonical) return { configPath: canonicalPath, relativePath: CONFIG_RELATIVE_PATH, kind: "canonical" };
@@ -282,7 +283,7 @@ function runCommand(
 }
 
 async function loadConfig(cwd: string): Promise<LoadedConfig> {
-  const { configPath } = await resolveConfigFile(cwd);
+  const { configPath } = await resolveConfigFile(cwd, false, { preferCanonicalOnConflict: true });
   const text = await readFile(configPath, "utf8");
   const parsed = YAML.parse(text, { uniqueKeys: true }) as unknown;
   return validateConfigObject(cwd, configPath, parsed);
@@ -301,6 +302,7 @@ async function validateConfigObject(cwd: string, configPath: string, parsed: unk
   const defaultContextFiles = defaults ? asStringArray("defaults.contextFiles", defaults.contextFiles, false) : [];
   const defaultFilenameTemplate = typeof defaults?.filenameTemplate === "string" ? defaults.filenameTemplate : undefined;
   const defaultMetadata = isRecord(defaults?.metadata) ? (defaults.metadata as Record<string, unknown>) : undefined;
+  const focusPresets = parseFocusPresets(parsed.focusPresets, "focusPresets");
 
   const workspaces: ResolvedWorkspace[] = [];
   for (let index = 0; index < parsed.workspaces.length; index += 1) {
@@ -426,6 +428,7 @@ async function validateConfigObject(cwd: string, configPath: string, parsed: unk
         filenameTemplate: defaultFilenameTemplate,
         metadata: defaultMetadata,
       },
+      focusPresets: focusPresets.length > 0 ? focusPresets : undefined,
       workspaces: workspaces.filter((workspace) => workspace.kind === "workspace"),
     },
     workspaces,
@@ -436,6 +439,26 @@ function timestampSuffix(now = new Date()): string {
   return now.toISOString().replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z").replace("T", "-").replace(/Z$/, "");
 }
 
+function normalizeCapabilityValues(value: unknown): string[] | undefined {
+  if (value === undefined) return undefined;
+  return asCapabilityArray(value);
+}
+
+function normalizeConfigCapabilities(config: Record<string, unknown>): void {
+  const workspaces = Array.isArray(config.workspaces) ? (config.workspaces as unknown[]) : [];
+  for (const workspace of workspaces) {
+    if (!isRecord(workspace)) continue;
+    const capabilities = normalizeCapabilityValues(workspace.capabilities);
+    if (capabilities) workspace.capabilities = capabilities;
+    const projects = Array.isArray(workspace.projects) ? (workspace.projects as unknown[]) : [];
+    for (const project of projects) {
+      if (!isRecord(project)) continue;
+      const projectCapabilities = normalizeCapabilityValues(project.capabilities);
+      if (projectCapabilities) project.capabilities = projectCapabilities;
+    }
+  }
+}
+
 function normalizeConfigForMigration(parsed: unknown): Record<string, unknown> {
   if (!isRecord(parsed)) throw new Error("monofold config must be a YAML object");
   assertKnownKeys("monofold config", parsed, ROOT_KEYS);
@@ -443,12 +466,17 @@ function normalizeConfigForMigration(parsed: unknown): Record<string, unknown> {
   if (version !== 1) throw new Error("monofold config requires version: 1");
   const normalized: Record<string, unknown> = { version: 1 };
   if (parsed.defaults !== undefined) normalized.defaults = parsed.defaults;
+  if (parsed.focusPresets !== undefined) normalized.focusPresets = parsed.focusPresets;
   normalized.workspaces = parsed.workspaces;
+  normalizeConfigCapabilities(normalized);
   return normalized;
 }
 
 async function buildConfigMigrationPlan(cwd: string): Promise<ConfigMigrationPlan> {
-  const source = await resolveConfigFile(cwd);
+  const canonicalPath = path.join(cwd, CONFIG_RELATIVE_PATH);
+  const legacyPath = path.join(cwd, LEGACY_CONFIG_RELATIVE_PATH);
+  const [hasCanonical, hasLegacy] = await Promise.all([pathExists(canonicalPath), pathExists(legacyPath)]);
+  const source = await resolveConfigFile(cwd, false, { preferCanonicalOnConflict: true });
   if (source.kind === "missing") throw new Error(`No Pi Monofold configuration found. Expected ${CONFIG_RELATIVE_PATH} or legacy ${LEGACY_CONFIG_RELATIVE_PATH}.`);
 
   const originalText = await readFile(source.configPath, "utf8");
@@ -457,13 +485,16 @@ async function buildConfigMigrationPlan(cwd: string): Promise<ConfigMigrationPla
   const targetPath = path.join(cwd, CONFIG_RELATIVE_PATH);
   const normalizedText = YAML.stringify(normalized).trimEnd() + "\n";
   const loaded = await validateConfigObject(cwd, targetPath, normalized);
-  const changed = source.kind !== "canonical" || originalText !== normalizedText;
+  const cleanupLegacy = hasCanonical && hasLegacy;
+  const changed = source.kind !== "canonical" || originalText !== normalizedText || cleanupLegacy;
   const actions: string[] = [];
   if (source.kind === "legacy") actions.push(`Move legacy config ${LEGACY_CONFIG_RELATIVE_PATH} to canonical ${CONFIG_RELATIVE_PATH}`);
   if (originalText !== normalizedText) actions.push("Normalize YAML and ensure version: 1 is explicit");
-  if (source.kind === "legacy") actions.push(`Remove legacy config ${LEGACY_CONFIG_RELATIVE_PATH} after writing ${CONFIG_RELATIVE_PATH}`);
+  if (source.kind === "legacy" || cleanupLegacy) actions.push(`Remove legacy config ${LEGACY_CONFIG_RELATIVE_PATH} after writing ${CONFIG_RELATIVE_PATH}`);
   if (!changed) actions.push(`Already current: ${CONFIG_RELATIVE_PATH} (version 1)`);
-  const backupPath = changed ? `${source.configPath}.bak-${timestampSuffix()}` : undefined;
+  const suffix = timestampSuffix();
+  const backupPath = changed && (source.kind === "legacy" || originalText !== normalizedText) ? `${source.configPath}.bak-${suffix}` : undefined;
+  const cleanupLegacyBackupPath = cleanupLegacy ? `${legacyPath}.bak-${suffix}` : undefined;
   return {
     changed,
     sourcePath: source.configPath,
@@ -473,6 +504,9 @@ async function buildConfigMigrationPlan(cwd: string): Promise<ConfigMigrationPla
     targetRelativePath: CONFIG_RELATIVE_PATH,
     backupPath,
     backupRelativePath: backupPath ? normalizeSlashes(path.relative(cwd, backupPath)) : undefined,
+    cleanupLegacyPath: cleanupLegacy ? legacyPath : undefined,
+    cleanupLegacyBackupPath,
+    cleanupLegacyBackupRelativePath: cleanupLegacyBackupPath ? normalizeSlashes(path.relative(cwd, cleanupLegacyBackupPath)) : undefined,
     normalizedText,
     loaded,
     actions,
@@ -481,11 +515,35 @@ async function buildConfigMigrationPlan(cwd: string): Promise<ConfigMigrationPla
 
 async function applyConfigMigrationPlan(plan: ConfigMigrationPlan): Promise<void> {
   if (!plan.changed) return;
-  if (!plan.backupPath) throw new Error("Migration backup path is required for changed configuration");
   await mkdir(path.dirname(plan.targetPath), { recursive: true });
-  await copyFile(plan.sourcePath, plan.backupPath);
+  if (plan.backupPath) await copyFile(plan.sourcePath, plan.backupPath);
+  if (plan.cleanupLegacyPath && plan.cleanupLegacyBackupPath) await copyFile(plan.cleanupLegacyPath, plan.cleanupLegacyBackupPath);
   await writeFile(plan.targetPath, plan.normalizedText, "utf8");
   if (plan.sourceKind === "legacy") await unlink(plan.sourcePath);
+  if (plan.cleanupLegacyPath) await unlink(plan.cleanupLegacyPath);
+}
+
+async function prepareIntentConfiguration(ctx: ExtensionCommandContext): Promise<boolean> {
+  const canonicalPath = path.join(ctx.cwd, CONFIG_RELATIVE_PATH);
+  const legacyPath = path.join(ctx.cwd, LEGACY_CONFIG_RELATIVE_PATH);
+  const [hasCanonical, hasLegacy] = await Promise.all([pathExists(canonicalPath), pathExists(legacyPath)]);
+  if (!hasCanonical && !hasLegacy) {
+    ctx.ui.notify(`No ${CONFIG_RELATIVE_PATH} found. Queueing /monofold:init.`, "info");
+    return false;
+  }
+  if (!hasCanonical && hasLegacy) {
+    try {
+      const plan = await buildConfigMigrationPlan(ctx.cwd);
+      await applyConfigMigrationPlan(plan);
+      if (plan.changed) {
+        ctx.ui.notify(`Migrated ${LEGACY_CONFIG_RELATIVE_PATH} to ${CONFIG_RELATIVE_PATH}${plan.backupRelativePath ? ` (backup: ${plan.backupRelativePath})` : ""}.`, "info");
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Legacy migration failed; continuing with ${LEGACY_CONFIG_RELATIVE_PATH}: ${message}`, "error");
+    }
+  }
+  return true;
 }
 
 function formatMigrationPlan(plan: ConfigMigrationPlan): string {
@@ -493,7 +551,8 @@ function formatMigrationPlan(plan: ConfigMigrationPlan): string {
   return [
     `Source: ${plan.sourceRelativePath}`,
     `Target: ${plan.targetRelativePath}`,
-    `Backup: ${plan.backupRelativePath}`,
+    `Backup: ${plan.backupRelativePath ?? plan.cleanupLegacyBackupRelativePath ?? "none"}`,
+    ...(plan.backupRelativePath && plan.cleanupLegacyBackupRelativePath ? [`Legacy backup: ${plan.cleanupLegacyBackupRelativePath}`] : []),
     "",
     "Actions:",
     ...plan.actions.map((action) => `- ${action}`),
@@ -503,13 +562,62 @@ function formatMigrationPlan(plan: ConfigMigrationPlan): string {
 function buildConfigurationHandoffPrompt(request: string): string {
   return [
     "/monofold:update completed. Apply this requested Pi Monofold configuration change to `.pi/monofold.yaml`.",
-    "Edit the canonical config directly when needed, preserve valid YAML, then run `/monofold:list` as manifest validation.",
+    "Edit the canonical config directly when needed, preserve valid YAML, then run `monofold_list` as manifest validation.",
     "",
     "User request:",
     request.trim(),
   ].join("\n");
 }
 
+function buildIntentHandoffPrompt(intent: IntentCategory, request: string): string {
+  const trimmed = request.trim();
+  const emptyInstruction =
+    intent === "Explore"
+      ? "Ask what the user wants to list, read, search, or inspect."
+      : intent === "Write"
+        ? "Ask what document to create and where it should be saved."
+        : intent === "Config"
+          ? "Ask what Workspace or Project Workspace configuration change is needed."
+          : "Ask whether the user wants git status, commit, push, or commit+push.";
+  return [
+    `Pi Monofold ${intent} request. Interpret the user's natural-language input and continue as the agent.`,
+    "",
+    "Rules:",
+    "- Use strict `monofold_*` tools as the execution API; do not ask the user to write JSON or YAML unless needed.",
+    "- Select a Workspace Target automatically only when the manifest makes it unique; if multiple targets match, ask one clarifying question.",
+    "- Ask missing information incrementally, one question at a time.",
+    "- Explore intent: read/search/tree/list is read-only; execute immediately when target and path/query are clear.",
+    "- Write intent: infer route/title/body/filename when possible, but confirm Workspace, route, and filename before calling `monofold_write`.",
+    "- Config intent: edit `.pi/monofold.yaml` only after showing the YAML diff; validate afterward with `monofold_list`.",
+    "- Git intent: use `monofold_git`; for commit+push use action `commitPush` and one combined confirmation. If message is missing, propose one from the diff.",
+    "- If there is no `.pi/monofold.yaml`, guide the user to `/monofold:init`.",
+    "",
+    "Intent:",
+    intent,
+    "",
+    "User request:",
+    trimmed || `(empty input) ${emptyInstruction}`,
+  ].join("\n");
+}
+
+function buildGuideHandoffPrompt(request: string): string {
+  return [
+    "Pi Monofold guide request. Start a conversational helper flow for Pi Monofold.",
+    "",
+    "Guide the user through Explore, Write, Config, Git, init, or update. Do not dump a static help page.",
+    "Ask one question at a time, then route to the appropriate intent behavior:",
+    "- Explore: list/read/search/tree workspaces.",
+    "- Write: routed Markdown output.",
+    "- Config: Workspace or Project Workspace configuration changes with YAML diff confirmation.",
+    "- Git: status/commit/push/commit+push via `monofold_git`.",
+    "- Init: queue or instruct `/monofold:init`.",
+    "- Update: run or instruct `/monofold:update` for migration/cleanup.",
+    "",
+    "Initial user request:",
+    request.trim() || "(empty input) Ask what they want to do with Pi Monofold.",
+  ].join("\n");
+}
+
 function matchesTarget(workspace: ResolvedWorkspace, target: TargetInput): boolean {
   if (target.targetId && workspace.targetId !== (target.targetId.startsWith("#") ? target.targetId : `#${target.targetId}`)) return false;
   if (target.workspaceIndex !== undefined && workspace.index !== target.workspaceIndex) return false;
@@ -884,6 +992,21 @@ function inferBashCwd(ctx: ExtensionContext, command: string): string {
 }
 
 export default function piMultiWorkspace(pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      const loaded = await loadConfig(ctx.cwd);
+      ensureActiveFocusInitialized(loaded.raw.focusPresets);
+      const activeId = getActiveFocusPresetId();
+      if (!activeId) return;
+      const preset = findFocusPresetById(loaded.raw.focusPresets, activeId);
+      if (!preset) return;
+      if (!ctx.hasUI) return;
+      warnZeroTargetMatchesForPreset(preset, loaded.workspaces, (message) => ctx.ui.notify(message, "warning"));
+    } catch {
+      return;
+    }
+  });
+
   pi.on("before_agent_start", async (_event, ctx) => {
     try {
       const loaded = await loadConfig(ctx.cwd);
@@ -1028,9 +1151,9 @@ ${manifest}
   pi.registerTool({
     name: "monofold_git",
     label: "Workspace Git",
-    description: "Run guarded git status, commit, or push for one configured Git Workspace.",
+    description: "Run guarded git status, commit, push, or commitPush for one configured Git Workspace.",
     parameters: Type.Object({
-      action: Type.String({ description: "status, commit, or push" }),
+      action: Type.String({ description: "status, commit, push, or commitPush" }),
       message: Type.Optional(Type.String()),
       targetTags: Type.Optional(Type.Array(Type.String())),
       targetName: Type.Optional(Type.String()),
@@ -1038,7 +1161,7 @@ ${manifest}
       workspaceName: Type.Optional(Type.String()),
     }),
     async execute(_id, params, signal, _onUpdate, ctx) {
-      const required: CapabilityTag[] = params.action === "push" ? ["gitPush"] : params.action === "commit" ? ["gitCommit"] : [];
+      const required: CapabilityTag[] = params.action === "status" ? ["read"] : ["git"];
       const loaded = await loadConfig(ctx.cwd);
       const workspace = await resolveWorkspace(ctx, loaded, {
         targetTags: params.targetTags,
@@ -1050,18 +1173,35 @@ ${manifest}
       const root = await gitRoot(workspace);
       if (!root) throw new Error(`Not a Git Workspace: ${formatWorkspaceLabel(workspace)}`);
       if (params.action === "status") {
+        if (!workspace.capabilities.includes("read")) throw new Error(`Workspace lacks read capability: ${formatWorkspaceLabel(workspace)}`);
         const result = await runCommand("git", ["-C", root, "status", "--short", "--branch"], { signal, timeout: 10000 });
         return { content: [{ type: "text", text: result.stdout || "clean" }], details: { workspace } };
       }
-      if (params.action === "commit") {
+      if (!workspace.capabilities.includes("git")) throw new Error(`Workspace lacks git capability: ${formatWorkspaceLabel(workspace)}`);
+      if (params.action === "commit" || params.action === "commitPush") {
         const message = params.message ?? `Update ${workspace.name ?? (workspace.tags.join("-") || "workspace")}`;
         const status = await runCommand("git", ["-C", root, "status", "--short"], { signal, timeout: 10000 });
         const diffstat = await runCommand("git", ["-C", root, "diff", "--stat"], { signal, timeout: 10000 });
         const scope = workspace.kind === "project" && root !== workspace.resolvedPath ? normalizeSlashes(path.relative(root, workspace.resolvedPath)) : ".";
-        const ok = await confirm(ctx, "Workspace Commit", `${formatWorkspaceLabel(workspace)}\n\nStatus (repo full):\n${status.stdout || "clean"}\n\nDiffstat (repo full):\n${diffstat.stdout || "none"}\n\nCommit scope:\n${scope}\n\nCommit message:\n${message}\n\nStage scoped changes and commit?`);
-        if (!ok) return { content: [{ type: "text", text: "Commit cancelled" }], details: { cancelled: true } };
+        let pushContext = "";
+        if (params.action === "commitPush") {
+          const branch = await runCommand("git", ["-C", root, "branch", "--show-current"], { signal, timeout: 10000 });
+          const remote = await runCommand("git", ["-C", root, "remote", "-v"], { signal, timeout: 10000 });
+          const log = await runCommand("git", ["-C", root, "log", "--oneline", "@{u}..HEAD"], {
+            signal,
+            timeout: 10000,
+            allowExitCodes: [0, 128],
+          });
+          pushContext = `\n\nPush after commit:\nBranch: ${branch.stdout.trim()}\n\nRemote:\n${remote.stdout}\nCommits already ahead:\n${log.stdout || "none/unknown upstream"}`;
+        }
+        const ok = await confirm(ctx, params.action === "commitPush" ? "Workspace Commit + Push" : "Workspace Commit", `${formatWorkspaceLabel(workspace)}\n\nStatus (repo full):\n${status.stdout || "clean"}\n\nDiffstat (repo full):\n${diffstat.stdout || "none"}\n\nCommit scope:\n${scope}\n\nCommit message:\n${message}${pushContext}\n\n${params.action === "commitPush" ? "Stage scoped changes, commit, then push?" : "Stage scoped changes and commit?"}`);
+        if (!ok) return { content: [{ type: "text", text: params.action === "commitPush" ? "Commit+push cancelled" : "Commit cancelled" }], details: { cancelled: true } };
         await runCommand("git", ["-C", root, "add", "-A", "--", scope], { signal, timeout: 10000 });
         const commit = await runCommand("git", ["-C", root, "commit", "-m", message], { signal, timeout: 30000 });
+        if (params.action === "commitPush") {
+          const push = await runCommand("git", ["-C", root, "push"], { signal, timeout: 60000 });
+          return { content: [{ type: "text", text: [commit.stdout || commit.stderr, push.stdout || push.stderr].filter(Boolean).join("\n") }], details: { workspace, message } };
+        }
         return { content: [{ type: "text", text: commit.stdout || commit.stderr }], details: { workspace, message } };
       }
       if (params.action === "push") {
@@ -1206,7 +1346,7 @@ ${manifest}
     try {
       const parsed = parseCommandArgs(args);
       const action = parsed.positional[0] ?? "status";
-      const required: CapabilityTag[] = action === "push" ? ["gitPush"] : action === "commit" ? ["gitCommit"] : [];
+      const required: CapabilityTag[] = action === "status" ? ["read"] : ["git"];
       const loaded = await loadConfig(ctx.cwd);
       const workspace = await resolveWorkspace(ctx, loaded, commandTarget(parsed.flags, required));
       const root = await gitRoot(workspace);
@@ -1322,6 +1462,7 @@ ${manifest}
         changed: plan.changed,
         configPath: CONFIG_RELATIVE_PATH,
         backupPath: plan.backupRelativePath,
+        legacyBackupPath: plan.cleanupLegacyBackupRelativePath,
       });
 
       let request = args.trim();
@@ -1336,20 +1477,26 @@ ${manifest}
     }
   };
 
-  pi.registerCommand("monofold:list", { description: "List configured Pi Monofold workspaces", handler: listCommand });
-  pi.registerCommand("monofold_list", { description: "Alias for /monofold:list", handler: listCommand });
-  pi.registerCommand("monofold:tree", { description: "Show a tree for a configured workspace", handler: readCommand });
-  pi.registerCommand("monofold:read", { description: "Read, tree, or search a configured workspace", handler: readCommand });
-  pi.registerCommand("monofold_read", { description: "Alias for /monofold:read", handler: readCommand });
-  pi.registerCommand("monofold:search", { description: "Search a configured workspace", handler: (args, ctx) => readCommand(`search ${args}`, ctx) });
-  pi.registerCommand("monofold:write", { description: "Write a routed Markdown document", handler: writeCommand });
-  pi.registerCommand("monofold_write", { description: "Alias for /monofold:write", handler: writeCommand });
-  pi.registerCommand("monofold:git", { description: "Run guarded workspace git status, commit, or push", handler: gitCommand });
-  pi.registerCommand("monofold_git", { description: "Alias for /monofold:git", handler: gitCommand });
-  pi.registerCommand("monofold:add", { description: `Add a workspace to ${CONFIG_RELATIVE_PATH}`, handler: addCommand });
-  pi.registerCommand("monofold_add", { description: "Alias for /monofold:add", handler: addCommand });
-  pi.registerCommand("monofold:project-add", { description: "Add a project workspace under a parent workspace", handler: projectAddCommand });
-  pi.registerCommand("monofold_project_add", { description: "Alias for /monofold:project-add", handler: projectAddCommand });
+  const intentCommand = (intent: IntentCategory) => async (args: string, ctx: ExtensionCommandContext) => {
+    const prepared = await prepareIntentConfiguration(ctx);
+    if (!prepared) {
+      pi.sendUserMessage("/monofold:init", { deliverAs: "followUp" });
+      return;
+    }
+    pi.sendUserMessage(buildIntentHandoffPrompt(intent, args), { deliverAs: "followUp" });
+    sendCommandOutput(pi, `monofold:${intent.toLowerCase()}`, `Queued ${intent} handoff.`, { intent, request: args.trim() });
+  };
+
+  const guideCommand = async (args: string, _ctx: ExtensionCommandContext) => {
+    pi.sendUserMessage(buildGuideHandoffPrompt(args), { deliverAs: "followUp" });
+    sendCommandOutput(pi, "monofold:guide", "Queued Monofold guide.", { request: args.trim() });
+  };
+
+  pi.registerCommand("monofold:explore", { description: "Explore configured workspaces via natural-language handoff", handler: intentCommand("Explore") });
+  pi.registerCommand("monofold:write", { description: "Create routed Markdown via natural-language handoff", handler: intentCommand("Write") });
+  pi.registerCommand("monofold:config", { description: "Change Workspace configuration via natural-language handoff", handler: intentCommand("Config") });
+  pi.registerCommand("monofold:git", { description: "Run workspace git workflows via natural-language handoff", handler: intentCommand("Git") });
+  pi.registerCommand("monofold:guide", { description: "Conversational guide for Pi Monofold workflows", handler: guideCommand });
   pi.registerCommand("monofold:update", { description: `Migrate and validate ${CONFIG_RELATIVE_PATH}`, handler: updateCommand });
 
   const initCommand = async (_args: string, ctx: ExtensionCommandContext) => {
@@ -1395,7 +1542,7 @@ ${manifest}
       const name = await ctx.ui.input("Optional workspace name", "");
       const tagsInput = await ctx.ui.input("Tags comma-separated", "business,markdown");
       if (!tagsInput) return;
-      const capsInput = await ctx.ui.input("Capabilities comma-separated", "read,writeDocs,gitCommit");
+      const capsInput = await ctx.ui.input("Capabilities comma-separated", "read,writeDocs,git");
       if (!capsInput) return;
       const capabilities = capsInput.split(",").map((s) => s.trim()).filter(Boolean);
       const routePath = capabilities.includes("writeDocs") ? await ctx.ui.input("Default document route", "Notes") : undefined;
@@ -1422,10 +1569,6 @@ ${manifest}
     description: `Create or update ${CONFIG_RELATIVE_PATH} with an interactive wizard`,
     handler: initCommand,
   });
-  pi.registerCommand("monofold_init", {
-    description: "Alias for /monofold:init",
-    handler: initCommand,
-  });
 
   pi.registerTool({
     name: "monofold_init",
@@ -1475,4 +1618,4 @@ ${manifest}
     return undefined;
   });
 }
-
+

package/package.json

@@ -1,7 +1,8 @@
 {
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "check": "npm run typecheck && npm pack --dry-run"
+    "test": "node --import tsx --test tests/**/*.test.ts",
+    "check": "npm run typecheck && npm test && npm pack --dry-run"
   },
   "peerDependencies": {
     "typebox": "*",
@@ -10,7 +11,7 @@
   },
   "description": "Pi extension that folds multiple repositories and folders into a guarded virtual monorepo for AI agents.",
   "type": "module",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "pi": {
     "extensions": [
       "./index.ts"
@@ -19,13 +20,16 @@
   "files": [
     "README.md",
     "LICENSE",
-    "index.ts"
+    "index.ts",
+    "focus-preset.ts",
+    "validation.ts"
   ],
   "name": "pi-monofold",
   "devDependencies": {
     "typescript": "^6.0.3",
     "typebox": "^1.1.38",
     "@types/node": "^25.9.1",
+    "tsx": "^4.20.5",
     "@earendil-works/pi-coding-agent": "^0.75.4",
     "@earendil-works/pi-ai": "^0.75.4"
   },

package/validation.ts

@@ -0,0 +1,25 @@
+/** Returns true when a value is a plain object record, excluding arrays and null. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Throws when an object contains keys outside the supplied allow-list. */
+export function assertKnownKeys(label: string, value: Record<string, unknown>, allowed: Set<string>): void {
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) throw new Error(`${label} has unknown key: ${key}`);
+  }
+}
+
+/** Coerces a required or optional unknown value to a string array with strict item validation. */
+export function asStringArray(label: string, value: unknown, required = true): string[] {
+  if (value === undefined && !required) return [];
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  return value;
+}
+
+/** Removes empty strings and duplicate entries while preserving first-seen order. */
+export function uniqueStrings(items: string[]): string[] {
+  return [...new Set(items.filter(Boolean))];
+}