@fml-inc/fml 0.7.0 → 0.8.0-rc.2

package/.claude-plugin/plugin.json

@@ -1,13 +1,11 @@
 {
   "name": "fml",
-  "version": "0.7.0",
+  "version": "0.8.0-rc.2",
   "description": "FML agent tools for Claude Code",
   "mcpServers": {
     "fml": {
       "command": "node",
-      "args": [
-        "${CLAUDE_PLUGIN_ROOT}/bin/mcp-server"
-      ]
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/mcp-server"]
     }
   }
 }

package/README.md

@@ -1,61 +1,266 @@
-# FML
+# FML CLI
 
-Agent tools for AI coding assistants. Installs as a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) with MCP tools for session analytics, cost tracking, integrations, and team workflows — powered by [Panopticon](https://github.com/fml-inc/panopticon) for local data collection.
+`@fml-inc/fml` is the single published FML command-line package. It provides
+the `fml` command, account and organization authentication, agent MCP
+integration, cloud-backed product commands, and raw artifact sync.
+
+Panopticon is an internal workspace engine under `packages/panopticon`. Its
+raw-sync implementation is bundled into this package at build time; users do
+not install or run a second Panopticon package.
 
 ## Install
 
+Node.js 22.15 or newer and npm are required.
+
+On macOS, Linux, and compatible Bash environments, install with:
+
 ```bash
-npm install -g @fml-inc/fml
+curl -fsSL https://fml.inc/install.sh | bash
 ```
 
-This installs the plugin, registers hooks and MCP tools in Claude Code, and bootstraps Panopticon for local data collection. Start a new session to activate.
-
-Then sign in:
+For Windows or manual installation, run:
 
 ```bash
-fml login
+npm install --global @fml-inc/fml
+fml setup
 ```
 
-## For LLM agents
+Run `fml update` to upgrade the global package with npm. Stable releases stay
+on npm's `latest` channel; prerelease versions stay on `next`.
 
-Setting up FML from inside a coding-agent sandbox (Claude Code, Codex, Gemini CLI, etc.)? Paste this to your agent:
+Installing the package does not change agent configuration. Run `fml setup`
+to register every supported FML agent integration, sign in when needed, and
+restart the observer. It installs the agent-native FML skill, configures the
+FML MCP server, and registers capture-only lifecycle hooks for supported
+agents. Invoke the skill as `/fml review` in Claude, Gemini, or Grok, and as
+`$fml review` in Codex. Review runs inside the agent from the packaged skill;
+it is not an `fml review` CLI command. Start a new agent session after setup so
+it picks up the integration. FML pre-approves only the isolated command hooks
+it installs for Codex; use `/hooks` to review or disable them.
 
-```
-Follow the installation instructions here: https://github.com/fml-inc/observe/blob/main/docs/agent_installation_guide.md
+The Claude plugin is MCP-only. FML installs the workflow through each host's
+native skill directory so it keeps the bare `fml` name without a second,
+plugin-namespaced skill.
+
+For a coding agent operating in a sandbox, use the
+[agent installation guide](./docs/agent_installation_guide.md).
+
+## Upgrading from standalone Panopticon
+
+Earlier releases shipped as a separate `@fml-inc/panopticon` package that
+installed its own Claude plugin, agent hooks, MCP server, OpenTelemetry
+settings, and shell environment. `fml install` does not migrate that install.
+Retire it first, from the machine that has it, before installing FML:
+
+```bash
+panopticon uninstall --purge
 ```
 
-The guide covers: `npm install -g @fml-inc/fml` → `fml install` → `fml login --device` (the agent relays the verification URL to you, you paste the code back) → `fml doctor`. No browser, no `gh` CLI, no manual shell-profile edits needed.
+`panopticon uninstall --purge` stops the standalone daemon and removes its
+plugin, hooks, MCP registrations, shell block, and generated data directory.
+Then follow the [Install](#install) steps above for a clean setup. If the old
+`panopticon` command is already gone, reinstall `@fml-inc/panopticon` just to
+run its uninstall, or clean up by hand: remove the `# >>> panopticon >>>` block
+from your shell profile, delete the data directory (macOS:
+`~/Library/Application Support/panopticon`; Linux: `~/.local/share/panopticon`;
+Windows: `%APPDATA%\panopticon`), and remove any leftover `panopticon` entries
+from the Claude plugin registration (`~/.claude/settings.json` and
+`~/.claude/plugins/`), agent hook configs (`~/.codex/config.toml`,
+`~/.codex/hooks.json`, `~/.gemini/settings.json`, `~/.grok/hooks/`), and MCP
+server registrations in those same agent config files.
+
+## Raw artifact sync
+
+Sync uploads original, file-backed agent artifacts to FML. It does not parse
+them into local session, message, tool-call, or scanner tables. Server-side
+scanners own parsing and projections.
+
+Discovery covers supported local stores across Claude Code, Codex, Gemini,
+Grok, Cursor, Pi, Copilot CLI, and Factory Droid, including archived Codex
+sessions. Availability depends on which harnesses have written artifacts on
+the machine.
+
+Sync has one persistent setting: enabled or disabled. It defaults to enabled.
+The backend environment, login, and selected organization determine the upload
+destination; there is no user-configurable sync-target list.
 
-## What it does
+```bash
+fml sync                 # Discover and drain pending raw artifacts
+fml sync --dry-run       # Show what would be discovered without changing the queue
+fml sync status          # Show enabled state, queue counts, and byte watermarks
+fml sync disable         # Stop discovery and upload
+fml sync enable          # Allow discovery and upload again
+fml sync reset           # Clear watermarks and replay every local artifact from byte zero
+fml start                # Start the observer and continuously run enabled raw sync
+fml restart              # Stop and start the observer
+fml stop                 # Stop the observer and disable raw sync
+```
 
-**Local observability** — Panopticon captures OpenTelemetry signals, hook events, session files, and API traffic from Claude Code, Gemini CLI, and Codex CLI into a local SQLite database.
+`fml sync reset` preserves the enabled/disabled setting and source files. It
+clears local upload progress and gives tracked artifacts fresh generations, so
+the next enabled `fml sync` performs a full replay. Reset refuses to race an
+active sync.
+
+For automation, the sync commands support `--json`. `fml start` enables raw
+sync and launches a detached observer with a loopback-only HTTP endpoint. The
+observer runs sync immediately, retries in the background, and follows later
+`fml env` and `fml org` changes. `fml sync disable` pauses only raw discovery
+and upload. Capture-only hooks continue writing to their durable local outbox
+and uploading in the background. `fml stop` disables raw sync, records an
+explicit hook-capture pause, and stops the complete observer runtime. Either
+`fml start` or `fml sync enable` clears that pause. A crash or reboot does not
+pause capture: handler inbox files remain durable until the observer returns.
+
+The observer keeps a SQLite database for runtime bookkeeping and the
+durable hook outbox. It is operational state, not a local copy of session,
+message, scanner, or analytics tables. Hermes discovery and sync remain
+deferred.
+
+The database is `panopticon.db` under FML's platform-native operational-state
+root:
+
+| Platform | Account/configuration (`FML_DATA_DIR`) | Operational database                                  |
+| -------- | -------------------------------------- | ----------------------------------------------------- |
+| macOS    | `~/Library/Application Support/fml`    | `~/Library/Application Support/fml/panopticon.db`     |
+| Linux    | `${XDG_DATA_HOME:-~/.local/share}/fml` | `${XDG_STATE_HOME:-~/.local/state}/fml/panopticon.db` |
+| Windows  | `%APPDATA%\fml`                        | `%LOCALAPPDATA%\fml\panopticon.db`                    |
+
+The cutover is forward-only: the observer starts with a clean database at the
+new path and does not migrate or delete the former
+`~/.fml/panopticon/observer.db`. `fml start` reports that retained path whenever
+the file still exists; when replacing a live legacy observer, it also reports
+the old observer's pending row count. The PID state, lease/lock, endpoint,
+auth-token files, hook inbox, and raw-sync watermarks remain under the
+separately configurable observer directory.
+
+Use `FML_STATE_DIR` to relocate the operational database and `FML_DATA_DIR` to
+relocate account and environment configuration. For compatibility, an explicit
+`FML_DATA_DIR` also relocates the database when `FML_STATE_DIR` is absent. It
+does not relocate logs or observer coordination state: those retain their
+platform defaults unless `FML_LOG_DIR` or an observer override is set.
+`FML_OBSERVER_DIR` directly relocates observer coordination state;
+`PANOPTICON_HOME` is a legacy alias for that directory and `FML_HOME` is a
+legacy parent whose `panopticon` child is used. These observer-only aliases do
+not relocate the database or account configuration. Because that pattern used
+to isolate the pre-cutover database as well, `fml start` and the observer warn
+at startup when an observer-only alias is set without `FML_STATE_DIR` or
+`FML_DATA_DIR`; set one of those to choose the database root explicitly.
+
+Every explicit FML directory override must be absolute; relative values are
+rejected so processes launched from different working directories cannot
+silently select different state. Relative XDG and Windows shell-directory
+variables are ignored in favor of the platform fallback.
+
+The filesystems containing `FML_STATE_DIR` and `FML_OBSERVER_DIR` must support
+same-directory hard links. FML uses that atomic primitive to publish complete
+observer lease records without exposing a partially written database lock;
+standard APFS, ext4, and NTFS volumes support it.
+
+For multiple fully isolated FML instances, configure absolute, dedicated
+`FML_DATA_DIR`, `FML_LOG_DIR`, and `FML_OBSERVER_DIR` roots per instance.
+`FML_DATA_DIR` also isolates the database unless a separate `FML_STATE_DIR` is
+set. Configuring a distinct `FML_OBSERVER_PORT` is also recommended. A
+database-scoped runtime lease rejects a second observer that resolves to the
+same `panopticon.db`; give that instance a different data or state root and
+start it again.
+
+## Hook capture
+
+FML installs capture-only hooks for Claude Code, Codex, Gemini CLI, and Grok
+CLI. It also configures direct MCP entries for Codex, Gemini, Grok, and Claude
+Desktop. The hook handler reads the agent's JSON event, first commits an
+owner-only per-delivery file, then sends it only to the authenticated loopback
+observer, and always returns an empty JSON object. It does not make permission
+decisions, inject context, or contact FML directly.
+
+The observer commits each event to SQLite before removing its handler-side
+delivery file. Files left by a stopped, restarting, busy, or unavailable
+observer are replayed with the same sync ID, so a timeout cannot create a
+duplicate or silently drop the event. A separate uploader sends stable,
+idempotent batches through `/v2/sync` to the selected FML environment and
+account, then removes local rows only after the server acknowledges them.
+Repository authorization is evaluated per row across every organization the
+account can access; hook delivery does not depend on the currently selected
+organization. `fml status` reports both the handler inbox and SQLite outbox.
+
+Each capture with known login state is durably bound to its exact FML URL,
+and stable account identity; switching environments or accounts cannot upload
+or acknowledge another destination's rows. Captures made while logged out
+remain unbound until the first authenticated destination atomically claims that
+backlog.
+
+The handler-side inbox is a short-lived durability bridge for times when the
+observer is stopped or unavailable. It is bounded independently from the
+SQLite spool: by default it accepts at most 512 MiB or 10,000 delivery files,
+whichever is reached first. At a limit it preserves older committed files,
+refuses the newest inbox write, and still fails open for the invoking agent; a
+running observer can still accept that event directly. `fml status` reports
+the active limits and cumulative capacity refusals.
+
+Set `FML_HOOK_INBOX_MAX_BYTES` and `FML_HOOK_INBOX_MAX_ENTRIES` in the coding
+agent's environment to change these limits. Bytes accept the same `B`, `KiB`,
+`MiB`, and `GiB` suffixes described below; entries are positive integers. An
+explicit `unbounded` opts out of either limit. These settings affect only the
+per-delivery file inbox and do not change normal SQLite spool retention.
+
+The hook spool is unbounded by default. To bound it, set
+`FML_HOOK_SPOOL_MAX_BYTES` when starting the observer:
 
-**MCP tools for your agent** — Once installed, Claude Code gets tools to query your sessions, costs, activity, and connected integrations directly in conversation.
+```bash
+FML_HOOK_SPOOL_MAX_BYTES=512MiB fml start
+```
 
-**Cloud sync** — Optionally sync local data to the FML dashboard for team-wide visibility, config snapshots, and automations.
+The value is a positive integer in bytes with an optional `B`, `KiB`, `MiB`,
+or `GiB` suffix. Unset it, or set it to `unbounded`, to retain the full spool
+without a size limit. Invalid values (including `0`) stop observer startup
+instead of silently disabling the limit. Restart a running observer after
+changing the setting.
+
+This is a logical-content limit: it counts the UTF-8 bytes retained in hook
+fields and their destination or rejection metadata across pending and
+quarantined rows, not SQLite page, index, or WAL overhead. When the limit is
+exceeded, the observer evicts the oldest quarantined rows first and then the
+oldest pending rows. It never fails a hook invocation merely because the spool
+is full. `fml status` reports current logical bytes, the configured maximum,
+cumulative eviction counts and bytes, and the last eviction time.
+
+Terminally rejected rows are retained for 30 days by default, independently
+of the pending spool's unbounded default. Set
+`FML_HOOK_QUARANTINE_MAX_AGE_DAYS` to a positive integer to change that window,
+or to `unbounded` to retain quarantine rows until the byte bound evicts them.
+Expired quarantine rows contribute to the same persisted eviction counters.
+Retryable pending rows are never removed by this age policy.
+
+The spool retains complete hook payloads and extracted fields, which can
+include prompts, commands, file paths, plans, and tool output. FML-created
+directories request owner-only permissions, and the SQLite database and
+sidecars are tightened to owner-only modes on platforms that support POSIX
+modes. An existing caller-supplied state directory retains its directory mode.
 
 ## MCP tools
 
-These tools are available to Claude Code via the plugin:
-
-| Tool | Description |
-|------|-------------|
-| `get_engineering_activity` | Activity summary — sessions, prompts, tools, costs |
-| `list_engineering_sessions` | List recent sessions with stats |
-| `search_engineering_sessions` | Search across all sessions |
-| `get_session_timeline` | Messages and tool calls for a session |
-| `get_session_turns` | Per-turn token usage for a session |
-| `get_ai_spending` | Token usage and cost breakdowns |
-| `whoami` | Current auth and org status |
-| `fml_list_integrations` | Connected integrations (Slack, GitHub, Linear, Sentry, etc.) |
-| `fml_query_*` | Query connected integrations directly |
-| `fml_list_messages` | Conversation messages |
-| `fml_search_analysis` | Search codebase analysis results |
-| `fml_run_analysis_workflow` | Run deep analysis workflows |
-| `fml_list_skills` | Browse and load skills |
-| `list_repo_configs` | Team config snapshots |
-
-For agents or scripts that need backend tools not exposed as dedicated MCP tools yet, use the dynamic CLI catalog:
+The MCP server exposes FML tools for session analytics, cost tracking,
+integrations, team workflows, and account context, including:
+
+| Tool                          | Description                                                 |
+| ----------------------------- | ----------------------------------------------------------- |
+| `get_engineering_activity`    | Activity summary across sessions, prompts, tools, and costs |
+| `list_engineering_sessions`   | List recent sessions with stats                             |
+| `search_engineering_sessions` | Search across sessions                                      |
+| `get_session_timeline`        | Messages and tool calls for a session                       |
+| `get_session_turns`           | Per-turn token usage for a session                          |
+| `get_ai_spending`             | Token usage and cost breakdowns                             |
+| `whoami`                      | Current auth and organization status                        |
+| `fml_list_integrations`       | Connected integrations                                      |
+| `fml_query_*`                 | Query connected integrations                                |
+| `fml_list_messages`           | Conversation messages                                       |
+| `fml_search_analysis`         | Search codebase analysis results                            |
+| `fml_run_analysis_workflow`   | Run analysis workflows                                      |
+| `fml_list_skills`             | Browse and load skills                                      |
+| `list_repo_configs`           | Team configuration snapshots                                |
+
+For backend tools not yet exposed as dedicated MCP tools, use the dynamic
+catalog:
 
 ```bash
 fml tools list --json
@@ -63,62 +268,101 @@ fml tools describe <tool-name> --json
 fml tools call <tool-name> --args '{"key":"value"}'
 ```
 
-## CLI
-
-```
-fml install              Register plugin, hooks, and daemons
-fml uninstall            Remove plugin and hooks
-  --target <t>           Target: claude, gemini, codex, claude-desktop, all
-  --purge                Also remove all data, logs, and auth tokens
-fml update               Update to the latest version
-
-fml login                Sign in to your FML account
-fml logout               Sign out and clear credentials
-fml org [slug]           Show or select organization
-fml status               Show auth and daemon status
-fml doctor               Check configuration and connectivity
-
-fml open                 Open FML dashboard in browser
-fml start                Start local collection and sync
-fml stop                 Stop local collection and sync
-
-fml tools                List backend tools from the dynamic catalog
-fml tools list           List backend tools from the dynamic catalog
-fml tools describe <n>   Show a backend tool schema
-fml tools call <n>       Invoke a backend tool with JSON args
-
-fml activity             Activity summary
-  --since <duration>     Time window (e.g. "24h", "7d")
+## CLI overview
+
+```text
+fml setup                Install integrations, sign in if needed, and start FML
+fml install              Register FML agent integrations and the MCP server
+fml uninstall            Remove agent integration; add --purge to remove local state
+fml update               Update @fml-inc/fml with npm (stable: latest; prerelease: next)
+
+fml start                Start the local observer and continuous raw sync
+fml restart              Stop and start the local observer
+fml stop                 Stop the local observer and disable raw sync
+
+fml login                Sign in to FML
+fml logout               Clear stored credentials
+fml org [slug]           Show or select an organization
+fml env [name-or-url]    Show or select a backend environment
+fml status               Show auth, environment, and raw-sync status
+fml doctor               Check auth, environment, organization, raw sync, and API access
+fml open                 Open the FML dashboard
+
+fml sync                 Upload raw local artifacts
+fml sync enable          Enable raw artifact sync
+fml sync disable         Disable raw artifact sync
+fml sync status          Show queue counts and byte watermarks
+fml sync reset           Replay all raw artifacts from byte zero
+
+fml tools                Browse and invoke backend tools
+fml activity             Show an activity summary
 fml sessions             List recent sessions
-fml timeline <id>        Events for a session
-fml spending             Token usage and cost breakdown
-fml search <query>       Search across sessions
-
-fml sync setup           Configure sync targets
-fml sync list            List sync targets
-fml sync add <n> <url>   Add a sync target
-fml sync remove <name>   Remove a sync target
-fml sync status          Show sync status
-fml sync reset [name]    Reset sync watermarks
+fml timeline <id>        Show events for a session
+fml spending             Show token usage and cost breakdowns
+fml search <query>       Search sessions
 ```
 
+Run `fml --help` or `fml commands` for the complete command inventory.
+
 ## Development
 
+Run from the repository root:
+
 ```bash
-pnpm install       # Install dependencies
-pnpm dev           # Watch mode (tsup)
-pnpm test          # Run tests (Vitest)
-pnpm type-check    # Type check
+pnpm install
+pnpm --filter @fml-inc/fml type-check
+pnpm --filter @fml-inc/fml test
+pnpm --filter @fml-inc/fml build
 ```
 
-To test the full install flow:
+Build, pack, and install the same artifact that will be published:
 
 ```bash
-pnpm build && pnpm pack
-npm install -g ./fml-inc-fml-*.tgz
+pnpm --filter @fml-inc/fml pack:local
+pnpm add --global ./apps/cli/fml-inc-fml-*.tgz
+fml --version
 fml install
 ```
 
+The packed manifest must not contain runtime dependencies on
+`@fml/panopticon` or `@fml/agent-targets`; both private workspace packages are
+bundled into the CLI.
+
+## Release
+
+The [FML CLI release workflow](../../.github/workflows/publish-fml-cli.yml)
+publishes the exact package that passes the packed-install smoke test. Create a
+tag named `fml-v<semver>` on a commit reachable from `main`, then push the tag:
+
+```bash
+git tag -a fml-v0.8.0 -m "Release FML CLI 0.8.0"
+git push origin fml-v0.8.0
+```
+
+Stable versions use npm's default `latest` tag. SemVer prereleases such as
+`fml-v0.9.0-beta.1` publish under `next`. Each release must advance the version
+currently assigned to its npm channel; the workflow rejects stable versions
+that do not advance `latest` and prereleases that do not advance `next`.
+Release tags may not contain SemVer build metadata. Keep
+`apps/cli/package.json` at `0.0.0-dev` on `main`; the workflow stamps the
+release version before building.
+
+The `@fml-inc/fml` package must have one npm trusted publisher configured with
+these exact values:
+
+- Provider: GitHub Actions
+- Organization: `fml-inc`
+- Repository: `fml`
+- Workflow: `publish-fml-cli.yml`
+- Environment: `npm`
+- Allowed action: `npm publish`
+
+The GitHub `npm` environment should allow only `fml-v*` tags and may require a
+reviewer. The publish job has no npm token, source checkout, dependency
+installation, or build step; it receives only the smoke-tested tarball and its
+checksum. npm provenance is disabled because the source repository is private,
+while OIDC trusted publishing remains enabled.
+
 ## License
 
 Proprietary — see [LICENSE](LICENSE).

package/agent-assets/fml/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: fml
+description: Route explicit FML requests to FML MCP tools, CLI operations, or the built-in branch and pull-request review workflow. Use when the user invokes /fml or $fml, explicitly asks to use FML, requests an FML command or tool, or asks for `fml review`. The `review` route is an agent workflow, never an `fml review` CLI command.
+---
+
+<!-- fml-managed-agent-surface:v1 -->
+
+# FML Agent Router
+
+Use this skill as FML's agent-native command surface. Route a request to an
+FML MCP tool, an actual `fml` CLI command, or an agent workflow defined here.
+
+## Invocation contract
+
+Use the user text that activated this skill. Different hosts may preserve
+trailing text in the original prompt, append an arguments annotation, or
+deliver it immediately after activation. Treat that accompanying text as
+`<command> [args...]`; do not depend on one host's invocation syntax or
+argument-substitution behavior.
+
+For an explicit skill invocation, parse the first trailing token as the
+subcommand. For a natural-language invocation, infer a subcommand only from
+the user's explicit FML request. With no subcommand, show concise help and do
+not run a command merely to fill the response.
+
+## Routing rules
+
+1. Select `review` before doing CLI or MCP discovery. If the subcommand is
+   `review`, or the user explicitly asks for the FML review workflow, perform
+   the complete review workflow below in this agent session. `review` is not
+   an FML CLI subcommand. Never execute `fml review` or delegate the workflow
+   to the CLI.
+2. For structured read-only data, prefer a dedicated FML MCP tool when one is
+   available. Prefer the CLI for install, authentication, lifecycle, observer,
+   environment, and sync operations.
+3. If command coverage is unclear, run `fml commands`. For backend tools, run
+   `fml tools list --json` and `fml tools describe <name> --json`; do not guess
+   tool names or argument schemas.
+4. FML activity and history commands read data synced to the selected FML
+   organization. If the user explicitly asks for unsynced, machine-local
+   session data, explain that this command surface does not expose a local
+   analytics database.
+5. Apply the host's normal approval and safety rules to writes and destructive
+   actions. Never silently run `sync reset`, `uninstall --purge`, integration
+   writes, automation mutations, memory writes or deletes, or analysis runs.
+6. Summarize large structured results unless the user asks for raw output.
+
+## Common routes
+
+- `review`: follow the complete pull-request review workflow below in the
+  current agent session.
+- Install, auth, environment, observer, lifecycle, or sync: use the CLI command
+  discovered through `fml commands` or command help.
+- Read-only activity, history, spending, configuration, integration, or
+  provenance: use the matching FML MCP tool by its live description, with a
+  CLI fallback when available.
+- Backend tool list, description, or invocation: use `fml tools ...` and
+  describe unfamiliar tools before calling them.
+- Automations, memory, analysis runs, integration writes, or other mutations:
+  discover the live schema, explain the change, and obtain any required
+  approval before invoking it.
+
+If the preferred route is unavailable, use the listed fallback and say which
+fallback was used.
+
+## CLI discovery
+
+Use runtime discovery instead of relying on a static command inventory:
+
+```bash
+fml commands
+fml tools list --json
+fml tools list --category integrations --json
+fml tools describe <name> --json
+fml tools call <name> --args '<json>'
+fml tools call <name> --file <path>
+```
+
+Prefer `--file` for multiline or nested JSON. Run `fml <command> --help` before
+using an unfamiliar bespoke command.
+
+## Authentication and failures
+
+- Use `fml doctor` to diagnose authentication, organization, observer, sync,
+  environment, and API connectivity.
+- Use `fml login --device` when an interactive browser callback is unavailable.
+- Never print or copy credential-store files or token values.
+- Report the failed command and the relevant error. Do not retry indefinitely.
+
+## Pull-request review workflow
+
+Apply this entire section for the `review` route.
+
+### 1. Establish the review scope
+
+1. Read repository instructions that govern the changed files.
+2. Determine the current branch and base ref. Prefer an explicitly supplied
+   base or PR base. Otherwise use the remote default from
+   `refs/remotes/origin/HEAD`, then fall back to a local `main` or `master`.
+   Do not fetch or mutate branches solely to perform the review.
+3. Inspect the branch and working-tree scope separately:
+
+   ```bash
+   git status --short
+   git diff --stat <base>...HEAD
+   git diff --find-renames <base>...HEAD
+   git log --oneline --decorate <base>..HEAD
+   git diff
+   git diff --cached
+   ```
+
+4. Read complete changed files and relevant callers, tests, schemas, or
+   configuration when the diff alone is insufficient.
+
+State the chosen base and whether uncommitted changes are included. If no
+reliable base can be determined, ask the user rather than inventing one.
+
+### 2. Review the code
+
+Prioritize defects that could affect users or maintainers:
+
+- correctness, edge cases, and error handling
+- security, authorization, privacy, and secret handling
+- data loss, unsafe migrations, and irreversible operations
+- concurrency, retries, idempotency, and partial failure
+- compatibility across supported platforms and agent targets
+- public contracts, packaging, install/uninstall symmetry, and upgrade paths
+- missing tests for meaningful behavior or regression risk
+
+Do not report formatting preferences or speculative concerns as defects. Trace
+the actual execution path and cite the smallest useful file and line location.
+Each finding must explain the triggering conditions, concrete impact, and a
+practical repair direction.
+
+### 3. Use FML context only for unresolved intent
+
+Finish the code-based review before consulting FML. If a finding or design
+question remains ambiguous, use read-only FML context:
+
+- `fml_commit_context` for branch commits
+- `fml_path_history` for the history of a changed path
+- `fml_pr_context` when the pull-request number is known
+- `search_engineering_sessions`, followed by `get_session_timeline`, for
+  relevant synced implementation sessions
+
+CLI fallbacks are `fml search`, `fml sessions`, and `fml timeline`. If FML is
+unavailable, unauthenticated, or has no matching data, note that briefly and
+complete the review from repository evidence. Never use historical intent to
+excuse a concrete defect in the current code.
+
+Put any material provenance answer after the verdict under
+`Follow-up: FML-sourced intent`, clearly separated from the findings.
+
+### 4. Report
+
+Lead with findings, ordered by severity:
+
+```text
+Findings
+
+- [P1] Short imperative title — path/to/file.ts:42
+  Explain the triggering scenario, impact, and repair direction.
+
+Questions / assumptions
+
+- Only questions that materially affect the review.
+
+Verdict
+
+Request changes | Approve with comments | Approve
+
+Follow-up: FML-sourced intent
+
+- Include only if FML resolved a lingering question.
+```
+
+Use `P0` for release-blocking or catastrophic risk, `P1` for serious defects,
+`P2` for normal correctness or maintainability defects, and `P3` sparingly for
+minor actionable issues. If there are no findings, say so explicitly and call
+out any meaningful test or evidence gap in the verdict.