{"owner":"nikivdev","repo":"flow","hasSkills":true,"totalSkillsCount":44,"totalTokensCount":36598,"categories":["root-instruction","anthropic-skill","command-prompt","plugin-manifest","cursor-rule"],"hasMcp":false,"mcpConfig":null,"found":[".ai/agents.md",".ai/skills/env/skill.md",".ai/skills/pr-markdown-body-file/skill.md",".ai/skills/quality-bun-feature-delivery/skill.md","agents.md","docs/commands/ai.md","docs/commands/clone.md","docs/commands/commit.md","docs/commands/commits.md","docs/commands/config.md","docs/commands/db.md","docs/commands/deploy.md","docs/commands/docs.md","docs/commands/domains.md","docs/commands/down.md","docs/commands/env.md","docs/commands/ext.md","docs/commands/failure.md","docs/commands/fast.md","docs/commands/global.md","docs/commands/install.md","docs/commands/invariants.md","docs/commands/jj.md","docs/commands/migrate.md","docs/commands/new.md","docs/commands/pr.md","docs/commands/publish.md","docs/commands/readme.md","docs/commands/recipe.md","docs/commands/release.md","docs/commands/repos.md","docs/commands/reviews-todo.md","docs/commands/seq-rpc.md","docs/commands/services.md","docs/commands/setup.md","docs/commands/skills.md","docs/commands/sync.md","docs/commands/tasks.md","docs/commands/up.md","docs/commands/upstream.md","docs/commands/url.md","docs/commands/web.md","tools/domainsd-cpp/readme.md",".cursorrules (gitflow.mdc)"],"skills":{".ai/agents.md":"# Autonomous Agent Instructions\n\nProject: flow\n\nThis project is configured for autonomous AI agent workflows with human-in-the-loop approval.\n\n## Response Format\n\n**Every response MUST end with exactly one of these signals on the final line:**\n\n### Success signals\n\n```\ndone.\n```\nUse when task completed successfully with high certainty. No further action needed.\n\n```\ndone: <message>\n```\nUse when task completed with context to share. Example: `done: Added login command with --token flag`\n\n### Needs human input\n\n```\nneedsUpdate: <message>\n```\nUse when you need human decision or action. Example: `needsUpdate: Should I use OAuth or API key auth?`\n\n### Error signals\n\n```\nerror: <message>\n```\nUse when task failed or cannot proceed. Example: `error: Build failed - missing dependency xyz`\n\n## Rules\n\n1. **Always end with a signal** - The last line must be one of the above\n2. **One signal only** - Never combine signals\n3. **Be specific** - Include actionable context in messages\n4. **No quotes** - Write signals exactly as shown, no wrapping quotes\n\n## Examples\n\n### Successful implementation\n```\nAdded the new CLI command with all requested flags.\n\ndone.\n```\n\n### Completed with context\n```\nRefactored the auth module to use the new token format.\n\ndone: Auth now supports both JWT and API key methods\n```\n\n### Need human decision\n```\nFound two approaches for caching:\n1. Redis - better for distributed systems\n2. In-memory - simpler, faster for single instance\n\nneedsUpdate: Which caching approach should I use?\n```\n\n### Error occurred\n```\nAttempted to run tests but encountered issues.\n\nerror: Test suite requires DATABASE_URL environment variable\n```\n",".ai/skills/env/skill.md":"---\nname: env\ndescription: Manage environment variables and secrets with flow (always use Flow env store)\nsource: flow-default\n---\n\n# Environment Variables & Secrets\n\nFlow provides a secure way to manage environment variables across projects.\n\n## Rules (Must)\n\n- Always use Flow env store for secrets/tokens in Flow projects.\n- Do not rely on shell env vars or `.env` files for secrets unless they are injected via `f env`.\n- For tasks/scripts that need secrets, fetch them with `f env get` or run via `f env run`.\n\n## Setup\n\n### 1. Define variables in flow.toml\n\nAdd a `[storage]` section to your project's `flow.toml`:\n\n```toml\n[storage]\nprovider = \"myflow.sh\"\n\n[[storage.envs]]\nname = \"local\"\ndescription = \"Local development\"\nvariables = [\n  { key = \"DATABASE_URL\" },\n  { key = \"API_KEY\" },\n  { key = \"SECRET_TOKEN\", default = \"\" },\n]\n```\n\n### 2. Set environment variables\n\nUse `f env set` to store values:\n\n```bash\n# Set individual env vars\nf env set API_KEY=abc123\nf env set DATABASE_URL=\"postgres://...\"\n\n# Values are stored in ~/.config/flow/env-local/personal/production.env\n```\n\n### 3. Pull env vars to local .env\n\n```bash\n# Pull all env vars for the current environment\nf env pull\n\n# Show current env vars\nf env list\n\n# Get specific var\nf env get API_KEY\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `f env set KEY=value` | Store an env var |\n| `f env pull` | Pull env vars to local .env file |\n| `f env push` | Push local .env to cloud |\n| `f env list` | List env vars for this project |\n| `f env get KEY` | Get specific env var(s) |\n| `f env keys` | Show configured env keys from flow.toml |\n| `f env setup` | Interactive env setup |\n| `f env guide` | Guided prompt to set required vars |\n| `f env run <cmd>` | Run command with env vars injected |\n\n## Environment Selection\n\nFlow supports multiple environments:\n\n```toml\n[[storage.envs]]\nname = \"local\"\nvariables = [{ key = \"DATABASE_URL\" }]\n\n[[storage.envs]]\nname = \"staging\"\nvariables = [{ key = \"DATABASE_URL\" }]\n\n[[storage.envs]]\nname = \"production\"\nvariables = [{ key = \"DATABASE_URL\" }]\n```\n\n## Example: Spotify CLI\n\n```toml\n[storage]\nprovider = \"myflow.sh\"\n\n[[storage.envs]]\nname = \"local\"\ndescription = \"Spotify API credentials\"\nvariables = [\n  { key = \"SPOTIFY_CLIENT_ID\" },\n  { key = \"SPOTIFY_CLIENT_SECRET\" },\n  { key = \"SPOTIFY_ACCESS_TOKEN\" },\n  { key = \"SPOTIFY_REFRESH_TOKEN\", default = \"\" },\n]\n```\n\nThen:\n```bash\n# Set your credentials (example values)\nf env set SPOTIFY_CLIENT_ID=example_client_id\nf env set SPOTIFY_CLIENT_SECRET=example_client_secret\n\n# Run CLI with env vars injected\nf env run bun run src/main.ts now\n\n# Or pull to .env first\nf env pull\nsource .env\nbun run src/main.ts now\n```\n\n## Task pattern (required for secrets)\n\nWhen writing Flow tasks, prefer:\n\n```bash\nMY_TOKEN=\"$(FLOW_ENV_BACKEND=local f env get --personal MY_TOKEN -f value 2>/dev/null || true)\"\nif [ -z \"${MY_TOKEN:-}\" ]; then\n  echo \"MY_TOKEN missing. Save it with envnew MY_TOKEN=...\"\n  exit 1\nfi\nexport MY_TOKEN\n```\n\n## One-time passwords (1Password Connect)\n\nUse Flow's OTP command to fetch TOTP codes from 1Password Connect:\n\n```bash\nf otp get <vault> <item> [--field <label>]\n```\n\nRequires:\n- `OP_CONNECT_HOST`\n- `OP_CONNECT_TOKEN` (env or Flow personal env store)\n\n## Storage Locations\n\n- **Personal env vars:** `~/.config/flow/env-local/personal/production.env`\n- **Project env vars:** Stored via myflow.sh cloud backend\n- **Local .env:** Created in project root via `f env pull`\n\n## Authentication\n\nFlow uses a token stored in `~/.config/flow/auth.toml` to authenticate. If you haven't authenticated:\n\n```bash\nf auth login\n```\n\n## Security Notes\n\n- Personal env vars stored locally in `~/.config/flow/`\n- Project env vars can be synced to cloud via `f env push`\n- Never commit `.env` files to git (add to `.gitignore`)\n- Use `f env run` to inject vars without creating .env files\n",".ai/skills/pr-markdown-body-file/skill.md":"---\nname: pr-markdown-body-file\ndescription: Always edit/create GitHub PR bodies from a markdown file; never inline escaped newlines.\nversion: 1\nsource: flow-default\n---\n\n# PR Markdown Body Discipline\n\nUse this skill when creating or editing pull requests.\n\n## Rules (Must)\n\n- Never pass multi-line PR text via a quoted CLI string with `\\n`.\n- Always use a markdown file with `--body-file`.\n- Prefer `f pr open edit` when available for local file-driven PR editing.\n\n## Why\n\nInline escaped newlines are fragile and can produce literal `\\n` text in GitHub PR descriptions.\n`--body-file` is deterministic and reviewable.\n\n## Safe patterns\n\n### Create PR (GitHub CLI)\n\n```bash\ncat > /tmp/pr-body.md <<'EOF'\n## Summary\n- ...\n\n## Scope\n- ...\nEOF\n\ngh pr create --title \"...\" --body-file /tmp/pr-body.md\n```\n\n### Edit existing PR\n\n```bash\ncat > /tmp/pr-body.md <<'EOF'\n## Summary\n- ...\nEOF\n\ngh pr edit <number> --body-file /tmp/pr-body.md\n```\n\n### Flow-native edit loop\n\n```bash\nf pr open edit\n```\n\nThis opens a local markdown file and syncs title/body on save.\n\n## Verification\n\n- Run:\n\n```bash\ngh pr view <number> --json body -q .body\n```\n\n- Confirm markdown renders correctly and contains no literal `\\n`.\n",".ai/skills/quality-bun-feature-delivery/skill.md":"---\nname: quality-bun-feature-delivery\ndescription: Enforce tight Codex/Claude delivery loop with Bun-first testing, skill sync/reload, and commit quality gates.\nversion: 2\nsource: flow-default\n---\n\n# Quality Bun Feature Delivery\n\nUse this workflow for every feature/change.\n\n## Rules (Must)\n\n- In Bun repos, run tests with `bun bd test ...` (never `bun test` for final validation).\n- Run only relevant tests first (single file/filter) for fast feedback.\n- Keep `.ai/features/*.md` and tests current for touched features.\n- Do not finish work without a passing local verification command.\n\n## Tight Loop\n\n1. Update code + tests.\n2. Run focused tests with Bun debug build:\n\n```bash\nbun bd test <target-test-file> -t \"<optional filter>\"\n```\n\n3. Sync task skills to keep agent context fresh:\n\n```bash\nf skills sync\n```\n\n4. Force Codex to reload skills for this cwd:\n\n```bash\nf skills reload\n```\n\n5. Commit through Flow quality gates:\n\n```bash\nf commit\n```\n\n## Bun Regression Check (for new tests)\n\nWhen adding/changing tests in Bun itself, ensure the test fails on system Bun and passes on debug Bun:\n\n```bash\nUSE_SYSTEM_BUN=1 bun test <target-test-file>\nbun bd test <target-test-file>\n```\n\n## Recommended flow.toml\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n","agents.md":"# Assistant Rules (flow)\n\nOnly load skills when the request clearly needs them.\n\n## Skills (on-demand)\n- flow-native: Use for Flow CLI native workflows (env setup, secrets, deploys, logs, deps), for repos with `flow.toml`, or Cloudflare Workers. Avoid direct pnpm/wrangler unless asked.\n- flow-interactive: Use when commands are interactive or could block on stdin (e.g., `f setup`).\n- flow-dev-traces: Use when debugging Flow proxy behavior, tracing requests, or when the user asks about proxyx, trace-summary.json, or flow trace commands.\n- flow-usage: Use when running or troubleshooting Flow command behavior.\n- internal-ai-inference: Use only when asked to run inference or integrate with internal AI tooling.\n\nDefault: Avoid loading skills for routine edits, reviews, or simple questions.\n\n## Deploy / Restart Policy\n\n- When changes affect the installed Flow CLI or built-in Codex daemon path,\n  prefer an explicit deploy + daemon reload instead of leaving runtime state\n  stale.\n- Use `deploy-with-codexd-reload` after edits in areas like `src/ai.rs`,\n  `src/codexd.rs`, `src/daemon.rs`, `src/supervisor.rs`, or `src/config.rs`\n  when those changes affect Codex runtime, daemon behavior, or Flow-managed\n  session recovery.\n- Use `deploy-with-hub-reload` for hub-facing changes that need `lin` / docs\n  processes refreshed.\n- For `codexd`, prefer explicit `stop` + `start` in automation over a single\n  restart command so the stop/start boundary is visible in logs.\n","docs/commands/ai.md":"# f ai\n\nManage Claude Code, Codex, and Cursor sessions for the current project.\n\nFlow reads local session stores, filters by current project path, and gives you one interface for list/search/resume/copy/save.\nWhen you need to reopen a repo's session from another working directory, use `--path <project-root>` on `resume` or provider-specific `continue`.\nCursor transcripts are supported for reading only.\n\nArchitecture note:\n\n- for the underlying transport split between wrapped Codex CLI, `jd`, and `codex app-server`, see `docs/codex-interface.md`\n\n## Quick Start\n\n```bash\n# Fuzzy-pick a recent session (Claude + Codex + Cursor)\nf ai\n\n# Provider-specific list/read\nf ai claude list\nf ai codex list\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\nf ai cursor list\nf codex resolve \"latest\"\nf codex resolve \"https://linear.app/.../project/.../overview\" --json\nf codex open \"continue the deploy work\"\nf codex agent list\nf codex agent show commit\nf ai claude resume <session-id-or-name>\nf ai codex resume <session-id-or-name>\nf ai codex resume --path ~/work/example-project\nf ai codex continue --path ~/work/example-project\nf ai codex find --path ~/repos/openai/codex \"where does codex store\"\nf ai codex find --all-history --path ~/repos/openai/codex \"older migration plan\"\nf ai codex find --recent-days 30 --path ~/repos/openai/codex \"thread/read\"\nf ai codex find --json --limit 5 --path ~/repos/openai/codex \"thread/read\"\nf codex connect --path ~/repos/openai/codex --exact-cwd --json \"app-server\"\nf codex connect --all-history --path ~/repos/openai/codex \"old designer cutover\"\nf ai cursor context - /path/to/repo 3\nf cursor copy\n\n# Save a memorable alias for a session\nf ai save reclaim-fix --id a38cf8bf-f4e2-4308-8b27-0254f89c4385\n```\n\n## Session Sources\n\n- Claude: `~/.claude/projects/<project-path>/*.jsonl`\n- Codex: `~/.codex/sessions/**/*.jsonl` (Flow matches by `session_meta.cwd`)\n- Cursor: `~/.cursor/projects/<project-key>/agent-transcripts/<session-id>/<session-id>.jsonl`\n- Saved aliases: `.ai/sessions/claude/index.json` in your repo\n\n## Resume Behavior (Important)\n\n### TTY requirement\n\nResume is interactive by design.\n\n- `f ai claude resume ...` requires a terminal TTY.\n- `f ai codex resume ...` requires a terminal TTY.\n- In non-interactive shells, Flow exits with a clear error and non-zero status.\n- Cursor does not currently expose a Flow resume/continue path; use `list`, `copy`, or `context`.\n\n### Claude exact-ID behavior\n\nIf you pass an explicit session (`name`, `id`, or `id-prefix`), Flow is strict:\n\n- it attempts `claude --resume <id>`\n- if Claude cannot open that exact session, Flow fails\n- Flow does **not** auto-fallback to `--continue` for explicit sessions (prevents opening the wrong conversation)\n\n### Claude no-arg behavior\n\nFor `f ai claude resume` with no argument:\n\n- Flow picks most recent Claude session for this project\n- if that resume fails, Flow may fallback to `claude --continue` in the same cwd (TTY only)\n\n### Codex behavior\n\nFor Codex, Flow runs:\n\n```bash\ncodex resume <id> --dangerously-bypass-approvals-and-sandbox\n```\n\nNo fallback is applied on resume failure; Flow returns non-zero.\n\n### Codex open and resolve\n\nUse `open` when you want one Codex entrypoint that stays conservative about context:\n\n```bash\nf codex open\nf codex open \"continue the deploy work\"\nf codex open \"resume latest\"\nf codex open --path ~/work/example-project \"what was I doing here\"\nf codex resolve \"https://linear.app/example-workspace/project/example-project-v1-1234567890ab/overview\" --json\nf codex doctor --path ~/work/example-project\n```\n\nBehavior:\n\n- no query: start a fresh Codex session in the target repo\n- explicit session lookup queries like `latest`, `resume session`, ordinals, or session IDs: resume the matching Codex session\n- explicit recovery prompts like `what was I doing` or `continue the ... work`: build a compact recovery handoff and start a new session\n- matching reference resolvers: inject only compact resolver output, then append the user request\n- otherwise: start a new session with the raw query and no extra wrapper text\n\nThis keeps prompt cost flat unless Flow has a strong reason to recover or unroll context.\nUse `f codex doctor` to confirm whether wrapper transport, runtime skills, and context budgets are actually active for the current repo.\n\n### Codex connect and find\n\n`f codex connect` and `f ai codex find` now use a Flow-managed local session-search index before\nfalling back to direct SQLite/transcript scans. The index is repo-scoped at query time, rebuilt\nfrom the Codex state DB when needed, and keeps transcript snippets for better recall on natural\nlanguage queries.\n\nBy default, search now prefers sessions from roughly the last 7 days for faster and more accurate\nranking on active work, then automatically widens back to the full session history when the recent\nwindow looks weak or sparse.\n\nUseful commands:\n\n```bash\nf codex connect --path ~/repos/openai/codex --exact-cwd \"app-server\"\nf codex connect --path ~/repos/openai/codex --exact-cwd --json \"thread/read\"\nf codex connect --all-history --path ~/repos/openai/codex \"old migration plan\"\nf ai codex find --path ~/repos/openai/codex \"where does codex store\"\nf ai codex find --recent-days 30 --path ~/repos/openai/codex \"thread/read\"\nf ai codex find --json --limit 5 --path ~/repos/openai/codex \"where does codex store\"\n```\n\nBehavior:\n\n- `connect` stays the interactive handoff path and returns the exact session match\n- `connect --json` prints the selected session instead of attaching\n- `find` still resumes the top hit\n- `find --json` is read-only and prints ranked candidates for inspection/eval work\n- by default both commands prefer the last 7 days first, then widen if the recent window is weak\n- use `--recent-days <N>` to widen the preferred recent window without fully disabling recency bias\n- use `--all-history` to search the full history immediately\n- if confidence is weak or the index misses, Flow still falls back to the older metadata and transcript paths instead of silently opening an arbitrary session\n\n### Codex sessions after a crash or restart\n\nIf your Mac restarts and you lose the live Codex terminals, use:\n\n```bash\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\n```\n\nBehavior:\n\n- lists recent Codex sessions for the current path\n- sorts by the last message timestamp descending\n- shows the stable session id plus a preview of the latest message\n- the numeric index matches `continue`, so you can reopen quickly\n\nIf you want to read or hand off a session instead of reopening it, use the native session bridge in Codex chat:\n\n```text\nsee codex in ~/repos/mark3labs/kit\nsee 019cd046 codex session\nread 019cd046 codex session deeply\n```\n\nExamples:\n\n```bash\nf ai codex continue 1 --path ~/repos/mark3labs/kit\nf ai codex continue 019cd046 --path ~/repos/mark3labs/kit\nf ai codex sessions --path ~/repos/mark3labs/kit --json\n```\n\n### Optional `flow.toml` resolver config\n\nYou can teach `f codex open` and `f codex resolve` to unroll repo-specific references:\n\n```toml\n[codex]\nauto_resolve_references = true\nprompt_context_budget_chars = 900\nmax_resolved_references = 1\nsync_workflow_command = \"./scripts/sync-safe\"\n\n[[codex.reference_resolver]]\nname = \"linear\"\nmatch = [\"https://linear.app/*/issue/*\", \"https://linear.app/*/project/*\"]\ncommand = \"my-linear-tool inspect {{ref}} --json\"\ninject_as = \"linear\"\n```\n\nNotes:\n\n- configure this in repo `flow.toml` or global `~/.config/flow/flow.toml`\n- `{{ref}}`, `{{query}}`, and `{{cwd}}` are available in resolver commands\n- built-in Linear URL parsing works even without a custom resolver\n- resolver output is compacted before prompt injection\n- `prompt_context_budget_chars` hard-caps injected context before your request is appended\n- `max_resolved_references` prevents broad unrolling from bloating one turn\n- `sync_workflow_command` lets plain `sync branch` route into a repo-specific safe sync command instead of improvised Git/JJ steps\n\n### Optional runtime skill transport\n\nFlow can also materialize tiny per-launch runtime skills for current upstream Codex without forking Codex.\n\nEnable it globally with:\n\n```bash\nf codex enable-global --full\nf codex doctor --path ~/docs --assert-runtime --assert-schedule\n```\n\nOr configure it manually with:\n\n```toml\n[codex]\nruntime_skills = true\n\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n```\n\nFor the `~/code/flow` repo specifically, the intended in-repo shape is:\n\n```toml\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n\n[codex]\nruntime_skills = true\nauto_resolve_references = true\nprompt_context_budget_chars = 1200\nmax_resolved_references = 2\n\n[[codex.skill_source]]\nname = \"run-control-plane\"\npath = \"~/run\"\nenabled = true\n```\n\nThat keeps a fresh checkout Codex-first even before machine-local setup is remembered.\n\nCurrent first-slice behavior:\n\n- `f codex open \"write plan\"` can attach a tiny plan-writing runtime skill\n- the runtime skill is exposed only for the launched Codex process\n- Flow keeps the generated runtime state under `~/.config/flow/codex/runtime`\n\nInspect or clear runtime state:\n\n```bash\nf codex runtime show\nf codex runtime clear\nf codex log status\nf codex log sync --limit 400\nf codex memory status\nf codex memory query --path ~/code/flow \"codex control plane runtime skills\"\nf codex memory recent --path ~/docs\nf codex doctor\n```\n\nAssertive health checks:\n\n```bash\nf codex doctor --path ~/docs --assert-runtime\nf codex doctor --path ~/docs --assert-schedule\nf codex doctor --path ~/docs --assert-learning\nf codex doctor --path ~/docs --assert-autonomous\n```\n\n`--assert-learning` is intentionally strict: it fails until Flow has real\nlogged events, grounded outcome samples, and a non-empty scorecard for that\ntarget.\n\nBuilt-in plan writer:\n\n```bash\ncat <<'EOF' | f codex runtime write-plan --title \"Example Plan\"\n# Example Plan\n\n- item\nEOF\n```\n\nBy default this writes to today's `~/docs/plan/<day-of-month>/` bucket, for\nexample `~/docs/plan/23/` on the 23rd day of the month.\n\nCompleted `j` sessions are also mirrored automatically into `~/log/.ai/docs/session-changes/`\nthrough `jd`, so durable home-log notes exist even when a repo-local `.ai/docs/`\npromotion never happens.\n\n### Run-owned agent bridge\n\nFlow can execute run-owned Codex agents directly without copying their specs or\nprompts into `~/code/flow`.\n\nUseful commands:\n\n```bash\nf codex agent list\nf codex agent list --json\nf codex agent show commit\nf codex agent run planner --path ~/code/flow \"make a 3 phase rollout plan\"\nf codex agent run commit --path ~/repos/openai/codex \"review the current diff and draft a safe commit\"\nf codex agent run planner --json --path ~/code/flow \"reply with exactly: ok\"\n```\n\nBehavior:\n\n- Flow bridges into `~/run/scripts/agent-router.sh`\n- the run-owned agent still executes through its own spec/runtime path in `~/run`\n- `--path` controls the repo/worktree cwd used for the agent run\n- `run` returns the agent's final output plus any durable artifact/trace paths\n- `f codex doctor --path <repo>` reports whether the run-agent bridge is ready\n\nRepo-local readiness check:\n\n```bash\nf codex doctor --path ~/code/flow --assert-runtime --assert-schedule\nf codex skill-source list --path ~/code/flow\nf codex agent list\n```\n\n### Skill eval and background refresh\n\nFlow can learn which runtime skills are actually worth injecting from local\nCodex usage history without replaying Codex in the hot path.\n\nUseful commands:\n\n```bash\nf codex eval --path ~/work/example-project\nf codex memory sync --limit 400\nf codex memory recent --path ~/work/example-project --limit 12\nf codex skill-eval show --path ~/work/example-project\nf codex skill-eval run --path ~/work/example-project\nf codex skill-eval cron --limit 400 --max-targets 12 --within-hours 168\nf codex telemetry status\nf codex telemetry flush --limit 200\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\nf codex project-ai show --path ~/work/example-project --json\nf codex project-ai recent --limit 12 --json\nf codex skill-source list --path ~/work/example-project\nf codex skill-source sync --path ~/work/example-project --skill find-skills\nf codex agent list\nf codex agent run planner --path ~/work/example-project \"summarize the next rollout slice\"\n```\n\nThe Codex memory mirror:\n\n- stores durable indexed memory under the Jazz2 root (`~/.jazz2/...` or `~/repos/garden-co/jazz2/.jazz2/...`)\n- mirrors Flow’s route/outcome history into SQLite with WAL enabled\n- extracts compact repo/code facts from repo capsules (summary, commands, important paths, docs hints)\n- adds bounded live code-path retrieval for explicit repo references, so prompts like `see ~/code/flow ...` can inject likely files such as `src/ai.rs` or `docs/...` without dumping raw source\n- indexes durable repo entrypoints and extracted symbols under the same Jazz2-rooted memory store, then supplements them with live symbol extraction from the top-ranked code files during `memory query` / `codex resolve`\n- adds tiny symbol snippets for the top code hits, so coding prompts can carry actual struct/function shape without inlining whole files\n- biases retrieval by intent: implementation/file-edit prompts prefer symbols, snippets, and `src/...` paths; summary/docs prompts prefer doc headings and docs paths\n- stays best-effort so failed memory writes do not block normal Codex coding turns\n\nThe project-ai manifest:\n\n- gives `jd` a bounded metadata view of repo-local `.ai/` scaffolding\n- records counts and latest paths for skills, docs, reviews, tasks, and todos\n- keeps default context fill minimal by exposing only compact hints, not raw content\n- tracks query counts and recent repo usage so you can see whether the feature is actually being used\n- is refreshed again by `f codex skill-eval cron`, so the mirror heals even if a hot-path write is skipped\n- is queried automatically for explicit repo references during `f codex open` / `f codex resolve`\n\nWhat `cron` does:\n\n- scans only recent logged Flow Codex events\n- syncs recent skill-eval logs into the Jazz2-backed memory mirror\n- skips missing/moved repo paths\n- rebuilds scorecards for a bounded number of recent repos\n- never launches Codex or replays network work in the background\n\nFor your use case, this keeps learning cheap and safe enough to run regularly.\n\n### Trace inspection for Flow-managed Codex sessions\n\nFlow now assigns a trace envelope to all Flow-managed Codex launches, not just\nspecial workflows like `check <github-pr-url>`.\n\nThat means sessions started or resumed through:\n\n```bash\nj ...\nk <session-id>\nf codex open ...\nf codex resume ...\nf codex continue ...\n```\n\ncarry `FLOW_TRACE_*` env vars and emit at least one compact Flow telemetry\nevent, so the session becomes remotely inspectable.\n\nUseful commands:\n\n```bash\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\n```\n\nBehavior:\n\n- `trace status` checks whether Maple MCP reads are configured and reachable\n- `trace current-session` reads the active `FLOW_TRACE_ID` from the current\n  Flow-managed Codex session, flushes recent Flow telemetry once, then attempts\n  a remote trace read\n- if Maple reads are partially configured but tenant access is still blocked,\n  Flow returns the current trace metadata plus `readError` instead of failing\n  without context\n\nThis keeps the workflow autonomous from inside Codex itself: once the session\nwas started through Flow, you can inspect the current trace without manually\ncopying ids.\n\n`f codex eval --path ...` is the joined operator report:\n\n- current runtime/doctor state\n- recent route mix and context cost\n- grounded skill scorecard highlights\n- concrete “what to improve next” recommendations\n- commands to deepen or fix the current state\n\nIf `jd` is running, it also keeps recent completion reconciliation warm and\nnow does a bounded background scorecard refresh, so the eval report does not go\nstale as quickly between manual runs.\n\nIf the native session bridge skill is installed, `jd` also prewarms compact\nhandoff capsules for recent native Codex sessions whenever the Codex state DB\nchanges. That keeps the exact handoff path cheap, so pasting\n`019d... codex session` into another chat is usually already a warm cache hit\ninstead of the first lookup having to build the capsule from the rollout.\n\nOptional telemetry export follows the same local-first pattern: Flow keeps\nlocal Codex logs canonical, and if `FLOW_CODEX_MAPLE_*` env vars are set it can\nexport redacted route/context/outcome spans to Maple without shipping raw\nprompts or full repo paths. Use:\n\n```bash\nf codex telemetry status\nf codex telemetry flush --limit 200\n```\n\nFor local-only secrets, prefer `f env set --personal ...`. On macOS you may\nneed `f env unlock` once per day for background reads. Flow-launched Codex\nsessions also inherit the same `FLOW_CODEX_MAPLE_*` values from the personal\nstore, while explicit shell env still wins for one-off tests.\n\nWhen `jd` is running, the daemon also performs a bounded background export\npass so the external analytics view stays warm.\n\n### macOS launchd schedule for skill-eval\n\nIf you want scorecards to stay fresh automatically on macOS:\n\n```bash\nf codex-skill-eval-launchd-install\nf codex-skill-eval-launchd-status\nf codex-skill-eval-launchd-logs\n```\n\n`f codex enable-global --full` installs this schedule for you.\n\nDefault schedule:\n\n- every 30 minutes\n- scan up to 400 recent events\n- rebuild up to 12 recent repo scorecards\n- ignore repos not seen in the last 168 hours\n\nYou can tune install-time bounds:\n\n```bash\nf codex-skill-eval-launchd-install --minutes 20 --limit 600 --max-targets 16 --within-hours 72\nf codex-skill-eval-launchd-install --dry-run\n```\n\nRemove it with:\n\n```bash\nf codex-skill-eval-launchd-uninstall\n```\n\n### Cursor behavior\n\nCursor transcripts are read-only in Flow:\n\n- `f ai cursor list` opens a picker and copies the selected transcript\n- `f ai cursor copy` copies the latest Cursor transcript for this repo\n- `f ai cursor context ...` copies the last N exchanges\n- `f cursor ...` is a shortcut for the same provider-specific read commands\n\n### Cross-directory resume\n\nYou can target another repo without changing directory:\n\n```bash\nf ai codex resume --path ~/work/example-project\nf ai codex resume --path ~/work/example-project 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai codex continue --path ~/work/example-project\n```\n\n- `resume --path <repo>` resolves the requested session against that repo instead of the current cwd\n- `continue --path <repo>` resumes the latest session for that repo\n- explicit full Codex IDs still work directly even when your current cwd is different\n\n## Session Selectors\n\n`resume` accepts:\n\n- saved alias from `.ai/sessions/claude/index.json`\n- full session ID\n- ID prefix (8+ chars)\n- numeric index from list output (1-based)\n\nExamples:\n\n```bash\nf ai resume my-feature\nf ai resume a38cf8bf\nf ai claude resume 2\nf ai codex resume 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai cursor context 382ef1a3 /path/to/repo 2\n```\n\n## Content Copy Commands\n\n```bash\n# Copy full conversation to clipboard\nf ai copy\nf ai copy <session>\n\n# Copy last N prompt/response turns\nf ai context\nf ai context <session> <path> <count>\n```\n\nUse `-` as session placeholder to trigger fuzzy selection:\n\n```bash\nf ai claude context - /path/to/repo 3\nf ai cursor context - /path/to/repo 3\n```\n\n## Project Workflow (Recommended)\n\n1. Start from repo root and inspect tasks:\n   `f tasks list`\n2. Resume exact session when continuing prior work:\n   `f ai claude resume <id>` or `f ai codex resume <id>`\n3. Keep context current:\n   `f skills sync` then `f skills reload`\n4. Validate through tasks:\n   `f test-related` / `f test`\n5. Commit through Flow gates:\n   `f commit`\n\nThis keeps sessions, tasks, skills, and commit quality checks in one loop.\n\n## Everruns Bridge Mode\n\nFlow also supports running a prompt through Everruns while routing client-side\n`seq_*` tool calls to local `seqd`:\n\n```bash\nf ai everruns \"open Safari and take a screenshot\"\n```\n\nKey points:\n\n- This path is additive. It does not replace `f ai claude ...` or `f ai codex ...`.\n- Flow now reuses Seq's canonical Everruns bridge for:\n  - `seq_*` tool definitions injected into new sessions\n  - tool-name normalization (`seq_open_app`, `seq.open_app`, `seq:open-app`)\n  - request correlation IDs (`request_id`, `run_id`, `tool_call_id`)\n- Event transport is SSE-first (`/sse`) with automatic fallback to polling (`/events`) if SSE is unavailable.\n- Optional Maple telemetry export can dual-write runtime traces to local + hosted ingest endpoints when `SEQ_EVERRUNS_MAPLE_*` env vars are configured.\n- Existing Flow features remain unchanged (`f seq-rpc`, session resume/copy/context flows).\n\nSetup and validation details are documented in:\n\n- `docs/everruns-seq-bridge-integration.md`\n- `docs/everruns-maple-runbook.md`\n","docs/commands/clone.md":"# f clone\n\nClone a repository with git-like destination behavior.\n\n## Overview\n\n`f clone` behaves like `git clone` for destination paths:\n\n- `f clone <url>` clones into the current working directory using Git's default folder naming.\n- `f clone <url> <dir>` clones into an explicit destination directory.\n\nFor GitHub inputs, Flow normalizes clone URLs to SSH:\n\n- `https://github.com/owner/repo` -> `git@github.com:owner/repo.git`\n- `owner/repo` -> `git@github.com:owner/repo.git`\n\nThis command does not force clones into `~/repos` and does not auto-configure `upstream`.\n\n## Usage\n\n```bash\nf clone <url-or-owner/repo> [directory]\n```\n\n## Examples\n\n```bash\n# GitHub URL -> SSH clone URL\nf clone https://github.com/genxai/new\n\n# owner/repo shorthand -> SSH clone URL\nf clone genxai/new\n\n# explicit destination folder (same as git clone)\nf clone genxai/new my-local-new\n```\n\n## When To Use\n\n- Use `f clone` when you want standard `git clone` destination behavior.\n- Use [`f repos clone`](repos.md) when you want managed placement under `~/repos/<owner>/<repo>` plus optional upstream automation.\n","docs/commands/commit.md":"# f commit\n\nAI-powered commit with deferred Codex review and GitEdit sync.\n\n## Overview\n\nStages all changes, commits quickly by default, runs Codex deep review asynchronously in the background, pushes, and syncs AI sessions to gitedit.dev.\n\n## Quick Start\n\n```bash\n# Default flow: commit now, Codex review runs in background\nf commit\n\n# Blocking pre-commit review (legacy behavior)\nf commit --slow\n\n# Fast commit with custom message (no AI review, no Codex follow-up)\nf commit --fast \"fix typo\"\nf commit --fast  # defaults to \".\" as message\n\n# Queue for review (no push) + create jj review bookmark\nf commit --queue\n\n# Commit without pushing\nf commit -n\n\n# Include AI context in review\nf commit --context\n\n# Custom message\nf commit -m \"Fixes #123\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--no-push` | `-n` | Skip pushing after commit |\n| `--queue` | | Queue the commit for review (no push) |\n| `--no-queue` | | Bypass queue and allow push |\n| `--sync` | | Run synchronously (don't delegate to hub) |\n| `--context` | | Include AI session context in code review |\n| `--dry` | | Dry run: show context without committing |\n| `--quick` | | Explicitly use fast commit + async Codex review (compat alias) |\n| `--slow` | | Run blocking pre-commit review before commit |\n| `--fast [MSG]` | | Fast commit with no AI review (defaults to \".\") |\n| `--codex` | | Use Codex instead of Claude for review |\n| `--review-model <MODEL>` | | Choose specific review model |\n| `--message <MSG>` | `-m` | Custom message appended to commit |\n| `--tokens <N>` | `-t` | Max tokens for AI context (default: 1000) |\n\n## Review Models\n\n| Model | Description |\n|-------|-------------|\n| `claude-opus` | Claude Opus 1 for review (default) |\n| `codex-high` | Codex high-capacity (gpt-5.1-codex-max) |\n| `codex-mini` | Codex mini (gpt-5.1-codex-mini) |\n\n```bash\n# Use Codex\nf commit --codex\n\n# Specific model\nf commit --review-model codex-high\n```\n\n---\n\n## Fast Commit + Deferred Codex Review\n\n`f commit` now uses this mode by default.\n\n### Default (`f commit`) / `--quick` — commit now, Codex reviews later\n\nCommits immediately (generates an AI commit message but skips the blocking code review), then spawns a background Codex review for that commit. The review result is queued and visible via `f commit-queue list`.\n\n```bash\nf commit\nf commit --quick\n```\n\nWhat happens:\n1. Stages all changes, generates commit message, commits, pushes\n2. Queues the commit SHA for async review\n3. Spawns a background Codex process that reviews the diff\n4. You keep working — check results later with `f commit-queue list`\n\n### `--slow` — run blocking review before commit\n\nRuns the pre-commit AI review before creating the commit.\n\n```bash\nf commit --slow\nf commit --slow --review-model codex-high\n```\n\n### `--fast` — instant commit, no review at all\n\nCommits with a provided message (or `\".\"` if omitted). No AI review, no async follow-up. Useful for trivial changes.\n\n```bash\nf commit --fast \"fix typo\"\nf commit --fast              # message defaults to \".\"\n```\n\n### When to use which\n\n| Flag | AI message | Code review | Async review | Best for |\n|------|-----------|-------------|-------------|----------|\n| (none) | Yes | No | Yes (Codex background) | Default fast workflow |\n| `--quick` | Yes | No | Yes (Codex background) | Explicit fast mode |\n| `--slow` | Yes | Yes (blocking) | No | Pre-commit deep check |\n| `--fast` | No (you provide) | No | No | Trivial/WIP commits |\n\n### Opt Out Of Fast Default\n\nIf you want plain `f commit` to run blocking review by default, set:\n\n```toml\n[commit]\nquick-default = false\n```\n\nWith this set, plain `f commit` behaves like `f commit --slow` unless you explicitly pass `--quick`.\n\nRun deep review in batches:\n\n```bash\nf reviews-todo codex --all\nf reviews-todo list\n```\n\n### Myflow Fast + Deep Profile\n\nFor `~/code/myflow`, this profile gives a fast default loop while keeping deep Codex coverage:\n\n```toml\n[commit]\nquick-default = true\nqueue = false\nqueue_on_issues = false\n\n# Fast message generation path via zerg/ai (glm + cerebras), then fallbacks.\nmessage_fallbacks = [\n  \"rise:zai:glm-5\",\n  \"rise:cerebras:gpt-oss-120b\",\n  \"remote\",\n  \"openai\"\n]\n\n# When you explicitly run blocking review, prefer fast models first.\nreview_fallbacks = [\n  \"glm5\",\n  \"rise:cerebras:gpt-oss-120b\",\n  \"codex-high\"\n]\n```\n\nThen operate with:\n\n```bash\nf commit\nf reviews-todo codex --all\n```\n\n---\n\n## What Happens\n\n1. **Safety Checks**\n   - Warns about sensitive files (.env, .pem, keys, credentials)\n   - Warns about files with large diffs (500+ lines)\n   - Runs invariant checks from `[invariants]` when configured\n\n2. **Stage Changes**\n   - Runs `git add -A` to stage all changes\n\n3. **Code Review**\n   - Sends diff to AI for review\n   - Checks for bugs, security issues, best practices\n   - Optionally includes AI session context (`--context`)\n\n4. **Generate Message**\n   - AI generates commit message from diff\n   - Appends custom message if provided (`-m`)\n\n5. **Commit**\n   - Creates commit with generated message\n\n6. **Queue (optional)**\n   - Adds commit to the review queue (`f commit-queue list`)\n   - Creates a jj review bookmark (e.g., `review/main-<sha>`)\n\n7. **Push**\n   - Pushes to remote (unless `--no-push` or `--queue`)\n\n7. **GitEdit Sync**\n   - Syncs AI session data to gitedit.dev\n\n## Invariant Gate\n\nIf your project defines `[invariants]` in `flow.toml`, `f commit` evaluates the staged diff against those rules (forbidden patterns, dependency allowlist policy, file line limits).\n\n- `mode = \"warn\"`: commit continues and findings are shown.\n- `mode = \"block\"`: commit is blocked on warning/critical findings.\n- Findings are injected into the AI review context.\n\n---\n\n## Usage Examples\n\n### Basic Commit\n\n```bash\n# Review, commit, and push\nf commit\n```\n\n### Local Commit Only\n\n```bash\n# Don't push to remote\nf commit -n\n```\n\n### With AI Context\n\nInclude recent AI session context in the review:\n\n```bash\nf commit --context\nf commit --context --tokens 2000  # More context\n```\n\n### Custom Message\n\nAppend additional context to the commit:\n\n```bash\nf commit -m \"Fixes #123\"\nf commit -m \"Co-authored-by: John <john@example.com>\"\n```\n\n### Dry Run\n\nSee what would be reviewed without committing:\n\n```bash\nf commit --dry\n```\n\n### Synchronous Mode\n\nRun directly without delegating to hub:\n\n```bash\nf commit --sync\n```\n\n---\n\n## Safety Warnings\n\n### Sensitive Files\n\nBefore committing, flow warns if staging files that look sensitive:\n\n```\n⚠ Warning: The following sensitive files are staged:\n  - .env\n  - credentials.json\n  - private.key\n```\n\nSensitive patterns include:\n- `.env`, `.env.*`\n- `credentials.json`, `secrets.json`\n- `.pem`, `.key`, `id_rsa`, `id_ed25519`\n- Files containing `password`, `secret`, `token`\n\n### Secret Scan (Staged Diff)\n\nFlow scans staged diffs for likely secrets (API keys, tokens, passwords). If a match\nis detected, the commit is blocked. In an interactive terminal, flow offers to run\nan auto-fix using `ai` to mask or replace the values, then asks for approval to\ncontinue.\n\nYou can bypass the check for a single commit with:\n\n```\nFLOW_ALLOW_SECRET_COMMIT=1 f commit\n```\n\n### Large Diffs\n\nWarns about files with significant changes:\n\n```\n⚠ Warning: The following files have large diffs:\n  - src/generated.rs (1523 lines)\n  - data/fixtures.json (834 lines)\n```\n\nThreshold: 500+ lines added/removed.\n\n---\n\n## Related Commands\n\n| Command | Description |\n|---------|-------------|\n| `f commit` | Fast commit + deferred Codex review (default) |\n| `f commitWithCheck` | Review without GitEdit sync |\n| `f commitSimple` | No review, just AI commit message |\n\n### commitWithCheck (alias: cc)\n\nSame as `commit` but skips GitEdit sync:\n\n```bash\nf commitWithCheck\nf cc  # Short alias\n```\n\n### commitSimple\n\nQuick commit without code review:\n\n```bash\nf commitSimple\n```\n\n---\n\n## Configuration\n\n### Hub Delegation\n\nBy default, `f commit` delegates to the hub daemon for async processing. Use `--sync` for direct execution:\n\n```bash\n# Async via hub (default)\nf commit\n\n# Sync (direct)\nf commit --sync\n```\n\n### Commit Message Tool\n\nOptionally force a specific commit-message generator:\n\n```toml\n[commit]\nmessage_tool = \"kimi\" # also supports: claude, rise, glm5, opencode, openrouter, remote, openai\nmessage_model = \"kimi-k2-thinking-turbo\" # optional, tool-specific\n```\n\nIf the forced tool fails, `f commit` now falls back through the configured/default chain.\n\n### Review Tool (Kimi CLI)\n\nUse Kimi Code CLI for code review:\n\n```toml\n[review]\ntool = \"kimi\"\nmodel = \"kimi-k2-thinking-turbo\" # optional; uses Kimi default if omitted\n```\n\nThis uses `kimi --quiet` (print mode) with your existing Kimi CLI auth/config.\n\n### Robust Fallbacks\n\n`f commit` now uses multi-attempt fallback chains for both review and commit-message generation.\n\nDefault behavior:\n- Review: primary selection, then `openrouter`, `claude`, `codex-high`\n- Message: review-aligned/override tool, then `remote` (myflow), `openai`, `openrouter`\n- If all message attempts fail and fail-open is enabled, Flow uses a deterministic local fallback message.\n\nConfiguration:\n\n```toml\n[commit]\nreview_fail_open = true\nmessage_fail_open = true\nreview_fallbacks = [\"openrouter\", \"claude\", \"codex-high\"]\nmessage_fallbacks = [\"remote\", \"openai\", \"openrouter\"]\n```\n\nEnvironment overrides:\n- `FLOW_COMMIT_REVIEW_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_MESSAGE_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_REVIEW_FALLBACKS=\"openrouter,claude,codex-high\"`\n- `FLOW_COMMIT_MESSAGE_FALLBACKS=\"remote,openai,openrouter\"`\n\nCodex -> GLM5 fallback example:\n\n```toml\n[commit]\nreview_fallbacks = [\"glm5\", \"openrouter\", \"claude\"]\nmessage_fallbacks = [\"glm5\", \"remote\", \"openai\"]\n```\n\n`glm5` maps to the Rise/internal route with model `zai:glm-5`.\n\n### Queue Policy\n\nQueue only when review finds issues (auto-push on a clean review):\n\n```toml\n[commit]\nqueue = true\nqueue_on_issues = true\n```\n\n`--queue` / `--no-queue` still override this behavior.\n\n### Commit Quality Gates (Testing + Required Skills)\n\nUse local gates to block commits that skip tests or required workflow skills:\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\nWhen `mode = \"block\"`, `f commit` fails until the test/skill requirements are satisfied.  \nFor Bun repos, run checks with `bun bd test ...` for debug-build validation. If no related tracked tests are found, Flow can run tests under `ai_scratch_test_dir` (default `.ai/test`) as a fallback signal.\n\n### AI Session Context\n\nWhen `--context` is enabled, includes recent Claude Code session context:\n\n```bash\n# Default: 1000 tokens of context\nf commit --context\n\n# More context\nf commit --context --tokens 3000\n```\n\n---\n\n## Examples\n\n### Quick Bug Fix\n\n```bash\n# Fix bug, commit with context\nvim src/lib.rs\nf commit --context -m \"Fixes null pointer in edge case\"\n```\n\n### Feature Branch\n\n```bash\n# Work on feature\ngit checkout -b feature/new-api\n# ... make changes ...\n\n# Commit without push\nf commit -n\n\n# More changes...\nf commit -n\n\n# Final push\ngit push -u origin feature/new-api\n```\n\n### Review Before Commit\n\n```bash\n# See what would be reviewed\nf commit --dry\n\n# If satisfied, commit\nf commit\n```\n\n---\n\n## Troubleshooting\n\n### \"Sensitive files staged\"\n\nEither:\n1. Add files to `.gitignore`\n2. Unstage with `git reset HEAD <file>`\n3. Proceed anyway if intentional\n\n### Review taking too long\n\nUse `--sync` to see progress directly:\n```bash\nf commit --sync\n```\n\n### Hub not responding\n\nFall back to sync mode:\n```bash\nf commit --sync\n```\n\n## See Also\n\n- [upstream](upstream.md) - Sync forks before committing\n- [publish](publish.md) - Publish after committing\n","docs/commands/commits.md":"# f commits\n\nBrowse commits with AI metadata and mark notable commits for quick access.\n\n## Usage\n\n```bash\nf commits\nf commits --limit 200\nf commits --all\nf commits top\nf commits mark <hash>\nf commits unmark <hash>\n```\n\n## Notable commits\n\nNotable commits are stored in `.ai/internal/commits/top.txt` in the repo root. Each line is:\n\n```\n<full-hash>\\t<label>\n```\n\n## Key bindings\n\nWhen using fzf:\n\n- `ctrl-t` — toggle notable for the selected commit.\n","docs/commands/config.md":"# f config\n\nCompile the personal Flow root config and generated compatibility outputs.\n\nSource of truth:\n\n- `~/.flow/config.ts`\n\nGenerated outputs:\n\n- `~/.config/flow/generated/config.snapshot.json`\n- `~/.config/flow/generated/flow/config.ts`\n- `~/.config/flow/generated/lin/config.ts`\n- `~/.config/flow/generated/lin/intents.json`\n- `~/.config/flow/generated/lin/mac.toml`\n- `~/.config/flow/generated/ai/config.json`\n\nHive config may still appear in the effective root config during migration, but Flow no longer emits or applies `~/.hive/config.json`.\n\nIf `~/.flow/config.ts` does not exist yet, Flow currently falls back to:\n\n- `~/config/i/lin/config.ts`\n\nand generates a starter `~/.flow/config.ts` migration file on apply.\n\n## Commands\n\n### f config doctor\n\nShows whether the root config exists, whether a TypeScript runner is available,\nwhether a generated snapshot already exists, and what extension directories are discoverable.\n\n```bash\nf config doctor\nf config doctor --json\n```\n\n### f config build\n\nLoads the root config plus named extensions, computes the merged effective config,\nand writes generated artifacts under `~/.config/flow/generated/`.\n\nThis does not overwrite consumer config locations.\n\n```bash\nf config build\nf config build --json\n```\n\n### f config apply\n\nBuilds the snapshot and then applies the generated compatibility files into their\nconsumer locations. This is the cutover step that keeps existing tools working while\nmoving authoring into `~/.flow/config.ts`.\n\n```bash\nf config apply\nf config apply --json\n```\n\n### f config eval\n\nPrints the currently effective merged config view. If no snapshot exists yet, Flow\nbuilds one first.\n\n```bash\nf config eval\nf config eval --json\n```\n\n## Root Config Shape\n\nThe first supported root-config shape is:\n\n```ts\nexport default {\n  flow: { ... },\n  lin: { ... },\n  ai: { ... },\n  hive: { ... }, // parsed for migration compatibility, not applied to ~/.hive\n  zerg: { ... },\n  extensions: [\"lin-compat\"],\n}\n```\n\nFilesystem extensions can live under:\n\n- `~/.flow/extensions/<name>/extension.ts`\n- `~/.flow/extensions/<name>/config.ts`\n\nEach extension can contribute partial config fragments plus optional generated files.\n\n## Notes\n\n- Flow currently ships one built-in extension name: `lin-compat`\n- explicit extensions must exist or `f config build` fails\n- generated outputs are written atomically\n- if a `hive` section is present, `f config build/apply/eval` warns that Hive output is deprecated and ignored\n","docs/commands/db.md":"# db\n\nManage database workflows and backends (Jazz + Postgres).\n\n## Usage\n\n```bash\nf db <provider> <action>\n```\n\n## Jazz\n\nCreate Jazz2 app credentials and populate env vars for the current project.\n\n```bash\nf db jazz new --kind mirror --name gitedit-mirror\n```\n\nResolution order for the credential bootstrap helper:\n\n1. Local `jazz-tools` binary on `PATH`\n2. Pinned `npx --yes jazz-tools@0.20.14`\n\nFor deliberate experiments, override the pinned fallback with:\n\n```bash\nFLOW_JAZZ_TOOLS_PACKAGE_SPEC=jazz-tools@<version> f db jazz new --kind mirror\n```\n\n## Postgres\n\nRun Drizzle migrations for the default Postgres project (`~/org/la/la/server`).\n\n```bash\nf db postgres migrate\nf db postgres migrate --generate\nf db postgres generate\n```\n\nEnvironment resolution order for `DATABASE_URL`:\n\n1. `--database-url` flag\n2. `DATABASE_URL`\n3. `PLANETSCALE_DATABASE_URL` / `PSCALE_DATABASE_URL`\n4. `<project>/.env` (DATABASE_URL)\n\nUse `--project` to override the Postgres project directory.\n","docs/commands/deploy.md":"# f deploy\n\nDeploy projects to hosts and cloud platforms.\n\n## Overview\n\nThe `deploy` command handles deployment to multiple platforms:\n- **Linux hosts** via SSH (with systemd + nginx)\n- **Cloudflare Workers**\n- **Railway**\n\nAuto-detects the platform from your `flow.toml` configuration.\nIf `[flow].deploy_task` is set, `f deploy` runs that task first.\nIf no deployment config exists but a `deploy` task is defined, `f deploy` runs that task.\nUse `f prod` to deploy directly from `[host]`, `[cloudflare]`, `[railway]`, or `[web]` (it skips `[flow].deploy_task`).\n\n## Quick Start\n\n```bash\n# Auto-deploy based on flow.toml config\nf deploy\n\n# Production deploy (skips flow.deploy_task, uses deploy config or deploy-prod task)\nf prod\n\n# Run the project's release task (flow.release_task or fallback)\nf deploy release\n\n# Deploy to specific platform\nf deploy host\nf deploy cloudflare\nf deploy railway\n\n# Production deploy to specific platform\nf prod host\nf prod cloudflare\n\n# Configure deployment defaults\nf deploy config\n\n# Deploy web site\nf deploy web\n```\n\n## Subcommands\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `host` | `h` | Deploy to Linux host via SSH |\n| `cloudflare` | `cf` | Deploy to Cloudflare Workers |\n| `web` | | Deploy the web site (Cloudflare) |\n| `setup` | | Interactive deploy setup (Cloudflare) |\n| `railway` | | Deploy to Railway |\n| `config` | | Configure deployment defaults (Linux host) |\n| `release` | | Run the project's release task |\n| `status` | | Show deployment status |\n| `logs` | | View deployment logs |\n| `restart` | | Restart the deployed service |\n| `stop` | | Stop the deployed service |\n| `shell` | | SSH into the host |\n| `set-host` | `set` | Configure host for deployment |\n| `show-host` | | Show current host configuration |\n| `health` | | Check if deployment is healthy |\n\n---\n\n## Web Deployment\n\nDeploys the web site using Cloudflare and your project tasks. Flow will:\n- Ensure `[web]` exists in `flow.toml` (auto-fills `path` when possible).\n- Add the `web.route` (or `web.domain/*`) to your wrangler config.\n- Optionally create/update the Cloudflare DNS record for the domain/route.\n- Apply env vars from cloud if `web.env_source = \"cloud\"` is set.\n- Run `deploy-web` (or `deploy` as fallback).\n\n```bash\nf deploy web\n```\n\nIf the Cloudflare API token is missing, Flow will guide you to create one and\nstore it in your env store as `CLOUDFLARE_API_TOKEN`.\n\nIf `web.domain`/`web.route` or `web.path` is missing, Flow will prompt for them\nand update `flow.toml`.\n\nIf you opt into DNS management, Flow will prompt for record type/target and\ncreate or update the Cloudflare DNS record (default: `A` to `192.0.2.1`,\nproxied).\n\nIf cloud is unavailable, Flow can store envs locally when you choose\n`web.env_source = \"local\"`.\n\nExample `flow.toml`:\n\n```toml\n[web]\npath = \"packages/web\"\ndomain = \"example.com\"\nenv_source = \"cloud\"\nenv_apply = \"always\"\nenv_keys = [\"PUBLIC_API_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\n## Host Deployment (Linux via SSH)\n\nDeploy to any Linux server with SSH access. Flow handles:\n- File syncing via rsync\n- Systemd service creation\n- Nginx reverse proxy setup\n- SSL via Let's Encrypt\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[flow]\ndeploy_task = \"deploy-cli-release\"\n\n[host]\ndest = \"/opt/myapp\"           # Remote destination path\nrun = \"./server\"              # Command to run the service\nport = 3000                   # Port the service listens on\nservice = \"myapp\"             # Systemd service name (optional, defaults to folder name)\nsetup = \"./scripts/setup.sh\"  # Setup script to run after first sync (optional)\nenv_file = \".env.production\"  # Path to .env file for secrets (optional)\nenv_source = \"flow\"           # Pull envs from Flow env store (optional)\nenv_keys = [\"API_KEY\"]        # Keys to fetch when env_source=flow/cloud (optional)\ndomain = \"myapp.example.com\"  # Public domain for nginx (optional)\nssl = true                    # Enable SSL via Let's Encrypt (optional)\n```\n\nTip: `f setup deploy` can scaffold the `[host]` section and create a remote setup script.\n\n### Setup Host\n\nFirst, configure your SSH connection:\n\n```bash\n# Set host (stored globally at ~/.config/flow/deploy.json)\nf deploy set-host user@host:port\nf deploy set-host deploy@myserver.com:22\nf deploy set-host root@192.168.1.100\n\n# Interactive config (prefills from ~/.config/infra/config.json if present)\nf deploy config\n\n# Verify connection\nf deploy shell\n```\n\n### Deploy\n\n```bash\n# Deploy to host\nf deploy host\n\n# Force re-run setup script\nf deploy host --setup\n\n# Build remotely instead of syncing local artifacts\nf deploy host --remote-build\n```\n\n### What Happens\n\n1. **Sync files** - rsync uploads project (excludes `target/`, `.git/`, `node_modules/`, `.env`, `*.log`)\n2. **Copy env file** - If `env_file` is specified, copies it to `{dest}/.env`\n   (or, if `env_source = \"flow\"`, fetches from Flow env store and writes `{dest}/.env`)\n3. **Run setup** - Executes setup script on first deploy or with `--setup`\n4. **Create systemd service** - Generates and enables `/etc/systemd/system/{service}.service`\n5. **Configure nginx** - If `domain` is set, creates reverse proxy config\n6. **Setup SSL** - If `ssl = true`, runs certbot for Let's Encrypt certificate\n7. **Start service** - Runs `systemctl restart {service}`\n\n### Manage Service\n\n```bash\n# View logs\nf deploy logs                 # Since last deploy (host only)\nf deploy logs -f              # Follow in real-time (since last deploy)\nf deploy logs --all           # Full history (ignore deploy marker)\nf deploy logs --all -n 500    # Show last 500 lines without deploy filter\n\n# Restart/stop\nf deploy restart\nf deploy stop\n\n# Check status\nf deploy status\n\n# SSH into server\nf deploy shell\n\n# Health check\nf deploy health\nf deploy health --url https://myapp.example.com/health\nf deploy health --status 204  # Expect specific status code\n```\n\nNote: For host deploys, Flow records the last successful deploy time in `.flow/deploy-log.json` and uses it to scope `f deploy logs` output. Use `--all` to ignore it.\n\n---\n\n## Cloudflare Workers\n\nDeploy to Cloudflare's edge network.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[cloudflare]\npath = \"worker\"                    # Path to worker directory (optional, defaults to project root)\nenvironment = \"production\"         # Wrangler environment name (optional)\nenv_file = \".env.cloudflare\"       # Path to .env file for secrets (optional)\nenv_source = \"cloud\"              # Use cloud or local env store for secrets (optional)\nenv_keys = [\"API_KEY\", \"SECRET\"]   # Specific keys to fetch from env store (optional)\nenv_vars = [\"PUBLIC_URL\"]          # Keys to set as non-secret vars (optional)\ndeploy = \"wrangler deploy\"         # Custom deploy command (optional)\ndev = \"wrangler dev\"               # Custom dev command (optional)\nurl = \"https://my-worker.workers.dev\"  # URL for health checks (optional)\n```\n\n### Prerequisites\n\n- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) installed\n- `wrangler.toml` in your worker directory\n- Authenticated with `wrangler login`\n\n### Deploy\n\n```bash\n# Deploy\nf deploy cloudflare\n\n# Deploy with secrets from env_file\nf deploy cloudflare --secrets\n\n# Run in dev mode\nf deploy cloudflare --dev\n```\n\n### Production domain (for `f prod`)\n\nUse `[prod]` to set a production domain or route for Workers. `f prod` will add\nthe route to your `wrangler.json/jsonc` before deploying.\n\n```toml\n[prod]\ndomain = \"anysynth.nikiv.com\"   # Will be mapped to route \"anysynth.nikiv.com/*\"\n# route = \"anysynth.nikiv.com/*\"  # Use this for explicit patterns\n```\n\n### Interactive Setup\n\nFor first-time setup, use the interactive wizard:\n\n```bash\nf deploy setup\n```\n\nThis walks you through:\n1. Selecting worker directory (auto-discovers `wrangler.toml`)\n2. Choosing .env file for secrets\n3. Selecting Cloudflare environment (production, staging, etc.)\n4. Picking which secrets to push\n5. Updating `flow.toml` with your choices\n\nIf your `flow.toml` lists service keys (for example Stripe keys), the setup flow\nwill offer to run the matching service onboarding before applying envs.\n\n### Secrets from cloud\n\nIf using cloud for secret management:\n\n```toml\n[cloudflare]\nenv_source = \"cloud\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"]  # Fetched as secrets\nenv_vars = [\"PUBLIC_API_URL\"]                      # Fetched as non-secret vars\nenvironment = \"production\"\n```\n\nThen deploy:\n\n```bash\nf deploy cloudflare --secrets\n```\n\nIf you want to use local Flow envs instead:\n\n```toml\n[cloudflare]\nenv_source = \"local\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\nIf you need to fill missing values first:\n\n```bash\nf env guide\n```\n\n---\n\n## Railway\n\nDeploy to Railway's platform.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[railway]\nproject = \"my-project\"         # Railway project ID\nservice = \"api\"                # Service name (optional)\nenvironment = \"production\"     # Environment name (optional)\nstart = \"npm start\"            # Start command (optional)\nenv_file = \".env.railway\"      # Path to .env file (optional)\n```\n\n### Prerequisites\n\n- [Railway CLI](https://docs.railway.app/develop/cli) installed (`npm install -g @railway/cli`)\n- Authenticated with `railway login`\n\n### Deploy\n\n```bash\nf deploy railway\n```\n\nWhat happens:\n1. Links to Railway project if specified\n2. Sets environment variables from `env_file`\n3. Deploys with `railway up --detach`\n\n---\n\n## Health Checks\n\nCheck if your deployment is responding:\n\n```bash\n# Use domain from [host] or url from [cloudflare] config\nf deploy health\n\n# Custom URL\nf deploy health --url https://api.example.com/health\n\n# Expect specific status code\nf deploy health --status 204\n```\n\nReturns:\n- `Healthy (HTTP 200 in 0.15s)` on success\n- `Unhealthy: expected HTTP 200, got 500` on wrong status\n- `Unreachable: Connection refused` on network error\n\n---\n\n## Global Host Configuration\n\nHost connection is stored globally at `~/.config/flow/deploy.json`:\n\n```json\n{\n  \"host\": {\n    \"user\": \"deploy\",\n    \"host\": \"myserver.com\",\n    \"port\": 22\n  }\n}\n```\n\nView/set:\n\n```bash\nf deploy show-host\nf deploy set-host deploy@newserver.com:2222\n```\n\n---\n\n## Examples\n\n### Full Host Setup\n\n```toml\n# flow.toml\n[host]\ndest = \"/opt/api\"\nrun = \"/opt/api/server\"\nport = 8080\nservice = \"myapi\"\nsetup = \"cargo build --release && cp target/release/server /opt/api/\"\nenv_file = \".env.production\"\ndomain = \"api.mycompany.com\"\nssl = true\n```\n\n```bash\n# First time setup\nf deploy set-host root@myserver.com\n\n# Deploy\nf deploy host\n\n# Check it's working\nf deploy health\nf deploy logs -f\n```\n\n### Full Cloudflare Setup\n\n```toml\n# flow.toml\n[cloudflare]\npath = \"packages/worker\"\nenvironment = \"production\"\nenv_source = \"cloud\"\nenv_keys = [\"OPENAI_API_KEY\", \"WEBHOOK_SECRET\"]\nurl = \"https://my-worker.mycompany.workers.dev\"\n```\n\n```bash\n# Store project secrets\nf env project set -e production OPENAI_API_KEY=sk-...\nf env project set -e production WEBHOOK_SECRET=whsec_...\n\n# Deploy with secrets\nf deploy cloudflare --secrets\n\n# Verify\nf deploy health\n```\n\n### CI/CD Integration\n\n```yaml\n# GitHub Actions\ndeploy:\n  runs-on: ubuntu-latest\n  steps:\n    - uses: actions/checkout@v4\n    - name: Deploy\n      run: |\n        f deploy set-host ${{ secrets.DEPLOY_HOST }}\n        f deploy host\n        f deploy health\n```\n\n---\n\n## Troubleshooting\n\n### \"No host configured\"\n\nRun `f deploy set-host user@host:port` first.\n\n### \"No wrangler config found\"\n\nEnsure `wrangler.toml` exists in your worker directory, or run `wrangler init`.\n\n### SSH connection fails\n\nTest with `f deploy shell` to debug. Check:\n- SSH key is in `~/.ssh/` and added to server\n- Port is correct (default: 22)\n- Server is reachable\n\n### Secrets not updating\n\nFor Cloudflare, use `--secrets` flag: `f deploy cloudflare --secrets`\n\n### Health check fails\n\nCheck URL is correct and service is running:\n```bash\nf deploy logs -f  # Check for errors\ncurl -v https://your-domain.com  # Test manually\n```\n","docs/commands/docs.md":"# f docs\n\nManage documentation for a project. There are two doc systems:\n\n- `.ai/docs` for AI-maintained internal docs.\n- `docs/` for human-facing docs rendered by the docs hub.\n\n## Quick Start\n\n```bash\n# Create docs/ with starter files\nf docs new\n\n# Open docs for the current project (auto-starts the hub)\nf docs\n\n# Deploy the current project's docs to Cloudflare Pages\nf docs deploy\n```\n\n## Commands\n\n### f docs new\n\nCreates a `docs/` folder in the current project using the template in `~/new/docs`.\nIf `docs/` already exists, it merges in any missing template files and leaves\nexisting content untouched.\n\nOptions:\n\n- `--path <PATH>`: Target directory (defaults to current folder).\n- `--force`: Overwrite if `docs/` already exists.\n\n### f docs hub\n\nRuns a single dev server that aggregates docs from `~/code` and `~/org`.\nUse `FLOW_DOCS_FOCUS=1` to only index the current project for faster startup.\n\nOptions:\n\n- `--host <HOST>` (default: `127.0.0.1`)\n- `--port <PORT>` (default: `4410`)\n- `--hub-root <PATH>` (default: `~/.config/flow/docs-hub`)\n- `--template-root <PATH>` (default: `~/new/docs`)\n- `--code-root <PATH>` (default: `~/code`)\n- `--org-root <PATH>` (default: `~/org`)\n- `--no-ai`: Skip `.ai/docs`.\n- `--no-open`: Do not open the browser.\n- `--sync-only`: Sync docs content and exit.\n\n### f docs deploy\n\nDeploys the current project's docs to Cloudflare Pages (uses the docs hub template).\n\nOptions:\n\n- `--project <NAME>`: Pages project name (defaults to the flow.toml name).\n- `--domain <DOMAIN>`: Attach a custom domain (optional).\n- `--yes`: Skip confirmation prompts.\n\n### f docs sync\n\nSyncs `.ai/docs` metadata based on recent commits. Intended for AI doc upkeep.\n\n### f docs list\n\nLists `.ai/docs` files for the current project.\n\n### f docs status\n\nShows recent commits and `.ai/docs` file modification times.\n\nIt now also shows:\n\n- recent Flow-managed Codex session packets stored under Flow state for the current project\n- doc-review queue state counts for the current project\n\n### f docs review-pending\n\nRuns the bounded daemon-style review pass over pending session-doc packets stored in\nFlow state and records promotion decisions into queue state plus each packet's\n`promotion.json`.\n\nOptions:\n\n- `-n, --limit <N>`: Maximum number of pending entries to review (default: `25`).\n\n### f docs promote-session\n\nPreviews or applies promotion for a daemon-captured session-doc packet.\n\nBy default this is a dry run. It prints the chosen target under `.ai/docs/` and the\npromoted markdown note. Raw packet bundles stay in Flow state; only promoted\ndurable notes are written into the repo.\n\nOptions:\n\n- `<SESSION>`: Session id, session id prefix, or session key like `019d035d-...` or `019d035d-1773776290`\n- `--apply`: Write the promoted note immediately\n\n### f docs commit-pending\n\nCommits promoted session-doc notes when the git diff is isolated to doc-only files.\n\nThis command refuses to commit if the worktree contains unrelated changes.\n\nOptions:\n\n- `--dry-run`: Show the candidate files and commit message without staging or committing\n\n### f docs edit\n\nOpens a `.ai/docs` file in `$EDITOR`.\n\nExample:\n\n```bash\nf docs edit architecture\n```\n","docs/commands/domains.md":"# `f domains`\n\nManage shared local `*.localhost` routing with a single proxy on port `80`.\n\n## Why\n\nWithout this, each repo can start its own proxy and race for port `80`.\n`f domains` centralizes ownership with one engine at a time.\n\nState lives in:\n\n- `~/.config/flow/local-domains/routes.json`\n- runtime artifacts under `~/.config/flow/local-domains/`\n\n## Engines\n\n- `docker` (default): shared nginx container (`flow-local-domains-proxy`)\n- `native` (experimental): local C++ daemon (`domainsd-cpp`)\n\nSelect engine per command:\n\n```bash\nf domains --engine docker up\nf domains --engine native up\n```\n\nOr via env:\n\n```bash\nexport FLOW_DOMAINS_ENGINE=native\n```\n\n## Commands\n\n```bash\nf domains list\nf domains add linsa.localhost 127.0.0.1:3481\nf domains rm linsa.localhost\nf domains up\nf domains down\nf domains doctor\nf domains --engine native up\nf domains --engine native down\nf domains --engine native doctor\n```\n\n## Behavior\n\n- `f domains up`\n  - starts shared proxy on `:80`\n  - fails fast if another process/container owns port `80`\n- `f domains add`\n  - validates `host` ends with `.localhost`\n  - validates target format `host:port`\n  - refuses overwrite unless `--replace`\n  - reloads proxy if already running\n- `f domains doctor`\n  - shows route count\n  - shows current owner of port `80`\n  - highlights conflict ownership\n\n## Native notes (experimental)\n\n- Requires `clang++` to build `tools/domainsd-cpp/domainsd.cpp`.\n- Current scope is HTTP/1.1 host routing with WebSocket upgrade passthrough and upstream keepalive pooling.\n- Native daemon has built-in overload shedding (`503`) and upstream timeout protection (`504` on connect timeout).\n- HTTP/2/TLS are not implemented yet.\n- See `docs/local-domains-domainsd-cpp-spec.md`.\n- myflow-specific setup: `docs/myflow-localhost-runbook.md`.\n- Lifecycle integration: configure `[lifecycle.domains]` and use `f up` / `f down`.\n\n### macOS no-docker bind to :80\n\nIf native startup fails with `Permission denied` on `127.0.0.1:80`, install launchd socket mode once:\n\n```bash\ncd ~/code/flow\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nThen run:\n\n```bash\nf domains --engine native up\n```\n\nThis keeps routing fully native and avoids Docker overhead while still using port `80`.\n\n### Native tuning envs\n\nYou can tune the native daemon at startup via environment variables:\n\n```bash\nFLOW_DOMAINS_NATIVE_MAX_ACTIVE_CLIENTS=128\nFLOW_DOMAINS_NATIVE_UPSTREAM_CONNECT_TIMEOUT_MS=10000\nFLOW_DOMAINS_NATIVE_UPSTREAM_IO_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_CLIENT_IO_TIMEOUT_MS=30000\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_PER_KEY=8\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_TOTAL=256\nFLOW_DOMAINS_NATIVE_POOL_IDLE_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_POOL_MAX_AGE_MS=120000\n```\n## Recommended Repo Pattern\n\nInstead of per-repo docker proxy tasks:\n\n```toml\n[[tasks]]\nname = \"domains-up\"\ncommand = \"f domains add myapp.localhost 127.0.0.1:3000 && f domains up\"\n```\n\nThis keeps one proxy process for all repos and avoids accidental domain hijacking.\n","docs/commands/down.md":"# f down\n\nBring a project down using lifecycle conventions.\n\n## Quick Start\n\n```bash\n# Run lifecycle down task and optional domains teardown\nf down\n```\n\n## Behavior\n\n- Loads nearest `flow.toml` (or `--config` path).\n- Runs lifecycle task:\n  - `[lifecycle].down_task` when configured\n  - otherwise fallback: `down`\n- If no down task is found and `down_task` is not explicitly set, Flow falls back to killing all running Flow-managed processes for the current project (`f kill --all` behavior).\n- If `[lifecycle.domains]` is configured, optional teardown is applied:\n  - `remove_on_down = true` -> removes configured host route\n  - `stop_proxy_on_down = true` -> stops shared local domains proxy\n- On macOS launchd-managed native domains, stopping native proxy is handled by:\n  - `sudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh`\n\nIf neither a down task nor lifecycle domain teardown is configured, command fails with guidance.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`, searches upward when default is missing) |\n| `ARGS...` | Extra args passed to the selected lifecycle task |\n","docs/commands/env.md":"# f env\n\nSync project environment and manage environment variables.\n\n## Overview\n\nManage environment variables via cloud or local storage. Supports:\n- Project-level environment variables\n- Personal/global variables\n- Multiple environments (dev, staging, production)\n- Direct injection into commands\n- Touch ID gating for cloud reads and keychain-backed personal local reads on macOS\n- Client-side sealed project env sharing in the cloud\n\n## Storage Backends\n\n| Backend | Location | Config |\n|---------|----------|--------|\n| `cloud` | Cloud (myflow.sh) | Default, requires login |\n| `local` | `~/.config/flow/env-local/` | No account needed |\n\nCloud behavior:\n- Personal cloud envs use Flow's existing server-managed secret storage.\n- Project cloud envs are sealed client-side before upload and decrypted locally on read.\n- If a host deploy is configured with `env_source = \"cloud\"` plus a `service_token`, Flow keeps a compatibility plaintext mirror for those project keys until the host fetch path is upgraded.\n\nForce local backend:\n\n```bash\n# Via environment variable\nexport FLOW_ENV_BACKEND=local\n\n# Or in ~/.config/flow/config.ts\nexport default {\n  flow: { env: { backend: \"local\" } }\n}\n```\n\nIf the current project has an unambiguous deploy env source such as:\n\n```toml\n[host]\nenv_source = \"local\"\n```\n\nthen `f env` will also use the local backend automatically in that project.\n\n### Local Storage Structure\n\n```\n~/.config/flow/env-local/\n├── <project-name>/\n│   ├── production.env\n│   ├── staging.env\n│   └── dev.env\n└── personal/\n    └── production.env\n```\n\nStorage behavior:\n- Project-local envs are private `.env` files under `~/.config/flow/env-local/`.\n- On macOS, personal-local env values are stored in Keychain by default; `personal/production.env` keeps Flow-managed references, not raw secret values.\n- If `FLOW_ENV_LOCAL_PLAINTEXT=1` is set, Flow falls back to plaintext personal local storage.\n- Local env paths are written with owner-only permissions.\n\n## Quick Start\n\n```bash\n# Store a personal secret\nf env set API_KEY=sk-xxx\n\n# List variables (default action when logged in)\nf env\n\n# Run command with env vars injected\nf env run -- npm start\n\n# Get a value\nf env get API_KEY -f value\n```\n\n## Linsa/TestFlight Example\n\nFor project-scoped keys used by local + ship flows (for example, assistant keys):\n\n```bash\n# Store in project space (recommended for app/server env)\nf env project set -e dev OPENROUTER_API_KEY=sk-...\nf env project set -e production OPENROUTER_API_KEY=sk-...\nf env project set -e dev OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\nf env project set -e production OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\n```\n\nNotes:\n- Do not commit secrets to docs or repository files.\n- Use `f env get -e production -f value OPENROUTER_API_KEY` at runtime when a ship script needs to inject a missing key.\n\n## Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `login` | Authenticate with cloud |\n| `set` | Set a single env var |\n| `get` | Get specific env var(s) |\n| `list` | List env vars for this project |\n| `delete` | Delete env var(s) |\n| `pull` | Fetch env vars and write to .env |\n| `push` | Push local .env to cloud |\n| `apply` | Apply env vars to Cloudflare worker |\n| `setup` | Interactive wizard to push env vars |\n| `run` | Run command with env vars injected |\n| `status` | Show current auth status |\n| `keys` | Show configured env keys from flow.toml |\n| `sync` | Sync project settings and hub workflow |\n| `bootstrap` | Bootstrap Cloudflare secrets from flow.toml |\n| `unlock` | Unlock env reads (Touch ID on macOS) |\n\n---\n\n## Set\n\nStore a personal environment variable:\n\n```bash\n# Basic set\nf env set API_KEY=sk-xxx\n\n# Personal envs always use the production personal store\nf env set GITHUB_TOKEN=ghp_xxx\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--personal` | | Compatibility flag; `set` already targets personal envs |\n\n## Project Set\n\nStore a project-scoped environment variable:\n\n```bash\nf env project set -e dev DATABASE_URL=postgres://localhost/app\nf env project set -e production PUBLIC_API_BASE_URL=https://api.example.com\n```\n\nNotes:\n- Project cloud writes are sealed by default.\n- On a new device, the first project read/write auto-registers that device as a sealer.\n- If a key exists in cloud but was never shared to this device, Flow will ask you to re-save it from a device that already has access.\n\n---\n\n## Get\n\nRetrieve environment variables:\n\n```bash\n# Get as KEY=VALUE\nf env get API_KEY\n# API_KEY=sk-xxx\n\n# Get just the value\nf env get API_KEY -f value\n# sk-xxx\n\n# Get as JSON\nf env get API_KEY -f json\n# {\"API_KEY\": \"sk-xxx\"}\n\n# Get multiple\nf env get API_KEY DATABASE_URL\n\n# From personal store\nf env get --personal GITHUB_TOKEN -f value\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--format <FORMAT>` | `-f` | Output: `env`, `json`, or `value` (default: env) |\n| `--personal` | | Fetch from personal store |\n\n---\n\n## List\n\nList all environment variables:\n\n```bash\n# List production vars\nf env list\n\n# List staging vars\nf env list -e staging\n```\n\nOutput:\n```\nEnvironment: production\n\n  API_KEY          OpenAI API key\n  DATABASE_URL     PostgreSQL connection string\n  REDIS_URL        -\n```\n\n---\n\n## Run\n\nRun a command with environment variables injected:\n\n```bash\n# Inject all project env vars\nf env run -- npm start\n\n# Inject specific keys\nf env run -k API_KEY -k DATABASE_URL -- node server.js\n\n# From personal store\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n\n# Multiple keys from personal\nf env run --personal -k TELEGRAM_BOT_TOKEN -k TELEGRAM_API_ID -- ./start.sh\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--keys <KEYS>` | `-k` | Specific keys to inject (repeatable) |\n| `--personal` | | Fetch from personal store |\n\n### Examples\n\n```bash\n# Start app with production secrets\nf env run -- npm run start\n\n# Run with staging environment\nf env run -e staging -- npm run dev\n\n# Telegram bot with personal tokens\nf env run --personal -k TELEGRAM_BOT_TOKEN -- pnpm tsx src/bot.ts\n```\n\n---\n\n## Pull\n\nFetch all env vars and write to `.env` file:\n\n```bash\n# Write to .env\nf env pull\n\n# Pull staging vars\nf env pull -e staging\n```\n\nCreates or overwrites `.env` in current directory with all project variables.\n\n---\n\n## Push\n\nUpload local `.env` file to cloud:\n\n```bash\nf env push\n```\n\nReads `.env` from current directory and stores all variables.\n\n---\n\n## Setup\n\nInteractive wizard for pushing env vars:\n\n```bash\nf env setup\n```\n\nIf `[cloudflare] env_source = \"cloud\"` is set in `flow.toml`, this runs a guided\nprompt based on `env_keys`/`env_vars`. Otherwise it guides you through:\n1. Reading your `.env` file\n2. Selecting which keys to push\n3. Confirming before upload\n\n---\n\n## Delete\n\nRemove environment variables:\n\n```bash\n# Delete single key\nf env delete API_KEY\n\n# Delete multiple\nf env delete API_KEY DATABASE_URL\n```\n\n---\n\n## Login\n\nAuthenticate with cloud:\n\n```bash\nf env login\n```\n\nPrompts for API base URL and token. On macOS, the token is stored in Keychain\nand Flow uses Touch ID to unlock env reads.\n\n---\n\n## Status\n\nCheck authentication status:\n\n```bash\nf env status\n```\n\nOutput:\n```\ncloud Status\n  Token: stored in Keychain\n  API: https://myflow.sh\n  Project: myproject\n```\n\n---\n\n## Apply\n\nApply env vars to Cloudflare worker (uses `[cloudflare]` config in flow.toml):\n\n```bash\nf env apply\n```\n\nRequires `env_source = \"cloud\"` in your `[cloudflare]` config.\n\n## Keys\n\nShow env keys configured in `flow.toml` without printing values:\n\n```bash\nf env keys\n```\n\n## Unlock\n\nOn macOS, unlock env reads for the day (Touch ID):\n\n```bash\nf env unlock\n```\n\n---\n\n## Environments\n\nFlow supports three environments:\n\n| Environment | Description |\n|-------------|-------------|\n| `production` | Production secrets (default) |\n| `staging` | Staging/preview secrets |\n| `dev` | Development secrets |\n\nUse `-e` flag with project-scoped commands:\n\n```bash\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env list -e dev\nf env run -e staging -- npm run preview\n```\n\n---\n\n## Personal vs Project Variables\n\n| Type | Flag | Scope | Use Case |\n|------|------|-------|----------|\n| Project | (default for `get`, `list`, `run`, `project ...`) | Current project | API keys, database URLs |\n| Personal | `--personal` | Global/user | GitHub token, Telegram bot token |\n\nPersonal variables are tied to your user account, not a specific project.\n`f env set` writes personal vars. Use `f env project set` for project vars.\n\n```bash\n# Use a personal token in any project\nf env run --personal -k ANTHROPIC_API_KEY -- ./my-script\n```\n\n---\n\n## Env Space Overrides\n\nYou can store project envs under a named cloud space by configuring `env_space`\nand `env_space_kind` in `flow.toml`.\n\n```toml\n# flow.toml\nenv_space = \"nikiv\"\nenv_space_kind = \"personal\"\n```\n\n- `env_space_kind = \"project\"` (default) uses the project name.\n- `env_space_kind = \"personal\"` routes project envs to your personal space.\n\nThis affects `f env pull`, `f env push`, `f env list`, `f env apply`, and service\ntoken creation.\n\n---\n\n## Examples\n\n### Typical Workflow\n\n```bash\n# 1. Authenticate\nf env login\n\n# 2. Set up secrets\nf env project set DATABASE_URL=postgres://... -e production\nf env project set API_KEY=sk-xxx -e production\n\n# 3. Verify\nf env list\n\n# 4. Run app\nf env run -- npm start\n```\n\n### Staging Deploy\n\n```bash\n# Set staging secrets\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env project set API_KEY=sk-test-xxx -e staging\n\n# Test with staging env\nf env run -e staging -- npm run preview\n```\n\n### Personal Tokens for CLI Tools\n\n```bash\n# Store once\nf env set --personal GITHUB_TOKEN=ghp_xxx\nf env set --personal TELEGRAM_BOT_TOKEN=xxx\n\n# Use anywhere\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n```\n\n### In flow.toml Tasks\n\n```toml\n[tasks.start]\ncommand = \"f env run -- npm start\"\n\n[tasks.bot]\ncommand = \"f env run --personal -k TELEGRAM_BOT_TOKEN -- node bot.js\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Not authenticated\"\n\nRun `f env login` to authenticate with cloud.\n\n### \"No env vars found\"\n\nCheck environment name - default is `production`:\n```bash\nf env list -e staging  # Check staging instead\n```\n\n### Variables not injecting\n\nEnsure command comes after `--`:\n```bash\nf env run -k API_KEY -- npm start  # Correct\nf env run -k API_KEY npm start     # May not work\n```\n\n## See Also\n\n- [deploy](deploy.md) - Using env vars in deployments\n- [docs/how-to-use-env.md](../how-to-use-env.md) - Extended usage guide\n","docs/commands/ext.md":"# f ext\n\nManage Flow config extensions under `~/.flow/extensions`.\n\nThis is the extension/operator surface for the centralized Flow config system:\n\n- root config: `~/.flow/config.ts`\n- runtime helper: `~/.flow/runtime/flow-config.ts`\n- extension root: `~/.flow/extensions/<name>/`\n\nExtensions are loaded by `f config build` / `f config apply` when their names\nappear in `extensions: [...]` inside `~/.flow/config.ts`.\n\nFor backwards compatibility, `f ext <path>` still supports the older external\ndirectory import workflow into `<project>/ext/<name>`.\n\n## Commands\n\n### f ext list\n\nList built-in and filesystem extensions and whether they are enabled.\n\n```bash\nf ext list\nf ext list --json\n```\n\n### f ext doctor\n\nShow root-config wiring for extensions:\n\n- `~/.flow/config.ts`\n- `~/.flow/extensions`\n- `~/.flow/runtime/flow-config.ts`\n\nand the currently discoverable extensions.\n\n```bash\nf ext doctor\nf ext doctor --json\n```\n\n### f ext init\n\nCreate a new extension scaffold under `~/.flow/extensions/<name>/`.\n\nGenerated files:\n\n- `extension.ts`\n- `README.md`\n\nThe scaffold imports:\n\n- `defineFlowExtension` from `~/.flow/runtime/flow-config.ts`\n\n```bash\nf ext init my-extension\nf ext init my-extension --force\n```\n\n### f ext enable\n\nEnable an extension by name in `~/.flow/config.ts`.\n\n```bash\nf ext enable my-extension\n```\n\n### f ext disable\n\nDisable an extension by name in `~/.flow/config.ts`.\n\n```bash\nf ext disable my-extension\n```\n\n### f ext import\n\nExplicit legacy import form. Copies an external directory into `<project>/ext/`\nand adds `ext/` to `.gitignore`.\n\n```bash\nf ext import ~/some/external/repo\n```\n\nBare path form is still accepted:\n\n```bash\nf ext ~/some/external/repo\n```\n\n## Extension Shape\n\nAn extension file can export:\n\n```ts\nimport { defineFlowExtension } from \"../../runtime/flow-config\"\n\nexport default defineFlowExtension({\n  name: \"my-extension\",\n  flow: { ... },\n  lin: { ... },\n  ai: { ... },\n  hive: { ... }, // migration-only; Flow no longer applies ~/.hive/config.json\n  zerg: { ... },\n  generatedFiles: [\n    {\n      path: \"~/.some/target/file.json\",\n      content: \"{...}\",\n    },\n  ],\n  doctor: [\"human-readable check or note\"],\n})\n```\n\n## Notes\n\n- built-in extension currently supported: `lin-compat`\n- `f ext enable` rewrites `~/.flow/config.ts`\n- `f ext init` also ensures the runtime helper exists\n- generated file path collisions fail the build\n","docs/commands/failure.md":"# f failure\n\nInspect and copy recent task failures without manually selecting terminal text.\n\n## Usage\n\n```bash\nf failure\nf failure last\nf failure last --json\nf failure list\nf failure list --json --limit 10\nf failure copy\nf failure copy --format codex\nf failure copy --format codex --write-repo\nf failure copy --format claude\nf failure copy --format excerpt\nf failure copy --format json\n```\n\n## What It Reads\n\nFlow records failures to a stable latest pointer plus versioned history:\n\n```text\n~/.cache/flow/last-task-failure.json\n~/.cache/flow/task-failures/*.json\n```\n\nOverride the latest pointer with:\n\n```bash\nFLOW_FAILURE_BUNDLE_PATH=/tmp/last-task-failure.json\n```\n\n## Notes\n\n- `f failure` defaults to `f failure last`\n- `f failure copy` defaults to the latest failure in `prompt` format\n- `f failure copy --format codex` and `--format claude` render Flow-native repair prompts\n- `f failure copy --write-repo` writes the selected payload to `.ai/internal/failures/`\n- `f failure list --json` is intended for launcher consumers such as Alfred or Lin\n- Set `FLOW_NO_CLIPBOARD=1` to disable clipboard writes\n","docs/commands/fast.md":"# f fast\n\nRun AI tasks through the low-latency fast client path.\n\nThis command is optimized for hot-loop invocation and prefers `fai`/`ai-taskd-client` over full `f` task startup.\n\n## Usage\n\n```bash\nf fast ai:flow/noop\nf fast ai:flow/bench-cli -- --iterations 30\nf fast --root ~/code/flow ai:flow/dev-check\nf fast --no-cache ai:flow/dev-check\n```\n\n## Behavior\n\n1. Tries fast client dispatch (`fai`, local `target/.../ai-taskd-client`, or `ai-taskd-client` on PATH).\n2. If daemon is not running, starts `ai-taskd` and retries.\n3. Falls back to direct daemon dispatch if no fast client binary is found.\n\n## Options\n\n- `--root <PATH>`: root directory for `.ai/tasks` discovery (default `.`)\n- `--no-cache`: disable cached binary execution and use direct Moon run\n- `TASK`: required AI selector like `ai:flow/dev-check`\n- trailing args after `--` are passed to the task\n\n## Notes\n\n- `f fast` is intentionally for `ai:*` selectors only.\n- Install `fai` for best latency:\n\n```bash\nf install-ai-fast-client\nf tasks daemon start\nf fast ai:flow/noop\n```\n\nFor pooled burst execution and timings, use `fai` directly:\n\n```bash\nfai --timings ai:flow/noop\nprintf 'ai:flow/noop\\nai:flow/noop\\n' | fai --batch-stdin --timings\n```\n","docs/commands/global.md":"# f global\n\nRun tasks from your global flow config (`~/.config/flow/flow.toml`).\n\n## Quick Start\n\n```bash\n# List global tasks\nf global --list\nf global list\n\n# Run a global task from anywhere\nf global repos-clone-safari\nf global run repos-clone-safari\n\n# Match a query against global tasks\nf global match \"clone safari repo\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `<TASK>` | | Global task name (omit to list) |\n| `list` | | List global tasks |\n| `run <TASK>` | | Run a global task |\n| `match <QUERY>` | | Match a query against global tasks |\n| `--list` | `-l` | List global tasks |\n| `-- <ARGS...>` | | Pass extra args to the task |\n\n## Examples\n\n```bash\nf global repos-clone-safari https://github.com/0xPlaygrounds/rig\n```\n","docs/commands/install.md":"# f install\n\nInstall a CLI/tool binary into your PATH.\n\nDefault backend behavior (`--backend auto`):\n1. Flow registry (`myflow.sh` or `--registry`)\n2. GitHub releases via `parm`\n3. flox package install\n\n## Usage\n\n```bash\nf install <name>\n```\n\n## Options\n\n- `--registry <URL>`: registry base URL (defaults to `FLOW_REGISTRY_URL`).\n- `--backend <auto|registry|parm|flox>`: choose install backend explicitly.\n- `--version <VERSION>`: install a specific version (defaults to latest).\n- `--bin <NAME>`: binary name to install (defaults to manifest default or package name).\n- `--bin-dir <PATH>`: install directory (defaults to `~/bin`).\n- `--force`: overwrite an existing binary.\n- `--no-verify`: skip checksum verification.\n\n## Auto backend notes\n\n- `f install rise` can resolve through `parm` using built-in owner/repo mapping.\n- Built-in aliases:\n  - `f install seqd` resolves registry package `seq` with binary `seqd`.\n  - `f install lin` resolves registry package `flow` with binary `lin`.\n- If a package name is ambiguous for `parm`, set `FLOW_INSTALL_OWNER` (env or Flow personal env store) or pass `owner/repo` directly.\n\n## Bootstrap from installer\n\nThe hosted installer can bootstrap core tools after installing flow:\n\n- `FLOW_BOOTSTRAP_TOOLS=\"rise seq seqd\"` (default) installs those with `f install ... --backend auto`.\n- `FLOW_BOOTSTRAP_TOOLS=0` disables this.\n- `FLOW_BOOTSTRAP_INSTALL_PARM=1` (default) attempts to install `parm` for robust GitHub fallback.\n\n## Registry layout\n\nThe registry must expose:\n\n- `GET /packages/<name>/latest.json`\n- `GET /packages/<name>/<version>/manifest.json`\n- `GET /packages/<name>/<version>/<target>/<bin>`\n\n## Example\n\n```bash\nFLOW_REGISTRY_URL=https://myflow.sh f install flow\n```\n\n```bash\nf install rise\n```\n","docs/commands/invariants.md":"# f invariants\n\nValidate project invariants declared in `flow.toml`.\n\nThis command checks the `[invariants]` section and reports violations in changed code.\n\n## Usage\n\n```bash\n# Check all local changes vs HEAD\nf invariants\n\n# Check only staged changes\nf invariants --staged\n```\n\n## What It Checks\n\n1. `forbidden`: disallowed patterns in added diff lines.\n2. `deps.approved`: unapproved dependencies in `package.json` sections (`dependencies`, `devDependencies`, `peerDependencies`).\n3. `files.max_lines`: changed files exceeding the configured line limit.\n\n## Modes\n\nSet in `flow.toml`:\n\n- `mode = \"off\"`: disable checks.\n- `mode = \"warn\"`: print findings, exit success.\n- `mode = \"block\"`: fail command when blocking findings exist.\n\n## Example `flow.toml`\n\n```toml\n[invariants]\nmode = \"block\"\narchitecture_style = \"layered monorepo, event-driven core\"\nnon_negotiable = [\n  \"no inline imports\",\n  \"no any types unless justified\",\n]\nforbidden = [\n  \"git add -A\",\n  \"git reset --hard\",\n]\n\n[invariants.terminology]\n\"pi-ai\" = \"LLM abstraction layer\"\n\"pi-agent\" = \"stateful agent runtime\"\n\n[invariants.deps]\npolicy = \"approval_required\"\napproved = [\"@sinclair/typebox\", \"@reatom/core\"]\n\n[invariants.files]\nmax_lines = 300\n```\n\n## Commit Integration\n\n`f commit` runs the invariant gate during commit-with-check flow.\n\n- In `mode = \"block\"`, commits are blocked on invariant warnings/critical findings.\n- Invariant context and findings are injected into AI review prompts.\n\n","docs/commands/jj.md":"# jj\n\nFlow wraps common Jujutsu (jj) workflows so you can stay in jj while remaining fully Git-compatible.\n\n## Quick start\n\n```bash\n# Inspect workspace + home-branch state\nf status\n\n# Initialize jj (colocated with git when .git exists)\nf jj init\n\n# Create a feature bookmark and track origin\nf jj bookmark create feature-x --track\n\n# Fetch + rebase onto main + push bookmark\nf jj sync --bookmark feature-x\n```\n\n## Commands\n\n- `f status` — Show workflow-aware JJ status (workspace, home branch, leaf branches, working-copy summary, and next-step hints)\n- `f jj status` — Show raw `jj st`\n- `f jj fetch` — `jj git fetch`\n- `f jj rebase --dest <branch>` — Rebase onto `jj.default_branch` (or main/master)\n- `f jj push --bookmark <name>` — Push a single bookmark\n- `f jj push --all` — Push all bookmarks\n- `f jj sync --bookmark <name>` — Fetch, rebase, then push bookmark\n- `f jj workspace add <name> [--path <dir>] [--rev <rev>]` — Create a workspace (optionally anchored to a revision)\n- `f jj workspace lane <name> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create an isolated parallel lane from trunk defaults\n- `f jj workspace review <branch> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create or reuse a stable JJ review workspace for a branch without touching the current checkout\n- `f jj workspace list` — List workspaces\n- `f jj bookmark create <name> [--rev <rev>] [--track]` — Create bookmark\n- `f jj bookmark track <name> [--remote <remote>]` — Track remote bookmark\n\n## Status-first workflow\n\nUse `f status` before branch, workspace, commit, or publish operations.\n\nIt is the fast way to answer:\n\n- which workspace am I in?\n- am I on the long-lived home branch or a branch-specific leaf?\n- what review or codex branches currently sit on top of the home branch?\n- is the working copy clean enough to mutate safely?\n\nExample:\n\n```bash\ncd ~/code/org/project\nf status\n```\n\nUse `f jj status` only when you want the raw Jujutsu working-copy view.\n\n## Parallel lanes (no interleaving)\n\nUse lanes when you want multiple active tasks in one repo without stash/pop churn:\n\n```bash\n# In your current repo, create isolated lanes anchored from trunk\nf jj workspace lane fix-otp\nf jj workspace lane testflight\n\n# Work each lane independently\ncd ~/.jj/workspaces/<repo>/fix-otp\njj st\n```\n\n`f jj workspace lane` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. chooses base as `<default_branch>@<remote>` when tracked (fallback: `<default_branch>`)\n3. creates a dedicated workspace with its own `@` working-copy commit\n\n## Review workspaces\n\nUse a review workspace when you want an isolated JJ working copy for a review branch without\ntouching the current repo checkout:\n\n```bash\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/<repo>/review-alice-feature\njj st\n```\n\n`f jj workspace review` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. reuses the existing review workspace when present\n3. otherwise anchors the workspace at the local branch commit, then the remote branch commit, then trunk\n4. prints the stable workspace path plus the JJ bookmark command to publish later\n\nImportant:\n\n- The review workspace is JJ-native. Use `jj` or `f jj` inside it.\n- In colocated repos, plain `git` still points at the main checkout, so this command intentionally does not run `flow switch` for you.\n\n## Config\n\nAdd to `flow.toml`:\n\n```toml\n[git]\nremote = \"myflow-i\"  # optional preferred writable remote\n\n[jj]\ndefault_branch = \"main\"\nhome_branch = \"alice\" # optional long-lived personal integration branch\nremote = \"origin\"     # optional legacy fallback if [git].remote is unset\nauto_track = true\n```\n\nThis keeps jj aligned with Git remotes while you work locally in jj.\n\n## Home-branch model\n\nIf you keep a long-lived personal branch on top of trunk, set `jj.home_branch` and treat it as\nyour integration branch.\n\nWhen the current branch matches that home branch, plain `f sync` also switches into home-branch\nmode and syncs `origin/<default-branch>` into it instead of using the normal tracking pull.\n\nThen use short-lived `review/*` or `codex/*` branches on top of that home branch for task-specific\nwork. `f status` is optimized to make that shape visible.\n\nRecommended flow:\n\n```bash\n# Default checkout stays on your home branch\ncd ~/code/org/project\nf status\n\n# Branch-specific work happens in isolated workspaces\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/project/review-alice-feature\nf status\n```\n\nSee also:\n\n- [`jj-review-workspaces.md`](../jj-review-workspaces.md)\n- [`jj-home-branch-workflow.md`](../jj-home-branch-workflow.md)\n","docs/commands/migrate.md":"# f migrate\n\nMove or copy a project folder to a new location, preserving symlinks and AI sessions.\n\n## Overview\n\nRelocates a project directory and automatically migrates Claude and Codex AI sessions so conversation history follows the project. Also relinks any `~/bin` symlinks that pointed into the old path (move only).\n\n## Quick Start\n\n```bash\n# Move current directory into ~/code/lang/cpp/stream\ncd ~/code/lang/cpp/stream\nf migrate code stream\n\n# Move current directory to an arbitrary path\nf migrate ~/code/stream\n\n# Move a specific source to a target\nf migrate ~/code/lang/cpp/stream ~/code/stream\n\n# Preview what would happen (no changes)\nf migrate --dry-run code stream\n\n# Copy instead of move (keeps original)\nf migrate --copy code stream\n```\n\n## Your case\n\nTo migrate `~/code/lang/cpp/stream` to `~/code/stream`:\n\n```bash\ncd ~/code/lang/cpp/stream\nf migrate code stream\n```\n\nOr without `cd`:\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\nPreview first with `--dry-run`:\n\n```bash\nf migrate --dry-run ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Usage Forms\n\n### `f migrate code <relative>`\n\nMoves the current directory into `~/code/<relative>`. This is the most common form.\n\n```bash\ncd ~/old/location/myproject\nf migrate code myproject          # -> ~/code/myproject\nf migrate code lang/rust/mylib    # -> ~/code/lang/rust/mylib\n```\n\n### `f migrate <target>`\n\nMoves the current directory to `<target>` (any absolute or relative path).\n\n```bash\ncd ~/old/location/myproject\nf migrate ~/code/myproject\n```\n\n### `f migrate <source> <target>`\n\nMoves `<source>` to `<target>` without needing to `cd` first.\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--copy` | `-c` | Copy instead of move (keeps the original intact) |\n| `--dry-run` | | Show what would change without writing anything |\n| `--skip-claude` | | Skip migrating Claude Code sessions |\n| `--skip-codex` | | Skip migrating Codex sessions |\n\n## What Happens\n\n### Step 1: Move or copy the folder\n\nThe project directory is moved (or copied with `--copy`) to the target path. Parent directories are created automatically. Cross-device moves are handled transparently (copy + delete).\n\n### Step 2: Relink ~/bin symlinks (move only)\n\nAny symlinks in `~/bin` that pointed into the old path are updated to point to the new location. Skipped when using `--copy`.\n\n### Step 3: Migrate AI sessions\n\nClaude and Codex store project sessions keyed by filesystem path. Migrate updates these so conversation history is preserved at the new location.\n\n- **Claude sessions**: Project directories under `~/.claude/projects/` are renamed from the old path-based key to the new one.\n- **Codex sessions**: Legacy project directories are renamed, and `.jsonl` session files referencing the old path are updated in-place.\n\nA summary is printed showing how many session dirs/files were migrated.\n\n## Examples\n\n```bash\n# Move project into ~/code, nested path\ncd ~/downloads/cool-project\nf migrate code tools/cool-project\n\n# Copy a project (keeps original)\nf migrate --copy ~/code/app ~/backup/app\n\n# Dry run to preview\nf migrate --dry-run code stream\n\n# Move without migrating AI sessions\nf migrate --skip-claude --skip-codex ~/old/path ~/new/path\n\n# Move and only migrate Claude (skip Codex)\nf migrate --skip-codex code myproject\n```\n\n## Troubleshooting\n\n### \"Destination already exists\"\n\nThe target path must not exist. Remove or rename the existing directory first, or choose a different target.\n\n### \"Source and destination are the same path\"\n\nBoth paths resolve to the same location. Double-check your arguments.\n\n### Session migration warnings\n\nAfter a move, you may see warnings like:\n\n```\nWARN Claude session dir still present: ...\nWARN Codex sessions still reference the old path:\n  /path/to/file.jsonl\n```\n\nThese mean some sessions couldn't be fully migrated. You can manually inspect or delete the referenced files.\n\n## See Also\n\n- [repos](repos.md) - Clone repositories into structured layout\n","docs/commands/new.md":"# f new\n\nCreate a new project from a local starter template under `~/new`.\n\n## Overview\n\n`f new` copies a directory from `~/new/<template>` into a destination path.\n\nThis is the native Flow way to work with local starters you keep in `~/new`.\n\n## Usage\n\n```bash\nf new [template] [path]\n```\n\n- `template`: folder name inside `~/new` (for example `app`, `docs`, `web`)\n- `path`: destination path (optional)\n\nIf `template` is omitted, Flow opens an `fzf` picker from templates in `~/new`.\n\n## Path Resolution Rules\n\nFlow resolves the destination path like this:\n\n```bash\nf new app          # -> ./app\nf new app zerg     # -> ~/code/zerg\nf new app ./xn     # -> ./xn\nf new app ~/xn     # -> ~/xn\n```\n\nNotes:\n- Plain names (no `./`, `../`, `/`, `~`) are treated as `~/code/<name>`.\n- Use `~/...` or absolute paths for custom locations outside `~/code`.\n\n## Dry Run\n\nPreview copy behavior without writing files:\n\n```bash\nf new app ~/xn --dry-run\n```\n\n## Starter Workflow\n\n1. Create or update starter in `~/new/<template>`.\n2. Generate a new project with `f new <template> <target>`.\n3. Enter the new project and run its setup/dev tasks with Flow.\n\nExample:\n\n```bash\nf new app ~/xn\ncd ~/xn\nf tasks\n```\n\n## Common Errors\n\n- `Template not found`: `~/new/<template>` does not exist.\n- `Destination already exists`: remove/rename target path or choose a new destination.\n","docs/commands/pr.md":"# f pr\n\nCreate or open GitHub pull requests, edit PR text locally, and pull review feedback.\n\n## Quick Start\n\n```bash\n# Create/update PR from current changes (default base: main)\nf pr \"assistant improvements\"\n\n# Open current branch PR in browser\nf pr open\n\n# Edit PR title/body in local markdown and sync on save\nf pr open edit\n\n# Pull actionable review feedback for current PR\nf pr feedback\n\n# Pull feedback for specific PR and store as local todos\nf pr feedback 8 --todo\nf pr feedback https://github.com/owner/repo/pull/8 --todo\n\n# Full inline diff/review context is now the default\nf pr feedback 8\n\n# Use terse terminal output if needed\nf pr feedback 8 --compact\n```\n\n## Feedback Workflow\n\n`f pr feedback` fetches:\n\n- PR reviews (`/pulls/<n>/reviews`)\n- Inline review comments (`/pulls/<n>/comments`)\n- Top-level PR comments (`/issues/<n>/comments`)\n\nIt then:\n\n1. Prints an actionable list in terminal with inline review state and diff hunk context by default.\n2. Writes a markdown snapshot to `.ai/reviews/pr-feedback-<pr>.md`.\n3. Writes a machine-readable JSON snapshot to `.ai/reviews/pr-feedback-<pr>.json`.\n4. Writes a human review plan to `~/docs/plan/review/<repo>-pr-<pr>-feedback.md`.\n5. Writes a PR-local execution artifact to `~/docs/plan/review/<repo>-pr-<pr>-review-rules.md`.\n6. Writes a Kit system prompt to `~/docs/plan/review/<repo>-pr-<pr>-kit-system.md`.\n7. Optionally (`--todo`) records feedback into `.ai/todos/todos.json` with dedupe via external refs.\n\nThe review plan includes ready-to-run `kit` commands for:\n\n- deterministic repo review via `kit review`\n- preventative lint/review rule synthesis from the fetched GitHub feedback set\n\nThe generated `*-review-rules.md` artifact contains the per-item resolution loop,\nprompt template, required response sections, and Kit-upgrade decision order so\nthe workflow can be reopened without extra instructions.\n\n## Notes\n\n- If no selector is passed, Flow resolves the PR from the current branch.\n- `f pr feedback --todo` is safe to re-run; existing feedback refs are not duplicated.\n- `f pr feedback` is full-context by default. Use `--compact` if you want the older terse terminal view.\n- `f pr feedback` now emits a Kit-ready handoff, so the same feedback set can drive a future review bot instead of staying trapped in GitHub comments.\n- `f pr open edit` remains the quickest path to tweak PR title/body from local editor.\n","docs/commands/publish.md":"# f publish\n\nPublish projects to GitHub.\n\n## Overview\n\nCreates a new GitHub repository and pushes the current project. Automatically infers the repo name from the folder name and handles both new repos and existing ones.\n\n## Quick Start\n\n```bash\n# Interactive mode - prompts for name and visibility\nf publish\n\n# Skip prompts, use folder name, default to private\nf publish -y\n\n# Create public repo\nf publish --public\n\n# Create with specific name\nf publish --name my-awesome-project\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--name <NAME>` | `-n` | Repository name (defaults to folder name) |\n| `--public` | | Create as public repository |\n| `--private` | | Create as private repository |\n| `--description <DESC>` | `-d` | Repository description |\n| `--yes` | `-y` | Skip prompts, use defaults (private, folder name) |\n\n## Prerequisites\n\n- [GitHub CLI](https://cli.github.com/) installed (`gh`)\n- Authenticated with `gh auth login`\n\n## Usage\n\n### Interactive Mode\n\nWithout flags, prompts for configuration:\n\n```bash\n$ f publish\n\nRepository name [my-project]:\nVisibility (public/private) [private]: public\n\nCreate repository:\n  Name: username/my-project\n  Visibility: public\n\nProceed? [Y/n]:\n```\n\n### Non-Interactive Mode\n\n```bash\n# Use all defaults (private, folder name as repo name)\nf publish -y\n\n# Public repo with defaults\nf publish -y --public\n\n# Specific name and description\nf publish -n cool-tool -d \"A cool CLI tool\" --public\n```\n\n### Existing Repositories\n\nIf the repository already exists on GitHub:\n\n1. Checks current visibility\n2. Updates visibility if different from requested\n3. Adds origin remote if missing\n4. Pushes current branch\n\n```bash\n$ f publish --public\nRepository username/my-repo already exists (private).\nUpdating visibility to public...\n✓ Updated to public\n\n✓ https://github.com/username/my-repo\n```\n\n## What Happens\n\n1. **Check gh CLI** - Verifies GitHub CLI is installed\n2. **Check authentication** - Ensures you're logged in to GitHub\n3. **Get username** - Fetches your GitHub username\n4. **Determine repo name** - Uses `--name`, folder name, or prompts\n5. **Determine visibility** - Uses `--public`/`--private` or prompts\n6. **Check if exists** - If repo exists, updates visibility if needed\n7. **Initialize git** - If not a git repo, runs `git init`\n8. **Create initial commit** - If no commits, stages all and commits\n9. **Create repository** - Uses `gh repo create` with `--source=. --push`\n10. **Output URL** - Prints the GitHub URL\n\n## Examples\n\n### Quick Publish New Project\n\n```bash\ncd my-new-project\nf publish -y --public\n# ✓ Published to https://github.com/username/my-new-project\n```\n\n### Publish with Description\n\n```bash\nf publish -n api-server -d \"REST API for my app\" --private\n```\n\n### Update Existing Repo Visibility\n\n```bash\n# Repo exists as private, make it public\nf publish --public\n# Repository username/my-repo already exists (private).\n# Updating visibility to public...\n# ✓ Updated to public\n```\n\n### In Scripts/CI\n\n```bash\n#!/bin/bash\ncd /path/to/project\nf publish -y --public -n release-candidate\n```\n\n## Troubleshooting\n\n### \"GitHub CLI (gh) is not installed\"\n\nInstall from https://cli.github.com:\n\n```bash\n# macOS\nbrew install gh\n\n# Linux\nsudo apt install gh  # or equivalent\n```\n\n### \"GitHub authentication required\"\n\nRun `gh auth login` and follow the prompts.\n\n### \"Could not determine GitHub username\"\n\nEnsure you're authenticated: `gh auth status`\n\n### Repository exists but can't update visibility\n\nSome visibility changes may require specific permissions or GitHub plan features.\n\n## See Also\n\n- [deploy](deploy.md) - Deploy after publishing\n- [upstream](upstream.md) - Managing forks\n","docs/commands/readme.md":"# Flow Commands Reference\n\nComplete documentation for all `f` (flow) commands.\n\n## Quick Reference\n\n| Command | Description |\n|---------|-------------|\n| [`deploy`](deploy.md) | Deploy to Linux hosts, Cloudflare Workers, or Railway |\n| [`release`](release.md) | Publish a release to registry or GitHub |\n| [`publish`](publish.md) | Publish project to GitHub |\n| [`install`](install.md) | Install a CLI/tool via registry, parm, or flox |\n| [`clone`](clone.md) | Clone repositories with git-like destination behavior |\n| [`repos`](repos.md) | Clone repositories into ~/repos |\n| [`new`](new.md) | Create a project from a local template in ~/new |\n| [`commit`](commit.md) | AI-powered commit with code review |\n| [`pr`](pr.md) | Create/open PRs and ingest GitHub feedback |\n| [`upstream`](upstream.md) | Manage upstream fork workflow |\n| [`env`](env.md) | Sync project environment and manage env vars |\n| [`config`](config.md) | Build and apply centralized Flow config outputs |\n| [`ext`](ext.md) | Manage Flow config extensions |\n| [`invariants`](invariants.md) | Validate project invariants from `flow.toml` |\n| [`fast`](fast.md) | Low-latency AI task invocation via fast client |\n| [`up`](up.md) | Bring a project up with lifecycle conventions |\n| [`down`](down.md) | Bring a project down with lifecycle conventions |\n| [`domains`](domains.md) | Shared local `*.localhost` route manager on port 80 |\n| [`tasks`](tasks.md) | List and run project tasks |\n| [`failure`](failure.md) | Inspect and copy recent task failures |\n| [`global`](global.md) | Run tasks from global flow config |\n| [`setup`](setup.md) | Print aliases or run setup task |\n| [`ai`](ai.md) | Manage AI coding sessions (Claude + Codex) |\n| [`daemon`](daemon.md) | Manage background daemons |\n| [`parallel`](parallel.md) | Run tasks in parallel |\n| [`docs`](docs.md) | Manage auto-generated documentation |\n| [`web`](web.md) | Open the Flow web UI for a project |\n| [`url`](url.md) | Inspect or crawl URLs into compact AI-friendly summaries |\n\n## Getting Started\n\n```bash\n# Show all commands\nf --help\n\n# Get help for a specific command\nf deploy --help\nf commit --help\n```\n\n## Command Categories\n\n### Deployment\n\n- **[deploy](deploy.md)** - Deploy to hosts and cloud platforms\n- **[release](release.md)** - Publish releases to registries\n- **[publish](publish.md)** - Publish project to GitHub\n\n### Version Control\n\n- **[commit](commit.md)** - AI-powered commits with review\n- **[pr](pr.md)** - PR creation/editing plus review feedback ingestion\n- **[clone](clone.md)** - Clone with git-like destination behavior\n- **[repos](repos.md)** - Clone repos into a structured directory\n- **[upstream](upstream.md)** - Fork management and sync\n- **[fixup](fixup.md)** - Fix common TOML syntax errors\n\n### Task Management\n\n- **[tasks](tasks.md)** - List project tasks\n- **[failure](failure.md)** - Inspect and copy recent task failures\n- **[fast](fast.md)** - Run AI tasks through the low-latency fast client path\n- **[up](up.md)** - Start project lifecycle (`up`/`dev`) with optional domains setup\n- **[down](down.md)** - Stop project lifecycle with optional domains teardown\n- **[global](global.md)** - Run tasks from ~/.config/flow/flow.toml\n- **[setup](setup.md)** - Print aliases or run setup task\n- **[run](run.md)** - Run a specific task\n- **[parallel](parallel.md)** - Run tasks in parallel\n- **[rerun](rerun.md)** - Re-run last task\n- **[search](search.md)** - Fuzzy search global commands\n\n### Process Management\n\n- **[ps](ps.md)** - List running flow processes\n- **[kill](kill.md)** - Stop running processes\n- **[logs](logs.md)** - View task logs\n- **[daemon](daemon.md)** - Manage background daemons\n\n### AI & Development\n\n- **[ai](ai.md)** - Manage AI coding sessions\n- **[url](url.md)** - Inspect or crawl URLs into compact summaries for AI use\n- **[agent](agent.md)** - Invoke AI subagents\n- **[match](match.md)** - Match natural language to tasks\n- **[sessions](sessions.md)** - Search AI sessions across projects\n\n### Environment & Configuration\n\n- **[env](env.md)** - Manage environment variables\n- **[config](config.md)** - Build/apply the centralized Flow config snapshot\n- **[ext](ext.md)** - Scaffold, enable, disable, and inspect Flow config extensions\n- **[invariants](invariants.md)** - Validate invariant policies in `flow.toml`\n- **[domains](domains.md)** - Shared local domain proxy ownership and route management\n- **[init](init.md)** - Scaffold a new flow.toml\n- **[doctor](doctor.md)** - Verify tools and integrations\n\n### Project Management\n\n- **[new](new.md)** - Create a project from a local starter in `~/new`\n- **[projects](projects.md)** - List registered projects\n- **[active](active.md)** - Show or set active project\n- **[hub](hub.md)** - Ensure hub daemon is running\n\n### Documentation\n\n- **[docs](docs.md)** - Manage auto-generated documentation\n- **[commits](commits.md)** - Browse commits with AI metadata\n\n### Legacy Compatibility\n\n- **[recipe](recipe.md)** - Legacy recipe command (hidden; prefer `tasks` + `.ai/tasks/*.mbt`)\n\n### Other\n\n- **[skills](skills.md)** - Manage Codex skills\n- **[install](install.md)** - Install binaries via registry/parm/flox\n- **[db](db.md)** - Manage databases and providers\n- **[tools](tools.md)** - Manage AI tools\n- **[notify](notify.md)** - Send proposal notifications\n- **[server](server.md)** - Start HTTP server for logs\n\n## Global Options\n\n```bash\n-h, --help     Print help\n-V, --version  Print version\n```\n\n## Configuration\n\nFlow uses `flow.toml` for project configuration. See [flow.toml reference](../flow-toml.md) for full documentation.\n\n## See Also\n\n- [Getting Started Guide](../getting-started.md)\n- [flow.toml Reference](../flow-toml.md)\n","docs/commands/recipe.md":"# f recipe\n\nLegacy compatibility command.\n\nPreferred model:\n\n- Put shell tasks in `flow.toml` under `[[tasks]]`.\n- Put AI/native tasks in `.ai/tasks/*.mbt`.\n- Run via `f <task>` or `f ai:<selector>`.\n\n`f recipe` remains for older repos that still use `.ai/recipes`.\n\n## Usage\n\n```bash\nf recipe list          # legacy listing\nf recipe run <selector> # legacy execution\n```\n\n## Options\n\n- `--scope <project|global|all>`: recipe source scope (default `all`)\n- `--global-dir <PATH>`: override global recipes directory\n- `--cwd <PATH>` (run only): working directory for execution\n- `--dry-run` (run only): print command without executing\n\n## Legacy Recipe Locations\n\n- Project recipes: `.ai/recipes/project` (fallback `.ai/recipes`).\n- Global recipes: `~/.config/flow/recipes`.\n\nSupported extensions: `.md`, `.markdown`, `.mbt`\n\nMoonBit recipe metadata is optional and can be declared in top comment lines:\n\n```mbt\n// title: My Fast Recipe\n// description: Run a moonbit action quickly\n// tags: [moonbit, fast]\n```\n\n## Migration\n\n```bash\n# Old\nf recipe run project:my-recipe\n\n# New\nf tasks init-ai\nf ai:my-task\n```\n","docs/commands/release.md":"# f release\n\nRelease a project based on `flow.toml` defaults or explicit subcommands.\n\n## Usage\n\n```bash\nf release\nf release registry\nf release gh\n```\n\n## Registry releases\n\n```bash\nf release registry\n```\n\n### flow.toml\n\n```toml\n[release]\ndefault = \"registry\"\nversioning = \"calver\"\n\n[release.registry]\nurl = \"https://myflow.sh\"\npackage = \"flow\"\nbins = [\"flow\", \"f\", \"lin\"]\ndefault_bin = \"flow\"\ntoken_env = \"FLOW_REGISTRY_TOKEN\"\nlatest = true\n```\n\n### Options\n\n- `--version <VERSION>`: publish a specific version.\n- `--registry <URL>`: override the registry base URL.\n- `--bin <NAME>`: override the binaries to upload (repeatable).\n- `--no-build`: skip building binaries.\n- `--latest` / `--no-latest`: control latest pointer updates.\n\n## GitHub releases\n\n```bash\nf release gh\n```\n","docs/commands/repos.md":"# f repos\n\nClone repositories into a structured local directory or create new ones.\n\nIf you want standard `git clone` destination behavior, use [`f clone`](clone.md) instead.\n\n## Overview\n\n`f repos clone` clones GitHub repositories into `~/repos/<owner>/<repo>` using SSH URLs. By default it does a shallow clone for speed, then fetches full history in the background. It always sets up an `upstream` remote and local tracking branch unless you pass `--no-upstream`. Clone-time bootstrap is local-only: it does not create or push a private mirror repo. If the target checkout already exists, Flow reports that and exits without re-bootstrapping or reopening the repo.\n`f repos create` creates a GitHub repository from the current folder and pushes it.\n\nBy default, Flow treats `~/repos` as an immutable managed root. Use `FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1` if you need to point `--root` somewhere else.\n\n## Quick Start\n\n```bash\n# Clone a GitHub repo into ~/repos/<owner>/<repo>\nf repos clone https://github.com/owner/repo\n\n# Short form\nf repos clone owner/repo\n\n# Skip upstream auto-setup\nf repos clone owner/repo --no-upstream\n\n# Full clone (skip background history fetch)\nf repos clone owner/repo --full\n\n# Create a new repo from the current folder (prompts for name/visibility)\nf repos create\n```\n\n## Options\n\n### f repos clone\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `<URL>` | | Repository URL or `owner/repo` |\n| `--root <PATH>` | | Root directory for clones (default: `~/repos`, override requires `FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1`) |\n| `--full` | | Full clone (skip shallow clone + background history fetch) |\n| `--no-upstream` | | Skip upstream setup |\n| `--upstream-url <URL>` | `-u` | Upstream URL override (skips GitHub lookup) |\n| `--no-home-branch-bootstrap` | | Skip local nikiv home-branch setup after clone |\n\n### f repos create\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--name <NAME>` | `-n` | Repository name (defaults to current folder) |\n| `--public` | | Create as public repository |\n| `--private` | | Create as private repository |\n| `--description <TEXT>` | `-d` | Description for the repository |\n| `--yes` | `-y` | Skip confirmation prompts |\n\n## Upstream Automation\n\nFlow will:\n\n1. Query GitHub via `gh api repos/<owner>/<repo>`\n2. Detect the parent repository\n3. Run `f upstream setup --url <parent>` inside the cloned repo\n\nIf the repo is not a fork (or `gh` is unavailable), flow sets `upstream` to the `origin` URL.\n\n## Background History Fetch\n\nWhen cloning in fast mode (default), flow spawns a background fetch:\n\n- `git fetch --unshallow --tags origin`\n- `git fetch --tags upstream` (if upstream was configured)\n\n## Private Mirror Setup\n\n`f repos clone` no longer creates or pushes the `fork` / `*-i` private mirror as part of clone.\n\nIf you want Flow to create or repair the private mirror workflow for an existing repo, run:\n\n```bash\nf repos bootstrap-home-branch --path ~/repos/<owner>/<repo>\n```\n\n## Examples\n\n```bash\n# Clone into a custom root (requires override)\nFLOW_REPOS_ALLOW_ROOT_OVERRIDE=1 f repos clone https://github.com/owner/repo --root ~/work/repos\n\n# Override upstream manually\nf repos clone https://github.com/your-user/repo -u git@github.com:upstream-org/repo.git\n```\n","docs/commands/reviews-todo.md":"# f reviews-todo\n\nManage deferred deep-review todos for queued commits.\n\nThis command is a workflow wrapper over `f commit-queue` for the fast-commit + deep-Codex-review loop.\n\n## Quick Start\n\n```bash\n# List pending deep-review todos (queued commits)\nf reviews-todo list\n\n# Run Codex deep review for all queued commits\nf reviews-todo codex --all\n\n# Inspect one queued review todo\nf reviews-todo show <commit-sha>\n\n# Approve all queued commits after issues are addressed\nf reviews-todo approve-all\n```\n\n## Why use this\n\n- Keep `f commit` fast.\n- Batch expensive Codex reviews later.\n- Keep one place to track deep-review backlog.\n\n## Notes\n\n- `codex --all` maps to `f commit-queue review --all`.\n- Queue entries live under `.ai/internal/commit-queue/`.\n- Review findings are still recorded into `.ai/todos/todos.json` and commit review reports.\n- If `[options].myflow_mirror = true` is enabled, queued Codex reviews from the quick path are mirrored to myflow as `commit_queue_review` events.\n- For a full speed-first operating loop in `~/code/myflow`, see [`../fast-commit-deep-review-loop.md`](../fast-commit-deep-review-loop.md).\n","docs/commands/seq-rpc.md":"# `f seq-rpc`\n\nNative `seqd` RPC bridge for Flow.\n\nUse this when an agent/workflow needs OS-level actions and you want a typed, low-overhead path.\nThis command talks to `seqd` over Unix socket directly from Rust (no `seq rpc` subprocess).\n\n## Why this command exists\n\n- Keeps protocol handling in Rust.\n- Avoids shell output parsing drift.\n- Gives stable response envelope fields (`ok`, `op`, `dur_us`, ids).\n- Matches hard policy in `docs/seq-agent-rpc-contract.md`.\n\n## Usage\n\n```bash\nf seq-rpc [--socket PATH] [--timeout-ms 5000] [--pretty] <action> ...\n```\n\nActions:\n\n- `ping`\n- `app-state`\n- `perf`\n- `open-app <name>`\n- `open-app-toggle <name>`\n- `screenshot <path>`\n- `rpc <op> [--args-json '{...}']`\n\nCommon id fields (recommended on every call):\n\n- `--request-id`\n- `--run-id`\n- `--tool-call-id`\n\nExample:\n\n```bash\nf seq-rpc open-app \"Safari\" \\\n  --request-id req-42 \\\n  --run-id run-a12 \\\n  --tool-call-id tool-7 \\\n  --pretty\n```\n\n## Socket resolution\n\n1. `--socket <path>`\n2. `SEQ_SOCKET_PATH`\n3. `SEQD_SOCKET`\n4. `/tmp/seqd.sock`\n\n## Output\n\nPrints JSON response envelope from `seqd`.\n\nOn `ok=false`, command exits non-zero after printing the response JSON.\n","docs/commands/services.md":"# f services\n\nGuided setup flows for third-party services. These commands prompt for required\nenv vars, store them in cloud, and can optionally apply them to Cloudflare.\n\n## Stripe\n\n```bash\nf services stripe\n```\n\n### Options\n\n- `--path <PATH>`: target project root (defaults to current directory).\n- `--environment <ENV>`: env store to write (default: flow.toml or `production`).\n- `--mode <test|live>`: Stripe mode (default: `test`).\n- `--force`: prompt even if keys are already set.\n- `--apply` / `--no-apply`: apply envs to Cloudflare after setup.\n\n### What it prompts for\n\nThe command inspects `flow.toml` `[cloudflare].env_keys` and asks for Stripe\nkeys found there (fallback order):\n\n- `STRIPE_SECRET_KEY`\n- `STRIPE_WEBHOOK_SECRET`\n- `STRIPE_PRO_PRICE_ID`\n- `STRIPE_REFILL_PRICE_ID`\n- `VITE_STRIPE_PUBLISHABLE_KEY`\n\n### Helpful Stripe sources\n\n- Secret/Publishable keys: Stripe Dashboard -> Developers -> API keys\n- Webhook signing secret: Stripe Dashboard -> Developers -> Webhooks (or `stripe listen --print-secret`)\n- Price IDs: Stripe Dashboard -> Products -> Price (starts with `price_`)\n\n### Example\n\n```bash\ncd ~/org/gen/new\nf services stripe --mode test --apply\n```\n","docs/commands/setup.md":"# f setup\n\nBootstrap the project if needed, generate a `flow.toml` if missing, then run the `setup` task or print shell aliases.\n\n## Quick Start\n\n```bash\n# Bootstrap if missing, generate flow.toml if missing, then run setup task or print aliases\nf setup\n\n# Configure host deployment (Linux)\nf setup deploy\n\n# Configure release hosting for server projects\nf setup release\n\n# Use a specific config file\nf setup --config ./flow.toml\n```\n\n## Behavior\n\n- If the project is not bootstrapped, it runs the bootstrap flow (`.ai/`, `.gitignore`).\n- If `flow.toml` is missing, it prompts to generate `setup` + `dev` tasks (AI via `gen` if available, otherwise manual prompts).\n- If `flow.toml` already exists, Flow non-destructively appends missing Codex baseline sections (`[skills]`, `[skills.codex]`, commit skill gate, and Bun testing gate in Bun contexts).\n- After baseline upgrades, Flow triggers a Codex skills reload (respecting `[skills.codex].force_reload_after_sync`) so open sessions pick up changes immediately.\n- If `flow.toml` defines a `setup` task, `f setup` runs that task.\n- After the `setup` task exits, Flow re-reads `flow.toml`, re-syncs task skills to `.ai/skills`, and reloads Codex skills (when configured). This makes setup-generated task changes visible to Claude/Codex immediately.\n- Otherwise, it prints shell aliases from `[alias]` in `flow.toml`.\n- `f setup deploy` adds a `[host]` section, creates a remote setup script, copies env templates, and optionally stores the deploy host.\n- `f setup release` detects server projects and offers Linux host deployment defaults.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`) |\n| `TARGET` | Optional setup target (e.g., `deploy`, `release`) |\n\n### Global Server Setup Defaults\n\nYou can provide a server template in your global config at `~/.config/flow/flow.toml`:\n\n```toml\n[setup.server]\ntemplate = \"~/infra/flow.toml\"\n```\n\nOr inline host defaults:\n\n```toml\n[setup.server.host]\nsetup = \"\"\"#!/usr/bin/env bash\nset -euo pipefail\n...\"\"\"\nenv_file = \".env.host\"\nport = 3000\n```\n","docs/commands/skills.md":"# f skills\n\nManage Codex/Claude skills for the current project.\n\nSkills live in `.ai/skills/` and are symlinked to `.codex/skills` and `.claude/skills` so active agent sessions can discover them.\n\n## Core Commands\n\n```bash\n# List local skills\nf skills\n\n# Create/edit/remove skills\nf skills new <name> -d \"description\"\nf skills edit <name>\nf skills remove <name>\n\n# Install curated skills\nf skills install <name>\n\n# Generate one skill per flow.toml task\nf skills sync\n\n# Force Codex app-server to rescan skills for this cwd\nf skills reload\n```\n\n## Codex Tight Feedback Loop\n\nUse this loop when coding with Codex/Claude:\n\n1. Make code changes.\n2. Run focused tests quickly (in Bun repos: `bun bd test ...`).\n3. Refresh skill context:\n\n```bash\nf skills sync\nf skills reload\n```\n\n4. Commit via quality gates:\n\n```bash\nf commit\n```\n\n`f skills reload` is useful for already-open Codex sessions; it refreshes the app-server skill cache without creating a new session.\n\n## `flow.toml` Settings\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n```\n\n## Built-in Default Skills\n\nFlow auto-materializes a small baseline set of project-local skills in `.ai/skills/`:\n\n- `env`\n- `quality-bun-feature-delivery`\n- `pr-markdown-body-file`\n\nThese are symlinked into `.codex/skills` and `.claude/skills` and can be reloaded with:\n\n```bash\nf skills reload\n```\n\n### `skills.codex` fields\n\n- `generate_openai_yaml`: writes `.ai/skills/<task>/agents/openai.yaml` for task-synced skills.\n- `force_reload_after_sync`: after `f skills sync` or `f skills install`, force Codex app-server `skills/list` with `forceReload: true`.\n- `task_skill_allow_implicit_invocation`: default `policy.allow_implicit_invocation` value in generated `agents/openai.yaml`.\n\n## Recommended Enforcement\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\nThis blocks commits that skip required Bun-oriented testing/skill policy.\n","docs/commands/sync.md":"# f sync\n\nSync git repo: pull from tracking remote, merge upstream changes, optionally push.\n\n## Overview\n\nSingle command to bring a repository up to date. Pulls from the tracking branch, syncs upstream if configured (fork workflow), and optionally pushes. Works with both plain git and jj (jujutsu) colocated repos.\n\n## Context Card\n\nUse this block when passing `f sync` behavior to another agent:\n\n- Default behavior: pull/sync only; push is off unless `--push`.\n- Defaults: `--stash=true`, `--fix=true`.\n- Modes: uses jj flow in healthy colocated workspaces, falls back to plain git when needed.\n- Home-branch mode: when the current branch matches `jj.home_branch`, `f sync` skips the normal tracking pull and syncs `origin/<default-branch>` into that branch.\n- Push target: configured `[git].remote` first, then standard fallback behavior.\n- Clipboard output: synced commit list is copied only when remote commit ranges are detected (typically jj fetch path).\n- Conflict note: jj can finish with unresolved conflicts and prints `jj resolve` guidance.\n\n## Quick Start\n\n```bash\n# Pull latest from remote (no push by default)\nf sync\n\n# Pull and push\nf sync --push\n\n# Pull with rebase instead of merge\nf sync -r\n\n# Pull with rebase and push\nf sync -r --push\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--rebase` | `-r` | Use rebase instead of merge when pulling |\n| `--push` | | Push to configured git remote after sync (default: off) |\n| `--no-push` | | Skip pushing (legacy; already the default) |\n| `--stash` | `-s` | Auto-stash uncommitted changes (default: true) |\n| `--stash-commits` | | Stash local JJ commits to a bookmark before syncing (jj only) |\n| `--allow-queue` | | Allow sync even when commit queue is non-empty |\n| `--create-repo` | | Create origin repo on GitHub if it doesn't exist |\n| `--fix` | `-f` | Auto-fix conflicts using Claude (default: true) |\n| `--no-fix` | | Disable auto-fix |\n| `--max-fix-attempts <N>` | | Maximum auto-fix attempts (default: 3) |\n| `--allow-review-issues` | | Allow push even if P1/P2 review todos are open |\n| `--compact` | | Legacy noise-reduction flag (jj fetch output is already compact by default) |\n\n## What Happens\n\n### Step 1: Pre-flight checks\n\n1. Detects if jj is available and healthy; falls back to git if not\n2. Checks for unmerged files and resolves them (or prompts)\n3. Handles in-progress rebase/merge\n4. Stashes uncommitted changes if `--stash` is set\n\n### Step 2: Pull from tracking branch\n\nPulls from the tracking remote/branch (e.g. `origin/main`). If the branch has no tracking info but the push remote has a matching branch, auto-configures tracking.\n\n- With `--rebase`: runs `git pull --rebase`\n- Without: runs `git pull --no-rebase --no-edit` (merge without opening an editor)\n- Auto-resolves conflicts when `--fix` is enabled\n\n### Step 3: Sync upstream\n\nIf an `upstream` remote exists (fork workflow), fetches and merges upstream changes into the current branch.\n\nIf no `upstream` remote but on a feature branch, syncs from `origin/<default-branch>` (e.g. `origin/main`) into the current branch.\n\n### Home-branch mode\n\nIf the current branch matches the resolved `jj.home_branch`, Flow treats that branch as your\nlong-lived integration branch.\n\nIn that mode, `f sync`:\n\n- skips the normal tracking-branch pull\n- leaves branch tracking config untouched\n- syncs `origin/<default-branch>` into the home branch\n- keeps all non-home branches on the existing sync behavior\n\nHome-branch resolution order is:\n\n1. `<repo>/flow.toml` `jj.home_branch`\n2. `~/.config/flow/flow.toml` `jj.home_branch`\n3. basename of `$HOME`\n4. `USER` or `USERNAME`\n\n### Step 4: Push (optional)\n\nOnly when `--push` is passed:\n\n- Detects fork push targets (redirects to private fork remote if configured)\n- Checks review-todo gate (blocks if P1/P2 issues are open unless `--allow-review-issues`)\n- Skips push if the push remote equals upstream (read-only clone)\n- Creates repo with `--create-repo` if origin doesn't exist\n\n### Step 5: Restore stash\n\nRestores auto-stashed changes if any were stashed in step 1.\n\n### Step 6: Synced commit list + clipboard\n\nWhen remote commit ranges are discovered (typically during jj fetch), Flow prints a deduplicated\nlist of newly synced commits (hash + subject) and copies that same list to your clipboard.\n\nIf no synced commit ranges were detected, this section is skipped.\n\nSet `FLOW_NO_CLIPBOARD=1` to disable clipboard copy.\n\n## JJ (Jujutsu) Support\n\nWhen a `.jj` directory is present and healthy, sync uses the jj flow instead of plain git. Falls back to git if:\n\n- Configured `git.remote` is not `origin`/`upstream`\n- Tracking remote is a custom remote\n- jj workspace is unhealthy or corrupt\n\nUse `--stash-commits` to bookmark local jj commits before syncing.\n\njj fetch output is compact by default; synced commit details are emitted once at the end for clipboard use.\n\n## Commit Queue Guard\n\nIf the commit queue has pending entries and sync would rebase (rewriting SHAs), sync refuses to proceed. Use `--allow-queue` to override, or process the queue first with `f commit-queue list`.\n\n## Configuration\n\n### Push remote\n\nSet in `flow.toml` under `[git]`:\n\n```toml\n[git]\nremote = \"origin\"  # default push remote\n\n[jj]\nhome_branch = \"alice\" # optional long-lived personal integration branch\n```\n\n### Fork push\n\nWhen a fork push target is configured, sync redirects push to the fork remote automatically.\n\n## Examples\n\n```bash\n# Basic sync (pull only)\nf sync\n\n# Sync and push\nf sync --push\n\n# Rebase workflow\nf sync -r --push\n\n# Sync a fork (has upstream remote)\nf sync --push\n\n# Create missing origin and push\nf sync --push --create-repo\n\n# Skip auto-fix for conflicts\nf sync --no-fix\n\n# Allow sync with pending commit queue\nf sync --allow-queue\n```\n\n## Troubleshooting\n\n### \"Unmerged files detected\"\n\nSync found files with unresolved merge conflicts. By default (`--fix`), it tries to auto-resolve. If that fails, resolve manually:\n\n```bash\ngit status                # see conflicted files\n# edit and fix conflicts\ngit add <files>\nf sync                    # retry\n```\n\n### \"Commit queue is not empty\"\n\nRebase-based sync can rewrite commit SHAs, breaking queued commits. Either:\n\n```bash\nf commit-queue list       # review the queue\nf sync --allow-queue      # override the guard\n```\n\n### \"Remote unreachable\"\n\nThe push remote doesn't exist or auth/network failed. For missing origin:\n\n```bash\nf sync --push --create-repo\n```\n\n### jj corruption fallback\n\nIf jj sync fails due to workspace/store issues, sync automatically retries with plain git. Fix jj with:\n\n```bash\njj git import\n# or if still broken:\nrm -rf .jj && jj git init --colocate\n```\n\n### \"Sync complete (jj) but conflicts remain\"\n\nThis means sync/rebase completed but conflict revisions still exist in jj.\n\n```bash\njj resolve\n```\n\n## See Also\n\n- [upstream](upstream.md) - Manage upstream fork workflow\n- [commit](commit.md) - Commit changes\n- [jj](jj.md) - Jujutsu workflow helpers\n","docs/commands/tasks.md":"# f tasks\n\nList and discover project tasks from:\n\n- `flow.toml` (`[[tasks]]`)\n- `.ai/tasks/*.mbt` (AI MoonBit tasks)\n\nYou can run tasks directly with `f <task>`.\n\n## Usage\n\n```bash\nf tasks\nf tasks list\nf tasks dupes\nf tasks init-ai\nf tasks build-ai ai:flow/dev-check\nf tasks run-ai ai:flow/dev-check\nf tasks run-ai --daemon ai:flow/dev-check\nf tasks daemon start\nf tasks daemon status\nf tasks daemon stop\nf ai-taskd-launchd-install\nf ai-taskd-launchd-status\ncargo build --release -p ai-taskd-client --bin ai-taskd-client\n./target/release/ai-taskd-client ai:flow/dev-check\nf install-ai-fast-client\nf fast ai:flow/dev-check\nf bench-ai-runtime --iterations 80 --warmup 10\nf bench-ffi-boundary --iters 10000000\nf bench-ffi-boundary --iters 10000000 --native-opt\n```\n\n## AI Task Workflow\n\nInitialize a starter MoonBit task:\n\n```bash\nf tasks init-ai\n```\n\nThis creates:\n\n```text\n.ai/tasks/starter.mbt\n```\n\nRun it:\n\n```bash\nf starter\nf ai:starter\n```\n\nAdd more tasks as `.mbt` files under `.ai/tasks/` and run by name or selector:\n\n```bash\nf release-flow\nf ai:project/release-flow\n```\n\n## Notes\n\n- Default execution mode is cached native binary:\n  1) `moon build --target native --release` once per content hash\n  2) run cached artifact from `~/Library/Caches/flow/ai-tasks/...`\n- Use `f tasks run-ai --no-cache ...` (or `FLOW_AI_TASK_RUNTIME=moon-run`) to force direct `moon run`.\n- Set `FLOW_AI_TASK_MODE=release` for release builds (`--release`).\n- Set `FLOW_AI_TASK_MODE=js` to run with JS target.\n- `f tasks daemon` runs a lightweight local `ai-taskd` over Unix socket for warm repeated runs.\n- For lowest invocation overhead, use the tiny client binary against the daemon:\n- `cargo build --release -p ai-taskd-client --bin ai-taskd-client`\n  - `./target/release/ai-taskd-client ai:<selector>`\n  - or `f install-ai-fast-client` then use `fai ai:<selector>`\n  - This bypasses full `f` startup for hot-loop calls.\n- `fai` supports:\n  - `--protocol msgpack|json` (msgpack default)\n  - `--timings` (server-side phase timings)\n  - `--batch-stdin` (pooled burst mode in one client process)\n- For stable startup/jitter, prefer always-on daemon via launchd:\n  - `f ai-taskd-launchd-install`\n  - `f ai-taskd-launchd-status`\n  - `f ai-taskd-launchd-logs`\n- Automatic preference for latency-critical AI selectors:\n  - Opt in with `FLOW_AI_TASK_FAST_CLIENT=1` (typically together with `FLOW_AI_TASK_DAEMON=1`).\n  - Then `f` will auto-prefer fast client dispatch for AI tasks tagged `fast`, `latency`, `hot`, or `hotkey`.\n  - Override selector matching with `FLOW_AI_TASK_FAST_SELECTORS` (comma-separated patterns, supports `*` prefix/suffix).\n  - Override client binary with `FLOW_AI_TASK_FAST_CLIENT_BIN=/path/to/fai`.\n- `f recipe` still exists for legacy compatibility, but task-centric workflow is preferred.\n","docs/commands/up.md":"# f up\n\nBring a project up using lifecycle conventions.\n\n## Quick Start\n\n```bash\n# Run lifecycle up (tries task \"up\", then \"dev\")\nf up\n\n# Pass args through to the selected task\nf up -- --port 3001\n```\n\n## Behavior\n\n- Loads nearest `flow.toml` (or `--config` path).\n- If `[lifecycle.domains]` is configured:\n  - runs `f domains add <host> <target> --replace`\n  - runs `f domains up` (with configured engine when set)\n- Runs lifecycle task:\n  - `[lifecycle].up_task` when configured\n  - otherwise fallback order: `up`, then `dev`\n\nIf no up task is found, command fails with guidance.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`, searches upward when default is missing) |\n| `ARGS...` | Extra args passed to the selected lifecycle task |\n\n## Recommended myflow config\n\n```toml\n[lifecycle]\nup_task = \"dev\"\n\n[lifecycle.domains]\nhost = \"myflow.localhost\"\ntarget = \"127.0.0.1:3000\"\nengine = \"native\"\nremove_on_down = false\nstop_proxy_on_down = false\n```\n","docs/commands/upstream.md":"# f upstream\n\nManage upstream fork workflow.\n\n## Overview\n\nSet up and sync forks with their upstream repositories. Creates a local `upstream` branch to cleanly track the original repo, making merges easier.\n\n## Quick Start\n\n```bash\n# Set up upstream tracking\nf upstream setup --upstream-url https://github.com/original/repo\n\n# Pull latest from upstream\nf upstream pull\n\n# Full sync: pull, merge, push\nf upstream sync\n```\n\n## Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `status` | Show current upstream configuration |\n| `setup` | Set up upstream remote and local tracking branch |\n| `pull` | Pull changes from upstream into local 'upstream' branch |\n| `sync` | Full sync: pull upstream, merge to dev/main, push to origin |\n\n---\n\n## Setup\n\nConfigure upstream tracking for a forked repository:\n\n```bash\n# Basic setup\nf upstream setup --upstream-url https://github.com/original/repo\n\n# Specify branch (if not main)\nf upstream setup --upstream-url https://github.com/original/repo --upstream-branch master\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--upstream-url <URL>` | `-u` | URL of the upstream repository |\n| `--upstream-branch <BRANCH>` | `-b` | Branch name on upstream (default: auto-detected) |\n\n### What Happens\n\n1. Adds `upstream` remote pointing to original repo\n2. Fetches upstream branches\n3. Creates local `upstream` branch tracking the upstream's default branch\n4. Stores configuration in `.git/config`\n\n---\n\n## Pull\n\nPull latest changes from upstream into local `upstream` branch:\n\n```bash\n# Pull into upstream branch\nf upstream pull\n\n# Pull and also merge into specific branch\nf upstream pull --branch main\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--branch <BRANCH>` | `-b` | Also merge into this branch after pulling |\n\n---\n\n## Sync\n\nFull sync workflow - pulls upstream, merges to your branch, and pushes:\n\n```bash\n# Full sync (pull, merge, push)\nf upstream sync\n\n# Sync without pushing (for review first)\nf upstream sync --no-push\n```\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `--no-push` | Skip pushing to origin |\n\n### What Happens\n\n1. Stashes any uncommitted changes\n2. Fetches latest from upstream\n3. Updates local `upstream` branch\n4. Merges upstream into your current branch (e.g., `main`)\n5. Pushes to origin (unless `--no-push`)\n6. Restores stashed changes\n\n### Branch Detection\n\nFlow auto-detects the upstream default branch:\n- Checks `refs/remotes/upstream/HEAD`\n- Falls back to checking if `upstream/main` or `upstream/master` exists\n- Uses `main` as final fallback\n\n---\n\n## Status\n\nShow current upstream configuration:\n\n```bash\nf upstream status\n```\n\nOutput:\n```\nUpstream Configuration\n  Remote: https://github.com/original/repo\n  Branch: main\n  Local tracking: upstream -> upstream/main\n  Last sync: 2 hours ago\n```\n\n---\n\n## Workflow Example\n\n### Initial Fork Setup\n\n```bash\n# 1. Clone your fork\ngit clone https://github.com/youruser/project\ncd project\n\n# 2. Set up upstream tracking\nf upstream setup --upstream-url https://github.com/original/project\n\n# 3. Verify\nf upstream status\n```\n\n### Regular Sync\n\n```bash\n# When you want to sync with upstream:\nf upstream sync\n\n# Or if you want to review before pushing:\nf upstream sync --no-push\ngit log --oneline main..upstream  # See what's new\ngit push  # Push when ready\n```\n\n### Handling Conflicts\n\nIf sync encounters merge conflicts:\n\n```bash\n$ f upstream sync\nMerging upstream into main...\nCONFLICT (content): Merge conflict in src/lib.rs\n\n# Fix conflicts manually\nvim src/lib.rs\ngit add src/lib.rs\ngit commit\n\n# Then push\ngit push\n```\n\n---\n\n## Configuration\n\nUpstream configuration is stored in `.git/config`:\n\n```ini\n[remote \"upstream\"]\n    url = https://github.com/original/repo\n    fetch = +refs/heads/*:refs/remotes/upstream/*\n\n[branch \"upstream\"]\n    remote = upstream\n    merge = refs/heads/main\n```\n\nYou can also manually configure:\n\n```bash\ngit remote add upstream https://github.com/original/repo\ngit fetch upstream\ngit branch upstream upstream/main\n```\n\n---\n\n## Troubleshooting\n\n### \"upstream remote not found\"\n\nRun `f upstream setup` first with the upstream URL.\n\n### \"git stash pop failed\"\n\nThis can happen if there were no changes to stash. Flow handles this automatically by tracking stash state.\n\n### Upstream uses master instead of main\n\nFlow auto-detects the default branch. If detection fails, specify explicitly:\n\n```bash\nf upstream setup --upstream-url https://github.com/original/repo --upstream-branch master\n```\n\n### Merge conflicts\n\nResolve conflicts manually:\n1. Fix conflicting files\n2. `git add <files>`\n3. `git commit`\n4. `git push`\n\n## See Also\n\n- [commit](commit.md) - Commit changes after sync\n- [publish](publish.md) - Publish to GitHub\n","docs/commands/url.md":"# `f url`\n\nInspect or crawl URLs into compact AI-friendly summaries.\n\n## Quick Start\n\n```bash\n# Thin single-page summary\nf url inspect https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\n\n# Force Cloudflare Browser Rendering markdown\nf url inspect --provider cloudflare https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\n\n# Machine-readable output\nf url inspect --json https://linear.app/example-workspace/project/example-project-v1-1234567890ab/overview\n\n# Explicit site crawl (Cloudflare Browser Rendering)\nf url crawl https://developers.cloudflare.com/browser-rendering/rest-api/crawl-endpoint/ --limit 3 --records 2\n```\n\n## `inspect`\n\n`f url inspect <url>` uses this provider order:\n\n1. Cloudflare Browser Rendering markdown\n2. configured scraper backend from `[skills.seq]`\n3. direct fetch fallback\n\nDefault output is intentionally compact:\n\n- title\n- URL\n- content type\n- short description\n- short excerpt\n\nUse `--full` to include the full markdown/content body.\n\n## `crawl`\n\n`f url crawl <url>` is the explicit multi-page path.\n\nIt currently uses Cloudflare Browser Rendering crawl and polls until the job completes or the wait timeout is reached.\n\nUseful flags:\n\n```bash\nf url crawl <url> --limit 10 --records 5\nf url crawl <url> --depth 2 --render\nf url crawl <url> --include-pattern \"https://developers.cloudflare.com/browser-rendering/*\"\nf url crawl <url> --exclude-pattern \"*/changelog/*\"\nf url crawl <url> --json\n```\n\nDefaults are tuned to stay small:\n\n- `--limit 10`\n- `--depth 2`\n- `--records 5`\n- `--render false`\n\n## Auth\n\nCloudflare auth is read from:\n\n1. shell env\n2. Flow personal env store fallback\n\nRequired keys:\n\n- `CLOUDFLARE_ACCOUNT_ID`\n- `CLOUDFLARE_API_TOKEN`\n\nNo daemon is required.\n\n## Config\n\nIf you have a local scraper backend, `f url inspect` reuses `[skills.seq]` settings from repo `flow.toml` or global `~/.config/flow/flow.toml`:\n\n```toml\n[skills.seq]\nscraper_base_url = \"http://127.0.0.1:7444\"\nscraper_api_key = \"...\"\ncache_ttl_hours = 2\nallow_direct_fallback = true\n```\n","docs/commands/web.md":"# web\n\nOpen the Flow web UI for the current project.\n\n## Usage\n\n```bash\nf web\n```\n\n## What it does\n\n- Serves the `.ai/web` UI for the current project.\n- Exposes `/api/projects` for project metadata and top-level `.ai` entries.\n- Exposes `/api/ai` for the full `.ai` tree (paths + kinds).\n- Exposes `/api/sessions` for Claude/Codex session summaries and transcripts.\n- Exposes `/api/openapi` when an OpenAPI spec is detected.\n\n## Options\n\n```bash\n--host <host>   Host to bind (default: 127.0.0.1)\n--port <port>   Port to serve the UI on (default: 9310)\n```\n\n## Notes\n\n- `f web` serves `.ai/web/dist` when it exists (Vite default output).\n- The Vite app source lives in `.ai/web`.\n- `.ai/web` is gitignored by default so AI can freely rewrite it.\n- If no build exists, `f web` shows a minimal placeholder.\n- Example build: `vite build` from `.ai/web`.\n- `f web` now runs `bun install` (once) and `bun run build` automatically when a Vite app is present.\n","tools/domainsd-cpp/readme.md":"# domainsd-cpp (experimental)\n\n`domainsd-cpp` is an experimental native local-domains proxy used by:\n\n- `f domains --engine native up`\n- `f domains --engine native down`\n\nIt is designed for low overhead on localhost routing and keeps Flow route state in:\n\n- `~/.config/flow/local-domains/routes.json`\n\nCurrent scope:\n- HTTP/1.1 host-based routing (`*.localhost` -> `host:port`)\n- WebSocket upgrade passthrough (full duplex tunnel)\n- request-side chunked transfer-encoding decode/forward\n- upstream keepalive connection pooling (safe framed-response reuse)\n- overload shedding with bounded active client handlers (`503` when saturated)\n- upstream connect/IO timeouts (`504` for connect timeout)\n- health endpoint: `GET /_flow/domains/health`\n- mtime-based route reload (no daemon restart required)\n- optional macOS launchd socket activation (`--launchd-socket <name>`) for privileged `:80` bind without Docker\n\nRuntime tuning:\n- daemon supports CLI flags (`--max-active-clients`, `--upstream-*-timeout-ms`, `--pool-*`)\n- Flow passes tuning via env vars prefixed `FLOW_DOMAINS_NATIVE_*`\n\nCurrent limitations:\n- no HTTP/2/TLS yet\n\nThe Flow CLI builds this binary automatically with `clang++` when needed.\n\n## macOS native `:80` without Docker\n\nWhen direct bind to `127.0.0.1:80` is blocked by permissions, install launchd socket mode once:\n\n```bash\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nThis installs `dev.flow.domainsd` in `/Library/LaunchDaemons`, binds port `80` via launchd, and runs `domainsd-cpp` as your user with inherited socket fd.\n\nUninstall:\n\n```bash\nsudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh\n```\n",".cursorrules (gitflow.mdc)":"# Gitflow Workflow Rules\n\n## Main Branches\n\n### main (or master)\n- Contains production-ready code\n- Never commit directly to main\n- Only accepts merges from:\n  - hotfix/* branches\n  - release/* branches\n- Must be tagged with version number after each merge\n\n### develop\n- Main development branch\n- Contains latest delivered development changes\n- Source branch for feature branches\n- Never commit directly to develop\n\n## Supporting Branches\n\n### feature/*\n- Branch from: develop\n- Merge back into: develop\n- Naming convention: feature/[issue-id]-descriptive-name\n- Example: feature/123-user-authentication\n- Must be up-to-date with develop before creating PR\n- Delete after merge\n\n### release/*\n- Branch from: develop\n- Merge back into: \n  - main\n  - develop\n- Naming convention: release/vX.Y.Z\n- Example: release/v1.2.0\n- Only bug fixes, documentation, and release-oriented tasks\n- No new features\n- Delete after merge\n\n### hotfix/*\n- Branch from: main\n- Merge back into:\n  - main\n  - develop\n- Naming convention: hotfix/vX.Y.Z\n- Example: hotfix/v1.2.1\n- Only for urgent production fixes\n- Delete after merge\n\n## Commit Messages\n\n- Format: `type(scope): description`\n- Types:\n  - feat: New feature\n  - fix: Bug fix\n  - docs: Documentation changes\n  - style: Formatting, missing semicolons, etc.\n  - refactor: Code refactoring\n  - test: Adding tests\n  - chore: Maintenance tasks\n\n## Version Control\n\n### Semantic Versioning\n- MAJOR version for incompatible API changes\n- MINOR version for backwards-compatible functionality\n- PATCH version for backwards-compatible bug fixes\n\n## Pull Request Rules\n\n1. All changes must go through Pull Requests\n2. Required approvals: minimum 1\n3. CI checks must pass\n4. No direct commits to protected branches (main, develop)\n5. Branch must be up to date before merging\n6. Delete branch after merge\n\n## Branch Protection Rules\n\n### main & develop\n- Require pull request reviews\n- Require status checks to pass\n- Require branches to be up to date\n- Include administrators in restrictions\n- No force pushes\n- No deletions\n\n## Release Process\n\n1. Create release branch from develop\n2. Bump version numbers\n3. Fix any release-specific issues\n4. Create PR to main\n5. After merge to main:\n   - Tag release\n   - Merge back to develop\n   - Delete release branch\n\n## Hotfix Process\n\n1. Create hotfix branch from main\n2. Fix the issue\n3. Bump patch version\n4. Create PR to main\n5. After merge to main:\n   - Tag release\n   - Merge back to develop\n   - Delete hotfix branch"},"files":{".ai/agents.md":"# Autonomous Agent Instructions\n\nProject: flow\n\nThis project is configured for autonomous AI agent workflows with human-in-the-loop approval.\n\n## Response Format\n\n**Every response MUST end with exactly one of these signals on the final line:**\n\n### Success signals\n\n```\ndone.\n```\nUse when task completed successfully with high certainty. No further action needed.\n\n```\ndone: <message>\n```\nUse when task completed with context to share. Example: `done: Added login command with --token flag`\n\n### Needs human input\n\n```\nneedsUpdate: <message>\n```\nUse when you need human decision or action. Example: `needsUpdate: Should I use OAuth or API key auth?`\n\n### Error signals\n\n```\nerror: <message>\n```\nUse when task failed or cannot proceed. Example: `error: Build failed - missing dependency xyz`\n\n## Rules\n\n1. **Always end with a signal** - The last line must be one of the above\n2. **One signal only** - Never combine signals\n3. **Be specific** - Include actionable context in messages\n4. **No quotes** - Write signals exactly as shown, no wrapping quotes\n\n## Examples\n\n### Successful implementation\n```\nAdded the new CLI command with all requested flags.\n\ndone.\n```\n\n### Completed with context\n```\nRefactored the auth module to use the new token format.\n\ndone: Auth now supports both JWT and API key methods\n```\n\n### Need human decision\n```\nFound two approaches for caching:\n1. Redis - better for distributed systems\n2. In-memory - simpler, faster for single instance\n\nneedsUpdate: Which caching approach should I use?\n```\n\n### Error occurred\n```\nAttempted to run tests but encountered issues.\n\nerror: Test suite requires DATABASE_URL environment variable\n```\n",".ai/skills/env/skill.md":"---\nname: env\ndescription: Manage environment variables and secrets with flow (always use Flow env store)\nsource: flow-default\n---\n\n# Environment Variables & Secrets\n\nFlow provides a secure way to manage environment variables across projects.\n\n## Rules (Must)\n\n- Always use Flow env store for secrets/tokens in Flow projects.\n- Do not rely on shell env vars or `.env` files for secrets unless they are injected via `f env`.\n- For tasks/scripts that need secrets, fetch them with `f env get` or run via `f env run`.\n\n## Setup\n\n### 1. Define variables in flow.toml\n\nAdd a `[storage]` section to your project's `flow.toml`:\n\n```toml\n[storage]\nprovider = \"myflow.sh\"\n\n[[storage.envs]]\nname = \"local\"\ndescription = \"Local development\"\nvariables = [\n  { key = \"DATABASE_URL\" },\n  { key = \"API_KEY\" },\n  { key = \"SECRET_TOKEN\", default = \"\" },\n]\n```\n\n### 2. Set environment variables\n\nUse `f env set` to store values:\n\n```bash\n# Set individual env vars\nf env set API_KEY=abc123\nf env set DATABASE_URL=\"postgres://...\"\n\n# Values are stored in ~/.config/flow/env-local/personal/production.env\n```\n\n### 3. Pull env vars to local .env\n\n```bash\n# Pull all env vars for the current environment\nf env pull\n\n# Show current env vars\nf env list\n\n# Get specific var\nf env get API_KEY\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `f env set KEY=value` | Store an env var |\n| `f env pull` | Pull env vars to local .env file |\n| `f env push` | Push local .env to cloud |\n| `f env list` | List env vars for this project |\n| `f env get KEY` | Get specific env var(s) |\n| `f env keys` | Show configured env keys from flow.toml |\n| `f env setup` | Interactive env setup |\n| `f env guide` | Guided prompt to set required vars |\n| `f env run <cmd>` | Run command with env vars injected |\n\n## Environment Selection\n\nFlow supports multiple environments:\n\n```toml\n[[storage.envs]]\nname = \"local\"\nvariables = [{ key = \"DATABASE_URL\" }]\n\n[[storage.envs]]\nname = \"staging\"\nvariables = [{ key = \"DATABASE_URL\" }]\n\n[[storage.envs]]\nname = \"production\"\nvariables = [{ key = \"DATABASE_URL\" }]\n```\n\n## Example: Spotify CLI\n\n```toml\n[storage]\nprovider = \"myflow.sh\"\n\n[[storage.envs]]\nname = \"local\"\ndescription = \"Spotify API credentials\"\nvariables = [\n  { key = \"SPOTIFY_CLIENT_ID\" },\n  { key = \"SPOTIFY_CLIENT_SECRET\" },\n  { key = \"SPOTIFY_ACCESS_TOKEN\" },\n  { key = \"SPOTIFY_REFRESH_TOKEN\", default = \"\" },\n]\n```\n\nThen:\n```bash\n# Set your credentials (example values)\nf env set SPOTIFY_CLIENT_ID=example_client_id\nf env set SPOTIFY_CLIENT_SECRET=example_client_secret\n\n# Run CLI with env vars injected\nf env run bun run src/main.ts now\n\n# Or pull to .env first\nf env pull\nsource .env\nbun run src/main.ts now\n```\n\n## Task pattern (required for secrets)\n\nWhen writing Flow tasks, prefer:\n\n```bash\nMY_TOKEN=\"$(FLOW_ENV_BACKEND=local f env get --personal MY_TOKEN -f value 2>/dev/null || true)\"\nif [ -z \"${MY_TOKEN:-}\" ]; then\n  echo \"MY_TOKEN missing. Save it with envnew MY_TOKEN=...\"\n  exit 1\nfi\nexport MY_TOKEN\n```\n\n## One-time passwords (1Password Connect)\n\nUse Flow's OTP command to fetch TOTP codes from 1Password Connect:\n\n```bash\nf otp get <vault> <item> [--field <label>]\n```\n\nRequires:\n- `OP_CONNECT_HOST`\n- `OP_CONNECT_TOKEN` (env or Flow personal env store)\n\n## Storage Locations\n\n- **Personal env vars:** `~/.config/flow/env-local/personal/production.env`\n- **Project env vars:** Stored via myflow.sh cloud backend\n- **Local .env:** Created in project root via `f env pull`\n\n## Authentication\n\nFlow uses a token stored in `~/.config/flow/auth.toml` to authenticate. If you haven't authenticated:\n\n```bash\nf auth login\n```\n\n## Security Notes\n\n- Personal env vars stored locally in `~/.config/flow/`\n- Project env vars can be synced to cloud via `f env push`\n- Never commit `.env` files to git (add to `.gitignore`)\n- Use `f env run` to inject vars without creating .env files\n",".ai/skills/pr-markdown-body-file/skill.md":"---\nname: pr-markdown-body-file\ndescription: Always edit/create GitHub PR bodies from a markdown file; never inline escaped newlines.\nversion: 1\nsource: flow-default\n---\n\n# PR Markdown Body Discipline\n\nUse this skill when creating or editing pull requests.\n\n## Rules (Must)\n\n- Never pass multi-line PR text via a quoted CLI string with `\\n`.\n- Always use a markdown file with `--body-file`.\n- Prefer `f pr open edit` when available for local file-driven PR editing.\n\n## Why\n\nInline escaped newlines are fragile and can produce literal `\\n` text in GitHub PR descriptions.\n`--body-file` is deterministic and reviewable.\n\n## Safe patterns\n\n### Create PR (GitHub CLI)\n\n```bash\ncat > /tmp/pr-body.md <<'EOF'\n## Summary\n- ...\n\n## Scope\n- ...\nEOF\n\ngh pr create --title \"...\" --body-file /tmp/pr-body.md\n```\n\n### Edit existing PR\n\n```bash\ncat > /tmp/pr-body.md <<'EOF'\n## Summary\n- ...\nEOF\n\ngh pr edit <number> --body-file /tmp/pr-body.md\n```\n\n### Flow-native edit loop\n\n```bash\nf pr open edit\n```\n\nThis opens a local markdown file and syncs title/body on save.\n\n## Verification\n\n- Run:\n\n```bash\ngh pr view <number> --json body -q .body\n```\n\n- Confirm markdown renders correctly and contains no literal `\\n`.\n",".ai/skills/quality-bun-feature-delivery/skill.md":"---\nname: quality-bun-feature-delivery\ndescription: Enforce tight Codex/Claude delivery loop with Bun-first testing, skill sync/reload, and commit quality gates.\nversion: 2\nsource: flow-default\n---\n\n# Quality Bun Feature Delivery\n\nUse this workflow for every feature/change.\n\n## Rules (Must)\n\n- In Bun repos, run tests with `bun bd test ...` (never `bun test` for final validation).\n- Run only relevant tests first (single file/filter) for fast feedback.\n- Keep `.ai/features/*.md` and tests current for touched features.\n- Do not finish work without a passing local verification command.\n\n## Tight Loop\n\n1. Update code + tests.\n2. Run focused tests with Bun debug build:\n\n```bash\nbun bd test <target-test-file> -t \"<optional filter>\"\n```\n\n3. Sync task skills to keep agent context fresh:\n\n```bash\nf skills sync\n```\n\n4. Force Codex to reload skills for this cwd:\n\n```bash\nf skills reload\n```\n\n5. Commit through Flow quality gates:\n\n```bash\nf commit\n```\n\n## Bun Regression Check (for new tests)\n\nWhen adding/changing tests in Bun itself, ensure the test fails on system Bun and passes on debug Bun:\n\n```bash\nUSE_SYSTEM_BUN=1 bun test <target-test-file>\nbun bd test <target-test-file>\n```\n\n## Recommended flow.toml\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n","agents.md":"# Assistant Rules (flow)\n\nOnly load skills when the request clearly needs them.\n\n## Skills (on-demand)\n- flow-native: Use for Flow CLI native workflows (env setup, secrets, deploys, logs, deps), for repos with `flow.toml`, or Cloudflare Workers. Avoid direct pnpm/wrangler unless asked.\n- flow-interactive: Use when commands are interactive or could block on stdin (e.g., `f setup`).\n- flow-dev-traces: Use when debugging Flow proxy behavior, tracing requests, or when the user asks about proxyx, trace-summary.json, or flow trace commands.\n- flow-usage: Use when running or troubleshooting Flow command behavior.\n- internal-ai-inference: Use only when asked to run inference or integrate with internal AI tooling.\n\nDefault: Avoid loading skills for routine edits, reviews, or simple questions.\n\n## Deploy / Restart Policy\n\n- When changes affect the installed Flow CLI or built-in Codex daemon path,\n  prefer an explicit deploy + daemon reload instead of leaving runtime state\n  stale.\n- Use `deploy-with-codexd-reload` after edits in areas like `src/ai.rs`,\n  `src/codexd.rs`, `src/daemon.rs`, `src/supervisor.rs`, or `src/config.rs`\n  when those changes affect Codex runtime, daemon behavior, or Flow-managed\n  session recovery.\n- Use `deploy-with-hub-reload` for hub-facing changes that need `lin` / docs\n  processes refreshed.\n- For `codexd`, prefer explicit `stop` + `start` in automation over a single\n  restart command so the stop/start boundary is visible in logs.\n","docs/commands/ai.md":"# f ai\n\nManage Claude Code, Codex, and Cursor sessions for the current project.\n\nFlow reads local session stores, filters by current project path, and gives you one interface for list/search/resume/copy/save.\nWhen you need to reopen a repo's session from another working directory, use `--path <project-root>` on `resume` or provider-specific `continue`.\nCursor transcripts are supported for reading only.\n\nArchitecture note:\n\n- for the underlying transport split between wrapped Codex CLI, `jd`, and `codex app-server`, see `docs/codex-interface.md`\n\n## Quick Start\n\n```bash\n# Fuzzy-pick a recent session (Claude + Codex + Cursor)\nf ai\n\n# Provider-specific list/read\nf ai claude list\nf ai codex list\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\nf ai cursor list\nf codex resolve \"latest\"\nf codex resolve \"https://linear.app/.../project/.../overview\" --json\nf codex open \"continue the deploy work\"\nf codex agent list\nf codex agent show commit\nf ai claude resume <session-id-or-name>\nf ai codex resume <session-id-or-name>\nf ai codex resume --path ~/work/example-project\nf ai codex continue --path ~/work/example-project\nf ai codex find --path ~/repos/openai/codex \"where does codex store\"\nf ai codex find --all-history --path ~/repos/openai/codex \"older migration plan\"\nf ai codex find --recent-days 30 --path ~/repos/openai/codex \"thread/read\"\nf ai codex find --json --limit 5 --path ~/repos/openai/codex \"thread/read\"\nf codex connect --path ~/repos/openai/codex --exact-cwd --json \"app-server\"\nf codex connect --all-history --path ~/repos/openai/codex \"old designer cutover\"\nf ai cursor context - /path/to/repo 3\nf cursor copy\n\n# Save a memorable alias for a session\nf ai save reclaim-fix --id a38cf8bf-f4e2-4308-8b27-0254f89c4385\n```\n\n## Session Sources\n\n- Claude: `~/.claude/projects/<project-path>/*.jsonl`\n- Codex: `~/.codex/sessions/**/*.jsonl` (Flow matches by `session_meta.cwd`)\n- Cursor: `~/.cursor/projects/<project-key>/agent-transcripts/<session-id>/<session-id>.jsonl`\n- Saved aliases: `.ai/sessions/claude/index.json` in your repo\n\n## Resume Behavior (Important)\n\n### TTY requirement\n\nResume is interactive by design.\n\n- `f ai claude resume ...` requires a terminal TTY.\n- `f ai codex resume ...` requires a terminal TTY.\n- In non-interactive shells, Flow exits with a clear error and non-zero status.\n- Cursor does not currently expose a Flow resume/continue path; use `list`, `copy`, or `context`.\n\n### Claude exact-ID behavior\n\nIf you pass an explicit session (`name`, `id`, or `id-prefix`), Flow is strict:\n\n- it attempts `claude --resume <id>`\n- if Claude cannot open that exact session, Flow fails\n- Flow does **not** auto-fallback to `--continue` for explicit sessions (prevents opening the wrong conversation)\n\n### Claude no-arg behavior\n\nFor `f ai claude resume` with no argument:\n\n- Flow picks most recent Claude session for this project\n- if that resume fails, Flow may fallback to `claude --continue` in the same cwd (TTY only)\n\n### Codex behavior\n\nFor Codex, Flow runs:\n\n```bash\ncodex resume <id> --dangerously-bypass-approvals-and-sandbox\n```\n\nNo fallback is applied on resume failure; Flow returns non-zero.\n\n### Codex open and resolve\n\nUse `open` when you want one Codex entrypoint that stays conservative about context:\n\n```bash\nf codex open\nf codex open \"continue the deploy work\"\nf codex open \"resume latest\"\nf codex open --path ~/work/example-project \"what was I doing here\"\nf codex resolve \"https://linear.app/example-workspace/project/example-project-v1-1234567890ab/overview\" --json\nf codex doctor --path ~/work/example-project\n```\n\nBehavior:\n\n- no query: start a fresh Codex session in the target repo\n- explicit session lookup queries like `latest`, `resume session`, ordinals, or session IDs: resume the matching Codex session\n- explicit recovery prompts like `what was I doing` or `continue the ... work`: build a compact recovery handoff and start a new session\n- matching reference resolvers: inject only compact resolver output, then append the user request\n- otherwise: start a new session with the raw query and no extra wrapper text\n\nThis keeps prompt cost flat unless Flow has a strong reason to recover or unroll context.\nUse `f codex doctor` to confirm whether wrapper transport, runtime skills, and context budgets are actually active for the current repo.\n\n### Codex connect and find\n\n`f codex connect` and `f ai codex find` now use a Flow-managed local session-search index before\nfalling back to direct SQLite/transcript scans. The index is repo-scoped at query time, rebuilt\nfrom the Codex state DB when needed, and keeps transcript snippets for better recall on natural\nlanguage queries.\n\nBy default, search now prefers sessions from roughly the last 7 days for faster and more accurate\nranking on active work, then automatically widens back to the full session history when the recent\nwindow looks weak or sparse.\n\nUseful commands:\n\n```bash\nf codex connect --path ~/repos/openai/codex --exact-cwd \"app-server\"\nf codex connect --path ~/repos/openai/codex --exact-cwd --json \"thread/read\"\nf codex connect --all-history --path ~/repos/openai/codex \"old migration plan\"\nf ai codex find --path ~/repos/openai/codex \"where does codex store\"\nf ai codex find --recent-days 30 --path ~/repos/openai/codex \"thread/read\"\nf ai codex find --json --limit 5 --path ~/repos/openai/codex \"where does codex store\"\n```\n\nBehavior:\n\n- `connect` stays the interactive handoff path and returns the exact session match\n- `connect --json` prints the selected session instead of attaching\n- `find` still resumes the top hit\n- `find --json` is read-only and prints ranked candidates for inspection/eval work\n- by default both commands prefer the last 7 days first, then widen if the recent window is weak\n- use `--recent-days <N>` to widen the preferred recent window without fully disabling recency bias\n- use `--all-history` to search the full history immediately\n- if confidence is weak or the index misses, Flow still falls back to the older metadata and transcript paths instead of silently opening an arbitrary session\n\n### Codex sessions after a crash or restart\n\nIf your Mac restarts and you lose the live Codex terminals, use:\n\n```bash\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\n```\n\nBehavior:\n\n- lists recent Codex sessions for the current path\n- sorts by the last message timestamp descending\n- shows the stable session id plus a preview of the latest message\n- the numeric index matches `continue`, so you can reopen quickly\n\nIf you want to read or hand off a session instead of reopening it, use the native session bridge in Codex chat:\n\n```text\nsee codex in ~/repos/mark3labs/kit\nsee 019cd046 codex session\nread 019cd046 codex session deeply\n```\n\nExamples:\n\n```bash\nf ai codex continue 1 --path ~/repos/mark3labs/kit\nf ai codex continue 019cd046 --path ~/repos/mark3labs/kit\nf ai codex sessions --path ~/repos/mark3labs/kit --json\n```\n\n### Optional `flow.toml` resolver config\n\nYou can teach `f codex open` and `f codex resolve` to unroll repo-specific references:\n\n```toml\n[codex]\nauto_resolve_references = true\nprompt_context_budget_chars = 900\nmax_resolved_references = 1\nsync_workflow_command = \"./scripts/sync-safe\"\n\n[[codex.reference_resolver]]\nname = \"linear\"\nmatch = [\"https://linear.app/*/issue/*\", \"https://linear.app/*/project/*\"]\ncommand = \"my-linear-tool inspect {{ref}} --json\"\ninject_as = \"linear\"\n```\n\nNotes:\n\n- configure this in repo `flow.toml` or global `~/.config/flow/flow.toml`\n- `{{ref}}`, `{{query}}`, and `{{cwd}}` are available in resolver commands\n- built-in Linear URL parsing works even without a custom resolver\n- resolver output is compacted before prompt injection\n- `prompt_context_budget_chars` hard-caps injected context before your request is appended\n- `max_resolved_references` prevents broad unrolling from bloating one turn\n- `sync_workflow_command` lets plain `sync branch` route into a repo-specific safe sync command instead of improvised Git/JJ steps\n\n### Optional runtime skill transport\n\nFlow can also materialize tiny per-launch runtime skills for current upstream Codex without forking Codex.\n\nEnable it globally with:\n\n```bash\nf codex enable-global --full\nf codex doctor --path ~/docs --assert-runtime --assert-schedule\n```\n\nOr configure it manually with:\n\n```toml\n[codex]\nruntime_skills = true\n\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n```\n\nFor the `~/code/flow` repo specifically, the intended in-repo shape is:\n\n```toml\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n\n[codex]\nruntime_skills = true\nauto_resolve_references = true\nprompt_context_budget_chars = 1200\nmax_resolved_references = 2\n\n[[codex.skill_source]]\nname = \"run-control-plane\"\npath = \"~/run\"\nenabled = true\n```\n\nThat keeps a fresh checkout Codex-first even before machine-local setup is remembered.\n\nCurrent first-slice behavior:\n\n- `f codex open \"write plan\"` can attach a tiny plan-writing runtime skill\n- the runtime skill is exposed only for the launched Codex process\n- Flow keeps the generated runtime state under `~/.config/flow/codex/runtime`\n\nInspect or clear runtime state:\n\n```bash\nf codex runtime show\nf codex runtime clear\nf codex log status\nf codex log sync --limit 400\nf codex memory status\nf codex memory query --path ~/code/flow \"codex control plane runtime skills\"\nf codex memory recent --path ~/docs\nf codex doctor\n```\n\nAssertive health checks:\n\n```bash\nf codex doctor --path ~/docs --assert-runtime\nf codex doctor --path ~/docs --assert-schedule\nf codex doctor --path ~/docs --assert-learning\nf codex doctor --path ~/docs --assert-autonomous\n```\n\n`--assert-learning` is intentionally strict: it fails until Flow has real\nlogged events, grounded outcome samples, and a non-empty scorecard for that\ntarget.\n\nBuilt-in plan writer:\n\n```bash\ncat <<'EOF' | f codex runtime write-plan --title \"Example Plan\"\n# Example Plan\n\n- item\nEOF\n```\n\nBy default this writes to today's `~/docs/plan/<day-of-month>/` bucket, for\nexample `~/docs/plan/23/` on the 23rd day of the month.\n\nCompleted `j` sessions are also mirrored automatically into `~/log/.ai/docs/session-changes/`\nthrough `jd`, so durable home-log notes exist even when a repo-local `.ai/docs/`\npromotion never happens.\n\n### Run-owned agent bridge\n\nFlow can execute run-owned Codex agents directly without copying their specs or\nprompts into `~/code/flow`.\n\nUseful commands:\n\n```bash\nf codex agent list\nf codex agent list --json\nf codex agent show commit\nf codex agent run planner --path ~/code/flow \"make a 3 phase rollout plan\"\nf codex agent run commit --path ~/repos/openai/codex \"review the current diff and draft a safe commit\"\nf codex agent run planner --json --path ~/code/flow \"reply with exactly: ok\"\n```\n\nBehavior:\n\n- Flow bridges into `~/run/scripts/agent-router.sh`\n- the run-owned agent still executes through its own spec/runtime path in `~/run`\n- `--path` controls the repo/worktree cwd used for the agent run\n- `run` returns the agent's final output plus any durable artifact/trace paths\n- `f codex doctor --path <repo>` reports whether the run-agent bridge is ready\n\nRepo-local readiness check:\n\n```bash\nf codex doctor --path ~/code/flow --assert-runtime --assert-schedule\nf codex skill-source list --path ~/code/flow\nf codex agent list\n```\n\n### Skill eval and background refresh\n\nFlow can learn which runtime skills are actually worth injecting from local\nCodex usage history without replaying Codex in the hot path.\n\nUseful commands:\n\n```bash\nf codex eval --path ~/work/example-project\nf codex memory sync --limit 400\nf codex memory recent --path ~/work/example-project --limit 12\nf codex skill-eval show --path ~/work/example-project\nf codex skill-eval run --path ~/work/example-project\nf codex skill-eval cron --limit 400 --max-targets 12 --within-hours 168\nf codex telemetry status\nf codex telemetry flush --limit 200\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\nf codex project-ai show --path ~/work/example-project --json\nf codex project-ai recent --limit 12 --json\nf codex skill-source list --path ~/work/example-project\nf codex skill-source sync --path ~/work/example-project --skill find-skills\nf codex agent list\nf codex agent run planner --path ~/work/example-project \"summarize the next rollout slice\"\n```\n\nThe Codex memory mirror:\n\n- stores durable indexed memory under the Jazz2 root (`~/.jazz2/...` or `~/repos/garden-co/jazz2/.jazz2/...`)\n- mirrors Flow’s route/outcome history into SQLite with WAL enabled\n- extracts compact repo/code facts from repo capsules (summary, commands, important paths, docs hints)\n- adds bounded live code-path retrieval for explicit repo references, so prompts like `see ~/code/flow ...` can inject likely files such as `src/ai.rs` or `docs/...` without dumping raw source\n- indexes durable repo entrypoints and extracted symbols under the same Jazz2-rooted memory store, then supplements them with live symbol extraction from the top-ranked code files during `memory query` / `codex resolve`\n- adds tiny symbol snippets for the top code hits, so coding prompts can carry actual struct/function shape without inlining whole files\n- biases retrieval by intent: implementation/file-edit prompts prefer symbols, snippets, and `src/...` paths; summary/docs prompts prefer doc headings and docs paths\n- stays best-effort so failed memory writes do not block normal Codex coding turns\n\nThe project-ai manifest:\n\n- gives `jd` a bounded metadata view of repo-local `.ai/` scaffolding\n- records counts and latest paths for skills, docs, reviews, tasks, and todos\n- keeps default context fill minimal by exposing only compact hints, not raw content\n- tracks query counts and recent repo usage so you can see whether the feature is actually being used\n- is refreshed again by `f codex skill-eval cron`, so the mirror heals even if a hot-path write is skipped\n- is queried automatically for explicit repo references during `f codex open` / `f codex resolve`\n\nWhat `cron` does:\n\n- scans only recent logged Flow Codex events\n- syncs recent skill-eval logs into the Jazz2-backed memory mirror\n- skips missing/moved repo paths\n- rebuilds scorecards for a bounded number of recent repos\n- never launches Codex or replays network work in the background\n\nFor your use case, this keeps learning cheap and safe enough to run regularly.\n\n### Trace inspection for Flow-managed Codex sessions\n\nFlow now assigns a trace envelope to all Flow-managed Codex launches, not just\nspecial workflows like `check <github-pr-url>`.\n\nThat means sessions started or resumed through:\n\n```bash\nj ...\nk <session-id>\nf codex open ...\nf codex resume ...\nf codex continue ...\n```\n\ncarry `FLOW_TRACE_*` env vars and emit at least one compact Flow telemetry\nevent, so the session becomes remotely inspectable.\n\nUseful commands:\n\n```bash\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\n```\n\nBehavior:\n\n- `trace status` checks whether Maple MCP reads are configured and reachable\n- `trace current-session` reads the active `FLOW_TRACE_ID` from the current\n  Flow-managed Codex session, flushes recent Flow telemetry once, then attempts\n  a remote trace read\n- if Maple reads are partially configured but tenant access is still blocked,\n  Flow returns the current trace metadata plus `readError` instead of failing\n  without context\n\nThis keeps the workflow autonomous from inside Codex itself: once the session\nwas started through Flow, you can inspect the current trace without manually\ncopying ids.\n\n`f codex eval --path ...` is the joined operator report:\n\n- current runtime/doctor state\n- recent route mix and context cost\n- grounded skill scorecard highlights\n- concrete “what to improve next” recommendations\n- commands to deepen or fix the current state\n\nIf `jd` is running, it also keeps recent completion reconciliation warm and\nnow does a bounded background scorecard refresh, so the eval report does not go\nstale as quickly between manual runs.\n\nIf the native session bridge skill is installed, `jd` also prewarms compact\nhandoff capsules for recent native Codex sessions whenever the Codex state DB\nchanges. That keeps the exact handoff path cheap, so pasting\n`019d... codex session` into another chat is usually already a warm cache hit\ninstead of the first lookup having to build the capsule from the rollout.\n\nOptional telemetry export follows the same local-first pattern: Flow keeps\nlocal Codex logs canonical, and if `FLOW_CODEX_MAPLE_*` env vars are set it can\nexport redacted route/context/outcome spans to Maple without shipping raw\nprompts or full repo paths. Use:\n\n```bash\nf codex telemetry status\nf codex telemetry flush --limit 200\n```\n\nFor local-only secrets, prefer `f env set --personal ...`. On macOS you may\nneed `f env unlock` once per day for background reads. Flow-launched Codex\nsessions also inherit the same `FLOW_CODEX_MAPLE_*` values from the personal\nstore, while explicit shell env still wins for one-off tests.\n\nWhen `jd` is running, the daemon also performs a bounded background export\npass so the external analytics view stays warm.\n\n### macOS launchd schedule for skill-eval\n\nIf you want scorecards to stay fresh automatically on macOS:\n\n```bash\nf codex-skill-eval-launchd-install\nf codex-skill-eval-launchd-status\nf codex-skill-eval-launchd-logs\n```\n\n`f codex enable-global --full` installs this schedule for you.\n\nDefault schedule:\n\n- every 30 minutes\n- scan up to 400 recent events\n- rebuild up to 12 recent repo scorecards\n- ignore repos not seen in the last 168 hours\n\nYou can tune install-time bounds:\n\n```bash\nf codex-skill-eval-launchd-install --minutes 20 --limit 600 --max-targets 16 --within-hours 72\nf codex-skill-eval-launchd-install --dry-run\n```\n\nRemove it with:\n\n```bash\nf codex-skill-eval-launchd-uninstall\n```\n\n### Cursor behavior\n\nCursor transcripts are read-only in Flow:\n\n- `f ai cursor list` opens a picker and copies the selected transcript\n- `f ai cursor copy` copies the latest Cursor transcript for this repo\n- `f ai cursor context ...` copies the last N exchanges\n- `f cursor ...` is a shortcut for the same provider-specific read commands\n\n### Cross-directory resume\n\nYou can target another repo without changing directory:\n\n```bash\nf ai codex resume --path ~/work/example-project\nf ai codex resume --path ~/work/example-project 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai codex continue --path ~/work/example-project\n```\n\n- `resume --path <repo>` resolves the requested session against that repo instead of the current cwd\n- `continue --path <repo>` resumes the latest session for that repo\n- explicit full Codex IDs still work directly even when your current cwd is different\n\n## Session Selectors\n\n`resume` accepts:\n\n- saved alias from `.ai/sessions/claude/index.json`\n- full session ID\n- ID prefix (8+ chars)\n- numeric index from list output (1-based)\n\nExamples:\n\n```bash\nf ai resume my-feature\nf ai resume a38cf8bf\nf ai claude resume 2\nf ai codex resume 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai cursor context 382ef1a3 /path/to/repo 2\n```\n\n## Content Copy Commands\n\n```bash\n# Copy full conversation to clipboard\nf ai copy\nf ai copy <session>\n\n# Copy last N prompt/response turns\nf ai context\nf ai context <session> <path> <count>\n```\n\nUse `-` as session placeholder to trigger fuzzy selection:\n\n```bash\nf ai claude context - /path/to/repo 3\nf ai cursor context - /path/to/repo 3\n```\n\n## Project Workflow (Recommended)\n\n1. Start from repo root and inspect tasks:\n   `f tasks list`\n2. Resume exact session when continuing prior work:\n   `f ai claude resume <id>` or `f ai codex resume <id>`\n3. Keep context current:\n   `f skills sync` then `f skills reload`\n4. Validate through tasks:\n   `f test-related` / `f test`\n5. Commit through Flow gates:\n   `f commit`\n\nThis keeps sessions, tasks, skills, and commit quality checks in one loop.\n\n## Everruns Bridge Mode\n\nFlow also supports running a prompt through Everruns while routing client-side\n`seq_*` tool calls to local `seqd`:\n\n```bash\nf ai everruns \"open Safari and take a screenshot\"\n```\n\nKey points:\n\n- This path is additive. It does not replace `f ai claude ...` or `f ai codex ...`.\n- Flow now reuses Seq's canonical Everruns bridge for:\n  - `seq_*` tool definitions injected into new sessions\n  - tool-name normalization (`seq_open_app`, `seq.open_app`, `seq:open-app`)\n  - request correlation IDs (`request_id`, `run_id`, `tool_call_id`)\n- Event transport is SSE-first (`/sse`) with automatic fallback to polling (`/events`) if SSE is unavailable.\n- Optional Maple telemetry export can dual-write runtime traces to local + hosted ingest endpoints when `SEQ_EVERRUNS_MAPLE_*` env vars are configured.\n- Existing Flow features remain unchanged (`f seq-rpc`, session resume/copy/context flows).\n\nSetup and validation details are documented in:\n\n- `docs/everruns-seq-bridge-integration.md`\n- `docs/everruns-maple-runbook.md`\n","docs/commands/clone.md":"# f clone\n\nClone a repository with git-like destination behavior.\n\n## Overview\n\n`f clone` behaves like `git clone` for destination paths:\n\n- `f clone <url>` clones into the current working directory using Git's default folder naming.\n- `f clone <url> <dir>` clones into an explicit destination directory.\n\nFor GitHub inputs, Flow normalizes clone URLs to SSH:\n\n- `https://github.com/owner/repo` -> `git@github.com:owner/repo.git`\n- `owner/repo` -> `git@github.com:owner/repo.git`\n\nThis command does not force clones into `~/repos` and does not auto-configure `upstream`.\n\n## Usage\n\n```bash\nf clone <url-or-owner/repo> [directory]\n```\n\n## Examples\n\n```bash\n# GitHub URL -> SSH clone URL\nf clone https://github.com/genxai/new\n\n# owner/repo shorthand -> SSH clone URL\nf clone genxai/new\n\n# explicit destination folder (same as git clone)\nf clone genxai/new my-local-new\n```\n\n## When To Use\n\n- Use `f clone` when you want standard `git clone` destination behavior.\n- Use [`f repos clone`](repos.md) when you want managed placement under `~/repos/<owner>/<repo>` plus optional upstream automation.\n","docs/commands/commit.md":"# f commit\n\nAI-powered commit with deferred Codex review and GitEdit sync.\n\n## Overview\n\nStages all changes, commits quickly by default, runs Codex deep review asynchronously in the background, pushes, and syncs AI sessions to gitedit.dev.\n\n## Quick Start\n\n```bash\n# Default flow: commit now, Codex review runs in background\nf commit\n\n# Blocking pre-commit review (legacy behavior)\nf commit --slow\n\n# Fast commit with custom message (no AI review, no Codex follow-up)\nf commit --fast \"fix typo\"\nf commit --fast  # defaults to \".\" as message\n\n# Queue for review (no push) + create jj review bookmark\nf commit --queue\n\n# Commit without pushing\nf commit -n\n\n# Include AI context in review\nf commit --context\n\n# Custom message\nf commit -m \"Fixes #123\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--no-push` | `-n` | Skip pushing after commit |\n| `--queue` | | Queue the commit for review (no push) |\n| `--no-queue` | | Bypass queue and allow push |\n| `--sync` | | Run synchronously (don't delegate to hub) |\n| `--context` | | Include AI session context in code review |\n| `--dry` | | Dry run: show context without committing |\n| `--quick` | | Explicitly use fast commit + async Codex review (compat alias) |\n| `--slow` | | Run blocking pre-commit review before commit |\n| `--fast [MSG]` | | Fast commit with no AI review (defaults to \".\") |\n| `--codex` | | Use Codex instead of Claude for review |\n| `--review-model <MODEL>` | | Choose specific review model |\n| `--message <MSG>` | `-m` | Custom message appended to commit |\n| `--tokens <N>` | `-t` | Max tokens for AI context (default: 1000) |\n\n## Review Models\n\n| Model | Description |\n|-------|-------------|\n| `claude-opus` | Claude Opus 1 for review (default) |\n| `codex-high` | Codex high-capacity (gpt-5.1-codex-max) |\n| `codex-mini` | Codex mini (gpt-5.1-codex-mini) |\n\n```bash\n# Use Codex\nf commit --codex\n\n# Specific model\nf commit --review-model codex-high\n```\n\n---\n\n## Fast Commit + Deferred Codex Review\n\n`f commit` now uses this mode by default.\n\n### Default (`f commit`) / `--quick` — commit now, Codex reviews later\n\nCommits immediately (generates an AI commit message but skips the blocking code review), then spawns a background Codex review for that commit. The review result is queued and visible via `f commit-queue list`.\n\n```bash\nf commit\nf commit --quick\n```\n\nWhat happens:\n1. Stages all changes, generates commit message, commits, pushes\n2. Queues the commit SHA for async review\n3. Spawns a background Codex process that reviews the diff\n4. You keep working — check results later with `f commit-queue list`\n\n### `--slow` — run blocking review before commit\n\nRuns the pre-commit AI review before creating the commit.\n\n```bash\nf commit --slow\nf commit --slow --review-model codex-high\n```\n\n### `--fast` — instant commit, no review at all\n\nCommits with a provided message (or `\".\"` if omitted). No AI review, no async follow-up. Useful for trivial changes.\n\n```bash\nf commit --fast \"fix typo\"\nf commit --fast              # message defaults to \".\"\n```\n\n### When to use which\n\n| Flag | AI message | Code review | Async review | Best for |\n|------|-----------|-------------|-------------|----------|\n| (none) | Yes | No | Yes (Codex background) | Default fast workflow |\n| `--quick` | Yes | No | Yes (Codex background) | Explicit fast mode |\n| `--slow` | Yes | Yes (blocking) | No | Pre-commit deep check |\n| `--fast` | No (you provide) | No | No | Trivial/WIP commits |\n\n### Opt Out Of Fast Default\n\nIf you want plain `f commit` to run blocking review by default, set:\n\n```toml\n[commit]\nquick-default = false\n```\n\nWith this set, plain `f commit` behaves like `f commit --slow` unless you explicitly pass `--quick`.\n\nRun deep review in batches:\n\n```bash\nf reviews-todo codex --all\nf reviews-todo list\n```\n\n### Myflow Fast + Deep Profile\n\nFor `~/code/myflow`, this profile gives a fast default loop while keeping deep Codex coverage:\n\n```toml\n[commit]\nquick-default = true\nqueue = false\nqueue_on_issues = false\n\n# Fast message generation path via zerg/ai (glm + cerebras), then fallbacks.\nmessage_fallbacks = [\n  \"rise:zai:glm-5\",\n  \"rise:cerebras:gpt-oss-120b\",\n  \"remote\",\n  \"openai\"\n]\n\n# When you explicitly run blocking review, prefer fast models first.\nreview_fallbacks = [\n  \"glm5\",\n  \"rise:cerebras:gpt-oss-120b\",\n  \"codex-high\"\n]\n```\n\nThen operate with:\n\n```bash\nf commit\nf reviews-todo codex --all\n```\n\n---\n\n## What Happens\n\n1. **Safety Checks**\n   - Warns about sensitive files (.env, .pem, keys, credentials)\n   - Warns about files with large diffs (500+ lines)\n   - Runs invariant checks from `[invariants]` when configured\n\n2. **Stage Changes**\n   - Runs `git add -A` to stage all changes\n\n3. **Code Review**\n   - Sends diff to AI for review\n   - Checks for bugs, security issues, best practices\n   - Optionally includes AI session context (`--context`)\n\n4. **Generate Message**\n   - AI generates commit message from diff\n   - Appends custom message if provided (`-m`)\n\n5. **Commit**\n   - Creates commit with generated message\n\n6. **Queue (optional)**\n   - Adds commit to the review queue (`f commit-queue list`)\n   - Creates a jj review bookmark (e.g., `review/main-<sha>`)\n\n7. **Push**\n   - Pushes to remote (unless `--no-push` or `--queue`)\n\n7. **GitEdit Sync**\n   - Syncs AI session data to gitedit.dev\n\n## Invariant Gate\n\nIf your project defines `[invariants]` in `flow.toml`, `f commit` evaluates the staged diff against those rules (forbidden patterns, dependency allowlist policy, file line limits).\n\n- `mode = \"warn\"`: commit continues and findings are shown.\n- `mode = \"block\"`: commit is blocked on warning/critical findings.\n- Findings are injected into the AI review context.\n\n---\n\n## Usage Examples\n\n### Basic Commit\n\n```bash\n# Review, commit, and push\nf commit\n```\n\n### Local Commit Only\n\n```bash\n# Don't push to remote\nf commit -n\n```\n\n### With AI Context\n\nInclude recent AI session context in the review:\n\n```bash\nf commit --context\nf commit --context --tokens 2000  # More context\n```\n\n### Custom Message\n\nAppend additional context to the commit:\n\n```bash\nf commit -m \"Fixes #123\"\nf commit -m \"Co-authored-by: John <john@example.com>\"\n```\n\n### Dry Run\n\nSee what would be reviewed without committing:\n\n```bash\nf commit --dry\n```\n\n### Synchronous Mode\n\nRun directly without delegating to hub:\n\n```bash\nf commit --sync\n```\n\n---\n\n## Safety Warnings\n\n### Sensitive Files\n\nBefore committing, flow warns if staging files that look sensitive:\n\n```\n⚠ Warning: The following sensitive files are staged:\n  - .env\n  - credentials.json\n  - private.key\n```\n\nSensitive patterns include:\n- `.env`, `.env.*`\n- `credentials.json`, `secrets.json`\n- `.pem`, `.key`, `id_rsa`, `id_ed25519`\n- Files containing `password`, `secret`, `token`\n\n### Secret Scan (Staged Diff)\n\nFlow scans staged diffs for likely secrets (API keys, tokens, passwords). If a match\nis detected, the commit is blocked. In an interactive terminal, flow offers to run\nan auto-fix using `ai` to mask or replace the values, then asks for approval to\ncontinue.\n\nYou can bypass the check for a single commit with:\n\n```\nFLOW_ALLOW_SECRET_COMMIT=1 f commit\n```\n\n### Large Diffs\n\nWarns about files with significant changes:\n\n```\n⚠ Warning: The following files have large diffs:\n  - src/generated.rs (1523 lines)\n  - data/fixtures.json (834 lines)\n```\n\nThreshold: 500+ lines added/removed.\n\n---\n\n## Related Commands\n\n| Command | Description |\n|---------|-------------|\n| `f commit` | Fast commit + deferred Codex review (default) |\n| `f commitWithCheck` | Review without GitEdit sync |\n| `f commitSimple` | No review, just AI commit message |\n\n### commitWithCheck (alias: cc)\n\nSame as `commit` but skips GitEdit sync:\n\n```bash\nf commitWithCheck\nf cc  # Short alias\n```\n\n### commitSimple\n\nQuick commit without code review:\n\n```bash\nf commitSimple\n```\n\n---\n\n## Configuration\n\n### Hub Delegation\n\nBy default, `f commit` delegates to the hub daemon for async processing. Use `--sync` for direct execution:\n\n```bash\n# Async via hub (default)\nf commit\n\n# Sync (direct)\nf commit --sync\n```\n\n### Commit Message Tool\n\nOptionally force a specific commit-message generator:\n\n```toml\n[commit]\nmessage_tool = \"kimi\" # also supports: claude, rise, glm5, opencode, openrouter, remote, openai\nmessage_model = \"kimi-k2-thinking-turbo\" # optional, tool-specific\n```\n\nIf the forced tool fails, `f commit` now falls back through the configured/default chain.\n\n### Review Tool (Kimi CLI)\n\nUse Kimi Code CLI for code review:\n\n```toml\n[review]\ntool = \"kimi\"\nmodel = \"kimi-k2-thinking-turbo\" # optional; uses Kimi default if omitted\n```\n\nThis uses `kimi --quiet` (print mode) with your existing Kimi CLI auth/config.\n\n### Robust Fallbacks\n\n`f commit` now uses multi-attempt fallback chains for both review and commit-message generation.\n\nDefault behavior:\n- Review: primary selection, then `openrouter`, `claude`, `codex-high`\n- Message: review-aligned/override tool, then `remote` (myflow), `openai`, `openrouter`\n- If all message attempts fail and fail-open is enabled, Flow uses a deterministic local fallback message.\n\nConfiguration:\n\n```toml\n[commit]\nreview_fail_open = true\nmessage_fail_open = true\nreview_fallbacks = [\"openrouter\", \"claude\", \"codex-high\"]\nmessage_fallbacks = [\"remote\", \"openai\", \"openrouter\"]\n```\n\nEnvironment overrides:\n- `FLOW_COMMIT_REVIEW_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_MESSAGE_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_REVIEW_FALLBACKS=\"openrouter,claude,codex-high\"`\n- `FLOW_COMMIT_MESSAGE_FALLBACKS=\"remote,openai,openrouter\"`\n\nCodex -> GLM5 fallback example:\n\n```toml\n[commit]\nreview_fallbacks = [\"glm5\", \"openrouter\", \"claude\"]\nmessage_fallbacks = [\"glm5\", \"remote\", \"openai\"]\n```\n\n`glm5` maps to the Rise/internal route with model `zai:glm-5`.\n\n### Queue Policy\n\nQueue only when review finds issues (auto-push on a clean review):\n\n```toml\n[commit]\nqueue = true\nqueue_on_issues = true\n```\n\n`--queue` / `--no-queue` still override this behavior.\n\n### Commit Quality Gates (Testing + Required Skills)\n\nUse local gates to block commits that skip tests or required workflow skills:\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\nWhen `mode = \"block\"`, `f commit` fails until the test/skill requirements are satisfied.  \nFor Bun repos, run checks with `bun bd test ...` for debug-build validation. If no related tracked tests are found, Flow can run tests under `ai_scratch_test_dir` (default `.ai/test`) as a fallback signal.\n\n### AI Session Context\n\nWhen `--context` is enabled, includes recent Claude Code session context:\n\n```bash\n# Default: 1000 tokens of context\nf commit --context\n\n# More context\nf commit --context --tokens 3000\n```\n\n---\n\n## Examples\n\n### Quick Bug Fix\n\n```bash\n# Fix bug, commit with context\nvim src/lib.rs\nf commit --context -m \"Fixes null pointer in edge case\"\n```\n\n### Feature Branch\n\n```bash\n# Work on feature\ngit checkout -b feature/new-api\n# ... make changes ...\n\n# Commit without push\nf commit -n\n\n# More changes...\nf commit -n\n\n# Final push\ngit push -u origin feature/new-api\n```\n\n### Review Before Commit\n\n```bash\n# See what would be reviewed\nf commit --dry\n\n# If satisfied, commit\nf commit\n```\n\n---\n\n## Troubleshooting\n\n### \"Sensitive files staged\"\n\nEither:\n1. Add files to `.gitignore`\n2. Unstage with `git reset HEAD <file>`\n3. Proceed anyway if intentional\n\n### Review taking too long\n\nUse `--sync` to see progress directly:\n```bash\nf commit --sync\n```\n\n### Hub not responding\n\nFall back to sync mode:\n```bash\nf commit --sync\n```\n\n## See Also\n\n- [upstream](upstream.md) - Sync forks before committing\n- [publish](publish.md) - Publish after committing\n","docs/commands/commits.md":"# f commits\n\nBrowse commits with AI metadata and mark notable commits for quick access.\n\n## Usage\n\n```bash\nf commits\nf commits --limit 200\nf commits --all\nf commits top\nf commits mark <hash>\nf commits unmark <hash>\n```\n\n## Notable commits\n\nNotable commits are stored in `.ai/internal/commits/top.txt` in the repo root. Each line is:\n\n```\n<full-hash>\\t<label>\n```\n\n## Key bindings\n\nWhen using fzf:\n\n- `ctrl-t` — toggle notable for the selected commit.\n","docs/commands/config.md":"# f config\n\nCompile the personal Flow root config and generated compatibility outputs.\n\nSource of truth:\n\n- `~/.flow/config.ts`\n\nGenerated outputs:\n\n- `~/.config/flow/generated/config.snapshot.json`\n- `~/.config/flow/generated/flow/config.ts`\n- `~/.config/flow/generated/lin/config.ts`\n- `~/.config/flow/generated/lin/intents.json`\n- `~/.config/flow/generated/lin/mac.toml`\n- `~/.config/flow/generated/ai/config.json`\n\nHive config may still appear in the effective root config during migration, but Flow no longer emits or applies `~/.hive/config.json`.\n\nIf `~/.flow/config.ts` does not exist yet, Flow currently falls back to:\n\n- `~/config/i/lin/config.ts`\n\nand generates a starter `~/.flow/config.ts` migration file on apply.\n\n## Commands\n\n### f config doctor\n\nShows whether the root config exists, whether a TypeScript runner is available,\nwhether a generated snapshot already exists, and what extension directories are discoverable.\n\n```bash\nf config doctor\nf config doctor --json\n```\n\n### f config build\n\nLoads the root config plus named extensions, computes the merged effective config,\nand writes generated artifacts under `~/.config/flow/generated/`.\n\nThis does not overwrite consumer config locations.\n\n```bash\nf config build\nf config build --json\n```\n\n### f config apply\n\nBuilds the snapshot and then applies the generated compatibility files into their\nconsumer locations. This is the cutover step that keeps existing tools working while\nmoving authoring into `~/.flow/config.ts`.\n\n```bash\nf config apply\nf config apply --json\n```\n\n### f config eval\n\nPrints the currently effective merged config view. If no snapshot exists yet, Flow\nbuilds one first.\n\n```bash\nf config eval\nf config eval --json\n```\n\n## Root Config Shape\n\nThe first supported root-config shape is:\n\n```ts\nexport default {\n  flow: { ... },\n  lin: { ... },\n  ai: { ... },\n  hive: { ... }, // parsed for migration compatibility, not applied to ~/.hive\n  zerg: { ... },\n  extensions: [\"lin-compat\"],\n}\n```\n\nFilesystem extensions can live under:\n\n- `~/.flow/extensions/<name>/extension.ts`\n- `~/.flow/extensions/<name>/config.ts`\n\nEach extension can contribute partial config fragments plus optional generated files.\n\n## Notes\n\n- Flow currently ships one built-in extension name: `lin-compat`\n- explicit extensions must exist or `f config build` fails\n- generated outputs are written atomically\n- if a `hive` section is present, `f config build/apply/eval` warns that Hive output is deprecated and ignored\n","docs/commands/db.md":"# db\n\nManage database workflows and backends (Jazz + Postgres).\n\n## Usage\n\n```bash\nf db <provider> <action>\n```\n\n## Jazz\n\nCreate Jazz2 app credentials and populate env vars for the current project.\n\n```bash\nf db jazz new --kind mirror --name gitedit-mirror\n```\n\nResolution order for the credential bootstrap helper:\n\n1. Local `jazz-tools` binary on `PATH`\n2. Pinned `npx --yes jazz-tools@0.20.14`\n\nFor deliberate experiments, override the pinned fallback with:\n\n```bash\nFLOW_JAZZ_TOOLS_PACKAGE_SPEC=jazz-tools@<version> f db jazz new --kind mirror\n```\n\n## Postgres\n\nRun Drizzle migrations for the default Postgres project (`~/org/la/la/server`).\n\n```bash\nf db postgres migrate\nf db postgres migrate --generate\nf db postgres generate\n```\n\nEnvironment resolution order for `DATABASE_URL`:\n\n1. `--database-url` flag\n2. `DATABASE_URL`\n3. `PLANETSCALE_DATABASE_URL` / `PSCALE_DATABASE_URL`\n4. `<project>/.env` (DATABASE_URL)\n\nUse `--project` to override the Postgres project directory.\n","docs/commands/deploy.md":"# f deploy\n\nDeploy projects to hosts and cloud platforms.\n\n## Overview\n\nThe `deploy` command handles deployment to multiple platforms:\n- **Linux hosts** via SSH (with systemd + nginx)\n- **Cloudflare Workers**\n- **Railway**\n\nAuto-detects the platform from your `flow.toml` configuration.\nIf `[flow].deploy_task` is set, `f deploy` runs that task first.\nIf no deployment config exists but a `deploy` task is defined, `f deploy` runs that task.\nUse `f prod` to deploy directly from `[host]`, `[cloudflare]`, `[railway]`, or `[web]` (it skips `[flow].deploy_task`).\n\n## Quick Start\n\n```bash\n# Auto-deploy based on flow.toml config\nf deploy\n\n# Production deploy (skips flow.deploy_task, uses deploy config or deploy-prod task)\nf prod\n\n# Run the project's release task (flow.release_task or fallback)\nf deploy release\n\n# Deploy to specific platform\nf deploy host\nf deploy cloudflare\nf deploy railway\n\n# Production deploy to specific platform\nf prod host\nf prod cloudflare\n\n# Configure deployment defaults\nf deploy config\n\n# Deploy web site\nf deploy web\n```\n\n## Subcommands\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `host` | `h` | Deploy to Linux host via SSH |\n| `cloudflare` | `cf` | Deploy to Cloudflare Workers |\n| `web` | | Deploy the web site (Cloudflare) |\n| `setup` | | Interactive deploy setup (Cloudflare) |\n| `railway` | | Deploy to Railway |\n| `config` | | Configure deployment defaults (Linux host) |\n| `release` | | Run the project's release task |\n| `status` | | Show deployment status |\n| `logs` | | View deployment logs |\n| `restart` | | Restart the deployed service |\n| `stop` | | Stop the deployed service |\n| `shell` | | SSH into the host |\n| `set-host` | `set` | Configure host for deployment |\n| `show-host` | | Show current host configuration |\n| `health` | | Check if deployment is healthy |\n\n---\n\n## Web Deployment\n\nDeploys the web site using Cloudflare and your project tasks. Flow will:\n- Ensure `[web]` exists in `flow.toml` (auto-fills `path` when possible).\n- Add the `web.route` (or `web.domain/*`) to your wrangler config.\n- Optionally create/update the Cloudflare DNS record for the domain/route.\n- Apply env vars from cloud if `web.env_source = \"cloud\"` is set.\n- Run `deploy-web` (or `deploy` as fallback).\n\n```bash\nf deploy web\n```\n\nIf the Cloudflare API token is missing, Flow will guide you to create one and\nstore it in your env store as `CLOUDFLARE_API_TOKEN`.\n\nIf `web.domain`/`web.route` or `web.path` is missing, Flow will prompt for them\nand update `flow.toml`.\n\nIf you opt into DNS management, Flow will prompt for record type/target and\ncreate or update the Cloudflare DNS record (default: `A` to `192.0.2.1`,\nproxied).\n\nIf cloud is unavailable, Flow can store envs locally when you choose\n`web.env_source = \"local\"`.\n\nExample `flow.toml`:\n\n```toml\n[web]\npath = \"packages/web\"\ndomain = \"example.com\"\nenv_source = \"cloud\"\nenv_apply = \"always\"\nenv_keys = [\"PUBLIC_API_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\n## Host Deployment (Linux via SSH)\n\nDeploy to any Linux server with SSH access. Flow handles:\n- File syncing via rsync\n- Systemd service creation\n- Nginx reverse proxy setup\n- SSL via Let's Encrypt\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[flow]\ndeploy_task = \"deploy-cli-release\"\n\n[host]\ndest = \"/opt/myapp\"           # Remote destination path\nrun = \"./server\"              # Command to run the service\nport = 3000                   # Port the service listens on\nservice = \"myapp\"             # Systemd service name (optional, defaults to folder name)\nsetup = \"./scripts/setup.sh\"  # Setup script to run after first sync (optional)\nenv_file = \".env.production\"  # Path to .env file for secrets (optional)\nenv_source = \"flow\"           # Pull envs from Flow env store (optional)\nenv_keys = [\"API_KEY\"]        # Keys to fetch when env_source=flow/cloud (optional)\ndomain = \"myapp.example.com\"  # Public domain for nginx (optional)\nssl = true                    # Enable SSL via Let's Encrypt (optional)\n```\n\nTip: `f setup deploy` can scaffold the `[host]` section and create a remote setup script.\n\n### Setup Host\n\nFirst, configure your SSH connection:\n\n```bash\n# Set host (stored globally at ~/.config/flow/deploy.json)\nf deploy set-host user@host:port\nf deploy set-host deploy@myserver.com:22\nf deploy set-host root@192.168.1.100\n\n# Interactive config (prefills from ~/.config/infra/config.json if present)\nf deploy config\n\n# Verify connection\nf deploy shell\n```\n\n### Deploy\n\n```bash\n# Deploy to host\nf deploy host\n\n# Force re-run setup script\nf deploy host --setup\n\n# Build remotely instead of syncing local artifacts\nf deploy host --remote-build\n```\n\n### What Happens\n\n1. **Sync files** - rsync uploads project (excludes `target/`, `.git/`, `node_modules/`, `.env`, `*.log`)\n2. **Copy env file** - If `env_file` is specified, copies it to `{dest}/.env`\n   (or, if `env_source = \"flow\"`, fetches from Flow env store and writes `{dest}/.env`)\n3. **Run setup** - Executes setup script on first deploy or with `--setup`\n4. **Create systemd service** - Generates and enables `/etc/systemd/system/{service}.service`\n5. **Configure nginx** - If `domain` is set, creates reverse proxy config\n6. **Setup SSL** - If `ssl = true`, runs certbot for Let's Encrypt certificate\n7. **Start service** - Runs `systemctl restart {service}`\n\n### Manage Service\n\n```bash\n# View logs\nf deploy logs                 # Since last deploy (host only)\nf deploy logs -f              # Follow in real-time (since last deploy)\nf deploy logs --all           # Full history (ignore deploy marker)\nf deploy logs --all -n 500    # Show last 500 lines without deploy filter\n\n# Restart/stop\nf deploy restart\nf deploy stop\n\n# Check status\nf deploy status\n\n# SSH into server\nf deploy shell\n\n# Health check\nf deploy health\nf deploy health --url https://myapp.example.com/health\nf deploy health --status 204  # Expect specific status code\n```\n\nNote: For host deploys, Flow records the last successful deploy time in `.flow/deploy-log.json` and uses it to scope `f deploy logs` output. Use `--all` to ignore it.\n\n---\n\n## Cloudflare Workers\n\nDeploy to Cloudflare's edge network.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[cloudflare]\npath = \"worker\"                    # Path to worker directory (optional, defaults to project root)\nenvironment = \"production\"         # Wrangler environment name (optional)\nenv_file = \".env.cloudflare\"       # Path to .env file for secrets (optional)\nenv_source = \"cloud\"              # Use cloud or local env store for secrets (optional)\nenv_keys = [\"API_KEY\", \"SECRET\"]   # Specific keys to fetch from env store (optional)\nenv_vars = [\"PUBLIC_URL\"]          # Keys to set as non-secret vars (optional)\ndeploy = \"wrangler deploy\"         # Custom deploy command (optional)\ndev = \"wrangler dev\"               # Custom dev command (optional)\nurl = \"https://my-worker.workers.dev\"  # URL for health checks (optional)\n```\n\n### Prerequisites\n\n- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) installed\n- `wrangler.toml` in your worker directory\n- Authenticated with `wrangler login`\n\n### Deploy\n\n```bash\n# Deploy\nf deploy cloudflare\n\n# Deploy with secrets from env_file\nf deploy cloudflare --secrets\n\n# Run in dev mode\nf deploy cloudflare --dev\n```\n\n### Production domain (for `f prod`)\n\nUse `[prod]` to set a production domain or route for Workers. `f prod` will add\nthe route to your `wrangler.json/jsonc` before deploying.\n\n```toml\n[prod]\ndomain = \"anysynth.nikiv.com\"   # Will be mapped to route \"anysynth.nikiv.com/*\"\n# route = \"anysynth.nikiv.com/*\"  # Use this for explicit patterns\n```\n\n### Interactive Setup\n\nFor first-time setup, use the interactive wizard:\n\n```bash\nf deploy setup\n```\n\nThis walks you through:\n1. Selecting worker directory (auto-discovers `wrangler.toml`)\n2. Choosing .env file for secrets\n3. Selecting Cloudflare environment (production, staging, etc.)\n4. Picking which secrets to push\n5. Updating `flow.toml` with your choices\n\nIf your `flow.toml` lists service keys (for example Stripe keys), the setup flow\nwill offer to run the matching service onboarding before applying envs.\n\n### Secrets from cloud\n\nIf using cloud for secret management:\n\n```toml\n[cloudflare]\nenv_source = \"cloud\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"]  # Fetched as secrets\nenv_vars = [\"PUBLIC_API_URL\"]                      # Fetched as non-secret vars\nenvironment = \"production\"\n```\n\nThen deploy:\n\n```bash\nf deploy cloudflare --secrets\n```\n\nIf you want to use local Flow envs instead:\n\n```toml\n[cloudflare]\nenv_source = \"local\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\nIf you need to fill missing values first:\n\n```bash\nf env guide\n```\n\n---\n\n## Railway\n\nDeploy to Railway's platform.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[railway]\nproject = \"my-project\"         # Railway project ID\nservice = \"api\"                # Service name (optional)\nenvironment = \"production\"     # Environment name (optional)\nstart = \"npm start\"            # Start command (optional)\nenv_file = \".env.railway\"      # Path to .env file (optional)\n```\n\n### Prerequisites\n\n- [Railway CLI](https://docs.railway.app/develop/cli) installed (`npm install -g @railway/cli`)\n- Authenticated with `railway login`\n\n### Deploy\n\n```bash\nf deploy railway\n```\n\nWhat happens:\n1. Links to Railway project if specified\n2. Sets environment variables from `env_file`\n3. Deploys with `railway up --detach`\n\n---\n\n## Health Checks\n\nCheck if your deployment is responding:\n\n```bash\n# Use domain from [host] or url from [cloudflare] config\nf deploy health\n\n# Custom URL\nf deploy health --url https://api.example.com/health\n\n# Expect specific status code\nf deploy health --status 204\n```\n\nReturns:\n- `Healthy (HTTP 200 in 0.15s)` on success\n- `Unhealthy: expected HTTP 200, got 500` on wrong status\n- `Unreachable: Connection refused` on network error\n\n---\n\n## Global Host Configuration\n\nHost connection is stored globally at `~/.config/flow/deploy.json`:\n\n```json\n{\n  \"host\": {\n    \"user\": \"deploy\",\n    \"host\": \"myserver.com\",\n    \"port\": 22\n  }\n}\n```\n\nView/set:\n\n```bash\nf deploy show-host\nf deploy set-host deploy@newserver.com:2222\n```\n\n---\n\n## Examples\n\n### Full Host Setup\n\n```toml\n# flow.toml\n[host]\ndest = \"/opt/api\"\nrun = \"/opt/api/server\"\nport = 8080\nservice = \"myapi\"\nsetup = \"cargo build --release && cp target/release/server /opt/api/\"\nenv_file = \".env.production\"\ndomain = \"api.mycompany.com\"\nssl = true\n```\n\n```bash\n# First time setup\nf deploy set-host root@myserver.com\n\n# Deploy\nf deploy host\n\n# Check it's working\nf deploy health\nf deploy logs -f\n```\n\n### Full Cloudflare Setup\n\n```toml\n# flow.toml\n[cloudflare]\npath = \"packages/worker\"\nenvironment = \"production\"\nenv_source = \"cloud\"\nenv_keys = [\"OPENAI_API_KEY\", \"WEBHOOK_SECRET\"]\nurl = \"https://my-worker.mycompany.workers.dev\"\n```\n\n```bash\n# Store project secrets\nf env project set -e production OPENAI_API_KEY=sk-...\nf env project set -e production WEBHOOK_SECRET=whsec_...\n\n# Deploy with secrets\nf deploy cloudflare --secrets\n\n# Verify\nf deploy health\n```\n\n### CI/CD Integration\n\n```yaml\n# GitHub Actions\ndeploy:\n  runs-on: ubuntu-latest\n  steps:\n    - uses: actions/checkout@v4\n    - name: Deploy\n      run: |\n        f deploy set-host ${{ secrets.DEPLOY_HOST }}\n        f deploy host\n        f deploy health\n```\n\n---\n\n## Troubleshooting\n\n### \"No host configured\"\n\nRun `f deploy set-host user@host:port` first.\n\n### \"No wrangler config found\"\n\nEnsure `wrangler.toml` exists in your worker directory, or run `wrangler init`.\n\n### SSH connection fails\n\nTest with `f deploy shell` to debug. Check:\n- SSH key is in `~/.ssh/` and added to server\n- Port is correct (default: 22)\n- Server is reachable\n\n### Secrets not updating\n\nFor Cloudflare, use `--secrets` flag: `f deploy cloudflare --secrets`\n\n### Health check fails\n\nCheck URL is correct and service is running:\n```bash\nf deploy logs -f  # Check for errors\ncurl -v https://your-domain.com  # Test manually\n```\n","docs/commands/docs.md":"# f docs\n\nManage documentation for a project. There are two doc systems:\n\n- `.ai/docs` for AI-maintained internal docs.\n- `docs/` for human-facing docs rendered by the docs hub.\n\n## Quick Start\n\n```bash\n# Create docs/ with starter files\nf docs new\n\n# Open docs for the current project (auto-starts the hub)\nf docs\n\n# Deploy the current project's docs to Cloudflare Pages\nf docs deploy\n```\n\n## Commands\n\n### f docs new\n\nCreates a `docs/` folder in the current project using the template in `~/new/docs`.\nIf `docs/` already exists, it merges in any missing template files and leaves\nexisting content untouched.\n\nOptions:\n\n- `--path <PATH>`: Target directory (defaults to current folder).\n- `--force`: Overwrite if `docs/` already exists.\n\n### f docs hub\n\nRuns a single dev server that aggregates docs from `~/code` and `~/org`.\nUse `FLOW_DOCS_FOCUS=1` to only index the current project for faster startup.\n\nOptions:\n\n- `--host <HOST>` (default: `127.0.0.1`)\n- `--port <PORT>` (default: `4410`)\n- `--hub-root <PATH>` (default: `~/.config/flow/docs-hub`)\n- `--template-root <PATH>` (default: `~/new/docs`)\n- `--code-root <PATH>` (default: `~/code`)\n- `--org-root <PATH>` (default: `~/org`)\n- `--no-ai`: Skip `.ai/docs`.\n- `--no-open`: Do not open the browser.\n- `--sync-only`: Sync docs content and exit.\n\n### f docs deploy\n\nDeploys the current project's docs to Cloudflare Pages (uses the docs hub template).\n\nOptions:\n\n- `--project <NAME>`: Pages project name (defaults to the flow.toml name).\n- `--domain <DOMAIN>`: Attach a custom domain (optional).\n- `--yes`: Skip confirmation prompts.\n\n### f docs sync\n\nSyncs `.ai/docs` metadata based on recent commits. Intended for AI doc upkeep.\n\n### f docs list\n\nLists `.ai/docs` files for the current project.\n\n### f docs status\n\nShows recent commits and `.ai/docs` file modification times.\n\nIt now also shows:\n\n- recent Flow-managed Codex session packets stored under Flow state for the current project\n- doc-review queue state counts for the current project\n\n### f docs review-pending\n\nRuns the bounded daemon-style review pass over pending session-doc packets stored in\nFlow state and records promotion decisions into queue state plus each packet's\n`promotion.json`.\n\nOptions:\n\n- `-n, --limit <N>`: Maximum number of pending entries to review (default: `25`).\n\n### f docs promote-session\n\nPreviews or applies promotion for a daemon-captured session-doc packet.\n\nBy default this is a dry run. It prints the chosen target under `.ai/docs/` and the\npromoted markdown note. Raw packet bundles stay in Flow state; only promoted\ndurable notes are written into the repo.\n\nOptions:\n\n- `<SESSION>`: Session id, session id prefix, or session key like `019d035d-...` or `019d035d-1773776290`\n- `--apply`: Write the promoted note immediately\n\n### f docs commit-pending\n\nCommits promoted session-doc notes when the git diff is isolated to doc-only files.\n\nThis command refuses to commit if the worktree contains unrelated changes.\n\nOptions:\n\n- `--dry-run`: Show the candidate files and commit message without staging or committing\n\n### f docs edit\n\nOpens a `.ai/docs` file in `$EDITOR`.\n\nExample:\n\n```bash\nf docs edit architecture\n```\n","docs/commands/domains.md":"# `f domains`\n\nManage shared local `*.localhost` routing with a single proxy on port `80`.\n\n## Why\n\nWithout this, each repo can start its own proxy and race for port `80`.\n`f domains` centralizes ownership with one engine at a time.\n\nState lives in:\n\n- `~/.config/flow/local-domains/routes.json`\n- runtime artifacts under `~/.config/flow/local-domains/`\n\n## Engines\n\n- `docker` (default): shared nginx container (`flow-local-domains-proxy`)\n- `native` (experimental): local C++ daemon (`domainsd-cpp`)\n\nSelect engine per command:\n\n```bash\nf domains --engine docker up\nf domains --engine native up\n```\n\nOr via env:\n\n```bash\nexport FLOW_DOMAINS_ENGINE=native\n```\n\n## Commands\n\n```bash\nf domains list\nf domains add linsa.localhost 127.0.0.1:3481\nf domains rm linsa.localhost\nf domains up\nf domains down\nf domains doctor\nf domains --engine native up\nf domains --engine native down\nf domains --engine native doctor\n```\n\n## Behavior\n\n- `f domains up`\n  - starts shared proxy on `:80`\n  - fails fast if another process/container owns port `80`\n- `f domains add`\n  - validates `host` ends with `.localhost`\n  - validates target format `host:port`\n  - refuses overwrite unless `--replace`\n  - reloads proxy if already running\n- `f domains doctor`\n  - shows route count\n  - shows current owner of port `80`\n  - highlights conflict ownership\n\n## Native notes (experimental)\n\n- Requires `clang++` to build `tools/domainsd-cpp/domainsd.cpp`.\n- Current scope is HTTP/1.1 host routing with WebSocket upgrade passthrough and upstream keepalive pooling.\n- Native daemon has built-in overload shedding (`503`) and upstream timeout protection (`504` on connect timeout).\n- HTTP/2/TLS are not implemented yet.\n- See `docs/local-domains-domainsd-cpp-spec.md`.\n- myflow-specific setup: `docs/myflow-localhost-runbook.md`.\n- Lifecycle integration: configure `[lifecycle.domains]` and use `f up` / `f down`.\n\n### macOS no-docker bind to :80\n\nIf native startup fails with `Permission denied` on `127.0.0.1:80`, install launchd socket mode once:\n\n```bash\ncd ~/code/flow\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nThen run:\n\n```bash\nf domains --engine native up\n```\n\nThis keeps routing fully native and avoids Docker overhead while still using port `80`.\n\n### Native tuning envs\n\nYou can tune the native daemon at startup via environment variables:\n\n```bash\nFLOW_DOMAINS_NATIVE_MAX_ACTIVE_CLIENTS=128\nFLOW_DOMAINS_NATIVE_UPSTREAM_CONNECT_TIMEOUT_MS=10000\nFLOW_DOMAINS_NATIVE_UPSTREAM_IO_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_CLIENT_IO_TIMEOUT_MS=30000\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_PER_KEY=8\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_TOTAL=256\nFLOW_DOMAINS_NATIVE_POOL_IDLE_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_POOL_MAX_AGE_MS=120000\n```\n## Recommended Repo Pattern\n\nInstead of per-repo docker proxy tasks:\n\n```toml\n[[tasks]]\nname = \"domains-up\"\ncommand = \"f domains add myapp.localhost 127.0.0.1:3000 && f domains up\"\n```\n\nThis keeps one proxy process for all repos and avoids accidental domain hijacking.\n","docs/commands/down.md":"# f down\n\nBring a project down using lifecycle conventions.\n\n## Quick Start\n\n```bash\n# Run lifecycle down task and optional domains teardown\nf down\n```\n\n## Behavior\n\n- Loads nearest `flow.toml` (or `--config` path).\n- Runs lifecycle task:\n  - `[lifecycle].down_task` when configured\n  - otherwise fallback: `down`\n- If no down task is found and `down_task` is not explicitly set, Flow falls back to killing all running Flow-managed processes for the current project (`f kill --all` behavior).\n- If `[lifecycle.domains]` is configured, optional teardown is applied:\n  - `remove_on_down = true` -> removes configured host route\n  - `stop_proxy_on_down = true` -> stops shared local domains proxy\n- On macOS launchd-managed native domains, stopping native proxy is handled by:\n  - `sudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh`\n\nIf neither a down task nor lifecycle domain teardown is configured, command fails with guidance.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`, searches upward when default is missing) |\n| `ARGS...` | Extra args passed to the selected lifecycle task |\n","docs/commands/env.md":"# f env\n\nSync project environment and manage environment variables.\n\n## Overview\n\nManage environment variables via cloud or local storage. Supports:\n- Project-level environment variables\n- Personal/global variables\n- Multiple environments (dev, staging, production)\n- Direct injection into commands\n- Touch ID gating for cloud reads and keychain-backed personal local reads on macOS\n- Client-side sealed project env sharing in the cloud\n\n## Storage Backends\n\n| Backend | Location | Config |\n|---------|----------|--------|\n| `cloud` | Cloud (myflow.sh) | Default, requires login |\n| `local` | `~/.config/flow/env-local/` | No account needed |\n\nCloud behavior:\n- Personal cloud envs use Flow's existing server-managed secret storage.\n- Project cloud envs are sealed client-side before upload and decrypted locally on read.\n- If a host deploy is configured with `env_source = \"cloud\"` plus a `service_token`, Flow keeps a compatibility plaintext mirror for those project keys until the host fetch path is upgraded.\n\nForce local backend:\n\n```bash\n# Via environment variable\nexport FLOW_ENV_BACKEND=local\n\n# Or in ~/.config/flow/config.ts\nexport default {\n  flow: { env: { backend: \"local\" } }\n}\n```\n\nIf the current project has an unambiguous deploy env source such as:\n\n```toml\n[host]\nenv_source = \"local\"\n```\n\nthen `f env` will also use the local backend automatically in that project.\n\n### Local Storage Structure\n\n```\n~/.config/flow/env-local/\n├── <project-name>/\n│   ├── production.env\n│   ├── staging.env\n│   └── dev.env\n└── personal/\n    └── production.env\n```\n\nStorage behavior:\n- Project-local envs are private `.env` files under `~/.config/flow/env-local/`.\n- On macOS, personal-local env values are stored in Keychain by default; `personal/production.env` keeps Flow-managed references, not raw secret values.\n- If `FLOW_ENV_LOCAL_PLAINTEXT=1` is set, Flow falls back to plaintext personal local storage.\n- Local env paths are written with owner-only permissions.\n\n## Quick Start\n\n```bash\n# Store a personal secret\nf env set API_KEY=sk-xxx\n\n# List variables (default action when logged in)\nf env\n\n# Run command with env vars injected\nf env run -- npm start\n\n# Get a value\nf env get API_KEY -f value\n```\n\n## Linsa/TestFlight Example\n\nFor project-scoped keys used by local + ship flows (for example, assistant keys):\n\n```bash\n# Store in project space (recommended for app/server env)\nf env project set -e dev OPENROUTER_API_KEY=sk-...\nf env project set -e production OPENROUTER_API_KEY=sk-...\nf env project set -e dev OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\nf env project set -e production OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\n```\n\nNotes:\n- Do not commit secrets to docs or repository files.\n- Use `f env get -e production -f value OPENROUTER_API_KEY` at runtime when a ship script needs to inject a missing key.\n\n## Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `login` | Authenticate with cloud |\n| `set` | Set a single env var |\n| `get` | Get specific env var(s) |\n| `list` | List env vars for this project |\n| `delete` | Delete env var(s) |\n| `pull` | Fetch env vars and write to .env |\n| `push` | Push local .env to cloud |\n| `apply` | Apply env vars to Cloudflare worker |\n| `setup` | Interactive wizard to push env vars |\n| `run` | Run command with env vars injected |\n| `status` | Show current auth status |\n| `keys` | Show configured env keys from flow.toml |\n| `sync` | Sync project settings and hub workflow |\n| `bootstrap` | Bootstrap Cloudflare secrets from flow.toml |\n| `unlock` | Unlock env reads (Touch ID on macOS) |\n\n---\n\n## Set\n\nStore a personal environment variable:\n\n```bash\n# Basic set\nf env set API_KEY=sk-xxx\n\n# Personal envs always use the production personal store\nf env set GITHUB_TOKEN=ghp_xxx\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--personal` | | Compatibility flag; `set` already targets personal envs |\n\n## Project Set\n\nStore a project-scoped environment variable:\n\n```bash\nf env project set -e dev DATABASE_URL=postgres://localhost/app\nf env project set -e production PUBLIC_API_BASE_URL=https://api.example.com\n```\n\nNotes:\n- Project cloud writes are sealed by default.\n- On a new device, the first project read/write auto-registers that device as a sealer.\n- If a key exists in cloud but was never shared to this device, Flow will ask you to re-save it from a device that already has access.\n\n---\n\n## Get\n\nRetrieve environment variables:\n\n```bash\n# Get as KEY=VALUE\nf env get API_KEY\n# API_KEY=sk-xxx\n\n# Get just the value\nf env get API_KEY -f value\n# sk-xxx\n\n# Get as JSON\nf env get API_KEY -f json\n# {\"API_KEY\": \"sk-xxx\"}\n\n# Get multiple\nf env get API_KEY DATABASE_URL\n\n# From personal store\nf env get --personal GITHUB_TOKEN -f value\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--format <FORMAT>` | `-f` | Output: `env`, `json`, or `value` (default: env) |\n| `--personal` | | Fetch from personal store |\n\n---\n\n## List\n\nList all environment variables:\n\n```bash\n# List production vars\nf env list\n\n# List staging vars\nf env list -e staging\n```\n\nOutput:\n```\nEnvironment: production\n\n  API_KEY          OpenAI API key\n  DATABASE_URL     PostgreSQL connection string\n  REDIS_URL        -\n```\n\n---\n\n## Run\n\nRun a command with environment variables injected:\n\n```bash\n# Inject all project env vars\nf env run -- npm start\n\n# Inject specific keys\nf env run -k API_KEY -k DATABASE_URL -- node server.js\n\n# From personal store\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n\n# Multiple keys from personal\nf env run --personal -k TELEGRAM_BOT_TOKEN -k TELEGRAM_API_ID -- ./start.sh\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--keys <KEYS>` | `-k` | Specific keys to inject (repeatable) |\n| `--personal` | | Fetch from personal store |\n\n### Examples\n\n```bash\n# Start app with production secrets\nf env run -- npm run start\n\n# Run with staging environment\nf env run -e staging -- npm run dev\n\n# Telegram bot with personal tokens\nf env run --personal -k TELEGRAM_BOT_TOKEN -- pnpm tsx src/bot.ts\n```\n\n---\n\n## Pull\n\nFetch all env vars and write to `.env` file:\n\n```bash\n# Write to .env\nf env pull\n\n# Pull staging vars\nf env pull -e staging\n```\n\nCreates or overwrites `.env` in current directory with all project variables.\n\n---\n\n## Push\n\nUpload local `.env` file to cloud:\n\n```bash\nf env push\n```\n\nReads `.env` from current directory and stores all variables.\n\n---\n\n## Setup\n\nInteractive wizard for pushing env vars:\n\n```bash\nf env setup\n```\n\nIf `[cloudflare] env_source = \"cloud\"` is set in `flow.toml`, this runs a guided\nprompt based on `env_keys`/`env_vars`. Otherwise it guides you through:\n1. Reading your `.env` file\n2. Selecting which keys to push\n3. Confirming before upload\n\n---\n\n## Delete\n\nRemove environment variables:\n\n```bash\n# Delete single key\nf env delete API_KEY\n\n# Delete multiple\nf env delete API_KEY DATABASE_URL\n```\n\n---\n\n## Login\n\nAuthenticate with cloud:\n\n```bash\nf env login\n```\n\nPrompts for API base URL and token. On macOS, the token is stored in Keychain\nand Flow uses Touch ID to unlock env reads.\n\n---\n\n## Status\n\nCheck authentication status:\n\n```bash\nf env status\n```\n\nOutput:\n```\ncloud Status\n  Token: stored in Keychain\n  API: https://myflow.sh\n  Project: myproject\n```\n\n---\n\n## Apply\n\nApply env vars to Cloudflare worker (uses `[cloudflare]` config in flow.toml):\n\n```bash\nf env apply\n```\n\nRequires `env_source = \"cloud\"` in your `[cloudflare]` config.\n\n## Keys\n\nShow env keys configured in `flow.toml` without printing values:\n\n```bash\nf env keys\n```\n\n## Unlock\n\nOn macOS, unlock env reads for the day (Touch ID):\n\n```bash\nf env unlock\n```\n\n---\n\n## Environments\n\nFlow supports three environments:\n\n| Environment | Description |\n|-------------|-------------|\n| `production` | Production secrets (default) |\n| `staging` | Staging/preview secrets |\n| `dev` | Development secrets |\n\nUse `-e` flag with project-scoped commands:\n\n```bash\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env list -e dev\nf env run -e staging -- npm run preview\n```\n\n---\n\n## Personal vs Project Variables\n\n| Type | Flag | Scope | Use Case |\n|------|------|-------|----------|\n| Project | (default for `get`, `list`, `run`, `project ...`) | Current project | API keys, database URLs |\n| Personal | `--personal` | Global/user | GitHub token, Telegram bot token |\n\nPersonal variables are tied to your user account, not a specific project.\n`f env set` writes personal vars. Use `f env project set` for project vars.\n\n```bash\n# Use a personal token in any project\nf env run --personal -k ANTHROPIC_API_KEY -- ./my-script\n```\n\n---\n\n## Env Space Overrides\n\nYou can store project envs under a named cloud space by configuring `env_space`\nand `env_space_kind` in `flow.toml`.\n\n```toml\n# flow.toml\nenv_space = \"nikiv\"\nenv_space_kind = \"personal\"\n```\n\n- `env_space_kind = \"project\"` (default) uses the project name.\n- `env_space_kind = \"personal\"` routes project envs to your personal space.\n\nThis affects `f env pull`, `f env push`, `f env list`, `f env apply`, and service\ntoken creation.\n\n---\n\n## Examples\n\n### Typical Workflow\n\n```bash\n# 1. Authenticate\nf env login\n\n# 2. Set up secrets\nf env project set DATABASE_URL=postgres://... -e production\nf env project set API_KEY=sk-xxx -e production\n\n# 3. Verify\nf env list\n\n# 4. Run app\nf env run -- npm start\n```\n\n### Staging Deploy\n\n```bash\n# Set staging secrets\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env project set API_KEY=sk-test-xxx -e staging\n\n# Test with staging env\nf env run -e staging -- npm run preview\n```\n\n### Personal Tokens for CLI Tools\n\n```bash\n# Store once\nf env set --personal GITHUB_TOKEN=ghp_xxx\nf env set --personal TELEGRAM_BOT_TOKEN=xxx\n\n# Use anywhere\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n```\n\n### In flow.toml Tasks\n\n```toml\n[tasks.start]\ncommand = \"f env run -- npm start\"\n\n[tasks.bot]\ncommand = \"f env run --personal -k TELEGRAM_BOT_TOKEN -- node bot.js\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Not authenticated\"\n\nRun `f env login` to authenticate with cloud.\n\n### \"No env vars found\"\n\nCheck environment name - default is `production`:\n```bash\nf env list -e staging  # Check staging instead\n```\n\n### Variables not injecting\n\nEnsure command comes after `--`:\n```bash\nf env run -k API_KEY -- npm start  # Correct\nf env run -k API_KEY npm start     # May not work\n```\n\n## See Also\n\n- [deploy](deploy.md) - Using env vars in deployments\n- [docs/how-to-use-env.md](../how-to-use-env.md) - Extended usage guide\n","docs/commands/ext.md":"# f ext\n\nManage Flow config extensions under `~/.flow/extensions`.\n\nThis is the extension/operator surface for the centralized Flow config system:\n\n- root config: `~/.flow/config.ts`\n- runtime helper: `~/.flow/runtime/flow-config.ts`\n- extension root: `~/.flow/extensions/<name>/`\n\nExtensions are loaded by `f config build` / `f config apply` when their names\nappear in `extensions: [...]` inside `~/.flow/config.ts`.\n\nFor backwards compatibility, `f ext <path>` still supports the older external\ndirectory import workflow into `<project>/ext/<name>`.\n\n## Commands\n\n### f ext list\n\nList built-in and filesystem extensions and whether they are enabled.\n\n```bash\nf ext list\nf ext list --json\n```\n\n### f ext doctor\n\nShow root-config wiring for extensions:\n\n- `~/.flow/config.ts`\n- `~/.flow/extensions`\n- `~/.flow/runtime/flow-config.ts`\n\nand the currently discoverable extensions.\n\n```bash\nf ext doctor\nf ext doctor --json\n```\n\n### f ext init\n\nCreate a new extension scaffold under `~/.flow/extensions/<name>/`.\n\nGenerated files:\n\n- `extension.ts`\n- `README.md`\n\nThe scaffold imports:\n\n- `defineFlowExtension` from `~/.flow/runtime/flow-config.ts`\n\n```bash\nf ext init my-extension\nf ext init my-extension --force\n```\n\n### f ext enable\n\nEnable an extension by name in `~/.flow/config.ts`.\n\n```bash\nf ext enable my-extension\n```\n\n### f ext disable\n\nDisable an extension by name in `~/.flow/config.ts`.\n\n```bash\nf ext disable my-extension\n```\n\n### f ext import\n\nExplicit legacy import form. Copies an external directory into `<project>/ext/`\nand adds `ext/` to `.gitignore`.\n\n```bash\nf ext import ~/some/external/repo\n```\n\nBare path form is still accepted:\n\n```bash\nf ext ~/some/external/repo\n```\n\n## Extension Shape\n\nAn extension file can export:\n\n```ts\nimport { defineFlowExtension } from \"../../runtime/flow-config\"\n\nexport default defineFlowExtension({\n  name: \"my-extension\",\n  flow: { ... },\n  lin: { ... },\n  ai: { ... },\n  hive: { ... }, // migration-only; Flow no longer applies ~/.hive/config.json\n  zerg: { ... },\n  generatedFiles: [\n    {\n      path: \"~/.some/target/file.json\",\n      content: \"{...}\",\n    },\n  ],\n  doctor: [\"human-readable check or note\"],\n})\n```\n\n## Notes\n\n- built-in extension currently supported: `lin-compat`\n- `f ext enable` rewrites `~/.flow/config.ts`\n- `f ext init` also ensures the runtime helper exists\n- generated file path collisions fail the build\n","docs/commands/failure.md":"# f failure\n\nInspect and copy recent task failures without manually selecting terminal text.\n\n## Usage\n\n```bash\nf failure\nf failure last\nf failure last --json\nf failure list\nf failure list --json --limit 10\nf failure copy\nf failure copy --format codex\nf failure copy --format codex --write-repo\nf failure copy --format claude\nf failure copy --format excerpt\nf failure copy --format json\n```\n\n## What It Reads\n\nFlow records failures to a stable latest pointer plus versioned history:\n\n```text\n~/.cache/flow/last-task-failure.json\n~/.cache/flow/task-failures/*.json\n```\n\nOverride the latest pointer with:\n\n```bash\nFLOW_FAILURE_BUNDLE_PATH=/tmp/last-task-failure.json\n```\n\n## Notes\n\n- `f failure` defaults to `f failure last`\n- `f failure copy` defaults to the latest failure in `prompt` format\n- `f failure copy --format codex` and `--format claude` render Flow-native repair prompts\n- `f failure copy --write-repo` writes the selected payload to `.ai/internal/failures/`\n- `f failure list --json` is intended for launcher consumers such as Alfred or Lin\n- Set `FLOW_NO_CLIPBOARD=1` to disable clipboard writes\n","docs/commands/fast.md":"# f fast\n\nRun AI tasks through the low-latency fast client path.\n\nThis command is optimized for hot-loop invocation and prefers `fai`/`ai-taskd-client` over full `f` task startup.\n\n## Usage\n\n```bash\nf fast ai:flow/noop\nf fast ai:flow/bench-cli -- --iterations 30\nf fast --root ~/code/flow ai:flow/dev-check\nf fast --no-cache ai:flow/dev-check\n```\n\n## Behavior\n\n1. Tries fast client dispatch (`fai`, local `target/.../ai-taskd-client`, or `ai-taskd-client` on PATH).\n2. If daemon is not running, starts `ai-taskd` and retries.\n3. Falls back to direct daemon dispatch if no fast client binary is found.\n\n## Options\n\n- `--root <PATH>`: root directory for `.ai/tasks` discovery (default `.`)\n- `--no-cache`: disable cached binary execution and use direct Moon run\n- `TASK`: required AI selector like `ai:flow/dev-check`\n- trailing args after `--` are passed to the task\n\n## Notes\n\n- `f fast` is intentionally for `ai:*` selectors only.\n- Install `fai` for best latency:\n\n```bash\nf install-ai-fast-client\nf tasks daemon start\nf fast ai:flow/noop\n```\n\nFor pooled burst execution and timings, use `fai` directly:\n\n```bash\nfai --timings ai:flow/noop\nprintf 'ai:flow/noop\\nai:flow/noop\\n' | fai --batch-stdin --timings\n```\n","docs/commands/global.md":"# f global\n\nRun tasks from your global flow config (`~/.config/flow/flow.toml`).\n\n## Quick Start\n\n```bash\n# List global tasks\nf global --list\nf global list\n\n# Run a global task from anywhere\nf global repos-clone-safari\nf global run repos-clone-safari\n\n# Match a query against global tasks\nf global match \"clone safari repo\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `<TASK>` | | Global task name (omit to list) |\n| `list` | | List global tasks |\n| `run <TASK>` | | Run a global task |\n| `match <QUERY>` | | Match a query against global tasks |\n| `--list` | `-l` | List global tasks |\n| `-- <ARGS...>` | | Pass extra args to the task |\n\n## Examples\n\n```bash\nf global repos-clone-safari https://github.com/0xPlaygrounds/rig\n```\n","docs/commands/install.md":"# f install\n\nInstall a CLI/tool binary into your PATH.\n\nDefault backend behavior (`--backend auto`):\n1. Flow registry (`myflow.sh` or `--registry`)\n2. GitHub releases via `parm`\n3. flox package install\n\n## Usage\n\n```bash\nf install <name>\n```\n\n## Options\n\n- `--registry <URL>`: registry base URL (defaults to `FLOW_REGISTRY_URL`).\n- `--backend <auto|registry|parm|flox>`: choose install backend explicitly.\n- `--version <VERSION>`: install a specific version (defaults to latest).\n- `--bin <NAME>`: binary name to install (defaults to manifest default or package name).\n- `--bin-dir <PATH>`: install directory (defaults to `~/bin`).\n- `--force`: overwrite an existing binary.\n- `--no-verify`: skip checksum verification.\n\n## Auto backend notes\n\n- `f install rise` can resolve through `parm` using built-in owner/repo mapping.\n- Built-in aliases:\n  - `f install seqd` resolves registry package `seq` with binary `seqd`.\n  - `f install lin` resolves registry package `flow` with binary `lin`.\n- If a package name is ambiguous for `parm`, set `FLOW_INSTALL_OWNER` (env or Flow personal env store) or pass `owner/repo` directly.\n\n## Bootstrap from installer\n\nThe hosted installer can bootstrap core tools after installing flow:\n\n- `FLOW_BOOTSTRAP_TOOLS=\"rise seq seqd\"` (default) installs those with `f install ... --backend auto`.\n- `FLOW_BOOTSTRAP_TOOLS=0` disables this.\n- `FLOW_BOOTSTRAP_INSTALL_PARM=1` (default) attempts to install `parm` for robust GitHub fallback.\n\n## Registry layout\n\nThe registry must expose:\n\n- `GET /packages/<name>/latest.json`\n- `GET /packages/<name>/<version>/manifest.json`\n- `GET /packages/<name>/<version>/<target>/<bin>`\n\n## Example\n\n```bash\nFLOW_REGISTRY_URL=https://myflow.sh f install flow\n```\n\n```bash\nf install rise\n```\n","docs/commands/invariants.md":"# f invariants\n\nValidate project invariants declared in `flow.toml`.\n\nThis command checks the `[invariants]` section and reports violations in changed code.\n\n## Usage\n\n```bash\n# Check all local changes vs HEAD\nf invariants\n\n# Check only staged changes\nf invariants --staged\n```\n\n## What It Checks\n\n1. `forbidden`: disallowed patterns in added diff lines.\n2. `deps.approved`: unapproved dependencies in `package.json` sections (`dependencies`, `devDependencies`, `peerDependencies`).\n3. `files.max_lines`: changed files exceeding the configured line limit.\n\n## Modes\n\nSet in `flow.toml`:\n\n- `mode = \"off\"`: disable checks.\n- `mode = \"warn\"`: print findings, exit success.\n- `mode = \"block\"`: fail command when blocking findings exist.\n\n## Example `flow.toml`\n\n```toml\n[invariants]\nmode = \"block\"\narchitecture_style = \"layered monorepo, event-driven core\"\nnon_negotiable = [\n  \"no inline imports\",\n  \"no any types unless justified\",\n]\nforbidden = [\n  \"git add -A\",\n  \"git reset --hard\",\n]\n\n[invariants.terminology]\n\"pi-ai\" = \"LLM abstraction layer\"\n\"pi-agent\" = \"stateful agent runtime\"\n\n[invariants.deps]\npolicy = \"approval_required\"\napproved = [\"@sinclair/typebox\", \"@reatom/core\"]\n\n[invariants.files]\nmax_lines = 300\n```\n\n## Commit Integration\n\n`f commit` runs the invariant gate during commit-with-check flow.\n\n- In `mode = \"block\"`, commits are blocked on invariant warnings/critical findings.\n- Invariant context and findings are injected into AI review prompts.\n\n","docs/commands/jj.md":"# jj\n\nFlow wraps common Jujutsu (jj) workflows so you can stay in jj while remaining fully Git-compatible.\n\n## Quick start\n\n```bash\n# Inspect workspace + home-branch state\nf status\n\n# Initialize jj (colocated with git when .git exists)\nf jj init\n\n# Create a feature bookmark and track origin\nf jj bookmark create feature-x --track\n\n# Fetch + rebase onto main + push bookmark\nf jj sync --bookmark feature-x\n```\n\n## Commands\n\n- `f status` — Show workflow-aware JJ status (workspace, home branch, leaf branches, working-copy summary, and next-step hints)\n- `f jj status` — Show raw `jj st`\n- `f jj fetch` — `jj git fetch`\n- `f jj rebase --dest <branch>` — Rebase onto `jj.default_branch` (or main/master)\n- `f jj push --bookmark <name>` — Push a single bookmark\n- `f jj push --all` — Push all bookmarks\n- `f jj sync --bookmark <name>` — Fetch, rebase, then push bookmark\n- `f jj workspace add <name> [--path <dir>] [--rev <rev>]` — Create a workspace (optionally anchored to a revision)\n- `f jj workspace lane <name> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create an isolated parallel lane from trunk defaults\n- `f jj workspace review <branch> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create or reuse a stable JJ review workspace for a branch without touching the current checkout\n- `f jj workspace list` — List workspaces\n- `f jj bookmark create <name> [--rev <rev>] [--track]` — Create bookmark\n- `f jj bookmark track <name> [--remote <remote>]` — Track remote bookmark\n\n## Status-first workflow\n\nUse `f status` before branch, workspace, commit, or publish operations.\n\nIt is the fast way to answer:\n\n- which workspace am I in?\n- am I on the long-lived home branch or a branch-specific leaf?\n- what review or codex branches currently sit on top of the home branch?\n- is the working copy clean enough to mutate safely?\n\nExample:\n\n```bash\ncd ~/code/org/project\nf status\n```\n\nUse `f jj status` only when you want the raw Jujutsu working-copy view.\n\n## Parallel lanes (no interleaving)\n\nUse lanes when you want multiple active tasks in one repo without stash/pop churn:\n\n```bash\n# In your current repo, create isolated lanes anchored from trunk\nf jj workspace lane fix-otp\nf jj workspace lane testflight\n\n# Work each lane independently\ncd ~/.jj/workspaces/<repo>/fix-otp\njj st\n```\n\n`f jj workspace lane` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. chooses base as `<default_branch>@<remote>` when tracked (fallback: `<default_branch>`)\n3. creates a dedicated workspace with its own `@` working-copy commit\n\n## Review workspaces\n\nUse a review workspace when you want an isolated JJ working copy for a review branch without\ntouching the current repo checkout:\n\n```bash\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/<repo>/review-alice-feature\njj st\n```\n\n`f jj workspace review` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. reuses the existing review workspace when present\n3. otherwise anchors the workspace at the local branch commit, then the remote branch commit, then trunk\n4. prints the stable workspace path plus the JJ bookmark command to publish later\n\nImportant:\n\n- The review workspace is JJ-native. Use `jj` or `f jj` inside it.\n- In colocated repos, plain `git` still points at the main checkout, so this command intentionally does not run `flow switch` for you.\n\n## Config\n\nAdd to `flow.toml`:\n\n```toml\n[git]\nremote = \"myflow-i\"  # optional preferred writable remote\n\n[jj]\ndefault_branch = \"main\"\nhome_branch = \"alice\" # optional long-lived personal integration branch\nremote = \"origin\"     # optional legacy fallback if [git].remote is unset\nauto_track = true\n```\n\nThis keeps jj aligned with Git remotes while you work locally in jj.\n\n## Home-branch model\n\nIf you keep a long-lived personal branch on top of trunk, set `jj.home_branch` and treat it as\nyour integration branch.\n\nWhen the current branch matches that home branch, plain `f sync` also switches into home-branch\nmode and syncs `origin/<default-branch>` into it instead of using the normal tracking pull.\n\nThen use short-lived `review/*` or `codex/*` branches on top of that home branch for task-specific\nwork. `f status` is optimized to make that shape visible.\n\nRecommended flow:\n\n```bash\n# Default checkout stays on your home branch\ncd ~/code/org/project\nf status\n\n# Branch-specific work happens in isolated workspaces\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/project/review-alice-feature\nf status\n```\n\nSee also:\n\n- [`jj-review-workspaces.md`](../jj-review-workspaces.md)\n- [`jj-home-branch-workflow.md`](../jj-home-branch-workflow.md)\n","docs/commands/migrate.md":"# f migrate\n\nMove or copy a project folder to a new location, preserving symlinks and AI sessions.\n\n## Overview\n\nRelocates a project directory and automatically migrates Claude and Codex AI sessions so conversation history follows the project. Also relinks any `~/bin` symlinks that pointed into the old path (move only).\n\n## Quick Start\n\n```bash\n# Move current directory into ~/code/lang/cpp/stream\ncd ~/code/lang/cpp/stream\nf migrate code stream\n\n# Move current directory to an arbitrary path\nf migrate ~/code/stream\n\n# Move a specific source to a target\nf migrate ~/code/lang/cpp/stream ~/code/stream\n\n# Preview what would happen (no changes)\nf migrate --dry-run code stream\n\n# Copy instead of move (keeps original)\nf migrate --copy code stream\n```\n\n## Your case\n\nTo migrate `~/code/lang/cpp/stream` to `~/code/stream`:\n\n```bash\ncd ~/code/lang/cpp/stream\nf migrate code stream\n```\n\nOr without `cd`:\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\nPreview first with `--dry-run`:\n\n```bash\nf migrate --dry-run ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Usage Forms\n\n### `f migrate code <relative>`\n\nMoves the current directory into `~/code/<relative>`. This is the most common form.\n\n```bash\ncd ~/old/location/myproject\nf migrate code myproject          # -> ~/code/myproject\nf migrate code lang/rust/mylib    # -> ~/code/lang/rust/mylib\n```\n\n### `f migrate <target>`\n\nMoves the current directory to `<target>` (any absolute or relative path).\n\n```bash\ncd ~/old/location/myproject\nf migrate ~/code/myproject\n```\n\n### `f migrate <source> <target>`\n\nMoves `<source>` to `<target>` without needing to `cd` first.\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--copy` | `-c` | Copy instead of move (keeps the original intact) |\n| `--dry-run` | | Show what would change without writing anything |\n| `--skip-claude` | | Skip migrating Claude Code sessions |\n| `--skip-codex` | | Skip migrating Codex sessions |\n\n## What Happens\n\n### Step 1: Move or copy the folder\n\nThe project directory is moved (or copied with `--copy`) to the target path. Parent directories are created automatically. Cross-device moves are handled transparently (copy + delete).\n\n### Step 2: Relink ~/bin symlinks (move only)\n\nAny symlinks in `~/bin` that pointed into the old path are updated to point to the new location. Skipped when using `--copy`.\n\n### Step 3: Migrate AI sessions\n\nClaude and Codex store project sessions keyed by filesystem path. Migrate updates these so conversation history is preserved at the new location.\n\n- **Claude sessions**: Project directories under `~/.claude/projects/` are renamed from the old path-based key to the new one.\n- **Codex sessions**: Legacy project directories are renamed, and `.jsonl` session files referencing the old path are updated in-place.\n\nA summary is printed showing how many session dirs/files were migrated.\n\n## Examples\n\n```bash\n# Move project into ~/code, nested path\ncd ~/downloads/cool-project\nf migrate code tools/cool-project\n\n# Copy a project (keeps original)\nf migrate --copy ~/code/app ~/backup/app\n\n# Dry run to preview\nf migrate --dry-run code stream\n\n# Move without migrating AI sessions\nf migrate --skip-claude --skip-codex ~/old/path ~/new/path\n\n# Move and only migrate Claude (skip Codex)\nf migrate --skip-codex code myproject\n```\n\n## Troubleshooting\n\n### \"Destination already exists\"\n\nThe target path must not exist. Remove or rename the existing directory first, or choose a different target.\n\n### \"Source and destination are the same path\"\n\nBoth paths resolve to the same location. Double-check your arguments.\n\n### Session migration warnings\n\nAfter a move, you may see warnings like:\n\n```\nWARN Claude session dir still present: ...\nWARN Codex sessions still reference the old path:\n  /path/to/file.jsonl\n```\n\nThese mean some sessions couldn't be fully migrated. You can manually inspect or delete the referenced files.\n\n## See Also\n\n- [repos](repos.md) - Clone repositories into structured layout\n","docs/commands/new.md":"# f new\n\nCreate a new project from a local starter template under `~/new`.\n\n## Overview\n\n`f new` copies a directory from `~/new/<template>` into a destination path.\n\nThis is the native Flow way to work with local starters you keep in `~/new`.\n\n## Usage\n\n```bash\nf new [template] [path]\n```\n\n- `template`: folder name inside `~/new` (for example `app`, `docs`, `web`)\n- `path`: destination path (optional)\n\nIf `template` is omitted, Flow opens an `fzf` picker from templates in `~/new`.\n\n## Path Resolution Rules\n\nFlow resolves the destination path like this:\n\n```bash\nf new app          # -> ./app\nf new app zerg     # -> ~/code/zerg\nf new app ./xn     # -> ./xn\nf new app ~/xn     # -> ~/xn\n```\n\nNotes:\n- Plain names (no `./`, `../`, `/`, `~`) are treated as `~/code/<name>`.\n- Use `~/...` or absolute paths for custom locations outside `~/code`.\n\n## Dry Run\n\nPreview copy behavior without writing files:\n\n```bash\nf new app ~/xn --dry-run\n```\n\n## Starter Workflow\n\n1. Create or update starter in `~/new/<template>`.\n2. Generate a new project with `f new <template> <target>`.\n3. Enter the new project and run its setup/dev tasks with Flow.\n\nExample:\n\n```bash\nf new app ~/xn\ncd ~/xn\nf tasks\n```\n\n## Common Errors\n\n- `Template not found`: `~/new/<template>` does not exist.\n- `Destination already exists`: remove/rename target path or choose a new destination.\n","docs/commands/pr.md":"# f pr\n\nCreate or open GitHub pull requests, edit PR text locally, and pull review feedback.\n\n## Quick Start\n\n```bash\n# Create/update PR from current changes (default base: main)\nf pr \"assistant improvements\"\n\n# Open current branch PR in browser\nf pr open\n\n# Edit PR title/body in local markdown and sync on save\nf pr open edit\n\n# Pull actionable review feedback for current PR\nf pr feedback\n\n# Pull feedback for specific PR and store as local todos\nf pr feedback 8 --todo\nf pr feedback https://github.com/owner/repo/pull/8 --todo\n\n# Full inline diff/review context is now the default\nf pr feedback 8\n\n# Use terse terminal output if needed\nf pr feedback 8 --compact\n```\n\n## Feedback Workflow\n\n`f pr feedback` fetches:\n\n- PR reviews (`/pulls/<n>/reviews`)\n- Inline review comments (`/pulls/<n>/comments`)\n- Top-level PR comments (`/issues/<n>/comments`)\n\nIt then:\n\n1. Prints an actionable list in terminal with inline review state and diff hunk context by default.\n2. Writes a markdown snapshot to `.ai/reviews/pr-feedback-<pr>.md`.\n3. Writes a machine-readable JSON snapshot to `.ai/reviews/pr-feedback-<pr>.json`.\n4. Writes a human review plan to `~/docs/plan/review/<repo>-pr-<pr>-feedback.md`.\n5. Writes a PR-local execution artifact to `~/docs/plan/review/<repo>-pr-<pr>-review-rules.md`.\n6. Writes a Kit system prompt to `~/docs/plan/review/<repo>-pr-<pr>-kit-system.md`.\n7. Optionally (`--todo`) records feedback into `.ai/todos/todos.json` with dedupe via external refs.\n\nThe review plan includes ready-to-run `kit` commands for:\n\n- deterministic repo review via `kit review`\n- preventative lint/review rule synthesis from the fetched GitHub feedback set\n\nThe generated `*-review-rules.md` artifact contains the per-item resolution loop,\nprompt template, required response sections, and Kit-upgrade decision order so\nthe workflow can be reopened without extra instructions.\n\n## Notes\n\n- If no selector is passed, Flow resolves the PR from the current branch.\n- `f pr feedback --todo` is safe to re-run; existing feedback refs are not duplicated.\n- `f pr feedback` is full-context by default. Use `--compact` if you want the older terse terminal view.\n- `f pr feedback` now emits a Kit-ready handoff, so the same feedback set can drive a future review bot instead of staying trapped in GitHub comments.\n- `f pr open edit` remains the quickest path to tweak PR title/body from local editor.\n","docs/commands/publish.md":"# f publish\n\nPublish projects to GitHub.\n\n## Overview\n\nCreates a new GitHub repository and pushes the current project. Automatically infers the repo name from the folder name and handles both new repos and existing ones.\n\n## Quick Start\n\n```bash\n# Interactive mode - prompts for name and visibility\nf publish\n\n# Skip prompts, use folder name, default to private\nf publish -y\n\n# Create public repo\nf publish --public\n\n# Create with specific name\nf publish --name my-awesome-project\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--name <NAME>` | `-n` | Repository name (defaults to folder name) |\n| `--public` | | Create as public repository |\n| `--private` | | Create as private repository |\n| `--description <DESC>` | `-d` | Repository description |\n| `--yes` | `-y` | Skip prompts, use defaults (private, folder name) |\n\n## Prerequisites\n\n- [GitHub CLI](https://cli.github.com/) installed (`gh`)\n- Authenticated with `gh auth login`\n\n## Usage\n\n### Interactive Mode\n\nWithout flags, prompts for configuration:\n\n```bash\n$ f publish\n\nRepository name [my-project]:\nVisibility (public/private) [private]: public\n\nCreate repository:\n  Name: username/my-project\n  Visibility: public\n\nProceed? [Y/n]:\n```\n\n### Non-Interactive Mode\n\n```bash\n# Use all defaults (private, folder name as repo name)\nf publish -y\n\n# Public repo with defaults\nf publish -y --public\n\n# Specific name and description\nf publish -n cool-tool -d \"A cool CLI tool\" --public\n```\n\n### Existing Repositories\n\nIf the repository already exists on GitHub:\n\n1. Checks current visibility\n2. Updates visibility if different from requested\n3. Adds origin remote if missing\n4. Pushes current branch\n\n```bash\n$ f publish --public\nRepository username/my-repo already exists (private).\nUpdating visibility to public...\n✓ Updated to public\n\n✓ https://github.com/username/my-repo\n```\n\n## What Happens\n\n1. **Check gh CLI** - Verifies GitHub CLI is installed\n2. **Check authentication** - Ensures you're logged in to GitHub\n3. **Get username** - Fetches your GitHub username\n4. **Determine repo name** - Uses `--name`, folder name, or prompts\n5. **Determine visibility** - Uses `--public`/`--private` or prompts\n6. **Check if exists** - If repo exists, updates visibility if needed\n7. **Initialize git** - If not a git repo, runs `git init`\n8. **Create initial commit** - If no commits, stages all and commits\n9. **Create repository** - Uses `gh repo create` with `--source=. --push`\n10. **Output URL** - Prints the GitHub URL\n\n## Examples\n\n### Quick Publish New Project\n\n```bash\ncd my-new-project\nf publish -y --public\n# ✓ Published to https://github.com/username/my-new-project\n```\n\n### Publish with Description\n\n```bash\nf publish -n api-server -d \"REST API for my app\" --private\n```\n\n### Update Existing Repo Visibility\n\n```bash\n# Repo exists as private, make it public\nf publish --public\n# Repository username/my-repo already exists (private).\n# Updating visibility to public...\n# ✓ Updated to public\n```\n\n### In Scripts/CI\n\n```bash\n#!/bin/bash\ncd /path/to/project\nf publish -y --public -n release-candidate\n```\n\n## Troubleshooting\n\n### \"GitHub CLI (gh) is not installed\"\n\nInstall from https://cli.github.com:\n\n```bash\n# macOS\nbrew install gh\n\n# Linux\nsudo apt install gh  # or equivalent\n```\n\n### \"GitHub authentication required\"\n\nRun `gh auth login` and follow the prompts.\n\n### \"Could not determine GitHub username\"\n\nEnsure you're authenticated: `gh auth status`\n\n### Repository exists but can't update visibility\n\nSome visibility changes may require specific permissions or GitHub plan features.\n\n## See Also\n\n- [deploy](deploy.md) - Deploy after publishing\n- [upstream](upstream.md) - Managing forks\n","docs/commands/readme.md":"# Flow Commands Reference\n\nComplete documentation for all `f` (flow) commands.\n\n## Quick Reference\n\n| Command | Description |\n|---------|-------------|\n| [`deploy`](deploy.md) | Deploy to Linux hosts, Cloudflare Workers, or Railway |\n| [`release`](release.md) | Publish a release to registry or GitHub |\n| [`publish`](publish.md) | Publish project to GitHub |\n| [`install`](install.md) | Install a CLI/tool via registry, parm, or flox |\n| [`clone`](clone.md) | Clone repositories with git-like destination behavior |\n| [`repos`](repos.md) | Clone repositories into ~/repos |\n| [`new`](new.md) | Create a project from a local template in ~/new |\n| [`commit`](commit.md) | AI-powered commit with code review |\n| [`pr`](pr.md) | Create/open PRs and ingest GitHub feedback |\n| [`upstream`](upstream.md) | Manage upstream fork workflow |\n| [`env`](env.md) | Sync project environment and manage env vars |\n| [`config`](config.md) | Build and apply centralized Flow config outputs |\n| [`ext`](ext.md) | Manage Flow config extensions |\n| [`invariants`](invariants.md) | Validate project invariants from `flow.toml` |\n| [`fast`](fast.md) | Low-latency AI task invocation via fast client |\n| [`up`](up.md) | Bring a project up with lifecycle conventions |\n| [`down`](down.md) | Bring a project down with lifecycle conventions |\n| [`domains`](domains.md) | Shared local `*.localhost` route manager on port 80 |\n| [`tasks`](tasks.md) | List and run project tasks |\n| [`failure`](failure.md) | Inspect and copy recent task failures |\n| [`global`](global.md) | Run tasks from global flow config |\n| [`setup`](setup.md) | Print aliases or run setup task |\n| [`ai`](ai.md) | Manage AI coding sessions (Claude + Codex) |\n| [`daemon`](daemon.md) | Manage background daemons |\n| [`parallel`](parallel.md) | Run tasks in parallel |\n| [`docs`](docs.md) | Manage auto-generated documentation |\n| [`web`](web.md) | Open the Flow web UI for a project |\n| [`url`](url.md) | Inspect or crawl URLs into compact AI-friendly summaries |\n\n## Getting Started\n\n```bash\n# Show all commands\nf --help\n\n# Get help for a specific command\nf deploy --help\nf commit --help\n```\n\n## Command Categories\n\n### Deployment\n\n- **[deploy](deploy.md)** - Deploy to hosts and cloud platforms\n- **[release](release.md)** - Publish releases to registries\n- **[publish](publish.md)** - Publish project to GitHub\n\n### Version Control\n\n- **[commit](commit.md)** - AI-powered commits with review\n- **[pr](pr.md)** - PR creation/editing plus review feedback ingestion\n- **[clone](clone.md)** - Clone with git-like destination behavior\n- **[repos](repos.md)** - Clone repos into a structured directory\n- **[upstream](upstream.md)** - Fork management and sync\n- **[fixup](fixup.md)** - Fix common TOML syntax errors\n\n### Task Management\n\n- **[tasks](tasks.md)** - List project tasks\n- **[failure](failure.md)** - Inspect and copy recent task failures\n- **[fast](fast.md)** - Run AI tasks through the low-latency fast client path\n- **[up](up.md)** - Start project lifecycle (`up`/`dev`) with optional domains setup\n- **[down](down.md)** - Stop project lifecycle with optional domains teardown\n- **[global](global.md)** - Run tasks from ~/.config/flow/flow.toml\n- **[setup](setup.md)** - Print aliases or run setup task\n- **[run](run.md)** - Run a specific task\n- **[parallel](parallel.md)** - Run tasks in parallel\n- **[rerun](rerun.md)** - Re-run last task\n- **[search](search.md)** - Fuzzy search global commands\n\n### Process Management\n\n- **[ps](ps.md)** - List running flow processes\n- **[kill](kill.md)** - Stop running processes\n- **[logs](logs.md)** - View task logs\n- **[daemon](daemon.md)** - Manage background daemons\n\n### AI & Development\n\n- **[ai](ai.md)** - Manage AI coding sessions\n- **[url](url.md)** - Inspect or crawl URLs into compact summaries for AI use\n- **[agent](agent.md)** - Invoke AI subagents\n- **[match](match.md)** - Match natural language to tasks\n- **[sessions](sessions.md)** - Search AI sessions across projects\n\n### Environment & Configuration\n\n- **[env](env.md)** - Manage environment variables\n- **[config](config.md)** - Build/apply the centralized Flow config snapshot\n- **[ext](ext.md)** - Scaffold, enable, disable, and inspect Flow config extensions\n- **[invariants](invariants.md)** - Validate invariant policies in `flow.toml`\n- **[domains](domains.md)** - Shared local domain proxy ownership and route management\n- **[init](init.md)** - Scaffold a new flow.toml\n- **[doctor](doctor.md)** - Verify tools and integrations\n\n### Project Management\n\n- **[new](new.md)** - Create a project from a local starter in `~/new`\n- **[projects](projects.md)** - List registered projects\n- **[active](active.md)** - Show or set active project\n- **[hub](hub.md)** - Ensure hub daemon is running\n\n### Documentation\n\n- **[docs](docs.md)** - Manage auto-generated documentation\n- **[commits](commits.md)** - Browse commits with AI metadata\n\n### Legacy Compatibility\n\n- **[recipe](recipe.md)** - Legacy recipe command (hidden; prefer `tasks` + `.ai/tasks/*.mbt`)\n\n### Other\n\n- **[skills](skills.md)** - Manage Codex skills\n- **[install](install.md)** - Install binaries via registry/parm/flox\n- **[db](db.md)** - Manage databases and providers\n- **[tools](tools.md)** - Manage AI tools\n- **[notify](notify.md)** - Send proposal notifications\n- **[server](server.md)** - Start HTTP server for logs\n\n## Global Options\n\n```bash\n-h, --help     Print help\n-V, --version  Print version\n```\n\n## Configuration\n\nFlow uses `flow.toml` for project configuration. See [flow.toml reference](../flow-toml.md) for full documentation.\n\n## See Also\n\n- [Getting Started Guide](../getting-started.md)\n- [flow.toml Reference](../flow-toml.md)\n","docs/commands/recipe.md":"# f recipe\n\nLegacy compatibility command.\n\nPreferred model:\n\n- Put shell tasks in `flow.toml` under `[[tasks]]`.\n- Put AI/native tasks in `.ai/tasks/*.mbt`.\n- Run via `f <task>` or `f ai:<selector>`.\n\n`f recipe` remains for older repos that still use `.ai/recipes`.\n\n## Usage\n\n```bash\nf recipe list          # legacy listing\nf recipe run <selector> # legacy execution\n```\n\n## Options\n\n- `--scope <project|global|all>`: recipe source scope (default `all`)\n- `--global-dir <PATH>`: override global recipes directory\n- `--cwd <PATH>` (run only): working directory for execution\n- `--dry-run` (run only): print command without executing\n\n## Legacy Recipe Locations\n\n- Project recipes: `.ai/recipes/project` (fallback `.ai/recipes`).\n- Global recipes: `~/.config/flow/recipes`.\n\nSupported extensions: `.md`, `.markdown`, `.mbt`\n\nMoonBit recipe metadata is optional and can be declared in top comment lines:\n\n```mbt\n// title: My Fast Recipe\n// description: Run a moonbit action quickly\n// tags: [moonbit, fast]\n```\n\n## Migration\n\n```bash\n# Old\nf recipe run project:my-recipe\n\n# New\nf tasks init-ai\nf ai:my-task\n```\n","docs/commands/release.md":"# f release\n\nRelease a project based on `flow.toml` defaults or explicit subcommands.\n\n## Usage\n\n```bash\nf release\nf release registry\nf release gh\n```\n\n## Registry releases\n\n```bash\nf release registry\n```\n\n### flow.toml\n\n```toml\n[release]\ndefault = \"registry\"\nversioning = \"calver\"\n\n[release.registry]\nurl = \"https://myflow.sh\"\npackage = \"flow\"\nbins = [\"flow\", \"f\", \"lin\"]\ndefault_bin = \"flow\"\ntoken_env = \"FLOW_REGISTRY_TOKEN\"\nlatest = true\n```\n\n### Options\n\n- `--version <VERSION>`: publish a specific version.\n- `--registry <URL>`: override the registry base URL.\n- `--bin <NAME>`: override the binaries to upload (repeatable).\n- `--no-build`: skip building binaries.\n- `--latest` / `--no-latest`: control latest pointer updates.\n\n## GitHub releases\n\n```bash\nf release gh\n```\n","docs/commands/repos.md":"# f repos\n\nClone repositories into a structured local directory or create new ones.\n\nIf you want standard `git clone` destination behavior, use [`f clone`](clone.md) instead.\n\n## Overview\n\n`f repos clone` clones GitHub repositories into `~/repos/<owner>/<repo>` using SSH URLs. By default it does a shallow clone for speed, then fetches full history in the background. It always sets up an `upstream` remote and local tracking branch unless you pass `--no-upstream`. Clone-time bootstrap is local-only: it does not create or push a private mirror repo. If the target checkout already exists, Flow reports that and exits without re-bootstrapping or reopening the repo.\n`f repos create` creates a GitHub repository from the current folder and pushes it.\n\nBy default, Flow treats `~/repos` as an immutable managed root. Use `FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1` if you need to point `--root` somewhere else.\n\n## Quick Start\n\n```bash\n# Clone a GitHub repo into ~/repos/<owner>/<repo>\nf repos clone https://github.com/owner/repo\n\n# Short form\nf repos clone owner/repo\n\n# Skip upstream auto-setup\nf repos clone owner/repo --no-upstream\n\n# Full clone (skip background history fetch)\nf repos clone owner/repo --full\n\n# Create a new repo from the current folder (prompts for name/visibility)\nf repos create\n```\n\n## Options\n\n### f repos clone\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `<URL>` | | Repository URL or `owner/repo` |\n| `--root <PATH>` | | Root directory for clones (default: `~/repos`, override requires `FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1`) |\n| `--full` | | Full clone (skip shallow clone + background history fetch) |\n| `--no-upstream` | | Skip upstream setup |\n| `--upstream-url <URL>` | `-u` | Upstream URL override (skips GitHub lookup) |\n| `--no-home-branch-bootstrap` | | Skip local nikiv home-branch setup after clone |\n\n### f repos create\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--name <NAME>` | `-n` | Repository name (defaults to current folder) |\n| `--public` | | Create as public repository |\n| `--private` | | Create as private repository |\n| `--description <TEXT>` | `-d` | Description for the repository |\n| `--yes` | `-y` | Skip confirmation prompts |\n\n## Upstream Automation\n\nFlow will:\n\n1. Query GitHub via `gh api repos/<owner>/<repo>`\n2. Detect the parent repository\n3. Run `f upstream setup --url <parent>` inside the cloned repo\n\nIf the repo is not a fork (or `gh` is unavailable), flow sets `upstream` to the `origin` URL.\n\n## Background History Fetch\n\nWhen cloning in fast mode (default), flow spawns a background fetch:\n\n- `git fetch --unshallow --tags origin`\n- `git fetch --tags upstream` (if upstream was configured)\n\n## Private Mirror Setup\n\n`f repos clone` no longer creates or pushes the `fork` / `*-i` private mirror as part of clone.\n\nIf you want Flow to create or repair the private mirror workflow for an existing repo, run:\n\n```bash\nf repos bootstrap-home-branch --path ~/repos/<owner>/<repo>\n```\n\n## Examples\n\n```bash\n# Clone into a custom root (requires override)\nFLOW_REPOS_ALLOW_ROOT_OVERRIDE=1 f repos clone https://github.com/owner/repo --root ~/work/repos\n\n# Override upstream manually\nf repos clone https://github.com/your-user/repo -u git@github.com:upstream-org/repo.git\n```\n","docs/commands/reviews-todo.md":"# f reviews-todo\n\nManage deferred deep-review todos for queued commits.\n\nThis command is a workflow wrapper over `f commit-queue` for the fast-commit + deep-Codex-review loop.\n\n## Quick Start\n\n```bash\n# List pending deep-review todos (queued commits)\nf reviews-todo list\n\n# Run Codex deep review for all queued commits\nf reviews-todo codex --all\n\n# Inspect one queued review todo\nf reviews-todo show <commit-sha>\n\n# Approve all queued commits after issues are addressed\nf reviews-todo approve-all\n```\n\n## Why use this\n\n- Keep `f commit` fast.\n- Batch expensive Codex reviews later.\n- Keep one place to track deep-review backlog.\n\n## Notes\n\n- `codex --all` maps to `f commit-queue review --all`.\n- Queue entries live under `.ai/internal/commit-queue/`.\n- Review findings are still recorded into `.ai/todos/todos.json` and commit review reports.\n- If `[options].myflow_mirror = true` is enabled, queued Codex reviews from the quick path are mirrored to myflow as `commit_queue_review` events.\n- For a full speed-first operating loop in `~/code/myflow`, see [`../fast-commit-deep-review-loop.md`](../fast-commit-deep-review-loop.md).\n","docs/commands/seq-rpc.md":"# `f seq-rpc`\n\nNative `seqd` RPC bridge for Flow.\n\nUse this when an agent/workflow needs OS-level actions and you want a typed, low-overhead path.\nThis command talks to `seqd` over Unix socket directly from Rust (no `seq rpc` subprocess).\n\n## Why this command exists\n\n- Keeps protocol handling in Rust.\n- Avoids shell output parsing drift.\n- Gives stable response envelope fields (`ok`, `op`, `dur_us`, ids).\n- Matches hard policy in `docs/seq-agent-rpc-contract.md`.\n\n## Usage\n\n```bash\nf seq-rpc [--socket PATH] [--timeout-ms 5000] [--pretty] <action> ...\n```\n\nActions:\n\n- `ping`\n- `app-state`\n- `perf`\n- `open-app <name>`\n- `open-app-toggle <name>`\n- `screenshot <path>`\n- `rpc <op> [--args-json '{...}']`\n\nCommon id fields (recommended on every call):\n\n- `--request-id`\n- `--run-id`\n- `--tool-call-id`\n\nExample:\n\n```bash\nf seq-rpc open-app \"Safari\" \\\n  --request-id req-42 \\\n  --run-id run-a12 \\\n  --tool-call-id tool-7 \\\n  --pretty\n```\n\n## Socket resolution\n\n1. `--socket <path>`\n2. `SEQ_SOCKET_PATH`\n3. `SEQD_SOCKET`\n4. `/tmp/seqd.sock`\n\n## Output\n\nPrints JSON response envelope from `seqd`.\n\nOn `ok=false`, command exits non-zero after printing the response JSON.\n","docs/commands/services.md":"# f services\n\nGuided setup flows for third-party services. These commands prompt for required\nenv vars, store them in cloud, and can optionally apply them to Cloudflare.\n\n## Stripe\n\n```bash\nf services stripe\n```\n\n### Options\n\n- `--path <PATH>`: target project root (defaults to current directory).\n- `--environment <ENV>`: env store to write (default: flow.toml or `production`).\n- `--mode <test|live>`: Stripe mode (default: `test`).\n- `--force`: prompt even if keys are already set.\n- `--apply` / `--no-apply`: apply envs to Cloudflare after setup.\n\n### What it prompts for\n\nThe command inspects `flow.toml` `[cloudflare].env_keys` and asks for Stripe\nkeys found there (fallback order):\n\n- `STRIPE_SECRET_KEY`\n- `STRIPE_WEBHOOK_SECRET`\n- `STRIPE_PRO_PRICE_ID`\n- `STRIPE_REFILL_PRICE_ID`\n- `VITE_STRIPE_PUBLISHABLE_KEY`\n\n### Helpful Stripe sources\n\n- Secret/Publishable keys: Stripe Dashboard -> Developers -> API keys\n- Webhook signing secret: Stripe Dashboard -> Developers -> Webhooks (or `stripe listen --print-secret`)\n- Price IDs: Stripe Dashboard -> Products -> Price (starts with `price_`)\n\n### Example\n\n```bash\ncd ~/org/gen/new\nf services stripe --mode test --apply\n```\n","docs/commands/setup.md":"# f setup\n\nBootstrap the project if needed, generate a `flow.toml` if missing, then run the `setup` task or print shell aliases.\n\n## Quick Start\n\n```bash\n# Bootstrap if missing, generate flow.toml if missing, then run setup task or print aliases\nf setup\n\n# Configure host deployment (Linux)\nf setup deploy\n\n# Configure release hosting for server projects\nf setup release\n\n# Use a specific config file\nf setup --config ./flow.toml\n```\n\n## Behavior\n\n- If the project is not bootstrapped, it runs the bootstrap flow (`.ai/`, `.gitignore`).\n- If `flow.toml` is missing, it prompts to generate `setup` + `dev` tasks (AI via `gen` if available, otherwise manual prompts).\n- If `flow.toml` already exists, Flow non-destructively appends missing Codex baseline sections (`[skills]`, `[skills.codex]`, commit skill gate, and Bun testing gate in Bun contexts).\n- After baseline upgrades, Flow triggers a Codex skills reload (respecting `[skills.codex].force_reload_after_sync`) so open sessions pick up changes immediately.\n- If `flow.toml` defines a `setup` task, `f setup` runs that task.\n- After the `setup` task exits, Flow re-reads `flow.toml`, re-syncs task skills to `.ai/skills`, and reloads Codex skills (when configured). This makes setup-generated task changes visible to Claude/Codex immediately.\n- Otherwise, it prints shell aliases from `[alias]` in `flow.toml`.\n- `f setup deploy` adds a `[host]` section, creates a remote setup script, copies env templates, and optionally stores the deploy host.\n- `f setup release` detects server projects and offers Linux host deployment defaults.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`) |\n| `TARGET` | Optional setup target (e.g., `deploy`, `release`) |\n\n### Global Server Setup Defaults\n\nYou can provide a server template in your global config at `~/.config/flow/flow.toml`:\n\n```toml\n[setup.server]\ntemplate = \"~/infra/flow.toml\"\n```\n\nOr inline host defaults:\n\n```toml\n[setup.server.host]\nsetup = \"\"\"#!/usr/bin/env bash\nset -euo pipefail\n...\"\"\"\nenv_file = \".env.host\"\nport = 3000\n```\n","docs/commands/skills.md":"# f skills\n\nManage Codex/Claude skills for the current project.\n\nSkills live in `.ai/skills/` and are symlinked to `.codex/skills` and `.claude/skills` so active agent sessions can discover them.\n\n## Core Commands\n\n```bash\n# List local skills\nf skills\n\n# Create/edit/remove skills\nf skills new <name> -d \"description\"\nf skills edit <name>\nf skills remove <name>\n\n# Install curated skills\nf skills install <name>\n\n# Generate one skill per flow.toml task\nf skills sync\n\n# Force Codex app-server to rescan skills for this cwd\nf skills reload\n```\n\n## Codex Tight Feedback Loop\n\nUse this loop when coding with Codex/Claude:\n\n1. Make code changes.\n2. Run focused tests quickly (in Bun repos: `bun bd test ...`).\n3. Refresh skill context:\n\n```bash\nf skills sync\nf skills reload\n```\n\n4. Commit via quality gates:\n\n```bash\nf commit\n```\n\n`f skills reload` is useful for already-open Codex sessions; it refreshes the app-server skill cache without creating a new session.\n\n## `flow.toml` Settings\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n```\n\n## Built-in Default Skills\n\nFlow auto-materializes a small baseline set of project-local skills in `.ai/skills/`:\n\n- `env`\n- `quality-bun-feature-delivery`\n- `pr-markdown-body-file`\n\nThese are symlinked into `.codex/skills` and `.claude/skills` and can be reloaded with:\n\n```bash\nf skills reload\n```\n\n### `skills.codex` fields\n\n- `generate_openai_yaml`: writes `.ai/skills/<task>/agents/openai.yaml` for task-synced skills.\n- `force_reload_after_sync`: after `f skills sync` or `f skills install`, force Codex app-server `skills/list` with `forceReload: true`.\n- `task_skill_allow_implicit_invocation`: default `policy.allow_implicit_invocation` value in generated `agents/openai.yaml`.\n\n## Recommended Enforcement\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\nThis blocks commits that skip required Bun-oriented testing/skill policy.\n","docs/commands/sync.md":"# f sync\n\nSync git repo: pull from tracking remote, merge upstream changes, optionally push.\n\n## Overview\n\nSingle command to bring a repository up to date. Pulls from the tracking branch, syncs upstream if configured (fork workflow), and optionally pushes. Works with both plain git and jj (jujutsu) colocated repos.\n\n## Context Card\n\nUse this block when passing `f sync` behavior to another agent:\n\n- Default behavior: pull/sync only; push is off unless `--push`.\n- Defaults: `--stash=true`, `--fix=true`.\n- Modes: uses jj flow in healthy colocated workspaces, falls back to plain git when needed.\n- Home-branch mode: when the current branch matches `jj.home_branch`, `f sync` skips the normal tracking pull and syncs `origin/<default-branch>` into that branch.\n- Push target: configured `[git].remote` first, then standard fallback behavior.\n- Clipboard output: synced commit list is copied only when remote commit ranges are detected (typically jj fetch path).\n- Conflict note: jj can finish with unresolved conflicts and prints `jj resolve` guidance.\n\n## Quick Start\n\n```bash\n# Pull latest from remote (no push by default)\nf sync\n\n# Pull and push\nf sync --push\n\n# Pull with rebase instead of merge\nf sync -r\n\n# Pull with rebase and push\nf sync -r --push\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--rebase` | `-r` | Use rebase instead of merge when pulling |\n| `--push` | | Push to configured git remote after sync (default: off) |\n| `--no-push` | | Skip pushing (legacy; already the default) |\n| `--stash` | `-s` | Auto-stash uncommitted changes (default: true) |\n| `--stash-commits` | | Stash local JJ commits to a bookmark before syncing (jj only) |\n| `--allow-queue` | | Allow sync even when commit queue is non-empty |\n| `--create-repo` | | Create origin repo on GitHub if it doesn't exist |\n| `--fix` | `-f` | Auto-fix conflicts using Claude (default: true) |\n| `--no-fix` | | Disable auto-fix |\n| `--max-fix-attempts <N>` | | Maximum auto-fix attempts (default: 3) |\n| `--allow-review-issues` | | Allow push even if P1/P2 review todos are open |\n| `--compact` | | Legacy noise-reduction flag (jj fetch output is already compact by default) |\n\n## What Happens\n\n### Step 1: Pre-flight checks\n\n1. Detects if jj is available and healthy; falls back to git if not\n2. Checks for unmerged files and resolves them (or prompts)\n3. Handles in-progress rebase/merge\n4. Stashes uncommitted changes if `--stash` is set\n\n### Step 2: Pull from tracking branch\n\nPulls from the tracking remote/branch (e.g. `origin/main`). If the branch has no tracking info but the push remote has a matching branch, auto-configures tracking.\n\n- With `--rebase`: runs `git pull --rebase`\n- Without: runs `git pull --no-rebase --no-edit` (merge without opening an editor)\n- Auto-resolves conflicts when `--fix` is enabled\n\n### Step 3: Sync upstream\n\nIf an `upstream` remote exists (fork workflow), fetches and merges upstream changes into the current branch.\n\nIf no `upstream` remote but on a feature branch, syncs from `origin/<default-branch>` (e.g. `origin/main`) into the current branch.\n\n### Home-branch mode\n\nIf the current branch matches the resolved `jj.home_branch`, Flow treats that branch as your\nlong-lived integration branch.\n\nIn that mode, `f sync`:\n\n- skips the normal tracking-branch pull\n- leaves branch tracking config untouched\n- syncs `origin/<default-branch>` into the home branch\n- keeps all non-home branches on the existing sync behavior\n\nHome-branch resolution order is:\n\n1. `<repo>/flow.toml` `jj.home_branch`\n2. `~/.config/flow/flow.toml` `jj.home_branch`\n3. basename of `$HOME`\n4. `USER` or `USERNAME`\n\n### Step 4: Push (optional)\n\nOnly when `--push` is passed:\n\n- Detects fork push targets (redirects to private fork remote if configured)\n- Checks review-todo gate (blocks if P1/P2 issues are open unless `--allow-review-issues`)\n- Skips push if the push remote equals upstream (read-only clone)\n- Creates repo with `--create-repo` if origin doesn't exist\n\n### Step 5: Restore stash\n\nRestores auto-stashed changes if any were stashed in step 1.\n\n### Step 6: Synced commit list + clipboard\n\nWhen remote commit ranges are discovered (typically during jj fetch), Flow prints a deduplicated\nlist of newly synced commits (hash + subject) and copies that same list to your clipboard.\n\nIf no synced commit ranges were detected, this section is skipped.\n\nSet `FLOW_NO_CLIPBOARD=1` to disable clipboard copy.\n\n## JJ (Jujutsu) Support\n\nWhen a `.jj` directory is present and healthy, sync uses the jj flow instead of plain git. Falls back to git if:\n\n- Configured `git.remote` is not `origin`/`upstream`\n- Tracking remote is a custom remote\n- jj workspace is unhealthy or corrupt\n\nUse `--stash-commits` to bookmark local jj commits before syncing.\n\njj fetch output is compact by default; synced commit details are emitted once at the end for clipboard use.\n\n## Commit Queue Guard\n\nIf the commit queue has pending entries and sync would rebase (rewriting SHAs), sync refuses to proceed. Use `--allow-queue` to override, or process the queue first with `f commit-queue list`.\n\n## Configuration\n\n### Push remote\n\nSet in `flow.toml` under `[git]`:\n\n```toml\n[git]\nremote = \"origin\"  # default push remote\n\n[jj]\nhome_branch = \"alice\" # optional long-lived personal integration branch\n```\n\n### Fork push\n\nWhen a fork push target is configured, sync redirects push to the fork remote automatically.\n\n## Examples\n\n```bash\n# Basic sync (pull only)\nf sync\n\n# Sync and push\nf sync --push\n\n# Rebase workflow\nf sync -r --push\n\n# Sync a fork (has upstream remote)\nf sync --push\n\n# Create missing origin and push\nf sync --push --create-repo\n\n# Skip auto-fix for conflicts\nf sync --no-fix\n\n# Allow sync with pending commit queue\nf sync --allow-queue\n```\n\n## Troubleshooting\n\n### \"Unmerged files detected\"\n\nSync found files with unresolved merge conflicts. By default (`--fix`), it tries to auto-resolve. If that fails, resolve manually:\n\n```bash\ngit status                # see conflicted files\n# edit and fix conflicts\ngit add <files>\nf sync                    # retry\n```\n\n### \"Commit queue is not empty\"\n\nRebase-based sync can rewrite commit SHAs, breaking queued commits. Either:\n\n```bash\nf commit-queue list       # review the queue\nf sync --allow-queue      # override the guard\n```\n\n### \"Remote unreachable\"\n\nThe push remote doesn't exist or auth/network failed. For missing origin:\n\n```bash\nf sync --push --create-repo\n```\n\n### jj corruption fallback\n\nIf jj sync fails due to workspace/store issues, sync automatically retries with plain git. Fix jj with:\n\n```bash\njj git import\n# or if still broken:\nrm -rf .jj && jj git init --colocate\n```\n\n### \"Sync complete (jj) but conflicts remain\"\n\nThis means sync/rebase completed but conflict revisions still exist in jj.\n\n```bash\njj resolve\n```\n\n## See Also\n\n- [upstream](upstream.md) - Manage upstream fork workflow\n- [commit](commit.md) - Commit changes\n- [jj](jj.md) - Jujutsu workflow helpers\n","docs/commands/tasks.md":"# f tasks\n\nList and discover project tasks from:\n\n- `flow.toml` (`[[tasks]]`)\n- `.ai/tasks/*.mbt` (AI MoonBit tasks)\n\nYou can run tasks directly with `f <task>`.\n\n## Usage\n\n```bash\nf tasks\nf tasks list\nf tasks dupes\nf tasks init-ai\nf tasks build-ai ai:flow/dev-check\nf tasks run-ai ai:flow/dev-check\nf tasks run-ai --daemon ai:flow/dev-check\nf tasks daemon start\nf tasks daemon status\nf tasks daemon stop\nf ai-taskd-launchd-install\nf ai-taskd-launchd-status\ncargo build --release -p ai-taskd-client --bin ai-taskd-client\n./target/release/ai-taskd-client ai:flow/dev-check\nf install-ai-fast-client\nf fast ai:flow/dev-check\nf bench-ai-runtime --iterations 80 --warmup 10\nf bench-ffi-boundary --iters 10000000\nf bench-ffi-boundary --iters 10000000 --native-opt\n```\n\n## AI Task Workflow\n\nInitialize a starter MoonBit task:\n\n```bash\nf tasks init-ai\n```\n\nThis creates:\n\n```text\n.ai/tasks/starter.mbt\n```\n\nRun it:\n\n```bash\nf starter\nf ai:starter\n```\n\nAdd more tasks as `.mbt` files under `.ai/tasks/` and run by name or selector:\n\n```bash\nf release-flow\nf ai:project/release-flow\n```\n\n## Notes\n\n- Default execution mode is cached native binary:\n  1) `moon build --target native --release` once per content hash\n  2) run cached artifact from `~/Library/Caches/flow/ai-tasks/...`\n- Use `f tasks run-ai --no-cache ...` (or `FLOW_AI_TASK_RUNTIME=moon-run`) to force direct `moon run`.\n- Set `FLOW_AI_TASK_MODE=release` for release builds (`--release`).\n- Set `FLOW_AI_TASK_MODE=js` to run with JS target.\n- `f tasks daemon` runs a lightweight local `ai-taskd` over Unix socket for warm repeated runs.\n- For lowest invocation overhead, use the tiny client binary against the daemon:\n- `cargo build --release -p ai-taskd-client --bin ai-taskd-client`\n  - `./target/release/ai-taskd-client ai:<selector>`\n  - or `f install-ai-fast-client` then use `fai ai:<selector>`\n  - This bypasses full `f` startup for hot-loop calls.\n- `fai` supports:\n  - `--protocol msgpack|json` (msgpack default)\n  - `--timings` (server-side phase timings)\n  - `--batch-stdin` (pooled burst mode in one client process)\n- For stable startup/jitter, prefer always-on daemon via launchd:\n  - `f ai-taskd-launchd-install`\n  - `f ai-taskd-launchd-status`\n  - `f ai-taskd-launchd-logs`\n- Automatic preference for latency-critical AI selectors:\n  - Opt in with `FLOW_AI_TASK_FAST_CLIENT=1` (typically together with `FLOW_AI_TASK_DAEMON=1`).\n  - Then `f` will auto-prefer fast client dispatch for AI tasks tagged `fast`, `latency`, `hot`, or `hotkey`.\n  - Override selector matching with `FLOW_AI_TASK_FAST_SELECTORS` (comma-separated patterns, supports `*` prefix/suffix).\n  - Override client binary with `FLOW_AI_TASK_FAST_CLIENT_BIN=/path/to/fai`.\n- `f recipe` still exists for legacy compatibility, but task-centric workflow is preferred.\n","docs/commands/up.md":"# f up\n\nBring a project up using lifecycle conventions.\n\n## Quick Start\n\n```bash\n# Run lifecycle up (tries task \"up\", then \"dev\")\nf up\n\n# Pass args through to the selected task\nf up -- --port 3001\n```\n\n## Behavior\n\n- Loads nearest `flow.toml` (or `--config` path).\n- If `[lifecycle.domains]` is configured:\n  - runs `f domains add <host> <target> --replace`\n  - runs `f domains up` (with configured engine when set)\n- Runs lifecycle task:\n  - `[lifecycle].up_task` when configured\n  - otherwise fallback order: `up`, then `dev`\n\nIf no up task is found, command fails with guidance.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`, searches upward when default is missing) |\n| `ARGS...` | Extra args passed to the selected lifecycle task |\n\n## Recommended myflow config\n\n```toml\n[lifecycle]\nup_task = \"dev\"\n\n[lifecycle.domains]\nhost = \"myflow.localhost\"\ntarget = \"127.0.0.1:3000\"\nengine = \"native\"\nremove_on_down = false\nstop_proxy_on_down = false\n```\n","docs/commands/upstream.md":"# f upstream\n\nManage upstream fork workflow.\n\n## Overview\n\nSet up and sync forks with their upstream repositories. Creates a local `upstream` branch to cleanly track the original repo, making merges easier.\n\n## Quick Start\n\n```bash\n# Set up upstream tracking\nf upstream setup --upstream-url https://github.com/original/repo\n\n# Pull latest from upstream\nf upstream pull\n\n# Full sync: pull, merge, push\nf upstream sync\n```\n\n## Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `status` | Show current upstream configuration |\n| `setup` | Set up upstream remote and local tracking branch |\n| `pull` | Pull changes from upstream into local 'upstream' branch |\n| `sync` | Full sync: pull upstream, merge to dev/main, push to origin |\n\n---\n\n## Setup\n\nConfigure upstream tracking for a forked repository:\n\n```bash\n# Basic setup\nf upstream setup --upstream-url https://github.com/original/repo\n\n# Specify branch (if not main)\nf upstream setup --upstream-url https://github.com/original/repo --upstream-branch master\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--upstream-url <URL>` | `-u` | URL of the upstream repository |\n| `--upstream-branch <BRANCH>` | `-b` | Branch name on upstream (default: auto-detected) |\n\n### What Happens\n\n1. Adds `upstream` remote pointing to original repo\n2. Fetches upstream branches\n3. Creates local `upstream` branch tracking the upstream's default branch\n4. Stores configuration in `.git/config`\n\n---\n\n## Pull\n\nPull latest changes from upstream into local `upstream` branch:\n\n```bash\n# Pull into upstream branch\nf upstream pull\n\n# Pull and also merge into specific branch\nf upstream pull --branch main\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--branch <BRANCH>` | `-b` | Also merge into this branch after pulling |\n\n---\n\n## Sync\n\nFull sync workflow - pulls upstream, merges to your branch, and pushes:\n\n```bash\n# Full sync (pull, merge, push)\nf upstream sync\n\n# Sync without pushing (for review first)\nf upstream sync --no-push\n```\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `--no-push` | Skip pushing to origin |\n\n### What Happens\n\n1. Stashes any uncommitted changes\n2. Fetches latest from upstream\n3. Updates local `upstream` branch\n4. Merges upstream into your current branch (e.g., `main`)\n5. Pushes to origin (unless `--no-push`)\n6. Restores stashed changes\n\n### Branch Detection\n\nFlow auto-detects the upstream default branch:\n- Checks `refs/remotes/upstream/HEAD`\n- Falls back to checking if `upstream/main` or `upstream/master` exists\n- Uses `main` as final fallback\n\n---\n\n## Status\n\nShow current upstream configuration:\n\n```bash\nf upstream status\n```\n\nOutput:\n```\nUpstream Configuration\n  Remote: https://github.com/original/repo\n  Branch: main\n  Local tracking: upstream -> upstream/main\n  Last sync: 2 hours ago\n```\n\n---\n\n## Workflow Example\n\n### Initial Fork Setup\n\n```bash\n# 1. Clone your fork\ngit clone https://github.com/youruser/project\ncd project\n\n# 2. Set up upstream tracking\nf upstream setup --upstream-url https://github.com/original/project\n\n# 3. Verify\nf upstream status\n```\n\n### Regular Sync\n\n```bash\n# When you want to sync with upstream:\nf upstream sync\n\n# Or if you want to review before pushing:\nf upstream sync --no-push\ngit log --oneline main..upstream  # See what's new\ngit push  # Push when ready\n```\n\n### Handling Conflicts\n\nIf sync encounters merge conflicts:\n\n```bash\n$ f upstream sync\nMerging upstream into main...\nCONFLICT (content): Merge conflict in src/lib.rs\n\n# Fix conflicts manually\nvim src/lib.rs\ngit add src/lib.rs\ngit commit\n\n# Then push\ngit push\n```\n\n---\n\n## Configuration\n\nUpstream configuration is stored in `.git/config`:\n\n```ini\n[remote \"upstream\"]\n    url = https://github.com/original/repo\n    fetch = +refs/heads/*:refs/remotes/upstream/*\n\n[branch \"upstream\"]\n    remote = upstream\n    merge = refs/heads/main\n```\n\nYou can also manually configure:\n\n```bash\ngit remote add upstream https://github.com/original/repo\ngit fetch upstream\ngit branch upstream upstream/main\n```\n\n---\n\n## Troubleshooting\n\n### \"upstream remote not found\"\n\nRun `f upstream setup` first with the upstream URL.\n\n### \"git stash pop failed\"\n\nThis can happen if there were no changes to stash. Flow handles this automatically by tracking stash state.\n\n### Upstream uses master instead of main\n\nFlow auto-detects the default branch. If detection fails, specify explicitly:\n\n```bash\nf upstream setup --upstream-url https://github.com/original/repo --upstream-branch master\n```\n\n### Merge conflicts\n\nResolve conflicts manually:\n1. Fix conflicting files\n2. `git add <files>`\n3. `git commit`\n4. `git push`\n\n## See Also\n\n- [commit](commit.md) - Commit changes after sync\n- [publish](publish.md) - Publish to GitHub\n","docs/commands/url.md":"# `f url`\n\nInspect or crawl URLs into compact AI-friendly summaries.\n\n## Quick Start\n\n```bash\n# Thin single-page summary\nf url inspect https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\n\n# Force Cloudflare Browser Rendering markdown\nf url inspect --provider cloudflare https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\n\n# Machine-readable output\nf url inspect --json https://linear.app/example-workspace/project/example-project-v1-1234567890ab/overview\n\n# Explicit site crawl (Cloudflare Browser Rendering)\nf url crawl https://developers.cloudflare.com/browser-rendering/rest-api/crawl-endpoint/ --limit 3 --records 2\n```\n\n## `inspect`\n\n`f url inspect <url>` uses this provider order:\n\n1. Cloudflare Browser Rendering markdown\n2. configured scraper backend from `[skills.seq]`\n3. direct fetch fallback\n\nDefault output is intentionally compact:\n\n- title\n- URL\n- content type\n- short description\n- short excerpt\n\nUse `--full` to include the full markdown/content body.\n\n## `crawl`\n\n`f url crawl <url>` is the explicit multi-page path.\n\nIt currently uses Cloudflare Browser Rendering crawl and polls until the job completes or the wait timeout is reached.\n\nUseful flags:\n\n```bash\nf url crawl <url> --limit 10 --records 5\nf url crawl <url> --depth 2 --render\nf url crawl <url> --include-pattern \"https://developers.cloudflare.com/browser-rendering/*\"\nf url crawl <url> --exclude-pattern \"*/changelog/*\"\nf url crawl <url> --json\n```\n\nDefaults are tuned to stay small:\n\n- `--limit 10`\n- `--depth 2`\n- `--records 5`\n- `--render false`\n\n## Auth\n\nCloudflare auth is read from:\n\n1. shell env\n2. Flow personal env store fallback\n\nRequired keys:\n\n- `CLOUDFLARE_ACCOUNT_ID`\n- `CLOUDFLARE_API_TOKEN`\n\nNo daemon is required.\n\n## Config\n\nIf you have a local scraper backend, `f url inspect` reuses `[skills.seq]` settings from repo `flow.toml` or global `~/.config/flow/flow.toml`:\n\n```toml\n[skills.seq]\nscraper_base_url = \"http://127.0.0.1:7444\"\nscraper_api_key = \"...\"\ncache_ttl_hours = 2\nallow_direct_fallback = true\n```\n","docs/commands/web.md":"# web\n\nOpen the Flow web UI for the current project.\n\n## Usage\n\n```bash\nf web\n```\n\n## What it does\n\n- Serves the `.ai/web` UI for the current project.\n- Exposes `/api/projects` for project metadata and top-level `.ai` entries.\n- Exposes `/api/ai` for the full `.ai` tree (paths + kinds).\n- Exposes `/api/sessions` for Claude/Codex session summaries and transcripts.\n- Exposes `/api/openapi` when an OpenAPI spec is detected.\n\n## Options\n\n```bash\n--host <host>   Host to bind (default: 127.0.0.1)\n--port <port>   Port to serve the UI on (default: 9310)\n```\n\n## Notes\n\n- `f web` serves `.ai/web/dist` when it exists (Vite default output).\n- The Vite app source lives in `.ai/web`.\n- `.ai/web` is gitignored by default so AI can freely rewrite it.\n- If no build exists, `f web` shows a minimal placeholder.\n- Example build: `vite build` from `.ai/web`.\n- `f web` now runs `bun install` (once) and `bun run build` automatically when a Vite app is present.\n","tools/domainsd-cpp/readme.md":"# domainsd-cpp (experimental)\n\n`domainsd-cpp` is an experimental native local-domains proxy used by:\n\n- `f domains --engine native up`\n- `f domains --engine native down`\n\nIt is designed for low overhead on localhost routing and keeps Flow route state in:\n\n- `~/.config/flow/local-domains/routes.json`\n\nCurrent scope:\n- HTTP/1.1 host-based routing (`*.localhost` -> `host:port`)\n- WebSocket upgrade passthrough (full duplex tunnel)\n- request-side chunked transfer-encoding decode/forward\n- upstream keepalive connection pooling (safe framed-response reuse)\n- overload shedding with bounded active client handlers (`503` when saturated)\n- upstream connect/IO timeouts (`504` for connect timeout)\n- health endpoint: `GET /_flow/domains/health`\n- mtime-based route reload (no daemon restart required)\n- optional macOS launchd socket activation (`--launchd-socket <name>`) for privileged `:80` bind without Docker\n\nRuntime tuning:\n- daemon supports CLI flags (`--max-active-clients`, `--upstream-*-timeout-ms`, `--pool-*`)\n- Flow passes tuning via env vars prefixed `FLOW_DOMAINS_NATIVE_*`\n\nCurrent limitations:\n- no HTTP/2/TLS yet\n\nThe Flow CLI builds this binary automatically with `clang++` when needed.\n\n## macOS native `:80` without Docker\n\nWhen direct bind to `127.0.0.1:80` is blocked by permissions, install launchd socket mode once:\n\n```bash\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nThis installs `dev.flow.domainsd` in `/Library/LaunchDaemons`, binds port `80` via launchd, and runs `domainsd-cpp` as your user with inherited socket fd.\n\nUninstall:\n\n```bash\nsudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh\n```\n",".cursorrules (gitflow.mdc)":"# Gitflow Workflow Rules\n\n## Main Branches\n\n### main (or master)\n- Contains production-ready code\n- Never commit directly to main\n- Only accepts merges from:\n  - hotfix/* branches\n  - release/* branches\n- Must be tagged with version number after each merge\n\n### develop\n- Main development branch\n- Contains latest delivered development changes\n- Source branch for feature branches\n- Never commit directly to develop\n\n## Supporting Branches\n\n### feature/*\n- Branch from: develop\n- Merge back into: develop\n- Naming convention: feature/[issue-id]-descriptive-name\n- Example: feature/123-user-authentication\n- Must be up-to-date with develop before creating PR\n- Delete after merge\n\n### release/*\n- Branch from: develop\n- Merge back into: \n  - main\n  - develop\n- Naming convention: release/vX.Y.Z\n- Example: release/v1.2.0\n- Only bug fixes, documentation, and release-oriented tasks\n- No new features\n- Delete after merge\n\n### hotfix/*\n- Branch from: main\n- Merge back into:\n  - main\n  - develop\n- Naming convention: hotfix/vX.Y.Z\n- Example: hotfix/v1.2.1\n- Only for urgent production fixes\n- Delete after merge\n\n## Commit Messages\n\n- Format: `type(scope): description`\n- Types:\n  - feat: New feature\n  - fix: Bug fix\n  - docs: Documentation changes\n  - style: Formatting, missing semicolons, etc.\n  - refactor: Code refactoring\n  - test: Adding tests\n  - chore: Maintenance tasks\n\n## Version Control\n\n### Semantic Versioning\n- MAJOR version for incompatible API changes\n- MINOR version for backwards-compatible functionality\n- PATCH version for backwards-compatible bug fixes\n\n## Pull Request Rules\n\n1. All changes must go through Pull Requests\n2. Required approvals: minimum 1\n3. CI checks must pass\n4. No direct commits to protected branches (main, develop)\n5. Branch must be up to date before merging\n6. Delete branch after merge\n\n## Branch Protection Rules\n\n### main & develop\n- Require pull request reviews\n- Require status checks to pass\n- Require branches to be up to date\n- Include administrators in restrictions\n- No force pushes\n- No deletions\n\n## Release Process\n\n1. Create release branch from develop\n2. Bump version numbers\n3. Fix any release-specific issues\n4. Create PR to main\n5. After merge to main:\n   - Tag release\n   - Merge back to develop\n   - Delete release branch\n\n## Hotfix Process\n\n1. Create hotfix branch from main\n2. Fix the issue\n3. Bump patch version\n4. Create PR to main\n5. After merge to main:\n   - Tag release\n   - Merge back to develop\n   - Delete hotfix branch"},"items":[{"name":"agents.md","path":".ai/agents.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/.ai/agents.md","title":".ai - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Autonomous Agent Instructions\n\nProject: flow\n\nThis project is configured for autonomous AI agent workflows with human-in-the-loop approval.\n\n## Response Format\n\n**Every response MUST end with exactly one of these signals on the final line:**\n\n### Success signals\n\n```\ndone.\n```\nUse when task completed successfully with high certainty. No further action needed.\n\n```\ndone: <message>\n```\nUse when task completed with context to share. Example: `done: Added login command with --token flag`\n\n### Needs human input\n\n```\nneedsUpdate: <message>\n```\nUse when you need human decision or action. Example: `needsUpdate: Should I use OAuth or API key auth?`\n\n### Error signals\n\n```\nerror: <message>\n```\nUse when task failed or cannot proceed. Example: `error: Build failed - missing dependency xyz`\n\n## Rules\n\n1. **Always end with a signal** - The last line must be one of the above\n2. **One signal only** - Never combine signals\n3. **Be specific** - Include actionable context in messages\n4. **No quotes** - Write signals exactly as shown, no wrapping quotes\n\n## Examples\n\n### Successful implementation\n```\nAdded the new CLI command with all requested flags.\n\ndone.\n```\n\n### Completed with context\n```\nRefactored the auth module to use the new token format.\n\ndone: Auth now supports both JWT and API key methods\n```\n\n### Need human decision\n```\nFound two approaches for caching:\n1. Redis - better for distributed systems\n2. In-memory - simpler, faster for single instance\n\nneedsUpdate: Which caching approach should I use?\n```\n\n### Error occurred\n```\nAttempted to run tests but encountered issues.\n\nerror: Test suite requires DATABASE_URL environment variable\n```\n","isInternal":false,"tokens":369,"sizeBytes":1657},{"name":"agents.md","path":"agents.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/agents.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# Assistant Rules (flow)\n\nOnly load skills when the request clearly needs them.\n\n## Skills (on-demand)\n- flow-native: Use for Flow CLI native workflows (env setup, secrets, deploys, logs, deps), for repos with `flow.toml`, or Cloudflare Workers. Avoid direct pnpm/wrangler unless asked.\n- flow-interactive: Use when commands are interactive or could block on stdin (e.g., `f setup`).\n- flow-dev-traces: Use when debugging Flow proxy behavior, tracing requests, or when the user asks about proxyx, trace-summary.json, or flow trace commands.\n- flow-usage: Use when running or troubleshooting Flow command behavior.\n- internal-ai-inference: Use only when asked to run inference or integrate with internal AI tooling.\n\nDefault: Avoid loading skills for routine edits, reviews, or simple questions.\n\n## Deploy / Restart Policy\n\n- When changes affect the installed Flow CLI or built-in Codex daemon path,\n  prefer an explicit deploy + daemon reload instead of leaving runtime state\n  stale.\n- Use `deploy-with-codexd-reload` after edits in areas like `src/ai.rs`,\n  `src/codexd.rs`, `src/daemon.rs`, `src/supervisor.rs`, or `src/config.rs`\n  when those changes affect Codex runtime, daemon behavior, or Flow-managed\n  session recovery.\n- Use `deploy-with-hub-reload` for hub-facing changes that need `lin` / docs\n  processes refreshed.\n- For `codexd`, prefer explicit `stop` + `start` in automation over a single\n  restart command so the stop/start boundary is visible in logs.\n","isInternal":false,"tokens":349,"sizeBytes":1473},{"name":"skill.md","path":".ai/skills/env/skill.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/.ai/skills/env/skill.md","title":"env","category":"anthropic-skill","format":"markdown","content":"---\nname: env\ndescription: Manage environment variables and secrets with flow (always use Flow env store)\nsource: flow-default\n---\n\n# Environment Variables & Secrets\n\nFlow provides a secure way to manage environment variables across projects.\n\n## Rules (Must)\n\n- Always use Flow env store for secrets/tokens in Flow projects.\n- Do not rely on shell env vars or `.env` files for secrets unless they are injected via `f env`.\n- For tasks/scripts that need secrets, fetch them with `f env get` or run via `f env run`.\n\n## Setup\n\n### 1. Define variables in flow.toml\n\nAdd a `[storage]` section to your project's `flow.toml`:\n\n```toml\n[storage]\nprovider = \"myflow.sh\"\n\n[[storage.envs]]\nname = \"local\"\ndescription = \"Local development\"\nvariables = [\n  { key = \"DATABASE_URL\" },\n  { key = \"API_KEY\" },\n  { key = \"SECRET_TOKEN\", default = \"\" },\n]\n```\n\n### 2. Set environment variables\n\nUse `f env set` to store values:\n\n```bash\n# Set individual env vars\nf env set API_KEY=abc123\nf env set DATABASE_URL=\"postgres://...\"\n\n# Values are stored in ~/.config/flow/env-local/personal/production.env\n```\n\n### 3. Pull env vars to local .env\n\n```bash\n# Pull all env vars for the current environment\nf env pull\n\n# Show current env vars\nf env list\n\n# Get specific var\nf env get API_KEY\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `f env set KEY=value` | Store an env var |\n| `f env pull` | Pull env vars to local .env file |\n| `f env push` | Push local .env to cloud |\n| `f env list` | List env vars for this project |\n| `f env get KEY` | Get specific env var(s) |\n| `f env keys` | Show configured env keys from flow.toml |\n| `f env setup` | Interactive env setup |\n| `f env guide` | Guided prompt to set required vars |\n| `f env run <cmd>` | Run command with env vars injected |\n\n## Environment Selection\n\nFlow supports multiple environments:\n\n```toml\n[[storage.envs]]\nname = \"local\"\nvariables = [{ key = \"DATABASE_URL\" }]\n\n[[storage.envs]]\nname = \"staging\"\nvariables = [{ key = \"DATABASE_URL\" }]\n\n[[storage.envs]]\nname = \"production\"\nvariables = [{ key = \"DATABASE_URL\" }]\n```\n\n## Example: Spotify CLI\n\n```toml\n[storage]\nprovider = \"myflow.sh\"\n\n[[storage.envs]]\nname = \"local\"\ndescription = \"Spotify API credentials\"\nvariables = [\n  { key = \"SPOTIFY_CLIENT_ID\" },\n  { key = \"SPOTIFY_CLIENT_SECRET\" },\n  { key = \"SPOTIFY_ACCESS_TOKEN\" },\n  { key = \"SPOTIFY_REFRESH_TOKEN\", default = \"\" },\n]\n```\n\nThen:\n```bash\n# Set your credentials (example values)\nf env set SPOTIFY_CLIENT_ID=example_client_id\nf env set SPOTIFY_CLIENT_SECRET=example_client_secret\n\n# Run CLI with env vars injected\nf env run bun run src/main.ts now\n\n# Or pull to .env first\nf env pull\nsource .env\nbun run src/main.ts now\n```\n\n## Task pattern (required for secrets)\n\nWhen writing Flow tasks, prefer:\n\n```bash\nMY_TOKEN=\"$(FLOW_ENV_BACKEND=local f env get --personal MY_TOKEN -f value 2>/dev/null || true)\"\nif [ -z \"${MY_TOKEN:-}\" ]; then\n  echo \"MY_TOKEN missing. Save it with envnew MY_TOKEN=...\"\n  exit 1\nfi\nexport MY_TOKEN\n```\n\n## One-time passwords (1Password Connect)\n\nUse Flow's OTP command to fetch TOTP codes from 1Password Connect:\n\n```bash\nf otp get <vault> <item> [--field <label>]\n```\n\nRequires:\n- `OP_CONNECT_HOST`\n- `OP_CONNECT_TOKEN` (env or Flow personal env store)\n\n## Storage Locations\n\n- **Personal env vars:** `~/.config/flow/env-local/personal/production.env`\n- **Project env vars:** Stored via myflow.sh cloud backend\n- **Local .env:** Created in project root via `f env pull`\n\n## Authentication\n\nFlow uses a token stored in `~/.config/flow/auth.toml` to authenticate. If you haven't authenticated:\n\n```bash\nf auth login\n```\n\n## Security Notes\n\n- Personal env vars stored locally in `~/.config/flow/`\n- Project env vars can be synced to cloud via `f env push`\n- Never commit `.env` files to git (add to `.gitignore`)\n- Use `f env run` to inject vars without creating .env files\n","frontmatter":{"name":"env","description":"Manage environment variables and secrets with flow (always use Flow env store)","source":"flow-default"},"isInternal":false,"tokens":1034,"sizeBytes":3876},{"name":"skill.md","path":".ai/skills/pr-markdown-body-file/skill.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/.ai/skills/pr-markdown-body-file/skill.md","title":"pr-markdown-body-file","category":"anthropic-skill","format":"markdown","content":"---\nname: pr-markdown-body-file\ndescription: Always edit/create GitHub PR bodies from a markdown file; never inline escaped newlines.\nversion: 1\nsource: flow-default\n---\n\n# PR Markdown Body Discipline\n\nUse this skill when creating or editing pull requests.\n\n## Rules (Must)\n\n- Never pass multi-line PR text via a quoted CLI string with `\\n`.\n- Always use a markdown file with `--body-file`.\n- Prefer `f pr open edit` when available for local file-driven PR editing.\n\n## Why\n\nInline escaped newlines are fragile and can produce literal `\\n` text in GitHub PR descriptions.\n`--body-file` is deterministic and reviewable.\n\n## Safe patterns\n\n### Create PR (GitHub CLI)\n\n```bash\ncat > /tmp/pr-body.md <<'EOF'\n## Summary\n- ...\n\n## Scope\n- ...\nEOF\n\ngh pr create --title \"...\" --body-file /tmp/pr-body.md\n```\n\n### Edit existing PR\n\n```bash\ncat > /tmp/pr-body.md <<'EOF'\n## Summary\n- ...\nEOF\n\ngh pr edit <number> --body-file /tmp/pr-body.md\n```\n\n### Flow-native edit loop\n\n```bash\nf pr open edit\n```\n\nThis opens a local markdown file and syncs title/body on save.\n\n## Verification\n\n- Run:\n\n```bash\ngh pr view <number> --json body -q .body\n```\n\n- Confirm markdown renders correctly and contains no literal `\\n`.\n","frontmatter":{"name":"pr-markdown-body-file","description":"Always edit/create GitHub PR bodies from a markdown file; never inline escaped newlines.","version":1,"source":"flow-default"},"isInternal":false,"tokens":303,"sizeBytes":1202},{"name":"skill.md","path":".ai/skills/quality-bun-feature-delivery/skill.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/.ai/skills/quality-bun-feature-delivery/skill.md","title":"quality-bun-feature-delivery","category":"anthropic-skill","format":"markdown","content":"---\nname: quality-bun-feature-delivery\ndescription: Enforce tight Codex/Claude delivery loop with Bun-first testing, skill sync/reload, and commit quality gates.\nversion: 2\nsource: flow-default\n---\n\n# Quality Bun Feature Delivery\n\nUse this workflow for every feature/change.\n\n## Rules (Must)\n\n- In Bun repos, run tests with `bun bd test ...` (never `bun test` for final validation).\n- Run only relevant tests first (single file/filter) for fast feedback.\n- Keep `.ai/features/*.md` and tests current for touched features.\n- Do not finish work without a passing local verification command.\n\n## Tight Loop\n\n1. Update code + tests.\n2. Run focused tests with Bun debug build:\n\n```bash\nbun bd test <target-test-file> -t \"<optional filter>\"\n```\n\n3. Sync task skills to keep agent context fresh:\n\n```bash\nf skills sync\n```\n\n4. Force Codex to reload skills for this cwd:\n\n```bash\nf skills reload\n```\n\n5. Commit through Flow quality gates:\n\n```bash\nf commit\n```\n\n## Bun Regression Check (for new tests)\n\nWhen adding/changing tests in Bun itself, ensure the test fails on system Bun and passes on debug Bun:\n\n```bash\nUSE_SYSTEM_BUN=1 bun test <target-test-file>\nbun bd test <target-test-file>\n```\n\n## Recommended flow.toml\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n","frontmatter":{"name":"quality-bun-feature-delivery","description":"Enforce tight Codex/Claude delivery loop with Bun-first testing, skill sync/reload, and commit quality gates.","version":2,"source":"flow-default"},"isInternal":false,"tokens":424,"sizeBytes":1690},{"name":"ai.md","path":"docs/commands/ai.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/ai.md","title":"Command: /ai","category":"command-prompt","format":"markdown","content":"# f ai\n\nManage Claude Code, Codex, and Cursor sessions for the current project.\n\nFlow reads local session stores, filters by current project path, and gives you one interface for list/search/resume/copy/save.\nWhen you need to reopen a repo's session from another working directory, use `--path <project-root>` on `resume` or provider-specific `continue`.\nCursor transcripts are supported for reading only.\n\nArchitecture note:\n\n- for the underlying transport split between wrapped Codex CLI, `jd`, and `codex app-server`, see `docs/codex-interface.md`\n\n## Quick Start\n\n```bash\n# Fuzzy-pick a recent session (Claude + Codex + Cursor)\nf ai\n\n# Provider-specific list/read\nf ai claude list\nf ai codex list\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\nf ai cursor list\nf codex resolve \"latest\"\nf codex resolve \"https://linear.app/.../project/.../overview\" --json\nf codex open \"continue the deploy work\"\nf codex agent list\nf codex agent show commit\nf ai claude resume <session-id-or-name>\nf ai codex resume <session-id-or-name>\nf ai codex resume --path ~/work/example-project\nf ai codex continue --path ~/work/example-project\nf ai codex find --path ~/repos/openai/codex \"where does codex store\"\nf ai codex find --all-history --path ~/repos/openai/codex \"older migration plan\"\nf ai codex find --recent-days 30 --path ~/repos/openai/codex \"thread/read\"\nf ai codex find --json --limit 5 --path ~/repos/openai/codex \"thread/read\"\nf codex connect --path ~/repos/openai/codex --exact-cwd --json \"app-server\"\nf codex connect --all-history --path ~/repos/openai/codex \"old designer cutover\"\nf ai cursor context - /path/to/repo 3\nf cursor copy\n\n# Save a memorable alias for a session\nf ai save reclaim-fix --id a38cf8bf-f4e2-4308-8b27-0254f89c4385\n```\n\n## Session Sources\n\n- Claude: `~/.claude/projects/<project-path>/*.jsonl`\n- Codex: `~/.codex/sessions/**/*.jsonl` (Flow matches by `session_meta.cwd`)\n- Cursor: `~/.cursor/projects/<project-key>/agent-transcripts/<session-id>/<session-id>.jsonl`\n- Saved aliases: `.ai/sessions/claude/index.json` in your repo\n\n## Resume Behavior (Important)\n\n### TTY requirement\n\nResume is interactive by design.\n\n- `f ai claude resume ...` requires a terminal TTY.\n- `f ai codex resume ...` requires a terminal TTY.\n- In non-interactive shells, Flow exits with a clear error and non-zero status.\n- Cursor does not currently expose a Flow resume/continue path; use `list`, `copy`, or `context`.\n\n### Claude exact-ID behavior\n\nIf you pass an explicit session (`name`, `id`, or `id-prefix`), Flow is strict:\n\n- it attempts `claude --resume <id>`\n- if Claude cannot open that exact session, Flow fails\n- Flow does **not** auto-fallback to `--continue` for explicit sessions (prevents opening the wrong conversation)\n\n### Claude no-arg behavior\n\nFor `f ai claude resume` with no argument:\n\n- Flow picks most recent Claude session for this project\n- if that resume fails, Flow may fallback to `claude --continue` in the same cwd (TTY only)\n\n### Codex behavior\n\nFor Codex, Flow runs:\n\n```bash\ncodex resume <id> --dangerously-bypass-approvals-and-sandbox\n```\n\nNo fallback is applied on resume failure; Flow returns non-zero.\n\n### Codex open and resolve\n\nUse `open` when you want one Codex entrypoint that stays conservative about context:\n\n```bash\nf codex open\nf codex open \"continue the deploy work\"\nf codex open \"resume latest\"\nf codex open --path ~/work/example-project \"what was I doing here\"\nf codex resolve \"https://linear.app/example-workspace/project/example-project-v1-1234567890ab/overview\" --json\nf codex doctor --path ~/work/example-project\n```\n\nBehavior:\n\n- no query: start a fresh Codex session in the target repo\n- explicit session lookup queries like `latest`, `resume session`, ordinals, or session IDs: resume the matching Codex session\n- explicit recovery prompts like `what was I doing` or `continue the ... work`: build a compact recovery handoff and start a new session\n- matching reference resolvers: inject only compact resolver output, then append the user request\n- otherwise: start a new session with the raw query and no extra wrapper text\n\nThis keeps prompt cost flat unless Flow has a strong reason to recover or unroll context.\nUse `f codex doctor` to confirm whether wrapper transport, runtime skills, and context budgets are actually active for the current repo.\n\n### Codex connect and find\n\n`f codex connect` and `f ai codex find` now use a Flow-managed local session-search index before\nfalling back to direct SQLite/transcript scans. The index is repo-scoped at query time, rebuilt\nfrom the Codex state DB when needed, and keeps transcript snippets for better recall on natural\nlanguage queries.\n\nBy default, search now prefers sessions from roughly the last 7 days for faster and more accurate\nranking on active work, then automatically widens back to the full session history when the recent\nwindow looks weak or sparse.\n\nUseful commands:\n\n```bash\nf codex connect --path ~/repos/openai/codex --exact-cwd \"app-server\"\nf codex connect --path ~/repos/openai/codex --exact-cwd --json \"thread/read\"\nf codex connect --all-history --path ~/repos/openai/codex \"old migration plan\"\nf ai codex find --path ~/repos/openai/codex \"where does codex store\"\nf ai codex find --recent-days 30 --path ~/repos/openai/codex \"thread/read\"\nf ai codex find --json --limit 5 --path ~/repos/openai/codex \"where does codex store\"\n```\n\nBehavior:\n\n- `connect` stays the interactive handoff path and returns the exact session match\n- `connect --json` prints the selected session instead of attaching\n- `find` still resumes the top hit\n- `find --json` is read-only and prints ranked candidates for inspection/eval work\n- by default both commands prefer the last 7 days first, then widen if the recent window is weak\n- use `--recent-days <N>` to widen the preferred recent window without fully disabling recency bias\n- use `--all-history` to search the full history immediately\n- if confidence is weak or the index misses, Flow still falls back to the older metadata and transcript paths instead of silently opening an arbitrary session\n\n### Codex sessions after a crash or restart\n\nIf your Mac restarts and you lose the live Codex terminals, use:\n\n```bash\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\n```\n\nBehavior:\n\n- lists recent Codex sessions for the current path\n- sorts by the last message timestamp descending\n- shows the stable session id plus a preview of the latest message\n- the numeric index matches `continue`, so you can reopen quickly\n\nIf you want to read or hand off a session instead of reopening it, use the native session bridge in Codex chat:\n\n```text\nsee codex in ~/repos/mark3labs/kit\nsee 019cd046 codex session\nread 019cd046 codex session deeply\n```\n\nExamples:\n\n```bash\nf ai codex continue 1 --path ~/repos/mark3labs/kit\nf ai codex continue 019cd046 --path ~/repos/mark3labs/kit\nf ai codex sessions --path ~/repos/mark3labs/kit --json\n```\n\n### Optional `flow.toml` resolver config\n\nYou can teach `f codex open` and `f codex resolve` to unroll repo-specific references:\n\n```toml\n[codex]\nauto_resolve_references = true\nprompt_context_budget_chars = 900\nmax_resolved_references = 1\nsync_workflow_command = \"./scripts/sync-safe\"\n\n[[codex.reference_resolver]]\nname = \"linear\"\nmatch = [\"https://linear.app/*/issue/*\", \"https://linear.app/*/project/*\"]\ncommand = \"my-linear-tool inspect {{ref}} --json\"\ninject_as = \"linear\"\n```\n\nNotes:\n\n- configure this in repo `flow.toml` or global `~/.config/flow/flow.toml`\n- `{{ref}}`, `{{query}}`, and `{{cwd}}` are available in resolver commands\n- built-in Linear URL parsing works even without a custom resolver\n- resolver output is compacted before prompt injection\n- `prompt_context_budget_chars` hard-caps injected context before your request is appended\n- `max_resolved_references` prevents broad unrolling from bloating one turn\n- `sync_workflow_command` lets plain `sync branch` route into a repo-specific safe sync command instead of improvised Git/JJ steps\n\n### Optional runtime skill transport\n\nFlow can also materialize tiny per-launch runtime skills for current upstream Codex without forking Codex.\n\nEnable it globally with:\n\n```bash\nf codex enable-global --full\nf codex doctor --path ~/docs --assert-runtime --assert-schedule\n```\n\nOr configure it manually with:\n\n```toml\n[codex]\nruntime_skills = true\n\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n```\n\nFor the `~/code/flow` repo specifically, the intended in-repo shape is:\n\n```toml\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n\n[codex]\nruntime_skills = true\nauto_resolve_references = true\nprompt_context_budget_chars = 1200\nmax_resolved_references = 2\n\n[[codex.skill_source]]\nname = \"run-control-plane\"\npath = \"~/run\"\nenabled = true\n```\n\nThat keeps a fresh checkout Codex-first even before machine-local setup is remembered.\n\nCurrent first-slice behavior:\n\n- `f codex open \"write plan\"` can attach a tiny plan-writing runtime skill\n- the runtime skill is exposed only for the launched Codex process\n- Flow keeps the generated runtime state under `~/.config/flow/codex/runtime`\n\nInspect or clear runtime state:\n\n```bash\nf codex runtime show\nf codex runtime clear\nf codex log status\nf codex log sync --limit 400\nf codex memory status\nf codex memory query --path ~/code/flow \"codex control plane runtime skills\"\nf codex memory recent --path ~/docs\nf codex doctor\n```\n\nAssertive health checks:\n\n```bash\nf codex doctor --path ~/docs --assert-runtime\nf codex doctor --path ~/docs --assert-schedule\nf codex doctor --path ~/docs --assert-learning\nf codex doctor --path ~/docs --assert-autonomous\n```\n\n`--assert-learning` is intentionally strict: it fails until Flow has real\nlogged events, grounded outcome samples, and a non-empty scorecard for that\ntarget.\n\nBuilt-in plan writer:\n\n```bash\ncat <<'EOF' | f codex runtime write-plan --title \"Example Plan\"\n# Example Plan\n\n- item\nEOF\n```\n\nBy default this writes to today's `~/docs/plan/<day-of-month>/` bucket, for\nexample `~/docs/plan/23/` on the 23rd day of the month.\n\nCompleted `j` sessions are also mirrored automatically into `~/log/.ai/docs/session-changes/`\nthrough `jd`, so durable home-log notes exist even when a repo-local `.ai/docs/`\npromotion never happens.\n\n### Run-owned agent bridge\n\nFlow can execute run-owned Codex agents directly without copying their specs or\nprompts into `~/code/flow`.\n\nUseful commands:\n\n```bash\nf codex agent list\nf codex agent list --json\nf codex agent show commit\nf codex agent run planner --path ~/code/flow \"make a 3 phase rollout plan\"\nf codex agent run commit --path ~/repos/openai/codex \"review the current diff and draft a safe commit\"\nf codex agent run planner --json --path ~/code/flow \"reply with exactly: ok\"\n```\n\nBehavior:\n\n- Flow bridges into `~/run/scripts/agent-router.sh`\n- the run-owned agent still executes through its own spec/runtime path in `~/run`\n- `--path` controls the repo/worktree cwd used for the agent run\n- `run` returns the agent's final output plus any durable artifact/trace paths\n- `f codex doctor --path <repo>` reports whether the run-agent bridge is ready\n\nRepo-local readiness check:\n\n```bash\nf codex doctor --path ~/code/flow --assert-runtime --assert-schedule\nf codex skill-source list --path ~/code/flow\nf codex agent list\n```\n\n### Skill eval and background refresh\n\nFlow can learn which runtime skills are actually worth injecting from local\nCodex usage history without replaying Codex in the hot path.\n\nUseful commands:\n\n```bash\nf codex eval --path ~/work/example-project\nf codex memory sync --limit 400\nf codex memory recent --path ~/work/example-project --limit 12\nf codex skill-eval show --path ~/work/example-project\nf codex skill-eval run --path ~/work/example-project\nf codex skill-eval cron --limit 400 --max-targets 12 --within-hours 168\nf codex telemetry status\nf codex telemetry flush --limit 200\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\nf codex project-ai show --path ~/work/example-project --json\nf codex project-ai recent --limit 12 --json\nf codex skill-source list --path ~/work/example-project\nf codex skill-source sync --path ~/work/example-project --skill find-skills\nf codex agent list\nf codex agent run planner --path ~/work/example-project \"summarize the next rollout slice\"\n```\n\nThe Codex memory mirror:\n\n- stores durable indexed memory under the Jazz2 root (`~/.jazz2/...` or `~/repos/garden-co/jazz2/.jazz2/...`)\n- mirrors Flow’s route/outcome history into SQLite with WAL enabled\n- extracts compact repo/code facts from repo capsules (summary, commands, important paths, docs hints)\n- adds bounded live code-path retrieval for explicit repo references, so prompts like `see ~/code/flow ...` can inject likely files such as `src/ai.rs` or `docs/...` without dumping raw source\n- indexes durable repo entrypoints and extracted symbols under the same Jazz2-rooted memory store, then supplements them with live symbol extraction from the top-ranked code files during `memory query` / `codex resolve`\n- adds tiny symbol snippets for the top code hits, so coding prompts can carry actual struct/function shape without inlining whole files\n- biases retrieval by intent: implementation/file-edit prompts prefer symbols, snippets, and `src/...` paths; summary/docs prompts prefer doc headings and docs paths\n- stays best-effort so failed memory writes do not block normal Codex coding turns\n\nThe project-ai manifest:\n\n- gives `jd` a bounded metadata view of repo-local `.ai/` scaffolding\n- records counts and latest paths for skills, docs, reviews, tasks, and todos\n- keeps default context fill minimal by exposing only compact hints, not raw content\n- tracks query counts and recent repo usage so you can see whether the feature is actually being used\n- is refreshed again by `f codex skill-eval cron`, so the mirror heals even if a hot-path write is skipped\n- is queried automatically for explicit repo references during `f codex open` / `f codex resolve`\n\nWhat `cron` does:\n\n- scans only recent logged Flow Codex events\n- syncs recent skill-eval logs into the Jazz2-backed memory mirror\n- skips missing/moved repo paths\n- rebuilds scorecards for a bounded number of recent repos\n- never launches Codex or replays network work in the background\n\nFor your use case, this keeps learning cheap and safe enough to run regularly.\n\n### Trace inspection for Flow-managed Codex sessions\n\nFlow now assigns a trace envelope to all Flow-managed Codex launches, not just\nspecial workflows like `check <github-pr-url>`.\n\nThat means sessions started or resumed through:\n\n```bash\nj ...\nk <session-id>\nf codex open ...\nf codex resume ...\nf codex continue ...\n```\n\ncarry `FLOW_TRACE_*` env vars and emit at least one compact Flow telemetry\nevent, so the session becomes remotely inspectable.\n\nUseful commands:\n\n```bash\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\n```\n\nBehavior:\n\n- `trace status` checks whether Maple MCP reads are configured and reachable\n- `trace current-session` reads the active `FLOW_TRACE_ID` from the current\n  Flow-managed Codex session, flushes recent Flow telemetry once, then attempts\n  a remote trace read\n- if Maple reads are partially configured but tenant access is still blocked,\n  Flow returns the current trace metadata plus `readError` instead of failing\n  without context\n\nThis keeps the workflow autonomous from inside Codex itself: once the session\nwas started through Flow, you can inspect the current trace without manually\ncopying ids.\n\n`f codex eval --path ...` is the joined operator report:\n\n- current runtime/doctor state\n- recent route mix and context cost\n- grounded skill scorecard highlights\n- concrete “what to improve next” recommendations\n- commands to deepen or fix the current state\n\nIf `jd` is running, it also keeps recent completion reconciliation warm and\nnow does a bounded background scorecard refresh, so the eval report does not go\nstale as quickly between manual runs.\n\nIf the native session bridge skill is installed, `jd` also prewarms compact\nhandoff capsules for recent native Codex sessions whenever the Codex state DB\nchanges. That keeps the exact handoff path cheap, so pasting\n`019d... codex session` into another chat is usually already a warm cache hit\ninstead of the first lookup having to build the capsule from the rollout.\n\nOptional telemetry export follows the same local-first pattern: Flow keeps\nlocal Codex logs canonical, and if `FLOW_CODEX_MAPLE_*` env vars are set it can\nexport redacted route/context/outcome spans to Maple without shipping raw\nprompts or full repo paths. Use:\n\n```bash\nf codex telemetry status\nf codex telemetry flush --limit 200\n```\n\nFor local-only secrets, prefer `f env set --personal ...`. On macOS you may\nneed `f env unlock` once per day for background reads. Flow-launched Codex\nsessions also inherit the same `FLOW_CODEX_MAPLE_*` values from the personal\nstore, while explicit shell env still wins for one-off tests.\n\nWhen `jd` is running, the daemon also performs a bounded background export\npass so the external analytics view stays warm.\n\n### macOS launchd schedule for skill-eval\n\nIf you want scorecards to stay fresh automatically on macOS:\n\n```bash\nf codex-skill-eval-launchd-install\nf codex-skill-eval-launchd-status\nf codex-skill-eval-launchd-logs\n```\n\n`f codex enable-global --full` installs this schedule for you.\n\nDefault schedule:\n\n- every 30 minutes\n- scan up to 400 recent events\n- rebuild up to 12 recent repo scorecards\n- ignore repos not seen in the last 168 hours\n\nYou can tune install-time bounds:\n\n```bash\nf codex-skill-eval-launchd-install --minutes 20 --limit 600 --max-targets 16 --within-hours 72\nf codex-skill-eval-launchd-install --dry-run\n```\n\nRemove it with:\n\n```bash\nf codex-skill-eval-launchd-uninstall\n```\n\n### Cursor behavior\n\nCursor transcripts are read-only in Flow:\n\n- `f ai cursor list` opens a picker and copies the selected transcript\n- `f ai cursor copy` copies the latest Cursor transcript for this repo\n- `f ai cursor context ...` copies the last N exchanges\n- `f cursor ...` is a shortcut for the same provider-specific read commands\n\n### Cross-directory resume\n\nYou can target another repo without changing directory:\n\n```bash\nf ai codex resume --path ~/work/example-project\nf ai codex resume --path ~/work/example-project 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai codex continue --path ~/work/example-project\n```\n\n- `resume --path <repo>` resolves the requested session against that repo instead of the current cwd\n- `continue --path <repo>` resumes the latest session for that repo\n- explicit full Codex IDs still work directly even when your current cwd is different\n\n## Session Selectors\n\n`resume` accepts:\n\n- saved alias from `.ai/sessions/claude/index.json`\n- full session ID\n- ID prefix (8+ chars)\n- numeric index from list output (1-based)\n\nExamples:\n\n```bash\nf ai resume my-feature\nf ai resume a38cf8bf\nf ai claude resume 2\nf ai codex resume 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai cursor context 382ef1a3 /path/to/repo 2\n```\n\n## Content Copy Commands\n\n```bash\n# Copy full conversation to clipboard\nf ai copy\nf ai copy <session>\n\n# Copy last N prompt/response turns\nf ai context\nf ai context <session> <path> <count>\n```\n\nUse `-` as session placeholder to trigger fuzzy selection:\n\n```bash\nf ai claude context - /path/to/repo 3\nf ai cursor context - /path/to/repo 3\n```\n\n## Project Workflow (Recommended)\n\n1. Start from repo root and inspect tasks:\n   `f tasks list`\n2. Resume exact session when continuing prior work:\n   `f ai claude resume <id>` or `f ai codex resume <id>`\n3. Keep context current:\n   `f skills sync` then `f skills reload`\n4. Validate through tasks:\n   `f test-related` / `f test`\n5. Commit through Flow gates:\n   `f commit`\n\nThis keeps sessions, tasks, skills, and commit quality checks in one loop.\n\n## Everruns Bridge Mode\n\nFlow also supports running a prompt through Everruns while routing client-side\n`seq_*` tool calls to local `seqd`:\n\n```bash\nf ai everruns \"open Safari and take a screenshot\"\n```\n\nKey points:\n\n- This path is additive. It does not replace `f ai claude ...` or `f ai codex ...`.\n- Flow now reuses Seq's canonical Everruns bridge for:\n  - `seq_*` tool definitions injected into new sessions\n  - tool-name normalization (`seq_open_app`, `seq.open_app`, `seq:open-app`)\n  - request correlation IDs (`request_id`, `run_id`, `tool_call_id`)\n- Event transport is SSE-first (`/sse`) with automatic fallback to polling (`/events`) if SSE is unavailable.\n- Optional Maple telemetry export can dual-write runtime traces to local + hosted ingest endpoints when `SEQ_EVERRUNS_MAPLE_*` env vars are configured.\n- Existing Flow features remain unchanged (`f seq-rpc`, session resume/copy/context flows).\n\nSetup and validation details are documented in:\n\n- `docs/everruns-seq-bridge-integration.md`\n- `docs/everruns-maple-runbook.md`\n","isInternal":false,"tokens":5153,"sizeBytes":20895},{"name":"clone.md","path":"docs/commands/clone.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/clone.md","title":"Command: /clone","category":"command-prompt","format":"markdown","content":"# f clone\n\nClone a repository with git-like destination behavior.\n\n## Overview\n\n`f clone` behaves like `git clone` for destination paths:\n\n- `f clone <url>` clones into the current working directory using Git's default folder naming.\n- `f clone <url> <dir>` clones into an explicit destination directory.\n\nFor GitHub inputs, Flow normalizes clone URLs to SSH:\n\n- `https://github.com/owner/repo` -> `git@github.com:owner/repo.git`\n- `owner/repo` -> `git@github.com:owner/repo.git`\n\nThis command does not force clones into `~/repos` and does not auto-configure `upstream`.\n\n## Usage\n\n```bash\nf clone <url-or-owner/repo> [directory]\n```\n\n## Examples\n\n```bash\n# GitHub URL -> SSH clone URL\nf clone https://github.com/genxai/new\n\n# owner/repo shorthand -> SSH clone URL\nf clone genxai/new\n\n# explicit destination folder (same as git clone)\nf clone genxai/new my-local-new\n```\n\n## When To Use\n\n- Use `f clone` when you want standard `git clone` destination behavior.\n- Use [`f repos clone`](repos.md) when you want managed placement under `~/repos/<owner>/<repo>` plus optional upstream automation.\n","isInternal":false,"tokens":276,"sizeBytes":1093},{"name":"commit.md","path":"docs/commands/commit.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/commit.md","title":"Command: /commit","category":"command-prompt","format":"markdown","content":"# f commit\n\nAI-powered commit with deferred Codex review and GitEdit sync.\n\n## Overview\n\nStages all changes, commits quickly by default, runs Codex deep review asynchronously in the background, pushes, and syncs AI sessions to gitedit.dev.\n\n## Quick Start\n\n```bash\n# Default flow: commit now, Codex review runs in background\nf commit\n\n# Blocking pre-commit review (legacy behavior)\nf commit --slow\n\n# Fast commit with custom message (no AI review, no Codex follow-up)\nf commit --fast \"fix typo\"\nf commit --fast  # defaults to \".\" as message\n\n# Queue for review (no push) + create jj review bookmark\nf commit --queue\n\n# Commit without pushing\nf commit -n\n\n# Include AI context in review\nf commit --context\n\n# Custom message\nf commit -m \"Fixes #123\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--no-push` | `-n` | Skip pushing after commit |\n| `--queue` | | Queue the commit for review (no push) |\n| `--no-queue` | | Bypass queue and allow push |\n| `--sync` | | Run synchronously (don't delegate to hub) |\n| `--context` | | Include AI session context in code review |\n| `--dry` | | Dry run: show context without committing |\n| `--quick` | | Explicitly use fast commit + async Codex review (compat alias) |\n| `--slow` | | Run blocking pre-commit review before commit |\n| `--fast [MSG]` | | Fast commit with no AI review (defaults to \".\") |\n| `--codex` | | Use Codex instead of Claude for review |\n| `--review-model <MODEL>` | | Choose specific review model |\n| `--message <MSG>` | `-m` | Custom message appended to commit |\n| `--tokens <N>` | `-t` | Max tokens for AI context (default: 1000) |\n\n## Review Models\n\n| Model | Description |\n|-------|-------------|\n| `claude-opus` | Claude Opus 1 for review (default) |\n| `codex-high` | Codex high-capacity (gpt-5.1-codex-max) |\n| `codex-mini` | Codex mini (gpt-5.1-codex-mini) |\n\n```bash\n# Use Codex\nf commit --codex\n\n# Specific model\nf commit --review-model codex-high\n```\n\n---\n\n## Fast Commit + Deferred Codex Review\n\n`f commit` now uses this mode by default.\n\n### Default (`f commit`) / `--quick` — commit now, Codex reviews later\n\nCommits immediately (generates an AI commit message but skips the blocking code review), then spawns a background Codex review for that commit. The review result is queued and visible via `f commit-queue list`.\n\n```bash\nf commit\nf commit --quick\n```\n\nWhat happens:\n1. Stages all changes, generates commit message, commits, pushes\n2. Queues the commit SHA for async review\n3. Spawns a background Codex process that reviews the diff\n4. You keep working — check results later with `f commit-queue list`\n\n### `--slow` — run blocking review before commit\n\nRuns the pre-commit AI review before creating the commit.\n\n```bash\nf commit --slow\nf commit --slow --review-model codex-high\n```\n\n### `--fast` — instant commit, no review at all\n\nCommits with a provided message (or `\".\"` if omitted). No AI review, no async follow-up. Useful for trivial changes.\n\n```bash\nf commit --fast \"fix typo\"\nf commit --fast              # message defaults to \".\"\n```\n\n### When to use which\n\n| Flag | AI message | Code review | Async review | Best for |\n|------|-----------|-------------|-------------|----------|\n| (none) | Yes | No | Yes (Codex background) | Default fast workflow |\n| `--quick` | Yes | No | Yes (Codex background) | Explicit fast mode |\n| `--slow` | Yes | Yes (blocking) | No | Pre-commit deep check |\n| `--fast` | No (you provide) | No | No | Trivial/WIP commits |\n\n### Opt Out Of Fast Default\n\nIf you want plain `f commit` to run blocking review by default, set:\n\n```toml\n[commit]\nquick-default = false\n```\n\nWith this set, plain `f commit` behaves like `f commit --slow` unless you explicitly pass `--quick`.\n\nRun deep review in batches:\n\n```bash\nf reviews-todo codex --all\nf reviews-todo list\n```\n\n### Myflow Fast + Deep Profile\n\nFor `~/code/myflow`, this profile gives a fast default loop while keeping deep Codex coverage:\n\n```toml\n[commit]\nquick-default = true\nqueue = false\nqueue_on_issues = false\n\n# Fast message generation path via zerg/ai (glm + cerebras), then fallbacks.\nmessage_fallbacks = [\n  \"rise:zai:glm-5\",\n  \"rise:cerebras:gpt-oss-120b\",\n  \"remote\",\n  \"openai\"\n]\n\n# When you explicitly run blocking review, prefer fast models first.\nreview_fallbacks = [\n  \"glm5\",\n  \"rise:cerebras:gpt-oss-120b\",\n  \"codex-high\"\n]\n```\n\nThen operate with:\n\n```bash\nf commit\nf reviews-todo codex --all\n```\n\n---\n\n## What Happens\n\n1. **Safety Checks**\n   - Warns about sensitive files (.env, .pem, keys, credentials)\n   - Warns about files with large diffs (500+ lines)\n   - Runs invariant checks from `[invariants]` when configured\n\n2. **Stage Changes**\n   - Runs `git add -A` to stage all changes\n\n3. **Code Review**\n   - Sends diff to AI for review\n   - Checks for bugs, security issues, best practices\n   - Optionally includes AI session context (`--context`)\n\n4. **Generate Message**\n   - AI generates commit message from diff\n   - Appends custom message if provided (`-m`)\n\n5. **Commit**\n   - Creates commit with generated message\n\n6. **Queue (optional)**\n   - Adds commit to the review queue (`f commit-queue list`)\n   - Creates a jj review bookmark (e.g., `review/main-<sha>`)\n\n7. **Push**\n   - Pushes to remote (unless `--no-push` or `--queue`)\n\n7. **GitEdit Sync**\n   - Syncs AI session data to gitedit.dev\n\n## Invariant Gate\n\nIf your project defines `[invariants]` in `flow.toml`, `f commit` evaluates the staged diff against those rules (forbidden patterns, dependency allowlist policy, file line limits).\n\n- `mode = \"warn\"`: commit continues and findings are shown.\n- `mode = \"block\"`: commit is blocked on warning/critical findings.\n- Findings are injected into the AI review context.\n\n---\n\n## Usage Examples\n\n### Basic Commit\n\n```bash\n# Review, commit, and push\nf commit\n```\n\n### Local Commit Only\n\n```bash\n# Don't push to remote\nf commit -n\n```\n\n### With AI Context\n\nInclude recent AI session context in the review:\n\n```bash\nf commit --context\nf commit --context --tokens 2000  # More context\n```\n\n### Custom Message\n\nAppend additional context to the commit:\n\n```bash\nf commit -m \"Fixes #123\"\nf commit -m \"Co-authored-by: John <john@example.com>\"\n```\n\n### Dry Run\n\nSee what would be reviewed without committing:\n\n```bash\nf commit --dry\n```\n\n### Synchronous Mode\n\nRun directly without delegating to hub:\n\n```bash\nf commit --sync\n```\n\n---\n\n## Safety Warnings\n\n### Sensitive Files\n\nBefore committing, flow warns if staging files that look sensitive:\n\n```\n⚠ Warning: The following sensitive files are staged:\n  - .env\n  - credentials.json\n  - private.key\n```\n\nSensitive patterns include:\n- `.env`, `.env.*`\n- `credentials.json`, `secrets.json`\n- `.pem`, `.key`, `id_rsa`, `id_ed25519`\n- Files containing `password`, `secret`, `token`\n\n### Secret Scan (Staged Diff)\n\nFlow scans staged diffs for likely secrets (API keys, tokens, passwords). If a match\nis detected, the commit is blocked. In an interactive terminal, flow offers to run\nan auto-fix using `ai` to mask or replace the values, then asks for approval to\ncontinue.\n\nYou can bypass the check for a single commit with:\n\n```\nFLOW_ALLOW_SECRET_COMMIT=1 f commit\n```\n\n### Large Diffs\n\nWarns about files with significant changes:\n\n```\n⚠ Warning: The following files have large diffs:\n  - src/generated.rs (1523 lines)\n  - data/fixtures.json (834 lines)\n```\n\nThreshold: 500+ lines added/removed.\n\n---\n\n## Related Commands\n\n| Command | Description |\n|---------|-------------|\n| `f commit` | Fast commit + deferred Codex review (default) |\n| `f commitWithCheck` | Review without GitEdit sync |\n| `f commitSimple` | No review, just AI commit message |\n\n### commitWithCheck (alias: cc)\n\nSame as `commit` but skips GitEdit sync:\n\n```bash\nf commitWithCheck\nf cc  # Short alias\n```\n\n### commitSimple\n\nQuick commit without code review:\n\n```bash\nf commitSimple\n```\n\n---\n\n## Configuration\n\n### Hub Delegation\n\nBy default, `f commit` delegates to the hub daemon for async processing. Use `--sync` for direct execution:\n\n```bash\n# Async via hub (default)\nf commit\n\n# Sync (direct)\nf commit --sync\n```\n\n### Commit Message Tool\n\nOptionally force a specific commit-message generator:\n\n```toml\n[commit]\nmessage_tool = \"kimi\" # also supports: claude, rise, glm5, opencode, openrouter, remote, openai\nmessage_model = \"kimi-k2-thinking-turbo\" # optional, tool-specific\n```\n\nIf the forced tool fails, `f commit` now falls back through the configured/default chain.\n\n### Review Tool (Kimi CLI)\n\nUse Kimi Code CLI for code review:\n\n```toml\n[review]\ntool = \"kimi\"\nmodel = \"kimi-k2-thinking-turbo\" # optional; uses Kimi default if omitted\n```\n\nThis uses `kimi --quiet` (print mode) with your existing Kimi CLI auth/config.\n\n### Robust Fallbacks\n\n`f commit` now uses multi-attempt fallback chains for both review and commit-message generation.\n\nDefault behavior:\n- Review: primary selection, then `openrouter`, `claude`, `codex-high`\n- Message: review-aligned/override tool, then `remote` (myflow), `openai`, `openrouter`\n- If all message attempts fail and fail-open is enabled, Flow uses a deterministic local fallback message.\n\nConfiguration:\n\n```toml\n[commit]\nreview_fail_open = true\nmessage_fail_open = true\nreview_fallbacks = [\"openrouter\", \"claude\", \"codex-high\"]\nmessage_fallbacks = [\"remote\", \"openai\", \"openrouter\"]\n```\n\nEnvironment overrides:\n- `FLOW_COMMIT_REVIEW_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_MESSAGE_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_REVIEW_FALLBACKS=\"openrouter,claude,codex-high\"`\n- `FLOW_COMMIT_MESSAGE_FALLBACKS=\"remote,openai,openrouter\"`\n\nCodex -> GLM5 fallback example:\n\n```toml\n[commit]\nreview_fallbacks = [\"glm5\", \"openrouter\", \"claude\"]\nmessage_fallbacks = [\"glm5\", \"remote\", \"openai\"]\n```\n\n`glm5` maps to the Rise/internal route with model `zai:glm-5`.\n\n### Queue Policy\n\nQueue only when review finds issues (auto-push on a clean review):\n\n```toml\n[commit]\nqueue = true\nqueue_on_issues = true\n```\n\n`--queue` / `--no-queue` still override this behavior.\n\n### Commit Quality Gates (Testing + Required Skills)\n\nUse local gates to block commits that skip tests or required workflow skills:\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\nWhen `mode = \"block\"`, `f commit` fails until the test/skill requirements are satisfied.  \nFor Bun repos, run checks with `bun bd test ...` for debug-build validation. If no related tracked tests are found, Flow can run tests under `ai_scratch_test_dir` (default `.ai/test`) as a fallback signal.\n\n### AI Session Context\n\nWhen `--context` is enabled, includes recent Claude Code session context:\n\n```bash\n# Default: 1000 tokens of context\nf commit --context\n\n# More context\nf commit --context --tokens 3000\n```\n\n---\n\n## Examples\n\n### Quick Bug Fix\n\n```bash\n# Fix bug, commit with context\nvim src/lib.rs\nf commit --context -m \"Fixes null pointer in edge case\"\n```\n\n### Feature Branch\n\n```bash\n# Work on feature\ngit checkout -b feature/new-api\n# ... make changes ...\n\n# Commit without push\nf commit -n\n\n# More changes...\nf commit -n\n\n# Final push\ngit push -u origin feature/new-api\n```\n\n### Review Before Commit\n\n```bash\n# See what would be reviewed\nf commit --dry\n\n# If satisfied, commit\nf commit\n```\n\n---\n\n## Troubleshooting\n\n### \"Sensitive files staged\"\n\nEither:\n1. Add files to `.gitignore`\n2. Unstage with `git reset HEAD <file>`\n3. Proceed anyway if intentional\n\n### Review taking too long\n\nUse `--sync` to see progress directly:\n```bash\nf commit --sync\n```\n\n### Hub not responding\n\nFall back to sync mode:\n```bash\nf commit --sync\n```\n\n## See Also\n\n- [upstream](upstream.md) - Sync forks before committing\n- [publish](publish.md) - Publish after committing\n","isInternal":false,"tokens":3147,"sizeBytes":11918},{"name":"commits.md","path":"docs/commands/commits.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/commits.md","title":"Command: /commits","category":"command-prompt","format":"markdown","content":"# f commits\n\nBrowse commits with AI metadata and mark notable commits for quick access.\n\n## Usage\n\n```bash\nf commits\nf commits --limit 200\nf commits --all\nf commits top\nf commits mark <hash>\nf commits unmark <hash>\n```\n\n## Notable commits\n\nNotable commits are stored in `.ai/internal/commits/top.txt` in the repo root. Each line is:\n\n```\n<full-hash>\\t<label>\n```\n\n## Key bindings\n\nWhen using fzf:\n\n- `ctrl-t` — toggle notable for the selected commit.\n","isInternal":false,"tokens":119,"sizeBytes":453},{"name":"config.md","path":"docs/commands/config.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/config.md","title":"Command: /config","category":"command-prompt","format":"markdown","content":"# f config\n\nCompile the personal Flow root config and generated compatibility outputs.\n\nSource of truth:\n\n- `~/.flow/config.ts`\n\nGenerated outputs:\n\n- `~/.config/flow/generated/config.snapshot.json`\n- `~/.config/flow/generated/flow/config.ts`\n- `~/.config/flow/generated/lin/config.ts`\n- `~/.config/flow/generated/lin/intents.json`\n- `~/.config/flow/generated/lin/mac.toml`\n- `~/.config/flow/generated/ai/config.json`\n\nHive config may still appear in the effective root config during migration, but Flow no longer emits or applies `~/.hive/config.json`.\n\nIf `~/.flow/config.ts` does not exist yet, Flow currently falls back to:\n\n- `~/config/i/lin/config.ts`\n\nand generates a starter `~/.flow/config.ts` migration file on apply.\n\n## Commands\n\n### f config doctor\n\nShows whether the root config exists, whether a TypeScript runner is available,\nwhether a generated snapshot already exists, and what extension directories are discoverable.\n\n```bash\nf config doctor\nf config doctor --json\n```\n\n### f config build\n\nLoads the root config plus named extensions, computes the merged effective config,\nand writes generated artifacts under `~/.config/flow/generated/`.\n\nThis does not overwrite consumer config locations.\n\n```bash\nf config build\nf config build --json\n```\n\n### f config apply\n\nBuilds the snapshot and then applies the generated compatibility files into their\nconsumer locations. This is the cutover step that keeps existing tools working while\nmoving authoring into `~/.flow/config.ts`.\n\n```bash\nf config apply\nf config apply --json\n```\n\n### f config eval\n\nPrints the currently effective merged config view. If no snapshot exists yet, Flow\nbuilds one first.\n\n```bash\nf config eval\nf config eval --json\n```\n\n## Root Config Shape\n\nThe first supported root-config shape is:\n\n```ts\nexport default {\n  flow: { ... },\n  lin: { ... },\n  ai: { ... },\n  hive: { ... }, // parsed for migration compatibility, not applied to ~/.hive\n  zerg: { ... },\n  extensions: [\"lin-compat\"],\n}\n```\n\nFilesystem extensions can live under:\n\n- `~/.flow/extensions/<name>/extension.ts`\n- `~/.flow/extensions/<name>/config.ts`\n\nEach extension can contribute partial config fragments plus optional generated files.\n\n## Notes\n\n- Flow currently ships one built-in extension name: `lin-compat`\n- explicit extensions must exist or `f config build` fails\n- generated outputs are written atomically\n- if a `hive` section is present, `f config build/apply/eval` warns that Hive output is deprecated and ignored\n","isInternal":false,"tokens":577,"sizeBytes":2479},{"name":"db.md","path":"docs/commands/db.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/db.md","title":"Command: /db","category":"command-prompt","format":"markdown","content":"# db\n\nManage database workflows and backends (Jazz + Postgres).\n\n## Usage\n\n```bash\nf db <provider> <action>\n```\n\n## Jazz\n\nCreate Jazz2 app credentials and populate env vars for the current project.\n\n```bash\nf db jazz new --kind mirror --name gitedit-mirror\n```\n\nResolution order for the credential bootstrap helper:\n\n1. Local `jazz-tools` binary on `PATH`\n2. Pinned `npx --yes jazz-tools@0.20.14`\n\nFor deliberate experiments, override the pinned fallback with:\n\n```bash\nFLOW_JAZZ_TOOLS_PACKAGE_SPEC=jazz-tools@<version> f db jazz new --kind mirror\n```\n\n## Postgres\n\nRun Drizzle migrations for the default Postgres project (`~/org/la/la/server`).\n\n```bash\nf db postgres migrate\nf db postgres migrate --generate\nf db postgres generate\n```\n\nEnvironment resolution order for `DATABASE_URL`:\n\n1. `--database-url` flag\n2. `DATABASE_URL`\n3. `PLANETSCALE_DATABASE_URL` / `PSCALE_DATABASE_URL`\n4. `<project>/.env` (DATABASE_URL)\n\nUse `--project` to override the Postgres project directory.\n","isInternal":false,"tokens":257,"sizeBytes":981},{"name":"deploy.md","path":"docs/commands/deploy.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/deploy.md","title":"Command: /deploy","category":"command-prompt","format":"markdown","content":"# f deploy\n\nDeploy projects to hosts and cloud platforms.\n\n## Overview\n\nThe `deploy` command handles deployment to multiple platforms:\n- **Linux hosts** via SSH (with systemd + nginx)\n- **Cloudflare Workers**\n- **Railway**\n\nAuto-detects the platform from your `flow.toml` configuration.\nIf `[flow].deploy_task` is set, `f deploy` runs that task first.\nIf no deployment config exists but a `deploy` task is defined, `f deploy` runs that task.\nUse `f prod` to deploy directly from `[host]`, `[cloudflare]`, `[railway]`, or `[web]` (it skips `[flow].deploy_task`).\n\n## Quick Start\n\n```bash\n# Auto-deploy based on flow.toml config\nf deploy\n\n# Production deploy (skips flow.deploy_task, uses deploy config or deploy-prod task)\nf prod\n\n# Run the project's release task (flow.release_task or fallback)\nf deploy release\n\n# Deploy to specific platform\nf deploy host\nf deploy cloudflare\nf deploy railway\n\n# Production deploy to specific platform\nf prod host\nf prod cloudflare\n\n# Configure deployment defaults\nf deploy config\n\n# Deploy web site\nf deploy web\n```\n\n## Subcommands\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `host` | `h` | Deploy to Linux host via SSH |\n| `cloudflare` | `cf` | Deploy to Cloudflare Workers |\n| `web` | | Deploy the web site (Cloudflare) |\n| `setup` | | Interactive deploy setup (Cloudflare) |\n| `railway` | | Deploy to Railway |\n| `config` | | Configure deployment defaults (Linux host) |\n| `release` | | Run the project's release task |\n| `status` | | Show deployment status |\n| `logs` | | View deployment logs |\n| `restart` | | Restart the deployed service |\n| `stop` | | Stop the deployed service |\n| `shell` | | SSH into the host |\n| `set-host` | `set` | Configure host for deployment |\n| `show-host` | | Show current host configuration |\n| `health` | | Check if deployment is healthy |\n\n---\n\n## Web Deployment\n\nDeploys the web site using Cloudflare and your project tasks. Flow will:\n- Ensure `[web]` exists in `flow.toml` (auto-fills `path` when possible).\n- Add the `web.route` (or `web.domain/*`) to your wrangler config.\n- Optionally create/update the Cloudflare DNS record for the domain/route.\n- Apply env vars from cloud if `web.env_source = \"cloud\"` is set.\n- Run `deploy-web` (or `deploy` as fallback).\n\n```bash\nf deploy web\n```\n\nIf the Cloudflare API token is missing, Flow will guide you to create one and\nstore it in your env store as `CLOUDFLARE_API_TOKEN`.\n\nIf `web.domain`/`web.route` or `web.path` is missing, Flow will prompt for them\nand update `flow.toml`.\n\nIf you opt into DNS management, Flow will prompt for record type/target and\ncreate or update the Cloudflare DNS record (default: `A` to `192.0.2.1`,\nproxied).\n\nIf cloud is unavailable, Flow can store envs locally when you choose\n`web.env_source = \"local\"`.\n\nExample `flow.toml`:\n\n```toml\n[web]\npath = \"packages/web\"\ndomain = \"example.com\"\nenv_source = \"cloud\"\nenv_apply = \"always\"\nenv_keys = [\"PUBLIC_API_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\n## Host Deployment (Linux via SSH)\n\nDeploy to any Linux server with SSH access. Flow handles:\n- File syncing via rsync\n- Systemd service creation\n- Nginx reverse proxy setup\n- SSL via Let's Encrypt\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[flow]\ndeploy_task = \"deploy-cli-release\"\n\n[host]\ndest = \"/opt/myapp\"           # Remote destination path\nrun = \"./server\"              # Command to run the service\nport = 3000                   # Port the service listens on\nservice = \"myapp\"             # Systemd service name (optional, defaults to folder name)\nsetup = \"./scripts/setup.sh\"  # Setup script to run after first sync (optional)\nenv_file = \".env.production\"  # Path to .env file for secrets (optional)\nenv_source = \"flow\"           # Pull envs from Flow env store (optional)\nenv_keys = [\"API_KEY\"]        # Keys to fetch when env_source=flow/cloud (optional)\ndomain = \"myapp.example.com\"  # Public domain for nginx (optional)\nssl = true                    # Enable SSL via Let's Encrypt (optional)\n```\n\nTip: `f setup deploy` can scaffold the `[host]` section and create a remote setup script.\n\n### Setup Host\n\nFirst, configure your SSH connection:\n\n```bash\n# Set host (stored globally at ~/.config/flow/deploy.json)\nf deploy set-host user@host:port\nf deploy set-host deploy@myserver.com:22\nf deploy set-host root@192.168.1.100\n\n# Interactive config (prefills from ~/.config/infra/config.json if present)\nf deploy config\n\n# Verify connection\nf deploy shell\n```\n\n### Deploy\n\n```bash\n# Deploy to host\nf deploy host\n\n# Force re-run setup script\nf deploy host --setup\n\n# Build remotely instead of syncing local artifacts\nf deploy host --remote-build\n```\n\n### What Happens\n\n1. **Sync files** - rsync uploads project (excludes `target/`, `.git/`, `node_modules/`, `.env`, `*.log`)\n2. **Copy env file** - If `env_file` is specified, copies it to `{dest}/.env`\n   (or, if `env_source = \"flow\"`, fetches from Flow env store and writes `{dest}/.env`)\n3. **Run setup** - Executes setup script on first deploy or with `--setup`\n4. **Create systemd service** - Generates and enables `/etc/systemd/system/{service}.service`\n5. **Configure nginx** - If `domain` is set, creates reverse proxy config\n6. **Setup SSL** - If `ssl = true`, runs certbot for Let's Encrypt certificate\n7. **Start service** - Runs `systemctl restart {service}`\n\n### Manage Service\n\n```bash\n# View logs\nf deploy logs                 # Since last deploy (host only)\nf deploy logs -f              # Follow in real-time (since last deploy)\nf deploy logs --all           # Full history (ignore deploy marker)\nf deploy logs --all -n 500    # Show last 500 lines without deploy filter\n\n# Restart/stop\nf deploy restart\nf deploy stop\n\n# Check status\nf deploy status\n\n# SSH into server\nf deploy shell\n\n# Health check\nf deploy health\nf deploy health --url https://myapp.example.com/health\nf deploy health --status 204  # Expect specific status code\n```\n\nNote: For host deploys, Flow records the last successful deploy time in `.flow/deploy-log.json` and uses it to scope `f deploy logs` output. Use `--all` to ignore it.\n\n---\n\n## Cloudflare Workers\n\nDeploy to Cloudflare's edge network.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[cloudflare]\npath = \"worker\"                    # Path to worker directory (optional, defaults to project root)\nenvironment = \"production\"         # Wrangler environment name (optional)\nenv_file = \".env.cloudflare\"       # Path to .env file for secrets (optional)\nenv_source = \"cloud\"              # Use cloud or local env store for secrets (optional)\nenv_keys = [\"API_KEY\", \"SECRET\"]   # Specific keys to fetch from env store (optional)\nenv_vars = [\"PUBLIC_URL\"]          # Keys to set as non-secret vars (optional)\ndeploy = \"wrangler deploy\"         # Custom deploy command (optional)\ndev = \"wrangler dev\"               # Custom dev command (optional)\nurl = \"https://my-worker.workers.dev\"  # URL for health checks (optional)\n```\n\n### Prerequisites\n\n- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) installed\n- `wrangler.toml` in your worker directory\n- Authenticated with `wrangler login`\n\n### Deploy\n\n```bash\n# Deploy\nf deploy cloudflare\n\n# Deploy with secrets from env_file\nf deploy cloudflare --secrets\n\n# Run in dev mode\nf deploy cloudflare --dev\n```\n\n### Production domain (for `f prod`)\n\nUse `[prod]` to set a production domain or route for Workers. `f prod` will add\nthe route to your `wrangler.json/jsonc` before deploying.\n\n```toml\n[prod]\ndomain = \"anysynth.nikiv.com\"   # Will be mapped to route \"anysynth.nikiv.com/*\"\n# route = \"anysynth.nikiv.com/*\"  # Use this for explicit patterns\n```\n\n### Interactive Setup\n\nFor first-time setup, use the interactive wizard:\n\n```bash\nf deploy setup\n```\n\nThis walks you through:\n1. Selecting worker directory (auto-discovers `wrangler.toml`)\n2. Choosing .env file for secrets\n3. Selecting Cloudflare environment (production, staging, etc.)\n4. Picking which secrets to push\n5. Updating `flow.toml` with your choices\n\nIf your `flow.toml` lists service keys (for example Stripe keys), the setup flow\nwill offer to run the matching service onboarding before applying envs.\n\n### Secrets from cloud\n\nIf using cloud for secret management:\n\n```toml\n[cloudflare]\nenv_source = \"cloud\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"]  # Fetched as secrets\nenv_vars = [\"PUBLIC_API_URL\"]                      # Fetched as non-secret vars\nenvironment = \"production\"\n```\n\nThen deploy:\n\n```bash\nf deploy cloudflare --secrets\n```\n\nIf you want to use local Flow envs instead:\n\n```toml\n[cloudflare]\nenv_source = \"local\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\nIf you need to fill missing values first:\n\n```bash\nf env guide\n```\n\n---\n\n## Railway\n\nDeploy to Railway's platform.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[railway]\nproject = \"my-project\"         # Railway project ID\nservice = \"api\"                # Service name (optional)\nenvironment = \"production\"     # Environment name (optional)\nstart = \"npm start\"            # Start command (optional)\nenv_file = \".env.railway\"      # Path to .env file (optional)\n```\n\n### Prerequisites\n\n- [Railway CLI](https://docs.railway.app/develop/cli) installed (`npm install -g @railway/cli`)\n- Authenticated with `railway login`\n\n### Deploy\n\n```bash\nf deploy railway\n```\n\nWhat happens:\n1. Links to Railway project if specified\n2. Sets environment variables from `env_file`\n3. Deploys with `railway up --detach`\n\n---\n\n## Health Checks\n\nCheck if your deployment is responding:\n\n```bash\n# Use domain from [host] or url from [cloudflare] config\nf deploy health\n\n# Custom URL\nf deploy health --url https://api.example.com/health\n\n# Expect specific status code\nf deploy health --status 204\n```\n\nReturns:\n- `Healthy (HTTP 200 in 0.15s)` on success\n- `Unhealthy: expected HTTP 200, got 500` on wrong status\n- `Unreachable: Connection refused` on network error\n\n---\n\n## Global Host Configuration\n\nHost connection is stored globally at `~/.config/flow/deploy.json`:\n\n```json\n{\n  \"host\": {\n    \"user\": \"deploy\",\n    \"host\": \"myserver.com\",\n    \"port\": 22\n  }\n}\n```\n\nView/set:\n\n```bash\nf deploy show-host\nf deploy set-host deploy@newserver.com:2222\n```\n\n---\n\n## Examples\n\n### Full Host Setup\n\n```toml\n# flow.toml\n[host]\ndest = \"/opt/api\"\nrun = \"/opt/api/server\"\nport = 8080\nservice = \"myapi\"\nsetup = \"cargo build --release && cp target/release/server /opt/api/\"\nenv_file = \".env.production\"\ndomain = \"api.mycompany.com\"\nssl = true\n```\n\n```bash\n# First time setup\nf deploy set-host root@myserver.com\n\n# Deploy\nf deploy host\n\n# Check it's working\nf deploy health\nf deploy logs -f\n```\n\n### Full Cloudflare Setup\n\n```toml\n# flow.toml\n[cloudflare]\npath = \"packages/worker\"\nenvironment = \"production\"\nenv_source = \"cloud\"\nenv_keys = [\"OPENAI_API_KEY\", \"WEBHOOK_SECRET\"]\nurl = \"https://my-worker.mycompany.workers.dev\"\n```\n\n```bash\n# Store project secrets\nf env project set -e production OPENAI_API_KEY=sk-...\nf env project set -e production WEBHOOK_SECRET=whsec_...\n\n# Deploy with secrets\nf deploy cloudflare --secrets\n\n# Verify\nf deploy health\n```\n\n### CI/CD Integration\n\n```yaml\n# GitHub Actions\ndeploy:\n  runs-on: ubuntu-latest\n  steps:\n    - uses: actions/checkout@v4\n    - name: Deploy\n      run: |\n        f deploy set-host ${{ secrets.DEPLOY_HOST }}\n        f deploy host\n        f deploy health\n```\n\n---\n\n## Troubleshooting\n\n### \"No host configured\"\n\nRun `f deploy set-host user@host:port` first.\n\n### \"No wrangler config found\"\n\nEnsure `wrangler.toml` exists in your worker directory, or run `wrangler init`.\n\n### SSH connection fails\n\nTest with `f deploy shell` to debug. Check:\n- SSH key is in `~/.ssh/` and added to server\n- Port is correct (default: 22)\n- Server is reachable\n\n### Secrets not updating\n\nFor Cloudflare, use `--secrets` flag: `f deploy cloudflare --secrets`\n\n### Health check fails\n\nCheck URL is correct and service is running:\n```bash\nf deploy logs -f  # Check for errors\ncurl -v https://your-domain.com  # Test manually\n```\n","isInternal":false,"tokens":3109,"sizeBytes":11957},{"name":"docs.md","path":"docs/commands/docs.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/docs.md","title":"Command: /docs","category":"command-prompt","format":"markdown","content":"# f docs\n\nManage documentation for a project. There are two doc systems:\n\n- `.ai/docs` for AI-maintained internal docs.\n- `docs/` for human-facing docs rendered by the docs hub.\n\n## Quick Start\n\n```bash\n# Create docs/ with starter files\nf docs new\n\n# Open docs for the current project (auto-starts the hub)\nf docs\n\n# Deploy the current project's docs to Cloudflare Pages\nf docs deploy\n```\n\n## Commands\n\n### f docs new\n\nCreates a `docs/` folder in the current project using the template in `~/new/docs`.\nIf `docs/` already exists, it merges in any missing template files and leaves\nexisting content untouched.\n\nOptions:\n\n- `--path <PATH>`: Target directory (defaults to current folder).\n- `--force`: Overwrite if `docs/` already exists.\n\n### f docs hub\n\nRuns a single dev server that aggregates docs from `~/code` and `~/org`.\nUse `FLOW_DOCS_FOCUS=1` to only index the current project for faster startup.\n\nOptions:\n\n- `--host <HOST>` (default: `127.0.0.1`)\n- `--port <PORT>` (default: `4410`)\n- `--hub-root <PATH>` (default: `~/.config/flow/docs-hub`)\n- `--template-root <PATH>` (default: `~/new/docs`)\n- `--code-root <PATH>` (default: `~/code`)\n- `--org-root <PATH>` (default: `~/org`)\n- `--no-ai`: Skip `.ai/docs`.\n- `--no-open`: Do not open the browser.\n- `--sync-only`: Sync docs content and exit.\n\n### f docs deploy\n\nDeploys the current project's docs to Cloudflare Pages (uses the docs hub template).\n\nOptions:\n\n- `--project <NAME>`: Pages project name (defaults to the flow.toml name).\n- `--domain <DOMAIN>`: Attach a custom domain (optional).\n- `--yes`: Skip confirmation prompts.\n\n### f docs sync\n\nSyncs `.ai/docs` metadata based on recent commits. Intended for AI doc upkeep.\n\n### f docs list\n\nLists `.ai/docs` files for the current project.\n\n### f docs status\n\nShows recent commits and `.ai/docs` file modification times.\n\nIt now also shows:\n\n- recent Flow-managed Codex session packets stored under Flow state for the current project\n- doc-review queue state counts for the current project\n\n### f docs review-pending\n\nRuns the bounded daemon-style review pass over pending session-doc packets stored in\nFlow state and records promotion decisions into queue state plus each packet's\n`promotion.json`.\n\nOptions:\n\n- `-n, --limit <N>`: Maximum number of pending entries to review (default: `25`).\n\n### f docs promote-session\n\nPreviews or applies promotion for a daemon-captured session-doc packet.\n\nBy default this is a dry run. It prints the chosen target under `.ai/docs/` and the\npromoted markdown note. Raw packet bundles stay in Flow state; only promoted\ndurable notes are written into the repo.\n\nOptions:\n\n- `<SESSION>`: Session id, session id prefix, or session key like `019d035d-...` or `019d035d-1773776290`\n- `--apply`: Write the promoted note immediately\n\n### f docs commit-pending\n\nCommits promoted session-doc notes when the git diff is isolated to doc-only files.\n\nThis command refuses to commit if the worktree contains unrelated changes.\n\nOptions:\n\n- `--dry-run`: Show the candidate files and commit message without staging or committing\n\n### f docs edit\n\nOpens a `.ai/docs` file in `$EDITOR`.\n\nExample:\n\n```bash\nf docs edit architecture\n```\n","isInternal":false,"tokens":788,"sizeBytes":3166},{"name":"domains.md","path":"docs/commands/domains.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/domains.md","title":"Command: /domains","category":"command-prompt","format":"markdown","content":"# `f domains`\n\nManage shared local `*.localhost` routing with a single proxy on port `80`.\n\n## Why\n\nWithout this, each repo can start its own proxy and race for port `80`.\n`f domains` centralizes ownership with one engine at a time.\n\nState lives in:\n\n- `~/.config/flow/local-domains/routes.json`\n- runtime artifacts under `~/.config/flow/local-domains/`\n\n## Engines\n\n- `docker` (default): shared nginx container (`flow-local-domains-proxy`)\n- `native` (experimental): local C++ daemon (`domainsd-cpp`)\n\nSelect engine per command:\n\n```bash\nf domains --engine docker up\nf domains --engine native up\n```\n\nOr via env:\n\n```bash\nexport FLOW_DOMAINS_ENGINE=native\n```\n\n## Commands\n\n```bash\nf domains list\nf domains add linsa.localhost 127.0.0.1:3481\nf domains rm linsa.localhost\nf domains up\nf domains down\nf domains doctor\nf domains --engine native up\nf domains --engine native down\nf domains --engine native doctor\n```\n\n## Behavior\n\n- `f domains up`\n  - starts shared proxy on `:80`\n  - fails fast if another process/container owns port `80`\n- `f domains add`\n  - validates `host` ends with `.localhost`\n  - validates target format `host:port`\n  - refuses overwrite unless `--replace`\n  - reloads proxy if already running\n- `f domains doctor`\n  - shows route count\n  - shows current owner of port `80`\n  - highlights conflict ownership\n\n## Native notes (experimental)\n\n- Requires `clang++` to build `tools/domainsd-cpp/domainsd.cpp`.\n- Current scope is HTTP/1.1 host routing with WebSocket upgrade passthrough and upstream keepalive pooling.\n- Native daemon has built-in overload shedding (`503`) and upstream timeout protection (`504` on connect timeout).\n- HTTP/2/TLS are not implemented yet.\n- See `docs/local-domains-domainsd-cpp-spec.md`.\n- myflow-specific setup: `docs/myflow-localhost-runbook.md`.\n- Lifecycle integration: configure `[lifecycle.domains]` and use `f up` / `f down`.\n\n### macOS no-docker bind to :80\n\nIf native startup fails with `Permission denied` on `127.0.0.1:80`, install launchd socket mode once:\n\n```bash\ncd ~/code/flow\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nThen run:\n\n```bash\nf domains --engine native up\n```\n\nThis keeps routing fully native and avoids Docker overhead while still using port `80`.\n\n### Native tuning envs\n\nYou can tune the native daemon at startup via environment variables:\n\n```bash\nFLOW_DOMAINS_NATIVE_MAX_ACTIVE_CLIENTS=128\nFLOW_DOMAINS_NATIVE_UPSTREAM_CONNECT_TIMEOUT_MS=10000\nFLOW_DOMAINS_NATIVE_UPSTREAM_IO_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_CLIENT_IO_TIMEOUT_MS=30000\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_PER_KEY=8\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_TOTAL=256\nFLOW_DOMAINS_NATIVE_POOL_IDLE_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_POOL_MAX_AGE_MS=120000\n```\n## Recommended Repo Pattern\n\nInstead of per-repo docker proxy tasks:\n\n```toml\n[[tasks]]\nname = \"domains-up\"\ncommand = \"f domains add myapp.localhost 127.0.0.1:3000 && f domains up\"\n```\n\nThis keeps one proxy process for all repos and avoids accidental domain hijacking.\n","isInternal":false,"tokens":767,"sizeBytes":2988},{"name":"down.md","path":"docs/commands/down.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/down.md","title":"Command: /down","category":"command-prompt","format":"markdown","content":"# f down\n\nBring a project down using lifecycle conventions.\n\n## Quick Start\n\n```bash\n# Run lifecycle down task and optional domains teardown\nf down\n```\n\n## Behavior\n\n- Loads nearest `flow.toml` (or `--config` path).\n- Runs lifecycle task:\n  - `[lifecycle].down_task` when configured\n  - otherwise fallback: `down`\n- If no down task is found and `down_task` is not explicitly set, Flow falls back to killing all running Flow-managed processes for the current project (`f kill --all` behavior).\n- If `[lifecycle.domains]` is configured, optional teardown is applied:\n  - `remove_on_down = true` -> removes configured host route\n  - `stop_proxy_on_down = true` -> stops shared local domains proxy\n- On macOS launchd-managed native domains, stopping native proxy is handled by:\n  - `sudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh`\n\nIf neither a down task nor lifecycle domain teardown is configured, command fails with guidance.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`, searches upward when default is missing) |\n| `ARGS...` | Extra args passed to the selected lifecycle task |\n","isInternal":false,"tokens":280,"sizeBytes":1169},{"name":"env.md","path":"docs/commands/env.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/env.md","title":"Command: /env","category":"command-prompt","format":"markdown","content":"# f env\n\nSync project environment and manage environment variables.\n\n## Overview\n\nManage environment variables via cloud or local storage. Supports:\n- Project-level environment variables\n- Personal/global variables\n- Multiple environments (dev, staging, production)\n- Direct injection into commands\n- Touch ID gating for cloud reads and keychain-backed personal local reads on macOS\n- Client-side sealed project env sharing in the cloud\n\n## Storage Backends\n\n| Backend | Location | Config |\n|---------|----------|--------|\n| `cloud` | Cloud (myflow.sh) | Default, requires login |\n| `local` | `~/.config/flow/env-local/` | No account needed |\n\nCloud behavior:\n- Personal cloud envs use Flow's existing server-managed secret storage.\n- Project cloud envs are sealed client-side before upload and decrypted locally on read.\n- If a host deploy is configured with `env_source = \"cloud\"` plus a `service_token`, Flow keeps a compatibility plaintext mirror for those project keys until the host fetch path is upgraded.\n\nForce local backend:\n\n```bash\n# Via environment variable\nexport FLOW_ENV_BACKEND=local\n\n# Or in ~/.config/flow/config.ts\nexport default {\n  flow: { env: { backend: \"local\" } }\n}\n```\n\nIf the current project has an unambiguous deploy env source such as:\n\n```toml\n[host]\nenv_source = \"local\"\n```\n\nthen `f env` will also use the local backend automatically in that project.\n\n### Local Storage Structure\n\n```\n~/.config/flow/env-local/\n├── <project-name>/\n│   ├── production.env\n│   ├── staging.env\n│   └── dev.env\n└── personal/\n    └── production.env\n```\n\nStorage behavior:\n- Project-local envs are private `.env` files under `~/.config/flow/env-local/`.\n- On macOS, personal-local env values are stored in Keychain by default; `personal/production.env` keeps Flow-managed references, not raw secret values.\n- If `FLOW_ENV_LOCAL_PLAINTEXT=1` is set, Flow falls back to plaintext personal local storage.\n- Local env paths are written with owner-only permissions.\n\n## Quick Start\n\n```bash\n# Store a personal secret\nf env set API_KEY=sk-xxx\n\n# List variables (default action when logged in)\nf env\n\n# Run command with env vars injected\nf env run -- npm start\n\n# Get a value\nf env get API_KEY -f value\n```\n\n## Linsa/TestFlight Example\n\nFor project-scoped keys used by local + ship flows (for example, assistant keys):\n\n```bash\n# Store in project space (recommended for app/server env)\nf env project set -e dev OPENROUTER_API_KEY=sk-...\nf env project set -e production OPENROUTER_API_KEY=sk-...\nf env project set -e dev OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\nf env project set -e production OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\n```\n\nNotes:\n- Do not commit secrets to docs or repository files.\n- Use `f env get -e production -f value OPENROUTER_API_KEY` at runtime when a ship script needs to inject a missing key.\n\n## Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `login` | Authenticate with cloud |\n| `set` | Set a single env var |\n| `get` | Get specific env var(s) |\n| `list` | List env vars for this project |\n| `delete` | Delete env var(s) |\n| `pull` | Fetch env vars and write to .env |\n| `push` | Push local .env to cloud |\n| `apply` | Apply env vars to Cloudflare worker |\n| `setup` | Interactive wizard to push env vars |\n| `run` | Run command with env vars injected |\n| `status` | Show current auth status |\n| `keys` | Show configured env keys from flow.toml |\n| `sync` | Sync project settings and hub workflow |\n| `bootstrap` | Bootstrap Cloudflare secrets from flow.toml |\n| `unlock` | Unlock env reads (Touch ID on macOS) |\n\n---\n\n## Set\n\nStore a personal environment variable:\n\n```bash\n# Basic set\nf env set API_KEY=sk-xxx\n\n# Personal envs always use the production personal store\nf env set GITHUB_TOKEN=ghp_xxx\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--personal` | | Compatibility flag; `set` already targets personal envs |\n\n## Project Set\n\nStore a project-scoped environment variable:\n\n```bash\nf env project set -e dev DATABASE_URL=postgres://localhost/app\nf env project set -e production PUBLIC_API_BASE_URL=https://api.example.com\n```\n\nNotes:\n- Project cloud writes are sealed by default.\n- On a new device, the first project read/write auto-registers that device as a sealer.\n- If a key exists in cloud but was never shared to this device, Flow will ask you to re-save it from a device that already has access.\n\n---\n\n## Get\n\nRetrieve environment variables:\n\n```bash\n# Get as KEY=VALUE\nf env get API_KEY\n# API_KEY=sk-xxx\n\n# Get just the value\nf env get API_KEY -f value\n# sk-xxx\n\n# Get as JSON\nf env get API_KEY -f json\n# {\"API_KEY\": \"sk-xxx\"}\n\n# Get multiple\nf env get API_KEY DATABASE_URL\n\n# From personal store\nf env get --personal GITHUB_TOKEN -f value\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--format <FORMAT>` | `-f` | Output: `env`, `json`, or `value` (default: env) |\n| `--personal` | | Fetch from personal store |\n\n---\n\n## List\n\nList all environment variables:\n\n```bash\n# List production vars\nf env list\n\n# List staging vars\nf env list -e staging\n```\n\nOutput:\n```\nEnvironment: production\n\n  API_KEY          OpenAI API key\n  DATABASE_URL     PostgreSQL connection string\n  REDIS_URL        -\n```\n\n---\n\n## Run\n\nRun a command with environment variables injected:\n\n```bash\n# Inject all project env vars\nf env run -- npm start\n\n# Inject specific keys\nf env run -k API_KEY -k DATABASE_URL -- node server.js\n\n# From personal store\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n\n# Multiple keys from personal\nf env run --personal -k TELEGRAM_BOT_TOKEN -k TELEGRAM_API_ID -- ./start.sh\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--keys <KEYS>` | `-k` | Specific keys to inject (repeatable) |\n| `--personal` | | Fetch from personal store |\n\n### Examples\n\n```bash\n# Start app with production secrets\nf env run -- npm run start\n\n# Run with staging environment\nf env run -e staging -- npm run dev\n\n# Telegram bot with personal tokens\nf env run --personal -k TELEGRAM_BOT_TOKEN -- pnpm tsx src/bot.ts\n```\n\n---\n\n## Pull\n\nFetch all env vars and write to `.env` file:\n\n```bash\n# Write to .env\nf env pull\n\n# Pull staging vars\nf env pull -e staging\n```\n\nCreates or overwrites `.env` in current directory with all project variables.\n\n---\n\n## Push\n\nUpload local `.env` file to cloud:\n\n```bash\nf env push\n```\n\nReads `.env` from current directory and stores all variables.\n\n---\n\n## Setup\n\nInteractive wizard for pushing env vars:\n\n```bash\nf env setup\n```\n\nIf `[cloudflare] env_source = \"cloud\"` is set in `flow.toml`, this runs a guided\nprompt based on `env_keys`/`env_vars`. Otherwise it guides you through:\n1. Reading your `.env` file\n2. Selecting which keys to push\n3. Confirming before upload\n\n---\n\n## Delete\n\nRemove environment variables:\n\n```bash\n# Delete single key\nf env delete API_KEY\n\n# Delete multiple\nf env delete API_KEY DATABASE_URL\n```\n\n---\n\n## Login\n\nAuthenticate with cloud:\n\n```bash\nf env login\n```\n\nPrompts for API base URL and token. On macOS, the token is stored in Keychain\nand Flow uses Touch ID to unlock env reads.\n\n---\n\n## Status\n\nCheck authentication status:\n\n```bash\nf env status\n```\n\nOutput:\n```\ncloud Status\n  Token: stored in Keychain\n  API: https://myflow.sh\n  Project: myproject\n```\n\n---\n\n## Apply\n\nApply env vars to Cloudflare worker (uses `[cloudflare]` config in flow.toml):\n\n```bash\nf env apply\n```\n\nRequires `env_source = \"cloud\"` in your `[cloudflare]` config.\n\n## Keys\n\nShow env keys configured in `flow.toml` without printing values:\n\n```bash\nf env keys\n```\n\n## Unlock\n\nOn macOS, unlock env reads for the day (Touch ID):\n\n```bash\nf env unlock\n```\n\n---\n\n## Environments\n\nFlow supports three environments:\n\n| Environment | Description |\n|-------------|-------------|\n| `production` | Production secrets (default) |\n| `staging` | Staging/preview secrets |\n| `dev` | Development secrets |\n\nUse `-e` flag with project-scoped commands:\n\n```bash\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env list -e dev\nf env run -e staging -- npm run preview\n```\n\n---\n\n## Personal vs Project Variables\n\n| Type | Flag | Scope | Use Case |\n|------|------|-------|----------|\n| Project | (default for `get`, `list`, `run`, `project ...`) | Current project | API keys, database URLs |\n| Personal | `--personal` | Global/user | GitHub token, Telegram bot token |\n\nPersonal variables are tied to your user account, not a specific project.\n`f env set` writes personal vars. Use `f env project set` for project vars.\n\n```bash\n# Use a personal token in any project\nf env run --personal -k ANTHROPIC_API_KEY -- ./my-script\n```\n\n---\n\n## Env Space Overrides\n\nYou can store project envs under a named cloud space by configuring `env_space`\nand `env_space_kind` in `flow.toml`.\n\n```toml\n# flow.toml\nenv_space = \"nikiv\"\nenv_space_kind = \"personal\"\n```\n\n- `env_space_kind = \"project\"` (default) uses the project name.\n- `env_space_kind = \"personal\"` routes project envs to your personal space.\n\nThis affects `f env pull`, `f env push`, `f env list`, `f env apply`, and service\ntoken creation.\n\n---\n\n## Examples\n\n### Typical Workflow\n\n```bash\n# 1. Authenticate\nf env login\n\n# 2. Set up secrets\nf env project set DATABASE_URL=postgres://... -e production\nf env project set API_KEY=sk-xxx -e production\n\n# 3. Verify\nf env list\n\n# 4. Run app\nf env run -- npm start\n```\n\n### Staging Deploy\n\n```bash\n# Set staging secrets\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env project set API_KEY=sk-test-xxx -e staging\n\n# Test with staging env\nf env run -e staging -- npm run preview\n```\n\n### Personal Tokens for CLI Tools\n\n```bash\n# Store once\nf env set --personal GITHUB_TOKEN=ghp_xxx\nf env set --personal TELEGRAM_BOT_TOKEN=xxx\n\n# Use anywhere\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n```\n\n### In flow.toml Tasks\n\n```toml\n[tasks.start]\ncommand = \"f env run -- npm start\"\n\n[tasks.bot]\ncommand = \"f env run --personal -k TELEGRAM_BOT_TOKEN -- node bot.js\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Not authenticated\"\n\nRun `f env login` to authenticate with cloud.\n\n### \"No env vars found\"\n\nCheck environment name - default is `production`:\n```bash\nf env list -e staging  # Check staging instead\n```\n\n### Variables not injecting\n\nEnsure command comes after `--`:\n```bash\nf env run -k API_KEY -- npm start  # Correct\nf env run -k API_KEY npm start     # May not work\n```\n\n## See Also\n\n- [deploy](deploy.md) - Using env vars in deployments\n- [docs/how-to-use-env.md](../how-to-use-env.md) - Extended usage guide\n","isInternal":false,"tokens":2759,"sizeBytes":10719},{"name":"ext.md","path":"docs/commands/ext.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/ext.md","title":"Command: /ext","category":"command-prompt","format":"markdown","content":"# f ext\n\nManage Flow config extensions under `~/.flow/extensions`.\n\nThis is the extension/operator surface for the centralized Flow config system:\n\n- root config: `~/.flow/config.ts`\n- runtime helper: `~/.flow/runtime/flow-config.ts`\n- extension root: `~/.flow/extensions/<name>/`\n\nExtensions are loaded by `f config build` / `f config apply` when their names\nappear in `extensions: [...]` inside `~/.flow/config.ts`.\n\nFor backwards compatibility, `f ext <path>` still supports the older external\ndirectory import workflow into `<project>/ext/<name>`.\n\n## Commands\n\n### f ext list\n\nList built-in and filesystem extensions and whether they are enabled.\n\n```bash\nf ext list\nf ext list --json\n```\n\n### f ext doctor\n\nShow root-config wiring for extensions:\n\n- `~/.flow/config.ts`\n- `~/.flow/extensions`\n- `~/.flow/runtime/flow-config.ts`\n\nand the currently discoverable extensions.\n\n```bash\nf ext doctor\nf ext doctor --json\n```\n\n### f ext init\n\nCreate a new extension scaffold under `~/.flow/extensions/<name>/`.\n\nGenerated files:\n\n- `extension.ts`\n- `README.md`\n\nThe scaffold imports:\n\n- `defineFlowExtension` from `~/.flow/runtime/flow-config.ts`\n\n```bash\nf ext init my-extension\nf ext init my-extension --force\n```\n\n### f ext enable\n\nEnable an extension by name in `~/.flow/config.ts`.\n\n```bash\nf ext enable my-extension\n```\n\n### f ext disable\n\nDisable an extension by name in `~/.flow/config.ts`.\n\n```bash\nf ext disable my-extension\n```\n\n### f ext import\n\nExplicit legacy import form. Copies an external directory into `<project>/ext/`\nand adds `ext/` to `.gitignore`.\n\n```bash\nf ext import ~/some/external/repo\n```\n\nBare path form is still accepted:\n\n```bash\nf ext ~/some/external/repo\n```\n\n## Extension Shape\n\nAn extension file can export:\n\n```ts\nimport { defineFlowExtension } from \"../../runtime/flow-config\"\n\nexport default defineFlowExtension({\n  name: \"my-extension\",\n  flow: { ... },\n  lin: { ... },\n  ai: { ... },\n  hive: { ... }, // migration-only; Flow no longer applies ~/.hive/config.json\n  zerg: { ... },\n  generatedFiles: [\n    {\n      path: \"~/.some/target/file.json\",\n      content: \"{...}\",\n    },\n  ],\n  doctor: [\"human-readable check or note\"],\n})\n```\n\n## Notes\n\n- built-in extension currently supported: `lin-compat`\n- `f ext enable` rewrites `~/.flow/config.ts`\n- `f ext init` also ensures the runtime helper exists\n- generated file path collisions fail the build\n","isInternal":false,"tokens":598,"sizeBytes":2386},{"name":"failure.md","path":"docs/commands/failure.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/failure.md","title":"Command: /failure","category":"command-prompt","format":"markdown","content":"# f failure\n\nInspect and copy recent task failures without manually selecting terminal text.\n\n## Usage\n\n```bash\nf failure\nf failure last\nf failure last --json\nf failure list\nf failure list --json --limit 10\nf failure copy\nf failure copy --format codex\nf failure copy --format codex --write-repo\nf failure copy --format claude\nf failure copy --format excerpt\nf failure copy --format json\n```\n\n## What It Reads\n\nFlow records failures to a stable latest pointer plus versioned history:\n\n```text\n~/.cache/flow/last-task-failure.json\n~/.cache/flow/task-failures/*.json\n```\n\nOverride the latest pointer with:\n\n```bash\nFLOW_FAILURE_BUNDLE_PATH=/tmp/last-task-failure.json\n```\n\n## Notes\n\n- `f failure` defaults to `f failure last`\n- `f failure copy` defaults to the latest failure in `prompt` format\n- `f failure copy --format codex` and `--format claude` render Flow-native repair prompts\n- `f failure copy --write-repo` writes the selected payload to `.ai/internal/failures/`\n- `f failure list --json` is intended for launcher consumers such as Alfred or Lin\n- Set `FLOW_NO_CLIPBOARD=1` to disable clipboard writes\n","isInternal":false,"tokens":281,"sizeBytes":1109},{"name":"fast.md","path":"docs/commands/fast.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/fast.md","title":"Command: /fast","category":"command-prompt","format":"markdown","content":"# f fast\n\nRun AI tasks through the low-latency fast client path.\n\nThis command is optimized for hot-loop invocation and prefers `fai`/`ai-taskd-client` over full `f` task startup.\n\n## Usage\n\n```bash\nf fast ai:flow/noop\nf fast ai:flow/bench-cli -- --iterations 30\nf fast --root ~/code/flow ai:flow/dev-check\nf fast --no-cache ai:flow/dev-check\n```\n\n## Behavior\n\n1. Tries fast client dispatch (`fai`, local `target/.../ai-taskd-client`, or `ai-taskd-client` on PATH).\n2. If daemon is not running, starts `ai-taskd` and retries.\n3. Falls back to direct daemon dispatch if no fast client binary is found.\n\n## Options\n\n- `--root <PATH>`: root directory for `.ai/tasks` discovery (default `.`)\n- `--no-cache`: disable cached binary execution and use direct Moon run\n- `TASK`: required AI selector like `ai:flow/dev-check`\n- trailing args after `--` are passed to the task\n\n## Notes\n\n- `f fast` is intentionally for `ai:*` selectors only.\n- Install `fai` for best latency:\n\n```bash\nf install-ai-fast-client\nf tasks daemon start\nf fast ai:flow/noop\n```\n\nFor pooled burst execution and timings, use `fai` directly:\n\n```bash\nfai --timings ai:flow/noop\nprintf 'ai:flow/noop\\nai:flow/noop\\n' | fai --batch-stdin --timings\n```\n","isInternal":false,"tokens":345,"sizeBytes":1214},{"name":"global.md","path":"docs/commands/global.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/global.md","title":"Command: /global","category":"command-prompt","format":"markdown","content":"# f global\n\nRun tasks from your global flow config (`~/.config/flow/flow.toml`).\n\n## Quick Start\n\n```bash\n# List global tasks\nf global --list\nf global list\n\n# Run a global task from anywhere\nf global repos-clone-safari\nf global run repos-clone-safari\n\n# Match a query against global tasks\nf global match \"clone safari repo\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `<TASK>` | | Global task name (omit to list) |\n| `list` | | List global tasks |\n| `run <TASK>` | | Run a global task |\n| `match <QUERY>` | | Match a query against global tasks |\n| `--list` | `-l` | List global tasks |\n| `-- <ARGS...>` | | Pass extra args to the task |\n\n## Examples\n\n```bash\nf global repos-clone-safari https://github.com/0xPlaygrounds/rig\n```\n","isInternal":false,"tokens":214,"sizeBytes":769},{"name":"install.md","path":"docs/commands/install.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/install.md","title":"Command: /install","category":"command-prompt","format":"markdown","content":"# f install\n\nInstall a CLI/tool binary into your PATH.\n\nDefault backend behavior (`--backend auto`):\n1. Flow registry (`myflow.sh` or `--registry`)\n2. GitHub releases via `parm`\n3. flox package install\n\n## Usage\n\n```bash\nf install <name>\n```\n\n## Options\n\n- `--registry <URL>`: registry base URL (defaults to `FLOW_REGISTRY_URL`).\n- `--backend <auto|registry|parm|flox>`: choose install backend explicitly.\n- `--version <VERSION>`: install a specific version (defaults to latest).\n- `--bin <NAME>`: binary name to install (defaults to manifest default or package name).\n- `--bin-dir <PATH>`: install directory (defaults to `~/bin`).\n- `--force`: overwrite an existing binary.\n- `--no-verify`: skip checksum verification.\n\n## Auto backend notes\n\n- `f install rise` can resolve through `parm` using built-in owner/repo mapping.\n- Built-in aliases:\n  - `f install seqd` resolves registry package `seq` with binary `seqd`.\n  - `f install lin` resolves registry package `flow` with binary `lin`.\n- If a package name is ambiguous for `parm`, set `FLOW_INSTALL_OWNER` (env or Flow personal env store) or pass `owner/repo` directly.\n\n## Bootstrap from installer\n\nThe hosted installer can bootstrap core tools after installing flow:\n\n- `FLOW_BOOTSTRAP_TOOLS=\"rise seq seqd\"` (default) installs those with `f install ... --backend auto`.\n- `FLOW_BOOTSTRAP_TOOLS=0` disables this.\n- `FLOW_BOOTSTRAP_INSTALL_PARM=1` (default) attempts to install `parm` for robust GitHub fallback.\n\n## Registry layout\n\nThe registry must expose:\n\n- `GET /packages/<name>/latest.json`\n- `GET /packages/<name>/<version>/manifest.json`\n- `GET /packages/<name>/<version>/<target>/<bin>`\n\n## Example\n\n```bash\nFLOW_REGISTRY_URL=https://myflow.sh f install flow\n```\n\n```bash\nf install rise\n```\n","isInternal":false,"tokens":448,"sizeBytes":1756},{"name":"invariants.md","path":"docs/commands/invariants.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/invariants.md","title":"Command: /invariants","category":"command-prompt","format":"markdown","content":"# f invariants\n\nValidate project invariants declared in `flow.toml`.\n\nThis command checks the `[invariants]` section and reports violations in changed code.\n\n## Usage\n\n```bash\n# Check all local changes vs HEAD\nf invariants\n\n# Check only staged changes\nf invariants --staged\n```\n\n## What It Checks\n\n1. `forbidden`: disallowed patterns in added diff lines.\n2. `deps.approved`: unapproved dependencies in `package.json` sections (`dependencies`, `devDependencies`, `peerDependencies`).\n3. `files.max_lines`: changed files exceeding the configured line limit.\n\n## Modes\n\nSet in `flow.toml`:\n\n- `mode = \"off\"`: disable checks.\n- `mode = \"warn\"`: print findings, exit success.\n- `mode = \"block\"`: fail command when blocking findings exist.\n\n## Example `flow.toml`\n\n```toml\n[invariants]\nmode = \"block\"\narchitecture_style = \"layered monorepo, event-driven core\"\nnon_negotiable = [\n  \"no inline imports\",\n  \"no any types unless justified\",\n]\nforbidden = [\n  \"git add -A\",\n  \"git reset --hard\",\n]\n\n[invariants.terminology]\n\"pi-ai\" = \"LLM abstraction layer\"\n\"pi-agent\" = \"stateful agent runtime\"\n\n[invariants.deps]\npolicy = \"approval_required\"\napproved = [\"@sinclair/typebox\", \"@reatom/core\"]\n\n[invariants.files]\nmax_lines = 300\n```\n\n## Commit Integration\n\n`f commit` runs the invariant gate during commit-with-check flow.\n\n- In `mode = \"block\"`, commits are blocked on invariant warnings/critical findings.\n- Invariant context and findings are injected into AI review prompts.\n\n","isInternal":false,"tokens":369,"sizeBytes":1468},{"name":"jj.md","path":"docs/commands/jj.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/jj.md","title":"Command: /jj","category":"command-prompt","format":"markdown","content":"# jj\n\nFlow wraps common Jujutsu (jj) workflows so you can stay in jj while remaining fully Git-compatible.\n\n## Quick start\n\n```bash\n# Inspect workspace + home-branch state\nf status\n\n# Initialize jj (colocated with git when .git exists)\nf jj init\n\n# Create a feature bookmark and track origin\nf jj bookmark create feature-x --track\n\n# Fetch + rebase onto main + push bookmark\nf jj sync --bookmark feature-x\n```\n\n## Commands\n\n- `f status` — Show workflow-aware JJ status (workspace, home branch, leaf branches, working-copy summary, and next-step hints)\n- `f jj status` — Show raw `jj st`\n- `f jj fetch` — `jj git fetch`\n- `f jj rebase --dest <branch>` — Rebase onto `jj.default_branch` (or main/master)\n- `f jj push --bookmark <name>` — Push a single bookmark\n- `f jj push --all` — Push all bookmarks\n- `f jj sync --bookmark <name>` — Fetch, rebase, then push bookmark\n- `f jj workspace add <name> [--path <dir>] [--rev <rev>]` — Create a workspace (optionally anchored to a revision)\n- `f jj workspace lane <name> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create an isolated parallel lane from trunk defaults\n- `f jj workspace review <branch> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create or reuse a stable JJ review workspace for a branch without touching the current checkout\n- `f jj workspace list` — List workspaces\n- `f jj bookmark create <name> [--rev <rev>] [--track]` — Create bookmark\n- `f jj bookmark track <name> [--remote <remote>]` — Track remote bookmark\n\n## Status-first workflow\n\nUse `f status` before branch, workspace, commit, or publish operations.\n\nIt is the fast way to answer:\n\n- which workspace am I in?\n- am I on the long-lived home branch or a branch-specific leaf?\n- what review or codex branches currently sit on top of the home branch?\n- is the working copy clean enough to mutate safely?\n\nExample:\n\n```bash\ncd ~/code/org/project\nf status\n```\n\nUse `f jj status` only when you want the raw Jujutsu working-copy view.\n\n## Parallel lanes (no interleaving)\n\nUse lanes when you want multiple active tasks in one repo without stash/pop churn:\n\n```bash\n# In your current repo, create isolated lanes anchored from trunk\nf jj workspace lane fix-otp\nf jj workspace lane testflight\n\n# Work each lane independently\ncd ~/.jj/workspaces/<repo>/fix-otp\njj st\n```\n\n`f jj workspace lane` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. chooses base as `<default_branch>@<remote>` when tracked (fallback: `<default_branch>`)\n3. creates a dedicated workspace with its own `@` working-copy commit\n\n## Review workspaces\n\nUse a review workspace when you want an isolated JJ working copy for a review branch without\ntouching the current repo checkout:\n\n```bash\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/<repo>/review-alice-feature\njj st\n```\n\n`f jj workspace review` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. reuses the existing review workspace when present\n3. otherwise anchors the workspace at the local branch commit, then the remote branch commit, then trunk\n4. prints the stable workspace path plus the JJ bookmark command to publish later\n\nImportant:\n\n- The review workspace is JJ-native. Use `jj` or `f jj` inside it.\n- In colocated repos, plain `git` still points at the main checkout, so this command intentionally does not run `flow switch` for you.\n\n## Config\n\nAdd to `flow.toml`:\n\n```toml\n[git]\nremote = \"myflow-i\"  # optional preferred writable remote\n\n[jj]\ndefault_branch = \"main\"\nhome_branch = \"alice\" # optional long-lived personal integration branch\nremote = \"origin\"     # optional legacy fallback if [git].remote is unset\nauto_track = true\n```\n\nThis keeps jj aligned with Git remotes while you work locally in jj.\n\n## Home-branch model\n\nIf you keep a long-lived personal branch on top of trunk, set `jj.home_branch` and treat it as\nyour integration branch.\n\nWhen the current branch matches that home branch, plain `f sync` also switches into home-branch\nmode and syncs `origin/<default-branch>` into it instead of using the normal tracking pull.\n\nThen use short-lived `review/*` or `codex/*` branches on top of that home branch for task-specific\nwork. `f status` is optimized to make that shape visible.\n\nRecommended flow:\n\n```bash\n# Default checkout stays on your home branch\ncd ~/code/org/project\nf status\n\n# Branch-specific work happens in isolated workspaces\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/project/review-alice-feature\nf status\n```\n\nSee also:\n\n- [`jj-review-workspaces.md`](../jj-review-workspaces.md)\n- [`jj-home-branch-workflow.md`](../jj-home-branch-workflow.md)\n","isInternal":false,"tokens":1147,"sizeBytes":4630},{"name":"migrate.md","path":"docs/commands/migrate.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/migrate.md","title":"Command: /migrate","category":"command-prompt","format":"markdown","content":"# f migrate\n\nMove or copy a project folder to a new location, preserving symlinks and AI sessions.\n\n## Overview\n\nRelocates a project directory and automatically migrates Claude and Codex AI sessions so conversation history follows the project. Also relinks any `~/bin` symlinks that pointed into the old path (move only).\n\n## Quick Start\n\n```bash\n# Move current directory into ~/code/lang/cpp/stream\ncd ~/code/lang/cpp/stream\nf migrate code stream\n\n# Move current directory to an arbitrary path\nf migrate ~/code/stream\n\n# Move a specific source to a target\nf migrate ~/code/lang/cpp/stream ~/code/stream\n\n# Preview what would happen (no changes)\nf migrate --dry-run code stream\n\n# Copy instead of move (keeps original)\nf migrate --copy code stream\n```\n\n## Your case\n\nTo migrate `~/code/lang/cpp/stream` to `~/code/stream`:\n\n```bash\ncd ~/code/lang/cpp/stream\nf migrate code stream\n```\n\nOr without `cd`:\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\nPreview first with `--dry-run`:\n\n```bash\nf migrate --dry-run ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Usage Forms\n\n### `f migrate code <relative>`\n\nMoves the current directory into `~/code/<relative>`. This is the most common form.\n\n```bash\ncd ~/old/location/myproject\nf migrate code myproject          # -> ~/code/myproject\nf migrate code lang/rust/mylib    # -> ~/code/lang/rust/mylib\n```\n\n### `f migrate <target>`\n\nMoves the current directory to `<target>` (any absolute or relative path).\n\n```bash\ncd ~/old/location/myproject\nf migrate ~/code/myproject\n```\n\n### `f migrate <source> <target>`\n\nMoves `<source>` to `<target>` without needing to `cd` first.\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--copy` | `-c` | Copy instead of move (keeps the original intact) |\n| `--dry-run` | | Show what would change without writing anything |\n| `--skip-claude` | | Skip migrating Claude Code sessions |\n| `--skip-codex` | | Skip migrating Codex sessions |\n\n## What Happens\n\n### Step 1: Move or copy the folder\n\nThe project directory is moved (or copied with `--copy`) to the target path. Parent directories are created automatically. Cross-device moves are handled transparently (copy + delete).\n\n### Step 2: Relink ~/bin symlinks (move only)\n\nAny symlinks in `~/bin` that pointed into the old path are updated to point to the new location. Skipped when using `--copy`.\n\n### Step 3: Migrate AI sessions\n\nClaude and Codex store project sessions keyed by filesystem path. Migrate updates these so conversation history is preserved at the new location.\n\n- **Claude sessions**: Project directories under `~/.claude/projects/` are renamed from the old path-based key to the new one.\n- **Codex sessions**: Legacy project directories are renamed, and `.jsonl` session files referencing the old path are updated in-place.\n\nA summary is printed showing how many session dirs/files were migrated.\n\n## Examples\n\n```bash\n# Move project into ~/code, nested path\ncd ~/downloads/cool-project\nf migrate code tools/cool-project\n\n# Copy a project (keeps original)\nf migrate --copy ~/code/app ~/backup/app\n\n# Dry run to preview\nf migrate --dry-run code stream\n\n# Move without migrating AI sessions\nf migrate --skip-claude --skip-codex ~/old/path ~/new/path\n\n# Move and only migrate Claude (skip Codex)\nf migrate --skip-codex code myproject\n```\n\n## Troubleshooting\n\n### \"Destination already exists\"\n\nThe target path must not exist. Remove or rename the existing directory first, or choose a different target.\n\n### \"Source and destination are the same path\"\n\nBoth paths resolve to the same location. Double-check your arguments.\n\n### Session migration warnings\n\nAfter a move, you may see warnings like:\n\n```\nWARN Claude session dir still present: ...\nWARN Codex sessions still reference the old path:\n  /path/to/file.jsonl\n```\n\nThese mean some sessions couldn't be fully migrated. You can manually inspect or delete the referenced files.\n\n## See Also\n\n- [repos](repos.md) - Clone repositories into structured layout\n","isInternal":false,"tokens":967,"sizeBytes":4056},{"name":"new.md","path":"docs/commands/new.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/new.md","title":"Command: /new","category":"command-prompt","format":"markdown","content":"# f new\n\nCreate a new project from a local starter template under `~/new`.\n\n## Overview\n\n`f new` copies a directory from `~/new/<template>` into a destination path.\n\nThis is the native Flow way to work with local starters you keep in `~/new`.\n\n## Usage\n\n```bash\nf new [template] [path]\n```\n\n- `template`: folder name inside `~/new` (for example `app`, `docs`, `web`)\n- `path`: destination path (optional)\n\nIf `template` is omitted, Flow opens an `fzf` picker from templates in `~/new`.\n\n## Path Resolution Rules\n\nFlow resolves the destination path like this:\n\n```bash\nf new app          # -> ./app\nf new app zerg     # -> ~/code/zerg\nf new app ./xn     # -> ./xn\nf new app ~/xn     # -> ~/xn\n```\n\nNotes:\n- Plain names (no `./`, `../`, `/`, `~`) are treated as `~/code/<name>`.\n- Use `~/...` or absolute paths for custom locations outside `~/code`.\n\n## Dry Run\n\nPreview copy behavior without writing files:\n\n```bash\nf new app ~/xn --dry-run\n```\n\n## Starter Workflow\n\n1. Create or update starter in `~/new/<template>`.\n2. Generate a new project with `f new <template> <target>`.\n3. Enter the new project and run its setup/dev tasks with Flow.\n\nExample:\n\n```bash\nf new app ~/xn\ncd ~/xn\nf tasks\n```\n\n## Common Errors\n\n- `Template not found`: `~/new/<template>` does not exist.\n- `Destination already exists`: remove/rename target path or choose a new destination.\n","isInternal":false,"tokens":367,"sizeBytes":1360},{"name":"pr.md","path":"docs/commands/pr.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/pr.md","title":"Command: /pr","category":"command-prompt","format":"markdown","content":"# f pr\n\nCreate or open GitHub pull requests, edit PR text locally, and pull review feedback.\n\n## Quick Start\n\n```bash\n# Create/update PR from current changes (default base: main)\nf pr \"assistant improvements\"\n\n# Open current branch PR in browser\nf pr open\n\n# Edit PR title/body in local markdown and sync on save\nf pr open edit\n\n# Pull actionable review feedback for current PR\nf pr feedback\n\n# Pull feedback for specific PR and store as local todos\nf pr feedback 8 --todo\nf pr feedback https://github.com/owner/repo/pull/8 --todo\n\n# Full inline diff/review context is now the default\nf pr feedback 8\n\n# Use terse terminal output if needed\nf pr feedback 8 --compact\n```\n\n## Feedback Workflow\n\n`f pr feedback` fetches:\n\n- PR reviews (`/pulls/<n>/reviews`)\n- Inline review comments (`/pulls/<n>/comments`)\n- Top-level PR comments (`/issues/<n>/comments`)\n\nIt then:\n\n1. Prints an actionable list in terminal with inline review state and diff hunk context by default.\n2. Writes a markdown snapshot to `.ai/reviews/pr-feedback-<pr>.md`.\n3. Writes a machine-readable JSON snapshot to `.ai/reviews/pr-feedback-<pr>.json`.\n4. Writes a human review plan to `~/docs/plan/review/<repo>-pr-<pr>-feedback.md`.\n5. Writes a PR-local execution artifact to `~/docs/plan/review/<repo>-pr-<pr>-review-rules.md`.\n6. Writes a Kit system prompt to `~/docs/plan/review/<repo>-pr-<pr>-kit-system.md`.\n7. Optionally (`--todo`) records feedback into `.ai/todos/todos.json` with dedupe via external refs.\n\nThe review plan includes ready-to-run `kit` commands for:\n\n- deterministic repo review via `kit review`\n- preventative lint/review rule synthesis from the fetched GitHub feedback set\n\nThe generated `*-review-rules.md` artifact contains the per-item resolution loop,\nprompt template, required response sections, and Kit-upgrade decision order so\nthe workflow can be reopened without extra instructions.\n\n## Notes\n\n- If no selector is passed, Flow resolves the PR from the current branch.\n- `f pr feedback --todo` is safe to re-run; existing feedback refs are not duplicated.\n- `f pr feedback` is full-context by default. Use `--compact` if you want the older terse terminal view.\n- `f pr feedback` now emits a Kit-ready handoff, so the same feedback set can drive a future review bot instead of staying trapped in GitHub comments.\n- `f pr open edit` remains the quickest path to tweak PR title/body from local editor.\n","isInternal":false,"tokens":581,"sizeBytes":2396},{"name":"publish.md","path":"docs/commands/publish.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/publish.md","title":"Command: /publish","category":"command-prompt","format":"markdown","content":"# f publish\n\nPublish projects to GitHub.\n\n## Overview\n\nCreates a new GitHub repository and pushes the current project. Automatically infers the repo name from the folder name and handles both new repos and existing ones.\n\n## Quick Start\n\n```bash\n# Interactive mode - prompts for name and visibility\nf publish\n\n# Skip prompts, use folder name, default to private\nf publish -y\n\n# Create public repo\nf publish --public\n\n# Create with specific name\nf publish --name my-awesome-project\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--name <NAME>` | `-n` | Repository name (defaults to folder name) |\n| `--public` | | Create as public repository |\n| `--private` | | Create as private repository |\n| `--description <DESC>` | `-d` | Repository description |\n| `--yes` | `-y` | Skip prompts, use defaults (private, folder name) |\n\n## Prerequisites\n\n- [GitHub CLI](https://cli.github.com/) installed (`gh`)\n- Authenticated with `gh auth login`\n\n## Usage\n\n### Interactive Mode\n\nWithout flags, prompts for configuration:\n\n```bash\n$ f publish\n\nRepository name [my-project]:\nVisibility (public/private) [private]: public\n\nCreate repository:\n  Name: username/my-project\n  Visibility: public\n\nProceed? [Y/n]:\n```\n\n### Non-Interactive Mode\n\n```bash\n# Use all defaults (private, folder name as repo name)\nf publish -y\n\n# Public repo with defaults\nf publish -y --public\n\n# Specific name and description\nf publish -n cool-tool -d \"A cool CLI tool\" --public\n```\n\n### Existing Repositories\n\nIf the repository already exists on GitHub:\n\n1. Checks current visibility\n2. Updates visibility if different from requested\n3. Adds origin remote if missing\n4. Pushes current branch\n\n```bash\n$ f publish --public\nRepository username/my-repo already exists (private).\nUpdating visibility to public...\n✓ Updated to public\n\n✓ https://github.com/username/my-repo\n```\n\n## What Happens\n\n1. **Check gh CLI** - Verifies GitHub CLI is installed\n2. **Check authentication** - Ensures you're logged in to GitHub\n3. **Get username** - Fetches your GitHub username\n4. **Determine repo name** - Uses `--name`, folder name, or prompts\n5. **Determine visibility** - Uses `--public`/`--private` or prompts\n6. **Check if exists** - If repo exists, updates visibility if needed\n7. **Initialize git** - If not a git repo, runs `git init`\n8. **Create initial commit** - If no commits, stages all and commits\n9. **Create repository** - Uses `gh repo create` with `--source=. --push`\n10. **Output URL** - Prints the GitHub URL\n\n## Examples\n\n### Quick Publish New Project\n\n```bash\ncd my-new-project\nf publish -y --public\n# ✓ Published to https://github.com/username/my-new-project\n```\n\n### Publish with Description\n\n```bash\nf publish -n api-server -d \"REST API for my app\" --private\n```\n\n### Update Existing Repo Visibility\n\n```bash\n# Repo exists as private, make it public\nf publish --public\n# Repository username/my-repo already exists (private).\n# Updating visibility to public...\n# ✓ Updated to public\n```\n\n### In Scripts/CI\n\n```bash\n#!/bin/bash\ncd /path/to/project\nf publish -y --public -n release-candidate\n```\n\n## Troubleshooting\n\n### \"GitHub CLI (gh) is not installed\"\n\nInstall from https://cli.github.com:\n\n```bash\n# macOS\nbrew install gh\n\n# Linux\nsudo apt install gh  # or equivalent\n```\n\n### \"GitHub authentication required\"\n\nRun `gh auth login` and follow the prompts.\n\n### \"Could not determine GitHub username\"\n\nEnsure you're authenticated: `gh auth status`\n\n### Repository exists but can't update visibility\n\nSome visibility changes may require specific permissions or GitHub plan features.\n\n## See Also\n\n- [deploy](deploy.md) - Deploy after publishing\n- [upstream](upstream.md) - Managing forks\n","isInternal":false,"tokens":902,"sizeBytes":3702},{"name":"readme.md","path":"docs/commands/readme.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/readme.md","title":"Command: /readme","category":"command-prompt","format":"markdown","content":"# Flow Commands Reference\n\nComplete documentation for all `f` (flow) commands.\n\n## Quick Reference\n\n| Command | Description |\n|---------|-------------|\n| [`deploy`](deploy.md) | Deploy to Linux hosts, Cloudflare Workers, or Railway |\n| [`release`](release.md) | Publish a release to registry or GitHub |\n| [`publish`](publish.md) | Publish project to GitHub |\n| [`install`](install.md) | Install a CLI/tool via registry, parm, or flox |\n| [`clone`](clone.md) | Clone repositories with git-like destination behavior |\n| [`repos`](repos.md) | Clone repositories into ~/repos |\n| [`new`](new.md) | Create a project from a local template in ~/new |\n| [`commit`](commit.md) | AI-powered commit with code review |\n| [`pr`](pr.md) | Create/open PRs and ingest GitHub feedback |\n| [`upstream`](upstream.md) | Manage upstream fork workflow |\n| [`env`](env.md) | Sync project environment and manage env vars |\n| [`config`](config.md) | Build and apply centralized Flow config outputs |\n| [`ext`](ext.md) | Manage Flow config extensions |\n| [`invariants`](invariants.md) | Validate project invariants from `flow.toml` |\n| [`fast`](fast.md) | Low-latency AI task invocation via fast client |\n| [`up`](up.md) | Bring a project up with lifecycle conventions |\n| [`down`](down.md) | Bring a project down with lifecycle conventions |\n| [`domains`](domains.md) | Shared local `*.localhost` route manager on port 80 |\n| [`tasks`](tasks.md) | List and run project tasks |\n| [`failure`](failure.md) | Inspect and copy recent task failures |\n| [`global`](global.md) | Run tasks from global flow config |\n| [`setup`](setup.md) | Print aliases or run setup task |\n| [`ai`](ai.md) | Manage AI coding sessions (Claude + Codex) |\n| [`daemon`](daemon.md) | Manage background daemons |\n| [`parallel`](parallel.md) | Run tasks in parallel |\n| [`docs`](docs.md) | Manage auto-generated documentation |\n| [`web`](web.md) | Open the Flow web UI for a project |\n| [`url`](url.md) | Inspect or crawl URLs into compact AI-friendly summaries |\n\n## Getting Started\n\n```bash\n# Show all commands\nf --help\n\n# Get help for a specific command\nf deploy --help\nf commit --help\n```\n\n## Command Categories\n\n### Deployment\n\n- **[deploy](deploy.md)** - Deploy to hosts and cloud platforms\n- **[release](release.md)** - Publish releases to registries\n- **[publish](publish.md)** - Publish project to GitHub\n\n### Version Control\n\n- **[commit](commit.md)** - AI-powered commits with review\n- **[pr](pr.md)** - PR creation/editing plus review feedback ingestion\n- **[clone](clone.md)** - Clone with git-like destination behavior\n- **[repos](repos.md)** - Clone repos into a structured directory\n- **[upstream](upstream.md)** - Fork management and sync\n- **[fixup](fixup.md)** - Fix common TOML syntax errors\n\n### Task Management\n\n- **[tasks](tasks.md)** - List project tasks\n- **[failure](failure.md)** - Inspect and copy recent task failures\n- **[fast](fast.md)** - Run AI tasks through the low-latency fast client path\n- **[up](up.md)** - Start project lifecycle (`up`/`dev`) with optional domains setup\n- **[down](down.md)** - Stop project lifecycle with optional domains teardown\n- **[global](global.md)** - Run tasks from ~/.config/flow/flow.toml\n- **[setup](setup.md)** - Print aliases or run setup task\n- **[run](run.md)** - Run a specific task\n- **[parallel](parallel.md)** - Run tasks in parallel\n- **[rerun](rerun.md)** - Re-run last task\n- **[search](search.md)** - Fuzzy search global commands\n\n### Process Management\n\n- **[ps](ps.md)** - List running flow processes\n- **[kill](kill.md)** - Stop running processes\n- **[logs](logs.md)** - View task logs\n- **[daemon](daemon.md)** - Manage background daemons\n\n### AI & Development\n\n- **[ai](ai.md)** - Manage AI coding sessions\n- **[url](url.md)** - Inspect or crawl URLs into compact summaries for AI use\n- **[agent](agent.md)** - Invoke AI subagents\n- **[match](match.md)** - Match natural language to tasks\n- **[sessions](sessions.md)** - Search AI sessions across projects\n\n### Environment & Configuration\n\n- **[env](env.md)** - Manage environment variables\n- **[config](config.md)** - Build/apply the centralized Flow config snapshot\n- **[ext](ext.md)** - Scaffold, enable, disable, and inspect Flow config extensions\n- **[invariants](invariants.md)** - Validate invariant policies in `flow.toml`\n- **[domains](domains.md)** - Shared local domain proxy ownership and route management\n- **[init](init.md)** - Scaffold a new flow.toml\n- **[doctor](doctor.md)** - Verify tools and integrations\n\n### Project Management\n\n- **[new](new.md)** - Create a project from a local starter in `~/new`\n- **[projects](projects.md)** - List registered projects\n- **[active](active.md)** - Show or set active project\n- **[hub](hub.md)** - Ensure hub daemon is running\n\n### Documentation\n\n- **[docs](docs.md)** - Manage auto-generated documentation\n- **[commits](commits.md)** - Browse commits with AI metadata\n\n### Legacy Compatibility\n\n- **[recipe](recipe.md)** - Legacy recipe command (hidden; prefer `tasks` + `.ai/tasks/*.mbt`)\n\n### Other\n\n- **[skills](skills.md)** - Manage Codex skills\n- **[install](install.md)** - Install binaries via registry/parm/flox\n- **[db](db.md)** - Manage databases and providers\n- **[tools](tools.md)** - Manage AI tools\n- **[notify](notify.md)** - Send proposal notifications\n- **[server](server.md)** - Start HTTP server for logs\n\n## Global Options\n\n```bash\n-h, --help     Print help\n-V, --version  Print version\n```\n\n## Configuration\n\nFlow uses `flow.toml` for project configuration. See [flow.toml reference](../flow-toml.md) for full documentation.\n\n## See Also\n\n- [Getting Started Guide](../getting-started.md)\n- [flow.toml Reference](../flow-toml.md)\n","isInternal":false,"tokens":1451,"sizeBytes":5687},{"name":"recipe.md","path":"docs/commands/recipe.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/recipe.md","title":"Command: /recipe","category":"command-prompt","format":"markdown","content":"# f recipe\n\nLegacy compatibility command.\n\nPreferred model:\n\n- Put shell tasks in `flow.toml` under `[[tasks]]`.\n- Put AI/native tasks in `.ai/tasks/*.mbt`.\n- Run via `f <task>` or `f ai:<selector>`.\n\n`f recipe` remains for older repos that still use `.ai/recipes`.\n\n## Usage\n\n```bash\nf recipe list          # legacy listing\nf recipe run <selector> # legacy execution\n```\n\n## Options\n\n- `--scope <project|global|all>`: recipe source scope (default `all`)\n- `--global-dir <PATH>`: override global recipes directory\n- `--cwd <PATH>` (run only): working directory for execution\n- `--dry-run` (run only): print command without executing\n\n## Legacy Recipe Locations\n\n- Project recipes: `.ai/recipes/project` (fallback `.ai/recipes`).\n- Global recipes: `~/.config/flow/recipes`.\n\nSupported extensions: `.md`, `.markdown`, `.mbt`\n\nMoonBit recipe metadata is optional and can be declared in top comment lines:\n\n```mbt\n// title: My Fast Recipe\n// description: Run a moonbit action quickly\n// tags: [moonbit, fast]\n```\n\n## Migration\n\n```bash\n# Old\nf recipe run project:my-recipe\n\n# New\nf tasks init-ai\nf ai:my-task\n```\n","isInternal":false,"tokens":297,"sizeBytes":1109},{"name":"release.md","path":"docs/commands/release.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/release.md","title":"Command: /release","category":"command-prompt","format":"markdown","content":"# f release\n\nRelease a project based on `flow.toml` defaults or explicit subcommands.\n\n## Usage\n\n```bash\nf release\nf release registry\nf release gh\n```\n\n## Registry releases\n\n```bash\nf release registry\n```\n\n### flow.toml\n\n```toml\n[release]\ndefault = \"registry\"\nversioning = \"calver\"\n\n[release.registry]\nurl = \"https://myflow.sh\"\npackage = \"flow\"\nbins = [\"flow\", \"f\", \"lin\"]\ndefault_bin = \"flow\"\ntoken_env = \"FLOW_REGISTRY_TOKEN\"\nlatest = true\n```\n\n### Options\n\n- `--version <VERSION>`: publish a specific version.\n- `--registry <URL>`: override the registry base URL.\n- `--bin <NAME>`: override the binaries to upload (repeatable).\n- `--no-build`: skip building binaries.\n- `--latest` / `--no-latest`: control latest pointer updates.\n\n## GitHub releases\n\n```bash\nf release gh\n```\n","isInternal":false,"tokens":212,"sizeBytes":779},{"name":"repos.md","path":"docs/commands/repos.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/repos.md","title":"Command: /repos","category":"command-prompt","format":"markdown","content":"# f repos\n\nClone repositories into a structured local directory or create new ones.\n\nIf you want standard `git clone` destination behavior, use [`f clone`](clone.md) instead.\n\n## Overview\n\n`f repos clone` clones GitHub repositories into `~/repos/<owner>/<repo>` using SSH URLs. By default it does a shallow clone for speed, then fetches full history in the background. It always sets up an `upstream` remote and local tracking branch unless you pass `--no-upstream`. Clone-time bootstrap is local-only: it does not create or push a private mirror repo. If the target checkout already exists, Flow reports that and exits without re-bootstrapping or reopening the repo.\n`f repos create` creates a GitHub repository from the current folder and pushes it.\n\nBy default, Flow treats `~/repos` as an immutable managed root. Use `FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1` if you need to point `--root` somewhere else.\n\n## Quick Start\n\n```bash\n# Clone a GitHub repo into ~/repos/<owner>/<repo>\nf repos clone https://github.com/owner/repo\n\n# Short form\nf repos clone owner/repo\n\n# Skip upstream auto-setup\nf repos clone owner/repo --no-upstream\n\n# Full clone (skip background history fetch)\nf repos clone owner/repo --full\n\n# Create a new repo from the current folder (prompts for name/visibility)\nf repos create\n```\n\n## Options\n\n### f repos clone\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `<URL>` | | Repository URL or `owner/repo` |\n| `--root <PATH>` | | Root directory for clones (default: `~/repos`, override requires `FLOW_REPOS_ALLOW_ROOT_OVERRIDE=1`) |\n| `--full` | | Full clone (skip shallow clone + background history fetch) |\n| `--no-upstream` | | Skip upstream setup |\n| `--upstream-url <URL>` | `-u` | Upstream URL override (skips GitHub lookup) |\n| `--no-home-branch-bootstrap` | | Skip local nikiv home-branch setup after clone |\n\n### f repos create\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--name <NAME>` | `-n` | Repository name (defaults to current folder) |\n| `--public` | | Create as public repository |\n| `--private` | | Create as private repository |\n| `--description <TEXT>` | `-d` | Description for the repository |\n| `--yes` | `-y` | Skip confirmation prompts |\n\n## Upstream Automation\n\nFlow will:\n\n1. Query GitHub via `gh api repos/<owner>/<repo>`\n2. Detect the parent repository\n3. Run `f upstream setup --url <parent>` inside the cloned repo\n\nIf the repo is not a fork (or `gh` is unavailable), flow sets `upstream` to the `origin` URL.\n\n## Background History Fetch\n\nWhen cloning in fast mode (default), flow spawns a background fetch:\n\n- `git fetch --unshallow --tags origin`\n- `git fetch --tags upstream` (if upstream was configured)\n\n## Private Mirror Setup\n\n`f repos clone` no longer creates or pushes the `fork` / `*-i` private mirror as part of clone.\n\nIf you want Flow to create or repair the private mirror workflow for an existing repo, run:\n\n```bash\nf repos bootstrap-home-branch --path ~/repos/<owner>/<repo>\n```\n\n## Examples\n\n```bash\n# Clone into a custom root (requires override)\nFLOW_REPOS_ALLOW_ROOT_OVERRIDE=1 f repos clone https://github.com/owner/repo --root ~/work/repos\n\n# Override upstream manually\nf repos clone https://github.com/your-user/repo -u git@github.com:upstream-org/repo.git\n```\n","isInternal":false,"tokens":806,"sizeBytes":3277},{"name":"reviews-todo.md","path":"docs/commands/reviews-todo.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/reviews-todo.md","title":"Command: /reviews-todo","category":"command-prompt","format":"markdown","content":"# f reviews-todo\n\nManage deferred deep-review todos for queued commits.\n\nThis command is a workflow wrapper over `f commit-queue` for the fast-commit + deep-Codex-review loop.\n\n## Quick Start\n\n```bash\n# List pending deep-review todos (queued commits)\nf reviews-todo list\n\n# Run Codex deep review for all queued commits\nf reviews-todo codex --all\n\n# Inspect one queued review todo\nf reviews-todo show <commit-sha>\n\n# Approve all queued commits after issues are addressed\nf reviews-todo approve-all\n```\n\n## Why use this\n\n- Keep `f commit` fast.\n- Batch expensive Codex reviews later.\n- Keep one place to track deep-review backlog.\n\n## Notes\n\n- `codex --all` maps to `f commit-queue review --all`.\n- Queue entries live under `.ai/internal/commit-queue/`.\n- Review findings are still recorded into `.ai/todos/todos.json` and commit review reports.\n- If `[options].myflow_mirror = true` is enabled, queued Codex reviews from the quick path are mirrored to myflow as `commit_queue_review` events.\n- For a full speed-first operating loop in `~/code/myflow`, see [`../fast-commit-deep-review-loop.md`](../fast-commit-deep-review-loop.md).\n","isInternal":false,"tokens":277,"sizeBytes":1131},{"name":"seq-rpc.md","path":"docs/commands/seq-rpc.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/seq-rpc.md","title":"Command: /seq-rpc","category":"command-prompt","format":"markdown","content":"# `f seq-rpc`\n\nNative `seqd` RPC bridge for Flow.\n\nUse this when an agent/workflow needs OS-level actions and you want a typed, low-overhead path.\nThis command talks to `seqd` over Unix socket directly from Rust (no `seq rpc` subprocess).\n\n## Why this command exists\n\n- Keeps protocol handling in Rust.\n- Avoids shell output parsing drift.\n- Gives stable response envelope fields (`ok`, `op`, `dur_us`, ids).\n- Matches hard policy in `docs/seq-agent-rpc-contract.md`.\n\n## Usage\n\n```bash\nf seq-rpc [--socket PATH] [--timeout-ms 5000] [--pretty] <action> ...\n```\n\nActions:\n\n- `ping`\n- `app-state`\n- `perf`\n- `open-app <name>`\n- `open-app-toggle <name>`\n- `screenshot <path>`\n- `rpc <op> [--args-json '{...}']`\n\nCommon id fields (recommended on every call):\n\n- `--request-id`\n- `--run-id`\n- `--tool-call-id`\n\nExample:\n\n```bash\nf seq-rpc open-app \"Safari\" \\\n  --request-id req-42 \\\n  --run-id run-a12 \\\n  --tool-call-id tool-7 \\\n  --pretty\n```\n\n## Socket resolution\n\n1. `--socket <path>`\n2. `SEQ_SOCKET_PATH`\n3. `SEQD_SOCKET`\n4. `/tmp/seqd.sock`\n\n## Output\n\nPrints JSON response envelope from `seqd`.\n\nOn `ok=false`, command exits non-zero after printing the response JSON.\n","isInternal":false,"tokens":335,"sizeBytes":1170},{"name":"services.md","path":"docs/commands/services.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/services.md","title":"Command: /services","category":"command-prompt","format":"markdown","content":"# f services\n\nGuided setup flows for third-party services. These commands prompt for required\nenv vars, store them in cloud, and can optionally apply them to Cloudflare.\n\n## Stripe\n\n```bash\nf services stripe\n```\n\n### Options\n\n- `--path <PATH>`: target project root (defaults to current directory).\n- `--environment <ENV>`: env store to write (default: flow.toml or `production`).\n- `--mode <test|live>`: Stripe mode (default: `test`).\n- `--force`: prompt even if keys are already set.\n- `--apply` / `--no-apply`: apply envs to Cloudflare after setup.\n\n### What it prompts for\n\nThe command inspects `flow.toml` `[cloudflare].env_keys` and asks for Stripe\nkeys found there (fallback order):\n\n- `STRIPE_SECRET_KEY`\n- `STRIPE_WEBHOOK_SECRET`\n- `STRIPE_PRO_PRICE_ID`\n- `STRIPE_REFILL_PRICE_ID`\n- `VITE_STRIPE_PUBLISHABLE_KEY`\n\n### Helpful Stripe sources\n\n- Secret/Publishable keys: Stripe Dashboard -> Developers -> API keys\n- Webhook signing secret: Stripe Dashboard -> Developers -> Webhooks (or `stripe listen --print-secret`)\n- Price IDs: Stripe Dashboard -> Products -> Price (starts with `price_`)\n\n### Example\n\n```bash\ncd ~/org/gen/new\nf services stripe --mode test --apply\n```\n","isInternal":false,"tokens":309,"sizeBytes":1180},{"name":"setup.md","path":"docs/commands/setup.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/setup.md","title":"Command: /setup","category":"command-prompt","format":"markdown","content":"# f setup\n\nBootstrap the project if needed, generate a `flow.toml` if missing, then run the `setup` task or print shell aliases.\n\n## Quick Start\n\n```bash\n# Bootstrap if missing, generate flow.toml if missing, then run setup task or print aliases\nf setup\n\n# Configure host deployment (Linux)\nf setup deploy\n\n# Configure release hosting for server projects\nf setup release\n\n# Use a specific config file\nf setup --config ./flow.toml\n```\n\n## Behavior\n\n- If the project is not bootstrapped, it runs the bootstrap flow (`.ai/`, `.gitignore`).\n- If `flow.toml` is missing, it prompts to generate `setup` + `dev` tasks (AI via `gen` if available, otherwise manual prompts).\n- If `flow.toml` already exists, Flow non-destructively appends missing Codex baseline sections (`[skills]`, `[skills.codex]`, commit skill gate, and Bun testing gate in Bun contexts).\n- After baseline upgrades, Flow triggers a Codex skills reload (respecting `[skills.codex].force_reload_after_sync`) so open sessions pick up changes immediately.\n- If `flow.toml` defines a `setup` task, `f setup` runs that task.\n- After the `setup` task exits, Flow re-reads `flow.toml`, re-syncs task skills to `.ai/skills`, and reloads Codex skills (when configured). This makes setup-generated task changes visible to Claude/Codex immediately.\n- Otherwise, it prints shell aliases from `[alias]` in `flow.toml`.\n- `f setup deploy` adds a `[host]` section, creates a remote setup script, copies env templates, and optionally stores the deploy host.\n- `f setup release` detects server projects and offers Linux host deployment defaults.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`) |\n| `TARGET` | Optional setup target (e.g., `deploy`, `release`) |\n\n### Global Server Setup Defaults\n\nYou can provide a server template in your global config at `~/.config/flow/flow.toml`:\n\n```toml\n[setup.server]\ntemplate = \"~/infra/flow.toml\"\n```\n\nOr inline host defaults:\n\n```toml\n[setup.server.host]\nsetup = \"\"\"#!/usr/bin/env bash\nset -euo pipefail\n...\"\"\"\nenv_file = \".env.host\"\nport = 3000\n```\n","isInternal":false,"tokens":535,"sizeBytes":2118},{"name":"skills.md","path":"docs/commands/skills.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/skills.md","title":"Command: /skills","category":"command-prompt","format":"markdown","content":"# f skills\n\nManage Codex/Claude skills for the current project.\n\nSkills live in `.ai/skills/` and are symlinked to `.codex/skills` and `.claude/skills` so active agent sessions can discover them.\n\n## Core Commands\n\n```bash\n# List local skills\nf skills\n\n# Create/edit/remove skills\nf skills new <name> -d \"description\"\nf skills edit <name>\nf skills remove <name>\n\n# Install curated skills\nf skills install <name>\n\n# Generate one skill per flow.toml task\nf skills sync\n\n# Force Codex app-server to rescan skills for this cwd\nf skills reload\n```\n\n## Codex Tight Feedback Loop\n\nUse this loop when coding with Codex/Claude:\n\n1. Make code changes.\n2. Run focused tests quickly (in Bun repos: `bun bd test ...`).\n3. Refresh skill context:\n\n```bash\nf skills sync\nf skills reload\n```\n\n4. Commit via quality gates:\n\n```bash\nf commit\n```\n\n`f skills reload` is useful for already-open Codex sessions; it refreshes the app-server skill cache without creating a new session.\n\n## `flow.toml` Settings\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n```\n\n## Built-in Default Skills\n\nFlow auto-materializes a small baseline set of project-local skills in `.ai/skills/`:\n\n- `env`\n- `quality-bun-feature-delivery`\n- `pr-markdown-body-file`\n\nThese are symlinked into `.codex/skills` and `.claude/skills` and can be reloaded with:\n\n```bash\nf skills reload\n```\n\n### `skills.codex` fields\n\n- `generate_openai_yaml`: writes `.ai/skills/<task>/agents/openai.yaml` for task-synced skills.\n- `force_reload_after_sync`: after `f skills sync` or `f skills install`, force Codex app-server `skills/list` with `forceReload: true`.\n- `task_skill_allow_implicit_invocation`: default `policy.allow_implicit_invocation` value in generated `agents/openai.yaml`.\n\n## Recommended Enforcement\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\nThis blocks commits that skip required Bun-oriented testing/skill policy.\n","isInternal":false,"tokens":612,"sizeBytes":2368},{"name":"sync.md","path":"docs/commands/sync.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/sync.md","title":"Command: /sync","category":"command-prompt","format":"markdown","content":"# f sync\n\nSync git repo: pull from tracking remote, merge upstream changes, optionally push.\n\n## Overview\n\nSingle command to bring a repository up to date. Pulls from the tracking branch, syncs upstream if configured (fork workflow), and optionally pushes. Works with both plain git and jj (jujutsu) colocated repos.\n\n## Context Card\n\nUse this block when passing `f sync` behavior to another agent:\n\n- Default behavior: pull/sync only; push is off unless `--push`.\n- Defaults: `--stash=true`, `--fix=true`.\n- Modes: uses jj flow in healthy colocated workspaces, falls back to plain git when needed.\n- Home-branch mode: when the current branch matches `jj.home_branch`, `f sync` skips the normal tracking pull and syncs `origin/<default-branch>` into that branch.\n- Push target: configured `[git].remote` first, then standard fallback behavior.\n- Clipboard output: synced commit list is copied only when remote commit ranges are detected (typically jj fetch path).\n- Conflict note: jj can finish with unresolved conflicts and prints `jj resolve` guidance.\n\n## Quick Start\n\n```bash\n# Pull latest from remote (no push by default)\nf sync\n\n# Pull and push\nf sync --push\n\n# Pull with rebase instead of merge\nf sync -r\n\n# Pull with rebase and push\nf sync -r --push\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--rebase` | `-r` | Use rebase instead of merge when pulling |\n| `--push` | | Push to configured git remote after sync (default: off) |\n| `--no-push` | | Skip pushing (legacy; already the default) |\n| `--stash` | `-s` | Auto-stash uncommitted changes (default: true) |\n| `--stash-commits` | | Stash local JJ commits to a bookmark before syncing (jj only) |\n| `--allow-queue` | | Allow sync even when commit queue is non-empty |\n| `--create-repo` | | Create origin repo on GitHub if it doesn't exist |\n| `--fix` | `-f` | Auto-fix conflicts using Claude (default: true) |\n| `--no-fix` | | Disable auto-fix |\n| `--max-fix-attempts <N>` | | Maximum auto-fix attempts (default: 3) |\n| `--allow-review-issues` | | Allow push even if P1/P2 review todos are open |\n| `--compact` | | Legacy noise-reduction flag (jj fetch output is already compact by default) |\n\n## What Happens\n\n### Step 1: Pre-flight checks\n\n1. Detects if jj is available and healthy; falls back to git if not\n2. Checks for unmerged files and resolves them (or prompts)\n3. Handles in-progress rebase/merge\n4. Stashes uncommitted changes if `--stash` is set\n\n### Step 2: Pull from tracking branch\n\nPulls from the tracking remote/branch (e.g. `origin/main`). If the branch has no tracking info but the push remote has a matching branch, auto-configures tracking.\n\n- With `--rebase`: runs `git pull --rebase`\n- Without: runs `git pull --no-rebase --no-edit` (merge without opening an editor)\n- Auto-resolves conflicts when `--fix` is enabled\n\n### Step 3: Sync upstream\n\nIf an `upstream` remote exists (fork workflow), fetches and merges upstream changes into the current branch.\n\nIf no `upstream` remote but on a feature branch, syncs from `origin/<default-branch>` (e.g. `origin/main`) into the current branch.\n\n### Home-branch mode\n\nIf the current branch matches the resolved `jj.home_branch`, Flow treats that branch as your\nlong-lived integration branch.\n\nIn that mode, `f sync`:\n\n- skips the normal tracking-branch pull\n- leaves branch tracking config untouched\n- syncs `origin/<default-branch>` into the home branch\n- keeps all non-home branches on the existing sync behavior\n\nHome-branch resolution order is:\n\n1. `<repo>/flow.toml` `jj.home_branch`\n2. `~/.config/flow/flow.toml` `jj.home_branch`\n3. basename of `$HOME`\n4. `USER` or `USERNAME`\n\n### Step 4: Push (optional)\n\nOnly when `--push` is passed:\n\n- Detects fork push targets (redirects to private fork remote if configured)\n- Checks review-todo gate (blocks if P1/P2 issues are open unless `--allow-review-issues`)\n- Skips push if the push remote equals upstream (read-only clone)\n- Creates repo with `--create-repo` if origin doesn't exist\n\n### Step 5: Restore stash\n\nRestores auto-stashed changes if any were stashed in step 1.\n\n### Step 6: Synced commit list + clipboard\n\nWhen remote commit ranges are discovered (typically during jj fetch), Flow prints a deduplicated\nlist of newly synced commits (hash + subject) and copies that same list to your clipboard.\n\nIf no synced commit ranges were detected, this section is skipped.\n\nSet `FLOW_NO_CLIPBOARD=1` to disable clipboard copy.\n\n## JJ (Jujutsu) Support\n\nWhen a `.jj` directory is present and healthy, sync uses the jj flow instead of plain git. Falls back to git if:\n\n- Configured `git.remote` is not `origin`/`upstream`\n- Tracking remote is a custom remote\n- jj workspace is unhealthy or corrupt\n\nUse `--stash-commits` to bookmark local jj commits before syncing.\n\njj fetch output is compact by default; synced commit details are emitted once at the end for clipboard use.\n\n## Commit Queue Guard\n\nIf the commit queue has pending entries and sync would rebase (rewriting SHAs), sync refuses to proceed. Use `--allow-queue` to override, or process the queue first with `f commit-queue list`.\n\n## Configuration\n\n### Push remote\n\nSet in `flow.toml` under `[git]`:\n\n```toml\n[git]\nremote = \"origin\"  # default push remote\n\n[jj]\nhome_branch = \"alice\" # optional long-lived personal integration branch\n```\n\n### Fork push\n\nWhen a fork push target is configured, sync redirects push to the fork remote automatically.\n\n## Examples\n\n```bash\n# Basic sync (pull only)\nf sync\n\n# Sync and push\nf sync --push\n\n# Rebase workflow\nf sync -r --push\n\n# Sync a fork (has upstream remote)\nf sync --push\n\n# Create missing origin and push\nf sync --push --create-repo\n\n# Skip auto-fix for conflicts\nf sync --no-fix\n\n# Allow sync with pending commit queue\nf sync --allow-queue\n```\n\n## Troubleshooting\n\n### \"Unmerged files detected\"\n\nSync found files with unresolved merge conflicts. By default (`--fix`), it tries to auto-resolve. If that fails, resolve manually:\n\n```bash\ngit status                # see conflicted files\n# edit and fix conflicts\ngit add <files>\nf sync                    # retry\n```\n\n### \"Commit queue is not empty\"\n\nRebase-based sync can rewrite commit SHAs, breaking queued commits. Either:\n\n```bash\nf commit-queue list       # review the queue\nf sync --allow-queue      # override the guard\n```\n\n### \"Remote unreachable\"\n\nThe push remote doesn't exist or auth/network failed. For missing origin:\n\n```bash\nf sync --push --create-repo\n```\n\n### jj corruption fallback\n\nIf jj sync fails due to workspace/store issues, sync automatically retries with plain git. Fix jj with:\n\n```bash\njj git import\n# or if still broken:\nrm -rf .jj && jj git init --colocate\n```\n\n### \"Sync complete (jj) but conflicts remain\"\n\nThis means sync/rebase completed but conflict revisions still exist in jj.\n\n```bash\njj resolve\n```\n\n## See Also\n\n- [upstream](upstream.md) - Manage upstream fork workflow\n- [commit](commit.md) - Commit changes\n- [jj](jj.md) - Jujutsu workflow helpers\n","isInternal":false,"tokens":1742,"sizeBytes":6970},{"name":"tasks.md","path":"docs/commands/tasks.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/tasks.md","title":"Command: /tasks","category":"command-prompt","format":"markdown","content":"# f tasks\n\nList and discover project tasks from:\n\n- `flow.toml` (`[[tasks]]`)\n- `.ai/tasks/*.mbt` (AI MoonBit tasks)\n\nYou can run tasks directly with `f <task>`.\n\n## Usage\n\n```bash\nf tasks\nf tasks list\nf tasks dupes\nf tasks init-ai\nf tasks build-ai ai:flow/dev-check\nf tasks run-ai ai:flow/dev-check\nf tasks run-ai --daemon ai:flow/dev-check\nf tasks daemon start\nf tasks daemon status\nf tasks daemon stop\nf ai-taskd-launchd-install\nf ai-taskd-launchd-status\ncargo build --release -p ai-taskd-client --bin ai-taskd-client\n./target/release/ai-taskd-client ai:flow/dev-check\nf install-ai-fast-client\nf fast ai:flow/dev-check\nf bench-ai-runtime --iterations 80 --warmup 10\nf bench-ffi-boundary --iters 10000000\nf bench-ffi-boundary --iters 10000000 --native-opt\n```\n\n## AI Task Workflow\n\nInitialize a starter MoonBit task:\n\n```bash\nf tasks init-ai\n```\n\nThis creates:\n\n```text\n.ai/tasks/starter.mbt\n```\n\nRun it:\n\n```bash\nf starter\nf ai:starter\n```\n\nAdd more tasks as `.mbt` files under `.ai/tasks/` and run by name or selector:\n\n```bash\nf release-flow\nf ai:project/release-flow\n```\n\n## Notes\n\n- Default execution mode is cached native binary:\n  1) `moon build --target native --release` once per content hash\n  2) run cached artifact from `~/Library/Caches/flow/ai-tasks/...`\n- Use `f tasks run-ai --no-cache ...` (or `FLOW_AI_TASK_RUNTIME=moon-run`) to force direct `moon run`.\n- Set `FLOW_AI_TASK_MODE=release` for release builds (`--release`).\n- Set `FLOW_AI_TASK_MODE=js` to run with JS target.\n- `f tasks daemon` runs a lightweight local `ai-taskd` over Unix socket for warm repeated runs.\n- For lowest invocation overhead, use the tiny client binary against the daemon:\n- `cargo build --release -p ai-taskd-client --bin ai-taskd-client`\n  - `./target/release/ai-taskd-client ai:<selector>`\n  - or `f install-ai-fast-client` then use `fai ai:<selector>`\n  - This bypasses full `f` startup for hot-loop calls.\n- `fai` supports:\n  - `--protocol msgpack|json` (msgpack default)\n  - `--timings` (server-side phase timings)\n  - `--batch-stdin` (pooled burst mode in one client process)\n- For stable startup/jitter, prefer always-on daemon via launchd:\n  - `f ai-taskd-launchd-install`\n  - `f ai-taskd-launchd-status`\n  - `f ai-taskd-launchd-logs`\n- Automatic preference for latency-critical AI selectors:\n  - Opt in with `FLOW_AI_TASK_FAST_CLIENT=1` (typically together with `FLOW_AI_TASK_DAEMON=1`).\n  - Then `f` will auto-prefer fast client dispatch for AI tasks tagged `fast`, `latency`, `hot`, or `hotkey`.\n  - Override selector matching with `FLOW_AI_TASK_FAST_SELECTORS` (comma-separated patterns, supports `*` prefix/suffix).\n  - Override client binary with `FLOW_AI_TASK_FAST_CLIENT_BIN=/path/to/fai`.\n- `f recipe` still exists for legacy compatibility, but task-centric workflow is preferred.\n","isInternal":false,"tokens":784,"sizeBytes":2797},{"name":"up.md","path":"docs/commands/up.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/up.md","title":"Command: /up","category":"command-prompt","format":"markdown","content":"# f up\n\nBring a project up using lifecycle conventions.\n\n## Quick Start\n\n```bash\n# Run lifecycle up (tries task \"up\", then \"dev\")\nf up\n\n# Pass args through to the selected task\nf up -- --port 3001\n```\n\n## Behavior\n\n- Loads nearest `flow.toml` (or `--config` path).\n- If `[lifecycle.domains]` is configured:\n  - runs `f domains add <host> <target> --replace`\n  - runs `f domains up` (with configured engine when set)\n- Runs lifecycle task:\n  - `[lifecycle].up_task` when configured\n  - otherwise fallback order: `up`, then `dev`\n\nIf no up task is found, command fails with guidance.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`, searches upward when default is missing) |\n| `ARGS...` | Extra args passed to the selected lifecycle task |\n\n## Recommended myflow config\n\n```toml\n[lifecycle]\nup_task = \"dev\"\n\n[lifecycle.domains]\nhost = \"myflow.localhost\"\ntarget = \"127.0.0.1:3000\"\nengine = \"native\"\nremove_on_down = false\nstop_proxy_on_down = false\n```\n","isInternal":false,"tokens":286,"sizeBytes":1032},{"name":"upstream.md","path":"docs/commands/upstream.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/upstream.md","title":"Command: /upstream","category":"command-prompt","format":"markdown","content":"# f upstream\n\nManage upstream fork workflow.\n\n## Overview\n\nSet up and sync forks with their upstream repositories. Creates a local `upstream` branch to cleanly track the original repo, making merges easier.\n\n## Quick Start\n\n```bash\n# Set up upstream tracking\nf upstream setup --upstream-url https://github.com/original/repo\n\n# Pull latest from upstream\nf upstream pull\n\n# Full sync: pull, merge, push\nf upstream sync\n```\n\n## Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `status` | Show current upstream configuration |\n| `setup` | Set up upstream remote and local tracking branch |\n| `pull` | Pull changes from upstream into local 'upstream' branch |\n| `sync` | Full sync: pull upstream, merge to dev/main, push to origin |\n\n---\n\n## Setup\n\nConfigure upstream tracking for a forked repository:\n\n```bash\n# Basic setup\nf upstream setup --upstream-url https://github.com/original/repo\n\n# Specify branch (if not main)\nf upstream setup --upstream-url https://github.com/original/repo --upstream-branch master\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--upstream-url <URL>` | `-u` | URL of the upstream repository |\n| `--upstream-branch <BRANCH>` | `-b` | Branch name on upstream (default: auto-detected) |\n\n### What Happens\n\n1. Adds `upstream` remote pointing to original repo\n2. Fetches upstream branches\n3. Creates local `upstream` branch tracking the upstream's default branch\n4. Stores configuration in `.git/config`\n\n---\n\n## Pull\n\nPull latest changes from upstream into local `upstream` branch:\n\n```bash\n# Pull into upstream branch\nf upstream pull\n\n# Pull and also merge into specific branch\nf upstream pull --branch main\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--branch <BRANCH>` | `-b` | Also merge into this branch after pulling |\n\n---\n\n## Sync\n\nFull sync workflow - pulls upstream, merges to your branch, and pushes:\n\n```bash\n# Full sync (pull, merge, push)\nf upstream sync\n\n# Sync without pushing (for review first)\nf upstream sync --no-push\n```\n\n### Options\n\n| Option | Description |\n|--------|-------------|\n| `--no-push` | Skip pushing to origin |\n\n### What Happens\n\n1. Stashes any uncommitted changes\n2. Fetches latest from upstream\n3. Updates local `upstream` branch\n4. Merges upstream into your current branch (e.g., `main`)\n5. Pushes to origin (unless `--no-push`)\n6. Restores stashed changes\n\n### Branch Detection\n\nFlow auto-detects the upstream default branch:\n- Checks `refs/remotes/upstream/HEAD`\n- Falls back to checking if `upstream/main` or `upstream/master` exists\n- Uses `main` as final fallback\n\n---\n\n## Status\n\nShow current upstream configuration:\n\n```bash\nf upstream status\n```\n\nOutput:\n```\nUpstream Configuration\n  Remote: https://github.com/original/repo\n  Branch: main\n  Local tracking: upstream -> upstream/main\n  Last sync: 2 hours ago\n```\n\n---\n\n## Workflow Example\n\n### Initial Fork Setup\n\n```bash\n# 1. Clone your fork\ngit clone https://github.com/youruser/project\ncd project\n\n# 2. Set up upstream tracking\nf upstream setup --upstream-url https://github.com/original/project\n\n# 3. Verify\nf upstream status\n```\n\n### Regular Sync\n\n```bash\n# When you want to sync with upstream:\nf upstream sync\n\n# Or if you want to review before pushing:\nf upstream sync --no-push\ngit log --oneline main..upstream  # See what's new\ngit push  # Push when ready\n```\n\n### Handling Conflicts\n\nIf sync encounters merge conflicts:\n\n```bash\n$ f upstream sync\nMerging upstream into main...\nCONFLICT (content): Merge conflict in src/lib.rs\n\n# Fix conflicts manually\nvim src/lib.rs\ngit add src/lib.rs\ngit commit\n\n# Then push\ngit push\n```\n\n---\n\n## Configuration\n\nUpstream configuration is stored in `.git/config`:\n\n```ini\n[remote \"upstream\"]\n    url = https://github.com/original/repo\n    fetch = +refs/heads/*:refs/remotes/upstream/*\n\n[branch \"upstream\"]\n    remote = upstream\n    merge = refs/heads/main\n```\n\nYou can also manually configure:\n\n```bash\ngit remote add upstream https://github.com/original/repo\ngit fetch upstream\ngit branch upstream upstream/main\n```\n\n---\n\n## Troubleshooting\n\n### \"upstream remote not found\"\n\nRun `f upstream setup` first with the upstream URL.\n\n### \"git stash pop failed\"\n\nThis can happen if there were no changes to stash. Flow handles this automatically by tracking stash state.\n\n### Upstream uses master instead of main\n\nFlow auto-detects the default branch. If detection fails, specify explicitly:\n\n```bash\nf upstream setup --upstream-url https://github.com/original/repo --upstream-branch master\n```\n\n### Merge conflicts\n\nResolve conflicts manually:\n1. Fix conflicting files\n2. `git add <files>`\n3. `git commit`\n4. `git push`\n\n## See Also\n\n- [commit](commit.md) - Commit changes after sync\n- [publish](publish.md) - Publish to GitHub\n","isInternal":false,"tokens":1170,"sizeBytes":4786},{"name":"url.md","path":"docs/commands/url.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/url.md","title":"Command: /url","category":"command-prompt","format":"markdown","content":"# `f url`\n\nInspect or crawl URLs into compact AI-friendly summaries.\n\n## Quick Start\n\n```bash\n# Thin single-page summary\nf url inspect https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\n\n# Force Cloudflare Browser Rendering markdown\nf url inspect --provider cloudflare https://developers.cloudflare.com/changelog/post/2026-03-10-br-crawl-endpoint/\n\n# Machine-readable output\nf url inspect --json https://linear.app/example-workspace/project/example-project-v1-1234567890ab/overview\n\n# Explicit site crawl (Cloudflare Browser Rendering)\nf url crawl https://developers.cloudflare.com/browser-rendering/rest-api/crawl-endpoint/ --limit 3 --records 2\n```\n\n## `inspect`\n\n`f url inspect <url>` uses this provider order:\n\n1. Cloudflare Browser Rendering markdown\n2. configured scraper backend from `[skills.seq]`\n3. direct fetch fallback\n\nDefault output is intentionally compact:\n\n- title\n- URL\n- content type\n- short description\n- short excerpt\n\nUse `--full` to include the full markdown/content body.\n\n## `crawl`\n\n`f url crawl <url>` is the explicit multi-page path.\n\nIt currently uses Cloudflare Browser Rendering crawl and polls until the job completes or the wait timeout is reached.\n\nUseful flags:\n\n```bash\nf url crawl <url> --limit 10 --records 5\nf url crawl <url> --depth 2 --render\nf url crawl <url> --include-pattern \"https://developers.cloudflare.com/browser-rendering/*\"\nf url crawl <url> --exclude-pattern \"*/changelog/*\"\nf url crawl <url> --json\n```\n\nDefaults are tuned to stay small:\n\n- `--limit 10`\n- `--depth 2`\n- `--records 5`\n- `--render false`\n\n## Auth\n\nCloudflare auth is read from:\n\n1. shell env\n2. Flow personal env store fallback\n\nRequired keys:\n\n- `CLOUDFLARE_ACCOUNT_ID`\n- `CLOUDFLARE_API_TOKEN`\n\nNo daemon is required.\n\n## Config\n\nIf you have a local scraper backend, `f url inspect` reuses `[skills.seq]` settings from repo `flow.toml` or global `~/.config/flow/flow.toml`:\n\n```toml\n[skills.seq]\nscraper_base_url = \"http://127.0.0.1:7444\"\nscraper_api_key = \"...\"\ncache_ttl_hours = 2\nallow_direct_fallback = true\n```\n","isInternal":false,"tokens":534,"sizeBytes":2065},{"name":"web.md","path":"docs/commands/web.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/docs/commands/web.md","title":"Command: /web","category":"command-prompt","format":"markdown","content":"# web\n\nOpen the Flow web UI for the current project.\n\n## Usage\n\n```bash\nf web\n```\n\n## What it does\n\n- Serves the `.ai/web` UI for the current project.\n- Exposes `/api/projects` for project metadata and top-level `.ai` entries.\n- Exposes `/api/ai` for the full `.ai` tree (paths + kinds).\n- Exposes `/api/sessions` for Claude/Codex session summaries and transcripts.\n- Exposes `/api/openapi` when an OpenAPI spec is detected.\n\n## Options\n\n```bash\n--host <host>   Host to bind (default: 127.0.0.1)\n--port <port>   Port to serve the UI on (default: 9310)\n```\n\n## Notes\n\n- `f web` serves `.ai/web/dist` when it exists (Vite default output).\n- The Vite app source lives in `.ai/web`.\n- `.ai/web` is gitignored by default so AI can freely rewrite it.\n- If no build exists, `f web` shows a minimal placeholder.\n- Example build: `vite build` from `.ai/web`.\n- `f web` now runs `bun install` (once) and `bun run build` automatically when a Vite app is present.\n","isInternal":false,"tokens":275,"sizeBytes":952},{"name":"readme.md","path":"tools/domainsd-cpp/readme.md","rawUrl":"https://raw.githubusercontent.com/nikivdev/flow/HEAD/tools/domainsd-cpp/readme.md","title":"domainsd-cpp Documentation","category":"plugin-manifest","format":"markdown","content":"# domainsd-cpp (experimental)\n\n`domainsd-cpp` is an experimental native local-domains proxy used by:\n\n- `f domains --engine native up`\n- `f domains --engine native down`\n\nIt is designed for low overhead on localhost routing and keeps Flow route state in:\n\n- `~/.config/flow/local-domains/routes.json`\n\nCurrent scope:\n- HTTP/1.1 host-based routing (`*.localhost` -> `host:port`)\n- WebSocket upgrade passthrough (full duplex tunnel)\n- request-side chunked transfer-encoding decode/forward\n- upstream keepalive connection pooling (safe framed-response reuse)\n- overload shedding with bounded active client handlers (`503` when saturated)\n- upstream connect/IO timeouts (`504` for connect timeout)\n- health endpoint: `GET /_flow/domains/health`\n- mtime-based route reload (no daemon restart required)\n- optional macOS launchd socket activation (`--launchd-socket <name>`) for privileged `:80` bind without Docker\n\nRuntime tuning:\n- daemon supports CLI flags (`--max-active-clients`, `--upstream-*-timeout-ms`, `--pool-*`)\n- Flow passes tuning via env vars prefixed `FLOW_DOMAINS_NATIVE_*`\n\nCurrent limitations:\n- no HTTP/2/TLS yet\n\nThe Flow CLI builds this binary automatically with `clang++` when needed.\n\n## macOS native `:80` without Docker\n\nWhen direct bind to `127.0.0.1:80` is blocked by permissions, install launchd socket mode once:\n\n```bash\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nThis installs `dev.flow.domainsd` in `/Library/LaunchDaemons`, binds port `80` via launchd, and runs `domainsd-cpp` as your user with inherited socket fd.\n\nUninstall:\n\n```bash\nsudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh\n```\n","isInternal":false,"tokens":401,"sizeBytes":1635},{"name":".cursorrules","path":".cursorrules (gitflow.mdc)","rawUrl":"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/gitflow.mdc","title":"Gitflow Workflow Rules. These rules should be applied when performing git operations.","category":"cursor-rule","format":"markdown","content":"# Gitflow Workflow Rules\n\n## Main Branches\n\n### main (or master)\n- Contains production-ready code\n- Never commit directly to main\n- Only accepts merges from:\n  - hotfix/* branches\n  - release/* branches\n- Must be tagged with version number after each merge\n\n### develop\n- Main development branch\n- Contains latest delivered development changes\n- Source branch for feature branches\n- Never commit directly to develop\n\n## Supporting Branches\n\n### feature/*\n- Branch from: develop\n- Merge back into: develop\n- Naming convention: feature/[issue-id]-descriptive-name\n- Example: feature/123-user-authentication\n- Must be up-to-date with develop before creating PR\n- Delete after merge\n\n### release/*\n- Branch from: develop\n- Merge back into: \n  - main\n  - develop\n- Naming convention: release/vX.Y.Z\n- Example: release/v1.2.0\n- Only bug fixes, documentation, and release-oriented tasks\n- No new features\n- Delete after merge\n\n### hotfix/*\n- Branch from: main\n- Merge back into:\n  - main\n  - develop\n- Naming convention: hotfix/vX.Y.Z\n- Example: hotfix/v1.2.1\n- Only for urgent production fixes\n- Delete after merge\n\n## Commit Messages\n\n- Format: `type(scope): description`\n- Types:\n  - feat: New feature\n  - fix: Bug fix\n  - docs: Documentation changes\n  - style: Formatting, missing semicolons, etc.\n  - refactor: Code refactoring\n  - test: Adding tests\n  - chore: Maintenance tasks\n\n## Version Control\n\n### Semantic Versioning\n- MAJOR version for incompatible API changes\n- MINOR version for backwards-compatible functionality\n- PATCH version for backwards-compatible bug fixes\n\n## Pull Request Rules\n\n1. All changes must go through Pull Requests\n2. Required approvals: minimum 1\n3. CI checks must pass\n4. No direct commits to protected branches (main, develop)\n5. Branch must be up to date before merging\n6. Delete branch after merge\n\n## Branch Protection Rules\n\n### main & develop\n- Require pull request reviews\n- Require status checks to pass\n- Require branches to be up to date\n- Include administrators in restrictions\n- No force pushes\n- No deletions\n\n## Release Process\n\n1. Create release branch from develop\n2. Bump version numbers\n3. Fix any release-specific issues\n4. Create PR to main\n5. After merge to main:\n   - Tag release\n   - Merge back to develop\n   - Delete release branch\n\n## Hotfix Process\n\n1. Create hotfix branch from main\n2. Fix the issue\n3. Bump patch version\n4. Create PR to main\n5. After merge to main:\n   - Tag release\n   - Merge back to develop\n   - Delete hotfix branch","frontmatter":{"description":"Gitflow Workflow Rules. These rules should be applied when performing git operations.","globs":["**/*"],"alwaysApply":false},"tokens":642,"sizeBytes":2493}],"systemPromptSnippet":"<yakaai_skills repo=\"nikivdev/flow\">\n<!-- File: .ai/agents.md (Tokens: ~369 | Category: root-instruction) -->\n# Autonomous Agent Instructions\n\nProject: flow\n\nThis project is configured for autonomous AI agent workflows with human-in-the-loop approval.\n\n## Response Format\n\n**Every response MUST end with exactly one of these signals on the final line:**\n\n### Success signals\n\n```\ndone.\n```\nUse when task completed successfully with high certainty. No further action needed.\n\n```\ndone: <message>\n```\nUse when task completed with context to share. Example: `done: Added login command with --token flag`\n\n### Needs human input\n\n```\nneedsUpdate: <message>\n```\nUse when you need human decision or action. Example: `needsUpdate: Should I use OAuth or API key auth?`\n\n### Error signals\n\n```\nerror: <message>\n```\nUse when task failed or cannot proceed. Example: `error: Build failed - missing dependency xyz`\n\n## Rules\n\n1. **Always end with a signal** - The last line must be one of the above\n2. **One signal only** - Never combine signals\n3. **Be specific** - Include actionable context in messages\n4. **No quotes** - Write signals exactly as shown, no wrapping quotes\n\n## Examples\n\n### Successful implementation\n```\nAdded the new CLI command with all requested flags.\n\ndone.\n```\n\n### Completed with context\n```\nRefactored the auth module to use the new token format.\n\ndone: Auth now supports both JWT and API key methods\n```\n\n### Need human decision\n```\nFound two approaches for caching:\n1. Redis - better for distributed systems\n2. In-memory - simpler, faster for single instance\n\nneedsUpdate: Which caching approach should I use?\n```\n\n### Error occurred\n```\nAttempted to run tests but encountered issues.\n\nerror: Test suite requires DATABASE_URL environment variable\n```\n\n<!-- File: agents.md (Tokens: ~349 | Category: root-instruction) -->\n# Assistant Rules (flow)\n\nOnly load skills when the request clearly needs them.\n\n## Skills (on-demand)\n- flow-native: Use for Flow CLI native workflows (env setup, secrets, deploys, logs, deps), for repos with `flow.toml`, or Cloudflare Workers. Avoid direct pnpm/wrangler unless asked.\n- flow-interactive: Use when commands are interactive or could block on stdin (e.g., `f setup`).\n- flow-dev-traces: Use when debugging Flow proxy behavior, tracing requests, or when the user asks about proxyx, trace-summary.json, or flow trace commands.\n- flow-usage: Use when running or troubleshooting Flow command behavior.\n- internal-ai-inference: Use only when asked to run inference or integrate with internal AI tooling.\n\nDefault: Avoid loading skills for routine edits, reviews, or simple questions.\n\n## Deploy / Restart Policy\n\n- When changes affect the installed Flow CLI or built-in Codex daemon path,\n  prefer an explicit deploy + daemon reload instead of leaving runtime state\n  stale.\n- Use `deploy-with-codexd-reload` after edits in areas like `src/ai.rs`,\n  `src/codexd.rs`, `src/daemon.rs`, `src/supervisor.rs`, or `src/config.rs`\n  when those changes affect Codex runtime, daemon behavior, or Flow-managed\n  session recovery.\n- Use `deploy-with-hub-reload` for hub-facing changes that need `lin` / docs\n  processes refreshed.\n- For `codexd`, prefer explicit `stop` + `start` in automation over a single\n  restart command so the stop/start boundary is visible in logs.\n\n<!-- File: .ai/skills/env/skill.md (Tokens: ~1034 | Category: anthropic-skill) -->\n---\nname: env\ndescription: Manage environment variables and secrets with flow (always use Flow env store)\nsource: flow-default\n---\n\n# Environment Variables & Secrets\n\nFlow provides a secure way to manage environment variables across projects.\n\n## Rules (Must)\n\n- Always use Flow env store for secrets/tokens in Flow projects.\n- Do not rely on shell env vars or `.env` files for secrets unless they are injected via `f env`.\n- For tasks/scripts that need secrets, fetch them with `f env get` or run via `f env run`.\n\n## Setup\n\n### 1. Define variables in flow.toml\n\nAdd a `[storage]` section to your project's `flow.toml`:\n\n```toml\n[storage]\nprovider = \"myflow.sh\"\n\n[[storage.envs]]\nname = \"local\"\ndescription = \"Local development\"\nvariables = [\n  { key = \"DATABASE_URL\" },\n  { key = \"API_KEY\" },\n  { key = \"SECRET_TOKEN\", default = \"\" },\n]\n```\n\n### 2. Set environment variables\n\nUse `f env set` to store values:\n\n```bash\n# Set individual env vars\nf env set API_KEY=abc123\nf env set DATABASE_URL=\"postgres://...\"\n\n# Values are stored in ~/.config/flow/env-local/personal/production.env\n```\n\n### 3. Pull env vars to local .env\n\n```bash\n# Pull all env vars for the current environment\nf env pull\n\n# Show current env vars\nf env list\n\n# Get specific var\nf env get API_KEY\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `f env set KEY=value` | Store an env var |\n| `f env pull` | Pull env vars to local .env file |\n| `f env push` | Push local .env to cloud |\n| `f env list` | List env vars for this project |\n| `f env get KEY` | Get specific env var(s) |\n| `f env keys` | Show configured env keys from flow.toml |\n| `f env setup` | Interactive env setup |\n| `f env guide` | Guided prompt to set required vars |\n| `f env run <cmd>` | Run command with env vars injected |\n\n## Environment Selection\n\nFlow supports multiple environments:\n\n```toml\n[[storage.envs]]\nname = \"local\"\nvariables = [{ key = \"DATABASE_URL\" }]\n\n[[storage.envs]]\nname = \"staging\"\nvariables = [{ key = \"DATABASE_URL\" }]\n\n[[storage.envs]]\nname = \"production\"\nvariables = [{ key = \"DATABASE_URL\" }]\n```\n\n## Example: Spotify CLI\n\n```toml\n[storage]\nprovider = \"myflow.sh\"\n\n[[storage.envs]]\nname = \"local\"\ndescription = \"Spotify API credentials\"\nvariables = [\n  { key = \"SPOTIFY_CLIENT_ID\" },\n  { key = \"SPOTIFY_CLIENT_SECRET\" },\n  { key = \"SPOTIFY_ACCESS_TOKEN\" },\n  { key = \"SPOTIFY_REFRESH_TOKEN\", default = \"\" },\n]\n```\n\nThen:\n```bash\n# Set your credentials (example values)\nf env set SPOTIFY_CLIENT_ID=example_client_id\nf env set SPOTIFY_CLIENT_SECRET=example_client_secret\n\n# Run CLI with env vars injected\nf env run bun run src/main.ts now\n\n# Or pull to .env first\nf env pull\nsource .env\nbun run src/main.ts now\n```\n\n## Task pattern (required for secrets)\n\nWhen writing Flow tasks, prefer:\n\n```bash\nMY_TOKEN=\"$(FLOW_ENV_BACKEND=local f env get --personal MY_TOKEN -f value 2>/dev/null || true)\"\nif [ -z \"${MY_TOKEN:-}\" ]; then\n  echo \"MY_TOKEN missing. Save it with envnew MY_TOKEN=...\"\n  exit 1\nfi\nexport MY_TOKEN\n```\n\n## One-time passwords (1Password Connect)\n\nUse Flow's OTP command to fetch TOTP codes from 1Password Connect:\n\n```bash\nf otp get <vault> <item> [--field <label>]\n```\n\nRequires:\n- `OP_CONNECT_HOST`\n- `OP_CONNECT_TOKEN` (env or Flow personal env store)\n\n## Storage Locations\n\n- **Personal env vars:** `~/.config/flow/env-local/personal/production.env`\n- **Project env vars:** Stored via myflow.sh cloud backend\n- **Local .env:** Created in project root via `f env pull`\n\n## Authentication\n\nFlow uses a token stored in `~/.config/flow/auth.toml` to authenticate. If you haven't authenticated:\n\n```bash\nf auth login\n```\n\n## Security Notes\n\n- Personal env vars stored locally in `~/.config/flow/`\n- Project env vars can be synced to cloud via `f env push`\n- Never commit `.env` files to git (add to `.gitignore`)\n- Use `f env run` to inject vars without creating .env files\n\n<!-- File: .ai/skills/pr-markdown-body-file/skill.md (Tokens: ~303 | Category: anthropic-skill) -->\n---\nname: pr-markdown-body-file\ndescription: Always edit/create GitHub PR bodies from a markdown file; never inline escaped newlines.\nversion: 1\nsource: flow-default\n---\n\n# PR Markdown Body Discipline\n\nUse this skill when creating or editing pull requests.\n\n## Rules (Must)\n\n- Never pass multi-line PR text via a quoted CLI string with `\\n`.\n- Always use a markdown file with `--body-file`.\n- Prefer `f pr open edit` when available for local file-driven PR editing.\n\n## Why\n\nInline escaped newlines are fragile and can produce literal `\\n` text in GitHub PR descriptions.\n`--body-file` is deterministic and reviewable.\n\n## Safe patterns\n\n### Create PR (GitHub CLI)\n\n```bash\ncat > /tmp/pr-body.md <<'EOF'\n## Summary\n- ...\n\n## Scope\n- ...\nEOF\n\ngh pr create --title \"...\" --body-file /tmp/pr-body.md\n```\n\n### Edit existing PR\n\n```bash\ncat > /tmp/pr-body.md <<'EOF'\n## Summary\n- ...\nEOF\n\ngh pr edit <number> --body-file /tmp/pr-body.md\n```\n\n### Flow-native edit loop\n\n```bash\nf pr open edit\n```\n\nThis opens a local markdown file and syncs title/body on save.\n\n## Verification\n\n- Run:\n\n```bash\ngh pr view <number> --json body -q .body\n```\n\n- Confirm markdown renders correctly and contains no literal `\\n`.\n\n<!-- File: .ai/skills/quality-bun-feature-delivery/skill.md (Tokens: ~424 | Category: anthropic-skill) -->\n---\nname: quality-bun-feature-delivery\ndescription: Enforce tight Codex/Claude delivery loop with Bun-first testing, skill sync/reload, and commit quality gates.\nversion: 2\nsource: flow-default\n---\n\n# Quality Bun Feature Delivery\n\nUse this workflow for every feature/change.\n\n## Rules (Must)\n\n- In Bun repos, run tests with `bun bd test ...` (never `bun test` for final validation).\n- Run only relevant tests first (single file/filter) for fast feedback.\n- Keep `.ai/features/*.md` and tests current for touched features.\n- Do not finish work without a passing local verification command.\n\n## Tight Loop\n\n1. Update code + tests.\n2. Run focused tests with Bun debug build:\n\n```bash\nbun bd test <target-test-file> -t \"<optional filter>\"\n```\n\n3. Sync task skills to keep agent context fresh:\n\n```bash\nf skills sync\n```\n\n4. Force Codex to reload skills for this cwd:\n\n```bash\nf skills reload\n```\n\n5. Commit through Flow quality gates:\n\n```bash\nf commit\n```\n\n## Bun Regression Check (for new tests)\n\nWhen adding/changing tests in Bun itself, ensure the test fails on system Bun and passes on debug Bun:\n\n```bash\nUSE_SYSTEM_BUN=1 bun test <target-test-file>\nbun bd test <target-test-file>\n```\n\n## Recommended flow.toml\n\n```toml\n[skills]\nsync_tasks = true\ninstall = [\"quality-bun-feature-delivery\"]\n\n[skills.codex]\ngenerate_openai_yaml = true\nforce_reload_after_sync = true\ntask_skill_allow_implicit_invocation = false\n\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\n<!-- File: docs/commands/ai.md (Tokens: ~5153 | Category: command-prompt) -->\n# f ai\n\nManage Claude Code, Codex, and Cursor sessions for the current project.\n\nFlow reads local session stores, filters by current project path, and gives you one interface for list/search/resume/copy/save.\nWhen you need to reopen a repo's session from another working directory, use `--path <project-root>` on `resume` or provider-specific `continue`.\nCursor transcripts are supported for reading only.\n\nArchitecture note:\n\n- for the underlying transport split between wrapped Codex CLI, `jd`, and `codex app-server`, see `docs/codex-interface.md`\n\n## Quick Start\n\n```bash\n# Fuzzy-pick a recent session (Claude + Codex + Cursor)\nf ai\n\n# Provider-specific list/read\nf ai claude list\nf ai codex list\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\nf ai cursor list\nf codex resolve \"latest\"\nf codex resolve \"https://linear.app/.../project/.../overview\" --json\nf codex open \"continue the deploy work\"\nf codex agent list\nf codex agent show commit\nf ai claude resume <session-id-or-name>\nf ai codex resume <session-id-or-name>\nf ai codex resume --path ~/work/example-project\nf ai codex continue --path ~/work/example-project\nf ai codex find --path ~/repos/openai/codex \"where does codex store\"\nf ai codex find --all-history --path ~/repos/openai/codex \"older migration plan\"\nf ai codex find --recent-days 30 --path ~/repos/openai/codex \"thread/read\"\nf ai codex find --json --limit 5 --path ~/repos/openai/codex \"thread/read\"\nf codex connect --path ~/repos/openai/codex --exact-cwd --json \"app-server\"\nf codex connect --all-history --path ~/repos/openai/codex \"old designer cutover\"\nf ai cursor context - /path/to/repo 3\nf cursor copy\n\n# Save a memorable alias for a session\nf ai save reclaim-fix --id a38cf8bf-f4e2-4308-8b27-0254f89c4385\n```\n\n## Session Sources\n\n- Claude: `~/.claude/projects/<project-path>/*.jsonl`\n- Codex: `~/.codex/sessions/**/*.jsonl` (Flow matches by `session_meta.cwd`)\n- Cursor: `~/.cursor/projects/<project-key>/agent-transcripts/<session-id>/<session-id>.jsonl`\n- Saved aliases: `.ai/sessions/claude/index.json` in your repo\n\n## Resume Behavior (Important)\n\n### TTY requirement\n\nResume is interactive by design.\n\n- `f ai claude resume ...` requires a terminal TTY.\n- `f ai codex resume ...` requires a terminal TTY.\n- In non-interactive shells, Flow exits with a clear error and non-zero status.\n- Cursor does not currently expose a Flow resume/continue path; use `list`, `copy`, or `context`.\n\n### Claude exact-ID behavior\n\nIf you pass an explicit session (`name`, `id`, or `id-prefix`), Flow is strict:\n\n- it attempts `claude --resume <id>`\n- if Claude cannot open that exact session, Flow fails\n- Flow does **not** auto-fallback to `--continue` for explicit sessions (prevents opening the wrong conversation)\n\n### Claude no-arg behavior\n\nFor `f ai claude resume` with no argument:\n\n- Flow picks most recent Claude session for this project\n- if that resume fails, Flow may fallback to `claude --continue` in the same cwd (TTY only)\n\n### Codex behavior\n\nFor Codex, Flow runs:\n\n```bash\ncodex resume <id> --dangerously-bypass-approvals-and-sandbox\n```\n\nNo fallback is applied on resume failure; Flow returns non-zero.\n\n### Codex open and resolve\n\nUse `open` when you want one Codex entrypoint that stays conservative about context:\n\n```bash\nf codex open\nf codex open \"continue the deploy work\"\nf codex open \"resume latest\"\nf codex open --path ~/work/example-project \"what was I doing here\"\nf codex resolve \"https://linear.app/example-workspace/project/example-project-v1-1234567890ab/overview\" --json\nf codex doctor --path ~/work/example-project\n```\n\nBehavior:\n\n- no query: start a fresh Codex session in the target repo\n- explicit session lookup queries like `latest`, `resume session`, ordinals, or session IDs: resume the matching Codex session\n- explicit recovery prompts like `what was I doing` or `continue the ... work`: build a compact recovery handoff and start a new session\n- matching reference resolvers: inject only compact resolver output, then append the user request\n- otherwise: start a new session with the raw query and no extra wrapper text\n\nThis keeps prompt cost flat unless Flow has a strong reason to recover or unroll context.\nUse `f codex doctor` to confirm whether wrapper transport, runtime skills, and context budgets are actually active for the current repo.\n\n### Codex connect and find\n\n`f codex connect` and `f ai codex find` now use a Flow-managed local session-search index before\nfalling back to direct SQLite/transcript scans. The index is repo-scoped at query time, rebuilt\nfrom the Codex state DB when needed, and keeps transcript snippets for better recall on natural\nlanguage queries.\n\nBy default, search now prefers sessions from roughly the last 7 days for faster and more accurate\nranking on active work, then automatically widens back to the full session history when the recent\nwindow looks weak or sparse.\n\nUseful commands:\n\n```bash\nf codex connect --path ~/repos/openai/codex --exact-cwd \"app-server\"\nf codex connect --path ~/repos/openai/codex --exact-cwd --json \"thread/read\"\nf codex connect --all-history --path ~/repos/openai/codex \"old migration plan\"\nf ai codex find --path ~/repos/openai/codex \"where does codex store\"\nf ai codex find --recent-days 30 --path ~/repos/openai/codex \"thread/read\"\nf ai codex find --json --limit 5 --path ~/repos/openai/codex \"where does codex store\"\n```\n\nBehavior:\n\n- `connect` stays the interactive handoff path and returns the exact session match\n- `connect --json` prints the selected session instead of attaching\n- `find` still resumes the top hit\n- `find --json` is read-only and prints ranked candidates for inspection/eval work\n- by default both commands prefer the last 7 days first, then widen if the recent window is weak\n- use `--recent-days <N>` to widen the preferred recent window without fully disabling recency bias\n- use `--all-history` to search the full history immediately\n- if confidence is weak or the index misses, Flow still falls back to the older metadata and transcript paths instead of silently opening an arbitrary session\n\n### Codex sessions after a crash or restart\n\nIf your Mac restarts and you lose the live Codex terminals, use:\n\n```bash\nf ai codex sessions\nf ai codex sessions --path ~/repos/mark3labs/kit\n```\n\nBehavior:\n\n- lists recent Codex sessions for the current path\n- sorts by the last message timestamp descending\n- shows the stable session id plus a preview of the latest message\n- the numeric index matches `continue`, so you can reopen quickly\n\nIf you want to read or hand off a session instead of reopening it, use the native session bridge in Codex chat:\n\n```text\nsee codex in ~/repos/mark3labs/kit\nsee 019cd046 codex session\nread 019cd046 codex session deeply\n```\n\nExamples:\n\n```bash\nf ai codex continue 1 --path ~/repos/mark3labs/kit\nf ai codex continue 019cd046 --path ~/repos/mark3labs/kit\nf ai codex sessions --path ~/repos/mark3labs/kit --json\n```\n\n### Optional `flow.toml` resolver config\n\nYou can teach `f codex open` and `f codex resolve` to unroll repo-specific references:\n\n```toml\n[codex]\nauto_resolve_references = true\nprompt_context_budget_chars = 900\nmax_resolved_references = 1\nsync_workflow_command = \"./scripts/sync-safe\"\n\n[[codex.reference_resolver]]\nname = \"linear\"\nmatch = [\"https://linear.app/*/issue/*\", \"https://linear.app/*/project/*\"]\ncommand = \"my-linear-tool inspect {{ref}} --json\"\ninject_as = \"linear\"\n```\n\nNotes:\n\n- configure this in repo `flow.toml` or global `~/.config/flow/flow.toml`\n- `{{ref}}`, `{{query}}`, and `{{cwd}}` are available in resolver commands\n- built-in Linear URL parsing works even without a custom resolver\n- resolver output is compacted before prompt injection\n- `prompt_context_budget_chars` hard-caps injected context before your request is appended\n- `max_resolved_references` prevents broad unrolling from bloating one turn\n- `sync_workflow_command` lets plain `sync branch` route into a repo-specific safe sync command instead of improvised Git/JJ steps\n\n### Optional runtime skill transport\n\nFlow can also materialize tiny per-launch runtime skills for current upstream Codex without forking Codex.\n\nEnable it globally with:\n\n```bash\nf codex enable-global --full\nf codex doctor --path ~/docs --assert-runtime --assert-schedule\n```\n\nOr configure it manually with:\n\n```toml\n[codex]\nruntime_skills = true\n\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n```\n\nFor the `~/code/flow` repo specifically, the intended in-repo shape is:\n\n```toml\n[options]\ncodex_bin = \"~/code/flow/scripts/codex-flow-wrapper\"\n\n[codex]\nruntime_skills = true\nauto_resolve_references = true\nprompt_context_budget_chars = 1200\nmax_resolved_references = 2\n\n[[codex.skill_source]]\nname = \"run-control-plane\"\npath = \"~/run\"\nenabled = true\n```\n\nThat keeps a fresh checkout Codex-first even before machine-local setup is remembered.\n\nCurrent first-slice behavior:\n\n- `f codex open \"write plan\"` can attach a tiny plan-writing runtime skill\n- the runtime skill is exposed only for the launched Codex process\n- Flow keeps the generated runtime state under `~/.config/flow/codex/runtime`\n\nInspect or clear runtime state:\n\n```bash\nf codex runtime show\nf codex runtime clear\nf codex log status\nf codex log sync --limit 400\nf codex memory status\nf codex memory query --path ~/code/flow \"codex control plane runtime skills\"\nf codex memory recent --path ~/docs\nf codex doctor\n```\n\nAssertive health checks:\n\n```bash\nf codex doctor --path ~/docs --assert-runtime\nf codex doctor --path ~/docs --assert-schedule\nf codex doctor --path ~/docs --assert-learning\nf codex doctor --path ~/docs --assert-autonomous\n```\n\n`--assert-learning` is intentionally strict: it fails until Flow has real\nlogged events, grounded outcome samples, and a non-empty scorecard for that\ntarget.\n\nBuilt-in plan writer:\n\n```bash\ncat <<'EOF' | f codex runtime write-plan --title \"Example Plan\"\n# Example Plan\n\n- item\nEOF\n```\n\nBy default this writes to today's `~/docs/plan/<day-of-month>/` bucket, for\nexample `~/docs/plan/23/` on the 23rd day of the month.\n\nCompleted `j` sessions are also mirrored automatically into `~/log/.ai/docs/session-changes/`\nthrough `jd`, so durable home-log notes exist even when a repo-local `.ai/docs/`\npromotion never happens.\n\n### Run-owned agent bridge\n\nFlow can execute run-owned Codex agents directly without copying their specs or\nprompts into `~/code/flow`.\n\nUseful commands:\n\n```bash\nf codex agent list\nf codex agent list --json\nf codex agent show commit\nf codex agent run planner --path ~/code/flow \"make a 3 phase rollout plan\"\nf codex agent run commit --path ~/repos/openai/codex \"review the current diff and draft a safe commit\"\nf codex agent run planner --json --path ~/code/flow \"reply with exactly: ok\"\n```\n\nBehavior:\n\n- Flow bridges into `~/run/scripts/agent-router.sh`\n- the run-owned agent still executes through its own spec/runtime path in `~/run`\n- `--path` controls the repo/worktree cwd used for the agent run\n- `run` returns the agent's final output plus any durable artifact/trace paths\n- `f codex doctor --path <repo>` reports whether the run-agent bridge is ready\n\nRepo-local readiness check:\n\n```bash\nf codex doctor --path ~/code/flow --assert-runtime --assert-schedule\nf codex skill-source list --path ~/code/flow\nf codex agent list\n```\n\n### Skill eval and background refresh\n\nFlow can learn which runtime skills are actually worth injecting from local\nCodex usage history without replaying Codex in the hot path.\n\nUseful commands:\n\n```bash\nf codex eval --path ~/work/example-project\nf codex memory sync --limit 400\nf codex memory recent --path ~/work/example-project --limit 12\nf codex skill-eval show --path ~/work/example-project\nf codex skill-eval run --path ~/work/example-project\nf codex skill-eval cron --limit 400 --max-targets 12 --within-hours 168\nf codex telemetry status\nf codex telemetry flush --limit 200\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\nf codex project-ai show --path ~/work/example-project --json\nf codex project-ai recent --limit 12 --json\nf codex skill-source list --path ~/work/example-project\nf codex skill-source sync --path ~/work/example-project --skill find-skills\nf codex agent list\nf codex agent run planner --path ~/work/example-project \"summarize the next rollout slice\"\n```\n\nThe Codex memory mirror:\n\n- stores durable indexed memory under the Jazz2 root (`~/.jazz2/...` or `~/repos/garden-co/jazz2/.jazz2/...`)\n- mirrors Flow’s route/outcome history into SQLite with WAL enabled\n- extracts compact repo/code facts from repo capsules (summary, commands, important paths, docs hints)\n- adds bounded live code-path retrieval for explicit repo references, so prompts like `see ~/code/flow ...` can inject likely files such as `src/ai.rs` or `docs/...` without dumping raw source\n- indexes durable repo entrypoints and extracted symbols under the same Jazz2-rooted memory store, then supplements them with live symbol extraction from the top-ranked code files during `memory query` / `codex resolve`\n- adds tiny symbol snippets for the top code hits, so coding prompts can carry actual struct/function shape without inlining whole files\n- biases retrieval by intent: implementation/file-edit prompts prefer symbols, snippets, and `src/...` paths; summary/docs prompts prefer doc headings and docs paths\n- stays best-effort so failed memory writes do not block normal Codex coding turns\n\nThe project-ai manifest:\n\n- gives `jd` a bounded metadata view of repo-local `.ai/` scaffolding\n- records counts and latest paths for skills, docs, reviews, tasks, and todos\n- keeps default context fill minimal by exposing only compact hints, not raw content\n- tracks query counts and recent repo usage so you can see whether the feature is actually being used\n- is refreshed again by `f codex skill-eval cron`, so the mirror heals even if a hot-path write is skipped\n- is queried automatically for explicit repo references during `f codex open` / `f codex resolve`\n\nWhat `cron` does:\n\n- scans only recent logged Flow Codex events\n- syncs recent skill-eval logs into the Jazz2-backed memory mirror\n- skips missing/moved repo paths\n- rebuilds scorecards for a bounded number of recent repos\n- never launches Codex or replays network work in the background\n\nFor your use case, this keeps learning cheap and safe enough to run regularly.\n\n### Trace inspection for Flow-managed Codex sessions\n\nFlow now assigns a trace envelope to all Flow-managed Codex launches, not just\nspecial workflows like `check <github-pr-url>`.\n\nThat means sessions started or resumed through:\n\n```bash\nj ...\nk <session-id>\nf codex open ...\nf codex resume ...\nf codex continue ...\n```\n\ncarry `FLOW_TRACE_*` env vars and emit at least one compact Flow telemetry\nevent, so the session becomes remotely inspectable.\n\nUseful commands:\n\n```bash\nf codex trace status\nf codex trace current-session --json\nf codex trace inspect <trace-id> --json\n```\n\nBehavior:\n\n- `trace status` checks whether Maple MCP reads are configured and reachable\n- `trace current-session` reads the active `FLOW_TRACE_ID` from the current\n  Flow-managed Codex session, flushes recent Flow telemetry once, then attempts\n  a remote trace read\n- if Maple reads are partially configured but tenant access is still blocked,\n  Flow returns the current trace metadata plus `readError` instead of failing\n  without context\n\nThis keeps the workflow autonomous from inside Codex itself: once the session\nwas started through Flow, you can inspect the current trace without manually\ncopying ids.\n\n`f codex eval --path ...` is the joined operator report:\n\n- current runtime/doctor state\n- recent route mix and context cost\n- grounded skill scorecard highlights\n- concrete “what to improve next” recommendations\n- commands to deepen or fix the current state\n\nIf `jd` is running, it also keeps recent completion reconciliation warm and\nnow does a bounded background scorecard refresh, so the eval report does not go\nstale as quickly between manual runs.\n\nIf the native session bridge skill is installed, `jd` also prewarms compact\nhandoff capsules for recent native Codex sessions whenever the Codex state DB\nchanges. That keeps the exact handoff path cheap, so pasting\n`019d... codex session` into another chat is usually already a warm cache hit\ninstead of the first lookup having to build the capsule from the rollout.\n\nOptional telemetry export follows the same local-first pattern: Flow keeps\nlocal Codex logs canonical, and if `FLOW_CODEX_MAPLE_*` env vars are set it can\nexport redacted route/context/outcome spans to Maple without shipping raw\nprompts or full repo paths. Use:\n\n```bash\nf codex telemetry status\nf codex telemetry flush --limit 200\n```\n\nFor local-only secrets, prefer `f env set --personal ...`. On macOS you may\nneed `f env unlock` once per day for background reads. Flow-launched Codex\nsessions also inherit the same `FLOW_CODEX_MAPLE_*` values from the personal\nstore, while explicit shell env still wins for one-off tests.\n\nWhen `jd` is running, the daemon also performs a bounded background export\npass so the external analytics view stays warm.\n\n### macOS launchd schedule for skill-eval\n\nIf you want scorecards to stay fresh automatically on macOS:\n\n```bash\nf codex-skill-eval-launchd-install\nf codex-skill-eval-launchd-status\nf codex-skill-eval-launchd-logs\n```\n\n`f codex enable-global --full` installs this schedule for you.\n\nDefault schedule:\n\n- every 30 minutes\n- scan up to 400 recent events\n- rebuild up to 12 recent repo scorecards\n- ignore repos not seen in the last 168 hours\n\nYou can tune install-time bounds:\n\n```bash\nf codex-skill-eval-launchd-install --minutes 20 --limit 600 --max-targets 16 --within-hours 72\nf codex-skill-eval-launchd-install --dry-run\n```\n\nRemove it with:\n\n```bash\nf codex-skill-eval-launchd-uninstall\n```\n\n### Cursor behavior\n\nCursor transcripts are read-only in Flow:\n\n- `f ai cursor list` opens a picker and copies the selected transcript\n- `f ai cursor copy` copies the latest Cursor transcript for this repo\n- `f ai cursor context ...` copies the last N exchanges\n- `f cursor ...` is a shortcut for the same provider-specific read commands\n\n### Cross-directory resume\n\nYou can target another repo without changing directory:\n\n```bash\nf ai codex resume --path ~/work/example-project\nf ai codex resume --path ~/work/example-project 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai codex continue --path ~/work/example-project\n```\n\n- `resume --path <repo>` resolves the requested session against that repo instead of the current cwd\n- `continue --path <repo>` resumes the latest session for that repo\n- explicit full Codex IDs still work directly even when your current cwd is different\n\n## Session Selectors\n\n`resume` accepts:\n\n- saved alias from `.ai/sessions/claude/index.json`\n- full session ID\n- ID prefix (8+ chars)\n- numeric index from list output (1-based)\n\nExamples:\n\n```bash\nf ai resume my-feature\nf ai resume a38cf8bf\nf ai claude resume 2\nf ai codex resume 019c61c5-0aef-71a1-b058-5c9ab43013d4\nf ai cursor context 382ef1a3 /path/to/repo 2\n```\n\n## Content Copy Commands\n\n```bash\n# Copy full conversation to clipboard\nf ai copy\nf ai copy <session>\n\n# Copy last N prompt/response turns\nf ai context\nf ai context <session> <path> <count>\n```\n\nUse `-` as session placeholder to trigger fuzzy selection:\n\n```bash\nf ai claude context - /path/to/repo 3\nf ai cursor context - /path/to/repo 3\n```\n\n## Project Workflow (Recommended)\n\n1. Start from repo root and inspect tasks:\n   `f tasks list`\n2. Resume exact session when continuing prior work:\n   `f ai claude resume <id>` or `f ai codex resume <id>`\n3. Keep context current:\n   `f skills sync` then `f skills reload`\n4. Validate through tasks:\n   `f test-related` / `f test`\n5. Commit through Flow gates:\n   `f commit`\n\nThis keeps sessions, tasks, skills, and commit quality checks in one loop.\n\n## Everruns Bridge Mode\n\nFlow also supports running a prompt through Everruns while routing client-side\n`seq_*` tool calls to local `seqd`:\n\n```bash\nf ai everruns \"open Safari and take a screenshot\"\n```\n\nKey points:\n\n- This path is additive. It does not replace `f ai claude ...` or `f ai codex ...`.\n- Flow now reuses Seq's canonical Everruns bridge for:\n  - `seq_*` tool definitions injected into new sessions\n  - tool-name normalization (`seq_open_app`, `seq.open_app`, `seq:open-app`)\n  - request correlation IDs (`request_id`, `run_id`, `tool_call_id`)\n- Event transport is SSE-first (`/sse`) with automatic fallback to polling (`/events`) if SSE is unavailable.\n- Optional Maple telemetry export can dual-write runtime traces to local + hosted ingest endpoints when `SEQ_EVERRUNS_MAPLE_*` env vars are configured.\n- Existing Flow features remain unchanged (`f seq-rpc`, session resume/copy/context flows).\n\nSetup and validation details are documented in:\n\n- `docs/everruns-seq-bridge-integration.md`\n- `docs/everruns-maple-runbook.md`\n\n<!-- File: docs/commands/clone.md (Tokens: ~276 | Category: command-prompt) -->\n# f clone\n\nClone a repository with git-like destination behavior.\n\n## Overview\n\n`f clone` behaves like `git clone` for destination paths:\n\n- `f clone <url>` clones into the current working directory using Git's default folder naming.\n- `f clone <url> <dir>` clones into an explicit destination directory.\n\nFor GitHub inputs, Flow normalizes clone URLs to SSH:\n\n- `https://github.com/owner/repo` -> `git@github.com:owner/repo.git`\n- `owner/repo` -> `git@github.com:owner/repo.git`\n\nThis command does not force clones into `~/repos` and does not auto-configure `upstream`.\n\n## Usage\n\n```bash\nf clone <url-or-owner/repo> [directory]\n```\n\n## Examples\n\n```bash\n# GitHub URL -> SSH clone URL\nf clone https://github.com/genxai/new\n\n# owner/repo shorthand -> SSH clone URL\nf clone genxai/new\n\n# explicit destination folder (same as git clone)\nf clone genxai/new my-local-new\n```\n\n## When To Use\n\n- Use `f clone` when you want standard `git clone` destination behavior.\n- Use [`f repos clone`](repos.md) when you want managed placement under `~/repos/<owner>/<repo>` plus optional upstream automation.\n\n<!-- File: docs/commands/commit.md (Tokens: ~3147 | Category: command-prompt) -->\n# f commit\n\nAI-powered commit with deferred Codex review and GitEdit sync.\n\n## Overview\n\nStages all changes, commits quickly by default, runs Codex deep review asynchronously in the background, pushes, and syncs AI sessions to gitedit.dev.\n\n## Quick Start\n\n```bash\n# Default flow: commit now, Codex review runs in background\nf commit\n\n# Blocking pre-commit review (legacy behavior)\nf commit --slow\n\n# Fast commit with custom message (no AI review, no Codex follow-up)\nf commit --fast \"fix typo\"\nf commit --fast  # defaults to \".\" as message\n\n# Queue for review (no push) + create jj review bookmark\nf commit --queue\n\n# Commit without pushing\nf commit -n\n\n# Include AI context in review\nf commit --context\n\n# Custom message\nf commit -m \"Fixes #123\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--no-push` | `-n` | Skip pushing after commit |\n| `--queue` | | Queue the commit for review (no push) |\n| `--no-queue` | | Bypass queue and allow push |\n| `--sync` | | Run synchronously (don't delegate to hub) |\n| `--context` | | Include AI session context in code review |\n| `--dry` | | Dry run: show context without committing |\n| `--quick` | | Explicitly use fast commit + async Codex review (compat alias) |\n| `--slow` | | Run blocking pre-commit review before commit |\n| `--fast [MSG]` | | Fast commit with no AI review (defaults to \".\") |\n| `--codex` | | Use Codex instead of Claude for review |\n| `--review-model <MODEL>` | | Choose specific review model |\n| `--message <MSG>` | `-m` | Custom message appended to commit |\n| `--tokens <N>` | `-t` | Max tokens for AI context (default: 1000) |\n\n## Review Models\n\n| Model | Description |\n|-------|-------------|\n| `claude-opus` | Claude Opus 1 for review (default) |\n| `codex-high` | Codex high-capacity (gpt-5.1-codex-max) |\n| `codex-mini` | Codex mini (gpt-5.1-codex-mini) |\n\n```bash\n# Use Codex\nf commit --codex\n\n# Specific model\nf commit --review-model codex-high\n```\n\n---\n\n## Fast Commit + Deferred Codex Review\n\n`f commit` now uses this mode by default.\n\n### Default (`f commit`) / `--quick` — commit now, Codex reviews later\n\nCommits immediately (generates an AI commit message but skips the blocking code review), then spawns a background Codex review for that commit. The review result is queued and visible via `f commit-queue list`.\n\n```bash\nf commit\nf commit --quick\n```\n\nWhat happens:\n1. Stages all changes, generates commit message, commits, pushes\n2. Queues the commit SHA for async review\n3. Spawns a background Codex process that reviews the diff\n4. You keep working — check results later with `f commit-queue list`\n\n### `--slow` — run blocking review before commit\n\nRuns the pre-commit AI review before creating the commit.\n\n```bash\nf commit --slow\nf commit --slow --review-model codex-high\n```\n\n### `--fast` — instant commit, no review at all\n\nCommits with a provided message (or `\".\"` if omitted). No AI review, no async follow-up. Useful for trivial changes.\n\n```bash\nf commit --fast \"fix typo\"\nf commit --fast              # message defaults to \".\"\n```\n\n### When to use which\n\n| Flag | AI message | Code review | Async review | Best for |\n|------|-----------|-------------|-------------|----------|\n| (none) | Yes | No | Yes (Codex background) | Default fast workflow |\n| `--quick` | Yes | No | Yes (Codex background) | Explicit fast mode |\n| `--slow` | Yes | Yes (blocking) | No | Pre-commit deep check |\n| `--fast` | No (you provide) | No | No | Trivial/WIP commits |\n\n### Opt Out Of Fast Default\n\nIf you want plain `f commit` to run blocking review by default, set:\n\n```toml\n[commit]\nquick-default = false\n```\n\nWith this set, plain `f commit` behaves like `f commit --slow` unless you explicitly pass `--quick`.\n\nRun deep review in batches:\n\n```bash\nf reviews-todo codex --all\nf reviews-todo list\n```\n\n### Myflow Fast + Deep Profile\n\nFor `~/code/myflow`, this profile gives a fast default loop while keeping deep Codex coverage:\n\n```toml\n[commit]\nquick-default = true\nqueue = false\nqueue_on_issues = false\n\n# Fast message generation path via zerg/ai (glm + cerebras), then fallbacks.\nmessage_fallbacks = [\n  \"rise:zai:glm-5\",\n  \"rise:cerebras:gpt-oss-120b\",\n  \"remote\",\n  \"openai\"\n]\n\n# When you explicitly run blocking review, prefer fast models first.\nreview_fallbacks = [\n  \"glm5\",\n  \"rise:cerebras:gpt-oss-120b\",\n  \"codex-high\"\n]\n```\n\nThen operate with:\n\n```bash\nf commit\nf reviews-todo codex --all\n```\n\n---\n\n## What Happens\n\n1. **Safety Checks**\n   - Warns about sensitive files (.env, .pem, keys, credentials)\n   - Warns about files with large diffs (500+ lines)\n   - Runs invariant checks from `[invariants]` when configured\n\n2. **Stage Changes**\n   - Runs `git add -A` to stage all changes\n\n3. **Code Review**\n   - Sends diff to AI for review\n   - Checks for bugs, security issues, best practices\n   - Optionally includes AI session context (`--context`)\n\n4. **Generate Message**\n   - AI generates commit message from diff\n   - Appends custom message if provided (`-m`)\n\n5. **Commit**\n   - Creates commit with generated message\n\n6. **Queue (optional)**\n   - Adds commit to the review queue (`f commit-queue list`)\n   - Creates a jj review bookmark (e.g., `review/main-<sha>`)\n\n7. **Push**\n   - Pushes to remote (unless `--no-push` or `--queue`)\n\n7. **GitEdit Sync**\n   - Syncs AI session data to gitedit.dev\n\n## Invariant Gate\n\nIf your project defines `[invariants]` in `flow.toml`, `f commit` evaluates the staged diff against those rules (forbidden patterns, dependency allowlist policy, file line limits).\n\n- `mode = \"warn\"`: commit continues and findings are shown.\n- `mode = \"block\"`: commit is blocked on warning/critical findings.\n- Findings are injected into the AI review context.\n\n---\n\n## Usage Examples\n\n### Basic Commit\n\n```bash\n# Review, commit, and push\nf commit\n```\n\n### Local Commit Only\n\n```bash\n# Don't push to remote\nf commit -n\n```\n\n### With AI Context\n\nInclude recent AI session context in the review:\n\n```bash\nf commit --context\nf commit --context --tokens 2000  # More context\n```\n\n### Custom Message\n\nAppend additional context to the commit:\n\n```bash\nf commit -m \"Fixes #123\"\nf commit -m \"Co-authored-by: John <john@example.com>\"\n```\n\n### Dry Run\n\nSee what would be reviewed without committing:\n\n```bash\nf commit --dry\n```\n\n### Synchronous Mode\n\nRun directly without delegating to hub:\n\n```bash\nf commit --sync\n```\n\n---\n\n## Safety Warnings\n\n### Sensitive Files\n\nBefore committing, flow warns if staging files that look sensitive:\n\n```\n⚠ Warning: The following sensitive files are staged:\n  - .env\n  - credentials.json\n  - private.key\n```\n\nSensitive patterns include:\n- `.env`, `.env.*`\n- `credentials.json`, `secrets.json`\n- `.pem`, `.key`, `id_rsa`, `id_ed25519`\n- Files containing `password`, `secret`, `token`\n\n### Secret Scan (Staged Diff)\n\nFlow scans staged diffs for likely secrets (API keys, tokens, passwords). If a match\nis detected, the commit is blocked. In an interactive terminal, flow offers to run\nan auto-fix using `ai` to mask or replace the values, then asks for approval to\ncontinue.\n\nYou can bypass the check for a single commit with:\n\n```\nFLOW_ALLOW_SECRET_COMMIT=1 f commit\n```\n\n### Large Diffs\n\nWarns about files with significant changes:\n\n```\n⚠ Warning: The following files have large diffs:\n  - src/generated.rs (1523 lines)\n  - data/fixtures.json (834 lines)\n```\n\nThreshold: 500+ lines added/removed.\n\n---\n\n## Related Commands\n\n| Command | Description |\n|---------|-------------|\n| `f commit` | Fast commit + deferred Codex review (default) |\n| `f commitWithCheck` | Review without GitEdit sync |\n| `f commitSimple` | No review, just AI commit message |\n\n### commitWithCheck (alias: cc)\n\nSame as `commit` but skips GitEdit sync:\n\n```bash\nf commitWithCheck\nf cc  # Short alias\n```\n\n### commitSimple\n\nQuick commit without code review:\n\n```bash\nf commitSimple\n```\n\n---\n\n## Configuration\n\n### Hub Delegation\n\nBy default, `f commit` delegates to the hub daemon for async processing. Use `--sync` for direct execution:\n\n```bash\n# Async via hub (default)\nf commit\n\n# Sync (direct)\nf commit --sync\n```\n\n### Commit Message Tool\n\nOptionally force a specific commit-message generator:\n\n```toml\n[commit]\nmessage_tool = \"kimi\" # also supports: claude, rise, glm5, opencode, openrouter, remote, openai\nmessage_model = \"kimi-k2-thinking-turbo\" # optional, tool-specific\n```\n\nIf the forced tool fails, `f commit` now falls back through the configured/default chain.\n\n### Review Tool (Kimi CLI)\n\nUse Kimi Code CLI for code review:\n\n```toml\n[review]\ntool = \"kimi\"\nmodel = \"kimi-k2-thinking-turbo\" # optional; uses Kimi default if omitted\n```\n\nThis uses `kimi --quiet` (print mode) with your existing Kimi CLI auth/config.\n\n### Robust Fallbacks\n\n`f commit` now uses multi-attempt fallback chains for both review and commit-message generation.\n\nDefault behavior:\n- Review: primary selection, then `openrouter`, `claude`, `codex-high`\n- Message: review-aligned/override tool, then `remote` (myflow), `openai`, `openrouter`\n- If all message attempts fail and fail-open is enabled, Flow uses a deterministic local fallback message.\n\nConfiguration:\n\n```toml\n[commit]\nreview_fail_open = true\nmessage_fail_open = true\nreview_fallbacks = [\"openrouter\", \"claude\", \"codex-high\"]\nmessage_fallbacks = [\"remote\", \"openai\", \"openrouter\"]\n```\n\nEnvironment overrides:\n- `FLOW_COMMIT_REVIEW_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_MESSAGE_FAIL_OPEN=0|1`\n- `FLOW_COMMIT_REVIEW_FALLBACKS=\"openrouter,claude,codex-high\"`\n- `FLOW_COMMIT_MESSAGE_FALLBACKS=\"remote,openai,openrouter\"`\n\nCodex -> GLM5 fallback example:\n\n```toml\n[commit]\nreview_fallbacks = [\"glm5\", \"openrouter\", \"claude\"]\nmessage_fallbacks = [\"glm5\", \"remote\", \"openai\"]\n```\n\n`glm5` maps to the Rise/internal route with model `zai:glm-5`.\n\n### Queue Policy\n\nQueue only when review finds issues (auto-push on a clean review):\n\n```toml\n[commit]\nqueue = true\nqueue_on_issues = true\n```\n\n`--queue` / `--no-queue` still override this behavior.\n\n### Commit Quality Gates (Testing + Required Skills)\n\nUse local gates to block commits that skip tests or required workflow skills:\n\n```toml\n[commit.testing]\nmode = \"block\"\nrunner = \"bun\"\nbun_repo_strict = true\nrequire_related_tests = true\nai_scratch_test_dir = \".ai/test\"\nrun_ai_scratch_tests = true\nallow_ai_scratch_to_satisfy_gate = false\nmax_local_gate_seconds = 20\n\n[commit.skill_gate]\nmode = \"block\"\nrequired = [\"quality-bun-feature-delivery\"]\n\n[commit.skill_gate.min_version]\nquality-bun-feature-delivery = 2\n```\n\nWhen `mode = \"block\"`, `f commit` fails until the test/skill requirements are satisfied.  \nFor Bun repos, run checks with `bun bd test ...` for debug-build validation. If no related tracked tests are found, Flow can run tests under `ai_scratch_test_dir` (default `.ai/test`) as a fallback signal.\n\n### AI Session Context\n\nWhen `--context` is enabled, includes recent Claude Code session context:\n\n```bash\n# Default: 1000 tokens of context\nf commit --context\n\n# More context\nf commit --context --tokens 3000\n```\n\n---\n\n## Examples\n\n### Quick Bug Fix\n\n```bash\n# Fix bug, commit with context\nvim src/lib.rs\nf commit --context -m \"Fixes null pointer in edge case\"\n```\n\n### Feature Branch\n\n```bash\n# Work on feature\ngit checkout -b feature/new-api\n# ... make changes ...\n\n# Commit without push\nf commit -n\n\n# More changes...\nf commit -n\n\n# Final push\ngit push -u origin feature/new-api\n```\n\n### Review Before Commit\n\n```bash\n# See what would be reviewed\nf commit --dry\n\n# If satisfied, commit\nf commit\n```\n\n---\n\n## Troubleshooting\n\n### \"Sensitive files staged\"\n\nEither:\n1. Add files to `.gitignore`\n2. Unstage with `git reset HEAD <file>`\n3. Proceed anyway if intentional\n\n### Review taking too long\n\nUse `--sync` to see progress directly:\n```bash\nf commit --sync\n```\n\n### Hub not responding\n\nFall back to sync mode:\n```bash\nf commit --sync\n```\n\n## See Also\n\n- [upstream](upstream.md) - Sync forks before committing\n- [publish](publish.md) - Publish after committing\n\n<!-- File: docs/commands/commits.md (Tokens: ~119 | Category: command-prompt) -->\n# f commits\n\nBrowse commits with AI metadata and mark notable commits for quick access.\n\n## Usage\n\n```bash\nf commits\nf commits --limit 200\nf commits --all\nf commits top\nf commits mark <hash>\nf commits unmark <hash>\n```\n\n## Notable commits\n\nNotable commits are stored in `.ai/internal/commits/top.txt` in the repo root. Each line is:\n\n```\n<full-hash>\\t<label>\n```\n\n## Key bindings\n\nWhen using fzf:\n\n- `ctrl-t` — toggle notable for the selected commit.\n\n<!-- File: docs/commands/config.md (Tokens: ~577 | Category: command-prompt) -->\n# f config\n\nCompile the personal Flow root config and generated compatibility outputs.\n\nSource of truth:\n\n- `~/.flow/config.ts`\n\nGenerated outputs:\n\n- `~/.config/flow/generated/config.snapshot.json`\n- `~/.config/flow/generated/flow/config.ts`\n- `~/.config/flow/generated/lin/config.ts`\n- `~/.config/flow/generated/lin/intents.json`\n- `~/.config/flow/generated/lin/mac.toml`\n- `~/.config/flow/generated/ai/config.json`\n\nHive config may still appear in the effective root config during migration, but Flow no longer emits or applies `~/.hive/config.json`.\n\nIf `~/.flow/config.ts` does not exist yet, Flow currently falls back to:\n\n- `~/config/i/lin/config.ts`\n\nand generates a starter `~/.flow/config.ts` migration file on apply.\n\n## Commands\n\n### f config doctor\n\nShows whether the root config exists, whether a TypeScript runner is available,\nwhether a generated snapshot already exists, and what extension directories are discoverable.\n\n```bash\nf config doctor\nf config doctor --json\n```\n\n### f config build\n\nLoads the root config plus named extensions, computes the merged effective config,\nand writes generated artifacts under `~/.config/flow/generated/`.\n\nThis does not overwrite consumer config locations.\n\n```bash\nf config build\nf config build --json\n```\n\n### f config apply\n\nBuilds the snapshot and then applies the generated compatibility files into their\nconsumer locations. This is the cutover step that keeps existing tools working while\nmoving authoring into `~/.flow/config.ts`.\n\n```bash\nf config apply\nf config apply --json\n```\n\n### f config eval\n\nPrints the currently effective merged config view. If no snapshot exists yet, Flow\nbuilds one first.\n\n```bash\nf config eval\nf config eval --json\n```\n\n## Root Config Shape\n\nThe first supported root-config shape is:\n\n```ts\nexport default {\n  flow: { ... },\n  lin: { ... },\n  ai: { ... },\n  hive: { ... }, // parsed for migration compatibility, not applied to ~/.hive\n  zerg: { ... },\n  extensions: [\"lin-compat\"],\n}\n```\n\nFilesystem extensions can live under:\n\n- `~/.flow/extensions/<name>/extension.ts`\n- `~/.flow/extensions/<name>/config.ts`\n\nEach extension can contribute partial config fragments plus optional generated files.\n\n## Notes\n\n- Flow currently ships one built-in extension name: `lin-compat`\n- explicit extensions must exist or `f config build` fails\n- generated outputs are written atomically\n- if a `hive` section is present, `f config build/apply/eval` warns that Hive output is deprecated and ignored\n\n<!-- File: docs/commands/db.md (Tokens: ~257 | Category: command-prompt) -->\n# db\n\nManage database workflows and backends (Jazz + Postgres).\n\n## Usage\n\n```bash\nf db <provider> <action>\n```\n\n## Jazz\n\nCreate Jazz2 app credentials and populate env vars for the current project.\n\n```bash\nf db jazz new --kind mirror --name gitedit-mirror\n```\n\nResolution order for the credential bootstrap helper:\n\n1. Local `jazz-tools` binary on `PATH`\n2. Pinned `npx --yes jazz-tools@0.20.14`\n\nFor deliberate experiments, override the pinned fallback with:\n\n```bash\nFLOW_JAZZ_TOOLS_PACKAGE_SPEC=jazz-tools@<version> f db jazz new --kind mirror\n```\n\n## Postgres\n\nRun Drizzle migrations for the default Postgres project (`~/org/la/la/server`).\n\n```bash\nf db postgres migrate\nf db postgres migrate --generate\nf db postgres generate\n```\n\nEnvironment resolution order for `DATABASE_URL`:\n\n1. `--database-url` flag\n2. `DATABASE_URL`\n3. `PLANETSCALE_DATABASE_URL` / `PSCALE_DATABASE_URL`\n4. `<project>/.env` (DATABASE_URL)\n\nUse `--project` to override the Postgres project directory.\n\n<!-- File: docs/commands/deploy.md (Tokens: ~3109 | Category: command-prompt) -->\n# f deploy\n\nDeploy projects to hosts and cloud platforms.\n\n## Overview\n\nThe `deploy` command handles deployment to multiple platforms:\n- **Linux hosts** via SSH (with systemd + nginx)\n- **Cloudflare Workers**\n- **Railway**\n\nAuto-detects the platform from your `flow.toml` configuration.\nIf `[flow].deploy_task` is set, `f deploy` runs that task first.\nIf no deployment config exists but a `deploy` task is defined, `f deploy` runs that task.\nUse `f prod` to deploy directly from `[host]`, `[cloudflare]`, `[railway]`, or `[web]` (it skips `[flow].deploy_task`).\n\n## Quick Start\n\n```bash\n# Auto-deploy based on flow.toml config\nf deploy\n\n# Production deploy (skips flow.deploy_task, uses deploy config or deploy-prod task)\nf prod\n\n# Run the project's release task (flow.release_task or fallback)\nf deploy release\n\n# Deploy to specific platform\nf deploy host\nf deploy cloudflare\nf deploy railway\n\n# Production deploy to specific platform\nf prod host\nf prod cloudflare\n\n# Configure deployment defaults\nf deploy config\n\n# Deploy web site\nf deploy web\n```\n\n## Subcommands\n\n| Command | Alias | Description |\n|---------|-------|-------------|\n| `host` | `h` | Deploy to Linux host via SSH |\n| `cloudflare` | `cf` | Deploy to Cloudflare Workers |\n| `web` | | Deploy the web site (Cloudflare) |\n| `setup` | | Interactive deploy setup (Cloudflare) |\n| `railway` | | Deploy to Railway |\n| `config` | | Configure deployment defaults (Linux host) |\n| `release` | | Run the project's release task |\n| `status` | | Show deployment status |\n| `logs` | | View deployment logs |\n| `restart` | | Restart the deployed service |\n| `stop` | | Stop the deployed service |\n| `shell` | | SSH into the host |\n| `set-host` | `set` | Configure host for deployment |\n| `show-host` | | Show current host configuration |\n| `health` | | Check if deployment is healthy |\n\n---\n\n## Web Deployment\n\nDeploys the web site using Cloudflare and your project tasks. Flow will:\n- Ensure `[web]` exists in `flow.toml` (auto-fills `path` when possible).\n- Add the `web.route` (or `web.domain/*`) to your wrangler config.\n- Optionally create/update the Cloudflare DNS record for the domain/route.\n- Apply env vars from cloud if `web.env_source = \"cloud\"` is set.\n- Run `deploy-web` (or `deploy` as fallback).\n\n```bash\nf deploy web\n```\n\nIf the Cloudflare API token is missing, Flow will guide you to create one and\nstore it in your env store as `CLOUDFLARE_API_TOKEN`.\n\nIf `web.domain`/`web.route` or `web.path` is missing, Flow will prompt for them\nand update `flow.toml`.\n\nIf you opt into DNS management, Flow will prompt for record type/target and\ncreate or update the Cloudflare DNS record (default: `A` to `192.0.2.1`,\nproxied).\n\nIf cloud is unavailable, Flow can store envs locally when you choose\n`web.env_source = \"local\"`.\n\nExample `flow.toml`:\n\n```toml\n[web]\npath = \"packages/web\"\ndomain = \"example.com\"\nenv_source = \"cloud\"\nenv_apply = \"always\"\nenv_keys = [\"PUBLIC_API_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\n## Host Deployment (Linux via SSH)\n\nDeploy to any Linux server with SSH access. Flow handles:\n- File syncing via rsync\n- Systemd service creation\n- Nginx reverse proxy setup\n- SSL via Let's Encrypt\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[flow]\ndeploy_task = \"deploy-cli-release\"\n\n[host]\ndest = \"/opt/myapp\"           # Remote destination path\nrun = \"./server\"              # Command to run the service\nport = 3000                   # Port the service listens on\nservice = \"myapp\"             # Systemd service name (optional, defaults to folder name)\nsetup = \"./scripts/setup.sh\"  # Setup script to run after first sync (optional)\nenv_file = \".env.production\"  # Path to .env file for secrets (optional)\nenv_source = \"flow\"           # Pull envs from Flow env store (optional)\nenv_keys = [\"API_KEY\"]        # Keys to fetch when env_source=flow/cloud (optional)\ndomain = \"myapp.example.com\"  # Public domain for nginx (optional)\nssl = true                    # Enable SSL via Let's Encrypt (optional)\n```\n\nTip: `f setup deploy` can scaffold the `[host]` section and create a remote setup script.\n\n### Setup Host\n\nFirst, configure your SSH connection:\n\n```bash\n# Set host (stored globally at ~/.config/flow/deploy.json)\nf deploy set-host user@host:port\nf deploy set-host deploy@myserver.com:22\nf deploy set-host root@192.168.1.100\n\n# Interactive config (prefills from ~/.config/infra/config.json if present)\nf deploy config\n\n# Verify connection\nf deploy shell\n```\n\n### Deploy\n\n```bash\n# Deploy to host\nf deploy host\n\n# Force re-run setup script\nf deploy host --setup\n\n# Build remotely instead of syncing local artifacts\nf deploy host --remote-build\n```\n\n### What Happens\n\n1. **Sync files** - rsync uploads project (excludes `target/`, `.git/`, `node_modules/`, `.env`, `*.log`)\n2. **Copy env file** - If `env_file` is specified, copies it to `{dest}/.env`\n   (or, if `env_source = \"flow\"`, fetches from Flow env store and writes `{dest}/.env`)\n3. **Run setup** - Executes setup script on first deploy or with `--setup`\n4. **Create systemd service** - Generates and enables `/etc/systemd/system/{service}.service`\n5. **Configure nginx** - If `domain` is set, creates reverse proxy config\n6. **Setup SSL** - If `ssl = true`, runs certbot for Let's Encrypt certificate\n7. **Start service** - Runs `systemctl restart {service}`\n\n### Manage Service\n\n```bash\n# View logs\nf deploy logs                 # Since last deploy (host only)\nf deploy logs -f              # Follow in real-time (since last deploy)\nf deploy logs --all           # Full history (ignore deploy marker)\nf deploy logs --all -n 500    # Show last 500 lines without deploy filter\n\n# Restart/stop\nf deploy restart\nf deploy stop\n\n# Check status\nf deploy status\n\n# SSH into server\nf deploy shell\n\n# Health check\nf deploy health\nf deploy health --url https://myapp.example.com/health\nf deploy health --status 204  # Expect specific status code\n```\n\nNote: For host deploys, Flow records the last successful deploy time in `.flow/deploy-log.json` and uses it to scope `f deploy logs` output. Use `--all` to ignore it.\n\n---\n\n## Cloudflare Workers\n\nDeploy to Cloudflare's edge network.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[cloudflare]\npath = \"worker\"                    # Path to worker directory (optional, defaults to project root)\nenvironment = \"production\"         # Wrangler environment name (optional)\nenv_file = \".env.cloudflare\"       # Path to .env file for secrets (optional)\nenv_source = \"cloud\"              # Use cloud or local env store for secrets (optional)\nenv_keys = [\"API_KEY\", \"SECRET\"]   # Specific keys to fetch from env store (optional)\nenv_vars = [\"PUBLIC_URL\"]          # Keys to set as non-secret vars (optional)\ndeploy = \"wrangler deploy\"         # Custom deploy command (optional)\ndev = \"wrangler dev\"               # Custom dev command (optional)\nurl = \"https://my-worker.workers.dev\"  # URL for health checks (optional)\n```\n\n### Prerequisites\n\n- [Wrangler CLI](https://developers.cloudflare.com/workers/wrangler/) installed\n- `wrangler.toml` in your worker directory\n- Authenticated with `wrangler login`\n\n### Deploy\n\n```bash\n# Deploy\nf deploy cloudflare\n\n# Deploy with secrets from env_file\nf deploy cloudflare --secrets\n\n# Run in dev mode\nf deploy cloudflare --dev\n```\n\n### Production domain (for `f prod`)\n\nUse `[prod]` to set a production domain or route for Workers. `f prod` will add\nthe route to your `wrangler.json/jsonc` before deploying.\n\n```toml\n[prod]\ndomain = \"anysynth.nikiv.com\"   # Will be mapped to route \"anysynth.nikiv.com/*\"\n# route = \"anysynth.nikiv.com/*\"  # Use this for explicit patterns\n```\n\n### Interactive Setup\n\nFor first-time setup, use the interactive wizard:\n\n```bash\nf deploy setup\n```\n\nThis walks you through:\n1. Selecting worker directory (auto-discovers `wrangler.toml`)\n2. Choosing .env file for secrets\n3. Selecting Cloudflare environment (production, staging, etc.)\n4. Picking which secrets to push\n5. Updating `flow.toml` with your choices\n\nIf your `flow.toml` lists service keys (for example Stripe keys), the setup flow\nwill offer to run the matching service onboarding before applying envs.\n\n### Secrets from cloud\n\nIf using cloud for secret management:\n\n```toml\n[cloudflare]\nenv_source = \"cloud\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"]  # Fetched as secrets\nenv_vars = [\"PUBLIC_API_URL\"]                      # Fetched as non-secret vars\nenvironment = \"production\"\n```\n\nThen deploy:\n\n```bash\nf deploy cloudflare --secrets\n```\n\nIf you want to use local Flow envs instead:\n\n```toml\n[cloudflare]\nenv_source = \"local\"\nenv_keys = [\"ANTHROPIC_API_KEY\", \"DATABASE_URL\"]\nenv_vars = [\"PUBLIC_API_URL\"]\n```\n\nIf you need to fill missing values first:\n\n```bash\nf env guide\n```\n\n---\n\n## Railway\n\nDeploy to Railway's platform.\n\n### Configuration\n\nAdd to `flow.toml`:\n\n```toml\n[railway]\nproject = \"my-project\"         # Railway project ID\nservice = \"api\"                # Service name (optional)\nenvironment = \"production\"     # Environment name (optional)\nstart = \"npm start\"            # Start command (optional)\nenv_file = \".env.railway\"      # Path to .env file (optional)\n```\n\n### Prerequisites\n\n- [Railway CLI](https://docs.railway.app/develop/cli) installed (`npm install -g @railway/cli`)\n- Authenticated with `railway login`\n\n### Deploy\n\n```bash\nf deploy railway\n```\n\nWhat happens:\n1. Links to Railway project if specified\n2. Sets environment variables from `env_file`\n3. Deploys with `railway up --detach`\n\n---\n\n## Health Checks\n\nCheck if your deployment is responding:\n\n```bash\n# Use domain from [host] or url from [cloudflare] config\nf deploy health\n\n# Custom URL\nf deploy health --url https://api.example.com/health\n\n# Expect specific status code\nf deploy health --status 204\n```\n\nReturns:\n- `Healthy (HTTP 200 in 0.15s)` on success\n- `Unhealthy: expected HTTP 200, got 500` on wrong status\n- `Unreachable: Connection refused` on network error\n\n---\n\n## Global Host Configuration\n\nHost connection is stored globally at `~/.config/flow/deploy.json`:\n\n```json\n{\n  \"host\": {\n    \"user\": \"deploy\",\n    \"host\": \"myserver.com\",\n    \"port\": 22\n  }\n}\n```\n\nView/set:\n\n```bash\nf deploy show-host\nf deploy set-host deploy@newserver.com:2222\n```\n\n---\n\n## Examples\n\n### Full Host Setup\n\n```toml\n# flow.toml\n[host]\ndest = \"/opt/api\"\nrun = \"/opt/api/server\"\nport = 8080\nservice = \"myapi\"\nsetup = \"cargo build --release && cp target/release/server /opt/api/\"\nenv_file = \".env.production\"\ndomain = \"api.mycompany.com\"\nssl = true\n```\n\n```bash\n# First time setup\nf deploy set-host root@myserver.com\n\n# Deploy\nf deploy host\n\n# Check it's working\nf deploy health\nf deploy logs -f\n```\n\n### Full Cloudflare Setup\n\n```toml\n# flow.toml\n[cloudflare]\npath = \"packages/worker\"\nenvironment = \"production\"\nenv_source = \"cloud\"\nenv_keys = [\"OPENAI_API_KEY\", \"WEBHOOK_SECRET\"]\nurl = \"https://my-worker.mycompany.workers.dev\"\n```\n\n```bash\n# Store project secrets\nf env project set -e production OPENAI_API_KEY=sk-...\nf env project set -e production WEBHOOK_SECRET=whsec_...\n\n# Deploy with secrets\nf deploy cloudflare --secrets\n\n# Verify\nf deploy health\n```\n\n### CI/CD Integration\n\n```yaml\n# GitHub Actions\ndeploy:\n  runs-on: ubuntu-latest\n  steps:\n    - uses: actions/checkout@v4\n    - name: Deploy\n      run: |\n        f deploy set-host ${{ secrets.DEPLOY_HOST }}\n        f deploy host\n        f deploy health\n```\n\n---\n\n## Troubleshooting\n\n### \"No host configured\"\n\nRun `f deploy set-host user@host:port` first.\n\n### \"No wrangler config found\"\n\nEnsure `wrangler.toml` exists in your worker directory, or run `wrangler init`.\n\n### SSH connection fails\n\nTest with `f deploy shell` to debug. Check:\n- SSH key is in `~/.ssh/` and added to server\n- Port is correct (default: 22)\n- Server is reachable\n\n### Secrets not updating\n\nFor Cloudflare, use `--secrets` flag: `f deploy cloudflare --secrets`\n\n### Health check fails\n\nCheck URL is correct and service is running:\n```bash\nf deploy logs -f  # Check for errors\ncurl -v https://your-domain.com  # Test manually\n```\n\n<!-- File: docs/commands/docs.md (Tokens: ~788 | Category: command-prompt) -->\n# f docs\n\nManage documentation for a project. There are two doc systems:\n\n- `.ai/docs` for AI-maintained internal docs.\n- `docs/` for human-facing docs rendered by the docs hub.\n\n## Quick Start\n\n```bash\n# Create docs/ with starter files\nf docs new\n\n# Open docs for the current project (auto-starts the hub)\nf docs\n\n# Deploy the current project's docs to Cloudflare Pages\nf docs deploy\n```\n\n## Commands\n\n### f docs new\n\nCreates a `docs/` folder in the current project using the template in `~/new/docs`.\nIf `docs/` already exists, it merges in any missing template files and leaves\nexisting content untouched.\n\nOptions:\n\n- `--path <PATH>`: Target directory (defaults to current folder).\n- `--force`: Overwrite if `docs/` already exists.\n\n### f docs hub\n\nRuns a single dev server that aggregates docs from `~/code` and `~/org`.\nUse `FLOW_DOCS_FOCUS=1` to only index the current project for faster startup.\n\nOptions:\n\n- `--host <HOST>` (default: `127.0.0.1`)\n- `--port <PORT>` (default: `4410`)\n- `--hub-root <PATH>` (default: `~/.config/flow/docs-hub`)\n- `--template-root <PATH>` (default: `~/new/docs`)\n- `--code-root <PATH>` (default: `~/code`)\n- `--org-root <PATH>` (default: `~/org`)\n- `--no-ai`: Skip `.ai/docs`.\n- `--no-open`: Do not open the browser.\n- `--sync-only`: Sync docs content and exit.\n\n### f docs deploy\n\nDeploys the current project's docs to Cloudflare Pages (uses the docs hub template).\n\nOptions:\n\n- `--project <NAME>`: Pages project name (defaults to the flow.toml name).\n- `--domain <DOMAIN>`: Attach a custom domain (optional).\n- `--yes`: Skip confirmation prompts.\n\n### f docs sync\n\nSyncs `.ai/docs` metadata based on recent commits. Intended for AI doc upkeep.\n\n### f docs list\n\nLists `.ai/docs` files for the current project.\n\n### f docs status\n\nShows recent commits and `.ai/docs` file modification times.\n\nIt now also shows:\n\n- recent Flow-managed Codex session packets stored under Flow state for the current project\n- doc-review queue state counts for the current project\n\n### f docs review-pending\n\nRuns the bounded daemon-style review pass over pending session-doc packets stored in\nFlow state and records promotion decisions into queue state plus each packet's\n`promotion.json`.\n\nOptions:\n\n- `-n, --limit <N>`: Maximum number of pending entries to review (default: `25`).\n\n### f docs promote-session\n\nPreviews or applies promotion for a daemon-captured session-doc packet.\n\nBy default this is a dry run. It prints the chosen target under `.ai/docs/` and the\npromoted markdown note. Raw packet bundles stay in Flow state; only promoted\ndurable notes are written into the repo.\n\nOptions:\n\n- `<SESSION>`: Session id, session id prefix, or session key like `019d035d-...` or `019d035d-1773776290`\n- `--apply`: Write the promoted note immediately\n\n### f docs commit-pending\n\nCommits promoted session-doc notes when the git diff is isolated to doc-only files.\n\nThis command refuses to commit if the worktree contains unrelated changes.\n\nOptions:\n\n- `--dry-run`: Show the candidate files and commit message without staging or committing\n\n### f docs edit\n\nOpens a `.ai/docs` file in `$EDITOR`.\n\nExample:\n\n```bash\nf docs edit architecture\n```\n\n<!-- File: docs/commands/domains.md (Tokens: ~767 | Category: command-prompt) -->\n# `f domains`\n\nManage shared local `*.localhost` routing with a single proxy on port `80`.\n\n## Why\n\nWithout this, each repo can start its own proxy and race for port `80`.\n`f domains` centralizes ownership with one engine at a time.\n\nState lives in:\n\n- `~/.config/flow/local-domains/routes.json`\n- runtime artifacts under `~/.config/flow/local-domains/`\n\n## Engines\n\n- `docker` (default): shared nginx container (`flow-local-domains-proxy`)\n- `native` (experimental): local C++ daemon (`domainsd-cpp`)\n\nSelect engine per command:\n\n```bash\nf domains --engine docker up\nf domains --engine native up\n```\n\nOr via env:\n\n```bash\nexport FLOW_DOMAINS_ENGINE=native\n```\n\n## Commands\n\n```bash\nf domains list\nf domains add linsa.localhost 127.0.0.1:3481\nf domains rm linsa.localhost\nf domains up\nf domains down\nf domains doctor\nf domains --engine native up\nf domains --engine native down\nf domains --engine native doctor\n```\n\n## Behavior\n\n- `f domains up`\n  - starts shared proxy on `:80`\n  - fails fast if another process/container owns port `80`\n- `f domains add`\n  - validates `host` ends with `.localhost`\n  - validates target format `host:port`\n  - refuses overwrite unless `--replace`\n  - reloads proxy if already running\n- `f domains doctor`\n  - shows route count\n  - shows current owner of port `80`\n  - highlights conflict ownership\n\n## Native notes (experimental)\n\n- Requires `clang++` to build `tools/domainsd-cpp/domainsd.cpp`.\n- Current scope is HTTP/1.1 host routing with WebSocket upgrade passthrough and upstream keepalive pooling.\n- Native daemon has built-in overload shedding (`503`) and upstream timeout protection (`504` on connect timeout).\n- HTTP/2/TLS are not implemented yet.\n- See `docs/local-domains-domainsd-cpp-spec.md`.\n- myflow-specific setup: `docs/myflow-localhost-runbook.md`.\n- Lifecycle integration: configure `[lifecycle.domains]` and use `f up` / `f down`.\n\n### macOS no-docker bind to :80\n\nIf native startup fails with `Permission denied` on `127.0.0.1:80`, install launchd socket mode once:\n\n```bash\ncd ~/code/flow\nsudo ./tools/domainsd-cpp/install-macos-launchd.sh\n```\n\nThen run:\n\n```bash\nf domains --engine native up\n```\n\nThis keeps routing fully native and avoids Docker overhead while still using port `80`.\n\n### Native tuning envs\n\nYou can tune the native daemon at startup via environment variables:\n\n```bash\nFLOW_DOMAINS_NATIVE_MAX_ACTIVE_CLIENTS=128\nFLOW_DOMAINS_NATIVE_UPSTREAM_CONNECT_TIMEOUT_MS=10000\nFLOW_DOMAINS_NATIVE_UPSTREAM_IO_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_CLIENT_IO_TIMEOUT_MS=30000\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_PER_KEY=8\nFLOW_DOMAINS_NATIVE_POOL_MAX_IDLE_TOTAL=256\nFLOW_DOMAINS_NATIVE_POOL_IDLE_TIMEOUT_MS=15000\nFLOW_DOMAINS_NATIVE_POOL_MAX_AGE_MS=120000\n```\n## Recommended Repo Pattern\n\nInstead of per-repo docker proxy tasks:\n\n```toml\n[[tasks]]\nname = \"domains-up\"\ncommand = \"f domains add myapp.localhost 127.0.0.1:3000 && f domains up\"\n```\n\nThis keeps one proxy process for all repos and avoids accidental domain hijacking.\n\n<!-- File: docs/commands/down.md (Tokens: ~280 | Category: command-prompt) -->\n# f down\n\nBring a project down using lifecycle conventions.\n\n## Quick Start\n\n```bash\n# Run lifecycle down task and optional domains teardown\nf down\n```\n\n## Behavior\n\n- Loads nearest `flow.toml` (or `--config` path).\n- Runs lifecycle task:\n  - `[lifecycle].down_task` when configured\n  - otherwise fallback: `down`\n- If no down task is found and `down_task` is not explicitly set, Flow falls back to killing all running Flow-managed processes for the current project (`f kill --all` behavior).\n- If `[lifecycle.domains]` is configured, optional teardown is applied:\n  - `remove_on_down = true` -> removes configured host route\n  - `stop_proxy_on_down = true` -> stops shared local domains proxy\n- On macOS launchd-managed native domains, stopping native proxy is handled by:\n  - `sudo ./tools/domainsd-cpp/uninstall-macos-launchd.sh`\n\nIf neither a down task nor lifecycle domain teardown is configured, command fails with guidance.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--config <PATH>` | Path to `flow.toml` (default: `./flow.toml`, searches upward when default is missing) |\n| `ARGS...` | Extra args passed to the selected lifecycle task |\n\n<!-- File: docs/commands/env.md (Tokens: ~2759 | Category: command-prompt) -->\n# f env\n\nSync project environment and manage environment variables.\n\n## Overview\n\nManage environment variables via cloud or local storage. Supports:\n- Project-level environment variables\n- Personal/global variables\n- Multiple environments (dev, staging, production)\n- Direct injection into commands\n- Touch ID gating for cloud reads and keychain-backed personal local reads on macOS\n- Client-side sealed project env sharing in the cloud\n\n## Storage Backends\n\n| Backend | Location | Config |\n|---------|----------|--------|\n| `cloud` | Cloud (myflow.sh) | Default, requires login |\n| `local` | `~/.config/flow/env-local/` | No account needed |\n\nCloud behavior:\n- Personal cloud envs use Flow's existing server-managed secret storage.\n- Project cloud envs are sealed client-side before upload and decrypted locally on read.\n- If a host deploy is configured with `env_source = \"cloud\"` plus a `service_token`, Flow keeps a compatibility plaintext mirror for those project keys until the host fetch path is upgraded.\n\nForce local backend:\n\n```bash\n# Via environment variable\nexport FLOW_ENV_BACKEND=local\n\n# Or in ~/.config/flow/config.ts\nexport default {\n  flow: { env: { backend: \"local\" } }\n}\n```\n\nIf the current project has an unambiguous deploy env source such as:\n\n```toml\n[host]\nenv_source = \"local\"\n```\n\nthen `f env` will also use the local backend automatically in that project.\n\n### Local Storage Structure\n\n```\n~/.config/flow/env-local/\n├── <project-name>/\n│   ├── production.env\n│   ├── staging.env\n│   └── dev.env\n└── personal/\n    └── production.env\n```\n\nStorage behavior:\n- Project-local envs are private `.env` files under `~/.config/flow/env-local/`.\n- On macOS, personal-local env values are stored in Keychain by default; `personal/production.env` keeps Flow-managed references, not raw secret values.\n- If `FLOW_ENV_LOCAL_PLAINTEXT=1` is set, Flow falls back to plaintext personal local storage.\n- Local env paths are written with owner-only permissions.\n\n## Quick Start\n\n```bash\n# Store a personal secret\nf env set API_KEY=sk-xxx\n\n# List variables (default action when logged in)\nf env\n\n# Run command with env vars injected\nf env run -- npm start\n\n# Get a value\nf env get API_KEY -f value\n```\n\n## Linsa/TestFlight Example\n\nFor project-scoped keys used by local + ship flows (for example, assistant keys):\n\n```bash\n# Store in project space (recommended for app/server env)\nf env project set -e dev OPENROUTER_API_KEY=sk-...\nf env project set -e production OPENROUTER_API_KEY=sk-...\nf env project set -e dev OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\nf env project set -e production OPENROUTER_MODEL=anthropic/claude-sonnet-4.5\n```\n\nNotes:\n- Do not commit secrets to docs or repository files.\n- Use `f env get -e production -f value OPENROUTER_API_KEY` at runtime when a ship script needs to inject a missing key.\n\n## Subcommands\n\n| Command | Description |\n|---------|-------------|\n| `login` | Authenticate with cloud |\n| `set` | Set a single env var |\n| `get` | Get specific env var(s) |\n| `list` | List env vars for this project |\n| `delete` | Delete env var(s) |\n| `pull` | Fetch env vars and write to .env |\n| `push` | Push local .env to cloud |\n| `apply` | Apply env vars to Cloudflare worker |\n| `setup` | Interactive wizard to push env vars |\n| `run` | Run command with env vars injected |\n| `status` | Show current auth status |\n| `keys` | Show configured env keys from flow.toml |\n| `sync` | Sync project settings and hub workflow |\n| `bootstrap` | Bootstrap Cloudflare secrets from flow.toml |\n| `unlock` | Unlock env reads (Touch ID on macOS) |\n\n---\n\n## Set\n\nStore a personal environment variable:\n\n```bash\n# Basic set\nf env set API_KEY=sk-xxx\n\n# Personal envs always use the production personal store\nf env set GITHUB_TOKEN=ghp_xxx\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--personal` | | Compatibility flag; `set` already targets personal envs |\n\n## Project Set\n\nStore a project-scoped environment variable:\n\n```bash\nf env project set -e dev DATABASE_URL=postgres://localhost/app\nf env project set -e production PUBLIC_API_BASE_URL=https://api.example.com\n```\n\nNotes:\n- Project cloud writes are sealed by default.\n- On a new device, the first project read/write auto-registers that device as a sealer.\n- If a key exists in cloud but was never shared to this device, Flow will ask you to re-save it from a device that already has access.\n\n---\n\n## Get\n\nRetrieve environment variables:\n\n```bash\n# Get as KEY=VALUE\nf env get API_KEY\n# API_KEY=sk-xxx\n\n# Get just the value\nf env get API_KEY -f value\n# sk-xxx\n\n# Get as JSON\nf env get API_KEY -f json\n# {\"API_KEY\": \"sk-xxx\"}\n\n# Get multiple\nf env get API_KEY DATABASE_URL\n\n# From personal store\nf env get --personal GITHUB_TOKEN -f value\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--format <FORMAT>` | `-f` | Output: `env`, `json`, or `value` (default: env) |\n| `--personal` | | Fetch from personal store |\n\n---\n\n## List\n\nList all environment variables:\n\n```bash\n# List production vars\nf env list\n\n# List staging vars\nf env list -e staging\n```\n\nOutput:\n```\nEnvironment: production\n\n  API_KEY          OpenAI API key\n  DATABASE_URL     PostgreSQL connection string\n  REDIS_URL        -\n```\n\n---\n\n## Run\n\nRun a command with environment variables injected:\n\n```bash\n# Inject all project env vars\nf env run -- npm start\n\n# Inject specific keys\nf env run -k API_KEY -k DATABASE_URL -- node server.js\n\n# From personal store\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n\n# Multiple keys from personal\nf env run --personal -k TELEGRAM_BOT_TOKEN -k TELEGRAM_API_ID -- ./start.sh\n```\n\n### Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--environment <ENV>` | `-e` | Environment (default: production) |\n| `--keys <KEYS>` | `-k` | Specific keys to inject (repeatable) |\n| `--personal` | | Fetch from personal store |\n\n### Examples\n\n```bash\n# Start app with production secrets\nf env run -- npm run start\n\n# Run with staging environment\nf env run -e staging -- npm run dev\n\n# Telegram bot with personal tokens\nf env run --personal -k TELEGRAM_BOT_TOKEN -- pnpm tsx src/bot.ts\n```\n\n---\n\n## Pull\n\nFetch all env vars and write to `.env` file:\n\n```bash\n# Write to .env\nf env pull\n\n# Pull staging vars\nf env pull -e staging\n```\n\nCreates or overwrites `.env` in current directory with all project variables.\n\n---\n\n## Push\n\nUpload local `.env` file to cloud:\n\n```bash\nf env push\n```\n\nReads `.env` from current directory and stores all variables.\n\n---\n\n## Setup\n\nInteractive wizard for pushing env vars:\n\n```bash\nf env setup\n```\n\nIf `[cloudflare] env_source = \"cloud\"` is set in `flow.toml`, this runs a guided\nprompt based on `env_keys`/`env_vars`. Otherwise it guides you through:\n1. Reading your `.env` file\n2. Selecting which keys to push\n3. Confirming before upload\n\n---\n\n## Delete\n\nRemove environment variables:\n\n```bash\n# Delete single key\nf env delete API_KEY\n\n# Delete multiple\nf env delete API_KEY DATABASE_URL\n```\n\n---\n\n## Login\n\nAuthenticate with cloud:\n\n```bash\nf env login\n```\n\nPrompts for API base URL and token. On macOS, the token is stored in Keychain\nand Flow uses Touch ID to unlock env reads.\n\n---\n\n## Status\n\nCheck authentication status:\n\n```bash\nf env status\n```\n\nOutput:\n```\ncloud Status\n  Token: stored in Keychain\n  API: https://myflow.sh\n  Project: myproject\n```\n\n---\n\n## Apply\n\nApply env vars to Cloudflare worker (uses `[cloudflare]` config in flow.toml):\n\n```bash\nf env apply\n```\n\nRequires `env_source = \"cloud\"` in your `[cloudflare]` config.\n\n## Keys\n\nShow env keys configured in `flow.toml` without printing values:\n\n```bash\nf env keys\n```\n\n## Unlock\n\nOn macOS, unlock env reads for the day (Touch ID):\n\n```bash\nf env unlock\n```\n\n---\n\n## Environments\n\nFlow supports three environments:\n\n| Environment | Description |\n|-------------|-------------|\n| `production` | Production secrets (default) |\n| `staging` | Staging/preview secrets |\n| `dev` | Development secrets |\n\nUse `-e` flag with project-scoped commands:\n\n```bash\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env list -e dev\nf env run -e staging -- npm run preview\n```\n\n---\n\n## Personal vs Project Variables\n\n| Type | Flag | Scope | Use Case |\n|------|------|-------|----------|\n| Project | (default for `get`, `list`, `run`, `project ...`) | Current project | API keys, database URLs |\n| Personal | `--personal` | Global/user | GitHub token, Telegram bot token |\n\nPersonal variables are tied to your user account, not a specific project.\n`f env set` writes personal vars. Use `f env project set` for project vars.\n\n```bash\n# Use a personal token in any project\nf env run --personal -k ANTHROPIC_API_KEY -- ./my-script\n```\n\n---\n\n## Env Space Overrides\n\nYou can store project envs under a named cloud space by configuring `env_space`\nand `env_space_kind` in `flow.toml`.\n\n```toml\n# flow.toml\nenv_space = \"nikiv\"\nenv_space_kind = \"personal\"\n```\n\n- `env_space_kind = \"project\"` (default) uses the project name.\n- `env_space_kind = \"personal\"` routes project envs to your personal space.\n\nThis affects `f env pull`, `f env push`, `f env list`, `f env apply`, and service\ntoken creation.\n\n---\n\n## Examples\n\n### Typical Workflow\n\n```bash\n# 1. Authenticate\nf env login\n\n# 2. Set up secrets\nf env project set DATABASE_URL=postgres://... -e production\nf env project set API_KEY=sk-xxx -e production\n\n# 3. Verify\nf env list\n\n# 4. Run app\nf env run -- npm start\n```\n\n### Staging Deploy\n\n```bash\n# Set staging secrets\nf env project set DATABASE_URL=postgres://staging... -e staging\nf env project set API_KEY=sk-test-xxx -e staging\n\n# Test with staging env\nf env run -e staging -- npm run preview\n```\n\n### Personal Tokens for CLI Tools\n\n```bash\n# Store once\nf env set --personal GITHUB_TOKEN=ghp_xxx\nf env set --personal TELEGRAM_BOT_TOKEN=xxx\n\n# Use anywhere\nf env run --personal -k GITHUB_TOKEN -- gh repo list\n```\n\n### In flow.toml Tasks\n\n```toml\n[tasks.start]\ncommand = \"f env run -- npm start\"\n\n[tasks.bot]\ncommand = \"f env run --personal -k TELEGRAM_BOT_TOKEN -- node bot.js\"\n```\n\n---\n\n## Troubleshooting\n\n### \"Not authenticated\"\n\nRun `f env login` to authenticate with cloud.\n\n### \"No env vars found\"\n\nCheck environment name - default is `production`:\n```bash\nf env list -e staging  # Check staging instead\n```\n\n### Variables not injecting\n\nEnsure command comes after `--`:\n```bash\nf env run -k API_KEY -- npm start  # Correct\nf env run -k API_KEY npm start     # May not work\n```\n\n## See Also\n\n- [deploy](deploy.md) - Using env vars in deployments\n- [docs/how-to-use-env.md](../how-to-use-env.md) - Extended usage guide\n\n<!-- File: docs/commands/ext.md (Tokens: ~598 | Category: command-prompt) -->\n# f ext\n\nManage Flow config extensions under `~/.flow/extensions`.\n\nThis is the extension/operator surface for the centralized Flow config system:\n\n- root config: `~/.flow/config.ts`\n- runtime helper: `~/.flow/runtime/flow-config.ts`\n- extension root: `~/.flow/extensions/<name>/`\n\nExtensions are loaded by `f config build` / `f config apply` when their names\nappear in `extensions: [...]` inside `~/.flow/config.ts`.\n\nFor backwards compatibility, `f ext <path>` still supports the older external\ndirectory import workflow into `<project>/ext/<name>`.\n\n## Commands\n\n### f ext list\n\nList built-in and filesystem extensions and whether they are enabled.\n\n```bash\nf ext list\nf ext list --json\n```\n\n### f ext doctor\n\nShow root-config wiring for extensions:\n\n- `~/.flow/config.ts`\n- `~/.flow/extensions`\n- `~/.flow/runtime/flow-config.ts`\n\nand the currently discoverable extensions.\n\n```bash\nf ext doctor\nf ext doctor --json\n```\n\n### f ext init\n\nCreate a new extension scaffold under `~/.flow/extensions/<name>/`.\n\nGenerated files:\n\n- `extension.ts`\n- `README.md`\n\nThe scaffold imports:\n\n- `defineFlowExtension` from `~/.flow/runtime/flow-config.ts`\n\n```bash\nf ext init my-extension\nf ext init my-extension --force\n```\n\n### f ext enable\n\nEnable an extension by name in `~/.flow/config.ts`.\n\n```bash\nf ext enable my-extension\n```\n\n### f ext disable\n\nDisable an extension by name in `~/.flow/config.ts`.\n\n```bash\nf ext disable my-extension\n```\n\n### f ext import\n\nExplicit legacy import form. Copies an external directory into `<project>/ext/`\nand adds `ext/` to `.gitignore`.\n\n```bash\nf ext import ~/some/external/repo\n```\n\nBare path form is still accepted:\n\n```bash\nf ext ~/some/external/repo\n```\n\n## Extension Shape\n\nAn extension file can export:\n\n```ts\nimport { defineFlowExtension } from \"../../runtime/flow-config\"\n\nexport default defineFlowExtension({\n  name: \"my-extension\",\n  flow: { ... },\n  lin: { ... },\n  ai: { ... },\n  hive: { ... }, // migration-only; Flow no longer applies ~/.hive/config.json\n  zerg: { ... },\n  generatedFiles: [\n    {\n      path: \"~/.some/target/file.json\",\n      content: \"{...}\",\n    },\n  ],\n  doctor: [\"human-readable check or note\"],\n})\n```\n\n## Notes\n\n- built-in extension currently supported: `lin-compat`\n- `f ext enable` rewrites `~/.flow/config.ts`\n- `f ext init` also ensures the runtime helper exists\n- generated file path collisions fail the build\n\n<!-- File: docs/commands/failure.md (Tokens: ~281 | Category: command-prompt) -->\n# f failure\n\nInspect and copy recent task failures without manually selecting terminal text.\n\n## Usage\n\n```bash\nf failure\nf failure last\nf failure last --json\nf failure list\nf failure list --json --limit 10\nf failure copy\nf failure copy --format codex\nf failure copy --format codex --write-repo\nf failure copy --format claude\nf failure copy --format excerpt\nf failure copy --format json\n```\n\n## What It Reads\n\nFlow records failures to a stable latest pointer plus versioned history:\n\n```text\n~/.cache/flow/last-task-failure.json\n~/.cache/flow/task-failures/*.json\n```\n\nOverride the latest pointer with:\n\n```bash\nFLOW_FAILURE_BUNDLE_PATH=/tmp/last-task-failure.json\n```\n\n## Notes\n\n- `f failure` defaults to `f failure last`\n- `f failure copy` defaults to the latest failure in `prompt` format\n- `f failure copy --format codex` and `--format claude` render Flow-native repair prompts\n- `f failure copy --write-repo` writes the selected payload to `.ai/internal/failures/`\n- `f failure list --json` is intended for launcher consumers such as Alfred or Lin\n- Set `FLOW_NO_CLIPBOARD=1` to disable clipboard writes\n\n<!-- File: docs/commands/fast.md (Tokens: ~345 | Category: command-prompt) -->\n# f fast\n\nRun AI tasks through the low-latency fast client path.\n\nThis command is optimized for hot-loop invocation and prefers `fai`/`ai-taskd-client` over full `f` task startup.\n\n## Usage\n\n```bash\nf fast ai:flow/noop\nf fast ai:flow/bench-cli -- --iterations 30\nf fast --root ~/code/flow ai:flow/dev-check\nf fast --no-cache ai:flow/dev-check\n```\n\n## Behavior\n\n1. Tries fast client dispatch (`fai`, local `target/.../ai-taskd-client`, or `ai-taskd-client` on PATH).\n2. If daemon is not running, starts `ai-taskd` and retries.\n3. Falls back to direct daemon dispatch if no fast client binary is found.\n\n## Options\n\n- `--root <PATH>`: root directory for `.ai/tasks` discovery (default `.`)\n- `--no-cache`: disable cached binary execution and use direct Moon run\n- `TASK`: required AI selector like `ai:flow/dev-check`\n- trailing args after `--` are passed to the task\n\n## Notes\n\n- `f fast` is intentionally for `ai:*` selectors only.\n- Install `fai` for best latency:\n\n```bash\nf install-ai-fast-client\nf tasks daemon start\nf fast ai:flow/noop\n```\n\nFor pooled burst execution and timings, use `fai` directly:\n\n```bash\nfai --timings ai:flow/noop\nprintf 'ai:flow/noop\\nai:flow/noop\\n' | fai --batch-stdin --timings\n```\n\n<!-- File: docs/commands/global.md (Tokens: ~214 | Category: command-prompt) -->\n# f global\n\nRun tasks from your global flow config (`~/.config/flow/flow.toml`).\n\n## Quick Start\n\n```bash\n# List global tasks\nf global --list\nf global list\n\n# Run a global task from anywhere\nf global repos-clone-safari\nf global run repos-clone-safari\n\n# Match a query against global tasks\nf global match \"clone safari repo\"\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `<TASK>` | | Global task name (omit to list) |\n| `list` | | List global tasks |\n| `run <TASK>` | | Run a global task |\n| `match <QUERY>` | | Match a query against global tasks |\n| `--list` | `-l` | List global tasks |\n| `-- <ARGS...>` | | Pass extra args to the task |\n\n## Examples\n\n```bash\nf global repos-clone-safari https://github.com/0xPlaygrounds/rig\n```\n\n<!-- File: docs/commands/install.md (Tokens: ~448 | Category: command-prompt) -->\n# f install\n\nInstall a CLI/tool binary into your PATH.\n\nDefault backend behavior (`--backend auto`):\n1. Flow registry (`myflow.sh` or `--registry`)\n2. GitHub releases via `parm`\n3. flox package install\n\n## Usage\n\n```bash\nf install <name>\n```\n\n## Options\n\n- `--registry <URL>`: registry base URL (defaults to `FLOW_REGISTRY_URL`).\n- `--backend <auto|registry|parm|flox>`: choose install backend explicitly.\n- `--version <VERSION>`: install a specific version (defaults to latest).\n- `--bin <NAME>`: binary name to install (defaults to manifest default or package name).\n- `--bin-dir <PATH>`: install directory (defaults to `~/bin`).\n- `--force`: overwrite an existing binary.\n- `--no-verify`: skip checksum verification.\n\n## Auto backend notes\n\n- `f install rise` can resolve through `parm` using built-in owner/repo mapping.\n- Built-in aliases:\n  - `f install seqd` resolves registry package `seq` with binary `seqd`.\n  - `f install lin` resolves registry package `flow` with binary `lin`.\n- If a package name is ambiguous for `parm`, set `FLOW_INSTALL_OWNER` (env or Flow personal env store) or pass `owner/repo` directly.\n\n## Bootstrap from installer\n\nThe hosted installer can bootstrap core tools after installing flow:\n\n- `FLOW_BOOTSTRAP_TOOLS=\"rise seq seqd\"` (default) installs those with `f install ... --backend auto`.\n- `FLOW_BOOTSTRAP_TOOLS=0` disables this.\n- `FLOW_BOOTSTRAP_INSTALL_PARM=1` (default) attempts to install `parm` for robust GitHub fallback.\n\n## Registry layout\n\nThe registry must expose:\n\n- `GET /packages/<name>/latest.json`\n- `GET /packages/<name>/<version>/manifest.json`\n- `GET /packages/<name>/<version>/<target>/<bin>`\n\n## Example\n\n```bash\nFLOW_REGISTRY_URL=https://myflow.sh f install flow\n```\n\n```bash\nf install rise\n```\n\n<!-- File: docs/commands/invariants.md (Tokens: ~369 | Category: command-prompt) -->\n# f invariants\n\nValidate project invariants declared in `flow.toml`.\n\nThis command checks the `[invariants]` section and reports violations in changed code.\n\n## Usage\n\n```bash\n# Check all local changes vs HEAD\nf invariants\n\n# Check only staged changes\nf invariants --staged\n```\n\n## What It Checks\n\n1. `forbidden`: disallowed patterns in added diff lines.\n2. `deps.approved`: unapproved dependencies in `package.json` sections (`dependencies`, `devDependencies`, `peerDependencies`).\n3. `files.max_lines`: changed files exceeding the configured line limit.\n\n## Modes\n\nSet in `flow.toml`:\n\n- `mode = \"off\"`: disable checks.\n- `mode = \"warn\"`: print findings, exit success.\n- `mode = \"block\"`: fail command when blocking findings exist.\n\n## Example `flow.toml`\n\n```toml\n[invariants]\nmode = \"block\"\narchitecture_style = \"layered monorepo, event-driven core\"\nnon_negotiable = [\n  \"no inline imports\",\n  \"no any types unless justified\",\n]\nforbidden = [\n  \"git add -A\",\n  \"git reset --hard\",\n]\n\n[invariants.terminology]\n\"pi-ai\" = \"LLM abstraction layer\"\n\"pi-agent\" = \"stateful agent runtime\"\n\n[invariants.deps]\npolicy = \"approval_required\"\napproved = [\"@sinclair/typebox\", \"@reatom/core\"]\n\n[invariants.files]\nmax_lines = 300\n```\n\n## Commit Integration\n\n`f commit` runs the invariant gate during commit-with-check flow.\n\n- In `mode = \"block\"`, commits are blocked on invariant warnings/critical findings.\n- Invariant context and findings are injected into AI review prompts.\n\n<!-- File: docs/commands/jj.md (Tokens: ~1147 | Category: command-prompt) -->\n# jj\n\nFlow wraps common Jujutsu (jj) workflows so you can stay in jj while remaining fully Git-compatible.\n\n## Quick start\n\n```bash\n# Inspect workspace + home-branch state\nf status\n\n# Initialize jj (colocated with git when .git exists)\nf jj init\n\n# Create a feature bookmark and track origin\nf jj bookmark create feature-x --track\n\n# Fetch + rebase onto main + push bookmark\nf jj sync --bookmark feature-x\n```\n\n## Commands\n\n- `f status` — Show workflow-aware JJ status (workspace, home branch, leaf branches, working-copy summary, and next-step hints)\n- `f jj status` — Show raw `jj st`\n- `f jj fetch` — `jj git fetch`\n- `f jj rebase --dest <branch>` — Rebase onto `jj.default_branch` (or main/master)\n- `f jj push --bookmark <name>` — Push a single bookmark\n- `f jj push --all` — Push all bookmarks\n- `f jj sync --bookmark <name>` — Fetch, rebase, then push bookmark\n- `f jj workspace add <name> [--path <dir>] [--rev <rev>]` — Create a workspace (optionally anchored to a revision)\n- `f jj workspace lane <name> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create an isolated parallel lane from trunk defaults\n- `f jj workspace review <branch> [--path <dir>] [--base <rev>] [--remote <name>] [--no-fetch]` — Create or reuse a stable JJ review workspace for a branch without touching the current checkout\n- `f jj workspace list` — List workspaces\n- `f jj bookmark create <name> [--rev <rev>] [--track]` — Create bookmark\n- `f jj bookmark track <name> [--remote <remote>]` — Track remote bookmark\n\n## Status-first workflow\n\nUse `f status` before branch, workspace, commit, or publish operations.\n\nIt is the fast way to answer:\n\n- which workspace am I in?\n- am I on the long-lived home branch or a branch-specific leaf?\n- what review or codex branches currently sit on top of the home branch?\n- is the working copy clean enough to mutate safely?\n\nExample:\n\n```bash\ncd ~/code/org/project\nf status\n```\n\nUse `f jj status` only when you want the raw Jujutsu working-copy view.\n\n## Parallel lanes (no interleaving)\n\nUse lanes when you want multiple active tasks in one repo without stash/pop churn:\n\n```bash\n# In your current repo, create isolated lanes anchored from trunk\nf jj workspace lane fix-otp\nf jj workspace lane testflight\n\n# Work each lane independently\ncd ~/.jj/workspaces/<repo>/fix-otp\njj st\n```\n\n`f jj workspace lane` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. chooses base as `<default_branch>@<remote>` when tracked (fallback: `<default_branch>`)\n3. creates a dedicated workspace with its own `@` working-copy commit\n\n## Review workspaces\n\nUse a review workspace when you want an isolated JJ working copy for a review branch without\ntouching the current repo checkout:\n\n```bash\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/<repo>/review-alice-feature\njj st\n```\n\n`f jj workspace review` does:\n\n1. `jj git fetch` (unless `--no-fetch`)\n2. reuses the existing review workspace when present\n3. otherwise anchors the workspace at the local branch commit, then the remote branch commit, then trunk\n4. prints the stable workspace path plus the JJ bookmark command to publish later\n\nImportant:\n\n- The review workspace is JJ-native. Use `jj` or `f jj` inside it.\n- In colocated repos, plain `git` still points at the main checkout, so this command intentionally does not run `flow switch` for you.\n\n## Config\n\nAdd to `flow.toml`:\n\n```toml\n[git]\nremote = \"myflow-i\"  # optional preferred writable remote\n\n[jj]\ndefault_branch = \"main\"\nhome_branch = \"alice\" # optional long-lived personal integration branch\nremote = \"origin\"     # optional legacy fallback if [git].remote is unset\nauto_track = true\n```\n\nThis keeps jj aligned with Git remotes while you work locally in jj.\n\n## Home-branch model\n\nIf you keep a long-lived personal branch on top of trunk, set `jj.home_branch` and treat it as\nyour integration branch.\n\nWhen the current branch matches that home branch, plain `f sync` also switches into home-branch\nmode and syncs `origin/<default-branch>` into it instead of using the normal tracking pull.\n\nThen use short-lived `review/*` or `codex/*` branches on top of that home branch for task-specific\nwork. `f status` is optimized to make that shape visible.\n\nRecommended flow:\n\n```bash\n# Default checkout stays on your home branch\ncd ~/code/org/project\nf status\n\n# Branch-specific work happens in isolated workspaces\nf jj workspace review review/alice-feature\ncd ~/.jj/workspaces/project/review-alice-feature\nf status\n```\n\nSee also:\n\n- [`jj-review-workspaces.md`](../jj-review-workspaces.md)\n- [`jj-home-branch-workflow.md`](../jj-home-branch-workflow.md)\n\n<!-- File: docs/commands/migrate.md (Tokens: ~967 | Category: command-prompt) -->\n# f migrate\n\nMove or copy a project folder to a new location, preserving symlinks and AI sessions.\n\n## Overview\n\nRelocates a project directory and automatically migrates Claude and Codex AI sessions so conversation history follows the project. Also relinks any `~/bin` symlinks that pointed into the old path (move only).\n\n## Quick Start\n\n```bash\n# Move current directory into ~/code/lang/cpp/stream\ncd ~/code/lang/cpp/stream\nf migrate code stream\n\n# Move current directory to an arbitrary path\nf migrate ~/code/stream\n\n# Move a specific source to a target\nf migrate ~/code/lang/cpp/stream ~/code/stream\n\n# Preview what would happen (no changes)\nf migrate --dry-run code stream\n\n# Copy instead of move (keeps original)\nf migrate --copy code stream\n```\n\n## Your case\n\nTo migrate `~/code/lang/cpp/stream` to `~/code/stream`:\n\n```bash\ncd ~/code/lang/cpp/stream\nf migrate code stream\n```\n\nOr without `cd`:\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\nPreview first with `--dry-run`:\n\n```bash\nf migrate --dry-run ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Usage Forms\n\n### `f migrate code <relative>`\n\nMoves the current directory into `~/code/<relative>`. This is the most common form.\n\n```bash\ncd ~/old/location/myproject\nf migrate code myproject          # -> ~/code/myproject\nf migrate code lang/rust/mylib    # -> ~/code/lang/rust/mylib\n```\n\n### `f migrate <target>`\n\nMoves the current directory to `<target>` (any absolute or relative path).\n\n```bash\ncd ~/old/location/myproject\nf migrate ~/code/myproject\n```\n\n### `f migrate <source> <target>`\n\nMoves `<source>` to `<target>` without needing to `cd` first.\n\n```bash\nf migrate ~/code/lang/cpp/stream ~/code/stream\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--copy` | `-c` | Copy instead of move (keeps the original intact) |\n| `--dry-run` | | Show what would change without writing anything |\n| `--skip-claude` | | Skip migrating Claude Code sessions |\n| `--skip-codex` | | Skip migrating Codex sessions |\n\n## What Happens\n\n### Step 1: Move or copy the folder\n\nThe project directory is moved (or copied with `--copy`) to the target path. Parent directories are created automatically. Cross-device moves are handled transparently (copy + delete).\n\n### Step 2: Relink ~/bin symlinks (move only)\n\nAny symlinks in `~/bin` that pointed into the old path are updated to point to the new location. Skipped when using `--copy`.\n\n### Step 3: Migrate AI sessions\n\nClaude and Codex store project sessions keyed by filesystem path. Migrate updates these so conversation history is preserved at the new location.\n\n- **Claude sessions**: Project directories under `~/.claude/projects/` are renamed from the old path-based key to the new one.\n- **Codex sessions**: Legacy project directories are renamed, and `.jsonl` session files referencing the old path are updated in-place.\n\nA summary is printed showing how many session dirs/files were migrated.\n\n## Examples\n\n```bash\n# Move project into ~/code, nested path\ncd ~/downloads/cool-project\nf migrate code tools/cool-project\n\n# Copy a project (keeps original)\nf migrate --copy ~/code/app ~/backup/app\n\n# Dry run to preview\nf migrate --dry-run code stream\n\n# Move without migrating AI sessions\nf migrate --skip-claude --skip-codex ~/old/path ~/new/path\n\n# Move and only migrate Claude (skip Codex)\nf migrate --skip-codex code myproject\n```\n\n## Troubleshooting\n\n### \"Destination already exists\"\n\nThe target path must not exist. Remove or rename the existing directory first, or choose a different target.\n\n### \"Source and destination are the same path\"\n\nBoth paths resolve to the same location. Double-check your arguments.\n\n### Session migration warnings\n\nAfter a move, you may see warnings like:\n\n```\nWARN Claude session dir still present: ...\nWARN Codex sessions still reference the old path:\n  /path/to/file.jsonl\n```\n\nThese mean some sessions couldn't be fully migrated. You can manually inspect or delete the referenced files.\n\n## See Also\n\n- [repos](repos.md) - Clone repositories into structured layout\n\n<!-- File: docs/commands/new.md (Tokens: ~367 | Category: command-prompt) -->\n# f new\n\nCreate a new project from a local starter template under `~/new`.\n\n## Overview\n\n`f new` copies a directory from `~/new/<template>` into a destination path.\n\nThis is the native Flow way to work with local starters you keep in `~/new`.\n\n## Usage\n\n```bash\nf new [template] [path]\n```\n\n- `template`: folder name inside `~/new` (for example `app`, `docs`, `web`)\n- `path`: destination path (optional)\n\nIf `template` is omitted, Flow opens an `fzf` picker from templates in `~/new`.\n\n## Path Resolution Rules\n\nFlow resolves the destination path like this:\n\n```bash\nf new app          # -> ./app\nf new app zerg     # -> ~/code/zerg\nf new app ./xn     # -> ./xn\nf new app ~/xn     # -> ~/xn\n```\n\nNotes:\n- Plain names (no `./`, `../`, `/`, `~`) are treated as `~/code/<name>`.\n- Use `~/...` or absolute paths for custom locations outside `~/code`.\n\n## Dry Run\n\nPreview copy behavior without writing files:\n\n```bash\nf new app ~/xn --dry-run\n```\n\n## Starter Workflow\n\n1. Create or update starter in `~/new/<template>`.\n2. Generate a new project with `f new <template> <target>`.\n3. Enter the new project and run its setup/dev tasks with Flow.\n\nExample:\n\n```bash\nf new app ~/xn\ncd ~/xn\nf tasks\n```\n\n## Common Errors\n\n- `Template not found`: `~/new/<template>` does not exist.\n- `Destination already exists`: remove/rename target path or choose a new destination.\n\n<!-- File: docs/commands/pr.md (Tokens: ~581 | Category: command-prompt) -->\n# f pr\n\nCreate or open GitHub pull requests, edit PR text locally, and pull review feedback.\n\n## Quick Start\n\n```bash\n# Create/update PR from current changes (default base: main)\nf pr \"assistant improvements\"\n\n# Open current branch PR in browser\nf pr open\n\n# Edit PR title/body in local markdown and sync on save\nf pr open edit\n\n# Pull actionable review feedback for current PR\nf pr feedback\n\n# Pull feedback for specific PR and store as local todos\nf pr feedback 8 --todo\nf pr feedback https://github.com/owner/repo/pull/8 --todo\n\n# Full inline diff/review context is now the default\nf pr feedback 8\n\n# Use terse terminal output if needed\nf pr feedback 8 --compact\n```\n\n## Feedback Workflow\n\n`f pr feedback` fetches:\n\n- PR reviews (`/pulls/<n>/reviews`)\n- Inline review comments (`/pulls/<n>/comments`)\n- Top-level PR comments (`/issues/<n>/comments`)\n\nIt then:\n\n1. Prints an actionable list in terminal with inline review state and diff hunk context by default.\n2. Writes a markdown snapshot to `.ai/reviews/pr-feedback-<pr>.md`.\n3. Writes a machine-readable JSON snapshot to `.ai/reviews/pr-feedback-<pr>.json`.\n4. Writes a human review plan to `~/docs/plan/review/<repo>-pr-<pr>-feedback.md`.\n5. Writes a PR-local execution artifact to `~/docs/plan/review/<repo>-pr-<pr>-review-rules.md`.\n6. Writes a Kit system prompt to `~/docs/plan/review/<repo>-pr-<pr>-kit-system.md`.\n7. Optionally (`--todo`) records feedback into `.ai/todos/todos.json` with dedupe via external refs.\n\nThe review plan includes ready-to-run `kit` commands for:\n\n- deterministic repo review via `kit review`\n- preventative lint/review rule synthesis from the fetched GitHub feedback set\n\nThe generated `*-review-rules.md` artifact contains the per-item resolution loop,\nprompt template, required response sections, and Kit-upgrade decision order so\nthe workflow can be reopened without extra instructions.\n\n## Notes\n\n- If no selector is passed, Flow resolves the PR from the current branch.\n- `f pr feedback --todo` is safe to re-run; existing feedback refs are not duplicated.\n- `f pr feedback` is full-context by default. Use `--compact` if you want the older terse terminal view.\n- `f pr feedback` now emits a Kit-ready handoff, so the same feedback set can drive a future review bot instead of staying trapped in GitHub comments.\n- `f pr open edit` remains the quickest path to tweak PR title/body from local editor.\n\n<!-- File: docs/commands/publish.md (Tokens: ~902 | Category: command-prompt) -->\n# f publish\n\nPublish projects to GitHub.\n\n## Overview\n\nCreates a new GitHub repository and pushes the current project. Automatically infers the repo name from the folder name and handles both new repos and existing ones.\n\n## Quick Start\n\n```bash\n# Interactive mode - prompts for name and visibility\nf publish\n\n# Skip prompts, use folder name, default to private\nf publish -y\n\n# Create public repo\nf publish --public\n\n# Create with specific name\nf publish --name my-awesome-project\n```\n\n## Options\n\n| Option | Short | Description |\n|--------|-------|-------------|\n| `--name <NAME>` | `-n` | Repository name (defaults to folder name) |\n| `--public` | | Create as public repository |\n| `--private` | | Create as private repository |\n| `--description <DESC>` | `-d` | Repository description |\n| `--yes` | `-y` | Skip prompts, use defaults (private, folder name) |\n\n## Prerequisites\n\n- [GitHub CLI](https://cli.github.com/) installed (`gh`)\n- Authenticated with `gh auth login`\n\n## Usage\n\n### Interactive Mode\n\nWithout flags, prompts for configuration:\n\n```bash\n$ f publish\n\nRepository name [my-project]:\nVisibility (public/private) [private]: public\n\nCreate repository:\n  Name: username/my-project\n  Visibility: public\n\nProceed? [Y/n]:\n```\n\n### Non-Interactive Mode\n\n```bash\n# Use all defaults (private, folder name as repo name)\nf publish -y\n\n# Public repo with defaults\nf publish -y --public\n\n# Specific name and description\nf publish -n cool-tool -d \"A cool CLI tool\" --public\n```\n\n### Existing Repositories\n\nIf the repository already exists on GitHub:\n\n1. Checks current visibility\n2. Updates visibility if different from requested\n3. Adds origin remote if missing\n4. Pushes current branch\n\n```bash\n$ f publish --public\nRepository username/my-repo already exists (private).\nUpdating visibility to public...\n✓ Updated to public\n\n✓ https://github.com/username/my-repo\n```\n\n## What Happens\n\n1. **Check gh CLI** - Verifies GitHub CLI is installed\n2. **Check authentication** - Ensures you're logged in to GitHub\n3. **Get username** - Fetches your GitHub username\n4. **Determine repo name** - Uses `--name`, folder name, or prompts\n5. **Determine visibility** - Uses `--public`/`--private` or prompts\n6. **Check if exists** - If repo exists, updates visibility if needed\n7. **Initialize git** - If not a git repo, runs `git init`\n8. **Create initial commit** - If no commits, stages all and commits\n9. **Create repository** - Uses `gh repo create` with `--source=. --push`\n10. **Output URL** - Prints the GitHub URL\n\n## Examples\n\n### Quick Publish New Project\n\n```bash\ncd my-new-project\nf publish -y --public\n# ✓ Published to https://github.com/username/my-new-project\n```\n\n### Publish with Description\n\n```bash\nf publish -n api-server -d \"REST API for my app\" --private\n```\n\n### Update Existing Repo Visibility\n\n```bash\n# Repo exists as private, make it public\nf publish --public\n# Repository username/my-repo already exists (private).\n# Updating visibility to public...\n# ✓ Updated to public\n```\n\n### In Scripts/CI\n\n```bash\n#!/bin/bash\ncd /path/to/project\nf publish -y --public -n release-candidate\n```\n\n## Troubleshooting\n\n### \"GitHub CLI (gh) is not installed\"\n\nInstall from https://cli.github.com:\n\n```bash\n# macOS\nbrew install gh\n\n# Linux\nsudo apt install gh  # or equivalent\n```\n\n### \"GitHub authentication required\"\n\nRun `gh auth login` and follow the prompts.\n\n### \"Could not determine GitHub username\"\n\nEnsure you're authenticated: `gh auth status`\n\n### Repository exists but can't update visibility\n\nSome visibility changes may require specific permissions or GitHub plan features.\n\n## See Also\n\n- [deploy](deploy.md) - Deploy after publishing\n- [upstream](upstream.md) - Managing forks\n\n<!-- File: docs/commands/readme.md (Tokens: ~1451 | Category: command-prompt) -->\n# Flow Commands Reference\n\nComplete documentation for all `f` (flow) commands.\n\n## Quick Reference\n\n| Command | Description |\n|---------|-------------|\n| [`deploy`](deploy.md) | Deploy to Linux hosts, Cloudflare Workers, or Railway |\n| [`release`](release.md) | Publish a release to registry or GitHub |\n| [`publish`](publish.md) | Publish project to GitHub |\n| [`install`](install.md) | Install a CLI/tool via registry, parm, or flox |\n| [`clone`](clone.md) | Clone repositories with git-like destination behavior |\n| [`repos`](repos.md) | Clone repositories into ~/repos |\n| [`new`](new.md) | Create a project from a local template in ~/new |\n| [`commit`](commit.md) | AI-powered commit with code review |\n| [`pr`](pr.md) | Create/open PRs and ingest GitHub feedback |\n| [`upstream`](upstream.md) | Manage upstream fork workflow |\n| [`env`](env.md) | Sync project environment and manage env vars |\n| [`config`](config.md) | Build and apply centralized Flow config outputs |\n| [`ext`](ext.md) | Manage Flow config extensions |\n| [`invariants`](invariants.md) | Validate project invariants from `flow.toml` |\n| [`fast`](fast.md) | Low-latency AI task invocation via fast client |\n| [`up`](up.md) | Bring a project up with lifecycle conventions |\n| [`down`](down.md) | Bring a project down with lifecycle conventions |\n| [`domains`](domains.md) | Shared local `*.localhost` route manager on port 80 |\n| [`tasks`](tasks.md) | List and run project tasks |\n| [`failure`](failure.md) | Inspect and copy recent task failures |\n| [`global`](global.md) | Run tasks from global flow config |\n| [`setup`](setup.md) | Print aliases or run setup task |\n| [`ai`](ai.md) | Manage AI coding sessions (Claude + Codex) |\n| [`daemon`](daemon.md) | Manage background daemons |\n| [`parallel`](parallel.md) | Run tasks in parallel |\n| [`docs`](docs.md) | Manage auto-generated documentation |\n| [`web`](web.md) | Open the Flow web UI for a project |\n| [`url`](url.md) | Inspect or crawl URLs into compact AI-friendly summaries |\n\n## Getting Started\n\n```bash\n# Show all commands\nf --help\n\n# Get help for a specific command\nf deploy --help\nf commit --help\n```\n\n## Command Categories\n\n### Deployment\n\n- **[deploy](deploy.md)** - Deploy to hosts and cloud platforms\n- **[release](release.md)** - Publish releases to registries\n- **[publish](publish.md)** - Publish project to GitHub\n\n### Version Control\n\n- **[commit](commit.md)** - AI-powered commits with review\n- **[pr](pr.md)** - PR creation/editing plus review feedback ingestion\n- **[clone](clone.md)** - Clone with git-like destination behavior\n- **[repos](repos.md)** - Clone repos into a structured directory\n- **[upstream](upstream.md)** - Fork management and sync\n- **[fixup](fixup.md)** - Fix common TOML syntax errors\n\n### Task Management\n\n- **[tasks](tasks.md)** - List project tasks\n- **[failure](failure.md)** - Inspect and copy recent task failures\n- **[fast](fast.md)** - Run AI tasks through the low-latency fast client path\n- **[up](up.md)** - Start project lifecycle (`up`/`dev`) with optional domains setup\n- **[down](down.md)** - Stop project lifecycle with optional domains teardown\n- **[global](global.md)** - Run tasks from ~/.config/flow/flow.toml\n- **[setup](setup.md)** - Print aliases or run setup task\n- **[run](run.md)** - Run a specific task\n- **[parallel](parallel.md)** - Run tasks in parallel\n- **[rerun](rerun.md)** - Re-run last task\n- **[search](search.md)** - Fuzzy search global commands\n\n### Process Management\n\n- **[ps](ps.md)** - List running flow processes\n- **[kill](kill.md)** - Stop running processes\n- **[logs](logs.md)** - View task logs\n- **[daemon](daemon.md)** - Manage background daemons\n\n### AI & Development\n\n- **[ai](ai.md)** - Manage AI coding sessions\n- **[url](url.md)** - Inspect or crawl URLs into compact summaries for AI use\n- **[agent](agent.md)** - Invoke AI subagents\n- **[match](match.md)** - Match natural language to tasks\n- **[sessions](sessions.md)** - Search AI sessions across projects\n\n### Environment & Configuration\n\n- **[env](env.md)** - Manage environment variables\n- **[config](config.md)** - Build/apply the centralized Flow config snapshot\n- **[ext](ext.md)** - Scaffold, enable, disable, and inspect Flow config extensions\n- **[invariants](invariants.md)** - Validate invariant policies in `flow.toml`\n- **[domains](domains.md)** - Shared local domain proxy ownership and route management\n- **[init](init.md)** - Scaffold a new flow.toml\n- **[doctor](doctor.md)** - Verify tools and integrations\n\n### Project Management\n\n- **[new](new.md)** - Create a project from a local starter in `~/new`\n- **[projects](projects.md)** - List registered projects\n- **[active](active.md)** - Show or set active project\n- **[hub](hub.md)** - Ensure hub daemon is running\n\n### Documentation\n\n- **[docs](docs.md)** - Manage auto-generated documentation\n- **[commits](commits.md)** - Browse commits with AI metadata\n\n### Legacy Compatibility\n\n- **[recipe](recipe.md)** - Legacy recipe command (hidden; prefer `tasks` + `.ai/tasks/*.mbt`)\n\n### Other\n\n- **[skills](skills.md)** - Manage Codex skills\n- **[install](install.md)** - Install binaries via registry/parm/flox\n- **[db](db.md)** - Manage databases and providers\n- **[tools](tools.md)** - Manage AI tools\n- **[notify](notify.md)** - Send proposal notifications\n- **[server](server.md)** - Start HTTP server for logs\n\n## Global Options\n\n```bash\n-h, --help     Print help\n-V, --version  Print version\n```\n\n## Configuration\n\nFlow uses `flow.toml` for project configuration. See [flow.toml reference](../flow-toml.md) for full documentation.\n\n## See Also\n\n- [Getting Started Guide](../getting-started.md)\n- [flow.toml Reference](../flow-toml.md)\n\n<!-- File: docs/commands/recipe.md (Tokens: ~297 | Category: command-prompt) -->\n# f recipe\n\nLegacy compatibility command.\n\nPreferred model:\n\n- Put shell tasks in `flow.toml` under `[[tasks]]`.\n- Put AI/native tasks in `.ai/tasks/*.mbt`.\n- Run via `f <task>` or `f ai:<selector>`.\n\n`f recipe` remains for older repos that still use `.ai/recipes`.\n\n## Usage\n\n```bash\nf recipe list          # legacy listing\nf recipe run <selector> # legacy execution\n```\n\n## Options\n\n- `--scope <project|global|all>`: recipe source scope (default `all`)\n- `--global-dir <PATH>`: override global recipes directory\n- `--cwd <PATH>` (run only): working directory for execution\n- `--dry-run` (run only): print command without executing\n\n## Legacy Recipe Locations\n\n- Project recipes: `.ai/recipes/project` (fallback `.ai/recipes`).\n- Global recipes: `~/.config/flow/recipes`.\n\nSupported extensions: `.md`, `.markdown`, `.mbt`\n\nMoonBit recipe metadata is optional and can be declared in top comment lines:\n\n```mbt\n// title: My Fast Recipe\n// description: Run a moonbit action quickly\n// tags: [moonbit, fast]\n```\n\n## Migration\n\n```bash\n# Old\nf recipe run project:my-recipe\n\n# New\nf tasks init-ai\nf ai:my-task\n```\n\n<!-- File: docs/commands/release.md (Tokens: ~212 | Category: command-prompt) -->\n# f release\n\nRelease a project based on `flow.toml` defaults or explicit subcommands.\n\n## Usage\n\n```bash\nf release\nf release registry\nf release gh\n```\n\n## Registry releases\n\n```bash\nf release registry\n```\n\n### flow.toml\n\n```toml\n[release]\ndefault = \"registry\"\nversioning = \"calver\"\n\n[release.registry]\nurl = \"https://myflow.sh\"\npackage = \"flow\"\nbins = [\"flow\", \"f\", \"lin\"]\ndefault_bin = \"flow\"\ntoken_env = \"FLOW_REGISTRY_TOKEN\"\nlatest = true\n```\n\n### Options\n\n- `--version <VERSION>`: publish a specific version.\n- `--registry <URL>`: override the registry base URL.\n- `--bin <NAME>`: override the binaries to upload (repeatable).\n- `--no-build`: skip building binaries.\n- `--latest` / `--no-latest`: control latest pointer updates.\n\n## GitHub releases\n\n```bash\nf release gh\n```\n\n<!-- ... +14 more modular skills available via /api/skills/nikivdev/flow?path={path} -->\n</yakaai_skills>"}