experimental-ash 0.35.0 → 0.37.0

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # experimental-ash
 
+## 0.37.0
+
+### Minor Changes
+
+- 25ef58e: Reject extra top-level fields passed to core `define*` helpers while preserving literal inference for valid definitions. TypeScript now also enforces documented exclusivity for schedules (`markdown` or `run`) and eval suites (`load` or `cases`, `task.prompt` or `task.messages`).
+
+### Patch Changes
+
+- 8b678cc: Channel event handlers now receive `AshCallbackContext` fields — `ctx.session` (with `turn`/`parent`), `ctx.getSandbox()`, and `ctx.getSkill()`. Channel-specific `continuationToken` and `setContinuationToken` are available at the top level of the event context.
+
+## 0.36.0
+
+### Minor Changes
+
+- 34722b0: Unify runtime data access: `ctx` is available as the last argument to all ALS-scoped authored callbacks. Omit it when you don't need it.
+
+  **Breaking changes:**
+
+  - Tool `execute(input)` → `execute(input, ctx)` — access session, sandbox, and skills via `ctx`
+  - Hook lifecycle `(input, ctx)` → `(ctx)` — session identity, auth, and turn info are on `ctx.session`
+  - Hook/channel events `(event, ctx)` → same shape, but `ctx` now carries `session`, `getSandbox()`, `getSkill()`
+  - `SessionHandle.id` (unchanged), `.auth` is now `{ current, initiator }` (was flat)
+  - `getSession()`, `getSandbox()`, `getSkill()` removed — use `ctx.session`, `ctx.getSandbox()`, `ctx.getSkill()`
+  - `HookContext.ash` removed — use `defineState` for durable state
+  - `CompactionHookInput` → `onCompact({ history, signal }, ctx)`
+  - `LifecycleHookInput` removed (absorbed into `HookContext`)
+
+  Non-ALS callbacks unchanged: schedule `run`, sandbox `bootstrap`/`onSession`, instrumentation `setup`.
+
+### Patch Changes
+
+- 4e50396: Fixed parked subagent/remote-agent turns persisting a stale (default) emission state. The runtime-action park now stamps the live turn's emission identity onto the parked session, so the resume turn is classified as a continuation instead of a fresh turn — preventing duplicate `session.started`/`turn.started` events and empty `turnId`s on resume.
+
 ## 0.35.0
 
 ### Minor Changes

package/README.md

@@ -61,7 +61,7 @@ Runtime accessors live on the subpath that owns the concern:
 - `getSkill(identifier)` — handle for a named skill visible to the current agent (`experimental-ash/skills`)
 - `getContext(key)`, `requireContext(key)`, `hasContext(key)`, `setContext(key)`, `ensureContext(key, factory)` — unified context helpers (`experimental-ash/context`)
 
-The complete API reference, including types and lower-level runtime primitives, is in [`./dist/docs/public/typescript-api.md`](./dist/docs/public/typescript-api.md).
+The complete API reference, including types and lower-level runtime primitives, is in [`./dist/docs/public/advanced/typescript-api.md`](./dist/docs/public/advanced/typescript-api.md).
 
 ## Tiny Example
 
@@ -121,7 +121,7 @@ CLI commands:
 
 ## Deploying
 
-Ash is built for Vercel. The runtime is Nitro + Vercel Workflows. Read [`./dist/docs/public/vercel-deployment.md`](./dist/docs/public/vercel-deployment.md) for the deployment path, environment variables, and Vercel-specific configuration.
+Ash is built for Vercel. The runtime is Nitro + Vercel Workflows. Read [`./dist/docs/public/advanced/vercel-deployment.md`](./dist/docs/public/advanced/vercel-deployment.md) for the deployment path, environment variables, and Vercel-specific configuration.
 
 ## Read Next
 
