ai-capability-framework 1.1.0-rc.1 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable public changes to AI Capability Framework are documented here.
 
 ## Unreleased
 
+## 1.1.0 - 2026-10-17
+
+- Fixed the installed CLI's POSIX symlink entrypoint so `npx aicf` runs commands instead
+  of silently returning. Programmatic CLI imports remain side-effect-free.
+
+- Stabilized the recommended lexical/native search-to-tool workflow and its named
+  runtime/provider contracts. Advanced APIs retain their documented maturity; hybrid
+  remains experimental and dedicated selection optional.
+- Made installed-package onboarding primary, with a complete manifest and mock app
+  checked directly from the published documentation in fresh consumers.
+- Corrected obsolete checkout-only guidance and a nonexistent registry-helper import.
+  Retrieval behavior, authorization, approval boundaries and model configuration are
+  unchanged. Frozen qualification evidence is reused without new live trials.
+
 ## 1.1.0-rc.1 - 2026-10-17
 
 - Published discovery as release-candidate public, with lexical retrieval and ordinary

package/README.md

@@ -110,40 +110,23 @@ In plain terms:
 
 ## Try It
 
-Install and validate the public examples:
+Start in a new project:
 
-```bash
-npm install
-npm run validate
-```
-
-Build the CLI and inspect the example registry:
-
-```bash
-npm run build
-node dist/cli.js inspect examples
-```
-
-Export OpenAI Responses function tools without calling a model:
-
-```bash
-node dist/cli.js openai-tools examples --context examples/support/openai/context.support_agent.json
-```
-
-Run the public mock runtime flow:
-
-```bash
-node examples/runtime-support-billing/run-mock.mjs
+```sh
+npm init -y
+npm install ai-capability-framework
+node node_modules/ai-capability-framework/examples/12-capability-discovery-selection/run-customer-mock.mjs
 ```
 
-Run deterministic evals:
-
-```bash
-node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
-```
+The mock flow reads a ticket, carries its order ID into refund preparation, and returns
+a preview awaiting approval. It exposes no commit and makes no real provider calls. No
+repository checkout, framework build or optional provider SDK is required.
 
-For expected output excerpts and what each command proves, use
-[Start here](docs/start-here.md).
+Follow the
+[complete first-app walkthrough](docs/getting-started/provider-neutral-quickstart.md) to
+author a capability, load a registry, register a handler and use the stable
+lexical/native workflow. [Repository development](docs/development.md) has separate
+build and validation commands.
 
 ## Documentation Map
 
@@ -300,10 +283,10 @@ MIT
 
 ## Find capabilities for a task
 
-Install the discovery prerelease explicitly:
+Install the stable framework:
 
 ```sh
