knowns 0.8.1 → 0.8.3

package/README.md

@@ -121,8 +121,9 @@ knowns time start <id> && knowns time stop
 knowns search "query" --plain
 
 # AI Guidelines
-knowns agents sync                          # Sync CLAUDE.md, AGENTS.md
-knowns agents sync --gemini                 # Compact version for Gemini
+knowns agents guideline                     # Output guidelines to stdout
+knowns agents sync                          # Sync CLAUDE.md, AGENTS.md (minimal)
+knowns agents sync --full                   # Sync with full embedded guidelines
 knowns agents sync --type mcp               # MCP tools format
 ```
 

package/dist/index.js

@@ -43475,17 +43475,114 @@ 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/cli/gemini.md
-var gemini_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns CLI - Gemini Quick Reference\n\n## RULES\n- NEVER edit .md files directly - use CLI only\n- Use `--plain` flag for VIEW/LIST/SEARCH commands only (NOT for create/edit)\n- Read docs BEFORE coding\n- Start timer when taking task, stop when done\n\n## SESSION START\n```bash\nknowns doc list --plain\nknowns doc "README" --plain\nknowns task list --plain\n```\n\n## TASK WORKFLOW\n\n### 1. Take Task\n```bash\nknowns task <id> --plain              # View task\nknowns task edit <id> -s in-progress -a @me\nknowns time start <id>\n```\n\n### 2. Read Context\n```bash\nknowns doc list "guides/" --plain     # List by folder\nknowns doc "path/name" --plain        # View doc\nknowns search "keyword" --type doc --plain\n```\n\n### 3. Plan & Implement\n```bash\nknowns task edit <id> --plan $\'1. Step one\\n2. Step two\'\n# Wait for approval, then code\nknowns task edit <id> --check-ac 1    # Check criteria after done\nknowns task edit <id> --append-notes "Done: feature X"\n```\n\n### 4. Complete\n```bash\nknowns time stop\nknowns task edit <id> -s done\n```\n\n## COMMANDS CHEATSHEET\n\n### Task\n```bash\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task <id> --plain\nknowns task create "Title" -d "Desc" --ac "Criterion" --priority high\nknowns task edit <id> -s <status> -a @me\nknowns task edit <id> --check-ac 1 --check-ac 2\nknowns task edit <id> --plan "..."\nknowns task edit <id> --notes "..."\nknowns task edit <id> --append-notes "..."\n```\n\n### Doc\n```bash\nknowns doc list --plain\nknowns doc list "folder/" --plain\nknowns doc "name" --plain\nknowns doc create "Title" -d "Desc" -t "tags" -f "folder"\nknowns doc edit "name" -c "content"\nknowns doc edit "name" -a "append"\nknowns doc edit "name" --content-file ./file.md\nknowns doc edit "name" --append-file ./file.md\nknowns doc search-in "name" "query" --plain\nknowns doc replace "name" "old" "new"\n```\n\n**Doc Organization:**\n| Type | Location |\n|------|----------|\n| Core docs | Root `.knowns/docs/` (no -f flag) |\n| Categorized | `.knowns/docs/<folder>/` (use -f flag) |\n\n### Time\n```bash\nknowns time start <id>\nknowns time stop\nknowns time status\nknowns time add <id> 2h -n "Note"\n```\n\n### Search\n```bash\nknowns search "query" --plain\nknowns search "query" --type doc --plain\nknowns search "query" --type task --plain\n```\n\n## REFS\n\n### Reading (output format)\n- `@.knowns/tasks/task-X - Title.md` \u2192 `knowns task X --plain`\n- `@.knowns/docs/path/name.md` \u2192 `knowns doc "path/name" --plain`\n\n### Writing (input format)\n- Task: `@task-X`\n- Doc: `@doc/path/name`\n\n## STATUS & PRIORITY\n\n**Status:** `todo`, `in-progress`, `in-review`, `blocked`, `done`\n**Priority:** `low`, `medium`, `high`\n\n## --plain FLAG\n\n\u26A0\uFE0F **CRITICAL**: Only use `--plain` with VIEW/LIST/SEARCH commands!\n\n| \u2705 Supports --plain | \u274C NO --plain |\n|---------------------|---------------|\n| `task <id> --plain` | `task create` |\n| `task list --plain` | `task edit` |\n| `doc <path> --plain` | `doc create` |\n| `doc list --plain` | `doc edit` |\n| `search --plain` | `time start/stop/add` |\n\n## LONG CONTENT\n\nWindows has ~8191 char limit. Use:\n\n```bash\n# Append in chunks\nknowns doc edit "name" -a "Section 1..."\nknowns doc edit "name" -a "Section 2..."\n\n# Or file-based\nknowns doc edit "name" --content-file ./content.md\nknowns doc edit "name" --append-file ./more.md\n```\n\n## VALIDATE & REPAIR\n\n```bash\nknowns doc validate "name" --plain\nknowns doc repair "name" --plain\nknowns task validate <id> --plain\nknowns task repair <id> --plain\n```\n<!-- KNOWNS GUIDELINES END -->\n';
+// src/templates/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/commands-reference.md
+var commands_reference_default = '# CLI Commands Reference\n\nComplete reference for all Knowns CLI commands.\n\n---\n\n## Task Commands\n\n### task create\n\n```\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--description` | `-d` | Task description | `-d "Fix the login bug"` |\n| `--ac` | | Acceptance criterion (repeatable) | `--ac "User can login"` |\n| `--labels` | `-l` | Comma-separated labels | `-l "bug,urgent"` |\n| `--assignee` | `-a` | Assign to user | `-a @username` |\n| `--priority` | | low/medium/high | `--priority high` |\n| `--status` | `-s` | Initial status | `-s todo` |\n| `--parent` | | Parent task ID (raw ID only!) | `--parent 48` |\n\n**Example:**\n```bash\nknowns task create "Fix login timeout" \\\n  -d "Users experience timeout on slow networks" \\\n  --ac "Login works on 3G connection" \\\n  --ac "Timeout increased to 30s" \\\n  -l "bug,auth" \\\n  --priority high\n```\n\n---\n\n### task edit\n\n```\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--title` | `-t` | Change title | `-t "New title"` |\n| `--description` | `-d` | Change description | `-d "New desc"` |\n| `--status` | `-s` | Change status | `-s in-progress` |\n| `--priority` | | Change priority | `--priority high` |\n| `--labels` | `-l` | Set labels | `-l "bug,urgent"` |\n| `--assignee` | `-a` | Assign user \u26A0\uFE0F | `-a @username` |\n| `--parent` | | Move to parent | `--parent 48` |\n| `--ac` | | Add acceptance criterion | `--ac "New criterion"` |\n| `--check-ac` | | Mark AC done (1-indexed) | `--check-ac 1` |\n| `--uncheck-ac` | | Unmark AC (1-indexed) | `--uncheck-ac 1` |\n| `--remove-ac` | | Delete AC (1-indexed) | `--remove-ac 3` |\n| `--plan` | | Set implementation plan | `--plan "1. Step one"` |\n| `--notes` | | Replace notes | `--notes "Summary"` |\n| `--append-notes` | | Add to notes | `--append-notes "\u2713 Done"` |\n\n**\u26A0\uFE0F WARNING:** `-a` is assignee, NOT acceptance criteria! Use `--ac` for AC.\n\n**Examples:**\n```bash\n# Take task\nknowns task edit abc123 -s in-progress -a @me\n\n# Add acceptance criteria (use --ac, NOT -a!)\nknowns task edit abc123 --ac "Feature works offline"\n\n# Check criteria as done (1-indexed)\nknowns task edit abc123 --check-ac 1 --check-ac 2\n\n# Add implementation plan\nknowns task edit abc123 --plan $\'1. Research\\n2. Implement\\n3. Test\'\n\n# Add progress notes\nknowns task edit abc123 --append-notes "\u2713 Completed research phase"\n\n# Complete task\nknowns task edit abc123 -s done\n```\n\n---\n\n### task view/list\n\n```bash\n# View single task (ALWAYS use --plain for AI)\nknowns task <id> --plain\nknowns task view <id> --plain\n\n# List tasks\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --assignee @me --plain\nknowns task list --tree --plain\n```\n\n---\n\n## Doc Commands\n\n### doc create\n\n```\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--description` | `-d` | Description | `-d "API reference"` |\n| `--tags` | `-t` | Comma-separated tags | `-t "api,reference"` |\n| `--folder` | `-f` | Folder path | `-f "guides"` |\n\n**Example:**\n```bash\nknowns doc create "API Reference" \\\n  -d "REST API documentation" \\\n  -t "api,docs" \\\n  -f "api"\n```\n\n---\n\n### doc edit\n\n```\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose | Example |\n|------|-------|---------|---------|\n| `--title` | `-t` | Change title | `-t "New Title"` |\n| `--description` | `-d` | Change description | `-d "New desc"` |\n| `--tags` | | Set tags | `--tags "new,tags"` |\n| `--content` | `-c` | Replace content | `-c "New content"` |\n| `--append` | `-a` | Append content \u26A0\uFE0F | `-a "Added section"` |\n| `--content-file` | | Content from file | `--content-file ./content.md` |\n| `--append-file` | | Append from file | `--append-file ./more.md` |\n\n**\u26A0\uFE0F NOTE:** In doc edit, `-a` means append content, NOT assignee!\n\n**Examples:**\n```bash\n# Replace content\nknowns doc edit "readme" -c "# New Content"\n\n# Append content\nknowns doc edit "readme" -a "## New Section"\n```\n\n---\n\n### doc view/list\n\n```bash\n# View doc (ALWAYS use --plain for AI)\nknowns doc <path> --plain\nknowns doc view "<path>" --plain\n\n# List docs\nknowns doc list --plain\nknowns doc list --tag api --plain\nknowns doc list "guides/" --plain\n```\n\n---\n\n## Time Commands\n\n```bash\n# Start timer (REQUIRED when taking task)\nknowns time start <taskId>\n\n# Stop timer (REQUIRED when completing task)\nknowns time stop\n\n# Pause/resume\nknowns time pause\nknowns time resume\n\n# Check status\nknowns time status\n\n# Manual entry\nknowns time add <taskId> <duration> -n "Note" -d "2025-01-01"\n# duration: "2h", "30m", "1h30m"\n\n# Report\nknowns time report --from "2025-01-01" --to "2025-12-31"\n```\n\n---\n\n## Search Commands\n\n```bash\n# Search everything\nknowns search "query" --plain\n\n# Search by type\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\n\n# Filter by status/priority\nknowns search "bug" --type task --status in-progress --priority high --plain\n```\n\n---\n\n## Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash/Zsh (ANSI-C quoting):**\n```bash\nknowns task edit <id> --plan $\'1. Step one\\n2. Step two\\n3. Step three\'\n```\n\n**PowerShell:**\n```powershell\nknowns task edit <id> --plan "1. Step one`n2. Step two`n3. Step three"\n```\n\n**Cross-platform (heredoc):**\n```bash\nknowns task edit <id> --plan "$(cat <<EOF\n1. Step one\n2. Step two\n3. Step three\nEOF\n)"\n```\n\n---\n\n## MCP Tools (Alternative to CLI)\n\n| Action | MCP Tool |\n|--------|----------|\n| List tasks | `list_tasks({})` |\n| Get task | `get_task({ taskId })` |\n| Create task | `create_task({ title, description, priority, labels })` |\n| Update task | `update_task({ taskId, status, assignee, plan, notes })` |\n| Search tasks | `search_tasks({ query })` |\n| List docs | `list_docs({})` |\n| Get doc | `get_doc({ path })` |\n| Create doc | `create_doc({ title, description, tags, folder })` |\n| Update doc | `update_doc({ path, content, appendContent })` |\n| Start timer | `start_time({ taskId })` |\n| Stop timer | `stop_time({ taskId })` |\n\n**Note:** MCP does NOT support acceptance criteria operations. Use CLI:\n```bash\nknowns task edit <id> --ac "criterion"\nknowns task edit <id> --check-ac 1\n```\n';
+
+// src/templates/guidelines/workflow-completion.md
+var workflow_completion_default = '# Task Completion Workflow\n\nGuide for properly completing tasks.\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** of the following are complete:\n\n### \u2705 Via CLI Commands\n\n| Requirement | Command | Status |\n|-------------|---------|--------|\n| All AC checked | `knowns task edit <id> --check-ac N` | Required |\n| Implementation notes added | `knowns task edit <id> --notes "..."` | Required |\n| Timer stopped | `knowns time stop` | Required |\n| Status set to done | `knowns task edit <id> -s done` | Required |\n\n### \u2705 Via Code/Testing\n\n| Requirement | Action | Status |\n|-------------|--------|--------|\n| Tests pass | Run test suite | Required |\n| No regressions | Verify existing functionality | Required |\n| Docs updated | Update relevant documentation | If applicable |\n| Code reviewed | Self-review changes | Required |\n\n---\n\n## Completion Steps\n\n### Step 1: Verify All Acceptance Criteria\n\n```bash\n# View the task to check AC status\nknowns task <id> --plain\n\n# Ensure ALL criteria are checked\n# If any are unchecked, complete the work first!\n```\n\n### Step 2: Add Implementation Notes\n\nWrite notes suitable for a PR description:\n\n```bash\nknowns task edit <id> --notes $\'## Summary\nImplemented JWT authentication using jsonwebtoken library.\n\n## Changes\n- Added auth middleware in src/middleware/auth.ts\n- Added /login and /refresh endpoints\n- Created JWT utility functions\n\n## Tests\n- Added 15 unit tests\n- Coverage: 94%\n\n## Notes\n- Chose HS256 algorithm for simplicity\n- Token expiry set to 1 hour as per requirements\'\n```\n\n**Good notes include:**\n- What was implemented\n- Key decisions and why\n- Files changed\n- Test coverage\n- Any follow-up needed\n\n### Step 3: Stop Timer\n\n```bash\nknowns time stop\n```\n\n**\u26A0\uFE0F CRITICAL:** Never forget to stop the timer!\n\nIf you forgot to stop earlier, add manual entry:\n```bash\nknowns time add <id> 2h -n "Forgot to stop timer"\n```\n\n### Step 4: Mark as Done\n\n```bash\nknowns task edit <id> -s done\n```\n\n---\n\n## Post-Completion Changes\n\nIf the user requests changes **AFTER** the task is marked done:\n\n```bash\n# 1. Reopen task\nknowns task edit <id> -s in-progress\n\n# 2. Restart timer\nknowns time start <id>\n\n# 3. Add AC for the changes\nknowns task edit <id> --ac "Post-completion fix: description"\n\n# 4. Document why reopened\nknowns task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - reason"\n\n# 5. Complete the work, then follow completion steps again\n```\n\n---\n\n## Knowledge Extraction\n\nAfter completing a task, consider if any knowledge should be documented:\n\n```bash\n# Search if similar pattern already documented\nknowns search "pattern-name" --type doc --plain\n\n# If new reusable knowledge, create doc\nknowns doc create "Pattern: Name" \\\n  -d "Reusable pattern from task implementation" \\\n  -t "pattern" \\\n  -f "patterns"\n\n# Reference source task\nknowns doc edit "patterns/name" -a "Source: @task-<id>"\n```\n\n**Extract knowledge when:**\n- New patterns/conventions discovered\n- Common error solutions found\n- Reusable code approaches identified\n- Integration patterns documented\n\n**Don\'t extract:**\n- Task-specific details (those belong in implementation notes)\n- One-off solutions\n\n---\n\n## Common Mistakes\n\n### \u274C Marking done without all AC checked\n\n```bash\n# \u274C Wrong: AC not all checked\nknowns task edit <id> -s done\n\n# \u2705 Right: Check all AC first\nknowns task edit <id> --check-ac 1 --check-ac 2 --check-ac 3\nknowns task edit <id> -s done\n```\n\n### \u274C Forgetting to stop timer\n\nTimer keeps running! Always stop when done:\n```bash\nknowns time stop\n```\n\n### \u274C No implementation notes\n\nNotes are required for PR description:\n```bash\n# \u274C Wrong: No notes\nknowns task edit <id> -s done\n\n# \u2705 Right: Add notes first\nknowns task edit <id> --notes "Summary of what was done"\nknowns task edit <id> -s done\n```\n\n### \u274C Autonomously creating follow-up tasks\n\nAfter completing work, **present** follow-up ideas to the user. Don\'t automatically create new tasks without permission.\n\n---\n\n## Completion Checklist\n\nBefore marking done, verify:\n\n- [ ] All acceptance criteria are checked (`--check-ac`)\n- [ ] Implementation notes are added (`--notes`)\n- [ ] Implementation plan reflects final approach\n- [ ] Tests pass without regressions\n- [ ] Documentation updated if needed\n- [ ] Timer stopped (`knowns time stop`)\n- [ ] Status set to done (`-s done`)\n';
+
+// src/templates/guidelines/workflow-creation.md
+var workflow_creation_default = '# Task Creation Workflow\n\nGuide for creating well-structured tasks.\n\n---\n\n## Step 1: Search First\n\nBefore creating a new task, check if similar work already exists:\n\n```bash\n# Search for existing tasks\nknowns search "keyword" --type task --plain\n\n# List tasks by status\nknowns task list --status todo --plain\nknowns task list --status in-progress --plain\n```\n\n**Why?** Avoid duplicate work and understand existing context.\n\n---\n\n## Step 2: Assess Scope\n\nAsk yourself:\n- Does this work fit in one PR?\n- Does it span multiple systems?\n- Are there natural breaking points?\n\n**Single task:** Work is focused, affects one area\n**Multiple tasks:** Work spans different subsystems or has phases\n\n---\n\n## Step 3: Create with Proper Structure\n\n### Basic Task Creation\n\n```bash\nknowns task create "Clear title describing what needs to be done" \\\n  -d "Description explaining WHY this is needed" \\\n  --ac "First acceptance criterion" \\\n  --ac "Second acceptance criterion" \\\n  --priority medium \\\n  -l "label1,label2"\n```\n\n### Creating Subtasks\n\n```bash\n# Create parent task first\nknowns task create "Parent feature"\n\n# Create subtasks (use raw ID, not task-XX)\nknowns task create "Subtask 1" --parent 48\nknowns task create "Subtask 2" --parent 48\n```\n\n---\n\n## Task Quality Guidelines\n\n### Title (The "what")\n\nClear, brief summary of the task.\n\n| \u274C Bad | \u2705 Good |\n|--------|---------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description (The "why")\n\nExplains context and purpose. Include doc references.\n\n```markdown\nWe need JWT authentication because sessions don\'t scale\nfor our microservices architecture.\n\nRelated: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria (The "what" - outcomes)\n\n**Key Principles:**\n- **Outcome-oriented** - Focus on results, not implementation\n- **Testable** - Can be objectively verified\n- **User-focused** - Frame from end-user perspective\n\n| \u274C Bad (Implementation details) | \u2705 Good (Outcomes) |\n|--------------------------------|-------------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n---\n\n## Anti-Patterns to Avoid\n\n### \u274C Don\'t create overly broad tasks\n\n```bash\n# \u274C Too broad - too many ACs\nknowns task create "Build entire auth system" \\\n  --ac "Login" --ac "Logout" --ac "Register" \\\n  --ac "Password reset" --ac "OAuth" --ac "2FA"\n\n# \u2705 Better - split into focused tasks\nknowns task create "Implement user login" --ac "User can login with email/password"\nknowns task create "Implement user registration" --ac "User can create account"\n```\n\n### \u274C Don\'t embed implementation steps in AC\n\n```bash\n# \u274C Implementation steps as AC\n--ac "Create auth.ts file"\n--ac "Add bcrypt dependency"\n--ac "Write handleLogin function"\n\n# \u2705 Outcome-focused AC\n--ac "User can login with valid credentials"\n--ac "Invalid credentials return 401 error"\n--ac "Successful login returns JWT token"\n```\n\n### \u274C Don\'t skip search\n\nAlways search for existing tasks first. You might find:\n- Duplicate task already exists\n- Related task with useful context\n- Completed task with reusable patterns\n\n---\n\n## Report Results\n\nAfter creating tasks, show the user:\n- Task ID\n- Title\n- Description summary\n- Acceptance criteria\n\nThis allows for feedback and corrections before work begins.\n';
+
+// src/templates/guidelines/workflow-execution.md
+var workflow_execution_default = '# Task Execution Workflow\n\nGuide for implementing tasks effectively.\n\n---\n\n## Step 1: Take the Task\n\nThe **first things** you must do when taking a task:\n\n```bash\n# Set status to in-progress and assign to yourself\nknowns task edit <id> -s in-progress -a @me\n\n# Start time tracking (REQUIRED!)\nknowns time start <id>\n```\n\n---\n\n## Step 2: Research & Understand\n\nBefore planning, gather complete context:\n\n```bash\n# Read the task details\nknowns task <id> --plain\n\n# Follow ALL refs in the task\n# @.knowns/docs/xxx.md \u2192 knowns doc "xxx" --plain\n# @.knowns/tasks/task-YY \u2192 knowns task YY --plain\n\n# Search for related documentation\nknowns search "keyword" --type doc --plain\n\n# Check similar completed tasks for patterns\nknowns search "keyword" --type task --status done --plain\n```\n\n**Why?** Understanding existing patterns prevents reinventing the wheel.\n\n---\n\n## Step 3: Create Implementation Plan\n\nCapture your plan in the task **BEFORE writing any code**.\n\n```bash\nknowns task edit <id> --plan $\'1. Research existing patterns (see @doc/xxx)\n2. Design approach\n3. Implement core functionality\n4. Add tests\n5. Update documentation\'\n```\n\n### \u26A0\uFE0F CRITICAL: Wait for Approval\n\n**Share the plan with the user and WAIT for explicit approval before coding.**\n\nDo not begin implementation until:\n- User approves the plan, OR\n- User explicitly tells you to skip review\n\n---\n\n## Step 4: Implement\n\nWork through your plan step by step:\n\n### Document Progress\n\n```bash\n# After completing each significant piece of work\nknowns task edit <id> --append-notes "\u2713 Completed: research phase"\nknowns task edit <id> --append-notes "\u2713 Completed: core implementation"\n```\n\n### Check Acceptance Criteria\n\nOnly mark AC as done **AFTER** the work is actually complete:\n\n```bash\n# After completing work for AC #1\nknowns task edit <id> --check-ac 1\n\n# After completing work for AC #2\nknowns task edit <id> --check-ac 2\n```\n\n**\u26A0\uFE0F CRITICAL:** Never check AC before the work is done. ACs represent completed outcomes.\n\n---\n\n## Scope Management\n\n### When New Requirements Emerge\n\nIf you discover additional work needed during implementation:\n\n**Option 1: Add to current task (if small)**\n```bash\nknowns task edit <id> --ac "New requirement discovered"\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X"\n```\n\n**Option 2: Create follow-up task (if significant)**\n```bash\nknowns task create "Follow-up: Additional feature" -d "Discovered during task <id>"\nknowns task edit <id> --append-notes "\u{1F4DD} Created follow-up task for X"\n```\n\n**\u26A0\uFE0F CRITICAL:** Stop and ask the user which option to use. Don\'t silently expand scope.\n\n---\n\n## Plan Updates\n\nIf your approach changes during implementation, update the plan:\n\n```bash\nknowns task edit <id> --plan $\'1. [DONE] Research\n2. [DONE] Original approach\n3. [CHANGED] New approach due to X\n4. Remaining work\'\n```\n\nThe plan should remain the **single source of truth** for how the task was solved.\n\n---\n\n## Handling Subtasks\n\n### When Assigned "Parent and All Subtasks"\n\nProceed sequentially without asking permission between each subtask:\n\n1. Complete subtask 1\n2. Complete subtask 2\n3. Continue until all done\n\n### When Assigned Single Subtask\n\nPresent progress and request guidance before advancing to the next subtask.\n\n---\n\n## Key Principles\n\n1. **Plan before code** - Always capture approach before implementation\n2. **Document decisions** - Record why you chose certain approaches\n3. **Update on changes** - Keep plan current if approach shifts\n4. **Ask on scope** - Don\'t silently expand work\n5. **Check AC after work** - Only mark done when truly complete\n';
+
+// src/templates/guidelines/common-mistakes.md
+var common_mistakes_default = '# Common Mistakes\n\nAnti-patterns and common errors to avoid.\n\n---\n\n## \u26A0\uFE0F CRITICAL: Flag Confusion\n\n### The -a Flag Means Different Things!\n\n| Command | `-a` Flag 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### \u274C WRONG: Using -a for Acceptance Criteria\n\n```bash\n# \u274C WRONG: -a is assignee, sets assignee to garbage text!\nknowns task edit 35 -a "- [ ] Criterion"\nknowns task edit 35 -a "User can login"\nknowns task create "Title" -a "Criterion text"\n```\n\n### \u2705 CORRECT: Using --ac for Acceptance Criteria\n\n```bash\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## Quick Reference: DO vs DON\'T\n\n### File Operations\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| Edit .md files directly | Use CLI commands |\n| Change `- [ ]` to `- [x]` in file | `--check-ac <index>` |\n| Add notes directly to file | `--notes` or `--append-notes` |\n| Edit frontmatter manually | Use CLI flags |\n\n### Task Operations\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| `-a "criterion"` (assignee!) | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| Skip time tracking | Always `time start`/`time stop` |\n| Check AC before work done | Check AC AFTER completing work |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read ALL related docs first |\n\n### Flag Usage\n\n| \u274C DON\'T | \u2705 DO |\n|----------|-------|\n| `--plain` with create | `--plain` only for view/list/search |\n| `--plain` with edit | `--plain` only for view/list/search |\n| `--criteria "text"` | `--ac "text"` |\n| `-ac "text"` | `--ac "text"` (two dashes!) |\n\n---\n\n## Detailed Mistakes\n\n### 1. Direct File Editing\n\n```markdown\n# \u274C DON\'T DO THIS:\n1. Open backlog/tasks/task-7.md in editor\n2. Change "- [ ]" to "- [x]" manually\n3. Add notes directly to the file\n4. Save the file\n\n# \u2705 DO THIS INSTEAD:\nknowns task edit 7 --check-ac 1\nknowns task edit 7 --notes "Implementation complete"\n```\n\n**Why?** Direct editing breaks:\n- Metadata synchronization\n- Git tracking\n- Task relationships\n\n### 2. Wrong Flag for Acceptance Criteria\n\n```bash\n# \u274C WRONG: All these set assignee, NOT acceptance criteria\nknowns task edit 35 -a "Criterion"\nknowns task create "Title" -a "AC text"\nknowns task edit 35 --assignee "Criterion"  # Still wrong!\n\n# \u2705 CORRECT: Use --ac\nknowns task edit 35 --ac "Criterion"\nknowns task create "Title" --ac "AC text"\n```\n\n### 3. Wrong Task ID Format for Parent\n\n```bash\n# \u274C WRONG: Don\'t prefix with "task-"\nknowns task create "Title" --parent task-48\nknowns task edit 35 --parent task-48\n\n# \u2705 CORRECT: Use raw ID only\nknowns task create "Title" --parent 48\nknowns task edit 35 --parent qkh5ne\n```\n\n### 4. Using --plain with Create/Edit\n\n```bash\n# \u274C WRONG: create/edit don\'t support --plain\nknowns task create "Title" --plain       # ERROR!\nknowns task edit 35 -s done --plain      # ERROR!\nknowns doc create "Title" --plain        # ERROR!\nknowns doc edit "name" -c "..." --plain  # ERROR!\n\n# \u2705 CORRECT: --plain only for view/list/search\nknowns task 35 --plain                   # OK\nknowns task list --plain                 # OK\nknowns doc "readme" --plain              # OK\nknowns search "query" --plain            # OK\n```\n\n### 5. Skipping Time Tracking\n\n```bash\n# \u274C WRONG: No timer\nknowns task edit 35 -s in-progress\n# ... work ...\nknowns task edit 35 -s done\n\n# \u2705 CORRECT: Always track time\nknowns task edit 35 -s in-progress -a @me\nknowns time start 35\n# ... work ...\nknowns time stop\nknowns task edit 35 -s done\n```\n\n### 6. Checking AC Before Work is Done\n\n```bash\n# \u274C WRONG: Checking AC as a TODO list\nknowns task edit 35 --check-ac 1  # Haven\'t done the work yet!\n# ... then do the work ...\n\n# \u2705 CORRECT: Check AC AFTER completing work\n# ... do the work first ...\nknowns task edit 35 --check-ac 1  # Now it\'s actually done\n```\n\n### 7. Coding Before Plan Approval\n\n```bash\n# \u274C WRONG: Start coding immediately\nknowns task edit 35 -s in-progress\nknowns task edit 35 --plan "1. Do X\\n2. Do Y"\n# Immediately starts coding...\n\n# \u2705 CORRECT: Wait for approval\nknowns task edit 35 -s in-progress\nknowns task edit 35 --plan "1. Do X\\n2. Do Y"\n# STOP! Present plan to user\n# Wait for explicit approval\n# Then start coding\n```\n\n### 8. Ignoring Task References\n\n```bash\n# \u274C WRONG: Don\'t read refs\nknowns task 35 --plain\n# See "@.knowns/docs/api.md" but don\'t read it\n# Start implementing without context...\n\n# \u2705 CORRECT: Follow ALL refs\nknowns task 35 --plain\n# See "@.knowns/docs/api.md"\nknowns doc "api" --plain  # Read it!\n# See "@.knowns/tasks/task-30"\nknowns task 30 --plain    # Read it!\n# Now have full context\n```\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n| Set assignee to AC text by mistake | `knowns task edit <id> -a @me` to fix |\n| Forgot to stop timer | `knowns time add <id> <duration> -n "Forgot to stop"` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac <index>` |\n| Task not found | `knowns task list --plain` to find correct ID |\n| AC index out of range | `knowns task <id> --plain` to see AC numbers |\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 Guidelines = {
+  // Core rules - always needed
+  core: CORE_RULES,
+  // Commands reference
+  commands: COMMANDS_REFERENCE,
+  // Workflow stages
+  workflow: {
+    creation: WORKFLOW_CREATION,
+    execution: WORKFLOW_EXECUTION,
+    completion: WORKFLOW_COMPLETION
+  },
+  // Common mistakes
+  mistakes: COMMON_MISTAKES,
+  /**
+   * Get full guidelines (all sections combined)
+   */
+  getFull(withMarkers2 = false) {
+    const content = [
+      CORE_RULES,
+      "---",
+      COMMANDS_REFERENCE,
+      "---",
+      WORKFLOW_CREATION,
+      "---",
+      WORKFLOW_EXECUTION,
+      "---",
+      WORKFLOW_COMPLETION,
+      "---",
+      COMMON_MISTAKES
+    ].join("\n\n");
+    if (withMarkers2) {
+      return `<!-- KNOWNS GUIDELINES START -->
+${content}
+<!-- KNOWNS GUIDELINES END -->`;
+    }
+    return content;
+  },
+  /**
+   * Get compact guidelines (core + mistakes only)
+   */
+  getCompact() {
+    return [CORE_RULES, "---", COMMON_MISTAKES].join("\n\n");
+  },
+  /**
+   * Get guidelines for specific workflow stage
+   */
+  getForStage(stage) {
+    const sections = [CORE_RULES, "---"];
+    switch (stage) {
+      case "creation":
+        sections.push(WORKFLOW_CREATION);
+        break;
+      case "execution":
+        sections.push(WORKFLOW_EXECUTION);
+        sections.push("---", COMMANDS_REFERENCE);
+        break;
+      case "completion":
+        sections.push(WORKFLOW_COMPLETION);
+        break;
+    }
+    sections.push("---", COMMON_MISTAKES);
+    return sections.join("\n\n");
+  }
+};
 
