1688-cli 0.1.41 → 0.1.43

package/AGENTS.md

@@ -1,318 +1,112 @@
-# 1688 — 1688 CLI for agents
-
-When the user asks anything about 1688 sourcing, products, orders, or
-logistics, use the `1688` CLI. It outputs JSON automatically when stdout
-is piped, so `1688 <cmd> | jq` works.
-
-## Current commands
-
-Organized by buyer journey: sourcing → inquiry → cart → checkout → tracking → post-sale.
-
-```
-# Sourcing
-1688 search <keyword>                       Keyword search; --max N to limit.
-1688 search --headed                        Open window once if a slider verification appears.
-1688 similar <offerId>                      "找同款" — similar offers from other suppliers, sorted by price.
-1688 image-search <pathOrUrl>               Search by image (local .jpg/.png/.webp file or http(s) URL).
-1688 offer <offerId>                        Full product detail: title, priceTiers, SKUs, attributes,
-                                            packageInfo, supplier (loginId/memberId/province/city).
-
-# Pre-sale inquiry (seller IM, scoped by offerId)
-1688 seller inquire <offerId> <message>     Send product link + question to the supplier.
-1688 seller messages --offer <offerId>      Read replies in this offer's conversation.
-1688 seller messages --offer <offerId> --watch [--interval N]
-                                            Live-tail new replies (line-delimited JSON when piped).
-                                            Long-running; min interval 10 s, default 30 s.
-
-# Cart
-1688 cart list                              List items in 1688 cart (采购车).
-1688 cart add <offerId> --sku <skuId> --qty N
-                                            Add SKU to cart (~6 s, mtop hijack). Returns
-                                            {added: CartItem, isNewRow, addedQuantity}.
-1688 cart remove <cartId>                   Remove one cart row (~12 s, UI replay).
-
-# Checkout
-1688 checkout prepare <cartId>...           Preview total/address/items (NO order placement).
-1688 checkout confirm <cartId>...           PLACE order — TTY+prompt by default.
-1688 checkout confirm <cartId>... --agent   Agent mode: no prompt; use only after explicit approval.
-                                            MUST be preceded by `prepare` shown to the user AND
-                                            explicit user authorization in the current turn.
-
-# Order tracking
-1688 order list                             List buyer orders; --status, --page, --page-size flags.
-                                            Each order has actions[] (buyer ops + URLs), services[]
-                                            (insurance/refund), badges[].
-1688 order list --status waitbuyerreceive   Filter to "awaiting delivery".
-1688 order get <orderId>                    One order by ID (--max-scan-pages N, --status hint).
-1688 order logistics <orderId>              Tracking number + trace (mailNo, carrier, remark).
-1688 shipped <orderId>                      Order detail + logistics merged into one call.
-1688 stuck [--days N]                       Paid but not shipped > N days (default 3).
-1688 fake-shipped [--days N] [--debug]      Marked shipped but courier never collected (虚假发货).
-1688 seller-history <sellerName>            All orders from a seller + avg ship days + on-time rate.
-
-# Post-sale chat (seller IM, scoped by orderId)
-1688 seller chat <orderId|loginId> <message>
-                                            Send to seller. With orderId, auto-attaches the order card.
-1688 seller chat <orderId> <message> --no-card
-                                            Follow-up reply, no card.
-1688 seller messages <orderId>              Read replies in this order's conversation.
-1688 seller messages <orderId> --watch      Live-tail (same as the --offer form above).
-
-# Account & daemon
-1688 login                                  Show QR code; user scans with phone.
-1688 login --headed                         Use a real browser window instead (fallback).
-1688 login --force                          Re-login even if a session exists.
-1688 logout [--yes]                         Log out (prompts unless --yes).
-1688 whoami [--verify]                      Print current account; exit 3 if not logged in.
-1688 doctor [--no-launch]                   Diagnose environment + session state.
-1688 daemon start | stop | status | reload  Manage the background daemon.
-1688 serve                                  Run the daemon in the foreground.
-```
-
-## Daemon (recommended for agent use)
-
-When the daemon is running, commands route through it and share a single
-Chromium context. Benefits:
-- ~2-3 seconds saved per command (no Chrome cold start)
-- One continuous logged-in session across commands
-- Built-in inter-command jitter (1.2-3 s)
-
-The agent should call `1688 daemon start` once at the beginning of a session
-that involves multiple 1688 commands. The daemon auto-stops after 30 minutes
-of inactivity. Run `1688 daemon reload` after the package updates to pick up
-new code.
-
-`login`, `logout`, `doctor` stay inline; they need interactive UI or browser
-windows. If the daemon is running and you need to `login --force`, stop the
-daemon first.
-
-## Watch mode (long-running streams)
-
-`1688 seller messages ... --watch` is a long-running command. It:
-- Prints `Baseline: <conversation> — N messages in history` to stderr on start
-- Emits one line of JSON to stdout per **newly-arrived** message (history is
-  not re-emitted)
-- Dedup is by server-side `messageId`
-- Default interval 30 s, minimum 10 s, override with `--interval <seconds>`
-- Exits cleanly on SIGINT (Ctrl+C)
-
-For agent loops, pipe stdout into a `while read line` and parse each line as
-its own JSON object. Do not assume the process will exit — it is meant to
-stay alive.
-
-## Exit codes
-
-| Code | Meaning |
-|------|---------|
-| 0 | Success |
-| 2 | Bad invocation (missing flag, etc.) |
-| 3 | Not logged in / session expired |
-| 5 | Another 1688 command is running (lock busy) |
-| 6 | Chromium not installed |
-| 7 | Login wait timeout |
-| 4 | Aliyun risk control (slider verification) — retry with `--headed` |
-| 8 | Login finished but cookies missing |
-| 9 | Network error |
-| 130 | User canceled |
-
-## Status filter values (for `order list --status`)
-
-| value | meaning |
-|---|---|
-| `all` | All orders |
-| `waitbuyerpay` | 待付款 |
-| `waitsellersend` | 待发货 |
-| `waitbuyerreceive` | 待收货 |
-| `success` | 已完成 |
-| `cancel` | 已取消 |
-
-## Rules for the agent
-
-- `1688 login` opens a window the user must interact with. Only run it
-  yourself if the user explicitly asks you to log in.
-- `1688 logout` requires `--yes` in non-interactive mode. Do not pass
-  `--yes` without explicit user confirmation in the current turn.
-- If a command returns exit 3, tell the user to run `1688 login`.
-  Do not loop or retry on your own.
-- If a command returns exit 4 (risk control), tell the user to run the
-  same command once with `--headed` (they will need to drag a slider).
-  Do not retry the same command silently.
-- **`1688 checkout confirm` requires a TTY by default**, OR `--agent` flag.
-  It places real orders (no payment yet, but commits to seller). 
-  
-  **Agent protocol for placing orders:**
-  1. Run `1688 checkout prepare <cartIds>` first
-  2. SHOW the user the full preview (total, items, address, seller)
-  3. WAIT for the user's explicit "yes, place it" / "下单吧" in the current turn
-  4. Only then run `1688 checkout confirm <cartIds> --agent`
-  5. Report the final orderId / URL back to the user
-  
-  NEVER run `--agent` without the prepare+approval cycle. NEVER infer authorization
-  from older messages — it must be explicit in the CURRENT turn.
-- JSON output of `whoami`:
-  ```json
-  {"loggedIn": true, "memberId": "...", "nick": "...", "lastVerifiedAt": "..."}
-  {"loggedIn": false}
-  ```
-
-## Key JSON shapes
-
-### `seller messages` result
-
-```ts
-{
-  conversation: string,
-  total: number,
-  messages: Array<{
-    sender: string,
-    time: string | null,            // "YYYY-MM-DD HH:MM:SS" in +08:00
-    isMine: boolean,
-    content: string,
-    read: boolean,
-    kind: "text" | "offerCard" | "orderCard" | "autoReply"
-        | "assessment" | "image" | "other",
-    card?: { title: string|null, price: string|null,
-             image: string|null, url: string|null },
-    messageId?: string,             // present when sourced from WS
-  }>,
-}
-```
-
-`--watch` mode emits per-message instead:
-```ts
-{ conversation: string, message: <one item from messages[] above> }
-```
-
-### `cart add` result
-
-```ts
-{
-  ok: boolean,
-  added: CartItem,                  // see `cart list` JSON for full shape
-  isNewRow: boolean,                // true=new cartId, false=merged into existing row
-  addedQuantity: number,            // delta this call added (== args.quantity for new row)
-}
-```
-
-To get the cartId reliably in a pipeline:
-```bash
-id=$(1688 cart add <offerId> --sku <skuId> --qty 1 | jq -r '.added.cartId')
-```
-
-## Output flags (every command)
-
-In addition to `BB1688_JSON=1`, every command accepts:
-
-```
---json            Force JSON output even in a TTY.
---pretty          Indent JSON by 2 spaces.
---get <path>      Print one field by dot-path. Scalar → raw line,
-                  object/array → JSON. Wildcards stream one element per line.
-                  Syntax: field.sub, arr[N].field, arr[*].field
---pick <paths>    Comma-separated dot-paths → emit a JSON object with each
-                  path as a key. Useful for trimming output for downstream agents.
-```
-
-Examples:
-```bash
-1688 offer X --get supplier.name              # 深圳... (raw)
-1688 offer X --get supplier                   # {"name":"...","loginId":"..."}
-1688 offer X --get 'skus[*].price'            # 49 \n 68 \n 98.75 ...
-1688 offer X --pick price,supplier.name       # {"price":1.25,"supplier.name":"..."}
-1688 offer X --json --pretty                  # full payload, indented
-```
-
-When `--get`/`--pick` is given, the human renderer is skipped; the resolved
-value(s) go to stdout. The full payload still flows through when neither
-flag is set, so existing `| jq` pipelines keep working.
-
-## Login in non-interactive sessions (Codex / Claude Code / scripted)
-
-`1688 login` displays a QR code on stderr. ASCII rendering only works on
-a real TTY — when invoked from an agent, stderr is usually piped and the
-ASCII art either does not render or appears garbled.
-
-The login command always **also** saves the QR as a PNG to
-`~/.1688/login-qr.png` (`%USERPROFILE%\.1688\login-qr.png` on Windows)
-and writes `QR saved as PNG: <path>` on stderr. The agent should:
-
-1. Watch stderr for the `QR saved as PNG:` line.
-2. Surface that file to the user (display the image inline, or tell the
-   user the exact path so they can open it).
-3. Wait for the command to exit naturally — the user must scan the QR
-   with their 1688 mobile app within the timeout (default 300 s).
-
-Do not attempt to "open" the raw QR URL in a browser — it is a token URL
-that only the 1688 app can consume, not a human-readable page.
-
-## Feedback / bug reports
-
-```
-1688 feedback "<message>"            Open a pre-filled GitHub issue (TTY browser).
-1688 feedback --bug "<details>"      Tag the issue as a bug.
-1688 feedback --no-open "<msg>"      Just print the URL — useful for agents to
-                                     show the user without opening a browser
-                                     on the agent's machine.
-1688 feedback "<msg>" --submit       Post the issue DIRECTLY via the `gh` CLI
-                                     (requires `gh auth login`). Skips the
-                                     "Submit new issue" click in the browser.
-```
-
-**Agent rule for `--submit`**: do NOT add `--submit` on the agent's own
-initiative. Always run without `--submit` first, show the user the
-generated URL, and only re-run with `--submit` if the user explicitly
-asks ("submit it" / "直接发吧" / "post the issue"). Posting an issue is
-a public write action.
-
-The CLI auto-attaches anonymized environment info (version, Node, OS) and
-the last error from `daemon.log` if present. Nothing about the user's
-1688 account is sent. The actual submission still requires the user to
-click "Submit new issue" in the browser — the CLI only prepares the URL.
-
-## Update awareness
-
-At the start of a session that runs multiple 1688 commands, run
-`1688 doctor`. Its JSON output includes a `version` block:
-
-```json
-{
-  "version": {
-    "current": "0.1.27",
-    "latest":  "0.1.29",
-    "updateAvailable": true,
-    "updateCommand":   "npm i -g 1688-cli@latest",
-    "error": null
-  }
-}
-```
-
-You can also detect updates from any command: in JSON mode (piped / `--json`
-/ `BB1688_JSON=1`), a single line of structured JSON appears on stderr
-when a newer version is cached:
-
-```
-{"_notice":"updateAvailable","current":"0.1.27","latest":"0.1.29","updateCommand":"npm i -g 1688-cli@latest"}
-```
-
-### Rules for upgrades
-
-- **Interactive session** (TTY, the user is watching the conversation):
-  ask the user once whether to upgrade now. Show the current → latest
-  versions and the install command. If the user agrees, run
-  `updateCommand`, then `1688 daemon reload` to pick up the new code.
-
-- **Non-interactive** (CI, cron, scripted agent loop with no human in
-  the loop): do NOT upgrade on your own. Log the notice to stderr and
-  continue. Pinning is intentional in those contexts.
-
-- Never run the install command without explicit user authorization in
-  the CURRENT turn. The CLI version is part of the user's global
-  environment; treat it the same way you treat any `sudo` or
-  "modify global state" action.
-
-- Ask at most once per session. If the user declines or postpones,
-  don't ask again in the same session.
-
-## Discovery
-
-Run `1688 --help` and `1688 <command> --help` for the latest flags.
+# Agent Map
+
+This file is the short entry point for coding agents. Treat it as a map, not
+as the full manual. Load deeper context from `ARCHITECTURE.md` and `docs/`
+only when the task needs it.
+
+## First Read
+
+- Agent working principles: `docs/AGENT_WORKING_PRINCIPLES.md`
+- System architecture: `ARCHITECTURE.md`
+- Documentation map: `docs/README.md`
+- Default workflow: `docs/WORKFLOW.md`
+- Command catalog: `docs/COMMANDS.md`
+- JSON contracts: `docs/JSON_CONTRACTS.md`
+- Safety and approval rules: `docs/SAFETY.md`
+- Reliability and browser/session behavior: `docs/RELIABILITY.md`
+- Quality score and known gaps: `docs/QUALITY_SCORE.md`
+
+## Project Shape
+
+- `src/cli.ts`: Commander CLI surface and command routing.
+- `src/commands`: command executors and human renderers.
+- `src/session`: Playwright browser/session helpers, mtop capture, locators,
+  recovery, lock, state, and artifacts.
+- `src/daemon`: background daemon client/server/protocol/throttle.
+- `src/io`: JSON/text output, prompts, and structured errors.
+- `src/auth`: login/session verification and cookie helpers.
+- `src/util`: small shared utilities.
+- `tests`: deterministic Vitest coverage and fixtures.
+- `scripts`: probes, postinstall, and agent-map utilities.
+- `docs`: canonical agent-readable knowledge base.
+
+## Common Commands
+
+- Install deps: `pnpm install`
+- Typecheck: `pnpm typecheck`
+- Deterministic tests: `pnpm test:unit`
+- Full test run, including live doctor checks: `pnpm test`
+- Build CLI: `pnpm build`
+- Generate agent indexes: `pnpm agent-context`
+- Check generated indexes: `pnpm docs-check`
+- Check map structure: `pnpm agent-map-check`
+- Default agent gate: `pnpm agent-verify`
+
+`pnpm agent-verify` is the default green gate. If it fails, report the exact
+failure instead of hiding it.
+
+## Task Routing
+
+- New or changed CLI command: read `docs/playbooks/add-command.md`,
+  `docs/COMMANDS.md`, and the relevant `src/commands/*` file.
+- JSON output change: read `docs/playbooks/change-json-output.md` and
+  `docs/JSON_CONTRACTS.md`; preserve compatibility unless the user approved a
+  breaking change.
+- Browser risk-control / slider / login issue: read
+  `docs/playbooks/debug-risk-control.md`, `docs/SAFETY.md`, and
+  `docs/RELIABILITY.md`.
+- New mtop or response capture: read `docs/playbooks/add-mtop-capture.md` and
+  existing helpers in `src/session/*capture*.ts`.
+- Release/update behavior: read `docs/playbooks/update-cli-release.md`.
+- Sourcing research features: read `docs/specs/sourcing-research.md`
+  and `docs/FEATURES.md`.
+- Supplier search/research work: read `docs/specs/supplier-search.md`.
+- Seller IM work: read `docs/specs/seller-im.md`.
+- Checkout/order work: read `docs/specs/checkout-and-orders.md` and
+  `docs/SAFETY.md`.
+- Complex feature/refactor: create or update an ExecPlan under
+  `docs/exec-plans/active/`.
+
+## 1688 Runtime Rules
+
+- For 1688 sourcing, products, orders, or logistics, use the `1688` CLI.
+- It outputs JSON automatically when stdout is piped, so
+  `1688 <cmd> | jq` works.
+- At the start of a multi-command 1688 session, run
+  `1688 doctor --no-launch --json` and start the daemon when useful with
+  `1688 daemon start`.
+- If a command returns exit `3`, tell the user to run `1688 login`; do not
+  retry in a loop.
+- If a command returns exit `4`, tell the user to run the same command once
+  with `--headed` and solve the slider manually; do not silently retry.
+- `1688 login` opens a user-interactive QR/browser flow. Run it only when the
+  user explicitly asks to log in.
+- `1688 logout --yes` requires explicit current-turn confirmation.
+- Seller messages `--watch` is long-running and emits one JSON object per new
+  message.
+
+## Write-Action Boundaries
+
+These commands contact sellers, modify buyer state, or place orders. Use the
+protocols in `docs/SAFETY.md`.
+
+- `1688 seller inquire <offerId> <message>`
+- `1688 seller chat <orderId|loginId> <message>`
+- `1688 cart add <offerId> --sku <skuId> --qty N`
+- `1688 cart remove <cartId>`
+- `1688 checkout confirm <cartIds...>`
+- `1688 feedback "<message>" --submit`
+- `1688 logout --yes`
+
+Hard rule: never run `1688 checkout confirm ... --agent` unless
+`1688 checkout prepare <cartIds...>` was shown to the user and the user gave
+explicit current-turn approval to place the order.
+
+## Done Criteria
+
+- Relevant docs/playbooks/specs were read and updated if behavior changed.
+- `pnpm agent-context` was run after command, JSON contract, source layout, or
+  test layout changes.
+- `pnpm agent-verify` was run, or the exact blocker is recorded.
+- For complex work, active ExecPlans contain progress, decisions, and latest
+  verification.

