GH#104: docs: add superdav ai agent v1.16.0 documentation

docs/addons/superdav-ai-agent/abilities/create-menu.md

@@ -0,0 +1,116 @@
+---
+title: "Create Menu"
+sidebar_position: 3
+---
+
+# Create Menu
+
+The **Create Menu** ability creates WordPress navigation menus with support for distinct navigation labels separate from page titles.
+
+## Overview
+
+This ability extends the standard menu creation functionality with the ability to specify a `navigation_label` parameter. This allows you to create menus where the label displayed in navigation differs from the page title, providing more flexibility in site structure and user experience.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Menu name, e.g. `Primary Navigation` |
+| `location` | string | No | Theme location to assign this menu to, e.g. `primary` |
+| `navigation_label` | string | No | Label to display in navigation (distinct from page title) |
+
+## Return Value
+
+```json
+{
+  "success": true,
+  "menu_id": 7,
+  "name": "Primary Navigation",
+  "navigation_label": "Main Menu"
+}
+```
+
+## Navigation Label vs Page Title
+
+The `navigation_label` parameter allows you to separate the internal menu name from the label displayed to users:
+
+- **`name`** — Internal menu identifier used by WordPress (e.g., "Primary Navigation")
+- **`navigation_label`** — The label displayed to site visitors in the navigation (e.g., "Main Menu")
+
+This is useful when:
+- Your internal naming convention differs from user-facing labels
+- You want shorter labels in navigation than in the admin panel
+- You need to support multiple languages with different label lengths
+- You're building menus for specific regions or user groups
+
+## Usage Examples
+
+### Example 1: Simple Menu with Navigation Label
+
+**Prompt:**
+```
+Create a primary navigation menu called "Main Navigation" with the navigation label "Menu".
+```
+
+**Result:**
+```json
+{
+  "success": true,
+  "menu_id": 7,
+  "name": "Main Navigation",
+  "navigation_label": "Menu"
+}
+```
+
+### Example 2: Menu for Specific Theme Location
+
+**Prompt:**
+```
+Create a footer menu called "Footer Links" with navigation label "Quick Links" and assign it to the footer location.
+```
+
+**Result:**
+```json
+{
+  "success": true,
+  "menu_id": 8,
+  "name": "Footer Links",
+  "navigation_label": "Quick Links",
+  "location": "footer"
+}
+```
+
+## Integration with Theme Builder
+
+When using Theme Builder, the Create Menu ability:
+
+1. Automatically detects available theme menu locations
+2. Creates menus with appropriate navigation labels for your design
+3. Assigns menus to the correct theme locations
+4. Supports adding menu items after creation
+
+## Related Abilities
+
+- **`add_menu_item`** — Add items to an existing menu
+- **`update_menu`** — Rename a menu or reassign it to a theme location
+- **`delete_menu`** — Remove a menu from your site
+
+## Best Practices
+
+- **Use clear navigation labels** — keep labels concise and descriptive for users
+- **Match theme locations** — assign menus to the correct theme location for proper display
+- **Plan menu structure** — decide on your menu hierarchy before creating items
+- **Test responsiveness** — verify menus display correctly on mobile devices
+- **Localize labels** — use different navigation labels for different language versions
+
+## Limitations
+
+- Navigation labels are display-only; the internal `name` is still used for WordPress identification
+- Theme support varies; not all themes support all menu locations
+- Menu items must be added separately after menu creation
+- Changing a navigation label requires updating the menu
+
+## Related Abilities
+
+- [Generate Logo SVG](./generate-logo-svg.md) — create logos for your site header
+- [Validate Palette Contrast](./validate-palette-contrast.md) — ensure accessible color schemes

docs/addons/superdav-ai-agent/abilities/generate-logo-svg.md

