@versdotsh/reef 0.1.2 → 0.1.3

package/examples/services/board/README.md

@@ -0,0 +1,36 @@
+# board
+
+Shared task tracking for agent fleets. Tasks move through a review workflow: `open` → `in_progress` → `in_review` → `done`. Agents claim tasks, add notes and artifacts, bump priority, and submit work for review.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/board/tasks` | Create a task |
+| `GET` | `/board/tasks` | List tasks (filter: `?status=`, `?assignee=`, `?tag=`) |
+| `GET` | `/board/tasks/:id` | Get a task |
+| `PATCH` | `/board/tasks/:id` | Update a task |
+| `DELETE` | `/board/tasks/:id` | Delete a task |
+| `POST` | `/board/tasks/:id/bump` | Bump priority score |
+| `POST` | `/board/tasks/:id/notes` | Add a note |
+| `GET` | `/board/tasks/:id/notes` | List notes |
+| `POST` | `/board/tasks/:id/artifacts` | Attach an artifact |
+| `POST` | `/board/tasks/:id/review` | Submit for review |
+| `POST` | `/board/tasks/:id/approve` | Approve (sets status to `done`) |
+| `POST` | `/board/tasks/:id/reject` | Reject (sets status back to `open`) |
+| `GET` | `/board/review` | List tasks awaiting review |
+| `GET` | `/board/_panel` | UI panel (HTML fragment) |
+
+## Tools
+
+- `board_create_task` — create a task with title, description, assignee, tags
+- `board_list_tasks` — list/filter tasks
+- `board_update_task` — update status, assignee, title, tags
+- `board_add_note` — add a finding, question, or update note
+
+## Events
+
+Emits to the server-side event bus:
+- `board:task_created` — `{ task }`
+- `board:task_updated` — `{ task, changes }`
+- `board:task_deleted` — `{ taskId }`

package/examples/services/commits/README.md

@@ -0,0 +1,12 @@
+# commits
+
+VM snapshot ledger. Records which VMs were committed, when, by whom, and with what labels. Useful for tracking golden images, rollback points, and the evolution of your fleet's VM state.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/commits` | Record a commit (`{ commitId, vmId, label?, agent, tags? }`) |
+| `GET` | `/commits` | List commits (filter: `?tag=`, `?agent=`, `?label=`, `?vmId=`) |
+| `GET` | `/commits/:commitId` | Get a commit by commitId |
+| `DELETE` | `/commits/:commitId` | Delete a commit record |

package/examples/services/feed/README.md

@@ -0,0 +1,29 @@
+# feed
+
+Activity event stream for coordination and observability. Services publish events, agents and dashboards consume them. Supports SSE streaming for real-time updates.
+
+Automatically listens for server-side events from other modules:
+- `board:task_created` → feed event `task_started`
+- `board:task_updated` → feed event `task_completed` (when status becomes `done`)
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/feed/events` | Publish an event |
+| `GET` | `/feed/events` | List events (filter: `?agent=`, `?type=`, `?since=`, `?limit=`) |
+| `GET` | `/feed/events/:id` | Get an event |
+| `DELETE` | `/feed/events` | Clear all events |
+| `GET` | `/feed/stats` | Event count statistics |
+| `GET` | `/feed/stream` | SSE stream of new events |
+| `GET` | `/feed/_panel` | UI panel (HTML fragment) |
+
+## Tools
+
+- `feed_publish` — publish an event with agent, type, summary, and optional detail
+- `feed_list` — list/filter recent events
+- `feed_stats` — get summary statistics
+
+## Behaviors
+
+Auto-publishes feed events when board tasks are created or completed.

package/examples/services/journal/README.md

@@ -0,0 +1,15 @@
+# journal
+
+Personal narrative log for agents. Like `log` but with mood/vibe tagging — agents reflect on their work, record observations, and track how things are going. Useful for building agent personality and self-awareness over time.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/journal` | Write an entry (`{ text, author, mood?, tags? }`) |
+| `GET` | `/journal` | List entries |
+| `GET` | `/journal/raw` | Plain text format |
+
+## Tools
+
+- `journal_entry` — write a journal entry with optional mood and tags

package/examples/services/log/README.md

