ai-capability-framework 1.0.0-rc.1

package/docs/adapter-roadmap.md

@@ -0,0 +1,179 @@
+# Adapter Status And Roadmap
+
+AICF is provider-neutral. Adapters export tool metadata, bindings, parsers, and
+diagnostics, but do not call models, execute handlers, persist actions, collect
+approvals, or perform side effects.
+
+## Priority Criteria
+
+Adapter priority is based on:
+
+- fit with AICF capability manifests and JSON Schema inputs;
+- adoption and usefulness for public developers;
+- ability to preserve the no-execution boundary;
+- deterministic name binding and argument parsing support;
+- implementation size in the TypeScript package.
+
+Every adapter should expose the same high-level contract:
+
+- `buildXTools(registry, options)` or equivalent export function;
+- `parseXToolCall(toolset, call)` or equivalent parser;
+- deterministic tool-name mapping back to AICF capability IDs;
+- `bindings`, `excluded`, and `diagnostics`;
+- selection gated by `decideCapability(..., operation: "select")`;
+- restricted side-effect tools excluded by default;
+- schema normalization that fails closed when the target cannot represent an
+  AICF input schema safely.
+
+## Priority Order
+
+| Priority | Adapter | Why It Comes Here | Primary Output |
+| --- | --- | --- | --- |
+| Priority | Adapter | Status | Primary Output |
+| --- | --- | --- | --- |
+| P1 | Anthropic Claude Messages tools | Implemented | Claude client tool definitions plus parser for `tool_use` blocks. |
+| P2 | Google Gemini function calling | Implemented | Gemini `functionDeclarations` plus parser for `functionCall` objects. |
+| P3 | Vercel AI SDK tools | Implemented | AI SDK tool map with `inputSchema`, `description`, `strict`, and no `execute`. |
+| P4 | Model Context Protocol tool descriptors | Implemented | MCP `Tool` descriptors and parser for `tools/call` requests. |
+| P5 | LangChain/LangGraph tools | Implemented | Structured tool parameter specs and bindings for host-supplied functions. |
+| P6 | Semantic Kernel functions | Implemented | Function/plugin metadata and parser guidance for manual invocation flows. |
+
+## P1: Anthropic Claude Messages Tools
+
+Target a no-model-call adapter that exports Claude client tool definitions:
+
+- `name`: sanitized AICF capability ID, capped at the provider limit.
+- `description`: composed from `model_description`, use guidance, risk,
+  autonomy, lifecycle, and side-effect metadata.
+- `input_schema`: normalized AICF `input_schema`.
+- `strict: true` when the schema can be represented safely.
+- optional `input_examples` only when public examples are available and validated.
+
+Parser target:
+
+- map Claude `tool_use.name` to capability ID;
+- read `tool_use.id` as call ID;
+- validate `tool_use.input` against the original AICF input schema;
+- return structured diagnostics for unknown names, malformed input, and schema
+  failures.
+
+Reference basis: Claude client tools include `name`, `description`, and
+`input_schema`, can use `strict: true`, and return `tool_use` blocks that the
+host application executes.
+
+## P2: Google Gemini Function Calling
+
+Target a no-model-call adapter that exports Gemini function declarations:
+
+- `name`: sanitized capability ID using underscores or camelCase-safe names.
+- `description`: composed from AICF model-facing and governance metadata.
+- `parameters`: AICF input schema converted to Gemini's OpenAPI-compatible
+  schema subset.
+
+Parser target:
+
+- map `functionCall.name` to capability ID;
+- preserve `functionCall.id` when present;
+- validate `functionCall.args` against the original AICF input schema;
+- report schema keywords that cannot be represented safely in Gemini parameters.
+
+The hard part is schema normalization. Gemini function declarations use an
+OpenAPI-compatible subset, so this adapter should fail closed for unsupported
+JSON Schema 2020-12 features rather than silently weakening validation.
+
+## P3: Vercel AI SDK Tools
+
+Target a TypeScript-first adapter that exports an AI SDK-compatible tool map
+without execution functions:
+
+- object keys are deterministic tool names;
+- values include `description`, `inputSchema`, and `strict` when supported;
+- no `execute` function is generated by AICF;
+- bindings preserve capability IDs and original schemas.
+
+Parser target:
+
+- map AI SDK tool call names to AICF capability IDs;
+- validate tool call input against the original AICF input schema;
+- leave tool result production and execution to the host app.
+
+This adapter is attractive because the AI SDK accepts JSON schemas and `execute`
+is optional, allowing host apps to forward calls to a queue, client, or approval
+path instead of executing in the same process.
+
+## P4: Model Context Protocol Tool Descriptors
+
+Target MCP descriptor export, not an AICF-owned executable MCP server:
+
+- `name`: deterministic MCP-safe tool name;
+- `title`: human-readable capability name;
+- `description`: AICF model description plus lifecycle/risk guidance;
+- `inputSchema`: AICF input schema, preserving JSON Schema 2020-12 where valid;
+- `outputSchema`: AICF output schema when representable;
+- `annotations`: conservative hints derived from side effects, such as read-only
+  and idempotent hints.
+
+Parser target:
+
+- map `tools/call.params.name` to capability ID;
+- validate `tools/call.params.arguments`;
+- return an AICF capability request object for the host MCP server or runtime to
+  decide and execute.
+
+Do not add an MCP server that executes capabilities inside AICF. Host apps may
+use AICF descriptors inside their own MCP server implementation.
+
+## P5: LangChain And LangGraph Tools
+
+Target descriptor export for host-created tools:
+
+- deterministic name;
+- description;
+- schema suitable for LangChain structured tools;
+- binding metadata for capability ID, risk, autonomy, and restriction status.
+
+Do not generate callable implementations. LangChain and LangGraph tools are
+runtime functions that can update state or return commands, so the host must
+supply execution, approval, and state handling.
+
+This adapter should probably be implemented after the AI SDK adapter, because
+both are TypeScript-oriented but AI SDK has a cleaner descriptor-only path.
+
+## P6: Semantic Kernel Functions
+
+Target metadata and manual-invocation compatibility:
+
+- function/plugin names derived from AICF capability IDs;
+- descriptions and parameter schemas derived from manifests;
+- parser support for chosen function name and arguments;
+- guidance for `autoInvoke: false` style host workflows.
+
+Semantic Kernel is useful for enterprise users, but its strongest value is in
+runtime orchestration. AICF should stay on the metadata and validation side.
+
+## Common Tests For Future Adapter Implementations
+
+Each adapter should add tests for:
+
+- allowed read and prepare capabilities exported for a matching context;
+- restricted commit/send capabilities excluded by default;
+- restricted export only with an explicit option and deterministic selection
+  still applied;
+- deterministic safe name generation, truncation, collision handling, and
+  reverse bindings;
+- schema normalization success and unsupported-schema exclusion;
+- valid tool-call parsing;
+- invalid JSON or malformed input handling;
+- unknown tool name handling;
+- input-schema failure;
+- CLI JSON output and exit behavior if a CLI command is added.
+
+## Reference Links
+
+- Anthropic Claude tool use: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview
+- Anthropic define tools: https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools
+- Google Gemini function calling: https://ai.google.dev/gemini-api/docs/function-calling
+- Vercel AI SDK tool calling: https://ai-sdk.dev/docs/ai-sdk-core/tools-and-tool-calling
+- Model Context Protocol tools: https://modelcontextprotocol.io/specification/2025-06-18/server/tools
+- LangChain JavaScript tools: https://docs.langchain.com/oss/javascript/langchain/tools
+- Semantic Kernel manual function invocation: https://learn.microsoft.com/en-us/semantic-kernel/concepts/ai-services/chat-completion/function-calling/function-invocation

