@jahia/agentic 0.3.0 → 0.4.1

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

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

package/dist/claude/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md
 <!-- Generated by APM CLI -->
-<!-- Build ID: 3e845c4f03a9 -->
+<!-- Build ID: 33278bb79af8 -->
 
 # Project Standards
 
@@ -15,47 +15,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.
-
-## 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 |
+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.
 
 ## Canonical References
 
@@ -79,8 +54,6 @@ Always fetch these when uncertain about version-sensitive topics:
 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
+- **GraphQL playground**: http://localhost:8080/modules/graphql-dxm-provider/tools/graphql-workspace.jsp
 - **JCR browser**: http://localhost:8080/modules/tools/jcrBrowser.jsp
 - **Definitions browser**: http://localhost:8080/modules/tools/definitionsBrowser.jsp

package/dist/codex/.agents/skills/jahia-cnd-author/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: jahia-cnd-author
+description: Use when you need to write a Jahia CND content type definition and its TypeScript props interface. Receives a component spec and produces definition.cnd + types.ts + .properties labels with correct Jahia-specific syntax. Self-validates output before returning.
+context: fork
+argument-hint: "[business need]"
+---
+
+You are a Jahia content modeling specialist. You receive a business need, e.g. "I want to model a blog post". If used in interactive mode, you may ask for clarifications. Your job is to write correct `definition.cnd`, `types.ts`, and `.properties` files for Jahia components.
+
+## Content Modeling 101
+
+Jahia stores content in a tree structure. Each content node can define props (attached to the node itself) and child nodes (attached to the node as children). To reduce duplication, all nodes extend exactly one node type (usually `jnt:content`) and as many mixins as needed. Mixins are reusable sets of props and child nodes. Jahia ships with many native mixins, and you can define your own.
+
+The content model is pushed to Jahia as CND files. The content is displayed with JS and therefore requires a TypeScript interface for each node type. For each component, you need to provide a `definition.cnd` and a `types.ts` file.
+
+Unless told otherwise, the practice is to create one component per file, colocated with the type definition: `src/components/<name>/definition.cnd` and `./types.ts`.
+
+Project-wide mixins are declared in `settings/definitions.cnd`. Read this file first to see which mixins are already defined. Unless told otherwise, in an existing project, read all existing `.cnd` files to infer practices. When doing so, share a concise summary of your findings with the user and ask for confirmation before proceeding.
+
+## Step 1: establish the component requirements
+
+Understanding the needs correctly is mandatory to provide a good editing experience. The component may be contributed directly in pages, with the visual editor named Page Builder, or from content folders (content collections).
+
+If invoked as a sub-agent with a structured spec, skip to Step 2.
+
+In interactive mode, ask the user to confirm using this template:
+
+```
+Component: [PascalCase name]
+Description: [what it represents and how editors use it]
+Fields:
+  - name: type / i18n? / mandatory?
+Views: [default, card, fullPage, small — list all needed]
+Used where: [page area / content folder / child of <Parent>]
+Has repeatable children: [no / yes: describe them]
+```
+
+For decisions that aren't obvious — semantic vs. generic type, weakreference vs. child nodes, whether to extract a mixin — load [references/cnd-modeling-decisions.md].
+
+## Step 2: survey the project
+
+Before writing anything, understand the project context:
+
+```bash
+grep -h "^<" settings/definitions.cnd | head -1                             # namespace prefix
+grep "nsmix:pageComponent" settings/definitions.cnd                         # two-tier mixin?
+grep -rh "^\[" settings/definitions.cnd src/components/ 2>/dev/null | sort  # existing types
+```
+
+Note the namespace prefix. Check whether `nsmix:pageComponent` is declared — this means components dropped in page areas must extend `nsmix:pageComponent` rather than just `nsmix:component`. Share a concise summary of your findings and, in interactive sessions, ask for confirmation before writing.
+
+## Step 3: write `definition.cnd`
+
+Load reference files as needed for the syntax you require:
+
+- **File structure, namespace declarations, property anatomy** → [references/cnd-syntax.md]
+- **Which Jahia native mixins to extend** (`mix:title`, `jmix:mainResource`, etc.) → [references/cnd-jahia-mixins.md]
+- **String properties, choicelists, link pickers, richtext** → [references/cnd-string-selectors.md]
+- **Numeric, boolean, and date properties** → [references/cnd-numbers-dates.md]
+- **Child nodes, CTAs, orderable containers** → [references/cnd-child-nodes.md]
+- **Custom area types** (only relevant for page template types) → [references/cnd-area-types.md]
+
+Write component-level definitions to `src/components/<Category>/<Name>/definition.cnd`. Module-level mixins belong in `settings/definitions.cnd`.
+
+## Step 4: write `types.ts`
+
+Every CND property needs a corresponding TypeScript entry. Load [references/types-ts-mapping.md] for the full mapping rules, including the discriminated union pattern required for `j:linkType` properties.
+
+Write to `src/components/<Category>/<Name>/types.ts`.
+
+## Step 5: write `.properties` labels
+
+Editors see these labels in the content editor — every type name and every field needs an entry. Load [references/cnd-authoring-experience.md] for the naming conventions and icon patterns.
+
+Write to:
+- `settings/resources/<module>_en.properties`
+- `settings/resources/<module>_fr.properties` (use the English label as a placeholder if no translation is available)
+
+## Step 6: validate and report
+
+Before returning, verify:
+
+- [ ] Namespace prefix matches `settings/definitions.cnd`
+- [ ] All component types extend `nsmix:component` (or `nsmix:pageComponent` if page-area only)
+- [ ] No `- title (string) i18n mandatory` — use `mix:title` instead
+- [ ] No `imageAlt (string)` — the image node's `jcr:title` serves as alt text
+- [ ] Links use `choicelist[linkTypeInitializer]`, not a plain string
+- [ ] No declared `j:linknode` or `j:url` — Jahia injects these automatically
+- [ ] Every `autocreated` property has a `= 'value'` default
+- [ ] `jmix:hiddenType` used for structural types (never `jmix:studioOnly`)
+- [ ] Every CND property has a matching entry in `types.ts`
+- [ ] `.properties` labels written for every type and field
+
+Return **PASS** or **FAIL** with a list of specific issues.

