@aixle/insights 0.2.1-staging → 0.2.1

package/README.md

@@ -13,7 +13,7 @@ Two channels are published. Pick one deliberately — they are **not** interchan
 | | Production | Staging (QA) |
 |---|---|---|
 | Install | `npm i -g @aixle/insights` | `npm i -g @aixle/insights@staging` |
-| Version looks like | `0.2.0` | `0.2.1-staging` |
+| Version looks like | `0.2.1` | `0.2.6-staging` |
 | Points at | the production API | the staging API |
 | Who should use it | **everyone** | QA validating unreleased work |
 | Stability | released, supported | may change or break without notice |
@@ -28,7 +28,7 @@ npx -y @aixle/insights init \
 
 # Or global install:
 npm i -g @aixle/insights
-aixle-insights --version    # e.g. 0.2.0  (no suffix)
+aixle-insights --version    # e.g. 0.2.1  (no suffix)
 ```
 
 ### Staging — QA only
@@ -44,7 +44,7 @@ npx -y @aixle/insights@staging init \
 
 # Or global install:
 npm i -g @aixle/insights@staging
-aixle-insights --version    # e.g. 0.2.1-staging  (note the suffix)
+aixle-insights --version    # e.g. 0.2.6-staging  (note the suffix)
 ```
 
 Point a staging build at the **staging** API host. Sending staging telemetry to production
@@ -60,7 +60,7 @@ npm view @aixle/insights dist-tags       # what each channel currently resolves
 Expected output — `latest` and `staging` move independently:
 
 ```
-{ latest: '0.2.0', staging: '0.2.1-staging' }
+{ latest: '0.2.1', staging: '0.2.6-staging' }
 ```
 
 ### Switching back to production
@@ -73,8 +73,8 @@ Then re-run `init` against the production host, since credentials and the MCP en
 per-host.
 
 > **Why `npm install` never surprises you with a staging build:** `-staging` versions are semver
-> prereleases, and no ordinary version range resolves to a prerelease. `*`, `^0.2.0`, `~0.2.0`
-> and `>=0.1.0` all select `0.2.0` even when `0.2.1-staging` exists. Staging builds are
+> prereleases, and no ordinary version range resolves to a prerelease. `*`, `^0.2.1`, `~0.2.1`
+> and `>=0.1.0` all select `0.2.1` even when `0.2.6-staging` exists. Staging builds are
 > reachable only by exact version or the `staging` dist-tag.
 
 Maintainers: see [`../RELEASING.md`](../RELEASING.md) for how each channel is cut.
@@ -113,14 +113,6 @@ npx -y @aixle/insights init \
 
 You can also set `DB90_ORGANIZATION_ID=<uuid>` in your shell environment, or pin it via `mcpServers.aixle-insights.env` in `~/.claude.json`. The CLI flag overrides the env var when both are set.
 
-## First run and backfill
-
-Before you run `init`, the MCP server is a deliberate no-op: it does not read, buffer, or send anything, and it does not create any state files. Nothing is lost during this window — Claude Code's transcripts and Cursor's local telemetry stores are unaffected by whether `@aixle/insights` is watching them.
-
-The moment `init` succeeds, this package's per-credential state starts from empty (no watermark, no dedupe checkpoint). That means **the very first sync after `init` treats "everything currently on disk" as new** — Claude transcript JSONL files and Cursor SQLite history alike — and sends all of it, not just activity from that point forward. There is no separate "backfill mode" to opt into; it is simply what an empty watermark means the first time `run --once` or the background sync loop executes.
-
-If the MCP has been installed but never connected, `aixle-insights health` (or the `status` MCP tool) reports `needs_init: true` with a human-readable `onboarding_message` explaining exactly this — install-but-uninitialized is not a state you need to worry about losing data in.
-
 ## Commands
 
 | Command | What it does |
@@ -162,6 +154,12 @@ Optional `~/.aixle-insights/config.json` accepts Cursor line-cost overrides (per
 }
 ```
 
+The file is optional — an absent `config.json` is the normal case and is silent. A file that is
+present but unusable is ignored entirely (every override falls back to its default) and a
+`config_parse_failed` line is written to `mcp.log`. That covers malformed JSON and valid JSON that
+isn't an object, including a **top-level array** — a common mistake when writing per-model rates.
+Nothing is printed to the terminal, so check the log if an override appears to have no effect.
+
 ## Security
 
 `@aixle/insights` enforces HTTPS for any remote host. Plaintext `http://` is allowed only for loopback (`localhost`, `127.0.0.0/8`, `[::1]`) so that local-dev flows against `make up` continue to work without friction.
