@jackwener/opencli 1.4.1 → 1.5.0

package/docs/adapters/browser/linux-do.md

@@ -6,37 +6,198 @@
 
 | Command | Description |
 |---------|-------------|
-| `opencli linux-do hot` | 热门话题 |
-| `opencli linux-do latest` | 最新话题 |
-| `opencli linux-do categories` | 板块列表 |
-| `opencli linux-do category` | 板块话题 |
-| `opencli linux-do search` | 搜索话题 |
-| `opencli linux-do topic` | 话题详情 |
+| `opencli linux-do feed` | Browse topics (site-wide, by tag, or by category) |
+| `opencli linux-do categories` | List all categories |
+| `opencli linux-do tags` | List popular tags |
+| `opencli linux-do search <query>` | Search topics |
+| `opencli linux-do topic <id>` | View topic posts |
+| `opencli linux-do user-topics <username>` | Topics created by a user |
+| `opencli linux-do user-posts <username>` | Replies posted by a user |
 
-## Usage Examples
+## feed
+
+Browse topic listings. Defaults to latest topics when called with no arguments.
+
+- Supports filtering by `--tag`, `--category`, or both
+- `--tag` accepts tag name, slug, or ID
+- `--category` accepts category name, slug, ID, or `Parent / Child` path for sub-categories
+- Use `--view` to switch between latest / hot / top
+
+### Basic
 
 ```bash
-# Hot topics this week
-opencli linux-do hot --limit 20
+# Latest topics (default)
+opencli linux-do feed
+
+# Hot topics
+opencli linux-do feed --view hot
+
+# Top topics — default period is weekly
+opencli linux-do feed --view top
+opencli linux-do feed --view top --period daily
+opencli linux-do feed --view top --period monthly
 
-# Hot topics by period
-opencli linux-do hot --period daily
-opencli linux-do hot --period monthly
+# Sort by views descending
+opencli linux-do feed --order views
+
+# Sort by created time ascending
+opencli linux-do feed --order created --ascending
+
+# Limit results
+opencli linux-do feed --limit 10
+
+# JSON output
+opencli linux-do feed -f json
+```
 
-# Latest topics
-opencli linux-do latest --limit 10
+### Filter by tag
+
+```bash
+# By tag name, slug, or ID — all equivalent
+opencli linux-do feed --tag "ChatGPT"
+opencli linux-do feed --tag chatgpt
+opencli linux-do feed --tag 3
+
+# Tag + hot view
+opencli linux-do feed --tag "ChatGPT" --view hot
+
+# Tag + top view with period
+opencli linux-do feed --tag "OpenAI" --view top --period monthly
+```
+
+### Filter by category
+
+Supports both top-level and sub-categories. Sub-categories auto-resolve their parent path.
+
+```bash
+# Top-level category — name, slug, or ID
+opencli linux-do feed --category "开发调优"
+opencli linux-do feed --category develop
+opencli linux-do feed --category 4
 
-# List all categories
+# Sub-category
+opencli linux-do feed --category "开发调优 / Lv1"
+opencli linux-do feed --category "网盘资源"
+
+# Category + hot / top view
+opencli linux-do feed --category "开发调优" --view hot
+opencli linux-do feed --category "开发调优" --view top --period weekly
+```
+
+### Category + tag
+
+Combine `--category` and `--tag` to narrow results within a category.
+
+```bash
+opencli linux-do feed --category "开发调优" --tag "ChatGPT"
+opencli linux-do feed --category "网盘资源" --tag "OpenAI"
+opencli linux-do feed --category 94 --tag 4 --view top --period monthly
+```
+
+### Parameters
+
+| Parameter | Description | Default |
+|-----------|-------------|---------|
+| `--view V` | `latest`, `hot`, `top` | `latest` |
+| `--tag VALUE` | Tag name, slug, or ID | — |
+| `--category VALUE` | Category name, slug, or ID | — |
+| `--limit N` | Number of results | `20` |
+| `--order O` | `default`, `created`, `activity`, `views`, `posts`, `category`, `likes`, `op_likes`, `posters` | `default` |
+| `--ascending` | Sort ascending instead of descending | off |
+| `--period P` | `all`, `daily`, `weekly`, `monthly`, `quarterly`, `yearly` (only with `--view top`) | `weekly` |
+
+Output columns: `title`, `replies`, `created`, `likes`, `views`, `url`
+
+## categories
+
+List forum categories with optional sub-category expansion.
+
+```bash
 opencli linux-do categories
+opencli linux-do categories --subcategories
+opencli linux-do categories --limit 50
+```
+
+When `--subcategories` is enabled, sub-categories are rendered as `Parent / Child` so the `name` value can be copied directly into `opencli linux-do feed --category ...`.
+
+Output columns: `name`, `slug`, `id`, `topics`, `description`
+
+## tags
 
