@flow-engineer/flow 0.2.1 → 0.2.3

package/README.md

@@ -26,23 +26,31 @@ Flow Framework makes the chat behaviour the default. You write the agent's promp
 Node 22.18 or later. Your agent is TypeScript that Node runs as it is, with no build step.
 
 ```bash
-npx @flow-engineer/flow new my-agent && cd my-agent && npm install
-cp .env.example .env        # then put one model key in it; the file says where to make one
+npx @flow-engineer/flow new my-agent --display-name "My agent" && cd my-agent && npm install
+npx @flow-engineer/flow link   # signs in; writes Flow's free trial model key and a phone link (or put your own key in .env)
 npm start
 ```
 
-`flow new <name>` makes `./<name>/` from the café example (lowercase letters, digits and dashes). Open the link `npm start` prints and text Pip, a café ordering assistant: your starting point. Pick a platform at the top (SMS, WhatsApp, iMessage, Telegram, web), and turn on **Debug** to see every tool call and how fast each message was answered. A model call that fails (a wrong or expired key, say) shows in the chat, in Debug and on the terminal. The café's `src/agent.ts` reads its model id from `CAFE_MODEL` (default: the model for the key you set, see [Models](#models)). The new folder has the coding-agent skills in `.claude/skills/` and an `AGENTS.md` pointing at them, so you can tell Claude Code, Codex or any coding agent what to build.
+`flow new <name>` makes `./<name>/` from the café example (lowercase letters, digits and dashes); `--display-name` is what people call it, kept as `displayName` in its `package.json`, and a phone reaches it by sending `Hi <that name> (ref <code>)`. Open the link `npm start` prints and text Pip, a café ordering assistant: your starting point. Pick a platform at the top (SMS, WhatsApp, iMessage, Telegram, web), and turn on **Debug** to see every tool call and how fast each message was answered. A model call that fails (a wrong or expired key, say) shows in the chat, in Debug and on the terminal. The café's `src/agent.ts` reads its model id from `CAFE_MODEL` (default: the model for the key you set, see [Models](#models)). The new folder has the coding-agent skills in `.claude/skills/` and an `AGENTS.md` pointing at them, so you can tell Claude Code, Codex or any coding agent what to build.
 
 ### On your phone, from your laptop
 
 ```bash
-npx @flow-engineer/flow init                 # the same starter in the current folder; then npm install and the model key
-printf 'hi\n' | npx @flow-engineer/flow chat  # talk to it in the terminal: no account
-npx @flow-engineer/flow link                 # signs in (opens the browser), writes its keys into .env, prints a link
-npm start                                    # open the link on your phone and text the agent
+npx @flow-engineer/flow init                 # the same starter in the current folder; then npm install
+npx @flow-engineer/flow link                 # signs in (opens the browser), writes its keys and Flow's trial model key into .env, prints a link
+npm start                                    # try it in the playground link it prints, then open the phone link and text the agent
+npx @flow-engineer/flow status               # what the folder has and lacks
 ```
 
-`flow chat` builds the agent from `src/agent.ts` and writes as its first test person, one message per line of stdin. `flow link` signs in and runs `flow setup` when the folder is not set up yet, then prints the link for `--channel telegram` (the default), `whatsapp` or `imessage`; a channel flow.engineer cannot open yet answers with what to do instead. With `FLOW_MESSAGING_KEY` in `.env`, the starter's `npm start` is on Telegram, plus WhatsApp and iMessage when `.env` has their senders, and connects to Flow Messaging by its outbound event stream, so there is no tunnel or public URL, and messages sent while it was stopped arrive when it starts again ([flow-messaging/README.md](flow-messaging/README.md)). Coding agents: [docs/agents.md](docs/agents.md) has the exit codes and `next` steps.
+Test it first in the playground (the link `npm start` prints: the test people and the channels side by side), then on your phone. `flow chat` (the agent in the terminal) and `npm test -- --synthetic` are how a coding agent checks its own work.
+
+`flow chat` builds the agent from `src/agent.ts` and writes as its first test person, one message per line of stdin. `flow link` signs in and runs `flow setup` when the folder is not set up yet, then prints the link for `--channel telegram` (the default), `whatsapp` or `imessage`; a channel flow.engineer cannot open yet answers with what to do instead. With `FLOW_MESSAGING_KEY` in `.env`, the starter's `npm start` is on Telegram, plus WhatsApp and iMessage when `.env` has their senders, and connects to Flow Messaging by its outbound event stream, so there is no tunnel or public URL, and messages sent while it was stopped arrive when it starts again ([flow-messaging/README.md](flow-messaging/README.md)). Coding agents: [docs/agents.md](docs/agents.md) (https://flow.engineer/flow-framework/agents.md) has the exit codes and `next` steps.
+
+**Shared test numbers and privacy.** The free trial runs on Flow's shared Telegram bot, WhatsApp number and iMessage line. A join code binds that phone to one app, so its messages go only to that app's agent; sending another app's code moves it. Trial chats are test data, kept for the account's retention (30 days by default). Do not use the trial for real customers' data: connect your own number for that.
+
+**Stability.** 0.x: the CLI's commands, `--json` fields and exit codes in [docs/agents.md](docs/agents.md) stay compatible within 0.2.x; a breaking change comes with a minor version bump and a release note. Pin the version in `package.json` for production.
+
+**Host it.** Coming soon: `npx @flow-engineer/flow deploy`, to keep the agent answering while the laptop sleeps.
 
 ### In a folder of your own
 
