chore(ai): document src/lib.mjs

- Added JSDoc to all exported functions in src/lib.mjs
- Added detailed flow comments for cmdLock and cmdComplete
- Created docs/lib-overview.md with high-level architectural documentation
- Created src/context/CONTEXT_2026-02-14T21-30-00Z.md
- Updated task-logs/daily/ with completion record

Co-authored-by: PR0M3TH3AN <[email protected]>

docs/lib-overview.md

@@ -0,0 +1,58 @@
+# src/lib.mjs: Core Logic Overview
+
+## Summary
+`src/lib.mjs` is the orchestration engine for Torch. It implements the high-level commands (`check`, `lock`, `list`, `complete`) that coordinate between local configuration, the file system (task logs), and Nostr relays (distributed locks).
+
+It is designed to be:
+- **Stateless**: No persistent local database; relies on Nostr events and flat files.
+- **Race-Condition Safe**: Uses a commit-wait-reveal pattern to handle concurrent agent starts.
+- **Dependency Injected**: Nearly all external side-effects (relays, time, FS) can be mocked.
+
+## Public API
+
+### `cmdCheck(cadence, deps)`
+Aggregates the current state of the world for a given cadence.
+- **Inputs**: Cadence ('daily'/'weekly').
+- **Outputs**: JSON object with lists of `locked`, `completed`, `paused`, and `available` agents.
+- **Side Effects**: Queries relays, reads `task-logs/`, reads `torch-config.json`.
+
+### `cmdLock(agent, cadence, dryRun, deps)`
+Attempts to claim a task.
+- **Returns**: `{ status: 'ok', eventId: '...' }`
+- **Throws**: `ExitError(3)` if the lock is denied (already active, completed, or race lost).
+
+### `cmdComplete(agent, cadence, dryRun, deps)`
+Finalizes a task.
+- **Action**: Publishes a permanent event (no expiration) with `status: 'completed'`.
+- **Constraint**: Requires an existing active lock for the agent.
+
+### `cmdList(cadence, deps)`
+Displays a CLI-friendly table of active locks.
+
+## Locking Flow (Sequence)
+
+1. **Check**: Query relays for any existing valid lock for `(agent, cadence, date)`.
+   - If found and `status=completed`: **Abort** (Task done).
+   - If found and `status=started` (and not expired): **Abort** (Agent busy).
+2. **Generate**: Create a new ephemeral Nostr keypair.
+3. **Build**: Create a signed event (Kind 30078) with:
+   - Tags: `d` (identifier), `expiration`, `t` (search tags).
+   - Content: JSON payload with metadata.
+4. **Publish**: Send to all configured relays.
+5. **Race Check**:
+   - Wait `RACE_CHECK_DELAY_MS` (default 2000ms).
+   - Query relays again.
+   - If another valid event exists with an *earlier* `created_at`: **Abort** (Race lost).
+   - Otherwise: **Success**.
+
+## Key Invariants
+
+- **Uniqueness**: Only one valid lock per (agent, cadence, date) should exist at a time.
+- **Expiration**: All locks must have an `expiration` tag (NIP-40) to prevent zombies, except completion events.
+- **Completion**: A completion event is permanent (no expiration) and effectively "freezes" the slot for that date.
+
+## When to Change
+
+- **Protocol Upgrades**: If changing the Nostr event structure or tags.
+- **Concurrency Tuning**: Adjusting `RACE_CHECK_DELAY_MS` or retry logic.
+- **New Commands**: Adding new lifecycle states (e.g., `failed` or `paused` via CLI).