@nullsquare/agent-authority 0.4.5 → 0.4.7

package/docs/connected-github.md

@@ -0,0 +1,140 @@
+# Connected GitHub quickstart
+
+This path is for a developer who has already understood the credential-free quickstart and now wants Agent Authority to execute through an authenticated GitHub connection.
+
+The product boundary is:
+
+```text
+GitHub token
+   |
+   v
+Agent Authority encrypted local vault
+   |
+   v
+CredentialBroker
+   |
+   v
+GitHub provider adapter
+   |
+   v
+task.execute(request)
+```
+
+The token is not placed in the task request, Mission, Task Lease, receipt, execution evidence, or public connection listing.
+
+## 1. Create a project
+
+```bash
+mkdir agent-authority-connected
+cd agent-authority-connected
+npm init -y
+npm install @nullsquare/agent-authority
+```
+
+Requires Node.js 20+.
+
+## 2. Initialize the local Agent Authority home
+
+```bash
+npx agent-authority setup
+```
+
+By default this creates `~/.agent-authority`. Provider secrets are stored in the local encrypted vault, whose files are restricted to the local user. This is a trusted-local-host developer reference backend, not a hostile-host or production KMS boundary.
+
+## 3. Connect GitHub without putting the token on the command line
+
+Use a GitHub token that has only the provider permissions your application actually needs.
+
+```bash
+printf %s "$GITHUB_TOKEN" | npx agent-authority connect github --token-stdin
+```
+
+The CLI verifies ordinary user/PAT credentials against GitHub before storing them. The token is accepted only on stdin and is written into the encrypted Agent Authority vault rather than task/model context.
+
+For CI installation tokens that do not support the `/user` verification endpoint, `--no-verify` is available for an already-trusted token source:
+
+```bash
+printf %s "$GITHUB_TOKEN" | npx agent-authority connect github --token-stdin --no-verify
+```
+
+Do not use `--no-verify` merely to bypass a failed or unknown credential.
+
+GitHub recommends fine-grained personal access tokens with minimum repository/permission scope for user-scoped access, and GitHub Apps for long-lived organization integrations. Agent Authority does not replace those provider-side controls; it adds a narrower task boundary on top of them.
+
+## 4. Run the connected task
+
+Copy `examples/quickstart-github-connected.mjs` into the project, or run the repository example from a checkout.
+
+The relevant application surface is intentionally small:
+
+```js
+import { createTask } from '@nullsquare/agent-authority/task';
+import { createRuntimeEnvironment } from '@nullsquare/agent-authority/runtime-env';
+
+const env = createRuntimeEnvironment();
+
+const task = createTask({
+  principal: env.config.principal_id,
+  agent: 'agent:assistant',
+  request: 'Inspect only acme/private',
+  permissions: {
+    github: {
+      allow: ['repo.read'],
+      constraints: {}
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: 'acme/private' }
+  },
+  bindings: [
+    { service: 'github', action: 'repo.read', field: 'repository', authority: 'repository' }
+  ],
+  runtime: env.runtime
+});
+
+const result = await task.execute({
+  service: 'github',
+  action: 'repo.read',
+  context: { repository: 'acme/private' }
+});
+```
+
+Use `task.run(request, callback)` when your application owns the provider SDK call. Use `task.execute(request)` when Agent Authority's connected provider runtime should own credential resolution and provider execution.
+
+## Standing permission vs task authority
+
+The example deliberately leaves Mission-level `github:repo.read` broad while binding the Task Lease to one repository:
+
+```text
+connected GitHub account can read repositories
+            |
+            v
+Mission permits github:repo.read
+            |
+            v
+Task authority = acme/private
+            |
+            +--> acme/private -> ALLOW -> provider executes
+            |
+            +--> acme/other   -> STEP-UP -> provider does not execute
+```
+
+That is the product value: provider/IAM permission can remain broader than the exact task without becoming ambient agent authority.
+
+## Multiple GitHub accounts
+
+If there is exactly one active GitHub connection for the principal, requests that omit `account_id` resolve that sole connection. If multiple active GitHub accounts exist, Agent Authority does not guess: set `request.account_id` explicitly. Ambiguity fails closed.
+
+## Automated proof
+
+`.github/workflows/verify-connected-github.yml` installs the packed package into a blank Node 20 project, initializes a fresh Agent Authority home, connects the workflow's GitHub installation token through stdin, and runs the connected task against the live GitHub API.
+
+The gate also checks that:
+
+- the public connection listing does not contain `credential_ref` or the token;
+- the raw token does not appear in plaintext under `AGENT_AUTHORITY_HOME`;
+- an encrypted vault file is created;
+- the unrelated repository is stopped by the Task Lease before connected provider execution;
+- ordinary test/coverage/CodeQL/live-provider gates remain separate and must still pass.
+
+The automated workflow uses the repository's GitHub Actions installation token on the current repository. That proves the authenticated brokered execution path; it does **not** claim public CI access to an unrelated private repository. A user-supplied fine-grained PAT or GitHub App token can use the same path for repositories that credential is permitted to access.

