@finchip.ai/foga 0.6.2 → 0.7.0

package/dist/cli.js

@@ -53,6 +53,11 @@ usage:
                                                  one command to a live cell: the wallet (made on the first run, reused after), anvil, the local world, a cell born with
                                                  the wallet's keys and its two skills, two tenders, the node serving HTTP and MCP, and the MCP client configurations
                                                  printed with every path filled in (~/.foga/quickstart)
+  foga join [--chain sepolia | --world <deployed.json>] [--rpc <url>] [--name <cell>] [--dir <dir>] [--wallet <dir>]
+            [--listen <host:port> | --no-serve] [--public-url <url>] [--run stub|anthropic] [--no-wait] [--min-wei <n>] [--capital-wei <n>] [--exit]
+                                                 one command to a cell that lives on a public chain: the wallet (made once, the same address on every chain), the
+                                                 chain's world from the package, a wait for the identity to be funded, the birth, the skills minted and offered, the
+                                                 documents on chain, the node served (or run with a model); resumable, in ~/.foga/cells/<network>/<name>, never cleared
   foga demo [--port <n>] [--keep] [--genesis <T0..T9>]   start anvil, deploy the local world, run the doctor (and the genesis)
   foga demo --loop-d [--model stub|anthropic|external] [--model-name <name>] [--seed <n>] [--no-recovery] [--port <n>] [--keep]
                                                  the above, then Loop D: a new cell born, a demander minting cases a-g, the node with a model (or served for an
@@ -525,6 +530,51 @@ async function main() {
             return; // a stop that was asked for: both children are gone
         fail(`${why}; the quickstart is over`);
     }
+    if (group === "join") {
+        const { runJoin } = await import("./node/join.js");
+        const run = str(flags, "run");
+        if (run && run !== "stub" && run !== "anthropic")
+            fail("--run must be stub or anthropic");
+        let result;
+        try {
+            result = await runJoin({
+                chain: str(flags, "chain"),
+                world: str(flags, "world"),
+                rpc: str(flags, "rpc"),
+                name: str(flags, "name"),
+                dir: str(flags, "dir"),
+                wallet: str(flags, "wallet"),
+                listen: flags["no-serve"] ? null : str(flags, "listen"),
+                publicUrl: str(flags, "public-url"),
+                run: run ?? null,
+                wait: !flags["no-wait"],
+                minWei: str(flags, "min-wei") ? BigInt(str(flags, "min-wei")) : undefined,
+                capitalWei: str(flags, "capital-wei") ? BigInt(str(flags, "capital-wei")) : undefined,
+                exit: Boolean(flags.exit),
+            });
+        }
+        catch (e) {
+            fail(e.message);
+        }
+        if (flags.exit || !result.nodeUrl) {
+            await result.stop();
+            return;
+        }
+        let asked = false;
+        const stopping = () => {
+            if (asked)
+                return;
+            asked = true;
+            console.error("join: stopping the node; the cell stays");
+            result.stop().finally(() => process.exit(0));
+        };
+        process.on("SIGINT", stopping);
+        process.on("SIGTERM", stopping);
+        const why = await result.ended;
+        if (why === "stopped")
+            return;
+        fail(`${why}; start it again with the same command`);
+    }
     if (group === "demo") {
         await demo({ port: Number(str(flags, "port") ?? 8545), keep: Boolean(flags.keep), genesis: str(flags, "genesis"), loopD: flags["loop-d"] ? loopDFlags(flags) : undefined });
         return;

package/dist/core/chains.js

@@ -0,0 +1,82 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { repoRoot } from "../util/fs.js";
+export const CHAINS = {
+    sepolia: {
+        name: "sepolia",
+        chainId: 11155111,
+        world: "deployments/sepolia.example.json",
+        rpcEnv: "SEPOLIA_RPC_URL",
+        rpc: ["https://ethereum-sepolia-rpc.publicnode.com", "https://rpc.sepolia.org", "https://1rpc.io/sepolia"],
+        faucets: ["https://cloud.google.com/application/web3/faucet/ethereum/sepolia", "https://www.alchemy.com/faucets/ethereum-sepolia", "https://sepoliafaucet.com"],
+        explorer: "https://sepolia.etherscan.io",
+        testnet: true,
+    },
+    "base-sepolia": {
+        name: "base-sepolia",
+        chainId: 84532,
+        world: null,
+        rpcEnv: "BASE_SEPOLIA_RPC_URL",
+        rpc: ["https://sepolia.base.org", "https://base-sepolia-rpc.publicnode.com"],
+        faucets: ["https://docs.base.org/base-chain/tools/network-faucets", "https://cloud.google.com/application/web3/faucet/base/sepolia"],
+        explorer: "https://sepolia.basescan.org",
+        testnet: true,
+    },
+    "optimism-sepolia": {
+        name: "optimism-sepolia",
+        chainId: 11155420,
+        world: null,
+        rpcEnv: "OPTIMISM_SEPOLIA_RPC_URL",
+        rpc: ["https://sepolia.optimism.io", "https://optimism-sepolia-rpc.publicnode.com"],
+        faucets: ["https://console.optimism.io/faucet", "https://cloud.google.com/application/web3/faucet/optimism/sepolia"],
+        explorer: "https://sepolia-optimism.etherscan.io",
+        testnet: true,
+    },
+    "arbitrum-sepolia": {
+        name: "arbitrum-sepolia",
+        chainId: 421614,
+        world: null,
+        rpcEnv: "ARBITRUM_SEPOLIA_RPC_URL",
+        rpc: ["https://sepolia-rollup.arbitrum.io/rpc", "https://arbitrum-sepolia-rpc.publicnode.com"],
+        faucets: ["https://docs.arbitrum.io/for-devs/dev-tools-and-resources/chain-info", "https://cloud.google.com/application/web3/faucet/arbitrum/sepolia"],
+        explorer: "https://sepolia.arbiscan.io",
+        testnet: true,
+    },
+    anvil: {
+        name: "anvil",
+        chainId: 31337,
+        world: null,
+        rpcEnv: "FOGA_RPC_URL",
+        rpc: ["http://127.0.0.1:8545"],
+        faucets: [],
+        explorer: null,
+        testnet: true,
+    },
+};
+/** The chain by name, or null; names are case-insensitive. */
+export function chainByName(name) {
+    return CHAINS[name.toLowerCase()] ?? null;
+}
+/** The chain whose id this is, or null. */
+export function chainById(chainId) {
+    return Object.values(CHAINS).find((c) => c.chainId === chainId) ?? null;
+}
+/** The absolute path of the packaged world for a chain, or null when none ships or the file is missing. */
+export function packagedWorld(chain) {
+    if (!chain.world)
+        return null;
+    const path = join(repoRoot(), chain.world);
+    return existsSync(path) ? path : null;
+}
+/** The RPC for a chain: the one given, the chain's own variable, the general one, then the first public endpoint. */
+export function resolveRpc(chain, given) {
+    if (given)
+        return { url: given, source: "flag" };
+    if (chain && process.env[chain.rpcEnv])
+        return { url: process.env[chain.rpcEnv], source: "env" };
+    if (process.env.FOGA_RPC_URL)
+        return { url: process.env.FOGA_RPC_URL, source: "env" };
+    if (chain?.rpc[0])
+        return { url: chain.rpc[0], source: "public" };
+    throw new Error("no RPC: pass --rpc <url> or set FOGA_RPC_URL");
+}

package/dist/mcp/server.js

@@ -145,7 +145,11 @@ export function buildMcpServer(o) {
     // how to become a cell: every cell carries the genome's instructions, so an agent that meets one can make itself one
     const quickstartDoc = join(repoRoot(), "docs", "quickstart.md");
     if (existsSync(quickstartDoc)) {
-        server.registerResource("quickstart", "foga://docs/quickstart", { title: "Become a cell", description: "How any agent makes itself a FOGA cell: one command, its own wallet, the same program this node runs.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(quickstartDoc, "utf8") }] }));
+        server.registerResource("quickstart", "foga://docs/quickstart", { title: "A local try", description: "How any agent makes itself a FOGA cell on a local chain in one command: its own wallet, the same program this node runs.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(quickstartDoc, "utf8") }] }));
+    }
+    const joinDoc = join(repoRoot(), "docs", "join.md");
+    if (existsSync(joinDoc)) {
+        server.registerResource("join", "foga://docs/join", { title: "Become a cell", description: "How any agent becomes a FOGA cell that lives on a public chain in one command (foga join): the wallet, the funding, the birth, the card, work over the chain, other chains with the same key.", mimeType: "text/markdown" }, async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: readFileSync(joinDoc, "utf8") }] }));
     }
     server.registerPrompt("become-a-cell", { title: "Become a cell", description: "Replicate: make yourself a FOGA cell on your own machine, with your own wallet — the same program as this node, your own identity.", argsSchema: z.object({}) }, () => ({
         messages: [
@@ -155,13 +159,15 @@ export function buildMcpServer(o) {
                     type: "text",
                     text: [
                         `You are talking to cell ${node.config.name}${cell ? ` (account ${cell.address})` : ""} through the Finch OG Agent node software, version ${o.version}. You can become a cell yourself: the program is public, the identity you make is your own, and nothing of this cell's identity is copied.`,
-                        "On a machine where you can run commands (Node 22.13 or newer, and Foundry's anvil for a local chain):",
-                        "1. A key of your own, first and once:  npx -y @finchip.ai/foga wallet new          (one signer key in ~/.foga/wallet — your identity, which fills every role a cell needs; never overwritten; a failure here never blocks the next step)",
-                        "2. A living cell on a local chain:  npx -y @finchip.ai/foga quickstart         (anvil, the world, a cell born with your wallet's keys, two tenders, the node served; it prints the MCP client configuration to connect a model to the cell)",
-                        "3. Connect your model: paste the printed configuration into your MCP client (Claude Desktop, Claude Code, Cursor, or any client with the HTTP form); the stdio form acts with your operator key, the HTTP form with the printed Bearer key.",
-                        "4. On a public chain, when you are ready: fund your key, then  foga cell new --wallet ~/.foga/wallet --world <world.json> …  and  foga cell init --config <cell.config.json> --wallet ~/.foga/wallet. (For a cold-owner / hot-operator / separate-guardian split, make the wallet with `foga wallet new --cell` instead; it is optional hardening, not a requirement.)",
-                        `5. With the wallet alone you can also call this cell as yourself:  npx -y @finchip.ai/foga wallet sign --url ${node.config.runtime.http.publicUrl ?? "<this node's URL>"}  prints an Authorization header (FOGA-EIP712) for its /api, /mcp and /a2a; what it is granted is this cell's policy.`,
-                        "The guide is the resource foga://docs/quickstart. In PowerShell, quote the package name: npx -y '@finchip.ai/foga' quickstart.",
+                        "On a machine where you can run commands (Node 22.13 or newer; Foundry's anvil only for the local try):",
+                        "1. A key of your own, first and once:  npx -y @finchip.ai/foga wallet new          (one signer key in ~/.foga/wallet — your identity, the same address on every EVM chain; never overwritten)",
+                        "2. A cell that lives, on a public chain:  npx -y @finchip.ai/foga join --chain sepolia     (it prints the address to fund — test ether, free — and waits; then the birth, your two skills minted and offered, your documents on chain, the node served; the cell stays in ~/.foga/cells/sepolia/<name>, and the same command resumes it. Add --run stub to take tenders on your own without a model, --listen 0.0.0.0:8787 --public-url https://<host> to be reachable from outside.)",
+                        "   A local try first, if you like:  npx -y @finchip.ai/foga quickstart     (anvil: a cell on a chain that ends with the process; nothing persists but the wallet)",
+                        "3. Say who you are:  npx -y @finchip.ai/foga cell card --config ~/.foga/cells/sepolia/<name>/cell.config.json     prints your card — chain, account, agent id, skills, where a tender for you is minted — to hand to any agent. Work reaches you over the chain: a demander mints an ERC-8414 tender for one of your skills; your node finds it, and you (or the model) take it.",
+                        "4. Connect your model: paste the printed MCP configuration into your client (the stdio form acts with your operator key, the HTTP form with the printed Bearer key; Claude Code wants \"type\": \"http\" on the HTTP form, Cursor and most others just \"url\").",
+                        "5. Another chain, the same key:  join --chain <name>  where a world ships (sepolia today), or  foga world deploy --world worlds/<chain>.json  once on a chain without one, then  join --world <its address book>.",
+                        `6. With the wallet alone you can also call this cell as yourself:  npx -y @finchip.ai/foga wallet sign --url ${node.config.runtime.http.publicUrl ?? "<this node's URL>"}  prints an Authorization header (FOGA-EIP712) for its /api, /mcp and /a2a; what it is granted is this cell's policy.`,
+                        "The guides are the resource foga://docs/quickstart and docs/join.md in the package. In PowerShell, quote the package name: npx -y '@finchip.ai/foga' join --chain sepolia.",
                         "What you get is a complete body: the ten standards, the catalog that decides, the acceptance (foga doctor, foga demo --loop-d). The mind driving it stays yours.",
                     ].join("\n"),
                 },

package/dist/node/card.js

@@ -0,0 +1,67 @@
+import { endpointsOf } from "../a2a/card.js";
+import { chainById } from "../core/chains.js";
+import { FOGA_COVENANTS } from "./propagation.js";
+import { PACKAGE_NAME } from "../util/version.js";
+export function cellCard(node, o) {
+    const cfg = node.config;
+    const world = node.world;
+    const chain = chainById(node.chainId);
+    const ep = endpointsOf(node);
+    const base = cfg.runtime.http.publicUrl?.replace(/\/+$/, "") ?? null;
+    const has = (id) => {
+        try {
+            return world.address(id);
+        }
+        catch {
+            return null;
+        }
+    };
+    const id = cfg.identity;
+    return {
+        schema: "foga.card/1",
+        name: cfg.name,
+        chain: { chainId: node.chainId, network: world.file.network, worldId: world.file.worldId, explorer: chain?.explorer ?? null },
+        identity: {
+            account: id.account ?? null,
+            agentId: id.agentId ?? null,
+            registry: has("identity8004/IdentityRegistry"),
+            owner: id.owner,
+            operator: id.operator,
+            guardian: id.guardian,
+            oneKey: id.owner === id.operator && id.operator === id.guardian,
+        },
+        covenants: { program: FOGA_COVENANTS, world: world.covenants() },
+        skills: Object.entries(cfg.skills.held).map(([sid, h]) => ({ id: sid, tokenId: String(h.tokenId), packageHash: h.packageHash ?? "", offered: cfg.skills.offered.includes(sid) })),
+        work: { taskToken: has("8414/TaskToken"), minRewardWei: String(cfg.policy.tenders.minRewardWei), acceptance: cfg.policy.tenders.acceptance, counterpartyMinLevel: cfg.policy.tenders.counterpartyMinLevel },
+        standing: id.standing ? { schemeId: id.standing.schemeId, issuers: id.standing.issuers } : null,
+        endpoints: { mcp: ep.mcp, a2a: ep.a2a, web: ep.web, manifest: base ? `${base}/.well-known/foga-cell.json` : null, card: base ? `${base}/.well-known/agent-card.json` : null },
+        program: { package: PACKAGE_NAME, version: o.version, join: `npx -y ${PACKAGE_NAME} join --chain ${chain?.name ?? "<chain>"}` },
+    };
+}
+/** The card as a few lines an agent can paste to another agent. */
+export function formatCard(c) {
+    const lines = [];
+    const where = c.chain.explorer && c.identity.account ? ` (${c.chain.explorer}/address/${c.identity.account})` : "";
+    lines.push(`I am ${c.name}, a FOGA cell on ${c.chain.network} (chain ${c.chain.chainId}), world ${c.chain.worldId}.`);
+    if (c.identity.account)
+        lines.push(`  account   ${c.identity.account}${where}`);
+    else
+        lines.push("  account   not born yet (foga cell init)");
+    if (c.identity.agentId)
+        lines.push(`  identity  ERC-8004 agent ${c.identity.agentId}${c.identity.registry ? ` in registry ${c.identity.registry}` : ""}`);
+    lines.push(`  roles     ${c.identity.oneKey ? `one key, every role: ${c.identity.owner}` : `owner ${c.identity.owner}, operator ${c.identity.operator}, guardian ${c.identity.guardian}`}`);
+    lines.push(`  covenants ${c.covenants.world.join(", ")}`);
+    const offered = c.skills.filter((s) => s.offered);
+    const heldOnly = c.skills.filter((s) => !s.offered);
+    lines.push(`  skills    ${offered.length ? offered.map((s) => `${s.id} (token ${s.tokenId})`).join(", ") + " — offered" : "none offered"}${heldOnly.length ? `; held: ${heldOnly.map((s) => s.id).join(", ")}` : ""}`);
+    if (c.standing)
+        lines.push(`  standing  scheme ${c.standing.schemeId.slice(0, 10)}… by ${c.standing.issuers.join(", ")}`);
+    if (c.work.taskToken)
+        lines.push(`  work      mint an ERC-8414 tender on TaskToken ${c.work.taskToken} for one of my offered skills, reward ≥ ${c.work.minRewardWei} wei, acceptance ${c.work.acceptance.join("/")}${c.work.counterpartyMinLevel ? `, your KYA level ≥ ${c.work.counterpartyMinLevel}` : ""}; I find it on chain, run the skill, submit, settle`);
+    if (c.endpoints.mcp)
+        lines.push(`  reach me  MCP ${c.endpoints.mcp} · A2A ${c.endpoints.a2a} · manifest ${c.endpoints.manifest}`);
+    else
+        lines.push("  reach me  on chain (no public URL); a tender is the handshake");
+    lines.push(`  program   ${c.program.package} ${c.program.version} — become one too:  ${c.program.join}`);
+    return lines.join("\n");
+}

package/dist/node/join.js

@@ -0,0 +1,343 @@
+import { spawn } from "node:child_process";
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { JsonRpcProvider, formatEther, parseEther } from "ethers";
+import { chainById, chainByName, packagedWorld, resolveRpc, CHAINS } from "../core/chains.js";
+import { newApiKey } from "../http/access.js";
+import { adviseCell, formatAdvice } from "./advise.js";
+import { cellCard, formatCard } from "./card.js";
+import { loadCellConfig, newCellConfig, saveCellConfig } from "./config.js";
+import { cellInit } from "./init.js";
+import { Node } from "./node.js";
+import { ensureWallet, ensuredKey, walletDir } from "./wallet.js";
+import { defaultCatalog, OPERATOR_CALLER } from "../tools/index.js";
+import { clientConfigs, clientLauncher } from "../demo/quickstart.js";
+import { cleanEnv, ownCli, waitForHttp } from "../demo/loop-d.js";
+import { nextFreePort, portInUse } from "../demo/anvil.js";
+import { repoRoot } from "../util/fs.js";
+import { PACKAGE_NAME, version } from "../util/version.js";
+export const JOIN_MARKER = "join.json";
+export const DEFAULT_SKILLS = ["foga-probe", "finch-extract-verify"];
+const PUBLIC_MIN = parseEther("0.03");
+const PUBLIC_COMFORTABLE = parseEther("0.05");
+export function fogaHome() {
+    return process.env.FOGA_HOME ?? join(homedir(), ".foga");
+}
+/** What a person is told while the identity waits for ether. */
+export function fundingMessage(p) {
+    const lines = [];
+    const need = p.minWei - p.balanceWei;
+    lines.push(`fund ${p.address} on ${p.network} (chain ${p.chainId}) with at least ${formatEther(need)} ETH more (it holds ${formatEther(p.balanceWei)}, needs ${formatEther(p.minWei)}; ${formatEther(PUBLIC_COMFORTABLE)} is comfortable).`);
+    if (p.chain?.testnet && p.chain.faucets.length)
+        lines.push(`  test ether is free: ${p.chain.faucets.join("  ·  ")}`);
+    if (p.chain && !p.chain.testnet)
+        lines.push("  this is a mainnet: the ether is real, and so is everything the cell will commit to.");
+    if (p.chain?.explorer)
+        lines.push(`  watch it arrive: ${p.chain.explorer}/address/${p.address}`);
+    return lines.join("\n");
+}
+async function balanceOf(rpc, address) {
+    const provider = new JsonRpcProvider(rpc, undefined, { staticNetwork: true });
+    try {
+        return await provider.getBalance(address);
+    }
+    catch (e) {
+        const why = e.shortMessage ?? e.message;
+        throw new Error(`cannot reach the RPC ${rpc} (${why}); pass --rpc <url> for one this machine can reach`);
+    }
+    finally {
+        provider.destroy();
+    }
+}
+export async function runJoin(o = {}) {
+    const log = o.log ?? ((line) => console.error(line));
+    const out = o.out ?? ((text) => console.log(text));
+    const root = repoRoot();
+    // --- the chain and its world: by name from the package, or a deployed address book given by path
+    let chain;
+    let worldSource;
+    if (o.world) {
+        worldSource = resolve(o.world);
+        if (!existsSync(worldSource))
+            throw new Error(`world file ${worldSource} not found`);
+        const file = JSON.parse(readFileSync(worldSource, "utf8"));
+        if (file.schema !== "foga.world/1")
+            throw new Error(`${worldSource} is not a world file (foga.world/1)`);
+        chain = chainById(Number(file.chainId)) ?? (file.network ? chainByName(file.network) : null);
+    }
+    else {
+        const name = (o.chain ?? "sepolia").toLowerCase();
+        chain = chainByName(name);
+        if (!chain)
+            throw new Error(`unknown chain "${name}"; known: ${Object.keys(CHAINS).join(", ")}. A chain not listed: deploy a world on it (foga world deploy --world worlds/<chain>.json --rpc <url>) and pass its address book with --world.`);
+        const packaged = packagedWorld(chain);
+        if (!packaged)
+            throw new Error(`no world ships for ${chain.name}: deploy one (foga world deploy --world worlds/${chain.name}.json --rpc <url>) and pass its address book with --world <file>`);
+        worldSource = packaged;
+    }
+    const worldFile = JSON.parse(readFileSync(worldSource, "utf8"));
+    const network = worldFile.network;
+    const local = network === "anvil";
+    const rpcResolved = resolveRpc(chain, o.rpc);
+    const rpc = rpcResolved.url;
+    if (rpcResolved.source === "public")
+        log(`join: no RPC given; using the public endpoint ${rpc} (shared and rate-limited — a dedicated one is advised: --rpc <url> or ${chain?.rpcEnv ?? "FOGA_RPC_URL"})`);
+    // --- the wallet: one key, the identity, made once and reused on every chain
+    const walletPath = resolve(o.wallet ?? walletDir());
+    const wallet = ensureWallet(walletPath, { name: "default" });
+    if (wallet.ephemeral)
+        throw new Error(`a cell that lives needs a wallet on disk, and ${walletPath} could not be written (${wallet.reason}); pass --wallet <a writable directory>`);
+    const singleKey = wallet.wallet.roles.length === 1 && wallet.wallet.roles[0] === "signer";
+    const identity = singleKey ? wallet.wallet.addresses.signer : wallet.wallet.addresses.owner;
+    log(`join: wallet ${wallet.created ? "made" : "using"} ${wallet.wallet.dir} — ${singleKey ? `identity ${identity} (one key, every role)` : `owner ${wallet.wallet.addresses.owner}, operator ${wallet.wallet.addresses.operator}, guardian ${wallet.wallet.addresses.guardian}`}; the same address on every EVM chain`);
+    // --- the cell's home: never cleared; a second join here resumes
+    const name = o.name ?? `cell-${identity.slice(2, 6).toLowerCase()}`;
+    const dir = resolve(o.dir ?? join(fogaHome(), "cells", network, name));
+    mkdirSync(dir, { recursive: true });
+    const configPath = join(dir, "cell.config.json");
+    const worldPath = join(dir, "world.json");
+    const keysDir = join(dir, "keys");
+    mkdirSync(keysDir, { recursive: true, mode: 0o700 });
+    if (!existsSync(worldPath))
+        writeFileSync(worldPath, readFileSync(worldSource));
+    // the skill packages and the fixtures travel with the cell: their hashes are what the chain holds, their files
+    // must stay where the cell is, not where this version of the package happens to be installed
+    for (const sub of ["skills", "fixtures"]) {
+        const dst = join(dir, sub);
+        if (!existsSync(dst))
+            cpSync(join(root, "scenarios", sub), dst, { recursive: true });
+    }
+    const resumed = existsSync(configPath);
+    if (resumed)
+        log(`join: resuming the cell in ${dir}`);
+    else {
+        const cfg = newCellConfig({
+            name,
+            world: "world.json",
+            store: "cell.ops.sqlite",
+            owner: wallet.wallet.addresses.owner ?? identity,
+            operator: wallet.wallet.addresses.operator ?? identity,
+            guardian: wallet.wallet.addresses.guardian ?? identity,
+            rpc: rpcResolved.source === "public" ? undefined : rpc,
+            skillsDir: "skills",
+            inputDir: "fixtures",
+            description: `Cell ${name}: born by foga join on ${network}`,
+        });
+        // a day with a birth, two mints and a publish in it spends more gas than the default daily cap allows on a chain
+        // that prices gas; the cap is raised to what the quickstart uses, and the operator's gas floor (a quarter of it)
+        // stays under the funding gate below
+        cfg.policy.budget.dailyGasWei = parseEther("0.02").toString();
+        cfg.runtime.http.listen = o.listen ?? "127.0.0.1:8787";
+        if (o.publicUrl)
+            cfg.runtime.http.publicUrl = o.publicUrl.replace(/\/+$/, "");
+        saveCellConfig(configPath, cfg);
+        log(`join: cell ${name} configured in ${dir} (world ${worldFile.worldId}, ${Object.keys(worldFile.contracts).length} contracts)`);
+    }
+    if (o.publicUrl) {
+        const loaded = loadCellConfig(configPath);
+        if (loaded.config.runtime.http.publicUrl !== o.publicUrl.replace(/\/+$/, "")) {
+            loaded.config.runtime.http.publicUrl = o.publicUrl.replace(/\/+$/, "");
+            saveCellConfig(configPath, loaded.config);
+        }
+    }
+    // --- the funding gate: nothing is sent until the identity can pay for its birth
+    const minWei = o.minWei ?? (local ? 0n : PUBLIC_MIN);
+    let balance = await balanceOf(rpc, identity);
+    if (balance < minWei) {
+        const msg = fundingMessage({ address: identity, chain, network, chainId: worldFile.chainId, balanceWei: balance, minWei });
+        if (o.wait === false)
+            throw new Error(`the identity is not funded yet.\n${msg}`);
+        log(`join: waiting for ether — ${msg}`);
+        const started = Date.now();
+        let lastSaid = started;
+        while (balance < minWei) {
+            if (Date.now() - started > 60 * 60_000)
+                throw new Error(`waited an hour for ${identity} to be funded; run the same command again once it is.\n${msg}`);
+            await new Promise((r) => setTimeout(r, local ? 1000 : 15_000));
+            balance = await balanceOf(rpc, identity);
+            if (balance < minWei && Date.now() - lastSaid > 120_000) {
+                lastSaid = Date.now();
+                log(`join: still waiting — ${identity} holds ${formatEther(balance)} ETH, needs ${formatEther(minWei)}`);
+            }
+        }
+        log(`join: funded — ${identity} holds ${formatEther(balance)} ETH`);
+    }
+    else
+        log(`join: ${identity} holds ${formatEther(balance)} ETH`);
+    // --- the birth: the owner's act; resumable, never repeated
+    let born = loadCellConfig(configPath).config.identity.account ?? null;
+    let agentId = loadCellConfig(configPath).config.identity.agentId ?? null;
+    if (!born) {
+        const node = await Node.open({ configPath, rpc, keys: { owner: ensuredKey(wallet, "owner") }, allowUnborn: true, log: () => { } });
+        try {
+            const r = await cellInit(node, { capitalWei: o.capitalWei, log: (line) => log(`join: ${line}`) });
+            born = r.account;
+            agentId = r.agentId;
+            log(`join: cell ${name} born as ${born} (ERC-8004 agent ${agentId}) in ${r.operations.length} operations`);
+        }
+        finally {
+            node.close();
+        }
+    }
+    else
+        log(`join: cell ${name} is ${born}${agentId ? ` (agent ${agentId})` : ""}, born before`);
+    // --- the skills: minted by the operator and offered; the documents committed on chain
+    const catalog = defaultCatalog();
+    {
+        const want = o.skills ?? DEFAULT_SKILLS;
+        const held = loadCellConfig(configPath).config.skills.held;
+        const missing = want.filter((s) => !held[s]);
+        if (missing.length) {
+            const node = await Node.open({ configPath, rpc, keys: { operator: ensuredKey(wallet, "operator") }, log: () => { } });
+            try {
+                for (const skill of missing) {
+                    const r = await catalog.invoke(node, "skill_mint", { skill }, OPERATOR_CALLER, { mode: "act" });
+                    if (!r.ok)
+                        throw new Error(`skill_mint ${skill}: ${r.gate}: ${r.reason}`);
+                    log(`join: skill ${skill} minted`);
+                }
+            }
+            finally {
+                node.close();
+            }
+        }
+        const loaded = loadCellConfig(configPath);
+        const offered = Object.keys(loaded.config.skills.held).filter((s) => want.includes(s));
+        if (offered.some((s) => !loaded.config.skills.offered.includes(s))) {
+            loaded.config.skills.offered = [...new Set([...loaded.config.skills.offered, ...offered])];
+            saveCellConfig(configPath, loaded.config);
+        }
+        log(`join: skills ${offered.join(", ")} held and offered`);
+    }
+    // --- an act-level API key for the HTTP entrance, kept in the cell's directory
+    const agentKeyPath = join(keysDir, "agent.api-key");
+    let apiKey;
+    {
+        const loaded = loadCellConfig(configPath);
+        const have = loaded.config.access.keys.find((k) => k.id === "agent");
+        if (have && existsSync(agentKeyPath))
+            apiKey = readFileSync(agentKeyPath, "utf8").trim();
+        else {
+            const api = newApiKey("agent");
+            loaded.config.access.keys = loaded.config.access.keys.filter((k) => k.id !== "agent");
+            loaded.config.access.keys.push({ id: "agent", sha256: api.sha256, level: "act", visibility: "caller", note: "the join's act-level key for the HTTP entrance" });
+            saveCellConfig(configPath, loaded.config);
+            writeFileSync(agentKeyPath, api.key + "\n", { mode: 0o600 });
+            apiKey = api.key;
+        }
+    }
+    {
+        const node = await Node.open({ configPath, rpc, keys: { operator: ensuredKey(wallet, "operator") }, log: () => { } });
+        try {
+            const r = await catalog.invoke(node, "docs_publish", {}, OPERATOR_CALLER, { mode: "act" });
+            if (!r.ok)
+                throw new Error(`docs_publish: ${r.gate}: ${r.reason}`);
+            const d = r.output;
+            // the same documents make the same job: a resume is answered from the store, and the chain is not asked again
+            const replayed = node.store.decisions({ limit: 1 })[0]?.gate === "idempotent";
+            log(`join: documents v${d.version} in ${d.dir}; ${replayed ? "the chain holds them (nothing sent)" : d.committed.length ? `committed on chain (${d.committed.join(", ")})` : "the chain already holds them"}`);
+        }
+        finally {
+            node.close();
+        }
+    }
+    // --- the node: served (every entrance, the watchers, no model) or run (with a model: it takes its tenders)
+    let listen = o.listen === undefined ? "127.0.0.1:8787" : o.listen;
+    if (listen) {
+        const lp = Number(listen.slice(listen.lastIndexOf(":") + 1));
+        if (await portInUse(lp)) {
+            if (o.listen !== undefined)
+                throw new Error(`port ${lp} is in use; pass --listen <host:port> (or --no-serve)`);
+            const next = await nextFreePort(lp + 1);
+            if (next === null)
+                throw new Error(`ports ${lp}-${lp + 20} are all in use; pass --listen <host:port>`);
+            log(`join: port ${lp} is in use; the node listens on ${next} instead`);
+            listen = `127.0.0.1:${next}`;
+        }
+    }
+    const operatorKeyPath = wallet.wallet.files.operator ?? wallet.wallet.files.signer;
+    const cli = ownCli();
+    let child = null;
+    let nodeUrl = null;
+    let endedWith = () => { };
+    const ended = new Promise((r) => (endedWith = r));
+    let stopping = false;
+    if (listen) {
+        const i = listen.lastIndexOf(":");
+        const host = listen.slice(0, i) || "127.0.0.1";
+        nodeUrl = `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${listen.slice(i + 1)}`;
+        const args = o.run ? ["node", "run", "--config", configPath, "--rpc", rpc, "--model", o.run, "--listen", listen] : ["node", "serve", "--config", configPath, "--rpc", rpc, "--listen", listen];
+        child = spawn(cli.command, [...cli.args, ...args], { env: cleanEnv({ FOGA_OPERATOR_KEY_FILE: operatorKeyPath }), stdio: ["ignore", "ignore", "pipe"] });
+        const idleTick = /: anchor ACTIVE, heartbeat not sent \([^)]*\); 0 new tender\(s\); 0 settled, 0 withdrawn; safety Satisfied$/;
+        child.stderr.on("data", (d) => {
+            for (const line of String(d).split("\n"))
+                if (line.trim() && !idleTick.test(line.trim()))
+                    log(`  node| ${line}`);
+        });
+        child.on("exit", (code, signal) => {
+            if (!stopping)
+                endedWith(`the node stopped (${code !== null ? `exit code ${code}` : `signal ${signal}`})`);
+        });
+        await waitForHttp(`${nodeUrl}/healthz`, 120);
+        const health = (await (await fetch(`${nodeUrl}/healthz`)).json());
+        if (!health.ok)
+            throw new Error("the node's /healthz is not ok");
+    }
+    else
+        endedWith("no node");
+    const stop = async () => {
+        stopping = true;
+        if (child) {
+            const { stopChild } = await import("../demo/anvil.js");
+            await stopChild(child);
+            child = null;
+        }
+        endedWith("stopped");
+    };
+    // --- the card and the configurations: what the cell is, and how anyone connects
+    const reader = await Node.open({ configPath, rpc, keys: {}, allowUnborn: true, log: () => { } });
+    let card;
+    let next = "";
+    try {
+        card = cellCard(reader, { version });
+        next = formatAdvice(adviseCell(reader), { brief: true, config: configPath });
+    }
+    finally {
+        reader.close();
+    }
+    const launcher = clientLauncher();
+    const configs = clientConfigs({ launcher, configPath, operatorKeyPath, nodeUrl, apiKey });
+    const mcpDir = join(dir, "mcp");
+    mkdirSync(mcpDir, { recursive: true });
+    for (const [file, text] of Object.entries(configs))
+        writeFileSync(join(mcpDir, file), text);
+    const lines = [];
+    lines.push(`foga join: cell ${name} lives on ${network}${resumed ? " (resumed)" : ""}`);
+    lines.push("");
+    lines.push(formatCard(card));
+    lines.push("");
+    lines.push(`  files     ${dir} — cell.config.json, cell.ops.sqlite (the store), world.json, skills/, documents/, keys/ (0600), mcp/*.json, connect.md`);
+    lines.push(`  wallet    ${wallet.wallet.dir} — the identity; back it up, it is the cell`);
+    if (nodeUrl)
+        lines.push(`  node      ${nodeUrl} (${o.run ? `running with model ${o.run}: it takes the tenders it is eligible for` : "served: every entrance and the watchers, no model"}) — /mcp, /api/<capability>, /a2a, /.well-known/foga-cell.json, /.well-known/agent-card.json, /healthz`);
+    lines.push("");
+    lines.push("Connect an MCP client over stdio (the client starts the server on this machine; with the operator key it acts for the cell):");
+    lines.push(configs["claude_desktop_config.json"].trimEnd().split("\n").map((l) => `  ${l}`).join("\n"));
+    if (nodeUrl) {
+        lines.push("");
+        lines.push(`Or over HTTP: MCP ${nodeUrl}/mcp and ${nodeUrl}/api/<capability> with   Authorization: Bearer ${apiKey}   (${join(mcpDir, "http-mcp.json")}); A2A at ${nodeUrl}/a2a.`);
+        lines.push(`Reachable from other machines only if ${listen.split(":")[0]} is not the loopback (--listen 0.0.0.0:<port>) and the port is open; then --public-url https://<host> puts the address in the documents and the card.`);
+    }
+    lines.push("");
+    lines.push("Work comes over the chain: a demander mints an ERC-8414 tender for an offered skill; the watchers find it; an agent at the entrance (or the model, with --run) pre-checks, runs the skill and submits; the hashlock verifier accepts a right answer; the watchers settle and withdraw.");
+    if (next)
+        lines.push("", next);
+    lines.push("");
+    lines.push(o.exit ? "Started with --exit: stopping the node." : `Ctrl-C stops the node; the cell stays. Start it again with the same command, or:  ${launcher.command} ${launcher.args.join(" ")} node serve --config ${configPath} --wallet ${wallet.wallet.dir}`);
+    const summary = lines.join("\n");
+    writeFileSync(join(dir, "connect.md"), `# foga join\n\n\`\`\`\n${summary}\n\`\`\`\n`);
+    writeFileSync(join(dir, JOIN_MARKER), JSON.stringify({ schema: "foga.join/1", joinedAt: new Date().toISOString(), package: PACKAGE_NAME, version, network, chainId: worldFile.chainId, worldId: worldFile.worldId, rpc: rpcResolved.source === "public" ? null : rpc, cell: name, account: born, agentId, wallet: wallet.wallet.dir, listen, publicUrl: o.publicUrl ?? null, run: o.run ?? null }, null, 2) + "\n");
+    out(summary);
+    return { dir, configPath, worldPath, rpc, chainId: worldFile.chainId, network, account: born, agentId, resumed, nodeUrl, card, stop, ended };
+}

package/docs/design-memo.md

@@ -117,6 +117,8 @@ Three checks, three vocabularies. A call to the node passes **call permission**
 
 **3d-2, the cell among other agents (0.6.0-alpha.7).** Six pieces, one principle (section 10). *The wallet.* `foga wallet new` makes an agent's keys on its own machine — by default one key, its identity, which fills every role a cell needs (the separated owner/operator/guardian set is the opt-in `--cell` hardening) — in 0600 files, with no network and no chain; it never overwrites, and whatever needs the keys goes on with keys made in memory when the disk refuses (`foga quickstart` makes the default wallet on its first run and births every later cell with it; `--wallet <dir>` on every `foga cell` and `foga node` command takes the role's key from there). *Signed callers.* `Authorization: FOGA-EIP712 <envelope>` is EIP-712 typed data in the cell's own domain (name FOGA, version 1, the chain, the cell's account): a `Request` envelope bound to method, path and body hash, good once within 120 s, or a `Session` envelope, reusable within 600 s for a client with static headers; the caller is the signing address and `access.signers` says what it is granted — the cell's own operator or owner remotely, an allow-list by address or by ERC-8004 agent id (checked against the registry's owner and agent wallet), a KYA standing threshold, a default of build, read or none; an act wants a request-bound envelope unless the policy says otherwise. `/api`, `/mcp` and `/a2a` take the same header; `GET /api/capabilities` tells a caller what it is. *The documents.* `foga cell docs build | publish | status` generates from one configuration the ERC-8004 registration (`registration-v1`, with `registrations`), the ERC-8434 AID document (identity, standing, skills and endpoints facets), the ERC-8444 descriptor, the ERC-8454 unit definition, the A2A agent card, the registry's `server.json` and a manifest of content hashes; the node serves them under `/documents` and `/.well-known`; `docs_publish` (the 31st capability, the operator's act) commits only what differs from the chain — `setAgentURI`, `setDocumentURI`, `updateDescriptor`, `publishVersion`, as one keyed job — and reads every commitment back; a cell without a public URL commits `data:` URIs and is complete on chain all the same. *Preflight.* `foga node preflight` reconciles a cell against the chain and the machine before it is served — the world, the account's revision, roles and allow-list, the budget, the operator key alone and its gas, the standing, the skills' packages and their executors actually run, the documents, the public URL, the model — as rows that are advisory by default and fatal with `--strict`. *A2A.* `POST /a2a` is the 1.0 JSON-RPC binding with the card at `/.well-known/agent-card.json`: a quote for anyone (the offered skills and the terms a tender needs to meet), a tender taken for an act-level caller as one task over the catalog's jobs (pre-check, run, submit; settlement stays the watchers'), `GetTask`, `ListTasks` scoped to the caller, `CancelTask` that undoes nothing broadcast, duplicates by (caller, messageId), the specification's error codes; no road does work first and talks about payment after. *Sourcify.* `foga world verify --sourcify` submits every FOGA-deployed contract of a world with the standard JSON input of its own compiler run — `forge build` leaves the build-info beside the artifacts — matched by runtime code and identified by the path solc saw; a local chain is a dry run and CI dry-runs all 47; the Sepolia run was 3d-3's (below: fifteen contracts, 2 exact_match and 13 match). The gate: `test/wallet.test.ts`, `test/signed.test.ts`, `test/documents.test.ts`, `test/a2a.test.ts`, `test/preflight.test.ts`, `test/sourcify.test.ts`, and `foga quickstart` ending with a cell whose documents are on chain, whose card answers and whose A2A entrance quotes. docs/wallet.md, docs/documents.md, docs/a2a.md, docs/node.md ("Preflight"), docs/world.md ("Verifying the sources").
 
+**3e-1, the cell that lives, in one command (0.7.0).** Two things the Phase 3 close left open were said plainly by the first outside reader: the one-command path led to a local chain that dies with its process, and the public-chain path was four commands with three things to prepare first — a world file to find, an RPC, a funded key. `foga join --chain sepolia` is the answer to both, and it adds nothing to the kernel: the wallet made or reused, the chain's address book from the package, a funding gate that prints the address and waits, then the birth, the skills, the documents and the node, each the same keyed operation `cell init`, `skill_mint`, `docs_publish` and `node serve` already were, so the command is resumable and idempotent by construction. The cell's directory carries the world and the skill packages with it — a cell must not depend on where this version of the package happens to be installed. `--run stub` makes the cell autonomous without a model: the deterministic decision table takes what the policy allows. `foga cell card` is the self-description the covenant was always implying — a cell knows its chain, account, identity, skills and where work for it is minted, and says so to any agent without a chain call. The social fact underneath: the handshake between cells is the chain, not the network; a tender minted for a cell's skill is found by its watchers wherever the demander is, and the hashlock verifier accepts a right answer with no one's say-so. `test/join.test.ts` runs that loop between a stranger and a joined cell on anvil. Other chains follow by the same key: a world deployed once (templates for three testnets ship), its address book handed to `join --world`. docs/join.md.
+
 **3d-3, the OG live and the public-chain evidence (0.6.0).** The reference cell is served: born fresh on Sepolia by the same path any cell takes (`wallet new`, `cell new`, `cell init`, `docs publish`, `node serve` — one key, no migration, no key handoff), agent 11261, account `0xD7155E48…`, its skill `finch-extract-verify` offered, its documents on chain, its fifteen FOGA-deployed contracts Sourcify-verified; served in host mode under systemd behind Caddy at `foga.finchip.ai`, so `/healthz`, `/.well-known/foga-cell.json`, `/.well-known/agent-card.json` and `/mcp` answer from outside and survive a reboot; listed in the MCP registry as `io.github.garyyang-finchip/foga` with the npm package as the stdio server and the public URL as the remote. The last acceptance ran on the public chain: Loop D with an outside agent (`--model external`, a person driving the HTTP entrance with the agent key), a second cell born for it (agent 11264), the demander's cases minted on Sepolia — and every invariant row Pass (every operation under an allowed decision; eleven refusals across policy, verifier, skill, conflict, budget, safety and execution with nothing broadcast; the four budget books; sixteen operator transactions at the account, allow-listed, none reverted; the recovery drill across a kill and restart with nothing sent twice; idempotency; conflict; concurrency), cases a, c, d, d2 and e as expected. The run also returned four findings a local chain cannot produce, each closed in 0.6.0 (docs/loop-d.md, "On a public chain"): a working directory reused across runs replayed the previous run's keyed operations (the orchestrator now clears its own files); the roles' gas reserve, priced at a near-zero gas price, left the operator under the policy's gas floor (the reserve is floored at 1 gwei); the settlement figure read as the account's balance delta took in a concurrent mint's escrow (it is now the tender's own: escrow released less credit left); a 9000-block log scan overran the worker's minute on a shared endpoint (the scan is windowed, the public-chain budget three minutes). docs/og-deployment.md, docs/loop-d.md.
 
 ## 10. Five defaults settled in 3d