knowns 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,103 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] - 2025-12-30
+
+### Fixed
+- **Kanban Drag-Drop**: Fixed cards not being droppable into empty columns
+  - Implemented custom multi-strategy collision detection algorithm
+  - Strategy 1: Pointer position detection (most intuitive for users)
+  - Strategy 2: Rectangle intersection for overlapping elements
+  - Strategy 3: Extended bounds with 150px buffer for near-column detection
+  - Strategy 4: Closest corners fallback for edge cases
+  - Dragging is now much smoother and easier
+
+### Changed
+- **MCP Integration Docs**: Updated `docs/mcp-integration.md` with complete tool reference
+  - Added all 15 MCP tools with parameters
+  - Added time tracking and board tools
+  - Added troubleshooting section for `--verbose` and `--info` flags
+  - Added resources section with links to official docs
+
+## [0.3.0] - 2025-12-29
+
+### Added
+- **CLI Shorthand Commands**: New concise syntax for common operations
+  - `knowns task <id>` - Shorthand for `knowns task view <id>`
+  - `knowns doc <path>` - Shorthand for `knowns doc view <path>`
+  - Reduces typing while maintaining full command compatibility
+
+- **New UI Components** (shadcn/ui):
+  - Badge, Card, Checkbox, Label, Progress, Select components
+  - Data Table with sorting, filtering, and pagination
+  - Dropdown Menu for context actions
+  - Kanban board components (Column, Card, Board)
+  - Sonner for toast notifications
+  - Table component for data display
+
+- **New React Contexts**:
+  - `ConfigContext` - Global configuration state management
+  - `TimeTrackerContext` - Time tracking state across components
+  - `UIPreferencesContext` - User UI preferences persistence
+
+- **Server Architecture**:
+  - `src/server/middleware/` - Request processing middleware
+  - `src/server/routes/` - Modular route handlers
+  - `src/server/utils/` - Server utility functions
+  - `src/server/types.ts` - TypeScript type definitions
+
+- **Documentation**:
+  - `docs/developer-guide.md` - Developer setup and contribution guide
+  - `docs/user-guide.md` - End-user documentation
+
+- **Utilities**:
+  - `src/ui/utils/colors.ts` - Color utility functions for UI
+  - `src/ui/utils/markdown-sections.ts` - Markdown section parsing
+
+### Changed
+- **UI Architecture**: Migrated to Atomic Design pattern
+  - `atoms/` - Basic UI building blocks (buttons, inputs, icons)
+  - `molecules/` - Composed components (form fields, cards)
+  - `organisms/` - Complex UI sections (forms, lists, modals)
+  - `templates/` - Page layout templates
+  - Improved component reusability and maintainability
+
+- **Server Refactoring**: Modularized monolithic server
+  - Split 567-line `server/index.ts` into focused modules
+  - Cleaner separation of concerns
+  - Easier testing and maintenance
+
+- **Page Components**: Simplified and optimized
+  - `TasksPage` - Reduced from 700+ to ~300 lines
+  - `DocsPage` - Streamlined document management
+  - `KanbanPage` - Enhanced board functionality
+  - `ConfigPage` - Improved settings interface
+
+- **API Client**: Enhanced `src/ui/api/client.ts`
+  - Better error handling
+  - Type-safe API calls
+  - Improved response parsing
+
+- **Guidelines**: Updated AI agent guidelines
+  - Clearer reference format documentation
+  - Better examples for input vs output formats
+  - Improved workflow instructions
+
+### Removed
+- **Legacy Components**: Cleaned up old monolithic components
+  - `ActivityFeed.tsx`, `AppSidebar.tsx`, `AssigneeDropdown.tsx`
+  - `Avatar.tsx`, `Board.tsx`, `Column.tsx`
+  - `MarkdownRenderer.tsx`, `NotificationBell.tsx`
+  - `SearchBox.tsx`, `SearchCommandDialog.tsx`
+  - `TaskCard.tsx`, `TaskCreateForm.tsx`, `TaskDetailModal.tsx`
+  - `TaskHistoryPanel.tsx`, `TimeTracker.tsx`, `VersionDiffViewer.tsx`
+  - Functionality preserved in new Atomic Design components
+
+### Fixed
+- **Dialog/Sheet Components**: Fixed accessibility and styling issues
+- **Mention Refs**: Improved reference parsing reliability
+- **Server Notifications**: Better WebSocket notification handling
+
 ## [0.2.1] - 2025-12-28
 
 ### Fixed
