@plurnk/plurnk-service 0.4.0 → 0.5.0

package/README.md

@@ -1,54 +1,23 @@
 # plurnk-service
 
-Engine library + admin CLI + daemon for the plurnk agent runtime. Speaks the [plurnk-grammar](https://github.com/plurnk/plurnk-grammar) contract; exposes a [WebSocket JSON-RPC surface](./SPEC.md#13) for clients (the user-facing CLI/TUI lives in [`plurnk`](https://github.com/plurnk/plurnk)).
+LLM agent runtime engine. Consumes [plurnk-grammar](https://github.com/plurnk/plurnk-grammar); exposes WebSocket JSON-RPC for clients. User-facing CLI: [plurnk](https://github.com/plurnk/plurnk).
 
-## Quick start
+## Documentation
 
-```sh
-git clone github.com/plurnk/plurnk-service
-cd plurnk-service
-npm install
-./bin/plurnk-service.js              # boots daemon on ws://127.0.0.1:3044
-```
+- [`SPEC.md`](./SPEC.md) — canonical specification. 16 numbered sections. Anchors `{§<id>}` bind to integration tests (`test/intg/spec-anchors.test.ts`).
+- [`AGENTS.md`](./AGENTS.md) — collaboration memory for agents working on this repo (gitignored).
 
-`.env.example` ships with sane defaults; the daemon auto-loads it. Override per-deployment in `.env` or via `--config=<path>`. Run `./bin/plurnk-service.js --help` for the flag surface.
+## Sibling contracts
 
-To talk to a real model, set in `.env`:
+Author-facing contracts hosted in their own repos. plurnk-service is the consumer; consumption surface section noted.
 
-```
-PLURNK_MODEL_<alias>=<provider>/<model-id>
-PLURNK_MODEL=<alias>
-OPENAI_BASE_URL=<endpoint>           # for openai-family aliases
-```
-
-Then `npm run test:live` for the end-to-end smoke against your configured model.
-
-## Architecture
-
-- [`SPEC.md`](./SPEC.md) — engine surface, RPC contract, packet shape, op semantics. 15 numbered sections; promise anchors `{§<id>}` link to tests.
-- [`MIMETYPES.md`](./MIMETYPES.md) — contract for `@plurnk/plurnk-mimetypes-*` packages.
-- [`PROVIDERS.md`](./PROVIDERS.md) — contract for `@plurnk/plurnk-providers-*` packages.
-- [`SCHEMES.md`](./SCHEMES.md) — contract for `@plurnk/plurnk-schemes-*` packages.
-- [`AGENTS.md`](./AGENTS.md) — collaboration memory for agents working on this repo (gitignored; see SPEC for canonical state).
+| Repo | Domain | Consumption |
+|---|---|---|
+| [plurnk-providers](https://github.com/plurnk/plurnk-providers) | LLM transports + tokenomic primitives | SPEC §2 |
+| [plurnk-schemes](https://github.com/plurnk/plurnk-schemes) | URI scheme handlers | SPEC §3.6 |
+| [plurnk-mimetypes](https://github.com/plurnk/plurnk-mimetypes) | Content interpreters | SPEC §4.5 |
+| [plurnk-execs](https://github.com/plurnk/plurnk-execs) | Runtime executors (EXEC dispatch) | SPEC §10 |
 
 ## Tests
 
-```sh
-npm run test:lint        # tsc --noEmit
-npm run test:intg        # integration tests (mock provider, real SQLite)
-npm run test:live        # live tests (real provider; requires PLURNK_MODEL)
-npm run test:demo        # demo tests (natural prompts; outcome assertions)
-```
-
-Four tiers per SPEC §0.7. Cadence:
-
-- **lint** — every commit (CI enforces).
-- **intg** — every commit (CI enforces). Mock provider, real in-memory SQLite. Fast (~2s).
-- **live** — before merging significant engine changes. Real provider, structural prompts, wire-level assertions. Catches protocol drift and validates rail behavior against actual model failure modes. ~30–80s per test against gemma.
-- **demo** — periodic. Real provider, natural human-style prompts, outcome assertions. Validates the model + sysprompt + grammar trio. Failures indict the trio, not the engine. ~25s per test.
-
-CI runs lint + intg. live + demo are run locally with real provider config.
-
-## License
-
-MIT.
+Tiers per SPEC §0.7. Scripts: `test:lint`, `test:unit`, `test:intg`, `test:live`, `test:demo`.