@escalay/kit 0.0.0-stage → 1.8.0

package/src/db/README.md

@@ -0,0 +1,39 @@
+# db
+
+The app's database through Drizzle: one `openDb` per app, and every feature's `repo.ts` queries through it. The same
+queries run on a local SQLite file today and on Turso or D1 later; only how the database is opened changes.
+
+Needs: `drizzle-orm` (0.45). On Node ≥ 22.16, `node:sqlite` (with `setReturnArrays`); on Cloudflare Workers, a D1
+binding. No native module. The module imports on both: `node:sqlite` loads only when a path asks for it.
+
+```ts
+import { migrate, openDb, testDb } from './kit/index.js'
+
+const db = await openDb(`file:${join(env.STATE_DIR, 'state.sqlite')}`)   // a path, ':memory:', or an open DatabaseSync
+await migrate(db, 'notes', NOTES_MIGRATIONS)                             // each feature brings its own steps
+const rows = await db.select().from(notes).where(eq(notes.id, id))       // in repo.ts only
+
+const db = await openDb(drizzle(createClient({ url, authToken })))       // Turso: any async Drizzle SQLite database
+const db = await openDb(drizzle(env.DB))                                 // Cloudflare D1 (drizzle-orm/d1), in worker.ts
+const db = await testDb()                                               // tests: empty, in memory
+```
+
+| Export | What |
+|---|---|
+| `openDb(source)` | a path or `file:` URL or `:memory:` or `DatabaseSync` → Drizzle over node:sqlite (the `sqlite-proxy` driver, rows as arrays so same-named columns in a join stay apart); a Drizzle database → used as it is; any other URL → an error naming what to do |
+| `migrate(db, feature, steps)` | applies the steps not yet applied, in order, each in a transaction, recorded in `kit_migrations (feature, step)`; on D1 (which refuses `begin`) each step and its record go as one atomic batch |
+| `dbGuardStore(db)` | the guards' state (`core/guards.ts`) in table `kit_guards`, each check one atomic statement: rate windows and Idempotency-Key answers shared by every instance. On Workers pass it to `createAgentApi({ guards: { store } })` and every `rateLimit` |
+| `testDb()` | Node: an empty in-memory database; workerd: the test Worker's `DB` binding (storage is kept apart per test file, not per test) |
+| `Db` | the type every repo takes |
+
+## Rules
+
+- **Only a feature's `repo.ts` queries the database.** Handlers call the repo, never `db`. That keeps a move off SQLite to
+  the repos, and SQLite-only SQL (FTS5, `json_each`) inside a repo function.
+- **A migration step never changes once it has run anywhere.** A change is a new step at the end. Step 1 of a table
+  that already exists is its exact `create table if not exists …`, so live data is adopted.
+- One step may hold several statements separated by `;` (not triggers: give a trigger its own step).
+- **Rows have one shape on every database only through the query builder.** Raw `db.all(sql…)` returns arrays on
+  node:sqlite and objects on D1: a repo uses `db.select()`, or names its columns and reads both shapes.
+- Read-only catalogs (a built store, JSON in memory) don't go through `db`; they stay behind their own store module.
+- Decision record: `docs/decisions/0001-features-drizzle-scaffold.md`.

package/src/db/guards.ts

@@ -0,0 +1,61 @@
+/**
+ * The guards' state (`core/guards.ts`) in the app's database, so every instance shares it: on Workers each isolate has
+ * its own memory, and a rate limit or an idempotency key kept there holds for that isolate alone. Each method is one
+ * atomic statement (an upsert with `returning`, or an insert that does nothing on conflict), on node:sqlite and D1
+ * alike.
+ *
+ * @example
+ * const guards = await dbGuardStore(db)
+ * const app = createAgentApi({ …, guards: { store: guards } })
+ */
+import { and, eq, lte, sql } from 'drizzle-orm'
+import { integer, primaryKey, sqliteTable, text } from 'drizzle-orm/sqlite-core'
+import type { GuardStore, StoredAnswer } from '../core/guards.js'
+import { migrate, type Db } from './index.js'
+
+/** One row per rate window (`rate`) or idempotency key (`key`); `value` is empty while a key's request runs. */
+export const kitGuards = sqliteTable('kit_guards', {
+  kind: text('kind').notNull(),
+  id: text('id').notNull(),
+  start: integer('start').notNull(),
+  used: integer('used').notNull(),
+  value: text('value').notNull(),
+  expiresAt: integer('expires_at').notNull(),
+}, (table) => [primaryKey({ columns: [table.kind, table.id] })])
+
+export const GUARD_MIGRATIONS = ['create table if not exists kit_guards (kind text not null, id text not null, start integer not null, used integer not null, value text not null, expires_at integer not null, primary key (kind, id))'] as const
+
+/** Makes the guards' table if needed and drops expired rows (epoch ms throughout). */
+export const dbGuardStore = async (db: Db): Promise<GuardStore> => {
+  await migrate(db, 'guards', GUARD_MIGRATIONS)
+  await db.delete(kitGuards).where(lte(kitGuards.expiresAt, Date.now()))
+  const key = (id: string) => and(eq(kitGuards.kind, 'key'), eq(kitGuards.id, id))
+  return {
+    count: async (id, windowMs, now) => {
+      // SQLite evaluates every `set` against the row as it was, so `start` and `used` restart together
+      const stale = sql`${kitGuards.start} <= ${now - windowMs}`
+      const [window] = await db.insert(kitGuards).values({ kind: 'rate', id, start: now, used: 1, value: '', expiresAt: now + windowMs })
+        .onConflictDoUpdate({
+          target: [kitGuards.kind, kitGuards.id],
+          set: {
+            used: sql`case when ${stale} then 1 else ${kitGuards.used} + 1 end`,
+            start: sql`case when ${stale} then ${now} else ${kitGuards.start} end`,
+            expiresAt: sql`case when ${stale} then ${now + windowMs} else ${kitGuards.expiresAt} end`,
+          },
+        })
+        .returning({ start: kitGuards.start, used: kitGuards.used })
+      return window!
+    },
+    claim: async (id, lockMs, now) => {
+      // An expired answer, or a lock whose request died, no longer holds the key
+      await db.delete(kitGuards).where(and(key(id), lte(kitGuards.expiresAt, now)))
+      const taken = await db.insert(kitGuards).values({ kind: 'key', id, start: now, used: 0, value: '', expiresAt: now + lockMs }).onConflictDoNothing().returning({ id: kitGuards.id })
+      if (taken.length) return null
+      const [row] = await db.select({ value: kitGuards.value }).from(kitGuards).where(key(id))
+      if (!row) return null
+      return row.value ? (JSON.parse(row.value) as StoredAnswer) : 'running'
+    },
+    save: async (id, answer, expiresAt) => void (await db.update(kitGuards).set({ value: JSON.stringify(answer), expiresAt }).where(key(id))),
+    release: async (id) => void (await db.delete(kitGuards).where(and(key(id), eq(kitGuards.value, '')))),
+  }
+}

