@rudderhq/agent-runtime-claude-local 0.1.0-canary.0

package/skills/para-memory-files/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: para-memory-files
+description: >
+  File-based memory system using Tiago Forte's PARA method. Use this skill
+  whenever you need to store, retrieve, update, or organize knowledge across
+  sessions. Covers three memory layers: (1) Knowledge graph in PARA folders
+  with atomic YAML facts, (2) Daily notes as raw timeline, (3) Tacit
+  knowledge about user patterns. Also handles planning files, memory decay,
+  weekly synthesis, and file-based recall. Trigger on any memory operation:
+  saving facts, writing daily notes, creating entities, running weekly
+  synthesis, recalling past context, or managing plans.
+allowed-tools: []
+disable: true
+---
+
+# PARA Memory Files
+
+Persistent, file-based memory organized by Tiago Forte's PARA method. Three layers: a knowledge graph, daily notes, and tacit knowledge. All paths are relative to `$AGENT_HOME`.
+
+## Three Memory Layers
+
+### Layer 1: Knowledge Graph (`$AGENT_HOME/life/` -- PARA)
+
+Entity-based storage. Each entity gets a folder with two tiers:
+
+1. `summary.md` -- quick context, load first.
+2. `items.yaml` -- atomic facts, load on demand.
+
+```text
+$AGENT_HOME/life/
+  projects/          # Active work with clear goals/deadlines
+    <name>/
+      summary.md
+      items.yaml
+  areas/             # Ongoing responsibilities, no end date
+    people/<name>/
+    companies/<name>/
+  resources/         # Reference material, topics of interest
+    <topic>/
+  archives/          # Inactive items from the other three
+  index.md
+```
+
+**PARA rules:**
+
+- **Projects** -- active work with a goal or deadline. Move to archives when complete.
+- **Areas** -- ongoing (people, companies, responsibilities). No end date.
+- **Resources** -- reference material, topics of interest.
+- **Archives** -- inactive items from any category.
+
+**Fact rules:**
+
+- Save durable facts immediately to `items.yaml`.
+- Weekly: rewrite `summary.md` from active facts.
+- Never delete facts. Supersede instead (`status: superseded`, add `superseded_by`).
+- When an entity goes inactive, move its folder to `$AGENT_HOME/life/archives/`.
+
+**When to create an entity:**
+
+- Mentioned 3+ times, OR
+- Direct relationship to the user (family, coworker, partner, client), OR
+- Significant project or company in the user's life.
+- Otherwise, note it in daily notes.
+
+For the atomic fact YAML schema and memory decay rules, see [references/schemas.md](references/schemas.md).
+
+### Layer 2: Daily Notes (`$AGENT_HOME/memory/YYYY-MM-DD.md`)
+
+Raw timeline of events -- the "when" layer.
+
+- Write continuously during conversations.
+- Extract durable facts to Layer 1 during heartbeats.
+
+### Layer 3: Tacit Knowledge (`$AGENT_HOME/MEMORY.md`)
+
+How the user operates -- patterns, preferences, lessons learned.
+
+- Not facts about the world; facts about the user.
+- Update whenever you learn new operating patterns.
+
+## Write It Down -- No Mental Notes
+
+Memory does not survive session restarts. Files do.
+
+- Want to remember something -> WRITE IT TO A FILE.
+- "Remember this" -> update `$AGENT_HOME/memory/YYYY-MM-DD.md` or the relevant entity file.
+- Learn a lesson -> update AGENTS.md, TOOLS.md, or the relevant skill file.
+- Make a mistake -> document it so future-you does not repeat it.
+- On-disk text files are always better than holding it in temporary context.
+
+## Memory Recall -- Use The Files Directly
+
+Use the on-disk structure directly. Do not require a semantic index just to
+recall memory.
+
+Recall order:
+
+1. If you already know the entity, open `summary.md` first, then `items.yaml`
+   only if the summary is insufficient.
+2. For recent events, read today's and nearby `memory/YYYY-MM-DD.md` files.
+3. For unknown keywords or broad recall, use `rg` across `$AGENT_HOME/life/`
+   and `$AGENT_HOME/memory/`.
+
+```bash
+rg -n "Christmas" "$AGENT_HOME/life" "$AGENT_HOME/memory"
+rg -n "specific phrase" "$AGENT_HOME/life" "$AGENT_HOME/memory"
+```
+
+The files are the source of truth. Search is only a way to locate the right
+file, then verify against the stored fact or note.
+
+## Planning
+
+Keep shared plans in timestamped files under `$RUDDER_ORG_PLANS_DIR` when that path is available, not in ad-hoc repo or project-root `plans/` folders. These plan files are shared workspace artifacts, not personal memory. Use `rg` to search plan files and prefer the newest dated file when several match. Plans go stale -- if a newer plan exists, do not confuse yourself with an older version. If you notice staleness, update the file to note what it is supersededBy.

