jackwener--opencli/docs/developer/documentation-audit-2026-05.md

# Documentation Audit — 2026-05

This document reviews the current long-form docs, README surfaces, and developer guides in `opencli`. It focuses on stale facts, internal contradictions, and documentation structure that now causes drift.

## Scope

- `README.md`
- `README.zh-CN.md`
- `docs/`
- `skills/` references that are linked from user-facing docs

## Executive View

The docs are usable, but they are drifting in four visible ways:

1. **Hard-coded counts and feature claims are stale.**
2. **Developer docs describe an older architecture and older test layout.**
3. **English and Chinese docs are no longer updated with the same rigor.**
4. **Some pages still describe deleted concepts or old workflows.**

The highest-value work is:

1. Fix the stale facts in `README*`, `docs/index.md`, `docs/zh/index.md`, and `docs/guide/getting-started.md`.
2. Rewrite `docs/developer/testing.md` and `docs/developer/architecture.md` against current `main`.
3. Make English and Chinese entry docs derive from the same source-of-truth checklist.
4. Stop writing command/adapters counts by hand unless they are generated.

## Priority 0 — Clearly stale or incorrect

### 1. Adapter / site counts are stale across multiple entry points

Affected files:

- `README.md`
- `README.zh-CN.md`
- `docs/guide/getting-started.md`
- `docs/comparison.md`

Current problems:

- `README.md` and `README.zh-CN.md` still say `90+` adapters.
- `docs/guide/getting-started.md` still says `87+` pre-built adapters.
- `docs/comparison.md` still says `87+` sites.

Current reality:

- `node dist/src/main.js list --format json | jq 'map(.site) | unique | length'` returns `106`.

Why this matters:

- These are the first pages people read.
- The mismatch is easy to notice and weakens trust in the rest of the docs.
- These values will keep drifting if we maintain them manually.

Recommended fix:

- Replace all hard-coded counts with one of:
  - `100+`
  - `100+ sites`
  - `over 100 registered sites`
- Best option: generate this number into docs at release time or avoid explicit counts entirely.

### 2. `docs/developer/testing.md` is materially out of date

Affected file:

- `docs/developer/testing.md`

Current problems:

- It says adapter tests live in `clis/**/*.test.{ts,js}`.
- The file examples name adapter tests such as:
  - `clis/zhihu/download.test.ts`
  - `clis/twitter/timeline.test.ts`
  - `clis/reddit/read.test.ts`
  - `clis/bilibili/dynamic.test.ts`
- Those files do not exist.
- It says E2E coverage is `5` files.
- Current reality is `11` E2E files.
- It presents `npm test` as the main local gate, while current team rule is to prefer the smallest sufficient test set instead of default full-suite runs.

Current reality from the repo:

- `find src -name '*.test.ts' | wc -l` → `60`
- `find clis -iregex '.*\\.test\\.(ts|js)$' | wc -l` → `0`
- `find tests/e2e -name '*.test.ts' | wc -l` → `11`
- `find tests/smoke -name '*.test.ts' | wc -l` → `1`

Why this matters:

- This page is the main developer testing contract.
- A new contributor following it will get the wrong mental model of the test layout.
- It encourages a heavier default test habit than the team currently wants.

Recommended fix:

- Rewrite the page from current files, not from remembered structure.
- Separate:
  - `fast local checks`
  - `targeted validation`
  - `full CI coverage`
- Remove nonexistent adapter test examples.
- Add a short rule:
  - local default = smallest sufficient validation
  - full-suite = broader refactor, shared runtime changes, or CI

### 3. `docs/developer/architecture.md` describes an older system shape

Affected file:

- `docs/developer/architecture.md`

Current problems:

- It refers to `src/browser.ts`, but that file does not exist.
- The directory structure block says `src/clis/`, but adapters live at top-level `clis/`.
- The architecture diagram is too simplified for the current system and omits important pieces such as:
  - `daemon.ts`
  - `external.ts`
  - `plugin.ts`
  - `electron-apps.ts`
  - update check / diagnostics / runtime detection paths
- It says “3-tier authentication strategy” but lists `5` strategies.

Why this matters:

- This is the page people read to understand the project.
- Once architecture docs are stale, all deeper docs become harder to trust.

Recommended fix:

- Rewrite this page around current modules:
  - command discovery and registry
  - execution
  - browser / daemon bridge
  - external CLI integration
  - plugin system
  - desktop / CDP path
  - pipeline engine
- Replace the static tree with a curated module map that matches current filenames.
- Change “3-tier” to a neutral label like `authentication strategies`.

### 4. Home pages still mention deleted concepts

Affected files:

- `docs/index.md`
- `docs/zh/index.md`

Current problems:

- Both home pages say:
  - `explore`
  - `synthesize`
  - `cascade`
- `docs/developer/ai-workflow.md` explicitly says those commands do not exist and that the skill drives the loop.

Why this matters:

- The home page is currently teaching a product vocabulary that the actual CLI does not have.
- This creates immediate confusion for users who go from docs to terminal.

Recommended fix:

- Replace those phrases with current concepts:
  - `browser primitives`
  - `adapter-authoring skill`
  - `verify loop`
