# Claude Code Project Instructions

## Project Stack

- **Language:** PHP 8.4
- **Framework:** Laravel (latest LTS)
- **Database:** MySQL
- **Deployment:** cPanel Git Version Control — auto-deploy via `.cpanel.yml` on every push
- **Web root:** repository root — `public/` is NEVER the document root on this cPanel host

All code, conventions, and tooling decisions must be consistent with this stack. Do not introduce Node, Vite, Docker, queues, Redis, or other services without developer approval.

## cPanel Auto-Deploy — Always Active

This project is directly hosted on cPanel and deployed automatically through cPanel Git Version Control. **These rules apply on every task, not only deployment tasks.**

Before touching any file that could affect the web entry point, `.htaccess`, asset paths, routes, or environment config:

1. Read `.claude/rules/cpanel-deployment.md` — mandatory, every time.
2. Confirm the root `index.php` and root `.htaccess` remain the sole web entry points.
3. Do not write anything to `public/` — web assets go in root-level folders (`css/`, `js/`, `assets/`, etc.).
4. Do not alter `.cpanel.yml` without developer approval.
5. `APP_URL` must match the live cPanel domain exactly.

Auto-deploy fires on push. Every merged file is immediately live. Treat every change as a production change.

---

## 1. First Read

Before editing code or documentation, read the files that already describe the project:

- `.claude/rules/cpanel-deployment.md` — always, before any change
- README files
- existing architecture or developer docs
- existing knowledge-base files
- relevant code near the change
- package/build/test configuration files

If the project has a knowledge base, use it before writing or updating files. If the project does not have one and the task creates durable knowledge, create or update the standard knowledge-base files after the task is verified and confirmed working.

## 2. Production-Ready Standard

Deliver production-ready changes:

- preserve the existing technology stack and architecture
- follow local naming, formatting, folder, and framework conventions
- keep changes small and reviewable
- do not introduce dependencies, services, queues, databases, build steps, or deployment requirements without approval
- validate external input
- protect secrets and sensitive data
- handle expected failures cleanly
- avoid broad rewrites and unrelated formatting churn
- add or update tests for behavior changes
- run validation commands when available

Do not claim a task is complete until validation has run or you have clearly stated why it could not run.

## 3. Enterprise Governance

Operate as a change-controlled enterprise coding agent:

- keep changes auditable and reviewable
- preserve user changes and avoid unrelated rewrites
- never run Git commands; Git status, diff, branch, commit, merge, rebase, push, and cleanup are developer-only
- require approval before dependency installation, schema proposal, migration, deployment, infrastructure, authentication, authorization, or production-impacting work
- document commands run, validation evidence, security impact, and remaining risk
- include rollback or mitigation notes for production-impacting changes
- do not add dependencies or services without approval and a clear reason

## 4. Knowledge Base Workflow

When writing or updating any file:

1. Look for existing knowledge-base files, including `docs/knowledge-base/`, `knowledge-base/`, `docs/kb/`, or repository-specific equivalents.
2. Read relevant knowledge-base entries before editing.
3. During implementation, keep notes about verified decisions, commands, table usage, integrations, and project conventions.
4. After tests/validation pass and the developer confirms the task is working, update the knowledge base.
5. Update the master knowledge base for all applications in the repository when the work affects shared behavior, multiple apps, common setup, cross-application schema, or reusable decisions.

Default files when no repository standard exists:

```text
docs/knowledge-base/master-knowledge-base.md
docs/knowledge-base/table-dictionary.md
docs/knowledge-base/applications/<application-name>.md
```

Do not record secrets, tokens, private keys, passwords, customer records, or production row data in the knowledge base.

## 5. Table Dictionary Workflow

Update the table dictionary when a task verifies or changes knowledge about tables, columns, relationships, indexes, schema ownership, data-access patterns, or MCP proposals.

Use metadata sources only:

- Schema MCP metadata
- migrations/schema docs already present in the repository
- reviewed developer-provided schema notes

Never use production row data to populate the table dictionary.

## 6. Schema MCP Workflow

The Schema MCP server is named `schema`.

Use MCP before designing or changing data-related code that depends on unknown schema:

- new entities or persisted fields
- unfamiliar tables
- repository/data-access changes
- reports, exports, imports, mappings, analytics, or queries
- schema reuse decisions
- new table, column, relationship, or index proposals

Required flow:

1. Call `find_existing_tables_for_concept` for the business concept.
2. Present candidate tables with scores and tradeoffs.
3. Stop for developer choice.
4. Call `describe_table` for every table that will be referenced.
5. Call `propose_table_change` only after developer approval.
6. Capture proposal IDs and include them in the final/PR summary.
7. Update the table dictionary after the task is verified and confirmed working.

If MCP is unavailable or unauthorized, stop and ask the developer to refresh MCP. Do not guess schema.

## 7. cPanel Deployment Workflow

See the **cPanel Auto-Deploy — Always Active** section at the top of this file. The full rule set is in `.claude/rules/cpanel-deployment.md` — read it before any change that touches web entry points, `.htaccess`, asset paths, routes, or environment config.

Do not change deployment behavior, document roots, production release steps, or public exposure rules without developer approval.

## 8. Security Rules

- Never print or commit bearer tokens, Authorization headers, `.env`, `.mcp.json`, `.claude.json`, certificates, private keys, or secret values.
- Use placeholders in docs and examples.
- If a real token is found, replace it with a placeholder and tell the developer to rotate or refresh it.
- Do not log sensitive data.
- Do not request production row data through MCP or chat.

## 9. Final Delivery

End every task with:

- summary of changes
- files changed
- validation run
- MCP tools used, if any
- database/schema impact
- cPanel/deployment impact, if applicable
- knowledge-base/table-dictionary updates made or intentionally deferred
- security and operational impact
- rollback or mitigation notes for production-impacting changes
- risks, assumptions, and manual steps