@jahia/agentic 0.0.0

package/dist/codex/.agents/skills/jahia-dev-java/references/content-types.md

@@ -0,0 +1,273 @@
+# Jahia Content Types (CND) Reference
+
+## Table of Contents
+1. [CND file basics](#1-cnd-file-basics)
+2. [Property types and selectors](#2-property-types-and-selectors)
+3. [Property keywords](#3-property-keywords)
+4. [Child node declarations](#4-child-node-declarations)
+5. [Mixins](#5-mixins)
+6. [Key built-in mixins reference](#6-key-built-in-mixins-reference)
+7. [Choicelist initializers](#7-choicelist-initializers)
+8. [Enhancing content types for editors](#8-enhancing-content-types-for-editors)
+9. [Modifying existing definitions](#9-modifying-existing-definitions)
+10. [Module definition checks](#10-module-definition-checks)
+
+---
+
+## 1. CND file basics
+
+CND = Compact Namespace and Node Type Definition (Apache Jackrabbit standard).
+
+File location: `src/main/resources/META-INF/definitions.cnd`
+
+### Namespace declaration (required first)
+```cnd
+<ns = 'http://www.example.org/ns/1.0'>
+```
+
+Jahia built-in namespaces:
+- `<jnt = 'http://www.jahia.org/jahia/nt/1.0'>` — node types
+- `<jmix = 'http://www.jahia.org/jahia/mix/1.0'>` — mixins
+- `<j = 'http://www.jahia.org/jahia/1.0'>` — core properties
+- `<mix = 'http://www.jcp.org/jcr/mix/1.0'>` — JCR standard mixins
+
+### Minimal content type definition
+```cnd
+<myns = 'http://www.example.org/myns/1.0'>
+
+[myns:myContent] > jnt:content, jmix:editorialContent
+- title (string) i18n mandatory
+- body (string, richtext) i18n
+- publishDate (date)
+```
+
+All user-editable content types MUST inherit from `jnt:content`.
+Add `jmix:editorialContent` to make the type visible in jContent.
+
+---
+
+## 2. Property types and selectors
+
+### Base property types
+
+| CND type | Content Editor renders as |
+|----------|--------------------------|
+| `string` | Text input |
+| `long` | Number field (integer) |
+| `double` | Number field (decimal) |
+| `boolean` | Checkbox |
+| `date` | Date picker |
+| `weakreference` | Node picker (UUID reference, not enforced) |
+
+### String selectors
+
+| Selector | Renders as |
+|----------|-----------|
+| `string` | Plain text input |
+| `string, textarea` | Multi-line textarea |
+| `string, richtext` | CKEditor WYSIWYG |
+| `string, choicelist` | Dropdown list |
+| `string, color` | Color picker |
+
+### Date selectors
+
+| Selector | Renders as |
+|----------|-----------|
+| `date, datetimepicker` | Date + time picker |
+| `date, datepicker` | Date-only picker |
+
+---
+
+## 3. Property keywords
+
+| Keyword | Effect |
+|---------|--------|
+| `i18n` / `internationalized` | Property has separate value per language |
+| `mandatory` | Field required before saving |
+| `multiple` | Allows multiple values |
+| `hidden` | Not shown in UI; only set programmatically |
+| `protected` | Read-only in UI; only set programmatically |
+| `autocreated` | Automatically created with default or blank value |
+| `primary` | Used as node label in JCR browser |
+| `indexed=no` | Not indexed for search |
+| `nofulltext` | Indexed but excluded from full-text search |
+| `boost=N` | Search weight multiplier (1.0–5.0) |
+| `analyzer=keyword` | Indexed word-by-word |
+| `facetable` | Enables faceted search on this property |
+
+---
+
+## 4. Child node declarations
+
+```cnd
+[myns:article] > jnt:content, jmix:editorialContent
++ * (jmix:droppableContent) = jmix:droppableContent version  # Any droppable content
++ media (jnt:file)                                            # Single named child
++ * (jnt:paragraph)                                          # Multiple children
++ section1 (jnt:contentList)                                 # Named child list
+```
+
+---
+
+## 5. Mixins
+
+A mixin adds properties/child nodes to a type without inheritance conflicts:
+
+```cnd
+[myns:myMixin] mixin
+- extraProp (string) i18n
+```
+
+Apply to a content type:
+```cnd
+[myns:article] > jnt:content, jmix:editorialContent, myns:myMixin
+```
+
+Create a custom component category:
+```cnd
+<mymix = 'http://example.org/mymix/1.0'>
+
+[mymix:myComponents] > jmix:droppableContent mixin
+```
+
+---
+
+## 6. Key built-in mixins reference
+
+### Content visibility / organization
+
+| Mixin | Purpose |
+|-------|---------|
+| `jmix:editorialContent` | Makes type visible in jContent; enables versioning |
+| `jmix:droppableContent` | Base for component category folders |
+| `jmix:list` | Declares a list component with built-in mechanisms |
+| `mix:title` | Syncs system name with `jcr:title` |
+| `jmix:mainResource` | Enables full-page display |
+| `jmix:hiddenNode` | Node not visible in Jahia managers |
+
+### Content behavior
+
+| Mixin | Purpose |
+|-------|---------|
+| `jmix:cache` | Exposes cache expiration controls in the editor UI |
+| `jmix:bindedComponent` | Defines a component that binds/links to another component |
+
+### Component categories (out-of-the-box)
+
+| Mixin | Component folder |
+|-------|-----------------|
+| `jmix:basicContent` | Content > Basic |
+| `jmix:multimediaContent` | Content > Multimedia |
+| `jmix:structuredContent` | Content > Structured |
+| `jmix:listContent` | Lists |
+| `jmix:siteComponent` | Site Components |
+| `jmix:editorialContent` | All editorial content |
+
+---
+
+## 7. Choicelist initializers
+
+### Built-in initializers
+
+```cnd
+# Static values from resource bundle
+- contract (string, choicelist[resourceBundle]) < contract1, contract2, contract3
+
+# JCR node tree
+- theme (weakreference, choicelist[nodes='$currentSite/files/themes;jnt:folder'])
+- category (weakreference, choicelist[nodes='/sites/systemsite/categories;jnt:category'])
+
+# Chained initializers
+- view (string, choicelist[templates,resourceBundle,image])
+```
+
+**Resource bundle keys format:**
+```properties
+jnt_article.contract.contract1 = Fixed-term contract
+jnt_article.contract.contract2 = Indefinite duration
+```
+Format: `{nodeTypeName_with_colon_as_underscore}.{propertyName}.{value} = Label`
+
+### Custom choicelist initializer
+
+```java
+@Component(service = {ModuleChoiceListInitializer.class})
+public class MyChoiceListInitializer implements ModuleChoiceListInitializer {
+
+    @Override
+    public String getKey() {
+        return "myCustomList";  // Used in CND as choicelist[myCustomList]
+    }
+
+    @Override
+    public List<ChoiceListValue> getChoiceListValues(
+            ExtendedPropertyDefinition epd, String param,
+            List<ChoiceListValue> values, Locale locale,
+            Map<String, Object> context) {
+        List<ChoiceListValue> result = new ArrayList<>();
+        result.add(new ChoiceListValue("Display Label", "storedValue"));
+        return result;
+    }
+}
+```
+
+---
+
+## 8. Enhancing content types for editors
+
+### Labels and i18n
+
+```properties
+# In src/main/resources/resources/ModuleName.properties
+myns_myContent.title = Title
+myns_myContent.body = Body text
+myns_myContent.publishDate = Publication date
+```
+
+### Icons
+Place at `src/main/resources/icons/myns_myContent.png` (replace `:` with `_`).
+
+### Constraints
+```cnd
+- size (string) < 'small', 'medium', 'large'
+- rating (long) < '[1,5]'
+```
+
+---
+
+## 9. Modifying existing definitions
+
+### Safe modifications (non-destructive)
+- Adding new optional properties to an existing type
+- Adding a new mixin to an existing type
+- Adding new child node definitions
+- Changing property constraints or default values
+
+### Dangerous modifications (require migration)
+- Renaming a property
+- Changing a property type (e.g., string to date)
+- Removing a property that has existing content
+- Changing the supertype hierarchy
+
+### Overriding built-in definitions
+
+```cnd
+[myns:pageExtension] mixin
+  extends = jnt:page
+- myCustomProp (string) i18n
+```
+
+### Migration scripts
+
+Groovy scripts in `src/main/resources/META-INF/patches/` run once on deployment.
+Naming convention: `7.0.0.0-SNAPSHOT-1_myMigration.groovy`
+
+---
+
+## 10. Module definition checks
+
+When deploying a module, Jahia checks CND changes. To bypass during development (NOT for production):
+```properties
+# In jahia.properties
+jahia.jackrabbit.overrideNodeTypes = true
+```

package/dist/codex/.agents/skills/jahia-dev-java/references/modules.md

@@ -0,0 +1,218 @@
+# Jahia Java Module Development Reference
+
+## Table of Contents
+1. [Module types and structure](#1-module-types-and-structure)
+2. [Maven pom.xml patterns](#2-maven-pomxml-patterns)
+3. [Deployment methods](#3-deployment-methods)
+4. [Deploy-free coding](#4-deploy-free-coding)
+5. [Static asset management](#5-static-asset-management)
+6. [Java 11 / 17 configuration](#6-java-11--17-configuration)
+7. [OSGi tooling in Karaf](#7-osgi-tooling-in-karaf)
+8. [Troubleshooting common deployment errors](#8-troubleshooting-common-deployment-errors)
+
+---
+
+## 1. Module types and structure
+
+| Type | Purpose |
+|------|---------|
+| `module` | Standard content module (default) |
+| `system` | System-level services, loaded early |
+| `templatesSet` | Provides site page templates |
+
+### Directory structure
+
+```
+src/main/
+  java/                    # Java source code
+  resources/
+    META-INF/
+      definitions.cnd      # Content type definitions
+      rules.drl            # Drools rules (all workspaces)
+      default-rules.drl    # Rules for edit/preview workspace only
+      live-rules.drl       # Rules for live workspace only
+      rules.dsl            # Custom DSL extensions
+      configurations/      # OSGi .cfg files deployed to karaf/etc/
+      patches/             # Groovy migration scripts
+    OSGI-INF/blueprint/    # Blueprint XML (deprecated in 8.2)
+  webapp/
+    css/
+    javascript/
+    icons/                 # Node type icons (jnt_news.png format)
+    resources/             # Resource bundles (ModuleName.properties)
+    WEB-INF/macros/        # Groovy/Velocity macros
+```
+
+Icons naming: replace `:` with `_` — `jnt:news` → `jnt_news.png`.
+
+---
+
+## 2. Maven pom.xml patterns
+
+### Minimal pom.xml
+
+```xml
+<parent>
+  <artifactId>jahia-modules</artifactId>
+  <groupId>org.jahia.modules</groupId>
+  <version>8.2.0.0</version>
+</parent>
+
+<groupId>org.example</groupId>
+<artifactId>my-module</artifactId>
+<version>1.0.0-SNAPSHOT</version>
+<packaging>bundle</packaging>
+<name>My Module</name>
+
+<properties>
+  <jahia-depends>default,assets</jahia-depends>
+  <jahia.modules.importPackage>org.jahia.defaults.config.spring</jahia.modules.importPackage>
+  <export-package>org.example.mymodule.api</export-package>
+</properties>
+
+<build>
+  <plugins>
+    <plugin>
+      <groupId>org.apache.felix</groupId>
+      <artifactId>maven-bundle-plugin</artifactId>
+      <extensions>true</extensions>
+      <configuration>
+        <instructions>
+          <Jahia-Module-Type>module</Jahia-Module-Type>
+          <Jahia-Static-Resources>/css,/icons,/javascript</Jahia-Static-Resources>
+          <Jahia-Source-Folders>${project.basedir}</Jahia-Source-Folders>
+          <Embed-Dependency>*;scope=compile|runtime;type=!pom;inline=false</Embed-Dependency>
+          <_dsannotations>*</_dsannotations>
+        </instructions>
+      </configuration>
+    </plugin>
+    <plugin>
+      <groupId>org.jahia.server</groupId>
+      <artifactId>jahia-maven-plugin</artifactId>
+    </plugin>
+  </plugins>
+</build>
+```
+
+### Declaring module dependencies with version constraints
+
+```xml
+<jahia-depends>dep-module1=4.1,dep-module2,dep-module3=[0, 3)</jahia-depends>
+<jahia-depends>dep-module1=optional</jahia-depends>
+```
+
+---
+
+## 3. Deployment methods
+
+### Method 1: Copy to modules directory (development)
+Drop the JAR into `digital-factory-data/modules/`. Jahia auto-deploys.
+
+### Method 2: Maven deploy goal (recommended)
+```xml
+<profile>
+  <id>jahia-local</id>
+  <properties>
+    <jahia.deploy.targetServerType>tomcat</jahia.deploy.targetServerType>
+    <jahia.deploy.targetServerDirectory>/path/to/jahia/apache-tomcat</jahia.deploy.targetServerDirectory>
+  </properties>
+</profile>
+```
+```bash
+mvn clean install jahia:deploy -P jahia-local
+# For Docker:
+mvn jahia:deploy -Djahia.deploy.targetContainerName=CONTAINER_NAME
+```
+
+### Creating a new module from archetype
+```bash
+mvn archetype:generate -Dfilter=org.jahia.archetypes:
+# Select: jahia-module-archetype
+```
+
+---
+
+## 4. Deploy-free coding
+
+Deploy-free coding allows JSP, CSS, JS, and CND changes to be reflected without redeployment.
+
+**Requirement:** `Jahia-Source-Folders` must point to the project base directory in MANIFEST.
+
+**Limitations:** Java class changes still require redeployment. Remove `Jahia-Source-Folders` for release builds.
+
+---
+
+## 5. Static asset management
+
+Assets are served from within the OSGi bundle JAR:
+```xml
+<Jahia-Static-Resources>/css,/icons,/images,/javascript</Jahia-Static-Resources>
+```
+
+OSGi configuration files shipped with a module go in:
+`src/main/resources/META-INF/configurations/` → auto-deployed to `digital-factory-data/karaf/etc/`
+
+To prevent overwriting on upgrade, start the file with:
+```
+# default configuration
+```
+
+---
+
+## 6. Java 11 / 17 configuration
+
+For Java 17, add to JVM startup arguments:
+```
+--add-opens java.base/java.lang=ALL-UNNAMED
+--add-opens java.base/java.io=ALL-UNNAMED
+--add-opens java.base/java.util=ALL-UNNAMED
+```
+
+---
+
+## 7. OSGi tooling in Karaf
+
+```bash
+ssh -p 8101 jahia@localhost
+bundle:list                    # List all OSGi bundles
+jahia:modules                  # List Jahia modules with state
+bundle:requirements --namespace=osgi.wiring.package <bundleId>  # Package requirements
+jcr:query "SELECT * FROM [jnt:page]"  # Execute JCR SQL2 query
+```
+
+### Jahia Maven Plugin goals for OSGi diagnostics
+
+```bash
+mvn jahia:dependencies          # Generate/inspect Import-Package list
+mvn jahia:find-package-uses -DpackageNames=com.example.pkg
+mvn jahia:osgi-inspect          # Dump MANIFEST headers of built JAR
+```
+
+---
+
+## 8. Troubleshooting common deployment errors
+
+### Bundle stuck in Installed/Resolved (not Started)
+
+Causes:
+1. Missing package import
+2. Unsatisfied Jahia-Depends
+3. CND dependency not met
+
+Diagnosis:
+```bash
+bundle:requirements --namespace=osgi.wiring.package <bundleId>
+bundle:requirements --namespace=com.jahia.services.content <bundleId>
+```
+
+### JSP compilation error: "class cannot be resolved"
+
+Solution: Add the package to `jahia.modules.importPackage` or run `mvn jahia:dependencies`.
+
+### "Unresolved constraint in bundle" on deploy
+
+```
+Unable to resolve 118.0: missing requirement [118.0] osgi.wiring.package
+```
+
+Solution: Use `mvn jahia:find-package-uses` to identify source. Mark as `resolution:=optional` if not needed at runtime.

package/dist/codex/.agents/skills/jahia-dev-java/references/osgi.md

@@ -0,0 +1,208 @@
+# Jahia OSGi Reference
+
+## Table of Contents
+1. [OSGi fundamentals](#1-osgi-fundamentals)
+2. [Jahia OSGi architecture](#2-jahia-osgi-architecture)
+3. [Declarative Services (preferred)](#3-declarative-services-preferred)
+4. [Blueprint XML (deprecated in 8.2)](#4-blueprint-xml-deprecated-in-82)
+5. [Package imports and exports](#5-package-imports-and-exports)
+6. [Embedding vs importing libraries](#6-embedding-vs-importing-libraries)
+7. [Service export between modules](#7-service-export-between-modules)
+8. [Available Jahia OSGi services](#8-available-jahia-osgi-services)
+9. [Bundle lifecycle states](#9-bundle-lifecycle-states)
+
+---
+
+## 1. OSGi fundamentals
+
+Each bundle:
+- Has its own class loader (isolation)
+- Declares what packages it imports (`Import-Package`)
+- Declares what packages it exports (`Export-Package`)
+- Registers services in a shared service registry
+- Can be installed, started, updated, stopped, and uninstalled at runtime
+
+---
+
+## 2. Jahia OSGi architecture
+
+```
+Jahia Application (DX)
+  └── Apache Karaf         (module management, clustering support, SSH shell)
+        └── Apache Felix   (OSGi framework implementation)
+              └── Tomcat   (servlet container)
+```
+
+---
+
+## 3. Declarative Services (preferred)
+
+Declarative Services (DS) is the **only recommended** way to register OSGi services in Jahia 8.2.
+
+### Enable DS annotation scanning in pom.xml
+```xml
+<_dsannotations>*</_dsannotations>
+```
+
+### Component declaration
+
+```java
+@Component(service = {MyServiceInterface.class})
+public class MyServiceImpl implements MyServiceInterface {
+
+    @Activate
+    public void activate(BundleContext context) { }
+
+    @Deactivate
+    public void deactivate() { }
+}
+```
+
+### Referencing a single service
+
+```java
+@Reference
+public void setDependency(MyDependency dep) { this.dep = dep; }
+
+public void unsetDependency(MyDependency dep) { this.dep = null; }
+```
+
+### Referencing multiple services
+
+```java
+@Reference(cardinality = ReferenceCardinality.MULTIPLE,
+           policy = ReferencePolicy.DYNAMIC,
+           policyOption = ReferencePolicyOption.GREEDY)
+public synchronized void addService(MyService service) { this.services.add(service); }
+
+public synchronized void removeService(MyService service) { this.services.remove(service); }
+```
+
+### Component with configuration
+
+```java
+@Component(service = MyConfiguredService.class,
+           configurationPid = "org.example.myservice",
+           configurationPolicy = ConfigurationPolicy.OPTIONAL)
+public class MyConfiguredService {
+
+    @Activate
+    public void activate(Map<String, Object> props) {
+        String value = (String) props.getOrDefault("myProperty", "default");
+    }
+
+    @Modified
+    public void modified(Map<String, Object> props) { }
+}
+```
+
+Configuration file: `src/main/resources/META-INF/configurations/org.example.myservice.cfg`
+
+---
+
+## 4. Blueprint XML (deprecated in 8.2)
+
+Do not use for new development. For legacy modules only. Files go in `OSGI-INF/blueprint/`.
+
+---
+
+## 5. Package imports and exports
+
+### Manually adding imports
+
+```xml
+<jahia.modules.importPackage>org.jahia.defaults.config.spring,org.example.api</jahia.modules.importPackage>
+```
+
+Or in bundle plugin instructions:
+```xml
+<Import-Package>
+  org.example.api,
+  com.optional.pkg;resolution:=optional,
+  *
+</Import-Package>
+```
+
+### Exporting packages
+
+```xml
+<export-package>org.example.mymodule.api</export-package>
+```
+
+---
+
+## 6. Embedding vs importing libraries
+
+### Option 1: Embed as JAR inside module JAR (easiest)
+
+```xml
+<Embed-Dependency>*;scope=compile|runtime;type=!pom;inline=false</Embed-Dependency>
+```
+
+To exclude a dependency from embedding, use `<scope>provided</scope>`.
+
+**Caution:** `Embed-Transitive>true</Embed-Transitive>` embeds ALL transitive dependencies — use carefully.
+
+---
+
+## 7. Service export between modules
+
+### Provider module
+
+```java
+@Component(service = {DataService.class})
+public class DataServiceImpl implements DataService {
+    @Override
+    public List<String> getData() { return Arrays.asList("item1", "item2"); }
+}
+```
+
+pom.xml: `<export-package>org.example.moduleA.api</export-package>`
+
+### Consumer module
+
+```java
+@Component(service = MyConsumer.class)
+public class MyConsumer {
+    @Reference
+    public void setDataService(DataService dataService) { this.dataService = dataService; }
+}
+```
+
+pom.xml:
+```xml
+<jahia-depends>moduleA-artifactId</jahia-depends>
+<jahia.modules.importPackage>org.example.moduleA.api</jahia.modules.importPackage>
+```
+
+---
+
+## 8. Available Jahia OSGi services
+
+Key Jahia services accessible via `@Reference`:
+
+| Interface | Description |
+|-----------|-------------|
+| `JahiaTemplateManagerService` | Template package registry, module lifecycle |
+| `JahiaUserManagerService` | User CRUD and lookup |
+| `JahiaGroupManagerService` | Group management |
+| `JCRSessionFactory` | JCR session factory |
+| `JahiaSitesService` | Site management |
+| `RenderService` | Content rendering |
+| `CacheService` | Cache management |
+| `WorkflowService` | Workflow management |
+
+---
+
+## 9. Bundle lifecycle states
+
+| State | Description |
+|-------|-------------|
+| `INSTALLED` | Bundle JAR is installed but requirements not resolved yet |
+| `RESOLVED` | All package dependencies resolved but not started |
+| `STARTING` | Bundle activator is running |
+| `ACTIVE` | Bundle is fully started and operational |
+| `STOPPING` | Bundle is being stopped |
+| `UNINSTALLED` | Bundle has been removed |
+
+A bundle stuck in `RESOLVED` but not `ACTIVE` usually means an `@Activate` method threw an exception or a required `@Reference` could not be resolved.