Release v1.0 refactor.

.gitignore

@@ -186,7 +186,7 @@ cython_debug/
 #   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #   and can be added to the global gitignore or merged into this file.  For a more nuclear
 #   option (not recommended) you can uncomment the following to ignore the entire idea folder.
-# .idea/
+.idea/
 
 # Abstra
 #   Abstra is an AI-powered process automation framework.

.pre-commit-config.yaml

@@ -24,7 +24,7 @@ repos:
     hooks:
       - id: ty
         name: ty
-        entry: ty check
+        entry: uv run ty check
         language: system
         types: [python]
         pass_filenames: false

.vscode/settings.json

@@ -0,0 +1,4 @@
+{
+  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
+  "python.analysis.extraPaths": ["${workspaceFolder}"]
+}

AGENTS.md

@@ -1,168 +1,223 @@
-# Scalable Cog & Interaction Patterns
+# Capy Discord Agent & Contributor Guide
 
-This document outlines the architectural patterns used in the `capy-discord` project to ensure scalability, clean code, and a consistent user experience. All agents and contributors should adhere to these patterns when creating new features.
+This document outlines the architectural patterns, workflows, and standards for the `capy-discord` project. All agents and contributors must adhere to these guidelines to ensure scalability and code consistency.
 
 ## 1. Directory Structure
 
-We follow a hybrid "Feature Folder" structure. Directories are created only as needed for complexity.
+We follow a flexible modular structure within `capy_discord/exts/`.
 
-```
+### Guidelines
+1.  **Feature Folders**: Complex features get their own directory (e.g., `exts/profile/`).
+2.  **Internal Helpers**: Helper files in a feature folder (schemas, views) **must be prefixed with an underscore** (e.g., `_schemas.py`) to prevent the extension loader from treating them as cogs.
+3.  **Grouping**: Use directories like `exts/tools/` to group simple, related cogs.
+4.  **Single File Cogs**: Simple cogs can live directly in `exts/` or a grouping directory.
+
+```text
 capy_discord/
 ├── exts/
-│   ├── profile/          # Complex Feature (Directory)
-│   │   ├── __init__.py   # Cog entry point
-│   │   ├── schemas.py    # Feature-specific models
-│   │   └── views.py      # Feature-specific UI
-│   ├── ping.py           # Simple Feature (Standalone file)
+│   ├── guild.py            # Simple Cog
+│   ├── tools/              # Grouping directory
+│   │   ├── ping.py
+│   │   └── sync.py
+│   ├── profile/            # Complex Feature (Directory)
+│   │   ├── profile.py      # Main Cog file (shares directory name)
+│   │   ├── _schemas.py     # Helper (ignored by loader)
+│   │   └── _views.py       # Helper (ignored by loader)
 │   └── __init__.py
 ├── ui/
-│   ├── modal.py          # Shared UI components
-│   ├── views.py          # BaseView and shared UI
-│   └── ...
+│   ├── forms.py            # ModelModal (Standard Forms)
+│   ├── views.py            # BaseView (Standard Interactions)
+│   └── modal.py            # Low-level base classes
 └── bot.py
 ```
 
-## 2. The `CallbackModal` Pattern (Decoupled UI)
+## 2. UI Patterns
+
+We use high-level abstractions to eliminate boilerplate.
+
+### Standard Forms (`ModelModal`)
+**Use for:** Data collection and user input.
+Do not subclass `BaseModal` manually for standard forms. Use `ModelModal` to auto-generate forms from Pydantic models.
 
-To prevent business logic from leaking into UI classes, we use the `CallbackModal` pattern. This keeps Modal classes "dumb" (pure UI/Validation) and moves logic into the Controller (Cog/Service).
+*   **Auto-Generation**: Converts Pydantic fields to TextInputs.
+*   **Validation**: Validates input against schema on submit.
+*   **Retry**: Auto-handles validation errors with a "Fix Errors" flow.
 
-### Usage
+```python
+from capy_discord.ui.forms import ModelModal
+
+class UserProfile(BaseModel):
+    name: str = Field(title="Display Name", max_length=20)
+
+# In your command:
+modal = ModelModal(UserProfile, callback=self.save_profile, title="Edit Profile")
+await interaction.response.send_modal(modal)
+```
 
-1.  **Inherit from `CallbackModal`**: located in `capy_discord.ui.modal`.
-2.  **Field Limit**: **Discord modals can only have up to 5 fields.** If you need more data, consider using multiple steps or splitting the form.
-3.  **Dynamic Initialization**: Use `__init__` to accept `default_values` for "Edit" flows.
-3.  **Inject Logic**: Pass a `callback` function from your Cog that handles the submission.
+### Interactive Views (`BaseView`)
+**Use for:** Buttons, Selects, and custom interactions.
+Always inherit from `BaseView` instead of `discord.ui.View`.
 
-**Example:**
+*   **Safety**: Handles timeouts and errors automatically.
+*   **Tracking**: Use `view.reply(interaction, ...)` to link view to message.
 
 ```python
