knowns 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,93 @@ 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.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
+- **Web UI Static Files**: Fixed `NotFoundError` when running `knowns browser` from global install
+  - Bun creates symlinks in `~/.bun/bin/` which broke path resolution for UI files
+  - Added `realpathSync` to resolve symlinks before computing paths
+  - Changed Express `sendFile` to use `root` option for reliable file serving
+
 ## [0.2.0] - 2025-12-27
 
 ### Added

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
 
@@ -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
@@ -316,8 +326,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 +338,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,7 +347,7 @@ 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
 
@@ -404,7 +414,8 @@ 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
@@ -435,7 +446,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 +491,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 +514,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 +554,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 +568,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
@@ -621,7 +631,8 @@ Use **lowercase with hyphens**:
 | 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 |
@@ -629,8 +640,8 @@ Use **lowercase with hyphens**:
 | Use `"In Progress"` or `"Done"` | Use `in-progress`, `done` |
 | Use `@yourself` | Use `@me` or specific username |
 | 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,7 +699,7 @@ 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`
 - [ ] Status set to in-progress: `-s in-progress`
@@ -697,7 +708,7 @@ EOF
 ### 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 "✓ ..."`
 
@@ -717,18 +728,18 @@ 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 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"
@@ -736,7 +747,7 @@ knowns time stop
 knowns task edit <id> -s done
 
 # === 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 search "query" --plain
@@ -750,7 +761,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 +785,4 @@ knowns doc edit "doc-name" -a "Appended content"
 
 
 
+

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="images/cover.png" alt="Knowns - Task & Documentation Management" width="100%">
+  <img src="images/cover.jpeg" alt="Knowns - Task & Documentation Management" width="100%">
 </p>
 
 <h1 align="center">Knowns</h1>
@@ -109,12 +109,12 @@ knowns browser  # Open Web UI
 # Tasks
 knowns task create "Title" -d "Description" --ac "Criterion"
 knowns task list --plain
-knowns task view <id> --plain
+knowns task <id> --plain                    # View task (shorthand)
 knowns task edit <id> -s in-progress -a @me
 
 # Documentation
 knowns doc create "Title" -d "Description" -f "folder"
-knowns doc view "doc-name" --plain
+knowns doc "doc-name" --plain               # View doc (shorthand)
 
 # Time & Search
 knowns time start <id> && knowns time stop