Docs that map the app, CLI, and extension as one system.

This repository is small enough that release quality should come from discipline, not process theater.

The contract surfaces to protect

Changes are high risk when they affect:

• command names or flags
• JSON shapes in src/domain.ts
• auth endpoint expectations in src/auth.ts
• BigQuery SQL generation in src/bigquery.ts
• domain-finder selection or writeback semantics in src/domainfinder.ts
• Instantly sync behavior in src/instantly.ts

If one of those changes, docs and tests need to move with it.

Standard validation

Run this before shipping meaningful CLI changes:

npm run check
npm test
npm run docs:broken-links
npm run docs:a11y

When warehouse logic changes

In addition to local tests, validate with real workflow runs where appropriate:

• domainfinder:run:bq
• domainfinder:audit-existing:bq
• domainfinder:audit-delta
• leads:lookup:bq --execute

Keep before and after artifacts so selection and writeback changes are auditable.

Release checklist

1. Build the CLI and run the full test suite.
2. Validate docs links and accessibility.
3. Update docs for any changed commands, env vars, schemas, or workflows.
4. If BigQuery or domain-finder behavior changed, run at least one real warehouse-backed validation path.
5. Confirm fallback-versus-real behavior is still labeled correctly.
6. Only then publish or package.

Docs-specific review checklist

• navigation updated in docs.json
• new pages linked from at least one existing page
• command examples reflect the actual CLI surface
• app and extension docs stay honest about what is implemented here versus documented as a contract

Testing philosophy

The goal is not just green tests. The goal is preserving trust in:

• the CLI as a production integration surface
• the docs as a reliable operator guide
• the JSON artifacts as stable contracts

Related pages

• Local Development
• CLI Reference
• JSON Contracts