@@ -0,0 +1,91 @@
+---
+title: "Generate Logo SVG"
+sidebar_position: 1
+---
+
+# Generate Logo SVG
+
+The **Generate Logo SVG** ability allows Theme Builder to create and embed custom logo SVGs directly into your WordPress site with automatic namespace-safe sanitisation.
+
+## Overview
+
+This ability generates scalable vector graphics (SVG) logos based on your site's branding direction and design preferences. The generated SVGs are automatically sanitised to ensure they are safe for use in WordPress while maintaining visual integrity.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `site_name` | string | Yes | The name of the site for which to generate the logo |
+| `style` | string | Yes | The design style (e.g., "modern", "classic", "minimalist", "playful") |
+| `colors` | array | No | Array of hex color codes to use in the logo (e.g., `["#678233", "#ffffff"]`) |
+| `width` | number | No | SVG width in pixels (default: 200) |
+| `height` | number | No | SVG height in pixels (default: 200) |
+| `include_text` | boolean | No | Whether to include the site name as text in the logo (default: true) |
+
+## Output Format
+
+The ability returns an SVG string with the following structure:
+
+```json
+{
+  "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 200 200\">...</svg>",
+  "width": 200,
+  "height": 200,
+  "colors_used": ["#678233", "#ffffff"],
+  "sanitised": true
+}
+```
+
+## SVG Sanitisation Behaviour
+
+The generated SVGs undergo automatic namespace-safe sanitisation to:
+
+- **Remove unsafe attributes** — strips event handlers, scripts, and potentially dangerous attributes
+- **Preserve namespaces** — maintains SVG namespaces (xmlns, xlink) for proper rendering
+- **Validate structure** — ensures the SVG conforms to W3C standards
+- **Encode entities** — properly escapes special characters in text content
+- **Remove external references** — strips external stylesheets and image references
+
+This ensures the SVG is safe to embed directly in WordPress without requiring additional sanitisation.
+
+## Usage Example
+
+**Prompt:**
+```
+Generate a modern logo for my tech startup called "CloudSync" using blue and white colors.
+```
+
+**Result:**
+The ability creates an SVG logo that:
+- Incorporates the site name "CloudSync"
+- Uses the specified blue and white color scheme
+- Follows modern design principles
+- Is automatically sanitised and ready to use
+
+## Integration with Theme Builder
+
+When using Theme Builder's design-direction selection, the Generate Logo SVG ability:
+
+1. Analyzes your design direction and color palette
+2. Generates a custom SVG logo matching your preferences
+3. Automatically embeds the logo into your site's header/branding area
+4. Stores the SVG as a custom logo in WordPress media
+
+## Best Practices
+
+- **Provide clear style preferences** — describe the design style you want (modern, classic, playful, etc.)
+- **Specify colors** — include your brand colors for consistency
+- **Test rendering** — verify the logo displays correctly across different screen sizes
+- **Customize further** — use WordPress's logo customization tools to adjust size and placement
+
+## Limitations
+
+- SVG logos are generated as static graphics (not animated)
+- Complex logos with many elements may require manual refinement
+- Custom fonts are not supported; text uses system fonts
+- Very large or very small dimensions may affect quality
+
+## Related Abilities
+
+- [Validate Palette Contrast](./validate-palette-contrast.md) — check color contrast for accessibility
+- [Create Menu](./create-menu.md) — create navigation menus for your site

docs/addons/superdav-ai-agent/abilities/validate-palette-contrast.md