-# In your Cog file
-class MyModal(CallbackModal):
-    def __init__(self, callback, default_text=None):
-        super().__init__(callback=callback, title="My Modal")
-        self.text_input = ui.TextInput(default=default_text, ...)
-        self.add_item(self.text_input)
+from capy_discord.ui.views import BaseView
 
-class MyCog(commands.Cog):
-    ...
-    async def my_command(self, interaction):
-        modal = MyModal(callback=self.handle_submit)
-        await interaction.response.send_modal(modal)
-
-    async def handle_submit(self, interaction, modal):
-        # Business logic here!
-        value = modal.text_input.value
-        await interaction.response.send_message(f"You said: {value}")
+class ConfirmView(BaseView):
+    @discord.ui.button(label="Confirm")
+    async def confirm(self, interaction, button):
+        ...
 ```
 
-## 3. Command Structure (Single Entry Point)
+### Simple Inputs (`CallbackModal`)
+**Use for:** Simple one-off inputs where a full Pydantic model is overkill.
 
-To avoid cluttering the Discord command list, prefer a **Single Command with Choices** or **Subcommands** over multiple top-level commands.
+```python
+from capy_discord.ui.modal import CallbackModal
+modal = CallbackModal(callback=my_handler, title="Quick Input")
+```
 
-### Pattern: Action Choices
+## 3. Command Patterns
 
-Use `app_commands.choices` to route actions within a single command. This is preferred for CRUD operations on a single resource (e.g., `/profile`).
+### Action Choices (CRUD)
+For managing a single resource, use one command with `app_commands.choices`.
 
 ```python
-@app_commands.command(name="resource", description="Manage resource")
-@app_commands.describe(action="The action to perform")
-@app_commands.choices(
-    action=[
-        app_commands.Choice(name="create", value="create"),
-        app_commands.Choice(name="view", value="view"),
-    ]
-)
-async def resource(self, interaction: discord.Interaction, action: str):
-    if action == "create":
-        await self.create_handler(interaction)
-    elif action == "view":
-        await self.view_handler(interaction)
+@app_commands.choices(action=[
+    Choice(name="create", value="create"),
+    Choice(name="view", value="view"),
+])
+async def resource(self, interaction, action: str):
+    ...
 ```
 
-## 4. Extension Loading
+### Group Cogs
+For complex features with multiple distinct sub-functions, use `commands.GroupCog`.
 
-Extensions should be robustly discoverable. Our `extensions.py` utility supports deeply nested subdirectories.
+## 4. Internal DM Service
 
-- **Packages (`__init__.py` with `setup`)**: Loaded as a single extension.
-- **Modules (`file.py`)**: Loaded individually.
-- **Naming**: Avoid starting files/folders with `_` unless they are internal helpers.
+Direct messaging is an internal service, **not** a user-facing cog. Do not add `/dm`-style command surfaces for bulk messaging.
 
-## 5. Deployment & Syncing
+### Location
+Use:
 
-- **Global Sync**: Done automatically on startup for consistent deployments.
-- **Dev Guild**: A specific Dev Guild ID can be targeted for rapid testing and clearing "ghost" commands.
-- **Manual Sync**: A `!sync` (text) command is available for emergency re-syncing without restarting.
+*   `capy_discord.services.dm`
+*   `capy_discord.services.policies`
 
-## 6. Time and Timezones
+### Safety Model
+*   DM sends are **deny-all by default** via `policies.DENY_ALL`.
+*   Developers must opt into explicit allowlists with helpers like `policies.allow_users(...)`, `policies.allow_roles(...)`, or `policies.allow_targets(...)`.
+*   The service rejects `@everyone`, rejects targets outside the allowed policy, and enforces `max_recipients`.
 
-To prevent bugs related to naive datetimes, **always use `zoneinfo.ZoneInfo`** for timezone-aware datetimes.
+### Usage Pattern
+Developers should think in terms of:
 
-- **Default Timezone**: Use `UTC` for database storage and internal logic.
-- **Library**: Use the built-in `zoneinfo` module (available in Python 3.9+).
+1.  The exact user or role to DM.
+2.  The predefined policy that permits that target.
 
-**Example:**
+Prefer explicit entrypoints over generic audience bags:
 
 ```python
-from datetime import datetime
-from zoneinfo import ZoneInfo
+from capy_discord.services import dm, policies
+
+EVENT_POLICY = policies.allow_roles(EVENT_ROLE_ID, max_recipients=20)
 
