RFC-0009: Configuration

Version: 0.2.0 | Status: normative | Phase: test

1. Summary

[RFC-0009:C-OVERVIEW] Overview (Informative)

skillc supports optional configuration files at two levels:

• Global: ~/.skillc/config.toml — user-wide preferences
• Project: .skillc/config.toml — project-specific overrides

Configuration is minimal by design. Most behavior is convention-based with CLI overrides for per-invocation choices. Config files are reserved for true preferences that rarely change but need project-level control.

v0.1.0 Scope:

• Tokenizer preference for search indexing (ASCII vs CJK)

Future Extensions (planned):

• Lint rule enable/disable per RFC-0008

Since: v0.1.0

2. Specification

[RFC-0009:C-FILES] Configuration Files (Normative)

File Locations

skillc MUST check for configuration files in these locations:

File Format

Configuration files MUST use TOML format.

Configuration files MAY be empty or omit any section. Missing values use defaults per RFC-0009:C-RESOLUTION.

Schema

# Schema version (optional, default: 1)
version = 1

[search]
# Tokenizer for search indexing: "ascii" (default) or "cjk"
tokenizer = "ascii"

# Reserved for future use
# [lint]
# rules = { ... }

Version Handling

The version field is OPTIONAL. If omitted, version 1 is assumed.

Compatibility rules:

• Version 1 is the only supported version in v0.1.0
• If version is present and greater than the supported version, skillc MUST emit a warning and proceed using only recognized fields
• If version is present and not a positive integer, skillc MUST emit an error and ignore the entire config file (proceed as if it does not exist)

Unknown Keys

Unknown keys and sections MUST be ignored with a warning. This enables forward compatibility when older skillc versions read configs written for newer versions.

Since: v0.1.0

[RFC-0009:C-RESOLUTION] Resolution Order (Normative)

When resolving a configuration value, skillc MUST apply this precedence order (highest first):

1. CLI flags — explicit per-invocation override
2. Environment variables — process-level override (see below)
3. Project config — .skillc/config.toml in current directory or ancestors
4. Global config — ~/.skillc/config.toml
5. Built-in defaults — hardcoded fallback values

Project Config Discovery

skillc MUST search for .skillc/config.toml starting from the current working directory and walking up to filesystem root. The first config file found is used.

If no project config is found, only global config and defaults apply.

Merging Behavior

Resolution is per-key, not per-file. For each setting:

• If project config specifies a value, use it
• Otherwise, if global config specifies a value, use it
• Otherwise, use the built-in default

Settings not specified in a config file do not override lower-precedence values.

Environment Variables (v0.1.0)

Only the following environment variables are defined in v0.1.0:

If an environment variable is set to an invalid value, skillc MUST emit a warning and ignore the variable (fall through to next precedence level).

Additional environment variables MAY be added in future versions.

Since: v0.1.0

[RFC-0009:C-TOKENIZER] Tokenizer Setting (Normative)

The [search].tokenizer setting controls how text is tokenized for the search index per RFC-0004:C-INDEX.

Values

Default

If not specified, the tokenizer MUST default to ascii.

Effect on Index

Changing the tokenizer setting invalidates existing search indexes. The search command MUST detect tokenizer mismatch and prompt for rebuild per RFC-0004:C-INDEX.

Since: v0.1.0

[RFC-0009:C-ENV-OVERRIDE] Environment Variable Override (Normative)

The SKILLC_HOME environment variable, if set, MUST override the default home directory detection for all global paths.

When SKILLC_HOME is set to a path (e.g., /custom/home):

• global_skillc_dir() MUST return $SKILLC_HOME/.skillc/ (e.g., /custom/home/.skillc/)
• All derived paths (global source store, global runtime, etc.) MUST use this base
• find_project_root() MUST exclude $SKILLC_HOME from project root detection

When SKILLC_HOME is not set:

• The implementation MUST fall back to dirs::home_dir() behavior

Rationale: This enables:

1. Cross-platform test isolation (HOME env var only works on Unix)
2. Custom installation locations
3. Portable/relocatable installations

Since: v0.2.0

Changelog

v0.2.0 (2026-01-31)

Add SKILLC_HOME override

v0.1.0 (2026-01-30)

Initial release