pomerado 0.2.0 → 0.2.1-canary.10

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## Unreleased
+
+- Runs of a built integration, through `run` or a served integration MCP, no longer call Guardian and need no model key. Guardian still reviews minting. A run no longer checks its `intent`, `effect` or `authenticationOrigins`.
+- Integrations generated by earlier versions still have README text that asks for `OPENAI_API_KEY`. They no longer need it.
+- `pomerado run` no longer requires `--intent`, and it ignores `--intent` and `--effect`.
+- A failed run that has no more specific message now reads "Operation failed. Check the local browser and integration configuration." Minting keeps its message.
+- Every merge to `main` publishes a canary, `X.Y.Z-canary.N`, under the `canary` dist-tag: `npm install pomerado@canary`. `latest` moves to the canary that Pomerado's hosted service promotes to production, so `npm install pomerado` gets the build production runs. The range it saves, such as `^0.2.1-canary.57`, also matches later canaries, so install with `--save-exact` or keep a lockfile. See [Releasing](docs/RELEASING.md).
+- A host sign-in step fills a form whose submit is disabled, `aria-disabled` or in a disabled fieldset until the fields hold input. The host waits up to 5 seconds for the page to enable the submit, then clicks it, and never clicks it while it is disabled. It reads whether the submit is disabled the way Playwright's click does, which page scripts can't change. An `aria-disabled` wrapper keeps a submit waiting only when the submit itself has an ARIA role, as Playwright judges it. A page that changes the form's controls three times during the wait is refused. A submit in an `inert` region is still refused before anything is typed.
+- Guardian's review of a host sign-in step shows the origin of the frame the step's controls are in, as the browser reports it, and no longer requires the submit to be enabled. The auth skill likewise lets the minter record a submit the page has not enabled yet.
+
+### Breaking changes
+
+- In `pomerado/core/destinations/autofill-step`, `AutofillInspection.screen` adds a required `origin`, which `inspectAutofillStep` sets. A filled `AutofillStepReport`'s `submit` adds `"stayed_disabled"`: the fields were filled, but the submit stayed disabled through the wait, so the host never clicked it.
+  - Migrate by setting `origin` on any inspection you build yourself, and by handling `"stayed_disabled"` in any exhaustive check on `submit`.
+
+### Fixes
+
+- A local edit the minter can't apply now says the edit was not applied and why. That covers a patch that doesn't match, a file that already exists or is missing, and a file past the size or file-count limit. The file is unchanged, and no new folder is left behind. These edits no longer report "Workspace edit outcome unknown".
+- The minter's `read_source` now reads local workspace files. Through 0.2.0 every local read failed as unavailable, because the local workspace refused the one extra byte the minter asks for to detect an oversized file. A file past 8 MiB is still refused.
+- Local runs stage authored source a level below the SDK, as the workspace guide describes. The documented `../../runtime/index.js` import from `src/` and the skill references' imports now load. Integrations saved with `../runtime/index.js` still run unchanged.
+
 ## 0.2.0
 
 This release changes how a host embeds the minting core's authoring and which MCP entry a generated integration writes. Other standalone use through `pomerado`, `pomerado/mcp` and the CLI needs no change.

package/README.md

@@ -1,263 +1,205 @@
 <h1 align="center"><a href="https://pomerado.ai">Pomerado</a></h1>
 
-<p align="center">Turn websites into MCP integrations.</p>
-<p align="center">Describe what you want to do on a website. Pomerado builds an integration your agent can use.</p>
+<p align="center">Turn websites into MCP integrations your agent can rely on.</p>
 
 <p align="center">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue?style=for-the-badge" alt="License MIT"></a>
+  <a href="https://www.npmjs.com/package/pomerado"><img src="https://img.shields.io/npm/v/pomerado?style=for-the-badge&amp;logo=npm" alt="npm version"></a>
   <img src="https://img.shields.io/badge/node-24.21%2B%20%3C25-339933?style=for-the-badge&amp;logo=nodedotjs&amp;logoColor=white" alt="Node 24.21 or later in Node 24">
-  <img src="https://img.shields.io/badge/pnpm-10.34.5-F69220?style=for-the-badge&amp;logo=pnpm&amp;logoColor=white" alt="pnpm 10.34.5">
 </p>
 
 <p align="center">
-  <a href="#quickstart">Quickstart</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#get-started">Get started</a> ·
   <a href="#create-an-integration">Create an integration</a> ·
   <a href="#use-your-integration">Use your integration</a> ·
-  <a href="#repository-guide">Repository guide</a> ·
+  <a href="#open-source-and-pomerado-cloud">Open source and Cloud</a> ·
+  <a href="#documentation-for-humans-and-agents">Docs</a> ·
   <a href="#contributing">Contributing</a>
 </p>
 
 ---
 
-## How it works
-
-Pomerado helps agents use websites, including ones without APIs. Connect it to Codex, describe a task, and get a reusable MCP integration. Both Pomerado and the integrations you create run on your computer.
+## What Pomerado does
 
