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

package/docs/adopt-existing-site.md

@@ -0,0 +1,189 @@
+# Make an existing website agent-native
+
+**Target:** Agent Native 1.0.1 · Node.js 22+ · an existing JavaScript/TypeScript website.
+**Result:** A real operation the website already supports, available to an agent over an actual HTTP and/or MCP server surface, with the same input checks and explicit authorization the application expects.
+
+Agent Native is not a chatbot widget or an automatic site conversion tool. It defines reusable operations that software—including suitable agents—can discover and invoke through selected adapters. Your existing pages, functions and ownership rules remain your responsibility.
+
+## 1. Identify one operation your website already provides
+
+Choose something low risk: search public content, retrieve an album, list public catalog entries, or convert a value. Find the *existing function* your website already calls. Prefer a public read on your first pass, not user-specific private data or an update/delete. Record the input/output shape and whether an ordinary visitor is entitled to the result.
+
+A representative complete example is [E10 existing functions retrofit](https://github.com/uppercut-labs/agent-native/tree/main/examples/e10-existing-functions-retrofit). It leaves an existing `searchContent({query, limit})` function intact, defines a typed Agent Native capability around it, and preserves the site's established `GET /api/content/search` shape. It is much closer to a real integration than inventing a new `greet` operation.
+
+Compare any user-named stack or host with the package manifest, lockfile, actual entry point, and build/deployment configuration. Explain a mismatch and follow the explicit request; then choose an adapter for the website's actual execution model:
+
+| Your website | How remote agents call it | Example and limitation |
+| --- | --- | --- |
+| Existing Node/Hono server | Mount a standard Web `Request`/`Response` HTTP or MCP handler in your current router | [E05](https://github.com/uppercut-labs/agent-native/tree/main/examples/e05-node-cli); app must provide TLS/auth/rate limits |
+| Next.js App Router | Use package `/next` route factory on Node runtime | [E03](https://github.com/uppercut-labs/agent-native/tree/main/examples/e03-next-reading-list); keep registry server-only |
+| Astro on-demand | Add app-owned endpoints with an existing compatible server adapter | [E02](https://github.com/uppercut-labs/agent-native/tree/main/examples/e02-astro-on-demand-catalog); do not silently change output modes |
+| Astro fully static | Use a separate Worker/sidecar server for HTTP/MCP while leaving site prerendered | [E01/E04](https://github.com/uppercut-labs/agent-native/tree/main/examples); static HTML cannot answer a dynamic remote MCP request by itself |
+| Browser-local only | Optional WebMCP browser registration with ordinary human fallback | [E06](https://github.com/uppercut-labs/agent-native/tree/main/examples/e06-browser-only-theme-controls); draft browser API, not universal host support |
+
+## 2. Install the version you can actually test
+
+In the consuming website repository with Node 22 or later, install the public package:
+
+```sh
+npm install @uppercut-labs/agent-native@1.0.1
+npm install zod@4.6.5
+```
+
+Zod is only needed if you use the `/schema/zod` adapter. Check the app’s current pin
+first; an incompatible schema peer can stay isolated in the separate sidecar instead
+of silently changing the existing website’s dependencies. To serve MCP, add the tested official server SDK peer separately:
+
+```sh
+npm install @modelcontextprotocol/server@2.3.0
+```
+
+For official client verification, install `npm install --save-dev @modelcontextprotocol/client@2.3.0`.
+Import `Client` and `StreamableHTTPClientTransport` from `@modelcontextprotocol/client`;
+connect the transport to your actual mounted MCP URL, list tools, and call the expected
+capability with its schema-valid input. For Next, also install `server-only@0.0.1` and
+follow the [authorized route example](next.md).
+
+No package-level `agent-native` executable ships. The `@uppercut-labs/agent-native/init` import is an experimental, narrowly recognized programmatic Astro static retrofit; it does **not** automatically discover your business functions, publish a Worker or install a global `init` command. See [installation](installation.md) and [Astro init details](getting-started.md).
+
+## 3. Define and bind your **existing** function
+
+E10's [capability module](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/src/capability.mjs) is a runnable reference. It uses:
+
+- `defineCapability({identity, description, input, output, risk:'read', access:{kind:'public'}})` from `/contracts`;
+- `fromZod(z.object(...))` from `/schema/zod` for input and output contracts;
+- `bindCapability(capability, {id, targets:['local','server'], execute: existingFunction})` from `/registry`;
+- `createCapabilityRegistry([capability], [binding])` to check definitions and bindings.
+
+The tested definition, binding and public-read-only authorizer are:
+
+<!-- source:examples/e10-existing-functions-retrofit/project/src/capability.mjs#adoption-contract -->
+~~~js
+const contentItem = z.object({
+  slug: z.string(),
+  title: z.string(),
+  summary: z.string(),
+});
+
+export const searchContentCapability = defineCapability({
+  identity: { namespace: 'content', name: 'search', majorVersion: 1 },
+  description: 'Search the existing public content collection.',
+  input: fromZod(
+    z.object({
+      query: z.string().trim().min(1).max(80),
+      limit: z.number().int().min(1).max(10).optional(),
+    }),
+  ),
+  output: fromZod(
+    z.object({
+      query: z.string(),
+      results: z.array(contentItem),
+    }),
+  ),
+  risk: 'read',
+  access: { kind: 'public' },
+  surfaces: {
+    // docs:start http-get-override
+    http: {
+      path: '/api/content/search',
+      method: 'GET',
+      query: { query: 'q' },
+    },
+    // docs:end http-get-override
+    // docs:start cli-command-override
+    cli: {
+      command: 'content-search',
+      aliases: ['search'],
+    },
+    // docs:end cli-command-override
+  },
+});
+
+export const searchContentBinding = bindCapability(searchContentCapability, {
+  id: 'existing-content-search',
+  targets: ['local', 'server'],
+  execute: searchContent,
+});
+
+export const registry = createCapabilityRegistry([searchContentCapability], [searchContentBinding]);
+
+export const publicReadAuthorization = {
+  authorize(request) {
+    return request.risk === 'read' && request.access.kind === 'public';
+  },
+};
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/src/capability.mjs#L8)
+<!-- /source -->
+
+The example preserves an established GET route with the same contract, instead of inventing a duplicate endpoint:
+
+<!-- source:examples/e10-existing-functions-retrofit/project/src/capability.mjs#http-get-override -->
+~~~js
+http: {
+  path: '/api/content/search',
+  method: 'GET',
+  query: { query: 'q' },
+},
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/src/capability.mjs#L33)
+<!-- /source -->
+
+Identity namespace and name use lower-case slug segments separated by dots or hyphens,
+such as `{ namespace: 'blog', name: 'list-posts', majorVersion: 1 }`.
+
+For your own site, adapt the namespace/operation names and input/output schemas from the actual operation. A registry is not a permission policy: supply an application authorization port **on every execution**, even for explicitly public reads. The E10 sample authorizer permits exactly public reads. Do not copy it to a protected write or assume an unauthenticated visitor owns someone else's data. [Capabilities and bindings](capabilities-and-bindings.md) explains this boundary.
+
+## 4. Mount the agent surface in an actual server
+
+E10's [HTTP mount](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/src/http.mjs) wraps the same registry in `createHttpHandler` from `@uppercut-labs/agent-native/http`, supplying a caller and explicit `authorization` through `resolveExecutionContext`. It adapts the Web-standard handler to its pre-existing Node HTTP server and leaves unrelated `/api/health` and content routes intact.
+
+<!-- source:examples/e10-existing-functions-retrofit/project/src/http.mjs#adoption-http -->
+~~~js
+const generatedHandler = createHttpHandler(registry, {
+  resolveExecutionContext: () => ({
+    caller: { kind: 'anonymous' },
+    authorization: publicReadAuthorization,
+  }),
+});
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/src/http.mjs#L7)
+<!-- /source -->
+
+By default, public read capabilities may be invoked by `POST /agent-native/v1/capabilities/{namespace}/{name}/v{major}/invoke` and are described at `GET /agent-native/v1/openapi.json`; E10 demonstrates an approved GET override at the original path. The HTTP adapter in 1.0.1 exposes **only public reads**; user-specific or destructive operations are not automatically routable. See [HTTP/OpenAPI](http.md).
+
+For agent-native MCP clients, add the isolated `/mcp` adapter and mount it at a real `/mcp` route, with the host's request-specific authorization context. Use the official MCP server SDK and a compatible MCP client. Successful structured results appear under `structuredContent.result`. MCP protected discovery, scopes, revocable grants and per-resource authorization are covered in [remote MCP](mcp.md) and [permissions](permissions-and-discovery.md). **Do not turn on protected MCP in the beginner read-only sample without an actual verified identity source.**
+
+If your website has no server, select a separately deployed Worker or equivalent server to host those routes, wire CORS/host/origin carefully and keep the static site untouched. Local workerd evidence is not a claim that your DNS or production Worker was deployed. See [static sites](static-sites.md).
+
+## 5. Prove the behavior, including a refusal
+
+For the checked E10 example, run this in the *public package source repository* to export and exercise its independent copy:
+
+```sh
+npm ci
+npm run example:e10
+```
+
+To verify the published registry package independently, run `npm run check:adoption`.
+It installs the 1.0.0 compatibility baseline in a clean consumer, preserves the E10 domain function, runs its HTTP/CLI
+tests, and uses the official MCP client over an actual local socket. The client validates
+`structuredContent.result`, rejects invalid input before the function, and cannot discover
+or call a protected canary. This is maintainer loopback proof, not an outsider pilot.
+
+Inside the generated E10 project, the [README](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/README.md) documents `npm ci`, `npm test`, `npm run search -- --query night --limit 1`, `npm start` and `curl 'http://127.0.0.1:8788/api/content/search?q=night&limit=1'`. In this fixture, that URL returns its first search match. Missing query, a fractional limit or an empty CLI query fails input validation before executing the existing function. POST to the preserved read GET route returns `405` with `Allow: GET`; unrelated health and catalog routes remain available.
+
+For **your site**, perform the equivalent on its actual local server, not the package fixture. Record the operation name and version, URL/host, expected schema, valid result, malformed input failure, denied or hidden operation, and unchanged human website flow. For MCP, use a compatible client to list tools and call one (not a hand-built success assertion). If only local route tests passed, describe that honestly; deployed provider and live commercial-host claims require separate verification. See [compatibility](compatibility.md) and [support limits](support-and-limitations.md).
+
+## 6. Take it from local proof to a deployed project
+
+Your application owns deployment routing, TLS, Origin/Host/CORS rules, rate limits, credential verification, resource authorization, persistence, secret management, observability and rollback. Never put server SDKs, credential stores or private schemas in browser assets. Calls that time out may still have completed writes; don't retry a mutation blindly without a real idempotency contract and state check.
+
+Use [release/provider handoff](release-handoff.md) to plan actual host acceptance, and [doctor and troubleshooting](doctor-and-troubleshooting.md) if a binding/route is unavailable. Treat the current [stability](stability.md) and [support matrix](support-and-limitations.md) as release-specific.
+
+## Hand this to a coding agent
+
+For a repo-aware AI assistant, read [the agent integration guide](for-agents.md) and give it the portable skill or copyable prompt. Neither automatically grants access to the customer's site, deployment credentials or private operations.

package/docs/browser.md

@@ -0,0 +1,70 @@
+# Browser-local WebMCP
+
+Import the browser-only subpath so application browser bundles do not load HTTP or MCP server
+adapters:
+
+~~~ts
+import { createBrowserCapabilityAdapter } from '@uppercut-labs/agent-native/browser';
+
+const adapter = createBrowserCapabilityAdapter(document);
+const report = await adapter.sync(registry);
+~~~
+
+The adapter feature-detects the current draft API at document.modelContext. It registers
+capabilities only when the registry has exactly one browser binding. The WebMCP tool name is a
+deterministic length-coded projection of the capability identity and follows the draft's allowed
+ASCII character set and 128-character limit.
+
+By default, discovery includes only public read capabilities. An application may explicitly opt
+in to a protected page-local tool with canExpose; every execution still goes through the shared
+executor and the application's AuthorizationPort. resolveExecutionContext is read for each tool
+call, so authorization and identity are not captured as browser secrets. Resync after route or
+authentication changes to abort stale registrations and register the current projection.
+
+The adapter owns each registration with the WebMCP registerTool(tool, { signal }) AbortSignal.
+Calling dispose() or receiving pagehide on the document's owning Window aborts those
+registrations. Repeated adapter creation for the same Document returns the same adapter instance.
+The registration signal controls availability; WebMCP passes a separate execution signal to the
+tool callback. Revoked callbacks also reject retained references after a resync or dispose.
+
+The normal human interface should work when WebMCP is absent. E06 demonstrates this with a
+page-local theme action and no server fallback. E12 uses the same converter function through local
+and browser bindings. The lifecycle fixtures use a simulated API and are labeled as such. On
+2026-10-10, the built E06 and E01 pages also passed against native WebMCP in Chrome 155 with the
+opt-in `WebMCP` feature. That run covered host-side tool listing and invocation, invalid input,
+`pagehide` cleanup and Astro client navigation. See the
+[native Chrome evidence](evidence/UAN-023-native-webmcp-chrome.md). No shipping browser agent was tested.
+
+The API shape follows the current WebMCP draft at https://webmachinelearning.github.io/webmcp/.
+That draft exposes Document.modelContext.registerTool() in secure contexts, and the registration
+options accept an AbortSignal. Tool annotations follow the draft: read capabilities set
+`readOnlyHint` and destructive capabilities set `consequentialHint`. The only verified browser is
+Chrome 155 with WebMCP enabled through `chrome://flags/#enable-webmcp-testing` or an origin
+trial. Default Chrome does not expose the API, and no agent host is certified.
+
+## Verify the browser-only binding
+
+With Node.js 22 or newer, run `npm ci` and `npm run example:e06` from the package root.
+The exported page binds its theme action only to `browser`:
+
+<!-- source:examples/e06-browser-only-theme-controls/project/src/theme.mjs#browser-theme-binding -->
+~~~js
+const binding = bindCapability(capability, {
+  id: 'page-theme',
+  targets: ['browser'],
+  execute: async ({ theme }) => {
+    document.documentElement.dataset.theme = theme;
+    return { theme };
+  },
+});
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e06-browser-only-theme-controls/project/src/theme.mjs#L23)
+<!-- /source -->
+
+The simulated lifecycle test checks registration, protected invocation, disposal, and the
+ordinary button fallback. A server invocation fails with `binding-unavailable`; use a
+separate server binding only if the application actually implements one. See the
+[E06 standalone instructions](https://github.com/uppercut-labs/agent-native/blob/main/examples/e06-browser-only-theme-controls/project/README.md).
+The simulated fixture alone implies no native result; `node test/uan023-native-webmcp.mjs`
+repeats E06 and E01 in a locally installed Chrome with the feature enabled.

package/docs/capabilities-and-bindings.md

@@ -0,0 +1,141 @@
+# Capabilities and bindings
+
+Identity namespace and name are lower-case slug segments separated by dots or hyphens,
+with at most 64 characters each; majorVersion is a positive safe integer.
+
+A capability definition describes a versioned outcome and its runtime input/output contracts. It
+does not need an implementation. A binding supplies that implementation for named runtime
+targets. Definitions and bindings compose into an immutable checked registry; requests execute
+through the shared gateway.
+
+## Frozen authoring signatures
+
+The v0 authoring surface is exercised in the installable examples under `examples/`. Definitions
+require identity, description, input and output schema ports, risk, and access. Public access is
+allowed only for read capabilities. Protected access carries one or more scopes; it does not issue
+or persist grants.
+
+```ts
+defineCapability({
+  identity: { namespace: 'example.catalog', name: 'album.lookup', majorVersion: 1 },
+  description: 'Look up a public sample album by its slug.',
+  input: albumInput,
+  output: albumOutput,
+  risk: 'read',
+  access: { kind: 'public' },
+});
+```
+
+Each binding has a unique slug and one or more explicit targets: `browser`, `server`, or `local`.
+No runtime is inferred. A server-only binding is unavailable to a browser request. If multiple
+bindings match one capability and runtime, the caller must specify `bindingId`; otherwise execution
+returns a `binding-ambiguous` failure.
+
+Every execution request provides a runtime, caller, and `AuthorizationPort`. The binding receives that caller as `context.caller`, after authorization, so it can scope records to it. The executor validates
+input first, awaits `authorize` for every invocation, invokes only the selected binding after an
+allow result, then validates output. Authorization errors deny execution. Public-read examples
+implement their own explicit policy port; there is no implicit allow-all default. The port is the
+adopter's policy boundary, not a durable grant store or identity integration.
+
+The result is a discriminated `success` or `failure`. Failure reasons include invalid identity,
+missing capability, unavailable or ambiguous binding, invalid input, denied authorization,
+authorization error, invalid output, and handler failure. Each failure includes a stable
+`DiagnosticObservation` without input, output, credentials, or exception text.
+
+## Exact identity and explicit binding selection
+
+Run `npm run example:e11` at the repository root for an installed, executable
+[selection and diagnostics recipe](https://github.com/uppercut-labs/agent-native/blob/main/examples/e11-diagnostics-fault-lab/project/src/executor-selection.mjs).
+After exporting it, `npm run selection` in `examples/e11-diagnostics-fault-lab/.exported`
+repeats the sequence. Failed requests invoke no handler:
+
+| Request | Outcome |
+| --- | --- |
+| `name: 'example.selection binding.read'` | `invalid-identity` |
+| Valid identity with `name: 'missing'` | `capability-missing` |
+| Browser runtime with local-only bindings | `binding-unavailable` |
+| Local runtime with two bindings, no selection | `binding-ambiguous` |
+| Exact identity, local runtime, `bindingId: 'primary'` | Success, one handler call |
+
+<!-- source:examples/e11-diagnostics-fault-lab/project/src/executor-selection.mjs#select-binding -->
+~~~js
+const selected = await executeCapability(registry, {
+  identity: { namespace: 'example.selection', name: 'binding.read', majorVersion: 1 },
+  runtime: 'local',
+  bindingId: 'primary',
+  input: {},
+  caller: { kind: 'anonymous' },
+  authorization: publicRead,
+});
+assert.equal(selected.kind, 'success');
+assert.equal(selected.bindingId, 'primary');
+assert.deepEqual(selected.value, { value: 'primary' });
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e11-diagnostics-fault-lab/project/src/executor-selection.mjs#L65)
+<!-- /source -->
+
+Namespace, name and major version are separate fields. Never pass a display label or a
+space-separated phrase as the name, normalize it into another identity, or silently select
+the first binding. If an application exposes an executor wrapper with a fixed namespace,
+state that namespace in both its schema descriptions and tool description, give the valid
+name example `binding.read`, and reject combined labels. Expose a `bindingId` selection only
+when the application's contract permits it. The MCP adapter exposes capabilities with one
+server binding; it does not select between ambiguous bindings on behalf of a client.
+
+The same recipe exercises the [MCP operator failure hook](mcp.md#operator-failure-hook).
+Keep detailed reasons in a private operator sink; do not expose hidden capabilities or
+unredacted exceptions to diagnose generic client errors.
+
+## Runnable examples
+
+- [E01 domain execution slice](https://github.com/uppercut-labs/agent-native/blob/main/examples/e01-album-catalog/project/README.md) proves found and
+  missing album outcomes plus malformed-slug rejection through local execution.
+- [E12 shared unit converter](https://github.com/uppercut-labs/agent-native/blob/main/examples/e12-shared-unit-converter/project/README.md) proves the
+  converter through an explicit local binding and the same executor.
+
+Run `npm run example:e01` and `npm run example:e12` at the repository root for fresh tarball
+exports, independent installs, tests, and CLI output. These examples do not implement the full E01
+Astro retrofit or claim browser, MCP, HTTP/OpenAPI, or real-host support.
+
+## Tested source and first run
+
+With Node.js 22 or newer, run `npm ci` in the repository root, then
+`npm run example:e01` and `npm run example:e12`. E01 returns a found or missing album through
+the local executor; a malformed slug fails input validation before its handler runs. E12 prints
+a versioned JSON conversion result with `30.48 cm`; an unsupported unit returns
+`invalid-input` before the shared converter runs. See the [E01 project](https://github.com/uppercut-labs/agent-native/blob/main/examples/e01-album-catalog/project/README.md)
+and [E12 project](https://github.com/uppercut-labs/agent-native/blob/main/examples/e12-shared-unit-converter/project/README.md) for independent exports.
+
+E01 executes a registered album lookup with an explicit public-read policy:
+
+<!-- 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 -->
+
+E12 binds one conversion function to local and browser runtimes:
+
+<!-- source:examples/e12-shared-unit-converter/project/src/converter.mjs#shared-converter-bindings -->
+~~~js
+export const localConversionBinding = bindCapability(convertDistanceCapability, {
+  id: 'local-converter',
+  targets: ['local'],
+  execute: convertDistance,
+});
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e12-shared-unit-converter/project/src/converter.mjs#L44)
+<!-- /source -->

package/docs/cli.md

@@ -0,0 +1,88 @@
+# Generated CLI
+
+This slice exports a runner from the separate `@uppercut-labs/agent-native/cli` entrypoint and includes runnable installed application CLIs in E05/E12. Applications own their capability executable. The development branch also provides a separate [site publication command](site-publication.md). Applications provide
+a capability registry, caller, authorization port, and stream adapter. The library does not
+discover application capabilities or credentials implicitly.
+
+```ts
+import { runCapabilityCli } from '@uppercut-labs/agent-native/cli';
+
+const status = await runCapabilityCli(process.argv.slice(2), {
+  registry,
+  caller: { kind: 'anonymous' },
+  authorization,
+  credentialProfiles,
+}, {
+  writeStdout: (value) => process.stdout.write(value),
+  writeStderr: (value) => process.stderr.write(value),
+  readStdin: async () => readStdin(),
+});
+process.exitCode = status;
+```
+
+The help list filters to public reads by default, and a selected hidden or unknown identity gets the same generic unavailable message. Applications may provide an async `canDiscover` callback for protected help metadata and `surfaceExposure: { cli: { destructive: ['account:delete@1'] } }` for exact destructive exposure. A destructive entry still needs the app's `canDiscover` approval; direct execution is independently checked by the shared executor.
+
+The registry generates the application CLI help list and simple field flags from each input JSON Schema. String,
+number, integer, boolean, and enum properties accept typed flags; nested objects and arrays require
+`--input-json JSON`. Use `--input-json -` to read one JSON document from the provided stdin port.
+Capability identity must match the complete `namespace:name@major` form. There is no fallback to a
+different version or binding.
+
+Definitions may replace that invocation name with an established command and explicit aliases:
+
+E10 binds its existing command names in the same tested definition:
+
+<!-- source:examples/e10-existing-functions-retrofit/project/src/capability.mjs#cli-command-override -->
+~~~js
+cli: {
+  command: 'content-search',
+  aliases: ['search'],
+},
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/src/capability.mjs#L40)
+<!-- /source -->
+
+Commands and aliases are lowercase slugs and must be unique across the registry. They resolve to
+the same canonical capability identity used for execution and result envelopes; an override does
+not change the contract identity.
+
+Every invocation names `--mode local` or `--mode remote`. Local mode uses the shared executor and
+requires the configured authorization port; an optional `--binding-id` selects one exact local
+binding. Remote mode requires both `--profile NAME` and a configured own-property credential entry.
+The profile includes an HTTPS base URL and bearer token. HTTP is permitted only for localhost and
+loopback addresses for local fixtures. The CLI rejects URL userinfo and does not print tokens.
+Remote mode rejects `--binding-id`; runtime binding selection belongs to the remote host.
+
+A remote `--timeout-ms` races the request against a deadline and also signals abort to cooperative
+fetchers. A fetcher that ignores abort cannot hold the CLI past that timeout. The generated remote
+HTTP surface exposes public reads only; protected writes are rejected before any network request.
+Local mode does not apply `--timeout-ms` to a binding. Remote JSON is checked against the selected
+capability output schema before it can be reported as success.
+
+For invocations, stdout contains exactly one JSON envelope using `uan.cli-result/v1`; stderr carries
+effective target and redacted failure diagnostics. Exit codes are 0 for success, 2 for invalid input,
+3 for denied authorization, and 1 for other failures. Help and version commands are human-readable.
+The CLI runner itself never spawns a shell. Applications that launch it should pass argv as an array
+and disable shell interpretation.
+
+See the installed E05 and E12 application examples for local and loopback HTTP fixtures, positive
+output, timeout, credential, malformed-input, and handler-failure paths. E05 mounts the generated
+HTTP and MCP handlers into one pinned Node/Hono application and checks the MCP surface with the
+official client SDK. It remains a local fixture, not a deployment or external credential provider.
+
+## Discovery filtering
+
+Help lists public reads by default. Applications may provide an async `canDiscover` callback for protected metadata and `surfaceExposure: { cli: { destructive: ['account:delete@1'] } }` for exact destructive exposure. Local help requires one unique local binding; remote help lists only public reads with one server binding. Direct destructive local invocation requires the explicit CLI exposure entry before input reaches a binding, and the shared executor independently checks authorization. Close `canDiscover` over a trusted caller from the application's auth boundary; do not infer identity from argv.
+
+## Exact runner options
+
+The [generated API and CLI reference](reference.md) lists every package import
+and each argument recognized by the current parser. `npm run docs:check`
+compares that page with the package manifest and CLI source.
+
+With Node.js 22 or newer, run `npm ci` then `npm run example:e10` at the repository
+root. In its exported project, `npm run search -- --query night --limit 1` yields the
+same versioned result envelope as the existing function. An empty query exits 2 with
+`invalid-input`; pass a nonempty query to repair it. See the
+[E10 CLI fixture](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/README.md).

package/docs/compatibility.md

@@ -0,0 +1,32 @@
+# Compatibility and evidence
+
+To wrap a working site’s existing operation, follow [adopt an existing site](adopt-existing-site.md).
+
+Agent Native `1.0.1`, with the same runtime and API as `1.0.0`. The table describes the exact local fixtures and hosts
+that were tested; it is not a claim for all releases of a runtime or every client.
+
+| Surface | Runnable check | Verified boundary |
+| --- | --- | --- |
+| Static Astro | `npm run example:e01` | Astro 7.3.5 static build and simulated WebMCP lifecycle; native Chrome 155 WebMCP (opt-in feature) [evidence](evidence/UAN-023-native-webmcp-chrome.md) |
+| Astro on-demand | `npm run example:e02` | Astro 7.3.5 with its existing Node adapter, HTTP route and official MCP SDK client |
+| Next App Router | `npm run example:e03` | Next 16.3.8 on Node, production route smoke and browser artifact scan |
+| Cloudflare Worker | `npm run example:e04` | Wrangler 4.147.0 local workerd, HTTP/OpenAPI and official MCP SDK client |
+| Node/Hono | `npm run example:e05` | Hono 4.13.12 and Node adapter 2.1.3 on loopback |
+| Browser-only WebMCP | `npm run example:e06` | Simulated `document.modelContext` and native Chrome 155 with the opt-in `WebMCP` feature; ordinary button fallback in default Chrome |
+| Deployed protected MCP | [Domain Expansion evidence](evidence/gate-2-domain-expansion.md) | Cloudflare Worker with Neon in production: official MCP SDK client 2.3.0 and Claude Code 2.1.285 against `https://domains.uppercut-labs.com/mcp`, with bearer tokens, grants, typed outcomes and a rollback drill |
+| Commercial agent hosts over MCP | `node test/uan023-agent-host.mjs agy` or `claude` (opt-in inference) | Antigravity CLI 1.2.14/1.3.3 and Claude Code 2.1.286 called the E04 flagship tool, with found and invalid cases ([evidence](evidence/UAN-023-commercial-agent-hosts.md)) |
+| MCP Apps | `npm run example:e09` | Official ext-apps App/AppBridge fixture and local MCP client; no commercial host claim |
+| Codex local harness | `npm run proof:codex -- --model gpt-5.6-luna` (explicit inference opt-in) | CLI 0.145.0, managed ChatGPT login, two file writes and same-thread resume across processes; [evidence](evidence/codex-harness.md) |
+
+Use Node.js 22 or newer and `npm ci` at the repository root before a listed command.
+Each command packs the package into an independent exported project; the root
+`npm run check` runs all twelve examples on Node 22 and 24 in CI.
+The [example coverage manifest](https://github.com/uppercut-labs/agent-native/blob/main/docs-site/coverage.json) maps all E01-E12 scripts, source,
+guides, negative probes, requirements and the CI gate. A malformed input or denied request
+is part of each example's test, not a successful operation to copy into an application.
+
+For a missing optional peer, install the exact adapter dependency in
+[installation](installation.md). For an inert route, check the application's adapter, runtime
+and route mapping in [frameworks](frameworks.md). Native browser support is verified only in
+Chrome 155 with WebMCP opted in; a simulated `modelContext` cannot prove other browsers. See
+[support and limitations](support-and-limitations.md) for the release boundary.

package/docs/composition-and-versioning.md

@@ -0,0 +1,113 @@
+# Composition and versioning
+
+Reusable capability packs distribute contracts, not providers. A pack owns an authority and a
+namespace; its definitions use the combined namespace `<authority>.<namespace>`. Definitions remain
+ordinary `CapabilityDefinition` values, and a consumer binds the exact definition it implements.
+Composition does not wrap handlers, grant scopes, or create a privileged execution path.
+
+## Exact major selection and aliases
+
+`majorVersion` is part of the canonical identity. A pack can therefore export v1 and v2 together,
+and `composeCapabilityPacks()` keeps both definitions. The E08 v2 consumer selects one exact major:
+
+<!-- source:examples/e08-reusable-versioned-pack/project/src/demo-b.mjs#select-v2-major -->
+~~~js
+const selected = composition.select({
+  namespace: 'example.org.catalog',
+  name: 'album.lookup',
+  majorVersion: 2,
+});
+if (selected === undefined) throw new Error('v2 contract is not installed');
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e08-reusable-versioned-pack/project/src/demo-b.mjs#L13)
+<!-- /source -->
+
+`composition.resolve()` accepts either a canonical ID or an explicitly configured alias. Every
+import must choose `{ kind: 'none' }` or `{ kind: 'explicit', aliases: [...] }`. An alias stores one
+full canonical ID; it never means "latest" and never falls forward. Thus an `album-v1` alias that
+targets `example.org.catalog:album.lookup@1` continues to select v1 when v2 is installed. Missing
+targets, duplicate aliases, and duplicate canonical identities fail composition with source
+locations.
+
+The E08 v1 consumer pins an alias explicitly instead of inferring a latest version:
+
+<!-- source:examples/e08-reusable-versioned-pack/project/src/demo.mjs#compose-v1-alias -->
+~~~js
+const composition = composeCapabilityPacks([
+  {
+    pack: catalogPack,
+    source: 'src/demo.mjs:consumer-import',
+    aliasPolicy: {
+      kind: 'explicit',
+      aliases: [{ name: 'album-v1', capabilityId: 'example.org.catalog:album.lookup@1' }],
+    },
+  },
+]);
+const selected = composition.resolve('album-v1');
+if (selected === undefined) throw new Error('v1 alias is not configured');
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e08-reusable-versioned-pack/project/src/demo.mjs#L10)
+<!-- /source -->
+
+## Contract migration reports
+
+`compareCapabilityDefinitions(previous, next)` returns a structural report over input and output
+JSON Schema plus risk, access, and HTTP/CLI surface metadata. Reports identify paths and before/after values for
+property additions/removals, likely one-to-one property renames, required-field changes, defaults,
+unit annotations such as `x-unit`, and other represented schema values. Rename detection is a
+structural aid, not proof of author intent.
+
+`assertCompatibleCapabilityReplacement(previous, next)` is for an unchanged canonical identity. It
+allows an implementation or description change when input/output schemas and risk/access metadata
+remain compatible. It rejects a breaking definition replacement, so a v1 ID cannot silently acquire
+v2 requirements or output shape.
+
+For a new major, use `defineCapabilityMigration({ previous, next, semanticReview })`. The semantic
+note and named reviewer are mandatory even when the two schemas are identical. JSON Schema can show
+represented structural changes; it cannot prove behavioral equivalence, units outside the schema,
+side effects, ordering, freshness, or other semantics. A pack that contains multiple majors of one
+capability family must attach the reviewed adjacent-major migrations and lifecycle policy; pack
+definition fails when either is missing.
+
+## Deprecation and removal
+
+Lifecycle is application policy, not npm semver inference. `defineCapabilityLifecyclePolicy()`
+records each canonical major as `supported`, `deprecated`, or `removed`. Deprecation needs an
+operator-facing note. Removal needs a note and reviewer.
+
+`validateCapabilityPackMigration()` compares an earlier pack to a later pack. It checks unchanged
+IDs with the replacement guard, requires reviewed migration records for added majors of an existing
+capability family, and reports additions/removals. A supported major cannot disappear implicitly. A
+major may be removed only when the previous policy already marked it deprecated and the new policy
+records an explicit reviewed removal. Package version changes do not alter these states.
+
+## Generated surfaces
+
+`capabilitySurfaceNames(identity)` maps each exact major identity deterministically:
+
+| Surface | Mapping |
+| --- | --- |
+| CLI | `<namespace>:<name>@<major>` |
+| HTTP | `/capabilities/<namespace>/<name>/v<major>/invoke` |
+| MCP | length-encoded `cap_..._v<major>` tool name |
+| OpenAPI | length-encoded `invoke_..._v<major>` operation ID |
+
+HTTP segments are encoded separately. MCP names over 128 characters receive a visible
+`_fnv1a64_<digest>` qualifier rather than silent truncation. Aliases are composition lookup names;
+they do not replace canonical CLI IDs, HTTP paths, MCP names, or OpenAPI operations. Adapters expose
+only definitions present in the registry and keep their existing authorization/discovery policies.
+
+Run `npm run example:e08` for the independently installed contract-only package. It exports v1 and
+v2 album lookup contracts, keeps a stable v1 alias, uses two consumer bindings, checks old/new output
+fixtures, and exercises migration failures. E12 retains its established canonical unit-converter ID.
+
+## Reproduce coexistence
+
+With Node.js 22 or newer, run `npm ci` and `npm run example:e08` from the
+repository root. The standalone package installs v1 and v2 contracts and each
+consumer selects its intended major; the v1 alias remains pinned. A breaking
+same-ID replacement fails composition. Give the changed contract a new major,
+add a reviewed migration record, and keep the earlier major until its lifecycle
+policy explicitly permits removal. See [E08 setup](https://github.com/uppercut-labs/agent-native/blob/main/examples/e08-reusable-versioned-pack/project/README.md).