Unify CLAUDE.md and AGENTS.md

Signed-off-by: objec <objecttothis@gmail.com>

AGENTS.md

@@ -1,29 +1,108 @@
 # Agent Instructions
 
-This document provides guidance for AI agents working on the Open Source Point of Sale (OSPOS) codebase.
+This document is the single source of truth for all AI agents working on the Open Source Point of Sale (OSPOS) codebase. Read it fully before making any changes.
+
+## Project Overview
+
+OpenSourcePOS is a web-based Point of Sale system built on **CodeIgniter 4** (PHP 8.2+) with MySQL/MariaDB. Frontend uses Bootstrap 3 (Bootstrap 5 migration in progress) and jQuery, with assets built via Gulp.
+
+## Common Commands
+
+```bash
+# PHP dependencies
+composer install
+
+# Frontend dependencies and asset build
+npm install
+npm run build          # Runs Gulp: compiles and copies all CSS/JS to public/resources/
+
+# Run full test suite
+composer test
+
+# Run a single test file
+vendor/bin/phpunit tests/unit/AppTest.php
+
+# Lint / code style check
+vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php --dry-run
+
+# Apply code style fixes
+vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php
+```
+
+Tests require a MariaDB/MySQL database (see CI config in `.github/workflows/phpunit.yml`).
+
+## Architecture
+
+### Framework & Entry Point
+
+- **Framework**: CodeIgniter 4 — MVC with QueryBuilder ORM, no Eloquent
+- **Web root**: `public/` — `public/index.php` is the only entry point
+- **Routes**: `app/Config/Routes.php`
+- **App config**: `app/Config/App.php` (version, session, security settings)
+- **Environment**: `.env` file (copy from `.env.example`); `CI_ENVIRONMENT` controls dev/prod/test mode
+
+### Directory Layout
+
+```text
+app/
+├── Config/         # CI4 config classes
+├── Controllers/    # ~27 controllers (Sales, Items, Reports, Customers, etc.)
+├── Models/         # ~28 models (Sale, Item, Customer, Supplier, etc.)
+├── Views/          # PHP view templates
+├── Libraries/      # Business logic (Sale_lib, Tax_lib, Receiving_lib, etc.)
+├── Plugins/        # Plugin system — each plugin is a subdirectory here
+├── Database/       # Migrations (ospos_ prefix) and seeds
+├── Language/       # i18n files (IETF BCP 47 locale names)
+├── Filters/        # Request/response filters (auth, HTTPS, etc.)
+└── Events/         # CI4 event subscribers
+public/
+└── resources/      # Built CSS/JS (do not edit directly — generated by npm run build)
+tests/              # PHPUnit test suite
+```
+
+### Key Libraries
+
+`app/Libraries/` holds core business logic:
+- `Sale_lib.php` — sale cart state, pricing, discounts, tax calculation
+- `Tax_lib.php` — multi-tier tax engine
+- `Receiving_lib.php` — purchase orders / receivings
+- `Barcode_lib.php` — barcode generation
+- `Email_lib.php` — email delivery
+- `Token_lib.php` — CSRF/session token management
+
+### Database
+
+- Table prefix: `ospos_` (defined in `app/Config/Database.php`)
+- Migrations live in `app/Database/Migrations/` and run automatically on first access
+- CodeIgniter QueryBuilder throughout — no raw SQL unless necessary
+
+### Plugin System
+
+Plugins live in `app/Plugins/<PluginName>/` and are auto-discovered by `PluginManager`. Each plugin:
+- Extends `BasePlugin` or implements `PluginInterface`
+- Registers event hooks (e.g., `item_sale`, `customer_saved`, view hooks like `customer_tabs`)
+- Can include its own `Views/`, `Models/`, `Controllers/`, and `Language/` subdirectories
+- Configuration stored in `ospos_plugin_config` table
+- See `app/Plugins/README.md` for plugin structure, event hooks, and LICENSE requirements
+
+### Frontend Build
+
+`gulpfile.js` (Gulp 5) copies vendor CSS/JS from `node_modules/` into `public/resources/`. Run `npm run build` after installing npm packages or changing gulp tasks. Do not manually edit files under `public/resources/`.
 
 ## Code Style
 
-- Follow PHP CodeIgniter 4 coding standards
-- Run PHP-CS-Fixer before committing: `vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php`
-- Write PHP 8.2+ compatible code with proper type declarations
-- Use PSR-12 naming conventions: `camelCase` for variables and functions, `PascalCase` for classes, `UPPER_CASE` for constants
+- **PSR-12** enforced via PHP-CS-Fixer (config: `.php-cs-fixer.no-header.php`)
+- `camelCase` for variables and methods; `PascalCase` for classes; `UPPER_CASE` for constants
+- PHP 8.2+ features acceptable (named arguments, enums, readonly properties)
+- Views in `app/Views/errors/html/` are excluded from the fixer
+- Run fixer before committing: `vendor/bin/php-cs-fixer fix --config=.php-cs-fixer.no-header.php`
 
-## Development
+## Development Workflow
 
 - Create a new git worktree for each issue, based on the latest state of `origin/master`
 - Commit fixes to the worktree and push to the remote
-
-## Testing
-
-- Run PHPUnit tests: `composer test`
-- Tests must pass before submitting changes
-- Minimum PHPUnit version: 10.5.16+. Default config: `phpunit.xml.dist` in project root
-
-## Build
-
-- Install dependencies: `composer install && npm install`
-- Build assets: `npm run build` or `gulp`
+- Tests must pass before submitting changes (`composer test`)
+- Minimum PHPUnit version: 10.5.16+. Default config: `phpunit.xml.dist`
 
 ## Conventions
 
@@ -37,6 +116,10 @@ This document provides guidance for AI agents working on the Open Source Point o
 
 ## Security
 
+- `app.allowedHostnames` **must** be set in production (host header injection protection)
+- HTMLPurifier for HTML sanitization; Laminas Escaper for output escaping
+- CSRF tokens managed via `Token_lib` — do not bypass CI4's CSRF filter
+- Session storage is database-backed (`ospos_sessions` table) for multi-instance support
 - Never commit secrets, credentials, or `.env` files
 - Use parameterized queries to prevent SQL injection
 - Validate and sanitize all user input