# AGENTS.md

## File Sending Protocol

**🚨 HARD RULE — VIOLATE THIS AND YOU'VE FAILED:**

### Priority Order (Highest to Lowest)

1. **Telegram Photo (DEFAULT — use this always unless told otherwise):** Send the image directly to Telegram via `sendPhoto`. This is the #1 preferred method. It delivers the image inline as a media message and automatically includes Telegram's media caption. Use this for ALL screenshots, diagrams, and generated images.

2. **Miniserve Link (only when explicitly asked for a link):** `https://files.rayyano.site/<path>` — only if the user says "send me the link" or "use miniserve".

3. **imgbs Upload Link (only when explicitly asked to upload):** Upload to imgbs.com then send the URL — only if the user says "upload to imgbs" or "send me the imgbs link".

### Telegram Photo (Default Method)

Always send images directly to Telegram unless the user specifies otherwise:

```bash
export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
curl -s -X POST https://api.telegram.org/bot8692103429:AAELCjRpVDJ3XlImiWp82dqXVg9_R1cCul4/sendPhoto \
  -F "chat_id=6796858829" \
  -F "photo=@<file-path>"
```

No caption needed — just the photo. Telegram renders it inline as a media message automatically.

### When Sending a Link (Miniserve or imgbs)

If the user explicitly asked for a link (not the default Telegram photo), follow this two-turn protocol:

**Turn 1:** The bare URL and **nothing else**. No markdown. No punctuation. No "here is". No wrapper text of any kind. Just:
```
https://files.rayyano.site/media/diagrams/example.png
```

**Turn 2 (a completely separate response, only after turn 1 is delivered):** The context, explanation, summary, or any prose.

**These are two distinct messages, not two paragraphs in one message.** Never combine the link and the explanation in the same response. If you find yourself typing both, STOP — send the link first, then write the follow-up as a separate message. This is non-negotiable.

## Web Search

When you need to search the web, use the Exa API. Full reference and API key at:

**[docs/prompts/web-search.md](docs/prompts/web-search.md)**

Quick reminder:
- Always `export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt` before curl (zerobrew CA path is broken)
- Prefer `type: "auto"` with `contents: {"highlights": true}` for most queries
- Use `outputSchema` + `type: "deep-lite"` when you need structured/synthesized answers
- Use `maxAgeHours: 0` for real-time data

## Web Page Cleaning (Defuddle)

When reading HTML documentation pages (MDN, library docs, RFCs, etc.) — not visual/image content but text-heavy info pages — strip the crap and get clean markdown. Only load the **defuddle** skill if the curl approach below fails or you need advanced options.

Quick curl approach (no install needed):

```bash
export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
curl -sL https://defuddle.md/<webpage-url>
```

CLI approach (from the defuddle skill, installed via `npm install -g defuddle`):

```bash
defuddle parse <url> --md
defuddle parse <url> --md -o content.md
```

This returns pure markdown with navigation, ads, and chrome stripped out. Use it before feeding a page to the model or when the raw HTML would be too noisy. Do NOT use for URLs ending in `.md` — those are already markdown.

## Image Upload

When you need to upload images to share via URL, use imgbs.com:

```bash
export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
curl -s -X POST https://imgbs.com/api/sharex.php \
  -H "X-API-Key: imgbs_f4ef26c6382920d9d48bdddbe37158ad73df373a5f5eed92" \
  -F "image=@<file-path>"
```

Response includes `url` (direct image link) and `page_url` (viewer page).
**Important:** The returned URLs may contain trailing whitespace/newlines — always `.trim()` them before use, otherwise you'll get a 404.

When sending an uploaded image URL to Telegram:
- The URL must be on its own line, no other characters on that line.
- There must be a blank line **above** and **below** the URL.
- No trailing punctuation, markdown wrapping, or any adjacent characters.

## Telegram Image Sending (Legacy — with caption)

If you ever need to send an image to Telegram AND include a URL caption (e.g., when sharing an imgbs link alongside the photo):

```bash
export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
curl -s -X POST https://api.telegram.org/bot8692103429:AAELCjRpVDJ3XlImiWp82dqXVg9_R1cCul4/sendPhoto \
  -F "chat_id=6796858829" \
  -F "photo=@<file-path>" \
  -F "caption=

https://imgbs.com/uploads/<filename>.png

"
```

Key points:
- `caption` value has a leading newline, the URL on its own line (trimmed, no extra chars), then a trailing newline. This ensures the URL is isolated with blank lines above and below in the Telegram message.
- Always `export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt` first (zerobrew CA path is broken).

## Self-Restart

To restart yourself (zot), use `oxmgr restart zot`. Before restarting, use the **zot-loop** extension to schedule a continuation task so you know which session to resume after restart. After coming back online, notify the user that you've restarted and confirm the effects of whatever triggered the restart.

```bash
oxmgr restart zot
```

## File Sharing (miniserve)

A local miniserve is running and served at `https://files.rayyano.site`. Any file under `/home/rayyan/` is accessible at that URL with the same relative path.

Mapping:
- `/home/rayyan/caddy.png` → `https://files.rayyano.site/caddy.png`
- `/home/rayyan/quickstock/package.json` → `https://files.rayyano.site/quickstock/package.json`

Use this to share file links with the user — no upload step needed.

## Screenshot a URL

When asked to screenshot a URL (or a specific element on a page), follow this workflow:

### 1. Navigate with Lightpanda

Load the **Lightpanda** skill, then use the Lightpanda MCP tools:
- `goto` — navigate to the target URL
- Wait for the page to load (use `waitForSelector` or `markdown` to confirm content is present)

