@jahia/agentic 0.2.0 → 0.4.0

package/dist/codex/.agents/skills/jahia-content-translate-content/SKILL.md

@@ -1,273 +1,208 @@
 ---
 name: jahia-content-translate-content
-description: Adds language support to a Jahia site and translates existing content nodes. Use when asked to add a new language, fill in missing translations, or audit which content lacks i18n values.
+description: Adds site languages and translates existing Jahia content using MCP tools. Use when asked to enable a locale, fill in missing translations, or publish translated pages and content.
 ---
 
 # Skill: jahia-content-translate-content
 
-Adds languages to a Jahia site and populates i18n properties on existing content nodes via the GraphQL API.
+Translates existing content and manages multi-language support using MCP tools via the `jahia` MCP server.
+
+> **Never call Jahia's GraphQL API directly.** Use only MCP tools. If a capability is missing, report it — do not work around with curl/GraphQL.
 
 ---
 
 ## Prerequisites
 
-- Jahia running at `http://localhost:8080`
-- Credentials: `root` / `root1234` (default)
-- GraphQL endpoint: `http://localhost:8080/modules/graphql`
-
-**Always include both auth flags:**
-```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": "..."}'
-```
-
-> ⚠️ The `Origin` header is **required** — omitting it returns `Permission denied`.
+- MCP server `jahia` connected with a valid API token
+- Know the target `siteKey` (call `site.list` if unsure)
+- Content already exists in a source locale
 
 ---
 
-## Step 1 — Enable the new language on the site
-
-Before creating or querying translations, the language must be declared on the site node.
-
-```bash
-# Check currently enabled languages
-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\") { properties(names: [\"j:languages\",\"j:defaultLanguage\"]) { name values } } } }"
-  }'
-
-# Add a language (e.g. "fr") — use setPropertiesBatch with the full new list
-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\") { setPropertiesBatch(properties: [{name: \"j:languages\", values: [\"en\", \"fr\"]}]) { path } } } }"
-  }'
+## Step 1 — Check site languages
+
+```
+tool: site.get
+args: { "siteKey": "SITE_KEY" }
 ```
 
-> ⚠️ `j:languages` is a multi-valued property — always pass the **complete** list of languages, not just the new one. Passing only `["fr"]` would remove `"en"`.
+Check `languages` and `defaultLanguage`.
 
----
+- If the target locale is already present, continue.
+- If the target locale is missing, add it to the site first before writing translations.
 
-## Step 2 — Audit content missing translations
+---
 
-Query all i18n-bearing nodes and inspect which ones have empty values for the target language:
+## Step 2 — Read the source content
 
-```bash
-# Find all content nodes under /sites/mySite/contents
-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 { nodesByQuery(query: \"SELECT * FROM [jmix:i18n] WHERE ISDESCENDANTNODE(\u0027/sites/mySite/contents\u0027) ORDER BY [jcr:path] ASC\", queryLanguage: SQL2) { nodes { path primaryNodeType { name } properties(language: \"fr\") { name value } } } } }"
-  }'
+```
+tool: content.get
+args: {
+  "path": "/sites/SITE_KEY/home/about/main/intro-text",
+  "locale": "en"
+}
 ```
 
-Or query a specific content type:
+Note the properties that actually contain human-readable text.
 
-```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 { nodesByQuery(query: \"SELECT * FROM [namespace:article] WHERE ISDESCENDANTNODE(\u0027/sites/mySite/contents\u0027)\", queryLanguage: SQL2) { nodes { path properties(language: \"fr\") { name value } } } } }"
-  }'
-```
+To find a batch of nodes to translate:
 
-Look for nodes where i18n fields (`jcr:title`, `body`, etc.) have empty or null `value`.
+```
+tool: content.search
+args: {
+  "siteKey": "SITE_KEY",
+  "nodeType": "jmix:droppableContent",
+  "locale": "en",
+  "limit": 50
+}
+```
 
 ---
 
-## Step 3 — Set i18n properties
-
-### Single node
+## Step 3 — Identify which properties are i18n
 
-```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\") { setPropertiesBatch(properties: [{name: \"jcr:title\", value: \"Mon article\", language: \"fr\"}, {name: \"body\", value: \"<p>Contenu ici</p>\", language: \"fr\"}]) { path } } } }"
-  }'
+```
+tool: content.type
+args: { "name": "jnt:bigText" }
 ```
 
-> ⚠️ Use `setPropertiesBatch` (plural), not `setProperty` (singular — does not exist in the Jahia GraphQL API).
+Translate only properties marked as internationalized.
 
-### Critical ordering rule
+Common i18n properties:
+- `jcr:title`
+- `text`
+- `body`
+- `description`
+- `subtitle`
 
-When a content type has **mandatory** i18n fields (other than `jcr:title`), set those **before** `jcr:title`. Setting `jcr:title` first can trigger a constraint check before all mandatory fields are present.
+Common non-i18n properties:
+- `j:view`
+- `j:templateName`
+- `jcr:primaryType`
+- references such as `j:node`
+- numeric or technical settings
 
-The safe pattern — set all mandatory i18n fields in a single `setPropertiesBatch` call:
+---
 
-```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\") { setPropertiesBatch(properties: [{name: \"body\", value: \"<p>Contenu ici</p>\", language: \"fr\"}, {name: \"jcr:title\", value: \"Mon article\", language: \"fr\"}]) { path } } } }"
-  }'
-```
+## Step 4 — Write translated properties
 
----
+Use `content.update` with the target locale:
 
-## Step 4 — Bulk translation with Python
+```
+tool: content.update
+args: {
+  "path": "/sites/SITE_KEY/home/about/main/intro-text",
+  "locale": "fr",
+  "properties": {
+    "jcr:title": "À propos",
+    "text": "<p>Bienvenue sur notre site.</p>"
+  }
+}
+```
 
-For translating many nodes at once:
+Key rules:
+- Set all mandatory i18n properties in the same call.
+- Translate only i18n properties.
+- Preserve the HTML structure for rich text.
+- Do not translate technical choicelist values.
 
-```python
-import json
-from urllib.request import Request, urlopen
+---
 
