@jahia/agentic 0.4.1 → 0.5.0

package/dist/kiro/.kiro/skills/jahia-dev-debug/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: jahia-dev-debug
+description: Debugs a Jahia JavaScript module end-to-end — build, deploy, and runtime errors. Finds the first error after deployment using live Docker logs.
+---
+
+# Skill: jahia-dev-debug
+
+Diagnoses why a Jahia JavaScript module fails to load. Follows the deployment pipeline from source to runtime.
+
+---
+
+## Step 1 — Build
+
+From the module directory (where `package.json` is):
+
+```bash
+yarn build
+```
+
+- **Build fails** → fix the TypeScript / bundling error shown and stop here. Do not proceed to deploy until the build is clean.
+- **Build succeeds** → proceed to Step 2.
+
+---
+
+## Step 2 — Deploy
+
+```bash
+yarn jahia-deploy
+```
+
+Interpret the output:
+- `"Operation successful"` in the response → deployment was accepted. Proceed to Step 3 — the module may still fail at runtime.
+- `"{}"` or empty JSON → deployment was **rejected** (usually a CND parse error or missing dependency). Proceed to Step 3 to find the cause in the logs.
+- Any other error → fix the connection issue (is Docker running?) then retry.
+
+---
+
+## Step 3 — Watch live Docker logs
+
+> Do NOT analyse logs that already exist — an old error is not necessarily the cause of the current issue. Start a fresh log stream, then deploy again to capture only what happens as a result of this deployment.
+
+### 3a — Start watching logs in the background
+
+Find the Jahia container name:
+
+```bash
+docker ps --format '{{.Names}}' | grep -i jahia | head -1
+```
+
+Then start tailing:
+
+```bash
+docker logs -f <container-name> 2>&1 | grep -v "^\s*$" &
+LOG_PID=$!
+```
+
+### 3b — Deploy again while logs are streaming
+
+```bash
+yarn jahia-deploy
+```
+
+### 3c — Wait ~15 seconds, then stop the log stream
+
+```bash
+sleep 15 && kill $LOG_PID 2>/dev/null
+```
+
+### 3d — Verify component registration
+
+```bash
+docker logs <container-name> 2>&1 | grep "Registered Jahia component"
+```
+
+Expected: one line per view registered, e.g.:
+```
+Registered Jahia component: mymodule_view_ns:hero_default
+Registered Jahia component: mymodule_view_ns:hero_small
+```
+
+If a component you just deployed is **absent** from this list, its `jahiaComponent` call was never reached — usually a syntax/import error in the view file that prevented the module from fully loading.
+
+---
+
+## Step 4 — Find the first error
+
+Scan the captured log output for the **first** error that appears **after** the deploy timestamp. Common patterns to look for:
+
+| Pattern | Likely cause |
+|---|---|
+| `CND parse error` / `invalid node type` | CND syntax error or illegal field declaration |
+| `NoSuchNodeTypeException` | A referenced type doesn't exist (wrong namespace, typo, missing dependency) |
+| `ClassNotFoundException` / `NoClassDefFoundError` | Java dependency missing |
+| `Cannot set property` / `TypeError` in JS stack | View runtime error |
+| `Module ... failed to start` | Any of the above |
+| `Unresolved requirement` | OSGi dependency not satisfied |
+| Missing `Registered Jahia component` for a specific type | View file has a syntax/import error, or `jahiaComponent` not reached |
+
+**Focus on the first error, not the last.** Later errors are often cascading failures caused by the first one.
+
+---
+
+## Step 5 — Fix and retry
+
+Once the root cause is identified:
+
+1. Fix the issue in the source files
+2. Run `yarn build` again
+3. Go back to Step 2
+
+Repeat until `yarn jahia-deploy` succeeds and the module loads cleanly (no errors in the 15-second window after deploy).
+
+---
+
+## Common fixes by error type
+
+### CND: `j:linknode` or `j:url` declared explicitly
+These fields are injected by Jahia's `linkTypeInitializer` mixin. Remove them from the CND.
+
+### CND: unknown mixin or type
+Check that the namespace is declared at the top of `settings/definitions.cnd` and that all referenced types exist.
+
+### import.xml: reference to a non-existent type
+Any `jcr:primaryType` or `jcr:mixinTypes` value in `import.xml` must exist in the deployed CND. Check for typos.
+
+### import.xml: `jmix:nolive` used as `jcr:primaryType`
+`jmix:nolive` is a mixin — it goes in `jcr:mixinTypes`, not `jcr:primaryType`.
+
+### import.xml: OSGi fails with `missing requirement … (nodetypes=jmix:nolive)`
+Every `jcr:mixinTypes` value in `import.xml` is scanned by the OSGi bundle resolver. If the mixin is not declared in the module's own CND and is not provided by a resolvable dependency, the bundle will not start. Correct spelling is `jmix:nolive` (all lowercase). Verify the mixin exists in your Jahia instance before using it in `import.xml`.
+
+### View: module loads but page is blank
+Run `yarn dev` and check the Vite / SSR console for a React render error.
+
+---
+
+## GraalJS (server-side JS) debugging with Chrome DevTools
+
+Use this when you need to step through server-side view code running inside GraalVM.
+
+### Step 1 — Enable the inspector via GraphQL
+
+In Jahia's Developer Tools > GraphQL editor, run:
+
+```graphql
+mutation {
+  admin {
+    jahia {
+      configuration(pid: "org.jahia.modules.javascript.modules.engine.jsengine.GraalVMEngine") {
+        polyGlotInspect: value(name: "polyglot.inspect", value: "0.0.0.0:9229")
+        polyGlotInspectSuspend: value(name: "polyglot.inspect.Suspend", value: "false")
+        polyGlotInspectSecure: value(name: "polyglot.inspect.Secure", value: "false")
+      }
+    }
+  }
+}
+```
+
+### Step 2 — Map the port
+
+If running in Docker, ensure port `9229` is mapped in `docker-compose.yml`:
+
+```yaml
+ports:
+  - "9229:9229"
+```
+
+### Step 3 — Connect Chrome
+
+After the mutation, Jahia logs a `devtools://...` URL. Open it in Chrome (use latest; Chrome 117–118 had known debugger bugs).
+
+### Step 4 — Set a breakpoint and debug
+
+In Chrome DevTools Sources tab, open `<module>/dist/main.js`, set a breakpoint, then reload the page. The server-side render pauses at the breakpoint. Full scope inspection, step-over, and continue are supported.
+
+The config file `org.jahia.modules.javascript.modules.engine.jsengine.GraalVMEngine.cfg` accepts any `polyglot.*` key as an engine option — you can persist these settings there instead of using the GraphQL mutation.

