@fangorn-network/westmarch 0.0.20-dev → 0.1.0

package/README.md

@@ -1,17 +1,46 @@
 # @fangorn-network/westmarch
 
-Everything you need to get started building Fangorn apps.
+Everything you need to get started building Fangorn apps, and the free tier that runs them.
 
 **Start here:** [docs/app-to-agent.md](docs/app-to-agent.md) takes a static site from nothing
 to a Fangorn app and ERC-8004 agent that any agent can discover, verify and drive.
 
 **Just want to query apps from Claude or another MCP client?** [docs/mcp.md](docs/mcp.md)
-installs `fangorn-mcp` in one command.
+installs `fangorn-mcp` in one command; in Claude Code, `claude plugin marketplace add
+fangorn-network/westmarch && claude plugin install fangorn-index@fangorn` adds it with its skill.
 
 
+## The free tier: one Worker per app
+
+```sh
+westmarch-ship app.json        # claim the app, commit its schema, run its sources, deploy its Worker
+```
+
+An app on the free tier is one Cloudflare Worker (`site/worker.js`), and nobody runs anything
+after the deploy:
+
+- **Indexer.** A cron follows the update log from where it left off, and runs the
+  embedding lens (WHITEPAPER_1 §3.4) over every repo it lists whose head moved: `view.js`, with
+  the Worker's AI binding as the encoder (`@cf/google/embeddinggemma-300m`, 256 dims). The view
+  goes to R2. A repo the app stops listing loses its domain on the next run.
+- **View.** `/view/cdn/…`: the catalog, manifests and content-named shards a reader ranks in
+  its own tab, so a query need never leave it.
+- **MCP.** `/mcp`, streamable HTTP: describe, search, get, similar, count, browse and threads
+  over the view, the query embedded by the same runtime as the rows. Add it to a client as a
+  URL; there is nothing to install.
+- **Site and card.** The stock page, and the agent card naming the app, its repos, its view
+  and its MCP endpoint, bound on chain.
+
+The whole network embeds with one model (`src/core/embed.js`): EmbeddingGemma-300m, by its
+retrieval prompts, truncated to 256 dims. A tab runs it with transformers.js (q8) and the Worker
+with Workers AI; on the same rows they agree to ~0.996 cosine (`E2E_PARITY=1 npm run e2e:worker`).
+
+`npm run e2e:worker` runs the whole tier on this machine: the contracts on anvil, a local IPFS
+gateway, publishers, and the Worker under `wrangler dev` with its real AI binding.
+
 **For Publishers** — shape a tree into a commit graph, describe what's in it, seal and upload the bytes. Needs `fangorn`. Runs anywhere: a script, a server, a browser.
 
-**For Consumers** — read a quickbeam view's Semantic CDN shards in the reader's own process and rank them there. Needs a view URL and nothing else. No index server, no chain read, and the query never leaves the tab.
+**For Consumers** — read an app's view (its Semantic CDN shards) in the reader's own process and rank them there. Needs a view URL and nothing else. No index server, no chain read, and the query never leaves the tab.
 
 The two halves never talk to each other. A publisher writes a graph; some
 watcher bakes it into a view; a consumer reads the view. Either half is useful
@@ -31,7 +60,8 @@ src/
               envelope.js · manifest.js · cli.js · view.js · ship.js · eval.ts
               lint.js    …and whether any of that WORKED
 site/         the stock page every `westmarch-ship` app deploys
-plugin/       the Claude Code plugin: skills + fangorn-fx
+plugin/       Claude Code plugin fangorn-index: its skill and the fangorn MCP server
+plugin-builder/  Claude Code plugin fangorn-builder: fangorn-app, fangorn-improve
 examples/     demo/ (a second consumer + fixtures) · publisher/ (the smallest publisher)
 scripts/      test.js (`npm test`) · build-bin.js (single-file fangorn-mcp)
 ```
@@ -212,7 +242,7 @@ A generic reader has one hard problem: it has rows and no idea which field is
 the title. Hardcode `name` and it works on one bundle and returns `undefined` on
 the next.
 
-The answer is already baked. A quickbeam domain manifest carries `role_map`
+The answer is already baked. A view's domain manifest carries `role_map`
 (title, subtitle, tags, the prose to search, measures, location, link) and
 `presentation` (icon, accent and singular/plural per entity type, plus per-type
 external URL templates). `rolesFrom(manifests, sample)` merges that across the