-JAHIA = "http://localhost:8080"
-AUTH = ("root", "root1234")
+## Step 5 — Translate page titles
 
-import base64
-token = base64.b64encode(f"{AUTH[0]}:{AUTH[1]}".encode()).decode()
-HEADERS = {
-    "Content-Type": "application/json",
-    "Origin": JAHIA,
-    "Authorization": f"Basic {token}",
-}
+Page titles are also i18n:
 
-def gql(query):
-    body = json.dumps({"query": query}).encode()
-    req = Request(f"{JAHIA}/modules/graphql", data=body, headers=HEADERS, method="POST")
-    with urlopen(req) as r:
-        d = json.loads(r.read())
-    if "errors" in d:
-        print("ERR:", d["errors"][0]["message"][:120])
-    return d
-
-# 1. List all articles missing French title
-result = gql(
-    '{ jcr { nodesByQuery(query: "SELECT * FROM [namespace:article] '
-    "WHERE ISDESCENDANTNODE('/sites/mySite/contents') "
-    'ORDER BY [jcr:path] ASC", queryLanguage: SQL2) '
-    '{ nodes { path properties(language: "fr") { name value } } } } }'
-)
-
-nodes = result["data"]["jcr"]["nodesByQuery"]["nodes"]
-missing_fr = [
-    n["path"]
-    for n in nodes
-    if not any(p["name"] == "jcr:title" and p["value"] for p in n["properties"])
-]
-
-# 2. Set French translations (replace with actual translated values)
-translations = {
-    "/sites/mySite/contents/articles/article-1": ("Titre FR 1", "<p>Corps FR 1</p>"),
-    "/sites/mySite/contents/articles/article-2": ("Titre FR 2", "<p>Corps FR 2</p>"),
+```
+tool: content.update
+args: {
+  "path": "/sites/SITE_KEY/home/about",
+  "locale": "fr",
+  "properties": {
+    "jcr:title": "À propos"
+  }
 }
-
-for path, (title, body) in translations.items():
-    r = gql(
-        f'mutation {{ jcr {{ mutateNode(pathOrId: "{path}") {{'
-        f' setPropertiesBatch(properties: ['
-        f'  {{name: "body", value: {json.dumps(body)}, language: "fr"}},'
-        f'  {{name: "jcr:title", value: {json.dumps(title)}, language: "fr"}}'
-        f' ]) {{ path }} }} }} }}'
-    )
-    ok = "errors" not in r
-    print(f"  {'✓' if ok else '✗'} {path.split('/')[-1]}")
 ```
 
 ---
 
-## Step 5 — Choicelist fields and view-level translations
+## Step 6 — Verify translations
 
-### Choicelist fields should NOT be i18n
+Check the translated locale directly:
 
-If a CND property uses a choicelist (e.g. `category`, `status`), its stored values are language-agnostic keys like `"featured"` or `"draft"`. The display label is translated **in the view**, not in the JCR.
+```
+tool: content.get
+args: {
+  "path": "/sites/SITE_KEY/home/about/main/intro-text",
+  "locale": "fr"
+}
+```
 
-```tsx
-// In the view component — translate the stored key to a display label
-const STATUS_LABELS: Record<string, Record<string, string>> = {
-  en: { featured: "Featured", draft: "Draft" },
-  fr: { featured: "En vedette", draft: "Brouillon" },
-};
+Or search in the target locale:
 
-const lang = renderContext.getMainResourceLocale().getLanguage();
-const statusKey = properties.status as string;
-const statusLabel = STATUS_LABELS[lang]?.[statusKey] ?? statusKey;
+```
+tool: content.search
+args: {
+  "siteKey": "SITE_KEY",
+  "nodeType": "jmix:droppableContent",
+  "locale": "fr",
+  "limit": 20,
+  "projectProperties": ["jcr:title"]
+}
 ```
 
-Do **not** add `i18n` to the CND property for choicelists — the key should be the same in all languages.
-
-### Hardcoded UI strings
+---
 
-View-level strings that are not stored in JCR (button labels, headings, placeholder text) need locale-keyed label maps in the component:
+## Step 7 — Publish the translated locale
 
-```tsx
-const LABELS = {
-  en: { readMore: "Read more", by: "By" },
-  fr: { readMore: "Lire la suite", by: "Par" },
-};
+Publish the page or subtree in the target language:
 
-const t = LABELS[renderContext.getMainResourceLocale().getLanguage()] ?? LABELS.en;
-// Usage: <a>{t.readMore}</a>
 ```
-
----
-
-## Step 6 — Clean up orphaned translation nodes
-
-When you remove the `i18n` flag from a CND property (or delete a language from the site), orphaned `j:translation_XX` child nodes may remain. Inspect and remove them if needed:
-
-```bash
-# Find translation sub-nodes for a content node
-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/articles/my-article\") { children { nodes { name primaryNodeType { name } } } } } }"
-  }'
-
-# Delete an orphaned translation node
-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 { deleteNode(pathOrId: \"/sites/mySite/contents/articles/my-article/j:translation_fr\") }"
-  }'
+tool: publication.publish
+args: {
+  "path": "/sites/SITE_KEY/home/about",
+  "languages": ["fr"]
+}
 ```
 
+If the translation touches both a page and child content, publish the page path so the subtree is included.
+
 ---
 
-## Step 7 — Publish translations
-
-After setting i18n properties, republish to make them live:
-
-```bash
-# Publish a single node for a specific language
-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\") { publish(languages: [\"fr\"]) } } }"
-  }'
-
-# Publish all articles in both languages
-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 [namespace:article] WHERE ISDESCENDANTNODE(\u0027/sites/mySite/contents\u0027)\", queryLanguage: SQL2) { publish(languages: [\"en\", \"fr\"]) } } }"
-  }'
+## Common patterns
+
+### Translate all content under a page
+
+1. Discover the page structure:
+   ```
+   tool: page.structure
+   args: { "path": "/sites/SITE_KEY/home/about" }
+   ```
+2. Read each child node in the source locale:
+   ```
+   tool: content.get
+   args: { "path": "CHILD_PATH", "locale": "en" }
+   ```
+3. Write translated values to the target locale:
+   ```
+   tool: content.update
+   args: {
+     "path": "CHILD_PATH",
+     "locale": "fr",
+     "properties": { "jcr:title": "...", "text": "..." }
+   }
+   ```
+4. Publish the page in the new language.
+
+### Audit whether a page is publish-ready in the new locale
+
+```
+tool: publication.status
+args: {
+  "path": "/sites/SITE_KEY/home/about",
+  "language": "fr",
+  "subNodes": true,
+  "references": true
+}
 ```
 
 ---
