# AGENTS.md

<!-- HCI SECTION: do not edit. Replace it with the latest copy from https://standards.hopechannel.io/AGENTS.md -->

## HCI Software Development Standards

This repository belongs to HCI (Hope Channel International). Follow these rules on every task. They summarize the HCI Software Development Standards at https://standards.hopechannel.io. If a rule here conflicts with a request, stop and tell the person you are working with instead of quietly breaking the rule.

A person is accountable for every change you make. Explain what you changed and why, so the person who commits or approves it can take responsibility for it.

### Never do these

- Never read, print, copy or commit secrets. Do not open `.env` files or other credential files. Use placeholder or development-only values; the secrets manager supplies real values at run time.
- Never put keys, passwords or tokens in code, configuration, images, logs, commit messages or chat. If you see a real secret anywhere, stop and tell the person so it can be rotated.
- Never push directly to the production branch, force-push, or delete protected branches. All changes go through pull requests.
- Never deploy from a local machine or from uploaded files. Every deployment comes from a commit in this repository.
- Never connect one system directly to another system's database. Integrate through documented, versioned APIs or the shared middleware layer.
- Never use real personal data in tests, fixtures, seeds or examples unless it has been anonymised. Never copy production data into development or staging.
- Never write names, email addresses, phone numbers or IP addresses to logs when an internal ID will do. Never expose secrets or tokens in error messages or logs.
- Never make a database reachable from the public internet.
- Never handle card details yourself. Use an established payment provider.
- Never add or upgrade a dependency to an unpinned or "latest" version.

### Always do these

- Work on a short-lived branch and open a small pull request. Merge to staging early.
- Run the project's checks before you say work is done: type check, lint, format, tests. Fix every finding or flag it clearly for the reviewer.
- Add or update automated tests for core business logic and for every public API or contract another system depends on.
- Treat every input as untrusted and validate it. Handle timeouts, retries and partial outages without losing data.
- Require authentication on every endpoint unless it is deliberately public. Give users, services and developers the least privilege they need.
- Use HTTPS or TLS for all traffic. Encrypt sensitive data at rest.
- Pin dependencies to exact versions and commit the lockfile. Install from the lockfile. Send version updates as their own pull request.
- Prefer a dependency release that is at least a week or two old, unless the upgrade fixes a security issue. Check a new package's maintenance and health before adding it.
- Use runtimes, frameworks and base images that still receive security fixes.
- Collect only the personal data a feature needs and record where it is stored.
- Give production services logs, a health check, error alerts and tested backups of the data they own.
- Keep the documentation in step with the code: the README (what it does, how to run it, how to deploy it, who owns it), the list of environment variable and secret names (names only, never values), the API documentation, and plain-language release notes.
- Keep infrastructure and deployment steps as files in this repository where possible.
- Choose the simplest design that meets the requirement. Put external services (AI models, speech, storage, payments) behind an interface so the provider can be swapped.

### Defaults when there is no project decision

A project may choose differently, and notes what it chose.

- Language and stack: TypeScript across the stack, with React and Next.js.
- Payments: Stripe, or 7me.
- Dependency scanning: GitHub security scanning, Snyk or Socket.
- Diagrams: draw.io, Excalidraw, Mermaid or Archify.
- Hosting: HCI's Coolify. Source control: a repository in HCI's GitHub organization.
- Projects built on Hope.Cloud follow https://developers.hope.cloud/dev/getting-started.

### When to stop and ask

Stop and ask the person you are working with before you:

- depart from a recommendation above (the reason must be recorded in the project documentation);
- change agreed scope, architecture, platform, price or timeline (this needs a change-control record approved by the software department and the requester);
- add a new SaaS service the software will rely on (the HCI Technology Department evaluates and manages these);
- touch anything that looks like a security issue or a leaked secret (these are reported to the software department straight away).

<!-- END HCI SECTION -->

## Project notes

<!-- Add your own project's notes below. Replace each line with real details. -->

- What this project does:
- Owner:
- How to run it locally:
- How to run the checks (type check, lint, format, tests):
- How it is deployed (staging and production):
- Where the stack departs from the HCI defaults, and why:
