agentuity · afterrburn · Sep 20, 2025 · Sep 17, 2025 · Sep 17, 2025 · Sep 18, 2025
diff --git a/.cursor/rules/overview.mdc b/.cursor/rules/overview.mdc
@@ -10,4 +10,8 @@ This is the technical documentation for the Agentuity Cloud, which covers:
 - Examples, tutorials, samples (/content/Examples)
 - And the different SDKs (/content/SDKs)
 
-This doc app is a NextJS app built on top of Fumadocs (https://fumadocs.vercel.app/docs/ui).
+This doc app is a NextJS app built on top of Fumadocs (https://fumadocs.vercel.app/docs/ui).
+
+This project also contains the agent the powers RAG and Tutorials. Those agents live in `/agent-docs` directory.
+To run the agent server locally, go into that directory with `cd agent-docs` and then start the agent with `agentuity dev`.
+To run the NextJS app, do `npm run dev` in the root of this repository. You will want to start these two apps in separate repositories.
diff --git a/.cursor/rules/tutorials-structure.mdc b/.cursor/rules/tutorials-structure.mdc
@@ -0,0 +1,69 @@
+### Rule: tutorials-structure
+
+Purpose: Define how tutorials are authored and rendered so docs and runnable code stay in sync.
+
+### Structure
+- Narrative pages: `content/Tutorial/<tutorial-id>/step-<n>.mdx`
+- Section navigation: `content/Tutorial/meta.json` (list MDX page slugs in order)
+- Runnable example project: `examples/<tutorial-id>/` (full project; exclude `node_modules/`, `.uv/`)
+- Tutorial code snippets: must be imported from files via `<CodeFromFiles />`
+- Other, non-project examples: use regular fenced code blocks in MDX
+
+### MDX authoring
+- Each step MDX must use frontmatter:
+  - `title`, `description` (recommended: `stepNumber`, `next`, `prev`)
+- Import real code from the example project using repo-root-relative paths via `<CodeFromFiles />`:
+
+```mdx
+---
+title: Step 1 — Getting Started
+description: Intro step
+---
+
+<!-- Single snippet -->
+<CodeFromFiles snippets={[{ path: "/examples/javascript-sdk/src/agent.ts", lang: "ts", title: "agent.ts" }]} />
+
+<!-- Line range -->
+<CodeFromFiles snippets={[{ path: "/examples/javascript-sdk/src/agent.ts", lang: "ts", from: 12, to: 48, title: "Handler section" }]} />
+
+<!-- Multi-language tabs -->
+<CodeFromFiles snippets={[
+  { path: "/examples/javascript-sdk/src/agent.ts", lang: "ts", title: "TypeScript" },
+  { path: "/examples/javascript-sdk-python/src/agent.py", lang: "python", title: "Python" },
+]} title="Agent comparison" />
+```
+
+### `<CodeFromFiles />` component
+- Available in MDX via the docs page components map
+- Props:
+  - `snippets`: array of `{ path, lang?, from?, to?, title? }`
+    - `path`: repo-root-relative (must start with `/`), validated and read server-side
+    - `lang`: language for highlighting (auto-inferred if omitted)
+    - `from`, `to`: 1-based line range (inclusive)
+    - `title`: label per tab
+  - `title` (optional): heading displayed above the tabs
+- Renders using shared `CodeBlock` styling and `Tabs` for multiple snippets
+
+### Example project conventions (`examples/<tutorial-id>/`)
+- Include: `package.json`, `tsconfig.json`, `src/**`, optional `README.md`, optional lockfile
+- Exclude: `node_modules/`
+- Optional hygiene:
+  - Add `examples/**` to `.eslintignore` if you don’t want repo-wide linting on example sources
+  - Add `examples/**` to root `tsconfig.json` `exclude` if you don’t want repo-wide type-checks
+- Should be runnable in a sandbox (StackBlitz/CodeSandbox) via `package.json` scripts
+
+### Rendering pipeline
+- Fumadocs loads MDX via `lib/source.ts` and `app/(docs)/[[...slug]]/page.tsx`
+- `<CodeFromFiles />` reads files at build/server time and renders with `CodeBlock`
+
+
+### Agent compatibility (optional)
+- Step API: `GET /api/tutorials/:id/steps/:stepNumber` returns `{ mdx, snippets }`.
+- The chat UI replaces each `<CodeFromFiles />` occurrence with one or more fenced code blocks by consuming entries from `snippets` in order.
+
+### Quality gates (recommended)
+- CI verifies:
+  - All `content/Tutorial/**.mdx` pages referenced by `content/Tutorial/meta.json` build without errors
+  - All `<CodeFromFiles snippets={[...]}/>` references resolve to existing files
+  - Optional: the example project type-checks (`tsc --noEmit`) or passes a smoke test
+
diff --git a/.env.example b/.env.example
@@ -1,6 +1,5 @@
 # Agent Configuration
 AGENT_BASE_URL=http://127.0.0.1:3500
-AGENT_ID=agent_9ccc5545e93644bd9d7954e632a55a61
 
-# Alternative: You can also set the full URL instead of BASE_URL + ID
-# AGENT_FULL_URL=http://127.0.0.1:3500/agent_9ccc5545e93644bd9d7954e632a55a61
+# API key can be found in agent-docs .env AGENTUITY_SDK_KEY
+AGENTUITY_API_KEY=
-# API key can be found in agent-docs .env AGENTUITY_SDK_KEY
-AGENTUITY_API_KEY=
+# Authentication (set one)
+# Prefer AGENT_BEARER_TOKEN; AGENTUITY_API_KEY is accepted as an alias.
+AGENT_BEARER_TOKEN=
+# AGENTUITY_API_KEY=
+
-# API key can be found in agent-docs .env AGENTUITY_SDK_KEY
-AGENTUITY_API_KEY=
+# Authentication (set one)
+# Prefer AGENT_BEARER_TOKEN; AGENTUITY_API_KEY is accepted as an alias.
+AGENT_BEARER_TOKEN=
+# AGENTUITY_API_KEY=
+
diff --git a/.gitignore b/.gitignore
@@ -26,6 +26,7 @@ yarn-error.log*
 .env*.local
 .env.local
 .env.production
+.env
 .vercel
 next-env.d.ts
 .open-next

diff --git a/agent-docs/RAG-TODO.md b/agent-docs/RAG-TODO.md
diff --git a/agent-docs/RAG-design.md b/agent-docs/RAG-design.md