@empirical-gauzza/cli 1.0.36 → 1.0.38

package/lib/constants.js

@@ -1,670 +1,722 @@
-'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>
-    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
-};
+'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.
+
+### tree
+One item and everything nested under it, as a readable document. The server assembles it in
+one query, so there is no walking the graph level by level.
+
+    empirical memory tree (--memory-id <id> | --match <q>) [--depth 10] [--max-nodes 500] [--no-notes] [--format markdown|json] [--out <path>]
+
+Flags:
+- \`--depth\`: how many levels below the starting item to include, default 10. 0 is the item alone
+- \`--max-nodes\`: cap on items in the document, default 500. When it bites, stderr carries a
+  truncated warning and the document itself stays clean for redirection
+- \`--no-notes\`: leave each item's notes out, for a bare outline
+- \`--format json\`: print the nodes and metadata instead of the document (markdown is the default
+  here, unlike other memory subcommands, because the point of this one is something to read)
+- \`--out <path>\`: write the document to a file instead of stdout
+
+Items nest only in a workspace that has a shape. For an ordinary memory this returns that one
+memory as a one-section document.
+
+### attachment
+Files attached to a memory. Up to 20 files per memory, 25MB each. Every subcommand takes the
+target memory as \`--memory-id <id>\` or \`--match <query>\`, the same way \`note\` and \`update\` do.
+
+    empirical memory attachment list    (--memory-id <id> | --match <q>) [--include-deleted] [--format table] [--pretty]
+    empirical memory attachment add     (--memory-id <id> | --match <q>) --file <path> [--author-type user|agent]
+    empirical memory attachment get     (--memory-id <id> | --match <q>) --attachment-id <id> [--out <path>] [--force]
+    empirical memory attachment delete  (--memory-id <id> | --match <q>) --attachment-id <id> [--confirm]
+    empirical memory attachment restore (--memory-id <id> | --match <q>) --attachment-id <id>
+
+\`empirical memory attach\` is shorthand for \`attachment add\`, and \`empirical memory attachments\`
+for \`attachment list\`.
+
+Notes:
+- \`delete\` is a soft delete: the file stays restorable for 30 days, then the purge worker
+  removes the bytes. Without \`--confirm\` it is a dry run, like \`memory delete\`.
+- \`list --include-deleted\` shows deleted rows with the date their bytes get purged.
+- \`get\` writes bytes to a file, not to stdout: \`--out <path>\` chooses where (a directory is
+  allowed), and without it the server's filename is used in the current directory. An existing
+  file is never overwritten without \`--force\`. \`--out -\` writes the bytes to stdout for piping.
+- Attachments need a paid plan; the free tier's attachment pool is 0 bytes.
+
+### 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.
+
+### Set up or re-shape a workspace by interview
+
+    empirical workspace create --interview
+    empirical workspace shape --workspace-id <id>
+    empirical setup abandon <sessionId>
+
+The interview asks what the workspace is for, offers kinds of item, statuses, fields and rules to pick from, shows a draft, and creates the workspace (or saves the new shape) and emails any invites only after you confirm. At the first review type next to choose who to invite (a bare yes is not a choice there), or confirm to finish with nobody invited, or type a change. On a new workspace a change can be its name (for example: change the name to Wellness on Balance); the name of an existing workspace is changed in its settings, not here. After the invitations, a yes confirms. In a re-shape the workspace's current kinds of item, statuses, fields and rules are listed first as Now in use: say keep, or only add things after a bar, to start from them as they are. Adding works; taking something away is not possible yet. In a script, the draft answer may be a list sent in order, for example for a new workspace {"draft": ["change the name to Leads", "next"], "invites": "ana@example.com writer", "confirm": "confirm"}. \`create --interview\` always makes a new workspace and takes no name. \`shape\` re-shapes an existing team workspace you manage: pass \`--workspace-id\`. Without it, at a terminal only, the command names the workspace this directory is bound to and asks you to confirm it; in a script (\`--answers\`), with \`--accept-cost\`, or with no terminal it refuses and needs \`--workspace-id\`. \`--answers <file.json>\` runs it from a map of question key to answer, and \`--accept-cost\` agrees to the Empirical Tokens cost in a script (a person at a terminal is asked instead).
+
+A new interview is charged. \`setup abandon\` stops one but does not return what it cost. When the interview is not switched on for your account, the start answers that nothing was started or charged.
+
+### 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
+};