package/ARCHITECTURE.md

@@ -0,0 +1,107 @@
+# Architecture
+
+`1688-cli` is a TypeScript command-line tool for Alibaba 1688 buyer workflows:
+sourcing, seller IM, cart, checkout, order tracking, and logistics follow-up.
+It uses Playwright with a persistent browser profile, a daemon for warm
+sessions, and stable JSON output for agents.
+
+## Layer Map
+
+```text
+src/cli.ts
+  -> src/commands
+  -> src/session
+  -> src/daemon
+  -> src/io
+  -> src/auth
+  -> src/util
+tests -> src/*
+docs/generated -> scripts/generate_agent_context.mjs
+```
+
+## Layer Responsibilities
+
+`src/cli.ts` owns the public command surface: command names, options,
+arguments, and lazy imports.
+
+`src/commands` owns user-visible behavior for each command. A command usually
+contains:
+
+- option parsing / validation
+- `execute(ctx, args)` for daemon-dispatched work
+- `run(opts)` for CLI invocation
+- human rendering through `emit({ human, data })`
+
+`src/session` owns browser automation primitives: Playwright context setup,
+mtop/response capture, locators, recovery, locking, page-state detection,
+navigation guards, artifacts, and timing helpers.
+
+`src/daemon` owns the long-lived background process, request protocol,
+client/server dispatch, and inter-command throttling.
+
+`src/io` owns output compatibility, JSON flags, prompts, and structured
+`CliError` behavior.
+
+`src/auth` owns login/session verification and cookie handling.
+
+`src/util` owns small shared helpers.
+
+`tests` owns deterministic Vitest coverage. Live/browser flows should be
+guarded or documented when they cannot be deterministic.
+
+`docs` owns durable agent-readable knowledge. `docs/generated/*` is generated
+by `scripts/generate_agent_context.mjs`.
+
+## Dependency Rules
+
+- CLI routing may import commands lazily, but command modules should not import
+  `src/cli.ts`.
+- Command modules may use `src/session`, `src/daemon/dispatch` indirectly,
+  `src/io`, `src/auth`, and `src/util`.
+- `src/session` should not depend on command modules, except shared types only
+  when there is no cleaner local session type.
+- `src/io` should stay browser-free and command-agnostic.
+- `src/daemon` should depend on command executors through explicit dispatch
+  wiring, not dynamic ad-hoc imports from arbitrary modules.
+- JSON-facing result interfaces should live near the owning command and be
+  documented in `docs/JSON_CONTRACTS.md` when stable for agents.
+
+## Major Domains
+
+- Sourcing: `search`, `similar`, `image-search`, `offer`.
+- Pre-sale seller IM: `seller inquire`, `seller messages --offer`.
+- Cart: `cart list`, `cart add`, `cart remove`.
+- Checkout: `checkout prepare`, `checkout confirm`.
+- Order tracking: `order list`, `order get`, `order logistics`, `shipped`,
+  `stuck`, `fake-shipped`, `seller-history`.
+- Post-sale seller IM: `seller chat`, `seller messages <orderId|loginId>`.
+- Account/session: `login`, `logout`, `whoami`, `doctor`, `daemon`, `serve`.
+
+## Browser And Session Model
+
+- The tool uses persistent browser profiles under `~/.1688`.
+- Each daemon is bound to one profile, reuses that profile's browser context,
+  and adds jitter between commands.
+- Commands should handle login redirects, risk-control pages, and browser
+  closure through structured exit codes.
+- `--headed` is the manual escape hatch for slider verification.
+- Browser probes under `scripts/probe-*.mjs` are exploratory tools, not stable
+  verification gates.
+
+## Generated Context
+
+- Run `pnpm agent-context` after changing commands, source layout, tests, or
+  exported JSON result interfaces.
+- Generated files live under `docs/generated`.
+- Do not hand-edit generated files; change
+  `scripts/generate_agent_context.mjs` instead.
+
+## Verification Surfaces
+
+- Type safety: `pnpm typecheck`
+- Deterministic tests: `pnpm test:unit`
+- Full test suite including live doctor checks: `pnpm test`
+- Agent indexes: `pnpm agent-context`
+- Generated docs freshness: `pnpm docs-check`
+- Agent map structure: `pnpm agent-map-check`
+- Default gate: `pnpm agent-verify`

