@limecloud/cli 0.8.0 → 0.10.0

package/src/diagnose.mjs

@@ -0,0 +1,99 @@
+import { commandOperations, inspectSchema } from "./commands.mjs";
+import { attachContractCompatibility } from "./compatibility.mjs";
+import { prepareManagement, validateJSON } from "./management.mjs";
+import { CLIError } from "./protocol.mjs";
+import { currentLocalizer, message, translate } from "./i18n.mjs";
+import { displayText, outputOptions, success } from "./output.mjs";
+
+// 任务适配只组织现有公开GET，不创建另一份应用、客户端或授权事实。
+export async function prepareLoginDiagnosis(contract, parsed, env) {
+  const environment = parsed.get("environment");
+  const limit = parsed.get("limit") ?? "20";
+  const cursor = parsed.get("cursor");
+  if (!["sandbox", "production"].includes(environment) || !/^(?:[1-9]|[1-4][0-9]|50)$/.test(limit) ||
+      cursor && (cursor.length > 1024 || /[\x00-\x20\x7f]/.test(cursor))) {
+    throw new CLIError("invalid_arguments", message("diagnosis.usage"));
+  }
+  const scope = { space_id: parsed.get("space-id"), application_id: parsed.get("app-id"), environment };
+  const catalogue = commandOperations(contract);
+  const operations = ["open.login_diagnosis.get"].map(command => {
+    const operation = catalogue.find(item => item.command === command);
+    if (!operation || operation.method !== "GET" || operation["x-lime-cli-origin"] !== "api") {
+      throw new CLIError("invalid_contract", message("diagnosis.contractUnavailable"));
+    }
+    return operation;
+  });
+  const flags = new Map(parsed.flags);
+  flags.set("limit", [limit]);
+  const inputs = [];
+  for (const operation of operations) inputs.push(await prepareManagement(contract, operation,
+    { flags, get: name => flags.get(name)?.[0] }, env));
+  return { scope, operation: operations[0], input: inputs[0], limit: Number(limit), cursor: cursor ?? null };
+}
+
+export async function diagnoseLogin(plan, { contract, context, read, fetchCatalog, now = Date.now, signal } = {}) {
+  const started = new Date(now()).toISOString();
+  const report = { schema_version: 2, task: "application-login-diagnosis", status: "blocked", login_verified: false,
+    scope: { issuer: context.issuer, api_origin: context.apiOrigin, ...plan.scope },
+    started_at: started, observed_at: started,
+    coverage: { complete: false, common_snapshot: false, first_page: !plan.cursor, limit: plan.limit, returned: 0, next_cursor: null },
+    application: null, clients: [], checks: [], evidence: [], next_steps: [] };
+  const finish = () => { report.observed_at = new Date(now()).toISOString(); return report; };
+  const [method] = await attachContractCompatibility([inspectSchema(contract, [plan.operation.command])], contract,
+    { online: true, issuer: context.issuer, apiOrigin: context.apiOrigin, fetchCatalog, now, signal });
+  const compatibility = { operation_id: method._meta.operationId, contract_revision: method._meta.contract_revision, ...method._meta.compatibility };
+  const contractsMatch = compatibility.status === "matched";
+  report.contract_check = { check: "contracts", status: contractsMatch ? "observed" : "blocked",
+    message: translate(contractsMatch ? "diagnosis.contractsObserved" : "diagnosis.contractsBlocked"), details: [compatibility] };
+  if (!contractsMatch) return finish();
+  const transport = { operation_id: plan.operation.operationId, method: plan.operation.method,
+    url: context.apiOrigin + plan.input.path + (plan.input.query.size ? "?" + plan.input.query : ""),
+    contract_revision: compatibility.contract_revision, started_at: new Date(now()).toISOString() };
+  try {
+    signal?.throwIfAborted();
+    const response = await read(plan.operation, plan.input);
+    signal?.throwIfAborted();
+    try {
+      validateJSON(contract, plan.operation.responses["200"].content["application/json"].schema, response, "response");
+      const value = response.data;
+      if (value.scope.space_id !== plan.scope.space_id || value.scope.application_id !== plan.scope.application_id || value.scope.environment !== plan.scope.environment ||
+          value.application.id !== plan.scope.application_id || value.application.space_id !== plan.scope.space_id ||
+          value.clients.length > plan.limit || value.coverage.returned !== value.clients.length || value.coverage.limit !== plan.limit ||
+          value.coverage.first_page !== !plan.cursor || value.coverage.complete && (plan.cursor || value.coverage.next_cursor !== null) ||
+          value.coverage.next_cursor !== null && (!value.coverage.next_cursor || /[\x00-\x20\x7f]/.test(value.coverage.next_cursor))) throw new Error("invalid diagnosis scope or coverage");
+    } catch { throw new CLIError("invalid_response", message("diagnosis.invalidResponse")); }
+    transport.observed_at = new Date(now()).toISOString(); transport.status = "observed";
+    Object.assign(report, response.data, { scope: { ...report.scope, ...response.data.scope }, transport });
+    if (report.coverage.next_cursor) report.next_steps.push({ reason: "next_page", executable: "limecloud-cli", arguments: ["diagnose", "login",
+      "--issuer", context.issuer, "--api-origin", context.apiOrigin, ...(context.clientID ? ["--auth-client-id", context.clientID] : []),
+      "--space-id", plan.scope.space_id, "--app-id", plan.scope.application_id, "--environment", plan.scope.environment,
+      "--limit", String(plan.limit), "--cursor", report.coverage.next_cursor, "--locale", currentLocalizer().locale] });
+    report.next_steps.push({ reason: "login_guide", executable: "limecloud-cli", arguments: ["docs", "read", "oauth-clients", "--locale", currentLocalizer().locale] });
+    return report;
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    const code = error instanceof CLIError && /^[A-Za-z0-9_.:-]{1,80}$/.test(error.code) ? error.code : "source_unavailable";
+    report.transport = { ...transport, observed_at: new Date(now()).toISOString(), status: "unavailable", error_code: code,
+      ...(Number.isInteger(error.status) ? { http_status: error.status } : {}) };
+    report.checks.push({ check: "diagnosis", status: "unavailable", error_code: code, message: translate("diagnosis.sourceUnavailable", { code }) });
+    return finish();
+  }
+}
+
+export function writeDiagnosis(io, report, parsed) {
+  const options = outputOptions(parsed);
+  const checks = [report.contract_check, ...report.checks].filter(Boolean);
+  if (options.format === "json") { success(io, report, { ...options, identity: "user" }); return; }
+  if (options.format === "table") {
+    for (const line of [translate("diagnosis.context", { ...report.scope }), translate("diagnosis.targets", { ...report.scope }),
+      translate("diagnosis.conclusion", { status: report.status, observed: report.observed_at }), translate("diagnosis.observationOnly")]) {
+      io.stdout.write(displayText(line) + "\n");
+    }
+    success(io, checks, { ...options, fields: options.fields ?? ["check", "status", "message"], identity: "user" });
+    // 下一页仅提供结构化参数供人或宿主选择，不自动遍历或执行。
+    if (report.coverage.next_cursor) io.stdout.write(translate("diagnosis.nextCursor") + "\n" + displayText(report.coverage.next_cursor) + "\n");
+    return;
+  }
+  success(io, checks.map(check => ({ ...check, task: report.task, task_status: report.status, scope: report.scope,
+    observed_at: report.observed_at, login_verified: false, coverage: report.coverage, evidence: report.evidence, next_steps: report.next_steps })), { ...options, identity: "user" });
+}