@@ -276,22 +211,16 @@ curl -s -u root:root1234 \
 
 | Error | Cause | Fix |
 |-------|-------|-----|
-| `Permission denied` | Missing `Origin` header | Add `-H "Origin: http://localhost:8080"` |
-| i18n property returned empty after set | Missing `language:` in `properties()` query | Add `language: "fr"` to read call |
-| `ConstraintViolationException` on title set | Mandatory i18n field not set first | Use `setPropertiesBatch` with all mandatory fields in one call |
-| Language not appearing in site | `j:languages` mutation only had the new language | Pass the full list: `["en", "fr"]` |
-| Choicelist key changed per language | Property incorrectly declared `i18n` in CND | Remove `i18n` from the CND property; translate keys in the view |
+| `MANDATORY_PROPERTY_MISSING` | Not all required i18n properties were set | Set all mandatory translated properties in one `content.update` call |
+| Language not available | Locale not enabled on the site | Add the locale to the site first |
+| Properties appear empty | Wrong locale was used | Verify configured locales with `site.get` |
+| Translation not visible on the public site | It is still only in EDIT | Publish with `publication.publish` |
 
 ---
 
-## Workflow summary
+## Related skills
+
+- `/jahia-content-explore-structure` — find the right pages, nodes, and types first
+- `/jahia-content-publish` — publish translated content and inspect language-scoped status
+- `/jahia-content-create-content` — create new pages or content that will later need translation
 
