feat(a11y): Accessibility Studio portlet + AI agent platform (@dotcms/ai, MCP server, agent UI)

.gitignore

@@ -150,6 +150,9 @@ dist-docs/
 
 #env
 /core-web/**/.env
+.env
+.env.*
+!.env.example
 
 /**/**/*.css.map
 
@@ -218,6 +221,9 @@ dist/
 *.egg
 .venv/
 
+# Local scratch space
+/core-web/scratch/
+
 # Spec-Kit working artifacts — process-only, kept local (see .specify/CUSTOMIZATIONS.md).
 # spec.md (and data-model.md / contracts/ when they carry verified contracts) stay tracked.
 specs/*/plan.md

core-web/.gitignore

@@ -1,5 +1,6 @@
 .env
-/libs/agentic-tools/src/generated
 
 vite.config.*.timestamp*
-vitest.config.*.timestamp*
+vitest.config.*.timestamp*
+
+.angular

core-web/apps/ai-evals/src/tools.ts

@@ -2,20 +2,13 @@ import { tool } from 'ai';
 import { z } from 'zod/v4';
 
 import { createApiAdapter } from '@dotcms/ai/adapter';
-import { createExecutor } from '@dotcms/ai/sandbox';
+import { createExecutor, formatSandboxResult } from '@dotcms/ai/sandbox';
 import { getSpec } from '@dotcms/ai/spec';
 
-function sandboxResult(
-    result: Awaited<ReturnType<ReturnType<typeof createExecutor>['execute']>>
-): string {
-    if (!result.success) return `Error: ${result.error?.name}: ${result.error?.message}`;
-    return typeof result.value === 'string' ? result.value : JSON.stringify(result.value, null, 2);
-}
-
 export function makeTools(dotcmsUrl: string, authToken: string) {
     // nosemgrep: detect-vercelai -- internal LLM eval harness (ai-evals), not shipped runtime code; Vercel AI SDK usage is intentional
     const searchTool = tool({
-        description: `Explore the dotCMS REST API spec. Write JavaScript with the \`spec\` global (spec.paths keyed by path string). Return the data you need.`,
+        description: `Explore the dotCMS REST API spec. Write JavaScript with the \`spec\` global (\`spec.paths\` + \`spec.components.schemas\`, \`$ref\`-based). Schemas in requestBody/responses are usually \`$ref\`s — call \`resolveRef(schemaOrName, depth)\` to expand them. Return the data you need.`,
         inputSchema: z.object({
             code: z
                 .string()
@@ -31,7 +24,7 @@ export function makeTools(dotcmsUrl: string, authToken: string) {
                 variables: { spec },
                 sandbox: { timeout: 10000 }
             });
-            return sandboxResult(result);
+            return formatSandboxResult(result);
         }
     });
 
@@ -54,7 +47,7 @@ export function makeTools(dotcmsUrl: string, authToken: string) {
                 sandbox: { timeout: 15000 },
                 adapters: ['api']
             });
-            return sandboxResult(result);
+            return formatSandboxResult(result);
         }
     });
 

core-web/apps/dotcms-ui/proxy-dev.conf.mjs

@@ -27,6 +27,51 @@ export default [
         changeOrigin: true,
         logLevel: 'debug'
     },
