From beb24f71d21525d401dad3ba7ab70036114f8bf9 Mon Sep 17 00:00:00 2001 From: Snider Date: Sun, 1 Feb 2026 18:49:35 +0000 Subject: [PATCH] docs: add feature request issues for core CLI migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 12 issue files documenting features needed to replace shell scripts: Claude Code hooks: - 001: core ai session (state management) - 002: core ai context (fact capture) - 003: core ai hook (command validation) - 004: core qa debug (debug statement detection) Data collection: - 005: core collect github (issues/PRs archive) - 006: core collect bitcointalk (forum threads) - 007: core collect market (CMC/CoinGecko) - 008: core collect papers (whitepapers) - 009: core collect excavate (project archaeology) - 010: core collect process (HTML→MD) - 011: core collect dispatch (event hooks) 000: Overview tracking issue These will be submitted to host-uk/core when rate limit resets. Co-Authored-By: Claude Opus 4.5 --- claude/issues/000-overview.md | 66 +++++++++++++++++ claude/issues/001-ai-session.md | 46 ++++++++++++ claude/issues/002-ai-context.md | 53 ++++++++++++++ claude/issues/003-ai-hook.md | 60 ++++++++++++++++ claude/issues/004-lint-debug.md | 58 +++++++++++++++ claude/issues/005-collect-github.md | 71 ++++++++++++++++++ claude/issues/006-collect-bitcointalk.md | 64 +++++++++++++++++ claude/issues/007-collect-market.md | 67 +++++++++++++++++ claude/issues/008-collect-papers.md | 68 ++++++++++++++++++ claude/issues/009-collect-excavate.md | 92 ++++++++++++++++++++++++ claude/issues/010-collect-process.md | 70 ++++++++++++++++++ claude/issues/011-collect-dispatch.md | 73 +++++++++++++++++++ 12 files changed, 788 insertions(+) create mode 100644 claude/issues/000-overview.md create mode 100644 claude/issues/001-ai-session.md create mode 100644 claude/issues/002-ai-context.md create mode 100644 claude/issues/003-ai-hook.md create mode 100644 claude/issues/004-lint-debug.md create mode 100644 claude/issues/005-collect-github.md create mode 100644 claude/issues/006-collect-bitcointalk.md create mode 100644 claude/issues/007-collect-market.md create mode 100644 claude/issues/008-collect-papers.md create mode 100644 claude/issues/009-collect-excavate.md create mode 100644 claude/issues/010-collect-process.md create mode 100644 claude/issues/011-collect-dispatch.md diff --git a/claude/issues/000-overview.md b/claude/issues/000-overview.md new file mode 100644 index 0000000..69f3d3a --- /dev/null +++ b/claude/issues/000-overview.md @@ -0,0 +1,66 @@ +# feat: Replace shell scripts with core CLI commands + +## Summary + +This tracking issue covers the migration from shell scripts to native `core` CLI commands in `core-agent`. Every shell script should be replaced by a `core` command, making the plugin purely configuration (JSON, MD) + calls to `core`. + +## Philosophy + +- Every agent using `core` tests the framework +- Missing features get raised as issues +- Code as if functionality exists (TDD approach) +- The CLI becomes battle-tested and bulletproof + +## Issues + +### Claude Code Hooks (core ai) + +| Issue | Command | Replaces | +|-------|---------|----------| +| #001 | `core ai session` | pre-compact.sh, session-start.sh, suggest-compact.sh | +| #002 | `core ai context` | capture-context.sh, extract-actionables.sh | +| #003 | `core ai hook` | prefer-core.sh, block-docs.sh, post-commit-check.sh | + +### Quality Assurance (core qa) + +| Issue | Command | Replaces | +|-------|---------|----------| +| #004 | `core qa debug` | check-debug.sh | + +### Data Collection (core collect) + +| Issue | Command | Replaces | +|-------|---------|----------| +| #005 | `core collect github` | github-history/collect.sh | +| #006 | `core collect bitcointalk` | bitcointalk/collect.sh | +| #007 | `core collect market` | coinmarketcap/*.sh | +| #008 | `core collect papers` | ledger-papers/discover.sh, collect-whitepaper.sh | +| #009 | `core collect excavate` | project-archaeology/excavate.sh | +| #010 | `core collect process` | job-collector/process.sh | +| #011 | `core collect dispatch` | collection/dispatch.sh | + +## Target State + +After all issues are implemented: + +``` +claude/ +├── hooks/ +│ └── hooks.json # Calls core ai hook validate-* +├── commands/ +│ └── remember.md # Calls core ai context add +├── collection/ +│ └── hooks.json # Calls core collect dispatch +└── skills/ + └── */ + └── SKILL.md # Documentation only, calls core collect * +``` + +No shell scripts. Just JSON config + markdown docs + `core` CLI calls. + +## Implementation Order + +1. **Phase 1**: `core ai session` + `core ai context` (enables hooks to work) +2. **Phase 2**: `core ai hook` + `core qa debug` (safety + quality) +3. **Phase 3**: `core collect github` + `core collect bitcointalk` (most used) +4. **Phase 4**: Remaining collection commands diff --git a/claude/issues/001-ai-session.md b/claude/issues/001-ai-session.md new file mode 100644 index 0000000..4adadad --- /dev/null +++ b/claude/issues/001-ai-session.md @@ -0,0 +1,46 @@ +# feat(ai): Add session state management for Claude Code hooks + +## Summary + +Add `core ai session` subcommands to manage Claude Code session state, replacing shell scripts that currently handle this. + +## Required Commands + +```bash +core ai session save # Save current session state (pre-compact) +core ai session restore # Restore session state (session-start) +core ai session stats # Track tool calls, suggest compaction +core ai session clear # Clear stale session data +``` + +## Current Shell Scripts Being Replaced + +- `claude/scripts/pre-compact.sh` - Saves state before auto-compact +- `claude/scripts/session-start.sh` - Restores context on startup +- `claude/scripts/suggest-compact.sh` - Suggests compaction at intervals + +## State to Manage + +- Working directory and git branch +- Git status (modified files) +- In-progress todos +- Context facts (decisions, actionables) +- Tool call counter per session + +## Storage + +State stored in `~/.claude/sessions/`: +- `scratchpad.md` - Human-readable resume state +- `context.json` - Structured context facts +- `stats.json` - Session statistics + +## Output Format + +```json +{ + "saved": true, + "path": "~/.claude/sessions/scratchpad.md", + "facts": 5, + "tool_calls": 47 +} +``` diff --git a/claude/issues/002-ai-context.md b/claude/issues/002-ai-context.md new file mode 100644 index 0000000..3d23ed4 --- /dev/null +++ b/claude/issues/002-ai-context.md @@ -0,0 +1,53 @@ +# feat(ai): Add context fact management for Claude Code + +## Summary + +Add `core ai context` subcommands to capture and manage context facts that persist across compaction. + +## Required Commands + +```bash +core ai context add [--source=X] # Save a context fact +core ai context list # List current facts +core ai context extract # Extract actionables from tool output +core ai context clear # Clear old context (>3h) +``` + +## Current Shell Scripts Being Replaced + +- `claude/scripts/capture-context.sh` - Stores context facts +- `claude/scripts/extract-actionables.sh` - Extracts actionables from core CLI output + +## Context Format + +```json +[ + {"fact": "Use Action pattern not Service", "source": "user", "ts": 1234567890}, + {"fact": "FAIL: TestFoo", "source": "core go test", "ts": 1234567891} +] +``` + +## Extraction Patterns + +The `extract` command should parse output from: +- `core go test` / `core go qa` / `core go lint` - Extract ERROR/WARN/FAIL lines +- `core php test` / `core php stan` - Extract FAIL/Error lines +- `core build` - Extract error/cannot/undefined lines + +## Storage + +- `~/.claude/sessions/context.json` +- Max 20 items, auto-clear after 3 hours of inactivity + +## Example Usage + +```bash +# Manual fact +core ai context add "User prefers UK English" --source=user + +# Extract from piped output +core go test 2>&1 | core ai context extract + +# List facts +core ai context list --json +``` diff --git a/claude/issues/003-ai-hook.md b/claude/issues/003-ai-hook.md new file mode 100644 index 0000000..0b378e6 --- /dev/null +++ b/claude/issues/003-ai-hook.md @@ -0,0 +1,60 @@ +# feat(ai): Add hook validation for Claude Code PreToolUse + +## Summary + +Add `core ai hook` subcommands to validate commands and file operations for Claude Code hooks. + +## Required Commands + +```bash +core ai hook validate-command # Check if command is safe/allowed +core ai hook validate-file # Check if file creation is allowed +core ai hook post-commit # Check for uncommitted work after commit +``` + +## Current Shell Scripts Being Replaced + +- `claude/hooks/prefer-core.sh` - Blocks dangerous commands, enforces core CLI +- `claude/scripts/block-docs.sh` - Blocks random .md file creation +- `claude/scripts/post-commit-check.sh` - Warns about uncommitted work + +## Command Validation Rules + +Block these patterns: +- `rm -rf` / `rm -r` (except node_modules, vendor, .cache, dist, build) +- `mv`/`cp` with wildcards +- `xargs` with rm/mv/cp +- `find -exec` with file operations +- `sed -i` (in-place editing) +- `grep -l | ...` (mass file targeting) +- `perl -i`, `awk > file` + +Redirect to core: +- `go test/build/fmt/mod` → suggest `core go *` +- `golangci-lint` → suggest `core go lint` +- `composer test` → suggest `core php test` +- `./vendor/bin/pint` → suggest `core php fmt` +- `php artisan serve` → suggest `core php dev` + +## File Validation Rules + +Allow: +- `README.md`, `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, `CHANGELOG.md`, `LICENSE.md` +- Files in `docs/` directory + +Block: +- Other `.md` files (suggest using README.md or docs/) + +## Output Format (JSON for hooks) + +```json +{"decision": "approve"} +``` + +```json +{"decision": "block", "message": "Use `core go test` instead of raw go test"} +``` + +```json +{"decision": "warn", "message": "3 files remain uncommitted after commit"} +``` diff --git a/claude/issues/004-lint-debug.md b/claude/issues/004-lint-debug.md new file mode 100644 index 0000000..431d98e --- /dev/null +++ b/claude/issues/004-lint-debug.md @@ -0,0 +1,58 @@ +# feat(qa): Add debug statement detection + +## Summary + +Add `core qa debug` command to detect debug statements in code, for use in Claude Code PostToolUse hooks. + +## Required Commands + +```bash +core qa debug # Check single file for debug statements +core qa debug --staged # Check all staged files +core qa debug --changed # Check all changed files +``` + +## Current Shell Script Being Replaced + +- `claude/scripts/check-debug.sh` - Warns about debug statements after edits + +## Detection Patterns + +**Go files (*.go):** +- `fmt.Println` +- `fmt.Printf` (without format verbs suggesting actual logging) +- `log.Println` +- `log.Printf` +- `spew.Dump` +- `pp.Println` + +**PHP files (*.php):** +- `dd(` +- `dump(` +- `var_dump(` +- `print_r(` +- `ray(` + +**JavaScript/TypeScript (*.js, *.ts, *.tsx):** +- `console.log` +- `console.debug` +- `debugger` + +## Output Format + +```json +{ + "file": "src/main.go", + "warnings": [ + {"line": 42, "type": "fmt.Println", "content": "fmt.Println(\"debug\")"}, + {"line": 87, "type": "log.Println", "content": "log.Println(err)"} + ] +} +``` + +For hooks, output to stderr: +``` +[qa] WARNING: Debug statements found in src/main.go + 42: fmt.Println("debug") + 87: log.Println(err) +``` diff --git a/claude/issues/005-collect-github.md b/claude/issues/005-collect-github.md new file mode 100644 index 0000000..09955aa --- /dev/null +++ b/claude/issues/005-collect-github.md @@ -0,0 +1,71 @@ +# feat(collect): Add GitHub history collection + +## Summary + +Add `core collect github` command to archive GitHub issues and PRs from repositories and organisations. + +## Required Commands + +```bash +core collect github # Collect issues + PRs from repo +core collect github --org # Collect all repos in org +core collect github --org # Batch collect multiple orgs +core collect github --issues-only # Issues only +core collect github --prs-only # PRs only +core collect github --check-rate # Show rate limit status +``` + +## Current Shell Script Being Replaced + +- `claude/skills/github-history/collect.sh` - 517 lines of bash + +## Features + +1. **Rate limit protection** + - Check every N calls + - Auto-pause at 25% remaining (75% used) + - Resume after reset + 10s buffer + +2. **Incremental collection** + - Skip already-fetched issues/PRs + - Resume interrupted collections + +3. **Reception scoring** + - ADDRESSED: Closed after discussion + - DISMISSED: Labeled wontfix/invalid + - IGNORED: Closed with no response + - STALE: Open with no replies + - ACTIVE: Open with discussion + - MERGED/REJECTED/PENDING for PRs + +4. **Output structure** + ``` + repo/{org}/{repo}/ + ├── Issue/ + │ ├── INDEX.md + │ ├── 001.md + │ └── 002.md + ├── PR/ + │ ├── INDEX.md + │ ├── 001.md + │ └── 002.md + └── .json/ + ├── issues-list.json + └── prs-list.json + ``` + +5. **Index generation** + - Markdown tables with seq, GitHub #, title, score + - Score legend + +## Output Format + +Progress to stderr, final summary to stdout: +```json +{ + "repo": "host-uk/core", + "issues": 47, + "prs": 23, + "output": "repo/host-uk/core/" +} +``` diff --git a/claude/issues/006-collect-bitcointalk.md b/claude/issues/006-collect-bitcointalk.md new file mode 100644 index 0000000..eaada6d --- /dev/null +++ b/claude/issues/006-collect-bitcointalk.md @@ -0,0 +1,64 @@ +# feat(collect): Add BitcoinTalk thread collection + +## Summary + +Add `core collect bitcointalk` command to archive BitcoinTalk forum threads. + +## Required Commands + +```bash +core collect bitcointalk # Collect full thread +core collect bitcointalk # Collect from URL +core collect bitcointalk --pages=5 # Limit pages +core collect bitcointalk --output=DIR # Custom output dir +``` + +## Current Shell Script Being Replaced + +- `claude/skills/bitcointalk/collect.sh` - 270 lines of bash + embedded Python + +## Features + +1. **Rate limiting** + - Respectful delay between requests (default 2s) + - Configurable via `--delay=N` + +2. **Post type detection** + - ANN: Original announcement (post #1) + - UPDATE: Contains [UPDATE]/[RELEASE]/[ANNOUNCEMENT] + - QUESTION: Contains question mark in first 200 chars + - COMMUNITY: General discussion + +3. **Output structure** + ``` + bitcointalk-{topic}/ + ├── INDEX.md + ├── pages/ + │ ├── page-0.html + │ └── page-20.html + └── posts/ + ├── POST-0001.md + └── POST-0002.md + ``` + +4. **Post metadata** + - Author + - Date + - Post type/score + - Original content + +5. **Incremental collection** + - Resume interrupted collections + - Skip already-fetched pages + +## Output Format + +```json +{ + "topic_id": "2769739", + "title": "Lethean - Privacy Blockchain VPN", + "posts": 1247, + "pages": 63, + "output": "bitcointalk-2769739/" +} +``` diff --git a/claude/issues/007-collect-market.md b/claude/issues/007-collect-market.md new file mode 100644 index 0000000..73d52be --- /dev/null +++ b/claude/issues/007-collect-market.md @@ -0,0 +1,67 @@ +# feat(collect): Add cryptocurrency market data collection + +## Summary + +Add `core collect market` command to collect historical price/market data from CoinMarketCap, CoinGecko, etc. + +## Required Commands + +```bash +core collect market # Collect current data +core collect market --historical # Include historical data +core collect market --from=2018-01-01 # Date range +core collect market # Multiple coins +core collect market jobs # Generate job list +``` + +## Current Shell Scripts Being Replaced + +- `claude/skills/coinmarketcap/generate-jobs.sh` - Generates CMC collection jobs +- `claude/skills/coinmarketcap/process.sh` - Processes collected CMC data + +## Data Sources + +1. **CoinMarketCap** + - Main page (description, links) + - Markets/exchanges + - Historical data + - News + - API endpoints (where available) + +2. **CoinGecko** (backup) + - Main page + - API for historical data + +## Output Structure + +``` +market/{coin}/ +├── INDEX.md +├── cmc/ +│ ├── main.json +│ ├── markets.json +│ └── historical.json +├── coingecko/ +│ ├── detail.json +│ └── history.json +└── summary.md +``` + +## Job Format + +For `jobs` subcommand (pipe to collector): +``` +URL|FILENAME|TYPE|METADATA +https://coinmarketcap.com/currencies/lethean/|cmc-lethean-main.html|cmc-main|coin=lethean +``` + +## Output Format + +```json +{ + "coin": "lethean", + "sources": ["cmc", "coingecko"], + "historical_days": 2190, + "output": "market/lethean/" +} +``` diff --git a/claude/issues/008-collect-papers.md b/claude/issues/008-collect-papers.md new file mode 100644 index 0000000..a15e424 --- /dev/null +++ b/claude/issues/008-collect-papers.md @@ -0,0 +1,68 @@ +# feat(collect): Add research paper/whitepaper collection + +## Summary + +Add `core collect papers` command to discover and collect distributed ledger research papers and whitepapers. + +## Required Commands + +```bash +core collect papers --all # All known papers +core collect papers --category=cryptography # Filter by category +core collect papers --topic=bulletproofs # Filter by topic +core collect papers --project=monero # Filter by project +core collect papers --search-iacr # Search IACR eprint +core collect papers queue # Queue single paper +``` + +## Current Shell Scripts Being Replaced + +- `claude/skills/ledger-papers/discover.sh` - Paper discovery +- `claude/collection/collect-whitepaper.sh` - Queue whitepaper collection +- `claude/collection/update-index.sh` - Update paper index + +## Categories + +- genesis (Bitcoin, b-money, hashcash, bit gold) +- cryptonote (CryptoNote v2.0, CNS standards) +- mrl (Monero Research Lab papers) +- privacy (Zcash, Dash, Mimblewimble, Lelantus) +- smart-contracts (Ethereum, Solana, Cardano) +- layer2 (Lightning, Plasma, Rollups) +- consensus (PBFT, Tendermint, HotStuff) +- cryptography (Bulletproofs, CLSAG, PLONK) +- defi (Uniswap, Aave, Compound) +- storage (IPFS, Filecoin, Arweave) +- identity (DIDs, Verifiable Credentials) +- attacks (Selfish mining, eclipse, traceability) + +## Registry + +Papers defined in `registry.json`: +```json +{ + "id": "bulletproofs", + "title": "Bulletproofs: Short Proofs for Confidential Transactions", + "year": 2017, + "url": "https://eprint.iacr.org/2017/1066.pdf", + "topics": ["range-proofs", "zero-knowledge"] +} +``` + +## Output Format + +Job list for collection: +``` +URL|FILENAME|TYPE|METADATA +https://bitcoin.org/bitcoin.pdf|bitcoin.pdf|paper|category=genesis,title=Bitcoin... +``` + +Summary: +```json +{ + "papers": 91, + "categories": 15, + "queued": 3, + "output": "papers/" +} +``` diff --git a/claude/issues/009-collect-excavate.md b/claude/issues/009-collect-excavate.md new file mode 100644 index 0000000..dd97045 --- /dev/null +++ b/claude/issues/009-collect-excavate.md @@ -0,0 +1,92 @@ +# feat(collect): Add project archaeology/excavation + +## Summary + +Add `core collect excavate` command to perform deep excavation of abandoned cryptocurrency projects before data is lost. + +## Required Commands + +```bash +core collect excavate # Full excavation +core collect excavate --scan-only # Check what's accessible +core collect excavate --resume # Resume interrupted dig +core collect excavate --only=github,btt # Specific collectors +``` + +## Current Shell Script Being Replaced + +- `claude/skills/project-archaeology/excavate.sh` - 312 lines of bash + +## Excavation Pipeline + +Runs collectors in priority order: + +| Phase | Source | Collector | Priority | Notes | +|-------|--------|-----------|----------|-------| +| 1 | GitHub repos | `collect github` | P1 | Often deleted first | +| 1 | GitHub releases | `collect github` | P1 | Binaries disappear | +| 2 | BitcoinTalk ANN | `collect bitcointalk` | P2 | Usually persists | +| 2 | Website (Wayback) | `collect wayback` | P2 | Snapshots exist | +| 3 | Block explorer | `collect explorer` | P3 | Chain data | +| 3 | CoinMarketCap | `collect market` | P3 | Historical prices | +| 4 | Reddit | `collect reddit` | P4 | Community context | +| 4 | Medium posts | `collect medium` | P4 | Announcements | + +## Project Registry + +Projects defined in `cryptonote-discovery/registry.json`: +```json +{ + "name": "Masari", + "symbol": "MSR", + "status": "abandoned", + "github": ["masari-project"], + "bitcointalk": "2769739", + "website": "getmasari.org", + "explorer": "explorer.getmasari.org", + "cmc": "masari" +} +``` + +## Output Structure + +``` +digs/{project}/ +├── EXCAVATION.md # Dig log with timestamps +├── SALVAGE-REPORT.md # What's worth keeping +├── LESSONS.md # Post-mortem analysis +├── github/ # All repo history +├── releases/ # Wallet binaries, checksums +├── bitcointalk/ # Thread archive +├── website/ # Wayback snapshots +├── explorer/ # Chain data samples +├── market/ # Price history +├── papers/ # Whitepapers, docs +└── community/ # Reddit, Medium, etc +``` + +## Scan Mode + +`--scan-only` checks accessibility without downloading: +- GitHub org accessible? +- BitcoinTalk thread exists? +- Wayback snapshots available? +- Block explorer online? +- CMC page exists? + +## Output Format + +```json +{ + "project": "masari", + "status": "abandoned", + "accessible": { + "github": true, + "bitcointalk": true, + "wayback": true, + "explorer": false, + "cmc": true + }, + "output": "digs/masari/" +} +``` diff --git a/claude/issues/010-collect-process.md b/claude/issues/010-collect-process.md new file mode 100644 index 0000000..c6999e1 --- /dev/null +++ b/claude/issues/010-collect-process.md @@ -0,0 +1,70 @@ +# feat(collect): Add collected data processing + +## Summary + +Add `core collect process` command to convert collected HTML/JSON files into clean markdown. + +## Required Commands + +```bash +core collect process # Process downloaded files +core collect process bitcointalk ./downloads # BitcoinTalk HTML → MD +core collect process reddit ./downloads # Reddit JSON → MD +core collect process wayback ./downloads # Wayback HTML → MD +core collect process medium ./downloads # Medium RSS → MD +``` + +## Current Shell Script Being Replaced + +- `claude/skills/job-collector/process.sh` - 243 lines of bash + embedded Python + +## Supported Sources + +1. **bitcointalk** / **btt** + - Input: HTML pages + - Extract: posts, authors, dates + - Output: POST-NNNN.md files + +2. **reddit** + - Input: JSON from Reddit API + - Extract: posts, comments, scores + - Output: REDDIT-NNNN.md files + +3. **wayback** + - Input: HTML from Wayback Machine + - Extract: title, body text + - Output: {basename}.md files + +4. **medium** + - Input: RSS/XML feed + - Extract: title, author, date, content + - Output: MEDIUM-NNNN.md files + +## Output Structure + +``` +processed/ +├── INDEX.md +└── posts/ + ├── POST-0001.md + ├── POST-0002.md + └── ... +``` + +## Index Generation + +Auto-generates INDEX.md with: +- Source metadata +- Post count +- Links to all posts + +## Output Format + +```json +{ + "source": "bitcointalk", + "input_files": 15, + "posts_extracted": 347, + "output": "processed/" +} +``` diff --git a/claude/issues/011-collect-dispatch.md b/claude/issues/011-collect-dispatch.md new file mode 100644 index 0000000..fa28315 --- /dev/null +++ b/claude/issues/011-collect-dispatch.md @@ -0,0 +1,73 @@ +# feat(collect): Add event hook dispatch system + +## Summary + +Add `core collect dispatch` command to fire events during data collection, allowing modular hook handling. + +## Required Commands + +```bash +core collect dispatch [args...] # Fire an event +core collect dispatch on_url_found # URL discovered +core collect dispatch on_file_collected # File downloaded +core collect dispatch on_collection_complete # Batch finished +core collect hooks list # List registered hooks +core collect hooks register # Register new hook +``` + +## Current Shell Script Being Replaced + +- `claude/collection/dispatch.sh` - Hook dispatcher + +## Events + +| Event | Trigger | Args | +|-------|---------|------| +| `on_url_found` | URL discovered during collection | url | +| `on_file_collected` | File successfully downloaded | file, type | +| `on_collection_complete` | Job batch finishes | - | + +## Hook Registration + +Hooks defined in `hooks.json`: +```json +{ + "hooks": { + "on_url_found": [ + { + "name": "whitepaper-collector", + "pattern": "\\.pdf$", + "handler": "collect papers queue", + "priority": 10, + "enabled": true + } + ] + } +} +``` + +## Pattern Matching + +- Hooks can specify regex pattern for filtering +- Only matching events trigger the handler +- Multiple hooks can handle same event (priority ordering) + +## Handler Types + +1. **Core commands**: `collect papers queue` +2. **Shell scripts**: `./my-handler.sh` +3. **External binaries**: `/usr/local/bin/handler` + +## Output Format + +```json +{ + "event": "on_url_found", + "args": ["https://example.com/paper.pdf"], + "handlers_fired": 2, + "results": [ + {"handler": "whitepaper-collector", "status": "ok"}, + {"handler": "archive-notifier", "status": "ok"} + ] +} +```