@@ -247,6 +344,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - CLAUDE.md with complete guidelines for AI agents
 - Example workflows and patterns
 
+[0.3.1]: https://github.com/knowns-dev/knowns/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/knowns-dev/knowns/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/knowns-dev/knowns/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/knowns-dev/knowns/compare/v0.1.8...v0.2.0
 [0.1.8]: https://github.com/knowns-dev/knowns/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/knowns-dev/knowns/compare/v0.1.6...v0.1.7

package/CLAUDE.md

@@ -28,10 +28,10 @@ When starting a new session or working on an unfamiliar project:
 knowns doc list --plain
 
 # 2. Read essential project docs (prioritize these)
-knowns doc view "README" --plain           # Project overview
-knowns doc view "ARCHITECTURE" --plain     # System design
-knowns doc view "CONVENTIONS" --plain      # Coding standards
-knowns doc view "API" --plain              # API specifications
+knowns doc "README" --plain                # Project overview
+knowns doc "ARCHITECTURE" --plain          # System design
+knowns doc "CONVENTIONS" --plain           # Coding standards
+knowns doc "API" --plain                   # API specifications
 
 # 3. Review current task backlog
 knowns task list --plain
@@ -42,17 +42,17 @@ knowns task list --status in-progress --plain
 
 ```bash
 # 1. View the task details
-knowns task view <id> --plain
+knowns task <id> --plain
 
 # 2. Follow ALL refs in the task (see Reference System section)
-# @.knowns/tasks/task-44 - ... → knowns task view 44 --plain
-# @.knowns/docs/patterns/module.md → knowns doc view "patterns/module" --plain
+# @.knowns/tasks/task-44 - ... → knowns task 44 --plain
+# @.knowns/docs/patterns/module.md → knowns doc "patterns/module" --plain
 
 # 3. Search for additional related documentation
 knowns search "<keywords from task>" --type doc --plain
 
 # 4. Read ALL related docs before planning
-knowns doc view "<related-doc>" --plain
+knowns doc "<related-doc>" --plain
 
 # 5. Check for similar completed tasks (learn from history)
 knowns search "<keywords>" --type task --status done --plain
@@ -90,10 +90,15 @@ Tasks and docs can contain **references** to other tasks/docs. AI agents MUST un
 
 ### Reference Formats
 
-| Type | User Input | System Output | CLI Command |
-|------|------------|---------------|-------------|
-| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `knowns task view <id> --plain` |
-| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `knowns doc view "<path>" --plain` |
+| Type | When Writing (Input) | When Reading (Output) | CLI Command |
+|------|---------------------|----------------------|-------------|
+| **Task ref** | `@task-<id>` | `@.knowns/tasks/task-<id> - <title>.md` | `knowns task <id> --plain` |
+| **Doc ref** | `@doc/<path>` | `@.knowns/docs/<path>.md` | `knowns doc <path> --plain` |
+
+> **CRITICAL for AI Agents**:
+> - When **WRITING** refs (in descriptions, plans, notes): Use `@task-<id>` and `@doc/<path>`
+> - When **READING** output from `--plain`: You'll see `@.knowns/tasks/...` and `@.knowns/docs/...`
+> - **NEVER write** the output format (`@.knowns/...`) - always use input format (`@task-<id>`, `@doc/<path>`)
 
 ### How to Follow Refs
 
@@ -105,16 +110,16 @@ When you read a task and see refs in system output format, follow them:
 # @.knowns/docs/patterns/module.md
 
 # Follow task ref (extract ID from task-<id>)
-knowns task view 44 --plain
+knowns task 44 --plain
 
 # Follow doc ref (extract path, remove .md)
-knowns doc view "patterns/module" --plain
+knowns doc "patterns/module" --plain
 ```
 
 ### Parsing Rules
 
