v0.12.4 - Error Handling & Stability Improvements

✨ Highlights

• 🛡️ Error Boundary - Catch rendering errors to prevent full app crashes
• 🔄 Retry UI - Graceful error recovery with retry button in DocsPage
• 📝 Defensive Parsing - Skip corrupted docs instead of crashing

🚀 Added

Error Handling

• New ErrorBoundary component to catch React rendering errors
• Error state and retry UI in DocsPage when docs fail to load
• Fallback UI with "Try Again" button and error message display

🐛 Fixed

Stability

• App crashes from rendering errors - ErrorBoundary prevents full app crash
• Corrupted doc files crash - Now skips invalid .md files with try-catch
• Missing doc metadata - Ensures all docs have required defaults (title, createdAt, updatedAt)
• DocsPage load failures - Shows error state with retry instead of silent failure

🔧 Technical

Error Boundary Component

• React class component with getDerivedStateFromError and componentDidCatch
• Supports custom fallback UI via props
• Logs errors to console for debugging
• Reset error state with retry button

Doc Parsing Safety

• Wrapped doc parsing in try-catch blocks
• Filters out null results from failed parsing
• Prevents server route crashes on invalid markdown files
• Default metadata injection for missing fields

App Integration

• ErrorBoundary wraps all page content in App.tsx
• Page errors are isolated and don't affect sidebar/header
• Users can continue using the app even if one page fails

Files Changed

src/ui/components/atoms/ErrorBoundary.tsx - New component (61 lines)
src/ui/components/atoms/index.ts          - Export ErrorBoundary
src/ui/App.tsx                            - Wrap pages in ErrorBoundary
src/ui/pages/DocsPage.tsx                 - Error state + retry UI
src/server/routes/docs.ts                 - Defensive parsing with try-catch

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.3...v0.12.4

v0.12.3 - Mobile Responsive UI & UX Enhancements

✨ Highlights

• 📱 Mobile Responsive - Optimized padding, spacing, and layouts for mobile devices
• 🚀 Performance - Lazy load Mermaid and page components (bundle reduced ~680KB)
• 🎨 UX Improvements - Breadcrumb navigation, scroll memory, copy table as markdown

🚀 Added

Mobile Support

• Mobile drawer for DocsPage, TemplatesPage, ImportsPage
• Mobile warning banner for Kanban (drag & drop not optimal on touch)
• Responsive padding throughout: p-3 sm:p-6
• Task modals use sheet-only mode on mobile (no center dialog)
• Hide maximize button on mobile (not applicable)

UX Features

• Copy table as markdown button (hover on tables)
• Breadcrumb navigation for DocsPage
• Scroll position memory when navigating between docs
• Keyboard shortcut Ctrl+B to toggle sidebar

Performance

• Lazy load MermaidBlock with React.lazy/Suspense
• Lazy load all page components in App.tsx
• Bundle size reduced from ~2,682KB to ~2,003KB

📝 Changed

Mermaid Diagrams

• GitHub-style zoom/pan controls
• Fullscreen mode support
• Improved rendering with better styling

Table Styling

• GitHub-like appearance with zebra striping
• Hover effects on rows
• Better border styling for headers vs cells

Typography

• Improved heading sizes and spacing
• Better list styling
• Custom checkbox styling for task lists

🐛 Fixed

• Task links in DocsPage - Now opens global modal instead of navigating to Kanban
• SSE reconnection - Improved handling for connection drops
• Safari markdown editor - Fixed issues with react-markdown-editor-lite

🔧 Technical

Responsive Patterns

• Consistent mobile padding: p-3 (mobile) / p-6 (desktop)
• Responsive gaps: gap-2 sm:gap-4, gap-3 sm:gap-6
• Responsive text: text-xl sm:text-2xl
• Truncate with min-w-0 for flex overflow handling

Components Updated

• TaskDetailSheet - mobile sheet mode, reduced padding
• TaskCreateForm - mobile sheet mode, compact layout
• TaskDataTable - responsive toolbar, stacked on mobile
• TaskGroupedView - responsive filters
• Board - responsive column controls

Files Changed