package/dist/codex/.agents/skills/jahia-cnd-author/references/cnd-area-types.md

@@ -0,0 +1,55 @@
+# CND Area Types — Quick Reference
+
+## Two-tier mixin system
+
+Define in `settings/definitions.cnd`:
+
+```cnd
+[nsmix:component]     > jmix:droppableContent, jmix:accessControllableContent mixin
+[nsmix:pageComponent] > nsmix:component mixin
+```
+
+| Component placement | Extend |
+|---|---|
+| Dropped in page areas (top-level) | `nsmix:pageComponent` |
+| Child of another component | `nsmix:component` |
+
+A component extending only `nsmix:component` cannot be dropped in areas that restrict to `nsmix:pageComponent`.
+
+## Custom area type
+
+Restricts what editors can drop into a given area:
+
+```cnd
+[nsnt:pageArea] > jnt:content, jmix:list, jmix:studioOnly orderable
+ + * (nsmix:pageComponent)
+```
+
+Use in a page template view:
+
+```tsx
+<Area name="main" nodeType="nsnt:pageArea" />
+```
+
+`jmix:studioOnly` on the area type prevents it from appearing in the content picker. Use `jmix:hiddenType` for regular component types that should be hidden.
+
+## Escape hatch component
+
+One component that accepts any droppable content, for advanced editors:
+
+```cnd
+[nsnt:contentStack] > jnt:content, nsmix:pageComponent
+ + * (jmix:droppableContent)
+```
+
+Editors add this to a page area, then drop any content type inside it.
+
+## Page templates vs sectioning components
+
+| Page templates | Sectioning components |
+|---|---|
+| Fixed vertical sections per template | Editor builds sections freely |
+| Simpler for less experienced editors | More flexible, preferred for evolving integrations |
+| Use when mockups define clear distinct layouts | Use for a single free-form template |
+
+Reuse area names across templates (e.g. always `main` and `sidebar`) so content is not lost when editors switch templates.

package/dist/codex/.agents/skills/jahia-cnd-author/references/cnd-authoring-experience.md

@@ -0,0 +1,92 @@
+# CND Authoring Experience Reference
+
+## .properties labels and icons
+
+Required files for every content type:
+- `settings/resources/<module>_en.properties`
+- `settings/resources/<module>_fr.properties`
+
+```ini
+# Node type label
+ns_heroSection.label=Hero Section
+
+# Field labels
+ns_heroSection.subtitle.label=Subtitle
+ns_heroSection.backgroundImage.label=Background Image
+
+# Field tooltip
+ns_heroSection.subtitle.ui.tooltip=Optional subtitle text displayed below the heading.
+
+# Choicelist item labels (for resourceBundle choicelist)
+ns_heroSection.variant.primary=Primary
+ns_heroSection.variant.secondary=Secondary
+```
+
+Icon file: `settings/content-types-icons/<ns>_<typeName>.png`
+Free icons: https://www.flaticon.com/
+
+**Rules:**
+- Every node type must have a `.label` entry.
+- Every field must have a `.label` entry.
+- Choicelist options using `resourceBundle` must have a label per value.
+- Replace special characters (e.g. `:`) with `_` in the `.properties` key.
+
+---
+
+## Editor hints in views
+
+Use `renderContext.isEditMode()` to show a flat, non-interactive layout and hints in edit mode.
+
+```tsx
+({ slides }: Props, { renderContext }) => {
+  const isEdit = renderContext.isEditMode();
+  return isEdit ? (
+    <div>
+      <RenderChildren />
+      <p className={classes.hint}>Carousel — add or reorder slides here</p>
+    </div>
+  ) : (
+    <div className={classes.carousel}><RenderChildren /></div>
+  );
+};
+```
+
+Show inline validation hints:
+
+```tsx
+{renderContext.isEditMode() && value % 2 !== 0 && (
+  <p className="editor-hint">Value should be even for best visual result.</p>
+)}
+```
+
+---
+
+## import.xml recommendations
+
+Provide `import.xml` in every template set to pre-populate new sites:
+
+- A homepage with `j:isHomePage="true"` — required for sitemap and nav generation.
+- Offline folder structure with `jmix:systemNameReadonly` + `jmix:nolive`:
+  - "Offline pages/Models"
+  - "Offline pages/Drafts"
+  - "Offline pages/Archive"
+- Content folders matching your types (e.g. "Blog/Authors", "Blog/Posts").
+- Content restrictions on folders:
+  ```xml
+  jcr:mixinTypes="jmix:contributeMode" j:contributeTypes="ns:blogPost"
+  ```
+
+> `import.xml` only applies at site creation — changes do NOT update existing sites.
+
+---
+
+## jmix:visibleInContentTree
+
+Enables Page Builder visual editing inside content folders (not just list view).
+
+```cnd
+[ns:authorCollection] > jnt:content, jmix:visibleInContentTree
+ + * (ns:author)
+```
+
+Use when editors benefit from visual layout while editing content folder items.

package/dist/codex/.agents/skills/jahia-cnd-author/references/cnd-child-nodes.md

@@ -0,0 +1,74 @@
+# CND Child Nodes
+
+## Syntax
+
+```cnd
++ childName (ns:type)            // named child — exactly one
++ childName (ns:type) multiple   // named child — list
++ * (ns:type)                    // any-name child of a specific type
++ * (jmix:droppableContent)      // open container — any droppable component
+```
+
+## When to use child nodes vs `weakreference multiple`
+
+| Use child nodes when… | Use `weakreference multiple` when… |
+|---|---|
+| Each item has multiple properties (label + link) | Each item is just a reference (a page, an image) |
+| Items have no life outside the parent | Items are managed elsewhere and reused |
+| You always create them together | Editors need to pick from existing content |
+
+## Repeatable CTA pattern
+
+**NEVER put `ctaText + ctaLink/ctaUrl` on the parent type as flat properties.**
+Model CTAs as child nodes — editors can then add multiple CTAs.
+
+```cnd
+// ✅ Correct — supports multiple CTAs
+[ns:heroSection] > jnt:content, nsmix:component, mix:title
+ - subtitle (string, richtext) i18n
+ - backgroundImage (weakreference, picker[type='image']) < jmix:image
+ + * (ns:heroCallToAction)
+
+[ns:heroCallToAction] > jnt:content, nsmix:component
+ - label (string) i18n mandatory
+ - j:linkType (string, choicelist[linkTypeInitializer]) mandatory
+
+// ❌ Wrong — forces exactly one CTA, editors can't add more
+[ns:heroSection] > jnt:content, nsmix:component
+ - ctaText (string) i18n
+ - ctaLink (string) i18n       // also wrong type for links
+```
+
+## Ordering
+
+Add `orderable` to the parent type when editors need to reorder children:
+
+```cnd
+[ns:featureList] > jnt:content, nsmix:component orderable
+ + * (ns:featureItem)
+```
+
+## Hidden structural nodes
+
+Child nodes that editors should never add manually (structural containers, auto-created nodes):
+
+```cnd
+[ns:heroSection] > jnt:content, nsmix:component, mix:title
+ + ctaContainer (ns:ctaContainer) autocreated
+
+[ns:ctaContainer] > jnt:content, jmix:hiddenType orderable
+ + * (ns:callToAction)
+```
+
+`jmix:hiddenType` hides a type from the Page Builder component picker.
+**Never use `jmix:studioOnly`** — it causes silent rendering issues.
+
+## Open container (accept any droppable)
+
+```cnd
+[ns:gridRow] > jnt:content, nsmix:component
+ - columns (long) = '3' autocreated mandatory < '1', '2', '3', '4'
+ + * (jmix:droppableContent)
+```
+
+`+ * (jmix:droppableContent)` accepts any component the editor can drop.