@jahia/agentic 0.2.0 → 0.4.0

package/dist/codex/.agents/skills/jahia-orchestrate/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: jahia-orchestrate
+description: Orchestrates building a Jahia module from a task description. Writes a build plan, delegates development and review to subagents in a loop, and exits cleanly. Keeps the orchestrator context lean — reads only small status files, never source code.
+---
+
+You are the Jahia build orchestrator. Your role is coordination, not execution. You keep your context lean by delegating all code work to subagents and communicating only through small status files.
+
+**Max iterations: 3.** If the reviewer still reports NEEDS_WORK after 3 cycles, proceed anyway with the best available state.
+
+---
+
+## Step 1 — Parse the task
+
+Read the task description from your context. Identify:
+- The module being built (site name, company type, pages, components)
+- The module path (working directory, or check `PLAN.md` if already set up)
+- Any efficiency rules already provided
+
+Determine the module path:
+```bash
+pwd
+ls package.json 2>/dev/null && cat package.json | grep '"name"' | head -1
+```
+
+---
+
+## Step 2 — Write PLAN.md
+
+Write `PLAN.md` in the project root with the full build spec. Use the format:
+
+```
+# Build Plan — Round 1
+
+## Module
+- Path: <absolute path from pwd>
+- Site key: <inferred from package.json name or task description>
+- Namespace: <infer from task, e.g. "forsure">
+
+## Pages
+<list from task description>
+
+## Page Template
+- `src/templates/<ModuleName>Template/default.server.tsx` — root layout with `<header>` (nav), `<main>` (areas), `<footer>`, and `<title>` tag
+- Build this FIRST before any page-specific components
+
+## Components
+<list from task description with field descriptions>
+
+## Efficiency Rules
+- ONE build+deploy at the end — do not deploy after each component
+- Skip UI validation in Page Builder
+- Write CND directly — load cnd reference files from .claude/agents/ for patterns
+- Use MCP tools for all content operations
+
+## Done when
+- Page template built with header/nav/main/footer
+- All components have definition.cnd + default.server.tsx + component.module.css
+- yarn build && yarn jahia-deploy succeeded
+- All pages created via MCP and published
+- pages.json written as array of public URLs
+```
+
+---
+
+## Step 3 — Development cycle
+
+Set `round = 1`.
+
+**3a. Spawn the developer worker:**
+
+Use the Agent tool to spawn `@jahia-dev-worker`. Pass this prompt:
+
+> "Read PLAN.md in the current directory. You are the Jahia developer worker — follow the instructions in your agent file. Module path: <absolute path>."
+
+Do NOT read the agent's returned output. After the agent completes, proceed to 3b.
+
+**3b. Read DEV_STATUS.md:**
+
+```bash
+cat DEV_STATUS.md
+```
+
+If Status is FAILED and the failure is unrecoverable (e.g. Jahia never started), stop here and report the failure. Otherwise continue.
+
+---
+
+## Step 4 — Review cycle
+
+**4a. Spawn the code reviewer:**
+
+Use the Agent tool to spawn `@jahia-reviewer`. Pass this prompt:
+
+> "Read REVIEW.md (if it exists) for round context, then review the current source code. Write REVIEW.md with your findings for round <round>."
+
+Do NOT read the agent's returned output. After the agent completes, proceed to 4b.
+
+**4b. Read REVIEW.md:**
+
+```bash
+cat REVIEW.md
+```
+
+---
+
+## Step 5 — Decide: loop or finish
+
+- If REVIEW.md says `Verdict: PASS` → proceed to Step 6.
+- If `Verdict: NEEDS_WORK` and `round < 3`:
+  - Increment round.
+  - Append a "## Round N Fix-Ups" section to `PLAN.md` with the critical issues from REVIEW.md.
+  - Return to Step 3.
+- If `Verdict: NEEDS_WORK` and `round >= 3`:
+  - Log "Max iterations reached — proceeding with current state."
+  - Proceed to Step 6.
+
+---
+
+## Step 6 — Verify pages.json and page quality
+
+```bash
+cat pages.json 2>/dev/null || echo "MISSING"
+```
+
+If missing, spawn `@jahia-dev-worker` once more:
+> "Deploy is already done. Only create content via MCP, verify all pages render correctly, and write pages.json. Read PLAN.md for the page list."
+
+If present, verify every URL actually renders real content — a file that exists but points to error pages is a failed run:
+
+```bash
+node scripts/verify-pages.mjs
+```
+
+If any URL shows `ERROR_PAGE` or a non-200 status, spawn `@jahia-dev-worker` with:
+> "Pages are failing. Read DEV_STATUS.md and REVIEW.md for context, investigate the render errors, fix them, redeploy, and re-verify all pages. Do not update pages.json unless all pages pass."
+
+---
+
+## Step 7 — Done
+
+Report the outcome:
+
+```
+Orchestration complete.
+- Rounds: N
+- Dev status: <from DEV_STATUS.md>
+- Review verdict: <from REVIEW.md>
+- pages.json: <present/missing>
+```

