tool notes & conventions
=========================

package managers
---------

in general, stick to bun. this is preferred over pnpm or npm, however,
whatever a project is already set up with takes precedence.

git
---------

don't assume it's okay to commit or push or perform git operations.
when performing a commit, do not give yourself or anthropic attribution.
we like you, we don't like anthropic.

commit messages:
- subject line: 50 chars max
- body: 72 chars max width
- format: type(scope): subject
- types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
- use imperative mood ("add feature" not "added feature")

arch packages
---------

use pacman for official repos, yay for AUR. don't use paru.

coding standards
---------

follow the universal coding standards documented in ~/universal-coding-standards.md

key principles:
- max 3 levels of indentation (if you need more, refactor)
- comments explain *why*, not *what* or *how*
- test things in the browser, don't be lazy

line width
---------

- soft limit: 80-100 chars (forces clear thinking, works on split screens)
- hard limit: 120 chars max
- exceptions: user-visible strings, URLs, long literals

ui design
---------

when building UI, follow the design principles documented in
~/.claude/UI-DESIGN-PRINCIPLES.md

grepai
---------

use grepai as the primary tool for code exploration and search.

use `grepai search` instead of grep/glob/find for:
- understanding what code does or where functionality lives
- finding implementations by intent
- exploring unfamiliar parts of the codebase

use standard grep/glob only for exact text matching or file path patterns.
if grepai fails, fall back to standard tools.

```bash
grepai search "query here" --json --compact
grepai trace callers "Symbol" --json
grepai trace callees "Symbol" --json
grepai trace graph "Symbol" --depth 3 --json
```

open source contributions
---------

- even if a PR gets rebuilt/refactored by maintainers, it still matters
- be transparent about ai assistance in PRs
- check how similar features are structured before contributing
- prefer shared helpers over custom one-off implementations
- keep core lean - features belong at the edges (plugins/extensions)
- dynamic config > hardcoded catalog entries
- when unsure about architecture fit, ask in an issue first

other tools
---------

imsg
- send an iMessage/SMS: describe who/what, confirm before sending
- prefer short messages; avoid sending secrets

sag
- text-to-speech: specify voice, target speaker/room, and whether to stream