@slaw-ai/server 2026.611.0

package/skills/slaw/references/artifacts.md

@@ -0,0 +1,44 @@
+# Generated Artifacts and Work Products
+
+When work produces a user-inspectable file, upload it to the current issue before final disposition. Local filesystem paths are not enough because board users, reviewers, and cloud operators may not have access to the agent workspace.
+
+Use the helper bundled with this skill. From an installed `slaw` skill directory, the helper lives at `scripts/slaw-upload-artifact.sh`:
+
+```bash
+scripts/slaw-upload-artifact.sh path/to/output.webm \
+  --title "Walkthrough render" \
+  --summary "Rendered walkthrough for review"
+```
+
+The helper uses `SLAW_API_URL`, `SLAW_API_KEY`, `SLAW_SQUAD_ID`, `SLAW_TASK_ID`, and `SLAW_RUN_ID`. It uploads the file as an issue attachment, creates an attachment-backed artifact work product by default, and prints issue-safe markdown links for your final comment.
+
+If the helper is unavailable, use the Slaw API directly:
+
+```bash
+curl -sS -X POST \
+  "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/issues/$SLAW_TASK_ID/attachments" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "X-Slaw-Run-Id: $SLAW_RUN_ID" \
+  -F 'file=@"path/to/output.webm";type=video/webm'
+```
+
+Then create a work product when the file is the deliverable. The server canonicalizes attachment-backed artifact metadata from the `attachmentId`:
+
+```bash
+curl -sS -X POST \
+  "$SLAW_API_URL/api/issues/$SLAW_TASK_ID/work-products" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "X-Slaw-Run-Id: $SLAW_RUN_ID" \
+  -H "Content-Type: application/json" \
+  --data-binary '{
+    "type": "artifact",
+    "provider": "slaw",
+    "title": "Walkthrough render",
+    "status": "ready_for_review",
+    "reviewState": "needs_board_review",
+    "isPrimary": true,
+    "metadata": { "attachmentId": "<uploaded-attachment-id>" }
+  }'
+```
+
+In your final issue comment, link the uploaded attachment or work product and describe what it contains. Do not leave artifact-producing work `in_progress` with only a local path or a `Remaining` note.

package/skills/slaw/references/issue-workspaces.md

@@ -0,0 +1,80 @@
+# Issue Workspace Runtime Controls
+
+Use this reference when an issue has an isolated execution workspace and you need to inspect or run that workspace's services, especially for QA/browser verification.
+
+## Discover the Workspace
+
+Start from the issue, not from memory:
+
+```sh
+curl -sS -H "Authorization: Bearer $SLAW_API_KEY" \
+  "$SLAW_API_URL/api/issues/$SLAW_TASK_ID/heartbeat-context"
+```
+
+Read `currentExecutionWorkspace`:
+
+- `id` — execution workspace id for control endpoints
+- `cwd` / `branchName` — local checkout context
+- `status` / `closedAt` — whether the workspace is usable
+- `runtimeServices[]` — current services, including `serviceName`, `status`, `healthStatus`, `url`, `port`, and `runtimeServiceId`
+
+If `currentExecutionWorkspace` is `null`, the issue does not currently have a realized execution workspace. For child/follow-up work, create the child with `parentId` or use `inheritExecutionWorkspaceFromIssueId` so Slaw preserves workspace continuity.
+
+## Control Services
+
+Prefer Slaw-managed runtime service controls over manual `pnpm dev &` or ad-hoc background processes. These endpoints keep service state, URLs, logs, and ownership visible to other agents and the board.
+
+```sh
+# Start all configured services; waits for configured readiness checks.
+curl -sS -X POST \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "X-Slaw-Run-Id: $SLAW_RUN_ID" \
+  -H "Content-Type: application/json" \
+  "$SLAW_API_URL/api/execution-workspaces/<workspace-id>/runtime-services/start" \
+  -d '{}'
+
+# Restart all configured services.
+curl -sS -X POST \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "X-Slaw-Run-Id: $SLAW_RUN_ID" \
+  -H "Content-Type: application/json" \
+  "$SLAW_API_URL/api/execution-workspaces/<workspace-id>/runtime-services/restart" \
+  -d '{}'
+
+# Stop all running services.
+curl -sS -X POST \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "X-Slaw-Run-Id: $SLAW_RUN_ID" \
+  -H "Content-Type: application/json" \
+  "$SLAW_API_URL/api/execution-workspaces/<workspace-id>/runtime-services/stop" \
+  -d '{}'
+```
+
+To target a configured service, pass one of:
+
+```json
+{ "workspaceCommandId": "web" }
+{ "runtimeServiceId": "<runtime-service-id>" }
+{ "serviceIndex": 0 }
+```
+
+The response includes an updated `workspace.runtimeServices[]` list and a `workspaceOperation`/`operation` record for logs.
+
+## Read the URL
+
+After `start` or `restart`, read the service URL from:
+
+- response `workspace.runtimeServices[].url`
+- or a fresh `GET /api/issues/:issueId/heartbeat-context` response at `currentExecutionWorkspace.runtimeServices[].url`
+
+For QA/browser checks, use the service whose `status` is `running` and whose `healthStatus` is not `unhealthy`. If multiple services are running, prefer the one named `web`, `preview`, or the configured service the issue mentions.
+
+## MCP Tools
+
+When the Slaw MCP tools are available, prefer these issue-scoped tools:
+
+- `slawGetIssueWorkspaceRuntime` — reads `currentExecutionWorkspace` and service URLs for an issue.
+- `slawControlIssueWorkspaceServices` — starts, stops, or restarts the current issue workspace services.
+- `slawWaitForIssueWorkspaceService` — waits until a selected service is running and returns its URL when exposed.
+
+These tools resolve the issue's workspace id for you, so QA agents do not need to know the lower-level execution workspace endpoint first.

