# AGENTS.md

> **Attention Humans & AI Agents:** This file is the project's single source of truth for file naming, code standards, and folder layouts. All modifications must strictly adhere to these rules.

## 1. File Naming Rules (Strict)
* **All Lowercase**: No capital letters are permitted in any filename.
* **No Separators**: Do not use dashes (`-`), underscores (`_`), or double underscores (`__`).
* **Dot Separation**: Use dots (`.`) to separate logical parts of the filename. 
* **Extension Placement**: The final dot must immediately precede the file extension.
* **Allowed Extensions**: `.php`, `.js`, `.json`, `.css`, `.md`

### Examples
* ✅ **Good**: `admin.tool.php`, `app.config.json`, `main.js`, `style.css`
* ❌ **Bad**: `admin_tool.php`, `admin-tool.php`, `Admin.Tool.php`, `bootstrap__core.php`

---

## 2. Code Naming Rules (PHP, JS, HTML)
* **Functions & Variables**: Must use strict `camelCase`. Do not use dots, dashes, or underscores.
  * ✅ **Good**: `sysPath()`, `appUrl()`, `$appId`, `$systemRoot`
  * ❌ **Bad**: `sys_path()`, `sys-path()`, `$app_id`, `$app.id`
* **Constants**: Eliminate language-native uppercase constants to avoid underscores. Use system-wide `camelCase` variables instead.
  * ✅ **Good**: `systemRoot`
  * ❌ **Bad**: `SYSTEM_ROOT`
* **No Custom Double Underscores**: Do not use `__` anywhere in filenames or custom code identifiers. (Language-native magic constants like PHP's `__FILE__` are the only exception).

---

## 3. Directory Layout & App IDs

### Structure Rules
* **App IDs**: Formatted using dots following a `category.name` pattern (e.g., `apps.defapp`).
* **Path Mapping**: App IDs mirror physical directory layouts under the local directory architecture.
* **Registry Rule**: The application registry maps IDs to paths. To rename an app, **modify the registry configuration only**. Never rename the physical files/folders manually.

### Repository Tree Structure
```text
.
├── AGENTS.md                  <-- This file (Root single source of truth)
├── apps/                      <-- Application collection root
│   ├── sh/                    <-- Global shell scripts
│   └── defapp/            <-- Default application profile (Maps to apps.defapp)
│       ├── admin/
│       ├── ai/
│       │   ├── output/
│       │   └── prompts/
│       ├── audit/
│       ├── config/
│       ├── css/
│       │   └── themes/
│       ├── data/
│       │   ├── config/
│       │   ├── fonts/
│       │   ├── logs/
│       │   └── sql/
│       ├── docs/
│       ├── img/
│       ├── js/
│       ├── pages/
│       ├── php/
│       ├── scripts/
│       ├── sql/
│       ├── src/
│       ├── templates/
│       └── tests/
├── docs/                      <-- Global system documentation
├── review/                    <-- Code review sandbox
└── system/                    <-- System engine core config and tools
    ├── admin/
    ├── ai/
    │   ├── output/
    │   └── prompts/
    ├── audit/
    ├── core/                  <-- Engine core code
    ├── css/
    │   └── themes/
    ├── data/
    │   ├── config/
    │   ├── fonts/
    │   └── sql/
    ├── docs/
    ├── img/
    ├── js/
    ├── pages/
    ├── php/
    ├── scripts/
    ├── sh/
    ├── sql/
    ├── templates/
    └── tests/
```

---

## 4. System Exceptions
* **Single-Word Entrypoints**: `index.php` is allowed without dot separation.
* **Documentation**: Files like `readme.md` or `changelog.md` are valid if completely lowercase.
* **Server Overrides**: System files like `.htaccess` are allowed but should be minimized.