@jahia/agentic 0.0.0

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

@@ -0,0 +1,136 @@
+---
+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
+---
+
+# 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.
+
+---
+
+## Step 1 — Classify the request
+
+Read the user's request and classify it using the table below. A task can span multiple categories.
+
+| Category | Keywords / intent | Skill |
+|----------|-------------------|-------|
+| **Module development** | create module, scaffold, content type, CND, view, React, TSX, page template, CSS, build, deploy, compile | `/jahia-dev` |
+| **Personalization / analytics** | jExperience, jCustomer, window.wem, visitor events, Kibana dashboard, personalization, DXP | `/jahia-dev-jexperience` |
+| **Content management** | create content, add article, populate, move, reorganize, publish, query what's in the CMS | `/jahia-content` |
+| **OSGi / back-office** | Java bundle, OSGi service, jcontent action, admin panel, toolbar button, Webpack, Module Federation | `/jahia-dev-osgi-module` or `/jahia-dev-ui-extension` |
+| **E2E testing** | Cypress, test spec, edit mode, component interaction, publish workflow | `/jahia-dev-cypress` |
+| **Java module reference** | OSGi DS, CND definitions, JSP rendering, Drools rules, JCR SQL2, Content Editor JSON, component registry | `/jahia-dev-java` |
+| **API reference** | GraphQL schema, JCR Java/REST API, OAuth/SAML auth, personal tokens, HTML filtering, CSP, security scopes | `/jahia-dev-apis` |
+| **Operations / DevOps** | Docker Compose, Kubernetes, health endpoints, logs, Karaf, provisioning YAML scripts | `/jahia-dev-ops` |
+| **Configuration reference** | jahia.properties keys, cluster setup, operating mode, auth settings, JCR/search tuning | `/jahia-dev-properties` |
+| **Both** | build a component AND fill it with content, design a section AND add pages to it, set up a site end-to-end | Run `/jahia-dev` first, then `/jahia-content` |
+
+If the request is ambiguous, ask one clarifying question:
+> "Are you building or changing **code** (module, views, templates) — or managing **content** (articles, pages, folders) inside a running Jahia site?"
+
+---
+
+## Step 2 — Run the right GPS(es)
+
+### Dev only → invoke `/jahia-dev`
+`/jahia-dev` will detect the project state and route to the correct dev sub-skill.
+
+### CMS only → invoke `/jahia-content`
+`/jahia-content` will check the live site and route to the right content management sub-skill.
+
+### Both → run in order
+
+When a task requires code changes **and** content changes, always execute in this order:
+
+```
+1. /jahia-dev                        ← build/update the module code
+2. yarn build && yarn jahia-deploy   ← push the updated module to Jahia (never use yarn dev)
+3. /jahia-content                    ← populate or reorganize content
+```
+
+Rationale: content types must exist in the CMS before you can create nodes of those types.
+
+---
+
+## Step 3 — Common compound workflows
+
+Use these recipes as starting points when the task maps to a known pattern.
+
+### "Build a new section on the site"
+```
+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)
+```
+
+### "Add an article to the site"
+```
+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
+```
+
+### "Redesign the layout of a page"
+```
+1. /jahia-dev-screenshot       → capture current state for before/after comparison
+2. /jahia-dev-create-view      → update the view / CSS
+3. yarn build && yarn jahia-deploy  → push changes (never use yarn dev)
+4. /jahia-dev-screenshot       → validate the result
+```
+
+### "Set up a new site from scratch"
+```
+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)
+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
+```
+
+---
+
+## Step 4 — Print the full skill map
+
+Always print this at the end so the user can jump anywhere:
+
+```
+## All Jahia Skills
+
+### 🏗 Development  (/jahia-dev and sub-skills)
+/jahia-dev                       Detect project state, guide to next step ← start here
+/jahia-dev-create-template-set   Scaffold a new JS/React Jahia module
+/jahia-dev-start-local           Start Jahia locally (Docker or bare metal)
+/jahia-dev-build-component       Build a complete component (CND + view) ← shortcut
+/jahia-dev-define-content-type   Define a CND content type + types.ts
+/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 / useJCRQuery for content listings
+/jahia-dev-review                Code review: 8 critical checks, 9 warnings, 10 suggestions
+/jahia-dev-screenshot            Screenshot reference + local render for visual comparison
+/jahia-dev-debug                 Debug build/deploy/runtime errors end-to-end
+/jahia-dev-cypress               Write Cypress E2E tests for Jahia components
+/jahia-dev-import-from           Implement a component inspired by one on an external URL
+/jahia-dev-jexperience           jExperience + jCustomer: push events, Kibana dashboards, local DXP stack
+
+### ⚙️ OSGi / Back-office extensions
+/jahia-dev-osgi-module           Build or configure an OSGi Java bundle module
+/jahia-dev-ui-extension     Extend jcontent back-office with React 18/Webpack actions or panels
+
+### 📝 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
+### 📚 Knowledge Reference
+/jahia-dev-java              OSGi DS, CND definitions, JSP rendering, Drools rules, Content Editor/jContent UI
+/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/copilot/.agents/skills/jahia-content/SKILL.md

@@ -0,0 +1,139 @@
+---
+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.
+---
+
+# 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.
+
+---
+
+## Step 1 — Verify Jahia is reachable
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/cms/login
+```
+
+- `200` → Jahia is running ✅
+- Anything else → Jahia is not running. Tell the user: **"Please start Jahia first (use `/jahia-dev-start-local` if needed)."**
+
+---
+
+## Step 2 — Detect site state
+
+Run both checks in parallel to understand what's currently in the CMS:
+
+### 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 } } } } }"}'
+```
+
+### 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 } } } } } }"}'
+```
+
+> Replace `mySite` with the actual site key if different.
+
+---
+
+## Step 3 — Report site state
+
+```
+🌐 Jahia:          ✅ running at http://localhost:8080
+📁 Sites:          <list site keys>
+📂 Content root:   <list folder names under /contents>
+```
+
+---
+
+## 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 |
+
+---
+
+## Step 5 — Direct patterns for one-off operations
+
+Use these when the task is simple enough to not need a full sub-skill.
+
+### 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\"]) } } }"}'
+```
+
+### 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\"]) } } }"}'
+```
+
+### 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 } } }"}'
+```
+
+### 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\") } } } }"}'
+```
+
+---
+
+## Step 6 — Print the full CMS skill map
+
+Always print this at the end so the user can navigate anywhere:
+
+```
+## 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
+```
+
+---
+
+## Critical rules (always enforce)
+
+- 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

