@@ -0,0 +1,119 @@
+<!--
+SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# AGENTS.md
+
+This file guides LLM agents through interacting with and maintaining
+the lune project—a CLI for the Lunatask productivity app.
+
+## Commands
+
+Run these most to least often:
+
+```bash
+task fmt lint:fix staticcheck test # Important ones to run often
+task # Include vulnerability and copyright checks
+```
+
+The Taskfile auto-installs tools (gofumpt, staticcheck, govulncheck) when
+running their respective tasks.
+
+## Architecture
+
+```
+main.go → cmd.Execute() entrypoint
+cmd/
+ root.go → Root command, registers all subcommands and groups
+ init.go, ping.go → Top-level commands
+ add.go, done.go, jrnl.go → Shortcuts (delegate to resource commands)
+ task/ → task add/list/get/update/delete
+ note/ → note add/list/get/update/delete
+ person/ → person add/list/get/update/delete/timeline
+ journal/ → journal add
+ habit/ → habit track
+internal/
+ client/ → Lunatask API client factory (reads LUNATASK_API_KEY)
+ config/ → TOML config at ~/.config/lunatask/config.toml
+ ui/ → Lipgloss styles (Success, Warning, Error, Muted, Bold)
+ validate/ → Input validation (UUID format)
+```
+
+**Command flow**: `fang.Execute()` wraps Cobra with version/commit info and
+signal handling. Resource commands live in subpackages (`cmd/task/`); shortcuts
+in `cmd/` delegate to resource commands by calling their `RunE` directly and
+copying their flagset.
+
+## Command patterns
+
+**Resource commands** (task, note, person, etc.):
+
+- Parent command in `<resource>.go` with `GroupID: "resources"`
+- Subcommands (add, list, get, update, delete) in separate files
+- Export the `*Cmd` vars for shortcuts to reference
+
+**Shortcuts** (add, done, jrnl):
+
+- Live in `cmd/` directly with `GroupID: "shortcuts"`
+- Copy flags from resource command:
+ `addCmd.Flags().AddFlagSet(task.AddCmd.Flags())`
+- Call resource command's `RunE` directly
+
+**Shell completions** registered inline via `RegisterFlagCompletionFunc`;
+see `cmd/task/add.go:43-56` for examples. Config-based completions load
+from `config.Load()`.
+
+## Core dependencies
+
+Reference docs via context7 or doc-agent when unsure:
+
+- `git.secluded.site/go-lunatask` (context7:
+ `/websites/pkg_go_dev_git_secluded_site_go-lunatask`): Lunatask API client.
+ Amolith maintains it, so issues can be resolved or missing features added
+ quickly.
+- `github.com/charmbracelet/lipgloss` (context7: `/charmbracelet/lipgloss`):
+ Terminal styling.
+- `github.com/charmbracelet/fang` (context7: `/charmbracelet/fang`): Cobra
+ wrapper with fancy styling, version injection, signal handling.
+- `github.com/BurntSushi/toml` (context7: `/burntsushi/toml`): Config file
+ parsing.
+- `github.com/spf13/cobra` (context7:
+ `/websites/pkg_go_dev_github_com_spf13_cobra`): CLI framework.
+
+## Gotchas
+
+### Lunatask E2E encryption
+
+Task/note names and content are end-to-end encrypted in Lunatask. The API only
+returns metadata (IDs, timestamps, status). See `cmd/task/list.go:17-20` for the
+documented limitation.
+
+### Linter exclusions for cmd/
+
+The `.golangci.yaml` disables several linters for `cmd/`:
+
+- `gochecknoglobals`, `gochecknoinits`: Cobra requires package-level vars and
+ `init()`
+- `errcheck`, `godox`: Stub implementations deliberately print without checking,
+ TODOs are placeholders
+- `wrapcheck`: CLI returns errors for display; wrapping adds noise
+
+These patterns are intentional.
+
+### API key
+
+Read from `LUNATASK_API_KEY` env var via `internal/client.New()`. No interactive
+prompts—fail fast with `client.ErrNoAPIKey` if unset.
+
+### Output formatting
+
+Use `cmd.OutOrStdout()` and `cmd.ErrOrStderr()` for testability. Styles are in
+`internal/ui/styles.go`—use `ui.Success`, `ui.Error`, etc. rather than inline
+colors.
+
+## Testing
+
+Currently stub implementations with `// TODO` markers. When implementing, use
+`cmd.SetOut()` / `cmd.SetErr()` to capture output.