@empirical-gauzza/cli 1.0.35 → 1.0.37

package/lib/constants.js

@@ -1,657 +1,672 @@
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-
-const EMPIRICAL_MCP_NAME = 'empirical';
-const EMPIRICAL_MCP_LEGACY_NAMES = ['empirical-live'];
-const EMPIRICAL_MCP_URL = process.env.EMPIRICAL_MCP_URL || 'https://empirical.gauzza.com/mcp';
-const COPILOT_OAUTH_CLIENT_ID = process.env.EMPIRICAL_COPILOT_OAUTH_CLIENT_ID || 'copilot-cli-empirical';
-
-// These two lists mirror the schema-level enums in packages/shared/src/memoryGraph.ts.
-// They are duplicated rather than imported on purpose: this CLI publishes to npm as
-// @empirical-gauzza/cli, and @empirical/shared is a private workspace package, so depending
-// on it would break `npm install` for end users. tests/unit/cliMemoryEnumParity.test.js
-// fails CI if the copies ever diverge.
-const MEMORY_CATEGORIES = [
-  'health', 'fitness', 'food', 'supplement', 'mood', 'idea', 'business',
-  'build', 'growth', 'learning', 'leadership', 'operations', 'workflow',
-  'lead', 'project', 'recipe', 'preference', 'reflection', 'relationship', 'heartbeat'
-];
-
-const NODE_TYPES = [
-  'event', 'entity', 'observation', 'reflection', 'goal', 'concept'
-];
-
-const DOC_TOPICS = {
-  memory: `# Empirical Memory Commands
-
-Use the \`empirical memory\` subcommands to query and manage memories via the REST API.
-All commands require a valid access token (see \`empirical doc auth\`).
-Errors are written to stderr as JSON. Successful output is written to stdout as JSON.
-
-## Subcommands
-
-### query
-Search memories by natural language.
-
-    empirical memory query --match "coding style preferences" [--top-k 3] [--category build] [--tags ts,node] [--pretty] [--format table]
-
-Flags:
-- \`--match\` (required): natural language search string
-- \`--top-k\`: number of results, 1–100, default 3
-- \`--category\`: filter by category
-- \`--tags\`: comma-separated tags filter
-- \`--tags-all\`: comma-separated tags that must ALL be present (AND match)
-- \`--status\`: comma-separated status values to keep (for example open,in_progress)
-- \`--due-before\`, \`--due-after\`: keep only reminders due in that window (ISO 8601 dates).
-  "What is due?" is \`--due-before <now> --remind-state pending\`; dueness is a filter, never
-  something semantic ranking finds on its own
-- \`--remind-state\`: comma-separated reminder states to keep: pending, notified, acknowledged, cancelled
-- \`--path\`: pin one retrieval pathway (see below)
-- \`--hops\`: 1 or 2, graph depth; only valid with \`--path graph\` or \`--path hebbian\`
-- \`--pretty\`: pretty-print JSON output
-- \`--format table\`: render results as a table instead of JSON (JSON stays the default)
-
-#### Retrieval pathways
-
-- \`--path semantic\`: ranked meaning match. Runs the embedding search and scores candidates.
-  Use it when you are asking a question and want the closest few answers.
-- \`--path list\`: filtered browse. Skips ranking and returns the matching set in order, with
-  paging. Use it when you want everything carrying a tag, status, or category, not a top few.
-- \`--path graph\`: relationship walk from the best entry points, out \`--hops\` steps. Use it
-  when what you want is connected to what you can name rather than worded like it.
-- \`--path hebbian\`: co-recall walk, following the links that repeated retrieval strengthened.
-  Use it when you want what usually comes up alongside this, not what merely resembles it.
-
-Omitting \`--path\` keeps the default, where the classifier decides which pathway answers.
-
-### get
-Retrieve one memory by exact ID.
-
-    empirical memory get --memory-id <id> [--pretty]
-
-### list
-Browse memories deterministically. Use \`--cursor\` from the previous response while \`pagination.hasMore\` is true.
-
-    empirical memory list [--category project] [--tags canonical,launch] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty] [--format table]
-
-Flags:
-- \`--category\`, \`--tags\`: optional filters
-- \`--start-date\`, \`--end-date\`: createdAt bounds
-- \`--limit\`: page size, 1–100, default 20
-- \`--cursor\`: continuation cursor from a previous page
-- \`--oldest\`: sort oldest first; default is newest first
-- \`--pretty\`: pretty-print JSON output
-- \`--format table\`: render results as a table instead of JSON (JSON stays the default)
-
-### acknowledge
-Close a due reminder from the terminal.
-
-    empirical memory acknowledge --memory-id <id> [--cancel]
-
-Marks the reminder done (or dropped, with \`--cancel\`), frees its slot on your plan, and clears
-its alert on every surface so no agent keeps relaying it. The id is in the reminder banner.
-
-### record
-Save a new memory.
-
-    empirical memory record --category build --summary "Use ESM modules for all new packages" [--tags ts,node] [--node-type observation] [--author-type user|agent] [--due <ISO date>]
-
-\`--due <ISO date>\` turns the memory into a REMINDER: at that time you get one email with a
-calendar entry attached. Accepts 2026-10-14 or a full timestamp like 2026-10-14T09:00:00Z.
-Any memory can carry one. Plans cap CONCURRENT pending reminders rather than how many you
-create per month, so acknowledging or cancelling one frees a slot.
-
-\`--author-type\` records WHO the fact belongs to, which the transport cannot know. Use
-\`user\` for something the user said, decided or prefers; \`agent\` for your own session notes
-and findings. Omitted, it is left unresolved rather than guessed. Retrieval reads it to keep
-agent notes out of answers about the user's own life and work.
-
-Passing text that contains code (backticks, \${...}, $(...)): do NOT put it in a double-quoted
-\`--summary "..."\` -- the shell substitutes those away before the CLI runs and the write still
-succeeds with the code silently missing. Use one of:
-
-    empirical memory record --category build --summary-file ./note.md --tags ts
-    empirical memory record --category build --summary - --tags ts <<'EOF'
-    Use \`createChat()\`; raw calls leak \${stage} and 400.
-    EOF
-
-(a single-quoted heredoc delimiter, 'EOF', disables substitution). From an MCP-connected agent,
-prefer the record_graph_memory tool, which takes JSON and never touches a shell.
-
-Flags:
-- \`--category\` (required unless --json-file): memory category
-- \`--summary\` (required unless --summary-file/--json-file): memory summary text; \`-\` reads stdin
-- \`--summary-file\`: path to a file whose contents become the summary (safe for code)
-- \`--tags\`: comma-separated tags
-- \`--node-type\`: node type, default \`observation\`
-- \`--json-file\`: path to JSON file with full memory payload
-
-Both \`--category\` and \`--node-type\` are closed sets. Do not guess a value: anything outside
-these lists is rejected and the write does not happen.
-
-Valid categories (20): health, fitness, food, supplement, mood, idea, business, build, growth,
-learning, leadership, operations, workflow, lead, project, recipe, preference, reflection,
-relationship, heartbeat.
-
-Valid node types (6): event, entity, observation, reflection, goal, concept.
-
-There is no \`product\` category and no \`decision\` node type. Record a decision as
-\`--category project --node-type event\`.
-
-### note
-Add a note to an existing memory.
-
-    empirical memory note --match "ESM modules" --text "confirmed in monorepo migration" [--min-score 0.35]
-
-Flags:
-- \`--match\` (required unless --memory-id): search string to find the memory
-- \`--text\` (required): note text to append
-- \`--memory-id\`: use exact memory ID (skips fuzzy search)
-- \`--min-score\`: minimum similarity score, default 0.35
-
-### update
-Update an existing memory.
-
-    empirical memory update --match "ESM modules" --patch-json '{"summary":"Updated summary"}' [--min-score 0.35]
-
-Flags:
-- \`--match\` (required unless --memory-id): search string
-- \`--patch-json\`: JSON string with fields to update
-- \`--json-file\`: path to JSON patch file
-- \`--memory-id\`: use exact memory ID
-- \`--min-score\`: minimum similarity score, default 0.35
-
-### delete
-Delete a memory. Without --confirm, runs a dry-run and prints what would be deleted.
-
-    empirical memory delete --match "old preference" --confirm [--min-score 0.35]
-
-Flags:
-- \`--match\` (required unless --memory-id): search string
-- \`--confirm\`: actually delete (without this, dry-run only)
-- \`--memory-id\`: use exact memory ID
-- \`--min-score\`: minimum similarity score, default 0.35
-
-Bulk delete by tag, category, or everything (exactly one selector):
-
-    empirical memory delete --tag old-preference --confirm
-    empirical memory delete --category recipe --confirm
-    empirical memory delete --all --confirm
-
-Without \`--confirm\`, always a dry-run that prints the count that would be deleted; no writes
-happen. Re-run with \`--confirm\` to actually delete.
-
-### export / import
-Export memories to a versioned, round-trippable JSON document and re-import them later.
-
-    empirical memory export --scope <personal|workspace> [--out <path>] [--workspace-id <id>]
-    empirical memory import <file> [--dry-run]
-
-Export writes \`{ schemaVersion: 1, exportedAt, memories: [...] }\`. Import reads that same
-shape and POSTs each row through the normal create endpoint, so imported memories get the same
-dedupe and auto-link treatment as any other write. \`--dry-run\` on import prints the count that
-would be imported without writing anything.
-
-### stats
-Aggregated counts, scoped to the caller.
-
-    empirical memory stats [--format table]
-
-Returns total count, counts by category, counts by tag, and oldest/newest memory timestamps.
-
-### compact
-On-demand near-duplicate scan (the same logic the nightly compaction job runs), scoped to the
-caller only. Dry-run by default, matching a terraform plan/apply model.
-
-    empirical memory compact [--category <cat>]
-    empirical memory compact --apply [--category <cat>]
-
-Without \`--apply\`, reports proposed merge/link candidate pairs and counts with no writes.
-With \`--apply\`, executes the merges and links for real and reports what was applied.
-
-## Error output contract
-- Errors → stderr as JSON: \`{ "error": true, "code": "...", "message": "..." }\`
-- Success → stdout as JSON (compact by default)
-`,
-
-  install: `# Empirical Install
-
-    empirical install
-
-Runs the interactive installer to connect Empirical memory to your AI coding CLI(s).
-
-## What it does
-1. Detects installed CLIs: Codex, GitHub Copilot, Claude Code
-2. Prompts for CLI target selection
-3. Asks how agents should interact with Empirical:
-   - Mode 1: Via MCP tool (recommended) — registers Empirical as an MCP server
-   - Mode 2: Via CLI commands — writes CLI-direct instruction block, no MCP registration
-   - Mode 3: Both — MCP primary with CLI fallback
-4. Stores the personalized behavior policy for the native Empirical Memory Skill; global
-   instruction files are left unchanged
-5. Offers optional browser OAuth login for CLI use, optional headless/API-key bootstrap for
-   automation, containers, and external runtimes, and optional work-history/scar-tissue guidance
-6. Installs a \`SessionStart\` hook for each selected client that calls the \`empirical\` CLI
-   directly once per session — deterministic baseline context that doesn't depend on the model
-   deciding to call a tool. Claude: \`~/.claude/settings.json\`. Codex: \`<CODEX_HOME>/hooks.json\`
-   (defaults to \`~/.codex\`). Copilot: \`~/.copilot/hooks/empirical-session-start.json\`.
-7. Installs the native \`empirical-memory\` plugin for each selected client. The plugin owns
-   the Empirical MCP connection and all agent-facing Skills; the CLI does not generate duplicate
-   \`SKILL.md\` or \`EMPIRICAL_SKILL.md\` files.
-
-## Native plugin only
-
-    empirical plugin install <codex|copilot|claude|all> [--all-optional]
-
-    empirical plugin check [--force]
-
-Installs or refreshes only the native marketplace plugin. It does not run the MCP/auth questionnaire
-or modify global instruction files. With no target, the command installs for detected CLIs.
-
-The CLI performs a best-effort native plugin version check during interactive use (at most once per
-day). It is silent for noninteractive/headless commands. Use \`empirical plugin check --force\` to
-check immediately.
-
-Use \`empirical policy show\` to inspect the current native-skill behavior policy and
-\`empirical policy set --json '{"allowDiscretionaryUse":false}'\` to change it without rerunning
-the installer. The policy is cached locally and refreshed when stale.
-`,
-
-  workspace: `# Empirical Workspace Commands
-
-Manage disposable team workspaces and which Empirical workspace is active for this OAuth client.
-
-## Commands
-
-### List workspaces
-
-    empirical workspace list
-
-Shows all available workspaces and which one is currently selected.
-
-### Show current workspace
-
-    empirical workspace current
-
-Prints the currently selected workspace name.
-
-### Select a workspace
-
-    empirical workspace select [<number|name>]
-
-Interactive workspace selector (prompts if no argument given).
-Pass a number (from \`list\`) or an exact workspace name.
-
-    empirical workspace select 2
-    empirical workspace select "My Workspace"
-
-Note: workspace selection may be admin-locked for some OAuth clients.
-
-### Create a demo workspace
-
-    empirical workspace create "Demo Workspace" --description "Temporary shared context"
-
-Creates a team workspace using your existing plan quota and prints its workspace ID.
-
-### Use a workspace
-
-    empirical workspace use <number|name|id>
-
-Friendly alias for \`workspace select\`. It accepts the list number, exact case-insensitive name, or workspace ID.
-
-### Share an active workspace
-
-    empirical workspace invite create --role writer --expires-in-days 7 --max-uses 3
-    empirical workspace invite list
-    empirical workspace invite revoke <token>
-
-Invite commands operate on the active team workspace. Create prints a shareable URL.
-
-### Soft-delete a demo workspace
-
-    empirical workspace delete <number|name|id>
-    empirical workspace delete <number|name|id> --confirm
-
-Deletion dry-runs by default. \`--confirm\` calls the existing soft-delete endpoint; the Default Workspace cannot be deleted. If the active workspace is deleted, the CLI selects the Default Workspace.
-`,
-
-  doctor: `# Empirical Doctor
-
-    empirical doctor [--output json] [--deep]
-
-Checks the health of your Empirical CLI setup, including why MCP tools might not be showing up
-in a host CLI (the most common failure report).
-
-## Checks performed
-
-1. **Token presence** — verifies a token exists via EMPIRICAL_ACCESS_TOKEN env, apiKey field,
-   or accessToken field in the token file
-2. **Token type** — detects API key (long alphanumeric, no dots) vs JWT (3 dot-separated parts)
-3. **Token expiry** — if JWT, decodes the payload and checks the \`exp\` field; warns if no \`exp\`
-4. **API connectivity** — calls GET /api/v1/users/me; 200 = OK, anything else = FAIL
-5. **Workspace** — reads workspaceId from the /api/v1/users/me response; warns if null
-6. **MCP hosts detected** — which of codex/claude/copilot were found on this machine
-7. **MCP config registration (per detected host)** — reads that host's own config file
-   (\`~/.claude.json\`, \`<CODEX_HOME>/config.toml\`, \`~/.copilot/mcp-config.json\`) and confirms
-   the Empirical MCP server is actually registered there with the current URL
-8. **MCP reachability** — POSTs a real MCP \`initialize\` request to the MCP endpoint with the
-   resolved access token and confirms a valid JSON-RPC response comes back
-9. **Native plugin presence/version (per detected host)** — runs \`<host> plugin list\` and
-   reports the installed empirical-memory (and optional) plugin versions
-10. **Hooks presence (per detected host)** — confirms the SessionStart/UserPromptSubmit/Stop
-    hook scripts exist on disk and are registered in that host's hook manifest
-
-## --deep
-
-Adds a live write/query/delete round trip: records a \`doctor-probe-<timestamp>\` memory, queries
-it back, deletes it, and reports elapsed time for each leg. Requires a valid token; writes and
-deletes exactly one throwaway memory tagged \`doctor-probe\`.
-
-## Output format
-
-Default: human-readable lines prefixed with [OK], [WARN], or [FAIL].
-
-    empirical doctor --output json
-
-JSON output: \`{ "checks": [{ "name", "status", "message" }], "overall": "ok"|"warn"|"fail" }\`
-Useful for agent/automation use.
-
-## Exit codes
-- 0: all checks passed (ok or warn)
-- 1: one or more checks failed
-`,
-
-  agents: `# Empirical Agent Integration
-
-Empirical memory integrates with three AI coding CLIs.
-
-## Supported agents
-
-| Agent       | Config dir          | Instruction file              | MCP config                          |
-|-------------|---------------------|-------------------------------|-------------------------------------|
-| Claude Code | ~/.claude/          | CLAUDE.md                     | ~/.claude.json (mcpServers)         |
-| Codex CLI   | ~/.codex/           | AGENTS.md                     | codex mcp add                       |
-| Copilot CLI | ~/.copilot/         | copilot-instructions.md       | ~/.copilot/mcp-config.json          |
-
-## Integration modes
-
-**Mode 1: MCP tool (recommended)**
-Empirical is registered as an MCP server. Agents call memory tools (query_memories,
-record_graph_memory, etc.) directly via the MCP protocol. Best for interactive sessions.
-
-**Mode 2: CLI commands**
-Agents run \`empirical memory <subcommand>\` shell commands. No MCP registration required.
-Suitable for headless/scripted environments or when MCP is unavailable.
-
-**Mode 3: Both**
-MCP is primary; CLI commands are available as fallback. Maximizes reliability.
-
-## Inventory commands
-
-    empirical skill list
-    empirical device list
-    empirical device show <deviceId>
-
-Use these to inspect Skills across Kits and the effective Skills installed for a device.
-
-The native \`empirical-memory\` plugin owns its Skills and MCP connection. Run
-\`empirical install\` to install it and configure detected agents.
-`,
-
-  kit: `# Empirical Skills Kits
-
-Kits are named collections of agent Skills. A Kit can contain Skills authored in Empirical
-or discovered from a git repository, then sync the resolved set to your local agents.
-
-## Commands
-
-### Create and list Kits
-
-    empirical kit create "My Team Kit"
-    empirical kit list
-
-### Add or remove a git source
-
-    empirical kit add-source "My Team Kit" https://github.com/example/skills.git
-    empirical kit add-source "My Team Kit" https://github.com/example/skills.git --ref main --path skills
-    empirical kit remove-source "My Team Kit" <source-id>
-
-Each source is scanned for valid \`SKILL.md\` files. A Skill file must begin with YAML
-frontmatter containing both \`name\` and \`description\`, for example:
-
-    ---
-    name: my-skill
-    description: Explain when this skill should be used.
-    ---
-
-### Activate and sync
-
-    empirical kit use "My Team Kit"
-    empirical kit sync
-    empirical kit sync --dry-run
-
-\`kit use\` activates a Kit on this device and syncs its Skills into detected agent
-directories. \`kit sync\` refreshes the active Kit. Use \`--quiet\` for unattended syncs
-and \`--force\` only when you intentionally want to bypass the local-edit guard.
-
-### Inventory
-
-    empirical skill list
-    empirical kit list
-    empirical kit devices "My Team Kit"
-    empirical device list
-    empirical device show <deviceId>
-
-\`skill list\` shows Skills resolved from owned Kits. \`device list\` shows registered devices and
-their active Kits; \`device show\` shows the effective resolved Skills for one device.
-
-### Manage devices and autosync
-
-    empirical kit autosync "My Team Kit" on
-    empirical kit devices "My Team Kit"
-    empirical kit deactivate "My Team Kit" <device-id>
-
-Autosync keeps a registered device current. Interactive syncs review new or changed external
-Skills; unattended syncs apply them and leave a review marker for the next interactive sync.
-`,
-
-  skill: `# Empirical Skills
-
-Skills are agent-facing \`SKILL.md\` instruction files. Authored Skills can be pushed into a
-Kit so they follow you across machines and projects.
-
-## Push an authored Skill
-
-    empirical skill list
-
-    empirical skill push path/to/SKILL.md
-    empirical skill push path/to/SKILL.md --kit "My Team Kit"
-
-The file must contain YAML frontmatter at the top with both required fields:
-
-    ---
-    name: my-skill
-    description: Explain when this skill should be used.
-    ---
-
-The remainder of the file is the Skill body. The CLI validates the frontmatter before upload.
-After pushing, activate or sync the target Kit with \`empirical kit use\` or \`empirical kit sync\`.
-
-## Review and rollback
-
-    empirical skill history <authored-skill-id>
-    empirical skill rollback <authored-skill-id> --to-version 2
-
-Use history to inspect versions and rollback to a known-good version when a Skill needs to be
-reverted. External git-sourced Skills are reviewed during Kit sync and are not authored with
-this command.
-`,
-
-  auth: `# Empirical Auth
-
-## Token types
-
-**API key**: Long alphanumeric string, no dots. Never expires. Preferred for automation.
-**JWT**: Three dot-separated base64 parts. Has an expiry (\`exp\` claim). Used for browser OAuth flows.
-
-## Browser OAuth login
-
-    empirical auth login
-
-Opens the browser, completes OAuth with the Empirical account, and saves a CLI session at
-\`~/.empirical/oauth-session.json\`. Use this for normal interactive CLI use when you do not
-want to provision a permanent API key.
-
-## Logging out (and actually revoking)
-
-    empirical auth logout                 # revoke refresh tokens server-side, then clear locally
-    empirical auth logout --local-only    # forget this machine only, leave other clients signed in
-    empirical auth logout --client-id <id>  # revoke just one client's refresh tokens
-
-Plain \`logout\` calls \`DELETE /api/v1/users/me/refresh-tokens\`, so the session ends on the
-server and not merely on disk. This matters because refresh tokens are written without an
-expiry: before this existed, a leaked refresh token stayed redeemable forever and no command,
-endpoint or portal screen could revoke it.
-
-## Managing API keys
-
-    empirical auth list-keys                          # ids, labels, created dates
-    empirical auth rotate-key [--label <name>]        # mint an ADDITIONAL key, others keep working
-    empirical auth rotate-key --replace-all           # destructive: wipe every key, mint exactly one
-    empirical auth revoke-key --key-id <id>           # revoke one key
-    empirical auth revoke-key --all                   # revoke every key on the account
-
-Rotating without \`--replace-all\` is the safe cutover: mint the new key, move your integrations
-over, then \`revoke-key --key-id\` the old one. A key is displayed once at mint time; only its
-hash is stored, so there is no way to read it back later.
-
-Minting requires a signed-in session (browser login or a fresh OAuth session), because a
-permanent API key must not be able to mint more credentials. Revoking does not: it only ever
-reduces access, and the CLI needs to be able to revoke with the credential it already holds.
-
-## Bootstrap command (headless / non-interactive)
-
-    empirical oauth bootstrap headless --write-env
-
-Exchanges account credentials (client ID + secret, i.e. your userId + API key) for an access
-token via \`grant_type=client_credentials\` — this is NOT a dynamically-registered OAuth client;
-the server treats client_id/client_secret as userId/apiKey directly.
-Writes token to \`.empirical/headless-token.json\` and \`.empirical/headless.env\`.
-
-No portal visit or manual copy/paste needed: if no client ID/secret is found via
-\`EMPIRICAL_CLIENT_ID\`/\`EMPIRICAL_CLIENT_SECRET\` env vars or \`~/.empirical/oauth-client.json\`
-(set via \`empirical oauth client set\`), the CLI self-provisions your account's API key via
-\`POST /api/v1/users/me/credentials\`, authenticated with whatever bearer token it already has
-(existing token file, or — only if nothing exists yet — one browser login). If you already have
-an API key on the account, the CLI will never silently rotate it (that would break other
-integrations using it); it asks for explicit confirmation in a TTY, or gives up quietly in
-non-interactive contexts. If a stored client is rejected by the server ("Invalid client
-credentials"), the CLI discards it and re-provisions automatically on the same run — unless
-\`--client-id\`/\`--client-secret\` was passed explicitly, in which case the error is surfaced
-as-is.
-
-## Refresh command
-
-    empirical oauth refresh headless
-
-Exchanges a stored refresh token for a new access token. Token file must exist.
-
-## Token resolution priority (resolveAccessToken)
-
-1. \`EMPIRICAL_ACCESS_TOKEN\` environment variable (skipped if it's an expired JWT, so a
-   stale session token can never permanently shadow a valid credential below it)
-2. \`apiKey\` field in token file
-3. \`accessToken\` field in token file
-4. \`~/.empirical/oauth-session.json\` browser OAuth session
-5. \`EMPIRICAL_API_KEY\` or \`EMPIRICAL_CLIENT_SECRET\` environment variable, used directly
-   as a permanent Bearer credential — lets a stateless agent environment authenticate from
-   client_id/secret alone with no token file and no bootstrap step
-
-Token file lookup order:
-1. Path in \`EMPIRICAL_TOKEN_OUTPUT\` env var
-2. \`.empirical/headless-token.json\` (current working directory)
-3. \`~/.empirical/headless-token.json\` (home directory)
-
-The browser OAuth session is stored separately at \`~/.empirical/oauth-session.json\`.
-
-## Verify auth status
-
-    empirical auth status
-    empirical whoami
-
-Prints a single JSON object: \`{ authenticated, tokenPresent, tokenType, tokenExpiresAt,
-tokenExpired, user: { id, email } | null, workspaceId, error }\`. \`whoami\` is an alias for
-\`auth status\`. Exits 1 if not authenticated.
-
-    empirical doctor
-
-Checks token presence, type, expiry, and API connectivity across a broader set of checks
-(host MCP config registration, hooks, plugin versions).
-`,
-
-  user: `# Empirical User Identity
-
-## Via MCP (when Empirical MCP server is connected)
-
-Use the \`get_user\` MCP tool. Returns: id, email, name, workspaceId, tier, and plan details.
-
-## Via CLI
-
-    empirical doctor --output json
-
-Returns a JSON object with a \`checks\` array. The connectivity check (name: "api")
-includes the user record from /api/users/me when successful.
-
-    empirical workspace current
-
-Prints the active workspace name.
-
-## Notes
-
-- \`get_user\` has no standalone CLI subcommand; use \`empirical doctor --output json\` to
-  inspect identity from the shell.
-- If MCP is unavailable, parse the \`api\` check from doctor JSON output for user context.
-`
-};
-
-let cachedCliVersion = null;
-
-function getCliVersion() {
-  if (cachedCliVersion) return cachedCliVersion;
-  try {
-    const cliPackagePath = path.join(__dirname, '..', 'package.json');
-    const parsed = JSON.parse(fs.readFileSync(cliPackagePath, 'utf8'));
-    if (parsed && typeof parsed.version === 'string' && parsed.version.trim()) {
-      cachedCliVersion = parsed.version.trim();
-      return cachedCliVersion;
-    }
-  } catch (_error) {
-    // ignore and use fallback
-  }
-  cachedCliVersion = 'unknown';
-  return cachedCliVersion;
-}
-
-function deriveBaseUrlFromMcpUrl() {
-  try {
-    const parsed = new URL(EMPIRICAL_MCP_URL);
-    parsed.pathname = parsed.pathname.replace(/\/mcp\/?$/, '');
-    return parsed.origin + parsed.pathname.replace(/\/$/, '');
-  } catch (_error) {
-    return '';
-  }
-}
-
-module.exports = {
-  EMPIRICAL_MCP_NAME,
-  EMPIRICAL_MCP_LEGACY_NAMES,
-  EMPIRICAL_MCP_URL,
-  COPILOT_OAUTH_CLIENT_ID,
-  MEMORY_CATEGORIES,
-  NODE_TYPES,
-  DOC_TOPICS,
-  getCliVersion,
-  deriveBaseUrlFromMcpUrl
-};
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const EMPIRICAL_MCP_NAME = 'empirical';
+const EMPIRICAL_MCP_LEGACY_NAMES = ['empirical-live'];
+const EMPIRICAL_MCP_URL = process.env.EMPIRICAL_MCP_URL || 'https://empirical.gauzza.com/mcp';
+const COPILOT_OAUTH_CLIENT_ID = process.env.EMPIRICAL_COPILOT_OAUTH_CLIENT_ID || 'copilot-cli-empirical';
+
+// These two lists mirror the schema-level enums in packages/shared/src/memoryGraph.ts.
+// They are duplicated rather than imported on purpose: this CLI publishes to npm as
+// @empirical-gauzza/cli, and @empirical/shared is a private workspace package, so depending
+// on it would break `npm install` for end users. tests/unit/cliMemoryEnumParity.test.js
+// fails CI if the copies ever diverge.
+const MEMORY_CATEGORIES = [
+  'health', 'fitness', 'food', 'supplement', 'mood', 'idea', 'business',
+  'build', 'growth', 'learning', 'leadership', 'operations', 'workflow',
+  'lead', 'project', 'recipe', 'preference', 'reflection', 'relationship', 'heartbeat'
+];
+
+const NODE_TYPES = [
+  'event', 'entity', 'observation', 'reflection', 'goal', 'concept'
+];
+
+const DOC_TOPICS = {
+  memory: `# Empirical Memory Commands
+
+Use the \`empirical memory\` subcommands to query and manage memories via the REST API.
+All commands require a valid access token (see \`empirical doc auth\`).
+Errors are written to stderr as JSON. Successful output is written to stdout as JSON.
+
+## Subcommands
+
+### query
+Search memories by natural language.
+
+    empirical memory query --match "coding style preferences" [--top-k 3] [--category build] [--tags ts,node] [--pretty] [--format table]
+
+Flags:
+- \`--match\` (required): natural language search string
+- \`--top-k\`: number of results, 1–100, default 3
+- \`--category\`: filter by category
+- \`--tags\`: comma-separated tags filter
+- \`--tags-all\`: comma-separated tags that must ALL be present (AND match)
+- \`--status\`: comma-separated status values to keep (for example open,in_progress)
+- \`--due-before\`, \`--due-after\`: keep only reminders due in that window (ISO 8601 dates).
+  "What is due?" is \`--due-before <now> --remind-state pending\`; dueness is a filter, never
+  something semantic ranking finds on its own
+- \`--remind-state\`: comma-separated reminder states to keep: pending, notified, acknowledged, cancelled
+- \`--path\`: pin one retrieval pathway (see below)
+- \`--hops\`: 1 or 2, graph depth; only valid with \`--path graph\` or \`--path hebbian\`
+- \`--pretty\`: pretty-print JSON output
+- \`--format table\`: render results as a table instead of JSON (JSON stays the default)
+
+#### Retrieval pathways
+
+- \`--path semantic\`: ranked meaning match. Runs the embedding search and scores candidates.
+  Use it when you are asking a question and want the closest few answers.
+- \`--path list\`: filtered browse. Skips ranking and returns the matching set in order, with
+  paging. Use it when you want everything carrying a tag, status, or category, not a top few.
+- \`--path graph\`: relationship walk from the best entry points, out \`--hops\` steps. Use it
+  when what you want is connected to what you can name rather than worded like it.
+- \`--path hebbian\`: co-recall walk, following the links that repeated retrieval strengthened.
+  Use it when you want what usually comes up alongside this, not what merely resembles it.
+
+Omitting \`--path\` keeps the default, where the classifier decides which pathway answers.
+
+### get
+Retrieve one memory by exact ID.
+
+    empirical memory get --memory-id <id> [--pretty]
+
+### list
+Browse memories deterministically. Use \`--cursor\` from the previous response while \`pagination.hasMore\` is true.
+
+    empirical memory list [--category project] [--tags canonical,launch] [--start-date <ISO>] [--end-date <ISO>] [--limit 20] [--cursor <cursor>] [--oldest] [--pretty] [--format table]
+
+Flags:
+- \`--category\`, \`--tags\`: optional filters
+- \`--start-date\`, \`--end-date\`: createdAt bounds
+- \`--limit\`: page size, 1–100, default 20
+- \`--cursor\`: continuation cursor from a previous page
+- \`--oldest\`: sort oldest first; default is newest first
+- \`--pretty\`: pretty-print JSON output
+- \`--format table\`: render results as a table instead of JSON (JSON stays the default)
+
+### acknowledge
+Close a due reminder from the terminal.
+
+    empirical memory acknowledge --memory-id <id> [--cancel]
+
+Marks the reminder done (or dropped, with \`--cancel\`), frees its slot on your plan, and clears
+its alert on every surface so no agent keeps relaying it. The id is in the reminder banner.
+
+### record
+Save a new memory.
+
+    empirical memory record --category build --summary "Use ESM modules for all new packages" [--tags ts,node] [--node-type observation] [--author-type user|agent] [--due <ISO date>]
+
+\`--due <ISO date>\` turns the memory into a REMINDER: at that time you get one email with a
+calendar entry attached. Accepts 2026-10-14 or a full timestamp like 2026-10-14T09:00:00Z.
+Any memory can carry one. Plans cap CONCURRENT pending reminders rather than how many you
+create per month, so acknowledging or cancelling one frees a slot.
+
+\`--author-type\` records WHO the fact belongs to, which the transport cannot know. Use
+\`user\` for something the user said, decided or prefers; \`agent\` for your own session notes
+and findings. Omitted, it is left unresolved rather than guessed. Retrieval reads it to keep
+agent notes out of answers about the user's own life and work.
+
+Passing text that contains code (backticks, \${...}, $(...)): do NOT put it in a double-quoted
+\`--summary "..."\` -- the shell substitutes those away before the CLI runs and the write still
+succeeds with the code silently missing. Use one of:
+
+    empirical memory record --category build --summary-file ./note.md --tags ts
+    empirical memory record --category build --summary - --tags ts <<'EOF'
+    Use \`createChat()\`; raw calls leak \${stage} and 400.
+    EOF
+
+(a single-quoted heredoc delimiter, 'EOF', disables substitution). From an MCP-connected agent,
+prefer the record_graph_memory tool, which takes JSON and never touches a shell.
+
+Flags:
+- \`--category\` (required unless --json-file): memory category
+- \`--summary\` (required unless --summary-file/--json-file): memory summary text; \`-\` reads stdin
+- \`--summary-file\`: path to a file whose contents become the summary (safe for code)
+- \`--tags\`: comma-separated tags
+- \`--node-type\`: node type, default \`observation\`
+- \`--json-file\`: path to JSON file with full memory payload
+
+Both \`--category\` and \`--node-type\` are closed sets. Do not guess a value: anything outside
+these lists is rejected and the write does not happen.
+
+Valid categories (20): health, fitness, food, supplement, mood, idea, business, build, growth,
+learning, leadership, operations, workflow, lead, project, recipe, preference, reflection,
+relationship, heartbeat.
+
+Valid node types (6): event, entity, observation, reflection, goal, concept.
+
+There is no \`product\` category and no \`decision\` node type. Record a decision as
+\`--category project --node-type event\`.
+
+### note
+Add a note to an existing memory.
+
+    empirical memory note --match "ESM modules" --text "confirmed in monorepo migration" [--min-score 0.35]
+
+Flags:
+- \`--match\` (required unless --memory-id): search string to find the memory
+- \`--text\` (required): note text to append
+- \`--memory-id\`: use exact memory ID (skips fuzzy search)
+- \`--min-score\`: minimum similarity score, default 0.35
+
+### update
+Update an existing memory.
+
+    empirical memory update --match "ESM modules" --patch-json '{"summary":"Updated summary"}' [--min-score 0.35]
+
+Flags:
+- \`--match\` (required unless --memory-id): search string
+- \`--patch-json\`: JSON string with fields to update
+- \`--json-file\`: path to JSON patch file
+- \`--memory-id\`: use exact memory ID
+- \`--min-score\`: minimum similarity score, default 0.35
+
+### delete
+Delete a memory. Without --confirm, runs a dry-run and prints what would be deleted.
+
+    empirical memory delete --match "old preference" --confirm [--min-score 0.35]
+
+Flags:
+- \`--match\` (required unless --memory-id): search string
+- \`--confirm\`: actually delete (without this, dry-run only)
+- \`--memory-id\`: use exact memory ID
+- \`--min-score\`: minimum similarity score, default 0.35
+
+Bulk delete by tag, category, or everything (exactly one selector):
+
+    empirical memory delete --tag old-preference --confirm
+    empirical memory delete --category recipe --confirm
+    empirical memory delete --all --confirm
+
+Without \`--confirm\`, always a dry-run that prints the count that would be deleted; no writes
+happen. Re-run with \`--confirm\` to actually delete.
+
+### export / import
+Export memories to a versioned, round-trippable JSON document and re-import them later.
+
+    empirical memory export --scope <personal|workspace> [--out <path>] [--workspace-id <id>]
+    empirical memory import <file> [--dry-run]
+
+Export writes \`{ schemaVersion: 1, exportedAt, memories: [...] }\`. Import reads that same
+shape and POSTs each row through the normal create endpoint, so imported memories get the same
+dedupe and auto-link treatment as any other write. \`--dry-run\` on import prints the count that
+would be imported without writing anything.
+
+### stats
+Aggregated counts, scoped to the caller.
+
+    empirical memory stats [--format table]
+
+Returns total count, counts by category, counts by tag, and oldest/newest memory timestamps.
+
+### compact
+On-demand near-duplicate scan (the same logic the nightly compaction job runs), scoped to the
+caller only. Dry-run by default, matching a terraform plan/apply model.
+
+    empirical memory compact [--category <cat>]
+    empirical memory compact --apply [--category <cat>]
+
+Without \`--apply\`, reports proposed merge/link candidate pairs and counts with no writes.
+With \`--apply\`, executes the merges and links for real and reports what was applied.
+
+## Error output contract
+- Errors → stderr as JSON: \`{ "error": true, "code": "...", "message": "..." }\`
+- Success → stdout as JSON (compact by default)
+`,
+
+  install: `# Empirical Install
+
+    empirical install
+
+Runs the interactive installer to connect Empirical memory to your AI coding CLI(s).
+
+## What it does
+1. Detects installed CLIs: Codex, GitHub Copilot, Claude Code
+2. Prompts for CLI target selection
+3. Asks how agents should interact with Empirical:
+   - Mode 1: Via MCP tool (recommended) — registers Empirical as an MCP server
+   - Mode 2: Via CLI commands — writes CLI-direct instruction block, no MCP registration
+   - Mode 3: Both — MCP primary with CLI fallback
+4. Stores the personalized behavior policy for the native Empirical Memory Skill; global
+   instruction files are left unchanged
+5. Offers optional browser OAuth login for CLI use, optional headless/API-key bootstrap for
+   automation, containers, and external runtimes, and optional work-history/scar-tissue guidance
+6. Installs a \`SessionStart\` hook for each selected client that calls the \`empirical\` CLI
+   directly once per session — deterministic baseline context that doesn't depend on the model
+   deciding to call a tool. Claude: \`~/.claude/settings.json\`. Codex: \`<CODEX_HOME>/hooks.json\`
+   (defaults to \`~/.codex\`). Copilot: \`~/.copilot/hooks/empirical-session-start.json\`.
+7. Installs the native \`empirical-memory\` plugin for each selected client. The plugin owns
+   the Empirical MCP connection and all agent-facing Skills; the CLI does not generate duplicate
+   \`SKILL.md\` or \`EMPIRICAL_SKILL.md\` files.
+
+## Native plugin only
+
+    empirical plugin install <codex|copilot|claude|all> [--all-optional]
+
+    Optional plugins: --work-history, --scar-tissue, --todo, --voice (writes as you once a voice is saved)
+
+    empirical plugin check [--force]
+
+Installs or refreshes only the native marketplace plugin. It does not run the MCP/auth questionnaire
+or modify global instruction files. With no target, the command installs for detected CLIs.
+
+The CLI performs a best-effort native plugin version check during interactive use (at most once per
+day). It is silent for noninteractive/headless commands. Use \`empirical plugin check --force\` to
+check immediately.
+
+Use \`empirical policy show\` to inspect the current native-skill behavior policy and
+\`empirical policy set --json '{"allowDiscretionaryUse":false}'\` to change it without rerunning
+the installer. The policy is cached locally and refreshed when stale.
+`,
+
+  workspace: `# Empirical Workspace Commands
+
+Manage disposable team workspaces and which Empirical workspace is active for this OAuth client.
+
+## Commands
+
+### List workspaces
+
+    empirical workspace list
+
+Shows all available workspaces and which one is currently selected.
+
+### Show current workspace
+
+    empirical workspace current
+
+Prints the currently selected workspace name.
+
+### Select a workspace
+
+    empirical workspace select [<number|name>]
+
+Interactive workspace selector (prompts if no argument given).
+Pass a number (from \`list\`) or an exact workspace name.
+
+    empirical workspace select 2
+    empirical workspace select "My Workspace"
+
+Note: workspace selection may be admin-locked for some OAuth clients.
+
+### Create a demo workspace
+
+    empirical workspace create "Demo Workspace" --description "Temporary shared context"
+
+Creates a team workspace using your existing plan quota and prints its workspace ID.
+
+### Use a workspace
+
+    empirical workspace use <number|name|id>
+    empirical workspace use <number|name|id> --global
+    empirical workspace unbind
+
+Friendly alias for \`workspace select\`. It accepts the list number, exact case-insensitive name, or workspace ID.
+
+Inside a git repository, \`use\` binds the workspace to THAT project by writing \`<repo>/.empirical/workspace.json\`; every command run inside the repo uses it, and other repositories are unaffected. \`--global\` sets the machine-wide default instead (the previous behavior). \`--project\` forces a project binding in the current directory even without git. \`unbind\` removes the project binding.
+
+Resolution order for every memory command, first match wins: the \`EMPIRICAL_WORKSPACE_ID\` environment variable, the nearest project binding walking up from the current directory, the global selection, then the server's per-client selection. \`workspace current\` and \`whoami\` print which source applied.
+
+### Query across several workspaces
+
+    empirical memory query --match "<query>" --workspaces "Default Workspace","Project Atlas"
+    empirical memory query --match "<query>" --all-workspaces
+
+\`--workspaces\` accepts list numbers, names, or workspace IDs (comma-separated) and returns one merged, ranked result set with each row's \`workspaceId\`. Paging (\`--cursor\`, offsets) is not available across several workspaces. Without the flag a query is scoped to the single active workspace exactly as before.
+
+### Share an active workspace
+
+    empirical workspace invite create --role writer --expires-in-days 7 --max-uses 3
+    empirical workspace invite list
+    empirical workspace invite revoke <token>
+
+Invite commands operate on the active team workspace. Create prints a shareable URL.
+
+### Soft-delete a demo workspace
+
+    empirical workspace delete <number|name|id>
+    empirical workspace delete <number|name|id> --confirm
+
+Deletion dry-runs by default. \`--confirm\` calls the existing soft-delete endpoint; the Default Workspace cannot be deleted. If the active workspace is deleted, the CLI selects the Default Workspace.
+`,
+
+  doctor: `# Empirical Doctor
+
+    empirical doctor [--output json] [--deep]
+
+Checks the health of your Empirical CLI setup, including why MCP tools might not be showing up
+in a host CLI (the most common failure report).
+
+## Checks performed
+
+1. **Token presence** — verifies a token exists via EMPIRICAL_ACCESS_TOKEN env, apiKey field,
+   or accessToken field in the token file
+2. **Token type** — detects API key (long alphanumeric, no dots) vs JWT (3 dot-separated parts)
+3. **Token expiry** — if JWT, decodes the payload and checks the \`exp\` field; warns if no \`exp\`
+4. **API connectivity** — calls GET /api/v1/users/me; 200 = OK, anything else = FAIL
+5. **Workspace** — reads workspaceId from the /api/v1/users/me response; warns if null
+6. **MCP hosts detected** — which of codex/claude/copilot were found on this machine
+7. **MCP config registration (per detected host)** — reads that host's own config file
+   (\`~/.claude.json\`, \`<CODEX_HOME>/config.toml\`, \`~/.copilot/mcp-config.json\`) and confirms
+   the Empirical MCP server is actually registered there with the current URL
+8. **MCP reachability** — POSTs a real MCP \`initialize\` request to the MCP endpoint with the
+   resolved access token and confirms a valid JSON-RPC response comes back
+9. **Native plugin presence/version (per detected host)** — runs \`<host> plugin list\` and
+   reports the installed empirical-memory (and optional) plugin versions
+10. **Hooks presence (per detected host)** — confirms the SessionStart/UserPromptSubmit/Stop
+    hook scripts exist on disk and are registered in that host's hook manifest
+
+## --deep
+
+Adds a live write/query/delete round trip: records a \`doctor-probe-<timestamp>\` memory, queries
+it back, deletes it, and reports elapsed time for each leg. Requires a valid token; writes and
+deletes exactly one throwaway memory tagged \`doctor-probe\`.
+
+## Output format
+
+Default: human-readable lines prefixed with [OK], [WARN], or [FAIL].
+
+    empirical doctor --output json
+
+JSON output: \`{ "checks": [{ "name", "status", "message" }], "overall": "ok"|"warn"|"fail" }\`
+Useful for agent/automation use.
+
+## Exit codes
+- 0: all checks passed (ok or warn)
+- 1: one or more checks failed
+`,
+
+  agents: `# Empirical Agent Integration
+
+Empirical memory integrates with three AI coding CLIs.
+
+## Supported agents
+
+| Agent       | Config dir          | Instruction file              | MCP config                          |
+|-------------|---------------------|-------------------------------|-------------------------------------|
+| Claude Code | ~/.claude/          | CLAUDE.md                     | ~/.claude.json (mcpServers)         |
+| Codex CLI   | ~/.codex/           | AGENTS.md                     | codex mcp add                       |
+| Copilot CLI | ~/.copilot/         | copilot-instructions.md       | ~/.copilot/mcp-config.json          |
+
+## Integration modes
+
+**Mode 1: MCP tool (recommended)**
+Empirical is registered as an MCP server. Agents call memory tools (query_memories,
+record_graph_memory, etc.) directly via the MCP protocol. Best for interactive sessions.
+
+**Mode 2: CLI commands**
+Agents run \`empirical memory <subcommand>\` shell commands. No MCP registration required.
+Suitable for headless/scripted environments or when MCP is unavailable.
+
+**Mode 3: Both**
+MCP is primary; CLI commands are available as fallback. Maximizes reliability.
+
+## Inventory commands
+
+    empirical skill list
+    empirical device list
+    empirical device show <deviceId>
+
+Use these to inspect Skills across Kits and the effective Skills installed for a device.
+
+The native \`empirical-memory\` plugin owns its Skills and MCP connection. Run
+\`empirical install\` to install it and configure detected agents.
+`,
+
+  kit: `# Empirical Skills Kits
+
+Kits are named collections of agent Skills. A Kit can contain Skills authored in Empirical
+or discovered from a git repository, then sync the resolved set to your local agents.
+
+## Commands
+
+### Create and list Kits
+
+    empirical kit create "My Team Kit"
+    empirical kit list
+
+### Add or remove a git source
+
+    empirical kit add-source "My Team Kit" https://github.com/example/skills.git
+    empirical kit add-source "My Team Kit" https://github.com/example/skills.git --ref main --path skills
+    empirical kit remove-source "My Team Kit" <source-id>
+
+Each source is scanned for valid \`SKILL.md\` files. A Skill file must begin with YAML
+frontmatter containing both \`name\` and \`description\`, for example:
+
+    ---
+    name: my-skill
+    description: Explain when this skill should be used.
+    ---
+
+### Activate and sync
+
+    empirical kit use "My Team Kit"
+    empirical kit sync
+    empirical kit sync --dry-run
+
+\`kit use\` activates a Kit on this device and syncs its Skills into detected agent
+directories. \`kit sync\` refreshes the active Kit. Use \`--quiet\` for unattended syncs
+and \`--force\` only when you intentionally want to bypass the local-edit guard.
+
+### Inventory
+
+    empirical skill list
+    empirical kit list
+    empirical kit devices "My Team Kit"
+    empirical device list
+    empirical device show <deviceId>
+
+\`skill list\` shows Skills resolved from owned Kits. \`device list\` shows registered devices and
+their active Kits; \`device show\` shows the effective resolved Skills for one device.
+
+### Manage devices and autosync
+
+    empirical kit autosync "My Team Kit" on
+    empirical kit devices "My Team Kit"
+    empirical kit deactivate "My Team Kit" <device-id>
+
+Autosync keeps a registered device current. Interactive syncs review new or changed external
+Skills; unattended syncs apply them and leave a review marker for the next interactive sync.
+`,
+
+  skill: `# Empirical Skills
+
+Skills are agent-facing \`SKILL.md\` instruction files. Authored Skills can be pushed into a
+Kit so they follow you across machines and projects.
+
+## Push an authored Skill
+
+    empirical skill list
+
+    empirical skill push path/to/SKILL.md
+    empirical skill push path/to/SKILL.md --kit "My Team Kit"
+
+The file must contain YAML frontmatter at the top with both required fields:
+
+    ---
+    name: my-skill
+    description: Explain when this skill should be used.
+    ---
+
+The remainder of the file is the Skill body. The CLI validates the frontmatter before upload.
+After pushing, activate or sync the target Kit with \`empirical kit use\` or \`empirical kit sync\`.
+
+## Review and rollback
+
+    empirical skill history <authored-skill-id>
+    empirical skill rollback <authored-skill-id> --to-version 2
+
+Use history to inspect versions and rollback to a known-good version when a Skill needs to be
+reverted. External git-sourced Skills are reviewed during Kit sync and are not authored with
+this command.
+`,
+
+  auth: `# Empirical Auth
+
+## Token types
+
+**API key**: Long alphanumeric string, no dots. Never expires. Preferred for automation.
+**JWT**: Three dot-separated base64 parts. Has an expiry (\`exp\` claim). Used for browser OAuth flows.
+
+## Browser OAuth login
+
+    empirical auth login
+
+Opens the browser, completes OAuth with the Empirical account, and saves a CLI session at
+\`~/.empirical/oauth-session.json\`. Use this for normal interactive CLI use when you do not
+want to provision a permanent API key.
+
+## Logging out (and actually revoking)
+
+    empirical auth logout                 # revoke refresh tokens server-side, then clear locally
+    empirical auth logout --local-only    # forget this machine only, leave other clients signed in
+    empirical auth logout --client-id <id>  # revoke just one client's refresh tokens
+
+Plain \`logout\` calls \`DELETE /api/v1/users/me/refresh-tokens\`, so the session ends on the
+server and not merely on disk. This matters because refresh tokens are written without an
+expiry: before this existed, a leaked refresh token stayed redeemable forever and no command,
+endpoint or portal screen could revoke it.
+
+## Managing API keys
+
+    empirical auth list-keys                          # ids, labels, created dates
+    empirical auth rotate-key [--label <name>]        # mint an ADDITIONAL key, others keep working
+    empirical auth rotate-key --replace-all           # destructive: wipe every key, mint exactly one
+    empirical auth revoke-key --key-id <id>           # revoke one key
+    empirical auth revoke-key --all                   # revoke every key on the account
+
+Rotating without \`--replace-all\` is the safe cutover: mint the new key, move your integrations
+over, then \`revoke-key --key-id\` the old one. A key is displayed once at mint time; only its
+hash is stored, so there is no way to read it back later.
+
+Minting requires a signed-in session (browser login or a fresh OAuth session), because a
+permanent API key must not be able to mint more credentials. Revoking does not: it only ever
+reduces access, and the CLI needs to be able to revoke with the credential it already holds.
+
+## Bootstrap command (headless / non-interactive)
+
+    empirical oauth bootstrap headless --write-env
+
+Exchanges account credentials (client ID + secret, i.e. your userId + API key) for an access
+token via \`grant_type=client_credentials\` — this is NOT a dynamically-registered OAuth client;
+the server treats client_id/client_secret as userId/apiKey directly.
+Writes token to \`.empirical/headless-token.json\` and \`.empirical/headless.env\`.
+
+No portal visit or manual copy/paste needed: if no client ID/secret is found via
+\`EMPIRICAL_CLIENT_ID\`/\`EMPIRICAL_CLIENT_SECRET\` env vars or \`~/.empirical/oauth-client.json\`
+(set via \`empirical oauth client set\`), the CLI self-provisions your account's API key via
+\`POST /api/v1/users/me/credentials\`, authenticated with whatever bearer token it already has
+(existing token file, or — only if nothing exists yet — one browser login). If you already have
+an API key on the account, the CLI will never silently rotate it (that would break other
+integrations using it); it asks for explicit confirmation in a TTY, or gives up quietly in
+non-interactive contexts. If a stored client is rejected by the server ("Invalid client
+credentials"), the CLI discards it and re-provisions automatically on the same run — unless
+\`--client-id\`/\`--client-secret\` was passed explicitly, in which case the error is surfaced
+as-is.
+
+## Refresh command
+
+    empirical oauth refresh headless
+
+Exchanges a stored refresh token for a new access token. Token file must exist.
+
+## Token resolution priority (resolveAccessToken)
+
+1. \`EMPIRICAL_ACCESS_TOKEN\` environment variable (skipped if it's an expired JWT, so a
+   stale session token can never permanently shadow a valid credential below it)
+2. \`apiKey\` field in token file
+3. \`accessToken\` field in token file
+4. \`~/.empirical/oauth-session.json\` browser OAuth session
+5. \`EMPIRICAL_API_KEY\` or \`EMPIRICAL_CLIENT_SECRET\` environment variable, used directly
+   as a permanent Bearer credential — lets a stateless agent environment authenticate from
+   client_id/secret alone with no token file and no bootstrap step
+
+Token file lookup order:
+1. Path in \`EMPIRICAL_TOKEN_OUTPUT\` env var
+2. \`.empirical/headless-token.json\` (current working directory)
+3. \`~/.empirical/headless-token.json\` (home directory)
+
+The browser OAuth session is stored separately at \`~/.empirical/oauth-session.json\`.
+
+## Verify auth status
+
+    empirical auth status
+    empirical whoami
+
+Prints a single JSON object: \`{ authenticated, tokenPresent, tokenType, tokenExpiresAt,
+tokenExpired, user: { id, email } | null, workspaceId, error }\`. \`whoami\` is an alias for
+\`auth status\`. Exits 1 if not authenticated.
+
+    empirical doctor
+
+Checks token presence, type, expiry, and API connectivity across a broader set of checks
+(host MCP config registration, hooks, plugin versions).
+`,
+
+  user: `# Empirical User Identity
+
+## Via MCP (when Empirical MCP server is connected)
+
+Use the \`get_user\` MCP tool. Returns: id, email, name, workspaceId, tier, and plan details.
+
+## Via CLI
+
+    empirical doctor --output json
+
+Returns a JSON object with a \`checks\` array. The connectivity check (name: "api")
+includes the user record from /api/users/me when successful.
+
+    empirical workspace current
+
+Prints the active workspace name.
+
+## Notes
+
+- \`get_user\` has no standalone CLI subcommand; use \`empirical doctor --output json\` to
+  inspect identity from the shell.
+- If MCP is unavailable, parse the \`api\` check from doctor JSON output for user context.
+`
+};
+
+let cachedCliVersion = null;
+
+function getCliVersion() {
+  if (cachedCliVersion) return cachedCliVersion;
+  try {
+    const cliPackagePath = path.join(__dirname, '..', 'package.json');
+    const parsed = JSON.parse(fs.readFileSync(cliPackagePath, 'utf8'));
+    if (parsed && typeof parsed.version === 'string' && parsed.version.trim()) {
+      cachedCliVersion = parsed.version.trim();
+      return cachedCliVersion;
+    }
+  } catch (_error) {
+    // ignore and use fallback
+  }
+  cachedCliVersion = 'unknown';
+  return cachedCliVersion;
+}
+
+function deriveBaseUrlFromMcpUrl() {
+  try {
+    const parsed = new URL(EMPIRICAL_MCP_URL);
+    parsed.pathname = parsed.pathname.replace(/\/mcp\/?$/, '');
+    return parsed.origin + parsed.pathname.replace(/\/$/, '');
+  } catch (_error) {
+    return '';
+  }
+}
+
+module.exports = {
+  EMPIRICAL_MCP_NAME,
+  EMPIRICAL_MCP_LEGACY_NAMES,
+  EMPIRICAL_MCP_URL,
+  COPILOT_OAUTH_CLIENT_ID,
+  MEMORY_CATEGORIES,
+  NODE_TYPES,
+  DOC_TOPICS,
+  getCliVersion,
+  deriveBaseUrlFromMcpUrl
+};