1688-cli 0.1.40 → 0.1.42

package/docs/specs/supplier-search.md

@@ -0,0 +1,179 @@
+# Supplier Search And Research
+
+This spec defines supplier discovery that starts from 1688's company search,
+not product-offer aggregation.
+
+## Goal
+
+Help a buyer or agent answer:
+
+- Which suppliers match this category keyword?
+- Which matching suppliers expose factory/trust/service signals?
+- Which suppliers deserve deeper `supplier inspect` enrichment?
+- Which suppliers should be contacted or compared after product discovery?
+
+## Source Boundary
+
+`supplier search` and `supplier research` must use 1688 company search. The
+known durable business endpoint from live probing is:
+
+```text
+search.1688.com/service/companySearchBusinessService
+```
+
+The page entry URL is:
+
+```text
+https://s.1688.com/company/company_search.htm?keywords=<GBK-percent-keyword>
+```
+
+Important encoding rule: `s.1688.com` expects GBK percent-encoded keywords.
+UTF-8 percent-encoding can search for mojibake and return zero or irrelevant
+results.
+
+Do not implement supplier discovery by running offer search and grouping
+offers by supplier. That is a different signal and can hide suppliers that are
+available in company search.
+
+## Commands
+
+### `supplier search`
+
+```bash
+1688 supplier search <keyword...> \
+  --max 20 \
+  --factory-only \
+  --province 广东 \
+  --city 深圳 \
+  --min-years 3 \
+  --min-repeat-rate 0.4 \
+  --min-response-rate 0.6 \
+  --enrich 0
+```
+
+Default behavior is supplier discovery only. `--enrich` is optional and
+defaults to `0`.
+
+### `supplier research`
+
+```bash
+1688 supplier research <keyword...> \
+  --max 20 \
+  --factory-only \
+  --enrich top:10 \
+  --jsonl
+```
+
+`supplier research` uses the same company-search source and scoring, but
+defaults to `--enrich top:10`. Enrichment calls `supplier inspect` with the
+company-search `memberId` when present.
+
+Supported export modes:
+
+- default: human table
+- JSON: automatic when stdout is piped or `--json` is used
+- `--jsonl`: one supplier item per line
+- `--csv`: comma-separated table
+- `--output <file>`: write JSONL/CSV to a file
+
+## Data Model
+
+Each item records source keyword/rank, normalized company-search supplier
+signals, score, and optional inspect enrichment:
+
+```ts
+{
+  sourceKeyword: string,
+  sourceRank: number,
+  globalRank: number,
+  supplier: {
+    companyName: string,
+    loginId: string | null,
+    memberId: string | null,
+    enterpriseId: string | null,
+    realUserId: string | null,
+    companyId: string | null,
+    shopUrl: string | null,
+    factoryCardUrl: string | null,
+    location: { province: string | null, city: string | null, address: string | null },
+    productionService: string | null,
+    tp: { serviceYears: number | null, memberLevel: string | null },
+    factory: {
+      isFactory: boolean,
+      factoryTag: string | null,
+      factoryLevel: string | null,
+      superFactory: boolean,
+      businessInspection: boolean,
+      factoryInspection: boolean,
+    },
+    service: {
+      compositeScore: number | null,
+      wwResponseRate: number | null,
+      repeatRate: number | null,
+    },
+    demand: {
+      payOrderCount3m: number | null,
+      payAmount3m: number | null,
+      fuzzyPayAmount3m: string | null,
+      saleQuantity3m: number | null,
+    },
+    tags: string[],
+    offersPreview: SupplierOfferPreview[],
+  },
+  score: number,
+  scoreBreakdown: Array<{ name: string, points: number, reason: string }>,
+  inspect?: SupplierInspectResult,
+  error?: { code: string, message: string },
+}
+```
+
+The top-level result includes:
+
+```ts
+source: {
+  kind: "company-search",
+  endpoint: "companySearchBusinessService",
+  offerAggregation: false,
+}
+```
+
+## Score V1
+
+The supplier score is a ranking aid, not a truth claim.
+
+- Company-search demand: up to 25 points from 3-month pay order count.
+- Supplier tenure: up to 15 points from service years.
+- Factory/trust: up to 20 points from factory/super-factory/inspection flags.
+- Service rates: up to 15 points from repeat and Wangwang response rates.
+- Composite score: up to 10 points.
+- Offer preview depth: up to 10 points from company-search previews.
+
+## Failure Semantics
+
+- Run-level failure: login expired, risk control, browser/network failure that
+  prevents company search from loading.
+- Empty result: company search loads but returns no supplier payload.
+- Item-level enrichment failure: `supplier inspect` fails for one supplier;
+  keep the supplier item and attach `error`.
+
+If a command exits with risk-control code `4`, retry once with `--headed` and
+solve the slider manually.
+
+## V1 Boundaries
+
+Live probing on 2026-06-04 showed the company search page emits
+`companySearchBusinessService` with `companyWithOfferLists`. A typical first
+page async response used `startIndex=6&asyncCount=14`; this likely means some
+top-page suppliers may be server-rendered before the async service response.
+V1 uses the stable browser-emitted business response and keeps the largest
+captured company-search payload. A later V2 can add HTML/DOM extraction for
+server-rendered supplier cards if we need exact 20-per-page completeness.
+
+## Verification
+
+- Unit tests cover GBK company-search URL construction.
+- Unit tests cover `companySearchBusinessService` parsing and offer previews.
+- Unit tests cover capture `keep: "largest"` behavior.
+- Unit tests cover enrich option parsing and CSV escaping.
+- `pnpm agent-context` refreshes generated command and JSON-shape indexes.
+- `pnpm agent-verify` is the default gate.

