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

package/docs/permissions-and-discovery.md

@@ -0,0 +1,58 @@
+# Permissions and discovery
+
+Agent Native separates metadata visibility from permission to execute. A public read capability can be listed anonymously. The shared `evaluateCapabilityDiscovery` policy supports public reads, application-provided protected visibility checks, and exact per-surface destructive exposure. The executor checks authorization again for every call. A stale client tool list does not preserve access after a grant is revoked.
+
+## Trusted identity
+
+For remote MCP, configure `bearerAuth` with an `OAuthTokenVerifier` and an `expectedResource` from the official MCP server SDK. The SDK bearer gate validates the token before Agent Native receives `AuthInfo`. The application must map verifier-owned identity metadata to a `TrustedPrincipal` through `resolveTrustedPrincipal`; request headers and MCP client metadata are not identity sources. The principal includes issuer, subject, client ID, tenant ID, audience, token scopes and token expiry.
+
+The library does not issue tokens, run an OAuth server, or refresh credentials. Browser sessions and CLI profiles have separate identity boundaries. Their host applications must establish a trusted principal before using the same grant policy; credentials are never shared across surfaces automatically.
+
+## Durable grants
+
+`GrantStorePort` supplies `find`, `save` and `revoke`. The host application owns persistent storage and the grant issuance flow. Each grant is bound to issuer, subject, client, tenant, application, audience and policy revision, with scopes, issue time, expiry and revocation time. A token is short lived proof of the current caller; a grant is the separately persisted permission. Protected execution requires both current token scopes and an unexpired, unrevoked matching grant.
+
+`createGrantAuthorization` checks the store on every protected call. Every protected capability also requires `authorizeResource` so the application can enforce record ownership and tenant boundaries before its binding runs. Public reads need no grant store and remain available anonymously.
+
+For protected MCP discovery, the application may use `hasGrantForScopes` inside `discoverProtected`. The older `canDiscover` hook only narrows public reads; it cannot expose protected metadata. `evaluateCapabilityDiscovery` returns only a visibility decision and safe denial reason; adapters do not serialize private descriptions or schemas when a capability is hidden. Refresh browser registration or remote tool discovery after login, grant, scope change and revocation. Do not put protected schemas in public static manifests or a shared public cache.
+
+Destructive visibility also requires an explicit per-app surface allowlist, such as `surfaceExposure: { mcp: { destructive: ['account:delete@1'] } }`. The canonical identity must be listed for that surface, and the current authorization check must still pass. This configuration does not change the domain capability's risk metadata. Browser and CLI use `browser` and `cli` keys respectively. The HTTP adapter in this package remains public-read-only and emits only public read routes in OpenAPI.
+
+The [E07 playlist fixture](https://github.com/uppercut-labs/agent-native/blob/main/examples/e07-playlist-permissions/README.md) demonstrates official SDK bearer authentication, two tenants, persistent local grants, repeated edits, restart persistence, separate delete scope and direct denial after revocation. Its static test identities and JSON store reject production mode. The JSON store is a single-process fixture; concurrent independent processes are unsupported. Replace both with the application's real verifier and durable store before deployment. E07 checks revocation at the next store lookup in its sequential fixture; a production store's consistency and cache policy determine its actual latency.
+
+Agent Native does not suppress confirmation prompts imposed by a browser, identity provider or MCP host. Grant reuse avoids repeated *library* consent only while identity, scopes, resource, policy and expiry remain valid.
+
+## Surface policy
+
+The shared `evaluateCapabilityDiscovery` decision supports public reads, application-provided protected visibility checks, and exact per-surface destructive exposure. For MCP, the adapter first requires current token scopes and a matching unexpired, unrevoked grant; `discoverProtected` can only narrow that set. A stale client tool list does not preserve access after grant revocation.
+
+Destructive capabilities also require an exact per-app surface allowlist, such as `surfaceExposure: { mcp: { destructive: ['account:delete@1'] } }`. The current authorization check must still pass, and destructive exposure is rechecked at the adapter call boundary. This configuration does not change domain risk metadata. Browser and CLI use `browser` and `cli` keys. HTTP/OpenAPI remains public-read-only and lists only capabilities with a unique server binding.
+
+CLI help filters by usable local bindings or public remote routes. Hidden or unavailable identities receive a generic explanation. Applications should close `canDiscover` over a trusted caller from their authentication boundary, never infer identity from command arguments or user-provided text. Refresh browser sync and remote tool listing after login, grant, scope change and revocation.
+
+## Verify revocation locally
+
+With Node.js 22 or newer, run `npm ci` and `npm run example:e07` from the package root.
+The single-process fixture persists grants and revokes an existing ID in its local JSON store:
+
+<!-- source:examples/e07-playlist-permissions/project/src/grant-store.mjs#revoke-grant -->
+~~~js
+async revoke(grantId, revokedAt) {
+  return await this.#withWriteLock(async () => {
+    const grants = await this.#read();
+    const grant = grants.find((entry) => entry.grantId === grantId);
+    if (!grant || grant.revokedAt !== null) return false;
+    grant.revokedAt = revokedAt;
+    await this.#write(grants);
+    return true;
+  });
+}
+~~~
+
+[View tested source](https://github.com/uppercut-labs/agent-native/blob/main/examples/e07-playlist-permissions/project/src/grant-store.mjs#L56)
+<!-- /source -->
+
+The negative test proves that a revoked ID cannot be saved again and that the next protected
+call is denied. If the fixture refuses to start in production mode, remove
+`NODE_ENV=production` and use the documented local test mode; this JSON store intentionally
+rejects production use. See [E07 setup and cleanup](https://github.com/uppercut-labs/agent-native/blob/main/examples/e07-playlist-permissions/README.md).

package/docs/programmatic-harness.md

@@ -0,0 +1,88 @@
+# Programmatic harness contracts
+
+The isolated `@uppercut-labs/agent-native/harness` export defines a provider-neutral
+Session -> Turns control plane without runtime dependencies. This initial slice
+includes neutral fake-adapter acceptance, a Node-only loopback MCP bridge and an
+isolated [Codex local adapter](harness-codex.md) with real Luna acceptance.
+Importing the neutral contracts starts no provider or inference.
+
+Harness control and capability execution are sibling planes. Starting an agent
+never grants permission to invoke application capabilities. The existing
+[capability executor](capabilities-and-bindings.md) and [MCP authorization](mcp.md)
+remain authoritative. The local bridge binds only to loopback; cloud
+configuration must explicitly supply a reachable authenticated endpoint.
+
+## Local MCP bridge
+
+The isolated Node-only `/harness/mcp-bridge` helper serves an application-supplied
+MCP handler on literal loopback, preserving its authorization and owning its
+listener lifecycle. See [bridge configuration and cleanup](harness-mcp-bridge.md).
+Cloud agents need an explicit reachable authenticated endpoint; no tunnel is created.
+
+## Lifecycle
+
+`ProgrammaticHarnessAdapter` exposes `describe`, `openSession`, `resumeSession`,
+`runTurn`, `cancelTurn`, and `closeSession`.
+
+- Call `describe()` before use. Its provider, targets (`local`/`cloud`), and features
+  (`resume`, `cancel`, `usage`, `mcp`) describe actual support.
+  `assertHarnessSupport(descriptor, target, feature?)` raises stable typed failures.
+  Adapters must also check support; negotiation is not authorization.
+- Local open/resume requests require an explicit workspace. Cloud requests carry
+  only the target; the provider factory must require explicit remote/repository and
+  authentication configuration. No local workspace is implicitly uploaded.
+- `HarnessSessionRef` contains provider, target, and an opaque session ID. Resume
+  receives this complete reference plus target/workspace. IDs are preserved verbatim;
+  no parsing, cross-provider migration, or global lookup is implied.
+- `runTurn({ session, prompt })` yields `turn-started` with an opaque turn ID,
+  optional status/tool/usage events, then exactly one terminal event: `completed`,
+  `failed`, or `cancelled`. A rejected start throws `HarnessError`.
+  A stream ending without a terminal event is incomplete, never successful.
+- `cancelTurn({ session, turnId })` targets one active turn and requires `cancel`.
+  `closeSession({ session })` releases only adapter-owned resources and is idempotent
+  for a known closed session. It does not imply deleting provider history.
+  Adapters define whether resume can reattach after local resource cleanup.
+
+Adapters validate provider/target identity, workspace ownership, session state,
+and concurrent-turn restrictions. Core contracts do not execute capabilities or
+weaken provider permissions.
+
+## Events and failures
+
+`HarnessEvent` is a closed union: `session-started`, `turn-started`, `progress`,
+`tool`, `usage`, `completed`, `failed`, `cancelled`.
+`createHarnessEvent` constructs immutable snapshots, projects out extra provider
+fields, and validates normalized payloads. `createHarnessStatusEvent` is the focused
+status/tool helper. Message length is 1-240 characters, provider length 1-64,
+session ID length 1-1024, and turn ID length 1-128; control characters are rejected.
+These limits bound individual events, not total stream length. Consumers must apply
+their own turn deadlines and event-count limits.
+
+Status/tool messages must be adapter-authored, reviewed safe summaries. Length checks
+and field projection do not detect credentials embedded in an allowed string.
+Never forward raw model output, exception text, environment dumps, credential files,
+or tool arguments. Treat session IDs as sensitive in external evidence unless provider
+guidance explicitly permits sharing them.
+
+Usage is a nonnegative safe integer in provider-reported `tokens` or `requests`.
+Emit it only when advertised and reliable; absence means unavailable, not zero.
+It is not a cross-provider price model.
+
+`HarnessError.reason` is one of `unsupported-target`, `unsupported-feature`,
+`invalid-request`, `authentication-required`, `provider-unavailable`,
+`session-not-found`, `session-closed`, `turn-not-found`, `turn-active`, `timeout`,
+`provider-failed`. Messages are fixed by reason and carry no raw provider cause.
+Terminal failure events use these same reasons. Adapters translate provider failures
+at the boundary; restricted diagnostics stay outside this normalized API.
+
+## Acceptance and installation
+
+`test/harness.test.mjs` checks a fake adapter opening a session, two turns with
+same-session resume, targeted cancellation, close, unsupported operations, stream
+failures, event bounds, and raw-field exclusion. Type checks reject local requests
+without a workspace. `npm run check:portability` packs and installs a fresh
+root/browser/harness consumer with optional peers absent and checks every export.
+
+The export is not re-exported from root/core and has no provider SDK, Node, DOM,
+framework, or MCP imports. Import contracts through `/harness`.
+Source/tarball checks do not establish availability of a new registry release.

package/docs/readability-frameworks.md

@@ -0,0 +1,18 @@
+# Framework examples for site publication
+
+Each project pairs the same Harbor field guide with a distinct application. Start from the matching project, follow the framework's production build and inspect how its public data supplies the human page and its Markdown mirror. The field guide's original edition departs from Pier Four. The updated edition moves the departure to Pier Seven and withdraws a route.
+
+| Integration | Production behavior exercised | Showcase |
+| --- | --- | --- |
+| Astro | Content collection, static HTML and a Node-rendered advisory. A second config builds a file-only version. | Breakwater field guide and tide advisory |
+| Next.js | App Router static parameter enumeration with server route handlers for protected resources | Field recording course |
+| React with Vite | Vite production pages, client routing, deep links and playback queue | Night Ferry track |
+| Vue with Vite | Vue Router with generated canonical pages and query-based catalog filters | Brass coupler parts catalog |
+| SvelteKit | Server load, dynamic event route, protected attendee route and adapter-node | Lantern workshop |
+| Nuxt | Nuxt file routing, server-rendered locale-specific pages and Nitro's Node preset | Bilingual museum exhibit |
+| React Router framework mode | Nested framework route modules, server loader, redirect and error response | River line transit stops |
+| Angular | Parameterized prerendering, hydration and lazy checklist | Atlas equipment handbook |
+
+The route and field allowlists are part of each example. Change those to match the adopting application and review them with its access rules. The examples use the shared experimental publication API and the framework integration code in their source. Version pins and lockfiles specify the tested framework and toolchain. Hosted compatibility and results from independent language models require separate evidence.
+
+[Runnable source and native test instructions](https://github.com/uppercut-labs/agent-native/blob/main/examples/readability/README.md) · [Publication and adoption guide](site-publication.md)

package/docs/reference.md

@@ -0,0 +1,161 @@
+# Generated package and CLI reference
+
+This page is generated from [package.json](../package.json) and the
+[CLI parser](https://github.com/uppercut-labs/agent-native/blob/main/src/cli.ts). Run `node docs-site/reference.mjs` after changing those
+sources. `npm run docs:check` fails if this page drifts. Agent Native
+`1.1.0`. Stable and experimental entry points are listed in [stability](stability.md).
+
+## Typed package entrypoints
+
+| Import specifier | Type declaration | ESM implementation |
+| --- | --- | --- |
+| `@uppercut-labs/agent-native` | `./dist/index.d.ts` | `./dist/index.js` |
+| `@uppercut-labs/agent-native/contracts` | `./dist/core/contracts.d.ts` | `./dist/core/contracts.js` |
+| `@uppercut-labs/agent-native/harness` | `./dist/harness.d.ts` | `./dist/harness.js` |
+| `@uppercut-labs/agent-native/composition` | `./dist/core/composition.d.ts` | `./dist/core/composition.js` |
+| `@uppercut-labs/agent-native/registry` | `./dist/registry.d.ts` | `./dist/registry.js` |
+| `@uppercut-labs/agent-native/executor` | `./dist/core/executor.d.ts` | `./dist/core/executor.js` |
+| `@uppercut-labs/agent-native/cli` | `./dist/cli.d.ts` | `./dist/cli.js` |
+| `@uppercut-labs/agent-native/http` | `./dist/http.d.ts` | `./dist/http.js` |
+| `@uppercut-labs/agent-native/schema/zod` | `./dist/adapters/zod.d.ts` | `./dist/adapters/zod.js` |
+| `@uppercut-labs/agent-native/diagnostics` | `./dist/core/diagnostics.d.ts` | `./dist/core/diagnostics.js` |
+| `@uppercut-labs/agent-native/doctor` | `./dist/doctor.d.ts` | `./dist/doctor.js` |
+| `@uppercut-labs/agent-native/mcp` | `./dist/mcp.d.ts` | `./dist/mcp.js` |
+| `@uppercut-labs/agent-native/browser` | `./dist/browser.d.ts` | `./dist/browser.js` |
+| `@uppercut-labs/agent-native/astro` | `./dist/astro.d.ts` | `./dist/astro.js` |
+| `@uppercut-labs/agent-native/next` | `./dist/next.d.ts` | `./dist/next.js` |
+| `@uppercut-labs/agent-native/next/browser` | `./dist/next-browser.d.ts` | `./dist/next-browser.js` |
+| `@uppercut-labs/agent-native/init` | `./dist/init.d.ts` | `./dist/init.js` |
+| `@uppercut-labs/agent-native/auth` | `./dist/auth.d.ts` | `./dist/auth.js` |
+| `@uppercut-labs/agent-native/mcp-apps` | `./dist/mcp-apps.d.ts` | `./dist/mcp-apps.js` |
+| `@uppercut-labs/agent-native/harness/mcp-bridge` | `./dist/harness-mcp-bridge.d.ts` | `./dist/harness-mcp-bridge.js` |
+| `@uppercut-labs/agent-native/harness/codex` | `./dist/harness-codex.d.ts` | `./dist/harness-codex.js` |
+| `@uppercut-labs/agent-native/publication` | `./dist/publication.d.ts` | `./dist/publication.js` |
+
+The package's optional peers are listed in [installation](installation.md). Import only
+the subpath needed by the application. The experimental [site publication CLI](site-publication.md) operates on approved public content.
+
+## Application CLI arguments
+
+The application calls `runCapabilityCli(argv, options, streams)`. One command or
+canonical capability ID is positional. A command override or alias retains the
+canonical identity and has no version fallback.
+
+| Argument | Value and default | Boundary |
+| --- | --- | --- |
+| `--mode` | local or remote | Required for invocation; remote needs a profile. |
+| `--profile` | lowercase slug (1-32 characters) | Remote only. |
+| `--binding-id` | exact binding ID | Local only. |
+| `--timeout-ms` | integer 1-300000 (default 10000) | Remote request deadline. |
+| `--input-json` | JSON document or - for stdin | Cannot combine with field flags. |
+| `--<field>` | typed scalar from input schema | Complex fields use `--input-json`. |
+| `--help` or `-h` | no value | Lists visible capabilities. |
+| `--version` | no value | Displays the application's supplied package version. |
+
+For a runnable instance, use Node.js 22 or newer, `npm ci`, and
+`npm run example:e10` from the repository root. The exported E10 CLI runs
+`npm run search -- --query night --limit 1` successfully. An empty query exits
+2 with `invalid-input`; provide a nonempty query to retry. See
+[CLI behavior](cli.md) and [E10 instructions](https://github.com/uppercut-labs/agent-native/blob/main/examples/e10-existing-functions-retrofit/project/README.md).
+
+## Typed adapter configuration
+
+These exported declarations are copied from the checked TypeScript source at build time.
+Framework mounts and security ownership are explained in the linked guides.
+
+### CLI
+
+[View source](https://github.com/uppercut-labs/agent-native/blob/main/src/cli.ts)
+
+~~~ts
+export type CliCredentialProfile = {
+  readonly baseUrl: string;
+  readonly token: string;
+};
+
+export type CapabilityCliOptions = {
+  readonly registry: CapabilityRegistry;
+  readonly authorization: AuthorizationPort;
+  readonly caller: ExecutionCaller;
+  readonly credentialProfiles?: Readonly<Record<string, CliCredentialProfile>>;
+  readonly packageVersion?: string;
+  readonly fetcher?: typeof fetch;
+  readonly surfaceExposure?: CapabilitySurfaceExposure;
+  readonly canDiscover?: (
+    definition: CapabilityDefinition<unknown, unknown>,
+  ) => boolean | Promise<boolean>;
+};
+~~~
+
+### HTTP
+
+[View source](https://github.com/uppercut-labs/agent-native/blob/main/src/http.ts)
+
+~~~ts
+export type HttpAdapterOptions = {
+  readonly basePath?: string;
+  readonly maxRequestBytes?: number;
+  readonly deadlineMs?: number;
+  readonly resolveExecutionContext?: (
+    request: Request,
+  ) => HttpExecutionContext | Promise<HttpExecutionContext>;
+};
+~~~
+
+### MCP
+
+[View source](https://github.com/uppercut-labs/agent-native/blob/main/src/mcp-core.ts)
+
+~~~ts
+export type McpAdapterOptions = {
+  readonly endpoint?: string;
+  readonly surfaceExposure?: CapabilitySurfaceExposure;
+  readonly maxRequestBytes?: number;
+  readonly deadlineMs?: number;
+  readonly canDiscover?: (
+    definition: CapabilityDefinition<unknown, unknown>,
+    request: Request,
+  ) => boolean | Promise<boolean>;
+  readonly discoverProtected?: (
+    definition: CapabilityDefinition<unknown, unknown>,
+    request: Request,
+    authInfo: AuthInfo,
+  ) => boolean | Promise<boolean>;
+  readonly bearerAuth?: {
+    readonly verifier: OAuthTokenVerifier;
+    readonly expectedResource: URL;
+    readonly requiredScopes?: readonly string[];
+    readonly resourceMetadataUrl?: string;
+    // Answer requests without an Authorization header with the SDK's 401 challenge. Defaults to
+    // true when no capability is a public read, so hosts are prompted to authenticate instead of
+    // receiving an empty tool list.
+    readonly required?: boolean;
+  };
+  // Operator hook for tool calls that end in an error. It runs after the response is decided;
+  // a throwing or rejecting hook is ignored.
+  readonly onToolFailure?: (failure: McpToolFailure) => void | Promise<void>;
+  // Overrides the default collision-free tool name. Names must be unique and match MCP's name rules.
+  readonly toolName?: (definition: CapabilityDefinition<unknown, unknown>) => string;
+  // AuthInfo comes from the SDK verifier; issuer/subject/tenant must be supplied by that
+  // verifier's trusted metadata, never inferred from request headers or MCP clientInfo.
+  readonly resolveTrustedPrincipal?: (
+    authInfo: AuthInfo,
+  ) => TrustedPrincipal | null | Promise<TrustedPrincipal | null>;
+  readonly grantAuthorization?: Omit<GrantAuthorizationOptions, 'principal'>;
+  readonly resolveExecutionContext?: (
+    request: Request,
+    authInfo?: AuthInfo,
+  ) => McpExecutionContext | Promise<McpExecutionContext>;
+};
+~~~
+
+### Doctor
+
+[View source](https://github.com/uppercut-labs/agent-native/blob/main/src/doctor.ts)
+
+~~~ts
+export type DoctorRunOptions = {
+  readonly now?: () => Date;
+  readonly profile?: DoctorCheckProfile;
+};
+~~~

package/docs/release-handoff.md

@@ -0,0 +1,41 @@
+# Release and provider handoff
+
+This handoff covers how a release candidate is checked and published; the current release is `1.0.1`. The public source is [uppercut-labs/agent-native](https://github.com/uppercut-labs/agent-native); `@uppercut-labs/agent-native` is its npm name and MIT is its license. Check the registry before claiming publication. Older entries below are dated release snapshots; their `latest` tags describe that publication date, not today. See [UAN-024 release evidence](evidence/UAN-024-release-readiness.md) for the earlier `0.0.0` preparation snapshot.
+
+## Package release sequence
+
+1. Select the version, update `src/package-version.ts` and the E08 contract peer with it, regenerate `docs/reference.md`, and align the changelog, installation guide and [upgrade notes](upgrading-to-1.0.md). Run `npm run check:api`; a stable API change needs a major version unless [stability](stability.md) allows it.
+2. Run the Node 22/24 CI matrix on the exact candidate commit. The example negative probes and independent tarball install are part of that gate.
+3. From a clean checkout of that commit, run `npm ci` and `npm pack --json`. Inspect the actual tarball, license, README, documentation, dependency licenses, production audit, file list, and every declared export. Record its SHA-256 digest, package file count and size, source SHA, and Node/npm versions. Install the archive in a clean consumer and run the documented first capability.
+4. Publish that exact archive under the organization scope with public access. Record the registry URL and digest. Keep the source tag and registry artifact tied to the same source commit.
+5. Perform a post-publish clean registry install and the documented first-run path. If publication or provenance verification fails, report the actual registry state and recovery action; never describe a local tarball as a published npm release.
+
+The provider gates below apply to application deployments and full host claims. The released 1.0.1 package has no `bin` entry; users call its programmatic APIs or application-owned CLI runner. Do not advertise `npx agent-native init` until an executable exists and is tested.
+
+## Native provider deployment
+
+Agent Native supplies contracts and adapters, not a managed hosting account. The deploying application owns its provider resources and operational policy:
+
+| Surface | Application-owned deployment work | Minimum live evidence |
+| --- | --- | --- |
+| Static Astro plus Worker sidecar (E01/E04) | Choose the sidecar origin, provision the Worker and routes, configure allowed Host/Origin/CORS and revision matching, bind secrets outside source control, and keep the static site independent. | Public and denied routes, cross-origin denial, OpenAPI and MCP client roundtrip through the deployed address, rollback of Worker and routing. |
+| Astro on-demand (E02) or Next App Router (E03) | Provide a supported server runtime, own endpoint mounting and framework adapter, deploy the site and server together, and verify static/prerendered pages remain correct. | HTTP and MCP calls, auth/denial, framework build, navigation and rollback at the real deployment. |
+| Node/Hono or another server (E05) | Own the process, TLS/front proxy, route path, limits, logs, credentials and restart behavior. | Local and remote CLI parity through the deployed endpoint, malformed input, auth denial and health evidence. |
+| Browser and MCP Apps (E06/E09) | Choose an actual host with the needed API, obtain host consent, set resource CSP/sandbox policy, and keep server credentials out of browser assets. | Named host version and origin, visible tool registration and action, denied call, iframe/CSP behavior, cleanup after navigation. |
+
+For protected capabilities, the application must provide token verification, issuer/audience/scope policy, resource authorization, a durable grant store, revocation consistency, idempotency for mutations, and incident response. A timeout can leave a write's completion uncertain; do not retry it blindly. The local E07 grant fixture and E11 doctor profile are examples, not production identity or persistence services. Record provider account owner, deployment ID, route/DNS owner, secret storage location (never the secret), rollback command, log/trace location, and the person who accepts live behavior in the deployment runbook.
+
+## Open provider and full-host acceptance gates
+
+- [x] GitHub private vulnerability reporting is enabled for the public repository; the [Security Advisories page](https://github.com/uppercut-labs/agent-native/security/advisories) is the private report channel.
+- [x] UAN-020 security/failure-safety review and its production support limits are recorded in [negative security fixtures](evidence/UAN-020-negative-security-fixtures.md), [operational failure safety](evidence/UAN-020-operational-failure-safety.md) and [support limits](support-and-limitations.md).
+- [x] UAN-021 guides and every E01-E12 example have checked prerequisites, expected output, a negative path, and source-backed evidence; `npm run docs:check` enforces [coverage](evidence/UAN-021-docs-coverage.md).
+- [x] UAN-022 Windows and Linux representative install/CLI behavior, dependency license inventory, and overhead measurements have a recorded decision: [portability](evidence/UAN-022-package-portability.md), [overhead](evidence/UAN-022-overhead-license-audit.md) and the [cross-platform license and notice review](evidence/UAN-022-cross-platform-license-notices.md).
+- [x] UAN-023 named-host evidence is recorded: [Inspector MCP Apps rendering and clean-context Astro adoption](evidence/UAN-023-inspector-web-and-astro-adoption.md) and [native Chrome 155 WebMCP](evidence/UAN-023-native-webmcp-chrome.md) with the opt-in feature. [Antigravity CLI and Claude Code](evidence/UAN-023-commercial-agent-hosts.md) invoked the flagship tool over remote MCP. MCP Apps rendering in commercial hosts and shipping browser agents remain unverified and carry no support claim.
+- [x] The Astro/example dependency path to `http-cache-semantics@4.2.0` is assessed against [GHSA-ch52-4w7c-c8xp](https://github.com/advisories/GHSA-ch52-4w7c-c8xp): the [2026-10-10 recheck](evidence/GHSA-ch52-4w7c-c8xp-2026-10-10.md) found no upstream fix, and Astro does not use the vulnerable method. Recheck before a provider launch guide.
+- [x] `1.0.0` was packed from a clean clone of CI-green `a7b3408`: 170 files, 187,584 bytes, SHA-256 `2d56d226791fdd7025cfec172cda83e408464b78141264a51f104f249761cf1e` (Windows 11, Node 25, npm 12.1). At its October 12, 2026 publication it was npm `latest` (integrity `sha512-8UUwdjsKxr4qk…`, shasum `3d5ef7ef…ae8e`, byte-identical to the archive) and the [v1.0.0 GitHub release](https://github.com/uppercut-labs/agent-native/releases/tag/v1.0.0). Clean registry installs on Windows 11 and macOS 27 (Node 26.9, npm 11.19) ran the quickstart, and the release archive verified against its `.sha256` on macOS. [Domain Expansion](evidence/gate-2-domain-expansion.md) runs 1.0.0 in production.
+- [x] `0.1.3` was packed from a clean clone of CI-green `755c635`: 162 files, SHA-256 `2cf416bbdac857c00a1153cf84e444674d9495852bfe94101f4b626141eca538`. At its October 10, 2026 publication it was npm `latest` (integrity `sha512-MgIgNjB/KFJPh…`, byte-identical to the archive) and the [v0.1.3 GitHub prerelease](https://github.com/uppercut-labs/agent-native/releases/tag/v0.1.3). A clean registry install ran the quickstart, and its packaged evidence records both commercial agent hosts.
+- [x] `0.1.2` was packed from a clean clone of CI-green `b6f31d4`: 162 files, SHA-256 `1b6c79890494dd4febb618840950301f66f75c1f3739f733b0136fc634833988`. It is published on [npm](https://www.npmjs.com/package/@uppercut-labs/agent-native/v/0.1.2), where `latest` was 0.1.2 on October 10, 2026 with integrity `sha512-UUTzWRnVE7Fbetwf…` and shasum `a0d64189…a8bc`, and the registry download is byte-identical. It is also published as the checksum-verified [v0.1.2 GitHub prerelease](https://github.com/uppercut-labs/agent-native/releases/tag/v0.1.2). Clean consumers installed it from both routes and ran the quickstart.
+- [x] The `0.1.1` tarball's digest, source commit, clean registry install and packed proof are recorded in the [harness release evidence](evidence/codex-harness.md#registry-release---2026-10-05). Provider handoff remains the deploying application's work, described above.
+
+See [support limits](support-and-limitations.md), [compatibility](compatibility.md), [security model](https://github.com/uppercut-labs/agent-native/blob/main/SECURITY.md), and [contributing](https://github.com/uppercut-labs/agent-native/blob/main/CONTRIBUTING.md). A green repository CI run is one gate; it does not close the deployment and host gates.

package/docs/site-publication.md

@@ -0,0 +1,85 @@
+# Publish public content for reading agents
+
+The unreleased experimental `/publication` import and `agent-native-site` executable generate a text index, directly readable Markdown mirrors, optional aggregate text and JSON-LD for approved public pages. Your app owns its human HTML, data permissions and cache invalidation.
+
+[Framework integrations and showcases](readability-frameworks.md)
+
+## Try a source-backed example
+
+Use Node 22+ and a checkout of this branch. From the repository root, run the following commands. The example creates a small workshop site in a new working directory with a private manifest, an empty state directory and a separate public output directory.
+
+```sh
+npm ci
+npm run build
+node examples/site-publication/build.mjs workshop-demo http://127.0.0.1:4173/
+node bin/agent-native-site.mjs preview --manifest workshop-demo/site.json --out workshop-demo/public --state workshop-demo/state
+```
+
+Read the proposed changes, included routes and excluded sources. Substitute the exact digest from that preview.
+
+```sh
+node bin/agent-native-site.mjs apply --manifest workshop-demo/site.json --out workshop-demo/public --state workshop-demo/state --approve REVIEWED_DIGEST
+```
+
+In a clean consumer that installed the candidate tarball, use `npm exec -- agent-native-site` in place of `node bin/agent-native-site.mjs`. The public site must serve the generated files verbatim with the expected media types. Configure `.md` as `text/markdown` or `text/plain`, `.jsonld` as `application/ld+json` or `application/json`, and `.txt` as `text/plain`. Unknown mirror paths should return 404 or 410. The verifier performs anonymous requests against the configured origin and checks canonical HTML, applicable JSON-LD, actual bytes, types and a missing Markdown path.
+
+```sh
+node bin/agent-native-site.mjs verify --manifest workshop-demo/site.json
+```
+
+## Discover review candidates in existing projects
+
+Run `agent-native-site discover --framework next --project .` on an App Router app. Astro, Next.js App Router, Nuxt and SvelteKit use conventional filesystem page paths. Dynamic parameters stay unresolved, and discovery reads filenames without running loaders or opening page bodies. Angular can read an existing `dist/prerendered-routes.json`. For React/Vite, Vue/Vite, React Router framework mode and Angular, pass `--routes routes.json` with an application-exported route table (paths or nested records with path, index and children). A custom route file must be inside the project. Redirects, internationalization, custom framework directories, aliases and complex mounted routers require developer review.
+
+The output is private review material. Every discovered route has unknown visibility, a source locator and a stable candidate ID. Enumerate the finite public routes and select their public fields to construct the manifest. An automatically discovered path cannot authorize publication.
+
+## Supply public projections
+
+A manifest has `config` and `candidates`. Generate these records from the same public fields that render the human site. The CLI consumes a developer-supplied route inventory. The [workshop source](https://github.com/uppercut-labs/agent-native/blob/main/examples/site-publication/build.mjs) drives both the page and its publication records.
+
+```json
+{
+  "config": {
+    "enabled": true,
+    "siteUrl": "https://example.org/",
+    "title": "Workshop calendar",
+    "description": "Public event information.",
+    "full": false
+  },
+  "candidates": [
+    {
+      "id": "w17",
+      "revision": "r1",
+      "route": "/events/lantern/",
+      "visibility": "public",
+      "title": "Lantern workshop",
+      "markdown": "Doors open at 10:30.",
+      "structuredType": "WebPage"
+    }
+  ],
+  "verify": {
+    "responses": [
+      {"path": "/events/lantern/", "status": 200, "contains": ["Doors open at 10:30."]},
+      {"path": "/unavailable-draft/", "status": 404}
+    ]
+  }
+}
+```
+
+Keep the manifest and journal outside every served directory. A public record requires a finite site-relative route, opaque ID and revision, title and Markdown prose. Use `links` with public source IDs for navigation. A protected/draft record needs only its identifier, revision, route and visibility. The engine excludes nonpublic material from generated bytes. The private preview can include opaque source IDs. Render the returned JSON-LD on the corresponding public HTML page when selecting a structured type, and set its canonical link to the reviewed URL.
+
+`planPublication(config, candidates)` performs an in-memory preview. Its assets are UTF-8 content, relative output paths, media types and SHA-256 digests. An error diagnostic suppresses all assets. An adapter can pass a read-only verifier as a third argument for public protocol declarations. The CLI recognizes same-site OpenAPI 3 JSON descriptions with an info record and at least one HTTP operation with an inline documented response. A protocol declaration alone cannot advertise an endpoint.
+
+A public record can also declare `facts`: up to 20 `{"label", "value"}` pairs that restate values from its prose, such as `{"label": "Doors open", "value": "10:30"}`. Each mirror lists them under **Key facts** after the body, so an agent can quote the bare value beside a citable URL. Render the same list on the human page. Each mirror states both its canonical URL and its own URL. The generated `llms.txt` opens with a coverage statement: it counts the pages in the approved projection, says that a fact outside those pages is not published by the site, and links `llms-full.txt` when the aggregate is enabled.
+
+A server can also return a page's mirror at its canonical URL to a client that asks for Markdown. `negotiateMarkdown({ method, pathname, accept }, markdownMirrors(plan.manifest.entries))` returns the mirror path when the `Accept` header names `text/markdown` at least as strongly as HTML. Browsers never send it, so they keep the HTML. Send `Vary: Accept` from those routes whichever representation you serve. `markdownNegotiationHandler(mirrors, read)` wraps the same decision as Node `(req, res, next)` middleware; `read` returns the mirror bytes from your generated asset directory.
+
+## Change or withdraw content
+
+Regenerate the manifest when a source changes, preview the diff and apply the new digest. Removing a candidate, changing it to private, or disabling the aggregate withdraws owned files on the next approved apply. Publish the changed human site and assets together and invalidate the host's public caches. Check its actual URLs again, including any retired mirror paths through `verify.responses`.
+
+`restore-preview` shows the owned files that restoration would remove. Run `restore` with the digest from that preview. Modified owned files produce a conflict and the command leaves their content intact. Resolve edits before retrying. The journal tracks only files created by the CLI. Empty generated directories may persist.
+
+## Operational boundaries
+
+Use an offline build or staging output under a single writer. Review first, apply, verify, then promote the complete build with the hosting platform’s deployment mechanism. The CLI checks existing path components and file digests, rejects symlinks and human-owned collisions, uses a private lock for writes and rolls back ordinary write failures. Keep a backup of the last accepted build. After a hard process or machine interruption, inspect the private recovery record and the target before resuming. The private `pending.json` includes the approved transaction digest, prior ownership, per-file before/after hashes and base64 originals. A matching transaction in `ownership.json` means the new journal was committed. Otherwise, compare each affected file to the recorded hashes before restoring an original or removing a newly created file. Preserve any unexpected human edits. Remove the recovery record and stale lock only after confirming the writer has stopped and reconciling all files. Never deploy the state directory. This executable operates independently of the app-owned capability CLI and its authorization model.

package/docs/stability.md

@@ -0,0 +1,53 @@
+# Stability and versioning
+
+From 1.0.0, Agent Native follows [semantic versioning](https://semver.org/) for its **stable** entry points. **Experimental** entry points are published and documented, but may change in a minor release. Each change appears in the [changelog](https://github.com/uppercut-labs/agent-native/blob/main/CHANGELOG.md) with a migration note.
+
+## Entry points
+
+| Import specifier | Class | Covers |
+| --- | --- | --- |
+| `@uppercut-labs/agent-native` | Stable | Definitions, bindings, registry, executor, composition, diagnostics, discovery, grants |
+| `@uppercut-labs/agent-native/contracts` | Stable | `defineCapability`, identities, risk and access |
+| `@uppercut-labs/agent-native/registry` | Stable | `bindCapability`, `createCapabilityRegistry` |
+| `@uppercut-labs/agent-native/executor` | Stable | `executeCapability`, callers, authorization port, results |
+| `@uppercut-labs/agent-native/composition` | Stable | Capability packs, aliases, migrations, surface names |
+| `@uppercut-labs/agent-native/diagnostics` | Stable | Diagnostic observations |
+| `@uppercut-labs/agent-native/auth` | Stable | Trusted principals, grant store port, grant authorization |
+| `@uppercut-labs/agent-native/schema/zod` | Stable | `fromZod` |
+| `@uppercut-labs/agent-native/http` | Stable | Public-read HTTP and OpenAPI |
+| `@uppercut-labs/agent-native/mcp` | Stable | Remote MCP over Streamable HTTP |
+| `@uppercut-labs/agent-native/cli` | Stable | Application-owned CLI runner and result schema |
+| `@uppercut-labs/agent-native/publication` | Experimental | Unreleased public-content manifest and rendering API |
+| `@uppercut-labs/agent-native/browser` | Experimental | WebMCP follows a draft browser API |
+| `@uppercut-labs/agent-native/mcp-apps` | Experimental | MCP Apps extension; no commercial host rendering is verified |
+| `@uppercut-labs/agent-native/astro` | Experimental | Framework integration tied to tested Astro releases |
+| `@uppercut-labs/agent-native/next` | Experimental | Framework integration tied to tested Next releases |
+| `@uppercut-labs/agent-native/next/browser` | Experimental | Next browser registration |
+| `@uppercut-labs/agent-native/init` | Experimental | Narrow existing-project init |
+| `@uppercut-labs/agent-native/doctor` | Experimental | Diagnostics checks and report format |
+| `@uppercut-labs/agent-native/harness` | Experimental | Provider-neutral harness contracts |
+| `@uppercut-labs/agent-native/harness/mcp-bridge` | Experimental | Loopback MCP bridge |
+| `@uppercut-labs/agent-native/harness/codex` | Experimental | Local Codex app-server adapter |
+
+Paths not listed above, such as `dist/` files, are internal and may change at any time. The package's `exports` map blocks them.
+
+## What counts as a breaking change to a stable entry point
+
+The following need a new major version:
+
+- Removing or renaming an export, or making a required parameter or option out of an optional one.
+- Narrowing an accepted input type or widening a returned type in a way that breaks existing callers.
+- Changing documented behavior a caller can rely on: execution order (input validation, then authorization, then the binding, then output validation), failure reasons, MCP tool naming by default, discovery and authorization outcomes, the result shape, and the HTTP routes and OpenAPI output for public reads.
+- Dropping support for a Node.js major line, or for a tested optional peer version line, listed in [installation](installation.md).
+
+The following can ship in a minor version: new exports, new optional options, new fields on returned objects, new failure reasons behind an existing generic client message, and support for new peer or runtime versions. Patch versions fix defects without changing documented behavior. A security fix may tighten behavior in a minor or patch release; the changelog marks it.
+
+Deprecated stable APIs keep working for at least one minor release, and until the next major, with a changelog note naming the replacement.
+
+## How the guarantee is enforced
+
+`npm run check:api` compares the declaration files reachable from every stable entry point with `api/stable-api.txt`. Any change fails the check until the baseline is regenerated with `node scripts/check-api.mjs --update` and the change is reviewed against this policy. Comment-only edits do not count. The check runs in CI as part of `npm run check`.
+
+## Runtime and peer support
+
+The package requires Node.js 22 or newer. Optional peers are pinned to the versions the test suite exercises; see [installation](installation.md). Widening a peer range to a newly tested line is a minor change.