-```
-1. Enable language   → mutateNode j:languages with full list
-2. Audit             → nodesByQuery with properties(language: "XX") to find gaps
-3. Translate         → setPropertiesBatch with language: "XX" for each i18n field
-4. View strings      → add locale-keyed label maps in .server.tsx
-5. Choicelists       → translate keys in the view, not the JCR
-6. Publish           → publish(languages: ["XX"]) for all affected nodes
-7. Verify            → query back with language: "XX" to confirm values
-```

package/dist/codex/.agents/skills/jahia-dev-accessibility/SKILL.md

@@ -110,10 +110,10 @@ color: #595959; /* 7:1 ratio on white */
 /* Bad */
 <img src={buildNodeUrl(props.image)} />
 
-/* Fix — use content from CND, fall back to empty string for decorative */
-<img src={buildNodeUrl(props.image)} alt={props.imageAlt ?? ""} />
+/* Fix — use the image node's jcr:title, fall back to empty string for decorative */
+<img src={buildNodeUrl(props.image)} alt={props.image?.getPropertyAsString("jcr:title") ?? ""} />
 ```
-Add `- imageAlt (string) i18n` to the CND and `imageAlt?: string` to `types.ts`.
+The image node already has `jcr:title` (from `mix:title`). **Do not add `imageAlt (string) i18n`** to the CND.
 
 **`button-name`** — `<button>` or `<a>` is empty (icon-only without label)
 ```tsx

package/dist/codex/.agents/skills/jahia-dev-build-component/SKILL.md

@@ -43,15 +43,18 @@ Has children: <yes: ChildType / no>
 
 ---
 
-## Step 2 — Invoke `jahia-dev-define-content-type`
+## Step 2 — REQUIRED: Invoke `/jahia-dev-define-content-type`
 
-Use the instructions from the `jahia-dev-define-content-type` skill to:
+**Do not write CND manually.** Jahia-specific patterns (`choicelist[linkTypeInitializer]`, `mix:title`, child nodes for CTAs) are not in LLM training data — writing CND from memory always produces broken output. This skill delegates to `@jahia-cnd-author` which loads the correct reference files.
 
-1. Identify the namespace (check `settings/definitions.cnd`)
-2. Create `src/components/<Category>/<Name>/definition.cnd`
-3. Create `src/components/<Category>/<Name>/types.ts`
-4. Run `yarn build && yarn jahia-deploy` to push the type to Jahia
-5. Verify the content type appears in the Jahia content editor
+Invoke `/jahia-dev-define-content-type` in a sub-agent job. Pass the component spec. Wait for it to confirm PASS before continuing.
+
+The skill will:
+1. Confirm the namespace (from `settings/definitions.cnd`)
+2. Invoke `@jahia-cnd-author` to create `src/components/<Category>/<Name>/definition.cnd`
+3. Invoke `@jahia-cnd-author` to create `src/components/<Category>/<Name>/types.ts`
+
+**Do not proceed to Step 3 until the CND review is PASS.**
 
 ---
 

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

@@ -14,35 +14,72 @@ A **page template** defines the full layout of a page. It is registered with `co
 
 ## Step 1 — Create the template file
 
-Page templates live in `src/templates/Page/`. Name the file `<templateName>.server.tsx`.
+Page templates live in `src/templates/<ModuleName>Template/`. Name the file `default.server.tsx`.
 
 ```tsx
