@jahia/agentic 0.1.0 → 0.2.0

package/dist/gemini/.agents/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/gemini/.agents/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):

package/dist/gemini/.agents/skills/jahia-dev-java/SKILL.md

@@ -15,14 +15,19 @@ allowed-tools: Read
 
 ## When to load which reference
 
-| Task | Reference file |
-|------|---------------|
+| Task | Reference |
+|------|-----------|
 | Creating a new module, Maven pom.xml, deployment, Java 11/17, static assets, deploy-free coding, troubleshooting bundle errors | `references/modules.md` |
 | Writing CND definitions, content type hierarchy, property types, choicelist initializers, modifying existing definitions | `references/content-types.md` |
 | JSP views, view selection, `@cache` tag, caching configuration, navigation menus, rendering filters, AMP | `references/rendering.md` |
 | Drools rules (DRL), JCR event listeners, JCR SQL2 queries, external data provider, permissions and roles | `references/backend.md` |
 | OSGi bundle lifecycle, Declarative Services, Blueprint XML, package Import/Export, service registry, Karaf tooling | `references/osgi.md` |
 | Content Editor JSON overrides, jContent UI extension points, component registry, custom selectors, settings pages, CKEditor | `references/ui-extensions.md` |
+| JCR session lifecycle, workspace, node names, SNS, mixins, locks, versioning — **correct patterns and pitfalls** | `/jahia-java-jcr` skill |
+| OSGi `@Component` state, `@Reference`, lifecycle side effects, Export-Package — **correct patterns and pitfalls** | `/jahia-java-osgi` skill |
+| Securing HTTP-reachable surfaces (servlets, GraphQL, filters) — Security Filter, CSRF Guard, ACLs | `/jahia-java-security` skill |
+| Relational persistence alongside JCR — N+1, timestamp consistency, entity model, transactional asymmetry | `/jahia-java-persistence` skill |
+| Thread safety in a multi-threaded webapp — `volatile`, locking, atomic variables, thread-safe collections, JCR session threading | `/jahia-java-concurrency` skill |
 
 ## Key Concepts Glossary
 

