@jahia/agentic 0.2.0 → 0.4.0

package/dist/gemini/.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/gemini/.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/gemini/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/gemini/GEMINI.md

@@ -1,6 +1,6 @@
 # GEMINI.md
 <!-- Generated by APM CLI -->
-<!-- Build ID: 87dc8219ce9b -->
-<!-- APM Version: 0.14.1 -->
+<!-- Build ID: 2ff1bbd97c77 -->
+<!-- APM Version: 0.21.0 -->
 
 @./AGENTS.md

package/dist/index.js

@@ -969,6 +969,19 @@ if (interactive && overwriteCount > 0) {
 } else if (overwriteCount > 0) R.warn(`Harness already exists, ${overwriteCount} file${overwriteCount >= 2 ? "s" : ""} will be overwritten.`);
 for (const dir of dirsToCreate) mkdirSync(dir, { recursive: true });
 for (const { src, dst } of filesToCopy) copyFileSync(src, dst);
+if (target === "claude" && !process.env.CI) {
+	R.step("Installing TypeScript LSP plugin for Claude Code…");
+	const pluginInstall = spawnSync("claude", [
+		"plugin",
+		"install",
+		"typescript-lsp@claude-plugins-official"
+	], {
+		encoding: "utf-8",
+		timeout: 15e3
+	});
+	if (pluginInstall.error || pluginInstall.status !== 0) R.warn(`Could not install TypeScript LSP plugin automatically.\nRun manually: ${styleText("blueBright", "claude plugin install typescript-lsp@claude-plugins-official")}`);
+	else R.success("TypeScript LSP plugin installed.");
+}
 ye(`Harness created successfully!
 
 To update the harness in the future, run ${styleText("blueBright", "npx @jahia/agentic@latest " + target)}`);

package/dist/opencode/.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

package/dist/opencode/.agents/skills/jahia-content/SKILL.md

@@ -1,139 +1,157 @@
 ---
 name: jahia-content
-description: Entry point for managing content on a running Jahia website via the GraphQL API. Detects the current site state and routes to the right sub-skill. Use for any task involving creating, querying, moving, updating, or publishing JCR content.
+description: Entry point for creating sites, authoring pages, querying content, reorganizing nodes, uploading media, translating, and publishing a Jahia website via MCP tools.
 ---
 
 # Jahia Content — Content Management GPS
 
-You are the entry point for managing content on a live Jahia instance. Your job is to understand what the user needs, assess the current site state, and route to the right sub-skill.
+You are the entry point for content work on a live Jahia instance. Understand the request, assess the site state, and route to the right content skill.
+
+> **Never call Jahia's GraphQL API directly for content operations.** Use only MCP tools via the `jahia` MCP server. If a capability is missing, report it — do not work around with curl/GraphQL.
 
 ---
 
-## Step 1 — Verify Jahia is reachable
+## Step 1 — Verify the MCP connection
+
+Confirm the `jahia` MCP server is available:
 
-```bash
-curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/cms/login
+```
+tool: site.list
 ```
 
-- `200` → Jahia is running ✅
-- Anything else → Jahia is not running. Tell the user: **"Please start Jahia first (use `/jahia-dev-start-local` if needed)."**
+If this fails, Jahia or the MCP connection is not ready.
 
 ---
 
-## Step 2 — Detect site state
+## Step 2 — Detect the site state
 
-Run both checks in parallel to understand what's currently in the CMS:
+Run these checks to understand what exists already:
 
 ### A. List available sites
-```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\") { children { nodes { name } } } } }"}'
+
+```
+tool: site.list
 ```
 
-### B. List top-level content folders
-```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/mySite/contents\") { children { nodes { name primaryNodeType { name } } } } } }"}'
+### B. Discover installed template sets for new site creation
+
+```
+tool: site.templateSets
+args: {}
 ```
 
-> Replace `mySite` with the actual site key if different.
+### C. If a site exists, list its pages
+
+```
+tool: page.list
+args: { "siteKey": "SITE_KEY" }
+```
 
 ---
 
-## Step 3 — Report site state
+## Step 3 — Report the CMS state
+
+Summarize what you found:
 
 ```
