add agents file

# AGENTS.md

This file is a working guide for agents modifying the `go_port` implementation of `climax`.

## Mission

Maintain the Go port as a CLI-compatible implementation of the Python `climax` app, while preserving behavior and output expectations validated in this workspace.

## Scope Constraints

- Port target is `src/climax` behavior.

- Do not reintroduce removed features:

  - `gui` command

  - `crash` command

  - `--show-completion` flag

  - `--install-completion` flag

- Do not port Python-only files previously excluded from porting:

  - `gui.py`

  - `eggs.py`

## CLI Compatibility Rules

- Keep command names and options compatible with existing Go implementation and prior Python behavior.

- Keep `templates-list` and `static-list` output as plain line-by-line paths (no table reformat).

- `bundles-list`, `bundles-add`, and `bundles-remove` must keep the same output style.

- `info` and `projects` are expected to render styled tables (unless JSON mode is explicitly selected).

## Freeze Command Invariants

- Frozen HTML and static assets links must remain relative.

- Freeze runtime start log should include both HTTP port and stop port.

- Freeze start and stop ports are distinct:

  - start uses `runtimeMeta.HTTPPort`

  - stop uses `runtimeMeta.HTTPStopPort`

- Avoid regressions where freeze shutdown targets default `8080/8081` instead of runtime ports.

- Freeze should tolerate missing linked resources (4xx during crawl) without failing the whole command.

## Storage and Project Registry

- Use JSON storage in `~/.climax/projects.json`.

- Do not bring back SQLite-based registry logic.

- `lastProjectDir` has been removed and must stay removed unless explicitly requested.

## Localization Rules

- Localization is centralized in `i18n.go`.

- Locale resolution order:

  1. `--lang`

  2. `CLIMAX_LANG`

  3. `LANG`

  4. fallback to `fr`

- Any new user-facing string in `main.go` should go through `T("...")` with keys in `i18n.go`.

- Keep command outputs stable while localizing.

## Build, Test, and Packaging

- Dependencies are vendored. Prefer `-mod=vendor` in tests/build checks.

- Core checks:

  - `gofmt -w ...`

  - `go test -mod=vendor ./...`

  - `make test`

- `make test` intentionally includes explicit main-file test invocation:

  - `go test -mod=vendor main.go i18n.go main_test.go`

- Packaging targets:

  - `make build` (linux/amd64, darwin/arm64, windows/amd64)

  - `make installer-windows` (NSIS)

  - `make installer-macos` (unsigned `pkgbuild` package)

## Dependency Policy

- Vendor all dependencies (`go mod vendor`) after dependency changes.

- When upgrading dependencies, verify:

  - build succeeds

  - full tests pass

  - no CLI output regressions on critical commands

## Code Style Notes

- Empty slice literals are allowed when non-nil semantics are intentional (for example JSON should encode `[]` instead of `null`).

- For purely stylistic cases, prefer `var s []T` over `s := []T{}`.

- Keep changes minimal and behavior-focused; avoid broad refactors during bug fixes.

## High-Risk Areas

- Server start/stop port wiring in `start`, `stop`, and `freeze` flows.

- HTML/CSS URL rewriting logic for freeze output.

- CLI output formatting for commands with screenshot-matched expectations.

## Recommended Change Workflow

1. Identify behavior contract affected by the change.

2. Patch smallest relevant surface.

3. Add or update regression tests.

4. Run `go test -mod=vendor ./...` and `make test`.

5. Confirm no output-style regressions for impacted commands.