### 2. Capture Full-Page Screenshot

Use the Lightpanda MCP tool to take a full-page screenshot. If the MCP server exposes a `screenshot` or `captureScreenshot` tool, use it directly. If not, use the `evaluate` tool with CDP's `Page.captureScreenshot` via a CDP session, or start Lightpanda in CDP mode (`lightpanda serve`) and connect with playwright-core/puppeteer-core to call `page.screenshot({ fullPage: true })`.

Save the screenshot to the local screenshots folder:
```bash
mkdir -p /home/rayyan/media/screenshots
```

File naming: `/home/rayyan/media/screenshots/<domain>_<timestamp>.png`

### 3. Send the Screenshot

**Default: Send directly to Telegram** (see File Sending Protocol above):
```bash
export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
curl -s -X POST https://api.telegram.org/bot8692103429:AAELCjRpVDJ3XlImiWp82dqXVg9_R1cCul4/sendPhoto \
  -F "chat_id=6796858829" \
  -F "photo=@/home/rayyan/media/screenshots/<filename>.png"
```

Only if user explicitly asks for a link, use miniserve or imgbs instead.

### 4. Optional: Crop to Specific Content

If the user asked for a specific element or section of the page:

1. **Analyze the screenshot** — inspect the saved screenshot image and identify the rectangular bounding box coordinates `(x, y, width, height)` of the content/region the user is interested in.

2. **Crop with ffmpeg:**
```bash
ffmpeg -i /home/rayyan/media/screenshots/<input>.png -vf "crop=<width>:<height>:<x>:<y>" /home/rayyan/media/screenshots/<output>_cropped.png
```

   Crop syntax: `crop=width:height:x:y` where `x,y` is the top-left corner of the region.

3. **Send the cropped screenshot** to Telegram directly (default), or via miniserve/imgbs if explicitly asked.

### Quick Reference: ffmpeg Crop

```bash
# Crop a 400x300 region starting at (100, 200)
ffmpeg -i input.png -vf "crop=400:300:100:200" output.png

# Crop centered 500x500
ffmpeg -i input.png -vf "crop=500:500" output.png
```

## Generate Diagrams (Mermaid)

When asked to create a diagram, generate mermaid, document architecture, or convert code to a diagram:

### 1. Generate Mermaid Code

Load the **design-doc-mermaid** skill. Analyze the user's intent to determine the diagram type and load the appropriate guide:

| Request | Diagram Type | Guide |
|---------|-------------|-------|
| Workflow, process, business logic | Activity | `references/guides/diagrams/activity-diagrams.md` |
| Infrastructure, cloud, K8s, deployment | Deployment | `references/guides/diagrams/deployment-diagrams.md` |
| System architecture, components | Architecture | `references/guides/diagrams/architecture-diagrams.md` |
| API flow, interactions, sequence | Sequence | `references/guides/diagrams/sequence-diagrams.md` |
| Code to diagram | Framework-specific | `examples/<framework>/` + relevant diagram guides |

Generate the mermaid code using templates and patterns from the loaded guide. Apply high-contrast styling (always set `color:` in `classDef`) and use Unicode semantic symbols for clarity.

### 2. Render with mmdr

Save the mermaid code as a `.mmd` file, then render it with `mmdr` (blazingly fast, no browser needed):

```bash
mkdir -p /home/rayyan/media/diagrams
mmdr -i /home/rayyan/media/diagrams/<name>.mmd -o /home/rayyan/media/diagrams/<name>.png -e png
```

**Quick alternatives:**
```bash
# Pipe directly (no file needed)
echo 'flowchart LR; A-->B-->C' | mmdr -i - -o /home/rayyan/media/diagrams/out.png -e png

# Render all diagrams from a markdown file
mmdr -i docs/design.md -o /home/rayyan/media/diagrams/ -e png
```

`mmdr` supports 23 diagram types: flowchart, sequence, class, state, ER, pie, gantt, timeline, journey, kanban, C4, block, architecture, requirement, mindmap, git graph, ZenUML, packet, radar, treemap, xy chart, quadrant chart, sankey.

**⚠️ Text Rendering Fix:** mmdr may fail to render Unicode emoji characters (👤, 🧮, ☁️, etc.) due to missing font support. To ensure all text renders correctly:
- **Avoid Unicode emojis** in node labels — use plain text with bracket tags like `[User]`, `[LLM]`, `[DB]` instead.
- If emojis are essential, use `--fontFamily` with a font that supports them (e.g., `--fontFamily "Noto Color Emoji, Arial"`).
- Always inspect the rendered PNG to verify text is visible before sending. If text is missing, regenerate with plain-text labels.

### 3. Send the Diagram

**Default: Send directly to Telegram** (see File Sending Protocol above):
```bash
export CURL_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
curl -s -X POST https://api.telegram.org/bot8692103429:AAELCjRpVDJ3XlImiWp82dqXVg9_R1cCul4/sendPhoto \
  -F "chat_id=6796858829" \
  -F "photo=@/home/rayyan/media/diagrams/<filename>.png"
```

Only if user explicitly asks for a link, use miniserve or imgbs instead.

### Quick Reference: mmdr

```bash
# SVG output (vector, smaller files)
mmdr -i diagram.mmd -o output.svg -e svg

# PNG output (raster, wider compatibility)
mmdr -i diagram.mmd -o output.png -e png

# Pipe from stdin
cat diagram.mmd | mmdr -i - -o output.png -e png

# Custom dimensions
mmdr -i diagram.mmd -o output.png -e png --width 1200 --height 800

# With config file for theming
mmdr -i diagram.mmd -o output.png -e png -c config.json
```