package/src/group-task.mjs

@@ -0,0 +1,137 @@
+import { join } from "node:path";
+import { actionContract } from "./action-contracts.mjs";
+import { commandOperations } from "./commands.mjs";
+import { message, translate } from "./i18n.mjs";
+import { prepareManagement, validateJSON } from "./management.mjs";
+import { CLIError } from "./protocol.mjs";
+import { PrivateJSONStore } from "./storage.mjs";
+import { displayText, outputOptions, success } from "./output.mjs";
+
+const validID = value => typeof value === "string" && /^[A-Za-z0-9_-]{1,48}$/.test(value);
+const digest = value => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const actions = new Set(["prepare", "get", "execute", "receipt", "resolve"]);
+const referenceKeys = new Set(["schema_version", "issuer", "api_origin", "client_id", "application_id", "audience", "environment", "actor_id", "space_id", "preparation_id", "target_id", "execution_contract_revision", "confirmation_digest", "expires_at", "execute_attempted_at"]);
+const fail = key => { throw new CLIError("invalid_arguments", message(key)); };
+
+export async function prepareGroupTask(contract, parsed, env, readInput) {
+  const [task, resource, action, ...extra] = parsed.positionals;
+  const id = parsed.get("preparation-id"), space = parsed.get("space-id");
+  if (task !== "task" || resource !== "group" || !actions.has(action) || extra.length || !validID(space) ||
+      (action === "prepare" ? id !== undefined : !validID(id)) ||
+      (action === "execute" ? !digest(parsed.get("confirm")) : parsed.get("confirm") !== undefined) ||
+      (action !== "prepare" && parsed.get("data") !== undefined)) fail("groupTask.usage");
+  const operation = commandOperations(contract).find(item => item.command === `open.group_change.${action}`);
+  if (!operation) throw new CLIError("invalid_contract", message("groupTask.contractUnavailable"));
+  const flags = new Map([["space-id", [space]], ...(id ? [["preparation-id", [id]]] : [])]);
+  if (action === "prepare") flags.set("data", [parsed.get("data")]);
+  if (action === "execute") flags.set("data", [JSON.stringify({ preview_token: parsed.get("confirm") })]);
+  if (action === "resolve") flags.set("data", ["{}"]);
+  const input = await prepareManagement(contract, operation, { flags, get: name => flags.get(name)?.[0] }, env, readInput);
+  return { action, id, space, operation, input, confirmation: parsed.get("confirm") };
+}
+
+function reference(prepared, context) {
+  return { schema_version: 1, issuer: context.issuer, api_origin: context.apiOrigin,
+    client_id: prepared.invocation.client_id, application_id: prepared.invocation.application_id,
+    audience: prepared.invocation.audience, environment: prepared.invocation.environment,
+    actor_id: prepared.actor_id, space_id: prepared.space_id, preparation_id: prepared.id,
+    target_id: prepared.command.group.id, execution_contract_revision: prepared.invocation.contract_revision,
+    confirmation_digest: prepared.preview.token, expires_at: prepared.expires_at };
+}
+
+function recovery(ref) {
+  const base = ["task", "group"];
+  const scope = ["--space-id", ref.space_id, "--preparation-id", ref.preparation_id];
+  return { preparation_id: ref.preparation_id, operation_key: ref.preparation_id,
+    issuer: ref.issuer, api_origin: ref.api_origin, client_id: ref.client_id, actor_id: ref.actor_id,
+    space_id: ref.space_id, execution_contract_revision: ref.execution_contract_revision,
+    commands: Object.fromEntries(["get", "receipt", "resolve"].map(action => [action, ["limecloud-cli", ...base, action, ...scope,
+      "--issuer", ref.issuer, "--api-origin", ref.api_origin, "--auth-client-id", ref.client_id]])),
+    message: translate("groupTask.recoveryHint") };
+}
+
+function present(value) {
+  if (Array.isArray(value)) return value.map(present);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key === "token" ? "confirmation_digest" : key, present(item)]));
+}
+
+// 本地只保存恢复定位和发送标记，不缓存命令、影响、组状态、回执或任何认证凭据。
+// 每次执行先重新读取原准备；发送前持久标记，一次尝试后只允许查询/终结，不自动重发。
+export async function executeGroupTask(plan, { contract, context, call, referenceDirectory,
+  referenceStore = id => new PrivateJSONStore(join(referenceDirectory, `${id}.json`), { durable: true }), now = Date.now } = {}) {
+  if (!context.apiOrigin || !context.clientID) throw new CLIError("group_context_required", message("groupTask.contextRequired"));
+  const catalogue = commandOperations(contract);
+  async function invoke(operation, input, beforeSend) {
+    const response = await call(operation, input, beforeSend);
+    try { validateJSON(contract, operation.responses["200"].content["application/json"].schema, response, "response"); }
+    catch { throw new CLIError("invalid_response", message("groupTask.invalidResponse")); }
+    return response.data;
+  }
+  function verifyPrepared(value, id) {
+    if (value.id !== id || value.space_id !== plan.space || value.invocation.client_id !== context.clientID || value.invocation.audience !== context.apiOrigin ||
+        value.preview.preparation_id !== id || value.preview.target_id !== value.command.group.id || value.command.kind !== "group" ||
+        Date.parse(value.expires_at) - Date.parse(value.prepared_at) !== 300000) {
+      throw new CLIError("invalid_response", message("groupTask.invalidResponse"));
+    }
+    return reference(value, context);
+  }
+  function result(ref, key, value) {
+    return { task: "member-group-change", [key]: present(value), recovery: recovery(ref),
+      message: translate(key === "preparation" ? "groupTask.reviewHint" : "groupTask.resultHint") };
+  }
+  if (plan.action === "prepare") {
+    const prepared = await invoke(plan.operation, plan.input);
+    if (!validID(prepared.id)) throw new CLIError("invalid_response", message("groupTask.invalidResponse"));
+    const ref = verifyPrepared(prepared, prepared.id), store = referenceStore(prepared.id);
+    try { await store.withLock(async () => {
+      if (await store.read()) throw new CLIError("group_reference_conflict", message("groupTask.referenceConflict"));
+      await store.write(ref);
+    }); } catch (error) { error.recovery = recovery(ref); throw error; }
+    return result(ref, "preparation", prepared);
+  }
+  const store = referenceStore(plan.id);
+  return store.withLock(async () => {
+    let ref = await store.read();
+    if (ref && (Object.keys(ref).some(key => !referenceKeys.has(key)) || ["client_id", "application_id", "actor_id", "space_id", "preparation_id", "target_id"].some(key => !validID(ref[key])) ||
+        !digest(ref.confirmation_digest) || !/^sha256:[a-f0-9]{64}$/.test(ref.execution_contract_revision) || !Number.isFinite(Date.parse(ref.expires_at)) ||
+        ref.execute_attempted_at !== undefined && !Number.isFinite(Date.parse(ref.execute_attempted_at)) ||
+        ref.schema_version !== 1 || ref.issuer !== context.issuer || ref.api_origin !== context.apiOrigin || ref.client_id !== context.clientID ||
+        ref.space_id !== plan.space || ref.preparation_id !== plan.id)) throw new CLIError("group_reference_conflict", message("groupTask.referenceConflict"));
+    if (plan.action === "execute" && !ref) throw new CLIError("group_reference_required", message("groupTask.referenceRequired"));
+    if (plan.action === "execute" && ref.execute_attempted_at) {
+      const error = new CLIError("group_execution_already_attempted", message("groupTask.alreadyAttempted"));
+      error.recovery = recovery(ref); throw error;
+    }
+    const readOperation = catalogue.find(item => item.command === "open.group_change.get");
+    if (!readOperation) throw new CLIError("invalid_contract", message("groupTask.contractUnavailable"));
+    const prepared = await invoke(readOperation, { path: readOperation.path.replace("{spaceID}", plan.space).replace("{preparationID}", plan.id), query: new URLSearchParams() });
+    const current = verifyPrepared(prepared, plan.id);
+    if (ref && Object.keys(current).some(key => current[key] !== ref[key])) throw new CLIError("group_reference_conflict", message("groupTask.referenceConflict"));
+    if (!ref) { ref = current; await store.write(ref); }
+    if (plan.action === "get") return result(ref, "preparation", prepared);
+    if (plan.action === "execute" && (plan.confirmation !== ref.confirmation_digest ||
+        ref.execution_contract_revision !== actionContract(contract, plan.operation).contract_revision)) {
+      const error = new CLIError("group_confirmation_changed", message("groupTask.confirmationChanged"));
+      error.recovery = recovery(ref); throw error;
+    }
+    try {
+      const value = await invoke(plan.operation, plan.input, plan.action === "execute" ? async () => {
+        ref = { ...ref, execute_attempted_at: new Date(now()).toISOString() };
+        await store.write(ref);
+      } : undefined);
+      const receipt = plan.action === "resolve" ? value.receipt : value;
+      if (receipt && (receipt.operation_key !== plan.id || receipt.preview.preparation_id !== plan.id || receipt.preview.token !== ref.confirmation_digest || receipt.result.id !== ref.target_id) ||
+          plan.action === "resolve" && value.cancellation && value.cancellation.operation_key !== plan.id) throw new CLIError("invalid_response", message("groupTask.invalidResponse"));
+      return result(ref, plan.action === "resolve" ? "resolution" : "receipt", value);
+    } catch (error) { error.recovery = recovery(ref); throw error; }
+  });
+}
+
+export function writeGroupTask(io, value, parsed) {
+  const options = outputOptions(parsed);
+  if (options.format !== "table") { success(io, value, { ...options, identity: "user" }); return; }
+  // 核对表不截断完整命令、影响或恢复引用，避免通用80列裁剪隐藏风险。
+  const rows = Object.entries(value).map(([key, item]) => `${displayText(key)}  ${displayText(item)}`);
+  io.stdout.write(`${translate("groupTask.tableHeading")}\n${rows.join("\n")}\n`);
+}

