@cyanheads/mcp-ts-core 0.8.8 → 0.8.10

package/skills/api-canvas/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: api-canvas
+description: >
+  DataCanvas primitive reference — a Tier 3 SQL/analytical workspace for tabular MCP servers, backed by DuckDB. Use when registering tables from upstream APIs, running ad-hoc SQL across them, and exporting results. Covers the acquire → register → query → export flow, the token-sharing pattern for multi-agent collaboration, env config, and Cloudflare Workers fail-closed behavior.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+`DataCanvas` is a primitive for **storage stashes, canvas computes**. The existing `IStorageProvider` is a key/value abstraction — it can stash blobs but exposes no analytical surface. `DataCanvas` is the analytical surface: register tabular data from upstream APIs, run SQL across multiple registered tables, and export results as CSV/Parquet/JSON.
+
+**Tier 3** — `@duckdb/node-api` is an optional peer dependency. Servers that don't enable canvas pay zero install cost. Lazy-loaded on first use.
+
+**Disabled by default.** Set `CANVAS_PROVIDER_TYPE=duckdb` to enable. Otherwise `core.canvas` is `undefined`.
+
+**Cloudflare Workers:** unsupported. DuckDB has no V8-isolate build. Setting `CANVAS_PROVIDER_TYPE=duckdb` on a Worker fails closed with a `ConfigurationError` at init time.
+
+---
+
+## Imports
+
+```ts
+import type { DataCanvas, CanvasInstance, ColumnSchema } from '@cyanheads/mcp-ts-core/canvas';
+```
+
+The framework wires the optional service onto `CoreServices`:
+
+```ts
+interface CoreServices {
+  canvas?: DataCanvas;     // present when CANVAS_PROVIDER_TYPE !== 'none'
+  // ... other services
+}
+```
+
+---
+
+## The token-sharing model
+
+A canvas is identified by an opaque 10-character URL-safe `canvasId` (~10¹⁸ keyspace). Tools that touch canvas state accept an optional `canvas_id` input parameter:
+
+| Caller passes | Result |
+|:--------------|:-------|
+| **Omitted** | Framework mints a fresh canvasId, returns it in the tool output. Caller surfaces it to the user / next tool call / another agent. |
+| **Existing id (own tenant)** | Resolves to that canvas, slides TTL forward, returns `isNew: false`. |
+| **Existing id (other tenant)** | Throws `NotFound` — uniform with unknown to avoid leaking existence across tenants. |
+| **Unknown id** | Throws `NotFound` with a hint to omit the parameter on retry. |
+
+When auth is enabled, the effective scope is the composite `(tenantId, canvasId)`. In `MCP_AUTH_MODE=none`, `tenantId` collapses to `'default'` and the canvasId is the only differentiator — entropy + TTL + the framework's rate limiter make brute-force discovery operationally infeasible. **Designed for public-data servers (BrAPI, OpenFEC, etc.). Don't put PII on a no-auth canvas.**
+
+---
+
+## Lifecycle
+
+| Behavior | Default | Override |
+|:---------|:--------|:---------|
+| Sliding TTL | 24 h, extended on every operation | `CANVAS_TTL_MS` |
+| Absolute cap from creation | 7 days | `CANVAS_ABSOLUTE_CAP_MS` |
+| Per-tenant active cap | 100 canvases | `CANVAS_MAX_CANVASES_PER_TENANT` |
+| Sweeper interval | 60 s | `CANVAS_SWEEPER_INTERVAL_MS` (0 to disable) |
+| Persistence | In-memory only | — (v1; restart drops all canvases) |
+
+The sweeper runs as an `unref`'d `setInterval` — does not keep the event loop alive on its own. Shutdown via `core.canvas.shutdown(ctx)` (called automatically from `ServerHandle.shutdown()`) stops the sweeper and tears down every active DuckDB instance.
+
+---
+
+## API
+
+### `canvas.acquire(maybeId, ctx, options?) → CanvasInstance`
+
+Resolves an existing canvas or creates a new one. Returns a {@link CanvasInstance} bound to `(canvasId, tenantId)`. Subsequent operations don't repeat them.
+
+```ts
+const instance = await ctx.core.canvas!.acquire(input.canvas_id, ctx);
+// instance.canvasId — surface to the agent
+// instance.isNew    — true on first call
+// instance.expiresAt — ISO 8601 after sliding extension
+```
+
+### `instance.registerTable(name, rows, options?)`
+
+Register an in-memory or async-iterable rowset as a canvas table.
+
+```ts
+await instance.registerTable('germplasm', rows);
+
+// Explicit schema for AsyncIterable (required — sniffer can't peek).
+await instance.registerTable('big_dataset', asyncRows, {
+  schema: [
+    { name: 'id', type: 'BIGINT' },
+    { name: 'label', type: 'VARCHAR', nullable: true },
+  ],
+});
+```
+
+**Schema inference** when `schema` is omitted: sniffer materializes the first 100 rows, unions JS-side types per column, and maps to DuckDB types. Fall-backs to `VARCHAR` for ambiguous unions (string mixed with numerics). Numeric widening: `INTEGER + DOUBLE → DOUBLE`, `INTEGER + BIGINT → BIGINT`. Column ordering follows first-appearance.
+
+### `instance.query(sql, options?)`
+
+Run SQL across registered tables. Returns at most `rowLimit` rows (default 10 000). For full result sets, pass `registerAs` — the result is materialized as a new canvas table; the response carries a `preview` slice plus the table reference.
+
+```ts
+const result = await instance.query(`
+  SELECT germplasmName, COUNT(*) AS n
+  FROM germplasm GROUP BY germplasmName ORDER BY n DESC
+`);
+
+// Materialize a join result for follow-up queries.
+const joined = await instance.query(`
+  SELECT g.germplasmName, o.value
+  FROM germplasm g JOIN observations o ON g.germplasmDbId = o.germplasmDbId
+`, { registerAs: 'g_with_obs', preview: 10 });
+// joined.tableName === 'g_with_obs'; joined.rows.length === 10; joined.rowCount === <full count>
+```
+
+`registerAs` rejects with `Conflict` if the target name already exists — drop it first.
+
+**Read-only enforcement** (three layers):
+1. Statement count (must be 1) via `extractStatements`.
+2. Statement type (must be `SELECT`) via `prepared.statementType`.
+3. EXPLAIN-plan walk against an allowlisted set of physical operators.
+
+Any layer's rejection throws `ValidationError` with a structured `data.reason`. File-reading scans (`READ_CSV`, `READ_PARQUET`, `READ_JSON`), DDL (`CREATE_*`, `DROP_*`, `ALTER_*`), DML (`INSERT`, `UPDATE`, `DELETE`), exports (`COPY_TO_FILE`), and utility statements (`PRAGMA`, `ATTACH`, `LOAD`, `SET`) are all rejected.
+
+### `instance.export(tableName, target, options?)`
+
+Export a canvas table. Path-based exports are sandboxed to `CANVAS_EXPORT_PATH` (default `./.canvas-exports`). Absolute paths and `..` traversal are rejected.
+
+```ts
+// Path target — written inside the sandbox.
+await instance.export('g_with_obs', { format: 'parquet', path: 'observations.parquet' });
+
+// Stream target — copied to a temp file in the sandbox, piped to the stream, unlinked.
+await instance.export('g_with_obs', { format: 'csv', stream: writableStream });
+```
+
+### `instance.describe(options?)` / `instance.drop(name)` / `instance.clear()`
+
+```ts
+const tables = await instance.describe();
+// [{ name: 'germplasm', rowCount: 200, columns: [...] }, ...]
+
+await instance.drop('staging_table');   // false if missing
+await instance.clear();                  // returns count dropped
+```
+
+### Cancellation
+
+`registerTable`, `query`, and `export` accept `options.signal: AbortSignal`. The provider opens a fresh DuckDB connection per query/export so `connection.interrupt()` cancels exactly the in-flight work without disturbing other ops on the same canvas.
+
+---
+
+## Result row shape
+
+Rows are returned via DuckDB's `getRowObjectsJson()` for JSON-safe serialization:
+
+| DuckDB type | JS type returned |
+|:------------|:-----------------|
+| `VARCHAR`, `JSON` | `string` |
+| `INTEGER`, `DOUBLE` | `number` |
+| `BIGINT` | `string` (lossless for values outside JS Number range) |
+| `BOOLEAN` | `boolean` |
+| `DATE`, `TIMESTAMP` | `string` |
+| `BLOB` | `string` (base64) |
+| `NULL` | `null` |
+
+If your tool surfaces row data via `structuredContent`, the JSON-safe shape flows through unchanged.
+
+---
+
+## Configuration
+
+| Env Var | `AppConfig` field | Default |
+|:--------|:-----------------|:--------|
+| `CANVAS_PROVIDER_TYPE` | `canvas.providerType` | `none` (also: `duckdb`) |
+| `CANVAS_DEFAULT_MEMORY_LIMIT_MB` | `canvas.defaultMemoryLimitMb` | `1024` |
+| `CANVAS_EXPORT_PATH` | `canvas.exportRootPath` | `./.canvas-exports` |
+| `CANVAS_MAX_CANVASES_PER_TENANT` | `canvas.maxCanvasesPerTenant` | `100` |
+| `CANVAS_TTL_MS` | `canvas.ttlMs` | `86_400_000` (24 h) |
+| `CANVAS_ABSOLUTE_CAP_MS` | `canvas.absoluteCapMs` | `604_800_000` (7 d) |
+| `CANVAS_SWEEPER_INTERVAL_MS` | `canvas.sweeperIntervalMs` | `60_000` |
+| `CANVAS_DEFAULT_ROW_LIMIT` | `canvas.defaultRowLimit` | `10_000` |
+| `CANVAS_SCHEMA_SNIFF_ROWS` | `canvas.schemaSniffRows` | `100` |
+
+---
+
+## Consumer tool template
+
+```ts
+import { tool, z } from '@cyanheads/mcp-ts-core';
+
+export const fetchAndStage = tool('fetch_and_stage_germplasm', {
+  description: 'Fetch germplasm matching a query and stage it on a DataCanvas for follow-up SQL.',
+  input: z.object({
+    query: z.string().describe('Search query'),
+    canvas_id: z
+      .string()
+      .optional()
+      .describe(
+        'Optional 10-char canvas ID returned from a prior call. Omit on first call to start a fresh canvas; the response will include a new canvas_id you can pass to subsequent calls or share with another agent.',
+      ),
+  }),
+  output: z.object({
+    canvas_id: z.string().describe('Canvas ID — pass to subsequent tool calls'),
+    is_new_canvas: z.boolean().describe('True if a new canvas was created'),
+    table_name: z.string().describe('Canvas table where rows were registered'),
+    row_count: z.number().describe('Rows registered'),
+    expires_at: z.string().describe('ISO 8601 expiry after sliding 24h window'),
+  }),
+  async handler(input, ctx) {
+    const canvas = ctx.core.canvas;
+    if (!canvas) {
+      throw new Error('DataCanvas is not enabled. Set CANVAS_PROVIDER_TYPE=duckdb.');
+    }
+    const instance = await canvas.acquire(input.canvas_id, ctx);
+    const rows = await fetchGermplasm(input.query);
+    const tableInfo = await instance.registerTable('germplasm', rows);
+    return {
+      canvas_id: instance.canvasId,
+      is_new_canvas: instance.isNew,
+      table_name: tableInfo.tableName,
+      row_count: tableInfo.rowCount,
+      expires_at: instance.expiresAt,
+    };
+  },
+});
+```
+
+---
+
+## Trade-offs
+
+- **DuckDB only in v1.** Polars/SQLite/DataFusion don't fit the "agent writes ad-hoc SQL across N registered tables" shape.
+- **In-memory only.** Server restart drops all canvases. For public-data servers, restart is rare and re-fetching upstream data is cheap. Disk persistence is a v2 concern.
+- **Single process.** Tokens issued by one process are not portable to another. Multi-process distributed canvases are out of scope.
+- **Read-only relative to upstream.** Canvas mutations (register, drop, clear, query+registerAs) all stay behind typed methods. Arbitrary SQL cannot mutate.
+- **No OTel in v1.** Canvas operations are not instrumented at the framework level. Add manually via `ctx.log` if needed.
+
+---
+
+## Platform support
+
+| Platform | Status |
+|:---------|:-------|
+| Linux x64 / arm64 | Supported |
+| macOS x64 / arm64 | Supported |
+| Windows x64 | Supported |
+| Windows arm64 | **Not supported** (DuckDB upstream limitation) |
+| Cloudflare Workers | **Not supported** — fail-closed at init time |
+
+---
+
+## Related skills
+
+- `add-tool` — scaffold a new MCP tool definition (use the canvas template above)
+- `api-config` — full env var reference
+- `api-workers` — Worker fail-closed behavior

