@rudderhq/agent-runtime-cursor-local 0.4.6-canary.9 → 0.5.0

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>

package/skills/visualize/references/runtime-contract.md

@@ -0,0 +1,114 @@
+# Rudder Inline Visual Runtime Contract
+
+Read this reference when producing a Rudder inline visual. The runtime is
+scriptless, sanitized, isolated from Rudder state, and has no network access.
+Every fragment must be under 2 MiB, and one assistant message may reference at
+most three fragments.
+
+## Output Envelope
+
+Write a fragment with one top-level markup root, `<div id="widget">`. Bounded
+`<style>` elements may precede that root. Do not write a doctype or `html`,
+`head`, or `body`; Rudder extracts and sanitizes the CSS before it sanitizes the
+markup.
+
+The assistant message must place this exact directive on its own line:
+
+```text
+::codex-inline-vis{file="<title>.html"}
+```
+
+Only a current-run file from the exact thread-scoped visualization directory is
+eligible for capture. Rudder rejects absolute paths, separators, traversal,
+symlink escapes, missing files, stale files, oversized files, malformed
+directives, unknown attributes, and duplicate attributes.
+
+## Preserved Markup
+
+Use these common HTML elements:
+
+- Structure: `article`, `aside`, `div`, `section`, `main`, `header`, `footer`,
+  `figure`, `figcaption`, `blockquote`, `hr`, `br`.
+- Text: `h1` through `h6`, `p`, `span`, `small`, `strong`, `em`, `b`, `i`,
+  `mark`, `s`, `u`, `code`, `pre`.
+- Lists and data: `ul`, `ol`, `li`, `dl`, `dt`, `dd`, `table`, `caption`,
+  `colgroup`, `col`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`, `meter`,
+  `progress`.
+- Native disclosure: `<details>` and `<summary>`. This is the only supported
+  stateful interaction.
+
+Use inline `<svg>` for charts and diagrams. Supported primitives include
+`svg`, `g`, `defs`, `title`, `desc`, `path`, `line`, `rect`, `circle`, `ellipse`,
+`polygon`, `polyline`, `text`, `tspan`, `linearGradient`, `radialGradient`, and
+`stop`. Do not use clipping paths; the runtime does not preserve a safe
+`clip-path` reference.
+
+Common preserved attributes include:
+
+- Accessibility and structure: `role`, `aria-label`, `aria-labelledby`,
+  `aria-describedby`, `aria-hidden`, `id`, `class`, `scope`, `colspan`,
+  `rowspan`, `open`, `value`, `min`, and `max`.
+- Tooltip: `data-tooltip`, limited to concise plain text.
+- SVG geometry and paint: `viewBox`, `preserveAspectRatio`, `x`, `y`, `x1`,
+  `x2`, `y1`, `y2`, `cx`, `cy`, `r`, `rx`, `ry`, `width`, `height`, `d`,
+  `points`, `transform`, `fill`, `stroke`, opacity, line, gradient, text-anchor,
+  and vector-effect attributes.
+
+IDs and class tokens must start with a letter and contain only letters, digits,
+underscores, and hyphens. Keep each token at most 64 characters. A class list is
+limited to 24 safe tokens. Use `url(#safe-id)` only for an inline SVG paint
+reference such as a gradient; all external URL values are removed.
+
+## Removed Markup
+
+Do not generate `<script>`, `a`, `button`, `input`, `select`, `textarea`,
+`form`, `img`, `image`, `audio`, `video`, `canvas`, `iframe`, `object`, `embed`,
+`foreignObject`, `use`, SVG animation, document metadata, or external resource
+elements. The runtime removes those elements and every URL-bearing or event
+handler attribute.
+
+There is no JavaScript, Lucide runtime, CDN library, parent bridge,
+`window.openai`, API access, storage, cookies, or authenticated context. A
+visual that depends on any of them is not a Rudder inline visual.
+
+## CSS
+
+Use host classes first:
+
+- Layout: `.viz-grid` and `.viz-row`. `.viz-controls` is also available as a
+  wrapping layout class, but it does not make removed buttons, inputs, selects,
+  or other active controls usable.
+- Summaries: `.card`, `.viz-stat`, `.viz-stat-value`, `.viz-badge`.
+- Text: `.text-small`, `.text-muted`, `.text-destructive`, `.sr-only`.
+- Tooltip: add `data-tooltip="Concise detail"` to `<summary>` for hover and
+  keyboard-focus behavior. On another preserved element it is hover-only, so
+  keep essential information visible elsewhere.
+
+The host provides theme variables including `--background`, `--foreground`,
+`--card`, `--card-foreground`, `--popover`, `--popover-foreground`, `--primary`,
+`--primary-foreground`, `--secondary`, `--secondary-foreground`, `--muted`,
+`--muted-foreground`, `--accent`, `--accent-foreground`, `--destructive`,
+`--border`, `--input`, `--ring`, `--font-size-base`, `--radius`, and
+`--viz-series-1` through `--viz-series-6`.
+
+Custom `<style>` content is bounded to eight style blocks and 32 KiB total.
+Use ordinary rules and responsive `@media` rules only. The sanitizer removes
+custom properties, URL values, imports, fonts, namespaces, keyframes, property
+registrations, malformed CSS, unknown functions, and unsupported declarations.
+Inline `style` attributes are always removed.
+
+Safe custom CSS commonly uses grid or flex layout, spacing, borders, text,
+theme colors, dimensions, responsive media queries, and static transforms. Keep
+selectors scoped beneath `#widget` and keep the result useful without animation.
+
+## Responsive And Accessible Output
+
+- Support widths from 736px down to 320px without horizontal overflow.
+- Use responsive SVG view boxes and `max-width: 100%` behavior.
+- Reserve enough space for the longest labels and values.
+- Give charts and diagrams a screen-reader name and, when useful, description.
+- Use tables when exact values matter more than spatial comparison.
+- Pair every color encoding with text, shape, or another non-color cue.
+
+See `../assets/example-chart.html` for a minimal contract-valid fragment. Its
+data is illustrative; reuse the structure, not the values.

package/skills/rudder/SKILL.md

@@ -1,314 +0,0 @@
----
-name: rudder
-description: Use Rudder control-plane best practices and CLI-backed references for ownership, checkout, comments, reviews, Library handoff, and organization skills. Runtime-owned heartbeat prompts provide the fixed heartbeat execution flow.
----
-
-# Rudder Skill
-
-This is the control-plane practice skill for agents working under Rudder. Rudder
-work is not only "run a command"; it is a governed loop:
-
-```text
-Goal -> Plan -> Chat or Issue -> Agent run -> Review -> Feedback -> Learning -> Better future runs
-```
-
-Runtime-owned heartbeat prompts provide the fixed heartbeat execution flow only
-for heartbeat scene runs. Issue, review, chat, and automation runs still use
-this skill for Rudder control-plane details when needed. Use this skill when a
-heartbeat flow, issue/review/chat/automation context, or your own investigation
-needs Rudder control-plane details:
-ownership, checkout, approvals, comments, reviews, Library handoffs, and
-organization-skill operations.
-
-## Control-Plane Interface
-
-- Prefer first-party Rudder MCP tools for normal control-plane work when the runtime exposes them. Tool names use the stable `rudder_<capability_id>` shape, for example `rudder_issue_checkout`.
-- Use `rudder ... --json` as the compatibility fallback when MCP is unavailable or a Rudder MCP tool returns a transport/configuration error. CLI output renders IDs as short IDs by default; `rudder runs ...` commands accept short run IDs. Add `--full-ids` only for debugging or compatibility checks that need raw UUIDs.
-- Use `rudder agent capabilities --json` when you need machine-readable discovery of supported CLI commands and first-party MCP tools.
-- Use `references/cli-reference.md` for the stable MCP + CLI fallback catalog.
-- Treat `references/api-reference.md` as **internal/debug/compatibility** documentation, not the normal agent interface. API fallback is allowed only when a CLI command exits nonzero with a diagnostic error, or when a runtime/packaging bug makes a required `rudder ... --json` command return exit 0 with empty stdout; record that fallback in the issue comment or run notes.
-- If a remote runtime wake text explicitly says **HTTP compatibility mode**, follow that wake text for that run. Otherwise use Rudder MCP tools first, then CLI fallback.
-
-## Control-Plane Rails
-
-- Chat and issues are parallel execution surfaces. Continue chat-scoped work in
-  Chat unless the operator explicitly asks for issue structure or team policy
-  requires governed issue fields.
-- For issue-scoped task work, always checkout before starting execution.
-- Never retry a `409` from checkout.
-- Never look for unassigned work.
-- In issue comments, use `[Agent Name](agent://agent-id?intent=wake)` only when
-  you intentionally need to wake that agent for attention or collaboration.
-  Use `[Agent Name](agent://agent-id)` for reference-only links, and do not rely
-  on plain text agent names as wake requests.
-- Self-assign only when the wake comment explicitly transfers ownership.
-- If a comment wakes you on an issue not assigned to you, including user-owned
-  or unassigned issues, and the comment does not explicitly ask you to
-  implement, modify files, close the issue, or take ownership, respond to the
-  comment's actual content instead of broadening the wake into issue execution.
-- Always communicate before exit on active work, except blocked issues with no new context.
-- Treat `issue_passive_followup` as issue follow-up, not a fresh assignment.
-- Treat `issue_review_closeout_missing` as review follow-up.
-- A reviewer does not take over implementation unless explicitly asked.
-- Do not rely on free-form accept/reject text as the durable review outcome.
-- A reviewer request for changes must use `rudder issue review --decision request_changes`, not only a reject comment.
-- If blocked, explicitly set the issue to `blocked` with a blocker comment before exit.
-- Never cancel cross-team tasks. Reassign upward with explanation.
-- Use `chainOfCommand` for escalation.
-- Above 80% spend, focus on critical work only.
-- Use `rudder-create-agent` for hiring or new-agent creation workflows.
-- If you make a git commit you MUST add `Co-Authored-By: Rudder <285064165+Rudderhq@users.noreply.github.com>` to the end of each commit message.
-- Git commits must use an explicit safe identity. Rudder prepares isolated Codex homes and runtime worktrees with `user.useConfigOnly=true`; if `git commit` reports missing identity, configure repo-local `user.name` and `user.email` instead of bypassing the guard. Never accept `*@*.local` author or committer metadata.
-
-## Essential Commands
-
-Use `references/cli-reference.md` for the full stable command catalog. Keep
-these high-risk command shapes in mind because the wrong command can make work
-invisible or unsafe:
-
-```bash
-rudder agent me --json
-rudder approval get "$RUDDER_APPROVAL_ID" --json
-rudder approval issues "$RUDDER_APPROVAL_ID" --json
-rudder agent inbox --json
-rudder issue context "<issue-id-or-identifier>" --json
-rudder issue context "$RUDDER_TASK_ID" --wake-comment-id "$RUDDER_WAKE_COMMENT_ID" --json
-rudder issue context "<issue-id-or-identifier>" --wake-comment-id "cmt_<uuid-prefix>" --json
-rudder issue checkout "<issue-id-or-identifier>" --json
-rudder issue comment "<issue-id-or-identifier>" --body-file "<path>" [--image "<path>"] --json
-rudder issue comments get "<issue-id-or-identifier>" "cmt_<uuid-prefix>" --json
-rudder issue comments list "<issue-id-or-identifier>" --after "cmt_<uuid-prefix>" --json
-rudder issue done "<issue-id-or-identifier>" --comment-file "<path>" [--image "<path>"] --json
-rudder issue block "<issue-id-or-identifier>" --comment-file "<path>" [--image "<path>"] --json
-rudder issue review "<issue-id-or-identifier>" --decision approve --comment-file "<path>" --json
-rudder issue review "<issue-id-or-identifier>" --decision request_changes --comment-file "<path>" --json
-rudder issue review "<issue-id-or-identifier>" --decision needs_followup --comment-file "<path>" --json
-rudder issue review "<issue-id-or-identifier>" --decision blocked --comment-file "<path>" --json
-rudder issue create --org-id "$RUDDER_ORG_ID" ... --json
-rudder user activity --user me --since today --json
-```
-
-Agent and issue-comment responses include `shortRef` when available. You may pass
-`agt_<uuid-prefix>` to `rudder agent get` and `cmt_<uuid-prefix>` as
-`--wake-comment-id`, `rudder issue comments get <issue> <comment>`, or
-`rudder issue comments list <issue> --after <comment>`; use the full UUID if a
-short ref is ambiguous within the issue.
-
-Issue comment and close-out commands accept comment bodies only from files or
-stdin. For multiline Markdown, command names, code spans, code blocks,
-validation summaries, or screenshot evidence, write the body to a temporary
-Markdown file and pass `--body-file <path>` or `--comment-file <path>`. Pass
-`-` to read from stdin.
-
-Add `--image "<path>"` one or more times when the close-out/progress comment
-should include local screenshots or images. Do not leave only a local `/tmp/...`
-or workspace image path in the comment, because board users may not be able to
-inspect it from Rudder.
-
-## User Activity Context
-
-Use `rudder user activity --user me --since today --json` when you need a
-user-centered view of recent Rudder behavior before claiming context is missing,
-before answering questions like "what did I do today?", "which agents did I
-talk to?", or "what feedback did I give?", and before turning broad recent
-activity into daily notes, handoff context, or preference candidates.
-
-The ledger returns safe excerpts plus source/provenance pointers across
-user-authored chat messages, issue comments, approval comments, and user actor
-activity events. Treat summaries and excerpts as pointers, not ground truth
-when exact wording matters. Inspect the cited source before writing durable
-memory, taste/profile updates, or conclusions about stable user preference. Do
-not use the ledger to bypass organization or project permissions, and do not
-store private content in long-term memory unless it is an explicit durable
-preference or operating lesson.
-
-## Authentication
-
-Rudder injects the runtime context for you. Common env vars:
-
-- `RUDDER_AGENT_ID`
-- `RUDDER_ORG_ID`
-- `RUDDER_API_URL`
-- `RUDDER_API_KEY`
-- `RUDDER_RUN_ID`
-
-Optional wake-context vars may also appear:
-
-- `RUDDER_TASK_ID`
-- `RUDDER_WAKE_REASON`
-- `RUDDER_WAKE_COMMENT_ID`
-- `RUDDER_APPROVAL_ID`
-- `RUDDER_APPROVAL_STATUS`
-- `RUDDER_LINKED_ISSUE_IDS`
-
-Rules:
-
-- Never ask for `RUDDER_API_KEY` inside a normal heartbeat.
-- Never hard-code the API URL.
-- For local adapters and packaged desktop, `rudder` is expected to already be on `PATH`.
-- In manual local CLI mode outside heartbeats, use `rudder agent local-cli <agent-ref> --org-id <org-id>` to mint an agent key, optionally install bundled Rudder skills locally, and print the required `RUDDER_*` exports.
-
-## Shared Workspace
-
-Each organization has one system-managed shared workspace root at:
-
-- `~/.rudder/instances/<instance>/organizations/<org-storage-key>/workspaces`
-
-`<org-storage-key>` is the filesystem-safe storage key for the organization. For UUID-backed organizations it is the Rudder short ID form: the first 12 lowercase hex characters of the UUID with dashes removed. The API and database still use the full organization id.
-
-Important files and conventions:
-
-- Structured shared references live in the org `Resources` catalog. Agents do not receive the whole org catalog automatically.
-- If a run or chat is linked to a project, Rudder injects only that project's attached resources into the runtime context.
-- Project Context is the explicit operator-curated starting set, not a knowledge boundary. If those resources are insufficient, inspect broader Library files and other org workspace know-how before concluding context is missing.
-- Library-backed resources use `sourceType: "library"` and a safe `locator` inside `library:projects/<project-key>/`.
-- External resources use `sourceType: "external"` and keep their original URL, local path, repo path, or connector locator.
-- If you encounter older `library-file://...` or `library-doc://...` links, treat them as legacy Rudder Library references. Prefer project Library resources going forward.
-- If you need broader org-wide resources, query the org resource catalog or inspect Library files explicitly instead of assuming they are already in the prompt.
-- Use Workspaces for disk-backed shared files and skill packages.
-- In local trusted runs with project context, durable generated project work files belong under `$RUDDER_PROJECT_LIBRARY_ROOT`. Use `$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>` only when asking Rudder for a renderable reference. When there is no project context, write durable generated chat/work artifacts under the organization Library artifacts fallback `$RUDDER_ORG_WORKSPACE_ROOT/artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>` and cite the product locator `library:artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`. Do not choose an existing project, such as Getting Started, just to obtain a project Library path. Use `/tmp` only for transient scratch files and temporary verification files.
-- If a `resources.md` file exists, treat it like a normal workspace file rather than a reserved Rudder surface.
-- Agent-specific files live under `workspaces/agents/<workspace-key>/...`.
-- New projects do not create or configure their own workspace roots.
-- When the operator asks you to create or maintain project records, use the
-  stable CLI instead of ad hoc API calls:
-
-```bash
-rudder project list --org-id "$RUDDER_ORG_ID" --json
-rudder project create --org-id "$RUDDER_ORG_ID" --name "<name>" --json
-rudder project update "<project-id-or-shortname>" --org-id "$RUDDER_ORG_ID" --status in_progress --json
-```
-
-## Delegation
-
-```bash
-rudder issue create --org-id "$RUDDER_ORG_ID" ... [--label-id "<label-id>"] [--label "<label-name>"] --json
-```
-
-When you create an issue as an authenticated agent without an assignee, Rudder assigns it to you by default. Pass an explicit assignee only when the new issue should belong to someone else.
-
-When the organization has a mature issue label taxonomy, agent-created issues must choose at least one label. List the available labels first when you are not sure which one applies:
-
-```bash
-rudder issue labels list --org-id "$RUDDER_ORG_ID" --json
-```
-
-Always set `parentId`. Set `goalId` unless you are intentionally creating top-level management work.
-
-## Organization Skills Workflow
-
-When you need to create a skill for yourself, prefer an agent-private skill:
-
-```bash
-rudder agent skills create "$RUDDER_AGENT_ID" --name "<name>" --description "<description>" --enable --json
-```
-
-This creates the package under `AGENT_HOME/skills` and does not require organization skill mutation permission.
-
-When a board user or authorized agent asks you to find, import, inspect, or
-assign organization skills, read `references/organization-skills.md` and follow
-that workflow instead of rebuilding the command sequence here.
-
-Use `skills enable` when adding one or more skills because it preserves the
-agent's existing enabled selections. Use `skills sync` only when you intend to
-replace the full optional enabled-skill set.
-
-After creating or copying a skill under `AGENT_HOME/skills/<slug>/`, check the
-agent's Skills snapshot. If the skill is installed but not enabled, say:
-installed but not enabled; future runs will not load it until enabled.
-
-Do not fall back to raw `curl` for this workflow in local adapters or packaged desktop.
-
-## Durable Library Files
-
-If asked to make or revise durable project work files, use the Library as a local file workspace. In local trusted runs with project context, write files directly under `$RUDDER_PROJECT_LIBRARY_ROOT` with normal filesystem tools. `library:projects/<project-key>/...` is the Rudder product locator for those files, not the Markdown link syntax and not a reason to route ordinary local edits through the CLI.
-
-If there is no project context, write durable generated chat/work artifacts under the organization Library artifacts fallback instead: `$RUDDER_ORG_WORKSPACE_ROOT/artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`, with product locator `library:artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`. Use the current date and a concise slug of the current chat/thread title for `<conversation-title>`. Do not choose an existing project, such as Getting Started, just to obtain a project Library path.
-
-When you need to cite a Library file in a chat reply, issue comment, review, blocker, or done comment, use the `markdownLink` returned by `rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>" --json` with project context, or `rudder library file ref "artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>" --json` without project context. Do not hand-write `library-entry://...` URLs.
-
-Strong Library links look like normal Markdown. The stable Library entry id is
-the identity; Rudder may add a `p` query parameter as a synchronous path hint so
-the UI can navigate immediately before entry metadata finishes loading. Agents
-must not hand-write that query parameter; copy the `mentionHref` or
-`markdownLink` returned by Rudder:
-
-```md
-[Project work file](library-entry://<entry-id>)
-```
-
-Typical flow:
-
-```bash
-printf '%s\n' "<markdown body>" > "$RUDDER_PROJECT_LIBRARY_ROOT/<issue-identifier>.md"
-rudder library file ref "$RUDDER_PROJECT_LIBRARY_PATH/<issue-identifier>.md" --json
-rudder issue comment "<issue-id-or-identifier>" --body-file "<path>" --json
-```
-
-The `ref`, `put`, and `get` JSON responses include:
-
-- `libraryEntryId`: stable Library file identity
-- `mentionHref`: the raw `library-entry://<entry-id>` target, optionally with
-  Rudder-generated `?p=<url-encoded-path-hint>`
-- `markdownLink`: the Markdown link to paste into the comment body
-
-For close-out comments, copy `markdownLink` from the JSON response into your temporary Markdown comment file and post that link as the Rudder-visible handoff checkpoint. Direct filesystem writes are not complete handoff evidence until the file is cited with the returned `markdownLink`. The `ref` argument is a Library-relative path such as `$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>` or `artifacts/YYYY-MM-DD/<conversation-title>/<relative-file>`, not an absolute filesystem path. If `$RUDDER_PROJECT_LIBRARY_ROOT` is unset or inaccessible but `$RUDDER_PROJECT_LIBRARY_PATH` exists, use `rudder library file get/put "$RUDDER_PROJECT_LIBRARY_PATH/<relative-file>"` as the remote or restricted runtime fallback. If there is no project context, use the organization artifacts fallback path instead. Use older `library-file://...` links only when you are preserving or reading legacy content that has no `libraryEntryId`.
-
-Planning rules:
-
-- do not mark the issue done when the request was only to create or revise a plan
-- reassign back to the requester if that is the expected workflow
-- when you create or update a durable Library file, always include a user-visible Markdown link to that file in your final chat reply or issue comment
-- when you reference the plan in comments, use the `markdownLink` returned by `rudder library file ref ... --json`
-- `rudder issue documents ...` has been retired. Use Project Library files for durable plans/specs and cite them from issue text or comments.
-
-## Comment Style (Required)
-
-Use concise markdown with:
-
-- a short status line
-- bullets for what changed or what is blocked
-- links to related issues, approvals, projects, agents, or documents when available
-
-**Clickable URLs are Markdown links.** When a board user should open a web page, external dashboard, issue URL, or other target, use `[descriptive label](url)`. Do not leave action URLs as bare text, and do not wrap them in code spans unless you are showing literal code or a command:
-
-- Good: `[NameSilo transfer page](https://www.namesilo.com/account_domain_manage_transfer.php)`
-- Bad: `https://www.namesilo.com/account_domain_manage_transfer.php`
-
-**Ticket references are links.** Never leave bare ticket ids like `PAP-224` in comments or descriptions when you can link them:
-
-- `[PAP-224](/PAP/issues/PAP-224)`
-- `[ZED-24](/ZED/issues/ZED-24)`
-
-**Company-prefixed URLs are required.** Derive the prefix from the issue identifier and use it in all internal links:
-
-- issues: `/<prefix>/issues/<issue-identifier>`
-- issue comments: `/<prefix>/issues/<issue-identifier>#comment-<comment-id>`
-- Library files: `/<prefix>/library?path=<url-encoded-relative-path>`
-- agents: `/<prefix>/agents/<agent-url-key>`
-- projects: `/<prefix>/projects/<project-url-key>`
-- approvals: `/<prefix>/messenger/approvals/<approval-id>`
-- runs: `/<prefix>/agents/<agent-url-key-or-id>/runs/<run-id>`
-
-Example:
-
-```md
-## Update
-
-Plan updated and ready for review.
-
-- Plan: [PAP-142 plan](/PAP/library?path=projects%2Fproject-name%2FPAP-142.md)
-- Depends on: [PAP-224](/PAP/issues/PAP-224)
-- Approval: [ca6ba09d](/PAP/messenger/approvals/ca6ba09d-b558-4a53-a552-e7ef87e54a1b)
-```
-
-## Discovery
-
-When you are unsure which Rudder commands are supported in this runtime, use:
-
-```bash
-rudder agent capabilities --json
-```
-
-For the human-readable command catalog, read `references/cli-reference.md`.
-For API debugging and compatibility investigations only, read `references/api-reference.md`.