@jahia/agentic 0.3.0 → 0.4.1

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

@@ -1,7 +1,7 @@
 # AGENTS.md
 <!-- Generated by APM CLI from distributed .apm/ primitives -->
-<!-- Build ID: 971609428c97 -->
-<!-- APM Version: 0.20.0 -->
+<!-- Build ID: f8784ff296c9 -->
+<!-- APM Version: 0.21.0 -->
 
 ## Global Instructions
 
@@ -14,47 +14,22 @@ You are helping develop a **Jahia JavaScript Module** — a React-based template
 ## Agent Principles
 
 1. **Always invoke a skill before any Jahia task** — skills are the canonical source of patterns, gotchas, and API syntax. Never operate from memory alone.
+1a. **Always load CND reference files before writing any CND** — Jahia-specific patterns (`choicelist[linkTypeInitializer]`, `mix:title`, child nodes for CTAs, `jmix:image` weakreferences) are not in your training data. Before writing any CND, read the reference files: `find . -maxdepth 4 -name 'cnd-jahia-mixins*' | head -3`. When working interactively through skill chains, prefer `@jahia-cnd-author` (it loads these files for you).
 2. **Never use `yarn dev` from an agent** — it is an interactive file watcher for human developers only. Always deploy with `yarn build && yarn jahia-deploy` (one-shot, non-interactive).
+2a. **Use the TypeScript LSP for API discovery, never grep.** When you need to know a function's signature or what a module exports, call `mcp__ide__getDiagnostics` on the file after writing it — the LSP reads live type definitions and reports mismatches, wrong argument counts, and missing exports. Never run `grep` on `node_modules` to find a function name or signature.
 3. **Never hardcode URLs** — all navigable links must come from contributed content (JCR nodes, `j:linkType`, `buildNodeUrl`). This is a CMS: content owns the URLs.
 4. **Never use `j:linkType: "external"` for internal pages** — use `"internal"` + `j:linknode`. External URLs break on environment changes, language switches, and vanity URL rewrites.
-5. **Always verify before creating** — check that content types are deployed, site keys are correct, and area structures exist before attempting GraphQL mutations.
+5. **Always verify before creating** — check that content types are deployed, site keys are correct, and parent area nodes exist before creating content via MCP.
 6. **All props are optional at runtime** — even mandatory CND fields. Always guard against `undefined` in views.
-7. **Always include `-H "Origin: http://localhost:8080"` in every GraphQL curl** — omitting it returns `Permission denied` even with correct credentials.
-8. **Build accessible HTML from the start** — every view must use semantic HTML (`<main>`, `<header>`, `<nav>`, `<footer>`, `<section>`, `<article>`), include exactly one `<h1>` per page, use a strict heading hierarchy (h1 → h2 → h3), add `alt` text to every `<img>`, and use sufficient colour contrast (≥ 4.5:1 for body text). Baking this in during authoring is faster than a post-hoc audit.
-9. **Run one accessibility audit at the end** — after all components are built and content is published, invoke `/jahia-dev-accessibility` once to catch any remaining violations. Do not audit after every individual component; it wastes time on pages that are not yet complete.
-10. **Batch builds and deploys** — build all components together, then run `yarn build && yarn jahia-deploy` once rather than after each individual component. Deploy once before populating content.
-
-## 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
 
