# Documentation Coverage Rules

This file contains Planet-specific documentation coverage rules. Documentation skills and agents should read this file before deciding which docs to update. Keep tool-specific workflow in skills; keep product and repository rules here.

## Audience Routing (mandatory)

Before deciding scope, classify the change by who performs the action:

- **Browser/UI end user** (login, account settings, configuring collectors or AI via UI, using Earth/Console pages): update `docs/technical/{zh,en}/manual.md` and `quickstart.md` only. Never put shell commands, log file paths, `planet.sh`, Docker operations, or `netsh portproxy` rules into these files.
- **Operations / deployment / on-call** (`planet.sh`, log paths, SMTP fallbacks like `createuser`, LAN/portproxy, env-var tuning, troubleshooting order, Bun build conventions): update `docs/technical/{zh,en}/ops-runbook.md` (or an existing `ops-*.md`). Never put UI button labels or screenshots into these files.
- **Second-party developers** (component context, render order, internal pipelines): update the existing `*-context.md` / `backend-*.md` / `earth-*.md` files.

If the same action has both a UI and a CLI path (e.g. user creation), describe the UI path in `manual.md` and the CLI path in `ops-runbook.md`, and cross-link them with a single sentence each.

## Scope Rules

- Focus documentation changes on the primary document that owns the affected behavior. Do not trigger speculative updates across secondary or architectural docs unless the underlying contract or operator-facing workflow actually changed.
- User-visible workflow changes must update `docs/technical/zh/manual.md` and usually `docs/technical/zh/quickstart.md`.
- If an English counterpart exists for user-facing docs such as `manual.md` or `quickstart.md`, update `docs/technical/en/...` enough that it does not contradict the Chinese source.
- Control console page responsibility changes must update `docs/technical/zh/frontend-admin-frontend-context.md`.
- Earth frontend behavior changes must update `docs/technical/zh/earth-frontend-context.md`.
- Earth layer additions, `renderOrder`, altitude/radius offsets, depth strategy, pointer picking, legend modes, or layer panel/startup ordering must update `docs/technical/zh/earth-render-layer-order.md`.
- Earth layer visual style or legend symbol/color semantics should also update `docs/technical/zh/earth-layer-style-reference.md` when that reference is affected.
- Collector, datasource, credential, settings, connectivity, scheduler, or API changes must update the relevant backend docs, especially `docs/technical/zh/backend-collectors.md` and any datasource/settings-specific doc.
- When a change turns an old plan assumption into current behavior, update the relevant `docs/plans/*.md` with a status note instead of leaving contradictory instructions.
- Search docs for stale terms introduced by the change, for example old tab names, old route responsibilities, obsolete auth assumptions, or renamed UI labels.
- Internal bug fixes or optimizations that preserve existing APIs and workflows do not require updating user manuals or creating new documentation.

## Public Docs Rules

- If adding a new technical document, add it to `docs/technical/zh/README.md` when it should be discoverable from the technical docs index.
- If a technical document should be visible in the public Docs page or linked from a technical README, register it in `frontend/src/pages/Docs/docs-content.ts` under `DOCS_METADATA`. Files under `docs/technical/{zh,en}/` are not automatically routable.
- For every public technical doc, keep the bilingual file pair in sync by filename: `docs/technical/zh/<name>.md` and `docs/technical/en/<name>.md`. If content is intentionally Chinese-only or English-only, state that intentionally in the final note.
- Public docs should use readable link text, not raw filenames such as `manual.md`.

## Credential Collector Rules

- Any built-in collector marked `requires_credentials: true` and `credential_status: supported` must have:
  - a `credential_provider` in `backend/app/core/datasource_defaults.py`;
  - a default credential guide in `backend/app/services/credential_guides.py`;
  - a supported connectivity provider in `backend/app/services/datasource_connectivity.py`;
  - settings UI guidance or a credential form in `frontend/src/admin/pages/PlainResourcePages.tsx`;
  - a regression test that fails if the guide/provider is missing.

## Recommended Checks

Always run the centralized harness documentation gate:

```bash
scripts/harness/docs-consistency-check.sh
```

This single command automatically covers:
1. Public docs whitelist and `DOCS_METADATA` synchronization (`frontend/src/pages/Docs/docs-content.ts` vs backend Gatekeeper)
2. Technical doc bilingual file pairs and identical duplicate-content detection
3. Public doc link validity and human-readable link titles (no raw `.md` filenames)
4. Language-scoped internal links (`docs/technical/zh/` links pointing to `docs/technical/zh/`)
5. Supported credential collector contracts and UI guide registration
6. Manual console route coverage against actual admin manifests
7. Documented `?section=` deep-link validity and UI route drift in active docs