experimental-ash 0.7.2 → 0.7.3

package/dist/docs/internals/README.md

@@ -24,11 +24,11 @@ If you want the shortest path through the architecture, read these in order:
 
 ## Guides
 
-- [`../../ARCHITECTURE.md`](../../ARCHITECTURE.md) — the repo-level architecture map
-- [`core-beliefs.md`](./core-beliefs.md) — the principles behind Ash's architecture rules
-- [`mechanical-invariants.md`](./mechanical-invariants.md) — detailed constraints that should become lints or structural tests
-- [`context.md`](./context.md) — the unified context system
-- [`compiler-and-artifacts.md`](./compiler-and-artifacts.md) — how authored files become `.ash/` artifacts
-- [`discovery.md`](./discovery.md) — how the framework finds authored sources
-- [`message-runtime.md`](./message-runtime.md) — the HTTP surface and runtime execution
-- [`testing.md`](./testing.md) — test tiers and helpers
+- [Ash Architecture](../../ARCHITECTURE.md) — the repo-level architecture map
+- [Core Beliefs](./core-beliefs.md) — the principles behind Ash's architecture rules
+- [Mechanical Invariants](./mechanical-invariants.md) — detailed constraints that should become lints or structural tests
+- [Unified Context](./context.md) — the unified context system
+- [Compiler and Artifacts](./compiler-and-artifacts.md) — how authored files become `.ash/` artifacts
+- [Discovery](./discovery.md) — how the framework finds authored sources
+- [Message Runtime](./message-runtime.md) — the HTTP surface and runtime execution
+- [Testing](./testing.md) — test tiers and helpers

package/dist/docs/internals/context.md

@@ -79,7 +79,7 @@ Framework providers use a superset `FrameworkContextProvider` that also receives
 
 Authored hook lifecycle dispatch (`lifecycle.session`, `lifecycle.turn`)
 runs inside step (4)'s ALS scope, before the harness step. See
-[`./hooks.md`](./hooks.md) for the full pipeline and the
+[Hooks](./hooks.md) for the full pipeline and the
 `SessionPreparedKey` flag's failure semantics.
 
 ## Channel Context

package/dist/docs/internals/hooks.md

@@ -7,7 +7,7 @@ hooks answer the runtime.
 This page explains the discovery → compile → resolve → dispatch pipeline
 and the runtime contract every authored hook handler relies on. The
 end-user-facing reference lives at
-[`docs/public/hooks.md`](../public/hooks.md).
+[Hooks](../public/hooks.md).
 
 ## Architectural Rationale
 
@@ -196,7 +196,7 @@ documented expectations:
 
 ## Related Pages
 
-- [`docs/public/hooks.md`](../public/hooks.md) — author-facing reference
-- [`./discovery.md`](./discovery.md) — discovery layout and the unified slot walker
-- [`./context.md`](./context.md) — `AshContext` surface shared by hooks
-- [`./message-runtime.md`](./message-runtime.md) — runtime stream events
+- [Hooks](../public/hooks.md) — author-facing reference
+- [Discovery](./discovery.md) — discovery layout and the unified slot walker
+- [Unified Context](./context.md) — `AshContext` surface shared by hooks
+- [Message Runtime](./message-runtime.md) — runtime stream events

package/dist/docs/internals/message-runtime.md

@@ -48,7 +48,7 @@ step.completed → turn.completed → session.waiting / session.completed
 Failure variants: `step.failed`, `turn.failed`, `session.failed`.
 A thrown `lifecycle.session` hook produces a terminal `session.failed`;
 a thrown `lifecycle.turn` hook produces a recoverable `turn.failed`
-cascade. See [`./hooks.md`](./hooks.md).
+cascade. See [Hooks](./hooks.md).
 
 `message.appended` and `reasoning.appended` carry both delta and cumulative text. `step.completed.data.finishReason` mirrors the model-step outcome (`tool-calls` means the turn continues).
 
