1688-cli 0.1.41 → 0.1.43

package/docs/exec-plans/completed/2026-06-16-profile-daemon.md

@@ -0,0 +1,146 @@
+# Plan: Profile Daemon
+
+## Goal
+
+Deliver profile-scoped daemon mode for `1688-cli`: one daemon, persistent
+browser context, lock, and runtime artifact set per profile, with default
+profile compatibility and deterministic verification.
+
+## Context
+
+- Source spec: `docs/specs/profile-daemon.md`.
+- Read first:
+  - `AGENTS.md`
+  - `ARCHITECTURE.md`
+  - `docs/WORKFLOW.md`
+  - `docs/COMMANDS.md`
+  - `docs/JSON_CONTRACTS.md`
+  - `docs/SAFETY.md`
+  - `docs/RELIABILITY.md`
+  - `docs/playbooks/add-command.md`
+  - `src/session/paths.ts`
+  - `src/session/lock.ts`
+  - `src/session/context.ts`
+  - `src/session/shared.ts`
+  - `src/session/dispatch.ts`
+  - `src/daemon/client.ts`
+  - `src/daemon/manager.ts`
+  - `src/daemon/server.ts`
+  - `src/commands/login.ts`
+  - `src/commands/doctor.ts`
+  - `src/commands/profile.ts`
+  - `src/cli.ts`
+  - `tests/paths.test.ts`
+  - `tests/profile.test.ts`
+  - `tests/doctor.test.ts`
+
+## Non-goals
+
+- Do not implement a multi-profile daemon process.
+- Do not change checkout confirmation safety.
+- Do not run external live login/search/browser flows during verification.
+- Do not introduce new dependencies.
+- Do not refactor unrelated command behavior.
+
+## Design
+
+Use one profile-bound daemon process per profile. The profile is resolved to
+`default` at the edge and then passed through path helpers, locks, daemon
+client/manager/server, shared context, dispatch, login, doctor, and profile
+status.
+
+Runtime artifacts become profile-scoped via centralized helpers. Non-Windows
+sockets live under a profile runtime directory; Windows named pipes include the
+root hash plus a profile-derived hash/slug so profiles do not collide.
+
+`dispatch` no longer treats `opts.profile` as a daemon skip condition. It
+connects to the selected profile daemon, auto-starts or refreshes only that
+daemon, and falls back inline only for that profile. Headed mode, `noDaemon`,
+and `BB1688_NO_DAEMON=1` still skip daemon dispatch.
+
+Inline fallback pauses only the selected profile daemon before opening an
+inline context on that profile. Other profile daemons continue running.
+
+`login --profile` writes profile-scoped state and attempts to start that
+profile daemon unless `--no-daemon` is set. `doctor --profile` and
+`profile status <name>` read profile-scoped state, lock, and daemon status.
+
+Docs and generated indexes are updated because command flags, daemon behavior,
+and source/test layout behavior changed.
+
+## Checklist
+
+- [x] Create spec/index and active ExecPlan for profile-scoped daemon work.
+- [x] Implement profile-scoped path helpers and lock acquisition.
+- [x] Thread profile through session context, shared daemon context, daemon
+  client, daemon manager, and daemon server.
+- [x] Update dispatch so explicit `--profile` uses the corresponding daemon and
+  inline fallback pauses only that profile daemon.
+- [x] Update CLI daemon/serve commands, login auto-start, doctor checks, and
+  profile status to use selected profile state and diagnostics.
+- [x] Update deterministic tests for paths, profile status, doctor, and daemon
+  profile plumbing.
+- [x] Update durable docs and regenerate generated context.
+- [x] Run focused and final verification, review diff, and record results.
+
+## Verification
+
+- `pnpm typecheck`
+- `pnpm test:unit`
+- `pnpm agent-context`
+- `pnpm docs-check`
+- `pnpm agent-map-check`
+- `pnpm agent-verify`
+
+## Decisions
+
+- 2026-06-16: Use one daemon process per profile instead of one daemon managing
+  many browser contexts, matching the request and current daemon architecture.
+- 2026-06-16: Keep `checkout-confirm` daemon-blocked; profile daemon support
+  does not weaken checkout safety.
+- 2026-06-16: Use deterministic local verification only; live 1688 browser
+  checks require user/session state and are out of scope for automated tests.
+
+## Progress Log
+
+- 2026-06-16: `/to-done` readiness path selected: clear complex request with no
+  existing matching durable spec or active plan, so create full spec and full
+  active ExecPlan before implementation.
+- 2026-06-16: `/run` execution strategy selected. Goal tracking preference:
+  prefer Codex /goal. Goal tracking result: Codex /goal. Delegation: none.
+  Reason: the active plan has one objective, scoped non-goals, deterministic
+  verification, and an adaptive validation loop. Subagents skipped because the
+  core daemon/session files are tightly coupled and should be edited/reviewed
+  by the primary agent. Completed checklist item: durable spec/index and active
+  ExecPlan created.
+- 2026-06-16: Implemented profile-scoped runtime helpers for socket, pid,
+  version, log, state, and lock artifacts. Default artifacts remain compatible
+  at the historical root paths; non-default profiles use their profile runtime
+  directory. Windows daemon pipes now include a profile hash.
+- 2026-06-16: Threaded profile through locks, inline sessions, shared daemon
+  browser context, daemon client/manager/server, dispatch, login auto-start,
+  doctor, profile status, whoami state writes, seller/inbox state reads, and
+  checkout-confirm daemon pause/resume.
+- 2026-06-16: Updated durable docs (`ARCHITECTURE.md`, `docs/COMMANDS.md`,
+  `docs/JSON_CONTRACTS.md`, `docs/RELIABILITY.md`, `docs/SAFETY.md`,
+  `docs/QUALITY_SCORE.md`) and refreshed generated context with
+  `pnpm agent-context`.
+- 2026-06-16: Review result: diff stayed within the profile daemon spec and
+  plan; checkout confirmation remains daemon-blocked and approval behavior is
+  unchanged. A small doctor indentation/readability issue found during diff
+  review was fixed before final verification.
+- 2026-06-16: Verification passed:
+  `pnpm typecheck`;
+  `pnpm vitest run tests/paths.test.ts tests/state.test.ts tests/profile.test.ts tests/doctor.test.ts --exclude tests/doctor-live.test.ts`;
+  `pnpm test:unit`;
+  `pnpm agent-context`;
+  `pnpm agent-verify`.
+  Final `pnpm agent-verify` passed with 27 test files and 174 deterministic
+  tests, fresh generated context, passing agent-map check, and passing release
+  check. No blockers or new open questions remain.
+
+## Rollback
+
+Revert the profile daemon changes in `src/session`, `src/daemon`,
+`src/commands`, `src/cli.ts`, tests, and docs. Existing profile browser data
+under `~/.1688/profiles/<name>` is not modified by rollback.