@@ -0,0 +1,16 @@
+# log
+
+Append-only work log. Agents write timestamped entries about what they're doing — like Carmack's `.plan` file. Useful for debugging, auditing, and keeping a shared record of fleet activity.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/log` | Append an entry (`{ text, agent }`) |
+| `GET` | `/log` | List entries (filter: `?last=1h`, `?last=7d`) |
+| `GET` | `/log/raw` | Plain text format |
+
+## Tools
+
+- `log_append` — append a work log entry
+- `log_query` — query entries by time range (`since`, `until`, `last`)

package/examples/services/registry/README.md

@@ -0,0 +1,26 @@
+# registry
+
+VM service discovery for agent fleets. Agents register themselves with a role, address, and capabilities. Other agents discover peers by role. Heartbeats keep registrations alive.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/registry/vms` | Register a VM |
+| `GET` | `/registry/vms` | List VMs (filter: `?role=`, `?status=`) |
+| `GET` | `/registry/vms/:id` | Get a VM |
+| `PATCH` | `/registry/vms/:id` | Update a VM |
+| `DELETE` | `/registry/vms/:id` | Deregister a VM |
+| `POST` | `/registry/vms/:id/heartbeat` | Send heartbeat |
+| `GET` | `/registry/discover/:role` | Discover VMs by role |
+
+## Tools
+
+- `registry_list` — list VMs, optionally filter by role or status
+- `registry_register` — register a VM with id, name, role, address, services
+- `registry_discover` — find VMs by role (worker, lieutenant, etc.)
+- `registry_heartbeat` — keep a registration alive
+
+## Behaviors
+
+Auto-registers and auto-heartbeats when running as part of a fleet.

package/examples/services/reports/README.md

@@ -0,0 +1,12 @@
+# reports
+
+Markdown reports. Agents write structured reports — sprint summaries, investigation findings, status updates. Stored with title, author, tags, and timestamp.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/reports` | Create a report (`{ title, content, author, tags? }`) |
+| `GET` | `/reports` | List reports |
+| `GET` | `/reports/:id` | Get a report |
+| `DELETE` | `/reports/:id` | Delete a report |

package/examples/services/ui/README.md

@@ -0,0 +1,22 @@
+# ui
+
+Web dashboard with magic link auth, dynamic panel discovery, and chat interface. Mounts at root — serves `/ui/*` and `/auth/*`.
+
+The UI discovers panels from other services at runtime. Any service that serves `GET /_panel` gets a tab in the dashboard. The chat tab connects to the agent service via SSE for streaming conversations with pi.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/auth/magic-link` | Generate a one-time login URL |
+| `GET` | `/ui/login` | Magic link landing page (sets session cookie) |
+| `GET` | `/ui/` | Dashboard shell |
+| `GET` | `/ui/static/:file` | Static assets (JS, CSS) |
+| `ALL` | `/ui/api/*` | Auth proxy — injects bearer token so the browser never needs it |
+
+## How it works
+
+1. **Auth**: `POST /auth/magic-link` with bearer token → returns a URL. Opening it sets a 24h session cookie.
+2. **Panel discovery**: The dashboard polls `GET /services` every 30s, fetches `GET /<service>/_panel` for each, and injects the HTML as tabs.
+3. **Chat**: Creates a pi RPC session via the agent service, streams responses via SSE, renders markdown with collapsible tool calls.
+4. **API proxy**: All requests to `/ui/api/*` are forwarded with the bearer token from the session, so panel scripts and chat can call any service endpoint without exposing the token to the browser.

package/examples/services/usage/README.md

@@ -0,0 +1,25 @@
+# usage
+
+Cost and token tracking for agent fleets. Records per-session token usage, cost breakdowns, and VM lifecycle events. Provides summaries by agent and time range.
+
+Depends on `feed` — publishes `agent_stopped` events when sessions end.
+
+## Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/usage` | Usage summary (filter: `?range=7d`) |
+| `POST` | `/usage/sessions` | Record a session |
+| `GET` | `/usage/sessions` | List sessions (filter: `?agent=`, `?range=`) |
+| `POST` | `/usage/vms` | Record a VM lifecycle event |
+| `GET` | `/usage/vms` | List VM records |
+
+## Tools
+
+- `usage_summary` — get cost & token totals by agent and time range
+- `usage_sessions` — list session records with tokens, cost, turns, tool calls
+- `usage_vms` — list VM lifecycle records
+
+## Behaviors
+
+Auto-records usage data from feed events.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@versdotsh/reef",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Self-improving fleet infrastructure — the minimum kernel agents need to build their own tools",
   "type": "module",
   "scripts": {