docs(agents): restructure site docs and remove workflow references

[zrosenbauer]

Summary

• Restructure documentation site layout
• Remove workflow references, replace with flow-agent terminology
• Add top-level docs (architecture, introduction, principles, quick-start)

Test plan

• Verify docs site builds correctly
• Check all internal links resolve

[changeset-bot]

🦋 Changeset detected

Latest commit: 63cb0d4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
funkai	Ready	Preview, Comment	Mar 24, 2026 8:40pm

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Added four new top-level documentation pages, renamed/rewired agent docs from “workflow” → “flowAgent” across examples and references, reorganized site navigation (including new Models section), tweaked package scripts/devDependency, adjusted vercel ignore logic, and added an empty changeset.

Changes

Cohort / File(s)	Summary
New top-level docs docs/architecture.md, docs/introduction.md, docs/principles.md, docs/quick-start.md	Added architecture, introduction, principles, and quick-start documentation describing agent/flowAgent semantics, Result-based returns, Runnable contract, models/prompts capabilities, and examples.
Agents docs — core & guides packages/agents/docs/core/flow-agent.md, packages/agents/docs/core/hooks.md, packages/agents/docs/core/overview.md, packages/agents/docs/core/step.md, packages/agents/docs/overview.md, packages/agents/docs/troubleshooting.md, packages/agents/docs/advanced/streaming.md, packages/agents/docs/guides/*, packages/agents/docs/guides/create-flow-agent.md	Systematic terminology/API rename from workflow → flowAgent across files: function/type names, examples, hook/event strings, error code references, and cross-links updated to flow-agent naming.
Provider & usage docs packages/agents/docs/provider/overview.md, packages/agents/docs/provider/usage.md	Renamed usage/token examples and identifiers to flow-agent-centric names (workflowUsage → flowAgentUsage, workflowId → flowAgentId) and updated example calls.
Docs navigation & site config zpress.config.ts	Reworked site navigation: added @funkai/models docs, promoted docs-driven root pages (Introduction, Quick Start, Principles, Architecture), reorganized Agents (Context, Middleware, Tracing), adjusted Prompts/CLI/Examples sections, and hid Contributing.
Package metadata & scripts package.json	Renamed npm script docs → docs:dev (command unchanged) and bumped devDependency @zpress/kit from ^0.2.4 → ^0.2.8.
Vercel config vercel.json	Replaced ignoreCommand git-diff check with pnpm zpress diff to determine ignored builds.
Minor docs edits & misc packages/cli/README.md, packages/agents/docs/guides/create-tool.md, packages/agents/docs/advanced/streaming.md, .changeset/tough-planes-lie.md	Fixed LICENSE link to absolute GitHub URL, updated reference links to flow-agent docs, swapped one streaming reference, and added an empty changeset metadata file.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• docs: comprehensive documentation for @funkai/models and @funkai/agents #7 — Overlapping documentation and JSDoc changes for models and agents; likely touches the same docs surface and type descriptions.
• feat(agents): Resolver pattern, evolve(), and unified params API #31 — Related API renames and examples for flowAgent and handler/resolver features mirrored in these docs.
• fix(repo): address bug and correctness issues across all packages #38 — Code-level flow-agent renames and hook fixes that correspond to the documentation updates here.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	Title clearly summarizes the primary changes: restructuring docs site layout and replacing workflow with flow-agent terminology.
Description check	✅ Passed	Description is related to the changeset, covering restructuring, terminology changes, and new documentation pages.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/quick-start.md`:
- Around line 6-23: The quick-start uses `@ai-sdk/openai` (import openai) but sets
OPENROUTER_API_KEY; fix by making auth and provider match: either change the
environment variable to OPENAI_API_KEY and document that consumers must export
OPENAI_API_KEY, or change the import/model to an OpenRouter-compatible provider
(and keep OPENROUTER_API_KEY). Update the doc lines that set the env var and/or
the import call (agent(...) using openai(...) / the OpenRouter provider symbol)
so the provider name and the env var (OPENAI_API_KEY or OPENROUTER_API_KEY) are
consistent.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 082133c8-6b34-4133-a91b-72bf10cd95f2

📥 Commits

Reviewing files that changed from the base of the PR and between e6a8c37 and 0df0dd6.

📒 Files selected for processing (23)

• docs/architecture.md
• docs/introduction.md
• docs/principles.md
• docs/quick-start.md
• package.json
• packages/agents/docs/advanced/streaming.md
• packages/agents/docs/core/flow-agent.md
• packages/agents/docs/core/hooks.md
• packages/agents/docs/core/overview.md
• packages/agents/docs/core/step.md
• packages/agents/docs/guides/cost-aware-agents.md
• packages/agents/docs/guides/create-agent.md
• packages/agents/docs/guides/create-flow-agent.md
• packages/agents/docs/guides/create-tool.md
• packages/agents/docs/guides/error-recovery.md
• packages/agents/docs/guides/multi-agent-orchestration.md
• packages/agents/docs/guides/test-agents.md
• packages/agents/docs/overview.md
• packages/agents/docs/provider/overview.md
• packages/agents/docs/provider/usage.md
• packages/agents/docs/troubleshooting.md
• packages/cli/README.md
• zpress.config.ts

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/introduction.md`:
- Around line 55-59: Replace the ternary expressions that check result.ok and
docs.ok with explicit if/else assignments to follow project conventions: for the
expression returning result.ok ? result.value.output : "" replace it with an
if/else that checks result.ok and returns result.value.output when true and ""
when false (referencing the variable result and its .value.output), and for the
object return using docs.ok ? docs.value : [] replace it by assigning a local
variable (e.g., docsArray) via an if/else that sets docsArray = docs.value when
docs.ok is true and docsArray = [] otherwise, then return { docs: docsArray }
(references: the symbols result, result.value.output, docs, and docs.value).

In `@docs/principles.md`:
- Around line 113-118: Replace the ternary expressions in this example with
explicit control flow to match project guidelines: instead of using "const
cleaned = cleanText(analysis.ok ? analysis.value.output : input.text);" and
"return { result: final.ok ? final.value : cleaned }", rewrite using if/else (or
match()) so you first check analysis.ok and set cleaned from
cleanText(analysis.value.output) or cleanText(input.text), and later check
final.ok to return either final.value or cleaned; update the $.step call (id:
"format", execute: () => formatOutput(cleaned)) usage accordingly so the example
shows clear, idiomatic branching with the functions cleanText, formatOutput and
the variables analysis, input.text, cleaned, and final.

In `@docs/quick-start.md`:
- Line 114: Replace the ternary in the return expression so it follows project
conventions: instead of using "return { final: reviewed.ok ?
reviewed.value.output : draft.value.output }", assign final via an if/else (or a
match on reviewed.ok) using the reviewed and draft values (e.g., compute final =
reviewed.ok ? ... but implemented as if/else) and then return { final }; update
the example to use the reviewed, draft, and final identifiers so it clearly
shows the if/else (or match) pattern.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 1d1819fe-e3b3-4dc9-a249-a553ea2a146c

📥 Commits

Reviewing files that changed from the base of the PR and between 570d947 and 5067d02.

📒 Files selected for processing (7)

• docs/architecture.md
• docs/introduction.md
• docs/principles.md
• docs/quick-start.md
• packages/agents/docs/core/flow-agent.md
• packages/agents/docs/overview.md
• zpress.config.ts