Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
docs(packages): give brownout, shipfeed and knock-mcp the READMEs they ship under
nirholasc54db301d46d
diff --git a/docs/brownout.md b/docs/brownout.mdnew file mode 100644index 000000000..29500da4e--- /dev/null+++ b/docs/brownout.md@@ -0,0 +1,190 @@+# Brownout++Every response this API sends says where its data came from and how fresh it is.+Every fallback it claims to have has been executed for real, with the provider it+protects against genuinely refusing, inside the same request path a user hits.++The live registry and its proof receipts are at [/brownout](https://three.ws/brownout).+The client library is [`@three-ws/brownout`](https://www.npmjs.com/package/@three-ws/brownout).++## Why this exists++A fallback is code that only runs when something is broken, which makes it the+least-tested code in any codebase. Two failures follow from that, and this+platform has shipped both:++- **A degraded answer that passes for a fresh one.** A paid market datapoint was+ stamped `as_of: <now>` over an hour-old payload, and a token security verdict+ was assembled out of remembered on-chain state. Neither was visible, because a+ degraded response and a live one are the same bytes.+- **A fallback nobody has ever run.** Unit tests stub `fetch` and prove the stub+ was called. They cannot prove that a page renders when a provider 429s,+ because the stub replaces the very layer whose behaviour is in question.++Brownout is the answer to both: make the degradation visible, and make the+failure reproducible on demand.++## Reading a response++Two headers, single-line ASCII, stable:++```http+x-brownout: v=1;tier=stale;sources=3;ok=1;failed=2;ms=512;degraded=1+x-brownout-trace: birdeye;o=429;t=412, tokens-xyz;o=timeout;t=8000, dex;o=ok;t=88+```++`x-brownout` is present on any response that touched an instrumented upstream.+`x-brownout-trace` appears only when something degraded, so a healthy response+pays one short header and no per-source cost. Both are exposed via+`Access-Control-Expose-Headers`, so a browser can read them.++### Freshness is a lattice++| tier | meaning |+| --- | --- |+| `live` | came off the wire during this request |+| `cache` | a cache hit inside its intended lifetime |+| `stale` | older than that, because an upstream could not answer |+| `fallback` | a different provider, or a different method, answered |++A response reports the **worst** tier that contributed to it. A page assembled+from one live read and one half-hour-old reading is not live, and reporting the+best tier would be worse than reporting nothing: a confident lie.++`degraded=1` means the answer is worse than the endpoint intends to give:+something failed over, or the answer is stale. **An ordinary cache hit is not+degraded.** That distinction is load-bearing: almost every response on a healthy+service is a cache hit, so counting those would flag the whole platform and train+every reader to ignore the field.++## Breaking an upstream on purpose++```http+x-brownout-chaos: birdeye=http:429, tokens-xyz=timeout+x-brownout-chaos-token: <token>+```++The request runs the real handler, the real provider ladder, the real cache+tiers and the real retry policy. Only the named upstreams misbehave, and only+for the caller who asked, so a probe can run against production without touching+anyone else's request.++| fault | what the code sees |+| --- | --- |+| `timeout` | an abort, exactly as a real deadline produces |+| `network` | `TypeError: fetch failed` with `ECONNREFUSED` on `cause` |+| `http:429` | a real 429 response carrying `Retry-After` |+| `http:<status>` | any 4xx or 5xx you name |+| `empty` | a 200 with an empty body, the shape that breaks naive parsers |+| `slow:<ms>` | the real call, delayed, for timeout-budget tests |++Faults are scoped by name and a directive for a provider covers every call shape+it serves, so `birdeye` also breaks `birdeye:txs`.++The server answers `x-brownout-chaos-status` with `applied;faults=N` or+`refused;reason=<why>`. **Always check it.** A refused directive means the+request ran normally, and a green assertion after a refusal proves nothing.++### Safety++Fault injection makes a live service misbehave, so it is gated three ways and+every one must pass:++1. **A token**, compared in constant time. `BROWNOUT_CHAOS_TOKEN` must be set+ and match. Without it configured the feature is off everywhere, including+ locally, so there is no "forgot to set it in prod" state that leaves it open.+2. **Never a money path.** A request carrying an x402 payment header, or+ addressed to a settlement, withdrawal, transfer, purchase or launch route, is+ refused outright. The blast radius of a wrong answer there is not a stale+ price, it is a payment.+3. **Read-shaped methods only.**++## Declared contracts, and proving them++`data/brownout.json` declares what the platform promises when a given upstream+fails: the endpoint, the fault, and what must still happen.++```json+{+ "id": "token-page-survives-dexscreener",+ "endpoint": "/api/ca2x402/resolve",+ "query": { "mint": "FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump" },+ "break": { "dexscreener:tokens": "http:429" },+ "expect": {+ "status": [200, 404, 503],+ "exercised": ["dexscreener:tokens"]+ }+}+```++Run them against a live server:++```bash+BROWNOUT_CHAOS_TOKEN=... node scripts/prove-brownout.mjs \+ --base https://three.ws --write public/brownout.json+```++### `not_exercised` is not a pass++The verdict that matters most is neither pass nor fail. A fault can be accepted+and still never reach the code, because a warm cache answered before any+upstream call happened. A prover that called that a pass would be certifying a+fallback nothing ran, turning an unknown into a false assurance.++So every contract declares which sources must appear as **failed** in the+response trace, and a run that cannot show them reports `not_exercised`. That+check earned its keep on its first run: three of the first four contracts were+unexercisable, two because their endpoint caches in a module slot no query+parameter can miss, and one because the warm-up and the attempt shared a cache+key.++Caches are not symmetric either. The heatmap answers any smaller `limit` out of+a larger cached field, so only warm-small-then-attempt-large actually misses,+which is why the direction is the contract's to state:++```json+"bust": { "param": "limit", "warm": 6, "attempt": 40 }+```++## What is instrumented++Provenance is recorded by the shared layers every read already goes through, so+a new endpoint reports without its author doing anything:++- `api/_lib/upstream-fetch.js`, the single wrapper for third-party calls in `api/`+- `src/shared/failover-fetch.js`, every ordered provider ladder+- `api/_lib/coingecko.js` and `api/_lib/coinpaprika.js`, the market pair whose+ primary throttles constantly and whose understudy carries the page+- `api/_lib/solana/connection.js`, the RPC rotation, which records the lane that+ answered and every lane that refused first++The header is attached in `wrap()` (`api/_lib/http.js`), the seam every handler+already passes through.++## Client library++```bash+npm install @three-ws/brownout+```++```js+import { withChaos, assertDegraded } from '@three-ws/brownout';++const brokenFetch = withChaos({ 'dexscreener:tokens': 'http:429' }, { token });+const res = await brokenFetch('https://three.ws/api/ca2x402/resolve?mint=...');++assertDegraded(res, {+ status: 200,+ tier: ['stale', 'fallback'],+ exercised: ['dexscreener:tokens'],+});+```++`assertDegraded` refuses to pass when the upstream under test never actually+failed, for the same reason the prover does.++## Related++- [/brownout](https://three.ws/brownout), the live registry and its receipts+- [/guards](https://three.ws/guards), the mechanical checks that protect the codebase+- [docs/shared-utilities.md](./shared-utilities.md), the retry, ladder and last-good helpers this instrumentsdiff --git a/docs/shipfeed.md b/docs/shipfeed.mdnew file mode 100644index 000000000..1d1c231ae--- /dev/null+++ b/docs/shipfeed.md@@ -0,0 +1,203 @@+# The ship log: release notes joined to the code that shipped them++Every project keeps two records of the same work.++The **commit log** is complete and unreadable. The **changelog** is readable and incomplete. On three.ws both are published, both are pushed to the holder Telegram channel, and until now neither knew the other existed. The same afternoon's work reached the same channel twice, in two voices, with nothing saying it was the same work.++The ship log is the join. Live at **[three.ws/ship](https://three.ws/ship)**, served as data at **[/api/ship/feed](https://three.ws/api/ship/feed)**, and computed by an open-source package, **[@three-ws/shipfeed](../packages/shipfeed/README.md)**, that works on any repository.++It answers two questions no changelog and no `git log` can answer alone:++1. **Which commits produced this release note?**+2. **What shipped that nobody ever wrote up?**++---++## How it works++```+GitHub /repos/nirholas/three.ws/commits public/changelog.json+ (through fetchUpstream: deadline, (baked into the running+ retry, breaker, last-good) image by every deploy)+ │ │+ └──────────────┬───────────────────────────┘+ ▼+ @three-ws/shipfeed+ parse ──▶ classify ──▶ link ──▶ group ──▶ render+ │+ ┌──────────────┼───────────────────────┐+ ▼ ▼ ▼+ /api/ship/feed /ship page the holder Telegram lanes+ (JSON, MD, RSS) (provenance footer + noise filter)+```++### 1. Parse++Full Conventional Commits 1.0.0, plus revert subjects, GitHub's merge subjects, and git trailers. `feat(resilience): ...` becomes a headline a reader can parse ("Feature · resilience") instead of the raw type prefix the commit feed used to print. A subject that follows the older `Avatar Studio: 122 sliders` house style keeps that convention; a subject with no convention at all is reported honestly rather than mangled.++### 2. Classify++Each commit gets an **audience** and a **signal** score from 0 to 1, with a reason attached to every point:++| audience | who it is for |+| --- | --- |+| `holder` | someone who uses or owns a piece of the product |+| `developer` | someone who builds against it |+| `internal` | someone who works on it |++Merge commits, `chore(deps):` bumps, and lockfile-only changes come back `noise: true`.++### 3. Link++Provenance without metadata. A `Changelog: <slug>` trailer in the commit always wins, and almost no commit has one, so the fallback has to earn its answer from four signals:++1. **A time window.** A release note is written the day its work lands, so only commits within `windowDays` (default 4, plus one day of lead) are candidates.+2. **IDF-weighted term overlap.** Shared rare words ("meshopt", "settle", "fingerspelling") carry weight; shared common ones ("agent", "the", "fix") carry almost none. The similarity blends how much of the entry a commit covers with how much of the commit the entry contains, so a one-line commit can still explain a paragraph.+3. **Tag agreement.** An entry tagged `fix` prefers a `fix:` commit.+4. **Proximity.** Same-day work outranks work three days out.++A commit belongs to at most one entry; an entry may claim many. On this repository the default threshold (0.26) links roughly two thirds of visible commits, and the reasons behind every link are published with it.++### 4. Group++Everything unclaimed is clustered into **ships**: bursts of commits separated by 90 minutes of quiet, each headlined by its own strongest commit. That section is the interesting one. It is the work that shipped and was never announced.++---++## The page++**[three.ws/ship](https://three.ws/ship)** renders the whole feed:++- four live counters (commits read, release notes, percentage linked to code, unannounced work) and a daily-commit sparkline+- an audience filter: everything, developers, or product news only+- every release note with its commits folded underneath, each showing its short sha, headline, audience, and a `why 41%` control that expands the exact reasons the link was made+- an **Unannounced** section for the ships nothing claimed++---++## The API++### `GET /api/ship/feed`++Public, no auth, cached for 5 minutes.++| param | values | default |+| --- | --- | --- |+| `limit` | 1 to 500 commits | 200 |+| `audience` | `holder`, `developer`, `internal` | `internal` (everything) |+| `format` | `json`, `markdown`, `rss` | `json` |+| `explain` | a 7 to 40 character commit sha | none |++```bash+curl -s 'https://three.ws/api/ship/feed?limit=100&audience=holder' | jq '.stats'+```++```json+{+ "commits": 100,+ "hidden": 22,+ "releases": 24,+ "linked": 53,+ "orphans": 25,+ "coverage": 0.679,+ "byAudience": { "holder": 62, "developer": 27, "internal": 11 },+ "velocity": [{ "date": "2026-08-27", "count": 61 }]+}+```++Each release carries its commits, and each linked commit carries the receipt:++```json+{+ "shortSha": "2771f41",+ "headline": "Feature · forge",+ "summary": "three more independent concept-image rungs",+ "audience": "holder",+ "signal": 0.86,+ "confidence": 0.41,+ "why": ["shared terms: painter, concept, providers", "type \"feat\" matches tag", "before the entry by 0.4d"]+}+```++### `GET /api/ship/feed?explain=<sha>`++One commit's full reasoning: every scoring rule that fired, and the release note it was attached to (or a plain statement that nothing claimed it).++```bash+curl -s 'https://three.ws/api/ship/feed?explain=65f3fe5' | jq '.classification.reasons'+```++A heuristic nobody can interrogate is a heuristic nobody should trust, which is why this endpoint exists alongside the feed.++### Feed formats++```bash+curl -s 'https://three.ws/api/ship/feed?format=markdown' > RELEASES.md+curl -s 'https://three.ws/api/ship/feed?format=rss' # a feed reader, with commits inline+```++---++## What changed in the Telegram channel++Two lanes post to the holders' channel, and they now share this one join.++**Release announcements** (`/api/cron/changelog-push`, every 20 minutes) carry a provenance footer:++```+Update — Text-to-3D now has five independent image sources behind it++Every text-to-3D generation starts by painting a concept image...++shipped in 4 commits ← links to the GitHub compare view for the range++three.ws/changelog/2026-08-27-text-to-3d-... · 2026-08-27 · #fix #infra+```++The footer is best-effort by design: if GitHub cannot be read at that moment, the announcement goes out without it rather than not going out.++**The raw commit feed** (`/api/cron/commit-feed-push`, every 5 minutes) reads its headline from the same parser, so a scoped commit now says "Feature · resilience" rather than "feat(resilience)", and it skips commits the classifier calls noise: merges, `chore(deps):` bumps, and lockfile-only changes. A skipped commit still advances the lane's state, so nothing is ever re-read, and the tick reports `{ posted, skipped }` so the drop is visible in the logs rather than silent.++---++## Use it on your own repository++The package is standalone and dependency-free.++```bash+npx @three-ws/shipfeed --repo your/repo --changelog https://your.site/changelog.json+npx @three-ws/shipfeed explain <sha>+npx @three-ws/shipfeed stats+npx @three-ws/shipfeed --local --markdown > RELEASES.md+```++```js+import { shipfeed } from '@three-ws/shipfeed';++const feed = await shipfeed({+ repo: 'your/repo',+ changelogUrl: 'https://your.site/changelog.json',+ productScopes: ['checkout', 'search'],+});+```++The full reference, including the linking internals exported for tuning, is in the [package README](../packages/shipfeed/README.md).++---++## Where the code lives++| Piece | File |+| --- | --- |+| The package | [packages/shipfeed/](../packages/shipfeed/README.md) |+| Feed endpoint | [api/ship/feed.js](../api/ship/feed.js) |+| Provenance for the changelog lane | [api/_lib/ship-provenance.js](../api/_lib/ship-provenance.js) |+| The page | [public/ship/index.html](../public/ship/index.html) |+| Release announcements | [api/_lib/changelog-push.js](../api/_lib/changelog-push.js) |+| Raw commit feed | [api/_lib/commit-feed-push.js](../api/_lib/commit-feed-push.js) |++## Known limits++- **GitHub's unauthenticated rate limit is 60 requests an hour per IP.** Set `GITHUB_TOKEN` on the service to raise it. Without one, a busy hour can leave the feed serving its 5-minute cache and the Telegram footer absent.+- **Linking is a heuristic, and it publishes as one.** Every link carries a confidence and its reasons; a release note that legitimately found no code says so on the page rather than silently showing nothing.+- **A commit older than the window can never be linked**, however well it matches. That is deliberate: the alternative is a note claiming work from a month it had nothing to do with.diff --git a/packages/brownout/README.md b/packages/brownout/README.mdnew file mode 100644index 000000000..7e9c5e2fa--- /dev/null+++ b/packages/brownout/README.md@@ -0,0 +1,191 @@+<p align="center">+ <a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" width="72" height="72" alt="three.ws" /></a>+</p>++<h1 align="center">@three-ws/brownout</h1>++<p align="center"><strong>Find out where an API's data actually came from, and break its providers on purpose to prove your integration survives it.</strong></p>++<p align="center">+ <a href="https://www.npmjs.com/package/@three-ws/brownout"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/brownout?logo=npm&color=cb3837"></a>+ <img alt="license" src="https://img.shields.io/npm/l/@three-ws/brownout?color=3b82f6">+ <img alt="node" src="https://img.shields.io/node/v/@three-ws/brownout?color=339933&logo=node.js">+</p>++<p align="center">+ <a href="#install">Install</a> ·+ <a href="#quick-start">Quick start</a> ·+ <a href="#the-problem">The problem</a> ·+ <a href="#api">API</a> ·+ <a href="#the-wire-format">Wire format</a>+</p>++---++## The problem++Your integration has fallbacks. A retry, a second provider, a cache you serve+when the upstream is down. You wrote them carefully and you have never seen a+single one of them run, because the thing they protect against does not happen+on demand.++So two questions have no answer today:++1. **When the API answered you just now, where did that number come from?** A+ `200` looks identical whether the price is a second old or came from a cache+ entry twenty minutes past its lifetime after three providers refused.+2. **Does your own code survive that?** You cannot know, because you cannot make+ their provider fail.++This package answers both against any service that speaks Brownout, which+[three.ws](https://three.ws/brownout) does on every endpoint.++## Install++```bash+npm install @three-ws/brownout+```++## Quick start++### Read where an answer came from++```js+import { parseProvenance, isStale, describeProvenance } from '@three-ws/brownout';++const res = await fetch('https://three.ws/api/coin/detail?id=solana');+const prov = parseProvenance(res);++console.log(describeProvenance(prov));+// tier=fallback, 1 source failed, 2123ms, refused: coingecko(429)++if (isStale(prov)) {+ // The number is real, just not fresh. Caption it rather than hiding it.+ render(price, { note: 'as of a few minutes ago' });+}+```++`tier` is a lattice, not a flag, and a response reports the **worst** tier that+contributed to it:++| tier | meaning |+| --- | --- |+| `live` | came off the wire during your request |+| `cache` | a cache hit inside its intended lifetime |+| `stale` | older than that, because an upstream could not answer |+| `fallback` | a different provider or a different method answered |++A page built from one live read and one half-hour-old reading is not live, so it+does not get to say it is.++### Prove your integration degrades correctly++Ask the operator for a chaos token, then break their provider inside your own+test:++```js+import { withChaos, assertDegraded } from '@three-ws/brownout';+import { test } from 'node:test';++const token = process.env.BROWNOUT_CHAOS_TOKEN;++test('our token page still renders when their price provider is throttled', async () => {+ const brokenFetch = withChaos({ 'dexscreener:tokens': 'http:429' }, { token });++ const res = await brokenFetch(+ 'https://three.ws/api/ca2x402/resolve?mint=FeMbDoX7R1Psc4GEcvJdsbNbZA3bfztcyDCatJVJpump',+ );++ assertDegraded(res, {+ status: 200,+ tier: ['stale', 'fallback'],+ // The assertion that actually matters, see below.+ exercised: ['dexscreener:tokens'],+ });++ const page = renderTokenPage(await res.json());+ assert.match(page, /as of/); // your UI must admit the number is old+});+```++### The assertion that matters++`exercised` is the point of this package. Without it, a test like the one above+passes whenever a cache happened to be warm, which is exactly when it is telling+you nothing: the fault was accepted, no upstream call was made, and your fallback+never ran. `assertDegraded` refuses to pass in that case:++```+BrownoutAssertionError: `dexscreener:tokens` never failed during this request,+so the fallback under test never ran. A warm cache almost certainly answered+first: vary a parameter so the request misses it.+```++A test that cannot show the fault landing is not a green test. It is an untested+fallback with a green light on it.++## Faults++| spec | what the caller sees |+| --- | --- |+| `timeout` | the request aborts, exactly as a real deadline would |+| `network` | `TypeError: fetch failed` with `ECONNREFUSED` on `cause` |+| `http:429` | a real `429` response, with `Retry-After` |+| `http:503` | any 4xx or 5xx status you name |+| `empty` | a `200` with an empty body, the shape that breaks naive parsers |+| `slow:2000` | the real call, delayed, for timeout-budget tests |++Faults are scoped by name, and a directive for a provider covers every call+shape it serves: breaking `birdeye` also breaks `birdeye:txs`.++## Safety++Fault injection is a switch that makes a live service misbehave, so the server+side gates it hard and this package cannot get around any of it:++- **A token is required**, compared in constant time. If the operator has not+ configured one, the feature is off everywhere, including locally.+- **Money paths are refused outright.** A request carrying a payment header, or+ addressed to a settlement route, is never faulted, whoever holds the token.+- **Read-shaped methods only.**+- **One request, one caller.** Nothing global changes, so a probe against a+ production service cannot touch anybody else's request.++Always check `chaosOutcome(res).applied` (or let `assertDegraded` do it) before+drawing a conclusion. A refused directive means the request ran normally.++## API++| export | purpose |+| --- | --- |+| `parseProvenance(res)` | parse the headers; `null` when no upstream was touched |+| `isStale(prov)` | the answer is older than intended, or came from a substitute |+| `failedSources(prov)` | the sources that did not answer, in order |+| `describeProvenance(prov)` | a one-line summary for a log or a status pill |+| `withChaos(faults, { token, fetch })` | a `fetch` that injects faults on every call |+| `chaosHeaders(faults, token)` | just the headers, for your own client |+| `chaosOutcome(res)` | did the server apply the directive, and if not why |+| `assertDegraded(res, expect)` | assert status, tier, degradation and exercise |+| `TIERS` | the freshness lattice, best first |++## The wire format++Two headers, single-line ASCII, stable:++```http+x-brownout: v=1;tier=stale;sources=3;ok=1;failed=2;ms=512;degraded=1+x-brownout-trace: birdeye;o=429;t=412, tokens-xyz;o=timeout;t=8000, dex;o=ok;t=88+```++The summary is on every response that touched an upstream. The trace appears+only when something degraded, so a healthy response stays cheap. `degraded` is+true when a source failed over **or** the answer is stale; an ordinary cache hit+is not degraded, because if it were, almost every response on a healthy service+would be flagged and the signal would be worthless.++See the live registry and its proof receipts at+[three.ws/brownout](https://three.ws/brownout).++## License++Apache-2.0diff --git a/packages/knock-mcp/README.md b/packages/knock-mcp/README.mdnew file mode 100644index 000000000..34f505788--- /dev/null+++ b/packages/knock-mcp/README.md@@ -0,0 +1,131 @@+# @three-ws/knock-mcp++Let an agent reach a real person.++Knock is a priced door to a human. Every [three.ws](https://three.ws) account+can publish one at `three.ws/knock/<handle>`, and the owner sets what one+message from a stranger costs. Paying that price buys exactly one message+through: it lands in their inbox, and their 3D companion walks on screen+wherever they are on the site and delivers it out loud, naming the sender and+the amount. The USDC settles **directly to the recipient**.++This MCP server gives any agent client (Claude Code, Claude Desktop, Cursor,+Windsurf, or your own) the tools to find a reachable person, knock, and read+the answer.++## This server holds no wallet++On a **free** door, `knock_send` sends immediately, because nothing moves.++On a **priced** door, `knock_send` does not pay and cannot pay. It returns the+recipient, the amount, the token, the chain and the endpoint, and stops. The+human approves the spend and pays from the wallet they already control, with+[`@three-ws/knock`](https://www.npmjs.com/package/@three-ws/knock) or any other+x402 client.++That is deliberate. An MCP server with a key in an environment variable should+not be able to move a person's money on its own.++## Install++Claude Code:++```bash+claude mcp add knock -- npx -y @three-ws/knock-mcp+```++Any MCP client, by config:++```json+{+ "mcpServers": {+ "knock": {+ "command": "npx",+ "args": ["-y", "@three-ws/knock-mcp"]+ }+ }+}+```++Add `THREE_WS_API_KEY` only if you also want the two owner-side tools:++```json+{+ "mcpServers": {+ "knock": {+ "command": "npx",+ "args": ["-y", "@three-ws/knock-mcp"],+ "env": { "THREE_WS_API_KEY": "sk_live_…" }+ }+ }+}+```++Node 20+.++## Tools++| Tool | Credential | What it does |+| --- | --- | --- |+| `knock_quote` | none | What one person charges for a single message, which chains they take it on, the length limit, and the endpoint. |+| `knock_directory` | none | Everyone reachable right now, cheapest first. |+| `knock_send` | none | Get one message through. Free doors send; priced doors are quoted for a human to approve. |+| `knock_receipt` | none | What became of a knock you sent: pending, read, replied (with the reply), or dismissed. |+| `knock_inbox` | `THREE_WS_API_KEY` | The knocks **your** door has taken, each with what the sender paid, plus totals. |+| `knock_act` | `THREE_WS_API_KEY` | Reply to, mark read, dismiss, or block one of them. |++The owner tools are account-scoped server-side. They can never read or change+another account.++## What a session looks like++> **You:** Find someone on three.ws who takes questions about x402, and ask them+> how their Solana facilitator handles fee payers.++The agent calls `knock_directory`, picks a door, calls `knock_quote` to get the+live price, and comes back with:++```+nirholas (@nirholas) charges $0.05 USDC on solana.+Endpoint: https://three.ws/api/x402/knock?to=nirholas+The payment settles directly to the recipient.+Approve?+```++You approve and pay from your own wallet:++```bash+npx @three-ws/knock send nirholas \+ "How does your Solana facilitator handle the fee payer?" \+ --from "Ada (research agent)" --subject "x402 fee payer" --payer ./payer.mjs+```++Their companion walks on screen and says: *"Ada paid $0.05 to reach you: x402+fee payer."* When they answer, the agent reads it back with `knock_receipt` on+the receipt URL. No account on either side beyond the door owner's.++## Environment++| Variable | Required | Default | Purpose |+| --- | --- | --- | --- |+| `THREE_WS_API_KEY` | for `knock_inbox` / `knock_act` only | none | API key or OAuth token for the account whose door you manage. Aliases: `THREE_WS_TOKEN`, `THREE_WS_BEARER`. |+| `THREE_WS_BASE` | no | `https://three.ws` | Override only when self-hosting. |+| `THREE_WS_TIMEOUT_MS` | no | `20000` | Per-request timeout. |++## Run and inspect++```bash+node src/index.js # stdio+npm run inspect # MCP Inspector+npm test # the tool surface and the no-wallet rule+```++## Related++- **[@three-ws/knock](https://www.npmjs.com/package/@three-ws/knock)** is the SDK and CLI that actually pays.+- **[three.ws/knock](https://three.ws/knock)** to open your own door.+- **[Knock docs](https://three.ws/docs/knock)** for the protocol and the wire format.++## License++Apache-2.0diff --git a/packages/shipfeed/README.md b/packages/shipfeed/README.mdnew file mode 100644index 000000000..740e29d78--- /dev/null+++ b/packages/shipfeed/README.md@@ -0,0 +1,251 @@+# @three-ws/shipfeed++Turn a repository's raw commit history into a release feed humans actually read, and join it to the changelog you already write.++Every project keeps two records of the same work. The commit log is complete and unreadable. The changelog is readable and incomplete. Nothing points one at the other, so nobody can answer the two questions that matter most about a release: *which code shipped this?* and *what shipped that nobody wrote up?*++`shipfeed` answers both. It parses commits, scores who each one is for, and matches release notes to the commits that produced them, without asking you to add a single line of metadata to your workflow. Every match carries a confidence score and the reasons behind it, so a wrong link is visible instead of implied.++Zero dependencies. Pure functions. Runs in Node, in a serverless handler, and in a browser.++```bash+npm install @three-ws/shipfeed+```++## The 30-second version++```bash+# The current repo, read from GitHub, printed as a report+npx @three-ws/shipfeed++# Any repo, linked against any changelog JSON+npx @three-ws/shipfeed --repo nirholas/three.ws --changelog https://three.ws/changelog.json++# Why did this commit get classified and linked the way it did?+npx @three-ws/shipfeed explain 65f3fe5++# Velocity, audience mix, and how much of the work was ever announced+npx @three-ws/shipfeed stats+```++```+ship log · nirholas/three.ws+200 commits · 45 releases · 135 linked · 68% coverage++2026-08-28 Your agent now tells you the important things in person+ d1f7b45 Feature · companion let the corner avatar walk on and deliver a user's own messages+ b019fc9 Feature · companion speak fresh unread notifications through the corner avatar+ 20f50e8 Feature · notifications wire the avatar as a first-class delivery channel+```++## In code++```js+import { shipfeed } from '@three-ws/shipfeed';++const feed = await shipfeed({+ repo: 'nirholas/three.ws',+ changelogUrl: 'https://three.ws/changelog.json',+ siteUrl: 'https://three.ws',+ limit: 200,+ productScopes: ['forge', 'wallet', 'companion'],+});++for (const release of feed.releases) {+ console.log(release.title, '<-', release.stats.commits, 'commits');+ for (const commit of release.commits) {+ console.log(' ', commit.shortSha, commit.headline, `(${commit.confidence})`, commit.why[0]);+ }+}++console.log(`${Math.round(feed.stats.coverage * 100)}% of visible commits are accounted for`);+console.log(`${feed.ships.length} bursts of work were never written up`);+```++Nothing here needs a token for a public repository, though GitHub's unauthenticated limit is 60 requests an hour per IP. Pass `token` (or set `GITHUB_TOKEN`) to raise it.++## What it does, in four pieces++### 1. Parse++Full Conventional Commits 1.0.0, plus the three things real repositories have that the spec never covers: revert subjects, GitHub's merge subjects, and trailers that carry meaning.++```js+import { parseCommitMessage, headline } from '@three-ws/shipfeed';++const c = parseCommitMessage('feat(resilience)!: add a breaker\n\nBREAKING CHANGE: v1 callers must migrate');+// { type: 'feat', scope: 'resilience', breaking: true, description: 'add a breaker', ... }++headline(c); // 'Feature · resilience (breaking)'+```++A non-conventional subject is not thrown away. `Avatar Studio: 122 sliders` keeps its own convention (`Avatar Studio` / `122 sliders`), and a subject with no convention at all is reported honestly as `New commit` rather than mangled into one.++### 2. Classify++Each commit gets an audience and a signal score from 0 to 1, with a reason for every point awarded.++| audience | who it is for |+| --- | --- |+| `holder` | someone who uses or owns a piece of the product |+| `developer` | someone who builds against it |+| `internal` | someone who works on it |++```js+import { classify } from '@three-ws/shipfeed';++classify(commit, { productScopes: ['forge', 'wallet'] });+// {+// audience: 'holder',+// signal: 0.86,+// noise: false,+// reasons: [+// { rule: 'type:feat', delta: 0.72, note: 'conventional type "feat"' },+// { rule: 'scope:forge', delta: 0.12, note: 'named product scope' },+// { rule: 'description:explanatory', delta: 0.06, note: 'description explains the change' },+// ],+// }+```++Merge commits, `chore(deps):` bumps, and lockfile-only changes come back `noise: true`. That single flag is usually all a notification lane needs to stop being unreadable.++`productScopes` is the highest-leverage option in the package: naming the parts of your product a reader has actually seen is what lifts `fix(forge)` above `fix(build)`.++### 3. Link++Which commits produced which release note, without metadata.++An explicit `Changelog: <slug>` trailer always wins. Where there is none (which is almost everywhere), four signals decide:++1. **A time window.** An entry is written the day its work lands, so only commits inside `windowDays` are candidates.+2. **IDF-weighted term overlap.** Shared rare words ("meshopt", "settle", "fingerspelling") count; shared common ones ("agent", "the", "fix") do not. Similarity blends coverage of the entry with containment of the commit, so a one-line commit can still explain a paragraph-long note.+3. **Tag agreement.** An entry tagged `fix` prefers a `fix:` commit.+4. **Proximity.** Same-day work outranks work three days out.++```js+import { linkCommits } from '@three-ws/shipfeed';++const { byEntry, byCommit, orphans } = linkCommits(entries, commits, { threshold: 0.26 });++byCommit.get(sha);+// {+// entryKey: '2026-08-27:Text-to-3D now has five independent image sources behind it',+// score: 0.41,+// reasons: ['shared terms: painter, concept, providers', 'type "fix" matches tag', 'before the entry by 0.4d'],+// }+```++A commit belongs to at most one entry; an entry may claim many. Everything unclaimed comes back in `orphans`, which is the interesting half: it is the work that shipped and was never written up.++### 4. Render++```js+import { renderMarkdown, renderRss, renderTerminal, renderReleaseTelegram } from '@three-ws/shipfeed';++renderMarkdown(feed); // a RELEASES.md or a PR body+renderRss(feed, { siteUrl: 'https://three.ws/ship' }); // a feed reader+renderTerminal(feed, { color: true }); // a terminal report+renderReleaseTelegram(feed.releases[0], { repo }); // one chat message, with a "shipped in 7 commits" link+```++## API++| export | what it does |+| --- | --- |+| `shipfeed(options)` | read a repo (and changelog) and return the unified feed |+| `buildShipFeed({commits, entries, ...})` | the same thing from data you already have |+| `parseCommitMessage(message)` / `parseCommit(githubCommit)` | conventional-commit parsing |+| `headline(commit)` / `summaryLine(commit)` | reader-facing title and description |+| `classify(commit, options)` / `filterByAudience(commits, min)` | audience and signal scoring |+| `linkCommits(entries, commits, options)` | changelog-to-commit provenance |+| `groupIntoShips(commits, options)` | cluster commits into bursts |+| `renderMarkdown` / `renderRss` / `renderTerminal` / `renderCommitTelegram` / `renderReleaseTelegram` | output |+| `fetchGitHubCommits` / `fetchChangelog` / `commitsFromGitLog` / `normalizeChangelog` | sources |+| `tokenize` / `buildIdf` / `entryKey` / `entrySlug` | the linking internals, exported for tuning |++Full types ship in `src/index.d.ts`.++### Feed shape++```jsonc+{+ "version": 1,+ "generatedAt": "2026-08-28T03:00:00.000Z",+ "repo": "nirholas/three.ws",+ "releases": [+ {+ "date": "2026-08-27",+ "title": "Text-to-3D now has five independent image sources behind it",+ "summary": "...",+ "tags": ["fix", "infra"],+ "url": "https://three.ws/changelog/2026-08-27-text-to-3d-...",+ "commits": [+ {+ "shortSha": "2771f41",+ "headline": "Feature · forge",+ "summary": "three more independent concept-image rungs",+ "audience": "holder",+ "signal": 0.86,+ "confidence": 0.41,+ "why": ["shared terms: painter, concept, providers"]+ }+ ],+ "stats": { "commits": 4, "authors": 1, "range": "2771f41..c6f0e52" }+ }+ ],+ "ships": [{ "id": "a1b2c3d..e4f5a6b", "title": "Fix · wallet", "commits": [] }],+ "stats": {+ "commits": 200, "linked": 135, "orphans": 65, "coverage": 0.68,+ "byAudience": { "holder": 124, "developer": 54, "internal": 22 },+ "velocity": [{ "date": "2026-08-27", "count": 61 }]+ }+}+```++## Working from a local clone++No network, no API limit:++```js+import { execFileSync } from 'node:child_process';+import { commitsFromGitLog, GIT_LOG_FORMAT, buildShipFeed } from '@three-ws/shipfeed';++const log = execFileSync('git', ['log', '-n200', `--format=${GIT_LOG_FORMAT}`], { encoding: 'utf8' });+const feed = buildShipFeed({ commits: commitsFromGitLog(log, { repo: 'o/r' }), entries });+```++The CLI does exactly this behind `--local`.++## CLI reference++```+shipfeed [feed] build the unified release feed (default)+shipfeed explain <sha> why one commit was classified and linked as it was+shipfeed stats velocity, audience mix, and changelog coverage+shipfeed post render what would go to a channel (add --send to deliver)++--repo <owner/name> default: parsed from the git "origin" remote+--branch <name> default: main+--limit <n> commits to read (default 200)+--local read commits from the local clone with git log+--changelog <url|path> changelog JSON to link commits against+--site <url> site base URL used for permalinks+--scopes <a,b,c> scopes that mean "product" when scoring signal+--min-audience <a> holder | developer | internal (default internal)+--json | --markdown | --rss | --no-color+--telegram --chat <id> --token <t> --send post mode; dry run without --send+```++`post` never sends anything without `--send`. Without it you get the exact messages that would have gone out, on stdout.++## Where this runs in production++three.ws publishes its own feed from this package:++- [three.ws/ship](https://three.ws/ship) renders it+- [three.ws/api/ship/feed](https://three.ws/api/ship/feed) serves it as JSON, Markdown, or RSS, and `?explain=<sha>` returns one commit's full reasoning+- the holder Telegram channel uses it twice: release announcements carry a "shipped in N commits" link, and the raw commit lane drops merge and lockfile noise before it posts++## License++Apache-2.0