- Keep the homepage aligned with `docs/developer/ai-workflow.md`.

### 5. Chinese getting-started page lists a deleted built-in command

Affected file:

- `docs/zh/guide/getting-started.md`

Current problem:

- It says built-in commands include `list、explore、validate...`
- `explore` is not a current built-in command.

Why this matters:

- This is a hard user-facing error.

Recommended fix:

- Replace the example list with current built-ins such as:
  - `list`
  - `validate`
  - `verify`
  - `browser`
  - `doctor`
  - `plugin`
  - `adapter`

## Priority 1 — Inconsistent or incomplete

### 6. Installation pages are inconsistent about runtime support and update flow

Affected files:

- `README.md`
- `README.zh-CN.md`
- `docs/guide/installation.md`
- `docs/zh/guide/installation.md`

Current problems:

- `README.md` says Node `>= 21` or Bun `>= 1.0`.
- `docs/guide/installation.md` and `docs/zh/guide/installation.md` only mention Node.
- `README.md` documents skill refresh on update.
- `docs/zh/guide/installation.md` only documents package update and omits skills refresh.

Why this matters:

- Entry docs should agree on install prerequisites and upgrade procedure.

Recommended fix:

- Pick one official runtime support statement and reuse it everywhere.
- If Bun is supported, add it consistently to guide pages.
- Mirror the post-update skill refresh guidance in the install/update guides.

### 7. README and docs still use top-level tables and examples that will drift by hand

Affected files:

- `README.md`
- `README.zh-CN.md`

Current problems:

- The “Built-in Commands” section is manually curated and already partially selective.
- The surrounding copy still frames it like a broad current snapshot.

Why this matters:

- Manual command snapshots go stale quickly in a repo with active adapter growth.

Recommended fix:

- Reframe the section as:
  - “Representative built-in commands”
  - “Sample sites”
- Keep `opencli list` and `docs/adapters/index.md` as the full registry surface.

### 8. `docs/comparison.md` contains stale scale claims

Affected file:

- `docs/comparison.md`

Current problem:

- It still says `87+` sites.

Why this matters:

- Comparison pages shape market positioning.
- Stale numbers make the project look less maintained than it is.

Recommended fix:

- Remove exact numbers from comparison copy unless they are generated.

## Priority 2 — Structural drift risks

### 9. English and Chinese docs are drifting independently

Most visible examples:

- `docs/index.md` and `docs/zh/index.md` both kept the deleted `explore / synthesize / cascade` language.
- `docs/zh/guide/getting-started.md` contains a stale built-in command example that should have been caught by parity review.
- `README.md` and `README.zh-CN.md` both carry the same stale adapter count.

Why this keeps happening:

- We have mirrored content with no explicit parity checklist.
- Updates land in one place and rely on memory for the rest.

Recommended fix:

- Introduce a small doc parity checklist for any change that touches:
  - `README.md`
  - `README.zh-CN.md`
  - `docs/index.md`
  - `docs/zh/index.md`
  - `docs/guide/*`
  - `docs/zh/guide/*`
- Add one PR checklist item:
  - “Did this change require an English/Chinese mirror update?”

### 10. Core product pages mix generated facts with narrative copy

Examples:

- command counts
- site counts
- test counts
- lists of built-in commands

Why this matters:

- Numbers and command inventories drift faster than narrative guidance.

Recommended fix:

- For fast-changing facts:
  - generate them
  - or generalize them
- Reserve hand-written docs for:
  - mental models
  - workflows
  - constraints
  - trade-offs

## Suggested rewrite order

### Pass 1 — Fix trust-breaking errors

1. `README.md`
2. `README.zh-CN.md`
3. `docs/index.md`
4. `docs/zh/index.md`
5. `docs/guide/getting-started.md`
6. `docs/zh/guide/getting-started.md`
7. `docs/comparison.md`

### Pass 2 — Rebuild the technical source-of-truth pages

1. `docs/developer/testing.md`
2. `docs/developer/architecture.md`
3. `docs/guide/installation.md`
4. `docs/zh/guide/installation.md`

### Pass 3 — Prevent the next round of drift

1. Add a docs parity checklist to PR workflow.
2. Remove exact counts from hand-written copy unless generated.
3. Decide which pages are authoritative for:
   - install
   - browser bridge
   - testing
   - architecture
   - AI workflow

## Concrete edits I would make next

### Small fast edits

- Replace all `87+` / `90+` claims with `100+`.
- Remove `explore / synthesize / cascade` from both home pages.
- Remove `explore` from `docs/zh/guide/getting-started.md`.
- Align install docs on Node/Bun support and skill refresh.

### Medium rewrites

- Rewrite `docs/developer/testing.md` from current filesystem state.
- Rewrite `docs/developer/architecture.md` from current module boundaries.

### Process fix

- Add a lightweight “doc drift” checklist to PRs that touch command surface, runtime support, testing strategy, or adapter discovery.

## Bottom line

The docs do not need a ground-up rewrite. They need a focused trust repair pass on entry pages, then a source-of-truth rebuild for testing and architecture, then a small process change so counts and mirrored pages stop drifting.