-1. **Task refs**: `@.knowns/tasks/task-<id> - ...` → extract `<id>` → `knowns task view <id> --plain`
-2. **Doc refs**: `@.knowns/docs/<path>.md` → extract `<path>` → `knowns doc view "<path>" --plain`
+1. **Task refs**: `@.knowns/tasks/task-<id> - ...` → extract `<id>` → `knowns task <id> --plain`
+2. **Doc refs**: `@.knowns/docs/<path>.md` → extract `<path>` → `knowns doc "<path>" --plain`
 
 ### Recursive Following
 
@@ -140,20 +145,20 @@ Task 42
 
 ```bash
 # 1. Read the task
-$ knowns task view 42 --plain
+$ knowns task 42 --plain
 
 # Output contains:
 # @.knowns/tasks/task-44 - CLI Task Create Command.md
 # @.knowns/docs/README.md
 
 # 2. Follow task ref
-$ knowns task view 44 --plain
+$ knowns task 44 --plain
 
 # 3. Follow doc ref
-$ knowns doc view "README" --plain
+$ knowns doc "README" --plain
 
 # 4. If README contains more refs, follow them too
-# @.knowns/docs/patterns/module.md → knowns doc view "patterns/module" --plain
+# @.knowns/docs/patterns/module.md → knowns doc "patterns/module" --plain
 
 # Now you have complete context
 ```
@@ -172,7 +177,12 @@ knowns init [name]
 knowns task create "Title" -d "Description" --ac "Criterion 1" --ac "Criterion 2"
 
 # View task (ALWAYS use --plain for AI)
-knowns task view <id> --plain
+knowns task <id> --plain                    # Shorthand
+knowns task view <id> --plain               # Full command
+
+# View doc (ALWAYS use --plain for AI)
+knowns doc <path> --plain                   # Shorthand
+knowns doc view "<path>" --plain            # Full command
 
 # List tasks
 knowns task list --plain
@@ -202,9 +212,9 @@ $ knowns doc list --plain
 # DOC: email-templates.md
 
 # 0b. Read essential project docs
-$ knowns doc view "README" --plain
-$ knowns doc view "ARCHITECTURE" --plain
-$ knowns doc view "CONVENTIONS" --plain
+$ knowns doc "README" --plain
+$ knowns doc "ARCHITECTURE" --plain
+$ knowns doc "CONVENTIONS" --plain
 
 # Now the agent understands project context and conventions
 
@@ -222,8 +232,8 @@ $ knowns task create "Add password reset flow" \
 
 # Output: Created task AUTH-042
 
-# 2. Take the task and start timer
-$ knowns task edit AUTH-042 -s in-progress -a @me
+# 2. Take the task and start timer (uses defaultAssignee or @me fallback)
+$ knowns task edit AUTH-042 -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")
 $ knowns time start AUTH-042
 
 # Output: Timer started for AUTH-042
@@ -236,12 +246,12 @@ $ knowns search "password security" --type doc --plain
 # DOC: email-templates.md (score: 0.78)
 
 # 4. Read the documentation
-$ knowns doc view "security-patterns" --plain
+$ knowns doc "security-patterns" --plain
 
 # 5. Create implementation plan (SHARE WITH USER, WAIT FOR APPROVAL)
-$ knowns task edit AUTH-042 --plan $'1. Review security patterns (see [security-patterns.md](./docs/security-patterns.md))
+$ knowns task edit AUTH-042 --plan $'1. Review security patterns (see @doc/security-patterns)
 2. Design token generation with 1-hour expiry
-3. Create email template (see [email-templates.md](./docs/email-templates.md))
+3. Create email template (see @doc/email-templates)
 4. Implement /forgot-password endpoint
 5. Implement /reset-password endpoint
 6. Add unit tests
@@ -296,17 +306,24 @@ $ knowns task edit AUTH-042 -s done
 ### Step 1: Take Task
 
 ```bash
-knowns task edit <id> -s in-progress -a @me
+# Assign using defaultAssignee from config (falls back to @me if not set)
+knowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")
 ```
 
-> **Note**: `@me` is a special keyword that assigns the task to yourself. You can also use specific usernames like `@harry` or `@john`.
+> **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"`
 
