knowns 0.8.8 → 0.8.9

package/dist/mcp/server.js

@@ -32825,6 +32825,13 @@ function extractSection(markdown, sectionTitle) {
   }
   return lines.slice(startLine, endLine).join("\n").trim();
 }
+function extractSectionByIndex(markdown, index) {
+  const toc = extractToc(markdown);
+  if (index < 1 || index > toc.length) {
+    return null;
+  }
+  return extractSection(markdown, toc[index - 1].title);
+}
 function replaceSection(markdown, sectionTitle, newContent) {
   const lines = markdown.split("\n");
   const normalizedTarget = normalizeTitle(sectionTitle);
@@ -32914,8 +32921,10 @@ var getDocSchema = external_exports3.object({
   // Return document stats (size, tokens, headings) without content
   toc: external_exports3.boolean().optional(),
   // Return table of contents only
-  section: external_exports3.string().optional()
+  section: external_exports3.string().optional(),
   // Return specific section by heading title or number
+  smart: external_exports3.boolean().optional()
+  // Smart mode: auto-return full content if small, or stats+TOC if large
 });
 var createDocSchema = external_exports3.object({
   title: external_exports3.string(),
@@ -32954,7 +32963,7 @@ var docTools = [
   },
   {
     name: "get_doc",
-    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.",
+    description: "Get a documentation file by path. Use 'smart: true' for auto-optimized reading (recommended for AI), or 'info/toc/section' for manual control.",
     inputSchema: {
       type: "object",
       properties: {
@@ -32962,6 +32971,10 @@ var docTools = [
           type: "string",
           description: "Document path (e.g., 'readme', 'guides/setup', 'conventions/naming.md')"
         },
+        smart: {
+          type: "boolean",
+          description: "Smart mode (recommended): auto-return full content if small (\u22642000 tokens), or stats+TOC if large. Use this by default."
+        },
         info: {
           type: "boolean",
           description: "Return document stats (size, tokens, headings) without content. Use this first to decide how to read."
@@ -33112,9 +33125,10 @@ async function handleListDocs(args) {
   }
   const docs = [];
   for (const file3 of mdFiles) {
-    const content = await readFile3(join7(DOCS_DIR, file3), "utf-8");
-    const { data } = (0, import_gray_matter3.default)(content);
+    const fileContent = await readFile3(join7(DOCS_DIR, file3), "utf-8");
+    const { data, content } = (0, import_gray_matter3.default)(fileContent);
     const metadata = data;
+    const stats = calculateDocStats(content);
     if (input.tag && !metadata.tags?.includes(input.tag)) {
       continue;
     }
@@ -33123,6 +33137,7 @@ async function handleListDocs(args) {
       title: metadata.title || file3.replace(/\.md$/, ""),
       description: metadata.description,
       tags: metadata.tags,
+      tokens: stats.estimatedTokens,
       updatedAt: metadata.updatedAt
     });
   }
@@ -33140,6 +33155,33 @@ 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.smart) {
+    const stats = calculateDocStats(content);
+    const SMART_THRESHOLD = 2e3;
+    if (stats.estimatedTokens <= SMART_THRESHOLD) {
+    } else {
+      const toc = extractToc(content);
+      return successResponse({
+        doc: {
+          path: resolved.filename.replace(/\.md$/, ""),
+          title: metadata.title,
+          smart: true,
+          isLarge: true,
+          stats: {
+            chars: stats.chars,
+            estimatedTokens: stats.estimatedTokens,
+            headingCount: stats.headingCount
+          },
+          toc: toc.map((entry, index) => ({
+            index: index + 1,
+            level: entry.level,
+            title: entry.title
+          })),
+          hint: "Document is large. Use 'section' parameter with a number (e.g., section: '1') to read specific content."
+        }
+      });
+    }
+  }
   if (input.info) {
     const stats = calculateDocStats(content);
     let recommendation;
@@ -33191,7 +33233,8 @@ async function handleGetDoc(args) {
     });
   }
   if (input.section) {
-    const sectionContent = extractSection(content, input.section);
+    const sectionIndex = /^\d+$/.test(input.section) ? Number.parseInt(input.section, 10) : null;
+    const sectionContent = sectionIndex !== null ? extractSectionByIndex(content, sectionIndex) : extractSection(content, input.section);
     if (!sectionContent) {
       return errorResponse(`Section not found: ${input.section}. Use 'toc: true' to see available sections.`);
     }
@@ -33351,13 +33394,13 @@ async function handleSearchDocs(args) {
 }
 
 // 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';
+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# Always use --smart (handles both small and large docs automatically)\nknowns doc <path> --plain --smart\n\n# If doc is large, --smart returns TOC, then read specific section:\nknowns doc <path> --plain --section "2"\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### Reading Documents (--smart)\n\n**ALWAYS use `--smart` when reading documents.** It automatically handles both small and large docs:\n\n```bash\n# Always use --smart (recommended)\nknowns doc <path> --plain --smart\n```\n\n**Behavior:**\n\n- **Small doc (\u22642000 tokens)**: Returns full content automatically\n- **Large doc (>2000 tokens)**: Returns stats + TOC, then use `--section` to read specific parts\n\n```bash\n# Example with large doc:\nknowns doc readme --plain --smart\n# Output: Size: ~12,132 tokens | TOC with numbered sections\n# Hint: Use --section <number> to read specific section\n\n# Then read specific section:\nknowns doc readme --plain --section 3\n```\n\n### Manual Control (--info, --toc, --section)\n\nIf you need manual control instead of `--smart`:\n\n```bash\nknowns doc <path> --info --plain     # Check size/tokens\nknowns doc <path> --toc --plain      # View table of contents\nknowns doc <path> --section "3" --plain  # Read specific section\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/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/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';
+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## Reading Documents (--smart)\n\n**ALWAYS use `--smart` when reading documents.** It automatically handles both small and large docs:\n\n```bash\n# \u274C Reading without --smart (may get truncated large doc)\nknowns doc readme --plain\n\n# \u2705 Always use --smart\nknowns doc readme --plain --smart\n# Small doc \u2192 returns full content\n# Large doc \u2192 returns stats + TOC\n\n# \u2705 If doc is large, read specific section:\nknowns doc readme --plain --section 3\n```\n\n**`--smart` behavior:**\n\n- **\u22642000 tokens**: Returns full content automatically\n- **>2000 tokens**: Returns stats + TOC, then use `--section <number>`\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. **Always `--smart`** - Use `--smart` when reading docs (auto-handles size)\n3. **Search first** - Don\'t read all docs hoping to find info\n4. **Read selectively** - Use offset/limit for large files\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/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';
@@ -33449,13 +33492,13 @@ ${content}
 };
 
 // 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';
+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### Reading Documents (smart)\n\n**ALWAYS use `smart: true` when reading documents.** It automatically handles both small and large docs:\n\n```json\n// Always use smart (recommended)\n{\n  "path": "readme",\n  "smart": true\n}\n```\n\n**Behavior:**\n\n- **Small doc (\u22642000 tokens)**: Returns full content automatically\n- **Large doc (>2000 tokens)**: Returns stats + TOC with numbered sections\n\n```json\n// If doc is large, smart returns TOC, then read specific section:\n{\n  "path": "readme",\n  "section": "3"\n}\n```\n\n| Parameter | Description                                                    |\n| --------- | -------------------------------------------------------------- |\n| `smart`   | **Recommended.** Auto-return full content or TOC based on size |\n| `section` | Read specific section by number (e.g., "3") or title           |\n\n### Manual Control (info, toc, section)\n\nIf you need manual control instead of `smart`:\n\n```json\n{ "path": "readme", "info": true }     // Check size/tokens\n{ "path": "readme", "toc": true }      // View table of contents\n{ "path": "readme", "section": "3" }   // Read specific section\n```\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// Always use smart (handles both small and large docs automatically)\n{ "path": "<path>", "smart": true }\n\n// If doc is large, smart returns TOC, then 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/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';
+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## Reading Documents (smart)\n\n**ALWAYS use `smart: true` when reading documents.** It automatically handles both small and large docs:\n\n```json\n// DON\'T: Read without smart (may get truncated large doc)\nmcp__knowns__get_doc({ "path": "readme" })\n\n// DO: Always use smart\nmcp__knowns__get_doc({ "path": "readme", "smart": true })\n// Small doc \u2192 returns full content\n// Large doc \u2192 returns stats + TOC\n\n// DO: If doc is large, read specific section\nmcp__knowns__get_doc({ "path": "readme", "section": "3" })\n```\n\n**`smart: true` behavior:**\n\n- **\u22642000 tokens**: Returns full content automatically\n- **>2000 tokens**: Returns stats + TOC, then use `section` parameter\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. **Always `smart: true`** - Use smart when reading docs (auto-handles size)\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Use filters** - Don\'t list everything then filter manually\n4. **Read selectively** - Only fetch what you need\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";