-🌐 Jahia:          ✅ running at http://localhost:8080
-📁 Sites:          <list site keys>
-📂 Content root:   <list folder names under /contents>
+🌐 Jahia MCP:       ✅ connected
+📁 Sites:           <site keys>
+🧱 Template sets:   <installed template sets>
+📄 Pages:           <page titles and templates for the chosen site>
 ```
 
 ---
 
 ## Step 4 — Route to the right sub-skill
 
-Use the task description to pick the right skill(s):
-
-| What the user wants to do | Skill |
-|---------------------------|-------|
-| Explore an unknown site's content types, property names, enum values, mixins | **`/jahia-content-explore-structure`** |
-| Find out what content exists, audit the tree, run a search | **`/jahia-content-query-content`** |
-| Create pages, articles, tutorials, folders, populate a site | **`/jahia-content-create-content`** |
-| Move, rename, restructure content into sub-folders | **`/jahia-content-move-content`** |
-| Translate existing content to another language | **`/jahia-content-translate-content`** |
-| Publish content to the live site | Use `publish` mutation (see below) |
-| Delete content | Use `deleteNode` mutation (see below) |
-| Do several of the above in sequence | Run the skills in order — start with **explore-structure** if site is unfamiliar, then create or move |
+| User intent | Skill |
+|-------------|-------|
+| Explore an unknown site, map areas, inspect types and properties | `/jahia-content-explore-structure` |
+| Create a brand-new site before authoring content | `/jahia-content-create-content` using `site.templateSets` and `site.create` |
+| Create pages, content, or structured trees on an existing site | `/jahia-content-create-content` |
+| Upload files and images to `/sites/<siteKey>/files` | `/jahia-content-media-upload` |
+| Find, inspect, or audit existing content | `/jahia-content-query-content` |
+| Move, copy, rename, reorder, or delete content | `/jahia-content-organize` |
+| Translate content to another locale | `/jahia-content-translate-content` |
+| Publish, unpublish, or check readiness | `/jahia-content-publish` |
+| Do several of the above in sequence | Start with `/jahia-content-explore-structure` if the site is unfamiliar |
 
 ---
 
-## Step 5 — Direct patterns for one-off operations
+## Direct MCP patterns
 
-Use these when the task is simple enough to not need a full sub-skill.
+### Create a site before authoring pages
 
-### Publish a node (and all its children)
-```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":"mutation { jcr { mutateNode(pathOrId: \"/sites/mySite/contents/articles\") { publish(languages: [\"en\"]) } } }"}'
 ```
+tool: site.templateSets
+args: {}
+
+tool: site.create
+args: {
+  "siteKey": "brandSite",
+  "title": "Brand Site",
+  "templateSet": "digitall",
+  "defaultLanguage": "en",
+  "languages": ["en", "fr"],
+  "serverName": "brand.local"
+}
+```
+
+### Publish a page or subtree
 
-### Publish all content at once
-```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":"mutation { jcr { mutateNodesByQuery(query: \"SELECT * FROM [jnt:content] WHERE ISDESCENDANTNODE(\u0027/sites/mySite/contents\u0027)\", queryLanguage: SQL2) { publish(languages: [\"en\"]) } } }"}'
 ```
+tool: publication.publish
+args: {
+  "path": "/sites/SITE_KEY/home/about",
+  "languages": ["en"]
+}
+```
+
+### Unpublish a page or subtree
 
-### Delete a node
-```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":"mutation { jcr { mutateNode(pathOrId: \"/sites/mySite/contents/articles/old-article\") { delete } } }"}'
+```
+tool: publication.unpublish
+args: {
+  "path": "/sites/SITE_KEY/home/about",
+  "languages": ["en"]
+}
 ```
 
-### Update a property on an existing node
-```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":"mutation { jcr { mutateNode(pathOrId: \"/sites/mySite/contents/articles/my-article\") { mutateProperty(name: \"jcr:title\") { setValue(language: \"en\", value: \"Updated Title\") } } } }"}'
+### Delete a published node correctly
+
+```
+tool: content.markForDeletion
+args: { "path": "/sites/SITE_KEY/home/old-page" }
+
+tool: publication.publish
+args: {
+  "path": "/sites/SITE_KEY/home/old-page",
+  "languages": ["en"]
+}
 ```
 
 ---
 
-## Step 6 — Print the full CMS skill map
-
-Always print this at the end so the user can navigate anywhere:
+## Full skill map
 
 ```
-## Jahia Content Skills
-
-/jahia-content-explore-structure    Map content types, properties, enums, mixins on an unknown site ← start here
-/jahia-content-query-content        List, inspect, and search content via GraphQL
-/jahia-content-create-content       Create nodes, folders, articles, and bulk-populate a site
-/jahia-content-move-content         Restructure the content tree: move, rename, reorder nodes
-/jahia-content-translate-content    Translate existing nodes to a new language and publish
+/jahia-content-explore-structure   Map sites, template sets, pages, areas, and content definitions
+/jahia-content-create-content      Create sites, pages, content nodes, and structured trees
+/jahia-content-media-upload        Upload media and reference it from content
+/jahia-content-query-content       List, inspect, and search content via MCP tools
+/jahia-content-organize            Move, copy, rename, reorder, mark for deletion, and delete content
+/jahia-content-move-content        Focused move/reorder/delete workflow for an existing content tree
+/jahia-content-translate-content   Translate i18n content and page titles
+/jahia-content-publish             Check publication status, publish, unpublish, and handle workflow
 ```
 
 ---
 
-## Critical rules (always enforce)
+## Critical rules
+
+- Always use MCP tools — never GraphQL directly
+- Use `site.templateSets` and `site.create` when the requested site does not exist yet
+- Always pass `locale` to content creation and update calls
+- Always publish after creating, moving, deleting, or translating content
+- Always explore with `/jahia-content-explore-structure` before authoring on an unfamiliar site
 
-- Always include `-H "Origin: http://localhost:8080"` in every curl — omitting it causes `Permission denied`
-- Always use `language: "en"` (or the site's language) for `i18n` properties (`jcr:title` on folders with `mix:title`, richtext body, etc.)
-- Always publish after creating or moving content — JCR writes to the **default workspace** only; live visitors see the **live workspace**
-- Mandatory fields (e.g. `body`) must be set **before** other properties on the same node in a new locale