Docs updates (#343)

* Sandbox and runtime updates

* Update the "why" for features

* Tweaks

* Tweaks

* Tweaks

* Tweaks

* Updates

* Clean up

* Fixes

* Add Community section and move Cookbook to top level

- Create Community section with Snow Leopard example
- Add `ExternalCard` component for external link cards
- Move Cookbook from `Learn/` to top-level nav
- Update internal links to Cookbook pages
- Remove empty Learn section

* Tweaks

* Fixes

* Update examples

* Fix Bun links

* Tweaks

* Reorganize and add more info

* Update AI commands

* Tweaks

Author: parteeksingh24

components/external-card.tsx

@@ -0,0 +1,34 @@
+import { ExternalLink } from 'lucide-react';
+import type { ReactNode, CSSProperties } from 'react';
+
+interface ExternalCardProps {
+  href: string;
+  title: string;
+  icon?: ReactNode;
+  children: ReactNode;
+  style?: CSSProperties;
+  className?: string;
+}
+
+export function ExternalCard({ href, title, icon, children, style, className }: ExternalCardProps) {
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      className={`not-prose block rounded-lg border p-4 shadow-md transition-colors ${className || 'bg-fd-card text-fd-card-foreground hover:bg-fd-accent/80'}`}
+      style={style}
+    >
+      <div className="flex items-start gap-3">
+        {icon && <div>{icon}</div>}
+        <div className="flex-1">
+          <div className="flex items-center gap-2 font-medium">
+            {title}
+            <ExternalLink className="h-3.5 w-3.5 opacity-60" />
+          </div>
+          <span className="mt-1 block text-sm opacity-80">{children}</span>
+        </div>
+      </div>
+    </a>
+  );
+}

content/Agents/creating-agents.mdx

