<!--
SPDX-FileCopyrightText: Amolith <amolith@secluded.site>

SPDX-License-Identifier: CC0-1.0
-->

# Configuration Guide

This document describes the configuration system for the Lunatask MCP server. The server uses TOML for configuration files rather than JSON, following the project philosophy that configuration should be human-readable and editable. Configuration is validated on startup to ensure all required fields are present and correctly formatted.

## First-Run Behavior

On first run, the server generates `config.toml` with placeholder values and exits. Users must:

1. Add their Lunatask API access token
2. Configure areas with real IDs from Lunatask (areas can have nested goals)
3. Configure habits with real IDs
4. Set timezone in IANA format (e.g., `America/New_York`, not `EST`)
5. Optionally customize server host/port (defaults to `localhost:8080`)

## Configuration Structure

The config uses TOML (not JSON) per project philosophy. Example structure:

```toml
access_token = "your-token"
timezone = "America/New_York"

[server]
host = "localhost"
port = 8080

[[area]]
name = "Work"
id = "uuid-here"

  [[area.goal]]
  name = "Q1 Project"
  id = "uuid-here"

[[habit]]
name = "Exercise"
id = "uuid-here"
```

## Additional Notes

- For valid timezone values, see the IANA timezone database: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
- Configuration is validated on startup using go-playground/validator tags in the lunatask package