# VectorCI documentation

Install VectorCI in a repository so humans and agents use the same GitHub-authenticated, review-gated setup and validation workflow.

Package: @orintech/vectorci@0.5.0
Website: https://davidgrijalva-orin.github.io/VectorCI/
npm: https://www.npmjs.com/package/@orintech/vectorci

## Topics

- [Install VectorCI in a repository](https://davidgrijalva-orin.github.io/VectorCI/install/): Add the official VectorCI CLI so humans, package scripts, and agents use the same reviewed version.
- [Authenticate with GitHub](https://davidgrijalva-orin.github.io/VectorCI/authentication/): Use GitHub CLI web authentication and explicit GitHub App consent without copying tokens into VectorCI.
- [Set up one repository](https://davidgrijalva-orin.github.io/VectorCI/single-repository/): Plan a deterministic .vectorci.yml, review its digest, apply it once, and prove the exact default-branch run.
- [Keep product repositories isolated](https://davidgrijalva-orin.github.io/VectorCI/multiple-repositories/): Run one pinned CLI inside each product repository without granting cross-repository access.
- [Give coding agents a safe VectorCI workflow](https://davidgrijalva-orin.github.io/VectorCI/agents/): Pin the CLI in the repository, tell agents which read-only commands to run first, and keep every write review-gated.
- [Understand .vectorci.yml](https://davidgrijalva-orin.github.io/VectorCI/configuration/): Declare required capabilities and exact validation commands while VectorCI owns routing, credentials, cleanup, and check publication.
- [Validate configuration and prove readiness](https://davidgrijalva-orin.github.io/VectorCI/validation/): Keep local contract checks, GitHub identity, exact branch configuration, and live App-owned execution proof distinct.
- [Security model](https://davidgrijalva-orin.github.io/VectorCI/security/): Use short-lived GitHub identities, bounded filesystem writes, exact capability routing, and separate privileged release paths.

# Install VectorCI in a repository

Add the official VectorCI CLI so humans, package scripts, and agents use the same reviewed version.

Documentation: https://davidgrijalva-orin.github.io/VectorCI/install/

## Requirements

VectorCI supports native macOS and Windows clients. Install Node.js 24, Git, and GitHub CLI before adding the package.

- Node.js 24.x
- Git with an origin remote pointing to the target GitHub repository
- GitHub CLI (`gh`) for browser-based GitHub authentication
- A private, trusted GitHub repository

## Recommended: install in the codebase

A project-local development dependency records VectorCI in package.json and the lockfile. That gives users, CI, and agents one reproducible command surface without relying on a machine-wide installation.

### Install and start setup

```bash
npm install --save-dev --save-exact @orintech/vectorci@0.5.0
npx vectorci auth login
npx vectorci setup .
```

> **Pin what agents execute:** `--save-exact` records the resolved release. Commit package.json and the lockfile, then use `npm ci --ignore-scripts` in automation before running `npx vectorci`.

## Add repository commands

Package scripts make the supported entry points obvious to contributors and coding agents.

### package.json

```json
{
  "scripts": {
    "vectorci:plan": "vectorci setup .",
    "vectorci:doctor": "vectorci doctor .",
    "vectorci:docs": "vectorci docs"
  }
}
```

### Run the pinned local CLI

```bash
npm run vectorci:plan
npm run vectorci:doctor
npm run vectorci:docs
```

## Global and one-off alternatives

A global install is convenient for a workstation. A one-off command is useful for exploration, but a codebase dependency is the recommended shared setup.

### Global install

```bash
npm install --global @orintech/vectorci@0.5.0
vectorci docs --open
```

### One-off run

```bash
npx @orintech/vectorci@0.5.0 docs
```

# Authenticate with GitHub

Use GitHub CLI web authentication and explicit GitHub App consent without copying tokens into VectorCI.

Documentation: https://davidgrijalva-orin.github.io/VectorCI/authentication/

## Sign in

GitHub is the identity provider. VectorCI asks GitHub CLI to start its browser-based login flow, then reads only the authenticated account identity and repository metadata it needs for setup.

### Authenticate and check status

```bash
npx vectorci auth login
npx vectorci auth status
```

> **Never paste a token:** The CLI does not request, return, or write GitHub tokens. Product agents must use a selected-repository GitHub identity that excludes VectorCI; auth status fails closed unless that denial is proved. Grant provider execution access only through the VectorCI GitHub App page.

## Install the VectorCI GitHub App

Setup can open the App installation page after a reviewed plan is applied. Select only the private repositories that should use VectorCI.

### Open App consent after apply

```bash
npx vectorci setup . --apply --plan-digest <reviewed-sha256> --confirm WRITE_VECTORCI_CONFIG --open-app
```

## Automation behavior

- Exit 0: authenticated and usable.
- Exit 3: action is required, such as signing in or completing setup.
- Exit 1: invalid input or a security boundary rejected the request.
- Exit 2: command usage is invalid.

# Set up one repository

Plan a deterministic .vectorci.yml, review its digest, apply it once, and prove the exact default-branch run.

Documentation: https://davidgrijalva-orin.github.io/VectorCI/single-repository/

## 1. Generate a read-only plan

Run setup from the repository root. VectorCI verifies the Git root and origin, checks that the GitHub repository is private and accessible, and discovers bounded Node.js validation commands when possible.

### Plan

```bash
npx vectorci setup .
```

> **Planning never writes:** The response includes the complete candidate configuration, blockers, warnings, next steps, and a SHA-256 `planDigest`.

## 2. Review and apply the exact plan

1. Read every proposed command and capability.
2. Resolve every blocker.
3. Use the returned planDigest with the exact write confirmation.

### Apply

```bash
npx vectorci setup . \
  --apply \
  --plan-digest <reviewed-sha256> \
  --confirm WRITE_VECTORCI_CONFIG \
  --open-app
```

> **No overwrite path:** Apply recomputes the plan and creates only a missing regular `.vectorci.yml`. Changed inputs, stale digests, symbolic links, existing files, or privileged capabilities are rejected.

## 3. Commit, push, and prove the run

Commit `.vectorci.yml` through the repository's normal protected workflow. After the default branch receives the file and the App-owned check finishes, run doctor.

- The GitHub session is valid.
- The local origin matches an accessible private repository.
- The local configuration is valid.
- The default branch contains the same configuration.
- The exact default-branch head has a successful VectorCI check owned by the VectorCI GitHub App.

### Read production proof

```bash
npx vectorci doctor .
```

# Keep product repositories isolated

Run one pinned CLI inside each product repository without granting cross-repository access.

Documentation: https://davidgrijalva-orin.github.io/VectorCI/multiple-repositories/

## Use one process per repository

Start the product agent and pinned CLI from the exact product Git root. The CLI refuses parent directories, sibling repositories, and the VectorCI provider source repository.

### Run independently inside each product

```bash
cd /absolute/product-one
npx vectorci setup .
npx vectorci doctor .

cd /absolute/product-two
npx vectorci setup .
npx vectorci doctor .
```

## Use a product-scoped identity

- The product credential may access only its selected product repositories.
- The product credential must receive Not Found when it probes davidgrijalva-orin/VectorCI.
- The VectorCI GitHub App may post the provider-owned VectorCI check without giving the product agent provider-source permission.
- A separate owner profile is required for VectorCI source, releases, workers, and provider administration.

## Allowed product surfaces

- The exact pinned `@orintech/vectorci` CLI release.
- Product-owned `.vectorci.yml` and public documentation.
- Provider-owned VectorCI status and Check Run output.

# 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.

Documentation: https://davidgrijalva-orin.github.io/VectorCI/agents/

## 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

```text
## 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.

# Understand .vectorci.yml

Declare required capabilities and exact validation commands while VectorCI owns routing, credentials, cleanup, and check publication.

Documentation: https://davidgrijalva-orin.github.io/VectorCI/configuration/

## Minimal configuration

The product repository declares what must run. VectorCI selects only capacity that proves the exact requested capability.

### .vectorci.yml

```yaml
version: 1

jobs:
  quality:
    name: Quality
    capability: linux-general
    commands:
      - npm ci --ignore-scripts
      - npm test
```

## Choose exact capabilities

- `linux-general` for ordinary Node.js, Python, Java, C, and C++ validation.
- `linux-docker` when the job genuinely needs Docker or service containers.
- `windows-native` for Windows-specific builds and tests.
- `macos-native` or `apple-xcode` for Apple-specific validation.
- Narrow device, signing, UI, and deployment capabilities remain separate protected routes.

> **No platform substitution:** A Linux pass is not Windows proof, an emulator is not physical-device proof, and ordinary validation capacity is not a signing or production-deployment boundary.

## Validate before committing

### Contract validation

```bash
npx vectorci validate .
```

# Validate configuration and prove readiness

Keep local contract checks, GitHub identity, exact branch configuration, and live App-owned execution proof distinct.

Documentation: https://davidgrijalva-orin.github.io/VectorCI/validation/

## Contract and operational validation

Validate without options parses `.vectorci.yml`, normalizes its job metadata, computes a digest, and reports local readiness blockers without contacting GitHub or claiming that capacity executed the job.

Validate with `--require-ready` additionally runs the end-to-end doctor proof. It returns READY only when the same local configuration is on the exact GitHub default-branch head and that head has a successful provider-owned VectorCI result. Accepted single-host constraints remain visible under `limitations`.

### Validate

```bash
npx vectorci validate .
npx vectorci validate . --require-ready
```

## End-to-end doctor

Doctor reads GitHub state and returns READY only when the exact default-branch head has a successful provider-owned VectorCI result. It uses the App-owned Check Run when the credential can read Checks, otherwise it requires the separate provider status created by immutable App bot user id 313620140.

### Current product repository

```bash
npx vectorci doctor .
```

## Report proof honestly

1. Identify the exact local and remote commit.
2. Report local configuration validity separately.
3. Report the proof source, provider identity, conclusion, and exact head SHA.
4. For high-availability routes, call out missing capacity, secondary routes, warm spares, or failover evidence as blockers rather than hiding them behind a green local check.
5. For an exact constrained single-host envelope, report the shared physical failure domain as a limitation and call same-host replacement recovery, never failover.

# Security model

Use short-lived GitHub identities, bounded filesystem writes, exact capability routing, and separate privileged release paths.

Documentation: https://davidgrijalva-orin.github.io/VectorCI/security/

## Identity and credentials

- Product agents use a selected-repository GitHub identity that excludes VectorCI.
- The VectorCI owner profile uses a separate owner-capable identity.
- The CLI never requests or returns token values.
- The GitHub App grants repository-scoped access.
- Workers receive job-scoped repository access only after signed admission.

## Bounded setup writes

- Planning is read-only.
- Apply requires a freshly recomputed SHA-256 digest and exact confirmation.
- Only a missing regular `.vectorci.yml` may be created.
- Feedback submission creates only the exact digest-reviewed issue in the current product repository.
- Symbolic links, path escapes, parent or sibling repositories, provider source, overwrites, and public repositories are rejected.

## Execution isolation

- Fork-originated code does not reach privileged or signing runners.
- Capabilities are routed exactly; a different operating system or device class is never equivalent proof.
- Signing and production deployment remain separate from pull-request validation.
- Ephemeral one-job workers are the default, with cleanup and terminal check publication required.

## Public package boundary

The public npm package contains one standalone reviewed Node.js CLI bundle (`vectorci`), README, third-party notices, and package manifest. Runtime dependencies are bundled and the published manifest has no install-time dependencies. MCP servers, control-plane code, private registry and inventory implementation, source maps, credentials, and private filesystem paths are excluded.

> **VectorCI-gated publishing:** Documentation and npm releases require an exact protected-main App-owned VectorCI check while GitHub Actions remains disabled. npm publication uses one temporary web-authenticated CLI session and ends by logging that session out; no release credential is committed or stored in VectorCI.