Improve README and add developer documentation

knowsuchagency · knowsuchagency · commit 24c299783916 · 2025-12-23T16:48:09.000Z
- Rewrite README to be user-focused with Claude Code first philosophy
- Add complete CLI and configuration documentation
- Move Chinese/z.ai mentions to bottom
- Extract developer docs into DEVELOPMENT.md
- Fix missing `done` action in current-task CLI command
- Bump version to 1.13.1
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
@@ -0,0 +1,125 @@
+# Development
+
+## Prerequisites
+
+- [mise](https://mise.jdx.dev/) for task running and tool management
+- [Bun](https://bun.sh/) (installed automatically via mise)
+
+## Getting Started
+
+```bash
+# Install tools and dependencies
+mise install
+
+# Start both frontend and backend (recommended)
+mise run dev
+
+# Or run separately:
+mise run server    # Backend (port 3333, with auto-reload)
+mise run client    # Frontend (port 5173, proxies to backend)
+```
+
+Development mode defaults to `~/.vibora/dev` (port 3222) to keep development data separate from production.
+
+## Available Tasks
+
+```bash
+mise run dev          # Start frontend and backend dev servers
+mise run server       # Start backend dev server with auto-reload
+mise run client       # Start frontend dev server
+mise run build        # Build for production
+mise run start        # Run production server
+mise run up           # Build and start production server as daemon
+mise run down         # Stop the daemon server
+mise run check        # Run all checks (lint + typecheck)
+mise run lint         # Run ESLint
+mise run typecheck    # Check TypeScript types
+mise run preview      # Preview production build
+
+# Database operations
+mise run db:push      # Sync schema to database
+mise run db:studio    # Open Drizzle Studio GUI
+mise run db:generate  # Generate migrations
+mise run db:migrate   # Apply migrations
+
+# CLI package
+mise run cli:build    # Bundle server, copy frontend, generate migrations
+mise run cli:publish  # Publish to npm (runs cli:build first)
+
+# Version management
+mise run bump         # Bump patch version (or: bump major, bump minor)
+```
+
+## Architecture
+
+### Frontend (`src/`)
+- **React 19** with TanStack Router (file-based routing in `src/routes/`)
+- **TanStack React Query** for server state
+- **shadcn/ui** (v4 with baseui support) for UI components
+- **xterm.js** for terminal emulation
+- Components organized by feature: `kanban/`, `terminal/`, `viewer/`, `ui/`
+- Path alias: `@` → `./src/`
+
+### Backend (`server/`)
+- **Hono.js** framework on Bun runtime
+- **SQLite** database with Drizzle ORM
+- **WebSocket** for real-time terminal I/O (`@hono/node-ws`)
+- **bun-pty** for PTY management
+
+### Key Data Flows
+- REST API (`/api/*`) for task CRUD, git operations, config
+- WebSocket (`/ws/terminal`) for terminal I/O multiplexing
+- Frontend uses relative URLs - Vite proxies to backend in dev
+
+## Database
+
+- Default location: `~/.vibora/vibora.db` (SQLite with WAL mode)
+- Schema: `server/db/schema.ts`
+
+### Tables
+
+- **tasks** - Task metadata, git worktree paths, status, Linear integration, PR tracking
+- **repositories** - Saved git repositories with startupScript and copyFiles patterns
+- **terminalTabs** - First-class tab entities for terminal organization
+- **terminals** - Terminal instances with dtach session backing
+- **terminalViewState** - Singleton UI state persistence (active tab, focused terminals)
+
+Task statuses: `IN_PROGRESS`, `IN_REVIEW`, `DONE`, `CANCELED`
+
+## File Organization
+
+```
+src/
+  routes/          # Pages (TanStack Router)
+  components/      # React components by feature
+  hooks/           # Custom hooks (use-tasks, use-terminal-ws, etc.)
+server/
+  routes/          # REST API handlers (/api/*)
+  services/        # Business logic (pr-monitor, linear, task-status, notifications)
+  terminal/        # PTY management (pty-manager, buffer-manager)
+  websocket/       # WebSocket protocol for terminal I/O (/ws/terminal)
+  db/              # Drizzle schema and initialization
+  lib/             # Shared utilities (settings, etc.)
+shared/            # Shared types (frontend, backend, CLI)
+cli/
+  src/             # CLI source (commands, utils)
+  server/          # Bundled server (generated)
+  dist/            # Frontend build (generated)
+  drizzle/         # SQL migrations (generated)
+```
+
+## CLI Package
+
+The `@vibora/cli` package provides a global CLI for running Vibora as a daemon. The built CLI package includes:
+
+- `cli/server/index.js` - Bundled server
+- `cli/dist/` - Pre-built frontend assets
+- `cli/drizzle/` - SQL migrations
+- `cli/lib/librust_pty.so` - Native PTY library
+
+### Building
+
+```bash
+mise run cli:build    # Bundle server, copy frontend, generate migrations
+mise run cli:publish  # Publish to npm (runs cli:build first)
+```
diff --git a/README.md b/README.md
@@ -2,14 +2,11 @@
 
 ![vibora](https://github.com/user-attachments/assets/fed72bab-0e66-42f3-91ac-8e024372685c)
 
-
 The Vibe Engineer's Cockpit. Vibora marries basic project management with actual software development by embedding terminals directly into the workflow.
 
-Available in English and Chinese. Works with [z.ai](https://z.ai) for Claude Code proxy integration.
-
 ## Philosophy
 
-- **Terminal-first AI agent orchestration** — Agents (Claude Code, Codex, etc.) run in terminals as-is. No abstraction layer, no wrapper APIs, no feature parity maintenance as agents evolve.
+- **Claude Code first** — Built for developers who prefer working in the terminal with CLI agents. Vibora is designed with Claude Code in mind, though it works with other CLI agents (Codex, Gemini CLI, etc.). No abstraction layer, no wrapper APIs—agents run in terminals as-is.
 - **Opinionated with few opinions** — Provides structure without dictating workflow.
 - **Git worktree isolation** — Tasks create isolated git worktrees, with architecture supporting evolution toward more general task types.
 
@@ -21,113 +18,144 @@ Requires [Node.js](https://nodejs.org/). Run the latest vibora with a single com
 npx vibora@latest up
 ```
 
-This starts the vibora server as a daemon. Open http://localhost:3333 in your browser. The `up` command will help you install any missing dependencies.
+This starts the Vibora server as a daemon. Open http://localhost:3333 in your browser. The `up` command will help you install any missing dependencies.
 
 ```bash
 npx vibora@latest down    # Stop the server
 npx vibora@latest status  # Check if running
 ```
 
-## Tech Stack
-
-- **Frontend**: React 19, TanStack Router & Query, xterm.js, Tailwind CSS, shadcn/ui (v4 with baseui support)
-- **Backend**: Hono.js on Bun, SQLite with Drizzle ORM, WebSocket for terminal I/O
-
 ## Configuration
 
-Settings are stored in `.vibora/settings.json`.
+Settings are stored in `.vibora/settings.json`. The vibora directory is resolved in this order:
+
+1. `VIBORA_DIR` environment variable (explicit override)
+2. `.vibora` in current working directory (per-worktree isolation)
+3. `~/.vibora` (default)
 
 | Setting | Env Var | Default |
 |---------|---------|---------|
-| (base directory) | `VIBORA_DIR` | .vibora in CWD or ~/.vibora |
 | port | `PORT` | 3333 |
 | defaultGitReposDir | `VIBORA_GIT_REPOS_DIR` | ~ |
 | taskCreationCommand | `VIBORA_TASK_CREATION_COMMAND` | `claude --dangerously-skip-permissions` |
 | hostname | `VIBORA_HOSTNAME` | (empty) |
 | sshPort | `VIBORA_SSH_PORT` | 22 |
+| basicAuthUsername | `VIBORA_BASIC_AUTH_USERNAME` | null |
+| basicAuthPassword | `VIBORA_BASIC_AUTH_PASSWORD` | null |
 | linearApiKey | `LINEAR_API_KEY` | null |
 | githubPat | `GITHUB_PAT` | null |
+| language | — | null (auto-detect) |
 
-Notification settings (sound, Slack, Discord, Pushover) are configured via the Settings UI and stored in `settings.json`.
+Notification settings (sound, Slack, Discord, Pushover) are configured via the Settings UI or CLI and stored in `settings.json`.
 
 Precedence: environment variable → settings.json → default
 
-## Development
-
-### Prerequisites
-
-- [mise](https://mise.jdx.dev/) for task running and tool management
-- [Bun](https://bun.sh/) (installed automatically via mise)
+### Linear Integration
 
-### Development
+Vibora can sync task status with Linear tickets. Configure `linearApiKey` in settings or set the `LINEAR_API_KEY` environment variable.
 
 ```bash
-# Install tools and dependencies
-mise install
-
-# Start both frontend and backend (recommended)
-mise run dev
-
-# Or run separately:
-mise run server    # Backend (port 3333, with auto-reload)
-mise run client    # Frontend (port 5173, proxies to backend)
+# Link current task to a Linear ticket
+vibora current-task linear https://linear.app/team/issue/TEAM-123
 ```
 
-### Available Tasks
+When a task status changes in Vibora, the linked Linear ticket status is updated automatically.
 
-```bash
-mise run dev          # Start frontend and backend dev servers
-mise run server       # Start backend dev server with auto-reload
-mise run client       # Start frontend dev server
-mise run build        # Build for production
-mise run start        # Run production server
-mise run lint         # Run ESLint
-mise run preview      # Preview production build
-
-# Database operations
-mise run db:push      # Sync schema to database
-mise run db:studio    # Open Drizzle Studio GUI
-mise run db:generate  # Generate migrations
-mise run db:migrate   # Apply migrations
-```
+### Basic Auth
+
+Set `basicAuthUsername` and `basicAuthPassword` (via settings or environment variables) to require authentication. Useful when exposing Vibora over a network.
 
 ## CLI
 
 The CLI lets AI agents (like Claude Code) working inside task worktrees query and update task status.
 
-### Usage
+### Server Management
 
 ```bash
-# Get current task (auto-detected from worktree path)
-vibora current-task
+vibora up                        # Start server daemon
+vibora down                      # Stop server
+vibora status                    # Check server status
+vibora health                    # Check server health
+```
+
+### Current Task (auto-detected from worktree)
 
-# Update task status
+```bash
+vibora current-task              # Get current task info
 vibora current-task in-progress  # Mark as IN_PROGRESS
 vibora current-task review       # Mark as IN_REVIEW
 vibora current-task done         # Mark as DONE
-vibora current-task cancel       # Mark as CANCELLED
+vibora current-task cancel       # Mark as CANCELED
+vibora current-task pr <url>     # Associate a PR with current task
+vibora current-task linear <url> # Link to a Linear ticket
+```
 
-# Server management
-vibora up                        # Start server daemon
-vibora down                      # Stop server
-vibora status                    # Check server status
+### Task Management
 
-# Task management
+```bash
 vibora tasks list                # List all tasks
 vibora tasks get <id>            # Get task by ID
+vibora tasks create              # Create a new task
+vibora tasks update <id>         # Update a task
+vibora tasks move <id>           # Move task to different status
+vibora tasks delete <id>         # Delete a task
+```
+
+### Git Operations
 
-# Git operations
+```bash
 vibora git status                # Git status for current worktree
 vibora git diff                  # Git diff for current worktree
+vibora git branches              # List branches in a repo
+```
+
+### Worktrees
+
+```bash
+vibora worktrees list            # List all worktrees
+vibora worktrees delete          # Delete a worktree
+```
+
+### Configuration
+
+```bash
+vibora config get <key>          # Get a config value
+vibora config set <key> <value>  # Set a config value
 ```
 
-### Options
+### Notifications
 
 ```bash
---port=<port>   # Server port (default: 3333)
---pretty        # Pretty-print JSON output
+vibora notifications             # Show notification settings
+vibora notifications enable      # Enable notifications
+vibora notifications disable     # Disable notifications
+vibora notifications test <ch>   # Test a channel (sound, slack, discord, pushover)
+vibora notifications set <ch> <key> <value>
+                                 # Set a channel config
+
+vibora notify <title> [message]  # Send a notification to all enabled channels
 ```
 
+### Global Options
+
+```bash
+--port=<port>     # Server port (default: 3333)
+--url=<url>       # Override full server URL
+--pretty          # Pretty-print JSON output
+```
+
+## Internationalization
+
+Available in English and Chinese. Set the `language` setting or let it auto-detect from your browser.
+
+## z.ai Integration
+
+Works with [z.ai](https://z.ai) for Claude Code proxy integration. Configure via the Settings UI.
+
+## Development
+
+See [DEVELOPMENT.md](DEVELOPMENT.md) for development setup, architecture, and contributing guidelines.
+
 ## License
 
 [PolyForm Shield 1.0.0](LICENSE)
diff --git a/cli/src/commands/current-task.ts b/cli/src/commands/current-task.ts
@@ -5,6 +5,7 @@ import type { TaskStatus } from '@shared/types'
 
 const STATUS_MAP: Record<string, TaskStatus> = {
   review: 'IN_REVIEW',
+  done: 'DONE',
   cancel: 'CANCELED',
   'in-progress': 'IN_PROGRESS',
 }
@@ -103,7 +104,7 @@ export async function handleCurrentTaskCommand(
   if (!newStatus) {
     throw new CliError(
       'INVALID_ACTION',
-      `Unknown action: ${action}. Valid actions: review, cancel, in-progress, pr, linear`,
+      `Unknown action: ${action}. Valid actions: in-progress, review, done, cancel, pr, linear`,
       ExitCodes.INVALID_ARGS
     )
   }
diff --git a/package.json b/package.json
@@ -1,7 +1,7 @@
 {
   "name": "vibora",
   "private": true,
-  "version": "1.13.0",
+  "version": "1.13.1",
   "description": "The Vibe Engineer's Cockpit",
   "license": "PolyForm-Shield-1.0.0",
   "type": "module",

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@ import type { TaskStatus } from '@shared/types'`
`5`	`5`
`6`	`6`	`const STATUS_MAP: Record<string, TaskStatus> = {`
`7`	`7`	`review: 'IN_REVIEW',`
	`8`	`+ done: 'DONE',`
`8`	`9`	`cancel: 'CANCELED',`
`9`	`10`	`'in-progress': 'IN_PROGRESS',`
`10`	`11`	`}`
`@@ -103,7 +104,7 @@ export async function handleCurrentTaskCommand(`
`103`	`104`	`if (!newStatus) {`
`104`	`105`	`throw new CliError(`
`105`	`106`	`'INVALID_ACTION',`
`106`		- `Unknown action: ${action}. Valid actions: review, cancel, in-progress, pr, linear`,
	`107`	+ `Unknown action: ${action}. Valid actions: in-progress, review, done, cancel, pr, linear`,
`107`	`108`	`ExitCodes.INVALID_ARGS`
`108`	`109`	`)`
`109`	`110`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "vibora",`
`3`	`3`	`"private": true,`
`4`		`- "version": "1.13.0",`
	`4`	`+ "version": "1.13.1",`
`5`	`5`	`"description": "The Vibe Engineer's Cockpit",`
`6`	`6`	`"license": "PolyForm-Shield-1.0.0",`
`7`	`7`	`"type": "module",`