~/.openfang/hands/
└── my-hand/
    ├── HAND.toml          # Hand definition
    └── SKILL.md           # Optional skill documentation

# Metadata
id = "my-hand"
name = "My Hand"
description = "What this Hand does in one sentence"
category = "productivity"  # or "data", "content", "communication"
icon = "🚀"

# Tools this Hand can use
tools = [
    "shell_exec",
    "file_read",
    "file_write",
    "web_fetch",
    "web_search",
    "memory_store",
    "memory_recall"
]

# Agent configuration
[agent]
name = "my-hand"
description = "Detailed description for internal use"
module = "builtin:chat"
provider = "default"
model = "default"
max_tokens = 16384
temperature = 0.3
max_iterations = 50
system_prompt = """
You are My Hand — [describe what the Hand does and how it works]

## Phase 0 — Platform Detection (ALWAYS DO THIS FIRST)
...

[Rest of system prompt]
"""

mkdir -p ~/.openfang/hands/news-digest
cd ~/.openfang/hands/news-digest

# ~/.openfang/hands/news-digest/HAND.toml

id = "news-digest"
name = "News Digest Hand"
description = "Reads news sites daily and generates a curated digest"
category = "data"
icon = "📰"

tools = [
    "web_fetch",
    "web_search",
    "file_write",
    "file_read",
    "memory_store",
    "memory_recall",
    "schedule_create",
    "schedule_list"
]

# Settings
[[settings]]
key = "news_sources"
label = "News Sources"
description = "Comma-separated list of news sites or topics"
setting_type = "text"
default = "TechCrunch, Hacker News, The Verge"

[[settings]]
key = "digest_frequency"
label = "Digest Frequency"
description = "How often to generate digests"
setting_type = "select"
default = "daily"

[[settings.options]]
value = "daily"
label = "Daily"

[[settings.options]]
value = "twice_daily"
label = "Twice Daily"

[[settings.options]]
value = "weekly"
label = "Weekly"

[[settings]]
key = "max_articles"
label = "Max Articles"
description = "Maximum number of articles to include in digest"
setting_type = "select"
default = "10"

[[settings.options]]
value = "5"
label = "5 articles"

[[settings.options]]
value = "10"
label = "10 articles"

[[settings.options]]
value = "20"
label = "20 articles"

[[settings]]
key = "output_format"
label = "Output Format"
description = "Format for the digest"
setting_type = "select"
default = "markdown"

[[settings.options]]
value = "markdown"
label = "Markdown"

[[settings.options]]
value = "html"
label = "HTML"

[[settings.options]]
value = "email"
label = "Email (requires SMTP config)"

