Merge branch 'development' into kk-pmp-install

Author: katarzyna-koltun-mx

.claude/hooks/audit-log.sh

@@ -13,9 +13,9 @@ set -uo pipefail
 # ---------------------------------------------------------------------------
 INPUT="$(cat)"
 
-TOOL_NAME="$(printf '%s' "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name','unknown'))" 2>/dev/null || echo "unknown")"
+TOOL_NAME="$(printf '%s' "$INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null || echo "unknown")"
 
-COMMAND="$(printf '%s' "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null || echo "")"
+COMMAND="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null || echo "")"
 
 # ---------------------------------------------------------------------------
 # 2. Determine log file path (relative to project root)

.claude/hooks/validate-bash-command.sh

@@ -14,14 +14,15 @@ set -euo pipefail
 # ---------------------------------------------------------------------------
 INPUT="$(cat)"
 
-TOOL_NAME="$(printf '%s' "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null || true)"
+TOOL_NAME="$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null || true)"
 
-# Only validate Bash commands — allow everything else through
-if [[ "$TOOL_NAME" != "Bash" ]]; then
+# Only validate Bash commands — allow everything else through.
+# If TOOL_NAME is empty (parse failure), fall through to check the command anyway (fail closed).
+if [[ -n "$TOOL_NAME" && "$TOOL_NAME" != "Bash" ]]; then
   exit 0
 fi
 
-COMMAND="$(printf '%s' "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null || true)"
+COMMAND="$(printf '%s' "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null || true)"
 
 if [[ -z "$COMMAND" ]]; then
   exit 0
