ts-procedures 7.1.2 → 7.3.0

package/docs/superpowers/plans/2026-05-07-astro-adapter.md

@@ -0,0 +1,1396 @@
+# Astro Adapter Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Ship a new `ts-procedures/astro` subpath that lets a downstream developer drop one or more pre-built Hono apps (from `HonoAPIAppBuilder`, `HonoRPCAppBuilder`, `HonoStreamAppBuilder`) into a single catch-all Astro endpoint file (`src/pages/api/[...rest].ts`) and have every procedure call route correctly with full access to Astro's per-request data inside factory-context closures.
+
+**Architecture:** Web-fetch delegator — accept already-built Hono apps via `app.fetch(request)`. The adapter (a) optionally strips a configured `pathPrefix` from the incoming `Request` URL, (b) stashes Astro's `APIContext` in a `WeakMap` keyed by the rewritten Request, (c) dispatches across the registered apps with first-non-404-wins, (d) returns the response. A second exported helper, `getAstroContext(c)`, lets factory closures read the stashed `APIContext` from the Hono `Context` (via `c.req.raw`). No Hono builder is modified; Astro is types-only and listed under `optionalDependencies`.
+
+**Tech Stack:** TypeScript (ESM, NodeNext), vitest, Hono (already a dev/optional dep), Astro 5 (new `optionalDependencies` + `devDependencies` entry, `import type` only).
+
+**Source spec:** `docs/superpowers/specs/2026-05-07-astro-adapter-design.md`
+
+---
+
+## File Structure
+
+**New files:**
+- `src/implementations/http/astro/astro-context.ts` — module-private `WeakMap<Request, APIContext>`, internal `setAstroContext(req, ctx)`, public `getAstroContext(c)` reading via `c.req.raw`. Throws `Error` when the request is not in scope.
+- `src/implementations/http/astro/rewrite-request.ts` — pure function `stripPrefix(request, prefix)`: returns the original request when no prefix, the rewritten request when prefix matches, or `null` (404 short-circuit) when it doesn't match.
+- `src/implementations/http/astro/create-handler.ts` — `createAstroHandler({ apps, pathPrefix })` returning the per-method `APIRoute` map. Internal multi-app dispatch with first-non-404 short-circuit.
+- `src/implementations/http/astro/index.ts` — public barrel: re-exports `createAstroHandler`, `getAstroContext`, and the `AstroAdapterConfig` type.
+- `src/implementations/http/astro/index.test.ts` — vitest suite with all unit + integration tests in one file (matches the convention used by `hono-api/index.test.ts`).
+- `src/implementations/http/astro/README.md` — usage docs, prefix semantics, examples.
+- `docs/astro-adapter.md` — end-to-end walkthrough.
+- `agent_config/claude-code/skills/ts-procedures-scaffold/templates/astro-catchall.ts` — scaffold template.
+
+**Modified files:**
+- `package.json` — add `./astro` to `exports`, add `astro` to `optionalDependencies` and `devDependencies`.
+- `agent_config/claude-code/skills/ts-procedures/api-reference.md` — add Astro adapter section.
+- `agent_config/claude-code/skills/ts-procedures/patterns.md` — add Astro pattern.
+- `agent_config/copilot/copilot-instructions.md` and `agent_config/cursor/cursorrules` — add the same Astro pattern inside `<!-- BEGIN/END ts-procedures -->` markers (these two files are kept identical per CLAUDE.md).
+
+---
+
+## Task 1: Module skeleton + package.json wiring
+
+**Files:**
+- Create: `src/implementations/http/astro/index.ts`
+- Create: `src/implementations/http/astro/astro-context.ts`
+- Create: `src/implementations/http/astro/rewrite-request.ts`
+- Create: `src/implementations/http/astro/create-handler.ts`
+- Create: `src/implementations/http/astro/index.test.ts`
+- Modify: `package.json`
+
+- [ ] **Step 1: Install Astro as a devDependency**
+
+Run from the project root:
+
+```bash
+npm install --save-dev --save-optional astro@^5.0.0
+```
+
+Expected: `astro` appears in both `devDependencies` and `optionalDependencies`. (npm will write `optionalDependencies` because of `--save-optional`; verify it also lands in `devDependencies` — if not, manually add it to `devDependencies` so types resolve at build time.)
+
+- [ ] **Step 2: Verify package.json now has astro in both sections**
+
+Open `package.json` and confirm both:
+
+```json
+"optionalDependencies": {
+  "ajsc": "7.2.0",
+  "astro": "^5.0.0",
+  "express": "^5.2.1",
+  "hono": "^4.7.4"
+},
+"devDependencies": {
+  "...": "...",
+  "astro": "^5.0.0"
+}
+```
+
+If `astro` is missing from `devDependencies`, add it manually with the same version range.
+
+- [ ] **Step 3: Add the `./astro` subpath export**
+
+In `package.json`, add to the `exports` object (alphabetical placement — between `.` and `./client` is fine):
+
+```json
+"./astro": {
+  "types": "./build/implementations/http/astro/index.d.ts",
+  "import": "./build/implementations/http/astro/index.js"
+}
+```
+
+- [ ] **Step 4: Create empty source files**
+
+Create the following with minimal placeholder content so TypeScript resolves them:
+
+```ts
+// src/implementations/http/astro/astro-context.ts
+export {}
+```
+
+```ts
+// src/implementations/http/astro/rewrite-request.ts
+export {}
+```
+
+```ts
+// src/implementations/http/astro/create-handler.ts
+export {}
+```
+
+```ts
+// src/implementations/http/astro/index.ts
+export {}
+```
+
+```ts
+// src/implementations/http/astro/index.test.ts
+import { describe } from 'vitest'
+describe.skip('astro adapter — placeholder', () => {})
+```
+
+- [ ] **Step 5: Run the build and tests to confirm the skeleton compiles**
+
+Run:
+
+```bash
+npm run build && npm test -- src/implementations/http/astro
+```
+
+Expected: build succeeds, the placeholder describe is skipped, test run passes with 0 failures.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add package.json package-lock.json src/implementations/http/astro/
+git commit -m "feat(astro): scaffold ts-procedures/astro subpath"
+```
+
+---
+
+## Task 2: stripPrefix helper
+
+**Files:**
+- Modify: `src/implementations/http/astro/rewrite-request.ts`
+- Modify: `src/implementations/http/astro/index.test.ts`
+
+- [ ] **Step 1: Write the failing tests**
+
+Replace the contents of `src/implementations/http/astro/index.test.ts` with:
+
+```ts
+import { describe, expect, test } from 'vitest'
+import { stripPrefix } from './rewrite-request.js'
+
+describe('stripPrefix', () => {
+  test('returns original request when prefix is undefined', () => {
+    const req = new Request('https://example.test/api/users/1')
+    expect(stripPrefix(req, undefined)).toBe(req)
+  })
+
+  test('returns original request when normalized prefix is "/"', () => {
+    const req = new Request('https://example.test/users/1')
+    expect(stripPrefix(req, '/')).toBe(req)
+    expect(stripPrefix(req, '')).toBe(req)
+  })
+
+  test('strips a leading-slash prefix', () => {
+    const req = new Request('https://example.test/api/users/1')
+    const out = stripPrefix(req, '/api')!
+    expect(new URL(out.url).pathname).toBe('/users/1')
+  })
+
+  test('strips a no-slash prefix (normalized)', () => {
+    const req = new Request('https://example.test/api/users/1')
+    const out = stripPrefix(req, 'api')!
+    expect(new URL(out.url).pathname).toBe('/users/1')
+  })
+
+  test('strips a trailing-slash prefix (normalized)', () => {
+    const req = new Request('https://example.test/api/users/1')
+    const out = stripPrefix(req, '/api/')!
+    expect(new URL(out.url).pathname).toBe('/users/1')
+  })
+
+  test('exact-match prefix becomes "/"', () => {
+    const req = new Request('https://example.test/api')
+    const out = stripPrefix(req, '/api')!
+    expect(new URL(out.url).pathname).toBe('/')
+  })
+
+  test('returns null when path does not start with prefix (404 short-circuit)', () => {
+    const req = new Request('https://example.test/other/users/1')
+    expect(stripPrefix(req, '/api')).toBeNull()
+  })
+
+  test('returns null when path shares prefix characters but not a segment boundary', () => {
+    // /apikey starts with /api but is not under /api — must NOT rewrite.
+    expect(stripPrefix(new Request('https://example.test/apikey/secret'), '/api')).toBeNull()
+    expect(stripPrefix(new Request('https://example.test/api-v2/x'), '/api')).toBeNull()
+    expect(stripPrefix(new Request('https://example.test/api_internal'), '/api')).toBeNull()
+  })
+
+  test('preserves the query string through the rewrite', () => {
+    const req = new Request('https://example.test/api/users?limit=10&tag=a&tag=b')
+    const out = stripPrefix(req, '/api')!
+    const url = new URL(out.url)
+    expect(url.pathname).toBe('/users')
+    expect(url.search).toBe('?limit=10&tag=a&tag=b')
+  })
+
+  test('preserves the request method', () => {
+    const req = new Request('https://example.test/api/users', { method: 'POST' })
+    const out = stripPrefix(req, '/api')!
+    expect(out.method).toBe('POST')
+  })
+
+  test('preserves headers', () => {
+    const req = new Request('https://example.test/api/users', {
+      method: 'POST',
+      headers: { 'X-Trace-Id': 'abc-123', 'Content-Type': 'application/json' },
+    })
+    const out = stripPrefix(req, '/api')!
+    expect(out.headers.get('X-Trace-Id')).toBe('abc-123')
+    expect(out.headers.get('Content-Type')).toBe('application/json')
+  })
+})
+```
+
+- [ ] **Step 2: Run the tests to verify they fail**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected: all `stripPrefix` tests fail with `stripPrefix is not a function` or import error.
+
+- [ ] **Step 3: Implement `stripPrefix`**
+
+Replace `src/implementations/http/astro/rewrite-request.ts` with:
+
+```ts
+/**
+ * Returns a Request with `prefix` stripped from the URL pathname.
+ *
+ * - `prefix` undefined or normalizing to '/' → returns the original request unchanged.
+ * - Path does not start with the normalized prefix at a segment boundary → returns `null`
+ *   (caller short-circuits to 404). E.g. with prefix '/api', the request '/apikey'
+ *   returns null because 'key' is not preceded by a path separator.
+ * - Otherwise → returns a new Request with the rewritten URL and method/headers/body/signal/duplex
+ *   preserved via `new Request(url, init)`.
+ *
+ * Normalization: leading and trailing slashes are optional. '/api', 'api', and '/api/' are equivalent.
+ */
+export function stripPrefix(request: Request, prefix: string | undefined): Request | null {
+  if (prefix === undefined) return request
+  const normalized = '/' + prefix.replace(/^\/|\/$/g, '')
+  if (normalized === '/') return request
+
+  const url = new URL(request.url)
+  if (!url.pathname.startsWith(normalized)) return null
+
+  // Segment-boundary guard: the character right after the prefix in the path
+  // MUST be either undefined (exact match) or '/' (real segment boundary).
+  // Without this, '/apikey' would falsely match prefix '/api'.
+  const nextChar = url.pathname[normalized.length]
+  if (nextChar !== undefined && nextChar !== '/') return null
+
+  const rest = url.pathname.slice(normalized.length)
+  url.pathname = rest === '' ? '/' : rest
+
+  return new Request(url, request)
+}
+```
+
+- [ ] **Step 4: Run the tests to verify they pass**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected: all 11 `stripPrefix` tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/implementations/http/astro/rewrite-request.ts src/implementations/http/astro/index.test.ts
+git commit -m "feat(astro): add stripPrefix URL-rewrite helper"
+```
+
+---
+
+## Task 3: astro-context (WeakMap + getAstroContext)
+
+**Files:**
+- Modify: `src/implementations/http/astro/astro-context.ts`
+- Modify: `src/implementations/http/astro/index.test.ts`
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `src/implementations/http/astro/index.test.ts` (keep the existing `stripPrefix` block above):
+
+```ts
+import { Hono } from 'hono'
+import { setAstroContext, getAstroContext } from './astro-context.js'
+
+// Minimal stand-in for Astro's APIContext for unit tests.
+function fakeApiContext(overrides: Record<string, unknown> = {}) {
+  return {
+    locals: { user: { id: 'u-1' } },
+    cookies: {},
+    params: {},
+    request: new Request('https://example.test/'),
+    url: new URL('https://example.test/'),
+    redirect: () => new Response(null, { status: 302 }),
+    ...overrides,
+  } as unknown as import('astro').APIContext
+}
+
+describe('astro-context', () => {
+  test('getAstroContext returns the APIContext stashed for the request seen by Hono', async () => {
+    const req = new Request('https://example.test/probe')
+    const apiContext = fakeApiContext()
+    setAstroContext(req, apiContext)
+
+    const app = new Hono()
+    let observed: import('astro').APIContext | null = null
+    app.get('/probe', (c) => {
+      observed = getAstroContext(c)
+      return c.json({ ok: true })
+    })
+
+    const res = await app.fetch(req)
+    expect(res.status).toBe(200)
+    expect(observed).toBe(apiContext)
+  })
+
+  test('getAstroContext throws when called outside an Astro request scope', async () => {
+    const app = new Hono()
+    let captured: unknown = null
+    app.get('/probe', (c) => {
+      try {
+        getAstroContext(c)
+      } catch (err) {
+        captured = err
+      }
+      return c.json({ ok: true })
+    })
+
+    await app.fetch(new Request('https://example.test/probe'))
+    expect(captured).toBeInstanceOf(Error)
+    expect((captured as Error).message).toMatch(/outside an Astro request scope/i)
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they fail**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected: the two `astro-context` tests fail (`setAstroContext` / `getAstroContext` not exported).
+
+- [ ] **Step 3: Implement `astro-context.ts`**
+
+Replace `src/implementations/http/astro/astro-context.ts` with:
+
+```ts
+import type { APIContext } from 'astro'
+import type { Context as HonoContext } from 'hono'
+
+const astroContextMap = new WeakMap<Request, APIContext>()
+
+/**
+ * Internal — stash the Astro APIContext for the Request that Hono will receive.
+ *
+ * The key MUST be the post-rewrite Request (the one passed to `app.fetch`),
+ * because that is what Hono exposes via `c.req.raw` and what `getAstroContext`
+ * reads back. When no `pathPrefix` rewrite happens, this is the same Request
+ * that Astro originally invoked the adapter with.
+ */
+export function setAstroContext(request: Request, apiContext: APIContext): void {
+  astroContextMap.set(request, apiContext)
+}
+
+/**
+ * Reads Astro's APIContext from inside a Hono factory-context closure.
+ *
+ * Throws when the request is not in scope — typically because the Hono app
+ * is being served outside the Astro adapter (e.g., bound to a Node listener
+ * or via a different adapter) and the closure was invoked there.
+ */
+export function getAstroContext(c: HonoContext): APIContext {
+  const ctx = astroContextMap.get(c.req.raw)
+  if (!ctx) {
+    throw new Error(
+      'getAstroContext was called outside an Astro request scope. ' +
+        'Ensure this Hono app is being served via createAstroHandler when this closure runs.'
+    )
+  }
+  return ctx
+}
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected: all `stripPrefix` and `astro-context` tests pass.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/implementations/http/astro/astro-context.ts src/implementations/http/astro/index.test.ts
+git commit -m "feat(astro): add WeakMap-backed getAstroContext bridge"
+```
+
+---
+
+## Task 4: createAstroHandler — single app, no prefix
+
+**Files:**
+- Modify: `src/implementations/http/astro/create-handler.ts`
+- Modify: `src/implementations/http/astro/index.ts`
+- Modify: `src/implementations/http/astro/index.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/implementations/http/astro/index.test.ts`:
+
+```ts
+import { Type } from 'typebox'
+import { Procedures } from '../../../index.js'
+import { HonoAPIAppBuilder } from '../hono-api/index.js'
+import type { APIConfig } from '../../types.js'
+import { createAstroHandler } from './create-handler.js'
+
+function buildSimpleUserApi() {
+  const API = Procedures<{ db: Map<string, { id: string; name: string }> }, APIConfig>()
+  API.Create(
+    'GetUser',
+    {
+      path: '/users/:id',
+      method: 'get',
+      schema: {
+        input: { pathParams: Type.Object({ id: Type.String() }) },
+        returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+      },
+    },
+    async (ctx, { pathParams }) => {
+      const u = ctx.db.get(pathParams.id)
+      if (!u) throw new Error('not found')
+      return u
+    }
+  )
+  const db = new Map([['1', { id: '1', name: 'Ada' }]])
+  return new HonoAPIAppBuilder().register(API, () => ({ db })).build()
+}
+
+describe('createAstroHandler — single app, no prefix', () => {
+  test('exports ALL plus the seven HTTP method handlers', () => {
+    const handlers = createAstroHandler({ apps: buildSimpleUserApi() })
+    expect(typeof handlers.ALL).toBe('function')
+    for (const m of ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'] as const) {
+      expect(typeof handlers[m]).toBe('function')
+    }
+  })
+
+  test('GET roundtrips through the underlying Hono app', async () => {
+    const { ALL } = createAstroHandler({ apps: buildSimpleUserApi() })
+    const apiContext = fakeApiContext({
+      request: new Request('https://example.test/users/1'),
+      url: new URL('https://example.test/users/1'),
+    })
+    const res = await (ALL as any)(apiContext)
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ id: '1', name: 'Ada' })
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected: the two `createAstroHandler` tests fail because `createAstroHandler` is not exported.
+
+- [ ] **Step 3: Implement minimal `createAstroHandler`**
+
+Replace `src/implementations/http/astro/create-handler.ts` with:
+
+```ts
+import type { Hono } from 'hono'
+import type { APIRoute } from 'astro'
+import { setAstroContext } from './astro-context.js'
+import { stripPrefix } from './rewrite-request.js'
+
+export type AstroAdapterConfig = {
+  /** One or more built Hono apps. Order matters in first-match dispatch. */
+  apps: Hono | Hono[]
+  /**
+   * Path prefix matching the Astro catch-all mount point.
+   * For src/pages/api/[...rest].ts use '/api'. The adapter strips this
+   * before delegating, so Hono routes do NOT need to repeat the prefix.
+   *
+   * Normalization: leading and trailing slashes are optional; '/api',
+   * 'api', and '/api/' are equivalent. Undefined or '/' means no rewrite.
+   */
+  pathPrefix?: string
+}
+
+export type AstroHandlers = {
+  ALL: APIRoute
+  GET: APIRoute
+  POST: APIRoute
+  PUT: APIRoute
+  PATCH: APIRoute
+  DELETE: APIRoute
+  HEAD: APIRoute
+  OPTIONS: APIRoute
+}
+
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'] as const
+
+export function createAstroHandler(config: AstroAdapterConfig): AstroHandlers {
+  const apps = Array.isArray(config.apps) ? config.apps : [config.apps]
+
+  const ALL: APIRoute = async (apiContext) => {
+    const rewritten = stripPrefix(apiContext.request, config.pathPrefix)
+    if (rewritten === null) {
+      return new Response(null, { status: 404 })
+    }
+    setAstroContext(rewritten, apiContext)
+
+    for (const app of apps) {
+      const res = await app.fetch(rewritten)
+      if (res.status !== 404) return res
+    }
+    return new Response(null, { status: 404 })
+  }
+
+  const handlers = { ALL } as AstroHandlers
+  for (const method of HTTP_METHODS) {
+    handlers[method] = ALL
+  }
+  return handlers
+}
+```
+
+- [ ] **Step 4: Wire the public barrel**
+
+Replace `src/implementations/http/astro/index.ts` with:
+
+```ts
+export { createAstroHandler } from './create-handler.js'
+export type { AstroAdapterConfig, AstroHandlers } from './create-handler.js'
+export { getAstroContext } from './astro-context.js'
+```
+
+- [ ] **Step 5: Run tests to verify they pass**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected: all tests up to and including `createAstroHandler — single app, no prefix` pass.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/implementations/http/astro/create-handler.ts src/implementations/http/astro/index.ts src/implementations/http/astro/index.test.ts
+git commit -m "feat(astro): add createAstroHandler with single-app dispatch"
+```
+
+---
+
+## Task 5: pathPrefix support + getAstroContext integration
+
+**Files:**
+- Modify: `src/implementations/http/astro/index.test.ts`
+
+`createAstroHandler` already calls `stripPrefix` and `setAstroContext` — this task adds the integration tests that prove they work end-to-end. No production changes if all goes well.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `src/implementations/http/astro/index.test.ts`:
+
+```ts
+describe('createAstroHandler — pathPrefix + getAstroContext', () => {
+  test('strips pathPrefix before delegating', async () => {
+    // Underlying Hono app has no /api in its routes.
+    const app = buildSimpleUserApi()
+    const { ALL } = createAstroHandler({ apps: app, pathPrefix: '/api' })
+    const apiContext = fakeApiContext({
+      request: new Request('https://example.test/api/users/1'),
+      url: new URL('https://example.test/api/users/1'),
+    })
+    const res = await (ALL as any)(apiContext)
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ id: '1', name: 'Ada' })
+  })
+
+  test('returns 404 directly when request path is outside the prefix', async () => {
+    const { ALL } = createAstroHandler({ apps: buildSimpleUserApi(), pathPrefix: '/api' })
+    const apiContext = fakeApiContext({
+      request: new Request('https://example.test/somewhere-else'),
+      url: new URL('https://example.test/somewhere-else'),
+    })
+    const res = await (ALL as any)(apiContext)
+    expect(res.status).toBe(404)
+  })
+
+  test('factory closure can read APIContext via getAstroContext', async () => {
+    const API = Procedures<{ user: { id: string } | null }, APIConfig>()
+    API.Create(
+      'WhoAmI',
+      { path: '/whoami', method: 'get', schema: { returnType: Type.Object({ userId: Type.Union([Type.String(), Type.Null()]) }) } },
+      async (ctx) => ({ userId: ctx.user?.id ?? null })
+    )
+
+    const app = new HonoAPIAppBuilder()
+      .register(API, (c) => {
+        const astro = getAstroContext(c)
+        return { user: (astro.locals as { user?: { id: string } }).user ?? null }
+      })
+      .build()
+
+    const { ALL } = createAstroHandler({ apps: app })
+    const apiContext = fakeApiContext({
+      locals: { user: { id: 'u-42' } },
+      request: new Request('https://example.test/whoami'),
+      url: new URL('https://example.test/whoami'),
+    })
+    const res = await (ALL as any)(apiContext)
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ userId: 'u-42' })
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they pass without changes to production code**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected: all three new tests pass. (Production code from Task 4 already supports both behaviors — these tests just lock them in.)
+
+If any test fails, fix the production code in `create-handler.ts` until they pass before continuing.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/implementations/http/astro/index.test.ts
+git commit -m "test(astro): cover pathPrefix and getAstroContext end-to-end"
+```
+
+---
+
+## Task 6: Multi-app dispatch (404 fallthrough + non-404 short-circuit)
+
+**Files:**
+- Modify: `src/implementations/http/astro/index.test.ts`
+
+The multi-app loop already exists in `create-handler.ts`. This task adds tests that cover both branches.
+
+- [ ] **Step 1: Write the failing tests**
+
+Append to `src/implementations/http/astro/index.test.ts`:
+
+```ts
+import { HonoRPCAppBuilder } from '../hono-rpc/index.js'
+
+describe('createAstroHandler — multi-app dispatch', () => {
+  function makeAppWithRoute(path: string, status: number, body: unknown) {
+    const app = new Hono()
+    app.all(path, (c) => c.json(body, status as any))
+    return app
+  }
+
+  test('first 404 falls through to the second app', async () => {
+    const a = makeAppWithRoute('/only-a', 200, { from: 'a' })
+    const b = makeAppWithRoute('/only-b', 200, { from: 'b' })
+    const { ALL } = createAstroHandler({ apps: [a, b] })
+
+    const apiContext = fakeApiContext({
+      request: new Request('https://example.test/only-b'),
+      url: new URL('https://example.test/only-b'),
+    })
+    const res = await (ALL as any)(apiContext)
+    expect(res.status).toBe(200)
+    expect(await res.json()).toEqual({ from: 'b' })
+  })
+
+  test('a non-404 response from the first app short-circuits dispatch', async () => {
+    const a = makeAppWithRoute('/error', 500, { boom: true })
+    const b = makeAppWithRoute('/error', 200, { from: 'b' })
+    const { ALL } = createAstroHandler({ apps: [a, b] })
+
+    const apiContext = fakeApiContext({
+      request: new Request('https://example.test/error'),
+      url: new URL('https://example.test/error'),
+    })
+    const res = await (ALL as any)(apiContext)
+    expect(res.status).toBe(500)
+    expect(await res.json()).toEqual({ boom: true })
+  })
+
+  test('all-404 returns the adapter\'s own 404 with empty body', async () => {
+    const a = makeAppWithRoute('/x', 200, { from: 'a' })
+    const b = makeAppWithRoute('/y', 200, { from: 'b' })
+    const { ALL } = createAstroHandler({ apps: [a, b] })
+
+    const apiContext = fakeApiContext({
+      request: new Request('https://example.test/nope'),
+      url: new URL('https://example.test/nope'),
+    })
+    const res = await (ALL as any)(apiContext)
+    expect(res.status).toBe(404)
+    expect(await res.text()).toBe('')
+  })
+})
+```
+
+- [ ] **Step 2: Run tests to verify they pass**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected: all three multi-app tests pass.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/implementations/http/astro/index.test.ts
+git commit -m "test(astro): cover multi-app first-match and non-404 short-circuit"
+```
+
+---
+
+## Task 7: Stream pass-through
+
+**Files:**
+- Modify: `src/implementations/http/astro/index.test.ts`
+
+Confirms a `HonoStreamAppBuilder` produces a streaming Response that survives the adapter intact.
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/implementations/http/astro/index.test.ts`:
+
+```ts
+import { HonoStreamAppBuilder } from '../hono-stream/index.js'
+import type { StreamConfig } from '../../types.js'
+
+describe('createAstroHandler — streams', () => {
+  test('SSE events from a HonoStream builder pass through the adapter', async () => {
+    const STREAM = Procedures<{}, StreamConfig>()
+    STREAM.CreateStream(
+      'Counter',
+      {
+        path: '/counter',
+        schema: {
+          yieldType: Type.Object({ n: Type.Number() }),
+        },
+      },
+      async function* () {
+        yield { n: 1 }
+        yield { n: 2 }
+        yield { n: 3 }
+      }
+    )
+
+    const streamApp = new HonoStreamAppBuilder().register(STREAM, () => ({})).build()
+    const { ALL } = createAstroHandler({ apps: streamApp })
+
+    const apiContext = fakeApiContext({
+      request: new Request('https://example.test/counter', { method: 'GET' }),
+      url: new URL('https://example.test/counter'),
+    })
+    const res = await (ALL as any)(apiContext)
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toMatch(/event-stream/)
+
+    // Drain the SSE body and assert all three events appear in order.
+    const text = await res.text()
+    expect(text).toMatch(/"n":1/)
+    expect(text).toMatch(/"n":2/)
+    expect(text).toMatch(/"n":3/)
+  })
+})
+```
+
+NOTE: If `HonoStreamAppBuilder`'s constructor or `CreateStream` signature differs from this snippet, open `src/implementations/http/hono-stream/index.test.ts` to find the canonical example and copy the matching shape. Do NOT invent a different API surface.
+
+- [ ] **Step 2: Run test to verify it passes (or fails informatively)**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected behaviour: the test passes. The adapter does not modify the streaming Response, so it should already work.
+
+If the test fails because of a `HonoStreamAppBuilder` API mismatch (e.g., `CreateStream` has a different signature in the current version), update only the test wiring to match — don't change the adapter.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/implementations/http/astro/index.test.ts
+git commit -m "test(astro): verify HonoStream SSE bodies pass through unchanged"
+```
+
+---
+
+## Task 8: Abort signal flow on client disconnect
+
+**Files:**
+- Modify: `src/implementations/http/astro/index.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `src/implementations/http/astro/index.test.ts`:
+
+```ts
+describe('createAstroHandler — abort signal', () => {
+  test('aborting the incoming request aborts the procedure handler\'s ctx.signal', async () => {
+    let observedSignal: AbortSignal | undefined
+    const aborted = new Promise<void>((resolve) => {
+      const API = Procedures<{}, APIConfig>()
+      API.Create(
+        'Hang',
+        { path: '/hang', method: 'get', schema: { returnType: Type.Object({ ok: Type.Boolean() }) } },
+        async (ctx) => {
+          observedSignal = ctx.signal
+          ctx.signal?.addEventListener('abort', () => resolve(), { once: true })
+          // Wait for abort or a generous timeout.
+          await new Promise<void>((r) => setTimeout(r, 200))
+          return { ok: true }
+        }
+      )
+      const app = new HonoAPIAppBuilder().register(API, () => ({})).build()
+      const { ALL } = createAstroHandler({ apps: app })
+
+      const controller = new AbortController()
+      const apiContext = fakeApiContext({
+        request: new Request('https://example.test/hang', { signal: controller.signal }),
+        url: new URL('https://example.test/hang'),
+      })
+
+      // Fire ALL but don't await — abort while the handler is still running.
+      ;(ALL as any)(apiContext).catch(() => {})
+      setTimeout(() => controller.abort(), 20)
+    })
+
+    await aborted
+    expect(observedSignal?.aborted).toBe(true)
+  })
+})
+```
+
+- [ ] **Step 2: Run test to verify it passes**
+
+Run:
+
+```bash
+npm test -- src/implementations/http/astro
+```
+
+Expected: the test passes. The HonoAPIAppBuilder already wires `ctx.signal = c.req.raw.signal`, and our `stripPrefix` preserves the signal via `new Request(url, request)`.
+
+If it fails, the cause is most likely that the rewritten `new Request(url, request)` is not preserving the signal in this Node/undici version. Investigate by adding a `console.log(rewritten.signal === request.signal)` inside `create-handler.ts` temporarily; if signals do not survive cloning, switch the rewrite to construct the new Request with explicit `signal: request.signal` in the `init` argument.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/implementations/http/astro/index.test.ts
+git commit -m "test(astro): verify client abort propagates to handler ctx.signal"
+```
+
+---
+
+## Task 9: README for the adapter module
+
+**Files:**
+- Create: `src/implementations/http/astro/README.md`
+
+- [ ] **Step 1: Read a sibling README for tone and structure**
+
+Open `src/implementations/http/hono-api/README.md` and skim the structure (overview → install → quick example → config reference → recipes).
+
+- [ ] **Step 2: Write the README**
+
+Create `src/implementations/http/astro/README.md` with this content:
+
+````markdown
+# `ts-procedures/astro`
+
+Drop one or more pre-built Hono apps (from `HonoAPIAppBuilder`, `HonoRPCAppBuilder`, or `HonoStreamAppBuilder`) into a single Astro catch-all endpoint. Procedure handlers can read Astro's per-request data (`locals`, `cookies`, `redirect`, `params`) inside their factory-context closures.
+
+## Install
+
+The adapter is part of `ts-procedures`. Astro is an optional peer; install it in your Astro app:
+
+```bash
+npm install ts-procedures hono astro
+```
+
+## Quick start
+
+```ts
+// src/server/api.ts
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import { getAstroContext } from 'ts-procedures/astro'
+import { usersAPI } from './procedures/users'
+import { db } from './db'
+
+export const apiApp = new HonoAPIAppBuilder()
+  .register(usersAPI, (c) => {
+    const astro = getAstroContext(c)
+    return { db, user: astro.locals.user ?? null }
+  })
+  .build()
+```
+
+```ts
+// src/pages/api/[...rest].ts
+import { createAstroHandler } from 'ts-procedures/astro'
+import { apiApp } from '../../server/api'
+
+export const { ALL } = createAstroHandler({
+  apps: apiApp,
+  pathPrefix: '/api',
+})
+```
+
+## Config reference
+
+| Option       | Type                  | Description                                                                                  |
+| ------------ | --------------------- | -------------------------------------------------------------------------------------------- |
+| `apps`       | `Hono \| Hono[]`      | One or more built Hono apps. Order matters in first-match dispatch.                          |
+| `pathPrefix` | `string \| undefined` | Path prefix matching the Astro catch-all mount point. `/api`, `api`, `/api/` are equivalent. |
+
+## Path prefix semantics
+
+The catch-all file is at `src/pages/api/[...rest].ts`, so Astro receives requests with paths like `/api/users/123`. The Hono builder routes you registered probably use just `/users/:id`. Configuring `pathPrefix: '/api'` strips the prefix before delegating — your Hono routes don't need to repeat the prefix.
+
+| Request path     | `pathPrefix` | Inner Hono sees |
+| ---------------- | ------------ | --------------- |
+| `/api/users/123` | `'/api'`     | `/users/123`    |
+| `/api`           | `'/api'`     | `/`             |
+| `/somewhere`     | `'/api'`     | (404, no app invoked) |
+| `/users/123`     | `undefined`  | `/users/123`    |
+
+## Multi-app dispatch
+
+Pass an array. The adapter tries each app in order:
+
+```ts
+export const { ALL } = createAstroHandler({
+  apps: [apiApp, rpcApp, streamsApp],
+  pathPrefix: '/api',
+})
+```
+
+Dispatch rules:
+- The first response with `status !== 404` is returned.
+- A `500` from app A stops dispatch (it is treated as a real answer, not a miss).
+- Only literal 404s fall through to the next app.
+- All apps 404 → adapter returns its own `Response(null, { status: 404 })`.
+
+## Streams
+
+`HonoStreamAppBuilder` returns a `Response` with a `ReadableStream` body. Astro SSR forwards that body verbatim — no additional configuration. Client disconnects abort `ctx.signal` inside the stream handler.
+
+## What's NOT included
+
+- Express RPC support (Express uses Node `req`/`res`, not Web Fetch).
+- DocRegistry coupling — wire `DocRegistry` against the same builders separately for client codegen.
+````
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/implementations/http/astro/README.md
+git commit -m "docs(astro): add README for ts-procedures/astro subpath"
+```
+
+---
+
+## Task 10: End-to-end walkthrough doc
+
+**Files:**
+- Create: `docs/astro-adapter.md`
+
+- [ ] **Step 1: Write the walkthrough**
+
+Create `docs/astro-adapter.md` with this content:
+
+````markdown
+# Astro adapter walkthrough
+
+This walkthrough builds an Astro app that serves ts-procedures handlers from a single catch-all endpoint.
+
+## Project shape
+
+```
+my-astro-app/
+├── astro.config.mjs
+├── package.json
+└── src/
+    ├── server/
+    │   ├── db.ts
+    │   ├── procedures/
+    │   │   └── users.ts
+    │   └── api.ts
+    └── pages/
+        └── api/
+            └── [...rest].ts
+```
+
+## 1. Define procedures
+
+```ts
+// src/server/procedures/users.ts
+import { Procedures } from 'ts-procedures'
+import type { APIConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+type UserContext = {
+  db: { findUser(id: string): Promise<{ id: string; name: string } | null> }
+  currentUser: { id: string } | null
+}
+
+export const usersAPI = Procedures<UserContext, APIConfig>()
+
+usersAPI.Create(
+  'GetUser',
+  {
+    path: '/users/:id',
+    method: 'get',
+    schema: {
+      input: { pathParams: Type.Object({ id: Type.String() }) },
+      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
+  },
+  async (ctx, { pathParams }) => {
+    const u = await ctx.db.findUser(pathParams.id)
+    if (!u) throw new Error('not found')
+    return u
+  }
+)
+```
+
+## 2. Build the Hono app once
+
+```ts
+// src/server/api.ts
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import { getAstroContext } from 'ts-procedures/astro'
+import { usersAPI } from './procedures/users'
+import { db } from './db'
+
+export const apiApp = new HonoAPIAppBuilder()
+  .register(usersAPI, (c) => {
+    const astro = getAstroContext(c)
+    return {
+      db,
+      currentUser: astro.locals.user ?? null,
+    }
+  })
+  .build()
+```
+
+## 3. Mount the catch-all
+
+```ts
+// src/pages/api/[...rest].ts
+import { createAstroHandler } from 'ts-procedures/astro'
+import { apiApp } from '../../server/api'
+
+export const { ALL } = createAstroHandler({
+  apps: apiApp,
+  pathPrefix: '/api',
+})
+```
+
+That's it — `GET /api/users/123` runs through `usersAPI.GetUser`. The factory closure sees `astro.locals.user` populated from your Astro middleware.
+
+## Where do `Astro.locals.user` come from?
+
+A typical pattern: an Astro middleware that reads a session cookie and sets `locals.user`:
+
+```ts
+// src/middleware.ts
+import { defineMiddleware } from 'astro:middleware'
+import { db } from './server/db'
+
+export const onRequest = defineMiddleware(async (context, next) => {
+  const sessionId = context.cookies.get('sid')?.value
+  if (sessionId) {
+    context.locals.user = await db.findUserBySession(sessionId)
+  }
+  return next()
+})
+```
+
+The Astro runtime invokes this before your endpoint. The adapter then forwards the same `APIContext` (with `locals.user` populated) into the WeakMap, so `getAstroContext(c)` returns it inside the procedure factory.
+
+## Client codegen — where does it go?
+
+The adapter does NOT couple to `DocRegistry`. Wire codegen separately, against the same builders:
+
+```ts
+// scripts/build-docs.ts
+import { DocRegistry } from 'ts-procedures/http-docs'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import { usersAPI } from '../src/server/procedures/users'
+
+const builder = new HonoAPIAppBuilder().register(usersAPI, () => ({} as never))
+builder.build()
+
+const registry = new DocRegistry().from(builder)
+console.log(JSON.stringify(registry.toEnvelope(), null, 2))
+```
+
+Then run `npx ts-procedures-codegen --file <envelope.json> --out ./generated/api`.
+
+## Multi-app composition
+
+For larger projects with separate API/RPC/Stream surfaces, pass an array:
+
+```ts
+export const { ALL } = createAstroHandler({
+  apps: [apiApp, rpcApp, streamsApp],
+  pathPrefix: '/api',
+})
+```
+
+Order matters — first non-404 wins. See the module README for full dispatch rules.
+````
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add docs/astro-adapter.md
+git commit -m "docs: add Astro adapter walkthrough"
+```
+
+---
+
+## Task 11: Scaffold template for ts-procedures-scaffold skill
+
+**Files:**
+- Create: `agent_config/claude-code/skills/ts-procedures-scaffold/templates/astro-catchall.ts`
+
+- [ ] **Step 1: Read an existing template for tone**
+
+Open `agent_config/claude-code/skills/ts-procedures-scaffold/templates/hono-rpc.ts` (or whichever exists) and skim the comment style.
+
+- [ ] **Step 2: Write the template**
+
+Create `agent_config/claude-code/skills/ts-procedures-scaffold/templates/astro-catchall.ts`:
+
+```ts
+// src/pages/api/[...rest].ts
+//
+// Catch-all entry point that serves every ts-procedures route from a single Astro file.
+// Adjust `pathPrefix` to match the directory the file lives in (e.g., '/api' for
+// src/pages/api/[...rest].ts; '/v1' for src/pages/v1/[...rest].ts).
+//
+// Build your Hono app(s) ONCE in a sibling module, then drop them in here.
+
+import { createAstroHandler } from 'ts-procedures/astro'
+import { apiApp } from '../../server/api' // ← your built Hono app(s)
+
+export const { ALL } = createAstroHandler({
+  apps: apiApp,
+  pathPrefix: '/api',
+})
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add agent_config/claude-code/skills/ts-procedures-scaffold/templates/astro-catchall.ts
+git commit -m "feat(agent-config): add astro-catchall scaffold template"
+```
+
+---
+
+## Task 12: Update agent_config rules (api-reference + patterns + Copilot/Cursor)
+
+**Files:**
+- Modify: `agent_config/claude-code/skills/ts-procedures/api-reference.md`
+- Modify: `agent_config/claude-code/skills/ts-procedures/patterns.md`
+- Modify: `agent_config/copilot/copilot-instructions.md`
+- Modify: `agent_config/cursor/cursorrules`
+
+- [ ] **Step 1: Read the current api-reference.md**
+
+Open `agent_config/claude-code/skills/ts-procedures/api-reference.md` and locate the existing section that lists builders (HonoAPIAppBuilder, HonoRPCAppBuilder, HonoStreamAppBuilder, etc.).
+
+- [ ] **Step 2: Add an Astro adapter section**
+
+After the existing builders section in `api-reference.md`, append:
+
+````markdown
+## Astro adapter — `ts-procedures/astro`
+
+For Astro apps, mount one or more pre-built Hono apps inside a single catch-all endpoint:
+
+```ts
+// src/pages/api/[...rest].ts
+import { createAstroHandler } from 'ts-procedures/astro'
+import { apiApp } from '../../server/api'
+
+export const { ALL } = createAstroHandler({
+  apps: apiApp,
+  pathPrefix: '/api',
+})
+```
+
+Inside factory-context closures, read Astro's APIContext via `getAstroContext`:
+
+```ts
+import { getAstroContext } from 'ts-procedures/astro'
+
+new HonoAPIAppBuilder()
+  .register(usersAPI, (c) => {
+    const astro = getAstroContext(c)
+    return { db, user: astro.locals.user ?? null }
+  })
+  .build()
+```
+
+Multi-app: pass an array; first non-404 response wins. All-404 falls back to the adapter's own 404. Streams pass through unchanged.
+
+Constraints:
+- Astro 5+ in SSR (or `prerender = false`).
+- Express builders are NOT supported by this adapter — Hono builders only.
+````
+
+- [ ] **Step 3: Update patterns.md**
+
+Open `agent_config/claude-code/skills/ts-procedures/patterns.md` and add a new "Astro integration" pattern at the end of the file:
+
+````markdown
+### Astro integration
+
+When a downstream developer is building inside an Astro app, recommend the catch-all pattern:
+
+1. Build the Hono app ONCE in `src/server/api.ts` using `HonoAPIAppBuilder` / `HonoRPCAppBuilder` / `HonoStreamAppBuilder` exactly as you would for any other deployment.
+2. Inside the factory-context closure, call `getAstroContext(c)` to read `locals`, `cookies`, `params`, etc.
+3. Mount the built app(s) in a single catch-all file: `src/pages/api/[...rest].ts`. Use `pathPrefix: '/api'` so your Hono routes don't need to repeat the prefix.
+
+Anti-pattern: don't create one Astro file per procedure — that loses the centralized factory wiring and forces the developer to repeat the context closure.
+
+Anti-pattern: don't try to use `express-rpc` with the Astro adapter. The adapter only accepts Web-Fetch apps (Hono).
+````
+
+- [ ] **Step 4: Mirror the same content into Copilot and Cursor rules**
+
+Per CLAUDE.md, `agent_config/copilot/copilot-instructions.md` and `agent_config/cursor/cursorrules` are kept identical inside their `<!-- BEGIN/END ts-procedures -->` markers.
+
+In each file, locate the existing builders section and append (verbatim — same text in both files):
+
+```markdown
+## Astro adapter
+
+Catch-all endpoint pattern. Build Hono apps once with HonoAPI/RPC/Stream builders, mount via `createAstroHandler` in `src/pages/api/[...rest].ts` with `pathPrefix: '/api'`. Read Astro context inside factory closures with `getAstroContext(c)`. Multi-app dispatch is first-non-404-wins. Express builders are not supported.
+```
+
+- [ ] **Step 5: Run the docs-consistency check**
+
+Run:
+
+```bash
+npm run check-docs
+```
+
+Expected: passes. If it fails because Copilot and Cursor diverged, reconcile them — both files should contain the same Astro section verbatim.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add agent_config/
+git commit -m "docs(agent-config): teach Claude/Cursor/Copilot rules the Astro adapter"
+```
+
+---
+
+## Task 13: Final validation
+
+**Files:** none
+
+- [ ] **Step 1: Run the full test suite**
+
+Run:
+
+```bash
+npm test
+```
+
+Expected: all tests pass, including the new Astro suite.
+
+- [ ] **Step 2: Run the build**
+
+Run:
+
+```bash
+npm run build
+```
+
+Expected: build succeeds. The `./astro` subpath emits `build/implementations/http/astro/index.{js,d.ts}`.
+
+- [ ] **Step 3: Run the lint**
+
+Run:
+
+```bash
+npm run lint
+```
+
+Expected: no warnings or errors.
+
+- [ ] **Step 4: Verify the subpath resolves**
+
+Run:
+
+```bash
+node --input-type=module -e "import('ts-procedures/astro').then(m => console.log(Object.keys(m).sort()))"
+```
+
+Expected: `['createAstroHandler', 'getAstroContext']` (order may vary, but both names present).
+
+- [ ] **Step 5: Final commit if any tail-end fixes were needed**
+
+If steps 1-4 required any code adjustments, commit them with:
+
+```bash
+git add -A
+git commit -m "chore(astro): final cleanup after full-suite validation"
+```
+
+If nothing changed, skip this step.
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- Approach (catch-all + delegate to Hono apps) — Tasks 4, 5, 6
+- WeakMap-based `getAstroContext` — Task 3, integration test in Task 5
+- Path prefix rewrite with all normalizations + query preservation — Task 2 (unit), Task 5 (integration)
+- Multi-app first-non-404 dispatch with non-404 short-circuit — Task 6
+- Stream pass-through — Task 7
+- Abort signal flow — Task 8
+- 404 fallback when nothing matches or prefix mismatches — Task 5 + Task 6
+- File layout (`astro-context.ts`, `rewrite-request.ts`, `create-handler.ts`, `index.ts`, `index.test.ts`, `README.md`) — Tasks 1, 2, 3, 4, 9
+- Package.json `./astro` export, `optionalDependencies` + `devDependencies` for `astro` — Task 1
+- `import type` only — Task 3 (`astro-context.ts` uses `import type { APIContext }`); Task 4 (`create-handler.ts` uses `import type { Hono }`, `import type { APIRoute }`)
+- `docs/astro-adapter.md` walkthrough — Task 10
+- Agent config updates (api-reference, patterns, scaffold template, Copilot/Cursor) — Tasks 11, 12
+
+**Placeholder scan:** No "TBD"/"TODO"/"implement later". Every code block contains the actual content. Tests have specific assertions, not "verify behavior".
+
+**Type consistency:**
+- `AstroAdapterConfig` — defined Task 4, referenced Task 4. Single definition.
+- `AstroHandlers` — defined Task 4, referenced Task 4. Single definition.
+- `setAstroContext(req, ctx)` — defined Task 3, called Task 4. Same signature both places.
+- `getAstroContext(c)` — defined Task 3, called Tasks 5, 9, 10, 11, 12. Same signature.
+- `stripPrefix(request, prefix)` — defined Task 2, called Task 4. Same signature.
+
+**Out-of-scope items confirmed not in plan:**
+- Express adapter — explicitly excluded
+- Native Astro builders — explicitly excluded
+- DocRegistry coupling — wired separately in walkthrough (Task 10), not in adapter
+- `dispatch: 'merge'` knob — not introduced
+
+Ready for execution.