bonecode 1.2.0 → 1.2.1

package/README.md

@@ -11,27 +11,90 @@
 npm install -g bonecode
 ```
 
-Then just run it from any project directory:
+Then run it from any project directory:
 
 ```bash
 bonecode
 ```
 
+---
+
+## Interfaces
+
+BoneCode ships three ways to interact with the agent.
+
+### Terminal UI (default)
+
+```bash
+bonecode
+```
+
+Opens an interactive terminal session in the current directory. Type `/` to see all available commands.
+
+| Key | Action |
+|-----|--------|
+| `/` | Show command menu (arrow keys to navigate, Enter/Tab to select) |
+| `Ctrl+C` | Interrupt the current agent request |
+| `Ctrl+D` | Exit |
+| `↑ / ↓` | Scroll through prompt history |
+| `@<path>` | Attach a file (Tab to autocomplete) |
+
+### Web UI
+
+```bash
+bonecode web
+```
+
+Starts the server and opens the web interface in your browser at `http://localhost:3000/ui`.
+
+If you already have the server running separately (`bonecode serve`), just navigate to:
+
+```
+http://localhost:3000/ui
+```
+
+**Build the web UI for production** (optional — the server serves it automatically after building):
+
+```bash
+cd web && npm install && npm run build
+```
+
+The built assets are served from `/ui`. Without a build, the server serves the raw source files in dev mode — functional but without bundling.
+
+**Run the web UI in hot-reload dev mode** (separate terminal):
+
+```bash
+cd web && npm install && npm run dev
+# Opens at http://localhost:5173 with proxy to the BoneCode server
+```
+
+### Headless server
+
+```bash
+bonecode serve
+```
+
+Starts the API server only (no TUI, no browser). Useful for CI, Docker, or connecting your own client.
+
+---
+
 ## Database modes
 
-BoneCode automatically detects what's available and picks the best option:
+BoneCode automatically detects what's available:
 
 | Mode | Setup required | Features |
 |------|---------------|----------|
 | **PostgreSQL** (full) | Docker | Sessions + agents + **pgvector RAG** + hybrid search + durable events |
 | **SQLite** (basic) | Nothing | Sessions + agents only — no RAG, no vector search |
 
-**No Docker?** BoneCode falls back to SQLite automatically. You get a fully working AI coding agent — just without the codebase indexing and RAG features.
+No Docker? BoneCode falls back to SQLite automatically — fully working agent, just without codebase indexing.
 
-**Want the full experience?** Install Docker, then run `bonecode` — it starts the Postgres container for you automatically on first run.
+Want the full experience? Install Docker and run `bonecode` — it starts Postgres automatically on first run.
 
 > Install Docker: https://docs.docker.com/get-docker/
 
+---
+
 ## Configuration
 
 Copy `.env.example` to `.env` and set your LLM provider:
@@ -50,14 +113,77 @@ OPENAI_API_KEY=not-needed
 MODEL_SUPPORTS_TOOLS=false
 ```
 
-For cloud providers (Anthropic, OpenAI, Google) just set the API key — no base URL needed.
+For cloud providers just set the API key — no base URL needed:
+
+```env
+# Anthropic
+ANTHROPIC_API_KEY=sk-ant-...
+DEFAULT_PROVIDER=anthropic
+DEFAULT_MODEL=claude-sonnet-4-5
+
+# OpenAI
+OPENAI_API_KEY=sk-...
+DEFAULT_PROVIDER=openai
+DEFAULT_MODEL=gpt-4o
+
+# Google
+GOOGLE_API_KEY=...
+DEFAULT_PROVIDER=google
+DEFAULT_MODEL=gemini-2.0-flash
+```
+
+---
+
+## CLI commands
+
+```
+bonecode                    Start server + open TUI
+bonecode serve              Start headless server only
+bonecode web                Start server + open web UI in browser
+bonecode run "fix the bug"  Send a one-shot prompt
+bonecode run -i             Interactive terminal mode (no TUI)
+bonecode stats              Show token usage and cost statistics
+bonecode export [id]        Export a session as JSON
+bonecode pr <number>        Checkout a GitHub PR branch
+bonecode github install     Show GitHub Actions agent setup
+bonecode compile            Recompile .bone domain models
+bonecode migrate            Run database migrations
+bonecode status             Check if server is running
+bonecode --version          Show version
+```
+
+### Stats
+
+```bash
+bonecode stats                  # all-time usage
+bonecode stats --days 7         # last 7 days
+bonecode stats --models 5       # show top 5 models
+bonecode stats --tools          # show tool usage breakdown
+```
+
+### Export
+
+```bash
+bonecode export                 # export most recent session
+bonecode export <session-id>    # export specific session
+bonecode export --sanitize      # redact file paths, tool outputs, etc.
+bonecode export > session.json  # pipe to file
+```
+
+---
 
 ## What's different from OpenCode
 
-- **BoneScript backend** — all domain models (sessions, agents, RAG, workspaces) are declared in `.bone` files and compiled to a full Node.js + Express backend with state machines, saga flows, and durable events
-- **pgvector RAG** — codebase indexing with hybrid search (vector + BM25 full-text + RRF fusion). Works without an embedding model using structural context (git recency, import graph, FTS)
-- **Single command** — `bonecode` starts everything in one process, no separate server terminal needed
-- **SQLite fallback** — works out of the box without Docker for users who just want the agent
+- **BoneScript backend** — domain models declared in `.bone` files, compiled to Express + state machines + saga flows + durable events
+- **pgvector RAG** — hybrid search (vector + BM25 + RRF fusion), works without an embedding model using structural context
+- **Web UI** — browser interface at `/ui` in addition to the TUI
+- **mDNS discovery** — server announces itself as `bonecode.local` on the local network
+- **Cursor pagination** — v2 session and message APIs support bidirectional keyset pagination
+- **Subagent spawning** — `POST /v2/session/:id/subagent` creates and runs a child session
+- **Single command** — `bonecode` starts everything in one process
+- **SQLite fallback** — works out of the box without Docker
+
+---
 
 ## Architecture
 
@@ -77,8 +203,18 @@ BoneCode/
 │   ├── cli.ts          # bonecode CLI entry point
 │   ├── tui.ts          # Interactive terminal UI
 │   ├── server.ts       # Express server (auto Postgres/SQLite)
+│   ├── mdns.ts         # mDNS/Bonjour local network discovery
+│   ├── stats.ts        # Token/cost statistics
+│   ├── export.ts       # Session export with PII redaction
 │   ├── db_adapter.ts   # Database detection + SQLite shim
 │   └── engine/         # Agent loop, tools, context builder
+├── web/                # Web UI (vanilla TypeScript + Vite)
+│   ├── index.html
+│   ├── src/
+│   │   ├── main.ts     # Entry point
+│   │   ├── app.ts      # Main app class
+│   │   └── api.ts      # API client
+│   └── vite.config.ts  # Dev server with proxy to :3000
 ├── compat/
 │   └── opencode_adapter.ts  # OpenCode v2 API compatibility layer
 └── extensions/         # Custom extension points (embeddings, chunking, etc.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bonecode",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "private": false,
   "description": "BoneCode — a production-grade AI coding agent with BoneScript-generated backend and pgvector RAG",
   "keywords": [