package/docs/adapters.md

@@ -0,0 +1,112 @@
+# Adapters
+
+AICF adapters export validated capability manifests into provider or runtime
+tool descriptor shapes. They do not call models, execute handlers, persist
+actions, collect approvals, or perform side effects.
+
+Every adapter follows the same boundary:
+
+- require a decision context with permissions and autonomy tier;
+- include only capabilities whose `select` decision is `allowed`;
+- exclude restricted commit, send, money-moving, permission-changing, workflow,
+  and irreversible capabilities by default;
+- allow restricted export only with `includeRestricted: true`, while still
+  applying deterministic selection;
+- bind exported names back to AICF capability IDs;
+- validate parsed tool-call arguments against the original AICF input schema;
+- fail closed with diagnostics when schemas or names cannot be represented
+  safely.
+
+## TypeScript APIs
+
+OpenAI Responses:
+
+```ts
+buildOpenAIResponsesTools(registry, { context });
+parseOpenAIResponsesToolCall(toolset, call);
+toOpenAIResponsesToolName("support.ticket.get");
+```
+
+Anthropic Claude:
+
+```ts
+buildAnthropicClaudeTools(registry, { context });
+parseAnthropicClaudeToolUse(toolset, toolUse);
+toAnthropicClaudeToolName("support.ticket.get");
+```
+
+Google Gemini:
+
+```ts
+buildGeminiFunctionDeclarations(registry, { context });
+parseGeminiFunctionCall(functionSet, functionCall);
+toGeminiFunctionName("support.ticket.get");
+```
+
+Vercel AI SDK:
+
+```ts
+buildAiSdkTools(registry, { context });
+parseAiSdkToolCall(toolset, toolCall);
+toAiSdkToolName("support.ticket.get");
+```
+
+Model Context Protocol:
+
+```ts
+buildMcpToolDescriptors(registry, { context });
+parseMcpToolCall(toolset, toolCall);
+toMcpToolName("support.ticket.get");
+```
+
+LangChain and LangGraph:
+
+```ts
+buildLangChainToolDescriptors(registry, { context });
+parseLangChainToolCall(toolset, toolCall);
+toLangChainToolName("support.ticket.get");
+```
+
+Semantic Kernel:
+
+```ts
+buildSemanticKernelFunctions(registry, { context });
+parseSemanticKernelFunctionCall(functionSet, functionCall);
+toSemanticKernelFunctionName("support.ticket.get");
+```
+
+## CLI
+
+All adapter commands accept a manifest path and context file:
+
+```bash
+npm run build
+node dist/cli.js anthropic-tools examples --context examples/support/openai/context.support_agent.json
+node dist/cli.js gemini-tools examples --context examples/support/openai/context.support_agent.json
+node dist/cli.js ai-sdk-tools examples --context examples/support/openai/context.support_agent.json
+node dist/cli.js mcp-tools examples --context examples/support/openai/context.support_agent.json
+node dist/cli.js langchain-tools examples --context examples/support/openai/context.support_agent.json
+node dist/cli.js semantic-kernel-functions examples --context examples/support/openai/context.support_agent.json
+```
+
+Use `--include-restricted` only when the host has deliberately narrowed context
+and still intends to run deterministic approval, idempotency, auth, and commit
+checks before any side effect.
+
+## Output Shapes
+
+- OpenAI Responses returns `tools`.
+- Anthropic Claude returns `tools`.
+- Google Gemini returns `functionDeclarations`.
+- Vercel AI SDK returns a keyed `tools` object.
+- MCP returns `tools` descriptors.
+- LangChain/LangGraph returns `tools` descriptors with metadata.
+- Semantic Kernel returns `functions`.
+
+All outputs include `bindings`, `excluded`, and `diagnostics`.
+
+## Host Responsibilities
+
+Adapters only produce descriptors and parse calls. Host applications remain
+responsible for model requests, real authorization, facts, approvals, execution,
+storage, idempotency, verification, and durable audit logs.