@@ -74,7 +82,7 @@ console.log(`Playground: ${url}/`);
 ```
 
 ```bash
-echo "OPENROUTER_API_KEY=sk-or-..." > .env
+npx @flow-engineer/flow setup      # writes FLOW_KEY (the agent's Flow key, on Flow's trial credit), or: echo "OPENROUTER_API_KEY=sk-or-..." > .env
 node --env-file=.env src/main.ts
 ```
 
@@ -154,6 +162,8 @@ await play.listen(buildAgent({ events: [play.events] }), 8788);
 
 The playground plays only the test people you declare (`testPeople: [{ name, phone }]`) on the agent's own channels. A test person is a real person to the agent: the same identity, `resolve` and history as if they wrote from their phone, one conversation on every channel, and "Clear history" to start again. Replies go back where the person last wrote from, the playground or the real channel. The playground's Person tab moves the agent's clock (`simulators({ clock: playgroundClock() })`, with `createAgent({ now: clock.now })`), lists what is scheduled or held for them, sets their time zone and quiet hours, and sends nudges with every field the API takes. Locally it answers only on localhost, and its API only its own page, so a site you visit cannot send it messages. On a deployed agent, mount `play.handler(agent, { token })`: it refuses requests without the token (at least 32 characters), swaps `?token=` for a cookie on the playground's path, and limits wrong tries.
 
+To test account sign-in, give `simulators` an `authentication({ channel, visitor })` hook. The person picker gains **New user · signed out**: the hook returns a sign-in URL until the application verifies the visitor, then its account `key` and channel `address`. The playground uses that account's existing conversation and keeps replies inside the simulator. Each interface authenticates independently; verified-phone channels can resolve the account directly. Existing test people keep their identity shortcut. See [setting up authentication](coding-agents/auth-skill.md#exercise-sign-in-in-the-playground).
+
 `AGENTS.md` says what the agent is for and what it may and may not do. Leave messaging out of it: Flow Framework adds how to talk on each channel (its send tool, reactions, formatting, acknowledging first). A skill's `SKILL.md` starts with a `name` and `description`; the agent sees every description and loads a skill when it needs it (`inlineSkills: true` puts them all in the prompt instead).
 
 ## Channels and people
@@ -510,9 +520,52 @@ It sends a fixed set of synthetic messages (a typed message, a double text, a ph
 
 The café's agent as an HTTP endpoint, with its two tools and one model through any OpenAI-compatible API (the same key variables as `openAICompatible`, `MODEL` for the model; `FAKE_MODEL=1` for a fixed reply and no model call): [`examples/http-agent-python`](examples/http-agent-python) (standard library only) and [`examples/http-agent-go`](examples/http-agent-go) (standard library only).
 
+## The same tools in Claude, ChatGPT and a CLI
+
+The tools and skills you write for the chat agent are also an MCP server, so people use them from
+Claude, ChatGPT or any MCP host, and a command line for your organization. Each needs the official
+MCP SDK, an optional peer installed only when you use it.
+
+```ts
+import { mcpServer } from "@flow-engineer/flow/mcp";            // npm i @modelcontextprotocol/server@2.3.1
+
+const mcp = mcpServer({ name: "cafe", version: "1.0.0", tools, dir: "agent" });
+createServer((req, res) => void mcp.node(req, res)).listen(8790);   // Streamable HTTP at /mcp
+```
+
+- Every tool becomes an MCP tool with every field filled from the tool: `title`, `output` (sent as
+  structured content), `status` lines, and `hints` (`readOnly`, `destructive`, `idempotent`,
+  `openWorld`) as MCP annotations. Chat ignores all of these. Skills go as the server's
+  instructions and a `read_skill` tool.
+- Sign-in is the host's OAuth against your own authorization server: `auth: { issuer, scopes,
+  verify }`, with `signIn: "required" | "optional" | "none"` per tool. A call that needs sign-in gets
+  HTTP 401 and the host's sign-in prompt; the person is `context.key` in the tool.
+- Backend access stays in tool code: supply the same `credentials` provider to `createAgent` and
+  `mcpServer`, then use `context.credentials.get("backend")` for that verified account. `resolve`
+  receives a normalized `phone` only on verified phone channels; phone-first brands need no extra
+  login or permissions screen there. See `coding-agents/auth-skill.md`.
+- Another MCP server's tools become your agent's with `mcpTools({ name, url })`, pinned to
+  `mcp.lock.json` (`npx flow mcp update`), so a change on that server never reaches your
+  customers before your tests do.
+- `@flow-engineer/flow/cli` makes your organization's command line from the same server, on Stricli (the
+  framework Sentry's CLI uses): every tool is a command, a `defineCli` file adds command groups
+  (`acme order -h` lists `place`, `status`), arguments and columns, and every command takes `--json`,
+  `--fields`, `--dry-run` and `--yes`. `npx flow cli --server <url> -h` works for any MCP server.
+- `npx flow check` checks it all by rule before you ship: tools that cannot be described
+  exactly, a CLI file that no longer matches the tools, skills that name chat-only tools.
+- Every generated piece can be replaced: the instructions, any tool's descriptor, your own MCP
+  handlers (`extend`), your own commands.
+
+The coding-agent skills in [`coding-agents/`](https://github.com/flow-engineer/flow/tree/main/coding-agents)
+cover it end to end: `context-skill.md` builds the context the tools are written from (OpenAPI,
+workflows, business rules, access) out of your existing codebase, and `auth-skill.md` sets up
+sign-in for your stack (an OAuth provider, Firebase, Supabase, your own login page).
+
 ## Models
 
-Any OpenAI-compatible API. With no `apiKey` or `baseURL`, `openAICompatible` uses the first key that has a value: `OPENROUTER_API_KEY` (OpenRouter), `OPENAI_API_KEY` (OpenAI), `ANTHROPIC_API_KEY` (Anthropic), then `GEMINI_API_KEY` (Gemini); with none it stops at once and names them. `MODEL` sets the model id; each key has its own default. Pass `baseURL` and `apiKey` for any other address; a local server that needs no key needs only `baseURL`. Give `contextTokens` (the model's window) and a long chat's history is kept within it: the latest messages go to every call, older ones are left out (the agent is told).
+Any OpenAI-compatible API. With no `apiKey` or `baseURL`, `openAICompatible` uses the first key that has a value: `OPENROUTER_API_KEY` (OpenRouter), `OPENAI_API_KEY` (OpenAI), `ANTHROPIC_API_KEY` (Anthropic), `GEMINI_API_KEY` (Gemini), then `FLOW_KEY` (Flow); with none it stops at once and names them.
+
+A provider key is optional: `npx @flow-engineer/flow setup` writes `FLOW_KEY`, the agent's one Flow key (shown only as its prefix and last 4 characters), which calls models through Flow on $2 of Flow trial credit per account (`npx @flow-engineer/flow status` shows what is left). A provider key in `.env` wins over it for the model; `setup --rotate key` replaces a leaked `FLOW_KEY` (the old one works 24 h more, `--now` ends it at once). `flowModel({ model })` uses Flow explicitly (default `anthropic/claude-haiku-5.5`; Flow offers a short list of models, `GET /models`); `FLOW_MODEL_URL` points it at another Flow server. When the credit is used up, a call fails with code `trial_credit_used` and the next step. `MODEL` sets the model id; each key has its own default. Pass `baseURL` and `apiKey` for any other address; a local server that needs no key needs only `baseURL`. Give `contextTokens` (the model's window) and a long chat's history is kept within it: the latest messages go to every call, older ones are left out (the agent is told).
 
 For agents with tools we recommend **Claude Haiku 5.5** (`anthropic/claude-haiku-5.5`) or **GPT-6.1 Sol** (`openai/gpt-6.1-sol`, about 3x the cost). In our tests, GPT Luna repeated tool calls and answered twice.
 
@@ -563,6 +616,8 @@ For agents with tools we recommend **Claude Haiku 5.5** (`anthropic/claude-haiku
 | `simulators/` | The playground (`@flow-engineer/flow/simulators`): SMS, WhatsApp, iMessage, Telegram and web, with each platform's rules |
 | `flow-messaging/` | Channels on Flow Messaging (`@flow-engineer/flow/flow-messaging`): WhatsApp, Telegram and SMS through one API |
 | `testing/` | Test file formats and the `flow` command (`@flow-engineer/flow/testing`) |