-# Search topics
+List tags sorted by usage count.
+
+```bash
+opencli linux-do tags
+opencli linux-do tags --limit 50
+```
+
+Output columns: `rank`, `name`, `count`, `url`
+
+## search
+
+Search topics by keyword.
+
+```bash
 opencli linux-do search "NixOS"
+opencli linux-do search "Docker" --limit 10
+opencli linux-do search "Claude" -f json
+```
 
-# View topic details
-opencli linux-do topic 12345
+Output columns: `rank`, `title`, `views`, `likes`, `replies`, `url`
 
-# JSON output
-opencli linux-do hot -f json
+## topic
+
+View posts within a topic (first page).
+
+```bash
+opencli linux-do topic 1234
+opencli linux-do topic 1234 --limit 50
+opencli linux-do topic 1234 --main_only -f json | jq -r '.[0].content'
+```
+
+Notes:
+- `--main_only` returns only the main post row and keeps the body untruncated
+
+Output columns: `author`, `content`, `likes`, `created_at`
+
+## user-topics
+
+List topics created by a user.
+
+```bash
+opencli linux-do user-topics neo
+opencli linux-do user-topics neo --limit 10
+```
+
+Output columns: `rank`, `title`, `replies`, `created_at`, `likes`, `views`, `url`
+
+## user-posts
+
+List replies posted by a user.
+
+```bash
+opencli linux-do user-posts neo
+opencli linux-do user-posts neo --limit 10
+```
+
+Output columns: `index`, `topic_user`, `topic`, `reply`, `time`, `url`
+
+## Compatibility
+
+The legacy commands below are still available as compatibility wrappers while `feed` becomes the canonical entrypoint:
+
+```bash
+opencli linux-do latest
+opencli linux-do hot --period weekly
+opencli linux-do category develop 4
+```
+
+Preferred modern forms:
+
+```bash
+opencli linux-do feed --view latest
+opencli linux-do feed --view top --period weekly
+opencli linux-do feed --category 4
 ```
 
 ## Prerequisites

package/docs/adapters/browser/paperreview.md