-```text
-┌────────────────────────────────────────────────────────────┐
-│  website task → Pomerado MCP → integration MCP → Playwright  │
-└────────────────────────────────────────────────────────────┘
-```
+Pomerado builds MCP integrations for websites, including sites without an API.
 
-- Describe a task in Codex and let Pomerado build the integration.
-- Connect the generated MCP and call it whenever you need it.
-- Answer sign-in questions and other prompts in the same chat.
-- Use your own browser and model API key.
+- Our tool builds integrations with only a natural language description of the task. No HAR file or recording is needed
+- Integrations are deterministic, making them much faster and more reliable than computer use
+- Pomerado works on sites behind a login and two-factor authentication
 
-This repository contains Pomerado's minter and Guardian, with native Playwright for browser execution. Both MCPs use stdio, so Codex starts them for you. Model requests go to your configured provider.
-
-## Quickstart
-
-Use macOS or Linux, Node 24.21 or a later Node 24 release, and pnpm 10.34.5.
+## How it works
 
-```sh
-git clone https://github.com/Pomerado/pomerado.git
-cd pomerado
-corepack enable
-corepack pnpm install --frozen-lockfile
-corepack pnpm exec playwright install chromium
-corepack pnpm build
-export OPENAI_API_KEY='your-model-api-key'
+```mermaid
+flowchart LR
+  try["<b>1. Explore the site</b><br/>Pomerado generates<br/>a script that explores<br/>the site in Chromium"]
+  complete["<b>2. Complete the example</b><br/>Pomerado generates<br/>code that completes<br/>your example"]
+  publish["<b>3. Generalize and publish</b><br/>Pomerado turns that code<br/>into a general integration<br/>that takes new inputs"]
+  use["<b>4. Your agent calls it</b><br/>Your agent calls<br/>the integration and<br/>gets validated output"]
+  try --> complete --> publish --> use
 ```
 
-On Linux, install Chromium's system dependencies with `corepack pnpm exec playwright install --with-deps chromium` if needed.
-
-The shared model configuration uses `gpt-6-sol` for minting and `gpt-6-luna` for Guardian. Your model account must have access to both. Local hosting still sends model requests to your configured provider. Library callers can inject Agents SDK `ModelProvider` implementations through `minterProvider` and `guardianProvider`.
+For more details, see [How it works](docs/how-it-works.md).
 
-### Connect Pomerado to Codex
+## Get started
 
-Find your Node executable and checkout paths.
+Prerequisites
 
-```sh
-node -p 'process.execPath'
-pwd
-```
+- macOS or Linux
+- Node 24.21 or a later Node 24 release, which you can check with `node --version`
+- An OpenAI API key, since Pomerado uses OpenAI models to build and review integrations. Your agent can run on any model
+- An MCP client that runs local servers, such as Claude Code, Codex, Cursor, VS Code, Claude Desktop or Gemini CLI
 
-Add this section to `~/.codex/config.toml`, replacing the paths with yours. Keep your other configuration sections.
+Install Pomerado and the Chromium build it drives.
 
-```toml
-[mcp_servers.pomerado]
-command = "/absolute/path/to/node"
-args = ["/absolute/path/to/pomerado/dist/typescript/src/standalone/mcp-cli.js", "mint", "--root", "/absolute/path/to/integrations"]
-env_vars = ["OPENAI_API_KEY"]
+```sh
+npx -y -p pomerado pomerado-mcp --help
+npx -y -p pomerado playwright install chromium
 ```
 