+| `mcp/` | Tools and skills as an MCP server, and other MCP servers' tools (`@flow-engineer/flow/mcp`) |
+| `cli/` | An organization's command line over its MCP server (`@flow-engineer/flow/cli`) |
 | `examples/cafe/` | Pip, an ordering assistant, with tests |
 | `coding-agents/` | Skills for coding agents |
 
@@ -609,3 +664,105 @@ The test cloud, its address and its API are unchanged, and traces keep their `ch
 ## License
 
 [Apache-2.0](https://github.com/flow-engineer/flow/blob/main/LICENSE)
+
+### Native plugins and standalone MCP
+
+The standalone `/mcp` endpoint includes the skills list and `read_skill`. Native plugins
+copy the agent's `agent/skills/` folder and connect to `/mcp/plugin`, which serves tools only,
+so a host receives each skill once. Both paths share tools, auth and descriptor overrides.
+`mcpServer({ ..., plugin: false })` disables the plugin path; `plugin: { path: "/native" }`
+moves it. `handle.plugin` exposes its path and descriptors. Your `instructions` override
+applies to both endpoints, and `extend` can add SDK handlers on both.
+
+From the agent folder, run:
+
+```sh
+flow plugin --server https://agent.example.com/mcp --out plugins
+flow check --plugin plugins
+```
+
+`plugins/claude/` uses Claude Code's `.claude-plugin/plugin.json` and `.mcp.json` with
+`type: "http"`. `plugins/agent-plugins/` uses Agent Plugins 1.0.0 root `plugin.json` and
+`mcp.json` with `type: "streamable-http"`; Codex supports this portable format.
+Pass `--name` to override the package name. For a custom plugin route, pass its URL ending
+in `/plugin`, or edit the generated MCP config. No token is written into either package.
+Regenerate after changing a skill or its assets; `check --plugin` compares content hashes.
+Generated files remain plain files in your repository: customize manifests and add components
+alongside them. Regeneration rewrites manifests and source skill copies; keep hand-written
+skills outside those source paths.
+
+Formats checked 18 October 2026: [Agent Plugins 1.0.0](https://agent-plugins.org/specification),
+[OpenAI plugin packaging](https://developers.openai.com/plugins/build/plugins), and
+[Claude Code plugin reference](https://code.claude.com/docs/en/plugins-reference).
+
+MCP calls emit `tool.start`/`tool.end` with surface (`mcp`, `mcp-plugin`, `cli`), client name
+and version, session, person, duration, outcome and error. CLI calls send command and an
+idempotency key in `_meta`; a caller can reuse its key on a retry. `defineCli`'s `version`
+sets its client version (default `"1"`). Neither CLI arguments nor trace credentials go in `_meta`.
+`mcpServer` uses `FLOW_FRAMEWORK_TRACES_*`, like chat agents, or explicit `traces` options;
+`traces: false` disables export without disabling your event sinks. `await handle.flushTraces()`
+flushes its bounded background queue. Each tool call is a root trace without a conversation;
+arguments and results require `FLOW_FRAMEWORK_TRACES_CONTENT=1`. Legacy clients' initialization
+metadata is retained for up to 24 hours in at most 4,096 sessions; bearer tokens are never cached.
+
+### Local playground CLI
+
+A local playground can run the team's actual CLI, including custom commands, OAuth, interactive
+chat, confirmations, stdout/stderr and exit codes. Opt in on the server that runs on your computer:
+
+```ts
+import { cli } from "./cli.ts"; // the team's defineCli configuration
+await play.listen(agent, 8790, { localCli: { channel: "terminal", config: cli } });
+// For a local agent mounting its playground under /playground:
+const handler = play.handler(agent, { token, base: "/playground", localCli: { channel: "terminal", config: cli } });
+```
+
+The named channel must be declared on the agent. Its tab opens the runner instead of simulated
+chat. Each browser gets an independent temporary sign-in and conversation directory; the test
+person picker does not grant it an account. Run `auth login`, open the sign-in link, then return
+to the runner. `chat` keeps reading input until `/exit`; reload reconnects to that session.
+**Clear output** clears the viewport; **New CLI session** ends the session and removes its local
+credentials, without clearing the account's agent history. Sessions expire after 30 minutes
+without browser activity, and a server restart starts fresh. Ending a session does not undo
+work already accepted by the agent.
+
+This runner accepts only direct loopback connections with a loopback Host and same-origin API
+requests, even if explicitly configured on a mounted handler. It is absent by default and is
+not enabled in the hosted test cloud. It invokes `runCli` in-process: no shell, arbitrary program
+execution, expansion or pipelines. Quoted arguments work. Its configured endpoints stay fixed;
+use the installed CLI for `--server`, `--token` or `skill --write`.
+
+- [ ] **TODO: Hosted CLI runner — deferred until a security review is complete.** Review execution
+  isolation, custom-command filesystem/network access, credentials, OAuth callbacks, session cleanup
+  and abuse controls before implementing or deploying cloud support. Keep the current runner local-only.
+
+Embedded clients can set `CliConfig.directory` to isolate credential/conversation files and
+`CliIO.env` to avoid inheriting process tokens; `CliIO.signal` cancels sign-in and terminal HTTP
+requests. Defaults retain the installed CLI's existing environment and config directory.
+
+### Terminal conversations
+
+`chat` talks directly to the agent, using the same bearer as MCP; it is not an MCP tool. `defineCli({ name: "acme", server, agent: "https://agent.example.com/agent/terminal" })`
+overrides the terminal URL; the default is the MCP server's origin plus `/agent/terminal`.
+`acme chat "Which orders are ready?" --json` prints one response; `acme chat` reads a TTY until
+Ctrl-D or `/exit`. Without a TTY pass a message to `chat` (an interactive chat exits 2); sign-in failures exit 3.
+`chat.json` is mode 600 and scoped by terminal endpoint. `--new` forgets the terminal's saved
+reference; the agent keeps its one-person history across channels. It does not erase a person's
+WhatsApp history. Teams can replace `chat` with their own Stricli command in `commands`.
+
+Mount the optional terminal handler beside MCP (no model or extra dependency in the CLI):
+
+```ts
+import { terminalServer } from "@flow-engineer/flow/mcp";
+const terminal = terminalServer({ agent: () => agent, auth });
+const agent = createAgent({ ...options, channels: [...channels, terminal.channel] });
+// Route terminal.path to terminal.fetch(request), and MCP's paths to mcp.fetch(request).
+```
+
+`terminalServer` accepts `path` and `channel` overrides. It verifies auth on every POST,
+serializes concurrent requests per person, and returns `{ conversationId, replies }` after the
+turn settles. The authenticated key becomes the same person that `resolve` returns on other
+channels. A body cannot choose its own person; a conversation reference from another person is
+refused. Its custom UI uses Markdown and exports turns as channel `cli`.
+For your own HTTP adapters, `agent.request({ channel, key, text, conversationId? })` exposes this
+without the handler. Supply a verified key and serialize calls for that channel and person.

package/coding-agents/auth-skill.md

@@ -0,0 +1,137 @@
+---
+name: flow-framework-auth
+description: Set up verified-phone sign-in, a brand’s OAuth server or its existing login, with one account across chat, MCP and the CLI and backend credentials kept in tool code.
+---
+
+# Sign-in for a Flow Framework agent’s tools
+
+Read `flow-framework-context` first: `context/access.yaml` describes the brand’s accounts and how its users sign in. Keep that account system. Every interface resolves to the same stable brand user id; a phone number, provider login and CLI connection are ways to reach it, not separate accounts.
+
+## Token authority and custody: the app mints, everyone else carries
+
+The brand (or its identity provider) issues the credential its API trusts, controls its lifetime and refresh, and can revoke it. The end client, such as the CLI or an MCP host, receives and maintains its own connection credentials and sends them with requests. Flow is the protocol handoff, not a separate authority that turns a user id into access to the brand's API.
+
+For a brand with ordinary login, its backend functions validate the existing session and mint or exchange the brand-authorized credential for the intended client and resource. Flow can coordinate OAuth registration, redirects, PKCE and one-time code exchange, retaining the short-lived protocol state needed for that exchange. It must not become a durable vault for the end client's brand access/refresh credentials or replace them with an independent Flow-owned permission to act as that user. Refresh and revocation stay under the brand's authority.
+
+A messaging agent can itself be a server-side client: its channel connection credentials belong behind the brand's integration boundary, not in WhatsApp/iMessage messages or model context. Distinguish that client from the OAuth handoff service. Verified-phone sign-in can authorize an operation directly when that is the brand's account policy; it does not require an extra OAuth token or login screen.
+
+## Choose the entry point
+
+1. **Phone is the brand’s primary identity.** A sender on a provider-verified phone channel (WhatsApp, phone-based iMessage, SMS) is signed in. Resolve that phone to the brand’s account, creating it only when the brand supports that. Give their normal full account access. Do not add an OTP, browser login, consent screen or permission picker on top of the verified channel.
+2. **The brand already exposes an OAuth authorization server.** Use it for MCP and CLI connections. On chat channels that need account sign-in, send a connection link to its existing login. A Google sign-in button in an app is not by itself an OAuth authorization server for MCP clients.
+3. **The brand has an ordinary login.** Use that login as the authentication step behind Flow’s OAuth layer (or a self-hosted OAuth server). Phone OTP, email, social login, company SSO and custom login can all finish the same connection. The brand confirms the signed-in account server-side and owns credential issuance and refresh; the OAuth layer coordinates client registration, one-time codes, PKCE and the brand-authorized token exchange. Do not add a Flow grant-selection screen by default. An existing provider can have its own required screens.
+
+A phone-first brand uses case 1 on WhatsApp and case 3 for its CLI: `auth login` opens the brand’s phone login in a browser, phone verification signs in, and OAuth returns to the CLI. The user never has to create an email account just to use another interface.
+
+## Verified phone → account
+
+`resolve` receives `phone` only when the channel verifies phone identities. It is normalized; `address` remains the provider’s original address. A custom web address that looks like a phone does not get this evidence. Only mark a channel `phone: true` when its provider verifies the sender and your webhook authenticates that provider.
+
+```ts
+const resolve = async ({ phone }) => phone ? accounts.forVerifiedPhone(phone) : null;
+const agent = createAgent({ ...options, resolve });
+```
+
+Return the brand’s account id. MCP’s `auth.verify` returns that same id as `key`, so the terminal, web and phone channels share the person’s history. Without a brand resolver, phone channels still share one `phone:<E.164>` identity; `context.key` is null. Connect other login methods to an existing account only with verified account-linking proof, never a number or email supplied in model input.
+
+## Tool code gets backend access
+
+Supply the same `credentials` provider to `createAgent` and `mcpServer`. It runs lazily when tool code requests a named credential or backend client, with the framework’s verified identity. The brand decides how to obtain, refresh, authorize and revoke that access. This callback can support an API token, an authenticated client, a grant reference or the brand’s own authentication mechanism.
+
+```ts
+const credentials = async (name, context) => {
+  if (name !== "backend" || !context.key) throw new Error("Sign in required");
+  return backend.forAccount(context.key); // checks current account/session access
+};
+
+const tools = [tool({
+  name: "my_orders", description: "Your orders.", input: z.object({}),
+  run: async (_input, ctx) => {
+    const api = await ctx.credentials.get("backend");
+    return api.orders();
+  },
+})];
+
+const agent = createAgent({ ...options, tools, resolve, credentials });
+const mcp = mcpServer({ ...serverOptions, tools, auth, credentials });
+```
+
+In TypeScript use `ctx.credentials!.get<YourBackendClient>("backend")`. Never take an account id from tool input as authorization. The credential accessor is non-enumerable and the framework sends neither its provider nor resolved credentials to the model, history or events. Tool authors must also keep credentials out of their results, errors and logs. Do not cache a user’s access in a process-global variable. A request-local token workaround is not necessary when backend access is resolved by verified account.
+
+When backend access depends on the caller's actual credential, `auth.verify` may return `{ key, credentials }`. That request's credential provider overrides the default for MCP and the authenticated terminal; close over the verified token there. A verified account id alone is not permission to mint or fetch a backend token. The provider is server-side and non-enumerable; it never enters model inputs or traces.
+
+The default is full normal user access, not global administrator access. Existing business ownership checks still apply. Optional scoped connections remain available for brands that require them; do not invent a permissions UI or restrict the brand’s normal experience by default.
+
+## Authentication at a chat tool boundary
+
+Configure `createAgent({ auth: { verify?, signIn } })`. Public conversation remains available while signed out. Tools use the same `signIn` metadata as MCP: `"none"` is public, `"optional"` runs with a null key when unsigned, and `"required"` (default) cannot execute until authenticated. Agents without `auth` retain their existing behavior.
+
+`verify(context)` can recheck revocation or the current channel connection. Without it, a non-null key from trusted `resolve` is enough, including a provider-verified phone mapped to a brand account. `signIn(context)` returns `{ message, url? }`: the framework delivers this as a real channel message with the login link, records it in the transcript, and does not run the protected tool. Parallel protected calls produce one challenge per channel per turn. A custom in-chat challenge may omit the URL. Login functions receive server-issued channel/address and tool identity, never model-supplied account ids. Errors fail closed and credentials stay outside model context.
+
+After login, resolve that channel to the canonical account key; the user can resume the request. Do not automatically replay an irreversible operation merely because login succeeded.
+
+## OAuth on MCP and the CLI
+
+The MCP server is a resource server, not the user’s login page. Its auth adapter verifies a token on every request and returns the brand’s user id:
+
+```ts
+const auth = {
+  issuer: "https://login.example.com",
+  resource: "https://agent.example.com/mcp",
+  async verify(token, request) {
+    const session = await accounts.verifyAgentAccess(token, request);
+    return session ? { key: session.accountId } : null;
+  },
+};
+```
+
+Verify signature (or introspect opaque tokens), issuer, expiry, intended resource and current revocation/account status. The token must be issued for this MCP resource. Native plugin endpoints advertise their own resource too: configure the authorization server and verifier for each enabled resource. Never accept an unrelated website session token and forward it unchanged to a downstream API. Backend access is separate and resolved through `credentials`, or tools run within the brand’s backend under its existing authorization.
+
+- Missing sign-in on a required tool returns HTTP 401 with `WWW-Authenticate`; MCP hosts discover the authorization server from protected-resource metadata. Do not return “please sign in” as a tool result and expect a host to start OAuth.
+- `signIn: "none"` tools are public, `"optional"` can run either way, and the default is `"required"`. With no scope mapping, being signed in is enough. Brands that need scopes may configure `auth.scopes` and return granted `scopes` from `verify`.
+- The CLI already implements browser-based authorization-code sign-in with PKCE and a loopback redirect. It stores credentials per server and the SDK refreshes them. CI can supply `<NAME>_TOKEN`. Device authorization is a separate optional flow, not an existing CLI feature.
+- The authorization server handles registered clients and redirect validation. A third-party client’s existing authorization requirements remain its own. Flow’s first-party experiences do not need an extra permissions picker.
+
+## Hosting choices
+
+| Deployment | Authorization server | Brand work |
+| --- | --- | --- |
+| Flow-hosted, existing OAuth/OIDC server | Existing provider (for example Cognito) | Register clients/redirects, authorize the agent resource, and configure token verification/backend access. Flow does not add a broker. |
+| Flow-hosted, ordinary/custom login | Flow's protocol bridge | Keep normal login. Add brand-owned one-time login completion, credential issuance, refresh, verification and revocation functions. The bridge relays brand-issued client credentials. |
+| Self-hosted | Existing provider or the team's own OAuth server | Publish OAuth discovery and resource metadata, configure PKCE and client/redirect validation, implement the same brand authority boundary. No Flow service is required. |
+
+An existing OAuth server must authorize the actual agent resource and supported clients; a website's social sign-in token alone is insufficient. Discover its authorization and token endpoints rather than assuming `/auth` and `/token`. Providers without dynamic registration need registered client configuration. The CLI accepts a configured OAuth client ID, and custom surfaces remain replaceable.
+
+## Connecting an ordinary brand login
+
+Keep the OAuth protocol layer reusable and the account authority in the brand. The brand integration must:
+
+1. **Finish its existing login.** A small server-side function verifies its normal session and returns a short-lived assertion or opaque one-time code identifying the account and the pending Flow connection. Bind it to the client, intended resource, callback and nonce; exchange it for a single-use brand authorization required by credential issuance; never accept a user id merely posted by the browser.
+2. **Provide account access.** Its backend validates a credential issued for that API, or supplies an authenticated execution path. Use separate resource credentials for MCP and downstream APIs; a UID alone never authorizes an API call.
+3. **End access.** Account disable/deletion and connection revocation stop new requests and refresh. Signing out of one client need not disconnect the others.
+
+For Firebase the app’s function validates the signed-in user’s Firebase session, or the authenticated provider’s phone proof, and resolves its Firebase UID. Where its API uses Firebase credentials, the intended client can exchange a brand-minted custom token for its own agent session and maintain that session; Flow’s handoff service does not retain its refresh credential. Keep the Admin SDK and its service-account keys in the brand’s backend. The old local test-account bootstrap is test setup, not a production sign-in flow.
+
+A custom login implements the same boundary. Do not make every brand adopt one identity provider or copy an OAuth server into its agent repository.
+
+After a verified OAuth callback has saved the chat client's connection, call
+`await agent.signInCompleted({ channel, address, key, idempotencyKey: "login:" + connectionId })`.
+This links the verified identity and queues an internal prompt to the agent, not a fixed user-facing
+reply. The agent continues a request blocked by sign-in, or acknowledges naturally if nothing is
+waiting. It does not automatically replay executed tools or unrelated failures. An anonymous
+request blocked at the auth boundary is carried forward as user text; anonymous history stays
+separate. Pass the originating `conversationId` when the login challenge was created inside a
+conversation; it must belong to that channel address. The prompt targets that address even if
+another session on the same channel wrote later. Signing in preserves no-contact rules, including
+STOP. Use a stable unique completion ID so retries and restarts do not queue another event.
+For playground connections pass `via: "playground"`; replies stay in the simulator. Persist pending
+completion events and retry queueing after restart instead of relying on the browser staying open.
+`linkIdentity` and `recordNudge` remain available for custom completion behavior.
+
+## Exercise sign-in in the playground
+
+Pass `authentication` to `simulators` to add **New user · signed out** to the person picker. Existing declared test people retain their current identities. The hook receives the `channel` and an opaque `visitor` issued by the playground server, and returns `{ key?, address?, label?, signInUrl? }`. Resolve that visitor's connection with the application's normal auth adapter and return the canonical account `key` only after authentication. A phone-primary brand can resolve a simulated provider-verified phone immediately; other interfaces can return the application's OAuth connection URL. Never take the key or verified phone proof from request bodies, and keep credentials out of the result.
+
+For a new user the playground checks this hook before history, messages, events and person-specific actions. While signed out, the visitor can chat and see only their own anonymous conversation; requesting a protected tool produces the normal login message. Signing in gives access to the verified account conversation. It calls `agent.simulateVisitor` with the server-verified identity, so the account's existing conversation is shared with other interfaces and replies stay in the simulator. A new user needs no declared phone or preassigned account. Each interface needs its own proof; signing in on web does not silently authorize another CLI session.
+
+After login return to the mounted playground with `person=visitor`; its message draft stays available. **Clear history** resets the selected visitor or authenticated account's conversation and agent memory across channels, after confirmation, while keeping its sign-in connection. **New signed-out user** replaces the browser's connection identity without clearing account history or revoking other clients. An existing authorization-server session may still allow login without re-entering a password. The operator token remains required on a deployed playground, and declared people still use the developer identity shortcut. This is a developer simulator, not a customer-facing chat endpoint.

package/coding-agents/context-skill.md

@@ -0,0 +1,94 @@
+---
+name: flow-framework-context
+description: Build the context pack (OpenAPI spec, overlay, workflows, business, data model, access rules, examples) from an organization's existing codebase, before writing a Flow Framework agent's tools. Load when starting an agent for a company that already has an app, API or database, when asked for an OpenAPI spec or "the spec", or when the tools need facts nobody has written down.
+---
+
+# The context pack
+
+Tools are only as good as what you know when you write them. Before writing a Flow Framework agent's
+tools (the `flow-framework-tools` skill), gather everything about the organization's systems into one
+folder in the agent's repository, `context/`. It is the input for every later step: the tools,
+the agent's skills, the sign-in (the `flow-framework-auth` skill), the tests and the CLI.
+
+Work from the organization's own code and documents. Never invent: anything you cannot find goes
+in `context/README.md` under "Questions for the team", phrased so someone can answer it in a line.
+
+## What goes in it
+
+| File | Format | What it holds |
+|---|---|---|
+| `context/README.md` | Markdown | The index: where each file came from (repo, path, commit, who confirmed it), environments, and the questions for the team |
+| `context/openapi.yaml` | OpenAPI 3.1, **exactly as the team gives it** | Their API: operations, request and response schemas, errors, security schemes |
+| `context/overlay.yaml` | [OpenAPI Overlay 1.0](https://spec.openapis.org/overlay/v1.0.0) | Everything you add to their spec, as changes applied to it: clearer descriptions, units ("amount is in paise"), which fields matter, gotchas, operations to avoid |
+| `context/workflows.arazzo.yaml` | [Arazzo 1.0](https://spec.openapis.org/arazzo/v1.0) | How calls connect: the steps of each real task, how one step's output feeds the next, what counts as success, what to do when a step fails |
+| `context/business.md` | Markdown | What the company does, who its customers are, the words they use, the policies a person would be told ("refunds within 30 days", "never promise delivery times") |
+| `context/data.md` | Markdown | The entities and their ids, how they relate ("an order belongs to one store"), and which fields are personal data |
+| `context/access.yaml` | YAML | Who may do what: for each task, whether it works signed out, needs the person signed in, needs a write, or needs the person's approval each time; customer or staff only |
+| `context/examples/*.md` | Markdown | Real situations and what should happen, including the awkward ones (a refund after the window, an order that fails to pay) |
+
+Never put keys, tokens, passwords or real customers' data in any of these files.
+
+**Why their spec stays untouched:** the team will send new versions. Your knowledge lives in the
+overlay, which is applied to each new version the same way, so nothing is lost and you can see
+exactly which overlay entries, workflows and tools point at operations that changed.
+
+## Find the API, by stack
+
+Look at the repository's routes, its framework and its dependencies first, then pick the case:
+
+- **A REST API with an OpenAPI spec.** Ask for the latest version, or find it in the repo
+  (`openapi.*`, `swagger.*`, a generator such as FastAPI, NestJS's Swagger module, springdoc,
+  drf-spectacular, rswag). Use theirs as is.
+- **A REST API without a spec.** Draft one from the routes and handlers, with an `operationId` and a
+  plain description on every operation, request and response schemas from the code's own types,
+  and the error responses the handlers send. Put `x-chinwag-draft: true` at its top and list it in
+  the questions: the team confirms it, and from then on it is theirs.
+- **GraphQL.** Keep the schema (`context/schema.graphql`) instead of OpenAPI, and describe the
+  queries and mutations the tasks use in the workflows file as plain steps.
+- **Supabase.** PostgREST generates an OpenAPI spec from the database. It is no longer served with
+  the public anon key: the team exports it with a secret key or the Management API
+  (`GET /v1/projects/{ref}/database/openapi`), once, and gives you the file. Read the row-level
+  security policies (`supabase/migrations`, `pg_policies`) into `access.yaml`: they are the real
+  permission model.
+- **Firebase (Firestore, Realtime Database, Storage).** There is no API: the database and its
+  security rules are the API. There is no OpenAPI; instead:
+  - `firestore.rules` (and `database.rules.json`, `storage.rules`) into `access.yaml`: who may read
+    and write what, condition by condition;
+  - `firestore.indexes.json`: which queries are possible;
+  - the app's models and the code that reads and writes each collection into `data.md`: the
+    collections, their fields and types, and the ids that link them;
+  - Callable or HTTP Cloud Functions are its only real endpoints: list them in `data.md` with their
+    input and output.
+- **Several of these at once** (a REST API plus Firebase for chat, say): one section per system in
+  `data.md`, and say in the workflows which system each step uses.
+
+## Fill the rest
+
+- **Workflows:** one per task the agent or a host should be able to do in one call ("place an
+  order" = check stock, create the order, take payment; if payment fails, cancel the order). These
+  become the tools: a tool is a task, not an endpoint.
+- **Business and data:** from the app's own copy (its website, help pages, emails, the UI's
+  strings), its terms and policies, and its models. Mark every personal field (names, phone
+  numbers, addresses, payment details) in `data.md`: tools return them only when a task needs them.
+- **Access:** from the rules and middleware. For each task in the workflows, write one of
+  `signed_out`, `signed_in`, `signed_in_write` or `approval` (the person confirms each time), and
+  `staff` when only the team's staff may do it. This is what the tools' `signIn` and `hints` say.
+- **Examples:** from support tickets, chat logs or the team's own words, with personal data
+  removed. They become test scenarios (the `flow-framework-tests` skill).
+- **Environments:** a sandbox or test server and how to get test accounts, the rate limits, how
+  the API pages results, and whether writes take an idempotency key. In `README.md`.
+
+## Questions for the team
+
+Ask for what the code cannot tell you. The usual ones:
+
+1. The latest OpenAPI spec (3.1), with an `operationId` and a description on every operation.
+2. Request and response examples, including the errors.
+3. The security schemes and the scopes each operation needs, and how their users sign in today.
+4. How results are paged, the rate limits, and whether writes accept an idempotency key.
+5. A sandbox or test server, and test accounts.
+6. The webhooks or events they send (orders shipped, payments failed).
+7. Which tasks customers may do themselves, which need their approval each time, and which are
+   staff only.
+
+Then go on to the `flow-framework-auth` skill (sign-in) and the `flow-framework-tools` skill (the tools).