jfl 0.1.0 → 0.2.0

package/README.md

@@ -1,17 +1,74 @@
 # JFL - Just Fucking Launch
 
-Your team's context layer for shipping products. Any AI. Any task.
+**The context layer for AI-native teams.**
 
-JFL is a CLI toolkit that powers go-to-market campaigns from zero to launch. It creates structured GTM workspaces where product code, strategy, brand, and content all work together.
+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.
+
+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)
+
+---
+
+## What Problem Does This Solve?
+
+AI agents are stateless by default. Each new 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
 
-- **Initialize GTM workspaces** with proper architecture
-- **Manage your launch dashboard** with countdown, phases, and tasks
-- **Authenticate and manage billing** ($5/day per person, crypto-first)
-- **Deploy to platform** for team collaboration
-- **Orchestrate parallel agents** for Pro tier
-- **Track feedback** and iterate
+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.
+
+---
 
 ## Installation
 
@@ -19,166 +76,319 @@ JFL is a CLI toolkit that powers go-to-market campaigns from zero to launch. It
 npm install -g jfl
 ```
 
-JFL automatically installs all required dependencies, including:
-- **httpcat-cli** - For gasless USDC transfers via x402 (bundled, no separate install needed)
-- **@x402/evm** - x402 payment protocol for Day Pass payments
+**Requirements:** Node ≥18
+
+JFL automatically installs dependencies including Context Hub MCP and x402 payment tools.
 
-## Quick Start
+---
+
+## Quick Start (TL;DR)
 
 ```bash
-# Create a new GTM workspace
-jfl init my-project-gtm
+# Initialize a GTM workspace
+jfl init my-product-gtm
 
 # Check status
-cd my-project-gtm
+cd my-product-gtm
 jfl status
 
-# View launch dashboard
+# View campaign dashboard
 jfl hud
 
-# Or just type. It will walk you through it
+# See what happened recently
+jfl synopsis 24
+
+# Start interactive session (auto-updates on first run)
 jfl
 ```
 
-## Architecture
+---
 
-JFL creates GTM workspaces that are **separate from your product code**:
+## 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 |
+
+---
+
+## How It Works
+
+**The system lives in git. Everything is files.**
+
+No proprietary database. No lock-in. Your company's knowledge graph is version-controlled and portable.
 
 ```
 my-project-gtm/              ← GTM workspace (strategy, content, brand)
+├── .jfl/
+│   ├── config.json          ← Project settings
+│   ├── journal/             ← Session journals (JSONL)
+│   └── context-hub.pid      ← Context Hub daemon
 ├── product/                 ← SUBMODULE → your-product-repo
-├── knowledge/               ← Strategy, vision, narrative
-├── content/                 ← Marketing content
-├── suggestions/             ← Contributor work
-├── skills/                  ← JFL skills (updated via jfl update)
+├── 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 lives here)
+your-product-repo/           ← SEPARATE REPO (all code)
 ├── src/
 ├── cli/
 └── ...
 ```
 
-**Why?**
+**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:**
 - Clean separation of concerns
-- Product can be worked on independently
-- GTM context doesn't pollute product repo
-- Multiple GTMs can reference same product
-- `jfl update` updates GTM toolkit without touching product
+- 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
 
-## Commands
+---
 
-### Core Commands
+## Clawdbot Integration
+
+JFL ships with a Clawdbot plugin for Telegram-based agents.
 
 ```bash
-jfl                          # Start interactive session (with optional --update)
-jfl init [template]          # Initialize new GTM workspace
-jfl status                   # Show project status
-jfl hud                      # Show campaign dashboard
-jfl hud --compact            # One-line status
-jfl update                   # Pull latest JFL updates
-jfl update --dry             # Preview updates without applying
+# Install plugin into Clawdbot
+jfl clawdbot setup
+
+# Check installation status
+jfl clawdbot status
 ```
 
-### Platform Commands
+After setup, restart your gateway (`clawdbot gateway`). The plugin is dormant until you activate it:
 
-```bash
-jfl login                    # Authenticate to JFL platform
-jfl login --x402             # Use x402 Day Pass ($5/day, crypto)
-jfl login --solo             # Use Solo plan ($49/mo)
-jfl login --team             # Use Team plan ($199/mo)
-jfl login --free             # Stay on trial
-jfl logout                   # Logout from platform
-jfl wallet                   # Show wallet and day pass status
-jfl deploy                   # Deploy to JFL platform
-jfl deploy --force           # Force deploy even if no changes
-jfl agents [action]          # Manage parallel agents (list, create, start, stop)
-jfl feedback                 # Rate your session
-```
+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
 
-### Skill Shortcuts
+**Telegram Commands:**
 
-These skills run in your Claude Code session:
+| 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 |
+
+**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
+
+**Claude also gets tools** (`jfl_context`, `jfl_journal`) it can use proactively without you asking.
+
+---
+
+## OpenClaw Protocol
+
+OpenClaw is JFL's runtime-agnostic agent protocol. Any AI agent can become a JFL team member:
 
 ```bash
