Configuration Reference¶

This page is the map for repository configuration files. Use it when a runbook mentions a config path and you need to know whether that file is source, generated output, workflow template, or public-repository data.

All paths below are repository-relative references.

Source Configs¶

File	Owner	Purpose	Main Commands
`config/dsw-compat.yml`	Tool repo	Declares the proven DSW server, document worker, and `dsw-tdk` runtime for each supported template metamodel range. Its schema is strict: duplicate keys, unknown fields, and unsupported `schema_version` values fail validation. This is the source of truth for runtime matrix generation.	`make sync-dsw-runtime-matrix`, `make check-dsw-runtime-matrix`, `make discover-upstream-compat`
`config/regression.ci.yml`	Tool repo	Base complete-fixture regression template. Upstream config generation writes an equality comparison; translated-package config generation writes a single-package render assertion.	`make generate-regression-config`, `make render-regression-ci-plan`, `make render-translated-package-regression`
`config/regression-evidence.yml`	Tool repo	Pins immutable Knowledge Model provenance and assigns one fixture to every DSW runtime. Config generation verifies its checksum and package metadata before DSW starts; the final evidence gate combines it with regression, coverage, and PDF results.	`make generate-regression-config`, `make render-regression-ci-plan`, `make verify-runtime-evidence`
`config/regression.preview.yml`	Tool repo	Local preview regression config for a manually controlled DSW instance. It expects API token auth.	`make render-regression CONFIG=config/regression.preview.yml`
`config/regression.document.yml`	Tool repo	Released-template document regression config. Use it when both baseline and candidate are already installed in DSW and referenced by released template id.	`make render-regression CONFIG=config/regression.document.yml`
`pyproject.toml`	Tool repo	Python package metadata, dependencies, development extras, and installed `dsw-template-*` console scripts.	`make install-dev`
`config/ruff.toml`	Tool repo	Formatting and linting rules for Python source, scripts, tests, and Sphinx config.	`make format`, `make format-check`, `make lint`

The three regression configs use the strict loader in yaml_config.py. Duplicate or unknown fields fail before a DSW request runs, so a misspelled option cannot silently fall back to its default.

regression.assertion is either equal or render_success. Equality requires baseline and candidate subjects. Render success rejects a baseline and is used with a local_package candidate so translated-package CI validates the actual ZIP without a meaningless cross-language or self-comparison.

generated_fixtures in config/regression.ci.yml uses these coverage controls:

Field	Meaning
`count`	Maximum number of selected cases that may become DSW projects and render comparisons.
`selection_pool_size`	Number of deterministic candidates evaluated locally before selecting cases. It must be at least `count`.
`require_complete_coverage`	Fail when the selected cases do not cover every reachable answer and supported collection shape. CI keeps this enabled for every planned version.

Increase selection_pool_size before increasing count: searching more local candidates is much cheaper than rendering more DSW projects.

config/regression-evidence.yml deliberately separates document-template and Knowledge Model metamodels. Each runtime_knowledge_models key must match a metamodel_key in config/dsw-compat.yml. A Knowledge Model entry records:

repository-relative bundle path
exact DSW package ID and version
Knowledge Model metamodelVersion
authoritative source URL
lowercase SHA-256 checksum

Adding a runtime without an assignment, replacing a bundle without updating its checksum, or declaring metadata that differs from the bundle fails before any render work begins.

The compatibility probe may update only the assignment lines between the BEGIN/END GENERATED RUNTIME KNOWLEDGE MODEL ASSIGNMENTS comments. For a new metamodel it copies the closest previous runtime’s pinned fixture as a testable assumption. The knowledge_models catalog, provenance, and checksums remain maintainer-owned and are never invented by automation.

Workflow and Stack Configs¶

File	Owner	Purpose	Main Commands
`.github/workflows/headless_render_regression.yml`	Tool repo	Main CI workflow for checks, upstream discovery, clean scaffold artifacts, release assets, and DSW render regression. Its runtime matrix is generated from `config/dsw-compat.yml`.	`make check`, `make sync-dsw-runtime-matrix`
`.github/workflows/pages.yml`	Tool repo	GitHub Pages deployment for this documentation site.	`make docs`
`.github/dsw/docker-compose.yml`	Tool repo	Ephemeral DSW stack used by local and CI render tests.	`make start-ci-dsw`, `make stop-ci-dsw`, `make ci-dsw-logs`
`examples/github-actions/document_template_translation_sync.yml`	Tool repo example	Template workflow copied into public repository `sync/v*` branches. The sync script renders version-specific values from `translation-config.yml`.	`make sync-translation-version-branches`
`examples/translation-repository/`	Tool repo example	Copy-ready README and docs templates for the public translated-template repository. Active public-repository copies are repository-owned.	Manual copy after `make docs`