@@ -64,4 +64,4 @@ The runtime stores both `auth.current` and `auth.initiator`. Follow-up messages
 
 The runtime owns stream plumbing; the channel owns delivery policy. The runtime calls `channel.onEvent(event)` for each lifecycle event — the channel may transform it or perform platform side effects. The harness emits events without knowing the transport.
 
-Authored stream-event hooks fan out alongside `callAdapterEventHandler` from the same `HarnessEmitFn` composer (`workflow-steps.ts` and `continuous-runtime.ts`). Hook errors propagate through the emit composer and are caught by the existing harness error path, which emits the recoverable `turn.failed` cascade. See [`./hooks.md`](./hooks.md).
+Authored stream-event hooks fan out alongside `callAdapterEventHandler` from the same `HarnessEmitFn` composer (`workflow-steps.ts` and `continuous-runtime.ts`). Hook errors propagate through the emit composer and are caught by the existing harness error path, which emits the recoverable `turn.failed` cascade. See [Hooks](./hooks.md).

package/dist/docs/public/README.md

@@ -3,7 +3,7 @@
 This folder is for app authors using Ash as a framework.
 
 If you want to understand how to build agents with Ash, start here. If you want to understand how
-the framework is implemented internally, read [`../internals/README.md`](../internals/README.md).
+the framework is implemented internally, read [Internals](../internals/README.md).
 
 Important naming note:
 
@@ -15,26 +15,26 @@ Important naming note:
 
 Read in this order:
 
-1. [getting-started.md](./getting-started.md)
-2. [project-layout.md](./project-layout.md)
-3. [agent-ts.md](./agent-ts.md)
-4. [typescript-api.md](./typescript-api.md)
-5. [context-control.md](./context-control.md)
-6. [skills.md](./skills.md)
-7. [tools.md](./tools.md)
-8. [connections.md](./connections.md)
-9. [workspace.md](./workspace.md)
-10. [sandbox.md](./sandbox.md)
-11. [channels/README.md](./channels/README.md)
-12. [human-in-the-loop.md](./human-in-the-loop.md)
-13. [session-context.md](./session-context.md)
-14. [runs-and-streaming.md](./runs-and-streaming.md)
-15. [subagents.md](./subagents.md)
-16. [schedules.md](./schedules.md)
-17. [evals.md](./evals.md)
-18. [auth-and-route-protection.md](./auth-and-route-protection.md)
-19. [vercel-deployment.md](./vercel-deployment.md)
-20. [cli-build-and-debugging.md](./cli-build-and-debugging.md)
+1. [Getting Started](./getting-started.md)
+2. [Project Layout](./project-layout.md)
+3. [`agent.ts`](./agent-ts.md)
+4. [TypeScript API](./typescript-api.md)
+5. [Context Control](./context-control.md)
+6. [Skills](./skills.md)
+7. [Tools](./tools.md)
+8. [Connections](./connections.md)
+9. [Workspace](./workspace.md)
+10. [Sandboxes](./sandbox.md)
+11. [Channels](./channels/README.md)
+12. [Human In The Loop](./human-in-the-loop.md)
+13. [Session Context](./session-context.md)
+14. [Sessions And Streaming](./runs-and-streaming.md)
+15. [Subagents](./subagents.md)
+16. [Schedules](./schedules.md)
+17. [Evals](./evals.md)
+18. [Auth And Route Protection](./auth-and-route-protection.md)
+19. [Vercel Deployment](./vercel-deployment.md)
+20. [CLI, Build, And Debugging](./cli-build-and-debugging.md)
 
 ## The Public Mental Model
 
@@ -88,4 +88,4 @@ That is why Ash exposes two identifiers:
 
 - Minimal end-to-end example: [`../../apps/weather-agent`](../../apps/weather-agent)
 - Public API source of truth: [`../../packages/ash/src/public/index.ts`](../../packages/ash/src/public/index.ts)
