# Contributing to `pi-news-api`

Thanks for contributing.

This project is small, but it is user-facing inside Pi and should stay
polished, predictable, and honest about what the Currents News API actually
returns.

## Principles

- Prefer correctness over flashy behavior
- Keep widget output readable in narrow terminals
- Keep docs aligned with shipped behavior
- Avoid unverified claims about the Currents API, compatibility, or security
- Preserve the package's narrow scope
- Never write `CURRENTS_API_KEY` to disk, logs, or generated files

## Repository layout

```text
index.ts                  TypeScript source of truth
dist/                     Compiled output committed to the repo
tests/                    Unit and package-structure tests
docs/COMPATIBILITY.md     Compatibility notes
README.md                 User-facing documentation
AGENTS.md                 Maintainer and agent guidance
SECURITY.md               Vulnerability reporting policy
CHANGELOG.md              Release history
```

## Local development

```bash
npm install
npm test
npm pack --dry-run
```

`npm test` does not require a live `CURRENTS_API_KEY` — the suite is
non-network and exercises pure functions only.

## Change checklist

Before handing work off or opening a PR:

1. Update `index.ts`
2. Rebuild `dist/`
3. Update `README.md` for user-visible changes
4. Update `AGENTS.md` if maintainer or agent behavior changed
5. Update `CHANGELOG.md` for shipped changes
6. Add or update tests
7. Run `npm test`
8. Run `npm pack --dry-run` if packaging or metadata changed

## Testing expectations

This repo prefers non-network tests so the suite stays fast and stable.

Good contributions usually include tests for:

- Currents article normalization and deduplication
- agent-tool registration, request construction, and structured results
- bounded interest-profile parsing, learning, decay, and personalized ranking
- category-name matching
- widget formatting guarantees
- rate-limit header parsing and HTTP error messaging
- package metadata and publish-file expectations

If you add functionality that calls the Currents API directly, keep the
network call isolated behind a small function so it can be mocked or stubbed
in tests rather than requiring a live key.

## Release policy

Maintainers do not commit, push, or publish from agent sessions unless the
user explicitly asks for it.