@jahia/agentic 0.0.0

package/dist/windsurf/.windsurf/rules/jahia.md

@@ -0,0 +1,80 @@
+---
+trigger: always_on
+---
+
+# Jahia JavaScript Module Development
+
+## Context
+
+You are helping develop a **Jahia JavaScript Module** — a React-based template set for Jahia 8+. The module renders content from Jahia's JCR (Java Content Repository) using server-side React components (`.server.tsx`) and optional client-side islands (`.client.tsx`). Content is modelled in CND files, managed via Page Builder or jContent, and queried with JCR-SQL2 or GraphQL.
+
+## 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.
+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).
+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.
+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. **Accessibility is mandatory** — every component must pass WCAG 2.1 AA. After building any component or completing a task, invoke `/jahia-dev-accessibility` to run an axe-core audit and fix all `critical` and `serious` violations before declaring work done.
+
+## Skill Map
+
+Start with `/jahia` if unsure where to begin.
+
+### Development
+
+| Skill | Purpose |
+|-------|---------|
+| `/jahia-dev` | Entry point — detect project state, guide to next step |
+| `/jahia-dev-create-template-set` | Scaffold a new Jahia JS module |
+| `/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-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-screenshot` | Screenshot reference + local render for visual comparison |
+| `/jahia-dev-debug` | Debug build/deploy/runtime errors end-to-end |
+
+### Content Management
+
+| Skill | Purpose |
+|-------|---------|
+| `/jahia-content` | Entry point — detect site state, route to content operations |
+| `/jahia-content-explore-structure` | Map content types, properties, enums on an unknown site |
+| `/jahia-content-query-content` | List and inspect content via GraphQL |
+| `/jahia-content-create-content` | Create nodes, folders, articles, bulk-populate |
+| `/jahia-content-move-content` | Restructure the content tree |
+| `/jahia-content-translate-content` | Translate existing nodes to a new language and publish |
+
+## Canonical References
+
+Always fetch these when uncertain about version-sensitive topics:
+
+| Topic | URL |
+|-------|-----|
+| Getting started / dev environment | https://academy.jahia.com/tutorials-get-started/front-end-developer/setting-up-your-dev-environment |
+| Hero section tutorial | https://academy.jahia.com/tutorials-get-started/front-end-developer/making-a-hero-section |
+| Blog / content listing | https://academy.jahia.com/tutorials-get-started/front-end-developer/making-a-blog |
+| Page templates | https://academy.jahia.com/tutorials-get-started/front-end-developer/the-about-us-page |
+| i18n (CND attribute, useTranslation, language switcher) | https://academy.jahia.com/documentation/jahia-cms/jahia-8-2/developer/javascript-module-development/preparing-for-internationalization-i18n |
+| GraphQL API | https://academy.jahia.com/documentation/developer/jahia/8/api-documentation/graphql-api |
+| Native Jahia mixins & node types | https://github.com/Jahia/jahia/tree/master/war/src/main/webapp/WEB-INF/etc/repository/nodetypes |
+| JavaScript modules monorepo | https://github.com/Jahia/javascript-modules |
+| Developer training | https://github.com/Jahia/developer-training/blob/main/js-training/slides.md |
+| Integration best practices | https://github.com/Jahia/gautier-braindump/blob/main/articles/integration-best-practices/README.md |
+
+## Local Development URLs
+
+When Jahia is running at `http://localhost:8080` (default credentials: `root` / `root1234`):
+
+- **Login**: http://localhost:8080/cms/login
+- **Page Builder**: http://localhost:8080/jahia/page-builder
+- **jContent**: http://localhost:8080/jahia/jcontent
+- **GraphQL playground**: http://localhost:8080/modules/graphql
+- **JCR browser**: http://localhost:8080/modules/tools/jcrBrowser.jsp
+- **Definitions browser**: http://localhost:8080/modules/tools/definitionsBrowser.jsp

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