-- Framework internals: [`../internals/README.md`](../internals/README.md)
+- Framework internals: [Internals](../internals/README.md)

package/dist/docs/public/agent-ts.md

@@ -1,6 +1,6 @@
 ---
 title: "agent.ts"
-description: "Configure your agent with agent.ts: model, name, metadata, and runtime options."
+description: "Configure your agent with agent.ts: model, metadata, and runtime options."
 ---
 
 `agent.ts` is the additive runtime config entrypoint for an Ash agent.
@@ -13,7 +13,6 @@ Put instructions in `instructions.md`. Put runtime settings in `agent.ts`.
 import { defineAgent } from "experimental-ash";
 
 export default defineAgent({
-  name: "support-agent",
   model: "openai/gpt-5.4-mini",
   metadata: {
     team: "support",
@@ -33,7 +32,6 @@ export default defineAgent({
 Use `agent.ts` for:
 
 - model selection
-- stable agent name
 - metadata you want preserved in runtime traces
 - human-in-the-loop policy
 - hosted-build packaging controls
@@ -41,7 +39,7 @@ Use `agent.ts` for:
 - provider-specific model options
 
 For OpenTelemetry configuration, use `instrumentation.ts` instead. See
-[`instrumentation.md`](./instrumentation.md).
+[`instrumentation.ts`](./instrumentation.md).
 
 Do not use `agent.ts` for long-form instructions. Put those in `instructions.md` (or `instructions.ts`) and
 `skills/`.
@@ -94,14 +92,21 @@ export default defineAgent({
 });
 ```
 
-## `name` And `metadata`
+## Agent Identity
 
-`name` is the public agent name you want Ash to use for this app.
+The agent's name is derived at compile time from the filesystem layout:
+
+- A root agent (its `agent.ts` sits at the app root or directly under `agent/`) takes its name
+  from the enclosing `package.json`'s `name` field.
+- A nested agent takes its name from its own directory (e.g. `subagents/researcher/agent.ts` →
+  `"researcher"`).
+
+## `metadata`
 
 `metadata` is a simple string map for app-owned labels that should travel with the resolved agent
 definition and related runtime metadata.
 
-Use them for stable identifiers, environment labels, or ownership metadata. Avoid secrets here.
+Use it for environment labels or ownership metadata. Avoid secrets here.
 
 ## `build`
 
@@ -123,7 +128,7 @@ server output instead of being bundled.
 - `model` optionally overrides the model used for compaction summaries
 
 The shared per-run workspace is configured on the sandbox, not on `agent.ts`. See
-[`workspace.md`](./workspace.md) and [`sandbox.md`](./sandbox.md).
+[Workspace](./workspace.md) and [Sandboxes](./sandbox.md).
 
 ## `humanInTheLoop`
 
@@ -147,13 +152,13 @@ Supported fields:
 Use `require-approval` when the default should be "ask first". Use `auto-allow` when the default
 should be "run immediately" and only a few named tools should still require approval.
 
-See [`human-in-the-loop.md`](./human-in-the-loop.md) for the runtime flow, `input.requested`
+See [Human In The Loop](./human-in-the-loop.md) for the runtime flow, `input.requested`
 events, and HTTP response payloads.
 
 ## Telemetry
 
 OpenTelemetry tracing is configured in `agent/instrumentation.ts`, not in `agent.ts`. See
-[`instrumentation.md`](./instrumentation.md) for setup.
+[`instrumentation.ts`](./instrumentation.md) for setup.
 
 ## Route Auth And Network Policy
 
@@ -161,8 +166,8 @@ OpenTelemetry tracing is configured in `agent/instrumentation.ts`, not in `agent
 
 Those concerns live on the HTTP channel layer instead. See:
 
-- [`auth-and-route-protection.md`](./auth-and-route-protection.md)
-- [`channels/README.md`](./channels/README.md)
+- [Auth And Route Protection](./auth-and-route-protection.md)
+- [Channels](./channels/README.md)
 
 ## A Good Default
 
@@ -172,7 +177,6 @@ For many apps, `agent.ts` stays small:
 import { defineAgent } from "experimental-ash";
 
 export default defineAgent({
-  name: "weather-agent",
   model: "openai/gpt-5.4-mini",
 });
 ```
@@ -181,7 +185,7 @@ That is enough to start. Add build and compaction settings only when you need th
 
 ## What To Read Next
 
-- [`context-control.md`](./context-control.md)
-- [`human-in-the-loop.md`](./human-in-the-loop.md)
-- [`workspace.md`](./workspace.md)
-- [`auth-and-route-protection.md`](./auth-and-route-protection.md)
+- [Context Control](./context-control.md)
+- [Human In The Loop](./human-in-the-loop.md)
+- [Workspace](./workspace.md)
+- [Auth And Route Protection](./auth-and-route-protection.md)

package/dist/docs/public/auth-and-route-protection.md

@@ -140,6 +140,6 @@ export default ashChannel({
 
 ## What To Read Next
 
-- [`agent-ts.md`](./agent-ts.md)
-- [`session-context.md`](./session-context.md)
-- [`vercel-deployment.md`](./vercel-deployment.md)
+- [`agent.ts`](./agent-ts.md)
+- [Session Context](./session-context.md)
+- [Vercel Deployment](./vercel-deployment.md)

package/dist/docs/public/channels/README.md

@@ -93,7 +93,7 @@ The framework ships its canonical session protocol on `experimental-ash/channels
 - `ashChannel({ auth })`
 
 This is the channel the Ash dev client and any deployed-agent SDK talk to — it mounts the routes
-under `/ash/v1/session*` documented in [`../../external-agent-protocol.md`](../../external-agent-protocol.md).
+under `/ash/v1/session*` documented in [Ash External Agent Protocol](../../external-agent-protocol.md).
 
 It requires an auth function. Use `experimental-ash/channels/auth` for the common helpers such as
 `vercelOidc()`, `httpBasic()`, and `none()`.
@@ -208,7 +208,7 @@ Each compiles down to the one below it:
 - `slackChannel(config)` -> `defineChannel` + Chat SDK setup + typed event dispatch
 - `defineChannel` -> the primitive
 
-For a Slack app backed by Vercel Connex, see [`./slack.md`](./slack.md) to create the Connex client
+For a Slack app backed by Vercel Connex, see [Slack channel setup](./slack.md) to create the Connex client
 and channel file.
 
 ## File Uploads
@@ -251,9 +251,9 @@ at send time.
 
 ## What To Read Next
 
-- [`./slack.md`](./slack.md)
-- [`./attachments.md`](./attachments.md)
-- [`../project-layout.md`](../project-layout.md)
-- [`../typescript-api.md`](../typescript-api.md)
-- [`../auth-and-route-protection.md`](../auth-and-route-protection.md)
-- [`../../external-agent-protocol.md`](../../external-agent-protocol.md)
+- [Slack channel setup](./slack.md)
+- [Channel attachments](./attachments.md)
+- [Project Layout](../project-layout.md)
+- [TypeScript API](../typescript-api.md)
+- [Auth And Route Protection](../auth-and-route-protection.md)
+- [Ash External Agent Protocol](../../external-agent-protocol.md)

package/dist/docs/public/cli-build-and-debugging.md

@@ -80,6 +80,6 @@ When something is wrong:
 
 ## What To Read Next
 
-- [`project-layout.md`](./project-layout.md)
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
-- [`typescript-api.md`](./typescript-api.md)
+- [Project Layout](./project-layout.md)
+- [Sessions And Streaming](./runs-and-streaming.md)
+- [TypeScript API](./typescript-api.md)

package/dist/docs/public/connections.md

@@ -124,7 +124,7 @@ when it needs a different cache and principal model:
   (status pages, shared dashboards, system bots).
 
 Ash resolves the active principal before every authorization call. See
-[`session-context.md`](./session-context.md) for how the principal flows through the runtime.
+[Session Context](./session-context.md) for how the principal flows through the runtime.
 
 ## Headers
 
@@ -157,7 +157,7 @@ export default defineMcpClientConnection({
 ```
 
 `never()` allows all calls, `once()` requires approval the first time per session, `always()`
-requires approval every time. See [`human-in-the-loop.md`](./human-in-the-loop.md) for the approval
+requires approval every time. See [Human In The Loop](./human-in-the-loop.md) for the approval
 runtime.
 
 ## Tool Filters
@@ -177,6 +177,6 @@ Tools that don't pass the filter are silently excluded from `connection_search`.
 
 ## What To Read Next
 
-- [`tools.md`](./tools.md) — authored tools live alongside connection-provided tools.
-- [`human-in-the-loop.md`](./human-in-the-loop.md) — interactive consent and approval runtime.
-- [`session-context.md`](./session-context.md) — how the active principal flows through the runtime.
+- [Tools](./tools.md) — authored tools live alongside connection-provided tools.
+- [Human In The Loop](./human-in-the-loop.md) — interactive consent and approval runtime.
+- [Session Context](./session-context.md) — how the active principal flows through the runtime.

package/dist/docs/public/context-control.md

@@ -88,7 +88,7 @@ prompt.
 - flat markdown skills may omit frontmatter
 - tools stay visible whether or not a skill is activated
 
-See [`skills.md`](./skills.md) for the full authoring model and install notes.
+See [Skills](./skills.md) for the full authoring model and install notes.
 
 ## 4. Put Runtime Files In The Workspace, Not The Prompt
 
@@ -102,7 +102,7 @@ Today that mainly means:
 - skill files are available under the active runtime workspace root
 - the model can inspect them with the shared `bash` tool
 
-See [`workspace.md`](./workspace.md) and [`sandbox.md`](./sandbox.md).
+See [Workspace](./workspace.md) and [Sandboxes](./sandbox.md).
 
 ## 5. Delegate To A Specialist With A Subagent
 
@@ -115,7 +115,7 @@ Subagents are a context-control tool too:
 - they can have their own tools and their own sandbox
 - they run inside their own delegated subagent context instead of extending the root agent inline
 
-See [`subagents.md`](./subagents.md).
+See [Subagents](./subagents.md).
 
 ## Choosing The Right Lever
 
@@ -139,8 +139,8 @@ For most agents:
 
 ## What To Read Next
 
-- [`tools.md`](./tools.md)
-- [`hooks.md`](./hooks.md)
-- [`skills.md`](./skills.md)
-- [`workspace.md`](./workspace.md)
-- [`subagents.md`](./subagents.md)
+- [Tools](./tools.md)
+- [Hooks](./hooks.md)
+- [Skills](./skills.md)
+- [Workspace](./workspace.md)
+- [Subagents](./subagents.md)

package/dist/docs/public/evals.md

@@ -287,6 +287,6 @@ For most apps:
 
 ## What To Read Next
 
-- [`typescript-api.md`](./typescript-api.md)
-- [`tools.md`](./tools.md)
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
+- [TypeScript API](./typescript-api.md)
+- [Tools](./tools.md)
+- [Sessions And Streaming](./runs-and-streaming.md)

package/dist/docs/public/getting-started.md

@@ -157,8 +157,8 @@ curl -X POST http://127.0.0.1:3000/ash/v1/session/<sessionId> \
 
 ## What To Read Next
 
-- [`project-layout.md`](./project-layout.md) for every supported authored slot
-- [`agent-ts.md`](./agent-ts.md) for runtime config
-- [`skills.md`](./skills.md) for on-demand procedures
-- [`tools.md`](./tools.md) for typed integrations
-- [`runs-and-streaming.md`](./runs-and-streaming.md) for the durable session model
+- [Project Layout](./project-layout.md) for every supported authored slot
+- [`agent.ts`](./agent-ts.md) for runtime config
+- [Skills](./skills.md) for on-demand procedures
+- [Tools](./tools.md) for typed integrations
+- [Sessions And Streaming](./runs-and-streaming.md) for the durable session model

package/dist/docs/public/hooks.md

@@ -230,7 +230,7 @@ when both are registered.
 
 ## What to read next
 
-- [`tools.md`](./tools.md)
-- [`context-control.md`](./context-control.md)
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
-- [`session-context.md`](./session-context.md)
+- [Tools](./tools.md)
+- [Context Control](./context-control.md)
+- [Sessions And Streaming](./runs-and-streaming.md)
+- [Session Context](./session-context.md)

package/dist/docs/public/human-in-the-loop.md

@@ -249,6 +249,6 @@ If you press `Escape` and then send a normal message, the pending requests are i
 
 ## What To Read Next
 
-- [`agent-ts.md`](./agent-ts.md)
-- [`tools.md`](./tools.md)
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
+- [`agent.ts`](./agent-ts.md)
+- [Tools](./tools.md)
+- [Sessions And Streaming](./runs-and-streaming.md)

package/dist/docs/public/instrumentation.md

@@ -36,7 +36,8 @@ telemetry -- there is no separate `isEnabled` toggle.
 
 The `setup` callback is invoked by the framework at server startup with the resolved agent name. Use
 it to register your OTel provider (e.g. `registerOTel` from `@vercel/otel`). The
-`context.agentName` value comes from `defineAgent`, so you never need to hard-code a service name.
+`context.agentName` is derived from the agent's filesystem path at compile time, so you never need
+to hard-code a service name.
 
 Any OTel-compatible backend works (Braintrust, Honeycomb, Datadog, Jaeger). Install the exporter
 package you need and configure it in the callback.
@@ -73,5 +74,5 @@ calls and tool executions are traced automatically. Session context (`ash.versio
 
 ## What To Read Next
 
-- [`agent-ts.md`](./agent-ts.md)
-- [`project-layout.md`](./project-layout.md)
+- [`agent.ts`](./agent-ts.md)
+- [Project Layout](./project-layout.md)

package/dist/docs/public/project-layout.md

@@ -34,11 +34,11 @@ my-agent/
 | Path                                   | Purpose                                                                                                                                                                                                                                | Notes                                                                                                                                                                                                                                           |
 | -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `instructions.md` or `instructions.ts` | Base instructions prompt                                                                                                                                                                                                               | Exactly one instructions prompt is expected. Module-backed sources execute once at build time; the resulting markdown is baked into the compiled manifest. The legacy `system.{md,ts,...}` slot is still discovered with a deprecation warning. |
-| `agent.ts`                             | Runtime config                                                                                                                                                                                                                         | Model, name, metadata, workspace, build, compaction                                                                                                                                                                                             |
+| `agent.ts`                             | Runtime config                                                                                                                                                                                                                         | Model, metadata, workspace, build, compaction                                                                                                                                                                                                   |
 | `instrumentation.ts`                   | Telemetry config                                                                                                                                                                                                                       | OTel exporter setup and AI SDK span settings; auto-discovered and run before agent code                                                                                                                                                         |
 | `channels/`                            | HTTP or messaging entrypoints                                                                                                                                                                                                          | Root-only today                                                                                                                                                                                                                                 |
 | `connections/`                         | External service connections (MCP)                                                                                                                                                                                                     | Each file defines one connection; name derived from filename                                                                                                                                                                                    |
-| `hooks/`                               | Lifecycle and stream-event subscribers                                                                                                                                                                                                 | Module-backed only. Recursive directories supported. See [`hooks.md`](./hooks.md).                                                                                                                                                              |
+| `hooks/`                               | Lifecycle and stream-event subscribers                                                                                                                                                                                                 | Module-backed only. Recursive directories supported. See [Hooks](./hooks.md).                                                                                                                                                                   |
 | `skills/`                              | On-demand procedures and capability packs                                                                                                                                                                                              | Flat markdown, module-backed skills, or packaged skills                                                                                                                                                                                         |
 | `lib/`                                 | Shared authored helper code                                                                                                                                                                                                            | Import-only source, not mounted into the workspace                                                                                                                                                                                              |
 | `sandbox/` or `sandbox.ts`             | The agent's single sandbox. Use top-level `sandbox.ts` for a definition-only override; use `sandbox/sandbox.ts` + optional `sandbox/workspace/**` when you also want seeded files. Framework default applies when neither is authored. | Supported on the root agent and local subagents                                                                                                                                                                                                 |
@@ -135,7 +135,7 @@ the sandbox workspace today:
 - skill files under `skills/` are seeded into `/workspace/skills/...`
 - files under `agent/sandbox/workspace/` are mirrored into `/workspace/...` at session bootstrap
 
-See [`sandbox.md`](./sandbox.md#seeding-workspace-files) for the convention.
+See [Sandboxes](./sandbox.md#seeding-workspace-files) for the convention.
 
 Important boundary:
 
@@ -155,15 +155,15 @@ Use:
 - `channels/` for HTTP or messaging ingress and delivery
 - `lib/` for shared helper modules imported by the slots above
 
-See [`connections.md`](./connections.md) for the connection authorization shape, including the
+See [Connections](./connections.md) for the connection authorization shape, including the
 `@vercel/connex/ash` helper for OAuth-backed connections.
 
 ## What To Read Next
 
-- [`agent-ts.md`](./agent-ts.md)
-- [`context-control.md`](./context-control.md)
-- [`connections.md`](./connections.md)
-- [`hooks.md`](./hooks.md)
-- [`skills.md`](./skills.md)
-- [`tools.md`](./tools.md)
-- [`channels/README.md`](./channels/README.md)
+- [`agent.ts`](./agent-ts.md)
+- [Context Control](./context-control.md)
+- [Connections](./connections.md)
+- [Hooks](./hooks.md)
+- [Skills](./skills.md)
+- [Tools](./tools.md)
+- [Channels](./channels/README.md)

package/dist/docs/public/runs-and-streaming.md

@@ -108,6 +108,6 @@ Important behavior:
 
 ## What To Read Next
 
-- [`session-context.md`](./session-context.md)
-- [`subagents.md`](./subagents.md)
-- [`schedules.md`](./schedules.md)
+- [Session Context](./session-context.md)
+- [Subagents](./subagents.md)
+- [Schedules](./schedules.md)

package/dist/docs/public/sandbox.md

@@ -375,6 +375,6 @@ Important behavior:
 
 ## What To Read Next
 
-- [`tools.md`](./tools.md)
-- [`workspace.md`](./workspace.md)
-- [`session-context.md`](./session-context.md)
+- [Tools](./tools.md)
+- [Workspace](./workspace.md)
+- [Session Context](./session-context.md)

package/dist/docs/public/session-context.md

@@ -17,7 +17,7 @@ Ash exposes runtime helpers for authored code:
 These APIs work only inside active authored runtime execution such as tools, channel event
 handlers, and authored hooks. Under the hood, they read from a single `AshContext` container that
 the framework binds to the current async call chain via `AsyncLocalStorage`. Authored hooks
-receive the same `ContextAccessor` on `HookContext.ash` -- see [`hooks.md`](./hooks.md).
+receive the same `ContextAccessor` on `HookContext.ash` -- see [Hooks](./hooks.md).
 
 ## `getSession()`
 
@@ -28,9 +28,11 @@ Use `getSession()` when you need durable runtime metadata about the current exec
 ```ts
 import { getSession } from "experimental-ash/context";
 import { defineTool } from "experimental-ash/tools";
+import { z } from "zod";
 
 export default defineTool({
   description: "Return the active session metadata.",
+  inputSchema: z.object({}),
   async execute() {
     const session = getSession();
 
@@ -83,7 +85,7 @@ Important behavior:
 backend-native path for a logical `/workspace/...` location before passing it to shell code or a
 child process.
 
-See [`sandbox.md`](./sandbox.md) for lifecycle details.
+See [Sandboxes](./sandbox.md) for lifecycle details.
 
 ## `getSkill(identifier)`
 
@@ -103,7 +105,7 @@ Important behavior:
 - missing skills surface when a file accessor reads a missing sandbox path
 - the returned handle exposes `name` and `file(relativePath)`
 
-See [`skills.md`](./skills.md) for the full authoring model.
+See [Skills](./skills.md) for the full authoring model.
 
 ## Passing Custom Context From a Channel
 
@@ -164,10 +166,12 @@ Auth lives on the return value of `run()`, not on a separate channel object.
 ```ts
 import { requireContext } from "experimental-ash/context";
 import { defineTool } from "experimental-ash/tools";
+import { z } from "zod";
 import { TenantKey } from "../channels/keys.js";
 
 export default defineTool({
   description: "Return the active tenant.",
+  inputSchema: z.object({}),
   async execute() {
     const tenant = requireContext(TenantKey);
     return { tenant };
@@ -241,6 +245,6 @@ accessors.
 
 ## What To Read Next
 
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
-- [`subagents.md`](./subagents.md)
-- [`skills.md`](./skills.md)
+- [Sessions And Streaming](./runs-and-streaming.md)
+- [Subagents](./subagents.md)
+- [Skills](./skills.md)

package/dist/docs/public/skills.md

@@ -83,9 +83,11 @@ Inside authored runtime code, you can read those packaged files through `getSkil
 ```ts
 import { getSkill } from "experimental-ash/skills";
 import { defineTool } from "experimental-ash/tools";
+import { z } from "zod";
 
 export default defineTool({
   description: "Load a packaged skill reference file.",
+  inputSchema: z.object({}),
   async execute() {
     const research = getSkill("research");
     return await research.file("references/checklist.md").text();
@@ -186,6 +188,6 @@ For most apps:
 
 ## What To Read Next
 
-- [`context-control.md`](./context-control.md)
-- [`tools.md`](./tools.md)
-- [`subagents.md`](./subagents.md)
+- [Context Control](./context-control.md)
+- [Tools](./tools.md)
+- [Subagents](./subagents.md)

package/dist/docs/public/subagents.md

@@ -130,5 +130,5 @@ just needs an optional procedure, prefer `skills/`.
 
 ## What To Read Next
 
-- [`context-control.md`](./context-control.md)
-- [`runs-and-streaming.md`](./runs-and-streaming.md)
+- [Context Control](./context-control.md)
+- [Sessions And Streaming](./runs-and-streaming.md)

package/dist/docs/public/tools.md

@@ -47,11 +47,10 @@ Runtime context helpers (`getSession`, `getContext`, `requireContext`, `hasConte
 
 - a filename slug under `agent/tools/` (this is the model-facing tool name)
 - `description`
-- `inputSchema` — a Zod schema (or any Standard Schema). Use `z.object({})` for tools with no input.
+- `inputSchema` — a Zod schema (or any Standard Schema). Required, matching the AI SDK's `Tool` contract. For a tool with no input, pass `z.object({})`.
 - `execute(input, options?)` — the tool's implementation. `options` provides `toolCallId`, `messages`, and `abortSignal` from the AI SDK.
 
-If you provide `inputSchema`, the AI SDK uses it to validate and transform model input (including
-Zod defaults) and to type `execute(input)`.
+The AI SDK uses `inputSchema` to validate and transform model input (including Zod defaults) and to type `execute(input)`.
 
 ## Schemas
 
@@ -321,5 +320,5 @@ export default defineTool({
 
 ## What To Read Next
 
-- [`session-context.md`](./session-context.md)
-- [`sandbox.md`](./sandbox.md)
+- [Session Context](./session-context.md)
+- [Sandboxes](./sandbox.md)