v2: thermo-cleanup rewrite (supersedes main/v1)

.agents/skills/chat-sdk/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: chat-sdk
+description: Build multi-platform chat bots with Chat SDK (`chat` npm package). Use when developers want to build a Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, or WhatsApp bot, handle mentions, direct messages, subscribed threads, reactions, slash commands, cards, modals, files, or AI streaming, set up webhook routes or multi-adapter bots, send rich cards or streamed AI responses to chat platforms, or build a custom adapter or state adapter.
+---
+
+# Chat SDK
+
+Unified TypeScript SDK for building chat bots across Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, and WhatsApp. Write bot logic once, deploy everywhere.
+
+## Start with published sources
+
+When Chat SDK is installed in a user project, inspect the published files that ship in `node_modules`:
+
+```
+node_modules/chat/docs/                    # bundled docs
+node_modules/chat/dist/index.d.ts          # core API types
+node_modules/chat/dist/adapters/index.d.ts # static adapter catalog types
+node_modules/chat/dist/jsx-runtime.d.ts    # JSX runtime types
+node_modules/chat/docs/contributing/       # adapter-authoring docs
+node_modules/chat/resources/guides/        # framework/platform guides (markdown)
+node_modules/chat/resources/templates.json # starter templates (title, description, href)
+```
+
+If one of the paths below does not exist, that package is not installed in the project yet.
+
+Read these before writing code:
+- `node_modules/chat/docs/getting-started.mdx` — install and setup
+- `node_modules/chat/docs/usage.mdx` — `Chat` config and lifecycle
+- `node_modules/chat/docs/handling-events.mdx` — event routing and handlers
+- `node_modules/chat/docs/threads-messages-channels.mdx` — thread/channel/message model
+- `node_modules/chat/docs/posting-messages.mdx` — post, edit, delete, schedule
+- `node_modules/chat/docs/streaming.mdx` — AI SDK integration and streaming semantics
+- `node_modules/chat/docs/cards.mdx` — JSX cards
+- `node_modules/chat/docs/actions.mdx` — button/select interactions
+- `node_modules/chat/docs/modals.mdx` — modal submit/close flows
+- `node_modules/chat/docs/slash-commands.mdx` — slash command routing
+- `node_modules/chat/docs/direct-messages.mdx` — DM behavior and `openDM()`
+- `node_modules/chat/docs/files.mdx` — attachments/uploads
+- `node_modules/chat/docs/state-adapters.mdx` — persistence, locking, dedupe
+- `node_modules/chat/docs/adapters.mdx` — cross-platform feature matrix
+- `node_modules/chat/docs/api/chat.mdx` — exact `Chat` API
+- `node_modules/chat/docs/api/thread.mdx` — exact `Thread` API
+- `node_modules/chat/docs/api/message.mdx` — exact `Message` API
+- `node_modules/chat/docs/api/modals.mdx` — modal element and event details
+
+For the specific adapter or state package you are using, inspect that installed package's `dist/index.d.ts` export surface in `node_modules`.
+
+## Adapter catalog subpath
+
+Chat SDK exposes a zero-dependency static catalog at `chat/adapters`. Agents can import `ADAPTERS`, `ADAPTER_NAMES`, `getAdapter`, `isAdapterSlug`, `listEnvVars`, `getSecretEnvVars`, and metadata types like `CatalogAdapter` and `AdapterSlug` from this subpath without importing any adapter implementation package.
+
+Use it for:
+- Listing official and vendor-official adapter slugs, names, npm packages, groups, and platform vs state types.
+- Building setup or onboarding flows that need package names, peer dependencies, and install guidance before any adapter is installed.
+- Discovering required, optional, and credential-mode environment variables for an adapter, including which variables are secrets.
+- Keeping vendor-official adapter docs and metadata aligned with the catalog when adding or updating a listed adapter.
+
+## Available resources
+
+<!-- RESOURCES:START -->
+
+### Guides
+
+- `node_modules/chat/resources/guides/how-to-build-an-ai-agent-for-slack-with-chat-sdk-and-ai-sdk.md` — Build a Slack AI agent using Chat SDK, AI SDK's ToolLoopAgent, and Vercel AI Gateway. Covers project setup, tool definitions, streaming responses, deployment to Vercel, and scaling tool selection with toolpick.
+- `node_modules/chat/resources/guides/human-in-the-loop-with-chat-sdk-and-workflow-sdk.md` — Pause durable workflows on Slack approval cards using Chat SDK and Workflow SDK. Uses createWebhook to suspend workflows until a button click, with patterns for multi-stage approvals, timeouts via durable sleep, and approver validation.
+- `node_modules/chat/resources/guides/liveblocks-chat-sdk-ai-sdk.md` — Build an AI agent that replies to @-mentions in Liveblocks comment threads with streamed responses and tool calling. Uses Chat SDK, the Liveblocks adapter, AI SDK's ToolLoopAgent, and Redis for thread subscriptions and distributed locking.
+- `node_modules/chat/resources/guides/slack-bot-vercel-blob.md` — Build a Slack bot that lists, reads, uploads, and deletes files in Vercel Blob through tool calls. Uses Chat SDK, AI SDK's ToolLoopAgent, and Files SDK's createFileTools factory with approval-gated write tools and a read-only mode.
+- `node_modules/chat/resources/guides/run-and-track-deploys-from-slack.md` — Build a Slack deploy bot with Chat SDK and Vercel Workflow. Dispatch GitHub Actions from a slash command, gate production behind approval, poll for completion, and notify Linear and GitHub when the run finishes.
+- `node_modules/chat/resources/guides/triage-form-submissions-with-chat-sdk.md` — Build a Slack bot that triages form submissions with interactive cards. Forward, edit, or mark as spam without leaving Slack. Built with Chat SDK, Hono, and Resend.
+- `node_modules/chat/resources/guides/how-to-build-a-slack-bot-with-next-js-and-redis.md` — This guide walks through building a Slack bot with Next.js, covering project setup, Slack app configuration, event handling, interactive features, and deployment.
+- `node_modules/chat/resources/guides/create-a-discord-support-bot-with-nuxt-and-redis.md` — This guide walks through building a Discord support bot with Nuxt, covering project setup, Discord app configuration, Gateway forwarding, AI-powered responses, and deployment.
+- `node_modules/chat/resources/guides/ship-a-github-code-review-bot-with-hono-and-redis.md` — This guide walks through building a GitHub bot that reviews pull requests on demand. When a user @mentions the bot on a PR, Chat SDK picks up the mention, spins up a Vercel Sandbox with the repo cloned, and uses AI SDK to analyze the diff.
+
+### Templates
+
+Listed in `node_modules/chat/resources/templates.json`:
+
+- **Chat SDK Liveblocks Bot** — Build a bot that you can engage with inside Liveblocks. (https://vercel.com/templates/next.js/chat-sdk-liveblocks-bot)
+- **Durable iMessage Agent** — Durable iMessage agent powered by the Sendblue adapter. (https://vercel.com/templates/nitro/durable-imessage-ai-agent)
+- **Knowledge Agent** — Open source file-system and knowledge based agent template. Build AI agents that stay up to date with your knowledge base. (https://vercel.com/templates/nuxt/chat-sdk-knowledge-agent)
+- **Community Agent** — Open source AI-powered Slack community management bot with a built-in Next.js admin panel. Uses Chat SDK, AI SDK, and Vercel Workflow. (https://vercel.com/templates/next.js/chat-sdk-community-agent)
+
+<!-- RESOURCES:END -->
+
+## Quick start
+
+```typescript
+import { Chat } from "chat";
+import { createSlackAdapter } from "@chat-adapter/slack";
+import { createRedisState } from "@chat-adapter/state-redis";
+
+const bot = new Chat({
+  userName: "mybot",
+  adapters: {
+    slack: createSlackAdapter(),
+  },
+  state: createRedisState(),
+  dedupeTtlMs: 600_000,
+});
+
+bot.onNewMention(async (thread) => {
+  await thread.subscribe();
+  await thread.post("Hello! I'm listening to this thread.");
+});
+
+bot.onSubscribedMessage(async (thread, message) => {
+  await thread.post(`You said: ${message.text}`);
+});
+```
+
+## Core concepts
+
+- **Chat** — main entry point; coordinates adapters, routing, locks, and state
+- **Adapters** — platform-specific integrations for Slack, Teams, Google Chat, Discord, Telegram, GitHub, Linear, and WhatsApp
+- **State adapters** — persistence for subscriptions, locks, dedupe, and thread state
+- **Thread** — conversation context with `post()`, `stream()`, `subscribe()`, `setState()`, `startTyping()`
+- **Message** — normalized content with `text`, `formatted`, attachments, author info, and platform `raw`
+- **Channel** — container for threads and top-level posts
+
+## Event handlers
+
+| Handler | Trigger |
+|---------|---------|
+| `onNewMention` | Bot @-mentioned in an unsubscribed thread |
+| `onDirectMessage` | New DM in an unsubscribed DM thread |
+| `onSubscribedMessage` | Any message in a subscribed thread |
+| `onNewMessage(regex)` | Regex match in an unsubscribed thread |
+| `onReaction(emojis?)` | Emoji added or removed |
+| `onAction(actionIds?)` | Button clicks and select/radio interactions |
+| `onModalSubmit(callbackId?)` | Modal form submitted |
+| `onModalClose(callbackId?)` | Modal dismissed/cancelled |
+| `onSlashCommand(commands?)` | Slash command invocation |
+| `onAssistantThreadStarted` | Slack assistant thread opened |
+| `onAssistantContextChanged` | Slack assistant context changed |
+| `onAppHomeOpened` | Slack App Home opened |
+| `onMemberJoinedChannel` | Slack member joined channel event |
+
+Read `node_modules/chat/docs/handling-events.mdx`, `node_modules/chat/docs/actions.mdx`, `node_modules/chat/docs/modals.mdx`, and `node_modules/chat/docs/slash-commands.mdx` before wiring handlers. `onDirectMessage` behavior is documented in `node_modules/chat/docs/direct-messages.mdx`.
+
+## Streaming
+
+Pass any `AsyncIterable<string>` to `thread.post()`. For AI SDK, prefer `result.fullStream` over `result.textStream` when available so step boundaries are preserved.
+
+```typescript
+import { ToolLoopAgent } from "ai";
+
+const agent = new ToolLoopAgent({ model: "anthropic/claude-4.5-sonnet" });
+
+bot.onNewMention(async (thread, message) => {
+  const result = await agent.stream({ prompt: message.text });
+  await thread.post(result.fullStream);
+});
+```
+
+Key details:
+- `streamingUpdateIntervalMs` controls post+edit fallback cadence
+- `fallbackStreamingPlaceholderText` defaults to `"..."`; set `null` to disable
+- Structured `StreamChunk` support is Slack-only; other adapters ignore non-text chunks
+
+## Cards and modals (JSX)
+
+Set `jsxImportSource: "chat"` in `tsconfig.json`.
+
+Card components:
+- `Card`, `CardText`, `Section`, `Fields`, `Field`, `Button`, `CardLink`, `LinkButton`, `Actions`, `Select`, `SelectOption`, `RadioSelect`, `Table`, `Image`, `Divider`
+
+Modal components:
+- `Modal`, `TextInput`, `Select`, `SelectOption`, `RadioSelect`
+
+`Button` and `Modal` accept a `callbackUrl` prop — when triggered, the SDK POSTs the action payload to that URL in addition to firing any `onAction` / `onModalSubmit` handler. Use this for webhook-based workflow flows. See `node_modules/chat/docs/actions.mdx` and `node_modules/chat/docs/modals.mdx`.
+
+```tsx
+await thread.post(
+  <Card title="Order #1234">
+    <CardText>Your order has been received.</CardText>
+    <Actions>
+      <Button id="approve" style="primary">Approve</Button>
+      <Button id="reject" style="danger">Reject</Button>
+    </Actions>
+  </Card>
+);
+```
+
+## Adapter inventory
+
+See [chat-sdk.dev/adapters](https://chat-sdk.dev/adapters) for the current list of official, vendor-official, and community adapters, including package names and authors. For the exact factory function and config types of an installed adapter, inspect its `dist/index.d.ts` in `node_modules`.
+
+## Building a custom adapter
+
+Read these published docs first:
+- `node_modules/chat/docs/contributing/building.mdx`
+- `node_modules/chat/docs/contributing/testing.mdx`
+- `node_modules/chat/docs/contributing/publishing.mdx`
+
+Also inspect:
+- `node_modules/chat/dist/index.d.ts` — `Adapter` and related interfaces
+- `node_modules/@chat-adapter/shared/dist/index.d.ts` — shared errors and utilities
+- Installed official adapter `dist/index.d.ts` files — reference implementations for config and APIs
+
+A custom adapter needs request verification, webhook parsing, message/thread/channel operations, ID encoding/decoding, and a format converter. Use `BaseFormatConverter` from `chat` and shared utilities from `@chat-adapter/shared`.
+
+## Webhook setup
+
+Each registered adapter exposes `bot.webhooks.<name>`. Wire those directly to your HTTP framework routes. See `node_modules/chat/resources/guides/how-to-build-a-slack-bot-with-next-js-and-redis.md` and `node_modules/chat/resources/guides/create-a-discord-support-bot-with-nuxt-and-redis.md` for framework-specific route patterns.

.agents/skills/coding-best-practices/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: coding-best-practices
+description: >
+  Code quality rules for the Gorkie Slack bot. Use when reviewing files for
+  violations, auditing PRs, or deciding how to structure new code. Covers
+  TypeScript patterns, Slack modal conventions, and architecture rules specific
+  to this repo.
+---
+
+## How to use this skill
+
+Read the rules below, then read the target files and report every violation with:
+- File path and line numbers
+- Which rule is violated
+- Concrete suggested fix
+
+Only report real issues. If a file is clean, say so in one line.
+
+---
+
+## Rules
+
+### 1. Minimal interfaces
+Accept only what the callee uses. When an SDK type carries more than needed, export a smaller internal type and convert at the boundary.
+
+```ts
+// bad — callee must fabricate fake SDK objects
+toolsModal({ tools: ListToolsResult['tools'] })
+
+// good
+export type ToolEntry = { name: string; group: GroupSlug };
+toolsModal({ tools: ToolEntry[] })
+```
+
+### 2. No fabricated data
+Never construct fake objects (empty descriptions, synthetic annotations, placeholder schemas) to satisfy a type. The type is wrong — narrow it.
+
+### 3. Export shared type discriminants
+When multiple files check the same string literals (`'ro' | 'dt' | 'gn'`, `'allow' | 'ask' | 'block'`), export a named union from one canonical location. Never re-validate the same literals with inline comparisons across files.
+
+### 4. No large inline closures
+Async closures longer than ~20 lines inside object literals belong in named functions at module scope with explicit parameter types.
+
+```ts
+// bad
+tools[name] = { execute: async (input, opts) => { /* 100 lines */ } }
+
+// good
+tools[name] = { execute: wrapMCPToolExecute({ ctxId, server, stream, ... }) }
+```
+
+### 5. Nested metadata over flat parallel fields
+Fields that always move together should be nested.
+
+```ts
+// bad
+{ serverId: server.id, serverName: server.name, toolName }
+
+// good
+{ server: { id: server.id, name: server.name }, tool: { name: toolName } }
+```
+
+### 6. Slack private_metadata: minimal and Zod-parsed
+Only persist what cannot be re-derived from view state or a DB lookup. Always parse with Zod — never cast with `as`.
+
+```ts
+// bad
+const meta = JSON.parse(view.private_metadata || '{}') as SomeMeta;
+
+// good
+const meta = someMetaSchema.parse(JSON.parse(view.private_metadata || '{}'));
+```
+
+### 7. Don't scrape view state to reconstruct stored data
+If a handler reads `body.view.state.values` for every element just to rebuild a structure for re-rendering, that structure should have been in `private_metadata`. Only scrape view state for values the user actively changed in this action.
+
+### 8. Always pass `hash` on mid-session `views.update`
+`block_actions` handlers must pass `hash: view.hash` to `client.views.update`. This prevents overwriting a view that a concurrent action already updated.
+
+### 9. Dict params
+Functions with more than one parameter take a single options object.
+
+```ts
+// bad
+logReply(ctxId, author, result, reason);
+// good
+logReply({ ctxId, author, result, reason });
+```
+
+### 10. Inline over extract (single-use)
+Only extract to a named function when called in multiple places or genuinely complex. A helper called once is worse than the inline code.
+
+### 11. No type casts
+Prefer schema parsing or narrower signatures over `as`. A cast is acceptable only at a real validated external boundary.
+
+### 12. Config for tuneable values
+Magic numbers and strings that could change per deployment belong in `apps/bot/src/config.ts`.
+
+---
+
+## Also check
+
+- Missing `await` on promises (fire-and-forget is only acceptable for intentional background work)
+- Empty or swallowed `catch` blocks
+- Ownership checks before DB mutations (user should only affect their own resources)
+- `views.update` without `hash` in action handlers (race condition)

.agents/skills/grill-with-docs/ADR-FORMAT.md

@@ -0,0 +1,47 @@
+# ADR Format
+
+ADRs live in `docs/adr/` and use sequential numbering: `0001-slug.md`, `0002-slug.md`, etc.
+
+Create the `docs/adr/` directory lazily — only when the first ADR is needed.
+
+## Template
+
+```md
+# {Short title of the decision}
+
+{1-3 sentences: what's the context, what did we decide, and why.}
+```
+
+That's it. An ADR can be a single paragraph. The value is in recording *that* a decision was made and *why* — not in filling out sections.
+
+## Optional sections
+
+Only include these when they add genuine value. Most ADRs won't need them.
+
+- **Status** frontmatter (`proposed | accepted | deprecated | superseded by ADR-NNNN`) — useful when decisions are revisited
+- **Considered Options** — only when the rejected alternatives are worth remembering
+- **Consequences** — only when non-obvious downstream effects need to be called out
+
+## Numbering
+
+Scan `docs/adr/` for the highest existing number and increment by one.
+
+## When to offer an ADR
+
+All three of these must be true:
+
+1. **Hard to reverse** — the cost of changing your mind later is meaningful
+2. **Surprising without context** — a future reader will look at the code and wonder "why on earth did they do it this way?"
+3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons
+
+If a decision is easy to reverse, skip it — you'll just reverse it. If it's not surprising, nobody will wonder why. If there was no real alternative, there's nothing to record beyond "we did the obvious thing."
+
+### What qualifies
+
+- **Architectural shape.** "We're using a monorepo." "The write model is event-sourced, the read model is projected into Postgres."
+- **Integration patterns between contexts.** "Ordering and Billing communicate via domain events, not synchronous HTTP."
+- **Technology choices that carry lock-in.** Database, message bus, auth provider, deployment target. Not every library — just the ones that would take a quarter to swap out.
+- **Boundary and scope decisions.** "Customer data is owned by the Customer context; other contexts reference it by ID only." The explicit no-s are as valuable as the yes-s.
+- **Deliberate deviations from the obvious path.** "We're using manual SQL instead of an ORM because X." Anything where a reasonable reader would assume the opposite. These stop the next engineer from "fixing" something that was deliberate.
+- **Constraints not visible in the code.** "We can't use AWS because of compliance requirements." "Response times must be under 200ms because of the partner API contract."
+- **Rejected alternatives when the rejection is non-obvious.** If you considered GraphQL and picked REST for subtle reasons, record it — otherwise someone will suggest GraphQL again in six months.