@mindot/will 0.2.0 → 0.3.0

package/README.md

@@ -19,6 +19,8 @@ Regulatory → Perceptual → Affective → Memory → Executive → Meta-cognit
 
 The mind is not re-derived from a prompt each run. It **accretes**: traits develop from experience, beliefs consolidate, skills proceduralise, and a coherent self carries across restarts as a portable, eval-verified artifact.
 
+Embed it four ways — [**SDK facade**](#the-will-sdk-facade--recommended) (Node/TS) · [**Claude Desktop via MCP**](#the-mcp-server--a-persistent-mind-in-claude-desktop--claude-code) · [**MCP tools as its abilities**](#employing-mcp-tools--the-mind-gets-abilities) · [**HTTP sidecar / Docker**](#the-http-sidecar--will-serve-any-language-or-docker) (any language). [Pick a surface →](#use-it-in-your-project)
+
 ---
 
 ## What makes it different
@@ -82,7 +84,16 @@ ticks — or earlier when physiology demands it.
 
 ## Use it in your project
 
-Runs anywhere **Node 18+ or Bun** runs (the engine is Node-compatible; Bun is the primary target). Two entry points:
+Runs anywhere **Node 18+ or Bun** runs (the engine is Node-compatible; Bun is the primary target). **Four surfaces**, one paradigm — you *perceive* things to a mind and *observe what it projects*; it may act, speak, or stay silent, and it persists across restarts via its [PMA artifact](#pma--the-persistent-mind-artifact):
+
+| Surface | You are… | Start with |
+|---|---|---|
+| [**SDK facade**](#the-will-sdk-facade--recommended) | a Node/TypeScript app embedding a mind | `import { Will } from '@mindot/will'` |
+| [**MCP host**](#the-mcp-server--a-persistent-mind-in-claude-desktop--claude-code) | Claude Desktop / Claude Code / an IDE | `npx -y @mindot/will mcp` |
+| [**MCP tools as abilities**](#employing-mcp-tools--the-mind-gets-abilities) | giving the mind tools it *chooses* to use | `import { connectMcpEffectors } from '@mindot/will/mcp'` |
+| [**HTTP sidecar**](#the-http-sidecar--will-serve-any-language-or-docker) | Python, Go, a game server — any language, or Docker | `npx -y @mindot/will serve` |
+
+(Power users can drop below all four to the [`WillStem` contract](#the-willstem-contract--full-control).)
 
 ### The `Will` SDK facade — recommended
 
@@ -135,7 +146,9 @@ Host a Will over the [Model Context Protocol](https://modelcontextprotocol.io)
 
 The surface keeps the paradigm: `perceive` delivers a stimulus (it returns when *delivered*, not answered), `next_utterance` awaits the mind's next words (**silence is a valid outcome**, reported — never an error), `state` reads its inner life, and `save` checkpoints it without stopping it. There is deliberately no `ask()`-shaped tool. Config via env: `WILL_TIER` (basic|standard|full), `WILL_LLM` (mock|anthropic — defaults to the zero-key mock unless `ANTHROPIC_API_KEY` is set), `WILL_TICK_MS`, `WILL_PMA_PATH`.
 
-**The other direction — a Will *employing* MCP tools.** Any MCP server's tools can become the Will's own *abilities*: each tool registers as a learnable affordance (its description is the ability's meaning, surfaced to the mind's deliberation), the **Will decides when to enact one** — nothing dispatches tools at it — and outcomes feed its reafference loop, so it gets *skilled* at the tools it uses. Arguments come from conscious intent: the executive supplies them in an action's `args`.
+### Employing MCP tools — the mind gets abilities
+
+The other direction from hosting: any MCP server's tools can become the Will's own *abilities*. Each tool registers as a learnable affordance (its description is the ability's meaning, surfaced to the mind's deliberation), the **Will decides when to enact one** — nothing dispatches tools at it — and outcomes feed its reafference loop, so it gets *skilled* at the tools it uses. Arguments come from conscious intent: the executive supplies them in an action's `args`.
 
 ```typescript
 import { connectMcpEffectors } from '@mindot/will/mcp'
@@ -148,6 +161,25 @@ const { names } = await connectMcpEffectors(will, {
 
 The hosted server composes with this: set `WILL_MCP_SERVERS` (a JSON array of `{command,args}` or `{url}` entries) and the mind you host in Claude Desktop itself employs those servers' tools.
 
+### The HTTP sidecar — `will serve` (any language, or Docker)
+
+Not on Node? Host the mind as a sidecar and speak to it over HTTP from Python, Go, a game server — anything:
+
+```bash
+npx -y @mindot/will serve          # http://127.0.0.1:7777, or: docker build -t will . && docker run -p 7777:7777 -v will-data:/data will
+```
+
+```bash
+curl -X POST localhost:7777/perceive -H 'content-type: application/json' \
+     -d '{"text":"Hello there.","from":"sam","speaker":"Sam"}'   # 202 — delivered, not answered
+curl 'localhost:7777/next-utterance?within_ms=8000&from=sam'     # its next words, or {"silence":true}
+curl localhost:7777/state                                        # its inner life
+curl -N localhost:7777/utterances                                # SSE: utterance / emotion / action projections
+curl -X POST localhost:7777/save                                 # checkpoint without stopping
+```
+
+Same paradigm, same env config, same persistence as the MCP host: the mind hibernates to its PMA artifact on shutdown and wakes as the same self on the next start (in Docker, mount `/data` to keep it across container restarts). There is deliberately no `/ask` route.
+
 ### The `WillStem` contract — full control
 
 The lower-level engine surface the facade wraps (explicit tick listeners, the outbox drain, the effector ack loop, PMA distill/load) — for hosts that manage many Wills, custom transports, or replay. The rest of this section walks it end to end.