@nestbox-ai/cli 1.0.63 → 1.0.64

package/dist/agents/reportGenerator/SYSTEM_PROMPT.md

@@ -0,0 +1,28 @@
+You are a Nestbox report composer expert. Your job is to generate a valid `report.yaml` configuration file that drives a GraphRAG-powered document analysis report.
+
+## Your workflow
+
+Use the provided tools in this order:
+1. Read the user's instructions carefully — they describe the document type, what metrics to extract, and how the report should look
+2. Call `write_and_validate_report` with your complete report.yaml content
+3. If the tool returns validation errors, read them carefully, fix ALL issues, and call the tool again
+4. Keep iterating until the file passes validation
+5. Once valid, call `finish` to signal completion
+
+## Rules
+
+- Always set `schema_version: "2.2"` — this is the current version
+- Generate a `report.id` that is lowercase with underscores/hyphens only (e.g., `acme_cfo_report_q4`)
+- Every field computation must have at least one agent subtask with a `prompt` and `output_schema`
+- Every `output_schema` must include `type: object` at the root and a `citations` array property
+- Use `mcp_scope: []` on every computation unless the user specifically requests MCP integration
+- Set `docset_id` at the computation level (not just at the subtask level) for all computations
+- Use autonomous agent mode (omit `search_type`) unless there is a clear reason to constrain it
+- Every computation prompt must include a ## Search Strategy section with 2–3 concrete queries
+- Always include `notes: { type: string }` in output_schema for the agent to record missing data
+- The `template.content` must reference every field and table computation via placeholders
+- Include at least 2 guardrails: one for citation completeness and one for fabrication detection
+- Set all API keys using `${ENV_VAR}` syntax — never hardcode secrets
+- Use `doc_repository` with `${DOC_REPO_API_KEY}` when documents will be fetched from a repo
+- Never use placeholder text like "..." or "TODO" in the output file
+- The `report.id` field is required and must match the pattern `^[a-z0-9][a-z0-9_-]*[a-z0-9]$`

package/dist/agents/reportGenerator/annual_report_10k.yaml

