shraga 0.1.6 → 0.1.8

package/README.md

@@ -9,23 +9,24 @@
 
 </div>
 
-Shraga is a self-hostable, multi-user web UI for running an AI coding agent (Claude Code out of
-the box, with a pluggable engine seam for other runtimes) that you can reach from anywhere: your
+Shraga is a self-hostable, multi-user agent harness that joins your team as a teammate (Claude Code
+out of the box, with a pluggable engine seam for other runtimes), reachable from anywhere: your
 laptop, a home server, or a VM.
 
 Give it its own machine, its own keys, its own identity. Onboard it once, then delegate.
 
 ## Why Shraga
 
-- ⭐ **Runs on your Claude subscription, not a metered API key.** Point it at Claude Code and it
-  drives the agent through your exsiting plan (`claude auth login`). No per-token bill to watch.
+- ⭐ **Runs on your Claude subscription, or via an API key.** Point it at Claude Code and it
+  drives the agent through your exsiting plan (`claude auth login`), or set `ANTHROPIC_API_KEY` to
+  pay per token if you prefer.
 - ⭐ **A real teammate, not a chat box.** It has its own machine, its own identity, and its own
   logins, so you delegate a task the way you would to a person and come back to the result.
 - ⭐ **Multi-user by design.** One Shraga serves a whole team, each with their own sessions,
   tools, and permissions.
 - ⭐ **A shared brain that compounds.** It onboards, learns your codebase and conventions, and
   carries that knowledge forward via skills and sessions. The full org-wide capture is the
-  north star ([the shared brain](./docs/shared-brain.md)) — it opens in stages.
+  north star ([the shared brain](./docs/shared-brain.md)); it opens in stages.
 - **Chat with an agent** that has your workspace, shell, and tools.
 - **Sessions** you can fork, resume, and revisit.
 - **Skills**: reusable procedures you teach it once (files in `data/skills/`).
@@ -35,39 +36,39 @@ Give it its own machine, its own keys, its own identity. Onboard it once, then d
 
 ## What's in the box
 
-Shraga ships as a small core (this repo, the `shraga` npm package — "CE") plus two ways to grow it.
-Capabilities fall into three tiers:
+Shraga is a small core (this repo, the `shraga` npm package) plus two ways to grow it. Capabilities
+fall into three groups:
 
-- **Built-in** — ships and runs in CE. Nothing to install; some need credentials configured.
-- **Optional overlay** — an external add-on module loaded at startup via `SHRAGA_OVERLAY`. Not in
-  this repo; you bring or build it.
-- **Bring-your-own** — you extend the core yourself through its seams (MCP, engine, skills, features).
+- **Built-in**: ships in this repo and runs out of the box. Nothing to install; some need
+  credentials configured.
+- **Optional add-on**: an external module the core loads at startup when you set `SHRAGA_OVERLAY`
+  to point at it. These live outside this repo and attach through the same seams the built-ins use.
+- **Bring-your-own**: you extend the core yourself through its seams (MCP, engine, skills, features).
 
-### Built-in (ships in CE)
+### Built-in
 
 | Capability | What you get | Setup |
 |-----------|--------------|-------|
 | **Agent chat & sessions** | Chat with an agent that has your workspace, shell, and tools; fork, resume, and revisit sessions. | none |