-npm install ai-capability-framework@1.1.0-rc.1
+npm install ai-capability-framework
 ```
 
 Lexical retrieval with the ordinary model/tool loop is the recommended default. The
@@ -311,11 +294,12 @@ Lexical retrieval with the ordinary model/tool loop is the recommended default.
 results and the unmet hybrid incremental-gain gate. Hybrid remains experimental and
 opt-in; dedicated selection remains optional.
 
-Use the optional release-candidate [discovery API](docs/discovery.md) when your
-application AI decomposes a customer request into tasks. Search each ready task and pass
-its result-bound router to the ordinary model/tool loop. Lexical search needs only a
-registry, task IDs/text, and existing runtime context. Hybrid retrieval and dedicated
-selection are optional and require caller-supplied model access and budgets.
+Use the [stable lexical/native workflow](docs/api/stable-workflow.md) and optional
+[discovery API](docs/discovery.md) when your application AI decomposes a customer
+request into tasks. Search each ready task and pass its result-bound router to the
+ordinary model/tool loop. Lexical search needs only a registry, task IDs/text, and
+existing runtime context. Hybrid retrieval and dedicated selection are optional and
+require caller-supplied model access and budgets.
 
 Run the
 [complete customer-request example](examples/12-capability-discovery-selection/README.md)

package/ROADMAP.md

@@ -27,11 +27,14 @@ systems, credentials, side effects, and deployment.
 
 ## Capability Discovery
 
-The optional release-candidate discovery API supports application-produced tasks,
-eligible shortlists, and ordinary model tool selection. Hybrid retrieval and dedicated
-selection remain explicit. No-key examples, a frozen synthetic dataset, and packed
-consumer checks cover integration. The tested synthetic configuration qualifies both
-lexical modes after an offline wording correction. Lexical/native is recommended; hybrid
-remains experimental because incremental benefit was not qualified. See the
+The stable lexical/native workflow supports application-produced tasks, eligible
+shortlists, and ordinary model tool selection. Hybrid retrieval and dedicated selection
+remain explicit. No-key examples, a frozen synthetic dataset, and packed consumer checks
+cover integration. The tested synthetic configuration qualifies both lexical modes after
+an offline wording correction. Lexical/native is recommended; hybrid remains
+experimental because incremental benefit was not qualified. See the
 [qualification report](docs/evals/discovery-qualification.md). Application-specific
-qualification and adoption remain separate from prerelease publication.
+qualification and adoption remain separate from framework publication. Normal npm
+installation includes the stable workflow; advanced features retain their own maturity
+labels. The active framework roadmap is complete when installed-package usability and
+verified stable publication pass; application migrations are outside its scope.

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAuGA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC7C,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAC9C;AA4BD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+SzF"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAwGA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAC7C,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;CAC9C;AA4BD,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CA+SzF"}

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import YAML from "yaml";
@@ -2165,5 +2166,10 @@ function isDirectCliRun() {
     if (!invokedPath) {
         return false;
     }
-    return path.resolve(invokedPath) === fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(invokedPath) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
 }

package/dist/discovery/index.d.ts

@@ -1,4 +1,4 @@
-/** Optional, release-candidate public capability discovery API. */
+/** Stable lexical/native facade; advanced APIs retain their documented maturity. */
 export { ModelCapabilitySelector } from "./selection.js";
 export { buildCapabilitySelectionTasks } from "./selection-cards.js";
 export type { BuildCapabilitySelectionTasksRequest } from "./selection-cards.js";

package/dist/discovery/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/discovery/index.ts"],"names":[],"mappings":"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"}

package/dist/discovery/index.js

@@ -1,4 +1,4 @@
-/** Optional, release-candidate public capability discovery API. */
+/** Stable lexical/native facade; advanced APIs retain their documented maturity. */
 export { ModelCapabilitySelector } from "./selection.js";
 export { buildCapabilitySelectionTasks } from "./selection-cards.js";
 export { createCapabilityDiscovery, DISCOVERY_STANDARD_PROFILE } from "./facade.js";

package/docs/api/public-api-policy.md

@@ -47,12 +47,15 @@ cloud, tracing, or CLI implementation dependencies.
 | CLI implementation helpers other than `runCli` and `CliRunOptions`                                                                                                                                                                                          | should move to subpath              | Keep private to the CLI module unless a future release documents a narrow public contract.                                                                  |
 | Undocumented source files, generated internals, and private helper functions                                                                                                                                                                                | should be removed before v1         | Do not expose through package exports.                                                                                                                      |
 
-The `ai-capability-framework/discovery` subpath is **release-candidate public**. It
-contains the documented facade, advanced retrieval/index/selection/replay contracts,
-budget helper, and evaluation API. Provider adapters stay in their existing subpaths.
-Discovery is optional and adds no implementation dependency to root/runtime imports. Its
-interface classification does not establish real-model retrieval quality. See
-[capability discovery](../discovery.md).
+The [named lexical/native workflow](stable-workflow.md) is **stable public from 1.1.0**,
+including its documented runtime/provider dependencies. Member-specific classifications
+override the broad subpath rows above; they do not stabilize every export in those
+modules. Advanced discovery remains **release-candidate public** and hybrid remains
+experimental. It contains the documented facade, advanced
+retrieval/index/selection/replay contracts, budget helper, and evaluation API. Provider
+adapters stay in their existing subpaths. Discovery is optional and adds no
+implementation dependency to root/runtime imports. Its interface classification does not
+establish real-model retrieval quality. See [capability discovery](../discovery.md).
 
 ## Migration Note For Release-Candidate Users
 

package/docs/api/stable-workflow.md

@@ -0,0 +1,58 @@
+# Stable search-to-tool workflow
+
+Starting with 1.1.0, the recommended lexical/native integration is a **stable public
+contract**. Compatible updates preserve the documented imports, request/result fields
+and behavior below. Removing or incompatibly changing these contracts requires a major
+version. Additive fields and new diagnostics may appear; consumers should tolerate them.
+
+This commitment applies to the named members and configurations, not every export in a
+mixed-maturity subpath. It does not guarantee retrieval accuracy for your application.
+See the [tested qualification and limits](../evals/discovery-qualification.md).
+
+## Stable members
+
+| Surface                           | Stable members and supported use                                                                                                                                                                                                                                                                                                                  |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Core                              | Existing manifest loading, validation, registry and descriptor contracts, including `loadManifests`, `validateManifests`, `buildRegistry` and `toOpenAIResponsesToolName`.                                                                                                                                                                        |
+| Discovery                         | `createCapabilityDiscovery` in lexical mode; `search`; `routerFor(result)` using the issued discovery result.                                                                                                                                                                                                                                     |
+| Discovery types                   | The lexical fields of `CapabilityDiscoveryOptions`; `CapabilitySearchRequest`, `CapabilityDiscoveryEligibility`, `CapabilityDiscoveryResult`, `RankedCapabilityCandidate`, `CapabilityResultRouter` and their documented standard diagnostics, usage and binding fields. Advanced fields/overloads retain the status below.                       |
+| Runtime context and routing       | `AicfRuntimeContext`, `DefaultContextBuilder`, `AicfContextBuilder`, `AicfCapabilityRouter`, `CapabilityRouteRequest`, `CapabilitySlice` and the tool-execution request/result contracts used by the walkthrough.                                                                                                                                 |
+| Runtime execution                 | Construction and the demonstrated `register`, `get`, `execute`, `evaluate` and `prepare` operations on `AicfHandlerRegistry`, `AicfToolExecutor`, `AicfActionLifecycleManager` and `DefaultPolicyBroker`; preparation/preview and approval requirements remain supported. Commit/approval administration is outside this newly stabilized subset. |
+| Reference stores                  | The approval, idempotency and prepared-action interfaces and `InMemoryApprovalStore`, `InMemoryIdempotencyStore`, `InMemoryPreparedActionStore` used by the read/prepare recipe. These implementations are single-process examples, not durable production storage.                                                                               |
+| Ordinary OpenAI-compatible runner | `runOpenAIResponses` with the lexical result router and the basic fields of `AicfOpenAIRunRequest`, `AicfOpenAIRunResult`, `AicfOpenAIResponsesClient`; `MockOpenAIResponsesClient`, `mockFunctionCallResponse` and `mockTextResponse` for deterministic tests. Other provider adapters keep their existing classification.                       |
+
+## Behavior you can rely on
+
+- The minimal discovery configuration needs only a registry. Search accepts ordered task
+  IDs/text and existing runtime context, with the documented context-builder,
+  eligibility, controls, cancellation and earlier-deadline options.
+- Default retrieval is lexical, bounded to eight candidates with positive-score
+  admission, no alias bonus/diversity and a 30-second deadline shortened by the caller.
+  Search purchases no provider work and never enables hybrid or dedicated selection.
+- Results preserve task identity and input order. `matched`, `no_match`, `unavailable`
+  and `cancelled` remain distinct. Invalid caller input produces `DiscoveryError`;
+  operational outcomes do not choose a fallback candidate automatically.
+- Result-bound routers reuse the issued shortlist without ranking or embedding again.
+  They reject foreign/reconstructed results and revalidate task, invocation, source,
+  eligibility, controls, cancellation and deadline before export and dispatch.
+- Runtime validation and authorization govern execution. Preparation can produce a
+  preview requiring approval; model-facing routers never expose commit operations.
+- Unknown usage remains distinguishable from zero. Fingerprints are opaque, versioned
+  compatibility bindings, not confidence estimates or durable request handles.
+
+Applications own decomposition, dependencies, argument completion, authentication,
+handler resource access checks and customer responses. No model, credentials, prices,
+production database or authorization service is supplied.
+
+## Advanced features retain their boundaries
+
+Dedicated selection is optional and its advanced selector contracts remain
+release-candidate public. Hybrid retrieval is **experimental and opt-in**, including
+index/client configuration; its incremental-gain qualification gate was not met. Custom
+rankers, low-level discovery/index APIs, selection-batch routing, shared provider runs,
+tracing, replay and evaluation retain their existing documented maturity. Their presence
+on the same facade or subpath does not promote them automatically.
+
+Start with the
+[installed-package walkthrough](../getting-started/provider-neutral-quickstart.md). The
+[API policy](public-api-policy.md) describes the remaining surfaces.

package/docs/development.md

@@ -0,0 +1,22 @@
+# Repository development
+
+Package users should start with the
+[installed-package quickstart](getting-started/provider-neutral-quickstart.md). You do
+not need a checkout, TypeScript compiler or provider SDK to run its mock flow.
+
+For work on the framework itself, clone the public repository and run from its root:
+
+```sh
+npm ci
+npm run check:generated
+npm run build
+npm run validate
+```
+
+Use `VITEST_MAX_WORKERS=2` when running `npm run check` or certification, as configured
+in CI. Framework development checks are provider-free; live evaluation requires an
+explicit opt-in and separate model access/budget. See [release checks](release.md).
+
+The repository currently validates 16 manifests and 21 recognized fixtures. Additional
+capabilities inside evaluation fixtures do not expand the normal manifest inventory.
+Generated docs, tarballs and local evidence belong in ignored or temporary paths.

package/docs/discovery.md

@@ -1,8 +1,9 @@
 # Find capabilities for a task
 
-Install the release-candidate package with
-`npm install ai-capability-framework@1.1.0-rc.1`. Lexical retrieval with ordinary model
-tool selection is the recommended default.
+Install with `npm install ai-capability-framework`. The lexical/native workflow is
+[stable public from 1.1.0](api/stable-workflow.md) and is the recommended default. For a
+complete first app, use the
+[installed-package quickstart](getting-started/provider-neutral-quickstart.md).
 
 ```ts
 import { createCapabilityDiscovery } from "ai-capability-framework/discovery";