package/docs/api.md

@@ -0,0 +1,115 @@
+# API
+
+AICF exposes a small TypeScript API and the `aicf` CLI. The package is public
+npm release-candidate material, and the exported surface is treated as public
+developer API.
+
+Import from the package root:
+
+```ts
+import {
+  buildRegistry,
+  decideCapability,
+  loadManifests,
+  validateManifests
+} from "ai-capability-framework";
+```
+
+## Boundaries
+
+The library does not call models, execute capabilities, verify host
+authorization, persist actions, collect approvals, write audit logs, or perform
+side effects. Host applications own runtime execution and storage.
+
+## Core Manifest APIs
+
+- `loadManifests(options)` reads YAML and JSON manifests from convention paths.
+- `validateManifests(manifests, options)` validates schemas, duplicate IDs, and
+  manifest cross-references.
+- `buildRegistry(manifests)` returns lookup maps and grouped manifest arrays.
+- `inspectRegistry(registry)` returns counts, capability groupings, eval
+  coverage, and warnings.
+
+Diagnostics use `AicfDiagnostic` with `code`, `path`, optional `kind`, optional
+`id`, and a human-readable `message`.
+
+## Decision APIs
+
+- `decideCapability(registry, request)` evaluates select, prepare, or commit
+  status for one capability.
+- `evaluatePolicy(capability, request)` evaluates deterministic policy metadata.
+- `evaluateLifecycle(capability, request)` evaluates lifecycle availability.
+
+Decision results return `status`, `reasons`, `requiredApprovals`, `policy`,
+`lifecycle`, and an audit preview. The audit preview is not persisted.
+
+## Provider And Runtime Adapters
+
+- `buildOpenAIResponsesTools(registry, options)` exports OpenAI-compatible
+  function tools plus bindings, exclusions, and diagnostics.
+- `parseOpenAIResponsesToolCall(toolset, call)` maps a Responses
+  `function_call` item back to a capability ID and validates arguments.
+- `toOpenAIResponsesToolName(capabilityId, options)` converts an AICF capability
+  ID into a deterministic OpenAI-safe tool name.
+- `buildAnthropicClaudeTools(registry, options)` exports Anthropic Claude tool
+  definitions.
+- `parseAnthropicClaudeToolUse(toolset, toolUse)` maps Claude `tool_use` blocks
+  back to AICF capability requests.
+- `buildGeminiFunctionDeclarations(registry, options)` exports Gemini function
+  declarations.
+- `parseGeminiFunctionCall(functionSet, functionCall)` parses Gemini
+  `functionCall` objects.
+- `buildAiSdkTools(registry, options)` exports a Vercel AI SDK-compatible tool
+  map without `execute` handlers.
+- `parseAiSdkToolCall(toolset, toolCall)` parses AI SDK tool calls.
+- `buildMcpToolDescriptors(registry, options)` exports MCP tool descriptors.
+- `parseMcpToolCall(toolset, toolCall)` parses MCP `tools/call` requests.
+- `buildLangChainToolDescriptors(registry, options)` exports LangChain and
+  LangGraph descriptor metadata without callable implementations.
+- `parseLangChainToolCall(toolset, toolCall)` parses LangChain-style tool calls.
+- `buildSemanticKernelFunctions(registry, options)` exports Semantic Kernel
+  function metadata.
+- `parseSemanticKernelFunctionCall(functionSet, functionCall)` parses Semantic
+  Kernel manual invocation calls.
+
+Adapters emit descriptor JSON only. They do not call providers or execute tool
+handlers. See [the adapter guide](adapters.md) for output shapes and CLI usage.
+
+## Eval Runner APIs
+
+- `loadEvalResults(path)` reads and validates a public-safe eval result fixture.
+- `scoreEvalCase(evalCase, candidate, registry)` scores one eval/candidate pair.
+- `runEvalSuite(registry, candidates, options)` scores loaded eval manifests
+  against candidate results.
+- `formatEvalSuiteResult(result)` formats a readable text summary.
+
+Eval runner output includes suite status, per-eval status, scorer results, and
+diagnostics. It scores summarized behavior only, not raw model traces.
+
+## CLI
+
+```bash
+aicf validate [path]
+aicf inspect [path]
+aicf decide <path> --request <decision.json>
+aicf openai-tools <path> --context <context.json> [--include-restricted]
+aicf anthropic-tools <path> --context <context.json> [--include-restricted]
+aicf gemini-tools <path> --context <context.json> [--include-restricted]
+aicf ai-sdk-tools <path> --context <context.json> [--include-restricted]
+aicf mcp-tools <path> --context <context.json> [--include-restricted]
+aicf langchain-tools <path> --context <context.json> [--include-restricted]
+aicf semantic-kernel-functions <path> --context <context.json> [--include-restricted]
+aicf eval <path> --results <results.json> [--format text|json]
+```
+
+Denied decisions exit `0` when the decision was evaluated successfully. Eval
+runs exit `0` only when all targeted evals pass.
+
+## Versioning
+
+The package version uses semver. Manifest schemas use `schema_version: "1.0"`.
+The 1.0 validator intentionally does not support the pre-release 0.1 schema.
+Changes to TypeScript exports, CLI output, or schema semantics must be covered
+by tests before release. Public API or schema changes must also update
+`CHANGELOG.md`, the migration notes when relevant, and the GitHub release notes
+checklist in `docs/release.md`.