@@ -0,0 +1,161 @@
+---
+title: "Validate Palette Contrast"
+sidebar_position: 2
+---
+
+# Validate Palette Contrast
+
+The **Validate Palette Contrast** ability checks colour pairs in your design palette for WCAG (Web Content Accessibility Guidelines) compliance before applying them to your theme.
+
+## Overview
+
+This ability ensures your site's color scheme meets accessibility standards by validating contrast ratios between text and background colors. It helps prevent color combinations that could be difficult for users with visual impairments to read.
+
+## Input Format
+
+The ability accepts a color palette as input:
+
+```json
+{
+  "colors": [
+    {
+      "name": "primary",
+      "hex": "#678233"
+    },
+    {
+      "name": "text",
+      "hex": "#ffffff"
+    },
+    {
+      "name": "background",
+      "hex": "#f5f5f5"
+    }
+  ],
+  "wcag_level": "AA"
+}
+```
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `colors` | array | Yes | Array of color objects with `name` and `hex` properties |
+| `wcag_level` | string | No | WCAG compliance level: "A", "AA" (default), or "AAA" |
+| `pairs_to_check` | array | No | Specific color pairs to validate (e.g., `["primary-text", "background-text"]`) |
+
+## WCAG Levels Checked
+
+The ability validates contrast ratios according to WCAG standards:
+
+| Level | Normal Text | Large Text | Minimum Ratio |
+|-------|-------------|------------|---------------|
+| **A** | 3:1 | 3:1 | 3:1 |
+| **AA** | 4.5:1 | 3:1 | 4.5:1 |
+| **AAA** | 7:1 | 4.5:1 | 7:1 |
+
+- **Normal Text** — text smaller than 18pt (or 14pt bold)
+- **Large Text** — text 18pt or larger (or 14pt bold or larger)
+
+## Output Schema
+
+The ability returns a detailed validation report:
+
+```json
+{
+  "compliant": true,
+  "wcag_level": "AA",
+  "pairs": [
+    {
+      "pair": "primary-text",
+      "color1": "#678233",
+      "color2": "#ffffff",
+      "contrast_ratio": 5.2,
+      "wcag_a": true,
+      "wcag_aa": true,
+      "wcag_aaa": false,
+      "status": "pass"
+    },
+    {
+      "pair": "background-text",
+      "color1": "#f5f5f5",
+      "color2": "#333333",
+      "contrast_ratio": 12.1,
+      "wcag_a": true,
+      "wcag_aa": true,
+      "wcag_aaa": true,
+      "status": "pass"
+    }
+  ],
+  "summary": {
+    "total_pairs": 2,
+    "passing": 2,
+    "failing": 0,
+    "recommendations": []
+  }
+}
+```
+
+### Output Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `compliant` | boolean | Whether the entire palette meets the specified WCAG level |
+| `wcag_level` | string | The WCAG level that was checked |
+| `pairs` | array | Detailed results for each color pair |
+| `contrast_ratio` | number | The calculated contrast ratio (1:1 to 21:1) |
+| `status` | string | "pass" or "fail" for each pair |
+| `recommendations` | array | Suggestions for improving failing pairs |
+
+## Usage Example
+
+**Prompt:**
+```
+Check if my color palette meets WCAG AA standards. I have primary color #678233, text color #ffffff, and background #f5f5f5.
+```
+
+**Result:**
+The ability validates all color combinations and returns:
+- ✅ Primary + Text: 5.2:1 ratio (passes WCAG AA)
+- ✅ Background + Text: 12.1:1 ratio (passes WCAG AAA)
+- Overall: Compliant with WCAG AA
+
+## Integration with Theme Builder
+
+When using Theme Builder's design-direction selection, the Validate Palette Contrast ability:
+
+1. Analyzes your selected color palette
+2. Checks all text-background combinations
+3. Validates against your chosen WCAG level
+4. Provides recommendations for non-compliant pairs
+5. Prevents applying inaccessible color schemes
+
+## Best Practices
+
+- **Start with AA level** — WCAG AA is the standard for most websites
+- **Test before applying** — validate your palette before committing to a design
+- **Check all combinations** — ensure text, links, and UI elements all meet standards
+- **Consider user preferences** — some users may have additional color sensitivity
+- **Use contrast checkers** — combine this ability with browser tools for verification
+
+## Failing Pairs and Recommendations
+
+If a color pair fails validation, the ability provides recommendations:
+
+```json
+{
+  "pair": "primary-text",
+  "status": "fail",
+  "contrast_ratio": 2.8,
+  "wcag_aa": false,
+  "recommendations": [
+    "Lighten the text color to #ffffff (ratio would be 5.2:1)",
+    "Darken the background color to #556b2f (ratio would be 4.8:1)",
+    "Use a different primary color like #4a6b1f (ratio would be 6.1:1)"
+  ]
+}
+```
+
+## Related Abilities
+
+- [Generate Logo SVG](./generate-logo-svg.md) — create logos with your validated color palette
+- [Create Menu](./create-menu.md) — build navigation with accessible colors

docs/addons/superdav-ai-agent/changelog.md

@@ -5,6 +5,23 @@ sidebar_position: 5
 
 # Changelog
 
+## 1.16.0 — Released on 2026-05-20
+
+### New
+
+- **Generate Logo SVG ability** — Theme Builder can now generate and embed custom logo SVGs with namespace-safe sanitisation
+- **Photo upload in discovery interview** — Theme Builder discovery interview now includes a photo upload step for richer design context
+- **Validate Palette Contrast ability** — check colour pairs for WCAG compliance before applying to a theme
+- **Hospitality menus** — Theme Builder can now generate structured food and beverage menu pages for hospitality businesses
+- **Desktop and mobile preview rendering** — preview your design on desktop and mobile devices during design-direction selection
+- **Navigation label parameter** — Create Menu ability now supports a distinct `navigation_label` separate from the page title
+- **Tier 1 tool availability** — sd-ai-agent/site-scrape is now a Tier 1 tool available by default in Theme Builder
+
+### Fixed
+
+- **AI Client cache** — now backed by transients for cross-request persistence, preventing data loss on long-running agent tasks
+- **Plugin row action links** — corrected and renamed for clarity
+
 ## 1.10.0 — Released on 2026-05-05
 
 ### New