@nestbox-ai/cli 1.0.63 → 1.0.64

package/dist/agents/reportGenerator/REPORT_CONFIG_GUIDE.md

@@ -0,0 +1,1449 @@
+# Report Configuration Guide — Schema v2.2
+
+> **For AI agents:** This document is your complete instructions for generating a valid `report_config.yaml`. Read every section before generating. Pay special attention to the [Quick Checklist](#quick-checklist) and [Computations](#5-computations) sections.
+
+---
+
+## Table of Contents
+
+1. [Overview & Pipeline](#overview--pipeline)
+2. [Quick Checklist](#quick-checklist)
+3. [Top-Level Structure](#top-level-structure)
+4. [report](#1-report)
+5. [context](#2-context)
+6. [docsets](#3-docsets)
+7. [llamaindex](#4-llamaindex)
+8. [computations](#5-computations)
+   - [fields](#fields)
+   - [tables](#tables)
+   - [DocsetSubtask (agents)](#docsetsubtask-agents)
+   - [Autonomous vs. Explicit Search Mode](#autonomous-vs-explicit-search-mode)
+   - [output_schema](#output_schema)
+   - [depends_on](#depends_on)
+9. [template](#6-template)
+   - [Placeholder Syntax](#placeholder-syntax)
+   - [Pipe Filters](#pipe-filters)
+10. [guardrails](#7-guardrails)
+11. [execution](#8-execution)
+12. [storage & doc_repository](#9-storage--doc_repository)
+13. [prompts](#10-prompts)
+14. [mcp](#11-mcp)
+15. [Environment Variables](#environment-variables)
+16. [Complete Minimal Example](#complete-minimal-example)
+17. [Full Annotated Example (Finance)](#full-annotated-example-finance)
+
+---
+
+## Overview & Pipeline
+
+The YAML config is a **declarative specification** — you describe *what* to extract, and the framework drives a ReAct agent loop automatically. Here is how every config section maps to a pipeline stage:
+
+```
+YAML config
+  │
+  ├── docsets        → GraphRAG parquet files loaded (entities, relationships, communities, text_units)
+  ├── llamaindex     → LLM and agent settings (model, timeouts, prompts)
+  ├── computations   → Agent spawned per subtask → searches GraphRAG → returns JSON validated against output_schema
+  │     ├── fields   → Single structured values (ARR snapshot, liquidity metrics, executive summary)
+  │     └── tables   → Tabular output rendered as markdown table in the report
+  ├── template       → Computed values injected into markdown via {{field.id.property}} placeholders
+  └── guardrails     → LLM-judge checks run on computed values and/or the rendered report
+```
+
+**Execution order:**
+1. All docsets pre-loaded from disk or downloaded from `doc_repository`
+2. Computations with no `depends_on` run in parallel
+3. Computations that declare `depends_on` run only after their dependencies complete
+4. Template rendered after all computations finish
+5. Guardrails run last on the completed outputs
+
+---
+
+## Quick Checklist
+
+Before writing the config, confirm you have answered:
+
+- [ ] **What is the source document?** → drives `docsets` and document `locator`
+- [ ] **What metrics/sections need to be extracted?** → drives `computations.fields`
+- [ ] **Do any metrics need tabular/historical data?** → drives `computations.tables`
+- [ ] **What should the final report look like?** → drives `template.content`
+- [ ] **Do any extractions depend on prior results?** → drives `depends_on`
+- [ ] **Which search type fits each extraction task?**
+  - Exact numbers, tables → `basic` or autonomous
+  - Entity/relationship lookups → `local` or autonomous
+  - High-level themes, summaries → `global` or autonomous
+  - Multi-hop graph exploration → `drift`
+- [ ] **What quality checks are needed?** → drives `guardrails`
+
+---
+
+## Top-Level Structure
+
+Required fields are marked with `*`.
+
+```yaml
+schema_version: "2.2"          # * Always "2.2"
+report: ...                    # * Report identity
+context: ...                   # Runtime variables referenced in prompts
+prompts: ...                   # Named reusable prompt strings
+storage: ...                   # For local file-based documents
+doc_repository: ...            # For API-based document downloads
+mcp: []                        # MCP server endpoints (use [] if none)
+docsets: [...]                 # * Document collections to query
+llamaindex: ...                # * LLM agent configuration
+computations: ...              # * What to extract
+template: ...                  # * Output template
+guardrails: [...]              # LLM-judge quality checks
+execution: ...                 # Retry and output settings
+```
+
+---
+
+## 1. `report`
+
+**Purpose:** Identifies the report. Used in file names, template placeholders, and logs.
+
+| Field | Required | Type | Notes |
+|-------|----------|------|-------|
+| `id` | Yes | string | Lowercase, alphanumeric, underscores/hyphens. Used in output filenames. |
+| `name` | Yes | string | Human-readable name shown in logs and reports. |
+| `description` | No | string | Longer description of purpose and scope. |
+| `version` | No | string | Reporting period version (e.g., "2025.Q4"). |
+
+```yaml
+report:
+  id: acme_cfo_kpi_q4_2025
+  name: "Acme CFO KPI Pack — Q4 2025"
+  description: |
+    Quarterly KPI extraction from the Q4 2025 Board Presentation.
+    Covers ARR, retention, liquidity, bookings, and marketing metrics.
+  version: "2025.Q4"
+```
+
+---
+
+## 2. `context`
+
+**Purpose:** Defines runtime variables that can be referenced anywhere in prompts and templates as `{{context.variable_name}}`. Also holds policies that guide agent behavior.
+
+- All fields are **optional** at the schema level
+- You can add **any custom key** — `context` allows extra properties
+- Use context variables to avoid hardcoding company names, periods, or policies into every prompt
+
+### Standard fields
+
+| Field | Description |
+|-------|-------------|
+| `company_name` | Injected into prompts to identify the company |
+| `currency` | Default "USD" |
+| `units_policy` | Instructions for how to handle number units ($M vs full dollars, etc.) |
+| `answer_quality_policy` | Numeric precision and citation requirements |
+| `value_types` | Allowed value type labels for classification |
+
+### Custom fields
+
+Any key you add becomes available in prompts and template as `{{context.your_key}}`.
+
+```yaml
+context:
+  company_name: "Acme Corp, Inc."
+  currency: "USD"
+  as_of_period: "CY2025 Q4"
+  meeting_date: "2026-01-15"
+  source_title: "Q4 2025 Board Meeting Presentation"
+  units_policy: |
+    Return raw numeric values — no $, commas, or M/K suffixes.
+    Convert abbreviated values: "$2.5M" → 2500000, "$350K" → 350000.
+    Percentages as whole numbers: 92.3 not 0.923.
+  answer_quality_policy:
+    numeric_requirements:
+      - "Every numeric value must have a citation (c_xxxxxxxx format)"
+      - "Return null if the value is not found — never guess"
+    labeling_requirements:
+      - "Include period label (e.g., 2025Q4) with every metric"
+  value_types:
+    - "money_usd"
+    - "percent"
+    - "count"
+    - "multiple"
+    - "string"
+    - "date"
+  kpi_namespace: "acme.board.25q4"
+```
+
+---
+
+## 3. `docsets`
+
+**Purpose:** Declares the GraphRAG-indexed document collections the agent will search. Each docset groups one or more documents and is referenced by `docset_id` in computations.
+
+| Field | Required | Type | Notes |
+|-------|----------|------|-------|
+| `id` | Yes | string | Unique identifier referenced in computations |
+| `docs` | Yes | array | At least one document |
+| `description` | No | string | What this docset represents |
+| `api_key` | No | string | OpenAI API key for GraphRAG searches. Falls back to `OPENAI_API_KEY` env var. |
+
+### Document fields
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `id` | Yes | Unique doc identifier |
+| `locator` | Recommended | See below for three forms |
+| `description` | No | Human-readable description |
+| `alias` | No | Short name for use in prompts |
+
+### Three ways to specify a document location
+
+**1. Local filesystem path** — points directly to the GraphRAG output directory:
+```yaml
+locator: /data/graphrag/board_deck/output
+locator: ./documents/doc-abc123/graphrag/output    # relative to config file
+```
+
+**2. `repo:doc-ID`** — download from the doc_repository API (requires `doc_repository` configured):
+```yaml
+locator: "repo:doc-eeb76651"
+```
+
+**3. Bare doc-ID** — check local cache first, then download from repo:
+```yaml
+locator: doc-a850ad6f
+```
+
+> **Legacy:** `document_id` is deprecated. Use `locator` instead.
+
+### Example — single docset, one document
+
+```yaml
+docsets:
+  - id: acme_board_deck_q4
+    description: "Acme Q4 2025 Board Presentation — GraphRAG indexed"
+    api_key: ${OPENAI_API_KEY}
+    docs:
+      - id: board_deck_pdf
+        locator: "repo:doc-eeb76651"
+        description: "Q4 2025 Board Meeting Presentation"
+        alias: q4_deck
+```
+
+### Example — two docsets (board deck + financial statements)
+
+```yaml
+docsets:
+  - id: board_deck
+    description: "Board presentation slides"
+    api_key: ${OPENAI_API_KEY}
+    docs:
+      - id: deck_pdf
+        locator: "repo:doc-abc12345"
+        description: "Q4 2025 Board Deck"
+
+  - id: financials
+    description: "Audited financial statements"
+    api_key: ${OPENAI_API_KEY}
+    docs:
+      - id: income_statement
+        locator: ./documents/income_stmt/graphrag/output
+      - id: balance_sheet
+        locator: ./documents/balance_sheet/graphrag/output
+```
+
+---
+
+## 4. `llamaindex`
+
+**Purpose:** Configures the LLM and ReAct agent that drives all extraction. One block controls all agents in the report.
+
+| Field | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `model` | Yes | — | LLM model ID: `gpt-4o`, `gpt-4.1-mini`, `claude-3-5-sonnet`, etc. |
+| `api_key` | Yes | — | Supports `${ENV_VAR}` |
+| `base_url` | No | OpenAI default | Custom endpoint (Azure, vLLM, Ollama) |
+| `max_tool_calls` | No | 20 | Per-subtask tool call limit (1–100) |
+| `tool_timeout_seconds` | No | 120 | Per-tool-call timeout (1–600) |
+| `max_agent_iterations` | No | 30 | ReAct loop iterations before stopping (1–100) |
+| `max_repair_attempts` | No | 2 | Schema validation repair loops (1–10) |
+| `system_prompt` | No | Built-in | Main system prompt for all agents |
+| `autonomous_search_guidance` | No | Built-in | Guidance for choosing between search tools in autonomous mode |
+| `synthesis_prompt` | No | Built-in | Template combining multiple subtask outputs. Placeholders: `{{subtask_results}}`, `{{output_schema}}` |
+| `validation_repair_prompt` | No | Built-in | Prompt for fixing schema validation failures. Placeholders: `{{raw_response}}`, `{{validation_errors}}`, `{{output_schema}}` |
+| `guardrail_system_prompt` | No | Built-in | Default system prompt for guardrail LLM-judge calls |
+| `json_extraction_prompt` | No | Built-in | Fallback for extracting JSON from non-JSON agent responses |
+| `mcp_system_prompt` | No | Built-in | System prompt for MCP integration agents |
+
+### Recommended model choices
+
+| Use Case | Recommended Model |
+|----------|------------------|
+| High-accuracy financial extraction | `gpt-4o` |
+| Cost-efficient extraction | `gpt-4.1-mini` |
+| Claude-based extraction | `claude-3-5-sonnet` |
+| Guardrail LLM-judge | `gpt-4.1-mini` (fast, cheap) |
+
+### Minimal example
+
+```yaml
+llamaindex:
+  model: gpt-4o
+  api_key: ${OPENAI_API_KEY}
+```
+
+### Full example with custom prompts
+
+```yaml
+llamaindex:
+  model: gpt-4o
+  base_url: ${OPENAI_BASE_URL:-https://api.openai.com/v1}
+  api_key: ${OPENAI_API_KEY}
+  max_tool_calls: 50
+  tool_timeout_seconds: 180
+  max_agent_iterations: 40
+  max_repair_attempts: 3
+  system_prompt: |
+    You are a CFO-grade KPI extraction analyst with expertise in financial document analysis.
+
+    ## ANTI-FABRICATION RULE — READ FIRST
+    NEVER return values from this prompt or any instruction text.
+    ALL values MUST come from your search tool results.
+    If a value is not found in search results, return null.
+
+    ## Critical Rules
+    1. NEVER FABRICATE: If a value isn't found, return null — never guess
+    2. EXACT VALUES: Use values exactly as found in documents
+    3. CITE EVERYTHING: Every numeric value needs a citation
+    4. RAW NUMBERS: Return 9697083 not "$9.7M" — no formatting
+    5. LABEL PERIODS: Always identify the time period (e.g., 2025Q4)
+```
+
+> **Tip for agents:** The built-in system prompt is already well-tuned for financial extraction. Only override `system_prompt` if you need domain-specific behavior or stricter rules. When you do override it, always include an anti-fabrication rule.
+
+---
+
+## 5. `computations`
+
+**Purpose:** Declares what to extract from the documents. Computations have two subtypes:
+- **`fields`** — produce a single structured value (a snapshot, a set of metrics)
+- **`tables`** — produce tabular data rendered as a markdown table
+
+Each computation contains one or more **agent subtasks** (`agents`). Each subtask spawns an independent ReAct agent that queries GraphRAG and returns a JSON output validated against an `output_schema`.
+
+---
+
+### Fields
+
+A field computation produces a single structured JSON value. Use fields for KPI snapshots, summaries, and any structured metric sets.
+
+| Field | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `id` | Yes | — | Lowercase alphanumeric + underscores. Referenced in template as `{{field.id}}` |
+| `label` | Yes | — | Human-readable name shown in logs |
+| `prompt` | Yes | — | Synthesis prompt combining all subtask outputs into the final result |
+| `agents` | No | — | Array of DocsetSubtask (see below). At least one of `agents` or `mcp_scope` needed. |
+| `mcp_scope` | No | — | MCP subtasks to run alongside agent subtasks |
+| `docset_id` | No | — | Default docset for all subtasks (overridden per-subtask) |
+| `type` | No | `object` | Output type hint: `object`, `number`, `string` |
+| `description` | No | — | Detailed description |
+| `priority` | No | 0 | Execution order hint — lower runs first |
+| `depends_on` | No | — | Array of field/table IDs that must complete first |
+| `output_schema` | No | — | Final JSON schema (only needed for multi-agent synthesis where schemas differ) |
+
+```yaml
+computations:
+  fields:
+    - id: arr_snapshot
+      label: "ARR & Retention Snapshot (Q4 2025)"
+      type: object
+      priority: 1
+      docset_id: acme_board_deck_q4
+      agents:
+        - id: arr_extract
+          prompt: |
+            Extract the Q4 2025 ARR waterfall and retention metrics.
+            ...
+          output_schema:
+            type: object
+            properties:
+              arr_end: { type: number }
+              nrr: { type: number }
+              citations: { type: array, items: { type: string } }
+      mcp_scope: []
+      prompt: "Return the Q4 2025 ARR snapshot with citations."
+```
+
+---
+
+### Tables
+
+A table computation produces an array of rows rendered as a markdown table in the report. Use tables for historical data, multi-period comparisons, and any row-per-item data.
+
+| Field | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `id` | Yes | — | Referenced in template as `{{table.id}}` |
+| `title` | Yes | — | Table title (used in the rendered table header) |
+| `prompt` | Yes | — | Synthesis prompt |
+| `agents` | No | — | Same as fields |
+| `docset_id` | No | — | Default docset |
+| `priority` | No | 0 | Execution order |
+| `depends_on` | No | — | Dependencies |
+| `output_schema` | No | — | JSON schema for the final table |
+
+> **Output format:** The agent's `output_schema` for a table should always use `{"type": "object", "properties": {"rows": {"type": "array", "items": {...}}}}`. The framework extracts the `rows` array and renders it as a markdown table.
+
+```yaml
+computations:
+  tables:
+    - id: arr_quarterly_history
+      title: "ARR Waterfall — Quarterly History"
+      priority: 2
+      docset_id: acme_board_deck_q4
+      agents:
+        - id: arr_history_extract
+          prompt: |
+            Extract the full quarterly ARR waterfall table.
+            For EACH quarter shown: period, beg_arr, new_logos_arr, net_upsell_arr,
+            churn_arr, end_arr, nrr, grr.
+            Return {"rows": [...]} with one object per quarter.
+          output_schema:
+            type: object
+            properties:
+              rows:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    period: { type: string }
+                    beg_arr: { type: number }
+                    end_arr: { type: number }
+                    nrr: { type: number }
+                    citations: { type: array, items: { type: string } }
+      mcp_scope: []
+      prompt: "Return quarterly ARR history with citations per row."
+```
+
+---
+
+### DocsetSubtask (`agents`)
+
+Each entry in `agents` is a **DocsetSubtask** — an independent agent run that queries one docset and returns an intermediate JSON result.
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `id` | Yes | Unique subtask ID (lowercase alphanumeric + underscores) |
+| `prompt` | Yes | What to extract. Be specific and include search strategy guidance. |
+| `output_schema` | Yes | JSON Schema the agent output must conform to |
+| `docset_id` | No | Overrides the computation-level `docset_id` |
+| `search_type` | No | `basic`, `local`, `global`, `drift`. **Omit for autonomous mode.** |
+| `options` | No | Search options (only used when `search_type` is set — see below) |
+
+```yaml
+agents:
+  - id: liquidity_extract
+    docset_id: acme_board_deck_q4          # optional override
+    search_type: basic                      # explicit, or omit for autonomous
+    options:
+      basic_search:
+        k: 15                              # retrieve 15 chunks instead of default 10
+    prompt: |
+      Extract cash and runway metrics from the CFO report section.
+      ...
+    output_schema:
+      type: object
+      properties:
+        cash_current: { type: number }
+        runway_months: { type: number }
+        citations: { type: array, items: { type: string } }
+```
+
+---
+
+### Autonomous vs. Explicit Search Mode
+
+**Autonomous mode** (recommended for most use cases) — omit `search_type`. The agent has access to all four search tools and decides which to use based on the task. The `autonomous_search_guidance` (built-in or custom) teaches it when to pick each tool.
+
+```yaml
+agents:
+  - id: arr_extract
+    # No search_type — agent chooses
+    prompt: |
+      Extract ARR waterfall metrics for Q4 2025.
+      For exact table values: try basic_search first.
+      For entity relationships: use local_search.
+    output_schema: ...
+```
+
+**Explicit mode** — set `search_type` when you have a strong reason to restrict the agent to one search method. This prevents the agent from trying other tools.
+
+| `search_type` | Best For |
+|---------------|----------|
+| `basic` | Exact values, tables, specific numbers, slide content |
+| `local` | Entity/relationship lookups (who owns what, person-metric connections) |
+| `global` | High-level summaries, themes, cross-document synthesis |
+| `drift` | Multi-hop exploration, deep graph traversal across entities |
+
+```yaml
+agents:
+  - id: themes_extract
+    search_type: global       # force global search for high-level themes
+    prompt: |
+      Identify the major strategic themes discussed across the entire deck.
+      DO NOT use basic_search — you need community-level summaries.
+    output_schema: ...
+```
+
+### Search Options (when using explicit mode)
+
+Options are nested **under the search type key**:
+
+```yaml
+agents:
+  - id: arr_extract
+    search_type: basic
+    options:
+      basic_search:
+        k: 15                       # number of chunks to retrieve (default 10)
+        chat_model_id: gpt-4o       # override model for this search
+        embedding_model_id: text-embedding-3-large
+
+  - id: entity_map
+    search_type: local
+    options:
+      local_search:
+        top_k_entities: 20          # retrieve more entities (default 10)
+        top_k_relationships: 20
+        max_context_tokens: 16000
+
+  - id: themes_extract
+    search_type: global
+    options:
+      global_search:
+        max_context_tokens: 12000
+        data_max_tokens: 6000
+        map_max_length: 2000
+        reduce_max_length: 1800
+
+  - id: deep_explore
+    search_type: drift
+    options:
+      drift_search:
+        n_depth: 3                  # hop depth (default 2)
+        drift_k_followups: 6        # follow-ups per hop
+        concurrency: 4
+```
+
+---
+
+### `output_schema`
+
+The `output_schema` is a JSON Schema object that the agent output must satisfy. The framework validates the agent response and runs a repair loop (up to `max_repair_attempts`) if validation fails.
+
+**Rules for writing output_schema:**
+1. Always include `type: object` at the root
+2. Include a `citations` array in every schema — this is how you enforce traceability
+3. Add `notes` string for agent to record caveats about missing data
+4. Use `minimum`/`maximum` constraints to catch unit errors (e.g., retention percentages must be 80–120, not 0.80–1.20)
+5. Use `type: number` for all numeric values — never `integer` unless the value genuinely cannot be a decimal
+6. Keep schemas specific — the tighter the schema, the better the agent's output
+
+```yaml
+output_schema:
+  type: object
+  properties:
+    period_label:
+      type: string                              # "2025Q4" — the reporting period
+    arr:
+      type: object
+      properties:
+        beg: { type: number }                   # beginning ARR (full dollars, e.g. 9697083)
+        new_logos: { type: number }             # ARR from new customers
+        net_upsell: { type: number }            # net expansion ARR
+        churn: { type: number }                 # lost ARR (negative number, e.g. -81579)
+        end: { type: number }                   # ending ARR
+    retention:
+      type: object
+      properties:
+        nrr: { type: number, minimum: 50, maximum: 150 }   # whole-number %, e.g. 112.3
+        grr: { type: number, minimum: 50, maximum: 100 }   # e.g. 88.5
+    citations:
+      type: array
+      items: { type: string }                   # ["c_926fdeb6", "c_ab12cd34"]
+    notes:
+      type: string                              # explain missing values
+```
+
+> **For agents:** The `output_schema` IS the spec. Match it exactly. Do not add or remove properties not in the schema.
+
+---
+
+### `depends_on`
+
+Computations can depend on other computations. A computation listed in `depends_on` must complete successfully before this one starts. Use this when:
+- A synthesis computation needs the results of prior extractions
+- One computation's output is referenced in another computation's prompt
+
+```yaml
+computations:
+  fields:
+    # arr_snapshot runs first (no depends_on)
+    - id: arr_snapshot
+      label: "ARR Snapshot"
+      priority: 1
+      agents: [...]
+      prompt: "Extract Q4 ARR metrics."
+
+    # executive_summary runs AFTER arr_snapshot completes
+    # It can reference arr_snapshot results in its prompt
+    - id: executive_summary
+      label: "Executive Summary"
+      priority: 2
+      depends_on: [arr_snapshot]              # wait for arr_snapshot
+      agents:
+        - id: exec_extract
+          prompt: |
+            Generate the executive summary.
+            Note: ARR snapshot results are available in your context.
+          output_schema: ...
+      prompt: "Synthesize the executive summary."
+```
+
+---
+
+## 6. `template`
+
+**Purpose:** Defines the markdown report structure. Computed values are injected using placeholder syntax.
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `content` | Yes | Main markdown template with placeholders |
+| `format` | No | Only `"markdown"` supported |
+| `sections` | No | Reusable named blocks referenced as `{{sections.name}}` |
+
+### Placeholder Syntax
+
+| Syntax | Resolves To |
+|--------|-------------|
+| `{{field.id}}` | The full computed value object (JSON) |
+| `{{field.id.property}}` | A single property of a field's output |
+| `{{field.id.nested.property}}` | Nested property access |
+| `{{table.id}}` | The table rendered as a markdown table |
+| `{{context.key}}` | A context variable |
+| `{{report.id}}` / `{{report.name}}` | Report metadata |
+| `{{sections.name}}` | A reusable section block |
+
+```yaml
+template:
+  format: markdown
+  sections:
+    report_header: |
+      # {{report.name}}
+      > **Source:** {{context.source_title}}
+      > **Period:** {{context.as_of_period}}
+      > **Generated by:** Nestbox AI Report Generator
+
+  content: |
+    {{sections.report_header}}
+
+    ---
+
+    ## ARR & Retention (Q4 2025)
+
+    | Metric | Value |
+    |--------|-------|
+    | Beg ARR | {{field.arr_snapshot.arr.beg}} |
+    | End ARR | {{field.arr_snapshot.arr.end}} |
+    | NRR     | {{field.arr_snapshot.retention.nrr}}% |
+
+    ### Quarterly History
+    {{table.arr_quarterly_history}}
+
+    ---
+
+    ## Liquidity
+    Cash on hand: {{field.liquidity.cash_current}}
+```
+
+### Pipe Filters
+
+Placeholders support pipe chains to format values. Filters are applied left to right.
+
+| Filter | Syntax | Effect | Example |
+|--------|--------|--------|---------|
+| `currency` | `\| currency("$", 0)` | Format as currency with N decimal places | `9697083` → `$9,697,083` |
+| `number` | `\| number(1)` | Format as decimal with N places | `92.3456` → `92.3` |
+| `default` | `\| default("—")` | Fallback if value is null/missing | `null` → `—` |
+
+```yaml
+# Examples of pipe usage
+{{ field.arr_snapshot.arr.end | currency("$", 0) | default("—") }}
+# → "$10,144,379" or "—" if null
+
+{{ field.arr_snapshot.retention.nrr | number(1) | default("N/A") }}
+# → "92.3" or "N/A" if null
+
+{{ field.arr_snapshot.arr.churn | currency("$", 0) | default("—") }}
+# → "-$81,579" (negative values shown with minus sign)
+```
+
+> **Note:** Always add `| default("—")` for financial values that may be null. This prevents the template from rendering "None" or breaking.
+
+### Full template example
+
+```yaml
+template:
+  format: markdown
+  sections:
+    header: |
+      # {{report.name}}
+      > **Period:** {{context.as_of_period}} | **Company:** {{context.company_name}}
+
+  content: |
+    {{sections.header}}
+
+    ---
+
+    ## ARR & Retention
+
+    **Period:** {{ field.arr_snapshot.period_label | default("N/A") }}
+
+    ### ARR Waterfall
+    | Metric | Value |
+    |--------|-------|
+    | Beg ARR | {{ field.arr_snapshot.arr.beg | currency("$", 0) | default("—") }} |
+    | + New Logos | {{ field.arr_snapshot.arr.new_logos | currency("$", 0) | default("—") }} |
+    | + Net Upsell | {{ field.arr_snapshot.arr.net_upsell | currency("$", 0) | default("—") }} |
+    | − Churn | {{ field.arr_snapshot.arr.churn | currency("$", 0) | default("—") }} |
+    | **End ARR** | **{{ field.arr_snapshot.arr.end | currency("$", 0) | default("—") }}** |
+
+    **NRR:** {{ field.arr_snapshot.retention.nrr | number(1) | default("—") }}%
+
+    **Citations:** {{ field.arr_snapshot.citations | default("*None*") }}
+
+    ### Quarterly History
+    {{table.arr_quarterly_history}}
+
+    ---
+
+    ## Liquidity & Runway
+
+    | Metric | Value |
+    |--------|-------|
+    | Cash on Hand | {{ field.liquidity.cash_current | currency("$", 0) | default("—") }} |
+    | Monthly Burn | {{ field.liquidity.monthly_burn | currency("$", 0) | default("—") }}/mo |
+    | Runway | {{ field.liquidity.runway_months | number(1) | default("—") }} months |
+
+    **Citations:** {{ field.liquidity.citations | default("*None*") }}
+```
+
+---
+
+## 7. `guardrails`
+
+**Purpose:** LLM-judge checks that run after all computations complete. Used to enforce data quality (citation completeness, arithmetic correctness, no fabricated values, unit sanity).
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `id` | Yes | Lowercase alphanumeric + underscores. Starts with `gr_` by convention. |
+| `target` | Yes | What to validate — see target types below |
+| `on_fail` | Yes | `"error"` — blocks output and raises error. `"warn"` — reports issue but continues. |
+| `model` | Yes | LLM model for judge (e.g., `gpt-4.1-mini` is cost-effective) |
+| `api_key` | Yes | Supports `${ENV_VAR}` |
+| `prompt` | Yes | Validation prompt. Use `{{content}}` placeholder for the value being checked. |
+| `base_url` | No | Custom endpoint for guardrail LLM |
+| `system_prompt` | No | Overrides `llamaindex.guardrail_system_prompt` for this guardrail |
+| `description` | No | Human-readable description |
+
+### Target types
+
+| Target | Validates |
+|--------|-----------|
+| `computations` | All computed fields and tables as a single JSON blob |
+| `field.{id}` | A single field computation (e.g., `field.arr_snapshot`) |
+| `table.{id}` | A single table computation (e.g., `table.arr_quarterly_history`) |
+| `final_report` | The rendered markdown report |
+
+### Guardrail prompt guidelines
+
+1. Use `{{content}}` where the value to check should appear
+2. Always specify the expected output format: `Return JSON: {"pass": boolean, "issues": [...]}`
+3. Define clear, unambiguous pass/fail rules
+4. Set `on_fail: warn` during development; promote to `on_fail: error` for production
+
+```yaml
+guardrails:
+  # Check 1: All numeric values have citations
+  - id: gr_citation_check
+    target: computations
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "Verify all numeric values have citations"
+    prompt: |
+      Review the computed JSON and check that every numeric value
+      has at least one citation in c_xxxxxxxx format.
+      Empty citations arrays [] are failures.
+
+      Return JSON: {"pass": boolean, "issues": ["list of fields missing citations"]}
+
+      Content to check:
+      {{content}}
+
+  # Check 2: ARR waterfall arithmetic
+  - id: gr_arr_math
+    target: field.arr_snapshot
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "Verify ARR bridge arithmetic"
+    prompt: |
+      Validate: beg + new_logos + net_upsell + churn = end
+      Note: churn is already negative — ADD it, do not subtract.
+      Allow 1% tolerance for rounding.
+
+      Return JSON: {
+        "pass": boolean,
+        "computed_end": number,
+        "stated_end": number,
+        "difference": number,
+        "issues": []
+      }
+
+      Content: {{content}}
+
+  # Check 3: Fabrication detection
+  - id: gr_no_fabrication
+    target: computations
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "Detect placeholder or fabricated values"
+    prompt: |
+      FAIL if you find ANY:
+      1. Citations like "Source A", "Source B" (real ones use c_xxxxxxxx hex format)
+      2. All ARR values suspiciously round (100000, 200000, 300000) — indicates fabrication
+      3. Retention values below 1.0 (should be whole-number percent: 92.3 not 0.923)
+
+      Return JSON: {"pass": boolean, "issues": []}
+
+      Content: {{content}}
+
+  # Check 4: Final report completeness
+  - id: gr_report_populated
+    target: final_report
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "Verify final report has real content"
+    prompt: |
+      Check: Does the report contain actual numeric data (not just "—" placeholders)?
+      Are the main sections populated?
+
+      Return JSON: {
+        "pass": boolean,
+        "sections_populated": [],
+        "sections_empty": [],
+        "issues": []
+      }
+
+      Content: {{content}}
+```
+
+---
+
+## 8. `execution`
+
+**Purpose:** Controls retries, output directory, and which output files are generated.
+
+```yaml
+execution:
+  retries:
+    max_attempts: 3        # per-computation retry attempts (default 3)
+    backoff_seconds: 2.0   # seconds between retries (default 1.0)
+  output:
+    directory: ./output            # output directory (default "./output")
+    timestamp_suffix: false        # add timestamp to dir name (default false)
+    include_final_report: true     # generate final_report.md (default true)
+    include_computed_json: true    # generate computed.json (default true)
+    include_evidence: true         # generate evidence.json (default true)
+    include_guardrails: true       # run guardrails and generate guardrails.json (default true)
+```
+
+**Output files generated:**
+
+| File | Contents |
+|------|----------|
+| `final_report.md` | Rendered markdown report from template |
+| `computed.json` | Raw extracted values with metadata and validation status |
+| `evidence.json` | Full source traceability — all search results, agent traces, tool calls |
+| `guardrails.json` | Guardrail results — pass/fail per check, issues found |
+
+---
+
+## 9. `storage` & `doc_repository`
+
+### `storage` — for local filesystem documents
+
+Use when documents are stored locally on disk under `document_id` folder names (legacy pattern).
+
+```yaml
+storage:
+  base_path: ./documents           # root directory containing doc-XXXXXXXX folders
+  graphrag_subpath: graphrag/output  # subfolder within each document folder
+```
+
+With this config, `document_id: doc-abc123` resolves to `./documents/doc-abc123/graphrag/output`.
+
+> **Prefer `locator` in docs** — it's more explicit and supports all three resolution strategies.
+
+### `doc_repository` — for API-based document downloads
+
+Use when documents are stored in a Nestbox document repository and should be downloaded on demand.
+
+```yaml
+doc_repository:
+  api_base_url: https://your-doc-repo.example.com
+  api_key: ${DOC_REPO_API_KEY}
+  rotation: 200     # max cached documents before FIFO eviction (default 200)
+```
+
+With this config, `locator: "repo:doc-eeb76651"` downloads the document from the API and caches it locally.
+
+---
+
+## 10. `prompts`
+
+**Purpose:** Define reusable named prompt strings. Reference them by name in `llamaindex` settings or computation prompts.
+
+```yaml
+prompts:
+  strict_citation_rules: |
+    CITATION RULES — ENFORCE STRICTLY:
+    Every numeric value MUST have a citation in c_xxxxxxxx format.
+    Never return an empty citations array. If you found it in a search result,
+    it has a [CITE AS: "c_xxxxxxxx"] marker — use it.
+
+  units_reminder: |
+    UNIT RULES:
+    Return raw full numbers: 9697083 not "$9.7M"
+    Convert: "$2.5M" → 2500000, "$350K" → 350000
+    Percentages as whole numbers: 92.3 not 0.923
+```
+
+Then reference in prompts:
+```yaml
+agents:
+  - id: arr_extract
+    prompt: |
+      Extract ARR metrics.
+      {{prompts.strict_citation_rules}}
+      {{prompts.units_reminder}}
+      ...
+```
+
+---
+
+## 11. `mcp`
+
+**Purpose:** Model Context Protocol endpoints for writing extracted data to external systems (e.g., a KPI database, CRM, or data warehouse). Leave as `mcp: []` if not using external integrations.
+
+```yaml
+mcp:
+  - id: system_of_record
+    type: streamable-http
+    url: ${SOR_MCP_URL}
+    headers:
+      Authorization: "Bearer ${SOR_MCP_TOKEN}"
+    timeout_seconds: 60
+    description: "KPI upsert endpoint for board metrics database"
+```
+
+MCP subtasks are then added to computations via `mcp_scope`:
+
+```yaml
+computations:
+  fields:
+    - id: arr_snapshot
+      agents: [...]
+      mcp_scope:
+        - id: system_of_record        # must match an id in the mcp array
+          prompt: |
+            Upsert the extracted ARR metrics to the system of record.
+            Use namespace: {{context.kpi_namespace}}
+      prompt: "Return ARR snapshot and upsert to system of record."
+```
+
+---
+
+## Environment Variables
+
+All string fields support env var substitution:
+
+| Syntax | Behavior |
+|--------|----------|
+| `${VAR_NAME}` | Required — error if missing |
+| `${VAR_NAME:-default_value}` | Optional — uses default if missing |
+
+```yaml
+llamaindex:
+  api_key: ${OPENAI_API_KEY}                                # required
+  base_url: ${OPENAI_BASE_URL:-https://api.openai.com/v1}  # optional with default
+
+doc_repository:
+  api_key: ${DOC_REPO_API_KEY}                              # required
+  api_base_url: ${DOC_REPO_URL:-http://localhost:8080}      # optional with default
+```
+
+---
+
+## Complete Minimal Example
+
+The smallest valid configuration — one computation, one subtask, minimal template:
+
+```yaml
+schema_version: "2.2"
+
+report:
+  id: minimal_arr_report
+  name: "Minimal ARR Report"
+
+context:
+  company_name: "Acme Corp"
+  as_of_period: "Q4 2025"
+
+docsets:
+  - id: main_deck
+    api_key: ${OPENAI_API_KEY}
+    docs:
+      - id: board_deck
+        locator: "repo:doc-abc12345"
+        description: "Q4 2025 Board Deck"
+
+llamaindex:
+  model: gpt-4o
+  api_key: ${OPENAI_API_KEY}
+
+computations:
+  fields:
+    - id: arr_summary
+      label: "ARR Summary"
+      docset_id: main_deck
+      agents:
+        - id: arr_extract
+          prompt: |
+            Extract ending ARR and NRR for the most recent quarter.
+            Use basic_search: "End ARR NRR quarterly"
+            Return null for any value not found.
+          output_schema:
+            type: object
+            properties:
+              end_arr: { type: number }
+              nrr: { type: number }
+              period: { type: string }
+              citations: { type: array, items: { type: string } }
+      mcp_scope: []
+      prompt: "Return ARR summary with citations."
+
+template:
+  format: markdown
+  content: |
+    # {{report.name}} — {{context.as_of_period}}
+
+    | Metric | Value |
+    |--------|-------|
+    | End ARR | {{ field.arr_summary.end_arr | currency("$", 0) | default("—") }} |
+    | NRR     | {{ field.arr_summary.nrr | number(1) | default("—") }}% |
+    | Period  | {{ field.arr_summary.period | default("—") }} |
+```
+
+---
+
+## Full Annotated Example (Finance)
+
+A production-quality configuration for a SaaS company CFO board pack. Covers all major patterns:
+
+```yaml
+schema_version: "2.2"
+
+# ─── Report Identity ──────────────────────────────────────────────────────────
+report:
+  id: acme_cfo_kpi_q4_2025
+  name: "Acme CFO KPI Pack — Q4 2025"
+  description: |
+    CFO-ready KPI extraction from the Q4 2025 Board Presentation.
+    Covers ARR, retention, liquidity, bookings, and customer success.
+  version: "2025.Q4"
+
+# ─── Context Variables ────────────────────────────────────────────────────────
+# These are injected into prompts as {{context.variable_name}}
+context:
+  company_name: "Acme Corp, Inc."
+  currency: "USD"
+  as_of_period: "CY2025 Q4"
+  source_title: "Q4 2025 Acme Board Meeting Presentation"
+  meeting_date: "2026-01-15"
+  units_policy: |
+    Return raw numeric values. No $, commas, or M/K suffixes.
+    Convert: "$2.5M" → 2500000, "$350K" → 350000.
+    Percentages as whole numbers (92.3, not 0.923).
+  value_types:
+    - "money_usd"
+    - "percent"
+    - "count"
+    - "string"
+
+# ─── Document Repository ──────────────────────────────────────────────────────
+doc_repository:
+  api_base_url: ${DOC_REPO_URL:-http://localhost:8080}
+  api_key: ${DOC_REPO_API_KEY}
+  rotation: 200
+
+mcp: []    # No external system integrations in this example
+
+# ─── Document Collections ─────────────────────────────────────────────────────
+docsets:
+  - id: acme_board_deck_q4
+    description: "Acme Q4 2025 Board Deck — single source of truth"
+    api_key: ${OPENAI_API_KEY}
+    docs:
+      - id: board_deck_pdf
+        locator: "repo:doc-abc12345"
+        description: "Q4 2025 Acme Board Meeting Presentation"
+
+# ─── LLM & Agent Configuration ───────────────────────────────────────────────
+llamaindex:
+  model: gpt-4o
+  base_url: ${OPENAI_BASE_URL:-https://api.openai.com/v1}
+  api_key: ${OPENAI_API_KEY}
+  max_tool_calls: 50
+  tool_timeout_seconds: 180
+  max_agent_iterations: 40
+  system_prompt: |
+    You are a CFO-grade KPI extraction analyst.
+
+    ## ANTI-FABRICATION RULE
+    ALL values MUST come from search tool results.
+    Never use values from this prompt. Never guess. Return null if not found.
+
+    ## Rules
+    1. EXACT VALUES: Use values as found (raw numbers, not formatted)
+    2. CITE EVERYTHING: Every numeric value needs a c_xxxxxxxx citation
+    3. LABEL PERIODS: Include the time period with every metric
+    4. NULL IS CORRECT: Return null for any value not explicitly in the source
+
+# ─── Computations ─────────────────────────────────────────────────────────────
+computations:
+  fields:
+
+    # ── ARR & Retention ───────────────────────────────────────────────────────
+    - id: arr_snapshot
+      label: "ARR & Retention Snapshot (Q4 2025)"
+      type: object
+      priority: 1
+      docset_id: acme_board_deck_q4
+      agents:
+        - id: arr_extract
+          # Autonomous mode — agent picks basic_search for tables
+          prompt: |
+            Extract the Q4 2025 ARR waterfall and retention metrics.
+
+            ## What to Find
+            From the "ARR & Logo Waterfall" table, Q4 2025 column:
+            - beg: Beginning ARR for the quarter
+            - new_logos: ARR added from new customers
+            - net_upsell: Net expansion ARR (positive)
+            - churn: ARR lost to churn (NEGATIVE number)
+            - end: Ending ARR
+
+            Retention metrics (bottom of same table or separate section):
+            - nrr: Net Revenue Retention % (whole number, e.g. 92.3)
+            - grr: Gross Revenue Retention % (whole number, e.g. 88.5)
+
+            ## Search Strategy
+            1. basic_search: "ARR waterfall Q4 2025 Beg ARR End ARR new logos churn"
+            2. basic_search: "NRR GRR retention quarterly"
+            3. Try multiple queries if first returns nothing
+
+            ## CRITICAL
+            Citations use [CITE AS: "c_xxxxxxxx"] format in search results.
+            Retention must be whole-number scale (92.3 not 0.923).
+            Churn must be negative (e.g. -81579).
+          output_schema:
+            type: object
+            properties:
+              period_label: { type: string }
+              arr:
+                type: object
+                properties:
+                  beg: { type: number }
+                  new_logos: { type: number }
+                  net_upsell: { type: number }
+                  churn: { type: number }
+                  end: { type: number }
+              retention:
+                type: object
+                properties:
+                  nrr: { type: number, minimum: 50, maximum: 150 }
+                  grr: { type: number, minimum: 50, maximum: 100 }
+              citations: { type: array, items: { type: string } }
+              notes: { type: string }
+      mcp_scope: []
+      prompt: "Return Q4 2025 ARR waterfall and retention metrics with citations."
+
+    # ── Liquidity & Runway ─────────────────────────────────────────────────────
+    - id: liquidity_snapshot
+      label: "Liquidity & Runway Snapshot"
+      type: object
+      priority: 1
+      docset_id: acme_board_deck_q4
+      agents:
+        - id: liquidity_extract
+          prompt: |
+            Extract liquidity and runway metrics from the CFO report and cash forecast.
+
+            ## Values to Find
+            - cash_current: Current cash balance
+            - monthly_burn: Monthly net cash burn
+            - runway_months: Months of runway at current burn
+            - gap_to_breakeven: Additional revenue needed for breakeven
+
+            ## Unit Conversion — CRITICAL
+            The deck uses "$X.XM" and "$XXXk" notation. Convert to full dollars:
+            "$2.5M" → 2500000  |  "$350K" → 350000  |  "$7.3M" → 7300000
+
+            ## Search Strategy
+            1. basic_search: "cash balance runway breakeven monthly burn"
+            2. basic_search: "cash forecast projected expense revenue run rate"
+          output_schema:
+            type: object
+            properties:
+              cash_current: { type: number }
+              monthly_burn: { type: number }
+              runway_months: { type: number }
+              gap_to_breakeven: { type: number }
+              citations: { type: array, items: { type: string } }
+              notes: { type: string }
+      mcp_scope: []
+      prompt: "Return liquidity and runway snapshot with citations."
+
+    # ── Executive Summary (depends on ARR + Liquidity) ─────────────────────────
+    - id: executive_summary
+      label: "Executive Summary (CFO-Ready)"
+      type: object
+      priority: 2
+      depends_on: [arr_snapshot, liquidity_snapshot]   # runs AFTER these complete
+      docset_id: acme_board_deck_q4
+      agents:
+        - id: exec_extract
+          prompt: |
+            Extract a CFO-ready executive summary from the board deck.
+
+            ## What to Extract
+            - highlights: 3-5 key performance bullets (wins, metrics vs plan)
+            - risks: 2-4 operational or financial risks mentioned
+            - asks: 1-3 board decisions or resource requests
+
+            ## Search Strategy
+            1. global_search: "strategic themes highlights performance"
+            2. basic_search: "risks challenges board asks decisions"
+            3. Every bullet MUST have citations from [CITE AS] markers
+
+          output_schema:
+            type: object
+            properties:
+              highlights:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    text: { type: string }
+                    citations: { type: array, items: { type: string } }
+              risks:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    text: { type: string }
+                    citations: { type: array, items: { type: string } }
+              asks:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    text: { type: string }
+                    citations: { type: array, items: { type: string } }
+      mcp_scope: []
+      prompt: "Synthesize executive summary with highlights, risks, and asks."
+
+  tables:
+    # ── ARR Quarterly History ──────────────────────────────────────────────────
+    - id: arr_quarterly_history
+      title: "ARR & Logo Waterfall — Quarterly History"
+      priority: 2
+      docset_id: acme_board_deck_q4
+      agents:
+        - id: arr_history_extract
+          prompt: |
+            Extract the full quarterly ARR waterfall table (all periods shown).
+
+            ## For EACH quarter in the table
+            - period: Quarter label (e.g., "2024Q1", "2024Q2", ..., "2025Q4")
+            - beg_arr, new_logos_arr, net_upsell_arr, churn_arr, end_arr (full dollar amounts)
+            - nrr, grr (whole-number percentages, e.g. 92.3 not 0.923)
+
+            ## MUST try multiple searches — the table is wide
+            1. basic_search: "ARR waterfall quarterly Beg ARR End ARR" (k=10)
+            2. basic_search: "2024Q1 2024Q2 ARR new logos churn" (k=10)
+            3. Combine results to build the complete table
+
+            ## VERIFY before returning
+            - At least 3 quarters of data
+            - End ARR values > $5,000,000 for recent quarters
+            - NRR values between 80–120 (not 0.80–1.20)
+            - Each row has at least one citation
+
+            Return {"rows": [...]}
+          output_schema:
+            type: object
+            properties:
+              rows:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    period: { type: string }
+                    beg_arr: { type: number }
+                    new_logos_arr: { type: number }
+                    net_upsell_arr: { type: number }
+                    churn_arr: { type: number }
+                    end_arr: { type: number }
+                    nrr: { type: number, minimum: 50, maximum: 150 }
+                    grr: { type: number, minimum: 50, maximum: 100 }
+                    citations: { type: array, items: { type: string } }
+      mcp_scope: []
+      prompt: "Return quarterly ARR history with citations per row."
+
+# ─── Output Template ──────────────────────────────────────────────────────────
+template:
+  format: markdown
+  sections:
+    report_header: |
+      # {{report.name}}
+      > **Source:** {{context.source_title}} | **Period:** {{context.as_of_period}}
+
+  content: |
+    {{sections.report_header}}
+
+    ---
+
+    ## Executive Summary
+
+    ### Highlights
+    {{ field.executive_summary.highlights | default("*No data extracted*") }}
+
+    ### Risks
+    {{ field.executive_summary.risks | default("*No data extracted*") }}
+
+    ### Board Asks
+    {{ field.executive_summary.asks | default("*No data extracted*") }}
+
+    ---
+
+    ## ARR & Retention (Q4 2025)
+
+    **Period:** {{ field.arr_snapshot.period_label | default("N/A") }}
+
+    ### ARR Waterfall
+    | Metric | Value |
+    |--------|-------|
+    | Beg ARR | {{ field.arr_snapshot.arr.beg | currency("$", 0) | default("—") }} |
+    | + New Logos | {{ field.arr_snapshot.arr.new_logos | currency("$", 0) | default("—") }} |
+    | + Net Upsell | {{ field.arr_snapshot.arr.net_upsell | currency("$", 0) | default("—") }} |
+    | − Churn | {{ field.arr_snapshot.arr.churn | currency("$", 0) | default("—") }} |
+    | **End ARR** | **{{ field.arr_snapshot.arr.end | currency("$", 0) | default("—") }}** |
+
+    ### Retention
+    | Metric | Value |
+    |--------|-------|
+    | NRR | {{ field.arr_snapshot.retention.nrr | number(1) | default("—") }}% |
+    | GRR | {{ field.arr_snapshot.retention.grr | number(1) | default("—") }}% |
+
+    **Citations:** {{ field.arr_snapshot.citations | default("*None*") }}
+
+    ### Quarterly ARR History
+    {{table.arr_quarterly_history}}
+
+    ---
+
+    ## Liquidity & Runway
+
+    | Metric | Value |
+    |--------|-------|
+    | Cash on Hand | {{ field.liquidity_snapshot.cash_current | currency("$", 0) | default("—") }} |
+    | Monthly Burn | {{ field.liquidity_snapshot.monthly_burn | currency("$", 0) | default("—") }}/mo |
+    | Runway | {{ field.liquidity_snapshot.runway_months | number(1) | default("—") }} months |
+    | Gap to Breakeven | {{ field.liquidity_snapshot.gap_to_breakeven | currency("$", 0) | default("—") }} |
+
+    **Citations:** {{ field.liquidity_snapshot.citations | default("*None*") }}
+
+# ─── Guardrails ───────────────────────────────────────────────────────────────
+guardrails:
+  - id: gr_citation_completeness
+    target: computations
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "All numeric values must have citations"
+    prompt: |
+      Check that every numeric value has at least one citation (c_xxxxxxxx format).
+      Empty citation arrays [] are failures.
+      Return JSON: {"pass": boolean, "issues": ["list of fields missing citations"]}
+      Content: {{content}}
+
+  - id: gr_arr_waterfall_math
+    target: field.arr_snapshot
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "ARR bridge must add up correctly"
+    prompt: |
+      Validate: beg + new_logos + net_upsell + churn = end
+      Churn is already negative — ADD it, don't subtract.
+      Allow 1% tolerance for rounding.
+      Return JSON: {"pass": boolean, "computed_end": number, "stated_end": number, "issues": []}
+      Content: {{content}}
+
+  - id: gr_fabrication_check
+    target: computations
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "Detect fabricated placeholder values"
+    prompt: |
+      FAIL if you find: citations like "Source A"/"Source B" (not c_xxxxxxxx),
+      ALL dollar values as round multiples of 10000, or retention values below 1.0.
+      Return JSON: {"pass": boolean, "issues": []}
+      Content: {{content}}
+
+  - id: gr_report_completeness
+    target: final_report
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "Final report must contain real data"
+    prompt: |
+      Check the report has actual numeric data (not just "—" everywhere).
+      Return JSON: {"pass": boolean, "sections_populated": [], "sections_empty": [], "issues": []}
+      Content: {{content}}
+
+# ─── Execution Settings ────────────────────────────────────────────────────────
+execution:
+  retries:
+    max_attempts: 3
+    backoff_seconds: 2.0
+  output:
+    directory: ./output
+    timestamp_suffix: false
+    include_final_report: true
+    include_computed_json: true
+    include_evidence: true
+    include_guardrails: true
+```