# Project Agent Guide

This is a Laravel 9 / PHP 8.1 point-of-sale and ERP application. Main
application code is in `app/`, feature modules are in `Modules/`, HTTP routes
are in `routes/`, database artifacts are in `database/`, UI assets and Blade
views are in `resources/`, and automated tests are in `tests/`.

Use this guide as the default procedure when working in this repository. Follow
any more specific instructions found in a directory before changing files under
it.

## How agents should work

1. Understand the requested outcome before editing. Identify the user-visible
   behavior, likely entry point, affected data, and authorization or financial
   implications.
2. Inspect existing code and conventions before proposing a design. Prefer the
   smallest change that fits the surrounding architecture.
3. Keep work scoped to the request. Do not reformat, rename, regenerate, or
   remove unrelated code or files.
4. Treat the working tree as potentially user-owned. Check `git status` before
   editing, preserve unrelated changes, and never use destructive Git commands
   such as `git reset --hard` or `git checkout --`.
5. Make changes with clear names, explicit validation, and safe failure paths.
   Avoid logging credentials, tokens, customer data, payment details, or other
   sensitive information.
6. Verify the change at the narrowest useful level, then report what changed,
   what was tested, and any remaining limitation.

## Start with the code graph

This workspace is indexed with `@sdsrs/code-graph` in
`.code-graph/index.db`. Before guessing paths or doing repository-wide text
scans, use the index to understand the relevant code.

Common commands:

```powershell
# High-level architecture and indexed areas
code-graph map

# Find a concept, route name, model, controller, or business term
code-graph search "sale payment"

# Find structural patterns when plain concept search is insufficient
code-graph ast-search "<query>"

# Inspect an indexed definition and trace relationships
code-graph show <SymbolName>
code-graph refs <SymbolName>
code-graph callgraph <SymbolName>
code-graph impact <SymbolName>
```

Use graph results to narrow the search, then read the implementation and its
tests. Use `rg` for focused exact-text searches, configuration files, templates,
translations, migrations, or files not represented well in the index. Do not
rely on symbol names alone: confirm route middleware, request validation, model
relations, database schema, and callers where applicable.

After adding, changing, moving, or deleting source files, refresh the index:

```powershell
code-graph incremental-index
```

## Problem-solving workflow

### Investigate a bug

1. Reproduce or precisely characterize the observed behavior; distinguish the
   expected result from the actual result.
2. Trace from the entry point (route, command, job, event, Livewire component,
   or API endpoint) through the service/controller/model code with the graph.
3. Check inputs, validation, authorization, configuration, data state,
   transactions, side effects, and error handling before selecting a cause.
4. Find the smallest root-cause fix. Do not mask errors with broad `try/catch`,
   silently ignore failures, or alter unrelated behavior.
5. Add or update a regression test when the behavior can be tested
   deterministically.

### Implement a feature or change

1. Locate similar existing behavior and follow its conventions.
2. Define the affected boundary: routes and middleware, request rules,
   controller/service action, models and relations, migrations, UI/API response,
   permissions, events/jobs, and tests.
3. For schema changes, create a reversible migration; do not edit an already
   deployed migration. Consider existing production data and indexes.
4. For sales, inventory, accounting, payments, and integrations, protect data
   integrity: validate amounts and state transitions, use database transactions
   where related writes must succeed together, and preserve auditability.
5. Review the diff for accidental changes and verify the requested workflow.

## Laravel conventions and useful commands

Use Artisan from the repository root:

```powershell
php artisan route:list
php artisan migrate:status
php artisan test
php artisan test --filter <TestName>
php artisan tinker
```

`tests/Unit` and `tests/Feature` are configured in `phpunit.xml`. Prefer a
focused test while iterating, then run the affected suite or full test suite
when practical. The test configuration uses `APP_ENV=testing`, array-backed
cache/session/mail, and synchronous queues; database setup must still be
understood before running database-dependent tests.

The front-end build uses Laravel Mix. If assets were changed, inspect
`package.json` and use its available npm scripts; do not invent a build command.

## Testing and verification

Every change should receive proportionate verification:

- PHP syntax or a focused test for a small server-side change.
- Feature or unit tests for business logic and regressions.
- Migration status and a safe test-database migration for schema changes.
- A build/lint step when JavaScript, CSS, or Blade asset tooling is affected.
- Manual verification of the relevant permission level and workflow when tests
  cannot cover it.

Before finishing, inspect `git diff --check` and `git diff`. Do not claim tests
passed if they were not run; state exactly which commands were run and why any
broader checks were skipped or blocked.

## Safety and collaboration

- Never commit, push, create pull requests, alter production settings, run
  destructive database commands, or send external messages unless explicitly
  requested.
- Do not expose values from `.env` or other secrets files in terminal output or
  responses.
- When requirements are ambiguous and the choice materially changes business
  behavior, pause and ask one concise question with the relevant trade-off.
- Leave the codebase cleaner only within the requested scope, and document
  assumptions or follow-up work in the final handoff.