# Agent configuration
[agent]
name = "news-digest-hand"
description = "AI news curator that generates daily digests from configured sources"
module = "builtin:chat"
provider = "default"
model = "default"
max_tokens = 16384
temperature = 0.3
max_iterations = 40
system_prompt = """
You are News Digest Hand — an AI news curator that reads configured news sources, filters for the most interesting stories, and generates a daily digest.

## Phase 0 — Platform Detection & State Recovery

Detect the operating system:

Recover state:
1. memory_recall `news_digest_state` — load previous digest history
2. Read **User Configuration** for news_sources, digest_frequency, max_articles, output_format
3. file_read `news_digest_seen.json` if it exists — articles already covered

## Phase 1 — Schedule Setup

On first run:
1. Create digest schedule using schedule_create based on `digest_frequency`:
   - daily: schedule at 8 AM
   - twice_daily: schedule at 8 AM and 5 PM
   - weekly: schedule Monday at 8 AM
2. Initialize seen articles database: `news_digest_seen.json`

## Phase 2 — News Collection

Parse `news_sources` setting (comma-separated):
- For known sources (TechCrunch, Hacker News, etc.), use direct fetch
- For topics (e.g., "AI safety"), use web_search

For each source:
1. Fetch the homepage or RSS feed
2. Extract article headlines, URLs, summaries
3. Check against `news_digest_seen.json` to skip duplicates
4. Tag each article with: title, url, source, publish_date, summary

Target: Collect 2-3x `max_articles` for filtering.

## Phase 3 — Article Filtering & Ranking

Score each article (0-100):
- Recency: +30 (published in last 24h)
- Relevance: +25 (matches user interests from history)
- Importance: +25 (major news, high engagement)
- Uniqueness: +20 (not covered elsewhere)

Sort by score, take top N per `max_articles` setting.

## Phase 4 — Digest Generation

Based on `output_format`:

**Markdown:**
```markdown
# News Digest — [Date]

## Top Story
[Article 1 with summary]

## Tech News
- [Article 2]
- [Article 3]

## Business
- [Article 4]

[... up to max_articles ...]

---
Generated by News Digest Hand

<!DOCTYPE html>
<html>
<head><title>News Digest - [Date]</title></head>
<body>
<h1>News Digest — [Date]</h1>
<div class="article">
  <h2>[Article Title]</h2>
  <p>[Summary]</p>
  <a href="[URL]">Read more</a>
</div>
...
</body>
</html>

### Step 3: Activate the Hand

```bash
openfang hand activate news-digest

openfang hand config news-digest \
  --set news_sources="TechCrunch, Hacker News, Ars Technica" \
  --set digest_frequency="daily" \
  --set max_articles="10" \
  --set output_format="markdown"

> Generate a news digest now

[[requires]]
key = "binary_name"
label = "Human-readable name"
requirement_type = "binary"
check_value = "binary_name"
description = "Why this is needed"

[requires.install]
macos = "brew install binary_name"
windows = "winget install Package.Name"
linux_apt = "sudo apt install binary_name"
manual_url = "https://example.com/install"
estimated_time = "2-5 min"

[[requires]]
key = "API_KEY_NAME"
label = "Service API Key"
requirement_type = "api_key"
check_value = "API_KEY_NAME"
description = "API key from example.com for feature X"

[requires.install]
signup_url = "https://example.com/signup"
docs_url = "https://example.com/docs/api"
env_example = "API_KEY_NAME=your_key_here"
estimated_time = "5-10 min"
steps = [
    "Sign up at example.com",
    "Navigate to Settings > API Keys",
    "Generate new API key",
    "Set as environment variable: export API_KEY_NAME=...",
    "Restart OpenFang"
]

[[settings]]
key = "setting_name"
label = "Display Name"
description = "What this controls"
setting_type = "select"  # or "text", "toggle"
default = "option1"

[[settings.options]]
value = "option1"
label = "Option 1 Label"

[[settings.options]]
value = "option2"
label = "Option 2 Label"

// In system prompt
knowledge_add_entity({
  type: "article",
  title: "Article Title",
  url: "https://...",
  source: "TechCrunch",
  date: "2026-03-06"
})

knowledge_add_relation({
  from: "article_1",
  to: "topic_ai",
  type: "about"
})

// Later, query:
knowledge_query({entity_type: "article", filters: {source: "TechCrunch"}})

event_publish({
  type: "news_digest_ready",
  data: {
    digest_path: "news_digest_2026-03-06.md",
    article_count: 10
  }
})

You are [Hand Name] — [one sentence description]

## Phase 0 — Platform Detection & State Recovery (ALWAYS DO THIS FIRST)
[Detect OS, load state, read config]

## Phase 1 — [Initialization/Setup]
[First-run setup, schedule creation, etc.]

## Phase 2 — [Core Work Phase 1]
[Primary task logic]

## Phase 3 — [Core Work Phase 2]
[Secondary task logic]

## Phase N — State Persistence
[Save state, update metrics]

## Guidelines
- Rule 1
- Rule 2
- Edge case handling

# Activate
openfang hand activate my-hand

# Test basic functionality
> [Send a test task]

# Check output files
ls -l *.md *.json

# Verify metrics
openfang hand stats my-hand

# Package your Hand
tar -czf my-hand.tar.gz ~/.openfang/hands/my-hand/

# Share via GitHub, etc.

# Download
wget https://example.com/my-hand.tar.gz

# Extract
tar -xzf my-hand.tar.gz -C ~/.openfang/hands/

# Activate
openfang hand activate my-hand