# AGENTS.md

Scope: this file applies to `~/Projects/bail` and all subdirectories, unless a deeper `AGENTS.md` overrides it.

## Workspace shape
- Treat `~/Projects/bail` as a multi-project workspace, not a single repo with one shared build or test command.
- Identify the target subproject before doing anything substantial. Most work should happen inside a specific package, library, or system directory rather than at the workspace root.
- Run commands from the relevant subproject directory, not from `~/Projects/bail`, unless the task is explicitly workspace-wide.
- Do not assume git commands work at the workspace root. Many tasks need to be done inside an individual subproject repo.

## Workspace map
- `packages/`: Composer packages shared across the PHP/Laravel systems.
- `systems/`: Deployable applications and services, including Laravel backends, Angular apps, and Node services.
- `libraries/`: Angular libraries published as internal `@ais/*` packages.
- `ai-context-pack/`: Source material used to generate tool-specific instruction files such as nested `AGENTS.md` and `CLAUDE.md`. Prefer changing the source of generated files rather than hand-editing generated outputs.
- `code-samples/` and `temp/`: Isolated examples or scratch work. Do not treat them as authoritative unless the task points there.
- `cdktf/` directories: Separate Node-based infrastructure projects with their own manifests and commands.

## Instruction precedence
- Always check for a closer `AGENTS.md` first. More specific instructions win.
- Known subprojects with their own `AGENTS.md` include:
  - `~/Projects/bail/packages/AGENTS.md`
  - `~/Projects/bail/packages/core/AGENTS.md`
  - `~/Projects/bail/packages/reports/AGENTS.md`
  - `~/Projects/bail/packages/self-serve/AGENTS.md`
  - `~/Projects/bail/packages/workflow-builder/AGENTS.md`
  - `~/Projects/bail/libraries/form-components/AGENTS.md`
  - `~/Projects/bail/systems/api/AGENTS.md`
  - `~/Projects/bail/systems/exports/AGENTS.md`
- Some nested instruction files are generated and explicitly say not to edit them by hand. Respect that.

## Key systems
- `systems/api`: Main AIS API backend. Laravel 11, PHP 8.3, MongoDB.
- `systems/app`: Main Angular portal used by handlers.
- `systems/exports`: TypeScript/AWS Lambda export microservice.
- `systems/oauth`: OAuth 2 server built on Laravel Passport.
- `systems/liability-api`: Laravel liability resolver service.
- `systems/enol-app`: Public-facing Angular ENOL application.
- `libraries/core-components`, `libraries/form-components`, `libraries/form-renderer`, `libraries/statement-renderer`: Shared Angular libraries consumed by the apps.

## Domain glossary
- Claim: Base insurance record. Belongs to a Client. Has Parties and must have a Policyholder.
- Party: Person or entity involved in a Claim.
- Client: Organisation we work with, such as an insurer or law firm.
- Department: Client subdivision used for branding and outbound communication rules.
- Form: Configurable data-capture structure built from Groups and Controls with conditional logic.
- Template: Multi-page capture layout made of Pages and Components with conditions.
- Workflow: Definition of a flow composed of linear Stages containing Templates.
- Report: Per-party instance of a Workflow. Workflow configuration is copied at creation time.
- Statement: Instance of a Template within a Report.
- Portal: Main handler-facing Angular app, primarily `systems/app`.
- Self-Serve: A Statement sent to a Party to complete directly.
- FNOL: First Notice Of Loss, typically a handler-created Claim in the Portal.
- ENOL: Electronic Notice Of Loss, the online capture flow used by `systems/enol-app`.

## Working rules
- Prefer small, focused changes over broad refactors.
- Before coding, search for an existing local pattern in the target subproject and follow it.
- If something is ambiguous, read the nearest `README.md`, manifest scripts, and any closer `AGENTS.md` before deciding.
- Keep changes contained to the relevant subproject unless the task truly spans multiple packages or systems.
- If a change touches a shared package and a consuming app or service, verify both sides or state clearly what still needs checking.
- Never commit or push unless a human explicitly asks.

## Tooling rules
- Do not invent commands. Prefer the scripts defined in the nearest `composer.json` or `package.json`.
- For PHP/Laravel work, use the target subproject's Composer scripts and existing Docker workflow. Tests often rely on Docker and MongoDB rather than local mocks.
- For Angular and other Node projects, prefer `yarn` when a `yarn.lock` is present.
- Do not switch a project from `yarn` to `npm`.
- `systems/exports` is the notable exception in this workspace: it uses `npm`, not `yarn`.
- For `cdktf/` work, treat the infra directory as its own project root and inspect local scripts and stack patterns before changing anything.

## Architecture cues
- `systems/api` uses a custom `refineries` package and its own API Resource pattern. Do not replace those with Laravel's built-in API Resources.
- `systems/api` and related Laravel services rely on OAuth 2 and established authorization patterns. Keep controllers thin and preserve existing validation and response conventions.
- Shared `bail/*` Composer packages live under `packages/`. If a system depends on one of them, make the package change in `packages/` and verify the consuming system still works.
- Angular apps depend heavily on internal `@ais/*` libraries. Check whether a change belongs in a library rather than in an app.
- `systems/exports` follows strict queue-first, idempotent processing patterns. Preserve those behaviors unless the task explicitly changes them.

## Safety and change hygiene
- Never edit installed or generated dependencies such as `vendor/` or `node_modules/`.
- Avoid broad formatting churn and unrelated file edits.
- Do not add dependencies without explaining why existing workspace tools or packages are insufficient.
- Treat logs, fixtures, and examples as potentially sensitive. Do not add secrets, tokens, or unnecessary PII.

## Verification
- Verify changes from the subproject you touched, using targeted commands first and broader suites when appropriate.
- In summaries, include the exact verification commands and the directory they should be run from.
- If verification is blocked by missing services, Docker, private registries, or local environment setup, say that explicitly instead of guessing.