feat: add docs for structured outputs

[AlemTuzlak]

🎯 Changes

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• Documentation
  • Added a comprehensive guide on Structured Outputs covering purpose, workflow, schema conversion, provider API usage, validation, and typed results.
  • Includes practical examples using popular schema libraries and best practices for implementation.
  • Updated documentation navigation to surface the new guide.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request adds documentation for a structured outputs feature, consisting of a navigation configuration entry and a comprehensive guide page explaining the feature's purpose, usage patterns, supported schema libraries, and best practices.

Changes

Cohort / File(s)	Summary
Documentation Configuration docs/config.json	Added navigation entry for "Structured Outputs" guide under the Guides section, positioned after "Agentic Cycle"
Feature Documentation docs/guides/structured-outputs.md	New comprehensive guide covering structured outputs workflow (schema conversion, provider API usage, validation), supported libraries (Zod, etc.), type inference behavior, code examples with error handling, and best practices

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Poem

🐰 Hop along, dear reader, through schemas so neat,
Structured outputs make data complete!
From Zod to JSON, we guide every way,
Type safety and validation, hooray, hooray!
A carrot-sized manual, easy to follow today! 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Description check	❓ Inconclusive	The description follows the required template structure with all sections present, but the key 'Changes' section lacks detail about what was actually added; all checklist items remain unchecked.	Complete the 'Changes' section with actual details about the documentation added, and verify/check the appropriate checklist items to confirm testing and release impact assessment.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: add docs for structured outputs' clearly and concisely describes the main change—adding documentation for a structured outputs feature.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feat/structured-outputs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

📜 Review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between f527119 and 252320e.

📒 Files selected for processing (2)

• docs/config.json
• docs/guides/structured-outputs.md

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-12-13T17:09:09.794Z

Learnt from: CR
Repo: TanStack/ai PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-13T17:09:09.794Z
Learning: Applies to **/*.{ts,tsx} : Use Zod for runtime schema validation and type inference, particularly for tool input/output definitions with `toolDefinition()` and Zod schema inference

Applied to files:

• docs/guides/structured-outputs.md

🔇 Additional comments (8)

docs/config.json (1)

53-56: LGTM!

The navigation entry is properly structured and logically placed in the guides section between agentic concepts and streaming topics.

docs/guides/structured-outputs.md (7)

40-68: LGTM!

The basic usage example is clear, complete, and demonstrates the key concepts effectively with proper imports, schema definition, and usage.

---

182-219: LGTM!

The tool integration example correctly demonstrates using Zod schemas with toolDefinition() for type-safe tool definitions, aligning with established patterns. The workflow explanation is clear.

Based on learnings, this follows the recommended pattern for using Zod with tool definitions.

---

263-300: LGTM!

The best practices section provides valuable guidance with clear examples, and the error handling pattern is appropriate for production use.

---

226-226: The JSONSchema type is correctly exported from "@tanstack/ai" and the import statement in the documentation is valid. The type is defined in the package's type exports and can be freely imported for use.

Likely an incorrect or invalid review comment.

---

74-77: The return type behavior is accurate. The type definition TextActivityResult<TSchema, TStream> correctly implements the distinction: when TSchema extends SchemaInput (outputSchema provided), it returns Promise<InferSchemaType<TSchema>>; otherwise with default parameters, it returns AsyncIterable<StreamChunk>. The table correctly represents this API behavior.

---

7-7: No issues found. The link to standardschema.dev is accessible (HTTP 200) and "Standard JSON Schema" is the correct terminology for the specification being referenced. The documentation is accurate.

---

29-29: The documentation is accurate. Zod v4 is stable as of 2025, and v4.2+ is the correct minimum version—it specifically introduced the JSON Schema/Standard Schema conversion features (z.fromJSONSchema / .toJSONSchema). No changes needed.

Likely an incorrect or invalid review comment.