# Contributing

Cicadel is experimental. Start with a focused issue or change and describe the behavior you want to improve.

## Work locally

Use the Go version declared in `go.mod` and PostgreSQL 18 for integration tests. Read the repository's `AGENTS.md` for project scope and contribution requirements. PostgreSQL is the only supported database.

The [architecture guide](https://cicadel.fauzaanu.com/en/dev/internals/architecture/index.md) describes package boundaries. The [testing guide](https://cicadel.fauzaanu.com/en/dev/topics/testing/index.md) explains application fixtures and database-backed tests.

## Documentation

Edit the Markdown guides in `docs/` or the relevant module README. The documentation website imports these files during its Hugo build, so fixes stay shared between GitHub and the published site.

See the [website authoring instructions](https://cicadel.fauzaanu.com/en/dev/sources/website/README.md) for local builds, navigation and release snapshots.

## Verify changes

Run the checks in all applicable `.github/workflows/` workflows before pushing. Include nested Go modules and real PostgreSQL integration tests. UI changes require the matching Cicadel CLI's `ui build` and `ui check --json`; commit authored and generated files together.

Keep changes focused. Do not stage unrelated work in a shared checkout. Report validation results and known limitations with your change.

## Update the documentation site

Edit source guides in `docs/`; write for developers building applications, with
short explanations, working code and useful agent prompts. Put framework design
and implementation history in the separate framework section.

Follow [the website authoring guide](https://cicadel.fauzaanu.com/en/dev/sources/website/README.md) for navigation, LLM
exports, version snapshots and local checks. GitHub Actions builds and validates
all static assets on pull requests, then publishes the verified site automatically
when changes reach `main`. Do not edit generated `website/public/` files or deploy
from a personal machine as part of the normal authoring workflow.