package/src/db/index.ts

@@ -0,0 +1,122 @@
+/**
+ * The app's database, through Drizzle: one handle every feature's repo queries, opened from where the data lives, so
+ * the same queries run on a local SQLite file today and on Turso or D1 later. Only repos (`<feature>/repo.ts`) touch
+ * it; handlers never do.
+ *   'file:./state.sqlite', a plain path, ':memory:', or an open `DatabaseSync`  → node:sqlite (built in, no native
+ *                                                                                 module), through Drizzle's proxy driver
+ *   any async Drizzle SQLite database                                           → used as it is: Turso / libSQL
+ *                                                                                 `drizzle(createClient({ url, authToken }))`
+ *                                                                                 (`drizzle-orm/libsql`), D1 `drizzle(env.DB)`
+ * The module imports on Workers: node:sqlite loads only when a path asks for it. Raw `db.all(sql…)` rows are arrays
+ * on node:sqlite and objects on D1, so repos read rows through the query builder or name their columns.
+ * Each feature brings its tables and its migrations: `migrate(db, 'boards', BOARDS_MIGRATIONS)` applies the steps it
+ * hasn't yet, in order, and records them in `kit_migrations`. A step never changes once shipped; a change is a new step.
+ *
+ * @example
+ * const db = await openDb(`file:${join(env.STATE_DIR, 'state.sqlite')}`)
+ * registerBoards(app, { db, … })                  // migrates its own tables
+ * const rows = await db.select().from(notes).where(eq(notes.owner, id))
+ */
+import type { DatabaseSync, SQLInputValue } from 'node:sqlite'
+import { is, sql } from 'drizzle-orm'
+import { DrizzleD1Database } from 'drizzle-orm/d1'
+import type { BaseSQLiteDatabase } from 'drizzle-orm/sqlite-core'
+import { drizzle } from 'drizzle-orm/sqlite-proxy'
+
+/** Any async Drizzle SQLite database: node:sqlite through the proxy, libSQL, D1. */
+export type Db = BaseSQLiteDatabase<'async', unknown>
+
+/** Where the data lives: a URL or path, an open node:sqlite database, or a Drizzle database already made. */
+export type DbSource = string | DatabaseSync | Db
+
+// node:sqlite is loaded only when a source needs it, so the module imports on Workers (where it is a stub)
+const isDb = (source: DbSource): source is Db => typeof source === 'object' && 'select' in source
+const isDatabaseSync = (source: DbSource): source is DatabaseSync => typeof source === 'object' && 'prepare' in source && 'exec' in source
+
+/** What migrate needs of a D1 binding (typed here so the module needs no Workers types). */
+type D1Statement = { bind: (...values: unknown[]) => D1Statement }
+type D1Client = { prepare: (query: string) => D1Statement; batch: (statements: D1Statement[]) => Promise<unknown> }
+
+/** Drizzle over node:sqlite: rows come back as arrays, so columns with the same name in a join stay apart. */
+export const nodeSqlite = (sqlite: DatabaseSync): Db => {
+  sqlite.exec('pragma foreign_keys = on')
+  return drizzle(async (query, params, method) => {
+    const statement = sqlite.prepare(query)
+    const values = params as SQLInputValue[]
+    if (method === 'run') {
+      statement.run(...values)
+      return { rows: [] }
+    }
+    statement.setReturnArrays(true)
+    return method === 'get' ? { rows: statement.get(...values) as unknown as unknown[] } : { rows: statement.all(...values) as unknown as unknown[] }
+  }) as unknown as Db
+}
+
+/** Opens the database a source names (see the module comment). */
+export const openDb = async (source: DbSource): Promise<Db> => {
+  if (isDb(source)) return source
+  if (isDatabaseSync(source)) return nodeSqlite(source)
+  if (/^[a-z]+:\/\//.test(source)) throw new Error(`openDb: ${source.split('//')[0]}// is not a file; open it with its Drizzle driver and pass the database in (Turso: drizzle-orm/libsql, D1: drizzle(env.DB) from drizzle-orm/d1)`)
+  const { DatabaseSync } = await import('node:sqlite')
+  return nodeSqlite(new DatabaseSync(source === ':memory:' ? source : source.replace(/^file:/, '')))
+}
+
+/**
+ * A database for tests: empty and in memory on Node; inside workerd (the Workers test project) the `DB` D1 binding,
+ * whose storage is kept apart per test file, not per test, so tests there use their own ids.
+ */
+export const testDb = async () => {
+  if (globalThis.navigator?.userAgent !== 'Cloudflare-Workers') return openDb(':memory:')
+  const runtime = 'cloudflare:workers'
+  const { env } = (await import(runtime)) as { env: { DB?: unknown } }
+  if (!env.DB) throw new Error('testDb: the Workers test project has no D1 binding named DB; add one to its wrangler config')
+  const { drizzle } = await import('drizzle-orm/d1')
+  return openDb(drizzle(env.DB as never) as unknown as Db)
+}
+
+/** A step's statements: split on every `;` outside quotes (a prepared statement runs only the first of several). */
+const statementsOf = (step: string) => {
+  const statements: string[] = []
+  let current = ''
+  let quote: string | null = null
+  for (const char of step) {
+    if (quote) quote = char === quote ? null : quote
+    else if (char === "'" || char === '"' || char === '`') quote = char
+    else if (char === ';') {
+      statements.push(current)
+      current = ''
+      continue
+    }
+    current += char
+  }
+  return [...statements, current].map((statement) => statement.trim()).filter(Boolean)
+}
+
+/**
+ * Applies a feature's migration steps it hasn't applied yet, in order, each in a transaction with its record in
+ * `kit_migrations (feature, step)`. Steps are SQL; one step may hold several statements separated by `;` (not
+ * triggers: their bodies hold `;`, so give each its own step and no other statement). On D1, which refuses `begin`,
+ * a step and its record go as one batch: D1 runs a batch as a single transaction.
+ */
+export const migrate = async (db: Db, feature: string, steps: readonly string[]) => {
+  await db.run(sql`create table if not exists kit_migrations (feature text not null, step integer not null, applied_at text not null, primary key (feature, step))`)
+  const done = await db.all<{ step: number }>(sql`select step from kit_migrations where feature = ${feature}`)
+  const applied = new Set(done.map((row) => Number(Array.isArray(row) ? row[0] : row.step)))
+  for (const [index, step] of steps.entries()) {
+    if (applied.has(index + 1)) continue
+    const appliedAt = new Date().toISOString()
+    if (is(db, DrizzleD1Database)) {
+      const d1 = (db as unknown as { $client: D1Client }).$client
+      const record = d1.prepare('insert into kit_migrations (feature, step, applied_at) values (?, ?, ?)').bind(feature, index + 1, appliedAt)
+      await d1.batch([...statementsOf(step).map((statement) => d1.prepare(statement)), record])
+      continue
+    }
+    await db.transaction(async (tx) => {
+      for (const statement of statementsOf(step)) await tx.run(sql.raw(statement))
+      await tx.run(sql`insert into kit_migrations (feature, step, applied_at) values (${feature}, ${index + 1}, ${appliedAt})`)
+    })
+  }
+}
+
+// An app's generated kit index re-exports each module's own index.ts, so the module's other parts go out from here
+export { dbGuardStore, kitGuards, GUARD_MIGRATIONS } from './guards.js'

package/src/guide/README.md

@@ -0,0 +1,38 @@
+# guide
+
+The agent guide: `/llms.txt`, `/llms-full.txt`, `/agents/*.md` and `/skills/*` from Markdown templates, filled per
+request. Everything the code knows (endpoints, tools, playbooks, how to get unstuck) is generated from the OpenAPI
+document and the MCP tools, so the guide can't drift from the API.
+
+Needs: `core`.
+
+```ts
+import { guideFiles, serveGuide } from './kit/index.js'
+
+serveGuide(app, { dir: GUIDE_DIR, vars: () => ({ counts: { notes: store.notes.length } }), full: ['llms.txt', 'agents/*', 'skills/*'] })
+serveGuide(app, { files: GUIDE_FILES, vars, full })   // Workers can't read a folder: `kit guide` writes src/guide.gen.ts
+```
+
+```md
+# Notes
+> {{counts.notes}} notes. Start with GET /api/search?q=…
+
+## Endpoints
+{{api.endpoints}}
+
+## MCP tools ({{mcp.count}})
+{{mcp.tools}}
+```
+
+| File | What |
+|---|---|
+| `guide.ts` | `serveGuide` (from `dir`, or `files` on Workers), `guideFiles(dir)`, `guideModuleSource(files)` (the text `kit guide` writes; an app's test compares its `guide.gen.ts` to it), `fillTemplate` |
+| `reference.ts` | the generated parts: `{{api.endpoints}}`, `{{api.operations}}`, `{{api.unblock}}`, `{{mcp.tools}}`, `{{mcp.count}}`, `{{mcp.resources}}`, `{{skills.<name>.playbooks}}` |
+
+## Rules
+
+- Write only what the code can't know: concepts, trust and measured accuracy, real-id examples, playbook steps and
+  judgement. Never hand-write a list of endpoints or tools.
+- Layout: `guide/llms.txt`, `guide/agents/{concepts,endpoints,trust,mcp}.md`, `guide/skills/<name>/SKILL.md` +
+  `references/*.md` (served as MCP prompts too).
+- Test it: `guideRoutes` and `guideGaps` (the testing module) return `[]`. Standard: `docs/STANDARD.md` §10.

package/src/guide/guide.ts

@@ -0,0 +1,152 @@
+/**
+ * The agent guide, served from a folder of Markdown templates so it reads and diffs like docs:
+ *   llms.txt                  the index (llmstxt.org): what this is, real example calls, links to the rest
+ *   agents/*.md               concepts, endpoints, trust and limits, MCP
+ *   skills/SKILL.md, *.md     a skill folder: a router plus one playbook per task (also the MCP prompts)
+ * `/llms-full.txt` is assembled from them in the order given, so it never drifts from its parts. `{{origin}}` and any
+ * `{{dotted.path}}` from `vars()` are filled per request; a placeholder with no value is left visible and reported by
+ * `fillTemplate`, which the tests check. The parts that must match the code are generated, never written by hand:
+ * `{{api.endpoints}}`, `{{api.tag.<slug>}}`, `{{api.unblock}}`, `{{mcp.tools}}`, `{{skills.<name>.playbooks}}`
+ * (see `reference.ts`). Each skill folder is also published for discovery: `/.well-known/agent-skills/index.json`
+ * and a deterministic archive per skill with references, or its SKILL.md alone.
+ *
+ * On Node the templates are read from `dir`; on Workers, which can't read a folder, from `files`: the module
+ * `kit guide` writes from the folder (`GUIDE_FILES`), checked current by a test with `guideModuleSource`.
+ *
+ * @example
+ * serveGuide(app, { dir: join(APP_DIR, 'guide'), vars: () => ({ snapshot: store.snapshot, counts: store.counts }),
+ *   full: ['llms.txt', 'agents/concepts.md', 'agents/endpoints.md', 'agents/trust.md', 'agents/mcp.md', 'skills/*'] })
+ * serveGuide(app, { files: GUIDE_FILES, vars, full })      // Workers: import { GUIDE_FILES } from './guide.gen.js'
+ */
+import { readdirSync, readFileSync, existsSync } from 'node:fs'
+import { join, relative } from 'node:path'
+import type { Context, Hono } from 'hono'
+import { CACHE } from '../core/cache.js'
+import { frontmatterOf, recordMounted, mountedOf, sendPublic, skillsIndex, tarGz, WELL_KNOWN, type SkillArtifact } from '../core/discovery.js'
+import { originOf } from '../core/hal.js'
+import { problemResponse } from '../core/problem.js'
+import { generatedVars, type OpenApiDoc } from './reference.js'
+
+export const MARKDOWN = 'text/markdown; charset=utf-8'
+
+/** `{{counts.recipes}}` → the value at that path; numbers get thousands separators. Unknown names stay as they are. */
+export const fillTemplate = (template: string, vars: Record<string, unknown>) => {
+  const missing = new Set<string>()
+  const text = template.replace(/\{\{\s*([\w.-]+)\s*\}\}/g, (whole, path: string) => {
+    const value = path.split('.').reduce<unknown>((at, key) => (at && typeof at === 'object' ? (at as Record<string, unknown>)[key] : undefined), vars)
+    if (value === undefined || value === null) {
+      missing.add(path)
+      return whole
+    }
+    return typeof value === 'number' ? value.toLocaleString('en-US') : String(value)
+  })
+  return { text, missing: [...missing] }
+}
+
+/** Every Markdown/text file under `dir`, by its path relative to it (`skills/plan-a-week.md`). */
+export const guideFiles = (dir: string) => {
+  const files = new Map<string, string>()
+  const walk = (folder: string) => {
+    for (const entry of readdirSync(folder, { withFileTypes: true })) {
+      const path = join(folder, entry.name)
+      if (entry.isDirectory()) walk(path)
+      else if (/\.(md|txt)$/.test(entry.name)) files.set(relative(dir, path), readFileSync(path, 'utf8'))
+    }
+  }
+  if (existsSync(dir)) walk(dir)
+  return files
+}
+
+/**
+ * The guide's files as a TypeScript module (`GUIDE_FILES`), for runtimes that can't read a folder. Deterministic:
+ * paths sorted, `/` separators. `kit guide` writes the same text, and an app's test compares the two.
+ *
+ * @example
+ * expect(readFileSync('src/guide.gen.ts', 'utf8')).toBe(guideModuleSource(guideFiles(GUIDE_DIR)))
+ */
+export const guideModuleSource = (files: Map<string, string>) =>
+  `// Generated by \`kit guide\` from the guide folder: edit the templates there, then run it again.\n` +
+  `export const GUIDE_FILES: Record<string, string> = {\n` +
+  [...files.entries()].map(([path, text]) => [path.split('\\').join('/'), text] as const).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([path, text]) => `  ${JSON.stringify(path)}: ${JSON.stringify(text)},\n`).join('') +
+  `}\n`
+
+/** The parts of llms-full.txt in order; `folder/*` expands to that folder's files, `SKILL.md` first. */
+export const fullOrder = (files: Map<string, string>, order: string[]) =>
+  order.flatMap((entry) =>
+    entry.endsWith('/*')
+      ? [...files.keys()].filter((name) => name.startsWith(entry.slice(0, -1))).sort((a, b) => Number(b.endsWith('SKILL.md')) - Number(a.endsWith('SKILL.md')) || a.localeCompare(b))
+      : files.has(entry) ? [entry] : [],
+  )
+
+/** The guide as served: its template files and a renderer that fills them for one origin. */
+export type Guide = { files: Map<string, string>; render: (origin: string, name: string) => Promise<string> }
+
+type Requester = { request: (input: string, init?: RequestInit) => Response | Promise<Response> }
+
+export type GuideSource = { dir: string; files?: never } | { files: Map<string, string> | Record<string, string>; dir?: never }
+
+export const serveGuide = (app: Hono<any, any, any> & Requester, { vars, full, ...source }: GuideSource & { vars: () => Record<string, unknown>; full: string[] }): Guide => {
+  const files = source.files ? (source.files instanceof Map ? source.files : new Map(Object.entries(source.files))) : guideFiles(source.dir!)
+  // The OpenAPI document only changes with a deploy: fetch it once per origin, in-process, with the caller's own
+  // credentials (a private service answers the spec only to them); only a good answer is kept
+  const docs = new Map<string, Promise<OpenApiDoc>>()
+  const docOf = (origin: string, credentials: Record<string, string>) => {
+    if (!docs.has(origin)) {
+      const url = new URL(origin)
+      const fetched = Promise.resolve(app.request(WELL_KNOWN.openapi, { headers: { 'x-forwarded-proto': url.protocol.slice(0, -1), 'x-forwarded-host': url.host, ...credentials } })).then((response) => {
+        if (!response.ok) throw new Error(`the spec answered ${response.status}`)
+        return response.json() as Promise<OpenApiDoc>
+      })
+      docs.set(origin, fetched)
+      fetched.catch(() => docs.delete(origin))
+    }
+    return docs.get(origin)!
+  }
+  const credentialsOf = (c: Context) => Object.fromEntries((['authorization', 'cookie', 'cf-access-jwt-assertion'] as const).flatMap((name) => (c.req.header(name) ? [[name, c.req.header(name)!]] : [])))
+  const render = async (origin: string, name: string, credentials: Record<string, string> = {}) => {
+    const generated = generatedVars({ origin, doc: await docOf(origin, credentials), tools: mountedOf(app).mcp?.tools, resources: mountedOf(app).mcp?.resources, files })
+    return fillTemplate(files.get(name)!, { origin, ...generated, ...vars() }).text
+  }
+  const send = (c: Context, body: string) => c.body(body, 200, { 'content-type': MARKDOWN, 'cache-control': CACHE.docs })
+
+  app.get('/llms.txt', async (c) => (files.has('llms.txt') ? send(c, await render(originOf(c), 'llms.txt', credentialsOf(c))) : problemResponse(c, 'not_found')))
+  app.get('/llms-full.txt', async (c) => {
+    const parts = await Promise.all(fullOrder(files, full).map(async (name) => `<!-- ${name} -->\n\n${(await render(originOf(c), name, credentialsOf(c))).trim()}\n`))
+    return send(c, parts.join('\n---\n\n'))
+  })
+  for (const folder of ['agents', 'skills']) {
+    app.get(`/${folder}/*`, async (c) => {
+      const name = c.req.path.slice(1)
+      return files.has(name) ? send(c, await render(originOf(c), name, credentialsOf(c))) : problemResponse(c, 'not_found', { detail: `No ${name}. The index is /llms.txt.` })
+    })
+  }
+
+  // Skills for discovery: a skill with references ships as one archive, a lone SKILL.md as itself
+  const skillNames = [...files.keys()].flatMap((path) => path.match(/^skills\/([^/]+)\/SKILL\.md$/)?.[1] ?? [])
+  const artifacts = async (origin: string, credentials: Record<string, string> = {}): Promise<SkillArtifact[]> =>
+    Promise.all(
+      skillNames.map(async (name) => {
+        const own = [...files.keys()].filter((path) => path.startsWith(`skills/${name}/`))
+        const skillMd = await render(origin, `skills/${name}/SKILL.md`, credentials)
+        const { description = '' } = frontmatterOf(skillMd)
+        if (own.length === 1) return { name, description, type: 'skill-md' as const, url: `/skills/${name}/SKILL.md`, bytes: skillMd, mediaType: MARKDOWN }
+        const entries = await Promise.all(own.map(async (path): Promise<[string, string]> => [path.slice(`skills/${name}/`.length), await render(origin, path, credentials)]))
+        return { name, description, type: 'archive' as const, url: `/.well-known/agent-skills/${name}.tar.gz`, bytes: tarGz(entries), mediaType: 'application/gzip' }
+      }),
+    )
+  // The catalogs read artifacts synchronously: keep the last set built per origin
+  const built = new Map<string, SkillArtifact[]>()
+  const artifactsNow = async (origin: string, credentials: Record<string, string> = {}) => {
+    const list = await artifacts(origin, credentials)
+    built.set(origin, list)
+    return list
+  }
+  recordMounted(app, { skills: (origin) => built.get(origin) ?? [], refreshSkills: artifactsNow })
+
+  app.get(WELL_KNOWN.skillsIndex, async (c) => sendPublic(c, JSON.stringify(skillsIndex(originOf(c), await artifactsNow(originOf(c), credentialsOf(c))), null, 2), 'application/json'))
+  app.get('/.well-known/agent-skills/:file', async (c) => {
+    const skill = (await artifactsNow(originOf(c), credentialsOf(c))).find((one) => one.url === c.req.path)
+    return skill ? sendPublic(c, skill.bytes, skill.mediaType) : problemResponse(c, 'not_found', { detail: `No ${c.req.path}. The index is ${WELL_KNOWN.skillsIndex}.` })
+  })
+  return { files, render }
+}

package/src/guide/reference.ts

@@ -0,0 +1,204 @@
+/**
+ * The parts of the agent guide that must never drift from the code, written from the code: every operation from the
+ * OpenAPI document, every MCP tool with the route it calls, every playbook in the skill folder, and how to get
+ * unstuck. Guide templates place them with `{{api.endpoints}}`, `{{api.tag.<slug>}}`, `{{api.unblock}}`,
+ * `{{api.operations}}`, `{{mcp.tools}}`, `{{mcp.count}}`, `{{mcp.resources}}` and `{{skills.<name>.playbooks}}`; `serveGuide` fills them.
+ *
+ * @example
+ * endpointsMarkdown(doc)             // ### Search … - `GET /api/v1/search/recipes?q=…` — Recipes for a description. …
+ * toolRoute(tool, doc)               // { method: 'GET', path: '/api/v1/search/recipes', operationId: 'searchRecipes' }
+ */
+import type { ResourceLike, ToolLike } from '../core/discovery.js'
+
+type Schema = { type?: string | string[]; enum?: unknown[]; default?: unknown; example?: unknown; description?: string; items?: Schema; minimum?: number; maximum?: number; anyOf?: Schema[]; $ref?: string; properties?: Record<string, Schema>; additionalProperties?: unknown }
+type Parameter = { name: string; in: string; required?: boolean; description?: string; example?: unknown; schema?: Schema }
+type Operation = { operationId?: string; summary?: string; description?: string; tags?: string[]; parameters?: Parameter[]; requestBody?: { content?: Record<string, { schema?: unknown }> }; responses?: Record<string, { content?: Record<string, { schema?: Schema }> }>; security?: unknown[] }
+export type OpenApiDoc = { tags?: { name: string; description?: string }[]; paths?: Record<string, Record<string, Operation>>; components?: { schemas?: Record<string, Schema & { properties?: Record<string, Schema>; required?: string[] }> } }
+
+const METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const
+const slugOf = (name: string) => name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '')
+
+/** The first sentence: what an index line needs, the rest is one call away. */
+export const firstSentence = (text = '') => (text.replace(/\s+/g, ' ').trim().match(/^.*?[.!?](?=\s|$)/)?.[0] ?? text.trim())
+
+const typeOf = (schema: Schema = {}): string => {
+  if (schema.enum) return schema.enum.map(String).join('|')
+  // `one | one[]` is a repeatable parameter: say it once
+  const single = schema.anyOf?.find((one) => one.type !== 'array')
+  const many = schema.anyOf?.find((one) => one.type === 'array')
+  if (single && many && schema.anyOf!.length === 2 && typeOf(single) === typeOf(many.items)) return `${typeOf(single)} (repeatable)`
+  if (schema.anyOf) return [...new Set(schema.anyOf.map(typeOf))].join('|')
+  if (schema.type === 'array') return `${typeOf(schema.items)}[]`
+  return Array.isArray(schema.type) ? schema.type.join('|') : (schema.type ?? 'any')
+}
+
+/** `q*` (required), `by=meaning|look (meaning)`: a parameter as an agent scans it. */
+const paramLine = (parameter: Parameter) => {
+  const schema = parameter.schema ?? {}
+  const shape = schema.enum || schema.anyOf?.some((one) => one.enum) ? `=${typeOf(schema)}` : ''
+  const fallback = schema.default !== undefined ? ` (default ${JSON.stringify(schema.default)})` : ''
+  return `\`${parameter.name}${parameter.required ? '*' : ''}${shape}\`${fallback}`
+}
+
+/** A call with the documented examples filled in, so the line itself is a working request. */
+const exampleCall = (method: string, path: string, operation: Operation) => {
+  const params = operation.parameters ?? []
+  const filled = path.replace(/\{(\w+)\}/g, (whole, name: string) => {
+    const example = params.find((parameter) => parameter.in === 'path' && parameter.name === name)?.example ?? params.find((parameter) => parameter.name === name)?.schema?.example
+    return example === undefined ? whole : String(example)
+  })
+  const query = params
+    .filter((parameter) => parameter.in === 'query' && (parameter.required || parameter.example !== undefined) && parameter.name !== 'cursor')
+    .slice(0, 3)
+    .flatMap((parameter) => {
+      const example = parameter.example ?? parameter.schema?.example
+      return example === undefined ? [] : [`${parameter.name}=${Array.isArray(example) ? example[0] : example}`]
+    })
+  return `${method.toUpperCase()} ${filled}${query.length ? `?${query.join('&')}` : ''}`
+}
+
+const operationsOf = (doc: OpenApiDoc) =>
+  Object.entries(doc.paths ?? {}).flatMap(([path, item]) => METHODS.flatMap((method) => (item[method] ? [{ method, path, operation: item[method]! }] : [])))
+
+/** `{ "$ref": "#/components/schemas/Page" }` → the named schema and its name. */
+const resolve = (doc: OpenApiDoc, schema: Schema | undefined): { name?: string; schema?: Schema } => {
+  const name = schema?.$ref?.split('/').pop()
+  return name ? { name, schema: doc.components?.schemas?.[name] } : { schema }
+}
+
+/** `Page { count, _links, _embedded.apps[] }`: the success body's top-level fields, where lists sit, by name. */
+export const returnsOf = (doc: OpenApiDoc, operation: Operation) => {
+  const success = Object.entries(operation.responses ?? {}).find(([status]) => /^20[01]$/.test(status))?.[1]
+  const content = success?.content ? Object.values(success.content)[0] : undefined
+  const { name, schema } = resolve(doc, content?.schema)
+  if (!schema?.properties) return name ? `\`${name}\`` : ''
+  const fields = Object.entries(schema.properties).flatMap(([key, value]) => {
+    if (key !== '_embedded') return [key]
+    const embedded = resolve(doc, value).schema?.properties ?? {}
+    return Object.keys(embedded).map((inner) => `_embedded.${inner}[]`)
+  })
+  const accepted = operation.responses?.['202'] ? ' (or `202` with a run)' : ''
+  return `${name ? `\`${name}\` ` : ''}{ ${fields.join(', ')} }${accepted}`
+}
+
+/** One line per operation: the call (with real example values), what it is for, its parameters (`*` = required), what it returns. */
+export const operationLine = ({ method, path, operation }: { method: string; path: string; operation: Operation }, doc: OpenApiDoc = {}) => {
+  const query = (operation.parameters ?? []).filter((parameter) => parameter.in === 'query' && parameter.name !== 'cursor')
+  const body = operation.requestBody?.content ? Object.keys(operation.requestBody.content).map((type) => type.split(';')[0]).join(' or ') : ''
+  const open = Array.isArray(operation.security) && operation.security.length === 0 ? ' No key needed.' : ''
+  return [
+    `- \`${exampleCall(method, path, operation)}\` — ${firstSentence(operation.description ?? operation.summary)}${open}`,
+    query.length ? `Query: ${query.map(paramLine).join(', ')}.` : '',
+    body ? `Body: ${body}.` : '',
+    returnsOf(doc, operation) ? `Returns ${returnsOf(doc, operation)}.` : '',
+    operation.operationId ? `Spec: \`${operation.operationId}\`.` : '',
+  ]
+    .filter(Boolean)
+    .join(' ')
+}
+
+/** Every operation, grouped under its tag in the document's tag order; `tags` narrows to some of them. */
+export const endpointsMarkdown = (doc: OpenApiDoc, { tags }: { tags?: string[] } = {}) => {
+  const operations = operationsOf(doc)
+  const order = (doc.tags ?? []).map((tag) => tag.name).filter((name) => !tags || tags.includes(name))
+  return order
+    .map((name) => {
+      const lines = operations.filter(({ operation }) => (operation.tags ?? [])[0] === name).map((entry) => operationLine(entry, doc))
+      if (!lines.length) return ''
+      const description = doc.tags?.find((tag) => tag.name === name)?.description
+      return `### ${name}\n\n${description ? `${description}\n\n` : ''}${lines.join('\n')}`
+    })
+    .filter(Boolean)
+    .join('\n\n')
+}
+
+/** Each tag's section on its own, for a template that interleaves prose: `{{api.tag.search}}`. */
+export const endpointsByTag = (doc: OpenApiDoc) =>
+  Object.fromEntries((doc.tags ?? []).map((tag) => [slugOf(tag.name), endpointsMarkdown(doc, { tags: [tag.name] })]))
+
+// ---- MCP tools ----
+
+/** Runs a tool's `call` with placeholder arguments (`{name}`) to see the route it hits, then finds that operation. */
+export const toolRoute = (tool: ToolLike, doc: OpenApiDoc) => {
+  const placeholders = new Proxy({}, { get: (_, key) => (typeof key === 'string' ? `{${key}}` : undefined) })
+  let call: { method?: string; path: string }
+  try {
+    call = tool.call(placeholders as never)
+  } catch {
+    return null
+  }
+  const method = (call.method ?? 'GET').toLowerCase()
+  const path = call.path.split('?')[0]!
+  for (const [template, item] of Object.entries(doc.paths ?? {})) {
+    if (!item[method]) continue
+    const pattern = new RegExp(`^${template.replace(/[.*+?^$()|[\]\\]/g, '\\$&').replace(/\\?\{[^}]+\\?\}/g, '[^/]+')}$`)
+    if (pattern.test(path)) return { method: method.toUpperCase(), path: template, operationId: item[method]!.operationId }
+  }
+  return null
+}
+
+/** One line per tool: its name, the route it runs, when to use it (its own description, which also states the cost). */
+export const toolsMarkdown = (tools: ToolLike[], doc: OpenApiDoc) =>
+  tools
+    .map((tool) => {
+      const route = toolRoute(tool, doc)
+      return `- **\`${tool.name}\`** → \`${route ? `${route.method} ${route.path}` : 'no route found'}\` — ${tool.description.replace(/\s+/g, ' ').trim()}`
+    })
+    .join('\n')
+
+/** One line per MCP resource: its URI template and what attaching it gives. */
+export const resourcesMarkdown = (resources: ResourceLike[]) => resources.map((resource) => `- \`${resource.uriTemplate}\` — ${resource.title}: ${resource.description.replace(/\s+/g, ' ').trim()}`).join('\n')
+
+// ---- Skills ----
+
+/** A playbook's title (its `# heading`) and its first paragraph (what it is for). */
+export const playbookSummary = (markdown: string) => ({
+  title: markdown.match(/^# (.+)$/m)?.[1]?.trim() ?? '',
+  purpose: markdown.replace(/^---[\s\S]*?---/, '').split(/\n\s*\n/).map((part) => part.trim()).find((part) => part && !part.startsWith('#'))?.replace(/\s+/g, ' ') ?? '',
+})
+
+/** `- [Plan a week](/skills/cookbook/references/plan-a-week.md): …` for every playbook of one skill. */
+export const playbooksMarkdown = (files: Map<string, string>, skill: string) =>
+  [...files.entries()]
+    .filter(([path]) => path.startsWith(`skills/${skill}/references/`) && path.endsWith('.md'))
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([path, text]) => {
+      const { title, purpose } = playbookSummary(text)
+      return `- [${title || path}](/${path}): ${firstSentence(purpose)}`
+    })
+    .join('\n')
+
+// ---- Getting unstuck ----
+
+/** The same five ways out for every kit API: the spec, the errors, the root, runs, the problem catalogue. */
+export const unblockMarkdown = (origin: string) => {
+  const search = `curl -s ${origin}/openapi.json | jq -r '.paths | to_entries[] | .key as $p | .value | to_entries[] | "\\(.key|ascii_upcase) \\($p) — \\(.value.summary)"' | grep -i <word>`
+  return [
+    '1. **Look the call up in the spec.** `GET /openapi.json` (with your key on a private service) has every operation with its parameters, examples and',
+    `   response schema. Find one by words: \`${search}\`.`,
+    '   What a field means: the call\'s line in `/agents/endpoints.md` names its schema after "Returns"; read it with',
+    `   \`curl -s ${origin}/openapi.json | jq '.components.schemas.<Name>'\` (every field is described there).`,
+    '2. **Read the error.** Every error is `application/problem+json` with a `code`, a `detail` that says what to change,',
+    '   and `errors[]` naming the field. A `400` for an unknown query parameter lists the ones the operation takes.',
+    '   `GET /problems/{code}` explains a code.',
+    '3. **Start over from the root.** `GET /api` links every list, search and workflow; resources link their neighbours',
+    '   in `_links`, so follow links instead of building URLs. Where an answer keeps its list (`_embedded.<name>`, or a',
+    '   top-level `items` with `total`) is on each operation\'s `Returns` line in the endpoints page.',
+    '4. **A `202` is not an error.** It started a run: poll `Location` until `status` is `done`, then repeat the call',
+    '   (or read `_links.result`).',
+    '5. **Still stuck?** Say exactly which call failed and its `detail`; never guess an id, a field or a number.',
+  ].join('\n')
+}
+
+/** Everything generated, keyed the way guide templates name it. */
+export const generatedVars = ({ origin, doc, tools, resources, files }: { origin: string; doc: OpenApiDoc; tools?: ToolLike[]; resources?: ResourceLike[]; files: Map<string, string> }) => {
+  const skills = [...new Set([...files.keys()].flatMap((path) => path.match(/^skills\/([^/]+)\/SKILL\.md$/)?.[1] ?? []))]
+  return {
+    api: { endpoints: endpointsMarkdown(doc), tag: endpointsByTag(doc), unblock: unblockMarkdown(origin), operations: operationsOf(doc).length },
+    mcp: { tools: tools ? toolsMarkdown(tools, doc) : '', count: tools?.length ?? 0, resources: resources?.length ? resourcesMarkdown(resources) : 'None.' },
+    skills: Object.fromEntries(skills.map((name) => [name, { playbooks: playbooksMarkdown(files, name) }])),
+  }
+}
+
+/** Template names the kit fills itself; `guideGaps` doesn't ask the app for them. */
+export const GENERATED_ROOTS = ['origin', 'api', 'mcp', 'skills'] as const

package/src/index.ts

@@ -0,0 +1,15 @@
+export * from './core/api.js'
+export * from './core/auth.js'
+export * from './core/cache.js'
+export * from './db/index.js'
+export * from './core/discovery.js'
+export * from './guide/guide.js'
+export * from './core/hal.js'
+export * from './core/kv.js'
+export * from './oauth/index.js'
+export * from './pagination/index.js'
+export * from './core/problem.js'
+export * from './guide/reference.js'
+export * from './core/guards.js'
+export * from './vectors/index.js'
+export * from './web/index.js'