@flow-engineer/flow 0.2.0 → 0.2.2

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).

package/coding-agents/skill.md

@@ -1,6 +1,6 @@
 ---
 name: flow-framework
-description: Build or change a chat agent on Flow Framework (WhatsApp, SMS, iMessage, Telegram, web). Load when creating a Flow Framework agent, editing its prompt or skills, wiring it into the playground, or when code imports @flow-engineer/flow (formerly chinwag). Also load the flow-framework-tools skill (tools-skill.md) before writing tools and flow-framework-tests (test-skill.md) before writing tests.
+description: Build or change a chat agent on Flow Framework (WhatsApp, SMS, iMessage, Telegram, web), and serve its tools as an MCP server for Claude and ChatGPT or as a CLI. Load when creating a Flow Framework agent, editing its prompt or skills, wiring it into the playground, adding MCP or a CLI, or when code imports @flow-engineer/flow. Also load the flow-framework-tools skill (tools-skill.md) before writing tools and flow-framework-tests (test-skill.md) before writing tests.
 ---
 
 # Building an agent on Flow Framework
@@ -10,17 +10,20 @@ reply, acknowledges people fast, runs tools in parallel and waits for them, movi
 background only when the person writes again or it passes its limit.
 You write the agent's prompt, skills and tools; Flow Framework handles the conversation.
 
-Two more skills go with this one: `flow-framework-tools` (`tools-skill.md`) before writing or changing a
-tool, and `flow-framework-tests` (`test-skill.md`) before writing or changing a test.
+More skills go with this one: `flow-framework-tools` (`tools-skill.md`) before writing or changing a
+tool, `flow-framework-tests` (`test-skill.md`) before writing or changing a test, `flow-framework-context`
+(`context-skill.md`) before writing tools for a company that already has an app, API or database,
+and `flow-framework-auth` (`auth-skill.md`) when tools need to know who the person is.
 
 ## Start a new agent
 
 `npx @flow-engineer/flow new <name>` (lowercase letters, digits and dashes) makes `./<name>/` from the café
 example: a complete agent with tools and tests that depends on the `@flow-engineer/flow` package and imports
 `@flow-engineer/flow` and `@flow-engineer/flow/simulators`, with these skills in `.claude/skills/`. Run `npm install` there.
-Build in it, changing Pip's prompt, skills, tools and tests into yours. The owner copies
-`.env.example` to `.env` and puts one model key in it (never read or print it). Flow Framework does not
-issue that key; it is made at the provider: `OPENROUTER_API_KEY` at https://openrouter.ai/keys,
+Build in it, changing Pip's prompt, skills, tools and tests into yours. A provider key is optional:
+`npx @flow-engineer/flow link` (or `setup`) writes `FLOW_KEY`, the agent's one Flow key, into `.env` (never
+read or print it), and the agent calls models through Flow with it on $2 of Flow trial credit. A key of the owner's own wins over it, made
+at the provider: `OPENROUTER_API_KEY` at https://openrouter.ai/keys,
 `OPENAI_API_KEY` at https://platform.openai.com/api-keys, `ANTHROPIC_API_KEY` at
 https://console.anthropic.com/settings/keys, or `GEMINI_API_KEY` at https://aistudio.google.com/apikey.
 The first one with a value is used, and `CAFE_MODEL` sets the café's model id. Then `npm start`
@@ -41,6 +44,10 @@ my-agent/
   src/tools.ts                 the agent's tools (see tools-skill.md)
   src/agent.ts                 buildAgent(): the one place the agent is built
   src/main.ts                  runs it in the playground