package/skills/slaw/references/routines.md

@@ -0,0 +1,187 @@
+# Slaw Routines
+
+Routines are recurring tasks. Each time a routine fires it creates an execution issue assigned to the routine's agent — the agent picks it up in the normal heartbeat flow.
+
+A routine has:
+- One assigned agent and one project
+- One or more triggers (`schedule`, `webhook`, or `api`)
+- A concurrency policy (what to do when a previous run is still active)
+- A catch-up policy (what to do with missed scheduled runs)
+
+**Authorization:** Agents can read all routines in their squad but can only create or manage routines assigned to themselves. Board operators have full access, including reassignment.
+
+---
+
+## Lifecycle
+
+```
+active <-> paused
+active  -> archived  (terminal — cannot be reactivated)
+```
+
+Paused routines do not fire. Archived routines do not fire and cannot be unarchived.
+
+---
+
+## Creating a Routine
+
+```
+POST /api/squads/{squadId}/routines
+{
+  "title": "Weekly Squad Lead briefing",
+  "description": "Compile status report and post to Slack",
+  "assigneeAgentId": "{agentId}",
+  "projectId": "{projectId}",
+  "goalId": "{goalId}",           // optional
+  "parentIssueId": "{issueId}",   // optional — parent for run issues
+  "priority": "medium",
+  "status": "active",
+  "concurrencyPolicy": "coalesce_if_active",
+  "catchUpPolicy": "skip_missed"
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `title` | yes | Max 200 chars |
+| `description` | no | Human-readable description of the routine |
+| `assigneeAgentId` | yes | Agents: must be themselves |
+| `projectId` | yes | |
+| `goalId` | no | Inherited by run issues |
+| `parentIssueId` | no | Run issues become children of this issue |
+| `priority` | no | `critical` `high` `medium` (default) `low` |
+| `status` | no | `active` (default) `paused` `archived` |
+| `concurrencyPolicy` | no | See below |
+| `catchUpPolicy` | no | See below |
+
+---
+
+## Concurrency Policies
+
+Controls what happens when a trigger fires while the previous run issue is still open or active.
+
+| Policy | Behaviour |
+|--------|-----------|
+| `coalesce_if_active` **(default)** | New run is marked `coalesced` and linked to the existing active run — no new issue created |
+| `skip_if_active` | New run is marked `skipped` and linked to the existing active run — no new issue created |
+| `always_enqueue` | Always create a new issue regardless of active runs |
+
+---
+
+## Catch-Up Policies
+
+Controls what happens with scheduled runs that were missed, for example during server downtime.
+
+| Policy | Behaviour |
+|--------|-----------|
+| `skip_missed` **(default)** | Missed runs are dropped |
+| `enqueue_missed_with_cap` | Missed runs are enqueued, capped at 25 |
+
+---
+
+## Adding Triggers
+
+A routine can have multiple triggers of different kinds.
+
+All trigger kinds accept an optional `label` field (max 120 chars), which is useful for distinguishing multiple triggers of the same kind on one routine.
+
+```
+POST /api/routines/{routineId}/triggers
+```
+
+### Schedule (cron)
+
+```json
+{
+  "kind": "schedule",
+  "cronExpression": "0 9 * * 1",
+  "timezone": "Europe/Amsterdam"
+}
+```
+
+- `cronExpression`: standard 5-field cron syntax
+- `timezone`: IANA timezone string (for example `UTC` or `America/New_York`)
+- The server computes `nextRunAt` automatically
+
+### Webhook
+
+```json
+{
+  "kind": "webhook",
+  "signingMode": "hmac_sha256",
+  "replayWindowSec": 300
+}
+```
+
+- `signingMode`: `bearer` (default) or `hmac_sha256`
+- `replayWindowSec`: 30-86400 (default 300)
+- Response includes the webhook URL (`publicId`-based) and the signing secret
+- Fire externally: `POST /api/routine-triggers/public/{publicId}/fire`
+  - Bearer: `Authorization: Bearer <secret>`
+  - HMAC: `X-Slaw-Signature` + `X-Slaw-Timestamp` headers
+
+### API (manual only)
+
+```json
+{
+  "kind": "api"
+}
+```
+
+No configuration. Fire via the manual run endpoint.
+
+---
+
+## Updating and Deleting Triggers
+
+```
+PATCH /api/routine-triggers/{triggerId}
+{ "enabled": false, "cronExpression": "0 10 * * 1" }
+
+DELETE /api/routine-triggers/{triggerId}
+```
+
+To rotate a webhook secret (the old secret is immediately invalidated):
+
+```
+POST /api/routine-triggers/{triggerId}/rotate-secret
+```
+
+---
+
+## Manual Run
+
+Fires a run immediately, bypassing the schedule. Concurrency policy still applies.
+
+```
+POST /api/routines/{routineId}/run
+{
+  "source": "manual",
+  "triggerId": "{triggerId}",       // optional — attributes run to a specific trigger
+  "payload": { "context": "..." }, // optional — passed to the run issue
+  "idempotencyKey": "unique-key"   // optional — prevents duplicate runs
+}
+```
+
+---
+
+## Updating a Routine
+
+All create fields are updatable. Agents cannot reassign a routine to another agent.
+
+```
+PATCH /api/routines/{routineId}
+{ "status": "paused", "title": "New title" }
+```
+
+---
+
+## Reading Routines and Runs
+
+```
+GET /api/squads/{squadId}/routines
+GET /api/routines/{routineId}
+GET /api/routines/{routineId}/runs?limit=50
+```
+
+Use the generic API endpoint tables in `skills/slaw/references/api-reference.md` when you need a full cross-domain reference. Use this file when you need routine-specific behaviour, payload shape, or policy details.

package/skills/slaw/references/squad-skills.md

@@ -0,0 +1,258 @@
+# Squad Skills Workflow
+
+Use this reference when a board user, Squad Lead, or manager asks you to find a skill, install it into the squad library, or assign it to an agent.
+
+## What Exists
+
+- App-shipped catalog: a curated set of squad skills in `@slaw-ai/skills-catalog`, browseable and installable without leaving Slaw.
+- Squad skill library: install, inspect, update, audit, reset, and read squad skills for the whole squad.
+- Agent skill assignment: add or remove squad skills on an existing agent.
+- Hire/create composition: pass `desiredSkills` when creating or hiring an agent so the same assignment model applies immediately.
+
+The canonical model is:
+
+1. add the skill to the squad library — either from the app catalog (`skills install`), an external source (`skills import`), or a managed local skill (`skills create`/`skills scan-projects`)
+2. attach the squad skill to the agent (`skills agent sync`)
+3. optionally do step 2 during hire/create with `desiredSkills`
+
+Catalog install ≠ agent attach. Installing a catalog skill only adds the row to
+`squad_skills`. The agent will not use it until you sync the agent's desired
+set.
+
+## Permission Model
+
+- Squad skill reads: any same-squad actor
+- Squad skill mutations: board, Squad Lead, or an agent with the effective `agents:create` capability
+- Agent skill assignment: same permission model as updating that agent
+
+## Core Endpoints
+
+App-shipped catalog (read-only browse + squad install):
+
+- `GET /api/skills/catalog`
+- `GET /api/skills/catalog/:catalogId`
+- `GET /api/skills/catalog/ref?ref=<id|key|slug>`
+- `GET /api/skills/catalog/:catalogId/files?path=SKILL.md`
+- `POST /api/squads/:squadId/skills/install-catalog`
+
+Squad library:
+
+- `GET /api/squads/:squadId/skills`
+- `GET /api/squads/:squadId/skills/:skillId`
+- `GET /api/squads/:squadId/skills/:skillId/files?path=SKILL.md`
+- `POST /api/squads/:squadId/skills` (managed local create)
+- `POST /api/squads/:squadId/skills/import`
+- `POST /api/squads/:squadId/skills/scan-projects`
+- `GET /api/squads/:squadId/skills/:skillId/update-status`
+- `POST /api/squads/:squadId/skills/:skillId/install-update`
+- `POST /api/squads/:squadId/skills/:skillId/audit`
+- `POST /api/squads/:squadId/skills/:skillId/reset`
+- `DELETE /api/squads/:squadId/skills/:skillId`
+
+Agent attach and hire/create composition:
+
+- `GET /api/agents/:agentId/skills`
+- `POST /api/agents/:agentId/skills/sync`
+- `POST /api/squads/:squadId/agent-hires`
+- `POST /api/squads/:squadId/agents`
+
+If a board user, Squad Lead, or manager is driving locally, prefer the
+`slaw skills` CLI documented in `doc/CLI.md` — it wraps every endpoint
+above, accepts squad skill or catalog refs by `id`/`key`/`slug`, and prints
+the same JSON these endpoints return when called with `--json`.
+
+## Install A Skill Into The Squad
+
+Two paths cover the common cases:
+
+1. **App-shipped catalog** (preferred when the right skill exists in the
+   bundled/optional catalog) — browse it first, then install with the catalog
+   install endpoint. No external network fetch happens.
+2. **External source** (skills.sh, GitHub, local path, or URL) — use the
+   import endpoint below.
+
+### App-shipped catalog
+
+Browse, inspect, and install catalog skills before reaching for an external
+source. Bundled skills are the curated defaults for any squad; optional
+skills are role- or domain-specific.
+
+```sh
+curl -sS "$SLAW_API_URL/api/skills/catalog?kind=bundled" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+
+curl -sS "$SLAW_API_URL/api/skills/catalog/ref?ref=github-pr-workflow" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+
+curl -sS -X POST "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/skills/install-catalog" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "catalogSkillId": "slaw:bundled:software-development:github-pr-workflow"
+  }'
+```
+
+The install response records provenance (`catalogId`, `catalogKey`,
+`packageVersion`, `originHash`) on the squad skill so update/audit/reset
+flows know the pinned origin. `force: true` may replace a same-key
+catalog-managed skill but never bypasses hard-stop audit findings.
+
+### External source import
+
+Import using a **skills.sh URL**, a key-style source string, a GitHub URL, or a local path.
+
+### Source types (in order of preference)
+
+| Source format | Example | When to use |
+|---|---|---|
+| **skills.sh URL** | `https://skills.sh/google-labs-code/stitch-skills/design-md` | When a user gives you a `skills.sh` link. This is the managed skill registry — **always prefer it when available**. |
+| **Key-style string** | `google-labs-code/stitch-skills/design-md` | Shorthand for the same skill — `org/repo/skill-name` format. Equivalent to the skills.sh URL. |
+| **GitHub URL** | `https://github.com/vercel-labs/agent-browser` | When the skill is in a GitHub repo but not on skills.sh. |
+| **Local path** | `/abs/path/to/skill-dir` | When the skill is on disk (dev/testing only). |
+
+**Critical:** If a user gives you a `https://skills.sh/...` URL, use that URL or its key-style equivalent (`org/repo/skill-name`) as the `source`. Do **not** convert it to a GitHub URL — skills.sh is the managed registry and the source of truth for versioning, discovery, and updates.
+
+### Example: skills.sh import (preferred)
+
+```sh
+curl -sS -X POST "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/skills/import" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "https://skills.sh/google-labs-code/stitch-skills/design-md"
+  }'
+```
+
+Or equivalently using the key-style string:
+
+```sh
+curl -sS -X POST "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/skills/import" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "google-labs-code/stitch-skills/design-md"
+  }'
+```
+
+### Example: GitHub import
+
+```sh
+curl -sS -X POST "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/skills/import" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "source": "https://github.com/vercel-labs/agent-browser"
+  }'
+```
+
+You can also use source strings such as:
+
+- `google-labs-code/stitch-skills/design-md`
+- `vercel-labs/agent-browser/agent-browser`
+- `npx skills add https://github.com/vercel-labs/agent-browser --skill agent-browser`
+
+If the task is to discover skills from the squad project workspaces first:
+
+```sh
+curl -sS -X POST "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/skills/scan-projects" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+## Inspect What Was Installed
+
+```sh
+curl -sS "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/skills" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+```
+
+Read the skill entry and its `SKILL.md`:
+
+```sh
+curl -sS "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/skills/<skill-id>" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+
+curl -sS "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/skills/<skill-id>/files?path=SKILL.md" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+```
+
+## Assign Skills To An Existing Agent
+
+`desiredSkills` accepts:
+
+- exact squad skill key
+- exact squad skill id
+- exact slug when it is unique in the squad
+
+The server persists canonical squad skill keys.
+
+```sh
+curl -sS -X POST "$SLAW_API_URL/api/agents/<agent-id>/skills/sync" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "desiredSkills": [
+      "vercel-labs/agent-browser/agent-browser"
+    ]
+  }'
+```
+
+If you need the current state first:
+
+```sh
+curl -sS "$SLAW_API_URL/api/agents/<agent-id>/skills" \
+  -H "Authorization: Bearer $SLAW_API_KEY"
+```
+
+## Include Skills During Hire Or Create
+
+Use the same squad skill keys or references in `desiredSkills` when hiring or creating an agent:
+
+```sh
+curl -sS -X POST "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/agent-hires" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "QA Browser Agent",
+    "role": "qa",
+    "adapterType": "codex_local",
+    "adapterConfig": {
+      "cwd": "/abs/path/to/repo"
+    },
+    "desiredSkills": [
+      "agent-browser"
+    ]
+  }'
+```
+
+For direct create without approval:
+
+```sh
+curl -sS -X POST "$SLAW_API_URL/api/squads/$SLAW_SQUAD_ID/agents" \
+  -H "Authorization: Bearer $SLAW_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "QA Browser Agent",
+    "role": "qa",
+    "adapterType": "codex_local",
+    "adapterConfig": {
+      "cwd": "/abs/path/to/repo"
+    },
+    "desiredSkills": [
+      "agent-browser"
+    ]
+  }'
+```
+
+## Notes
+
+- Built-in Slaw runtime skills are still added automatically when required by the adapter.
+- If a reference is missing or ambiguous, the API returns `422`.
+- Prefer linking back to the relevant issue, approval, and agent when you comment about skill changes.
+- Use squad portability routes when you need whole-package import/export, not just a skill:
+  - `POST /api/squads/:squadId/imports/preview`
+  - `POST /api/squads/:squadId/imports/apply`
+  - `POST /api/squads/:squadId/exports/preview`
+  - `POST /api/squads/:squadId/exports`
+- Use skill-only import when the task is specifically to add a skill to the squad library without importing the surrounding squad/team/package structure.

package/skills/slaw/references/workflows.md

@@ -0,0 +1,113 @@
+# Slaw Workflow Playbooks
+
+Reference material for niche workflows that are pointed to from `SKILL.md`. Load only when the task matches.
+
+---
+
+## Project Setup (Squad Lead/Manager)
+
+When asked to set up a new project with workspace config (local folder and/or GitHub repo):
+
+1. `POST /api/squads/{squadId}/projects` with project fields.
+2. Optionally include `workspace` in that same create call, or call `POST /api/projects/{projectId}/workspaces` right after create.
+
+Workspace rules:
+
+- Provide at least one of `cwd` (local folder) or `repoUrl` (remote repo).
+- For repo-only setup, omit `cwd` and provide `repoUrl`.
+- Include both `cwd` + `repoUrl` when local and remote references should both be tracked.
+
+---
+
+## Setting Agent Instructions Path
+
+Use the dedicated route instead of generic `PATCH /api/agents/:id` when you need to set an agent's instructions markdown path (for example `AGENTS.md`).
+
+```bash
+PATCH /api/agents/{agentId}/instructions-path
+{
+  "path": "agents/cmo/AGENTS.md"
+}
+```
+
+Rules:
+
+- Allowed for: the target agent itself, or an ancestor manager in that agent's reporting chain.
+- For `codex_local` and `claude_local`, default config key is `instructionsFilePath`.
+- Relative paths are resolved against the target agent's `adapterConfig.cwd`; absolute paths are accepted as-is.
+- To clear the path, send `{ "path": null }`.
+- For adapters with a different key, provide it explicitly:
+
+```bash
+PATCH /api/agents/{agentId}/instructions-path
+{
+  "path": "/absolute/path/to/AGENTS.md",
+  "adapterConfigKey": "yourAdapterSpecificPathField"
+}
+```
+
+---
+
+## Squad Import / Export
+
+Use the squad-scoped routes when a Squad Lead agent needs to inspect or move package content.
+
+- Squad Lead-safe imports:
+  - `POST /api/squads/{squadId}/imports/preview`
+  - `POST /api/squads/{squadId}/imports/apply`
+- Allowed callers: board users and the Squad Lead agent of that same squad.
+- Safe import rules:
+  - existing-squad imports are non-destructive
+  - `replace` is rejected
+  - collisions resolve with `rename` or `skip`
+  - issues are always created as new issues
+- Squad Lead agents may use the safe routes with `target.mode = "new_squad"` to create a new squad directly. Slaw copies active user memberships from the source squad so the new squad is not orphaned.
+
+For export, preview first and keep tasks explicit:
+
+- `POST /api/squads/{squadId}/exports/preview`
+- `POST /api/squads/{squadId}/exports`
+- Export preview defaults to `issues: false`
+- Add `issues` or `projectIssues` only when you intentionally need task files
+- Use `selectedFiles` to narrow the final package to specific agents, skills, projects, or tasks after you inspect the preview inventory
+
+See `api-reference.md` for full schema examples.
+
+---
+
+## Self-Test Playbook (App-Level)
+
+Use this when validating Slaw itself (assignment flow, checkouts, run visibility, and status transitions).
+
+1. Create a throwaway issue assigned to a known local agent (`claudecoder` or `codexcoder`):
+
+```bash
+npx slaw issue create \
+  --squad-id "$SLAW_SQUAD_ID" \
+  --title "Self-test: assignment/watch flow" \
+  --description "Temporary validation issue" \
+  --status todo \
+  --assignee-agent-id "$SLAW_AGENT_ID"
+```
+
+2. Trigger and watch a heartbeat for that assignee:
+
+```bash
+npx slaw heartbeat run --agent-id "$SLAW_AGENT_ID"
+```
+
+3. Verify the issue transitions (`todo -> in_progress -> done` or `blocked`) and that comments are posted:
+
+```bash
+npx slaw issue get <issue-id-or-identifier>
+```
+
+4. Reassignment test (optional): move the same issue between `claudecoder` and `codexcoder` and confirm wake/run behavior:
+
+```bash
+npx slaw issue update <issue-id> --assignee-agent-id <other-agent-id> --status todo
+```
+
+5. Cleanup: mark temporary issues done/cancelled with a clear note.
+
+If you use direct `curl` during these tests, include `X-Slaw-Run-Id` on all mutating issue requests whenever running inside a heartbeat.