-// src/templates/cli/general.md
-var general_default = '<!-- KNOWNS GUIDELINES START -->\n# Knowns CLI Guidelines\n\n## Core Principles\n\n### 1. CLI-Only Operations\n**NEVER edit .md files directly. ALL operations MUST use CLI commands.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```bash\n# 1. List all available documentation\nknowns doc list --plain\n\n# 2. Read essential project docs (prioritize these)\nknowns doc "README" --plain                # Project overview\nknowns doc "ARCHITECTURE" --plain          # System design\nknowns doc "CONVENTIONS" --plain           # Coding standards\nknowns doc "API" --plain                   # API specifications\n\n# 3. Review current task backlog\nknowns task list --plain\nknowns task list --status in-progress --plain\n```\n\n### Before Taking Any Task\n\n```bash\n# 1. View the task details\nknowns task <id> --plain\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.knowns/tasks/task-44 - ... \u2192 knowns task 44 --plain\n# @.knowns/docs/patterns/module.md \u2192 knowns doc "patterns/module" --plain\n\n# 3. Search for additional related documentation\nknowns search "<keywords from task>" --type doc --plain\n\n# 4. Read ALL related docs before planning\nknowns doc "<related-doc>" --plain\n\n# 5. Check for similar completed tasks (learn from history)\nknowns search "<keywords>" --type task --status done --plain\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.knowns/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | CLI Command |\n|------|---------------------|----------------------|-------------|\n| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `knowns task <id> --plain` |\n| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `knowns doc <path> --plain` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output from `--plain`: You\'ll see `@.knowns/tasks/...` and `@.knowns/docs/...`\n> - **NEVER write** the output format (`@.knowns/...`) - always use input format (`@task-<id>`, `@doc/<path>`)\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```bash\n# Example: Task 42 output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nknowns task 44 --plain\n\n# Follow doc ref (extract path, remove .md)\nknowns doc "patterns/module" --plain\n```\n\n### Parsing Rules\n\n1. **Task refs**: `@.knowns/tasks/task-<id> - ...` \u2192 extract `<id>` \u2192 `knowns task <id> --plain`\n2. **Doc refs**: `@.knowns/docs/<path>.md` \u2192 extract `<path>` \u2192 `knowns doc "<path>" --plain`\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n  \u2192 @.knowns/docs/README.md\n    \u2192 @.knowns/docs/patterns/module.md (found in README)\n      \u2192 (read for full pattern details)\n```\n\n### When to Follow Refs\n\n| Situation | Action |\n|-----------|--------|\n| Refs in Description | ALWAYS follow - critical context |\n| Refs in Implementation Plan | Follow if implementing related work |\n| Refs in Notes | Optional - for historical context |\n| Dependency mentions | Follow if marked as blocker |\n\n### Example: Complete Ref Resolution\n\n```bash\n# 1. Read the task\n$ knowns task 42 --plain\n\n# Output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/README.md\n\n# 2. Follow task ref\n$ knowns task 44 --plain\n\n# 3. Follow doc ref\n$ knowns doc "README" --plain\n\n# 4. If README contains more refs, follow them too\n# @.knowns/docs/patterns/module.md \u2192 knowns doc "patterns/module" --plain\n\n# Now you have complete context\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```bash\n# Initialize project\nknowns init [name]\n\n# Create task with acceptance criteria\nknowns task create "Title" -d "Description" --ac "Criterion 1" --ac "Criterion 2"\n\n# View task (ALWAYS use --plain for AI)\nknowns task <id> --plain                    # Shorthand\nknowns task view <id> --plain               # Full command\n\n# View doc (ALWAYS use --plain for AI)\nknowns doc <path> --plain                   # Shorthand\nknowns doc view "<path>" --plain            # Full command\n\n# List tasks\nknowns task list --plain\n\n# Search (tasks + docs)\nknowns search "query" --plain\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```bash\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\n$ knowns doc list --plain\n\n# Output:\n# DOC: README.md\n# DOC: ARCHITECTURE.md\n# DOC: CONVENTIONS.md\n# DOC: security-patterns.md\n# DOC: api-guidelines.md\n# DOC: email-templates.md\n\n# 0b. Read essential project docs\n$ knowns doc "README" --plain\n$ knowns doc "ARCHITECTURE" --plain\n$ knowns doc "CONVENTIONS" --plain\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\n$ knowns task create "Add password reset flow" \\\n    -d "Users need ability to reset forgotten passwords via email" \\\n    --ac "User can request password reset via email" \\\n    --ac "Reset link expires after 1 hour" \\\n    --ac "User can set new password via reset link" \\\n    --ac "Unit tests cover all scenarios" \\\n    --priority high \\\n    -l "auth,feature"\n\n# Output: Created task AUTH-042\n\n# 2. Take the task and start timer (uses defaultAssignee or @me fallback)\n$ knowns task edit AUTH-042 -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\n$ knowns time start AUTH-042\n\n# Output: Timer started for AUTH-042\n\n# 3. Search for related documentation\n$ knowns search "password security" --type doc --plain\n\n# Output:\n# DOC: security-patterns.md (score: 0.92)\n# DOC: email-templates.md (score: 0.78)\n\n# 4. Read the documentation\n$ knowns doc "security-patterns" --plain\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\n$ knowns task edit AUTH-042 --plan $\'1. Review security patterns (see @doc/security-patterns)\n2. Design token generation with 1-hour expiry\n3. Create email template (see @doc/email-templates)\n4. Implement /forgot-password endpoint\n5. Implement /reset-password endpoint\n6. Add unit tests\n7. Update API documentation\'\n\n# 6. After approval, implement and check criteria as you go\n$ knowns task edit AUTH-042 --check-ac 1\n$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /forgot-password endpoint"\n\n$ knowns task edit AUTH-042 --check-ac 2\n$ knowns task edit AUTH-042 --append-notes "\u2713 Token expiry set to 1 hour"\n\n$ knowns task edit AUTH-042 --check-ac 3\n$ knowns task edit AUTH-042 --append-notes "\u2713 Implemented /reset-password endpoint"\n\n$ knowns task edit AUTH-042 --check-ac 4\n$ knowns task edit AUTH-042 --append-notes "\u2713 Added 12 unit tests, 100% coverage"\n\n# 7. Add final implementation notes\n$ knowns task edit AUTH-042 --notes $\'## Summary\nImplemented complete password reset flow with secure token generation.\n\n## Changes\n- Added POST /forgot-password endpoint\n- Added POST /reset-password endpoint\n- Created password_reset_tokens table\n- Added email template for reset link\n\n## Security\n- Tokens use crypto.randomBytes(32)\n- 1-hour expiry enforced at DB level\n- Rate limiting: 3 requests per hour per email\n\n## Tests\n- 12 unit tests added\n- Coverage: 100% for new code\n\n## Documentation\n- Updated API.md with new endpoints\'\n\n# 8. Stop timer and complete\n$ knowns time stop\n$ knowns task edit AUTH-042 -s done\n\n# Output: Task AUTH-042 marked as done\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```bash\n# Assign using defaultAssignee from config (falls back to @me if not set)\nknowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\n```\n\n> **Note**: The `defaultAssignee` is configured in `.knowns/config.json` during `knowns init`. If not set, `@me` is used as fallback. To update: `knowns config set defaultAssignee "@username"`\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```bash\nknowns time start <id>\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```bash\n# Search for related docs\nknowns search "authentication" --type doc --plain\n\n# View relevant documents\nknowns doc "API Guidelines" --plain\nknowns doc "Security Patterns" --plain\n\n# Also check for similar completed tasks\nknowns search "auth" --type task --status done --plain\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning! Understanding existing patterns and conventions prevents rework and ensures consistency.\n\n### Step 4: Create Implementation Plan\n\n```bash\nknowns task edit <id> --plan $\'1. Research patterns (see @doc/security-patterns)\n2. Design middleware\n3. Implement\n4. Add tests\n5. Update docs\'\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```bash\n# Work through implementation plan step by step\n# IMPORTANT: Only check AC AFTER completing the work, not before\n\n# After completing work for AC #1:\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Completed: <brief description>"\n\n# After completing work for AC #2:\nknowns task edit <id> --check-ac 2\nknowns task edit <id> --append-notes "\u2713 Completed: <brief description>"\n```\n\n> **CRITICAL**: Never check an AC before the work is actually done. ACs represent completed outcomes, not intentions.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```bash\n# Add new acceptance criteria\nknowns task edit <id> --ac "New requirement from user"\n\n# Update implementation plan to include new steps\nknowns task edit <id> --plan $\'1. Original step 1\n2. Original step 2\n3. NEW: Handle user request for X\n4. Continue with remaining work\'\n\n# Append note about scope change\nknowns task edit <id> --append-notes "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```bash\n# Add comprehensive notes (suitable for PR description)\nknowns task edit <id> --notes $\'## Summary\n\nImplemented JWT auth.\n\n## Changes\n- Added middleware\n- Added tests\'\n\n# OR append progressively (recommended)\nknowns task edit <id> --append-notes "\u2713 Implemented middleware"\nknowns task edit <id> --append-notes "\u2713 Added tests"\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```bash\nknowns time stop\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry: `knowns time add <id> <duration> -n "Forgot to stop timer"`\n\n### Step 9: Complete Task\n\n```bash\nknowns task edit <id> -s done\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```bash\n# 1. Reopen task - set back to in-progress\nknowns task edit <id> -s in-progress\n\n# 2. Restart time tracking (REQUIRED)\nknowns time start <id>\n\n# 3. Add new AC for the changes requested\nknowns task edit <id> --ac "Post-completion fix: <description>"\n\n# 4. Document the reopen reason\nknowns task edit <id> --append-notes "\u{1F504} Reopened: User requested changes - <reason>"\n\n# 5. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Add AC for traceability\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```bash\n# Search if similar pattern already documented\nknowns search "<pattern/concept>" --type doc --plain\n\n# If new knowledge, create a doc for future reference\nknowns doc create "Pattern: <Name>" \\\n    -d "Reusable pattern discovered during task implementation" \\\n    -t "pattern,<domain>" \\\n    -f "patterns"\n\n# Or append to existing doc\nknowns doc edit "<existing-doc>" -a "## New Section\\n\\nLearned from task <id>: ..."\n\n# Reference the source task\nknowns doc edit "<doc-name>" -a "\\n\\n> Source: @task-<id>"\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential Commands\n\n### Task Management\n\n```bash\n# Create task\nknowns task create "Title" -d "Description" --ac "Criterion" -l "labels" --priority high\n\n# Edit task\nknowns task edit <id> -t "New title"\nknowns task edit <id> -d "New description"\nknowns task edit <id> -s in-progress\nknowns task edit <id> --priority high\nknowns task edit <id> -a <assignee>              # $(knowns config get defaultAssignee --plain || echo "@me")\n\n# Acceptance Criteria\nknowns task edit <id> --ac "New criterion"           # Add\nknowns task edit <id> --check-ac 1 --check-ac 2      # Check (1-indexed)\nknowns task edit <id> --uncheck-ac 2                 # Uncheck\nknowns task edit <id> --remove-ac 3                  # Remove\n\n# Implementation Plan & Notes\nknowns task edit <id> --plan $\'1. Step\\n2. Step\'\nknowns task edit <id> --notes "Implementation summary"\nknowns task edit <id> --append-notes "Progress update"\n\n# View & List\nknowns task <id> --plain                             # Shorthand (ALWAYS use --plain)\nknowns task view <id> --plain                        # Full command\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --assignee <assignee> --plain   # $(knowns config get defaultAssignee --plain || echo "@me")\nknowns task list --tree --plain                      # Tree hierarchy\n```\n\n### Time Tracking\n\n```bash\n# Timer\nknowns time start <id>\nknowns time stop\nknowns time pause\nknowns time resume\nknowns time status\n\n# Manual entry\nknowns time add <id> 2h -n "Note" -d "2025-12-25"\n\n# Reports\nknowns time report --from "2025-12-01" --to "2025-12-31"\nknowns time report --by-label --csv > report.csv\n```\n\n### Documentation\n\n```bash\n# List & View\nknowns doc list --plain\nknowns doc list --tag architecture --plain\nknowns doc <path> --plain                          # Shorthand (ALWAYS use --plain)\nknowns doc view "<path>" --plain                   # Full command\n\n# Create (with optional folder)\nknowns doc create "Title" -d "Description" -t "tags"\nknowns doc create "Title" -d "Description" -t "tags" -f "folder/path"\n\n# Edit metadata\nknowns doc edit "Doc Name" -t "New Title" --tags "new,tags"\n\n# Edit content\nknowns doc edit "Doc Name" -c "New content"        # Replace content\nknowns doc edit "Doc Name" -a "Appended content"   # Append to content\n```\n\n#### Doc Organization\n\n| Doc Type | Location | Example |\n|----------|----------|---------|\n| **Important/Core docs** | Root `.knowns/docs/` | `README.md`, `ARCHITECTURE.md`, `CONVENTIONS.md` |\n| **Guides** | `.knowns/docs/guides/` | `guides/getting-started.md` |\n| **Patterns** | `.knowns/docs/patterns/` | `patterns/controller.md` |\n| **API docs** | `.knowns/docs/api/` | `api/endpoints.md` |\n| **Other categorized docs** | `.knowns/docs/<category>/` | `security/auth-patterns.md` |\n\n```bash\n# Important docs - at root (no -f flag)\nknowns doc create "README" -d "Project overview" -t "core"\nknowns doc create "ARCHITECTURE" -d "System design" -t "core"\n\n# Categorized docs - use -f for folder\nknowns doc create "Getting Started" -d "Setup guide" -t "guide" -f "guides"\nknowns doc create "Controller Pattern" -d "MVC pattern" -t "pattern" -f "patterns"\n```\n\n### Search\n\n```bash\n# Search everything\nknowns search "query" --plain\n\n# Search specific type\nknowns search "auth" --type task --plain\nknowns search "patterns" --type doc --plain\n\n# Filter\nknowns search "bug" --status in-progress --priority high --plain\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```markdown\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n### Implementation Plan\n\nHOW to solve. Added AFTER taking task, BEFORE coding.\n\n```markdown\n1. Research JWT libraries (see @doc/security-patterns)\n2. Design token structure (access + refresh tokens)\n3. Implement auth middleware\n4. Add unit tests (aim for 90%+ coverage)\n5. Update API.md with new endpoints\n```\n\n### Implementation Notes\n\nSummary for PR description. Added AFTER completion.\n\n```markdown\n## Summary\nImplemented JWT auth using jsonwebtoken library.\n\n## Changes\n- Added auth middleware in src/middleware/auth.ts\n- Added /login and /refresh endpoints\n- Created JWT utility functions\n\n## Tests\n- Added 15 unit tests\n- Coverage: 94%\n\n## Documentation\n- Updated API.md with authentication section\n```\n\n---\n\n## Error Handling\n\n### Common Errors and Solutions\n\n| Error | Cause | Solution |\n|-------|-------|----------|\n| `Error: Task not found` | Invalid task ID | Run `knowns task list --plain` to find correct ID |\n| `Error: No active timer` | Calling `time stop` without active timer | Start timer first: `knowns time start <id>` |\n| `Error: Timer already running` | Starting timer when one is active | Stop current: `knowns time stop` |\n| `Error: Invalid status` | Wrong status format | Use lowercase with hyphens: `in-progress`, not `In Progress` |\n| `Error: AC index out of range` | Checking non-existent criterion | View task first: `knowns task <id> --plain` |\n| `Error: Document not found` | Wrong document name | Run `knowns doc list --plain` to find correct name |\n| `Error: Not initialized` | Running commands without init | Run `knowns init` first |\n\n### Debugging Commands\n\n```bash\n# Check CLI version\nknowns --version\n\n# Verify project is initialized\nknowns status\n\n# View raw task data (for debugging)\nknowns task <id> --json\n\n# Check timer status\nknowns time status\n```\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via CLI (Required)\n\n- [ ] All acceptance criteria checked: `--check-ac <index>` (only after work is actually done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] \u23F1\uFE0F Timer stopped: `knowns time stop` (MANDATORY - do not skip!)\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\nUse **lowercase with hyphens**:\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use `knowns task edit` |\n| Change `- [ ]` to `- [x]` in file | Use `--check-ac <index>` |\n| Check AC before completing work | Only check AC AFTER work is actually done |\n| Skip time tracking | ALWAYS use `time start` and `time stop` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Skip `knowns doc list` on new project | Always list docs when starting |\n| Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |\n| Plan without checking docs | Read docs before planning |\n| Ignore similar completed tasks | Search done tasks for patterns |\n| Missing doc links in description/plan | Link docs using `@doc/<path>` |\n| Write refs as `@.knowns/docs/...` or `@.knowns/tasks/...` | Use input format: `@doc/<path>`, `@task-<id>` |\n| Forget `--plain` flag | Always use `--plain` for AI |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Check ALL criteria first |\n| Write implementation steps in AC | Write outcome-oriented criteria |\n| Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |\n| Use `@yourself` or unknown assignee | Use `$(knowns config get defaultAssignee --plain \\|\\| echo "@me")` |\n| Ignore refs in task description | Follow ALL refs (`@.knowns/...`) before planning |\n| See `@.knowns/docs/...` but don\'t read | Use `knowns doc "<path>" --plain` |\n| See `@.knowns/tasks/task-X` but don\'t check | Use `knowns task X --plain` for context |\n| Follow only first-level refs | Recursively follow nested refs until complete |\n| Use `--plain` with `task create` | `--plain` is only for view/list commands |\n| Use `--plain` with `task edit` | `--plain` is only for view/list commands |\n| Use `--plain` with `doc create` | `--plain` is only for view/list commands |\n| Use `--plain` with `doc edit` | `--plain` is only for view/list commands |\n\n---\n\n## The `--plain` Flag (AI Agents)\n\n> **\u26A0\uFE0F CRITICAL FOR AI AGENTS**: The `--plain` flag is ONLY supported by **view/list/search** commands. Using it with create/edit commands will cause errors!\n\n### \u2705 Commands that support `--plain`\n\nThese are **read-only** commands - use `--plain` to get clean output:\n\n```bash\n# Task viewing/listing\nknowns task <id> --plain\nknowns task view <id> --plain\nknowns task list --plain\nknowns task list --status in-progress --plain\n\n# Doc viewing/listing\nknowns doc <path> --plain\nknowns doc view "<path>" --plain\nknowns doc list --plain\nknowns doc list --tag <tag> --plain\n\n# Search\nknowns search "<query>" --plain\nknowns search "<query>" --type task --plain\nknowns search "<query>" --type doc --plain\n\n# Config\nknowns config get <key> --plain\n```\n\n### \u274C Commands that do NOT support `--plain`\n\nThese are **write** commands - NEVER use `--plain`:\n\n```bash\n# Task create/edit - NO --plain!\nknowns task create "Title" -d "Description"          # \u2705 Correct\nknowns task create "Title" --plain                   # \u274C ERROR!\nknowns task edit <id> -s done                        # \u2705 Correct\nknowns task edit <id> -s done --plain                # \u274C ERROR!\n\n# Doc create/edit - NO --plain!\nknowns doc create "Title" -d "Description"           # \u2705 Correct\nknowns doc create "Title" --plain                    # \u274C ERROR!\nknowns doc edit "name" -c "content"                  # \u2705 Correct\nknowns doc edit "name" -c "content" --plain          # \u274C ERROR!\n\n# Time tracking - NO --plain!\nknowns time start <id>                               # \u2705 Correct\nknowns time stop                                     # \u2705 Correct\nknowns time add <id> 2h                              # \u2705 Correct\n```\n\n### Quick Reference Table\n\n| Command Type | Example | `--plain` Support |\n|-------------|---------|-------------------|\n| `task <id>` | `knowns task 42 --plain` | \u2705 Yes |\n| `task list` | `knowns task list --plain` | \u2705 Yes |\n| `task create` | `knowns task create "Title"` | \u274C No |\n| `task edit` | `knowns task edit 42 -s done` | \u274C No |\n| `doc <path>` | `knowns doc "README" --plain` | \u2705 Yes |\n| `doc list` | `knowns doc list --plain` | \u2705 Yes |\n| `doc create` | `knowns doc create "Title"` | \u274C No |\n| `doc edit` | `knowns doc edit "name" -c "..."` | \u274C No |\n| `search` | `knowns search "query" --plain` | \u2705 Yes |\n| `time start/stop` | `knowns time start 42` | \u274C No |\n| `time add` | `knowns time add 42 2h` | \u274C No |\n| `config get` | `knowns config get key --plain` | \u2705 Yes |\n| `config set` | `knowns config set key value` | \u274C No |\n\n---\n\n## Platform-Specific Notes\n\n### Multi-line Input\n\nDifferent shells handle multi-line strings differently:\n\n**Bash / Zsh (Recommended)**\n```bash\nknowns task edit <id> --plan $\'1. First step\\n2. Second step\\n3. Third step\'\n```\n\n**PowerShell**\n```powershell\nknowns task edit <id> --plan "1. First step`n2. Second step`n3. Third step"\n```\n\n**Cross-platform (Using printf)**\n```bash\nknowns task edit <id> --plan "$(printf \'1. First step\\n2. Second step\\n3. Third step\')"\n```\n\n**Using heredoc (for long content)**\n```bash\nknowns task edit <id> --plan "$(cat <<EOF\n1. First step\n2. Second step\n3. Third step\nEOF\n)"\n```\n\n### Path Separators\n\n- **Unix/macOS**: Use forward slashes: `./docs/api.md`\n- **Windows**: Both work, but prefer forward slashes for consistency\n\n### Windows Command Line Limit\n\nWindows has ~8191 character limit. For long content, append in chunks:\n\n```bash\n# 1. Create or reset with short content\nknowns doc edit "doc-name" -c "## Overview\\n\\nShort intro."\n\n# 2. Append each section separately\nknowns doc edit "doc-name" -a "## Section 1\\n\\nContent..."\nknowns doc edit "doc-name" -a "## Section 2\\n\\nMore content..."\n```\n\nOr use file-based options:\n\n```bash\nknowns doc edit "doc-name" --content-file ./content.md\nknowns doc edit "doc-name" --append-file ./more.md\n```\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `knowns doc list --plain`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task has clear acceptance criteria\n- [ ] ALL refs in task followed (`@.knowns/...`)\n- [ ] Nested refs recursively followed until complete context gathered\n- [ ] Related docs searched: `knowns search "keyword" --type doc --plain`\n- [ ] ALL relevant docs read: `knowns doc "Doc Name" --plain`\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self: `-a $(knowns config get defaultAssignee --plain || echo "@me")`\n- [ ] Status set to in-progress: `-s in-progress`\n- [ ] Timer started: `knowns time start <id>`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Criteria checked as completed: `--check-ac <index>`\n- [ ] Progress notes appended: `--append-notes "\u2713 ..."`\n\n### After Work\n\n- [ ] All acceptance criteria checked (only after work is done)\n- [ ] Implementation notes added: `--notes "..."`\n- [ ] Timer stopped: `knowns time stop`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done: `-s done`\n- [ ] Knowledge extracted to docs (if applicable): patterns, solutions, conventions\n\n---\n\n## Quick Reference Card\n\n```bash\n# === AGENT INITIALIZATION (Once per session) ===\nknowns doc list --plain\nknowns doc "README" --plain\nknowns doc "ARCHITECTURE" --plain\nknowns doc "CONVENTIONS" --plain\n\n# === FULL WORKFLOW ===\nknowns task create "Title" -d "Description" --ac "Criterion"\nknowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")\nknowns time start <id>                                     # \u23F1\uFE0F REQUIRED: Start timer\nknowns search "keyword" --type doc --plain\nknowns doc "Doc Name" --plain\nknowns search "keyword" --type task --status done --plain  # Learn from history\nknowns task edit <id> --plan $\'1. Step (see @doc/file)\\n2. Step\'\n# ... wait for approval, then implement ...\n# Only check AC AFTER completing the work:\nknowns task edit <id> --check-ac 1\nknowns task edit <id> --append-notes "\u2713 Completed: feature X"\nknowns task edit <id> --check-ac 2\nknowns task edit <id> --append-notes "\u2713 Completed: feature Y"\nknowns time stop                                           # \u23F1\uFE0F REQUIRED: Stop timer\nknowns task edit <id> -s done\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nknowns task <id> --plain                                   # Shorthand for view\nknowns task list --plain\nknowns task list --status in-progress --assignee $(knowns config get defaultAssignee --plain || echo "@me") --plain\nknowns search "query" --plain\nknowns search "bug" --type task --status in-progress --plain\n\n# === TIME TRACKING ===\nknowns time start <id>\nknowns time stop\nknowns time status\nknowns time report --from "2025-12-01" --to "2025-12-31"\n\n# === DOCUMENTATION ===\nknowns doc list --plain\nknowns doc "path/doc-name" --plain                         # Shorthand for view\nknowns doc create "Title" -d "Description" -t "tags" -f "folder"\nknowns doc edit "doc-name" -c "New content"\nknowns doc edit "doc-name" -a "Appended content"\n```\n\n---\n\n**Maintained By**: Knowns CLI Team\n\n<!-- KNOWNS GUIDELINES END -->\n';
+// src/templates/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';
 
