diff --git a/.claude/skills/doc-check/SKILL.md b/.claude/skills/doc-check/SKILL.md new file mode 100644 index 00000000..bc35c5a7 --- /dev/null +++ b/.claude/skills/doc-check/SKILL.md @@ -0,0 +1,102 @@ +--- +name: doc-check +description: Documentation update checklist. Run after API changes to find documentation that needs updating. Use for doc check, documentation review, docs update, API change docs. +allowed-tools: + - Read + - Grep + - Glob + - Bash(pnpm:*) + - Bash(node:*) + - Bash(git:*) +--- + +# Documentation Update Checklist + +After any API change, verify all documentation is in sync. This checklist is ordered by priority. + +## How to Use + +1. Identify what changed (new field, new method, changed signature, etc.) +2. Walk through each section below +3. Check only items relevant to the change scope (core, react, or both) +4. Mark items as done or N/A + +## 1. Package LLM Docs (bundled in npm) + +These are the primary references for AI coding agents. + +- [ ] `packages/durably/docs/llms.md` — Core API docs +- [ ] `packages/durably-react/docs/llms.md` — React hooks docs + +## 2. Website API Reference + +### Core API + +| File | Content | +| ------------------------------- | ------------------------------------------------------ | +| `website/api/index.md` | Quick reference / cheat sheet (covers ALL APIs) | +| `website/api/create-durably.md` | `createDurably()`, instance methods, types | +| `website/api/define-job.md` | `defineJob()`, job config | +| `website/api/step.md` | Step context (`step.run`, `step.progress`, `step.log`) | +| `website/api/events.md` | Event types and their fields | +| `website/api/http-handler.md` | `createDurablyHandler()`, request/response types | + +### React API + +| File | Content | +| -------------------------------------- | ---------------------------------------------- | +| `website/api/durably-react/index.md` | React hooks overview | +| `website/api/durably-react/browser.md` | Browser-mode hooks (`useJob`, `useRuns`, etc.) | +| `website/api/durably-react/client.md` | Client-mode hooks (server-connected) | +| `website/api/durably-react/types.md` | Shared type definitions | + +### Guides (check if examples use changed API) + +| File | Content | +| ---------------------------------- | ------------------------- | +| `website/guide/concepts.md` | Core concepts explanation | +| `website/guide/getting-started.md` | Getting started tutorial | +| `website/guide/csv-import.md` | CSV import example | +| `website/guide/background-sync.md` | Background sync example | +| `website/guide/offline-app.md` | Offline app example | + +## 3. Generated Files + +These are derived from package docs and must be regenerated: + +```bash +pnpm --filter durably-website generate:llms +``` + +- [ ] `website/public/llms.txt` — Concatenation of core + react `llms.md` + +## 4. Scope Guide + +Use this table to quickly determine which docs to check based on what changed: + +| Change Type | Docs to Check | +| -------------------------------- | ------------------------------------------------------------------------------------------ | +| New field on `Run` / `RunFilter` | llms.md (core), create-durably.md, index.md, http-handler.md, react browser.md + client.md | +| New event field | llms.md (core), events.md, index.md | +| New step method | llms.md (core), step.md, index.md | +| New trigger option | llms.md (core), index.md, http-handler.md, create-durably.md | +| React hook change | llms.md (react), browser.md, client.md, index.md (react section) | +| HTTP handler change | llms.md (core), http-handler.md, client.md | +| New config option | llms.md (core), create-durably.md, index.md | + +## 5. Common Oversights + +- **`website/api/index.md`** is a cheat sheet — it duplicates key info from other pages and is easy to forget +- **Event field additions** must be added to every event type comment block in `events.md` +- **Browser and Client mode** hooks often have parallel options tables — update both +- **Type definitions** in `website/api/durably-react/types.md` may need new type exports +- **`website/public/llms.txt`** is generated — don't edit directly, regenerate instead +- **Code examples** in guides may use the changed API — grep for the symbol name in `website/guide/` + +## 6. Verification + +```bash +pnpm format:fix +pnpm --filter durably-website generate:llms +pnpm validate +``` diff --git a/.claude/skills/release-check/SKILL.md b/.claude/skills/release-check/SKILL.md index 396abeb8..e5d097fd 100644 --- a/.claude/skills/release-check/SKILL.md +++ b/.claude/skills/release-check/SKILL.md @@ -32,12 +32,10 @@ Verify package integrity for API changes and spec updates. ### Core - [ ] `packages/durably/docs/llms.md` - LLM docs (bundled in npm) -- [ ] `docs/spec.md` - Core specification ### React - [ ] `packages/durably-react/docs/llms.md` - LLM docs (bundled in npm) -- [ ] `docs/spec-react.md` - React specification - [ ] `website/api/durably-react/index.md` - Overview - [ ] `website/api/durably-react/browser.md` - Browser hooks - [ ] `website/api/durably-react/client.md` - Client hooks @@ -95,12 +93,13 @@ Check `git status` for uncommitted changes. When React hooks should provide the same API in both Browser and Client modes: -| File | Mode | -| --------------------- | ------------- | -| `hooks/use-job.ts` | Browser mode | -| `client/use-job.ts` | Client mode | +| File | Mode | +| ------------------- | ------------ | +| `hooks/use-job.ts` | Browser mode | +| `client/use-job.ts` | Client mode | Ensure consistency in: + - Interface definitions - Return values - Options @@ -108,6 +107,7 @@ Ensure consistency in: ### Code Examples in Documentation Verify code examples in docs match actual API: + - Return value properties - Option parameters - Type definitions @@ -125,5 +125,6 @@ pnpm typecheck # Includes all examples ``` Key components to check: + - `dashboard.tsx` - useRuns, useRunActions - `*-progress.tsx` - useJob return values (status booleans) diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 06696994..00000000 --- a/AGENTS.md +++ /dev/null @@ -1,18 +0,0 @@ - -# OpenSpec Instructions - -These instructions are for AI assistants working in this project. - -Always open `@/openspec/AGENTS.md` when the request: -- Mentions planning or proposals (words like proposal, spec, change, plan) -- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work -- Sounds ambiguous and you need the authoritative spec before coding - -Use `@/openspec/AGENTS.md` to learn: -- How to create and apply change proposals -- Spec format and conventions -- Project structure and guidelines - -Keep this managed block so 'openspec update' can refresh the instructions. - - \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 8101f7fd..4cf19464 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,22 +1,3 @@ - -# OpenSpec Instructions - -These instructions are for AI assistants working in this project. - -Always open `@/openspec/AGENTS.md` when the request: -- Mentions planning or proposals (words like proposal, spec, change, plan) -- Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work -- Sounds ambiguous and you need the authoritative spec before coding - -Use `@/openspec/AGENTS.md` to learn: -- How to create and apply change proposals -- Spec format and conventions -- Project structure and guidelines - -Keep this managed block so 'openspec update' can refresh the instructions. - - - # CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. @@ -27,13 +8,12 @@ Durably is a step-oriented batch execution framework for Node.js and browsers. I ## Documentation -- `docs/spec.md` - Core specification -- `docs/spec-streaming.md` - Streaming extension for AI Agent workflows - `packages/durably/docs/llms.md` - LLM/AI agent documentation (bundled in npm package) ### LLM Documentation Maintenance When API changes are made, update `packages/durably/docs/llms.md` to keep it in sync. This file is: + - Bundled in the npm package for coding agents to read from `node_modules` - Symlinked to `website/public/llms.txt` for web access @@ -83,3 +63,4 @@ pnpm lint:fix # Fix lint issues ## Skills - **release-check** - Pre-release integrity check for API changes and spec updates (`.claude/skills/release-check/`) +- **doc-check** - Documentation update checklist after API changes (`.claude/skills/doc-check/`) diff --git a/examples/browser-react-router-spa/app/routes/_index.tsx b/examples/browser-react-router-spa/app/routes/_index.tsx index 574480ec..2767a266 100644 --- a/examples/browser-react-router-spa/app/routes/_index.tsx +++ b/examples/browser-react-router-spa/app/routes/_index.tsx @@ -34,7 +34,10 @@ export async function clientAction({ request }: { request: Request }) { if (intent === 'image') { const filename = formData.get('filename') as string const width = Number(formData.get('width')) - const run = await durably.jobs.processImage.trigger({ filename, width }) + const run = await durably.jobs.processImage.trigger( + { filename, width }, + { labels: { source: 'browser' } }, + ) return { intent: 'image', runId: run.id } } @@ -59,22 +62,22 @@ export default function Index() { return (
-
+

Durably - Browser-Only SPA

-

+

React Router v7 SPA mode with clientAction + Form

-
+
{/* Left: Job Trigger + Progress */}
{/* Job Selection */} -
-
+
+

Run Job

-
+