# 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.6** | 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.6
**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

## Audiobookshelf

Helper script: `~/clawd/bin/audiobooks`

```bash
audiobooks current              # Currently listening / in-progress books
audiobooks recent [limit]       # Recently active books (default: 5)
audiobooks finished [limit]     # Finished books (default: 10)
audiobooks stats                # Listening stats overview
audiobooks libraries            # List libraries
```

- Credentials: `.credentials/audiobookshelf.env`
- URL: `https://audiobooks.cloonar.com`
- Output is tab-separated for minimal tokens
- Use during wind-down to suggest continuing audiobook

---

## Jellyfin

Helper script: `~/clawd/bin/jellyfin`

```bash
jellyfin resume [limit]         # Continue watching (in-progress items)
jellyfin recent [limit]         # Recently added to library
jellyfin watched [limit]        # Watch history (last played)
jellyfin shows                  # All series with watch status
jellyfin movies                 # All movies with watch status
jellyfin search <query>         # Search library
jellyfin stats                  # Watch statistics overview
jellyfin libraries              # List libraries
```

- Credentials: `.credentials/jellyfin.env` (user-scoped token for `tv`)
- URL: `https://jellyfin.cloonar.com`
- Output is tab-separated for minimal tokens
- Use during wind-down to suggest specific shows/movies

---

## 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

---

## Brain Dump CLI

Helper script: `~/clawd/bin/tasks`

```bash
tasks list [--priority now,soon] [--due] [--limit N]
tasks add --text "..." --priority soon [--context "..."]
tasks add --recurring --text "..." --frequency daily [--when evening] [--context "..."]
tasks edit <id> [--text "..."] [--priority|--frequency|--when|--context "..."]
tasks done <id>
tasks show <id>
tasks nudged <id1>,<id2>,...
tasks recurring
```

- Data: `memory/tasks.json`
- `--due` filters by nudge interval: now=1d, soon=3d, someday=7d
- `nudged` marks tasks as just-nudged (resets due timer)
- `recurring` lists all recurring items with full context (note, when, frequency)
- `add --recurring` / `edit` / `done` work for both tasks and recurring items
- Output is tab-separated for minimal tokens

**Heartbeat workflow:**
1. `tasks list --due --limit 2` → get tasks needing a nudge
2. Mention them conversationally
3. `tasks nudged <id1>,<id2>` → mark as nudged

---

## Der Standard RSS Summaries

- **Schedule:** 4× daily: 10:00, 14:00, 18:00, 22:00 Vienna (1 cron job with `0 10,14,18,22 * * *`)
- **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.