-// src/templates/mcp/gemini.md
-var gemini_default2 = '<!-- KNOWNS GUIDELINES START -->\n# Knowns MCP - Gemini Quick Reference\n\n## RULES\n- NEVER edit .md files directly - use MCP tools only\n- Read docs BEFORE coding\n- Start timer when taking task, stop when done\n\n## SESSION START\n```\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__list_tasks({})\n```\n\n## TASK WORKFLOW\n\n### 1. Take Task\n```\nmcp__knowns__get_task({ taskId: "<id>" })\nmcp__knowns__update_task({ taskId: "<id>", status: "in-progress", assignee: "@me" })\nmcp__knowns__start_time({ taskId: "<id>" })\n```\n\n### 2. Read Context\n```\nmcp__knowns__list_docs({ tag: "guides" })\nmcp__knowns__get_doc({ path: "path/name" })\nmcp__knowns__search_docs({ query: "keyword" })\n```\n\n### 3. Plan & Implement\n```\nmcp__knowns__update_task({ taskId: "<id>", description: "Updated with plan..." })\n// Wait for approval, then code\nmcp__knowns__update_task({ taskId: "<id>", labels: ["done-ac-1"] })\n```\n\n### 4. Complete\n```\nmcp__knowns__stop_time({ taskId: "<id>" })\nmcp__knowns__update_task({ taskId: "<id>", status: "done" })\n```\n\n## MCP TOOLS CHEATSHEET\n\n### Task\n```\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\nmcp__knowns__get_task({ taskId: "<id>" })\nmcp__knowns__create_task({ title: "Title", description: "Desc", priority: "high" })\nmcp__knowns__update_task({ taskId: "<id>", status: "<status>", assignee: "@me" })\nmcp__knowns__search_tasks({ query: "keyword" })\n```\n\n### Doc\n```\nmcp__knowns__list_docs({})\nmcp__knowns__list_docs({ tag: "patterns" })\nmcp__knowns__get_doc({ path: "name" })\nmcp__knowns__create_doc({ title: "Title", description: "Desc", tags: ["tag1"] })\nmcp__knowns__update_doc({ path: "name", content: "new content" })\nmcp__knowns__update_doc({ path: "name", appendContent: "more content" })\nmcp__knowns__search_docs({ query: "keyword" })\n```\n\n**Doc Organization:**\n| Type | Location |\n|------|----------|\n| Core docs | Root `.knowns/docs/` (no folder param) |\n| Categorized | `.knowns/docs/<folder>/` (use folder param) |\n\n### Time\n```\nmcp__knowns__start_time({ taskId: "<id>" })\nmcp__knowns__stop_time({ taskId: "<id>" })\nmcp__knowns__add_time({ taskId: "<id>", duration: "2h", note: "Note" })\nmcp__knowns__get_time_report({})\n```\n\n### Board\n```\nmcp__knowns__get_board({})\n```\n\n## REFS\n\n### Reading (output format)\n- `@.knowns/tasks/task-X - Title.md` \u2192 `mcp__knowns__get_task({ taskId: "X" })`\n- `@.knowns/docs/path/name.md` \u2192 `mcp__knowns__get_doc({ path: "path/name" })`\n\n### Writing (input format)\n- Task: `@task-X`\n- Doc: `@doc/path/name`\n\n## STATUS & PRIORITY\n\n**Status:** `todo`, `in-progress`, `in-review`, `blocked`, `done`\n**Priority:** `low`, `medium`, `high`\n\n## LONG CONTENT\n\nFor large docs, append in chunks:\n```\n# Create with initial content\nmcp__knowns__create_doc({ title: "Title", content: "## Overview\\n\\nIntro." })\n\n# Append sections\nmcp__knowns__update_doc({ path: "name", appendContent: "## Section 1\\n\\n..." })\nmcp__knowns__update_doc({ path: "name", appendContent: "## Section 2\\n\\n..." })\n```\n<!-- KNOWNS GUIDELINES END -->\n';
+// src/templates/instruction/mcp.md
+var mcp_default = '# Knowns Project\n\nThis project uses **Knowns MCP** tools for task and documentation management.\n\n## Before Starting\n\nCall this MCP tool to get usage guidelines:\n\n```\nmcp__knowns__get_guideline({})\n```\n\nYou MUST call this at session start and follow every rule it returns.\n\n## Context-Specific Guidelines\n\nGet guidelines for specific contexts:\n\n```\n// Full guidelines\nmcp__knowns__get_guideline({ type: "unified" })\n\n// CLI-specific (fallback)\nmcp__knowns__get_guideline({ type: "cli" })\n\n// MCP-specific\nmcp__knowns__get_guideline({ type: "mcp" })\n```\n\n**CLI Fallback:** If MCP tools are unavailable, use CLI commands:\n\n```bash\nknowns agents guideline --full      # All guidelines\nknowns agents guideline --stage creation    # Task creation\nknowns agents guideline --stage execution   # Task execution\nknowns agents guideline --stage completion  # Task completion\n```\n\n## Quick Tools\n\n```\n// List tasks\nmcp__knowns__list_tasks({})\n\n// View task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n// List docs\nmcp__knowns__list_docs({})\n\n// View doc\nmcp__knowns__get_doc({ path: "<path>" })\n\n// Search\nmcp__knowns__search_tasks({ query: "keyword" })\nmcp__knowns__search_docs({ query: "keyword" })\n```\n\n**Important:** Always read the guidelines before working on tasks.\n';
 
