@spec anthropic_api_key(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Anthropic API key.

Calling Planck.Headless.Config.anthropic_api_key() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "ANTHROPIC_API_KEY"
• Type: :binary
• Default: nil
• Required: false
• Cached: true

@spec anthropic_api_key!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()

Anthropic API key.

Bang version of Planck.Headless.Config.anthropic_api_key/0 (fails on error). Optionally, receives the namespace for the variable.

@spec config_files(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}

Colon-separated list of JSON config files to read at boot, in order. Later files override earlier ones. Not read from the JSON files themselves — that would be circular. Defaults to the user-global file followed by the project-local file (project-local wins on collision).

Calling Planck.Headless.Config.config_files() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_CONFIG_FILES"
• Type: Planck.Headless.Config.PathList
• Default: ["~/.planck/config.json", ".planck/config.json"]
• Required: false
• Cached: true

@spec config_files!(Skogsra.Env.namespace()) ::
  Planck.Headless.Config.PathList.t() | no_return()

Colon-separated list of JSON config files to read at boot, in order. Later files override earlier ones. Not read from the JSON files themselves — that would be circular. Defaults to the user-global file followed by the project-local file (project-local wins on collision).

Bang version of Planck.Headless.Config.config_files/0 (fails on error). Optionally, receives the namespace for the variable.

@spec default_model(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Default model id within the default provider (e.g. claude-sonnet-4-6).

Calling Planck.Headless.Config.default_model() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_DEFAULT_MODEL"
• Type: :binary
• Default: nil
• Required: false
• Cached: true

@spec default_model!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()

Default model id within the default provider (e.g. claude-sonnet-4-6).

Bang version of Planck.Headless.Config.default_model/0 (fails on error). Optionally, receives the namespace for the variable.

@spec default_provider(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Default provider key — references an entry in the providers map (e.g. "anthropic").

Calling Planck.Headless.Config.default_provider() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_DEFAULT_PROVIDER"
• Type: :binary
• Default: nil
• Required: false
• Cached: true

@spec default_provider!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()

Default provider key — references an entry in the providers map (e.g. "anthropic").

Bang version of Planck.Headless.Config.default_provider/0 (fails on error). Optionally, receives the namespace for the variable.

@spec env_files(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}

Ordered list of .env files to read for API keys. Global file is read first; project-local file wins on collision. Not read from the .env files themselves — that would be circular.

Calling Planck.Headless.Config.env_files() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_ENV_FILES"
• Type: Planck.Headless.Config.PathList
• Default: ["~/.planck/.env", "./.planck/.env"]
• Required: false
• Cached: true

@spec env_files!(Skogsra.Env.namespace()) ::
  Planck.Headless.Config.PathList.t() | no_return()

Ordered list of .env files to read for API keys. Global file is read first; project-local file wins on collision. Not read from the .env files themselves — that would be circular.

Bang version of Planck.Headless.Config.env_files/0 (fails on error). Optionally, receives the namespace for the variable.

@spec get() :: t()

Return the fully-resolved config as a %Planck.Headless.Config{} struct.

@spec google_api_key(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Google API key.

Calling Planck.Headless.Config.google_api_key() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "GOOGLE_API_KEY"
• Type: :binary
• Default: nil
• Required: false
• Cached: true

@spec google_api_key!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()

Google API key.

Bang version of Planck.Headless.Config.google_api_key/0 (fails on error). Optionally, receives the namespace for the variable.

@spec locale(Skogsra.Env.namespace()) :: {:ok, nil | binary()} | {:error, binary()}

UI locale (e.g. "en", "es"). Set in .planck/config.json for a project-specific language or in ~/.planck/config.json for a global preference. When absent the browser's Accept-Language header is used, falling back to English.

Calling Planck.Headless.Config.locale() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_LOCALE"
• Type: :binary
• Default: nil
• Required: false
• Cached: true

@spec locale!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()

UI locale (e.g. "en", "es"). Set in .planck/config.json for a project-specific language or in ~/.planck/config.json for a global preference. When absent the browser's Accept-Language header is used, falling back to English.

Bang version of Planck.Headless.Config.locale/0 (fails on error). Optionally, receives the namespace for the variable.

@spec models(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.Models.t()} | {:error, binary()}

List of model declarations. Each entry references a key in providers and assigns a user alias. Only readable from .planck/config.json or application config — no env var equivalent (the format is too structured for a flat string).

Example (in .planck/config.json):

"models": [
  { "id": "sonnet",   "model": "claude-sonnet-4-6",              "provider": "anthropic" },
  { "id": "llama70b", "model": "meta/llama-3.3-70b-instruct",    "provider": "nvidia",
    "params": { "temperature": 0.6, "receive_timeout": 600000 } }
]

Calling Planck.Headless.Config.models() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_MODELS"
• Type: Planck.Headless.Config.Models
• Default: []
• Required: false
• Cached: true

@spec models!(Skogsra.Env.namespace()) ::
  Planck.Headless.Config.Models.t() | no_return()

List of model declarations. Each entry references a key in providers and assigns a user alias. Only readable from .planck/config.json or application config — no env var equivalent (the format is too structured for a flat string).

Example (in .planck/config.json):

"models": [
  { "id": "sonnet",   "model": "claude-sonnet-4-6",              "provider": "anthropic" },
  { "id": "llama70b", "model": "meta/llama-3.3-70b-instruct",    "provider": "nvidia",
    "params": { "temperature": 0.6, "receive_timeout": 600000 } }
]

Bang version of Planck.Headless.Config.models/0 (fails on error). Optionally, receives the namespace for the variable.

@spec openai_api_key(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

OpenAI API key.

Calling Planck.Headless.Config.openai_api_key() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "OPENAI_API_KEY"
• Type: :binary
• Default: nil
• Required: false
• Cached: true

@spec openai_api_key!(Skogsra.Env.namespace()) :: (nil | binary()) | no_return()

OpenAI API key.

Bang version of Planck.Headless.Config.openai_api_key/0 (fails on error). Optionally, receives the namespace for the variable.

@spec preload(Skogsra.Env.namespace()) :: :ok

Preloads all variables in a namespace if supplied.

@spec providers(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.Providers.t()} | {:error, binary()}

Map of named provider entries. Each key is a user-defined provider alias; the value describes the provider type and connection details. Only readable from .planck/config.json or application config — no env var equivalent.

Example (in .planck/config.json):

"providers": {
  "anthropic":    { "type": "anthropic" },
  "nvidia":       { "type": "openai", "base_url": "https://integrate.api.nvidia.com/v1", "identifier": "NVIDIA" },
  "local-ollama": { "type": "openai", "base_url": "http://localhost:11434", "has_api_key": false }
}

Calling Planck.Headless.Config.providers() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_PROVIDERS"
• Type: Planck.Headless.Config.Providers
• Default: %{}
• Required: false
• Cached: true

@spec providers!(Skogsra.Env.namespace()) ::
  Planck.Headless.Config.Providers.t() | no_return()

Map of named provider entries. Each key is a user-defined provider alias; the value describes the provider type and connection details. Only readable from .planck/config.json or application config — no env var equivalent.

Example (in .planck/config.json):

"providers": {
  "anthropic":    { "type": "anthropic" },
  "nvidia":       { "type": "openai", "base_url": "https://integrate.api.nvidia.com/v1", "identifier": "NVIDIA" },
  "local-ollama": { "type": "openai", "base_url": "http://localhost:11434", "has_api_key": false }
}

Bang version of Planck.Headless.Config.providers/0 (fails on error). Optionally, receives the namespace for the variable.

@spec put_anthropic_api_key(nil | binary(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.anthropic_api_key/0. Optionally, receives the namespace.

@spec put_config_files(Planck.Headless.Config.PathList.t(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.config_files/0. Optionally, receives the namespace.

@spec put_default_model(nil | binary(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.default_model/0. Optionally, receives the namespace.

@spec put_default_provider(nil | binary(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.default_provider/0. Optionally, receives the namespace.

@spec put_env_files(Planck.Headless.Config.PathList.t(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.env_files/0. Optionally, receives the namespace.

@spec put_google_api_key(nil | binary(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.google_api_key/0. Optionally, receives the namespace.

@spec put_locale(nil | binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.locale/0. Optionally, receives the namespace.

@spec put_models(Planck.Headless.Config.Models.t(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.models/0. Optionally, receives the namespace.

@spec put_openai_api_key(nil | binary(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.openai_api_key/0. Optionally, receives the namespace.

@spec put_providers(Planck.Headless.Config.Providers.t(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.providers/0. Optionally, receives the namespace.

@spec put_sessions_dir(binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.sessions_dir/0. Optionally, receives the namespace.

@spec put_sidecar(binary(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.sidecar/0. Optionally, receives the namespace.

@spec put_skills_dirs(Planck.Headless.Config.PathList.t(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.skills_dirs/0. Optionally, receives the namespace.

@spec put_teams_dirs(Planck.Headless.Config.PathList.t(), Skogsra.Env.namespace()) ::
  :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.teams_dirs/0. Optionally, receives the namespace.

@spec put_top_skills(integer(), Skogsra.Env.namespace()) :: :ok | {:error, binary()}

Puts the value to Planck.Headless.Config.top_skills/0. Optionally, receives the namespace.

@spec reload_anthropic_api_key(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.anthropic_api_key/0. Optionally, receives the namespace for the variable.

@spec reload_config_files(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.config_files/0. Optionally, receives the namespace for the variable.

@spec reload_default_model(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.default_model/0. Optionally, receives the namespace for the variable.

@spec reload_default_provider(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.default_provider/0. Optionally, receives the namespace for the variable.

@spec reload_env_files(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.env_files/0. Optionally, receives the namespace for the variable.

@spec reload_google_api_key(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.google_api_key/0. Optionally, receives the namespace for the variable.

@spec reload_locale(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.locale/0. Optionally, receives the namespace for the variable.

@spec reload_models(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.Models.t()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.models/0. Optionally, receives the namespace for the variable.

@spec reload_openai_api_key(Skogsra.Env.namespace()) ::
  {:ok, nil | binary()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.openai_api_key/0. Optionally, receives the namespace for the variable.

@spec reload_providers(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.Providers.t()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.providers/0. Optionally, receives the namespace for the variable.

@spec reload_sessions_dir(Skogsra.Env.namespace()) ::
  {:ok, binary()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.sessions_dir/0. Optionally, receives the namespace for the variable.

@spec reload_sidecar(Skogsra.Env.namespace()) :: {:ok, binary()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.sidecar/0. Optionally, receives the namespace for the variable.

@spec reload_skills_dirs(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.skills_dirs/0. Optionally, receives the namespace for the variable.

@spec reload_teams_dirs(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.teams_dirs/0. Optionally, receives the namespace for the variable.

@spec reload_top_skills(Skogsra.Env.namespace()) ::
  {:ok, integer()} | {:error, binary()}

Reloads the value for Planck.Headless.Config.top_skills/0. Optionally, receives the namespace for the variable.

@spec sessions_dir(Skogsra.Env.namespace()) :: {:ok, binary()} | {:error, binary()}

Path to the sessions directory.

Calling Planck.Headless.Config.sessions_dir() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_SESSIONS_DIR"
• Type: :binary
• Default: ".planck/sessions"
• Required: false
• Cached: true

@spec sessions_dir!(Skogsra.Env.namespace()) :: binary() | no_return()

Path to the sessions directory.

Bang version of Planck.Headless.Config.sessions_dir/0 (fails on error). Optionally, receives the namespace for the variable.

@spec sidecar(Skogsra.Env.namespace()) :: {:ok, binary()} | {:error, binary()}

Path to the sidecar Mix project directory. planck_headless starts the sidecar application from this path when it exists on disk. Set to a non-existent path to disable sidecar startup.

Calling Planck.Headless.Config.sidecar() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_SIDECAR"
• Type: :binary
• Default: ".planck/sidecar"
• Required: false
• Cached: true

@spec sidecar!(Skogsra.Env.namespace()) :: binary() | no_return()

Path to the sidecar Mix project directory. planck_headless starts the sidecar application from this path when it exists on disk. Set to a non-existent path to disable sidecar startup.

Bang version of Planck.Headless.Config.sidecar/0 (fails on error). Optionally, receives the namespace for the variable.

@spec skills_dirs(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}

Colon-separated list of skill directories.

Calling Planck.Headless.Config.skills_dirs() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_SKILLS_DIRS"
• Type: Planck.Headless.Config.PathList
• Default: [".planck/skills", "~/.planck/skills"]
• Required: false
• Cached: true

@spec skills_dirs!(Skogsra.Env.namespace()) ::
  Planck.Headless.Config.PathList.t() | no_return()

Colon-separated list of skill directories.

Bang version of Planck.Headless.Config.skills_dirs/0 (fails on error). Optionally, receives the namespace for the variable.

@spec teams_dirs(Skogsra.Env.namespace()) ::
  {:ok, Planck.Headless.Config.PathList.t()} | {:error, binary()}

Colon-separated list of team directories.

Calling Planck.Headless.Config.teams_dirs() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_TEAMS_DIRS"
• Type: Planck.Headless.Config.PathList
• Default: [".planck/teams", "~/.planck/teams"]
• Required: false
• Cached: true

@spec teams_dirs!(Skogsra.Env.namespace()) ::
  Planck.Headless.Config.PathList.t() | no_return()

Colon-separated list of team directories.

Bang version of Planck.Headless.Config.teams_dirs/0 (fails on error). Optionally, receives the namespace for the variable.

@spec template(
  Path.t(),
  keyword()
) :: :ok | {:error, File.posix()}

Creates a template for OS environment variables given a filename. Additionally, it can receive a list of options:

• type: What kind of file it will generate (:elixir, :unix, :windows).
• namespace: Namespace for the variables.

@spec top_skills(Skogsra.Env.namespace()) :: {:ok, integer()} | {:error, binary()}

Maximum number of recently-used skills shown in the agent skill index.

Calling Planck.Headless.Config.top_skills() will ensure the following:

• Binding order: [:system, :config]
• OS environment variable: "PLANCK_TOP_SKILLS"
• Type: :integer
• Default: 5
• Required: false
• Cached: true

@spec top_skills!(Skogsra.Env.namespace()) :: integer() | no_return()

Maximum number of recently-used skills shown in the agent skill index.

Bang version of Planck.Headless.Config.top_skills/0 (fails on error). Optionally, receives the namespace for the variable.

@spec validate(Skogsra.Env.namespace()) :: :ok | {:error, [binary()]}

Validates that all required variables are present. Returns :ok if they are, {:error, errors} if they are not. errors will be a list of all errors encountered while getting required variables.

It is possible to provide a namespace as argument (defaults to nil).

@spec validate!(Skogsra.Env.namespace()) :: :ok | no_return()

Validates that all required variables are present. Returns :ok if they are, raises if they're not.

It is possible to provide a namespace as argument (defaults to nil).