-jfl brand [subcommand]       # Run /brand-architect skill
-jfl content <type> [topic]   # Run /content skill (thread, post, article, one-pager)
+# Register agent with a GTM workspace
+jfl openclaw register -g /path/to/gtm -a my-agent
+
+# Start session (creates branch, auto-commit, Context Hub)
+jfl openclaw session-start -a my-agent --json
+
+# Search project context
+jfl openclaw context -q "pricing decisions" --json
+
+# Write journal entry
+jfl openclaw journal --type decision --title "Chose OAuth" --summary "Better for multi-tenant"
+
+# End session (merge, cleanup)
+jfl openclaw session-end --json
 ```
 
-## Authentication
+All commands support `--json` for programmatic use. See `jfl openclaw --help` for the full command list.
+
+---
 
-JFL supports two authentication methods:
+## Context Hub
+
+Context Hub is a local daemon (port 4242) that provides unified context to any AI:
 
-**GitHub OAuth**
 ```bash
-jfl login
+# Start Context Hub
+jfl context-hub start
+
+# Check status
+jfl context-hub status
+
+# Stop daemon
+jfl context-hub stop
+```
+
+**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
+
+**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
+
+Add to your `.mcp.json`:
+```json
+{
+  "jfl-context": {
+    "command": "jfl-context-hub-mcp"
+  }
+}
 ```
 
-**x402 Crypto Wallet** (with httpcat-cli bundled)
+---
+
+## Synopsis - Work Summaries
+
+Synopsis aggregates journal entries, git commits, and code file headers to answer "what happened?"
+
 ```bash
-jfl login --x402
+# Last 24 hours, all authors
+jfl synopsis 24
+
+# Last 8 hours
+jfl synopsis 8
+
+# What did Alex work on in last 48 hours?
+jfl synopsis 48 alex
+
+# Filter by git author name
+jfl synopsis 24 --author "Andrew"
 ```
 
-This enables:
-- Gasless USDC transfers (no ETH needed for gas)
-- $5/day payments via x402 protocol
-- httpcat-cli automatically installed and configured
+**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
+
+---
+
+## Session Management
+
+Work in isolated git worktrees with automatic commit/merge:
 
-View your auth status:
 ```bash
-jfl wallet
+# Create new session (creates worktree + branch)
+jfl session create
+
+# List active sessions
+jfl session list
+
+# End session (merges to main, removes worktree)
+jfl session end [session-name]
+
+# Auto-commit running in background (every 2 min)
+./scripts/session/auto-commit.sh start
 ```
 
-## Pricing
+**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
 
-**Trial - $0**
-- Full JFL toolkit
-- Foundation + brand setup
-- Use Claude Code or Codex CLI - download Claude Pro or Max at claude.ai 
-- Ends when you add teammates (context is more fun when you shape it together)
+**Stop hook:**
+- Auto-commit uncommitted changes
+- Merge to main (with conflict handling)
+- Cleanup worktree and branch
+- Validate journal entry exists
 
-**Day Pass - $5/day per person**
-- Only pay the days you use it
-- AI included (no API key needed)
-- Chat in Telegram, Slack, Discord
-- Dashboard + Deploy at [TBD]
-- Pay with USDC (gasless via x402)
+---
 
-**Solo - $49/mo**
-- Just you (1 seat)
-- AI included
-- Everything in Day Pass
-- Best if you use it most days
+## Authentication
+
+**GitHub OAuth:**
+```bash
+jfl login
+```
+
+**x402 Crypto Wallet ($5/day micropayments):**
+```bash
+jfl login --x402
+```
 
-**Team - $199/mo**
-- Up to 5 seats (+$25/seat after)
-- AI included for everyone
-- Team dashboard + analytics
-- Parallel agents
-- Priority support
+Enables:
+- Gasless USDC transfers (no ETH needed)
+- $5/day Day Pass payments
+- httpcat-cli bundled and configured
 
-## Project Setup Types
+View auth status:
+```bash
+jfl status
+jfl wallet
+```
 
-When initializing a project, JFL asks about your setup:
+---
 
-**Building a product**
-- You're writing code
-- Product repo linked as submodule at `product/`
-- Code changes go to product repo
+## Pricing
 
-**GTM only**
-- Team handles code
-- You focus on content, brand, outreach
-- No code changes, just marketing
+| 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. |
 
-**Contributor**
-- Working on specific tasks
-- Changes go to `suggestions/{name}.md`
-- Owner reviews and merges
+---
 
-## Skills Available
+## Skills Library
 
-JFL includes powerful skills for Claude Code:
+JFL includes skills for Claude Code:
 
 | Skill | Description |
 |-------|-------------|
@@ -186,16 +396,18 @@ JFL includes powerful skills for Claude Code:
 | `/brand-architect` | Generate brand identity (marks, colors, typography) |
 | `/web-architect` | Implement assets (SVG, favicon, OG images) |
 | `/content` | Create content (threads, posts, articles, one-pagers) |
-| `/x-algorithm` | Optimize tweets for X For You feed using the open-sourced algorithm |
+| `/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 - navigate, screenshot, scrape |
-| `/search` | Semantic search across GTM knowledge base using qmd |
+| `/agent-browser` | Headless browser automation |
+| `/search` | Semantic search across GTM knowledge base |
 | `/spec` | Multi-agent adversarial spec refinement |
 | `/react-best-practices` | React/Next.js performance optimization |
 | `/remotion-best-practices` | Remotion video creation in React |
 
