@monadeo.com/grimoire-cli 0.3.6 → 0.4.0

package/dist/index.js

@@ -10,7 +10,7 @@ import { join as join6 } from "node:path";
 import { readFileSync, existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-var DEFAULT_API_BASE = "https://grimoire-api.monadeo.com";
+var DEFAULT_API_BASE = "https://cli.grimoire.monadeo.com";
 function globalConfigPath() {
   return join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "grimoire", "config.json");
 }
@@ -99,116 +99,224 @@ async function fetchWithTimeout(url, init = {}) {
 }
 
 // ../core/dist/auth.js
+function configDir() {
+  return join2(process.env.XDG_CONFIG_HOME ?? join2(homedir2(), ".config"), "grimoire");
+}
 function credentialsPath() {
-  return join2(process.env.XDG_CONFIG_HOME ?? join2(homedir2(), ".config"), "grimoire", "credentials.json");
+  return join2(configDir(), "credentials.json");
 }
-function storeRefreshToken(token) {
+function storeSession(session) {
   const path = credentialsPath();
   mkdirSync2(dirname2(path), { recursive: true, mode: 448 });
-  writeFileSync2(path, JSON.stringify({ refresh_token: token }) + "\n", { mode: 384 });
+  writeFileSync2(path, JSON.stringify(session) + "\n", { mode: 384 });
 }
-function readRefreshToken() {
+function readSession() {
   try {
     const parsed = JSON.parse(readFileSync2(credentialsPath(), "utf8"));
-    return typeof parsed.refresh_token === "string" && parsed.refresh_token !== "" ? parsed.refresh_token : void 0;
+    if (typeof parsed.refresh_token === "string" && parsed.refresh_token !== "" && typeof parsed.supabase_url === "string" && typeof parsed.supabase_anon_key === "string") {
+      return {
+        refresh_token: parsed.refresh_token,
+        supabase_url: parsed.supabase_url,
+        supabase_anon_key: parsed.supabase_anon_key
+      };
+    }
+    return void 0;
   } catch {
     return void 0;
   }
 }
-function clearRefreshToken() {
+function clearSession() {
   if (existsSync2(credentialsPath()))
     rmSync(credentialsPath());
 }
+function machineTokenPath() {
+  return join2(configDir(), "machine-token");
+}
+function storeMachineToken(token) {
+  const path = machineTokenPath();
+  mkdirSync2(dirname2(path), { recursive: true, mode: 448 });
+  writeFileSync2(path, token + "\n", { mode: 384 });
+}
+function readMachineToken() {
+  try {
+    const token = readFileSync2(machineTokenPath(), "utf8").trim();
+    return token !== "" ? token : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function clearMachineToken() {
+  if (existsSync2(machineTokenPath()))
+    rmSync(machineTokenPath());
+}
+async function fetchAuthConfig(apiBase) {
+  const res = await fetchWithTimeout(`${apiBase.replace(/\/+$/, "")}/v1/auth/config`);
+  if (!res.ok)
+    throw new ApiError(res.status, "auth_config_unavailable", await res.text());
+  const body = await res.json();
+  if (typeof body.supabase_url !== "string" || typeof body.supabase_anon_key !== "string" || typeof body.oauth_provider !== "string" || !Array.isArray(body.redirect_urls) || body.redirect_urls.length === 0) {
+    throw new ApiError(res.status, "auth_config_malformed", body);
+  }
+  return {
+    supabase_url: body.supabase_url,
+    supabase_anon_key: body.supabase_anon_key,
+    oauth_provider: body.oauth_provider,
+    redirect_urls: body.redirect_urls.map(String)
+  };
+}
+function parseDetail(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+async function gotrueToken(supabaseUrl, anonKey, grantType, body) {
+  const res = await fetchWithTimeout(`${supabaseUrl.replace(/\/+$/, "")}/auth/v1/token?grant_type=${grantType}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", apikey: anonKey },
+    body: JSON.stringify(body)
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new ApiError(res.status, grantType === "pkce" ? "login_failed" : "refresh_failed", parseDetail(text));
+  }
+  const parsed = JSON.parse(text);
+  if (typeof parsed.access_token !== "string" || typeof parsed.refresh_token !== "string" || typeof parsed.expires_in !== "number") {
+    throw new ApiError(res.status, "token_malformed", parsed);
+  }
+  return {
+    access_token: parsed.access_token,
+    refresh_token: parsed.refresh_token,
+    expires_in: parsed.expires_in
+  };
+}
 function base64url(buf) {
   return buf.toString("base64url");
 }
-async function browserLogin(apiBase, openBrowser2) {
-  const broker = apiBase.replace(/\/+$/, "");
+async function bindCallback(server, redirectUrls) {
+  for (const candidate of redirectUrls) {
+    const port = Number(new URL(candidate).port);
+    const bound = await new Promise((resolve) => {
+      const onError = () => {
+        server.off("error", onError);
+        resolve(false);
+      };
+      server.once("error", onError);
+      server.listen(port, "127.0.0.1", () => {
+        server.off("error", onError);
+        resolve(true);
+      });
+    });
+    if (bound)
+      return candidate;
+  }
+  throw new Error(`No free login callback port among: ${redirectUrls.join(", ")}`);
+}
+async function browserLogin(apiBase, openBrowser, timeoutMs = 3e5) {
+  const config = await fetchAuthConfig(apiBase);
   const verifier = base64url(randomBytes(32));
   const challenge = base64url(createHash("sha256").update(verifier).digest());
   const state = base64url(randomBytes(16));
   const code = await new Promise((resolve, reject) => {
-    const server = createServer((req, res2) => {
+    let timer;
+    const finish2 = (outcome) => {
+      if (timer)
+        clearTimeout(timer);
+      server.closeAllConnections();
+      server.close();
+      if ("code" in outcome)
+        resolve(outcome.code);
+      else
+        reject(outcome.error);
+    };
+    const server = createServer((req, res) => {
       const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (req.method !== "GET" || url.pathname !== `/callback/${state}`) {
+        res.writeHead(404).end();
+        return;
+      }
+      const failure = url.searchParams.get("error_description") ?? url.searchParams.get("error");
       const received = url.searchParams.get("code");
-      if (req.method !== "GET" || url.pathname !== "/callback" || url.searchParams.get("state") !== state || !received) {
-        res2.writeHead(404).end();
+      if (failure || !received) {
+        res.writeHead(400, { "Content-Type": "text/plain" }).end(`Login failed: ${failure ?? "no code"}`);
+        finish2({ error: new Error(`Login failed: ${failure ?? "no code returned"}`) });
         return;
       }
-      res2.writeHead(302, { Location: `${broker}/auth/cli/success` }).end();
-      clearTimeout(timer);
-      server.close();
-      resolve(received);
+      res.writeHead(200, { "Content-Type": "text/plain" }).end("Logged in to Grimoire. You can close this tab.");
+      finish2({ code: received });
     });
-    server.listen(0, "127.0.0.1", () => {
-      const port = server.address().port;
-      const redirect = `http://127.0.0.1:${port}/callback`;
-      openBrowser2(`${broker}/auth/cli/start?code_challenge=${challenge}&code_challenge_method=S256&state=${state}&redirect_uri=${encodeURIComponent(redirect)}`);
-    });
-    const timer = setTimeout(() => {
-      server.close();
-      reject(new Error("Login timed out"));
-    }, 3e5);
+    bindCallback(server, config.redirect_urls).then((redirectBase) => {
+      timer = setTimeout(() => finish2({ error: new Error("Login timed out") }), timeoutMs);
+      const authorize = new URL(`${config.supabase_url.replace(/\/+$/, "")}/auth/v1/authorize`);
+      authorize.searchParams.set("provider", config.oauth_provider);
+      authorize.searchParams.set("redirect_to", `${redirectBase.replace(/\/+$/, "")}/${state}`);
+      authorize.searchParams.set("code_challenge", challenge);
+      authorize.searchParams.set("code_challenge_method", "s256");
+      openBrowser(authorize.toString());
+    }).catch((err) => finish2({ error: err }));
   });
-  const res = await fetchWithTimeout(`${broker}/auth/cli/exchange`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ code, code_verifier: verifier })
+  const tokens = await gotrueToken(config.supabase_url, config.supabase_anon_key, "pkce", {
+    auth_code: code,
+    code_verifier: verifier
+  });
+  storeSession({
+    refresh_token: tokens.refresh_token,
+    supabase_url: config.supabase_url,
+    supabase_anon_key: config.supabase_anon_key
   });
-  if (!res.ok)
-    throw new Error(`Token exchange failed: ${res.status}`);
-  const { refresh_token } = await res.json();
-  if (typeof refresh_token !== "string" || refresh_token.length === 0) {
-    throw new Error("Token exchange succeeded but returned no refresh token");
-  }
-  storeRefreshToken(refresh_token);
 }
 
 // ../core/dist/client.js
+var CODES = {
+  401: "unauthorized",
+  403: "forbidden",
+  404: "not_found",
+  422: "invalid_request",
+  429: "quota_exceeded"
+};
 var GrimoireClient = class {
   baseUrl;
   machineToken;
-  cachedIdToken;
+  cachedAccessToken;
   refreshInFlight;
   constructor(opts = {}) {
     this.baseUrl = (opts.baseUrl ?? loadGlobalConfig().apiBaseUrl).replace(/\/+$/, "");
-    this.machineToken = opts.machineToken ?? process.env.GRIMOIRE_AUTH_TOKEN;
+    this.machineToken = opts.machineToken ?? process.env.GRIMOIRE_AUTH_TOKEN ?? readMachineToken();
   }
   async bearer() {
     if (this.machineToken)
       return this.machineToken;
-    if (this.cachedIdToken && this.cachedIdToken.expiresAt > Date.now() + 6e4) {
-      return this.cachedIdToken.token;
+    if (this.cachedAccessToken && this.cachedAccessToken.expiresAt > Date.now() + 6e4) {
+      return this.cachedAccessToken.token;
     }
-    this.refreshInFlight ??= this.refreshIdToken().finally(() => {
+    this.refreshInFlight ??= this.refreshAccessToken().finally(() => {
       this.refreshInFlight = void 0;
     });
     return this.refreshInFlight;
   }
-  // Exchange the Firebase refresh token for a fresh ID token (silent refresh).
-  async refreshIdToken() {
-    const refresh = readRefreshToken();
-    if (!refresh)
+  // Exchange the stored refresh token for a fresh access token. GoTrue rotates
+  // refresh tokens, so the new one replaces the stored one every time.
+  async refreshAccessToken() {
+    const session = readSession();
+    if (!session)
       throw new ApiError(401, "not_logged_in", "Run `grimoire login`");
-    const res = await fetchWithTimeout(`${this.baseUrl}/auth/cli/refresh`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ refresh_token: refresh })
-    });
-    if (!res.ok)
-      throw new ApiError(res.status, "refresh_failed", "Run `grimoire login`");
-    let payload;
+    let tokens;
     try {
-      payload = await res.json();
-    } catch {
-      throw new ApiError(res.status, "refresh_failed", "Malformed refresh response");
-    }
-    const { id_token, expires_in } = payload;
-    if (typeof id_token !== "string" || typeof expires_in !== "number") {
-      throw new ApiError(res.status, "refresh_failed", "Malformed refresh response");
+      tokens = await gotrueToken(session.supabase_url, session.supabase_anon_key, "refresh_token", {
+        refresh_token: session.refresh_token
+      });
+    } catch (err) {
+      if (err instanceof ApiError)
+        throw new ApiError(err.status, "refresh_failed", "Run `grimoire login`");
+      throw err;
     }
-    this.cachedIdToken = { token: id_token, expiresAt: Date.now() + expires_in * 1e3 };
-    return id_token;
+    storeSession({ ...session, refresh_token: tokens.refresh_token });
+    this.cachedAccessToken = {
+      token: tokens.access_token,
+      expiresAt: Date.now() + tokens.expires_in * 1e3
+    };
+    return tokens.access_token;
   }
   async refreshSession() {
     await this.bearer();
@@ -225,11 +333,12 @@ var GrimoireClient = class {
   async request(path, init = {}, auth = true) {
     let res = await this.send(path, init, auth);
     if (res.status === 401 && auth && !this.machineToken) {
-      this.cachedIdToken = void 0;
+      this.cachedAccessToken = void 0;
       res = await this.send(path, init, auth);
     }
     return this.parseResponse(res);
   }
+  // FastAPI errors carry {"detail": "..."} (string) or {"detail": [...]} (422).
   async parseResponse(res) {
     const isJson = res.headers.get("content-type")?.includes("json") ?? false;
     const text = await res.text();
@@ -244,33 +353,28 @@ var GrimoireClient = class {
       }
     }
     if (!res.ok) {
-      const code = parsed && typeof body === "object" && body !== null ? body.error ?? "error" : "error";
-      throw new ApiError(res.status, code, parsed ? body : text);
+      const detail = parsed && typeof body === "object" && body !== null ? body.detail : void 0;
+      throw new ApiError(res.status, CODES[res.status] ?? "error", detail ?? (parsed ? body : text));
     }
     if (isJson)
       return parsed ? body : {};
     return text;
   }
   search(input) {
-    return this.request("/v1/search", {
-      method: "POST",
-      body: JSON.stringify(input)
-    });
+    return this.request("/v1/search", { method: "POST", body: JSON.stringify(input) });
   }
-  listSources(q) {
-    return this.request(`/v1/sources${q ? `?q=${encodeURIComponent(q)}` : ""}`);
+  listSources() {
+    return this.request("/v1/sources");
   }
-  listVersions(sourceId) {
-    return this.request(`/v1/sources/${encodeURIComponent(sourceId)}/versions`);
+  listVersions(product) {
+    return this.request(`/v1/sources/${encodeURIComponent(product)}/versions`);
   }
-  getContext(chunkId, window = 2) {
-    return this.request(`/v1/documents/${encodeURIComponent(chunkId)}/context?window=${window}`);
+  getDoc(pointId, window = 2) {
+    return this.request(`/v1/doc/${encodeURIComponent(pointId)}?window=${window}`);
   }
-  reportResult(chunkId, verdict, note) {
-    return this.request("/v1/feedback", {
-      method: "POST",
-      body: JSON.stringify({ chunk_id: chunkId, verdict, note })
-    });
+  reportResult(pointId, verdict, note) {
+    const body = { point_id: pointId, verdict, ...note ? { note } : {} };
+    return this.request("/v1/report", { method: "POST", body: JSON.stringify(body) });
   }
   submitSource(body) {
     return this.request("/v1/sources", { method: "POST", body: JSON.stringify(body) });
@@ -278,12 +382,49 @@ var GrimoireClient = class {
   getJob(jobId) {
     return this.request(`/v1/jobs/${encodeURIComponent(jobId)}`);
   }
+  me() {
+    return this.request("/v1/me");
+  }
+  reviewQueue() {
+    return this.request("/v1/staff/review-queue");
+  }
+  approveJob(jobId) {
+    return this.request(`/v1/staff/jobs/${encodeURIComponent(jobId)}/approve`, { method: "POST" });
+  }
+  listUsers() {
+    return this.request("/v1/staff/users");
+  }
+  grantUser(subject, name) {
+    return this.request("/v1/staff/users", {
+      method: "POST",
+      body: JSON.stringify({ subject, name })
+    });
+  }
+  revokeUser(subject) {
+    return this.request(`/v1/staff/users/${encodeURIComponent(subject)}`, { method: "DELETE" });
+  }
+  rejectJob(jobId, reason) {
+    return this.request(`/v1/staff/jobs/${encodeURIComponent(jobId)}/reject`, {
+      method: "POST",
+      body: JSON.stringify({ reason })
+    });
+  }
 };
 
 // src/args.ts
 var UsageError = class extends Error {
 };
-var BOOL_FLAGS = /* @__PURE__ */ new Set(["json", "compact", "watch", "private", "names", "http", "unset"]);
+var BOOL_FLAGS = /* @__PURE__ */ new Set([
+  "json",
+  "compact",
+  "watch",
+  "names",
+  "http",
+  "unset",
+  "rolling",
+  "debug",
+  "no-launch-browser"
+]);
 function parseArgs(argv, aliases = {}, allowed) {
   const positionals = [];
   const flags = {};
@@ -334,39 +475,39 @@ function requireFlagOneOf(parsed, name, allowed, usage) {
 
 // src/output.ts
 var EXIT = { ok: 0, apiError: 1, authRequired: 2, quota: 3, notFound: 4 };
-function noteRerank(status) {
-  if (status === void 0) return;
-  const label = status === "used" ? "reranker: used" : status === "degraded" ? "reranker: degraded (fused order)" : "reranker: disabled";
-  process.stderr.write(`${label}
+function preamble(res) {
+  const versions = Object.entries(res.resolved_versions).map(([product, version]) => `${product}@${version}`).join(", ");
+  process.stderr.write(`sources: ${versions} \xB7 retrievals remaining: ${res.retrievals_remaining}
 `);
-}
-function warnWeak(confidence) {
-  if (confidence === "weak") {
-    process.stderr.write(
-      "note: low-confidence results \u2014 the docs may not cover this; tell the user rather than guessing.\n"
-    );
+  process.stderr.write(`note: ${res.untrusted_content_notice}
+`);
+  if (res.results.length === 0) {
+    process.stderr.write("note: no result passed the relevance threshold \u2014 the docs may not cover this.\n");
   }
 }
-function printResults(results, confidence, rerankStatus) {
-  noteRerank(rerankStatus);
-  warnWeak(confidence);
-  for (const r of results) {
-    const path = (r.heading_path ?? []).join(" \u203A ");
-    process.stdout.write(`
-${r.score.toFixed(3)}  ${r.source}@${r.version}  ${path}
-${r.origin_url}
-`);
+function heading(r) {
+  return r.heading_path.join(" \u203A ");
+}
+function printResults(res) {
+  preamble(res);
+  for (const r of res.results) {
+    process.stdout.write(
+      `
+${r.score.toFixed(3)}  ${r.product}@${r.version}  ${heading(r)}
+${r.source_url}
+point_id: ${r.point_id}
+`
+    );
     const preview = r.text.length > 500 ? `${r.text.slice(0, 500)}\u2026` : r.text;
     process.stdout.write(`${preview}
 `);
   }
 }
-function printCompact(results, confidence, rerankStatus) {
-  noteRerank(rerankStatus);
-  warnWeak(confidence);
-  for (const r of results) {
+function printCompact(res) {
+  preamble(res);
+  for (const r of res.results) {
     process.stdout.write(
-      `${r.score.toFixed(3)} | ${r.source}@${r.version} | ${(r.heading_path ?? []).join(" \u203A ")} | ${r.origin_url}
+      `${r.score.toFixed(3)} | ${r.product}@${r.version} | ${heading(r)} | ${r.source_url} | ${r.point_id}
 `
     );
   }
@@ -418,7 +559,7 @@ function setupCodex() {
 function hasSession() {
   if (process.env.GRIMOIRE_AUTH_TOKEN) return true;
   try {
-    return readRefreshToken() !== void 0;
+    return readMachineToken() !== void 0 || readSession() !== void 0;
   } catch {
     return false;
   }
@@ -518,7 +659,7 @@ var CONFIG_KEYS = {
     describe: `API origin without a path (default ${DEFAULT_API_BASE}; env GRIMOIRE_API_URL overrides)`,
     parse: (raw) => {
       if (!/^https?:\/\/[^/]+$/.test(raw)) {
-        throw new UsageError("api-url must be a bare origin, e.g. https://grimoire-api.monadeo.com");
+        throw new UsageError("api-url must be a bare origin, e.g. https://api.example.com");
       }
       return raw;
     }
@@ -527,22 +668,11 @@ var CONFIG_KEYS = {
     prop: "updateCheckHours",
     describe: "hours between CLI update checks (default 24, 0 disables)",
     parse: (raw) => intInRange("update-check-hours", raw, 0)
-  },
-  language: {
-    prop: "defaultLanguage",
-    describe: "default search language filter",
-    parse: (raw) => {
-      if (!raw) throw new UsageError("language must be non-empty");
-      return raw;
-    }
-  },
-  "max-response-tokens": {
-    prop: "maxResponseTokens",
-    describe: "search response token budget",
-    parse: (raw) => intInRange("max-response-tokens", raw, 1)
   }
 };
-var USAGE = "Usage: grimoire config [<key>] [<value>] [--unset]  (keys: " + Object.keys(CONFIG_KEYS).join(", ") + ")";
+var AUTH_TOKEN_KEY = "auth-token";
+var MACHINE_TOKEN_RE = /^mt_[A-Za-z0-9_-]{32,}$/;
+var USAGE = "Usage: grimoire config [<key>] [<value>] [--unset]  (keys: " + [...Object.keys(CONFIG_KEYS), AUTH_TOKEN_KEY].join(", ") + ")";
 function runConfig(args) {
   const [key, value] = args.positionals;
   if (key === void 0) {
@@ -554,6 +684,30 @@ function runConfig(args) {
       process.stdout.write(`${name} = ${current === void 0 ? "(unset)" : JSON.stringify(current)}  # ${spec2.describe}
 `);
     }
+    process.stdout.write(
+      `${AUTH_TOKEN_KEY} = ${readMachineToken() ? "(set)" : "(unset)"}  # machine token, stored 0600 (env GRIMOIRE_AUTH_TOKEN overrides)
+`
+    );
+    return EXIT.ok;
+  }
+  if (key === AUTH_TOKEN_KEY) {
+    if (args.bools.has("unset")) {
+      clearMachineToken();
+      process.stdout.write(`${AUTH_TOKEN_KEY} unset
+`);
+      return EXIT.ok;
+    }
+    if (value === void 0) {
+      process.stdout.write(`${readMachineToken() ? "(set)" : "(unset)"}
+`);
+      return EXIT.ok;
+    }
+    if (!MACHINE_TOKEN_RE.test(value)) {
+      throw new UsageError("auth-token must be a machine token starting with mt_");
+    }
+    storeMachineToken(value);
+    process.stdout.write(`${AUTH_TOKEN_KEY} set
+`);
     return EXIT.ok;
   }
   const spec = CONFIG_KEYS[key];
@@ -622,6 +776,33 @@ function runUpdate() {
   return result.status === 0 ? EXIT.ok : EXIT.apiError;
 }
 
+// src/commands/ingest.ts
+function submissionFromArgs(url, args) {
+  const usage = "Usage: grimoire ingest <url> --product <name> (--rolling | --fixed <version> | --npm <pkg> | --pypi <pkg> | --github <owner/repo>)";
+  const product = args.flags.product?.[0];
+  if (!product) throw new UsageError(usage);
+  const fixed = args.flags.fixed?.[0];
+  const npm = args.flags.npm?.[0];
+  const pypi = args.flags.pypi?.[0];
+  const github = args.flags.github?.[0];
+  const probes = [npm, pypi, github].filter(Boolean).length;
+  if (probes > 1) throw new UsageError("Pass only one of --npm, --pypi, --github");
+  const body = {
+    url,
+    product,
+    version_rule: { kind: "rolling" },
+    include_patterns: args.flags.include ?? [],
+    exclude_patterns: args.flags.exclude ?? []
+  };
+  if (args.bools.has("rolling")) return body;
+  if (fixed) return { ...body, version_rule: { kind: "fixed", value: fixed } };
+  if (npm) return { ...body, version_rule: { kind: "fixed" }, probe: { kind: "npm", package: npm } };
+  if (pypi) return { ...body, version_rule: { kind: "fixed" }, probe: { kind: "pypi", package: pypi } };
+  if (github) return { ...body, version_rule: { kind: "fixed" }, probe: { kind: "github", repo: github } };
+  throw new UsageError(`${usage}
+A version rule is mandatory: --rolling for unversioned docs, --fixed, or a release probe.`);
+}
+
 // src/updatecheck.ts
 import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
@@ -678,15 +859,21 @@ async function refreshUpdateState(current, configuredHours) {
 }
 
 // src/index.ts
-function openBrowser(url) {
-  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
-  try {
-    execFileSync(cmd, [url], { stdio: "ignore" });
-  } catch {
-    process.stdout.write(`Open this URL to log in:
-${url}
+function loginOpener(launchBrowser) {
+  return (url) => {
+    process.stdout.write(`${url}
 `);
-  }
+    if (!launchBrowser) {
+      process.stderr.write("Open the URL above in a browser to log in; waiting for the callback\u2026\n");
+      return;
+    }
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+      execFileSync(cmd, [url], { stdio: "ignore" });
+    } catch {
+      process.stderr.write("Could not open a browser; open the URL above manually.\n");
+    }
+  };
 }
 function parseSourceFlags(values) {
   return (values ?? []).map((v) => {
@@ -694,33 +881,39 @@ function parseSourceFlags(values) {
     return version ? { source, version } : { source };
   });
 }
-var VERSION = true ? "0.3.6" : "dev";
+function toSelectors(pins) {
+  return pins.map((p) => ({ product: p.source, ...p.version ? { version: p.version } : {} }));
+}
+var VERSION = true ? "0.4.0" : "dev";
 var HELP = `grimoire ${VERSION} \u2014 documentation retrieval for AI agents
 
-  grimoire login | logout | whoami
+  grimoire login [--no-launch-browser] | logout | whoami
   grimoire setup <claude-code|cursor|windsurf|codex>
   grimoire init
-  grimoire search "<query>" [-s nextjs@15 -s react] [--lang en] [--top-k 8] [--json|--compact]
+  grimoire search "<query>" [-s nextjs@15 -s react] [--json|--compact] [--debug]
   grimoire sources [--q <kw>] [--names|--json]
-  grimoire versions <source> [--json]
+  grimoire versions <product> [--json]
   grimoire config [<key>] [<value>] [--unset]
   grimoire update
-  grimoire doc <chunk_id> [--window 2]
-  grimoire report <chunk_id> --verdict helpful|incorrect|outdated [--note "..."]
-  grimoire ingest <url> [--version 15.2] [--private] [--webhook URL] [--watch]
+  grimoire doc <point_id> [--window 2] [--json]
+  grimoire report <point_id> --verdict helpful|incorrect|outdated [--note "..."]
+  grimoire ingest <url> --product <name> (--rolling | --fixed <version> | --npm <pkg> | --pypi <pkg> | --github <owner/repo>)
+                        [--include <pattern>]... [--exclude <pattern>]... [--watch]
   grimoire jobs <job_id> [--watch]
+  grimoire staff queue [--json] | approve <job_id> | reject <job_id> --reason "..."
+  grimoire staff users [--json] | grant <subject> --name "..." | revoke <subject>
   grimoire mcp [--http]
   grimoire help | --help | -h
   grimoire version | --version | -v
 
   env: GRIMOIRE_AUTH_TOKEN \u2014 machine token (CI, instead of login)
-       GRIMOIRE_API_URL   \u2014 API origin without a path, e.g. https://grimoire-api-qa.monadeo.com
+       GRIMOIRE_API_URL   \u2014 API origin without a path
 `;
 var COMMAND_FLAGS = {
   version: [],
   "--version": [],
   "-v": [],
-  login: [],
+  login: ["no-launch-browser"],
   logout: [],
   setup: [],
   init: [],
@@ -731,14 +924,23 @@ var COMMAND_FLAGS = {
   mcp: ["http"],
   config: ["unset"],
   update: [],
-  search: ["source", "lang", "top-k", "json", "compact"],
+  search: ["source", "json", "compact", "debug"],
   sources: ["q", "names", "json"],
   versions: ["json"],
-  doc: ["window"],
+  doc: ["window", "json"],
   report: ["verdict", "note"],
-  ingest: ["version", "private", "webhook", "watch"],
-  jobs: ["watch"]
+  ingest: ["product", "rolling", "fixed", "npm", "pypi", "github", "include", "exclude", "watch"],
+  jobs: ["watch"],
+  staff: ["reason", "name", "json"]
 };
+function describeError(err) {
+  const detail = typeof err.body === "string" ? err.body : err.body !== void 0 && err.body !== null ? JSON.stringify(err.body) : "";
+  return `error: ${err.code}${detail ? ` \u2014 ${detail}` : ""}`;
+}
+function describeJob(job) {
+  const extra = [job.reason ? `reason: ${job.reason}` : "", job.source_id ? `source: ${job.source_id}` : ""].filter(Boolean).join("  ");
+  return `${job.state}${extra ? `  ${extra}` : ""}`;
+}
 async function main(argv) {
   const [command, ...rest] = argv;
   const args = parseArgs(rest, { "-s": "source", "-q": "q" }, command !== void 0 ? COMMAND_FLAGS[command] : []);
@@ -751,12 +953,14 @@ async function main(argv) {
 `);
       return EXIT.ok;
     case "login": {
-      await browserLogin(loadGlobalConfig().apiBaseUrl, openBrowser);
+      const launch = !args.bools.has("no-launch-browser");
+      process.stderr.write(launch ? "Opening your browser to log in\u2026\n" : "Login URL:\n");
+      await browserLogin(loadGlobalConfig().apiBaseUrl, loginOpener(launch));
       process.stdout.write("Logged in.\n");
       return EXIT.ok;
     }
     case "logout":
-      clearRefreshToken();
+      clearSession();
       process.stdout.write("Logged out.\n");
       return EXIT.ok;
     case "setup":
@@ -781,29 +985,22 @@ async function main(argv) {
   try {
     switch (command) {
       case "whoami": {
-        if (process.env.GRIMOIRE_AUTH_TOKEN) {
-          process.stdout.write("machine token configured (GRIMOIRE_AUTH_TOKEN)\n");
-          return EXIT.ok;
-        }
-        if (!readRefreshToken()) {
+        const via = process.env.GRIMOIRE_AUTH_TOKEN ? "GRIMOIRE_AUTH_TOKEN" : readMachineToken() ? "grimoire config auth-token" : readSession() ? "browser login" : void 0;
+        if (!via) {
           process.stderr.write("not logged in \u2014 run `grimoire login`\n");
           return EXIT.authRequired;
         }
-        try {
-          await client.refreshSession();
-          process.stdout.write("logged in (browser session)\n");
-          return EXIT.ok;
-        } catch (err) {
-          const reason = err instanceof ApiError ? err.code : err.message;
-          process.stderr.write(`not logged in (${reason}) \u2014 run \`grimoire login\`
-`);
-          return EXIT.authRequired;
-        }
+        const me = await client.me();
+        process.stdout.write(
+          `${me.kind} ${me.subject}${me.is_staff ? "  staff" : ""}  quota ${me.quota_per_day}/day  via ${via}
+`
+        );
+        return EXIT.ok;
       }
       case "search": {
         const query = args.positionals[0];
         if (!query) {
-          process.stderr.write('Usage: grimoire search "<query>" -s <source>\n');
+          process.stderr.write('Usage: grimoire search "<query>" -s <product>[@version]\n');
           return EXIT.apiError;
         }
         const explicit = parseSourceFlags(args.flags.source);
@@ -811,99 +1008,73 @@ async function main(argv) {
         if (sources.length === 0) {
           const initHelps = existsSync6(join6(process.cwd(), "package.json")) || existsSync6(join6(process.cwd(), "requirements.txt"));
           process.stderr.write(
-            'No sources selected. List what is indexed:\n  grimoire sources\nthen scope the search:\n  grimoire search "<query>" -s <source>[@version]\n' + (initHelps ? "or pin this project's sources from its dependencies:\n  grimoire init\n" : "")
+            'No sources selected. List what is indexed:\n  grimoire sources\nthen scope the search:\n  grimoire search "<query>" -s <product>[@version]\n' + (initHelps ? "or pin this project's sources from its dependencies:\n  grimoire init\n" : "")
           );
           return EXIT.apiError;
         }
-        const res = await client.search({
-          query,
-          sources,
-          language: args.flags.lang?.[0],
-          top_k: intFlag(args, "top-k")
-        });
+        const res = await client.search({ query, sources: toSelectors(sources), debug: args.bools.has("debug") });
         if (json) process.stdout.write(JSON.stringify(res, null, 2) + "\n");
-        else if (args.bools.has("compact")) printCompact(res.results, res.confidence, res.rerank_status);
-        else printResults(res.results, res.confidence, res.rerank_status);
+        else if (args.bools.has("compact")) printCompact(res);
+        else printResults(res);
         return EXIT.ok;
       }
       case "sources": {
-        const res = await client.listSources(args.flags.q?.[0]);
-        const sources = res.sources ?? [];
+        const needle = args.flags.q?.[0]?.toLowerCase();
+        const sources = (await client.listSources()).filter(
+          (s) => !needle || s.product.toLowerCase().includes(needle) || s.base_url.toLowerCase().includes(needle)
+        );
         if (json) {
           process.stdout.write(JSON.stringify(sources, null, 2) + "\n");
         } else if (args.bools.has("names")) {
-          for (const s of sources) process.stdout.write(`${s.source_id}
+          for (const s of sources) process.stdout.write(`${s.product}
 `);
         } else {
           for (const s of sources) {
-            const latest = s.latest_semver ?? s.latest_version ?? "-";
-            const vis = s.visibility === "private" ? " (private)" : "";
-            const meta = [
-              s.latest_chunks != null ? `${s.latest_chunks} chunks` : "",
-              s.latest_pages != null ? `${s.latest_pages} pages` : "",
-              s.latest_crawled_at ? `crawled ${s.latest_crawled_at.slice(0, 10)}` : ""
-            ].filter(Boolean).join(" \xB7 ");
-            process.stdout.write(
-              [`${s.source_id}@${latest}${vis}`, meta, s.origin_url ?? ""].filter(Boolean).join("  ") + "\n"
-            );
+            const versions = s.versions.length > 0 ? s.versions.join(", ") : "(not indexed yet)";
+            process.stdout.write(`${s.product}  ${versions}  ${s.base_url}
+`);
           }
         }
         return EXIT.ok;
       }
       case "versions": {
-        const source = requirePositional(args, 0, "Usage: grimoire versions <source> [--json]");
-        const res = await client.listVersions(source);
-        const versions = res.versions ?? [];
+        const product = requirePositional(args, 0, "Usage: grimoire versions <product> [--json]");
+        const res = await client.listVersions(product);
         if (json) {
-          process.stdout.write(JSON.stringify(versions, null, 2) + "\n");
+          process.stdout.write(JSON.stringify(res, null, 2) + "\n");
           return EXIT.ok;
         }
-        const available = versions.filter((v) => v.status === "active");
-        if (available.length === 0) {
-          process.stdout.write(`no active versions for ${source}
+        for (const v of res.versions) {
+          process.stdout.write(`${v.version}${v.version === res.latest ? "  latest" : ""}  ${v.chunk_count} chunks
 `);
-          return EXIT.ok;
-        }
-        for (const v of available) {
-          const label = v.semver ?? v.version_id;
-          const parts = [
-            label,
-            v.is_latest ? "latest" : "",
-            `${v.chunk_count ?? 0} chunks`,
-            `crawled ${(v.ingested_at ?? "").slice(0, 10)}`,
-            v.semver ? `(${v.version_id})` : ""
-          ].filter(Boolean);
-          process.stdout.write(parts.join("  ") + "\n");
         }
         return EXIT.ok;
       }
       case "doc": {
-        const chunkId = requirePositional(args, 0, "Usage: grimoire doc <chunk_id> [--window 2]");
+        const pointId = requirePositional(args, 0, "Usage: grimoire doc <point_id> [--window 2] [--json]");
         const window = intFlag(args, "window", { min: 0, max: 5 }) ?? 2;
-        const res = await client.getContext(chunkId, window);
-        process.stdout.write(JSON.stringify(res.chunks ?? [], null, 2) + "\n");
+        const res = await client.getDoc(pointId, window);
+        if (json) {
+          process.stdout.write(JSON.stringify(res, null, 2) + "\n");
+          return EXIT.ok;
+        }
+        process.stderr.write(`${res.product}@${res.version}  ${res.heading_path.join(" \u203A ")}
+${res.source_url}
+`);
+        process.stdout.write(res.text + "\n");
         return EXIT.ok;
       }
       case "report": {
-        const usage = 'Usage: grimoire report <chunk_id> --verdict helpful|incorrect|outdated [--note "..."]';
-        const chunkId = requirePositional(args, 0, usage);
+        const usage = 'Usage: grimoire report <point_id> --verdict helpful|incorrect|outdated [--note "..."]';
+        const pointId = requirePositional(args, 0, usage);
         const verdict = requireFlagOneOf(args, "verdict", ["helpful", "incorrect", "outdated"], usage);
-        await client.reportResult(chunkId, verdict, args.flags.note?.[0]);
+        await client.reportResult(pointId, verdict, args.flags.note?.[0]);
         process.stdout.write("Reported.\n");
         return EXIT.ok;
       }
       case "ingest": {
-        const url = requirePositional(
-          args,
-          0,
-          "Usage: grimoire ingest <url> [--version 15.2] [--private] [--webhook URL] [--watch]"
-        );
-        const res = await client.submitSource({
-          url,
-          version: args.flags.version?.[0],
-          visibility: args.bools.has("private") ? "private" : "public",
-          webhook_url: args.flags.webhook?.[0]
-        });
+        const url = requirePositional(args, 0, "Usage: grimoire ingest <url> --product <name> --rolling|--fixed|--npm|--pypi|--github");
+        const res = await client.submitSource(submissionFromArgs(url, args));
         process.stdout.write(`Job: ${res.job_id}
 `);
         if (args.bools.has("watch")) return watchJob(client, res.job_id);
@@ -913,6 +1084,54 @@ async function main(argv) {
         const jobId = requirePositional(args, 0, "Usage: grimoire jobs <job_id> [--watch]");
         return args.bools.has("watch") ? watchJob(client, jobId) : printJob(client, jobId);
       }
+      case "staff": {
+        const usage = 'Usage: grimoire staff queue [--json] | approve <job_id> | reject <job_id> --reason "..." | users [--json] | grant <subject> --name "..." | revoke <subject>';
+        const [action, jobId] = args.positionals;
+        if (action === "users") {
+          const users = await client.listUsers();
+          if (json) process.stdout.write(JSON.stringify(users, null, 2) + "\n");
+          else for (const u of users) process.stdout.write(`${u.subject}  ${u.status}  ${u.name}  by ${u.granted_by}
+`);
+          return EXIT.ok;
+        }
+        if (action === "grant") {
+          const name = args.flags.name?.[0];
+          if (!jobId || !name) throw new UsageError(usage);
+          const granted = await client.grantUser(jobId, name);
+          process.stdout.write(`${granted.subject}  ${granted.status}  ${granted.name}
+`);
+          return EXIT.ok;
+        }
+        if (action === "revoke") {
+          if (!jobId) throw new UsageError(usage);
+          const revoked = await client.revokeUser(jobId);
+          process.stdout.write(`${revoked.subject}  ${revoked.status}
+`);
+          return EXIT.ok;
+        }
+        if (action === "queue") {
+          const queue = await client.reviewQueue();
+          if (json) process.stdout.write(JSON.stringify(queue, null, 2) + "\n");
+          else if (queue.length === 0) process.stdout.write("review queue is empty\n");
+          else for (const job of queue) process.stdout.write(`${job.id}  ${describeJob(job)}
+`);
+          return EXIT.ok;
+        }
+        if (!jobId) throw new UsageError(usage);
+        if (action === "approve") {
+          process.stdout.write(`${describeJob(await client.approveJob(jobId))}
+`);
+          return EXIT.ok;
+        }
+        if (action === "reject") {
+          const reason = args.flags.reason?.[0];
+          if (!reason) throw new UsageError(usage);
+          process.stdout.write(`${describeJob(await client.rejectJob(jobId, reason))}
+`);
+          return EXIT.ok;
+        }
+        throw new UsageError(usage);
+      }
       default:
         process.stderr.write(`Unknown command: ${command}
 ${HELP}`);
@@ -920,14 +1139,10 @@ ${HELP}`);
     }
   } catch (err) {
     if (err instanceof ApiError) {
-      const body = typeof err.body === "object" && err.body !== null ? err.body : {};
-      process.stderr.write(`error: ${err.code}${body.message ? ` \u2014 ${body.message}` : ""}
-`);
-      if (body.available?.length) process.stderr.write(`available: ${body.available.join(", ")}
-`);
-      if (body.did_you_mean?.length) process.stderr.write(`did you mean: ${body.did_you_mean.join(", ")}
+      process.stderr.write(`${describeError(err)}
 `);
       if (err.status === 401) return EXIT.authRequired;
+      if (err.status === 403) return EXIT.authRequired;
       if (err.status === 429) return EXIT.quota;
       if (err.status === 404) return EXIT.notFound;
       return EXIT.apiError;
@@ -935,14 +1150,13 @@ ${HELP}`);
     throw err;
   }
 }
-var TERMINAL_STATUSES = ["complete", "failed", "rejected"];
-var FAILED_STATUSES = ["failed", "rejected"];
+var TERMINAL_STATES = ["accepted", "done", "rejected", "failed", "pending_review"];
+var FAILED_STATES = ["rejected", "failed"];
 async function printJob(client, jobId) {
   const job = await client.getJob(jobId);
-  const status = job.status ?? "unknown";
-  process.stdout.write(`${status} ${JSON.stringify(job.counters ?? {})}
+  process.stdout.write(`${describeJob(job)}
 `);
-  return FAILED_STATUSES.includes(status) ? EXIT.apiError : EXIT.ok;
+  return FAILED_STATES.includes(job.state) ? EXIT.apiError : EXIT.ok;
 }
 var WATCH_POLL_MS = 5e3;
 var WATCH_BACKOFF_CAP_MS = 3e4;
@@ -956,11 +1170,13 @@ async function watchJob(client, jobId) {
   while (Date.now() < deadline) {
     try {
       const job = await client.getJob(jobId);
-      const status = job.status ?? "unknown";
-      process.stdout.write(`${status} ${JSON.stringify(job.counters ?? {})}
+      process.stdout.write(`${describeJob(job)}
 `);
-      if (TERMINAL_STATUSES.includes(status)) {
-        return FAILED_STATUSES.includes(status) ? EXIT.apiError : EXIT.ok;
+      if (TERMINAL_STATES.includes(job.state)) {
+        if (job.state === "pending_review") {
+          process.stderr.write("Parked for staff review: grimoire staff queue\n");
+        }
+        return FAILED_STATES.includes(job.state) ? EXIT.apiError : EXIT.ok;
       }
       backoff = WATCH_POLL_MS;
       await sleep(WATCH_POLL_MS);