@@ -188,6 +186,22 @@ The runtime gate exists because `init`'s two gates only run once, at login time.
 
 The Keycloak issuer URL (`--keycloak-url` / `KEYCLOAK_ISSUER`) is **not** TLS-gated by this package. Same threat model, different ticket — tracked separately. For now, use HTTPS for any remote Keycloak issuer; the OIDC device-flow library will fail the request if the cert is invalid, but it will not refuse to attempt plaintext.
 
+### Local store integrity
+
+Transport security covers data in flight. The other half of the threat model is what the package
+reads back off the local machine: credentials (keychain or file), `config.json`, and state files are
+all attacker-writable if the account is compromised, so none of them is trusted on read.
+
+Each is validated every time it is loaded. A payload that fails to parse, or that parses but does
+not match the expected shape, is **rejected** and the caller falls back to its documented default —
+no credentials, no config overrides, fresh state. Every rejection is recorded in `mcp.log`, so a
+corrupted or tampered store is distinguishable from one that was never created; before this, both
+were silent and looked identical to a fresh install. See
+[Diagnostics](#diagnostics) for the event names.
+
+Log fields carry only the file path (or the keychain service name) and a short machine-readable
+reason. File contents, keychain payloads, and tokens are never logged.
+
 ## Cursor hook forwarder (opt-in)
 
 `aixle-insights init --hooks --tool-name cursor` installs a Node script as a Cursor hook (`~/.cursor/hooks.json`). The script appends redacted hook payloads to `~/.aixle-insights/hooks-queue.ndjson`; the background sync drains the queue on its next cycle and POSTs the events with accurate per-turn model attribution. Requires a Cursor restart after install. To remove, run `aixle-insights uninstall-hooks` and restart Cursor again.
@@ -225,6 +239,35 @@ aixle-insights verify-hooks  # JSON: hooks installed + queue depth
 
 `mcp.log` (rotates at 5 MiB to `mcp.log.1`) under the app home directory captures operational events. Inside Claude Code, the **`aixle_insights_status`** MCP tool returns the same diagnostic structure as `aixle-insights health`.
 
+### Local-store integrity events
+
+These four are the only signal that a local store was present but unusable — `health` and
+`aixle_insights_status` do **not** report them, so `mcp.log` is the sole surface:
+
+| Event | Fires when |
+|---|---|
+| `credentials_parse_failed` | `credentials.json` exists but was rejected |
+| `credentials_keytar_parse_failed` | the OS keychain entry exists but was rejected |
+| `config_parse_failed` | `config.json` exists but was rejected |
+| `state_parse_failed` | a state file exists but was rejected |
+
+Each carries a `reason` distinguishing the two failure modes:
+
+- `invalid_json` — the payload did not parse at all.
+- `invalid_shape` — it parsed, but validation rejected it: credentials with no usable token, a
+  `config.json` that is a JSON array, a state file missing `version` / `sessions`, and so on.
+
+Three properties are worth relying on:
+
+- An **absent** file never warns. That is the everyday case (most users never create a
+  `config.json`, and every machine starts with no state file), so a warning always means something
+  is actually there and wrong.
+- A **missing or disabled OS keychain** never warns either — falling back to the file is expected
+  on headless Linux, CI, and containers, not an error.
+- All four are written to the log **only**, never mirrored to stderr, because stray output on the
+  stdio transport corrupts the MCP protocol. Emitting a warning never changes the fallback the
+  caller returns.
+
 ## Troubleshooting
 
 | Symptom | Most likely cause | Fix |
@@ -236,6 +279,9 @@ aixle-insights verify-hooks  # JSON: hooks installed + queue depth
 | `health` shows `authenticated: true` but `last_result` is `sent: 0, failed: N` cycle after cycle | Same as the 401 row above. `authenticated` only proves the OIDC token was acquired, not that the ingest token still validates server-side. | Re-init as above. |
 | `last_result` reports `sent: N` but the Events UI shows nothing | The Temporal worker is not running. The ingest endpoint returns HTTP 202 (queued) regardless of worker state. | `make worker` (or check `docker ps` for `db90-worker`). See [LOCAL-DEV.md](./LOCAL-DEV.md) §1. |
 | `sync_lock_skip {reason: "advisory_lock_held"}` in the log | Another sync cycle is still holding `~/.aixle-insights/state.lock`. | Wait for it to finish; only delete the lock file (`rm -f ~/.aixle-insights/state.lock`) after confirming no `aixle-insights run` process is alive (`pgrep -fa aixle-insights`). |
+| `health` reports `authenticated: false` right after a successful `init`, and `credentials_parse_failed` or `credentials_keytar_parse_failed` is in the log | The credential store exists but was rejected, so it is treated as absent. The `reason` field says whether it failed to parse (`invalid_json`) or parsed into the wrong shape (`invalid_shape`). | Re-run `init`. If you hand-edited `credentials.json` for local testing, remember the keychain is read **first** — see [State + credentials](#state--credentials). |
+| A `config.json` override has no effect, and `config_parse_failed` is in the log | The file is malformed, or is valid JSON that is not an object — a top-level array is the usual mistake. | Fix it to match the shape under [Environment](#environment); until it parses, every override is ignored. |
+| Sync re-sends history that was already delivered, and `state_parse_failed` is in the log | A state file was present but rejected, so sync fell back to fresh state and lost its dedup checkpoints. | This is recovery, not a loop — the next successful cycle writes valid state. Ingest upserts by session, so duplicates are absorbed. Worth investigating what wrote the bad file. |
 | `aixle-insights --help` doesn't list `--insecure` | You're running an older published version of the package, not the local source. | `which aixle-insights` shows the path. To run local source: `cd packages/tools/aixle-insights && npm run build && npm link`. To return to the published version: `npm unlink -g @aixle/insights && npm install -g @aixle/insights@latest`. |
 | Not sure whether `aixle-insights` is a `npm link` or a real install | Real installs are regular files; `npm link` is a symlink chain into the repo. | `readlink "$(which aixle-insights)"` shows the link target if any. A linked install will trace back to a path under your monorepo checkout. |
 
@@ -274,7 +320,9 @@ After the script reports success: **quit and reopen Claude Code / Cursor** so ea
 
 ## Requirements
 
-- Node.js ≥ 20.
+- Node.js >= 20.19.0 — matches `engines.node` in `package.json`, and
+  `src/test/supply-chain-contract.test.ts` fails if the two drift apart. Older
+  20.x patch releases are not supported.
 - macOS / Linux / Windows. On Windows, the package writes a `cmd /c npx …` wrapper in `~/.claude.json` so Claude Code can spawn the MCP server reliably.
 - `better-sqlite3` is a native module. After a Node upgrade, if SQLite reads start failing, rebuild it from the tools workspace:
 

package/dist/auth/credentials.js

@@ -4,6 +4,7 @@ import { userInfo } from "node:os";
 import { join } from "node:path";
 import { getAppDir } from "../state.js";
 import { mcpLog } from "../log.js";
+import { describeReadFailure } from "../lib/parse-error.js";
 export const KEYTAR_SERVICE = "aixle-insights";
 const KEYTAR_ACCOUNT = "aixle-insights-ingest-credential";
 function credentialsPath(appDir) {
@@ -62,15 +63,23 @@ export function loadCredentialsFromFileOnly(appDir = getAppDir()) {
     const filePath = credentialsPath(appDir);
     if (!existsSync(filePath))
         return null;
+    let raw;
     try {
-        const raw = JSON.parse(readFileSync(filePath, "utf-8"));
-        return normalizeLoadedCredentials(raw);
+        raw = JSON.parse(readFileSync(filePath, "utf-8"));
     }
     catch (err) {
-        // File exists (checked above) but failed to parse/normalize — distinguishes tampering from "never created".
-        mcpLog.warn("credentials_parse_failed", { path: filePath, error: err instanceof Error ? err.message : String(err) }, false);
+        // File exists (checked above) but is not readable/valid JSON — distinguishes tampering from "never created".
+        mcpLog.warn("credentials_parse_failed", { path: filePath, ...describeReadFailure(err) }, false);
         return null;
     }
+    const normalized = normalizeLoadedCredentials(raw);
+    if (normalized === null) {
+        // Valid JSON, but not a credential shape we accept. `normalizeLoadedCredentials` signals
+        // rejection by returning null and never throws, so this cannot surface in the catch
+        // above — without this branch a plausible-looking replacement file stays silent. (DB90DV-699)
+        mcpLog.warn("credentials_parse_failed", { path: filePath, reason: "invalid_shape" }, false);
+    }
+    return normalized;
 }
 async function tryKeytarGet() {
     if (keytarDisabled())
@@ -86,15 +95,22 @@ async function tryKeytarGet() {
     }
     if (!raw)
         return null;
+    let parsed;
     try {
-        const parsed = JSON.parse(raw);
-        return normalizeLoadedCredentials(parsed);
+        parsed = JSON.parse(raw);
     }
     catch (err) {
-        // Keychain entry exists (checked above) but failed to parse/normalize — distinguishes tampering from "no entry".
-        mcpLog.warn("credentials_keytar_parse_failed", { keytarService: KEYTAR_SERVICE, error: err instanceof Error ? err.message : String(err) }, false);
+        // Keychain entry exists (checked above) but is not valid JSON — distinguishes tampering from "no entry".
+        mcpLog.warn("credentials_keytar_parse_failed", { keytarService: KEYTAR_SERVICE, ...describeReadFailure(err) }, false);
         return null;
     }
+    const normalized = normalizeLoadedCredentials(parsed);
+    if (normalized === null) {
+        // Same shape-rejection hole as the file path above. Fields stay service-only — never the
+        // keychain payload. (DB90DV-699)
+        mcpLog.warn("credentials_keytar_parse_failed", { keytarService: KEYTAR_SERVICE, reason: "invalid_shape" }, false);
+    }
+    return normalized;
 }
 async function tryKeytarSet(payload) {
     if (keytarDisabled())

package/dist/auth/exchange.d.ts

@@ -11,7 +11,7 @@ export interface ExchangeResult {
 }
 type ExchangeToolId = "claude_code" | "cursor";
 export declare function exchangeIngestToken(params: {
-    apiHost: string;
+    db90Host: string;
     keycloakAccessToken: string;
     /** Legacy single-tool mint. Omit when tools is provided. */
     toolName?: ExchangeToolId;

package/dist/auth/exchange.js

@@ -1,7 +1,7 @@
 export async function exchangeIngestToken(params) {
     const fetchFn = params.fetchImpl ?? fetch;
     const requestedTools = params.tools?.length ? [...params.tools] : params.toolName ? [params.toolName] : [];
-    const base = params.apiHost.replace(/\/$/, "");
+    const base = params.db90Host.replace(/\/$/, "");
     const url = `${base}/api/v1/integrations/mcp/exchange`;
     const body = {};
     if (params.tools?.length) {

package/dist/auth/flow.d.ts

@@ -1,7 +1,7 @@
 import { defaultKeycloakClientId, defaultKeycloakIssuer } from "./keycloak.js";
 import type { TelemetryToolId } from "./credentials.js";
 export interface LoginAndPersistOptions {
-    apiHost: string;
+    db90Host: string;
     keycloakIssuer: string;
     /** @deprecated Prefer `tools`; kept for callers that mint a single ingest account. */
     toolName?: string;
@@ -12,8 +12,6 @@ export interface LoginAndPersistOptions {
     clientId?: string;
     appDir?: string;
     allowInsecureHttp?: boolean;
-    /** Skip the "already authenticated" short-circuit and re-run the device flow. */
-    force?: boolean;
     onSecurityWarning?: (message: string) => void;
     onVisitInstructions?: (verification_uri: string, user_code: string) => void;
     fetchImpl?: typeof fetch;
@@ -21,11 +19,6 @@ export interface LoginAndPersistOptions {
 export declare function loginAndPersistCredentials(opts: LoginAndPersistOptions): Promise<{
     ok: true;
     organizationId: string;
-} | {
-    ok: true;
-    alreadyAuthenticated: true;
-    host: string;
-    organizationId?: string;
 } | {
     ok: false;
     error: string;

package/dist/auth/flow.js

@@ -3,36 +3,15 @@ import { defaultKeycloakClientId, defaultKeycloakIssuer, obtainKeycloakAccessTok
 import { loadCredentials, saveStoredCredentials } from "./credentials.js";
 import { getAppDir } from "../state.js";
 import { evaluateTransportSecurity } from "../lib/transport-security.js";
-function normalizeHostForComparison(host) {
-    return host.replace(/\/$/, "");
-}
-function credentialsCoverRequestedTools(creds, requestedTools) {
-    return requestedTools.every((tool) => {
-        const token = creds.accounts[tool];
-        return typeof token === "string" && token.length > 0;
-    });
-}
-function credentialsMatchRequestedScope(creds, opts, requestedTools) {
-    if (normalizeHostForComparison(creds.host) !== normalizeHostForComparison(opts.apiHost))
-        return false;
-    if (opts.exchangeOrganizationId && creds.organizationId !== opts.exchangeOrganizationId)
-        return false;
-    return credentialsCoverRequestedTools(creds, requestedTools);
-}
 export async function loginAndPersistCredentials(opts) {
-    const appDir = opts.appDir ?? getAppDir();
-    const requestedTools = opts.tools ?? ((opts.toolName ?? "claude_code") === "cursor" ? ["cursor"] : ["claude_code"]);
-    if (!opts.force) {
-        const existing = await loadCredentials(appDir);
-        if (existing && credentialsMatchRequestedScope(existing, opts, requestedTools)) {
-            return { ok: true, alreadyAuthenticated: true, host: existing.host, organizationId: existing.organizationId };
-        }
-    }
     const issuer = opts.keycloakIssuer.trim();
     if (!issuer) {
         return { ok: false, error: "Keycloak issuer is empty; set KEYCLOAK_ISSUER or pass --keycloak-url." };
     }
     const clientId = opts.clientId?.trim() || defaultKeycloakClientId();
+    const appDir = opts.appDir ?? getAppDir();
+    const requestedTools = opts.tools ??
+        ((opts.toolName ?? "claude_code") === "cursor" ? ["cursor"] : ["claude_code"]);
     let accessToken;
     try {
         accessToken = await obtainKeycloakAccessTokenViaDeviceFlow({
@@ -49,7 +28,7 @@ export async function loginAndPersistCredentials(opts) {
     try {
         if (requestedTools.length > 1) {
             exchanged = await exchangeIngestToken({
-                apiHost: opts.apiHost,
+                db90Host: opts.db90Host,
                 keycloakAccessToken: accessToken,
                 tools: requestedTools,
                 deviceLabel: opts.deviceLabel,
@@ -59,7 +38,7 @@ export async function loginAndPersistCredentials(opts) {
         }
         else {
             exchanged = await exchangeIngestToken({
-                apiHost: opts.apiHost,
+                db90Host: opts.db90Host,
                 keycloakAccessToken: accessToken,
                 toolName: requestedTools[0],
                 deviceLabel: opts.deviceLabel,

package/dist/auth/keycloak.d.ts

@@ -31,5 +31,5 @@ export declare function obtainKeycloakAccessTokenViaDeviceFlow(params: {
     onInstructions?: (verification_uri: string, user_code: string) => void;
     fetchImpl?: typeof fetch;
 }): Promise<string>;
-export declare function defaultKeycloakIssuer(ingestHost?: string): string;
+export declare function defaultKeycloakIssuer(): string;
 export declare function defaultKeycloakClientId(): string;

package/dist/auth/keycloak.js

@@ -2,7 +2,6 @@
  * RFC 8628 OAuth 2.0 Device Authorization Grant against Keycloak OIDC endpoints.
  */
 import { createHash, randomBytes } from "node:crypto";
-import { isLoopbackHost } from "../lib/transport-security.js";
 function normalizeIssuer(issuer) {
     return issuer.replace(/\/$/, "");
 }
@@ -155,31 +154,13 @@ export async function obtainKeycloakAccessTokenViaDeviceFlow(params) {
         fetchImpl: params.fetchImpl,
     });
 }
-export function defaultKeycloakIssuer(ingestHost) {
+export function defaultKeycloakIssuer() {
     const fromEnv = process.env["DB90_KEYCLOAK_ISSUER"]?.trim() ||
         process.env["KEYCLOAK_ISSUER"]?.trim();
     if (fromEnv)
         return fromEnv.replace(/\/$/, "");
     const useLocalDefault = ["1", "true", "yes"].includes(process.env["DB90_MCP_USE_LOCAL_KEYCLOAK_DEFAULT"]?.toLowerCase() ?? "");
     if (useLocalDefault || process.env["NODE_ENV"] === "development") {
-        if (ingestHost) {
-            let hostname;
-            try {
-                hostname = new URL(ingestHost).hostname;
-            }
-            catch {
-                hostname = ingestHost;
-            }
-            if (!isLoopbackHost(hostname)) {
-                const reason = useLocalDefault
-                    ? `DB90_MCP_USE_LOCAL_KEYCLOAK_DEFAULT=${process.env["DB90_MCP_USE_LOCAL_KEYCLOAK_DEFAULT"]}`
-                    : `NODE_ENV=development`;
-                console.error(`[aixle-insights] Warning: ${reason} would redirect Keycloak authentication to ` +
-                    `http://localhost:8080, but the ingest host "${ingestHost}" is not localhost. ` +
-                    `Ignoring the local Keycloak default. Set DB90_KEYCLOAK_ISSUER explicitly.`);
-                return "";
-            }
-        }
         return "http://localhost:8080/realms/db90";
     }
     return "";

package/dist/cli.d.ts

@@ -7,9 +7,8 @@ import { migrateLegacyState, getAppDir } from "./state.js";
 import { syncTelemetryTools } from "./sync.js";
 import { mergePricing } from "./pricing.js";
 import { type InstallClaudeUserMcpOptions, type InstallResult } from "./install/claude.js";
-import { type InstallCursorUserMcpOptions } from "./install/cursor.js";
 export interface Args {
-    command: "init" | "health" | "run" | "help" | "uninstall-hooks" | "verify-hooks" | "uninstall-cursor-mcp";
+    command: "init" | "health" | "run" | "help" | "uninstall-hooks" | "verify-hooks";
     help: boolean;
     once: boolean;
     /** With `run --once`: ignore Cursor watermarks and commit hash dedupe. */
@@ -40,13 +39,12 @@ interface InitDeps {
     defaultKeycloakIssuer: typeof defaultKeycloakIssuer;
     getAppDir: typeof getAppDir;
     installClaudeUserMcp: (options: InstallClaudeUserMcpOptions) => InstallResult;
-    installCursorUserMcp: (options: InstallCursorUserMcpOptions) => InstallResult;
     log: (message: string) => void;
     error: (message: string) => void;
 }
 /** Matches DB90 Rails `McpController` UUID check for `X-Organization-ID` (RFC 4122 variant). */
-export declare const ORGANIZATION_UUID_PATTERN: RegExp;
-export declare function isValidOrganizationUuid(value: string): boolean;
+export declare const DB90_ORGANIZATION_UUID_PATTERN: RegExp;
+export declare function isValidDb90OrganizationUuid(value: string): boolean;
 export declare function parseArgs(argv: string[]): Args;
 export declare function runInit(cliArgs: Args, deps?: Partial<InitDeps>): Promise<number>;
 export declare function runOnce(deps?: Partial<RunOnceDeps>, options?: {

package/dist/cli.js

@@ -11,7 +11,6 @@ import { DEFAULT_PRICING, mergePricing } from "./pricing.js";
 import { resolveCursorPricing } from "./cursor-config.js";
 import { buildHealthSnapshot, formatHealthForCli } from "./health.js";
 import { installClaudeUserMcp } from "./install/claude.js";
-import { installCursorUserMcp, uninstallCursorUserMcp } from "./install/cursor.js";
 import { installHooksConfig, uninstallHooksConfig, verifyHooksConfig, FORWARDER_FILENAME } from "./hooks/hooks-config.js";
 import { evaluateTransportSecurity } from "./lib/transport-security.js";
 import { join } from "node:path";
@@ -21,9 +20,9 @@ const GLOBAL_FLAGS = new Set(["--help", "-h", "--once", "--full"]);
 const INIT_VALUE_FLAGS = new Set(["--host", "--keycloak-url", "--tool-name", "--organization-id"]);
 const INIT_BOOLEAN_FLAGS = new Set(["--force", "--hooks", "--insecure"]);
 /** Matches DB90 Rails `McpController` UUID check for `X-Organization-ID` (RFC 4122 variant). */
-export const ORGANIZATION_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
-export function isValidOrganizationUuid(value) {
-    return ORGANIZATION_UUID_PATTERN.test(value.trim());
+export const DB90_ORGANIZATION_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+export function isValidDb90OrganizationUuid(value) {
+    return DB90_ORGANIZATION_UUID_PATTERN.test(value.trim());
 }
 function takeFlagValue(argv, name) {
     const eqForm = argv.find((a) => a.startsWith(`${name}=`));
@@ -148,7 +147,7 @@ export function parseArgs(argv) {
     if (raw === "serve") {
         return { command: "run", help, once, full: full || undefined };
     }
-    if (raw === "uninstall-hooks" || raw === "verify-hooks" || raw === "uninstall-cursor-mcp") {
+    if (raw === "uninstall-hooks" || raw === "verify-hooks") {
         return { command: raw, help: false, once: false };
     }
     return { command: "help", help: true, once: false };
@@ -161,12 +160,11 @@ Usage:
   aixle-insights [command] [options]
 
 Commands:
-  run                   Start the MCP stdio server (default — used by Claude Code).
-  init                  Keycloak device login once, then persist DB90 ingest credentials (keychain or file).
-  health                Multi-line diagnostic (credentials, sync, log path, state files).
-  uninstall-hooks       Remove DB90 from ~/.cursor/hooks.json and restore backup (if any).
-  verify-hooks          Print hooks install status and queue depth as JSON.
-  uninstall-cursor-mcp  Remove aixle-insights from ~/.cursor/mcp.json and restore backup (if any).
+  run              Start the MCP stdio server (default — used by Claude Code).
+  init             Keycloak device login once, then persist DB90 ingest credentials (keychain or file).
+  health           Multi-line diagnostic (credentials, sync, log path, state files).
+  uninstall-hooks  Remove DB90 from ~/.cursor/hooks.json and restore backup (if any).
+  verify-hooks     Print hooks install status and queue depth as JSON.
 
 Options:
   --once      With 'run': perform a multi-tool sync then exit (no MCP server).
@@ -178,8 +176,7 @@ init options:
   --keycloak-url <issuer>  Keycloak realm issuer (default: env KEYCLOAK_ISSUER / DB90_KEYCLOAK_ISSUER)
   --tool-name <name>       Optional: mint only \`claude_code\`, only \`cursor\`, or omit to mint BOTH.
   --organization-id <uuid> Optional: scope MCP token exchange to this org (overrides env DB90_ORGANIZATION_ID).
-  --force                  Re-run the device flow even if valid credentials already exist, and
-                           replace an existing user "aixle-insights" MCP entry in ~/.claude.json if it differs.
+  --force                  Replace an existing user "aixle-insights" MCP entry in ~/.claude.json if it differs.
   --hooks                  (opt-in) Install Cursor hook forwarder for per-turn model attribution.
                            Requires Cursor restart. Run 'aixle-insights uninstall-hooks' to remove.
   --insecure               Allow remote http:// hosts for trusted non-production test endpoints only.
@@ -194,7 +191,7 @@ Credentials:
 Note: Omitting --tool-name provisions separate ingest tokens for Claude Code + Cursor behind a single Keycloak login.
 `);
 }
-function defaultApiHost() {
+function defaultDb90Host() {
     const v = process.env["DB90_API_URL"]?.trim();
     if (v)
         return v.replace(/\/$/, "");
@@ -214,13 +211,12 @@ export async function runInit(cliArgs, deps) {
         defaultKeycloakIssuer,
         getAppDir,
         installClaudeUserMcp,
-        installCursorUserMcp,
         log: console.log,
         error: console.error,
         ...deps,
     };
-    const apiHost = (cliArgs.host ?? defaultApiHost()).replace(/\/$/, "");
-    const transportSecurity = evaluateTransportSecurity(apiHost, {
+    const db90Host = (cliArgs.host ?? defaultDb90Host()).replace(/\/$/, "");
+    const transportSecurity = evaluateTransportSecurity(db90Host, {
         allowInsecureHttp: cliArgs.insecure === true,
         label: "DB90 API host",
     });
@@ -232,6 +228,10 @@ export async function runInit(cliArgs, deps) {
         runtime.error(`Warning: ${transportSecurity.warning}`);
     }
     const kcIssuer = (cliArgs.keycloakUrl ?? runtime.defaultKeycloakIssuer()).trim();
+    if (!kcIssuer) {
+        runtime.error("Error: Keycloak issuer is not configured. Pass --keycloak-url or set KEYCLOAK_ISSUER / DB90_KEYCLOAK_ISSUER.");
+        return 1;
+    }
     if (cliArgs.toolName !== undefined && !["claude_code", "cursor"].includes(cliArgs.toolName)) {
         runtime.error("Error: --tool-name must be one of: claude_code, cursor.");
         return 1;
@@ -244,12 +244,12 @@ export async function runInit(cliArgs, deps) {
     const fromFlag = cliArgs.organizationId?.trim();
     const fromEnv = process.env["DB90_ORGANIZATION_ID"]?.trim();
     const exchangeOrganizationId = fromFlag || fromEnv;
-    if (exchangeOrganizationId && !isValidOrganizationUuid(exchangeOrganizationId)) {
+    if (exchangeOrganizationId && !isValidDb90OrganizationUuid(exchangeOrganizationId)) {
         runtime.error("Error: --organization-id / DB90_ORGANIZATION_ID must be a valid UUID (RFC 4122, version 1–5, variant per DB90 API).");
         return 1;
     }
     const result = await runtime.loginAndPersistCredentials({
-        apiHost,
+        db90Host,
         keycloakIssuer: kcIssuer,
         tools: provisionTools.length > 1 ? provisionTools : undefined,
         toolName: provisionTools.length === 1
@@ -261,7 +261,6 @@ export async function runInit(cliArgs, deps) {
         appDir: runtime.getAppDir(),
         exchangeOrganizationId: exchangeOrganizationId || undefined,
         allowInsecureHttp: cliArgs.insecure === true,
-        force: cliArgs.force === true,
         onSecurityWarning: (message) => {
             runtime.error(`Warning: ${message}`);
         },
@@ -273,12 +272,7 @@ export async function runInit(cliArgs, deps) {
         runtime.error(`Auth failed: ${result.error}`);
         return 1;
     }
-    if ("alreadyAuthenticated" in result) {
-        runtime.log(`Already authenticated (organization ${result.organizationId ?? "unknown"}). Pass --force to re-authenticate.`);
-    }
-    else {
-        runtime.log(`Credentials saved (organization ${result.organizationId}).`);
-    }
+    runtime.log(`Credentials saved (organization ${result.organizationId}).`);
     if (cliArgs.hooks) {
         const appDir = runtime.getAppDir();
         const thisFile = nodeFileURLToPath(import.meta.url);
@@ -324,28 +318,6 @@ export async function runInit(cliArgs, deps) {
     else {
         runtime.log("Skipped Claude Code MCP auto-install (--tool-name cursor only).");
     }
-    const shouldInstallCursor = provisionTools.includes("cursor");
-    if (shouldInstallCursor) {
-        const cursorInstallResult = runtime.installCursorUserMcp({ force: cliArgs.force === true });
-        switch (cursorInstallResult.kind) {
-            case "already-configured":
-                runtime.log("Cursor MCP: aixle-insights server is already configured for your user.");
-                break;
-            case "installed":
-                runtime.log("Cursor MCP: added aixle-insights server to ~/.cursor/mcp.json.");
-                break;
-            case "requires-force":
-                runtime.error(cursorInstallResult.detail);
-                return 1;
-            case "error":
-                runtime.error(`Cursor MCP install failed: ${cursorInstallResult.message}`);
-                return 1;
-        }
-        runtime.log("Restart Cursor to activate the aixle-insights MCP server.");
-    }
-    else {
-        runtime.log("Skipped Cursor MCP auto-install (--tool-name claude_code only).");
-    }
     return 0;
 }
 export async function runOnce(deps, options) {
@@ -362,8 +334,6 @@ export async function runOnce(deps, options) {
     };
     const creds = await runtime.loadCredentials();
     if (!creds || !credentialsHaveAnyToken(creds)) {
-        // File-only: runOnce prints a user-facing error below, so mirroring this
-        // structured warn would just duplicate the message on stderr.
         mcpLog.warn("credential_validation_failed", { source: "cli_once", reason: "missing_credentials" }, false);
         runtime.error("Error: no Aixle Insights credentials. Run `aixle-insights init` first (dual-tool auth is the default).");
         return 1;
@@ -438,24 +408,6 @@ async function main() {
             }
             return;
         }
-        case "uninstall-cursor-mcp": {
-            const result = uninstallCursorUserMcp();
-            switch (result.kind) {
-                case "restored":
-                    console.log(`Cursor MCP entry removed; ~/.cursor/mcp.json restored from ${result.backupPath}.`);
-                    break;
-                case "removed":
-                    console.log("Cursor MCP entry removed from ~/.cursor/mcp.json.");
-                    break;
-                case "noop":
-                    console.log("No aixle-insights entry found in ~/.cursor/mcp.json — nothing to uninstall.");
-                    break;
-                case "error":
-                    console.error(`Cursor MCP uninstall failed: ${result.message}`);
-                    process.exit(1);
-            }
-            return;
-        }
         case "verify-hooks": {
             const report = verifyHooksConfig(getAppDir());
             console.log(JSON.stringify(report, null, 2));

package/dist/collect-cursor-payloads.d.ts

@@ -1,10 +1,10 @@
 import type { ProjectResolution } from "./lib/index.js";
 import type { State } from "./state.js";
-import { type CursorPayload, type CursorTranscriptTurn, type PricingConfig } from "./readers/cursor.js";
+import { type CursorDb90Payload, type CursorTranscriptTurn, type PricingConfig } from "./readers/cursor.js";
 export interface CursorSliceGroup {
     key: string;
     label: string;
-    payloads: CursorPayload[];
+    payloads: CursorDb90Payload[];
 }
 export interface PrepareCursorSliceGroupsOptions {
     stateBefore: State;
@@ -47,7 +47,7 @@ export interface CollectLocalCursorPayloadsOptions {
     stateBefore?: State;
 }
 export interface CollectedCursorPayloads {
-    payloads: CursorPayload[];
+    payloads: CursorDb90Payload[];
     counts: PreparedCursorSliceGroups["counts"];
 }
 /**

package/dist/cursor-checkpoints.d.ts

@@ -1,5 +1,5 @@
 import type { State } from "./state.js";
-import type { CursorPayload } from "./readers/cursor.js";
+import type { CursorDb90Payload } from "./readers/cursor.js";
 /** Cursor SQLite watermark checkpoints — never collide with Claude `claude_code:*` session keys. */
 export declare const CURSOR_WATERMARK_KEY: "cursor:watermark";
 export declare const CURSOR_EVENTS_WATERMARK_KEY: "cursor:events_watermark";
@@ -9,4 +9,4 @@ export declare const CURSOR_TRANSCRIPT_TURN_PREFIX: "cursor:transcript_turn:";
 export declare function cursorTranscriptTurnStateKey(turnId: string): string;
 export declare function cursorWatermarkDate(state: Pick<State, "sessions">, ...keys: string[]): Date | null;
 /** Skip recent-commit payloads whose hash was already successfully POSTed. */
-export declare function filterRecentCommitsByHashDedup(payloads: CursorPayload[], lastRecentCommitHashes?: string[]): CursorPayload[];
+export declare function filterRecentCommitsByHashDedup(payloads: CursorDb90Payload[], lastRecentCommitHashes?: string[]): CursorDb90Payload[];