src/ui/App.tsx                    - Lazy load pages
src/ui/components/editor/MDRender.tsx - Table copy, lazy Mermaid
src/ui/components/editor/MermaidBlock.tsx - Zoom/pan/fullscreen
src/ui/components/organisms/TaskDetailSheet.tsx - Mobile sheet
src/ui/components/organisms/TaskCreateForm.tsx - Mobile sheet
src/ui/pages/DocsPage.tsx         - Breadcrumb, scroll memory, drawer
src/ui/pages/KanbanPage.tsx       - Mobile warning banner
src/ui/pages/TasksPage.tsx        - Responsive layout
src/ui/pages/TemplatesPage.tsx    - Mobile drawer
src/ui/pages/ImportsPage.tsx      - Mobile drawer
src/ui/index.css                  - Table styling, typography

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.2...v0.12.3

v0.12.2 - Browser Improvements & Validate E2E Tests

✨ Highlights

• 🌐 Smart Browser Detection - Prevents duplicate server instances when running knowns browser
• ✅ Validate E2E Tests - Comprehensive validation tests with scope filtering
• 🎨 Dynamic Status Options - UI now uses custom statuses from project config

🚀 Added

Validation Tests

• Added 29 vitest integration tests in validate.test.ts
• Expanded MCP e2e tests with 6 validation workflow tests
• Expanded CLI e2e tests with 6 validation workflow tests
• Tests cover: scope filtering, SDD mode, strict mode

Browser Command Improvements

• Server detection before starting new instance
• Auto-switch to next available port if occupied
• Only opens browser on successful port (not fallback)

📝 Changed

UI Enhancements

• TaskDataTable now uses dynamic status options from config.statuses
• StatusBadge supports custom statuses (e.g., "urgent")
• DocsPage and TaskGroupedView UI improvements

Skills System

• Updated /kn-spec with validation step
• Updated /kn-template with validation step
• Updated /kn-verify with improved coverage reporting

Publish Workflow

• Changed install instructions from Homebrew to npm/bun

🐛 Fixed

• Browser duplicate ports - Fixed knowns browser opening both 6420 and 6421
• Server port detection - Now properly checks if Knowns server is already running
• E2E test order - Fixed git init must run before knowns init

🔧 Technical

Validate Command

• Enhanced MCP handler with better scope filtering
• Improved stats reporting (tasks, docs, templates count)
• SDD validation with coverage percentage

Server

• Added isKnownsServerRunning() health check function
• Browser only opens on originally requested port
• Port fallback message shown when switching ports

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.1...v0.12.2

v0.12.1 - E2E Tests & Node 20+ Requirement

✨ Highlights

• 🧪 E2E Test Suite - Comprehensive CLI and MCP workflow tests
• 📦 pnpm Support - Added pnpm as package manager option
• ⚡ Node 20+ - Dropped Node 18, now requires Node 20+

🚀 Added

E2E Tests

• scripts/test-cli.mjs - CLI basic tests
• scripts/test-cli-e2e.mjs - CLI workflow tests
• scripts/test-mcp.mjs - MCP basic tests
• scripts/test-mcp-e2e.mjs - MCP workflow tests with semantic search
• New npm scripts: test:cli, test:cli:e2e, test:mcp, test:mcp:e2e

Documentation

• Added auth-patterns.md pattern documentation

📝 Changed

Node.js Requirements

• Breaking: Minimum Node.js version raised from 18 to 20
• Vite 7 and VI@vitest/coverage-v8 require Node 20+

Package Manager

• Added pnpm-lock.yaml for pnpm support
• CI now uses pnpm for faster installs

Skills System

• Removed .agent/skills/ synced files
• Skills now sourced directly from src/instructions/skills/

🐛 Fixed

• Fixed semantic search not working in MCP e2e tests
• Fixed CI coverage failing on Node 18 (now skipped)

🔧 Technical

• Updated CI matrix: Node 20, 22, 24 (removed 18)
• MCP e2e tests now use CLI to setup semantic search properly
• Removed obsolete engine.test.ts and store.test.ts

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.12.0...v0.12.1

v0.12.0 - Semantic Search & SDD Enhancements

✨ Highlights

• 🔍 Semantic Search - AI-powered search using vector embeddings for better relevance
• 🔗 Fulfills Field - Link tasks to spec acceptance criteria for SDD workflow
• 📊 Similarity Scores - See match confidence (%) in search results

🚀 Added

Semantic Search

• New knowns search with hybrid mode (semantic + keyword + fuzzy matching)
• knowns model command for embedding model management
  • model list - List available models (6 curated models)
  • model download <id> - Download embedding model
  • model set <id> - Set model for project
  • model status - Show current model status