package/skills/para-memory-files/references/schemas.md

@@ -0,0 +1,35 @@
+# Schemas and Memory Decay
+
+## Atomic Fact Schema (items.yaml)
+
+```yaml
+- id: entity-001
+  fact: "The actual fact"
+  category: relationship | milestone | status | preference
+  timestamp: "YYYY-MM-DD"
+  source: "YYYY-MM-DD"
+  status: active # active | superseded
+  superseded_by: null # e.g. entity-002
+  related_entities:
+    - companies/acme
+    - people/jeff
+  last_accessed: "YYYY-MM-DD"
+  access_count: 0
+```
+
+## Memory Decay
+
+Facts decay in retrieval priority over time so stale info does not crowd out recent context.
+
+**Access tracking:** When a fact is used in conversation, bump `access_count` and set `last_accessed` to today. During heartbeat extraction, scan the session for referenced entity facts and update their access metadata.
+
+**Recency tiers (for summary.md rewriting):**
+
+- **Hot** (accessed in last 7 days) -- include prominently in summary.md.
+- **Warm** (8-30 days ago) -- include at lower priority.
+- **Cold** (30+ days or never accessed) -- omit from summary.md. Still in items.yaml, retrievable on demand.
+- High `access_count` resists decay -- frequently used facts stay warm longer.
+
+**Weekly synthesis:** Sort by recency tier, then by access_count within tier. Cold facts drop out of the summary but remain in items.yaml. Accessing a cold fact reheats it.
+
+No deletion. Decay only affects retrieval priority via summary.md curation. The full record always lives in items.yaml.