-Codex must have `OPENAI_API_KEY` in its environment so it can forward the value to the MCP. Keep that key out of chat and integration source. The configuration names the environment variable without writing its value. See the [Codex MCP configuration documentation](https://learn.chatgpt.com/docs/extend/mcp) for client setup.
-
-The configured root is where minted integrations are saved. Starting the MCP and listing tools do not launch Chromium or invoke a model.
+On Linux, add `--with-deps` after `install` if Chromium's system libraries are missing.
 
-## Create an integration
+Pomerado runs as a standard MCP stdio server. Clients that read an `mcpServers` file use this entry.
 
-Ask Codex to create an integration with Pomerado. We call this minting.
+```json
+{
+  "mcpServers": {
+    "pomerado": {
+      "command": "npx",
+      "args": ["-y", "-p", "pomerado", "pomerado-mcp", "mint", "--root", "/absolute/path/to/pomerado-integrations"]
+    }
+  }
+}
+```
 
-> Use Pomerado to create an integration named example_reader that reads the main heading from https://example.com. Keep it read-only.
+- `--root` sets the folder where Pomerado saves your integrations. Use an absolute path, because each client starts servers from its own working folder
+- The server reads `OPENAI_API_KEY` from its environment, so the key never needs to appear in chat
+- Starting the server and listing its tools costs nothing. It launches no browser and calls no model until you start a mint
 
-- `mint` creates an integration from a name, URL, task description, optional input, and `read` or `write` permission. Names use lowercase letters, digits and underscores.
-- `get_job` checks progress and waits for a question or completion. Minting starts once and returns a job ID.
-- `provide_input` sends your answer to a question in the same chat. Pomerado checks that the answer matches the requested format.
-- `cancel_job` stops the job and cleans up its browser and child process. An action already sent to a website may have taken effect.
+Add Pomerado to your client with the command or file below.
 
-Codex uses these tools to continue the same job. Checking progress or answering a question never starts the integration again. The default active mint budget is 20 minutes. Time spent answering a human question does not consume that budget.
+| Client | Add Pomerado |
+| --- | --- |
+| Claude Code | `claude mcp add --scope user pomerado -- npx -y -p pomerado pomerado-mcp mint --root ~/pomerado-integrations` |
+| Codex | `codex mcp add pomerado -- npx -y -p pomerado pomerado-mcp mint --root ~/pomerado-integrations`, then add `env_vars` |
+| Gemini CLI | `gemini mcp add -s user -e 'OPENAI_API_KEY=$OPENAI_API_KEY' pomerado npx -y -p pomerado pomerado-mcp mint --root ~/pomerado-integrations` |
+| Cursor | Add the entry to `~/.cursor/mcp.json` |
+| VS Code | `code --add-mcp '{"name":"pomerado","command":"npx","args":["-y","-p","pomerado","pomerado-mcp","mint","--root","/absolute/path/to/pomerado-integrations"]}'`, or add the entry to `.mcp.json` in your workspace |
+| Claude Desktop | Add the entry to `claude_desktop_config.json` |
 
-Choose write authority only when you intend to change the website. A write mint can perform the requested action while creating the integration. Its final source is checked without repeating that action. The standalone host requires write authority up front.
+Each client passes environment variables its own way. [Client settings](docs/getting-started.md#client-settings) covers the key and the timeouts for every client above.
 
-The destination must be new. Pomerado reserves it before starting work, so a name collision cannot run the task and then fail to save it.
+To confirm the setup, ask your agent which Pomerado tools it has. It should list `mint`, `get_job`, `provide_input` and `cancel_job`.
 
-## Use your integration
+## Let your agent set it up
 
-When minting finishes, Pomerado saves the integration and returns the paths you need to connect it.
+If you'd rather not run these steps yourself, paste this into your agent.
 
 ```text
-integrations/example_reader/
-├── src/                 Generated operation modules
-├── pomerado.json        Entrypoint and input/output schemas
-├── deployment.json      Tool name, description, URL, intent and authority
-├── mcp.mjs              Fixed launcher for the shared Pomerado runtime
-├── mcp.json             Standard MCP server entry, with no key
-└── README.md            Commands and usage for this integration
+Set up Pomerado for me by following https://raw.githubusercontent.com/Pomerado/pomerado/main/docs/agent-setup.md
 ```
 
-1. Open the generated `README.md`. It lists the add command for each major MCP client, with your local Node, launcher and runtime paths filled in.
-2. Add the server to your client, or copy the entry in `mcp.json` into a client that reads an `mcpServers` file.
-3. Make sure the server gets `OPENAI_API_KEY` from its environment. Generated integrations still use Guardian.
-4. Reload the MCP configuration in your client and ask it to use the integration.
-
-> Use example_reader to read the page heading.
-
-The integration MCP exposes a tool named after your integration, with its arguments nested under `input`. It also provides `get_job`, `provide_input` and `cancel_job` for calls that need an answer or more time.
-
-Ordinary calls return the validated operation output. A pending call returns a job ID to continue. Calling the business tool again starts a new execution, including another website write when the integration has write authority.
-
-The generated launcher imports your installed Pomerado runtime. Keep that installation available. The launcher source is portable, but its local configuration contains installation paths. Update those paths if you move the integration, Node or Pomerado.
-
-## Questions and authentication
-
-When a task needs a login, Pomerado can inspect the sign-in form, ask for credentials in chat, and fill them into the browser. It uses the same sign-in and autofill helpers as the Pomerado application.
+Your agent checks your Node version, installs Chromium and adds Pomerado to the client it runs in. It asks before changing anything you didn't mention, and it never asks for your API key in chat.
 
-Answers sent through `provide_input`, including passwords and codes, are visible to the MCP client and its model provider. Codex should explain this before collecting protected answers. There is no portal, credential vault, saved login recipe, submission ledger or automatic SMS/TOTP service.
-
-Each MCP job owns a fresh browser context and closes it when the job ends. A minted integration does not inherit the mint's signed-in browser. Authenticated runs need their own declared sign-in inputs and implementation. Automatic login replay is not included. The library can keep a signed-in session open across mint and run calls.
+## Create an integration
 
-Jobs and pending answers live in memory. Restarting the MCP loses active jobs but keeps saved integrations. The default server accepts one active job and retains at most 32 job records, with completed records expiring after 15 minutes.
+Ask your agent to create an integration with Pomerado. We call this minting. A good request names the site, describes the task in plain language and says whether the integration should only read or also make changes.
 
-Supplied secrets are masked in minting-model observations and checked in generated source. Operation outputs are returned without secret redaction. Error diagnostics mask credential-shaped values. Website content reaches the configured models. This package has no general privacy screening service.
+> Use Pomerado to create an integration named example_reader that reads the main heading from https://example.com. Keep it read-only.
 
-<details>
-<summary>Attach an existing Playwright browser</summary>
+Your agent runs the mint with four tools.
 
-By default, Pomerado launches local Chromium. Add `--headed` to the minting MCP arguments to see it. To use an existing browser server, add `--endpoint` and its native Playwright WebSocket URL to the MCP command arguments.
+- `mint` starts a job from a name, a URL, a task, an optional example input and `read` or `write` authority. It returns a job ID right away
+- `get_job` waits up to 30 seconds for progress, a question or the result. Checking a job never restarts the work
+- `provide_input` sends your answer when Pomerado asks a question. Pomerado checks the answer against the question's format
+- `cancel_job` stops the job and closes its browser. An action already sent to a website may still have taken effect
 
-```toml
-args = ["/absolute/path/to/pomerado/dist/typescript/src/standalone/mcp-cli.js", "mint", "--root", "/absolute/path/to/integrations", "--endpoint", "ws://your-browser-host/playwright-endpoint"]
-```
+Authority decides what an integration is allowed to do, so choose it deliberately. Your agent picks one when it calls `mint`, and the tool tells it to ask you before choosing `write`.
 
-The endpoint must support `chromium.connect()`, with a matching Playwright version. A Chromium remote debugging URL for `connectOverCDP()` uses a different protocol. For a local connection test, start a Playwright browser server and use its printed endpoint.
-
-```sh
-node --input-type=module -e 'import { chromium } from "playwright"; const server = await chromium.launchServer({ headless: true }); console.log(server.wsEndpoint());'
-```
+- Use `read` when the task only looks at a website
+- Use `write` only when the task changes something, such as submitting a form or making a booking
+- A write mint performs the action once while it builds, then reviews the final source without repeating it
+- A read mint that finds the task needs a change asks to switch to write, and your agent's answer decides
+- A run doesn't check authority, intent or sign-in origins, and edits to `src/` or `deployment.json` aren't reviewed
 
-Pomerado owns its browser context. Closing a session closes that context and disconnects from a supplied server, leaving the server and other clients' contexts available. A failed browser transport is invalidated without replaying the request.
+Names start with a lowercase letter and use only lowercase letters, digits and underscores. The integration's folder must not exist yet. Each mint gets 20 minutes of active work, and time spent waiting for your answers doesn't count against it.
 
-</details>
-
----
+## Use your integration
 
-## Repository guide
+When minting finishes, Pomerado saves the integration as a folder of source code and returns its paths.
 
-This repository owns the shared minter, Guardian, operation runtime and live authentication helpers. Its local host supplies files, child processes and native Playwright. Pomerado Cloud installs the same core as a pinned library package.
-
-| Path                           | Responsibility                                                   |
-| ------------------------------ | ---------------------------------------------------------------- |
-| `typescript/src/mint/`         | Shared minter loop, source tools and completion                  |
-| `typescript/src/guardian/`     | Shared review loop, source inspection and policy                 |
-| `typescript/src/runtime/`      | Shared operation SDK, schemas and browser call contract          |
-| `typescript/src/browser/`      | Shared browser helpers used by authored operations               |
-| `typescript/src/destinations/` | Shared sign-in inspection, autofill and trusted credential entry |
-| `typescript/src/inputs/`       | Input validation, terminal collection and per-session secrets    |
-| `typescript/src/execution/`    | Local workspaces, child processes and native Playwright adapter  |
-| `typescript/src/standalone/`   | Local library, terminal and MCP composition                      |
-| `typescript/src/mcp/schema.ts` | Pure schema adapter shared with the production MCP               |
-| `typescript/authoring/`        | Shared prompts and examples, with sections a host can replace    |
-
-<details>
-<summary>Runtime boundaries and browser compatibility</summary>
-
-Generated code keeps the application's browser call shape.
-
-```js
-const response = await kernel.browsers.playwright.execute(sessionId, {
-  code: "return await page.title();",
-  timeout_sec: 30,
-});
+```text
+pomerado-integrations/example_reader/
+├── src/                 Generated operation modules
+├── pomerado.json        Entrypoint and input and output schemas
+├── deployment.json      Tool name, description, URL, task and authority
+├── mcp.mjs              Launcher for the shared Pomerado runtime
+├── mcp.json             Standard MCP server entry, with no key
+└── README.md            Add commands for each MCP client
 ```
 
-Here `kernel` is a compatibility object forwarding calls to native Playwright over local process IPC. It does not load the Kernel SDK or call Kernel. Narrow credential-keyboard and browser-ownership checks still use Chromium's low-level CDP primitives where required.
-
-This public repository is the sole source for the shared core, portable tests, authoring assets and local MCP adapters. Cloud calls the installed library directly. Its hosted MCP frontend stays in the private repository with accounts, permissions and durable jobs.
+1. Open the integration's `README.md`. It has the add command for each major client with your paths already filled in
+2. Add the server with that command. Skip the key setup. Running an integration makes no model request, so only minting needs `OPENAI_API_KEY`
+3. Reload your client and ask your agent to use the integration
 
-Cloud owns the REST backend, database, hosted browser and compute providers, recorder, evidence bundles, general privacy service, repair loop, credential storage and its own hosted authoring text.
+> Use example_reader to read the page heading.
 
-Integrations run through native Playwright. The local host does not mint HTTP variants, record network traffic, produce `captures/routes.json`, or provide the hosted `SiteHttp` transport and capture replay helpers. Website requests made inside the browser remain available.
+Each integration appears to your agent as its own MCP server.
 
-Authored operation processes, offline commands and native Playwright page-code workers run with your operating system user's filesystem and network privileges. Guardian review and file checks do not provide an OS sandbox. Clearing the worker's `process.env` hides environment variables from that API; it does not isolate host credentials or prevent access through operating system facilities.
+- It has one tool named after the integration, with its arguments under `input`
+- It also has `get_job`, `provide_input` and `cancel_job` for calls that need an answer or more time
+- A call returns output that matches the schema in `pomerado.json`, or a job ID to follow up on
+- Each call is a new run. With write authority, calling again performs the write again
+- The integration runs on the Pomerado installation that minted it. For a stable path, install globally with `npm install -g pomerado` and use `pomerado-mcp` in place of `npx -y -p pomerado pomerado-mcp`
 
-</details>
+## Open source and Pomerado Cloud
 
-<details>
-<summary>Library and terminal use</summary>
+This repository is the complete Pomerado core, released under the MIT license. Everything you need to mint integrations and run them yourself is here, with no Pomerado account required.
 
-The existing library and terminal interfaces remain available. A library session can mint and run while retaining the same signed-in browser context.
+- The minter, which builds integrations in a real Chromium browser
+- The minting harness and prompts that Pomerado Cloud also builds on
+- Guardian, which reviews each browser action and the finished source while minting, not when an integration runs
+- The standalone host, which serves each integration as an MCP server on your own machine
+- The integrations themselves, saved as source code in your folder that you own
 
-```js
-import { Effect } from "effect";
-import { createPomerado, makeTerminalAsker } from "pomerado";
+[Pomerado Cloud](https://pomerado.ai) runs this same core as a managed service. It adds the operations that production use needs.
 
-await Effect.runPromise(
-  Effect.scoped(
-    Effect.gen(function* () {
-      const session = yield* createPomerado({ ask: makeTerminalAsker() });
-      const request = {
-        url: "https://example.com",
-        intent: "Read the main heading",
-        input: {},
-        effect: "read",
-      };
-      const result = yield* session.mint(request);
-      if (result.artifact === undefined) throw new Error(result.summary);
-      console.log(yield* session.run(result.artifact, request));
-    }),
-  ),
-);
-```
+- Hosting for your integrations and their jobs
+- OAuth brokerage and saved logins
+- Access control over who can use each integration
+- A managed browser fleet that handles bot protection
+- Breakage detection that notices when a site changes and repairs the integration automatically
 
-Use `makeInputAsker` to adapt your own chat callback. Its callback receives an `InputRequest` and returns raw answers keyed by question ID. `makePomeradoMcp` and `makeIntegrationMcp` expose the same local MCP modes as library functions. Their Effect scopes own cleanup.
+## Documentation for humans and agents
 
-The package exposes local APIs and direct core library entry points. Importing a core module does not start a browser, MCP listener or workspace.
+- [Getting started](docs/getting-started.md) covers install, client settings, a first integration and troubleshooting.
+- [Agent setup](docs/agent-setup.md) gives an AI agent the steps to install Pomerado for you.
+- [How it works](docs/how-it-works.md) covers the minter, Guardian, the runtime, jobs and the library.
+- [AGENTS.md](AGENTS.md) tells coding agents how to change this repository.
+- [CONTRIBUTING.md](CONTRIBUTING.md) covers building from source and how changes land.
+- [RELEASING.md](docs/RELEASING.md) covers how npm releases are built and verified.
 
-- Use `pomerado`, `pomerado/runtime` and `pomerado/mcp` for local sessions, the authored browser runtime and local MCP composition.
-- Use explicit `pomerado/core/*` subpaths such as `pomerado/core/mint/harness`, `pomerado/core/guardian/review` and `pomerado/core/runtime/host-execute` for hosted library composition. The export map lists supported modules.
-- Use `pomerado/testing/*` for reusable test helpers and fixtures. Vitest is an optional peer for helpers that need it.
-- Use `getAuthoringDirectory` and `getGuardianPolicyPath` from `pomerado/assets` for installed prompt and policy paths. These paths resolve relative to the package.
-- `loadAuthoringSkills` and `loadWorkspaceGuide` from `pomerado/core/mint/skills` render each named authoring section's standalone text by default. A host that supplies its own text for those sections composes the directory first, then loads it in `"hosted"` mode, which refuses any section left uncomposed.
+## Repository guide
 
-Run `corepack pnpm start --help` for the advanced terminal mint/run interface. Terminal mint retains its original source-artifact format. Use the MCP minting entrypoint for generated MCP packaging.
+| Path | Contents |
+| --- | --- |
+| `typescript/src/` | Minter, Guardian, runtime, browser helpers and the local MCP host |
+| `typescript/authoring/` | Shared prompts and examples, with sections a host can replace |
+| `typescript/tests/` | Unit tests and browser tests with local fixture sites |
+| `tools/` | Build helpers and the CI scans |
+| `docs/` | Guides for users, agents and maintainers |
+| `third-party/` | Licenses for adapted third-party code |
 
-</details>
+[How it works](docs/how-it-works.md#source-layout) lists each module under `typescript/src/`.
 
 ## Contributing
 
-```sh
-corepack pnpm typecheck
-corepack pnpm build
-corepack pnpm test
-corepack pnpm exec playwright install chromium
-corepack pnpm test:browser
-```
+- Issues are welcome.
+- Outside pull requests open once the review and approval gate in [CONTRIBUTING.md](CONTRIBUTING.md) is live.
+- Security problems go privately through **Report a vulnerability** on the [Security tab](https://github.com/Pomerado/pomerado/security).
+- [CONTRIBUTING.md](CONTRIBUTING.md) has the clone, build and test steps.
 
-This repository owns the portable tests for its shared core and local runtime, with synthetic fixtures and the existing Vitest and Playwright runners. Browser tests exercise native Playwright, minting through MCP, generated integration MCPs, authentication and autofill using local fixture sites and scripted model responses. They need no Cloud account or model API key. Tests for hosted services stay in the application repository.
-
-Outside pull requests are not accepted yet. They open once the review and approval gate described in [CONTRIBUTING.md](CONTRIBUTING.md) is live. Issues are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for how changes land and how to report a vulnerability privately.
-
-Public tests use synthetic sites and data. Keep customer-specific incidents, private credentials and internal issue references out of public contributions. CI enforces this with a gitleaks secret scan and a public content scan. Run `node tools/check-public-content.ts` before you push. Link a public issue by its full URL.
-
-- Build and test the package before publishing an explicit versioned release. The release workflow validates the packed artifact before npm publication.
-- Adopt a tested release in Cloud through an exact dependency pin and locked integrity. Update the controller and sandbox images together.
-- Roll Cloud back by restoring its previous package pin and matching image versions. Public commits do not update Cloud automatically.
-
-The clone and build quickstart works independently of npm releases. Contributors can test Cloud against a locally built package before publishing a new version.
-
----
+## License
 
 Copyright (c) 2026 Pomerado AI, Inc. Licensed under the MIT License (`MIT`). See [LICENSE](LICENSE).
 

package/dist/typescript/authoring/auth/SKILL.md

@@ -10,6 +10,12 @@ screen's fields and its submit control, and the host fills them from the private
 the submit. You never see, type, request or read back a credential. Start with a `signInStep` for
 the first screen. If a step fails, inspect the site and correct the steps in this browser.
 
+A code the site sends as part of signing in, by text message, email or an authenticator app, is
+part of the sign-in: map its screen as a `signInStep` with a `code` field and let `authenticate`
+get the code. Never ask for it separately with `request_input`. A `request_input` secret question
+for a code is only for a later protected action after sign-in, when the site asks for another code
+to confirm it.
+
 Sign in only when the task needs it (the request asks, the task is about the caller's own account,
 or the data sits behind a login wall). Try a public task signed out first.
 
@@ -59,10 +65,11 @@ ask with `request_input` right away. A preselected option says nothing about the
 
 <!-- pomerado:section auth.signed-out-flow -->
 
-Record a field or submit only after observing its unique visible enabled match in the intended
-frame and form. Validate the complete live login and a fresh signed-out replay from the stable
-login URL. A saved DOM supports locator matching and extraction; it cannot prove live controls
-are actionable, their event handlers work or authentication succeeds.
+Record a field only after observing its unique visible enabled match in the intended frame and
+form, and a submit after observing its unique visible match there, even one the page enables only
+once the fields hold input. Validate the complete live login and a fresh signed-out replay from
+the stable login URL. A saved DOM supports locator matching and extraction; it cannot prove live
+controls are actionable, their event handlers work or authentication succeeds.
 
 <!-- pomerado:section auth.partial-flow -->
 
@@ -142,6 +149,10 @@ browser. A failed host check leaves this browser available for another evidenced
 that sign-in could not be verified when the site or the remaining allowance prevents recovery.
 Never send a visibly rejected value again. There is no provider-login fallback.
 
+When the host refuses to type into a field (`AutofillRefused`), its answer names the field, the
+check that refused it and why. Fix that cause before sending the step again: the same refusal of
+the same field on the same screen three times in a row ends sign-in in this build.
+
 <!-- pomerado:section auth.after-recovery -->
 
 # Every sign-in ends with its check
@@ -166,10 +177,10 @@ A direct sign-in request signs in with one host-filled HTTP request instead of a
 
 ## Standalone live authentication
 
-Observe the current login screen with a reviewed read-only probe: its URL, frames, visible field labels/types/names/autocomplete, form destination and enabled submit. Never read control values or enter credentials in source. Pass `signInStep` to execute purpose `authenticate`, target `liveBrowser`, with the evidenced reusable `loginUrl`.
+Observe the current login screen with a reviewed read-only probe: its URL, frames, visible field labels/types/names/autocomplete, form destination and submit. Never read control values or enter credentials in source. Pass `signInStep` to execute purpose `authenticate`, target `liveBrowser`, with the evidenced reusable `loginUrl`.
 
 Fields use the same slots and format declarations. `username` lists every accepted identifier kind; password/code/recovery-code/date-of-birth/ZIP match that observed field's purpose. The host obtains the needed value through the caller's protected input callback or masked terminal, checks the original field/document/origin/focus binding and inserts privately. No saved credential, seed, SMS automation or recipe is used. No value enters your model context or files.
 
-Inspect each subsequent screen and send its observed step. A method or account choice needs caller input before selection. Wait for and verify an observed signed-in marker; disappearance of the login form is insufficient. Rejection requires caller correction and never authorizes replay of a private submission. Popup/frame sign-in uses the observed host target and configured sign-in origins, with the same destination guard.
+Inspect each subsequent screen and send its observed step. After a step whose submit the host clicked, its result names `captures/after-submit/<step>.json`, where the host saved the next screen's controls: role, name or label, input type, and whether each is required, visible and enabled, never a value. Read it first to see what the screen asks for, then probe read-only only for what it lacks, such as a selector or form destination. A failed step's result shows the last saved controls inline, at most 30, and the file holds the rest. A method or account choice needs caller input before selection. Wait for and verify an observed signed-in marker; disappearance of the login form is insufficient. Rejection requires caller correction and never authorizes replay of a private submission. Popup/frame sign-in uses the observed host target and configured sign-in origins, with the same destination guard.
 
 pomerado:section auth.direct-request:end -->

package/dist/typescript/authoring/caller-input/SKILL.md

@@ -10,7 +10,9 @@ Try first. Ask only for what the page or the caller uniquely knows at that point
 - a choice whose options exist only once the run reaches them: the open seats of the
   flight the caller just chose, the delivery slots for the cart the run just filled, or
   which of the account's saved travelers or addresses to use;
-- a code the site sends during the action, such as a confirmation code by text or email;
+- a code the site sends to confirm a protected action after sign-in, such as a confirmation code
+  by text or email. A code that is part of signing in is the host's: a `code` field of the
+  `authenticate` step, never a question;
 - a fact only the caller has that the site now asks for.
 
 <!-- pomerado:section caller-input.published-input -->

package/dist/typescript/authoring/core/SKILL.md

@@ -166,9 +166,11 @@ is bounded; never describe a truncated list as complete.
 
 Supported login challenges during `authenticate` belong to the host's sign-in
 (autofill or an explicit direct HTTP step) and its protected input requests. Generated `operation.run` and `explore` code
-never request or enter a sign-in code, or sign in themselves. A code the site sends during the
-action, such as a two-factor or confirmation code, is different: declare it as a `secret`
-question and ask it with `ask`, as the caller-input skill's `caller-code.ts` shows. A missing ordinary page
+never request or enter a sign-in code, or sign in themselves: an SMS, email or authenticator code
+that is part of signing in is a `code` field of the `authenticate` step (auth skill), never asked
+separately. A code the site sends later, to confirm a protected action after sign-in, is different:
+declare it as a `secret` question and ask it with `ask`, as the caller-input skill's
+`caller-code.ts` shows. A missing ordinary page
 control alone does not establish a human-verification challenge. Observe the
 current page state within the existing deadline. When a few distinct attempts have
 not found the way, ask the caller for directions with `request_input` before

package/dist/typescript/authoring/pagination/SKILL.md

@@ -13,6 +13,18 @@ or an agent's remembered Page is not a cursor authenticity check.
 
 <!-- pomerado:section pagination.no-recreated-writes -->
 
+## Append pagination ("load more")
+
+Some pages page by appending: a "Load more" or "Show more" control, or scrolling to the
+bottom, adds rows to the same list instead of navigating. Detect it when activating the
+control leaves the URL and page number unchanged while the row count grows, or when a
+scroll adds rows. Then page by repeating that one action and reading only the rows it
+added, identified by stable ID, until the control disappears or disables, a step adds no
+new rows, or the requested count is met. Bound the loop: a fixed step cap and a time
+budget, with a short wait for rows after each step. On hitting a bound, return the rows
+read with an explicit reason and no pretend next cursor. Never treat a repeated click as
+safe if it could submit or change anything.
+
 Use and test both warm and fresh paths, including expired state, changed live data,
 wrong query/account and unsupported reconstruction. `references/pagination.ts`
 provides a compiling authoring pattern; its hooks are site logic, not platform

package/dist/typescript/authoring/workspace/AGENTS.md

@@ -132,9 +132,11 @@ add-on toggle, a pre-selected checkbox or a lone saved payment method is still a
 to ask about. Read the path's options with read-only exploration where you can and settle them before
 the first act step where possible; a question during the session waits in place. Take a site default only for a choice that is not a
 credential, not a write and easy to reverse, and list it in `finish_build` `assumptions`. A full
-new login goes through execute purpose `authenticate`, where the host fills or asks for any
-sign-in code; a standalone two-factor code needed during an action is a `request_input`
-secret question, and `authenticate` is never started just for a code. You may ask after live
+new login goes through execute purpose `authenticate`: an SMS, email or authenticator code that
+is part of signing in is a `code` field of its `signInStep`, which the host fills or asks the
+caller for, so never ask for it with `request_input`. The standalone code path, a
+`request_input` secret question, is only for a later protected action after sign-in, when the
+site asks for another code to confirm it; `authenticate` is never started just for such a code. You may ask after live
 execution has closed or while a write's outcome is uncertain; after the answer, verify the
 current state before writing again.
 
@@ -247,9 +249,9 @@ Use the same canonical operation SDK and Kernel-shaped browser execute syntax. T
 
 `read_source` reads source, installed skills and references in bounded ranges. `apply_patch` edits only authored directories. `execute` supports `liveBrowser` and `pureFiles`; every command or live execution receives fresh Guardian review. `exec_command` runs a local process over caller-owned files with an explicit environment; it is not an operating-system or network sandbox. Never use a command, Node fetch or socket to access the website; browser work stays in reviewed Playwright calls. `request_input`, `report_blocked` and `finish_build` use their existing request shapes.
 
-Inspect the current page with bounded read-only probes. Use only caller-supplied input, answers and observed page choices. Keep observations focused; there are no recorder captures to read or retain. A timeout or browser loss leaves effects uncertain: read back current state before repeating an action and never replay an uncertain write.
+Inspect the current page with bounded read-only probes. Use only caller-supplied input, answers and observed page choices. Keep observations focused; there are no recorder captures to retain. A timeout or browser loss leaves effects uncertain: read back current state before repeating an action and never replay an uncertain write.
 
-For sign-in, inspect the actual current fields without reading their values, then submit an observed `signInStep` through execute purpose `authenticate`. The host collects credentials through protected callback or masked terminal input and inserts them through the guarded credential channel. Model text, files and ordinary output never contain passwords or codes. A secret answer is an opaque handle; apply the core skill's whole-value restrictions.
+For sign-in, inspect the actual current fields without reading their values, then submit an observed `signInStep` through execute purpose `authenticate`. The host collects credentials through protected callback or masked terminal input and inserts them through the guarded credential channel. After each step whose submit it clicked, the host saves the next screen's controls (role, name or label, input type, required, visible, enabled; never a value) to `captures/after-submit/<step>.json` and its result names that file: read it with `read_source` or `exec_command` like any other file. A step that fails also shows the last saved controls inline, at most 30. Model text, files and ordinary output never contain passwords or codes. A secret answer is an opaque handle; apply the core skill's whole-value restrictions.
 
 A write performs the caller's task once as live act steps, reads back a supported confirmation, then composes the operation from those steps. Do not execute the composed write again. Finish with honest coverage and the confirming execution ID; returning integration files does not justify a second website write.
 

package/dist/typescript/src/destinations/autofill-fill.d.ts

@@ -22,7 +22,9 @@ interface FillInput {
  * nothing reached the site: a lost answer is `uncertain`, a control refused before a field's typing
  * fails that field, and one refused before the click, or a submission refused as it fires, refuses
  * the submit. That click ran, though, so the report says so (`clicked`): the page's own handlers
- * ran on it, and what the step filled may have gone out.
+ * ran on it, and what the step filled may have gone out. A submit the page keeps disabled is never
+ * clicked: the host waits for the page to enable it once the fields are filled, and when it stays
+ * disabled the report says so (`stayed_disabled`).
  */
 export declare const fillAutofillStep: (input: FillInput) => Effect.Effect<AutofillStepReport>;
 export {};