Change configuration loading

[mickume]

Currently, the configuration file is by default located at .agent-fox/config.toml.

I want to add a central, shared configuration file at location $HOME/.agent-fox/config.toml. This configuration is used as a default configuration and can be shared with multiple repos.

Desired behaviour

• On start-up, af looks for a configuration file at $HOME/.agent-fox/config.toml. It provides the base-line configuration.
• On start-up af also looks for a configuration file in the current repo at .agent-fox/config.toml. If it exists, both configuration files are merged, i.e. values from the local config file overwrite values from the global config file.
• If none exist, af creates a default config file $HOME/.agent-fox/config.toml and uses it

Change to af init

• "init" creates a default config file $HOME/.agent-fox/config.toml, if it does not exists. An existing one is not modified
• "init" creates a local config file .agent-fox/config.toml, with all possible config values commented out. An existing file is not changed.

[mickume]

Finalized PRD

This PRD was generated from this issue using the afspec skill.
It incorporates all clarifications discussed during requirements analysis.

Global Configuration Loading

Overview

Add a central, shared configuration file at $HOME/.agent-fox/config.toml that
provides baseline configuration shared across multiple repositories. Local
per-repo config at .agent-fox/config.toml overrides global values using
shallow section replacement semantics.

User Stories

US-1: Global baseline configuration. As a user working across multiple
repos, I want a single global config so I don't repeat orchestrator, theme, and
routing settings in every project.

US-2: Local overrides. As a user, I want a per-repo config that overrides
specific sections of the global config so each project can customize behavior
without affecting others.

US-3: Zero-config bootstrap. As a new user running af for the first time,
I want a sensible default global config created automatically so I don't need to
set anything up manually.

US-4: Project scaffolding. As a user running af init, I want a local
config template with all values commented out so I can see what's customizable
and selectively override global settings.

Desired Behaviour

Config Loading (all CLIs)

1. On start-up, af, nightshift, and spec all call the same config loading
   function.
2. The loader looks for a global config at $HOME/.agent-fox/config.toml. If it
   exists, it is parsed and provides the baseline configuration.
3. The loader then looks for a local config at .agent-fox/config.toml (relative
   to the current working directory). If it exists, it is parsed and merged with
   the global config.
4. Merge semantics are shallow section replacement: if the local config
   defines a TOML section (e.g. [orchestrator]), that entire section replaces
   the corresponding section from the global config. Sections not present in the
   local config are inherited from the global config unchanged. Top-level scalar
   keys (if any) follow the same rule: local overrides global.
5. If neither file exists, a default global config is created at
   $HOME/.agent-fox/config.toml (creating the $HOME/.agent-fox/ directory if
   needed) and used.
6. After merging, the result is validated and defaults applied as today.
7. Security: both global and local config files reject symlinks (existing
   CWE-59 protection applies to both paths).

AF_CONFIG Environment Variable

• Support for the AF_CONFIG environment variable is removed. The
  nightshift CLI currently uses AF_CONFIG to override the config path; this
  override is dropped in favour of the global+local loading scheme.

agentspec Settings Consolidation

• The ~/.af/settings.yaml file used by the agentspec package is consolidated
  into $HOME/.agent-fox/config.toml.
• A new [spec_tool] section is added to AgentFoxConfig with the following
  fields:
  • model (str, default "claude-sonnet-4-6") — the Anthropic model used for
    spec generation.
  • auth_method (str, default "") — authentication method (e.g. "vertex").
    Empty string means default Anthropic API key auth.
  • vertex_project (str, default "") — Google Cloud project for Vertex AI.
  • vertex_region (str, default "") — Google Cloud region for Vertex AI.
• The agentspec package's load_config() is updated to accept an
  AgentFoxConfig (or its spec_tool sub-config) instead of reading
  ~/.af/settings.yaml directly.
• The AF_SPEC_MODEL environment variable override is preserved as a
  backward-compatible escape hatch.
