@jahia/agentic 0.1.1 → 0.3.0

package/dist/claude/.claude/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/claude/.claude/skills/jahia-dev-build-component/SKILL.md

@@ -16,17 +16,17 @@ Run these steps in order. Do not skip to the view before the content type is def
 
 ---
 
-## Step 0 — Optional: capture reference screenshot
+## Step 0 — Optional: capture reference screenshot (interactive sessions only)
 
 If the user provides a reference URL (or mentions a site to model after), invoke `/jahia-dev-screenshot` **before writing any code** to capture the visual spec.
 
-The screenshot gives the view implementation visual context: layout, colors, typography, and component anatomy. Reference it throughout Steps 2–3.
+> Skip this step in automated / autopilot contexts — screenshot comparison requires human review and adds significant time.
 
 ---
 
-## Step 1 — Write and confirm the content spec
+## Step 1 — Write the content spec
 
-Before writing any code, fill out this template and confirm with the user:
+Before writing any code, draft this spec internally. In an interactive session, confirm with the user; in autopilot mode, proceed with your best judgement and document what you chose:
 
 ```
 Name: <ComponentName>
@@ -41,8 +41,6 @@ Used where: <Area on page / nested in <Parent> / listing item>
 Has children: <yes: ChildType / no>
 ```
 
-Only proceed once the spec is confirmed.
-
 ---
 
 ## Step 2 — Invoke `jahia-dev-define-content-type`
@@ -69,25 +67,12 @@ Use the instructions from the `jahia-dev-create-view` skill to:
 
 ---
 
-## Step 4 — Validate and compare
+## Step 4 — Validate
 
 1. In Jahia Page Builder, click **New content** and select the new type
 2. Fill in the content form and click **Save**
 3. Verify the component renders correctly on the page
 4. Check for the error `No rendering set for node: <type>` — if seen, re-run `yarn build && yarn jahia-deploy`
-5. **If a reference screenshot was taken in Step 0**, invoke `/jahia-dev-screenshot` again to capture the Jahia render and compare against the reference.
-
----
-
-## Step 5 — Accessibility check
-
-After the component is live, invoke `/jahia-dev-accessibility` to audit it:
-
-1. Run the axe-core audit against the page(s) containing the new component
-2. Fix any `critical` or `serious` violations before considering the component done
-3. Report remaining violations to the user
-
-A component is not complete until it has no critical or serious accessibility violations.
 
 ---
 
@@ -128,13 +113,13 @@ If the component has child nodes (e.g. a hero with CTA buttons), repeat Steps 2
 ---
 
 ## Validation checklist
-- [ ] Spec confirmed before writing any code
+- [ ] Spec written before any code
 - [ ] Component count within scale of thumbs (1–4 templates, 5–10 types, 2–5 mixins, 1–4 views/type)
 - [ ] `definition.cnd` created with correct namespace and mixins
 - [ ] `types.ts` reflects all CND properties
 - [ ] `default.server.tsx` renders without errors
 - [ ] Views handle null/missing fields gracefully (mandatory does not guarantee a value at runtime)
 - [ ] `component.module.css` applied and visible
+- [ ] Semantic HTML used: correct heading level, `alt` text on images, sufficient colour contrast
 - [ ] Component appears in Page Builder content picker
 - [ ] Content can be created and renders on the page
-- [ ] No critical or serious accessibility violations (`/jahia-dev-accessibility`)

package/dist/claude/.claude/skills/jahia-dev-create-view/SKILL.md

@@ -78,6 +78,64 @@ When you have a source HTML fragment to translate (e.g. from `/jahia-dev-import-
 
 ---
 
+## Step 1b — Accessibility and SEO rules (apply to every view)
+
+Build these requirements in from the start — retrofitting them later is more expensive.
+
+### Semantic HTML structure
+
+| Element | Rule |
+|---|---|
+| `<section>`, `<article>` | Wrap every self-contained block of content |
+| `<header>` / `<footer>` | Use for the page header and footer in page templates |
+| `<nav>` | Wrap navigation menus; add `aria-label` when there are multiple navs |
+| `<main>` | Exactly one per page, wrapping all page body content (already enforced by the Layout component for page templates) |
+| Headings | Each page must have exactly one `<h1>`; section headings use `<h2>`; sub-section headings use `<h3>`. Never skip levels. |
+
+### Images
+
+Every `<img>` must have an `alt` attribute. Decorative images use `alt=""`. Informational images use a descriptive string from a CND property:
+
+```tsx
+// ❌ Missing alt
+<img src={buildNodeUrl(props.image)} />
+
+// ✅ Descriptive alt from content
+<img src={buildNodeUrl(props.image)} alt={props.imageAlt ?? ""} />
+```
+
+Add `- imageAlt (string) i18n` to the CND and `imageAlt?: string` to `types.ts` for any type with an image field.
+
+### Colour contrast
+
+Use colours with a contrast ratio ≥ 4.5:1 for body text and ≥ 3:1 for large text (18px+ or bold 14px+) against the background. Avoid light grey on white. When in doubt, use near-black (`#333333` or `#1a1a1a`) for body text.
+
+### Link and button names
+
+Every `<a>` and `<button>` must have an accessible name — either visible text or `aria-label`. Icon-only buttons must have `aria-label`:
+
+```tsx
+// ❌ No accessible name
+<button><svg>…</svg></button>
+
+// ✅ Accessible name via aria-label
+<button aria-label="Close menu"><svg aria-hidden="true">…</svg></button>
+```
+
+### Focus styles
+
+Never suppress focus indicators globally. Use `:focus-visible` to style keyboard focus:
+
+```css
+/* ❌ Never do this */
+* { outline: none; }
+
+/* ✅ Style keyboard focus without affecting mouse users */
+:focus-visible { outline: 2px solid #0969da; outline-offset: 2px; }
+```
+
+---
+
 ## Step 2 — Import Props from types.ts
 
 Always import `Props` from `./types.js` (not `./types.ts` — use `.js` extension at import time):