package/docs/capability-manifests.md

@@ -0,0 +1,47 @@
+# Capability Manifests
+
+A capability manifest is the contract between model-facing intent and
+application-owned execution.
+
+See [the 1.0 spec](spec.md) for the shared vocabulary.
+
+## Required Fields
+
+- `schema_version`: Manifest schema version.
+- `id`: Stable dotted identifier such as `support.refund.prepare_case`.
+- `version`: Semantic version for the capability contract.
+- `status`: Lifecycle state such as `draft`, `active`, or `deprecated`.
+- `name` and `summary`: Human-readable labels for operators and maintainers.
+- `model_description`: Short model-facing description of when to use the
+  capability.
+- `capability_type`: The broad action class, such as read, compute, prepare, or
+  commit.
+- `autonomy_tier`: Maximum autonomy level allowed for the capability.
+- `risk_tier`: Safety and business risk tier.
+- `input_schema` and `output_schema`: JSON Schema contracts.
+- `side_effects`: Explicit flags for data reads, writes, money movement,
+  external messages, permission changes, and irreversible actions.
+- `authorization`: Required permissions and scoping rules.
+- `policy`: Deny, approval, and review rules.
+- `lifecycle`: Explicit prepare, preview, approve, commit, verify, and audit
+  flags.
+- `idempotency`: Optional commit idempotency requirements.
+- `observability`: Logging and trace expectations.
+
+## Lifecycle Guidance
+
+Use `write_prepare_only` for capabilities that assemble a proposed action but do
+not execute it. Use `write_commit` only when the application can enforce
+authorization, idempotency, approval state, verification, and audit.
+
+High-risk capabilities should require explicit approval before commit. Critical
+capabilities should usually be split into separate prepare and commit
+capabilities.
+
+Commit capabilities should be excluded from normal model tool sets until
+application code has verified approval and idempotency state.
+
+AICF tooling loads and validates capability manifests, builds registries,
+evaluates deterministic select, prepare, and commit decisions, exports adapter
+metadata, and scores eval fixtures. It does not execute capabilities, persist
+actions, collect approvals, or perform side effects.