@@ -0,0 +1,43 @@
+# paperreview.ai
+
+**Mode**: 🌐 Public · **Domain**: `paperreview.ai`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli paperreview submit` | Submit a PDF to paperreview.ai for review |
+| `opencli paperreview review` | Fetch a review by token |
+| `opencli paperreview feedback` | Send feedback on a completed review |
+
+## Usage Examples
+
+```bash
+# Validate a local PDF without uploading it
+opencli paperreview submit ./paper.pdf --email you@example.com --venue RAL --dry-run true
+
+# Request an upload slot but stop before the actual upload
+opencli paperreview submit ./paper.pdf --email you@example.com --venue RAL --prepare-only true
+
+# Submit a paper for review
+opencli paperreview submit ./paper.pdf --email you@example.com --venue RAL -f json
+
+# Check the review status or fetch the final review
+opencli paperreview review tok_123 -f json
+
+# Submit feedback on the review quality
+opencli paperreview feedback tok_123 --helpfulness 4 --critical-error no --actionable-suggestions yes
+```
+
+## Prerequisites
+
+- No browser required — uses public paperreview.ai endpoints
+- The input file must be a local `.pdf`
+- paperreview.ai currently rejects files larger than `10MB`
+- `submit` requires `--email`; `--venue` is optional
+
+## Notes
+
+- `submit` returns both the review token and the review URL when submission succeeds
+- `review` returns `processing` until the paperreview.ai result is ready
+- `feedback` expects `yes` / `no` values for `--critical-error` and `--actionable-suggestions`

package/docs/adapters/browser/producthunt.md

@@ -0,0 +1,49 @@
+# Product Hunt
+
+**Mode**: 🌐 Public / 🔐 Browser · **Domain**: `www.producthunt.com`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `opencli producthunt posts` | Latest Product Hunt launches (optional category filter) |
+| `opencli producthunt today` | Today's Product Hunt launches (most recent day in feed) |
+| `opencli producthunt hot` | Today's top Product Hunt launches with vote counts |
+| `opencli producthunt browse <category>` | Best products in a Product Hunt category |
+
+## Usage Examples
+
+```bash
+# Today's top launches with vote counts
+opencli producthunt hot --limit 10
+
+# Latest posts (RSS feed)
+opencli producthunt posts --limit 20
+
+# Filter by category
+opencli producthunt posts --category developer-tools --limit 10
+
+# Today's launches only
+opencli producthunt today --limit 10
+
+# Browse best products in a category
+opencli producthunt browse vibe-coding --limit 10
+opencli producthunt browse ai-agents --limit 10
+opencli producthunt browse developer-tools --limit 10
+
+# JSON output
+opencli producthunt hot -f json
+```
+
+## Category Slugs
+
+Common categories for `browse` and `posts --category`:
+
+`ai-agents`, `ai-coding-agents`, `ai-code-editors`, `ai-chatbots`, `ai-workflow-automation`,
+`vibe-coding`, `developer-tools`, `productivity`, `design-creative`, `marketing-sales`,
+`no-code-platforms`, `llms`, `finance`, `social-community`, `engineering-development`
+
+## Prerequisites
+
+- `posts` and `today` — no browser required (public RSS feed)
+- `hot` and `browse` — Chrome running with [Browser Bridge extension](/guide/browser-bridge) installed

package/docs/adapters/desktop/chatgpt.md

@@ -14,8 +14,13 @@ The current built-in commands use native AppleScript automation — no extra lau
 - `opencli chatgpt status`: Check if the ChatGPT app is currently running.
 - `opencli chatgpt new`: Activate ChatGPT and press `Cmd+N` to start a new conversation.
 - `opencli chatgpt send "message"`: Copy your message to clipboard, activate ChatGPT, paste, and submit.
+- `opencli chatgpt send "message" --model thinking`: Switch model/mode first, then send the message.
 - `opencli chatgpt read`: Read the last visible message from the focused ChatGPT window via the Accessibility tree.
 - `opencli chatgpt ask "message"`: Send a prompt and wait for the visible reply in one shot.
+- `opencli chatgpt ask "message" --model instant`: Run a one-shot prompt using a specific model/mode.
+- `opencli chatgpt model thinking`: Switch the active ChatGPT model/mode without sending a message.
+
+Supported model choices: `auto`, `instant`, `thinking`, `5.2-instant`, `5.2-thinking`.
 
 ## Approach 2: CDP (Advanced, Electron Debug Mode)
 

package/docs/adapters/index.md

@@ -25,13 +25,14 @@ Run `opencli list` for the live registry.
 | **[jike](/adapters/browser/jike)** | `feed` `search` `post` `topic` `user` `create` `comment` `like` `repost` `notifications` | 🔐 Browser |
 | **[jimeng](/adapters/browser/jimeng)** | `generate` `history` | 🔐 Browser |
 | **[yollomi](/adapters/browser/yollomi)** | `generate` `video` `edit` `upload` `models` `remove-bg` `upscale` `face-swap` `restore` `try-on` `background` `object-remover` | 🔐 Browser |
-| **[linux-do](/adapters/browser/linux-do)** | `hot` `latest` `categories` `category` `search` `topic` | 🔐 Browser |
+| **[linux-do](/adapters/browser/linux-do)** | `feed` `categories` `tags` `search` `topic` `user-topics` `user-posts` | 🔐 Browser |
 | **[chaoxing](/adapters/browser/chaoxing)** | `assignments` `exams` | 🔐 Browser |
 | **[grok](/adapters/browser/grok)** | `ask` | 🔐 Browser |
 | **[doubao](/adapters/browser/doubao)** | `status` `new` `send` `read` `ask` | 🔐 Browser |
 | **[weread](/adapters/browser/weread)** | `shelf` `search` `book` `ranking` `notebooks` `highlights` `notes` | 🔐 Browser |
-| **[douban](/adapters/browser/douban)** | `search` `top250` `subject` `marks` `reviews` `movie-hot` `book-hot` | 🔐 Browser |
+| **[douban](/adapters/browser/douban)** | `search` `top250` `subject` `photos` `download` `marks` `reviews` `movie-hot` `book-hot` | 🔐 Browser |
 | **[facebook](/adapters/browser/facebook)** | `feed` `profile` `search` `friends` `groups` `events` `notifications` `memories` `add-friend` `join-group` | 🔐 Browser |
+| **[imdb](/adapters/browser/imdb)** | `search` `title` `top` `trending` `person` `reviews` | 🌐 / 🔐 |
 | **[instagram](/adapters/browser/instagram)** | `explore` `profile` `search` `user` `followers` `following` `follow` `unfollow` `like` `unlike` `comment` `save` `unsave` `saved` | 🔐 Browser |
 | **[medium](/adapters/browser/medium)** | `feed` `search` `user` | 🔐 Browser |
 | **[sinablog](/adapters/browser/sinablog)** | `hot` `search` `article` `user` | 🔐 Browser |
@@ -42,6 +43,8 @@ Run `opencli list` for the live registry.
 | **[jd](/adapters/browser/jd)** | `item` | 🔐 Browser |
 | **[web](/adapters/browser/web)** | `read` | 🔐 Browser |
 | **[weixin](/adapters/browser/weixin)** | `download` | 🔐 Browser |
+| **[36kr](/adapters/browser/36kr)** | `news` `hot` `search` `article` | 🌐 / 🔐 |
+| **[producthunt](/adapters/browser/producthunt)** | `posts` `today` `hot` `browse` | 🌐 / 🔐 |
 
 ## Public API Adapters
 
@@ -55,6 +58,7 @@ Run `opencli list` for the live registry.
 | **[xiaoyuzhou](/adapters/browser/xiaoyuzhou)** | `podcast` `podcast-episodes` `episode` | 🌐 Public |
 | **[yahoo-finance](/adapters/browser/yahoo-finance)** | `quote` | 🌐 Public |
 | **[arxiv](/adapters/browser/arxiv)** | `search` `paper` | 🌐 Public |
+| **[paperreview](/adapters/browser/paperreview)** | `submit` `review` `feedback` | 🌐 Public |
 | **[barchart](/adapters/browser/barchart)** | `quote` `options` `greeks` `flow` | 🌐 Public |
 | **[hf](/adapters/browser/hf)** | `top` | 🌐 Public |
 | **[sinafinance](/adapters/browser/sinafinance)** | `news` | 🌐 Public |

package/docs/advanced/download.md

@@ -9,6 +9,7 @@ OpenCLI supports downloading images, videos, and articles from supported platfor
 | **xiaohongshu** | Images, Videos | Downloads all media from a note |
 | **bilibili** | Videos | Requires `yt-dlp` installed |
 | **twitter** | Images, Videos | Downloads from user media tab or single tweet |
+| **douban** | Images | Downloads poster / still image lists from movie subjects |
 | **zhihu** | Articles (Markdown) | Exports articles with optional image download |
 | **weixin** | Articles (Markdown) | Exports WeChat Official Account articles |
 
@@ -39,6 +40,9 @@ opencli twitter download elonmusk --limit 20 --output ./twitter
 # Download single tweet media
 opencli twitter download --tweet-url "https://x.com/user/status/123" --output ./twitter
 
+# Download Douban posters / stills
+opencli douban download 30382501 --output ./douban
+
 # Export Zhihu article to Markdown
 opencli zhihu download "https://zhuanlan.zhihu.com/p/xxx" --output ./zhihu
 

package/docs/advanced/rate-limiter-plugin.md

@@ -0,0 +1,99 @@
+# Rate Limiter Plugin
+
+An optional plugin that adds a random sleep between browser-based commands to reduce the risk of platform rate-limiting or bot detection.
+
+## Install
+
+```bash
+opencli plugin install github:jackwener/opencli-plugin-rate-limiter
+```
+
+Or copy the example below into `~/.opencli/plugins/rate-limiter/` to use it locally without installing from GitHub.
+
+## What it does
+
+After every command targeting a browser platform (xiaohongshu, weibo, bilibili, douyin, tiktok, …), the plugin sleeps for a random duration — 5–30 seconds by default — before returning control to the caller.
+
+## Configuration
+
+| Variable | Default | Description |
+|---|---|---|
+| `OPENCLI_RATE_MIN` | `5` | Minimum sleep in seconds |
+| `OPENCLI_RATE_MAX` | `30` | Maximum sleep in seconds |
+| `OPENCLI_NO_RATE` | — | Set to `1` to disable entirely (local dev) |
+
+```bash
+# Shorter delays for light scraping
+OPENCLI_RATE_MIN=3 OPENCLI_RATE_MAX=10 opencli xiaohongshu search "AI眼镜"
+
+# Skip delays when iterating locally
+OPENCLI_NO_RATE=1 opencli bilibili comments BV1WtAGzYEBm
+```
+
+## Local installation (without GitHub)
+
+1. Create the plugin directory:
+
+   ```bash
+   mkdir -p ~/.opencli/plugins/rate-limiter
+   ```
+
+2. Create `~/.opencli/plugins/rate-limiter/package.json`:
+
+   ```json
+   { "type": "module" }
+   ```
+
+3. Create `~/.opencli/plugins/rate-limiter/index.js`:
+
+   ```js
+   import { onAfterExecute } from '@jackwener/opencli/hooks'
+
+   const BROWSER_DOMAINS = [
+     'xiaohongshu', 'weibo', 'bilibili', 'douyin', 'tiktok',
+     'instagram', 'twitter', 'youtube', 'zhihu', 'douban',
+     'jike', 'weixin', 'xiaoyuzhou',
+   ]
+
+   onAfterExecute(async (ctx) => {
+     if (process.env.OPENCLI_NO_RATE === '1') return
+
+     const site = ctx.command?.split('/')?.[0] ?? ''
+     if (!BROWSER_DOMAINS.includes(site)) return
+
+     const min = Number(process.env.OPENCLI_RATE_MIN ?? 5)
+     const max = Number(process.env.OPENCLI_RATE_MAX ?? 30)
+     const ms = Math.floor(Math.random() * (max - min + 1) + min) * 1000
+
+     process.stderr.write(`[rate-limiter] ${site}: sleeping ${(ms / 1000).toFixed(0)}s\n`)
+     await new Promise(r => setTimeout(r, ms))
+   })
+   ```
+
+4. Verify it loaded:
+
+   ```bash
+   OPENCLI_NO_RATE=1 opencli xiaohongshu search "test" 2>&1 | grep rate-limiter
+   # → (no output — plugin loaded but rate limit skipped)
+
+   opencli xiaohongshu search "test" 2>&1 | grep rate-limiter
+   # → [rate-limiter] xiaohongshu: sleeping 12s
+   ```
+
+## Writing your own plugin
+
+Plugins are plain JS/TS files in `~/.opencli/plugins/<name>/`. A plugin file must export a hook registration call that matches the pattern `onStartup(`, `onBeforeExecute(`, or `onAfterExecute(` — opencli's discovery engine uses this pattern to identify hook files vs. command files.
+
+```js
+// ~/.opencli/plugins/my-plugin/index.js
+import { onAfterExecute } from '@jackwener/opencli/hooks'
+
+onAfterExecute(async (ctx) => {
+  // ctx.command — e.g. "bilibili/comments"
+  // ctx.args    — coerced command arguments
+  // ctx.error   — set if the command threw
+  console.error(`[my-plugin] finished: ${ctx.command}`)
+})
+```
+
+See [hooks.ts](../../src/hooks.ts) for the full `HookContext` type.

package/docs/guide/electron-app-cli.md

@@ -0,0 +1,200 @@
+---
+description: How to turn a new Electron desktop app into an OpenCLI adapter
+---
+
+# Add a New Electron App CLI
+
+This guide is the **fast entry point** for turning a new Electron desktop application into an OpenCLI adapter.
+
+If you want the full background and deeper SOP, read:
+- [CLI-ifying Electron Applications](/advanced/electron)
+- [Chrome DevTools Protocol](/advanced/cdp)
+- [TypeScript Adapter Guide](/developer/ts-adapter)
+
+## When to use this guide
+
+Use this workflow when the target app:
+- is built with **Electron**, or at least exposes a working **Chrome DevTools Protocol (CDP)** endpoint
+- can be launched with `--remote-debugging-port=<port>`
+- should be automated through its real UI instead of a public HTTP API
+
+If the app is **not** Electron and does **not** expose CDP, use the native desktop automation pattern instead. See [CLI-ifying Electron Applications](/advanced/electron#non-electron-pattern-applescript).
+
+## The shortest path
+
+### 1. Confirm the app is Electron
+
+Typical macOS check:
+
+```bash
+ls /Applications/AppName.app/Contents/Frameworks/Electron\ Framework.framework
+```
+
+If Electron is present, the next step is usually to launch the app with a debugging port.
+
+### 2. Launch it with CDP enabled
+
+```bash
+/Applications/AppName.app/Contents/MacOS/AppName --remote-debugging-port=9222
+```
+
+Then point OpenCLI at that CDP endpoint:
+
+```bash
+export OPENCLI_CDP_ENDPOINT="http://127.0.0.1:9222"
+```
+
+### 3. Start with the 5-command pattern
+
+For a new Electron adapter, implement these commands first in `src/clis/<app>/`:
+
+- `status.ts` — verify the app is reachable through CDP
+- `dump.ts` — inspect DOM and snapshot structure before guessing selectors
+- `read.ts` — extract the visible context you actually need
+- `send.ts` — inject text and submit through the real editor
+- `new.ts` — create a new session, tab, thread, or document
+
+This is the standard baseline because it gives you:
+- a connection check
+- a reverse-engineering tool
+- one read path
+- one write path
+- one session reset path
+
+The full rationale and examples are in [CLI-ifying Electron Applications](/advanced/electron).
+
+## Recommended implementation workflow
+
+### Step 1: Build `status`
+
+Goal: prove CDP connectivity before touching app-specific logic.
+
+Typical checks:
+- current URL
+- document title
+- app shell presence
+
+If `status` is unstable, stop there and fix connectivity first.
+
+### Step 2: Build `dump`
+
+Do **not** guess selectors from the rendered UI.
+
+Dump:
+- `document.body.innerHTML`
+- accessibility snapshot
+- any stable attributes such as `data-testid`, `role`, `aria-*`, framework-specific markers
+
+Use the dump to identify real containers, buttons, composers, and conversation regions.
+
+### Step 3: Build `read`
+
+Target only the app region that matters.
+
+Good targets:
+- message list
+- editor history
+- visible thread content
+- selected document panel
+
+Avoid dumping the entire page text into the final command output.
+
+### Step 4: Build `send`
+
+Most Electron apps use React-style controlled editors, so direct `.value = ...` assignments are often ignored.
+
+Prefer editor-aware input patterns such as:
+- focus the editable region
+- use `document.execCommand('insertText', false, text)` when applicable
+- use real key presses like `Enter`, `Meta+Enter`, or app-specific shortcuts
+
+### Step 5: Build `new`
+
+Many desktop apps rely on keyboard shortcuts for “new chat”, “new tab”, or “new note”.
+
+Typical pattern:
+
+```ts
+const isMac = process.platform === 'darwin';
+await page.pressKey(isMac ? 'Meta+N' : 'Control+N');
+await page.wait(1);
+```
+
+## Where to put files
+
+For a TypeScript desktop adapter, the usual layout is:
+
+```text
+src/clis/<app>/status.ts
+src/clis/<app>/dump.ts
+src/clis/<app>/read.ts
+src/clis/<app>/send.ts
+src/clis/<app>/new.ts
+src/clis/<app>/utils.ts
+```
+
+If the app grows beyond the baseline, add higher-level commands such as:
+- `ask`
+- `history`
+- `model`
+- `screenshot`
+- `export`
+
+## What to document when you add a new app
+
+When the adapter is ready, also add:
+
+- an adapter doc under `docs/adapters/desktop/`
+- command list and examples
+- launch instructions with `--remote-debugging-port`
+- any required environment variables
+- platform-specific caveats
+
+Examples to study:
+- `docs/adapters/desktop/codex.md`
+- `docs/adapters/desktop/chatwise.md`
+- `docs/adapters/desktop/notion.md`
+- `docs/adapters/desktop/discord.md`
+
+## Common failure modes
+
+### CDP endpoint exists, but commands are flaky
+
+Usually one of these:
+- the wrong window/tab is selected
+- the app has not finished rendering
+- selectors were guessed instead of discovered from `dump`
+- the editor is controlled and ignores direct value assignment
+
+### The app is Chromium-based but not truly controllable
+
+Some desktop apps embed Chromium but do not expose a usable CDP surface.
+In that case, switch to the non-Electron desktop automation approach instead of forcing the Electron pattern.
+
+### You already have a browser workflow and wonder whether to reuse it
+
+If the app exposes a normal web URL and the browser flow is enough, a browser adapter is usually simpler.
+Use an Electron adapter only when the desktop app is the real integration surface.
+
+## Recommended reading order
+
+If you are starting from zero:
+
+1. This page
+2. [CLI-ifying Electron Applications](/advanced/electron)
+3. [Chrome DevTools Protocol](/advanced/cdp)
+4. [TypeScript Adapter Guide](/developer/ts-adapter)
+5. One concrete desktop adapter doc under `docs/adapters/desktop/`
+
+## Practical rule
+
+Do not start with a large feature surface.
+
+Start with:
+- `status`
+- `dump`
+- `read`
+- `send`
+- `new`
+
+Once those are stable, extend outward.

package/docs/guide/getting-started.md

@@ -55,3 +55,4 @@ opencli bilibili hot -v         # Verbose: show pipeline debug
 - [Plugins — extend with community adapters](/guide/plugins)
 - [All available adapters](/adapters/)
 - [For developers / AI agents](/developer/contributing)
+- [Add a new Electron app CLI](/guide/electron-app-cli)