+  src/mcp.ts                   optional: the tools as an MCP server (below)
+  src/cli.ts                   optional: the CLI file, for the organization's command line (below)
+  context/                     optional: the context pack the tools are written from (context-skill.md)
+  mcp.lock.json                optional: the tools of other MCP servers the agent uses (tools-skill.md)
   tests/tools/*.yaml           how each tool behaves in tests (see tools-skill.md)
   tests/scenarios/*.yaml       the tests (see test-skill.md)
 ```
@@ -89,8 +96,10 @@ is how long a finished tool's result waits for the others of its response; `shar
 guidance with a string.
 
 Models are reached through any OpenAI-compatible API. `openAICompatible()` with no key reads the
-first of `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY` and `GEMINI_API_KEY` that has a
-value, and uses that provider's default model (`MODEL` overrides it). With none it stops at once and
+first of `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY` and
+`FLOW_KEY` (the agent's Flow key, on its trial credit, from `setup`) that has a value, and uses that provider's
+default model (`MODEL` overrides it). `flowModel()` uses Flow alone; when its credit is used up a
+call fails with code `trial_credit_used` and a next step (tell the owner to add their own key). With none it stops at once and
 names them. Pass `apiKey` and `baseURL` for anywhere else (`baseURL` alone for a local server that needs no key).
 
 Which model: recommend Claude Haiku 5.5 (`anthropic/claude-haiku-5.5`, the default above) or OpenAI
@@ -294,9 +303,50 @@ To demo what your backend does (an order ships), send the nudge it would send fr
 On a deployed agent, mount it in your own server with a token of at least 32 characters, from a
 secret: `const playground = play.handler(agent, { token: process.env.PLAYGROUND_TOKEN!, base: "/playground" })`,
 and hand it the requests under `/playground` (`if (url.pathname.startsWith("/playground")) return playground(req, res)`).
-Open `/playground/?token=...` once (it becomes an HttpOnly cookie and leaves the URL) or call the API
-with `Authorization: Bearer <token>`. Wrong tokens are limited per address, and every simulated
-message is logged with the person, channel, time and address.
+Open `/playground/?token=...` once (it becomes an HttpOnly, SameSite=Lax cookie and leaves the URL) or call the API
+with `Authorization: Bearer <token>`. The cookie survives a top-level return from sign-in on another site;
+the API still accepts only requests from the playground’s own origin. Wrong tokens are limited per address,
+and every simulated message is logged with the person, channel, time and address.
+
+## Put it on a phone
+
+To chat with the agent from the owner's phone, with no tunnel and no key made by hand, run these
+from the agent's folder (`npx @flow-engineer/flow init --display-name "<name>"` makes a starter in
+an empty one: first ask the owner what people should call their agent, such as "FlatX agent"; the
+phone's first message is `Hi FlatX agent (ref <code>)`, and `package.json`'s `displayName` keeps it).
+Only `chat` reads stdin; `init` asks for the name only in a terminal, and nothing else asks for input.
+
+```sh
+npx @flow-engineer/flow link --json          # signs in and runs setup when needed (Flow's trial model key too), then the channel's own link (t.me, wa.me, sms:); give its say_to_person to the owner
+npm start                                    # the agent: its playground link, and the owner texts it while it runs
+npx @flow-engineer/flow status --json        # what the folder has and lacks, at any time
+printf 'hi\nA latte please\n' | npx @flow-engineer/flow chat   # your own check: one message per line, replies printed
+npx @flow-engineer/flow test --synthetic     # your own check: the tests, on the key setup wrote
+```
+
+When the owner asks how to test it, recommend first the playground (`npm start`, then open the
+link it prints: the test people and the channels side by side, with Debug), then their phone (the
+`link`, while `npm start` runs). `chat` and `test --synthetic` are for you to check your own work;
+do not offer them to the owner as ways to test.
+
+`link` runs `login` first when not signed in: it opens the owner's browser itself and prints the
+link and code at once (with `--json` the first line is `{"status":"pending","verification_uri":...,
+"user_code":...,"next":...}`), waits at most 120 s (`--timeout <s>`), then exits 4 with the code
+kept: give the owner the link and code, and run `link` again (it polls the same code). Then it runs
+`setup`, which writes the test cloud, traces and Flow Messaging keys into `.env`, prints names and
+last 4 characters only, keeps values already there (`--replace` takes the new ones), and is safe to
+run again. `--channel telegram|whatsapp|imessage` picks the channel; a channel flow.engineer cannot
+open yet exits 3 with its `next`. `login`, `setup` and `link` also run on their own.
+
+In `src/main.ts`, put `fm.telegram()` from `@flow-engineer/flow/flow-messaging` in the agent's
+channels and call `fm.start(agent, { cursorFile: ".flow/flow-messaging-cursor" })`: with no webhook
+secret it opens Flow Messaging's event stream, an outbound connection, so the laptop needs no public
+URL, and the cursor file lets messages sent while it was stopped arrive when it starts again. The
+starter does this when `.env` has `FLOW_MESSAGING_KEY`. Each error is
+`{"error":{"code","message","next"}}`: run its `next`. Exit codes: 0 done, 1 usage or not signed in,
+2 network, 3 refused, 4 sign-in waiting. Never ask the owner to paste a key into the chat. Always
+name the package (`npx @flow-engineer/flow ...`): `npx flow` on its own fetches another npm package.
+CI never logs in: `setup --ci` says how to give it the cloud key.
 
 ## Send traces to a dashboard
 
@@ -319,3 +369,187 @@ touches a chat; call `await agent.flushTraces()` before the process exits. Tests
 `node --test` never send from the environment. Under `flow test` the traces say they are a test's
 (`chinwag.run_kind` is "test", else "production", and each turn names the test session as
 `chinwag.test.session`), so the dashboard keeps them apart from real conversations.
+
+## Serve the tools over MCP
+
+The same tools and skills go to Claude, ChatGPT and any MCP host as an MCP server. Install the
+SDK it runs on (`npm i @modelcontextprotocol/server@2.3.1`, the version Flow Framework pins) and add
+`src/mcp.ts`:
+
+```ts
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import { mcpServer } from "@flow-engineer/flow/mcp";
+import { tools } from "./tools.ts";
+
+export const mcp = mcpServer({
+  name: "acme",
+  version: "1.0.0",
+  tools,
+  dir: fileURLToPath(new URL("../agent", import.meta.url)),   // its skills; AGENTS.md is not sent
+  // auth: { issuer, resource, scopes, verify }               // sign-in: the flow-framework-auth skill
+});
+createServer((req, res) => void mcp.node(req, res)).listen(8790);   // Streamable HTTP at /mcp
+```
+
+- `mcp.fetch(request)` serves a web-standard `Request` instead (Cloudflare Workers, Deno, Bun), so
+  it mounts beside the chat agent in one process or runs on its own: it needs no model, channels
+  or store.
+- Hosts get the skills as the server's instructions (each one's description) and read one with the
+  `read_skill` tool. A skill that tells the chat agent to use `send_*` or `share_updates` makes
+  no sense to a host: `flow check` warns about it.
+- Every part can be changed: `instructions` replaces the instructions, `descriptor(tool, generated)`
+  changes any tool's MCP descriptor, `extend(server)` adds handlers of your own (resources,
+  prompts) to the SDK's server, `path` moves the endpoint, `allowedHosts` checks the Host header.
+- Try it locally with `claude mcp add --transport http acme http://localhost:8790/mcp`.
+- Run `npx flow check` from the agent's folder before serving: it refuses tools that cannot be
+  described exactly (the `flow-framework-tools` skill lists the rules).
+
+## A CLI for the organization
+
+The same tools as commands, over the organization's MCP server, with the same sign-in and gating.
+It runs on Stricli (`@stricli/core`, the framework Sentry's CLI is built on). Every tool is already a
+command under its own name (`place_order` is `acme place-order`); a CLI file adds what needs
+judgement. Install `@modelcontextprotocol/client@2.3.1` and `@stricli/core@1.3.0` (the versions
+Flow Framework pins) and write `src/cli.ts`:
+
+```ts
+#!/usr/bin/env node
+import { fileURLToPath } from "node:url";
+import { defineCli, runCli } from "@flow-engineer/flow/cli";
+
+export const cli = defineCli({
+  name: "acme",
+  server: process.env.ACME_SERVER ?? "https://acme.example.com/mcp",
+  description: "Acme's orders and customers",
+  groups: { order: "Place and track orders" },
+  commands: {
+    "order list": { tool: "list_orders", columns: ["order_id", "status", "total"], alias: "orders" },
+    "order view": { tool: "get_order", args: ["order_id"], examples: ["acme order view BL-1042 --json"] },
+    "order place": { tool: "place_order" },
+  },
+});
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) process.exit(await runCli(cli, process.argv.slice(2)));
+```
+
+- Words are groups then a verb: `order` is a **command group**, `list`, `view` and `place` its
+  subcommands. `acme order` and `acme order -h` list the group's subcommands, `acme order place -h`
+  that command's flags and examples, and `acme -h` the groups and top-level commands. A word is a
+  group or a command, never both. `groups` gives each group its line in help.
+- `args` are the input fields taken as positional arguments, `columns` a list's table, `view` one
+  record's fields, `alias` another name, `examples` lines for help. Every other input field is a
+  flag (`order_id` is `--order-id`); a list is a repeatable or comma-separated flag; an object or a
+  list of objects takes JSON, or `@file.json`, and its help shows the shape
+  (`JSON list of {item, size, milk?}`).
+- A command of the team's own is any Stricli command: `"report daily": { command: buildCommand({ ... }) }`
+  with `buildCommand` from `@stricli/core`; inside it, `this.cli.call(tool, input)` calls the server's
+  tools and `this.cli.print(value, { json })` prints like the rest.
+- Installed, it is the organization's own command: `"bin": { "acme": "src/cli.ts" }` in its package
+  (node runs `.ts` files outside `node_modules`; publish a compiled `.js` bin to npm). While building
+  it, run it with `npm run cli -- order -h`: npm takes flags before `--` as its own.
+- Every tool command takes `--json` and `--fields a,b`; one that changes things takes `--dry-run`; one
+  that may delete or overwrite asks first in a terminal and needs `--yes` without one. Exit codes: 0
+  done, 1 the tool failed, 2 wrong command or arguments (with the help to read), 3 sign-in needed, 4
+  needs `--yes`, 5 the server could not be reached. `--server <url>` and `--token <token>` work on
+  every command. `acme auth login` signs in on the organization's own login (tokens in
+  `~/.config/acme/`, mode 600), `ACME_TOKEN` is for CI, `acme tools` lists every tool and schema, and
+  `acme skill --write ~/.claude/skills` installs the CLI's SKILL.md, made from the tools and the CLI
+  file, for coding agents. For any MCP server without a CLI file, `npx flow cli --server <url> -h`.
+- `npx flow check` checks the CLI file against the tools: a command naming a tool that does not
+  exist, an `args` field the input lacks, a `columns` or `view` field the output lacks, two commands
+  with one name, a word that is both a command and a group, or one of the CLI's own words (`auth`,
+  `tools`, `skill`) is an error; a tool no command names is a warning (it keeps its own name).
+
+
+### 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
+
+To exercise the real CLI on your computer, pass `localCli: { channel: "terminal", config: cli }`
+to `play.listen(agent, port, options)` or a locally mounted `play.handler(agent, options)`.
+`cli` is the team's existing `defineCli` configuration, with its server URL; the named channel
+must exist. This opens an independent CLI session in that tab, with real stdout/stderr, exit
+codes, interactive input and confirmation prompts. It does not use the selected test person's
+identity. Run `auth login`, open the login link and return, then use commands or `chat` (`/exit`
+leaves chat). Reload reconnects. New CLI session discards only this runner's temporary sign-in;
+server restart or 30 minutes without browser activity also ends it. Clear output keeps sign-in.
+An operation already accepted by the agent may still complete after its client session ends.
+
+Enable this only in local startup code. The runner is off by default, rejects non-loopback or
+forwarded connections, and is not part of the hosted test cloud. It calls the actual CLI runner
+only locally. Hosted CLI support is deferred pending security review; do not add it to cloud startup
+or deployment wiring. See the hosted CLI TODO in the README. The runner invokes the CLI
+without a shell: quoting works, pipelines/expansion do not. The browser cannot override server
+or token flags, or use `skill --write` to write onto the developer's computer.
+For other embedded clients, `CliConfig.directory` overrides credential/conversation storage;
+`CliIO.env` overrides the inherited process environment and `CliIO.signal` cancels sign-in and
+terminal HTTP requests. Installed CLI defaults stay unchanged.
+
+### 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.
+Human chat shows a `You ›` input prompt, a waiting indicator and agent replies under the CLI's
+name. `--json` keeps stdout as one JSON response per line, without those labels. Embedded CLIs
+can supply `CliIO.lines(prompt?)` and their own output handlers to replace the presentation.
+`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/test-skill.md

@@ -5,7 +5,9 @@ description: Write or change tests for a Flow Framework agent (tests/scenarios/*
 
 # Writing tests for a Flow Framework agent
 
-Read the `flow-framework` skill (`skill.md`) first if you haven't.
+Read the `flow-framework` skill (`skill.md`) first if you haven't. Turn the situations in
+`context/examples/` (the `flow-framework-context` skill) into scenarios, and run `npx flow check`
+before the tests when the agent serves MCP or a CLI.
 
 A test is a scenario: a situation to put the agent in, played through a platform simulator by a
 model acting as the person, with the agent's tools played by a model from `tests/tools/*.yaml`
@@ -120,7 +122,7 @@ connects out to the cloud, which plays the person and the tools and judges.
 1. Have a test cloud: the hosted one at https://flow.engineer/observe, the default (see "Get a test
    cloud" below), or another with `--cloud <url>` or `FLOW_FRAMEWORK_CLOUD`.
 2. From the agent's folder (it must export `buildAgent` and `tools` from `src/agent.ts`), which reads
-   the agent's `.env` itself: `npx flow test --synthetic [--runs 3]` (`npm test -- --synthetic`
+   the agent's `.env` itself: `npx @flow-engineer/flow test --synthetic [--runs 3]` (`npm test -- --synthetic`
    in an agent `flow new` made).
 3. It first reads every test file as the cloud does; a mistake stops it with
    `tests/scenarios/<file>.yaml:<line>: <field>: <what is wrong>`, one line each, and nothing is sent.
@@ -151,17 +153,17 @@ connects out to the cloud, which plays the person and the tools and judges.
 
 Work in this loop, and never finish on a partial run:
 
-1. `npx flow test --synthetic`: the whole suite.
+1. `npx @flow-engineer/flow test --synthetic`: the whole suite.
 2. Fix what failed (the agent, or a test that asks for the wrong thing; say which).
-3. `npx flow test --synthetic --failed`, again until every run in it passes (exit 0).
-4. `npx flow test --synthetic`: the whole suite once more, since a fix can break another scenario.
+3. `npx @flow-engineer/flow test --synthetic --failed`, again until every run in it passes (exit 0).
+4. `npx @flow-engineer/flow test --synthetic`: the whole suite once more, since a fix can break another scenario.
 
 ### When a run fails
 
-1. `npx flow test --synthetic --json > report.json`, and read the runs whose `verdict` is not
+1. `npx @flow-engineer/flow test --synthetic --json > report.json`, and read the runs whose `verdict` is not
    `passed` (`jq '.runs[] | select(.verdict != "passed")' report.json`).
-2. `npx flow show last` (the first run that did not pass; it names the others) or
-   `npx flow show <runId>`: the checks with the judge's reasons, then the conversation in time
+2. `npx @flow-engineer/flow show last` (the first run that did not pass; it names the others) or
+   `npx @flow-engineer/flow show <runId>`: the checks with the judge's reasons, then the conversation in time
    order with every tool call the simulator played, its input, output and what it changed.
    `--json` gives the whole record.
 3. Decide which is wrong, and say which:
@@ -169,7 +171,7 @@ Work in this loop, and never finish on a partial run:
    - the test: a check asks for the wrong thing, or the scenario cannot reach its goal; fix the YAML;
    - the simulator: a tool output that could not happen, or a person who left the scenario; fix
      `tests/tools/*.yaml` or the scenario's `world` and `person`.
-4. `npx flow test --synthetic --failed`, then `--runs 3 --only <scenario>` on what you fixed, so
+4. `npx @flow-engineer/flow test --synthetic --failed`, then `--runs 3 --only <scenario>` on what you fixed, so
    a pass is not luck.
 5. The whole suite once more.
 
@@ -181,7 +183,7 @@ The owner does these; never ask for the key in chat or print it:
 2. Workspace → New agent.
 3. On the agent's Developers page, "Make a CI key". It starts with `oci_` and is shown once.
 4. Put it in the agent's `.env` as `FLOW_FRAMEWORK_CLOUD_KEY` (never on the command line).
-5. `npx flow test --cloud https://flow.engineer/observe --synthetic` from the agent's folder (`--cloud` is that address by default).
+5. `npx @flow-engineer/flow test --cloud https://flow.engineer/observe --synthetic` from the agent's folder (`--cloud` is that address by default).
 
 Your agent runs on your machine with your own model key. The cloud's person simulator, tool simulator and judge are free up to $5 a day per workspace, with 2 sessions at once; test data only (`--synthetic`), and records are deleted after 30 days. `--synthetic` is the promise that the test files hold no real customer or member data;
 the CLI refuses a hosted cloud without it and the key. `--environment staging` or `production` is
@@ -192,7 +194,7 @@ answers, with the session's own token. `--agent-version` (else `GITHUB_SHA`) and
 GitHub's branch) are kept with the session. A CI step (GitHub Actions shown):
 
 ```yaml
-- run: npx flow test --cloud https://flow.engineer/observe --synthetic --environment staging
+- run: npx @flow-engineer/flow test --cloud https://flow.engineer/observe --synthetic --environment staging
   env:
     FLOW_FRAMEWORK_CLOUD_KEY: ${{ secrets.FLOW_FRAMEWORK_CLOUD_KEY }}
     OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}