package/dist/gemini/.agents/skills/jahia-java-concurrency/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: jahia-java-concurrency
+description: Thread safety patterns for Jahia Java backend development in a multi-threaded web application. Covers volatile, locking, atomic variables, thread-safe collections, immutability, and common pitfalls that cause data races, stale reads, and silent corruption. Load when implementing or reviewing any class that holds mutable state accessible from multiple threads — OSGi services, caches, static fields, background workers, event listeners.
+allowed-tools: Read
+---
+
+# Concurrency and Thread Safety for Jahia Java Backend
+
+In a Jahia webapp, every OSGi service is a singleton — its instance fields are shared across every concurrent request, publication job, event listener, and background thread. A field that looks fine in a single-threaded test can silently corrupt data or read stale values under real load.
+
+This skill covers the correct patterns and the pitfalls. Both developers and reviewers use it.
+
+> OSGi-specific concurrency (`@Modified` config reload, `@Reference` dynamic rebinding) is covered in `/jahia-java-osgi`. This skill covers the general Java concurrency model applicable to all backend code.
+
+---
+
+## The three questions to ask about any mutable field
+
+Before writing or reviewing any instance or static field in a service:
+
+1. **Can it be written by more than one thread?** If yes → needs synchronization or an atomic type.
+2. **Can it be read while another thread is writing it?** If yes → at minimum needs `volatile`.
+3. **Are read + write part of a compound action** (check-then-act, read-modify-write)? If yes → `volatile` alone is not enough, needs a lock or an atomic with CAS.
+
+---
+
+## Immutability — the first line of defence
+
+### Correct approach
+
+Prefer immutable objects. An immutable object needs no synchronization — it is inherently thread-safe.
+
+- Make fields `final` wherever possible.
+- Use `record` types for config/value objects (all fields are final by definition).
+- Use `List.of()`, `Map.of()`, `Set.of()` for collections that do not change after construction.
+- Return copies or unmodifiable views of mutable internal collections rather than the live reference.
+
+### Pitfall
+
+```java
+// dangerous — caller can mutate the internal list
+public List<String> getAllowedRoles() {
+    return allowedRoles; // returns live mutable reference
+}
+```
+
+Return `Collections.unmodifiableList(allowedRoles)` or `List.copyOf(allowedRoles)` instead.
+
+---
+
+## `volatile` — correct use and limits
+
+### Correct use
+
+`volatile` guarantees **visibility**: a write to a `volatile` field is immediately visible to all subsequent reads in other threads. Use it when:
+
+- One thread writes, many threads read (no compound action needed).
+- The written value is a single reference or primitive (not two fields that must be updated atomically together).
+
+```java
+// correct — single writer (SCR @Modified), many readers
+private volatile Config config;
+
+@Activate @Modified
+void activate(Cfg cfg) {
+    this.config = new Config(cfg); // atomic reference swap
+}
+```
+
+### Limits — volatile is NOT enough for compound actions
+
+```java
+// WRONG — read-modify-write is not atomic even with volatile
+private volatile int counter = 0;
+public void increment() {
+    counter++; // read, increment, write — three steps, not one
+}
+```
+
+Two threads can both read `counter = 5`, both compute `6`, and both write `6` — losing one increment. Use `AtomicInteger.incrementAndGet()` instead.
+
+Similarly, volatile does not protect **two fields that must be consistent with each other**:
+
+```java
+// WRONG — reader can see updated 'host' with old 'port'
+private volatile String host;
+private volatile int port;
+```
+
+Bundle related fields into a single immutable record and swap the reference atomically (as shown in `/jahia-java-osgi`).
+
+---
+
+## Atomic variables
+
+Use `java.util.concurrent.atomic` for lock-free, thread-safe single-value updates:
+
+| Need | Type |
+|---|---|
+| Thread-safe counter | `AtomicInteger` / `AtomicLong` |
+| Thread-safe reference swap | `AtomicReference<T>` |
+| Conditional update (compare-and-swap) | `AtomicReference.compareAndSet()` |
+| Accumulator under high contention | `LongAdder` (more scalable than `AtomicLong` for pure counting) |
+
+### Check-then-act with `compareAndSet`
+
+```java
+// correct — atomic conditional update
+AtomicReference<State> stateRef = new AtomicReference<>(State.IDLE);
+
+public boolean tryStart() {
+    return stateRef.compareAndSet(State.IDLE, State.RUNNING);
+}
+```
+
+Two threads calling `tryStart()` concurrently: only one gets `true`. No lock needed.
+
+---
+
+## Synchronized blocks and `ReentrantLock`
+
+### When to use
+
+Use explicit locking when:
+- The critical section spans multiple statements that must execute atomically.
+- You need read/write distinction (`ReadWriteLock`).
+- You need a timed or interruptible lock attempt (`ReentrantLock.tryLock(timeout)`).
+
+### Correct approach
+
+```java
+// small, focused critical section
+private final Object lock = new Object();
+private List<String> items = new ArrayList<>();
+
+public void addItem(String item) {
+    synchronized (lock) {
+        items.add(item);
+    }
+}
+
+public List<String> snapshot() {
+    synchronized (lock) {
+        return List.copyOf(items); // return a copy, not the live list
+    }
+}
+```
+
+### Pitfalls
+
+- **Locking on `this`.** Callers can also `synchronized(service)` from outside, causing unexpected contention or deadlock. Prefer a private `final Object lock`.
+- **Holding a lock during I/O or JCR calls.** A lock held while doing a JCR query or an HTTP call blocks all other threads waiting for it. Move I/O outside the critical section; only protect the state mutation.
+- **Inconsistent lock object.** Two methods protecting the same state must use the same lock.
+- **Deadlock.** Two threads each holding lock A and waiting for lock B. Always acquire multiple locks in the same fixed order. Prefer `tryLock(timeout)` and fail gracefully rather than block indefinitely.
+
+### `ReadWriteLock` for read-heavy state
+
+```java
+private final ReadWriteLock rwLock = new ReentrantReadWriteLock();
+private Map<String, String> cache = new HashMap<>();
+
+public String get(String key) {
+    rwLock.readLock().lock();
+    try { return cache.get(key); }
+    finally { rwLock.readLock().unlock(); }
+}
+
+public void put(String key, String value) {
+    rwLock.writeLock().lock();
+    try { cache.put(key, value); }
+    finally { rwLock.writeLock().unlock(); }
+}
+```
+
+Multiple readers proceed concurrently; a writer gets exclusive access. Worth the complexity only when reads heavily outnumber writes.
+
+---
+
+## Thread-safe collections
+
+| Use case | Correct type | What NOT to use |
+|---|---|---|
+| Concurrent map (read-heavy or write-heavy) | `ConcurrentHashMap` | `HashMap` (not thread-safe), `Collections.synchronizedMap` (full lock on every op) |
+| Concurrent list, infrequent writes | `CopyOnWriteArrayList` | `ArrayList`, `Collections.synchronizedList` |
+| Concurrent queue / work queue | `LinkedBlockingQueue`, `ArrayBlockingQueue` | `LinkedList` |
+| Set | `ConcurrentHashMap.newKeySet()` | `HashSet` |
+| Cache with eviction | `Caffeine` or `Guava Cache` | `HashMap` with manual cleanup |
+
+### Pitfall — compound actions on `ConcurrentHashMap`
+
+```java
+// WRONG — check-then-put is not atomic
+if (!map.containsKey(key)) {
+    map.put(key, value);
+}
+// CORRECT
+map.putIfAbsent(key, value);
+// or for a more complex compute:
+map.computeIfAbsent(key, k -> expensiveCreate(k));
+```
+
+Even `ConcurrentHashMap` does not make compound actions atomic unless you use the atomic methods (`putIfAbsent`, `computeIfAbsent`, `merge`, `compute`).
+
+---
+
+## Static fields
+
+### Pitfall
+
+Static fields are shared across all class loader instances — effectively global state in a webapp. A static mutable field is the most dangerous form of shared state: it is not scoped to a component lifecycle, so it outlives bundle reactivations and can carry stale state.
+
+```java
+// dangerous — static mutable state in a webapp
+private static Map<String, Object> cache = new HashMap<>();
+```
+
+**Rule:** static fields in a Jahia module must be either:
+- `final` and truly immutable (constants, loggers), or
+- `volatile` / concurrent-typed with documented thread-safety, or
+- `ThreadLocal` (thread-scoped, not shared).
+
+If you need a cache or shared service state, use an OSGi `@Component` instance field — the OSGi lifecycle manages it correctly.
+
+---
+
+## `ThreadLocal`
+
+`ThreadLocal` gives each thread its own isolated copy of a variable. Correct for per-request state (locale, user context, transaction context).
+
+### Pitfall — thread pool reuse
+
+Jahia uses thread pools. A `ThreadLocal` set during request A and not cleared will be visible during a later request B handled by the same thread:
+
+```java
+// always clean up in a finally block
+threadLocal.set(value);
+try {
+    doWork();
+} finally {
+    threadLocal.remove(); // mandatory
+}
+```
+
+Failing to call `remove()` is a P1 finding — stale user context or locale leaked to subsequent requests.
+
+---
+
+## JCR sessions are NOT thread-safe
+
+A `JCRSessionWrapper` must never be shared across threads. Do not store a session as an instance field of an OSGi service and reuse it across requests.
+
+```java
+// WRONG — shared session across threads
+@Component
+public class MyService {
+    private JCRSessionWrapper session; // one session, all threads — crash under concurrency
+}
+```
+
+Always obtain a fresh session per-thread (and per-locale where i18n matters) and close it in a `finally` block or via `JCRTemplate`.
+
+---
+
+## Lazy initialization
+
+### Correct approach — `volatile` + double-checked locking
+
+```java
+private volatile ExpensiveObject instance;
+
+public ExpensiveObject get() {
+    if (instance == null) {                    // first check (no lock)
+        synchronized (this) {
+            if (instance == null) {            // second check (with lock)
+                instance = new ExpensiveObject();
+            }
+        }
+    }
+    return instance;
+}
+```
+
+Without `volatile`, the JVM may publish a partially-constructed object due to instruction reordering. **`volatile` on the field is mandatory for double-checked locking to be correct.**
+
+### Simpler alternative — holder idiom
+
+```java
+// no synchronization needed — class loading is inherently thread-safe
+private static class Holder {
+    static final ExpensiveObject INSTANCE = new ExpensiveObject();
+}
+public static ExpensiveObject get() { return Holder.INSTANCE; }
+```
+
+---
+
+## Review checklist
+
+When reviewing any class in a Jahia module, check:
+
+1. **Instance fields of `@Component` services** — are mutable ones `volatile`, atomic, or synchronized?
+2. **Static mutable fields** — flag immediately; require justification and correct synchronization.
+3. **Compound actions** — every check-then-act or read-modify-write on a shared field needs a lock or atomic CAS.
+4. **Collections returned from getters** — are they copies or unmodifiable views?
+5. **JCR sessions** — never stored as instance fields; always obtained and closed per-thread.
+6. **`ThreadLocal`** — always cleaned up in a `finally` block.
+7. **Locks** — held for the minimum possible time; no I/O inside a critical section.
+8. **Undocumented thread-safety contract** — if the class is not internally thread-safe, its Javadoc must say so and name the required external synchronization.