-### Step 2: Start Time Tracking
+### Step 2: Start Time Tracking (REQUIRED)
 
 ```bash
 knowns time start <id>
 ```
 
+> **CRITICAL**: Time tracking is MANDATORY. Always start timer when taking a task and stop when done. This data is essential for:
+> - Accurate project estimation
+> - Identifying bottlenecks
+> - Resource planning
+> - Sprint retrospectives
+
 ### Step 3: Read Related Documentation
 
 > **FOR AI AGENTS**: This step is MANDATORY, not optional. You must understand the codebase before planning.
@@ -316,8 +333,8 @@ knowns time start <id>
 knowns search "authentication" --type doc --plain
 
 # View relevant documents
-knowns doc view "API Guidelines" --plain
-knowns doc view "Security Patterns" --plain
+knowns doc "API Guidelines" --plain
+knowns doc "Security Patterns" --plain
 
 # Also check for similar completed tasks
 knowns search "auth" --type task --status done --plain
@@ -328,7 +345,7 @@ knowns search "auth" --type task --status done --plain
 ### Step 4: Create Implementation Plan
 
 ```bash
-knowns task edit <id> --plan $'1. Research patterns (see [security-patterns.md](./security-patterns.md))
+knowns task edit <id> --plan $'1. Research patterns (see @doc/security-patterns)
 2. Design middleware
 3. Implement
 4. Add tests
@@ -337,16 +354,48 @@ knowns task edit <id> --plan $'1. Research patterns (see [security-patterns.md](
 
 > **CRITICAL**:
 > - Share plan with user and **WAIT for approval** before coding
-> - Include doc references using `[file.md](./path/file.md)` format
+> - Include doc references using `@doc/<path>` format
 
 ### Step 5: Implement
 
 ```bash
-# Check acceptance criteria as you complete them
-knowns task edit <id> --check-ac 1 --check-ac 2 --check-ac 3
+# Work through implementation plan step by step
+# IMPORTANT: Only check AC AFTER completing the work, not before
+
+# After completing work for AC #1:
+knowns task edit <id> --check-ac 1
+knowns task edit <id> --append-notes "✓ Completed: <brief description>"
+
+# After completing work for AC #2:
+knowns task edit <id> --check-ac 2
+knowns task edit <id> --append-notes "✓ Completed: <brief description>"
 ```
 
-### Step 6: Add Implementation Notes
+> **CRITICAL**: Never check an AC before the work is actually done. ACs represent completed outcomes, not intentions.
+
+### Step 6: Handle Dynamic Requests (During Implementation)
+
+If the user adds new requirements during implementation:
+
+```bash
+# Add new acceptance criteria
+knowns task edit <id> --ac "New requirement from user"
+
+# Update implementation plan to include new steps
+knowns task edit <id> --plan $'1. Original step 1
+2. Original step 2
+3. NEW: Handle user request for X
+4. Continue with remaining work'
+
+# Append note about scope change
+knowns task edit <id> --append-notes "⚠️ Scope updated: Added requirement for X per user request"
+
+# Continue with Step 5 (Implement) for new requirements
+```
+
+> **Note**: Always document scope changes. This helps track why a task took longer than expected.
+
+### Step 7: Add Implementation Notes
 
 ```bash
 # Add comprehensive notes (suitable for PR description)
