Imported from rnwolfe/hearth (AGENTS.md). Install upstream with npx skills add rnwolfe/hearth. Copyright stays with the author.

hearth — agent notes

Agent-safe CLI for Home Assistant (official local REST API; long-lived access token). Read-only by default; the single mutation entry point is service call (+ apply), gated behind --allow-mutations (Agent CLI Guidelines v0.4.0, Full).

Build / test / run

go build ./...            # build
go vet ./...              # vet
go test ./...             # tests, incl. the schema-snapshot gate
go run ./cmd/hearth …     # run from source

• Schema drift: internal/cli/testdata/schema.json is a required CI gate. If a command/flag change is intentional, regenerate with HEARTH_UPDATE_GOLDEN=1 go test ./internal/cli -run TestSchemaGolden and review the diff.
• Tests never touch a real instance or the real keyring: they run against an httptest mock (newMockHA) with XDG_* pointed at temp dirs.

Conventions

• The contract surface (internal/output, internal/errs, the Guard gate in internal/cli/runtime.go, schema/agent in misc.go) is the agent-cli-factory profile of aclig.dev — don't invent new cross-tool norms here; route them through spec-propose.
• Output fields, flags, commands, and exit codes are append-only once released.
• Secrets: stdin/env only, never argv; keyring via OS-native backends only, 0600 file fallback (internal/auth).
• Instance-controlled free text (friendly names, logbook messages, template output) is fenced [UNTRUSTED_DATA_BEGIN] … [UNTRUSTED_DATA_END] in agent mode — keep new free-text fields fenced (contract §8).
• Areas/registry have no REST endpoint: area commands resolve via the official template API (POST /api/template + Jinja areas()/area_entities()), keeping hearth WebSocket-free. Don't add a WS dependency without a spec-level reason.

Freshness directive (commit-coupled)

When commands, flags, output fields, or exit codes change: update internal/skill/SKILL.md (ships embedded in the binary), the README's command tables, the docs site pages (site/src/content/docs/), and the landing (site/src/pages/index.astro) in the same change; regenerate the OG cards when titles or the headline change (cd site && pnpm og) and verify with pnpm build (also regenerates /llms.txt). Landing + docs styling share ONE token source: site/src/styles/tokens.css — never fork it. Regenerate the schema golden. A release (vX.Y.Z tag) runs GoReleaser (registry + tap) — see .github/workflows/release.yml; GORELEASER_TOKEN is required for the Homebrew tap push.