fileOnlyConfigKeys top-level constant

Map<String, String> const fileOnlyConfigKeys

Top-level yaml keys that are intentionally NOT interactive settings on ANY surface — structural or infrastructure config, edited in the file by design. Every entry carries its WHY (issue #288 AC1: a documented structural-only key, reviewed).

Implementation

const fileOnlyConfigKeys = <String, String>{
  // A2A gateway endpoints + credentials are deployment wiring (env-token
  // references included) — infrastructure, not a user preference.
  'a2a':
      'A2A gateways are deployment infrastructure (endpoints and '
      'credentials with env-token references); no surface edits them '
      'interactively.',

  // Trajectory capture tuning (opt-in raw wire dumps, issue #385): a
  // deliberate, size/pII-sensitive escape hatch — file-only by design so
  // it cannot be flipped casually mid-session.
  'trajectory':
      'Trajectory wire-dump capture is an opt-in, size/pII-sensitive '
      'debugging escape hatch (issue #385); provisioned deliberately in '
      'the file per environment.',

  // Background-subagent heartbeat cadence and stall threshold (issue
  // #383): operational knobs for long-running sessions, tuned in the
  // file; 0/0 disables the heartbeat entirely.
  'subagents':
      'Heartbeat cadence and stall threshold for background-subagent '
      'status digests (issue #383) — operational knobs, tuned in the '
      'file.',

  // Background-job registry knobs (issue #478): the stale-entry age
  // belt (`staleHours`) and the boot log GC (`logRetentionDays`) —
  // operational knobs, tuned in the file; 0 disables either.
  'jobs':
      'Job-registry reconcile knobs (issue #478) — staleHours age belt '
      '+ logRetentionDays boot GC; operational, tuned in the file.',

  // Visible-waiting heartbeat cadence + `--wait-for-jobs` ceiling
  // (issue #450): operational knobs for long waits, tuned in the file;
  // 0 disables the heartbeat entirely.
  'waiting':
      'Waiting-heartbeat cadence and the headless --wait-for-jobs '
      'ceiling (issue #450) — operational knobs, tuned in the file.',
  // The fabric section carries the HOST's discovery announcements (issue
  // #27 phase 2) — written by hosts, read by the runtime, never user-edited.
  'fabric':
      'Host discovery announcements are written BY hosts (issue #27), not '
      'by users; read-only config.',

  // Roles-group member: per-path role pinning, parsed together with
  // roles:. Superseded for interactive use by the roles: chains the
  // agent-models flow edits; per-path pinning stays file-tuned.
  'modelOverrides':
      'Roles-group member (per-path role pinning), superseded for '
      'interactive use by the roles: chains the agent-models flow edits; '
      'per-path pinning stays file-tuned.',

  // Product/store links (issue #691): routing data read by every
  // surface (app Get banner, CLI, fa1.dev generator) — no interactive
  // editor by design; the file is the single source of truth.
  'links':
      'Product/store links (issue #691) are routing data every surface '
      'READS (app Get banner, CLI, fa1.dev generator); the config file '
      'is the single source of truth and no surface edits it '
      'interactively.',
};