@rudderhq/agent-runtime-codex-local 0.4.6-canary.8 → 0.5.0

package/skills/rudder-docs/references/control-plane-practices.md

@@ -0,0 +1,231 @@
+# Rudder Control-Plane Practices
+
+Consult this reference only for questions about exact Rudder operating
+behavior. It is conditional documentation, not a trigger and not an always-run
+workflow. For exact tool and CLI syntax, pair the relevant rule with
+`cli-reference.md` instead of recreating its command table here.
+
+## Section Map
+
+- [Interface and scope](#interface-and-scope)
+- [Ownership, checkout, and wake scope](#ownership-checkout-and-wake-scope)
+- [Comments, mentions, and evidence](#comments-mentions-and-evidence)
+- [Review and close-out](#review-and-close-out)
+- [Approvals](#approvals)
+- [Delegation, escalation, and budget](#delegation-escalation-and-budget)
+- [Git identity and attribution](#git-identity-and-attribution)
+- [Workspaces, projects, and resources](#workspaces-projects-and-resources)
+- [Durable Library artifacts](#durable-library-artifacts)
+- [Organization and agent skills](#organization-and-agent-skills)
+- [Authentication and runtime environment](#authentication-and-runtime-environment)
+- [User activity context](#user-activity-context)
+
+## Interface And Scope
+
+- Prefer exposed first-party Rudder typed tools for normal control-plane work.
+  Use the installed `rudder ... --json` CLI as the compatibility fallback when
+  MCP is unavailable or a Rudder tool has a transport or configuration error.
+- Use `rudder agent capabilities --json` to discover the current capability
+  set. Treat direct API use as an internal, debugging, or compatibility path,
+  not the normal interface.
+- Direct API fallback for required close-out is acceptable only when the CLI
+  exits nonzero with a diagnostic error or incorrectly exits zero with empty
+  stdout. Record the failed command and fallback reason in the issue comment or
+  run notes.
+- If wake text explicitly declares HTTP compatibility mode, follow that
+  bounded mode for the run.
+
+Chat and issues are parallel work surfaces. Continue chat-scoped work in Chat
+unless the operator asks for issue structure or team policy requires explicit
+ownership, status, dependencies, or review. Do not create an issue merely
+because work is executable, durable, long-running, or reviewable.
+
+## Ownership, Checkout, And Wake Scope
+
+- Before issue-scoped execution, checkout the assigned issue. Never retry a
+  checkout that returns `409`; stop and report the ownership conflict.
+- Never look for unassigned work. Work the authenticated agent's assignee or
+  reviewer inbox and the explicit wake context.
+- Self-assign only when a wake comment explicitly transfers ownership.
+- A wake on an issue not assigned to the agent, including a user-owned or
+  unassigned issue, is scoped to that comment unless it explicitly requests
+  implementation, file changes, close-out, or ownership transfer. Answer a
+  question as a question; do not silently take over the whole issue.
+- Treat `issue_passive_followup` as follow-up on the same issue, not a fresh
+  assignment. Treat `issue_review_closeout_missing` as review follow-up.
+
+## Comments, Mentions, And Evidence
+
+- Keep issue comments concise: a short status line, the material change or
+  blocker, validation evidence, and links to related entities, Library files,
+  or external pages.
+- Use normal Markdown links with Rudder's canonical renderable entity schemes:
+  `issue://`, `agent://`, `automation://`, `project://`, `chat://`, and
+  `skill://`. Add `?c=<comment-id>` to an issue URI for a specific comment.
+- Add `?intent=wake` to an agent URI only when intentionally waking that agent;
+  omit it for a reference-only link. Plain text names are not wake requests.
+- For Library files, copy the returned `markdownLink` instead of constructing a
+  URI. Link external pages with a descriptive Markdown `https` link.
+- Multiline comments, code spans, test summaries, and Markdown should be passed
+  from a file or stdin according to the CLI reference. Do not depend on fragile
+  shell interpolation.
+- Attach each screenshot or image with `--image` when it is evidence in an
+  issue comment or close-out. A local filesystem path alone is not inspectable
+  by board users.
+- Always communicate before exiting active issue work, except when a blocked
+  issue has no new context to report.
+
+## Review And Close-Out
+
+Use the close-out signal matching the outcome: a progress comment when work
+remains, done with completion evidence, blocked with a blocker comment, or an
+explicit handoff comment with an ownership change.
+
+If blocked, set the issue to `blocked`, identify the blocker, name the next
+actor or action, and leave the blocker comment before exit. Do not present
+partial work as complete.
+
+A reviewer does not take over implementation unless explicitly asked.
+Reviewer work may cover `in_review` or `blocked`; the latter is blocker triage,
+not implementation ownership. Record one structured durable decision:
+
+- `--decision approve` for accepted work;
+- `--decision request_changes` for required changes;
+- `--decision needs_followup` when review remains open; or
+- `--decision blocked` only for a confirmed human or external blocker, with
+  the next human action named.
+
+Do not rely on free-form accept, reject, or change-request text as the review
+outcome. The structured decision is the durable close-out signal.
+
+## Approvals
+
+When `RUDDER_APPROVAL_ID` is present, read the approval and its linked issues
+before acting. Preserve the approval boundary: comment, request revision,
+resubmit, approve, or reject only through the governed approval surface and
+only when the current actor is authorized. An approval question does not grant
+permission for the underlying mutation. When an approval remains unresolved,
+report the status and required follow-up rather than bypassing it.
+
+## Delegation, Escalation, And Budget
+
+- Agent-created issues default to the creating agent when no assignee is
+  supplied. Set an explicit assignee when delegating to someone else.
+- Always set `parentId` for delegated work. Set `goalId` unless intentionally
+  creating top-level management work. When the organization has a mature label
+  taxonomy, choose at least one suitable label after inspecting the available
+  labels.
+- Never cancel cross-team work. Reassign upward with an explanation, and use
+  `chainOfCommand` for escalation.
+- Above 80% spend, focus on critical work only and avoid expanding scope.
+- Use the canonical `rudder-create-agent` workflow for hiring or agent creation
+  rather than assembling a raw control-plane payload.
+
+## Git Identity And Attribution
+
+Every agent-created commit must include this trailer at the end of the commit
+message:
+
+`Co-Authored-By: Rudder <285064165+Rudderhq@users.noreply.github.com>`
+
+Use an explicit safe Git identity. Rudder prepares isolated runtime worktrees
+with `user.useConfigOnly=true`; if Git reports a missing identity, configure
+repository-local `user.name` and `user.email`. Do not bypass the guard and
+never accept `*@*.local` author or committer metadata.
+
+## Workspaces, Projects, And Resources
+
+Each organization has one managed shared workspace under its Rudder instance.
+The organization storage key is filesystem-safe; for UUID-backed organizations
+it is the first 12 lowercase hexadecimal characters with dashes removed. APIs
+continue to use the full organization ID.
+
+- The organization Resources catalog is reusable shared context, but it is not
+  injected wholesale into every run.
+- A project-linked run or chat receives only that project's attached
+  resources. Project Context is the curated starting set, not a knowledge
+  boundary; inspect broader Library or organization workspace knowledge when
+  the attached set is insufficient.
+- Library resources use `sourceType: "library"` and safe locators below
+  `library:projects/<project-key>/`. External resources retain their original
+  URL, local path, repository path, or connector locator.
+- Use Workspaces for disk-backed shared files and skill packages. Agent-private
+  files live below the agent's workspace key. New projects do not create
+  independent workspace roots.
+- Preserve organization and workspace boundaries. Do not query or copy another
+  organization's private resources to fill a context gap.
+- Use the typed project or stable CLI surface for project records; do not
+  substitute ad hoc API mutations.
+
+## Durable Library Artifacts
+
+With project context in a local trusted run, write durable project work under
+`$RUDDER_PROJECT_LIBRARY_ROOT`. Use
+`$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>` only when requesting a
+renderable Rudder reference.
+
+Without project context, write durable generated chat or work artifacts under
+`$RUDDER_ORG_WORKSPACE_ROOT/artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`
+and use the product locator
+`library:artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`. Do not choose an existing project, such as Getting Started, merely to obtain a project
+Library path. Reserve temporary directories for scratch and verification
+artifacts.
+
+After creating or changing a durable Library file, request its stable
+`markdownLink` using `rudder library file ref` with the Library-relative path.
+Use that returned link in the final chat reply, issue comment, review, blocker,
+or done comment. Direct filesystem writes are not complete Rudder-visible
+handoff evidence until the returned link is posted.
+
+Do not hand-write `library-entry://` URLs or their query parameters. Copy the
+returned `mentionHref` or `markdownLink`; the entry ID is stable identity and a
+Rudder-generated `p` value is only a synchronous path hint. Treat
+`library-file://` and `library-doc://` as legacy references for existing
+content, not new links.
+
+Use `rudder library file get/put` only when the local Library filesystem is
+unavailable, such as a remote or restricted runtime. With project context the
+fallback path is `$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>`; without it,
+use `artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`. These are
+Library-relative paths, never absolute workspace paths.
+
+Do not mark an issue done when the request was only to create or revise a plan.
+Reassign the plan for review when that is the expected workflow, and include
+the returned `markdownLink` in the handoff. The retired `rudder issue
+documents` surface is not a durable-plan path.
+
+## Organization And Agent Skills
+
+For private skills used only by the running agent, prefer agent-private skill
+creation under `AGENT_HOME/skills`, then confirm the skill is enabled in the
+agent snapshot. Installed but disabled skills do not load on future runs.
+
+For organization discovery, import, inspection, and assignment, consult
+`organization-skills.md`. `skills enable` is additive and preserves existing
+optional selections; `skills sync` replaces the full optional enabled-skill
+set and should be used only when replacement is intentional. Do not fall back
+to raw HTTP for this workflow in local adapters or packaged Desktop.
+
+## Authentication And Runtime Environment
+
+Rudder normally injects the runtime context, including `RUDDER_AGENT_ID`,
+`RUDDER_ORG_ID`, `RUDDER_API_URL`, `RUDDER_API_KEY`, and `RUDDER_RUN_ID`.
+Issue, wake, or approval contexts may also provide `RUDDER_TASK_ID`,
+`RUDDER_WAKE_REASON`, `RUDDER_WAKE_COMMENT_ID`, `RUDDER_APPROVAL_ID`,
+`RUDDER_APPROVAL_STATUS`, and `RUDDER_LINKED_ISSUE_IDS`.
+
+Never ask for `RUDDER_API_KEY`; never print it. Do not hard-code the API URL.
+For local adapters and packaged Desktop, the installed `rudder` binary should
+already be on `PATH`. Manual local CLI setup outside a managed run may use the
+documented local-cli authentication flow, but it must preserve organization
+scope and should not expose the minted key in durable output.
+
+## User Activity Context
+
+Use the user activity ledger when a question depends on recent user-authored
+Rudder activity, such as today's conversations, feedback, or handoff context.
+The ledger's excerpts are pointers with provenance, not ground truth when exact
+wording matters. Inspect the cited source before writing durable memory,
+profile changes, or stable preference conclusions. Do not use the ledger to
+bypass permissions or promote private content into long-term memory without a
+clear durable operating lesson.

package/skills/{rudder → rudder-docs}/references/organization-skills.md

@@ -2,7 +2,10 @@
 
 Use this reference when a board user or authorized agent asks you to discover, import, inspect, or enable organization skills.
 
-This workflow is now **CLI-first** for the bundled `rudder` skill.
+This is the organization and agent-skill administration reference for the
+bundled `rudder-docs` package. Use the typed Rudder tool when exposed and the
+documented CLI as its compatibility fallback. General control-plane ownership,
+authentication, and workspace rules remain in `control-plane-practices.md`.
 
 For a skill that belongs only to the running agent, do not use organization import or scan commands. Use:
 
@@ -12,6 +15,17 @@ rudder agent skills create "$RUDDER_AGENT_ID" --name "<name>" --description "<de
 
 Agent-private skill creation writes under `AGENT_HOME/skills` and does not require organization skill mutation permission.
 
+## Section Map
+
+- [Canonical model](#canonical-model)
+- [Core CLI surface](#core-cli-surface)
+- [Source types](#source-types)
+- [Import examples](#import-examples)
+- [Inspect imported skills](#inspect-imported-skills)
+- [Enable skills on an existing agent](#enable-skills-on-an-existing-agent)
+- [Permission model](#permission-model)
+- [Notes](#notes)
+
 ## Canonical Model
 
 1. import or scan the skill into the organization library

package/skills/rudder-docs/references/source-map.md

@@ -0,0 +1,138 @@
+# Rudder Documentation And Source Map
+
+Use this map to choose a narrow evidence route. It describes stable domains and
+directories rather than an exhaustive page list. Follow the current checkout's
+`AGENTS.md` before repository inspection.
+
+## Section Map
+
+- [Official public documentation](#official-public-documentation)
+- [Product Logic Registry](#product-logic-registry)
+- [Contributor and engineering documentation](#contributor-and-engineering-documentation)
+- [Implementation and tests](#implementation-and-tests)
+- [Official remote source and version history](#official-remote-source-and-version-history)
+- [Bundled offline references](#bundled-offline-references)
+- [Targeted search patterns](#targeted-search-patterns)
+
+## Official Public Documentation
+
+- Index: `https://docs.rudderhq.dev/llms.txt`
+- Site: `https://docs.rudderhq.dev/`
+- Local public-docs checkout: `docs/`
+
+Start with the index, choose the page matching the user's job, and open one or
+two pages. Prefer the user's language when equivalent official pages exist.
+Public docs own published user guidance; a local `docs/` checkout is useful
+when the live site is unavailable or the task is editing the public site.
+
+## Product Logic Registry
+
+- Entry point: `doc/product/README.md`
+- Registry map: `doc/product/registry.yml`
+- Domain contracts: `doc/product/domains/`
+- Composed workflows: `doc/product/workflows/`
+- Surface-to-contract maps: `doc/product/surfaces/`
+
+Use Product Logic for intended product semantics and invariants. Start at the
+registry entry point and select the owning domain rather than scanning all
+contracts. Reading these guarded files does not authorize editing them.
+
+Common domain routes include:
+
+- agents, skills, and inbox: `doc/product/domains/agents/`
+- issues and issue-visible state: `doc/product/domains/issues/`
+- assignment, checkout, review routing: `doc/product/domains/work-routing/`
+- runs, execution, transcripts, workspaces: `doc/product/domains/execution/`
+- organizations, goals, and projects:
+  `doc/product/domains/organizations-and-goals/`
+- Library, resources, and runtime context:
+  `doc/product/domains/library-and-context/`
+- Chat, Messenger, comments, and integrations:
+  `doc/product/domains/collaboration/`
+- approvals, budgets, costs, and activity:
+  `doc/product/domains/control-plane/`
+- reviews, feedback, and learning:
+  `doc/product/domains/review-feedback-learning/`
+- automations: `doc/product/domains/automations/`
+- plugins: `doc/product/domains/plugins/`
+
+## Contributor And Engineering Documentation
+
+- Route selector: `doc/README.md`
+- Development: `doc/engineering/DEVELOPING.md`
+- CLI: `doc/engineering/CLI.md`
+- Database: `doc/engineering/DATABASE.md`
+- Deployment modes: `doc/engineering/DEPLOYMENT-MODES.md`
+- Desktop and packaging: `doc/engineering/DESKTOP.md`
+- Design: `doc/engineering/DESIGN.md`
+- Releases and publishing: `doc/engineering/RELEASING.md` and
+  `doc/engineering/PUBLISHING.md`
+- Plugin contracts: `doc/engineering/PLUGIN_AUTHORING_GUIDE.md` and
+  `doc/engineering/PLUGIN_RUNTIME_CONTRACT.md`
+- Dated decisions and proposals: `doc/plans/`
+- Historical archaeology only: `doc/archive/`
+
+Contributor docs own build, operation, packaging, and architecture guidance.
+Plans explain decisions in time; archived documents are not current behavior
+contracts.
+
+## Implementation And Tests
+
+Use source and tests for exact implementation evidence:
+
+| Area | Owning source | Tests |
+| --- | --- | --- |
+| REST routes and orchestration services | `server/src/routes/`, `server/src/services/` | `server/src/__tests__/` |
+| Shared API types, validators, and constants | `packages/shared/src/` | colocated `*.test.ts` plus server/UI consumers |
+| Database schema and migrations | `packages/db/src/schema/`, `packages/db/src/migrations/` | package tests and server integration tests |
+| CLI commands and capability registry | `cli/src/` | `cli/src/__tests__/` |
+| Runtime adapters and prompt construction | `packages/agent-runtimes/`, `packages/agent-runtime-utils/` | package adapter tests plus server integration tests |
+| Board UI and clients | `ui/src/` | colocated UI tests and `tests/e2e/` |
+| Desktop shell and packaging | `desktop/`, `scripts/prod-desktop.mjs` | Desktop smoke scripts and packaged verification |
+| Bundled skills | `server/resources/bundled-skills/` | bundled-skill, runtime adapter, public route, and E2E tests |
+
+The owning module establishes what code does; tests establish protected and
+edge-case behavior. Cite both when the claim depends on a guarded branch,
+permission boundary, failure status, persistence rule, or adapter-specific
+path.
+
+## Official Remote Source And Version History
+
+- Repository: `https://github.com/Undertone0809/rudder`
+- Releases: `https://github.com/Undertone0809/rudder/releases`
+- Tags: `https://github.com/Undertone0809/rudder/tags`
+
+This is the only default remote source repository. For installed behavior,
+first identify the installed Rudder version and use a matching official tag or
+release when one exists. The default branch represents latest development and
+must not be presented as the behavior of an older installed build. Link the
+exact file, test, commit, tag, or release used.
+
+## Bundled Offline References
+
+Within this package:
+
+- `cli-reference.md` preserves the typed capability and CLI fallback catalog;
+- `api-reference.md` preserves internal/debug compatibility endpoints;
+- `control-plane-practices.md` preserves conditional operating semantics; and
+- `organization-skills.md` preserves organization skill workflows.
+
+Use only the relevant section. These references are version-adjacent fallback
+evidence, not a substitute for live installed help when the two disagree.
+
+## Targeted Search Patterns
+
+Prefer `rg -n` in the smallest owning directory. Useful query shapes include:
+
+- contract or registry ID: `rg -n "CONTRACT.ID|domain term" doc/product`
+- route or status: `rg -n "route-fragment|409|422" server/src packages/shared/src`
+- CLI command or capability: `rg -n "capability.id|command-name" cli/src server/src`
+- environment or configuration key: `rg -n "RUDDER_[A-Z_]+|configKey" server packages cli desktop`
+- schema field or table: `rg -n "fieldName|table_name" packages/db/src server/src`
+- UI label or test id: `rg -n "visible copy|data-testid" ui/src tests/e2e`
+- a bundled-skill fact: `rg -n "phrase|command" server/resources/bundled-skills`
+- related regression coverage: `rg -n "identifier|error text|behavior phrase" --glob '*test*' --glob '*.spec.ts'`
+
+Search exact identifiers first, then widen to a stable concept. Avoid broad
+repository scans when an owning domain, route, command, or component is already
+known.

package/skills/visualize/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: visualize
+description: "Create safe inline visual explanations in Rudder Chat. Use when asked for a chart, plot, diagram, timeline, comparison, static map, simulator, scenario view, or compact visual that materially improves understanding. Prefer Mermaid for static node-and-edge structures; use Rudder's HTML/SVG/CSS artifact path only when thread-scoped output is available. Rudder visuals are declarative and scriptless: convert simulator requests to static scenarios or disclosure-based comparisons and never rely on JavaScript, network access, or external assets."
+compatibility: "Rudder Chat inline visual capture. HTML artifacts require a thread-scoped visualization directory exposed by the current runtime."
+---
+
+# Visualize
+
+Create a visual only when it materially improves what the user can understand,
+compare, or decide. The Rudder inline runtime is scriptless and has no network
+access, so design for a useful first render with declarative HTML, SVG, and CSS.
+
+## Choose The Output
+
+1. Use a normal fenced Mermaid block when labeled nodes and edges fully explain
+   a static structure or flow. Do not create an HTML artifact for that case.
+2. Use an inline visual for charts, timelines, comparisons, spatial layouts,
+   static scenario views, or compact reports that benefit from custom geometry.
+3. Create an HTML artifact only when the current run exposes a writable,
+   thread-scoped visualization directory ending in
+   `visualizations/YYYY/MM/DD/<thread-id>`. Use the exact directory from the
+   runtime's writable roots. Never infer, scan for, or create another thread's
+   directory.
+4. If that directory is unavailable, fall back to Mermaid, Markdown tables, or
+   concise prose. Do not emit a directive that Rudder cannot resolve.
+
+## File And Directive
+
+- Choose a concise ASCII lowercase-hyphenated title and write
+  `<title>.html` inside the current thread-scoped visualization directory.
+- Write only an HTML fragment. Do not include a doctype or `html`, `head`, or
+  `body` elements.
+- Keep every fragment under 2 MiB and emit at most three visuals in one
+  assistant message.
+- Give the fragment one top-level markup root, `<div id="widget">`. Bounded
+  `<style>` blocks may precede that root.
+- Put any custom CSS in bounded `<style>` elements. Inline `style` attributes
+  are removed.
+- Read the file back before replying. Fix escaped markup such as literal `\"`
+  or `\n`, missing labels, clipped content, and malformed SVG.
+- Add this exact directive on its own line where the visual should render:
+
+```text
+::codex-inline-vis{file="<title>.html"}
+```
+
+Use only the `file` attribute. The value must be a basename ending in `.html`;
+paths, separators, traversal, extra attributes, and alternate quoting are
+rejected. Keep any necessary explanation outside the fragment and do not add a
+second Markdown link to the file.
+
+## Rudder Safety Boundary
+
+Rudder sanitizes the fragment before rendering, but generate valid input rather
+than relying on sanitization:
+
+- Do not write scripts, event handlers, JavaScript URLs, forms, links, images,
+  media, nested frames, embedded objects, canvas, or external resources.
+- Do not use `fetch`, XHR, WebSocket, module imports, CDN libraries, web fonts,
+  or URL-bearing CSS. The artifact has no network access.
+- Do not use active controls such as buttons, inputs, selects, or textareas.
+  They are removed because the scriptless runtime cannot preserve their state
+  or behavior safely.
+- Do not implement a parent bridge, follow-up prompt action, filesystem access,
+  or access to Rudder state, credentials, cookies, storage, or APIs.
+- Use `<details>` and `<summary>` for the only stateful native disclosure.
+  Use `data-tooltip` on `<summary>` for short supplementary hover/focus text.
+  A tooltip on any other preserved element is hover-only and must not contain
+  essential information.
+- Keep all data needed for the visual inside the fragment. Use inline SVG for
+  charts and supplied geometry; never fetch a basemap or invent geography.
+
+Read [references/runtime-contract.md](references/runtime-contract.md) before
+writing custom markup or CSS. Use
+[assets/example-chart.html](assets/example-chart.html) as a structure example,
+not as data or copy to repeat.
+
+## Composition
+
+- Start with the visual itself. Do not add decorative KPI rows, repeated
+  legends, permanent toolbars, or explanatory paragraphs inside the fragment.
+- Use one dominant chart, diagram, or comparison. Add up to three compact
+  summary cards only when their values are central to reading the visual.
+- For a requested simulator or adjustable explorer, show representative static
+  scenarios or a disclosure-based comparison and state the limitation in the
+  surrounding response. Do not pretend controls survived when they cannot.
+- For maps, use only user-supplied or locally available geometry that can be
+  embedded as safe SVG. Otherwise choose a table, ranked plot, or schematic.
+- Keep the outer surface transparent and unframed. Use `.card` only for a real
+  bounded summary or detail; never nest cards.
+
+## Layout And Accessibility
+
+- Design for the full Chat width around 736px and reflow cleanly down to 320px.
+- Avoid fixed outer widths, viewport-height layouts, horizontal scrolling,
+  fixed positioning, and clipped labels.
+- Use semantic headings sparingly. Do not restate the user prompt or render a
+  title inside the fragment when the surrounding Markdown already names it.
+- Give each meaningful SVG `role="img"` plus an accessible name or description.
+  Include `<title>` and `<desc>` when they improve screen-reader output.
+- Label important values directly. Add a legend only when multiple series
+  cannot be labeled on the marks.
+- Pair color with text, shape, or line style so meaning never depends on color
+  alone.
+
+## Theme And Utilities
+
+- Use Rudder theme variables for every color. Start with `--foreground`,
+  `--muted-foreground`, `--border`, and `--viz-series-1`; use
+  `--viz-series-2` through `--viz-series-6` only for stable categories.
+- Use host utilities such as `.viz-grid`, `.viz-row`, `.viz-stat`,
+  `.viz-stat-value`, `.viz-badge`, `.card`, `.text-small`, `.text-muted`,
+  `.text-destructive`, and `.sr-only` before adding custom CSS.
+- Keep custom selectors scoped below `#widget`. Use only theme variables already
+  provided by Rudder; custom CSS variables are removed.
+- Use normal text by default and weights 400 or 500. Reserve compact secondary
+  text for annotations, never essential labels.
+
+## Verification
+
+Before replying:
+
+1. Confirm the file is in the exact current-thread visualization directory,
+   uses an allowed basename, is below 2 MiB, and the message has no more than
+   three directives.
+2. Confirm the fragment contains no scripts, handlers, URLs, external assets,
+   active controls, document-level elements, or unsupported embeds.
+3. Confirm SVG view boxes, labels, referenced IDs, table semantics, and CSS
+   selectors are valid.
+4. Check both narrow and wide layout when a preview path is available. If not,
+   keep the geometry responsive and the composition conservative.
+5. Emit the directive only after the file is complete and readable.

package/skills/visualize/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Visualize"
+  short_description: "Create safe inline visuals in Rudder Chat"
+  default_prompt: "Use $visualize to create a clear Rudder-native chart, diagram, comparison, or other inline visual when it improves understanding."
+
+policy:
+  allow_implicit_invocation: true

package/skills/visualize/assets/example-chart.html

@@ -0,0 +1,89 @@
+<style>
+#widget .example-chart {
+  display: grid;
+  gap: 12px;
+}
+
+#widget .example-chart-bars {
+  display: grid;
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+  align-items: end;
+  gap: 10px;
+  min-height: 180px;
+  padding-block: 8px;
+  border-bottom: 1px solid var(--border);
+}
+
+#widget .example-chart-bar {
+  display: grid;
+  grid-template-rows: 1fr auto;
+  align-items: end;
+  gap: 6px;
+  min-width: 0;
+  color: var(--foreground);
+  text-align: center;
+}
+
+#widget .example-chart-bar-mark {
+  width: 100%;
+  min-height: 12px;
+  border-radius: var(--radius) var(--radius) 0 0;
+  background: var(--viz-series-1);
+}
+
+#widget .example-chart-bar:nth-child(1) .example-chart-bar-mark {
+  height: 52px;
+}
+
+#widget .example-chart-bar:nth-child(2) .example-chart-bar-mark {
+  height: 72px;
+}
+
+#widget .example-chart-bar:nth-child(3) .example-chart-bar-mark {
+  height: 98px;
+}
+
+#widget .example-chart-bar:nth-child(4) .example-chart-bar-mark {
+  height: 118px;
+}
+
+@media (max-width: 420px) {
+  #widget .example-chart-bars {
+    gap: 5px;
+  }
+}
+</style>
+<div id="widget">
+  <figure class="example-chart" aria-labelledby="example-chart-caption">
+    <figcaption id="example-chart-caption">
+      Completed loops by week
+    </figcaption>
+    <div class="example-chart-bars" role="img" aria-label="Completed loops rose from 8 to 18 over four weeks">
+      <div class="example-chart-bar">
+        <div class="example-chart-bar-mark"></div>
+        <span class="text-small">8</span>
+      </div>
+      <div class="example-chart-bar">
+        <div class="example-chart-bar-mark"></div>
+        <span class="text-small">11</span>
+      </div>
+      <div class="example-chart-bar">
+        <div class="example-chart-bar-mark"></div>
+        <span class="text-small">15</span>
+      </div>
+      <div class="example-chart-bar">
+        <div class="example-chart-bar-mark"></div>
+        <span class="text-small">18</span>
+      </div>
+    </div>
+  </figure>
+  <details class="card">
+    <summary data-tooltip="Show how the sample values are defined">Method</summary>
+    <p class="text-small text-muted">Illustrative weekly counts for validating the Rudder fragment contract.</p>
+  </details>
+  <svg role="img" aria-label="Upward trend marker" viewBox="0 0 120 24">
+    <title>Upward trend</title>
+    <desc>A line rises from left to right across four points.</desc>
+    <polyline points="4,20 40,16 78,9 116,4" fill="none" stroke="var(--viz-series-1)" stroke-width="2" vector-effect="non-scaling-stroke" />
+  </svg>
+</div>