1<!--
  2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
  3
  4SPDX-License-Identifier: CC0-1.0
  5-->
  6
  7# AGENTS.md
  8
  9This file guides LLM agents through interacting with and maintaining
 10the lune project—a CLI for the Lunatask productivity app.
 11
 12## Lunatask concepts
 13
 14Lunatask is end-to-end encrypted and any sensitive information
 15(person/task/note/habit names, contents, etc.) is all omitted. The API
 16only returns basic metadata (IDs, timestamps, status, etc.). That also
 17means there is no way to dynamically list the user's areas, habits, or
 18notebooks; they must copy those details from the desktop app into lune
 19during interactive initialisation or reconfiguration.
 20
 21## Commands
 22
 23Run these most to least often:
 24
 25```bash
 26task fmt lint:fix staticcheck test  # Important ones to run often
 27task                                # Include vulnerability and copyright checks
 28```
 29
 30The Taskfile auto-installs tools (gofumpt, staticcheck, govulncheck) when
 31running their respective tasks.
 32
 33## Architecture
 34
 35```
 36main.go              → cmd.Execute() entrypoint
 37cmd/
 38  root.go            → Root command, registers all subcommands and groups
 39  init.go, ping.go   → Top-level commands
 40  add.go, done.go, jrnl.go  → Shortcuts (delegate to resource commands)
 41  task/              → task add/list/get/update/delete
 42  note/              → note add/list/get/update/delete
 43  person/            → person add/list/get/update/delete/timeline
 44  journal/           → journal add
 45  habit/             → habit track
 46internal/
 47  client/            → Lunatask API client factory (uses system keyring)
 48  config/            → TOML config at ~/.config/lunatask/config.toml
 49  ui/                → Lipgloss styles (Success, Warning, Error, Muted, Bold)
 50  validate/          → Input validation (UUID format)
 51```
 52
 53**Command flow**: `fang.Execute()` wraps Cobra with version/commit info and
 54signal handling. Resource commands live in subpackages (`cmd/task/`); shortcuts
 55in `cmd/` delegate to resource commands by calling their `RunE` directly and
 56copying their flagset.
 57
 58## Command patterns
 59
 60**Resource commands** (task, note, person, etc.):
 61
 62- Parent command in `<resource>.go` with `GroupID: "resources"`
 63- Subcommands (add, list, get, update, delete) in separate files
 64- Export the `*Cmd` vars for shortcuts to reference
 65
 66**Shortcuts** (add, done, jrnl):
 67
 68- Live in `cmd/` directly with `GroupID: "shortcuts"`
 69- Copy flags from resource command:
 70  `addCmd.Flags().AddFlagSet(task.AddCmd.Flags())`
 71- Call resource command's `RunE` directly
 72
 73**Shell completions** registered inline via `RegisterFlagCompletionFunc`;
 74see `cmd/task/add.go:43-56` for examples. Config-based completions load
 75from `config.Load()`.
 76
 77## Core dependencies
 78
 79Reference docs via context7 or doc-agent when unsure:
 80
 81- `git.secluded.site/go-lunatask` (context7:
 82  `/websites/pkg_go_dev_git_secluded_site_go-lunatask`): Lunatask API client.
 83  Amolith maintains it, so issues can be resolved or missing features added
 84  quickly.
 85- `github.com/charmbracelet/huh` (context7: `/charmbracelet/huh`):
 86  powerful and attractive libs for interactive forms and prompts
 87- `github.com/charmbracelet/lipgloss` (context7: `/charmbracelet/lipgloss`):
 88  Terminal styling.
 89- `github.com/charmbracelet/fang` (context7: `/charmbracelet/fang`): Cobra
 90  wrapper with fancy styling, version injection, signal handling.
 91- `github.com/zalando/go-keyring` (context7: `/zalando/go-keyring`):
 92  Cross-platform interface to the system keyring
 93- `github.com/BurntSushi/toml` (context7: `/burntsushi/toml`): Config file
 94  parsing.
 95- `github.com/spf13/cobra` (context7:
 96  `/websites/pkg_go_dev_github_com_spf13_cobra`): CLI framework.
 97
 98## Gotchas
 99
100### Linter exclusions for cmd/
101
102The `.golangci.yaml` disables several linters for `cmd/`:
103
104- `gochecknoglobals`, `gochecknoinits`: Cobra requires package-level vars and
105  `init()`
106- `errcheck`, `godox`: Stub implementations deliberately print without checking,
107  TODOs are placeholders
108- `wrapcheck`: CLI returns errors for display; wrapping adds noise
109
110These patterns are intentional.
111
112### Access token
113
114Read from system keyring via `internal/client.New()`. No interactive
115prompts—fail fast with `client.ErrNoToken` if not configured.
116
117### Output formatting
118
119Use `cmd.OutOrStdout()` and `cmd.ErrOrStderr()` for testability. Styles are in
120`internal/ui/styles.go`—use `ui.Success`, `ui.Error`, etc. rather than inline
121colors.
122
123## Testing
124
125Currently stub implementations with `// TODO` markers. When implementing, use
126`cmd.SetOut()` / `cmd.SetErr()` to capture output.