-# Always specify tzinfo
-now = datetime.now(ZoneInfo("UTC"))
+draft = await dm.compose_to_role(
+    guild,
+    EVENT_ROLE_ID,
+    "Reminder: event starts at 7 PM.",
+    policy=EVENT_POLICY,
+)
+result = await dm.send(guild, draft)
 ```
 
-## 7. Development Workflow
+For self-test or single-user flows, use `dm.compose_to_user(...)` with `policies.allow_users(...)`.
+
+### Cog Usage
+If you need an operator-facing entrypoint for DM functionality, keep it narrow and task-specific rather than exposing a generic DM surface.
+
+Use a small cog command only for explicit, safe flows such as self-test notifications:
+
+```python
+from capy_discord.services import dm, policies
 
-We use `uv` for dependency management and task execution. This ensures all commands run within the project's virtual environment.
+policy = policies.allow_users(interaction.user.id, max_recipients=1)
 
-### Running Tasks
+draft = await dm.compose_to_user(
+    guild,
+    interaction.user.id,
+    message,
+    policy=policy,
+)
+self.log.info("Notify preview\n%s", dm.render_preview(draft))
 
-Use `uv run task <task_name>` to execute common development tasks defined in `pyproject.toml`.
+result = await dm.send(guild, draft)
+```
 
-- **Start App**: `uv run task start`
-- **Lint & Format**: `uv run task lint`
-- **Run Tests**: `uv run task test`
-- **Build Docker**: `uv run task build`
+This pattern is implemented in `capy_discord/exts/tools/notify.py`. Do not add broad `/dm` or bulk-message commands; use explicit commands tied to a specific feature or operational workflow.
 
-**IMPORTANT: After every change, run `uv run task lint` to perform a Ruff and Type check.**
+## 5. Error Handling
+We use a global `on_tree_error` handler in `bot.py`.
+*   Exceptions are logged with the specific module name.
+*   Do not wrap every command in `try/except` blocks unless handling specific business logic errors.
 
-### Running Scripts
+## 6. Logging
+All logs follow a standardized format for consistency across the console and log files.
 
-To run arbitrary scripts or commands within the environment:
+*   **Format**: `[{asctime}] [{levelname:<8}] {name}: {message}`
+*   **Date Format**: `%Y-%m-%d %H:%M:%S`
+*   **Usage**: Always use `logging.getLogger(__name__)` to ensure logs are attributed to the correct module.
 
-```bash
-uv run python path/to/script.py
+```python
+import logging
+self.log = logging.getLogger(__name__)
+self.log.info("Starting feature X")
 ```
 
-## 8. Git Commit Guidelines
+## 7. Time and Timezones
+**Always use `zoneinfo.ZoneInfo`**.
+*   **Storage**: `UTC`.
+*   **Usage**: `datetime.now(ZoneInfo("UTC"))`.
 
-### Pre-Commit Hooks
+## 8. Development Workflow
 
-This project uses pre-commit hooks for linting. If a hook fails during commit:
+### Linear & Branching
+*   **Issue Tracking**: Every task must have a Linear issue.
+*   **Branching**:
+    *   `feature/CAPY-123-description`
+    *   `fix/CAPY-123-description`
+    *   `refactor/` | `docs/` | `test/`
 
-1. **DO NOT** use `git commit --no-verify` to bypass hooks.
-2. **DO** run `uv run task lint` manually to verify and fix issues.
-3. If `uv run task lint` passes but the hook still fails (e.g., executable not found), there is likely an environment issue with the pre-commit config that needs to be fixed.
+### Dependency Management (`uv`)
+Always run commands via `uv` to use the virtual environment.
 
-### Cog Initialization Pattern
+*   **Start**: `uv run task start`
+*   **Lint**: `uv run task lint` (Run this before every commit!)
+*   **Test**: `uv run task test`
 
-All Cogs **MUST** accept the `bot` instance as an argument in their `__init__` method:
+### Commit Guidelines (Conventional Commits)
+Format: `<type>(<scope>): <subject>`
+
+*   `feat(auth): add login flow`
+*   `fix(ui): resolve timeout issue`
+*   Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`.
+
+### Pull Requests
+1.  **Base Branch**: Merge into `develop`.
+2.  **Reviewers**: Must include `Shamik` and `Jason`.
+3.  **Checks**: All CI checks (Lint, Test, Build) must pass.
+
+## 9. Cog Standards
+
+### Initialization
+All Cogs **MUST** accept the `bot` instance in `__init__`. The use of the global `capy_discord.instance` is **deprecated** and should not be used in new code.
 
 ```python
-# CORRECT
 class MyCog(commands.Cog):
     def __init__(self, bot: commands.Bot) -> None:
         self.bot = bot
 
 async def setup(bot: commands.Bot) -> None:
     await bot.add_cog(MyCog(bot))
-
-# INCORRECT - Do not use global instance or omit bot argument
-class MyCog(commands.Cog):
-    def __init__(self) -> None:  # Missing bot!
-        pass
 ```
-
-This ensures:
-- Proper dependency injection
-- Testability (can pass mock bot)
-- No reliance on global state