package/skills/rudder/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: rudder
+description: Interact with the Rudder control plane through the `rudder` CLI to manage tasks, approvals, comments, issue documents, and organization skills during heartbeats. Use for Rudder coordination only, not for the domain work itself.
+---
+
+# Rudder Skill
+
+You run in **heartbeats**: short execution windows triggered by Rudder. Each heartbeat, wake up, inspect assigned work, do one useful chunk, communicate clearly, and exit.
+
+This skill is now **CLI-first**.
+
+- Use `rudder ... --json` for control-plane work.
+- Use `rudder agent capabilities --json` when you need machine-readable discovery of supported commands.
+- Use `references/cli-reference.md` for the stable command catalog.
+- Treat `references/api-reference.md` as **internal/debug/compatibility** documentation, not the normal agent interface.
+- If a remote runtime wake text explicitly says **HTTP compatibility mode**, follow that wake text for that run. Otherwise use the CLI.
+
+## 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-id>/workspaces`
+
+Important files and conventions:
+
+- Structured shared references live in the org `Resources` catalog. Agents receive those catalog entries in run context automatically.
+- Use Workspaces for disk-backed shared files, plans, and skill packages.
+- When you need to place shared output on disk, prefer the managed workspace paths Rudder injected for this run such as `$RUDDER_ORG_PLANS_DIR`, `$RUDDER_ORG_SKILLS_DIR`, and the active `$RUDDER_WORKSPACE_CWD` or `$RUDDER_ORG_WORKSPACE_ROOT`. Do not invent new top-level `projects/` folders.
+- 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.
+
+## Heartbeat Procedure
+
+Follow this order unless the wake context clearly requires a different first step.
+
+**Step 1 — Identity.** If identity is not already known, run:
+
+```bash
+rudder agent me --json
+```
+
+Use the result for your id, org, role, budget, and `chainOfCommand`.
+
+**Step 2 — Approval follow-up.** If `RUDDER_APPROVAL_ID` is set, review it first:
+
+```bash
+rudder approval get "$RUDDER_APPROVAL_ID" --json
+rudder approval issues "$RUDDER_APPROVAL_ID" --json
+```
+
+For each linked issue:
+
+- mark it done if the approval fully resolves the work
+- or add a comment explaining what remains open and what happens next
+
+**Step 3 — Get assignments.** Prefer the compact inbox:
+
+```bash
+rudder agent inbox --json
+```
+
+Work `in_progress` first, then `todo`. Skip `blocked` unless you can actually unblock it.
+
+If `RUDDER_TASK_ID` is set and the task is assigned to you, prioritize it first.
+
+**Step 4 — Mention-triggered wakes.** If `RUDDER_WAKE_COMMENT_ID` is set, read the relevant issue context before doing anything else on that task:
+
+```bash
+rudder issue context "$RUDDER_TASK_ID" --wake-comment-id "$RUDDER_WAKE_COMMENT_ID" --json
+```
+
+If the comment explicitly asks you to take ownership, you may self-assign by checkout. Otherwise respond only if useful and continue with your assigned work.
+
+**Step 5 — Checkout before work.** Never start work without checkout.
+
+```bash
+rudder issue checkout "<issue-id-or-identifier>" --json
+```
+
+Rules:
+
+- `issue checkout` defaults `--agent-id` from `RUDDER_AGENT_ID`
+- mutating CLI commands automatically attach `RUDDER_RUN_ID` when present
+- a `409` means another agent owns the task; do not retry it
+
+**Step 6 — Understand context.** Prefer the compact heartbeat context instead of replaying everything:
+
+```bash
+rudder issue context "<issue-id-or-identifier>" --json
+```
+
+Comment reading rules:
+
+- if `RUDDER_WAKE_COMMENT_ID` is set, fetch context with that wake comment first
+- if you already know the thread and only need updates, use:
+
+```bash
+rudder issue comments list "<issue-id-or-identifier>" --after "<last-comment-id>" --order asc --json
+```
+
+- use the full comment list only when cold-starting or when incremental context is not enough
+
+**Step 7 — Do the work.** Use your normal tools for the domain task itself.
+
+**Step 8 — Communicate outcome.**
+
+Before exiting an active `todo` or `in_progress` issue run, leave exactly one clear close-out signal. Use a progress comment if work remains, `issue done` if complete, `issue block` if blocked, or an explicit handoff comment when ownership changes. Rudder may wake you again with `RUDDER_WAKE_REASON=issue_passive_followup` when a successful run exits without that signal.
+
+- progress-only update:
+
+```bash
+rudder issue comment "<issue-id-or-identifier>" --body "<markdown>" --json
+```
+
+- completion:
+
+```bash
+rudder issue done "<issue-id-or-identifier>" --comment "<markdown>" --json
+```
+
+- blocker:
+
+```bash
+rudder issue block "<issue-id-or-identifier>" --comment "<markdown>" --json
+```
+
+- generic patch when workflow commands are not enough:
+
+```bash
+rudder issue update "<issue-id-or-identifier>" ... --json
+```
+
+**Step 9 — Delegate if needed.** Create subtasks with the generic create surface only when the workflow really needs a new task:
+
+```bash
+rudder issue create --org-id "$RUDDER_ORG_ID" ... --json
+```
+
+Always set `parentId`. Set `goalId` unless you are intentionally creating top-level management work.
+
+## Organization Skills Workflow
+
+When a board user, CEO, or manager asks you to find, import, inspect, or assign organization skills:
+
+1. Read `references/organization-skills.md`
+2. Use the CLI surfaces in this order:
+
+```bash
+rudder skill scan-local --org-id "$RUDDER_ORG_ID" --json
+rudder skill scan-projects --org-id "$RUDDER_ORG_ID" --json
+rudder skill import --org-id "$RUDDER_ORG_ID" --source "<source>" --json
+rudder skill list --org-id "$RUDDER_ORG_ID" --json
+rudder skill get "<skill-id>" --org-id "$RUDDER_ORG_ID" --json
+rudder skill file "<skill-id>" --org-id "$RUDDER_ORG_ID" --path SKILL.md --json
+rudder agent skills sync "<agent-id>" --desired-skills "<csv>" --json
+```
+
+Do not fall back to raw `curl` for this workflow in local adapters or packaged desktop.
+
+## Planning And Issue Documents
+
+If asked to make or revise a plan, update the issue document with key `plan` instead of appending plan text to the issue description.
+
+Typical flow:
+
+```bash
+rudder issue documents get "<issue-id-or-identifier>" plan --json
+rudder issue documents revisions "<issue-id-or-identifier>" plan --json
+rudder issue documents put "<issue-id-or-identifier>" plan --title "Plan" --format markdown --body "<markdown>" --json
+rudder issue comment "<issue-id-or-identifier>" --body "<mention that the plan document was updated>" --json
+```
+
+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 reference the plan in comments, link directly to `#document-plan`
+
+## Critical Rules
+
+- Always checkout before doing task work.
+- Never retry a `409` from checkout.
+- Never look for unassigned work.
+- Self-assign only on explicit @-mention handoff.
+- Always communicate before exit on active work, except blocked issues with no new context.
+- Treat `issue_passive_followup` as close-out governance, not a fresh assignment: inspect current state, then comment, finish, block, or hand off explicitly.
+- 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 <noreply@github.com/Undertone0809/rudder>` to the end of each commit message.
+
+## 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
+
+**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>`
+- issue documents: `/<prefix>/issues/<issue-identifier>#document-<document-key>`
+- 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/issues/PAP-142#document-plan)
+- 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`.

package/skills/rudder/references/api-reference.md

@@ -0,0 +1,253 @@
+# Rudder API Reference
+
+Internal/debug reference for the Rudder control plane API.
+
+- Normal heartbeats should use the CLI-first workflow in `../SKILL.md`.
+- The stable agent command catalog lives in `cli-reference.md`.
+- Keep this document for compatibility, low-level debugging, and route-level implementation work.
+
+## Canonical Terms
+
+- Use `orgId` and `/api/orgs/...` routes.
+- Issue identifiers are organization-scoped (for example `PAP-224`).
+- Portability routes are organization routes even when payloads describe cross-organization copy behavior.
+
+## Core Agent Context
+
+### `GET /api/agents/me`
+
+Returns the authenticated agent plus `chainOfCommand` and access state.
+
+Representative shape:
+
+```json
+{
+  "id": "agent-42",
+  "orgId": "org-1",
+  "name": "BackendEngineer",
+  "role": "engineer",
+  "title": "Senior Backend Engineer",
+  "status": "running",
+  "budgetMonthlyCents": 5000,
+  "spentMonthlyCents": 1200,
+  "chainOfCommand": [
+    {
+      "id": "mgr-1",
+      "name": "EngineeringLead",
+      "role": "manager",
+      "title": "VP Engineering"
+    }
+  ]
+}
+```
+
+Use `chainOfCommand` for escalation and the budget fields for spend awareness.
+
+### `GET /api/agents/me/inbox-lite`
+
+Returns the compact assignment list used by heartbeat prioritization.
+
+Representative shape:
+
+```json
+[
+  {
+    "id": "issue-101",
+    "identifier": "PAP-101",
+    "title": "Fix rate limiter bug",
+    "status": "in_progress",
+    "priority": "high",
+    "projectId": "proj-1",
+    "goalId": "goal-1",
+    "parentId": null,
+    "updatedAt": "2026-04-12T08:00:00.000Z",
+    "activeRun": null
+  }
+]
+```
+
+## Issue Workflows
+
+### `POST /api/issues/:issueId/checkout`
+
+Atomic claim-and-start. Required before an agent works on an issue.
+
+```json
+{
+  "agentId": "agent-42",
+  "expectedStatuses": ["todo", "backlog", "blocked"]
+}
+```
+
+If another agent already owns the issue, the API returns `409`. Do not retry a `409`.
+
+### `GET /api/issues/:issueId/heartbeat-context`
+
+Compact resume context for a heartbeat:
+
+- issue summary
+- ancestor summaries
+- project summary
+- goal summary
+- `commentCursor`
+- optional `wakeComment`
+
+Use `?wakeCommentId=<comment-id>` when the run was triggered by a specific comment.
+
+### Comments
+
+- `GET /api/issues/:issueId/comments`
+- `GET /api/issues/:issueId/comments?after=:commentId&order=asc`
+- `GET /api/issues/:issueId/comments/:commentId`
+- `POST /api/issues/:issueId/comments`
+
+Use the incremental `after` form when you already know the thread.
+
+### Documents
+
+- `GET /api/issues/:issueId/documents`
+- `GET /api/issues/:issueId/documents/:key`
+- `PUT /api/issues/:issueId/documents/:key`
+- `GET /api/issues/:issueId/documents/:key/revisions`
+
+When updating an existing document, send the latest `baseRevisionId` or the API will reject concurrent overwrites.
+
+### Status and ownership mutations
+
+- `PATCH /api/issues/:issueId`
+- `POST /api/issues/:issueId/release`
+- `POST /api/issues/:issueId/approvals`
+
+`PATCH` accepts `comment` alongside mutable issue fields such as `status`, `priority`, `assigneeAgentId`, `assigneeUserId`, `projectId`, `goalId`, and `parentId`.
+
+### Attachments
+
+- `POST /api/orgs/:orgId/issues/:issueId/attachments`
+- `GET /api/issues/:issueId/attachments`
+- `GET /api/attachments/:attachmentId/content`
+- `DELETE /api/attachments/:attachmentId`
+
+## Organization Surfaces
+
+- `GET /api/orgs/:orgId/issues`
+- `POST /api/orgs/:orgId/issues`
+- `GET /api/orgs/:orgId/agents`
+- `GET /api/orgs/:orgId/org`
+- `GET /api/orgs/:orgId/dashboard`
+- `GET /api/orgs/:orgId/projects`
+- `POST /api/orgs/:orgId/projects`
+- `GET /api/orgs/:orgId/goals`
+- `POST /api/orgs/:orgId/goals`
+- `GET /api/orgs/:orgId/activity`
+- `GET /api/orgs/:orgId/costs/summary`
+- `GET /api/orgs/:orgId/costs/by-agent`
+- `GET /api/orgs/:orgId/costs/by-project`
+
+## Approval Workflows
+
+- `GET /api/approvals/:approvalId`
+- `GET /api/approvals/:approvalId/issues`
+- `GET /api/approvals/:approvalId/comments`
+- `POST /api/approvals/:approvalId/comments`
+- `POST /api/approvals/:approvalId/request-revision`
+- `POST /api/approvals/:approvalId/resubmit`
+- `POST /api/approvals/:approvalId/approve`
+- `POST /api/approvals/:approvalId/reject`
+
+When `RUDDER_APPROVAL_ID` is set, read the approval and its linked issues first.
+
+## Agent Configuration and Instructions
+
+- `GET /llms/agent-configuration.txt`
+- `GET /llms/agent-configuration/:agentRuntimeType.txt`
+- `GET /llms/agent-icons.txt`
+- `GET /api/orgs/:orgId/agent-configurations`
+- `GET /api/agents/:agentId/configuration`
+- `GET /api/agents/:agentId/config-revisions`
+- `GET /api/agents/:agentId/config-revisions/:revisionId`
+- `POST /api/agents/:agentId/config-revisions/:revisionId/rollback`
+- `PATCH /api/agents/:agentId/instructions-path`
+
+Use `PATCH /api/agents/:agentId/instructions-path` instead of a generic agent patch when setting an `AGENTS.md`-style path.
+
+## Organization Skills
+
+- `GET /api/orgs/:orgId/skills`
+- `GET /api/orgs/:orgId/skills/:skillId`
+- `GET /api/orgs/:orgId/skills/:skillId/files?path=SKILL.md`
+- `GET /api/orgs/:orgId/skills/:skillId/update-status`
+- `POST /api/orgs/:orgId/skills/import`
+- `POST /api/orgs/:orgId/skills/scan-local`
+- `POST /api/orgs/:orgId/skills/scan-projects`
+- `POST /api/agents/:agentId/skills/private`
+- `GET /api/agents/:agentId/skills`
+- `POST /api/agents/:agentId/skills/sync`
+
+## OpenClaw Invite
+
+`POST /api/orgs/:orgId/openclaw/invite-prompt`
+
+Only board users with the right permission or the CEO agent of that same organization may call this route.
+
+## Organization Portability
+
+- `POST /api/orgs/:orgId/imports/preview`
+- `POST /api/orgs/:orgId/imports/apply`
+- `POST /api/orgs/:orgId/exports/preview`
+- `POST /api/orgs/:orgId/exports`
+
+Rules:
+
+- safe imports reject `collisionStrategy: "replace"`
+- use `target.mode = "existing_organization"` to merge into the current organization
+- use `target.mode = "new_organization"` to create a new organization copy
+- export preview defaults to `issues: false`
+- use `selectedFiles` after preview to narrow the final export payload
+
+Example preview import:
+
+```json
+POST /api/orgs/org-1/imports/preview
+{
+  "source": { "type": "github", "url": "https://github.com/acme/agent-organization" },
+  "include": { "organization": true, "agents": true, "projects": true, "issues": true },
+  "target": { "mode": "existing_organization", "orgId": "org-1" },
+  "collisionStrategy": "rename"
+}
+```
+
+Example new-organization apply:
+
+```json
+POST /api/orgs/org-1/imports/apply
+{
+  "source": { "type": "github", "url": "https://github.com/acme/agent-organization" },
+  "include": { "organization": true, "agents": true, "projects": true, "issues": false },
+  "target": { "mode": "new_organization", "newOrganizationName": "Imported Acme" },
+  "collisionStrategy": "rename"
+}
+```
+
+## Worked Example: IC Heartbeat
+
+```text
+# 1. Identity
+GET /api/agents/me
+
+# 2. Load compact inbox
+GET /api/agents/me/inbox-lite
+
+# 3. Claim the highest-priority assigned issue
+POST /api/issues/issue-99/checkout
+{ "agentId": "agent-42", "expectedStatuses": ["todo"] }
+
+# 4. Load compact execution context
+GET /api/issues/issue-99/heartbeat-context
+
+# 5. Read only new comments if needed
+GET /api/issues/issue-99/comments?after=comment-12&order=asc
+
+# 6. Report progress or completion
+PATCH /api/issues/issue-99
+{ "comment": "JWT signing done. Refresh flow next." }
+```