-Run these in Claude Code after initializing your project. Easy to add more skills, it has a sklls factory just ask it or copy your favorite skills repos
+Run in Claude Code after `jfl init`.
+
+---
 
 ## Knowledge Layer
 
@@ -210,52 +422,104 @@ knowledge/
 ├── BRAND_BRIEF.md         # Brand inputs
 ├── BRAND_DECISIONS.md     # Finalized brand choices
 ├── VOICE_AND_TONE.md      # How the brand speaks
-├── TASKS.md               # Master task list
-└── CRM.md                 # Contact database
+└── TASKS.md               # Master task list
 ```
 
-These docs are the source of truth that AI reads to generate content, make decisions, and maintain consistency.
+These docs are the source of truth. AIs read them to generate content, make decisions, and maintain consistency.
+
+---
 
-## Updating JFL
+## Auto-Update
 
-JFL updates independently of your project:
+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
 ```
 
-This updates:
-- `skills/` - Latest skill implementations
-- `CLAUDE.md` - Latest AI instructions
-- Templates for new docs
+**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
+
+---
+
+## Journal Protocol
+
+Every session MUST write journal entries. The Stop hook blocks if no entry exists.
+
+**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"
+}
+```
+
+**Write entries when:**
+- Feature completed
+- Decision made
+- Bug fixed
+- Milestone reached
+- Session ending
 
-Your project content (knowledge/, content/, product/) is never touched.
+Journal entries become searchable via Context Hub and Synopsis.
 
-## Session Management
+---
 
-**Default:** Single session, direct in repo.
+## File Headers (Required for Code)
 
-**Advanced:** For parallel work across multiple sessions, use worktrees:
+Every `.ts`, `.tsx`, `.js`, `.jsx` file MUST have a header with `@purpose`:
 
-```bash
-./scripts/worktree-session.sh create [username]    # Create isolated session
-./scripts/worktree-session.sh list                 # List active sessions
-./scripts/worktree-session.sh end [session-name]   # End session
+```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)
+ */
 ```
 
-Each worktree session has:
-- Isolated git worktree
-- Auto-commit (every 5 min)
-- Auto-merge to main (every 15 min)
-- Own branch for changes
+Enables:
+- Synopsis to extract context from files
+- Codebase understanding without reading full files
+- Decision traceability
 
-## Development
+---
 
-Contributing to JFL itself:
+## Contributing to JFL
 
 ```bash
-# Clone through GTM structure
+# Clone via GTM structure
 jfl init my-jfl-gtm
 # During setup, add: https://github.com/402goose/just-fucking-launch.git
 
@@ -263,8 +527,8 @@ jfl init my-jfl-gtm
 cd my-jfl-gtm/product
 ./scripts/dev-setup.sh
 
-# Work in the submodule
-cd product/cli
+# Work in the CLI submodule
+cd cli
 npm install
 npm run build
 
@@ -272,42 +536,76 @@ npm run build
 npm link
 ```
 
+---
+
 ## Environment Variables
 
 ```bash
 CRM_SHEET_ID=your-sheet-id   # Google Sheets CRM integration
 ```
 
+---
+
 ## Files You'll Work With
 
 ```
-.jfl/config.json              # Project configuration
+.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
 ```
 
-## Help
+---
+
+## Help & Support
 
 ```bash
 jfl help                      # Show all commands
 jfl --version                 # Show version
 ```
 
-For issues or feedback:
-- GitHub: https://github.com/402goose/just-fucking-launch
-- Docs: https://jfl.run
+**Issues & Feedback:**
+- GitHub: https://github.com/402goose/jfl-cli/issues
+- X: [@taggaoyl](https://x.com/taggaoyl)
+
+---
+
+## What's New
+
+**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)
+
+**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
+
+---
 
 ## License
 
 MIT License - see LICENSE file for details.
 
+---
+
 ## Credits
 
 Built by [@tagga](https://x.com/taggaoyl) (Alec Taggart)
 
 Powered by:
-- Claude (Anthropic)
-- x402 (crypto micropayments)
+- [Claude](https://claude.ai) (Anthropic)
+- [x402](https://402.com) (crypto micropayments)
 - Commander.js, Inquirer, Chalk, and more
+