config/TOOLS.md

# TOOLS.md - Local Notes

Skills define *how* tools work. This file is for *your* specifics — the stuff that's unique to your setup.

## Model Selection Policy

When creating tasks, jobs, sub-agents, or hooks, choose the appropriate model:

| Model | Use For |
|-------|---------|
| **Opus 4.5** | Everything (default) - best quality, same limits as Sonnet in Max plan |
| **Haiku 4.5** | Simple bulk tasks only - news summaries, quick lookups, translations |

**Default (main session):** Opus 4.5
**Sonnet 4.5:** Not used (Opus has same limits but better quality)

## Home Assistant Integration

- Webhook endpoint: `/hooks/agent`
- Token: configured in `hooks.token`
- Model: Opus 4.5 (default)

### Arrival Hook
When user arrives home, HA calls the webhook. Check `memory/arrival-reminders.json` for pending reminders and deliver them.

**Important:** Just send the content directly — no explaining what you're doing (checking files, clearing reminders, etc.). User just wants the info, not the process.

**File format for `memory/arrival-reminders.json`:**
```json
{
  "reminders": [
    { "id": "unique-id", "task": "fetch_weather_tomorrow" },
    { "id": "unique-id", "task": "check_calendar_tomorrow" },
    { "id": "unique-id", "message": "Call mom! 📞" }
  ]
}
```

- Use `"task"` for things that require action (fetch weather, check calendar, look something up)
- Use `"message"` for simple reminders to display as-is
- Always include a unique `id` for each item

## Der Standard RSS

Helper script: `~/bin/derstandard`

```bash
derstandard items [max]          # NEW items only (filters out seen)
derstandard items --all [max]    # All items including already seen
derstandard article <url>        # Full article content for a specific URL
derstandard articles <url1>,<url2>,... # Fetch multiple + auto-mark as seen
derstandard urls [max]           # Article URLs only (default: 50)
derstandard titles [max]         # Article titles only
derstandard seen                 # Show seen count and recent entries
derstandard reset                # Clear seen history
derstandard raw [max]            # Full RSS XML
```

- Uses internal fivefilters proxy (bypasses web_fetch private IP block)
- Pre-processes output for minimal token usage
- **Auto-tracks seen articles** in `memory/derstandard-seen.txt`
- `items` marks ALL displayed URLs as seen (even if skipped)
- Auto-prunes to 200 entries (oldest removed)

**Workflow for news briefing:**
1. `derstandard items` → shows NEW articles, marks them as seen
2. Pick interesting ones, optionally fetch full content with `articles`
3. Next briefing: only shows articles published since last check

## Forgejo Git Access

Helper script: `~/bin/forgejo`

```bash
forgejo repos [org]              # List repos
forgejo files <owner/repo> [path] # List files
forgejo cat <owner/repo> <path>  # Get file content
forgejo issues <owner/repo>      # List open issues
forgejo prs <owner/repo>         # List open PRs
forgejo branches <owner/repo>    # List branches
forgejo commits <owner/repo> [n] # Recent commits
forgejo search <query>           # Search repos
forgejo raw <endpoint>           # Raw API call
```

- URL: `https://git.cloonar.com`
- User: `openclawd` (read-only)
- Token stored in `.credentials/forgejo.env`

## CalDAV Calendar Access

Credentials stored in `.credentials/nextcloud.env`:
- URL: `https://nextcloud.cloonar.com`
- User: `moltbot@cloonar.com`
- Calendar: `personal_shared_by_dominik.polakovics@cloonar.com`

To fetch today's events:
```bash
source .credentials/nextcloud.env
curl -s -X REPORT -u "$NEXTCLOUD_USER:$NEXTCLOUD_PASS" \
  -H "Content-Type: application/xml" -H "Depth: 1" \
  -d '<c:calendar-query xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav"><d:prop><c:calendar-data/></d:prop><c:filter><c:comp-filter name="VCALENDAR"><c:comp-filter name="VEVENT"><c:time-range start="'$(date +%Y%m%d)'T000000Z" end="'$(date +%Y%m%d)'T235959Z"/></c:comp-filter></c:comp-filter></c:filter></c:calendar-query>' \
  "$NEXTCLOUD_URL/remote.php/dav/calendars/$NEXTCLOUD_USER/$CALDAV_CALENDAR/"
```

## AI News RSS (Hybrid Approach)

Helper script: `~/bin/ainews`

```bash
ainews items [max]          # NEW items only (filters out seen)
ainews items --all [max]    # All items including already seen
ainews article <url>        # Full article content via fivefilters
ainews articles <url1>,<url2>,... # Fetch multiple + auto-mark as seen
ainews seen                 # Show seen count and recent entries
ainews reset                # Clear seen history
```

- Aggregates: Simon Willison, OpenAI Blog, Sebastian Raschka
- Auto-tracks seen articles in `memory/ainews-seen.txt`
- Auto-prunes to 200 entries

**Content availability by source:**
| Source | Full Content | Method |
|--------|-------------|--------|
| Simon Willison | ✅ In RSS/fivefilters | `ainews articles` |
| Sebastian Raschka | ✅ In RSS/fivefilters | `ainews articles` |
| OpenAI Blog | ❌ JS-rendered | Use `web_fetch` tool |

**Hybrid workflow for AI news briefing:**
1. `ainews items` → shows NEW articles from all sources
2. For Simon/Raschka: `ainews articles <urls>` to get full content
3. For OpenAI: Use `web_fetch` tool directly (fivefilters can't extract JS sites)
4. Write briefing with all content

---

## Der Standard RSS Summaries

- **Schedule:** 4× daily: 10:00, 14:00, 18:00, 22:00 (Vienna time)
- **Model:** Haiku 4.5
- **Workflow:** `derstandard items` → pick relevant → `derstandard articles` → write briefing
- **Focus:** International politics, technology, science, economics
- **Excluded:** Sports, culture, society, local Austrian politics
- **Seen tracking:** Automatic via `memory/derstandard-seen.txt`

---

Add whatever helps you do your job. This is your cheat sheet.