@jahia/agentic 0.0.0

package/dist/windsurf/.windsurf/skills/jahia-dev-create-page-template/SKILL.md

@@ -0,0 +1,303 @@
+---
+name: jahia-dev-create-page-template
+description: Creates a Jahia page template with Areas and AbsoluteAreas. Use when asked to add a new page layout, create a page template, or set up a shared area like a header or footer.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+## Overview
+
+A **page template** defines the full layout of a page. It is registered with `componentType: "template"` and always targets `jnt:page`. Templates contain **Areas** (per-page content) and **AbsoluteAreas** (shared across all pages, e.g. footer, navbar).
+
+---
+
+> ⚠️ **CMS rule — never hardcode links in templates.** Navigation links, logo hrefs, footer links — all must come from contributed content (via props, `buildNodeUrl`, or `j:linkType`). Do not put literal URLs in template code.
+
+## Step 1 — Create the template file
+
+Page templates live in `src/templates/Page/`. Name the file `<templateName>.server.tsx`.
+
+```tsx
+import { Area, AbsoluteArea, jahiaComponent } from "@jahia/javascript-modules-library";
+import { Layout } from "../Layout.jsx";
+
+jahiaComponent(
+  {
+    componentType: "template",   // "template" for full pages, not "view"
+    nodeType: "jnt:page",        // always jnt:page for page templates
+    displayName: "Single Column",
+    name: "singleColumn",        // used in Jahia UI when selecting a template
+  },
+  ({ "jcr:title": title }, { renderContext }) => (
+    <Layout title={title}>
+      <Area name="header" nodeType="namespace:header" />
+      <main style={{ maxWidth: "40rem", margin: "0 auto" }}>
+        <Area name="main" />
+      </main>
+      <AbsoluteArea
+        name="footer"
+        parent={renderContext.getSite()}
+        nodeType="namespace:footer"
+      />
+    </Layout>
+  ),
+);
+```
+
+---
+
+## Step 2 — Choose: Area vs AbsoluteArea
+
+| | `<Area>` | `<AbsoluteArea>` |
+|---|---|---|
+| Content | Per-page (each page has its own) | Shared across all pages |
+| Use for | Page body, hero, sections | Footer, navbar, sidebar |
+| `parent` prop | Not needed | Set to `renderContext.getSite()` for site-wide |
+
+---
+
+## Step 3 — Use typed area nodes (required for good editorial UX)
+
+Instead of a single generic area type, define **one area type per section** with a tight child constraint. This ensures editors only see relevant content types in each area's "New content" menu.
+
+```cnd
+// settings/definitions.cnd
+
+[namespacemix:pageComponent] > namespacemix:component mixin
+
+// ✅ Typed areas — editors only see the right types per area
+// Use jmix:hiddenType (NOT jmix:studioOnly) — hides from picker while keeping rendering intact
+[namespace:heroArea] > jnt:content, jmix:list, jmix:hiddenType orderable
+ + * (namespace:heroSection)
+
+[namespace:featuresArea] > jnt:content, jmix:list, jmix:hiddenType orderable
+ + * (namespace:featureCard)
+
+// Generic fallback — use only when no tighter constraint makes sense
+[namespace:pageArea] > jnt:content, jmix:list, jmix:hiddenType orderable
+ + * (namespacemix:pageComponent)
+```
+
+Then in the template:
+
+```tsx
+<Area name="hero"     nodeType="namespace:heroArea" />
+<Area name="features" nodeType="namespace:featuresArea" />
+<Area name="footer"   nodeType="namespace:pageArea" />   // generic ok for footer
+```
+
+> ⚠️ **Never use a generic `pageArea` for every area.** If all areas accept all `pageComponent` types, editors will see "New Hero Section" as an option in a feature card area, which is confusing and error-prone.
+
+> **Sections driven by content folders** (e.g. a tutorials listing that queries `/contents/tutorials/`) should NOT use an Area at all — the template renders them via a server-side query component. Exposing an Area there invites editors to manually add duplicates of auto-queried content.
+
+> ⚠️ **CSS gotcha — `Area` renders children directly, no wrapper div.** When wrapping an `<Area>` in a container div and styling children with `.container > div { display: grid }`, the grid won't apply because there is no intermediate `div` — the area's child components are rendered as direct children of `.container`. Always apply grid/flex layout **on the container itself** when its only content is an Area:
+> ```css
+> /* ✅ correct — grid on the container that wraps the Area */
+> .featuresSection .container { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 1.5rem; }
+> /* ❌ wrong — no div is inserted between container and the card articles */
+> .container > div { display: grid; }
+> ```
+
+### ⚠️ After defining `pageComponent` — update existing components
+
+**This is the most common mistake:** if the module already has content types, they all extend `namespacemix:component`. After introducing the custom area type, **editors will not be able to drop anything** until you update the page-level components to extend `namespacemix:pageComponent` instead.
+
+Scan all `definition.cnd` files and update every component that should be droppable in page areas:
+
+```cnd
+// Before (editors can't drop in pageArea):
+[namespace:heroSection] > jnt:content, namespacemix:component
+
+// After (editors can drop in pageArea):
+[namespace:heroSection] > jnt:content, namespacemix:pageComponent
+```
+
+**Which components need `pageComponent`?**
+- Standalone page sections (hero, feature cards, text blocks, etc.) → `namespacemix:pageComponent`
+- Child-only types (CTA inside hero, card inside list) → keep `namespacemix:component`
+- `jmix:mainResource` types stored in content folders → keep `namespacemix:component`
+
+---
+
+## Step 4 — Page template vs sectioning component
+
+Before creating a new page template, ask:
+
+| Is this… | Use a… |
+|---|---|
+| A new top-level page layout (different column structure, hero slot) | **New page template** |
+| A layout variation that could be reused as a section on any page | **Sectioning component** (use the build-component skill) |
+| A minor style difference on an existing template | **Named view** of the existing template |
+
+**Guideline**: keep page templates small (1–4). Use sectioning components for compositional differences.
+
+---
+
+## Step 5 — Define structural (non-selectable) container nodes
+
+Some nodes are purely structural — they hold child nodes but shouldn't appear in the component picker. Omit `namespacemix:component` and add `jmix:hiddenType`:
+
+```cnd
+[namespace:header] > jnt:content, jmix:hiddenType
+ + hero (namespace:heroSection)
+```
+
+Render it with `RenderChild`:
+
+```tsx
+// src/components/Header/default.server.tsx
+import { jahiaComponent, RenderChild } from "@jahia/javascript-modules-library";
+
+jahiaComponent(
+  { componentType: "view", nodeType: "namespace:header" },
+  () => <RenderChild name="hero" />,
+);
+```
+
+---
+
+## Step 6 — Bootstrap site structure with import.xml
+
+`import.xml` provisions every new site created from this template set. **Always update it** — editors cannot contribute if there's no page structure to start from.
+
+**Minimum required:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<content xmlns:j="http://www.jahia.org/jahia/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0">
+  <modules jcr:primaryType="jnt:modules">
+    <your-module-name>
+
+      <!-- Homepage — MUST use your actual template name, not "basic" -->
+      <home j:isHomePage="true" j:templateName="homepage" jcr:primaryType="jnt:page">
+        <j:translation_en jcr:language="en" jcr:mixinTypes="mix:title"
+          jcr:primaryType="jnt:translation" jcr:title="Home"/>
+
+        <!-- Pre-create area nodes so editors can start dropping content immediately -->
+        <hero jcr:primaryType="namespace:pageArea"/>
+        <main jcr:primaryType="namespace:pageArea"/>
+      </home>
+
+      <!-- Add sub-pages for each template you created -->
+      <documentation j:templateName="documentation" jcr:primaryType="jnt:page">
+        <j:translation_en jcr:language="en" jcr:mixinTypes="mix:title"
+          jcr:primaryType="jnt:translation" jcr:title="Documentation"/>
+        <hero jcr:primaryType="namespace:pageArea"/>
+      </documentation>
+
+      <!-- Offline management pages — never published, system-name locked -->
+      <drafts jcr:primaryType="jnt:page" j:templateName="basic"
+        jcr:mixinTypes="jmix:systemNameReadonly jmix:nolive">
+        <j:translation_en jcr:language="en" jcr:mixinTypes="mix:title"
+          jcr:primaryType="jnt:translation" jcr:title="Drafts"/>
+      </drafts>
+
+      <!-- Content folders — store jmix:mainResource content here, not in pages -->
+      <contents jcr:primaryType="jnt:contentFolder">
+        <articles jcr:primaryType="jnt:contentFolder"
+          jcr:mixinTypes="jmix:contributeMode" j:contributeTypes="namespace:docArticle">
+          <j:translation_en jcr:language="en" jcr:primaryType="jnt:translation" jcr:title="Articles"/>
+        </articles>
+      </contents>
+
+    </your-module-name>
+  </modules>
+</content>
+```
+
+**Rules:**
+- `j:templateName` must match the `name:` in your `jahiaComponent` call — if it's wrong, editors get a blank page
+- Pre-create area nodes (`jcr:primaryType="namespace:pageArea"`) so editors don't face empty containers on first open
+- Add a starter component in the hero area so the page isn't visually blank (optional but strongly recommended)
+- Content folders with `jmix:contributeMode` + `j:contributeTypes` restrict what editors can create in them
+- `jmix:systemNameReadonly` prevents editors from renaming or moving management pages; `jmix:nolive` prevents accidental publishing
+
+---
+
+## Step 7 — Build and deploy
+
+```bash
+yarn build && yarn jahia-deploy
+```
+
+> ⚠️ **Do not use `yarn dev`** — it is a continuous file watcher that should only be started manually when needed for rapid iteration. For agentic workflows, always use `yarn build && yarn jahia-deploy` for explicit, one-shot deploys.
+
+After deploying, the new template will appear in the **template selection** step when creating a new page (right-click on a page in the sidebar → **+ New Page**).
+
+---
+
+## Common patterns
+
+### Single column with shared footer
+
+```tsx
+<Layout title={title}>
+  <Area name="main" />
+  <AbsoluteArea name="footer" parent={renderContext.getSite()} nodeType="namespace:footer" />
+</Layout>
+```
+
+### Two-column layout
+
+```tsx
+<Layout title={title}>
+  <div style={{ display: "grid", gridTemplateColumns: "1fr 2fr", gap: "2rem" }}>
+    <Area name="sidebar" />
+    <Area name="main" />
+  </div>
+</Layout>
+```
+
+### Edit mode-aware rendering
+
+```tsx
+({ "jcr:title": title }, { renderContext }) => {
+  const isEdit = renderContext.isEditMode();
+  return (
+    <Layout title={title}>
+      <Area name="main" />
+      <nav style={{ flexDirection: isEdit ? "column" : "row" }}>
+        <AbsoluteArea name="footer" parent={renderContext.getSite()} />
+      </nav>
+    </Layout>
+  );
+}
+```
+
+---
+
+## Validation checklist
+- [ ] File is in `src/templates/Page/`
+- [ ] `componentType: "template"` and `nodeType: "jnt:page"`
+- [ ] `name` is set (used in Jahia UI template picker)
+- [ ] Areas use a custom area node type (not bare `<Area name="..."/>`)
+- [ ] Custom area type has `jmix:list`, `jmix:hiddenType`, and `orderable`
+- [ ] `AbsoluteArea` uses `renderContext.getSite()` as parent
+- [ ] Structural container nodes use `jmix:hiddenType` (hidden from picker)
+- [ ] Decision made: page template vs sectioning component (see Step 4)
+- [ ] `yarn build && yarn jahia-deploy` run and template appears in Jahia UI
+
+## Troubleshooting
+
+### 🚨 Area renders blank — content invisible
+
+**Symptom:** An Area in your template produces no HTML output at all, even though you can see children in jContent.
+
+**Root cause:** Jahia's `Area` component auto-creates the JCR area node using its declared `nodeType` on first page load. If that node was subsequently **deleted and recreated manually** (e.g. via GraphQL) with a *different* type, the declared type and the actual JCR type no longer match — and Jahia silently renders nothing.
+
+**Fix:** Delete the mistyped node and let Jahia recreate it automatically:
+
+```graphql
+mutation {
+  jcr {
+    mutateNode(pathOrId: "/sites/mySite/home/hero") {
+      delete
+    }
+  }
+}
+```
+
+Visit the page — Jahia recreates the node with the correct type and children render again.
+
+**Prevention:** Never manually create area nodes via GraphQL with a type that differs from the `nodeType` declared in the template. Always let Jahia auto-create area nodes on first render.
+
+> https://academy.jahia.com/tutorials-get-started/front-end-developer/the-about-us-page

package/dist/windsurf/.windsurf/skills/jahia-dev-create-template-set/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: jahia-dev-create-template-set
+description: Scaffolds a new Jahia JavaScript template set (React). Use this when asked to create a new Jahia module, website, or project.
+---
+
+## About Jahia JavaScript Modules
+
+This skill only covers **JavaScript Modules** — React-based template sets for Jahia 8+. This is the recommended approach for all new Jahia projects.
+
+### JS modules vs Java modules vs Next.js
+
+| | Java Modules | JS Modules | Next.js (Headless) |
+|---|---|---|---|
+| Availability | All versions | 8.2+ | Depends on setup |
+| Separate runtime | No | No | Yes |
+| GraphQL required | No | No | Yes |
+| CMS navigation/cache/auth | Yes | Yes | No |
+| Packaging | Maven/jar | NPM/tgz | NPM/tgz |
+| Templating | JSP | JSX | JSX |
+| Module descriptor | pom.xml | package.json | Separate module |
+
+Jahia recommends JS or Java modules for most projects. Next.js should only be chosen when integrating with an existing Next.js codebase.
+
+### How JS modules run: GraalVM + GraalJS
+
+Jahia JS modules run inside **GraalJS** (part of GraalVM) — a fully ECMAScript-2019-compliant JS engine on the JVM. GraalVM Native Image is **not** used (incompatible with OSGi). Official Jahia Docker images ship with GraalVM pre-configured.
+
+**Build pipeline:** Yarn 4 + Vite. The `npm init @jahia/module@latest` scaffolder generates `vite.config.mjs` handling TypeScript, CSS Modules, and client-side JS bundles.
+
+**tgz → OSGi transformation:** On install, Jahia converts the NPM tgz into an OSGi bundle. Key `package.json` → `MANIFEST.MF` mappings:
+
+| package.json field | MANIFEST.MF clause |
+|---|---|
+| `jahia.module-dependencies` | `Jahia-Depends` |
+| `jahia.server` | `Jahia-NPM-InitScript` |
+| `jahia.required-version` | `Jahia-Required-Version` |
+| `jahia.module-type` | `Jahia-Module-Type` |
+| `jahia.static-resources` | `Jahia-Static-Resources` |
+
+**Request flow:**
+1. Browser request → Jahia servlet
+2. `TemplateNodeFilter` resolves the template identifier
+3. `ViewsRegistrar` resolves the JS script for the template
+4. `GraalVMEngine` pulls a `ContextProvider` from its pool, renders via GraalJS
+5. `<Area>` / `<Render>` components may call `RenderService` to render child views
+6. Final HTML assembled and returned
+
+The engine maintains a pool of polyglot contexts (one per thread). Each context runs all init scripts (`dist/server/index.js`) on creation. A version counter invalidates stale contexts when modules are added or removed.
+
+---
+
+## Step 1 — Check prerequisites
+
+Before scaffolding, verify Node.js and Yarn are available:
+
+```bash
+node --version   # must be 22.14+
+yarn --version   # must be 4.9+
+```
+
+Node 22.14+ is required. Yarn is managed by **Corepack** (bundled with Node) — no global install needed:
+
+```bash
+corepack enable yarn
+```
+
+If Node is missing or outdated, install it from [nodejs.org/en/download](https://nodejs.org/en/download) — select **for your platform** and **with Yarn**. Alternatively use mise:
+
+```bash
+mise use node@lts && corepack enable yarn
+```
+
+Do not proceed until both `node --version` (22.14+) and `yarn --version` (4.9+) pass.
+
+---
+
+## Step 2 — Scaffold the module
+
+Run the interactive CLI and **show the user its full output**:
+
+```bash
+npm init @jahia/module@latest <project-name>
+```
+
+The CLI will prompt interactively for:
+
+| Prompt | Guidance |
+|--------|----------|
+| Module name | kebab-case, e.g. `my-site` |
+| Output directory | accept the default (`./<module-name>`) |
+| Module type | see below |
+
+**Module type — always choose a template set:**
+- `A minimal Hello World template set` ✅ — best starting point, includes working components
+- `An empty template set` — blank canvas, for experienced developers
+
+Once the project is created, the CLI will suggest commands to start it. Run them in order — they start Docker (Jahia) and push the module.
+
+---
+
+## Step 3 — After generation
+
+1. `cd <project-name>`
+2. `yarn install` — install dependencies
+
+To run the module locally, use the `/jahia-dev-start-local` skill next.
+
+---
+
+## Step 4 — Build and deploy the module
+
+Once Jahia is running at `http://localhost:8080`, build and deploy the module:
+
+```bash
+yarn build && yarn jahia-deploy
+```
+
+`yarn jahia-deploy` (from `@jahia/vite-plugin` 1.2.0+) always uses curl and defaults to `http://localhost:8080` / `root:root1234` — no `.env` configuration is required for standard local development.
+
+Verify the module is installed:
+
+```bash
+curl -s -u root:root1234 -H "Origin: http://localhost:8080" \
+  -X POST http://localhost:8080/modules/graphql \
+  -H "Content-Type: application/json" \
+  -d '{"query":"{ jcr { nodeByPath(path:\"/modules/<module-name>\") { name } } }"}'
+```
+
+Replace `<module-name>` with the `name` from `package.json`. The response should contain `"name": "<module-name>"`.
+
+---
+
+## Step 5 — Create a new site in Jahia
+
+After the module is deployed, create the site via the Provisioning API — **do not use the UI**.
+
+> ⚠️ **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
+
+curl -u root:root1234 \
+     -X POST \
+     -H "Content-Type: application/yaml" \
+     --data-binary "- createSite: \"\"
+  siteKey: ${MODULE_NAME}
+  title: \"My Site\"
+  defaultLanguage: en
+  serverName: localhost
+  templateSet: ${MODULE_NAME}" \
+     http://localhost:8080/modules/api/provisioning
+```
+
+Or write the script to a file and POST it:
+
+```bash
+MODULE_NAME=<module-name>
+
+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
+```
+
+Verify the site was created:
+```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 } } }\"}"
+```
+
+The response must contain `"name": "<module-name>"`. If the path returns `null`, the site was not created — check that `templateSet` exactly matches the deployed module name.
+
+---
+
+## Generated structure (Hello World template set)
+
+```
+<module-name>/
+├── .github/               # GitHub Actions (builds on push)
+├── .vscode/               # VSCode config — install recommended extensions!
+├── src/
+│   ├── components/        # React content type components
+│   └── templates/         # Page layouts
+├── settings/
+│   ├── content-types-icons/   # 32×32 PNG icons per content type
+│   ├── definitions.cnd        # Module-level CND (mixins, base types)
+│   ├── import.xml             # Content/pages provisioned on site creation
+│   ├── locales/               # i18n (en.json, fr.json, ...)
+│   ├── resources/             # Editor UI labels (.properties files)
+│   └── template-thumbnail.png # Shown in the Jahia template picker
+├── static/                # Static files (images, fonts, vendor CSS/JS)
+├── docker-compose.yml     # Local Jahia instance
+├── docker/provisioning.yml
+├── .env                   # Environment variables for build tools
+├── .node-version          # Node version pin (used by GitHub Actions)
+├── package.json
+├── vite.config.mjs
+└── tsconfig.json
+```
+
+`static/` is served at `/modules/<name>/` — reference files there with `buildModuleFileUrl("image.png")`.
+
+---
+
+## References
+- https://github.com/Jahia/javascript-modules (monorepo — includes the `create-module` archetype)
+
+## Troubleshooting
+
+If anything goes wrong during setup or scaffolding, refer to the official Jahia front-end developer setup guide:
+
+> https://academy.jahia.com/tutorials-get-started/front-end-developer/setting-up-your-dev-environment
+
+---
+
+## Validation checklist
+- [ ] `node --version` reports 22.14+
+- [ ] `yarn --version` reports 4.9+ (via Corepack)
+- [ ] Module directory created with expected structure
+- [ ] `yarn install` completes without errors
+- [ ] `yarn build && yarn jahia-deploy` succeeds — module appears at `/modules/<name>` in JCR
+- [ ] Site created with `createSite: ""` — JCR confirms `/sites/<name>` exists