knowns 0.10.1 → 0.10.3

package/dist/index.js

@@ -58829,7 +58829,7 @@ function evaluateCondition(condition, context) {
 var commands_reference_default = '{{#if mcp}}\n# MCP Tools Reference\n\n## Task Tools\n\n### mcp__knowns__create_task\n\n```json\n{\n  "title": "Task title",\n  "description": "Task description",\n  "status": "todo",\n  "priority": "medium",\n  "labels": ["label1"],\n  "assignee": "@me",\n  "parent": "parent-id"\n}\n```\n\n### mcp__knowns__update_task\n\n```json\n{\n  "taskId": "<id>",\n  "status": "in-progress",\n  "assignee": "@me",\n  "addAc": ["Criterion 1", "Criterion 2"],\n  "checkAc": [1, 2],\n  "uncheckAc": [3],\n  "removeAc": [4],\n  "plan": "1. Step one\\n2. Step two",\n  "notes": "Implementation notes",\n  "appendNotes": "Additional notes"\n}\n```\n\n| Field | Purpose |\n|-------|---------|\n| `addAc` | Add new acceptance criteria |\n| `checkAc` | Mark AC done (1-based index) |\n| `uncheckAc` | Unmark AC (1-based index) |\n| `removeAc` | Remove AC (1-based index) |\n| `plan` | Set implementation plan |\n| `notes` | Replace implementation notes |\n| `appendNotes` | Append to notes |\n\n### mcp__knowns__get_task\n\n```json\n{ "taskId": "<id>" }\n```\n\n### mcp__knowns__list_tasks\n\n```json\n{ "status": "in-progress", "assignee": "@me" }\n```\n\n### mcp__knowns__search_tasks\n\n```json\n{ "query": "keyword" }\n```\n\n---\n\n## Doc Tools\n\n### mcp__knowns__get_doc\n\n**ALWAYS use `smart: true`** - auto-handles small/large docs:\n\n```json\n{ "path": "readme", "smart": true }\n```\n\nIf large, returns TOC. Then read section:\n```json\n{ "path": "readme", "section": "3" }\n```\n\n### mcp__knowns__list_docs\n\n```json\n{ "tag": "api" }\n```\n\n### mcp__knowns__create_doc\n\n```json\n{\n  "title": "Doc Title",\n  "description": "Description",\n  "tags": ["tag1"],\n  "folder": "guides",\n  "content": "Initial content"\n}\n```\n\n### mcp__knowns__update_doc\n\n```json\n{\n  "path": "readme",\n  "content": "Replace content",\n  "section": "2"\n}\n```\n\n### mcp__knowns__search_docs\n\n```json\n{ "query": "keyword", "tag": "api" }\n```\n\n### mcp__knowns__search (Unified)\n\n```json\n{\n  "query": "keyword",\n  "type": "all",\n  "status": "in-progress",\n  "priority": "high",\n  "assignee": "@me",\n  "label": "feature",\n  "tag": "api",\n  "limit": 20\n}\n```\n\n| Field | Purpose |\n|-------|---------|\n| `type` | "all", "task", or "doc" |\n| `status/priority/assignee/label` | Task filters |\n| `tag` | Doc filter |\n| `limit` | Max results (default: 20) |\n\n---\n\n## Time Tools\n\n### mcp__knowns__start_time\n\n```json\n{ "taskId": "<id>" }\n```\n\n### mcp__knowns__stop_time\n\n```json\n{ "taskId": "<id>" }\n```\n\n### mcp__knowns__add_time\n\n```json\n{\n  "taskId": "<id>",\n  "duration": "2h30m",\n  "note": "Note",\n  "date": "2025-01-15"\n}\n```\n\n### mcp__knowns__get_time_report\n\n```json\n{ "from": "2025-01-01", "to": "2025-01-31", "groupBy": "task" }\n```\n\n---\n\n## Template Tools\n\n### mcp__knowns__list_templates\n\n```json\n{}\n```\n\n### mcp__knowns__get_template\n\n```json\n{ "name": "template-name" }\n```\n\n### mcp__knowns__run_template\n\n```json\n{\n  "name": "template-name",\n  "variables": { "name": "MyComponent" },\n  "dryRun": true\n}\n```\n\n### mcp__knowns__create_template\n\n```json\n{\n  "name": "my-template",\n  "description": "Description",\n  "doc": "patterns/my-pattern"\n}\n```\n\n---\n\n## Other\n\n### mcp__knowns__get_board\n\n```json\n{}\n```\n\n{{else}}\n# CLI Commands Reference\n\n## task create\n\n```bash\nknowns task create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Task description |\n| `--ac` | | Acceptance criterion (repeatable) |\n| `--labels` | `-l` | Comma-separated labels |\n| `--assignee` | `-a` | Assign to user |\n| `--priority` | | low/medium/high |\n| `--parent` | | Parent task ID (raw ID only!) |\n\n**`-a` = assignee, NOT acceptance criteria! Use `--ac` for AC.**\n\n---\n\n## task edit\n\n```bash\nknowns task edit <id> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--status` | `-s` | Change status |\n| `--assignee` | `-a` | Assign user |\n| `--ac` | | Add acceptance criterion |\n| `--check-ac` | | Mark AC done (1-indexed) |\n| `--uncheck-ac` | | Unmark AC |\n| `--plan` | | Set implementation plan |\n| `--notes` | | Replace notes |\n| `--append-notes` | | Add to notes |\n\n---\n\n## task view/list\n\n```bash\nknowns task <id> --plain\nknowns task list --plain\nknowns task list --status in-progress --plain\nknowns task list --tree --plain\n```\n\n---\n\n## doc create\n\n```bash\nknowns doc create <title> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--description` | `-d` | Description |\n| `--tags` | `-t` | Comma-separated tags |\n| `--folder` | `-f` | Folder path |\n\n---\n\n## doc edit\n\n```bash\nknowns doc edit <name> [options]\n```\n\n| Flag | Short | Purpose |\n|------|-------|---------|\n| `--content` | `-c` | Replace content |\n| `--append` | `-a` | Append content |\n| `--section` | | Target section (use with -c) |\n\n**In doc edit, `-a` = append content, NOT assignee!**\n\n---\n\n## doc view/list\n\n**ALWAYS use `--smart`** - auto-handles small/large docs:\n\n```bash\nknowns doc <path> --plain --smart\n```\n\nIf large, returns TOC. Then read section:\n```bash\nknowns doc <path> --plain --section 3\n```\n\n```bash\nknowns doc list --plain\nknowns doc list --tag api --plain\n```\n\n---\n\n## time\n\n```bash\nknowns time start <id>    # REQUIRED when taking task\nknowns time stop          # REQUIRED when completing\nknowns time status\nknowns time add <id> <duration> -n "Note"\n```\n\n---\n\n## search\n\n```bash\nknowns search "query" --plain\nknowns search "auth" --type task --plain\nknowns search "api" --type doc --plain\n```\n\n---\n\n## template\n\n```bash\nknowns template list\nknowns template info <name>\nknowns template run <name> --name "X" --dry-run\nknowns template create <name>\n```\n\n---\n\n## Multi-line Input\n\n```bash\nknowns task edit <id> --plan $\'1. Step\\n2. Step\\n3. Step\'\n```\n{{/if}}\n';
 
 // src/instructions/guidelines/unified/common-mistakes.md
-var common_mistakes_default = '# Common Mistakes\n\n{{#unless mcp}}\n## CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n{{/unless}}\n\n## Quick Reference\n\n| DON\'T | DO |\n|-------|-----|\n{{#if mcp}}\n| Edit .md files directly | Use MCP tools |\n{{else}}\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n{{/if}}\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always start/stop timer |\n| Ignore refs | Follow ALL `@task-xxx`, `@doc/xxx`, `@template/xxx` refs |\n\n{{#if mcp}}\n---\n\n## MCP Task Operations\n\nAll task operations are available via MCP:\n\n| Operation | MCP Field |\n|-----------|-----------|\n| Add acceptance criteria | `addAc: ["criterion"]` |\n| Check AC | `checkAc: [1, 2]` (1-based) |\n| Uncheck AC | `uncheckAc: [1]` (1-based) |\n| Remove AC | `removeAc: [1]` (1-based) |\n| Set plan | `plan: "..."` |\n| Set notes | `notes: "..."` |\n| Append notes | `appendNotes: "..."` |\n| Change status | `status: "in-progress"` |\n| Assign | `assignee: "@me"` |\n{{/if}}\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n{{#if mcp}}\n| Forgot to stop timer | `mcp__knowns__add_time` with duration |\n| Wrong status | `mcp__knowns__update_task` to fix |\n| Task not found | `mcp__knowns__list_tasks` to find ID |\n| Need to uncheck AC | `mcp__knowns__update_task` with `uncheckAc: [N]` |\n| Checked AC too early | `mcp__knowns__update_task` with `uncheckAc: [N]` |\n{{else}}\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n{{/if}}\n';
+var common_mistakes_default = '# Common Mistakes\n\n{{#unless mcp}}\n## CRITICAL: The -a Flag\n\n| Command | `-a` Means | NOT This! |\n|---------|------------|-----------|\n| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |\n| `doc edit` | `--append` | ~~assignee~~ |\n\n```bash\n# WRONG (sets assignee to garbage!)\nknowns task edit 35 -a "Criterion text"\n\n# CORRECT (use --ac)\nknowns task edit 35 --ac "Criterion text"\n```\n\n---\n{{/unless}}\n\n## Quick Reference\n\n| DON\'T | DO |\n|-------|-----|\n{{#if mcp}}\n| Edit .md files directly | Use MCP tools |\n{{else}}\n| Edit .md files directly | Use CLI commands |\n| `-a "criterion"` | `--ac "criterion"` |\n| `--parent task-48` | `--parent 48` (raw ID) |\n| `--plain` with create/edit | `--plain` only for view/list |\n{{/if}}\n| Check AC before work done | Check AC AFTER work done |\n| Code before plan approval | Wait for user approval |\n| Code before reading docs | Read docs FIRST |\n| Skip time tracking | Always start/stop timer |\n| Ignore refs | Follow ALL `@task-xxx`, `@doc/xxx`, `@template/xxx` refs |\n\n{{#if mcp}}\n---\n\n## MCP Task Operations\n\nAll task operations are available via MCP:\n\n| Operation | MCP Field |\n|-----------|-----------|\n| Add acceptance criteria | `addAc: ["criterion"]` |\n| Check AC | `checkAc: [1, 2]` (1-based) |\n| Uncheck AC | `uncheckAc: [1]` (1-based) |\n| Remove AC | `removeAc: [1]` (1-based) |\n| Set plan | `plan: "..."` |\n| Set notes | `notes: "..."` |\n| Append notes | `appendNotes: "..."` |\n| Change status | `status: "in-progress"` |\n| Assign | `assignee: "@me"` |\n{{/if}}\n\n---\n\n## Template Syntax Pitfalls\n\nWhen writing `.hbs` templates, **NEVER** create `$` followed by triple-brace - Handlebars interprets triple-brace as unescaped output:\n\n```\n// \u274C WRONG - Parse error!\nthis.logger.log(`Created: $` + `{` + `{` + `{camelCase entity}.id}`);\n\n// \u2705 CORRECT - Add space between ${ and double-brace, use ~ to trim whitespace\nthis.logger.log(`Created: ${ \\{{~camelCase entity~}}.id}`);\n```\n\n| DON\'T | DO |\n|-------|-----|\n| `$` + triple-brace | `${ \\{{~helper~}}}` (space + escaped) |\n\n**Rules:**\n- Add space between `${` and double-brace\n- Use `~` (tilde) to trim whitespace in output\n- Escape literal braces with backslash\n\n---\n\n## Error Recovery\n\n| Problem | Solution |\n|---------|----------|\n{{#if mcp}}\n| Forgot to stop timer | `mcp__knowns__add_time` with duration |\n| Wrong status | `mcp__knowns__update_task` to fix |\n| Task not found | `mcp__knowns__list_tasks` to find ID |\n| Need to uncheck AC | `mcp__knowns__update_task` with `uncheckAc: [N]` |\n| Checked AC too early | `mcp__knowns__update_task` with `uncheckAc: [N]` |\n{{else}}\n| Set assignee to AC text | `knowns task edit <id> -a @me` |\n| Forgot to stop timer | `knowns time add <id> <duration>` |\n| Checked AC too early | `knowns task edit <id> --uncheck-ac N` |\n| Task not found | `knowns task list --plain` |\n{{/if}}\n';
 
 // src/instructions/guidelines/unified/context-optimization.md
 var context_optimization_default = '# Context Optimization\n\nOptimize your context usage to work more efficiently within token limits.\n\n---\n\n{{#unless mcp}}\n## Output Format\n\n```bash\n# Verbose output\nknowns task 42 --json\n\n# Compact output (always use --plain)\nknowns task 42 --plain\n```\n\n---\n{{/unless}}\n\n## Search Before Read\n\n{{#if mcp}}\n```json\n// DON\'T: Read all docs hoping to find info\nmcp__knowns__get_doc({ "path": "doc1" })\nmcp__knowns__get_doc({ "path": "doc2" })\n\n// DO: Search first, then read only relevant docs\nmcp__knowns__search_docs({ "query": "authentication" })\nmcp__knowns__get_doc({ "path": "security-patterns" })\n```\n{{else}}\n```bash\n# DON\'T: Read all docs hoping to find info\nknowns doc "doc1" --plain\nknowns doc "doc2" --plain\n\n# DO: Search first, then read only relevant docs\nknowns search "authentication" --type doc --plain\nknowns doc "security-patterns" --plain\n```\n{{/if}}\n\n---\n\n{{#if mcp}}\n## Use Filters\n\n```json\n// DON\'T: List all then filter manually\nmcp__knowns__list_tasks({})\n\n// DO: Use filters in the query\nmcp__knowns__list_tasks({\n  "status": "in-progress",\n  "assignee": "@me"\n})\n```\n\n---\n{{/if}}\n\n## Reading Documents\n\n{{#if mcp}}\n**ALWAYS use `smart: true`** - auto-handles both small and large docs:\n\n```json\n// DON\'T: Read without smart\nmcp__knowns__get_doc({ "path": "readme" })\n\n// DO: Always use smart\nmcp__knowns__get_doc({ "path": "readme", "smart": true })\n// Small doc \u2192 full content\n// Large doc \u2192 stats + TOC\n\n// If large, read specific section:\nmcp__knowns__get_doc({ "path": "readme", "section": "3" })\n```\n{{else}}\n**ALWAYS use `--smart`** - auto-handles both small and large docs:\n\n```bash\n# DON\'T: Read without --smart\nknowns doc readme --plain\n\n# DO: Always use --smart\nknowns doc readme --plain --smart\n# Small doc \u2192 full content\n# Large doc \u2192 stats + TOC\n\n# If large, read specific section:\nknowns doc readme --plain --section 3\n```\n{{/if}}\n\n**Behavior:**\n- **\u22642000 tokens**: Returns full content automatically\n- **>2000 tokens**: Returns stats + TOC, then use section parameter\n\n---\n\n## Compact Notes\n\n```bash\n# DON\'T: Verbose notes\nknowns task edit 42 --append-notes "I have successfully completed the implementation..."\n\n# DO: Compact notes\nknowns task edit 42 --append-notes "Done: Auth middleware + JWT validation"\n```\n\n---\n\n## Avoid Redundant Operations\n\n| Don\'t | Do Instead |\n|-------|------------|\n| Re-read files already in context | Reference from memory |\n| List tasks/docs multiple times | List once, remember results |\n| Quote entire file contents | Summarize key points |\n\n---\n\n## Efficient Workflow\n\n| Phase | Context-Efficient Approach |\n|-------|---------------------------|\n| **Research** | Search \u2192 Read only matches |\n| **Planning** | Brief plan, not detailed prose |\n| **Coding** | Read only files being modified |\n| **Notes** | Bullet points, not paragraphs |\n| **Completion** | Summary, not full log |\n\n---\n\n## Quick Rules\n\n{{#if mcp}}\n1. **Always `smart: true`** - Auto-handles doc size\n{{else}}\n1. **Always `--plain`** - Never use `--json` unless needed\n2. **Always `--smart`** - Auto-handles doc size\n{{/if}}\n3. **Search first** - Don\'t read all docs hoping to find info\n4. **Read selectively** - Only fetch what you need\n5. **Write concise** - Compact notes, not essays\n6. **Don\'t repeat** - Reference context already loaded\n';
@@ -59011,7 +59011,7 @@ var SKILL_default9 = '---\nname: knowns.task.reopen\ndescription: Use when reope
 var SKILL_default10 = '---\nname: knowns.task\ndescription: Use when working on a Knowns task - view task details and decide next action\n---\n\n# Working on a Task\n\nView task details and determine the appropriate next action.\n\n**Announce at start:** "I\'m using the knowns.task skill to view task [ID]."\n\n**Core principle:** VIEW AND ROUTE - analyze state, suggest next skill.\n\n## The Process\n\n### Step 1: View Task\n\n{{#if mcp}}\n```json\nmcp__knowns__get_task({ "taskId": "$ARGUMENTS" })\n```\n{{else}}\n```bash\nknowns task $ARGUMENTS --plain\n```\n{{/if}}\n\n### Step 2: Analyze State\n\nCheck:\n- **Status**: todo, in-progress, done?\n- **Assignee**: Assigned to someone?\n- **AC**: Any checked? All checked?\n- **Plan**: Has implementation plan?\n- **Refs**: Any `@doc/` or `@task-` references?\n\n### Step 3: Suggest Next Action\n\nBased on task state, recommend the appropriate skill:\n\n| State | Next Skill |\n|-------|------------|\n| `todo`, not started | `knowns.task.plan` |\n| `in-progress`, no plan | `knowns.task.plan` |\n| `in-progress`, has plan | `knowns.task.implement` |\n| `done`, needs changes | `knowns.task.reopen` |\n| Requirements unclear | `knowns.task.brainstorm` |\n\n### Step 4: Follow Refs (if needed)\n\nIf task has references, follow them for context:\n\n{{#if mcp}}\n```json\n// Doc ref: @doc/path \u2192\nmcp__knowns__get_doc({ "path": "<path>", "smart": true })\n\n// Task ref: @task-<id> \u2192\nmcp__knowns__get_task({ "taskId": "<id>" })\n```\n{{else}}\n```bash\n# Doc ref: @doc/path \u2192\nknowns doc "<path>" --plain\n\n# Task ref: @task-<id> \u2192\nknowns task <id> --plain\n```\n{{/if}}\n\n## Quick Actions\n\n**Start planning (includes taking ownership):**\n```\n/knowns.task.plan $ARGUMENTS\n```\n\n**Continue implementing:**\n```\n/knowns.task.implement $ARGUMENTS\n```\n\n**Requirements unclear:**\n```\n/knowns.task.brainstorm $ARGUMENTS\n```\n\n**Reopen completed task:**\n```\n/knowns.task.reopen $ARGUMENTS\n```\n\n## Remember\n\n- This skill is for viewing and routing\n- Use `plan` to start a new task (takes ownership, starts timer)\n- Use `implement` to continue/complete in-progress tasks\n- Always follow refs for full context\n';
 
 // src/instructions/skills/knowns.template/SKILL.md
-var SKILL_default11 = '---\nname: knowns.template\ndescription: Use when generating code from templates - list, run, or create templates\n---\n\n# Working with Templates\n\nGenerate code from predefined templates stored in `.knowns/templates/`.\n\n**Announce at start:** "I\'m using the knowns.template skill to work with templates."\n\n**Core principle:** USE TEMPLATES FOR CONSISTENT CODE GENERATION.\n\n## The Process\n\n### Step 1: List Available Templates\n\n{{#if mcp}}\n```json\nmcp__knowns__list_templates({})\n```\n{{else}}\n```bash\nknowns template list\n```\n{{/if}}\n\n### Step 2: Get Template Details\n\n{{#if mcp}}\n```json\nmcp__knowns__get_template({ "name": "<template-name>" })\n```\n{{else}}\n```bash\nknowns template info <template-name>\n```\n{{/if}}\n\nCheck:\n- Required variables (prompts)\n- Linked documentation (`doc:`)\n- Files that will be generated\n\n### Step 3: Read Linked Documentation\n\nIf template has a `doc:` field, read it first:\n\n{{#if mcp}}\n```json\nmcp__knowns__get_doc({ "path": "<doc-path>", "smart": true })\n```\n{{else}}\n```bash\nknowns doc "<doc-path>" --plain\n```\n{{/if}}\n\n### Step 4: Run Template\n\n{{#if mcp}}\n```json\n// Dry run first (preview)\nmcp__knowns__run_template({\n  "name": "<template-name>",\n  "variables": { "name": "MyComponent", "type": "page" },\n  "dryRun": true\n})\n\n// Then run for real\nmcp__knowns__run_template({\n  "name": "<template-name>",\n  "variables": { "name": "MyComponent", "type": "page" },\n  "dryRun": false\n})\n```\n{{else}}\n```bash\n# Dry run (preview)\nknowns template run <template-name> --name "MyComponent" --dry-run\n\n# Run for real\nknowns template run <template-name> --name "MyComponent"\n```\n{{/if}}\n\n### Step 5: Create New Template\n\n{{#if mcp}}\n```json\nmcp__knowns__create_template({\n  "name": "<template-name>",\n  "description": "Template description",\n  "doc": "patterns/<related-doc>"  // Optional: link to documentation\n})\n```\n{{else}}\n```bash\nknowns template create <template-name>\n```\n{{/if}}\n\nThis creates:\n```\n.knowns/templates/<template-name>/\n  \u251C\u2500\u2500 _template.yaml    # Config\n  \u2514\u2500\u2500 example.ts.hbs    # Example file\n```\n\n## Template Config (`_template.yaml`)\n\n```yaml\nname: react-component\ndescription: Create a React component with tests\ndoc: patterns/react-component    # Link to documentation\n\nprompts:\n  - name: name\n    message: Component name?\n    validate: required\n\n  - name: type\n    message: Component type?\n    type: select\n    choices:\n      - page\n      - component\n      - layout\n\nfiles:\n  - template: "{{name}}.tsx.hbs"\n    destination: "src/components/{{pascalCase name}}/{{pascalCase name}}.tsx"\n\n  - template: "{{name}}.test.tsx.hbs"\n    destination: "src/components/{{pascalCase name}}/{{pascalCase name}}.test.tsx"\n    condition: "{{includeTests}}"\n```\n\n## Template-Doc Linking\n\nTemplates can reference docs and vice versa:\n\n**In `_template.yaml`:**\n```yaml\ndoc: patterns/react-component\n```\n\n**In doc (markdown):**\n```markdown\nUse @template/react-component to generate.\n```\n\n**AI workflow:**\n1. Get template config\n2. Follow `doc:` link to understand patterns\n3. Run template with appropriate variables\n\n## Handlebars Helpers\n\nTemplates use Handlebars with built-in helpers:\n\n| Helper | Example | Output |\n|--------|---------|--------|\n| `camelCase` | `{{camelCase "my name"}}` | `myName` |\n| `pascalCase` | `{{pascalCase "my name"}}` | `MyName` |\n| `kebabCase` | `{{kebabCase "MyName"}}` | `my-name` |\n| `snakeCase` | `{{snakeCase "MyName"}}` | `my_name` |\n| `upperCase` | `{{upperCase "name"}}` | `NAME` |\n| `lowerCase` | `{{lowerCase "NAME"}}` | `name` |\n\n## When to Use Templates\n\n| Scenario | Action |\n|----------|--------|\n| Creating new component | Run `react-component` template |\n| Adding API endpoint | Run `api-endpoint` template |\n| Setting up new feature | Run `feature-module` template |\n| Consistent file structure | Use template instead of copy-paste |\n\n## Integrated Workflows\n\n### During Implementation (Use Template)\n\n```\nTask \u2192 Read Context \u2192 Find Template \u2192 Generate Code \u2192 Customize\n```\n\n1. Read task and understand requirements\n2. List templates to find applicable one\n3. Get template details and read linked doc\n4. Run template (dry run first, then real)\n5. Customize generated code as needed\n6. Continue with remaining implementation\n\n**Benefits:**\n- Reduces context (no need to generate boilerplate)\n- Ensures consistency with project patterns\n- Faster implementation\n\n### During Extract (Create Template)\n\n```\nContext \u2192 Identify Pattern \u2192 Create Doc \u2192 Create Template \u2192 Link Both\n```\n\n1. Identify repeatable code pattern\n2. Create doc with `/knowns.extract`\n3. Create template with `knowns template create <name>`\n4. Link template to doc: `doc: patterns/<name>`\n5. Link doc to template: `@template/<name>`\n\n**When to create template:**\n- Pattern will be used multiple times\n- Has consistent file structure\n- Can be parameterized\n\n## Checklist\n\n- [ ] Listed available templates\n- [ ] Got template details (prompts, files)\n- [ ] Read linked documentation (if any)\n- [ ] Understood required variables\n- [ ] Ran dry run first\n- [ ] Ran template with correct inputs\n- [ ] Verified generated files\n\n## Remember\n\n- Always dry run first before writing files\n- Check `doc:` link in template for context\n- Templates ensure consistent code structure\n- Create new templates for repeated patterns\n';
+var SKILL_default11 = '---\nname: knowns.template\ndescription: Use when generating code from templates - list, run, or create templates\n---\n\n# Working with Templates\n\nGenerate code from predefined templates stored in `.knowns/templates/`.\n\n**Announce at start:** "I\'m using the knowns.template skill to work with templates."\n\n**Core principle:** USE TEMPLATES FOR CONSISTENT CODE GENERATION.\n\n## The Process\n\n### Step 1: List Available Templates\n\n{{#if mcp}}\n```json\nmcp__knowns__list_templates({})\n```\n{{else}}\n```bash\nknowns template list\n```\n{{/if}}\n\n### Step 2: Get Template Details\n\n{{#if mcp}}\n```json\nmcp__knowns__get_template({ "name": "<template-name>" })\n```\n{{else}}\n```bash\nknowns template info <template-name>\n```\n{{/if}}\n\nCheck:\n- Required variables (prompts)\n- Linked documentation (`doc:`)\n- Files that will be generated\n\n### Step 3: Read Linked Documentation\n\nIf template has a `doc:` field, read it first:\n\n{{#if mcp}}\n```json\nmcp__knowns__get_doc({ "path": "<doc-path>", "smart": true })\n```\n{{else}}\n```bash\nknowns doc "<doc-path>" --plain\n```\n{{/if}}\n\n### Step 4: Run Template\n\n{{#if mcp}}\n```json\n// Dry run first (preview)\nmcp__knowns__run_template({\n  "name": "<template-name>",\n  "variables": { "name": "MyComponent", "type": "page" },\n  "dryRun": true\n})\n\n// Then run for real\nmcp__knowns__run_template({\n  "name": "<template-name>",\n  "variables": { "name": "MyComponent", "type": "page" },\n  "dryRun": false\n})\n```\n{{else}}\n```bash\n# Dry run (preview)\nknowns template run <template-name> --name "MyComponent" --dry-run\n\n# Run for real\nknowns template run <template-name> --name "MyComponent"\n```\n{{/if}}\n\n### Step 5: Create New Template\n\n{{#if mcp}}\n```json\nmcp__knowns__create_template({\n  "name": "<template-name>",\n  "description": "Template description",\n  "doc": "patterns/<related-doc>"  // Optional: link to documentation\n})\n```\n{{else}}\n```bash\nknowns template create <template-name>\n```\n{{/if}}\n\nThis creates:\n```\n.knowns/templates/<template-name>/\n  \u251C\u2500\u2500 _template.yaml    # Config\n  \u2514\u2500\u2500 example.ts.hbs    # Example file\n```\n\n## Template Config (`_template.yaml`)\n\n```yaml\nname: react-component\ndescription: Create a React component with tests\ndoc: patterns/react-component    # Link to documentation\n\nprompts:\n  - name: name\n    message: Component name?\n    validate: required\n\n  - name: type\n    message: Component type?\n    type: select\n    choices:\n      - page\n      - component\n      - layout\n\nfiles:\n  - template: "{{name}}.tsx.hbs"\n    destination: "src/components/{{pascalCase name}}/{{pascalCase name}}.tsx"\n\n  - template: "{{name}}.test.tsx.hbs"\n    destination: "src/components/{{pascalCase name}}/{{pascalCase name}}.test.tsx"\n    condition: "{{includeTests}}"\n```\n\n## Template-Doc Linking\n\nTemplates can reference docs and vice versa:\n\n**In `_template.yaml`:**\n```yaml\ndoc: patterns/react-component\n```\n\n**In doc (markdown):**\n```markdown\nUse @template/react-component to generate.\n```\n\n**AI workflow:**\n1. Get template config\n2. Follow `doc:` link to understand patterns\n3. Run template with appropriate variables\n\n## Handlebars Helpers\n\nTemplates use Handlebars with built-in helpers:\n\n| Helper | Example | Output |\n|--------|---------|--------|\n| `camelCase` | `{{camelCase "my name"}}` | `myName` |\n| `pascalCase` | `{{pascalCase "my name"}}` | `MyName` |\n| `kebabCase` | `{{kebabCase "MyName"}}` | `my-name` |\n| `snakeCase` | `{{snakeCase "MyName"}}` | `my_name` |\n| `upperCase` | `{{upperCase "name"}}` | `NAME` |\n| `lowerCase` | `{{lowerCase "NAME"}}` | `name` |\n\n## CRITICAL: Template Syntax Pitfalls\n\n### JavaScript Template Literals + Handlebars\n\n**NEVER write `$` followed by triple-brace** - Handlebars interprets triple-brace as unescaped output:\n\n```\n// \u274C WRONG - Parse error!\nthis.logger.log(`Created: $` + `\\{{\\{camelCase entity}.id}`);\n\n// \u2705 CORRECT - Add space, use ~ to trim whitespace\nthis.logger.log(`Created: ${ \\{{~camelCase entity~}}.id}`);\n// Output: this.logger.log(`Created: ${product.id}`);\n```\n\n**Rules when writing .hbs templates:**\n1. Never `$` + triple-brace - always add space: `${ \\{{`\n2. Use `~` (tilde) to trim whitespace: `\\{{~helper~}}`\n3. For literal braces, escape with backslash\n\n## When to Use Templates\n\n| Scenario | Action |\n|----------|--------|\n| Creating new component | Run `react-component` template |\n| Adding API endpoint | Run `api-endpoint` template |\n| Setting up new feature | Run `feature-module` template |\n| Consistent file structure | Use template instead of copy-paste |\n\n## Integrated Workflows\n\n### During Implementation (Use Template)\n\n```\nTask \u2192 Read Context \u2192 Find Template \u2192 Generate Code \u2192 Customize\n```\n\n1. Read task and understand requirements\n2. List templates to find applicable one\n3. Get template details and read linked doc\n4. Run template (dry run first, then real)\n5. Customize generated code as needed\n6. Continue with remaining implementation\n\n**Benefits:**\n- Reduces context (no need to generate boilerplate)\n- Ensures consistency with project patterns\n- Faster implementation\n\n### During Extract (Create Template)\n\n```\nContext \u2192 Identify Pattern \u2192 Create Doc \u2192 Create Template \u2192 Link Both\n```\n\n1. Identify repeatable code pattern\n2. Create doc with `/knowns.extract`\n3. Create template with `knowns template create <name>`\n4. Link template to doc: `doc: patterns/<name>`\n5. Link doc to template: `@template/<name>`\n\n**When to create template:**\n- Pattern will be used multiple times\n- Has consistent file structure\n- Can be parameterized\n\n## Checklist\n\n- [ ] Listed available templates\n- [ ] Got template details (prompts, files)\n- [ ] Read linked documentation (if any)\n- [ ] Understood required variables\n- [ ] Ran dry run first\n- [ ] Ran template with correct inputs\n- [ ] Verified generated files\n\n## Remember\n\n- Always dry run first before writing files\n- Check `doc:` link in template for context\n- Templates ensure consistent code structure\n- Create new templates for repeated patterns\n- **NEVER write `$` + triple-brace** - use `${ \\{{~helper~}}` instead (add space, use tilde)\n';
 
 // src/instructions/skills/index.ts
 function parseSkillFrontmatter(content) {
@@ -61849,22 +61849,25 @@ var searchCommand = new Command("search").description("Search tasks and document
             const pathGroups = {};
             for (const doc of docResults) {
               const parts = doc.filename.split("/");
-              const folder = parts.length > 1 ? `${parts.slice(0, -1).join("/")}/` : "(root)";
+              const folder = parts.length > 1 ? `${parts.slice(0, -1).join("/")}/` : "";
               if (!pathGroups[folder]) {
                 pathGroups[folder] = [];
               }
               pathGroups[folder].push(doc);
             }
             const sortedPaths = Object.keys(pathGroups).sort((a, b) => {
-              if (a === "(root)") return -1;
-              if (b === "(root)") return 1;
+              if (a === "") return -1;
+              if (b === "") return 1;
               return a.localeCompare(b);
             });
             for (const path3 of sortedPaths) {
-              console.log(`  ${path3}:`);
+              if (path3) {
+                console.log(`  ${path3}:`);
+              }
+              const indent = path3 ? "    " : "  ";
               for (const doc of pathGroups[path3]) {
                 const filename = doc.filename.split("/").pop() || doc.filename;
-                console.log(`    ${filename} - ${doc.metadata.title}`);
+                console.log(`${indent}${filename} - ${doc.metadata.title}`);
               }
             }
           }
@@ -62482,6 +62485,7 @@ function createConfigRoutes(ctx) {
         name: data.name,
         id: data.id,
         createdAt: data.createdAt,
+        imports: data.imports,
         ...settings
       };
       if (!config2.visibleColumns) {
@@ -62501,10 +62505,13 @@ function createConfigRoutes(ctx) {
         const content = await readFile7(configPath, "utf-8");
         existingData = JSON.parse(content);
       }
-      const { name, ...settings } = config2;
+      const { name, imports, id, createdAt, ...settings } = config2;
       const merged = {
         ...existingData,
         name: name || existingData.name,
+        id: id || existingData.id,
+        createdAt: createdAt || existingData.createdAt,
+        imports: imports !== void 0 ? imports : existingData.imports,
         settings
       };
       await writeFile4(configPath, JSON.stringify(merged, null, 2), "utf-8");
@@ -63966,7 +63973,7 @@ async function importSource(projectRoot, source, options2 = {}) {
   if (!nameValidation.valid) {
     throw new ImportError(nameValidation.error || "Invalid name", "NAME_CONFLICT" /* NAME_CONFLICT */);
   }
-  if (!options2.force && await importExists(projectRoot, name)) {
+  if (!options2.force && !options2.isSync && await importExists(projectRoot, name)) {
     throw new ImportError(
       `Import "${name}" already exists`,
       "NAME_CONFLICT" /* NAME_CONFLICT */,
@@ -64144,8 +64151,10 @@ async function syncImport(projectRoot, name, options2 = {}) {
     exclude: config2.exclude,
     force: options2.force,
     dryRun: options2.dryRun,
-    noSave: true
+    noSave: true,
     // Don't update config on sync
+    isSync: true
+    // Bypass "already exists" check
   });
 }
 async function syncAllImports(projectRoot, options2 = {}) {
@@ -64153,7 +64162,7 @@ async function syncAllImports(projectRoot, options2 = {}) {
   const configs = await getImportConfigs2(projectRoot);
   const results = [];
   for (const config2 of configs) {
-    if (config2.autoSync === false && !options2.force) {
+    if (options2.autoOnly && config2.autoSync === false) {
       continue;
     }
     try {
@@ -64197,7 +64206,38 @@ import { existsSync as existsSync14 } from "node:fs";
 import { readdir as readdir7 } from "node:fs/promises";
 import { join as join17 } from "node:path";
 var KNOWNS_DIR5 = ".knowns";
+var TEMPLATES_DIR2 = "templates";
 var DOCS_DIR2 = "docs";
+async function getTemplateDirectories(projectRoot) {
+  const results = [];
+  const localTemplates = join17(projectRoot, KNOWNS_DIR5, TEMPLATES_DIR2);
+  if (existsSync14(localTemplates)) {
+    results.push({
+      path: localTemplates,
+      source: "local",
+      isImported: false
+    });
+  }
+  const importsDir = getImportsDir(projectRoot);
+  if (existsSync14(importsDir)) {
+    try {
+      const entries = await readdir7(importsDir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const importedTemplates = join17(importsDir, entry.name, TEMPLATES_DIR2);
+        if (existsSync14(importedTemplates)) {
+          results.push({
+            path: importedTemplates,
+            source: entry.name,
+            isImported: true
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  return results;
+}
 async function getDocDirectories(projectRoot) {
   const results = [];
   const localDocs = join17(projectRoot, KNOWNS_DIR5, DOCS_DIR2);
@@ -64300,8 +64340,36 @@ async function resolveDocWithContext(projectRoot, docPath, context) {
   }
   return null;
 }
+async function listAllTemplates(projectRoot) {
+  const directories = await getTemplateDirectories(projectRoot);
+  const importConfigs = await getImportConfigs(projectRoot);
+  const sourceUrlMap = new Map(importConfigs.map((c) => [c.name, c.source]));
+  const results = [];
+  for (const dir of directories) {
+    try {
+      const entries = await readdir7(dir.path, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name.startsWith(".")) continue;
+        const ref = dir.isImported ? `${dir.source}/${entry.name}` : entry.name;
+        results.push({
+          name: entry.name,
+          ref,
+          source: dir.source,
+          sourceUrl: dir.isImported ? sourceUrlMap.get(dir.source) : void 0,
+          path: join17(dir.path, entry.name),
+          isImported: dir.isImported
+        });
+      }
+    } catch {
+    }
+  }
+  return results.sort((a, b) => a.ref.localeCompare(b.ref));
+}
 async function listAllDocs(projectRoot) {
   const directories = await getDocDirectories(projectRoot);
+  const importConfigs = await getImportConfigs(projectRoot);
+  const sourceUrlMap = new Map(importConfigs.map((c) => [c.name, c.source]));
   const results = [];
   async function scanDir(baseDir, relativePath, source, isImported) {
     const currentDir = join17(baseDir, relativePath);
@@ -64319,6 +64387,7 @@ async function listAllDocs(projectRoot) {
             name: docPath,
             ref,
             source,
+            sourceUrl: isImported ? sourceUrlMap.get(source) : void 0,
             fullPath: join17(currentDir, entry.name),
             isImported
           });
@@ -87092,131 +87161,190 @@ var createCommand3 = new Command("create").description("Create a new documentati
     }
   }
 );
-var listCommand2 = new Command("list").description("List all documentation files").argument("[path]", "Filter by path (e.g., 'guides/' or 'patterns/')").option("--plain", "Plain text output for AI").option("-t, --tag <tag>", "Filter by tag").action(async (path3, options2) => {
-  try {
-    await ensureDocsDir();
-    const mdFiles = await getAllMdFiles(DOCS_DIR3);
-    if (mdFiles.length === 0) {
-      if (options2.plain) {
-        console.log("No documentation found");
-      } else {
-        console.log(source_default.yellow("No documentation files found."));
-        console.log(source_default.gray(`Create one with: knowns doc create "Title"`));
-      }
-      return;
-    }
-    const docs = [];
-    for (const file3 of mdFiles) {
-      const fileContent = await readFile18(join29(DOCS_DIR3, file3), "utf-8");
-      const { data, content } = (0, import_gray_matter7.default)(fileContent);
-      const stats = calculateDocStats(content);
-      docs.push({
-        filename: file3,
-        metadata: data,
-        tokens: stats.estimatedTokens
-      });
-    }
-    let filteredDocs = docs;
-    if (path3) {
-      const normalizedPath = path3.endsWith("/") ? path3 : `${path3}/`;
-      filteredDocs = docs.filter((doc) => doc.filename.startsWith(normalizedPath));
-    }
-    if (options2.tag) {
-      filteredDocs = filteredDocs.filter((doc) => doc.metadata.tags?.includes(options2.tag));
-    }
-    if (filteredDocs.length === 0) {
-      const filterMsg = path3 ? `path: ${path3}` : options2.tag ? `tag: ${options2.tag}` : "";
-      console.log(
-        options2.plain ? "No documentation found" : source_default.yellow(`No documentation found${filterMsg ? ` with ${filterMsg}` : ""}`)
-      );
-      return;
-    }
-    if (options2.plain) {
-      const folders = /* @__PURE__ */ new Map();
-      const rootDocs = [];
-      for (const doc of filteredDocs) {
-        const parts = doc.filename.split("/");
-        if (parts.length === 1) {
-          rootDocs.push({
-            name: parts[0].replace(/\.md$/, ""),
-            title: doc.metadata.title,
-            tokens: doc.tokens
-          });
+var listCommand2 = new Command("list").description("List all documentation files (local + imported)").argument("[path]", "Filter by path (e.g., 'guides/' or 'patterns/')").option("--plain", "Plain text output for AI").option("-t, --tag <tag>", "Filter by tag").option("--local", "Show only local docs").option("--imported", "Show only imported docs").action(
+  async (path3, options2) => {
+    try {
+      await ensureDocsDir();
+      const projectRoot = await findProjectRoot() || process.cwd();
+      const allDocs = await listAllDocs(projectRoot);
+      if (allDocs.length === 0) {
+        if (options2.plain) {
+          console.log("No documentation found");
         } else {
-          const folder = parts.slice(0, -1).join("/");
-          const name = parts[parts.length - 1].replace(/\.md$/, "");
-          if (!folders.has(folder)) {
-            folders.set(folder, []);
-          }
-          folders.get(folder)?.push({ name, title: doc.metadata.title, tokens: doc.tokens });
+          console.log(source_default.yellow("No documentation files found."));
+          console.log(source_default.gray(`Create one with: knowns doc create "Title"`));
         }
+        return;
       }
-      const sortedFolders = Array.from(folders.keys()).sort();
-      for (const folder of sortedFolders) {
-        console.log(`${folder}/`);
-        const docs2 = folders.get(folder)?.sort((a, b) => a.name.localeCompare(b.name));
-        for (const doc of docs2) {
-          console.log(`  ${doc.name} - ${doc.title} (~${doc.tokens} tokens)`);
+      const docs = [];
+      for (const doc of allDocs) {
+        try {
+          const fileContent = await readFile18(doc.fullPath, "utf-8");
+          const { data, content } = (0, import_gray_matter7.default)(fileContent);
+          const stats = calculateDocStats(content);
+          docs.push({
+            ref: doc.ref,
+            name: doc.name,
+            source: doc.source,
+            sourceUrl: doc.sourceUrl,
+            isImported: doc.isImported,
+            fullPath: doc.fullPath,
+            metadata: data,
+            tokens: stats.estimatedTokens
+          });
+        } catch {
         }
       }
-      if (rootDocs.length > 0) {
-        rootDocs.sort((a, b) => a.name.localeCompare(b.name));
-        for (const doc of rootDocs) {
-          console.log(`${doc.name} - ${doc.title} (~${doc.tokens} tokens)`);
-        }
+      let filteredDocs = docs;
+      if (options2.local) {
+        filteredDocs = docs.filter((doc) => !doc.isImported);
+      } else if (options2.imported) {
+        filteredDocs = docs.filter((doc) => doc.isImported);
       }
-    } else {
-      const folders = /* @__PURE__ */ new Map();
-      const rootDocs = [];
-      for (const doc of filteredDocs) {
-        const parts = doc.filename.split("/");
-        if (parts.length === 1) {
-          rootDocs.push(doc);
-        } else {
-          const folder = parts.slice(0, -1).join("/");
-          if (!folders.has(folder)) {
-            folders.set(folder, []);
+      if (path3) {
+        const normalizedPath = path3.endsWith("/") ? path3 : `${path3}/`;
+        filteredDocs = filteredDocs.filter(
+          (doc) => doc.ref.startsWith(normalizedPath) || doc.name.startsWith(normalizedPath)
+        );
+      }
+      if (options2.tag) {
+        filteredDocs = filteredDocs.filter((doc) => doc.metadata.tags?.includes(options2.tag));
+      }
+      if (filteredDocs.length === 0) {
+        const filterMsg = path3 ? `path: ${path3}` : options2.tag ? `tag: ${options2.tag}` : "";
+        console.log(
+          options2.plain ? "No documentation found" : source_default.yellow(`No documentation found${filterMsg ? ` with ${filterMsg}` : ""}`)
+        );
+        return;
+      }
+      if (options2.plain) {
+        const sources = /* @__PURE__ */ new Map();
+        for (const doc of filteredDocs) {
+          const sourceKey = doc.isImported ? `[${doc.source}]` : "[local]";
+          if (!sources.has(sourceKey)) {
+            sources.set(sourceKey, []);
+          }
+          sources.get(sourceKey)?.push(doc);
+        }
+        const sortedSources = Array.from(sources.keys()).sort((a, b) => {
+          if (a === "[local]") return -1;
+          if (b === "[local]") return 1;
+          return a.localeCompare(b);
+        });
+        for (const sourceKey of sortedSources) {
+          const sourceDocs = sources.get(sourceKey) || [];
+          const sourceUrl = sourceDocs[0]?.sourceUrl;
+          if (sourceUrl) {
+            console.log(`${sourceKey} (${sourceUrl})`);
+          } else {
+            console.log(`${sourceKey}`);
+          }
+          const folders = /* @__PURE__ */ new Map();
+          const rootDocs = [];
+          for (const doc of sourceDocs) {
+            const parts = doc.name.split("/");
+            if (parts.length === 1) {
+              rootDocs.push({
+                name: parts[0],
+                title: doc.metadata.title || parts[0],
+                tokens: doc.tokens
+              });
+            } else {
+              const folder = parts.slice(0, -1).join("/");
+              const name = parts[parts.length - 1];
+              if (!folders.has(folder)) {
+                folders.set(folder, []);
+              }
+              folders.get(folder)?.push({ name, title: doc.metadata.title || name, tokens: doc.tokens });
+            }
+          }
+          const sortedFolders = Array.from(folders.keys()).sort();
+          for (const folder of sortedFolders) {
+            console.log(`  ${folder}/`);
+            const folderDocs = folders.get(folder)?.sort((a, b) => a.name.localeCompare(b.name));
+            for (const doc of folderDocs || []) {
+              console.log(`    ${doc.name} - ${doc.title} (~${doc.tokens} tokens)`);
+            }
+          }
+          if (rootDocs.length > 0) {
+            rootDocs.sort((a, b) => a.name.localeCompare(b.name));
+            for (const doc of rootDocs) {
+              console.log(`  ${doc.name} - ${doc.title} (~${doc.tokens} tokens)`);
+            }
           }
-          folders.get(folder)?.push(doc);
         }
-      }
-      console.log(source_default.bold(`
+      } else {
+        const sources = /* @__PURE__ */ new Map();
+        for (const doc of filteredDocs) {
+          const sourceKey = doc.isImported ? doc.source : "local";
+          if (!sources.has(sourceKey)) {
+            sources.set(sourceKey, []);
+          }
+          sources.get(sourceKey)?.push(doc);
+        }
+        const sortedSources = Array.from(sources.keys()).sort((a, b) => {
+          if (a === "local") return -1;
+          if (b === "local") return 1;
+          return a.localeCompare(b);
+        });
+        console.log(source_default.bold(`
 Documentation (${filteredDocs.length})
 `));
-      const sortedFolders = Array.from(folders.keys()).sort();
-      for (const folder of sortedFolders) {
-        console.log(source_default.cyan.bold(`${folder}/`));
-        const docs2 = folders.get(folder)?.sort((a, b) => a.metadata.title.localeCompare(b.metadata.title));
-        for (const doc of docs2) {
-          console.log(source_default.white(`  ${doc.metadata.title}`));
-          if (doc.metadata.description) {
-            console.log(source_default.gray(`    ${doc.metadata.description}`));
-          }
-          if (doc.metadata.tags && doc.metadata.tags.length > 0) {
-            console.log(source_default.gray(`    Tags: ${doc.metadata.tags.join(", ")}`));
+        for (const sourceKey of sortedSources) {
+          const sourceDocs = sources.get(sourceKey) || [];
+          const sourceUrl = sourceDocs[0]?.sourceUrl;
+          const sourceLabel = sourceKey === "local" ? "Local" : `Import: ${sourceKey}`;
+          if (sourceUrl) {
+            console.log(source_default.magenta.bold(`[${sourceLabel}]`) + source_default.gray(` ${sourceUrl}`));
+          } else {
+            console.log(source_default.magenta.bold(`[${sourceLabel}]`));
+          }
+          const folders = /* @__PURE__ */ new Map();
+          const rootDocs = [];
+          for (const doc of sourceDocs) {
+            const parts = doc.name.split("/");
+            if (parts.length === 1) {
+              rootDocs.push(doc);
+            } else {
+              const folder = parts.slice(0, -1).join("/");
+              if (!folders.has(folder)) {
+                folders.set(folder, []);
+              }
+              folders.get(folder)?.push(doc);
+            }
           }
-        }
-        console.log();
-      }
-      if (rootDocs.length > 0) {
-        rootDocs.sort((a, b) => a.metadata.title.localeCompare(b.metadata.title));
-        for (const doc of rootDocs) {
-          console.log(source_default.white(`${doc.metadata.title}`));
-          if (doc.metadata.description) {
-            console.log(source_default.gray(`  ${doc.metadata.description}`));
+          const sortedFolders = Array.from(folders.keys()).sort();
+          for (const folder of sortedFolders) {
+            console.log(source_default.cyan.bold(`  ${folder}/`));
+            const folderDocs = folders.get(folder)?.sort((a, b) => (a.metadata.title || "").localeCompare(b.metadata.title || ""));
+            for (const doc of folderDocs || []) {
+              console.log(source_default.white(`    ${doc.metadata.title || doc.name}`));
+              if (doc.metadata.description) {
+                console.log(source_default.gray(`      ${doc.metadata.description}`));
+              }
+            }
           }
-          if (doc.metadata.tags && doc.metadata.tags.length > 0) {
-            console.log(source_default.gray(`  Tags: ${doc.metadata.tags.join(", ")}`));
+          if (rootDocs.length > 0) {
+            rootDocs.sort((a, b) => (a.metadata.title || "").localeCompare(b.metadata.title || ""));
+            for (const doc of rootDocs) {
+              console.log(source_default.white(`  ${doc.metadata.title || doc.name}`));
+              if (doc.metadata.description) {
+                console.log(source_default.gray(`    ${doc.metadata.description}`));
+              }
+            }
           }
           console.log();
         }
       }
+    } catch (error48) {
+      console.error(
+        source_default.red("Error listing documentation:"),
+        error48 instanceof Error ? error48.message : String(error48)
+      );
+      process.exit(1);
     }
-  } catch (error48) {
-    console.error(source_default.red("Error listing documentation:"), error48 instanceof Error ? error48.message : String(error48));
-    process.exit(1);
   }
-});
+);
 var viewCommand2 = new Command("view").description("View a documentation file").argument("<name>", "Document name (filename or title or path)").option("--plain", "Plain text output for AI").option("--info", "Show document stats (size, tokens, headings) without content").option("--toc", "Show table of contents only").option("--section <title>", "Show specific section by heading title or number (e.g., '2. Overview' or '2')").option("--smart", "Smart mode: auto-return full content if small, or stats+TOC if large (>2000 tokens)").action(
   async (name, options2) => {
     try {
@@ -96471,8 +96599,9 @@ async function resolveDocPath2(name) {
 async function handleListDocs(args2) {
   const input = listDocsSchema.parse(args2);
   await ensureDocsDir2();
-  const mdFiles = await getAllMdFiles2(DOCS_DIR4);
-  if (mdFiles.length === 0) {
+  const projectRoot = process.cwd();
+  const allDocs = await listAllDocs(projectRoot);
+  if (allDocs.length === 0) {
     return successResponse({
       count: 0,
       docs: [],
@@ -96480,22 +96609,29 @@ async function handleListDocs(args2) {
     });
   }
   const docs = [];
-  for (const file3 of mdFiles) {
-    const fileContent = await readFile21(join33(DOCS_DIR4, file3), "utf-8");
-    const { data, content } = (0, import_gray_matter9.default)(fileContent);
-    const metadata = data;
-    const stats = calculateDocStats(content);
-    if (input.tag && !metadata.tags?.includes(input.tag)) {
-      continue;
+  for (const doc of allDocs) {
+    try {
+      const fileContent = await readFile21(doc.fullPath, "utf-8");
+      const { data, content } = (0, import_gray_matter9.default)(fileContent);
+      const metadata = data;
+      const stats = calculateDocStats(content);
+      if (input.tag && !metadata.tags?.includes(input.tag)) {
+        continue;
+      }
+      docs.push({
+        path: doc.ref,
+        // Use full ref path (includes import prefix if imported)
+        title: metadata.title || doc.name,
+        description: metadata.description,
+        tags: metadata.tags,
+        tokens: stats.estimatedTokens,
+        updatedAt: metadata.updatedAt,
+        source: doc.source,
+        sourceUrl: doc.sourceUrl,
+        isImported: doc.isImported
+      });
+    } catch {
     }
-    docs.push({
-      path: file3.replace(/\.md$/, ""),
-      title: metadata.title || file3.replace(/\.md$/, ""),
-      description: metadata.description,
-      tags: metadata.tags,
-      tokens: stats.estimatedTokens,
-      updatedAt: metadata.updatedAt
-    });
   }
   return successResponse({
     count: docs.length,
@@ -96803,7 +96939,7 @@ async function handleGetGuideline(args2) {
 import { existsSync as existsSync29 } from "node:fs";
 import { mkdir as mkdir18, writeFile as writeFile16 } from "node:fs/promises";
 import { join as join34 } from "node:path";
-var TEMPLATES_DIR2 = join34(process.cwd(), ".knowns", "templates");
+var TEMPLATES_DIR3 = join34(process.cwd(), ".knowns", "templates");
 var listTemplatesSchema = external_exports.object({});
 var getTemplateSchema = external_exports.object({
   name: external_exports.string()
@@ -96896,30 +97032,45 @@ var templateTools = [
 ];
 async function handleListTemplates(_args) {
   listTemplatesSchema.parse(_args);
-  if (!existsSync29(TEMPLATES_DIR2)) {
-    return successResponse({
-      count: 0,
-      templates: [],
-      message: "No templates directory found. Create templates in .knowns/templates/"
-    });
-  }
+  const projectRoot = process.cwd();
   try {
-    const templates = await listTemplates(TEMPLATES_DIR2);
-    if (templates.length === 0) {
+    const allTemplates = await listAllTemplates(projectRoot);
+    if (allTemplates.length === 0) {
       return successResponse({
         count: 0,
         templates: [],
-        message: "No templates found in .knowns/templates/"
+        message: "No templates found. Create templates in .knowns/templates/"
       });
     }
-    const templateList = templates.map((t) => ({
-      name: t.name,
-      description: t.description,
-      doc: t.doc,
-      // Linked documentation
-      promptCount: t.prompts?.length || 0,
-      fileCount: t.files?.length || 0
-    }));
+    const templateList = [];
+    for (const t of allTemplates) {
+      try {
+        const loaded = await listTemplates(join34(t.path, ".."));
+        const match2 = loaded.find((l) => l.name === t.name);
+        templateList.push({
+          name: t.name,
+          ref: t.ref,
+          description: match2?.description || "No description",
+          doc: match2?.doc,
+          promptCount: match2?.prompts?.length || 0,
+          fileCount: match2?.files?.length || 0,
+          source: t.source,
+          sourceUrl: t.sourceUrl,
+          isImported: t.isImported
+        });
+      } catch {
+        templateList.push({
+          name: t.name,
+          ref: t.ref,
+          description: "No description",
+          promptCount: 0,
+          fileCount: 0,
+          source: t.source,
+          sourceUrl: t.sourceUrl,
+          isImported: t.isImported
+        });
+      }
+    }
     return successResponse({
       count: templateList.length,
       templates: templateList
@@ -96930,27 +97081,37 @@ async function handleListTemplates(_args) {
 }
 async function handleGetTemplate(args2) {
   const input = getTemplateSchema.parse(args2);
-  if (!existsSync29(TEMPLATES_DIR2)) {
+  if (!existsSync29(TEMPLATES_DIR3)) {
     return errorResponse("No templates directory found");
   }
   try {
-    const template = await loadTemplateByName(input.name, TEMPLATES_DIR2);
+    const template = await loadTemplateByName(TEMPLATES_DIR3, input.name);
     if (!template) {
       return errorResponse(`Template not found: ${input.name}`);
     }
     const prompts4 = template.config.prompts?.map((p) => ({
       name: p.name,
       message: p.message,
-      type: p.type || "input",
+      type: p.type || "text",
       required: p.validate === "required",
-      default: p.default,
+      default: p.initial,
       choices: p.choices
     }));
-    const files = template.config.files?.map((f) => ({
-      template: f.template,
-      destination: f.destination,
-      condition: f.condition
-    }));
+    const actions = template.config.actions?.map((a) => {
+      if (a.type === "add") {
+        return { type: a.type, template: a.template, path: a.path, skipIfExists: a.skipIfExists };
+      }
+      if (a.type === "addMany") {
+        return { type: a.type, source: a.source, destination: a.destination, globPattern: a.globPattern };
+      }
+      if (a.type === "modify") {
+        return { type: a.type, path: a.path, pattern: a.pattern };
+      }
+      if (a.type === "append") {
+        return { type: a.type, path: a.path, unique: a.unique };
+      }
+      return a;
+    });
     return successResponse({
       template: {
         name: template.config.name,
@@ -96958,7 +97119,7 @@ async function handleGetTemplate(args2) {
         doc: template.config.doc,
         // Linked documentation - AI should read this
         prompts: prompts4 || [],
-        files: files || [],
+        actions: actions || [],
         messages: template.config.messages
       },
       hint: template.config.doc ? `This template links to @doc/${template.config.doc}. Read the doc for context before running.` : void 0
@@ -96970,11 +97131,11 @@ async function handleGetTemplate(args2) {
 async function handleRunTemplate(args2) {
   const input = runTemplateSchema.parse(args2);
   const dryRun = input.dryRun !== false;
-  if (!existsSync29(TEMPLATES_DIR2)) {
+  if (!existsSync29(TEMPLATES_DIR3)) {
     return errorResponse("No templates directory found");
   }
   try {
-    const template = await loadTemplateByName(input.name, TEMPLATES_DIR2);
+    const template = await loadTemplateByName(TEMPLATES_DIR3, input.name);
     if (!template) {
       return errorResponse(`Template not found: ${input.name}`);
     }
@@ -96989,8 +97150,8 @@ async function handleRunTemplate(args2) {
     for (const prompt of template.config.prompts || []) {
       if (input.variables?.[prompt.name]) {
         values[prompt.name] = input.variables[prompt.name];
-      } else if (prompt.default) {
-        values[prompt.name] = String(prompt.default);
+      } else if (prompt.initial !== void 0) {
+        values[prompt.name] = String(prompt.initial);
       }
     }
     const result = await runTemplate(template, {
@@ -97001,19 +97162,18 @@ async function handleRunTemplate(args2) {
     if (!result.success) {
       return errorResponse(`Template failed: ${result.error}`);
     }
-    const filesCreated = result.files?.map((f) => ({
-      path: f.path,
-      action: f.action,
-      skipped: f.skipped,
-      skipReason: f.skipReason
-    }));
+    const totalCreated = result.created?.length || 0;
+    const totalModified = result.modified?.length || 0;
+    const totalSkipped = result.skipped?.length || 0;
     return successResponse({
       success: true,
       dryRun,
       template: input.name,
       variables: values,
-      files: filesCreated || [],
-      message: dryRun ? `Dry run complete. ${filesCreated?.length || 0} files would be created. Set dryRun: false to write files.` : `Template executed. ${filesCreated?.filter((f) => !f.skipped).length || 0} files created.`
+      created: result.created || [],
+      modified: result.modified || [],
+      skipped: result.skipped || [],
+      message: dryRun ? `Dry run complete. ${totalCreated} files would be created, ${totalModified} modified. Set dryRun: false to write files.` : `Template executed. ${totalCreated} files created, ${totalModified} modified, ${totalSkipped} skipped.`
     });
   } catch (error48) {
     return errorResponse(`Failed to run template: ${error48 instanceof Error ? error48.message : String(error48)}`);
@@ -97022,10 +97182,10 @@ async function handleRunTemplate(args2) {
 async function handleCreateTemplate(args2) {
   const input = createTemplateSchema.parse(args2);
   try {
-    if (!existsSync29(TEMPLATES_DIR2)) {
-      await mkdir18(TEMPLATES_DIR2, { recursive: true });
+    if (!existsSync29(TEMPLATES_DIR3)) {
+      await mkdir18(TEMPLATES_DIR3, { recursive: true });
     }
-    const templateDir = join34(TEMPLATES_DIR2, input.name);
+    const templateDir = join34(TEMPLATES_DIR3, input.name);
     if (existsSync29(templateDir)) {
       return errorResponse(`Template "${input.name}" already exists`);
     }
@@ -97645,7 +97805,7 @@ function showConfigInfo() {
 import { existsSync as existsSync33 } from "node:fs";
 import { mkdir as mkdir19, writeFile as writeFile17 } from "node:fs/promises";
 import { join as join38 } from "node:path";
-var TEMPLATES_DIR3 = ".knowns/templates";
+var TEMPLATES_DIR4 = ".knowns/templates";
 function getProjectRoot3() {
   const projectRoot = findProjectRoot();
   if (!projectRoot) {
@@ -97656,7 +97816,7 @@ function getProjectRoot3() {
   return projectRoot;
 }
 function getTemplatesDir(projectRoot) {
-  return join38(projectRoot, TEMPLATES_DIR3);
+  return join38(projectRoot, TEMPLATES_DIR4);
 }
 async function ensureTemplatesDir(projectRoot) {
   const templatesDir = getTemplatesDir(projectRoot);
@@ -97666,20 +97826,16 @@ async function ensureTemplatesDir(projectRoot) {
   return templatesDir;
 }
 var templateCommand = new Command("template").description("Manage code generation templates").enablePositionalOptions();
-var listCommand4 = new Command("list").description("List available templates").option("--plain", "Plain text output for AI").action(async (options2) => {
+var listCommand4 = new Command("list").description("List available templates (local + imported)").option("--plain", "Plain text output for AI").option("--local", "Show only local templates").option("--imported", "Show only imported templates").action(async (options2) => {
   try {
     const projectRoot = getProjectRoot3();
-    const templatesDir = getTemplatesDir(projectRoot);
-    if (!existsSync33(templatesDir)) {
-      if (options2.plain) {
-        console.log("No templates found");
-      } else {
-        console.log(source_default.yellow("No templates found"));
-        console.log(source_default.gray("  Create one with: knowns template create <name>"));
-      }
-      return;
+    const allTemplates = await listAllTemplates(projectRoot);
+    let templates = allTemplates;
+    if (options2.local) {
+      templates = allTemplates.filter((t) => !t.isImported);
+    } else if (options2.imported) {
+      templates = allTemplates.filter((t) => t.isImported);
     }
-    const templates = await listTemplates(templatesDir);
     if (templates.length === 0) {
       if (options2.plain) {
         console.log("No templates found");
@@ -97689,21 +97845,88 @@ var listCommand4 = new Command("list").description("List available templates").o
       }
       return;
     }
+    const templatesWithDesc = [];
+    for (const t of templates) {
+      try {
+        const loaded = await listTemplates(join38(t.path, ".."));
+        const match2 = loaded.find((l) => l.name === t.name);
+        templatesWithDesc.push({
+          ref: t.ref,
+          name: t.name,
+          source: t.source,
+          sourceUrl: t.sourceUrl,
+          isImported: t.isImported,
+          description: match2?.description || "No description"
+        });
+      } catch {
+        templatesWithDesc.push({
+          ref: t.ref,
+          name: t.name,
+          source: t.source,
+          sourceUrl: t.sourceUrl,
+          isImported: t.isImported,
+          description: "No description"
+        });
+      }
+    }
     if (options2.plain) {
-      for (const template of templates) {
-        console.log(`${template.name} - ${template.description || "No description"}`);
+      const sources = /* @__PURE__ */ new Map();
+      for (const t of templatesWithDesc) {
+        const sourceKey = t.isImported ? `[${t.source}]` : "[local]";
+        if (!sources.has(sourceKey)) {
+          sources.set(sourceKey, []);
+        }
+        sources.get(sourceKey)?.push(t);
+      }
+      const sortedSources = Array.from(sources.keys()).sort((a, b) => {
+        if (a === "[local]") return -1;
+        if (b === "[local]") return 1;
+        return a.localeCompare(b);
+      });
+      for (const sourceKey of sortedSources) {
+        const sourceTemplates = sources.get(sourceKey) || [];
+        const sourceUrl = sourceTemplates[0]?.sourceUrl;
+        if (sourceUrl) {
+          console.log(`${sourceKey} (${sourceUrl})`);
+        } else {
+          console.log(sourceKey);
+        }
+        for (const t of sourceTemplates) {
+          console.log(`  ${t.name} - ${t.description}`);
+        }
       }
     } else {
       console.log(source_default.bold("\nTemplates:\n"));
-      const maxNameLen = Math.max(...templates.map((t) => t.name.length), 4);
-      console.log(source_default.gray(`${"Name".padEnd(maxNameLen + 2)}Description`));
-      console.log(source_default.gray("\u2500".repeat(60)));
-      for (const template of templates) {
-        const name = source_default.cyan(template.name.padEnd(maxNameLen + 2));
-        const desc = template.description || source_default.gray("No description");
-        console.log(`${name}${desc}`);
+      const sources = /* @__PURE__ */ new Map();
+      for (const t of templatesWithDesc) {
+        const sourceKey = t.isImported ? t.source : "local";
+        if (!sources.has(sourceKey)) {
+          sources.set(sourceKey, []);
+        }
+        sources.get(sourceKey)?.push(t);
+      }
+      const sortedSources = Array.from(sources.keys()).sort((a, b) => {
+        if (a === "local") return -1;
+        if (b === "local") return 1;
+        return a.localeCompare(b);
+      });
+      for (const sourceKey of sortedSources) {
+        const sourceTemplates = sources.get(sourceKey) || [];
+        const sourceUrl = sourceTemplates[0]?.sourceUrl;
+        const sourceLabel = sourceKey === "local" ? "Local" : `Import: ${sourceKey}`;
+        if (sourceUrl) {
+          console.log(source_default.magenta.bold(`[${sourceLabel}]`) + source_default.gray(` ${sourceUrl}`));
+        } else {
+          console.log(source_default.magenta.bold(`[${sourceLabel}]`));
+        }
+        const maxNameLen = Math.max(...sourceTemplates.map((t) => t.name.length), 4);
+        for (const t of sourceTemplates) {
+          const name = source_default.cyan(t.name.padEnd(maxNameLen + 2));
+          const desc = t.description || source_default.gray("No description");
+          console.log(`  ${name}${desc}`);
+        }
+        console.log();
       }
-      console.log();
     }
   } catch (error48) {
     console.error(source_default.red("Error:"), error48 instanceof Error ? error48.message : String(error48));
@@ -97831,7 +98054,7 @@ export function {{camelCase name}}() {
     await writeFile17(join38(templateDir, "example.ts.hbs"), exampleTemplate, "utf-8");
     console.log();
     console.log(source_default.green(`\u2713 Created template: ${name}`));
-    console.log(source_default.gray(`  Location: ${TEMPLATES_DIR3}/${name}/`));
+    console.log(source_default.gray(`  Location: ${TEMPLATES_DIR4}/${name}/`));
     console.log();
     console.log(source_default.cyan("Files created:"));
     console.log(source_default.gray("  - _template.yaml (config)"));
@@ -98636,7 +98859,7 @@ async function notifyCliUpdate(options2) {
 // package.json
 var package_default = {
   name: "knowns",
-  version: "0.10.1",
+  version: "0.10.3",
   description: "AI-native task and documentation management for dev teams",
   module: "index.ts",
   type: "module",