package/src/knowledge.mjs

@@ -0,0 +1,171 @@
+import { readFile } from "node:fs/promises";
+import { currentLocalizer, defaultLocale, message, translate } from "./i18n.mjs";
+import { CLIError, issuerOrigin } from "./protocol.mjs";
+import { outputOptions, success } from "./output.mjs";
+import { fetchPublicJSON } from "./public-json.mjs";
+
+const articleID = /^[a-z0-9-]{1,80}$/;
+const revisionID = /^sha256:[a-f0-9]{64}$/;
+const publicOrigin = "https://open.limeai.run";
+const fail = key => { throw new CLIError("invalid_arguments", message(key)); };
+const loadPublicBundle = async () => JSON.parse(await readFile(new URL("../dist/knowledge.json", import.meta.url), "utf8"));
+
+// 仅读取公开部署，无认证头、Cookie、重定向、自动登录或持久缓存。
+export async function fetchPublicKnowledge(url, { signal } = {}) {
+  try {
+    return await fetchPublicJSON(url, { signal });
+  } catch (error) {
+    if (signal?.aborted) throw error;
+    throw new CLIError("knowledge_unavailable", message("knowledge.unavailable"));
+  }
+}
+
+function validateArticle(article, requestedLocale, body) {
+  if (!article || !articleID.test(article.id) || typeof article.title !== "string" || typeof article.summary !== "string" ||
+    article.visibility !== "public" || article.lifecycle !== "published" || !revisionID.test(article.revision) ||
+    article.requested_locale !== requestedLocale || ![requestedLocale, defaultLocale].includes(article.locale) ||
+    article.fallback !== (article.locale !== requestedLocale) || !["guide", "tutorial", "api", "client", "cli"].includes(article.group) || !Array.isArray(article.sections) ||
+    !Array.isArray(article.related_operations) || article.related_operations.length > 256 ||
+    new Set(article.related_operations).size !== article.related_operations.length || !article.related_operations.every(id => typeof id === "string" && /^[a-z][a-z0-9_]{0,199}$/.test(id)) ||
+    !article.sections.every(section => /^[a-z0-9-]{1,100}$/.test(section.id) && typeof section.title === "string") ||
+    body && typeof article.markdown !== "string") throw new CLIError("knowledge_invalid", message("knowledge.invalid"));
+  try {
+    const source = new URL(article.source_url);
+    if (source.href !== `${publicOrigin}/docs/${article.id}?locale=${article.locale}`) throw new Error("source");
+  } catch { throw new CLIError("knowledge_invalid", message("knowledge.invalid")); }
+  return article;
+}
+
+function snapshotMetadata(snapshot, locale, body = false) {
+  if (!snapshot || snapshot.schema_version !== 1 || snapshot.visibility !== "public" || snapshot.locale !== locale ||
+    typeof snapshot.software_version !== "string" || !revisionID.test(snapshot.revision) || !Array.isArray(snapshot.articles) || snapshot.articles.length > 5000) {
+    throw new CLIError("knowledge_invalid", message("knowledge.invalid"));
+  }
+  const ids = new Set();
+  for (const article of snapshot.articles) {
+    validateArticle(article, locale, body);
+    if (ids.has(article.id)) throw new CLIError("knowledge_invalid", message("knowledge.invalid"));
+    ids.add(article.id);
+  }
+  return snapshot;
+}
+
+export async function loadBundledKnowledge({ loadBundle = loadPublicBundle, locale = currentLocalizer().locale } = {}) {
+  let bundle;
+  try { bundle = await loadBundle(); } catch { throw new CLIError("knowledge_unavailable", message("knowledge.unavailable")); }
+  return snapshotMetadata(bundle?.snapshots?.find(item => item.locale === locale), locale, true);
+}
+
+export async function attachSchemaKnowledge(schema, options = {}) {
+  let snapshot;
+  try { snapshot = await loadBundledKnowledge(options); }
+  catch (error) {
+    if (!["knowledge_unavailable", "knowledge_invalid"].includes(error.code)) throw error;
+    // 知识是补充资料；缺失不改写或阻断仍然有效的本地动作合同。
+    const unavailable = method => ({ ...method, _meta: { ...method._meta, knowledge: {
+      status: "unavailable", distribution: "bundled", current_online: false, error_code: error.code, articles: [],
+    } } });
+    return Array.isArray(schema) ? schema.map(unavailable) : unavailable(schema);
+  }
+  const attach = method => ({ ...method, _meta: { ...method._meta, knowledge: {
+    status: "available",
+    distribution: "bundled", current_online: false, software_version: snapshot.software_version, snapshot_revision: snapshot.revision,
+    articles: snapshot.articles.filter(article => article.related_operations.includes(method._meta.operationId)).map(article => ({
+      id: article.id, title: article.title, revision: article.revision, source_url: article.source_url,
+      locale: article.locale, requested_locale: article.requested_locale, fallback: article.fallback,
+    })),
+  } } });
+  return Array.isArray(schema) ? schema.map(attach) : attach(schema);
+}
+
+function numberFlag(parsed, key, fallback, min, max) {
+  const raw = parsed.get(key);
+  if (raw === undefined) return fallback;
+  if (!/^(0|[1-9][0-9]*)$/.test(raw)) fail("knowledge.pagination");
+  const value = Number(raw);
+  if (!Number.isSafeInteger(value) || value < min || value > max) fail("knowledge.pagination");
+  return value;
+}
+
+function selectSection(article, id) {
+  if (!article.sections.some(section => section.id === id)) throw new CLIError("knowledge_section_not_found", message("knowledge.sectionNotFound"));
+  const index = article.sections.findIndex(section => section.id === id);
+  const start = article.markdown.indexOf(`<a id="${id}"></a>`);
+  const next = article.sections[index + 1];
+  const end = next ? article.markdown.indexOf(`<a id="${next.id}"></a>`, start + 1) : article.markdown.length;
+  if (start < 0 || end < start) throw new CLIError("knowledge_invalid", message("knowledge.invalid"));
+  return { ...article, section: id, markdown: article.markdown.slice(start, end).trim() + "\n" };
+}
+
+function safeMarkdown(value) {
+  // 保留换行和制表符，移除终端控制序列（含OSC链接）及C0/C1字符。
+  return value.replace(/\x1b\][\s\S]*?(?:\x07|\x1b\\)/g, "").replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, "");
+}
+
+export async function executeKnowledge(parsed, { io, signal, cliVersion, fetchKnowledge = fetchPublicKnowledge,
+  loadBundle = loadPublicBundle } = {}) {
+  const [, action, target, ...extra] = parsed.positionals;
+  const get = parsed.get;
+  const read = action === "read";
+  const commands = ["list", "search", "read"];
+  const knownAction = commands.includes(action);
+  const allowed = ["help", "json", "locale", ...(knownAction ? ["online", "offline", "docs-origin", "format", ...(read ? ["section", "revision"] : ["limit", "offset", "group", "fields"])] : [])];
+  for (const flag of parsed.flags.keys()) if (!allowed.includes(flag)) fail("knowledge.usage");
+  if (!knownAction) {
+    if (target || extra.length || action && !articleID.test(action)) fail("knowledge.usage");
+    success(io, { url: `${publicOrigin}/docs${action ? `/${action}` : ""}` }); return;
+  }
+  if (extra.length || read && !articleID.test(target ?? "") || action === "search" && (!target?.trim() || target.length > 256) || action === "list" && target ||
+    get("online") && get("offline") || get("docs-origin") && !get("online") || get("section") && !/^[a-z0-9-]{1,100}$/.test(get("section")) ||
+    get("revision") && !revisionID.test(get("revision"))) fail("knowledge.usage");
+  const markdown = read && (!get("format") && !get("json") || get("format") === "markdown");
+  if (markdown && get("json")) fail("knowledge.usage");
+  const output = markdown ? null : outputOptions(parsed);
+  if (read && output?.format !== "json" && !markdown) fail("knowledge.usage");
+  const limit = numberFlag(parsed, "limit", 10, 1, 50);
+  const offset = numberFlag(parsed, "offset", 0, 0, 5000);
+  if (get("group") && !["guide", "tutorial", "api", "client", "cli"].includes(get("group"))) fail("knowledge.usage");
+  const locale = currentLocalizer().locale;
+  const online = Boolean(get("online"));
+  const origin = online ? issuerOrigin(get("docs-origin") ?? publicOrigin) : publicOrigin;
+  let snapshot;
+  if (online) snapshot = snapshotMetadata(await fetchKnowledge(`${origin}/knowledge/v1/${locale}/index.json`, { signal }), locale);
+  else snapshot = await loadBundledKnowledge({ loadBundle, locale });
+  const provenance = { schema_version: 1, cli_version: cliVersion, software_version: snapshot.software_version,
+    snapshot_revision: snapshot.revision, distribution: online ? "online" : "bundled", current_online: online,
+    source_origin: origin, locale, visibility: "public", search_scope: online ? "metadata" : "article-body" };
+  if (!read) {
+    const terms = (target ?? "").trim().toLocaleLowerCase(locale).split(/\s+/u).filter(Boolean);
+    const matches = snapshot.articles.map(article => {
+      const title = `${article.id} ${article.title}`.toLocaleLowerCase(locale);
+      const summary = article.summary.toLocaleLowerCase(locale);
+      const headings = article.sections.map(section => section.title).join(" ").toLocaleLowerCase(locale);
+      const body = online ? "" : article.markdown?.toLocaleLowerCase(locale) ?? "";
+      const score = terms.reduce((sum, term) => sum + (title.includes(term) ? 100 : summary.includes(term) ? 20 : headings.includes(term) ? 10 : body.includes(term) ? 1 : 0), 0);
+      return { article, score, matches: (!get("group") || article.group === get("group")) && terms.every(term => `${title} ${summary} ${headings} ${body}`.includes(term)) };
+    }).filter(value => value.matches).sort((a, b) => b.score - a.score).map(value => value.article);
+    const rows = matches.slice(offset, offset + limit).map(({ markdown: body, sections, ...article }) => article);
+    if (output.format !== "json") io.stderr?.write(translate("knowledge.snapshotNotice", { version: snapshot.software_version, revision: snapshot.revision,
+      distribution: translate(online ? "knowledge.distributionOnline" : "knowledge.distributionBundled") }) + "\n");
+    success(io, rows, { ...output, meta: { ...provenance, total: matches.length, offset, limit,
+      next_offset: offset + rows.length < matches.length ? offset + rows.length : null, truncated: offset > 0 || offset + rows.length < matches.length } }); return;
+  }
+  const indexed = snapshot.articles.find(article => article.id === target);
+  if (!indexed) throw new CLIError("knowledge_not_found", message("knowledge.notFound"));
+  let article = online ? await fetchKnowledge(`${origin}/knowledge/v1/${locale}/articles/${target}.json`, { signal }) : indexed;
+  if (online && article?.schema_version !== 1) throw new CLIError("knowledge_invalid", message("knowledge.invalid"));
+  validateArticle(article, locale, true);
+  if (article.id !== target || article.revision !== indexed.revision || get("revision") && article.revision !== get("revision")) {
+    throw new CLIError("knowledge_revision_changed", message("knowledge.revisionChanged"));
+  }
+  if (get("section")) article = selectSection(article, get("section"));
+  if (markdown) {
+    const metadata = { id: article.id, revision: article.revision, locale: article.locale, requested_locale: locale,
+      fallback: article.fallback, source_url: article.source_url, updated_at: article.updated_at, visibility: article.visibility,
+      lifecycle: article.lifecycle, applicability: article.applicability, related_operations: article.related_operations, software_version: snapshot.software_version,
+      distribution: provenance.distribution, current_online: online, snapshot_revision: snapshot.revision, cli_version: cliVersion,
+      source_origin: origin, ...(article.section ? { section: article.section } : {}) };
+    io.stdout.write(safeMarkdown("---\n" + Object.entries(metadata).map(([key, value]) => `${key}: ${JSON.stringify(value)}`).join("\n") + "\n---\n\n" + article.markdown));
+  } else success(io, article, { ...output, meta: provenance });
+}

