# Acai CMS — Project Instructions This is an Acai CMS website project. Follow these instructions when working with the codebase. ## Environment - The site runs on Acai Forge — get the live editable URL with the `get_web_url` MCP tool (never assume a fixed domain) - You can make HTTP requests to test pages, APIs, or form submissions against that URL - If you need to inspect the live site, use browser tools (Playwright MCP) or HTTP requests to the Forge URL ## Project Structure ``` . ├── template/estandar/ │ ├── modulos/ # Builder modules (visual components) │ │ └── / │ │ ├── index-base.tpl # Twig template (source — EDIT THIS) │ │ ├── style.css # Module styles │ │ └── script.js # Module JavaScript │ │ ├── index.tpl # Compiled (auto-generated, do NOT edit) │ │ ├── index-twig.tpl # Compiled (auto-generated, do NOT edit) │ │ └── builder.json # Compiled builder vars (auto-generated, do NOT edit) │ ├── css/ # Global CSS │ └── js/ # Global JavaScript ├── hooks/ # PHP hooks (server-side logic) ├── cms/ │ ├── data/schema/ # Database table schemas (JSON) │ ├── lib/plugins/ # CMS plugins │ └── uploads/ # Uploaded media files └── .acai # Project config (domain, tokens, DB credentials) ``` ## Key Concepts ### Modules (`template/estandar/modulos/`) Visual components that the site builder uses. Each module is a self-contained unit with its own template (Twig + Acai attributes), CSS, and JS. Modules are placed on pages via the drag-and-drop builder. The editable file is always `index-base.tpl`. - Include other modules: `` - Each module instance gets a unique `section_id` variable for anchors/scoping - Use `interno` variable to detect CMS editor mode vs public view See [docs/03-modules-and-sections.md](docs/03-modules-and-sections.md) for detailed rules. ### Pages Every record with an `enlace` field is a page. Pages are either **Builder** (modular) or **Standard**: - **Builder**: `controlador` = `cms/lib/plugins/builder_saas/controlador.php` — content via modules - **Standard**: `controlador` = `cms/lib/plugins/builder_saas/controlador_tabla.php` — content in record fields **Critical**: Never change `enlace` or `controlador` of existing pages unless explicitly asked. See [docs/04-pages-and-records.md](docs/04-pages-and-records.md) for full details. ### General Sections Database-backed templates (headers, footers, record views) that use the `thisrecord` variable to access record fields. They use the same Twig + Acai attribute engine as modules. - Upload fields return arrays: `thisrecord.image[0].urlPath` - Foreign keys use `_num` suffix: `category_num` See [docs/03-modules-and-sections.md](docs/03-modules-and-sections.md) for details. ### Hooks (`hooks/`) PHP files that execute server-side logic. Triggered by: - Twig filter: `'hooks/module_id/' | hook({param: value})` - HTML tag: `` - JavaScript: `CmsApi.hook('/hooks/module_id/', {param: value}, callback)` - Form action: via `c-form` attribute There are two valid hook locations: - Global hooks in `hooks/hooks..php` for reusable/shared server-side logic - Module-specific hooks in `template/estandar/modulos//hook.php` for logic owned by a single module How to reference them: - Global hook `hooks/hooks.calcular_precio.php` -> endpoint `/hooks/calcular_precio/` - Module hook `template/estandar/modulos/hero_banner/hook.php` -> endpoint `/hooks/hero_banner/` - Module hook `template/estandar/modulos/buscadorapartados_hjd8s/hook.php` -> endpoint `/hooks/buscadorapartados_hjd8s/` Rule of thumb: - If the logic is only used by one module, prefer that module's `hook.php` - If the logic will be reused by several modules/pages, create a global hook in `hooks/` - Return arrays from hooks; do not use `echo json_encode(...)` or `exit` - Calling a hook over plain HTTP (`curl https:///hooks/x/`) returns **404 on purpose**: the endpoint requires the `X-Hooks-Token` header. From the agent use the `call_hook` MCP tool; the site's own JS (`CmsApi.hook`) already sends the token See [docs/06-hooks-and-cmsapi.md](docs/06-hooks-and-cmsapi.md) for usage. ## Acai Core (web-base) The project workspace contains only the **customization layer** (modules, hooks, schemas, uploads). The CMS core (routing, rendering engine, admin panel, APIs) lives in a separate, shared directory called **web-base**. Do NOT modify web-base files — they are shared across all projects. ## Critical Rules 1. **Before working with any area (hooks, modules, templates, CSS/JS, etc.), read the corresponding documentation in `docs/` first.** Do not guess or assume — always consult the docs before taking action. 2. **NEVER use `mkdir` to create directories.** Instead, use `acai-write` to create the first file inside the directory — this creates parent directories automatically. For example, to create a new module, directly write the `index-base.tpl` file. 3. Only edit `index-base.tpl` in modules — `index.tpl`, `index-twig.tpl`, and `builder.json` are auto-generated 4. Editing or creating any `index-base.tpl` through `acai-write` or `acai-line-replace` triggers automatic compilation. `compile_module` is only for manual recovery when you need to force a recompile without changing the file. 5. `script.js` and `style.css` are static files — do NOT use Twig syntax inside them. Pass dynamic values from `index-base.tpl` via `data-*` attributes. 6. Use Twig **filters** (with `|`), never Twig functions 7. Table names without `cms_` prefix everywhere 8. Primary key is `num`, never `id` 9. Upload fields are arrays — access with `[0].urlPath` 10. Tailwind CSS as primary styling, custom CSS scoped with BEM when needed 11. Twig concatenation uses `~` operator: `'value=' ~ variable` 12. `enlace` (link) fields already include slashes — **NEVER modify an existing enlace** unless explicitly asked 13. **NEVER modify the `controlador` field** of existing records — it defines whether a page is Builder or Standard 14. **This repository is PUBLIC. NEVER commit secrets** (API keys, `ANTHROPIC_*` tokens, passwords). Local Claude Code config with credentials goes in `.claude/settings.local.json` (git-ignored), never in `.claude/settings.json`. Enable the secret-scanning hook once per clone: `git config core.hooksPath .githooks`. A leaked key stays in git history even after deleting it: rotate it immediately. ## MCP Tools This project has MCP tools for managing modules, records, media, and more. **Before starting any task, consult the tools reference for the correct workflow.** See [docs/09-mcp-tools-reference.md](docs/09-mcp-tools-reference.md) for the complete list of available tools and step-by-step workflows, and [docs/11a-decision-table.md](docs/11a-decision-table.md) to route a request to the right tool. Key workflows: - **Create module**: Read [docs/03-modules-and-sections.md](docs/03-modules-and-sections.md) first → create files with `acai-write` / refine with `acai-line-replace` → automatic compile on `index-base.tpl` → `add_module_to_record` (returns sectionId) → `set_module_config_vars` (returns uploadFields) → images via uploadFields. Use `compile_module` only if you need a manual recompile without editing the file. - **Edit module**: `acai-view` → `acai-line-replace` (or `acai-write` for full rewrites) → automatic compile on `index-base.tpl` - **Add images**: use `uploadFields` from `set_module_config_vars` response → `upload_record_image` - **Generate images**: `generate_image` → `upload_record_image` with returned URL ## Documentation The `docs/` folder holds the 13 canonical Acai docs (numbered; the same set the Forge agent uses). They are refreshed automatically from the canonical source — do not edit them here. - [docs/01-builder-fields.md](docs/01-builder-fields.md) — Builder field types (`data-field-*`), tabs, conditional visibility, colors/colorpicker, components - [docs/02-twig.md](docs/02-twig.md) — Twig filters reference (get, hook, queryDB, translate, module, set…) and `{% if %}` vs `c-if` - [docs/03-modules-and-sections.md](docs/03-modules-and-sections.md) — Modules, `index-base.tpl`, general sections (`custom-{table}`), module creation workflow, uploads - [docs/04-pages-and-records.md](docs/04-pages-and-records.md) — Page types (Builder vs Standard), controller, `enlace`, records with `num`, visibility, critical rules - [docs/05-tables-and-fields.md](docs/05-tables-and-fields.md) — Creating and changing tables and fields with the MCP tools, `regenerate_enlaces` - [docs/06-hooks-and-cmsapi.md](docs/06-hooks-and-cmsapi.md) — PHP hooks (global and per module), `CmsApi`/`CocoDB`, middleware, `X-Hooks-Token`/`call_hook`, record creation - [docs/07-css-js-conventions.md](docs/07-css-js-conventions.md) — Tailwind, BEM scoped CSS, `data-*` for dynamic values, `CmsApi.hook` from JS, Vue 3, native components - [docs/08-layout-and-libraries.md](docs/08-layout-and-libraries.md) — Header/footer/global CSS/global JS via `get_layout_field`/`set_layout_field`, global libraries - [docs/09-mcp-tools-reference.md](docs/09-mcp-tools-reference.md) — Full MCP tools inventory by category and canonical workflows - [docs/10-production-patterns.md](docs/10-production-patterns.md) — Real production snippets (header with menu, FAQ, zigzag, forms, listings, structured data) - [docs/11a-decision-table.md](docs/11a-decision-table.md) — "User intent → MCP tool" routing table - [docs/11b-rules-cheat-sheet.md](docs/11b-rules-cheat-sheet.md) — Non-negotiable rules cheat sheet (`cms_`, `num`, `_num`, upload arrays, `c-if`), field types - [docs/12-glossary.md](docs/12-glossary.md) — Short definitions of Acai terms (sectionId, recordNum, apartados, builder_custom, enlace, controlador…)