@khotan/cli 0.5.0 → 0.8.0

package/dist/khotan.js

@@ -19,7 +19,7 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // ../khotan-core/src/version.ts
-var CATALOG_SCHEMA_VERSION = 1, CATALOG_VERSION = "2026-06-23", KHOTAN_ADAPTER_NAME = "khotan", KHOTAN_ADAPTER_VERSION = "0.5.0", SUPPORTED_CATALOG_SCHEMA_VERSIONS;
+var CATALOG_SCHEMA_VERSION = 1, CATALOG_VERSION = "2026-06-28", KHOTAN_ADAPTER_NAME = "khotan", KHOTAN_ADAPTER_VERSION = "0.7.0", SUPPORTED_CATALOG_SCHEMA_VERSIONS;
 var init_version = __esm(() => {
   SUPPORTED_CATALOG_SCHEMA_VERSIONS = [
     CATALOG_SCHEMA_VERSION
@@ -115,6 +115,12 @@ function platformDomain(config) {
   const idArg = idField(resourceParam, `The ${noun} id.`);
   const cap = domain;
   const a = article(noun);
+  const envWriteTargetField = {
+    name: "target",
+    location: "body",
+    type: "string[]",
+    description: "Environments to write, any of: production, preview, development (comma-separated or repeatable). Omit to write all environments."
+  };
   const tool = (suffix) => `khotan_${domain}_${suffix}`;
   const operations = [
     {
@@ -220,14 +226,15 @@ function platformDomain(config) {
       safety: "write",
       auth: true,
       title: `Bulk upsert ${noun} environment variables`,
-      description: `Create or update many env vars in one request.`,
+      description: `Create or update many env vars in one request. Writes every environment unless you pass target.`,
       input: [
         idArg,
-        { name: "variables", location: "body", type: "json", required: true, description: "Array of { key, value } to upsert." }
+        { name: "variables", location: "body", type: "json", required: true, description: "Array of { key, value } to upsert." },
+        envWriteTargetField
       ],
       http: { method: "POST", path: `${base}/{${resourceParam}}/env`, operationId: operationIds.envBulkSet, bodyMode: "json" },
       cli: { command: [domain, "env", "bulk-set"], summary: "Bulk upsert env vars" },
-      mcp: { tool: { name: tool("env_bulk_set"), title: "Bulk upsert env vars", description: "Create or update many env vars in one request." } }
+      mcp: { tool: { name: tool("env_bulk_set"), title: "Bulk upsert env vars", description: "Create or update many env vars in one request. Writes every environment unless target is provided." } }
     },
     {
       id: `${cap}.env.reveal`,
@@ -236,8 +243,17 @@ function platformDomain(config) {
       safety: "secret",
       auth: true,
       title: `Reveal one ${noun} environment variable value`,
-      description: `Reveal a single decrypted env var value. Secret-bearing; explicit-only.`,
-      input: [idArg, idField("key", "The env var key to reveal.")],
+      description: `Reveal a single decrypted env var value for one environment. Secret-bearing; explicit-only.`,
+      input: [
+        idArg,
+        idField("key", "The env var key to reveal."),
+        {
+          name: "target",
+          location: "query",
+          type: "string",
+          description: "Environment to read: production, preview, or development. Omit to default to production."
+        }
+      ],
       http: { method: "GET", path: `${base}/{${resourceParam}}/env/{key}`, operationId: operationIds.envReveal },
       cli: { command: [domain, "env", "reveal"], summary: "Reveal one env var value (secret)", defaultOutput: "raw" },
       mcp: { tool: { name: tool("env_reveal"), title: "Reveal one env var value (secret)", description: "Reveal one decrypted env var value. Secret-bearing — returns a credential, not a list." } }
@@ -249,15 +265,16 @@ function platformDomain(config) {
       safety: "write",
       auth: true,
       title: `Set one ${noun} environment variable`,
-      description: `Create or update one env var across all targets.`,
+      description: `Create or update one env var. Writes every environment unless you pass target.`,
       input: [
         idArg,
         idField("key", "The env var key."),
-        { name: "value", location: "body", type: "string", required: true, secret: true, description: "The env var value." }
+        { name: "value", location: "body", type: "string", required: true, secret: true, description: "The env var value." },
+        envWriteTargetField
       ],
       http: { method: "PUT", path: `${base}/{${resourceParam}}/env/{key}`, operationId: operationIds.envSet, bodyMode: "json" },
       cli: { command: [domain, "env", "set"], summary: "Set one env var" },
-      mcp: { tool: { name: tool("env_set"), title: "Set one env var", description: "Create or update one env var across all targets." } }
+      mcp: { tool: { name: tool("env_set"), title: "Set one env var", description: "Create or update one env var. Writes every environment unless target is provided." } }
     },
     {
       id: `${cap}.env.unset`,
@@ -266,11 +283,20 @@ function platformDomain(config) {
       safety: "destructive",
       auth: true,
       title: `Unset one ${noun} environment variable`,
-      description: `Delete one env var across all targets.`,
-      input: [idArg, idField("key", "The env var key to delete.")],
+      description: `Delete one env var. Removes it from every environment unless you pass target.`,
+      input: [
+        idArg,
+        idField("key", "The env var key to delete."),
+        {
+          name: "target",
+          location: "query",
+          type: "string",
+          description: "Environment to remove from: production, preview, or development. Omit to remove from all environments."
+        }
+      ],
       http: { method: "DELETE", path: `${base}/{${resourceParam}}/env/{key}`, operationId: operationIds.envDelete },
       cli: { command: [domain, "env", "unset"], summary: "Unset one env var" },
-      mcp: { tool: { name: tool("env_unset"), title: "Unset one env var", description: "Delete one env var across all targets. Requires confirmation." } }
+      mcp: { tool: { name: tool("env_unset"), title: "Unset one env var", description: "Delete one env var. Removes it from every environment unless target is provided. Requires confirmation." } }
     }
   ];
   const resource = {
@@ -296,6 +322,71 @@ function platformDomain(config) {
   };
   return [...operations, resource];
 }
+function emailSubscriptionDomain(config) {
+  const { domain, noun, resourceParam, cap } = config;
+  const base = `/api/v1/${domain}/{${resourceParam}}/email-subscriptions`;
+  const idArg = idField(resourceParam, `The ${noun} id.`);
+  const subArg = idField("subscriptionId", "The email subscription id.");
+  const tool = (suffix) => `khotan_${domain}_email_subscriptions_${suffix}`;
+  return [
+    {
+      id: `${domain}.email-subscriptions.list`,
+      kind: "operation",
+      domain,
+      safety: "read",
+      auth: true,
+      title: `List ${noun} email subscriptions`,
+      description: `List the connected mailboxes this ${noun} watches.`,
+      input: [idArg],
+      http: { method: "GET", path: base, operationId: `list${cap}EmailSubscriptions` },
+      cli: { command: [domain, "email-subscriptions", "list"], summary: "List email subscriptions", defaultOutput: "table" },
+      mcp: { tool: { name: tool("list"), title: "List email subscriptions", description: `List the connected mailboxes this ${noun} watches.` } }
+    },
+    {
+      id: `${domain}.email-subscriptions.create`,
+      kind: "operation",
+      domain,
+      safety: "write",
+      auth: true,
+      title: `Subscribe ${article(noun)} ${noun} to a mailbox`,
+      description: `Watch a connected Gmail mailbox for this ${noun}; Google pushes notifications directly to the delivery URL.`,
+      input: [
+        idArg,
+        { name: "emailIntegrationId", location: "body", type: "string", required: true, description: "The connected Gmail integration id." },
+        { name: "deliveryUrl", location: "body", type: "string", required: true, description: "https URL on the target's primary hostname." }
+      ],
+      http: { method: "POST", path: base, operationId: `create${cap}EmailSubscription`, bodyMode: "json" },
+      cli: { command: [domain, "email-subscriptions", "create"], summary: "Subscribe to a mailbox", defaultOutput: "detail" },
+      mcp: { tool: { name: tool("create"), title: "Subscribe to a mailbox", description: `Watch a connected Gmail mailbox for this ${noun}.` } }
+    },
+    {
+      id: `${domain}.email-subscriptions.get`,
+      kind: "operation",
+      domain,
+      safety: "read",
+      auth: true,
+      title: `Get ${article(noun)} ${noun} email subscription`,
+      description: "Get one email subscription by id.",
+      input: [idArg, subArg],
+      http: { method: "GET", path: `${base}/{subscriptionId}`, operationId: `get${cap}EmailSubscription` },
+      cli: { command: [domain, "email-subscriptions", "get"], summary: "Get an email subscription", defaultOutput: "detail" },
+      mcp: { tool: { name: tool("get"), title: "Get an email subscription", description: "Get one email subscription by id." } }
+    },
+    {
+      id: `${domain}.email-subscriptions.delete`,
+      kind: "operation",
+      domain,
+      safety: "destructive",
+      auth: true,
+      title: `Unsubscribe ${article(noun)} ${noun} from a mailbox`,
+      description: "Remove an email subscription (deletes the Pub/Sub push subscription).",
+      input: [idArg, subArg],
+      http: { method: "DELETE", path: `${base}/{subscriptionId}`, operationId: `delete${cap}EmailSubscription` },
+      cli: { command: [domain, "email-subscriptions", "delete"], summary: "Unsubscribe from a mailbox" },
+      mcp: { tool: { name: tool("delete"), title: "Unsubscribe from a mailbox", description: "Remove an email subscription. Requires confirmation." } }
+    }
+  ];
+}
 function getCapability(id) {
   return capabilitiesById.get(id);
 }
@@ -317,7 +408,7 @@ var idField = (name, description) => ({
   type: "string",
   required: true,
   description
-}), article = (noun) => /^[aeiou]/i.test(noun) ? "an" : "a", identityCapabilities, databaseCapabilities, fileCapabilities, folderCapabilities, contextCapabilities, appsCapabilities, pipelinesCapabilities, capabilities, khotanCatalog, capabilitiesById;
+}), article = (noun) => /^[aeiou]/i.test(noun) ? "an" : "a", identityCapabilities, databaseCapabilities, redisCapabilities, fileCapabilities, folderCapabilities, contextCapabilities, appsCapabilities, pipelinesCapabilities, integrationsCapabilities, emailSubscriptionCapabilities, capabilities, khotanCatalog, capabilitiesById;
 var init_catalog = __esm(() => {
   init_version();
   identityCapabilities = [
@@ -556,6 +647,54 @@ var init_catalog = __esm(() => {
       cli: { command: ["databases", "branches", "rotate-credentials"], summary: "Rotate branch credentials (secret)", defaultOutput: "raw" },
       mcp: { tool: { name: "khotan_databases_branches_rotate_credentials", title: "Rotate branch credentials (secret)", description: "Rotate a branch's credentials and return the new connection. Secret-bearing." } }
     },
+    {
+      id: "databases.schema-promotions.plan",
+      kind: "operation",
+      domain: "databases",
+      safety: "write",
+      auth: true,
+      title: "Plan a database schema promotion",
+      description: "Generate and validate a schema-only promotion plan from a ready branch to the production database. Data is never copied.",
+      input: [
+        idField("databaseId", "The database id."),
+        idField("branchId", "The branch id.")
+      ],
+      http: { method: "POST", path: "/api/v1/databases/{databaseId}/branches/{branchId}/schema-promotions", operationId: "planDatabaseSchemaPromotion", bodyMode: "none" },
+      cli: { command: ["databases", "schema-promotions", "plan"], summary: "Plan a schema-only promotion", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_databases_schema_promotions_plan", title: "Plan a schema promotion", description: "Generate and validate a schema-only promotion plan from a ready branch to production. Data is never copied." } }
+    },
+    {
+      id: "databases.schema-promotions.get",
+      kind: "operation",
+      domain: "databases",
+      safety: "read",
+      auth: true,
+      title: "Get a database schema promotion",
+      description: "Read one schema promotion record, including summary, blocked changes, failure state, and SQL.",
+      input: [
+        idField("databaseId", "The database id."),
+        idField("promotionId", "The schema promotion id.")
+      ],
+      http: { method: "GET", path: "/api/v1/databases/{databaseId}/schema-promotions/{promotionId}", operationId: "getDatabaseSchemaPromotion" },
+      cli: { command: ["databases", "schema-promotions", "get"], summary: "Get a schema promotion", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_databases_schema_promotions_get", title: "Get a schema promotion", description: "Read one schema promotion record, including generated SQL." } }
+    },
+    {
+      id: "databases.schema-promotions.apply",
+      kind: "operation",
+      domain: "databases",
+      safety: "destructive",
+      auth: true,
+      title: "Apply a database schema promotion",
+      description: "Apply the exact reviewed schema-only promotion SQL to the production database. Fails if branch or production schema hashes changed after planning.",
+      input: [
+        idField("databaseId", "The database id."),
+        idField("promotionId", "The schema promotion id.")
+      ],
+      http: { method: "POST", path: "/api/v1/databases/{databaseId}/schema-promotions/{promotionId}/apply", operationId: "applyDatabaseSchemaPromotion", bodyMode: "none" },
+      cli: { command: ["databases", "schema-promotions", "apply"], summary: "Apply a schema promotion" },
+      mcp: { tool: { name: "khotan_databases_schema_promotions_apply", title: "Apply a schema promotion", description: "Apply reviewed schema-only SQL to production. Requires confirmation." } }
+    },
     {
       id: "databases.branches.resource",
       kind: "resource",
@@ -581,6 +720,84 @@ var init_catalog = __esm(() => {
       }
     }
   ];
+  redisCapabilities = [
+    {
+      id: "redis.list",
+      kind: "operation",
+      domain: "redis",
+      safety: "read",
+      auth: true,
+      title: "List Redis databases",
+      description: "List the organization's Redis (KV) databases (no credentials).",
+      input: [],
+      http: { method: "GET", path: "/api/v1/redis-databases", operationId: "listRedisDatabases" },
+      cli: { command: ["redis", "list"], summary: "List Redis (KV) databases", defaultOutput: "table" },
+      mcp: { tool: { name: "khotan_redis_list", title: "List Redis databases", description: "List the organization's Redis (KV) databases (no credentials)." } }
+    },
+    {
+      id: "redis.get",
+      kind: "operation",
+      domain: "redis",
+      safety: "read",
+      auth: true,
+      title: "Get a Redis database",
+      description: "Get one Redis (KV) database by id (no credentials).",
+      input: [idField("databaseId", "The Redis database id.")],
+      http: { method: "GET", path: "/api/v1/redis-databases/{databaseId}", operationId: "getRedisDatabase" },
+      cli: { command: ["redis", "get"], summary: "Get a Redis (KV) database", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_redis_get", title: "Get a Redis database", description: "Get one Redis (KV) database by id (no credentials)." } }
+    },
+    {
+      id: "redis.create",
+      kind: "operation",
+      domain: "redis",
+      safety: "write",
+      auth: true,
+      title: "Create a Redis database",
+      description: "Provision a global Upstash Redis (KV) database. Not idempotent: retrying a succeeded create provisions a second database. Omit primaryRegion for the default region.",
+      input: [
+        { name: "name", location: "body", type: "string", required: true, description: "The database name." },
+        { name: "primaryRegion", location: "body", type: "string", description: "Optional primary region id; omit for the default region." }
+      ],
+      http: { method: "POST", path: "/api/v1/redis-databases", operationId: "createRedisDatabase", bodyMode: "json" },
+      cli: { command: ["redis", "create"], summary: "Create a Redis (KV) database", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_redis_create", title: "Create a Redis database", description: "Provision a global Upstash Redis (KV) database. Not idempotent — retrying provisions a second database." } }
+    },
+    {
+      id: "redis.delete",
+      kind: "operation",
+      domain: "redis",
+      safety: "destructive",
+      auth: true,
+      title: "Delete a Redis database",
+      description: "Permanently delete a Redis (KV) database and tear down its Upstash resources. Fails if deletion protection is enabled; remove protection from the dashboard first.",
+      input: [idField("databaseId", "The Redis database id.")],
+      http: { method: "DELETE", path: "/api/v1/redis-databases/{databaseId}", operationId: "deleteRedisDatabase" },
+      cli: { command: ["redis", "delete"], summary: "Delete a Redis (KV) database" },
+      mcp: { tool: { name: "khotan_redis_delete", title: "Delete a Redis database", description: "Permanently delete a Redis (KV) database. Requires confirmation; fails if deletion protection is enabled." } }
+    },
+    {
+      id: "redis.resource",
+      kind: "resource",
+      domain: "redis",
+      safety: "read",
+      auth: true,
+      title: "Redis database summary",
+      description: "Credential-free Redis (KV) database summary addressed by id.",
+      input: [idField("databaseId", "The Redis database id.")],
+      readsVia: "redis.get",
+      http: { method: "GET", path: "/api/v1/redis-databases/{databaseId}", operationId: "getRedisDatabase" },
+      mcp: {
+        resource: {
+          uriTemplate: "khotan://redis/{databaseId}",
+          name: "redis-database-summary",
+          title: "Redis database summary",
+          description: "Credential-free Redis (KV) database summary as JSON.",
+          mimeType: "application/json"
+        }
+      }
+    }
+  ];
   fileCapabilities = [
     {
       id: "files.list",
@@ -947,14 +1164,127 @@ var init_catalog = __esm(() => {
       envDelete: "deletePipelineEnvVar"
     }
   });
+  integrationsCapabilities = [
+    {
+      id: "integrations.list",
+      kind: "operation",
+      domain: "integrations",
+      safety: "read",
+      auth: true,
+      title: "List integrations",
+      description: "List the organization's connected mailbox integrations (no token material).",
+      input: [],
+      http: { method: "GET", path: "/api/v1/integrations", operationId: "listIntegrations" },
+      cli: { command: ["integrations", "list"], summary: "List integrations", defaultOutput: "table" },
+      mcp: { tool: { name: "khotan_integrations_list", title: "List integrations", description: "List the organization's connected mailbox integrations (no token material)." } }
+    },
+    {
+      id: "integrations.get",
+      kind: "operation",
+      domain: "integrations",
+      safety: "read",
+      auth: true,
+      title: "Get an integration",
+      description: "Get one integration by id (no token material).",
+      input: [idField("integrationId", "The integration id.")],
+      http: { method: "GET", path: "/api/v1/integrations/{integrationId}", operationId: "getIntegration" },
+      cli: { command: ["integrations", "get"], summary: "Get an integration", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_integrations_get", title: "Get an integration", description: "Get one integration by id (no token material)." } }
+    },
+    {
+      id: "integrations.connect",
+      kind: "operation",
+      domain: "integrations",
+      safety: "write",
+      auth: true,
+      title: "Start connecting an integration",
+      description: "Begin a mailbox connection and return a URL a human opens in a browser to authorize (OAuth consent cannot be completed headlessly).",
+      input: [
+        { name: "provider", location: "body", type: "string", description: "The provider to connect. Defaults to google.", default: "google" }
+      ],
+      http: { method: "POST", path: "/api/v1/integrations", operationId: "connectIntegration", bodyMode: "json" },
+      cli: { command: ["integrations", "connect"], summary: "Start connecting a mailbox", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_integrations_connect", title: "Start connecting an integration", description: "Begin a mailbox connection and return a browser URL to complete OAuth consent." } }
+    },
+    {
+      id: "integrations.rename",
+      kind: "operation",
+      domain: "integrations",
+      safety: "write",
+      auth: true,
+      title: "Rename an integration",
+      description: "Set an integration's display name. Pass an empty value to clear it.",
+      input: [
+        idField("integrationId", "The integration id."),
+        { name: "name", location: "body", type: "string", required: true, description: "The display name (empty to clear)." }
+      ],
+      http: { method: "PATCH", path: "/api/v1/integrations/{integrationId}", operationId: "updateIntegration", bodyMode: "json" },
+      cli: { command: ["integrations", "rename"], summary: "Rename an integration", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_integrations_rename", title: "Rename an integration", description: "Set an integration's display name." } }
+    },
+    {
+      id: "integrations.delete",
+      kind: "operation",
+      domain: "integrations",
+      safety: "destructive",
+      auth: true,
+      title: "Disconnect an integration",
+      description: "Permanently disconnect a mailbox integration (revokes the stored credentials).",
+      input: [idField("integrationId", "The integration id.")],
+      http: { method: "DELETE", path: "/api/v1/integrations/{integrationId}", operationId: "deleteIntegration" },
+      cli: { command: ["integrations", "delete"], summary: "Disconnect an integration" },
+      mcp: { tool: { name: "khotan_integrations_delete", title: "Disconnect an integration", description: "Permanently disconnect a mailbox integration. Requires confirmation." } }
+    },
+    {
+      id: "integrations.token",
+      kind: "operation",
+      domain: "integrations",
+      safety: "secret",
+      auth: true,
+      title: "Mint an access token (secret)",
+      description: "Mint a fresh OAuth access token for the integration so a service can call the provider on the user's behalf. Secret-bearing; explicit-only.",
+      input: [idField("integrationId", "The integration id.")],
+      http: { method: "POST", path: "/api/v1/integrations/{integrationId}/token", operationId: "mintIntegrationToken", bodyMode: "none" },
+      cli: { command: ["integrations", "token"], summary: "Mint an access token (secret)", defaultOutput: "detail" },
+      mcp: { tool: { name: "khotan_integrations_token", title: "Mint an access token (secret)", description: "Mint a fresh OAuth access token for the integration. Secret-bearing — returns a credential." } }
+    },
+    {
+      id: "integrations.resource",
+      kind: "resource",
+      domain: "integrations",
+      safety: "read",
+      auth: true,
+      title: "Integration summary",
+      description: "Credential-free integration summary addressed by id.",
+      input: [idField("integrationId", "The integration id.")],
+      readsVia: "integrations.get",
+      http: { method: "GET", path: "/api/v1/integrations/{integrationId}", operationId: "getIntegration" },
+      mcp: {
+        resource: {
+          uriTemplate: "khotan://integrations/{integrationId}",
+          name: "integration-summary",
+          title: "Integration summary",
+          description: "Credential-free integration summary as JSON.",
+          mimeType: "application/json"
+        }
+      }
+    }
+  ];
+  emailSubscriptionCapabilities = [
+    ...emailSubscriptionDomain({ domain: "apps", noun: "deployment", resourceParam: "appId", cap: "App" }),
+    ...emailSubscriptionDomain({ domain: "pipelines", noun: "pipeline", resourceParam: "pipelineId", cap: "Pipeline" })
+  ];
   capabilities = [
     ...identityCapabilities,
     ...appsCapabilities,
     ...pipelinesCapabilities,
     ...databaseCapabilities,
+    ...redisCapabilities,
     ...fileCapabilities,
     ...folderCapabilities,
-    ...contextCapabilities
+    ...contextCapabilities,
+    ...integrationsCapabilities,
+    ...emailSubscriptionCapabilities
   ];
   khotanCatalog = {
     schemaVersion: CATALOG_SCHEMA_VERSION,
@@ -1315,6 +1645,66 @@ var init_profiles = __esm(() => {
   init_errors();
 });
 
+// ../khotan-core/src/profiles/repo-env.ts
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
+function findRepoEnvFile(startDir) {
+  let dir = startDir;
+  for (;; ) {
+    const candidate = join2(dir, REPO_ENV_FILENAME);
+    if (existsSync(candidate))
+      return candidate;
+    if (existsSync(join2(dir, ".git")))
+      return;
+    const parent = dirname2(dir);
+    if (parent === dir)
+      return;
+    dir = parent;
+  }
+}
+function parseRepoEnvFile(contents) {
+  const map = new Map;
+  for (const rawLine of contents.split(`
+`)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#"))
+      continue;
+    const eq = line.indexOf("=");
+    if (eq === -1)
+      continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (value.startsWith("'") && value.endsWith("'") || value.startsWith('"') && value.endsWith('"')) {
+      value = value.slice(1, -1);
+    }
+    map.set(key, value);
+  }
+  return map;
+}
+function overlayRepoEnv(env, options) {
+  const filePath = findRepoEnvFile(options.cwd);
+  if (!filePath)
+    return { env };
+  let parsed;
+  try {
+    parsed = parseRepoEnvFile(readFileSync2(filePath, "utf8"));
+  } catch {
+    return { env, filePath };
+  }
+  const merged = { ...env };
+  for (const key of OVERLAY_KEYS) {
+    const value = parsed.get(key)?.trim();
+    if (value)
+      merged[key] = value;
+  }
+  return { env: merged, filePath, orgId: merged[ENV_ORG_ID]?.trim() || undefined };
+}
+var ENV_ORG_ID = "KHOTAN_ORG_ID", REPO_ENV_FILENAME = "env.khotan.local", OVERLAY_KEYS;
+var init_repo_env = __esm(() => {
+  init_profiles();
+  OVERLAY_KEYS = [ENV_API_URL, ENV_API_KEY, ENV_PROFILE, ENV_ORG_ID];
+});
+
 // ../khotan-core/src/index.ts
 var exports_src = {};
 __export(exports_src, {
@@ -1325,6 +1715,8 @@ __export(exports_src, {
   saveProfileStore: () => saveProfileStore,
   resolveProfile: () => resolveProfile,
   requiresConfirmation: () => requiresConfirmation,
+  parseRepoEnvFile: () => parseRepoEnvFile,
+  overlayRepoEnv: () => overlayRepoEnv,
   loadProfileStore: () => loadProfileStore,
   listDomains: () => listDomains,
   listCapabilities: () => listCapabilities,
@@ -1338,12 +1730,14 @@ __export(exports_src, {
   indexOpenApiOperations: () => indexOpenApiOperations,
   getProfileStorePath: () => getProfileStorePath,
   getCapability: () => getCapability,
+  findRepoEnvFile: () => findRepoEnvFile,
   createApiClient: () => createApiClient,
   capabilitiesByOperationId: () => capabilitiesByOperationId,
   buildHttpRequest: () => buildHttpRequest,
   assertSupportedCatalogSchemaVersion: () => assertSupportedCatalogSchemaVersion,
   SUPPORTED_CATALOG_SCHEMA_VERSIONS: () => SUPPORTED_CATALOG_SCHEMA_VERSIONS,
   SAFETY_LEVELS: () => SAFETY_LEVELS,
+  REPO_ENV_FILENAME: () => REPO_ENV_FILENAME,
   KhotanUnknownCapabilityError: () => KhotanUnknownCapabilityError,
   KhotanError: () => KhotanError,
   KhotanConfirmationRequiredError: () => KhotanConfirmationRequiredError,
@@ -1353,6 +1747,7 @@ __export(exports_src, {
   KHOTAN_ADAPTER_VERSION: () => KHOTAN_ADAPTER_VERSION,
   KHOTAN_ADAPTER_NAME: () => KHOTAN_ADAPTER_NAME,
   ENV_PROFILE: () => ENV_PROFILE,
+  ENV_ORG_ID: () => ENV_ORG_ID,
   ENV_API_URL: () => ENV_API_URL,
   ENV_API_KEY: () => ENV_API_KEY,
   CATALOG_VERSION: () => CATALOG_VERSION,
@@ -1366,6 +1761,7 @@ var init_src = __esm(() => {
   init_validate();
   init_api_client();
   init_profiles();
+  init_repo_env();
 });
 
 // src/cli/io.ts
@@ -1402,6 +1798,65 @@ function errLine(io, line = "") {
 }
 var init_io = () => {};
 
+// src/cli/assert-org.ts
+import { createHash } from "node:crypto";
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname4, join as join5 } from "node:path";
+function cacheDir(env) {
+  const xdg = env.XDG_CACHE_HOME;
+  const base = xdg && xdg.trim() ? xdg : join5(homedir2(), ".cache");
+  return join5(base, "khotan");
+}
+function cacheFilePath(env, apiUrl, orgId) {
+  const hash = createHash("sha256").update(`${apiUrl}
+${orgId}`).digest("hex").slice(0, 32);
+  return join5(cacheDir(env), `org-assert-${hash}.json`);
+}
+function readAssertionCache(path, expectedOrgId) {
+  if (!existsSync3(path))
+    return false;
+  try {
+    const parsed = JSON.parse(readFileSync4(path, "utf8"));
+    if (parsed.organizationId !== expectedOrgId)
+      return false;
+    if (Date.now() - parsed.verifiedAt > CACHE_TTL_MS)
+      return false;
+    return true;
+  } catch {
+    return false;
+  }
+}
+function writeAssertionCache(path, organizationId) {
+  try {
+    mkdirSync3(dirname4(path), { recursive: true });
+    const payload = { organizationId, verifiedAt: Date.now() };
+    writeFileSync4(path, `${JSON.stringify(payload)}
+`);
+  } catch {}
+}
+async function assertOrg(session, expectedOrgId, options = {}) {
+  const expected = expectedOrgId.trim();
+  if (!expected)
+    return;
+  const env = options.env ?? process.env;
+  const cachePath = cacheFilePath(env, session.apiUrl, expected);
+  if (!options.skipCache && readAssertionCache(cachePath, expected)) {
+    return;
+  }
+  const principal = await session.client.execute("identity.whoami");
+  const actual = String(principal.organizationId ?? "");
+  if (actual !== expected) {
+    throw new KhotanClientError("org_mismatch", `Khotan org mismatch: expected organizationId=${expected} (KHOTAN_ORG_ID / --assert-org), ` + `but whoami returned organizationId=${actual || "(empty)"}. ` + `You may be authenticated to a different customer's org. ` + `Fix credentials in env.khotan.local, pass --assert-org, or select a per-customer profile.`);
+  }
+  writeAssertionCache(cachePath, actual);
+}
+var CACHE_TTL_MS;
+var init_assert_org = __esm(() => {
+  init_src();
+  CACHE_TTL_MS = 5 * 60 * 1000;
+});
+
 // src/cli/session.ts
 function resolveSession(options) {
   const resolved = resolveProfile({
@@ -1421,8 +1876,17 @@ function resolveSession(options) {
     apiKey
   };
 }
+async function resolveSessionAsserted(options) {
+  const session = resolveSession(options);
+  const expectedOrgId = options.assertOrgOverride?.trim() || options.env[ENV_ORG_ID]?.trim();
+  if (expectedOrgId) {
+    await assertOrg(session, expectedOrgId, { env: options.env });
+  }
+  return session;
+}
 var init_session = __esm(() => {
   init_src();
+  init_assert_org();
 });
 
 // src/mcp/protocol.ts
@@ -1673,13 +2137,14 @@ __export(exports_serve, {
 import { createInterface as createInterface2 } from "node:readline";
 async function serveMcp(deps) {
   assertSupportedCatalogSchemaVersion();
-  const session = resolveSession({
+  const session = await resolveSessionAsserted({
     env: deps.env,
     storeOptions: deps.storeOptions,
     profileName: deps.profileName,
     apiUrlOverride: deps.apiUrlOverride,
     apiKeyOverride: deps.apiKeyOverride,
-    fetch: deps.fetch
+    fetch: deps.fetch,
+    assertOrgOverride: deps.assertOrgOverride
   });
   if (!session.apiKey) {
     throw new KhotanClientError("not_authenticated", "The MCP server needs an API key. Run `khotan auth set-key` or set KHOTAN_API_KEY.");
@@ -2053,8 +2518,8 @@ async function downloadFile(deps, options) {
 
 // src/cli/commands/init.ts
 init_io();
-import { existsSync, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
-import { dirname as dirname2, join as join2, relative } from "node:path";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync, readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname3, join as join3, relative } from "node:path";
 
 // src/cli/skills.ts
 init_src();
@@ -2161,9 +2626,11 @@ var DOMAIN_TITLES = {
   apps: "Apps",
   pipelines: "Pipelines",
   databases: "Databases",
+  redis: "Redis (KV)",
   files: "Files",
   folders: "Folders",
-  context: "Context documents"
+  context: "Context documents",
+  integrations: "Integrations"
 };
 function commandWords(capability) {
   return capability.cli?.command.join(" ");
@@ -2229,6 +2696,8 @@ function printTopLevelHelp(io) {
   outLine(io, "  files download <fileId>     Download a file to --output (presigned flow)");
   outLine(io);
   outLine(io, "Workspace:");
+  outLine(io, "  status                      Show the workspace topology (apps, pipelines, databases)");
+  outLine(io, "  status --write              Refresh a committable WORKSPACE.md from live data");
   outLine(io, "  init                        Scaffold MCP config + agent guidance into this workspace");
   outLine(io);
   outLine(io, "Agent:");
@@ -2240,10 +2709,33 @@ function printTopLevelHelp(io) {
   outLine(io, "  --profile <name>            Use a specific stored profile");
   outLine(io, "  --api-url <url>             Override the API origin");
   outLine(io, "  --api-key <key>             Override the API key");
+  outLine(io, "  --assert-org <id>           Require whoami.organizationId to equal <id> (fail closed)");
   outLine(io, "  --help                      Show help for a command");
   outLine(io);
   outLine(io, `khotan v${KHOTAN_ADAPTER_VERSION}`);
 }
+function groupCommands(prefix) {
+  if (prefix.length === 0) {
+    return [];
+  }
+  return listCapabilities().filter((capability) => {
+    if (!isOperationCapability(capability) || !capability.cli) {
+      return false;
+    }
+    const words = capability.cli.command;
+    return words.length > prefix.length && prefix.every((word, index) => words[index] === word);
+  });
+}
+function printGroupHelp(io, prefix, commands) {
+  outLine(io, `khotan ${prefix.join(" ")} — commands`);
+  outLine(io);
+  for (const capability of commands) {
+    const words = commandWords(capability) ?? capability.id;
+    outLine(io, `  ${words.padEnd(30)} ${capability.cli?.summary ?? capability.title}`);
+  }
+  outLine(io);
+  outLine(io, "Run `khotan <command> --help` for details.");
+}
 function printCommandHelp(io, capability) {
   outLine(io, capability.title);
   outLine(io);
@@ -2276,6 +2768,7 @@ var DOMAIN_TITLES2 = {
   apps: "Apps",
   pipelines: "Pipelines",
   databases: "Databases",
+  redis: "Redis (KV)",
   files: "Files",
   folders: "Folders",
   context: "Context documents"
@@ -2284,6 +2777,7 @@ var DOMAIN_LABELS = {
   apps: "apps",
   pipelines: "pipelines",
   databases: "databases and database branches",
+  redis: "Redis (KV) databases",
   files: "files",
   folders: "folders",
   context: "context documents"
@@ -2458,32 +2952,54 @@ var SKILL_BASES = [".cursor", ".agents", ".claude"];
 function mcpServerEntry() {
   return {
     command: "khotan",
-    args: ["mcp", "serve"],
-    env: {
-      KHOTAN_API_URL: "<your-khotan-api-url>",
-      KHOTAN_API_KEY: "<your-khotan-api-key>"
-    }
+    args: ["mcp", "serve"]
   };
 }
 var GUIDE_BODY = `This workspace is wired to Khotan through the \`khotan\` CLI and its MCP server.
 Use them to inspect and configure apps, pipelines, databases, files, folders, and
 context documents through the Khotan \`/api/v1\` surface.
 
+## Org isolation (never cross customers)
+
+Khotan credentials are machine-global unless scoped per repo. Pin this repo to
+its organization with \`KHOTAN_ORG_ID\` in \`env.khotan.local\`: the CLI and MCP
+server load that file and assert \`whoami.organizationId === KHOTAN_ORG_ID\`
+before trusting any output, failing closed on mismatch. You can also pass
+\`--assert-org <id>\` on any command.
+
+If \`apps list\` / \`context list\` returns another customer's data (foreign product
+names, wrong org slug), **stop** — credentials are wrong. Do not infer
+deployment or env from CLI output until the org assertion passes.
+
 ## Authentication (do this once — never commit secrets)
 
-Khotan reads an organization-scoped API key from a stored profile or the
-environment:
+Repo credentials live in \`env.khotan.local\` (\`KHOTAN_API_URL\`, \`KHOTAN_API_KEY\`,
+\`KHOTAN_ORG_ID\`), which the CLI auto-loads. Alternatively:
 
-- Profile (recommended): \`khotan auth set-key --api-url <url> --api-key <key>\`
-  stores the key in an owner-only file outside the repository.
-- Environment: export \`KHOTAN_API_URL\` and \`KHOTAN_API_KEY\` in your shell or
-  agent sandbox.
+- Profile: \`khotan auth set-key --api-url <url> --api-key <key>\` stores the key in
+  an owner-only file outside the repository (use a per-customer profile name, not
+  \`default\`).
+- Environment: export \`KHOTAN_API_URL\`, \`KHOTAN_API_KEY\`, and \`KHOTAN_ORG_ID\`.
 
 Never put an API key in a file committed to the repository. The generated MCP
-config contains only placeholders.
+config carries no secrets — the server resolves credentials at startup.
+
+## Workspace layout
+
+A Khotan workspace is an **organization mono-root repo**: one GitHub repo whose
+top-level subdirectories are each an independent deployable (an app or a
+pipeline). The repo root holds shared agent skills and instruction files;
+per-app guidance lives in each subdirectory's own \`AGENTS.md\` / \`CLAUDE.md\`.
+
+- Run \`khotan status\` to see which subdirectory maps to which app/pipeline and
+  database, and which repo it deploys from. \`khotan status --write\` refreshes a
+  committable \`WORKSPACE.md\` with that map.
+- Each app lives in its own subdirectory — **do not run app scaffolders (e.g.
+  \`khotan-data init\`) at the repo root.** \`cd\` into the app's subdirectory first.
 
 ## CLI surface
 
+- \`khotan status\` — the workspace topology (apps, pipelines, databases) at a glance
 - \`khotan apps list|get|create|delete|redeploy\` and \`khotan apps env …\`
 - \`khotan pipelines …\`, \`khotan databases …\`
 - \`khotan files list|upload|download|…\`, \`khotan folders …\`
@@ -2503,7 +3019,9 @@ surface.
 ## MCP
 
 \`khotan mcp serve\` exposes the same operations as MCP tools and durable reads as
-MCP resources, reusing your stored profile or environment credentials.
+MCP resources, scoping credentials from \`env.khotan.local\` (or your stored
+profile) and asserting the org at startup. Restart the MCP server after changing
+\`env.khotan.local\`.
 `;
 var CURSOR_RULES = `---
 description: Use the Khotan CLI and MCP tools to configure and operate this workspace's Khotan resources
@@ -2519,31 +3037,59 @@ ${GUIDE_BODY}`;
 function toRelative(cwd, absolutePath) {
   return relative(cwd, absolutePath) || absolutePath;
 }
+function detectMonoRoot(cwd) {
+  if (hasWorkspacesManifest(join3(cwd, "package.json")))
+    return true;
+  if (existsSync2(join3(cwd, "turbo.json")))
+    return true;
+  if (existsSync2(join3(cwd, "WORKSPACE.md")))
+    return true;
+  if (existsSync2(join3(cwd, "package.json")))
+    return false;
+  try {
+    return readdirSync(cwd, { withFileTypes: true }).some((entry) => entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules" && existsSync2(join3(cwd, entry.name, "package.json")));
+  } catch {
+    return false;
+  }
+}
+function hasWorkspacesManifest(packageJsonPath) {
+  if (!existsSync2(packageJsonPath))
+    return false;
+  try {
+    const parsed = JSON.parse(readFileSync3(packageJsonPath, "utf8"));
+    if (typeof parsed !== "object" || parsed === null)
+      return false;
+    const workspaces = parsed.workspaces;
+    return Array.isArray(workspaces) && workspaces.length > 0;
+  } catch {
+    return false;
+  }
+}
 function writeTextAsset(ctx, absolutePath, content) {
   const path = toRelative(ctx.cwd, absolutePath);
-  const existed = existsSync(absolutePath);
+  const existed = existsSync2(absolutePath);
   if (existed && !ctx.force) {
     ctx.results.push({ path, action: "skipped" });
     return;
   }
-  mkdirSync2(dirname2(absolutePath), { recursive: true });
+  mkdirSync2(dirname3(absolutePath), { recursive: true });
   writeFileSync2(absolutePath, content);
   ctx.results.push({ path, action: existed ? "forced" : "created" });
 }
 function writeManagedAsset(ctx, absolutePath, content) {
   const path = toRelative(ctx.cwd, absolutePath);
-  const existed = existsSync(absolutePath);
-  mkdirSync2(dirname2(absolutePath), { recursive: true });
+  const existed = existsSync2(absolutePath);
+  mkdirSync2(dirname3(absolutePath), { recursive: true });
   writeFileSync2(absolutePath, content);
   ctx.results.push({ path, action: existed ? "updated" : "created" });
 }
 function writeMcpConfig(ctx, absolutePath) {
   const path = toRelative(ctx.cwd, absolutePath);
   let config = {};
-  const existed = existsSync(absolutePath);
+  const existed = existsSync2(absolutePath);
   if (existed) {
     try {
-      config = JSON.parse(readFileSync2(absolutePath, "utf8"));
+      config = JSON.parse(readFileSync3(absolutePath, "utf8"));
     } catch {
       ctx.results.push({ path, action: "skipped" });
       return;
@@ -2559,7 +3105,7 @@ function writeMcpConfig(ctx, absolutePath) {
     return;
   }
   servers[MCP_SERVER_KEY] = mcpServerEntry();
-  mkdirSync2(dirname2(absolutePath), { recursive: true });
+  mkdirSync2(dirname3(absolutePath), { recursive: true });
   writeFileSync2(absolutePath, `${JSON.stringify(config, null, 2)}
 `);
   ctx.results.push({
@@ -2571,19 +3117,20 @@ function runInit(options) {
   const { io, cwd, client, force, json } = options;
   const ctx = { cwd, force, results: [] };
   if (client === "cursor") {
-    writeMcpConfig(ctx, join2(cwd, ".cursor", "mcp.json"));
-    writeTextAsset(ctx, join2(cwd, ".cursor", "rules", "khotan.mdc"), CURSOR_RULES);
+    writeMcpConfig(ctx, join3(cwd, ".cursor", "mcp.json"));
+    writeTextAsset(ctx, join3(cwd, ".cursor", "rules", "khotan.mdc"), CURSOR_RULES);
   } else {
-    writeMcpConfig(ctx, join2(cwd, "mcp.json"));
-    writeTextAsset(ctx, join2(cwd, "khotan-agents.md"), GENERIC_GUIDE);
+    writeMcpConfig(ctx, join3(cwd, "mcp.json"));
+    writeTextAsset(ctx, join3(cwd, "khotan-agents.md"), GENERIC_GUIDE);
   }
   for (const skill of generateSkills()) {
     for (const base of SKILL_BASES) {
-      writeManagedAsset(ctx, join2(cwd, base, "skills", skill.name, "SKILL.md"), skill.content);
+      writeManagedAsset(ctx, join3(cwd, base, "skills", skill.name, "SKILL.md"), skill.content);
     }
   }
+  const monoRoot = detectMonoRoot(cwd);
   if (json) {
-    io.out(`${JSON.stringify({ client, actions: ctx.results }, null, 2)}
+    io.out(`${JSON.stringify({ client, monoRoot, actions: ctx.results }, null, 2)}
 `);
     return 0;
   }
@@ -2592,12 +3139,322 @@ function runInit(options) {
     errLine(io, `  ${result.action.padEnd(8)} ${result.path}`);
   }
   errLine(io);
+  if (monoRoot) {
+    errLine(io, "Detected a Khotan mono-root workspace (multiple apps under one repo).");
+    errLine(io, "Each app lives in its own subdirectory — do NOT run app scaffolders");
+    errLine(io, "(e.g. `khotan-data init`) at this root. `cd` into an app subdirectory");
+    errLine(io, "first. Run `khotan status` to see the layout.");
+    errLine(io);
+  }
   errLine(io, "Next steps:");
   errLine(io, "  1. Authenticate: khotan auth set-key --api-url <url> --api-key <key>");
   errLine(io, "  2. Open this workspace in your agent and ask it to configure Khotan.");
   return 0;
 }
 
+// src/cli/commands/status.ts
+init_io();
+import { writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join4, relative as relative2 } from "node:path";
+function str(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function record(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function listOf(result, key) {
+  const container = record(result);
+  const candidate = container && Array.isArray(container[key]) && container[key] || Array.isArray(result) && result || container && soleArrayProperty(container) || [];
+  return candidate.map(record).filter((r) => r !== null);
+}
+function soleArrayProperty(container) {
+  const arrays = Object.keys(container).filter((k) => Array.isArray(container[k]));
+  return arrays.length === 1 ? container[arrays[0]] : null;
+}
+function toResourceRow(kind, raw) {
+  const repo = record(raw.repo);
+  return {
+    kind,
+    name: str(raw.displayName) ?? str(raw.slug) ?? "(unnamed)",
+    slug: str(raw.slug) ?? "",
+    status: str(raw.status) ?? "unknown",
+    subdirectory: repo ? str(repo.subdirectory) : null,
+    repo: repo ? str(repo.fullName) : null,
+    branch: repo ? str(repo.defaultBranch) : null,
+    hostname: str(raw.liveUrl) ?? str(raw.primaryHostname) ?? null
+  };
+}
+function toDatabaseRow(raw) {
+  return {
+    name: str(raw.displayName) ?? "(unnamed)",
+    status: str(raw.status) ?? "unknown",
+    environment: str(raw.environment),
+    region: str(raw.regionId),
+    host: str(raw.endpointHost)
+  };
+}
+function toRedisRow(raw) {
+  return {
+    name: str(raw.displayName) ?? "(unnamed)",
+    status: str(raw.status) ?? "unknown",
+    environment: null,
+    region: str(raw.primaryRegion),
+    host: str(raw.endpointHost)
+  };
+}
+async function readList(session, capabilityId, domain, errors, map, responseKey = domain) {
+  try {
+    const result = await session.client.execute(capabilityId);
+    return map(listOf(result, responseKey));
+  } catch (error) {
+    errors.push({
+      domain,
+      message: error instanceof Error ? error.message : String(error)
+    });
+    return [];
+  }
+}
+async function loadTopology(session) {
+  const errors = [];
+  const apps = await readList(session, "apps.list", "apps", errors, (rows) => rows.map((r) => toResourceRow("app", r)));
+  const pipelines = await readList(session, "pipelines.list", "pipelines", errors, (rows) => rows.map((r) => toResourceRow("pipeline", r)));
+  const databases = await readList(session, "databases.list", "databases", errors, (rows) => rows.map(toDatabaseRow));
+  const redisDatabases = await readList(session, "redis.list", "redis", errors, (rows) => rows.map(toRedisRow), "databases");
+  const repoBearer = [...apps, ...pipelines].find((r) => r.repo);
+  return {
+    repo: repoBearer?.repo ?? null,
+    defaultBranch: repoBearer?.branch ?? null,
+    apps,
+    pipelines,
+    databases,
+    redisDatabases,
+    errors
+  };
+}
+var EM_DASH = "—";
+function table(rows) {
+  if (rows.length === 0) {
+    return ["  (none)"];
+  }
+  const columns = Object.keys(rows[0]);
+  const widths = columns.map((column) => Math.max(column.length, ...rows.map((row) => (row[column] ?? "").length)));
+  const format = (cells) => `  ${cells.map((cell, index) => cell.padEnd(widths[index] ?? 0)).join("  ").trimEnd()}`;
+  return [
+    format(columns),
+    format(widths.map((width) => "-".repeat(width))),
+    ...rows.map((row) => format(columns.map((column) => row[column] ?? "")))
+  ];
+}
+function resourceTable(rows) {
+  return rows.map((row) => ({
+    subdir: row.subdirectory ?? EM_DASH,
+    name: row.name,
+    status: row.status,
+    hostname: row.hostname ?? EM_DASH
+  }));
+}
+function deployables(topology) {
+  return [...topology.apps, ...topology.pipelines];
+}
+function deployableLayout(topology) {
+  if (topology.errors.some((error) => error.domain === "apps" || error.domain === "pipelines")) {
+    return "partial";
+  }
+  const rows = deployables(topology);
+  if (rows.length === 0)
+    return "empty";
+  const withSubdir = rows.filter((row) => row.subdirectory).length;
+  if (withSubdir === rows.length)
+    return "subdirectory";
+  if (withSubdir === 0)
+    return "whole-repo";
+  return "mixed";
+}
+function renderLayoutIntro(io, topology) {
+  const layout = deployableLayout(topology);
+  if (layout === "subdirectory") {
+    outLine(io, "Every app and pipeline below lives as a subdirectory of one shared");
+    outLine(io, "organization mono-root repo — that repo is the deploy source. Each");
+    outLine(io, "subdirectory is an independent deployable. Databases are separate");
+    outLine(io, "resources, linked to apps via env vars (`khotan apps env list`), not");
+    outLine(io, "by directory.");
+    return;
+  }
+  if (layout === "mixed") {
+    outLine(io, "Some deployables below live in subdirectories of the deploy repo;");
+    outLine(io, "rows marked with — use the repo root or have no subdirectory metadata.");
+  } else if (layout === "whole-repo") {
+    outLine(io, "Deployables below use the deploy repo root or have no subdirectory");
+    outLine(io, "metadata, rather than an organization mono-root subdirectory layout.");
+  } else if (layout === "partial") {
+    outLine(io, "Some app or pipeline data could not be read, so the deployable");
+    outLine(io, "layout below is incomplete. Treat missing deployables as unknown.");
+  } else {
+    outLine(io, "No app or pipeline deployables were returned yet.");
+  }
+  outLine(io, "Databases are separate resources, linked to apps via env vars");
+  outLine(io, "(`khotan apps env list`), not by directory.");
+}
+function renderHuman(io, topology) {
+  outLine(io, "Workspace topology");
+  outLine(io);
+  renderLayoutIntro(io, topology);
+  outLine(io);
+  outLine(io, `Deploy repo: ${topology.repo ?? "(none provisioned yet)"}` + (topology.defaultBranch ? `  (branch: ${topology.defaultBranch})` : ""));
+  outLine(io);
+  outLine(io, `Apps (${topology.apps.length})`);
+  for (const line of table(resourceTable(topology.apps)))
+    outLine(io, line);
+  outLine(io);
+  outLine(io, `Pipelines (${topology.pipelines.length})`);
+  for (const line of table(resourceTable(topology.pipelines)))
+    outLine(io, line);
+  outLine(io);
+  outLine(io, `Databases (${topology.databases.length})`);
+  for (const line of table(topology.databases.map((db) => ({
+    name: db.name,
+    status: db.status,
+    region: db.region ?? EM_DASH,
+    host: db.host ?? EM_DASH
+  })))) {
+    outLine(io, line);
+  }
+  outLine(io);
+  outLine(io, `Redis (KV) (${topology.redisDatabases.length})`);
+  for (const line of table(topology.redisDatabases.map((db) => ({
+    name: db.name,
+    status: db.status,
+    region: db.region ?? EM_DASH,
+    host: db.host ?? EM_DASH
+  })))) {
+    outLine(io, line);
+  }
+  for (const failure of topology.errors) {
+    errLine(io, `! could not read ${failure.domain}: ${failure.message}`);
+  }
+}
+function markdownTable(headers, rows) {
+  const lines = [
+    `| ${headers.join(" | ")} |`,
+    `| ${headers.map(() => "---").join(" | ")} |`,
+    ...rows.map((row) => `| ${row.join(" | ")} |`)
+  ];
+  return lines.join(`
+`);
+}
+function mdCell(value) {
+  return value ? value : EM_DASH;
+}
+function workspaceIntro(topology) {
+  const layout = deployableLayout(topology);
+  if (layout === "subdirectory") {
+    return [
+      "This directory is one **organization mono-root repo**: a single GitHub repo",
+      "whose top-level subdirectories are each an independent Khotan deployable (an",
+      "app or a pipeline). Cloning the repo (or a sparse subdirectory checkout) gives",
+      "you the code; each subdirectory deploys on its own from this same repo.",
+      "",
+      "**Do not run app scaffolders (e.g. `khotan-data init`) at this root.** Each",
+      "app already lives in its own subdirectory — `cd` into it first."
+    ];
+  }
+  if (layout === "mixed") {
+    return [
+      "This file records Khotan deployables for this repository. Some deployables",
+      "live in subdirectories; deployables marked with — use the repo root or have",
+      "no subdirectory metadata.",
+      "",
+      "For deployables with a subdirectory, `cd` into that directory before running",
+      "app scaffolders. For rows marked —, verify the resource layout before",
+      "scaffolding."
+    ];
+  }
+  if (layout === "whole-repo") {
+    return [
+      "This file records Khotan deployables for this repository. The returned",
+      "deployables use the repo root or have no subdirectory metadata, so this is",
+      "not described as an organization mono-root subdirectory layout."
+    ];
+  }
+  if (layout === "partial") {
+    return [
+      "This file records Khotan deployables for this repository. Some app or",
+      "pipeline data could not be read, so the deployable layout is incomplete.",
+      "Use the Read Errors section before deciding where to run scaffolders."
+    ];
+  }
+  return [
+    "This file records Khotan deployables for this repository. No apps or pipelines",
+    "were returned yet; re-run `khotan status --write` after provisioning resources",
+    "to capture their deploy mapping."
+  ];
+}
+function errorsSection(errors) {
+  if (errors.length === 0)
+    return [];
+  return [
+    "",
+    "## Read Errors",
+    "",
+    "Some live data could not be read while generating this file. Treat affected",
+    "empty sections as unknown, not as confirmed empty.",
+    "",
+    markdownTable(["Domain", "Error"], errors.map((error) => [error.domain, error.message]))
+  ];
+}
+function buildWorkspaceManifest(topology) {
+  const rows = deployables(topology);
+  const sections = [];
+  sections.push("# Workspace", "", "> Generated by `khotan status --write`. Re-run to refresh; safe to commit.", "", ...workspaceIntro(topology), "", `- **Deploy repo:** ${topology.repo ? `\`${topology.repo}\`` : "_(none provisioned yet)_"}` + (topology.defaultBranch ? ` (branch \`${topology.defaultBranch}\`)` : ""));
+  sections.push("", "## Deployables", "", rows.length === 0 ? "_No apps or pipelines provisioned yet._" : markdownTable(["Subdirectory", "Resource", "Type", "Status", "Live URL"], rows.map((row) => [
+    row.subdirectory ? `\`${row.subdirectory}\`` : EM_DASH,
+    row.name,
+    row.kind,
+    row.status,
+    row.hostname ? `https://${row.hostname.replace(/^https?:\/\//, "")}` : EM_DASH
+  ])));
+  sections.push("", "## Databases", "", "Databases are separate resources. An app connects to one through environment", "variables (`khotan apps env list <appId>`), not by directory.", "", topology.databases.length === 0 ? "_No databases provisioned yet._" : markdownTable(["Name", "Status", "Environment", "Region", "Host"], topology.databases.map((db) => [
+    db.name,
+    db.status,
+    mdCell(db.environment),
+    mdCell(db.region),
+    mdCell(db.host)
+  ])));
+  sections.push("", "## Redis (KV)", "", "Redis (KV) databases are separate resources. An app connects to one through", "environment variables (`khotan apps env list <appId>`), not by directory.", "", topology.redisDatabases.length === 0 ? "_No Redis (KV) databases provisioned yet._" : markdownTable(["Name", "Status", "Region", "Host"], topology.redisDatabases.map((db) => [
+    db.name,
+    db.status,
+    mdCell(db.region),
+    mdCell(db.host)
+  ])));
+  sections.push(...errorsSection(topology.errors));
+  sections.push("", "## Working here", "", "- `khotan status` — reprint this topology (`--json` for machine output).", "- `khotan status --write` — regenerate this `WORKSPACE.md` from live data.", "- `khotan apps list` · `khotan pipelines list` · `khotan databases list` · `khotan redis list` — per-domain detail.", "");
+  return sections.join(`
+`);
+}
+async function runStatus(options) {
+  const { session, io, json, writeDir } = options;
+  const topology = await loadTopology(session);
+  if (writeDir) {
+    const target = join4(writeDir, "WORKSPACE.md");
+    writeFileSync3(target, buildWorkspaceManifest(topology));
+    const shown = relative2(process.cwd(), target) || target;
+    if (json) {
+      outLine(io, JSON.stringify({ wrote: shown, topology }, null, 2));
+    } else {
+      renderHuman(io, topology);
+      errLine(io);
+      errLine(io, `Wrote ${shown}`);
+    }
+    return 0;
+  }
+  if (json) {
+    outLine(io, JSON.stringify(topology, null, 2));
+    return 0;
+  }
+  renderHuman(io, topology);
+  return 0;
+}
+
 // src/cli/confirm.ts
 init_src();
 init_io();
@@ -2653,13 +3510,14 @@ async function runCapability(match, args, options) {
     printCommandHelp(options.io, capability);
     return 0;
   }
-  const session = resolveSession({
+  const session = await resolveSessionAsserted({
     env: options.env,
     storeOptions: options.storeOptions,
     profileName: options.profileName,
     apiUrlOverride: options.apiUrlOverride,
     apiKeyOverride: options.apiKeyOverride,
-    fetch: options.fetch
+    fetch: options.fetch,
+    assertOrgOverride: options.assertOrgOverride
   });
   const input = buildCapabilityInput(capability, match.rest, args);
   const json = options.jsonFlag || session.resolved.defaultOutput === "json";
@@ -2676,7 +3534,7 @@ async function runCapability(match, args, options) {
 }
 async function run(argv, options = {}) {
   const io = options.io ?? createNodeIo();
-  const env = options.env ?? io.env;
+  const env = overlayRepoEnv(options.env ?? io.env, { cwd: process.cwd() }).env;
   const args = parseArgs(argv);
   const { positionals } = args;
   const jsonFlag = flagBool(args, "json");
@@ -2685,6 +3543,7 @@ async function run(argv, options = {}) {
   const profileName = flagValue(args, "profile");
   const apiUrlOverride = flagValue(args, "api-url");
   const apiKeyOverride = flagValue(args, "api-key");
+  const assertOrgOverride = flagValue(args, "assert-org");
   if (flagBool(args, "version")) {
     const { KHOTAN_ADAPTER_VERSION: KHOTAN_ADAPTER_VERSION2 } = await Promise.resolve().then(() => (init_src(), exports_src));
     io.out(`${KHOTAN_ADAPTER_VERSION2}
@@ -2708,7 +3567,12 @@ async function run(argv, options = {}) {
       if (match2 && isOperationCapability(match2.capability)) {
         printCommandHelp(io, match2.capability);
       } else {
-        printTopLevelHelp(io);
+        const group2 = groupCommands(topic);
+        if (group2.length > 0) {
+          printGroupHelp(io, topic, group2);
+        } else {
+          printTopLevelHelp(io);
+        }
       }
       return 0;
     }
@@ -2724,6 +3588,26 @@ async function run(argv, options = {}) {
       const cwd = flagValue(args, "dir") ?? process.cwd();
       return runInit({ io, cwd, client: clientRaw, force: flagBool(args, "force"), json: jsonFlag });
     }
+    if (first === "status") {
+      if (helpFlag) {
+        errLine(io, "Usage: khotan status [--write [path]] [--dir <path>] [--json]");
+        return 0;
+      }
+      const session = await resolveSessionAsserted({
+        env,
+        storeOptions: options.storeOptions,
+        profileName,
+        apiUrlOverride,
+        apiKeyOverride,
+        fetch: options.fetch,
+        assertOrgOverride
+      });
+      const json = jsonFlag || session.resolved.defaultOutput === "json";
+      const writeValue = flagValue(args, "write");
+      const write = flagBool(args, "write");
+      const writeDir = write ? flagValue(args, "dir") ?? (writeValue && writeValue !== "true" ? writeValue : undefined) ?? process.cwd() : undefined;
+      return await runStatus({ session, io, json, writeDir });
+    }
     if (first === "mcp" && positionals[1] === "serve") {
       const launcher = options.startMcpServer ?? (async (deps) => {
         const { serveMcp: serveMcp2 } = await Promise.resolve().then(() => (init_serve(), exports_serve));
@@ -2736,7 +3620,8 @@ async function run(argv, options = {}) {
         fetch: options.fetch,
         profileName,
         apiUrlOverride,
-        apiKeyOverride
+        apiKeyOverride,
+        assertOrgOverride
       });
     }
     if (first === "login") {
@@ -2769,13 +3654,14 @@ async function run(argv, options = {}) {
         errLine(io, positionals[1] === "upload" ? "Usage: khotan files upload <localPath> [--name <n>] [--folder-id <id>] [--folder-path <p>] [--content-type <t>]" : "Usage: khotan files download <fileId> --output <path>");
         return 0;
       }
-      const session = resolveSession({
+      const session = await resolveSessionAsserted({
         env,
         storeOptions: options.storeOptions,
         profileName,
         apiUrlOverride,
         apiKeyOverride,
-        fetch: options.fetch
+        fetch: options.fetch,
+        assertOrgOverride
       });
       const json = jsonFlag || session.resolved.defaultOutput === "json";
       if (positionals[1] === "upload") {
@@ -2808,9 +3694,15 @@ async function run(argv, options = {}) {
         yes,
         profileName,
         apiUrlOverride,
-        apiKeyOverride
+        apiKeyOverride,
+        assertOrgOverride
       });
     }
+    const group = groupCommands(positionals);
+    if (group.length > 0) {
+      printGroupHelp(io, positionals, group);
+      return 0;
+    }
     errLine(io, `Unknown command "${positionals.join(" ")}". Run \`khotan help\` for usage.`);
     return 1;
   } catch (error) {