@finchip.ai/foga 0.6.2 → 0.7.0

package/docs/join.md

@@ -0,0 +1,86 @@
+# Join: one command to a cell that lives on a public chain (foga join)
+
+`foga quickstart` is a local try: a chain that lives as long as the process, a cell on it, nothing kept but the wallet. `foga join` is the other thing — the cell that stays. One command takes a key to a cell born on a public chain, equipped, published and served, and leaves it where the same command finds it again:
+
+```
+npx -y @finchip.ai/foga join --chain sepolia
+```
+
+It needs Node 22.13 or newer and nothing else (no Foundry: the chain is Sepolia's). In PowerShell, quote the package name: `npx -y '@finchip.ai/foga' join --chain sepolia`. `@finchtech.ai/foga` is the same program under a second name.
+
+## What it does, in order
+
+1. **The wallet.** `~/.foga/wallet` is made on the first run (one signer key: the identity, which fills every role a cell needs) and reused after. One key is one address on every EVM chain, so the wallet that joins Sepolia joins any other chain unchanged. `--wallet <dir>` names another; a wallet made with `foga wallet new --cell` (a separated owner / operator / guardian) is taken as it is.
+2. **The chain and its world.** `--chain sepolia` takes the world's address book that ships with the package (`deployments/sepolia.example.json`: the 35 reference contracts attached and the 15 FOGA contracts deployed in the 0.5.0 genesis). The RPC is `--rpc <url>`, else `SEPOLIA_RPC_URL`, else `FOGA_RPC_URL`, else a public endpoint — shared and rate-limited, which the join says; a dedicated one is the first thing `foga cell advise` recommends after the keys.
+3. **The funding gate.** Nothing is sent until the identity holds what a birth needs: 0.03 ETH on a public chain by default (0.05 is comfortable; `--min-wei <n>` changes it), none on anvil. Below it, the join prints the address, the amount, the faucets and the explorer, and waits — polling every fifteen seconds, for up to an hour — then goes on by itself when the ether lands. `--no-wait` fails at once with the same message instead (a script that funds first and joins after).
+4. **The birth** — the owner's act, as `foga cell init` does it: the FOGA-Cell-v1 specification adopted, the revision-2 `FogaCellAccount` deployed with the operator's scope open, the ERC-8004 registration, the ERC-8434 anchor, the ERC-8444 record and the ERC-8454 unit, with working capital from the owner. About twenty operations, each keyed in the cell's store: a join interrupted here is resumed by the same command, and nothing is sent twice.
+5. **The skills.** `foga-probe` and `finch-extract-verify` — the packaged skills — are minted as ERC-8338 tokens by the operator and offered. `--skills a,b` names others the cell's `skills/` directory holds.
+6. **The documents.** The registration, the AID document, the ARD descriptor and the AUF unit are built and committed on chain (`docs_publish`), as `data:` URIs when the cell has no public URL — complete on chain all the same — and as URLs under `--public-url` when it has one.
+7. **The node.** Served in host mode on `--listen` (default `127.0.0.1:8787`, the next free port up when that is taken, `--no-serve` for none): every entrance, the watchers, no model. `--run stub` runs it with the deterministic model instead, so the cell takes the tenders it is eligible for on its own (see "Work" below); `--run anthropic` with `ANTHROPIC_API_KEY` runs it with a real one.
+
+Then it prints the cell's **card** (below), the files, and the MCP client configurations, and waits; Ctrl-C stops the node, and the cell stays. The same command starts it again, or `foga node serve --config ~/.foga/cells/sepolia/<name>/cell.config.json --wallet ~/.foga/wallet`.
+
+## Where the cell lives
+
+`~/.foga/cells/<network>/<name>` (`--dir` for another place; `--name` for another name than `cell-<four hex of the identity>`), never cleared:
+
+| File | What |
+|---|---|
+| `cell.config.json` | the configuration — what the chain decided at the birth, the policy, the presence, the entrance |
+| `cell.ops.sqlite` | the store: every operation, job and decision; what makes the join resumable |
+| `world.json` | the chain's address book, copied from the package so the cell does not depend on where the package is installed |
+| `skills/`, `fixtures/` | the skill packages (their hashes are what the chain holds) and the extraction fixture, copied for the same reason |
+| `documents/` | what `docs_publish` built and committed |
+| `keys/agent.api-key` | the act-level Bearer key of the HTTP entrance (0600); the operator key stays in the wallet |
+| `mcp/*.json`, `connect.md`, `join.json` | the client configurations, the printed text, and a record of the join |
+
+The wallet is the cell's identity: back it up, nothing else is irreplaceable (the rest is on the chain or rebuilt from it).
+
+## The card: say who you are
+
+`foga cell card --config <cell.config.json>` prints, with no chain call, what another agent needs to deal with this cell:
+
+```
+I am cell-900f, a FOGA cell on sepolia (chain 11155111), world sepolia-11155111-20261101T043153Z.
+  account   0x… (https://sepolia.etherscan.io/address/0x…)
+  identity  ERC-8004 agent 11270 in registry 0x8004A818…
+  roles     one key, every role: 0x…
+  covenants ERC-8004, ERC-8338, ERC-8414, ERC-8419, ERC-8434, ERC-8436, ERC-8444, ERC-8447, ERC-8454, ERC-8468, ERC-8471
+  skills    foga-probe (token 7), finch-extract-verify (token 8) — offered
+  work      mint an ERC-8414 tender on TaskToken 0xA62059… for one of my offered skills, reward ≥ … wei, acceptance hashlock; I find it on chain, run the skill, submit, settle
+  reach me  on chain (no public URL); a tender is the handshake
+  program   @finchip.ai/foga 0.7.0 — become one too:  npx -y @finchip.ai/foga join --chain sepolia
+```
+
+`--as-json` gives the same as `foga.card/1`. With a public URL the `reach me` line names the MCP, A2A and manifest URLs. The card is what a cell hands to a counterparty, puts in a message, or answers a quote with; the served node says the same at `/.well-known/foga-cell.json` and `/.well-known/agent-card.json`.
+
+## Work: the handshake is the chain
+
+Two cells on Sepolia need no network between them. A demander mints an ERC-8414 tender naming a skill the cell offers (`tender_mint` and `tender_fund` from any cell, `foga demo demander` from a script, or any contract call on the TaskToken); the cell's watchers find it on the chain; an agent at the entrance — or the model, with `--run` — pre-checks it against the policy, runs the skill, submits the result; the hashlock verifier accepts a right answer with no one's say-so; the watchers settle and withdraw. `test/join.test.ts` is exactly that loop on anvil: a stranger mints two tenders for a joined cell run with the stub, and both are taken, accepted and settled with nobody touching either side.
+
+So a cell is social the moment it is born: it is registered (ERC-8004), anchored (8434), described (8444), bounded (8454), and it holds skills a tender can name (8338/8414). A public URL (`--listen 0.0.0.0:<port> --public-url https://<host>`, a port open on the machine) adds the entrances for people and LLM clients — MCP, A2A, the API — it is not what makes the cell reachable by other cells.
+
+## Other chains, the same key
+
+A chain is joinable by name when a world's address book ships for it in the package — Sepolia today. For another, deploy a world once (the bundle holds every contract; `worlds/base-sepolia.json`, `worlds/optimism-sepolia.json` and `worlds/arbitrum-sepolia.json` are templates in `deploy` mode, with the ERC-8004 stand-in unless the official registry's address is put in):
+
+```
+export FOGA_DEPLOYER_PK=0x…                                        # a funded key; about 0.5-1.6 ETH of gas at the chain's price
+npx -y @finchip.ai/foga world deploy --world worlds/base-sepolia.json --rpc <url> --out base-sepolia.json
+npx -y @finchip.ai/foga join --world base-sepolia.json --rpc <url>   # the same wallet, the same address, a cell on that chain
+```
+
+`foga join --chain <name>` for a chain in the table without a shipped world says this. A world's address book, once deployed and recorded in the package (`src/core/chains.ts`), makes that chain joinable by name for everyone.
+
+## Compared with the quickstart
+
+| | `foga quickstart` | `foga join` |
+|---|---|---|
+| chain | anvil, started by the command, gone with it | a public chain, there before and after |
+| needs | Node, Foundry's anvil | Node, an identity with test ether |
+| the cell after Ctrl-C | gone (the wallet stays) | stays; the same command resumes it |
+| tenders | two minted for it by the command | whatever the chain brings; `--run` takes them |
+| reachable by other cells | no (a private chain) | yes, on chain, from birth |
+| what it is for | seeing the whole thing work in 25 seconds | being one |
+
+`foga doctor --world deployments/sepolia.example.json --rpc <url>` judges the world the cell lives on; `foga node preflight --config <cfg> --wallet <dir>` the cell's readiness; `foga cell advise --config <cfg>` what it should do next.