@@ -363,18 +412,77 @@ knowns task edit <id> --append-notes "✓ Implemented middleware"
 knowns task edit <id> --append-notes "✓ Added tests"
 ```
 
-### Step 7: Stop Time Tracking
+### Step 8: Stop Time Tracking (REQUIRED)
 
 ```bash
 knowns time stop
 ```
 
-### Step 8: Complete Task
+> **CRITICAL**: Never forget to stop the timer. If you forget, use manual entry: `knowns time add <id> <duration> -n "Forgot to stop timer"`
+
+### Step 9: Complete Task
 
 ```bash
 knowns task edit <id> -s done
 ```
 
+### Step 10: Handle Post-Completion Changes (If Applicable)
+
+If the user requests changes or updates AFTER task is marked done:
+
+```bash
+# 1. Reopen task - set back to in-progress
+knowns task edit <id> -s in-progress
+
+# 2. Restart time tracking (REQUIRED)
+knowns time start <id>
+
+# 3. Add new AC for the changes requested
+knowns task edit <id> --ac "Post-completion fix: <description>"
+
+# 4. Document the reopen reason
+knowns task edit <id> --append-notes "🔄 Reopened: User requested changes - <reason>"
+
+# 5. Follow Step 5-9 again (Implement → Notes → Stop Timer → Done)
+```
+
+> **CRITICAL**: Treat post-completion changes as a mini-workflow. Always:
+> - Reopen task (in-progress)
+> - Start timer again
+> - Add AC for traceability
+> - Document why it was reopened
+> - Follow the same completion process
+
+### Step 11: Knowledge Extraction (Post-Completion)
+
+After completing a task, extract reusable knowledge to docs:
+
+```bash
+# Search if similar pattern already documented
+knowns search "<pattern/concept>" --type doc --plain
+
+# If new knowledge, create a doc for future reference
+knowns doc create "Pattern: <Name>" \
+    -d "Reusable pattern discovered during task implementation" \
+    -t "pattern,<domain>" \
+    -f "patterns"
+
+# Or append to existing doc
+knowns doc edit "<existing-doc>" -a "## New Section\n\nLearned from task <id>: ..."
+
+# Reference the source task
+knowns doc edit "<doc-name>" -a "\n\n> Source: @task-<id>"
+```
+
+**When to extract knowledge:**
+- New patterns/conventions discovered
+- Common error solutions
+- Reusable code snippets or approaches
+- Integration patterns with external services
+- Performance optimization techniques
+
+> **CRITICAL**: Only extract **generalizable** knowledge. Task-specific details belong in implementation notes, not docs.
+
 ---
 
 ## Essential Commands
@@ -390,7 +498,7 @@ knowns task edit <id> -t "New title"
 knowns task edit <id> -d "New description"
 knowns task edit <id> -s in-progress
 knowns task edit <id> --priority high
-knowns task edit <id> -a @me
+knowns task edit <id> -a <assignee>              # $(knowns config get defaultAssignee --plain || echo "@me")
 
 # Acceptance Criteria
 knowns task edit <id> --ac "New criterion"           # Add
@@ -404,10 +512,11 @@ knowns task edit <id> --notes "Implementation summary"
 knowns task edit <id> --append-notes "Progress update"
 
 # View & List
-knowns task view <id> --plain                        # ALWAYS use --plain
+knowns task <id> --plain                             # Shorthand (ALWAYS use --plain)
+knowns task view <id> --plain                        # Full command
 knowns task list --plain
 knowns task list --status in-progress --plain
-knowns task list --assignee @me --plain
+knowns task list --assignee <assignee> --plain   # $(knowns config get defaultAssignee --plain || echo "@me")
 knowns task list --tree --plain                      # Tree hierarchy
 ```
 
@@ -435,7 +544,8 @@ knowns time report --by-label --csv > report.csv
 # List & View
 knowns doc list --plain
 knowns doc list --tag architecture --plain
-knowns doc view "Doc Name" --plain
+knowns doc <path> --plain                          # Shorthand (ALWAYS use --plain)
+knowns doc view "<path>" --plain                   # Full command
 
 # Create (with optional folder)
 knowns doc create "Title" -d "Description" -t "tags"
@@ -479,14 +589,12 @@ Clear summary (WHAT needs to be done).
 
 ### Description
 
-Explains WHY and WHAT (not HOW). **Link related docs using `[file.md](./path/file.md)`**
+Explains WHY and WHAT (not HOW). **Link related docs using `@doc/<path>`**
 
 ```markdown
 We need JWT authentication because sessions don't scale for our microservices architecture.
 
-Related docs:
-- [security-patterns.md](./docs/security-patterns.md)
-- [api-guidelines.md](./docs/api-guidelines.md)
+Related docs: @doc/security-patterns, @doc/api-guidelines
 ```
 
 ### Acceptance Criteria