+    // 2. Embedded dotCMS page proxy (a11y portlet iframe).
+    //
+    // Lets the portlet iframe load live/edit-mode pages same-origin in dev.
+    // Use src="/dot-page/index?mode=EDIT_MODE" — the prefix is stripped so it
+    // hits the dotCMS page renderer (e.g. /index) on the BE. The sentinel prefix
+    // avoids colliding with the dev server's own Angular routes.
+    //
+    // DEV-ONLY WORKAROUND FOR A MISSING BACKEND CAPABILITY — do not delete this
+    // rule on its own; it is load-bearing (see below).
+    // --------------------------------------------------------------------------
+    // Why it exists: the Accessibility Studio's side-by-side frames are not
+    // passive previews. The run screen reaches INTO each iframe's contentWindow to
+    // inject the axe violation-marker overlay and to sync scroll between the two
+    // frames (see A11yMarkerService + DotA11yRunComponent.frameWindow). That is
+    // same-origin-only by the browser's security model — cross-origin frames throw
+    // on contentWindow access, so the markers silently never render.
+    //
+    // In prod there is no problem: the portlet is served FROM the dotCMS origin, so
+    // the page is already same-origin and the iframe needs no prefix at all. This
+    // rule exists purely because `nx serve` puts the app on a different origin than
+    // the backend, and it papers over that split in the dev server instead of in
+    // the platform.
+    //
+    // What the real fix is (BACKEND): dotCMS should expose a first-class,
+    // same-origin endpoint for rendering a page for inspection — i.e. a supported
+    // resource under /api that returns the page render, so the Studio (and any
+    // future agent that needs to inspect a rendered page) can frame it directly
+    // with no origin games and no dev-server rewrite. Today no such endpoint
+    // exists, which is the actual gap.
+    //
+    // Until that lands this rule must stay, and it must stay in sync with
+    // DotA11yRunComponent.previewPathPrefix, which emits the `/dot-page` sentinel
+    // under isDevMode(). Removing one without the other 404s the preview frames in
+    // local dev. Both should be deleted together once the backend endpoint exists.
+    {
+        context: ['/dot-page'],
+        target,
+        secure: false,
+        changeOrigin: true,
+        logLevel: 'debug',
+        followRedirects: false,
+        pathRewrite: {
+            '^/dot-page': ''
+        }
+    },
     // 2. Main API Proxy
     {
         context: [

core-web/apps/dotcms-ui/src/app/app.routes.ts

@@ -185,6 +185,12 @@ const PORTLETS_ANGULAR: Route[] = [
                 (m) => m.dotPublishingQueueRoutes
             )
     },
+    {
+        path: 'agents',
+        data: { reuseRoute: false },
+        loadChildren: () =>
+            import('@dotcms/portlets/dot-agents/portlet').then((m) => m.dotAgentsRoutes)
+    },
     {
         path: 'users',
         canActivate: [MenuGuardService],

core-web/apps/mcp-server/.env.example

@@ -4,5 +4,5 @@ DOTCMS_URL=
 # API token for authentication
 AUTH_TOKEN=
 
-# Sandbox execution timeout in milliseconds (default: 15000)
-SANDBOX_TIMEOUT=15000
+# Sandbox execution timeout in milliseconds (default: 45000)
+SANDBOX_TIMEOUT=45000

core-web/apps/mcp-server/CLAUDE.md

@@ -47,7 +47,7 @@ Configure the MCP server via the `env` block in your MCP client config:
 |---|---|---|
 | `DOTCMS_URL` | Yes | Base URL of the dotCMS instance |
 | `AUTH_TOKEN` | Yes | JWT Bearer token (generate in dotCMS → User Tools → API Tokens) |
-| `SANDBOX_TIMEOUT` | No | Sandbox execution timeout in ms (default: `15000`) |
+| `SANDBOX_TIMEOUT` | No | Sandbox execution timeout in ms (default: `45000`) |
 
 ## Architecture Overview
 
@@ -60,7 +60,7 @@ This is a **Model Context Protocol (MCP) server** for dotCMS, built with [xmcp](
 **Entry Point**: xmcp generates the entry point at build time (`dist/stdio.js`).
 
 **Build Pipeline**:
-1. `generate-spec` — fetches the OpenAPI spec from a dotCMS instance, processes it into `src/generated/spec.json` (dereferences $refs, filters to relevant endpoints)
+1. `generate-spec` — fetches the OpenAPI spec from a dotCMS instance, processes it into `src/generated/spec.json` (filters to relevant endpoints, keeps request/response `$ref`s, prunes `components.schemas` to just the schemas those endpoints reference)
 2. `xmcp build` — bundles everything with rspack into `dist/`
 
 **Tool Layer** (`src/tools/`):
@@ -86,7 +86,7 @@ This is a **Model Context Protocol (MCP) server** for dotCMS, built with [xmcp](
 - Main thread executes the actual HTTP call with injected auth
 - Result is posted back to the sandbox
 
-**Build-time Spec Processing**: `scripts/generate-spec.ts` fetches the OpenAPI spec from a URL (or reads a local file), dereferences it, filters to allowed endpoint prefixes, strips response schemas, and handles circular references. The developer must provide the spec URL or file path when running `generate-spec`.
+**Build-time Spec Processing**: `scripts/generate-spec.ts` (thin CLI) + `scripts/spec-transform.ts` (pure, testable logic) fetch the OpenAPI spec from a URL (or read a local file), filter to allowed endpoint prefixes, replace only Jersey-autogenerated multipart bodies with a placeholder (curated multipart schemas are kept), keep request/response `$ref`s as-is, and prune `components.schemas` to just the schemas transitively referenced by the kept paths. Keeping `$ref`s (rather than dereferencing) dedupes shared schemas and is naturally acyclic. The developer must provide the spec URL or file path when running `generate-spec`.
 
 ### Type System
 
@@ -99,7 +99,7 @@ All interfaces are in `src/lib/types.ts`:
 
 ### Search Tool
 **Purpose**: Explore the dotCMS REST API specification
-**Sandbox globals**: `spec` (the dereferenced OpenAPI spec object)
+**Sandbox globals**: `spec` (the filtered OpenAPI spec: `$ref`-based `paths` + `components.schemas`), plus helpers `resolveRef`, `pick`, `table`, `count`, `sum`, `first`. Use `resolveRef(schemaOrName, depth)` to expand `$ref`s at a bounded depth.
 **Read-only**: Yes — no side effects
 
 ### Execute Tool

core-web/apps/mcp-server/README.md

@@ -89,7 +89,7 @@ Before setting up the MCP server, you need these environment variables to connec
 | ------------------ | -------- | ---------------------------------- | ------- |
 | `DOTCMS_URL`  | ✅       | Your dotCMS instance URL           | `https://demo.dotcms.com` |
 | `AUTH_TOKEN` | ✅       | API authentication token (created in [setup step](#create-a-dotcms-api-token)) | `your-api-token-here` |
-| `SANDBOX_TIMEOUT`  | ❌       | Sandbox execution timeout in ms (default: 15000) | `15000` |
+| `SANDBOX_TIMEOUT`  | ❌       | Sandbox execution timeout in ms (default: 45000) | `45000` |
 | `DEBUG`            | ❌       | When set to any truthy value, emits diagnostic logs to stderr (e.g. context cache load events) | `1` |
 
 
@@ -208,7 +208,7 @@ The dotCMS MCP Server provides tools that enable comprehensive content managemen
 
 **Purpose**: Explore the dotCMS REST API specification using JavaScript code that runs in an isolated sandbox.
 
-The `spec` global contains the full dereferenced OpenAPI spec with `paths` object.
+The `spec` global contains the filtered OpenAPI spec — `$ref`-based, with a `paths` object and a `components.schemas` map. Request/response `.schema` values are usually `$ref`s (e.g. `{ $ref: '#/components/schemas/PageView' }`); call `resolveRef(schemaOrName, depth)` to expand them at a bounded depth. Output is hard-capped (~25k chars), so return only what you need.
 
 ```javascript
 // List all available endpoint paths
@@ -218,6 +218,9 @@ return Object.keys(spec.paths)
 return Object.entries(spec.paths)
   .filter(([path]) => path.includes('contenttype'))
   .map(([path, methods]) => ({ path, methods: Object.keys(methods) }))
+
+// Resolve a request-body schema one level deep
+return resolveRef(spec.paths['/api/v1/contenttype'].post.requestBody.content['application/json'].schema, 1)
 ```
 
 ### Execute
@@ -459,7 +462,7 @@ libs/sdk/ai/                      # Portable runtime primitives
 │   │       ├── bun-worker.ts   # Bun Web Worker sandbox
 │   │       └── node-worker.ts  # Node.js worker_threads sandbox
 │   └── generated/
-│       └── spec.json       # Committed processed OpenAPI spec
+│       └── spec.json       # Build-generated, git-ignored (lives in libs/sdk/ai)
 └── project.json            # Nx project configuration
 ```
 
@@ -479,7 +482,7 @@ libs/sdk/ai/                      # Portable runtime primitives
 -   Adapter pattern bridges sandbox ↔ main thread for API calls
 
 **Build-time Spec Processing**: The OpenAPI spec is pre-processed at build time:
--   `generate-spec` target dereferences `$ref` pointers and filters to relevant endpoints
+-   `generate-spec` target filters to relevant endpoints, keeps request/response `$ref`s, and prunes `components.schemas` to just the referenced schemas
 -   Output is a compact JSON embedded in the bundle
 -   Reduces runtime overhead and MCP response size
 
@@ -501,7 +504,7 @@ pnpm nx test mcp-server
 # Run tests in watch mode
 pnpm nx test mcp-server --watch
 
-# Refresh the OpenAPI spec (run when dotCMS API changes, then commit spec.json)
+# Refresh the OpenAPI spec (git-ignored; regenerated by build/serve/test via dependsOn)
 # Defaults to https://demo.dotcms.com/api/openapi.json
 pnpm nx run sdk-ai:generate-spec
 ```