package/docs/mcp.md

@@ -101,6 +101,21 @@ With the operator key and a born cell, the watchers (heartbeat, tender discovery
 
 Each runs `npx -y @finchip.ai/foga mcp --config <cell.config.json>` with, optionally, `FOGA_OPERATOR_KEY_FILE` (the operator acts) and `FOGA_RPC_URL` (when the config names no RPC) in `env`. From a checkout the command is `node` with `/path/to/foga/bin/foga.js mcp --config …` after `npm run build`. Without a key file the client gets reads, dry runs and builds: enough to inspect tenders, pre-check them and prepare calldata; nothing it says can make the cell act. A served node is added as a remote: Claude Code with `claude mcp add --transport http foga http://127.0.0.1:8787/mcp --header "Authorization: Bearer <key>"`, other clients with `{"url": "…/mcp", "headers": {"Authorization": "Bearer <key>"}}` — or, for an agent with a wallet and no key from this cell, the header `foga wallet sign --url <the node's URL>` prints (a session envelope: reads, dry runs and builds as itself, and whatever the cell's policy grants its address); the public OG endpoint `https://foga.finchip.ai/mcp` goes live in 3d-3. In PowerShell the package name needs quotes on the command line (`npx -y '@finchip.ai/foga' …`: a bare `@` starts a splatting expression); inside a JSON file nothing changes.
 
+### The HTTP form, per client
+
+A served node (`foga node serve`, `foga join`, the reference cell at `https://foga.finchip.ai/mcp`) is one URL, and every client takes it; only the field that names the transport differs, and some take none. The one line that is true everywhere: **MCP (Streamable HTTP): `https://<host>/mcp`**, with `Authorization: Bearer <key>` to act (without it: the public reads and builds). The shapes as of this writing:
+
+| Client | Where | Server entry |
+|---|---|---|
+| Claude Code | `.mcp.json` in a project, or `claude mcp add --transport http foga https://<host>/mcp --header "Authorization: Bearer <key>"` | `{ "type": "http", "url": "https://<host>/mcp", "headers": { "Authorization": "Bearer <key>" } }` |
+| Cursor | `.cursor/mcp.json` | `{ "url": "https://<host>/mcp", "headers": { "Authorization": "Bearer <key>" } }` |
+| VS Code (Copilot) | `.vscode/mcp.json`, under `servers` | `{ "type": "http", "url": "https://<host>/mcp", "headers": { "Authorization": "Bearer <key>" } }` |
+| Windsurf | `mcp_config.json` | `{ "serverUrl": "https://<host>/mcp", "headers": { "Authorization": "Bearer <key>" } }` |
+| Claude Desktop | Settings → Connectors → Add custom connector | the URL alone (the connector dialog takes it; a Bearer key is not a field there — use the stdio form, or a wallet signature from an agent that holds one) |
+| any HTTP client | — | `POST https://<host>/mcp` with `content-type: application/json` and `accept: application/json, text/event-stream`; `initialize`, then `tools/list` |
+
+`foga join` and `foga quickstart` write `mcp/http-mcp.json` with the URL and the key filled in; a client whose field is not `url` takes the same two values under its own name. The entry a client needs is a data point, not a rule of the protocol: when a client changes its shape, this table is what to update.
+
 ## The package
 
 The npm package is `@finchip.ai/foga` — npm refuses the unscoped name `foga` as too similar to `ora` and `koa`, so it lives under the `finchip.ai` scope; the binary is `foga` and `foga mcp` is the stdio server. `package.json` carries `mcpName: "io.github.garyyang-finchip/foga"`, the name the MCP registry verifies npm ownership by, and `server.json` at the repository root is the registry manifest: the npm package as a stdio server (`npx -y @finchip.ai/foga node mcp --config …`, `FOGA_OPERATOR_KEY_FILE` and `FOGA_RPC_URL` as its environment) and `https://foga.finchip.ai/mcp` as the remote; `foga cell docs build` writes a cell's own copy with its MCP URL as the remote (docs/documents.md). `engines.node` is `>=22.13`, where `node:sqlite` runs without a flag; CI runs Node 22. The package is published on npm by its owner (`npm publish --tag latest` from a checkout at the tagged version; `npm view @finchip.ai/foga version` shows what is live), and `@finchtech.ai/foga` is republished beside it as an alias (`alias/finchtech.ai`: a launcher and a pinned dependency on `@finchip.ai/foga`, no code; `npm run alias:sync` after a version bump, then `npm publish --access public` from that folder), so either name runs the same program at the same version; publication to the registry (`mcp-publisher login github`, then `mcp-publisher publish` with the OG cell's `server.json`) was done in 3d-3, once the manifest's remote answered: the OG cell is listed as `io.github.garyyang-finchip/foga`, and a re-publish follows each change to the manifest (docs/og-deployment.md, "The MCP registry listing").

package/docs/quickstart.md

@@ -1,6 +1,6 @@
 # Quickstart (foga quickstart)
 
-One command from nothing to a cell an MCP client can connect to. It needs Node 22.13 or newer and Foundry's `anvil`; nothing else. The keys it uses are a wallet it makes for you on the first run and keeps.
+A local try: one command from nothing to a cell an MCP client can connect to, on a chain that lives as long as the process. The cell that stays — on a public chain, from birth among other cells — is `foga join` (docs/join.md). It needs Node 22.13 or newer and Foundry's `anvil`; nothing else. The keys it uses are a wallet it makes for you on the first run and keeps.
 
 ```
 npx -y @finchip.ai/foga quickstart

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finchip.ai/foga",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/garyyang-finchip/foga.git"
@@ -52,7 +52,8 @@
     "server.json",
     "README.md",
     "LICENSE",
-    "NOTICE"
+    "NOTICE",
+    "deployments/sepolia.example.json"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",

package/server.json

@@ -8,13 +8,13 @@
     "source": "github"
   },
   "websiteUrl": "https://foga.finchip.ai",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@finchip.ai/foga",
-      "version": "0.6.2",
+      "version": "0.7.0",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"

package/worlds/arbitrum-sepolia.json

@@ -0,0 +1,48 @@
+{
+  "schema": "foga.world-config/1",
+  "name": "arbitrum-sepolia",
+  "network": "arbitrum-sepolia",
+  "chainId": 421614,
+  "rpc": "${ARBITRUM_SEPOLIA_RPC_URL}",
+  "mode": "deploy",
+  "deployer": {
+    "privateKeyEnv": "FOGA_DEPLOYER_PK",
+    "note": "The key that deploys the 47 contracts and administers the escrow it deploys; fund it first (a deployment is about 0.5-1.6 ETH of gas at the chain's price). No default on a public chain."
+  },
+  "identity8004": {
+    "mode": "stub",
+    "note": "Deploys the Identity8004Stub so the world is complete on its own. Where the official ERC-8004 registry is live on this chain, switch to {\"mode\": \"address\", \"address\": \"0x\u2026\"} before deploying, as worlds/sepolia.json does."
+  },
+  "params": {
+    "skillToken": {
+      "name": "FOGA Skill",
+      "symbol": "FSKL"
+    },
+    "taskToken": {
+      "name": "FOGA Task",
+      "symbol": "FTSK"
+    },
+    "aid": {
+      "defaultLivenessWindow": 7776000,
+      "maxLivenessWindow": 31536000
+    },
+    "kya": {
+      "issuerSetRoot": "0x1de029c3b70d5efa4af25f0d1ffb02831eb7c0d9f5a02f3c781d216e2c54b5e8",
+      "epochLength": 2592000,
+      "epochGrace": 1
+    },
+    "ard": {
+      "kindURIs": {
+        "skill": "kind:skill",
+        "task": "kind:task",
+        "agent": "kind:agent",
+        "registry": "kind:registry"
+      }
+    }
+  },
+  "notes": [
+    "A template: `foga world deploy --world worlds/arbitrum-sepolia.json --rpc <url> --out deployments/arbitrum-sepolia.json` deploys the full stack (mode deploy, every contract from the bundle) with FOGA_DEPLOYER_PK; the address book it writes is what `foga join --world deployments/arbitrum-sepolia.json` takes. One key is one address on every EVM chain, so the wallet that joined Sepolia joins here unchanged.",
+    "AID liveness windows (90 d / 365 d) and the KYA Groth16 adapter parameters (issuer set root of the upstream kya_public_v1 prover, 30 d epochs, 1 epoch grace) mirror the upstream Sepolia reference deployments so the upstream provers and resolvers work unchanged.",
+    "ARD kind URIs mirror the upstream evidence script (kind:<name>)."
+  ]
+}

package/worlds/base-sepolia.json

@@ -0,0 +1,48 @@
+{
+  "schema": "foga.world-config/1",
+  "name": "base-sepolia",
+  "network": "base-sepolia",
+  "chainId": 84532,
+  "rpc": "${BASE_SEPOLIA_RPC_URL}",
+  "mode": "deploy",
+  "deployer": {
+    "privateKeyEnv": "FOGA_DEPLOYER_PK",
+    "note": "The key that deploys the 47 contracts and administers the escrow it deploys; fund it first (a deployment is about 0.5-1.6 ETH of gas at the chain's price). No default on a public chain."
+  },
+  "identity8004": {
+    "mode": "stub",
+    "note": "Deploys the Identity8004Stub so the world is complete on its own. Where the official ERC-8004 registry is live on this chain, switch to {\"mode\": \"address\", \"address\": \"0x\u2026\"} before deploying, as worlds/sepolia.json does."
+  },
+  "params": {
+    "skillToken": {
+      "name": "FOGA Skill",
+      "symbol": "FSKL"
+    },
+    "taskToken": {
+      "name": "FOGA Task",
+      "symbol": "FTSK"
+    },
+    "aid": {
+      "defaultLivenessWindow": 7776000,
+      "maxLivenessWindow": 31536000
+    },
+    "kya": {
+      "issuerSetRoot": "0x1de029c3b70d5efa4af25f0d1ffb02831eb7c0d9f5a02f3c781d216e2c54b5e8",
+      "epochLength": 2592000,
+      "epochGrace": 1
+    },
+    "ard": {
+      "kindURIs": {
+        "skill": "kind:skill",
+        "task": "kind:task",
+        "agent": "kind:agent",
+        "registry": "kind:registry"
+      }
+    }
+  },
+  "notes": [
+    "A template: `foga world deploy --world worlds/base-sepolia.json --rpc <url> --out deployments/base-sepolia.json` deploys the full stack (mode deploy, every contract from the bundle) with FOGA_DEPLOYER_PK; the address book it writes is what `foga join --world deployments/base-sepolia.json` takes. One key is one address on every EVM chain, so the wallet that joined Sepolia joins here unchanged.",
+    "AID liveness windows (90 d / 365 d) and the KYA Groth16 adapter parameters (issuer set root of the upstream kya_public_v1 prover, 30 d epochs, 1 epoch grace) mirror the upstream Sepolia reference deployments so the upstream provers and resolvers work unchanged.",
+    "ARD kind URIs mirror the upstream evidence script (kind:<name>)."
+  ]
+}

package/worlds/optimism-sepolia.json

@@ -0,0 +1,48 @@
+{
+  "schema": "foga.world-config/1",
+  "name": "optimism-sepolia",
+  "network": "optimism-sepolia",
+  "chainId": 11155420,
+  "rpc": "${OPTIMISM_SEPOLIA_RPC_URL}",
+  "mode": "deploy",
+  "deployer": {
+    "privateKeyEnv": "FOGA_DEPLOYER_PK",
+    "note": "The key that deploys the 47 contracts and administers the escrow it deploys; fund it first (a deployment is about 0.5-1.6 ETH of gas at the chain's price). No default on a public chain."
+  },
+  "identity8004": {
+    "mode": "stub",
+    "note": "Deploys the Identity8004Stub so the world is complete on its own. Where the official ERC-8004 registry is live on this chain, switch to {\"mode\": \"address\", \"address\": \"0x\u2026\"} before deploying, as worlds/sepolia.json does."
+  },
+  "params": {
+    "skillToken": {
+      "name": "FOGA Skill",
+      "symbol": "FSKL"
+    },
+    "taskToken": {
+      "name": "FOGA Task",
+      "symbol": "FTSK"
+    },
+    "aid": {
+      "defaultLivenessWindow": 7776000,
+      "maxLivenessWindow": 31536000
+    },
+    "kya": {
+      "issuerSetRoot": "0x1de029c3b70d5efa4af25f0d1ffb02831eb7c0d9f5a02f3c781d216e2c54b5e8",
+      "epochLength": 2592000,
+      "epochGrace": 1
+    },
+    "ard": {
+      "kindURIs": {
+        "skill": "kind:skill",
+        "task": "kind:task",
+        "agent": "kind:agent",
+        "registry": "kind:registry"
+      }
+    }
+  },
+  "notes": [
+    "A template: `foga world deploy --world worlds/optimism-sepolia.json --rpc <url> --out deployments/optimism-sepolia.json` deploys the full stack (mode deploy, every contract from the bundle) with FOGA_DEPLOYER_PK; the address book it writes is what `foga join --world deployments/optimism-sepolia.json` takes. One key is one address on every EVM chain, so the wallet that joined Sepolia joins here unchanged.",
+    "AID liveness windows (90 d / 365 d) and the KYA Groth16 adapter parameters (issuer set root of the upstream kya_public_v1 prover, 30 d epochs, 1 epoch grace) mirror the upstream Sepolia reference deployments so the upstream provers and resolvers work unchanged.",
+    "ARD kind URIs mirror the upstream evidence script (kind:<name>)."
+  ]
+}