@@ -504,7 +612,7 @@ Related docs:
 HOW to solve. Added AFTER taking task, BEFORE coding.
 
 ```markdown
-1. Research JWT libraries (see [security-patterns.md](./docs/security-patterns.md))
+1. Research JWT libraries (see @doc/security-patterns)
 2. Design token structure (access + refresh tokens)
 3. Implement auth middleware
 4. Add unit tests (aim for 90%+ coverage)
@@ -544,7 +652,7 @@ Implemented JWT auth using jsonwebtoken library.
 | `Error: No active timer` | Calling `time stop` without active timer | Start timer first: `knowns time start <id>` |
 | `Error: Timer already running` | Starting timer when one is active | Stop current: `knowns time stop` |
 | `Error: Invalid status` | Wrong status format | Use lowercase with hyphens: `in-progress`, not `In Progress` |
-| `Error: AC index out of range` | Checking non-existent criterion | View task first: `knowns task view <id> --plain` |
+| `Error: AC index out of range` | Checking non-existent criterion | View task first: `knowns task <id> --plain` |
 | `Error: Document not found` | Wrong document name | Run `knowns doc list --plain` to find correct name |
 | `Error: Not initialized` | Running commands without init | Run `knowns init` first |
 
@@ -558,7 +666,7 @@ knowns --version
 knowns status
 
 # View raw task data (for debugging)
-knowns task view <id> --json
+knowns task <id> --json
 
 # Check timer status
 knowns time status
@@ -572,10 +680,11 @@ A task is **Done** ONLY when **ALL** criteria are met:
 
 ### Via CLI (Required)
 
-- [ ] All acceptance criteria checked: `--check-ac <index>`
+- [ ] All acceptance criteria checked: `--check-ac <index>` (only after work is actually done)
 - [ ] Implementation notes added: `--notes "..."`
-- [ ] Timer stopped: `knowns time stop`
+- [ ] ⏱️ Timer stopped: `knowns time stop` (MANDATORY - do not skip!)
 - [ ] Status set to done: `-s done`
+- [ ] Knowledge extracted to docs (if applicable)
 
 ### Via Code (Required)
 
@@ -616,21 +725,24 @@ Use **lowercase with hyphens**:
 |-------|-------|
 | Edit .md files directly | Use `knowns task edit` |
 | Change `- [ ]` to `- [x]` in file | Use `--check-ac <index>` |
+| Check AC before completing work | Only check AC AFTER work is actually done |
+| Skip time tracking | ALWAYS use `time start` and `time stop` |
 | Start coding without reading docs | Read ALL related docs FIRST |
 | Skip `knowns doc list` on new project | Always list docs when starting |
 | Assume you know the conventions | Read CONVENTIONS/ARCHITECTURE docs |
 | Plan without checking docs | Read docs before planning |
 | Ignore similar completed tasks | Search done tasks for patterns |
-| Missing doc links in description/plan | Link docs using `[file.md](./path)` |
+| Missing doc links in description/plan | Link docs using `@doc/<path>` |
+| Write refs as `@.knowns/docs/...` or `@.knowns/tasks/...` | Use input format: `@doc/<path>`, `@task-<id>` |
 | Forget `--plain` flag | Always use `--plain` for AI |
 | Code before plan approval | Share plan, WAIT for approval |
 | Mark done without all criteria | Check ALL criteria first |
 | Write implementation steps in AC | Write outcome-oriented criteria |
 | Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |
-| Use `@yourself` | Use `@me` or specific username |
+| Use `@yourself` or unknown assignee | Use `$(knowns config get defaultAssignee --plain \|\| echo "@me")` |
 | Ignore refs in task description | Follow ALL refs (`@.knowns/...`) before planning |
-| See `@.knowns/docs/...` but don't read | Use `knowns doc view "<path>" --plain` |
-| See `@.knowns/tasks/task-X` but don't check | Use `knowns task view X --plain` for context |
+| See `@.knowns/docs/...` but don't read | Use `knowns doc "<path>" --plain` |
+| See `@.knowns/tasks/task-X` but don't check | Use `knowns task X --plain` for context |
 | Follow only first-level refs | Recursively follow nested refs until complete |
 
 ---
@@ -688,27 +800,28 @@ EOF
 - [ ] ALL refs in task followed (`@.knowns/...`)
 - [ ] Nested refs recursively followed until complete context gathered
 - [ ] Related docs searched: `knowns search "keyword" --type doc --plain`
-- [ ] ALL relevant docs read: `knowns doc view "Doc Name" --plain`
+- [ ] ALL relevant docs read: `knowns doc "Doc Name" --plain`
 - [ ] Similar done tasks reviewed for patterns
-- [ ] Task assigned to self: `-a @me`
+- [ ] Task assigned to self: `-a $(knowns config get defaultAssignee --plain || echo "@me")`
 - [ ] Status set to in-progress: `-s in-progress`
 - [ ] Timer started: `knowns time start <id>`
 
 ### During Work
 
 - [ ] Implementation plan created and approved
-- [ ] Doc links included in plan: `[file.md](./path/file.md)`
+- [ ] Doc links included in plan: `@doc/<path>`
 - [ ] Criteria checked as completed: `--check-ac <index>`
 - [ ] Progress notes appended: `--append-notes "✓ ..."`
 
 ### After Work
 
-- [ ] All acceptance criteria checked
+- [ ] All acceptance criteria checked (only after work is done)
 - [ ] Implementation notes added: `--notes "..."`
 - [ ] Timer stopped: `knowns time stop`
 - [ ] Tests passing
 - [ ] Documentation updated
 - [ ] Status set to done: `-s done`
+- [ ] Knowledge extracted to docs (if applicable): patterns, solutions, conventions
 
 ---
 
@@ -717,28 +830,32 @@ EOF
 ```bash
 # === AGENT INITIALIZATION (Once per session) ===
 knowns doc list --plain
