diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000000000000000000000000000000000000..813284e84efaceec876f7969bf8d2d8acecbbb04
--- /dev/null
+++ b/AGENTS.md
@@ -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.