-| **Slack** | The agent is **active on Slack** — it replies in threads, manages reactions, handles uploaded files, resolves `@mentions`, and runs polls. Via the public [`mcp-slack-use`](https://github.com/Livshitz/mcp-slack-use) package. | Slack app + tokens |
+| **Slack** | The agent is **active on Slack**: it replies in threads, manages reactions, handles uploaded files, resolves `@mentions`, and runs polls. Via the public [`mcp-slack-use`](https://github.com/Livshitz/mcp-slack-use) package. | Slack app + tokens |
 | **Scheduler** | Cron schedules and event-triggered tasks that run agent jobs unattended. | none |
 | **Events** | Generic event-bus ingress (`POST /api/events/:source`) that fires matching schedules. | none |
 | **Push notifications** | Web and native push. | none |
-| **Artifacts** | Render HTML artifacts from a session. (PNG export is overlay-only — see below.) | none |
-| **MCP — both directions** | *Consume* external MCP servers to give the agent tools, **and** *expose* Shraga itself as an MCP endpoint (`POST /mcp`) so claude.ai and other clients can drive it. | per-server config |
+| **Artifacts** | Render HTML artifacts from a session. (PNG export is an optional add-on, see below.) | none |
+| **MCP (both directions)** | *Consume* external MCP servers to give the agent tools, **and** *expose* Shraga itself as an MCP endpoint (`POST /mcp`) so claude.ai and other clients can drive it. | per-server config |
 | **Engine seam** | Pluggable agent runtime. Claude Code is the built-in engine. | none |
 | **Auth** | Local username/password by default; Firebase optional (`AUTH_PROVIDER=firebase`). | none / Firebase config |
 | **CLI** | `shraga` server bin plus `shraga user add <email> <password>` to seed a local user. | none |
 
-### Optional overlay (add-on module, not in CE)
+### Optional add-ons (plug in an external module)
 
-Loaded only when you point `SHRAGA_OVERLAY` at an external module. **None of these ship in this
-repo** — a bare self-host does not get them out of the box:
+Loaded only when you point `SHRAGA_OVERLAY` at an external module. **None of these ship in
+this repo**, so a bare self-host does not get them out of the box:
 
 | Capability | Notes |
 |-----------|-------|
-| **Email / Gmail** | Inbound email → agent sessions. **Not built-in** — overlay only. |
+| **Email / Gmail** | Inbound email to agent sessions. **Not built-in** (add-on only). |
 | **GitHub bot** | Issues/PRs → agent sessions with GH-native trust tiers. |
-| **Voice** | Voice input/output. |
 | **Fleet / multi-instance** | Blue-green and multi-instance orchestration. |
 | **PNG artifact export** | Puppeteer-rendered PNGs of artifacts. |
 
@@ -84,13 +85,13 @@ The core is deliberately small and grows through documented seams (see
 | **Server features** (`src/server/features.ts`) | Mount new server-side surfaces via `registerFeature`. |
 | **Client slots** (`src/client/lib/slots.tsx`) | Inject UI into typed render slots without touching core. |
 | **Route extensions** (`data/extensions/*.ext.ts`) | Drop-in public routes (webhooks, OAuth callbacks) per deployment. |
-| **`SHRAGA_OVERLAY`** | Load a whole external add-on module at startup (the overlay tier above). |
+| **`SHRAGA_OVERLAY`** | Load a whole external add-on module at startup (the optional add-ons above). |
 
 ## Use as a library
 
 Shraga's first-class surface is the `createShraga` factory (the package `main`/`exports`). You
 `import` it, wire your registrations against the same seams the built-ins use, then own the
-lifecycle — `start()` returns a handle you can `stop()`. The CLI and the run-from-source entry are
+lifecycle. `start()` returns a handle you can `stop()`. The CLI and the run-from-source entry are
 thin wrappers over this exact call (`createShraga(fromEnv()).start()`).
 
 ```ts
@@ -129,18 +130,34 @@ registerExtension, registerWebhook, stop }`.
 
 **Runtime plug-and-play is opt-in.** `registerFeature`/`registerEngine`/`registerExtension`/
 `registerWebhook`/`on` are meant to run **before** `start()`. If you need to register *after* boot,
-set `runtimeRegistration: true` (or `SHRAGA_RUNTIME_REGISTRATION=1`) — then the `ServerHandle`'s
+set `runtimeRegistration: true` (or `SHRAGA_RUNTIME_REGISTRATION=1`), and then the `ServerHandle`'s
 `registerExtension`/`registerWebhook`/`on` mount onto the live extension Router / event bus.
 Default is **off**, and those handle methods throw until you enable it. Only extensions, webhooks
-and event subscriptions are runtime-registerable — features and engines mount at boot and are never
+and event subscriptions are runtime-registerable; features and engines mount at boot and are never
 runtime-registerable, on or off.
 
+## Spin one up with your coding agent
+
+Hand this to Claude Code (or Cursor, Codex, any coding agent) and let it stand up your instance:
+
+```text
+Set up a self-hosted Shraga instance for me (https://github.com/Livshitz/shraga).
+- Runtime is Bun. Simplest run: `bunx shraga` (serves on :3032, state in ./data).
+- To customize/extend, scaffold a tiny Bun app that depends on `shraga` and does:
+    import { createShraga } from 'shraga';
+    await createShraga({ port: 3032, authProvider: 'local' }).start();
+  Register any features/webhooks/engines before .start() (see the "Use as a library" section).
+- Auth: run `claude auth login` to use my Claude subscription, or set ANTHROPIC_API_KEY.
+- Create my first account (`shraga user add <email> <password>`), then tell me the URL to open.
+Read the README + AGENTS.md for the seams before adding anything custom.
+```
+
 ## Quickstart (CLI)
 
-Requires [Bun](https://bun.sh) ≥ 1.0. Env-configured, no code — this is the `createShraga(fromEnv())`
+Requires [Bun](https://bun.sh) ≥ 1.0. Env-configured, no code; this is the `createShraga(fromEnv())`
 tier.
 
-**Fastest — run from npm:**
+**Fastest, run from npm:**
 
 ```bash
 bunx shraga                   # serve on http://localhost:3032, state in ./data/
@@ -189,6 +206,27 @@ common ones:
 | `AUTH_PROVIDER` | `local` | `local` (username/password) or `firebase` |
 | `OWNERS` | *(unset)* | Comma-separated list of admin emails |
 
+### The config file (`data/shraga.config.ts`)
+
+Beyond env vars, a typed config module in your data dir declares **global MCP servers**: the tools
+every user gets. (Per-user MCPs are added in the UI, and agent settings like model and engine live
+in `agent-config.json`, editable from the UI.) Shraga seeds it from a template on first run and
+gitignores it, so you just edit the seeded file:
+
+```ts
+export default defineConfig({
+  mcps: {
+    // Full form: an explicit command.
+    'stripe': { command: 'bunx', args: ['@stripe/mcp'], env: { STRIPE_KEY: '' } },
+    // Shorthand: a vendored MCP under vendor/<name>/, listing the env keys it needs.
+    'mcp-example': { env: ['EXAMPLE_API_KEY'] },
+  },
+});
+```
+
+Values in `env` resolve from `process.env` (your `.env` or system env) at startup. The legacy
+filename `unclaw.config.ts` is also accepted.
+
 ## Expose it (optional)
 
 Running on a home machine? Set `CLOUDFLARE_TUNNEL_TOKEN` for a public URL via Cloudflare Tunnel, or