Generated Configs¶

Path	Created By	Purpose	Commit?
`config/.generated-regression.ci.yml`	`make generate-regression-config` or `make render-regression-ci`	Active single-version CI regression config.	No
`config/.generated-regression.ci.<metamodel>.<version>.yml`	`make render-regression-ci-plan`	Per-version regression config generated from the compatibility ledger plan.	No
`config/.generated-regression.translated.yml`	`make render-translated-package-regression`	Single-package full render config using the pinned KM for the package metamodel.	No
`outputs/runtime-evidence/<metamodel>/evidence.json` and `evidence.md`	`make verify-runtime-evidence`	Runtime, KM provenance, complete branch coverage, regression result, and strict PDF proof for every planned version.	No

Generated configs are ignored by git. If a generated config looks wrong, fix the source config or generator instead of committing the generated file.

Public Repository Translation Config¶

The public translated-template repository owns translation-config.yml; this tool only validates and consumes it. The schema is implemented by dsw_document_template_tool.translation_repository and validated with:

make validate-translation-config TRANSLATION_REPO=/path/to/science-europe-template-zh_Hant

The current schema is schema_version: 2. Validation rejects duplicate and unknown fields so ambiguous values, misspellings, and retired settings cannot remain as inert configuration.

Important fields:

Field	Meaning
`template.supported_versions`	Upstream versions known to the public repository. A version can be known without being actively translated.
`translation.translated_template_*`	Public DSW metadata written to `template.json`, including organization id, template id, name, and optional description.
`version_policy`	Per-version lifecycle policy: whether automation may refresh, migrate into, or publish release assets.
`branches.control_branch`	Operations branch that owns repository-level config and docs.
`branches.version_branch_prefix`	Prefix for translator-facing branches, usually `sync/`.
`tooling.repository` / `tooling.ref`	Tool repository and revision used by public-repository workflows. Keep both as one-line YAML scalars: operations needs them before it can check out the tool and run full config validation.
`public_readme.path`	Canonical user-facing template README copied into generated version branches.
`xliff_exchange`	Optional XLIFF export/import settings. The default workflow still treats `translation.md` as canonical.

Common Version Policy Snippets¶

Use these snippets under version_policy.overrides when a version needs an explicit lifecycle. The default policy should usually stay scaffold-only, so new upstream tags do not silently become translation work.

Scaffold exists, but translation has not started:

version_policy:
  overrides:
    vX.Y.Z:
      state: available
      refresh: false
      migrate_into: false
      publish_release: false
      reason: scaffold available; translation not started

Actively translated and allowed to update automatically:

version_policy:
  overrides:
    vX.Y.Z:
      state: active
      refresh: artifact
      migrate_into: auto
      publish_release: true
      reason: actively translated

Maintenance branch that can be refreshed only by an operator:

version_policy:
  overrides:
    vX.Y.Z:
      state: maintenance
      refresh: manual
      migrate_into: manual
      publish_release: true
      reason: maintenance changes require operator action

Published and frozen:

version_policy:
  overrides:
    vX.Y.Z:
      state: published
      refresh: false
      migrate_into: false
      publish_release: true
      reason: published; do not rebuild from newer scaffold artifacts

Archived and fully frozen:

version_policy:
  overrides:
    vX.Y.Z:
      state: archived
      refresh: false
      migrate_into: false
      publish_release: false
      reason: archived; keep historical branch and release assets unchanged

refresh controls whether sync/v* branches are created or refreshed. migrate_into controls cross-version synchronization membership. auto versions may act as source and target during normal fan-out, manual versions participate only when explicitly selected by an operator, and false versions do not participate. For an allowed target, blank units are filled and existing translations are updated only when the source structure is identical. publish_release controls translated release asset generation. state and reason are maintainer-facing labels that make CI summaries and reviews easier to understand.

state must be one of available, active, maintenance, published, or archived. Validation rejects spelling variants rather than treating them as a new state with undefined lifecycle behavior.

Policy precedence is defaults, then matching rules in file order, then the exact version override. Rules and overrides change only fields they explicitly declare; omitted fields keep the value inherited from the previous layer. Use the domain values artifact and auto when enabling automation. The ambiguous shortcuts refresh: true and migrate_into: true are rejected.

Use refresh: artifact only for versions that should be rebuilt from the latest tooling clean scaffold artifact. Published and archived versions must use both refresh: false and migrate_into: false; the loader rejects frozen versions that could still mutate from artifact refreshes or cross-version sync.

Use Public Template Repository Integration for the operational sequence and Translation Workflow for translator-facing behavior.