@@ -27,14 +28,14 @@ returns a shortlist → ordinary model/tool loop chooses → runtime validates a
 executes**. Applications own decomposition, task dependencies, argument completion, and
 customer responses. Search each dependent task when its context is ready.
 
-Discovery is an optional **release-candidate public API**. It does not change
+The named lexical/native facade is **stable public**. Advanced discovery APIs retain
+their [individual maturity labels](api/stable-workflow.md). Discovery does not change
 `DefaultCapabilityRouter`. Results contain eligible candidates, scores, diagnostics,
 usage, and version bindings. A useful shortlist is the goal; neither ranking first nor a
 high score authorizes execution or guarantees a suitable tool.
 
-Until a release includes this subpath, use a locally packed tarball for
-installed-package examples. The unreleased source and tarball checks do not publish a
-new npm version.
+The stable npm package includes this subpath; no checkout, framework build or locally
+packed tarball is required.
 
 ## Defaults and result handling
 
@@ -62,13 +63,7 @@ operations are never exposed through discovery routers.
 
 ## Complete no-key example
 
-Run from a source checkout after `npm run build`:
-
-```sh
-node examples/12-capability-discovery-selection/run-customer-mock.mjs
-```
-
-For an installed package, run the packaged example from your project directory:
+Run the packaged example from your project directory after installation:
 
 ```sh
 node node_modules/ai-capability-framework/examples/12-capability-discovery-selection/run-customer-mock.mjs

package/docs/evals/discovery-qualification.md

@@ -1,5 +1,10 @@
 # Discovery qualification for 1.1.0-rc.1
 
+Stable 1.1.0 reuses these frozen observations without new live trials or retrieval
+changes. The [named lexical/native workflow](../api/stable-workflow.md) now has a stable
+compatibility commitment; the historical prerelease classification below describes the
+assessed release. Hybrid qualification is unchanged.
+
 Lexical retrieval with ordinary model tool selection (**lexical/native**) is the
 recommended default. Lexical/dedicated also qualified for the tested configuration; it
 remains an optional additional model call. Hybrid/native and hybrid/dedicated remain

package/docs/getting-started/installation.md

@@ -1,21 +1,20 @@
 # Installation
 
-Install the public package:
+Use Node.js 20, 22 or 24. Install the stable package in your application:
 
-```bash
+```sh
 npm install ai-capability-framework
 ```
 
