knowns 0.3.1 → 0.4.0

package/dist/index.js

@@ -3313,10 +3313,10 @@ var require_stringify = __commonJS({
       data = Object.assign({}, file3.data, data);
       const open = opts.delimiters[0];
       const close = opts.delimiters[1];
-      const matter9 = engine.stringify(data, options2).trim();
+      const matter10 = engine.stringify(data, options2).trim();
       let buf = "";
-      if (matter9 !== "{}") {
-        buf = newline(open) + newline(matter9) + newline(close);
+      if (matter10 !== "{}") {
+        buf = newline(open) + newline(matter10) + newline(close);
       }
       if (typeof file3.excerpt === "string" && file3.excerpt !== "") {
         if (str2.indexOf(file3.excerpt.trim()) === -1) {
@@ -3422,19 +3422,19 @@ var require_gray_matter = __commonJS({
     var toFile = require_to_file();
     var parse4 = require_parse();
     var utils = require_utils();
-    function matter9(input, options2) {
+    function matter10(input, options2) {
       if (input === "") {
         return { data: {}, content: input, excerpt: "", orig: input };
       }
       let file3 = toFile(input);
-      const cached2 = matter9.cache[file3.content];
+      const cached2 = matter10.cache[file3.content];
       if (!options2) {
         if (cached2) {
           file3 = Object.assign({}, cached2);
           file3.orig = cached2.orig;
           return file3;
         }
-        matter9.cache[file3.content] = file3;
+        matter10.cache[file3.content] = file3;
       }
       return parseMatter(file3, options2);
     }
@@ -3456,7 +3456,7 @@ var require_gray_matter = __commonJS({
       }
       str2 = str2.slice(openLen);
       const len = str2.length;
-      const language = matter9.language(str2, opts);
+      const language = matter10.language(str2, opts);
       if (language.name) {
         file3.language = language.name;
         str2 = str2.slice(language.raw.length);
@@ -3491,24 +3491,24 @@ var require_gray_matter = __commonJS({
       }
       return file3;
     }
-    matter9.engines = engines2;
-    matter9.stringify = function(file3, data, options2) {
-      if (typeof file3 === "string") file3 = matter9(file3, options2);
+    matter10.engines = engines2;
+    matter10.stringify = function(file3, data, options2) {
+      if (typeof file3 === "string") file3 = matter10(file3, options2);
       return stringify(file3, data, options2);
     };
-    matter9.read = function(filepath, options2) {
+    matter10.read = function(filepath, options2) {
       const str2 = fs.readFileSync(filepath, "utf8");
-      const file3 = matter9(str2, options2);
+      const file3 = matter10(str2, options2);
       file3.path = filepath;
       return file3;
     };
-    matter9.test = function(str2, options2) {
+    matter10.test = function(str2, options2) {
       return utils.startsWith(str2, defaults(options2).delimiters[0]);
     };
-    matter9.language = function(str2, options2) {
+    matter10.language = function(str2, options2) {
       const opts = defaults(options2);
       const open = opts.delimiters[0];
-      if (matter9.test(str2)) {
+      if (matter10.test(str2)) {
         str2 = str2.slice(open.length);
       }
       const language = str2.slice(0, str2.search(/\r?\n/));
@@ -3517,11 +3517,11 @@ var require_gray_matter = __commonJS({
         name: language ? language.trim() : ""
       };
     };
-    matter9.cache = {};
-    matter9.clearCache = function() {
-      matter9.cache = {};
+    matter10.cache = {};
+    matter10.clearCache = function() {
+      matter10.cache = {};
     };
-    module2.exports = matter9;
+    module2.exports = matter10;
   }
 });
 
@@ -46167,6 +46167,22 @@ var FileStore = class {
       return null;
     }
   }
+  /**
+   * Skipped files due to parse errors (for graceful degradation)
+   */
+  skippedFiles = [];
+  /**
+   * Get list of skipped files from last load
+   */
+  getSkippedFiles() {
+    return this.skippedFiles;
+  }
+  /**
+   * Clear skipped files list
+   */
+  clearSkippedFiles() {
+    this.skippedFiles = [];
+  }
   /**
    * Get all tasks
    */
@@ -46175,24 +46191,42 @@ var FileStore = class {
       const files = await readdir(this.tasksPath);
       const taskFiles = files.filter((f) => f.startsWith("task-") && f.endsWith(".md"));
       const allTimeEntries = await this.loadTimeEntries();
+      this.skippedFiles = [];
       const tasksMap = /* @__PURE__ */ new Map();
       for (const taskFile of taskFiles) {
-        const filePath = join2(this.tasksPath, taskFile);
-        const content = await file(filePath).text();
-        const taskData = parseTaskMarkdown(content);
-        if (taskData.id) {
-          const timeEntries = (allTimeEntries[taskData.id] || []).map((e) => ({
-            ...e,
-            startedAt: new Date(e.startedAt),
-            endedAt: e.endedAt ? new Date(e.endedAt) : void 0
-          }));
-          tasksMap.set(taskData.id, {
-            ...taskData,
-            subtasks: [],
-            timeEntries
+        try {
+          const filePath = join2(this.tasksPath, taskFile);
+          const content = await file(filePath).text();
+          const taskData = parseTaskMarkdown(content);
+          if (taskData.id) {
+            const timeEntries = (allTimeEntries[taskData.id] || []).map((e) => ({
+              ...e,
+              startedAt: new Date(e.startedAt),
+              endedAt: e.endedAt ? new Date(e.endedAt) : void 0
+            }));
+            tasksMap.set(taskData.id, {
+              ...taskData,
+              subtasks: [],
+              timeEntries
+            });
+          } else {
+            this.skippedFiles.push({
+              file: taskFile,
+              error: "Missing task ID in frontmatter"
+            });
+          }
+        } catch (parseError) {
+          this.skippedFiles.push({
+            file: taskFile,
+            error: parseError instanceof Error ? parseError.message : String(parseError)
           });
         }
       }
+      if (this.skippedFiles.length > 0) {
+        console.warn(
+          `\u26A0 Skipped ${this.skippedFiles.length} corrupted task file(s). Run "knowns task validate <id>" or "knowns task repair <id>" to fix.`
+        );
+      }
       for (const task of tasksMap.values()) {
         const subtasks = [];
         for (const otherTask of tasksMap.values()) {
@@ -46953,17 +46987,25 @@ var {
 // src/commands/init.ts
 var import_prompts2 = __toESM(require_prompts3(), 1);
 
-// src/templates/knowns-guidelines-cli.md
-var knowns_guidelines_cli_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns CLI Guidelines\n\n## Core Principles\n\n### 1. CLI-Only Operations\n**NEVER edit .md files directly. ALL operations MUST use CLI commands.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```bash\n# 1. List all available documentation\nknowns doc list --plain\n\n# 2. Read essential project docs (prioritize these)\nknowns doc "README" --plain                # Project overview\nknowns doc "ARCHITECTURE" --plain          # System design\nknowns doc "CONVENTIONS" --plain           # Coding standards\nknowns doc "API" --plain                   # API specifications\n\n# 3. Review current task backlog\nknowns task list --plain\nknowns task list --status in-progress --plain\n```\n\n### Before Taking Any Task\n\n```bash\n# 1. View the task details\nknowns task <id> --plain\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.knowns/tasks/task-44 - ... \u2192 knowns task 44 --plain\n# @.knowns/docs/patterns/module.md \u2192 knowns doc "patterns/module" --plain\n\n# 3. Search for additional related documentation\nknowns search "<keywords from task>" --type doc --plain\n\n# 4. Read ALL related docs before planning\nknowns doc "<related-doc>" --plain\n\n# 5. Check for similar completed tasks (learn from history)\nknowns search "<keywords>" --type task --status done --plain\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.knowns/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | CLI Command |\n|------|---------------------|----------------------|-------------|\n| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `knowns task <id> --plain` |\n| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `knowns doc <path> --plain` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output from `--plain`: You\'ll see `@.knowns/tasks/...` and `@.knowns/docs/...`\n> - **NEVER write** the output format (`@.knowns/...`) - always use input format (`@task-<id>`, `@doc/<path>`)\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```bash\n# Example: Task 42 output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nknowns task 44 --plain\n\n# Follow doc ref (extract path, remove .md)\nknowns doc "patterns/module" --plain\n```\n\n### Parsing Rules\n\n1. **Task refs**: `@.knowns/tasks/task-<id> - ...` \u2192 extract `<id>` \u2192 `knowns task <id> --plain`\n2. **Doc refs**: `@.knowns/docs/<path>.md` \u2192 extract `<path>` \u2192 `knowns doc "<path>" --plain`\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n  \u2192 @.knowns/docs/README.md\n    \u2192 @.knowns/docs/patterns/module.md (found in README)\n      \u2192 (read for full pattern details)\n```\n\n### When to Follow Refs\n\n| Situation | Action |\n|-----------|--------|\n| Refs in Description | ALWAYS follow - critical context |\n| Refs in Implementation Plan | Follow if implementing related work |\n| Refs in Notes | Optional - for historical context |\n| Dependency mentions | Follow if marked as blocker |\n\n### Example: Complete Ref Resolution\n\n```bash\n# 1. Read the task\n$ knowns task 42 --plain\n\n# Output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/README.md\n\n# 2. Follow task ref\n$ knowns task 44 --plain\n\n# 3. Follow doc ref\n$ knowns doc "README" --plain\n\n# 4. If README contains more refs, follow them too\n# @.knowns/docs/patterns/module.md \u2192 knowns doc "patterns/module" --plain\n\n# Now you have complete context\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```bash\n# Initialize project\nknowns init [name]\n\n# Create task with acceptance criteria\nknowns task create "Title" -d "Description" --ac "Criterion 1" --ac "Criterion 2"\n\n# View task (ALWAYS use --plain for AI)\nknowns task <id> --plain                    # Shorthand\nknowns task view <id> --plain               # Full command\n\n# View doc (ALWAYS use --plain for AI)\nknowns doc <path> --plain                   # Shorthand\nknowns doc view "<path>" --plain            # Full command\n\n# List tasks\nknowns task list --plain\n\n# Search (tasks + docs)\nknowns search "query" --plain\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```bash\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\n$ knowns doc list --plain\n\n# Output:\n# DOC: README.md\n# DOC: ARCHITECTURE.md\n# DOC: CONVENTIONS.md\n# DOC: security-patterns.md\n# DOC: api-guidelines.md\n# DOC: email-templates.md\n\n# 0b. Read essential project docs\n$ knowns doc "README" --plain\n$ knowns doc "ARCHITECTURE" --plain\n$ knowns doc "CONVENTIONS" --plain\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\n$ knowns task create "Add password reset flow" \\\n    -d "Users need ability to reset forgotten passwords via email" \\\n    --ac "User can request password reset via email" \\\n    --ac "Reset link expires after 1 hour" \\\n    --ac "User can set new password via reset link" \\\n    --ac "Unit tests cover all scenarios" \\\n    --priority high \\\n    -l "auth,feature"\n\n# Output: Created task AUTH-042\n\n# 2. Take the task and start timer (uses defaultAssignee or @me fallback)\n$ knowns task edit AUTH-042 -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\n$ knowns time start AUTH-042\n\n# Output: Timer started for AUTH-042\n\n# 3. Search for related documentation\n$ knowns search "password security" --type doc --plain\n\n# Output:\n# DOC: security-patterns.md (score: 0.92)\n# DOC: email-templates.md (score: 0.78)\n\n# 4. Read the documentation\n$ knowns doc "security-patterns" --plain\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\n$ knowns task edit AUTH-042 --plan $\'1. Review security patterns (see @doc/security-patterns)\n2. Design token generation with 1-hour expiry\n3. Create email template (see @doc/email-templates)\n4. Implement /forgot-password endpoint\n5. Implement /reset-password endpoint\n6. Add unit tests\n7. Update API documentation\'\n\n# 6. After approval, implement and check criteria as you go\n$ knowns task edit AUTH-042 --check-ac 1\n$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /forgot-password endpoint"\n\n$ knowns task edit AUTH-042 --check-ac 2\n$ knowns task edit AUTH-042 --append-notes "\u2713 Token expiry set to 1 hour"\n\n$ knowns task edit AUTH-042 --check-ac 3\n$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /reset-password endpoint"\n\n$ knowns task edit AUTH-042 --check-ac 4\n$ knowns task edit AUTH-042 --append-notes "\u2713 Added 12 unit tests, 100% coverage"\n\n# 7. Add final implementation notes\n$ knowns task edit AUTH-042 --notes $\'## Summary\nImplemented complete password reset flow with secure token generation.\n\n## Changes\n- Added POST /forgot-password endpoint\n- Added POST /reset-password endpoint\n- Created password_reset_tokens table\n- Added email template for reset link\n\n## Security\n- Tokens use crypto.randomBytes(32)\n- 1-hour expiry enforced at DB level\n- Rate limiting: 3 requests per hour per email\n\n## Tests\n- 12 unit tests added\n- Coverage: 100% for new code\n\n## Documentation\n- Updated API.md with new endpoints\'\n\n# 8. Stop timer and complete\n$ knowns time stop\n$ knowns task edit AUTH-042 -s done\n\n# Output: Task AUTH-042 marked as done\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```bash\n# Assign using defaultAssignee from config (falls back to @me if not set)\nknowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\n```\n\n> **Note**: The `defaultAssignee` is configured in `.knowns/config.json` during `knowns init`. If not set, `@me` is used as fallback. To update: `knowns config set defaultAssignee "@username"`\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```bash\nknowns time start <id>\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```bash\n# Search for related docs\nknowns search "authentication" --type doc --plain\n\n# View relevant documents\nknowns doc "API Guidelines" --plain\nknowns doc "Security Patterns" --plain\n\n# Also check for similar completed tasks\nknowns search "auth" --type task --status done --plain\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning! Understanding existing patterns and conventions prevents rework and ensures consistency.\n\n### Step 4: Create Implementation Plan\n\n```bash\nknowns task edit <id> --plan $\'1. Research patterns (see @doc/security-patterns)\n2. Design middleware\n3. Implement\n4. Add tests\n5. Update docs\'\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```bash\n# Work through implementation plan step by step\n# IMPORTANT: Only check AC AFTER completing the work, not before\n\n# After completing work for AC #1:\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Completed: <brief description>"\n\n# After completing work for AC #2:\nknowns task edit <id> --check-ac 2\nknowns task edit <id> --append-notes "\u2713 Completed: <brief description>"\n```\n\n> **CRITICAL**: Never check an AC before the work is actually done. ACs represent completed outcomes, not intentions.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```bash\n# Add new acceptance criteria\nknowns task edit <id> --ac "New requirement from user"\n\n# Update implementation plan to include new steps\nknowns task edit <id> --plan $\'1. Original step 1\n2. Original step 2\n3. NEW: Handle user request for X\n4. Continue with remaining work\'\n\n# Append note about scope change\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```bash\n# Add comprehensive notes (suitable for PR description)\nknowns task edit <id> --notes $\'## Summary\n\nImplemented JWT auth.\n\n## Changes\n- Added middleware\n- Added tests\'\n\n# OR append progressively (recommended)\nknowns task edit <id> --append-notes "\u2713 Implemented middleware"\nknowns task edit <id> --append-notes "\u2713 Added tests"\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```bash\nknowns time stop\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry: `knowns time add <id> <duration> -n "Forgot to stop timer"`\n\n### Step 9: Complete Task\n\n```bash\nknowns task edit <id> -s done\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```bash\n# 1. Reopen task - set back to in-progress\nknowns task edit <id> -s in-progress\n\n# 2. Restart time tracking (REQUIRED)\nknowns time start <id>\n\n# 3. Add new AC for the changes requested\nknowns task edit <id> --ac "Post-completion fix: <description>"\n\n# 4. Document the reopen reason\nknowns task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - <reason>"\n\n# 5. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Add AC for traceability\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```bash\n# Search if similar pattern already documented\nknowns search "<pattern/concept>" --type doc --plain\n\n# If new knowledge, create a doc for future reference\nknowns doc create "Pattern: <Name>" \\\n    -d "Reusable pattern discovered during task implementation" \\\n    -t "pattern,<domain>" \\\n    -f "patterns"\n\n# Or append to existing doc\nknowns doc edit "<existing-doc>" -a "## New Section\\n\\nLearned from task <id>: ..."\n\n# Reference the source task\nknowns doc edit "<doc-name>" -a "\\n\\n> Source: @task-<id>"\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential Commands\n\n### Task Management\n\n```bash\n# Create task\nknowns task create "Title" -d "Description" --ac "Criterion" -l "labels" --priority high\n\n# Edit task\nknowns task edit <id> -t "New title"\nknowns task edit <id> -d "New description"\nknowns task edit <id> -s in-progress\nknowns task edit <id> --priority high\nknowns task edit <id> -a <assignee>              # $(knowns config get defaultAssignee --plain || echo "@me")\n\n# Acceptance Criteria\nknowns task edit <id> --ac "New criterion"           # Add\nknowns task edit <id> --check-ac 1 --check-ac 2      # Check (1-indexed)\nknowns task edit <id> --uncheck-ac 2                 # Uncheck\nknowns task edit <id> --remove-ac 3                  # Remove\n\n# Implementation Plan & Notes\nknowns task edit <id> --plan $\'1. Step\\n2. Step\'\nknowns task edit <id> --notes "Implementation summary"\nknowns task edit <id> --append-notes "Progress update"\n\n# View & List\nknowns task <id> --plain                             # Shorthand (ALWAYS use --plain)\nknowns task view <id> --plain                        # Full command\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --assignee <assignee> --plain   # $(knowns config get defaultAssignee --plain || echo "@me")\nknowns task list --tree --plain                      # Tree hierarchy\n```\n\n### Time Tracking\n\n```bash\n# Timer\nknowns time start <id>\nknowns time stop\nknowns time pause\nknowns time resume\nknowns time status\n\n# Manual entry\nknowns time add <id> 2h -n "Note" -d "2025-12-25"\n\n# Reports\nknowns time report --from "2025-12-01" --to "2025-12-31"\nknowns time report --by-label --csv > report.csv\n```\n\n### Documentation\n\n```bash\n# List & View\nknowns doc list --plain\nknowns doc list --tag architecture --plain\nknowns doc <path> --plain                          # Shorthand (ALWAYS use --plain)\nknowns doc view "<path>" --plain                   # Full command\n\n# Create (with optional folder)\nknowns doc create "Title" -d "Description" -t "tags"\nknowns doc create "Title" -d "Description" -t "tags" -f "folder/path"\n\n# Edit metadata\nknowns doc edit "Doc Name" -t "New Title" --tags "new,tags"\n\n# Edit content\nknowns doc edit "Doc Name" -c "New content"        # Replace content\nknowns doc edit "Doc Name" -a "Appended content"   # Append to content\n```\n\n### Search\n\n```bash\n# Search everything\nknowns search "query" --plain\n\n# Search specific type\nknowns search "auth" --type task --plain\nknowns search "patterns" --type doc --plain\n\n# Filter\nknowns search "bug" --status in-progress --priority high --plain\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```markdown\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n### Implementation Plan\n\nHOW to solve. Added AFTER taking task, BEFORE coding.\n\n```markdown\n1. Research JWT libraries (see @doc/security-patterns)\n2. Design token structure (access + refresh tokens)\n3. Implement auth middleware\n4. Add unit tests (aim for 90%+ coverage)\n5. Update API.md with new endpoints\n```\n\n### Implementation Notes\n\nSummary for PR description. Added AFTER completion.\n\n```markdown\n## Summary\nImplemented JWT auth using jsonwebtoken library.\n\n## Changes\n- Added auth middleware in src/middleware/auth.ts\n- Added /login and /refresh endpoints\n- Created JWT utility functions\n\n## Tests\n- Added 15 unit tests\n- Coverage: 94%\n\n## Documentation\n- Updated API.md with authentication section\n```\n\n---\n\n## Error Handling\n\n### Common Errors and Solutions\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Error: Task not found` | Invalid task ID | Run `knowns task list --plain` to find correct ID |\n| `Error: No active timer` | Calling `time stop` without active timer | Start timer first: `knowns time start <id>` |\n| `Error: Timer already running` | Starting timer when one is active | Stop current: `knowns time stop` |\n| `Error: Invalid status` | Wrong status format | Use lowercase with hyphens: `in-progress`, not `In Progress` |\n| `Error: AC index out of range` | Checking non-existent criterion | View task first: `knowns task <id> --plain` |\n| `Error: Document not found` | Wrong document name | Run `knowns doc list --plain` to find correct name |\n| `Error: Not initialized` | Running commands without init | Run `knowns init` first |\n\n### Debugging Commands\n\n```bash\n# Check CLI version\nknowns --version\n\n# Verify project is initialized\nknowns status\n\n# View raw task data (for debugging)\nknowns task <id> --json\n\n# Check timer status\nknowns time status\n```\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via CLI (Required)\n\n- [ ] All acceptance criteria checked: `--check-ac <index>` (only after work is actually done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] \u23F1\uFE0F Timer stopped: `knowns time stop` (MANDATORY - do not skip!)\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\nUse **lowercase with hyphens**:\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use `knowns task edit` |\n| Change `- [ ]` to `- [x]` in file | Use `--check-ac <index>` |\n| Check AC before completing work | Only check AC AFTER work is actually done |\n| Skip time tracking | ALWAYS use `time start` and `time stop` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Skip `knowns doc list` on new project | Always list docs when starting |\n| Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |\n| Plan without checking docs | Read docs before planning |\n| Ignore similar completed tasks | Search done tasks for patterns |\n| Missing doc links in description/plan | Link docs using `@doc/<path>` |\n| Write refs as `@.knowns/docs/...` or `@.knowns/tasks/...` | Use input format: `@doc/<path>`, `@task-<id>` |\n| Forget `--plain` flag | Always use `--plain` for AI |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Check ALL criteria first |\n| Write implementation steps in AC | Write outcome-oriented criteria |\n| Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |\n| Use `@yourself` or unknown assignee | Use `$(knowns config get defaultAssignee --plain \\|\\| echo "@me")` |\n| Ignore refs in task description | Follow ALL refs (`@.knowns/...`) before planning |\n| See `@.knowns/docs/...` but don\'t read | Use `knowns doc "<path>" --plain` |\n| See `@.knowns/tasks/task-X` but don\'t check | Use `knowns task X --plain` for context |\n| Follow only first-level refs | Recursively follow nested refs until complete |\n\n---\n\n## Platform-Specific Notes\n\n### Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash / Zsh (Recommended)**\n```bash\nknowns task edit <id> --plan $\'1. First step\\n2. Second step\\n3. Third step\'\n```\n\n**PowerShell**\n```powershell\nknowns task edit <id> --plan "1. First step`n2. Second step`n3. Third step"\n```\n\n**Cross-platform (Using printf)**\n```bash\nknowns task edit <id> --plan "$(printf \'1. First step\\n2. Second step\\n3. Third step\')"\n```\n\n**Using heredoc (for long content)**\n```bash\nknowns task edit <id> --plan "$(cat <<EOF\n1. First step\n2. Second step\n3. Third step\nEOF\n)"\n```\n\n### Path Separators\n\n- **Unix/macOS**: Use forward slashes: `./docs/api.md`\n- **Windows**: Both work, but prefer forward slashes for consistency\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `knowns doc list --plain`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task has clear acceptance criteria\n- [ ] ALL refs in task followed (`@.knowns/...`)\n- [ ] Nested refs recursively followed until complete context gathered\n- [ ] Related docs searched: `knowns search "keyword" --type doc --plain`\n- [ ] ALL relevant docs read: `knowns doc "Doc Name" --plain`\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self: `-a $(knowns config get defaultAssignee --plain || echo "@me")`\n- [ ] Status set to in-progress: `-s in-progress`\n- [ ] Timer started: `knowns time start <id>`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Criteria checked as completed: `--check-ac <index>`\n- [ ] Progress notes appended: `--append-notes "\u2713 ..."`\n\n### After Work\n\n- [ ] All acceptance criteria checked (only after work is done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] Timer stopped: `knowns time stop`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable): patterns, solutions, conventions\n\n---\n\n## Quick Reference Card\n\n```bash\n# === AGENT INITIALIZATION (Once per session) ===\nknowns doc list --plain\nknowns doc "README" --plain\nknowns doc "ARCHITECTURE" --plain\nknowns doc "CONVENTIONS" --plain\n\n# === FULL WORKFLOW ===\nknowns task create "Title" -d "Description" --ac "Criterion"\nknowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\nknowns time start <id>                                     # \u23F1\uFE0F REQUIRED: Start timer\nknowns search "keyword" --type doc --plain\nknowns doc "Doc Name" --plain\nknowns search "keyword" --type task --status done --plain  # Learn from history\nknowns task edit <id> --plan $\'1. Step (see @doc/file)\\n2. Step\'\n# ... wait for approval, then implement ...\n# Only check AC AFTER completing the work:\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Completed: feature X"\nknowns task edit <id> --check-ac 2\nknowns task edit <id> --append-notes "\u2713 Completed: feature Y"\nknowns time stop                                           # \u23F1\uFE0F REQUIRED: Stop timer\nknowns task edit <id> -s done\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nknowns task <id> --plain                                   # Shorthand for view\nknowns task list --plain\nknowns task list --status in-progress --assignee $(knowns config get defaultAssignee --plain || echo "@me") --plain\nknowns search "query" --plain\nknowns search "bug" --type task --status in-progress --plain\n\n# === TIME TRACKING ===\nknowns time start <id>\nknowns time stop\nknowns time status\nknowns time report --from "2025-12-01" --to "2025-12-31"\n\n# === DOCUMENTATION ===\nknowns doc list --plain\nknowns doc "path/doc-name" --plain                         # Shorthand for view\nknowns doc create "Title" -d "Description" -t "tags" -f "folder"\nknowns doc edit "doc-name" -c "New content"\nknowns doc edit "doc-name" -a "Appended content"\n```\n\n---\n\n**Maintained By**: Knowns CLI Team\n\n<!-- KNOWNS GUIDELINES END -->\n';
-
-// src/templates/knowns-guidelines-mcp.md
-var knowns_guidelines_mcp_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns MCP Guidelines\n\n## Core Principles\n\n### 1. MCP Tool Operations\n**Use MCP tools for ALL Knowns operations. NEVER edit .md files directly.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```\n# 1. List all available documentation\nmcp__knowns__list_docs({})\n\n# 2. Read essential project docs (prioritize these)\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\nmcp__knowns__get_doc({ path: "API" })\n\n# 3. Review current task backlog\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\n```\n\n### Before Taking Any Task\n\n```\n# 1. View the task details\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.knowns/tasks/task-44 - ... \u2192 mcp__knowns__get_task({ taskId: "44" })\n# @.knowns/docs/patterns/module.md \u2192 mcp__knowns__get_doc({ path: "patterns/module" })\n\n# 3. Search for additional related documentation\nmcp__knowns__search_docs({ query: "<keywords from task>" })\n\n# 4. Read ALL related docs before planning\nmcp__knowns__get_doc({ path: "<related-doc>" })\n\n# 5. Check for similar completed tasks (learn from history)\nmcp__knowns__search_tasks({ query: "<keywords>", status: "done" })\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.knowns/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | MCP Tool |\n|------|---------------------|----------------------|----------|\n| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `mcp__knowns__get_task({ taskId: "<id>" })` |\n| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `mcp__knowns__get_doc({ path: "<path>" })` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output: You\'ll see `@.knowns/tasks/...` and `@.knowns/docs/...`\n> - **NEVER write** the output format (`@.knowns/...`) - always use input format\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```\n# Example: Task 42 output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nmcp__knowns__get_task({ taskId: "44" })\n\n# Follow doc ref (extract path, remove .md)\nmcp__knowns__get_doc({ path: "patterns/module" })\n```\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n  \u2192 @.knowns/docs/README.md\n    \u2192 @.knowns/docs/patterns/module.md (found in README)\n      \u2192 (read for full pattern details)\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```\n# Initialize project (use CLI for this)\nknowns init [name]\n\n# Create task with acceptance criteria\nmcp__knowns__create_task({\n  title: "Title",\n  description: "Description",\n  priority: "high",\n  labels: ["label1", "label2"]\n})\n\n# View task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# List tasks\nmcp__knowns__list_tasks({})\n\n# Search (tasks + docs)\nmcp__knowns__search_tasks({ query: "query" })\nmcp__knowns__search_docs({ query: "query" })\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\nmcp__knowns__list_docs({})\n\n# 0b. Read essential project docs\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\nmcp__knowns__create_task({\n  title: "Add password reset flow",\n  description: "Users need ability to reset forgotten passwords via email",\n  priority: "high",\n  labels: ["auth", "feature"]\n})\n\n# Output: Created task 42\n\n# 2. Take the task and start timer\nmcp__knowns__update_task({\n  taskId: "42",\n  status: "in-progress",\n  assignee: "@howznguyen"\n})\nmcp__knowns__start_time({ taskId: "42" })\n\n# 3. Search for related documentation\nmcp__knowns__search_docs({ query: "password security" })\n\n# 4. Read the documentation\nmcp__knowns__get_doc({ path: "security-patterns" })\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\nmcp__knowns__update_task({\n  taskId: "42",\n  plan: "1. Review security patterns (see @doc/security-patterns)\\n2. Design token generation with 1-hour expiry\\n3. Implement /forgot-password endpoint\\n4. Add unit tests"\n})\n\n# 6. After approval, implement and update task progressively\nmcp__knowns__update_task({\n  taskId: "42",\n  appendNotes: "\u2713 Implemented /forgot-password endpoint"\n})\n\n# 7. Add final implementation notes\nmcp__knowns__update_task({\n  taskId: "42",\n  notes: "## Summary\\nImplemented complete password reset flow.\\n\\n## Changes\\n- Added POST /forgot-password endpoint\\n- Added POST /reset-password endpoint"\n})\n\n# 8. Stop timer and complete\nmcp__knowns__stop_time({ taskId: "42" })\nmcp__knowns__update_task({\n  taskId: "42",\n  status: "done"\n})\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```\n# Update task status and assign to self\nmcp__knowns__update_task({\n  taskId: "<id>",\n  status: "in-progress",\n  assignee: "@<your-username>"\n})\n```\n\n> **Note**: Use your username as configured in the project. Check project config for `defaultAssignee`.\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```\nmcp__knowns__start_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```\n# Search for related docs\nmcp__knowns__search_docs({ query: "authentication" })\n\n# View relevant documents\nmcp__knowns__get_doc({ path: "API Guidelines" })\nmcp__knowns__get_doc({ path: "Security Patterns" })\n\n# Also check for similar completed tasks\nmcp__knowns__search_tasks({ query: "auth", status: "done" })\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning!\n\n### Step 4: Create Implementation Plan\n\n```\nmcp__knowns__update_task({\n  taskId: "<id>",\n  plan: "1. Research patterns (see @doc/security-patterns)\\n2. Design middleware\\n3. Implement\\n4. Add tests\\n5. Update docs"\n})\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```\n# Work through implementation plan step by step\n# IMPORTANT: Only update task AFTER completing the work, not before\n\n# After completing work, append notes:\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u2713 Completed: <brief description>"\n})\n```\n\n> **CRITICAL**: Never claim work is done before it\'s actually completed.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```\n# Append note about scope change\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n})\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```\n# Add comprehensive notes (suitable for PR description)\nmcp__knowns__update_task({\n  taskId: "<id>",\n  notes: "## Summary\\n\\nImplemented JWT auth.\\n\\n## Changes\\n- Added middleware\\n- Added tests"\n})\n\n# OR append progressively (recommended)\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u2713 Implemented middleware"\n})\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```\nmcp__knowns__stop_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry:\n> `mcp__knowns__add_time({ taskId: "<id>", duration: "2h", note: "Forgot to stop timer" })`\n\n### Step 9: Complete Task\n\n```\nmcp__knowns__update_task({\n  taskId: "<id>",\n  status: "done"\n})\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```\n# 1. Reopen task - set back to in-progress\nmcp__knowns__update_task({\n  taskId: "<id>",\n  status: "in-progress"\n})\n\n# 2. Restart time tracking (REQUIRED)\nmcp__knowns__start_time({ taskId: "<id>" })\n\n# 3. Document the reopen reason\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u{1F504} Reopened: User requested changes - <reason>"\n})\n\n# 4. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```\n# Search if similar pattern already documented\nmcp__knowns__search_docs({ query: "<pattern/concept>" })\n\n# If new knowledge, create a doc for future reference\nmcp__knowns__create_doc({\n  title: "Pattern: <Name>",\n  description: "Reusable pattern discovered during task implementation",\n  tags: ["pattern", "<domain>"],\n  folder: "patterns"\n})\n\n# Or append to existing doc\nmcp__knowns__update_doc({\n  path: "<existing-doc>",\n  appendContent: "## New Section\\n\\nLearned from task <id>: ..."\n})\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential MCP Tools\n\n### Task Management\n\n```\n# Create task\nmcp__knowns__create_task({\n  title: "Title",\n  description: "Description",\n  priority: "high",        # low, medium, high\n  labels: ["label1"],\n  status: "todo",          # todo, in-progress, in-review, done, blocked\n  assignee: "@username"\n})\n\n# Get task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# Update task\nmcp__knowns__update_task({\n  taskId: "<id>",\n  title: "New title",\n  description: "New description",\n  status: "in-progress",\n  priority: "high",\n  assignee: "@username",\n  labels: ["new", "labels"],\n  plan: "Implementation plan...",\n  notes: "Implementation notes...",\n  appendNotes: "Append to existing notes..."\n})\n\n# List tasks\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\nmcp__knowns__list_tasks({ assignee: "@username" })\nmcp__knowns__list_tasks({ priority: "high" })\nmcp__knowns__list_tasks({ label: "feature" })\n\n# Search tasks\nmcp__knowns__search_tasks({ query: "auth" })\n```\n\n### Time Tracking\n\n```\n# Start timer\nmcp__knowns__start_time({ taskId: "<id>" })\n\n# Stop timer\nmcp__knowns__stop_time({ taskId: "<id>" })\n\n# Manual entry\nmcp__knowns__add_time({\n  taskId: "<id>",\n  duration: "2h",           # e.g., "2h", "30m", "1h30m"\n  note: "Optional note",\n  date: "2025-12-25"        # Optional, defaults to now\n})\n\n# Reports\nmcp__knowns__get_time_report({})\nmcp__knowns__get_time_report({\n  from: "2025-12-01",\n  to: "2025-12-31",\n  groupBy: "task"           # task, label, status\n})\n```\n\n### Documentation\n\n```\n# List docs\nmcp__knowns__list_docs({})\nmcp__knowns__list_docs({ tag: "architecture" })\n\n# Get doc\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "patterns/module" })\n\n# Create doc\nmcp__knowns__create_doc({\n  title: "Title",\n  description: "Description",\n  tags: ["tag1", "tag2"],\n  folder: "folder/path",    # Optional\n  content: "Initial content..."\n})\n\n# Update doc\nmcp__knowns__update_doc({\n  path: "doc-name",\n  title: "New Title",\n  description: "New description",\n  tags: ["new", "tags"],\n  content: "Replace content...",\n  appendContent: "Append to content..."\n})\n\n# Search docs\nmcp__knowns__search_docs({ query: "patterns" })\nmcp__knowns__search_docs({ query: "auth", tag: "security" })\n```\n\n### Board\n\n```\n# Get kanban board view\nmcp__knowns__get_board({})\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via MCP Tools (Required)\n\n- [ ] All work completed and verified\n- [ ] Implementation notes added via `update_task`\n- [ ] \u23F1\uFE0F Timer stopped: `mcp__knowns__stop_time` (MANDATORY - do not skip!)\n- [ ] Status set to done via `update_task`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | ALWAYS use `start_time` and `stop_time` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Plan without checking docs | Read docs before planning |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Verify ALL criteria first |\n| Ignore refs in task description | Follow ALL refs before planning |\n| Follow only first-level refs | Recursively follow nested refs |\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `mcp__knowns__list_docs({})`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task details retrieved: `mcp__knowns__get_task`\n- [ ] ALL refs in task followed\n- [ ] Nested refs recursively followed\n- [ ] Related docs searched and read\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self via `update_task`\n- [ ] Status set to in-progress\n- [ ] Timer started: `mcp__knowns__start_time`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Progress notes appended: `appendNotes`\n\n### After Work\n\n- [ ] All work verified complete\n- [ ] Implementation notes added\n- [ ] Timer stopped: `mcp__knowns__stop_time`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done\n- [ ] Knowledge extracted to docs (if applicable)\n\n---\n\n## Quick Reference\n\n```\n# === AGENT INITIALIZATION (Once per session) ===\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\n\n# === FULL WORKFLOW ===\nmcp__knowns__create_task({ title: "Title", description: "Description" })\nmcp__knowns__update_task({ taskId: "<id>", status: "in-progress", assignee: "@me" })\nmcp__knowns__start_time({ taskId: "<id>" })                    # \u23F1\uFE0F REQUIRED\nmcp__knowns__search_docs({ query: "keyword" })\nmcp__knowns__get_doc({ path: "Doc Name" })\nmcp__knowns__search_tasks({ query: "keyword", status: "done" }) # Learn from history\nmcp__knowns__update_task({ taskId: "<id>", plan: "1. Step\\n2. Step" })\n# ... wait for approval, then implement ...\nmcp__knowns__update_task({ taskId: "<id>", appendNotes: "\u2713 Completed: feature X" })\nmcp__knowns__stop_time({ taskId: "<id>" })                     # \u23F1\uFE0F REQUIRED\nmcp__knowns__update_task({ taskId: "<id>", status: "done" })\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nmcp__knowns__get_task({ taskId: "<id>" })\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress", assignee: "@me" })\nmcp__knowns__search_tasks({ query: "bug" })\nmcp__knowns__search_docs({ query: "pattern" })\n\n# === TIME TRACKING ===\nmcp__knowns__start_time({ taskId: "<id>" })\nmcp__knowns__stop_time({ taskId: "<id>" })\nmcp__knowns__add_time({ taskId: "<id>", duration: "2h" })\nmcp__knowns__get_time_report({})\n\n# === DOCUMENTATION ===\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "path/doc-name" })\nmcp__knowns__create_doc({ title: "Title", description: "Desc", tags: ["tag"] })\nmcp__knowns__update_doc({ path: "doc-name", appendContent: "New content" })\n```\n\n---\n\n**Maintained By**: Knowns CLI Team\n\n<!-- KNOWNS GUIDELINES END -->\n';
-
 // src/commands/agents.ts
 import { existsSync } from "node:fs";
 import { mkdir as mkdir3, readFile as readFile2, writeFile as writeFile2 } from "node:fs/promises";
 import { dirname, join as join3 } from "node:path";
 var import_prompts = __toESM(require_prompts3(), 1);
+
+// src/templates/cli/gemini.md
+var gemini_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns CLI - Gemini Quick Reference\n\n## RULES\n- NEVER edit .md files directly - use CLI only\n- ALWAYS use `--plain` flag\n- Read docs BEFORE coding\n- Start timer when taking task, stop when done\n\n## SESSION START\n```bash\nknowns doc list --plain\nknowns doc "README" --plain\nknowns task list --plain\n```\n\n## TASK WORKFLOW\n\n### 1. Take Task\n```bash\nknowns task <id> --plain              # View task\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>\n```\n\n### 2. Read Context\n```bash\nknowns doc list "guides/" --plain     # List by folder\nknowns doc "path/name" --plain        # View doc\nknowns search "keyword" --type doc --plain\n```\n\n### 3. Plan & Implement\n```bash\nknowns task edit <id> --plan $\'1. Step one\\n2. Step two\'\n# Wait for approval, then code\nknowns task edit <id> --check-ac 1    # Check criteria after done\nknowns task edit <id> --append-notes "Done: feature X"\n```\n\n### 4. Complete\n```bash\nknowns time stop\nknowns task edit <id> -s done\n```\n\n## COMMANDS CHEATSHEET\n\n### Task\n```bash\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task <id> --plain\nknowns task create "Title" -d "Desc" --ac "Criterion" --priority high\nknowns task edit <id> -s <status> -a @me\nknowns task edit <id> --check-ac 1 --check-ac 2\nknowns task edit <id> --plan "..."\nknowns task edit <id> --notes "..."\nknowns task edit <id> --append-notes "..."\n```\n\n### Doc\n```bash\nknowns doc list --plain\nknowns doc list "folder/" --plain\nknowns doc "name" --plain\nknowns doc create "Title" -d "Desc" -t "tags" -f "folder"\nknowns doc edit "name" -c "content"\nknowns doc edit "name" -a "append"\nknowns doc edit "name" --content-file ./file.md\nknowns doc edit "name" --append-file ./file.md\nknowns doc search-in "name" "query" --plain\nknowns doc replace "name" "old" "new"\n```\n\n### Time\n```bash\nknowns time start <id>\nknowns time stop\nknowns time status\nknowns time add <id> 2h -n "Note"\n```\n\n### Search\n```bash\nknowns search "query" --plain\nknowns search "query" --type doc --plain\nknowns search "query" --type task --plain\n```\n\n## REFS\n\n### Reading (output format)\n- `@.knowns/tasks/task-X - Title.md` \u2192 `knowns task X --plain`\n- `@.knowns/docs/path/name.md` \u2192 `knowns doc "path/name" --plain`\n\n### Writing (input format)\n- Task: `@task-X`\n- Doc: `@doc/path/name`\n\n## STATUS & PRIORITY\n\n**Status:** `todo`, `in-progress`, `in-review`, `blocked`, `done`\n**Priority:** `low`, `medium`, `high`\n\n## LONG CONTENT\n\nWindows has ~8191 char limit. Use:\n\n```bash\n# Append in chunks\nknowns doc edit "name" -a "Section 1..."\nknowns doc edit "name" -a "Section 2..."\n\n# Or file-based\nknowns doc edit "name" --content-file ./content.md\nknowns doc edit "name" --append-file ./more.md\n```\n\n## VALIDATE & REPAIR\n\n```bash\nknowns doc validate "name" --plain\nknowns doc repair "name" --plain\nknowns task validate <id> --plain\nknowns task repair <id> --plain\n```\n<!-- KNOWNS GUIDELINES END -->\n';
+
+// src/templates/cli/general.md
+var general_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns CLI Guidelines\n\n## Core Principles\n\n### 1. CLI-Only Operations\n**NEVER edit .md files directly. ALL operations MUST use CLI commands.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```bash\n# 1. List all available documentation\nknowns doc list --plain\n\n# 2. Read essential project docs (prioritize these)\nknowns doc "README" --plain                # Project overview\nknowns doc "ARCHITECTURE" --plain          # System design\nknowns doc "CONVENTIONS" --plain           # Coding standards\nknowns doc "API" --plain                   # API specifications\n\n# 3. Review current task backlog\nknowns task list --plain\nknowns task list --status in-progress --plain\n```\n\n### Before Taking Any Task\n\n```bash\n# 1. View the task details\nknowns task <id> --plain\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.knowns/tasks/task-44 - ... \u2192 knowns task 44 --plain\n# @.knowns/docs/patterns/module.md \u2192 knowns doc "patterns/module" --plain\n\n# 3. Search for additional related documentation\nknowns search "<keywords from task>" --type doc --plain\n\n# 4. Read ALL related docs before planning\nknowns doc "<related-doc>" --plain\n\n# 5. Check for similar completed tasks (learn from history)\nknowns search "<keywords>" --type task --status done --plain\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.knowns/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | CLI Command |\n|------|---------------------|----------------------|-------------|\n| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `knowns task <id> --plain` |\n| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `knowns doc <path> --plain` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output from `--plain`: You\'ll see `@.knowns/tasks/...` and `@.knowns/docs/...`\n> - **NEVER write** the output format (`@.knowns/...`) - always use input format (`@task-<id>`, `@doc/<path>`)\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```bash\n# Example: Task 42 output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nknowns task 44 --plain\n\n# Follow doc ref (extract path, remove .md)\nknowns doc "patterns/module" --plain\n```\n\n### Parsing Rules\n\n1. **Task refs**: `@.knowns/tasks/task-<id> - ...` \u2192 extract `<id>` \u2192 `knowns task <id> --plain`\n2. **Doc refs**: `@.knowns/docs/<path>.md` \u2192 extract `<path>` \u2192 `knowns doc "<path>" --plain`\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n  \u2192 @.knowns/docs/README.md\n    \u2192 @.knowns/docs/patterns/module.md (found in README)\n      \u2192 (read for full pattern details)\n```\n\n### When to Follow Refs\n\n| Situation | Action |\n|-----------|--------|\n| Refs in Description | ALWAYS follow - critical context |\n| Refs in Implementation Plan | Follow if implementing related work |\n| Refs in Notes | Optional - for historical context |\n| Dependency mentions | Follow if marked as blocker |\n\n### Example: Complete Ref Resolution\n\n```bash\n# 1. Read the task\n$ knowns task 42 --plain\n\n# Output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/README.md\n\n# 2. Follow task ref\n$ knowns task 44 --plain\n\n# 3. Follow doc ref\n$ knowns doc "README" --plain\n\n# 4. If README contains more refs, follow them too\n# @.knowns/docs/patterns/module.md \u2192 knowns doc "patterns/module" --plain\n\n# Now you have complete context\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```bash\n# Initialize project\nknowns init [name]\n\n# Create task with acceptance criteria\nknowns task create "Title" -d "Description" --ac "Criterion 1" --ac "Criterion 2"\n\n# View task (ALWAYS use --plain for AI)\nknowns task <id> --plain                    # Shorthand\nknowns task view <id> --plain               # Full command\n\n# View doc (ALWAYS use --plain for AI)\nknowns doc <path> --plain                   # Shorthand\nknowns doc view "<path>" --plain            # Full command\n\n# List tasks\nknowns task list --plain\n\n# Search (tasks + docs)\nknowns search "query" --plain\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```bash\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\n$ knowns doc list --plain\n\n# Output:\n# DOC: README.md\n# DOC: ARCHITECTURE.md\n# DOC: CONVENTIONS.md\n# DOC: security-patterns.md\n# DOC: api-guidelines.md\n# DOC: email-templates.md\n\n# 0b. Read essential project docs\n$ knowns doc "README" --plain\n$ knowns doc "ARCHITECTURE" --plain\n$ knowns doc "CONVENTIONS" --plain\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\n$ knowns task create "Add password reset flow" \\\n    -d "Users need ability to reset forgotten passwords via email" \\\n    --ac "User can request password reset via email" \\\n    --ac "Reset link expires after 1 hour" \\\n    --ac "User can set new password via reset link" \\\n    --ac "Unit tests cover all scenarios" \\\n    --priority high \\\n    -l "auth,feature"\n\n# Output: Created task AUTH-042\n\n# 2. Take the task and start timer (uses defaultAssignee or @me fallback)\n$ knowns task edit AUTH-042 -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\n$ knowns time start AUTH-042\n\n# Output: Timer started for AUTH-042\n\n# 3. Search for related documentation\n$ knowns search "password security" --type doc --plain\n\n# Output:\n# DOC: security-patterns.md (score: 0.92)\n# DOC: email-templates.md (score: 0.78)\n\n# 4. Read the documentation\n$ knowns doc "security-patterns" --plain\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\n$ knowns task edit AUTH-042 --plan $\'1. Review security patterns (see @doc/security-patterns)\n2. Design token generation with 1-hour expiry\n3. Create email template (see @doc/email-templates)\n4. Implement /forgot-password endpoint\n5. Implement /reset-password endpoint\n6. Add unit tests\n7. Update API documentation\'\n\n# 6. After approval, implement and check criteria as you go\n$ knowns task edit AUTH-042 --check-ac 1\n$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /forgot-password endpoint"\n\n$ knowns task edit AUTH-042 --check-ac 2\n$ knowns task edit AUTH-042 --append-notes "\u2713 Token expiry set to 1 hour"\n\n$ knowns task edit AUTH-042 --check-ac 3\n$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /reset-password endpoint"\n\n$ knowns task edit AUTH-042 --check-ac 4\n$ knowns task edit AUTH-042 --append-notes "\u2713 Added 12 unit tests, 100% coverage"\n\n# 7. Add final implementation notes\n$ knowns task edit AUTH-042 --notes $\'## Summary\nImplemented complete password reset flow with secure token generation.\n\n## Changes\n- Added POST /forgot-password endpoint\n- Added POST /reset-password endpoint\n- Created password_reset_tokens table\n- Added email template for reset link\n\n## Security\n- Tokens use crypto.randomBytes(32)\n- 1-hour expiry enforced at DB level\n- Rate limiting: 3 requests per hour per email\n\n## Tests\n- 12 unit tests added\n- Coverage: 100% for new code\n\n## Documentation\n- Updated API.md with new endpoints\'\n\n# 8. Stop timer and complete\n$ knowns time stop\n$ knowns task edit AUTH-042 -s done\n\n# Output: Task AUTH-042 marked as done\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```bash\n# Assign using defaultAssignee from config (falls back to @me if not set)\nknowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\n```\n\n> **Note**: The `defaultAssignee` is configured in `.knowns/config.json` during `knowns init`. If not set, `@me` is used as fallback. To update: `knowns config set defaultAssignee "@username"`\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```bash\nknowns time start <id>\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```bash\n# Search for related docs\nknowns search "authentication" --type doc --plain\n\n# View relevant documents\nknowns doc "API Guidelines" --plain\nknowns doc "Security Patterns" --plain\n\n# Also check for similar completed tasks\nknowns search "auth" --type task --status done --plain\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning! Understanding existing patterns and conventions prevents rework and ensures consistency.\n\n### Step 4: Create Implementation Plan\n\n```bash\nknowns task edit <id> --plan $\'1. Research patterns (see @doc/security-patterns)\n2. Design middleware\n3. Implement\n4. Add tests\n5. Update docs\'\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```bash\n# Work through implementation plan step by step\n# IMPORTANT: Only check AC AFTER completing the work, not before\n\n# After completing work for AC #1:\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Completed: <brief description>"\n\n# After completing work for AC #2:\nknowns task edit <id> --check-ac 2\nknowns task edit <id> --append-notes "\u2713 Completed: <brief description>"\n```\n\n> **CRITICAL**: Never check an AC before the work is actually done. ACs represent completed outcomes, not intentions.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```bash\n# Add new acceptance criteria\nknowns task edit <id> --ac "New requirement from user"\n\n# Update implementation plan to include new steps\nknowns task edit <id> --plan $\'1. Original step 1\n2. Original step 2\n3. NEW: Handle user request for X\n4. Continue with remaining work\'\n\n# Append note about scope change\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```bash\n# Add comprehensive notes (suitable for PR description)\nknowns task edit <id> --notes $\'## Summary\n\nImplemented JWT auth.\n\n## Changes\n- Added middleware\n- Added tests\'\n\n# OR append progressively (recommended)\nknowns task edit <id> --append-notes "\u2713 Implemented middleware"\nknowns task edit <id> --append-notes "\u2713 Added tests"\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```bash\nknowns time stop\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry: `knowns time add <id> <duration> -n "Forgot to stop timer"`\n\n### Step 9: Complete Task\n\n```bash\nknowns task edit <id> -s done\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```bash\n# 1. Reopen task - set back to in-progress\nknowns task edit <id> -s in-progress\n\n# 2. Restart time tracking (REQUIRED)\nknowns time start <id>\n\n# 3. Add new AC for the changes requested\nknowns task edit <id> --ac "Post-completion fix: <description>"\n\n# 4. Document the reopen reason\nknowns task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - <reason>"\n\n# 5. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Add AC for traceability\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```bash\n# Search if similar pattern already documented\nknowns search "<pattern/concept>" --type doc --plain\n\n# If new knowledge, create a doc for future reference\nknowns doc create "Pattern: <Name>" \\\n    -d "Reusable pattern discovered during task implementation" \\\n    -t "pattern,<domain>" \\\n    -f "patterns"\n\n# Or append to existing doc\nknowns doc edit "<existing-doc>" -a "## New Section\\n\\nLearned from task <id>: ..."\n\n# Reference the source task\nknowns doc edit "<doc-name>" -a "\\n\\n> Source: @task-<id>"\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential Commands\n\n### Task Management\n\n```bash\n# Create task\nknowns task create "Title" -d "Description" --ac "Criterion" -l "labels" --priority high\n\n# Edit task\nknowns task edit <id> -t "New title"\nknowns task edit <id> -d "New description"\nknowns task edit <id> -s in-progress\nknowns task edit <id> --priority high\nknowns task edit <id> -a <assignee>              # $(knowns config get defaultAssignee --plain || echo "@me")\n\n# Acceptance Criteria\nknowns task edit <id> --ac "New criterion"           # Add\nknowns task edit <id> --check-ac 1 --check-ac 2      # Check (1-indexed)\nknowns task edit <id> --uncheck-ac 2                 # Uncheck\nknowns task edit <id> --remove-ac 3                  # Remove\n\n# Implementation Plan & Notes\nknowns task edit <id> --plan $\'1. Step\\n2. Step\'\nknowns task edit <id> --notes "Implementation summary"\nknowns task edit <id> --append-notes "Progress update"\n\n# View & List\nknowns task <id> --plain                             # Shorthand (ALWAYS use --plain)\nknowns task view <id> --plain                        # Full command\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --assignee <assignee> --plain   # $(knowns config get defaultAssignee --plain || echo "@me")\nknowns task list --tree --plain                      # Tree hierarchy\n```\n\n### Time Tracking\n\n```bash\n# Timer\nknowns time start <id>\nknowns time stop\nknowns time pause\nknowns time resume\nknowns time status\n\n# Manual entry\nknowns time add <id> 2h -n "Note" -d "2025-12-25"\n\n# Reports\nknowns time report --from "2025-12-01" --to "2025-12-31"\nknowns time report --by-label --csv > report.csv\n```\n\n### Documentation\n\n```bash\n# List & View\nknowns doc list --plain\nknowns doc list --tag architecture --plain\nknowns doc <path> --plain                          # Shorthand (ALWAYS use --plain)\nknowns doc view "<path>" --plain                   # Full command\n\n# Create (with optional folder)\nknowns doc create "Title" -d "Description" -t "tags"\nknowns doc create "Title" -d "Description" -t "tags" -f "folder/path"\n\n# Edit metadata\nknowns doc edit "Doc Name" -t "New Title" --tags "new,tags"\n\n# Edit content\nknowns doc edit "Doc Name" -c "New content"        # Replace content\nknowns doc edit "Doc Name" -a "Appended content"   # Append to content\n```\n\n### Search\n\n```bash\n# Search everything\nknowns search "query" --plain\n\n# Search specific type\nknowns search "auth" --type task --plain\nknowns search "patterns" --type doc --plain\n\n# Filter\nknowns search "bug" --status in-progress --priority high --plain\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```markdown\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n### Implementation Plan\n\nHOW to solve. Added AFTER taking task, BEFORE coding.\n\n```markdown\n1. Research JWT libraries (see @doc/security-patterns)\n2. Design token structure (access + refresh tokens)\n3. Implement auth middleware\n4. Add unit tests (aim for 90%+ coverage)\n5. Update API.md with new endpoints\n```\n\n### Implementation Notes\n\nSummary for PR description. Added AFTER completion.\n\n```markdown\n## Summary\nImplemented JWT auth using jsonwebtoken library.\n\n## Changes\n- Added auth middleware in src/middleware/auth.ts\n- Added /login and /refresh endpoints\n- Created JWT utility functions\n\n## Tests\n- Added 15 unit tests\n- Coverage: 94%\n\n## Documentation\n- Updated API.md with authentication section\n```\n\n---\n\n## Error Handling\n\n### Common Errors and Solutions\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Error: Task not found` | Invalid task ID | Run `knowns task list --plain` to find correct ID |\n| `Error: No active timer` | Calling `time stop` without active timer | Start timer first: `knowns time start <id>` |\n| `Error: Timer already running` | Starting timer when one is active | Stop current: `knowns time stop` |\n| `Error: Invalid status` | Wrong status format | Use lowercase with hyphens: `in-progress`, not `In Progress` |\n| `Error: AC index out of range` | Checking non-existent criterion | View task first: `knowns task <id> --plain` |\n| `Error: Document not found` | Wrong document name | Run `knowns doc list --plain` to find correct name |\n| `Error: Not initialized` | Running commands without init | Run `knowns init` first |\n\n### Debugging Commands\n\n```bash\n# Check CLI version\nknowns --version\n\n# Verify project is initialized\nknowns status\n\n# View raw task data (for debugging)\nknowns task <id> --json\n\n# Check timer status\nknowns time status\n```\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via CLI (Required)\n\n- [ ] All acceptance criteria checked: `--check-ac <index>` (only after work is actually done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] \u23F1\uFE0F Timer stopped: `knowns time stop` (MANDATORY - do not skip!)\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\nUse **lowercase with hyphens**:\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use `knowns task edit` |\n| Change `- [ ]` to `- [x]` in file | Use `--check-ac <index>` |\n| Check AC before completing work | Only check AC AFTER work is actually done |\n| Skip time tracking | ALWAYS use `time start` and `time stop` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Skip `knowns doc list` on new project | Always list docs when starting |\n| Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |\n| Plan without checking docs | Read docs before planning |\n| Ignore similar completed tasks | Search done tasks for patterns |\n| Missing doc links in description/plan | Link docs using `@doc/<path>` |\n| Write refs as `@.knowns/docs/...` or `@.knowns/tasks/...` | Use input format: `@doc/<path>`, `@task-<id>` |\n| Forget `--plain` flag | Always use `--plain` for AI |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Check ALL criteria first |\n| Write implementation steps in AC | Write outcome-oriented criteria |\n| Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |\n| Use `@yourself` or unknown assignee | Use `$(knowns config get defaultAssignee --plain \\|\\| echo "@me")` |\n| Ignore refs in task description | Follow ALL refs (`@.knowns/...`) before planning |\n| See `@.knowns/docs/...` but don\'t read | Use `knowns doc "<path>" --plain` |\n| See `@.knowns/tasks/task-X` but don\'t check | Use `knowns task X --plain` for context |\n| Follow only first-level refs | Recursively follow nested refs until complete |\n\n---\n\n## Platform-Specific Notes\n\n### Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash / Zsh (Recommended)**\n```bash\nknowns task edit <id> --plan $\'1. First step\\n2. Second step\\n3. Third step\'\n```\n\n**PowerShell**\n```powershell\nknowns task edit <id> --plan "1. First step`n2. Second step`n3. Third step"\n```\n\n**Cross-platform (Using printf)**\n```bash\nknowns task edit <id> --plan "$(printf \'1. First step\\n2. Second step\\n3. Third step\')"\n```\n\n**Using heredoc (for long content)**\n```bash\nknowns task edit <id> --plan "$(cat <<EOF\n1. First step\n2. Second step\n3. Third step\nEOF\n)"\n```\n\n### Path Separators\n\n- **Unix/macOS**: Use forward slashes: `./docs/api.md`\n- **Windows**: Both work, but prefer forward slashes for consistency\n\n### Windows Command Line Limit\n\nWindows has ~8191 character limit. For long content, append in chunks:\n\n```bash\n# 1. Create or reset with short content\nknowns doc edit "doc-name" -c "## Overview\\n\\nShort intro."\n\n# 2. Append each section separately\nknowns doc edit "doc-name" -a "## Section 1\\n\\nContent..."\nknowns doc edit "doc-name" -a "## Section 2\\n\\nMore content..."\n```\n\nOr use file-based options:\n\n```bash\nknowns doc edit "doc-name" --content-file ./content.md\nknowns doc edit "doc-name" --append-file ./more.md\n```\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `knowns doc list --plain`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task has clear acceptance criteria\n- [ ] ALL refs in task followed (`@.knowns/...`)\n- [ ] Nested refs recursively followed until complete context gathered\n- [ ] Related docs searched: `knowns search "keyword" --type doc --plain`\n- [ ] ALL relevant docs read: `knowns doc "Doc Name" --plain`\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self: `-a $(knowns config get defaultAssignee --plain || echo "@me")`\n- [ ] Status set to in-progress: `-s in-progress`\n- [ ] Timer started: `knowns time start <id>`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Criteria checked as completed: `--check-ac <index>`\n- [ ] Progress notes appended: `--append-notes "\u2713 ..."`\n\n### After Work\n\n- [ ] All acceptance criteria checked (only after work is done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] Timer stopped: `knowns time stop`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable): patterns, solutions, conventions\n\n---\n\n## Quick Reference Card\n\n```bash\n# === AGENT INITIALIZATION (Once per session) ===\nknowns doc list --plain\nknowns doc "README" --plain\nknowns doc "ARCHITECTURE" --plain\nknowns doc "CONVENTIONS" --plain\n\n# === FULL WORKFLOW ===\nknowns task create "Title" -d "Description" --ac "Criterion"\nknowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\nknowns time start <id>                                     # \u23F1\uFE0F REQUIRED: Start timer\nknowns search "keyword" --type doc --plain\nknowns doc "Doc Name" --plain\nknowns search "keyword" --type task --status done --plain  # Learn from history\nknowns task edit <id> --plan $\'1. Step (see @doc/file)\\n2. Step\'\n# ... wait for approval, then implement ...\n# Only check AC AFTER completing the work:\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Completed: feature X"\nknowns task edit <id> --check-ac 2\nknowns task edit <id> --append-notes "\u2713 Completed: feature Y"\nknowns time stop                                           # \u23F1\uFE0F REQUIRED: Stop timer\nknowns task edit <id> -s done\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nknowns task <id> --plain                                   # Shorthand for view\nknowns task list --plain\nknowns task list --status in-progress --assignee $(knowns config get defaultAssignee --plain || echo "@me") --plain\nknowns search "query" --plain\nknowns search "bug" --type task --status in-progress --plain\n\n# === TIME TRACKING ===\nknowns time start <id>\nknowns time stop\nknowns time status\nknowns time report --from "2025-12-01" --to "2025-12-31"\n\n# === DOCUMENTATION ===\nknowns doc list --plain\nknowns doc "path/doc-name" --plain                         # Shorthand for view\nknowns doc create "Title" -d "Description" -t "tags" -f "folder"\nknowns doc edit "doc-name" -c "New content"\nknowns doc edit "doc-name" -a "Appended content"\n```\n\n---\n\n**Maintained By**: Knowns CLI Team\n\n<!-- KNOWNS GUIDELINES END -->\n';
+
+// src/templates/mcp/gemini.md
+var gemini_default2 = '<!-- KNOWNS GUIDELINES START -->\n# Knowns MCP - Gemini Quick Reference\n\n## RULES\n- NEVER edit .md files directly - use MCP tools only\n- Read docs BEFORE coding\n- Start timer when taking task, stop when done\n\n## SESSION START\n```\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__list_tasks({})\n```\n\n## TASK WORKFLOW\n\n### 1. Take Task\n```\nmcp__knowns__get_task({ taskId: "<id>" })\nmcp__knowns__update_task({ taskId: "<id>", status: "in-progress", assignee: "@me" })\nmcp__knowns__start_time({ taskId: "<id>" })\n```\n\n### 2. Read Context\n```\nmcp__knowns__list_docs({ tag: "guides" })\nmcp__knowns__get_doc({ path: "path/name" })\nmcp__knowns__search_docs({ query: "keyword" })\n```\n\n### 3. Plan & Implement\n```\nmcp__knowns__update_task({ taskId: "<id>", description: "Updated with plan..." })\n// Wait for approval, then code\nmcp__knowns__update_task({ taskId: "<id>", labels: ["done-ac-1"] })\n```\n\n### 4. Complete\n```\nmcp__knowns__stop_time({ taskId: "<id>" })\nmcp__knowns__update_task({ taskId: "<id>", status: "done" })\n```\n\n## MCP TOOLS CHEATSHEET\n\n### Task\n```\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\nmcp__knowns__get_task({ taskId: "<id>" })\nmcp__knowns__create_task({ title: "Title", description: "Desc", priority: "high" })\nmcp__knowns__update_task({ taskId: "<id>", status: "<status>", assignee: "@me" })\nmcp__knowns__search_tasks({ query: "keyword" })\n```\n\n### Doc\n```\nmcp__knowns__list_docs({})\nmcp__knowns__list_docs({ tag: "patterns" })\nmcp__knowns__get_doc({ path: "name" })\nmcp__knowns__create_doc({ title: "Title", description: "Desc", tags: ["tag1"] })\nmcp__knowns__update_doc({ path: "name", content: "new content" })\nmcp__knowns__update_doc({ path: "name", appendContent: "more content" })\nmcp__knowns__search_docs({ query: "keyword" })\n```\n\n### Time\n```\nmcp__knowns__start_time({ taskId: "<id>" })\nmcp__knowns__stop_time({ taskId: "<id>" })\nmcp__knowns__add_time({ taskId: "<id>", duration: "2h", note: "Note" })\nmcp__knowns__get_time_report({})\n```\n\n### Board\n```\nmcp__knowns__get_board({})\n```\n\n## REFS\n\n### Reading (output format)\n- `@.knowns/tasks/task-X - Title.md` \u2192 `mcp__knowns__get_task({ taskId: "X" })`\n- `@.knowns/docs/path/name.md` \u2192 `mcp__knowns__get_doc({ path: "path/name" })`\n\n### Writing (input format)\n- Task: `@task-X`\n- Doc: `@doc/path/name`\n\n## STATUS & PRIORITY\n\n**Status:** `todo`, `in-progress`, `in-review`, `blocked`, `done`\n**Priority:** `low`, `medium`, `high`\n\n## LONG CONTENT\n\nFor large docs, append in chunks:\n```\n# Create with initial content\nmcp__knowns__create_doc({ title: "Title", content: "## Overview\\n\\nIntro." })\n\n# Append sections\nmcp__knowns__update_doc({ path: "name", appendContent: "## Section 1\\n\\n..." })\nmcp__knowns__update_doc({ path: "name", appendContent: "## Section 2\\n\\n..." })\n```\n<!-- KNOWNS GUIDELINES END -->\n';
+
+// src/templates/mcp/general.md
+var general_default2 = '<!-- KNOWNS GUIDELINES START -->\n# Knowns MCP Guidelines\n\n## Core Principles\n\n### 1. MCP Tool Operations\n**Use MCP tools for ALL Knowns operations. NEVER edit .md files directly.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```\n# 1. List all available documentation\nmcp__knowns__list_docs({})\n\n# 2. Read essential project docs (prioritize these)\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\nmcp__knowns__get_doc({ path: "API" })\n\n# 3. Review current task backlog\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\n```\n\n### Before Taking Any Task\n\n```\n# 1. View the task details\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.knowns/tasks/task-44 - ... \u2192 mcp__knowns__get_task({ taskId: "44" })\n# @.knowns/docs/patterns/module.md \u2192 mcp__knowns__get_doc({ path: "patterns/module" })\n\n# 3. Search for additional related documentation\nmcp__knowns__search_docs({ query: "<keywords from task>" })\n\n# 4. Read ALL related docs before planning\nmcp__knowns__get_doc({ path: "<related-doc>" })\n\n# 5. Check for similar completed tasks (learn from history)\nmcp__knowns__search_tasks({ query: "<keywords>", status: "done" })\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.knowns/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | MCP Tool |\n|------|---------------------|----------------------|----------|\n| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `mcp__knowns__get_task({ taskId: "<id>" })` |\n| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `mcp__knowns__get_doc({ path: "<path>" })` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output: You\'ll see `@.knowns/tasks/...` and `@.knowns/docs/...`\n> - **NEVER write** the output format (`@.knowns/...`) - always use input format\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```\n# Example: Task 42 output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nmcp__knowns__get_task({ taskId: "44" })\n\n# Follow doc ref (extract path, remove .md)\nmcp__knowns__get_doc({ path: "patterns/module" })\n```\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n  \u2192 @.knowns/docs/README.md\n    \u2192 @.knowns/docs/patterns/module.md (found in README)\n      \u2192 (read for full pattern details)\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```\n# Initialize project (use CLI for this)\nknowns init [name]\n\n# Create task with acceptance criteria\nmcp__knowns__create_task({\n  title: "Title",\n  description: "Description",\n  priority: "high",\n  labels: ["label1", "label2"]\n})\n\n# View task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# List tasks\nmcp__knowns__list_tasks({})\n\n# Search (tasks + docs)\nmcp__knowns__search_tasks({ query: "query" })\nmcp__knowns__search_docs({ query: "query" })\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\nmcp__knowns__list_docs({})\n\n# 0b. Read essential project docs\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\nmcp__knowns__create_task({\n  title: "Add password reset flow",\n  description: "Users need ability to reset forgotten passwords via email",\n  priority: "high",\n  labels: ["auth", "feature"]\n})\n\n# Output: Created task 42\n\n# 2. Take the task and start timer\nmcp__knowns__update_task({\n  taskId: "42",\n  status: "in-progress",\n  assignee: "@howznguyen"\n})\nmcp__knowns__start_time({ taskId: "42" })\n\n# 3. Search for related documentation\nmcp__knowns__search_docs({ query: "password security" })\n\n# 4. Read the documentation\nmcp__knowns__get_doc({ path: "security-patterns" })\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\nmcp__knowns__update_task({\n  taskId: "42",\n  plan: "1. Review security patterns (see @doc/security-patterns)\\n2. Design token generation with 1-hour expiry\\n3. Implement /forgot-password endpoint\\n4. Add unit tests"\n})\n\n# 6. After approval, implement and update task progressively\nmcp__knowns__update_task({\n  taskId: "42",\n  appendNotes: "\u2713 Implemented /forgot-password endpoint"\n})\n\n# 7. Add final implementation notes\nmcp__knowns__update_task({\n  taskId: "42",\n  notes: "## Summary\\nImplemented complete password reset flow.\\n\\n## Changes\\n- Added POST /forgot-password endpoint\\n- Added POST /reset-password endpoint"\n})\n\n# 8. Stop timer and complete\nmcp__knowns__stop_time({ taskId: "42" })\nmcp__knowns__update_task({\n  taskId: "42",\n  status: "done"\n})\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```\n# Update task status and assign to self\nmcp__knowns__update_task({\n  taskId: "<id>",\n  status: "in-progress",\n  assignee: "@<your-username>"\n})\n```\n\n> **Note**: Use your username as configured in the project. Check project config for `defaultAssignee`.\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```\nmcp__knowns__start_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```\n# Search for related docs\nmcp__knowns__search_docs({ query: "authentication" })\n\n# View relevant documents\nmcp__knowns__get_doc({ path: "API Guidelines" })\nmcp__knowns__get_doc({ path: "Security Patterns" })\n\n# Also check for similar completed tasks\nmcp__knowns__search_tasks({ query: "auth", status: "done" })\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning!\n\n### Step 4: Create Implementation Plan\n\n```\nmcp__knowns__update_task({\n  taskId: "<id>",\n  plan: "1. Research patterns (see @doc/security-patterns)\\n2. Design middleware\\n3. Implement\\n4. Add tests\\n5. Update docs"\n})\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```\n# Work through implementation plan step by step\n# IMPORTANT: Only update task AFTER completing the work, not before\n\n# After completing work, append notes:\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u2713 Completed: <brief description>"\n})\n```\n\n> **CRITICAL**: Never claim work is done before it\'s actually completed.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```\n# Append note about scope change\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n})\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```\n# Add comprehensive notes (suitable for PR description)\nmcp__knowns__update_task({\n  taskId: "<id>",\n  notes: "## Summary\\n\\nImplemented JWT auth.\\n\\n## Changes\\n- Added middleware\\n- Added tests"\n})\n\n# OR append progressively (recommended)\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u2713 Implemented middleware"\n})\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```\nmcp__knowns__stop_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry:\n> `mcp__knowns__add_time({ taskId: "<id>", duration: "2h", note: "Forgot to stop timer" })`\n\n### Step 9: Complete Task\n\n```\nmcp__knowns__update_task({\n  taskId: "<id>",\n  status: "done"\n})\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```\n# 1. Reopen task - set back to in-progress\nmcp__knowns__update_task({\n  taskId: "<id>",\n  status: "in-progress"\n})\n\n# 2. Restart time tracking (REQUIRED)\nmcp__knowns__start_time({ taskId: "<id>" })\n\n# 3. Document the reopen reason\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u{1F504} Reopened: User requested changes - <reason>"\n})\n\n# 4. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```\n# Search if similar pattern already documented\nmcp__knowns__search_docs({ query: "<pattern/concept>" })\n\n# If new knowledge, create a doc for future reference\nmcp__knowns__create_doc({\n  title: "Pattern: <Name>",\n  description: "Reusable pattern discovered during task implementation",\n  tags: ["pattern", "<domain>"],\n  folder: "patterns"\n})\n\n# Or append to existing doc\nmcp__knowns__update_doc({\n  path: "<existing-doc>",\n  appendContent: "## New Section\\n\\nLearned from task <id>: ..."\n})\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential MCP Tools\n\n### Task Management\n\n```\n# Create task\nmcp__knowns__create_task({\n  title: "Title",\n  description: "Description",\n  priority: "high",        # low, medium, high\n  labels: ["label1"],\n  status: "todo",          # todo, in-progress, in-review, done, blocked\n  assignee: "@username"\n})\n\n# Get task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# Update task\nmcp__knowns__update_task({\n  taskId: "<id>",\n  title: "New title",\n  description: "New description",\n  status: "in-progress",\n  priority: "high",\n  assignee: "@username",\n  labels: ["new", "labels"],\n  plan: "Implementation plan...",\n  notes: "Implementation notes...",\n  appendNotes: "Append to existing notes..."\n})\n\n# List tasks\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\nmcp__knowns__list_tasks({ assignee: "@username" })\nmcp__knowns__list_tasks({ priority: "high" })\nmcp__knowns__list_tasks({ label: "feature" })\n\n# Search tasks\nmcp__knowns__search_tasks({ query: "auth" })\n```\n\n### Time Tracking\n\n```\n# Start timer\nmcp__knowns__start_time({ taskId: "<id>" })\n\n# Stop timer\nmcp__knowns__stop_time({ taskId: "<id>" })\n\n# Manual entry\nmcp__knowns__add_time({\n  taskId: "<id>",\n  duration: "2h",           # e.g., "2h", "30m", "1h30m"\n  note: "Optional note",\n  date: "2025-12-25"        # Optional, defaults to now\n})\n\n# Reports\nmcp__knowns__get_time_report({})\nmcp__knowns__get_time_report({\n  from: "2025-12-01",\n  to: "2025-12-31",\n  groupBy: "task"           # task, label, status\n})\n```\n\n### Documentation\n\n```\n# List docs\nmcp__knowns__list_docs({})\nmcp__knowns__list_docs({ tag: "architecture" })\n\n# Get doc\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "patterns/module" })\n\n# Create doc\nmcp__knowns__create_doc({\n  title: "Title",\n  description: "Description",\n  tags: ["tag1", "tag2"],\n  folder: "folder/path",    # Optional\n  content: "Initial content..."\n})\n\n# Update doc\nmcp__knowns__update_doc({\n  path: "doc-name",\n  title: "New Title",\n  description: "New description",\n  tags: ["new", "tags"],\n  content: "Replace content...",\n  appendContent: "Append to content..."\n})\n\n# Search docs\nmcp__knowns__search_docs({ query: "patterns" })\nmcp__knowns__search_docs({ query: "auth", tag: "security" })\n```\n\n### Board\n\n```\n# Get kanban board view\nmcp__knowns__get_board({})\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via MCP Tools (Required)\n\n- [ ] All work completed and verified\n- [ ] Implementation notes added via `update_task`\n- [ ] \u23F1\uFE0F Timer stopped: `mcp__knowns__stop_time` (MANDATORY - do not skip!)\n- [ ] Status set to done via `update_task`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | ALWAYS use `start_time` and `stop_time` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Plan without checking docs | Read docs before planning |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Verify ALL criteria first |\n| Ignore refs in task description | Follow ALL refs before planning |\n| Follow only first-level refs | Recursively follow nested refs |\n\n---\n\n## Long Content Handling\n\nFor long documentation content, append in chunks:\n\n```\n# 1. Create doc with initial content\nmcp__knowns__create_doc({\n  title: "Doc Title",\n  content: "## Overview\\n\\nShort intro."\n})\n\n# 2. Append each section separately\nmcp__knowns__update_doc({\n  path: "doc-title",\n  appendContent: "## Section 1\\n\\nContent for section 1..."\n})\n\nmcp__knowns__update_doc({\n  path: "doc-title",\n  appendContent: "## Section 2\\n\\nContent for section 2..."\n})\n```\n\n> **Tip**: Each `appendContent` adds content after existing content. Use this for large docs to avoid context limits.\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `mcp__knowns__list_docs({})`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task details retrieved: `mcp__knowns__get_task`\n- [ ] ALL refs in task followed\n- [ ] Nested refs recursively followed\n- [ ] Related docs searched and read\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self via `update_task`\n- [ ] Status set to in-progress\n- [ ] Timer started: `mcp__knowns__start_time`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Progress notes appended: `appendNotes`\n\n### After Work\n\n- [ ] All work verified complete\n- [ ] Implementation notes added\n- [ ] Timer stopped: `mcp__knowns__stop_time`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done\n- [ ] Knowledge extracted to docs (if applicable)\n\n---\n\n## Quick Reference\n\n```\n# === AGENT INITIALIZATION (Once per session) ===\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\n\n# === FULL WORKFLOW ===\nmcp__knowns__create_task({ title: "Title", description: "Description" })\nmcp__knowns__update_task({ taskId: "<id>", status: "in-progress", assignee: "@me" })\nmcp__knowns__start_time({ taskId: "<id>" })                    # \u23F1\uFE0F REQUIRED\nmcp__knowns__search_docs({ query: "keyword" })\nmcp__knowns__get_doc({ path: "Doc Name" })\nmcp__knowns__search_tasks({ query: "keyword", status: "done" }) # Learn from history\nmcp__knowns__update_task({ taskId: "<id>", plan: "1. Step\\n2. Step" })\n# ... wait for approval, then implement ...\nmcp__knowns__update_task({ taskId: "<id>", appendNotes: "\u2713 Completed: feature X" })\nmcp__knowns__stop_time({ taskId: "<id>" })                     # \u23F1\uFE0F REQUIRED\nmcp__knowns__update_task({ taskId: "<id>", status: "done" })\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nmcp__knowns__get_task({ taskId: "<id>" })\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress", assignee: "@me" })\nmcp__knowns__search_tasks({ query: "bug" })\nmcp__knowns__search_docs({ query: "pattern" })\n\n# === TIME TRACKING ===\nmcp__knowns__start_time({ taskId: "<id>" })\nmcp__knowns__stop_time({ taskId: "<id>" })\nmcp__knowns__add_time({ taskId: "<id>", duration: "2h" })\nmcp__knowns__get_time_report({})\n\n# === DOCUMENTATION ===\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "path/doc-name" })\nmcp__knowns__create_doc({ title: "Title", description: "Desc", tags: ["tag"] })\nmcp__knowns__update_doc({ path: "doc-name", appendContent: "New content" })\n```\n\n---\n\n**Maintained By**: Knowns CLI Team\n\n<!-- KNOWNS GUIDELINES END -->\n';
+
+// src/commands/agents.ts
 var PROJECT_ROOT = process.cwd();
 var INSTRUCTION_FILES = [
   { path: "CLAUDE.md", name: "Claude Code", selected: true },
@@ -46971,8 +47013,11 @@ var INSTRUCTION_FILES = [
   { path: "GEMINI.md", name: "Gemini", selected: false },
   { path: ".github/copilot-instructions.md", name: "GitHub Copilot", selected: false }
 ];
-function getGuidelines(version2) {
-  return version2 === "mcp" ? knowns_guidelines_mcp_default : knowns_guidelines_cli_default;
+function getGuidelines(type, variant = "general") {
+  if (type === "mcp") {
+    return variant === "gemini" ? gemini_default2 : general_default2;
+  }
+  return variant === "gemini" ? gemini_default : general_default;
 }
 async function updateInstructionFile(filePath, guidelines) {
   const fullPath = join3(PROJECT_ROOT, filePath);
@@ -47003,11 +47048,12 @@ ${guidelines}
   await writeFile2(fullPath, newContent, "utf-8");
   return { success: true, action: "updated" };
 }
-var agentsCommand = new Command("agents").description("Manage agent instruction files (CLAUDE.md, GEMINI.md, etc.)").option("--update-instructions", "Update agent instruction files (non-interactive)").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--files <files>", "Comma-separated list of files to update").action(async (options2) => {
+var agentsCommand = new Command("agents").description("Manage agent instruction files (CLAUDE.md, GEMINI.md, etc.)").enablePositionalOptions().passThroughOptions().option("--update-instructions", "Update agent instruction files (non-interactive)").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--gemini", "Use compact Gemini variant (smaller context)").option("--files <files>", "Comma-separated list of files to update").action(async (options2) => {
   try {
     if (options2.updateInstructions) {
-      const version2 = options2.type === "mcp" ? "mcp" : "cli";
-      const guidelines2 = getGuidelines(version2);
+      const type = options2.type === "mcp" ? "mcp" : "cli";
+      const variant = options2.gemini ? "gemini" : "general";
+      const guidelines2 = getGuidelines(type, variant);
       let filesToUpdate = INSTRUCTION_FILES;
       if (options2.files) {
         const requestedFiles = options2.files.split(",").map((f) => f.trim());
@@ -47015,32 +47061,55 @@ var agentsCommand = new Command("agents").description("Manage agent instruction
           (f) => requestedFiles.includes(f.path) || requestedFiles.includes(f.name)
         );
       }
+      const label2 = `${type.toUpperCase()}${variant === "gemini" ? " (Gemini)" : ""}`;
       console.log(source_default.bold(`
-Updating agent instruction files (${version2.toUpperCase()} version)...
+Updating agent instruction files (${label2})...
 `));
       await updateFiles(filesToUpdate, guidelines2);
       return;
     }
     console.log(source_default.bold("\n\u{1F916} Agent Instructions Manager\n"));
-    const versionResponse = await (0, import_prompts.default)({
+    const typeResponse = await (0, import_prompts.default)({
       type: "select",
-      name: "version",
-      message: "Select guidelines version:",
+      name: "type",
+      message: "Select guidelines type:",
       choices: [
         {
           title: "CLI",
           value: "cli",
-          description: "Use CLI commands (knowns task edit, knowns doc view, etc.)"
+          description: "CLI commands (knowns task edit, knowns doc view, etc.)"
         },
         {
           title: "MCP",
           value: "mcp",
-          description: "Use MCP tools (mcp__knowns__update_task, mcp__knowns__get_doc, etc.)"
+          description: "MCP tools (mcp__knowns__update_task, etc.)"
+        }
+      ],
+      initial: 0
+    });
+    if (!typeResponse.type) {
+      console.log(source_default.yellow("\n\u26A0\uFE0F  Cancelled"));
+      return;
+    }
+    const variantResponse = await (0, import_prompts.default)({
+      type: "select",
+      name: "variant",
+      message: "Select variant:",
+      choices: [
+        {
+          title: "General (Full)",
+          value: "general",
+          description: "Complete guidelines for Claude, GPT, etc."
+        },
+        {
+          title: "Gemini (Compact)",
+          value: "gemini",
+          description: "Condensed version for Gemini 2.5 Flash (smaller context)"
         }
       ],
       initial: 0
     });
-    if (!versionResponse.version) {
+    if (!variantResponse.variant) {
       console.log(source_default.yellow("\n\u26A0\uFE0F  Cancelled"));
       return;
     }
@@ -47059,19 +47128,23 @@ Updating agent instruction files (${version2.toUpperCase()} version)...
       console.log(source_default.yellow("\n\u26A0\uFE0F  No files selected"));
       return;
     }
+    const label = `${typeResponse.type.toUpperCase()}${variantResponse.variant === "gemini" ? " (Gemini)" : ""}`;
     const confirmResponse = await (0, import_prompts.default)({
       type: "confirm",
       name: "confirm",
-      message: `Update ${filesResponse.files.length} file(s) with ${versionResponse.version.toUpperCase()} guidelines?`,
+      message: `Update ${filesResponse.files.length} file(s) with ${label} guidelines?`,
       initial: true
     });
     if (!confirmResponse.confirm) {
       console.log(source_default.yellow("\n\u26A0\uFE0F  Cancelled"));
       return;
     }
-    const guidelines = getGuidelines(versionResponse.version);
+    const guidelines = getGuidelines(
+      typeResponse.type,
+      variantResponse.variant
+    );
     console.log(source_default.bold(`
-Updating files with ${versionResponse.version.toUpperCase()} guidelines...
+Updating files with ${label} guidelines...
 `));
     await updateFiles(filesResponse.files, guidelines);
   } catch (error46) {
@@ -47122,6 +47195,23 @@ async function updateFiles(files, guidelines) {
   }
   console.log();
 }
+var syncCommand = new Command("sync").description("Sync/update all agent instruction files with latest guidelines").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--gemini", "Use compact Gemini variant (smaller context)").option("--all", "Update all instruction files (including Gemini, Copilot)").action(async (options2) => {
+  try {
+    const type = options2.type === "mcp" ? "mcp" : "cli";
+    const variant = options2.gemini ? "gemini" : "general";
+    const guidelines = getGuidelines(type, variant);
+    const filesToUpdate = options2.all ? INSTRUCTION_FILES : INSTRUCTION_FILES.filter((f) => f.selected);
+    const label = `${type.toUpperCase()}${variant === "gemini" ? " (Gemini)" : ""}`;
+    console.log(source_default.bold(`
+Syncing agent instructions (${label})...
+`));
+    await updateFiles(filesToUpdate, guidelines);
+  } catch (error46) {
+    console.error(source_default.red("Error:"), error46 instanceof Error ? error46.message : String(error46));
+    process.exit(1);
+  }
+});
+agentsCommand.addCommand(syncCommand);
 
 // src/commands/init.ts
 async function checkAndInitGit(projectRoot) {
@@ -47251,8 +47341,8 @@ async function runWizard() {
       },
       {
         type: "select",
-        name: "guidelinesVersion",
-        message: "AI Guidelines version",
+        name: "guidelinesType",
+        message: "AI Guidelines type",
         choices: [
           { title: "CLI", value: "cli", description: "Use CLI commands (knowns task edit, knowns doc view)" },
           { title: "MCP", value: "mcp", description: "Use MCP tools (mcp__knowns__update_task, etc.)" }
@@ -47289,7 +47379,7 @@ async function runWizard() {
     defaultPriority: response.defaultPriority,
     defaultLabels: response.defaultLabels?.filter((l) => l.trim()) || [],
     timeFormat: response.timeFormat,
-    guidelinesVersion: response.guidelinesVersion || "cli",
+    guidelinesType: response.guidelinesType || "cli",
     agentFiles: response.agentFiles || []
   };
 }
@@ -47322,7 +47412,7 @@ var initCommand = new Command("init").description("Initialize .knowns/ folder in
         defaultPriority: "medium",
         defaultLabels: [],
         timeFormat: "24h",
-        guidelinesVersion: "cli",
+        guidelinesType: "cli",
         agentFiles: INSTRUCTION_FILES.filter((f) => f.selected)
       };
     }
@@ -47347,8 +47437,8 @@ var initCommand = new Command("init").description("Initialize .knowns/ folder in
     console.log(source_default.gray(`  Time Format: ${config2.timeFormat}`));
     console.log();
     if (config2.agentFiles.length > 0) {
-      const guidelines = config2.guidelinesVersion === "mcp" ? knowns_guidelines_mcp_default : knowns_guidelines_cli_default;
-      console.log(source_default.bold(`Updating AI instruction files (${config2.guidelinesVersion.toUpperCase()} version)...`));
+      const guidelines = getGuidelines(config2.guidelinesType);
+      console.log(source_default.bold(`Updating AI instruction files (${config2.guidelinesType.toUpperCase()} version)...`));
       console.log();
       let syncedCount = 0;
       for (const file3 of config2.agentFiles) {
@@ -47383,7 +47473,7 @@ var initCommand = new Command("init").description("Initialize .knowns/ folder in
 });
 
 // src/commands/task.ts
-import { mkdir as mkdir4, readdir as readdir2, unlink as unlink3 } from "node:fs/promises";
+import { mkdir as mkdir4, readFile as readFile4, readdir as readdir2, unlink as unlink3 } from "node:fs/promises";
 import { join as join8 } from "node:path";
 
 // src/utils/doc-links.ts
@@ -47582,6 +47672,402 @@ async function notifyTimeUpdate(active) {
   }
 }
 
+// src/utils/validate.ts
+var import_gray_matter2 = __toESM(require_gray_matter(), 1);
+import { existsSync as existsSync6 } from "node:fs";
+import { copyFile, readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
+var DOC_REQUIRED_FIELDS = ["title", "createdAt", "updatedAt"];
+function validateDoc(content) {
+  const errors = [];
+  const warnings = [];
+  let data;
+  let bodyContent;
+  try {
+    const parsed = (0, import_gray_matter2.default)(content);
+    data = parsed.data;
+    bodyContent = parsed.content;
+  } catch (error46) {
+    errors.push({
+      field: "frontmatter",
+      message: `Invalid YAML frontmatter: ${error46 instanceof Error ? error46.message : String(error46)}`,
+      fixable: false
+    });
+    return { valid: false, errors, warnings };
+  }
+  for (const field of DOC_REQUIRED_FIELDS) {
+    if (!data[field]) {
+      errors.push({
+        field,
+        message: `Missing required field: ${field}`,
+        fixable: true
+      });
+    }
+  }
+  if (data.title && typeof data.title !== "string") {
+    errors.push({
+      field: "title",
+      message: "Title must be a string",
+      fixable: true
+    });
+  }
+  if (data.createdAt && !isValidISODate(data.createdAt)) {
+    errors.push({
+      field: "createdAt",
+      message: "createdAt must be a valid ISO date",
+      fixable: true
+    });
+  }
+  if (data.updatedAt && !isValidISODate(data.updatedAt)) {
+    errors.push({
+      field: "updatedAt",
+      message: "updatedAt must be a valid ISO date",
+      fixable: true
+    });
+  }
+  if (data.tags !== void 0) {
+    if (typeof data.tags === "string") {
+      warnings.push({
+        field: "tags",
+        message: "Tags should be an array, not a string"
+      });
+    } else if (!Array.isArray(data.tags)) {
+      errors.push({
+        field: "tags",
+        message: "Tags must be an array of strings",
+        fixable: true
+      });
+    }
+  }
+  if (!bodyContent.trim()) {
+    warnings.push({
+      field: "content",
+      message: "Document has no content"
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+async function repairDoc(filePath) {
+  const fixes = [];
+  const repairErrors = [];
+  if (!existsSync6(filePath)) {
+    return {
+      success: false,
+      errors: ["File not found"],
+      fixes: []
+    };
+  }
+  const backupPath = `${filePath}.bak`;
+  try {
+    await copyFile(filePath, backupPath);
+  } catch (error46) {
+    return {
+      success: false,
+      errors: [`Failed to create backup: ${error46 instanceof Error ? error46.message : String(error46)}`],
+      fixes: []
+    };
+  }
+  let content;
+  try {
+    content = await readFile3(filePath, "utf-8");
+  } catch (error46) {
+    return {
+      success: false,
+      backupPath,
+      errors: [`Failed to read file: ${error46 instanceof Error ? error46.message : String(error46)}`],
+      fixes: []
+    };
+  }
+  let data;
+  let bodyContent;
+  try {
+    const parsed = (0, import_gray_matter2.default)(content);
+    data = parsed.data;
+    bodyContent = parsed.content;
+  } catch {
+    const lines = content.split("\n");
+    const titleMatch = lines.find((l) => l.startsWith("# "));
+    const title = titleMatch ? titleMatch.replace("# ", "").trim() : "Untitled";
+    const now2 = (/* @__PURE__ */ new Date()).toISOString();
+    data = {
+      title,
+      createdAt: now2,
+      updatedAt: now2
+    };
+    const frontmatterEnd = content.indexOf("---", 3);
+    bodyContent = frontmatterEnd > 0 ? content.substring(frontmatterEnd + 3).trim() : content.replace(/^---[\s\S]*?---/, "").trim();
+    fixes.push("Rebuilt corrupted frontmatter");
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (!data.title) {
+    const titleMatch = bodyContent.match(/^#\s+(.+)$/m);
+    data.title = titleMatch ? titleMatch[1] : "Untitled Document";
+    fixes.push(`Added missing title: "${data.title}"`);
+  }
+  if (!data.createdAt || !isValidISODate(data.createdAt)) {
+    data.createdAt = now;
+    fixes.push("Fixed createdAt date");
+  }
+  if (!data.updatedAt || !isValidISODate(data.updatedAt)) {
+    data.updatedAt = now;
+    fixes.push("Fixed updatedAt date");
+  }
+  if (typeof data.tags === "string") {
+    data.tags = data.tags.split(",").map((t) => t.trim());
+    fixes.push("Converted tags from string to array");
+  }
+  if (data.tags && !Array.isArray(data.tags)) {
+    data.tags = [];
+    fixes.push("Reset invalid tags to empty array");
+  }
+  try {
+    const repairedContent = import_gray_matter2.default.stringify(bodyContent, data);
+    await writeFile3(filePath, repairedContent, "utf-8");
+  } catch (error46) {
+    repairErrors.push(`Failed to write repaired file: ${error46 instanceof Error ? error46.message : String(error46)}`);
+    return {
+      success: false,
+      backupPath,
+      errors: repairErrors,
+      fixes
+    };
+  }
+  return {
+    success: true,
+    backupPath,
+    fixes,
+    errors: repairErrors
+  };
+}
+var TASK_REQUIRED_FIELDS = ["id", "title", "status", "priority", "createdAt", "updatedAt"];
+var VALID_STATUSES = ["todo", "in-progress", "in-review", "done", "blocked", "on-hold"];
+var VALID_PRIORITIES = ["low", "medium", "high"];
+function validateTask(content) {
+  const errors = [];
+  const warnings = [];
+  let data;
+  let bodyContent;
+  try {
+    const parsed = (0, import_gray_matter2.default)(content);
+    data = parsed.data;
+    bodyContent = parsed.content;
+  } catch (error46) {
+    errors.push({
+      field: "frontmatter",
+      message: `Invalid YAML frontmatter: ${error46 instanceof Error ? error46.message : String(error46)}`,
+      fixable: false
+    });
+    return { valid: false, errors, warnings };
+  }
+  for (const field of TASK_REQUIRED_FIELDS) {
+    if (data[field] === void 0) {
+      errors.push({
+        field,
+        message: `Missing required field: ${field}`,
+        fixable: field !== "id"
+        // ID can't be auto-fixed
+      });
+    }
+  }
+  if (data.id && !/^\d+(\.\d+)*$/.test(data.id)) {
+    errors.push({
+      field: "id",
+      message: "Invalid ID format (expected: number or hierarchical like 7.1.2)",
+      fixable: false
+    });
+  }
+  if (data.status && !VALID_STATUSES.includes(data.status)) {
+    errors.push({
+      field: "status",
+      message: `Invalid status: ${data.status}. Expected one of: ${VALID_STATUSES.join(", ")}`,
+      fixable: true
+    });
+  }
+  if (data.priority && !VALID_PRIORITIES.includes(data.priority)) {
+    errors.push({
+      field: "priority",
+      message: `Invalid priority: ${data.priority}. Expected one of: ${VALID_PRIORITIES.join(", ")}`,
+      fixable: true
+    });
+  }
+  if (data.createdAt && !isValidISODate(data.createdAt)) {
+    errors.push({
+      field: "createdAt",
+      message: "createdAt must be a valid ISO date",
+      fixable: true
+    });
+  }
+  if (data.updatedAt && !isValidISODate(data.updatedAt)) {
+    errors.push({
+      field: "updatedAt",
+      message: "updatedAt must be a valid ISO date",
+      fixable: true
+    });
+  }
+  if (data.labels !== void 0) {
+    if (typeof data.labels === "string") {
+      warnings.push({
+        field: "labels",
+        message: "Labels should be an array, not a string"
+      });
+    } else if (!Array.isArray(data.labels)) {
+      errors.push({
+        field: "labels",
+        message: "Labels must be an array of strings",
+        fixable: true
+      });
+    }
+  }
+  if (data.timeSpent !== void 0 && (typeof data.timeSpent !== "number" || data.timeSpent < 0)) {
+    errors.push({
+      field: "timeSpent",
+      message: "timeSpent must be a non-negative number",
+      fixable: true
+    });
+  }
+  if (!bodyContent.includes("# ")) {
+    warnings.push({
+      field: "content",
+      message: "Missing title heading in body"
+    });
+  }
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings
+  };
+}
+async function repairTask(filePath, extractedId) {
+  const fixes = [];
+  const repairErrors = [];
+  if (!existsSync6(filePath)) {
+    return {
+      success: false,
+      errors: ["File not found"],
+      fixes: []
+    };
+  }
+  const backupPath = `${filePath}.bak`;
+  try {
+    await copyFile(filePath, backupPath);
+  } catch (error46) {
+    return {
+      success: false,
+      errors: [`Failed to create backup: ${error46 instanceof Error ? error46.message : String(error46)}`],
+      fixes: []
+    };
+  }
+  let content;
+  try {
+    content = await readFile3(filePath, "utf-8");
+  } catch (error46) {
+    return {
+      success: false,
+      backupPath,
+      errors: [`Failed to read file: ${error46 instanceof Error ? error46.message : String(error46)}`],
+      fixes: []
+    };
+  }
+  let data;
+  let bodyContent;
+  try {
+    const parsed = (0, import_gray_matter2.default)(content);
+    data = parsed.data;
+    bodyContent = parsed.content;
+  } catch {
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1] : "Untitled Task";
+    const now2 = (/* @__PURE__ */ new Date()).toISOString();
+    data = {
+      id: extractedId,
+      title,
+      status: "todo",
+      priority: "medium",
+      labels: [],
+      createdAt: now2,
+      updatedAt: now2,
+      timeSpent: 0
+    };
+    const frontmatterEnd = content.indexOf("---", 3);
+    bodyContent = frontmatterEnd > 0 ? content.substring(frontmatterEnd + 3).trim() : content.replace(/^---[\s\S]*?---/, "").trim();
+    fixes.push("Rebuilt corrupted frontmatter");
+  }
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  if (!data.id && extractedId) {
+    data.id = extractedId;
+    fixes.push(`Set ID from filename: ${extractedId}`);
+  }
+  if (!data.title) {
+    const titleMatch = bodyContent.match(/^#\s+(.+)$/m);
+    data.title = titleMatch ? titleMatch[1] : "Untitled Task";
+    fixes.push(`Added missing title: "${data.title}"`);
+  }
+  if (!data.status || !VALID_STATUSES.includes(data.status)) {
+    data.status = "todo";
+    fixes.push("Set status to 'todo'");
+  }
+  if (!data.priority || !VALID_PRIORITIES.includes(data.priority)) {
+    data.priority = "medium";
+    fixes.push("Set priority to 'medium'");
+  }
+  if (!data.createdAt || !isValidISODate(data.createdAt)) {
+    data.createdAt = now;
+    fixes.push("Fixed createdAt date");
+  }
+  if (!data.updatedAt || !isValidISODate(data.updatedAt)) {
+    data.updatedAt = now;
+    fixes.push("Fixed updatedAt date");
+  }
+  if (typeof data.labels === "string") {
+    data.labels = data.labels.split(",").map((l) => l.trim());
+    fixes.push("Converted labels from string to array");
+  }
+  if (!Array.isArray(data.labels)) {
+    data.labels = [];
+    fixes.push("Reset invalid labels to empty array");
+  }
+  if (typeof data.timeSpent !== "number" || data.timeSpent < 0) {
+    data.timeSpent = 0;
+    fixes.push("Reset timeSpent to 0");
+  }
+  if (!bodyContent.includes("# ") && data.title) {
+    bodyContent = `# ${data.title}
+
+${bodyContent}`;
+    fixes.push("Added title heading to body");
+  }
+  try {
+    const repairedContent = import_gray_matter2.default.stringify(bodyContent, data);
+    await writeFile3(filePath, repairedContent, "utf-8");
+  } catch (error46) {
+    repairErrors.push(`Failed to write repaired file: ${error46 instanceof Error ? error46.message : String(error46)}`);
+    return {
+      success: false,
+      backupPath,
+      errors: repairErrors,
+      fixes
+    };
+  }
+  return {
+    success: true,
+    backupPath,
+    fixes,
+    errors: repairErrors
+  };
+}
+function isValidISODate(dateString) {
+  if (typeof dateString !== "string") return false;
+  const date5 = new Date(dateString);
+  return !Number.isNaN(date5.getTime());
+}
+function extractTaskIdFromFilename(filename) {
+  const match = filename.match(/^task-(\d+(?:\.\d+)*)\s*-/);
+  return match ? match[1] : void 0;
+}
+
 // src/commands/task.ts
 function getFileStore() {
   const projectRoot = findProjectRoot();
@@ -48649,7 +49135,151 @@ var restoreCommand = new Command("restore").description("Restore task to a previ
     process.exit(1);
   }
 });
-var taskCommand = new Command("task").description("Manage tasks").argument("[id]", "Task ID (shorthand for 'task view <id>')").option("--plain", "Plain text output for AI").action(async (id, options2) => {
+var validateCommand = new Command("validate").description("Validate a task file format").argument("<id>", "Task ID to validate").option("--plain", "Plain text output for AI").action(async (id, options2) => {
+  try {
+    const projectRoot = findProjectRoot();
+    if (!projectRoot) {
+      console.error(source_default.red("\u2717 Not a knowns project"));
+      process.exit(1);
+    }
+    const tasksPath = join8(projectRoot, ".knowns", "tasks");
+    const files = await readdir2(tasksPath);
+    const taskFile = files.find((f) => f.startsWith(`task-${id} -`));
+    if (!taskFile) {
+      console.error(source_default.red(`\u2717 Task ${id} not found`));
+      process.exit(1);
+    }
+    const filePath = join8(tasksPath, taskFile);
+    const content = await readFile4(filePath, "utf-8");
+    const result = validateTask(content);
+    if (options2.plain) {
+      console.log(`Validating: task-${id}`);
+      console.log(`Valid: ${result.valid}`);
+      if (result.errors.length > 0) {
+        console.log("\nErrors:");
+        for (const error46 of result.errors) {
+          console.log(`  \u2717 ${error46.field}: ${error46.message}${error46.fixable ? " (fixable)" : ""}`);
+        }
+      }
+      if (result.warnings.length > 0) {
+        console.log("\nWarnings:");
+        for (const warning of result.warnings) {
+          console.log(`  \u26A0 ${warning.field}: ${warning.message}`);
+        }
+      }
+      if (result.valid && result.warnings.length === 0) {
+        console.log("No issues found.");
+      }
+    } else {
+      console.log(source_default.bold(`
+\u{1F4CB} Validation: Task ${id}
+`));
+      if (result.valid) {
+        console.log(source_default.green("\u2713 Task is valid"));
+      } else {
+        console.log(source_default.red("\u2717 Task has errors"));
+      }
+      if (result.errors.length > 0) {
+        console.log(source_default.red("\nErrors:"));
+        for (const error46 of result.errors) {
+          const fixable = error46.fixable ? source_default.gray(" (fixable)") : "";
+          console.log(source_default.red(`  \u2717 ${error46.field}: ${error46.message}${fixable}`));
+        }
+      }
+      if (result.warnings.length > 0) {
+        console.log(source_default.yellow("\nWarnings:"));
+        for (const warning of result.warnings) {
+          console.log(source_default.yellow(`  \u26A0 ${warning.field}: ${warning.message}`));
+        }
+      }
+      if (result.valid && result.warnings.length === 0) {
+        console.log(source_default.gray("\nNo issues found."));
+      }
+      console.log();
+    }
+    process.exit(result.valid ? 0 : 1);
+  } catch (error46) {
+    console.error(source_default.red("\u2717 Failed to validate task"));
+    if (error46 instanceof Error) {
+      console.error(source_default.red(`  ${error46.message}`));
+    }
+    process.exit(1);
+  }
+});
+var repairCommand = new Command("repair").description("Repair a corrupted task file").argument("<id>", "Task ID to repair").option("--plain", "Plain text output for AI").action(async (id, options2) => {
+  try {
+    const projectRoot = findProjectRoot();
+    if (!projectRoot) {
+      console.error(source_default.red("\u2717 Not a knowns project"));
+      process.exit(1);
+    }
+    const tasksPath = join8(projectRoot, ".knowns", "tasks");
+    const files = await readdir2(tasksPath);
+    const taskFile = files.find((f) => f.startsWith(`task-${id} -`));
+    if (!taskFile) {
+      console.error(source_default.red(`\u2717 Task ${id} not found`));
+      process.exit(1);
+    }
+    const filePath = join8(tasksPath, taskFile);
+    const extractedId = extractTaskIdFromFilename(taskFile);
+    const result = await repairTask(filePath, extractedId);
+    if (options2.plain) {
+      console.log(`Repairing: task-${id}`);
+      console.log(`Success: ${result.success}`);
+      if (result.backupPath) {
+        console.log(`Backup: ${result.backupPath}`);
+      }
+      if (result.fixes.length > 0) {
+        console.log("\nFixes applied:");
+        for (const fix of result.fixes) {
+          console.log(`  \u2713 ${fix}`);
+        }
+      }
+      if (result.errors.length > 0) {
+        console.log("\nErrors:");
+        for (const err of result.errors) {
+          console.log(`  \u2717 ${err}`);
+        }
+      }
+    } else {
+      console.log(source_default.bold(`
+\u{1F527} Repair: Task ${id}
+`));
+      if (result.success) {
+        console.log(source_default.green("\u2713 Task repaired successfully"));
+      } else {
+        console.log(source_default.red("\u2717 Repair failed"));
+      }
+      if (result.backupPath) {
+        console.log(source_default.gray(`  Backup created: ${result.backupPath}`));
+      }
+      if (result.fixes.length > 0) {
+        console.log(source_default.green("\nFixes applied:"));
+        for (const fix of result.fixes) {
+          console.log(source_default.green(`  \u2713 ${fix}`));
+        }
+      }
+      if (result.errors.length > 0) {
+        console.log(source_default.red("\nErrors:"));
+        for (const err of result.errors) {
+          console.log(source_default.red(`  \u2717 ${err}`));
+        }
+      }
+      console.log();
+    }
+    if (result.success) {
+      await notifyTaskUpdate(id);
+    }
+    process.exit(result.success ? 0 : 1);
+  } catch (error46) {
+    console.error(source_default.red("\u2717 Failed to repair task"));
+    if (error46 instanceof Error) {
+      console.error(source_default.red(`  ${error46.message}`));
+    }
+    process.exit(1);
+  }
+});
+var taskCommand = new Command("task").description("Manage tasks").argument("[id]", "Task ID (shorthand for 'task view <id>')").option("--plain", "Plain text output for AI").enablePositionalOptions().passThroughOptions().action(async (id, options2) => {
   if (!id) {
     taskCommand.help();
     return;
@@ -48679,6 +49309,8 @@ taskCommand.addCommand(unarchiveCommand);
 taskCommand.addCommand(historyCommand);
 taskCommand.addCommand(diffCommand);
 taskCommand.addCommand(restoreCommand);
+taskCommand.addCommand(validateCommand);
+taskCommand.addCommand(repairCommand);
 
 // src/commands/board.ts
 function getFileStore2() {
@@ -48840,10 +49472,10 @@ var boardCommand = new Command("board").description("Display Kanban board").opti
 );
 
 // src/commands/search.ts
-import { existsSync as existsSync6 } from "node:fs";
-import { readFile as readFile3, readdir as readdir3 } from "node:fs/promises";
+import { existsSync as existsSync7 } from "node:fs";
+import { readFile as readFile5, readdir as readdir3 } from "node:fs/promises";
 import { join as join9 } from "node:path";
-var import_gray_matter2 = __toESM(require_gray_matter(), 1);
+var import_gray_matter3 = __toESM(require_gray_matter(), 1);
 function getFileStore3() {
   const projectRoot = findProjectRoot();
   if (!projectRoot) {
@@ -48895,7 +49527,7 @@ function calculateDocScore(doc, query) {
 }
 async function searchDocs(query, projectRoot) {
   const docsDir = join9(projectRoot, ".knowns", "docs");
-  if (!existsSync6(docsDir)) {
+  if (!existsSync7(docsDir)) {
     return [];
   }
   try {
@@ -48903,8 +49535,8 @@ async function searchDocs(query, projectRoot) {
     const mdFiles = files.filter((f) => f.endsWith(".md"));
     const results = [];
     for (const file3 of mdFiles) {
-      const content = await readFile3(join9(docsDir, file3), "utf-8");
-      const { data, content: docContent } = (0, import_gray_matter2.default)(content);
+      const content = await readFile5(join9(docsDir, file3), "utf-8");
+      const { data, content: docContent } = (0, import_gray_matter3.default)(content);
       const metadata = data;
       const doc = {
         filename: file3,
@@ -49507,13 +50139,13 @@ timeCommand.addCommand(addCommand);
 timeCommand.addCommand(reportCommand);
 
 // src/commands/browser.ts
-import { existsSync as existsSync12 } from "node:fs";
-import { mkdir as mkdir6, readFile as readFile8, writeFile as writeFile6 } from "node:fs/promises";
+import { existsSync as existsSync13 } from "node:fs";
+import { mkdir as mkdir6, readFile as readFile10, writeFile as writeFile7 } from "node:fs/promises";
 import { join as join16 } from "node:path";
 
 // src/server/index.ts
 import { spawn } from "node:child_process";
-import { existsSync as existsSync11, realpathSync } from "node:fs";
+import { existsSync as existsSync12, realpathSync } from "node:fs";
 import { createServer } from "node:http";
 import { basename as basename2, dirname as dirname3, join as join15 } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -49577,8 +50209,8 @@ function createActivityRoutes(ctx) {
 
 // src/server/routes/config.ts
 var import_express2 = __toESM(require_express2(), 1);
-import { existsSync as existsSync7 } from "node:fs";
-import { readFile as readFile4, writeFile as writeFile3 } from "node:fs/promises";
+import { existsSync as existsSync8 } from "node:fs";
+import { readFile as readFile6, writeFile as writeFile4 } from "node:fs/promises";
 import { join as join10 } from "node:path";
 function createConfigRoutes(ctx) {
   const router = (0, import_express2.Router)();
@@ -49586,7 +50218,7 @@ function createConfigRoutes(ctx) {
   const configPath = join10(store.projectRoot, ".knowns", "config.json");
   router.get("/", async (_req, res) => {
     try {
-      if (!existsSync7(configPath)) {
+      if (!existsSync8(configPath)) {
         res.json({
           config: {
             name: "Knowns",
@@ -49598,7 +50230,7 @@ function createConfigRoutes(ctx) {
         });
         return;
       }
-      const content = await readFile4(configPath, "utf-8");
+      const content = await readFile6(configPath, "utf-8");
       const data = JSON.parse(content);
       const settings = data.settings || {};
       const config2 = {
@@ -49620,8 +50252,8 @@ function createConfigRoutes(ctx) {
     try {
       const config2 = req.body;
       let existingData = {};
-      if (existsSync7(configPath)) {
-        const content = await readFile4(configPath, "utf-8");
+      if (existsSync8(configPath)) {
+        const content = await readFile6(configPath, "utf-8");
         existingData = JSON.parse(content);
       }
       const { name, ...settings } = config2;
@@ -49630,7 +50262,7 @@ function createConfigRoutes(ctx) {
         name: name || existingData.name,
         settings
       };
-      await writeFile3(configPath, JSON.stringify(merged, null, 2), "utf-8");
+      await writeFile4(configPath, JSON.stringify(merged, null, 2), "utf-8");
       res.json({ success: true });
     } catch (error46) {
       console.error("Error saving config:", error46);
@@ -49642,9 +50274,9 @@ function createConfigRoutes(ctx) {
 
 // src/server/routes/docs.ts
 var import_express3 = __toESM(require_express2(), 1);
-var import_gray_matter3 = __toESM(require_gray_matter(), 1);
-import { existsSync as existsSync8 } from "node:fs";
-import { mkdir as mkdir5, readFile as readFile5, writeFile as writeFile4 } from "node:fs/promises";
+var import_gray_matter4 = __toESM(require_gray_matter(), 1);
+import { existsSync as existsSync9 } from "node:fs";
+import { mkdir as mkdir5, readFile as readFile7, writeFile as writeFile5 } from "node:fs/promises";
 import { join as join12 } from "node:path";
 
 // src/server/utils/markdown.ts
@@ -49673,7 +50305,7 @@ function createDocRoutes(ctx) {
   const docsDir = join12(store.projectRoot, ".knowns", "docs");
   router.get("/", async (_req, res) => {
     try {
-      if (!existsSync8(docsDir)) {
+      if (!existsSync9(docsDir)) {
         res.json({ docs: [] });
         return;
       }
@@ -49681,8 +50313,8 @@ function createDocRoutes(ctx) {
       const docs = await Promise.all(
         mdFiles.map(async (relativePath) => {
           const fullPath = join12(docsDir, relativePath);
-          const content = await readFile5(fullPath, "utf-8");
-          const { data, content: docContent } = (0, import_gray_matter3.default)(content);
+          const content = await readFile7(fullPath, "utf-8");
+          const { data, content: docContent } = (0, import_gray_matter4.default)(content);
           const pathParts = relativePath.split("/");
           const filename = pathParts[pathParts.length - 1];
           const folder = pathParts.length > 1 ? pathParts.slice(0, -1).join("/") : "";
@@ -49709,12 +50341,12 @@ function createDocRoutes(ctx) {
         res.status(400).json({ error: "Invalid path" });
         return;
       }
-      if (!existsSync8(fullPath)) {
+      if (!existsSync9(fullPath)) {
         res.status(404).json({ error: "Document not found" });
         return;
       }
-      const content = await readFile5(fullPath, "utf-8");
-      const { data, content: docContent } = (0, import_gray_matter3.default)(content);
+      const content = await readFile7(fullPath, "utf-8");
+      const { data, content: docContent } = (0, import_gray_matter4.default)(content);
       const pathParts = docPath.split("/");
       const filename = pathParts[pathParts.length - 1];
       const folder = pathParts.length > 1 ? pathParts.slice(0, -1).join("/") : "";
@@ -49736,7 +50368,7 @@ function createDocRoutes(ctx) {
   });
   router.post("/", async (req, res) => {
     try {
-      if (!existsSync8(docsDir)) {
+      if (!existsSync9(docsDir)) {
         await mkdir5(docsDir, { recursive: true });
       }
       const data = req.body;
@@ -49756,10 +50388,10 @@ function createDocRoutes(ctx) {
         targetDir = docsDir;
         filepath = join12(docsDir, filename);
       }
-      if (!existsSync8(targetDir)) {
+      if (!existsSync9(targetDir)) {
         await mkdir5(targetDir, { recursive: true });
       }
-      if (existsSync8(filepath)) {
+      if (existsSync9(filepath)) {
         res.status(409).json({ error: "Document with this title already exists in this folder" });
         return;
       }
@@ -49771,8 +50403,8 @@ function createDocRoutes(ctx) {
         updatedAt: now,
         tags: tags || []
       };
-      const markdown = import_gray_matter3.default.stringify(content || "", frontmatter);
-      await writeFile4(filepath, markdown, "utf-8");
+      const markdown = import_gray_matter4.default.stringify(content || "", frontmatter);
+      await writeFile5(filepath, markdown, "utf-8");
       res.status(201).json({
         success: true,
         filename,
@@ -49793,14 +50425,14 @@ function createDocRoutes(ctx) {
         res.status(400).json({ error: "Invalid path" });
         return;
       }
-      if (!existsSync8(fullPath)) {
+      if (!existsSync9(fullPath)) {
         res.status(404).json({ error: "Document not found" });
         return;
       }
       const data = req.body;
       const { content, title, description, tags } = data;
-      const existingContent = await readFile5(fullPath, "utf-8");
-      const { data: existingData } = (0, import_gray_matter3.default)(existingContent);
+      const existingContent = await readFile7(fullPath, "utf-8");
+      const { data: existingData } = (0, import_gray_matter4.default)(existingContent);
       const now = (/* @__PURE__ */ new Date()).toISOString();
       const updatedFrontmatter = {
         ...existingData,
@@ -49809,8 +50441,8 @@ function createDocRoutes(ctx) {
         tags: tags ?? existingData.tags,
         updatedAt: now
       };
-      const newFileContent = import_gray_matter3.default.stringify(content ?? "", updatedFrontmatter);
-      await writeFile4(fullPath, newFileContent, "utf-8");
+      const newFileContent = import_gray_matter4.default.stringify(content ?? "", updatedFrontmatter);
+      await writeFile5(fullPath, newFileContent, "utf-8");
       const pathParts = docPath.split("/");
       const filename = pathParts[pathParts.length - 1];
       const folder = pathParts.length > 1 ? pathParts.slice(0, -1).join("/") : "";
@@ -49878,9 +50510,9 @@ function createNotifyRoutes(ctx) {
 
 // src/server/routes/search.ts
 var import_express5 = __toESM(require_express2(), 1);
-var import_gray_matter4 = __toESM(require_gray_matter(), 1);
-import { existsSync as existsSync9 } from "node:fs";
-import { readFile as readFile6 } from "node:fs/promises";
+var import_gray_matter5 = __toESM(require_gray_matter(), 1);
+import { existsSync as existsSync10 } from "node:fs";
+import { readFile as readFile8 } from "node:fs/promises";
 import { join as join13 } from "node:path";
 function createSearchRoutes(ctx) {
   const router = (0, import_express5.Router)();
@@ -49908,12 +50540,12 @@ function createSearchRoutes(ctx) {
       });
       const docsDir = join13(store.projectRoot, ".knowns", "docs");
       const docResults = [];
-      if (existsSync9(docsDir)) {
+      if (existsSync10(docsDir)) {
         const mdFiles = await findMarkdownFiles(docsDir, docsDir);
         for (const relativePath of mdFiles) {
           const fullPath = join13(docsDir, relativePath);
-          const content = await readFile6(fullPath, "utf-8");
-          const { data, content: docContent } = (0, import_gray_matter4.default)(content);
+          const content = await readFile8(fullPath, "utf-8");
+          const { data, content: docContent } = (0, import_gray_matter5.default)(content);
           const searchText = `${data.title || ""} ${data.description || ""} ${data.tags?.join(" ") || ""} ${docContent}`.toLowerCase();
           if (searchText.includes(q)) {
             const pathParts = relativePath.split("/");
@@ -50037,22 +50669,22 @@ function createTaskRoutes(ctx) {
 
 // src/server/routes/time.ts
 var import_express7 = __toESM(require_express2(), 1);
-import { existsSync as existsSync10 } from "node:fs";
-import { readFile as readFile7, writeFile as writeFile5 } from "node:fs/promises";
+import { existsSync as existsSync11 } from "node:fs";
+import { readFile as readFile9, writeFile as writeFile6 } from "node:fs/promises";
 import { join as join14 } from "node:path";
 function createTimeRoutes(ctx) {
   const router = (0, import_express7.Router)();
   const { store, broadcast } = ctx;
   const timePath = join14(store.projectRoot, ".knowns", "time.json");
   async function loadTimeData2() {
-    if (!existsSync10(timePath)) {
+    if (!existsSync11(timePath)) {
       return { active: null };
     }
-    const content = await readFile7(timePath, "utf-8");
+    const content = await readFile9(timePath, "utf-8");
     return JSON.parse(content);
   }
   async function saveTimeData2(data) {
-    await writeFile5(timePath, JSON.stringify(data, null, 2), "utf-8");
+    await writeFile6(timePath, JSON.stringify(data, null, 2), "utf-8");
   }
   router.get("/status", async (_req, res) => {
     try {
@@ -50241,7 +50873,7 @@ async function startServer(options2) {
     packageRoot = join15(currentDir, "..", "..");
   }
   const uiDistPath = join15(packageRoot, "dist", "ui");
-  if (!existsSync11(join15(uiDistPath, "index.html"))) {
+  if (!existsSync12(join15(uiDistPath, "index.html"))) {
     throw new Error(`UI build not found at ${uiDistPath}. Run 'bun run build:ui' first.`);
   }
   const app = (0, import_express9.default)();
@@ -50272,7 +50904,7 @@ async function startServer(options2) {
   app.use(errorHandler);
   app.get("/{*path}", (_req, res) => {
     const indexPath = join15(uiDistPath, "index.html");
-    if (existsSync11(indexPath)) {
+    if (existsSync12(indexPath)) {
       res.sendFile("index.html", { root: uiDistPath });
     } else {
       res.status(404).send("Not Found");
@@ -50323,19 +50955,19 @@ var CONFIG_FILE = ".knowns/config.json";
 async function saveServerPort(projectRoot, port) {
   const configPath = join16(projectRoot, CONFIG_FILE);
   const knownsDir = join16(projectRoot, ".knowns");
-  if (!existsSync12(knownsDir)) {
+  if (!existsSync13(knownsDir)) {
     await mkdir6(knownsDir, { recursive: true });
   }
   try {
     let config2 = {};
-    if (existsSync12(configPath)) {
-      const content = await readFile8(configPath, "utf-8");
+    if (existsSync13(configPath)) {
+      const content = await readFile10(configPath, "utf-8");
       config2 = JSON.parse(content);
     }
     const settings = config2.settings || {};
     settings.serverPort = port;
     config2.settings = settings;
-    await writeFile6(configPath, JSON.stringify(config2, null, 2), "utf-8");
+    await writeFile7(configPath, JSON.stringify(config2, null, 2), "utf-8");
   } catch {
   }
 }
@@ -50365,10 +50997,10 @@ var browserCommand = new Command("browser").description("Open web UI for task ma
 });
 
 // src/commands/doc.ts
-import { existsSync as existsSync13 } from "node:fs";
-import { mkdir as mkdir7, readFile as readFile9, readdir as readdir5, writeFile as writeFile7 } from "node:fs/promises";
+import { existsSync as existsSync14 } from "node:fs";
+import { mkdir as mkdir7, readFile as readFile11, readdir as readdir5, writeFile as writeFile8 } from "node:fs/promises";
 import { join as join17 } from "node:path";
-var import_gray_matter5 = __toESM(require_gray_matter(), 1);
+var import_gray_matter6 = __toESM(require_gray_matter(), 1);
 var DOCS_DIR = join17(process.cwd(), ".knowns", "docs");
 async function getAllMdFiles(dir, basePath = "") {
   const files = [];
@@ -50386,7 +51018,7 @@ async function getAllMdFiles(dir, basePath = "") {
   return files;
 }
 async function ensureDocsDir() {
-  if (!existsSync13(DOCS_DIR)) {
+  if (!existsSync14(DOCS_DIR)) {
     await mkdir7(DOCS_DIR, { recursive: true });
   }
 }
@@ -50397,11 +51029,11 @@ async function resolveDocPath(name) {
   await ensureDocsDir();
   let filename = name.endsWith(".md") ? name : `${name}.md`;
   let filepath = join17(DOCS_DIR, filename);
-  if (!existsSync13(filepath)) {
+  if (!existsSync14(filepath)) {
     filename = `${titleToFilename(name)}.md`;
     filepath = join17(DOCS_DIR, filename);
   }
-  if (!existsSync13(filepath)) {
+  if (!existsSync14(filepath)) {
     const allFiles = await getAllMdFiles(DOCS_DIR);
     const searchName = name.toLowerCase().replace(/\.md$/, "");
     const matchingFile = allFiles.find((file3) => {
@@ -50414,7 +51046,7 @@ async function resolveDocPath(name) {
       filepath = join17(DOCS_DIR, matchingFile);
     }
   }
-  if (!existsSync13(filepath)) {
+  if (!existsSync14(filepath)) {
     return null;
   }
   return { filepath, filename };
@@ -50429,12 +51061,12 @@ var createCommand3 = new Command("create").description("Create a new documentati
       const folderPath = options2.folder.replace(/^\/|\/$/g, "");
       targetDir = join17(DOCS_DIR, folderPath);
       relativePath = join17(folderPath, filename);
-      if (!existsSync13(targetDir)) {
+      if (!existsSync14(targetDir)) {
         await mkdir7(targetDir, { recursive: true });
       }
     }
     const filepath = join17(targetDir, filename);
-    if (existsSync13(filepath)) {
+    if (existsSync14(filepath)) {
       console.error(source_default.red(`\u2717 Document already exists: ${relativePath}`));
       process.exit(1);
     }
@@ -50450,8 +51082,8 @@ var createCommand3 = new Command("create").description("Create a new documentati
     if (options2.tags) {
       metadata.tags = options2.tags.split(",").map((t) => t.trim());
     }
-    const content = import_gray_matter5.default.stringify("# Content\n\nWrite your documentation here.\n", metadata);
-    await writeFile7(filepath, content, "utf-8");
+    const content = import_gray_matter6.default.stringify("# Content\n\nWrite your documentation here.\n", metadata);
+    await writeFile8(filepath, content, "utf-8");
     await notifyDocUpdate(relativePath);
     if (options2.plain) {
       console.log(`Created: ${relativePath}`);
@@ -50464,7 +51096,7 @@ var createCommand3 = new Command("create").description("Create a new documentati
     process.exit(1);
   }
 });
-var listCommand2 = new Command("list").description("List all documentation files").option("--plain", "Plain text output for AI").option("-t, --tag <tag>", "Filter by tag").action(async (options2) => {
+var listCommand2 = new Command("list").description("List all documentation files").argument("[path]", "Filter by path (e.g., 'guides/' or 'patterns/')").option("--plain", "Plain text output for AI").option("-t, --tag <tag>", "Filter by tag").action(async (path, options2) => {
   try {
     await ensureDocsDir();
     const mdFiles = await getAllMdFiles(DOCS_DIR);
@@ -50479,55 +51111,107 @@ var listCommand2 = new Command("list").description("List all documentation files
     }
     const docs = [];
     for (const file3 of mdFiles) {
-      const content = await readFile9(join17(DOCS_DIR, file3), "utf-8");
-      const { data } = (0, import_gray_matter5.default)(content);
+      const content = await readFile11(join17(DOCS_DIR, file3), "utf-8");
+      const { data } = (0, import_gray_matter6.default)(content);
       docs.push({
         filename: file3,
         metadata: data
       });
     }
     let filteredDocs = docs;
+    if (path) {
+      const normalizedPath = path.endsWith("/") ? path : `${path}/`;
+      filteredDocs = docs.filter((doc) => doc.filename.startsWith(normalizedPath));
+    }
     if (options2.tag) {
-      filteredDocs = docs.filter((doc) => doc.metadata.tags?.includes(options2.tag));
+      filteredDocs = filteredDocs.filter((doc) => doc.metadata.tags?.includes(options2.tag));
     }
     if (filteredDocs.length === 0) {
+      const filterMsg = path ? `path: ${path}` : options2.tag ? `tag: ${options2.tag}` : "";
       console.log(
-        options2.plain ? "No documentation found" : source_default.yellow(`No documentation found with tag: ${options2.tag}`)
+        options2.plain ? "No documentation found" : source_default.yellow(`No documentation found${filterMsg ? ` with ${filterMsg}` : ""}`)
       );
       return;
     }
     if (options2.plain) {
-      const border = "=".repeat(50);
-      console.log(`Documentation Files (${filteredDocs.length})`);
-      console.log(border);
-      console.log();
+      const folders = /* @__PURE__ */ new Map();
+      const rootDocs = [];
       for (const doc of filteredDocs) {
-        console.log(`${doc.filename} - ${doc.metadata.title}`);
-        if (doc.metadata.description) {
-          console.log(`  ${doc.metadata.description}`);
+        const parts = doc.filename.split("/");
+        if (parts.length === 1) {
+          rootDocs.push({
+            name: parts[0].replace(/\.md$/, ""),
+            title: doc.metadata.title
+          });
+        } else {
+          const folder = parts.slice(0, -1).join("/");
+          const name = parts[parts.length - 1].replace(/\.md$/, "");
+          if (!folders.has(folder)) {
+            folders.set(folder, []);
+          }
+          folders.get(folder)?.push({ name, title: doc.metadata.title });
         }
-        console.log(`  Created: ${doc.metadata.createdAt}`);
-        if (doc.metadata.tags && doc.metadata.tags.length > 0) {
-          console.log(`  Tags: ${doc.metadata.tags.join(", ")}`);
+      }
+      const sortedFolders = Array.from(folders.keys()).sort();
+      for (const folder of sortedFolders) {
+        console.log(`${folder}/`);
+        const docs2 = folders.get(folder)?.sort((a, b) => a.name.localeCompare(b.name));
+        for (const doc of docs2) {
+          console.log(`  ${doc.name} - ${doc.title}`);
+        }
+      }
+      if (rootDocs.length > 0) {
+        rootDocs.sort((a, b) => a.name.localeCompare(b.name));
+        for (const doc of rootDocs) {
+          console.log(`${doc.name} - ${doc.title}`);
         }
-        console.log();
       }
     } else {
-      console.log(source_default.bold("\n\u{1F4DA} Documentation\n"));
+      const folders = /* @__PURE__ */ new Map();
+      const rootDocs = [];
       for (const doc of filteredDocs) {
-        console.log(source_default.cyan(`  ${doc.metadata.title}`));
-        if (doc.metadata.description) {
-          console.log(source_default.gray(`    ${doc.metadata.description}`));
+        const parts = doc.filename.split("/");
+        if (parts.length === 1) {
+          rootDocs.push(doc);
+        } else {
+          const folder = parts.slice(0, -1).join("/");
+          if (!folders.has(folder)) {
+            folders.set(folder, []);
+          }
+          folders.get(folder)?.push(doc);
         }
-        console.log(source_default.gray(`    File: ${doc.filename}`));
-        if (doc.metadata.tags && doc.metadata.tags.length > 0) {
-          console.log(source_default.gray(`    Tags: ${doc.metadata.tags.join(", ")}`));
+      }
+      console.log(source_default.bold(`
+Documentation (${filteredDocs.length})
+`));
+      const sortedFolders = Array.from(folders.keys()).sort();
+      for (const folder of sortedFolders) {
+        console.log(source_default.cyan.bold(`${folder}/`));
+        const docs2 = folders.get(folder)?.sort((a, b) => a.metadata.title.localeCompare(b.metadata.title));
+        for (const doc of docs2) {
+          console.log(source_default.white(`  ${doc.metadata.title}`));
+          if (doc.metadata.description) {
+            console.log(source_default.gray(`    ${doc.metadata.description}`));
+          }
+          if (doc.metadata.tags && doc.metadata.tags.length > 0) {
+            console.log(source_default.gray(`    Tags: ${doc.metadata.tags.join(", ")}`));
+          }
         }
-        console.log(source_default.gray(`    Updated: ${new Date(doc.metadata.updatedAt).toLocaleString()}`));
         console.log();
       }
-      console.log(source_default.gray(`Total: ${filteredDocs.length} document(s)
-`));
+      if (rootDocs.length > 0) {
+        rootDocs.sort((a, b) => a.metadata.title.localeCompare(b.metadata.title));
+        for (const doc of rootDocs) {
+          console.log(source_default.white(`${doc.metadata.title}`));
+          if (doc.metadata.description) {
+            console.log(source_default.gray(`  ${doc.metadata.description}`));
+          }
+          if (doc.metadata.tags && doc.metadata.tags.length > 0) {
+            console.log(source_default.gray(`  Tags: ${doc.metadata.tags.join(", ")}`));
+          }
+          console.log();
+        }
+      }
     }
   } catch (error46) {
     console.error(source_default.red("Error listing documentation:"), error46 instanceof Error ? error46.message : String(error46));
@@ -50539,11 +51223,11 @@ var viewCommand2 = new Command("view").description("View a documentation file").
     await ensureDocsDir();
     let filename = name.endsWith(".md") ? name : `${name}.md`;
     let filepath = join17(DOCS_DIR, filename);
-    if (!existsSync13(filepath)) {
+    if (!existsSync14(filepath)) {
       filename = `${titleToFilename(name)}.md`;
       filepath = join17(DOCS_DIR, filename);
     }
-    if (!existsSync13(filepath)) {
+    if (!existsSync14(filepath)) {
       const allFiles = await getAllMdFiles(DOCS_DIR);
       const searchName = name.toLowerCase().replace(/\.md$/, "");
       const matchingFile = allFiles.find((file3) => {
@@ -50556,12 +51240,12 @@ var viewCommand2 = new Command("view").description("View a documentation file").
         filepath = join17(DOCS_DIR, matchingFile);
       }
     }
-    if (!existsSync13(filepath)) {
+    if (!existsSync14(filepath)) {
       console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
       process.exit(1);
     }
-    const fileContent = await readFile9(filepath, "utf-8");
-    const { data, content } = (0, import_gray_matter5.default)(fileContent);
+    const fileContent = await readFile11(filepath, "utf-8");
+    const { data, content } = (0, import_gray_matter6.default)(fileContent);
     const metadata = data;
     if (options2.plain) {
       const border = "-".repeat(50);
@@ -50642,18 +51326,18 @@ var viewCommand2 = new Command("view").description("View a documentation file").
     process.exit(1);
   }
 });
-var editCommand2 = new Command("edit").description("Edit a documentation file (metadata and content)").argument("<name>", "Document name or path (e.g., guides/my-doc)").option("-t, --title <text>", "New title").option("-d, --description <text>", "New description").option("--tags <tags>", "Comma-separated tags").option("-c, --content <text>", "Replace content").option("-a, --append <text>", "Append to content").option("--plain", "Plain text output for AI").action(
+var editCommand2 = new Command("edit").description("Edit a documentation file (metadata and content)").argument("<name>", "Document name or path (e.g., guides/my-doc)").option("-t, --title <text>", "New title").option("-d, --description <text>", "New description").option("--tags <tags>", "Comma-separated tags").option("-c, --content <text>", "Replace content").option("-a, --append <text>", "Append to content").option("--content-file <path>", "Replace content with file contents").option("--append-file <path>", "Append file contents to document").option("--plain", "Plain text output for AI").action(
   async (name, options2) => {
     try {
       await ensureDocsDir();
       let filename = name.endsWith(".md") ? name : `${name}.md`;
       let filepath = join17(DOCS_DIR, filename);
-      if (!existsSync13(filepath)) {
+      if (!existsSync14(filepath)) {
         const baseName = name.includes("/") ? name : titleToFilename(name);
         filename = baseName.endsWith(".md") ? baseName : `${baseName}.md`;
         filepath = join17(DOCS_DIR, filename);
       }
-      if (!existsSync13(filepath)) {
+      if (!existsSync14(filepath)) {
         const allFiles = await getAllMdFiles(DOCS_DIR);
         const searchName = name.toLowerCase().replace(/\.md$/, "");
         const matchingFile = allFiles.find((file3) => {
@@ -50666,33 +51350,57 @@ var editCommand2 = new Command("edit").description("Edit a documentation file (m
           filepath = join17(DOCS_DIR, matchingFile);
         }
       }
-      if (!existsSync13(filepath)) {
+      if (!existsSync14(filepath)) {
         console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
         process.exit(1);
       }
-      const fileContent = await readFile9(filepath, "utf-8");
-      const { data, content } = (0, import_gray_matter5.default)(fileContent);
+      const fileContent = await readFile11(filepath, "utf-8");
+      const { data, content } = (0, import_gray_matter6.default)(fileContent);
       const metadata = data;
       if (options2.title) metadata.title = options2.title;
       if (options2.description) metadata.description = normalizeRefs(options2.description);
       if (options2.tags) metadata.tags = options2.tags.split(",").map((t) => t.trim());
       metadata.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
       let updatedContent = content;
-      if (options2.content) {
+      let sourceFile;
+      if (options2.contentFile) {
+        if (!existsSync14(options2.contentFile)) {
+          console.error(source_default.red(`\u2717 File not found: ${options2.contentFile}`));
+          process.exit(1);
+        }
+        const fileData = await readFile11(options2.contentFile, "utf-8");
+        updatedContent = normalizeRefs(fileData);
+        sourceFile = options2.contentFile;
+      } else if (options2.appendFile) {
+        if (!existsSync14(options2.appendFile)) {
+          console.error(source_default.red(`\u2717 File not found: ${options2.appendFile}`));
+          process.exit(1);
+        }
+        const fileData = await readFile11(options2.appendFile, "utf-8");
+        updatedContent = `${content.trimEnd()}
+
+${normalizeRefs(fileData)}`;
+        sourceFile = options2.appendFile;
+      } else if (options2.content) {
         updatedContent = normalizeRefs(options2.content);
-      }
-      if (options2.append) {
+      } else if (options2.append) {
         updatedContent = `${content.trimEnd()}
 
 ${normalizeRefs(options2.append)}`;
       }
-      const newFileContent = import_gray_matter5.default.stringify(updatedContent, metadata);
-      await writeFile7(filepath, newFileContent, "utf-8");
+      const newFileContent = import_gray_matter6.default.stringify(updatedContent, metadata);
+      await writeFile8(filepath, newFileContent, "utf-8");
       await notifyDocUpdate(filename);
       if (options2.plain) {
         console.log(`Updated: ${filename}`);
+        if (sourceFile) {
+          console.log(`Content from: ${sourceFile}`);
+        }
       } else {
         console.log(source_default.green(`\u2713 Updated documentation: ${source_default.bold(filename)}`));
+        if (sourceFile) {
+          console.log(source_default.gray(`  Content from: ${sourceFile}`));
+        }
       }
     } catch (error46) {
       console.error(
@@ -50703,7 +51411,285 @@ ${normalizeRefs(options2.append)}`;
     }
   }
 );
-var docCommand = new Command("doc").description("Manage documentation").argument("[name]", "Document name (shorthand for 'doc view <name>')").option("--plain", "Plain text output for AI").action(async (name, options2) => {
+var validateCommand2 = new Command("validate").description("Validate a documentation file format").argument("<name>", "Document name or path").option("--plain", "Plain text output for AI").action(async (name, options2) => {
+  try {
+    const resolved = await resolveDocPath(name);
+    if (!resolved) {
+      console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
+      process.exit(1);
+    }
+    const content = await readFile11(resolved.filepath, "utf-8");
+    const result = validateDoc(content);
+    if (options2.plain) {
+      console.log(`Validating: ${resolved.filename}`);
+      console.log(`Valid: ${result.valid}`);
+      if (result.errors.length > 0) {
+        console.log("\nErrors:");
+        for (const error46 of result.errors) {
+          console.log(`  \u2717 ${error46.field}: ${error46.message}${error46.fixable ? " (fixable)" : ""}`);
+        }
+      }
+      if (result.warnings.length > 0) {
+        console.log("\nWarnings:");
+        for (const warning of result.warnings) {
+          console.log(`  \u26A0 ${warning.field}: ${warning.message}`);
+        }
+      }
+      if (result.valid && result.warnings.length === 0) {
+        console.log("No issues found.");
+      }
+    } else {
+      console.log(source_default.bold(`
+\u{1F4CB} Validation: ${resolved.filename}
+`));
+      if (result.valid) {
+        console.log(source_default.green("\u2713 Document is valid"));
+      } else {
+        console.log(source_default.red("\u2717 Document has errors"));
+      }
+      if (result.errors.length > 0) {
+        console.log(source_default.red("\nErrors:"));
+        for (const error46 of result.errors) {
+          const fixable = error46.fixable ? source_default.gray(" (fixable)") : "";
+          console.log(source_default.red(`  \u2717 ${error46.field}: ${error46.message}${fixable}`));
+        }
+      }
+      if (result.warnings.length > 0) {
+        console.log(source_default.yellow("\nWarnings:"));
+        for (const warning of result.warnings) {
+          console.log(source_default.yellow(`  \u26A0 ${warning.field}: ${warning.message}`));
+        }
+      }
+      if (result.valid && result.warnings.length === 0) {
+        console.log(source_default.gray("\nNo issues found."));
+      }
+      console.log();
+    }
+    process.exit(result.valid ? 0 : 1);
+  } catch (error46) {
+    console.error(
+      source_default.red("Error validating documentation:"),
+      error46 instanceof Error ? error46.message : String(error46)
+    );
+    process.exit(1);
+  }
+});
+var repairCommand2 = new Command("repair").description("Repair a corrupted documentation file").argument("<name>", "Document name or path").option("--plain", "Plain text output for AI").action(async (name, options2) => {
+  try {
+    const resolved = await resolveDocPath(name);
+    if (!resolved) {
+      console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
+      process.exit(1);
+    }
+    const result = await repairDoc(resolved.filepath);
+    if (options2.plain) {
+      console.log(`Repairing: ${resolved.filename}`);
+      console.log(`Success: ${result.success}`);
+      if (result.backupPath) {
+        console.log(`Backup: ${result.backupPath}`);
+      }
+      if (result.fixes.length > 0) {
+        console.log("\nFixes applied:");
+        for (const fix of result.fixes) {
+          console.log(`  \u2713 ${fix}`);
+        }
+      }
+      if (result.errors.length > 0) {
+        console.log("\nErrors:");
+        for (const error46 of result.errors) {
+          console.log(`  \u2717 ${error46}`);
+        }
+      }
+    } else {
+      console.log(source_default.bold(`
+\u{1F527} Repair: ${resolved.filename}
+`));
+      if (result.success) {
+        console.log(source_default.green("\u2713 Document repaired successfully"));
+      } else {
+        console.log(source_default.red("\u2717 Repair failed"));
+      }
+      if (result.backupPath) {
+        console.log(source_default.gray(`  Backup created: ${result.backupPath}`));
+      }
+      if (result.fixes.length > 0) {
+        console.log(source_default.green("\nFixes applied:"));
+        for (const fix of result.fixes) {
+          console.log(source_default.green(`  \u2713 ${fix}`));
+        }
+      }
+      if (result.errors.length > 0) {
+        console.log(source_default.red("\nErrors:"));
+        for (const error46 of result.errors) {
+          console.log(source_default.red(`  \u2717 ${error46}`));
+        }
+      }
+      console.log();
+    }
+    if (result.success) {
+      await notifyDocUpdate(resolved.filename);
+    }
+    process.exit(result.success ? 0 : 1);
+  } catch (error46) {
+    console.error(
+      source_default.red("Error repairing documentation:"),
+      error46 instanceof Error ? error46.message : String(error46)
+    );
+    process.exit(1);
+  }
+});
+var searchInCommand = new Command("search-in").description("Search text within a specific document").argument("<name>", "Document name or path").argument("<query>", "Text to search for").option("--plain", "Plain text output for AI").option("-i, --ignore-case", "Case insensitive search").action(async (name, query, options2) => {
+  try {
+    const resolved = await resolveDocPath(name);
+    if (!resolved) {
+      console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
+      process.exit(1);
+    }
+    const fileContent = await readFile11(resolved.filepath, "utf-8");
+    const { content } = (0, import_gray_matter6.default)(fileContent);
+    const lines = content.split("\n");
+    const matches = [];
+    const searchQuery = options2.ignoreCase ? query.toLowerCase() : query;
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const searchLine = options2.ignoreCase ? line.toLowerCase() : line;
+      if (searchLine.includes(searchQuery)) {
+        const contextStart = Math.max(0, i - 1);
+        const contextEnd = Math.min(lines.length - 1, i + 1);
+        const context = lines.slice(contextStart, contextEnd + 1).join("\n");
+        matches.push({
+          lineNum: i + 1,
+          // 1-indexed
+          line,
+          context
+        });
+      }
+    }
+    if (options2.plain) {
+      console.log(`Searching in: ${resolved.filename}`);
+      console.log(`Query: "${query}"`);
+      console.log(`Found: ${matches.length} match(es)`);
+      console.log();
+      for (const match of matches) {
+        console.log(`Line ${match.lineNum}: ${match.line.trim()}`);
+      }
+    } else {
+      console.log(source_default.bold(`
+\u{1F50D} Search in: ${resolved.filename}
+`));
+      console.log(source_default.gray(`Query: "${query}"`));
+      console.log(source_default.gray(`Found: ${matches.length} match(es)
+`));
+      for (const match of matches) {
+        console.log(source_default.cyan(`Line ${match.lineNum}:`));
+        console.log(source_default.white(`  ${match.line.trim()}`));
+        console.log();
+      }
+    }
+  } catch (error46) {
+    console.error(source_default.red("Error searching document:"), error46 instanceof Error ? error46.message : String(error46));
+    process.exit(1);
+  }
+});
+var replaceCommand = new Command("replace").description("Replace text in a document").argument("<name>", "Document name or path").argument("<old-text>", "Text to find").argument("<new-text>", "Text to replace with").option("--plain", "Plain text output for AI").option("-a, --all", "Replace all occurrences (default: first only)").action(async (name, oldText, newText, options2) => {
+  try {
+    const resolved = await resolveDocPath(name);
+    if (!resolved) {
+      console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
+      process.exit(1);
+    }
+    const fileContent = await readFile11(resolved.filepath, "utf-8");
+    const { data, content } = (0, import_gray_matter6.default)(fileContent);
+    if (!content.includes(oldText)) {
+      if (options2.plain) {
+        console.log(`Text not found: "${oldText}"`);
+      } else {
+        console.log(source_default.yellow(`\u26A0 Text not found: "${oldText}"`));
+      }
+      process.exit(1);
+    }
+    let newContent;
+    let count = 0;
+    if (options2.all) {
+      const parts = content.split(oldText);
+      count = parts.length - 1;
+      newContent = parts.join(newText);
+    } else {
+      newContent = content.replace(oldText, newText);
+      count = 1;
+    }
+    const metadata = data;
+    metadata.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const updatedFileContent = import_gray_matter6.default.stringify(newContent, data);
+    await writeFile8(resolved.filepath, updatedFileContent, "utf-8");
+    await notifyDocUpdate(resolved.filename);
+    if (options2.plain) {
+      console.log(`Updated: ${resolved.filename}`);
+      console.log(`Replaced: ${count} occurrence(s)`);
+    } else {
+      console.log(source_default.green(`\u2713 Updated: ${resolved.filename}`));
+      console.log(source_default.gray(`  Replaced ${count} occurrence(s)`));
+    }
+  } catch (error46) {
+    console.error(source_default.red("Error replacing text:"), error46 instanceof Error ? error46.message : String(error46));
+    process.exit(1);
+  }
+});
+var replaceSectionCommand = new Command("replace-section").description("Replace an entire section by its header").argument("<name>", "Document name or path").argument("<header>", "Section header (e.g., '## Section Name')").argument("<content>", "New section content (without header)").option("--plain", "Plain text output for AI").action(async (name, header, newSectionContent, options2) => {
+  try {
+    const resolved = await resolveDocPath(name);
+    if (!resolved) {
+      console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
+      process.exit(1);
+    }
+    const fileContent = await readFile11(resolved.filepath, "utf-8");
+    const { data, content } = (0, import_gray_matter6.default)(fileContent);
+    const headerLevel = (header.match(/^#+/) || ["##"])[0];
+    const headerPattern = new RegExp(`^${header.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*$`, "m");
+    const headerMatch = content.match(headerPattern);
+    if (!headerMatch) {
+      if (options2.plain) {
+        console.log(`Section not found: "${header}"`);
+      } else {
+        console.log(source_default.yellow(`\u26A0 Section not found: "${header}"`));
+      }
+      process.exit(1);
+    }
+    const headerIndex = content.indexOf(headerMatch[0]);
+    const afterHeader = content.substring(headerIndex + headerMatch[0].length);
+    const nextHeaderPattern = new RegExp(`^#{1,${headerLevel.length}}\\s+`, "m");
+    const nextHeaderMatch = afterHeader.match(nextHeaderPattern);
+    let sectionEnd;
+    if (nextHeaderMatch) {
+      sectionEnd = headerIndex + headerMatch[0].length + afterHeader.indexOf(nextHeaderMatch[0]);
+    } else {
+      sectionEnd = content.length;
+    }
+    const beforeSection = content.substring(0, headerIndex);
+    const afterSection = content.substring(sectionEnd);
+    const newContent = `${beforeSection}${header}
+
+${newSectionContent}
+
+${afterSection.trimStart()}`;
+    const metadata = data;
+    metadata.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const updatedFileContent = import_gray_matter6.default.stringify(newContent.trim(), data);
+    await writeFile8(resolved.filepath, updatedFileContent, "utf-8");
+    await notifyDocUpdate(resolved.filename);
+    if (options2.plain) {
+      console.log(`Updated: ${resolved.filename}`);
+      console.log(`Replaced section: "${header}"`);
+    } else {
+      console.log(source_default.green(`\u2713 Updated: ${resolved.filename}`));
+      console.log(source_default.gray(`  Replaced section: "${header}"`));
+    }
+  } catch (error46) {
+    console.error(source_default.red("Error replacing section:"), error46 instanceof Error ? error46.message : String(error46));
+    process.exit(1);
+  }
+});
+var docCommand = new Command("doc").description("Manage documentation").argument("[name]", "Document name (shorthand for 'doc view <name>')").option("--plain", "Plain text output for AI").enablePositionalOptions().passThroughOptions().action(async (name, options2) => {
   if (!name) {
     docCommand.help();
     return;
@@ -50715,8 +51701,8 @@ var docCommand = new Command("doc").description("Manage documentation").argument
       process.exit(1);
     }
     const { filepath, filename } = resolved;
-    const fileContent = await readFile9(filepath, "utf-8");
-    const { data, content } = (0, import_gray_matter5.default)(fileContent);
+    const fileContent = await readFile11(filepath, "utf-8");
+    const { data, content } = (0, import_gray_matter6.default)(fileContent);
     const metadata = data;
     if (options2.plain) {
       const border = "-".repeat(50);
@@ -50801,10 +51787,15 @@ docCommand.addCommand(createCommand3);
 docCommand.addCommand(listCommand2);
 docCommand.addCommand(viewCommand2);
 docCommand.addCommand(editCommand2);
+docCommand.addCommand(validateCommand2);
+docCommand.addCommand(repairCommand2);
+docCommand.addCommand(searchInCommand);
+docCommand.addCommand(replaceCommand);
+docCommand.addCommand(replaceSectionCommand);
 
 // src/commands/config.ts
-import { existsSync as existsSync14 } from "node:fs";
-import { mkdir as mkdir8, readFile as readFile10, writeFile as writeFile8 } from "node:fs/promises";
+import { existsSync as existsSync15 } from "node:fs";
+import { mkdir as mkdir8, readFile as readFile12, writeFile as writeFile9 } from "node:fs/promises";
 import { join as join18 } from "node:path";
 
 // node_modules/zod/v4/classic/external.js
@@ -64363,11 +65354,11 @@ function getProjectRoot2() {
 }
 async function loadConfig(projectRoot) {
   const configPath = join18(projectRoot, CONFIG_FILE2);
-  if (!existsSync14(configPath)) {
+  if (!existsSync15(configPath)) {
     return { ...DEFAULT_CONFIG };
   }
   try {
-    const content = await readFile10(configPath, "utf-8");
+    const content = await readFile12(configPath, "utf-8");
     const data = JSON.parse(content);
     const settings = data.settings || {};
     const validated = ConfigSchema.parse(settings);
@@ -64383,20 +65374,20 @@ async function loadConfig(projectRoot) {
 async function saveConfig(projectRoot, config2) {
   const configPath = join18(projectRoot, CONFIG_FILE2);
   const knownsDir = join18(projectRoot, ".knowns");
-  if (!existsSync14(knownsDir)) {
+  if (!existsSync15(knownsDir)) {
     await mkdir8(knownsDir, { recursive: true });
   }
   try {
     let existingData = {};
-    if (existsSync14(configPath)) {
-      const content = await readFile10(configPath, "utf-8");
+    if (existsSync15(configPath)) {
+      const content = await readFile12(configPath, "utf-8");
       existingData = JSON.parse(content);
     }
     const merged = {
       ...existingData,
       settings: config2
     };
-    await writeFile8(configPath, JSON.stringify(merged, null, 2), "utf-8");
+    await writeFile9(configPath, JSON.stringify(merged, null, 2), "utf-8");
   } catch (error46) {
     console.error(source_default.red("\u2717 Failed to save config"));
     if (error46 instanceof Error) {
@@ -64538,8 +65529,8 @@ var resetCommand = new Command("reset").description("Reset configuration to defa
 var configCommand = new Command("config").description("Manage configuration settings").addCommand(listCommand3).addCommand(getCommand).addCommand(setCommand).addCommand(resetCommand);
 
 // src/mcp/server.ts
-import { existsSync as existsSync16 } from "node:fs";
-import { readFile as readFile13 } from "node:fs/promises";
+import { existsSync as existsSync17 } from "node:fs";
+import { readFile as readFile15 } from "node:fs/promises";
 import { join as join21 } from "node:path";
 
 // node_modules/zod/v3/helpers/util.js
@@ -71600,12 +72591,12 @@ var StdioServerTransport = class {
 };
 
 // src/mcp/server.ts
-var import_gray_matter8 = __toESM(require_gray_matter(), 1);
+var import_gray_matter9 = __toESM(require_gray_matter(), 1);
 
 // src/mcp/utils.ts
-import { readFile as readFile11 } from "node:fs/promises";
+import { readFile as readFile13 } from "node:fs/promises";
 import { join as join19 } from "node:path";
-var import_gray_matter6 = __toESM(require_gray_matter(), 1);
+var import_gray_matter7 = __toESM(require_gray_matter(), 1);
 function parseDuration2(durationStr) {
   let totalSeconds = 0;
   const hoursMatch = durationStr.match(/(\d+)h/);
@@ -71646,8 +72637,8 @@ async function fetchLinkedDocs(task) {
     try {
       const filename = ref.resolvedPath.replace("@.knowns/docs/", "");
       const filepath = join19(docsDir, filename);
-      const fileContent = await readFile11(filepath, "utf-8");
-      const { data, content } = (0, import_gray_matter6.default)(fileContent);
+      const fileContent = await readFile13(filepath, "utf-8");
+      const { data, content } = (0, import_gray_matter7.default)(fileContent);
       linkedDocs.push({
         path: ref.resolvedPath,
         title: data.title || ref.text,
@@ -72208,10 +73199,10 @@ async function handleGetBoard(fileStore2) {
 }
 
 // src/mcp/handlers/doc.ts
-import { existsSync as existsSync15 } from "node:fs";
-import { mkdir as mkdir9, readFile as readFile12, readdir as readdir6, writeFile as writeFile9 } from "node:fs/promises";
+import { existsSync as existsSync16 } from "node:fs";
+import { mkdir as mkdir9, readFile as readFile14, readdir as readdir6, writeFile as writeFile10 } from "node:fs/promises";
 import { join as join20 } from "node:path";
-var import_gray_matter7 = __toESM(require_gray_matter(), 1);
+var import_gray_matter8 = __toESM(require_gray_matter(), 1);
 var DOCS_DIR2 = join20(process.cwd(), ".knowns", "docs");
 var listDocsSchema = external_exports.object({
   tag: external_exports.string().optional()
@@ -72329,7 +73320,7 @@ var docTools = [
   }
 ];
 async function ensureDocsDir2() {
-  if (!existsSync15(DOCS_DIR2)) {
+  if (!existsSync16(DOCS_DIR2)) {
     await mkdir9(DOCS_DIR2, { recursive: true });
   }
 }
@@ -72338,7 +73329,7 @@ function titleToFilename2(title) {
 }
 async function getAllMdFiles2(dir, basePath = "") {
   const files = [];
-  if (!existsSync15(dir)) {
+  if (!existsSync16(dir)) {
     return files;
   }
   const entries = await readdir6(dir, { withFileTypes: true });
@@ -72358,12 +73349,12 @@ async function resolveDocPath2(name) {
   await ensureDocsDir2();
   let filename = name.endsWith(".md") ? name : `${name}.md`;
   let filepath = join20(DOCS_DIR2, filename);
-  if (existsSync15(filepath)) {
+  if (existsSync16(filepath)) {
     return { filepath, filename };
   }
   filename = `${titleToFilename2(name)}.md`;
   filepath = join20(DOCS_DIR2, filename);
-  if (existsSync15(filepath)) {
+  if (existsSync16(filepath)) {
     return { filepath, filename };
   }
   const allFiles = await getAllMdFiles2(DOCS_DIR2);
@@ -72394,8 +73385,8 @@ async function handleListDocs(args) {
   }
   const docs = [];
   for (const file3 of mdFiles) {
-    const content = await readFile12(join20(DOCS_DIR2, file3), "utf-8");
-    const { data } = (0, import_gray_matter7.default)(content);
+    const content = await readFile14(join20(DOCS_DIR2, file3), "utf-8");
+    const { data } = (0, import_gray_matter8.default)(content);
     const metadata = data;
     if (input.tag && !metadata.tags?.includes(input.tag)) {
       continue;
@@ -72419,8 +73410,8 @@ async function handleGetDoc(args) {
   if (!resolved) {
     return errorResponse(`Documentation not found: ${input.path}`);
   }
-  const fileContent = await readFile12(resolved.filepath, "utf-8");
-  const { data, content } = (0, import_gray_matter7.default)(fileContent);
+  const fileContent = await readFile14(resolved.filepath, "utf-8");
+  const { data, content } = (0, import_gray_matter8.default)(fileContent);
   const metadata = data;
   return successResponse({
     doc: {
@@ -72444,12 +73435,12 @@ async function handleCreateDoc(args) {
     const folderPath = input.folder.replace(/^\/|\/$/g, "");
     targetDir = join20(DOCS_DIR2, folderPath);
     relativePath = join20(folderPath, filename);
-    if (!existsSync15(targetDir)) {
+    if (!existsSync16(targetDir)) {
       await mkdir9(targetDir, { recursive: true });
     }
   }
   const filepath = join20(targetDir, filename);
-  if (existsSync15(filepath)) {
+  if (existsSync16(filepath)) {
     return errorResponse(`Document already exists: ${relativePath}`);
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
@@ -72465,8 +73456,8 @@ async function handleCreateDoc(args) {
     metadata.tags = input.tags;
   }
   const initialContent = input.content || "# Content\n\nWrite your documentation here.";
-  const fileContent = import_gray_matter7.default.stringify(initialContent, metadata);
-  await writeFile9(filepath, fileContent, "utf-8");
+  const fileContent = import_gray_matter8.default.stringify(initialContent, metadata);
+  await writeFile10(filepath, fileContent, "utf-8");
   await notifyDocUpdate(relativePath);
   return successResponse({
     message: `Created documentation: ${relativePath}`,
@@ -72484,8 +73475,8 @@ async function handleUpdateDoc(args) {
   if (!resolved) {
     return errorResponse(`Documentation not found: ${input.path}`);
   }
-  const fileContent = await readFile12(resolved.filepath, "utf-8");
-  const { data, content } = (0, import_gray_matter7.default)(fileContent);
+  const fileContent = await readFile14(resolved.filepath, "utf-8");
+  const { data, content } = (0, import_gray_matter8.default)(fileContent);
   const metadata = data;
   if (input.title) metadata.title = input.title;
   if (input.description) metadata.description = input.description;
@@ -72500,8 +73491,8 @@ async function handleUpdateDoc(args) {
 
 ${input.appendContent}`;
   }
-  const newFileContent = import_gray_matter7.default.stringify(updatedContent, metadata);
-  await writeFile9(resolved.filepath, newFileContent, "utf-8");
+  const newFileContent = import_gray_matter8.default.stringify(updatedContent, metadata);
+  await writeFile10(resolved.filepath, newFileContent, "utf-8");
   await notifyDocUpdate(resolved.filename);
   return successResponse({
     message: `Updated documentation: ${resolved.filename}`,
@@ -72521,8 +73512,8 @@ async function handleSearchDocs(args) {
   const query = input.query.toLowerCase();
   const results = [];
   for (const file3 of mdFiles) {
-    const fileContent = await readFile12(join20(DOCS_DIR2, file3), "utf-8");
-    const { data, content } = (0, import_gray_matter7.default)(fileContent);
+    const fileContent = await readFile14(join20(DOCS_DIR2, file3), "utf-8");
+    const { data, content } = (0, import_gray_matter8.default)(fileContent);
     const metadata = data;
     if (input.tag && !metadata.tags?.includes(input.tag)) {
       continue;
@@ -72630,7 +73621,7 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     description: `Task #${task.id}: ${task.title}`
   }));
   const docResources = [];
-  if (existsSync16(docsDir)) {
+  if (existsSync17(docsDir)) {
     const { readdir: readdir7 } = await import("node:fs/promises");
     async function getAllMdFiles3(dir, basePath = "") {
       const files = [];
@@ -72650,8 +73641,8 @@ server.setRequestHandler(ListResourcesRequestSchema, async () => {
     const mdFiles = await getAllMdFiles3(docsDir);
     for (const file3 of mdFiles) {
       const filepath = join21(docsDir, file3);
-      const content = await readFile13(filepath, "utf-8");
-      const { data } = (0, import_gray_matter8.default)(content);
+      const content = await readFile15(filepath, "utf-8");
+      const { data } = (0, import_gray_matter9.default)(content);
       docResources.push({
         uri: `knowns://doc/${file3.replace(/\.md$/, "")}`,
         name: data.title || file3.replace(/\.md$/, ""),
@@ -72688,11 +73679,11 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
     const docPath = docMatch[1];
     const docsDir = join21(process.cwd(), ".knowns", "docs");
     const filepath = join21(docsDir, `${docPath}.md`);
-    if (!existsSync16(filepath)) {
+    if (!existsSync17(filepath)) {
       throw new Error(`Documentation ${docPath} not found`);
     }
-    const content = await readFile13(filepath, "utf-8");
-    const { data, content: docContent } = (0, import_gray_matter8.default)(content);
+    const content = await readFile15(filepath, "utf-8");
+    const { data, content: docContent } = (0, import_gray_matter9.default)(content);
     return {
       contents: [
         {
@@ -72795,7 +73786,7 @@ function showConfigInfo() {
 // package.json
 var package_default = {
   name: "knowns",
-  version: "0.3.1",
+  version: "0.4.0",
   description: "CLI tool for dev teams to manage tasks and documentation",
   module: "index.ts",
   type: "module",
@@ -72928,7 +73919,7 @@ function showBanner() {
   console.log();
 }
 var program2 = new Command();
-program2.name("knowns").description("CLI tool for dev teams to manage tasks, track time, and sync").version(package_default.version);
+program2.name("knowns").description("CLI tool for dev teams to manage tasks, track time, and sync").version(package_default.version).enablePositionalOptions();
 program2.addCommand(initCommand);
 program2.addCommand(taskCommand);
 program2.addCommand(boardCommand);