package/dist/kiro/.kiro/skills/jahia-dev-import-from/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: jahia-dev-import-from
+description: Builds a Jahia component inspired by a component on an external URL. Fetches the page, lets the developer target one section, extracts its HTML structure and CSS/JS dependencies, then creates a proper CND + view. Use when asked to "create a component like the one on this page".
+allowed-tools: Bash, Read, Write, Edit, WebFetch
+---
+
+# Skill: jahia-dev-import-from
+
+Turns a component on an external website into a Jahia component. This is a developer workflow — the result uses CSS Modules, proper Jahia architecture, and is maintainable code. It is not a wholesale site clone.
+
+---
+
+## Step 1 — Fetch and map the page
+
+Fetch the URL with `WebFetch`. If WebFetch fails (403/503), fall back to:
+
+```bash
+wget --quiet --user-agent="Mozilla/5.0" -O /tmp/imported-page.html "<URL>"
+```
+
+Scan the HTML for semantic section boundaries (`<section>`, `<article>`, `<header>`, `<footer>`, `<main>`, or `<div>` with class names matching patterns like `hero`, `banner`, `card`, `grid`, `slider`, `features`).
+
+Print a numbered text map:
+
+```
+[1] HEADER     — logo + nav + CTA button
+[2] HERO       — animated text + background image + scroll indicator
+[3] FEATURES   — 3-column icon grid
+[4] CAROUSEL   — auto-sliding testimonials (Swiper)
+[5] FOOTER     — 4-column links + social icons
+```
+
+Ask the developer: **"Which section do you want to implement?"**
+
+---
+
+## Step 2 — Extract the HTML fragment
+
+Locate the target section in the fetched HTML. Extract the **complete HTML block** — every element, every attribute, every nesting level. Do not simplify, summarize, or rewrite any part of it.
+
+**For repeating patterns** (card grid, carousel), copy the wrapper structure **plus one complete child item** with all its attributes.
+
+**Replace only dynamic content** with typed placeholders:
+
+| Source HTML | Replacement |
+|---|---|
+| Text inside an element | `{title}`, `{description}`, etc. |
+| Image `src` / `data-bg` / `data-src` URL | `{image}` (will become a `weakreference` field) |
+| Link `href` | `{href}` (will become `j:linkType` / `j:linknode`) |
+
+**Keep verbatim:**
+- All CSS classes
+- All `data-*` attributes (animation libraries, carousel config, IDs)
+- `aria-*` and `role` attributes
+- `<noscript>` blocks and `<picture>/<source>` elements
+- Carousel/slider wrapper `id`s — JS libraries use these for initialization
+
+> ⚠️ Self-check: count the attributes on 2–3 key elements in the source HTML. If your extraction has fewer, you dropped something — re-extract.
+
+---
+
+## Step 3 — Identify content fields vs structural HTML
+
+Show the developer a proposed split:
+
+**Will become CND fields (editable in Jahia):**
+- User-facing text: titles, subtitles, descriptions, button labels
+- Images (→ `weakreference, picker[type='image']`)
+- Links (→ `j:linkType / j:linknode / j:url`)
+- Any value that should vary between instances
+
+**Will be hardcoded in the view:**
+- Layout wrapper divs
+- Icon SVGs that are decorative / never change
+- Animation class names and `data-*` config attributes
+- ARIA labels that are structural (e.g. `aria-label="Main navigation"`)
+
+Ask the developer to confirm or adjust. If they want something to be editable that wasn't identified, add it as a field.
+
+---
+
+## Step 4 — Identify CSS and JS dependencies
+
+Scan the page `<head>` for resources that the target component depends on:
+
+```bash
+# From downloaded HTML, extract stylesheet and script references
+grep -E '<link[^>]+stylesheet|<script[^>]+src' /tmp/imported-page.html | head -30
+```
+
+Categorize findings:
+
+| Type | Examples | Action |
+|---|---|---|
+| **Animation library** | AOS, GSAP, ScrollReveal, Animate.css | Likely needed — check npm first |
+| **Carousel/slider** | Swiper, Glide, Owl Carousel, Splide | Likely needed — check npm first |
+| **Utility CSS** | Bootstrap, Tailwind | May already be in the module or can be imported |
+| **Site-specific CSS** | `main.css`, `theme.css` | Targeted import only (see Step 5b) |
+| **Fonts** | Google Fonts, custom woff2 | Import if not already in the module |
+
+Report findings, then ask: **"Should I import any of these? (yes / no / specific ones)"**
+
+---
+
+## Step 5 — Create the Jahia component
+
+### Step 5a — CND and view
+
+Using the confirmed field split from Step 3, run the `jahia-dev-define-content-type` and `jahia-dev-create-view` patterns to create:
+
+- `src/components/<Category>/<Name>/definition.cnd`
+- `src/components/<Category>/<Name>/types.ts`
+- `src/components/<Category>/<Name>/default.server.tsx`
+- `src/components/<Category>/<Name>/component.module.css`
+
+**TSX conversion rules** (mechanical, not creative):
+
+1. `class="foo bar"` → `className="foo bar"` — keep class strings as-is if vendor CSS is imported, OR map to `classes.fooBar` if authoring new CSS
+2. Void elements: `<img>`, `<input>`, `<br>` → add ` />`
+3. `{placeholder}` → `{propName}` matching `Props`
+4. Every `data-*`, `aria-*`, `id`, `<noscript>`, `<source>` stays in the TSX
+
+**CSS Modules:** Write new CSS in `component.module.css` that achieves the same visual result. Rename source class names to semantic camelCase keys (`hero__title` → `.heroTitle`). Exception: if you're importing the original CSS as a static asset, use the original class names as plain strings — CSS Modules would rename them and break the imported CSS.
+
+**Interactive components** (animations, carousels, event handlers) → Island architecture:
+
+```tsx
+// default.server.tsx — passes config, initializes nothing
+({ title, subtitle }: Props, { renderContext }) => (
+  <Island component={MyComponentClient} props={{ title, subtitle }} />
+)
+
+// MyComponent.client.tsx — owns the browser-side lifecycle
+import { useEffect } from "react";
+
+export default function MyComponentClient({ title, subtitle }: Props) {
+  useEffect(() => {
+    import("aos").then(({ default: AOS }) => AOS.init({ duration: 800 }));
+  }, []);
+
+  return (
+    <div data-aos="fade-up" className="hero">
+      <h1>{title}</h1>
+    </div>
+  );
+}
+```
+
+**Edit mode for carousels/sliders:** Render all items flat so editors can see and reorder them:
+
+```tsx
+({ slides }, { renderContext }) =>
+  renderContext.isEditMode() ? (
+    <div className={classes.editStack}>
+      <RenderChildren />
+      <p className={classes.hint}>Carousel — add or reorder slides above</p>
+    </div>
+  ) : (
+    <Island component={CarouselClient} props={{ count: slides?.length }} />
+  )
+```
+
+---
+
+### Step 5b — Import static assets (if confirmed in Step 4)
+
+For each confirmed CSS file:
+
+```bash
+mkdir -p static/css
+curl -sL "<css-url>" -o "static/css/<filename>.css"
+```
+
+For JS libraries — prefer npm over manual download:
+
+```bash
+# Check if available on npm
+npm info <library-name> version 2>/dev/null
+
+# If available:
+yarn add <library-name>
+# Then import in the .client.tsx: import AOS from "aos";
+
+# If not on npm, download to static:
+mkdir -p static/js
+curl -sL "<js-url>" -o "static/js/<filename>.js"
+```
+
+For fonts:
+
+```bash
+mkdir -p static/fonts
+curl -sL "<font-url>" -o "static/fonts/<filename>.woff2"
+```
+
+Update the module's `Layout` template (`src/templates/Layout.server.tsx` or `src/templates/Layout.jsx`) to include the assets:
+
+```tsx
+import { AddResources, buildModuleFileUrl } from "@jahia/javascript-modules-library";
+
+// In the <head> section:
+<AddResources type="css" url={buildModuleFileUrl("static/css/vendor.css")} />
+<AddResources type="javascript" url={buildModuleFileUrl("static/js/aos.js")} />
+```
+
+Update `package.json` → `jahia.static-resources` to expose the static directories:
+
+```json
+{
+  "jahia": {
+    "static-resources": "/dist/client,/dist/assets,/locales,/static/css,/static/js,/static/fonts"
+  }
+}
+```
+
+> **Never hardcode `/modules/<name>/...` paths** — use `buildModuleFileUrl` so the path resolves correctly across environments and module name changes.
+
+---
+
+## Step 6 — Build, deploy, and verify
+
+```bash
+yarn build && yarn jahia-deploy
+```
+
+Verify the component registered:
+
+```bash
+docker logs $(docker ps --format '{{.Names}}' | grep -i jahia | head -1) 2>&1 \
+  | grep "Registered Jahia component" | grep "<ComponentName>"
+```
+
+Expected: one line per view. If absent, check the build output for TypeScript errors in the new view file.
+
+---
+
+## Rules that always apply
+
+- **CSS Modules for authored styles** — use `classes.propertyName`, not plain string class names
+- **Vendor class names stay as-is** — when importing external CSS, don't route those classes through CSS Modules
+- **No hardcoded links** — `href` and `src` must come from JCR props or `buildModuleFileUrl`
+- **Island for anything interactive** — animations, browser events, `useState`, third-party JS → `.client.tsx`
+- **All props optional in `types.ts`** — even CND `mandatory` fields
+- **Edit mode awareness** — carousels, sliders, and tabs should render flat in edit mode