@@ -129,14 +129,14 @@ These files ship inside the installed package at `node_modules/experimental-ash/
 
 - [Full docs index](./dist/docs/public/README.md) — recommended entry point
 - [Getting Started](./dist/docs/public/getting-started.md) — install, scaffold, and run locally
-- [Project Layout](./dist/docs/public/project-layout.md) — every authored directory in depth
+- [Project Layout](./dist/docs/public/advanced/project-layout.md) — every authored directory in depth
 - [`agent.ts`](./dist/docs/public/agent-ts.md) — agent config reference
-- [TypeScript API](./dist/docs/public/typescript-api.md) — complete `define*` and runtime helper reference
-- [Vercel Deployment](./dist/docs/public/vercel-deployment.md) — deploy to production
+- [TypeScript API](./dist/docs/public/advanced/typescript-api.md) — complete `define*` and runtime helper reference
+- [Vercel Deployment](./dist/docs/public/advanced/vercel-deployment.md) — deploy to production
 
-By authoring concern: [Tools](./dist/docs/public/tools.md) · [Channels](./dist/docs/public/channels/README.md) · [Hooks](./dist/docs/public/hooks.md) · [Skills](./dist/docs/public/skills.md) · [Sandbox](./dist/docs/public/sandbox.md) · [Workspace](./dist/docs/public/workspace.md) · [Connections](./dist/docs/public/connections.md) · [Subagents](./dist/docs/public/subagents.md) · [Schedules](./dist/docs/public/schedules.md) · [Human In The Loop](./dist/docs/public/human-in-the-loop.md) · [Evals](./dist/docs/public/evals.md)
+By authoring concern: [Tools](./dist/docs/public/tools.md) · [Channels](./dist/docs/public/channels/README.md) · [Hooks](./dist/docs/public/advanced/hooks.md) · [Skills](./dist/docs/public/skills.md) · [Sandbox](./dist/docs/public/sandbox.md) · [Workspace](./dist/docs/public/advanced/workspace.md) · [Connections](./dist/docs/public/connections.md) · [Subagents](./dist/docs/public/subagents.md) · [Schedules](./dist/docs/public/schedules.md) · [Human In The Loop](./dist/docs/public/human-in-the-loop.md) · [Evals](./dist/docs/public/advanced/evals.md)
 
-By runtime concern: [Sessions and Streaming](./dist/docs/public/runs-and-streaming.md) · [Session Context](./dist/docs/public/session-context.md) · [Context Control](./dist/docs/public/context-control.md) · [Auth and Route Protection](./dist/docs/public/auth-and-route-protection.md) · [CLI, Build, and Debugging](./dist/docs/public/cli-build-and-debugging.md) · [Instrumentation](./dist/docs/public/instrumentation.md)
+By runtime concern: [Sessions and Streaming](./dist/docs/public/advanced/runs-and-streaming.md) · [Session Context](./dist/docs/public/advanced/session-context.md) · [Context Control](./dist/docs/public/advanced/context-control.md) · [Auth and Route Protection](./dist/docs/public/advanced/auth-and-route-protection.md) · [CLI, Build, and Debugging](./dist/docs/public/advanced/cli-build-and-debugging.md) · [Instrumentation](./dist/docs/public/advanced/instrumentation.md)
 
 ## Architecture (Internals)
 

package/dist/docs/internals/context.md

@@ -17,7 +17,7 @@ interface AshContext {
 }
 ```
 
-`loadContext()` returns the active context or throws. Public accessors (`getSession()`, `getSandbox()`, `getSkill()`) delegate to it.
+`loadContext()` returns the active context or throws. Internal accessors (`getSession()`, `getSandbox()`, `getSkill()`) delegate to it — these are implementation details, not public exports. Authored code uses `ctx.session`, `ctx.getSandbox()`, and `ctx.getSkill()` instead.
 
 ## Type Hierarchy
 
@@ -78,9 +78,10 @@ Framework providers use a superset `FrameworkContextProvider` that also receives
 5. Call framework provider `commit` hooks for provider-owned session state
 
 Authored hook lifecycle dispatch (`lifecycle.session`, `lifecycle.turn`)
