docs: Write quetza docs

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

@@ -0,0 +1,14 @@
+---
+title: Concepts
+weight: 4
+---
+
+
+**Quetza** concepts explain the *Why* and *How* behind the framework's design. These documents cover the underlying philosophy and architectural decisions.
+
+## Key Topics
+
+{{% cards %}}
+  {{< card link="architecture" title="Architecture & Philosophy" icon="scale" subtitle="Design principles: Convention over Configuration, Composition, and Isolation." >}}
+  {{< card link="module-system" title="The Module System" icon="template" subtitle="Understanding Clients, Modules, Controllers, and Events." >}}
+{{% /cards %}}

services/docs/content/en/quetza/concepts/architecture.md

@@ -0,0 +1,38 @@
+---
+title: Architecture & Philosophy
+weight: 1
+---
+
+
+**Goal:** Understand the core design principles that drive Quetza's modularity.
+
+## Design Philosophies
+
+### Convention Over Configuration
+Quetza minimizes boilerplate by relying on strict folder structures.
+*   **No central registry:** The filesystem *is* the registry.
+*   **Result:** You don't update a config file to add a module; you just create the folder.
+
+### Composition Over Inheritance
+Modules are composed of capabilities, not inherited from a base class.
+*   **Flexibility:** Modules can use any internal architecture (Functional, OOP) as long as they export the required interfaces.
+
+### Isolation Over Integration
+Modules cannot directly invoke each other.
+*   **Why:** Prevents tight coupling.
+*   **Benefit:** You can delete any module without breaking the rest of the bot.
+
+## Core Entities
+
+| Entity | Role | Lifecycle |
+| :--- | :--- | :--- |
+| **Client** | Service Locator & Orchestrator | Singleton. Runs the show. |
+| **Module** | Namespace for features | Loaded at startup. |
+| **Command** | User Interaction Endpoint | Stateless. Request/Response. |
+| **Event** | Reactive Observer | Subscribed at startup. |
+| **Controller** | State Manager | Persists across interactions. |
+
+---
+**See also:**
+- [Service Locator Pattern](https://en.wikipedia.org/wiki/Service_locator_pattern)
+- [Observer Pattern](https://en.wikipedia.org/wiki/Observer_pattern)

services/docs/content/en/quetza/concepts/module-system.md

@@ -0,0 +1,54 @@
+---
+title: The Module System
+weight: 2
+---
+
+
+**Goal:** Define the vocabulary and mechanics of Quetza's primary abstraction unit.
+
+## System Vocabulary
+
+### Module Declaration
+The `module.ts` file acts as the manifest. It is the entry point for discovery.
+```typescript
+export const name = 'my-module'; // ID
+export const description = '...'; // Doc
+```
+
+### Command Registration
+Occurs during the `ready` event.
+1.  Quetza scans all `commands/` folders.
+2.  Compiles `ApplicationCommandData`.
+3.  PUTs the payload to Discord's API.
+
+### Controller Injection
+State is injected, not imported.
+```typescript
+// The framework calls this:
+execute(client, interaction, controller)
+```
+*   **Why?** Allows the framework to manage the controller's lifecycle (singleton per module).
+
+## State Management Philosophy
+
+### Ephemeral by Default
+Quetza provides **no built-in database**.
+*   **Memory:** Controllers store state in JS `Map` or `Set` objects.
+*   **Restart:** All state is lost when the process exits.
+*   **Persistence:** Must be implemented manually (e.g., SQLite, Redis) inside the Controller.
+
+### Scope as Key
+State must be keyed by its boundary.
+*   `Map<GuildID, ...>` - Server specific (Most common).
+*   `Map<UserID, ...>` - User specific (DM bots).
+
+## Error Handling Model
+
+**Fail Fast & Friendly.**
+*   **Validation:** Check permissions/inputs immediately.
+*   **User-Facing:** "You don't have permission" (Not "Error: 403").
+*   **Isolation:** A crash in `/ping` catches itself and doesn't kill the bot.
+
+---
+**See also:**
+- [Discord Interaction Lifecycle](https://discord.com/developers/docs/interactions/receiving-and-responding)