jfl 0.2.3 → 0.2.4

package/README.md

@@ -2,71 +2,22 @@
 
 **The context layer for AI-native teams.**
 
-JFL provides persistent context for AI workflows. Agents can read what happened in previous sessions, understand decisions that were made, and access project knowledge—eliminating the cold-start problem where each AI interaction begins from zero.
+JFL provides persistent context for AI workflows. Agents read what happened in previous sessions, understand decisions made, and access project knowledge — eliminating the cold-start problem where each AI interaction begins from zero.
 
 Context lives in git as structured files (markdown, JSONL). Any AI tool can integrate via MCP.
 
-**Quick Links:** [GitHub](https://github.com/402goose/jfl-cli) · [npm](https://www.npmjs.com/package/jfl)
+**Quick Links:** [GitHub](https://github.com/402goose/jfl-cli) | [npm](https://www.npmjs.com/package/jfl)
 
 ---
 
 ## What Problem Does This Solve?
 
-AI agents are stateless by default. Each new session starts from scratch:
+AI agents are stateless. Each session starts from scratch:
 - Previous decisions aren't remembered
 - Work from other sessions isn't visible
 - Context has to be re-explained every time
 
-For multi-session projects or team collaboration with AI, this creates coordination overhead. JFL provides a shared context layer that accumulates over time and is accessible to any AI tool.
-
----
-
-## Where JFL Fits
-
-JFL is a coordination and context layer for AI workflows.
-
-**What it provides:**
-- Persistent memory across sessions (journal entries, decisions, code context)
-- Shared context that any AI can read and contribute to
-- Git-native storage (markdown, JSONL) that survives model changes
-
-**What it works with:**
-- AI coding tools (Claude Code, Cursor)
-- Agent frameworks (CrewAI, AutoGPT)
-- Custom AI workflows
-
-**Architecture:**
-JFL runs as a local daemon (Context Hub on port 4242) and integrates via MCP. Your project's context lives in `.jfl/` as structured files. Any AI tool with MCP support can read and update this context.
-
-**Use cases:**
-- Solo developers building with AI (never lose context between sessions)
-- Teams coordinating work with AI agents (shared memory across people and agents)
-- Multi-session projects (context accumulates, agents get smarter over time)
-
----
-
-## What JFL Does
-
-JFL provides three core systems:
-
-**Context Hub** — A local daemon (port 4242) that aggregates journal entries, knowledge docs, and code headers. Any AI can query it via MCP to understand what happened across sessions, what decisions were made, and what code does.
-
-**Synopsis** — Generates work summaries by rolling up journal entries, git commits, and file headers. Answers questions like "what happened this week?" or "what did Alex work on?" with structured reports and time breakdowns.
-
-**Session Management** — Automatic session isolation for parallel work. Single sessions work directly on your branch for simplicity. Multiple concurrent sessions use isolated worktrees to prevent conflicts. Auto-commit saves work every 2 minutes, and sessions auto-merge when finished.
-
----
-
-## How Teams Use It
-
-**Solo developers:**
-Build with AI tools across multiple sessions without re-explaining context. Your project knowledge accumulates—agents get smarter over time, not dumber.
-
-**Teams with AI agents:**
-Multiple people and AI agents can work in parallel. Everyone reads from and writes to the same context layer. No meetings to sync up, no handoff docs that get stale.
-
-**Works with your existing tools:**
-JFL integrates with Claude Code, Cursor, Clawdbot, CrewAI, and any tool that supports MCP. Switch models or tools tomorrow—your context survives because it's git-native.
+JFL provides a shared context layer that accumulates over time and is accessible to any AI tool.
 
 ---
 
@@ -76,527 +27,556 @@ JFL integrates with Claude Code, Cursor, Clawdbot, CrewAI, and any tool that sup
 npm install -g jfl
 ```
 
-**Requirements:** Node ≥18
+**Requirements:** Node >= 18
 
-JFL automatically installs dependencies including Context Hub MCP and x402 payment tools.
+**Also installs:**
+- `jfl-context-hub-mcp` — MCP server binary for Context Hub
+- `jfl-service-registry-mcp` — MCP server binary for Service Registry
 
 ---
 
-## Quick Start (TL;DR)
+## Quick Start
 
 ```bash
-# Initialize a GTM workspace
-jfl init my-product-gtm
-
-# Check status
-cd my-product-gtm
-jfl status
+# Create a GTM workspace
+jfl init -n my-project
 
-# View campaign dashboard
-jfl hud
+# Start working
+cd my-project
+claude                        # Claude Code — hooks fire automatically
 
-# See what happened recently
-jfl synopsis 24
-
-# Start interactive session (auto-updates on first run)
-jfl
+# Inside Claude Code:
+/hud                          # Project dashboard — start here
 ```
 
----
-
-## Core Commands
-
-| Command | Description |
-|---------|-------------|
-| `jfl` | Interactive session (auto-updates GTM template + npm package) |
-| `jfl init [name]` | Initialize new GTM workspace |
-| `jfl status` | Show project status and auth |
-| `jfl hud` | Campaign dashboard (ship date, phases, pipeline) |
-| `jfl synopsis [hours] [author]` | Work summary (journal + commits + code) |
-| `jfl update` | Pull latest skills and templates |
-| `jfl context-hub [action]` | Manage Context Hub daemon (start/stop/status) |
-| `jfl session [action]` | Session management (create/list/end) |
-| `jfl repair` | Fix .jfl/config.json if corrupted |
-
-### Platform Commands
-
-| Command | Description |
-|---------|-------------|
-| `jfl login` | Authenticate to JFL platform |
-| `jfl login --x402` | Use x402 Day Pass ($5/day crypto) |
-| `jfl wallet` | Show wallet and day pass status |
-| `jfl deploy` | Deploy to JFL platform |
-| `jfl agents [action]` | Manage parallel agents (list/create/start/stop) |
-| `jfl feedback` | Rate your session |
+That's it. SessionStart hooks handle repo sync, session branching, Context Hub startup, and auto-commit. You just work.
 
 ---
 
-## How It Works
-
-**The system lives in git. Everything is files.**
+## Architecture
 
-No proprietary database. No lock-in. Your company's knowledge graph is version-controlled and portable.
+JFL workspaces are **context layers**, not code repos. Product code lives in separate service repos that register with the GTM.
 
 ```
-my-project-gtm/              ← GTM workspace (strategy, content, brand)
+my-project/                    <- GTM workspace (strategy, context, orchestration)
 ├── .jfl/
-│   ├── config.json          ← Project settings
-│   ├── journal/             ← Session journals (JSONL)
-│   └── context-hub.pid      ← Context Hub daemon
-├── product/                 ← SUBMODULE → your-product-repo
-├── knowledge/               ← Strategy docs (VISION, ROADMAP, etc.)
-├── content/                 ← Generated marketing content
-├── suggestions/             ← Contributor workspaces
-├── .claude/skills/          ← JFL skills
-└── CLAUDE.md                ← AI instructions
-
-your-product-repo/           ← SEPARATE REPO (all code)
+│   ├── config.json           <- Project config (team, services, ports)
+│   ├── journal/              <- Session journals (JSONL, one file per session)
+│   ├── memory.db             <- Indexed memory (TF-IDF + embeddings)
+│   ├── service-events.jsonl  <- Event bus file-drop
+│   └── services.json         <- Registered services
+├── knowledge/                <- Strategy docs (VISION, ROADMAP, THESIS, etc.)
+├── content/                  <- Generated content
+├── suggestions/              <- Per-contributor workspaces
+├── .claude/
+│   ├── settings.json         <- Claude Code hooks (SessionStart, Stop, etc.)
+│   ├── agents/               <- Service agent definitions
+│   └── skills/               <- Slash commands (/hud, /content, etc.)
+├── scripts/session/          <- Session management (init, sync, cleanup)
+├── CLAUDE.md                 <- AI instructions
+└── .mcp.json                 <- MCP server config (Context Hub)
+
+my-api/                        <- Service repo (registered in GTM)
 ├── src/
-├── cli/
-└── ...
+├── .jfl/config.json          <- type: "service", gtm_parent: "/path/to/gtm"
+└── .jfl/journal/             <- Service journals (synced to GTM on session end)
 ```
 
-**When you start a session:**
-1. The agent loads your full context (via Context Hub)
-2. You work (code, content, strategy, whatever)
-3. Decisions and learnings are captured automatically
-4. Session ends, context persists
-5. Next session picks up exactly where you left off
-
-**Why git-native?**
-
-All context is stored as markdown and JSONL in your git repository. This means:
-- Version controlled (see how context evolved)
-- Portable (no vendor lock-in)
-- Model-agnostic (switch AI tools without losing context)
-- Collaborative (merge and branch like code)
-
-**It compounds.** The more you use it, the more it knows. Six months in, the agent understands your business better than most employees would.
-
-**Why GTM workspace is separate from product code:**
+**Why separate?**
 - Clean separation of concerns
-- Product code doesn't get polluted with GTM docs
-- Multiple GTMs can reference the same product
-- `jfl update` updates GTM toolkit without touching product code
-- Team can work on product independently
+- Services work independently
+- Multiple services register to one GTM
+- `jfl update` updates tooling without touching service code
+- Journal entries sync from services to parent GTM
 
 ---
 
-## Clawdbot Integration
+## Core Systems
 
-JFL ships with a Clawdbot plugin for Telegram-based agents.
+### Context Hub
 
-```bash
-# Install plugin into Clawdbot
-jfl clawdbot setup
+A per-project daemon that aggregates journal entries, knowledge docs, code headers, and events into a unified context layer. Any AI can query it via MCP.
 
-# Check installation status
-jfl clawdbot status
+```bash
+jfl context-hub ensure        # Start if not running (idempotent)
+jfl context-hub status        # Check health
+jfl context-hub stop          # Stop daemon
+jfl context-hub restart       # Restart daemon
+jfl context-hub doctor        # Diagnose all projects (OK/ZOMBIE/DOWN/STALE)
+jfl context-hub ensure-all    # Start for all GTM projects
+jfl context-hub dashboard     # Live event + context dashboard
+jfl context-hub install-daemon  # Auto-start on boot (launchd/systemd)
+jfl context-hub uninstall-daemon  # Remove auto-start
+jfl context-hub query         # Query context from CLI
+jfl context-hub serve         # Run in foreground (daemon mode)
 ```
 
-After setup, restart your gateway (`clawdbot gateway`). The plugin is dormant until you activate it:
+**Per-project ports** assigned automatically (or set in `.jfl/config.json` → `contextHub.port`).
 
-1. Send `/jfl` in Telegram
-2. Pick a project (or auto-picks if you have one)
-3. Plugin activates — context injection, decision capture, auto-commit
+**MCP Tools** (available to Claude Code and any MCP client):
 
-**Telegram Commands:**
+| Tool | What It Does |
+|------|-------------|
+| `context_get` | Unified context (journal + knowledge + code headers) |
+| `context_search` | Semantic search across all sources |
+| `context_status` | Daemon health check |
+| `context_sessions` | Activity from other sessions |
+| `memory_search` | Search indexed journal memories |
+| `memory_status` | Memory system statistics |
+| `memory_add` | Add manual memory entry |
 
-| Command | What it does |
-|---------|-------------|
-| `/jfl` | Activate JFL / show status |
-| `/context <query>` | Search project knowledge |
-| `/journal <type> <title> \| <summary>` | Write a journal entry |
-| `/hud` | Project dashboard |
+**Resilience:** 5-layer system — MCP auto-recovery on ECONNREFUSED, health-check-before-ensure hooks, `ensure-all` for batch startup, `doctor` diagnostics, launchd/systemd daemon with keepalive.
 
-**What the plugin does automatically:**
-- Injects relevant project context before every AI response
-- Captures decisions to the journal after responses
-- Auto-commits work periodically
-- Manages session branches for isolated work
+### MAP Event Bus
 
-**Claude also gets tools** (`jfl_context`, `jfl_journal`) it can use proactively without you asking.
+Metrics, Agents, Pipeline — an in-process event bus inside Context Hub.
 
----
+- **Ring buffer** (1000 events) with JSONL persistence
+- **Service event bridge** — watches `.jfl/service-events.jsonl`, converts to events
+- **Journal bridge** — watches `.jfl/journal/`, emits events on new entries
+- **Pattern-matching subscriptions** (glob support)
+- **Transports:** SSE, WebSocket, HTTP polling
+- **Event types:** `session:started`, `session:ended`, `task:completed`, `journal:entry`, `service:healthy`, `custom`, and more
 
-## OpenClaw Protocol
+Services emit events by appending to `.jfl/service-events.jsonl` — no auth needed, Context Hub watches the file automatically.
 
-OpenClaw is JFL's runtime-agnostic agent protocol. Any AI agent can become a JFL team member:
+### Memory System
+
+Hybrid search over all journal entries with TF-IDF (40%) + semantic embeddings (60%).
 
 ```bash
-# Register agent with a GTM workspace
-jfl openclaw register -g /path/to/gtm -a my-agent
+jfl memory init               # Initialize database
+jfl memory search "pricing"   # Search memories
+jfl memory status             # Stats and health
+jfl memory index [--force]    # Reindex journal entries
+jfl ask "what did we decide about auth?"  # Shorthand
+```
 
-# Start session (creates branch, auto-commit, Context Hub)
-jfl openclaw session-start -a my-agent --json
+Auto-indexes every 60 seconds. Boosts recent entries (1.3x), decisions (1.4x), features (1.2x). Works with or without OpenAI embeddings — TF-IDF alone provides solid keyword search.
 
-# Search project context
-jfl openclaw context -q "pricing decisions" --json
+### Session Management
 
-# Write journal entry
-jfl openclaw journal --type decision --title "Chose OAuth" --summary "Better for multi-tenant"
+Automatic session isolation for parallel work:
 
-# End session (merge, cleanup)
-jfl openclaw session-end --json
+- **Single session:** Works directly on a session branch (no worktree overhead)
+- **Multiple concurrent sessions:** Isolated git worktrees prevent conflicts
+- **Auto-commit:** Saves work every 2 minutes (knowledge, journal, suggestions)
+- **Crash recovery:** Detects uncommitted work in stale sessions, auto-commits on next start
+
+```bash
+# Hooks handle everything automatically. Manual control:
+jfl session create            # Create session
+jfl session list              # List active sessions
+jfl session end               # End and merge
+./scripts/session/auto-commit.sh start  # Background auto-commit
 ```
 
-All commands support `--json` for programmatic use. See `jfl openclaw --help` for the full command list.
+**SessionStart hook flow:**
+1. Sync repos (prevent context loss)
+2. Check for stale sessions, auto-cleanup if > 5
+3. Recover uncommitted work from crashed sessions
+4. Create session branch (or worktree if concurrent)
+5. Start auto-commit
+6. Health-check Context Hub (start only if down)
 
 ---
 
-## Context Hub
+## Service Agents
 
-Context Hub is a local daemon (port 4242) that provides unified context to any AI:
+Register external repos as services in your GTM. Each service gets an agent definition, skill wrapper, and journal sync.
 
 ```bash
-# Start Context Hub
-jfl context-hub start
-
-# Check status
-jfl context-hub status
-
-# Stop daemon
-jfl context-hub stop
+# Onboard a service repo
+jfl onboard /path/to/my-api --name my-api --type api
+
+# Or create from scratch
+jfl services create
+
+# Manage services
+jfl services list             # All registered services
+jfl services status my-api    # Health check
+jfl services start my-api     # Start a service
+jfl services stop my-api      # Stop a service
+jfl services validate --fix   # Validate and auto-repair
+jfl services sync-agents      # Sync peer agent definitions
+jfl services scan             # Discover services in directory
+jfl services deps             # Show dependency graph
+jfl services                  # Interactive TUI (no args)
 ```
 
-**What it aggregates:**
-- **Journal entries** — What happened across sessions (`.jfl/journal/*.jsonl`)
-- **Knowledge docs** — Strategy, vision, roadmap (`knowledge/*.md`)
-- **Code headers** — `@purpose`, `@spec`, `@decision` tags from files
+**What onboarding creates:**
+- Agent definition (`.claude/agents/service-{name}.md`)
+- Skill wrapper (`.claude/skills/{name}/SKILL.md` + `handler.sh`)
+- Service entry in `.jfl/services.json`
+- Config in service repo (`.jfl/config.json` with `gtm_parent`)
 
-**MCP Integration:**
-Context Hub exposes MCP tools that Claude Code and other AIs can use:
-- `context_get` — Get unified context (journal + knowledge + code)
-- `context_search` — Semantic search across all sources
-- `context_status` — Check daemon status
-- `context_sessions` — See activity from other sessions
+**Phone-home on session end:** When a service session ends, it syncs to the parent GTM:
+- Journal entries copied to `GTM/.jfl/journal/service-{name}-*.jsonl`
+- Comprehensive sync payload (git stats, health, environment)
+- GTM agent notified via event bus
+- Never blocks session end
 
-Add to your `.mcp.json`:
-```json
-{
-  "jfl-context": {
-    "command": "jfl-context-hub-mcp"
-  }
-}
+**Invoke from GTM:**
+```
+/my-api status               # Check service health
+/my-api recent               # Recent changes
 ```
 
 ---
 
-## Synopsis - Work Summaries
+## Commands
 
-Synopsis aggregates journal entries, git commits, and code file headers to answer "what happened?"
+### Core
 
-```bash
-# Last 24 hours, all authors
-jfl synopsis 24
+| Command | Description |
+|---------|-------------|
+| `jfl init -n <name>` | Create new GTM workspace |
+| `jfl status` | Project status and auth |
+| `jfl hud [-c\|--compact]` | Campaign dashboard (ship date, phases, pipeline) |
+| `jfl update [--dry]` | Pull latest skills, scripts, templates (preserves CLAUDE.md, .mcp.json) |
+| `jfl synopsis [hours] [author]` | Work summary (journal + commits + file headers) |
+| `jfl repair` | Fix corrupted .jfl/config.json |
+| `jfl validate-settings [--fix] [--json]` | Validate and repair .claude/settings.json |
+| `jfl preferences [--clear-ai] [--show]` | Manage JFL preferences |
+| `jfl profile [action]` | Manage profile (show, edit, export, import, generate) |
+| `jfl test` | Test onboarding flow (isolated environment) |
+
+### Context Hub
 
-# Last 8 hours
-jfl synopsis 8
+| Command | Description |
+|---------|-------------|
+| `jfl context-hub ensure` | Start daemon if not running |
+| `jfl context-hub stop [--purge]` | Stop daemon |
+| `jfl context-hub restart` | Restart daemon |
+| `jfl context-hub status` | Health check |
+| `jfl context-hub doctor [--clean]` | Diagnose all projects |
+| `jfl context-hub ensure-all` | Start for all GTM projects |
+| `jfl context-hub dashboard` | Live event/context dashboard |
+| `jfl context-hub query` | Query context from CLI |
+| `jfl context-hub serve` | Run in foreground (daemon mode) |
+| `jfl context-hub install-daemon` | Auto-start on boot |
+| `jfl context-hub uninstall-daemon` | Remove auto-start |
+
+### Memory
 
-# What did Alex work on in last 48 hours?
-jfl synopsis 48 alex
+| Command | Description |
+|---------|-------------|
+| `jfl memory init` | Initialize memory database |
+| `jfl memory search <query> [-t type] [-n max]` | Search indexed memories |
+| `jfl memory status` | Stats and health |
+| `jfl memory index [--force]` | Reindex journal entries |
+| `jfl ask <question> [-t type]` | Shorthand for memory search |
 
-# Filter by git author name
-jfl synopsis 24 --author "Andrew"
-```
+### Services
 
-**Output includes:**
-- Summary of features, fixes, decisions
-- Time audit breakdown (infra vs features vs docs)
-- Per-team-member contributions
-- Health checks (too much infra? not enough outreach?)
-- Next steps from journal entries
-- Incomplete/stubbed items
+| Command | Description |
+|---------|-------------|
+| `jfl onboard <path> [-n name] [-t type]` | Register service in GTM |
+| `jfl services` | Interactive service manager TUI |
+| `jfl services create [--skip-ai]` | Create new service (wizard) |
+| `jfl services list` | List all services |
+| `jfl services status [name]` | Health check |
+| `jfl services start <name>` | Start a service |
+| `jfl services stop <name> [--force]` | Stop a service |
+| `jfl services scan [--path <p>] [--dry-run]` | Discover services in directory |
+| `jfl services deps [validate]` | Show/validate dependency graph |
+| `jfl services validate [--fix] [--json]` | Validate configs, auto-repair |
+| `jfl services sync-agents [--dry-run] [--current]` | Sync peer agent definitions |
+| `jfl service-agent <action> [name]` | Manage MCP agents (init, generate, generate-all, register, unregister, list, clean) |
+| `jfl service-manager <action>` | Service Manager daemon (start, stop, restart, status, serve) |
+| `jfl migrate-services [gtm-path]` | Migrate from references/ to service manager |
+
+### Agent Orchestration
 
----
+| Command | Description |
+|---------|-------------|
+| `jfl ralph [args]` | Ralph-tui agent loop orchestrator |
+| `jfl peter [action]` | Peter Parker model-routed orchestrator (setup, run, status) |
+| `jfl orchestrate [name] [--list] [--create <n>]` | Multi-service orchestration workflows |
+| `jfl dashboard` | Interactive service monitoring TUI |
+| `jfl events [-p pattern]` | Live MAP event bus dashboard |
 
-## Session Management
+### Platform
 
-Work in isolated git worktrees with automatic commit/merge:
+| Command | Description |
+|---------|-------------|
+| `jfl login [--platform\|--x402\|--solo\|--team\|--free]` | Authenticate |
+| `jfl logout` | Logout from platform |
+| `jfl wallet` | Wallet and day pass status |
+| `jfl deploy [-f]` | Deploy to JFL platform |
+| `jfl agents [action]` | Manage parallel agents (list, create, start, stop, destroy) |
+| `jfl feedback [action]` | Rate session (0-5), view or sync |
 
-```bash
-# Create new session (creates worktree + branch)
-jfl session create
+### Telemetry & Intelligence
+
+| Command | Description |
+|---------|-------------|
+| `jfl telemetry status` | Show telemetry status |
+| `jfl telemetry show` | Show queued events |
+| `jfl telemetry digest [--hours N] [--format json] [--platform]` | Cost breakdown, health analysis, suggestions |
+| `jfl telemetry reset` | Reset install ID |
+| `jfl telemetry track --category <c> --event <e>` | Emit event from shell scripts |
+| `jfl improve [--dry-run] [--auto] [--hours N]` | Self-improvement loop: analyze, suggest, create issues |
+| `jfl preferences --no-telemetry` | Opt out of telemetry |
 
-# List active sessions
-jfl session list
+**Model cost tracking:** Every Stratus API call emits token counts and estimated cost. Covers claude-opus-4-6, claude-sonnet-4-6, claude-sonnet-4-5, claude-haiku-3-5, gpt-4o.
 
-# End session (merges to main, removes worktree)
-jfl session end [session-name]
+**`jfl telemetry digest`** analyzes local events: per-model cost tables, command stats, error rates, hub/memory/session health. Flags issues like high MCP latency, cost concentration, crash rates.
 
-# Auto-commit running in background (every 2 min)
-./scripts/session/auto-commit.sh start
-```
+**`jfl improve`** generates actionable suggestions from the digest. `--dry-run` previews, `--auto` creates GitHub issues tagged `[jfl-improve]`.
 
-**Each session:**
-- Isolated git worktree (parallel work without conflicts)
-- Auto-commits knowledge/, content/, suggestions/ every 2 minutes
-- Auto-merges to main on session end
-- Removes worktree and branch when merged
-- Writes journal entries (enforced by hooks)
-
-**SessionStart hook:**
-- CD to worktree
-- Sync repos (jfl-gtm + product submodule)
-- Run doctor check (detect issues)
-- Start Context Hub
-- Show HUD dashboard
-
-**Stop hook:**
-- Auto-commit uncommitted changes
-- Merge to main (with conflict handling)
-- Cleanup worktree and branch
-- Validate journal entry exists
+### Voice Input
 
----
+Local voice-to-text using Whisper models.
 
-## Authentication
+| Command | Description |
+|---------|-------------|
+| `jfl voice` | Start voice recording with VAD |
+| `jfl voice setup` | First-time setup wizard |
+| `jfl voice devices` | List audio input devices |
+| `jfl voice test [-d device]` | Test record + transcribe (3s) |
+| `jfl voice recording [-d device] [-t seconds]` | Test recording only |
+| `jfl voice record [-d device]` | Record with VAD |
+| `jfl voice hotkey [-d device] [-m mode]` | Global hotkey listener (macOS) |
+| `jfl voice daemon start\|stop\|status` | Background hotkey daemon (macOS) |
+| `jfl voice model list\|download\|default [name]` | Manage whisper models |
+| `jfl voice help` | Voice command help |
+
+### Skills
 
-**GitHub OAuth:**
-```bash
-jfl login
-```
+| Command | Description |
+|---------|-------------|
+| `jfl skills list [-a\|--available] [-c category] [-t tag]` | List installed or available skills |
+| `jfl skills install <skills...>` | Install skill(s) |
+| `jfl skills remove <skills...>` | Remove skill(s) |
+| `jfl skills update [skill] [--dry]` | Update installed skill(s) |
+| `jfl skills search <query>` | Search for skills |
+| `jfl brand [subcommand]` | Brand architect shortcut |
+| `jfl content <type> [topic]` | Content creator shortcut |
 
-**x402 Crypto Wallet ($5/day micropayments):**
-```bash
-jfl login --x402
-```
+### OpenClaw Protocol
 
-Enables:
-- Gasless USDC transfers (no ETH needed)
-- $5/day Day Pass payments
-- httpcat-cli bundled and configured
+Runtime-agnostic agent integration. All commands support `--json`.
 
-View auth status:
-```bash
-jfl status
-jfl wallet
-```
+| Command | Description |
+|---------|-------------|
+| `jfl openclaw session-start -a <agent>` | Start agent session |
+| `jfl openclaw session-end [-s]` | End session (merge, sync) |
+| `jfl openclaw context [-q query] [-t type]` | Query project context |
+| `jfl openclaw journal --type <t> --title <t> --summary <s>` | Write journal entry |
+| `jfl openclaw heartbeat` | Health pulse (auto-commit, check hub) |
+| `jfl openclaw status` | Agent session state |
+| `jfl openclaw register -g <gtm>` | Register agent with GTM |
+| `jfl openclaw gtm-list` | List registered GTM workspaces |
+| `jfl openclaw gtm-switch <id>` | Switch active GTM workspace |
+| `jfl openclaw gtm-create <name> [-p path]` | Create and register new GTM |
+| `jfl openclaw tag <service> <message>` | Send message to service agent |
+
+### Clawdbot
+
+Telegram-based agent with context injection.
 
----
+| Command | Description |
+|---------|-------------|
+| `jfl clawdbot setup` | Install JFL plugin into Clawdbot |
+| `jfl clawdbot status` | Plugin installation status |
 
-## Pricing
+### GTM
 
-| Plan | Price | What You Get |
-|------|-------|--------------|
-| **Trial** | $0 | Full toolkit, foundation + brand setup. Use with Claude Code. |
-| **Day Pass** | $5/day | Pay only days you use. AI included. Chat in Telegram/Slack/Discord. Pay with USDC (gasless). |
-| **Solo** | $49/mo | Just you. AI included. Best if you use it most days. |
-| **Team** | $199/mo | Up to 5 seats (+$25/seat after). AI for everyone. Parallel agents. Team analytics. |
+| Command | Description |
+|---------|-------------|
+| `jfl gtm process-service-update [file]` | Process service sync notification (hook) |
 
 ---
 
-## Skills Library
+## Skills
 
-JFL includes skills for Claude Code:
+Pre-installed slash commands for Claude Code:
 
 | Skill | Description |
 |-------|-------------|
-| `/hud` | Campaign dashboard with countdown and tasks |
+| `/hud` | Project dashboard — guided workflow, progress tracking |
 | `/brand-architect` | Generate brand identity (marks, colors, typography) |
-| `/web-architect` | Implement assets (SVG, favicon, OG images) |
+| `/web-architect` | Implement brand assets, audit code |
 | `/content` | Create content (threads, posts, articles, one-pagers) |
-| `/x-algorithm` | Optimize tweets for X For You feed |
-| `/video` | Founder video scripts (viral short-form) |
-| `/startup` | Startup journey guidance (idea to scale) |
-| `/agent-browser` | Headless browser automation |
-| `/search` | Semantic search across GTM knowledge base |
+| `/founder-video` | Viral short-form video scripts |
+| `/startup` | Startup guidance (idea to scale) |
 | `/spec` | Multi-agent adversarial spec refinement |
-| `/react-best-practices` | React/Next.js performance optimization |
+| `/fly-deploy` | Fly.io deployment management |
+| `/search` | Semantic search across knowledge base |
+| `/end` | End session gracefully (merge, cleanup) |
+| `/ralph-tui` | AI agent loop orchestrator |
+| `/x-algorithm` | X/Twitter For You feed optimization |
+| `/agent-browser` | Headless browser automation |
+| `/react-best-practices` | React/Next.js performance patterns |
 | `/remotion-best-practices` | Remotion video creation in React |
+| `/geo` | GEO-first SEO analysis for AI search engines |
+| `/geo-audit` | Full website GEO+SEO audit with parallel agents |
 
-Run in Claude Code after `jfl init`.
+```bash
+# Install more skills
+jfl skills list --available
+jfl skills install geo-audit
+```
 
 ---
 
 ## Knowledge Layer
 
-JFL structures your GTM knowledge:
+Strategy docs filled through conversation, not forms:
 
 ```
 knowledge/
-├── VISION.md              # What you're building
+├── VISION.md              # What you're building, who it's for
 ├── NARRATIVE.md           # How you tell the story
 ├── THESIS.md              # Why you'll win
 ├── ROADMAP.md             # What ships when
 ├── BRAND_BRIEF.md         # Brand inputs
 ├── BRAND_DECISIONS.md     # Finalized brand choices
-├── VOICE_AND_TONE.md      # How the brand speaks
-└── TASKS.md               # Master task list
-```
-
-These docs are the source of truth. AIs read them to generate content, make decisions, and maintain consistency.
-
----
-
-## Auto-Update
-
-JFL automatically checks for updates on session start (24-hour cache):
-
-- **Minor/patch versions** — Auto-updates silently
-- **Major versions** — Prompts for approval
-
-**Skip auto-update:**
-```bash
-jfl --no-update
-```
-
-**Manual update:**
-```bash
-jfl update                   # Pull latest skills and CLAUDE.md
-jfl update --dry             # Preview changes first
+└── VOICE_AND_TONE.md      # How the brand speaks
 ```
 
-**What gets updated:**
-- `.claude/skills/` — Latest skill implementations
-- `CLAUDE.md` — Latest AI instructions
-- `scripts/` — Session management scripts
-- `templates/` — Doc templates
-
-**What's preserved:**
-- `knowledge/` — Your strategy docs
-- `content/` — Your generated content
-- `product/` — Your product code
-- `.jfl/config.json` — Project settings
+**Philosophy:** Vision emerges from doing, not declaring. Start building immediately. Claude captures context into docs as you work.
 
 ---
 
 ## Journal Protocol
 
-Every session MUST write journal entries. The Stop hook blocks if no entry exists.
+Every session MUST write journal entries. Hooks enforce this.
 
-**Entry format:**
 ```json
 {
   "v": 1,
-  "ts": "2026-01-28T10:00:00.000Z",
-  "session": "session-goose-20260128-1014-00cec4",
-  "type": "feature|fix|decision|milestone|discovery",
-  "status": "complete|incomplete|blocked",
-  "title": "Short title",
-  "summary": "2-3 sentence summary",
-  "detail": "Full description with context",
-  "files": ["file1.ts", "file2.ts"],
-  "incomplete": ["what's not done"],
-  "next": "what should happen next"
+  "ts": "2026-02-27T10:00:00.000Z",
+  "session": "session-goose-20260227-1014-abc123",
+  "type": "feature",
+  "status": "complete",
+  "title": "Add service agent onboarding",
+  "summary": "Built jfl onboard command that registers service repos in GTM",
+  "detail": "Creates agent definition, skill wrapper, services.json entry...",
+  "files": ["src/commands/onboard.ts"],
+  "incomplete": ["peer sync not wired"],
+  "next": "Wire phone-home on session end"
 }
 ```
 
-**Write entries when:**
-- Feature completed
-- Decision made
-- Bug fixed
-- Milestone reached
-- Session ending
+**Write entries when:** Feature completed, decision made, bug fixed, milestone reached, session ending.
 
-Journal entries become searchable via Context Hub and Synopsis.
+Entries become searchable via `jfl memory search` and MCP `memory_search` tool.
 
 ---
 
-## File Headers (Required for Code)
-
-Every `.ts`, `.tsx`, `.js`, `.jsx` file MUST have a header with `@purpose`:
+## How It Works
 
-```typescript
-/**
- * Component/Module Name
- *
- * Brief description of what this does.
- *
- * @purpose One-line description of file's purpose
- * @spec Optional: link to spec (e.g., PLATFORM_SPEC.md#sessions)
- * @decision Optional: decision slug (e.g., journal/2026-01.md#per-session)
- */
+```
+Session Start                    During Session                   Session End
+─────────────                    ──────────────                   ───────────
+SessionStart hook fires          You work normally                Stop hook fires
+├─ Sync repos                    ├─ Code, content, strategy       ├─ Warn if no journal
+├─ Create session branch         ├─ Journal entries auto-tracked  ├─ Auto-commit changes
+├─ Recover crashed sessions      ├─ Auto-commit every 2 min       ├─ Merge to main
+├─ Health-check Context Hub      ├─ Events flow to MAP bus        └─ Cleanup branch
+└─ Start auto-commit             └─ Memory indexes continuously
+
+                    Context Hub (always running)
+                    ├─ Serves MCP tools to Claude Code
+                    ├─ Aggregates journal + knowledge + code
+                    ├─ Bridges service events from file-drop
+                    └─ Watches journal/ for live entries
 ```
 
-Enables:
-- Synopsis to extract context from files
-- Codebase understanding without reading full files
-- Decision traceability
+**Everything is files.** No proprietary database. No lock-in. Context is git-native — version controlled, portable, model-agnostic.
 
 ---
 
-## Contributing to JFL
-
-```bash
-# Clone via GTM structure
-jfl init my-jfl-gtm
-# During setup, add: https://github.com/402goose/just-fucking-launch.git
-
-# Run dev setup
-cd my-jfl-gtm/product
-./scripts/dev-setup.sh
-
-# Work in the CLI submodule
-cd cli
-npm install
-npm run build
-
-# Link globally for testing
-npm link
-```
+## Auto-Update
 
----
+JFL checks for npm updates on session start (24-hour cache):
 
-## Environment Variables
+- **Minor/patch:** Auto-updates silently
+- **Major:** Prompts for approval
 
 ```bash
-CRM_SHEET_ID=your-sheet-id   # Google Sheets CRM integration
+jfl update                    # Pull latest skills and scripts
+jfl update --dry              # Preview changes first
+jfl --no-update               # Skip auto-update check
 ```
 
----
-
-## Files You'll Work With
-
-```
-.jfl/
-├── config.json              # Project configuration
-├── journal/                 # Session journals (JSONL)
-├── context-hub.pid          # Context Hub daemon PID
-└── logs/                    # Session logs
-
-knowledge/                    # Strategy docs (you fill these)
-content/                      # Generated content
-suggestions/{name}.md         # Per-person working space
-previews/                     # Generated assets
-```
+**What gets updated:** `.claude/skills/`, `scripts/`, `templates/`, `context-hub`
+**What's preserved:** `knowledge/`, `content/`, `suggestions/`, `CLAUDE.md`, `.mcp.json`, `.jfl/config.json`
 
 ---
 
-## Help & Support
+## Authentication
 
 ```bash
-jfl help                      # Show all commands
-jfl --version                 # Show version
+jfl login                     # Platform Account (recommended)
+jfl login --x402              # x402 Day Pass ($5/day, crypto)
+jfl login --solo              # Solo plan ($49/mo)
+jfl login --team              # Team plan ($199/mo)
+jfl login --free              # Stay on trial
+jfl logout                    # Logout
+jfl status                    # Check auth status
+jfl wallet                    # Wallet and day pass status
 ```
 
-**Issues & Feedback:**
-- GitHub: https://github.com/402goose/jfl-cli/issues
-- X: [@taggaoyl](https://x.com/taggaoyl)
-
 ---
 
 ## What's New
 
+**0.2.4**
+- Feat: `jfl telemetry digest` — per-model cost tables, command stats, health analysis, improvement suggestions
+- Feat: `jfl improve` — self-improvement loop with GitHub issue creation (`--auto`)
+- Feat: Model cost tracking on every Stratus API call (token counts, estimated USD, confidence, timing)
+- Feat: Peter Parker agent cost tracking (per-role, per-model cost events)
+- Feat: Model pricing table (claude-opus-4-6, claude-sonnet-4-6, claude-sonnet-4-5, claude-haiku-3-5, gpt-4o)
+
+**0.2.3**
+- Fix: Context Hub race condition — SessionStart hook checks health before ensure
+- Fix: `jfl update` no longer clobbers project-specific CLAUDE.md and .mcp.json
+- Fix: `restartCoreServices` checks health before stop+restart cycle
+- Feat: Context Hub dashboard with live event stream
+- Feat: Journal bridge — journal entries appear in MAP event bus in real-time
+- Feat: Auth supports query param tokens for SSE/EventSource connections
+
+**0.2.2**
+- Feat: Context Hub always-on — MCP auto-recovery, ensure-all, doctor, launchd daemon
+- Fix: Context Hub survives SIGTERM during daemon startup (5s grace period)
+- Feat: MAP event bus with ring buffer, SSE/WS, pattern matching, file-drop bridging
+- Feat: Per-project Context Hub ports (no more collisions)
+
+**0.2.1**
+- Feat: Service agent system — onboard, create, validate, phone-home
+- Feat: Peter Parker model-routed orchestrator (cost/balanced/quality profiles)
+- Feat: Peer agent sync across services
+- Fix: `jfl init` no longer creates nested directories
+
 **0.2.0**
-- OpenClaw protocol — runtime-agnostic agent integration (`jfl openclaw`)
-- Clawdbot plugin — single install, dormant until /jfl, full lifecycle hooks
-- `jfl clawdbot setup` — one command to install plugin
-- Agent tools (jfl_context, jfl_journal) for proactive AI behavior
-- GTM detection via config.json type field (no more false positives on service repos)
+- OpenClaw protocol — runtime-agnostic agent integration
+- Clawdbot plugin — Telegram-based agent with context injection
+- Memory system — TF-IDF + embeddings, hybrid search, auto-indexing
 
 **0.1.0**
-- Auto-update on session start (checks npm registry, 24h cache)
-- Synopsis command (`jfl synopsis [hours] [author]`)
-- Improved doctor checks with categorized output
-- Fixed auto-merge failure that caused branch pileup
-- Context Hub productization improvements
+- Auto-update on session start
+- Synopsis command
+- Context Hub productization
+
+---
+
+## Environment Variables
+
+```bash
+OPENAI_API_KEY=sk-...         # Optional: enables semantic embeddings for memory search
+CONTEXT_HUB_PORT=4242         # Override per-project port
+CRM_SHEET_ID=your-sheet-id    # Google Sheets CRM integration
+JFL_PLATFORM_URL=...          # JFL platform URL (default: jfl.run)
+```
 
 ---
 
 ## License
 
-MIT License - see LICENSE file for details.
+MIT License - see LICENSE file.
 
 ---
 
@@ -604,8 +584,4 @@ MIT License - see LICENSE file for details.
 
 Built by [@tagga](https://x.com/taggaoyl) (Alec Taggart)
 
-Powered by:
-- [Claude](https://claude.ai) (Anthropic)
-- [x402](https://402.com) (crypto micropayments)
-- Commander.js, Inquirer, Chalk, and more
-
+Powered by [Claude](https://claude.ai) (Anthropic), [x402](https://x402.org) (crypto micropayments), Commander.js, sql.js, and more.