@jahia/agentic 0.3.0 → 0.4.0

package/dist/copilot/.agents/skills/jahia-dev-review-cnd/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: jahia-dev-review-cnd
+description: Use after writing any CND file to validate it against Jahia best practices. Runs the deterministic cnd-checker script and reports PASS / FAIL with file:line citations and fixes. Run /jahia-dev-review-cnd <path> to check a specific file or directory, or without arguments to check all CND files in the current module.
+allowed-tools: Bash
+---
+
+## Step 1 — Run the checker
+
+```bash
+CND_SCRIPT=$(find .claude .agents -name "check-cnd.mjs" 2>/dev/null | head -1)
+node "$CND_SCRIPT" <path-to-file-or-directory>
+# or, to check all CND files in the module:
+node "$CND_SCRIPT" src/
+```
+
+The script exits with code 0 for PASS and code 1 for FAIL.
+
+## Step 2 — Fix and repeat until clean
+
+This is a loop. Run the checker, fix every issue reported, run it again. Repeat until the result is `PASS`.
+
+- **FAIL** — fix every issue, re-run. Do not proceed until exit code is 0.
+- **PASS** — clean. Continue.
+
+---
+
+## Antipattern reference
+
+The checker enforces these patterns. Use this as a guide when interpreting output or fixing issues manually.
+
+### `rawStringLink`
+Property whose name contains `link`, `url`, `href`, or `path` declared as `(string)`.
+**Fix**: Use the link picker:
+```cnd
+- j:linkType (string, choicelist[linkTypeInitializer]) mandatory
+```
+
+### `singleHardcodedCta`
+A type with both a CTA label (`ctaText`, `ctaLabel`, `buttonText`, `buttonLabel`) and a CTA link (`ctaLink`, `ctaUrl`, `ctaHref`, `buttonLink`) as flat properties, with no child node.
+**Fix**: Replace with a child node:
+```cnd
++ * (ns:cta)
+
+[ns:cta] > jnt:content, nsmix:component
+ - label (string) i18n mandatory
+ - j:linkType (string, choicelist[linkTypeInitializer]) mandatory
+```
+
+### `directDroppable`
+A concrete type extending `jmix:droppableContent` directly.
+**Fix**: Extend the module mixin: `[ns:hero] > jnt:content, nsmix:component`
+
+### `missingRatingConstraint`
+`rating (long)` without a range constraint — unconstrained ratings cause data integrity issues.
+**Fix**: Add `< "[1,5]"`
+
+### `redundantImageAlt`
+`imageAlt (string)` alongside an image weakreference. The image node already has `jcr:title`.
+**Fix**: Remove `imageAlt`. In the view: `image.getPropertyAsString("jcr:title") ?? ""`
+
+### `rawTitleProp`
+Property named `title`, `heroTitle`, `pageTitle`, or `sectionTitle` typed as `(string)`.
+**Fix**: Remove it, extend `mix:title`. Access as `props["jcr:title"]`.
+
+### `weakrefNoConstraint`
+`(weakreference)` with no `< ` type constraint.
+**Fix**: Add constraint — `< jmix:image` for images, `< jnt:file` for files.
+
+### `weakrefWrongConstraint`
+`< 'jnt:file'` (quoted form).
+**Fix**: `< jmix:image` (unquoted).
+
+### `missingI18n`
+User-visible string (`title`, `text`, `label`, `description`, `subtitle`, `caption`, `alt`, `heading`, `summary`, `excerpt`, `body`) without `i18n`.
+**Fix**: Add `i18n` after the type declaration.
+
+### `studioOnly`
+Any use of `jmix:studioOnly`.
+**Fix**: Replace with `jmix:hiddenType`.

package/dist/copilot/.agents/skills/jahia-dev-review-cnd/scripts/check-cnd.d.mts

@@ -0,0 +1,13 @@
+export interface CndIssue {
+  file: string;
+  line?: number;
+  pattern: string;
+  message: string;
+  fix: string;
+}
+
+export function checkCndFiles(projectDir: string): {
+  score: number;
+  issues: CndIssue[];
+  filesChecked: number;
+};