-For repository development:
+Version 1.1.0 includes the stable lexical/native search-to-tool workflow. The
+[complete quickstart](provider-neutral-quickstart.md) runs with deterministic mocks,
+without a provider SDK, API key, repository checkout or framework build.
 
-```bash
-npm ci
-npm run build
-npm run validate
-```
+Live calls require caller-supplied model access and explicit configuration. Optional
+SDKs are installed only when your chosen provider integration needs them.
 
-The default examples use fake data and do not call live model providers. Live provider
-tests are opt-in and require explicit environment variables documented in the provider
-guides.
+For reproducible deployments, pin the tested version in your lockfile. Existing
+prereleases remain available by explicit version; `next` is a separate channel.
 
-Next: [Quickstart](quickstart.md).
+[Framework repository development](../development.md) has separate install/build/check
+commands.

package/docs/getting-started/openai-quickstart.md

@@ -20,28 +20,39 @@ npm install openai
 Root and runtime imports remain lightweight:
 
 ```ts
-import { loadRegistryFromPath } from "ai-capability-framework";
+import {
+  loadManifests,
+  validateManifests,
+  buildRegistry
+} from "ai-capability-framework";
 import { runOpenAIResponses } from "ai-capability-framework/openai";
 ```
 
+Load and validate your manifests with `loadManifests` and `validateManifests`, then pass
+them to `buildRegistry`; the [complete quickstart](provider-neutral-quickstart.md) shows
+runnable code.
+
 ## Mock-Tested Flow
 
-Run the existing mock runtime tests:
+Run the installed no-key customer flow:
 
 ```bash
-npm run test:openai:mock
+node node_modules/ai-capability-framework/examples/12-capability-discovery-selection/run-customer-mock.mjs
 ```
 
 Expected output excerpt:
 
 ```text
-Test Files ... passed
+"ordinaryModelTurns": 4
 ```
 
 The OpenAI runtime exports only routed read/prepare tools. Commit tools remain
 host-controlled through AICF action lifecycle APIs.
 
-## Live Opt-In
+## Repository development and live opt-in
+
+The commands below are for an optional [framework source checkout](../development.md).
+Normal package consumers supply their own configured client and explicit model.
 
 Live tests are skipped unless you explicitly opt in:
 

package/docs/getting-started/provider-neutral-quickstart.md

@@ -1,106 +1,265 @@
 # Provider-Neutral Quickstart
 
-Use this path first if you want to understand AICF without choosing a model provider. It
-uses the public support/refund examples and does not require API keys, provider SDKs,
-live calls, or credentials.
+Start in an empty project with Node.js 20, 22 or 24 and npm. This walkthrough uses
+synthetic data and a deterministic mock model: no API key, provider SDK, source checkout
+or framework build is required.
 
-## What You Will Prove
+## 1. Install
 
