# AGENTS.md

## Scope and Current State
- This repository is a near-default CodeIgniter 4 app starter (minimal app code, mostly framework config).
- App code currently has one route and one controller action: `app/Config/Routes.php` -> `Home::index` in `app/Controllers/Home.php`.
- Treat most behavior as config-driven; check `app/Config/*.php` before adding custom infrastructure.

## Architecture and Request Flow
- Web entrypoint is `public/index.php`; CLI entrypoint is `spark`.
- Both bootstrap through `app/Config/Paths.php` and `CodeIgniter\Boot` (`bootWeb` / `bootSpark`).
- Controllers should extend `app/Controllers/BaseController.php`; shared helpers/services are loaded in `initController()`.
- Views are rendered with `view()` and live under `app/Views/` (example: `welcome_message.php`).
- Auto-routing is disabled in `app/Config/Routing.php` (`$autoRoute = false`), so new endpoints require explicit route definitions.

## Config Decisions That Affect Agent Work
- Namespace/autoload roots: `App\` -> `app/`, `Config\` -> `app/Config/` (`composer.json`).
- Default DB group is `default` in `app/Config/Database.php` (MySQLi placeholder settings).
- In `ENVIRONMENT=testing`, DB group is forced to `tests` (SQLite `:memory:`) by `Database::__construct()`.
- Environment behavior is controlled by `app/Config/Boot/*.php` (dev shows errors; production hides them).
- `app/Config/Filters.php` keeps required framework filters enabled (`pagecache`, `performance`, `toolbar`; plus `forcehttps` alias present by default).

## Developer Workflows (Windows-friendly)
- Install deps: `composer install`
- Run tests (script): `composer test`
- Run tests directly on Windows: `vendor\bin\phpunit`
- Run local server: `php spark serve`
- Common CLI maintenance entrypoint: `php spark list` (then run generators/migrations from there)

## Testing Patterns in This Repo
- PHPUnit config is `phpunit.xml.dist` with bootstrap `vendor/codeigniter4/framework/system/Test/bootstrap.php`.
- Tests are organized under `tests/` and include unit/session/database examples.
- DB tests use `DatabaseTestTrait` and support fixtures under `tests/_support/Database/`.
- `tests/_support/Libraries/ConfigReader.php` is used to read config defaults without `.env` overrides.

## Conventions to Follow When Adding Features
- Add new HTTP endpoints in this order: route in `app/Config/Routes.php`, controller in `app/Controllers/`, view/model as needed.
- Keep reusable app wiring in config/services (`app/Config/Services.php`, `app/Config/*.php`) rather than ad-hoc globals.
- Keep writable runtime artifacts in `writable/` (`cache`, `logs`, `session`, `debugbar`); these are gitignored.
- Prefer extending existing CI4 patterns in this starter instead of introducing parallel architecture layers.

## Integration Boundaries
- External dependencies are composer-managed; primary runtime dependency is `codeigniter4/framework` (`composer.json`).
- DB, cache, session, email, and logging integrations are configured centrally in `app/Config/Database.php`, `Cache.php`, `Session.php`, `Email.php`, and `Logger.php`.
- If behavior is unclear, verify whether it comes from app config or CI4 framework defaults under `vendor/codeigniter4/framework`.

## Front-End Templates (Metronic)
- The UI is built on the **Metronic Tailwind HTML** theme.
- **Official docs**: <https://preview.keenthemes.com/html/metronic/docs/?page=index> — refer to this for component usage, layout options, utility classes, and integration guidance.
- **`metronic-tailwind-html-starter-kit/`** — use this as the base for all new page templates and layouts.
- **`metronic-tailwind-html-demos/`** — full library of demo pages and assets; reference these for available components, patterns, and markup examples when building features.
- Both folders are **gitignored** and exist only as local development references — they are **not deployed** to the web server.
- When creating or modifying views in `app/Views/`, adapt markup and structure from the starter kit / demos into CI4 view files rather than copying the folders wholesale.