@@ -136,20 +137,19 @@ BLOCKED_PATTERNS=(
 # ---------------------------------------------------------------------------
 check_command() {
   local cmd="$1"
-  # Trim leading/trailing whitespace
-  cmd="$(echo "$cmd" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')"
+  # Trim leading/trailing whitespace using parameter expansion
+  cmd="${cmd#"${cmd%%[![:space:]]*}"}"
+  cmd="${cmd%"${cmd##*[![:space:]]}"}"
 
   if [[ -z "$cmd" ]]; then
     return 0
   fi
 
-  # Convert to lowercase for case-insensitive matching
-  local cmd_lower
-  cmd_lower="$(echo "$cmd" | tr '[:upper:]' '[:lower:]')"
+  # Convert to lowercase using parameter expansion
+  local cmd_lower="${cmd,,}"
 
   for pattern in "${BLOCKED_PATTERNS[@]}"; do
-    local pattern_lower
-    pattern_lower="$(echo "$pattern" | tr '[:upper:]' '[:lower:]')"
+    local pattern_lower="${pattern,,}"
 
     # shellcheck disable=SC2254
     if [[ "$cmd_lower" == $pattern_lower ]]; then
@@ -164,8 +164,12 @@ check_command() {
 # ---------------------------------------------------------------------------
 # 4. Split on pipes and command chains, then check each sub-command
 # ---------------------------------------------------------------------------
-# Replace common chain operators with a delimiter
-NORMALIZED="$(echo "$COMMAND" | sed 's/&&/\n/g; s/||/\n/g; s/;/\n/g; s/|/\n/g')"
+# Replace common chain operators with newlines using parameter expansion
+# Order matters: replace && and || before | to avoid double-splitting ||
+NORMALIZED="${COMMAND//&&/$'\n'}"
+NORMALIZED="${NORMALIZED//||/$'\n'}"
+NORMALIZED="${NORMALIZED//;/$'\n'}"
+NORMALIZED="${NORMALIZED//|/$'\n'}"
 
 while IFS= read -r subcmd; do
   check_command "$subcmd"

.claude/scripts/README.md

@@ -0,0 +1,38 @@
+# Claude Helper Scripts
+
+Utility scripts to support Claude Code when working with this documentation repository.
+
+## resolve-doc-url.sh
+
+Resolves a documentation URL to its source markdown file.
+
+### Usage
+
+```bash
+.claude/scripts/resolve-doc-url.sh "/path/to/page/"
+```
+
+### Examples
+
+```bash
+# Find the file for a specific URL
+.claude/scripts/resolve-doc-url.sh "/community-tools/contribute-to-mendix-docs/"
+# Output: content/en/docs/community-tools/contribute-to-mendix-docs/_index.md
+
+# Check if a URL exists
+.claude/scripts/resolve-doc-url.sh "/some/page/"
+# Exit code 0 if found, 1 if not found
+```
+
+### Benefits
+
+- **Fast**: Uses grep optimized for file-only output
+- **Token-efficient**: Returns only the file path, no surrounding context
+- **Reliable**: Matches exact URL in front matter using fixed-string search
+
+### When to Use
+
+- Following cross-references between documentation pages
+- Validating internal links
+- Finding files by their published URL
+- Checking if a URL is already in use

.claude/scripts/resolve-doc-url.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+# Resolve a documentation URL to its source markdown file
+# Usage: resolve-doc-url.sh "/url/path/"
+
+if [ -z "$1" ]; then
+    echo "Usage: resolve-doc-url.sh <url>"
+    echo "Example: resolve-doc-url.sh '/community-tools/contribute-to-mendix-docs/'"
+    exit 1
+fi
+
+# Search for the URL in front matter
+# Using grep with -l (files only) and -F (fixed string) for speed
+grep -rl --include="*.md" "^url: $1$" content/en/docs/
+
+# Exit code 0 if found, 1 if not found

.claude/settings.json

@@ -1,16 +1,17 @@
 {
+  "_comment": "DO NOT EDIT THIS FILE. To override these settings, use .claude/settings.local.json instead.",
   "env": {
     "CLAUDE_CODE_ENABLE_TELEMETRY": "0",
     "DISABLE_TELEMETRY": "1",
     "OTEL_METRICS_EXPORTER": "otlp",
     "AWS_PROFILE": "my-sandbox",
     "AWS_REGION": "eu-central-1",
     "CLAUDE_CODE_USE_BEDROCK": "1",
-    "ANTHROPIC_MODEL": "eu.anthropic.claude-sonnet-4-5-20250929-v1:0",
+    "ANTHROPIC_MODEL": "eu.anthropic.claude-sonnet-4-6",
     "ANTHROPIC_SMALL_FAST_MODEL": "eu.anthropic.claude-haiku-4-5-20251001-v1:0",
     "ANTHROPIC_DEFAULT_HAIKU_MODEL": "eu.anthropic.claude-haiku-4-5-20251001-v1:0",
-    "ANTHROPIC_DEFAULT_OPUS_MODEL": "eu.anthropic.claude-opus-4-6-v1",
-    "ANTHROPIC_DEFAULT_SONNET_MODEL": "eu.anthropic.claude-sonnet-4-5-20250929-v1:0",
+    "ANTHROPIC_DEFAULT_OPUS_MODEL": "eu.anthropic.claude-opus-4-8",
+    "ANTHROPIC_DEFAULT_SONNET_MODEL": "eu.anthropic.claude-sonnet-4-6",
     "DISABLE_PROMPT_CACHING": "0",
     "CLAUDE_CODE_MAX_OUTPUT_TOKENS": "10240",
     "MAX_THINKING_TOKENS": "1024"
@@ -173,18 +174,18 @@
     "PreToolUse": [
       {
         "matcher": "Bash",
-        "hooks": [{"type": "command", "command": ".claude/hooks/validate-bash-command.sh"}]
+        "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate-bash-command.sh"}]
       }
     ],
     "PostToolUse": [
       {
         "matcher": "*",
-        "hooks": [{"type": "command", "command": ".claude/hooks/audit-log.sh"}]
+        "hooks": [{"type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/audit-log.sh"}]
       }
     ]
   },
   "statusLine": {
     "type": "command",
-    "command": ".claude/statusline.sh"
+    "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/statusline.sh"
   }
 }

.claude/skills/add/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: docs-add
+description: Adds new content to a single documentation page while preserving the original structure and meaning. Integrates new sections, paragraphs, or information smoothly with appropriate transitions. Use when the user wants to add, insert, include, or append new content to existing pages without rewriting what's already there.
+user-invocable: true
+disable-model-invocation: true
+---
+
+> **After adding content:** Consider running `/docs-polish` to improve clarity or `/docs-proofread` to check for errors in the final result.
+
+Ask the user for the new content to add. Determine a suitable place to smoothly integrate the new content into the existing content, with appropriate transitions and formatting, while preserving the original meaning and structure of the page. Don't make changes to existing content unless necessary for clarity or coherence when adding the new content.
+
+If the new content introduces redundancy or conflicts with existing content, flag these issues in the chat and suggest ways to resolve them without directly editing the existing content.

.claude/skills/docs-add/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: docs-alt-text
+description: Generates W3C-compliant alt text for images in documentation pages. Analyzes each image's purpose and adds descriptive alt text for informative images or empty alt for decorative images, improving accessibility and SEO.
+user-invocable: true
+disable-model-invocation: false
+---
+
+> **Accessibility skill:** Generates alt text following W3C/WCAG 2.1 guidelines. Analyzes actual image content plus context to create concise, meaningful descriptions.
+
+## Workflow
+
+Follow this order for each image:
+
+1. **STEP 1 - View the image file** (REQUIRED)
+   - Extract image src path from figure shortcode
+   - Convert path: `src="/attachments/path/file.png"` → `static/attachments/path/file.png`
+   - Use Read tool to view the actual image
+   - Understand what the image shows BEFORE reading context
+
+2. **STEP 2 - Read surrounding context**
+   - Read the heading, preceding/following text, list item, or numbered step
+   - Understand the image's purpose within the documentation
+   - Consider if context + image together make the image informative or decorative
+
+3. **STEP 3 - Determine if informative or decorative**
+   - **Technical docs assumption:** Images are informative unless obviously decorative
+   - **Informative:** Images that convey information → write descriptive alt text
+   - **Decorative:** Images where the information is already given in adjacent text, or pure visual styling with no informational value → use `alt=""`
+
+4. **STEP 4 - Generate alt text**
+   - **If decorative, use `alt=""`.** Never omit the alt attribute entirely.
+   - **If informative, generate descriptive alt text:**
+      - Focus on the information the image communicates, not what it looks like
+      - Give the most concise description possible
+      - Maximum 30 words (flag complex images needing longer descriptions for body text)
+      - Don't include "screenshot of", "image of", or "picture of" (screen readers already announce it's an image)
+      - Use Mendix terminology
+      - Avoid redundancy with nearby text
+      - **Based on surrounding context:**
+         - In a procedure: emphasize the action/element relevant to the step (e.g., "Download button in Registration dialog")
+         - Showing UI elements: name the relevant elements (e.g., "Properties pane")
+         - Showing structure or relationships: describe what entities/components are connected (e.g., "Domain model with Customer and Order entities connected by one-to-many association")
+         - Showing logic or process flow: describe what the flow accomplishes (e.g., "Microflow that retrieves FileDocument list and updates encryption keys")
+
+5. **STEP 5 - Edit the figure shortcode**
+   - Use Edit tool to add/update only the `alt` attribute
+   - Preserve all other attributes: `class`, `width`, `max-width`, `link`
+   - Maintain exact indentation and spacing
+
+## Special Cases
+
+- **Images in numbered lists:** Common in procedures—describe the procedural step shown
+- **Before/after sequences:** Describe what changed or the state shown
+- **Existing alt text:** May update if it's empty, generic, or poor quality (e.g., `alt=""`, `alt="button"`, `alt="before"`)
+- **File format icons:** Use format name (e.g., "PDF", "ZIP", "Word document")
+- **Complex diagrams:** If needs >30 words, flag to user and suggest adding description to body text
+
+## What NOT to do
+
+- Don't modify `src` path or attributes other than `alt`
+- Don't change surrounding text or document structure
+- Don't process images outside the determined scope
+- Don't generate alt text based solely on filename—always view the image first
+
+## After Processing
+
+Report summary:
+- How many images processed
+- How many updated
+
+**Always suggest user review:** Recommend that the user review the images themselves to confirm alt text accuracy, as AI-generated descriptions may miss important nuances or context-specific details.

.claude/skills/docs-alt-text/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: docs-enhance
+description: Comprehensively edits a single documentation page including reorganization, restructuring, and rephrasing while preserving original meaning and intent. Improves flow, strengthens weak phrasing, and enhances overall quality. Use when documentation needs significant structural improvements, better organization, or when the user mentions reorganize, restructure, rewrite, or enhance.
+user-invocable: true
+disable-model-invocation: true
+---
+
+> **Skill progression:** This is the most intensive editing. If restructuring isn't needed, use `/docs-polish` for clarity improvements or `/docs-proofread` for basic fixes.
+
+Perform holistic improvements, including reorganization and stronger phrasing, while preserving original intent. This goes beyond basic proofreading and polishing to enhance the overall quality and impact of the text. Consider restructuring sentences, paragraphs, or sections for better flow, replacing weak words with stronger alternatives, and improving clarity and consistency while maintaining the original meaning. However, avoid making changes just for the sake of change; every edit should serve a clear purpose in enhancing the text.

.claude/skills/docs-enhance/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: docs-polish
+description: Applies style guide standards to a documentation page without changing meaning or reorganizing structure. This includes fixing grammar, improving clarity and readability, simplifying complex sentences, using active voice, and standardizing terminology and formatting. Use when the user wants to polish, check style guide compliance, improve language, or clean up documentation while preserving its structure.
+user-invocable: true
+disable-model-invocation: false
+---
+
+> **Skill progression:** This does everything `/docs-proofread` does plus style guide enforcement including clarity improvements. If only grammar and spelling fixes are needed, use `/docs-proofread`. For deeper reorganization, suggest `/docs-enhance`. If missing alt text is found, suggest `/docs-alt-text`.
+
+Improve clarity and readability without changing meaning, structure, or paragraph order:
+
+**docs-polish should**:
+* Read Mendix style guides first (in parallel): `grammar-formatting.md`, `terminology.md`, and `product-naming-guide.md` from `/content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/`
+* Fix all spelling, grammar, and punctuation errors
+* Check all figure shortcodes for missing alt text. If the alt text parameter is missing, insert `alt=""` as a placeholder.
+* Ensure required front matter fields are present (title, url, description) and make descriptions concise and action-oriented
+* Fix broken Markdown syntax
+* Fix capitalization and terminology inconsistencies
+* Break up long, complex sentences for better readability
+* Simplify wordy or awkward phrasing
+* Improve word choice (more precise or accessible terms)
+* Change passive voice to active voice where appropriate
+* Remove first-person plural (we, us, our, let's), except in release notes
+* Remove bold and italics used for emphasis (reword or use alert shortcodes if needed)
+* Apply Mendix style guide standards (overrides the Microsoft Writing Style Guide)
+* Apply Microsoft Writing Style Guide standards, unless they conflict with the Mendix style guide standards
+
+**After completing edits**:
+* Report what was changed in a concise summary
+* If any images were found with missing or empty alt text, state "I found [N] image(s) with missing alt text. Consider running `/docs-alt-text` to generate alt text."
+
+**docs-polish should NOT**:
+* Move paragraphs or restructure sections (that's `/docs-enhance`)
+* Change technical meaning or accuracy
+* Significantly increase document length
+* Generate alt text for images
+* Change command syntax, code identifiers, variable names, placeholders, or any other text that appears in code formatting (inline backticks or code blocks). Code-formatted text represents literal technical content that must remain unchanged. If you notice an issue with code-formatted text, flag it in the chat but don't edit it directly.
+
+Every edit should serve a clear purpose in making the text easier to read, scan, and understand.
+
+Priority order for determining scope:
+1. If the user has selected text in a file (check for `ide_selection` tags), only polish the selected text in that file. Don't polish the entire document.
+2. If there's one open file (check for `ide_opened_file` tags) and no selection, work on the entire file.
+3. If there are multiple open files, list them and ask which to process.
+4. If no files are open, ask for a file path.