@@ -78,9 +53,7 @@ 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jahia/agentic",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "A CLI to bootstrap an agentic harness for Jahia",
   "license": "MIT",
   "repository": {

package/dist/claude/.claude/skills/jahia/SKILL.md

@@ -1,144 +0,0 @@
----
-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 via MCP tools), and delegates to the right skill or combination. Start here if unsure which Jahia skill to use.
----
-
-# Jahia — Universal Entry Point
-
-You are the top-level GPS for all Jahia work. Your job is to understand what the user wants to accomplish, then delegate to the right skill(s) — `/jahia-dev`, `/jahia-content`, or both in sequence.
-
-> **Content operations use MCP tools** via the `jahia` MCP server. Never call Jahia's GraphQL API directly for content creation, querying, or structure discovery — use the MCP tools instead.
-
----
-
-## Step 1 — Classify the request
-
-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    → create the site if needed, then populate the section with content
-4. /jahia-content-organize          → (if existing content needs to be reorganized)
-```
-
-### "Add an article to the site"
-```
-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
-3. /jahia-content-publish           → publish it to LIVE
-```
-
-### "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    → use `site.templateSets` + `site.create`, then add pages and content
-6. /jahia-content-publish           → publish the site content
-7. /jahia-dev-review                → catch issues before shipping
-```
-
----
-
-## 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 MCP tools
-/jahia-content-create-content        Create sites, pages, nodes, folders, and articles
-/jahia-content-media-upload          Upload files and images into Jahia media storage
-/jahia-content-organize              Restructure the tree: move, copy, rename, reorder, delete
-/jahia-content-move-content          Focused move/reorder/delete workflow for an existing branch
-/jahia-content-translate-content     Translate i18n content and page titles
-/jahia-content-publish               Publish, unpublish, and inspect publication status
-### 📚 Knowledge Reference
-/jahia-dev-java              OSGi DS, CND definitions, JSP rendering, Drools rules, Content Editor/jContent UI
-/jahia-jcr-sql2              JCR-SQL2 syntax, filtering, full-text, joins, and pagination guardrails
-/jahia-dev-apis              GraphQL, JCR Java/REST API, OAuth/SAML, personal tokens, HTML filtering, CSP
-/jahia-dev-ops               Docker Compose, Kubernetes, health monitoring, Karaf, provisioning YAML API
-/jahia-dev-properties        jahia.properties and OSGi .cfg configuration keys reference
-```
-

package/dist/claude/.claude/skills/jahia-content/SKILL.md

@@ -1,157 +0,0 @@
----
-name: jahia-content
-description: Entry point for creating sites, authoring pages, querying content, reorganizing nodes, uploading media, translating, and publishing a Jahia website via MCP tools.
----
-
-# Jahia Content — Content Management GPS
-
-You are the entry point for content work on a live Jahia instance. Understand the request, assess the site state, and route to the right content skill.
-
-> **Never call Jahia's GraphQL API directly for content operations.** Use only MCP tools via the `jahia` MCP server. If a capability is missing, report it — do not work around with curl/GraphQL.
-
----
-
-## Step 1 — Verify the MCP connection
-
-Confirm the `jahia` MCP server is available:
-
-```
-tool: site.list
-```
-
-If this fails, Jahia or the MCP connection is not ready.
-
----
-
-## Step 2 — Detect the site state
-
-Run these checks to understand what exists already:
-
-### A. List available sites
-
-```
-tool: site.list
-```
-
-### B. Discover installed template sets for new site creation
-
-```
-tool: site.templateSets
-args: {}
-```
-
-### C. If a site exists, list its pages
-
-```
-tool: page.list
-args: { "siteKey": "SITE_KEY" }
-```
-
----
-
-## Step 3 — Report the CMS state
-
-Summarize what you found:
-
-```
-🌐 Jahia MCP:       ✅ connected
-📁 Sites:           <site keys>
-🧱 Template sets:   <installed template sets>
-📄 Pages:           <page titles and templates for the chosen site>
-```
-
----
-
-## Step 4 — Route to the right sub-skill
-
-| User intent | Skill |
-|-------------|-------|
-| Explore an unknown site, map areas, inspect types and properties | `/jahia-content-explore-structure` |
-| Create a brand-new site before authoring content | `/jahia-content-create-content` using `site.templateSets` and `site.create` |
-| Create pages, content, or structured trees on an existing site | `/jahia-content-create-content` |
-| Upload files and images to `/sites/<siteKey>/files` | `/jahia-content-media-upload` |
-| Find, inspect, or audit existing content | `/jahia-content-query-content` |
-| Move, copy, rename, reorder, or delete content | `/jahia-content-organize` |
-| Translate content to another locale | `/jahia-content-translate-content` |
-| Publish, unpublish, or check readiness | `/jahia-content-publish` |
-| Do several of the above in sequence | Start with `/jahia-content-explore-structure` if the site is unfamiliar |
-
----
-
-## Direct MCP patterns
-
-### Create a site before authoring pages
-
-```
-tool: site.templateSets
-args: {}
-
-tool: site.create
-args: {
-  "siteKey": "brandSite",
-  "title": "Brand Site",
-  "templateSet": "digitall",
-  "defaultLanguage": "en",
-  "languages": ["en", "fr"],
-  "serverName": "brand.local"
-}
-```
-
-### Publish a page or subtree
-
-```
-tool: publication.publish
-args: {
-  "path": "/sites/SITE_KEY/home/about",
-  "languages": ["en"]
-}
-```
-
-### Unpublish a page or subtree
-
-```
-tool: publication.unpublish
-args: {
-  "path": "/sites/SITE_KEY/home/about",
-  "languages": ["en"]
-}
-```
-
-### Delete a published node correctly
-
-```
-tool: content.markForDeletion
-args: { "path": "/sites/SITE_KEY/home/old-page" }
-
-tool: publication.publish
-args: {
-  "path": "/sites/SITE_KEY/home/old-page",
-  "languages": ["en"]
-}
-```
-
----
-
-## Full skill map
-
-```
-/jahia-content-explore-structure   Map sites, template sets, pages, areas, and content definitions
-/jahia-content-create-content      Create sites, pages, content nodes, and structured trees
-/jahia-content-media-upload        Upload media and reference it from content
-/jahia-content-query-content       List, inspect, and search content via MCP tools
-/jahia-content-organize            Move, copy, rename, reorder, mark for deletion, and delete content
-/jahia-content-move-content        Focused move/reorder/delete workflow for an existing content tree
-/jahia-content-translate-content   Translate i18n content and page titles
-/jahia-content-publish             Check publication status, publish, unpublish, and handle workflow
-```
-
----
-
-## Critical rules
-
-- Always use MCP tools — never GraphQL directly
-- Use `site.templateSets` and `site.create` when the requested site does not exist yet
-- Always pass `locale` to content creation and update calls
-- Always publish after creating, moving, deleting, or translating content
-- Always explore with `/jahia-content-explore-structure` before authoring on an unfamiliar site
-