larkit 0.0.0-stage → 0.1.0

package/scripts/verify-console.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import "../src/shared/quiet.js";
+import process from "node:process";
+import { checkAuth } from "../src/auth/service.js";
+import {
+  enableBotWs,
+  getCredentials,
+  grantScopes,
+  listApps,
+  publishVersion,
+} from "../src/console/client.js";
+import { probeOpenApi } from "../src/probe/openapi.js";
+
+const profileArg = process.argv.find((arg) => arg.startsWith("--profile="));
+const profile = profileArg ? profileArg.slice(10) : "geren";
+
+const auth = await checkAuth({ profile });
+console.log("auth:", auth.ok, auth.profile, auth.user?.name || auth.hint || auth.error);
+if (!auth.ok) process.exit(1);
+
+const apps = await listApps({ profile, limit: 30 });
+console.log("apps:", apps.ok, apps.total);
+if (!apps.ok || !apps.apps.length) process.exit(1);
+
+const app =
+  apps.apps.find((item) => item.status === 2 && item.abilities?.includes("bot")) ||
+  apps.apps[0];
+console.log("selected app:", app.app_id, app.name, "status=" + app.status);
+
+const cred = await getCredentials({ appId: app.app_id, profile });
+console.log("credentials:", cred.ok, "secret_len=" + (cred.app_secret?.length || 0));
+if (!cred.ok) process.exit(1);
+
+const probe = await probeOpenApi({
+  appId: cred.app_id,
+  appSecret: cred.app_secret,
+  method: "GET",
+  path: "/im/v1/chats",
+  query: { page_size: 1 },
+});
+console.log("openapi probe:", probe.status, probe.code, probe.msg, probe.log_id || "");
+
+const wsPlan = await enableBotWs({ appId: app.app_id, profile, dryRun: true });
+console.log("bot ws dry-run:", wsPlan.ok, wsPlan.calls?.length || 0, "calls");
+
+const scopePlan = await grantScopes({
+  appId: app.app_id,
+  scopes: ["im:message"],
+  profile,
+  dryRun: true,
+});
+console.log(
+  "scope dry-run:",
+  scopePlan.ok,
+  "resolved=" + (scopePlan.plan?.resolved?.map((s) => s.name).join(",") || ""),
+  "missing=" + (scopePlan.plan?.missing?.join(",") || ""),
+);
+
+const publishPlan = await publishVersion({ appId: app.app_id, profile, dryRun: true });
+console.log("publish dry-run:", publishPlan.ok, publishPlan.plan?.steps?.length || 0, "steps");

package/scripts/verify-index.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import "../src/shared/quiet.js";
+import process from "node:process";
+import { searchTruth, getProtocolEntry, readSlice, truthStats } from "../src/truth/search.js";
+import { TRUTH_DB, FORMATTED_DIR } from "../src/shared/paths.js";
+
+const queries = process.argv.slice(2).filter((x) => !x.startsWith("--"));
+const list = queries.length
+  ? queries
+  : ["chart_spec", "card_link", "PUT_MESSAGE", "PUSH_MESSAGES"];
+
+let failed = 0;
+const stats = truthStats();
+console.log(JSON.stringify({ truth_db: TRUTH_DB, formatted_dir: FORMATTED_DIR, stats }, null, 2));
+
+for (const query of list) {
+  const result = searchTruth({ query, scope: "all", limit: 5 });
+  const ok = result.results.length > 0;
+  const fast = result.elapsed_ms < 50;
+  if (!ok || !fast) failed++;
+  console.log(
+    `\n${ok ? "PASS" : "FAIL"} ${fast ? "fast" : "SLOW"} ${result.elapsed_ms}ms  query=${JSON.stringify(query)}  hits=${result.results.length}`,
+  );
+  for (const hit of result.results.slice(0, 3)) {
+    if (hit.kind === "protocol") {
+      console.log(
+        `  protocol cmd=${hit.cmd} ${hit.name} ${hit.request_type || ""} schema=${(hit.schema || "").slice(0, 100)}`,
+      );
+    } else {
+      console.log(
+        `  ${hit.kind} ${hit.file_path}:${hit.line_number ?? hit.line_start} ${hit.anchor_type || hit.section || hit.title || ""} ${(hit.literal || "").slice(0, 90)}`,
+      );
+    }
+  }
+  if (query === list[0]) {
+    const first = result.results[0];
+    if (first && !first.kind.includes("protocol")) {
+      const slice = readSlice({
+        filePath: first.file_path,
+        lineNumber: first.line_number || first.line_start || 1,
+        context: 3,
+        maxLines: 12,
+      });
+      console.log(
+        `  slice ${slice.file_path}:${slice.range.start}-${slice.range.end} (${slice.lines.length} lines)`,
+      );
+    }
+  }
+}
+
+const protocol = getProtocolEntry("PUT_MESSAGE");
+console.log(`\nprotocol lookup PUT_MESSAGE: ${protocol.length} entr${protocol.length === 1 ? "y" : "ies"}`);
+if (!protocol.length) failed++;
+
+if (failed) {
+  console.error(`\n${failed} verification check(s) failed`);
+  process.exit(1);
+}
+console.log("\nall index checks passed");

