Web UI Guide

Visual interface for managing tasks, documentation, and specs.

Quick Start

knowns browser

Opens the Web UI at http://localhost:6420.

Options

knowns browser --port 8080      # Custom port
knowns browser --no-open        # Don't open browser

Features

Dashboard

The dashboard provides an overview of your project:

Kanban Board

Drag-and-drop task management with columns:

Actions:

• Drag tasks between columns to change status
• Click task to view/edit details
• Create new tasks with + button

Spec Links: Tasks linked to specs show a clickable spec badge on the card.

Task Details

Click any task to open the detail panel:

• View/edit title and description
• Check/uncheck acceptance criteria
• Update status and priority
• Assign to team members
• View implementation plan and notes
• See time tracking history

Rich Text Editor

Task descriptions and documentation use a BlockNote-based rich text editor:

• Formatting: Bold, italic, strikethrough, underline
• Lists: Bullet lists, numbered lists, checklists
• Code: Inline code and fenced code blocks with syntax highlighting
• Mentions: Type @task- or @doc/ for auto-complete suggestions
• Headings: Multiple heading levels for structure

The editor seamlessly converts to/from markdown for CLI compatibility.

Document Browser

Tree view of all documentation:

docs/
├── patterns/
│   ├── auth.md
│   └── caching.md
├── architecture/
│   └── overview.md
└── guides/
    └── getting-started.md

Features:

• Click folder to expand/collapse
• Click document to view content
• Markdown preview with syntax highlighting
• Reference badges (@task, @doc) are clickable
• Specs filter: Filter to show only spec documents
• Spec badges: Specs show SPEC badge and status (Draft/Approved/Implemented)
• AC Progress: Spec documents show acceptance criteria completion bar
• Linked Tasks: Expand to see all tasks linked to a spec

Global Search

Press Cmd+K (Mac) or Ctrl+K (Windows) to open search.

Search across:

• Task titles and descriptions
• Document titles and content
• Acceptance criteria

Dark Mode

Automatically follows system preference. Toggle manually in the UI.

Keyboard Shortcuts

Real-time Sync

Changes sync in real-time between:

• Multiple browser tabs
• CLI and Web UI
• Team members (same network)

When you run knowns task edit in CLI, the Web UI updates instantly.

Server-Sent Events (SSE)

Knowns uses SSE for real-time updates, providing:

• Reliable one-way data streaming from server
• Automatic reconnection after network interruptions
• Better compatibility than WebSocket across proxies/firewalls

Auto-Reconnection

The Web UI automatically reconnects when:

• Your computer wakes from sleep
• Network connection is restored
• Server restarts

No manual refresh required - updates resume seamlessly.

Reference Badges

Task and doc references render as clickable badges:

Click any badge to navigate to that item.

URL Routing

Direct links to specific views:

Architecture

Browser ←→ Express Server ←→ File System (.knowns/)
              ↕
           SSE (real-time sync)

The Web UI connects to a local Express server that reads/writes to your .knowns/ folder. All data stays on your machine.

Real-time updates use Server-Sent Events (SSE) for reliable, one-way data streaming with automatic reconnection.

Troubleshooting

Port in use

knowns browser --port 6421

Browser doesn't open

knowns browser --no-open
# Then manually open http://localhost:6420

Changes not syncing

1. Check if server is running in terminal
2. Refresh the browser
3. Check browser console for SSE connection errors