-runs inside step (4)'s ALS scope, before the harness step. See
-[Hooks](./hooks.md) for the full pipeline and the
-`SessionPreparedKey` flag's failure semantics.
+runs inside step (4)'s ALS scope, before the harness step. Lifecycle
+hooks receive `(ctx)`, and event hooks receive `(event, ctx)`. See
+[Hooks](./hooks.md) for the full pipeline and the `SessionPreparedKey`
+flag's failure semantics.
 
 `StepInput.modelContext` has two producers. Channels can provide
 ephemeral messages through `SendPayload.modelContext`, and lifecycle
@@ -91,7 +92,7 @@ call only and are never persisted to durable session history.
 
 ## Channel Context
 
-Channels set custom durable context keys inside `onDeliver(ctx, payload)`. The method receives a `ContextAccessor` and returns `Promise<StepInput>`. This runs once per turn (both initial `run()` and each `deliver()`), after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the accessor.
+Channels set custom durable context keys inside `onDeliver(ctx, payload)`. The method receives a context accessor and returns `Promise<StepInput>`. This runs once per turn (both initial `run()` and each `deliver()`), after auth keys are seeded. Channel code stays workflow-agnostic because it only touches the accessor.
 
 Auth lives on the run and deliver inputs:
 

package/dist/docs/internals/core-beliefs.md

@@ -15,8 +15,8 @@ source of truth; a repeated `name` field is a second source that can drift.
 
 The hooks surface (`agent/hooks/`) deliberately reuses the unified
 `AshContext` rather than introducing a parallel state-patch channel:
-hooks read and write through `ctx.ash` like every other authored
-function. One context, one set of keys, one place to look when debugging.
+hooks read and write through `ctx` like every other authored function.
+One context, one set of keys, one place to look when debugging.
 
 ## Durable Work Belongs In The Runtime
 

package/dist/docs/internals/hooks.md

@@ -18,15 +18,20 @@ through one runtime registry, one `HookContext`, one set of ordering
 rules.
 
 The hooks surface deliberately reuses the unified `AshContext`:
-`HookContext.ash` is the same `ContextAccessor` tools, providers, and
-channels get. There is no parallel state-patch channel — one
-`AshContext`, one set of keys, one place to look when debugging.
+`HookContext` extends `AshCallbackContext`, giving hooks the same
+context surface tools, providers, and channels get. There is no
+parallel state-patch channel — one `AshContext`, one set of keys, one
+place to look when debugging.
 
-`HookContext` itself is intentionally tiny: `agent`, `channel`, `session`
-identity plus the `ash` accessor. Per-turn `turnId` and `sequence` come
-from `LifecycleHookInput.turn` for lifecycle hooks, and from
-`event.data.{turnId, sequence}` for stream-event hooks — never duplicated
-on the context.
+`HookContext` carries `agent`, `channel`, and `session` (which includes
+`id`, `auth`, `turn`, and `parent`). `session.auth` is a nested
+`SessionAuth` with `{ current, initiator }`.
+
+Lifecycle hooks receive `(ctx)` — a single `HookContext` argument.
+Event hooks receive `(event, ctx)` — event first, context last (omit `ctx` when unused).
+Per-turn `turnId` and `sequence` come from `ctx.session.turn` for
+lifecycle hooks, and from `event.data.{turnId, sequence}` for
+stream-event hooks — never duplicated on the context.
 
 ## Authoring shape
 
@@ -87,7 +92,7 @@ the workflow path.
 Lifecycle dispatch lives in `src/context/hook-lifecycle.ts`. The
 workflow runtime entry point (`execution/workflow-steps.ts`) calls
 `runHookLifecycleStep` once per turn, **inside** the active ALS scope
