diff --git a/docs/docs.json b/docs/docs.json
index 880e58e86..3d1865687 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -113,6 +113,13 @@
"migration/breaking-changes",
"migration/api-changes"
]
+ },
+ {
+ "group": "Contribute",
+ "icon": "clipboard-list",
+ "pages": [
+ "platform/contribute"
+ ]
}
]
},
@@ -417,24 +424,24 @@
"icon": "microchip",
"pages": [
"api-reference/memory/add-memories",
- "api-reference/memory/search-memories",
"api-reference/memory/get-memories",
+ "api-reference/memory/search-memories",
"api-reference/memory/update-memory",
"api-reference/memory/delete-memory"
]
},
{
- "group": "Advanced Memory APIs",
+ "group": "Memory APIs",
"icon": "sparkles",
"pages": [
- "api-reference/memory/history-memory",
+ "api-reference/memory/create-memory-export",
+ "api-reference/memory/feedback",
"api-reference/memory/get-memory",
+ "api-reference/memory/history-memory",
+ "api-reference/memory/get-memory-export",
"api-reference/memory/batch-update",
"api-reference/memory/batch-delete",
- "api-reference/memory/delete-memories",
- "api-reference/memory/create-memory-export",
- "api-reference/memory/get-memory-export",
- "api-reference/memory/feedback"
+ "api-reference/memory/delete-memories"
]
},
{
diff --git a/docs/platform/contribute.mdx b/docs/platform/contribute.mdx
new file mode 100644
index 000000000..87abf7b78
--- /dev/null
+++ b/docs/platform/contribute.mdx
@@ -0,0 +1,138 @@
+---
+title: Contribution Hub
+description: "Follow the shared playbook for writing and updating Mem0 documentation."
+icon: "clipboard-list"
+---
+
+# Build Mem0 Docs the Right Way
+
+
+ **Who this is for**
+ - Contributors and LLM assistants updating the docs
+ - Reviewers vetting new pages before publication
+ - Maintainers syncing live docs with the template library
+
+
+
+
+Check your team’s latest checklist or guidance so the update keeps the right navigation flow, CTA pattern, and language coverage.
+
+
+Select the doc type you are writing (quickstart, feature guide, migration, etc.) and copy the skeleton from the template library below.
+
+
+Fill the skeleton completely, include inline verification callouts, and jot down any open questions for maintainers before opening a PR.
+
+
+
+
+ When previewing locally, confirm the page ends with exactly two CTA cards, includes both Python and TypeScript examples when they exist, and keeps all Mintlify icons (no emojis).
+
+
+## Template Library
+
+Choose the document type you need. Each card links directly to the canonical template inside this repo.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+## Contribution Checklist
+
+
+
+ Confirm you copied the exact skeleton (`✅ COPY THIS` block) and removed every placeholder. Keep the DO-NOT-COPY guidance out of the published doc.
+
+
+ Use Mintlify icons, include `` after runnable steps, and ensure Tabs show both Python and TypeScript (or justify the absence with ``).
+
+
+ Flag blockers or follow-up work in your PR description so reviewers know what to look for and can update project trackers as needed.
+
+
+
+
+
+
+
diff --git a/docs/templates/api_reference_template.mdx b/docs/templates/api_reference_template.mdx
new file mode 100644
index 000000000..5043a1f56
--- /dev/null
+++ b/docs/templates/api_reference_template.mdx
@@ -0,0 +1,244 @@
+---
+title: API Reference Template
+description: "Standard layout for documenting Mem0 API endpoints."
+icon: "code"
+---
+
+# Api Reference Template
+
+API reference pages document a single endpoint contract. Present metadata, request/response examples, and recovery guidance without narrative detours.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Frontmatter must include `title`, `description`, `icon`, `method`, `path`. Heading should be `# METHOD /path`.
+- Provide a quick facts table (Method, Path, Auth, Rate limit) followed by an `` block describing when to use the endpoint. Add `` for beta headers or scope requirements.
+- Requests require headers table, body/parameters table, and `` with cURL, Python, TypeScript. If a language is unavailable, include a `` explaining why.
+- Response section must show a canonical success payload, status-code table, and troubleshooting tips. Document pagination/idempotency in `` or `` blocks.
+- End with related endpoints, a sample workflow link, and two CTA cards (left = concept/feature, right = applied tutorial). Keep the comment reminder for reviewers.
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+
+````mdx
+---
+title: [Endpoint name]
+description: [Primary action handled by this endpoint]
+icon: "bolt"
+method: "POST"
+path: "/v1/memories"
+---
+
+# [METHOD] [path]
+
+| Method | Path | Auth | Rate Limit |
+| --- | --- | --- | --- |
+| [METHOD] | `[path]` | Bearer (`mem0-api-key`) | [X req/min] |
+
+
+ Use this endpoint when [brief scenario]. Prefer [alternative endpoint] for [other scenario].
+
+
+
+ [Optional: scopes, beta headers, or breaking changes.] Remove if not needed.
+
+
+## Request
+
+### Headers
+
+| Name | Required | Description |
+| --- | --- | --- |
+| `Authorization` | Yes | `Bearer YOUR_API_KEY` |
+| `Content-Type` | Yes | `application/json` |
+
+### Body
+
+| Field | Type | Required | Description | Example |
+| --- | --- | --- | --- | --- |
+| `user_id` | string | Yes | Identifier for the end user. | `"alex"` |
+| `memory` | string | Yes | Content to store. | `"Prefers email follow-ups."` |
+| `metadata` | object | No | Key/value pairs for filtering. | `{ "channel": "support" }` |
+
+
+```bash Shell
+curl https://api.mem0.ai/v1/memories \
+ -H "Authorization: Bearer $MEM0_API_KEY" \
+ -H "Content-Type: application/json" \
+ -d '{ "user_id": "alex", "memory": "Prefers email follow-ups." }'
+```
+
+```python Python
+import requests
+
+resp = requests.post(
+ "https://api.mem0.ai/v1/memories",
+ headers={"Authorization": f"Bearer {API_KEY}"},
+ json={"user_id": "alex", "memory": "Prefers email follow-ups."},
+)
+resp.raise_for_status()
+```
+
+```ts TypeScript
+const response = await fetch("https://api.mem0.ai/v1/memories", {
+ method: "POST",
+ headers: {
+ Authorization: `Bearer ${process.env.MEM0_API_KEY}`,
+ "Content-Type": "application/json",
+ },
+ body: JSON.stringify({ user_id: "alex", memory: "Prefers email follow-ups." }),
+});
+```
+
+
+
+ Batch insertion? Use `/v1/memories/batch` with the same payload structure.
+
+
+## Response
+
+```json
+{
+ "memory_id": "mem_123",
+ "created_at": "2025-02-04T12:00:00Z"
+}
+```
+
+| Status | Meaning | Fix |
+| --- | --- | --- |
+| `201` | Memory stored successfully. | — |
+| `400` | Missing required field. | Provide `user_id` and `memory`. |
+| `401` | Invalid or missing API key. | Refresh key in dashboard. |
+
+
+ Responses include pagination tokens when you request multiple resources. Reuse them to fetch the next page.
+
+
+## Related endpoints
+
+- [GET /v1/memories/{memory_id}](./get-memory)
+- [DELETE /v1/memories/{memory_id}](./delete-memory)
+
+## Sample workflow
+
+- [Build a Customer Support Agent](/cookbooks/customer-support-agent)
+
+
+
+
+
+
+
+````
+
+---
+
+## ✅ Publish Checklist
+- [ ] Quick facts table matches frontmatter method/path and shows auth/rate limit.
+- [ ] Request section includes headers, body table, and code samples for cURL, Python, TypeScript (or `` explaining missing SDK).
+- [ ] Response section documents success payload plus error table with fixes.
+- [ ] Related endpoints and sample workflow link to existing docs.
+- [ ] CTA pair uses concept/feature on the left and an applied example on the right.
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/concept_guide_template.mdx b/docs/templates/concept_guide_template.mdx
new file mode 100644
index 000000000..64f00c9d3
--- /dev/null
+++ b/docs/templates/concept_guide_template.mdx
@@ -0,0 +1,211 @@
+---
+title: Concept Guide Template
+description: "Teach mental models and terminology before diving into implementation."
+icon: "brain"
+---
+
+# Concept Guide Template
+
+Concept guides establish a shared mental model before feature or API docs. Define the idea, show how it behaves over time, and point to practical follow-ups.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Frontmatter must include `title`, `description`, `icon`. Lead with a definition + analogy in two sentences max.
+- Add an `` block (“Why it matters”) with 2–3 bullets summarizing user impact. Use `` near limitations or beta callouts.
+- Introduce vocabulary via `## Key terms` (table or bullets) before diving deeper.
+- Organize the body with question-style headings (`How does it work?`, `When should you use it?`, `How it compares`). Optional diagrams should be left-to-right (`graph LR`).
+- Include at least one light code/JSON snippet or data table so the concept ties back to implementation.
+- Close with a “Put it into practice” checklist, “See it live” links, and the standard two-card CTA (left = feature/reference, right = applied cookbook).
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+
+````mdx
+---
+title: [Concept name]
+description: [One-sentence promise of understanding]
+icon: "lightbulb"
+---
+
+# [Concept headline]
+
+[Define the concept in one sentence.] [Add an analogy or context hook.]
+
+
+ **Why it matters**
+ - [Impact bullet]
+ - [Impact bullet]
+ - [Impact bullet]
+
+
+## Key terms
+
+- **[Term]** – [Short definition]
+- **[Term]** – [Short definition]
+
+
+```mermaid
+graph LR
+ A[Input] --> B[Concept]
+ B --> C[Outcome]
+```
+
+## How does it work?
+
+[Explain lifecycle or architecture.]
+
+```python
+# Minimal snippet that anchors the concept in code
+```
+
+
+ [Nuance or best practice related to this concept.]
+
+
+## When should you use it?
+
+- [Scenario 1]
+- [Scenario 2]
+- [Scenario 3]
+
+## How it compares
+
+| Option | Best for | Trade-offs |
+| --- | --- | --- |
+| [Concept] | [Use case] | [Caveat] |
+| [Alternative] | [Use case] | [Caveat] |
+
+
+ [Optional limitation or beta note.] Delete if not needed.
+
+
+## Put it into practice
+
+- [Operation or feature doc that relies on this concept]
+- [Another supporting doc]
+
+## See it live
+
+- [Cookbook or integration demonstrating the concept]
+- [Recording, demo, or sample repo]
+
+
+
+
+
+
+
+````
+
+---
+
+## ✅ Publish Checklist
+- [ ] Definition + analogy stay within two sentences.
+- [ ] “Why it matters” bullets focus on user impact, not implementation detail.
+- [ ] Key terms, lifecycle explanation, and comparison table are present (or intentionally removed when irrelevant).
+- [ ] At least one code/JSON/table example grounds the concept.
+- [ ] CTA pair links to a feature/reference (left) and applied tutorial (right).
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/cookbook_template.mdx b/docs/templates/cookbook_template.mdx
new file mode 100644
index 000000000..b6d0cce53
--- /dev/null
+++ b/docs/templates/cookbook_template.mdx
@@ -0,0 +1,283 @@
+---
+title: Cookbook Template
+description: "Narrative recipe structure for end-to-end Mem0 workflows."
+icon: "book-open"
+---
+
+# Cookbook Template
+
+Cookbooks are narrative tutorials. They start with a real problem, show the broken path, then layer production-ready fixes. Use this template verbatim so every contributor (human or LLM) ships the same experience.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Tell a story: problem → broken demo → iterative fixes → production patterns.
+- Keep tone conversational; use real names ("Max", "Sarah"), not `user_123`.
+- Opening must stay tight: ≤2 short paragraphs (no bullet lists) before the first section.
+- Inline expected outputs immediately after each code block.
+- Limit callouts to 3–5 per page. Prefer narrative text over stacked boxes.
+- Always provide Python **and** TypeScript tabs when an SDK exists for both.
+- Every page must end with exactly two navigation cards (left = related/side quest, right = next cookbook in the journey).
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+Paste the block below into a new cookbook, then replace all placeholders. Remove any section you don't need **only after** the happy path works.
+
+```mdx
+---
+title: [Cookbook title — action oriented]
+description: [1 sentence outcome]
+---
+
+# [Hero headline]
+
+[Two sentences max: state the user's pain and what this cookbook will fix.]
+
+
+[Only include if you truly have launch news. Delete otherwise to keep the intro crisp.]
+
+
+
+**Time to complete:** [~X minutes] · **Languages:** Python, TypeScript
+
+
+## Setup
+
+```python
+default_language = "python" # replace with real imports
+```
+```typescript
+// Equivalent TypeScript setup goes here
+```
+
+
+Mention any prerequisites (API keys, environment variables) right here if the reader must do something before running code.
+
+
+## Make It Work Once
+
+[Set context with characters + goal.]
+
+```python
+# Happy-path example
+```
+```typescript
+// Happy-path example (TypeScript)
+```
+
+
+Expected output (Python): `[describe inline]` · Expected output (TypeScript): `[describe inline]`
+
+
+## The Problem
+
+[Explain what breaks without tuning.]
+
+```python
+# Broken behaviour
+```
+```typescript
+// Broken behaviour
+```
+
+**Output:**
+```
+[Paste noisy output]
+```
+
+[One sentence on why the result is unacceptable.]
+
+## Fix It – [Solution Name]
+
+[Explain the fix and why it helps.]
+
+```python
+# Improved implementation
+```
+```typescript
+// Improved implementation
+```
+
+**Retest:**
+```python
+# Same test as before
+```
+```typescript
+// Same test as before
+```
+
+**Output:**
+```
+[Cleaner result]
+```
+
+[Highlight the improvement + remaining gap if any.]
+
+## Build On It – [Second Layer]
+
+[Add another enhancement, e.g., metadata filters, rerankers, batching.]
+
+```python
+# Additional refinement
+```
+```typescript
+// Additional refinement
+```
+
+
+Call out the most common mistake or edge case for this layer.
+
+
+## Production Patterns
+
+- **[Pattern 1]** — `[When to use it]`
+ ```python
+ # Example snippet
+ ```
+ ```typescript
+ // Example snippet
+ ```
+- **[Pattern 2]** — `[When to use it]`
+ ```python
+ # Example snippet
+ ```
+ ```typescript
+ // Example snippet
+ ```
+
+## What You Built
+
+- **[Capability 1]** — [How the cookbook delivers it]
+- **[Capability 2]** — [How the cookbook delivers it]
+- **[Capability 3]** — [How the cookbook delivers it]
+
+## Production Checklist
+
+- [Actionable step #1]
+- [Actionable step #2]
+- [Actionable step #3]
+
+## Next Steps
+
+
+
+
+
+```
+
+---
+
+## ✅ Publish Checklist (Keep Handy)
+- [ ] Replace every `[placeholder]` and remove unused sections.
+- [ ] Python & TypeScript code compile (or TypeScript omitted with explicit `` stating language limitation).
+- [ ] Each code block is followed by output + `` or inline equivalent.
+- [ ] Callouts ≤ 5 total; no emoji, only Mintlify icons.
+- [ ] Exactly two cards in the final ``.
+- [ ] Added verification narrative (what success looks like) in every major step.
+- [ ] Linked related docs (cookbooks, guides, reference) in Next Steps.
+
+Stick to the skeleton above. If you need to deviate, document the rationale in the PR so we can update the template for everyone else.
+```
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/feature_guide_template.mdx b/docs/templates/feature_guide_template.mdx
new file mode 100644
index 000000000..6c56f8451
--- /dev/null
+++ b/docs/templates/feature_guide_template.mdx
@@ -0,0 +1,227 @@
+---
+title: Feature Guide Template
+description: "Structure for explaining when and why to use a Mem0 feature."
+icon: "sparkles"
+---
+
+# Feature Guide Template
+
+Use this when you introduce or deepen a single Mem0 capability (Graph Memory, Advanced Retrieval, etc.). Aim for crisp problem framing, a walkthrough of how the feature works, and practical configuration guidance with clear exits.
+
+## Reader Promise
+- Understand the pain the feature solves and when to reach for it.
+- See how to enable, configure, and observe the feature in action.
+- Know the next conceptual deep dive and a hands-on example to try.
+
+## Start → Middle → End Pattern
+
+### 1. **Start – Why this feature exists**
+- Frontmatter stays outcome-driven: `title`, `description`, `icon`, optional `badge` (e.g., “Advanced”).
+- Opening paragraph = two sentences: problem, then payoff. Keep energy high right from the start.
+- Include an `` block titled “You’ll use this when…” with 3 bullets (user persona, workload, expected benefit).
+- If there’s a known caveat (pricing, performance), surface it early in a `` so readers don’t get surprised later.
+- Optional but encouraged: add a Mermaid diagram right after the intro to show how components connect; delete it if the story is obvious without visuals.
+- Add a `## Configure access` snippet (even if it’s “Confirm your Mem0 API key is already configured”) so contributors never forget to mention the baseline setup.
+
+### 2. **Middle – How it works**
+- Create three predictable sections:
+ 1. **Feature anatomy** – Diagram or bullet list of moving parts. Use a table if you need to compare modes (platform vs OSS).
+ 2. **Configure it** – Step-by-step enabling instructions with `` or JSON/YAML snippets. Follow each code block with a short explanation of why it matters.
+ 3. **See it in action** – End-to-end example (often reusing operation snippets). Pair code with `` for expected results and `` for optimization hints.
+- Insert `` blocks for cross-links (e.g., “Also available via REST endpoint `/v1/...`”).
+- Keep the tone instructive but light—no long manifestos.
+
+### 3. **End – Evaluate and go deeper**
+- Add an `## Verify the feature is working` section with bullets (metrics, logs, dashboards).
+- Follow with `## Best practices` or `## Tuning tips` (3–4 bullets max).
+- Close with the standard two-card CTA pair: left card = related concept or architecture page, right card = cookbook/application. Keep the comment reminder to double-check links.
+- If providers differ meaningfully, summarize them in a final accordion (`` with one `` per provider) so readers can expand what they need without scrolling walls of configuration.
+
+## Markdown Skeleton
+
+```mdx
+---
+title: Advanced Retrieval
+description: Increase relevance with reranking, criteria filters, and context windows.
+icon: "sparkles"
+badge: "Advanced"
+---
+
+# Advanced Retrieval
+
+Mem0’s advanced retrieval elevates search accuracy when basic keyword matches aren’t enough. Turn it on when you need precise context for high-stakes conversations.
+
+
+ **You’ll use this when…**
+ - You need semantic ranking across long-running agents
+ - Compliance requires tight control over returned memories
+ - Personalization hinges on precise filters
+
+
+
+ Advanced retrieval currently applies to managed Platform projects only. Self-hosted users should rely on the OSS reranker configuration.
+
+
+
+```mermaid
+%% Diagram the moving parts (delete when you fill this out)
+graph TD
+ A[Input] --> B[Feature]
+ B --> C[Output]
+```
+
+## Feature anatomy
+
+- Outline the moving parts (retriever, reranker, filters).
+- Add a table comparing default vs advanced behavior.
+
+## Configure it
+
+
+```python Python
+client = Client(...)
+client.memories.search(criteria={...})
+```
+
+```ts TypeScript
+const memories = await mem0.memories.search({ criteria: { ... } });
+```
+
+
+Explain which knobs matter (e.g., `rerank_top_k`, `criteria`, `filters`).
+
+
+ OSS users can mirror this by enabling the reranker in `config.yaml`. Link to the integration guide if relevant.
+
+
+## See it in action
+
+Walk through a real request/response. Include sample payloads and highlight notable fields.
+
+
+ Expect the top memory to match the user persona you set earlier. If not, revisit your filters.
+
+
+## Provider setup {/* Delete if not applicable */}
+
+
+
+ Outline configuration or link to provider docs here.
+
+
+
+## Verify the feature is working
+
+- Watch the dashboard analytics for retrieval latency changes.
+- Check logs for `reranker_applied: true`.
+
+## Best practices
+
+- Keep criteria minimal—overfiltering hurts recall.
+- Pair with Memory Filters v2 for hybrid scoring.
+
+{/* DEBUG: verify CTA targets */}
+
+
+
+ Understand how Mem0 ranks memories under the hood.
+
+
+ See advanced retrieval driving a full knowledge assistant.
+
+
+```
+
+Stick to this outline. Keep the “why” up front, the “how” in the middle, and the “where to go next” crystal clear at the end.
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/integration_guide_template.mdx b/docs/templates/integration_guide_template.mdx
new file mode 100644
index 000000000..cd01bbc32
--- /dev/null
+++ b/docs/templates/integration_guide_template.mdx
@@ -0,0 +1,290 @@
+---
+title: Integration Guide Template
+description: "Pattern for pairing Mem0 with third-party tools."
+icon: "plug"
+---
+
+# Integration Guide Template
+
+Integration guides prove a joint journey: configure Mem0 and the partner with minimal steps, run one end-to-end sanity command, then hand the reader to deeper workflows.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Frontmatter must include `title`, `description`, `icon`, and optional `partnerBadge`/`tags`. State the joint value in one sentence right after the H1.
+- List prerequisites for **both** platforms inside an `` block. Surface limited-access or beta flags in a `` before any setup.
+- Default to Tabs + Steps when instructions diverge (Platform vs OSS, Python vs TypeScript). When only one path exists, add a `` explaining the missing variant.
+- Keep any Mermaid diagrams optional and left-to-right (`graph LR`) to avoid vertical overflow; use only if architecture clarity is needed.
+- Every major step must finish with a verification ``. End the page with exactly two CTA cards (left = related reference, right = next integration/cookbook).
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+Paste the block below, replace placeholders, and delete optional sections only when unnecessary for this integration.
+
+````mdx
+---
+title: [Integration title]
+description: [One-sentence joint value]
+icon: "puzzle-piece"
+partnerBadge: "[Partner name]" # Optional
+---
+
+# [Integration headline — Mem0 + Partner promise]
+
+Combine Mem0’s memory layer with [Partner] to [describe the joint outcome].
+
+
+ **Prerequisites**
+ - [Mem0 requirement: API key, SDK version, project access]
+ - [Partner requirement: account, SDK version, tooling]
+ - [Optional extras: Docker, ngrok, etc.]
+
+
+
+ [Use only if access is gated or breaking changes exist. Delete when not needed.]
+
+
+
+```mermaid
+graph LR
+ A[Mem0] --> B[Connector]
+ B --> C[Partner workflow]
+```
+
+## Configure credentials
+
+
+
+
+
+```bash
+export MEM0_API_KEY="sk-..."
+```
+
+
+```bash
+partner secrets set MEM0_API_KEY=$MEM0_API_KEY
+```
+
+
+
+
+
+
+```bash
+partner auth login
+```
+
+
+```bash
+export PARTNER_API_KEY="..."
+```
+
+
+
+
+
+
+ Self-hosting Mem0? Swap `https://api.mem0.ai` with `https://` and keep the rest of this guide identical.
+
+
+## Wire Mem0 into [Partner]
+
+
+
+
+
+```bash
+pip install mem0ai [partner-package]
+```
+
+
+```python
+from mem0 import Memory
+from partner import Client
+
+memory = Memory(api_key=os.environ["MEM0_API_KEY"])
+partner_client = Client(api_key=os.environ["PARTNER_API_KEY"])
+```
+
+
+```python
+@graph.tool
+def recall_preferences(user_id: str):
+ return memory.search("recent preferences", filters={"user_id": user_id})
+```
+
+
+
+
+
+
+```bash
+npm install mem0ai [partner-package]
+```
+
+
+```typescript
+import { Memory } from "mem0ai/oss";
+import { Partner } from "[partner-package]";
+
+const memory = new Memory({ apiKey: process.env.MEM0_API_KEY! });
+const partner = new Partner({ apiKey: process.env.PARTNER_API_KEY! });
+```
+
+
+```typescript
+partner.registerTool("recallPreferences", async (userId: string) => {
+ const result = await memory.search("recent preferences", { userId });
+ return result.results;
+});
+```
+
+
+
+
+
+
+ Run `[verification command]` and expect `[describe log/result]`. If you see `[common error]`, jump to Troubleshooting below.
+
+
+## Run the integration sanity check
+
+```bash
+[command or script that exercises the flow]
+```
+
+
+ Output should mention `[success signal]` and `[partner console confirmation]`.
+
+
+## Verify the integration
+
+- `[Signal 1: dashboard entry, log line, or console message]`
+- `[Signal 2: partner UI reflects the memory data]`
+- `[Optional signal 3]`
+
+## Troubleshooting
+
+- **[Issue]** — `[Fix or link to partner docs]`
+- **[Issue]** — `[Fix or link to Mem0 troubleshooting guide]`
+
+
+
+
+
+
+
+````
+
+---
+
+## ✅ Publish Checklist
+- [ ] Joint value statement and prerequisites cover both Mem0 and partner requirements.
+- [ ] Tabs/Steps include Python and TypeScript (or a `` explains missing parity).
+- [ ] Every major step ends with an `` describing success criteria.
+- [ ] Troubleshooting lists at least two concrete fixes.
+- [ ] Final `` has exactly two cards with validated links.
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/migration_guide_template.mdx b/docs/templates/migration_guide_template.mdx
new file mode 100644
index 000000000..e0b066c3b
--- /dev/null
+++ b/docs/templates/migration_guide_template.mdx
@@ -0,0 +1,258 @@
+---
+title: Migration Guide Template
+description: "Plan → migrate → validate flow with rollback coverage."
+icon: "arrow-right"
+---
+
+# Migration Guide Template
+
+Migrations lower blood pressure. They explain what’s changing, why it matters, and how to get through the upgrade with verifications and rollbacks close at hand.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Keep the frontmatter complete (`title`, `description`, `icon`, `versionFrom`, `versionTo`, and optional `releaseDate`). Readers should know at a glance what versions they are moving between.
+- Start with context: summary table + “Should you upgrade?” checklist. Highlight deadlines with `` and call out optional paths with ``.
+- Break the body into **Plan → Migrate → Validate**. Use numbered headings inside **Migrate** and put rollback instructions directly after any risky step.
+- Document breaking changes with an `Old behavior` vs `New behavior` table. Use `` for mandatory verification steps.
+- Optional flow diagrams are allowed, but only when a left-to-right Mermaid (`graph LR`) clarifies the upgrade path.
+- End with two CTA cards (left = deep dive reference, right = applied example) and keep the comment reminder for reviewers.
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+Paste the block below, swap placeholders, and delete optional sections only after you’ve confirmed they aren’t needed.
+
+```mdx
+---
+title: [Migration title]
+description: [Why this upgrade matters]
+icon: "arrows-rotate"
+versionFrom: "[current version]"
+versionTo: "[target version]"
+releaseDate: "[YYYY-MM-DD]" # Optional
+---
+
+# [Migration headline — state the move]
+
+| Scope | Effort | Downtime |
+| --- | --- | --- |
+| [Platform/OSS/etc.] | [Low/Medium/High] ([~time]) | [Expected downtime impact] |
+
+
+ **Should you upgrade?**
+ - [Criteria 1]
+ - [Criteria 2]
+ - [Criteria 3]
+
+
+
+ [Breaking deadline or critical change. Remove if not needed.]
+
+
+## Timeline
+
+- [Date]: [Milestone]
+- [Date]: [Milestone]
+
+
+```mermaid
+graph LR
+ A[Plan] --> B[Migrate]
+ B --> C[Validate]
+ C --> D[Roll back if needed]
+```
+
+## Plan
+
+- [Actionable preparatory step]
+- [Stakeholder alignment or backup note]
+
+## Migrate
+
+### 1. [Upgrade dependencies]
+
+```bash
+pip install mem0ai==[version]
+npm install mem0ai@[version]
+```
+
+
+ [Optional hint or staging strategy.]
+
+
+
+ Run `[verification command]` and confirm it reports `[expected output]`.
+
+
+### 2. [Update configuration]
+
+```diff
+- memory_filters = true
++ filters = true
+```
+
+
+ **Breaking change:** `[Explain the new behavior and what to update]`.
+
+
+**Rollback:** `[Describe how to revert this specific step]`.
+
+### 3. [Run data migrations or API updates]
+
+```python
+[Code snippet showing new behavior]
+```
+
+
+ `[Describe logs, metrics, or sample response that proves success]`.
+
+
+## Validate
+
+- [ ] `[Smoke test or script]` returns expected result.
+- [ ] `[Dashboard or metric]` shows `[desired signal]`.
+- [ ] `[End-to-end scenario]` passes with `[new behavior]`.
+
+## Breaking changes
+
+| Old behavior | New behavior | Action |
+| --- | --- | --- |
+| `[Explain]` | `[Explain]` | `[What to change]` |
+| `[Explain]` | `[Explain]` | `[What to change]` |
+
+## Rollback plan
+
+1. `[Step-by-step rollback instructions]`
+2. `[Restore backups or redeploy previous image]`
+3. `[Validation after rollback]`
+
+## Known issues
+
+- **[Issue name]** — `[Status]`. `[Workaround or link]`.
+- **[Issue name]** — `[Status]`. `[Workaround or link]`.
+
+## After you migrate
+
+- `[Link to feature guide showing new capabilities]`
+- `[Link to cookbook or integration that benefits from the upgrade]`
+
+{/* DEBUG: verify CTA targets */}
+
+
+
+
+
+```
+
+---
+
+## ✅ Publish Checklist
+- [ ] Versions (`versionFrom`, `versionTo`) and timelines are accurate.
+- [ ] Every breaking change is highlighted via table or ``.
+- [ ] Rollback instructions are present and placed immediately after risky steps.
+- [ ] Verification steps use `` and are actionable.
+- [ ] Optional sections (Mermaid, tips) removed if unused.
+- [ ] Final `` contains exactly two cards with valid links.
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/operation_guide_template.mdx b/docs/templates/operation_guide_template.mdx
new file mode 100644
index 000000000..058996c6d
--- /dev/null
+++ b/docs/templates/operation_guide_template.mdx
@@ -0,0 +1,261 @@
+---
+title: Operation Guide Template
+description: "Checklist and skeleton for documenting a single Mem0 operation."
+icon: "circle-check"
+---
+
+# Operation Guide Template
+
+Operation guides focus on a single action (add, search, update, delete). Show the minimal path to execute it, verify the result, and route readers to references or applied guides.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Frontmatter needs `title`, `description`, `icon`. Title should be a verb phrase (“Add Memories”).
+- Lead with a two-sentence promise (problem → outcome), followed by an `` prerequisites block and optional `` for hazards (overwrites, rate limits).
+- Include a “When to pick this” bullet list (≤3 items) so readers confirm they’re in the right doc.
+- Use Tabs with Python and TypeScript examples. If only one SDK exists, add a `` stating that explicitly.
+- Provide `` verification after each critical step; call out the most common error with a `` close to where it can occur.
+- End with exactly two CTA cards: left = conceptual depth, right = applied example/cookbook.
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+
+````mdx
+---
+title: [Operation title]
+description: [Outcome in one sentence]
+icon: "bolt"
+---
+
+# [Operation headline — say what it does]
+
+[State the problem this solves.] [Explain the outcome after running it.]
+
+
+ **Prerequisites**
+ - [API key, project, runtime requirements]
+ - [Identifiers the reader needs ready]
+
+
+
+ [Optional: describe the main risk, e.g., duplicates or destructive behavior.]
+
+
+## When to pick this
+
+- [Scenario 1]
+- [Scenario 2]
+- [Scenario 3]
+
+## Configure access
+
+```bash
+export MEM0_API_KEY="sk-..."
+```
+
+
+ Already configured Mem0? Skip this and move to the next section.
+
+
+## Prepare inputs
+
+[Brief sentence describing payload requirements.]
+
+
+
+
+```python Python
+payload = {
+ "user_id": "alex",
+ "memory": "I am training for a marathon.",
+}
+```
+
+
+
+
+```typescript TypeScript
+const payload = {
+ userId: "alex",
+ memory: "I am training for a marathon.",
+};
+```
+
+
+
+
+## Call the operation
+
+
+
+
+```python Python
+from mem0 import Memory
+
+memory = Memory(api_key=os.environ["MEM0_API_KEY"])
+response = memory.add(payload)
+```
+
+
+
+
+```typescript TypeScript
+import { Memory } from "mem0ai/oss";
+
+const memory = new Memory({ apiKey: process.env.MEM0_API_KEY! });
+const response = await memory.add(payload);
+```
+
+
+
+
+
+ Expect `{"memory_id": "mem_123"}` (or similar). Keep this ID for updates or deletes.
+
+
+
+ `401 Unauthorized` usually means the API key is missing or scoped incorrectly.
+
+
+## Interpret the response
+
+| Field | Description |
+| --- | --- |
+| `memory_id` | Use to update or delete later. |
+| `created_at` | ISO 8601 timestamp for auditing. |
+
+
+ Need to upsert instead? Switch to the update operation and supply the `memory_id`.
+
+
+## Verify it worked
+
+- Check the Mem0 dashboard for the new memory entry.
+- Run the search operation with the same `user_id` and confirm it appears in results.
+
+## Common follow-ups
+
+- [Link to parameter reference]
+- [Link to complementary operation]
+- [Link to troubleshooting playbook section]
+
+
+
+
+
+
+
+````
+
+---
+
+## ✅ Publish Checklist
+- [ ] Intro states problem + outcome, and prerequisites are complete.
+- [ ] Python and TypeScript snippets stay in sync (or a `` clarifies missing parity).
+- [ ] Every major step includes an actionable ``.
+- [ ] Warnings cover the most likely failure mode near where it occurs.
+- [ ] CTA pair is present with valid links (concept left, cookbook right).
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/parameters_reference_template.mdx b/docs/templates/parameters_reference_template.mdx
new file mode 100644
index 000000000..190863645
--- /dev/null
+++ b/docs/templates/parameters_reference_template.mdx
@@ -0,0 +1,249 @@
+---
+title: Parameters Reference Template
+description: "Use this to document accepted fields, defaults, and example payloads."
+icon: "list"
+---
+
+# Parameters Reference Template
+
+Parameter references document every input/output detail for one operation after the quickstart/onboarding journey. Keep them scannable: signature, tables, examples, exits.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Frontmatter requires `title`, `description`, `icon`. Titles should mirror the operation (“Add Memories Parameters”).
+- Place canonical Python and TypeScript signatures right under the heading using ``. Mention defaults or breaking changes in an `` or `` immediately after.
+- Parameter table must include columns: Name, Type, Required, Description, Notes. Add a Managed/OSS distinction either as a column or in Notes.
+- Response table must include Field, Type, Description, Example. For nested objects, add subtables or `` JSON snippets beneath the row.
+- Examples section should show minimal Python and TypeScript calls with one-sentence explanations. If a language is missing, include a `` explaining why.
+- Finish with related operations, troubleshooting tied to parameter misuse, and a two-card CTA (operation guide on the left, cookbook/integration on the right).
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+
+````mdx
+---
+title: [Operation title] Parameters
+description: Full reference for `[client.method]` inputs and responses.
+icon: "table"
+---
+
+# [Operation title] Parameters
+
+
+```python Python
+client.memories.add(
+ user_id: str,
+ memory: str,
+ metadata: Optional[dict] = None,
+ memory_type: Literal["session", "long_term"] = "session",
+)
+```
+
+```ts TypeScript
+await mem0.memories.add({
+ userId: string;
+ memory: string;
+ metadata?: Record;
+ memoryType?: "session" | "long_term";
+});
+```
+
+
+
+ Defaults to session memories. Override `memory_type` for long-term storage.
+
+
+
+ [Optional: call out deprecated fields or upcoming removals.]
+
+
+## Parameters
+
+| Name | Type | Required | Description | Notes |
+| --- | --- | --- | --- | --- |
+| `user_id` | string | Yes | Unique identifier for the end user. | Must match follow-up operations. |
+| `memory` | string | Yes | Content to persist. | Managed & OSS. Markdown allowed. |
+| `metadata` | object | No | Key-value pairs for filters. | OSS stores as JSONB; limit to 2KB. |
+| `memory_type` | string | No | Retention bucket | Platform supports `shared`. |
+
+
+ Set `ttl_seconds` when you need memories to expire automatically (OSS only).
+
+
+## Response fields
+
+| Field | Type | Description | Example |
+| --- | --- | --- | --- |
+| `memory_id` | string | Identifier used for updates/deletes. | `mem_123` |
+| `created_at` | string (ISO 8601) | Timestamp when the memory was stored. | `2025-02-04T12:00:00Z` |
+| `metadata` | object | Echoed metadata (if provided). | `{ "team": "support" }` |
+
+```json
+{
+ "memory_id": "mem_123",
+ "memory": "I am training for a marathon.",
+ "metadata": {
+ "team": "support"
+ }
+}
+```
+
+## Examples
+
+
+
+
+```python Python
+response = client.memories.add(
+ user_id="alex",
+ memory="I am training for a marathon.",
+)
+print(response["memory_id"])
+```
+
+
+
+
+```typescript TypeScript
+const { memoryId } = await mem0.memories.add({
+ userId: "alex",
+ memory: "I am training for a marathon.",
+});
+console.log(memoryId);
+```
+
+
+
+
+These snippets confirm the method returns the new `memory_id` for follow-up operations.
+
+## Related operations
+
+- [Operation guide](./[operation-guide-slug])
+- [Complementary operation](./[secondary-operation-slug])
+
+## Troubleshooting
+
+- **`400 Missing user_id`** — Provide either `user_id` or `agent_id` in the payload.
+- **`422 Metadata too large`** — Reduce metadata size below 2KB (OSS hard limit).
+
+
+
+
+
+
+
+````
+
+---
+
+## ✅ Publish Checklist
+- [ ] Python and TypeScript signatures match the current SDKs (or a `` explains missing parity).
+- [ ] Parameter and response tables cover every field with clear Managed vs OSS notes.
+- [ ] Examples execute the minimal happy path and include one-line explanations.
+- [ ] Troubleshooting entries correspond to parameter misuse or validation errors.
+- [ ] CTA pair links to the operation guide (left) and an applied example (right).
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/quickstart_template.mdx b/docs/templates/quickstart_template.mdx
new file mode 100644
index 000000000..fb31c47fd
--- /dev/null
+++ b/docs/templates/quickstart_template.mdx
@@ -0,0 +1,333 @@
+---
+title: Quickstart Template
+description: "Guidance and skeleton for Mem0 quickstart documentation."
+icon: "rocket"
+---
+
+# Quickstart Template
+
+Quickstarts are the fastest path to first success. Each page should configure the minimum viable setup for its section, execute one complete add/search/delete loop, and hand readers off to deeper docs once the core flow succeeds.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Keep the intro tight: one-sentence promise + `` prerequisites. Add `` only for blocking requirements (e.g., “requires paid tier”).
+- Default to Python + TypeScript examples inside `` with `` per language. If a second language truly doesn’t exist, add a `` explaining why.
+- Every journey must follow **Install → Configure → Add → Search → Delete** (or closest equivalents). Drop verification `` immediately after the critical operation.
+- If you include a Mermaid diagram, keep it optional and render left-to-right (`graph LR`) so it doesn’t flood the page.
+- End with exactly two CTA cards: left = related/alternative path, right = next step in the journey. No link farms.
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+Paste the block below into a new quickstart, then replace **every** placeholder. Remove optional sections only after the happy path is working.
+
+````mdx
+---
+title: [Quickstart title — action focused]
+description: [1 sentence outcome]
+icon: "rocket"
+estimatedTime: "[~X minutes]"
+---
+
+# [Hero headline — promise the win]
+
+
+ **Prerequisites**
+ - [SDK/Runtime requirement]
+ - [API key or account requirement]
+ - [Any optional tooling the reader might want]
+
+
+
+ [Optional: cross-link to OSS or platform alternative if applicable. Delete if unused.]
+
+
+
+```mermaid
+graph LR
+ A[Install] --> B[Configure keys]
+ B --> C[Add memory]
+ C --> D[Search]
+ D --> E[Delete]
+```
+
+## Install dependencies
+
+
+
+
+
+```bash
+pip install [package-name]
+```
+
+
+
+
+
+
+```bash
+npm install [package-name]
+```
+
+
+
+
+
+[Explain why the install matters in one sentence.]
+
+## Configure access
+
+
+
+
+
+```bash
+export MEM0_API_KEY="sk-..."
+```
+
+
+```python
+from mem0 import Memory
+
+memory = Memory(api_key="sk-...")
+```
+
+
+
+
+
+
+```bash
+export MEM0_API_KEY="sk-..."
+```
+
+
+```typescript
+import { Memory } from "mem0ai";
+
+const memory = new Memory({ apiKey: process.env.MEM0_API_KEY! });
+```
+
+
+
+
+
+
+ [Optional: call out the most common setup failure and how to fix it.]
+
+
+## Add your first memory
+
+
+
+
+
+```python
+messages = [
+ {"role": "user", "content": "Hi, I'm Alex and I love basketball."},
+ {"role": "assistant", "content": "Noted! I'll remember that."},
+]
+
+memory.add(messages, user_id="alex")
+```
+
+
+
+
+
+
+```typescript
+const messages = [
+ { role: "user", content: "Hi, I'm Alex and I love basketball." },
+ { role: "assistant", content: "Noted! I'll remember that." },
+];
+
+await memory.add(messages, { userId: "alex" });
+```
+
+
+
+
+
+
+ Expected output: `[Describe the success log or console output]`. If you see `[common error]`, jump to the troubleshooting section.
+
+
+## Search the memory
+
+
+
+
+
+```python
+result = memory.search("What does Alex like?", filters={"user_id": "alex"})
+print(result)
+```
+
+
+
+
+
+
+```typescript
+const result = await memory.search("What does Alex like?", { userId: "alex" });
+console.log(result);
+```
+
+
+
+
+
+
+ You should see `[show the key fields]`. Screenshot or paste real output when possible.
+
+
+## Delete the memory
+
+
+
+
+
+```python
+memory.delete_all(user_id="alex")
+```
+
+
+
+
+
+
+```typescript
+await memory.deleteAll({ userId: "alex" });
+```
+
+
+
+
+
+## Quick recovery
+
+- `[Error message]` → `[One-line fix or link to troubleshooting guide]`
+- `[Second error]` → `[How to resolve]`
+
+
+
+
+
+
+
+````
+
+---
+
+## ✅ Publish Checklist
+- [ ] Replace every placeholder and delete unused sections (``, Mermaid diagram, etc.).
+- [ ] Python **and** TypeScript tabs render correctly (or you added a `` explaining a missing language).
+- [ ] Each major step includes an inline verification ``.
+- [ ] Quick recovery section lists at least two common issues.
+- [ ] Final `` has exactly two cards (related on the left, next step on the right).
+- [ ] Links, commands, and code snippets were tested or clearly marked if hypothetical.
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/release_notes_template.mdx b/docs/templates/release_notes_template.mdx
new file mode 100644
index 000000000..aa32b6dc4
--- /dev/null
+++ b/docs/templates/release_notes_template.mdx
@@ -0,0 +1,209 @@
+---
+title: Release Notes Template
+description: "Format for concise launch summaries with clear CTAs."
+icon: "megaphone"
+---
+
+# Release Notes Template
+
+Release notes are heartbeat updates. They tell readers what shipped, what needs attention, and where to go for the deep dive—fast.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Frontmatter must include `title`, `description`, `icon`, `releaseDate`, and `version`. Add `tags` if you need filters (e.g., `["platform", "oss"]`).
+- Lead with a one-sentence headline plus a quick stats table (New features, Fixes, Required action). Keep the TL;DR in an `` block; use `` only for breaking changes or deadlines.
+- Organize the body into Highlights, Improvements & fixes (grouped by product), and Known issues. Each bullet links to docs where appropriate.
+- Include an Upgrade checklist with concrete next steps. Optional “Community shout-outs” should remain short.
+- Two-card CTA at the end, as always: left = deeper reference, right = applied next step.
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+Paste the snippet below, swap placeholders, and trim optional sections only once you know they’re unnecessary.
+
+```mdx
+---
+title: [Release title]
+description: [1 sentence summary of the release]
+icon: "sparkles"
+releaseDate: "[YYYY-MM-DD]"
+version: "[X.Y]"
+tags: ["platform", "oss"] # Optional filters
+---
+
+# [Release at a glance]
+
+[Hero sentence that states the biggest win.]
+
+| New features | Fixes | Required action |
+| --- | --- | --- |
+| [#] | [#] | [Required/Optional + short note] |
+
+
+ **TL;DR**
+ - [Highlight #1]
+ - [Highlight #2]
+ - [Highlight #3]
+
+
+
+ [Breaking change or deadline reminder. Remove if not needed.]
+
+
+## Highlights
+
+- **[Feature name]** — [One-sentence benefit]. [Link to doc]
+- **[Feature name]** — [One-sentence benefit]. [Link to doc]
+- **[Feature name]** — [One-sentence benefit]. [Link to doc]
+
+## Improvements & fixes
+
+**Platform**
+- [Improvement sentence with link if relevant.]
+- [Fix sentence.]
+
+**Open Source**
+- [Improvement sentence.]
+
+**SDKs**
+- Python: `[Change summary]`.
+- TypeScript: `[Change summary]`.
+
+
+ [Optional activation hint, e.g., “Enable the feature in Settings → Labs.”]
+
+
+## Known issues
+
+- **[Issue name]** — `[Status]`. `[Workaround or link].`
+- **[Issue name]** — `[Status]`. `[Workaround or link].`
+
+## Upgrade checklist
+
+- [ ] `[Step 1 — update package or config]`
+- [ ] `[Step 2 — run migration or toggle setting]`
+- [ ] `[Step 3 — verify workflow or metric]`
+
+## Community shout-outs
+
+- [Contributor or team] — `[Short thank-you message].`
+
+
+
+
+
+
+
+```
+
+---
+
+## ✅ Publish Checklist
+- [ ] Headline sentence and stats table reflect the release accurately.
+- [ ] Every highlight, improvement, and issue links to supporting docs when available.
+- [ ] `` only appears when a deadline or breaking change exists.
+- [ ] Upgrade checklist lists concrete steps (not vague reminders).
+- [ ] Exactly two CTA cards at the end with valid links.
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/section_overview_template.mdx b/docs/templates/section_overview_template.mdx
new file mode 100644
index 000000000..a6c493cfa
--- /dev/null
+++ b/docs/templates/section_overview_template.mdx
@@ -0,0 +1,193 @@
+---
+title: Section Overview Template
+description: "Blueprint for landing pages with headline, card grid, and CTAs."
+icon: "grid"
+---
+
+# Section Overview Template
+
+Overview pages orient readers for an entire section. Summarize who it’s for, surface the core journeys, and end with a clear “build vs explore” CTA pair.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Frontmatter must include `title`, `description`, `icon`. Keep the hero paragraph under two sentences describing audience + outcome.
+- Provide an `` block pointing to the primary entry point (usually the quickstart). Use `` only for major caveats (beta, deprecation).
+- Card grids should list 4–6 journeys max using `` or ``. Copy must stay ≤15 words, and every card needs an icon + link.
+- Optional visuals (comparison table, Mermaid diagram) should be left-to-right and only added when they reduce confusion.
+- Finish with exactly two CTA cards: left = adjacent/alternative track, right = next logical step deeper in the section.
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+
+````mdx
+---
+title: [Section name] Overview
+description: [30-second summary of what lives in this section]
+icon: "compass"
+---
+
+# [Section] Overview
+
+[State who this section is for.] [Explain what they’ll accomplish after browsing these docs.]
+
+
+ Start with [Quickstart link] if you’re new, then choose a deeper topic below.
+
+
+
+```mermaid
+graph LR
+ A[Get set up] --> B[Learn concepts]
+ B --> C[Build workflows]
+ C --> D[Support & scale]
+```
+
+## Choose your path
+
+
+
+ [One-line outcome]
+
+
+ [One-line outcome]
+
+
+ [One-line outcome]
+
+
+ [One-line outcome]
+
+
+ [One-line outcome]
+
+
+ [One-line outcome]
+
+
+
+
+ [Optional cross-link, e.g., “Self-hosting? Jump to the OSS overview.”] Delete if unused.
+
+
+## Keep going
+
+
+
+
+
+
+
+````
+
+---
+
+## ✅ Publish Checklist
+- [ ] Hero paragraph states audience + outcome; `` points to the primary entry point.
+- [ ] Card grid lists 4–6 journeys with concise copy and valid icons/links.
+- [ ] Optional visuals (tables/Mermaid) are LR and actually clarify the flow.
+- [ ] CTA pair present with related alternative on the left and next logical step on the right.
+- [ ] All placeholders and unused callouts removed before publishing.
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/templates/troubleshooting_playbook_template.mdx b/docs/templates/troubleshooting_playbook_template.mdx
new file mode 100644
index 000000000..c3d40534c
--- /dev/null
+++ b/docs/templates/troubleshooting_playbook_template.mdx
@@ -0,0 +1,216 @@
+---
+title: Troubleshooting Playbook Template
+description: "Runbook structure for diagnosing and fixing common issues."
+icon: "life-buoy"
+---
+
+# Troubleshooting Playbook Template
+
+Troubleshooting playbooks map symptoms to diagnostics and fixes. Keep them fast to scan, script-friendly, and closed with prevention tips plus next steps.
+
+---
+
+## ❌ DO NOT COPY — Guidance & Constraints
+- Frontmatter must include `title`, `description`, `icon`. Lead with one sentence about the system or workflow this playbook covers.
+- Add an `` block (“Use this when…”) and a quick index table (Symptom, Likely cause, Fix link). Surface critical safety warnings in ``.
+- Each symptom section needs: diagnostic command/snippet, `` expected output, `` for the observed failure, numbered fix steps, and optional `` for prevention.
+- Group unrelated issues with horizontal rules and provide escalation guidance when self-service stops.
+- Conclude with prevention checklist, related docs, and the standard two-card CTA (concept/reference left, applied workflow right).
+
+---
+
+## ✅ COPY THIS — Content Skeleton
+
+````mdx
+---
+title: [Playbook name]
+description: Diagnose and resolve [system/component] issues.
+icon: "stethoscope"
+---
+
+# [Playbook headline]
+
+[One sentence describing the scope of this playbook.]
+
+
+ **Use this when…**
+ - [Trigger symptom]
+ - [Trigger symptom]
+ - [Trigger symptom]
+
+
+## Quick index
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| [Error code/message] | [Cause] | [Link to section] |
+| [Error code/message] | [Cause] | [Link to section] |
+
+
+ [Optional safety note (data loss, downtime risk). Remove if unnecessary.]
+
+
+## Symptom: [Name]
+
+Run this check:
+
+```bash
+[diagnostic command]
+```
+
+
+ Expected: `[describe success signal]`.
+
+
+
+ Actual: `[describe failure output]`.
+
+
+**Fix**
+1. [Step]
+2. [Step]
+3. [Step]
+
+
+ [Preventative measure or best practice.]
+
+
+---
+
+## Symptom: [Next issue]
+
+[Repeat pattern above.]
+
+## Escalate when
+
+- [Status/case when self-service ends]
+- Contact `[support channel]` with `[logs]`
+
+## Prevention checklist
+
+- [Habit/monitoring item]
+- [Habit/monitoring item]
+
+## Related docs
+
+- [Feature or integration doc]
+- [Runbook or SLO doc]
+
+
+
+
+
+
+
+````
+
+---
+
+## ✅ Publish Checklist
+- [ ] Quick index table includes every symptom covered below.
+- [ ] Each symptom section documents diagnostics, expected vs actual output, and actionable fix steps.
+- [ ] Preventative tips and escalation guidance are present where relevant.
+- [ ] Prevention checklist and related docs point to current resources.
+- [ ] CTA pair links to concept/reference (left) and applied workflow (right).
+
+## Browse Other Templates
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+