• --reindex flag to rebuild search index
• --status-check flag to check semantic search status
• --keyword flag for keyword-only search fallback
• Similarity scores shown in results: (97%) for high relevance
• Matched by: semantic, fuzzy, keyword to explain why results matched

SDD (Spec-Driven Development)

• fulfills field on tasks to link to spec ACs
• Auto-check spec ACs when task AC is completed
• Pattern documentation for fulfills mapping

New Commands

• knowns guidelines - Display Knowns usage guidelines for AI agents
  • --plain for AI-readable output
  • --mode cli|mcp|unified for different guideline modes
  • --search <query> to search within guidelines
  • --compact for condensed rules (what goes in CLAUDE.md)

Auto-Sync & Version Tracking

• .version file in skill directories for tracking sync state
• Auto-sync skills when CLI version changes
• Progress bar utility for visual feedback during operations

📝 Changed

Search Output

• Plain output now shows structured format for AI:

  #taskId [status] [priority] (97%)
    Content snippet...
    Matched by: semantic, fuzzy, keyword
  

• Doc results show section and match reason

Documentation

• Converted ASCII diagrams to Mermaid in all docs
• Translated all Vietnamese text to English
• Removed non-existent CLI commands from docs
• Added 9 guide docs in .knowns/docs/guides/
• Updated README.md structure

MCP

• Search MCP tool now includes score field in results
• Added mode parameter: hybrid, semantic, keyword

🐛 Fixed

• Fixed config test using invalid key testKey
• Removed fake CLI commands: knowns ai detect, knowns mcp status, knowns skill export

📚 New Documentation

• docs/semantic-search.md - Semantic search guide
• docs/skills.md - Skills system guide
• docs/auto-sync.md - Auto-sync version tracking
• docs/guidelines.md - AI guidelines command
• docs/multi-platform.md - Multi-platform support
• .knowns/docs/guides/ - 9 new guide docs

🔧 Technical

• New src/search/ module:
  • chunker.ts - Document chunking for embeddings
  • embedding.ts - Embedding service (transformers.js)
  • engine.ts - Hybrid search engine
  • store.ts - Search index storage
  • index-service.ts - Incremental indexing
• New src/utils/progress-bar.ts - Progress bar utility
• New src/utils/auto-sync.ts - Version tracking
• New src/utils/sync-spec-acs.ts - Spec AC sync utility

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.4...v0.12.0

Changea

• Add setNotifyProjectRoot() to cache project root in notify-server
• Call setNotifyProjectRoot() when MCP sets project via set_project tool
• Sync project root in getFileStore() for all MCP tool calls
• Fixes issue where MCP couldn't notify web UI due to process.cwd() mismatch

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.3...v0.11.4

Changes

• Add standalone binary detection with helpful error message
• Auto-increment port when requested port is in use (max 10 retries)
• Write running port to .server-port file for CLI to read
• Fix dark mode flash by setting theme before React loads
• Add background-color to body for proper theme display

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.2...v0.11.3

Fixed

• fix(ci): restructure workflow - version first, then build, then publish HO@howznguyen (#54)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.1...v0.11.2

v0.11.1

Highlights

🍺 Homebrew Support

Knowns CLI is now available via Homebrew! No Node.js required.

brew install knowns-dev/tap/knowns

🪟 Windows Compatibility Fix

Renamed skill folders from kn:* to kn-* to fix Windows compatibility issues. Windows doesn't allow colons (:) in directory names.

Breaking Change: Skill invocation changed from /kn:init to /kn-init.

What's Changed

Features

• Homebrew tap: brew install knowns-dev/tap/knowns - standalone binary, no Node.js required
• Standalone binaries: macOS (arm64, x64) and Linux (x64) binaries included in releases
• Auto-update Homebrew: Formula automatically updates on new releases

Fixes

• Windows compatibility: Skill folders renamed from kn:* to kn-*
• Deprecated folder cleanup: Old kn:* and knowns.* folders are automatically removed on sync

Docs

• Added Homebrew install instructions to README, user-guide, and mcp-integration docs

Installation

# Homebrew (macOS/Linux) - no Node.js required
brew install knowns-dev/tap/knowns

# npm
npm install -g knowns

# bun
bun install -g knowns

Upgrading

# Homebrew
brew upgrade knowns

# npm
npm update -g knowns

# Re-sync skills to update folder names
knowns sync skills --force

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.11.0...v0.11.1

v0.11.0 - SDD (Spec-Driven Development) Support

What's New

CLI & Backend

• Add knowns validate --sdd command for SDD coverage reporting
• Add spec AC auto-sync - when task ACs are checked, matching spec ACs are automatically updated
• Add task-spec linking via spec: field in task frontmatter
• Add mermaid diagram rendering support in markdown

Skills

• Rename all skills to kn:* namespace (kn:init, kn:plan, kn:commit, kn:research, kn:implement, kn:extract, kn:template, kn:doc)
• Add kn:spec skill - create spec documents from requirements
• Add kn:verify skill - run SDD verification and coverage reporting

WebUI

• Add Dashboard page with 7 widgets:

  • Tasks overview with completion progress
  • Documentation stats
  • SDD Coverage widget
  • Time Tracking Summary (today/week/total)
  • Recent Activity feed
  • Recent Tasks list
  • Spec Progress Cards

• Add spec link on Kanban task cards - clickable link to spec document

• Add spec badges in Docs page (SPEC badge, status badge)

• Add AC Progress bar for spec documents

• Add expandable linked tasks list in spec view

• Add Specs filter in Docs page

• Add status badge (Draft/Approved/Implemented) to spec cards

• Fix kanban navigation bug when closing task detail

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.6...v0.11.0

Release v0.10.6

Highlights

This release adds MCP Project Detection for global MCP configurations (like Antigravity) and cleans up deprecated agent commands.

What's Changed

Added

• MCP Project Detection Tools - New tools for AI agents using global MCP configs:
  • detect_projects - Scan for Knowns projects in common workspace directories
  • set_project - Set the active project for all MCP operations
  • get_current_project - Verify current project status
• Auto Antigravity MCP Config - Automatically creates MCP config at ~/.gemini/antigravity/mcp_config.json during knowns init
• GEMINI.md sync by default - Now included in default sync targets

Removed

• knowns agents command - Use knowns sync instead
• mcp__knowns__get_guideline tool - Guidelines are now embedded in instruction files (CLAUDE.md, GEMINI.md, AGENTS.md)

Documentation

• Updated MCP integration docs with project detection workflow
• Added Antigravity configuration examples
• Updated all command references to use knowns sync

Migration Guide

For CLI Users

# Before (deprecated)
knowns agents guideline
knowns agents sync

# After
knowns sync
knowns sync --all

For MCP Users (Antigravity/Global Configs)

Add session initialization at the start of each session:

// 1. Detect available projects
mcp__knowns__detect_projects({})

// 2. Set active project
mcp__knowns__set_project({ "projectRoot": "/path/to/project" })

// 3. Verify
mcp__knowns__get_current_project({})

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.5...v0.10.6

Release v0.10.5

What's New

Multi-Timer Support ⏱️

You can now run multiple timers concurrently - one per task. No more stopping your current timer to track time on another task!

• Concurrent timers: Start timers on multiple tasks simultaneously
• Task ID normalization: Use either 42 or task-42 format - both work everywhere
• Interactive selection: When multiple timers are running, CLI prompts you to choose which one to stop/pause

# Start timers on multiple tasks
knowns time start 1
knowns time start 2
knowns time status  # Shows all active timers

# Stop specific timer
knowns time stop 1

Template Import Prefix 📦

Templates from imports are now fully accessible via CLI and MCP using the import prefix.

# View imported template
knowns template knowns/knowns-command

# Run imported template
knowns template run knowns/knowns-command --name myCommand

• CLI/MCP support import-name/template-name syntax
• URL encoding fixed for template names with slashes

TreeView UI 🌳

New hierarchical tree view for better organization:

• DocsPage: Docs organized in collapsible folders
• ImportsPage: Imported files shown in tree structure
• TemplatesPage: Local and imported templates grouped separately
• Orphaned imports: Shows imports on disk but not in config

Bug Fixes 🐛

• Fixed duplicate update notification in CLI
• Fixed URL encoding for imported templates in UI

Changelog

Added

• Multi-timer support with concurrent task tracking
• Task ID normalization (42 and task-42 both valid)
• TreeView component for hierarchical file display
• Import prefix support for templates in CLI/MCP
• resolveTemplate for local and imported template resolution

Changed

• DocsPage, ImportsPage, TemplatesPage now use TreeView
• Update notifier shows only once per session
• Guidelines and skill instructions updated

Fixed

• Duplicate update notification in CLI
• URL encoding for template names with slashes
• Orphaned imports now visible in ImportsPage

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.4...v0.10.5

v0.10.4

Added

• feat(discord): add Discord integration for releases and community HO@howznguyen (#43)

Changed

• feat(discord): add Discord integration for releases and community HO@howznguyen (#43)

Documentation

• feat(discord): add Discord integration for releases and community HO@howznguyen (#43)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.3...v0.10.4

Fixed

• fix(mcp): fix template handler bugs and add syntax pitfall docs HO@howznguyen (#40)

Documentation

• fix(mcp): fix template handler bugs and add syntax pitfall docs HO@howznguyen (#40)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.2...v0.10.3

Fix

• Fix syncImport to bypass "already exists" check with isSync option
• Fix syncAllImports to sync all imports (not just autoSync)
• Add toast notifications for sync success/error in web UI
• Add imports field to config API response
• Improve type safety for imports in config handlers
• Fix auto-expand for imported docs in sidebar
• Add sourceUrl display for imported docs/templates in list commands

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.1...v0.10.2

Fix

File changed: scripts/build-cli.js

Change: Rename createRequire → __createRequire in banner to avoid conflict with fdir package

- import { createRequire } from 'module';
+ import { createRequire as __createRequire } from 'module';
- const require = createRequire(import.meta.url);
+ const require = __createRequire(import.meta.url);

Why: The fdir package also imports createRequire, causing SyntaxError: Identifier 'createRequire' has already been declared on Node.js 24

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.10.0...v0.10.1

v0.10.0

New Features

Template System

• Code generation engine with Handlebars (.hbs) templates
• CLI commands: template list, template run, template create
• MCP handlers for template operations
• Web UI Templates page
• Built-in knowns-command template for scaffolding new CLI commands

Import System

• Import docs/templates from git, npm, or local sources
• Context-aware doc resolution (<GitHubMention username="doc" />/import-name/path)
• Support for import aliases and version pinning
• Commands: import add, import sync, import list

MCP Enhancements

• Full task operations via MCP: addAc, checkAc, uncheckAc, removeAc, plan, notes, appendNotes
• Unified search tool for searching both tasks and docs

Improvements

• Reorganized .knowns/docs into logical folders (ai/, architecture/, core/, development/, github/, templates/)
• Unified CLI/MCP guidelines (removed duplication)
• Added IDE instructions for Cursor and Windsurf
• Broken refs detection with visual indicators in Web UI

Bug Fixes

• Fixed favicon (32x32 and 16x16 versions)
• Static file serving fix for Express server

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.9.0...v0.10.0

v0.9.0

Features

• Skills System: Add knowns sync skills command and 8 Claude Code skills with dot notation (knowns.task, knowns.commit, etc.)
• Smart Doc Reading: Add --smart flag for auto-optimized document reading (full content for small docs, TOC for large docs)
• Section Editing: Add --section with numeric index support for editing specific document sections

Bug Fixes

• UI: Support alphanumeric task IDs in MDRender mentions (<GitHubMention username="task-pdyd2e" /> now renders correctly)

Refactor

• Reference System: Simplify ref format - keep <GitHubMention username="task-xxx" /> and <GitHubMention username="doc" />/xxx as-is instead of expanding to verbose paths
• Guidelines: Update all agent instruction files with simplified ref format

Deprecated

• knowns agents --update-instructions → Use knowns sync agent instead

Documentation

• Add claude-code-skills pattern documentation
• Fix duplicate headers in command-pattern doc

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.9...v0.9.0

New Features

• Smart Document Reading (--smart): New flag for intelligent document reading that automatically handles both small and large documents

  • Small docs (≤2000 tokens): Returns full content automatically
  • Large docs (>2000 tokens): Returns stats + TOC with numbered sections, then use --section <number> to read specific parts
  • Available in both CLI (--smart) and MCP (smart: true)

• Token Count in Doc List: doc list --plain now shows estimated token count for each document, helping AI agents assess document sizes at a glance

Bug Fixes

• Section by Number: Fixed --section to properly support numeric indices from TOC display (e.g., --section 1, --section 4)

Documentation

• Updated CLI and MCP guidelines to recommend using --smart as the default approach for reading documents

Usage

# Always use --smart when reading docs
knowns doc <path> --plain --smart

# If doc is large, smart returns TOC, then read specific section:
knowns doc <path> --plain --section 3

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.8...v0.8.9

Added

• feat(ui): add visual notifications for SSE connection status HO@howznguyen (#30)

Fixed

• [Bug]: [SSE] No visual notification when Server-Sent Events connection is lost (Silent Failure) #28

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.7...v0.8.8

Changed

• refactor(guidelines): split guidelines into cli and mcp variants HO@howznguyen (#26)

Documentation

• refactor(guidelines): split guidelines into cli and mcp variants HO@howznguyen (#26)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.6...v0.8.7

Changed

• chore(deps): replace react-diff-viewer with react19 fork HO@howznguyen (#25)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.5...v0.8.6

v0.8.5

Changed

• Guidelines default: Changed default from minimal to full embedded guidelines - AI now has immediate access to all rules without needing to call extra commands
• Sync command: Replaced --full flag with --minimal (knowns agents sync now uses full guidelines by default)
• Guidelines size: Optimized guidelines from ~1200 to ~600 lines (~50% reduction, ~1.7% context usage)
• Husky pre-commit: Fixed deprecated format and replaced bun with npx for CI compatibility

Added

• Context Optimization section: New guidelines section teaching AI how to reduce token consumption:
• Use --plain flag for compact output
• Search before reading all docs
• Selective file reading with offset/limit
• Write compact notes instead of verbose logs

Fixed

• GitHub Actions workflow failing due to bun not being available in CI environment
• Husky pre-commit hook using deprecated v9 format that will fail in v10

Documentation

• Updated docs/commands.md, docs/ai-workflow.md, docs/configuration.md, docs/user-guide.md, docs/mcp-integration.md to reflect new default behavior

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.4...v0.8.5

v0.8.4

Added

• MCP Auto-Setup: New knowns mcp setup command to automatically configure Claude Code integration
  • --project: Creates .mcp.json in project root for auto-discovery
  • --global: Adds knowns to Claude Code global config via claude mcp add-json
• Auto .mcp.json on Init: When selecting "MCP" as AI Guidelines type during knowns init, automatically creates .mcp.json for Claude Code auto-discovery

Changed

• Simplified Init Wizard: Streamlined from 7+ prompts to 4 essential options:
  • Project name
  • Git tracking mode (git-tracked / git-ignored)
  • AI Guidelines type (CLI / MCP)
  • Agent files to create (CLAUDE.md, AGENTS.md, etc.)
• Removed wizard prompts for: default assignee, default priority, default labels, time format (now uses defaults)

Documentation

• Updated docs/user-guide.md with init wizard examples
• Updated docs/mcp-integration.md with auto-setup instructions
• Updated docs/configuration.md with init wizard section
• Updated docs/commands.md with knowns mcp setup command reference

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.3...v0.8.4

Changed

• refactor(guidelines): modular structure with stage-specific options HO@howznguyen (#18)

Documentation

• refactor(guidelines): modular structure with stage-specific options HO@howznguyen (#18)

Contributors

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.2...v0.8.3

Knowns v0.8.2

What's Changed

Agent Guidelines & Fallbacks

• Unified guidelines now live in shared templates (CLI + MCP + unified) with explicit “must follow” wording.
• MCP agents are instructed to run knowns agents guideline --cli and fall back to CLI commands when MCP tools are missing.
• Added minimal instruction templates for CLI/MCP; removed unused --gemini option and Gemini templates.

CI/CD Fixes

• chore(ci): remove redundant GitHub release step.

Upgrade

npm i -g knowns@0.8.2
# or
pnpm add -g knowns@0.8.2

———

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.1...v0.8.2

Knowns v0.8.1

What's Changed

Global Cache Location

Update notifier cache has been moved from project directory to a global location:

• Before: .knowns/cli-cache.json (inside each project)
• After: ~/.knowns/cli-cache.json (global)

This allows:

• CLI works anywhere, no project context required
• Avoids duplicate cache files across projects
• Consistent with popular CLI tools (~/.npm, ~/.yarn, ...)

CI/CD Fixes

• Auto-bump version from git tag before npm publish
• Removed duplicate workflow file

Upgrade

npm i -g knowns@0.8.1
# or
pnpm add -g knowns@0.8.1

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.8.0...v0.8.1

Release v0.8.0

What's New

Random 6-Character Task IDs

Task IDs now use random 6-character base36 format instead of sequential numbers:

# Old format
task-1, task-2, task-3

# New format
task-a7f3k9, task-m2x8p4, task-k9y2z7

Benefits:

• ~2.1 billion possible IDs
• No ID collision after archiving tasks
• Backward compatible - legacy IDs (task-1) still work

Update Notifier

CLI now checks for updates automatically:

 UPDATE  v1.0.0 available (current v0.8.0) → npm i -g knowns

• 1-hour cache to avoid slowing commands
• Auto-detects package manager (npm/pnpm/yarn/bun)
• Skips on CI, --plain mode, or NO_UPDATE_CHECK=1

CLI Output Improvements

Task list with separators:

48.1 | todo        | high   | Hub Connection Commands
44   | done        | high   | Create condensed guidelines

Search --plain nested format:

Tasks:
  To Do:
    [HIGH] 48.1 - Hub Connection Commands
  Done:
    [HIGH] 43 - Add interactive agents command

Docs:
  (root):
    readme.md - README

Changelog

• feat: add random 6-char task IDs with collision detection
• feat: add npm update notifier with PM detection
• feat: improve task list output with column separators
• feat: change search --plain from CSV to nested format
• docs: add ID strategy documentation
• docs: add update notifier section to CLI guide
• fix: update notifier tests for spacing changes

Upgrade

npm update -g knowns
# or
bun update -g knowns

Thanks

• OL@OliviaAlter for reporting the task ID collision issue #13

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.7.0...v0.8.0

Added

• CLI: --children option - View subtasks directly from parent task (knowns task <id> --children)
• CLI: Improved tree format - Better AI-readable format with > markers for hierarchy
• CLI: Escape sequence parsing - Support \n, \t, \r in CLI inputs for AI agents
• GitHub Automation:
  • Dependabot for automated dependency updates
  • Stale bot for auto-closing inactive issues/PRs
  • Release Drafter for auto-generated release notes
  • Welcome bot for first-time contributors
  • Auto-labeler based on Conventional Commits
• Documentation:
  • Development workflow guide
  • GitHub bots setup guide
  • Release process guide
  • Branch protection rules guide
  • Code of Conduct
  • Contributing guidelines
  • Issue templates (bug report, feature request)
  • Pull request template

Changed

• UI: Config-based status options - Task forms now use status options from config instead of hardcoded values HA@HarryVu176 (#3)
• Release workflow - Automatically bumps package.json version from release tag

Fixed

• UI: Missing status options - Added blocked and in-review status to task dropdown HA@HarryVu176 (#3)

Contributors

HA@HarryVu176 and HO@howznguyen

Full Changelog: https://github.com/knowns-dev/knowns/compare/v0.6.0...v0.7.0

Added

• Git Tracking Mode: Select tracking mode during knowns init
  • git-tracked (default): All .knowns/ files tracked in git (recommended for teams)
  • git-ignored: Only docs tracked, tasks/config ignored (personal use)
  • Automatically updates .gitignore for git-ignored mode
• SSE Auto-Reconnection: Web UI automatically refreshes data on reconnect
  • Detects when connection is restored after sleep/wake
  • Triggers tasks:refresh, time:refresh, docs:refresh events
• New Docs: Added feature documentation
  • features/git-tracking-modes.md - Git tracking modes explained
  • features/real-time-sync.md - SSE sync and reconnection behavior

Changed

• WebSocket → SSE: Migrated real-time updates from WebSocket to Server-Sent Events
  • Simpler protocol with built-in auto-reconnect
  • Better firewall compatibility (standard HTTP)
• Init requires Git: knowns init now checks for .git directory and exits with helpful message if not found
• Documentation Updates:
  • All docs translated to English
  • Updated architecture diagrams (WebSocket → SSE)
  • Added --plain flag clarification (only for view/list/search commands)
  • Added doc organization guide (core docs at root, categorized in folders)

Fixed

• Guidelines clarity: Updated CLI/MCP templates to clarify --plain flag usage
  • --plain only works with view/list/search commands
  • Create/edit commands do NOT support --plain