• The ~/.af/settings.yaml file is still read as a migration fallback: if
  $HOME/.agent-fox/config.toml has no [spec_tool] section and
  ~/.af/settings.yaml exists, its values are used. This avoids breaking
  existing setups immediately.

Changes to af init

1. af init creates a default global config at $HOME/.agent-fox/config.toml
   if it does not exist. An existing global config is not modified.
2. af init creates a local config at .agent-fox/config.toml with all
   possible config values commented out. An existing local config is not
   modified — it is truly left alone (no schema merge, no template update).
3. The $HOME/.agent-fox/ directory is auto-created if it doesn't exist.

Non-Goals

• Deep-merge of nested keys within a section. Sections are replaced wholesale.
• GUI or interactive config editor.
• Config file watching / hot-reload of global config.

Tech Stack

• Python 3.12+
• TOML parsing via tomllib (stdlib) for reading, tomlkit for generation
• Pydantic v2 for validation
• Click for CLI

Glossary

Term	Definition
Global config	$HOME/.agent-fox/config.toml — user-wide baseline
Local config	.agent-fox/config.toml — per-repo overrides
Shallow section replacement	Local TOML sections entirely replace the corresponding global section

Design Decisions

1. Shallow section replacement over deep merge: Shallow replacement is
   simpler to reason about and implement. Users who override [orchestrator]
   in a local config must specify all desired values for that section, not just
   the ones that differ. This avoids surprising merge artifacts in nested tables.

2. Auto-create global config on every command: Every af, nightshift, and
   spec invocation auto-creates the global config if missing. This ensures
   zero-config bootstrap without requiring af init first.

3. All three CLIs share the same loading: af, nightshift, and spec all
   use the same load_config() function with the same global+local merge logic.
   This ensures consistent behaviour across all entry points.

4. Drop AF_CONFIG: The global+local scheme replaces the need for
   AF_CONFIG. Removing it simplifies the config resolution logic and avoids
   ambiguity about which path it overrides.

5. Truly leave existing local config alone during af init: Unlike the
   current behaviour which merges schema changes into existing configs, af init
   now skips the local config entirely if it exists. Users can re-generate it
   manually with af init --force.

6. Consolidate ~/.af/settings.yaml: Moving agentspec settings into the
   main config TOML gives users a single config surface. The migration fallback
   ensures existing setups continue working.

7. Auto-create $HOME/.agent-fox/ directory: When auto-creating the global
   config, the directory is created with owner-only permissions (0o700) matching
   the existing security model.

Source

Source: #633

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 4f5d384978670f3064f8154ab7a41e0fccf9543a

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 4f5d384978670f3064f8154ab7a41e0fccf9543a

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 3f61f91deb31c86ed9170b9e2d73186c3c499b17

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 3f61f91deb31c86ed9170b9e2d73186c3c499b17

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 9ebad7a2fa70df169f154364df0781371502db53

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 9ebad7a2fa70df169f154364df0781371502db53

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 8106812f2bd530058a51e70edac185fd6d39063f

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 8106812f2bd530058a51e70edac185fd6d39063f

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 8106812f2bd530058a51e70edac185fd6d39063f

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 8106812f2bd530058a51e70edac185fd6d39063f

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: d829b51edba13af96c2f6d0a9036351033fa1fa8

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.

[mickume]

Spec Implemented

Spec 13_global_config_loading has been fully implemented and merged to main.

Commit: 8b69948e7ff2dfc2cb307fe0893c29186730bacb

Task Groups

• Write spec tests for global config loading
• Implement AgentFoxConfig spec_tool sub-config and shallow merge logic
• Implement core load_config function with global+local loading, symlink rejection, and debug logging
• Implement agentspec settings consolidation and model resolution precedence
• Implement af init scaffolding with global and local config creation
• Regression and property test gate
• End-to-end wiring verification and smoke tests

---

Auto-generated by agent-fox.