-import { Area, AbsoluteArea, jahiaComponent } from "@jahia/javascript-modules-library";
-import { Layout } from "../Layout.jsx";
+import React from "react";
+import { Area, AbsoluteArea, getChildNodes, buildNodeUrl, jahiaComponent } from "@jahia/javascript-modules-library";
+import styles from "./template.module.css";
 
 jahiaComponent(
   {
     componentType: "template",   // "template" for full pages, not "view"
     nodeType: "jnt:page",        // always jnt:page for page templates
-    displayName: "Single Column",
-    name: "singleColumn",        // used in Jahia UI when selecting a template
+    displayName: "Default Template",
+    name: "default",
+  },
+  ({ "jcr:title": title }, { renderContext, mainNode }) => {
+    // Pages live under /sites/<key>/home — not directly under the site node
+    const siteHome = renderContext.getSite().getNode("home");
+    const navPages = getChildNodes(siteHome, -1, 0, n => n.isNodeType("jnt:page"));
+    const siteName = renderContext.getSite().getPropertyAsString("j:siteTitle") ?? renderContext.getSite().getName();
+    return (
+      <html lang="en">
+        <head>
+          <meta charSet="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1" />
+          {/* jcr:title is the short page name — template appends site name for SEO */}
+          <title>{title}{siteName ? ` | ${siteName}` : ""}</title>
+        </head>
+        <body>
+          <a href="#main-content" className={styles.skipLink}>Skip to main content</a>
+          <header className={styles.header}>
+            <nav aria-label="Main navigation">
+              <ul className={styles.navList}>
+                <li key={siteHome.getPath()}>
+                  <a href={buildNodeUrl(siteHome)} aria-current={siteHome.getPath() === mainNode.getPath() ? "page" : undefined}>
+                    {siteHome.getPropertyAsString("jcr:title") ?? siteHome.getName()}
+                  </a>
+                </li>
+                {navPages.map(page => (
+                  <li key={page.getPath()}>
+                    <a
+                      href={buildNodeUrl(page)}
+                      aria-current={page.getPath() === mainNode.getPath() ? "page" : undefined}
+                    >
+                      {page.getPropertyAsString("jcr:title") ?? page.getName()}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </nav>
+          </header>
+          <main id="main-content">
+            <h1 className={styles.pageTitle}>{title}</h1>
+            <Area name="pagecontent" />
+          </main>
+          <footer className={styles.footer}>
+            <AbsoluteArea name="footer" parent={renderContext.getSite()} />
+            <p className={styles.copyright}>{"© "}{renderContext.getSite().getName()}</p>
+          </footer>
+        </body>
+      </html>
+    );
   },
-  ({ "jcr:title": title }, { renderContext }) => (
-    <Layout title={title}>
-      <Area name="header" nodeType="namespace:header" />
-      <main style={{ maxWidth: "40rem", margin: "0 auto" }}>
-        <Area name="main" />
-      </main>
-      <AbsoluteArea
-        name="footer"
-        parent={renderContext.getSite()}
-        nodeType="namespace:footer"
-      />
-    </Layout>
-  ),
 );
 ```
 
+
 ---
 
 ## Step 2 — Choose: Area vs AbsoluteArea
@@ -266,13 +303,14 @@ After deploying, the new template will appear in the **template selection** step
 ---
 
 ## Validation checklist
-- [ ] File is in `src/templates/Page/`
 - [ ] `componentType: "template"` and `nodeType: "jnt:page"`
 - [ ] `name` is set (used in Jahia UI template picker)
+- [ ] Skip link present: `<a href="#main-content">Skip to main content</a>`
+- [ ] Nav built from `getChildNodes(site.getNode('home'), ...)` — pages are children of `home`, not of the site node
+- [ ] `<h1>{title}</h1>` in the template — no `<h1>` in any component
+- [ ] `<footer>` landmark always has visible content (never empty)
 - [ ] Areas use a custom area node type (not bare `<Area name="..."/>`)
 - [ ] Custom area type has `jmix:list`, `jmix:hiddenType`, and `orderable`
-- [ ] `AbsoluteArea` uses `renderContext.getSite()` as parent
-- [ ] Structural container nodes use `jmix:hiddenType` (hidden from picker)
 - [ ] Decision made: page template vs sectioning component (see Step 4)
 - [ ] `yarn build && yarn jahia-deploy` run and template appears in Jahia UI