package/dist/copilot/.agents/skills/jahia-dev-review-cnd/scripts/check-cnd.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+function findCndFiles(dir) {
+  const results = [];
+  function walk(current) {
+    try {
+      const stat = statSync(current);
+      if (stat.isFile()) {
+        if (current.endsWith(".cnd")) results.push(current);
+        return;
+      }
+      for (const entry of readdirSync(current, { withFileTypes: true })) {
+        if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== ".git") {
+          walk(join(current, entry.name));
+        } else if (entry.isFile() && entry.name.endsWith(".cnd")) {
+          results.push(join(current, entry.name));
+        }
+      }
+    } catch {
+      // skip unreadable paths
+    }
+  }
+  walk(dir);
+  return results;
+}
+
+function checkFile(filePath, content) {
+  const issues = [];
+  const lines = content.split("\n");
+
+  lines.forEach((line, i) => {
+    const lineNum = i + 1;
+    const trimmed = line.trim();
+    if (trimmed.startsWith("//") || trimmed.startsWith("<")) return;
+
+    // rawStringLink
+    if (
+      /^-\s+\w*(Url|Href|Link)\s+\(string[,)]/i.test(trimmed) &&
+      !/choicelist\[linkTypeInitializer\]/.test(trimmed)
+    ) {
+      const propName = trimmed.match(/^-\s+(\w+)/)?.[1] ?? "unknown";
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "rawStringLink",
+        message: `"${propName}" uses (string) for a link/url — use choicelist[linkTypeInitializer]`,
+        fix: "Replace with: - j:linkType (string, choicelist[linkTypeInitializer]) mandatory",
+      });
+    }
+
+    // rawTitleProp
+    if (/^-\s+(title|heroTitle|pageTitle|sectionTitle)\s+\(string[,)]/i.test(trimmed)) {
+      const propName = trimmed.match(/^-\s+(\w+)/)?.[1] ?? "unknown";
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "rawTitleProp",
+        message: `"${propName}" is a plain string — extend mix:title instead`,
+        fix: "Add mix:title to the type declaration and remove this property",
+      });
+    }
+
+    // weakrefNoConstraint: (weakreference) with no < constraint on same line
+    if (/\(weakreference[,)]/.test(trimmed) && !/<\s*\S/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "weakrefNoConstraint",
+        message: "Unconstrained weakreference — add a type constraint",
+        fix: "Add e.g. (weakreference, picker[type='image']) < jmix:image",
+      });
+    }
+
+    // weakrefWrongConstraint
+    if (/< ['"]jnt:file['"]/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "weakrefWrongConstraint",
+        message: "< 'jnt:file' (quoted) does not enforce image type",
+        fix: "Replace with < jmix:image for images",
+      });
+    }
+
+    // missingI18n: user-visible string without i18n
+    if (
+      /^-\s+\w+\s+\(string(,\s*(textarea|richtext))?[,)]/.test(trimmed) &&
+      !/ i18n/.test(trimmed) &&
+      !/^-\s+j:/.test(trimmed) &&
+      /(title|text|label|description|subtitle|caption|alt|heading|summary|excerpt|body)/i.test(trimmed)
+    ) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "missingI18n",
+        message: "User-visible string property missing i18n",
+        fix: "Add i18n keyword after the type declaration",
+      });
+    }
+
+    // directDroppable: concrete type (not mixin) extending jmix:droppableContent
+    if (trimmed.startsWith("[") && /jmix:droppableContent/.test(trimmed) && !/\bmixin\b/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "directDroppable",
+        message: "Extends jmix:droppableContent directly — always extend the module component mixin",
+        fix: "Replace jmix:droppableContent with nsmix:component (or your module's equivalent)",
+      });
+    }
+
+    // studioOnly
+    if (/jmix:studioOnly/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "studioOnly",
+        message: "jmix:studioOnly causes silent rendering issues",
+        fix: "Replace with jmix:hiddenType",
+      });
+    }
+
+    // redundantImageAlt: imageAlt as plain string — image node already has jcr:title
+    if (/^-\s+imageAlt\s+\(string[,)]/i.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "redundantImageAlt",
+        message: '"imageAlt" is redundant — the image node\'s jcr:title (mix:title) serves as alt text',
+        fix: 'Remove imageAlt. In the view, use image.getPropertyAsString("jcr:title") for alt text',
+      });
+    }
+
+    // missingRatingConstraint: rating (long) without a range constraint
+    if (/^-\s+rating\s+\(long[,)]/i.test(trimmed) && !/<\s*"?\[/.test(trimmed)) {
+      issues.push({
+        file: filePath, line: lineNum,
+        pattern: "missingRatingConstraint",
+        message: '"rating" (long) has no range constraint — unconstrained ratings cause data integrity issues',
+        fix: 'Add: < "[1,5]"',
+      });
+    }
+  });
+
+  // singleHardcodedCta: check whole-file type blocks
+  const typeBlocks = content.split(/(?=^\[)/m);
+  for (const block of typeBlocks) {
+    if (!block.trim().startsWith("[")) continue;
+    const hasCtaLabel = /^\s*-\s+cta(Text|Label|ButtonText|ButtonLabel)\s+\(/im.test(block);
+    const hasCtaLink = /^\s*-\s+cta(Link|Url|Href|ButtonLink|ButtonUrl)\s+\(/im.test(block);
+    const hasChildNodes = /^\s*\+\s+/.test(block);
+    if (hasCtaLabel && hasCtaLink && !hasChildNodes) {
+      const typeName = block.match(/^\[(\S+)\]/m)?.[1] ?? "unknown";
+      const typeLineIdx = lines.findIndex((l) => l.includes(`[${typeName}]`));
+      issues.push({
+        file: filePath,
+        ...(typeLineIdx >= 0 ? { line: typeLineIdx + 1 } : {}),
+        pattern: "singleHardcodedCta",
+        message: `${typeName}: flat ctaText+ctaLink forces a single CTA — model as child nodes`,
+        fix: "Remove ctaText and ctaLink. Add: + * (ns:cta). Create a [ns:cta] type with label + j:linkType",
+      });
+    }
+  }
+
+  return issues;
+}
+
+export function checkCndFiles(projectDir) {
+  const files = findCndFiles(projectDir);
+  const allIssues = [];
+
+  for (const file of files) {
+    try {
+      const content = readFileSync(file, "utf-8");
+      allIssues.push(...checkFile(file, content));
+    } catch {
+      // skip unreadable files
+    }
+  }
+
+  return { score: Math.exp(-allIssues.length * 0.5), issues: allIssues, filesChecked: files.length };
+}
+
+if (import.meta.main) {
+  const targetPath = resolve(process.argv[2] ?? ".");
+  const { score, issues, filesChecked } = checkCndFiles(targetPath);
+
+  console.log(`\nCND Review: ${filesChecked} file${filesChecked !== 1 ? "s" : ""} checked\n`);
+
+  if (issues.length > 0) {
+    console.log(`ISSUES (${issues.length}):`);
+    for (const issue of issues) {
+      const loc = issue.line ? `${issue.file}:${issue.line}` : issue.file;
+      console.log(`  [${issue.pattern}] ${loc}`);
+      console.log(`    ${issue.message}`);
+      console.log(`    Fix: ${issue.fix}`);
+    }
+    console.log();
+  }
+
+  const verdict = issues.length > 0 ? "FAIL" : "PASS";
+  console.log(`Result: ${verdict} (score=${score.toFixed(2)})`);
+  process.exit(issues.length > 0 ? 1 : 0);
+}

package/dist/copilot/.agents/skills/jahia-dev-site-review/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: jahia-dev-site-review
+description: Scores live pages for accessibility (WCAG 2.1 AA via axe-core) and SEO (title, meta description, h1, alt). Use after deploying to get a pass/fail signal with per-violation detail before completing development.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# Skill: jahia-dev-site-review
+
+Runs automated a11y and SEO checks against every URL in `pages.json`. Reports a numeric score per page, lists violations by severity, and exits non-zero on any critical/serious a11y violation or missing SEO baseline.
+
+**A11y scoring:** `Math.exp(-Σ impact_weights)` where `critical=1, serious=0.5, moderate=0.25, minor=0.1`. Score of 1.0 = perfect; 0.607 = one serious violation.
+
+---
+
+## Step 1 — Ensure tooling is installed
+
+```bash
+node -e "require('@axe-core/playwright'); require('playwright')" 2>/dev/null || \
+  npm install --no-save @axe-core/playwright playwright && npx playwright install chromium --with-deps
+```
+
+---
+
+## Step 2 — Run the review
+
+```bash
+SCRIPT=$(find .claude .agents -name "review-pages.mjs" 2>/dev/null | head -1)
+node "$SCRIPT" 2>&1 | tee /tmp/site-review.txt
+```
+
+---
+
+## Step 3 — Interpret and fix
+
+The script exits 1 if any page has:
+- A `🔴 [critical]` or `🔴 [serious]` a11y violation
+- A `🔍 SEO` issue (missing title, meta description, h1, or img alt)
+
+`🟡 [moderate]` and `🟡 [minor]` violations are reported but do not fail the run — fix them for a higher score.
+
+**Common violations and where to fix them:**
+
+| Violation | Fix location |
+|---|---|
+| `landmark-*` empty nav or footer | Page template — ensure `<nav>` has inline content, `<footer>` has fallback text |
+| `page-has-heading-one` | Page template — add `<h1>{title}</h1>` |
+| `image-alt` | Component `.server.tsx` — use `imageAlt \|\| title \|\| 'Image'` |
+| `color-contrast` | Component `.module.css` — check foreground/background ratio ≥ 4.5:1 |
+| `heading-order` | Component — components start at `<h2>`, sub-items at `<h3>` |
+| Missing `<title>` | Page template `<head>` |
+| Missing meta description | Page template `<head>` — add `<meta name="description" content={…} />` |
+| Multiple `<h1>` | Remove `<h1>` from components; only the template renders one |
+
+After fixing, redeploy and re-run:
+
+```bash
+yarn build && yarn jahia-deploy
+node "$SCRIPT"
+```
+
+Iterate until the script exits 0.
+
+---
+
+## Validation checklist
+- [ ] Script exits 0 (no critical/serious violations, no SEO issues)
+- [ ] Average a11y score ≥ 0.8
+- [ ] Every page has a unique, non-empty `<title>`
+- [ ] Every page has `<meta name="description">`
+- [ ] Every page has exactly one `<h1>`

package/dist/copilot/.agents/skills/jahia-dev-site-review/scripts/review-pages.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Runs a11y (axe-core) + SEO checks on every URL in pages.json.
+// Exits 1 if any page has critical/serious a11y violations or missing SEO basics.
+import { chromium } from "playwright";
+import { AxeBuilder } from "@axe-core/playwright";
+import { readFileSync } from "fs";
+
+const IMPACTS = { minor: 0.1, moderate: 0.25, serious: 0.5, critical: 1 };
+
+const urls = JSON.parse(readFileSync("pages.json", "utf-8"));
+const browser = await chromium.launch({ args: ["--no-sandbox"] });
+const context = await browser.newContext();
+const page = await context.newPage();
+
+const results = [];
+
+for (const url of urls) {
+  process.stdout.write(`\nChecking ${url} … `);
+  await page.goto(url, { waitUntil: "networkidle", timeout: 30_000 });
+
+  // A11y
+  const axe = await new AxeBuilder({ page })
+    .withTags(["wcag2a", "wcag2aa", "wcag21aa"])
+    .analyze();
+
+  const a11yScore = Math.exp(
+    -axe.violations.reduce((t, v) => t + (IMPACTS[v.impact] ?? 0), 0),
+  );
+
+  // SEO
+  const title = await page.title();
+  const metaDesc = await page
+    .$eval('meta[name="description"]', el => el.getAttribute("content"))
+    .catch(() => null);
+  const h1s = await page.$$eval("h1", els => els.map(e => e.textContent?.trim()));
+  const imgsMissingAlt = await page.$$eval(
+    "img",
+    els => els.filter(e => !e.getAttribute("alt")).map(e => e.outerHTML.slice(0, 80)),
+  );
+
+  const seoIssues = [];
+  if (!title) seoIssues.push("missing <title>");
+  if (!metaDesc) seoIssues.push("missing <meta name=description>");
+  if (h1s.length === 0) seoIssues.push("no <h1>");
+  if (h1s.length > 1) seoIssues.push(`${h1s.length} <h1> elements (must be exactly 1)`);
+  if (imgsMissingAlt.length > 0)
+    seoIssues.push(`${imgsMissingAlt.length} <img> missing alt attribute`);
+
+  process.stdout.write(`a11y=${a11yScore.toFixed(3)}\n`);
+  results.push({ url, a11yScore, violations: axe.violations, seoIssues });
+}
+
+await browser.close();
+
+// ── Report ──────────────────────────────────────────────────────────────────
+let failed = false;
+
+for (const r of results) {
+  const critical = r.violations.filter(v => v.impact === "critical" || v.impact === "serious");
+  const pageOk = critical.length === 0 && r.seoIssues.length === 0;
+  if (!pageOk) failed = true;
+
+  console.log(`\n${"─".repeat(70)}`);
+  console.log(`${pageOk ? "✅" : "❌"} ${r.url}`);
+  console.log(`   A11y score : ${r.a11yScore.toFixed(3)}  (1.0 = perfect)`);
+
+  for (const v of r.violations) {
+    const marker = v.impact === "critical" || v.impact === "serious" ? "🔴" : "🟡";
+    console.log(`   ${marker} [${v.impact}] ${v.id} — ${v.description} (${v.nodes.length} node${v.nodes.length !== 1 ? "s" : ""})`);
+    for (const node of v.nodes.slice(0, 3)) {
+      console.log(`        ${node.html.slice(0, 100)}`);
+    }
+  }
+
+  for (const issue of r.seoIssues) {
+    console.log(`   🔍 SEO: ${issue}`);
+  }
+}
+
+console.log(`\n${"═".repeat(70)}`);
+const avg = results.reduce((t, r) => t + r.a11yScore, 0) / results.length;
+console.log(`Average a11y score: ${avg.toFixed(3)}`);
+console.log(failed ? "\n❌ FAIL — fix the issues above, redeploy, and re-run." : "\n✅ PASS");
+
+process.exit(failed ? 1 : 0);

package/dist/copilot/.agents/skills/jahia-dev-start-local/SKILL.md

@@ -79,36 +79,28 @@ Follow the instructions on that page for the user's platform, then return here t
 
 ## Step 4 — Create a new site in Jahia
 
-Once the module is deployed to Jahia, create the site via the Provisioning API — **do not use the UI**.
+Once the module is deployed to Jahia, create the site via MCP:
 
-> ⚠️ **CRITICAL: syntax is `- createSite: ""`** — the empty string `""` after the colon is **mandatory**. Without it, Jahia returns HTTP 200 but silently creates nothing. Using `- createSite:` with nested properties is **wrong and will fail silently**.
-
-```bash
-MODULE_NAME=<module-name>   # value of "name" in package.json
-
-cat > /tmp/create-site.yaml <<EOF
-- createSite: ""
-  siteKey: ${MODULE_NAME}
-  title: "My Site"
-  defaultLanguage: en
-  serverName: localhost
-  templateSet: ${MODULE_NAME}
-EOF
-
-curl -u root:root1234 -X POST -H "Content-Type: application/yaml" \
-  --data-binary @/tmp/create-site.yaml \
-  http://localhost:8080/modules/api/provisioning
 ```
+tool: site.create
+args: {
+  "siteKey": "<module-name>",
+  "title": "My Site",
+  "templateSet": "<module-name>",
+  "defaultLanguage": "en",
+  "serverName": "localhost"
+}
+```
+
+Replace `<module-name>` with the `name` from `package.json`. `templateSet` must exactly match the deployed module name.
 
 Verify the site exists:
-```bash
-curl -s -u root:root1234 \
-  -H "Content-Type: application/json" -H "Origin: http://localhost:8080" \
-  -X POST http://localhost:8080/modules/graphql \
-  -d "{\"query\":\"{ jcr { nodeByPath(path:\\\"/sites/${MODULE_NAME}\\\") { name } } }\"}"
+
+```
+tool: site.list
 ```
 
-The response must contain `"name": "<module-name>"`. If it returns `null`, the site was not created — check that `templateSet` exactly matches the deployed module name.
+The site key must appear in the response. If it does not, check that `templateSet` exactly matches the deployed module name.
 
 Then open **Page Builder** at http://localhost:8080/jahia/page-builder to start building.
 
@@ -119,8 +111,8 @@ Then open **Page Builder** at http://localhost:8080/jahia/page-builder to start
 - [ ] `docker compose up --wait` completes without errors (Docker path)
 - [ ] Jahia UI is reachable at http://localhost:8080
 - [ ] Module deployed to Jahia (`yarn build && yarn jahia-deploy` run; or `yarn dev` in user terminal for interactive development)
-- [ ] Site created via Provisioning API (`createSite: ""` with correct templateSet)
-- [ ] GraphQL confirms `/sites/<site-key>` node exists
+- [ ] Site created via `site.create` MCP tool with correct `templateSet`
+- [ ] `site.list` confirms site key exists
 
 ## Troubleshooting
 

package/dist/copilot/.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>
+```