export const summary = 'yg-config.yaml fields: version, reviewer tiers, quality thresholds, parallelism';

export const content = `# Configuration (yg-config.yaml)

\`yg-config.yaml\` lives in \`.yggdrasil/\` and controls the reviewer and
runtime behavior. It is generated by \`yg init\`. \`yg init --upgrade\` refreshes
rules, schemas, platform files, and \`.gitattributes\`, and lifts the config's
version bookkeeping to the current schema.

## yg-config.yaml reference

Full annotated example:

\`\`\`yaml
version: "5.0.0"                   # Managed by the CLI — never set or edit by hand; not your concern.

reviewer:
  default: standard               # Tier name used when an aspect doesn't declare one.
                                  # REQUIRED when more than one tier is configured.
                                  # OPTIONAL with exactly one tier.
  tiers:
    standard:                     # Tier name — referenced by aspect reviewer.tier
      provider: ollama            # LLM provider (ollama, anthropic, openai, claude-code, ...)
      consensus: 1                # Votes per aspect (1 = single call; odd >= 3 = majority vote)
      max_prompt_chars: 50000     # Optional — cap on the assembled LLM prompt; absent = unlimited.
                                  # yg init writes 50000 so out-of-box adopters keep a guard.
      config:
        model: qwen3              # Model identifier for this provider
        temperature: 0            # Sampling temperature (0 = deterministic)
        endpoint: http://localhost:11434   # Required for openai-compatible (no default host); ollama defaults to localhost:11434

coverage:                           # Optional — controls which files must be mapped
  required:                         # Unmapped files under these roots are a blocking error
    - "/"                           # Default: whole repo
  excluded: []                      # Files under these roots are silently ignored

quality:
  max_direct_relations: 10        # Max out-edges per node before high-fan-out warning

parallel: 1                       # Concurrent pair verifications (default: 1)

debug: false                      # When true, appends all command output to .yggdrasil/.debug.log (default: false)
\`\`\`

## Reviewer tiers

A reviewer tier is a named LLM configuration. Aspects declare which tier
they want via \`reviewer.tier: <name>\`. The same tier set is used across
the entire repository, shared by every aspect.

Two motivating shapes:

- Single-tier projects (cheapest setup): one tier; no \`reviewer.default\` needed.
- Multi-tier projects: a \`standard\` tier for routine checks, a premium
  \`deep\` tier for critical aspects. \`reviewer.default\` selects \`standard\`;
  critical aspects opt into the premium with \`reviewer.tier: deep\`.

### reviewer.default

The tier name aspects fall back to when they do not declare \`reviewer.tier:\`.

- REQUIRED when \`reviewer.tiers\` has more than one entry.
- OPTIONAL when \`reviewer.tiers\` has exactly one entry (the single tier is
  implicitly the default).
- Must reference a key in \`reviewer.tiers\`.

If you forget \`reviewer.default\` with more than one tier, \`yg check\`
emits \`config-default-tier-missing\`.

### reviewer.tiers.<name>

Tier name regex: \`^[a-zA-Z][a-zA-Z0-9_-]{0,62}$\`.
The literal name \`default\` is reserved (it would clash with
\`reviewer.default\` visually). Convention: \`standard\` for the primary
tier, \`deep\` for an opt-in higher-capability tier.

### reviewer.tiers.<name>.provider

One of: \`ollama\`, \`anthropic\`, \`openai\`, \`google\`, \`openai-compatible\`,
\`claude-code\`, \`codex\`, \`gemini-cli\`.

CLI providers (\`claude-code\`, \`codex\`, \`gemini-cli\`) do not require an API key —
they delegate to the installed CLI tool.

### reviewer.tiers.<name>.consensus

Number of independent reviewer calls per aspect — declared per tier. Must
be a positive odd integer.

- \`1\` — single call, cheapest.
- \`3\` — majority vote (2 of 3 must agree), more reliable.

Consensus multiplies wall-clock per pair (calls run sequentially inside
the slot held by the global \`parallel\` limit). The trade-off is per tier,
not global.

### reviewer.tiers.<name>.max_prompt_chars

Optional cap on the assembled LLM prompt for any pair resolving to this tier —
scaffold + content.md + references + the unit's subject files + node descriptor.
Absent = unlimited. \`yg init\` writes \`50000\` into the generated config so
out-of-box adopters keep a guard.

A pair whose prompt exceeds the limit is a blocking \`prompt-too-large\` error
(checked deterministically at \`yg check\`; the pair is skipped by \`--approve\`).
\`max_prompt_chars\` is a GATE, not a judgment input — it is NOT folded into a
verdict's hash. Lowering it can trip the gate on an already-verified pair without
invalidating that verdict. Switching an aspect to a tier with a smaller limit can
turn \`yg check\` red. Remedies are documented in
\`yg knowledge read writing-llm-aspects\`.

### reviewer.tiers.<name>.config

Provider-specific options passed to the LLM client:

| Field | Type | Notes |
|---|---|---|
| \`model\` | string | Required. Provider-specific model identifier. |
| \`temperature\` | number | Defaults to 0. Higher = more varied responses. |
| \`endpoint\` | string | Required for \`openai-compatible\` (no default host — else falls back to api.openai.com); \`ollama\` defaults to http://localhost:11434. |
| \`timeout\` | number | Timeout in seconds. Default 300. Applies to CLI providers only — non-CLI/API providers ignore it. Not folded into a verdict's hash (a transport knob). |

API keys do NOT live here — they belong in \`yg-secrets.yaml\` (api_key only).
API providers also read the provider API key from environment variables (e.g.
the provider's standard \`*_API_KEY\`) as a fallback when not present in
\`yg-secrets.yaml\`.

## Multi-tier example

\`\`\`yaml
reviewer:
  default: standard
  tiers:
    standard:
      provider: ollama
      consensus: 1
      config:
        model: qwen3
        endpoint: http://localhost:11434
    deep:
      provider: anthropic
      consensus: 3
      config:
        model: claude-opus-4-7
        temperature: 0
\`\`\`

Aspect using the deep tier:

\`\`\`yaml
reviewer:
  type: llm
  tier: deep
\`\`\`

Aspect using the default tier — no \`tier:\` needed:

\`\`\`yaml
reviewer:
  type: llm
\`\`\`

## Secrets (yg-secrets.yaml)

API keys go in \`yg-secrets.yaml\`, NOT in \`yg-config.yaml\`.
\`yg-secrets.yaml\` is gitignored by default.

\`\`\`yaml
# .yggdrasil/yg-secrets.yaml  — gitignored, never commit
reviewer:
  anthropic:
    api_key: sk-ant-...
\`\`\`

The secrets file accepts only \`api_key\` per provider. Any other field
triggers \`secrets-non-credential-field\` from \`yg check\` — non-credential
overrides belong in the tier's \`config:\` block instead.

API providers also read the provider API key from environment variables (e.g.
the provider's standard \`*_API_KEY\`) as a fallback when not present in
\`yg-secrets.yaml\`. If the env var is set, \`yg-secrets.yaml\` is not required.

\`yg-config.yaml\` itself must never contain credentials. Commit it to the
repository — it is safe to share.

## Coverage config

\`\`\`yaml
coverage:
  required:
    - src/                  # unmapped files under src/ are a blocking error
  excluded:
    - vendor/               # silently ignored
    - "**/*.generated.ts"   # glob: drop generated files anywhere
\`\`\`

Controls which git-tracked files must be mapped to a node.

- \`required\` — roots where unmapped files are a blocking \`unmapped-files\` error. Default: \`["/"]\` (whole repo — the previous always-map-everything behavior). An explicit empty list \`[]\` means require nothing: every uncovered file (outside \`excluded\`/nested) becomes a non-blocking \`uncovered-advisory\` warning and nothing blocks (pure-advisory adoption). Empty only counts when written explicitly; omitting the \`coverage\` block keeps the \`["/"]\` default.
- \`excluded\` — roots that are silently ignored. Default: \`[]\`.
- Roots accept the same forms as a node \`mapping:\` entry: an exact file, a directory prefix (e.g. \`src/\` covers everything beneath it), or a glob (\`*\` within a segment, \`**\` across) — so \`excluded: ["**/*.generated.ts"]\` drops generated files anywhere and \`required: ["services/*/api/**"]\` scopes the blocking tier to a pattern. \`/\` still means the whole repo.
- Files that match neither a required nor an excluded root produce a non-blocking \`uncovered-advisory\` warning.
- Subtrees containing their own nested \`.yggdrasil/\` are auto-skipped by all repo-walking checks (they are governed by their own graph).
- Longest-match wins (by normalized root/pattern length); on a tie between required and excluded, excluded wins.

## Quality thresholds

\`\`\`yaml
quality:
  max_direct_relations: 10          # high-fan-out warning threshold
\`\`\`

\`max_direct_relations\` fires a warning when a node exceeds it (out-edges).
Node size is bounded by the LLM prompt-size gate (\`max_prompt_chars\` per tier),
not by a per-node character budget — there is no node-level size limit and no
per-node size exemption.

## Parallel vs consensus

\`parallel\` (top-level) controls how many pair verifications run concurrently
during \`yg check --approve\`. It defaults to \`1\`; raise it (for example to 10) to
verify pairs in parallel. Each verification runs its tier's \`consensus\` calls
sequentially in a single slot, and lock writes are serialized in-process.
Cross-tier traffic shares one queue: an expensive tier saturating the queue
starves a cheap tier. Tune \`parallel\` conservatively when mixing tier costs.

## Debug logging

\`debug\` (top-level) defaults to \`false\`. When set to \`true\`, every command
appends its output to \`.yggdrasil/.debug.log\`. The log is append-only — rotate
or delete it manually.

## Upgrading

\`\`\`bash
yg init --upgrade
\`\`\`

Refreshes rules, schemas, platform files, and \`.gitattributes\`, and lifts the
config's version bookkeeping to the current schema. The config parser is strict:
a config carrying an unknown field (e.g. \`quality.max_node_chars\` or a tier
\`references:\` cap block) gets a clear unknown-key error from \`yg check\` — delete
those lines. Run from the repository root only. Review the diff before committing.

### Prompt size, not reference caps

There is no node-level size budget and no per-tier reference byte cap. The
assembled LLM prompt is bounded by \`max_prompt_chars\` (above), which covers the
same payload — content.md, references, and the unit's subject files — where it
actually matters. A pair whose prompt exceeds the tier limit is reported as
\`prompt-too-large\` at \`yg check\` time, before any reviewer call.
`;
