# AGENTS Guide for PowerOfDark CMS Start with `Docs/knowledge/index.md`. It is the source of truth for repo guidance. Do not explain if not asked, focus on the job done, you can reason but do not explain again to the user, he just want the plans or the job done. When you're doing changes, do not explain also the changes except if not asked. Do not give a summary if is not asked. Keep your responses the much technical as possible and concise, avoid useless words, you can even use symbols to keep a smaller text, this also applies to the docs. Also, do not over analyze. For a concrete task, focus on the smallest implementation path; if required information is missing or a contract is ambiguous, ask before broadening the search. ## Context and Search Discipline - Start with the smallest relevant knowledge document and the files explicitly named by the request. - Use narrow, exact symbol or string searches scoped to the likely directories; do not run broad architecture scans when the target files are already known. - Read only the matching function, class, or nearby code needed to establish the change boundary instead of loading entire unrelated files. - Follow direct callers and consumers only after the initial evidence shows they are affected. - Expand to additional providers, models, routes, tests, or documentation only when the behavior crosses those boundaries or the focused search is inconclusive. - Stop investigation once the implementation path is clear, switch directly to editing, and reuse the gathered context. Do not reread the same files, repeat searches, or re-derive established facts unless the patch reveals a contradiction; ask the user when a contract is ambiguous. ## What matters here - Keep changes small and tied to the request. - Follow existing patterns in nearby files before introducing new ones. - If behavior differs by source type (`emulator`, `stream`, `trinity-stream`, variants), update each affected path and test only when the relevant environment is available. - Avoid editing bundled third-party code unless the task explicitly requires it. - Existing application strings may already contain HTML entities. Do not add `htmlspecialchars()` to new output by default; preserve the established encoding convention. If escaping appears necessary, ask the user before adding it. - Skip templates except if is requested, also skip them from the finidng/regex, if you have doubts, ask to the user before find in them, they are a very token expensive for nothing. - Skip models others than BASE and CMS except if is requested, also skip them from the finidng/regex, if you have doubts, ask to the user before find in them, they are a very token expensive for nothing. - Read `Docs/knowledge/index.md` before searching or opening application code. - When using `codebase-memory-mcp` with worktrees, always use and verify the project path for the current working directory/worktree. Treat the current folder as the canonical project path, even if an MCP response suggests another worktree or repository path. Never access or index a different folder unless the user explicitly asks for it. - `Databases/` contains customer restoration snapshots, not application source. Never read, search, index, inspect, inject context from, or modify anything under `Databases/` unless the user explicitly names that path or asks to inspect its contents. Exclude it from all discovery, grep, glob, MCP indexing, and validation by default. ## Project basics - Web entry point: `src/index.php` - CLI entry point: `src/cli.php` - No build step; the app runs directly in PHP/Apache. - Deployment-like obfuscation: `./tools/obfuscator/bin/obfuscate obfuscate ./src ./obfuscated --config=./tools/obfuscator-config.yml` ## Default workflow 1. Read the relevant knowledge document first, the index is at `Docs/knowledge/index.md`. If specified read only the target files it identifies and look for only the missing information in the code or if the user specified to check it. - For any database/table/relationship/schema task, read `Docs/knowledge/04-database-relationships.md` first. Treat it as the canonical relationship map; do not read or re-analyze anything under `Databases/` unless the user explicitly names it, even when verifying a documented discrepancy or adding a migration. 2. Implement using the current architecture and naming patterns. 3. Skip prettier and tests by default while they are unavailable; use only lightweight checks that do not require external services when verification is useful. ## Analysis Scope Rules - Application feature searches should start in `src/pages/`, `src/core/modules/`, `src/model/`, and `src/settings/`. - Skip `src/CuteNews/`, bundled libraries, `src/assets/`, generated or bundled theme assets, `Databases/`, and `tools/` unless the request explicitly names them. - For page work, inspect the route, controller, view, and only the relevant component API. Skip unrelated theme templates; use `Docs/api/form-components.md` and `Docs/api/template-components.md` for component behavior. - For model work, inspect `src/model/base/`, `src/model/cms/`, and only the active source override. Skip other source directories unless the change is source-specific or the shared API must be synchronized. - For email work, read `11-emails.md`; inspect `Mail.php`, the shared mail layout, and the named page mail template. Skip PHPMailer internals and unrelated mail templates. - For order/payment work, read `20-cart-orders.md` and `21-payment-discounts.md`; inspect base order/store models and the shared payment module before provider-specific files. - For admin order work, read `api/pages/admin__orders-management.md`; skip the customer cart and provider internals unless the request changes them. ## Contributing to Knowledge When adding new features or patterns: 1. Update the relevant knowledge document 2. If creating a new category, add to this index 3. Keep documents concise and practical with examples ## Linting Code style is enforced by **php-cs-fixer** with PSR-12 + custom rules: ```bash # Format changed files make pretty # Format all make pretty-all ``` Configuration in `.php-cs-fixer.dist.php`.