-so hook code can read and write `ctx.ash` like every other authored
+so hook code can read and write context like every other authored
 function. `runHookLifecycleStep` wraps `dispatchHookLifecycle`, lowers
 a `turn-failed` outcome into a parking `StepResult` (`{ next: null }`
 for conversation mode, `{ next: { done: true, output } }` for task
@@ -142,7 +147,7 @@ Subagent hooks are fully isolated by structural construction:
   established by the existing subagent invocation pipeline. Hooks
   resolve from the subagent node's `hookRegistry`, not the parent
   agent's.
-- `ctx.ash` reads hit the subagent's container, not the parent's.
+- `ctx` reads hit the subagent's container, not the parent's.
 - Lexicographic ordering applies within a subagent's hook set only.
   Parent and child registries do not interleave.
 
@@ -188,7 +193,7 @@ documented expectations:
 - Hook modules never import workflow primitives (`start`, `resumeHook`,
   `createHook`, `getWritable`).
 - Hook return shapes have no `state` field — durable state goes through
-  `ctx.ash`.
+  `ctx`.
 - Subagent hooks never read parent ALS context.
 
 ## Related Pages

package/dist/docs/internals/mechanical-invariants.md

@@ -68,10 +68,10 @@ flags new `@workflow/*` imports from channel, harness, and hook code.
 ### Hooks Use The Single State Channel
 
 Authored hook modules (`agent/hooks/**`) must read and write durable state
-through `ctx.ash` (the unified `ContextAccessor`). The hooks surface
-introduces no parallel state-patch channel — lifecycle return shapes
-expose only `modelContext` (a one-shot per-call ephemeral message list),
-and subagent hooks never read parent ALS context.
+through `ctx` (the unified context). The hooks surface introduces no
+parallel state-patch channel — lifecycle return shapes expose only
+`modelContext` (a one-shot per-call ephemeral message list), and subagent
+hooks never read parent ALS context.
 
 Enforcement: rule 27 in `scripts/guard-agents-rules.mjs` fails if a
 `state:` (or `readonly state:`, `state?:`) field is declared on any

package/dist/docs/internals/testing.md

@@ -62,7 +62,7 @@ Ad-hoc tmp directories with `package.json` + `agent/` scaffolding.
 
 - Unit tier: `unit-guard.ts` throws on disk writes, subprocesses, `process.chdir`, real fetch. If you hit a guard throw, move the test to a higher tier.
 - Never mutate the process-default `RuntimeSession` — let `createTestRuntime().run(fn)` scope it. Do not call `installBundledCompiledArtifacts` / `resetBundledCompiledArtifacts` / `clearProcessDefaultRuntimeSession` directly.
-- Use `runAsSession({}, ...)` when the test needs `getSession()` / `getSandbox()` / `getSkill()` to resolve. Use `run(...)` when only compiled artifacts + bundle cache need scoping.
+- Use `runAsSession({}, ...)` when the test needs `ctx.session` / `ctx.getSandbox()` / `ctx.getSkill()` to resolve (the internal `getSession()`, `getSandbox()`, `getSkill()` free functions still work but are not public API). Use `run(...)` when only compiled artifacts + bundle cache need scoping.
 - Cleanup is automatic for `mockSkill`, `useScenarioApp`, and `useTemporaryAppRoots`.
 - Do not commit new fixtures under `test/fixtures/` — CI guard will fail. Use descriptors in `src/internal/testing/scenario-apps/`.
 - Prefer `vi.stubEnv` over direct `process.env` mutation.

package/dist/docs/public/README.md

@@ -16,25 +16,25 @@ Important naming note:
 Read in this order:
 
 1. [Getting Started](./getting-started.md)
-2. [Project Layout](./project-layout.md)
+2. [Project Layout](./advanced/project-layout.md)
 3. [`agent.ts`](./agent-ts.md)
-4. [TypeScript API](./typescript-api.md)
-5. [Context Control](./context-control.md)
+4. [TypeScript API](./advanced/typescript-api.md)
+5. [Context Control](./advanced/context-control.md)
 6. [Skills](./skills.md)
 7. [Tools](./tools.md)
 8. [Connections](./connections.md)
-9. [Workspace](./workspace.md)
+9. [Workspace](./advanced/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)
+13. [Session Context](./advanced/session-context.md)
+14. [Sessions And Streaming](./advanced/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)
+17. [Evals](./advanced/evals.md)
+18. [Auth And Route Protection](./advanced/auth-and-route-protection.md)
+19. [Vercel Deployment](./advanced/vercel-deployment.md)
+20. [CLI, Build, And Debugging](./advanced/cli-build-and-debugging.md)
 
 ## The Public Mental Model
 
@@ -60,7 +60,7 @@ Ash then gives you:
 - a reconnectable session stream
 - durable session state across turns
 - a per-agent sandbox with a shared runtime workspace
-- typed runtime helpers such as `getSession()`, `getSandbox()`, and `getSkill()`
+- typed runtime helpers accessed through `ctx` (`ctx.session`, `ctx.getSandbox()`, `ctx.getSkill()`)
 
 ## The Runtime Shape
 

package/dist/docs/public/{auth-and-route-protection.md → advanced/auth-and-route-protection.md}

@@ -1,6 +1,7 @@
 ---
 title: "Auth And Route Protection"
 description: "Protect agent routes with HTTP Basic, JWT, OIDC, and Vercel OIDC."
+url: /auth-and-route-protection
 ---
 
 Ash protects its own HTTP routes through the channel layer.
@@ -163,7 +164,7 @@ configured, and their `environment` matches `VERCEL_TARGET_ENV` or `VERCEL_ENV`
 those user tokens, `external_sub` becomes the session subject, `external_iss` becomes the session
 issuer when present, and `connector_id` is used as the issuer fallback before the Vercel OIDC issuer.
 String OIDC profile claims such as `name`, `picture`, and `email` are exposed in
-`getSession().auth.current.attributes`.
+`ctx.session.auth.current.attributes`.
 
 ### `none`
 
@@ -195,7 +196,7 @@ re-materializes them from the authored channel definition when it needs the live
 
 ## What Auth Reaches Authored Code
 
-Inside runtime code, `getSession().auth` gives you the caller snapshot.
+Inside runtime code, `ctx.session.auth` gives you the caller snapshot.
 
 Important behavior:
 
@@ -207,8 +208,8 @@ Important behavior:
   accepts with a `SessionAuthContext` or returns `401`
 
 Auth on follow-up messages (`deliver()`) is honored by the workflow runtime. When a different
-user sends a follow-up to the same session, `session.auth.current` reflects the new caller on
-that turn while `session.auth.initiator` stays the same.
+user sends a follow-up to the same session, `ctx.session.auth.current` reflects the new caller on
+that turn while `ctx.session.auth.initiator` stays the same.
 
 ## What Ash Does Not Do
 

package/dist/docs/public/{cli-build-and-debugging.md → advanced/cli-build-and-debugging.md}

@@ -1,6 +1,7 @@
 ---
 title: "CLI, Build, And Debugging"
 description: "CLI commands: dev, build, info, eval. Debugging techniques."
+url: /cli-build-and-debugging
 ---
 
 Ash's CLI gives you the normal day-to-day workflow for authoring, inspecting, and shipping an app.
@@ -77,7 +78,7 @@ When something is wrong:
 
 - `schedules/` are root-only today
 - `agent.ts` no longer owns inbound auth or network policy; those live on the HTTP channel layer
-- runtime helpers such as `getSession()` do not work at module top level
+- runtime helpers on `ctx` (like `ctx.session`) do not work at module top level
 - skill guidance belongs in `skills/`, not in tool descriptions
 
 ## What To Read Next

package/dist/docs/public/{context-control.md → advanced/context-control.md}

@@ -1,6 +1,7 @@
 ---
 title: "Context Control"
 description: "Author always-on instructions with instructions.md or instructions.ts."
+url: /context-control
 ---
 
 Ash gives you a few different levers for controlling what the model sees and when it sees it.

package/dist/docs/public/{evals.md → advanced/evals.md}

@@ -1,6 +1,7 @@
 ---
 title: "Evals"
 description: "Define eval suites with test cases, scoring rubrics, and automated runs."
+url: /evals
 ---
 
 Evals let you define repeatable checks for an Ash agent and run them with the `ash eval` CLI

package/dist/docs/public/{faqs.md → advanced/faqs.md}

@@ -1,6 +1,7 @@
 ---
 title: "FAQs"
 description: "Frequently asked questions about Ash."
+url: /faqs
 ---
 
 # FAQs
@@ -56,12 +57,11 @@ the framework's mechanical invariants.
 
 If you want session data from your own code, there are two supported surfaces:
 
-- **Tools** can read the current session's metadata (sessionId, turn, auth,
-  parent lineage) via `getSession()` from `experimental-ash/context`. This is
+- **Tools** can read the current session's metadata (id, turn, auth,
+  parent lineage) via `ctx.session` from the optional `ctx` parameter on `execute`. This is
   read-only.