package/docs/control-plane.md

@@ -0,0 +1,59 @@
+# Control Plane
+
+The control plane provides deterministic decision APIs for capability selection,
+preparation, and commit gating. It does not execute capabilities, store action
+state, call models, or enforce host application authorization.
+
+## Decision API
+
+Use `decideCapability(registry, request)` with a registry built from validated
+manifests.
+
+The request includes:
+
+- `capabilityId`
+- `operation`: `select`, `prepare`, or `commit`
+- `args`
+- `context.permissions`
+- `context.autonomyTier`
+- optional `facts`
+- optional `approval`
+- optional `idempotencyKey`
+
+The result includes:
+
+- `status`: `allowed`, `approval_required`, or `denied`
+- `reasons`
+- `requiredApprovals`
+- `policy`
+- `lifecycle`
+- `audit` preview
+
+The audit preview is not persisted and has no timestamp. Host applications own
+real audit logging.
+
+## Policy Semantics
+
+- Missing permissions deny.
+- Autonomy above the capability tier or policy max tier denies.
+- `select` decisions check tool-set eligibility with permissions and autonomy.
+- `prepare` and `commit` decisions evaluate fact-dependent policy rules.
+- `deny_if` rules read `facts[rule]`.
+- A true deny fact denies.
+- A missing deny fact fails closed and denies.
+- `approval_required_if` can return `approval_required` for prepare decisions.
+- Commit decisions missing required approval deny.
+- Commit decisions missing required idempotency deny.
+
+## CLI
+
+Run a decision from a JSON request file:
+
+```bash
+npm run build
+node dist/cli.js decide examples --request examples/support/decisions/support.refund.commit_case.allowed.json
+```
+
+Denied decisions still exit `0` because the decision was evaluated
+successfully. Invalid manifests, invalid request files, and unknown capability
+IDs exit nonzero.

package/docs/eval-runner.md

@@ -0,0 +1,80 @@
+# Eval Runner
+
+The deterministic eval runner scores AICF eval manifests against candidate
+result fixtures without calling models, executing capabilities, storing traces,
+or reading raw provider payloads.
+
+Host applications are responsible for producing candidate results. AICF only
+validates and scores the summarized behavior.
+
+## Candidate Fixture
+
+Candidate fixtures are JSON files with `schema_version: "1.0"` and a `results`
+array. Each result is keyed by `eval_id` and may include selected capabilities,
+tool calls, policy decision, action state, committed capabilities, refusal
+information, and response text.
+
+```json
+{
+  "schema_version": "1.0",
+  "results": [
+    {
+      "eval_id": "support.refund.prepare_case.valid",
+      "selected_capabilities": ["support.refund.prepare_case"],
+      "tool_calls": [
+        {
+          "capability_id": "support.refund.prepare_case",
+          "args": {
+            "ticket_id": "TCK-1001"
+          }
+        }
+      ],
+      "action_state": "prepared",
+      "committed_capabilities": []
+    }
+  ]
+}
+```
+
+Keep fixtures synthetic and public-safe. Do not commit raw prompts, raw traces,
+provider payloads, customer records, secrets, internal endpoints, or private
+documents.
+
+## Scorers
+
+The runner supports the scorer types used by the public eval examples:
+
+- `tool_selection_includes`
+- `tool_selection_excludes`
+- `tool_input_json_subset`
+- `policy_decision_matches`
+- `no_unapproved_commit`
+- `refusal_present`
+- `response_excludes_private_detail`
+
+It also enforces `expected.response.must_include` and
+`expected.response.must_not_include` whenever those fields are present. Unknown
+scorer types fail closed.
+
+`no_unapproved_commit` fails when a candidate has `action_state: "committed"`,
+non-empty `committed_capabilities`, or a tool call to a capability whose
+manifest is a commit capability.
+
+## CLI
+
+Run the full public example fixture:
+
+```bash
+npm run build
+node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json
+```
+
+For machine-readable output:
+
+```bash
+node dist/cli.js eval examples --results examples/eval-results/public.results.passing.json --format json
+```
+
+The command exits `0` only when manifests are valid, the result fixture is valid,
+every loaded eval has a candidate result, and all scorer checks pass. Failed
+checks, missing candidates, invalid fixtures, and unknown scorers exit nonzero.