package/dist/kiro/.kiro/skills/jahia-dev-jexperience/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: jahia-dev-jexperience
+description: Integrate a Jahia JavaScript module with jExperience and jCustomer — set up the local stack, push visitor events from client components, visualize data in Kibana, and package dashboards for deployment.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+## What is jExperience / jCustomer?
+
+**jCustomer** (built on Apache Unomi) collects and processes visitor events to create personalized digital experiences. **jExperience** is the Jahia module that bridges Jahia with jCustomer — it injects the `window.wem` tracker into every page and exposes dashboards inside jContent.
+
+Together they form Jahia's **DXP** (Digital Experience Platform). You only need this skill when you want to track interactions, build personalization, or visualize visitor data.
+
+---
+
+## Step 1 — Set up jCustomer locally
+
+### 1a — Update `docker-compose.yml`
+
+Give the `jahia` service a static IP, add three containers, and declare the subnet:
+
+```yaml
+services:
+  jahia:
+    # ... existing config ...
+    networks:
+      default:
+        ipv4_address: 172.16.1.100
+
+  elasticsearch:
+    image: elasticsearch:7.17.28
+    ports:
+      - 9200:9200
+    environment:
+      discovery.type: single-node
+      cluster.name: jahia-es-cluster
+
+  kibana:
+    image: kibana:7.17.28
+    ports:
+      - 5601:5601
+    environment:
+      discovery.type: single-node
+      elasticsearch.hosts: http://elasticsearch:9200
+
+  jcustomer:
+    image: jahia/jcustomer:2.6
+    depends_on:
+      - elasticsearch
+    ports:
+      - 9443:9443
+      - 8181:8181
+      - 8102:8102
+    environment:
+      UNOMI_ELASTICSEARCH_ADDRESSES: elasticsearch:9200
+      UNOMI_ELASTICSEARCH_CLUSTERNAME: jahia-es-cluster
+      UNOMI_CLUSTER_PUBLIC_ADDRESS: http://localhost:8181
+      UNOMI_CLUSTER_INTERNAL_ADDRESS: https://jcustomer:9443
+      UNOMI_THIRDPARTY_PROVIDER1_IPADDRESSES: 172.16.1.100
+      UNOMI_THIRDPARTY_PROVIDER1_ALLOWEDEVENTS: login,updateProperties
+      UNOMI_ROOT_PASSWORD: karaf
+      UNOMI_HAZELCAST_TCPIP_MEMBERS: jcustomer
+
+networks:
+  default:
+    ipam:
+      config:
+        - subnet: 172.16.1.0/24
+```
+
+### 1b — Update `docker/provisioning.yml`
+
+Append at the end of the file:
+
+```yaml
+# Install and start jExperience
+- installModule:
+    - "mvn:org.jahia.modules/jexperience/3.6.2"
+    - "mvn:org.jahia.modules/jexperience-dashboards/1.0.0"
+  autoStart: true
+  uninstallPreviousVersion: true
+
+# Connect jExperience to jCustomer
+- editConfiguration: "org.jahia.modules.jexperience.settings"
+  configIdentifier: "global"
+  properties:
+    jexperience.jCustomerURL: "https://jcustomer:9443"
+    jexperience.jCustomerUsername: "karaf"
+    jexperience.jCustomerPassword: "karaf"
+    jexperience.jCustomerTrustAllCertificates: "true"
+    jexperience.jCustomerUsePublicAddressesForAdmin: "false"
+    jexperience.jCustomerKey: "670c26d1cc413346c3b2fd9ce65dab41"
+
+# Configure Kibana dashboards proxy
+- editConfiguration: "org.jahia.modules.kibana_dashboards_provider"
+  properties:
+    kibana_dashboards_provider.kibanaURL: "http://kibana:5601"
+    kibana_dashboards_provider.kibanaUser: "elastic"
+    kibana_dashboards_provider.kibanaPassword: "ELASTIC_PASSWORD"
+    kibana_dashboards_provider.KibanaProxy.enable: "true"
+    kibana_dashboards_provider.KibanaProxy.cloud: "true"
+- installModule:
+    - "mvn:org.jahia.modules/kibana-dashboards-provider/1.4.0"
+  autoStart: true
+  uninstallPreviousVersion: true
+```
+
+### 1c — Start the stack
+
+```bash
+docker compose down jahia && docker compose up --wait
+```
+
+### 1d — Enable jExperience on the site
+
+1. Open **Administration → Modules → jExperience → Usage in sites**
+2. Check the box next to your site. Repeat for **jExperience Dashboards**.
+3. Open jContent — a new **jExperience** tab should appear in the vertical bar (refresh if needed).
+
+---
+
+## Step 2 — Push events from a client component
+
+jExperience injects `window.wem` (Web Experience Manager) into every page. It is only available in the browser — use it inside `.client.tsx` files.
+
+### Event model
+
+Every event has two parts:
+
+| Part | What it is | Helper |
+|------|------------|--------|
+| **source** | Where the event happened (usually the current page) | `wem.buildSourcePage()` |
+| **target** | What happened (the action) | `wem.buildTarget(id, type, properties)` |
+
+### Full example — feedback widget
+
+```tsx
+// src/components/FeedbackWidget/definition.cnd
+// [hydrogen:feedbackWidget] > jnt:content, hydrogenmix:component
+//  - question (string) = 'Was this helpful?'
+```
+
+```tsx
+// Widget.client.tsx
+import { useState } from "react";
+
+export default function Widget({ question }: { question: string }) {
+  const [sent, setSent] = useState(false);
+
+  const handler = (happy: boolean) => () => {
+    const source = wem.buildSourcePage();
+    const target = wem.buildTarget("feedback", "click", { happy });
+    const event = wem.buildEvent("click", target, source);
+    wem.collectEvents({ events: [event] });
+    setSent(true);
+  };
+
+  if (sent) return <aside>Thank you for your feedback!</aside>;
+
+  return (
+    <aside>
+      {question}
+      <button type="button" onClick={handler(true)}>Yes</button>
+      <button type="button" onClick={handler(false)}>No</button>
+    </aside>
+  );
+}
+```
+
+```tsx
+// default.server.tsx
+import { jahiaComponent, Island } from "@jahia/javascript-modules-library";
+import Widget from "./Widget.client.jsx";
+
+interface Props { question: string; }
+
+jahiaComponent(
+  { nodeType: "hydrogen:feedbackWidget", componentType: "view" },
+  ({ question }: Props) => (
+    <Island clientOnly component={Widget} props={{ question }}>
+      Loading…
+    </Island>
+  ),
+);
+```
+
+### `window.wem` API reference
+
+| Method | Signature | Returns |
+|--------|-----------|---------|
+| `buildSourcePage` | `()` | Source object for the current page |
+| `buildTarget` | `(id: string, type: string, properties?: object)` | Target object |
+| `buildEvent` | `(eventType: string, target, source)` | Event object |
+| `collectEvents` | `({ events: Event[] })` | Sends events to jCustomer |
+
+`buildTarget` properties are free-form — pass any serializable data you want to analyse downstream (e.g. `{ happy: true }`, `{ productId: "p-123" }`).
+
+> The `window.wem` object comes from the [apache/unomi-tracker](https://github.com/apache/unomi-tracker) package. Refer to its documentation for advanced event types.
+
+### Google Tag Manager alternative
+
+If your site uses GTM instead of jCustomer:
+
+```tsx
+dataLayer.push({ event: "feedback", happy });
+```
+
+---
+
+## Step 3 — Verify events in Kibana
+
+1. Open [localhost:5601](http://localhost:5601)
+2. Go to **Discover**, select the `*-event` index, and expand the time range
+3. Browse an event — confirm the `source.properties.pageInfo.pagePath` and `target.properties.happy` fields are present
+
+---
+
+## Step 4 — Create a Kibana dashboard
+
+### Create a saved search
+
+In **Discover**, add column filters for:
+- `eventType` = `click`
+- `itemType` = `event`
+- `target.itemId` = `feedback`
+- `target.itemType` = `click`
+
+Add display columns: `source.properties.pageInfo.pagePath`, `target.properties.happy`. Save as e.g. **All Feedbacks**.
+
+### Create the dashboard
+
+1. **Dashboards → Create dashboard**
+2. **Add from library** → add the saved search (table of all feedbacks)
+3. **Create visualization** → paste this KQL filter into the search bar:
+   ```
+   eventType: click and itemType: event and target.itemId: feedback and target.itemType: click
+   ```
+4. Drop **Records** onto the panel, then in **Break down by** select `target.properties.happy`. Use the **Status** color palette for red/green.
+5. **Save and return**, then **Save** the dashboard with a meaningful name — this name becomes the entry label inside Jahia's jExperience tab.
+
+---
+
+## Step 5 — Package the dashboard in the module
+
+Dashboards exported from Kibana are automatically imported when the module is deployed.
+
+1. In Kibana go to **Analytics → Overview → Manage → Saved Objects**
+2. Select your dashboard, click **Export** — you get a `.ndjson` file
+3. Save it to your module:
+   ```
+   settings/kibana-dashboard/dashboards/<dashboard-name>.ndjson
+   ```
+4. Deploy the module — the dashboard will appear in the jExperience tab on any Jahia instance running the module.
+
+---
+
+## Validation checklist
+- [ ] `docker compose up --wait` completed with elasticsearch, kibana, jcustomer healthy
+- [ ] jExperience and jExperience Dashboards enabled on the target site
+- [ ] jExperience tab visible in jContent
+- [ ] Client component uses `.client.tsx` extension and `Island clientOnly`
+- [ ] `wem.collectEvents` called with a valid event (source + target)
+- [ ] Events visible in Kibana Discover under `*-event` index
+- [ ] Dashboard saved and visible under the jExperience tab in Jahia
+- [ ] Dashboard `.ndjson` saved to `settings/kibana-dashboard/dashboards/` for packaging
+
+## References
+- Apache Unomi tracker: https://github.com/apache/unomi-tracker
+- KQL query syntax: https://www.elastic.co/guide/en/kibana/current/kuery-query.html
+- jExperience guide: https://github.com/Jahia/javascript-modules/blob/main/docs/2-guides/1-building-a-feedback-form/README.md