knowns 0.8.5 → 0.8.7

package/dist/mcp/server.js

@@ -32778,14 +32778,144 @@ async function handleGetBoard(fileStore2) {
 import { existsSync as existsSync4 } from "node:fs";
 import { mkdir as mkdir3, readFile as readFile3, readdir as readdir2, writeFile as writeFile2 } from "node:fs/promises";
 import { join as join7 } from "node:path";
+
+// src/utils/markdown-toc.ts
+function extractToc(markdown) {
+  const lines = markdown.split("\n");
+  const toc = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line.match(/^(#{1,6})\s+(.+)$/);
+    if (match) {
+      const level = match[1].length;
+      const title = match[2].trim();
+      const slug = slugify2(title);
+      toc.push({ level, title, slug, line: i + 1 });
+    }
+  }
+  return toc;
+}
+function extractSection(markdown, sectionTitle) {
+  const lines = markdown.split("\n");
+  const normalizedTarget = normalizeTitle(sectionTitle);
+  let startLine = -1;
+  let startLevel = 0;
+  let endLine = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line.match(/^(#{1,6})\s+(.+)$/);
+    if (match) {
+      const level = match[1].length;
+      const title = match[2].trim();
+      if (startLine === -1) {
+        if (normalizeTitle(title) === normalizedTarget || matchesPartial(title, sectionTitle)) {
+          startLine = i;
+          startLevel = level;
+        }
+      } else {
+        if (level <= startLevel) {
+          endLine = i;
+          break;
+        }
+      }
+    }
+  }
+  if (startLine === -1) {
+    return null;
+  }
+  return lines.slice(startLine, endLine).join("\n").trim();
+}
+function replaceSection(markdown, sectionTitle, newContent) {
+  const lines = markdown.split("\n");
+  const normalizedTarget = normalizeTitle(sectionTitle);
+  let startLine = -1;
+  let startLevel = 0;
+  let endLine = lines.length;
+  let originalHeading = "";
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line.match(/^(#{1,6})\s+(.+)$/);
+    if (match) {
+      const level = match[1].length;
+      const title = match[2].trim();
+      if (startLine === -1) {
+        if (normalizeTitle(title) === normalizedTarget || matchesPartial(title, sectionTitle)) {
+          startLine = i;
+          startLevel = level;
+          originalHeading = line;
+        }
+      } else {
+        if (level <= startLevel) {
+          endLine = i;
+          break;
+        }
+      }
+    }
+  }
+  if (startLine === -1) {
+    return null;
+  }
+  const beforeSection = lines.slice(0, startLine);
+  const afterSection = lines.slice(endLine);
+  const newSection = `${originalHeading}
+
+${newContent.trim()}`;
+  return [...beforeSection, newSection, ...afterSection].join("\n");
+}
+function slugify2(title) {
+  return title.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").trim();
+}
+function normalizeTitle(title) {
+  return title.toLowerCase().replace(/[^\w\s]/g, "").replace(/\s+/g, " ").trim();
+}
+function calculateDocStats(markdown) {
+  const chars = markdown.length;
+  const words = markdown.split(/\s+/).filter((w) => w.length > 0).length;
+  const lines = markdown.split("\n").length;
+  const toc = extractToc(markdown);
+  const headingCount = toc.length;
+  const estimatedTokens = Math.ceil(chars / 3.5);
+  return {
+    chars,
+    words,
+    lines,
+    estimatedTokens,
+    headingCount
+  };
+}
+function matchesPartial(title, search) {
+  const normalizedTitle = normalizeTitle(title);
+  const normalizedSearch = normalizeTitle(search);
+  if (normalizedTitle === normalizedSearch) return true;
+  if (normalizedTitle.startsWith(normalizedSearch)) return true;
+  const numMatch = search.match(/^(\d+)\.?\s*(.*)$/);
+  if (numMatch) {
+    const [, num, rest] = numMatch;
+    const titleNumMatch = title.match(/^(\d+)\.?\s*(.*)$/);
+    if (titleNumMatch && titleNumMatch[1] === num) {
+      if (!rest || normalizeTitle(titleNumMatch[2]).startsWith(normalizeTitle(rest))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// src/mcp/handlers/doc.ts
 var import_gray_matter3 = __toESM(require_gray_matter(), 1);
 var DOCS_DIR = join7(process.cwd(), ".knowns", "docs");
 var listDocsSchema = external_exports3.object({
   tag: external_exports3.string().optional()
 });
 var getDocSchema = external_exports3.object({
-  path: external_exports3.string()
+  path: external_exports3.string(),
   // Document path (filename or folder/filename)
+  info: external_exports3.boolean().optional(),
+  // Return document stats (size, tokens, headings) without content
+  toc: external_exports3.boolean().optional(),
+  // Return table of contents only
+  section: external_exports3.string().optional()
+  // Return specific section by heading title or number
 });
 var createDocSchema = external_exports3.object({
   title: external_exports3.string(),
@@ -32802,8 +32932,10 @@ var updateDocSchema = external_exports3.object({
   description: external_exports3.string().optional(),
   content: external_exports3.string().optional(),
   tags: external_exports3.array(external_exports3.string()).optional(),
-  appendContent: external_exports3.string().optional()
+  appendContent: external_exports3.string().optional(),
   // Append to existing content
+  section: external_exports3.string().optional()
+  // Target section to replace (use with content)
 });
 var searchDocsSchema = external_exports3.object({
   query: external_exports3.string(),
@@ -32822,13 +32954,25 @@ var docTools = [
   },
   {
     name: "get_doc",
-    description: "Get a documentation file by path (filename or folder/filename)",
+    description: "Get a documentation file by path. Use 'info: true' first to check size, then 'toc: true' for table of contents, then 'section' to read specific parts.",
     inputSchema: {
       type: "object",
       properties: {
         path: {
           type: "string",
           description: "Document path (e.g., 'readme', 'guides/setup', 'conventions/naming.md')"
+        },
+        info: {
+          type: "boolean",
+          description: "Return document stats (size, tokens, headings) without content. Use this first to decide how to read."
+        },
+        toc: {
+          type: "boolean",
+          description: "Return table of contents only (list of headings). Use this first for large documents."
+        },
+        section: {
+          type: "string",
+          description: "Return specific section by heading title or number (e.g., '2. Overview' or '2'). Use after viewing TOC."
         }
       },
       required: ["path"]
@@ -32858,7 +33002,7 @@ var docTools = [
   },
   {
     name: "update_doc",
-    description: "Update an existing documentation file",
+    description: "Update an existing documentation file. Use 'section' with 'content' to replace only a specific section.",
     inputSchema: {
       type: "object",
       properties: {
@@ -32868,7 +33012,10 @@ var docTools = [
         },
         title: { type: "string", description: "New title" },
         description: { type: "string", description: "New description" },
-        content: { type: "string", description: "Replace content" },
+        content: {
+          type: "string",
+          description: "Replace content (or section content if 'section' is specified)"
+        },
         tags: {
           type: "array",
           items: { type: "string" },
@@ -32877,6 +33024,10 @@ var docTools = [
         appendContent: {
           type: "string",
           description: "Append to existing content"
+        },
+        section: {
+          type: "string",
+          description: "Target section to replace by heading title or number (use with 'content')"
         }
       },
       required: ["path"]
@@ -32989,6 +33140,70 @@ async function handleGetDoc(args) {
   const fileContent = await readFile3(resolved.filepath, "utf-8");
   const { data, content } = (0, import_gray_matter3.default)(fileContent);
   const metadata = data;
+  if (input.info) {
+    const stats = calculateDocStats(content);
+    let recommendation;
+    if (stats.estimatedTokens > 4e3) {
+      recommendation = "Document is large. Use 'toc: true' first, then 'section' to read specific parts.";
+    } else if (stats.estimatedTokens > 2e3) {
+      recommendation = "Consider using 'toc: true' and 'section' for specific info.";
+    } else {
+      recommendation = "Document is small enough to read directly.";
+    }
+    return successResponse({
+      doc: {
+        path: resolved.filename.replace(/\.md$/, ""),
+        title: metadata.title,
+        stats: {
+          chars: stats.chars,
+          words: stats.words,
+          lines: stats.lines,
+          estimatedTokens: stats.estimatedTokens,
+          headingCount: stats.headingCount
+        },
+        recommendation
+      }
+    });
+  }
+  if (input.toc) {
+    const toc = extractToc(content);
+    if (toc.length === 0) {
+      return successResponse({
+        doc: {
+          path: resolved.filename.replace(/\.md$/, ""),
+          title: metadata.title,
+          toc: [],
+          message: "No headings found in this document."
+        }
+      });
+    }
+    return successResponse({
+      doc: {
+        path: resolved.filename.replace(/\.md$/, ""),
+        title: metadata.title,
+        toc: toc.map((entry, index) => ({
+          index: index + 1,
+          level: entry.level,
+          title: entry.title
+        })),
+        hint: "Use 'section' parameter with a heading title or number to read specific content."
+      }
+    });
+  }
+  if (input.section) {
+    const sectionContent = extractSection(content, input.section);
+    if (!sectionContent) {
+      return errorResponse(`Section not found: ${input.section}. Use 'toc: true' to see available sections.`);
+    }
+    return successResponse({
+      doc: {
+        path: resolved.filename.replace(/\.md$/, ""),
+        title: metadata.title,
+        section: input.section,
+        content: sectionContent
+      }
+    });
+  }
   return successResponse({
     doc: {
       path: resolved.filename.replace(/\.md$/, ""),
@@ -33059,11 +33274,21 @@ async function handleUpdateDoc(args) {
   if (input.tags) metadata.tags = input.tags;
   metadata.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   let updatedContent = content;
-  if (input.content) {
+  let sectionUpdated;
+  if (input.section && input.content) {
+    const result = replaceSection(content, input.section, input.content);
+    if (!result) {
+      return errorResponse(
+        `Section not found: ${input.section}. Use 'toc: true' with get_doc to see available sections.`
+      );
+    }
+    updatedContent = result;
+    sectionUpdated = input.section;
+  } else if (input.content) {
     updatedContent = input.content;
   }
   if (input.appendContent) {
-    updatedContent = `${content.trimEnd()}
+    updatedContent = `${updatedContent.trimEnd()}
 
 ${input.appendContent}`;
   }
@@ -33071,13 +33296,14 @@ ${input.appendContent}`;
   await writeFile2(resolved.filepath, newFileContent, "utf-8");
   await notifyDocUpdate(resolved.filename);
   return successResponse({
-    message: `Updated documentation: ${resolved.filename}`,
+    message: sectionUpdated ? `Updated section "${sectionUpdated}" in ${resolved.filename}` : `Updated documentation: ${resolved.filename}`,
     doc: {
       path: resolved.filename.replace(/\.md$/, ""),
       title: metadata.title,
       description: metadata.description,
       tags: metadata.tags,
-      updatedAt: metadata.updatedAt
+      updatedAt: metadata.updatedAt,
+      ...sectionUpdated && { section: sectionUpdated }
     }
   });
 }
@@ -33124,68 +33350,166 @@ async function handleSearchDocs(args) {
   });
 }
 
-// src/templates/guidelines/core-rules.md
-var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion"   # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n```\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
+// src/templates/guidelines/cli/commands-reference.md
+var commands_reference_default = '# Commands Reference\n\n## task create\n\n```bash\nknowns task create <title> [options]\n```\n\n| Flag            | Short | Purpose                           |\n| --------------- | ----- | --------------------------------- |\n| `--description` | `-d`  | Task description                  |\n| `--ac`          |       | Acceptance criterion (repeatable) |\n| `--labels`      | `-l`  | Comma-separated labels            |\n| `--assignee`    | `-a`  | Assign to user \u26A0\uFE0F                 |\n| `--priority`    |       | low/medium/high                   |\n| `--status`      | `-s`  | Initial status                    |\n| `--parent`      |       | Parent task ID (raw ID only!)     |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task edit\n\n```bash\nknowns task edit <id> [options]\n```\n\n| Flag             | Short | Purpose                  |\n| ---------------- | ----- | ------------------------ |\n| `--title`        | `-t`  | Change title             |\n| `--description`  | `-d`  | Change description       |\n| `--status`       | `-s`  | Change status            |\n| `--priority`     |       | Change priority          |\n| `--labels`       | `-l`  | Set labels               |\n| `--assignee`     | `-a`  | Assign user \u26A0\uFE0F           |\n| `--parent`       |       | Move to parent           |\n| `--ac`           |       | Add acceptance criterion |\n| `--check-ac`     |       | Mark AC done (1-indexed) |\n| `--uncheck-ac`   |       | Unmark AC (1-indexed)    |\n| `--remove-ac`    |       | Delete AC (1-indexed)    |\n| `--plan`         |       | Set implementation plan  |\n| `--notes`        |       | Replace notes            |\n| `--append-notes` |       | Add to notes             |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain              # View single task\nknowns task list --plain              # List all\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain       # Tree hierarchy\n```\n\n---\n\n## doc create\n\n```bash\nknowns doc create <title> [options]\n```\n\n| Flag            | Short | Purpose              |\n| --------------- | ----- | -------------------- |\n| `--description` | `-d`  | Description          |\n| `--tags`        | `-t`  | Comma-separated tags |\n| `--folder`      | `-f`  | Folder path          |\n\n### Document Structure Best Practice\n\nWhen creating/editing docs, use clear heading structure for `--toc` and `--section` to work properly:\n\n```markdown\n# Main Title (H1 - only one)\n\n## 1. Overview\n\nBrief introduction...\n\n## 2. Installation\n\nStep-by-step guide...\n\n## 3. Configuration\n\n### 3.1 Basic Config\n\n...\n\n### 3.2 Advanced Config\n\n...\n\n## 4. API Reference\n\n...\n```\n\n**Writing rules:**\n\n- Use numbered headings (`## 1. Overview`) for easy `--section "1"` access\n- Keep H1 for title only, use H2 for main sections\n- Use H3 for subsections within H2\n- Each section should be self-contained (readable without context)\n\n**Reading workflow:**\n\n```bash\n# Step 1: Check size first\nknowns doc <path> --info --plain\n# \u2192 If <2000 tokens: read directly with --plain\n# \u2192 If >2000 tokens: continue to step 2\n\n# Step 2: Get table of contents\nknowns doc <path> --toc --plain\n\n# Step 3: Read specific section\nknowns doc <path> --section "2" --plain\n```\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag             | Short | Purpose                                   |\n| ---------------- | ----- | ----------------------------------------- |\n| `--title`        | `-t`  | Change title                              |\n| `--description`  | `-d`  | Change description                        |\n| `--tags`         |       | Set tags                                  |\n| `--content`      | `-c`  | Replace content (or section if --section) |\n| `--append`       | `-a`  | Append content \u26A0\uFE0F                         |\n| `--section`      |       | Target section to replace (use with -c)   |\n| `--content-file` |       | Content from file                         |\n| `--append-file`  |       | Append from file                          |\n\n**\u26A0\uFE0F In doc edit, `-a` = append content, NOT assignee!**\n\n### Section Edit (Context-Efficient)\n\nReplace only a specific section instead of entire document:\n\n```bash\n# Step 1: View TOC to find section\nknowns doc readme --toc --plain\n\n# Step 2: Edit only that section\nknowns doc edit readme --section "2. Installation" -c "New content here..."\nknowns doc edit readme --section "2" -c "New content..."  # By number works too\n```\n\nThis reduces context usage significantly - no need to read/write entire document.\n\n---\n\n## doc view/list\n\n```bash\nknowns doc <path> --plain             # View single doc\nknowns doc list --plain               # List all\nknowns doc list --tag api --plain     # Filter by tag\n```\n\n### Large Documents (--info, --toc, --section)\n\nFor large documents, check size first with `--info`, then use `--toc` and `--section`:\n\n```bash\n# Step 1: Check document size and token count\nknowns doc readme --info --plain\n# Output: Size: 42,461 chars (~12,132 tokens) | Headings: 83\n# Recommendation: Document is large. Use --toc first, then --section.\n\n# Step 2: View table of contents\nknowns doc readme --toc --plain\n\n# Step 3: Read specific section by title or number\nknowns doc readme --section "5. Sync" --plain\nknowns doc readme --section "3" --plain\n```\n\n**Decision flow:**\n\n- `--info` \u2192 Check size (~tokens) \u2192 If >2000 tokens, use --toc/--section\n- `--toc` \u2192 Get heading list \u2192 Choose section to read\n- `--section` \u2192 Read only what you need\n\n---\n\n## time\n\n```bash\nknowns time start <id>    # REQUIRED when taking task\nknowns time stop          # REQUIRED when completing\nknowns time pause\nknowns time resume\nknowns time status\nknowns time add <id> <duration> -n "Note" -d "2025-01-01"\n```\n\n---\n\n## search\n\n```bash\nknowns search "query" --plain\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input (Bash/Zsh)\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n';
+
+// src/templates/guidelines/cli/common-mistakes.md
+var common_mistakes_default = '# Common Mistakes\n\n## \u26A0\uFE0F CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# \u274C WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# \u2705 CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n\n## Quick Reference\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always `time start`/`stop` |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n';
 
-// src/templates/guidelines/commands-reference.md
-var commands_reference_default = '# Commands Reference\n\n## task create\n\n```bash\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Task description |\n| `--ac` | | Acceptance criterion (repeatable) |\n| `--labels` | `-l` | Comma-separated labels |\n| `--assignee` | `-a` | Assign to user \u26A0\uFE0F |\n| `--priority` | | low/medium/high |\n| `--status` | `-s` | Initial status |\n| `--parent` | | Parent task ID (raw ID only!) |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task edit\n\n```bash\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--status` | `-s` | Change status |\n| `--priority` | | Change priority |\n| `--labels` | `-l` | Set labels |\n| `--assignee` | `-a` | Assign user \u26A0\uFE0F |\n| `--parent` | | Move to parent |\n| `--ac` | | Add acceptance criterion |\n| `--check-ac` | | Mark AC done (1-indexed) |\n| `--uncheck-ac` | | Unmark AC (1-indexed) |\n| `--remove-ac` | | Delete AC (1-indexed) |\n| `--plan` | | Set implementation plan |\n| `--notes` | | Replace notes |\n| `--append-notes` | | Add to notes |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain              # View single task\nknowns task list --plain              # List all\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain       # Tree hierarchy\n```\n\n---\n\n## doc create\n\n```bash\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Description |\n| `--tags` | `-t` | Comma-separated tags |\n| `--folder` | `-f` | Folder path |\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--tags` | | Set tags |\n| `--content` | `-c` | Replace content |\n| `--append` | `-a` | Append content \u26A0\uFE0F |\n| `--content-file` | | Content from file |\n| `--append-file` | | Append from file |\n\n**\u26A0\uFE0F In doc edit, `-a` = append content, NOT assignee!**\n\n---\n\n## doc view/list\n\n```bash\nknowns doc <path> --plain             # View single doc\nknowns doc list --plain               # List all\nknowns doc list --tag api --plain     # Filter by tag\n```\n\n---\n\n## time\n\n```bash\nknowns time start <id>    # REQUIRED when taking task\nknowns time stop          # REQUIRED when completing\nknowns time pause\nknowns time resume\nknowns time status\nknowns time add <id> <duration> -n "Note" -d "2025-01-01"\n```\n\n---\n\n## search\n\n```bash\nknowns search "query" --plain\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input (Bash/Zsh)\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n';
+// src/templates/guidelines/cli/context-optimization.md
+var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Output Format\n\n```bash\n# \u274C Verbose output\nknowns task 42 --json\n\n# \u2705 Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n\n## Search Before Read\n\n```bash\n# \u274C Reading all docs to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\nknowns doc "doc3" --plain\n\n# \u2705 Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain  # Only the relevant one\n```\n\n---\n\n## Selective File Reading\n\n```bash\n# \u274C Reading entire large file\nRead file (2000+ lines)\n\n# \u2705 Read specific sections\nRead file with offset=100 limit=50\n```\n\n---\n\n## Large Documents (--info, --toc, --section)\n\nFor large documents, check size first with `--info`:\n\n```bash\n# \u274C Reading entire large document (may be truncated)\nknowns doc readme --plain\n\n# \u2705 Step 1: Check document size first\nknowns doc readme --info --plain\n# Output: Size: 42,461 chars (~12,132 tokens) | Headings: 83\n\n# \u2705 Step 2: View table of contents (if >2000 tokens)\nknowns doc readme --toc --plain\n\n# \u2705 Step 3: Read only the section you need\nknowns doc readme --section "3. Config" --plain\n```\n\n**Decision flow:** `--info` \u2192 check tokens \u2192 if >2000, use `--toc` then `--section`\n\n---\n\n## Compact Notes\n\n```bash\n# \u274C Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation of the authentication middleware which validates JWT tokens and handles refresh logic..."\n\n# \u2705 Compact notes\nknowns task edit 42 --append-notes "\u2713 Auth middleware + JWT validation done"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t                            | Do Instead                  |\n| -------------------------------- | --------------------------- |\n| Re-read files already in context | Reference from memory       |\n| List tasks/docs multiple times   | List once, remember results |\n| Quote entire file contents       | Summarize key points        |\n| Repeat full error messages       | Reference error briefly     |\n\n---\n\n## Efficient Workflow\n\n| Phase          | Context-Efficient Approach     |\n| -------------- | ------------------------------ |\n| **Research**   | Search \u2192 Read only matches     |\n| **Planning**   | Brief plan, not detailed prose |\n| **Coding**     | Read only files being modified |\n| **Notes**      | Bullet points, not paragraphs  |\n| **Completion** | Summary, not full log          |\n\n---\n\n## Quick Rules\n\n1. **Always `--plain`** - Never use `--json` unless specifically needed\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Read selectively** - Use offset/limit for large files\n4. **Use --info first** - Check doc size before reading, then --toc/--section if needed\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n7. **Summarize** - Key points, not full quotes\n';
 
-// src/templates/guidelines/workflow-completion.md
+// src/templates/guidelines/cli/core-rules.md
+var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion"   # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n```\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
+
+// src/templates/guidelines/cli/workflow-completion.md
 var workflow_completion_default = '# Task Completion\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n| Requirement | Command |\n|-------------|---------|\n| All AC checked | `knowns task edit <id> --check-ac N` |\n| Notes added | `knowns task edit <id> --notes "Summary"` |\n| Timer stopped | `knowns time stop` |\n| Status = done | `knowns task edit <id> -s done` |\n| Tests pass | Run test suite |\n\n---\n\n## Completion Steps\n\n```bash\n# 1. Verify all AC are checked\nknowns task <id> --plain\n\n# 2. Add implementation notes\nknowns task edit <id> --notes $\'## Summary\nWhat was done and key decisions.\'\n\n# 3. Stop timer (REQUIRED!)\nknowns time stop\n\n# 4. Mark done\nknowns task edit <id> -s done\n```\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n```bash\nknowns task edit <id> -s in-progress    # Reopen\nknowns time start <id>                   # Restart timer\nknowns task edit <id> --ac "Fix: description"\nknowns task edit <id> --append-notes "\u{1F504} Reopened: reason"\n# Complete work, then follow completion steps again\n```\n\n---\n\n## Checklist\n\n- [ ] All AC checked (`--check-ac`)\n- [ ] Notes added (`--notes`)\n- [ ] Timer stopped (`time stop`)\n- [ ] Tests pass\n- [ ] Status = done (`-s done`)\n';
 
-// src/templates/guidelines/workflow-creation.md
+// src/templates/guidelines/cli/workflow-creation.md
 var workflow_creation_default = '# Task Creation\n\n## Before Creating\n\n```bash\n# Search for existing tasks first\nknowns search "keyword" --type task --plain\n```\n\n---\n\n## Create Task\n\n```bash\nknowns task create "Clear title (WHAT)" \\\n  -d "Description (WHY)" \\\n  --ac "Outcome 1" \\\n  --ac "Outcome 2" \\\n  --priority medium \\\n  -l "labels"\n```\n\n---\n\n## Quality Guidelines\n\n### Title\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout |\n\n### Description\nExplain WHY. Include doc refs: `@doc/security-patterns`\n\n### Acceptance Criteria\n**Outcome-focused, NOT implementation steps:**\n\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Add handleLogin() function | User can login |\n| Use bcrypt | Passwords are hashed |\n| Add try-catch | Errors return proper HTTP codes |\n\n---\n\n## Subtasks\n\n```bash\nknowns task create "Parent task"\nknowns task create "Subtask" --parent 48  # Raw ID only!\n```\n\n---\n\n## Anti-Patterns\n\n- \u274C Too many AC in one task \u2192 Split into multiple tasks\n- \u274C Implementation steps as AC \u2192 Write outcomes instead\n- \u274C Skip search \u2192 Always check existing tasks first\n';
 
-// src/templates/guidelines/workflow-execution.md
+// src/templates/guidelines/cli/workflow-execution.md
 var workflow_execution_default = '# Task Execution\n\n## Step 1: Take Task\n\n```bash\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>    # REQUIRED!\n```\n\n---\n\n## Step 2: Research\n\n```bash\n# Read task and follow ALL refs\nknowns task <id> --plain\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search related docs\nknowns search "keyword" --type doc --plain\n\n# Check similar done tasks\nknowns search "keyword" --type task --status done --plain\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**\u26A0\uFE0F Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\nknowns task create "Follow-up: feature" -d "From task <id>"\n```\n\n**\u26A0\uFE0F Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
 
-// src/templates/guidelines/common-mistakes.md
-var common_mistakes_default = '# Common Mistakes\n\n## \u26A0\uFE0F CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# \u274C WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# \u2705 CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n\n## Quick Reference\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always `time start`/`stop` |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n';
+// src/templates/guidelines/cli/index.ts
+var CLI_CORE_RULES = core_rules_default.trim();
+var CLI_COMMANDS_REFERENCE = commands_reference_default.trim();
+var CLI_WORKFLOW_CREATION = workflow_creation_default.trim();
+var CLI_WORKFLOW_EXECUTION = workflow_execution_default.trim();
+var CLI_WORKFLOW_COMPLETION = workflow_completion_default.trim();
+var CLI_COMMON_MISTAKES = common_mistakes_default.trim();
+var CLI_CONTEXT_OPTIMIZATION = context_optimization_default.trim();
+var CLIGuidelines = {
+  // Core rules - always needed
+  core: CLI_CORE_RULES,
+  // Commands reference
+  commands: CLI_COMMANDS_REFERENCE,
+  // Workflow stages
+  workflow: {
+    creation: CLI_WORKFLOW_CREATION,
+    execution: CLI_WORKFLOW_EXECUTION,
+    completion: CLI_WORKFLOW_COMPLETION
+  },
+  // Common mistakes
+  mistakes: CLI_COMMON_MISTAKES,
+  // Context optimization
+  contextOptimization: CLI_CONTEXT_OPTIMIZATION,
+  /**
+   * Get full CLI guidelines (all sections combined)
+   */
+  getFull(withMarkers = false) {
+    const content = [
+      CLI_CORE_RULES,
+      "---",
+      CLI_CONTEXT_OPTIMIZATION,
+      "---",
+      CLI_COMMANDS_REFERENCE,
+      "---",
+      CLI_WORKFLOW_CREATION,
+      "---",
+      CLI_WORKFLOW_EXECUTION,
+      "---",
+      CLI_WORKFLOW_COMPLETION,
+      "---",
+      CLI_COMMON_MISTAKES
+    ].join("\n\n");
+    if (withMarkers) {
+      return `<!-- KNOWNS GUIDELINES START -->
+${content}
+<!-- KNOWNS GUIDELINES END -->`;
+    }
+    return content;
+  },
+  /**
+   * Get compact CLI guidelines (core + context optimization + mistakes only)
+   */
+  getCompact() {
+    return [CLI_CORE_RULES, "---", CLI_CONTEXT_OPTIMIZATION, "---", CLI_COMMON_MISTAKES].join("\n\n");
+  },
+  /**
+   * Get CLI guidelines for specific workflow stage
+   */
+  getForStage(stage) {
+    const sections = [CLI_CORE_RULES, "---", CLI_CONTEXT_OPTIMIZATION, "---"];
+    switch (stage) {
+      case "creation":
+        sections.push(CLI_WORKFLOW_CREATION);
+        break;
+      case "execution":
+        sections.push(CLI_WORKFLOW_EXECUTION);
+        sections.push("---", CLI_COMMANDS_REFERENCE);
+        break;
+      case "completion":
+        sections.push(CLI_WORKFLOW_COMPLETION);
+        break;
+    }
+    sections.push("---", CLI_COMMON_MISTAKES);
+    return sections.join("\n\n");
+  }
+};
 
-// src/templates/guidelines/context-optimization.md
-var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Output Format\n\n```bash\n# \u274C Verbose output\nknowns task 42 --json\n\n# \u2705 Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n\n## Search Before Read\n\n```bash\n# \u274C Reading all docs to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\nknowns doc "doc3" --plain\n\n# \u2705 Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain  # Only the relevant one\n```\n\n---\n\n## Selective File Reading\n\n```bash\n# \u274C Reading entire large file\nRead file (2000+ lines)\n\n# \u2705 Read specific sections\nRead file with offset=100 limit=50\n```\n\n---\n\n## Compact Notes\n\n```bash\n# \u274C Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation of the authentication middleware which validates JWT tokens and handles refresh logic..."\n\n# \u2705 Compact notes\nknowns task edit 42 --append-notes "\u2713 Auth middleware + JWT validation done"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t | Do Instead |\n|-------|------------|\n| Re-read files already in context | Reference from memory |\n| List tasks/docs multiple times | List once, remember results |\n| Quote entire file contents | Summarize key points |\n| Repeat full error messages | Reference error briefly |\n\n---\n\n## Efficient Workflow\n\n| Phase | Context-Efficient Approach |\n|-------|---------------------------|\n| **Research** | Search \u2192 Read only matches |\n| **Planning** | Brief plan, not detailed prose |\n| **Coding** | Read only files being modified |\n| **Notes** | Bullet points, not paragraphs |\n| **Completion** | Summary, not full log |\n\n---\n\n## Quick Rules\n\n1. **Always `--plain`** - Never use `--json` unless specifically needed\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Read selectively** - Use offset/limit for large files\n4. **Write concise** - Compact notes, not essays\n5. **Don\'t repeat** - Reference context already loaded\n6. **Summarize** - Key points, not full quotes\n';
+// src/templates/guidelines/mcp/commands-reference.md
+var commands_reference_default2 = '# MCP Tools Reference\n\n## mcp**knowns**create_task\n\nCreate a new task.\n\n```json\n{\n  "title": "Task title",\n  "description": "Task description",\n  "status": "todo",\n  "priority": "medium",\n  "labels": ["label1", "label2"],\n  "assignee": "@me",\n  "parent": "parent-task-id"\n}\n```\n\n| Parameter     | Required | Description                             |\n| ------------- | -------- | --------------------------------------- |\n| `title`       | Yes      | Task title                              |\n| `description` | No       | Task description                        |\n| `status`      | No       | todo/in-progress/in-review/blocked/done |\n| `priority`    | No       | low/medium/high                         |\n| `labels`      | No       | Array of labels                         |\n| `assignee`    | No       | Assignee (use @me for self)             |\n| `parent`      | No       | Parent task ID for subtasks             |\n\n**Note:** Acceptance criteria must be added via `mcp__knowns__update_task` after creation.\n\n---\n\n## mcp**knowns**update_task\n\nUpdate task fields.\n\n```json\n{\n  "taskId": "abc123",\n  "title": "New title",\n  "description": "New description",\n  "status": "in-progress",\n  "priority": "high",\n  "labels": ["updated"],\n  "assignee": "@me"\n}\n```\n\n| Parameter     | Required | Description       |\n| ------------- | -------- | ----------------- |\n| `taskId`      | Yes      | Task ID to update |\n| `title`       | No       | New title         |\n| `description` | No       | New description   |\n| `status`      | No       | New status        |\n| `priority`    | No       | New priority      |\n| `labels`      | No       | New labels array  |\n| `assignee`    | No       | New assignee      |\n\n**Note:** For acceptance criteria, implementation plan, and notes - use CLI commands or edit task file directly through knowns CLI.\n\n---\n\n## mcp**knowns**get_task\n\nGet a task by ID.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**list_tasks\n\nList tasks with optional filters.\n\n```json\n{\n  "status": "in-progress",\n  "priority": "high",\n  "assignee": "@me",\n  "label": "bug"\n}\n```\n\nAll parameters are optional filters.\n\n---\n\n## mcp**knowns**search_tasks\n\nSearch tasks by query string.\n\n```json\n{\n  "query": "authentication"\n}\n```\n\n---\n\n## mcp**knowns**get_doc\n\nGet a documentation file by path.\n\n```json\n{\n  "path": "README"\n}\n```\n\nPath can be filename or folder/filename (without .md extension).\n\n### Large Documents (info, toc, section)\n\nFor large documents, check size first with `info`, then use `toc` and `section`:\n\n```json\n// Step 1: Check document size and token count\n{\n  "path": "readme",\n  "info": true\n}\n// Response: { stats: { chars: 42461, estimatedTokens: 12132, headingCount: 83 }, recommendation: "..." }\n\n// Step 2: Get table of contents\n{\n  "path": "readme",\n  "toc": true\n}\n\n// Step 3: Read specific section by title or number\n{\n  "path": "readme",\n  "section": "5. Sync"\n}\n```\n\n| Parameter | Description                                              |\n| --------- | -------------------------------------------------------- |\n| `info`    | Set `true` to get stats (size, tokens, headings) only    |\n| `toc`     | Set `true` to get table of contents only                 |\n| `section` | Section title or number to read (e.g., "5. Sync" or "3") |\n\n**Decision flow:**\n\n- `info: true` \u2192 Check estimatedTokens \u2192 If >2000, use toc/section\n- `toc: true` \u2192 Get heading list \u2192 Choose section to read\n- `section: "X"` \u2192 Read only what you need\n\n---\n\n## mcp**knowns**list_docs\n\nList all documentation files.\n\n```json\n{\n  "tag": "api"\n}\n```\n\nOptional `tag` parameter to filter by tag.\n\n---\n\n## mcp**knowns**create_doc\n\nCreate a new documentation file.\n\n```json\n{\n  "title": "Doc Title",\n  "description": "Doc description",\n  "tags": ["tag1", "tag2"],\n  "folder": "guides",\n  "content": "Initial content"\n}\n```\n\n### Document Structure Best Practice\n\nWhen creating/updating docs, use clear heading structure for `toc` and `section` to work properly:\n\n```markdown\n# Main Title (H1 - only one)\n\n## 1. Overview\n\nBrief introduction...\n\n## 2. Installation\n\nStep-by-step guide...\n\n## 3. Configuration\n\n### 3.1 Basic Config\n\n...\n\n### 3.2 Advanced Config\n\n...\n\n## 4. API Reference\n\n...\n```\n\n**Writing rules:**\n\n- Use numbered headings (`## 1. Overview`) for easy `section: "1"` access\n- Keep H1 for title only, use H2 for main sections\n- Use H3 for subsections within H2\n- Each section should be self-contained (readable without context)\n\n**Reading workflow:**\n\n```json\n// Step 1: Check size first\n{ "path": "<path>", "info": true }\n// \u2192 If estimatedTokens <2000: read directly (no options)\n// \u2192 If estimatedTokens >2000: continue to step 2\n\n// Step 2: Get table of contents\n{ "path": "<path>", "toc": true }\n\n// Step 3: Read specific section\n{ "path": "<path>", "section": "2" }\n```\n\n---\n\n## mcp**knowns**update_doc\n\nUpdate an existing documentation file.\n\n```json\n{\n  "path": "README",\n  "title": "New Title",\n  "description": "New description",\n  "tags": ["new", "tags"],\n  "content": "Replace content",\n  "appendContent": "Append to existing"\n}\n```\n\nUse either `content` (replace) or `appendContent` (append), not both.\n\n### Section Edit (Context-Efficient)\n\nReplace only a specific section instead of entire document:\n\n```json\n// Step 1: View TOC to find section\n{ "path": "readme", "toc": true }\n\n// Step 2: Edit only that section\n{\n  "path": "readme",\n  "section": "2. Installation",\n  "content": "New content here..."\n}\n```\n\nThis reduces context usage significantly - no need to read/write entire document.\n\n---\n\n## mcp**knowns**search_docs\n\nSearch documentation by query.\n\n```json\n{\n  "query": "authentication",\n  "tag": "api"\n}\n```\n\n---\n\n## mcp**knowns**start_time\n\nStart time tracking for a task.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**stop_time\n\nStop time tracking.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**add_time\n\nManually add a time entry.\n\n```json\n{\n  "taskId": "abc123",\n  "duration": "2h30m",\n  "note": "Optional note",\n  "date": "2025-01-15"\n}\n```\n\n---\n\n## mcp**knowns**get_time_report\n\nGet time tracking report.\n\n```json\n{\n  "from": "2025-01-01",\n  "to": "2025-01-31",\n  "groupBy": "task"\n}\n```\n\n`groupBy` can be: task, label, or status.\n\n---\n\n## mcp**knowns**get_board\n\nGet current board state with tasks grouped by status.\n\n```json\n{}\n```\n\nNo parameters required.\n';
 
-// src/templates/guidelines/index.ts
-var CORE_RULES = core_rules_default.trim();
-var COMMANDS_REFERENCE = commands_reference_default.trim();
-var WORKFLOW_CREATION = workflow_creation_default.trim();
-var WORKFLOW_EXECUTION = workflow_execution_default.trim();
-var WORKFLOW_COMPLETION = workflow_completion_default.trim();
-var COMMON_MISTAKES = common_mistakes_default.trim();
-var CONTEXT_OPTIMIZATION = context_optimization_default.trim();
-var Guidelines = {
+// src/templates/guidelines/mcp/common-mistakes.md
+var common_mistakes_default2 = "# Common Mistakes (MCP)\n\n## Quick Reference\n\n| DON'T | DO |\n|-------|-----|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | Always `start_time`/`stop_time` |\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n| Use wrong task ID format | Use raw ID string |\n\n---\n\n## MCP vs CLI Usage\n\nSome operations require CLI (not available in MCP):\n\n| Operation | Tool |\n|-----------|------|\n| Add acceptance criteria | CLI: `--ac` |\n| Check/uncheck AC | CLI: `--check-ac`, `--uncheck-ac` |\n| Set implementation plan | CLI: `--plan` |\n| Add/append notes | CLI: `--notes`, `--append-notes` |\n| Create/update task basic fields | MCP tools |\n| Time tracking | MCP tools |\n| Read tasks/docs | MCP tools |\n| Search | MCP tools |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Forgot to stop timer | `mcp__knowns__add_time` with duration |\n| Wrong status | `mcp__knowns__update_task` to fix |\n| Task not found | `mcp__knowns__list_tasks` to find ID |\n| Need to uncheck AC | CLI: `knowns task edit <id> --uncheck-ac N` |\n";
+
+// src/templates/guidelines/mcp/context-optimization.md
+var context_optimization_default2 = '# Context Optimization (MCP)\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Search Before Read\n\n```json\n// DON\'T: Read all docs hoping to find info\nmcp__knowns__get_doc({ "path": "doc1" })\nmcp__knowns__get_doc({ "path": "doc2" })\nmcp__knowns__get_doc({ "path": "doc3" })\n\n// DO: Search first, then read only relevant docs\nmcp__knowns__search_docs({ "query": "authentication" })\nmcp__knowns__get_doc({ "path": "security-patterns" })  // Only the relevant one\n```\n\n---\n\n## Use Filters\n\n```json\n// DON\'T: List all tasks then filter manually\nmcp__knowns__list_tasks({})\n\n// DO: Use filters in the query\nmcp__knowns__list_tasks({\n  "status": "in-progress",\n  "assignee": "@me"\n})\n```\n\n---\n\n## Large Documents (info, toc, section)\n\nFor large documents, check size first with `info`:\n\n```json\n// DON\'T: Read entire large document (may be truncated)\nmcp__knowns__get_doc({ "path": "readme" })\n\n// DO: Step 1 - Check document size first\nmcp__knowns__get_doc({ "path": "readme", "info": true })\n// Response: { stats: { estimatedTokens: 12132 }, recommendation: "..." }\n\n// DO: Step 2 - Get table of contents (if >2000 tokens)\nmcp__knowns__get_doc({ "path": "readme", "toc": true })\n\n// DO: Step 3 - Read only the section you need\nmcp__knowns__get_doc({ "path": "readme", "section": "3. Config" })\n```\n\n**Decision flow:** `info: true` \u2192 check tokens \u2192 if >2000, use `toc` then `section`\n\n---\n\n## Compact Notes\n\n```bash\n# DON\'T: Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation..."\n\n# DO: Compact notes\nknowns task edit 42 --append-notes "Done: Auth middleware + JWT validation"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t                                 | Do Instead                  |\n| ------------------------------------- | --------------------------- |\n| Re-read tasks/docs already in context | Reference from memory       |\n| List tasks/docs multiple times        | List once, remember results |\n| Fetch same task repeatedly            | Cache the result            |\n\n---\n\n## Efficient Workflow\n\n| Phase          | Context-Efficient Approach     |\n| -------------- | ------------------------------ |\n| **Research**   | Search -> Read only matches    |\n| **Planning**   | Brief plan, not detailed prose |\n| **Coding**     | Read only files being modified |\n| **Notes**      | Bullet points, not paragraphs  |\n| **Completion** | Summary, not full log          |\n\n---\n\n## Quick Rules\n\n1. **Search first** - Don\'t read all docs hoping to find info\n2. **Use filters** - Don\'t list everything then filter manually\n3. **Read selectively** - Only fetch what you need\n4. **Use info first** - Check doc size before reading, then toc/section if needed\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n7. **Summarize** - Key points, not full quotes\n';
+
+// src/templates/guidelines/mcp/core-rules.md
+var core_rules_default2 = "# Core Rules (MCP)\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **MCP Tools Only** | Use MCP tools for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID (string) for all MCP tool calls.\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n";
+
+// src/templates/guidelines/mcp/workflow-completion.md
+var workflow_completion_default2 = '# Task Completion (MCP)\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n| Requirement | How |\n|-------------|-----|\n| All AC checked | CLI: `knowns task edit <id> --check-ac N` |\n| Notes added | CLI: `knowns task edit <id> --notes "Summary"` |\n| Timer stopped | MCP: `mcp__knowns__stop_time` |\n| Status = done | MCP: `mcp__knowns__update_task` |\n| Tests pass | Run test suite |\n\n---\n\n## Completion Steps\n\n```json\n// 1. Verify all AC are checked\nmcp__knowns__get_task({ "taskId": "abc123" })\n```\n\n```bash\n# 2. Add implementation notes (use CLI)\nknowns task edit abc123 --notes $\'## Summary\nWhat was done and key decisions.\'\n```\n\n```json\n// 3. Stop timer (REQUIRED!)\nmcp__knowns__stop_time({ "taskId": "abc123" })\n\n// 4. Mark done\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "done"\n})\n```\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n```json\n// 1. Reopen task\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "in-progress"\n})\n\n// 2. Restart timer\nmcp__knowns__start_time({ "taskId": "abc123" })\n```\n\n```bash\n# 3. Add AC for the fix\nknowns task edit abc123 --ac "Fix: description"\nknowns task edit abc123 --append-notes "Reopened: reason"\n```\n\nThen follow completion steps again.\n\n---\n\n## Checklist\n\n- [ ] All AC checked (CLI `--check-ac`)\n- [ ] Notes added (CLI `--notes`)\n- [ ] Timer stopped (`mcp__knowns__stop_time`)\n- [ ] Tests pass\n- [ ] Status = done (`mcp__knowns__update_task`)\n';
+
+// src/templates/guidelines/mcp/workflow-creation.md
+var workflow_creation_default2 = '# Task Creation (MCP)\n\n## Before Creating\n\n```json\n// Search for existing tasks first\nmcp__knowns__search_tasks({ "query": "keyword" })\n```\n\n---\n\n## Create Task\n\n```json\nmcp__knowns__create_task({\n  "title": "Clear title (WHAT)",\n  "description": "Description (WHY). Related: @doc/security-patterns",\n  "priority": "medium",\n  "labels": ["feature", "auth"]\n})\n```\n\n**Note:** Add acceptance criteria after creation using CLI:\n```bash\nknowns task edit <id> --ac "Outcome 1" --ac "Outcome 2"\n```\n\n---\n\n## Quality Guidelines\n\n### Title\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout |\n\n### Description\nExplain WHY. Include doc refs: `@doc/security-patterns`\n\n### Acceptance Criteria\n**Outcome-focused, NOT implementation steps:**\n\n| Bad | Good |\n|-----|------|\n| Add handleLogin() function | User can login |\n| Use bcrypt | Passwords are hashed |\n| Add try-catch | Errors return proper HTTP codes |\n\n---\n\n## Subtasks\n\n```json\n// Create parent first\nmcp__knowns__create_task({ "title": "Parent task" })\n\n// Then create subtask with parent ID\nmcp__knowns__create_task({\n  "title": "Subtask",\n  "parent": "parent-task-id"\n})\n```\n\n---\n\n## Anti-Patterns\n\n- Too many AC in one task -> Split into multiple tasks\n- Implementation steps as AC -> Write outcomes instead\n- Skip search -> Always check existing tasks first\n';
+
+// src/templates/guidelines/mcp/workflow-execution.md
+var workflow_execution_default2 = '# Task Execution (MCP)\n\n## Step 1: Take Task\n\n```json\n// Update status and assignee\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "in-progress",\n  "assignee": "@me"\n})\n\n// Start timer (REQUIRED!)\nmcp__knowns__start_time({ "taskId": "abc123" })\n```\n\n---\n\n## Step 2: Research\n\n```json\n// Read task and follow ALL refs\nmcp__knowns__get_task({ "taskId": "abc123" })\n\n// @.knowns/docs/xxx.md -> read the doc\nmcp__knowns__get_doc({ "path": "xxx" })\n\n// @.knowns/tasks/task-YY -> read the task\nmcp__knowns__get_task({ "taskId": "YY" })\n\n// Search related docs\nmcp__knowns__search_docs({ "query": "keyword" })\n\n// Check similar done tasks\nmcp__knowns__list_tasks({ "status": "done" })\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\nUse CLI for implementation plan:\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\nUse CLI for checking acceptance criteria:\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\n```\n\n```json\nmcp__knowns__create_task({\n  "title": "Follow-up: feature",\n  "description": "From task <id>"\n})\n```\n\n**Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
+
+// src/templates/guidelines/mcp/index.ts
+var MCP_CORE_RULES = core_rules_default2.trim();
+var MCP_COMMANDS_REFERENCE = commands_reference_default2.trim();
+var MCP_WORKFLOW_CREATION = workflow_creation_default2.trim();
+var MCP_WORKFLOW_EXECUTION = workflow_execution_default2.trim();
+var MCP_WORKFLOW_COMPLETION = workflow_completion_default2.trim();
+var MCP_COMMON_MISTAKES = common_mistakes_default2.trim();
+var MCP_CONTEXT_OPTIMIZATION = context_optimization_default2.trim();
+var MCPGuidelines = {
   // Core rules - always needed
-  core: CORE_RULES,
+  core: MCP_CORE_RULES,
   // Commands reference
-  commands: COMMANDS_REFERENCE,
+  commands: MCP_COMMANDS_REFERENCE,
   // Workflow stages
   workflow: {
-    creation: WORKFLOW_CREATION,
-    execution: WORKFLOW_EXECUTION,
-    completion: WORKFLOW_COMPLETION
+    creation: MCP_WORKFLOW_CREATION,
+    execution: MCP_WORKFLOW_EXECUTION,
+    completion: MCP_WORKFLOW_COMPLETION
   },
   // Common mistakes
-  mistakes: COMMON_MISTAKES,
+  mistakes: MCP_COMMON_MISTAKES,
   // Context optimization
-  contextOptimization: CONTEXT_OPTIMIZATION,
+  contextOptimization: MCP_CONTEXT_OPTIMIZATION,
   /**
-   * Get full guidelines (all sections combined)
+   * Get full MCP guidelines (all sections combined)
    */
   getFull(withMarkers = false) {
     const content = [
-      CORE_RULES,
+      MCP_CORE_RULES,
       "---",
-      CONTEXT_OPTIMIZATION,
+      MCP_CONTEXT_OPTIMIZATION,
       "---",
-      COMMANDS_REFERENCE,
+      MCP_COMMANDS_REFERENCE,
       "---",
-      WORKFLOW_CREATION,
+      MCP_WORKFLOW_CREATION,
       "---",
-      WORKFLOW_EXECUTION,
+      MCP_WORKFLOW_EXECUTION,
       "---",
-      WORKFLOW_COMPLETION,
+      MCP_WORKFLOW_COMPLETION,
       "---",
-      COMMON_MISTAKES
+      MCP_COMMON_MISTAKES
     ].join("\n\n");
     if (withMarkers) {
       return `<!-- KNOWNS GUIDELINES START -->
@@ -33195,33 +33519,43 @@ ${content}
     return content;
   },
   /**
-   * Get compact guidelines (core + context optimization + mistakes only)
+   * Get compact MCP guidelines (core + context optimization + mistakes only)
    */
   getCompact() {
-    return [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---", COMMON_MISTAKES].join("\n\n");
+    return [MCP_CORE_RULES, "---", MCP_CONTEXT_OPTIMIZATION, "---", MCP_COMMON_MISTAKES].join("\n\n");
   },
   /**
-   * Get guidelines for specific workflow stage
+   * Get MCP guidelines for specific workflow stage
    */
   getForStage(stage) {
-    const sections = [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---"];
+    const sections = [MCP_CORE_RULES, "---", MCP_CONTEXT_OPTIMIZATION, "---"];
     switch (stage) {
       case "creation":
-        sections.push(WORKFLOW_CREATION);
+        sections.push(MCP_WORKFLOW_CREATION);
         break;
       case "execution":
-        sections.push(WORKFLOW_EXECUTION);
-        sections.push("---", COMMANDS_REFERENCE);
+        sections.push(MCP_WORKFLOW_EXECUTION);
+        sections.push("---", MCP_COMMANDS_REFERENCE);
         break;
       case "completion":
-        sections.push(WORKFLOW_COMPLETION);
+        sections.push(MCP_WORKFLOW_COMPLETION);
         break;
     }
-    sections.push("---", COMMON_MISTAKES);
+    sections.push("---", MCP_COMMON_MISTAKES);
     return sections.join("\n\n");
   }
 };
 
+// src/templates/guidelines/index.ts
+var Guidelines = CLIGuidelines;
+var CORE_RULES = CLIGuidelines.core;
+var COMMANDS_REFERENCE = CLIGuidelines.commands;
+var WORKFLOW_CREATION = CLIGuidelines.workflow.creation;
+var WORKFLOW_EXECUTION = CLIGuidelines.workflow.execution;
+var WORKFLOW_COMPLETION = CLIGuidelines.workflow.completion;
+var COMMON_MISTAKES = CLIGuidelines.mistakes;
+var CONTEXT_OPTIMIZATION = CLIGuidelines.contextOptimization;
+
 // src/mcp/handlers/guideline.ts
 var getGuidelineSchema = external_exports3.object({
   type: external_exports3.enum(["unified", "cli", "mcp"]).optional().default("unified")
@@ -33244,7 +33578,18 @@ var guidelineTools = [
 ];
 async function handleGetGuideline(args) {
   const input = getGuidelineSchema.parse(args || {});
-  const guidelines = Guidelines.getFull();
+  let guidelines;
+  switch (input.type) {
+    case "mcp":
+      guidelines = MCPGuidelines.getFull();
+      break;
+    case "cli":
+      guidelines = Guidelines.getFull();
+      break;
+    default:
+      guidelines = MCPGuidelines.getFull();
+      break;
+  }
   return {
     content: [
       {