knowns 0.8.6 → 0.8.7

package/dist/index.js

@@ -43475,68 +43475,166 @@ import { mkdir as mkdir3, readFile as readFile2, writeFile as writeFile2 } from
 import { dirname, join as join3 } from "node:path";
 var import_prompts = __toESM(require_prompts3(), 1);
 
-// src/templates/guidelines/core-rules.md
-var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion"   # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n```\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
+// src/templates/guidelines/cli/commands-reference.md
+var commands_reference_default = '# Commands Reference\n\n## task create\n\n```bash\nknowns task create <title> [options]\n```\n\n| Flag            | Short | Purpose                           |\n| --------------- | ----- | --------------------------------- |\n| `--description` | `-d`  | Task description                  |\n| `--ac`          |       | Acceptance criterion (repeatable) |\n| `--labels`      | `-l`  | Comma-separated labels            |\n| `--assignee`    | `-a`  | Assign to user \u26A0\uFE0F                 |\n| `--priority`    |       | low/medium/high                   |\n| `--status`      | `-s`  | Initial status                    |\n| `--parent`      |       | Parent task ID (raw ID only!)     |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task edit\n\n```bash\nknowns task edit <id> [options]\n```\n\n| Flag             | Short | Purpose                  |\n| ---------------- | ----- | ------------------------ |\n| `--title`        | `-t`  | Change title             |\n| `--description`  | `-d`  | Change description       |\n| `--status`       | `-s`  | Change status            |\n| `--priority`     |       | Change priority          |\n| `--labels`       | `-l`  | Set labels               |\n| `--assignee`     | `-a`  | Assign user \u26A0\uFE0F           |\n| `--parent`       |       | Move to parent           |\n| `--ac`           |       | Add acceptance criterion |\n| `--check-ac`     |       | Mark AC done (1-indexed) |\n| `--uncheck-ac`   |       | Unmark AC (1-indexed)    |\n| `--remove-ac`    |       | Delete AC (1-indexed)    |\n| `--plan`         |       | Set implementation plan  |\n| `--notes`        |       | Replace notes            |\n| `--append-notes` |       | Add to notes             |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain              # View single task\nknowns task list --plain              # List all\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain       # Tree hierarchy\n```\n\n---\n\n## doc create\n\n```bash\nknowns doc create <title> [options]\n```\n\n| Flag            | Short | Purpose              |\n| --------------- | ----- | -------------------- |\n| `--description` | `-d`  | Description          |\n| `--tags`        | `-t`  | Comma-separated tags |\n| `--folder`      | `-f`  | Folder path          |\n\n### Document Structure Best Practice\n\nWhen creating/editing docs, use clear heading structure for `--toc` and `--section` to work properly:\n\n```markdown\n# Main Title (H1 - only one)\n\n## 1. Overview\n\nBrief introduction...\n\n## 2. Installation\n\nStep-by-step guide...\n\n## 3. Configuration\n\n### 3.1 Basic Config\n\n...\n\n### 3.2 Advanced Config\n\n...\n\n## 4. API Reference\n\n...\n```\n\n**Writing rules:**\n\n- Use numbered headings (`## 1. Overview`) for easy `--section "1"` access\n- Keep H1 for title only, use H2 for main sections\n- Use H3 for subsections within H2\n- Each section should be self-contained (readable without context)\n\n**Reading workflow:**\n\n```bash\n# Step 1: Check size first\nknowns doc <path> --info --plain\n# \u2192 If <2000 tokens: read directly with --plain\n# \u2192 If >2000 tokens: continue to step 2\n\n# Step 2: Get table of contents\nknowns doc <path> --toc --plain\n\n# Step 3: Read specific section\nknowns doc <path> --section "2" --plain\n```\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag             | Short | Purpose                                   |\n| ---------------- | ----- | ----------------------------------------- |\n| `--title`        | `-t`  | Change title                              |\n| `--description`  | `-d`  | Change description                        |\n| `--tags`         |       | Set tags                                  |\n| `--content`      | `-c`  | Replace content (or section if --section) |\n| `--append`       | `-a`  | Append content \u26A0\uFE0F                         |\n| `--section`      |       | Target section to replace (use with -c)   |\n| `--content-file` |       | Content from file                         |\n| `--append-file`  |       | Append from file                          |\n\n**\u26A0\uFE0F In doc edit, `-a` = append content, NOT assignee!**\n\n### Section Edit (Context-Efficient)\n\nReplace only a specific section instead of entire document:\n\n```bash\n# Step 1: View TOC to find section\nknowns doc readme --toc --plain\n\n# Step 2: Edit only that section\nknowns doc edit readme --section "2. Installation" -c "New content here..."\nknowns doc edit readme --section "2" -c "New content..."  # By number works too\n```\n\nThis reduces context usage significantly - no need to read/write entire document.\n\n---\n\n## doc view/list\n\n```bash\nknowns doc <path> --plain             # View single doc\nknowns doc list --plain               # List all\nknowns doc list --tag api --plain     # Filter by tag\n```\n\n### Large Documents (--info, --toc, --section)\n\nFor large documents, check size first with `--info`, then use `--toc` and `--section`:\n\n```bash\n# Step 1: Check document size and token count\nknowns doc readme --info --plain\n# Output: Size: 42,461 chars (~12,132 tokens) | Headings: 83\n# Recommendation: Document is large. Use --toc first, then --section.\n\n# Step 2: View table of contents\nknowns doc readme --toc --plain\n\n# Step 3: Read specific section by title or number\nknowns doc readme --section "5. Sync" --plain\nknowns doc readme --section "3" --plain\n```\n\n**Decision flow:**\n\n- `--info` \u2192 Check size (~tokens) \u2192 If >2000 tokens, use --toc/--section\n- `--toc` \u2192 Get heading list \u2192 Choose section to read\n- `--section` \u2192 Read only what you need\n\n---\n\n## time\n\n```bash\nknowns time start <id>    # REQUIRED when taking task\nknowns time stop          # REQUIRED when completing\nknowns time pause\nknowns time resume\nknowns time status\nknowns time add <id> <duration> -n "Note" -d "2025-01-01"\n```\n\n---\n\n## search\n\n```bash\nknowns search "query" --plain\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input (Bash/Zsh)\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n';
+
+// src/templates/guidelines/cli/common-mistakes.md
+var common_mistakes_default = '# Common Mistakes\n\n## \u26A0\uFE0F CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# \u274C WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# \u2705 CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n\n## Quick Reference\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always `time start`/`stop` |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n';
+
+// src/templates/guidelines/cli/context-optimization.md
+var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Output Format\n\n```bash\n# \u274C Verbose output\nknowns task 42 --json\n\n# \u2705 Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n\n## Search Before Read\n\n```bash\n# \u274C Reading all docs to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\nknowns doc "doc3" --plain\n\n# \u2705 Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain  # Only the relevant one\n```\n\n---\n\n## Selective File Reading\n\n```bash\n# \u274C Reading entire large file\nRead file (2000+ lines)\n\n# \u2705 Read specific sections\nRead file with offset=100 limit=50\n```\n\n---\n\n## Large Documents (--info, --toc, --section)\n\nFor large documents, check size first with `--info`:\n\n```bash\n# \u274C Reading entire large document (may be truncated)\nknowns doc readme --plain\n\n# \u2705 Step 1: Check document size first\nknowns doc readme --info --plain\n# Output: Size: 42,461 chars (~12,132 tokens) | Headings: 83\n\n# \u2705 Step 2: View table of contents (if >2000 tokens)\nknowns doc readme --toc --plain\n\n# \u2705 Step 3: Read only the section you need\nknowns doc readme --section "3. Config" --plain\n```\n\n**Decision flow:** `--info` \u2192 check tokens \u2192 if >2000, use `--toc` then `--section`\n\n---\n\n## Compact Notes\n\n```bash\n# \u274C Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation of the authentication middleware which validates JWT tokens and handles refresh logic..."\n\n# \u2705 Compact notes\nknowns task edit 42 --append-notes "\u2713 Auth middleware + JWT validation done"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t                            | Do Instead                  |\n| -------------------------------- | --------------------------- |\n| Re-read files already in context | Reference from memory       |\n| List tasks/docs multiple times   | List once, remember results |\n| Quote entire file contents       | Summarize key points        |\n| Repeat full error messages       | Reference error briefly     |\n\n---\n\n## Efficient Workflow\n\n| Phase          | Context-Efficient Approach     |\n| -------------- | ------------------------------ |\n| **Research**   | Search \u2192 Read only matches     |\n| **Planning**   | Brief plan, not detailed prose |\n| **Coding**     | Read only files being modified |\n| **Notes**      | Bullet points, not paragraphs  |\n| **Completion** | Summary, not full log          |\n\n---\n\n## Quick Rules\n\n1. **Always `--plain`** - Never use `--json` unless specifically needed\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Read selectively** - Use offset/limit for large files\n4. **Use --info first** - Check doc size before reading, then --toc/--section if needed\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n7. **Summarize** - Key points, not full quotes\n';
 
-// src/templates/guidelines/commands-reference.md
-var commands_reference_default = '# Commands Reference\n\n## task create\n\n```bash\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Task description |\n| `--ac` | | Acceptance criterion (repeatable) |\n| `--labels` | `-l` | Comma-separated labels |\n| `--assignee` | `-a` | Assign to user \u26A0\uFE0F |\n| `--priority` | | low/medium/high |\n| `--status` | `-s` | Initial status |\n| `--parent` | | Parent task ID (raw ID only!) |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task edit\n\n```bash\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--status` | `-s` | Change status |\n| `--priority` | | Change priority |\n| `--labels` | `-l` | Set labels |\n| `--assignee` | `-a` | Assign user \u26A0\uFE0F |\n| `--parent` | | Move to parent |\n| `--ac` | | Add acceptance criterion |\n| `--check-ac` | | Mark AC done (1-indexed) |\n| `--uncheck-ac` | | Unmark AC (1-indexed) |\n| `--remove-ac` | | Delete AC (1-indexed) |\n| `--plan` | | Set implementation plan |\n| `--notes` | | Replace notes |\n| `--append-notes` | | Add to notes |\n\n**\u26A0\uFE0F `-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain              # View single task\nknowns task list --plain              # List all\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain       # Tree hierarchy\n```\n\n---\n\n## doc create\n\n```bash\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Description |\n| `--tags` | `-t` | Comma-separated tags |\n| `--folder` | `-f` | Folder path |\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--title` | `-t` | Change title |\n| `--description` | `-d` | Change description |\n| `--tags` | | Set tags |\n| `--content` | `-c` | Replace content |\n| `--append` | `-a` | Append content \u26A0\uFE0F |\n| `--content-file` | | Content from file |\n| `--append-file` | | Append from file |\n\n**\u26A0\uFE0F In doc edit, `-a` = append content, NOT assignee!**\n\n---\n\n## doc view/list\n\n```bash\nknowns doc <path> --plain             # View single doc\nknowns doc list --plain               # List all\nknowns doc list --tag api --plain     # Filter by tag\n```\n\n---\n\n## time\n\n```bash\nknowns time start <id>    # REQUIRED when taking task\nknowns time stop          # REQUIRED when completing\nknowns time pause\nknowns time resume\nknowns time status\nknowns time add <id> <duration> -n "Note" -d "2025-01-01"\n```\n\n---\n\n## search\n\n```bash\nknowns search "query" --plain\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input (Bash/Zsh)\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n';
+// src/templates/guidelines/cli/core-rules.md
+var core_rules_default = '# Core Rules\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## \u{1F3AF} The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use CLI commands or MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## \u26A0\uFE0F CRITICAL: The -a Flag Confusion\n\nThe `-a` flag means DIFFERENT things in different commands:\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `task edit` | `--assignee` (assign user) | ~~acceptance criteria~~ |\n| `doc edit` | `--append` (append content) | ~~assignee~~ |\n\n### Acceptance Criteria: Use --ac\n\n```bash\n# \u274C WRONG: -a is assignee, NOT acceptance criteria!\nknowns task edit 35 -a "- [ ] Criterion"    # Sets assignee to garbage!\nknowns task create "Title" -a "Criterion"   # Sets assignee to garbage!\n\n# \u2705 CORRECT: Use --ac for acceptance criteria\nknowns task edit 35 --ac "Criterion one"\nknowns task edit 35 --ac "Criterion two"\nknowns task create "Title" --ac "Criterion one" --ac "Criterion two"\n```\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **CLI/MCP Only** | Use commands for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## The --plain Flag\n\n**ONLY for view/list/search commands (NOT create/edit):**\n\n```bash\n# \u2705 CORRECT\nknowns task <id> --plain\nknowns task list --plain\nknowns doc "path" --plain\nknowns doc list --plain\nknowns search "query" --plain\n\n# \u274C WRONG (create/edit don\'t support --plain)\nknowns task create "Title" --plain       # ERROR!\nknowns task edit <id> -s done --plain    # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n```\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID for `--parent`:\n```bash\n# \u2705 CORRECT\nknowns task create "Title" --parent 48\n\n# \u274C WRONG\nknowns task create "Title" --parent task-48\n```\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n';
 