package/docs/specs/windows-cli-compatibility.md

@@ -0,0 +1,123 @@
+# Windows CLI Compatibility
+
+This spec defines the compatibility baseline required before `1688-cli` can
+claim normal Windows command-line support.
+
+## Goal
+
+Make the installed CLI and local development workflow work from Windows
+PowerShell and cmd.exe for read-only and daemon-backed commands.
+
+## Scope
+
+- npm package install and build scripts must not depend on Unix shell commands.
+- The daemon IPC path must work on Windows named pipes and avoid collisions
+  between different `BB1688_HOME` roots.
+- Runtime paths, temporary files, and diagnostics must use Node path helpers
+  instead of hard-coded Unix paths where they are part of normal command code.
+- `doctor` fix hints must be executable or meaningful on Windows.
+- README and command docs must show Windows alternatives where Unix examples
+  use `jq`, shell assignment, `/tmp`, or `~/.1688`.
+- Deterministic tests must cover the Windows-specific path and hint logic.
+- CI/package verification must include a Windows-compatible build and smoke
+  path, or document the exact manual Windows checks when CI is not available
+  in the current environment.
+
+## Non-Goals
+
+- Do not bypass 1688 login, slider verification, or risk control.
+- Do not automate Windows UI interaction beyond Playwright's existing browser
+  launch behavior.
+- Do not guarantee live 1688 network/search success in CI; CI checks should be
+  deterministic and use `doctor --no-launch` unless a real account/session is
+  explicitly supplied.
+- Do not change public JSON contracts except by additive diagnostic fields.
+- Do not add a new installer, native binary, or Windows service wrapper.
+
+## Behavior Contract
+
+### Build And Install
+
+`pnpm build` must run on Windows, macOS, and Linux. Any executable-bit fix must
+be implemented in Node and become a no-op on Windows.
+
+`scripts/postinstall.mjs` must:
+
+- locate the daemon pid file under `BB1688_HOME` when set
+- detect Windows Chrome install paths
+- invoke `npx.cmd` on Windows and `npx` elsewhere
+- print retry commands that are valid for the current platform
+
+### Daemon IPC
+
+Unix-like platforms continue to use `<BB1688_HOME>/daemon.sock`.
+
+Windows must use a named pipe:
+
+```text
+\\.\pipe\1688-cli-daemon-<stable-root-hash>
+```
+
+The hash must be stable for a given `BB1688_HOME`/default root and different
+for different roots so tests, profiles, and concurrent users do not collide.
+
+### Diagnostics
+
+`1688 doctor` must emit platform-appropriate fix hints:
+
+- Unix-like stale lock: `rm -rf "..."`
+- Windows stale lock: `Remove-Item -Recurse -Force "..."`
+- Unix-like writable-directory issue: `chmod u+w "..."`
+- Windows writable-directory issue: explain to grant write permission or choose
+  another `BB1688_HOME`
+
+The daemon protocol documentation and README must not describe the daemon as
+Unix-only.
+
+### Documentation
+
+README and command docs must include:
+
+- PowerShell examples using built-in `--get`/`--pick` instead of requiring `jq`
+- Windows output paths such as `$env:TEMP\suppliers.csv`
+- Windows local state paths using `%USERPROFILE%\.1688` or `$env:USERPROFILE`
+- named pipe note for daemon IPC on Windows
+
+## Acceptance Criteria
+
+- `pnpm build` succeeds without requiring `chmod` from the shell.
+- Unit tests cover Windows named pipe generation and platform-specific doctor
+  hints.
+- `pnpm test:unit` passes.
+- `pnpm agent-verify` passes.
+- `npm pack --dry-run` succeeds.
+- README and `docs/COMMANDS.md` no longer present Unix-only examples as the
+  only way to use JSON, output files, or local paths.
+- Manual Windows smoke checklist is documented:
+  - `npm i -g 1688-cli`
+  - `1688 --version`
+  - `1688 doctor --no-launch --json`
+  - `1688 daemon start`
+  - `1688 daemon status --json`
+  - `1688 daemon stop`
+  - `1688 search 雨伞 --max 1 --json`
+  - `1688 supplier search 键盘 --max 1 --json`
+
+## Verification Signals
+
+- Focused tests:
+  - `tests/paths.test.ts`
+  - `tests/doctor.test.ts` or existing doctor tests
+- Package checks:
+  - `pnpm build`
+  - `pnpm test:unit`
+  - `pnpm agent-verify`
+  - `npm pack --dry-run`
+- Manual Windows smoke checks listed above when a Windows machine/session is
+  available.
+
+## Open Questions
+
+- Whether to add GitHub Actions `windows-latest` is a repository operations
+  decision. The code/docs work should make that job straightforward, but adding
+  CI config is not required unless the repository already uses GitHub Actions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "1688-cli",
-  "version": "0.1.40",
+  "version": "0.1.42",
   "description": "1688.com CLI for humans, Codex, and Claude Code. Sourcing (search / image-search / offer / inquire) and orders (list / detail / logistics / seller chat).",
   "license": "MIT",
   "author": "nobodyjack",