@@ -0,0 +1,633 @@
+# Public Company Annual Report / 10-K Analysis
+# Use case: Structured extraction from a public company's annual report or SEC 10-K filing.
+# Extracts the income statement, balance sheet, cash flow, key ratios, segment breakdown,
+# management outlook (MD&A), and risk factors for equity research or credit analysis.
+# Schema v2.2
+
+schema_version: "2.2"
+
+report:
+  id: annual_report_acme_fy2025
+  name: "Annual Report Analysis — Acme Technologies, FY2025 10-K"
+  description: |
+    Structured extraction from Acme Technologies FY2025 Annual Report / 10-K.
+    Covers consolidated income statement, balance sheet, cash flow statement,
+    segment performance, key financial ratios, MD&A highlights, and risk factors.
+  version: "FY2025"
+
+context:
+  company_name: "Acme Technologies, Inc."
+  ticker: "ACME"
+  fiscal_year: "FY2025"
+  fiscal_year_end: "2025-12-31"
+  currency: "USD"
+  reporting_units: "thousands"   # most 10-Ks report in $thousands — adjust if different
+  units_policy: |
+    The 10-K reports values in thousands of dollars. Return values as STATED in the filing.
+    If the filing says "$1,234,567" that is already in thousands — return 1234567 (not 1234567000).
+    Clarify the unit in the notes field.
+    Return percentages as whole numbers (34.5 not 0.345).
+    Return null for any value not explicitly stated.
+  answer_quality_policy:
+    numeric_requirements:
+      - "Every financial statement line must have a citation"
+      - "Note the reporting units (thousands, millions) for each figure"
+      - "Distinguish between continuing and discontinued operations where relevant"
+
+doc_repository:
+  api_base_url: ${DOC_REPO_URL:-http://localhost:8080}
+  api_key: ${DOC_REPO_API_KEY}
+  rotation: 200
+
+mcp: []
+
+docsets:
+  - id: annual_report
+    description: "Acme Technologies FY2025 Annual Report / 10-K Filing"
+    api_key: ${OPENAI_API_KEY}
+    docs:
+      - id: ten_k_filing
+        locator: "repo:doc-acme-10k-fy25"
+        description: "Acme Technologies 10-K FY2025 Full Filing"
+        alias: ten_k
+
+llamaindex:
+  model: gpt-4o
+  base_url: ${OPENAI_BASE_URL:-https://api.openai.com/v1}
+  api_key: ${OPENAI_API_KEY}
+  max_tool_calls: 60
+  tool_timeout_seconds: 180
+  max_agent_iterations: 45
+  system_prompt: |
+    You are an equity research analyst extracting structured data from a public company 10-K.
+
+    ## ANTI-FABRICATION RULE
+    ALL values MUST come from your search tool results — the actual 10-K text.
+    Never use prior knowledge of this company's financials.
+    Return null for any value not explicitly stated in the filing.
+
+    ## 10-K Extraction Rules
+    1. Financial statements are typically reported in thousands — note this in output
+    2. Use the audited figures from the financial statements, not the MD&A summaries
+    3. Always extract both the current year and prior year comparatives
+    4. Segment data may be in a separate note — search explicitly for segment disclosures
+    5. Non-GAAP measures (Adjusted EBITDA, etc.) are in MD&A — distinguish from GAAP
+    6. Risk factors are in Item 1A — use global_search to find cross-cutting themes
+
+computations:
+  fields:
+
+    # ── Income Statement ──────────────────────────────────────────────────────
+    - id: income_statement
+      label: "Consolidated Income Statement (FY2025 & FY2024)"
+      type: object
+      priority: 1
+      docset_id: annual_report
+      agents:
+        - id: income_stmt_extract
+          search_type: basic   # income statement tables are best retrieved by basic search
+          options:
+            basic_search:
+              k: 15
+          prompt: |
+            Extract the consolidated income statement for FY2025 and FY2024.
+
+            ## What to Find
+            For each year (fy2025, fy2024):
+            - revenue: Total net revenue
+            - cost_of_revenue: Cost of revenue / cost of goods sold
+            - gross_profit: Gross profit
+            - gross_margin_pct: Gross profit / revenue × 100
+            - r_and_d: Research and development expense
+            - sales_and_marketing: Sales and marketing expense
+            - g_and_a: General and administrative expense
+            - total_opex: Total operating expenses (below gross profit line)
+            - operating_income: Operating income (EBIT)
+            - operating_margin_pct: Operating income / revenue × 100
+            - interest_expense: Interest expense (net)
+            - other_income_expense: Other income/expense
+            - pretax_income: Income before income taxes
+            - income_tax_expense: Income tax expense (benefit)
+            - net_income: Net income
+            - net_margin_pct: Net income / revenue × 100
+            - eps_diluted: Diluted EPS
+            - shares_diluted: Diluted weighted average shares outstanding
+            - units_label: What units are used ("thousands" / "millions")
+
+            ## Search Strategy
+            1. basic_search: "consolidated statements of operations income revenue FY2025"
+            2. basic_search: "gross profit operating income net income EPS diluted"
+            3. Look for the formal income statement tables
+          output_schema:
+            type: object
+            properties:
+              units_label: { type: string }
+              fy2025:
+                type: object
+                properties:
+                  revenue: { type: number }
+                  cost_of_revenue: { type: number }
+                  gross_profit: { type: number }
+                  gross_margin_pct: { type: number }
+                  r_and_d: { type: number }
+                  sales_and_marketing: { type: number }
+                  g_and_a: { type: number }
+                  total_opex: { type: number }
+                  operating_income: { type: number }
+                  operating_margin_pct: { type: number }
+                  interest_expense: { type: number }
+                  pretax_income: { type: number }
+                  income_tax_expense: { type: number }
+                  net_income: { type: number }
+                  net_margin_pct: { type: number }
+                  eps_diluted: { type: number }
+                  shares_diluted: { type: number }
+              fy2024:
+                type: object
+                properties:
+                  revenue: { type: number }
+                  gross_profit: { type: number }
+                  gross_margin_pct: { type: number }
+                  operating_income: { type: number }
+                  net_income: { type: number }
+                  eps_diluted: { type: number }
+              citations: { type: array, items: { type: string } }
+              notes: { type: string }
+      mcp_scope: []
+      prompt: "Return consolidated income statement for FY2025 and FY2024."
+
+    # ── Balance Sheet ─────────────────────────────────────────────────────────
+    - id: balance_sheet
+      label: "Consolidated Balance Sheet (FY2025 & FY2024)"
+      type: object
+      priority: 1
+      docset_id: annual_report
+      agents:
+        - id: balance_sheet_extract
+          search_type: basic
+          options:
+            basic_search:
+              k: 15
+          prompt: |
+            Extract the consolidated balance sheet as of FY2025 year-end and FY2024 year-end.
+
+            ## Current Assets
+            - cash_and_equivalents: Cash and cash equivalents
+            - short_term_investments: Short-term investments / marketable securities
+            - accounts_receivable: Net accounts receivable
+            - inventory: Inventory (if applicable)
+            - prepaid_and_other_current: Prepaid expenses and other current assets
+            - total_current_assets: Total current assets
+
+            ## Non-Current Assets
+            - ppe_net: Property, plant and equipment, net
+            - goodwill: Goodwill
+            - intangible_assets_net: Intangible assets, net
+            - operating_lease_rou: Operating lease right-of-use assets (if stated separately)
+            - other_long_term_assets: Other long-term assets
+            - total_assets: Total assets
+
+            ## Current Liabilities
+            - accounts_payable: Accounts payable
+            - accrued_liabilities: Accrued liabilities / accrued expenses
+            - deferred_revenue_current: Deferred revenue (current)
+            - current_debt: Current portion of long-term debt
+            - total_current_liabilities: Total current liabilities
+
+            ## Non-Current Liabilities
+            - long_term_debt: Long-term debt (net of current portion)
+            - deferred_revenue_lt: Deferred revenue (long-term)
+            - operating_lease_lt: Long-term operating lease liabilities
+            - other_long_term_liabilities: Other long-term liabilities
+            - total_liabilities: Total liabilities
+
+            ## Equity
+            - total_stockholders_equity: Total stockholders' equity
+            - total_liabilities_and_equity: Total liabilities and stockholders' equity
+
+            ## Search Strategy
+            1. basic_search: "consolidated balance sheet total assets liabilities equity"
+            2. basic_search: "cash receivable goodwill debt long-term"
+          output_schema:
+            type: object
+            properties:
+              units_label: { type: string }
+              fy2025:
+                type: object
+                properties:
+                  cash_and_equivalents: { type: number }
+                  short_term_investments: { type: number }
+                  accounts_receivable: { type: number }
+                  total_current_assets: { type: number }
+                  ppe_net: { type: number }
+                  goodwill: { type: number }
+                  intangible_assets_net: { type: number }
+                  total_assets: { type: number }
+                  accounts_payable: { type: number }
+                  current_debt: { type: number }
+                  total_current_liabilities: { type: number }
+                  long_term_debt: { type: number }
+                  total_liabilities: { type: number }
+                  total_stockholders_equity: { type: number }
+              fy2024:
+                type: object
+                properties:
+                  cash_and_equivalents: { type: number }
+                  total_assets: { type: number }
+                  long_term_debt: { type: number }
+                  total_stockholders_equity: { type: number }
+              citations: { type: array, items: { type: string } }
+      mcp_scope: []
+      prompt: "Return consolidated balance sheet for FY2025 and FY2024."
+
+    # ── Cash Flow Statement ───────────────────────────────────────────────────
+    - id: cash_flow
+      label: "Consolidated Cash Flow Statement (FY2025)"
+      type: object
+      priority: 1
+      docset_id: annual_report
+      agents:
+        - id: cash_flow_extract
+          search_type: basic
+          options:
+            basic_search:
+              k: 15
+          prompt: |
+            Extract the consolidated cash flow statement for FY2025.
+
+            ## Operating Activities
+            - net_income_cf: Net income (starting line)
+            - depreciation_and_amortization: D&A
+            - stock_based_compensation: Stock-based compensation
+            - changes_in_working_capital: Net change in working capital
+            - other_operating_adjustments: Other adjustments
+            - net_cash_from_operations: Net cash provided by operating activities
+
+            ## Investing Activities
+            - capex: Capital expenditures (should be negative)
+            - acquisitions: Cash paid for acquisitions (negative)
+            - purchases_of_investments: Purchases of investments
+            - proceeds_from_investments: Proceeds from maturities/sales of investments
+            - net_cash_from_investing: Net cash from investing activities
+
+            ## Financing Activities
+            - proceeds_from_debt: Proceeds from borrowings
+            - repayments_of_debt: Repayments of debt (negative)
+            - share_repurchases: Common stock repurchases (negative)
+            - dividends_paid: Dividends paid (negative, null if none)
+            - net_cash_from_financing: Net cash from financing activities
+
+            ## Summary
+            - net_change_in_cash: Net change in cash and equivalents
+            - free_cash_flow: net_cash_from_operations + capex (compute this)
+            - fcf_margin_pct: Free cash flow / revenue × 100
+
+            ## Search Strategy
+            1. basic_search: "cash flow operations investing financing activities FY2025"
+            2. basic_search: "capital expenditures free cash flow stock compensation"
+          output_schema:
+            type: object
+            properties:
+              units_label: { type: string }
+              net_income_cf: { type: number }
+              depreciation_and_amortization: { type: number }
+              stock_based_compensation: { type: number }
+              net_cash_from_operations: { type: number }
+              capex: { type: number }
+              acquisitions: { type: number }
+              net_cash_from_investing: { type: number }
+              share_repurchases: { type: number }
+              dividends_paid: { type: number }
+              net_cash_from_financing: { type: number }
+              net_change_in_cash: { type: number }
+              free_cash_flow: { type: number }
+              fcf_margin_pct: { type: number }
+              citations: { type: array, items: { type: string } }
+              notes: { type: string }
+      mcp_scope: []
+      prompt: "Return consolidated cash flow statement for FY2025."
+
+    # ── Key Financial Ratios ──────────────────────────────────────────────────
+    - id: key_ratios
+      label: "Key Financial Ratios & Metrics"
+      type: object
+      priority: 2
+      depends_on: [income_statement, balance_sheet, cash_flow]
+      docset_id: annual_report
+      agents:
+        - id: ratios_extract
+          docset_id: annual_report
+          prompt: |
+            Compute or extract key financial ratios from the financial statements.
+            Use the FY2025 figures from the statements in your context (from depends_on).
+
+            ## Profitability
+            - gross_margin_pct: Gross profit / Revenue × 100 (from income statement)
+            - operating_margin_pct: Operating income / Revenue × 100
+            - net_margin_pct: Net income / Revenue × 100
+            - fcf_margin_pct: Free cash flow / Revenue × 100 (from cash flow)
+            - roa_pct: Net income / Total assets × 100
+            - roe_pct: Net income / Stockholders equity × 100
+
+            ## Liquidity
+            - current_ratio: Current assets / Current liabilities
+            - quick_ratio: (Cash + Short-term investments + AR) / Current liabilities
+            - cash_and_investments: Cash + short-term investments
+
+            ## Leverage
+            - net_debt: Long-term debt + current debt - cash and investments
+            - net_debt_to_ebitda: Use reported EBITDA if available; otherwise skip
+            - interest_coverage: Operating income / Interest expense
+
+            ## Growth (YoY)
+            - revenue_growth_yoy_pct: (FY2025 revenue - FY2024 revenue) / FY2024 revenue × 100
+            - operating_income_growth_yoy_pct: YoY operating income growth %
+            - eps_growth_yoy_pct: YoY diluted EPS growth %
+
+            Compute from the financial statement data in your context.
+            Note: If a prior-year figure is not available, set growth metrics to null.
+          output_schema:
+            type: object
+            properties:
+              gross_margin_pct: { type: number }
+              operating_margin_pct: { type: number }
+              net_margin_pct: { type: number }
+              fcf_margin_pct: { type: number }
+              roa_pct: { type: number }
+              roe_pct: { type: number }
+              current_ratio: { type: number }
+              quick_ratio: { type: number }
+              cash_and_investments: { type: number }
+              net_debt: { type: number }
+              interest_coverage: { type: number }
+              revenue_growth_yoy_pct: { type: number }
+              eps_growth_yoy_pct: { type: number }
+              notes: { type: string }
+      mcp_scope: []
+      prompt: "Return key financial ratios computed from FY2025 financial statements."
+
+    # ── MD&A Highlights & Outlook ─────────────────────────────────────────────
+    - id: mda_and_outlook
+      label: "MD&A Highlights & Management Outlook"
+      type: object
+      priority: 2
+      docset_id: annual_report
+      agents:
+        - id: mda_extract
+          prompt: |
+            Extract the key highlights from Management's Discussion & Analysis (MD&A)
+            and the company's forward-looking guidance.
+
+            ## What to Find
+            - performance_narrative: Management's explanation of FY2025 performance (2-3 sentences)
+            - revenue_drivers: Key factors that drove revenue growth or decline
+            - margin_commentary: Management commentary on margin changes
+            - fy2026_revenue_guidance: FY2026 revenue guidance (full dollars or range)
+            - fy2026_eps_guidance: FY2026 diluted EPS guidance
+            - fy2026_other_guidance: Any other FY2026 metrics guided (operating margin, FCF, etc.)
+            - non_gaap_measures: Any non-GAAP measures highlighted (Adjusted EBITDA, Non-GAAP EPS, etc.)
+            - capital_allocation_commentary: Buybacks, dividends, M&A intent mentioned
+
+            ## Search Strategy
+            1. basic_search: "management discussion analysis MD&A results operations"
+            2. basic_search: "fiscal 2026 guidance outlook revenue earnings per share"
+            3. global_search: "strategic priorities company direction growth drivers"
+          output_schema:
+            type: object
+            properties:
+              performance_narrative: { type: string }
+              revenue_drivers: { type: array, items: { type: string } }
+              margin_commentary: { type: string }
+              fy2026_revenue_guidance: { type: string }
+              fy2026_eps_guidance: { type: string }
+              fy2026_other_guidance: { type: array, items: { type: string } }
+              non_gaap_measures: { type: array, items: { type: string } }
+              capital_allocation_commentary: { type: string }
+              citations: { type: array, items: { type: string } }
+      mcp_scope: []
+      prompt: "Return MD&A highlights and FY2026 guidance."
+
+    # ── Risk Factors ──────────────────────────────────────────────────────────
+    - id: risk_factors
+      label: "Key Risk Factors (Item 1A)"
+      type: object
+      priority: 2
+      docset_id: annual_report
+      agents:
+        - id: risks_extract
+          search_type: global   # risk factors are cross-cutting — global search is best
+          prompt: |
+            Extract the key risk factors from Item 1A of the 10-K.
+
+            ## What to Find
+            Identify 6-10 of the most material risks across these categories:
+            - business_risks: Competition, technology, product, operational
+            - financial_risks: Debt, liquidity, covenant, foreign exchange
+            - regulatory_risks: Compliance, government, data privacy, IP
+            - macro_risks: Economic conditions, interest rates, supply chain
+            - cyber_risks: Cybersecurity, data breaches, system failures
+
+            For each risk:
+            - category: One of the above
+            - title: Short risk title (as used in the 10-K if possible)
+            - summary: 1-sentence summary of the risk
+
+            ## Search Strategy
+            Use global_search to extract cross-cutting risk themes:
+            Query 1: "risk factors competition market technology"
+            Query 2: "regulatory compliance data privacy cybersecurity"
+            Query 3: "financial risks debt interest liquidity"
+          output_schema:
+            type: object
+            properties:
+              risks:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    category: { type: string }
+                    title: { type: string }
+                    summary: { type: string }
+                    citations: { type: array, items: { type: string } }
+              citations: { type: array, items: { type: string } }
+      mcp_scope: []
+      prompt: "Return the most material risk factors from Item 1A."
+
+  tables:
+    - id: income_statement_table
+      title: "Consolidated Income Statement (FY2025 vs FY2024)"
+      priority: 1
+      depends_on: [income_statement]
+      docset_id: annual_report
+      agents:
+        - id: income_table_build
+          docset_id: annual_report
+          prompt: |
+            Build the income statement comparison table from the data in your context.
+            For each line item, create one row:
+            - metric: Line item name
+            - fy2025: FY2025 value
+            - fy2024: FY2024 value
+            - change_pct: YoY change % (null if FY2024 not available)
+
+            Include: Revenue, Cost of Revenue, Gross Profit, Gross Margin %,
+            R&D, S&M, G&A, Operating Income, Operating Margin %, Net Income, Diluted EPS.
+            Return {"rows": [...]}
+          output_schema:
+            type: object
+            properties:
+              rows:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    metric: { type: string }
+                    fy2025: { type: number }
+                    fy2024: { type: number }
+                    change_pct: { type: number }
+      mcp_scope: []
+      prompt: "Return income statement comparison table."
+
+template:
+  format: markdown
+  sections:
+    header: |
+      # {{report.name}}
+      > **Company:** {{context.company_name}} ({{context.ticker}}) | **Fiscal Year:** {{context.fiscal_year}}
+      > **Reporting units:** USD {{context.reporting_units}}
+
+  content: |
+    {{sections.header}}
+
+    ---
+
+    ## Income Statement
+
+    {{table.income_statement_table}}
+
+    ---
+
+    ## Balance Sheet Highlights
+
+    | Metric | FY2025 | FY2024 |
+    |--------|--------|--------|
+    | Cash & Equivalents | {{ field.balance_sheet.fy2025.cash_and_equivalents | number(0) | default("—") }} | {{ field.balance_sheet.fy2024.cash_and_equivalents | number(0) | default("—") }} |
+    | Total Current Assets | {{ field.balance_sheet.fy2025.total_current_assets | number(0) | default("—") }} | — |
+    | Total Assets | {{ field.balance_sheet.fy2025.total_assets | number(0) | default("—") }} | {{ field.balance_sheet.fy2024.total_assets | number(0) | default("—") }} |
+    | Long-Term Debt | {{ field.balance_sheet.fy2025.long_term_debt | number(0) | default("—") }} | {{ field.balance_sheet.fy2024.long_term_debt | number(0) | default("—") }} |
+    | Total Stockholders' Equity | {{ field.balance_sheet.fy2025.total_stockholders_equity | number(0) | default("—") }} | {{ field.balance_sheet.fy2024.total_stockholders_equity | number(0) | default("—") }} |
+
+    ---
+
+    ## Cash Flow
+
+    | | FY2025 |
+    |-|--------|
+    | Cash from Operations | {{ field.cash_flow.net_cash_from_operations | number(0) | default("—") }} |
+    | Capital Expenditures | {{ field.cash_flow.capex | number(0) | default("—") }} |
+    | **Free Cash Flow** | **{{ field.cash_flow.free_cash_flow | number(0) | default("—") }}** |
+    | FCF Margin | {{ field.cash_flow.fcf_margin_pct | number(1) | default("—") }}% |
+    | Stock-Based Compensation | {{ field.cash_flow.stock_based_compensation | number(0) | default("—") }} |
+    | Share Repurchases | {{ field.cash_flow.share_repurchases | number(0) | default("—") }} |
+
+    ---
+
+    ## Key Financial Ratios (FY2025)
+
+    | Ratio | Value |
+    |-------|-------|
+    | Gross Margin | {{ field.key_ratios.gross_margin_pct | number(1) | default("—") }}% |
+    | Operating Margin | {{ field.key_ratios.operating_margin_pct | number(1) | default("—") }}% |
+    | Net Margin | {{ field.key_ratios.net_margin_pct | number(1) | default("—") }}% |
+    | FCF Margin | {{ field.key_ratios.fcf_margin_pct | number(1) | default("—") }}% |
+    | ROE | {{ field.key_ratios.roe_pct | number(1) | default("—") }}% |
+    | Current Ratio | {{ field.key_ratios.current_ratio | number(2) | default("—") }}x |
+    | Net Debt | {{ field.key_ratios.net_debt | number(0) | default("—") }} |
+    | Revenue Growth YoY | {{ field.key_ratios.revenue_growth_yoy_pct | number(1) | default("—") }}% |
+    | EPS Growth YoY | {{ field.key_ratios.eps_growth_yoy_pct | number(1) | default("—") }}% |
+
+    ---
+
+    ## MD&A Highlights & FY2026 Guidance
+
+    {{ field.mda_and_outlook.performance_narrative | default("—") }}
+
+    **Revenue drivers:** {{ field.mda_and_outlook.revenue_drivers | default("—") }}
+    **Margin commentary:** {{ field.mda_and_outlook.margin_commentary | default("—") }}
+
+    ### FY2026 Guidance
+    | | |
+    |-|-|
+    | Revenue | {{ field.mda_and_outlook.fy2026_revenue_guidance | default("Not provided") }} |
+    | EPS | {{ field.mda_and_outlook.fy2026_eps_guidance | default("Not provided") }} |
+    | Other | {{ field.mda_and_outlook.fy2026_other_guidance | default("—") }} |
+
+    **Capital allocation:** {{ field.mda_and_outlook.capital_allocation_commentary | default("—") }}
+
+    ---
+
+    ## Key Risk Factors
+
+    {{ field.risk_factors.risks | default("—") }}
+
+guardrails:
+  - id: gr_balance_sheet_balances
+    target: field.balance_sheet
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "Total assets must equal total liabilities plus equity"
+    prompt: |
+      Verify: total_assets ≈ total_liabilities + total_stockholders_equity (within 1%)
+      Also verify: total_current_assets < total_assets
+      Return JSON: {"pass": boolean, "issues": []}
+      Content: {{content}}
+
+  - id: gr_income_stmt_math
+    target: field.income_statement
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "Income statement lines must add up correctly"
+    prompt: |
+      Verify for FY2025: gross_profit ≈ revenue - cost_of_revenue (within 1%)
+      Verify: net_income < gross_profit (unless extraordinary items)
+      Verify: eps_diluted ≈ net_income / shares_diluted (within 5%)
+      Return JSON: {"pass": boolean, "issues": []}
+      Content: {{content}}
+
+  - id: gr_fcf_math
+    target: field.cash_flow
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "FCF must equal operating cash flow plus capex"
+    prompt: |
+      Verify: free_cash_flow ≈ net_cash_from_operations + capex (capex is negative, so this is effectively subtracted)
+      Allow 1% tolerance for rounding.
+      Return JSON: {"pass": boolean, "issues": []}
+      Content: {{content}}
+
+  - id: gr_no_fabrication
+    target: computations
+    on_fail: warn
+    model: gpt-4.1-mini
+    api_key: ${OPENAI_API_KEY}
+    description: "Detect fabricated values"
+    prompt: |
+      FAIL if citations are "Source A"/"Source B" style (real ones use c_xxxxxxxx).
+      FAIL if ALL financial statement values are round multiples of 100000.
+      Return JSON: {"pass": boolean, "issues": []}
+      Content: {{content}}
+
+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

package/dist/agents/reportGenerator/index.d.ts

@@ -0,0 +1,18 @@
+export interface ReportComposerAgentOptions {
+    /** Full instruction text (from the instructions file) */
+    instructions: string;
+    /** Anthropic API key */
+    anthropicApiKey: string;
+    /** Claude model ID, e.g. "claude-sonnet-4-6" */
+    model?: string;
+    /** Maximum agentic iterations before giving up */
+    maxIterations?: number;
+    /** Called on each status update (for spinner / logging) */
+    onProgress?: (message: string) => void;
+}
+export interface ReportComposerAgentResult {
+    reportYaml: string;
+    iterations: number;
+    reportValid: boolean;
+}
+export declare function runReportComposerAgent(options: ReportComposerAgentOptions): Promise<ReportComposerAgentResult>;