docs: Write quetza docs

services/docs/content/en/quetza/recipes/_index.md

@@ -0,0 +1,14 @@
+---
+title: Recipes
+weight: 3
+---
+
+
+**Quetza** recipes are strategic architectural patterns for common functional requirements. They focus on *how* to compose framework features to solve business problems.
+
+## Recipe Categories
+
+{{% cards %}}
+  {{< card link="voice-features" title="Interactive Voice Features" icon="users" subtitle="Managing audio players and guild-scoped state." >}}
+  {{< card link="conversational-ai" title="Conversational AI" icon="chip" subtitle="Handling LLM context and long-running responses." >}}
+{{% /cards %}}

services/docs/content/en/quetza/recipes/conversational-ai.md

@@ -0,0 +1,50 @@
+---
+title: Conversational AI Integration
+weight: 2
+---
+
+
+**Goal:** Integrate Large Language Models (LLMs) while managing context and Discord's timeout constraints.
+
+## 1. Context Management Strategy
+Conversations require history to be coherent.
+*   **Scoping:** `Map<GuildID, Map<UserID, Message[]>>`
+    *   **Guild Key:** Prevents cross-server leaks.
+    *   **User Key:** Prevents cross-user confusion in public channels.
+*   **Lifecycle:** Implement a rolling window (e.g., last 50 messages) to prevent context bloat.
+
+## 2. Response Streaming
+LLMs are slow; Discord is fast (3s timeout).
+
+{{% steps %}}
+### Step 1: Defer Interaction
+Immediately call `interaction.deferReply()`. This buys you 15 minutes.
+
+### Step 2: Invoke LLM
+Call your AI service asynchronously.
+
+### Step 3: Edit Response
+When data arrives, use `interaction.editReply(content)`.
+{{% /steps %}}
+
+## 3. Implementation Sketch
+
+```typescript
+// commands/chat.ts
+export async function execute(interaction, controller) {
+  // 1. Defer
+  await interaction.deferReply();
+
+  // 2. Process
+  const history = controller.getHistory(interaction.guildId, interaction.user.id);
+  const response = await aiService.generate(interaction.options.getString('prompt'), history);
+
+  // 3. Respond
+  await interaction.editReply(response);
+  controller.updateHistory(interaction.guildId, interaction.user.id, response);
+}
+```
+
+> [!WARNING]
+> **API Costs:**
+> AI APIs are often billed by token. Implement strict user-based rate limits in your Controller to prevent abuse.

services/docs/content/en/quetza/recipes/voice-features.md

@@ -0,0 +1,58 @@
+---
+title: Interactive Voice Features
+weight: 1
+---
+
+
+**Goal:** Implement sophisticated voice interactions that respect guild boundaries and manage ephemeral resources.
+
+## 1. Resource Scoping Strategy
+Voice features **MUST** be scoped to the Guild.
+*   **Pattern:** The Controller maintains a `Map<GuildID, Player>`.
+*   **Behavior:**
+    *   **Join:** Create a Player for `Guild A` if none exists.
+    *   **Leave:** Destroy the Player and release connections.
+    *   **Isolation:** Commands in `Guild B` never affect `Guild A`.
+
+## 2. Command Orchestration
+Voice features require a suite of commands coordinated via the Controller.
+
+| Command | Action | Controller Logic |
+| :--- | :--- | :--- |
+| `/join` | Connect to channel | `createPlayer(guildId, channelId)` |
+| `/play` | Add track to queue | `getPlayer(guildId).enqueue(track)` |
+| `/stop` | Disconnect | `destroyPlayer(guildId)` |
+
+## 3. State Persistence
+Audio sessions are ephemeral.
+*   **Transient State:** Active audio stream (Lost on disconnect).
+*   **Durable State:** Queue/Playlist (Persisted in Controller until restart).
+
+> [!TIP]
+> **Resilience:** Separate the *Queue* logic from the *Voice Connection* logic. This allows the bot to reconnect without losing the user's playlist.
+
+## 4. Implementation Sketch
+
+```typescript
+// lib/MusicController.ts
+class MusicController {
+  private players = new Map<string, AudioPlayer>();
+
+  getPlayer(guildId: string): AudioPlayer {
+    if (!this.players.has(guildId)) {
+      this.players.set(guildId, new AudioPlayer());
+    }
+    return this.players.get(guildId);
+  }
+
+  destroyPlayer(guildId: string) {
+    this.players.get(guildId)?.disconnect();
+    this.players.delete(guildId);
+  }
+}
+```
+
+---
+
+**See also:**
+- [Discord.js Voice Guide](https://discordjs.guide/voice/)