package/docs/npm-release.md

@@ -4,35 +4,55 @@ The public package name is `@nullsquare/agent-authority`.
 
 Before any publication:
 
-1. the release commit must pass CI, CodeQL, live GitHub validation, current AI SDK integration validation, and packed-consumer validation;
+1. the release commit must pass CI, CodeQL, live GitHub validation, current AI SDK integration validation, task-first utility/demo gates, and packed-consumer validation;
 2. `npm pack` must contain the documented public exports;
-3. a fresh Node.js 20 consumer must install the tarball and run the core Task Lease smoke test;
+3. a fresh Node.js 20 consumer must install the tarball and run the current public behavior smoke test;
 4. the optional AI SDK integration must import without making `ai` a production dependency;
 5. the registry package must be public and its repository metadata must point to `https://github.com/Null-Square/agent-authority`.
 
 After publication, verify from a fresh project with:
 
 ```bash
-npm install @nullsquare/agent-authority@0.4.4
+npm install @nullsquare/agent-authority@0.4.6
 ```
 
 Then run the same consumer smoke flow through the registry-installed package. Registry verification is part of the release gate; a successful `npm publish` command alone is not sufficient.
 
-The repository also includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility and a clean consumer install. For v0.4.4 it verifies the public execution-evidence and two-provider authority-extractor APIs plus the Task-Lease-aware transport surfaces:
+The repository includes `.github/workflows/verify-npm-registry.yml`, which verifies registry visibility, a clean Node.js 20 install, and current public behavior from the registry artifact.
 
-- `gmailThreadSenderAuthorityExtractor` from `@nullsquare/agent-authority/providers/google`;
-- `githubIssueListSelectedNumberAuthorityExtractor` from `@nullsquare/agent-authority/providers/github`;
-- `ExecutingAuthorityRuntime.executeTaskLease()` from `@nullsquare/agent-authority/execution`;
-- `MissionMcpGateway` from `@nullsquare/agent-authority/mcp-gateway`.
+For v0.4.6 the consumer exercises:
 
-This makes the registry artifact verification cover both the two-provider execution-evidence surface and the SDK/MCP/broker transport-invariance surface exercised by the repository conformance tests.
+- `createTask()` from `@nullsquare/agent-authority/task`;
+- explicit task permissions and named authority roots;
+- task-first allow / `authority_delta_required` behavior;
+- `task.explain()` for established-vs-requested authority deltas;
+- durable local-state opt-in through `JsonFileTaskLeaseStore` without changing normal task calls;
+- execution evidence and the reviewed Google/GitHub authority extractors;
+- `ExecutingAuthorityRuntime.executeTaskLease()` and `MissionMcpGateway` transport surfaces;
+- `JsonFileTaskLeaseStore`, `DurableTaskLeaseSession`, and the lower-level Task Lease APIs;
+- the requirement that the optional `ai` package is not installed as a production dependency.
+
+This makes the registry artifact verification cover the product-facing task-first API and the lower-level durability/evidence/transport surfaces it composes, rather than checking export names alone.
+
+The v0.4.6 independent registry verification passed after publication: npm visibility succeeded and the fresh Node.js 20 registry-installed consumer executed the current task-first + durable behavior smoke successfully.
+
+The deterministic task utility fixture is also part of the source-release gate. It currently requires:
+
+```text
+normal task completion rate = 100%
+false approval rate = 0%
+true authority-delta step-up rate = 100%
+unauthorized effect rate = 0%
+```
+
+This fixture is a regression gate, not a real-world performance benchmark.
 
 ## npm vs GitHub release surfaces
 
 Publishing to the public npm registry does not automatically create either a GitHub Release or a GitHub Packages entry.
 
 - **npm registry** — `npm publish --access public` publishes `@nullsquare/agent-authority` to `registry.npmjs.org` / npmjs.com. This is the package users install with `npm install`.
-- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.4`. A release must be created explicitly or by release automation.
+- **GitHub Releases** — a separate GitHub object, normally backed by a Git tag such as `v0.4.6`. A release must be created explicitly or by release automation.
 - **GitHub Packages** — a separate package registry. It only appears when the package is published to GitHub's npm registry (`npm.pkg.github.com`); publishing to npmjs.com does not populate it.
 
 Agent Authority currently uses npmjs.com as its public package registry. Therefore an empty GitHub **Packages** section is expected unless the project intentionally adopts dual publication. A GitHub **Release** is still useful for source-release discoverability and should track published versions, but it is independent from npm publication.

package/docs/product-proof.md

@@ -0,0 +1,311 @@
+# Product proof gate
+
+Agent Authority has enough security machinery to validate its core thesis. The next risk is no longer "can we make the invariant stronger?" It is "will an agent developer actually install and keep this layer?"
+
+The product thesis is:
+
+> **Your agent may use the permissions it already has only for the task the user actually gave it.**
+
+The differentiated mechanism is narrower:
+
+> **Authority may follow exact resources discovered through already-authorized execution, without turning those resources into standing account permissions.**
+
+Everything else in the repository exists to make those two statements true.
+
+## Developer mental model
+
+The preferred public experience should stay close to three concepts:
+
+```text
+Task -> Effect -> Authority
+```
+
+A developer should not need to understand Mission internals, Task Lease hashing, execution evidence envelopes, CAS persistence or transport adapters before getting value.
+
+Those primitives remain available for advanced integrations and audits.
+
+## Product-facing API
+
+The task-first facade intentionally composes the existing primitives instead of replacing them:
+
+```js
+import { createTask } from '@nullsquare/agent-authority/task';
+
+const task = createTask({
+  principal: 'user:me',
+  agent: 'agent:assistant',
+  request: 'Handle issue #42',
+  permissions: {
+    github: {
+      allow: ['issue.list', 'issue.comment'],
+      deny: ['repo.delete'],
+      constraints: { repository: ['acme/app'] }
+    }
+  },
+  authority: {
+    repository: { kind: 'github.repository', value: 'acme/app' }
+  }
+});
+
+const discovery = await task.run(request, () => github.listIssues());
+const issue = task.authorityFrom(discovery, {
+  name: 'issue',
+  kind: 'github.issue.number',
+  from: 'repository',
+  extractor
+});
+
+task.bind({
+  service: 'github',
+  action: 'issue.comment',
+  field: 'issue_number',
+  authority: 'issue'
+});
+```
+
+The low-level Mission and Task Lease APIs remain the source of truth. The facade must never add authority that those lower layers would reject.
+
+## Adoption gate
+
+Do not prioritize another deep authorization subsystem until the following are demonstrated:
+
+- [ ] a new developer can run a meaningful task-first example in under 10 minutes;
+- [ ] at least three real workflow examples exist: coding, support/communications, and operations/finance;
+- [x] the same task-first API works in-memory and with durable local state;
+- [x] useful-task completion stays high under the deterministic product benchmark;
+- [x] normal fixture task actions do not trigger unnecessary approvals;
+- [x] unrelated-resource effects execute zero provider callbacks in the deterministic fixture, live GitHub proof, support/communications proof, and operations/finance proof;
+- [x] approval/step-up output explains the established authority and requested delta clearly;
+- [ ] at least one external developer uses the package without project-author assistance.
+
+The checked utility items are evidence about the current deterministic fixtures and live GitHub proof, not a claim that arbitrary real-world agent workloads have already met the same rates.
+
+## First live provider product proof
+
+The existing GitHub Actions mutation validation now runs through the public task-first API rather than hand-assembling Mission + Task Lease + Guard.
+
+The live workflow uses:
+
+```text
+createTask()
+   |
+   v
+task.run(issue.list)
+   |
+   v
+task.authorityFrom(reviewed GitHub output)
+   |
+   v
+issue #9 becomes downstream task authority
+   |
+   +--> task.run(issue.comment #9) -> real GitHub mutation
+   +--> task.run(issue.comment #1) -> STEP-UP, zero provider mutation
+   |
+   v
+task.complete()
+   |
+   v
+issue.comment #9 -> DENY, zero provider mutation
+```
+
+Passing CI evidence from the live run:
+
+- repository root: `Null-Square/agent-authority`;
+- reviewed fixture selection: issue `#9`;
+- `task.authorityFrom()` established issue `#9` as downstream authority;
+- exactly one real GitHub comment mutation executed;
+- unrelated issue `#1` produced `authority_delta_required` before provider mutation;
+- `task.explain()` reported established authority `9` vs requested value `1`;
+- the same issue was denied after `task.complete()`;
+- provider calls before cleanup: `reads=1`, `task_mutations=1`;
+- the temporary validation comment was deleted outside the authority proof.
+
+This establishes a real-provider product proof for the facade, but it is **not yet** the full coding-agent product workflow. Branch creation, file edits and PR creation still need to be chained under task-derived authority while merge/deploy remain outside the task.
+
+## Cross-provider support/communications proof
+
+`examples/task-first-support.js` exercises the same public facade across two service boundaries using the exact field names and normalized sender shape used by the Google adapter:
+
+```text
+Task: handle one customer email and schedule the requested meeting
+
+origin thread authority
+      |
+      v
+task.run(gmail:thread.read)
+      |
+      v
+reviewed Gmail sender extractor
+      |
+      v
+customer@example.com
+      |
+      v
+task.bind(calendar:event.create.attendee_email)
+      |
+      +--> exact customer meeting -> ALLOW
+      +--> unrelated attendee -> STEP-UP, zero Calendar callbacks
+      |
+      v
+task.complete() -> same meeting authority no longer usable
+```
+
+The task also binds the Gmail `thread_id` and Calendar `calendar_id` to explicit task-entry roots. A different Gmail thread is stopped before its callback runs.
+
+The example and `test/task-product-support.test.js` run on Node 20 and Node 22 CI. The support proof demonstrates that the task-first model crosses Gmail -> Calendar without a second authorization abstraction.
+
+This is intentionally a **self-contained product proof**. It mirrors the real Google provider contract but does not close the separate public Google Actions evidence gate; that gate still requires repository OAuth secrets.
+
+## Operations / finance lineage proof
+
+`examples/task-first-finance.js` exercises a longer evidence-derived authority chain without adding another provider, policy DSL, or numeric relation language:
+
+```text
+Task: resolve one support ticket by refunding only its payment
+
+ticket:481
+   |
+   v
+task.run(helpdesk:ticket.read)
+   |
+   v
+order:991
+   |
+   v
+task.run(orders:order.read)
+   |
+   v
+payment:abc123
+   |
+   v
+task.run(payments:payment.read)
+   |
+   +--> amount = 12500 minor units
+   +--> currency = USD
+   |
+   v
+task.bind(refund payment_id + amount + currency)
+   |
+   +--> exact full refund -> ALLOW
+   +--> another payment -> STEP-UP, zero refund callbacks
+   +--> over-refund -> STEP-UP, zero refund callbacks
+   +--> wrong currency -> STEP-UP, zero refund callbacks
+   +--> partial refund -> STEP-UP under current exact binding model
+   |
+   v
+task.complete() -> same refund authority no longer usable
+```
+
+The task cannot read an arbitrary order before the ticket establishes the order fact: the unresolved binding fails closed before the order callback runs. The same pattern continues through payment and refund.
+
+The example and `test/task-product-finance.test.js` run on Node 20 and Node 22 CI. On the passing fixture, provider-shaped callbacks are exactly one ticket read, one order read, one payment read and one refund.
+
+This proof intentionally exposes a **product limitation rather than hiding it behind new policy machinery**: Task Lease bindings currently require exact equality. Therefore the payment amount `12500` can authorize an exact `12500` refund, but a legitimate partial refund such as `5000` also produces `authority_delta_required`. A future narrow `requested amount <= evidence-derived payment amount` relation may be justified if real provider/adoption evidence shows partial refunds are needed. Until then, the repository should keep this limitation visible instead of adding a general expression language speculatively.
+
+## Utility metrics
+
+Security tests remain required, but product work should additionally track:
+
+```text
+normal task completion rate
+false approval rate
+true authority-delta step-up rate
+unauthorized effect rate
+provider effects per completed task
+integration lines required for a representative workflow
+```
+
+`npm run benchmark:task` is the first deterministic fixture for these metrics. It is not a real-world benchmark and must not be marketed as one. Its purpose is to make utility regressions visible alongside security regressions.
+
+The current fixture target is:
+
+```text
+normal task completion rate = 100%
+false approval rate = 0%
+true authority-delta step-up rate = 100%
+unauthorized effect rate = 0%
+```
+
+The current fixture run contains 40 normal tasks and 10 unrelated-resource attempts. Real provider/harness benchmarks should replace or supplement it as the product matures.
+
+## Three product proofs
+
+### Coding agent
+
+Task:
+
+> Fix issue #42 and open a PR. Do not merge or deploy.
+
+Desired authority lineage:
+
+```text
+repository -> issue -> task branch -> changed files -> pull request
+```
+
+Unrelated repositories, issues, merge and deploy remain outside the task.
+
+The live issue-discovery -> exact-issue-comment proof is the first slice of this direction; it does not complete the branch/files/PR lineage yet.
+
+### Support / communications agent
+
+Task:
+
+> Handle this customer email.
+
+Desired authority lineage:
+
+```text
+email thread -> customer -> meeting / CRM record / reply target
+```
+
+The self-contained Gmail-thread -> exact Calendar-attendee slice is now established. The next value proof should connect the same customer authority to another useful downstream action (for example reply/CRM) or rerun the task-first flow with the real Google Actions fixture once repository OAuth secrets are available.
+
+### Operations / finance agent
+
+Task:
+
+> Resolve this ticket and refund the affected order.
+
+Desired authority lineage:
+
+```text
+ticket -> customer -> order -> payment -> refund <= original payment
+```
+
+The self-contained ticket -> order -> payment -> **exact full refund** lineage is now established. The remaining product question is narrower than the original workflow: whether partial refunds are important enough to justify one evidence-derived numeric ceiling relation. Current exact bindings intentionally step up for a smaller amount rather than guessing that relation into the core.
+
+## Freeze list
+
+Until the adoption gate moves, the following remain research backlog unless a real workflow proves they are blocking adoption or safety:
+
+- distributed Task Lease databases;
+- generic storage abstraction layers;
+- provider-signed attestation protocols;
+- another token or identity format;
+- a general delegation standard;
+- a proprietary policy DSL;
+- broad OAuth/OIDC platform work;
+- another MCP control plane;
+- A2A protocol implementation;
+- large connector-count expansion;
+- full distributed transaction semantics across arbitrary remote providers.
+
+The existing durability, evidence, transport and credential primitives should be reused rather than deepened by default.
+
+## Boundary discipline
+
+Agent Authority should integrate with identity providers, OAuth systems, MCP gateways, policy engines and agent frameworks rather than compete with all of them.
+
+The intended position is:
+
+```text
+agent reasoning
+      |
+      v
+Agent Authority
+      |
+      v
+existing SDK / MCP / gateway / OAuth / provider
+```
+
+The product wins if that middle layer is small to adopt, preserves useful autonomy, and technically prevents the same standing account permission from becoming unrelated task authority.

package/docs/quickstart.md

@@ -0,0 +1,147 @@
+# Fresh-install quickstart
+
+This quickstart is for a developer who wants to understand Agent Authority before connecting an account or learning Mission/Task Lease internals.
+
+It uses the real public task-first API and the reviewed GitHub issue-number authority extractor from the published npm package. The first provider callback is a local provider-shaped fixture, so **no GitHub token, OAuth setup, repository checkout, or custom extractor is required**.
+
+## 1. Create a blank project
+
+```bash
+mkdir agent-authority-quickstart
+cd agent-authority-quickstart
+npm init -y
+npm install @nullsquare/agent-authority
+```
+
+Requires Node.js 20+.
+
+## 2. Get the credential-free fixture quickstart
+
+Download or copy `examples/quickstart.mjs` from this repository into the blank project as `quickstart.mjs`.
+
+For example on macOS/Linux:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Null-Square/agent-authority/main/examples/quickstart.mjs -o quickstart.mjs
+```
+
+The file imports only published package exports:
+
+```js
+import { createTask } from '@nullsquare/agent-authority/task';
+import { AuthorityApprovalRequiredError } from '@nullsquare/agent-authority/guard';
+import { githubIssueListSelectedNumberAuthorityExtractor } from '@nullsquare/agent-authority/providers/github';
+```
+
+## 3. Run it
+
+```bash
+node quickstart.mjs
+```
+
+Expected shape:
+
+```text
+ALLOW -> task discovered issue #42 and the exact comment effect ran
+STEP-UP -> The task established authority for 42 but this action requested 7.
+PASS -> useful task work ran; unrelated standing permission did not become task authority
+```
+
+## What happened
+
+The task starts with authority over one repository and one task-selection marker:
+
+```text
+repository + marker
+      |
+      v
+authorized issue discovery
+      |
+      v
+reviewed extractor + execution evidence
+      |
+      v
+issue #42 becomes downstream task authority
+      |
+      +--> comment on #42 -> ALLOW
+      +--> comment on #7  -> STEP-UP before callback
+```
+
+The important point is not the fixture itself. It is that the callback which represents the provider effect executes for the task-derived issue and does **not** execute for the unrelated issue even though the Mission-level GitHub permission includes `issue.comment`.
+
+The quickstart counts callbacks and fails if the unrelated effect executes.
+
+## 4. Next step: call real GitHub with no credential
+
+The second quickstart uses the same published package in the same blank project, but the callback now makes a real network request to GitHub's public API.
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/Null-Square/agent-authority/main/examples/quickstart-github-live.mjs -o quickstart-github-live.mjs
+node quickstart-github-live.mjs
+```
+
+Default behavior:
+
+```text
+Standing GitHub permission -> repo.read
+Task authority -> Null-Square/agent-authority
+GitHub mode -> public API; no credential required
+ALLOW -> real GitHub returned Null-Square/agent-authority
+STEP-UP -> The task established authority for "Null-Square/agent-authority" but this action requested "octocat/Hello-World".
+PASS -> broader standing repo.read permission could not reach an unrelated repository for this task
+```
+
+This example deliberately models the **standing capability as broader than the task**. Mission-level `github:repo.read` is allowed without a repository constraint. The Task authority root then binds `repo.read` to exactly `Null-Square/agent-authority`.
+
+The allowed request performs one real `fetch()` to GitHub. The unrelated repository request reaches the Task authority check, becomes `authority_delta_required`, and does not execute a second `fetch()`.
+
+You can inspect another public repository by passing it as the first argument:
+
+```bash
+node quickstart-github-live.mjs owner/repository
+```
+
+An optional `GITHUB_TOKEN` may be supplied for authenticated GitHub API access, but no token is required for the default public-repository path.
+
+## Replace the fixture with your provider call
+
+The first quickstart's discovery callback is the only intentionally fake provider piece:
+
+```js
+const discovery = await task.run(request, async () => {
+  return providerShapedOutput;
+});
+```
+
+In an application, keep the Agent Authority request and replace the callback with the SDK/provider call you already use. For the built-in GitHub extractor, use the normalized output produced by the Agent Authority GitHub adapter. If your provider/output shape is different, use a reviewed extractor for that mapping rather than trusting arbitrary model-selected values.
+
+The live GitHub quickstart shows the even simpler direct-boundary case: an application can put its existing `fetch()` or SDK call inside `task.run()` while Task authority remains narrower than the standing account/app capability.
+
+## Evidence boundaries
+
+The credential-free fixture is an **adoption quickstart**, not a live-provider security proof. The live GitHub quickstart is a real-provider onboarding proof, but it is read-only and uses a public repository by default.
+
+Separate repository evidence already covers:
+
+- a real GitHub issue discovery -> exact issue comment mutation through the task-first API;
+- Gmail sender -> Calendar attendee authority;
+- SDK, MCP and broker transport invariance;
+- durable local Task Lease recovery/session behavior;
+- adversarial execution-evidence tests.
+
+The public Gmail -> Calendar GitHub Actions proof remains separately gated on repository Google OAuth secrets. Authenticated/private-repository onboarding and production OAuth/KMS UX also remain separate product work.
+
+## Automated fresh-install gates
+
+`.github/workflows/verify-quickstart.yml` repeats the fixture developer path in a blank temporary project:
+
+1. resolve the latest public `@nullsquare/agent-authority` version from npm;
+2. create a new empty npm project;
+3. install only that registry package;
+4. copy the quickstart file;
+5. confirm the optional AI SDK was not installed;
+6. run `node quickstart.mjs`.
+
+`.github/workflows/verify-live-quickstart.yml` repeats the real-provider path from another blank Node 20 project and requires exactly one live GitHub request before the unrelated repository is blocked.
+
+Both gates have passed against `@nullsquare/agent-authority@0.4.6`. They catch documentation/example drift against the actually published package. They do **not** substitute for timing a first-time external developer, so the roadmap's under-10-minute human adoption gate remains open until that evidence exists.