Skip to content

Rewrite framework docs to showcase power and developer experience - #5

Merged
jhoffner merged 16 commits into
mainfrom
claude/improve-framework-docs-iOzV0
Mar 1, 2026
Merged

jhoffner merged 16 commits into
mainfrom
claude/improve-framework-docs-iOzV0

Conversation

@jhoffner

Copy link
Copy Markdown
Collaborator

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 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
@vercel

vercel Bot commented Feb 28, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
flow-state-dev-docs Ready Ready Preview, Comment Mar 1, 2026 6:40pm
flow-state-dev-kitchen-sink Error Error Mar 1, 2026 6:40pm

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread apps/docs/docs/intro.md Resolved
…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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread packages/client/README.md Outdated
const sessions = createSessionClient();
import { createSessionClient } from "@flow-state-dev/client";

const sessions = createSessionClient({ flowKind: "my-app", userId: "user_1" });

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread README.md Outdated
generators: { "chat": mockGenerator({ script: [{ text: "Hi there!" }] }) },
});

expect(result.items).toContainItemOfType("message");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread apps/docs/docs/concepts/streaming.md Outdated
Comment on lines +30 to +31
event: item.updated
data: { "item": { "type": "message", "role": "assistant", "status": "completed" } }

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread README.md Outdated

**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.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread apps/docs/src/pages/index.tsx Outdated
});

expect(result.items).toContainItemOfType("message");
expect(result.items).toContainItemOfType("tool_call");`;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread packages/server/README.md
Comment on lines +32 to 35
import { createFilesystemStores, createInMemoryStores } from "@flow-state-dev/server";

// Production: filesystem (default)
// Default: filesystem persistence
const router = createFlowApiRouter({ registry });

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread apps/docs/src/pages/index.tsx Outdated
function App() {
return (
<FlowProvider
config={{ baseUrl: "/api" }}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread apps/docs/docs/concepts/actions.md Outdated
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`).

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment thread README.md
export default defineFlow({
kind: "my-app",
actions: {
chat: { block: pipeline, userMessage: (i) => i.message },

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread apps/docs/docs/concepts/flows.md Outdated

user: {
stateSchema: z.object({
preferences: z.object({ theme: z.string() }).default({}),

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread apps/docs/docs/concepts/testing.md Outdated
expect(result.items).toContainEqual(
expect.objectContaining({ type: "message" })
);
expect(result.session.state.messageCount).toBe(1);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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 👍 / 👎.

Comment thread apps/docs/src/pages/index.tsx Outdated
},
});

expect(result.items).toContainItemOfType("message");

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge 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
@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

This branch had an error being deployed

1 failed and 1 active deployments
Preview – flow-state-dev-kitchen-sink — e9a60973 Deployed Mar 1, 2026 by vercel[bot]
Preview – flow-state-dev-docs — e9a60973 Deployed Mar 1, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants