@rudderhq/server 0.5.0 → 0.5.1

package/resources/bundled-skills/rudder-docs/evals/trigger-evals.json

@@ -16,19 +16,19 @@
     "should_trigger": true
   },
   {
-    "query": "Where in the official Rudder source are bundled skills materialized for local runtime adapters, and which tests protect stale managed-skill cleanup?",
+    "query": "请在 Rudder 里创建一个 Researcher Agent，让它向 CTO 汇报；先核对当前权限、runtime config、role enum 和 approval 流程，再执行创建。",
     "should_trigger": true
   },
   {
-    "query": "Rudder 显示这个 skill 已 enabled，但刚才的 run 没有使用它。这是 selected、loaded 和 used 语义不同，还是运行时出了 bug？请核对当前契约。",
+    "query": "Scaffold a new Rudder Plugin named @acme/quality-gate in a temporary external package directory. Verify the current create-rudder-plugin and SDK workflow first, then run its typecheck, tests, and build.",
     "should_trigger": true
   },
   {
-    "query": "我把交付文档写进 Rudder Library 后，为什么评论里必须使用返回的 markdownLink，不能手写 library-entry URL？请给出准确规则。",
+    "query": "Rudder Plugin 的 worker capability、same-origin UI、routePath 和 ctx.assets 现在到底有哪些边界？请查当前 authoring guide、SDK 和源码后回答。",
     "should_trigger": true
   },
   {
-    "query": "Which Rudder API endpoint is the compatibility fallback behind the CLI issue checkout command, and under what failure conditions is direct API fallback allowed?",
+    "query": "Before hiring a Founding Engineer in Rudder, compare the installed Codex runtime configuration with existing agents and explain the correct role, title, reportsTo, SOUL.md, desiredSkills, and sourceIssueId fields.",
     "should_trigger": true
   },
   {
@@ -44,7 +44,7 @@
     "should_trigger": false
   },
   {
-    "query": "这个 React 组件在当前 Rudder run 里渲染成空白了，帮我修复状态更新逻辑并补一个组件测试。",
+    "query": "这个 React 组件在当前 Rudder run 里渲染成空白了，帮我修复状态更新逻辑并补一个组件测试；这不是 Rudder 产品行为问题。",
     "should_trigger": false
   },
   {
@@ -56,27 +56,27 @@
     "should_trigger": false
   },
   {
-    "query": "把下面这段提到 rudder control 的英文产品文案总结成三条中文要点；这里的 rudder 是船舵控制，不是软件产品。",
+    "query": "The target Agent and new title are already in context. Use the exposed typed Agent update tool to change only its title to Staff Engineer; do not look up Rudder docs.",
     "should_trigger": false
   },
   {
-    "query": "在这个 Rudder run 里分析附件中的三家竞品定价表，算出年付折扣并推荐我们的套餐价格。",
+    "query": "给这个普通 Vite 应用写一个 markdown-it plugin，把内部链接加上 target 属性；它不是 Rudder Plugin，也不需要 Rudder SDK。",
     "should_trigger": false
   },
   {
-    "query": "Write a short email to the design team saying the issue is complete and that the new screenshots are ready for review.",
+    "query": "在这个 Rudder run 里分析附件中的三家竞品定价表，算出年付折扣并推荐我们的套餐价格。",
     "should_trigger": false
   },
   {
-    "query": "Please fix the spelling mistakes on the docs page in this repository, preserve its existing tone, and run the markdown linter afterward.",
+    "query": "Write a short email to the design team saying the issue is complete and that the new screenshots are ready for review.",
     "should_trigger": false
   },
   {
-    "query": "帮我设计一个名叫 Rudder 的船舵图标：深蓝色、圆形徽章、透明背景，输出 1024px PNG。",
+    "query": "Please fix spelling mistakes on an unrelated library's docs page in this repository, preserve its tone, and run the markdown linter; no Rudder behavior needs clarification.",
     "should_trigger": false
   },
   {
-    "query": "用当前已经暴露的 Library 文件读取工具打开季度计划，把第二节复制到这条聊天里；路径和权限都已在上下文中。",
+    "query": "帮我设计一个名叫 Rudder 的船舵图标：深蓝色、圆形徽章、透明背景，输出 1024px PNG。",
     "should_trigger": false
   }
 ]

package/resources/bundled-skills/rudder-docs/references/agent-creation.md

@@ -0,0 +1,153 @@
+# Agent Creation
+
+Use this workflow for an explicit request to create, hire, or configure a
+Rudder Agent. A question about Agent behavior or configuration is read-only.
+Only an explicit user request to perform the action authorizes mutation, and
+normal organization, permission, approval, and safety boundaries still apply.
+
+For exact installed command syntax, use [CLI reference](cli-reference.md) after
+checking live capabilities and `--help`. Use [API reference](api-reference.md)
+only for internal debugging or compatibility work.
+
+## Section Map
+
+- [Verify authority and context](#verify-authority-and-context)
+- [Discover a current runtime configuration](#discover-a-current-runtime-configuration)
+- [Design the durable Agent identity](#design-the-durable-agent-identity)
+- [Submit the governed hire](#submit-the-governed-hire)
+- [Handle direct creation or approval](#handle-direct-creation-or-approval)
+- [Report evidence](#report-evidence)
+
+## Verify Authority And Context
+
+Before designing or creating an Agent:
+
+1. Verify the actor, organization, and authentication with
+   `rudder agent me --json` or an equivalent exposed typed identity
+   capability.
+2. Board access may create an Agent. An Agent actor needs
+   `canCreateAgents=true` in the same organization.
+3. If identity or authorization is unavailable, stop and report the missing
+   authority. Do not ask for or print `RUDDER_API_KEY`, create files as a
+   substitute, or cross an organization boundary.
+4. If the request is advisory rather than an explicit request to create or
+   change an Agent, remain read-only and return the verified guidance.
+
+For a source issue, preserve its identity for the hire payload rather than
+creating an unlinked Agent and repairing the relationship later.
+
+## Discover A Current Runtime Configuration
+
+Inspect exposed typed capabilities first. If a governed typed Agent-hire
+capability is exposed by the current runtime, prefer it. The standard Rudder
+Rudder tool set currently has no Agent-hire mutation tool, so verify and
+use `rudder agent hire` as the canonical installed fallback.
+
+Discover before drafting:
+
+1. Read `rudder agent config index` to learn which runtime configuration
+   documents this instance exposes.
+2. Read one relevant `rudder agent config doc <agent-runtime-type>` document.
+3. Compare related Agents with `rudder agent list`,
+   `rudder agent config list`, and, where necessary,
+   `rudder agent config get`.
+4. Reuse a proven pattern only after checking that its working directory,
+   model, runtime options, and responsibilities fit the new role.
+5. If the role needs `desiredSkills` on day one, inspect the organization skill
+   inventory and import or validate required skills before hiring. Follow
+   [Organization skills](organization-skills.md) for that workflow.
+
+Installed help and live capability evidence win over this reference when a
+version differs. Do not hand-create Agent directories, configuration records,
+or instruction files as a fallback.
+
+## Design The Durable Agent Identity
+
+An Agent is a durable team member. Draft the smallest complete payload that
+defines its organizational responsibility and runnable configuration:
+
+- `name` is optional; when omitted, Rudder assigns a distinct personal name.
+- `role` is one fixed enum value: `ceo`, `cto`, `cmo`, `cfo`, `engineer`,
+  `designer`, `pm`, `qa`, `devops`, `researcher`, or `general`.
+- `title` carries the specific job title. For example, use role `engineer` and
+  title `Founding Engineer`, never a new `founding_engineer` role.
+- `reportsTo` identifies an in-organization manager and must preserve the
+  intended reporting line.
+- `capabilities` states the work this Agent owns and the boundaries it should
+  not silently cross.
+- `agentRuntimeType`, `agentRuntimeConfig`, and `runtimeConfig` must follow the
+  current adapter documentation and a valid local environment.
+- `desiredSkills` contains only skills already available to the organization
+  and actually needed for the role.
+- `sourceIssueId` or `sourceIssueIds` links the hire to the originating work.
+- Omit `icon` for a normal hire so Rudder generates and persists its default
+  Oreo avatar. Supply an icon only when the operator provided an explicit
+  supported `oreo:<shape>:<palette>:<uuid>`, DiceBear Notionists, or uploaded
+  `asset:<uuid>` reference.
+
+For supported local runtimes, `agentRuntimeConfig.promptTemplate` becomes the
+managed `SOUL.md`. Write durable role/persona guidance rather than a one-line
+command. A substantial role should define:
+
+- an opening identity statement;
+- mission and owned outcome;
+- durable responsibilities;
+- boundaries and escalation points;
+- decision principles;
+- communication voice; and
+- continuity rules for what should become memory or instruction updates.
+
+Do not copy Rudder's shared filesystem, memory, safety, or operating contract
+into `promptTemplate`; the runtime injects that shared contract separately.
+Keep secrets out of the payload unless the verified adapter contract requires a
+supported secret mechanism.
+
+## Submit The Governed Hire
+
+After the payload and authority are verified, use the exposed governed typed
+capability if one exists. Otherwise invoke the installed canonical command:
+
+`rudder agent hire --org-id <org-id> --payload <json> --json`
+
+Verify its exact syntax in [CLI reference](cli-reference.md) or installed
+`rudder agent hire --help` immediately before execution. Do not replace it with
+manual filesystem changes or `rudder approval create --type hire_agent`.
+The canonical hire surface owns both permission checks and the organization's
+direct-create versus approval-required policy.
+
+## Handle Direct Creation Or Approval
+
+The canonical response has two governed branches:
+
+- Direct creation: `approval: null`; the returned Agent is created in its
+  ordinary post-hire state.
+- Approval required: the returned Agent is `pending_approval`, and the response
+  includes an approval record.
+
+For `pending_approval`:
+
+1. Inspect it with `rudder approval get` and keep the source issue visible.
+2. Use a markdown approval comment when review context or revision evidence is
+   needed.
+3. If the board requests changes, revise the existing payload and use
+   `rudder approval resubmit`; do not create a duplicate hire.
+4. Use `rudder approval issues` to inspect linked issues after the server has
+   created the canonical linkage.
+5. After approval, close a linked issue only when the approved hire resolves
+   it; otherwise leave a linked next-action comment.
+
+Never treat a `pending_approval` Agent as runnable, assignable, or fully hired.
+Approval, rejection, and revision semantics remain server-owned.
+
+## Report Evidence
+
+Do not report success merely because a payload was drafted or files were
+written. Success requires the canonical hire operation to return:
+
+- `agent.id` for the created or pending Agent; and
+- `approval.id` when approval is required.
+
+Report the organization, Agent identity, role/title, reporting line, runtime,
+source issue, and direct versus approval branch without exposing secrets.
+If execution was not explicitly requested, report only the verified proposed
+configuration and the current command or capability that would govern it.

package/resources/bundled-skills/rudder-docs/references/api-reference.md

@@ -1,12 +1,12 @@
 # Rudder API Reference
 
-Internal/debug reference for the Rudder control plane API.
+Internal/debug reference for the Rudder API.
 
 - The `rudder-docs` router treats this as a compatibility and source-debugging
   reference, not the normal first interface for agent operations.
 - The stable agent command catalog lives in `cli-reference.md`.
 - Conditional ownership, review, workspace, and authentication guidance lives
-  in `control-plane-practices.md`.
+  in `operating-practices.md`.
 - Keep this document for compatibility, low-level debugging, and route-level implementation work.
 
 ## Section Map
@@ -146,6 +146,7 @@ Use the incremental `after` form when you already know the thread.
 - `GET /api/orgs/:orgId/issues`
 - `POST /api/orgs/:orgId/issues`
 - `GET /api/orgs/:orgId/agents`
+- `POST /api/orgs/:orgId/agent-hires`
 - `GET /api/orgs/:orgId/org`
 - `GET /api/orgs/:orgId/dashboard`
 - `GET /api/orgs/:orgId/projects`
@@ -160,6 +161,12 @@ Use the incremental `after` form when you already know the thread.
 - `GET /api/orgs/:orgId/costs/by-agent`
 - `GET /api/orgs/:orgId/costs/by-project`
 
+`POST /api/orgs/:orgId/agent-hires` is the governed Agent creation route behind
+`rudder agent hire`. It returns `approval: null` for direct creation or an Agent
+in `pending_approval` plus the approval record when organization policy requires
+review. Normal runtime work should follow [Agent creation](agent-creation.md)
+and the installed CLI instead of calling this route directly.
+
 ### Resources
 
 - `GET /api/orgs/:orgId/resources`

package/resources/bundled-skills/rudder-docs/references/cli-reference.md

@@ -19,14 +19,14 @@ returns a transport or configuration error.
 ## Operating Policy Owners
 
 Keep this file focused on commands and CLI-specific I/O. Consult the exact
-control-plane owner for operating behavior:
+operating-practices guide for operating behavior:
 
-- [Interface and Chat/issue scope](control-plane-practices.md#interface-and-scope)
-- [Ownership, checkout, and wake scope](control-plane-practices.md#ownership-checkout-and-wake-scope)
-- [Comments, mentions, and evidence](control-plane-practices.md#comments-mentions-and-evidence)
-- [Review and close-out](control-plane-practices.md#review-and-close-out)
-- [Durable Library artifacts](control-plane-practices.md#durable-library-artifacts)
-- [Git identity and attribution](control-plane-practices.md#git-identity-and-attribution)
+- [Interface and Chat/issue scope](operating-practices.md#interface-and-scope)
+- [Ownership, checkout, and wake scope](operating-practices.md#ownership-checkout-and-wake-scope)
+- [Comments, mentions, and evidence](operating-practices.md#comments-mentions-and-evidence)
+- [Review and close-out](operating-practices.md#review-and-close-out)
+- [Durable Library artifacts](operating-practices.md#durable-library-artifacts)
+- [Git identity and attribution](operating-practices.md#git-identity-and-attribution)
 
 ## Defaults
 
@@ -48,7 +48,7 @@ control-plane owner for operating behavior:
 | `rudder_agent_me` | `rudder agent me` | Show the authenticated agent identity, budget, and chain of command. | no | no | no | no |
 | `rudder_agent_inbox` | `rudder agent inbox` | List the compact assignee and reviewer work inbox for the authenticated agent. | no | no | no | no |
 | `rudder_agent_capabilities` | `rudder agent capabilities` | List the stable Rudder agent command contract. | no | no | no | no |
-| `rudder_agent_update` | `rudder agent update [agent-id] [--title <title>] [--description <text>]` | Update an agent's control-plane identity fields; defaults to the authenticated agent. | yes | no | no | attached when available |
+| `rudder_agent_update` | `rudder agent update [agent-id] [--title <title>] [--description <text>]` | Update an agent's identity fields; defaults to the authenticated agent. | yes | no | no | attached when available |
 | `rudder_agent_skills_create` | `rudder agent skills create [agent-id] --name <name> [--enable]` | Create an agent-private skill package under AGENT_HOME/skills. | yes | no | no | attached when available |
 | `rudder_agent_skills_enable` | `rudder agent skills enable <agent-id> <selection-ref...>` | Add skill selections to an agent without replacing existing enabled skills. | yes | no | no | attached when available |
 | `rudder_agent_skills_sync` | `rudder agent skills sync <agent-id>` | Sync the desired enabled skill set for an agent. | yes | no | no | attached when available |
@@ -110,7 +110,7 @@ control-plane owner for operating behavior:
 | `rudder_chat_messages` | `rudder chat messages <chat-id> [--limit <n>] [--cursor <cursor>] [--include-transcript]` | Read bounded chat messages with page cursors; transcript output is omitted unless requested. | no | no | no | no |
 | `rudder_chat_transcript` | `rudder chat transcript <chat-id> [--limit <n>] [--cursor <cursor>] [--max-output-chars <n>]` | Read paginated chat messages with assistant transcript entries clipped in human output. | no | no | no | no |
 | `rudder_chat_read` | `rudder chat read <chat-id> [--turn-limit <n>] [--cursor <cursor>] [--include-output]` | Read a bounded recent-message snapshot for one chat with page cursors. | no | no | no | no |
-| `rudder_chat_create` | `rudder chat create --org-id <id>` | Create a chat conversation. | yes | required | no | attached when available |
+| `rudder_chat_create` | `rudder chat create --org-id <id> --body <text>` | Create a chat conversation with its first message. | yes | required | no | attached when available |
 | `rudder_chat_send` | `rudder chat send <chat-id> --body <text>` | Send an agent-authored message directly to the operator in a chat. | yes | no | required | attached when available |
 | `rudder_chat_archive` | `rudder chat archive <chat-id>` | Archive a chat conversation without deleting it. | yes | no | no | attached when available |
 | `rudder_runs_list` | `rudder runs list --org-id <id> [--used-skill <skill>] [--loaded-skill <skill>] [--cursor <cursor>] [--full]` | List lightweight run summaries with stable pagination and filters; use --full only for legacy full-row compatibility. | no | required | no | no |
@@ -125,7 +125,7 @@ control-plane owner for operating behavior:
 
 ## Issue Command I/O And Shapes
 
-Operating rules live in [ownership, checkout, and wake scope](control-plane-practices.md#ownership-checkout-and-wake-scope), [comments and evidence](control-plane-practices.md#comments-mentions-and-evidence), and [review and close-out](control-plane-practices.md#review-and-close-out). The CLI close-out shapes are:
+Operating rules live in [ownership, checkout, and wake scope](operating-practices.md#ownership-checkout-and-wake-scope), [comments and evidence](operating-practices.md#comments-mentions-and-evidence), and [review and close-out](operating-practices.md#review-and-close-out). The CLI close-out shapes are:
 
 - progress: `rudder issue comment <issue> --body-file <path> [--image <path>]`
 - done: `rudder issue done <issue> --comment-file <path> [--image <path>]`
@@ -139,7 +139,7 @@ Issue comment responses include `shortRef` when available. `rudder issue comment
 
 ## Renderable Library CLI Output
 
-File placement and handoff policy lives in [Durable Library artifacts](control-plane-practices.md#durable-library-artifacts). Request a renderable reference with `rudder library file ref <library-relative-path> --json`.
+File placement and handoff policy lives in [Durable Library artifacts](operating-practices.md#durable-library-artifacts). Request a renderable reference with `rudder library file ref <library-relative-path> --json`.
 
 The relevant JSON fields are:
 
@@ -151,7 +151,7 @@ The `ref` argument is Library-relative, not an absolute filesystem path. CLI fal
 
 ## Reviewer Decision Command Shapes
 
-Reviewer policy lives in [Review and close-out](control-plane-practices.md#review-and-close-out). Supported decision command shapes are:
+Reviewer policy lives in [Review and close-out](operating-practices.md#review-and-close-out). Supported decision command shapes are:
 
 - `rudder issue review <issue> --decision approve --comment-file <path>`
 - `rudder issue review <issue> --decision request_changes --comment-file <path>`

package/{skills/rudder-docs/references/control-plane-practices.md → resources/bundled-skills/rudder-docs/references/operating-practices.md}

@@ -1,4 +1,4 @@
-# Rudder Control-Plane Practices
+# Rudder Work Practices
 
 Consult this reference only for questions about exact Rudder operating
 behavior. It is conditional documentation, not a trigger and not an always-run
@@ -22,7 +22,7 @@ workflow. For exact tool and CLI syntax, pair the relevant rule with
 
 ## Interface And Scope
 
-- Prefer exposed first-party Rudder typed tools for normal control-plane work.
+- Prefer exposed first-party Rudder typed tools for normal Rudder 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
@@ -118,8 +118,8 @@ report the status and required follow-up rather than bypassing it.
 - 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.
+- Use [Agent creation](agent-creation.md) for the canonical governed hiring
+  workflow rather than assembling a raw Rudder API payload.
 
 ## Git Identity And Attribution
 

package/resources/bundled-skills/rudder-docs/references/organization-skills.md

@@ -4,8 +4,8 @@ Use this reference when a board user or authorized agent asks you to discover, i
 
 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`.
+documented CLI as its compatibility fallback. General work ownership,
+authentication, and workspace rules remain in `operating-practices.md`.
 
 For a skill that belongs only to the running agent, do not use organization import or scan commands. Use:
 
@@ -180,4 +180,4 @@ the full optional enabled-skill set intentionally.
 - If a skill reference is missing or ambiguous, Rudder returns `422`.
 - Prefer linking back to the relevant issue, approval, and agent when commenting about skill changes.
 - This document only covers library import/inspect/enable/sync.
-- Hire and create flows now live on the CLI-first `rudder-create-agent` path.
+- Agent hire and create flows live in [Agent creation](agent-creation.md).

package/resources/bundled-skills/rudder-docs/references/plugin-authoring.md

@@ -0,0 +1,116 @@
+# Plugin Authoring
+
+Use this workflow for a Rudder Plugin source question or an explicit request to
+scaffold, develop, or verify a Plugin. Reading authoring guidance is read-only.
+Only an explicit user request to scaffold or modify a package authorizes writes,
+and those writes must stay inside the requested repository or target directory.
+
+The current fact sources are
+`doc/engineering/PLUGIN_AUTHORING_GUIDE.md` and
+`packages/plugins/sdk/README.md`. Use
+`doc/engineering/PLUGIN_RUNTIME_CONTRACT.md` only to understand the implemented
+runtime boundary, and label future ideas as non-current.
+
+## Section Map
+
+- [Confirm scope and package layout](#confirm-scope-and-package-layout)
+- [Scaffold from the current package](#scaffold-from-the-current-package)
+- [Implement within current boundaries](#implement-within-current-boundaries)
+- [Wire a bundled example only when requested](#wire-a-bundled-example-only-when-requested)
+- [Verify the package and host](#verify-the-package-and-host)
+
+## Confirm Scope And Package Layout
+
+Before writing, determine whether the Plugin is:
+
+- a repository-local example under `packages/plugins/examples/`;
+- another Rudder monorepo package under `packages/plugins/`; or
+- an external npm package in an absolute target directory.
+
+Repository-local examples are a development workflow. For deployable Plugins,
+prefer an npm package installed from a public or private npm-compatible
+registry. GitHub installs are not a first-class path today.
+
+Treat both Plugin workers and Plugin UI as trusted code. Plugin UI runs as
+same-origin JavaScript and is not sandboxed by manifest capabilities.
+Worker-side host APIs are capability-gated. Keep these boundaries visible when
+reviewing third-party code or selecting capabilities.
+
+## Scaffold From The Current Package
+
+Use `create-rudder-plugin` instead of hand-writing boilerplate. In a Rudder
+checkout, first build the scaffold package, then run its generated CLI for the
+requested npm package name and output root. `--output` names the parent
+directory; the CLI appends the package basename, and that destination must not
+already exist. Verify the exact commands in
+the current authoring guide before execution.
+
+For a repository-local package, the scaffold uses `workspace:*` for
+`@rudderhq/plugin-sdk`. For an external package, pass `--sdk-path` pointing to
+the checkout's `packages/plugins/sdk`; the scaffold snapshots the SDK/shared
+packages into `.rudder-sdk/` so the Plugin can build and test before an npm
+publication exists.
+
+The generated package should include:
+
+- `src/manifest.ts`;
+- `src/worker.ts`;
+- `src/ui/index.tsx` when UI is used;
+- `tests/plugin.spec.ts`;
+- `package.json` and current build configuration.
+
+Scaffold only under the explicit output root and confirm the derived package
+directory before execution. Do not install the generated Plugin into a running
+Rudder instance unless the user also requested that host mutation.
+
+## Implement Within Current Boundaries
+
+Review the manifest, worker, UI, and tests together:
+
+- Declare only capabilities used by the worker-side host APIs.
+- Keep tool names Plugin-namespaced; they must not shadow core or other Plugin
+  tools.
+- Keep UI self-contained. Rudder does not provide a shared Plugin React
+  component kit yet.
+- Do not use `ctx.assets`; it is not supported in the current runtime.
+- Use `routePath` only for a `page` slot. It must be one lowercase slug and may
+  not collide with a reserved host route or another installed Plugin page.
+- Use the SDK's declared worker, UI, testing, bundler, and dev-server surfaces
+  rather than undocumented application internals.
+- Treat jobs and webhooks as namespaced external execution surfaces and keep
+  their capabilities, ownership, logs, and failure evidence explicit.
+
+Local development installs must use an absolute filesystem path. The server
+can watch a local-path Plugin and restart its worker after rebuilds, but that
+does not make a repo-local checkout a production deployment artifact.
+
+## Wire A Bundled Example Only When Requested
+
+Only if the user explicitly asks for bundled example or discoverable host
+wiring, update the host's bundled-example list and the documentation that
+enumerates in-repo examples. A request to scaffold or develop a Plugin alone
+does not authorize changing `server/src/routes/plugins.ts` or other host
+registration surfaces.
+
+If host runtime, SDK, capability validation, static UI serving, or lifecycle
+code changes, follow the repository's Plugin engineering and Product Logic
+rules in addition to the package workflow.
+
+## Verify The Package And Host
+
+At minimum, run the generated or existing Plugin package's:
+
+- `typecheck`;
+- `test`; and
+- `build`.
+
+Use the package scripts or the monorepo's `pnpm --filter <plugin-package>`
+forms. For a new scaffold, execute them in a temporary or explicitly requested
+target and confirm that its worker, manifest, UI bundle, and
+`tests/plugin.spec.ts` compile against the selected SDK layout.
+
+When host or SDK code changed, also run the relevant host integration tests,
+repository typecheck, test suite, and build. If the user asked to install the
+Plugin, verify the real host from its absolute local path and surface worker
+health, logs, route behavior, and capability failures. Package creation alone
+is not evidence that a Plugin is installed or active in Rudder.

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

@@ -25,6 +25,30 @@ 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.
 
+Use these routes for governance and operational evidence questions:
+
+| User topic | English | 简体中文 |
+| --- | --- | --- |
+| Approvals, budgets, cost, and activity | `https://docs.rudderhq.dev/reference/approvals-budgets-activity` | `https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity` |
+| Run evidence and Run detail | `https://docs.rudderhq.dev/concepts/agents` | `https://docs.rudderhq.dev/zh/concepts/agents` |
+| Dashboard summary | `https://docs.rudderhq.dev/concepts/overview` | `https://docs.rudderhq.dev/zh/concepts/overview` |
+| Calendar source and history | `https://docs.rudderhq.dev/concepts/calendar` | `https://docs.rudderhq.dev/zh/concepts/calendar` |
+| Human attention, Inbox, and Messenger | `https://docs.rudderhq.dev/concepts/chat-messenger` | `https://docs.rudderhq.dev/zh/concepts/chat-messenger` |
+
+The approvals reference includes stable `#approvals`, `#budgets-and-cost`, and
+`#activity` anchors for narrow retrieval. Legacy public URLs are compatibility
+entries only. Cite the canonical routes in new answers.
+
+Other lookup pages are similarly narrow:
+
+| User topic | English | 简体中文 |
+| --- | --- | --- |
+| Issue states | `https://docs.rudderhq.dev/reference/issue-statuses` | `https://docs.rudderhq.dev/zh/reference/issue-statuses` |
+| Runtime choices and readiness | `https://docs.rudderhq.dev/reference/runtime-types` | `https://docs.rudderhq.dev/zh/reference/runtime-types` |
+| Workspace and file placement | `https://docs.rudderhq.dev/reference/workspace-boundaries` | `https://docs.rudderhq.dev/zh/reference/workspace-boundaries` |
+| Automation result destinations | `https://docs.rudderhq.dev/reference/automation-output-routing` | `https://docs.rudderhq.dev/zh/reference/automation-output-routing` |
+| Deployment trust, credentials, Browser, and platform behavior | `https://docs.rudderhq.dev/reference/permissions-and-platforms` | `https://docs.rudderhq.dev/zh/reference/permissions-and-platforms` |
+
 ## Product Logic Registry
 
 - Entry point: `doc/product/README.md`
@@ -50,7 +74,7 @@ Common domain routes include:
 - Chat, Messenger, comments, and integrations:
   `doc/product/domains/collaboration/`
 - approvals, budgets, costs, and activity:
-  `doc/product/domains/control-plane/`
+  `doc/product/domains/governance-and-visibility/`
 - reviews, feedback, and learning:
   `doc/product/domains/review-feedback-learning/`
 - automations: `doc/product/domains/automations/`
@@ -114,7 +138,7 @@ 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
+- `operating-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

package/resources/bundled-skills/visualize/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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."
+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 runtime-neutral HTML/SVG/CSS message envelope for custom geometry. 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 v1 inline visual message protocol. Provider-neutral and filesystem-independent; outside Rudder Chat, fall back to Mermaid, Markdown, or prose."
 ---
 
 # Visualize
@@ -16,38 +16,40 @@ access, so design for a useful first render with declarative HTML, SVG, and CSS.
    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.
+3. Use the v1 message envelope only in Rudder Chat. It is a Rudder protocol,
+   independent of Codex, Claude, Gemini, Cursor, OpenCode, Pi, Hermes, process,
+   HTTP, or gateway filesystem conventions.
+4. Outside Rudder Chat, fall back to Mermaid, Markdown tables, or concise prose.
+   Do not emit a Rudder envelope on a surface that cannot render it.
+
+## Message Envelope
+
 - 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.
+- Keep every fragment at or below 64 KiB UTF-8, all fragments together at or
+  below 128 KiB, and the complete visual-bearing final reply at or below
+  256 KiB. 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 `\"`
+- Check the fragment 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:
+- Put this exact opening marker on its own line where the visual should render,
+  then the fragment, then the exact closing marker on its own line:
 
 ```text
-::codex-inline-vis{file="<title>.html"}
+:::rudder-inline-visual:v1
+<style>#widget .series { color: var(--viz-series-1); }</style>
+<div id="widget">...</div>
+:::rudder-inline-visual:end
 ```
 
-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.
+The markers must have no indentation, attributes, or trailing text. Keep any
+necessary explanation outside the envelope. Never emit
+`::codex-inline-vis{...}`, `::rudder-inline-vis{...}`, a file path, an iframe,
+or a second link to source HTML; Rudder owns capture, trusted placement,
+persistence, sandboxing, and rendering.
 
 ## Rudder Safety Boundary
 
@@ -120,13 +122,13 @@ not as data or copy to repeat.
 
 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.
+1. Confirm each envelope uses the exact v1 markers, satisfies the 64/128/256 KiB
+   limits, and the message has no more than three visuals.
 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.
+5. Emit the envelope only after the fragment is complete and valid. Never leave
+   an opening marker unterminated.