-knowns doc view "README" --plain
-knowns doc view "ARCHITECTURE" --plain
-knowns doc view "CONVENTIONS" --plain
+knowns doc "README" --plain
+knowns doc "ARCHITECTURE" --plain
+knowns doc "CONVENTIONS" --plain
 
 # === FULL WORKFLOW ===
 knowns task create "Title" -d "Description" --ac "Criterion"
-knowns task edit <id> -s in-progress -a @me
-knowns time start <id>
+knowns task edit <id> -s in-progress -a $(knowns config get defaultAssignee --plain || echo "@me")
+knowns time start <id>                                     # ⏱️ REQUIRED: Start timer
 knowns search "keyword" --type doc --plain
-knowns doc view "Doc Name" --plain
+knowns doc "Doc Name" --plain
 knowns search "keyword" --type task --status done --plain  # Learn from history
-knowns task edit <id> --plan $'1. Step (see [file.md](./file.md))\n2. Step'
+knowns task edit <id> --plan $'1. Step (see @doc/file)\n2. Step'
 # ... wait for approval, then implement ...
-knowns task edit <id> --check-ac 1 --check-ac 2
-knowns task edit <id> --append-notes "✓ Completed feature"
-knowns time stop
+# Only check AC AFTER completing the work:
+knowns task edit <id> --check-ac 1
+knowns task edit <id> --append-notes "✓ Completed: feature X"
+knowns task edit <id> --check-ac 2
+knowns task edit <id> --append-notes "✓ Completed: feature Y"
+knowns time stop                                           # ⏱️ REQUIRED: Stop timer
 knowns task edit <id> -s done
+# Optional: Extract knowledge to docs if generalizable patterns found
 
 # === VIEW & SEARCH ===
-knowns task view <id> --plain
+knowns task <id> --plain                                   # Shorthand for view
 knowns task list --plain
-knowns task list --status in-progress --assignee @me --plain
+knowns task list --status in-progress --assignee $(knowns config get defaultAssignee --plain || echo "@me") --plain
 knowns search "query" --plain
 knowns search "bug" --type task --status in-progress --plain
 
@@ -750,7 +867,7 @@ knowns time report --from "2025-12-01" --to "2025-12-31"
 
 # === DOCUMENTATION ===
 knowns doc list --plain
-knowns doc view "path/doc-name" --plain
+knowns doc "path/doc-name" --plain                         # Shorthand for view
 knowns doc create "Title" -d "Description" -t "tags" -f "folder"
 knowns doc edit "doc-name" -c "New content"
 knowns doc edit "doc-name" -a "Appended content"
@@ -774,3 +891,8 @@ knowns doc edit "doc-name" -a "Appended content"
 
 
 
+
+
+
+
+