-- Capability manifests can describe app functionality without provider-specific schemas.
-- AICF can validate the registry and inspect the capability set.
-- Deterministic decisions and evals run without calling a model.
-- Provider adapters are optional layers over the same AICF contracts.
-
-## 1. Install And Build
-
-```bash
-npm ci
-npm run build
+```sh
+mkdir aicf-example
+cd aicf-example
+npm init -y
+npm install ai-capability-framework
 ```
 
-Expected output excerpt:
-
-```text
-added ... packages
-tsc -p tsconfig.json
+The stable package includes discovery. Your ordinary model/tool loop chooses among
+eligible tools; lexical discovery makes no model or embedding calls.
+
+## 2. Describe your capability
+
+Create a `capabilities` directory. Save this as `capabilities/ticket.json`:
+
+```json
+{
+  "schema_version": "1.0",
+  "id": "support.ticket.get",
+  "version": "1.0.0",
+  "status": "active",
+  "name": "Read support ticket",
+  "summary": "Read a support ticket by ticket ID.",
+  "model_description": "Read a synthetic ticket the current user is allowed to view. Does not change data.",
+  "capability_type": "read_data",
+  "autonomy_tier": "A1",
+  "risk_tier": "low",
+  "input_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["ticket_id"],
+    "properties": { "ticket_id": { "type": "string", "pattern": "^TCK-[0-9]+$" } }
+  },
+  "output_schema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["ticket_id", "status"],
+    "properties": { "ticket_id": { "type": "string" }, "status": { "type": "string" } }
+  },
+  "side_effects": {
+    "reads_data": true,
+    "writes_data": false,
+    "creates_records": false,
+    "updates_records": false,
+    "deletes_records": false,
+    "sends_external_messages": false,
+    "charges_money": false,
+    "refunds_money": false,
+    "changes_permissions": false,
+    "triggers_external_workflow": false,
+    "irreversible": false
+  },
+  "authorization": {
+    "permissions": ["ticket.read"],
+    "tenant_scoped": true,
+    "requires_user_context": true
+  },
+  "policy": { "approval_required": false, "max_autonomy_tier": "A1" },
+  "lifecycle": {
+    "prepare": false,
+    "preview": false,
+    "approve": false,
+    "commit": false,
+    "verify": false,
+    "audit": true
+  },
+  "observability": { "log_inputs": "redacted", "log_outputs": "summary" }
+}
 ```
 
-## 2. Inspect A Capability Manifest
-
-Open `examples/support/capabilities/support.ticket.get.yaml`. It defines a read-only
-support ticket capability with input/output schemas, permissions, risk, status, and
-lifecycle metadata.
-
-The important point is that the manifest is provider-neutral. It is not an OpenAI,
-Anthropic, Gemini, MCP, LangChain, or AI SDK schema.
-
-## 3. Validate Public Examples
-
-```bash
-npm run validate
+The manifest describes the contract; your handler supplies the implementation.
+Production identity and permissions must come from trusted host authentication. Handlers
+must enforce access to the requested resource within that tenant.
+
+## 3. Load, discover and execute
+
+Save this as `app.mjs`:
+
+```js
+import {
+  buildRegistry,
+  loadManifests,
+  validateManifests,
+  toOpenAIResponsesToolName
+} from "ai-capability-framework";
+import { createCapabilityDiscovery } from "ai-capability-framework/discovery";
+import {
+  AicfHandlerRegistry,
+  AicfToolExecutor,
+  AicfActionLifecycleManager,
+  DefaultContextBuilder,
+  DefaultPolicyBroker,
+  InMemoryApprovalStore,
+  InMemoryIdempotencyStore,
+  InMemoryPreparedActionStore
+} from "ai-capability-framework/runtime";
+import {
+  MockOpenAIResponsesClient,
+  mockFunctionCallResponse,
+  mockTextResponse,
+  runOpenAIResponses
+} from "ai-capability-framework/openai";
+
+const loaded = await loadManifests({ path: "capabilities" });
+if (loaded.errors.length || !validateManifests(loaded.manifests).valid) {
+  throw new Error("Invalid capability manifests.");
+}
+const registry = buildRegistry(loaded.manifests);
+// Synthetic identity for this mock only. Production identity comes from your host.
+const runtimeContext = {
+  environment: "test",
+  runId: "run_example",
+  requestId: "request_example",
+  startedAt: new Date().toISOString(),
+  account: { accountId: "account_example", tenantId: "tenant_example" },
+  subject: {
+    actorType: "user",
+    userId: "user_example",
+    roles: [],
+    permissions: ["ticket.read"]
+  },
+  autonomy: {
+    autonomyTier: "A1",
+    maxRiskTier: "low",
+    allowSideEffects: false,
+    allowExternalMessages: false,
+    allowMoneyMovement: false,
+    allowPermissionChanges: false
+  },
+  facts: {},
+  metadata: {}
+};
+
+// Set up the existing runtime once. These example stores live in one process.
+const handlers = new AicfHandlerRegistry({ registry });
+let reads = 0;
+handlers.register({
+  capabilityId: "support.ticket.get",
+  read: ({ args }) => {
+    reads += 1;
+    return { ticket_id: args.ticket_id, status: "open" };
+  }
+});
+const policyBroker = new DefaultPolicyBroker();
+const actionLifecycle = new AicfActionLifecycleManager({
+  registry,
+  handlers,
+  policyBroker,
+  approvalStore: new InMemoryApprovalStore(),
+  idempotencyStore: new InMemoryIdempotencyStore(),
+  preparedActionStore: new InMemoryPreparedActionStore()
+});
+const executor = new AicfToolExecutor({
+  registry,
+  handlers,
+  policyBroker,
+  actionLifecycle
+});
+
+const task = { id: "read-ticket", text: "Read ticket TCK-100." };
+const discovery = createCapabilityDiscovery({ registry });
+const [result] = await discovery.search({ tasks: [task], runtimeContext });
+if (result.status !== "matched")
+  throw new Error("No actionable shortlist; clarify or handle the failure.");
+const client = new MockOpenAIResponsesClient([
+  mockFunctionCallResponse({
+    name: toOpenAIResponsesToolName("support.ticket.get"),
+    callId: "read_example",
+    args: { ticket_id: "TCK-100" }
+  }),
+  mockTextResponse("Ticket TCK-100 is open.")
+]);
+const loop = await runOpenAIResponses({
+  registry,
+  executor,
+  client,
+  model: "mock-model",
+  runtimeContext,
+  contextBuilder: new DefaultContextBuilder(),
+  userInput: { text: task.text },
+  router: discovery.routerFor(result),
+  maxToolCalls: 1,
+  maxTurns: 2
+});
+if (
+  loop.status !== "completed" ||
+  reads !== 1 ||
+  loop.toolResults[0]?.status !== "success"
+) {
+  throw new Error("The mock read did not complete.");
+}
+console.log(
+  JSON.stringify(
+    {
+      queryId: result.queryId,
+      capabilityId: loop.toolCalls[0].capabilityId,
+      toolStatus: loop.toolResults[0].status,
+      data: loop.toolResults[0].data,
+      reads,
+      ordinaryModelTurns: client.requests.length,
+      discoveryProviderCalls: result.usage.totals.providerAttempts
+    },
+    null,
+    2
+  )
+);
 ```
 
-Expected output excerpt:
+Run the installed CLI and app:
 
-```text
-Validated 16 manifest(s) and 18 fixture(s).
+```sh
+npx aicf validate capabilities
+node app.mjs
 ```
 
