Repository navigation
Rewrite framework docs to showcase power and developer experience - #5
Conversation
The existing docs read like internal specs — accurate but uninspiring. This rewrites the main README, architecture overview, and four package READMEs to lead with working code examples, convey the developer experience, and make the framework's value proposition immediately clear. Key changes: - README.md: Lead with a complete code example, show the full-stack DX (server, client, React, testing), replace bullet-point feature lists with narrative explanations of what you get - docs/architecture/overview.md: Add "the idea in 30 seconds" section with code, make abstractions concrete with usage context - packages/core/README.md: Show all four block kinds in action with real patterns (tools, history, rescue, routing) - packages/server/README.md: Lead with the 3-line API setup, organize around what you can do rather than what exists - packages/client/README.md: Show streaming and resume patterns, compare client variants in a table - packages/react/README.md: Lead with a complete chat UI example, explain the architecture (hooks wrap client, no transport in UI) https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
The docs site read like technical specs — accurate but uninspiring. This rewrites 13 files across the entire site to lead with narrative, show real code first, and make the framework's power immediately tangible. Landing page (index.tsx + CSS): - New hero: "Stop wiring. Start building." with a clear value prop - Rewritten feature cards with punchy titles and practical descriptions - Replaced single code preview with 4-step code showcase (Define, Serve, Render, Test) showing the full developer experience - Added CTA section at bottom - Gradient hero background, step numbers, responsive styles Config & intro: - New tagline: "Composable AI workflows for TypeScript. Blocks in. Streaming out." - Intro page opens with the problem, shows a complete code example, then walks through what you get and why each piece matters Concept pages (blocks, flows, actions, state, streaming, testing): - Every page now opens with a "why this matters" hook instead of jumping straight to definitions - Blocks page explains what the framework manages for each kind - Streaming page leads with "most frameworks bolt streaming on as an afterthought" contrast - Testing page opens with "LLMs aren't deterministic. But your tests should be." - State page opens with the real problem (state is messy in AI apps) Guides: - Quick start adds conversation history to the example and explains what the framework handles at each step - Building a chat app guide adds projections, better test examples, and explains the "why" alongside the "how" Blog: - Welcome post rewritten from placeholder to a real "Introducing Flow State Dev" announcement with the core idea, what's different, and current status Verified: `pnpm --filter docs build` passes cleanly. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
…APIs Weaves four key differentiators throughout the docs that were previously underrepresented: 1. Tools are blocks (including sequencers): A generator's tools array accepts any block, so a single tool call can trigger an entire multi-step pipeline. Added dedicated "Tools are blocks" section to blocks.md with concrete examples, updated feature cards, intro, and README. 2. Resources as hybrid memory/filesystem: Resources combine rich text content with structured atomic state — like files that carry metadata. Rewrote the resources section in state.md to lead with this model, updated intro and README descriptions. 3. Ecosystem by design: Blocks and flows are portable. The uniform contract and partial state schemas mean community blocks compose without adapters. Added "Blocks are portable" section to blocks.md, new "Built for an ecosystem" feature card and README section. 4. Flows are full APIs: Register a flow and get complete REST endpoints with zero route wiring. Added "Flows are full APIs" section to intro, new feature card on landing page, updated server code example to show multiple flows with route comments, updated README. Landing page now has 6 feature cards in a 3-column grid (was 4 in 2-column). Code showcase updated to show a research assistant with sequencer-as-tool and resource with content+metadata. Verified: pnpm --filter docs build passes cleanly. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 2ab6415839
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
…ment The session state snapshot route is GET /api/flows/sessions/:id/state, not /api/flows/:kind/sessions/:id/state. Fixed in the landing page server example and the intro page route listing. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
…tors docs Branding: - Stylize framework name as "flow-state.dev" throughout — site title, navbar, hero subtitle, meta description - Add .brandName CSS class: monospace font, bold, primary-light color to give the lowercase name visual distinction - URL changed to https://flow-state.dev - Copyright changed to Fixpoint Labs, LLC Projection example: - Replace messageCount projection (trivially computable client-side) with docList — a projection that derives a document list from a resource, showing the real value of projections - React example now shows a research assistant with a sidebar of documents derived from server-side resources - Test example updated to match: seeds resource state, asserts on tool_call items Tools messaging: - Reword "tools are blocks too" to "any block or sequence of blocks can be used as a tool" — clearer, less confusing - Updated in landing page (feature card + code comments), README, intro.md, and blocks.md concept page Block connectors: - Add "Connecting blocks with different shapes" section to blocks.md explaining how blocks with incompatible types work together - Covers sequencer connectors (the primary pattern), block-level connectInput/connectOutput, and why connectors matter for portability - Concrete examples: reshaping output for the next block, parallel with mixed connectors, adapting community blocks Verified: pnpm --filter docs build passes cleanly. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
The blog post now frames flow-state.dev as a framework for pushing the boundaries of AI agent architectures, not just making existing patterns easier. Emphasizes composable primitives for experimentation, building together as an ecosystem, and solid infrastructure for bold experiments. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c93a5c7561
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| const sessions = createSessionClient(); | ||
| import { createSessionClient } from "@flow-state-dev/client"; | ||
|
|
||
| const sessions = createSessionClient({ flowKind: "my-app", userId: "user_1" }); |
There was a problem hiding this comment.
Stop passing unsupported options to createSessionClient
This example calls createSessionClient({ flowKind, userId }), but the client API only accepts transport options (baseUrl/fetcher) in CreateSessionClientOptions (packages/client/src/session-client/sessions.ts). In TypeScript projects this copy-pasted snippet will fail type-checking, and it also suggests an incorrect mental model that session clients are flow/user-bound at construction time.
Useful? React with 👍 / 👎.
| generators: { "chat": mockGenerator({ script: [{ text: "Hi there!" }] }) }, | ||
| }); | ||
|
|
||
| expect(result.items).toContainItemOfType("message"); |
There was a problem hiding this comment.
Replace nonexistent test matcher in README example
The testing example uses expect(result.items).toContainItemOfType(...), but there is no matcher with that name in this repo’s testing utilities or Jest setup, so this onboarding snippet fails immediately when copied. Use the documented item query helpers (for example testItems(result.items).byType(...)) or a standard Jest assertion instead.
Useful? React with 👍 / 👎.
- Dark-first design with deep backgrounds, subtle radial gradients, and glassmorphism feature cards with hover effects - Pill-shaped buttons with glow on primary, glass on secondary - Proper mobile spacing (1.25-1.5rem padding), responsive text sizing down to 480px breakpoint, stacked buttons on small screens - Feature grid: 3-col → 2-col → 1-col responsive with glass cards - Tabbed code showcase (Define/Serve/Render/Test) instead of showing all 4 code blocks sequentially — much less scrolling on mobile - Subtle gradient dividers between sections - Frosted glass navbar in dark mode - Light theme fallbacks for all custom styles https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 15967b867c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| event: item.updated | ||
| data: { "item": { "type": "message", "role": "assistant", "status": "completed" } } |
There was a problem hiding this comment.
Replace nonexistent SSE event name in streaming example
The event sequence documents item.updated, but the runtime emits item.done for completion and the client parser only handles item.added/item.done (packages/core/src/items/events.ts, packages/client/src/stream-client/createSSEClient.ts). Anyone implementing custom stream handling from this example will subscribe to an event that is never sent and miss terminal item updates.
Useful? React with 👍 / 👎.
|
|
||
| **Resumable streaming out of the box.** Items stream over SSE as blocks execute. Disconnect mid-response? Reconnect with a sequence cursor and pick up exactly where you left off. No data loss. No duplicate events. | ||
|
|
||
| **Resources: hybrid memory and filesystem.** Each resource combines rich text content with structured atomic state — like files that carry metadata. An artifact can hold a document's full text alongside its title, tags, and timestamps. Scoped to sessions, users, or projects. Projections derive client-safe views — the *only* way to expose data. You can't accidentally leak internal state. |
There was a problem hiding this comment.
Stop claiming projections are the only client data path
This says projections are the only way to expose data to clients, but the session snapshot endpoint currently returns raw scope state (state.request/session/user/project) in addition to projections (packages/server/src/routes/http-handlers.ts, get_session_state response). That claim can lead developers to treat scope state as non-client-visible and accidentally place sensitive values there.
Useful? React with 👍 / 👎.
| }); | ||
|
|
||
| expect(result.items).toContainItemOfType("message"); | ||
| expect(result.items).toContainItemOfType("tool_call");`; |
There was a problem hiding this comment.
Use a valid output item type in landing-page test snippet
The snippet asserts for "tool_call", but OutputItem has no tool_call variant; tool-call details are represented under block_output.toolCall (packages/core/src/items/types.ts). A copied test based on this example cannot assert this type successfully and teaches an incorrect item taxonomy.
Useful? React with 👍 / 👎.
Blocks don't send outputs to the client — they emit typed items. Updated Define example to show ctx.emitComponent() with a handler that emits a named "report-card" component. Updated Render example to show FlowProvider with registered component renderers and how ItemRenderer resolves component items from the stream. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 01be582281
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| import { createFilesystemStores, createInMemoryStores } from "@flow-state-dev/server"; | ||
|
|
||
| // Production: filesystem (default) | ||
| // Default: filesystem persistence | ||
| const router = createFlowApiRouter({ registry }); |
There was a problem hiding this comment.
Import createFlowApiRouter in store configuration example
The store configuration snippet calls createFlowApiRouter(...) but the import only brings in createFilesystemStores/createInMemoryStores, so the copied example fails TypeScript/JS execution with an undefined identifier before users can try either store option. Please include createFlowApiRouter in this import so the example is runnable as shown.
Useful? React with 👍 / 👎.
| function App() { | ||
| return ( | ||
| <FlowProvider | ||
| config={{ baseUrl: "/api" }} |
There was a problem hiding this comment.
Replace unsupported FlowProvider config prop in example
FlowProvider does not accept a config prop (its public props are flowKind, sessionId, userId, baseUrl, and renderers), so this homepage example is not copy-pastable and will fail type-checking; it also omits flowKind/userId, which makes useFlow({ autoCreateSession: true }) fail when creating a session. Use the documented top-level props instead.
Useful? React with 👍 / 👎.
| 2. **Session** — Resolved from `sessionId` or created new. | ||
| 3. **User message** — If `userMessage` is defined, a user-role message item is emitted to the stream. | ||
| 4. **Execute** — The root block runs asynchronously. Items stream to the client as they're produced. | ||
| 5. **Complete** — Lifecycle hooks fire. The stream emits `request.completed` (or `request.errored`). |
There was a problem hiding this comment.
Use emitted request.failed event name in action lifecycle
The lifecycle description says the stream emits request.completed or request.errored, but RequestStatusEvent only includes request.in_progress, request.completed, request.incomplete, and request.failed (packages/core/src/items/events.ts). Readers implementing failure handling from this doc will subscribe to an event that is never sent and miss terminal failures.
Useful? React with 👍 / 👎.
Landing page Define tab now shows a sequencer with parallel steps, doUntil loop, background work, and rescue — not just .then() chains. Feature card calls out specific DSL methods by name. blocks.md sequencer section expanded from a single example to full coverage of all DSL capabilities: parallel, forEach, doUntil/doWhile, loopBack, work/waitForWork, branch, tap/tapIf, rescue, and map — each with code examples. Closes with a composed example showing how they combine into a single block. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: ed2ee16254
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| export default defineFlow({ | ||
| kind: "my-app", | ||
| actions: { | ||
| chat: { block: pipeline, userMessage: (i) => i.message }, |
There was a problem hiding this comment.
Add required inputSchema to README action example
This defineFlow snippet omits inputSchema for the chat action, but ActionConfig requires every action to declare one (packages/core/src/types/flow.ts), so copied TypeScript code will fail to type-check and won't reflect the actual action contract expected by the framework. Include the action schema here to keep the example runnable and aligned with the public API.
Useful? React with 👍 / 👎.
|
|
||
| user: { | ||
| stateSchema: z.object({ | ||
| preferences: z.object({ theme: z.string() }).default({}), |
There was a problem hiding this comment.
Use a valid default for required preferences.theme
This schema declares theme as required (z.string()) but sets .default({}), so the default value itself is invalid and will either fail TypeScript checking or throw when defaults are materialized at runtime. The example should use a default object that satisfies the schema (or make theme optional) so users can copy it without hitting an immediate validation/type error.
Useful? React with 👍 / 👎.
| expect(result.items).toContainEqual( | ||
| expect.objectContaining({ type: "message" }) | ||
| ); | ||
| expect(result.session.state.messageCount).toBe(1); |
There was a problem hiding this comment.
Assert against TestFlowResult fields that actually exist
testFlow returns status/requestId/output/error/items and does not expose session.state (packages/testing/src/test-utilities/types.ts), so this assertion is not valid for the documented API and will fail in typed usage. Replace it with assertions on emitted items or other fields that TestFlowResult actually provides.
Useful? React with 👍 / 👎.
| }, | ||
| }); | ||
|
|
||
| expect(result.items).toContainItemOfType("message"); |
There was a problem hiding this comment.
Replace unsupported toContainItemOfType matcher
The docs use toContainItemOfType, but this repository does not define that matcher in Jest setup or testing helpers, so the copied test fails immediately with a matcher-not-found error. Use testItems(...) helpers or a standard Jest assertion instead so the homepage example is executable.
Useful? React with 👍 / 👎.
The previous example had a handler wrapping a buildReport() function call, which goes against the framework principle that meaningful work should be expressed as blocks. Now analyze is a sequencer composing gatherEvidence and scoreFindings, with a tap that emits the report-card component to the UI as a side effect. https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
The existing docs read like internal specs — accurate but uninspiring.
This rewrites the main README, architecture overview, and four package
READMEs to lead with working code examples, convey the developer
experience, and make the framework's value proposition immediately clear.
Key changes:
(server, client, React, testing), replace bullet-point feature lists
with narrative explanations of what you get
with code, make abstractions concrete with usage context
real patterns (tools, history, rescue, routing)
around what you can do rather than what exists
compare client variants in a table
explain the architecture (hooks wrap client, no transport in UI)
https://claude.ai/code/session_01F9D1j5EPAQseYvXfyeNuwh