-// src/templates/guidelines/workflow-completion.md
+// src/templates/guidelines/cli/workflow-completion.md
 var workflow_completion_default = '# Task Completion\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n| Requirement | Command |\n|-------------|---------|\n| All AC checked | `knowns task edit <id> --check-ac N` |\n| Notes added | `knowns task edit <id> --notes "Summary"` |\n| Timer stopped | `knowns time stop` |\n| Status = done | `knowns task edit <id> -s done` |\n| Tests pass | Run test suite |\n\n---\n\n## Completion Steps\n\n```bash\n# 1. Verify all AC are checked\nknowns task <id> --plain\n\n# 2. Add implementation notes\nknowns task edit <id> --notes $\'## Summary\nWhat was done and key decisions.\'\n\n# 3. Stop timer (REQUIRED!)\nknowns time stop\n\n# 4. Mark done\nknowns task edit <id> -s done\n```\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n```bash\nknowns task edit <id> -s in-progress    # Reopen\nknowns time start <id>                   # Restart timer\nknowns task edit <id> --ac "Fix: description"\nknowns task edit <id> --append-notes "\u{1F504} Reopened: reason"\n# Complete work, then follow completion steps again\n```\n\n---\n\n## Checklist\n\n- [ ] All AC checked (`--check-ac`)\n- [ ] Notes added (`--notes`)\n- [ ] Timer stopped (`time stop`)\n- [ ] Tests pass\n- [ ] Status = done (`-s done`)\n';
 
-// src/templates/guidelines/workflow-creation.md
+// src/templates/guidelines/cli/workflow-creation.md
 var workflow_creation_default = '# Task Creation\n\n## Before Creating\n\n```bash\n# Search for existing tasks first\nknowns search "keyword" --type task --plain\n```\n\n---\n\n## Create Task\n\n```bash\nknowns task create "Clear title (WHAT)" \\\n  -d "Description (WHY)" \\\n  --ac "Outcome 1" \\\n  --ac "Outcome 2" \\\n  --priority medium \\\n  -l "labels"\n```\n\n---\n\n## Quality Guidelines\n\n### Title\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout |\n\n### Description\nExplain WHY. Include doc refs: `@doc/security-patterns`\n\n### Acceptance Criteria\n**Outcome-focused, NOT implementation steps:**\n\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Add handleLogin() function | User can login |\n| Use bcrypt | Passwords are hashed |\n| Add try-catch | Errors return proper HTTP codes |\n\n---\n\n## Subtasks\n\n```bash\nknowns task create "Parent task"\nknowns task create "Subtask" --parent 48  # Raw ID only!\n```\n\n---\n\n## Anti-Patterns\n\n- \u274C Too many AC in one task \u2192 Split into multiple tasks\n- \u274C Implementation steps as AC \u2192 Write outcomes instead\n- \u274C Skip search \u2192 Always check existing tasks first\n';
 
-// src/templates/guidelines/workflow-execution.md
+// src/templates/guidelines/cli/workflow-execution.md
 var workflow_execution_default = '# Task Execution\n\n## Step 1: Take Task\n\n```bash\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>    # REQUIRED!\n```\n\n---\n\n## Step 2: Research\n\n```bash\n# Read task and follow ALL refs\nknowns task <id> --plain\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search related docs\nknowns search "keyword" --type doc --plain\n\n# Check similar done tasks\nknowns search "keyword" --type task --status done --plain\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**\u26A0\uFE0F Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\nknowns task create "Follow-up: feature" -d "From task <id>"\n```\n\n**\u26A0\uFE0F Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
 
-// src/templates/guidelines/common-mistakes.md
-var common_mistakes_default = '# Common Mistakes\n\n## \u26A0\uFE0F CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# \u274C WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# \u2705 CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n\n## Quick Reference\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always `time start`/`stop` |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n';
+// src/templates/guidelines/cli/index.ts
+var CLI_CORE_RULES = core_rules_default.trim();
+var CLI_COMMANDS_REFERENCE = commands_reference_default.trim();
+var CLI_WORKFLOW_CREATION = workflow_creation_default.trim();
+var CLI_WORKFLOW_EXECUTION = workflow_execution_default.trim();
+var CLI_WORKFLOW_COMPLETION = workflow_completion_default.trim();
+var CLI_COMMON_MISTAKES = common_mistakes_default.trim();
+var CLI_CONTEXT_OPTIMIZATION = context_optimization_default.trim();
+var CLIGuidelines = {
+  // Core rules - always needed
+  core: CLI_CORE_RULES,
+  // Commands reference
+  commands: CLI_COMMANDS_REFERENCE,
+  // Workflow stages
+  workflow: {
+    creation: CLI_WORKFLOW_CREATION,
+    execution: CLI_WORKFLOW_EXECUTION,
+    completion: CLI_WORKFLOW_COMPLETION
+  },
+  // Common mistakes
+  mistakes: CLI_COMMON_MISTAKES,
+  // Context optimization
+  contextOptimization: CLI_CONTEXT_OPTIMIZATION,
+  /**
+   * Get full CLI guidelines (all sections combined)
+   */
+  getFull(withMarkers2 = false) {
+    const content = [
+      CLI_CORE_RULES,
+      "---",
+      CLI_CONTEXT_OPTIMIZATION,
+      "---",
+      CLI_COMMANDS_REFERENCE,
+      "---",
+      CLI_WORKFLOW_CREATION,
+      "---",
+      CLI_WORKFLOW_EXECUTION,
+      "---",
+      CLI_WORKFLOW_COMPLETION,
+      "---",
+      CLI_COMMON_MISTAKES
+    ].join("\n\n");
+    if (withMarkers2) {
+      return `<!-- KNOWNS GUIDELINES START -->
+${content}
+<!-- KNOWNS GUIDELINES END -->`;
+    }
+    return content;
+  },
+  /**
+   * Get compact CLI guidelines (core + context optimization + mistakes only)
+   */
+  getCompact() {
+    return [CLI_CORE_RULES, "---", CLI_CONTEXT_OPTIMIZATION, "---", CLI_COMMON_MISTAKES].join("\n\n");
+  },
+  /**
+   * Get CLI guidelines for specific workflow stage
+   */
+  getForStage(stage) {
+    const sections = [CLI_CORE_RULES, "---", CLI_CONTEXT_OPTIMIZATION, "---"];
+    switch (stage) {
+      case "creation":
+        sections.push(CLI_WORKFLOW_CREATION);
+        break;
+      case "execution":
+        sections.push(CLI_WORKFLOW_EXECUTION);
+        sections.push("---", CLI_COMMANDS_REFERENCE);
+        break;
+      case "completion":
+        sections.push(CLI_WORKFLOW_COMPLETION);
+        break;
+    }
+    sections.push("---", CLI_COMMON_MISTAKES);
+    return sections.join("\n\n");
+  }
+};
 
-// src/templates/guidelines/context-optimization.md
-var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Output Format\n\n```bash\n# \u274C Verbose output\nknowns task 42 --json\n\n# \u2705 Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n\n## Search Before Read\n\n```bash\n# \u274C Reading all docs to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\nknowns doc "doc3" --plain\n\n# \u2705 Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain  # Only the relevant one\n```\n\n---\n\n## Selective File Reading\n\n```bash\n# \u274C Reading entire large file\nRead file (2000+ lines)\n\n# \u2705 Read specific sections\nRead file with offset=100 limit=50\n```\n\n---\n\n## Compact Notes\n\n```bash\n# \u274C Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation of the authentication middleware which validates JWT tokens and handles refresh logic..."\n\n# \u2705 Compact notes\nknowns task edit 42 --append-notes "\u2713 Auth middleware + JWT validation done"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t | Do Instead |\n|-------|------------|\n| Re-read files already in context | Reference from memory |\n| List tasks/docs multiple times | List once, remember results |\n| Quote entire file contents | Summarize key points |\n| Repeat full error messages | Reference error briefly |\n\n---\n\n## Efficient Workflow\n\n| Phase | Context-Efficient Approach |\n|-------|---------------------------|\n| **Research** | Search \u2192 Read only matches |\n| **Planning** | Brief plan, not detailed prose |\n| **Coding** | Read only files being modified |\n| **Notes** | Bullet points, not paragraphs |\n| **Completion** | Summary, not full log |\n\n---\n\n## Quick Rules\n\n1. **Always `--plain`** - Never use `--json` unless specifically needed\n2. **Search first** - Don\'t read all docs hoping to find info\n3. **Read selectively** - Use offset/limit for large files\n4. **Write concise** - Compact notes, not essays\n5. **Don\'t repeat** - Reference context already loaded\n6. **Summarize** - Key points, not full quotes\n';
+// src/templates/guidelines/mcp/commands-reference.md
+var commands_reference_default2 = '# MCP Tools Reference\n\n## mcp**knowns**create_task\n\nCreate a new task.\n\n```json\n{\n  "title": "Task title",\n  "description": "Task description",\n  "status": "todo",\n  "priority": "medium",\n  "labels": ["label1", "label2"],\n  "assignee": "@me",\n  "parent": "parent-task-id"\n}\n```\n\n| Parameter     | Required | Description                             |\n| ------------- | -------- | --------------------------------------- |\n| `title`       | Yes      | Task title                              |\n| `description` | No       | Task description                        |\n| `status`      | No       | todo/in-progress/in-review/blocked/done |\n| `priority`    | No       | low/medium/high                         |\n| `labels`      | No       | Array of labels                         |\n| `assignee`    | No       | Assignee (use @me for self)             |\n| `parent`      | No       | Parent task ID for subtasks             |\n\n**Note:** Acceptance criteria must be added via `mcp__knowns__update_task` after creation.\n\n---\n\n## mcp**knowns**update_task\n\nUpdate task fields.\n\n```json\n{\n  "taskId": "abc123",\n  "title": "New title",\n  "description": "New description",\n  "status": "in-progress",\n  "priority": "high",\n  "labels": ["updated"],\n  "assignee": "@me"\n}\n```\n\n| Parameter     | Required | Description       |\n| ------------- | -------- | ----------------- |\n| `taskId`      | Yes      | Task ID to update |\n| `title`       | No       | New title         |\n| `description` | No       | New description   |\n| `status`      | No       | New status        |\n| `priority`    | No       | New priority      |\n| `labels`      | No       | New labels array  |\n| `assignee`    | No       | New assignee      |\n\n**Note:** For acceptance criteria, implementation plan, and notes - use CLI commands or edit task file directly through knowns CLI.\n\n---\n\n## mcp**knowns**get_task\n\nGet a task by ID.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**list_tasks\n\nList tasks with optional filters.\n\n```json\n{\n  "status": "in-progress",\n  "priority": "high",\n  "assignee": "@me",\n  "label": "bug"\n}\n```\n\nAll parameters are optional filters.\n\n---\n\n## mcp**knowns**search_tasks\n\nSearch tasks by query string.\n\n```json\n{\n  "query": "authentication"\n}\n```\n\n---\n\n## mcp**knowns**get_doc\n\nGet a documentation file by path.\n\n```json\n{\n  "path": "README"\n}\n```\n\nPath can be filename or folder/filename (without .md extension).\n\n### Large Documents (info, toc, section)\n\nFor large documents, check size first with `info`, then use `toc` and `section`:\n\n```json\n// Step 1: Check document size and token count\n{\n  "path": "readme",\n  "info": true\n}\n// Response: { stats: { chars: 42461, estimatedTokens: 12132, headingCount: 83 }, recommendation: "..." }\n\n// Step 2: Get table of contents\n{\n  "path": "readme",\n  "toc": true\n}\n\n// Step 3: Read specific section by title or number\n{\n  "path": "readme",\n  "section": "5. Sync"\n}\n```\n\n| Parameter | Description                                              |\n| --------- | -------------------------------------------------------- |\n| `info`    | Set `true` to get stats (size, tokens, headings) only    |\n| `toc`     | Set `true` to get table of contents only                 |\n| `section` | Section title or number to read (e.g., "5. Sync" or "3") |\n\n**Decision flow:**\n\n- `info: true` \u2192 Check estimatedTokens \u2192 If >2000, use toc/section\n- `toc: true` \u2192 Get heading list \u2192 Choose section to read\n- `section: "X"` \u2192 Read only what you need\n\n---\n\n## mcp**knowns**list_docs\n\nList all documentation files.\n\n```json\n{\n  "tag": "api"\n}\n```\n\nOptional `tag` parameter to filter by tag.\n\n---\n\n## mcp**knowns**create_doc\n\nCreate a new documentation file.\n\n```json\n{\n  "title": "Doc Title",\n  "description": "Doc description",\n  "tags": ["tag1", "tag2"],\n  "folder": "guides",\n  "content": "Initial content"\n}\n```\n\n### Document Structure Best Practice\n\nWhen creating/updating docs, use clear heading structure for `toc` and `section` to work properly:\n\n```markdown\n# Main Title (H1 - only one)\n\n## 1. Overview\n\nBrief introduction...\n\n## 2. Installation\n\nStep-by-step guide...\n\n## 3. Configuration\n\n### 3.1 Basic Config\n\n...\n\n### 3.2 Advanced Config\n\n...\n\n## 4. API Reference\n\n...\n```\n\n**Writing rules:**\n\n- Use numbered headings (`## 1. Overview`) for easy `section: "1"` access\n- Keep H1 for title only, use H2 for main sections\n- Use H3 for subsections within H2\n- Each section should be self-contained (readable without context)\n\n**Reading workflow:**\n\n```json\n// Step 1: Check size first\n{ "path": "<path>", "info": true }\n// \u2192 If estimatedTokens <2000: read directly (no options)\n// \u2192 If estimatedTokens >2000: continue to step 2\n\n// Step 2: Get table of contents\n{ "path": "<path>", "toc": true }\n\n// Step 3: Read specific section\n{ "path": "<path>", "section": "2" }\n```\n\n---\n\n## mcp**knowns**update_doc\n\nUpdate an existing documentation file.\n\n```json\n{\n  "path": "README",\n  "title": "New Title",\n  "description": "New description",\n  "tags": ["new", "tags"],\n  "content": "Replace content",\n  "appendContent": "Append to existing"\n}\n```\n\nUse either `content` (replace) or `appendContent` (append), not both.\n\n### Section Edit (Context-Efficient)\n\nReplace only a specific section instead of entire document:\n\n```json\n// Step 1: View TOC to find section\n{ "path": "readme", "toc": true }\n\n// Step 2: Edit only that section\n{\n  "path": "readme",\n  "section": "2. Installation",\n  "content": "New content here..."\n}\n```\n\nThis reduces context usage significantly - no need to read/write entire document.\n\n---\n\n## mcp**knowns**search_docs\n\nSearch documentation by query.\n\n```json\n{\n  "query": "authentication",\n  "tag": "api"\n}\n```\n\n---\n\n## mcp**knowns**start_time\n\nStart time tracking for a task.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**stop_time\n\nStop time tracking.\n\n```json\n{\n  "taskId": "abc123"\n}\n```\n\n---\n\n## mcp**knowns**add_time\n\nManually add a time entry.\n\n```json\n{\n  "taskId": "abc123",\n  "duration": "2h30m",\n  "note": "Optional note",\n  "date": "2025-01-15"\n}\n```\n\n---\n\n## mcp**knowns**get_time_report\n\nGet time tracking report.\n\n```json\n{\n  "from": "2025-01-01",\n  "to": "2025-01-31",\n  "groupBy": "task"\n}\n```\n\n`groupBy` can be: task, label, or status.\n\n---\n\n## mcp**knowns**get_board\n\nGet current board state with tasks grouped by status.\n\n```json\n{}\n```\n\nNo parameters required.\n';
 