-## 4. Inspect The Registry
+The CLI validates one manifest. The app reports `queryId: "read-ticket"`,
+`capabilityId: "support.ticket.get"`, `toolStatus: "success"`, one read, two mocked
+ordinary-model turns and zero discovery-provider calls. The ticket is `TCK-100` with
+status `open`. No real provider calls occur.
 
-```bash
-node dist/cli.js inspect examples
-```
-
-Expected output excerpt:
-
-```text
-Capabilities:
-- support.ticket.get
-- support.refund.prepare_case
-- support.refund.commit_case
-```
+## 4. Try the complete customer request
 
-## 5. Run A Deterministic Decision
+Run the packaged example from this same project:
 
-```bash
-node dist/cli.js decide examples --request examples/support/decisions/support.ticket.get.select.json
+```sh
+node node_modules/ai-capability-framework/examples/12-capability-discovery-selection/run-customer-mock.mjs
 ```
 
-Expected output excerpt:
-
-```text
-allowed: true
-capability: support.ticket.get
-```
-
-This proves the policy/selection path without a model. The request uses a synthetic
-user, tenant, permissions, and arguments.
-
-## 6. Run Deterministic Evals
-
-```bash
-node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
-```
-
-Expected output excerpt:
-
-```text
-Eval suite passed
-```
-
-The eval runner checks expected selected capabilities, tool calls, arguments,
-approval-required behavior, and no-commit boundaries from public fixtures. It does not
-call a provider.
-
-## 7. Export Provider Descriptors Later
-
-When you are ready to connect a provider, choose a runtime from
-[Choose a Runtime](../providers/choose-a-runtime.md). The provider adapter will export a
-routed AICF capability slice, but AICF validation and policy remain the authority.
-
-Useful next steps:
-
-- [OpenAI quickstart](openai-quickstart.md)
-- [Anthropic quickstart](anthropic-quickstart.md)
-- [Gemini quickstart](gemini-quickstart.md)
+It models “Read ticket TCK-100 and prepare a refund for its order.” Application code
+searches each ready task once, carries the authorized order ID to its dependent task,
+then prepares a preview requiring approval. Expect one mocked planning turn, four
+ordinary-model turns, one read, one preparation and zero commits. The customer response
+explains that approval is still pending. Dependencies and response assembly belong to
+the example application, not a framework workflow engine.
+
+## Connect your model and application
+
+Keep the same task text and invocation context when passing a result-bound router to
+your ordinary runner. Do not reconstruct, persist or reuse results across requests.
+Permissions, controls, source changes, cancellation and expiry are rechecked before
+export and execution. A retrieval score never authorizes an action.
+
+Replace the mock with your configured Responses-compatible client and an explicit model
+when using `runOpenAIResponses`; the framework supplies no account, credentials or model
+default. Existing configured clients need no additional discovery model. The optional
+OpenAI SDK is needed only if your application chooses it. See the
+[OpenAI quickstart](openai-quickstart.md) or
+[choose another runtime](../providers/choose-a-runtime.md).
+
+For `no_match`, clarify; for `unavailable` or `cancelled`, handle the operational
+outcome. Do not execute the first candidate automatically. Lexical/native is
+recommended. [Dedicated selection](../discovery.md#optional-dedicated-selection) is
+optional; hybrid is experimental with
+[qualification limits](../evals/discovery-qualification.md).
+
+The [stable workflow contract](../api/stable-workflow.md) defines compatibility for this
+path. Production authentication, resource access checks and durable stores remain
+host-owned. [Repository development](../development.md) is separate from package use.

package/docs/getting-started/quickstart.md

@@ -1,32 +1,10 @@
 # Quickstart
 
-The fastest path is the public support/refund walkthrough:
-
-```bash
-npm install
-npm run build
-npm run validate
-node dist/cli.js inspect examples
-node dist/cli.js openai-tools examples --context examples/support/openai/context.support_agent.json
-node examples/runtime-support-billing/run-mock.mjs
-node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
-```
-
-Expected output excerpts:
-
-```text
-Validated 16 manifest(s) and 18 fixture(s).
-Manifests: 16 (6 capabilities, 4 entities, 6 evals)
-approval_required
-Eval suite passed
-```
-
-What this proves:
-
-- manifests and fixtures validate;
-- read/prepare tools can be exported without exposing commit tools;
-- the runtime can read, prepare, require approval, and commit through host lifecycle
-  APIs;
-- evals prove expected behavior without calling a model.
-
-Full command explanations are in [Start here](../start-here.md).
+Start with the [installed-package walkthrough](provider-neutral-quickstart.md). From an
+empty project it shows a complete manifest, registry loading, runtime context, handler,
+lexical discovery and ordinary mocked tool execution. No checkout or provider key is
+required.
+
+The same guide runs the complete dependent read/prepare customer example and explains
+approval requirements. See [repository development](../development.md) only when
+changing the framework itself.

package/docs/index.md

@@ -76,9 +76,10 @@ Models propose; applications validate, authorize, execute, and audit.
 
 ## Capability discovery
 
-The optional release-candidate `ai-capability-framework/discovery` API provides a simple
-search facade, result-bound routers, explicit hybrid retrieval and dedicated selection,
-and provider-free evaluation. Start with
-[finding capabilities for a task](discovery.md). For opt-in provider evaluation, see the
+The optional `ai-capability-framework/discovery` API provides a
+[stable lexical/native workflow](api/stable-workflow.md), a simple search facade,
+result-bound routers, explicit hybrid retrieval and dedicated selection, and
+provider-free evaluation. Start with [finding capabilities for a task](discovery.md).
+For opt-in provider evaluation, see the
 [discovery live evaluation guide](evals/discovery-live.md) and the
 [qualification results and limits](evals/discovery-qualification.md).

package/docs/release.md

@@ -2,18 +2,22 @@
 
 This checklist prepares an AICF public release for GitHub and npm distribution.
 
-## Discovery prerelease
+## Stable discovery workflow
 
-Discovery is release-candidate public. Recommend lexical retrieval with ordinary model
-tool selection; dedicated selection is optional and hybrid remains experimental. Link
-the [qualification report](evals/discovery-qualification.md) in release notes. Its
-qualified lexical results apply to a tested synthetic configuration, and the revised
-workflow assessment is an offline checker correction rather than new live trials.
+The [named lexical/native workflow](api/stable-workflow.md) is stable public in 1.1.0.
+Advanced APIs retain their individual maturity labels. Recommend lexical retrieval with
+ordinary model tool selection; dedicated selection is optional and hybrid remains
+experimental. Link the [qualification report](evals/discovery-qualification.md) in
+release notes. Its qualified lexical results apply to a tested synthetic configuration,
+and the revised workflow assessment is an offline checker correction rather than new
+live trials.
 
 Use a reviewed pull request, passing hosted Linux Node 20/22/24 checks, merge, and an
-exact-commit manual release dry-run before pushing the matching prerelease tag. Local
-checks do not replace hosted checks. Publish both packages to `next`, preserving
-`latest`, then verify exact-version registry installs.
+exact-commit manual release dry-run before pushing the matching version tag. Local
+checks do not replace hosted checks. Prereleases publish both packages to `next`,
+preserving `latest` for prereleases. Stable 1.1.0 publishes to `latest` while preserving
+the existing `next` tag and prerelease versions. Verify normal installation as well as
+exact-version registry installs.
 
 The publication and dry-run workflows run `npm run check` plus certification with
 `VITEST_MAX_WORKERS=2`. Publication is serialized; registry failures fail closed unless

package/docs/runtime.md

@@ -1,5 +1,10 @@
 # Runtime Contracts
 
+The [named lexical/native workflow](api/stable-workflow.md) and its required runtime
+members are stable public from 1.1.0. Other runtime APIs retain their existing maturity;
+this does not promote every export. Start with the
+[installed-package walkthrough](getting-started/provider-neutral-quickstart.md).
+
 AICF Runtime is an additive TypeScript subpath for host applications that want
 deterministic runtime context, capability routing, policy brokering, handler execution,
 action lifecycle control, and model-safe tool result envelopes.

package/docs/start-here.md

@@ -1,136 +1,25 @@
 # Start Here
 
-This guide shows the smallest useful AICF path with the public support/refund example.
-It is API-key-free and uses synthetic data only.
-
-You will validate manifests, inspect the registry, export OpenAI tools, run the mock
-runtime flow, and score evals.
-
-## 1. Install
-
-```bash
-npm install
-```
-
-This installs the local package dependencies. It does not install provider SDKs or call
-any model.
-
-## 2. Validate The Public Examples
-
-```bash
-npm run validate
-```
-
-Expected excerpt:
-
-```text
-Validated 16 manifest(s) and 18 fixture(s).
-```
-
-This proves the public manifests and fixture files are parseable, schema-valid,
-cross-referenced, and public-safe enough for the validation rules.
-
-## 3. Inspect The Registry
-
-Build the CLI, then inspect the examples:
-
-```bash
-npm run build
-node dist/cli.js inspect examples
-```
-
-Expected excerpt:
-
-```text
-AICF Registry
-Manifests: 16
-Capabilities by type:
-- read_data: scheduling.availability.get, support.ticket.get
-- write_prepare_only: scheduling.invite.prepare, support.refund.prepare_case
-- write_commit: scheduling.invite.send, support.refund.commit_case
-```
-
-This shows the validated registry AICF uses for routing, provider export, policy
-decisions, and eval scoring.
-
-## 4. Export OpenAI Tools
-
-```bash
-node dist/cli.js openai-tools examples --context examples/support/openai/context.support_agent.json
-```
-
-Expected excerpt:
-
-```json
-{
-  "tools": [
-    {
-      "type": "function",
-      "name": "aicf_support_refund_prepare_case",
-      "strict": true
-    },
-    {
-      "type": "function",
-      "name": "aicf_support_ticket_get",
-      "strict": true
-    }
-  ],
-  "excluded": [
-    {
-      "capabilityId": "support.refund.commit_case"
-    }
-  ]
-}
-```
-
-This proves safe tool export. The model can see read and prepare tools, but the commit
-capability is not exposed as a normal model tool.
-
-## 5. Run The Mock Runtime Flow
-
-```bash
-node examples/runtime-support-billing/run-mock.mjs
-```
-
-Expected excerpt:
-
-```json
-{
-  "readStatus": "success",
-  "prepareStatus": "approval_required",
-  "commitStatus": "committed"
-}
-```
-
-This runs route, read, prepare, approval, and lifecycle commit with mock handlers and
-in-memory reference stores. The model-facing path still cannot commit. Commit happens
-only after the host records approval and calls the lifecycle manager.
-
-## 6. Run Deterministic Evals
-
-```bash
-node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
-```
-
-Expected excerpt:
-
-```text
-Eval suite passed: 6/6 passed.
-```
-
-This proves the candidate fixture matches the eval manifests for tool selection,
-arguments, policy decisions, refusals, response text, and no unapproved commit
-boundaries.
-
-## What You Just Proved
-
-- Public manifests validate and build a registry.
-- OpenAI tool export is safe and does not expose commit tools by default.
-- Provider SDK validation does not replace AICF validation.
-- The runtime can execute read and prepare handlers with model-safe envelopes.
-- Approval-required prepare pauses before side effects.
-- Host-controlled lifecycle commit works after approval and idempotency checks.
-- Evals score behavior without calling models.
-
-Next, read the [OpenAI walkthrough](openai-walkthrough.md) for the same flow from the
-model/tool-call perspective, then use the [glossary](glossary.md) for the main terms.
+Install with `npm install ai-capability-framework`, then follow the
+[complete installed-package quickstart](getting-started/provider-neutral-quickstart.md).
+It needs no checkout, provider SDK or API key.
+
+You will author one capability, load its registry, create runtime context, register a
+handler, search a task and execute the ordinary mock model/tool loop. The packaged
+customer example then shows an authorized read followed by an approval-required preview.
+
+Lexical/native is the recommended [stable workflow](api/stable-workflow.md). Dedicated
+selection is optional; hybrid remains experimental with
+[qualification limits](evals/discovery-qualification.md). Applications own
+decomposition, dependencies, arguments, authentication, resource access and customer
+responses.
+
+The model can see read and prepare tools, but the commit capability is not exposed.
+Runtime validation, authorization and approval policy remain the authority for actions.
+
+- [Installation](getting-started/installation.md)
+- [Capability manifests](capability-manifests.md)
+- [Choose a runtime](providers/choose-a-runtime.md)
+- [Discovery details](discovery.md)
+- [API policy](api/public-api-policy.md)
+- [Repository development](development.md)

package/examples/12-capability-discovery-selection/README.md

@@ -1,6 +1,6 @@
 # From a customer request to a tool
 
-Use `ai-capability-framework@1.1.0-rc.1` for these discovery APIs. Lexical/native is the
+Install `ai-capability-framework` (stable 1.1.0 or later). Lexical/native is the
 recommended default. Hybrid is experimental and opt-in; the
 [qualification report](../../docs/evals/discovery-qualification.md) explains its limits.
 
@@ -155,8 +155,9 @@ construction.
 The selector returns decisions; application argument completion and runtime execution
 remain separate. Native search and `routerFor` never call the dedicated selector.
 Selected-result routers, the optional Responses adapter, and managed full-run accounting
-are available; see the shared-run integration below. Imports use the public
-release-candidate discovery subpath.
+are available; see the shared-run integration below. Imports use the public discovery
+subpath; the [named lexical/native workflow](../../docs/api/stable-workflow.md) is
+stable.
 
 Run the explicit selector companion:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-capability-framework",
-  "version": "1.1.0-rc.1",
+  "version": "1.1.0",
   "private": false,
   "description": "Provider-agnostic AI capability contracts, runtime controls, evals, and model/provider adapters.",
   "license": "MIT",