package/skills/api-config/SKILL.md

@@ -99,6 +99,24 @@ Activated when `OAUTH_PROXY_AUTHORIZATION_URL` or `OAUTH_PROXY_TOKEN_URL` is set
 | `STORAGE_PROVIDER_TYPE` | `storage.providerType` | `in-memory` | `in-memory` \| `filesystem` \| `supabase` \| `cloudflare-r2` \| `cloudflare-kv` \| `cloudflare-d1`; aliases: `mem`, `fs` |
 | `STORAGE_FILESYSTEM_PATH` | `storage.filesystemPath` | `./.storage` | Used only when `providerType` is `filesystem` |
 
+---
+
+### Canvas (DataCanvas primitive — Tier 3, optional peer dep `@duckdb/node-api`)
+
+| Env Var | `AppConfig` field | Default | Notes |
+|:--------|:-----------------|:--------|:------|
+| `CANVAS_PROVIDER_TYPE` | `canvas.providerType` | `none` | `none` \| `duckdb`. Set to `duckdb` to enable `core.canvas`. Fails closed on Cloudflare Workers (DuckDB has no V8-isolate build). |
+| `CANVAS_DEFAULT_MEMORY_LIMIT_MB` | `canvas.defaultMemoryLimitMb` | `1024` | Per-canvas DuckDB `memory_limit` PRAGMA value, in MB. |
+| `CANVAS_EXPORT_PATH` | `canvas.exportRootPath` | `./.canvas-exports` | Sandbox root for path-targeted exports. Absolute paths and `..` traversal are rejected. |
+| `CANVAS_MAX_CANVASES_PER_TENANT` | `canvas.maxCanvasesPerTenant` | `100` | Active canvas cap per tenant; throws `RateLimited` when exceeded. |
+| `CANVAS_TTL_MS` | `canvas.ttlMs` | `86400000` | Sliding TTL (24 h). Every operation extends the expiry. |
+| `CANVAS_ABSOLUTE_CAP_MS` | `canvas.absoluteCapMs` | `604800000` | Absolute cap from creation (7 d). Sliding window clamps to this. |
+| `CANVAS_SWEEPER_INTERVAL_MS` | `canvas.sweeperIntervalMs` | `60000` | Background sweep interval. Set to `0` to disable. |
+| `CANVAS_DEFAULT_ROW_LIMIT` | `canvas.defaultRowLimit` | `10000` | Default cap on rows materialized into a query response. |
+| `CANVAS_SCHEMA_SNIFF_ROWS` | `canvas.schemaSniffRows` | `100` | Rows to materialize for schema inference when `schema` is omitted. |
+
+**Platform support:** Linux/macOS/Windows × x64 supported, Linux/macOS arm64 supported. Windows arm64 unsupported (DuckDB upstream). See `api-canvas` skill for the full DataCanvas reference.
+
 #### Supabase (optional sub-object)
 
 Activated when both `SUPABASE_URL` and `SUPABASE_ANON_KEY` are set.

