Document Index

Pre-built documentation index for efficient AI test generation.

Related: CLI Reference Configuration

Overview

The spectra docs index command builds a persistent docs/_index.md file — a pre-built index with per-document metadata. The AI agent reads this lightweight index (~1-2K tokens) instead of scanning all documentation files at generation time.

How It Works

  1. Discovery — Scans docs/ (or configured local_dir) for Markdown files using include/exclude patterns
  2. Extraction — For each file, extracts: title, H2/H3 sections with 200-char summaries, key entities (code spans, capitalized phrases, API paths, quoted strings), word count, token estimate (words × 1.3), file size, SHA-256 content hash
  3. Incremental Updates — On subsequent runs, only re-indexes files whose content hash has changed. Unchanged entries are reused from the existing index.
  4. Output — Writes docs/_index.md in Markdown format with a hidden <!-- SPECTRA_INDEX_CHECKSUMS {...} --> comment for fast hash lookups
  5. Acceptance Criteria Extraction — After indexing, automatically extracts testable acceptance criteria from the indexed documents using the configured AI provider and writes them to _criteria_index.yaml. Use --skip-criteria to skip this step. If no AI provider is configured, this step is silently skipped.

Usage 

# Build or incrementally update the index
spectra docs index

# Force a full rebuild (re-indexes all files regardless of changes)
spectra docs index --force

Auto-Refresh

The document index is automatically refreshed (incremental) before every spectra ai generate run. During spectra init, an initial full index build is performed if documentation files exist.

Acceptance Criteria Extraction

After building or updating the index, spectra docs index automatically extracts testable acceptance criteria from the documentation using the configured AI provider. Extracted criteria are merged into _criteria_index.yaml (configured via coverage.criteria_file), with duplicate detection to avoid re-extracting existing entries.

This removes the need to run spectra ai analyze --extract-criteria as a separate step — criteria stay in sync with the documentation index. Use --skip-criteria to skip this step. The --extract-criteria flag on spectra ai analyze is still available for on-demand extraction.

If no AI provider is configured, the extraction step is skipped silently and the command completes with the index only.

Index Format

The generated docs/_index.md looks like:

# Documentation Index

> Auto-generated by Spectra. Last updated: 2026-03-20T14:30:00Z
> Total: 5 documents | 12,000 words | ~15,600 tokens

---

### docs/features/checkout.md
- **Title:** Checkout Flow
- **Size:** 12 KB | **Words:** 3,450 | **Tokens:** ~4,485
- **Last Modified:** 2026-03-18
- **Key Entities:** Payment Gateway, Cart, Discount Code

| Section | Summary |
|---------|---------|
| Payment Methods | Three payment methods are supported: credit card... |
|   ↳ Credit Card | Card details are validated client-side before... |

---

<!-- SPECTRA_INDEX_CHECKSUMS
{"docs/features/checkout.md":"a1b2c3d4..."}
-->

Configuration

The index path can be customized in spectra.config.json:

{
  "source": {
    "doc_index": "docs/_index.md"
  }
}

If doc_index is not set, defaults to {local_dir}/_index.md.