niahere 0.2.57 → 0.2.59

package/README.md

@@ -1,5 +1,9 @@
 # nia
 
+[![npm version](https://img.shields.io/npm/v/niahere.svg)](https://www.npmjs.com/package/niahere)
+[![npm downloads](https://img.shields.io/npm/dm/niahere.svg)](https://www.npmjs.com/package/niahere)
+[![license](https://img.shields.io/npm/l/niahere.svg)](https://github.com/onlyoneaman/niahere/blob/main/LICENSE)
+
 A personal AI agent you fork and make your own. Small enough to understand, built for one user. Powered by Claude Agent SDK.
 
 - npm package: [`niahere`](https://www.npmjs.com/package/niahere)
@@ -33,7 +37,7 @@ nia start               # starts daemon + registers OS service
 - **Telegram** — message your agent from your phone, typing indicator while processing
 - **Slack** — Socket Mode bot with thread awareness, thinking emoji, watch channels for proactive monitoring
 - **Terminal chat** — REPL with session resume support
-- **Scheduled jobs** — recurring jobs and crons that run Claude and can message you back
+- **Scheduled jobs** — recurring jobs and crons that run Claude and can message you back. Stateful by default (working memory), per-job model routing for cost savings
 - **Persona system** — customizable identity, soul, owner profile, rules, and memory (preloaded every session)
 - **Agents** — domain specialists (marketer, senior-dev) via Claude Agent SDK subagents
 - **Skills** — loads skills from multiple directories, invokable as slash commands
@@ -63,8 +67,8 @@ nia update                     — update to latest version (auto-backup + resta
 nia job list                   — list all jobs
 nia job show [name]            — full details + recent runs
 nia job status [name]          — quick status check
-nia job add <n> <s> <p>        — add a job (--type, --always, --agent, --stateless, --prompt-file)
-nia job update <name>          — update a job (--schedule, --prompt, --prompt-file, --type, --always, --agent, --stateless)
+nia job add <n> <s> <p>        — add a job (--type, --always, --agent, --model, --stateless, --prompt-file)
+nia job update <name>          — update a job (--schedule, --prompt, --prompt-file, --type, --always, --agent, --model, --stateless)
 nia job remove <name>          — delete a job
 nia job enable / disable <n>   — toggle a job
 nia job run <name>             — run a job once
@@ -106,6 +110,8 @@ All config and data lives in `~/.niahere/`:
     soul.md         — how the agent works
     rules.md        — behavioral instructions (loaded every session)
     memory.md       — persistent facts and context (loaded every session)
+  jobs/               — per-job working memory and state (auto-created)
+  optimizations/      — optimization loop run workspaces
   images/
     reference.webp  — visual identity reference image
     profile.webp    — profile picture for Telegram/Slack

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niahere",
-  "version": "0.2.57",
+  "version": "0.2.59",
   "description": "A personal AI assistant daemon — chat, scheduled jobs, persona system, extensible via skills.",
   "type": "module",
   "scripts": {
@@ -43,7 +43,7 @@
   "license": "MIT",
   "private": false,
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.74",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.97",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@slack/bolt": "^4.6.0",
     "cron-parser": "^5.5.0",

package/skills/beads-tasks/SKILL.md

@@ -3,9 +3,8 @@ name: beads-tasks
 description: >
   Persistent task management via Beads CLI (bd). Use when user mentions tasks, todos, issues, or tracking work.
   Check `which bd` first — if missing, offer: `npm install -g @beads/bd`.
-  Prefer setting `BEATS_DIR` (for example `~/.niahere/beads`) and run commands from there:
-  `cd "$BEATS_DIR" && bd <command>`. Always label: `--label project:<project-name>`.
-  Run `cd "$BEATS_DIR" && bd help-all` for available commands. Not for ephemeral in-conversation tracking.
+  All commands: run from `$BEATS_DIR` (for example `~/.niahere/beads`) and use `bd <command>`. Always label: `--label project:<project-name>`.
+  Run `bd help-all` for available commands. Not for ephemeral in-conversation tracking.
 ---
 
 ## Overview
@@ -19,7 +18,63 @@ Global task manager powered by [Beads](https://github.com/steveyegge/beads). Sto
 2. Ensure `~/.niahere/beads/.beads` exists — `bd init` if not.
 3. Set `BEATS_DIR` to your Beads workspace (for example `~/.niahere/beads`).
 4. All commands: `cd "$BEATS_DIR" && bd <command>`.
-5. Always label with `--label project:<project-name>`.
+5. Always label with `--label project:<name>`.
+6. Run `cd "$BEATS_DIR" && bd help-all` for available commands.
+
+## Core Commands
+
+### Creating tasks
+
+```bash
+# Basic
+bd create --title "Fix auth token refresh" --priority P2 --type bug
+
+# With parent (subtask)
+bd create --title "Extract shared logic" --priority P2 --type task --parent <parent-id>
+
+# With description — ALWAYS add context: what's broken, links, references
+bd create --title "Chat fails on long docs" --type bug --description "Fails on docs >500 pages. Ref: https://..."
+
+# Epic (container for related tasks)
+bd create --title "API performance improvements" --type epic --priority P2
+```
+
+### Updating tasks
+
+`bd update` is the workhorse — use it for reparenting, reprioritizing, retyping, renaming:
+
+```bash
+bd update <id> --parent <new-parent-id>    # Reparent / move under epic
+bd update <id> --parent ""                 # Remove parent (make top-level)
+bd update <id> --priority P1               # Change priority
+bd update <id> --type bug                  # Change type
+bd update <id> --title "Better title"      # Rename
+bd update <id> --status in_progress        # Start work
+bd update <id> --description "..."         # Add/replace description
+bd update <id> --add-label personal        # Add label
+bd update <id> --set-labels bug,urgent     # Replace all labels
+```
+
+Chain multiple updates: `bd update <id> --priority P1 --type bug --parent <parent-id>`
+
+### Viewing tasks
+
+```bash
+bd list                          # Open tasks (tree view)
+bd list --all                    # Include closed/deferred tasks
+bd list --label project:<name>   # Filter by project
+bd show <id>                     # Full details of a task
+bd children <id>                 # List children of a parent
+```
+
+### Closing tasks
+
+```bash
+bd close <id>                    # Close a task
+bd reopen <id>                   # Reopen if closed prematurely
+```
+
+**Warning:** Closing a parent does NOT close or reparent its children. If a parent epic is done but children remain open, reparent them first or they become orphaned top-level items.
 
 ## Decision Points
 
@@ -29,22 +84,45 @@ Global task manager powered by [Beads](https://github.com/steveyegge/beads). Sto
 - User says "done with X" / "finished" → `bd close <id>`
 - User wants to see cross-project work → `bd list` (no project filter)
 - User wants project-specific view → `bd list --label project:<name>`
-- User asks for task in-progress state → use task status:
-  - `bd update <task-id> --status in_progress`
-- `bd set-state ... state=...` is for operational metadata only and does not
-  change list-visible task status.
 - bd not installed → offer install, don't silently fail
 - Ephemeral/conversation-only tracking → use conversation context, not beads
+- `bd set-state ... state=...` is for operational metadata only; it does not change the task status shown in list.
+
+## Hierarchy & Organization
+
+### When to use parent-child vs labels
+
+- **Parent-child** (`--parent`): for structural grouping — epics containing subtasks, features broken into steps.
+- **Labels** (`--add-label`): for cross-cutting tags — `personal`, `urgent`, `project:<name>`. A task can have multiple labels but only one parent.
+
+### Epic patterns
+
+- Use `--type epic` for containers that group related work.
+- Epics can nest: epic > sub-epic > tasks.
+- Keep epic titles broad ("API improvements"), subtask titles specific ("Reduce /search latency from 2s to 200ms").
+
+### Cleanup & auditing
+
+Periodically review with `bd list` and look for:
+- **Orphaned tasks** — top-level items that should be under an epic.
+- **Similar ungrouped tasks** — multiple tasks on the same topic that should share a parent.
+- **Misplaced tasks** — bugs under improvement epics or vice versa.
+- **Stale tasks** — open tasks that are actually done or no longer relevant.
+
+When reorganizing, reparent with `bd update <id> --parent <new-parent>` — don't delete and recreate.
 
 ## Conventions
 
-- Titles: descriptive, actionable (e.g. "Fix auth token refresh in niahere")
-- Labels: `project:<name>`, `bug`, `feature`, `chore`, `urgent`
-- Priority: default P2 unless user specifies urgency
-- Status flow: `open` → `in_progress` → `closed`
+- **Titles:** descriptive, actionable (e.g. "Fix auth token refresh in niahere")
+- **Descriptions:** always include context — what's broken, why it matters, links to references (Canny, threads, logs). Future you needs enough to start working without asking questions.
+- **Types:** `epic`, `bug`, `feature`, `task`, `chore`, `decision`
+- **Priority:** P0 (critical) → P4 (nice-to-have). Default P2 unless user specifies.
+- **Labels:** `project:<name>`, `personal`, `bug`, `feature`, `chore`, `urgent`
+- **Status flow:** `open` → `in_progress` → `closed`
 
 ## Validation
 
-- `cd "$BEATS_DIR" && bd list` returns results after creating a task
+- `bd list` returns results after creating a task
 - Labels appear correctly in list output
+- Parent-child relationships show as indented tree in `bd list`
 - Dependencies show in `bd dep tree`

package/skills/optimization-loop/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: optimization-loop
+description: |
+  The iterative optimization pattern (Karpathy Loop / autoresearch). Reference for running
+  autonomous experiment loops on any target: modify → score → keep or revert → repeat.
+  Use when running multiple iterations of improvement against a measurable metric — code
+  benchmarks, prompt quality, copy effectiveness, config tuning, or any scorable target.
+  Also known as "autoresearch." Use this skill to understand the pattern and discipline.
+  For orchestration (scheduling, user confirmation, job setup), see the "optimize" skill.
+metadata:
+  version: 1.0.0
+---
+
+# Optimization Loop
+
+The Karpathy Loop: autonomous iterative optimization through disciplined experimentation.
+Modify a target, score the result, keep improvements, revert failures, repeat.
+
+This skill defines the **pattern and discipline**. For when/how to schedule and orchestrate
+optimization runs, see the `optimize` skill.
+
+## The Pattern
+
+```
+freeze contract + rubric
+save baseline (never touch again)
+copy baseline → current-best
+
+repeat:
+  1. read state — what's been tried, what worked
+  2. hypothesize — form a specific idea, informed by history
+  3. modify — produce a candidate version
+  4. gate check — hard constraints pass? if no → reject
+  5. score — compare candidate vs current-best (pairwise)
+  6. decide — clearly better? keep. otherwise revert.
+  7. log — append to results.jsonl
+  8. update state — what you tried, what happened, what next
+
+until: budget exhausted, target reached, or plateau detected
+notify user with summary
+```
+
+## Workspace Layout
+
+Each optimization run gets a dedicated, self-contained directory:
+
+```
+~/.niahere/optimizations/{slug}-{hex}/
+├── contract.md           # Frozen at start: objective, scope, constraints, metrics, budget
+├── rubric.md             # Frozen at start: scoring criteria (never modify during run)
+├── baseline.md           # Original version (never modify)
+├── current-best.md       # Best version so far (update only on accept)
+├── accepted/             # Every accepted candidate, numbered
+│   ├── 001.md
+│   ├── 002.md
+│   └── ...
+├── results.jsonl         # One JSON object per experiment (append-only)
+└── state.md              # Your working notebook
+```
+
+**The slug** is human-readable (e.g., `signup-prompt`). The hex suffix (4 chars) prevents
+collisions across multiple runs on the same target.
+
+## The Contract (contract.md)
+
+Freeze this at the start. Never modify during the run.
+
+```markdown
+# Optimization Contract
+
+## Objective
+
+[What we're optimizing and why — one sentence]
+
+## Target
+
+[File path or content being modified]
+[Which sections/parts are in scope — be specific]
+
+## Primary Metric
+
+[The metric being optimized — what "better" means]
+
+## Secondary Metrics (regression guards)
+
+[Metrics that must NOT degrade. Each with a threshold.]
+
+- [e.g., "Word count must stay under 200"]
+- [e.g., "All existing tests must pass"]
+- [e.g., "Readability score must stay above grade 8"]
+
+## Hard Constraints
+
+[Violations = automatic reject, no exceptions]
+
+- [e.g., "Must mention the free trial"]
+- [e.g., "Must pass lint and type check"]
+
+## Soft Preferences
+
+[Tiebreakers — not vetoes, but guide decisions]
+
+- [e.g., "Prefer shorter over longer"]
+- [e.g., "Prefer simple over clever"]
+
+## Budget
+
+- Max iterations: [N]
+- Max wall-clock time: [hours]
+
+## Stop Rules
+
+- All iterations completed
+- Target score reached: [if applicable]
+- Plateau: [N] consecutive discards (default 5)
+```
+
+## Scoring
+
+### For code targets
+
+Run a benchmark or test command. Extract the metric. The command is fixed in the contract
+and cannot be modified during the run.
+
+```
+1. Gate check: tests pass? lint clean? types check? → if any fail, reject immediately
+2. Run benchmark command → extract primary metric
+3. Check secondary metrics for regressions → if any violated, reject
+4. Compare primary metric against current-best
+5. Accept only if clearly improved (above noise floor)
+```
+
+### For content targets (prompts, copy, configs)
+
+Use pairwise comparison. Never absolute 1-10 scoring.
+
+```
+1. Gate check: hard constraints met? (word count, required elements, etc.)
+2. Present both versions side by side:
+   - Randomly assign which is "Version A" and "Version B"
+   - Do NOT label which is current-best vs candidate
+3. Evaluate using the frozen rubric criteria
+4. Pick the winner — candidate must be CLEARLY better, not just different
+5. If it's a toss-up, reject (bias toward stability)
+6. Check secondary metrics for regressions
+```
+
+**Anti-bias controls for LLM-as-judge:**
+
+- Randomize A/B order every time (prevents position bias)
+- Never reveal which version is "current" vs "candidate"
+- If the margin is slim, run the comparison twice with swapped order
+- The rubric is frozen in `rubric.md` — you cannot modify scoring criteria mid-run
+
+## Exploration Strategy
+
+Don't just make incremental tweaks. Use staged exploration:
+
+**Early phase (first ~30% of iterations):** Go broad. Try fundamentally different approaches.
+Different structures, different angles, different trade-offs. You're mapping the space.
+
+**Exploit phase (middle ~50%):** You've found something that works. Refine around it.
+Incremental improvements, wording tweaks, parameter tuning.
+
+**Escape phase (if plateaued):** If you hit 5 consecutive discards, try ONE radical departure
+from current-best — something completely different. If that fails too, stop. You've likely
+found a local optimum.
+
+## The Results Log (results.jsonl)
+
+Append one JSON object per experiment. Never edit previous entries.
+
+```json
+{"n": 1, "status": "keep", "hypothesis": "shorter opening hook", "score_note": "candidate clearly more direct", "duration_s": 45, "timestamp": "2026-04-07T02:14:00Z"}
+{"n": 2, "status": "discard", "hypothesis": "add social proof", "score_note": "toss-up, rejected for stability", "duration_s": 38, "timestamp": "2026-04-07T02:21:00Z"}
+{"n": 3, "status": "crash", "hypothesis": "doubled context window", "error": "benchmark timed out", "duration_s": 300, "timestamp": "2026-04-07T02:28:00Z"}
+```
+
+Every entry must include:
+
+- `n` — experiment number
+- `status` — `keep`, `discard`, or `crash`
+- `hypothesis` — what you tried and why (one line)
+- `score_note` — why you kept or discarded (one line)
+- `timestamp` — when the experiment completed
+
+## Resumability
+
+If the run crashes or is interrupted:
+
+1. Read `current-best.md` — this is always the last accepted version
+2. Read `results.jsonl` — count completed experiments, review what was tried
+3. Read `state.md` — pick up your thinking from where you left off
+4. Continue from the next experiment number
+5. Do NOT re-run completed experiments
+
+## Scoring Integrity
+
+**The scorer and the optimizer must be separated in intent.** You are both proposer and judge,
+so you must be disciplined:
+
+- The rubric is frozen. Do not adjust criteria because a candidate "almost" passes.
+- Do not add special cases to make a favorite candidate win.
+- Do not lower the bar after repeated failures. If nothing passes, that's a valid outcome.
+- If you notice you're gaming your own rubric, stop and note it in state.md.
+
+## When Finished
+
+1. Update `state.md` with a final summary:
+   - Baseline description vs final best description
+   - Total experiments: N run, X accepted, Y discarded, Z crashed
+   - Key findings: what worked, what didn't, surprises
+2. Send a message to the user (via `send_message`):
+   ```
+   [optimization] Done. Ran N experiments on [target].
+   X accepted, Y discarded. [One-line summary of the best version vs baseline].
+   Results: ~/.niahere/optimizations/{slug}-{hex}/
+   ```
+3. Do NOT auto-apply the result. The user reviews `current-best.md` and decides
+   whether to use it.
+
+## Principles
+
+- **Propose, never apply.** The optimization produces a candidate. The user promotes it.
+- **Simplicity criterion.** A marginal improvement that adds complexity isn't worth keeping.
+  Removing something while maintaining quality is always a win.
+- **Bias toward stability.** When in doubt, reject. Keeping a good version is better than
+  accepting a sideways move.
+- **One target, one metric, one run.** Don't try to optimize multiple things simultaneously.
+  Run separate optimizations for separate targets.

package/skills/optimize/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: optimize
+description: |
+  Schedule or run an iterative optimization pass on code, prompts, copy, or any scorable
+  target. Use when user asks to "optimize this", "run experiments", "autoresearch this",
+  "iterate on this overnight", "can this be better", or proactively suggest after completing
+  work that could benefit from further iteration. Also use when a job wants to self-optimize
+  something within its own run. Handles spec confirmation, scoring setup, job scheduling,
+  and result delivery. For the loop discipline itself, references the optimization-loop skill.
+metadata:
+  version: 1.0.0
+---
+
+# Optimize
+
+Schedule or run autonomous optimization passes. This skill handles the orchestration —
+when to use it, how to confirm specs, how to schedule, how to deliver results.
+
+For the loop discipline, scoring methods, and workspace layout, invoke the
+`optimization-loop` skill.
+
+## Two Entry Points
+
+### 1. User explicitly asks
+
+User says "autoresearch this", "optimize this overnight", "run experiments on this",
+"can you iterate on this more", or similar.
+
+**Don't suggest — confirm and schedule.** The user already wants this. Move to Step 1.
+
+### 2. Proactive suggestion (after immediate work)
+
+You just finished a task — rewrote copy, tuned a prompt, optimized a function. The result
+is good, but more iterations could find something better.
+
+Suggest briefly:
+
+> "This is solid. Want me to schedule an overnight optimization pass? I'll run ~30
+> experiments scoring each version against [brief criteria] and have the best version
+> ready by morning."
+
+**Rules for suggesting:**
+
+- Only suggest when there's a clear, scorable metric
+- Only suggest when the target is self-contained (one file, one prompt, one section)
+- Don't suggest for trivial tasks or quick fixes
+- Don't push if the user declines — move on immediately
+- Don't suggest if the user said they need this done now and can't wait
+
+## Step 1: Confirm the Setup
+
+Before scheduling, confirm these with the user. Be concise — a quick summary, not an
+interrogation.
+
+**Target** — What are we optimizing?
+
+- A file (code, config, prompt file)
+- A section of content (landing page hero, email subject line)
+- A prompt or template
+
+**Scoring method** — How do we know if a version is better?
+
+- Code: what benchmark or test command produces a number?
+- Content: what criteria matter? (clarity, persuasiveness, brevity, conversion, etc.)
+- Custom: does the user have a specific scoring script?
+
+**Constraints** — What can't change?
+
+- Hard constraints (must-haves, test requirements, word limits)
+- Soft preferences (shorter is better, simpler is better)
+
+**Secondary metrics** — What must NOT get worse?
+
+- Code: performance can't drop, memory can't increase, tests must pass
+- Content: readability, brand voice, required elements
+- These are regression guards — violations veto an otherwise good candidate
+
+**Iterations** — How many experiments? Default 30. User can adjust.
+
+**When** — Now, or schedule for later? If later, what time?
+
+Example confirmation:
+
+> "Here's the plan:
+>
+> - **Target**: signup prompt at `src/prompts/signup.md`
+> - **Scoring**: pairwise comparison on clarity, persuasiveness, and brevity
+> - **Constraints**: must mention free trial, keep under 150 words
+> - **Regression guards**: readability must stay above grade 8
+> - **Iterations**: 30 experiments
+> - **When**: tonight at midnight
+>
+> Sound right?"
+
+Wait for confirmation before proceeding.
+
+## Step 2: Set Up the Workspace
+
+Create the optimization directory:
+
+```
+~/.niahere/optimizations/{slug}-{hex}/
+```
+
+Where `{slug}` is a short descriptive name and `{hex}` is 4 random hex chars.
+
+Create the frozen files:
+
+1. **contract.md** — objective, target, primary metric, secondary metrics, constraints,
+   preferences, budget, stop rules (see optimization-loop skill for template)
+2. **rubric.md** — detailed scoring criteria
+   - For code: the benchmark command and how to extract the metric
+   - For content: the pairwise comparison rubric with specific criteria and weights
+3. **baseline.md** — copy the current version of the target (the starting point)
+4. **current-best.md** — copy of baseline (will be updated during the run)
+5. **state.md** — initialize with "Run starting. 0 experiments completed."
+6. **accepted/** — create empty directory
+
+## Step 3: Compose the Job Prompt
+
+Build a self-contained job prompt that encodes everything the agent needs to run
+the optimization loop autonomously. The prompt must include:
+
+```
+Job: optimization — {slug}
+
+You are running an optimization loop. Follow the optimization-loop pattern strictly.
+
+## Your workspace
+{absolute path to the optimization directory}
+
+## What to optimize
+{description of the target — file path, what it does, context}
+
+## Current version
+{full content of the target}
+
+## Contract
+{contents of contract.md}
+
+## Scoring rubric
+{contents of rubric.md}
+
+## Loop instructions
+
+Read your workspace files (contract.md, rubric.md, baseline.md, current-best.md,
+state.md, results.jsonl) to understand the current state.
+
+For each iteration:
+1. Read state.md for context on what's been tried
+2. Form a hypothesis — what to change and why
+3. Produce a candidate version
+4. Gate check — verify all hard constraints from the contract
+5. Score — compare candidate vs current-best using the rubric (pairwise, randomized order)
+6. If candidate is clearly better AND no secondary metric regressions:
+   - Update current-best.md
+   - Save candidate to accepted/{NNN}.md
+   - Log {"status": "keep", ...} to results.jsonl
+7. If not clearly better:
+   - Discard candidate
+   - Log {"status": "discard", ...} to results.jsonl
+8. Update state.md with what you tried and learned
+
+Stop when:
+- Completed {N} iterations, OR
+- {stop_count} consecutive discards (plateau), OR
+- Target score reached (if specified in contract)
+
+When finished, update state.md with a final summary and send a message to the user:
+"[optimization] Done. Ran N experiments on {target}. X accepted, Y discarded.
+{One-line summary}. Results: {workspace path}"
+
+IMPORTANT:
+- Do NOT modify contract.md or rubric.md
+- Do NOT auto-apply results to the original file
+- Do NOT stop to ask the user questions — run autonomously until done
+```
+
+## Step 4: Schedule the Job
+
+Use the `add_job` MCP tool (preferred) or `nia job add` CLI:
+
+- **name**: `optimize-{slug}` (e.g., `optimize-signup-prompt`)
+- **schedule**: ISO timestamp for the agreed time, or now
+- **schedule_type**: `once`
+- **prompt**: the composed job prompt from Step 3
+- **always**: `true` (overnight runs need to ignore active hours)
+- **stateless**: `yes` (the optimization uses its own workspace, not the job's state.md)
+
+Confirm to the user:
+
+> "Scheduled. The optimization run starts at {time} and will run ~{N} experiments.
+> I'll message you when it's done with the results."
+
+## Step 5: After Completion
+
+When the user asks about results, or when reviewing the notification:
+
+1. Read `~/.niahere/optimizations/{slug}-{hex}/state.md` for the summary
+2. Read `results.jsonl` for the experiment log
+3. Show `current-best.md` vs `baseline.md` — the diff is the value
+4. Show the accepted progression if the user wants to see the journey
+5. Ask if the user wants to apply the result to the original target
+
+## Running Now vs Later
+
+**"Run it now":** Schedule with the current timestamp. The user stays in the conversation
+and can check results when the job finishes. Good for shorter runs (10-15 iterations).
+
+**"Schedule for later":** Schedule for a specific time (midnight, after hours). The user
+goes about their day. The notification arrives when done. Good for longer runs (30+ iterations).
+
+**"Run it inline":** If the user wants to optimize something RIGHT NOW in this conversation
+(not as a job), you can run the optimization-loop pattern directly without scheduling a job.
+Use this for quick 5-10 iteration runs where the user is watching.
+
+## When a Job Self-Optimizes
+
+A running job (e.g., news-curator, prompt-generator) can use this pattern to improve
+its own approach. The flow:
+
+1. Job creates an optimization subdirectory in its workspace or in `~/.niahere/optimizations/`
+2. Runs the loop inline (not as a sub-job — within its own execution)
+3. Saves the best version in the workspace
+4. Does NOT auto-apply changes to its own prompt or config
+5. Sends a message: "I found a better approach for [X]. Review at [path]."
+6. The user decides whether to apply it (e.g., via `nia job update`)
+
+## What NOT to Optimize
+
+- Things without a clear metric (vague "make it better")
+- Targets that require human judgment with no proxy (art, brand voice decisions)
+- Multi-file changes with complex interdependencies
+- Anything where the scoring takes longer than the modification (defeats the loop)
+- Security-sensitive code where autonomous changes are risky
+
+If the target doesn't fit, say so. Not everything benefits from iterative optimization.
+Sometimes the first good version is the right answer.