-- **Durable context keys + `ContextProvider`** are the supported pattern for
-  reading or writing session-scoped durable state from authored code — see
-  [Session Context](./session-context.md).
+- **`defineState`** is the supported pattern for reading or writing session-scoped durable state
+  from authored code — see [Session Context](./session-context.md).
 
 For the wire-level session lifecycle (creating sessions, streaming events,
 reconnecting by event index) see [Sessions And Streaming](./runs-and-streaming.md).

package/dist/docs/public/{hooks.md → advanced/hooks.md}

@@ -1,6 +1,7 @@
 ---
 title: "Hooks"
 description: "Subscribe to lifecycle moments and runtime stream events from agent/hooks/."
+url: /hooks
 ---
 
 Hooks are Ash's authored extension points for the per-turn lifecycle and
@@ -20,7 +21,7 @@ import { defineHook } from "experimental-ash/hooks";
 export default defineHook({
   events: {
     async "session.started"(_event, ctx) {
-      console.info("session started", { sessionId: ctx.session.sessionId });
+      console.info("session started", { sessionId: ctx.session.id });
     },
     async "message.completed"(event) {
       console.info("model finished", { length: event.data.message?.length ?? 0 });
@@ -33,8 +34,7 @@ The slug is the path-relative basename: `agent/hooks/audit.ts` → `"audit"`,
 `agent/hooks/auth/load-profile.ts` → `"auth/load-profile"`.
 
 `defineHook`, `HookDefinition`, and `HookContext` live on
-`experimental-ash/hooks`. Runtime context helpers (`getSession`,
-`getContext`, …) live on `experimental-ash/context`.
+`experimental-ash/hooks`. The `defineState` helper lives on `experimental-ash/context`.
 
 ## Shape
 
@@ -55,16 +55,10 @@ Every handler receives the same `HookContext`:
 interface HookContext {
   readonly agent: { readonly name: string; readonly nodeId?: string };
   readonly channel: { readonly kind?: string; readonly continuationToken?: string };
-  readonly session: { readonly sessionId: string };
-  readonly ash: ContextAccessor;
+  readonly session: { readonly id: string };
 }
 ```
 
-`ctx.ash` is the same `ContextAccessor` tools, providers, and channels use.
-Hooks read and write durable state through `ctx.ash.set(...)` /
-`ctx.ash.get(...)`. The hooks surface deliberately introduces no parallel
-state-patch channel — one `AshContext`, one set of keys.
-
 ### Narrowing tool results
 
 `toolResultFrom` narrows an `action.result` event to a specific authored
@@ -108,11 +102,13 @@ Lifecycle hooks share one signature:
 
 ```ts
 type LifecycleHook = (
-  input: { session: { sessionId: string }; turn: { sequence: number; turnId: string } },
   ctx: HookContext,
 ) => void | { modelContext?: readonly ModelMessage[]; skills?: readonly NamedSkillDefinition[] } | Promise<…>;
 ```
 
+Session and turn metadata are available on `ctx.session`. For example,
+`ctx.session.turn.sequence` gives the current turn sequence number.
+
 `lifecycle.session` runs **once per durable session**, before the first
 model turn. `lifecycle.turn` runs **once per fresh delivery** — tool-loop
 continuations and HITL resumes do not re-fire it.
@@ -130,24 +126,24 @@ lifecycle hook messages.
 
 ```ts
 // agent/hooks/load-profile.ts
-import { ContextKey } from "experimental-ash/context";
+import { defineState } from "experimental-ash/context";
 import { defineHook } from "experimental-ash/hooks";
 import { fetchGithubProfile, type GithubProfile } from "../lib/github";
 
-const GithubProfileKey = new ContextKey<GithubProfile>("myapp.githubProfile");
+const githubProfile = defineState<GithubProfile | null>("myapp.githubProfile", () => null);
 
 export default defineHook({
   lifecycle: {
-    async session(_input, ctx) {
-      const profile = await fetchGithubProfile(ctx.session.sessionId);
-      ctx.ash.set(GithubProfileKey, profile);
+    async session(ctx) {
+      const profile = await fetchGithubProfile(ctx.session.id);
+      githubProfile.update(() => profile);
     },
   },
 });
 ```
 
 The profile is now visible to every tool, provider, and subsequent hook
-through `ctx.ash.get(GithubProfileKey)`.
+through `githubProfile.get()`.
 
 ### Inject ephemeral system text
 
@@ -158,7 +154,7 @@ import { fetchActiveIncident } from "../lib/linear";
 
 export default defineHook({
   lifecycle: {
-    async turn() {
+    async turn(ctx) {
       const incident = await fetchActiveIncident();
       if (incident === null) return;
 
@@ -186,7 +182,7 @@ import { defineHook } from "experimental-ash/hooks";
 
 export default defineHook({
   lifecycle: {
-    async session() {
+    async session(ctx) {
       return {
         skills: [
           {
@@ -216,12 +212,12 @@ import { defineHook } from "experimental-ash/hooks";
 
 export default defineHook({
   lifecycle: {
-    async session(_input, ctx) {
+    async session(ctx) {
       return {
         modelContext: [
           {
             role: "system",
-            content: `Greet the user by name (${await lookupName(ctx.session.sessionId)}).`,
+            content: `Greet the user by name (${await lookupName(ctx.session.id)}).`,
           },
         ],
       };
@@ -247,7 +243,7 @@ import { postToHoneycomb } from "../lib/honeycomb";
 export default defineHook({
   events: {
     async "session.started"(_event, ctx) {
-      await postToHoneycomb({ event: "session.started", sessionId: ctx.session.sessionId });
+      await postToHoneycomb({ event: "session.started", sessionId: ctx.session.id });
     },
     async "message.completed"(event) {
       await postToHoneycomb({ event: "message.completed", payload: event.data });
@@ -282,7 +278,7 @@ in `try`/`catch` — Ash treats a thrown hook as a real failure.
 Subagents may carry their own `agent/hooks/` directory. Subagent hooks
 fire only inside the subagent scope; parent-agent hooks do not fire for
 subagent turns, and subagent hooks see only the subagent's own
-`ctx.ash`.
+context.
 
 ## When to use a hook vs a tool vs a provider
 

package/dist/docs/public/{instrumentation.md → advanced/instrumentation.md}

@@ -1,6 +1,7 @@
 ---
 title: "instrumentation.ts"
 description: "Configure OpenTelemetry exporters and AI SDK span behavior for your agent."
+url: /instrumentation
 ---
 
 `instrumentation.ts` is the single place to configure OpenTelemetry for an Ash agent. It controls

package/dist/docs/public/advanced/meta.json

@@ -0,0 +1,19 @@
+{
+  "title": "Advanced",
+  "pages": [
+    "project-layout",
+    "context-control",
+    "hooks",
+    "auth-and-route-protection",
+    "vercel-deployment",
+    "runs-and-streaming",
+    "session-context",
+    "workspace",
+    "evals",
+    "instrumentation",
+    "cli-build-and-debugging",
+    "typescript-api",
+    "...",
+    "faqs"
+  ]
+}

package/dist/docs/public/{project-layout.md → advanced/project-layout.md}

@@ -1,6 +1,7 @@
 ---
 title: "Project Layout"
 description: "Directory structure and filesystem conventions."
+url: /project-layout
 ---
 
 Ash supports two layouts:

package/dist/docs/public/{runs-and-streaming.md → advanced/runs-and-streaming.md}

@@ -1,6 +1,7 @@
 ---
 title: "Sessions And Streaming"
 description: "The HTTP API, NDJSON event stream, and session lifecycle."
+url: /runs-and-streaming
 ---
 
 Ash is durable and session-based by default.