-// src/templates/guidelines/index.ts
-var CORE_RULES = core_rules_default.trim();
-var COMMANDS_REFERENCE = commands_reference_default.trim();
-var WORKFLOW_CREATION = workflow_creation_default.trim();
-var WORKFLOW_EXECUTION = workflow_execution_default.trim();
-var WORKFLOW_COMPLETION = workflow_completion_default.trim();
-var COMMON_MISTAKES = common_mistakes_default.trim();
-var CONTEXT_OPTIMIZATION = context_optimization_default.trim();
-var Guidelines = {
+// src/templates/guidelines/mcp/common-mistakes.md
+var common_mistakes_default2 = "# Common Mistakes (MCP)\n\n## Quick Reference\n\n| DON'T | DO |\n|-------|-----|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | Always `start_time`/`stop_time` |\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Ignore task refs | Follow ALL `@.knowns/...` refs |\n| Use wrong task ID format | Use raw ID string |\n\n---\n\n## MCP vs CLI Usage\n\nSome operations require CLI (not available in MCP):\n\n| Operation | Tool |\n|-----------|------|\n| Add acceptance criteria | CLI: `--ac` |\n| Check/uncheck AC | CLI: `--check-ac`, `--uncheck-ac` |\n| Set implementation plan | CLI: `--plan` |\n| Add/append notes | CLI: `--notes`, `--append-notes` |\n| Create/update task basic fields | MCP tools |\n| Time tracking | MCP tools |\n| Read tasks/docs | MCP tools |\n| Search | MCP tools |\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Forgot to stop timer | `mcp__knowns__add_time` with duration |\n| Wrong status | `mcp__knowns__update_task` to fix |\n| Task not found | `mcp__knowns__list_tasks` to find ID |\n| Need to uncheck AC | CLI: `knowns task edit <id> --uncheck-ac N` |\n";
+
+// src/templates/guidelines/mcp/context-optimization.md
+var context_optimization_default2 = '# Context Optimization (MCP)\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n## Search Before Read\n\n```json\n// DON\'T: Read all docs hoping to find info\nmcp__knowns__get_doc({ "path": "doc1" })\nmcp__knowns__get_doc({ "path": "doc2" })\nmcp__knowns__get_doc({ "path": "doc3" })\n\n// DO: Search first, then read only relevant docs\nmcp__knowns__search_docs({ "query": "authentication" })\nmcp__knowns__get_doc({ "path": "security-patterns" })  // Only the relevant one\n```\n\n---\n\n## Use Filters\n\n```json\n// DON\'T: List all tasks then filter manually\nmcp__knowns__list_tasks({})\n\n// DO: Use filters in the query\nmcp__knowns__list_tasks({\n  "status": "in-progress",\n  "assignee": "@me"\n})\n```\n\n---\n\n## Large Documents (info, toc, section)\n\nFor large documents, check size first with `info`:\n\n```json\n// DON\'T: Read entire large document (may be truncated)\nmcp__knowns__get_doc({ "path": "readme" })\n\n// DO: Step 1 - Check document size first\nmcp__knowns__get_doc({ "path": "readme", "info": true })\n// Response: { stats: { estimatedTokens: 12132 }, recommendation: "..." }\n\n// DO: Step 2 - Get table of contents (if >2000 tokens)\nmcp__knowns__get_doc({ "path": "readme", "toc": true })\n\n// DO: Step 3 - Read only the section you need\nmcp__knowns__get_doc({ "path": "readme", "section": "3. Config" })\n```\n\n**Decision flow:** `info: true` \u2192 check tokens \u2192 if >2000, use `toc` then `section`\n\n---\n\n## Compact Notes\n\n```bash\n# DON\'T: Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation..."\n\n# DO: Compact notes\nknowns task edit 42 --append-notes "Done: Auth middleware + JWT validation"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t                                 | Do Instead                  |\n| ------------------------------------- | --------------------------- |\n| Re-read tasks/docs already in context | Reference from memory       |\n| List tasks/docs multiple times        | List once, remember results |\n| Fetch same task repeatedly            | Cache the result            |\n\n---\n\n## Efficient Workflow\n\n| Phase          | Context-Efficient Approach     |\n| -------------- | ------------------------------ |\n| **Research**   | Search -> Read only matches    |\n| **Planning**   | Brief plan, not detailed prose |\n| **Coding**     | Read only files being modified |\n| **Notes**      | Bullet points, not paragraphs  |\n| **Completion** | Summary, not full log          |\n\n---\n\n## Quick Rules\n\n1. **Search first** - Don\'t read all docs hoping to find info\n2. **Use filters** - Don\'t list everything then filter manually\n3. **Read selectively** - Only fetch what you need\n4. **Use info first** - Check doc size before reading, then toc/section if needed\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n7. **Summarize** - Key points, not full quotes\n';
+
+// src/templates/guidelines/mcp/core-rules.md
+var core_rules_default2 = "# Core Rules (MCP)\n\nYou MUST follow these rules. If you cannot follow any rule, stop and ask for guidance before proceeding.\n\n---\n\n## The Golden Rule\n\n**If you want to change ANYTHING in a task or doc, use MCP tools. NEVER edit .md files directly.**\n\nWhy? Direct file editing breaks metadata synchronization, Git tracking, and relationships.\n\n---\n\n## Core Principles\n\n| Rule | Description |\n|------|-------------|\n| **MCP Tools Only** | Use MCP tools for ALL operations. NEVER edit .md files directly |\n| **Docs First** | Read project docs BEFORE planning or coding |\n| **Time Tracking** | Always start timer when taking task, stop when done |\n| **Plan Approval** | Share plan with user, WAIT for approval before coding |\n| **Check AC After Work** | Only mark acceptance criteria done AFTER completing the work |\n\n---\n\n## Reference System\n\n| Context | Task Format | Doc Format |\n|---------|-------------|------------|\n| **Writing** (input) | `@task-<id>` | `@doc/<path>` |\n| **Reading** (output) | `@.knowns/tasks/task-<id>` | `@.knowns/docs/<path>.md` |\n\nFollow refs recursively until complete context gathered.\n\n---\n\n## Task IDs\n\n| Format | Example | Notes |\n|--------|---------|-------|\n| Sequential | `48`, `49` | Legacy numeric |\n| Hierarchical | `48.1`, `48.2` | Legacy subtasks |\n| Random | `qkh5ne` | Current (6-char) |\n\n**CRITICAL:** Use raw ID (string) for all MCP tool calls.\n\n---\n\n## Status & Priority\n\n| Status | When |\n|--------|------|\n| `todo` | Not started (default) |\n| `in-progress` | Currently working |\n| `in-review` | PR submitted |\n| `blocked` | Waiting on dependency |\n| `done` | All criteria met |\n\n| Priority | Level |\n|----------|-------|\n| `low` | Nice-to-have |\n| `medium` | Normal (default) |\n| `high` | Urgent |\n";
+
+// src/templates/guidelines/mcp/workflow-completion.md
+var workflow_completion_default2 = '# Task Completion (MCP)\n\n## Definition of Done\n\nA task is **Done** when ALL of these are complete:\n\n| Requirement | How |\n|-------------|-----|\n| All AC checked | CLI: `knowns task edit <id> --check-ac N` |\n| Notes added | CLI: `knowns task edit <id> --notes "Summary"` |\n| Timer stopped | MCP: `mcp__knowns__stop_time` |\n| Status = done | MCP: `mcp__knowns__update_task` |\n| Tests pass | Run test suite |\n\n---\n\n## Completion Steps\n\n```json\n// 1. Verify all AC are checked\nmcp__knowns__get_task({ "taskId": "abc123" })\n```\n\n```bash\n# 2. Add implementation notes (use CLI)\nknowns task edit abc123 --notes $\'## Summary\nWhat was done and key decisions.\'\n```\n\n```json\n// 3. Stop timer (REQUIRED!)\nmcp__knowns__stop_time({ "taskId": "abc123" })\n\n// 4. Mark done\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "done"\n})\n```\n\n---\n\n## Post-Completion Changes\n\nIf user requests changes after task is done:\n\n```json\n// 1. Reopen task\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "in-progress"\n})\n\n// 2. Restart timer\nmcp__knowns__start_time({ "taskId": "abc123" })\n```\n\n```bash\n# 3. Add AC for the fix\nknowns task edit abc123 --ac "Fix: description"\nknowns task edit abc123 --append-notes "Reopened: reason"\n```\n\nThen follow completion steps again.\n\n---\n\n## Checklist\n\n- [ ] All AC checked (CLI `--check-ac`)\n- [ ] Notes added (CLI `--notes`)\n- [ ] Timer stopped (`mcp__knowns__stop_time`)\n- [ ] Tests pass\n- [ ] Status = done (`mcp__knowns__update_task`)\n';
+
+// src/templates/guidelines/mcp/workflow-creation.md
+var workflow_creation_default2 = '# Task Creation (MCP)\n\n## Before Creating\n\n```json\n// Search for existing tasks first\nmcp__knowns__search_tasks({ "query": "keyword" })\n```\n\n---\n\n## Create Task\n\n```json\nmcp__knowns__create_task({\n  "title": "Clear title (WHAT)",\n  "description": "Description (WHY). Related: @doc/security-patterns",\n  "priority": "medium",\n  "labels": ["feature", "auth"]\n})\n```\n\n**Note:** Add acceptance criteria after creation using CLI:\n```bash\nknowns task edit <id> --ac "Outcome 1" --ac "Outcome 2"\n```\n\n---\n\n## Quality Guidelines\n\n### Title\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout |\n\n### Description\nExplain WHY. Include doc refs: `@doc/security-patterns`\n\n### Acceptance Criteria\n**Outcome-focused, NOT implementation steps:**\n\n| Bad | Good |\n|-----|------|\n| Add handleLogin() function | User can login |\n| Use bcrypt | Passwords are hashed |\n| Add try-catch | Errors return proper HTTP codes |\n\n---\n\n## Subtasks\n\n```json\n// Create parent first\nmcp__knowns__create_task({ "title": "Parent task" })\n\n// Then create subtask with parent ID\nmcp__knowns__create_task({\n  "title": "Subtask",\n  "parent": "parent-task-id"\n})\n```\n\n---\n\n## Anti-Patterns\n\n- Too many AC in one task -> Split into multiple tasks\n- Implementation steps as AC -> Write outcomes instead\n- Skip search -> Always check existing tasks first\n';
+
+// src/templates/guidelines/mcp/workflow-execution.md
+var workflow_execution_default2 = '# Task Execution (MCP)\n\n## Step 1: Take Task\n\n```json\n// Update status and assignee\nmcp__knowns__update_task({\n  "taskId": "abc123",\n  "status": "in-progress",\n  "assignee": "@me"\n})\n\n// Start timer (REQUIRED!)\nmcp__knowns__start_time({ "taskId": "abc123" })\n```\n\n---\n\n## Step 2: Research\n\n```json\n// Read task and follow ALL refs\nmcp__knowns__get_task({ "taskId": "abc123" })\n\n// @.knowns/docs/xxx.md -> read the doc\nmcp__knowns__get_doc({ "path": "xxx" })\n\n// @.knowns/tasks/task-YY -> read the task\nmcp__knowns__get_task({ "taskId": "YY" })\n\n// Search related docs\nmcp__knowns__search_docs({ "query": "keyword" })\n\n// Check similar done tasks\nmcp__knowns__list_tasks({ "status": "done" })\n```\n\n---\n\n## Step 3: Plan (BEFORE coding!)\n\nUse CLI for implementation plan:\n```bash\nknowns task edit <id> --plan $\'1. Research (see @doc/xxx)\n2. Implement\n3. Test\n4. Document\'\n```\n\n**Share plan with user. WAIT for approval before coding.**\n\n---\n\n## Step 4: Implement\n\nUse CLI for checking acceptance criteria:\n```bash\n# Check AC only AFTER work is done\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "Done: feature X"\n```\n\n---\n\n## Scope Changes\n\nIf new requirements emerge during work:\n\n```bash\n# Small: Add to current task\nknowns task edit <id> --ac "New requirement"\nknowns task edit <id> --append-notes "Scope updated: reason"\n\n# Large: Ask user first, then create follow-up\n```\n\n```json\nmcp__knowns__create_task({\n  "title": "Follow-up: feature",\n  "description": "From task <id>"\n})\n```\n\n**Don\'t silently expand scope. Ask user first.**\n\n---\n\n## Key Rules\n\n1. **Plan before code** - Capture approach first\n2. **Wait for approval** - Don\'t start without OK\n3. **Check AC after work** - Not before\n4. **Ask on scope changes** - Don\'t expand silently\n';
+
+// src/templates/guidelines/mcp/index.ts
+var MCP_CORE_RULES = core_rules_default2.trim();
+var MCP_COMMANDS_REFERENCE = commands_reference_default2.trim();
+var MCP_WORKFLOW_CREATION = workflow_creation_default2.trim();
+var MCP_WORKFLOW_EXECUTION = workflow_execution_default2.trim();
+var MCP_WORKFLOW_COMPLETION = workflow_completion_default2.trim();
+var MCP_COMMON_MISTAKES = common_mistakes_default2.trim();
+var MCP_CONTEXT_OPTIMIZATION = context_optimization_default2.trim();
+var MCPGuidelines = {
   // Core rules - always needed
-  core: CORE_RULES,
+  core: MCP_CORE_RULES,
   // Commands reference
-  commands: COMMANDS_REFERENCE,
+  commands: MCP_COMMANDS_REFERENCE,
   // Workflow stages
   workflow: {
-    creation: WORKFLOW_CREATION,
-    execution: WORKFLOW_EXECUTION,
-    completion: WORKFLOW_COMPLETION
+    creation: MCP_WORKFLOW_CREATION,
+    execution: MCP_WORKFLOW_EXECUTION,
+    completion: MCP_WORKFLOW_COMPLETION
   },
   // Common mistakes
-  mistakes: COMMON_MISTAKES,
+  mistakes: MCP_COMMON_MISTAKES,
   // Context optimization
-  contextOptimization: CONTEXT_OPTIMIZATION,
+  contextOptimization: MCP_CONTEXT_OPTIMIZATION,
   /**
-   * Get full guidelines (all sections combined)
+   * Get full MCP guidelines (all sections combined)
    */
   getFull(withMarkers2 = false) {
     const content = [
-      CORE_RULES,
+      MCP_CORE_RULES,
       "---",
-      CONTEXT_OPTIMIZATION,
+      MCP_CONTEXT_OPTIMIZATION,
       "---",
-      COMMANDS_REFERENCE,
+      MCP_COMMANDS_REFERENCE,
       "---",
-      WORKFLOW_CREATION,
+      MCP_WORKFLOW_CREATION,
       "---",
-      WORKFLOW_EXECUTION,
+      MCP_WORKFLOW_EXECUTION,
       "---",
-      WORKFLOW_COMPLETION,
+      MCP_WORKFLOW_COMPLETION,
       "---",
-      COMMON_MISTAKES
+      MCP_COMMON_MISTAKES
     ].join("\n\n");
     if (withMarkers2) {
       return `<!-- KNOWNS GUIDELINES START -->
@@ -43546,33 +43644,43 @@ ${content}
     return content;
   },
   /**
-   * Get compact guidelines (core + context optimization + mistakes only)
+   * Get compact MCP guidelines (core + context optimization + mistakes only)
    */
   getCompact() {
-    return [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---", COMMON_MISTAKES].join("\n\n");
+    return [MCP_CORE_RULES, "---", MCP_CONTEXT_OPTIMIZATION, "---", MCP_COMMON_MISTAKES].join("\n\n");
   },
   /**
-   * Get guidelines for specific workflow stage
+   * Get MCP guidelines for specific workflow stage
    */
   getForStage(stage) {
-    const sections = [CORE_RULES, "---", CONTEXT_OPTIMIZATION, "---"];
+    const sections = [MCP_CORE_RULES, "---", MCP_CONTEXT_OPTIMIZATION, "---"];
     switch (stage) {
       case "creation":
-        sections.push(WORKFLOW_CREATION);
+        sections.push(MCP_WORKFLOW_CREATION);
         break;
       case "execution":
-        sections.push(WORKFLOW_EXECUTION);
-        sections.push("---", COMMANDS_REFERENCE);
+        sections.push(MCP_WORKFLOW_EXECUTION);
+        sections.push("---", MCP_COMMANDS_REFERENCE);
         break;
       case "completion":
-        sections.push(WORKFLOW_COMPLETION);
+        sections.push(MCP_WORKFLOW_COMPLETION);
         break;
     }
-    sections.push("---", COMMON_MISTAKES);
+    sections.push("---", MCP_COMMON_MISTAKES);
     return sections.join("\n\n");
   }
 };
 
+// src/templates/guidelines/index.ts
+var Guidelines = CLIGuidelines;
+var CORE_RULES = CLIGuidelines.core;
+var COMMANDS_REFERENCE = CLIGuidelines.commands;
+var WORKFLOW_CREATION = CLIGuidelines.workflow.creation;
+var WORKFLOW_EXECUTION = CLIGuidelines.workflow.execution;
+var WORKFLOW_COMPLETION = CLIGuidelines.workflow.completion;
+var COMMON_MISTAKES = CLIGuidelines.mistakes;
+var CONTEXT_OPTIMIZATION = CLIGuidelines.contextOptimization;
+
 // src/templates/instruction/cli.md
 var cli_default = '# Knowns Project\n\nThis project uses **Knowns CLI** for task and documentation management.\n\n## Before Starting\n\nRun this command to get usage guidelines:\n\n```bash\nknowns agents guideline\n```\n\nYou MUST call this at session start and follow every rule it outputs.\n\n## Context-Specific Guidelines\n\nGet guidelines for specific workflow stages:\n\n```bash\n# Full guidelines (all sections)\nknowns agents guideline --full\n\n# Compact (core rules + common mistakes)\nknowns agents guideline --compact\n\n# By workflow stage\nknowns agents guideline --stage creation    # Creating tasks\nknowns agents guideline --stage execution   # Implementing tasks\nknowns agents guideline --stage completion  # Completing tasks\n\n# Individual sections\nknowns agents guideline --core       # Core rules only\nknowns agents guideline --commands   # Commands reference\nknowns agents guideline --mistakes   # Common mistakes\n```\n\n## Quick Commands\n\n```bash\nknowns task list --plain        # List tasks\nknowns task <id> --plain        # View task\nknowns doc list --plain         # List docs\nknowns doc "<path>" --plain     # View doc\nknowns search "query" --plain   # Search\n```\n\n**Important:** Always read the guidelines before working on tasks.\n';
 
@@ -43598,13 +43706,17 @@ var INSTRUCTION_FILES = [
   { path: "CLAUDE.md", name: "Claude Code", selected: true },
   { path: "AGENTS.md", name: "Agent SDK", selected: true },
   { path: "GEMINI.md", name: "Gemini", selected: false },
-  { path: ".github/copilot-instructions.md", name: "GitHub Copilot", selected: false }
+  {
+    path: ".github/copilot-instructions.md",
+    name: "GitHub Copilot",
+    selected: false
+  }
 ];
 function getGuidelines(type, variant = "general") {
   if (variant === "instruction") {
     return type === "mcp" ? MCP_INSTRUCTION : CLI_INSTRUCTION;
   }
-  return Guidelines.getFull(true);
+  return type === "mcp" ? MCPGuidelines.getFull(true) : Guidelines.getFull(true);
 }
 async function updateInstructionFile(filePath, guidelines) {
   const fullPath = join3(PROJECT_ROOT, filePath);
@@ -43635,111 +43747,113 @@ ${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.)").enablePositionalOptions().passThroughOptions().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) => {
-  try {
-    if (options2.updateInstructions) {
-      const type = options2.type === "mcp" ? "mcp" : "cli";
-      const variant = "general";
-      const guidelines2 = getGuidelines(type, variant);
-      let filesToUpdate = INSTRUCTION_FILES;
-      if (options2.files) {
-        const requestedFiles = options2.files.split(",").map((f) => f.trim());
-        filesToUpdate = INSTRUCTION_FILES.filter(
-          (f) => requestedFiles.includes(f.path) || requestedFiles.includes(f.name)
-        );
-      }
-      const label2 = `${type.toUpperCase()}`;
-      console.log(source_default.bold(`
+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("--files <files>", "Comma-separated list of files to update").action(
+  async (options2) => {
+    try {
+      if (options2.updateInstructions) {
+        const type = options2.type === "mcp" ? "mcp" : "cli";
+        const variant = "general";
+        const guidelines2 = getGuidelines(type, variant);
+        let filesToUpdate = INSTRUCTION_FILES;
+        if (options2.files) {
+          const requestedFiles = options2.files.split(",").map((f) => f.trim());
+          filesToUpdate = INSTRUCTION_FILES.filter(
+            (f) => requestedFiles.includes(f.path) || requestedFiles.includes(f.name)
+          );
+        }
+        const label2 = `${type.toUpperCase()}`;
+        console.log(source_default.bold(`
 Updating agent instruction files (${label2})...
 `));
-      await updateFiles(filesToUpdate, guidelines2);
-      return;
-    }
-    console.log(source_default.bold("\n\u{1F916} Agent Instructions Manager\n"));
-    const typeResponse = await (0, import_prompts.default)({
-      type: "select",
-      name: "type",
-      message: "Select guidelines type:",
-      choices: [
-        {
-          title: "CLI",
-          value: "cli",
-          description: "CLI commands (knowns task edit, knowns doc view, etc.)"
-        },
-        {
-          title: "MCP",
-          value: "mcp",
-          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: "Full (Recommended)",
-          value: "general",
-          description: "Complete guidelines embedded in file"
-        },
-        {
-          title: "Minimal",
-          value: "instruction",
-          description: "Just tells AI to call `knowns agents guideline` for rules"
-        }
-      ],
-      initial: 0
-    });
-    if (!variantResponse.variant) {
-      console.log(source_default.yellow("\n\u26A0\uFE0F  Cancelled"));
-      return;
-    }
-    const filesResponse = await (0, import_prompts.default)({
-      type: "multiselect",
-      name: "files",
-      message: "Select agent files to update:",
-      choices: INSTRUCTION_FILES.map((f) => ({
-        title: `${f.name} (${f.path})`,
-        value: f,
-        selected: f.selected
-      })),
-      hint: "- Space to select. Return to submit"
-    });
-    if (!filesResponse.files || filesResponse.files.length === 0) {
-      console.log(source_default.yellow("\n\u26A0\uFE0F  No files selected"));
-      return;
-    }
-    const variantLabel = variantResponse.variant === "instruction" ? " (minimal)" : " (full)";
-    const label = `${typeResponse.type.toUpperCase()}${variantLabel}`;
-    const confirmResponse = await (0, import_prompts.default)({
-      type: "confirm",
-      name: "confirm",
-      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(
-      typeResponse.type,
-      variantResponse.variant
-    );
-    console.log(source_default.bold(`
+        await updateFiles(filesToUpdate, guidelines2);
+        return;
+      }
+      console.log(source_default.bold("\n\u{1F916} Agent Instructions Manager\n"));
+      const typeResponse = await (0, import_prompts.default)({
+        type: "select",
+        name: "type",
+        message: "Select guidelines type:",
+        choices: [
+          {
+            title: "CLI",
+            value: "cli",
+            description: "CLI commands (knowns task edit, knowns doc view, etc.)"
+          },
+          {
+            title: "MCP",
+            value: "mcp",
+            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: "Full (Recommended)",
+            value: "general",
+            description: "Complete guidelines embedded in file"
+          },
+          {
+            title: "Minimal",
+            value: "instruction",
+            description: "Just tells AI to call `knowns agents guideline` for rules"
+          }
+        ],
+        initial: 0
+      });
+      if (!variantResponse.variant) {
+        console.log(source_default.yellow("\n\u26A0\uFE0F  Cancelled"));
+        return;
+      }
+      const filesResponse = await (0, import_prompts.default)({
+        type: "multiselect",
+        name: "files",
+        message: "Select agent files to update:",
+        choices: INSTRUCTION_FILES.map((f) => ({
+          title: `${f.name} (${f.path})`,
+          value: f,
+          selected: f.selected
+        })),
+        hint: "- Space to select. Return to submit"
+      });
+      if (!filesResponse.files || filesResponse.files.length === 0) {
+        console.log(source_default.yellow("\n\u26A0\uFE0F  No files selected"));
+        return;
+      }
+      const variantLabel = variantResponse.variant === "instruction" ? " (minimal)" : " (full)";
+      const label = `${typeResponse.type.toUpperCase()}${variantLabel}`;
+      const confirmResponse = await (0, import_prompts.default)({
+        type: "confirm",
+        name: "confirm",
+        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(
+        typeResponse.type,
+        variantResponse.variant
+      );
+      console.log(source_default.bold(`
 Updating files with ${label} guidelines...
 `));
-    await updateFiles(filesResponse.files, guidelines);
-  } catch (error48) {
-    console.error(source_default.red("Error:"), error48 instanceof Error ? error48.message : String(error48));
-    process.exit(1);
+      await updateFiles(filesResponse.files, guidelines);
+    } catch (error48) {
+      console.error(source_default.red("Error:"), error48 instanceof Error ? error48.message : String(error48));
+      process.exit(1);
+    }
   }
-});
+);
 async function updateFiles(files, guidelines) {
   let createdCount = 0;
   let appendedCount = 0;
@@ -43890,18 +44004,26 @@ async function createMcpJsonFile(projectRoot) {
     console.log(source_default.green("\u2713 Created .mcp.json for Claude Code MCP auto-discovery"));
   }
 }
-async function updateGitignoreForIgnoredMode(projectRoot) {
+async function updateGitignore(projectRoot, mode) {
   const { appendFileSync, readFileSync: readFileSync4, writeFileSync: writeFileSync3 } = await import("node:fs");
   const gitignorePath = join4(projectRoot, ".gitignore");
-  const knownsIgnorePattern = `
+  const patterns = {
+    "git-ignored": `
 # knowns (ignore all except docs)
 .knowns/*
 !.knowns/docs/
 !.knowns/docs/**
-`;
+`,
+    none: `
+# knowns (ignore entire folder)
+.knowns/
+`
+  };
+  const knownsIgnorePattern = patterns[mode];
+  const checkPattern = mode === "none" ? ".knowns/" : ".knowns/*";
   if (existsSync2(gitignorePath)) {
     const content = readFileSync4(gitignorePath, "utf-8");
-    if (content.includes(".knowns/*")) {
+    if (content.includes(checkPattern)) {
       console.log(source_default.gray("  .gitignore already has knowns pattern"));
       return;
     }
@@ -43943,6 +44065,11 @@ async function runWizard() {
             title: "Git Ignored (personal use)",
             value: "git-ignored",
             description: "Only docs tracked, tasks/config ignored"
+          },
+          {
+            title: "None (ignore all)",
+            value: "none",
+            description: "Entire .knowns/ folder ignored by git"
           }
         ],
         initial: 0
@@ -43953,8 +44080,16 @@ async function runWizard() {
         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.)" }
+          {
+            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.)"
+          }
         ],
         initial: 0
         // CLI
@@ -44026,8 +44161,8 @@ var initCommand = new Command("init").description("Initialize .knowns/ folder in
         agentFiles: INSTRUCTION_FILES.filter((f) => f.selected)
       };
     }
-    if (config2.gitTrackingMode === "git-ignored") {
-      await updateGitignoreForIgnoredMode(projectRoot);
+    if (config2.gitTrackingMode === "git-ignored" || config2.gitTrackingMode === "none") {
+      await updateGitignore(projectRoot, config2.gitTrackingMode);
     }
     if (config2.guidelinesType === "mcp") {
       await createMcpJsonFile(projectRoot);
@@ -47743,6 +47878,159 @@ var browserCommand = new Command("browser").description("Open web UI for task ma
 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";
+
+// src/utils/markdown-toc.ts
+function extractToc(markdown) {
+  const lines = markdown.split("\n");
+  const toc = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line.match(/^(#{1,6})\s+(.+)$/);
+    if (match) {
+      const level = match[1].length;
+      const title = match[2].trim();
+      const slug = slugify(title);
+      toc.push({ level, title, slug, line: i + 1 });
+    }
+  }
+  return toc;
+}
+function formatToc(toc, options2) {
+  const { indent = true, showLine = false } = options2 || {};
+  return toc.map((entry) => {
+    const indentation = indent ? "  ".repeat(entry.level - 1) : "";
+    const prefix = indent ? "- " : `${"#".repeat(entry.level)} `;
+    const lineInfo = showLine ? ` (line ${entry.line})` : "";
+    return `${indentation}${prefix}${entry.title}${lineInfo}`;
+  }).join("\n");
+}
+function extractSection(markdown, sectionTitle) {
+  const lines = markdown.split("\n");
+  const normalizedTarget = normalizeTitle(sectionTitle);
+  let startLine = -1;
+  let startLevel = 0;
+  let endLine = lines.length;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line.match(/^(#{1,6})\s+(.+)$/);
+    if (match) {
+      const level = match[1].length;
+      const title = match[2].trim();
+      if (startLine === -1) {
+        if (normalizeTitle(title) === normalizedTarget || matchesPartial(title, sectionTitle)) {
+          startLine = i;
+          startLevel = level;
+        }
+      } else {
+        if (level <= startLevel) {
+          endLine = i;
+          break;
+        }
+      }
+    }
+  }
+  if (startLine === -1) {
+    return null;
+  }
+  return lines.slice(startLine, endLine).join("\n").trim();
+}
+function replaceSection(markdown, sectionTitle, newContent) {
+  const lines = markdown.split("\n");
+  const normalizedTarget = normalizeTitle(sectionTitle);
+  let startLine = -1;
+  let startLevel = 0;
+  let endLine = lines.length;
+  let originalHeading = "";
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const match = line.match(/^(#{1,6})\s+(.+)$/);
+    if (match) {
+      const level = match[1].length;
+      const title = match[2].trim();
+      if (startLine === -1) {
+        if (normalizeTitle(title) === normalizedTarget || matchesPartial(title, sectionTitle)) {
+          startLine = i;
+          startLevel = level;
+          originalHeading = line;
+        }
+      } else {
+        if (level <= startLevel) {
+          endLine = i;
+          break;
+        }
+      }
+    }
+  }
+  if (startLine === -1) {
+    return null;
+  }
+  const beforeSection = lines.slice(0, startLine);
+  const afterSection = lines.slice(endLine);
+  const newSection = `${originalHeading}
+
+${newContent.trim()}`;
+  return [...beforeSection, newSection, ...afterSection].join("\n");
+}
+function slugify(title) {
+  return title.toLowerCase().replace(/[^\w\s-]/g, "").replace(/\s+/g, "-").replace(/-+/g, "-").trim();
+}
+function normalizeTitle(title) {
+  return title.toLowerCase().replace(/[^\w\s]/g, "").replace(/\s+/g, " ").trim();
+}
+function calculateDocStats(markdown) {
+  const chars = markdown.length;
+  const words = markdown.split(/\s+/).filter((w) => w.length > 0).length;
+  const lines = markdown.split("\n").length;
+  const toc = extractToc(markdown);
+  const headingCount = toc.length;
+  const estimatedTokens = Math.ceil(chars / 3.5);
+  return {
+    chars,
+    words,
+    lines,
+    estimatedTokens,
+    headingCount
+  };
+}
+function formatDocStats(stats, title) {
+  const lines = [
+    `Document: ${title}`,
+    "=".repeat(50),
+    "",
+    `Size: ${stats.chars.toLocaleString()} chars (~${stats.estimatedTokens.toLocaleString()} tokens)`,
+    `Words: ${stats.words.toLocaleString()}`,
+    `Lines: ${stats.lines.toLocaleString()}`,
+    `Headings: ${stats.headingCount}`,
+    ""
+  ];
+  if (stats.estimatedTokens > 4e3) {
+    lines.push("Recommendation: Document is large. Use --toc first, then --section.");
+  } else if (stats.estimatedTokens > 2e3) {
+    lines.push("Recommendation: Consider using --toc and --section for specific info.");
+  } else {
+    lines.push("Recommendation: Document is small enough to read directly.");
+  }
+  return lines.join("\n");
+}
+function matchesPartial(title, search) {
+  const normalizedTitle = normalizeTitle(title);
+  const normalizedSearch = normalizeTitle(search);
+  if (normalizedTitle === normalizedSearch) return true;
+  if (normalizedTitle.startsWith(normalizedSearch)) return true;
+  const numMatch = search.match(/^(\d+)\.?\s*(.*)$/);
+  if (numMatch) {
+    const [, num, rest] = numMatch;
+    const titleNumMatch = title.match(/^(\d+)\.?\s*(.*)$/);
+    if (titleNumMatch && titleNumMatch[1] === num) {
+      if (!rest || normalizeTitle(titleNumMatch[2]).startsWith(normalizeTitle(rest))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+// src/commands/doc.ts
 var import_gray_matter6 = __toESM(require_gray_matter(), 1);
 var DOCS_DIR = join17(process.cwd(), ".knowns", "docs");
 async function getAllMdFiles(dir, basePath = "") {
@@ -47794,51 +48082,56 @@ async function resolveDocPath(name) {
   }
   return { filepath, filename };
 }
-var createCommand3 = new Command("create").description("Create a new documentation file").argument("<title>", "Document title").option("-d, --description <text>", "Document description").option("-t, --tags <tags>", "Comma-separated tags").option("-f, --folder <path>", "Folder path (e.g., guides, patterns/auth)").option("--plain", "Plain text output for AI").action(async (title, options2) => {
-  try {
-    await ensureDocsDir();
-    const filename = `${titleToFilename(title)}.md`;
-    let targetDir = DOCS_DIR;
-    let relativePath = filename;
-    if (options2.folder) {
-      const folderPath = options2.folder.replace(/^\/|\/$/g, "");
-      targetDir = join17(DOCS_DIR, folderPath);
-      relativePath = join17(folderPath, filename);
-      if (!existsSync14(targetDir)) {
-        await mkdir7(targetDir, { recursive: true });
-      }
-    }
-    const filepath = join17(targetDir, filename);
-    if (existsSync14(filepath)) {
-      console.error(source_default.red(`\u2717 Document already exists: ${relativePath}`));
+var createCommand3 = new Command("create").description("Create a new documentation file").argument("<title>", "Document title").option("-d, --description <text>", "Document description").option("-t, --tags <tags>", "Comma-separated tags").option("-f, --folder <path>", "Folder path (e.g., guides, patterns/auth)").option("--plain", "Plain text output for AI").action(
+  async (title, options2) => {
+    try {
+      await ensureDocsDir();
+      const filename = `${titleToFilename(title)}.md`;
+      let targetDir = DOCS_DIR;
+      let relativePath = filename;
+      if (options2.folder) {
+        const folderPath = options2.folder.replace(/^\/|\/$/g, "");
+        targetDir = join17(DOCS_DIR, folderPath);
+        relativePath = join17(folderPath, filename);
+        if (!existsSync14(targetDir)) {
+          await mkdir7(targetDir, { recursive: true });
+        }
+      }
+      const filepath = join17(targetDir, filename);
+      if (existsSync14(filepath)) {
+        console.error(source_default.red(`\u2717 Document already exists: ${relativePath}`));
+        process.exit(1);
+      }
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const metadata = {
+        title,
+        createdAt: now,
+        updatedAt: now
+      };
+      if (options2.description) {
+        metadata.description = normalizeRefs(options2.description);
+      }
+      if (options2.tags) {
+        metadata.tags = options2.tags.split(",").map((t) => t.trim());
+      }
+      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}`);
+      } else {
+        console.log(source_default.green(`\u2713 Created documentation: ${source_default.bold(relativePath)}`));
+        console.log(source_default.gray(`  Location: ${filepath}`));
+      }
+    } catch (error48) {
+      console.error(
+        source_default.red("Error creating documentation:"),
+        error48 instanceof Error ? error48.message : String(error48)
+      );
       process.exit(1);
     }
-    const now = (/* @__PURE__ */ new Date()).toISOString();
-    const metadata = {
-      title,
-      createdAt: now,
-      updatedAt: now
-    };
-    if (options2.description) {
-      metadata.description = normalizeRefs(options2.description);
-    }
-    if (options2.tags) {
-      metadata.tags = options2.tags.split(",").map((t) => t.trim());
-    }
-    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}`);
-    } else {
-      console.log(source_default.green(`\u2713 Created documentation: ${source_default.bold(relativePath)}`));
-      console.log(source_default.gray(`  Location: ${filepath}`));
-    }
-  } catch (error48) {
-    console.error(source_default.red("Error creating documentation:"), error48 instanceof Error ? error48.message : String(error48));
-    process.exit(1);
   }
-});
+);
 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();
@@ -47961,115 +48254,197 @@ Documentation (${filteredDocs.length})
     process.exit(1);
   }
 });
-var viewCommand2 = new Command("view").description("View a documentation file").argument("<name>", "Document name (filename or title or path)").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 (!existsSync14(filepath)) {
-      filename = `${titleToFilename(name)}.md`;
-      filepath = join17(DOCS_DIR, filename);
-    }
-    if (!existsSync14(filepath)) {
-      const allFiles = await getAllMdFiles(DOCS_DIR);
-      const searchName = name.toLowerCase().replace(/\.md$/, "");
-      const matchingFile = allFiles.find((file3) => {
-        const fileNameOnly = file3.toLowerCase().replace(/\.md$/, "");
-        const fileBaseName = file3.split("/").pop()?.toLowerCase().replace(/\.md$/, "");
-        return fileNameOnly === searchName || fileBaseName === searchName || file3 === name;
-      });
-      if (matchingFile) {
-        filename = matchingFile;
-        filepath = join17(DOCS_DIR, matchingFile);
+var viewCommand2 = new Command("view").description("View a documentation file").argument("<name>", "Document name (filename or title or path)").option("--plain", "Plain text output for AI").option("--info", "Show document stats (size, tokens, headings) without content").option("--toc", "Show table of contents only").option("--section <title>", "Show specific section by heading title or number (e.g., '2. Overview' or '2')").action(
+  async (name, options2) => {
+    try {
+      await ensureDocsDir();
+      let filename = name.endsWith(".md") ? name : `${name}.md`;
+      let filepath = join17(DOCS_DIR, filename);
+      if (!existsSync14(filepath)) {
+        filename = `${titleToFilename(name)}.md`;
+        filepath = join17(DOCS_DIR, filename);
       }
-    }
-    if (!existsSync14(filepath)) {
-      console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
-      process.exit(1);
-    }
-    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);
-      const titleBorder = "=".repeat(50);
-      const projectRoot = process.cwd();
-      console.log(`File: ${projectRoot}/.knowns/docs/${filename}`);
-      console.log();
-      console.log(metadata.title);
-      console.log(titleBorder);
-      console.log();
-      console.log(`Created: ${metadata.createdAt}`);
-      console.log(`Updated: ${metadata.updatedAt}`);
-      if (metadata.tags && metadata.tags.length > 0) {
-        console.log(`Tags: ${metadata.tags.join(", ")}`);
+      if (!existsSync14(filepath)) {
+        const allFiles = await getAllMdFiles(DOCS_DIR);
+        const searchName = name.toLowerCase().replace(/\.md$/, "");
+        const matchingFile = allFiles.find((file3) => {
+          const fileNameOnly = file3.toLowerCase().replace(/\.md$/, "");
+          const fileBaseName = file3.split("/").pop()?.toLowerCase().replace(/\.md$/, "");
+          return fileNameOnly === searchName || fileBaseName === searchName || file3 === name;
+        });
+        if (matchingFile) {
+          filename = matchingFile;
+          filepath = join17(DOCS_DIR, matchingFile);
+        }
       }
-      if (metadata.description) {
-        console.log();
-        console.log("Description:");
-        console.log(border);
-        console.log(metadata.description);
+      if (!existsSync14(filepath)) {
+        console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
+        process.exit(1);
       }
-      console.log();
-      console.log("Content:");
-      console.log(border);
-      const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
-      let enhancedContent = content.trimEnd();
-      const linksToAdd = [];
-      let match;
-      while ((match = linkPattern.exec(content)) !== null) {
-        const _linkText = match[1];
-        const linkTarget = match[2];
-        const fullMatch = match[0];
-        if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
-          continue;
+      const fileContent = await readFile11(filepath, "utf-8");
+      const { data, content } = (0, import_gray_matter6.default)(fileContent);
+      const metadata = data;
+      if (options2.info) {
+        const stats = calculateDocStats(content);
+        if (options2.plain) {
+          console.log(formatDocStats(stats, metadata.title));
+        } else {
+          console.log(source_default.bold(`
+\u{1F4CA} ${metadata.title} - Document Info
+`));
+          console.log(
+            `Size: ${source_default.cyan(stats.chars.toLocaleString())} chars (~${source_default.yellow(stats.estimatedTokens.toLocaleString())} tokens)`
+          );
+          console.log(`Words: ${stats.words.toLocaleString()}`);
+          console.log(`Lines: ${stats.lines.toLocaleString()}`);
+          console.log(`Headings: ${stats.headingCount}`);
+          console.log();
+          if (stats.estimatedTokens > 4e3) {
+            console.log(source_default.yellow("\u26A0 Document is large. Use --toc first, then --section."));
+          } else if (stats.estimatedTokens > 2e3) {
+            console.log(source_default.gray("Consider using --toc and --section for specific info."));
+          } else {
+            console.log(source_default.green("\u2713 Document is small enough to read directly."));
+          }
+          console.log();
         }
-        if (linkTarget.startsWith("../")) {
-          continue;
+        return;
+      }
+      if (options2.toc) {
+        const toc = extractToc(content);
+        if (toc.length === 0) {
+          console.log(options2.plain ? "No headings found." : source_default.yellow("No headings found in this document."));
+          return;
         }
-        let resolvedFilename = linkTarget.replace(/^\.\//, "");
-        if (!resolvedFilename.endsWith(".md")) {
-          resolvedFilename = `${resolvedFilename}.md`;
+        if (options2.plain) {
+          console.log(`Table of Contents: ${metadata.title}`);
+          console.log("=".repeat(50));
+          console.log();
+          toc.forEach((entry, index) => {
+            const indent = "  ".repeat(entry.level - 1);
+            console.log(`${indent}${index + 1}. ${entry.title}`);
+          });
+          console.log();
+          console.log("Use --section <number or title> to view a specific section.");
+        } else {
+          console.log(source_default.bold(`
+\u{1F4C4} ${metadata.title} - Table of Contents
+`));
+          console.log(formatToc(toc));
+          console.log(source_default.gray("\nUse --section <number or title> to view a specific section."));
         }
-        const resolvedPath = `@.knowns/docs/${resolvedFilename}`;
-        linksToAdd.push({
-          original: fullMatch,
-          resolved: resolvedPath
-        });
-      }
-      for (const { original, resolved } of linksToAdd) {
-        enhancedContent = enhancedContent.replace(original, resolved);
+        return;
       }
-      const knownProjectRoot = findProjectRoot();
-      if (knownProjectRoot) {
-        const fileStore2 = new FileStore(knownProjectRoot);
-        const allTasks = await fileStore2.getAllTasks();
-        const taskMap = buildTaskMap(allTasks);
-        enhancedContent = transformMentionsToRefs(enhancedContent, taskMap);
+      if (options2.section) {
+        const sectionContent = extractSection(content, options2.section);
+        if (!sectionContent) {
+          console.error(
+            options2.plain ? `Section not found: ${options2.section}` : source_default.red(`\u2717 Section not found: ${options2.section}`)
+          );
+          console.log(
+            options2.plain ? "Use --toc to see available sections." : source_default.gray("Use --toc to see available sections.")
+          );
+          process.exit(1);
+        }
+        if (options2.plain) {
+          console.log(`File: ${process.cwd()}/.knowns/docs/${filename}`);
+          console.log(`Section: ${options2.section}`);
+          console.log("=".repeat(50));
+          console.log();
+          console.log(sectionContent);
+        } else {
+          console.log(source_default.bold(`
+\u{1F4C4} ${metadata.title} - Section
+`));
+          console.log(sectionContent);
+          console.log();
+        }
+        return;
       }
-      console.log(enhancedContent);
-    } else {
-      console.log(source_default.bold(`
+      if (options2.plain) {
+        const border = "-".repeat(50);
+        const titleBorder = "=".repeat(50);
+        const projectRoot = process.cwd();
+        console.log(`File: ${projectRoot}/.knowns/docs/${filename}`);
+        console.log();
+        console.log(metadata.title);
+        console.log(titleBorder);
+        console.log();
+        console.log(`Created: ${metadata.createdAt}`);
+        console.log(`Updated: ${metadata.updatedAt}`);
+        if (metadata.tags && metadata.tags.length > 0) {
+          console.log(`Tags: ${metadata.tags.join(", ")}`);
+        }
+        if (metadata.description) {
+          console.log();
+          console.log("Description:");
+          console.log(border);
+          console.log(metadata.description);
+        }
+        console.log();
+        console.log("Content:");
+        console.log(border);
+        const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+        let enhancedContent = content.trimEnd();
+        const linksToAdd = [];
+        let match;
+        while ((match = linkPattern.exec(content)) !== null) {
+          const _linkText = match[1];
+          const linkTarget = match[2];
+          const fullMatch = match[0];
+          if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
+            continue;
+          }
+          if (linkTarget.startsWith("../")) {
+            continue;
+          }
+          let resolvedFilename = linkTarget.replace(/^\.\//, "");
+          if (!resolvedFilename.endsWith(".md")) {
+            resolvedFilename = `${resolvedFilename}.md`;
+          }
+          const resolvedPath = `@.knowns/docs/${resolvedFilename}`;
+          linksToAdd.push({
+            original: fullMatch,
+            resolved: resolvedPath
+          });
+        }
+        for (const { original, resolved } of linksToAdd) {
+          enhancedContent = enhancedContent.replace(original, resolved);
+        }
+        const knownProjectRoot = findProjectRoot();
+        if (knownProjectRoot) {
+          const fileStore2 = new FileStore(knownProjectRoot);
+          const allTasks = await fileStore2.getAllTasks();
+          const taskMap = buildTaskMap(allTasks);
+          enhancedContent = transformMentionsToRefs(enhancedContent, taskMap);
+        }
+        console.log(enhancedContent);
+      } else {
+        console.log(source_default.bold(`
 \u{1F4C4} ${metadata.title}
 `));
-      if (metadata.description) {
-        console.log(source_default.gray(metadata.description));
+        if (metadata.description) {
+          console.log(source_default.gray(metadata.description));
+          console.log();
+        }
+        if (metadata.tags && metadata.tags.length > 0) {
+          console.log(source_default.gray(`Tags: ${metadata.tags.join(", ")}`));
+        }
+        console.log(source_default.gray(`Updated: ${new Date(metadata.updatedAt).toLocaleString()}`));
+        console.log(source_default.gray("-".repeat(60)));
+        console.log(content);
         console.log();
       }
-      if (metadata.tags && metadata.tags.length > 0) {
-        console.log(source_default.gray(`Tags: ${metadata.tags.join(", ")}`));
-      }
-      console.log(source_default.gray(`Updated: ${new Date(metadata.updatedAt).toLocaleString()}`));
-      console.log(source_default.gray("-".repeat(60)));
-      console.log(content);
-      console.log();
+    } catch (error48) {
+      console.error(
+        source_default.red("Error viewing documentation:"),
+        error48 instanceof Error ? error48.message : String(error48)
+      );
+      process.exit(1);
     }
-  } catch (error48) {
-    console.error(source_default.red("Error viewing documentation:"), error48 instanceof Error ? error48.message : String(error48));
-    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("--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(
+);
+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 (or section content if --section used)").option("-a, --append <text>", "Append to content").option("--section <title>", "Target section to replace (use with -c)").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();
@@ -48124,6 +48499,18 @@ var editCommand2 = new Command("edit").description("Edit a documentation file (m
 
 ${normalizeRefs(fileData)}`;
         sourceFile = options2.appendFile;
+      } else if (options2.section && options2.content) {
+        const result = replaceSection(content, options2.section, normalizeRefs(options2.content));
+        if (!result) {
+          console.error(
+            options2.plain ? `Section not found: ${options2.section}` : source_default.red(`\u2717 Section not found: ${options2.section}`)
+          );
+          console.log(
+            options2.plain ? "Use 'knowns doc <path> --toc --plain' to see available sections." : source_default.gray("Use 'knowns doc <path> --toc --plain' to see available sections.")
+          );
+          process.exit(1);
+        }
+        updatedContent = result;
       } else if (options2.content) {
         updatedContent = normalizeRefs(options2.content);
       } else if (options2.append) {
@@ -48136,11 +48523,17 @@ ${normalizeRefs(options2.append)}`;
       await notifyDocUpdate(filename);
       if (options2.plain) {
         console.log(`Updated: ${filename}`);
+        if (options2.section) {
+          console.log(`Section: ${options2.section}`);
+        }
         if (sourceFile) {
           console.log(`Content from: ${sourceFile}`);
         }
       } else {
         console.log(source_default.green(`\u2713 Updated documentation: ${source_default.bold(filename)}`));
+        if (options2.section) {
+          console.log(source_default.gray(`  Section: ${options2.section}`));
+        }
         if (sourceFile) {
           console.log(source_default.gray(`  Content from: ${sourceFile}`));
         }
@@ -48432,100 +48825,182 @@ ${afterSection.trimStart()}`;
     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().action(async (name, options2) => {
-  if (!name) {
-    docCommand.help();
-    return;
-  }
-  try {
-    const resolved = await resolveDocPath(name);
-    if (!resolved) {
-      console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
-      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").option("--info", "Show document stats (size, tokens, headings) without content").option("--toc", "Show table of contents only").option("--section <title>", "Show specific section by heading title or number").enablePositionalOptions().action(
+  async (name, options2) => {
+    if (!name) {
+      docCommand.help();
+      return;
     }
-    const { filepath, filename } = resolved;
-    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);
-      const titleBorder = "=".repeat(50);
-      const projectRoot = process.cwd();
-      console.log(`File: ${projectRoot}/.knowns/docs/${filename}`);
-      console.log();
-      console.log(metadata.title);
-      console.log(titleBorder);
-      console.log();
-      console.log(`Created: ${metadata.createdAt}`);
-      console.log(`Updated: ${metadata.updatedAt}`);
-      if (metadata.tags && metadata.tags.length > 0) {
-        console.log(`Tags: ${metadata.tags.join(", ")}`);
-      }
-      if (metadata.description) {
-        console.log();
-        console.log("Description:");
-        console.log(border);
-        console.log(metadata.description);
+    try {
+      const resolved = await resolveDocPath(name);
+      if (!resolved) {
+        console.error(source_default.red(`\u2717 Documentation not found: ${name}`));
+        process.exit(1);
       }
-      console.log();
-      console.log("Content:");
-      console.log(border);
-      const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
-      let enhancedContent = content.trimEnd();
-      const linksToAdd = [];
-      let match;
-      while ((match = linkPattern.exec(content)) !== null) {
-        const _linkText = match[1];
-        const linkTarget = match[2];
-        const fullMatch = match[0];
-        if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
-          continue;
+      const { filepath, filename } = resolved;
+      const fileContent = await readFile11(filepath, "utf-8");
+      const { data, content } = (0, import_gray_matter6.default)(fileContent);
+      const metadata = data;
+      if (options2.info) {
+        const stats = calculateDocStats(content);
+        if (options2.plain) {
+          console.log(formatDocStats(stats, metadata.title));
+        } else {
+          console.log(source_default.bold(`
+\u{1F4CA} ${metadata.title} - Document Info
+`));
+          console.log(
+            `Size: ${source_default.cyan(stats.chars.toLocaleString())} chars (~${source_default.yellow(stats.estimatedTokens.toLocaleString())} tokens)`
+          );
+          console.log(`Words: ${stats.words.toLocaleString()}`);
+          console.log(`Lines: ${stats.lines.toLocaleString()}`);
+          console.log(`Headings: ${stats.headingCount}`);
+          console.log();
+          if (stats.estimatedTokens > 4e3) {
+            console.log(source_default.yellow("\u26A0 Document is large. Use --toc first, then --section."));
+          } else if (stats.estimatedTokens > 2e3) {
+            console.log(source_default.gray("Consider using --toc and --section for specific info."));
+          } else {
+            console.log(source_default.green("\u2713 Document is small enough to read directly."));
+          }
+          console.log();
         }
-        if (linkTarget.startsWith("../")) {
-          continue;
+        return;
+      }
+      if (options2.toc) {
+        const toc = extractToc(content);
+        if (toc.length === 0) {
+          console.log(options2.plain ? "No headings found." : source_default.yellow("No headings found in this document."));
+          return;
         }
-        let resolvedFilename = linkTarget.replace(/^\.\//, "");
-        if (!resolvedFilename.endsWith(".md")) {
-          resolvedFilename = `${resolvedFilename}.md`;
+        if (options2.plain) {
+          console.log(`Table of Contents: ${metadata.title}`);
+          console.log("=".repeat(50));
+          console.log();
+          toc.forEach((entry, index) => {
+            const indent = "  ".repeat(entry.level - 1);
+            console.log(`${indent}${index + 1}. ${entry.title}`);
+          });
+          console.log();
+          console.log("Use --section <number or title> to view a specific section.");
+        } else {
+          console.log(source_default.bold(`
+\u{1F4C4} ${metadata.title} - Table of Contents
+`));
+          console.log(formatToc(toc));
+          console.log(source_default.gray("\nUse --section <number or title> to view a specific section."));
         }
-        const resolvedPath = `@.knowns/docs/${resolvedFilename}`;
-        linksToAdd.push({
-          original: fullMatch,
-          resolved: resolvedPath
-        });
-      }
-      for (const { original, resolved: resolved2 } of linksToAdd) {
-        enhancedContent = enhancedContent.replace(original, resolved2);
+        return;
       }
-      const knownProjectRoot = findProjectRoot();
-      if (knownProjectRoot) {
-        const fileStore2 = new FileStore(knownProjectRoot);
-        const allTasks = await fileStore2.getAllTasks();
-        const taskMap = buildTaskMap(allTasks);
-        enhancedContent = transformMentionsToRefs(enhancedContent, taskMap);
+      if (options2.section) {
+        const sectionContent = extractSection(content, options2.section);
+        if (!sectionContent) {
+          console.error(
+            options2.plain ? `Section not found: ${options2.section}` : source_default.red(`\u2717 Section not found: ${options2.section}`)
+          );
+          console.log(
+            options2.plain ? "Use --toc to see available sections." : source_default.gray("Use --toc to see available sections.")
+          );
+          process.exit(1);
+        }
+        if (options2.plain) {
+          console.log(`File: ${process.cwd()}/.knowns/docs/${filename}`);
+          console.log(`Section: ${options2.section}`);
+          console.log("=".repeat(50));
+          console.log();
+          console.log(sectionContent);
+        } else {
+          console.log(source_default.bold(`
+\u{1F4C4} ${metadata.title} - Section
+`));
+          console.log(sectionContent);
+          console.log();
+        }
+        return;
       }
-      console.log(enhancedContent);
-    } else {
-      console.log(source_default.bold(`
+      if (options2.plain) {
+        const border = "-".repeat(50);
+        const titleBorder = "=".repeat(50);
+        const projectRoot = process.cwd();
+        console.log(`File: ${projectRoot}/.knowns/docs/${filename}`);
+        console.log();
+        console.log(metadata.title);
+        console.log(titleBorder);
+        console.log();
+        console.log(`Created: ${metadata.createdAt}`);
+        console.log(`Updated: ${metadata.updatedAt}`);
+        if (metadata.tags && metadata.tags.length > 0) {
+          console.log(`Tags: ${metadata.tags.join(", ")}`);
+        }
+        if (metadata.description) {
+          console.log();
+          console.log("Description:");
+          console.log(border);
+          console.log(metadata.description);
+        }
+        console.log();
+        console.log("Content:");
+        console.log(border);
+        const linkPattern = /\[([^\]]+)\]\(([^)]+)\)/g;
+        let enhancedContent = content.trimEnd();
+        const linksToAdd = [];
+        let match;
+        while ((match = linkPattern.exec(content)) !== null) {
+          const _linkText = match[1];
+          const linkTarget = match[2];
+          const fullMatch = match[0];
+          if (linkTarget.startsWith("http://") || linkTarget.startsWith("https://")) {
+            continue;
+          }
+          if (linkTarget.startsWith("../")) {
+            continue;
+          }
+          let resolvedFilename = linkTarget.replace(/^\.\//, "");
+          if (!resolvedFilename.endsWith(".md")) {
+            resolvedFilename = `${resolvedFilename}.md`;
+          }
+          const resolvedPath = `@.knowns/docs/${resolvedFilename}`;
+          linksToAdd.push({
+            original: fullMatch,
+            resolved: resolvedPath
+          });
+        }
+        for (const { original, resolved: resolved2 } of linksToAdd) {
+          enhancedContent = enhancedContent.replace(original, resolved2);
+        }
+        const knownProjectRoot = findProjectRoot();
+        if (knownProjectRoot) {
+          const fileStore2 = new FileStore(knownProjectRoot);
+          const allTasks = await fileStore2.getAllTasks();
+          const taskMap = buildTaskMap(allTasks);
+          enhancedContent = transformMentionsToRefs(enhancedContent, taskMap);
+        }
+        console.log(enhancedContent);
+      } else {
+        console.log(source_default.bold(`
 \u{1F4C4} ${metadata.title}
 `));
-      if (metadata.description) {
-        console.log(source_default.gray(metadata.description));
+        if (metadata.description) {
+          console.log(source_default.gray(metadata.description));
+          console.log();
+        }
+        if (metadata.tags && metadata.tags.length > 0) {
+          console.log(source_default.gray(`Tags: ${metadata.tags.join(", ")}`));
+        }
+        console.log(source_default.gray(`Updated: ${new Date(metadata.updatedAt).toLocaleString()}`));
+        console.log(source_default.gray("-".repeat(60)));
+        console.log(content);
         console.log();
       }
-      if (metadata.tags && metadata.tags.length > 0) {
-        console.log(source_default.gray(`Tags: ${metadata.tags.join(", ")}`));
-      }
-      console.log(source_default.gray(`Updated: ${new Date(metadata.updatedAt).toLocaleString()}`));
-      console.log(source_default.gray("-".repeat(60)));
-      console.log(content);
-      console.log();
+    } catch (error48) {
+      console.error(
+        source_default.red("Error viewing documentation:"),
+        error48 instanceof Error ? error48.message : String(error48)
+      );
+      process.exit(1);
     }
-  } catch (error48) {
-    console.error(source_default.red("Error viewing documentation:"), error48 instanceof Error ? error48.message : String(error48));
-    process.exit(1);
   }
-});
+);
 docCommand.addCommand(createCommand3);
 docCommand.addCommand(listCommand2);
 docCommand.addCommand(viewCommand2);
@@ -49194,7 +49669,7 @@ __export(util_exports, {
   required: () => required,
   safeExtend: () => safeExtend,
   shallowClone: () => shallowClone,
-  slugify: () => slugify,
+  slugify: () => slugify2,
   stringifyPrimitive: () => stringifyPrimitive,
   uint8ArrayToBase64: () => uint8ArrayToBase64,
   uint8ArrayToBase64url: () => uint8ArrayToBase64url,
@@ -49335,7 +49810,7 @@ function randomString(length = 10) {
 function esc(str2) {
   return JSON.stringify(str2);
 }
-function slugify(input) {
+function slugify2(input) {
   return input.toLowerCase().trim().replace(/[^\w\s-]/g, "").replace(/[\s_-]+/g, "-").replace(/^-+|-+$/g, "");
 }
 var captureStackTrace = "captureStackTrace" in Error ? Error.captureStackTrace : (..._args) => {
@@ -59069,7 +59544,7 @@ function _toUpperCase() {
 }
 // @__NO_SIDE_EFFECTS__
 function _slugify() {
-  return /* @__PURE__ */ _overwrite((input) => slugify(input));
+  return /* @__PURE__ */ _overwrite((input) => slugify2(input));
 }
 // @__NO_SIDE_EFFECTS__
 function _array(Class2, element, params) {
@@ -70196,8 +70671,14 @@ var listDocsSchema = external_exports.object({
   tag: external_exports.string().optional()
 });
 var getDocSchema = external_exports.object({
-  path: external_exports.string()
+  path: external_exports.string(),
   // Document path (filename or folder/filename)
+  info: external_exports.boolean().optional(),
+  // Return document stats (size, tokens, headings) without content
+  toc: external_exports.boolean().optional(),
+  // Return table of contents only
+  section: external_exports.string().optional()
+  // Return specific section by heading title or number
 });
 var createDocSchema = external_exports.object({
   title: external_exports.string(),
@@ -70214,8 +70695,10 @@ var updateDocSchema = external_exports.object({
   description: external_exports.string().optional(),
   content: external_exports.string().optional(),
   tags: external_exports.array(external_exports.string()).optional(),
-  appendContent: external_exports.string().optional()
+  appendContent: external_exports.string().optional(),
   // Append to existing content
+  section: external_exports.string().optional()
+  // Target section to replace (use with content)
 });
 var searchDocsSchema = external_exports.object({
   query: external_exports.string(),
@@ -70234,13 +70717,25 @@ var docTools = [
   },
   {
     name: "get_doc",
-    description: "Get a documentation file by path (filename or folder/filename)",
+    description: "Get a documentation file by path. Use 'info: true' first to check size, then 'toc: true' for table of contents, then 'section' to read specific parts.",
     inputSchema: {
       type: "object",
       properties: {
         path: {
           type: "string",
           description: "Document path (e.g., 'readme', 'guides/setup', 'conventions/naming.md')"
+        },
+        info: {
+          type: "boolean",
+          description: "Return document stats (size, tokens, headings) without content. Use this first to decide how to read."
+        },
+        toc: {
+          type: "boolean",
+          description: "Return table of contents only (list of headings). Use this first for large documents."
+        },
+        section: {
+          type: "string",
+          description: "Return specific section by heading title or number (e.g., '2. Overview' or '2'). Use after viewing TOC."
         }
       },
       required: ["path"]
@@ -70270,7 +70765,7 @@ var docTools = [
   },
   {
     name: "update_doc",
-    description: "Update an existing documentation file",
+    description: "Update an existing documentation file. Use 'section' with 'content' to replace only a specific section.",
     inputSchema: {
       type: "object",
       properties: {
@@ -70280,7 +70775,10 @@ var docTools = [
         },
         title: { type: "string", description: "New title" },
         description: { type: "string", description: "New description" },
-        content: { type: "string", description: "Replace content" },
+        content: {
+          type: "string",
+          description: "Replace content (or section content if 'section' is specified)"
+        },
         tags: {
           type: "array",
           items: { type: "string" },
@@ -70289,6 +70787,10 @@ var docTools = [
         appendContent: {
           type: "string",
           description: "Append to existing content"
+        },
+        section: {
+          type: "string",
+          description: "Target section to replace by heading title or number (use with 'content')"
         }
       },
       required: ["path"]
@@ -70401,6 +70903,70 @@ async function handleGetDoc(args2) {
   const fileContent = await readFile14(resolved.filepath, "utf-8");
   const { data, content } = (0, import_gray_matter8.default)(fileContent);
   const metadata = data;
+  if (input.info) {
+    const stats = calculateDocStats(content);
+    let recommendation;
+    if (stats.estimatedTokens > 4e3) {
+      recommendation = "Document is large. Use 'toc: true' first, then 'section' to read specific parts.";
+    } else if (stats.estimatedTokens > 2e3) {
+      recommendation = "Consider using 'toc: true' and 'section' for specific info.";
+    } else {
+      recommendation = "Document is small enough to read directly.";
+    }
+    return successResponse({
+      doc: {
+        path: resolved.filename.replace(/\.md$/, ""),
+        title: metadata.title,
+        stats: {
+          chars: stats.chars,
+          words: stats.words,
+          lines: stats.lines,
+          estimatedTokens: stats.estimatedTokens,
+          headingCount: stats.headingCount
+        },
+        recommendation
+      }
+    });
+  }
+  if (input.toc) {
+    const toc = extractToc(content);
+    if (toc.length === 0) {
+      return successResponse({
+        doc: {
+          path: resolved.filename.replace(/\.md$/, ""),
+          title: metadata.title,
+          toc: [],
+          message: "No headings found in this document."
+        }
+      });
+    }
+    return successResponse({
+      doc: {
+        path: resolved.filename.replace(/\.md$/, ""),
+        title: metadata.title,
+        toc: toc.map((entry, index) => ({
+          index: index + 1,
+          level: entry.level,
+          title: entry.title
+        })),
+        hint: "Use 'section' parameter with a heading title or number to read specific content."
+      }
+    });
+  }
+  if (input.section) {
+    const sectionContent = extractSection(content, input.section);
+    if (!sectionContent) {
+      return errorResponse(`Section not found: ${input.section}. Use 'toc: true' to see available sections.`);
+    }
+    return successResponse({
+      doc: {
+        path: resolved.filename.replace(/\.md$/, ""),
+        title: metadata.title,
+        section: input.section,
+        content: sectionContent
+      }
+    });
+  }
   return successResponse({
     doc: {
       path: resolved.filename.replace(/\.md$/, ""),
@@ -70471,11 +71037,21 @@ async function handleUpdateDoc(args2) {
   if (input.tags) metadata.tags = input.tags;
   metadata.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   let updatedContent = content;
-  if (input.content) {
+  let sectionUpdated;
+  if (input.section && input.content) {
+    const result = replaceSection(content, input.section, input.content);
+    if (!result) {
+      return errorResponse(
+        `Section not found: ${input.section}. Use 'toc: true' with get_doc to see available sections.`
+      );
+    }
+    updatedContent = result;
+    sectionUpdated = input.section;
+  } else if (input.content) {
     updatedContent = input.content;
   }
   if (input.appendContent) {
-    updatedContent = `${content.trimEnd()}
+    updatedContent = `${updatedContent.trimEnd()}
 
 ${input.appendContent}`;
   }
@@ -70483,13 +71059,14 @@ ${input.appendContent}`;
   await writeFile10(resolved.filepath, newFileContent, "utf-8");
   await notifyDocUpdate(resolved.filename);
   return successResponse({
-    message: `Updated documentation: ${resolved.filename}`,
+    message: sectionUpdated ? `Updated section "${sectionUpdated}" in ${resolved.filename}` : `Updated documentation: ${resolved.filename}`,
     doc: {
       path: resolved.filename.replace(/\.md$/, ""),
       title: metadata.title,
       description: metadata.description,
       tags: metadata.tags,
-      updatedAt: metadata.updatedAt
+      updatedAt: metadata.updatedAt,
+      ...sectionUpdated && { section: sectionUpdated }
     }
   });
 }
@@ -70558,7 +71135,18 @@ var guidelineTools = [
 ];
 async function handleGetGuideline(args2) {
   const input = getGuidelineSchema.parse(args2 || {});
-  const guidelines = Guidelines.getFull();
+  let guidelines;
+  switch (input.type) {
+    case "mcp":
+      guidelines = MCPGuidelines.getFull();
+      break;
+    case "cli":
+      guidelines = Guidelines.getFull();
+      break;
+    default:
+      guidelines = MCPGuidelines.getFull();
+      break;
+  }
   return {
     content: [
       {
@@ -71016,7 +71604,7 @@ async function notifyCliUpdate(options2) {
 // package.json
 var package_default = {
   name: "knowns",
-  version: "0.8.6",
+  version: "0.8.7",
   description: "AI-native task and documentation management for dev teams",
   module: "index.ts",
   type: "module",
@@ -71147,7 +71735,7 @@ var BANNER = `
 function showBanner() {
   console.log(source_default.cyan(BANNER));
   console.log(source_default.bold("  Knowns CLI") + source_default.gray(` v${package_default.version}`));
-  console.log(source_default.gray('  "Know what your team knows."'));
+  console.log(source_default.gray('  "What your AI should have knowns."'));
   console.log();
   console.log(source_default.gray("  Open-source CLI for dev teams"));
   console.log(source_default.gray("  Tasks \u2022 Time \u2022 Docs \u2022 Sync"));