@zleap-ai/sag-cli 0.2.1 → 0.4.0

package/dist/cli.js

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { confirm, password, select } from "@inquirer/prompts";
+import { confirm, input, select } from "@inquirer/prompts";
 
 // package.json
 var package_default = {
   name: "@zleap-ai/sag-cli",
-  version: "0.2.1",
+  version: "0.4.0",
   description: "Command-line client and diagnostics for SAG knowledge bases",
   type: "module",
   bin: {
@@ -16,7 +16,8 @@ var package_default = {
     "dist",
     "README.md",
     "README.en.md",
-    "LICENSE"
+    "LICENSE",
+    "skill"
   ],
   scripts: {
     build: "tsup",
@@ -176,7 +177,7 @@ var claudeEntrySchema = z.object({
 function invalidSpec() {
   return new CliError(
     "INVALID_ARGUMENT",
-    "Claude Code v0.2 supports Docker stdio MCP connections only",
+    "The Claude Code adapter supports Docker stdio MCP connections only",
     {
       exitCode: exitCodes.invalidArgument
     }
@@ -205,6 +206,12 @@ var ClaudeCodeAdapter = class {
   }
   runner;
   id = "claude-code";
+  capabilities = {
+    transports: ["stdio"],
+    scopes: ["user"],
+    structuredRead: true,
+    projectApproval: false
+  };
   readConfig;
   async detect() {
     try {
@@ -293,7 +300,7 @@ var CODEX_STATUS_FIELDS = /* @__PURE__ */ new Set(["name", "disabled_reason", "a
 function invalidSpec2() {
   return new CliError(
     "INVALID_ARGUMENT",
-    "Codex v0.2 supports Docker stdio MCP connections only",
+    "The Codex adapter supports Docker stdio MCP connections only",
     {
       exitCode: exitCodes.invalidArgument
     }
@@ -317,6 +324,12 @@ var CodexAdapter = class {
   }
   runner;
   id = "codex";
+  capabilities = {
+    transports: ["stdio"],
+    scopes: ["user"],
+    structuredRead: true,
+    projectApproval: false
+  };
   async detect() {
     try {
       const result = await this.runner.run({
@@ -533,9 +546,9 @@ var ManagedConnectionStore = class {
       await this.#saveUnlocked(state);
     });
   }
-  async list(input) {
+  async list(input2) {
     return Object.values((await this.load()).connections).filter(
-      (connection) => (!input?.agent || connection.agent === input.agent) && (!input?.scope || connection.scope === input.scope)
+      (connection) => (!input2?.agent || connection.agent === input2.agent) && (!input2?.scope || connection.scope === input2.scope)
     );
   }
 };
@@ -557,12 +570,12 @@ function validateProfileName(name) {
   }
   return name;
 }
-function normalizeOrigin(input) {
+function normalizeOrigin(input2) {
   let url;
   try {
-    url = new URL(input);
+    url = new URL(input2);
   } catch (cause) {
-    throw new CliError("INVALID_ARGUMENT", `Invalid SAG URL: ${input}`, {
+    throw new CliError("INVALID_ARGUMENT", `Invalid SAG URL: ${input2}`, {
       exitCode: exitCodes.invalidArgument,
       cause,
       hint: "Use an absolute HTTP or HTTPS URL such as http://localhost:8000."
@@ -1089,16 +1102,6 @@ var McpVerifier = class {
   }
   cliVersion;
   async verify(spec, options) {
-    if (spec.transport !== "stdio") {
-      throw new CliError(
-        "INVALID_ARGUMENT",
-        "HTTP MCP is not supported in SAG CLI v0.2",
-        {
-          exitCode: exitCodes.invalidArgument,
-          hint: "Use a local Docker stdio connection."
-        }
-      );
-    }
     const client = new Client(
       {
         name: "@zleap-ai/sag-cli",
@@ -1190,12 +1193,12 @@ var McpVerifier = class {
 // src/process/runner.ts
 import { spawn } from "child_process";
 var NodeProcessRunner = class {
-  async run(input) {
+  async run(input2) {
     return new Promise((resolve, reject) => {
-      const child = spawn(input.command, input.args, {
+      const child = spawn(input2.command, input2.args, {
         shell: false,
-        env: input.env ?? process.env,
-        stdio: [input.stdin === "pipe" ? "pipe" : "ignore", "pipe", "pipe"]
+        env: input2.env ?? process.env,
+        stdio: [input2.stdin === "pipe" ? "pipe" : "ignore", "pipe", "pipe"]
       });
       const childStdout = child.stdout;
       const childStderr = child.stderr;
@@ -1209,7 +1212,7 @@ var NodeProcessRunner = class {
         forceKill = setTimeout(() => {
           child.kill("SIGKILL");
         }, 250);
-      }, input.timeoutMs);
+      }, input2.timeoutMs);
       childStdout?.setEncoding("utf8");
       childStderr?.setEncoding("utf8");
       childStdout?.on("data", (chunk) => {
@@ -1222,10 +1225,10 @@ var NodeProcessRunner = class {
         clearTimeout(timeout);
         if (forceKill) clearTimeout(forceKill);
         reject(
-          new CliError("DEPENDENCY_MISSING", `Unable to start ${input.command}`, {
+          new CliError("DEPENDENCY_MISSING", `Unable to start ${input2.command}`, {
             exitCode: exitCodes.dependencyMissing,
             cause,
-            hint: `Install ${input.command} and ensure it is available on PATH.`
+            hint: `Install ${input2.command} and ensure it is available on PATH.`
           })
         );
       });
@@ -1234,9 +1237,9 @@ var NodeProcessRunner = class {
         if (forceKill) clearTimeout(forceKill);
         if (timedOut) {
           reject(
-            new CliError("DEPENDENCY_MISSING", `${input.command} timed out`, {
+            new CliError("DEPENDENCY_MISSING", `${input2.command} timed out`, {
               exitCode: exitCodes.dependencyMissing,
-              hint: `Check that ${input.command} is responsive and try again.`
+              hint: `Check that ${input2.command} is responsive and try again.`
             })
           );
           return;
@@ -1273,6 +1276,10 @@ var userSchema = z6.object({
   name: z6.string(),
   created_at: dateTime.optional()
 }).passthrough();
+var loginResponseSchema = z6.object({
+  access_token: z6.string().min(1),
+  user: userSchema
+}).passthrough();
 var sourceSchema = z6.object({
   id: z6.string().min(1),
   name: z6.string(),
@@ -1354,6 +1361,43 @@ var mcpDescriptorSchema = z6.object({
     headers: z6.record(z6.string(), z6.string())
   }).passthrough()
 }).passthrough();
+var outlineItemSchema = z6.object({
+  rank: z6.number().int(),
+  heading: z6.string(),
+  chunk_id: z6.string()
+}).passthrough();
+var outlineSchema = z6.object({
+  document_id: z6.string(),
+  filename: z6.string(),
+  outline: z6.array(outlineItemSchema)
+}).passthrough();
+var grepMatchSchema = z6.object({
+  chunk_id: z6.string(),
+  heading: z6.string(),
+  snippet: z6.string()
+}).passthrough();
+var grepResponseSchema = z6.object({
+  pattern: z6.string(),
+  matches: z6.array(grepMatchSchema),
+  count: z6.number().int().nonnegative()
+}).passthrough();
+var readResponseSchema = z6.object({
+  document_id: z6.string(),
+  filename: z6.string(),
+  total_lines: z6.number().int().nonnegative(),
+  offset: z6.number().int().positive(),
+  limit: z6.number().int().positive(),
+  lines: z6.array(z6.string())
+}).passthrough();
+var entityContextSchema = z6.object({
+  entity_id: z6.string(),
+  name: z6.string(),
+  type: z6.string(),
+  description: z6.string(),
+  context: z6.string(),
+  source_id: z6.string(),
+  source_name: z6.string()
+}).passthrough();
 
 // src/api/client.ts
 var SagClient = class {
@@ -1385,6 +1429,14 @@ var SagClient = class {
   me() {
     return this.#request("/api/v1/auth/me", userSchema);
   }
+  async login(name) {
+    const response = await this.#request("/api/v1/auth/login", loginResponseSchema, {
+      authenticated: false,
+      method: "POST",
+      body: { name }
+    });
+    return { accessToken: response.access_token, user: response.user };
+  }
   mcpDescriptor() {
     return this.#request("/api/v1/system/mcp", mcpDescriptorSchema);
   }
@@ -1409,12 +1461,48 @@ var SagClient = class {
       documentSchema
     );
   }
-  search(input) {
+  search(input2) {
     return this.#request("/api/v1/search", searchResponseSchema, {
       method: "POST",
-      body: input
+      body: input2
     });
   }
+  outline(sourceId, documentId) {
+    const params = new URLSearchParams({ document_id: documentId });
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/outline?${params}`,
+      outlineSchema
+    );
+  }
+  grep(sourceId, pattern, limit) {
+    const params = new URLSearchParams({ pattern });
+    if (limit !== void 0) {
+      params.set("limit", String(limit));
+    }
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/grep?${params}`,
+      grepResponseSchema
+    );
+  }
+  readDocument(sourceId, documentId, offset, limit) {
+    const params = new URLSearchParams();
+    if (offset !== void 0) {
+      params.set("offset", String(offset));
+    }
+    if (limit !== void 0) {
+      params.set("limit", String(limit));
+    }
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/documents/${encodeURIComponent(documentId)}/read?${params}`,
+      readResponseSchema
+    );
+  }
+  getEntityContext(sourceId, name) {
+    return this.#request(
+      `/api/v1/sources/${encodeURIComponent(sourceId)}/entities/${encodeURIComponent(name)}/context`,
+      entityContextSchema
+    );
+  }
   async #request(path5, schema, options = {}) {
     const authenticated = options.authenticated ?? true;
     if (authenticated && !this.#token) {
@@ -1529,81 +1617,98 @@ function hostFailure3(message, cause, hint) {
     hint: hint ?? "Inspect the Agent MCP configuration and run the command again."
   });
 }
-function determinePlan(input) {
+function determinePlan(input2) {
   let action;
-  if (!input.hostFingerprint || !input.hostSpecFingerprint) {
-    if (input.managed) {
+  if (!input2.hostFingerprint || !input2.hostSpecFingerprint) {
+    if (input2.managed) {
       throw conflict("Managed state exists but the Agent MCP entry is missing");
     }
     action = "create";
-  } else if (!input.managed) {
+  } else if (!input2.managed) {
     throw conflict("The Agent MCP name is already owned by the user");
-  } else if (input.managed.fingerprint !== input.hostFingerprint) {
+  } else if (input2.managed.fingerprint !== input2.hostFingerprint) {
     throw conflict("The managed Agent MCP entry was changed outside SAG CLI");
-  } else if (input.hostSpecFingerprint === input.desiredFingerprint) {
+  } else if (input2.hostSpecFingerprint === input2.desiredFingerprint) {
     action = "unchanged";
   } else {
     action = "update";
   }
   return {
     action,
-    agent: input.agent,
-    serverName: input.serverName,
-    scope: input.scope,
+    agent: input2.agent,
+    serverName: input2.serverName,
+    scope: input2.scope,
     provider: "docker-stdio",
-    target: input.target.name,
-    sourceId: input.sourceId ?? null,
-    ...input.hostSpecFingerprint ? { currentFingerprint: input.hostSpecFingerprint } : {},
-    desiredFingerprint: input.desiredFingerprint
+    target: input2.target.name,
+    sourceId: input2.sourceId ?? null,
+    ...input2.hostSpecFingerprint ? { currentFingerprint: input2.hostSpecFingerprint } : {},
+    desiredFingerprint: input2.desiredFingerprint
   };
 }
-function managedConnection(input, resolved, fingerprint, existing) {
+function managedConnection(input2, resolved, fingerprint, existing) {
   return {
-    agent: input.agent,
+    agent: input2.agent,
     provider: "docker-stdio",
-    profile: input.profile,
-    serverName: input.serverName,
+    profile: input2.profile,
+    serverName: input2.serverName,
     docker: {
       ...resolved.target.composeProject ? { composeProject: resolved.target.composeProject } : {},
       ...resolved.target.composeService ? { composeService: resolved.target.composeService } : {},
       containerName: resolved.target.name
     },
-    sourceId: input.sourceId ?? null,
-    scope: input.scope,
+    sourceId: input2.sourceId ?? null,
+    scope: input2.scope,
     fingerprint,
-    createdAt: existing?.createdAt ?? input.now().toISOString()
+    createdAt: existing?.createdAt ?? input2.now().toISOString()
   };
 }
-async function rollbackHost(input) {
-  if (input.previousSpec) {
+async function rollbackHost(input2) {
+  if (input2.previousSpec) {
     try {
-      await input.adapter.remove(input.serverName, input.scope);
+      await input2.adapter.remove(input2.serverName, input2.scope);
     } catch {
     }
-    await input.adapter.add(input.serverName, input.scope, input.previousSpec);
-    const restored = await input.adapter.read(input.serverName, input.scope);
-    if (!restored || restored.fingerprint !== (input.previousFingerprint ?? fingerprintConnection(input.previousSpec))) {
+    await input2.adapter.add(input2.serverName, input2.scope, input2.previousSpec);
+    const restored = await input2.adapter.read(input2.serverName, input2.scope);
+    if (!restored || restored.fingerprint !== (input2.previousFingerprint ?? fingerprintConnection(input2.previousSpec))) {
       throw new Error("Previous Agent MCP entry was not restored");
     }
     return;
   }
-  await input.adapter.remove(input.serverName, input.scope);
+  await input2.adapter.remove(input2.serverName, input2.scope);
 }
-async function connectAgent(input) {
-  validateServerName(input.serverName);
-  const resolved = await input.resolveConnection();
-  await input.verifier.verify(resolved.spec, { timeoutMs: input.timeoutMs });
-  await input.adapter.detect();
-  const host = await input.adapter.read(input.serverName, input.scope);
-  const key = connectionKey(input.agent, input.scope, input.serverName);
-  const managed = await input.state.get(key);
+async function connectAgent(input2) {
+  validateServerName(input2.serverName);
+  const resolved = await input2.resolveConnection();
+  if (!input2.adapter.capabilities.transports.includes(resolved.spec.transport)) {
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      `${input2.agent} adapter does not support ${resolved.spec.transport} MCP connections`,
+      {
+        exitCode: exitCodes.invalidArgument,
+        hint: "Choose a provider supported by the installed Agent adapter."
+      }
+    );
+  }
+  if (!input2.adapter.capabilities.scopes.includes(input2.scope)) {
+    throw new CliError(
+      "INVALID_ARGUMENT",
+      `${input2.agent} adapter does not support ${input2.scope} scope`,
+      { exitCode: exitCodes.invalidArgument }
+    );
+  }
+  await input2.verifier.verify(resolved.spec, { timeoutMs: input2.timeoutMs });
+  await input2.adapter.detect();
+  const host = await input2.adapter.read(input2.serverName, input2.scope);
+  const key = connectionKey(input2.agent, input2.scope, input2.serverName);
+  const managed = await input2.state.get(key);
   const desiredFingerprint = fingerprintConnection(resolved.spec);
   const plan = determinePlan({
-    agent: input.agent,
-    serverName: input.serverName,
-    scope: input.scope,
+    agent: input2.agent,
+    serverName: input2.serverName,
+    scope: input2.scope,
     target: resolved.target,
-    ...input.sourceId ? { sourceId: input.sourceId } : {},
+    ...input2.sourceId ? { sourceId: input2.sourceId } : {},
     desiredFingerprint,
     ...host ? { hostFingerprint: host.fingerprint } : {},
     ...host ? { hostSpecFingerprint: fingerprintConnection(host.spec) } : {},
@@ -1611,9 +1716,9 @@ async function connectAgent(input) {
   });
   if (plan.action === "unchanged") {
     return {
-      agent: input.agent,
-      serverName: input.serverName,
-      scope: input.scope,
+      agent: input2.agent,
+      serverName: input2.serverName,
+      scope: input2.scope,
       action: "unchanged",
       changed: false,
       verified: true,
@@ -1621,11 +1726,11 @@ async function connectAgent(input) {
       plan
     };
   }
-  if (input.dryRun) {
+  if (input2.dryRun) {
     return {
-      agent: input.agent,
-      serverName: input.serverName,
-      scope: input.scope,
+      agent: input2.agent,
+      serverName: input2.serverName,
+      scope: input2.scope,
       action: plan.action,
       changed: false,
       verified: true,
@@ -1633,13 +1738,13 @@ async function connectAgent(input) {
       plan
     };
   }
-  if (!input.yes && !await input.confirm(
-    `${plan.action === "create" ? "Add" : "Update"} ${input.serverName} in ${input.agent}?`
+  if (!input2.yes && !await input2.confirm(
+    `${plan.action === "create" ? "Add" : "Update"} ${input2.serverName} in ${input2.agent}?`
   )) {
     return {
-      agent: input.agent,
-      serverName: input.serverName,
-      scope: input.scope,
+      agent: input2.agent,
+      serverName: input2.serverName,
+      scope: input2.scope,
       action: "cancelled",
       changed: false,
       verified: true,
@@ -1649,23 +1754,23 @@ async function connectAgent(input) {
   }
   try {
     if (plan.action === "update") {
-      await input.adapter.remove(input.serverName, input.scope);
+      await input2.adapter.remove(input2.serverName, input2.scope);
     }
-    await input.adapter.add(input.serverName, input.scope, resolved.spec);
-    const readBack = await input.adapter.read(input.serverName, input.scope);
+    await input2.adapter.add(input2.serverName, input2.scope, resolved.spec);
+    const readBack = await input2.adapter.read(input2.serverName, input2.scope);
     if (!readBack || fingerprintConnection(readBack.spec) !== desiredFingerprint) {
       throw hostFailure3("Agent MCP read-back did not match the requested connection");
     }
-    await input.verifier.verify(readBack.spec, { timeoutMs: input.timeoutMs });
-    await input.state.set(
-      managedConnection(input, resolved, readBack.fingerprint, managed)
+    await input2.verifier.verify(readBack.spec, { timeoutMs: input2.timeoutMs });
+    await input2.state.set(
+      managedConnection(input2, resolved, readBack.fingerprint, managed)
     );
   } catch (cause) {
     try {
       await rollbackHost({
-        adapter: input.adapter,
-        serverName: input.serverName,
-        scope: input.scope,
+        adapter: input2.adapter,
+        serverName: input2.serverName,
+        scope: input2.scope,
         ...host ? { previousSpec: host.spec } : {},
         ...host ? { previousFingerprint: host.fingerprint } : {}
       });
@@ -1673,7 +1778,7 @@ async function connectAgent(input) {
       throw hostFailure3(
         "Agent MCP configuration failed and rollback also failed",
         cause,
-        `Inspect the ${input.agent} MCP entry \`${input.serverName}\` before retrying.`
+        `Inspect the ${input2.agent} MCP entry \`${input2.serverName}\` before retrying.`
       );
     }
     throw hostFailure3(
@@ -1682,9 +1787,9 @@ async function connectAgent(input) {
     );
   }
   return {
-    agent: input.agent,
-    serverName: input.serverName,
-    scope: input.scope,
+    agent: input2.agent,
+    serverName: input2.serverName,
+    scope: input2.scope,
     action: plan.action,
     changed: true,
     verified: true,
@@ -1692,15 +1797,15 @@ async function connectAgent(input) {
     plan
   };
 }
-async function disconnectAgent(input) {
-  validateServerName(input.serverName);
-  await input.adapter.detect();
-  const key = connectionKey(input.agent, input.scope, input.serverName);
-  const managed = await input.state.get(key);
+async function disconnectAgent(input2) {
+  validateServerName(input2.serverName);
+  await input2.adapter.detect();
+  const key = connectionKey(input2.agent, input2.scope, input2.serverName);
+  const managed = await input2.state.get(key);
   if (!managed) {
     throw conflict("The Agent MCP entry is not managed by SAG CLI");
   }
-  const host = await input.adapter.read(input.serverName, input.scope);
+  const host = await input2.adapter.read(input2.serverName, input2.scope);
   if (!host) {
     throw conflict("Managed state exists but the Agent MCP entry is missing");
   }
@@ -1709,20 +1814,20 @@ async function disconnectAgent(input) {
   }
   const plan = {
     action: "unchanged",
-    agent: input.agent,
-    serverName: input.serverName,
-    scope: input.scope,
+    agent: input2.agent,
+    serverName: input2.serverName,
+    scope: input2.scope,
     provider: "docker-stdio",
     target: managed.docker.containerName,
     sourceId: managed.sourceId,
     currentFingerprint: host.fingerprint,
     desiredFingerprint: host.fingerprint
   };
-  if (!input.yes && !await input.confirm(`Remove ${input.serverName} from ${input.agent}?`)) {
+  if (!input2.yes && !await input2.confirm(`Remove ${input2.serverName} from ${input2.agent}?`)) {
     return {
-      agent: input.agent,
-      serverName: input.serverName,
-      scope: input.scope,
+      agent: input2.agent,
+      serverName: input2.serverName,
+      scope: input2.scope,
       action: "cancelled",
       changed: false,
       verified: true,
@@ -1730,12 +1835,12 @@ async function disconnectAgent(input) {
       plan
     };
   }
-  await input.adapter.remove(input.serverName, input.scope);
+  await input2.adapter.remove(input2.serverName, input2.scope);
   try {
-    await input.state.delete(key);
+    await input2.state.delete(key);
   } catch (cause) {
     try {
-      await input.adapter.add(input.serverName, input.scope, host.spec);
+      await input2.adapter.add(input2.serverName, input2.scope, host.spec);
     } catch {
       throw hostFailure3(
         "Managed state cleanup failed and the Agent entry could not be restored",
@@ -1748,9 +1853,9 @@ async function disconnectAgent(input) {
     );
   }
   return {
-    agent: input.agent,
-    serverName: input.serverName,
-    scope: input.scope,
+    agent: input2.agent,
+    serverName: input2.serverName,
+    scope: input2.scope,
     action: "disconnect",
     changed: true,
     verified: true,
@@ -1763,21 +1868,21 @@ async function disconnectAgent(input) {
 var SOURCE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
 var DockerStdioProvider = class {
   id = "docker-stdio";
-  async inspect(input) {
+  async inspect(input2) {
     return {
       provider: this.id,
       ready: true,
-      target: input.target.name
+      target: input2.target.name
     };
   }
-  async createSpec(input) {
-    if (input.sourceId && !SOURCE_ID_PATTERN.test(input.sourceId)) {
+  async createSpec(input2) {
+    if (input2.sourceId && !SOURCE_ID_PATTERN.test(input2.sourceId)) {
       throw new CliError("INVALID_ARGUMENT", "Invalid SAG source id", {
         exitCode: exitCodes.invalidArgument,
         hint: "Use 1-128 letters, numbers, underscores, or dashes."
       });
     }
-    const sourceArguments = input.sourceId ? ["-e", `SAG_MCP_SOURCE_ID=${input.sourceId}`] : [];
+    const sourceArguments = input2.sourceId ? ["-e", `SAG_MCP_SOURCE_ID=${input2.sourceId}`] : [];
     return {
       transport: "stdio",
       command: "docker",
@@ -1785,7 +1890,7 @@ var DockerStdioProvider = class {
         "exec",
         "-i",
         ...sourceArguments,
-        input.target.name,
+        input2.target.name,
         "python",
         "-m",
         "sag_api.mcp.server"
@@ -1835,13 +1940,13 @@ async function validateTarget(docker, container) {
   }
   return toTarget(inspection);
 }
-async function discoverSagContainer(input) {
-  await input.docker.version();
-  if (input.container) {
-    validateContainer(input.container);
-    return validateTarget(input.docker, input.container);
+async function discoverSagContainer(input2) {
+  await input2.docker.version();
+  if (input2.container) {
+    validateContainer(input2.container);
+    return validateTarget(input2.docker, input2.container);
   }
-  const containers = await input.docker.listRunningContainers();
+  const containers = await input2.docker.listRunningContainers();
   const apiCandidates = containers.filter(
     (container) => container.labels["com.docker.compose.service"] === "api"
   );
@@ -1856,7 +1961,7 @@ async function discoverSagContainer(input) {
   let preferredFailure;
   for (const candidate of apiCandidates) {
     try {
-      targets.push(await validateTarget(input.docker, candidate.id));
+      targets.push(await validateTarget(input2.docker, candidate.id));
     } catch (error) {
       firstFailure ??= error;
       if (candidate.labels["com.docker.compose.project"] === "sag") {
@@ -1872,13 +1977,13 @@ async function discoverSagContainer(input) {
   if (rankedTargets.length === 1) {
     return rankedTargets[0];
   }
-  if (!input.interactive || !input.select) {
+  if (!input2.interactive || !input2.select) {
     throw new CliError("CONFIG_CONFLICT", "Multiple SAG API containers were found", {
       exitCode: exitCodes.configConflict,
       hint: "Pass `--container <name-or-id>` to select one."
     });
   }
-  const selectedId = await input.select(rankedTargets);
+  const selectedId = await input2.select(rankedTargets);
   const selected = rankedTargets.find(
     (target) => target.id === selectedId || target.name === selectedId
   );
@@ -1891,34 +1996,34 @@ async function discoverSagContainer(input) {
 }
 
 // src/commands/agent.ts
-async function connectLocalAgent(runtime2, input) {
+async function connectLocalAgent(runtime2, input2) {
   return connectAgent({
-    agent: input.agent,
-    serverName: input.serverName,
+    agent: input2.agent,
+    serverName: input2.serverName,
     scope: "user",
-    profile: input.profile,
-    ...input.sourceId ? { sourceId: input.sourceId } : {},
-    timeoutMs: input.timeoutMs,
-    dryRun: input.dryRun,
-    yes: input.yes,
+    profile: input2.profile,
+    ...input2.sourceId ? { sourceId: input2.sourceId } : {},
+    timeoutMs: input2.timeoutMs,
+    dryRun: input2.dryRun,
+    yes: input2.yes,
     resolveConnection: async () => {
       const target = await discoverSagContainer({
         docker: runtime2.docker,
-        ...input.container ? { container: input.container } : {},
+        ...input2.container ? { container: input2.container } : {},
         interactive: runtime2.interactive,
         select: runtime2.selectContainer
       });
       const spec = await new DockerStdioProvider().createSpec({
         target,
-        ...input.sourceId ? { sourceId: input.sourceId } : {}
+        ...input2.sourceId ? { sourceId: input2.sourceId } : {}
       });
       return { target, spec };
     },
     verifier: runtime2.verifier,
-    adapter: runtime2.adapters[input.agent],
+    adapter: runtime2.adapters[input2.agent],
     state: runtime2.state,
-    confirm: input.confirm,
-    now: input.now
+    confirm: input2.confirm,
+    now: input2.now
   });
 }
 async function agentStatus(runtime2, agent, serverName) {
@@ -1997,10 +2102,10 @@ async function agentStatus(runtime2, agent, serverName) {
     };
   }
 }
-async function statusLocalAgents(runtime2, input) {
-  const agents = input.agent ? [input.agent] : ["codex", "claude-code"];
+async function statusLocalAgents(runtime2, input2) {
+  const agents = input2.agent ? [input2.agent] : ["codex", "claude-code"];
   return Promise.all(
-    agents.map((agent) => agentStatus(runtime2, agent, input.serverName))
+    agents.map((agent) => agentStatus(runtime2, agent, input2.serverName))
   );
 }
 async function listAgentHosts(runtime2) {
@@ -2021,58 +2126,69 @@ async function listAgentHosts(runtime2) {
     })
   );
 }
-async function disconnectLocalAgent(runtime2, input) {
+async function disconnectLocalAgent(runtime2, input2) {
   return disconnectAgent({
-    agent: input.agent,
-    serverName: input.serverName,
+    agent: input2.agent,
+    serverName: input2.serverName,
     scope: "user",
-    adapter: runtime2.adapters[input.agent],
+    adapter: runtime2.adapters[input2.agent],
     state: runtime2.state,
-    yes: input.yes,
-    confirm: input.confirm
+    yes: input2.yes,
+    confirm: input2.confirm
   });
 }
 
 // src/commands/auth.ts
-async function login(input) {
-  const token = input.environmentToken?.trim() || await input.promptToken();
-  if (!token.trim()) {
-    throw new CliError("AUTH_REQUIRED", "A SAG token is required", {
-      exitCode: exitCodes.authRequired,
-      hint: "Paste a token when prompted or set SAG_TOKEN."
+async function login(input2) {
+  const environmentToken = input2.environmentToken?.trim();
+  if (environmentToken) {
+    const user2 = await input2.validate(environmentToken);
+    await input2.store.set(input2.credentialRef, environmentToken);
+    return {
+      authenticated: true,
+      credentialRef: input2.credentialRef,
+      credentialStore: input2.store.kind,
+      user: user2
+    };
+  }
+  const name = (input2.name ?? await input2.promptName()).trim();
+  if (!name) {
+    throw new CliError("INVALID_ARGUMENT", "A SAG user name is required", {
+      exitCode: exitCodes.invalidArgument,
+      hint: "Pass `--name <name>` or enter a name when prompted."
     });
   }
-  const user = await input.validate(token);
-  await input.store.set(input.credentialRef, token);
+  const { accessToken, user } = await input2.authenticate(name);
+  await input2.store.set(input2.credentialRef, accessToken);
   return {
     authenticated: true,
-    credentialRef: input.credentialRef,
-    credentialStore: input.store.kind,
+    credentialRef: input2.credentialRef,
+    credentialStore: input2.store.kind,
     user
   };
 }
-async function status(input) {
-  const token = input.environmentToken?.trim() || await input.store.get(input.credentialRef);
+async function status(input2) {
+  const token = input2.environmentToken?.trim() || await input2.store.get(input2.credentialRef);
   if (!token) {
     return {
       authenticated: false,
-      credentialRef: input.credentialRef,
-      credentialStore: input.store.kind
+      credentialRef: input2.credentialRef,
+      credentialStore: input2.store.kind
     };
   }
-  const user = await input.validate(token);
+  const user = await input2.validate(token);
   return {
     authenticated: true,
-    credentialRef: input.credentialRef,
-    credentialStore: input.store.kind,
+    credentialRef: input2.credentialRef,
+    credentialStore: input2.store.kind,
     user
   };
 }
-async function logout(input) {
-  await input.store.delete(input.credentialRef);
+async function logout(input2) {
+  await input2.store.delete(input2.credentialRef);
   return {
     authenticated: false,
-    credentialRef: input.credentialRef
+    credentialRef: input2.credentialRef
   };
 }
 
@@ -2133,25 +2249,63 @@ async function documentStatus(client, sourceId, documentId) {
   };
 }
 
+// src/commands/knowledge.ts
+function requiredIdentifier2(value, label) {
+  const normalized = value.trim();
+  if (!normalized) {
+    throw new CliError("INVALID_ARGUMENT", `${label} is required`, {
+      exitCode: exitCodes.invalidArgument
+    });
+  }
+  return normalized;
+}
+async function outline(client, sourceId, documentId) {
+  return client.outline(
+    requiredIdentifier2(sourceId, "Source ID"),
+    requiredIdentifier2(documentId, "Document ID")
+  );
+}
+async function grep(client, sourceId, pattern, limit) {
+  return client.grep(
+    requiredIdentifier2(sourceId, "Source ID"),
+    requiredIdentifier2(pattern, "Pattern"),
+    limit
+  );
+}
+async function read(client, sourceId, documentId, offset, limit) {
+  return client.readDocument(
+    requiredIdentifier2(sourceId, "Source ID"),
+    requiredIdentifier2(documentId, "Document ID"),
+    offset,
+    limit
+  );
+}
+async function getEntityContext(client, sourceId, name) {
+  return client.getEntityContext(
+    requiredIdentifier2(sourceId, "Source ID"),
+    requiredIdentifier2(name, "Entity name")
+  );
+}
+
 // src/commands/mcp.ts
-async function testLocalMcp(runtime2, input) {
+async function testLocalMcp(runtime2, input2) {
   const container = await discoverSagContainer({
     docker: runtime2.docker,
-    ...input.container ? { container: input.container } : {},
+    ...input2.container ? { container: input2.container } : {},
     interactive: runtime2.interactive,
     select: runtime2.selectContainer
   });
   const spec = await new DockerStdioProvider().createSpec({
     target: container,
-    ...input.sourceId ? { sourceId: input.sourceId } : {}
+    ...input2.sourceId ? { sourceId: input2.sourceId } : {}
   });
   const verification = await runtime2.verifier.verify(spec, {
-    timeoutMs: input.timeoutMs
+    timeoutMs: input2.timeoutMs
   });
   return {
     provider: "docker-stdio",
     container,
-    sourceId: input.sourceId ?? null,
+    sourceId: input2.sourceId ?? null,
     ...verification
   };
 }
@@ -2163,9 +2317,9 @@ function skipped(name, detail) {
     detail
   };
 }
-async function localMcpDoctorChecks(runtime2, input) {
+async function localMcpDoctorChecks(runtime2, input2) {
   try {
-    const report = await testLocalMcp(runtime2, input);
+    const report = await testLocalMcp(runtime2, input2);
     return [
       {
         name: "docker",
@@ -2362,16 +2516,16 @@ function directCredentialRef(url) {
   const fingerprint = createHash2("sha256").update(url).digest("hex").slice(0, 16);
   return `sag-cli/direct-${fingerprint}`;
 }
-async function createRuntimeContext(input) {
-  const config = await input.configStore.load();
-  const connection = resolveConnection(input.options, input.environment, config);
+async function createRuntimeContext(input2) {
+  const config = await input2.configStore.load();
+  const connection = resolveConnection(input2.options, input2.environment, config);
   const credentialRef = connection.credentialRef ?? directCredentialRef(connection.url);
-  const token = connection.environmentToken ?? await input.credentialStore.get(credentialRef) ?? void 0;
+  const token = connection.environmentToken ?? await input2.credentialStore.get(credentialRef) ?? void 0;
   return {
     connection,
     credentialRef,
     ...token ? { token } : {},
-    client: input.createClient({
+    client: input2.createClient({
       origin: connection.url,
       ...token ? { token } : {}
     })
@@ -2475,7 +2629,7 @@ function documentDetail(total, statuses) {
   const parts = displayOrder.filter((status2) => statuses[status2] > 0).map((status2) => `${statuses[status2]} ${status2}`);
   return `${total} ${total === 1 ? "document" : "documents"}${parts.length ? `: ${parts.join(", ")}` : ""}`;
 }
-async function runDoctor(client, input, localMcpChecks) {
+async function runDoctor(client, input2, localMcpChecks) {
   const checks = [];
   let sagVersion;
   let authenticated = false;
@@ -2590,8 +2744,8 @@ async function runDoctor(client, input, localMcpChecks) {
   }
   return {
     status: overallStatus(checks),
-    url: input.url,
-    ...input.profileName ? { profileName: input.profileName } : {},
+    url: input2.url,
+    ...input2.profileName ? { profileName: input2.profileName } : {},
     ...sagVersion ? { sagVersion } : {},
     checks,
     summary: {
@@ -2681,6 +2835,45 @@ function renderLocalMcp(value) {
   ].join("\n")}
 `;
 }
+function renderOutline(value) {
+  const filename = typeof value.filename === "string" ? value.filename : "Unknown";
+  const items = Array.isArray(value.outline) ? value.outline.filter(isRecord) : [];
+  const lines = items.map(
+    (item) => `${String(item.rank ?? 0).padStart(3)}. ${item.heading || "(untitled)"}  (chunk_id=${item.chunk_id})`
+  );
+  return `${filename}
+${lines.join("\n")}
+`;
+}
+function renderGrep(value) {
+  const matches = Array.isArray(value.matches) ? value.matches.filter(isRecord) : [];
+  const lines = matches.map(
+    (match, index) => `[${index + 1}] ${match.heading || "Match"}
+${match.snippet}`
+  );
+  return lines.length ? `${lines.join("\n\n")}
+` : "No matches.\n";
+}
+function renderRead(value) {
+  const filename = typeof value.filename === "string" ? value.filename : "Unknown";
+  const total = typeof value.total_lines === "number" ? value.total_lines : 0;
+  const offset = typeof value.offset === "number" ? value.offset : 1;
+  const lines = Array.isArray(value.lines) ? value.lines.map(String) : [];
+  const header = `${filename} \xB7 lines ${offset}-${offset + lines.length - 1} / ${total}`;
+  return `${header}
+${lines.join("")}`;
+}
+function renderEntityContext(value) {
+  const name = typeof value.name === "string" ? value.name : "Unknown";
+  const type = typeof value.type === "string" ? value.type : "";
+  const source = typeof value.source_name === "string" ? value.source_name : "";
+  const context = typeof value.context === "string" ? value.context : "";
+  return `Entity: ${name}${type ? ` (${type})` : ""}
+Source: ${source}
+
+${context}
+`;
+}
 function renderHuman(value, quiet = false) {
   if (quiet) {
     if (Array.isArray(value)) {
@@ -2703,6 +2896,18 @@ function renderHuman(value, quiet = false) {
   if (isRecord(value) && Array.isArray(value.sections) && "query" in value) {
     return renderSearch(value);
   }
+  if (isRecord(value) && Array.isArray(value.outline) && "filename" in value) {
+    return renderOutline(value);
+  }
+  if (isRecord(value) && Array.isArray(value.matches) && "pattern" in value) {
+    return renderGrep(value);
+  }
+  if (isRecord(value) && Array.isArray(value.lines) && "total_lines" in value) {
+    return renderRead(value);
+  }
+  if (isRecord(value) && "entity_id" in value && "context" in value) {
+    return renderEntityContext(value);
+  }
   if (isRecord(value) && value.provider === "docker-stdio" && "protocolVersion" in value && "container" in value) {
     return renderLocalMcp(value);
   }
@@ -2847,12 +3052,14 @@ function addProfileCommands(program, dependencies2) {
 }
 function addAuthCommands(program, dependencies2) {
   const auth = program.command("auth").description("Manage SAG credentials");
-  auth.command("login").action(async () => {
+  auth.command("login").option("--name <name>", "SAG user name for the existing local login").action(async (options) => {
     const context = await runtime(program, dependencies2);
     const result = await login({
       credentialRef: context.credentialRef,
       ...context.connection.environmentToken ? { environmentToken: context.connection.environmentToken } : {},
-      promptToken: dependencies2.promptToken,
+      ...options.name ? { name: options.name } : {},
+      promptName: dependencies2.promptName,
+      authenticate: (name) => dependencies2.createClient({ origin: context.connection.url }).login(name),
       validate: async (token) => dependencies2.createClient({ origin: context.connection.url, token }).me(),
       store: dependencies2.credentialStore
     });
@@ -2946,6 +3153,46 @@ function addKnowledgeCommands(program, dependencies2) {
       );
     }
   );
+  program.command("outline").argument("<document-id>").requiredOption("--source <source-id>").action(async (documentId, options) => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await outline(context.client, options.source, documentId)
+    );
+  });
+  program.command("grep").argument("<pattern>").requiredOption("--source <source-id>").option("--limit <number>", "Maximum result count", parseInteger).action(async (pattern, options) => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await grep(context.client, options.source, pattern, options.limit)
+    );
+  });
+  program.command("read").argument("<document-id>").requiredOption("--source <source-id>").option("--offset <number>", "Starting line (1-based)", parseInteger).option("--limit <number>", "Lines to read", parseInteger).action(
+    async (documentId, options) => {
+      const context = await runtime(program, dependencies2);
+      emit(
+        program,
+        dependencies2,
+        await read(
+          context.client,
+          options.source,
+          documentId,
+          options.offset,
+          options.limit
+        )
+      );
+    }
+  );
+  program.command("get-entity").argument("<name>").requiredOption("--source <source-id>").action(async (name, options) => {
+    const context = await runtime(program, dependencies2);
+    emit(
+      program,
+      dependencies2,
+      await getEntityContext(context.client, options.source, name)
+    );
+  });
 }
 function addLocalMcpCommands(program, dependencies2) {
   const mcp = program.command("mcp").description("Verify local SAG MCP");
@@ -3081,10 +3328,7 @@ var dependencies = {
   configStore: new ConfigStore(defaultConfigPath()),
   credentialStore: credentialSelection.store,
   createClient: defaultClientFactory,
-  promptToken: () => password({
-    message: "SAG Token",
-    mask: "*"
-  }),
+  promptName: () => input({ message: "SAG user name" }),
   confirm: (message) => confirm({ message, default: false }),
   writeStdout: (value) => process.stdout.write(value),
   writeStderr: (value) => process.stderr.write(value),