@zerotal/arch 1.7.4 → 1.8.0

package/docs/admin/operations.md

@@ -30,7 +30,7 @@ as it does today.
 
 Turn it on per resource:
 
-```ts
+```ts fragment
 export class ProductResource extends Resource {
   static override history = true;
 }
@@ -50,7 +50,7 @@ ago should not also undo the description somebody fixed yesterday.
 The support request nobody can reproduce is usually solved by seeing what the person
 actually sees.
 
-```ts
+```ts fragment
 export class UserResource extends Resource {
   static override impersonatable = true;
 
@@ -79,7 +79,7 @@ Every bit of list state already lives in the URL: search, filters, tab, sort, co
 visibility, grouping, page size. So a saved view is a saved query string, and
 restoring one is a link.
 
-```ts
+```ts fragment
 Panel.savedViews({
   async list(resource) {
     /* … */
@@ -103,7 +103,7 @@ A file upload field puts a file somewhere and stores a path. That works until th
 logo is needed on twenty products, or somebody wants to know what is still pointing at
 a file before deleting it.
 
-```ts
+```ts fragment
 import { databaseMedia, mediaPicker } from "@zerotal/admin";
 
 Panel.media(databaseMedia());
@@ -117,7 +117,7 @@ somewhere else.
 Configured, the panel gains a Media page — a grid with upload, search, folder
 filtering, alt-text editing and deletion — and forms can use the picker:
 
-```ts
+```ts fragment
 mediaPicker("imageUrl").label("Image");
 ```
 
@@ -134,7 +134,7 @@ Authorization already works without a UI: a resource's `can()` answers every que
 the panel asks. What is missing is the other direction — seeing who can do what, and
 changing it, without editing code.
 
-```ts
+```ts fragment
 import { authRoles } from "@zerotal/admin";
 
 Panel.roles(authRoles({ superusers: ["admin"] }));
@@ -162,7 +162,7 @@ week.
 What belongs at the top of a dashboard differs by role, and neither the finance lead
 nor support wants to scroll past the other's widget every morning.
 
-```ts
+```ts fragment
 Panel.dashboardLayout({
   async load() {
     return Auth.user()?.dashboard ?? null;
@@ -193,7 +193,7 @@ stale key mentions it.
 Two people editing the same record is normal; one of them losing their work silently
 is not.
 
-```ts
+```ts fragment
 export class ProductResource extends Resource {
   static override optimisticLock = "version";
 }
@@ -207,7 +207,7 @@ overwriting loses somebody's work, and merging blind is worse.
 
 The expensive mistake is editing production believing it is staging.
 
-```ts
+```ts fragment
 import { environmentIndicator } from "@zerotal/admin";
 
 Panel.renderHook("body.start", environmentIndicator());

package/docs/admin/resources.md

@@ -18,7 +18,7 @@ Scaffold one with the generator, which writes `app/admin/<Name>Resource.ts`:
 bun zt make:admin-resource Post
 ```
 
-```ts
+```ts fragment
 class PostResource extends Resource {
   static model = Post;
 
@@ -71,7 +71,7 @@ class PostResource extends Resource {
 A resource does nothing until the panel knows about it. Register it where the panel
 is configured:
 
-```ts
+```ts fragment
 Panel.register(PostResource);
 ```
 
@@ -93,7 +93,7 @@ any of its links changing.
 Override `can(ability, record?)` to gate the built-in actions. Abilities used by the
 presets: `create`, `update`, `delete`, `restore`, `forceDelete`.
 
-```ts
+```ts fragment
 static can(ability: string, record?: AdminRecord) {
   return Gate.allows(ability, record ?? this.model);
 }

package/docs/admin/structure.md

@@ -21,7 +21,7 @@ real back office takes.
 A cluster gives a group of resources a shared URL segment and a single sidebar
 entry. Declare one, then point resources at it:
 
-```ts
+```ts fragment
 import { Cluster } from "@zerotal/admin";
 
 export class ShopCluster extends Cluster {
@@ -42,7 +42,7 @@ the cluster segment on its own. Nothing in a resource needs to know its own path
 
 A cluster's `ability` gates the whole section:
 
-```ts
+```ts fragment
 export class FinanceCluster extends Cluster {
   static override slug = "finance";
   static override title = "Finance";
@@ -59,7 +59,7 @@ Some records have no meaning apart from their parent. Comments belong to a post;
 there is no useful screen listing every comment in the database. Declare the
 parent and the resource moves inside it:
 
-```ts
+```ts fragment
 export class CommentResource extends Resource {
   static override model = Comment;
   static override parent = { resource: () => PostResource, foreignKey: "post_id" };
@@ -83,7 +83,7 @@ on whichever side of the import cycle evaluated first.
 When the parent declares the child with `hasMany`, its view page links into the
 nested pages instead of rendering an inline table:
 
-```ts
+```ts fragment
 export class PostResource extends Resource {
   static override relations() {
     return [hasMany(CommentResource, "post_id").title("Comments")];
@@ -96,7 +96,7 @@ export class PostResource extends Resource {
 Site settings are one row. A list of one, with a view page and an edit page behind
 it, is three screens too many:
 
-```ts
+```ts fragment
 export class SettingsResource extends Resource {
   static override model = Setting;
   static override singular = true;
@@ -123,7 +123,7 @@ than an error.
 Most applications have one panel, and `Panel.configure(...)` / `Panel.register(...)`
 write to it. When a second audience needs a second set of screens, make another:
 
-```ts
+```ts fragment
 // The back office — everything.
 Panel.configure({ brand: "Acme", path: "/admin", middleware: [AuthMiddleware] });
 Panel.register(ProductResource, OrderResource, UserResource);

package/docs/admin/tables.md

@@ -7,7 +7,7 @@ description: Columns, filters, sorting, search, and bulk actions on the list scr
 
 `columns()` returns `Column`s built with `text(key)` plus chainable modifiers.
 
-```ts
+```ts fragment
 static columns() {
   return [
     text("title").label("Title").sortable().searchable(),
@@ -42,14 +42,14 @@ static columns() {
 formatter) render a `<tfoot>` total computed over the **full filtered dataset**, plus
 per-group subtotals when grouping is active.
 
-```ts
+```ts fragment
 text("amount").align("end").sum("Revenue", (n) => `$${n.toFixed(2)}`),
 text("id").count("Orders"),
 ```
 
 ## Filters
 
-```ts
+```ts fragment
 import { selectFilter, ternaryFilter } from "@zerotal/admin";
 
 static filters() {
@@ -70,7 +70,7 @@ Fixed filters work when you can name the useful questions in advance. A catalogu
 or a ledger is queried in too many ways for that, so `queryBuilder` lets the user
 stack their own comparisons and nest AND/OR groups:
 
-```ts
+```ts fragment
 import {
   queryBuilder, textConstraint, numberConstraint,
   selectConstraint, booleanConstraint, dateConstraint,
@@ -112,7 +112,7 @@ link someone can send to a colleague.
 `tab(key)` adds quick-filter tabs above the table, each scoping the query and
 optionally showing a count badge.
 
-```ts
+```ts fragment
 import { tab } from "@zerotal/admin";
 
 static tabs() {
@@ -129,7 +129,7 @@ static tabs() {
 `group(column)` adds a "Group by" menu; the page renders header rows per bucket with
 counts (and per-group summary subtotals).
 
-```ts
+```ts fragment
 import { group } from "@zerotal/admin";
 
 static groups() {
@@ -143,7 +143,7 @@ static defaultGroup = "status";   // optional
 Set `reorderable` to an integer position column to show up/down handles that persist
 order:
 
-```ts
+```ts fragment
 static reorderable = "sort";
 ```
 
@@ -158,7 +158,7 @@ automatically and are URL-driven.
 A blank table teaches nobody anything. Override `emptyState()` to say why the list
 is empty and what will fill it:
 
-```ts
+```ts fragment
 static emptyState() {
   return {
     heading: "No orders yet",

package/docs/admin/testing.md

@@ -26,7 +26,7 @@ works alongside the admin-specific ones below.
 | `AdminTest.view(Resource, id)`     | View page          | Infolist entries and header actions for a record |
 | `AdminTest.form(Resource, mode?)`  | Create / Edit form | Fields, validation and saving                    |
 
-```ts
+```ts fragment
 // tests/admin/users.test.ts
 import { AdminTest, assertHasColumn, assertHasAction } from "@zerotal/admin/testing";
 import { UserResource } from "../../app/admin/UserResource.ts";
@@ -41,7 +41,7 @@ list.assertSee("ada@example.com");
 default) or `"edit"`. Drive the form through its `form` property, which holds
 every field's value:
 
-```ts
+```ts fragment
 const form = await AdminTest.form(UserResource, "create");
 assertHasField(form, UserResource, "name");
 await form.set("form", { name: "" });
@@ -56,7 +56,7 @@ those values as the second argument to `AdminTest.list()` and the page mounts as
 though the reader had arrived on that URL — which is how you assert on a filtered
 or sorted table without first driving the clicks that would produce it.
 
-```ts
+```ts fragment
 const list = await AdminTest.list(UserResource, {
   search: "ada",
   sortBy: "createdAt",
@@ -125,7 +125,7 @@ Every helper accepts a panel as its last argument, defaulting to
 `Panel.default()`. Apps that register more than one panel pass the one under test,
 so the page resolves that panel's own configuration and navigation:
 
-```ts
+```ts fragment
 const shop = Panel.get("shop");
 
 const list = await AdminTest.list(OrderResource, {}, shop);

package/docs/ai.md

@@ -116,7 +116,7 @@ a price with `registerModelPrice()`.
 
 ## Generating text
 
-```ts
+```ts fragment
 import { Ai } from "@zerotal/ai";
 
 // Just the text.
@@ -152,7 +152,7 @@ Reach for `effort` instead. It trades thoroughness against cost and latency:
 
 ### Streaming
 
-```ts
+```ts fragment
 for await (const chunk of Ai.stream({ prompt, signal })) {
   if (chunk.type === "text") process.stdout.write(chunk.text);
   if (chunk.type === "done") console.log(chunk.response.usage);
@@ -166,7 +166,7 @@ generation. See [Flow](/docs/flow) for streaming straight into a component.
 
 ### Structured output
 
-```ts
+```ts fragment
 const review = await Ai.object({ prompt: `Classify this review:\n\n${text}` }, (rule) => ({
   sentiment: rule.string().in(["positive", "neutral", "negative"]),
   summary: rule.string().max(140),
@@ -189,13 +189,13 @@ schema is defined, not when the request is sent.
 `strippedConstraints()` names exactly what the model will not see, if you want to
 check that a load-bearing constraint is visible to it:
 
-```ts
+```ts fragment
 strippedConstraints({ title: rule.string().min(3) }); // → ["title: min"]
 ```
 
 ## Tools and the agent loop
 
-```ts
+```ts fragment
 import { Ai, tool } from "@zerotal/ai";
 
 const lookupOrder = tool({
@@ -238,7 +238,7 @@ back and re-requests.
 
 ### Locking a run
 
-```ts
+```ts fragment
 await Ai.agent({
   prompt: "Refund order 4821 if it shipped over 30 days ago.",
   tools: [lookupOrder, issueRefund],
@@ -264,7 +264,7 @@ checking crashes on a response the API considers fine.
 
 This package checks the stop reason first and raises a typed error:
 
-```ts
+```ts fragment
 import { AiRefusedError } from "@zerotal/ai";
 
 try {
@@ -283,7 +283,7 @@ with `drivers.anthropic.fallbacks: false`.
 
 ## Embeddings
 
-```ts
+```ts fragment
 const { embeddings } = await Ai.embed(["first chunk", "second chunk"]);
 ```
 
@@ -294,7 +294,7 @@ One vector per input, in input order.
 A queued generation is serialized, so its completion handler is registered by **name**
 — a closure cannot survive the trip to a worker process:
 
-```ts
+```ts fragment
 // in a service provider's onBooted(), so the worker registers it too
 Ai.onGenerated("summarize-ticket", async (response, meta) => {
   await Ticket.query().where("id", meta.ticketId).update({ summary: response.text });
@@ -313,7 +313,7 @@ in-process where its tools are.
 `AiFake` replaces the container binding and answers from a script. No API key, no
 network, no flakiness:
 
-```ts
+```ts fragment
 import { AiFake } from "@zerotal/ai";
 
 const ai = AiFake.install();
@@ -361,7 +361,7 @@ suffix, a gateway that rewrites the base URL.
 Implement `AiDriver` — `text`, `stream`, `object`, `countTokens`, `verify` — and
 register it:
 
-```ts
+```ts fragment
 // in a service provider's onBooted()
 const ai = app.container.makeSync("ai");
 ai.extend("bedrock", () => new BedrockDriver(config));
@@ -371,3 +371,110 @@ Nothing else is needed. Spend ceilings, redaction, telemetry, the lock, and the
 loop all live above the driver, so a new provider is a translation layer and nothing
 more. `agent()` is optional on the interface and none of the built-in three implement
 it — they all run the same shared loop.
+
+## Reference
+
+Every exported name, grouped by the job it belongs to. The behaviour is in the
+sections above; this is the index.
+
+### Requests and responses
+
+| Name                | Description                                                                    |
+| ------------------- | ------------------------------------------------------------------------------ |
+| `AiRequest`         | What every generation call takes. `prompt` and `messages` are interchangeable. |
+| `AiResponse`        | A finished, non-streaming generation.                                          |
+| `AiStreamChunk`     | One event from a streaming generation.                                         |
+| `AiObjectResponse`  | A structured-output generation: the parsed value plus the usual accounting.    |
+| `AiMessage`         | One turn of a conversation.                                                    |
+| `AiRole`            | Who said it. Tool results ride inside a `user` turn, as the providers expect.  |
+| `AiUsage`           | Token accounting for one request. Fields a provider does not report stay 0.    |
+| `AiStopReason`      | Why generation stopped. `refusal` is a successful HTTP response, not an error. |
+| `AiEffort`          | How hard the model should work before answering. Mapped per-driver.            |
+| `AiProviderOptions` | Per-driver escape hatch, keyed by driver name and passed through untouched.    |
+| `AiEmbedRequest`    | A vector embedding request.                                                    |
+| `AiEmbedResponse`   | Embeddings, one vector per input, in input order.                              |
+
+### Tools and the agent loop
+
+| Name             | Description                                                                            |
+| ---------------- | -------------------------------------------------------------------------------------- |
+| `AiToolCall`     | A tool call the model asked for, lifted out of whatever block shape the provider used. |
+| `AiToolResult`   | The answer to one `AiToolCall`.                                                        |
+| `AiToolContext`  | What a tool handler is told about the turn that invoked it.                            |
+| `AiToolCalled`   | Emitted once per tool call inside an agent run.                                        |
+| `AiAgentRequest` | An agent run, plus the two things only the caller can decide.                          |
+| `AgentOptions`   | What the agent loop needs from the caller, beyond the request itself.                  |
+| `AiAgentResult`  | The result of running the agent loop to completion.                                    |
+| `AiAgentStep`    | One tool call and its result within an agent run.                                      |
+
+### Errors
+
+| Name                       | Description                                                                 |
+| -------------------------- | --------------------------------------------------------------------------- |
+| `AiError`                  | Base class for all `@zerotal/ai` errors.                                    |
+| `AiConfigError`            | Thrown at boot, or on first use, for a config combination that cannot work. |
+| `AiRequestError`           | Thrown for any other non-2xx from the provider, carrying its status.        |
+| `AiRateLimitError`         | Thrown when the provider rate-limits. The SDKs already retried.             |
+| `AiSpendLimitError`        | Thrown when a request would breach a configured spend ceiling.              |
+| `AiAgentLimitError`        | Thrown when the agent loop hits its step or resume ceiling.                 |
+| `AiCancelledError`         | Thrown when the caller's `AbortSignal` fired before the call finished.      |
+| `AiDriverUnavailableError` | Thrown when a driver's optional peer package is not installed.              |
+| `UnknownAiDriverError`     | Thrown for a driver name the manager does not know.                         |
+
+### Configuration
+
+| Name                    | Description                                                                   |
+| ----------------------- | ----------------------------------------------------------------------------- |
+| `AiConfigInput`         | What `AiConfig()` accepts — every key optional, all the way down.             |
+| `AiConfigFromEnv`       | The zero-config fallback: an Anthropic driver built from `ANTHROPIC_API_KEY`. |
+| `AiLimitsConfigShape`   | Spend ceilings, enforced before the request leaves.                           |
+| `AiAgentConfigShape`    | How the agent loop behaves.                                                   |
+| `AnthropicConfigShape`  | Anthropic driver settings.                                                    |
+| `OpenAiConfigShape`     | OpenAI driver settings.                                                       |
+| `OllamaConfigShape`     | Ollama driver settings — a local server, so no key.                           |
+| `EmbeddingsConfigShape` | Embeddings are their own block with their own driver.                         |
+
+### Drivers and pricing
+
+| Name                     | Description                                                                  |
+| ------------------------ | ---------------------------------------------------------------------------- |
+| `AnthropicDriver`        | The Anthropic driver.                                                        |
+| `OpenAiDriver`           | The OpenAI driver — Chat Completions over `fetch`, no SDK.                   |
+| `OllamaDriver`           | The Ollama driver — a local model server, so no API key and no billing.      |
+| `EmbeddingsDriver`       | What an embeddings provider implements.                                      |
+| `OpenAiEmbeddingsDriver` | OpenAI embeddings over `fetch`. No SDK, no dependency.                       |
+| `OllamaEmbeddingsDriver` | Ollama embeddings — a local server, so no key and no per-token cost.         |
+| `DriverStatus`           | What `zt ai:test` prints for one driver.                                     |
+| `ModelPrice`             | USD per million tokens.                                                      |
+| `modelPrice`             | The price for a model, or `undefined` when we have none.                     |
+| `estimateCost`           | Estimated USD for one request's usage. Returns 0 for an unpriced model.      |
+| `modelRejectsSampling`   | Whether a Claude model rejects `temperature` / `top_p` / `top_k` with a 400. |
+
+### Spend and statistics
+
+| Name                 | Description                                               |
+| -------------------- | --------------------------------------------------------- |
+| `spentToday`         | USD recorded so far today, in this process.               |
+| `resetSpend`         | Reset the ledger. Tests, and the `ai:spend --reset` path. |
+| `AiDelivery`         | One recorded generation.                                  |
+| `modelStats`         | Per-model roll-up over everything still in the buffer.    |
+| `ModelStat`          | Rolled-up figures for one model.                          |
+| `recentGenerations`  | The most recent generations, newest first.                |
+| `refusalRate`        | Share of recorded calls that the provider declined, 0–1.  |
+| `resetStats`         | Reset the buffer. Tests.                                  |
+| `CapturedGeneration` | One recorded call, as `AiFake` captures it.               |
+
+### Queued generation
+
+| Name             | Description                                  |
+| ---------------- | -------------------------------------------- |
+| `AiQueueOptions` | What `Ai.queue()` needs beyond the request.  |
+| `AiQueueHandler` | What a queued generation's handler receives. |
+
+### Structured-output schemas
+
+| Name              | Description                                                                 |
+| ----------------- | --------------------------------------------------------------------------- |
+| `SchemaInput`     | Either shape callers have on hand: the builder map, or the raw definitions. |
+| `toSchema`        | Normalise either input shape to raw definitions.                            |
+| `translateSchema` | Translate a validator schema into the JSON Schema the providers accept.     |

package/docs/application.md

@@ -73,7 +73,7 @@ helper reaches it anywhere.
 > **Note** — `Application.create({ providers })` and
 > `Application.create({ providers, config, env })` accept explicit providers and
 > config for lightweight in-process test setups that bypass auto-discovery. See
-> [Testing](/docs/testing/index).
+> [Testing](/docs/testing).
 
 ### The current application
 
@@ -159,7 +159,7 @@ Framework packages (`@zerotal/orm`, `@zerotal/auth`, `@zerotal/notifications`,
 their own providers. List them in the **providers array** in
 `bootstrap/providers.ts` and pass that array to `Application.create({ providers })`:
 
-```typescript
+```typescript fragment
 // bootstrap/providers.ts
 import { DatabaseProvider } from "@zerotal/orm";
 import { AuthProvider } from "@zerotal/auth";
@@ -170,7 +170,7 @@ const providers = [DatabaseProvider, AuthProvider, AppServiceProvider];
 export default providers;
 ```
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { Application, basePath } from "zerotal";
 import providers from "./providers.ts";
@@ -190,7 +190,7 @@ A deferred provider boots lazily — only the first time one of its container
 bindings is resolved. This keeps cold-start fast when a service isn't used on
 every request.
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts — defer() is called on the app instance (and returns it)
 const app = Application.create({ providers });
 
@@ -216,7 +216,7 @@ config-driven wiring, middleware. But when you just need to register a binding o
 two, that's a lot of ceremony. For those cases, `bind()` lets you register
 straight from `bootstrap/app.ts`:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { Application, basePath } from "zerotal";
 import { Clock, SystemClock } from "../app/services/clock.ts";
@@ -249,7 +249,7 @@ Declare where your routes live; the application loads them at boot, after every
 provider has registered its middleware groups (so a route file can always
 reference `web`, `api`, or any provider-supplied group).
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 Application.create().routing({
   web: "./routes/web.ts",
@@ -262,7 +262,7 @@ middleware group, `api` mounts at `/api` with the `api` group. Any other group
 name must declare both `prefix` and `middleware` explicitly (or an error is thrown
 at boot):
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 .routing({
   web: "./routes/web.ts",
@@ -273,7 +273,7 @@ at boot):
 For directory-based routing, use `fileBasedRouting()` — same key semantics, but
 each value is a directory that's scanned for exported HTTP-method handlers:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 Application.create().fileBasedRouting({ web: "./app/routes" });
 ```
@@ -285,7 +285,7 @@ root regardless of the calling file.
 
 Register global middleware that runs on every request, in array order:
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { CorsMiddleware, SecureHeadersMiddleware } from "zerotal";
 
@@ -296,7 +296,7 @@ The resolved pipeline runs provider-registered middleware first, then everything
 you added via `.use()`. You can read the final ordering back off the app instance
 (handy in a test or a diagnostic):
 
-```typescript
+```typescript fragment
 // in a test or diagnostic
 currentApp().globalMiddleware; // PipeClass[] in execution order
 ```
@@ -315,7 +315,7 @@ class to push it onto the global pipeline automatically. See
 These are the remaining configuration methods, all called on the app instance in
 `bootstrap/app.ts` (and all returning it, so they chain):
 
-```typescript
+```typescript fragment
 // bootstrap/app.ts
 import { Handler } from "../app/exceptions/Handler.ts";
 
@@ -360,7 +360,7 @@ provider hooks through a fixed set of phases.
 5. **Started** — `Bun.serve()` is live; `onStarted()` fires. A health endpoint, a
    PID file, and `SIGTERM`/`SIGINT`/`SIGUSR2` handlers are installed.
 
-```typescript
+```typescript fragment
 // zt.ts (managed) ultimately does:
 const app = (await import("./bootstrap/app.ts")).default;
 await app.start(Number(env("PORT", 3000)));

package/docs/arch.md

@@ -24,7 +24,7 @@ bun add -d @zerotal/arch
 
 Register the provider in `bootstrap/providers.ts`:
 
-```typescript
+```typescript fragment
 // bootstrap/providers.ts
 import { ArchProvider } from "@zerotal/arch";
 
@@ -189,7 +189,7 @@ The transport is exported separately from the tools, on the `@zerotal/arch/mcp`
 A tool is a plain object with a schema and a `run`, so you can serve your own alongside
 these — or serve these over a transport of your own.
 
-```typescript
+```typescript fragment
 import { McpServer, serveStdio } from "@zerotal/arch/mcp";
 import { archTools, vendoredDocsDir, spawnProbe } from "@zerotal/arch";
 
@@ -256,8 +256,30 @@ The transport is on the `@zerotal/arch/mcp` subpath: `McpServer`, `McpServerOpti
 `JsonRpcRequest`, `JsonRpcResponse`, `JsonRpcSuccess`, `JsonRpcFailure`, `JsonRpcId`,
 `RpcError`, `Meta`, `MODERN_VERSION`, `LEGACY_VERSIONS` and `SUPPORTED_VERSIONS`.
 
+## What `stable` covers here
+
+The usual promise — anything importable without an `@internal` marker keeps its
+shape for the rest of the 1.x line — and one more, because this package's real
+interface is not its exports.
+
+**The MCP tool contract is covered.** Tool names, the arguments they accept, and
+the shape of what they return do not change within 1.x. That is the surface an
+agent client is configured against: a renamed tool or a dropped field breaks
+every `.mcp.json` pointing at this server, and none of it is visible to a
+type-level check — `archTools = (ctx) => ArchTool[]` is byte-identical whatever
+the tools are called. `mcp-surface.md` records all nine and CI diffs it.
+
+**The protocol revision is not.** Which version of the Model Context Protocol the
+server speaks follows the protocol, not this package's major version. A revision
+that requires a transport change will land in a minor release, described in the
+notes.
+
+**The writers behind `arch:install` are not.** `detectAgents`, `applyMcpConfig`,
+`applyBlock`, `buildGuidelines` and the rest are `@internal`: they exist for the
+command, and the format of the files it writes is not a promise.
+
 ## Next steps
 
 - [Commands](/docs/commands) — the full `bun zt` vocabulary an agent is told about.
 - [Package Development](/docs/package-development) — contributing doctor checks of your own.
-- [Support policy](/docs/support-policy#maturity-levels) — what `beta` promises.
+- [Support policy](/docs/support-policy#maturity-levels) — what `stable` promises.