# AGENTS.md ## Global Instructions # Jahia JavaScript Module Development ## Context You are helping develop a **Jahia JavaScript Module** — a React-based template set for Jahia 8+. The module renders content from Jahia's JCR (Java Content Repository) using server-side React components (`.server.tsx`) and optional client-side islands (`.client.tsx`). Content is modelled in CND files, managed via Page Builder or jContent, and queried with JCR-SQL2 or GraphQL. ## Agent Principles 1. **Always invoke a skill before any Jahia task** — skills are the canonical source of patterns, gotchas, and API syntax. Never operate from memory alone. 1a. **Always load CND reference files before writing any CND** — Jahia-specific patterns (`choicelist[linkTypeInitializer]`, `mix:title`, child nodes for CTAs, `jmix:image` weakreferences) are not in your training data. Before writing any CND, read the reference files: `find "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" -name 'cnd-jahia-mixins*' -not -path '*/node_modules/*' | head -3`. When working interactively through skill chains, prefer `@jahia-cnd-author` (it loads these files for you). 2. **Never use `yarn dev` from an agent** — it is an interactive file watcher for human developers only. Always deploy with `yarn build && yarn jahia-deploy` (one-shot, non-interactive). 2a. **Use the TypeScript LSP for API discovery, never grep.** When you need to know a function's signature or what a module exports, call `mcp__ide__getDiagnostics` on the file after writing it — the LSP reads live type definitions and reports mismatches, wrong argument counts, and missing exports. Never run `grep` on `node_modules` to find a function name or signature. 3. **Never hardcode URLs** — all navigable links must come from contributed content (JCR nodes, `j:linkType`, `buildNodeUrl`). This is a CMS: content owns the URLs. 4. **Never use `j:linkType: "external"` for internal pages** — use `"internal"` + `j:linknode`. External URLs break on environment changes, language switches, and vanity URL rewrites. 5. **Always verify before creating** — check that content types are deployed, site keys are correct, and parent area nodes exist before creating content via MCP. 5a. **Create content as subtrees, not node by node** — `content.create` takes `children`, nested up to five levels, and creates the whole graph atomically. One call creates a section with its list and every card inside it; one call per page area block is the ceiling. A run that creates each card in its own call spends a model turn per node: the benchmark measured 83 calls for four pages where 20 would do. Call `page.structure` once per page for the container paths, then batch. 5b. **Add the images the content needs — never leave them out.** Upload each image with the MCP tool `media.upload.url` from a public HTTPS URL, such as `https://picsum.photos/seed//1600/900` (a different seed gives a different photo): it stores the file under `/sites//files` and returns its path. Set the image property of the content (`weakreference, picker[type='image']`) to that path. When MCP tools load on demand, search for `media_upload_url`. To upload a local file instead, use `media.upload.create` then `media.upload.finalize`. 6. **All props are optional at runtime** — even mandatory CND fields. Always guard against `undefined` in views. 7. **Use MCP tools for all Jahia operations — never GraphQL curl.** The `jahia` MCP server covers site, page, content, media, and publication operations. Never fall back to `curl` + GraphQL mutations for anything the MCP server can do. Never write Python scripts — use JavaScript or bash only. 7a. **`yarn` and `npx` must be run from the module root** — the module is a standalone project, not part of a monorepo. Running `yarn` from a parent directory fails with a workspace boundary error. Always `cd` to the module directory first. 7b. **Use `grep`, not `ugrep`** — `ugrep` is not available on all systems and does not support the same regex syntax. Use `grep -rn` for plain text, `grep -rn -E` for extended regex, or `grep -rn -P` for Perl-compatible patterns (e.g. lookaheads). Never use `ugrep` or `(?m)` flags. 8. **Build accessible HTML from the start** — every view must use semantic HTML (`
`, `
`, `