package/docs/evals.md

@@ -0,0 +1,34 @@
+# Evals
+
+Eval cases keep capability behavior from drifting as prompts, models, policies,
+and routing code change.
+
+Each eval should be synthetic, deterministic, and tied to a specific behavior.
+See [the 1.0 spec](spec.md) for public-safe example rules.
+
+## Useful Eval Types
+
+- Capability selection includes the correct capability.
+- Capability selection excludes unsafe or premature commit capabilities.
+- Extracted arguments match the user request and available context.
+- The action remains in a prepared state when approval is required.
+- The model refuses or redirects requests outside the allowed policy.
+- Tool results and final responses do not expose private implementation detail.
+- Commit capabilities remain excluded until approval is verified.
+
+## Public Example Rule
+
+Public examples must use fake identifiers, fake users, fake tenants, and generic
+domains. Do not commit real traces, customer records, raw prompts, internal
+schemas, or provider payloads.
+
+AICF validation checks that eval files referenced by capability manifests are
+present in the loaded manifest bundle.
+
+Decision behavior should be covered with synthetic request examples and tests
+for permission denial, autonomy denial, approval requirements, deny facts,
+missing facts, approval state, and idempotency keys.
+
+AICF includes a deterministic eval runner for scoring public-safe candidate
+result fixtures against eval manifests. See [the eval runner guide](eval-runner.md)
+for fixture shape, scorer behavior, and CLI usage.

package/docs/getting-started.md

@@ -0,0 +1,51 @@
+# Getting Started
+
+AICF describes AI-facing application behavior as public, typed manifests.
+
+Use it when you need to answer these questions:
+
+- What can the model select?
+- What input does the application accept?
+- What output can the application return?
+- What side effects can happen?
+- Who is allowed to use the capability?
+- What policy gates or approvals apply?
+- What evals prove the behavior is stable?
+
+## Basic Workflow
+
+1. Read the [1.0 spec](spec.md).
+2. Identify one application behavior that the model may request.
+3. Write a capability manifest for that behavior.
+4. Define strict input and output JSON Schemas.
+5. Mark side effects explicitly.
+6. Add authorization and policy requirements.
+7. Link synthetic eval cases that test selection, arguments, refusals, and
+   approval boundaries.
+8. Run `npm run validate`.
+
+## CLI Workflow
+
+- `npm run validate` builds the CLI and validates the public examples.
+- `npm run inspect` prints a readable registry summary.
+- After building, `node dist/cli.js validate <path>` and
+  `node dist/cli.js inspect <path>` can target another manifest bundle.
+- `node dist/cli.js decide <path> --request <decision.json>` evaluates a
+  deterministic decision request and prints JSON.
+- `node dist/cli.js openai-tools <path> --context <context.json>` exports
+  OpenAI Responses function tools without calling a model.
+- `node dist/cli.js eval <path> --results <results.json>` scores deterministic
+  candidate eval results without calling a model.
+
+## Design Rules
+
+- Give the model the smallest relevant set of capabilities for a task.
+- Use deterministic application code for validation, permissions, policy,
+  execution, and audit.
+- Do not expose raw databases, unrestricted HTTP clients, shell access, payment
+  tools, or admin tools directly to the model.
+- Treat retrieved content and tool results as untrusted unless your application
+  has explicitly marked them as authoritative.
+- Keep examples synthetic and public-safe.
+- Keep commit capabilities separate from prepare capabilities unless the action
+  is explicitly low-risk and policy allows auto-commit.