package/dist/gemini/.agents/skills/jahia-java-jcr/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: jahia-java-jcr
+description: JCR patterns for Jahia Java development — correct usage of sessions, workspaces, node operations, mixins, locks, and versioning. Covers both the right approach and the pitfalls that cause data loss, security gaps, or concurrency bugs. Load when implementing or reviewing any class that reads or writes the JCR.
+allowed-tools: Read
+---
+
+# JCR Patterns for Jahia Java
+
+This skill covers how to use the JCR correctly in a Jahia Java module. Each section states the correct approach first, then the pitfall to avoid. Both developers and reviewers use this skill: developers to implement correctly from the start, reviewers to identify violations.
+
+---
+
+## Session lifecycle and workspace
+
+### Correct approach
+
+- **User session** (`JCRSessionWrapper` obtained from `JCRSessionFactory.getCurrentUserSession(workspace, locale)`) enforces ACLs. Use this for any operation that should respect the user's permissions.
+- **System session** (`JCRTemplate.doExecuteWithSystemSession` or `JCRSessionFactory.getCurrentSystemSession`) bypasses ACLs. Use only when a permission check was performed earlier in the call chain and documented explicitly.
+- **Workspace boundary.** `default` (edit workspace, where authors work) vs `live` (published, visitor-facing). Public-facing reads must use `live`. Admin UIs use `default`. Writes that must appear publicly go through `PublicationService` — never write to `live` directly unless you have a specific operational reason.
+- **Locale.** `getCurrentUserSession(workspace, locale)` resolves i18n properties. Omitting the locale falls back to default — correct only if the caller truly does not need a specific locale.
+
+### Pitfalls
+
+- **System session without prior permission check.** When a system session performs an operation, trace back to where the target node ID came from. If it came from a user-session lookup with no further authorization check, the user-session lookup is the entire security boundary. Document this explicitly. If it is absent, it is a security finding.
+- **Workspace mismatch.** Reading from `default` when rendering public pages, or writing to `live` when the intended target is `default`. Both produce silent wrong behavior.
+- **Locale omission.** Calling without locale and reading `jcr:title` or any i18n property — the result is locale-nondeterministic.
+
+---
+
+## Node names — JSR-283 conformance
+
+### Correct approach
+
+Forbidden characters in a local name: `/ : [ ] | *`, plus whitespace-only names. Use `JCRContentUtils.escapeLocalNodeName` to sanitize any externally-supplied string before using it as a node name.
+
+### Pitfall
+
+Hand-rolled filename sanitization (regex replacements, `String.replace`) is almost always incomplete. The JSR-283 character set is non-obvious. Use the platform helper.
+
+---
+
+## Same-name siblings (SNS)
+
+### Correct approach
+
+Two children with the same name under the same parent are indexed `node[1]`, `node[2]`. If you need to find-or-create by name under concurrent load, either:
+- Lock the parent node before the check-then-create sequence.
+- Use a unique-by-construction name (UUID, slug+timestamp) and store the display name as a property.
+
+### Pitfall
+
+Unguarded find-or-create patterns under any concurrent caller (publication pipeline, event listener, HTTP endpoint) hit `ItemExistsException` or silently create a duplicate SNS node. Under guest endpoints this is a P1 finding.
+
+---
+
+## Mixin handling
+
+### Correct approach
+
+- Before setting properties specific to a mixin, call `node.addMixin("ns:myMixin")` if the node does not already have it.
+- Use `node.isNodeType("ns:myMixin")` to classify behavior rather than switching on concrete node type strings from another module. This keeps the engine decoupled from specific UI modules.
+- **Definition-level vs instance-level mixins.** Mixins applied in the CND definition are always present on every node of that type. Mixins added at runtime via `addMixin()` are instance-level — they must be captured and restored explicitly in any serialization/versioning path.
+
+### Pitfalls
+
+- Assuming a mixin is present because the content type "should" have it — this breaks when the content was created before the mixin was added to the definition.
+- Hardcoded concrete node-type strings from another module (`fmdb:inputText`, `fmdb:textarea`). The correct pattern is classifying mixins in the engine's own CND.
+- Serialization paths (export, versioning, diff) that capture `properties` but ignore `mixinNodeTypesNames` — instance-level mixin changes are silently lost on restore.
+
+---
+
+## Versioning and checkout
+
+### Correct approach
+
+Writing to a `mix:versionable` node requires a `checkout()` call first. After saving, call `checkin()` if the workflow requires it. Jahia's publication service handles this for standard publication flows — only write direct checkout/checkin in custom write paths.
+
+### Pitfall
+
+Writing to a versioned node without `checkout()` throws `VersionException`. Code that assumes the node is always in a checked-out state breaks whenever the publication service last left it checked in.
+
+---
+
+## Locking
+
+### Correct approach
+
+Respect existing locks before performing write operations. Before clearing a lock:
+1. Check whether the lock is owned by the current operation or by an external caller (another user, a publication job, a workflow).
+2. If the lock is external, **fail the operation** with a clear error — do not clear it silently and continue.
+3. Document the thread-safety contract of any write path that involves locking.
+
+### Pitfall
+
+```java
+// dangerous — clears locks unconditionally, continues even if clearing fails
+JCRContentUtils.clearAllLocks(node);
+restoreContent(node, version);
+```
+
+A node locked by an active publication job, a concurrent editor, or a workflow step is locked for a reason. Clearing it unconditionally can corrupt in-progress work. This is a P0 finding if the code ships to production; P1 if guarded by a feature flag that is off by default.
+
+---
+
+## JCR event listeners
+
+### Correct approach
+
+Register listeners in `@Activate` and unregister in `@Deactivate`. Use `JCRObservationManager` or Jahia's `DefaultEventListener` base class. Keep listeners short — heavy work should be dispatched to a separate thread or scheduled task.
+
+Event listener disabling via `JCRObservationManager.setAllEventListenersDisabled(true)` is **thread-local** in Jahia, not global. It is safe to use inside a request thread or a background thread without affecting other concurrent threads.
+
+### Pitfalls
+
+- Listeners registered but never unregistered — accumulate across reactivations, causing duplicate event processing.
+- Blocking I/O or JCR writes inside a synchronous event listener — holds the observation thread and causes lag across the entire event queue.
+
+---
+
+## `RepositoryException` handling
+
+### Correct approach
+
+- On a **security gate** (checking node type, checking permission): if the check throws, fail closed. Do not let the operation continue.
+- On a **data read**: if partial results would be misleading downstream, fail or return an empty result with a logged warning.
+
+### Pitfall
+
+```java
+try {
+    requiresAuth = node.isNodeType("...");
+} catch (RepositoryException e) {
+    log.warn(...);
+    return; // operation continues — fails open
+}
+```
+
+Fail-open on a security gate is a P0 finding. Fail-open on a data read producing misleading partial state is P0 or P1 depending on downstream impact.
+
+---
+
+## JCR SQL2 queries
+
+### Correct approach
+
+- Scope queries with `ISDESCENDANTNODE(alias, '/sites/...')` — never query the entire repository.
+- Use specific node types, not `nt:base`. Use `jmix:searchable` for broad content queries.
+- Parameterize with bind variables, not string concatenation.
+- Set a `LIMIT` on unbounded queries.
+
+### Pitfall
+
+`SELECT * FROM [nt:base]` against the full repository is a full-scan and blocks the query index. String-concatenated queries are a JCR injection vector (less critical than SQL injection but still wrong).