@@ -197,7 +197,15 @@ All implement [StandardSchema](https://github.com/standard-schema/standard-schem
 
 ### Type Inference
 
-TypeScript automatically infers types from your schemas:
+TypeScript automatically infers types from your schemas. Don't add explicit type annotations to handler parameters:
+
+```typescript
+// Good: types inferred from schema
+handler: async (ctx, input) => { ... }
+
+// Bad: explicit types can cause issues
+handler: async (ctx: AgentContext, input: MyInput) => { ... }
+```
 
 ```typescript
 const agent = createAgent('Search', {
@@ -364,6 +372,10 @@ handler: async (ctx, input) => {
 
 ## Next Steps
 
+<Callout type="tip" title="AI-Assisted Development">
+The [OpenCode plugin](/Reference/CLI/opencode-plugin) provides AI-assisted development for full-stack Agentuity projects, including agents, routes, frontend, and deployment.
+</Callout>
+
 - [Using the AI SDK](/Agents/ai-sdk-integration): Add LLM capabilities with generateText and streamText
 - [Managing State](/Agents/state-management): Persist data across requests with thread and session state
 - [Calling Other Agents](/Agents/calling-other-agents): Build multi-agent workflows

content/Agents/evaluations.mdx

@@ -5,6 +5,21 @@ description: Automatically test and validate agent outputs for quality and compl
 
 Evaluations (evals) are automated tests that run after your agent completes. They validate output quality, check compliance, and monitor performance without blocking agent responses.
 
+## Why Evals?
+
+Most evaluation tools test the LLM: did the model respond appropriately? That's fine for chatbots, but agents aren't single LLM calls. They're entire runs with multiple model calls, tool executions, and orchestration working together.
+
+Agent failures can happen anywhere in the run—a tool call that returned bad data, a state bug that corrupted context, and more. Testing just the LLM response misses most of this.
+
+Agentuity evals test the whole run—every tool call, state change, and orchestration step. They run on every session in production, so you catch issues with real traffic.
+
+**The result:**
+
+- **Full-run evaluation**: Test the entire agent execution, not just LLM responses
+- **Production monitoring**: Once configured, evals run automatically on every session
+- **Async by default**: Evals don't block responses, so users aren't waiting
+- **Preset library**: Common checks (PII, safety, hallucination) available out of the box
+
 Evals come in two types: **binary** (pass/fail) for yes/no criteria, and **score** (0-1) for quality gradients.
 
 <Callout type="info" title="Where Scores Appear">
@@ -426,6 +441,37 @@ export const politenessCheck = agent.createEval(politeness({
 
 All preset evals use a default model optimized for cost and speed. Override `model` when you need specific capabilities.
 
+### Lifecycle Hooks
+
+Preset evals support `onStart` and `onComplete` hooks for custom logic around eval execution:
+
+```typescript
+import { politeness } from '@agentuity/evals';
+
+export const politenessCheck = agent.createEval(politeness({
+  onStart: async (ctx, input, output) => {
+    ctx.logger.info('Starting politeness eval', {
+      inputLength: input.request?.length,
+    });
+  },
+  onComplete: async (ctx, result) => {
+    // Track results in external monitoring
+    if (!result.passed) {
+      ctx.logger.warn('Politeness check failed', {
+        score: result.score,
+        reason: result.reason,
+      });
+    }
+  },
+}));
+```
+
+**Use cases for lifecycle hooks:**
+- Log eval execution for debugging
+- Send results to external monitoring systems
+- Track eval performance metrics
+- Trigger alerts on failures
+
 ### Schema Middleware
 
 Preset evals expect a standard input/output format:

content/Agents/schema-libraries.mdx

@@ -103,6 +103,29 @@ type User = s.infer<typeof User>;
 // { name: string; age: number; role: 'admin' | 'user' }
 ```
 
+### JSON Schema Generation
+
+Convert schemas to JSON Schema for use with LLM structured output:
+
+```typescript
+import { s } from '@agentuity/schema';
+
+const ResponseSchema = s.object({
+  answer: s.string(),
+  confidence: s.number(),
+});
+
+// Generate JSON Schema
+const jsonSchema = s.toJSONSchema(ResponseSchema);
+
+// Generate strict JSON Schema for LLM structured output
+const strictSchema = s.toJSONSchema(ResponseSchema, { strict: true });
+```
+
+<Callout type="tip" title="Strict Mode for LLMs">
+Use `{ strict: true }` when generating schemas for LLM structured output (e.g., OpenAI's `response_format`). Strict mode ensures the schema is compatible with model constraints and produces more reliable outputs.
+</Callout>
+
 <Callout type="info" title="When to Use">
 Use `@agentuity/schema` for simple validation needs. For advanced features like email validation, string length constraints, or complex transformations, consider Zod or Valibot.
 </Callout>

content/Agents/standalone-execution.mdx

@@ -6,7 +6,7 @@ description: Execute agents programmatically for cron jobs, bots, CLI tools, and
 Sometimes your agent logic needs to run without an incoming HTTP request. `createAgentContext()` gives standalone code the same infrastructure that HTTP handlers get automatically: tracing, sessions, and storage access.
 
 <Callout type="warning" title="Agentuity Runtime Only">
-`createAgentContext()` requires Agentuity's runtime initialization and only works within the Agentuity runtime (Discord bots, CLI tools, queue workers deployed alongside your agents). It will throw an error if called from external frameworks like Next.js or Express. To access storage from external backends, see [SDK Utilities for External Apps](/Learn/Cookbook/Patterns/server-utilities).
+`createAgentContext()` requires Agentuity's runtime initialization and only works within the Agentuity runtime (Discord bots, CLI tools, queue workers deployed alongside your agents). It will throw an error if called from external frameworks like Next.js or Express. To access storage from external backends, see [SDK Utilities for External Apps](/Cookbook/Patterns/server-utilities).
 </Callout>
 
 ## Basic Usage
@@ -16,10 +16,20 @@ import { createAgentContext } from '@agentuity/runtime';
 import chatAgent from '@agent/chat';
 
 const ctx = createAgentContext();
-const result = await ctx.invoke(() => chatAgent.run({ message: 'Hello' }));
+const result = await ctx.run(chatAgent, { message: 'Hello' });
 ```
 
-The `invoke()` method executes your agent with full infrastructure support: tracing, session management, and access to all storage services.
+The `run()` method executes your agent with full infrastructure support: tracing, session management, and access to all storage services.
+
+For agents that don't require input:
+
+```typescript
+const result = await ctx.run(statusAgent);
+```
+
+<Callout type="info" title="Legacy invoke() Method">
+The older `ctx.invoke(() => agent.run(input))` pattern still works but `ctx.run(agent, input)` is preferred for its cleaner syntax.
+</Callout>
 
 ## Options
 
@@ -45,10 +55,7 @@ await createApp();
 // Run cleanup every hour
 cron.schedule('0 * * * *', async () => {
   const ctx = createAgentContext({ trigger: 'cron' });
-
-  await ctx.invoke(async () => {
-    await cleanupAgent.run({ task: 'expired-sessions' });
-  });
+  await ctx.run(cleanupAgent, { task: 'expired-sessions' });
 });
 ```
 
@@ -58,35 +65,33 @@ For most scheduled tasks, use the [`cron()` middleware](/Routes/cron) instead. I
 
 ## Multiple Agents in Sequence
 
-Run multiple agents within a single `invoke()` call to share the same session and tracing context:
+Run multiple agents in sequence with the same context:
 
 ```typescript
 const ctx = createAgentContext();
 
-const result = await ctx.invoke(async () => {
-  // First agent analyzes the input
-  const analysis = await analyzeAgent.run({ text: userInput });
-
-  // Second agent generates response based on analysis
-  const response = await respondAgent.run({
-    analysis: analysis.summary,
-    sentiment: analysis.sentiment,
-  });
+// First agent analyzes the input
+const analysis = await ctx.run(analyzeAgent, { text: userInput });
 
-  return response;
+// Second agent generates response based on analysis
+const response = await ctx.run(respondAgent, {
+  analysis: analysis.summary,
+  sentiment: analysis.sentiment,
 });
 ```
 
+Each `ctx.run()` call gets its own session and tracing span, while sharing the logger, tracer, and app state.
+
 ## Reusing Contexts
 
 Create a context once and reuse it for multiple invocations:
 
 ```typescript
 const ctx = createAgentContext({ trigger: 'websocket' });
 
-// Each invoke() gets its own session and tracing span
+// Each run gets its own session and tracing span
 websocket.on('message', async (data) => {
-  const result = await ctx.invoke(() => messageAgent.run(data));
+  const result = await ctx.run(messageAgent, data);
   websocket.send(result);
 });
 ```
@@ -104,6 +109,31 @@ Standalone contexts provide the same infrastructure as HTTP request handlers:
 - **Session events**: Start/complete events for observability
 </Callout>
 
+## Detecting Context
+
+Use `inAgentContext()` to check if code is running inside an agent handler with ambient context available:
+
+```typescript
+import { inAgentContext, createAgentContext } from '@agentuity/runtime';
+import myAgent from '@agent/my-agent';
+
+async function processRequest(data: unknown) {
+  if (inAgentContext()) {
+    // Inside an agent handler, ambient context is available
+    // so agent.run() works directly without explicit context
+    return myAgent.run(data);
+  }
+
+  // Outside agent handler, create context first
+  const ctx = createAgentContext();
+  return ctx.run(myAgent, data);
+}
+```
+
+This is useful for writing utility functions that work both inside agent handlers and in standalone scripts.
+
+To check if the Agentuity runtime is initialized (but not necessarily inside a handler), use `isInsideAgentRuntime()` instead.
+
 ## Next Steps
 
 - [Calling Other Agents](/Agents/calling-other-agents): Agent-to-agent communication patterns

content/Agents/streaming-responses.mdx

@@ -50,6 +50,10 @@ Streaming requires both: `schema.stream: true` in your agent (so the handler ret
 
 Enable streaming by setting `stream: true` in your schema and returning a `textStream`:
 
+<Callout type="info" title="AI SDK Integration">
+The `textStream` from AI SDK's `streamText()` works directly with Agentuity's streaming middleware. Return it from your handler without additional processing.
+</Callout>
+
 ```typescript
 import { createAgent } from '@agentuity/runtime';
 import { streamText } from 'ai';

content/Agents/workbench.mdx

@@ -5,6 +5,19 @@ description: Use the built-in development UI to test agents, validate schemas, a
 
 Workbench is a built-in UI for testing your agents during development. It automatically discovers your agents, displays their input/output schemas, and lets you execute them with real inputs.
 
+## Why Workbench?
+
+Testing agents isn't like testing traditional APIs. You need to validate input schemas, see how responses format, test multi-turn conversations, and understand execution timing. Using `curl` or Postman means manually constructing JSON payloads and parsing responses.
+
+Workbench understands your agents. It reads your schemas, generates test forms, maintains conversation threads, and shows execution metrics. When something goes wrong, you see exactly what the agent received and returned.
+
+**Key capabilities:**
+
+- **Schema-aware testing**: Input forms generated from your actual schemas
+- **Thread persistence**: Test multi-turn conversations without manual state tracking
+- **Execution metrics**: See token usage and response times for every request
+- **Quick iteration**: Test prompts display in the UI for one-click execution
+
 ## Enabling Workbench
 
 Add a `workbench` section to your `agentuity.config.ts`:

content/Community/meta.json

@@ -0,0 +1,4 @@
+{
+	"title": "Community",
+	"pages": ["overview"]
+}

content/Community/overview.mdx

@@ -0,0 +1,31 @@
+---
+title: Community Examples
+description: Real-world integrations and tutorials built with Agentuity
+---
+
+import { Cards } from 'fumadocs-ui/components/card';
+import { ExternalCard } from '@/components/external-card';
+
+## From the Community
+
+<Cards>
+  <ExternalCard
+    href="https://docs.snowleopard.ai/quickstarts/agentuity"
+    title="Snow Leopard: Data Retrieval Agent"
+    icon={
+      <picture>
+        <img src="/images/snow-leopard-icon.png" alt="Snow Leopard" width={28} height={28} />
+      </picture>
+    }
+    className="bg-white text-[#2D2D2D] border-gray-200 hover:bg-gray-50 hover:border-[#2D2D2D] dark:bg-[#2D2D2D] dark:text-white dark:border-[#484848] dark:hover:bg-[#484848] dark:hover:border-[#9DEDEB]"
+  >
+    Answer questions about your SQL data. No MCP, ETL, or RAG required.
+  </ExternalCard>
+</Cards>
+
+## Share Your Work
+
+Built something with Agentuity? We'd love to feature it.
+
+- [Open a PR](https://github.com/agentuity/docs/pulls) to add your example
+- Or, [reach out on Discord](https://discord.gg/agentuity) to share what you've built

content/Frontend/react-hooks.mdx

@@ -280,6 +280,44 @@ function SearchResults({ query }: { query: string }) {
 }
 ```
 
+### Dynamic Path Parameters
+
+For routes with path parameters (e.g., `/api/items/:itemId`), pass params at invocation time:
+
+```tsx
+import { useAPI } from '@agentuity/react';
+
+function ItemActions({ itemId }: { itemId: string }) {
+  const { invoke: deleteItem, isLoading } = useAPI('DELETE /api/items/:itemId');
+  const { invoke: updateItem } = useAPI('PUT /api/items/:itemId');
+
+  const handleDelete = async () => {
+    await deleteItem(undefined, { params: { itemId } });
+  };
+
+  const handleUpdate = async (name: string) => {
+    await updateItem({ name }, { params: { itemId } });
+  };
+
+  return (
+    <div>
+      <button onClick={() => handleUpdate('New Name')} disabled={isLoading}>
+        Rename
+      </button>
+      <button onClick={handleDelete} disabled={isLoading}>
+        Delete
+      </button>
+    </div>
+  );
+}
+```
+
+The second argument to `invoke()` accepts `params` for path parameter values (e.g., `{ params: { itemId: '123' } }`).
+
+<Callout type="info" title="Query and Headers">
+To set `query` or `headers`, pass them when calling `useAPI()`, not to `invoke()`. For dynamic query parameters, see the [example above](#request-options).
+</Callout>
+
 ## Auth State with useAuth
 
 Access authentication state for protected components or custom auth logic: