1<!--
 2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
 3
 4SPDX-License-Identifier: CC0-1.0
 5-->
 6
 7# Configuration Guide
 8
 9This 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.
10
11## First-Run Behavior
12
13On first run, the server generates `config.toml` with placeholder values and exits. Users must:
14
151. Add their Lunatask API access token
162. Configure areas with real IDs from Lunatask (areas can have nested goals)
173. Configure habits with real IDs
184. Set timezone in IANA format (e.g., `America/New_York`, not `EST`)
195. Optionally customize server host/port (defaults to `localhost:8080`)
20
21## Configuration Structure
22
23The config uses TOML (not JSON) per project philosophy. Example structure:
24
25```toml
26access_token = "your-token"
27timezone = "America/New_York"
28
29[server]
30host = "localhost"
31port = 8080
32
33[[area]]
34name = "Work"
35id = "uuid-here"
36
37  [[area.goal]]
38  name = "Q1 Project"
39  id = "uuid-here"
40
41[[habit]]
42name = "Exercise"
43id = "uuid-here"
44```
45
46## Additional Notes
47
48- For valid timezone values, see the IANA timezone database: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
49- Configuration is validated on startup using go-playground/validator tags in the lunatask package