@rudderhq/agent-runtime-opencode-local 0.5.0 → 0.5.1

package/skills/rudder-docs/evals/retrieval-authority-evals.json

@@ -0,0 +1,262 @@
+[
+  {
+    "query": "Where can I check whether a governed Rudder action was approved and applied?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["APPROVAL.GOVERNED.ACTIONS.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/approvals-budgets-activity",
+    "expected_anchor": "approvals",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Which Rudder page explains monthly budget hard stops and cost events?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["BUDGET.ENFORCEMENT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/approvals-budgets-activity",
+    "expected_anchor": "budgets-and-cost",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "I need the audit trail for a product mutation in Rudder.",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ACTIVITY.AUDIT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/approvals-budgets-activity",
+    "expected_anchor": "activity",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Where does Rudder explain Run summaries, transcripts, logs, and raw evidence?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["RUN.INTELLIGENCE.001", "RUN.RESULT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/concepts/agents",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "What owns the current Dashboard health summary?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["DASHBOARD.SUMMARY.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/concepts/overview",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "How do Calendar events link back to their source work?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["CALENDAR.SOURCE.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/concepts/calendar",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Where should a human recover unread work and requests for attention?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["INBOX.ATTENTION.001", "MESSENGER.ATTENTION.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/concepts/chat-messenger",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Where did Rudder's old Control Plane documentation move?",
+    "locale": "en",
+    "query_mode": "legacy_compatibility",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["APPROVAL.GOVERNED.ACTIONS.001", "BUDGET.ENFORCEMENT.001", "ACTIVITY.AUDIT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/approvals-budgets-activity",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "在哪里查看受治理动作的审批结论和实际应用结果？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["APPROVAL.GOVERNED.ACTIONS.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity",
+    "expected_anchor": "approvals",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Rudder 的月度预算硬限制和成本事件以哪个页面为准？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["BUDGET.ENFORCEMENT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity",
+    "expected_anchor": "budgets-and-cost",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "我需要查一项产品变更的活动审计记录。",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ACTIVITY.AUDIT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity",
+    "expected_anchor": "activity",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "运行摘要、完整记录、日志和原始证据应该看哪一页？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["RUN.INTELLIGENCE.001", "RUN.RESULT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/concepts/agents",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Dashboard 当前状态汇总的权威说明在哪里？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["DASHBOARD.SUMMARY.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/concepts/overview",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Calendar 事件怎样回到来源任务？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["CALENDAR.SOURCE.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/concepts/calendar",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "负责人应该在哪里找回未读工作和需要人处理的事项？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["INBOX.ATTENTION.001", "MESSENGER.ATTENTION.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/concepts/chat-messenger",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Rudder 以前的 Control Plane 文档迁移到哪里了？",
+    "locale": "zh",
+    "query_mode": "legacy_compatibility",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["APPROVAL.GOVERNED.ACTIONS.001", "BUDGET.ENFORCEMENT.001", "ACTIVITY.AUDIT.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/approvals-budgets-activity",
+    "expected_anchor": null,
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "What are all valid Issue statuses, including cancelled and review states?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ISSUE.STATE.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/issue-statuses",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Where can I compare local Agent runtime choices and readiness labels?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AGENT.RUNTIME.ADAPTERS.001", "AGENT.RUNTIME.PERMISSIONS.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/runtime-types",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Which paths belong to Library, Project Context, run workspaces, and backups?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["CONTEXT.RESOURCES.001", "LIBRARY.FILES.001", "WORKSPACE.PROJECT.001", "WORKSPACE.RUN.001", "WORKSPACE.BACKUP.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/workspace-boundaries",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "How do chat_output and track_issue route Automation results?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AUTOMATION.OUTPUT.001", "AUTOMATION.RUN.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/automation-output-routing",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "What are Rudder's platform, credential, browser, and local trust boundaries?",
+    "locale": "en",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AGENT.RUNTIME.PERMISSIONS.001", "AGENT.BROWSER.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/reference/permissions-and-platforms",
+    "expected_anchor": "boundaries",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "哪里可以查到包括 cancelled 和评审状态在内的全部 Issue 状态？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["ISSUE.STATE.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/issue-statuses",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "在哪里比较本地 Agent 运行环境选项和就绪提示？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AGENT.RUNTIME.ADAPTERS.001", "AGENT.RUNTIME.PERMISSIONS.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/runtime-types",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Library、Project Context、运行工作区和备份各自放什么？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["CONTEXT.RESOURCES.001", "LIBRARY.FILES.001", "WORKSPACE.PROJECT.001", "WORKSPACE.RUN.001", "WORKSPACE.BACKUP.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/workspace-boundaries",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "chat_output 和 track_issue 会把自动化结果分别送到哪里？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AUTOMATION.OUTPUT.001", "AUTOMATION.RUN.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/automation-output-routing",
+    "expected_anchor": "states",
+    "illustrative_case_sufficient": false
+  },
+  {
+    "query": "Rudder 的平台、凭据、浏览器和本地信任边界在哪里查？",
+    "locale": "zh",
+    "query_mode": "current",
+    "expected_source_class": "official_public_docs_primary",
+    "required_contract_ids": ["AGENT.RUNTIME.PERMISSIONS.001", "AGENT.BROWSER.001"],
+    "expected_public_path": "https://docs.rudderhq.dev/zh/reference/permissions-and-platforms",
+    "expected_anchor": "boundaries",
+    "illustrative_case_sufficient": false
+  }
+]

package/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/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/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/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 → 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/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).