package/dist/copilot/.agents/skills/jahia-content-create-content/SKILL.md

@@ -0,0 +1,384 @@
+---
+name: jahia-content-create-content
+description: Creates and publishes JCR content nodes in a running Jahia instance via the GraphQL API. Use when asked to populate a site with content, create articles, tutorials, or any JCR node programmatically.
+---
+
+# Skill: jahia-content-create-content
+
+Creates content nodes in a running Jahia instance using the GraphQL JCR mutation API, then publishes them.
+
+---
+
+## Prerequisites
+
+- Jahia running at `http://localhost:8080`
+- Credentials: `root` / `root1234` (default)
+- GraphQL endpoint: `http://localhost:8080/modules/graphql`
+
+**Auth pattern — always use both flags:**
+```bash
+curl -u root:root1234 \
+     -H "Content-Type: application/json" \
+     -H "Origin: http://localhost:8080" \
+     ...
+```
+
+> ⚠️ The `Origin: http://localhost:8080` header is **required**. Requests without it return `Permission denied` even with correct credentials.
+
+---
+
+## ⚡ Minimum-call workflow
+
+Use these patterns to minimise the number of API round-trips:
+
+### 1. Batch site exploration — one call instead of four
+
+Use GraphQL aliases to retrieve site metadata, page structure, files, and available content types in a **single request**:
+
+```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 { site: nodeByPath(path: \"/sites/SITE_KEY\") { properties(names: [\"j:templatesSet\",\"j:defaultLanguage\"]) { name value } } home: nodeByPath(path: \"/sites/SITE_KEY/home\") { children { nodes { name primaryNodeType { name } children { nodes { name primaryNodeType { name } } } } } } files: nodeByPath(path: \"/sites/SITE_KEY/files\") { children { nodes { name uuid } } } contentTypes: nodeTypes(filter: {siteKey: \"SITE_KEY\", includeMixins: false, includeAbstract: false}) { nodes { name systemId } } } }"}'
+```
+
+Then fetch all needed type definitions in one more call using `nodeTypesByNames` (see `/jahia-content-explore-structure`).
+
+### 2. Upload images in parallel
+
+Run all uploads simultaneously using background processes:
+
+```bash
+for f in /path/to/img1.jpg /path/to/img2.jpg /path/to/img3.jpg; do
+  name=$(basename "$f")
+  curl -s -u root:root1234 \
+    -H "Origin: http://localhost:8080" \
+    -X POST http://localhost:8080/modules/graphql \
+    -F "operations={\"query\":\"mutation { jcr { addNode(name: \\\"${name}\\\", parentPathOrId: \\\"/sites/SITE_KEY/files\\\", primaryNodeType: \\\"jnt:file\\\", mixins: [\\\"jmix:image\\\"]) { addChild(name: \\\"jcr:content\\\", primaryNodeType: \\\"jnt:resource\\\") { content: mutateProperty(name: \\\"jcr:data\\\") { setValue(type: BINARY, value: \\\"fc\\\") } contentType: mutateProperty(name: \\\"jcr:mimeType\\\") { setValue(value: \\\"image/jpeg\\\") } } uuid } } }\"}" \
+    -F 'map={"fc":["variables.f"]}' \
+    -F "fc=@${f};type=image/jpeg" &
+done
+wait  # all uploads complete in parallel
+```
+
+> ⚠️ Always include `mixins: ["jmix:image"]` in the upload. Without it, the file node **cannot be used as a WEAKREFERENCE** in image properties.
+
+To collect UUIDs after parallel uploads, query them in one batch:
+```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 { nodesByQuery(query: \"SELECT * FROM [jnt:file] WHERE ISDESCENDANTNODE(\u0027/sites/SITE_KEY/files/FOLDER\u0027)\", queryLanguage: SQL2) { nodes { name uuid } } } }"}'
+```
+
+### 3. Create an entire content tree in one mutation
+
+Use nested `addChild` calls inside a single `addNode` mutation to build a complete page hierarchy without sequential round-trips:
+
+```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 { addNode(parentPathOrId: \"/sites/SITE_KEY/home\", name: \"my-page\", primaryNodeType: \"jnt:page\", properties: [{name: \"j:templateName\", value: \"TEMPLATE\"}, {name: \"jcr:title\", value: \"Page Title\", language: \"en\"}]) { uuid addChild(name: \"AREA_NAME\", primaryNodeType: \"AREA_TYPE\") { addChild(name: \"section-1\", primaryNodeType: \"NAMESPACE:section\", properties: [{name: \"jcr:title\", value: \"Section 1\", language: \"en\"}]) { uuid addChild(name: \"item-1\", primaryNodeType: \"NAMESPACE:item\", properties: [{name: \"jcr:title\", value: \"Item 1\", language: \"en\"}, {name: \"body\", value: \"<p>Content</p>\", language: \"en\"}]) { uuid } } } } } }"}'
+```
+
+> This creates the full `page → area → section → item` hierarchy atomically.
+
+### 4. Publish the entire page in one call
+
+```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/SITE_KEY/home/my-page\") { publish(languages: [\"en\"]) } } }"}'
+```
+
+---
+
+## Uploading image files
+
+Use the GraphQL API with a **multipart request** to upload files.
+
+> ⚠️ Do **not** use `Content-Type: application/json` for uploads — use multipart form-data.
+> Do **not** use `type: BINARY` inside the `properties: [...]` array of `addNode` or `addChild` — it won't work. Always use the separate `mutateProperty.setValue` step.
+
+### Upload a single file
+
+> ⚠️ Always include `mixins: ["jmix:image"]` when uploading images. Without this mixin, the file node **cannot be used as a WEAKREFERENCE** in image properties — you will get a constraint error.
+
+```bash
+curl -s -u root:root1234 \
+  -H "Origin: http://localhost:8080" \
+  -X POST http://localhost:8080/modules/graphql \
+  -F 'operations={"query":"mutation { jcr { addNode(name: \"image.jpg\", parentPathOrId: \"/sites/SITE_KEY/files\", primaryNodeType: \"jnt:file\", mixins: [\"jmix:image\"]) { addChild(name: \"jcr:content\", primaryNodeType: \"jnt:resource\") { content: mutateProperty(name: \"jcr:data\") { setValue(type: BINARY, value: \"fc\") } contentType: mutateProperty(name: \"jcr:mimeType\") { setValue(value: \"image/jpeg\") } } uuid } } }"}' \
+  -F 'map={"fc":["variables.f"]}' \
+  -F "fc=@/absolute/path/to/image.jpg;type=image/jpeg"
+```
+
+The response contains the UUID:
+```json
+{"data":{"jcr":{"addNode":{"addChild":{"content":{"setValue":true},"contentType":{"setValue":true}},"uuid":"xxxxxxxx-..."}}}}
+```
+
+### Use a file UUID as an image property
+
+Image properties in CND have `requiredType: WEAKREFERENCE`. Pass the UUID with `type: WEAKREFERENCE`:
+
+```graphql
+properties: [
+  {name: "image", value: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", type: WEAKREFERENCE}
+]
+```
+
+> After uploading, publish the files folder so images are accessible on the live site:
+> ```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/SITE_KEY/files\") { publish(languages: [\"en\"]) } } }"}'
+> ```
+
+---
+
+## Creating pages (jnt:page) — Area structure is mandatory
+
+> ⚠️ If your task involves creating a **page**, read this section first.
+
+In Jahia, a `jnt:page` uses a template that declares named **Areas**. Content added as **direct children of the page node** is silently ignored by the renderer — it will never appear on the page.
+
+Content must be created as children of the **Area sub-node** (e.g. `/sites/mySite/home/my-page/AREA_NAME/hero`).
+
+### Step A — Discover the correct Area structure from an existing page
+
+Pick any working sibling page and inspect 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":"{ jcr { nodeByPath(path: \"/sites/SITE_KEY/home\") { children { nodes { name primaryNodeType { name } children { nodes { name primaryNodeType { name } } } } } } } }"}'
+```
+
+Look for a child node that is a content list or area type (e.g. `jnt:contentList`, `jnt:area`, or a custom area type). Note its **name** — that is your Area node name.
+
+### Step B — Check the page template
+
+```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/SITE_KEY/home/EXISTING_PAGE\") { properties(names: [\"j:templateName\"]) { name value } } } }"}'
+```
+
+Use this exact template name for your new page.
+
+### Step C — Create the page, then add content inside the Area
+
+```bash
+# 1. Create the page
+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 { addNode(parentPathOrId: \"/sites/SITE_KEY/home\", name: \"my-page\", primaryNodeType: \"jnt:page\", properties: [{name: \"jcr:title\", value: \"My Page\", language: \"en\"}, {name: \"j:templateName\", value: \"TEMPLATE_NAME\"}]) { uuid node { path } } } }"}'
+
+# 2. Create the Area sub-node (same type and name as the sibling page's area)
+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 { addNode(parentPathOrId: \"/sites/SITE_KEY/home/my-page\", name: \"AREA_NAME\", primaryNodeType: \"AREA_TYPE\") { uuid node { path } } } }"}'
+
+# 3. Add content INSIDE the area (not on the page directly)
+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 { addNode(parentPathOrId: \"/sites/SITE_KEY/home/my-page/AREA_NAME\", name: \"hero\", primaryNodeType: \"jnt:text\", properties: [{name: \"text\", value: \"<h1>Hello<\\/h1>\", language: \"en\"}]) { uuid node { path } } } }"}'
+```
+
+### Step D — Publish the page
+
+```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/SITE_KEY/home/my-page\") { publish(languages: [\"en\"]) } } }"}'
+```
+
+---
+
+## Step 1 — Identify target site and content folder
+
+Standard content folder paths:
+- `/sites/<siteKey>/contents/articles/` — for article nodes
+- `/sites/<siteKey>/contents/tutorials/` — for tutorial nodes
+- `/sites/<siteKey>/contents/` — for any other content folder
+
+---
+
+## Step 2 — Look up the content type's properties
+
+> 💡 **If the site is unfamiliar**, use **`/jahia-content-explore-structure`** first.
+
+```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 { nodeTypeByName(name: \"NAMESPACE:typeName\") { properties { name requiredType internationalized mandatory constraints } } } }"
+  }'
+```
+
+---
+
+## Step 3 — Create 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 { addNode(parentPathOrId: \"/sites/mySite/contents/articles\", name: \"my-article\", primaryNodeType: \"namespace:docArticle\", properties: [{name: \"jcr:title\", value: \"My Article\", language: \"en\"}, {name: \"body\", value: \"<p>Content here</p>\", language: \"en\"}]) { uuid node { path } } } }"
+  }'
+```
+
+### Property rules
+
+| Situation | GraphQL syntax |
+|-----------|---------------|
+| i18n property (declared `i18n` in CND) | `{name: "body", value: "...", language: "en"}` |
+| Non-i18n property | `{name: "product", value: "jahia"}` |
+| Title (from `mix:title`) | `{name: "jcr:title", value: "...", language: "en"}` |
+| Date property | `{name: "updatedAt", value: "2024-01-15T00:00:00.000Z", type: DATE}` |
+| Multiple values | `{name: "tags", values: ["a", "b"]}` |
+
+### Node name rules
+- Use lowercase kebab-case: `my-article`, `getting-started`
+- No spaces, no special characters
+- Must be unique within the parent folder
+- Use `useAvailableNodeName: true` to auto-suffix if name is taken
+
+---
+
+## Step 4 — Publish the 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\") { publish(languages: [\"en\"]) } } }"
+  }'
+```
+
+Expected response: `{"data": {"jcr": {"mutateNode": {"publish": true}}}}`
+
+---
+
+## Step 5 — Batch creation
+
+To create multiple nodes efficiently, use `addNodesBatch`:
+
+```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 { addNodesBatch(nodes: [{parentPathOrId: \"/sites/mySite/contents/articles\", name: \"article-1\", primaryNodeType: \"namespace:docArticle\", properties: [{name: \"jcr:title\", value: \"Article One\", language: \"en\"}, {name: \"body\", value: \"<p>Body 1</p>\", language: \"en\"}]}, {parentPathOrId: \"/sites/mySite/contents/articles\", name: \"article-2\", primaryNodeType: \"namespace:docArticle\", properties: [{name: \"jcr:title\", value: \"Article Two\", language: \"en\"}, {name: \"body\", value: \"<p>Body 2</p>\", language: \"en\"}]}]) { uuid node { path } } } }"
+  }'
+```
+
+Then publish all at once using `mutateNodesByQuery`:
+
+```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 [namespace:docArticle] WHERE ISDESCENDANTNODE(\u0027/sites/mySite/contents/articles\u0027)\", queryLanguage: SQL2) { publish(languages: [\"en\"]) } } }"
+  }'
+```
+
+---
+
+## Step 6 — Verify
+
+```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 { nodesByQuery(query: \"SELECT * FROM [namespace:docArticle] WHERE ISDESCENDANTNODE(\u0027/sites/mySite/contents/articles\u0027)\", queryLanguage: SQL2) { nodes { name path properties(names: [\"jcr:title\"], language: \"en\") { name value } } } } }"
+  }'
+```
+
+---
+
+## Common errors
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Permission denied` | Missing `Origin` header | Add `-H "Origin: http://localhost:8080"` |
+| `Couldn't find definition for property X` | Wrong property name or non-i18n prop given with `language:` | Check CND definition; remove `language:` for non-i18n props |
+| `ConstraintViolationException: mandatory property` | A mandatory CND property was not provided | Provide all mandatory properties |
+| `ItemExistsException` | Node name already taken | Use `useAvailableNodeName: true` or choose a different name |
+| WEAKREFERENCE image constraint error | Uploaded file missing `jmix:image` mixin | Always include `mixins: ["jmix:image"]` in the `addNode` upload mutation |
+| `deletePropertiesBatch fails with missing required fields` | `language` is NON_NULL in `InputJCRDeletedProperty` — required even for non-i18n properties | Always provide `language: "en"` in every `deletePropertiesBatch` entry |
+
+---
+
+## Setting `j:linkType` links via GraphQL
+
+> 🚫 **NEVER use `j:linkType: "external"` to link to an internal Jahia page.** Always use `"internal"` with `j:linknode`. Hardcoding an internal URL as an external link will break on environment changes, language switching, vanity URLs, and live/preview workspace toggling.
+
+### Internal link (`j:linkType: "internal"`)
+
+`j:linknode` is an **internationalized** weakreference. Add the mixin first, then set the property with `language:`.
+
+```graphql
+# Step 1 — add mixin + set j:linkType
+mutation {
+  jcr {
+    mutateNode(pathOrId: "/sites/mySite/home/features/my-card") {
+      addMixins(mixins: ["jmix:internalLink"])
+      setPropertiesBatch(properties: [
+        {name: "j:linkType", value: "internal"}
+      ]) { path }
+    }
+  }
+}
+
+# Step 2 — set j:linknode (i18n weakreference — must include language)
+mutation {
+  jcr {
+    mutateNode(pathOrId: "/sites/mySite/home/features/my-card") {
+      mutateProperty(name: "j:linknode") {
+        setValue(value: "<target-node-uuid>", language: "en", type: WEAKREFERENCE)
+      }
+    }
+  }
+}
+```
+
+### External link (`j:linkType: "external"`)
+
+```graphql
+mutation {
+  jcr {
+    mutateNode(pathOrId: "/sites/mySite/home/features/my-card") {
+      addMixins(mixins: ["jmix:externalLink"])
+      setPropertiesBatch(properties: [
+        {name: "j:linkType", value: "external"}
+        {name: "j:url", value: "https://example.com", language: "en"}
+        {name: "j:linkTitle", value: "Visit Example", language: "en"}
+      ]) { path }
+    }
+  }
+}
+```
+
+---
+
+## References
+
+- Jahia GraphQL API playground: `http://localhost:8080/modules/graphql` (GET in browser, POST for queries)
+- JCR mutation docs: https://academy.jahia.com/documentation/developer/jahia/8/api-documentation/graphql-api
+- Native Jahia node types (CND source): https://github.com/Jahia/jahia/tree/master/war/src/main/webapp/WEB-INF/etc/repository/nodetypes