fix: sync SKILL.md with local — triggers, DeepSeek, v1.1.0

SKILL.md

@@ -1,27 +1,94 @@
 ---
 name: session-cleaner
 description: "Clean Hermes session DB: delete short conversations, generate missing titles."
-version: 1.0.0
+version: 1.1.0
 ---
 
 # Session Cleaner
 
-Scans the Hermes session DB and:
+When the user says **"temizlik yap"** or **"clean sessions"**, follow this workflow.
-1. Deletes sessions with fewer than 5 messages (configurable)
-2. Generates titles for sessions that don't have one
 
-Uses local Ollama (hermes3:latest) for title generation.
+Trigger keywords: `temizlik yap`, `clean sessions`
 
-## Usage
+## Workflow
+
+### Step 1: Dry-run first
+
+ALWAYS dry-run first — deletion is irreversible:
 
 ```bash
-python3 hermes_cleaner.py --dry-run      # Preview
+SKILL_DIR=$(dirname $(readlink -f ~/.hermes/skills/productivity/session-cleaner/SKILL.md))
-python3 hermes_cleaner.py                # Full clean
+python3 "$SKILL_DIR/scripts/hermes_cleaner.py" --dry-run
-python3 hermes_cleaner.py --no-delete    # Titles only
-python3 hermes_cleaner.py --min-messages 3  # Custom threshold
 ```
 
-## Requirements
+### Step 2: Report and confirm
 
-- Hermes Agent installed (for hermes_state module)
+Show the user:
-- Ollama with hermes3:latest model (env-configurable)
+- How many sessions will be deleted (and some examples)
+- How many sessions will get titles
+
+Ask for confirmation. User may want to adjust `--min-messages` or skip parts.
+
+### Step 3: Run for real
+
+```bash
+python3 "$SKILL_DIR/scripts/hermes_cleaner.py"
+```
+
+### Options
+
+| Flag | Effect |
+|---|---|
+| `--dry-run` | Preview only, no changes |
+| `--min-messages N` | Delete sessions with < N messages (default: 5) |
+| `--no-delete` | Skip deletion, only generate titles |
+| `--no-title` | Skip title generation, only delete |
+| `--max-titles N` | Max titles per run (default: 20) |
+
+## Configuration
+
+Default is DeepSeek v4 Flash API (works everywhere, needs API key in `.env`):
+
+| Env var | Default | Description |
+|---|---|---|
+| `HERMES_CLEANER_MODEL` | `deepseek-v4-flash` | Model for title generation |
+| `HERMES_CLEANER_ENDPOINT` | `https://api.deepseek.com/v1/chat/completions` | API endpoint |
+| `HERMES_CLEANER_API_KEY` | auto-loaded from `~/.hermes/.env` (`DEEPSEEK_API_KEY`) | API key |
+
+To switch to local Ollama:
+```bash
+export HERMES_CLEANER_ENDPOINT="http://localhost:11434/v1/chat/completions"
+export HERMES_CLEANER_MODEL="hermes3:latest"
+export HERMES_CLEANER_API_KEY=""
+```
+
+## Important Rules
+
+- **Dry-run first. Always.** Deletion is IRREVERSIBLE.
+- Short sessions are deleted FIRST, then titles generated for remaining untitled ones.
+  This avoids generating titles for sessions that will be deleted anyway.
+- Title generation uses the same model rules as **session-ending** skill — see
+  its Pitfalls section for model selection guidance.
+
+## Pitfalls
+
+### Same model pitfalls as session-ending
+
+This skill uses the same title generation pipeline as session-ending. All pitfalls
+from that skill apply — see **session-ending** skill's Pitfalls section for the
+full model compatibility table. Key points:
+- `deepseek-v4-flash` requires `max_tokens ≥ 500` (script already uses 500)
+- `deepseek-chat` and `hermes3:latest` work with any limit
+- Ollama thinking models (`gemma4:12b`, `qwen3.5:9b`) are unreliable — avoid
+- Markdown stripping and strict prompt formatting are handled by the script
+
+### Overlap between short AND untitled sessions
+
+Sessions that are both short (< N msgs) AND untitled appear in both lists during
+scan. The script handles this correctly: delete runs first, so these sessions
+are removed before title generation starts. No titles are wasted on doomed sessions.
+
+## See Also
+
+- **session-ending** skill — per-session title + save workflow ("ending")
+- Gitea repo: https://git.softmediadesign.com/git_alhan/hermes-session-cleaner