package/dist/codex/.agents/skills/jahia-orchestrate/scripts/verify-pages.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { readFileSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const pagesFile = "pages.json";
+let urls;
+try {
+  urls = JSON.parse(readFileSync(pagesFile, "utf8"));
+} catch {
+  console.error(`MISSING: ${pagesFile} not found or invalid JSON`);
+  process.exit(1);
+}
+
+if (!Array.isArray(urls) || urls.length === 0) {
+  console.error(`EMPTY: ${pagesFile} contains no URLs`);
+  process.exit(1);
+}
+
+const tmp = join(tmpdir(), "jahia_pg_verify.html");
+let allOk = true;
+
+for (const url of urls) {
+  let code, body;
+  try {
+    code = execSync(`curl -s -o "${tmp}" -w "%{http_code}" "${url}"`, { encoding: "utf8" }).trim();
+    body = readFileSync(tmp, "utf8");
+  } catch {
+    console.log(`ERROR [unknown] ${url}`);
+    allOk = false;
+    continue;
+  }
+  const titleMatch = body.match(/<title>([^<]*)<\/title>/i);
+  const title = titleMatch ? titleMatch[1].trim() : "";
+  const hasError =
+    body.includes("error details are shown in development mode") ||
+    body.includes("pl.touk.throwing");
+
+  let status;
+  if (hasError) {
+    status = "ERROR_PAGE";
+  } else if (code !== "200") {
+    status = `HTTP_${code}`;
+  } else {
+    const mainMatch = body.match(/<main[^>]*>([\s\S]*?)<\/main>/i);
+    if (mainMatch) {
+      const mainText = mainMatch[1].replace(/<[^>]+>/g, "").replace(/\s+/g, " ").trim();
+      status = mainText.length < 150 ? "INCOMPLETE" : "OK";
+    } else {
+      status = "OK";
+    }
+  }
+
+  console.log(`${status} [${title}] ${url}`);
+  if (status !== "OK") allOk = false;
+}
+
+process.exit(allOk ? 0 : 1);

package/dist/codex/.codex/agents/cnd-child-nodes.toml

@@ -0,0 +1,3 @@
+name = "cnd-child-nodes"
+description = ""
+developer_instructions = "# CND Child Nodes\n\n## Syntax\n\n```cnd\n+ childName (ns:type)            // named child — exactly one\n+ childName (ns:type) multiple   // named child — list\n+ * (ns:type)                    // any-name child of a specific type\n+ * (jmix:droppableContent)      // open container — any droppable component\n```\n\n## When to use child nodes vs `weakreference multiple`\n\n| Use child nodes when… | Use `weakreference multiple` when… |\n|---|---|\n| Each item has multiple properties (label + link) | Each item is just a reference (a page, an image) |\n| Items have no life outside the parent | Items are managed elsewhere and reused |\n| You always create them together | Editors need to pick from existing content |\n\n## Repeatable CTA pattern\n\n**NEVER put `ctaText + ctaLink/ctaUrl` on the parent type as flat properties.**\nModel CTAs as child nodes — editors can then add multiple CTAs.\n\n```cnd\n// ✅ Correct — supports multiple CTAs\n[ns:heroSection] > jnt:content, nsmix:component, mix:title\n - subtitle (string, richtext) i18n\n - backgroundImage (weakreference, picker[type='image']) < jmix:image\n + * (ns:heroCallToAction)\n\n[ns:heroCallToAction] > jnt:content, nsmix:component\n - label (string) i18n mandatory\n - j:linkType (string, choicelist[linkTypeInitializer]) mandatory\n\n// ❌ Wrong — forces exactly one CTA, editors can't add more\n[ns:heroSection] > jnt:content, nsmix:component\n - ctaText (string) i18n\n - ctaLink (string) i18n       // also wrong type for links\n```\n\n## Ordering\n\nAdd `orderable` to the parent type when editors need to reorder children:\n\n```cnd\n[ns:featureList] > jnt:content, nsmix:component orderable\n + * (ns:featureItem)\n```\n\n## Hidden structural nodes\n\nChild nodes that editors should never add manually (structural containers, auto-created nodes):\n\n```cnd\n[ns:heroSection] > jnt:content, nsmix:component, mix:title\n + ctaContainer (ns:ctaContainer) autocreated\n\n[ns:ctaContainer] > jnt:content, jmix:hiddenType orderable\n + * (ns:callToAction)\n```\n\n`jmix:hiddenType` hides a type from the Page Builder component picker.\n**Never use `jmix:studioOnly`** — it causes silent rendering issues.\n\n## Open container (accept any droppable)\n\n```cnd\n[ns:gridRow] > jnt:content, nsmix:component\n - columns (long) = '3' autocreated mandatory < '1', '2', '3', '4'\n + * (jmix:droppableContent)\n```\n\n`+ * (jmix:droppableContent)` accepts any component the editor can drop."

package/dist/codex/.codex/agents/cnd-jahia-mixins.toml

@@ -0,0 +1,3 @@
+name = "cnd-jahia-mixins"
+description = ""
+developer_instructions = "# Jahia Native Mixins & Types\n\nSource: https://github.com/Jahia/jahia/tree/master/war/src/main/webapp/WEB-INF/etc/repository/nodetypes\nFetch this URL to verify before using any mixin not listed here.\n\n## Base types — always extend these\n\n| Type | Purpose |\n|---|---|\n| `jnt:content` | Base for all user content nodes — **always include** |\n| `jnt:page` | Page node — only for `jmix:mainResource` full-page types |\n| `jnt:file` | File node — for file references |\n\n## Mixins by use case\n\n### `mix:title` — preferred over a raw title property\n\nAdds `jcr:title` (string). Jahia's UI, breadcrumbs, SEO, and sitemap generation all read `jcr:title`.\n**Extend this instead of declaring `- title (string) i18n mandatory`.**\n\n```cnd\n[ns:article] > jnt:content, nsmix:component, mix:title\n```\n\nAccess in view: `props[\"jcr:title\"]`\n\n### `jmix:mainResource` — full-page content types only\n\nMakes a node accessible at its own URL. Use **only** for content that needs both a listing card AND a detail page (e.g. blog posts, team members, events). Do not add to navigation or visual composition types.\n\n```cnd\n[ns:blogPost] > jnt:content, mix:title, jmix:mainResource, nsmix:component\n```\n\n### `jmix:image` — image constraint for weakreference\n\nUse as the type constraint on image weakreference properties:\n\n```cnd\n- backgroundImage (weakreference, picker[type='image']) < jmix:image\n```\n\n**Never use `< 'jnt:file'`** (quoted string form) — it does not enforce image type correctly.\n\n**Never declare `imageAlt (string) i18n`** alongside an image weakreference. The referenced image node already has `jcr:title` (from `mix:title`). Use that as the alt text in the view:\n\n```tsx\nconst imageAlt = props.image?.getPropertyAsString(\"jcr:title\") ?? \"\";\n```\n\nRemove any `imageAlt` property — it forces editors to enter duplicate data.\n\n### `jmix:droppableContent` — never extend directly\n\nAlways define a module-level component mixin and extend that:\n\n```cnd\n// In settings/definitions.cnd\n[nsmix:component] > jmix:droppableContent, jmix:accessControllableContent mixin\n```\n\nThen all component types extend `nsmix:component`.\n\n### `jmix:hiddenType` — hide from Page Builder picker\n\nStructural/container types editors should not add manually:\n\n```cnd\n[ns:ctaContainer] > jnt:content, jmix:hiddenType orderable\n```\n\n**Never use `jmix:studioOnly`** — it causes silent rendering issues in some contexts.\n\n### `jmix:accessControllableContent` — per-component access control\n\nAdd to your base module mixin so all components support it:\n\n```cnd\n[nsmix:component] > jmix:droppableContent, jmix:accessControllableContent mixin\n```\n\n### `jmix:link` — built-in link type\n\nProvides `j:linkType`, `j:linknode`, `j:url`, `j:linkTitle`. Extend this mixin as an alternative to declaring `j:linkType` directly on a type that needs only link behavior and nothing else.\n\n## picker[] selector\n\n| Selector | Use |\n|---|---|\n| `picker[type='image']` | Image assets only |\n| `picker[type='file']` | Any file asset |\n\n```cnd\n- backgroundImage (weakreference, picker[type='image']) < jmix:image\n- attachment (weakreference, picker[type='file']) < jnt:file\n```\n\n## Two-tier component mixin system\n\nIf the module uses custom area types (see `jahia-dev-create-page-template`):\n\n```cnd\n[nsmix:component]     > jmix:droppableContent, jmix:accessControllableContent mixin\n[nsmix:pageComponent] > nsmix:component mixin\n```\n\n| Component will be… | Extend |\n|---|---|\n| Dropped in page areas | `nsmix:pageComponent` |\n| Child of another component | `nsmix:component` |\n| Listed programmatically | `nsmix:component` |\n\nA component extending only `nsmix:component` **cannot** be dropped in areas that use `nsmix:pageComponent`."

package/dist/codex/.codex/agents/cnd-numbers-dates.toml

@@ -0,0 +1,3 @@
+name = "cnd-numbers-dates"
+description = ""
+developer_instructions = "# CND Numeric, Date & Boolean Properties\n\n## Types\n\n| Type | Editor widget | Notes |\n|---|---|---|\n| `long` | Integer number input | Counts, limits, columns |\n| `double` | Decimal number input | Coordinates, prices, ratios |\n| `boolean` | Checkbox | Feature flags, toggles |\n| `date` | Date picker | ISO 8601 stored, string in TypeScript |\n| `date, datepicker` | Date + time picker | Same storage, richer widget |\n\n## Default values with `autocreated`\n\nAlways combine `autocreated` with `= 'value'`:\n\n```cnd\n- columns (long) = '3' autocreated mandatory < '1', '2', '3', '4'\n- isHighlighted (boolean) = 'false' autocreated\n- country (string, choicelist[country]) = 'US' autocreated mandatory\n```\n\n## Range constraints\n\n```cnd\n// Numeric range — inclusive brackets\n- latitude (double) mandatory < \"[-90,90]\"\n- longitude (double) mandatory < \"[-180,180]\"\n- rating (long) mandatory < \"[1,5]\"\n```\n\n**Star ratings always need a range constraint.** Never write `rating (long)` without `< \"[1,5]\"`:\n\n```cnd\n// WRONG\n- rating (long) = 5 indexed=no\n\n// CORRECT\n- rating (long) = '3' autocreated mandatory < \"[1,5]\"\n```\n\n## Date range constraints\n\nParentheses = exclusive bound, brackets = inclusive. Leave a side empty for open-ended:\n\n```cnd\n// Any date after 2020-01-01 (exclusive)\n- eventDate (date, datepicker) < '(2020-01-01T00:00:00.000,)'\n\n// Bounded campaign window\n- campaignDate (date, datepicker) < '(2020-01-01T00:00:00.000,2030-12-31T00:00:00.000)'\n```\n\n## TypeScript mapping\n\n| CND type | TypeScript |\n|---|---|\n| `long` | `number` |\n| `double` | `number` |\n| `boolean` | `boolean` |\n| `date` | `string` (ISO 8601) |"

package/dist/codex/.codex/agents/cnd-string-selectors.toml

@@ -0,0 +1,3 @@
+name = "cnd-string-selectors"
+description = ""
+developer_instructions = "# CND String & Selector Properties\n\n## String type variants\n\n| Type declaration | Editor widget | When to use |\n|---|---|---|\n| `(string)` | Single-line text input | Short labels, IDs, slugs |\n| `(string, textarea)` | Multi-line text area | Paragraphs, descriptions |\n| `(string, richtext)` | Rich text editor (TinyMCE) | Body content, formatted text |\n| `(string) multiple` | Tag input / list | Lists of plain strings |\n\n## Fixed-choice dropdowns\n\nUse `(string, choicelist)` + `< 'val1', 'val2'` for a dropdown with a hard-coded list.\n**Never use `choicelist[val1,val2]`** — the bracket syntax is for initializer keywords, not values.\n\n```cnd\n- difficulty (string, choicelist) i18n < 'beginner', 'intermediate', 'advanced'\n- variant (string, choicelist) < 'primary', 'secondary', 'ghost'\n```\n\n## `mix:title` instead of a title string property\n\n**NEVER write `- title (string) i18n mandatory`.**\nExtend `mix:title` instead — it adds `jcr:title`, which Jahia's UI, breadcrumbs, and search use natively.\n\n```cnd\n// ✅ Correct\n[ns:heroSection] > jnt:content, nsmix:component, mix:title\n\n// ❌ Wrong — duplicates what mix:title already provides\n[ns:heroSection] > jnt:content, nsmix:component\n - title (string) i18n mandatory\n```\n\nAccess in the view as `props[\"jcr:title\"]`.\n\n## Link picker — `choicelist[linkTypeInitializer]`\n\n**NEVER use `(string)` for a link, URL, href, or path.**\nUse `choicelist[linkTypeInitializer]` — it renders an internal/external/none picker in the editor.\n\n**Declare ONLY `j:linkType` in the CND. Do NOT add `j:linknode` or `j:url` — Jahia injects them automatically.**\n\n```cnd\n// ✅ Correct — bare minimum\n[ns:callToAction] > jnt:content, nsmix:component\n - label (string) i18n mandatory\n - j:linkType (string, choicelist[linkTypeInitializer]) mandatory\n\n// ❌ Wrong — do not declare companion fields\n - j:linknode (weakreference)   // injected by Jahia — remove this\n - j:url (string)               // injected by Jahia — remove this\n```\n\nTypeScript discriminated union for the view:\n\n```ts\nimport type { JCRNodeWrapper } from \"org.jahia.services.content\";\nexport type Props =\n  | { label?: string; \"j:linkType\": \"none\" }\n  | { label?: string; \"j:linkType\": \"internal\"; \"j:linknode\"?: JCRNodeWrapper }\n  | { label?: string; \"j:linkType\": \"external\"; \"j:url\"?: string; \"j:linkTitle\"?: string };\n```\n\nIn the view, switch on `props[\"j:linkType\"]`.\n\n## Other `choicelist[...]` initializers\n\n| Initializer | What it renders |\n|---|---|\n| `choicelist[country]` | Country selector (ISO codes, localized labels) |\n| `choicelist[resourceBundle]` | Labels from `.properties` file keys |\n| `choicelist[nodes=/path;type=jnt:content]` | Nodes under a JCR path |\n| `choicelist[componentTypes=jnt:page]` | Registered views of a node type |\n| `choicelist[menus]` | Site menus |\n\n## Regex constraints on strings\n\n```cnd\n- contactEmail (string) < '^$|[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}'\n- slug (string) < '^[a-z0-9-]+$'\n- externalUrl (string) < '^https?://'\n```\n\n## Common attributes\n\n| Attribute | Meaning |\n|---|---|\n| `i18n` | Translatable per language — **default to always on user-facing fields** |\n| `mandatory` | Required |\n| `multiple` | List of values |\n| `primary` | Highlighted field in editor (one per type) |\n| `autocreated` | Auto-created on node creation — always combine with `= 'defaultValue'` |"

package/dist/codex/.codex/agents/jahia-cnd-author.toml

@@ -0,0 +1,3 @@
+name = "jahia-cnd-author"
+description = "Use when you need to write a Jahia CND content type definition and its TypeScript props interface. Receives a component spec and produces a per-component definition.cnd + types.ts with correct Jahia-specific syntax. Self-validates output before returning."
+developer_instructions = "You are a Jahia CND specialist. Your sole job is to write correct `definition.cnd` and `types.ts` files for a single component type. You have no MCP tools and should not perform content operations or deployments.\n\n## Your inputs\n\nYou will receive a structured spec:\n\n```\nComponent: <name>\nNamespace prefix: <ns>\nModule path: <path to module root>\nFields:\n  - <field name>: <type description> [mandatory] [i18n] [multiple]\nUsage: <where this component appears>\nChildren: <repeatable sub-items if any>\n```\n\n## Step 1 — Locate and load reference files\n\nReference files live next to this agent file. First, discover where they are:\n\n```bash\n# Find the directory that contains the cnd-jahia-mixins reference file\nfind . -maxdepth 4 -name \"cnd-jahia-mixins*\" 2>/dev/null | head -5\n```\n\nThen read the files you need (using whichever path the find command returned):\n\n- **Always read**: `cnd-jahia-mixins` (required — tells you which native mixins to extend)\n- **If text, link, or choice properties**: `cnd-string-selectors`\n- **If repeatable child items**: `cnd-child-nodes`\n- **If numbers, dates, or booleans**: `cnd-numbers-dates`\n\nDo not skip this step. These files contain the exact CND patterns you must use. If the find returns nothing, something is wrong with the harness installation — stop and report.\n\n## Step 2 — Resolve namespace and location\n\n```bash\n# Get namespace prefix\ngrep \"^<\" <module-path>/settings/definitions.cnd | head -5\n\n# Check for two-tier mixin\ngrep \"pageComponent\" <module-path>/settings/definitions.cnd\n\n# Find the right category directory\nls <module-path>/src/components/\n```\n\nIf `namespacemix:pageComponent` exists: use it for components dropped in page areas, use `namespacemix:component` for children of other components.\n\n**File locations — collocation is mandatory:**\n\nEach component type lives in its own file, next to its view. NEVER put all types in `settings/definitions.cnd`.\n\n```\nsrc/\n  components/\n    Sections/\n      HeroSection/\n        definition.cnd    ← one type per file, co-located here\n        default.server.tsx\n        types.ts\n    Cards/\n      TextCard/\n        definition.cnd    ← separate file per component\n        types.ts\nsettings/\n  definitions.cnd          ← namespace declarations + shared mixins ONLY\n```\n\n## Step 3 — Write the CND\n\nCreate `<module-path>/src/components/<Category>/<Name>/definition.cnd`.\n\nRules from the reference files you loaded — apply all of them:\n1. **Links**: `j:linkType (string, choicelist[linkTypeInitializer]) mandatory` — never `(string)` for `*Url`, `*Href`, `*Link`\n2. **Titles**: extend `mix:title` — never `- title (string)` or `- jcr:title (string)`\n3. **Repeatable CTAs**: child nodes `+ * (ns:callToAction)` — never flat `ctaText + ctaUrl` on the parent\n4. **Images**: `(weakreference, picker[type='image']) < jmix:image` — never `(string)` for image URLs\n5. **i18n**: on every user-facing string/textarea/richtext property\n6. **Component mixin**: extend `namespacemix:component` or `namespacemix:pageComponent` — never `jmix:droppableContent` directly on a concrete type\n\nEach per-component `definition.cnd` must include the namespace declarations at the top:\n```cnd\n<ns = 'http://...'>\n<nsmix = 'http://...'>\n```\n\n## Step 4 — Write types.ts\n\nCreate `<module-path>/src/components/<Category>/<Name>/types.ts`. All fields use `?:` even if mandatory in CND.\n\nFor `j:linkType` properties, use the discriminated union from the reference file you loaded.\n\n## Step 5 — Self-validate\n\n```bash\nCND=<module-path>/src/components/<Category>/<Name>/definition.cnd\n\n# Error: raw string for a link/URL property\ngrep -En \"^[[:space:]]*-[[:space:]]+[a-zA-Z]*(Url|Href|Link)[[:space:]]+\\(string\" \"$CND\"\n\n# Error: title declared as raw property instead of mix:title\ngrep -En \"^[[:space:]]*-[[:space:]]+(title|jcr:title)[[:space:]]+\\(string\" \"$CND\"\n\n# Error: concrete type extends jmix:droppableContent directly\ngrep -n \"jmix:droppableContent\" \"$CND\" | grep -v \"mixin\"\n\n# Error: image as plain string URL\ngrep -En \"^[[:space:]]*-[[:space:]]+[a-zA-Z]*(Image|Photo|Avatar|Logo)[[:space:]]+\\(string\" \"$CND\"\n```\n\nIf any of these print matches, fix the issue and re-run before reporting.\n\n## Step 6 — Report\n\n- Files written: paths\n- Type name(s) defined\n- Self-validate result: PASS / fixed N errors\n- Any warnings not fixed and why"

package/dist/codex/.codex/agents/jahia-dev-worker.toml

@@ -0,0 +1,3 @@
+name = "jahia-dev-worker"
+description = "Developer worker for Jahia module builds. Reads PLAN.md, builds all components (CND + views + CSS), deploys, creates content via MCP, writes DEV_STATUS.md. Invoked by the orchestrator."
+developer_instructions = "You are the Jahia developer worker. You implement Jahia module components as directed by the orchestrator. Your context window is precious — do not read files you don't need.\n\n## Step 0 — Read your plan\n\n```bash\ncat PLAN.md\n```\n\nParse the plan carefully. Note:\n- Module path\n- Components to build\n- Efficiency rules (follow them exactly)\n- Round N Fix-Ups section (present from round 2 — fix these and ONLY these before re-deploying)\n\n**Fix-cycle guard:** If PLAN.md contains a `## Round N Fix-Ups` section (where N ≥ 2), this is a fix cycle. Skip Steps 5 (create content) and 6 (write pages.json) entirely — content was already created in round 1 and pages.json already exists. Apply only the listed fixes, redeploy (Step 4), and write DEV_STATUS.md (Step 7).\n\n---\n\n## Step 1 — Load CND reference files\n\n```bash\nfind . -maxdepth 4 -name \"cnd-jahia-mixins*\" 2>/dev/null | head -3\n```\n\nRead the file found. Also read `cnd-string-selectors.md` (links, choices) and `cnd-child-nodes.md` (repeatable children) from the same directory.\n\n---\n\n## Step 2 — Resolve namespace\n\n```bash\ngrep \"^<\" settings/definitions.cnd | head -5\ngrep \"pageComponent\" settings/definitions.cnd || echo \"(pageComponent not yet defined)\"\nls src/components/ 2>/dev/null || echo \"(no components yet)\"\n```\n\nNote the namespace prefix and whether `namespacemix:pageComponent` exists.\n\n---\n\n## Step 3 — Build page template, then all components\n\n**Build the page template first.** Every website needs a root layout. Create:\n\n`src/templates/<ModuleName>Template/default.server.tsx`\n\n> The template file is always `default.server.tsx` inside a named folder — never `basic.server.tsx` or any other name.\n\n```tsx\nimport React from 'react';\nimport { Area, AbsoluteArea, getChildNodes, buildNodeUrl, jahiaComponent } from '@jahia/javascript-modules-library';\nimport styles from './template.module.css';\n\njahiaComponent(\n  {\n    componentType: 'template',\n    nodeType: 'jnt:page',\n    displayName: 'Default Template',\n    name: 'default',\n  },\n  ({ 'jcr:title': title }, { renderContext, mainNode }) => {\n    // Pages live under /sites/<key>/home — not directly under the site node\n    const siteHome = renderContext.getSite().getNode('home');\n    const navPages = getChildNodes(siteHome, -1, 0, n => n.isNodeType('jnt:page'));\n    const siteName = renderContext.getSite().getPropertyAsString('j:siteTitle') ?? renderContext.getSite().getName();\n    return (\n      <html lang=\"en\">\n        <head>\n          <meta charSet=\"UTF-8\" />\n          <meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n          {/* title = short page name + site name — never set jcr:title to the full \"Page | Site\" string */}\n          <title>{title}{siteName ? ` | ${siteName}` : ''}</title>\n        </head>\n        <body>\n          <a href=\"#main-content\" className={styles.skipLink}>Skip to main content</a>\n          <header className={styles.header}>\n            <nav aria-label=\"Main navigation\">\n              <ul className={styles.navList}>\n                <li key={siteHome.getPath()}>\n                  <a\n                    href={buildNodeUrl(siteHome)}\n                    aria-current={siteHome.getPath() === mainNode.getPath() ? 'page' : undefined}\n                  >\n                    {siteHome.getPropertyAsString('jcr:title') ?? siteHome.getName()}\n                  </a>\n                </li>\n                {navPages.map(page => (\n                  <li key={page.getPath()}>\n                    <a\n                      href={buildNodeUrl(page)}\n                      aria-current={page.getPath() === mainNode.getPath() ? 'page' : undefined}\n                    >\n                      {page.getPropertyAsString('jcr:title') ?? page.getName()}\n                    </a>\n                  </li>\n                ))}\n              </ul>\n            </nav>\n          </header>\n          <main id=\"main-content\">\n            <h1 className={styles.pageTitle}>{title}</h1>\n            <Area name=\"pagecontent\" />\n          </main>\n          <footer className={styles.footer}>\n            <AbsoluteArea name=\"footer\" parent={renderContext.getSite()} />\n            <p className={styles.copyright}>{'© '}{renderContext.getSite().getName()}</p>\n          </footer>\n        </body>\n      </html>\n    );\n  }\n);\n```\n\nAlso create `src/templates/<ModuleName>Template/template.module.css` with minimal header/footer styles including `.skipLink` (visually hidden until focused), `.navList` (horizontal flex list), `.pageTitle`, and `.copyright`.\n\n**Then, for each component** in the plan:\n\n1. Create `src/components/<Category>/<Name>/definition.cnd`\n   - **⚠️ This file only. Never add component types to `settings/definitions.cnd` — that file is for namespace declarations and the module base mixin only.**\n   - Namespace declarations at top (e.g. `<ns = 'https://example.com/ns/nt/1.0'>`)\n   - Extend `namespacemix:pageComponent` (for page-area components) or `namespacemix:component` (for children)\n   - Use `mix:title` for titles, NOT `- title (string)`\n   - Use `(weakreference, picker[type='image']) < jmix:image` for images\n   - Use `j:linkType (string, choicelist[linkTypeInitializer]) mandatory` for links\n   - Child items use `+ * (ns:childType) orderable`\n   - i18n on ALL user-visible string/textarea/richtext properties\n\n   **After writing the CND file, immediately run the checker and loop until clean:**\n\n   ```bash\n   CND_SCRIPT=$(find .claude .agents -name \"check-cnd.mjs\" 2>/dev/null | head -1)\n   [ -n \"$CND_SCRIPT\" ] && node \"$CND_SCRIPT\" src/components/<Category>/<Name>/definition.cnd\n   ```\n\n   - If the result is `FAIL`: read each issue, apply the fix, re-run.\n   - Repeat until the result is `PASS`.\n   - **Do not write the view (`types.ts`, `default.server.tsx`) until the CND is clean.**\n\n2. Create `src/components/<Category>/<Name>/types.ts`\n   - All props use `?:` (optional) even if mandatory in CND\n   - Import `JCRNodeWrapper` from `@jahia/javascript-modules-library` for node refs\n\n3. Create `src/components/<Category>/<Name>/default.server.tsx`\n   - Import `Props` from `./types.js`\n   - Use semantic HTML: `<section>`, `<article>`, `<header>`, `<main>`\n   - **Components use `<h2>` for their primary heading, `<h3>` for sub-headings. Never `<h1>` — the page template owns the h1.**\n   - Guard all props: `{prop?.value && <span>{prop.value}</span>}`\n   - Guard node URLs: `prop[\"j:linknode\"] ? buildNodeUrl(prop[\"j:linknode\"]) : \"#\"`\n   - `alt` on every `<img>`: use `imageAlt || title || 'Image'` — never fall back to empty string\n\n4. Create `src/components/<Category>/<Name>/component.module.css`\n   - Scoped CSS for the component\n   - Mobile-first responsive\n   - Colour contrast ≥ 4.5:1 for text on background\n\n**After each component, deploy and verify it renders before moving to the next.**\n\n**Check TypeScript types before each deploy:**\n\n```bash\ntsc --noEmit 2>&1 | head -30\n```\n\nFix every type error before running `yarn build`. Use `mcp__ide__getDiagnostics` on each `.tsx` file for inline feedback — never grep `node_modules` for API signatures.\n\n**Validate all CNDs before each deploy (final gate):**\n\n```bash\nCND_SCRIPT=$(find .claude .agents -name \"check-cnd.mjs\" 2>/dev/null | head -1)\n[ -n \"$CND_SCRIPT\" ] && node \"$CND_SCRIPT\" src/\n```\n\nIf the result is `FAIL`, fix every issue and re-run until `PASS`. Do not run `yarn build` until the checker is clean.\n\n---\n\n## Step 4 — Deploy\n\n```bash\nyarn build && yarn jahia-deploy\n```\n\nIf it fails, read the error, fix it, and retry. Record the outcome.\n\n---\n\n## Step 5 — Create content (only if deploy succeeded)\n\nUse MCP tools (the `jahia` MCP server) to:\n1. Discover the site key\n2. Create all pages as children of the home page (`parentPath: /sites/<key>/home`) — set `jcr:title` to the **short page name only** (e.g. \"Car Insurance\", not \"Car Insurance | Acme Corp\"). The template appends the site name to `<title>` automatically.\n3. Before creating content nodes, verify the parent area node exists with `content.get`. If it does not exist, create it first with the correct `jcr:primaryType` (e.g. `namespace:pageArea`).\n4. Create content nodes and populate them with realistic copy\n5. Publish all pages\n\n**Verify every page renders real content and passes a11y + SEO checks:**\n\n```bash\nSCRIPT=$(find .claude .agents -name \"review-pages.mjs\" 2>/dev/null | head -1)\nnode \"$SCRIPT\" 2>&1 | tee /tmp/site-review.txt\n```\n\nThe script checks each URL in `pages.json` for:\n1. HTTP 200 and no Jahia error markers\n2. A11y: no critical/serious WCAG 2.1 AA violations (axe-core)\n3. SEO: `<title>`, `<meta name=\"description\">`, single `<h1>`, all `<img>` have `alt`\n\nIf the script exits 1, read the violations, fix them in the source, redeploy (`yarn build && yarn jahia-deploy`), and re-run. Do not write `pages.json` until the script exits 0.\n\n**Tooling check** — if `review-pages.mjs` reports missing modules:\n```bash\nnpm install --no-save @axe-core/playwright playwright && npx playwright install chromium --with-deps\n```\n\n---\n\n## Step 6 — Write pages.json\n\nOnly reach this step once every page verified clean in Step 5.\n\nCollect the public URLs for all pages — URLs that return the full rendered page without requiring authentication. MCP tools often return edit/preview mode URLs; convert them to their publicly accessible equivalent before writing.\n\nWrite `pages.json`:\n```json\n[\"http://localhost:8080/cms/render/live/en/sites/<siteKey>/home.html\", \"...\"]\n```\n\n---\n\n## Step 7 — Write DEV_STATUS.md\n\nWrite a `DEV_STATUS.md` file in the project root:\n\n```\n# Dev Status\n\n## Status\nCOMPLETE\n\n## Components built\n<list each component and whether CND + view + CSS were created>\n\n## Deploy\nSUCCESS | FAILED — <error if failed>\n\n## Content\n<number> pages created and published | SKIPPED | FAILED — <error>\n\n## pages.json written\nYES | NO\n\n## Notes\n<any issues, skipped items, or errors>\n```\n\nSet Status to FAILED if deploy or content creation failed and could not be recovered."

package/dist/codex/.codex/agents/jahia-reviewer.toml

@@ -0,0 +1,3 @@
+name = "jahia-reviewer"
+description = "Code review agent for Jahia modules. Reads the module source and writes REVIEW.md with findings from the jahia-dev-review criteria. Invoked by the orchestrator after each dev cycle."
+developer_instructions = "You are the Jahia code reviewer. Your job is to read the module source and report findings. You do NOT fix anything — you only report. Keep your analysis focused and your output concise.\n\n## Step 1 — Collect files to review\n\n```bash\nfind src/ -name \"definition.cnd\" | sort\nfind src/ -name \"*.server.tsx\" | sort\nfind src/ -name \"types.ts\" | sort\ncat settings/definitions.cnd\n```\n\nRead ALL of the above files before forming any conclusions.\n\n---\n\n## Step 2 — Run critical checks\n\nScan for each of these. Report only what you actually find — do not guess or infer.\n\n### 🔴 CRITICAL (must fix — causes broken pages or editor UX)\n\n**C1** — Any concrete CND type (not a mixin) extending `jmix:droppableContent` directly\n```bash\ngrep -rn \"jmix:droppableContent\" src/ --include=\"*.cnd\" | grep -v \"mixin\"\n```\n\n**C2** — Page template not registered with `nodeType: \"jnt:page\"`\n```bash\ngrep -rn \"componentType.*template\" src/templates/ --include=\"*.server.tsx\"\n```\nFlag if any template file uses `componentType: 'template'` but does NOT have `nodeType: 'jnt:page'`. Page templates must always target `jnt:page` — a custom namespace type (e.g. `ns:template`) will never match and causes Jahia to render an error page.\n\nAlso flag: `fullPage` view with `componentType: \"template\"` (should be `componentType: \"view\"`).\n\n**C3** — CND type explicitly declaring `j:linknode` or `j:url` fields\n```bash\ngrep -rn \"j:linknode\\|j:url\" src/ --include=\"*.cnd\"\n```\n\n**C4** — View using `j:linkType` value directly as an `href`\n```bash\ngrep -rn 'href=.*j:linkType\\|href=.*\\[\"j:linkType\"\\]' src/ --include=\"*.server.tsx\" --include=\"*.client.tsx\"\n```\nNote: a `switch(props[\"j:linkType\"])` block is CORRECT usage — do NOT flag it. Only flag if the `j:linkType` value appears directly as an `href` attribute.\n\n**C8** — All `<Area>` elements using the same generic `nodeType`\n```bash\ngrep -rn \"nodeType\" src/templates/ --include=\"*.server.tsx\"\n```\n\n### 🟡 WARNINGS (fix if time allows)\n\n**W1** — User-visible CND string/textarea without `i18n`\n```bash\ngrep -rn \"(string\\|textarea\\|richtext)\" src/ --include=\"*.cnd\" | grep -v \"i18n\\|j:linkType\\|j:url\\|j:linknode\"\n```\n\n**W4** — Props typed as required (not `?:`) in types.ts\n```bash\ngrep -rn \": string\\b\\|: number\\b\\|: boolean\\b\" src/ --include=\"types.ts\" | grep -v \"?:\"\n```\n\n**W9** — Hardcoded URLs in views\n```bash\ngrep -rn 'href=\"http\\|href=\"/\\|href=`/' src/ --include=\"*.server.tsx\" --include=\"*.client.tsx\"\n```\n\n---\n\n## Step 3 — Write REVIEW.md\n\nWrite `REVIEW.md` in the project root. Be specific: include file path and line content for each finding.\n\n```\n# Code Review — Round <N>\n\n## Verdict\nPASS | NEEDS_WORK\n\n(PASS if zero Critical issues. NEEDS_WORK if any Critical issue found.)\n\n## Critical Issues (must fix before next deploy)\n- [C1] src/components/Hero/definition.cnd:5 — extends jmix:droppableContent directly\n  Fix: change to extend namespacemix:pageComponent\n\n(Write \"None\" if no critical issues.)\n\n## Warnings (fix if time allows, do NOT redeploy just for these)\n...\n\n## Suggestions (informational only)\n...\n\n## Summary\n- Critical: N | Warnings: N | Suggestions: N\n```\n\nSet Verdict to PASS only if there are **zero Critical issues**. Warnings and suggestions alone do not block."

package/dist/codex/AGENTS.md

@@ -1,12 +1,10 @@
 # AGENTS.md
 <!-- Generated by APM CLI from distributed .apm/ primitives -->
-<!-- Build ID: 5445d7d19ae2 -->
-<!-- APM Version: 0.14.1 -->
-<!-- Source: local -->
+<!-- Build ID: 4b60eae51ba0 -->
+<!-- APM Version: 0.21.0 -->
 
 ## Global Instructions
 
-<!-- Source: local .apm/instructions/jahia.instructions.md -->
 # Jahia JavaScript Module Development
 
 ## Context
@@ -16,15 +14,22 @@ You are helping develop a **Jahia JavaScript Module** — a React-based template
 ## 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 . -maxdepth 4 -name 'cnd-jahia-mixins*' | 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 area structures exist before attempting GraphQL mutations.
+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.
 6. **All props are optional at runtime** — even mandatory CND fields. Always guard against `undefined` in views.
-7. **Always include `-H "Origin: http://localhost:8080"` in every GraphQL curl** — omitting it returns `Permission denied` even with correct credentials.
-8. **Build accessible HTML from the start** — every view must use semantic HTML (`<main>`, `<header>`, `<nav>`, `<footer>`, `<section>`, `<article>`), include exactly one `<h1>` per page, use a strict heading hierarchy (h1 → h2 → h3), add `alt` text to every `<img>`, and use sufficient colour contrast (≥ 4.5:1 for body text). Baking this in during authoring is faster than a post-hoc audit.
-9. **Run one accessibility audit at the end** — after all components are built and content is published, invoke `/jahia-dev-accessibility` once to catch any remaining violations. Do not audit after every individual component; it wastes time on pages that are not yet complete.
-10. **Batch builds and deploys** — build all components together, then run `yarn build && yarn jahia-deploy` once rather than after each individual component. Deploy once before populating content.
+7. **Use MCP tools for all Jahia operations — never GraphQL curl.** The `jahia` MCP server covers site, page, content, 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 (`<main>`, `<header>`, `<nav>`, `<footer>`, `<section>`, `<article>`), include exactly one `<h1>` per page (in the template from `jcr:title` — never inside a component), use a strict heading hierarchy (h1 in template → h2 in components → h3 for sub-items), add `alt` text to every `<img>` with a meaningful fallback (`imageAlt || title || 'Image'` — never empty string), ensure sufficient colour contrast (≥ 4.5:1 for body text), include a skip link at the top of the template, and never leave a landmark (`<nav>`, `<footer>`) empty.
+9. **Review quality after each deploy** — after deploying and populating content, run `/jahia-dev-site-review` to get a scored a11y + SEO report. Fix any critical/serious violations before moving on. Do not write `pages.json` until the review passes.
+10. **Deploy iteratively** — deploy after each component with `yarn build && yarn jahia-deploy`, verify it renders, then move to the next. Don't accumulate components before deploying; a broken component is easier to diagnose in isolation.
+11. **Collocate everything per component** — each component lives in `src/components/<Category>/<Name>/` containing its `definition.cnd`, `default.server.tsx`, `component.module.css`, and `types.ts`. Never centralize content types in `settings/definitions.cnd` — that file holds only namespace declarations and the module base mixin.
+12. **Always build a page template first** — every website needs a root template at `src/templates/<ModuleName>Template/default.server.tsx`. It must include: a skip link, a `<nav>` built inline from children of the site's home node using `getChildNodes(renderContext.getSite().getNode('home'), -1, 0, n => n.isNodeType('jnt:page'))` (pages live under `home`, not directly under the site), a `<main id="main-content">` with `<h1>{title}</h1>` and Areas, and a `<footer>` that is never empty. The `<title>` tag must be `{title} | {siteName}` — never set `jcr:title` to the full `Page | Site` string; `jcr:title` is always just the short page name (e.g. "Car Insurance"). Build and deploy before any page-specific components.
+13. **SEO baseline** — every page template must render a `<title>` tag, all `<img>` must have descriptive `alt` text, all links must have visible text (no icon-only links without `aria-label`), and pages must have a single `<h1>` matching the page title.
 
 ## Skill Map
 
@@ -39,11 +44,13 @@ Start with `/jahia` if unsure where to begin.
 | `/jahia-dev-start-local` | Start Jahia locally (Docker or bare metal) |
 | `/jahia-dev-build-component` | Build a complete component (CND + view) — start here |
 | `/jahia-dev-define-content-type` | Define a CND content type + types.ts |
+| `/jahia-dev-review-cnd` | Validate a CND file for antipatterns — run after writing any CND |
 | `/jahia-dev-create-view` | Implement a React view (.server.tsx + CSS Module) |
 | `/jahia-dev-create-page-template` | Create a page template with Areas |
 | `/jahia-dev-query-content` | Write JCR-SQL2 queries and useJCRQuery |
 | `/jahia-dev-review` | Code review: 8 critical checks, 9 warnings, 11 suggestions |
-| `/jahia-dev-accessibility` | Audit live pages with axe-core, fix WCAG 2.1 AA violations |
+| `/jahia-dev-site-review` | Scored a11y + SEO report on live pages — use after every deploy |
+| `/jahia-dev-accessibility` | Deep WCAG 2.1 AA audit with fixes — use for targeted a11y work |
 | `/jahia-dev-screenshot` | Screenshot reference + local render for visual comparison |
 | `/jahia-dev-debug` | Debug build/deploy/runtime errors end-to-end |
 

package/dist/copilot/.agents/skills/jahia/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: jahia
-description: Top-level entry point for ALL Jahia tasks. Detects whether the request is about building a module (dev) or managing content (CMS), and delegates to the right skill or combination. Start here if unsure which Jahia skill to use.
-allowed-tools: Bash, Read
+description: Top-level entry point for ALL Jahia tasks. Detects whether the request is about building a module (dev) or managing content (CMS via MCP tools), and delegates to the right skill or combination. Start here if unsure which Jahia skill to use.
 ---
 
 # Jahia — Universal Entry Point
 
 You are the top-level GPS for all Jahia work. Your job is to understand what the user wants to accomplish, then delegate to the right skill(s) — `/jahia-dev`, `/jahia-content`, or both in sequence.
 
+> **Content operations use MCP tools** via the `jahia` MCP server. Never call Jahia's GraphQL API directly for content creation, querying, or structure discovery — use the MCP tools instead.
+
 ---
 
 ## Step 1 — Classify the request
@@ -62,8 +63,8 @@ Use these recipes as starting points when the task maps to a known pattern.
 ```
 1. /jahia-dev-build-component       → define the content type + create the view
 2. /jahia-dev-create-page-template  → (if a new page layout is needed)
-3. /jahia-content-create-content    → populate the section with real or dummy content
-4. /jahia-content-move-content      → (if existing content needs to be reorganized)
+3. /jahia-content-create-content    → create the site if needed, then populate the section with content
+4. /jahia-content-organize          → (if existing content needs to be reorganized)
 ```
 
 ### "Add an article to the site"
@@ -71,7 +72,8 @@ Use these recipes as starting points when the task maps to a known pattern.
 1. Check the CND — does the article content type exist?
    → Yes: jump to step 2
    → No: /jahia-dev-define-content-type + /jahia-dev-create-view first
-2. /jahia-content-create-content    → create the article node + set properties + publish
+2. /jahia-content-create-content    → create the article node + set properties
+3. /jahia-content-publish           → publish it to LIVE
 ```
 
 ### "Redesign the layout of a page"
@@ -86,10 +88,15 @@ Use these recipes as starting points when the task maps to a known pattern.
 ```
 1. /jahia-dev-create-template-set   → scaffold the module
 2. /jahia-dev-start-local           → start Jahia locally
-3. /jahia-dev-build-component       → build content types + views (repeat per component)
+3. /jahia-dev-build-component       → build ONE component at a time (repeat this step per component):
+                                       - invokes /jahia-dev-define-content-type
+                                       - which invokes @jahia-cnd-author (sub-agent, mandatory)
+                                       - then invokes /jahia-dev-create-view
+                                       ⚠ Never batch-write CND — always go through @jahia-cnd-author
 4. /jahia-dev-create-page-template  → create page templates
-5. /jahia-content-create-content    → populate with articles, pages, folders
-6. /jahia-dev-review                → catch issues before shipping
+5. /jahia-content-create-content    → use `site.templateSets` + `site.create`, then add pages and content
+6. /jahia-content-publish           → publish the site content
+7. /jahia-dev-review                → catch issues before shipping
 ```
 
 ---
@@ -124,11 +131,16 @@ Always print this at the end so the user can jump anywhere:
 ### 📝 Content Management  (/jahia-content and sub-skills)
 /jahia-content                       Detect site state, route to content operations ← start here
 /jahia-content-explore-structure     Map content types, properties, enums & mixins on an unknown site
-/jahia-content-query-content         Query and audit content via GraphQL
-/jahia-content-create-content        Create nodes, folders, articles, bulk-populate
-/jahia-content-move-content          Restructure the content tree: move, rename, reorder
+/jahia-content-query-content         Query and audit content via MCP tools
+/jahia-content-create-content        Create sites, pages, nodes, folders, and articles
+/jahia-content-media-upload          Upload files and images into Jahia media storage
+/jahia-content-organize              Restructure the tree: move, copy, rename, reorder, delete
+/jahia-content-move-content          Focused move/reorder/delete workflow for an existing branch
+/jahia-content-translate-content     Translate i18n content and page titles
+/jahia-content-publish               Publish, unpublish, and inspect publication status
 ### 📚 Knowledge Reference
 /jahia-dev-java              OSGi DS, CND definitions, JSP rendering, Drools rules, Content Editor/jContent UI
+/jahia-jcr-sql2              JCR-SQL2 syntax, filtering, full-text, joins, and pagination guardrails
 /jahia-dev-apis              GraphQL, JCR Java/REST API, OAuth/SAML, personal tokens, HTML filtering, CSP
 /jahia-dev-ops               Docker Compose, Kubernetes, health monitoring, Karaf, provisioning YAML API
 /jahia-dev-properties        jahia.properties and OSGi .cfg configuration keys reference