# AGENTS.md

`civilytics` is the house R package for Civilytics Consulting: a ggplot2 brand theme
system, curated palettes, logo composition, Quarto/Typst/Reveal templates, and
data-wrangling helpers for public-sector analysis. It is a library other projects
depend on, so a breaking change here breaks reports that are already published.

## Project tracking

This repo is managed with compass. `pm/compass.toml`
defines the workstreams; `pm/JOURNAL.md` records sessions; `pm/decisions/` holds
numbered, immutable decision records. Ask compass where things stand rather than
reading the config back.

Workstreams (the `ws/` label on every issue):

| `ws/` | covers |
|---|---|
| `theme` | `R/theme.R`, `R/colors.R`, `R/fonts.R` — themes, palettes, font loading |
| `logo` | `R/logo.R`, `R/flextable.R`, `inst/img/` — logo and branded output |
| `quarto` | `R/quarto.R`, `inst/quarto/` — HTML, PDF, Typst, Reveal templates |
| `helpers` | `R/utils.R`, `R/prop_conf.R`, `R/join_utilities.R`, `R/db.R`, `R/notifications.R` |
| `packaging` | `DESCRIPTION`, `NAMESPACE`, `Makefile`, `Dockerfile`, `.gitea/workflows/` |

## Commit cadence

One coherent unit per commit, subject line:

```
type(ws): subject (#N)
```

`type` is one of `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `perf`, `ci`.
`ws` is a workstream id from the table above. `#N` is the issue, when there is one.

## Conventions

`pm/compass.toml` is authoritative for these rules. Its `[roborev]
project_guidelines` are composed into `.roborev.toml`, so change them there and
re-run compass rather than editing `.roborev.toml` by hand. The prose below is the
same rules stated for a human reader; if the two ever disagree, `pm/compass.toml`
wins.

**Dependencies.** Base R plus ggplot2 (>= 4.0), grid/gridExtra, png/jpeg, stringr,
stringdist, showtext/sysfonts, jsonlite. No tidyverse: no dplyr, purrr, magrittr,
tibble, or data.table. Prefer an existing dependency or base R over adding one —
this package is installed into other people's environments.

**Brand colors** live in `civilytics_colors` and nowhere else. Never write a hex
literal in theme, scale, logo, or table code. (`R/flextable.R` still carries
off-brand Bootstrap defaults; that is known debt, not a pattern to copy.)

**Themes** default to a transparent background (`paper_bg = FALSE`) so plots
composite onto any Quarto, Reveal, or Typst background. Thread `ink`, `paper`, and
`accent` into ggplot2 4.0's base-theme parameters rather than setting element colors
one at a time. ggplot2 >= 4.0 is a hard dependency, so use S7 `@` property access on
plot and theme objects, not `$`.

**Naming.** New functions are snake_case. The camelCase exports (`countCleanr`,
`dbSafeNames`, `simpleCap`, `waldInterval`, `countDots`, `countNA`, `findDots`,
`nvals`) are frozen public API — do not rename them.

**Documentation.** Roxygen generates both `man/` and `NAMESPACE`. Declare imports
with `@importFrom` in the roxygen block; never hand-edit `NAMESPACE`. Every exported
function needs `@param` for each argument and `@return`; exported API needs
`@examples`. Re-run roxygen in the same commit as the code change — compass files
documentation debt when code moves and its `man/` pages do not.

**Output.** User-facing progress goes through `message()` so callers can suppress it.
No `cat()` or `print()` in package code.

**Assets.** Nothing personal or client-identifying is vendored into `inst/` — brand
assets only. Version 0.3.2 removed headshots for exactly this reason.

## Testing

testthat edition 3, one file per source file (`tests/testthat/test_theme.R` etc.).
Tests are self-sufficient: no reliance on state left by an earlier test. New
behaviour needs a test; a bug fix needs a test that fails without the fix.

```zsh
make check          # R CMD check --no-manual against a built tarball
Rscript -e 'devtools::test()'
```

CI runs `R CMD check` on `rocker/r-ver:4.6` via `.gitea/workflows/check.yaml` for
every push and PR to `master`.

## Release

Bump `Version` in `DESCRIPTION` and add a `NEWS.md` entry under **New features**,
**Bug fixes**, or **Internal**. `NEWS.md` is the changelog; compass tracks the work
that led to it, not the release itself.