Reference sources

• LocalAI: https://github.com/mudler/LocalAI
• LocalAI docs: https://localai.io/
• Sparrow: https://github.com/katanaml/sparrow

Why this matters

LocalAI exposes runtime settings, API discovery, feature metadata, and instruction surfaces so tools and UI can discover what the running instance supports. Sparrow exposes versioned API paths and OpenAPI docs for its local service. Melix should expose similar machine-readable local state for CLI, macOS UI, and automation without requiring brittle parsing of help text.

Some Melix issues already track acceleration capability receipts (#350, #352). This issue is broader: settings precedence and a stable discovery contract for CLI/macOS/tooling.

Evidence from references

LocalAI:

• docs/content/features/runtime-settings.md documents runtime settings.
• core/config/runtime_settings.go defines runtime settings.
• core/config/runtime_settings_persist.go persists them.
• core/http/endpoints/localai/settings.go exposes settings endpoints.
• docs/content/features/api-discovery.md documents /.well-known/localai.json, /api/instructions, and config metadata.
• core/http/endpoints/localai/api_instructions.go implements instruction areas.
• core/http/routes/localai.go registers discovery, features, settings, system, metrics, and monitor routes.

Sparrow:

• sparrow-ml/llm/api.py exposes versioned paths like /api/v1/sparrow-llm/inference and docs at /api/v1/sparrow-llm/docs.

Proposal

Add Melix runtime settings and discovery surfaces:

Settings:

• ~/.melix/runtime_settings.json
• project override: .melix/runtime_settings.json
• melix settings show --json
• melix settings set <key> <value>
• melix settings validate
• melix settings reset <key>

Discovery:

• melix info --json
• melix capabilities --json
• melix instructions --json
• melix schema --json
• melix config metadata --json

If/when a daemon is running:

• /.well-known/melix.json
• /api/instructions
• /api/capabilities
• /api/config-metadata

Candidate settings:

• model cache path
• dataset cache path
• artifact path
• max concurrent jobs
• memory pressure threshold
• default dtype/quantization
• benchmark warmup/repeat defaults
• eval sample defaults
• log retention days
• auto-cleanup policy

Acceptance criteria

• Settings precedence is documented and tested: CLI flag > env var > project settings > user settings > default.
• melix settings show --json prints effective config and source for each value.
• Discovery output includes version, enabled features, supported tasks, schema paths/URLs, and local paths.
• macOS UI or scripts can consume discovery output without parsing human help text.

Out of scope

• Duplicating the narrower acceleration receipts tracked in Track serving acceleration profiles, capability receipts, and diagnostics bundles #350/Track acceleration capability receipts and typed unsupported reasons #352.
• Full OpenAI-compatible API parity.