package/docs/exec-plans/completed/README.md

@@ -0,0 +1,4 @@
+# Completed ExecPlans
+
+Move completed complex work here with final verification notes.
+

package/docs/exec-plans/tech-debt-tracker.md

@@ -0,0 +1,5 @@
+# Tech Debt Tracker
+
+Record non-blocking follow-up work here when it should not stay in an active
+ExecPlan.
+

package/docs/generated/command-index.md

@@ -0,0 +1,54 @@
+# Command Index
+
+_Generated by `scripts/generate_agent_context.mjs`._
+
+| Command | Source | Arguments | Options | Description |
+|---|---|---|---|---|
+| `login` | `src/commands/login.ts` | - | `--force`<br>`--timeout <seconds>`<br>`--profile <name>`<br>`--headed`<br>`--no-daemon` | Log in to 1688 by scanning a QR code (auto-starts daemon afterwards) |
+| `search` | `src/commands/search.ts` | `<keyword>` | `--max <n>`<br>`--sort <sort>`<br>`--price-min <n>`<br>`--price-max <n>`<br>`--province <name>`<br>`--city <name>`<br>`--verified <kind>`<br>`--min-turnover <n>`<br>`--exclude-ads`<br>`--profile <name>`<br>`--headed` | Search 1688 by keyword |
+| `research` | `src/commands/research.ts` | `<keywords...>` | `--max-per-query <n>`<br>`--sort <sort>`<br>`--price-min <n>`<br>`--price-max <n>`<br>`--province <name>`<br>`--city <name>`<br>`--verified <kind>`<br>`--min-turnover <n>`<br>`--exclude-ads`<br>`--enrich <spec>`<br>`--jsonl`<br>`--csv`<br>`--output <file>`<br>`--profile <name>`<br>`--headed` | Run multi-keyword sourcing research with scoring and optional enrichment |
+| `compare` | `src/commands/compare.ts` | `<offerIds...>` | `--csv`<br>`--output <file>`<br>`--profile <name>`<br>`--headed` | Compare multiple offer detail pages for sourcing decisions |
+| `supplier` | - | - | - | - |
+| `supplier inspect` | `src/commands/supplier-inspect.ts` | `<target>` | `--profile <name>`<br>`--headed` | Inspect supplier signals from an offerId or b2b-* memberId |
+| `supplier search` | `src/commands/supplier-search.ts` | `<keywords...>` | `--max <n>`<br>`--factory-only`<br>`--province <name>`<br>`--city <name>`<br>`--min-years <n>`<br>`--min-repeat-rate <n>`<br>`--min-response-rate <n>`<br>`--enrich <spec>`<br>`--jsonl`<br>`--csv`<br>`--output <file>`<br>`--profile <name>`<br>`--headed` | Search suppliers from 1688 company search |
+| `supplier research` | `src/commands/supplier-search.ts` | `<keywords...>` | `--max <n>`<br>`--factory-only`<br>`--province <name>`<br>`--city <name>`<br>`--min-years <n>`<br>`--min-repeat-rate <n>`<br>`--min-response-rate <n>`<br>`--enrich <spec>`<br>`--jsonl`<br>`--csv`<br>`--output <file>`<br>`--profile <name>`<br>`--headed` | Run supplier research from 1688 company search with scoring and inspect enrichment |
+| `image-search` | `src/commands/image-search.ts` | `<imagePathOrUrl>` | `--max <n>`<br>`--profile <name>`<br>`--headed` | Search 1688 by image (local file or http(s) URL) |
+| `offer` | `src/commands/offer.ts` | `<offerId>` | `--profile <name>`<br>`--headed` | Show details of a single 1688 offer |
+| `similar` | `src/commands/similar.ts` | `<offerId>` | `--max <n>`<br>`--profile <name>`<br>`--headed` | Find similar / 找同款 offers for a given offerId (compare suppliers, sorted by price), |
+| `inbox` | `src/commands/inbox.ts` | - | `--limit <n>`<br>`--unread`<br>`--profile <name>`<br>`--headed` | List recent 旺旺 IM conversations (newest first) |
+| `seller` | - | - | - | Seller communication (旺旺 IM |
+| `seller inquire` | `src/commands/seller-inquire.ts` | `<offerId>`<br>`<message>` | `--to <sellerLoginId>`<br>`--profile <name>`<br>`--headed` | Pre-sale inquiry: send a product link question to seller (requires prior chat or --to), |
+| `seller messages` | `src/commands/seller-messages.ts` | `[target]` | `--offer <offerId>`<br>`--limit <n>`<br>`--since <iso>`<br>`--watch`<br>`--interval <seconds>`<br>`--profile <name>`<br>`--headed` | Read recent messages from a seller conversation |
+| `seller chat` | `src/commands/seller-chat.ts` | `<target>`<br>`<message>` | `--no-card`<br>`--prefix`<br>`--profile <name>`<br>`--headed` | Send to seller. With orderId: sends order card link message (use --no-card for follow-ups |
+| `checkout` | - | - | - | - |
+| `checkout confirm` | `src/commands/checkout-confirm.ts` | `<cartIds...>` | `-y, --yes`<br>`--agent`<br>`--profile <name>` | Place an order for selected cart items. Default: TTY prompt. --agent: no prompt after external approval., |
+| `checkout prepare` | `src/commands/checkout-prepare.ts` | `<cartIds...>` | `--profile <name>`<br>`--headed` | Preview total/address/items for a checkout (does NOT place order) |
+| `cart` | - | - | - | - |
+| `cart add` | `src/commands/cart-add.ts` | `<offerId>` | `--sku <skuId>`<br>`--qty <n>`<br>`--profile <name>`<br>`--headed` | Add one item to cart (UI replay, ~15s) |
+| `cart remove` | `src/commands/cart-remove.ts` | `<cartId>` | `--profile <name>`<br>`--headed` | Remove one item from cart by cartId (UI replay, ~10s) |
+| `cart list` | `src/commands/cart-list.ts` | - | `--profile <name>`<br>`--headed` | List items in your cart |
+| `shipped` | `src/commands/workflows.ts` | `<orderId>` | `--profile <name>`<br>`--headed` | Combined order detail logistics for one orderId |
+| `stuck` | `src/commands/workflows.ts` | - | `--days <n>`<br>`--limit <n>`<br>`--profile <name>`<br>`--headed` | Orders paid but not shipped after N days (default 3) |
+| `fake-shipped` | `src/commands/workflows.ts` | - | `--days <n>`<br>`--max-pages <n>`<br>`--max-check <n>`<br>`--limit <n>`<br>`--debug`<br>`--profile <name>`<br>`--headed` | Orders marked shipped but logistics frozen at 等待揽收 (likely 虚假发货) |
+| `seller-history` | `src/commands/workflows.ts` | `<seller>` | `--max-pages <n>`<br>`--profile <name>`<br>`--headed` | All orders from a seller avg shipping days on-time rate |
+| `order` | - | - | - | - |
+| `order logistics` | `src/commands/order-logistics.ts` | `<orderId>` | `--max-scan-pages <n>`<br>`--status <s>`<br>`--profile <name>`<br>`--headed` | Show shipping status tracking number for an order |
+| `order get` | `src/commands/order-get.ts` | `<orderId>` | `--max-scan-pages <n>`<br>`--status <s>`<br>`--profile <name>`<br>`--headed` | Show one order by orderId (scans recent pages) |
+| `order list` | `src/commands/order-list.ts` | - | `--status <s>`<br>`--page <n>`<br>`--page-size <n>`<br>`--profile <name>`<br>`--headed` | List buyer orders |
+| `whoami` | `src/commands/whoami.ts` | - | `--verify`<br>`--profile <name>` | Show the current logged-in account |
+| `logout` | `src/commands/logout.ts` | - | `-y, --yes`<br>`--profile <name>` | Log out and clear local session |
+| `doctor` | `src/commands/doctor.ts` | - | `--no-launch`<br>`--live`<br>`--profile <name>` | Check environment, profile, Chromium, and session |
+| `serve` | - | - | `--profile <name>`<br>`--idle-timeout <minutes>`<br>`--no-prewarm` | Run the 1688 daemon in the foreground |
+| `daemon` | - | - | - | - |
+| `daemon start` | - | - | `--profile <name>` | Start the daemon as a background process |
+| `daemon stop` | - | - | `--profile <name>` | Stop the running daemon |
+| `daemon reload` | - | - | `--profile <name>` | Restart the daemon (stop start) to pick up new code |
+| `daemon status` | - | - | `--profile <name>` | Show daemon status |
+| `profile` | - | - | - | - |
+| `profile list` | `src/commands/profile.ts` | - | - | List local profiles |
+| `profile status` | `src/commands/profile.ts` | `[name]` | - | Show profile status |
+| `debug` | - | - | - | - |
+| `debug list` | `src/commands/debug.ts` | - | `--limit <n>`<br>`--failed` | List recent command events |
+| `debug last` | `src/commands/debug.ts` | - | `--failed` | Show the most recent command event |
+| `debug show` | `src/commands/debug.ts` | `<requestId>` | - | Show events and artifact location for a request |
+| `feedback` | `src/commands/feedback.ts` | `<message...>` | `--bug`<br>`--submit`<br>`--no-open`<br>`--json`<br>`--json-v2`<br>`--pretty`<br>`--get <path>`<br>`--pick <paths>` | Submit feedback or a bug report. Default: opens a pre-filled GitHub issue. With --submit: posts directly via the gh CLI., |

package/docs/generated/json-shapes.md

@@ -0,0 +1,111 @@
+# JSON Shapes
+
+_Generated by `scripts/generate_agent_context.mjs`._
+
+This is a heuristic index of exported TypeScript interfaces that are likely to matter for agent-facing JSON.
+
+| Interface | File | Notable Fields |
+|---|---|---|
+| `CartAddArgs` | `src/commands/cart-add.ts` | `offerId: string;`<br>`skuId: string;`<br>`quantity: number;`<br>`headed?: boolean;` |
+| `CartAddOpts` | `src/commands/cart-add.ts` | `offerId: string;`<br>`sku?: string;`<br>`qty?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `CartAddResult` | `src/commands/cart-add.ts` | `ok: boolean;`<br>`confirmationStatus: 'confirmed';`<br>`added: CartItem;`<br>`/** True when a brand-new cart row was created. False when the SKU was`<br>`isNewRow: boolean;`<br>`/** Actual quantity added by this call. For a new row it equals`<br>`addedQuantity: number;` |
+| `CartItem` | `src/commands/cart-list.ts` | `cartId: string;`<br>`offerId: string;`<br>`skuId: string \| null;`<br>`productTitle: string;`<br>`skuTitle: string \| null;`<br>`unit: string \| null;`<br>`quantity: number;`<br>`unitPrice: number;`<br>`amount: number;`<br>`minQuantity: number \| null;`<br>`maxQuantity: number \| null;`<br>`image: string \| null;`<br>`checked: boolean;`<br>`effective: boolean;` |
+| `CartListArgs` | `src/commands/cart-list.ts` | `headed?: boolean;` |
+| `CartListOpts` | `src/commands/cart-list.ts` | `profile?: string;`<br>`headed?: boolean;` |
+| `CartListResult` | `src/commands/cart-list.ts` | `total: number;`<br>`selectedCount: number;`<br>`items: CartItem[];` |
+| `CartRemoveArgs` | `src/commands/cart-remove.ts` | `cartId: string;`<br>`headed?: boolean;` |
+| `CartRemoveOpts` | `src/commands/cart-remove.ts` | `cartId: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `CartRemoveResult` | `src/commands/cart-remove.ts` | `ok: boolean;`<br>`removed: CartItem;` |
+| `CheckoutConfirmArgs` | `src/commands/checkout-confirm.ts` | `cartIds: string[];`<br>`headed?: boolean;` |
+| `CheckoutConfirmOpts` | `src/commands/checkout-confirm.ts` | `cartIds: string[];`<br>`yes?: boolean;`<br>`agent?: boolean;`<br>`profile?: string;` |
+| `CheckoutConfirmResult` | `src/commands/checkout-confirm.ts` | `ok: boolean;`<br>`placed: boolean;`<br>`finalUrl: string;`<br>`orderId: string \| null;`<br>`message: string;`<br>`preview: CheckoutPrepareResult;` |
+| `CheckoutPrepareArgs` | `src/commands/checkout-prepare.ts` | `cartIds: string[];`<br>`headed?: boolean;` |
+| `CheckoutPrepareOpts` | `src/commands/checkout-prepare.ts` | `cartIds: string[];`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `CheckoutPrepareResult` | `src/commands/checkout-prepare.ts` | `ok: boolean;`<br>`url: string;`<br>`totalAmount: number;`<br>`productAmount: number;`<br>`shippingAmount: number;`<br>`taxAmount: number;`<br>`receiveAddress: {`<br>`fullName: string \| null;`<br>`mobile: string \| null;`<br>`address: string \| null;`<br>`region: string \| null;`<br>`orders: PrepareOrder[];` |
+| `PrepareOrder` | `src/commands/checkout-prepare.ts` | `seller: {`<br>`memberId: string \| null;`<br>`loginId: string \| null;`<br>`companyName: string \| null;`<br>`totalAmount: number;`<br>`productAmount: number;`<br>`shippingAmount: number;`<br>`items: PrepareItem[];` |
+| `CompareOpts` | `src/commands/compare.ts` | `offerIds: string[];`<br>`csv?: boolean;`<br>`output?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `CompareResult` | `src/commands/compare.ts` | `total: number;`<br>`ok: number;`<br>`failed: number;`<br>`items: CompareItem[];` |
+| `DebugLastOpts` | `src/commands/debug.ts` | `failed?: boolean;` |
+| `DebugListOpts` | `src/commands/debug.ts` | `limit?: string;`<br>`failed?: boolean;` |
+| `DebugShowOpts` | `src/commands/debug.ts` | `requestId: string;` |
+| `DoctorOpts` | `src/commands/doctor.ts` | `launch?: boolean;`<br>`live?: boolean;`<br>`profile?: string;` |
+| `FeedbackOpts` | `src/commands/feedback.ts` | `message?: string;`<br>`bug?: boolean;`<br>`open?: boolean;`<br>`submit?: boolean;` |
+| `FeedbackResult` | `src/commands/feedback.ts` | `url: string;`<br>`title: string;`<br>`bodyPreview: string;`<br>`submitted: boolean;` |
+| `ImageSearchArgs` | `src/commands/image-search.ts` | `imagePath: string;`<br>`max: number;`<br>`headed?: boolean;` |
+| `ImageSearchOpts` | `src/commands/image-search.ts` | `imagePath: string;`<br>`max?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `ImageSearchResult` | `src/commands/image-search.ts` | `imageId: string;`<br>`total: number;`<br>`offers: Offer[];` |
+| `InboxArgs` | `src/commands/inbox.ts` | `limit: number;`<br>`unreadOnly: boolean;`<br>`myLoginId: string;`<br>`myMemberId: string;`<br>`headed?: boolean;` |
+| `InboxOpts` | `src/commands/inbox.ts` | `limit?: string;`<br>`unread?: boolean;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `InboxResult` | `src/commands/inbox.ts` | `myLoginId: string;`<br>`myMemberId: string;`<br>`conversations: Conversation[];`<br>`nextCursor: number \| null;`<br>`truncated: boolean;` |
+| `LoginOpts` | `src/commands/login.ts` | `force?: boolean;`<br>`timeout?: string;`<br>`profile?: string;`<br>`headed?: boolean;`<br>`noDaemon?: boolean;` |
+| `LogoutOpts` | `src/commands/logout.ts` | `yes?: boolean;`<br>`profile?: string;` |
+| `OfferArgs` | `src/commands/offer.ts` | `offerId: string;`<br>`headed?: boolean;` |
+| `OfferOpts` | `src/commands/offer.ts` | `offerId: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `OfferResult` | `src/commands/offer.ts` | `offerId: string;`<br>`title: string;`<br>`url: string;`<br>`priceRange: string \| null;`<br>`priceMin: number \| null;`<br>`priceMax: number \| null;`<br>`/** Display unit ("件" / "个" / "米" ...) */`<br>`unitName: string \| null;`<br>`/** 起订量 — minimum order quantity for a single SKU buy. */`<br>`minOrderQty: number \| null;`<br>`/** 混批起订量 — minimum quantity when mixing SKUs in one order. */`<br>`mixOrderQty: number \| null;`<br>`/** Bulk-discount tiers, e.g. [{minQty: 1, price: 4.16}, {minQty: 100, price: 3.50}]. */`<br>`priceTiers: PriceTier[];` |
+| `PriceTier` | `src/commands/offer.ts` | `minQty: number;`<br>`price: number;` |
+| `ProductAttribute` | `src/commands/offer.ts` | `name: string;`<br>`value: string;` |
+| `SkuOption` | `src/commands/offer.ts` | `prop: string;`<br>`values: { name: string; imageUrl: string \| null }[];` |
+| `SkuPackage` | `src/commands/offer.ts` | `skuId: string;`<br>`spec: string;`<br>`/** cm */`<br>`length: number \| null;`<br>`width: number \| null;`<br>`height: number \| null;`<br>`/** Stated weight (raw value — 1688 sometimes uses grams or kg per offer). */`<br>`weight: number \| null;`<br>`/** Volume (cm³). */`<br>`volume: number \| null;` |
+| `SkuVariant` | `src/commands/offer.ts` | `skuId: string;`<br>`specs: string;`<br>`price: number \| null;`<br>`/** Bulk-tier price when 1688 surfaces a separate multi-piece price. */`<br>`multiPrice: number \| null;`<br>`stock: number \| null;`<br>`saleCount: number;`<br>`/** Best-effort image URL derived from the first option (颜色/款式) match. */`<br>`image: string \| null;` |
+| `OrderGetArgs` | `src/commands/order-get.ts` | `orderId: string;`<br>`maxScanPages: number;`<br>`/** Narrow scan to a specific tradeStatus when known — much faster for`<br>`statusHint?: string;`<br>`headed?: boolean;` |
+| `OrderGetOpts` | `src/commands/order-get.ts` | `orderId: string;`<br>`maxScanPages?: string;`<br>`status?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `Order` | `src/commands/order-list.ts` | `orderId: string;`<br>`status: string;`<br>`statusLabel: string;`<br>`bizType: string \| null; // "cb" / "pc" / ...`<br>`createdAt: string;`<br>`paidAt: string \| null;`<br>`shippedAt: string \| null;`<br>`confirmGoodsTime: string \| null;`<br>`totalAmount: number;`<br>`productAmount: number;`<br>`shipping: number;`<br>`originalAmount: number; // before any promotions`<br>`discountAmount: number; // sum of all promotions applied`<br>`adjustment: number; // seller manual price adjustment (改价)` |
+| `OrderAction` | `src/commands/order-list.ts` | `key: string; // permissionKey, e.g. "canBuyerRefund"`<br>`name: string; // display name, e.g. "申请退款"`<br>`url: string \| null;`<br>`highlight: boolean;` |
+| `OrderItem` | `src/commands/order-list.ts` | `entryId: string;`<br>`productName: string;`<br>`spec: string;`<br>`quantity: number;`<br>`unitPrice: number;`<br>`amount: number;`<br>`image: string \| null;`<br>`productNumber: string \| null;` |
+| `OrderListArgs` | `src/commands/order-list.ts` | `status: string;`<br>`page: number;`<br>`pageSize: number;`<br>`headed?: boolean;` |
+| `OrderListOpts` | `src/commands/order-list.ts` | `status?: string;`<br>`page?: string;`<br>`pageSize?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `OrderListResult` | `src/commands/order-list.ts` | `status: string;`<br>`page: number;`<br>`pageSize: number;`<br>`totalPages: number;`<br>`totalOrders: number;`<br>`orders: Order[];` |
+| `OrderService` | `src/commands/order-list.ts` | `productName: string;`<br>`category: string; // "insurance" / "refund" / ...`<br>`payer: string; // "seller" / "buyer"`<br>`detailLink: string \| null;` |
+| `OrderStep` | `src/commands/order-list.ts` | `status: string;`<br>`name: string;`<br>`paid: number;`<br>`goods: number;`<br>`postage: number;` |
+| `OrderLogisticsArgs` | `src/commands/order-logistics.ts` | `orderId: string;`<br>`maxScanPages: number;`<br>`/** Narrow the scan to one tradeStatus (e.g. "waitbuyerreceive") when known —`<br>`statusHint?: string;`<br>`headed?: boolean;` |
+| `OrderLogisticsOpts` | `src/commands/order-logistics.ts` | `orderId: string;`<br>`maxScanPages?: string;`<br>`status?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `OrderLogisticsResult` | `src/commands/order-logistics.ts` | `orderId: string;`<br>`found: boolean;`<br>`trace: LogisticsTrace[];` |
+| `ResearchOpts` | `src/commands/research.ts` | `keywords: string[];`<br>`maxPerQuery?: string;`<br>`sort?: string;`<br>`priceMin?: string;`<br>`priceMax?: string;`<br>`province?: string;`<br>`city?: string;`<br>`verified?: string;`<br>`minTurnover?: string;`<br>`excludeAds?: boolean;`<br>`enrich?: string;`<br>`jsonl?: boolean;`<br>`csv?: boolean;`<br>`output?: string;` |
+| `ResearchResult` | `src/commands/research.ts` | `queries: string[];`<br>`sort: SearchSort;`<br>`filters: SearchFilterSummary;`<br>`maxPerQuery: number;`<br>`enrichTop: number;`<br>`total: number;`<br>`enrichedCount: number;`<br>`items: ResearchItem[];` |
+| `SearchArgs` | `src/commands/search.ts` | `keyword: string;`<br>`max: number;`<br>`sort?: SearchSort;`<br>`filters?: SearchFilterSummary;`<br>`headed?: boolean;` |
+| `SearchOpts` | `src/commands/search.ts` | `max?: string;`<br>`sort?: string;`<br>`priceMin?: string;`<br>`priceMax?: string;`<br>`province?: string;`<br>`city?: string;`<br>`verified?: string;`<br>`minTurnover?: string;`<br>`excludeAds?: boolean;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SearchResult` | `src/commands/search.ts` | `keyword: string;`<br>`sort: SearchSort;`<br>`filters: SearchFilterSummary;`<br>`totalBeforeFilter: number;`<br>`total: number;`<br>`offers: Offer[];` |
+| `SellerChatArgs` | `src/commands/seller-chat.ts` | `/** Display name(s) to find seller in 旺旺 sidebar — try in order */`<br>`searchNames: string[];`<br>`/** Seller loginId (raw, no cnalichn prefix) for order/offer-context URL */`<br>`sellerLoginId?: string;`<br>`/** Order ID — passed in URL to trigger order-scoped conversation */`<br>`orderId?: string;`<br>`/** Offer ID — passed in URL to trigger pre-sale (offer-scoped) conversation */`<br>`offerId?: string;`<br>`myLoginId: string;`<br>`message: string;`<br>`headed?: boolean;` |
+| `SellerChatOpts` | `src/commands/seller-chat.ts` | `target?: string;`<br>`message: string;`<br>`prefix?: boolean;`<br>`/** Skip sending order card link before message (use for follow-up replies) */`<br>`noCard?: boolean;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SellerChatResult` | `src/commands/seller-chat.ts` | `ok: boolean;`<br>`sentTo: string;`<br>`message: string;`<br>`sentAt: string;` |
+| `SellerInquireOpts` | `src/commands/seller-inquire.ts` | `offerId: string;`<br>`message: string;`<br>`to?: string; // explicit seller loginId`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `Message` | `src/commands/seller-messages.ts` | `sender: string;`<br>`time: string \| null;`<br>`isMine: boolean;`<br>`content: string;`<br>`read: boolean;`<br>`/** Type of message — auto-detected from DOM. */`<br>`kind: MessageKind;`<br>`/** Populated when kind === 'offerCard' or 'orderCard'. */`<br>`card?: {`<br>`title: string \| null;`<br>`price: string \| null;`<br>`image: string \| null;`<br>`url: string \| null;`<br>`/** Server-side message ID (only present when sourced from WS). Used for` |
+| `SellerMessagesArgs` | `src/commands/seller-messages.ts` | `searchNames: string[];`<br>`sellerLoginId?: string;`<br>`orderId?: string;`<br>`offerId?: string;`<br>`myLoginId: string;`<br>`limit: number;`<br>`headed?: boolean;` |
+| `SellerMessagesOpts` | `src/commands/seller-messages.ts` | `target?: string;`<br>`offer?: string;`<br>`limit?: string;`<br>`since?: string;`<br>`watch?: boolean;`<br>`interval?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SellerMessagesResult` | `src/commands/seller-messages.ts` | `conversation: string;`<br>`total: number;`<br>`messages: Message[];` |
+| `SimilarArgs` | `src/commands/similar.ts` | `offerId: string;`<br>`max: number;`<br>`headed?: boolean;` |
+| `SimilarOpts` | `src/commands/similar.ts` | `offerId: string;`<br>`max?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SimilarResult` | `src/commands/similar.ts` | `offerId: string;`<br>`total: number;`<br>`offers: Offer[];` |
+| `OfferDetailSummary` | `src/commands/sourcing-utils.ts` | `offerId: string;`<br>`title: string;`<br>`url: string;`<br>`priceMin: number \| null;`<br>`priceMax: number \| null;`<br>`unitName: string \| null;`<br>`minOrderQty: number \| null;`<br>`mixOrderQty: number \| null;`<br>`priceTiers: PriceTier[];`<br>`saledCount: number \| null;`<br>`categoryId: string \| null;`<br>`supplier: OfferResult['supplier'];`<br>`skuCount: number;`<br>`totalStock: number \| null;` |
+| `SupplierInspectArgs` | `src/commands/supplier-inspect.ts` | `target: string;`<br>`headed?: boolean;` |
+| `SupplierInspectOpts` | `src/commands/supplier-inspect.ts` | `target: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SupplierInspectResult` | `src/commands/supplier-inspect.ts` | `target: SupplierTarget;`<br>`supplier: {`<br>`name: string \| null;`<br>`loginId: string \| null;`<br>`memberId: string \| null;`<br>`userId: string \| null;`<br>`companyId: string \| null;`<br>`shopUrl: string \| null;`<br>`shopUrls: Record<string, string>;`<br>`identity: string \| null;`<br>`signs: Record<string, boolean>;`<br>`factory: {`<br>`isFactory: boolean;`<br>`superFactory: boolean;` |
+| `SupplierResearchOpts` | `src/commands/supplier-search.ts` | - |
+| `SupplierSearchArgs` | `src/commands/supplier-search.ts` | `keywords: string[];`<br>`maxPerQuery: number;`<br>`enrichTop?: number;`<br>`filters?: SupplierFilters;`<br>`headed?: boolean;` |
+| `SupplierSearchOpts` | `src/commands/supplier-search.ts` | `keywords: string[];`<br>`max?: string;`<br>`enrich?: string;`<br>`factoryOnly?: boolean;`<br>`province?: string;`<br>`city?: string;`<br>`minYears?: string;`<br>`minRepeatRate?: string;`<br>`minResponseRate?: string;`<br>`jsonl?: boolean;`<br>`csv?: boolean;`<br>`output?: string;`<br>`profile?: string;`<br>`headed?: boolean;` |
+| `SupplierSearchResult` | `src/commands/supplier-search.ts` | `queries: string[];`<br>`source: {`<br>`kind: 'company-search';`<br>`endpoint: 'companySearchBusinessService';`<br>`offerAggregation: false;`<br>`filters: SupplierFilters;`<br>`maxPerQuery: number;`<br>`enrichTop: number;`<br>`totalBeforeFilter: number;`<br>`total: number;`<br>`enrichedCount: number;`<br>`items: SupplierSearchItem[];` |
+| `WhoamiArgs` | `src/commands/whoami.ts` | `verify?: boolean;`<br>`profile?: string;` |
+| `WhoamiOpts` | `src/commands/whoami.ts` | `verify?: boolean;`<br>`profile?: string;` |
+| `WhoamiResult` | `src/commands/whoami.ts` | `loggedIn: boolean;`<br>`memberId?: string;`<br>`nick?: string \| null;`<br>`lastVerifiedAt?: string \| null;` |
+| `FakeShippedOpts` | `src/commands/workflows.ts` | `days?: string;`<br>`limit?: string;`<br>`maxPages?: string;`<br>`maxCheck?: string;`<br>`debug?: boolean;` |
+| `SellerHistoryOpts` | `src/commands/workflows.ts` | `seller: string;`<br>`maxPages?: string;` |
+| `ShippedOpts` | `src/commands/workflows.ts` | `orderId: string;` |
+| `StuckOpts` | `src/commands/workflows.ts` | `days?: string;`<br>`limit?: string;` |
+| `SessionOpts` | `src/session/context.ts` | `headless: boolean;`<br>`profile?: string;` |
+| `DispatchOpts` | `src/session/dispatch.ts` | `headed?: boolean;`<br>`profile?: string;`<br>`noDaemon?: boolean;` |
+| `DecodedMessage` | `src/session/im-cards.ts` | `kind: MessageKind;`<br>`preview: string;`<br>`/** Set when `kind === 'card'`. Semantic name when known, `'unknown'` otherwise. */`<br>`cardTemplate?: CardTemplate;`<br>`/** Raw 6-digit template code (`170002`, `467001`, …). Always present for cards. */`<br>`cardCode?: string;`<br>`/** Populated only when at least one field resolved — keep JSON output compact. */`<br>`extras?: MessageExtras;` |
+| `MessageExtras` | `src/session/im-cards.ts` | `/** Trade order id parsed from card link, if any. */`<br>`orderId?: string;`<br>`/** Offer (product) id parsed from card link, if any. */`<br>`offerId?: string;`<br>`/** Refund / 退货 id, if any. */`<br>`refundId?: string;`<br>`/** Product / order thumbnail URL. */`<br>`imgUrl?: string;`<br>`/** Clickthrough URL embedded in the card. */`<br>`linkUrl?: string;`<br>`/** Display string such as "订单金额：￥4.90" or "¥0.04". */`<br>`amount?: string;` |
+| `RawImMessage` | `src/session/im-cards.ts` | `content?: {`<br>`contentType?: number;`<br>`text?: { content?: string };`<br>`custom?: {`<br>`summary?: string;`<br>`data?: string;`<br>`title?: string;`<br>`extension?: {`<br>`biMsgType?: string;`<br>`dynamic_msg_content?: string;` |
+| `StableLocatorResult` | `src/session/locator.ts` | `strategy: string;`<br>`description: string;` |
+| `ResponseCaptureActionResult` | `src/session/response-capture.ts` | `actionResult: TResult;`<br>`response: T \| null;`<br>`diagnostics: ResponseCaptureDiagnostics;` |
+| `ResponseCaptureEmptyResult` | `src/session/response-capture.ts` | `at: string;`<br>`url: string;` |
+| `SearchOfferCaptureDiagnostics` | `src/session/search-capture.ts` | `startedAt: string;`<br>`endedAt?: string;`<br>`disposed: boolean;`<br>`finalStatus?: SearchOfferCaptureWaitStatus;`<br>`timedOut: boolean;`<br>`seenCount: number;`<br>`matchedCount: number;`<br>`parsedCount: number;`<br>`failureCount: number;`<br>`lastSeenUrl?: string;`<br>`lastMatchedUrl?: string;`<br>`lastParsedUrl?: string;`<br>`lastError?: { name?: string; message: string };`<br>`failures: SearchOfferCaptureFailure[];` |
+| `SearchOfferCaptureFailure` | `src/session/search-capture.ts` | `at: string;`<br>`url: string;`<br>`name?: string;`<br>`message: string;` |
+| `SearchOfferCaptureOptions` | `src/session/search-capture.ts` | `page: Page;`<br>`requireMethod?: string;`<br>`targetPage?: () => number;`<br>`keep?: 'first' \| 'largest';` |
+| `SearchOfferCaptureResult` | `src/session/search-capture.ts` | `actionResult: TResult;`<br>`status: SearchOfferCaptureWaitStatus;`<br>`offers: Offer[];`<br>`diagnostics: SearchOfferCaptureDiagnostics;` |
+| `SearchOfferCaptureWaitOptions` | `src/session/search-capture.ts` | `timeoutMs: number;`<br>`intervalMs?: number;`<br>`isBlocked?: () => boolean \| Promise<boolean>;`<br>`isClosed?: () => boolean;` |
+| `SearchOfferCaptureWaitResult` | `src/session/search-capture.ts` | `status: SearchOfferCaptureWaitStatus;`<br>`offers: Offer[];`<br>`diagnostics: SearchOfferCaptureDiagnostics;` |
+| `Offer` | `src/session/search-mtop.ts` | `offerId: string;`<br>`title: string;`<br>`price: { text: string; min: number \| null; max: number \| null };`<br>`supplier: {`<br>`name: string \| null;`<br>`shopUrl: string \| null;`<br>`years: number \| null;`<br>`location: { province: string \| null; city: string \| null };`<br>`bizType: string \| null;`<br>`verified: { factory: boolean; business: boolean; superFactory: boolean };`<br>`tags: string[];`<br>`serviceTags?: string[];`<br>`productBadges?: string[];`<br>`demand?: {` |
+| `RawOfferItem` | `src/session/search-mtop.ts` | `cellType?: string;`<br>`data?: {`<br>`offerId?: string;`<br>`title?: string;`<br>`priceInfo?: { price?: string };`<br>`offerPicUrl?: string;`<br>`loginId?: string;`<br>`memberId?: string;`<br>`province?: string;`<br>`city?: string;`<br>`bookedCount?: string;`<br>`repurchaseRate?: string;`<br>`repurchaseRateText?: string;`<br>`orderCount?: string \| number;` |
+| `SupplierOfferPreview` | `src/session/supplier-search.ts` | `offerId: string \| null;`<br>`title: string;`<br>`url: string \| null;`<br>`price: { text: string \| null; value: number \| null };`<br>`unit: string \| null;`<br>`image: string \| null;`<br>`bookedCount: number \| null;`<br>`saleQuantity: number \| null;`<br>`quantitySumMonth: number \| null;`<br>`brief: string \| null;` |
+| `SupplierSearchCaptureWaitResult` | `src/session/supplier-search.ts` | `status: SupplierSearchCaptureWaitStatus;`<br>`data: SupplierSearchServiceData \| null;`<br>`diagnostics: SupplierSearchCaptureDiagnostics;` |

package/docs/generated/module-map.md

@@ -0,0 +1,13 @@
+# Module Map
+
+_Generated by `scripts/generate_agent_context.mjs`._
+
+| Directory | Source Files | Related Tests | Notes |
+|---|---:|---:|---|
+| `src` | 1 | 0 | - |
+| `src/auth` | 2 | 1 | login/session/cookie helpers |
+| `src/commands` | 29 | 5 | command executors and renderers |
+| `src/daemon` | 5 | 0 | background daemon client/server/protocol |
+| `src/io` | 3 | 10 | output, prompts, and errors |
+| `src/session` | 27 | 11 | browser/session automation helpers |
+| `src/util` | 3 | 0 | shared utilities |

package/docs/generated/test-index.md

@@ -0,0 +1,34 @@
+# Test Index
+
+_Generated by `scripts/generate_agent_context.mjs`._
+
+| Test File | Focus | Risk Notes |
+|---|---|---|
+| `tests/artifacts.test.ts` | artifacts | live/session-sensitive, browser/page-state, fixture/parser |
+| `tests/config.test.ts` | config | live/session-sensitive, fixture/parser |
+| `tests/cookies.test.ts` | cookies | live/session-sensitive, browser/page-state |
+| `tests/debug.test.ts` | debug | live/session-sensitive |
+| `tests/doctor-live.test.ts` | doctor-live | live/session-sensitive |
+| `tests/doctor.test.ts` | doctor | live/session-sensitive |
+| `tests/events.test.ts` | events | live/session-sensitive, browser/page-state |
+| `tests/fix-bin-mode.test.ts` | fix-bin-mode | - |
+| `tests/im-cards.test.ts` | im-cards | live/session-sensitive, fixture/parser |
+| `tests/inbox.test.ts` | inbox | live/session-sensitive |
+| `tests/locator.test.ts` | locator | browser/page-state |
+| `tests/mtop.test.ts` | mtop | fixture/parser |
+| `tests/navigation-guard.test.ts` | navigation-guard | live/session-sensitive |
+| `tests/output.test.ts` | output | - |
+| `tests/page-state.test.ts` | page-state | live/session-sensitive, browser/page-state |
+| `tests/paths.test.ts` | paths | live/session-sensitive |
+| `tests/profile.test.ts` | profile | live/session-sensitive |
+| `tests/recovery.test.ts` | recovery | browser/page-state |
+| `tests/replay-fixtures.test.ts` | replay-fixtures | browser/page-state, fixture/parser |
+| `tests/response-capture.test.ts` | response-capture | browser/page-state, fixture/parser |
+| `tests/search-capture.test.ts` | search-capture | browser/page-state, fixture/parser |
+| `tests/search-mtop.test.ts` | search-mtop | browser/page-state, fixture/parser |
+| `tests/search-options.test.ts` | search-options | - |
+| `tests/sourcing-utils.test.ts` | sourcing-utils | fixture/parser |
+| `tests/state.test.ts` | state | live/session-sensitive |
+| `tests/supplier-inspect.test.ts` | supplier-inspect | browser/page-state, fixture/parser |
+| `tests/supplier-search.test.ts` | supplier-search | browser/page-state, fixture/parser |
+| `tests/wait.test.ts` | wait | - |

package/docs/playbooks/add-command.md

@@ -0,0 +1,15 @@
+# Playbook: Add A Command
+
+1. Add the Commander surface in `src/cli.ts`.
+2. Create or update the owning module in `src/commands`.
+3. Keep CLI parsing in `run(opts)` and browser/session work in
+   `execute(ctx, args)` when daemon dispatch is needed.
+4. Wire daemon dispatch in `src/session/dispatch.ts` if the command should run
+   through the daemon.
+5. Use `emit({ human, data })` so JSON/text dual mode stays consistent.
+6. Add deterministic tests for parsing, output, mtop payload parsing, or helper
+   behavior.
+7. Update `docs/COMMANDS.md` and `docs/JSON_CONTRACTS.md` when behavior or
+   output shape changes.
+8. Run `pnpm agent-context` and the focused verification command.
+

package/docs/playbooks/add-mtop-capture.md

@@ -0,0 +1,13 @@
+# Playbook: Add Mtop Capture
+
+1. Probe the browser flow manually only when needed and safe.
+2. Capture the smallest stable endpoint/method/appId signal.
+3. Add parsing logic under `src/session` when it is shared, or in the command
+   module when it is command-specific.
+4. Save representative payloads as tests fixtures when they do not contain
+   sensitive account data.
+5. Return structured `CliError` failures for timeout, login redirect,
+   risk-control, and parse failure.
+6. Update `docs/JSON_CONTRACTS.md` if the capture changes agent-facing output.
+7. Run focused parser/capture tests, then `pnpm agent-context`.
+

package/docs/playbooks/change-json-output.md

@@ -0,0 +1,11 @@
+# Playbook: Change JSON Output
+
+1. Identify the stable result interface in `src/commands/*`.
+2. Prefer additive fields. Do not rename or remove fields unless the user
+   approved a breaking change.
+3. Update human rendering only after preserving machine output.
+4. Add or update tests for the JSON shape or parser feeding it.
+5. Update `docs/JSON_CONTRACTS.md`.
+6. Run `pnpm agent-context`.
+7. Run `pnpm test` or a focused test plus `pnpm docs-check`.
+

package/docs/playbooks/debug-risk-control.md

@@ -0,0 +1,12 @@
+# Playbook: Debug Risk Control
+
+1. Confirm whether the failure is login redirect, risk-control URL, empty mtop
+   capture, network error, or browser closure.
+2. Check structured exit code behavior. Exit `3` should point to `1688 login`;
+   exit `4` should point to rerunning once with `--headed`.
+3. Use `--headed` only when manual slider solving is expected.
+4. Inspect `src/session/page-state.ts`, `src/session/recovery.ts`, and the
+   relevant command's capture logic.
+5. Add fixture-backed tests for page-state or parser changes.
+6. Do not add silent retry loops around risk-control failures.
+

package/docs/playbooks/update-cli-release.md

@@ -0,0 +1,61 @@
+# Playbook: Update CLI Release Behavior
+
+Use this playbook for version bumps, npm publishes, GitHub release/tag work,
+postinstall changes, and update-notifier behavior.
+
+## Release Checklist
+
+1. Update `CHANGELOG.md` first.
+   - Keep current in-progress docs/features under `## [Unreleased]`.
+   - Before publishing, move released items into
+     `## [x.y.z] - YYYY-MM-DD`.
+   - Do not describe post-tag work as part of an already-published npm version.
+2. Check `package.json`, `README.md`, npm metadata, and update-notifier behavior
+   in `src/cli.ts`.
+3. Preserve the update protocol in `docs/SAFETY.md`: never run a global install
+   command without explicit current-turn user approval.
+4. If daemon behavior changes after upgrade, document whether
+   `1688 daemon reload` is required.
+5. Run:
+
+   ```bash
+   pnpm agent-context
+   pnpm agent-verify
+   npm pack --dry-run
+   ```
+
+6. Verify the release gate explicitly:
+
+   ```bash
+   pnpm release-check
+   ```
+
+7. Publish only after npm auth is valid:
+
+   ```bash
+   npm whoami
+   npm publish
+   ```
+
+8. Push both branch and tag. Lightweight tags are not pushed by
+   `git push --follow-tags`, so push the release tag explicitly:
+
+   ```bash
+   git push origin main
+   git push origin vX.Y.Z
+   ```
+
+9. After publish, verify:
+
+   ```bash
+   npm view 1688-cli version dist-tags --json
+   npm view 1688-cli@X.Y.Z readmeFilename version --json
+   git ls-remote --tags origin refs/tags/vX.Y.Z
+   ```
+
+## Omission Tracking
+
+If a release step is missed, record it in
+`docs/records/release-omissions.md` with symptom, cause, fix, and prevention.
+Then update this playbook or a script so the same omission becomes harder to
+repeat.

package/docs/records/release-omissions.md

@@ -0,0 +1,34 @@
+# Release Omissions
+
+Record release misses here so the process improves instead of relying on memory.
+
+## 2026-06-08 - 0.1.42 CHANGELOG Omitted
+
+### Symptom
+
+After `1688-cli@0.1.42` was published and pushed, the GitHub file list still
+showed `CHANGELOG.md` last changed by `chore(release): 0.1.41`. The npm
+package included the old changelog because the 0.1.42 release commit only
+bumped `package.json`.
+
+### Cause
+
+The release playbook said to check `CHANGELOG.md`, but there was no executable
+gate in `agent-verify` or `prepublishOnly` to fail when the package version was
+missing from `CHANGELOG.md`.
+
+### Fix
+
+- Backfilled `CHANGELOG.md` with a `0.1.42` section for released work.
+- Added an `Unreleased` section for post-tag README/npm-metadata documentation
+  changes that should ship in the next npm version.
+- Added `pnpm release-check`, backed by `scripts/check_release.mjs`.
+- Added `release-check` to `pnpm agent-verify` and `prepublishOnly`.
+- Expanded `docs/playbooks/update-cli-release.md` with changelog, npm, tag, and
+  post-publish verification steps.
+
+### Prevention
+
+Before the next publish, move `Unreleased` items into the new version section,
+run `pnpm agent-verify`, run `npm pack --dry-run`, and push the release tag
+explicitly with `git push origin vX.Y.Z`.

package/docs/specs/checkout-and-orders.md

@@ -0,0 +1,30 @@
+# Checkout And Orders
+
+Checkout and order tracking commands operate real buyer state.
+
+## Commands
+
+```bash
+1688 checkout prepare <cartIds...>
+1688 checkout confirm <cartIds...>
+1688 order list [--status <status>]
+1688 order get <orderId>
+1688 order logistics <orderId>
+1688 shipped <orderId>
+1688 stuck [--days N]
+1688 fake-shipped [--days N]
+1688 seller-history <sellerName>
+```
+
+## Checkout Boundary
+
+`checkout prepare` is read-only. `checkout confirm` places a real order and
+must follow the protocol in `docs/SAFETY.md`.
+
+## Agent Requirements
+
+- Preserve order IDs, seller identity, totals, line items, services, badges,
+  actions, and logistics trace fields.
+- Keep overdue/fake-shipped workflows explainable: include thresholds and the
+  evidence used to flag each order.
+- Never hide partial scans; report scan limits and blockers.

package/docs/specs/index.md

@@ -0,0 +1,9 @@
+# Specs Index
+
+- [Checkout And Orders](checkout-and-orders.md)
+- [Profile Daemon](profile-daemon.md)
+- [Seller IM](seller-im.md)
+- [Sourcing Research](sourcing-research.md)
+- [Supplier Inspect](supplier-inspect.md)
+- [Supplier Search](supplier-search.md)
+- [Windows CLI Compatibility](windows-cli-compatibility.md)