# Setup & Quickstart

Morse agents (Dot and Dash) are designed to be run as self-contained Python applications using `uv`, a fast and reliable Python package manager and project runner.

## 1. Prerequisites

- **Python 3.11+**: Ensure you have a modern Python version installed.
- **uv**: If you don't have it, install it via:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- **External CLI Tools**:
  - **Claude Code**: Required to run agents using the `claude` harness.
  - **Gemini CLI**: Required to run agents using the `gemini` harness.

## 2. Initial Setup

Each agent (Dot and Dash) lives in its own directory with its own dependencies and configuration.

### For Dot:
1.  Navigate to the `dot/` directory:
    ```bash
    cd dot
    ```
2.  Install dependencies:
    ```bash
    uv sync
    ```
3.  Configure environment variables:
    ```bash
    cp .env.example .env
    ```
    Edit `.env` and provide your `DISCORD_TOKEN`, `BSKY_HANDLE`, `BSKY_APP_PASSWORD`, and optionally `GEMINI_API_KEY`.

### For Dash:
1.  Navigate to the `dash/` directory:
    ```bash
    cd dash
    ```
2.  Install dependencies:
    ```bash
    uv sync
    ```
3.  Configure environment variables:
    ```bash
    cp .env.example .env
    ```
    Edit `.env` and provide your `DASH_DISCORD_TOKEN`, `DASH_BSKY_HANDLE`, `DASH_BSKY_APP_PASSWORD`, and optionally `GEMINI_API_KEY`.

## 3. Running the Agents

There are two primary ways to interact with the agents: the **CLI** for manual commands and the **Orchestrator** for continuous operation (Discord + Scheduling).

### Using the CLI
The `dot` (or `dash`) command allows you to send messages, trigger checks, or dry-run prompts.

```bash
# Send a message to Dot (defaults to Claude harness)
uv run dot say "Hello Dot, what are your current goals?"

# Send a message using the Gemini harness
uv run dot say "Hello Dot" --harness gemini

# Trigger a scheduled-style operational check
uv run dot tick

# View the last 10 journal entries
uv run dot log show
```

### Running the Orchestrator
The Orchestrator is the long-running process that manages the Discord bridge and the background scheduler.

```bash
# Start the Dot orchestrator
uv run dot-coordinator

# Start the Dash orchestrator
uv run dash-coordinator
```

## 4. Troubleshooting

- **"Module not found"**: Ensure you are running commands with `uv run` to use the virtual environment managed by `uv`.
- **"Missing Environment Variable"**: Check that your `.env` file is in the same directory as the `pyproject.toml` file (e.g., inside `dot/` or `dash/`).
- **Discord Bot not responding**: Verify your `DISCORD_TOKEN` and ensure the bot has the necessary Gateway Intents enabled in the Discord Developer Portal (specifically Message Content Intent).

## 5. Optional: Adding Metacog

For advanced cognitive capabilities, it is highly recommended to integrate the **Metacog** MCP server. Metacog provides the agents with structured reasoning and internal metacognitive tools.

To add Metacog:
1.  **Get the Server**: Follow the installation instructions at the [Metacog repository](https://github.com/inanna-malick/metacog).
2.  **Update `mcp-config.json`**: Add the metacog server to the `mcpServers` object in your agent's `mcp-config.json`:
    ```json
    "metacog": {
      "type": "http",
      "url": "https://metacog.inanna-c38.workers.dev/mcp"
    }
    ```
3.  **Update Invocation Scripts**: In `invoke_dot.py` or `invoke_dash.py`, ensure that `mcp__metacog__*` is added to the `--allowedTools` list in the `invoke_claude` or `invoke_gemini` functions.