Agent guide

Give coding agents a safe VectorCI workflow

Pin the CLI in the repository, tell agents which read-only commands to run first, and keep every write review-gated.

Add an agent-facing repository contract

Put a short VectorCI policy in AGENTS.md or the repository's equivalent instructions. Agents should inspect documentation and plan before requesting approval to apply.

AGENTS.md example
## VectorCI

- Install dependencies with `npm ci --ignore-scripts`.
- Read `npx vectorci docs agents` before changing CI setup.
- Use `npx vectorci setup .` for a read-only plan.
- Never apply without showing the full candidate and planDigest to the user.
- Apply only with the reviewed digest and `WRITE_VECTORCI_CONFIG` confirmation.
- Use `npx vectorci doctor .` after the committed default-branch run finishes.
- Provider feedback belongs in the approved shared support workflow, never in the VectorCI source repository.
- Never list, clone, inspect, execute, or change the VectorCI provider source repository.
- Never request, print, store, or commit GitHub or runner credentials.

Agent execution order

  1. Run vectorci docs.
  2. Check GitHub authentication without requesting credentials.
  3. Generate a setup plan and surface every blocker and proposed command.
  4. Pause for review before any apply command.
  5. Apply only the fresh digest with exact confirmation.
  6. Commit through the repository's normal protected process.
  7. Run doctor and report live proof separately from local validation.
  8. If provider work is needed, use the approved shared support workflow without accessing VectorCI source.

Machine-readable documentation

The Pages site publishes llms.txt for a complete agent-oriented guide and docs.json for the versioned topic catalog. The CLI embeds the same catalog, so documentation remains available even when browser access is unavailable.