@uppercut-labs/agent-native 0.0.0-stage → 1.1.0

package/docs/evidence/UAN-023-inspector-host-probe.md

@@ -0,0 +1,37 @@
+# UAN-023 named-client and host availability probe
+
+Date: 2026-10-03 UTC. Isolated source commit: `076b4197e49997da190389d9e247521baa3bab50`. Host: `research`, macOS 27.0 build 26A425, Node 25.9.0, npm 11.12.1. These observations do not complete UAN-023 or the v1 release matrix.
+
+## Pinned named MCP client over HTTP
+
+The independent client was the official [MCP Inspector CLI](https://github.com/modelcontextprotocol/inspector/blob/main/clients/cli/README.md), pinned to `@modelcontextprotocol/inspector@2.8.0`. It connected with Streamable HTTP to the packed E09 example's actual loopback server. This is a real named client and real HTTP transport; the server/data and identity policy remain local fixtures. No commercial service or external network endpoint was tested.
+
+Reproduce from this checkout:
+
+```sh
+npm ci --ignore-scripts --no-audit --no-fund
+npm run build
+npm run example:e09
+node test/uan023-inspector-client.mjs
+```
+
+The manual probe starts the E09 server on `127.0.0.1`, invokes the Inspector CLI four times with a 45-second per-call timeout, asserts protocol outcomes, and closes the server. It uses `npx --yes @modelcontextprotocol/inspector@2.8.0`; no credential is passed.
+
+Observed results:
+
+| Probe | Inspector result |
+| --- | --- |
+| `tools/list` | Exit 0; exactly one named album-lookup tool with input/output schemas and a `ui://uppercut/album-explorer.html` resource reference |
+| `tools/call --app-info` | Exit 0; `hasApp: true`, resource MIME `text/html;profile=mcp-app` |
+| `tools/call` with `{"slug":"first-light"}` | Exit 0; text and `structuredContent.result` both represent the found album |
+| `tools/call` with `{"slug":"blocked-album"}` | Exit 5; `isError: true` and no successful value |
+
+The standalone E09 packaging/build/tests also passed (3/3). The probe script is the exact assertion source. Its `.exported` E09 dependency is intentionally generated by `npm run example:e09`, not checked in. The result expands the prior SDK-only fixture evidence to a separately distributed named client CLI. Inspector CLI app metadata inspection does **not** demonstrate rendering or interaction in an MCP Apps host.
+
+## Browser and MCP Apps host boundary
+
+Installed Google Chrome 154.0.8037.95 was probed in a headless, no-focus session without an origin-trial token or experimental flag. `document.modelContext` and its `registerTool` member both evaluated as `undefined` on a blank page. This shows the default local Chrome session did not expose native WebMCP; it does not test a supported WebMCP agent host. Chrome's [WebMCP origin-trial notice](https://developer.chrome.com/blog/ai-webmcp-origin-trial) describes opt-in access. The package's ordinary-site fallback was covered by earlier simulated/browser fixtures, not by this blank-page probe.
+
+The Inspector CLI read App resource metadata and called the tool, but no Inspector web UI or other MCP Apps iframe host was opened. App rendering, host-mediated UI actions, browser sandbox/CSP enforcement, and consent behavior remain unverified. No author-independent human or clean-context Astro adoption was performed. UAN-023 cannot be marked complete from this slice.
+
+No Windows foreground UI was used. No external credential, private package, deployment, or npm publish was involved.

package/docs/evidence/UAN-023-inspector-web-and-astro-adoption.md

@@ -0,0 +1,44 @@
+# UAN-023: Inspector web host and clean-context Astro adoption
+
+Date: 2026-10-03 UTC. Isolated public source base: `8a502b5` on `research` (macOS 27.0, build 26A425; Node 25.9.0; npm 11.12.1). This is a delegated clean-context agent using only public package docs, public example source, and official host docs. It is not an unrelated human trial. No canonical checkout was edited for these observations.
+
+## Named MCP Apps web host
+
+The official `@modelcontextprotocol/inspector@2.8.0` web Apps tab connected through real loopback Streamable HTTP to the packed E09 server. The Inspector's sandbox iframe rendered in headless Google Chrome 154.0.8037.95, driven with Playwright 1.56.1. The E09 project used `@modelcontextprotocol/server@2.3.0`, `@modelcontextprotocol/client@2.3.0`, and `@modelcontextprotocol/ext-apps@2.0.3`.
+
+Reproduce after a normal repository `npm ci`:
+
+~~~sh
+npm run example:e09
+npm install --no-save --package-lock=false --ignore-scripts --no-audit --no-fund playwright@1.56.1
+node test/uan023-inspector-web.mjs
+~~~
+
+The browser script launches the Inspector with its web, sandbox, and App-origin listeners bound to `127.0.0.1`, disables automatic foreground opening, generates a fresh token without printing it, and uses the Inspector's documented deep link. It waits for `connected` and `data-app-status="ready"`, then enters the actual iframe. The initial tool result displayed `First Light (first-light)`. Submitting `blue-hour` from the view displayed `Blue Hour (blue-hour)`; submitting `blocked-album` displayed `The host denied this request.` The app's binding ran exactly twice, so the denied call did not execute it. There were three frames (Inspector, sandbox proxy, App), no page errors, and no App CSP console errors. This is a real named local host result, beyond the earlier in-memory AppBridge fixture and Inspector CLI metadata probe.
+
+The first host attempt connected and called the E09 tool but left the view in `loading`. Headless Chrome showed a CSP-blocked `http://127.0.0.1:6485/view.js` request. Investigation found `template.replace(marker, replacementString)` expanded `$&` tokens in esbuild's minified bundle: the generated resource had 24 opening/closing script tags and 23 copied `src="./view.js"` references. The builder now replaces through a callback, checks for exactly one marker, and escapes any closing-script token in bundled JavaScript. The focused E09 resource assertion checks one inline module script, one closing tag, and zero external view references. After this fix, standalone E09 passed 3/3 and the real Inspector iframe passed.
+
+[Inspector MCP App review recipe](https://github.com/modelcontextprotocol/inspector/blob/main/docs/mcp-app-review.md) and [Inspector web client contract](https://github.com/modelcontextprotocol/inspector/blob/main/clients/web/README.md) describe the deep link, iframe, and sandbox host used here.
+
+## Fresh existing-Astro adoption
+
+The agent followed [getting started](../getting-started.md), [static sites](../static-sites.md), [frameworks](../frameworks.md), and linked public E01/E02 example sources. Each before-state site was copied to a fresh temporary directory; no private planning instructions, private packages, credentials, or deployment were used. The local `0.0.0` package was installed from a tarball generated by `npm run example:e09`, since npmjs publication has not happened.
+
+**E01 static Astro (Astro 7.3.5).** `npm ci` and the before-state build passed. The documented `createInitPlan` and `applyInitPlan` calls with `{ hosting: 'cloudflare', routeMode: 'sidecar', sidecarOrigin: 'http://127.0.0.1:8787' }` returned an applied plan. The detection accurately reported `hosting-unknown`; the explicit choice resolved it. The after-state build retained three static pages and the original data, pages, SVG, and CSS byte-for-byte. The init-generated browser entry only announces readiness. This proves the narrow documented init flow, not a registered capability or live sidecar.
+
+The separate fully integrated public E01 example was exported with `npm run example:e01`. Its targeted fixture checks and three-page static build passed. A headless Chrome run initially exposed a real-browser failure hidden by simulated tests: the album form briefly displayed a result, then Astro ClientRouter navigated to `/albums/?slug=first-light` and cleared it. Adding Astro's documented `data-astro-reload` attribute to that one form let the application submit handler prevent navigation. Reproduction:
+
+~~~sh
+npm run example:e01
+node test/uan023-browser-fallback.mjs
+~~~
+
+On Chrome 154.0.8037.95, `document.modelContext` was `undefined`. The page displayed the unavailable-agent fallback; human lookup returned `first-light`, returned `kind: missing` for an absent slug, and returned `blue-hour` after navigating About to Albums through ClientRouter. The URL stayed `/albums/` after form submissions, and page errors were empty. [Astro's ClientRouter form guidance](https://docs.astro.build/en/guides/view-transitions/#preventing-client-side-navigation) supports this form opt-out.
+
+**E02 on-demand Astro (Astro 7.3.5, `@astrojs/node@11.1.6`).** The fresh before-state `npm ci`, build, and its six baseline tests passed. The public [E02 source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e02-astro-on-demand-catalog/project/README.md) supplied the config, one registry/binding, HTTP/MCP endpoint files, browser entry, and live verification script. These files were copied into the existing site; then the public installation guide's exact MCP and Zod peers and the local package tarball were installed. The after-state Astro build and the copied public live HTTP/MCP verifier passed. The pre-existing ordinary JSON route still returned HTTP 200 for `night-bus-radio` and HTTP 404 for a missing slug. Seven unrelated source/data/asset files remained byte-identical.
+
+The E02 integration required a source-guided intervention: the public guide links to working source but does not yet give a complete copy/edit sequence for a stranger's own project. The verification script also uses a local fixture bearer token from that public example. This is reproducibility evidence for the public example patterns, not independent design of a new site or production identity integration.
+
+## Limits and remaining gates
+
+Inspector web is a genuine local MCP Apps iframe host; no commercial host, remote deployment, consent dialog, external identity provider, or arbitrary third-party MCP server was checked. Chrome's default session did not expose native WebMCP, so the browser result proves the human fallback and no native browser-agent registration. E01's sidecar origin was a local planning choice, not a running Worker. E02 relied on the linked public after-state source. UAN-023's full acceptance and npm release matrix remain open.

package/docs/evidence/UAN-023-native-webmcp-chrome.md

@@ -0,0 +1,44 @@
+# UAN-023 native WebMCP in Chrome 155
+
+Checked 2026-10-10 on macOS arm64 with Google Chrome 155.0.8059.39 (stable channel), Node 26.10.0 and npm 11.19.1. This is the first native WebMCP result for Agent Native. Earlier browser evidence used a simulated `document.modelContext`, and the [2026-10-03 probe](UAN-023-inspector-host-probe.md) found no native API in default Chrome 154.
+
+## Host and access
+
+Chrome ships WebMCP behind an opt-in. Chrome's [WebMCP documentation](https://developer.chrome.com/docs/ai/webmcp) names `chrome://flags/#enable-webmcp-testing` for local testing and an origin trial for sites. The probe launches a separate headless Chrome process with a temporary profile and `--enable-features=WebMCP`, the feature behind that flag. It does not touch any user browser profile. A second run without the feature confirms that default Chrome 155 still has no `document.modelContext`.
+
+With the feature on, Chrome exposes `document.modelContext` with `registerTool`, `getTools`, `executeTool`, `ontoolchange` and `when`. This matches the [current draft](https://webmachinelearning.github.io/webmcp/) that the adapter targets. On the host side, the experimental DevTools `WebMCP` domain reports `toolsAdded` and `toolsRemoved` and accepts `invokeTool`. Agent Native's own tests use the in-page API and that DevTools domain; an agent host would use the browser's own APIs. No AI agent, prompt or model was involved.
+
+## Reproduce
+
+```sh
+npm ci
+npm run example:e06
+npm run example:e01
+node test/uan023-native-webmcp.mjs
+```
+
+Set `CHROME_PATH` if Chrome is not at the default macOS location. The script serves the built E06 and E01 static output on loopback and asserts every outcome below.
+
+## Observed results
+
+| Example | Check | Result |
+| --- | --- | --- |
+| E06 | Default Chrome, no feature | No `document.modelContext`; the page shows its human-control fallback text |
+| E06 | `WebMCP.enable`, then load | `toolsAdded` reports `uan.15.example.browser.9.theme.set.v1` with the draft-2020-12 input schema and annotations `readOnly: false`, `consequential: false` |
+| E06 | Host `invokeTool` `{theme:"dark"}` | `Completed`; output `{ ok: true, capabilityId: "example.browser:theme.set@1", value: { theme: "dark" } }`; page theme changed |
+| E06 | Host `invokeTool` `{theme:"purple"}` | `Completed` with the safe `Capability input is invalid.` envelope; theme unchanged |
+| E06 | `pagehide` on the Window | The adapter's registration `AbortSignal` removed the native tool (`getTools()` count 1 to 0) |
+| E01 | Static Astro `/albums/` | One read tool `uan.15.example.catalog.12.album.lookup.v1`, `readOnlyHint: true`; page status says browser agent tools are available |
+| E01 | `executeTool` `first-light` / unknown slug | Found album and typed `{ kind: "missing" }` results |
+| E01 | Astro client navigation to `/about/`, then back | Tool removed on `/about/` (0 tools) and registered again on `/albums/` |
+
+## Change made from this evidence
+
+The draft and Chrome define the annotations `readOnlyHint`, `untrustedContentHint` and `consequentialHint`. The browser adapter previously sent MCP's `destructiveHint`, which Chrome silently dropped, so a destructive capability reached Chrome with no risk hint. The adapter now sets `consequentialHint` for `risk: 'destructive'` capabilities and keeps `readOnlyHint` for reads. The MCP adapter keeps MCP's own `destructiveHint`. Destructive browser tools still require explicit exposure and per-call authorization. The new annotation is unit-tested with the simulated API, because neither E06 nor E01 has a destructive browser tool.
+
+## Limits
+
+- Native WebMCP was verified only in Chrome 155 with the opt-in feature. Default Chrome, other browsers and origin-trial tokens were not tested.
+- Calls came from Chrome's DevTools protocol, not from a shipping browser agent. Agent consent, prompting and tool selection are untested.
+- Leaving a document by full navigation produced no `toolsRemoved` DevTools event within five seconds. The document is discarded, and the adapter's `pagehide` cleanup was verified separately.
+- Commercial MCP and MCP Apps hosts remain unverified.

package/docs/evidence/UAN-024-release-readiness-2026-10-10.md

@@ -0,0 +1,33 @@
+# UAN-024 release-readiness update (2026-10-10)
+
+This page supersedes the open rows in the [2026-10-03 snapshot](UAN-024-release-readiness.md), which stays as a dated record. The package is published as `0.1.1`. Every UAN acceptance item now has evidence or a recorded scope limit.
+
+## Closed since the earlier snapshot
+
+| Earlier open item | Current evidence |
+| --- | --- |
+| UAN-020 vulnerability contact and support limits | GitHub private vulnerability reporting is enabled ([release handoff](../release-handoff.md)). Limits are in [support limits](../support-and-limitations.md) and the [operational failure-safety evidence](UAN-020-operational-failure-safety.md) |
+| UAN-021/023 rendered MCP Apps, clean-context adoption and native WebMCP | [Inspector MCP Apps and Astro adoption](UAN-023-inspector-web-and-astro-adoption.md) and [native Chrome 155 WebMCP](UAN-023-native-webmcp-chrome.md) |
+| UAN-022 Windows/Linux CLI, timing and license inventory | [Portability](UAN-022-package-portability.md), [overhead](UAN-022-overhead-license-audit.md) and the [cross-platform license and notice review](UAN-022-cross-platform-license-notices.md) |
+| Astro advisory | [2026-10-10 recheck](GHSA-ch52-4w7c-c8xp-2026-10-10.md): disputed upstream with no fix; Astro does not call the affected method |
+| Final candidate artifact | The `0.1.1` registry tarball (SHA-256 `a1ce884f…8fbb`) matches the reviewed archive for source `ab79aed`, and a clean registry install passed ([harness release evidence](codex-harness.md#registry-release---2026-10-05)) |
+| UAN-002 house style | [House TypeScript style review](UAN-002-house-style-review.md) |
+| UAN-018 converter parity | E12 now has local, browser and server bindings. Its HTTP route returns the same results as the local and browser bindings, and invalid input returns 422 |
+| UAN-021 exports outside workspace paths | `npm run check:isolated-examples` copies every exported example to a temporary directory outside the repository. It confirms there is no `node_modules` above that directory and that the package resolves to the copy's own install. It then runs `npm ci` and the example's checks there. All twelve passed locally, and CI runs it on Node 24 |
+| UAN-023 flagship CLI from one definition | E04's application-owned CLI reuses the shared E01 contract and calls the sidecar remotely. Together, E01, E04 and E09 give the flagship browser, HTTP/OpenAPI, MCP, CLI and MCP Apps surfaces from one definition |
+
+## Acceptance row ledger
+
+| Row | Evidence | Disposition |
+| --- | --- | --- |
+| A19 sidecar routing and revision | Packed E04 route, origin, revision and protocol checks on local workerd | Passed locally. A live provider address and rollback belong to the deploying application |
+| A23 docs/example coverage | The coverage manifest, source-region and link checks, and isolated example exports | Passed |
+| A26 provider provisioning guard | Init plans only local edits and never provisions | Passed |
+| A27 real-host compatibility | Inspector 2.8.0 MCP Apps, Chrome 155 native WebMCP with the opt-in feature, and [Antigravity CLI and Claude Code invoking the flagship tool over MCP](UAN-023-commercial-agent-hosts.md) | Passed for named hosts. MCP Apps rendering in commercial hosts and shipping browser agents are unverified and not claimed |
+| A28 independent checks | Node 22/24 CI on every pushed commit | Passed |
+| A29 packed install | The 0.1.1 registry install, and examples installed outside the repository | Passed |
+| A30 CLI platform smoke | macOS and Linux CI packed CLI, plus the Windows packed CLI in a path with spaces | Passed |
+
+## Not claimed
+
+Native WebMCP in default browsers, MCP Apps rendering in commercial hosts, provider deployments, and external identity providers. The changes listed under 0.1.2 in the changelog ship in that release.

package/docs/evidence/UAN-024-release-readiness.md

@@ -0,0 +1,41 @@
+# UAN-024 release-readiness audit update
+
+Snapshot: 2026-10-03 07:05 UTC, public source `79f7e4ea8324ed616d83c04715a1eaf4dd175144`. This note updates the earlier isolated audit at `8a502b5`; it does not certify a release or include later commits. No package version/visibility, npm registry, provider deployment, or DNS state was changed for this update.
+
+## Confirmed repairs
+
+| Earlier finding | Current observation at this snapshot |
+| --- | --- |
+| A clean pack omitted `dist` and all 36 export targets. | `fc4e4e2` added `prepack: npm run build`. A separate clean clone of `79f7e4e` ran `npm ci` then normal `npm pack --dry-run --json` and reported 124 files, a 127,308-byte tarball and 36/36 declared export target paths. This is a dry-run file-list check, not an immutable release tarball or digest. |
+| The Worker E04 MCP path returned HTTP 500. | `24c8bab` gives the Workerd JSON Schema validator a mutable copy before it annotates schemas. A fresh packed E04 run passed its nine fixture tests, bundle/host/origin/CORS checks and official MCP client roundtrip. |
+| Integration CI was red. | [Run 37104609091](https://github.com/uppercut-labs/agent-native/actions/runs/37104609091) passed `npm run check` and `npm pack --dry-run --json` in both Node 22 and Node 24 jobs for the exact `79f7e4e` SHA. This is the broad integration result; no duplicate full suite was run for this documentation update. |
+
+The manifest names `@uppercut-labs/agent-native`, points to the public Uppercut Labs repository, and declares MIT; [LICENSE](../../LICENSE) credits Devin Thomas. `npm view @uppercut-labs/agent-native version --registry https://registry.npmjs.org/` returned E404 on 2026-10-03 07:04 UTC. That response means the target is not publicly readable at that moment; it does not reserve the name or prove publish permissions. The manifest remains `private: true` at `0.0.0`.
+
+## Evidence still needed for v1 acceptance
+
+1. **Complete UAN-020.** The [negative security fixtures](UAN-020-negative-security-fixtures.md) and later failure-safety work are valuable local evidence. A maintainer-approved private vulnerability contact is still absent from [SECURITY.md](https://github.com/uppercut-labs/agent-native/blob/main/SECURITY.md). Provider auth, grant persistence, cache isolation, CSP/iframe behavior and timeout handling need their exact supported boundaries recorded.
+2. **Complete UAN-021/023 documentation and real-host evidence.** The [coverage manifest](https://github.com/uppercut-labs/agent-native/blob/main/docs-site/coverage.json) links E01-E12 to guides and negative probes, while the [named Inspector CLI probe](UAN-023-inspector-host-probe.md) proves a real Streamable HTTP client, not rendered MCP Apps interaction. Clean-context Astro adoption and native WebMCP host behavior remain open at this snapshot. The default Chrome probe did not expose `document.modelContext`.
+3. **Complete UAN-022 portability.** [Measured macOS package evidence](UAN-022-package-portability.md) and the green Linux CI matrix cover several pieces. Windows/Linux representative installed CLI use, cold doctor/invocation timing, license inventory and consumer bundle budgets need a final support decision. A CI runner is not a Windows or production provider host.
+4. **Assess the Astro dependency advisory.** The lockfile resolves `astro@7.3.5` and `http-cache-semantics@4.2.0`. [GHSA-ch52-4w7c-c8xp](https://github.com/advisories/GHSA-ch52-4w7c-c8xp) lists versions through 4.2.0 as affected and no patched version as of this snapshot; `npm view http-cache-semantics version` returned 4.2.0. The earlier `npm audit --omit=dev --audit-level=high` found no production dependency vulnerability. Decide and document impact/mitigation for the Astro integration path before claiming a hosted support tier.
+5. **Make a final candidate artifact and provider record.** The dry-run file list and CI do not supply a tarball digest, dependency license report, published version, registry install, or live deployment. Use the [release and provider handoff](../release-handoff.md) after the remaining gates pass. The package has no `bin` entry or package-level `init` command; a programmatic v1 scope would need an explicit acceptance decision.
+
+## Acceptance row ledger
+
+The internal acceptance matrix is planning context; these public results are scoped to the cited source snapshot.
+
+| Row | Current evidence | Release disposition |
+| --- | --- | --- |
+| A19 sidecar routing and revision (R21) | Packed E04 route, origin and protocol fixture passed. | Live provider address and rollback remain unverified. |
+| A23 docs/example coverage (R18) | Coverage manifest resolves twelve examples; the current docs build checks links. | Guide prerequisites, expected output and independent adoption review remain open. |
+| A26 provider provisioning guard (R21) | Programmatic init plans local project edits and does not provision an account. | Provider handoff remains an application operation. |
+| A27 real-host compatibility (R22) | Named Inspector CLI 2.8.0 exchanged MCP requests. | Rendered MCP Apps and native WebMCP host behavior remain open. |
+| A28 independent checks (R23) | Node 22/24 CI passed on this SHA. | Re-run once on the final release candidate SHA. |
+| A29 packed install (R24) | Existing examples and core/browser portability check use fresh local tarballs; clean pack contains all exports. | Final immutable candidate and outside-repository release install remain open. |
+| A30 CLI platform smoke (R24) | macOS Node/Hono CLI fixture passed; Linux CI runs examples. | Representative Windows/Linux installed CLI invocation remains open. |
+
+## Documentation output in this slice
+
+[CHANGELOG.md](https://github.com/uppercut-labs/agent-native/blob/main/CHANGELOG.md) records unreleased work and states there is no prior npm migration path. [CONTRIBUTING.md](https://github.com/uppercut-labs/agent-native/blob/main/CONTRIBUTING.md) describes scoped verification and private-data handling. The [release handoff](../release-handoff.md) maps package release steps and application-owned native-provider work without inventing a hosted service or a support address.
+
+This is a release preparation checkpoint. UAN-024 remains open until all mandatory evidence is complete or a specific unsupported scope is explicitly accepted by the maintainer, and the final artifact is tied to a source commit.

package/docs/evidence/codex-harness.md

@@ -0,0 +1,56 @@
+# Codex harness evidence
+
+Checked 2026-10-04 (America/Chicago), with the real proof completed at
+`2026-10-05T03:50:19.168Z`; fresh-tarball inference passed at
+`2026-10-05T03:56:16.489Z`. This records one local runtime/model route, not all CLI
+versions, accounts, models or cloud targets.
+
+| Component | Tested value |
+| --- | --- |
+| Local Node | 24.18.0; package floor Node 22 |
+| Codex CLI/app-server | 0.145.0, stdio transport |
+| Authentication | Codex-managed ChatGPT sign-in; no Platform API-key fallback |
+| Model | gpt-5.6-luna, selected from this runtime's model/list catalog |
+| Effort | low |
+| Sandbox | workspace-write, disposable local directory |
+| Result | Both exact file checks passed; same thread resumed through a new process |
+| Cleanup | Both owned app-server processes closed; temporary workspace removed |
+
+Generated protocol schemas from the installed CLI were inspected before implementation.
+Official sources: [app-server](https://developers.openai.com/codex/app-server/) and
+[authentication](https://developers.openai.com/codex/auth/). The adapter uses managed
+CLI login rather than application-owned external token injection. No identity,
+plan detail, session ID, credential or raw provider transcript is included here.
+
+The real proof created `proof.txt` with `hello world`, closed the original process,
+read/resumed the same persisted thread in another process and changed the file to
+`hello Codex`. File contents and resume identity were verified by the runner, rather
+than inferred from model output. Usage updates were snapshots, not billed-cost evidence.
+The opt-in runner is `npm run proof:codex -- --model gpt-5.6-luna`; regular package
+checks use synthetic protocol processes only.
+
+Fresh packed-consumer acceptance verifies all export targets exist and imports
+root/browser/harness/bridge/Codex without optional SDKs. Its missing-runtime probe
+checks actionable guidance without launching inference. Provider fixtures test
+interrupt, failures, wrong auth, malformed protocol, deadlines, concurrent turns,
+workspace ownership, cross-process resume, permission denial and owned cleanup.
+
+The checks above record pre-release source/tarball acceptance. Cursor local/cloud
+acceptance remains pending. Codex programmatic MCP configuration and cloud
+operation are not advertised by this adapter.
+
+## Registry release - 2026-10-05
+
+[`@uppercut-labs/agent-native@0.1.1`](https://www.npmjs.com/package/@uppercut-labs/agent-native/v/0.1.1)
+is published and npm `latest` resolves to 0.1.1. Its registry download matches the
+reviewed GitHub release archive byte-for-byte: SHA-256
+`a1ce884f89eadba319d6fbad5c9b09b05575a7ab15998bcfd4a6ad8cc8228fbb`, source
+`ab79aed4b8556752b33286f2edf261a07b3921d1`, 168772 bytes / 152 files.
+
+A fresh consumer installed this exact version from npm, imported root/browser/Codex
+without optional peers and verified actionable missing-runtime guidance without
+inference. The equivalent GitHub archive had already passed the installed reusable
+two-turn proof with Node 24.19.0 / Codex CLI 0.145.0 / gpt-5.6-luna, same-session
+cross-process resume and owned cleanup. No additional inference was needed to
+verify the identical registry bytes. The checksum-verified GitHub route remains
+available when a registry cannot be reached.

package/docs/evidence/gate-2-domain-expansion.md

@@ -0,0 +1,35 @@
+# Real integration: Domain Expansion
+
+Checked 2026-10-11. Domain Expansion is an owner-only domain portfolio app on a Cloudflare Worker with Neon Postgres. Its source is the public [uppercut-labs/domain-expansion](https://github.com/uppercut-labs/domain-expansion) repository. It serves Agent Native capabilities as remote MCP at `https://domains.uppercut-labs.com/mcp`. This was the first integration outside the repository's fixtures.
+
+## What it exercises
+
+- Five protected capabilities (`domains.list`, `domains.get`, `renewals.upcoming`, `domains.create`, `domains.update`) and a destructive `domains.delete` with no MCP exposure.
+- The application's own personal tokens act as the bearer credential and the persisted grant, through `bearerAuth`, `resolveTrustedPrincipal`, `GrantStorePort` and `authorizeResource`.
+- Bindings call the application's existing REST services, so validation, revisions, idempotency and rate limits are shared with its API and CLI.
+
+## Results
+
+| Check | Where | Result |
+| --- | --- | --- |
+| Official SDK client discovery and calls | Deployed | Pass; protocol 2025-11-25 |
+| Typed outcomes: found and not found, stale revision, duplicate name | Deployed | Pass |
+| Invalid input rejected before the binding | Deployed | Pass |
+| No token: 401 with `WWW-Authenticate: Bearer`; bad token: 401; foreign Origin: 403 (application check) | Deployed | Pass |
+| A read-only token lists only read tools; a revoked token is refused on the next call | Local, official SDK | Pass |
+| Delete neither listed nor callable | Deployed | Pass |
+| Real host | Deployed | Claude Code 2.1.285 listed the tools and read real data without changes |
+| Rollback to the previous Worker version and back | Deployed | Pass |
+| Other MCP hosts; MCP OAuth | — | Not tested |
+
+## Findings fixed for 1.0
+
+The integration ran on 0.1.3, and these changes came out of it:
+
+- Bindings receive `context.caller`.
+- Protected-only servers challenge requests that have no token.
+- The adapter has `onToolFailure` and `toolName` options.
+- The Zod peer accepts the 4.6.x patch line.
+- The MCP guide documents the Workers stream lifecycle.
+
+The application was then rebuilt on the packed 1.0 candidate. Its MCP tests and its Worker smoke test under workerd passed. See [upgrading from 0.1.x](../upgrading-to-1.0.md).

package/docs/evidence/recovery-and-selection-recipes-2026-10-15.md

@@ -0,0 +1,63 @@
+# Recovery and executor-selection recipes
+
+Verified October 15, 2026 against the Agent Native 1.0.1 implementation. These
+application examples extend E07 and E11 without changing package runtime code,
+stable declarations, transport envelopes, tool naming or authorization policy.
+
+## Protected write recovery
+
+E07's `src/recovery.mjs` defines a protected write and protected status read. The
+application reserves an idempotency key scoped to subject and tenant in a local
+file journal. Its write deliberately ignores abort and waits for a deferred
+commit. The test advances the adapter deadline with Node mock timers, observes
+the existing uncertain-write warning and one handler invocation, then reads
+pending status. Releasing the original write produces committed status and one
+persisted commit. Reopening the journal retains that state.
+
+Negative paths cover missing status, an unauthorized reader, an explicitly
+resubmitted matching key while pending and committed, and a conflicting value.
+Explicit duplicate requests do not create another mutation. Sentinel assertions
+check that the timeout and denied read expose no protected value. The demo makes
+only one write invocation, reconciling its outcome through status reads.
+
+## Exact selection and private diagnostics
+
+E11's `src/executor-selection.mjs` distinguishes `invalid-identity`,
+`capability-missing`, `binding-unavailable` and `binding-ambiguous` before any
+handler runs. Explicit `bindingId: 'primary'` invokes one binding with separate
+namespace, name and major-version fields.
+
+The same executable uses the official MCP client/server SDKs with an in-process
+fetch transport. Its operator hook receives `handler-failed` and `invalid-output`
+with diagnostic observations. The client receives the existing bounded error.
+Neither operator events nor client results contain credential, input, output or
+exception sentinels. Hidden tools cannot be listed or called, and generated tool
+names remain distinct for separator-bearing identity pairs.
+
+## Verification
+
+On macOS with Node 26.9.0 and npm 11.19.1:
+
+- `npm run check` passed: 136 library tests, format/lint/type checks, API baseline,
+  browser proof, all twelve standalone exports, docs, portability and adoption.
+- After strengthening the no-retry counter assertion, `npm run example:e07`,
+  `npm run format:check`, `npm run lint` and `npm run docs:check` passed again.
+- `npm run check:isolated-examples -- e07-playlist-permissions e11-diagnostics-fault-lab`
+  passed independent installs, example tests and both executable demos outside
+  the repository, without ancestor dependencies.
+- The three new recipe tests passed against installed tarballs on Node 22.23.3
+  and 24.22.0 using `npm exec --package=node@22 -- node --test` and the equivalent
+  Node 24 command, with the exported E07 recovery and E11 selection test paths.
+
+The existing root CI runs the exports on Node 22 and 24. The isolated runner also
+executes both demos. Source-backed snippets in the guides are checked for drift.
+
+## Limits
+
+The file journal is a single-process fixture, not a production database or a
+cross-process/crash-safe transaction protocol. A real application owns operation
+identity, persistence, key retention, reconciliation and recovery. Missing or
+pending status does not authorize blind replay. No exactly-once guarantee or
+rollback on timeout is supplied by Agent Native. No paid model trials, model
+efficacy measurement, commercial host verification or production deployment is
+claimed by these deterministic checks.

package/docs/for-agents.md

@@ -0,0 +1,50 @@
+# Let a coding agent integrate Agent Native
+
+The quickest way to make an existing website agent-native is to give a coding agent the **website repository** and a bounded, source-grounded task. Agent Native provides **application capabilities**, not a turnkey chat overlay or magic remote execution of a site.
+
+Canonical source assets: [portable skill](../skill/agent-native/SKILL.md),
+[adapter selection](../skill/agent-native/references/adapter-decision.md),
+[verification](../skill/agent-native/references/verification.md),
+[full prompt](../agent/agent-prompt.md), and [short prompt](../agent/agent-prompt-short.md).
+
+For local skill installation, keep `SKILL.md` and both reference files together:
+
+```text
+agent-native/
+  SKILL.md
+  references/
+    adapter-decision.md
+    verification.md
+```
+
+The npm package includes this folder under
+`node_modules/@uppercut-labs/agent-native/skill/agent-native/` starting in 1.0.1.
+Copy the whole folder into your coding agent’s skill directory. Downloading only
+`SKILL.md` requires fetching its two linked references as well. The standalone prompt
+is a single file.
+
+There are two independent instructions paths:
+
+- **Portable Agent Native skill:** a short `SKILL.md` for agents supporting portable Agent Skills format, with optional references for adapter selection and verification. Read the skill source from the public package, or download the canonical asset from Uppercut's documentation host when that route is available.
+- **Standalone agent prompt:** copy/paste text for any coding agent with repository access. It includes necessary behavior without requiring a skill/plugin installation.
+
+**Documentation downloads:** `https://docs.uppercut-labs.com/agent-native/skill/agent-native/SKILL.md` and `https://docs.uppercut-labs.com/agent-native/agent-prompt.md`. The installed npm package and public package repository contain the same canonical assets.
+
+## What the agent should accomplish
+
+1. Read the site's repository instructions, package manifest, lockfile, actual entry points, framework/runtime, tests, auth and human workflows. Treat a user-named stack or host as an acceptance condition: verify it against these sources, explain any mismatch and follow the explicit request.
+2. Choose a real existing public read, not arbitrary generated demo logic, and create a typed capability with honest risk/access.
+3. Bind the unchanged application function in a checked registry and enforce authorization every call.
+4. Expose one real HTTP or official MCP surface with the correct runtime and optional dependencies. A static site cannot run dynamic MCP unaided.
+5. Verify one allowed call, one schema rejection before the handler, one denial/hidden path and an unchanged human UI.
+6. Report changed files, versions, observed commands/results and remaining hosting/identity responsibilities.
+
+Do not claim that the 1.0.1 library includes a global `agent-native init` executable, production identity service, default-enabled browser WebMCP or verified commercial MCP Apps host rendering. Review [support and limitations](support-and-limitations.md).
+
+## If the agent only has public docs
+
+Start with [adopt an existing site](adopt-existing-site.md), [install the published package](installation.md), and [E10 unchanged-function retrofit](https://github.com/uppercut-labs/agent-native/tree/main/examples/e10-existing-functions-retrofit). For remote operations use [HTTP](http.md) or [MCP](mcp.md) according to app runtime. For authenticated operations read [permissions and discovery](permissions-and-discovery.md), with a real trusted auth source and record policy. Never paste user tokens into chat or code.
+
+## What the agent does **not** gain
+
+The skill and prompt are just text. They do not give a coding agent automatic GitHub access, credentials, permission to deploy, cross-tenant record authorization or a general hosted MCP endpoint. The integrating owner must grant the agent appropriate repository/test access separately and approve production actions. The report must distinguish a local capability run, local protocol integration and live host verification.

package/docs/frameworks.md

@@ -0,0 +1,62 @@
+# Framework support
+
+To wrap a working site’s existing operation, follow [adopt an existing site](adopt-existing-site.md).
+
+This table records framework surfaces actually built and checked in this package. It is not a
+compatibility promise for every release in a listed major version.
+
+| Framework | Supported shape | Verified environment | Boundary |
+| --- | --- | --- | --- |
+| Astro | Static browser bootstrap or application-owned on-demand HTTP/MCP routes | Astro 7.3.5, `@astrojs/node` 11.1.6, Node 22.12+ fixtures | Integration installs no adapter; on-demand mode requires a supported application adapter |
+| Next App Router | App-owned HTTP/MCP route factories on the Node runtime | Next 16.3.8 E03; official MCP 2.3.0 client | Experimental adapter; keep registry server-only; local fixture only |
+| Cloudflare Worker sidecar (runtime) | Separate dynamic HTTP/MCP server while Astro stays static | E04 local workerd fixture; see [static sites](static-sites.md) | No deployment or DNS claim; configure Host/Origin/CORS in the sidecar |
+| Hono | One Node application mounting the Web-standard HTTP and MCP handlers | Hono 4.13.12, `@hono/node-server` 2.1.3, Node 22+ E05 fixture | Loopback lab host; no provider deployment or production identity integration |
+
+The Astro integration uses the documented `astro:config:setup` page-script injection hook and
+`astro:config:done` output diagnostic. `mode: 'on-demand'` permits Astro's server build mode while
+the application owns its routes and adapter; it does not create either. E01 preserves a wholly
+static build. E02 preserves prerendered pages and human navigation while live `/agent-native/v1/*`
+and `/mcp` routes reuse the framework-neutral HTTP/MCP handlers.
+
+The experimental [existing-project init](getting-started.md) can patch only an Astro config with
+the recognized literal static shape. It records a reviewed sidecar origin and generates a browser
+entry, then verifies the built E01 site from a local package tarball. More complex Astro config,
+on-demand configs, and other frameworks require manual integration. Detection reports on-demand
+routes, a missing server adapter, and protocol-looking static files; it never recommends the
+historical `output: 'hybrid'` value.
+
+The browser capability host remains experimental. E01 exercises a simulated WebMCP API in Node
+tests, not a real browser or agent. Other Astro releases, deployment providers, and
+real-host WebMCP behavior are unverified. E02 proves only the pinned local Node standalone adapter;
+it is not a claim about other adapters or external hosts.
+
+E05 follows Hono's official Node adapter shape: the Hono router receives Fetch API requests and
+`@hono/node-server` owns the Node HTTP socket. The package's `createHttpHandler` and
+`createMcpHandler` remain framework-neutral and are mounted into the same Hono app. The fixture
+checks HTTP and the official MCP client against one registry, binds loopback by default, and handles
+SIGINT/SIGTERM and listen errors. This verifies the pinned fixture only, not every Hono release or a
+deployed host.
+
+Astro references: [integration hooks](https://docs.astro.build/en/reference/integrations-reference/)
+and [ClientRouter lifecycle](https://docs.astro.build/en/guides/view-transitions/).
+Hono reference: [official Node.js adapter guide](https://hono.dev/docs/getting-started/nodejs).
+
+## Verify the Hono mount
+
+With Node.js 22 or newer, run `npm ci` and `npm run example:e05` from the package root.
+The standalone export mounts the package HTTP and MCP handlers into one pinned Hono app:
+
+<!-- source:examples/e05-node-cli/project/src/server.mjs#hono-routes -->
+~~~js
+app.all('/agent-native/*', (context) => httpHandler(context.req.raw));
+app.all('/mcp', (context) => mcpHandler(context.req.raw));
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e05-node-cli/project/src/server.mjs#L11)
+<!-- /source -->
+
+The harness checks the ordinary HTTP result and an official MCP client call on loopback.
+If the listen address is occupied, stop the other process or choose another `PORT`; the
+fixture reports `server_error=address-in-use`. See the
+[E05 application instructions](https://github.com/uppercut-labs/agent-native/blob/main/examples/e05-node-cli/project/README.md) for local
+start, stop, and shell-only credential cleanup.

package/docs/getting-started.md

@@ -0,0 +1,109 @@
+# Optional programmatic Astro static init
+
+For the general adoption path, begin with [adopt an existing site](adopt-existing-site.md).
+This optional guide handles only a narrowly recognized static Astro configuration.
+
+The `@uppercut-labs/agent-native/init` entrypoint is available in the
+`1.0.1` package. There is no `agent-native init` executable yet. Use the E01 fixture to try the current
+programmatic flow from a local package tarball:
+
+```sh
+npm ci
+npm run example:e01
+```
+
+E01 copies an existing static Astro site into a temporary directory, installs a
+local tarball, applies a reviewed plan, and builds the site. It checks the
+original pages, routes, assets, data, and lockfile preservation after installation.
+
+## Plan before applying
+
+The supported automatic edit is intentionally narrow: an Astro project with a
+single, literal `defineConfig({ output: 'static' })` configuration. Detection
+reads project files as data; it does not import the site's config or business
+modules. A project with multiple apps, competing lockfiles, dynamic config, or
+an unsupported host receives an unresolved action instead of a guessed edit.
+
+Detection also distinguishes pure static output from `prerender = false` on-demand routes. It
+records whether the Astro config has a server adapter, diagnoses `server-adapter-missing`, and
+rejects static files placed at known HTTP/MCP protocol paths. Existing on-demand projects are
+manual-integration cases: init does not rewrite their adapter or endpoint routes. Select a sidecar
+for a pure static site, or review same-origin endpoints and a supported adapter explicitly. Never
+rewrite an Astro 7 project to the removed historical `output: 'hybrid'` mode.
+
+After installing this source package into a disposable Astro project, a caller
+can inspect the plan and then explicitly approve the same choices:
+
+```js
+import { applyInitPlan, createInitPlan, restoreInit } from '@uppercut-labs/agent-native/init';
+
+const projectRoot = '/absolute/path/to/existing-astro-site';
+const choices = {
+  hosting: 'cloudflare',
+  routeMode: 'sidecar',
+  sidecarOrigin: 'https://your-worker.example',
+};
+const plan = await createInitPlan(projectRoot, {}, choices);
+console.log(plan);
+
+// Review detection, unresolved actions, proposed files, and choices first.
+const result = await applyInitPlan(projectRoot, plan, choices, { approved: true });
+console.log(result);
+
+// Later, if the generated files are unchanged:
+// await restoreInit(projectRoot);
+```
+
+The plan digest binds detected evidence, overrides, and selected choices.
+Apply rechecks that evidence and refuses a stale plan. A second init is a
+no-op. Restore checks ownership and content digests before changing any file;
+it reports a conflict if a generated file was edited. Keep the ownership file
+at `.agent-native/ownership.json` with the project until restoration is no
+longer needed.
+
+## What this slice creates
+
+The installer patches the recognized Astro config to inject
+`.agent-native/browser-entry.mjs` as a page script and writes
+`.agent-native/init.json` with the selected mode and sidecar origin. The browser
+entry emits an `agent-native:ready` event. It does not discover site functions,
+register a capability, create a server route, deploy a Worker, or edit the
+project's dependencies or lockfile. Bind only reviewed application operations
+using the [capability guide](capabilities-and-bindings.md), and use the
+[static-site guide](static-sites.md) for the separate Worker example.
+
+After init, these steps remain yours:
+
+1. Install what you import: `@uppercut-labs/agent-native`, `zod@4.6.5` for the schema adapter,
+   and `@modelcontextprotocol/server@2.3.0` if you expose MCP ([installation](installation.md)).
+2. Define capabilities and bind them to reviewed application operations.
+3. Pass an authorization port on every execution, including public reads.
+4. Add and deploy the server route or Worker sidecar if you expose HTTP or MCP.
+5. Test discovery, one successful call and one denied or invalid call before you publish.
+
+E01's installed after-state explicitly executes its public album lookup through the shared
+registry and authorization port. Init does not generate this application code:
+
+<!-- source:examples/e01-album-catalog/project/src/catalog.mjs#local-album-execution -->
+~~~js
+/** @param {unknown} input */
+export function runAlbumLookup(input) {
+  return executeCapability(registry, {
+    identity: getAlbumCapability.identity,
+    runtime: 'local',
+    input,
+    caller: { kind: 'anonymous' },
+    authorization: publicReadAuthorization,
+  });
+}
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e01-album-catalog/project/src/catalog.mjs#L36)
+<!-- /source -->
+
+The `npm run example:e01` export uses Node.js 22 or newer and a root `npm ci`. It builds the
+static site and checks found/missing results. A malformed album slug is rejected before the
+handler runs; correct the slug and retry. See the [E01 project instructions](https://github.com/uppercut-labs/agent-native/blob/main/examples/e01-album-catalog/project/README.md).
+
+The current init API is a tested foundation for a later interactive CLI.
+It is not a production deployment or a browser-agent host test.