-// src/templates/mcp/general.md
-var general_default2 = '<!-- KNOWNS GUIDELINES START -->\n# Knowns MCP Guidelines\n\n## Core Principles\n\n### 1. MCP Tool Operations\n**Use MCP tools for ALL Knowns operations. NEVER edit .md files directly.**\n\nThis ensures data integrity, maintains proper change history, and prevents file corruption.\n\n### 2. Documentation-First (For AI Agents)\n**ALWAYS read project documentation BEFORE planning or coding.**\n\nAI agents must understand project context, conventions, and existing patterns before making any changes. This prevents rework and ensures consistency.\n\n---\n\n## AI Agent Guidelines\n\n> **CRITICAL**: Before performing ANY task, AI agents MUST read documentation to understand project context.\n\n### First-Time Initialization\n\nWhen starting a new session or working on an unfamiliar project:\n\n```\n# 1. List all available documentation\nmcp__knowns__list_docs({})\n\n# 2. Read essential project docs (prioritize these)\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\nmcp__knowns__get_doc({ path: "API" })\n\n# 3. Review current task backlog\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\n```\n\n### Before Taking Any Task\n\n```\n# 1. View the task details\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# 2. Follow ALL refs in the task (see Reference System section)\n# @.knowns/tasks/task-44 - ... \u2192 mcp__knowns__get_task({ taskId: "44" })\n# @.knowns/docs/patterns/module.md \u2192 mcp__knowns__get_doc({ path: "patterns/module" })\n\n# 3. Search for additional related documentation\nmcp__knowns__search_docs({ query: "<keywords from task>" })\n\n# 4. Read ALL related docs before planning\nmcp__knowns__get_doc({ path: "<related-doc>" })\n\n# 5. Check for similar completed tasks (learn from history)\nmcp__knowns__search_tasks({ query: "<keywords>", status: "done" })\n```\n\n### Why Documentation First?\n\n| Without Reading Docs | With Reading Docs |\n|---------------------|-------------------|\n| Reinvent existing patterns | Reuse established patterns |\n| Break conventions | Follow project standards |\n| Duplicate code | Use existing utilities |\n| Wrong architecture decisions | Align with system design |\n| Inconsistent naming | Match naming conventions |\n\n### Context Checklist for Agents\n\nBefore writing ANY code, ensure you can answer:\n\n- [ ] Have I followed ALL refs (`@.knowns/...`) in the task?\n- [ ] Have I followed nested refs recursively?\n- [ ] What is the project\'s overall architecture?\n- [ ] What coding conventions does this project follow?\n- [ ] Are there existing patterns/utilities I should reuse?\n- [ ] What are the testing requirements?\n- [ ] How should I structure my implementation?\n\n> **Remember**: A few minutes reading docs saves hours of rework. NEVER skip this step.\n\n---\n\n## Reference System (Refs)\n\nTasks and docs can contain **references** to other tasks/docs. AI agents MUST understand and follow these refs to gather complete context.\n\n### Reference Formats\n\n| Type | When Writing (Input) | When Reading (Output) | MCP Tool |\n|------|---------------------|----------------------|----------|\n| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `mcp__knowns__get_task({ taskId: "<id>" })` |\n| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `mcp__knowns__get_doc({ path: "<path>" })` |\n\n> **CRITICAL for AI Agents**:\n> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`\n> - When **READING** output: You\'ll see `@.knowns/tasks/...` and `@.knowns/docs/...`\n> - **NEVER write** the output format (`@.knowns/...`) - always use input format\n\n### How to Follow Refs\n\nWhen you read a task and see refs in system output format, follow them:\n\n```\n# Example: Task 42 output contains:\n# @.knowns/tasks/task-44 - CLI Task Create Command.md\n# @.knowns/docs/patterns/module.md\n\n# Follow task ref (extract ID from task-<id>)\nmcp__knowns__get_task({ taskId: "44" })\n\n# Follow doc ref (extract path, remove .md)\nmcp__knowns__get_doc({ path: "patterns/module" })\n```\n\n### Recursive Following\n\nRefs can be nested. Follow until complete context is gathered:\n\n```\nTask 42\n  \u2192 @.knowns/docs/README.md\n    \u2192 @.knowns/docs/patterns/module.md (found in README)\n      \u2192 (read for full pattern details)\n```\n\n> **CRITICAL**: Never assume you understand a task fully without following its refs. Refs contain essential context that may change your implementation approach.\n\n---\n\n## Quick Start\n\n```\n# Initialize project (use CLI for this)\nknowns init [name]\n\n# Create task with acceptance criteria\nmcp__knowns__create_task({\n  title: "Title",\n  description: "Description",\n  priority: "high",\n  labels: ["label1", "label2"]\n})\n\n# View task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# List tasks\nmcp__knowns__list_tasks({})\n\n# Search (tasks + docs)\nmcp__knowns__search_tasks({ query: "query" })\nmcp__knowns__search_docs({ query: "query" })\n```\n\n---\n\n## End-to-End Example\n\nHere\'s a complete workflow for an AI agent implementing a feature:\n\n```\n# === AGENT SESSION START (Do this once per session) ===\n\n# 0a. List all available documentation\nmcp__knowns__list_docs({})\n\n# 0b. Read essential project docs\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\n\n# Now the agent understands project context and conventions\n\n# === TASK WORKFLOW ===\n\n# 1. Create the task\nmcp__knowns__create_task({\n  title: "Add password reset flow",\n  description: "Users need ability to reset forgotten passwords via email",\n  priority: "high",\n  labels: ["auth", "feature"]\n})\n\n# Output: Created task 42\n\n# 2. Take the task and start timer\nmcp__knowns__update_task({\n  taskId: "42",\n  status: "in-progress",\n  assignee: "@howznguyen"\n})\nmcp__knowns__start_time({ taskId: "42" })\n\n# 3. Search for related documentation\nmcp__knowns__search_docs({ query: "password security" })\n\n# 4. Read the documentation\nmcp__knowns__get_doc({ path: "security-patterns" })\n\n# 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)\nmcp__knowns__update_task({\n  taskId: "42",\n  plan: "1. Review security patterns (see @doc/security-patterns)\\n2. Design token generation with 1-hour expiry\\n3. Implement /forgot-password endpoint\\n4. Add unit tests"\n})\n\n# 6. After approval, implement and update task progressively\nmcp__knowns__update_task({\n  taskId: "42",\n  appendNotes: "\u2713 Implemented /forgot-password endpoint"\n})\n\n# 7. Add final implementation notes\nmcp__knowns__update_task({\n  taskId: "42",\n  notes: "## Summary\\nImplemented complete password reset flow.\\n\\n## Changes\\n- Added POST /forgot-password endpoint\\n- Added POST /reset-password endpoint"\n})\n\n# 8. Stop timer and complete\nmcp__knowns__stop_time({ taskId: "42" })\nmcp__knowns__update_task({\n  taskId: "42",\n  status: "done"\n})\n```\n\n---\n\n## Task Workflow\n\n### Step 1: Take Task\n\n```\n# Update task status and assign to self\nmcp__knowns__update_task({\n  taskId: "<id>",\n  status: "in-progress",\n  assignee: "@<your-username>"\n})\n```\n\n> **Note**: Use your username as configured in the project. Check project config for `defaultAssignee`.\n\n### Step 2: Start Time Tracking (REQUIRED)\n\n```\nmcp__knowns__start_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:\n> - Accurate project estimation\n> - Identifying bottlenecks\n> - Resource planning\n> - Sprint retrospectives\n\n### Step 3: Read Related Documentation\n\n> **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.\n\n```\n# Search for related docs\nmcp__knowns__search_docs({ query: "authentication" })\n\n# View relevant documents\nmcp__knowns__get_doc({ path: "API Guidelines" })\nmcp__knowns__get_doc({ path: "Security Patterns" })\n\n# Also check for similar completed tasks\nmcp__knowns__search_tasks({ query: "auth", status: "done" })\n```\n\n> **CRITICAL**: ALWAYS read related documentation BEFORE planning!\n\n### Step 4: Create Implementation Plan\n\n```\nmcp__knowns__update_task({\n  taskId: "<id>",\n  plan: "1. Research patterns (see @doc/security-patterns)\\n2. Design middleware\\n3. Implement\\n4. Add tests\\n5. Update docs"\n})\n```\n\n> **CRITICAL**:\n> - Share plan with user and **WAIT for approval** before coding\n> - Include doc references using `@doc/<path>` format\n\n### Step 5: Implement\n\n```\n# Work through implementation plan step by step\n# IMPORTANT: Only update task AFTER completing the work, not before\n\n# After completing work, append notes:\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u2713 Completed: <brief description>"\n})\n```\n\n> **CRITICAL**: Never claim work is done before it\'s actually completed.\n\n### Step 6: Handle Dynamic Requests (During Implementation)\n\nIf the user adds new requirements during implementation:\n\n```\n# Append note about scope change\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u26A0\uFE0F Scope updated: Added requirement for X per user request"\n})\n\n# Continue with Step 5 (Implement) for new requirements\n```\n\n> **Note**: Always document scope changes. This helps track why a task took longer than expected.\n\n### Step 7: Add Implementation Notes\n\n```\n# Add comprehensive notes (suitable for PR description)\nmcp__knowns__update_task({\n  taskId: "<id>",\n  notes: "## Summary\\n\\nImplemented JWT auth.\\n\\n## Changes\\n- Added middleware\\n- Added tests"\n})\n\n# OR append progressively (recommended)\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u2713 Implemented middleware"\n})\n```\n\n### Step 8: Stop Time Tracking (REQUIRED)\n\n```\nmcp__knowns__stop_time({ taskId: "<id>" })\n```\n\n> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry:\n> `mcp__knowns__add_time({ taskId: "<id>", duration: "2h", note: "Forgot to stop timer" })`\n\n### Step 9: Complete Task\n\n```\nmcp__knowns__update_task({\n  taskId: "<id>",\n  status: "done"\n})\n```\n\n### Step 10: Handle Post-Completion Changes (If Applicable)\n\nIf the user requests changes or updates AFTER task is marked done:\n\n```\n# 1. Reopen task - set back to in-progress\nmcp__knowns__update_task({\n  taskId: "<id>",\n  status: "in-progress"\n})\n\n# 2. Restart time tracking (REQUIRED)\nmcp__knowns__start_time({ taskId: "<id>" })\n\n# 3. Document the reopen reason\nmcp__knowns__update_task({\n  taskId: "<id>",\n  appendNotes: "\u{1F504} Reopened: User requested changes - <reason>"\n})\n\n# 4. Follow Step 5-9 again (Implement \u2192 Notes \u2192 Stop Timer \u2192 Done)\n```\n\n> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:\n> - Reopen task (in-progress)\n> - Start timer again\n> - Document why it was reopened\n> - Follow the same completion process\n\n### Step 11: Knowledge Extraction (Post-Completion)\n\nAfter completing a task, extract reusable knowledge to docs:\n\n```\n# Search if similar pattern already documented\nmcp__knowns__search_docs({ query: "<pattern/concept>" })\n\n# If new knowledge, create a doc for future reference\nmcp__knowns__create_doc({\n  title: "Pattern: <Name>",\n  description: "Reusable pattern discovered during task implementation",\n  tags: ["pattern", "<domain>"],\n  folder: "patterns"\n})\n\n# Or append to existing doc\nmcp__knowns__update_doc({\n  path: "<existing-doc>",\n  appendContent: "## New Section\\n\\nLearned from task <id>: ..."\n})\n```\n\n**When to extract knowledge:**\n- New patterns/conventions discovered\n- Common error solutions\n- Reusable code snippets or approaches\n- Integration patterns with external services\n- Performance optimization techniques\n\n> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.\n\n---\n\n## Essential MCP Tools\n\n### Task Management\n\n```\n# Create task\nmcp__knowns__create_task({\n  title: "Title",\n  description: "Description",\n  priority: "high",        # low, medium, high\n  labels: ["label1"],\n  status: "todo",          # todo, in-progress, in-review, done, blocked\n  assignee: "@username"\n})\n\n# Get task\nmcp__knowns__get_task({ taskId: "<id>" })\n\n# Update task\nmcp__knowns__update_task({\n  taskId: "<id>",\n  title: "New title",\n  description: "New description",\n  status: "in-progress",\n  priority: "high",\n  assignee: "@username",\n  labels: ["new", "labels"],\n  plan: "Implementation plan...",\n  notes: "Implementation notes...",\n  appendNotes: "Append to existing notes..."\n})\n\n# List tasks\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress" })\nmcp__knowns__list_tasks({ assignee: "@username" })\nmcp__knowns__list_tasks({ priority: "high" })\nmcp__knowns__list_tasks({ label: "feature" })\n\n# Search tasks\nmcp__knowns__search_tasks({ query: "auth" })\n```\n\n### Time Tracking\n\n```\n# Start timer\nmcp__knowns__start_time({ taskId: "<id>" })\n\n# Stop timer\nmcp__knowns__stop_time({ taskId: "<id>" })\n\n# Manual entry\nmcp__knowns__add_time({\n  taskId: "<id>",\n  duration: "2h",           # e.g., "2h", "30m", "1h30m"\n  note: "Optional note",\n  date: "2025-12-25"        # Optional, defaults to now\n})\n\n# Reports\nmcp__knowns__get_time_report({})\nmcp__knowns__get_time_report({\n  from: "2025-12-01",\n  to: "2025-12-31",\n  groupBy: "task"           # task, label, status\n})\n```\n\n### Documentation\n\n```\n# List docs\nmcp__knowns__list_docs({})\nmcp__knowns__list_docs({ tag: "architecture" })\n\n# Get doc\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "patterns/module" })\n\n# Create doc\nmcp__knowns__create_doc({\n  title: "Title",\n  description: "Description",\n  tags: ["tag1", "tag2"],\n  folder: "folder/path",    # Optional\n  content: "Initial content..."\n})\n\n# Update doc\nmcp__knowns__update_doc({\n  path: "doc-name",\n  title: "New Title",\n  description: "New description",\n  tags: ["new", "tags"],\n  content: "Replace content...",\n  appendContent: "Append to content..."\n})\n\n# Search docs\nmcp__knowns__search_docs({ query: "patterns" })\nmcp__knowns__search_docs({ query: "auth", tag: "security" })\n```\n\n#### Doc Organization\n\n| Doc Type | Location | Example |\n|----------|----------|---------|\n| **Important/Core docs** | Root `.knowns/docs/` | `README.md`, `ARCHITECTURE.md`, `CONVENTIONS.md` |\n| **Guides** | `.knowns/docs/guides/` | `guides/getting-started.md` |\n| **Patterns** | `.knowns/docs/patterns/` | `patterns/controller.md` |\n| **API docs** | `.knowns/docs/api/` | `api/endpoints.md` |\n| **Other categorized docs** | `.knowns/docs/<category>/` | `security/auth-patterns.md` |\n\n```\n# Important docs - at root (no folder)\nmcp__knowns__create_doc({ title: "README", description: "Project overview", tags: ["core"] })\nmcp__knowns__create_doc({ title: "ARCHITECTURE", description: "System design", tags: ["core"] })\n\n# Categorized docs - use folder\nmcp__knowns__create_doc({ title: "Getting Started", description: "Setup guide", tags: ["guide"], folder: "guides" })\nmcp__knowns__create_doc({ title: "Controller Pattern", description: "MVC pattern", tags: ["pattern"], folder: "patterns" })\n```\n\n### Board\n\n```\n# Get kanban board view\nmcp__knowns__get_board({})\n```\n\n---\n\n## Task Structure\n\n### Title\n\nClear summary (WHAT needs to be done).\n\n| Bad | Good |\n|-----|------|\n| Do auth stuff | Add JWT authentication |\n| Fix bug | Fix login timeout on slow networks |\n| Update docs | Document rate limiting in API.md |\n\n### Description\n\nExplains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**\n\n```\nWe need JWT authentication because sessions don\'t scale for our microservices architecture.\n\nRelated docs: @doc/security-patterns, @doc/api-guidelines\n```\n\n### Acceptance Criteria\n\n**Outcome-oriented**, testable criteria. NOT implementation steps.\n\n| Bad (Implementation details) | Good (Outcomes) |\n|------------------------------|-----------------|\n| Add function handleLogin() in auth.ts | User can login and receive JWT token |\n| Use bcrypt for hashing | Passwords are securely hashed |\n| Add try-catch blocks | Errors return appropriate HTTP status codes |\n\n---\n\n## Definition of Done\n\nA task is **Done** ONLY when **ALL** criteria are met:\n\n### Via MCP Tools (Required)\n\n- [ ] All work completed and verified\n- [ ] Implementation notes added via `update_task`\n- [ ] \u23F1\uFE0F Timer stopped: `mcp__knowns__stop_time` (MANDATORY - do not skip!)\n- [ ] Status set to done via `update_task`\n- [ ] Knowledge extracted to docs (if applicable)\n\n### Via Code (Required)\n\n- [ ] All tests pass\n- [ ] Documentation updated\n- [ ] Code reviewed (linting, formatting)\n- [ ] No regressions introduced\n\n---\n\n## Status & Priority Reference\n\n### Status Values\n\n| Status | Description | When to Use |\n|--------|-------------|-------------|\n| `todo` | Not started | Default for new tasks |\n| `in-progress` | Currently working | After taking task |\n| `in-review` | In code review | PR submitted |\n| `blocked` | Waiting on dependency | External blocker |\n| `done` | Completed | All criteria met |\n\n### Priority Values\n\n| Priority | Description |\n|----------|-------------|\n| `low` | Can wait, nice-to-have |\n| `medium` | Normal priority (default) |\n| `high` | Urgent, time-sensitive |\n\n---\n\n## Common Mistakes\n\n| Wrong | Right |\n|-------|-------|\n| Edit .md files directly | Use MCP tools |\n| Skip time tracking | ALWAYS use `start_time` and `stop_time` |\n| Start coding without reading docs | Read ALL related docs FIRST |\n| Plan without checking docs | Read docs before planning |\n| Code before plan approval | Share plan, WAIT for approval |\n| Mark done without all criteria | Verify ALL criteria first |\n| Ignore refs in task description | Follow ALL refs before planning |\n| Follow only first-level refs | Recursively follow nested refs |\n\n---\n\n## Long Content Handling\n\nFor long documentation content, append in chunks:\n\n```\n# 1. Create doc with initial content\nmcp__knowns__create_doc({\n  title: "Doc Title",\n  content: "## Overview\\n\\nShort intro."\n})\n\n# 2. Append each section separately\nmcp__knowns__update_doc({\n  path: "doc-title",\n  appendContent: "## Section 1\\n\\nContent for section 1..."\n})\n\nmcp__knowns__update_doc({\n  path: "doc-title",\n  appendContent: "## Section 2\\n\\nContent for section 2..."\n})\n```\n\n> **Tip**: Each `appendContent` adds content after existing content. Use this for large docs to avoid context limits.\n\n---\n\n## Best Practices Checklist\n\n### For AI Agents: Session Start\n\n- [ ] List all docs: `mcp__knowns__list_docs({})`\n- [ ] Read README/ARCHITECTURE docs\n- [ ] Understand coding conventions\n- [ ] Review current task backlog\n\n### Before Starting Work\n\n- [ ] Task details retrieved: `mcp__knowns__get_task`\n- [ ] ALL refs in task followed\n- [ ] Nested refs recursively followed\n- [ ] Related docs searched and read\n- [ ] Similar done tasks reviewed for patterns\n- [ ] Task assigned to self via `update_task`\n- [ ] Status set to in-progress\n- [ ] Timer started: `mcp__knowns__start_time`\n\n### During Work\n\n- [ ] Implementation plan created and approved\n- [ ] Doc links included in plan: `@doc/<path>`\n- [ ] Progress notes appended: `appendNotes`\n\n### After Work\n\n- [ ] All work verified complete\n- [ ] Implementation notes added\n- [ ] Timer stopped: `mcp__knowns__stop_time`\n- [ ] Tests passing\n- [ ] Documentation updated\n- [ ] Status set to done\n- [ ] Knowledge extracted to docs (if applicable)\n\n---\n\n## Quick Reference\n\n```\n# === AGENT INITIALIZATION (Once per session) ===\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "README" })\nmcp__knowns__get_doc({ path: "ARCHITECTURE" })\nmcp__knowns__get_doc({ path: "CONVENTIONS" })\n\n# === FULL WORKFLOW ===\nmcp__knowns__create_task({ title: "Title", description: "Description" })\nmcp__knowns__update_task({ taskId: "<id>", status: "in-progress", assignee: "@me" })\nmcp__knowns__start_time({ taskId: "<id>" })                    # \u23F1\uFE0F REQUIRED\nmcp__knowns__search_docs({ query: "keyword" })\nmcp__knowns__get_doc({ path: "Doc Name" })\nmcp__knowns__search_tasks({ query: "keyword", status: "done" }) # Learn from history\nmcp__knowns__update_task({ taskId: "<id>", plan: "1. Step\\n2. Step" })\n# ... wait for approval, then implement ...\nmcp__knowns__update_task({ taskId: "<id>", appendNotes: "\u2713 Completed: feature X" })\nmcp__knowns__stop_time({ taskId: "<id>" })                     # \u23F1\uFE0F REQUIRED\nmcp__knowns__update_task({ taskId: "<id>", status: "done" })\n# Optional: Extract knowledge to docs if generalizable patterns found\n\n# === VIEW & SEARCH ===\nmcp__knowns__get_task({ taskId: "<id>" })\nmcp__knowns__list_tasks({})\nmcp__knowns__list_tasks({ status: "in-progress", assignee: "@me" })\nmcp__knowns__search_tasks({ query: "bug" })\nmcp__knowns__search_docs({ query: "pattern" })\n\n# === TIME TRACKING ===\nmcp__knowns__start_time({ taskId: "<id>" })\nmcp__knowns__stop_time({ taskId: "<id>" })\nmcp__knowns__add_time({ taskId: "<id>", duration: "2h" })\nmcp__knowns__get_time_report({})\n\n# === DOCUMENTATION ===\nmcp__knowns__list_docs({})\nmcp__knowns__get_doc({ path: "path/doc-name" })\nmcp__knowns__create_doc({ title: "Title", description: "Desc", tags: ["tag"] })\nmcp__knowns__update_doc({ path: "doc-name", appendContent: "New content" })\n```\n\n---\n\n**Maintained By**: Knowns CLI Team\n\n<!-- KNOWNS GUIDELINES END -->\n';
+// src/templates/instruction/index.ts
+var START_MARKER = "<!-- KNOWNS GUIDELINES START -->";
+var END_MARKER = "<!-- KNOWNS GUIDELINES END -->";
+function withMarkers(template) {
+  return `${START_MARKER}
+${template.trim()}
+${END_MARKER}`;
+}
+var CLI_TEMPLATE_RAW = cli_default.trim();
+var MCP_TEMPLATE_RAW = mcp_default.trim();
+var CLI_INSTRUCTION = withMarkers(cli_default);
+var MCP_INSTRUCTION = withMarkers(mcp_default);
 
 // src/commands/agents.ts
 var PROJECT_ROOT = process.cwd();