package/src/locales/en.json

@@ -1,5 +1,11 @@
 {
-  "arguments.docsUsage": "Use docs [article-slug]",
+  "protocol.contractRequired": "The server requires an exact action contract revision (ACTION_CONTRACT_REQUIRED). This request did not invoke the domain action. Review the current contract and update the caller from a trusted source; no retry was performed.",
+  "protocol.contractChanged": "The server rejected a changed action contract (ACTION_CONTRACT_CHANGED). This request did not invoke the domain action. Preserve any earlier operation with an unknown result; review the contract and trusted updates without automatically replaying it.",
+  "protocol.contractUnavailable": "The server could not determine this action contract (ACTION_CONTRACT_UNAVAILABLE). This request did not invoke the domain action. Check public discovery before an explicit new request; no retry was performed.",
+  "arguments.managedHeader": "Lime-Action-Contract is supplied by the CLI from its own action contract and cannot be overridden.",
+  "compatibility.writeDifferent": "The current contract for {{command}} differs. No write was sent. Review schema {{command}} --online and trusted CLI/Skill updates. Do not automatically replay an earlier operation with an unknown result.",
+  "compatibility.writeAbsent": "The target does not advertise {{command}}. No write was sent. Check the selected deployment and current schema; this does not establish whether you have permission.",
+  "compatibility.writeUnknown": "The current contract for {{command}} could not be verified. No write was sent. Check public contract discovery; no update, sign-in or retry was performed.",
   "arguments.publicClientRequired": "Provide the already registered public client with --client-id",
   "arguments.configUsage": "Use config init, config show or config set <issuer|api_origin|client_id|scope> <value>",
   "arguments.tooMany": "Too many arguments; use --help",
@@ -116,12 +122,12 @@
   "arguments.requiredPathParameter": "Required path parameter: {{name}}",
   "arguments.unknownSchema": "Unknown schema path: {{target}}; start with schema",
   "protocol.apiFailed": "API request failed: {{code}} (HTTP {{status}})",
-  "help.overview": "limecloud-cli — Lime Cloud CLI (@limecloud/cli)\n\nUsage:\n  limecloud-cli <command> [resource] [method] [flags]\n  limecloud-cli identity +login | +whoami\n  limecloud-cli identity token exchange --data <json>\n  limecloud-cli api <METHOD> <contract-path> [--params <json>] [--data <json>]\n  limecloud-cli schema [service.resource.method | service resource method]\n\nIdentity:\n  identity    Public OAuth / OpenID Connect operations and +shortcuts\n\nCLI management:\n  install     Install this CLI and guide first-time setup\n  config      init | show | set: local public-client configuration\n  auth        login | status | whoami | refresh | logout | scopes | check\n  whoami      Show the local effective identity and token state\n  doctor      Check local configuration and contract (--offline; no network)\n  docs        Print a documentation URL\n\nAPI tools:\n  api         Call a contract HTTP path; list/schema/call also accept operationId\n  schema      Inspect public methods, parameters, responses and authentication\n\n",
+  "help.overview": "limecloud-cli — Lime Cloud CLI (@limecloud/cli)\n\nUsage:\n  limecloud-cli <command> [resource] [method] [flags]\n  limecloud-cli identity +login | +whoami\n  limecloud-cli identity token exchange --data <json>\n  limecloud-cli api <METHOD> <contract-path> [--params <json>] [--data <json>]\n  limecloud-cli schema [service.resource.method | service resource method]\n\nIdentity:\n  identity    Public OAuth / OpenID Connect operations and +shortcuts\n\nCLI management:\n  install     Install this CLI and guide first-time setup\n  config      init | show | set: local public-client configuration\n  auth        login | status | whoami | refresh | logout | scopes | check\n  whoami      Show the local effective identity and token state\n  doctor      Check local configuration and contract (--offline; no network)\n  diagnose    Read-only application login configuration diagnosis\n  task        Prepare, precisely confirm and recover one member-group change\n  skills      Inspect and export optional public method candidates; never install automatically\n  docs        List, search and read public knowledge; print Web URLs\n\nAPI tools:\n  api         Call a contract HTTP path; list/schema/call also accept operationId\n  schema      Inspect public methods, parameters, responses and authentication\n\n",
   "help.apiFlags": "API flags:\n  --params JSON       Query JSON; supports @file or - for stdin\n  --data JSON         OAuth form or API JSON body; supports @file or - for stdin\n  --dry-run           Print a redacted request without executing or changing state\n  --format FORMAT     json (default), ndjson, table or csv\n  --fields PATHS      Comma-separated data field paths\n  --json              Shorthand for --format json\n  --param name=value  Repeat a non-sensitive protocol parameter\n  --param-env name=ENV Read a sensitive protocol parameter from an environment variable\n  --header name=value Set a contract-declared HTTP header\n  --file PATH         Binary body for image/png methods; - reads stdin\n  --show-secrets      Explicitly include API response credentials in stdout\n\n",
   "help.connectionFlags": "Connection flags:\n  --issuer ORIGIN     Auth origin (HTTPS; HTTP only on loopback)\n  --api-origin ORIGIN Explicit business API origin, bound to the saved login\n  --client-id ID      Already registered sign-in client ID\n  --auth-client-id ID Override the OAuth client context for a business API call\n\n  --locale TAG        Output language (also LIMECLOUD_LOCALE, LC_ALL, LC_MESSAGES, LANG)\n\nRun limecloud-cli <command> --help or schema identity before calling a method.\n",
   "help.auth": "Usage: auth <login|status|whoami|refresh|logout|scopes|check> [flags]\n\nlogin --client-id ID [--scope \"openid profile\"] [--installation-id ID --space-id ID]\n      --no-wait: return a verification URL and save private pending state\n      --resume: complete the saved authorization without exposing its device code\nstatus: local state; whoami: remote UserInfo; refresh: rotate stored credentials\nlogout [--local-only]: revoke, then forget; --local-only forgets without revocation\nscopes: read supported OIDC scopes and report locally granted scopes\ncheck --scope SCOPES: check unexpired local granted scopes (no network)\n\nAuth commands use an already registered public client. --dry-run previews login, refresh, logout or scopes without execution.\n",
   "help.config": "Usage:\n  config init\n  config init --issuer ORIGIN --client-id ID [--api-origin ORIGIN] [--scope SCOPES]\n  config show\n  config set <issuer|api_origin|client_id|scope> <value>\n\nConfiguration stores public client settings only. Business API origin must be explicit; changing it requires a new login binding.\n",
-  "help.schema": "Usage: schema [identity | identity.resource | identity.resource.method | identity resource method]\nReturns public inputSchema, outputSchema and _meta derived from the OpenAPI contract. Risk: read.\n",
+  "help.schema": "Usage: schema [service[.resource[.method]] | service resource method]\nReturns inputSchema, outputSchema, local contract revision and related public guides.\n\nDefault / --offline: local contract only; no network or credentials.\n--online: check the selected issuer and API deployment with public metadata.\n  --issuer ORIGIN      Canonical issuer; otherwise current CLI settings\n  --api-origin ORIGIN  Required API target for management methods\n\n_meta.compatibility.status is not-checked / matched / different / absent / unknown. matched compares an exact action contract; it grants no permission and is not an execution gate. Knowledge links remain bundled. No update, browser launch or business call is performed.\n",
   "help.identityShortcuts": "Identity shortcuts:\n  identity +login [--scope SCOPES] [--no-wait | --resume]\n  identity +whoami\n\n",
   "help.typedMethods": "Typed API commands:\n{{methods}}\n\nUse schema {{service}}.<resource>.<method> for parameters. --dry-run executes nothing.\n",
   "help.services": "Available services: {{services}}\n",
@@ -149,5 +155,63 @@
   "install.promptAPIOrigin": "Business API origin (leave empty for identity-only use) [{{value}}]: ",
   "install.promptClientID": "Already registered public CLI Client ID [{{value}}]: ",
   "install.promptLogin": "Start device authorization now? You must confirm it in your browser (y/N) [{{value}}]: ",
-  "install.pathHint": "Add {{directory}} to PATH to run limecloud-cli from any terminal."
+  "install.pathHint": "Add {{directory}} to PATH to run limecloud-cli from any terminal.",
+  "knowledge.usage": "Use docs [article-slug], docs list, docs search <query>, or docs read <article-id>. Use --help for supported options.",
+  "knowledge.pagination": "--limit must be 1–50 and --offset 0–5000.",
+  "knowledge.unavailable": "Public knowledge is unavailable. Build or reinstall the CLI for its bundled snapshot, or explicitly use --online with a trusted documentation deployment. No fallback was executed.",
+  "knowledge.invalid": "The public knowledge format is unsupported or invalid. Update from the trusted source; no content was executed.",
+  "knowledge.notFound": "Article not found in this public knowledge snapshot.",
+  "knowledge.sectionNotFound": "Section not found in this article.",
+  "knowledge.revisionChanged": "The article revision changed. Read the current index and review the source before continuing; no task was replayed.",
+  "help.docs": "Usage:\n  limecloud-cli docs [article-slug]                 Print a Web URL\n  limecloud-cli docs list [--group GROUP]           List public guides\n  limecloud-cli docs search \"QUERY\"                Bounded keyword search\n  limecloud-cli docs read ARTICLE [--section ID]    Read Markdown in this host\n\nOptions:\n  --locale LOCALE      Registered language; English fallback\n  --online             Explicitly read the documentation deployment\n  --docs-origin URL    Trusted HTTPS origin (only with --online)\n  --offline            Use the bundled public snapshot (the default)\n  --limit N            1–50 results, default 10 (list/search)\n  --offset N           0–5000 (list/search)\n  --revision SHA256    Require an exact article revision (read)\n  --json               Structured data with provenance\n  --format FORMAT      json/ndjson/table/csv for list/search; markdown/json for read\n\nNo login, Skills installation, browser launch or business operation is performed. Bundled knowledge does not prove current online capability. Online search matches metadata; bundled search also matches body text.\n",
+  "knowledge.snapshotNotice": "Public knowledge: {{distribution}}, software {{version}}, {{revision}}. Guidance does not prove current online capability.",
+  "compatibility.apiOriginRequired": "Provide the target API origin with --api-origin or current CLI settings before checking management contracts. No request was sent.",
+  "compatibility.usage": "Use schema [method] --online [--issuer ORIGIN] [--api-origin ORIGIN], or --offline. Target options require --online.",
+  "knowledge.distributionOnline": "online documentation deployment",
+  "knowledge.distributionBundled": "bundled snapshot (offline)",
+  "help.relatedKnowledge": "Related public guides (bundled snapshot, offline; not an online capability check):\n{{articles}}\n",
+  "help.knowledgeUnavailable": "The bundled guide snapshot is unavailable. This is still the local action contract; online compatibility has not been checked. Build or reinstall from a trusted source for related guides.\n",
+  "help.diagnose": "Usage: diagnose login --space-id ID --app-id ID --environment sandbox|production [--limit 1..50] [--cursor CURSOR]\n\nRead-only application login configuration diagnosis. Uses the exact configured issuer and API origin. Compares public contracts, then reads the application and one client page through the delegated API. No login, update, browser, writes or automatic pagination.\nUse --format json|table|csv|ndjson. ok:true means a report was produced; inspect status and coverage. Configuration observations do not verify a real login.\n",
+  "diagnosis.usage": "Use diagnose login --space-id ID --app-id ID --environment sandbox|production [--limit 1..50] [--cursor CURSOR].",
+  "diagnosis.contractUnavailable": "This local contract does not provide the shared read-only login diagnosis action.",
+  "diagnosis.contractsObserved": "The public diagnosis action contract matches; the original owner still checks each source against current access.",
+  "diagnosis.contractsBlocked": "A current action contract could not be matched. No business data was requested.",
+  "diagnosis.invalidResponse": "The source did not return the declared response for this scope.",
+  "diagnosis.sourceUnavailable": "Source unavailable ({{code}}); its result remains unchecked.",
+  "diagnosis.context": "Space: {{space_id}}  Application: {{application_id}}  Environment: {{environment}}",
+  "diagnosis.conclusion": "Report: {{status}}  Observed: {{observed}}",
+  "diagnosis.observationOnly": "Read-only configuration observations; separate source reads do not share a snapshot. Real login is unverified.",
+  "diagnosis.nextCursor": "Next cursor (continue explicitly with the same scope):",
+  "columns.check": "Check",
+  "columns.status": "Status",
+  "columns.message": "Message",
+  "diagnosis.targets": "Issuer: {{issuer}}  API: {{api_origin}}",
+  "help.task": "Usage: limecloud-cli task group prepare --space-id ID --data @change.json\n       limecloud-cli task group get|receipt|resolve --space-id ID --preparation-id ID\n       limecloud-cli task group execute --space-id ID --preparation-id ID --confirm DIGEST\nReview the complete original preparation before confirming. One execution attempt is recorded locally before sending; recover by the original ID instead of repeating execution.\n",
+  "groupTask.usage": "Use task group prepare --space-id ID --data JSON, get|receipt|resolve --space-id ID --preparation-id ID, or execute with those IDs and --confirm followed by the exact confirmation digest. No replacement command, --yes, projection or implicit confirmation is supported.",
+  "groupTask.contractUnavailable": "The bundled member-group task contract is unavailable.",
+  "groupTask.contextRequired": "Configure an explicit API origin and controlled authentication Client ID before running this task.",
+  "groupTask.invalidResponse": "The member-group response does not match the original task contract or invocation binding.",
+  "groupTask.referenceConflict": "The saved recovery reference does not match this invocation or the original preparation. Preserve it and verify the original issuer, API, client, actor and organization.",
+  "groupTask.referenceRequired": "Read the original preparation with task group get to save its recovery reference before confirming execution.",
+  "groupTask.alreadyAttempted": "An execution attempt is already recorded for this original key. Read its receipt or explicitly resolve the original operation; this task will not repeat execution.",
+  "groupTask.confirmationChanged": "The confirmation digest or execution contract differs from the saved original preparation. Check or resolve the original operation before preparing a new change.",
+  "groupTask.reviewHint": "Review the actor, organization, invocation, original values, frozen command, full impact and expiry. Only after explicit review, pass this preparation ID and confirmation_digest to task group execute --confirm. The digest does not prove human consent or grant authority.",
+  "groupTask.recoveryHint": "Use the original ID to read the preparation or receipt, or explicitly resolve it. A missing receipt is not proof of non-commit. Never replace the key or automatically repeat execution, login, update or open a browser.",
+  "groupTask.resultHint": "This is the original Owner result. Recheck current authority for later actions; the local reference is not a permission or business-state cache.",
+  "groupTask.tableHeading": "Field  Complete task value (values wrap; no truncation)",
+  "help.skills": "Usage: limecloud-cli skills list | inspect ID [--online --issuer ISSUER --api-origin API_ORIGIN] | export ID --host codex|skill --output-dir NEW_DIRECTORY --digest EXACT_DIGEST\nInspection is offline by default; --online compares every required action with the selected deployment without credentials. Authorization, provenance, withdrawal and host loading remain separate. The default wrapper is codex. Export does not install, enable, update or load a host plugin.\n",
+  "skills.loginTitle": "Application login configuration diagnosis",
+  "skills.loginDescription": "Guide one read-only Lime application login configuration diagnosis inside an existing Agent host. Actual login and repairs are separate tasks.",
+  "skills.groupTitle": "One organization member group change",
+  "skills.groupDescription": "Guide one group creation, rename or status change with full preparation review, explicit confirmation and original-result recovery. Membership, roles and bulk changes are separate tasks.",
+  "skills.usage": "Use skills list, skills inspect ID [--online --issuer ISSUER --api-origin API_ORIGIN], or skills export ID --output-dir NEW_DIRECTORY --digest EXACT_DIGEST; optional --host codex|skill selects a wrapper. No automatic installation or host changes.",
+  "skills.invalidArtifact": "The bundled public Skill artifact is incomplete or its integrity does not match. Obtain the CLI from a trusted source; no artifact was exported.",
+  "skills.candidateNotice": "Bundled public candidate only. Integrity matches this installed CLI; current online compatibility, provenance, withdrawal and host loading have not been verified. Inspect the complete files before separately selecting native installation or import.",
+  "skills.onlineNotice": "Only the candidate's required action contracts were compared with the selected deployment at the recorded time. Review every action and its expiry; matching is not authorization, provenance, withdrawal clearance or evidence that this method is installed or loaded. No installation, update or business action was performed.",
+  "skills.exportedNotice": "Complete candidate exported. This did not install, enable, update or load a method, change host settings or execute artifact scripts. Native plugin installation/update belongs to the selected host manager; current session loading is unknown.",
+  "skills.notInstallation": "Export to a new ordinary directory outside Agent discovery/configuration directories. Use the actual host manager for an explicitly selected installation or update.",
+  "skills.unsafeDirectory": "The export parent must be an existing physical directory without symbolic-link ancestors.",
+  "skills.confirmationChanged": "The selected artifact digest does not match. Inspect this exact wrapper and candidate before exporting.",
+  "skills.destinationExists": "The export destination already exists. Select a new directory; existing files and local changes are never overwritten.",
+  "skills.notFound": "This public method and wrapper are not included in the installed CLI. No download, installation or update was attempted."
 }