package/scripts/verify-mcp.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import "../src/shared/quiet.js";
+import { spawn } from "node:child_process";
+import process from "node:process";
+
+const child = spawn(process.execPath, ["bin/larkit-mcp.js"], {
+  cwd: process.cwd(),
+  stdio: ["pipe", "pipe", "pipe"],
+  env: { ...process.env, LARKIT_MCP_TEST: "1" },
+});
+
+let buffer = "";
+const pending = new Map();
+let nextId = 1;
+let stderr = "";
+const received = [];
+
+child.stderr.on("data", (chunk) => {
+  stderr += chunk.toString();
+  if (stderr.length > 8000) stderr = stderr.slice(-8000);
+});
+
+child.stdout.on("data", (chunk) => {
+  buffer += chunk.toString();
+  let index;
+  while ((index = buffer.indexOf("\n")) >= 0) {
+    const line = buffer.slice(0, index).trim();
+    buffer = buffer.slice(index + 1);
+    if (!line) continue;
+    let message;
+    try {
+      message = JSON.parse(line);
+    } catch {
+      console.error("non-JSON stdout:", line.slice(0, 300));
+      continue;
+    }
+    received.push(message);
+    if (message.id && pending.has(message.id)) {
+      pending.get(message.id)(message);
+      pending.delete(message.id);
+    }
+  }
+});
+
+function send(method, params, timeout = 60_000) {
+  const id = nextId++;
+  const payload = { jsonrpc: "2.0", id, method, params };
+  child.stdin.write(`${JSON.stringify(payload)}\n`);
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      reject(new Error(`timeout waiting for ${method}`));
+    }, timeout);
+    pending.set(id, (message) => {
+      clearTimeout(timer);
+      if (message.error) reject(new Error(JSON.stringify(message.error)));
+      else resolve(message.result);
+    });
+  });
+}
+
+function notify(method, params = {}) {
+  child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params })}\n`);
+}
+
+function textOf(result) {
+  return result?.content?.map((item) => item.text).join("\n") || "";
+}
+
+async function main() {
+  const init = await send("initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "larkit-verify", version: "1.0.0" },
+  });
+  console.log("initialize:", init.serverInfo?.name, init.serverInfo?.version);
+  notify("notifications/initialized");
+
+  const list = await send("tools/list", {});
+  console.log(
+    "tools:",
+    list.tools.map((tool) => tool.name).join(", "),
+  );
+  if (list.tools.length !== 6) {
+    throw new Error(`expected 6 tools, got ${list.tools.length}`);
+  }
+
+  const search = await send("tools/call", {
+    name: "lark_truth_search",
+    arguments: { query: "chart_spec", scope: "all", limit: 3 },
+  });
+  const searchJson = JSON.parse(textOf(search));
+  console.log(
+    "truth_search:",
+    `${searchJson.results.length} hits, ${searchJson.elapsed_ms}ms, first=${searchJson.results[0]?.file_path}:${searchJson.results[0]?.line_start || searchJson.results[0]?.line_number}`,
+  );
+  if (!searchJson.results.length) throw new Error("truth search returned no hits");
+
+  const firstCode = searchJson.results.find((hit) => hit.kind === "code") || {
+    file_path: "verified_truths/card-json-2.0-official.md",
+    line_number: 10,
+  };
+  const slice = await send("tools/call", {
+    name: "lark_truth_inspect",
+    arguments: {
+      action: "read_slice",
+      file_path: firstCode.file_path,
+      line_number: firstCode.line_number || 1,
+      context: 3,
+      max_lines: 20,
+    },
+  });
+  const sliceJson = JSON.parse(textOf(slice));
+  console.log(
+    "truth_inspect:",
+    `${sliceJson.file_path}:${sliceJson.range?.start}-${sliceJson.range?.end}, ${sliceJson.lines?.length} lines`,
+  );
+  if (!sliceJson.lines?.length) throw new Error("read_slice returned no lines");
+
+  const who = await send("tools/call", {
+    name: "lark_auth",
+    arguments: { action: "whoami", profile: "geren" },
+  });
+  const whoJson = JSON.parse(textOf(who));
+  console.log("auth whoami:", whoJson.ok, whoJson.profile, whoJson.user?.name || "");
+
+  const doc = await send("tools/call", {
+    name: "lark_doc",
+    arguments: { action: "search", query: "图表", limit: 3 },
+  });
+  const docJson = JSON.parse(textOf(doc));
+  console.log("doc search:", docJson.ok, docJson.total, docJson.docs?.[0]?.title || "");
+  if (!docJson.docs?.length) throw new Error("doc search returned no docs");
+  const docRead = await send("tools/call", {
+    name: "lark_doc",
+    arguments: { action: "read", path: docJson.docs[0].path, limit: 20 },
+  });
+  const docReadJson = JSON.parse(textOf(docRead));
+  console.log("doc read:", docReadJson.ok, docReadJson.total_lines, "lines");
+
+  const consoleList = await send("tools/call", {
+    name: "lark_console",
+    arguments: { action: "list_apps", profile: "geren", limit: 50 },
+  });
+  const consoleJson = JSON.parse(textOf(consoleList));
+  console.log("console list_apps:", consoleJson.ok, consoleJson.total, consoleJson.apps?.[0]?.app_id || "");
+  if (!consoleJson.apps?.length) throw new Error("console list_apps returned no apps");
+  const testApp = consoleJson.apps[0].app_id;
+  const probeApp =
+    (process.env.LARKIT_VERIFY_APP_ID &&
+      consoleJson.apps.find(
+        (app) => app.app_id === process.env.LARKIT_VERIFY_APP_ID,
+      )) ||
+    consoleJson.apps.find((app) => app.status === 2) ||
+    consoleJson.apps[0];
+
+  const consoleDry = await send("tools/call", {
+    name: "lark_console",
+    arguments: { action: "enable_bot_ws", app_id: testApp, profile: "geren", dry_run: true },
+  });
+  const consoleDryJson = JSON.parse(textOf(consoleDry));
+  console.log("console dry-run ws:", consoleDryJson.ok, consoleDryJson.calls?.length || 0, "calls");
+
+  const credResult = await send("tools/call", {
+    name: "lark_console",
+    arguments: { action: "get_credentials", app_id: probeApp.app_id, profile: "geren" },
+  });
+  const cred = JSON.parse(textOf(credResult));
+  console.log("console credentials:", cred.ok, cred.app_id, "secret_len=" + (cred.app_secret?.length || 0));
+
+  const openapi = await send("tools/call", {
+    name: "lark_probe",
+    arguments: {
+      mode: "openapi",
+      app_id: cred.app_id,
+      app_secret: cred.app_secret,
+      method: "GET",
+      path: "/im/v1/chats",
+      query: { page_size: 1 },
+    },
+  }, 60_000);
+  const openapiJson = JSON.parse(textOf(openapi));
+  console.log("openapi probe:", openapiJson.ok, openapiJson.status, openapiJson.code, openapiJson.ms || openapiJson.elapsed_ms);
+
+  const probe = await send("tools/call", {
+    name: "lark_probe",
+    arguments: {
+      mode: "client",
+      command: "PUSH_MESSAGES",
+      profile: "geren",
+      transport: "ws",
+      wait_push: true,
+      timeout: 5000,
+    },
+  }, 30_000);
+  const probeJson = JSON.parse(textOf(probe));
+  console.log(
+    "client probe:",
+    `handshake=${probeJson.handshake} ok=${probeJson.ok} events=${probeJson.events?.length || 0}`,
+  );
+
+  console.log("\nMCP verification passed");
+  if (stderr.trim()) console.log("server stderr tail:\n", stderr.trim().split("\n").slice(-8).join("\n"));
+}
+
+try {
+  await main();
+} catch (error) {
+  console.error("MCP verification failed:", error);
+  if (stderr.trim()) console.error("stderr:\n", stderr.trim().slice(-3000));
+  process.exitCode = 1;
+} finally {
+  child.kill("SIGTERM");
+  setTimeout(() => process.exit(process.exitCode || 0), 200);
+}

package/skills/larkit/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: larkit
+description: >
+  Feishu/Lark full-stack development and reverse-engineering with a local truth engine. Use when the
+  task involves Feishu/Lark official docs, cards (卡片/JSON 2.0/chart_spec/card_link), messages,
+  bots or event subscriptions, WebSocket long connections, app creation and publishing in the
+  developer console (open.feishu.cn/app), permission scopes, tenant_access_token, OpenAPI probing,
+  client private protocol commands (PUT_MESSAGE/PUSH_MESSAGES/2020 commands), protobuf schemas,
+  hidden fields, error codes (99991672/9499), or reading reverse-engineered web/Electron client code.
+  Provides MCP tools `lark_doc`, `lark_truth_search`, `lark_truth_inspect`, `lark_auth`,
+  `lark_console`, `lark_probe` and the equivalent `larkit` CLI.
+---
+
+# Larkit — Feishu full-stack truth engine
+
+Larkit answers Feishu questions from **evidence**, not guesses: 4800+ official docs, 2020 client
+protocol commands, 237k code anchors from the web/Electron client, and a `verified_truths`
+knowledge base that grows as you verify things. It can also create/configure/publish real apps in
+the developer console and send real API/protocol probes.
+
+## 1. Preflight (do this once per session)
+
+```bash
+larkit status --json          # fastest: truth.db? code corpus? skill? MCP config?
+larkit doctor                 # auth profiles, tokens, Chrome, install state
+```
+
+- `truth.installed=false` → have the user run `npx larkit` (or `larkit init`).
+- `code.installed=false` → the truth pack is half-extracted; rerun `larkit init` (the code corpus
+  ships in the same archive, there is nothing optional to add).
+- If the MCP tools are not mounted, use the CLI equivalents in `references/tools.md`; they return
+  the same JSON.
+
+Never invent Feishu behavior when the truth engine or the official docs can answer it.
+
+## 2. Route the question
+
+| User asks | Start with | Then |
+| --- | --- | --- |
+| "Is card field X supported?" / card JSON 2.0 | `lark_truth_search(scope="verified")` | `lark_doc search` → `read` → code anchors |
+| "What does this error code mean?" | `lark_truth_search(scope="all")` | doc error-code pages → `lark_probe` |
+| "Create a bot that receives events over WebSocket" | `references/playbooks.md` §B | `lark_auth` → `lark_console` → `lark_probe` |
+| "Why does this OpenAPI call fail?" | `lark_probe(mode="openapi")` | read `code/msg/log_id`, then scope/CSRF checks |
+| "What is command N / PUT_MESSAGE?" | `lark_truth_search(scope="protocol")` | `read_slice` on protocol docs or client code |
+| "Show me the client implementation" | search `scope="web"`/`"electron"` | `read_slice` with `mode="function"` |
+| "Configure/publish an app" | `lark_console` (`dry_run` first) | `references/console.md` |
+| "Log me in / switch account" | `lark_auth(action="list")` | `check` → QR login → `check` |
+| "Set up larkit / install the skill" | §6 below | |
+
+Full playbooks: `references/playbooks.md`. Console API recipes and failure matrix:
+`references/console.md`. Tool/CLI/env reference: `references/tools.md`.
+
+## 3. Token discipline (hard rules)
+
+1. **Always try `scope="verified"` first.** If a prior conclusion exists, stop there.
+2. `limit <= 10`; results contain coordinates + a 320-char snippet, not whole files.
+3. Never read a formatted client file end-to-end. `search` → `read_slice`.
+4. `read_slice`: prefer `mode="function"`, `max_lines <= 120`.
+5. Docs: `lark_doc search` → `read` with `offset/limit`; use returned `headings` to jump.
+6. Probes: `GET` before `POST`; `dry_run=true` before every console write; `wait_push=true` for
+   listener-only protocol commands.
+7. `save_verified` only with evidence (probe output/log_id, doc URL, `file:line`). No secrets,
+   cookies or tokens in the knowledge base.
+8. Never echo credentials or auth headers back to the user.
+
+## 4. Standard loop
+
+```
+lark_auth check
+  → lark_truth_search(scope=verified)
+  → lark_doc search/read
+  → lark_truth_search(scope=protocol|web|electron)
+  → lark_truth_inspect(read_slice)
+  → lark_probe(openapi|client)
+  → lark_truth_inspect(save_verified)
+  → lark_console(dry_run → apply)
+  → lark_probe re-verify
+```
+
+Stop as soon as the answer is certain. Each step exists only to cover the previous step's gap.
+
+## 5. Evidence boundaries
+
+- Desktop client main process is a native binary (`feishu`/`libiron`); the corpus covers renderer,
+  preload, JSSDK, worker and protocol assets, not native main-process logic.
+- `read_slice` paths are relative to `formatted/` (web/electron) or `verified_truths/`.
+- i18n bundles are not indexed; search specific keys if needed.
+- Feishu internal console APIs and private protocol routes drift between client versions. Record
+  what you verified, with the client/doc version, in `verified_truths`.
+- Official doc endpoints and console APIs are rate-limited; back off instead of retrying blindly.
+
+## 6. Installing / repairing larkit (when the user asks)
+
+```bash
+npx larkit                     # init on first run, status afterwards
+npx larkit init --channel      # (re)install from the official truth channel
+npx larkit init --pack=<manifest.json|dir|.tar.gz>   # offline / pinned install
+npx larkit init --from-assets --deb=./feishu-linux.deb --web-dump=./feishu-web-dump
+# ↑ 构建资产不随包分发，需自备 deb + web dump；常规安装用上面两条命令即可
+npx larkit status              # verify truth.db / skill / CLI / MCP
+npx larkit update              # refresh outdated pieces
+npx larkit skills install      # reinstall the agent skill
+npx larkit pack verify <manifest.json>   # maintainers: verify a truth pack
+```
+
+Layout: `~/.larkit/{data/truth.db, verified_truths, cli, install.json, mcp.json}`. The MCP client
+config is written to `~/.larkit/mcp.json`; the skill lands in existing agent skill directories
+(`~/.agents/skills/larkit`, `~/.claude/skills/larkit`) or `--target=`/`--project`.
+
+## 7. When a tool fails
+
+| Symptom | Action |
+| --- | --- |
+| `truth.db not found` | `npx larkit` (or `larkit init`) |
+| `file not found: formatted/...` | `larkit init` (corpus ships with the truth pack) |
+| `needs_login` / `9499` | `lark_auth(action="login")` then poll `login_status`; or `import` cookies |
+| `99991672` | missing scope → `lark_console grant_scopes` → re-probe |
+| `command: N not found` | re-check cmd/kind with `lark_truth_search(scope="protocol")` |
+| `PullFeedGroups invalid request` | read operations belong on OpenAPI, not the private gateway |
+| MCP tool missing | use the CLI (`larkit search/inspect/doc/console/probe`) |

package/skills/larkit/references/console.md

@@ -0,0 +1,86 @@
+# Developer console (`open.feishu.cn/app`) — recipes and failure matrix
+
+## Session / CSRF
+
+- Read the active profile from `~/.larkit/credentials.json`.
+- Open `https://open.feishu.cn/app`, extract `window.csrfToken`, and merge response cookies
+  (`lark_oapi_csrf_token`, `sl_session`).
+- Headers: `Cookie`, `x-csrf-token`, `Origin`, `Referer`, `User-Agent`, `X-Timezone-Offset`.
+- `swp_csrf_token` alone → `9499 lark_oapi_csrf_token not exist in cookie`.
+- Mismatched header token → `9499 csrf token check fail`.
+
+## Internal HTTP recipes
+
+| Capability | Method / path | Key body |
+| --- | --- | --- |
+| App list | `POST /developers/v1/app/list` | `{Count,Cursor}` |
+| Create app | `POST /developers/v1/app/create` | `{name,desc,avatar,primaryLang,i18n,appSceneType}` |
+| App detail | `POST /developers/v1/app/:clientId` | `{}` |
+| Credentials | `POST /developers/v1/secret/:clientId` | `{}` → `data.secret` |
+| Update info | `POST /developers/v1/base_info/:clientId` | `{name,desc,i18n,avatar,languages}` |
+| All scopes | `POST /developers/v1/scope/all/:clientId` | `{clientId}` |
+| Apply scopes | `POST /developers/v1/scope/update/:clientId` | `{operation:"add",scopeIds:[],appScopeIDs:[...]}` |
+| Robot state | `POST /developers/v1/robot/:clientId` | `{clientId}` |
+| Enable robot | `POST /developers/v1/robot/switch/:clientId` | `{enable:true}` |
+| Event mode | `POST /developers/v1/event/switch/:clientId` | `{eventMode:4}` |
+| Card callback mode | `POST /developers/v1/callback/switch/:clientId` | `{callbackMode:4}` |
+| Version list | `POST /developers/v1/app_version/list/:clientId` | `{clientId}` |
+| Create version | `POST /developers/v1/app_version/create/:clientId` | `{appVersion,updateRemark,visibleSuggest,changeLog}` |
+| Commit release | `POST /developers/v1/publish/commit/:clientId/:versionId` | `{is_full_release}` |
+| Release | `POST /developers/v1/publish/release/:clientId/:versionId` | `{is_full_release}` |
+
+`eventMode=4` and `callbackMode=4` mean WebSocket long connection. `robot.cardCallbackMode` is the
+card request-address mode (1=Webhook), not the long-connection switch. Sending `callbackMode:4` to
+`/v2/robot/push_mode/switch` returns `ParamInvalid`.
+
+## HTTP first, browser fallback second
+
+Use plain HTTP when `lark_console` already has a recipe: milliseconds, dry-runnable, reproducible.
+Use `browser_fallback` when:
+
+- the internal endpoint is not covered (avatar upload, complex forms, review flows),
+- HTTP returns 9499/403 while the session is known-good,
+- you need to capture a new console API shape.
+
+Example:
+
+```
+lark_console({
+  action:"browser_fallback",
+  profile:"geren",
+  url:"https://open.feishu.cn/app",
+  wait_ms:3000,
+  actions:[
+    {type:"click_text", text:"创建应用"},
+    {type:"fill", fields:[{placeholder:"应用名称", value:"my-app"}]}
+  ],
+  screenshot:true,
+  record_as:"create_app"
+})
+```
+
+It reuses system Chrome (`CHROME_PATH`) with the larkit cookie and records `/developers/` +
+`/open-apis/` requests (sanitized headers, body shape, status) into
+`<data>/console-api-recipes.json`. Promote stable paths into `src/console/client.js`
+`DEFAULT_RECIPES`, then reproduce via `lark_console` HTTP.
+
+## Failure matrix
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `9499 lark_oapi_csrf_token not exist in cookie` | only `swp_csrf_token` sent | re-resolve session (`lark_auth check`), merge Set-Cookie |
+| `9499 csrf token check fail` | header/page/cookie token mismatch | use page `window.csrfToken` + `lark_oapi_csrf_token` |
+| `99991672` | app lacks scope | `grant_scopes` then re-probe |
+| WS `timeout waiting for cmd=6` | push command was sent instead of listened | use `wait_push:true` |
+| Gateway `PullFeedGroups invalid request` | read command not routed on the gateway | use OpenAPI for reads |
+| `command: N not found` | wrong command id/name or wrong transport | re-check via `lark_truth_search(scope=protocol)` |
+| `ParamInvalid` on `/v2/robot/push_mode/switch` | `callbackMode:4` misuse | use `/v1/callback/switch` |
+| `truth.db not found` | no truth source installed | `npx larkit` / `larkit init` |
+| `file not found` in `read_slice` | code corpus missing | `larkit init` |
+| `needs_login` from browser fallback | cookie expired | `lark_auth login` |
+
+## Evidence rules for console work
+
+- Writes have real side effects (apps, versions, releases). Always dry-run first.
+- Record `app_id`, action, `code`, `msg`, and verification fields in `save_verified`.
+- Never persist credentials, tokens, or full auth headers.