@@ -36,7 +36,12 @@
   "files": [
     "dist",
     "scripts/postinstall.mjs",
+    "scripts/fix_bin_mode.mjs",
+    "scripts/generate_agent_context.mjs",
+    "scripts/check_agent_map.mjs",
+    "docs",
     "AGENTS.md",
+    "ARCHITECTURE.md",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -46,10 +51,15 @@
   },
   "scripts": {
     "dev": "tsx src/cli.ts",
-    "build": "tsc -p tsconfig.json && chmod +x dist/cli.js",
+    "build": "tsc -p tsconfig.json && node scripts/fix_bin_mode.mjs",
     "test": "vitest run",
+    "test:unit": "vitest run --exclude tests/doctor-live.test.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
+    "agent-context": "node scripts/generate_agent_context.mjs",
+    "docs-check": "node scripts/generate_agent_context.mjs --check",
+    "agent-map-check": "node scripts/check_agent_map.mjs",
+    "agent-verify": "pnpm typecheck && pnpm test:unit && pnpm docs-check && pnpm agent-map-check",
     "prepublishOnly": "pnpm build",
     "postinstall": "node scripts/postinstall.mjs"
   },

package/scripts/check_agent_map.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+async function read(relPath) {
+  return fs.readFile(path.join(root, relPath), 'utf8');
+}
+
+async function exists(relPath) {
+  try {
+    await fs.access(path.join(root, relPath));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const requiredFiles = [
+  'AGENTS.md',
+  'ARCHITECTURE.md',
+  'docs/AGENT_WORKING_PRINCIPLES.md',
+  'docs/README.md',
+  'docs/WORKFLOW.md',
+  'docs/COMMANDS.md',
+  'docs/JSON_CONTRACTS.md',
+  'docs/SAFETY.md',
+  'docs/RELIABILITY.md',
+  'docs/QUALITY_SCORE.md',
+  'docs/FEATURES.md',
+  'docs/specs/sourcing-research.md',
+  'docs/specs/seller-im.md',
+  'docs/specs/checkout-and-orders.md',
+  'docs/playbooks/add-command.md',
+  'docs/playbooks/change-json-output.md',
+  'docs/playbooks/debug-risk-control.md',
+  'docs/playbooks/add-mtop-capture.md',
+  'docs/playbooks/update-cli-release.md',
+  'docs/generated/command-index.md',
+  'docs/generated/module-map.md',
+  'docs/generated/test-index.md',
+  'docs/generated/json-shapes.md',
+];
+
+const missing = [];
+for (const file of requiredFiles) {
+  if (!(await exists(file))) missing.push(file);
+}
+
+const failures = [];
+if (missing.length) failures.push(`Missing files: ${missing.join(', ')}`);
+
+const agents = await read('AGENTS.md').catch(() => '');
+if (!agents.includes('pnpm agent-verify'))
+  failures.push('AGENTS.md must mention pnpm agent-verify.');
+if (!agents.includes('docs/playbooks'))
+  failures.push('AGENTS.md must route work to docs/playbooks.');
+if (!agents.includes('docs/AGENT_WORKING_PRINCIPLES.md'))
+  failures.push('AGENTS.md must link docs/AGENT_WORKING_PRINCIPLES.md.');
+if (agents.split('\n').length > 220)
+  failures.push('AGENTS.md should stay short (<= 220 lines).');
+
+const pkg = JSON.parse(await read('package.json'));
+for (const scriptName of ['agent-context', 'docs-check', 'agent-map-check', 'agent-verify']) {
+  if (!pkg.scripts?.[scriptName]) failures.push(`package.json missing script: ${scriptName}`);
+}
+
+const docsReadme = await read('docs/README.md').catch(() => '');
+for (const needle of [
+  'AGENT_WORKING_PRINCIPLES.md',
+  'COMMANDS.md',
+  'JSON_CONTRACTS.md',
+  'SAFETY.md',
+  'generated/',
+]) {
+  if (!docsReadme.includes(needle)) failures.push(`docs/README.md must link ${needle}.`);
+}
+
+if (failures.length) {
+  console.error(failures.join('\n'));
+  process.exit(1);
+}
+
+console.log('Agent map structure looks good.');

package/scripts/fix_bin_mode.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+export async function fixBinMode({
+  platform = process.platform,
+  target = path.join('dist', 'cli.js'),
+} = {}) {
+  if (platform === 'win32') {
+    return { changed: false, reason: 'windows-noop', target };
+  }
+  await fs.chmod(target, 0o755);
+  return { changed: true, reason: 'chmod-755', target };
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  await fixBinMode();
+}

package/scripts/generate_agent_context.mjs

@@ -0,0 +1,253 @@
+#!/usr/bin/env node
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const outDir = path.join(root, 'docs', 'generated');
+const checkOnly = process.argv.includes('--check');
+
+const rel = (p) => path.relative(root, p).replaceAll(path.sep, '/');
+const read = (p) => fs.readFile(path.join(root, p), 'utf8');
+
+async function exists(p) {
+  try {
+    await fs.access(path.join(root, p));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function walk(dir, predicate = () => true) {
+  const abs = path.join(root, dir);
+  const out = [];
+  async function visit(current) {
+    const entries = await fs.readdir(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git') continue;
+      const p = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await visit(p);
+      } else if (predicate(p)) {
+        out.push(p);
+      }
+    }
+  }
+  if (await exists(dir)) await visit(abs);
+  return out.sort((a, b) => rel(a).localeCompare(rel(b)));
+}
+
+function header(title) {
+  return `# ${title}\n\n_Generated by \`scripts/generate_agent_context.mjs\`._\n\n`;
+}
+
+function cleanDescription(raw) {
+  if (!raw) return '-';
+  return raw
+    .replace(/[`'"]/g, '')
+    .replace(/\s*\+\s*/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .replace(/\|/g, '\\|') || '-';
+}
+
+function compactList(items) {
+  return items.length ? items.map((x) => `\`${x}\``).join('<br>') : '-';
+}
+
+async function commandIndex() {
+  const cli = await read('src/cli.ts');
+  const re =
+    /(?:(?:const\s+([A-Za-z0-9_]+)\s*=\s*)?([A-Za-z0-9_]+)\s*\n\s*\.command\('([^']+)'\))/g;
+  const matches = [...cli.matchAll(re)];
+  const varToCommand = new Map();
+  const rows = [];
+
+  for (let i = 0; i < matches.length; i++) {
+    const m = matches[i];
+    const assignedVar = m[1];
+    const receiver = m[2];
+    const command = m[3];
+    const start = m.index ?? 0;
+    const end = matches[i + 1]?.index ?? cli.length;
+    const block = cli.slice(start, end);
+    const parent = receiver === 'program' ? '' : varToCommand.get(receiver) ?? receiver;
+    const full = parent ? `${parent} ${command}` : command;
+    if (assignedVar) varToCommand.set(assignedVar, full);
+
+    const descRaw = block.match(/\.description\(([\s\S]*?)\)\s*(?:\.|\n)/)?.[1];
+    const args = [...block.matchAll(/\.argument\(\s*(['"`])([^'"`]+)\1/g)].map(
+      (x) => x[2],
+    );
+    const opts = [
+      ...block.matchAll(/\.(?:requiredOption|option)\(\s*(['"`])([^'"`]+)\1/g),
+    ].map((x) => x[2]);
+    const source = block.match(/import\('\.\/commands\/([^']+)\.js'\)/)?.[1];
+    rows.push({
+      command: full,
+      source: source ? `src/commands/${source}.ts` : '-',
+      args,
+      opts,
+      description: cleanDescription(descRaw),
+    });
+  }
+
+  let out = header('Command Index');
+  out += '| Command | Source | Arguments | Options | Description |\n';
+  out += '|---|---|---|---|---|\n';
+  for (const row of rows) {
+    out += `| \`${row.command}\` | ${row.source === '-' ? '-' : `\`${row.source}\``} | ${compactList(
+      row.args,
+    )} | ${compactList(row.opts)} | ${row.description} |\n`;
+  }
+  return out;
+}
+
+async function moduleMap() {
+  const files = await walk('src', (p) => p.endsWith('.ts'));
+  const tests = await walk('tests', (p) => p.endsWith('.test.ts') || p.endsWith('.spec.ts'));
+  const dirs = new Map();
+  for (const file of files) {
+    const r = rel(file);
+    const parts = r.split('/');
+    const dir = parts.length > 2 ? `${parts[0]}/${parts[1]}` : parts[0];
+    const entry = dirs.get(dir) ?? { files: 0, tests: 0, notes: '-' };
+    entry.files++;
+    dirs.set(dir, entry);
+  }
+  for (const file of tests) {
+    const content = await fs.readFile(file, 'utf8');
+    const target = content.match(/from ['"]\.\.\/src\/([^/'"]+)/)?.[1];
+    if (target) {
+      const key = `src/${target}`;
+      const entry = dirs.get(key) ?? { files: 0, tests: 0, notes: '-' };
+      entry.tests++;
+      dirs.set(key, entry);
+    }
+  }
+
+  const notes = {
+    'src/commands': 'command executors and renderers',
+    'src/session': 'browser/session automation helpers',
+    'src/daemon': 'background daemon client/server/protocol',
+    'src/io': 'output, prompts, and errors',
+    'src/auth': 'login/session/cookie helpers',
+    'src/util': 'shared utilities',
+  };
+
+  let out = header('Module Map');
+  out += '| Directory | Source Files | Related Tests | Notes |\n';
+  out += '|---|---:|---:|---|\n';
+  for (const dir of [...dirs.keys()].sort()) {
+    const entry = dirs.get(dir);
+    out += `| \`${dir}\` | ${entry.files} | ${entry.tests} | ${notes[dir] ?? entry.notes} |\n`;
+  }
+  return out;
+}
+
+async function testIndex() {
+  const tests = await walk('tests', (p) => p.endsWith('.test.ts') || p.endsWith('.spec.ts'));
+  let out = header('Test Index');
+  out += '| Test File | Focus | Risk Notes |\n';
+  out += '|---|---|---|\n';
+  for (const file of tests) {
+    const content = await fs.readFile(file, 'utf8');
+    const name = path.basename(file).replace(/\.(test|spec)\.ts$/, '');
+    const risks = [];
+    if (/live|doctor-live|process\.env|BB1688|1688\s/.test(content + name))
+      risks.push('live/session-sensitive');
+    if (/playwright|BrowserContext|Page|page-state|risk-control/i.test(content))
+      risks.push('browser/page-state');
+    if (/fixture|jsonp|mtop|capture/i.test(content)) risks.push('fixture/parser');
+    out += `| \`${rel(file)}\` | ${name} | ${risks.join(', ') || '-'} |\n`;
+  }
+  return out;
+}
+
+function extractInterfaces(source, file) {
+  const lines = source.split('\n');
+  const interfaces = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(/^export interface ([A-Za-z0-9_]+)/);
+    if (!m) continue;
+    const name = m[1];
+    const keep =
+      /(Args|Opts|Result|Offer|Message|CartItem|Order|Sku|Price|Attribute|Package)/.test(
+        name,
+      );
+    if (!keep) continue;
+
+    const body = [];
+    let depth = 0;
+    for (let j = i; j < lines.length; j++) {
+      const line = lines[j];
+      if (j > i) body.push(line);
+      depth += (line.match(/\{/g) ?? []).length;
+      depth -= (line.match(/\}/g) ?? []).length;
+      if (j > i && depth <= 0) break;
+    }
+    const fields = body
+      .map((line) => line.trim())
+      .filter((line) => /^[A-Za-z0-9_?]+:/.test(line) || /^\/\*\*/.test(line))
+      .slice(0, 14)
+      .map((line) => line.replace(/\|/g, '\\|'));
+    interfaces.push({ name, file, fields });
+  }
+  return interfaces;
+}
+
+async function jsonShapes() {
+  const files = await walk('src', (p) => p.endsWith('.ts'));
+  const interfaces = [];
+  for (const file of files) {
+    const source = await fs.readFile(file, 'utf8');
+    interfaces.push(...extractInterfaces(source, rel(file)));
+  }
+
+  let out = header('JSON Shapes');
+  out +=
+    'This is a heuristic index of exported TypeScript interfaces that are likely to matter for agent-facing JSON.\n\n';
+  out += '| Interface | File | Notable Fields |\n';
+  out += '|---|---|---|\n';
+  for (const it of interfaces.sort((a, b) => a.file.localeCompare(b.file) || a.name.localeCompare(b.name))) {
+    out += `| \`${it.name}\` | \`${it.file}\` | ${it.fields.length ? it.fields.map((x) => `\`${x}\``).join('<br>') : '-'} |\n`;
+  }
+  return out;
+}
+
+const outputs = new Map([
+  ['command-index.md', await commandIndex()],
+  ['module-map.md', await moduleMap()],
+  ['test-index.md', await testIndex()],
+  ['json-shapes.md', await jsonShapes()],
+]);
+
+if (checkOnly) {
+  const mismatches = [];
+  for (const [name, content] of outputs) {
+    const target = path.join(outDir, name);
+    let current = '';
+    try {
+      current = await fs.readFile(target, 'utf8');
+    } catch {
+      mismatches.push(name);
+      continue;
+    }
+    if (current !== content) mismatches.push(name);
+  }
+  if (mismatches.length) {
+    console.error(
+      `Generated agent context is stale: ${mismatches.join(', ')}. Run pnpm agent-context.`,
+    );
+    process.exit(1);
+  }
+  console.log('Generated agent context is fresh.');
+} else {
+  await fs.mkdir(outDir, { recursive: true });
+  for (const [name, content] of outputs) {
+    await fs.writeFile(path.join(outDir, name), content);
+  }
+  console.log(`Generated agent context files in ${rel(outDir)}`);
+}
+