package/skills/api-workers/SKILL.md

@@ -171,3 +171,9 @@ export function getServerConfig() {
 **`in-memory` storage is volatile.** Data stored with the `in-memory` provider is lost between cold starts and is not shared across Worker instances. Use `cloudflare-kv`, `cloudflare-r2`, or `cloudflare-d1` for any state that must persist or be shared.
 
 **Node-only utilities throw in Workers.** `scheduler` (`node-cron`), `sanitizePath` (fs-based), and `filesystem` storage provider all throw `ConfigurationError` when called from a Worker. Guard with `runtimeCaps.isNode` or avoid entirely.
+
+**DataCanvas is unavailable in Workers.** DuckDB has no V8-isolate build, so `core.canvas` is always `undefined` on Workers. Setting `CANVAS_PROVIDER_TYPE=duckdb` (the only non-default value) in `wrangler.toml` triggers a fail-closed `ConfigurationError` at init time:
+
+> `DuckDB canvas requires Node.js or Bun. Set CANVAS_PROVIDER_TYPE=none or omit it for Cloudflare Workers deployment.`
+
+Leave the env unset (or set to `none`) for Worker deployments. Tools that conditionally use canvas should check `if (!ctx.core.canvas) { ... }` and surface a clear "feature unavailable on this deployment" message. See `api-canvas` for the full DataCanvas reference.

package/skills/design-mcp-server/SKILL.md

@@ -408,6 +408,8 @@ Skip for purely data/action-oriented servers.
 
 **Server-as-service.** When the server IS the source of truth (knowledge graph, in-memory task tracker, local scratchpad, embedded inference wrapper), the resilience table below doesn't apply — there's no upstream to retry. The design questions shift to state management: what's tenant-scoped vs. global, what TTLs apply, what survives a restart, what the storage backend is. Plan persistence via `ctx.state` for tenant-scoped KV (auto-namespaced by `tenantId`), or use a `StorageService` provider directly when data must cross tenants. Service init still happens in `setup()`, accessed via `getMyService()` at request time. Calls within the server are local and synchronous-ish — the API-efficiency table below also doesn't apply.
 
+**Tabular API servers: DataCanvas is one option.** For servers that fetch tabular data and want to expose a SQL/analytical workspace — register tables, run cross-table queries, export results — the framework's optional `DataCanvas` primitive (Tier 3, opt-in via `CANVAS_PROVIDER_TYPE=duckdb`) handles lifecycle, ID generation, eviction, and export wiring so you don't design your own. If you opt in, surface `canvas_id` as an optional input on register/query/export tools; the framework mints on omit and resolves on match. Tools access it via `ctx.core.canvas?` (undefined when disabled or running on Workers — DuckDB has no V8-isolate build). See `api-canvas` for the full reference.
+
 For services wrapping external APIs, plan the resilience layer.
 
 | Concern | Decision |
@@ -551,4 +553,5 @@ Items without an `If …:` prefix apply to every design. Conditional items only
 - [ ] **If the server exposes resources:** URIs use `{param}` templates, pagination planned for large lists
 - [ ] **If the server has external deps or shared state:** service layer planned (or explicitly skipped with reasoning)
 - [ ] **If services wrap external APIs:** resilience planned (retry boundary, backoff, parse classification)
+- [ ] **If exposing a SQL/analytical workspace over tabular data is in scope:** DataCanvas considered (`api-canvas` skill) as one option before designing custom analytical state — register / query / export tools accepting an optional `canvas_id`, with `ctx.core.canvas?` reads
 - [ ] **If the server needs runtime config:** env vars identified in `server-config.ts`

package/skills/report-issue-framework/SKILL.md

@@ -172,6 +172,7 @@ Every issue needs exactly one primary label. Stack secondary labels on top when
 | `performance` | Memory, CPU, latency, or resource usage |
 | `security` | Vulnerability, CVE, or hardening work |
 | `breaking-change` | Fix/feature will break public API; requires a major bump |
+| `surplus-token-idea` | Worth exploring when token budget allows |
 
 Combine labels: `--label "bug" --label "regression"`.
 

package/skills/report-issue-local/SKILL.md

@@ -158,6 +158,7 @@ Every issue needs exactly one primary label. Stack secondary labels on top when
 | `performance` | Memory, CPU, latency, or resource usage |
 | `security` | Vulnerability, CVE, or hardening work |
 | `breaking-change` | Change will break public API; requires a major bump |
+| `surplus-token-idea` | Worth exploring when token budget allows |
 
 Combine labels: `--label "bug" --label "regression"`.
 
@@ -168,6 +169,7 @@ gh label create regression --color e99695 --description "Worked before, broken a
 gh label create performance --color 5319e7 --description "Memory, CPU, latency, or resource usage"
 gh label create security --color b60205 --description "Vulnerability, CVE, or hardening work"
 gh label create breaking-change --color d93f0b --description "Change will break public API; requires a major bump"
+gh label create surplus-token-idea --color FF10F0 --description "Worth exploring when token budget allows"
 ```
 
 ### Attaching logs or large output

package/skills/security-pass/SKILL.md

@@ -54,6 +54,12 @@ Note: tool / resource / prompt counts, auth mode, storage provider, upstream API
 - Any unauthenticated routes (`/healthz`, `/sse`, metadata endpoints) — do they leak tool lists or tenant hints?
 - MCP Authorization spec: if implemented, PKCE enforced, token audience (`aud`) checked, resource indicators used
 
+**If `CANVAS_PROVIDER_TYPE=duckdb` is set**, also capture:
+
+- Auth mode — canvas in `MCP_AUTH_MODE=none` collapses the composite `(tenantId, canvasId)` scope to `('default', canvasId)`, where the ID is the only differentiator
+- `CANVAS_MAX_CANVASES_PER_TENANT`, `CANVAS_TTL_MS`, `CANVAS_ABSOLUTE_CAP_MS`, `CANVAS_EXPORT_PATH` values
+- Whether external rate limiting (CDN, reverse proxy, WAF) fronts the deployment — required to keep the ~10¹⁸ canvasId keyspace operationally infeasible to brute-force
+
 Use `TaskCreate` — one task per axis. Mark complete as you go.
 
 **Run `fuzzTool` in parallel.** `@cyanheads/mcp-ts-core/testing/fuzz` catches crashes, memory leaks, and prototype pollution automatically on each tool — start it now so results are ready when you reach Axis 5.
@@ -249,6 +255,23 @@ grep -rn "JSON.parse\b" src/
 
 **Smell:** `while (cursor) { results.push(...); cursor = next; }` with no max count. Or: `JSON.parse(await req.text())` with no `Content-Length` check upstream.
 
+#### Axis 9 — Canvas (only if `CANVAS_PROVIDER_TYPE=duckdb`)
+
+DataCanvas is opt-in and deliberately trades isolation for cross-agent token-shareable working sets — designed for public-data tabular servers (BrAPI, OpenAlex, etc.) where session-pinning isn't desired. The trade only holds when the deployment matches that assumption. Skip this axis entirely when canvas is disabled (`CANVAS_PROVIDER_TYPE=none`, the default).
+
+**Look in:** `src/config/server-config.ts`, every tool reading `ctx.core.canvas?`, deployment config (wrangler / Dockerfile / proxy).
+
+**Check:**
+
+- Data registered on canvases is **already public** or already-shared-out-of-band. The composite `(tenantId, canvasId)` scope collapses to `('default', canvasId)` in `MCP_AUTH_MODE=none` — anyone with the `canvasId` attaches.
+- External rate limiting (CDN, reverse proxy, WAF) fronts the deployment so the ~10¹⁸ keyspace can't be brute-forced. Without it, the entropy assumption breaks and discovery becomes feasible.
+- `CANVAS_MAX_CANVASES_PER_TENANT` sized for the memory budget — default 100 is the floor; raising it lets a single tenant exhaust memory faster.
+- `CANVAS_TTL_MS` / `CANVAS_ABSOLUTE_CAP_MS` not absurdly long. Defaults (24 h sliding / 7 d absolute) are reasonable; longer widens the window an unreferenced `canvasId` stays guessable.
+- `CANVAS_EXPORT_PATH` doesn't point into a shared mount, the repo, or a directory another service serves from. The path-sandbox blocks `..` traversal but doesn't prevent the configured root from being a bad choice.
+- Axis 1 (description templating from canvas-supplied content), Axis 5 (no parallel service runs raw SQL outside the canvas API and bypasses `assertReadOnlyQuery`), and Axis 7 (errors from canvas operations don't leak the failed SQL string back through `McpError.data`) all apply.
+
+**Smell:** `MCP_AUTH_MODE=none` deployment registering per-user data (recent activity, account state, cart contents) onto a canvas. Or: `CANVAS_EXPORT_PATH=/srv/static` with a static file server pointing at the same root.
+
 ### 3. Quick sanity pass
 
 Fast, sometimes high-leverage. Outside the eight axes.
@@ -320,5 +343,6 @@ End with:
 - [ ] Axis 6 — tenant isolation: module-scope state swept
 - [ ] Axis 7 — leakage back: errors / outputs / `ctx.log` / `console.*` / telemetry / constant-time comparisons
 - [ ] Axis 8 — resource bounds on loops / retries / pagination / parse size+depth / per-tenant rate
+- [ ] **If `CANVAS_PROVIDER_TYPE=duckdb`:** Axis 9 — public-data assumption holds, external rate limiting in place, max-canvases-per-tenant + TTLs sized for the deployment, `CANVAS_EXPORT_PATH` doesn't escape into shared / served paths, `assertReadOnlyQuery` is the only SQL path
 - [ ] Quick sanity pass: `bun audit`, lifecycle scripts, `.env.example`, config validation, new-dep provenance
 - [ ] Report: summary → grouped findings → numbered options

package/templates/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -13,6 +13,7 @@ body:
         - `performance` — memory, CPU, latency, or resource usage
         - `security` — vulnerability, CVE, or hardening work
         - `breaking-change` — fix will break public API
+        - `surplus-token-idea` — worth exploring when token budget allows
 
         If a label doesn't exist in this repo yet, create it once: `gh label create <name>`.
 

package/templates/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -10,6 +10,7 @@ body:
         - `performance` — improves memory, CPU, latency, or resource usage
         - `security` — hardens the security posture
         - `breaking-change` — will break public API; requires a major bump
+        - `surplus-token-idea` — worth exploring when token budget allows
 
         If a label doesn't exist in this repo yet, create it once: `gh label create <name>`.