package/CHANGELOG.md

@@ -3,6 +3,85 @@
 All notable changes to this project are documented here.
 This project follows [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.1.43] - 2026-06-16
+
+### Added
+- **Profile-scoped daemons.** Added one-daemon-per-profile runtime support:
+  `1688 serve --profile <name>` and
+  `1688 daemon start|stop|status|reload --profile <name>` now manage the
+  selected profile's daemon independently.
+- **Profile-scoped runtime artifacts.** Daemon socket or Windows named pipe,
+  pid, version, log, lock, and cached identity state are now scoped per
+  profile. Different profiles can run in parallel without contending on one
+  global lock.
+- **Profile-aware command dispatch.** Commands such as
+  `1688 search "实木床头柜" --profile acc-a` now try the `acc-a` daemon first
+  instead of falling back inline solely because `--profile` was present.
+- **Profile diagnostics.** `doctor --profile <name>` and
+  `profile status <name>` now report that profile's daemon, lock, login state,
+  and recent command state.
+
+### Changed
+- `login --profile <name>` now writes that profile's state and can auto-start
+  the same profile daemon after login.
+- Inline fallback and checkout-confirm daemon pausing now stop only the
+  selected profile daemon, leaving other profile daemons running.
+- Default profile behavior remains compatible: commands without `--profile`
+  continue to use `default` and the historical default daemon artifact paths.
+
+### Docs
+- Split the README sourcing section into two separate user paths:
+  **Product Scraper / Product Research** and **Supplier Scraper / Supplier
+  Research**, with a quick command-selection table.
+- Updated package metadata locally with scraper-oriented description and
+  keywords (`supplier-scraper`, `product-scraper`, `supplier-search`,
+  `sourcing`). These npm metadata changes will appear on npm on the next
+  published version.
+- Documented multi-profile daemon usage, default-profile compatibility,
+  profile-scoped files, and Windows named-pipe behavior.
+
+### Tests
+- Added deterministic coverage for profile-scoped daemon paths, Windows pipe
+  names, profile state separation, and profile status diagnostics.
+
+## [0.1.42] - 2026-06-08
+
+### Added
+- **Sourcing research workflow.** Added `1688 research` for multi-keyword
+  product research datasets with scoring, JSONL/CSV export, and optional
+  top-N offer enrichment.
+- **Supplier scraper/research workflow.** Added `1688 supplier search` and
+  `1688 supplier research`, backed by 1688 company search
+  (`companySearchBusinessService`) instead of grouping product-offer results.
+  Supplier results include company identity, memberId, location, service
+  years, factory signals, repeat/response rates, order/amount signals,
+  previews, score, and export support.
+- **Supplier inspection.** Added `1688 supplier inspect` for supplier/factory
+  trust signals from an offerId or `b2b-*` memberId.
+- **Offer comparison.** Added `1688 compare <offerId...>` for side-by-side
+  price, MOQ, SKU depth, sales, supplier, freight/package, and score signals.
+- **Agent map and harness.** Added the short `AGENTS.md` entrypoint,
+  `ARCHITECTURE.md`, docs/specs/playbooks, generated agent indexes, completed
+  ExecPlans, and the default `pnpm agent-verify` gate.
+
+### Changed
+- **Search sourcing filters.** Added sorted/filtered sourcing controls such as
+  sort modes, price range, location, verified supplier, minimum turnover/order
+  signals, and optional ad exclusion.
+- **Windows CLI compatibility baseline.** Replaced shell `chmod` in the build
+  with a Node helper, made Windows daemon named pipes root-hashed, made
+  postinstall/doctor hints platform-aware, moved production temp debug paths to
+  `os.tmpdir()`, and added PowerShell/Windows docs.
+- **Documentation packaging.** Published the expanded agent-readable docs and
+  generated indexes in the npm package.
+
+### Tests
+- Added deterministic tests for sourcing scoring/export helpers, supplier
+  inspect/search behavior, Windows path/doctor/bin-mode helpers, and search
+  option handling.
+
 ## [0.1.41] - 2026-05-16
 
 ### Added