@@ -43495,11 +43592,11 @@ var INSTRUCTION_FILES = [
   { path: "GEMINI.md", name: "Gemini", selected: false },
   { path: ".github/copilot-instructions.md", name: "GitHub Copilot", selected: false }
 ];
-function getGuidelines(type, variant = "general") {
-  if (type === "mcp") {
-    return variant === "gemini" ? gemini_default2 : general_default2;
+function getGuidelines(type, variant = "instruction") {
+  if (variant === "general") {
+    return Guidelines.getFull(true);
   }
-  return variant === "gemini" ? gemini_default : general_default;
+  return type === "mcp" ? MCP_INSTRUCTION : CLI_INSTRUCTION;
 }
 async function updateInstructionFile(filePath, guidelines) {
   const fullPath = join3(PROJECT_ROOT, filePath);
@@ -43530,11 +43627,11 @@ ${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("--gemini", "Use compact Gemini variant (smaller context)").option("--files <files>", "Comma-separated list of files to update").action(async (options2) => {
+var agentsCommand = new Command("agents").description("Manage agent instruction files (CLAUDE.md, GEMINI.md, etc.)").enablePositionalOptions().passThroughOptions().option("--update-instructions", "Update agent instruction files (non-interactive)").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--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 = options2.gemini ? "gemini" : "general";
+      const variant = "general";
       const guidelines2 = getGuidelines(type, variant);
       let filesToUpdate = INSTRUCTION_FILES;
       if (options2.files) {
@@ -43543,7 +43640,7 @@ var agentsCommand = new Command("agents").description("Manage agent instruction
           (f) => requestedFiles.includes(f.path) || requestedFiles.includes(f.name)
         );
       }
-      const label2 = `${type.toUpperCase()}${variant === "gemini" ? " (Gemini)" : ""}`;
+      const label2 = `${type.toUpperCase()}`;
       console.log(source_default.bold(`
 Updating agent instruction files (${label2})...
 `));
@@ -43579,14 +43676,14 @@ Updating agent instruction files (${label2})...
       message: "Select variant:",
       choices: [
         {
-          title: "General (Full)",
-          value: "general",
-          description: "Complete guidelines for Claude, GPT, etc."
+          title: "Minimal (Recommended)",
+          value: "instruction",
+          description: "Just tells AI to call `knowns agents guideline` for rules"
         },
         {
-          title: "Gemini (Compact)",
-          value: "gemini",
-          description: "Condensed version for Gemini 2.5 Flash (smaller context)"
+          title: "Full (Embedded)",
+          value: "general",
+          description: "Complete guidelines embedded in file"
         }
       ],
       initial: 0
@@ -43610,7 +43707,8 @@ Updating agent instruction files (${label2})...
       console.log(source_default.yellow("\n\u26A0\uFE0F  No files selected"));
       return;
     }
-    const label = `${typeResponse.type.toUpperCase()}${variantResponse.variant === "gemini" ? " (Gemini)" : ""}`;
+    const variantLabel = variantResponse.variant === "instruction" ? " (minimal)" : " (full)";
+    const label = `${typeResponse.type.toUpperCase()}${variantLabel}`;
     const confirmResponse = await (0, import_prompts.default)({
       type: "confirm",
       name: "confirm",
@@ -43677,13 +43775,14 @@ async function updateFiles(files, guidelines) {
   }
   console.log();
 }
-var syncCommand = new Command("sync").description("Sync/update all agent instruction files with latest guidelines").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--gemini", "Use compact Gemini variant (smaller context)").option("--all", "Update all instruction files (including Gemini, Copilot)").action(async (options2) => {
+var syncCommand = new Command("sync").description("Sync/update all agent instruction files with latest guidelines").option("--type <type>", "Guidelines type: cli or mcp", "cli").option("--full", "Use full embedded guidelines (default: minimal instruction)").option("--all", "Update all instruction files (including Gemini, Copilot)").action(async (options2) => {
   try {
     const type = options2.type === "mcp" ? "mcp" : "cli";
-    const variant = options2.gemini ? "gemini" : "general";
+    const variant = options2.full ? "general" : "instruction";
     const guidelines = getGuidelines(type, variant);
     const filesToUpdate = options2.all ? INSTRUCTION_FILES : INSTRUCTION_FILES.filter((f) => f.selected);
-    const label = `${type.toUpperCase()}${variant === "gemini" ? " (Gemini)" : ""}`;
+    const variantLabel = variant === "instruction" ? " (minimal)" : " (full)";
+    const label = `${type.toUpperCase()}${variantLabel}`;
     console.log(source_default.bold(`
 Syncing agent instructions (${label})...
 `));
@@ -43694,6 +43793,46 @@ Syncing agent instructions (${label})...
   }
 });
 agentsCommand.addCommand(syncCommand);
+var guidelineCommand = new Command("guideline").description("Output guidelines for AI agents (use this at session start)").option("--cli", "Show CLI-specific guidelines (legacy)").option("--mcp", "Show MCP-specific guidelines (legacy)").option("--full", "Show full guidelines (all sections)").option("--compact", "Show compact guidelines (core + mistakes only)").option("--stage <stage>", "Show guidelines for specific stage: creation, execution, completion").option("--core", "Show core rules only").option("--commands", "Show commands reference only").option("--mistakes", "Show common mistakes only").action(
+  async (options2) => {
+    try {
+      if (options2.cli || options2.mcp) {
+        console.log(Guidelines.getFull());
+        return;
+      }
+      if (options2.core) {
+        console.log(Guidelines.core);
+        return;
+      }
+      if (options2.commands) {
+        console.log(Guidelines.commands);
+        return;
+      }
+      if (options2.mistakes) {
+        console.log(Guidelines.mistakes);
+        return;
+      }
+      if (options2.compact) {
+        console.log(Guidelines.getCompact());
+        return;
+      }
+      if (options2.stage) {
+        const stage = options2.stage;
+        if (!["creation", "execution", "completion"].includes(stage)) {
+          console.error("Error: Invalid stage. Use: creation, execution, or completion");
+          process.exit(1);
+        }
+        console.log(Guidelines.getForStage(stage));
+        return;
+      }
+      console.log(Guidelines.getFull());
+    } catch (error48) {
+      console.error("Error:", error48 instanceof Error ? error48.message : String(error48));
+      process.exit(1);
+    }
+  }
+);
+agentsCommand.addCommand(guidelineCommand);
 
 // src/commands/init.ts
 function checkGitExists(projectRoot) {
@@ -70412,6 +70551,39 @@ async function handleSearchDocs(args2) {
   });
 }
 
+// src/mcp/handlers/guideline.ts
+var getGuidelineSchema = external_exports.object({
+  type: external_exports.enum(["unified", "cli", "mcp"]).optional().default("unified")
+});
+var guidelineTools = [
+  {
+    name: "get_guideline",
+    description: "Get usage guidelines for Knowns CLI/MCP. Call this at session start to understand how to use the tools correctly.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["unified", "cli", "mcp"],
+          description: "Type of guidelines: unified (default, covers both), cli (CLI only), mcp (MCP only)"
+        }
+      }
+    }
+  }
+];
+async function handleGetGuideline(args2) {
+  const input = getGuidelineSchema.parse(args2 || {});
+  const guidelines = Guidelines.getFull();
+  return {
+    content: [
+      {
+        type: "text",
+        text: guidelines
+      }
+    ]
+  };
+}
+
 // src/mcp/server.ts
 var fileStore = new FileStore(process.cwd());
 var server = new Server(
@@ -70426,7 +70598,7 @@ var server = new Server(
     }
   }
 );
-var tools = [...taskTools, ...timeTools, ...boardTools, ...docTools];
+var tools = [...taskTools, ...timeTools, ...boardTools, ...docTools, ...guidelineTools];
 server.setRequestHandler(ListToolsRequestSchema, async () => {
   return { tools };
 });
@@ -70468,6 +70640,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         return await handleUpdateDoc(args2);
       case "search_docs":
         return await handleSearchDocs(args2);
+      // Guideline handler
+      case "get_guideline":
+        return await handleGetGuideline(args2);
       default:
         return errorResponse(`Unknown tool: ${name}`);
     }
@@ -70773,8 +70948,8 @@ async function notifyCliUpdate(options2) {
 // package.json
 var package_default = {
   name: "knowns",
-  version: "0.8.1",
-  description: "CLI tool for dev teams to manage tasks and documentation",
+  version: "0.8.3",
+  description: "AI-native task and documentation management for dev teams",
   module: "index.ts",
   type: "module",
   bin: {
@@ -70784,7 +70959,6 @@ var package_default = {
   main: "./dist/index.js",
   files: [
     "dist",
-    "CLAUDE.md",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
@@ -70806,7 +70980,7 @@ var package_default = {
     type: "git",
     url: "https://github.com/knowns-dev/knowns.git"
   },
-  homepage: "https://knowns.dev",
+  homepage: "https://cli.knowns.dev",
   bugs: {
     url: "https://github.com/knowns-dev/knowns/issues"
   },