{"id":"c293e024-ac41-46fc-b499-487effb9a504","entityType":"agent","slug":"clawhub-cargo-ai-cargo-workspace-management","name":"cargo-workspace-management","canonicalUrl":"https://www.xpersona.co/agent/clawhub-cargo-ai-cargo-workspace-management","canonicalPath":"/agent/clawhub-cargo-ai-cargo-workspace-management","generatedAt":"2026-10-10T05:40:16.359Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:08:41.185Z","emptyReason":null},"description":"Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: \"invite my teammate\", \"create an API token for CI\", \"who has access\", \"organize these into folders\", \"rotate that token\", \"upload this CSV for a batch\" — and for feedback: \"report this bug to Cargo\", \"send feedback to the Cargo team\", \"this CLI command is broken\", \"share this session with Cargo\", \"request a feature\". Most commands need a token with admin access. Skip when: the question is about credits, plans, or invoices — use cargo-billing.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.9K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s178dcd9wkfn0a2fqrygmt3jzn87j9e1:cargo-workspace-management","sourceUrl":"https://clawhub.ai/cargo-ai/cargo-workspace-management","homepage":"https://clawhub.ai/cargo-ai/skills/cargo-workspace-management","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/cargo-ai/cargo-workspace-management","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/cargo-ai/skills/cargo-workspace-management","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":66,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"cargo-workspace-management technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:08:41.185Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:08:41.185Z","emptyReason":null},"stars":null,"forks":null,"downloads":1908,"packageName":null,"latestVersion":"1.3.1","tractionLabel":"1.9K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:08:40.108Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T23:08:41.185Z","lastCrawledAt":"2026-10-09T23:08:40.108Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T23:08:40.108Z","lastVerifiedAt":null,"highlights":[{"version":"1.3.1","createdAt":"2026-09-21T22:04:41.232Z","changelog":"- Removed the unused skill-card.md file. - Updated version to 1.3.1 in metadata. - No user-facing feature or documentation changes.","fileCount":11,"zipByteSize":19023},{"version":"1.3.0","createdAt":"2026-09-16T07:27:22.423Z","changelog":"cargo-workspace-management 1.3.0 - Added workspace environment variable management commands: `envVar list` and `envVar create`. - Updated documentation to include new envVar usage examples and options. - Removed the obsolete skill-card.md file.","fileCount":11,"zipByteSize":18857},{"version":"1.2.2","createdAt":"2026-08-27T23:45:17.213Z","changelog":"cargo-workspace-management v1.2.2 - Updated SKILL.md: improved description and added clearer onboarding (\"Bootstrap\") steps for new users. - Expanded trigger phrases to help with more natural language requests. - Clarified admin requirements and when to skip usage of this skill (e.g., billing-related questions). - Removed obsolete skill-card.md file. - No changes to CLI functionality or command syntax.","fileCount":11,"zipByteSize":17903},{"version":"1.2.1","createdAt":"2026-08-11T21:44:39.958Z","changelog":"- Updates compatibility instructions to clarify login and account creation methods (now supports `cargo-ai login --email`, with or without browser). - Adds new metadata file: skill-metadata.json. - Removes outdated file: skill-card.md. - Bumps version to 1.2.1.","fileCount":11,"zipByteSize":17485},{"version":"1.2.0","createdAt":"2026-07-09T04:39:46.817Z","changelog":"cargo-workspace-management 1.2.0 - Minor documentation updates to SKILL.md and references/examples/reports.md. - Removed deprecated skill-card.md file. - No changes to functionality or CLI commands.","fileCount":10,"zipByteSize":16811},{"version":"1.1.0","createdAt":"2026-06-17T07:27:12.352Z","changelog":"cargo-workspace-management 1.1.0 - Added SessionStop hook reference for session tracking in examples documentation. - Removed deprecated skill-card.md file. - General documentation updates and minor clarifications in SKILL.md.","fileCount":10,"zipByteSize":16261},{"version":"1.0.2","createdAt":"2026-06-09T22:01:19.255Z","changelog":"- Added note clarifying that the Cargo installer now scaffolds session tracking hooks (SessionStart/SessionEnd) automatically. - Minor updates to documentation in SKILL.md around session tracking. - Removed the skill-card.md file as part of documentation cleanup. - No changes to user-facing commands or functionality.","fileCount":10,"zipByteSize":15849},{"version":"1.0.1","createdAt":"2026-05-28T22:13:39.931Z","changelog":"- Added reference to a new session management example: `references/examples/sessions.md` - Documented the `session upsert` command for session tracking and reporting - Updated install metadata to use the latest `@cargo-ai/cli` package - Clarified admin-only requirements for certain workspace commands - Linked prerequisites to a shared documentation file for consistency","fileCount":10,"zipByteSize":16081}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s178dcd9wkfn0a2fqrygmt3jzn87j9e1:cargo-workspace-management","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s178dcd9wkfn0a2fqrygmt3jzn87j9e1:cargo-workspace-management` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/cargo-ai/cargo-workspace-management before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T05:40:16.356Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-cargo-ai-cargo-workspace-management/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T23:08:41.185Z","emptyReason":null},"readme":"Skill: cargo-workspace-management\n\nOwner: cargo-ai\n\nSummary: Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: \"invite my teammate\", \"create an API token for CI\", \"who has access\", \"organize these into folders\", \"rotate that token\", \"upload this CSV for a batch\" — and for feedback: \"report this bug to Cargo\", \"send feedback to the Cargo team\", \"this CLI command is broken\", \"share this session with Cargo\", \"request a feature\". Most commands need a token with admin access. Skip when: the question is about credits, plans, or invoices — use cargo-billing.\n\nTags: latest:1.3.1\n\nVersion history:\n\nv1.3.1 | 2026-09-21T22:04:41.232Z | auto\n\n- Removed the unused skill-card.md file.\n- Updated version to 1.3.1 in metadata.\n- No user-facing feature or documentation changes.\n\nv1.3.0 | 2026-09-16T07:27:22.423Z | auto\n\ncargo-workspace-management 1.3.0\n\n- Added workspace environment variable management commands: `envVar list` and `envVar create`.\n- Updated documentation to include new envVar usage examples and options.\n- Removed the obsolete skill-card.md file.\n\nv1.2.2 | 2026-08-27T23:45:17.213Z | auto\n\ncargo-workspace-management v1.2.2\n\n- Updated SKILL.md: improved description and added clearer onboarding (\"Bootstrap\") steps for new users.\n- Expanded trigger phrases to help with more natural language requests.\n- Clarified admin requirements and when to skip usage of this skill (e.g., billing-related questions).\n- Removed obsolete skill-card.md file.\n- No changes to CLI functionality or command syntax.\n\nv1.2.1 | 2026-08-11T21:44:39.958Z | auto\n\n- Updates compatibility instructions to clarify login and account creation methods (now supports `cargo-ai login --email`, with or without browser).\n- Adds new metadata file: skill-metadata.json.\n- Removes outdated file: skill-card.md.\n- Bumps version to 1.2.1.\n\nv1.2.0 | 2026-07-09T04:39:46.817Z | auto\n\ncargo-workspace-management 1.2.0\n\n- Minor documentation updates to SKILL.md and references/examples/reports.md.\n- Removed deprecated skill-card.md file.\n- No changes to functionality or CLI commands.\n\nv1.1.0 | 2026-06-17T07:27:12.352Z | auto\n\ncargo-workspace-management 1.1.0\n\n- Added SessionStop hook reference for session tracking in examples documentation.\n- Removed deprecated skill-card.md file.\n- General documentation updates and minor clarifications in SKILL.md.\n\nv1.0.2 | 2026-06-09T22:01:19.255Z | auto\n\n- Added note clarifying that the Cargo installer now scaffolds session tracking hooks (SessionStart/SessionEnd) automatically.\n- Minor updates to documentation in SKILL.md around session tracking.\n- Removed the skill-card.md file as part of documentation cleanup.\n- No changes to user-facing commands or functionality.\n\nv1.0.1 | 2026-05-28T22:13:39.931Z | auto\n\n- Added reference to a new session management example: `references/examples/sessions.md`\n- Documented the `session upsert` command for session tracking and reporting\n- Updated install metadata to use the latest `@cargo-ai/cli` package\n- Clarified admin-only requirements for certain workspace commands\n- Linked prerequisites to a shared documentation file for consistency\n\nv1.0.0 | 2026-05-28T19:28:51.750Z | auto\n\nInitial release of cargo-workspace-management skill.\n\n- Manage workspace users: invite, remove, update roles.\n- Create, list, and remove API tokens.\n- Organize resources into folders: create, update, list, remove.\n- Inspect available roles and permissions.\n- Submit reports to workspace management for issues or feedback.\n- Requires @cargo-ai/cli and a Cargo account for authentication.\n\nArchive index:\n\nArchive v1.3.1: 11 files, 19023 bytes\n\nFiles: references/examples/folders.md (1583b), references/examples/reports.md (6122b), references/examples/sessions.md (4044b), references/examples/tokens.md (2032b), references/examples/users.md (1258b), references/response-shapes.md (4525b), references/troubleshooting.md (5031b), skill-card.md (2924b), skill-metadata.json (1290b), SKILL.md (14159b), _meta.json (145b)\n\nFile v1.3.1:SKILL.md\n\n---\nname: cargo-workspace-management\ndescription: \"Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: \\\"invite my teammate\\\", \\\"create an API token for CI\\\", \\\"who has access\\\", \\\"organize these into folders\\\", \\\"rotate that token\\\", \\\"upload this CSV for a batch\\\" — and for feedback: \\\"report this bug to Cargo\\\", \\\"send feedback to the Cargo team\\\", \\\"this CLI command is broken\\\", \\\"share this session with Cargo\\\", \\\"request a feature\\\". Most commands need a token with admin access. Skip when: the question is about credits, plans, or invoices — use cargo-billing.\"\nversion: \"1.3.1\"\ncompatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n  author: getcargo\n  openclaw:\n    requires:\n      bins:\n        - cargo-ai\n    install:\n      - kind: node\n        package: \"@cargo-ai/cli@latest\"\n        bins:\n          - cargo-ai\n    homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Workspace\n\nWorkspace administration: managing users, API tokens, folders, roles, workspace-level files, and submitting reports to workspace management.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/users.md` for user invite and management examples.\n> See `references/examples/tokens.md` for API token creation and rotation examples.\n> See `references/examples/folders.md` for organizing resources into folders.\n> See `references/examples/reports.md` for examples of submitting workspace management reports.\n> See `references/examples/sessions.md` for session tracking — the Cargo installer scaffolds the Claude Code SessionStart + Stop + SessionEnd hooks automatically.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\n```\n\nEvery command prints JSON to stdout; failures exit non-zero with `{\"errorMessage\": \"...\"}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. **Admin-only:** user, role, and token writes require a token with admin access on the workspace. Folder writes and `report create` work with non-admin tokens. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.\n\n## Discover resources first\n\n```bash\ncargo-ai whoami                        # current user and active workspace\ncargo-ai workspaceManagement user list           # all workspace members\ncargo-ai workspaceManagement role list           # available roles\ncargo-ai workspaceManagement token list          # all API tokens\ncargo-ai workspaceManagement folder list         # all folders\n```\n\n## Quick reference\n\n```bash\ncargo-ai whoami\ncargo-ai workspaceManagement user list\ncargo-ai workspaceManagement user create --user-email <email> --role-slug <slug>\ncargo-ai workspaceManagement token list\ncargo-ai workspaceManagement token create --name <name>\ncargo-ai workspaceManagement token remove <token-uuid>\ncargo-ai workspaceManagement folder list\ncargo-ai workspaceManagement folder create --name <name> --emoji-slug <slug> --kind <kind>\ncargo-ai workspaceManagement report create --title <title> --description <description>\ncargo-ai workspaceManagement session upsert --session-id <id> --title <title> --summary <summary> [--finished]\ncargo-ai workspaceManagement envVar list\ncargo-ai workspaceManagement envVar create --key <KEY> [--value <v>] [--secret]\n```\n\n## Current user and workspace\n\n```bash\n# Get your current user and workspace context\ncargo-ai whoami\n# → Returns your user UUID, email, and active workspace UUID\n```\n\n## Users\n\n```bash\n# List all workspace members\ncargo-ai workspaceManagement user list\n\n# Invite a new user (requires their email and a role)\ncargo-ai workspaceManagement user create \\\n  --user-email user@example.com \\\n  --role-slug <role-slug>\n\n# Update a user's role\ncargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>\n\n# Remove a user from the workspace\ncargo-ai workspaceManagement user remove --user-uuid <uuid>\n```\n\n## Roles\n\nRoles define what users can do in the workspace.\n\n```bash\n# List available roles\ncargo-ai workspaceManagement role list\n```\n\nAlways check available roles before inviting users — use the `slug` from `role list` when creating or updating users.\n\n## API tokens\n\nEach token has a human-readable `name` and a `permissions` field. Tokens created via the CLI are issued with `permissions: null`, which means the token mirrors the permissions of its owning user (the user who ran `token create`) — so a token's effective access is bounded by what that user can do in the workspace. Fine-grained permission scoping (an explicit allow/deny list) is configured via the API or the Cargo app.\n\n```bash\n# List all API tokens (includes name and permissions of each token)\ncargo-ai workspaceManagement token list\n\n# Create a new token — --name is required\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline\"\n# → Returns the token value — store it securely, it won't be shown again\n\n# Remove a token\ncargo-ai workspaceManagement token remove <token-uuid>\n```\n\n**Naming:** Pick a `--name` that makes the token's purpose obvious in `token list` later (e.g. `\"GitHub Actions — production\"`, `\"Local dev — alice\"`, `\"Zapier integration\"`). The name is the only way to tell tokens apart in the listing.\n\n**Security:** Token values are only shown once at creation. Store them in a secrets manager (e.g. GitHub Secrets, AWS Secrets Manager).\n\n## Folders\n\nFolders organize resources (plays, tools, agents) in the Cargo app.\n\n```bash\n# List all folders\ncargo-ai workspaceManagement folder list\n\n# Create a folder (kind: \"tool\", \"play\", \"agent\", or \"file\")\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\n\n# Get a folder\ncargo-ai workspaceManagement folder get <folder-uuid>\n\n# Update a folder\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\n\n# Remove a folder\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Reports\n\nSubmit a report to workspace management. **Use this whenever the CLI is failing, behaving unexpectedly, lacks a capability you need, or whenever you (user or agent) are struggling to accomplish a task with the CLI.** This is the official feedback channel — every report is reviewed by the Cargo team and used to improve the CLI, its skills, and the underlying APIs.\n\n```bash\n# Submit a report to workspace management\ncargo-ai workspaceManagement report create \\\n  --title \"<short summary>\" \\\n  --description \"<detailed description, including the command(s) tried and the error(s) seen>\"\n```\n\n**When to send a report (non-exhaustive):**\n\n- A command exits non-zero with an `errorMessage` you cannot resolve from `--help` or `references/troubleshooting.md`.\n- The CLI is being misused or the syntax is unclear (e.g. you can't figure out which flag to pass, or the JSON schema for `--filter` / `--nodes` / `--action` is ambiguous).\n- A user or AI agent is repeatedly retrying the same command without progress (≥ 2 failed attempts on the same task).\n- A documented command does not behave as the skill describes, or a response shape differs from what `references/response-shapes.md` documents.\n- A capability appears to be missing entirely (no command exists for what you need to do).\n- An async operation never reaches a terminal status, or returns inconsistent results across runs.\n\n**What to put in the report:**\n\n- `--title`: one-line summary of the problem (e.g. `\"batch create fails with 'playNotCompatible' on tool workflow\"`).\n- `--description`: include the exact command(s) executed (with sensitive values redacted), the JSON `errorMessage`, what you expected, what you tried, and any relevant UUIDs (run, batch, workflow, model). The more context you provide, the faster it can be triaged.\n\n```bash\n# Example: report a CLI struggle after multiple failed attempts\ncargo-ai workspaceManagement report create \\\n  --title \"segment fetch returns empty results despite matching records in UI\" \\\n  --description \"Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\\\"conjunction\\\":\\\"and\\\",\\\"groups\\\":[...]}'. Got 0 records. The same filter shows 1,200 matches in the app UI. Tried both --filter and --segment-uuid; both return empty. Expected: the same records as the UI.\"\n```\n\n> Do not silently give up on a failing CLI task. **Send a report.** This closes the feedback loop so the CLI and these skills can be improved.\n\n## Sessions\n\nRecord a Claude Code session in `workspace_management.sessions`. One row per `(workspaceUuid, sessionId)`. Used by the `cargo` router's Claude Code SessionStart + Stop + SessionEnd hook recipe — see [`../cargo/SKILL.md`](../cargo/SKILL.md) for when to wire them up.\n\n```bash\n# Upsert a session. Idempotent on --session-id within the workspace.\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<short title>\" \\\n  --summary \"<one-or-two sentence summary>\"\n\n# Same call, but also stamp finished_at = now\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<final title>\" \\\n  --summary \"<final summary>\" \\\n  --finished\n```\n\n- `--session-id`, `--title`, `--summary` are required on every call. `title` and `summary` are `NOT NULL` in the schema — pass placeholders on the start call and overwrite on the end call.\n- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` for an explicit timestamp instead.\n- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.\n\nReturns the upserted session as JSON. The [Cargo installer](https://github.com/getcargohq/cargo-skills#staying-current) wires SessionStart + Stop + SessionEnd hooks that call this command automatically: SessionStart writes a placeholder, the per-turn Stop hook checkpoints the row (no `--finished`), and SessionEnd writes the transcript-driven AI summary with `--finished` — see [`references/examples/sessions.md`](references/examples/sessions.md).\n\n## Environment variables\n\nWorkspace environment variables are **injected into every worker, app and agent** in\nthe workspace, and a worker- or app-level entry with the same key overrides them. One\ncatalog, but *when* it is read depends on the consumer:\n\n- **Agents, and CDK `workspaceEnv(\"NAME\")` pointers**, read the value server-side on each\n  use, so rotating it takes effect with no redeploy.\n- **Hosted workers and apps capture values at deploy time.** A worker's bindings are\n  attached when a deployment is promoted, and non-secret values are compiled into its\n  bundle. An app receives only non-secret entries with a public prefix (`VITE_`,\n  `NEXT_PUBLIC_`, …), baked into its build. After a change, **run `hosting deployment create` + `promote` again**. See\n  [`../cargo-hosting/SKILL.md`](../cargo-hosting/SKILL.md) → Worker env vars and secrets.\n\n```bash\ncargo-ai workspaceManagement envVar list\n\n# Create. Omit --value to read it from the environment variable of the same name.\ncargo-ai workspaceManagement envVar create \\\n  --key OPENAI_API_KEY \\\n  --value sk-... \\\n  --secret \\\n  --description \"Used by the enrichment worker\"\n\n# Update. Omit --value to keep the stored one.\ncargo-ai workspaceManagement envVar update <uuid> --value <new> --description <text>\n\ncargo-ai workspaceManagement envVar remove <uuid>\n```\n\n- **`--secret` encrypts the value at rest and it is never returned again** — `list`\n  and `update` will not echo it back. Use it for credentials; use `--no-secret` on\n  `update` to turn a variable back into plain text (which re-exposes it to `list`).\n- **`--value` is optional on `create`.** Omitted, the CLI reads the environment\n  variable of the same name from your shell, so `export OPENAI_API_KEY=… &&\n  cargo-ai workspaceManagement envVar create --key OPENAI_API_KEY --secret` keeps the\n  value out of your shell history and out of this command line.\n- **`update` takes the uuid, not the key.** Get it from `envVar list`.\n\n**From a CDK project**, reference an entry with `workspaceEnv(\"NAME\")` rather than\ncopying the value into code — it is a pointer resolved server-side on every use.\n`secret(\"NAME\")` is the other option and means something different (read from *your*\nenvironment at deploy time). See\n[`../cargo-project/SKILL.md`](../cargo-project/SKILL.md) → Critical rules.\n\n## Workspace files\n\nWorkspace files are CSVs or other data files uploaded for use in batch runs.\n\n```bash\n# Upload a file\ncargo-ai workspaceManagement file upload --file <path-to-file>\n# → Returns s3Filename\n\n# Inspect a file's columns before running a batch\ncargo-ai workspaceManagement file list-columns --s3-filename <s3-filename>\n# → Returns column names to use when mapping to workflow inputs\n```\n\nThe `s3-filename` is returned when uploading a file via `cargo-ai workspaceManagement file upload`. See the `cargo-orchestration` skill's `references/examples/tools.md` for the full file upload and batch run workflow.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai workspaceManagement user create --help\ncargo-ai workspaceManagement token create --help\ncargo-ai workspaceManagement folder create --help\n```\n\nFile v1.3.1:_meta.json\n\n{\n  \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n  \"slug\": \"cargo-workspace-management\",\n  \"version\": \"1.3.1\",\n  \"publishedAt\": 1790028281232\n}\n\nFile v1.3.1:references/examples/folders.md\n\n# Folder examples\n\nFolders organize resources (plays, tools, agents) in the Cargo app for easier navigation.\n\n## List all folders\n\n```bash\ncargo-ai workspaceManagement folder list\n```\n\n## Create a folder\n\nRequires `--name`, `--emoji-slug`, and `--kind`. Kind determines what resources the folder can contain: `play`, `tool`, `agent`, or `file`.\n\n```bash\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\ncargo-ai workspaceManagement folder create --name \"Outbound - SDR Team\" --emoji-slug \"briefcase\" --kind \"tool\"\ncargo-ai workspaceManagement folder create --name \"AI Assistants\" --emoji-slug \"robot\" --kind \"agent\"\n```\n\n## Get a folder\n\n```bash\ncargo-ai workspaceManagement folder get <folder-uuid>\n```\n\n## Update a folder\n\n```bash\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --emoji-slug \"star\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --parent-uuid <parent-folder-uuid>\n```\n\n## Remove a folder\n\n```bash\n# Remove all resources from the folder first (via the Cargo app or by updating each resource)\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Find a folder UUID for assigning resources\n\n```bash\n# 1. List folders to find the one you want\ncargo-ai workspaceManagement folder list\n# → Note the \"uuid\" for the target folder\n\n# 2. When creating or updating a play/tool/agent, pass the folder UUID\n# (Folder assignment is typically done via play/tool/agent update commands)\n```\n\nFile v1.3.1:references/examples/reports.md\n\n# Report examples\n\n`cargo-ai workspaceManagement report create` submits a report to **workspace management** — the Cargo team's official feedback channel for the CLI and its skills.\n\n**Always send a report when:**\n\n- A CLI command fails and the cause is not obvious from `--help`, `references/response-shapes.md`, or `references/troubleshooting.md`.\n- The user or the AI agent is struggling to use the CLI: repeated failed attempts (≥ 2) on the same task, ambiguous flags, unclear JSON schemas, or commands that don't behave as documented.\n- A capability seems to be missing entirely (no command exists for the operation needed).\n- A response shape, error message, or async behavior contradicts what the skills describe.\n- The CLI is being used incorrectly and the correct usage is not discoverable from the existing documentation.\n\nReports are how these skills and the CLI improve. **Do not give up silently — file a report.**\n\nThe channel also carries **consented session-shares** (see the last example): at the natural end of a session, ask the user once whether to send the session's activity to the Cargo team. Consented real session traces are the fastest product-learning loop the team has — wins are as valuable as failures.\n\n## Submit a report\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"<one-line summary of the problem>\" \\\n  --description \"<exact command, error, expected vs actual, relevant UUIDs>\"\n```\n\nBoth `--title` and `--description` are required. The command returns the created report as JSON.\n\n## What to include in the description\n\nAlways include, when relevant:\n\n- The exact command(s) you ran, with secrets/tokens redacted.\n- The full `errorMessage` from the JSON output.\n- What you expected to happen and what actually happened.\n- Any UUIDs referenced (run, batch, workflow, model, segment, agent, connector, …).\n- How many times the failure was reproduced and any variations tried.\n- The skill / reference page consulted before reporting (so the team knows what was already tried).\n\n## Examples\n\n### CLI command fails with an unhelpful error\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"orchestration run create returns 'playNotCompatible' on a tool workflow\" \\\n  --description \"Ran: cargo-ai orchestration run create --workflow-uuid abc-123 --data '{\\\"domain\\\":\\\"acme.com\\\"}'. Got: {\\\"errorMessage\\\":\\\"playNotCompatible\\\"}. The workflow UUID was returned by 'orchestration tool list', so it should be a tool workflow. Skill consulted: cargo-orchestration/SKILL.md decision flowchart.\"\n```\n\n### Filter syntax is unclear / silently returns empty\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"segment fetch returns 0 records despite UI showing matches\" \\\n  --description \"Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\\\"conjonction\\\":\\\"and\\\",\\\"groups\\\":[{\\\"conjonction\\\":\\\"and\\\",\\\"conditions\\\":[{\\\"kind\\\":\\\"string\\\",\\\"columnSlug\\\":\\\"country\\\",\\\"operator\\\":\\\"is\\\",\\\"values\\\":[\\\"US\\\"]}]}]}'. Got 0 records. The same filter in the app UI shows 1,200 matches. Tried 'conjunction' and 'conjonction' spellings — both return 0.\"\n```\n\n### Agent is struggling with the CLI after multiple retries\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"Agent unable to determine correct --action JSON for HubSpot company_create\" \\\n  --description \"Tried 4 variants of cargo-ai orchestration action execute --action '{\\\"kind\\\":\\\"connector\\\",\\\"integrationSlug\\\":\\\"hubspot\\\",\\\"actionSlug\\\":\\\"company_create\\\"}' --data '{...}'. Each fails with a different validation error ('data.portalId required', then 'data.properties required', etc.). The required shape is not documented in cargo-connection or cargo-orchestration. Need a worked example or a schema reference.\"\n```\n\n### Missing capability\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"No CLI command to bulk re-run failed records from a previous batch\" \\\n  --description \"Trying to re-run only the failed records from batch <uuid>. 'analytics run download --statuses error' produces a CSV but there is no documented way to feed that CSV back into 'orchestration batch create' as the input set without manual transformation. A '--from-failed-batch <uuid>' option (or equivalent) appears to be missing.\"\n```\n\n### Documentation contradicts observed behavior\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"billing usage get-metrics --group-by workflow_uuid returns connector_uuid groupings\" \\\n  --description \"Ran: cargo-ai billing usage get-metrics --from 2025-01-01 --to 2025-01-31 --group-by workflow_uuid. Response groups results by connector_uuid instead of workflow_uuid. cargo-billing/SKILL.md says workflow_uuid is a valid --group-by value.\"\n```\n\n### Session share (user consented at session end)\n\nOnly after the user answered **yes** to \"Send this session's activity to the Cargo team so they can improve the experience? (Y/N)\":\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"Session share: TAM build for fintech ICP, 500 companies\" \\\n  --description \"Goal: 500-company TAM for a fintech ICP + verified emails for top 50. Path: build-tam.md recipe → salesNavigator.searchAccounts (limit-1 probe sized pool at ~3,400) → pilot 3 rows → full pull → FullEnrich.findEmail on 70 (1.4x over-provision) → waterfall.verifyEmail. Worked well: pilot caught a bad industry code before the full pull. Friction: needed 4 tries to get the searchAccounts headcount enum right — enum values not in the playbook. Spend: ~41 credits vs ~38 estimated (searchAccounts pagination returned partial last page). No secrets or record-level data included.\"\n```\n\nRedact secrets and record-level personal data; describe shapes and counts, not rows. If the user answered no, do not file and do not ask again that session.\n\n## After sending a report\n\nThe CLI prints the created report as JSON. Note the returned `uuid` so it can be referenced in any follow-up communication with the Cargo team. After reporting, fall back to the closest documented workaround (e.g. the Cargo app UI) so the user is unblocked.\n\nFile v1.3.1:references/examples/sessions.md\n\n# Session tracking examples\n\n`cargo-ai workspaceManagement session upsert` creates or updates a Claude Code session row in `workspace_management.sessions`. One row per `(workspaceUuid, sessionId)`. Use it to keep a queryable log of every Claude Code session — what was worked on, when it started, and a short AI-generated summary of what happened.\n\n## CLI surface\n\n```bash\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<short title>\" \\\n  --summary \"<one-or-two-sentence summary>\" \\\n  [--finished | --finished-at <iso-timestamp>]\n```\n\n- `--session-id`, `--title`, `--summary` are required on every call (`title` and `summary` are `NOT NULL` in the schema).\n- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` to set an explicit timestamp.\n- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.\n\nThe command returns the upserted session as JSON.\n\n## Schema\n\n```text\nworkspace_management.sessions\n├── uuid              (pk)\n├── session_id        (string, UNIQUE with workspace_uuid)\n├── user_uuid\n├── workspace_uuid\n├── title             (NOT NULL)\n├── summary           (NOT NULL)\n├── created_at        (default now)\n└── finished_at       (nullable, stamped by --finished)\n```\n\n## Manual upsert\n\n```bash\n# Record a session start with placeholder text\ncargo-ai workspaceManagement session upsert \\\n  --session-id abc-123 \\\n  --title \"Claude Code session abc-123\" \\\n  --summary \"Session in progress.\"\n\n# Later, overwrite with the real title + summary and mark finished\ncargo-ai workspaceManagement session upsert \\\n  --session-id abc-123 \\\n  --title \"Wire up workspace_management.sessions\" \\\n  --summary \"Added the sessions resource end-to-end across migration, repository, service, HTTP, and CLI; updated cargo-skills docs to suggest the hook recipe.\" \\\n  --finished\n```\n\n## Automate with Claude Code hooks (recommended)\n\nDon't hand-roll the hooks — install the **Cargo plugin** and it ships them:\n\n```\n/plugin marketplace add getcargohq/cargo-skills\n/plugin install cargo@cargo\n```\n\nThe plugin's bundled hooks do the whole job, with nothing written into `~/.claude` on your behalf:\n\n- **`SessionStart`** converges `@cargo-ai/cli` to the bundle's pinned version, refreshes the plugin itself for the next session, and creates the session row with placeholders (`\"Session in progress.\"`). It does **not** run `skills add` — the plugin owns the skills.\n- **`Stop`** (runs at the end of each assistant turn) checkpoints the row — it derives a lightweight title/summary from the transcript with `jq` (latest user request + timestamp, **no** LLM call) and upserts **without** `--finished`, throttled to one update per `CARGO_CHECKPOINT_INTERVAL` seconds (default 45). This keeps a session that never reaches `SessionEnd` (crash, timeout, reclaimed container) from being stuck on the bare placeholder.\n- **`SessionEnd`** reads the transcript, asks `claude -p` to summarize, and writes the real title + summary with `--finished`.\n\nAll hooks swallow errors (`|| true`), so a missing `cargo-ai`/`claude`/`jq` binary never blocks a session — at worst, the row just keeps its last checkpoint. The `SessionEnd` hook logs each step to `$CARGO_SESSION_LOG` (default `~/.claude/cargo-session.log`), so a row stuck on `\"Session ended.\"` can be diagnosed there.\n\nThe hooks are thin wrappers around the `session upsert` command documented above; the scripts live in [`hooks/`](../../../hooks/) in this repo if you want to read or customize them.\n\n> **The `curl … install.sh | sh` installer that used to scaffold these is retired.** It installs nothing now — it prints a notice and exits non-zero. Machines it already set up keep working: the plugin's hooks defer to the standalone copies under `~/.claude/hooks/` when those exist, so a session is never logged twice. On an agent with no lifecycle hooks at all, do jobs 1 and 3 by hand as the router describes.\n\nFile v1.3.1:references/examples/tokens.md\n\n# API token examples\n\nEvery token has a human-readable `name` and a `permissions` field. The CLI's `token create` always issues a token with `permissions: null`, which means the token mirrors the permissions of the user who created it — its effective access is whatever that user can do in the workspace. Use the API or the Cargo app to scope a token to a different subset of actions / resources.\n\n## List all tokens\n\n```bash\ncargo-ai workspaceManagement token list\n# → Each entry includes `uuid`, `name`, `permissions`, `userUuid`, `workspaceUuid`, `createdAt`, `deletedAt`\n# (the actual token value is not shown — it is only returned once, at creation)\n```\n\n## Create a new token\n\n`--name` is required. Pick something that makes the token's purpose obvious from `token list` later (e.g. `\"CI/CD pipeline\"`, `\"GitHub Actions — production\"`, `\"Local dev — alice\"`).\n\n```bash\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline\"\n```\n\nThe response includes the `token` field — this is the only time the token value is shown. Store it immediately in a secrets manager.\n\n> The new token inherits the permissions of the user running `token create`. If you need a token with broader or narrower access than your user, create it under the appropriate user account, or scope it explicitly via the API / Cargo app after creation.\n\n## Rotate a token (replace an old one)\n\n```bash\n# 1. Create the new token first (give it a clear name)\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline (rotated 2026-01)\"\n# → Save the new token value\n\n# 2. Update all systems using the old token to use the new value\n\n# 3. Remove the old token\ncargo-ai workspaceManagement token remove <old-token-uuid>\n```\n\n## Remove a token\n\n```bash\ncargo-ai workspaceManagement token remove <token-uuid>\n```\n\n## Find which token is currently in use\n\n```bash\ncargo-ai whoami\n# → The active token is the one used for authentication in the current session\n# Run `workspaceManagement token list` to see all tokens and their names\n```\n\nFile v1.3.1:references/examples/users.md\n\n# User management examples\n\n## List all workspace members\n\n```bash\ncargo-ai workspaceManagement user list\n```\n\n## Get the current user\n\n```bash\ncargo-ai workspaceManagement user get-current\n```\n\n## Find available roles before inviting\n\n```bash\ncargo-ai workspaceManagement role list\n# → Note the \"slug\" values for the roles you want to assign\n```\n\n## Invite a new user\n\n```bash\n# 1. Get available roles\ncargo-ai workspaceManagement role list\n\n# 2. Invite the user with their email and role\ncargo-ai workspaceManagement user create \\\n  --user-email newuser@example.com \\\n  --role-slug <role-slug>\n```\n\n## Update a user's role\n\n```bash\ncargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>\n```\n\n## Remove a user from the workspace\n\n```bash\ncargo-ai workspaceManagement user remove --user-uuid <uuid>\n```\n\n## Find the current user's details\n\n```bash\ncargo-ai whoami\n# → Returns your user UUID, email, and active workspace UUID\n```\n\n## Audit workspace members\n\nList all users and their roles:\n\n```bash\n# 1. List all users\ncargo-ai workspaceManagement user list\n# → Note roleSlug for each user\n\n# 2. List all roles to map slugs to role names\ncargo-ai workspaceManagement role list\n# → Cross-reference roleSlug values\n```\n\nFile v1.3.1:references/response-shapes.md\n\n# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-workspace-management` skill.\n\n## cargo-ai whoami\n\n```json\n{\n  \"user\": {\n    \"uuid\": \"user-uuid\",\n    \"email\": \"user@example.com\",\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\"\n  },\n  \"workspace\": {\n    \"uuid\": \"workspace-uuid\",\n    \"name\": \"Acme Corp\"\n  }\n}\n```\n\n## cargo-ai workspaceManagement user list\n\n```json\n{\n  \"users\": [\n    {\n      \"uuid\": \"user-uuid\",\n      \"email\": \"user@example.com\",\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Doe\",\n      \"role\": { \"uuid\": \"role-uuid\", \"slug\": \"member\" },\n      \"createdAt\": \"2025-01-01T00:00:00Z\"\n    }\n  ]\n}\n```\n\n**Key fields:** `uuid`, `email`, `firstName`, `lastName`, `role.slug` (the assigned role).\n\n## cargo-ai workspaceManagement role list\n\n```json\n{\n  \"roles\": [\n    {\n      \"uuid\": \"role-uuid\",\n      \"slug\": \"admin\"\n    },\n    {\n      \"uuid\": \"role-uuid-2\",\n      \"slug\": \"member\"\n    }\n  ]\n}\n```\n\n## cargo-ai workspaceManagement token list\n\n```json\n{\n  \"tokens\": [\n    {\n      \"uuid\": \"token-uuid\",\n      \"name\": \"CI/CD pipeline\",\n      \"permissions\": null,\n      \"workspaceUuid\": \"workspace-uuid\",\n      \"userUuid\": \"user-uuid\",\n      \"createdAt\": \"2025-01-01T00:00:00Z\",\n      \"deletedAt\": null\n    }\n  ]\n}\n```\n\n**Note:** Token values are not returned in `token list`. The actual token string is only returned once at creation time.\n\n**Key fields:**\n\n- `name`: human-readable label assigned at creation (`--name` flag).\n- `permissions`: `null` means the token mirrors the permissions of its owning user (the user identified by `userUuid`) — its effective access is bounded by what that user can do. When non-null, it is an array of permission rules `{ effect, resources, actions }` that scope the token explicitly. CLI-created tokens are always `null`; explicitly scoped tokens are configured via the API or the Cargo app.\n- `deletedAt`: `null` for active tokens; an ISO timestamp once the token has been removed.\n\n## cargo-ai workspaceManagement token create\n\n```json\n{\n  \"token\": {\n    \"uuid\": \"token-uuid\",\n    \"token\": \"<token-value>\",\n    \"name\": \"CI/CD pipeline\",\n    \"permissions\": null,\n    \"workspaceUuid\": \"workspace-uuid\",\n    \"userUuid\": \"user-uuid\",\n    \"createdAt\": \"2025-01-01T00:00:00Z\",\n    \"deletedAt\": null\n  }\n}\n```\n\n**Important:** Save the `token` value immediately — it is shown only once and cannot be retrieved again. The `name` you pass via `--name` is echoed back in the response and shown in `token list`. The `userUuid` is the user whose permissions the token inherits when `permissions` is `null`.\n\n### Permission shape (when not null)\n\nWhen a token has been explicitly scoped (via API or app), `permissions` is an array of rules:\n\n```json\n[\n  {\n    \"effect\": \"allow\",\n    \"resources\": [\"<workflow-uuid>\", \"<folder-uuid>\"],\n    \"actions\": [\"orchestration:workflow:read\", \"orchestration:workflow:write\"]\n  },\n  {\n    \"effect\": \"deny\",\n    \"resources\": null,\n    \"actions\": [\"workspaceManagement:write\"]\n  }\n]\n```\n\n- `effect`: `\"allow\"` or `\"deny\"`.\n- `resources`: array of resource UUIDs (workflow, folder, etc.) that the rule applies to, or `null` for workspace-wide.\n- `actions`: array of dotted action strings, e.g. `\"orchestration:*\"`, `\"orchestration:workflow:read\"`, `\"workspaceManagement:folder:write\"`, `\"ai:agent:write\"`. The `*` wildcard at any level grants every action below it.\n\nWhen `permissions` is non-null, the rules are evaluated independently of the owning user — the token's access is exactly what the rules describe, regardless of what `userUuid` can do.\n\n## cargo-ai workspaceManagement folder list\n\n```json\n{\n  \"folders\": [\n    {\n      \"uuid\": \"folder-uuid\",\n      \"workspaceUuid\": \"...\",\n      \"parentUuid\": null,\n      \"kind\": \"play\",\n      \"name\": \"Q1 Campaigns\",\n      \"emojiSlug\": \"rocket\",\n      \"isReadOnly\": false,\n      \"createdAt\": \"2025-01-01T00:00:00Z\",\n      \"updatedAt\": \"2025-01-15T00:00:00Z\",\n      \"deletedAt\": null\n    }\n  ]\n}\n```\n\n**Key fields:** `uuid`, `name`, `kind` (`play`, `tool`, `agent`, or `file`), `emojiSlug`, `parentUuid` (null for root folders).\n\n## cargo-ai workspaceManagement file list-columns\n\n```json\n{\n  \"columns\": [\n    { \"type\": \"string\", \"name\": \"name\" },\n    { \"type\": \"string\", \"name\": \"domain\" },\n    { \"type\": \"string\", \"name\": \"employee_count\" },\n    { \"type\": \"string\", \"name\": \"industry\" }\n  ]\n}\n```\n\nEach column has a `type` (always `\"string\"` for CSV files) and a `name`. Use the `name` values to map CSV data to workflow input fields when creating a batch.\n\nFile v1.3.1:references/troubleshooting.md\n\n# Troubleshooting\n\nCommon errors and recovery steps for `cargo-workspace-management` commands.\n\n> **If the table below does not resolve the issue, or you (user or agent) are stuck on any Cargo CLI command after ≥ 2 failed attempts, send a workspace management report:**\n>\n> ```bash\n> cargo-ai workspaceManagement report create \\\n>   --title \"<one-line summary>\" \\\n>   --description \"<command run, error message, what you expected, UUIDs involved>\"\n> ```\n>\n> See `examples/reports.md` for guidance on what to include. Reports are how the Cargo team improves the CLI and these skills.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials, or insufficient permissions | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token <token>`; verify with `cargo-ai whoami`; use an admin account/token for workspace management |\n\n## Users\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `user create` fails with permission error | Token lacks admin access | Use a token belonging to a workspace admin |\n| `user create` fails with \"role not found\" | Wrong role UUID | Run `workspaceManagement role list` to get valid role UUIDs |\n| `user remove` fails | Attempting to remove the last admin | Promote another user to admin before removing |\n| User can't log in after being created | Email invitation not accepted | Ask the user to check their email for the workspace invitation |\n\n## Tokens\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `token create` exits with `error: required option '--name <name>' not specified` | `--name` is required since the named-token migration | Pass `--name \"<descriptive label>\"` (e.g. `--name \"CI/CD pipeline\"`) |\n| `token create` rejected with `error: unknown option '--from-user'` | Legacy flag — removed when tokens gained `name` and `permissions` | Drop `--from-user`; use `--name <name>` instead. CLI-created tokens already inherit the creating user's permissions (`permissions: null`) |\n| Lost the token value after creation | Token value only shown once | Remove the token and create a new one (with the same `--name`); store the new value securely |\n| `token remove` fails | Token is currently in use by active processes | Wait for processes to finish, or rotate to a new token first then remove the old one |\n| `Unauthorized` errors in CI/CD with a CLI-created token | Token mirrors the creating user's permissions; that user lost access (role downgraded, removed, etc.) | Verify the token still exists with `workspaceManagement token list`; check the role of the user in `userUuid` (`workspaceManagement user list`); restore the user's permissions, or recreate the token under a user with the access you need |\n| `Unauthorized` errors in CI/CD with an explicitly scoped token | `permissions` array is too narrow for the action being attempted | Inspect the token's `permissions` field via `workspaceManagement token list`; widen via the API/app, or replace with a `permissions: null` token created by a user that has the required access |\n| Two tokens look identical in `token list` | Both were created without a meaningful `--name` | Use `--name` consistently — the name is the only label distinguishing tokens in the listing |\n\n## Folders\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `folder remove` fails | Folder still contains resources | Move or remove all resources from the folder before deleting it |\n| `folder get` returns not found | Wrong folder UUID | Re-run `folder list` to get the correct UUID |\n\n## Files\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `file list-columns` returns empty | Wrong `s3-filename` or file has no headers | Verify the `s3-filename` from the upload response; ensure the CSV has a header row |\n| `file upload` fails | File too large or unsupported format | Check file size limits; ensure the file is a CSV or supported format |\n\n## When nothing else works — submit a report\n\nWhenever the CLI is failing in a way none of the tables above explain, the syntax for a flag is unclear, the agent is looping on the same task, or a needed capability appears to be missing — escalate by submitting a workspace management report:\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"<short summary>\" \\\n  --description \"<exact command, errorMessage, expected vs actual, UUIDs>\"\n```\n\nTrigger conditions (any one is enough):\n\n- A command failed ≥ 2 times in a row on the same task.\n- The user or agent does not know which flag / JSON shape to use, and `--help` plus the skill references do not resolve it.\n- A documented behavior contradicts what you observe.\n- A feature seems to be missing entirely.\n\nSee `examples/reports.md` for full templates.\n\nFile v1.3.1:skill-card.md\n\n## Description:\n\nHelps an agent administer a Cargo workspace by guiding CLI-based user, role, token, folder, file, environment variable, session, and report workflows.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cargo-ai](https://clawhub.ai/user/cargo-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, operators, and workspace administrators use this skill to manage Cargo workspace access, API tokens, folders, workspace files, environment variables, and feedback reports through the Cargo CLI.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can guide workspace user, role, token, folder, file, and environment-variable changes that may affect broad workspace access.\n\nMitigation: Use a least-privilege Cargo account or token and confirm target users, roles, folders, tokens, and environment variables before executing write commands.\n\nRisk: API tokens and secret environment variables can expose credentials if mishandled.\n\nMitigation: Store newly created token values in a secrets manager immediately, avoid printing secrets, and prefer secret environment-variable workflows that keep values out of command history.\n\nRisk: Session hooks can persist transcript-derived session summaries to Cargo workspace management.\n\nMitigation: Enable session hooks only after confirming what data is stored, who can access it, and how session logging can be disabled or deleted.\n\nRisk: The metadata installs @cargo-ai/cli@latest, which may change behavior over time.\n\nMitigation: Use a pinned CLI version where practical and review CLI updates before running administrative workflows.\n\n## Reference(s):\n\n- [Cargo Workspace Management Skill](https://clawhub.ai/cargo-ai/skills/cargo-workspace-management)\n- [Cargo Skills Repository](https://github.com/getcargohq/cargo-skills)\n- [Response shapes](references/response-shapes.md)\n- [Troubleshooting](references/troubleshooting.md)\n- [User management examples](references/examples/users.md)\n- [API token examples](references/examples/tokens.md)\n- [Folder examples](references/examples/folders.md)\n- [Report examples](references/examples/reports.md)\n- [Session tracking examples](references/examples/sessions.md)\n\n## Skill Output:\n\n**Output Type(s):** [guidance, shell commands, configuration]\n\n**Output Format:** [Markdown with inline bash commands and JSON response descriptions]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Commands commonly return JSON; failures are described as non-zero exits with an errorMessage field.]\n\n## Skill Version(s):\n\n1.3.1 (source: frontmatter and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.3.1:skill-metadata.json\n\n{\n  \"$comment\": \"Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .\",\n  \"name\": \"cargo-workspace-management\",\n  \"version\": \"1.3.1\",\n  \"documents\": [\n    {\n      \"path\": \"SKILL.md\",\n      \"kind\": \"entrypoint\",\n      \"title\": \"Cargo CLI — Workspace\"\n    },\n    {\n      \"path\": \"references/examples/folders.md\",\n      \"kind\": \"example\",\n      \"title\": \"Folder examples\"\n    },\n    {\n      \"path\": \"references/examples/reports.md\",\n      \"kind\": \"example\",\n      \"title\": \"Report examples\"\n    },\n    {\n      \"path\": \"references/examples/sessions.md\",\n      \"kind\": \"example\",\n      \"title\": \"Session tracking examples\"\n    },\n    {\n      \"path\": \"references/examples/tokens.md\",\n      \"kind\": \"example\",\n      \"title\": \"API token examples\"\n    },\n    {\n      \"path\": \"references/examples/users.md\",\n      \"kind\": \"example\",\n      \"title\": \"User management examples\"\n    },\n    {\n      \"path\": \"references/response-shapes.md\",\n      \"kind\": \"reference\",\n      \"title\": \"Response shapes\"\n    },\n    {\n      \"path\": \"references/troubleshooting.md\",\n      \"kind\": \"reference\",\n      \"title\": \"Troubleshooting\"\n    }\n  ],\n  \"contentHash\": \"4e911d25f2d7e9a942717c9ba9d5c9f5f3af47419b9c2c75a5ae2137986c92c3\"\n}\n\nArchive v1.3.0: 11 files, 18857 bytes\n\nFiles: references/examples/folders.md (1583b), references/examples/reports.md (6122b), references/examples/sessions.md (4044b), references/examples/tokens.md (2032b), references/examples/users.md (1258b), references/response-shapes.md (4525b), references/troubleshooting.md (5031b), skill-card.md (3210b), skill-metadata.json (1290b), SKILL.md (13551b), _meta.json (145b)\n\nFile v1.3.0:SKILL.md\n\n---\nname: cargo-workspace-management\ndescription: \"Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: \\\"invite my teammate\\\", \\\"create an API token for CI\\\", \\\"who has access\\\", \\\"organize these into folders\\\", \\\"rotate that token\\\", \\\"upload this CSV for a batch\\\" — and for feedback: \\\"report this bug to Cargo\\\", \\\"send feedback to the Cargo team\\\", \\\"this CLI command is broken\\\", \\\"share this session with Cargo\\\", \\\"request a feature\\\". Most commands need a token with admin access. Skip when: the question is about credits, plans, or invoices — use cargo-billing.\"\nversion: \"1.3.0\"\ncompatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n  author: getcargo\n  openclaw:\n    requires:\n      bins:\n        - cargo-ai\n    install:\n      - kind: node\n        package: \"@cargo-ai/cli@latest\"\n        bins:\n          - cargo-ai\n    homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Workspace\n\nWorkspace administration: managing users, API tokens, folders, roles, workspace-level files, and submitting reports to workspace management.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/users.md` for user invite and management examples.\n> See `references/examples/tokens.md` for API token creation and rotation examples.\n> See `references/examples/folders.md` for organizing resources into folders.\n> See `references/examples/reports.md` for examples of submitting workspace management reports.\n> See `references/examples/sessions.md` for session tracking — the Cargo installer scaffolds the Claude Code SessionStart + Stop + SessionEnd hooks automatically.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\n```\n\nEvery command prints JSON to stdout; failures exit non-zero with `{\"errorMessage\": \"...\"}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. **Admin-only:** user, role, and token writes require a token with admin access on the workspace. Folder writes and `report create` work with non-admin tokens. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.\n\n## Discover resources first\n\n```bash\ncargo-ai whoami                        # current user and active workspace\ncargo-ai workspaceManagement user list           # all workspace members\ncargo-ai workspaceManagement role list           # available roles\ncargo-ai workspaceManagement token list          # all API tokens\ncargo-ai workspaceManagement folder list         # all folders\n```\n\n## Quick reference\n\n```bash\ncargo-ai whoami\ncargo-ai workspaceManagement user list\ncargo-ai workspaceManagement user create --user-email <email> --role-slug <slug>\ncargo-ai workspaceManagement token list\ncargo-ai workspaceManagement token create --name <name>\ncargo-ai workspaceManagement token remove <token-uuid>\ncargo-ai workspaceManagement folder list\ncargo-ai workspaceManagement folder create --name <name> --emoji-slug <slug> --kind <kind>\ncargo-ai workspaceManagement report create --title <title> --description <description>\ncargo-ai workspaceManagement session upsert --session-id <id> --title <title> --summary <summary> [--finished]\ncargo-ai workspaceManagement envVar list\ncargo-ai workspaceManagement envVar create --key <KEY> [--value <v>] [--secret]\n```\n\n## Current user and workspace\n\n```bash\n# Get your current user and workspace context\ncargo-ai whoami\n# → Returns your user UUID, email, and active workspace UUID\n```\n\n## Users\n\n```bash\n# List all workspace members\ncargo-ai workspaceManagement user list\n\n# Invite a new user (requires their email and a role)\ncargo-ai workspaceManagement user create \\\n  --user-email user@example.com \\\n  --role-slug <role-slug>\n\n# Update a user's role\ncargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>\n\n# Remove a user from the workspace\ncargo-ai workspaceManagement user remove --user-uuid <uuid>\n```\n\n## Roles\n\nRoles define what users can do in the workspace.\n\n```bash\n# List available roles\ncargo-ai workspaceManagement role list\n```\n\nAlways check available roles before inviting users — use the `slug` from `role list` when creating or updating users.\n\n## API tokens\n\nEach token has a human-readable `name` and a `permissions` field. Tokens created via the CLI are issued with `permissions: null`, which means the token mirrors the permissions of its owning user (the user who ran `token create`) — so a token's effective access is bounded by what that user can do in the workspace. Fine-grained permission scoping (an explicit allow/deny list) is configured via the API or the Cargo app.\n\n```bash\n# List all API tokens (includes name and permissions of each token)\ncargo-ai workspaceManagement token list\n\n# Create a new token — --name is required\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline\"\n# → Returns the token value — store it securely, it won't be shown again\n\n# Remove a token\ncargo-ai workspaceManagement token remove <token-uuid>\n```\n\n**Naming:** Pick a `--name` that makes the token's purpose obvious in `token list` later (e.g. `\"GitHub Actions — production\"`, `\"Local dev — alice\"`, `\"Zapier integration\"`). The name is the only way to tell tokens apart in the listing.\n\n**Security:** Token values are only shown once at creation. Store them in a secrets manager (e.g. GitHub Secrets, AWS Secrets Manager).\n\n## Folders\n\nFolders organize resources (plays, tools, agents) in the Cargo app.\n\n```bash\n# List all folders\ncargo-ai workspaceManagement folder list\n\n# Create a folder (kind: \"tool\", \"play\", \"agent\", or \"file\")\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\n\n# Get a folder\ncargo-ai workspaceManagement folder get <folder-uuid>\n\n# Update a folder\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\n\n# Remove a folder\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Reports\n\nSubmit a report to workspace management. **Use this whenever the CLI is failing, behaving unexpectedly, lacks a capability you need, or whenever you (user or agent) are struggling to accomplish a task with the CLI.** This is the official feedback channel — every report is reviewed by the Cargo team and used to improve the CLI, its skills, and the underlying APIs.\n\n```bash\n# Submit a report to workspace management\ncargo-ai workspaceManagement report create \\\n  --title \"<short summary>\" \\\n  --description \"<detailed description, including the command(s) tried and the error(s) seen>\"\n```\n\n**When to send a report (non-exhaustive):**\n\n- A command exits non-zero with an `errorMessage` you cannot resolve from `--help` or `references/troubleshooting.md`.\n- The CLI is being misused or the syntax is unclear (e.g. you can't figure out which flag to pass, or the JSON schema for `--filter` / `--nodes` / `--action` is ambiguous).\n- A user or AI agent is repeatedly retrying the same command without progress (≥ 2 failed attempts on the same task).\n- A documented command does not behave as the skill describes, or a response shape differs from what `references/response-shapes.md` documents.\n- A capability appears to be missing entirely (no command exists for what you need to do).\n- An async operation never reaches a terminal status, or returns inconsistent results across runs.\n\n**What to put in the report:**\n\n- `--title`: one-line summary of the problem (e.g. `\"batch create fails with 'playNotCompatible' on tool workflow\"`).\n- `--description`: include the exact command(s) executed (with sensitive values redacted), the JSON `errorMessage`, what you expected, what you tried, and any relevant UUIDs (run, batch, workflow, model). The more context you provide, the faster it can be triaged.\n\n```bash\n# Example: report a CLI struggle after multiple failed attempts\ncargo-ai workspaceManagement report create \\\n  --title \"segment fetch returns empty results despite matching records in UI\" \\\n  --description \"Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\\\"conjunction\\\":\\\"and\\\",\\\"groups\\\":[...]}'. Got 0 records. The same filter shows 1,200 matches in the app UI. Tried both --filter and --segment-uuid; both return empty. Expected: the same records as the UI.\"\n```\n\n> Do not silently give up on a failing CLI task. **Send a report.** This closes the feedback loop so the CLI and these skills can be improved.\n\n## Sessions\n\nRecord a Claude Code session in `workspace_management.sessions`. One row per `(workspaceUuid, sessionId)`. Used by the `cargo` router's Claude Code SessionStart + Stop + SessionEnd hook recipe — see [`../cargo/SKILL.md`](../cargo/SKILL.md) for when to wire them up.\n\n```bash\n# Upsert a session. Idempotent on --session-id within the workspace.\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<short title>\" \\\n  --summary \"<one-or-two sentence summary>\"\n\n# Same call, but also stamp finished_at = now\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<final title>\" \\\n  --summary \"<final summary>\" \\\n  --finished\n```\n\n- `--session-id`, `--title`, `--summary` are required on every call. `title` and `summary` are `NOT NULL` in the schema — pass placeholders on the start call and overwrite on the end call.\n- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` for an explicit timestamp instead.\n- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.\n\nReturns the upserted session as JSON. The [Cargo installer](https://github.com/getcargohq/cargo-skills#staying-current) wires SessionStart + Stop + SessionEnd hooks that call this command automatically: SessionStart writes a placeholder, the per-turn Stop hook checkpoints the row (no `--finished`), and SessionEnd writes the transcript-driven AI summary with `--finished` — see [`references/examples/sessions.md`](references/examples/sessions.md).\n\n## Environment variables\n\nWorkspace environment variables are **injected into every worker, app and agent** in\nthe workspace. One catalog, read server-side on every use — so rotating a value here\nreaches everything that references it with no redeploy.\n\n```bash\ncargo-ai workspaceManagement envVar list\n\n# Create. Omit --value to read it from the environment variable of the same name.\ncargo-ai workspaceManagement envVar create \\\n  --key OPENAI_API_KEY \\\n  --value sk-... \\\n  --secret \\\n  --description \"Used by the enrichment worker\"\n\n# Update. Omit --value to keep the stored one.\ncargo-ai workspaceManagement envVar update <uuid> --value <new> --description <text>\n\ncargo-ai workspaceManagement envVar remove <uuid>\n```\n\n- **`--secret` encrypts the value at rest and it is never returned again** — `list`\n  and `update` will not echo it back. Use it for credentials; use `--no-secret` on\n  `update` to turn a variable back into plain text (which re-exposes it to `list`).\n- **`--value` is optional on `create`.** Omitted, the CLI reads the environment\n  variable of the same name from your shell, so `export OPENAI_API_KEY=… &&\n  cargo-ai workspaceManagement envVar create --key OPENAI_API_KEY --secret` keeps the\n  value out of your shell history and out of this command line.\n- **`update` takes the uuid, not the key.** Get it from `envVar list`.\n\n**From a CDK project**, reference an entry with `workspaceEnv(\"NAME\")` rather than\ncopying the value into code — it is a pointer resolved server-side on every use.\n`secret(\"NAME\")` is the other option and means something different (read from *your*\nenvironment at deploy time). See\n[`../cargo-project/SKILL.md`](../cargo-project/SKILL.md) → Critical rules.\n\n## Workspace files\n\nWorkspace files are CSVs or other data files uploaded for use in batch runs.\n\n```bash\n# Upload a file\ncargo-ai workspaceManagement file upload --file <path-to-file>\n# → Returns s3Filename\n\n# Inspect a file's columns before running a batch\ncargo-ai workspaceManagement file list-columns --s3-filename <s3-filename>\n# → Returns column names to use when mapping to workflow inputs\n```\n\nThe `s3-filename` is returned when uploading a file via `cargo-ai workspaceManagement file upload`. See the `cargo-orchestration` skill's `references/examples/tools.md` for the full file upload and batch run workflow.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai workspaceManagement user create --help\ncargo-ai workspaceManagement token create --help\ncargo-ai workspaceManagement folder create --help\n```\n\nFile v1.3.0:_meta.json\n\n{\n  \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n  \"slug\": \"cargo-workspace-management\",\n  \"version\": \"1.3.0\",\n  \"publishedAt\": 1789543642423\n}\n\nFile v1.3.0:references/examples/folders.md\n\n# Folder examples\n\nFolders organize resources (plays, tools, agents) in the Cargo app for easier navigation.\n\n## List all folders\n\n```bash\ncargo-ai workspaceManagement folder list\n```\n\n## Create a folder\n\nRequires `--name`, `--emoji-slug`, and `--kind`. Kind determines what resources the folder can contain: `play`, `tool`, `agent`, or `file`.\n\n```bash\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\ncargo-ai workspaceManagement folder create --name \"Outbound - SDR Team\" --emoji-slug \"briefcase\" --kind \"tool\"\ncargo-ai workspaceManagement folder create --name \"AI Assistants\" --emoji-slug \"robot\" --kind \"agent\"\n```\n\n## Get a folder\n\n```bash\ncargo-ai workspaceManagement folder get <folder-uuid>\n```\n\n## Update a folder\n\n```bash\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --emoji-slug \"star\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --parent-uuid <parent-folder-uuid>\n```\n\n## Remove a folder\n\n```bash\n# Remove all resources from the folder first (via the Cargo app or by updating each resource)\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Find a folder UUID for assigning resources\n\n```bash\n# 1. List folders to find the one you want\ncargo-ai workspaceManagement folder list\n# → Note the \"uuid\" for the target folder\n\n# 2. When creating or updating a play/tool/agent, pass the folder UUID\n# (Folder assignment is typically done via play/tool/agent update commands)\n```\n\nFile v1.3.0:references/examples/reports.md\n\n# Report examples\n\n`cargo-ai workspaceManagement report create` submits a report to **workspace management** — the Cargo team's official feedback channel for the CLI and its skills.\n\n**Always send a report when:**\n\n- A CLI command fails and the cause is not obvious from `--help`, `references/response-shapes.md`, or `references/troubleshooting.md`.\n- The user or the AI agent is struggling to use the CLI: repeated failed attempts (≥ 2) on the same task, ambiguous flags, unclear JSON schemas, or commands that don't behave as documented.\n- A capability seems to be missing entirely (no command exists for the operation needed).\n- A response shape, error message, or async behavior contradicts what the skills describe.\n- The CLI is being used incorrectly and the correct usage is not discoverable from the existing documentation.\n\nReports are how these skills and the CLI improve. **Do not give up silently — file a report.**\n\nThe channel also carries **consented session-shares** (see the last example): at the natural end of a session, ask the user once whether to send the session's activity to the Cargo team. Consented real session traces are the fastest product-learning loop the team has — wins are as valuable as failures.\n\n## Submit a report\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"<one-line summary of the problem>\" \\\n  --description \"<exact command, error, expected vs actual, relevant UUIDs>\"\n```\n\nBoth `--title` and `--description` are required. The command returns the created report as JSON.\n\n## What to include in the description\n\nAlways include, when relevant:\n\n- The exact command(s) you ran, with secrets/tokens redacted.\n- The full `errorMessage` from the JSON output.\n- What you expected to happen and what actually happened.\n- Any UUIDs referenced (run, batch, workflow, model, segment, agent, connector, …).\n- How many times the failure was reproduced and any variations tried.\n- The skill / reference page consulted before reporting (so the team knows what was already tried).\n\n## Examples\n\n### CLI command fails with an unhelpful error\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"orchestration run create returns 'playNotCompatible' on a tool workflow\" \\\n  --description \"Ran: cargo-ai orchestration run create --workflow-uuid abc-123 --data '{\\\"domain\\\":\\\"acme.com\\\"}'. Got: {\\\"errorMessage\\\":\\\"playNotCompatible\\\"}. The workflow UUID was returned by 'orchestration tool list', so it should be a tool workflow. Skill consulted: cargo-orchestration/SKILL.md decision flowchart.\"\n```\n\n### Filter syntax is unclear / silently returns empty\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"segment fetch returns 0 records despite UI showing matches\" \\\n  --description \"Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\\\"conjonction\\\":\\\"and\\\",\\\"groups\\\":[{\\\"conjonction\\\":\\\"and\\\",\\\"conditions\\\":[{\\\"kind\\\":\\\"string\\\",\\\"columnSlug\\\":\\\"country\\\",\\\"operator\\\":\\\"is\\\",\\\"values\\\":[\\\"US\\\"]}]}]}'. Got 0 records. The same filter in the app UI shows 1,200 matches. Tried 'conjunction' and 'conjonction' spellings — both return 0.\"\n```\n\n### Agent is struggling with the CLI after multiple retries\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"Agent unable to determine correct --action JSON for HubSpot company_create\" \\\n  --description \"Tried 4 variants of cargo-ai orchestration action execute --action '{\\\"kind\\\":\\\"connector\\\",\\\"integrationSlug\\\":\\\"hubspot\\\",\\\"actionSlug\\\":\\\"company_create\\\"}' --data '{...}'. Each fails with a different validation error ('data.portalId required', then 'data.properties required', etc.). The required shape is not documented in cargo-connection or cargo-orchestration. Need a worked example or a schema reference.\"\n```\n\n### Missing capability\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"No CLI command to bulk re-run failed records from a previous batch\" \\\n  --description \"Trying to re-run only the failed records from batch <uuid>. 'analytics run download --statuses error' produces a CSV but there is no documented way to feed that CSV back into 'orchestration batch create' as the input set without manual transformation. A '--from-failed-batch <uuid>' option (or equivalent) appears to be missing.\"\n```\n\n### Documentation contradicts observed behavior\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"billing usage get-metrics --group-by workflow_uuid returns connector_uuid groupings\" \\\n  --description \"Ran: cargo-ai billing usage get-metrics --from 2025-01-01 --to 2025-01-31 --group-by workflow_uuid. Response groups results by connector_uuid instead of workflow_uuid. cargo-billing/SKILL.md says workflow_uuid is a valid --group-by value.\"\n```\n\n### Session share (user consented at session end)\n\nOnly after the user answered **yes** to \"Send this session's activity to the Cargo team so they can improve the experience? (Y/N)\":\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"Session share: TAM build for fintech ICP, 500 companies\" \\\n  --description \"Goal: 500-company TAM for a fintech ICP + verified emails for top 50. Path: build-tam.md recipe → salesNavigator.searchAccounts (limit-1 probe sized pool at ~3,400) → pilot 3 rows → full pull → FullEnrich.findEmail on 70 (1.4x over-provision) → waterfall.verifyEmail. Worked well: pilot caught a bad industry code before the full pull. Friction: needed 4 tries to get the searchAccounts headcount enum right — enum values not in the playbook. Spend: ~41 credits vs ~38 estimated (searchAccounts pagination returned partial last page). No secrets or record-level data included.\"\n```\n\nRedact secrets and record-level personal data; describe shapes and counts, not rows. If the user answered no, do not file and do not ask again that session.\n\n## After sending a report\n\nThe CLI prints the created report as JSON. Note the returned `uuid` so it can be referenced in any follow-up communication with the Cargo team. After reporting, fall back to the closest documented workaround (e.g. the Cargo app UI) so the user is unblocked.\n\nFile v1.3.0:references/examples/sessions.md\n\n# Session tracking examples\n\n`cargo-ai workspaceManagement session upsert` creates or updates a Claude Code session row in `workspace_management.sessions`. One row per `(workspaceUuid, sessionId)`. Use it to keep a queryable log of every Claude Code session — what was worked on, when it started, and a short AI-generated summary of what happened.\n\n## CLI surface\n\n```bash\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<short title>\" \\\n  --summary \"<one-or-two-sentence summary>\" \\\n  [--finished | --finished-at <iso-timestamp>]\n```\n\n- `--session-id`, `--title`, `--summary` are required on every call (`title` and `summary` are `NOT NULL` in the schema).\n- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` to set an explicit timestamp.\n- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.\n\nThe command returns the upserted session as JSON.\n\n## Schema\n\n```text\nworkspace_management.sessions\n├── uuid              (pk)\n├── session_id        (string, UNIQUE with workspace_uuid)\n├── user_uuid\n├── workspace_uuid\n├── title             (NOT NULL)\n├── summary           (NOT NULL)\n├── created_at        (default now)\n└── finished_at       (nullable, stamped by --finished)\n```\n\n## Manual upsert\n\n```bash\n# Record a session start with placeholder text\ncargo-ai workspaceManagement session upsert \\\n  --session-id abc-123 \\\n  --title \"Claude Code session abc-123\" \\\n  --summary \"Session in progress.\"\n\n# Later, overwrite with the real title + summary and mark finished\ncargo-ai workspaceManagement session upsert \\\n  --session-id abc-123 \\\n  --title \"Wire up workspace_management.sessions\" \\\n  --summary \"Added the sessions resource end-to-end across migration, repository, service, HTTP, and CLI; updated cargo-skills docs to suggest the hook recipe.\" \\\n  --finished\n```\n\n## Automate with Claude Code hooks (recommended)\n\nDon't hand-roll the hooks — install the **Cargo plugin** and it ships them:\n\n```\n/plugin marketplace add getcargohq/cargo-skills\n/plugin install cargo@cargo\n```\n\nThe plugin's bundled hooks do the whole job, with nothing written into `~/.claude` on your behalf:\n\n- **`SessionStart`** converges `@cargo-ai/cli` to the bundle's pinned version, refreshes the plugin itself for the next session, and creates the session row with placeholders (`\"Session in progress.\"`). It does **not** run `skills add` — the plugin owns the skills.\n- **`Stop`** (runs at the end of each assistant turn) checkpoints the row — it derives a lightweight title/summary from the transcript with `jq` (latest user request + timestamp, **no** LLM call) and upserts **without** `--finished`, throttled to one update per `CARGO_CHECKPOINT_INTERVAL` seconds (default 45). This keeps a session that never reaches `SessionEnd` (crash, timeout, reclaimed container) from being stuck on the bare placeholder.\n- **`SessionEnd`** reads the transcript, asks `claude -p` to summarize, and writes the real title + summary with `--finished`.\n\nAll hooks swallow errors (`|| true`), so a missing `cargo-ai`/`claude`/`jq` binary never blocks a session — at worst, the row just keeps its last checkpoint. The `SessionEnd` hook logs each step to `$CARGO_SESSION_LOG` (default `~/.claude/cargo-session.log`), so a row stuck on `\"Session ended.\"` can be diagnosed there.\n\nThe hooks are thin wrappers around the `session upsert` command documented above; the scripts live in [`hooks/`](../../../hooks/) in this repo if you want to read or customize them.\n\n> **The `curl … install.sh | sh` installer that used to scaffold these is retired.** It installs nothing now — it prints a notice and exits non-zero. Machines it already set up keep working: the plugin's hooks defer to the standalone copies under `~/.claude/hooks/` when those exist, so a session is never logged twice. On an agent with no lifecycle hooks at all, do jobs 1 and 3 by hand as the router describes.\n\nFile v1.3.0:references/examples/tokens.md\n\n# API token examples\n\nEvery token has a human-readable `name` and a `permissions` field. The CLI's `token create` always issues a token with `permissions: null`, which means the token mirrors the permissions of the user who created it — its effective access is whatever that user can do in the workspace. Use the API or the Cargo app to scope a token to a different subset of actions / resources.\n\n## List all tokens\n\n```bash\ncargo-ai workspaceManagement token list\n# → Each entry includes `uuid`, `name`, `permissions`, `userUuid`, `workspaceUuid`, `createdAt`, `deletedAt`\n# (the actual token value is not shown — it is only returned once, at creation)\n```\n\n## Create a new token\n\n`--name` is required. Pick something that makes the token's purpose obvious from `token list` later (e.g. `\"CI/CD pipeline\"`, `\"GitHub Actions — production\"`, `\"Local dev — alice\"`).\n\n```bash\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline\"\n```\n\nThe response includes the `token` field — this is the only time the token value is shown. Store it immediately in a secrets manager.\n\n> The new token inherits the permissions of the user running `token create`. If you need a token with broader or narrower access than your user, create it under the appropriate user account, or scope it explicitly via the API / Cargo app after creation.\n\n## Rotate a token (replace an old one)\n\n```bash\n# 1. Create the new token first (give it a clear name)\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline (rotated 2026-01)\"\n# → Save the new token value\n\n# 2. Update all systems using the old token to use the new value\n\n# 3. Remove the old token\ncargo-ai workspaceManagement token remove <old-token-uuid>\n```\n\n## Remove a token\n\n```bash\ncargo-ai workspaceManagement token remove <token-uuid>\n```\n\n## Find which token is currently in use\n\n```bash\ncargo-ai whoami\n# → The active token is the one used for authentication in the current session\n# Run `workspaceManagement token list` to see all tokens and their names\n```\n\nFile v1.3.0:references/examples/users.md\n\n# User management examples\n\n## List all workspace members\n\n```bash\ncargo-ai workspaceManagement user list\n```\n\n## Get the current user\n\n```bash\ncargo-ai workspaceManagement user get-current\n```\n\n## Find available roles before inviting\n\n```bash\ncargo-ai workspaceManagement role list\n# → Note the \"slug\" values for the roles you want to assign\n```\n\n## Invite a new user\n\n```bash\n# 1. Get available roles\ncargo-ai workspaceManagement role list\n\n# 2. Invite the user with their email and role\ncargo-ai workspaceManagement user create \\\n  --user-email newuser@example.com \\\n  --role-slug <role-slug>\n```\n\n## Update a user's role\n\n```bash\ncargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>\n```\n\n## Remove a user from the workspace\n\n```bash\ncargo-ai workspaceManagement user remove --user-uuid <uuid>\n```\n\n## Find the current user's details\n\n```bash\ncargo-ai whoami\n# → Returns your user UUID, email, and active workspace UUID\n```\n\n## Audit workspace members\n\nList all users and their roles:\n\n```bash\n# 1. List all users\ncargo-ai workspaceManagement user list\n# → Note roleSlug for each user\n\n# 2. List all roles to map slugs to role names\ncargo-ai workspaceManagement role list\n# → Cross-reference roleSlug values\n```\n\nFile v1.3.0:references/response-shapes.md\n\n# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-workspace-management` skill.\n\n## cargo-ai whoami\n\n```json\n{\n  \"user\": {\n    \"uuid\": \"user-uuid\",\n    \"email\": \"user@example.com\",\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\"\n  },\n  \"workspace\": {\n    \"uuid\": \"workspace-uuid\",\n    \"name\": \"Acme Corp\"\n  }\n}\n```\n\n## cargo-ai workspaceManagement user list\n\n```json\n{\n  \"users\": [\n    {\n      \"uuid\": \"user-uuid\",\n      \"email\": \"user@example.com\",\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Doe\",\n      \"role\": { \"uuid\": \"role-uuid\", \"slug\": \"member\" },\n      \"createdAt\": \"2025-01-01T00:00:00Z\"\n    }\n  ]\n}\n```\n\n**Key fields:** `uuid`, `email`, `firstName`, `lastName`, `role.slug` (the assigned role).\n\n## cargo-ai workspaceManagement role list\n\n```json\n{\n  \"roles\": [\n    {\n      \"uuid\": \"role-uuid\",\n      \"slug\": \"admin\"\n    },\n    {\n      \"uuid\": \"role-uuid-2\",\n      \"slug\": \"member\"\n    }\n  ]\n}\n```\n\n## cargo-ai workspaceManagement token list\n\n```json\n{\n  \"tokens\": [\n    {\n      \"uuid\": \"token-uuid\",\n      \"name\": \"CI/CD pipeline\",\n      \"permissions\": null,\n      \"workspaceUuid\": \"workspace-uuid\",\n      \"userUuid\": \"user-uuid\",\n      \"createdAt\": \"2025-01-01T00:00:00Z\",\n      \"deletedAt\": null\n    }\n  ]\n}\n```\n\n**Note:** Token values are not returned in `token list`. The actual token string is only returned once at creation time.\n\n**Key fields:**\n\n- `name`: human-readable label assigned at creation (`--name` flag).\n- `permissions`: `null` means the token mirrors the permissions of its owning user (the user identified by `userUuid`) — its effective access is bounded by what that user can do. When non-null, it is an array of permission rules `{ effect, resources, actions }` that scope the token explicitly. CLI-created tokens are always `null`; explicitly scoped tokens are configured via the API or the Cargo app.\n- `deletedAt`: `null` for active tokens; an ISO timestamp once the token has been removed.\n\n## cargo-ai workspaceManagement token create\n\n```json\n{\n  \"token\": {\n    \"uuid\": \"token-uuid\",\n    \"token\": \"<token-value>\",\n    \"name\": \"CI/CD pipeline\",\n    \"permissions\": null,\n    \"workspaceUuid\": \"workspace-uuid\",\n    \"userUuid\": \"user-uuid\",\n    \"createdAt\": \"2025-01-01T00:00:00Z\",\n    \"deletedAt\": null\n  }\n}\n```\n\n**Important:** Save the `token` value immediately — it is shown only once and cannot be retrieved again. The `name` you pass via `--name` is echoed back in the response and shown in `token list`. The `userUuid` is the user whose permissions the token inherits when `permissions` is `null`.\n\n### Permission shape (when not null)\n\nWhen a token has been explicitly scoped (via API or app), `permissions` is an array of rules:\n\n```json\n[\n  {\n    \"effect\": \"allow\",\n    \"resources\": [\"<workflow-uuid>\", \"<folder-uuid>\"],\n    \"actions\": [\"orchestration:workflow:read\", \"orchestration:workflow:write\"]\n  },\n  {\n    \"effect\": \"deny\",\n    \"resources\": null,\n    \"actions\": [\"workspaceManagement:write\"]\n  }\n]\n```\n\n- `effect`: `\"allow\"` or `\"deny\"`.\n- `resources`: array of resource UUIDs (workflow, folder, etc.) that the rule applies to, or `null` for workspace-wide.\n- `actions`: array of dotted action strings, e.g. `\"orchestration:*\"`, `\"orchestration:workflow:read\"`, `\"workspaceManagement:folder:write\"`, `\"ai:agent:write\"`. The `*` wildcard at any level grants every action below it.\n\nWhen `permissions` is non-null, the rules are evaluated independently of the owning user — the token's access is exactly what the rules describe, regardless of what `userUuid` can do.\n\n## cargo-ai workspaceManagement folder list\n\n```json\n{\n  \"folders\": [\n    {\n      \"uuid\": \"folder-uuid\",\n      \"workspaceUuid\": \"...\",\n      \"parentUuid\": null,\n      \"kind\": \"play\",\n      \"name\": \"Q1 Campaigns\",\n      \"emojiSlug\": \"rocket\",\n      \"isReadOnly\": false,\n      \"createdAt\": \"2025-01-01T00:00:00Z\",\n      \"updatedAt\": \"2025-01-15T00:00:00Z\",\n      \"deletedAt\": null\n    }\n  ]\n}\n```\n\n**Key fields:** `uuid`, `name`, `kind` (`play`, `tool`, `agent`, or `file`), `emojiSlug`, `parentUuid` (null for root folders).\n\n## cargo-ai workspaceManagement file list-columns\n\n```json\n{\n  \"columns\": [\n    { \"type\": \"string\", \"name\": \"name\" },\n    { \"type\": \"string\", \"name\": \"domain\" },\n    { \"type\": \"string\", \"name\": \"employee_count\" },\n    { \"type\": \"string\", \"name\": \"industry\" }\n  ]\n}\n```\n\nEach column has a `type` (always `\"string\"` for CSV files) and a `name`. Use the `name` values to map CSV data to workflow input fields when creating a batch.\n\nFile v1.3.0:references/troubleshooting.md\n\n# Troubleshooting\n\nCommon errors and recovery steps for `cargo-workspace-management` commands.\n\n> **If the table below does not resolve the issue, or you (user or agent) are stuck on any Cargo CLI command after ≥ 2 failed attempts, send a workspace management report:**\n>\n> ```bash\n> cargo-ai workspaceManagement report create \\\n>   --title \"<one-line summary>\" \\\n>   --description \"<command run, error message, what you expected, UUIDs involved>\"\n> ```\n>\n> See `examples/reports.md` for guidance on what to include. Reports are how the Cargo team improves the CLI and these skills.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials, or insufficient permissions | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token <token>`; verify with `cargo-ai whoami`; use an admin account/token for workspace management |\n\n## Users\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `user create` fails with permission error | Token lacks admin access | Use a token belonging to a workspace admin |\n| `user create` fails with \"role not found\" | Wrong role UUID | Run `workspaceManagement role list` to get valid role UUIDs |\n| `user remove` fails | Attempting to remove the last admin | Promote another user to admin before removing |\n| User can't log in after being created | Email invitation not accepted | Ask the user to check their email for the workspace invitation |\n\n## Tokens\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `token create` exits with `error: required option '--name <name>' not specified` | `--name` is required since the named-token migration | Pass `--name \"<descriptive label>\"` (e.g. `--name \"CI/CD pipeline\"`) |\n| `token create` rejected with `error: unknown option '--from-user'` | Legacy flag — removed when tokens gained `name` and `permissions` | Drop `--from-user`; use `--name <name>` instead. CLI-created tokens already inherit the creating user's permissions (`permissions: null`) |\n| Lost the token value after creation | Token value only shown once | Remove the token and create a new one (with the same `--name`); store the new value securely |\n| `token remove` fails | Token is currently in use by active processes | Wait for processes to finish, or rotate to a new token first then remove the old one |\n| `Unauthorized` errors in CI/CD with a CLI-created token | Token mirrors the creating user's permissions; that user lost access (role downgraded, removed, etc.) | Verify the token still exists with `workspaceManagement token list`; check the role of the user in `userUuid` (`workspaceManagement user list`); restore the user's permissions, or recreate the token under a user with the access you need |\n| `Unauthorized` errors in CI/CD with an explicitly scoped token | `permissions` array is too narrow for the action being attempted | Inspect the token's `permissions` field via `workspaceManagement token list`; widen via the API/app, or replace with a `permissions: null` token created by a user that has the required access |\n| Two tokens look identical in `token list` | Both were created without a meaningful `--name` | Use `--name` consistently — the name is the only label distinguishing tokens in the listing |\n\n## Folders\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `folder remove` fails | Folder still contains resources | Move or remove all resources from the folder before deleting it |\n| `folder get` returns not found | Wrong folder UUID | Re-run `folder list` to get the correct UUID |\n\n## Files\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `file list-columns` returns empty | Wrong `s3-filename` or file has no headers | Verify the `s3-filename` from the upload response; ensure the CSV has a header row |\n| `file upload` fails | File too large or unsupported format | Check file size limits; ensure the file is a CSV or supported format |\n\n## When nothing else works — submit a report\n\nWhenever the CLI is failing in a way none of the tables above explain, the syntax for a flag is unclear, the agent is looping on the same task, or a needed capability appears to be missing — escalate by submitting a workspace management report:\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"<short summary>\" \\\n  --description \"<exact command, errorMessage, expected vs actual, UUIDs>\"\n```\n\nTrigger conditions (any one is enough):\n\n- A command failed ≥ 2 times in a row on the same task.\n- The user or agent does not know which flag / JSON shape to use, and `--help` plus the skill references do not resolve it.\n- A documented behavior contradicts what you observe.\n- A feature seems to be missing entirely.\n\nSee `examples/reports.md` for full templates.\n\nFile v1.3.0:skill-card.md\n\n## Description:\n\nAdminister a Cargo workspace and communicate with the Cargo team by managing workspace members, roles, API tokens, folders, environment variables, workspace files, sessions, and reports through the Cargo CLI.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cargo-ai](https://clawhub.ai/user/cargo-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers and workspace administrators use this skill to operate Cargo workspaces from an agent session, including member administration, token rotation, folder organization, environment variable management, file uploads, session logging, and issue reporting. Most user, role, and token writes require admin access.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: Workspace administration commands can invite or remove users, change roles, create or remove tokens, and modify environment variables.\n\nMitigation: Use a low-privilege account or token where possible, verify the active workspace with cargo-ai whoami, and confirm every user, token, role, or environment variable mutation before execution.\n\nRisk: The CLI install guidance uses a mutable latest package version.\n\nMitigation: Prefer a pinned @cargo-ai/cli version before installing or running commands in a real workspace.\n\nRisk: Reports and session summaries may send operational context, logs, UUIDs, or transcript-derived details to the Cargo team.\n\nMitigation: Show report text before submission, redact secrets and customer data, and avoid automatic session hooks unless users understand what may be stored.\n\nRisk: Workspace environment variables can expose secrets broadly if created as plain text or updated incorrectly.\n\nMitigation: Use the --secret option for credentials, avoid putting secret values in shell history, and review envVar updates or removals before applying them.\n\n## Reference(s):\n\n- [Cargo skills repository](https://github.com/getcargohq/cargo-skills)\n- [ClawHub skill page](https://clawhub.ai/cargo-ai/skills/cargo-workspace-management)\n- [Response shapes](references/response-shapes.md)\n- [Troubleshooting](references/troubleshooting.md)\n- [User management examples](references/examples/users.md)\n- [API token examples](references/examples/tokens.md)\n- [Folder examples](references/examples/folders.md)\n- [Report examples](references/examples/reports.md)\n- [Session tracking examples](references/examples/sessions.md)\n\n## Skill Output:\n\n**Output Type(s):** [Guidance, Shell commands, Configuration, Markdown, JSON]\n\n**Output Format:** [Markdown guidance with Cargo CLI commands and expected JSON response shapes]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Commands may create, update, remove, or report workspace resources through the cargo-ai CLI; command failures return JSON error messages.]\n\n## Skill Version(s):\n\n1.3.0 (source: skill frontmatter, skill metadata, and server release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.3.0:skill-metadata.json\n\n{\n  \"$comment\": \"Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .\",\n  \"name\": \"cargo-workspace-management\",\n  \"version\": \"1.3.0\",\n  \"documents\": [\n    {\n      \"path\": \"SKILL.md\",\n      \"kind\": \"entrypoint\",\n      \"title\": \"Cargo CLI — Workspace\"\n    },\n    {\n      \"path\": \"references/examples/folders.md\",\n      \"kind\": \"example\",\n      \"title\": \"Folder examples\"\n    },\n    {\n      \"path\": \"references/examples/reports.md\",\n      \"kind\": \"example\",\n      \"title\": \"Report examples\"\n    },\n    {\n      \"path\": \"references/examples/sessions.md\",\n      \"kind\": \"example\",\n      \"title\": \"Session tracking examples\"\n    },\n    {\n      \"path\": \"references/examples/tokens.md\",\n      \"kind\": \"example\",\n      \"title\": \"API token examples\"\n    },\n    {\n      \"path\": \"references/examples/users.md\",\n      \"kind\": \"example\",\n      \"title\": \"User management examples\"\n    },\n    {\n      \"path\": \"references/response-shapes.md\",\n      \"kind\": \"reference\",\n      \"title\": \"Response shapes\"\n    },\n    {\n      \"path\": \"references/troubleshooting.md\",\n      \"kind\": \"reference\",\n      \"title\": \"Troubleshooting\"\n    }\n  ],\n  \"contentHash\": \"b80d3833133aaae2ba052318e8221a87b62f83da181159272231eb470f410a25\"\n}\n\nArchive v1.2.2: 11 files, 17903 bytes\n\nFiles: references/examples/folders.md (1583b), references/examples/reports.md (6122b), references/examples/sessions.md (3664b), references/examples/tokens.md (2032b), references/examples/users.md (1258b), references/response-shapes.md (4525b), references/troubleshooting.md (5031b), skill-card.md (3073b), skill-metadata.json (1290b), SKILL.md (11709b), _meta.json (145b)\n\nFile v1.2.2:SKILL.md\n\n---\nname: cargo-workspace-management\ndescription: \"Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: \\\"invite my teammate\\\", \\\"create an API token for CI\\\", \\\"who has access\\\", \\\"organize these into folders\\\", \\\"rotate that token\\\", \\\"upload this CSV for a batch\\\" — and for feedback: \\\"report this bug to Cargo\\\", \\\"send feedback to the Cargo team\\\", \\\"this CLI command is broken\\\", \\\"share this session with Cargo\\\", \\\"request a feature\\\". Most commands need a token with admin access. Skip when: the question is about credits, plans, or invoices — use cargo-billing.\"\nversion: \"1.2.2\"\ncompatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n  author: getcargo\n  openclaw:\n    requires:\n      bins:\n        - cargo-ai\n    install:\n      - kind: node\n        package: \"@cargo-ai/cli@latest\"\n        bins:\n          - cargo-ai\n    homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Workspace\n\nWorkspace administration: managing users, API tokens, folders, roles, workspace-level files, and submitting reports to workspace management.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/users.md` for user invite and management examples.\n> See `references/examples/tokens.md` for API token creation and rotation examples.\n> See `references/examples/folders.md` for organizing resources into folders.\n> See `references/examples/reports.md` for examples of submitting workspace management reports.\n> See `references/examples/sessions.md` for session tracking — the Cargo installer scaffolds the Claude Code SessionStart + Stop + SessionEnd hooks automatically.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\n```\n\nEvery command prints JSON to stdout; failures exit non-zero with `{\"errorMessage\": \"...\"}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. **Admin-only:** user, role, and token writes require a token with admin access on the workspace. Folder writes and `report create` work with non-admin tokens. When the full skill bundle is installed, [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) adds the CLI version pin, token scopes, and the admin-only surface.\n\n## Discover resources first\n\n```bash\ncargo-ai whoami                        # current user and active workspace\ncargo-ai workspaceManagement user list           # all workspace members\ncargo-ai workspaceManagement role list           # available roles\ncargo-ai workspaceManagement token list          # all API tokens\ncargo-ai workspaceManagement folder list         # all folders\n```\n\n## Quick reference\n\n```bash\ncargo-ai whoami\ncargo-ai workspaceManagement user list\ncargo-ai workspaceManagement user create --user-email <email> --role-slug <slug>\ncargo-ai workspaceManagement token list\ncargo-ai workspaceManagement token create --name <name>\ncargo-ai workspaceManagement token remove <token-uuid>\ncargo-ai workspaceManagement folder list\ncargo-ai workspaceManagement folder create --name <name> --emoji-slug <slug> --kind <kind>\ncargo-ai workspaceManagement report create --title <title> --description <description>\ncargo-ai workspaceManagement session upsert --session-id <id> --title <title> --summary <summary> [--finished]\n```\n\n## Current user and workspace\n\n```bash\n# Get your current user and workspace context\ncargo-ai whoami\n# → Returns your user UUID, email, and active workspace UUID\n```\n\n## Users\n\n```bash\n# List all workspace members\ncargo-ai workspaceManagement user list\n\n# Invite a new user (requires their email and a role)\ncargo-ai workspaceManagement user create \\\n  --user-email user@example.com \\\n  --role-slug <role-slug>\n\n# Update a user's role\ncargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>\n\n# Remove a user from the workspace\ncargo-ai workspaceManagement user remove --user-uuid <uuid>\n```\n\n## Roles\n\nRoles define what users can do in the workspace.\n\n```bash\n# List available roles\ncargo-ai workspaceManagement role list\n```\n\nAlways check available roles before inviting users — use the `slug` from `role list` when creating or updating users.\n\n## API tokens\n\nEach token has a human-readable `name` and a `permissions` field. Tokens created via the CLI are issued with `permissions: null`, which means the token mirrors the permissions of its owning user (the user who ran `token create`) — so a token's effective access is bounded by what that user can do in the workspace. Fine-grained permission scoping (an explicit allow/deny list) is configured via the API or the Cargo app.\n\n```bash\n# List all API tokens (includes name and permissions of each token)\ncargo-ai workspaceManagement token list\n\n# Create a new token — --name is required\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline\"\n# → Returns the token value — store it securely, it won't be shown again\n\n# Remove a token\ncargo-ai workspaceManagement token remove <token-uuid>\n```\n\n**Naming:** Pick a `--name` that makes the token's purpose obvious in `token list` later (e.g. `\"GitHub Actions — production\"`, `\"Local dev — alice\"`, `\"Zapier integration\"`). The name is the only way to tell tokens apart in the listing.\n\n**Security:** Token values are only shown once at creation. Store them in a secrets manager (e.g. GitHub Secrets, AWS Secrets Manager).\n\n## Folders\n\nFolders organize resources (plays, tools, agents) in the Cargo app.\n\n```bash\n# List all folders\ncargo-ai workspaceManagement folder list\n\n# Create a folder (kind: \"tool\", \"play\", \"agent\", or \"file\")\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\n\n# Get a folder\ncargo-ai workspaceManagement folder get <folder-uuid>\n\n# Update a folder\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\n\n# Remove a folder\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Reports\n\nSubmit a report to workspace management. **Use this whenever the CLI is failing, behaving unexpectedly, lacks a capability you need, or whenever you (user or agent) are struggling to accomplish a task with the CLI.** This is the official feedback channel — every report is reviewed by the Cargo team and used to improve the CLI, its skills, and the underlying APIs.\n\n```bash\n# Submit a report to workspace management\ncargo-ai workspaceManagement report create \\\n  --title \"<short summary>\" \\\n  --description \"<detailed description, including the command(s) tried and the error(s) seen>\"\n```\n\n**When to send a report (non-exhaustive):**\n\n- A command exits non-zero with an `errorMessage` you cannot resolve from `--help` or `references/troubleshooting.md`.\n- The CLI is being misused or the syntax is unclear (e.g. you can't figure out which flag to pass, or the JSON schema for `--filter` / `--nodes` / `--action` is ambiguous).\n- A user or AI agent is repeatedly retrying the same command without progress (≥ 2 failed attempts on the same task).\n- A documented command does not behave as the skill describes, or a response shape differs from what `references/response-shapes.md` documents.\n- A capability appears to be missing entirely (no command exists for what you need to do).\n- An async operation never reaches a terminal status, or returns inconsistent results across runs.\n\n**What to put in the report:**\n\n- `--title`: one-line summary of the problem (e.g. `\"batch create fails with 'playNotCompatible' on tool workflow\"`).\n- `--description`: include the exact command(s) executed (with sensitive values redacted), the JSON `errorMessage`, what you expected, what you tried, and any relevant UUIDs (run, batch, workflow, model). The more context you provide, the faster it can be triaged.\n\n```bash\n# Example: report a CLI struggle after multiple failed attempts\ncargo-ai workspaceManagement report create \\\n  --title \"segment fetch returns empty results despite matching records in UI\" \\\n  --description \"Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\\\"conjunction\\\":\\\"and\\\",\\\"groups\\\":[...]}'. Got 0 records. The same filter shows 1,200 matches in the app UI. Tried both --filter and --segment-uuid; both return empty. Expected: the same records as the UI.\"\n```\n\n> Do not silently give up on a failing CLI task. **Send a report.** This closes the feedback loop so the CLI and these skills can be improved.\n\n## Sessions\n\nRecord a Claude Code session in `workspace_management.sessions`. One row per `(workspaceUuid, sessionId)`. Used by the `cargo` router's Claude Code SessionStart + Stop + SessionEnd hook recipe — see [`../cargo/SKILL.md`](../cargo/SKILL.md) for when to wire them up.\n\n```bash\n# Upsert a session. Idempotent on --session-id within the workspace.\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<short title>\" \\\n  --summary \"<one-or-two sentence summary>\"\n\n# Same call, but also stamp finished_at = now\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<final title>\" \\\n  --summary \"<final summary>\" \\\n  --finished\n```\n\n- `--session-id`, `--title`, `--summary` are required on every call. `title` and `summary` are `NOT NULL` in the schema — pass placeholders on the start call and overwrite on the end call.\n- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` for an explicit timestamp instead.\n- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.\n\nReturns the upserted session as JSON. The [Cargo installer](https://github.com/getcargohq/cargo-skills#staying-current) wires SessionStart + Stop + SessionEnd hooks that call this command automatically: SessionStart writes a placeholder, the per-turn Stop hook checkpoints the row (no `--finished`), and SessionEnd writes the transcript-driven AI summary with `--finished` — see [`references/examples/sessions.md`](references/examples/sessions.md).\n\n## Workspace files\n\nWorkspace files are CSVs or other data files uploaded for use in batch runs.\n\n```bash\n# Upload a file\ncargo-ai workspaceManagement file upload --file <path-to-file>\n# → Returns s3Filename\n\n# Inspect a file's columns before running a batch\ncargo-ai workspaceManagement file list-columns --s3-filename <s3-filename>\n# → Returns column names to use when mapping to workflow inputs\n```\n\nThe `s3-filename` is returned when uploading a file via `cargo-ai workspaceManagement file upload`. See the `cargo-orchestration` skill's `references/examples/tools.md` for the full file upload and batch run workflow.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai workspaceManagement user create --help\ncargo-ai workspaceManagement token create --help\ncargo-ai workspaceManagement folder create --help\n```\n\nFile v1.2.2:_meta.json\n\n{\n  \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n  \"slug\": \"cargo-workspace-management\",\n  \"version\": \"1.2.2\",\n  \"publishedAt\": 1787874317213\n}\n\nFile v1.2.2:references/examples/folders.md\n\n# Folder examples\n\nFolders organize resources (plays, tools, agents) in the Cargo app for easier navigation.\n\n## List all folders\n\n```bash\ncargo-ai workspaceManagement folder list\n```\n\n## Create a folder\n\nRequires `--name`, `--emoji-slug`, and `--kind`. Kind determines what resources the folder can contain: `play`, `tool`, `agent`, or `file`.\n\n```bash\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\ncargo-ai workspaceManagement folder create --name \"Outbound - SDR Team\" --emoji-slug \"briefcase\" --kind \"tool\"\ncargo-ai workspaceManagement folder create --name \"AI Assistants\" --emoji-slug \"robot\" --kind \"agent\"\n```\n\n## Get a folder\n\n```bash\ncargo-ai workspaceManagement folder get <folder-uuid>\n```\n\n## Update a folder\n\n```bash\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --emoji-slug \"star\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --parent-uuid <parent-folder-uuid>\n```\n\n## Remove a folder\n\n```bash\n# Remove all resources from the folder first (via the Cargo app or by updating each resource)\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Find a folder UUID for assigning resources\n\n```bash\n# 1. List folders to find the one you want\ncargo-ai workspaceManagement folder list\n# → Note the \"uuid\" for the target folder\n\n# 2. When creating or updating a play/tool/agent, pass the folder UUID\n# (Folder assignment is typically done via play/tool/agent update commands)\n```\n\nFile v1.2.2:references/examples/reports.md\n\n# Report examples\n\n`cargo-ai workspaceManagement report create` submits a report to **workspace management** — the Cargo team's official feedback channel for the CLI and its skills.\n\n**Always send a report when:**\n\n- A CLI command fails and the cause is not obvious from `--help`, `references/response-shapes.md`, or `references/troubleshooting.md`.\n- The user or the AI agent is struggling to use the CLI: repeated failed attempts (≥ 2) on the same task, ambiguous flags, unclear JSON schemas, or commands that don't behave as documented.\n- A capability seems to be missing entirely (no command exists for the operation needed).\n- A response shape, error message, or async behavior contradicts what the skills describe.\n- The CLI is being used incorrectly and the correct usage is not discoverable from the existing documentation.\n\nReports are how these skills and the CLI improve. **Do not give up silently — file a report.**\n\nThe channel also carries **consented session-shares** (see the last example): at the natural end of a session, ask the user once whether to send the session's activity to the Cargo team. Consented real session traces are the fastest product-learning loop the team has — wins are as valuable as failures.\n\n## Submit a report\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"<one-line summary of the problem>\" \\\n  --description \"<exact command, error, expected vs actual, relevant UUIDs>\"\n```\n\nBoth `--title` and `--description` are required. The command returns the created report as JSON.\n\n## What to include in the description\n\nAlways include, when relevant:\n\n- The exact command(s) you ran, with secrets/tokens redacted.\n- The full `errorMessage` from the JSON output.\n- What you expected to happen and what actually happened.\n- Any UUIDs referenced (run, batch, workflow, model, segment, agent, connector, …).\n- How many times the failure was reproduced and any variations tried.\n- The skill / reference page consulted before reporting (so the team knows what was already tried).\n\n## Examples\n\n### CLI command fails with an unhelpful error\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"orchestration run create returns 'playNotCompatible' on a tool workflow\" \\\n  --description \"Ran: cargo-ai orchestration run create --workflow-uuid abc-123 --data '{\\\"domain\\\":\\\"acme.com\\\"}'. Got: {\\\"errorMessage\\\":\\\"playNotCompatible\\\"}. The workflow UUID was returned by 'orchestration tool list', so it should be a tool workflow. Skill consulted: cargo-orchestration/SKILL.md decision flowchart.\"\n```\n\n### Filter syntax is unclear / silently returns empty\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"segment fetch returns 0 records despite UI showing matches\" \\\n  --description \"Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\\\"conjonction\\\":\\\"and\\\",\\\"groups\\\":[{\\\"conjonction\\\":\\\"and\\\",\\\"conditions\\\":[{\\\"kind\\\":\\\"string\\\",\\\"columnSlug\\\":\\\"country\\\",\\\"operator\\\":\\\"is\\\",\\\"values\\\":[\\\"US\\\"]}]}]}'. Got 0 records. The same filter in the app UI shows 1,200 matches. Tried 'conjunction' and 'conjonction' spellings — both return 0.\"\n```\n\n### Agent is struggling with the CLI after multiple retries\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"Agent unable to determine correct --action JSON for HubSpot company_create\" \\\n  --description \"Tried 4 variants of cargo-ai orchestration action execute --action '{\\\"kind\\\":\\\"connector\\\",\\\"integrationSlug\\\":\\\"hubspot\\\",\\\"actionSlug\\\":\\\"company_create\\\"}' --data '{...}'. Each fails with a different validation error ('data.portalId required', then 'data.properties required', etc.). The required shape is not documented in cargo-connection or cargo-orchestration. Need a worked example or a schema reference.\"\n```\n\n### Missing capability\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"No CLI command to bulk re-run failed records from a previous batch\" \\\n  --description \"Trying to re-run only the failed records from batch <uuid>. 'analytics run download --statuses error' produces a CSV but there is no documented way to feed that CSV back into 'orchestration batch create' as the input set without manual transformation. A '--from-failed-batch <uuid>' option (or equivalent) appears to be missing.\"\n```\n\n### Documentation contradicts observed behavior\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"billing usage get-metrics --group-by workflow_uuid returns connector_uuid groupings\" \\\n  --description \"Ran: cargo-ai billing usage get-metrics --from 2025-01-01 --to 2025-01-31 --group-by workflow_uuid. Response groups results by connector_uuid instead of workflow_uuid. cargo-billing/SKILL.md says workflow_uuid is a valid --group-by value.\"\n```\n\n### Session share (user consented at session end)\n\nOnly after the user answered **yes** to \"Send this session's activity to the Cargo team so they can improve the experience? (Y/N)\":\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"Session share: TAM build for fintech ICP, 500 companies\" \\\n  --description \"Goal: 500-company TAM for a fintech ICP + verified emails for top 50. Path: build-tam.md recipe → salesNavigator.searchAccounts (limit-1 probe sized pool at ~3,400) → pilot 3 rows → full pull → FullEnrich.findEmail on 70 (1.4x over-provision) → waterfall.verifyEmail. Worked well: pilot caught a bad industry code before the full pull. Friction: needed 4 tries to get the searchAccounts headcount enum right — enum values not in the playbook. Spend: ~41 credits vs ~38 estimated (searchAccounts pagination returned partial last page). No secrets or record-level data included.\"\n```\n\nRedact secrets and record-level personal data; describe shapes and counts, not rows. If the user answered no, do not file and do not ask again that session.\n\n## After sending a report\n\nThe CLI prints the created report as JSON. Note the returned `uuid` so it can be referenced in any follow-up communication with the Cargo team. After reporting, fall back to the closest documented workaround (e.g. the Cargo app UI) so the user is unblocked.\n\nFile v1.2.2:references/examples/sessions.md\n\n# Session tracking examples\n\n`cargo-ai workspaceManagement session upsert` creates or updates a Claude Code session row in `workspace_management.sessions`. One row per `(workspaceUuid, sessionId)`. Use it to keep a queryable log of every Claude Code session — what was worked on, when it started, and a short AI-generated summary of what happened.\n\n## CLI surface\n\n```bash\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<short title>\" \\\n  --summary \"<one-or-two-sentence summary>\" \\\n  [--finished | --finished-at <iso-timestamp>]\n```\n\n- `--session-id`, `--title`, `--summary` are required on every call (`title` and `summary` are `NOT NULL` in the schema).\n- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` to set an explicit timestamp.\n- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.\n\nThe command returns the upserted session as JSON.\n\n## Schema\n\n```text\nworkspace_management.sessions\n├── uuid              (pk)\n├── session_id        (string, UNIQUE with workspace_uuid)\n├── user_uuid\n├── workspace_uuid\n├── title             (NOT NULL)\n├── summary           (NOT NULL)\n├── created_at        (default now)\n└── finished_at       (nullable, stamped by --finished)\n```\n\n## Manual upsert\n\n```bash\n# Record a session start with placeholder text\ncargo-ai workspaceManagement session upsert \\\n  --session-id abc-123 \\\n  --title \"Claude Code session abc-123\" \\\n  --summary \"Session in progress.\"\n\n# Later, overwrite with the real title + summary and mark finished\ncargo-ai workspaceManagement session upsert \\\n  --session-id abc-123 \\\n  --title \"Wire up workspace_management.sessions\" \\\n  --summary \"Added the sessions resource end-to-end across migration, repository, service, HTTP, and CLI; updated cargo-skills docs to suggest the hook recipe.\" \\\n  --finished\n```\n\n## Automate with Claude Code hooks (recommended)\n\nDon't hand-roll the hooks — the Cargo installer scaffolds them for you. Run it once and answer **y** at the session-hooks prompt:\n\n```bash\ncurl -fsSL https://api.getcargo.io/install.sh | sh\n```\n\nIt writes three hooks under `~/.claude/` and merges the matching entries into `~/.claude/settings.json`:\n\n- **`SessionStart`** refreshes `@cargo-ai/cli` + the skills bundle and creates the session row with placeholders (`\"Session in progress.\"`).\n- **`Stop`** (runs at the end of each assistant turn) checkpoints the row — it derives a lightweight title/summary from the transcript with `jq` (latest user request + timestamp, **no** LLM call) and upserts **without** `--finished`, throttled to one update per `CARGO_CHECKPOINT_INTERVAL` seconds (default 45). This keeps a session that never reaches `SessionEnd` (crash, timeout, reclaimed container) from being stuck on the bare placeholder.\n- **`SessionEnd`** reads the transcript, asks `claude -p` to summarize, and writes the real title + summary with `--finished`.\n\nAll hooks swallow errors (`|| true`), so a missing `cargo-ai`/`claude`/`jq` binary never blocks a session — at worst, the row just keeps its last checkpoint. The `SessionEnd` hook logs each step to `$CARGO_SESSION_LOG` (default `~/.claude/cargo-session.log`), so a row stuck on `\"Session ended.\"` can be diagnosed there. Set `CARGO_INSTALL_HOOKS=0` to skip the prompt (or `=1` to install without prompting).\n\nThe hooks are thin wrappers around the `session upsert` command documented above — read the installer (`apps/backend/src/http/routes/install.sh` in `getcargohq/cargo`) if you want to see or customize the exact scripts.\n\nFile v1.2.2:references/examples/tokens.md\n\n# API token examples\n\nEvery token has a human-readable `name` and a `permissions` field. The CLI's `token create` always issues a token with `permissions: null`, which means the token mirrors the permissions of the user who created it — its effective access is whatever that user can do in the workspace. Use the API or the Cargo app to scope a token to a different subset of actions / resources.\n\n## List all tokens\n\n```bash\ncargo-ai workspaceManagement token list\n# → Each entry includes `uuid`, `name`, `permissions`, `userUuid`, `workspaceUuid`, `createdAt`, `deletedAt`\n# (the actual token value is not shown — it is only returned once, at creation)\n```\n\n## Create a new token\n\n`--name` is required. Pick something that makes the token's purpose obvious from `token list` later (e.g. `\"CI/CD pipeline\"`, `\"GitHub Actions — production\"`, `\"Local dev — alice\"`).\n\n```bash\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline\"\n```\n\nThe response includes the `token` field — this is the only time the token value is shown. Store it immediately in a secrets manager.\n\n> The new token inherits the permissions of the user running `token create`. If you need a token with broader or narrower access than your user, create it under the appropriate user account, or scope it explicitly via the API / Cargo app after creation.\n\n## Rotate a token (replace an old one)\n\n```bash\n# 1. Create the new token first (give it a clear name)\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline (rotated 2026-01)\"\n# → Save the new token value\n\n# 2. Update all systems using the old token to use the new value\n\n# 3. Remove the old token\ncargo-ai workspaceManagement token remove <old-token-uuid>\n```\n\n## Remove a token\n\n```bash\ncargo-ai workspaceManagement token remove <token-uuid>\n```\n\n## Find which token is currently in use\n\n```bash\ncargo-ai whoami\n# → The active token is the one used for authentication in the current session\n# Run `workspaceManagement token list` to see all tokens and their names\n```\n\nFile v1.2.2:references/examples/users.md\n\n# User management examples\n\n## List all workspace members\n\n```bash\ncargo-ai workspaceManagement user list\n```\n\n## Get the current user\n\n```bash\ncargo-ai workspaceManagement user get-current\n```\n\n## Find available roles before inviting\n\n```bash\ncargo-ai workspaceManagement role list\n# → Note the \"slug\" values for the roles you want to assign\n```\n\n## Invite a new user\n\n```bash\n# 1. Get available roles\ncargo-ai workspaceManagement role list\n\n# 2. Invite the user with their email and role\ncargo-ai workspaceManagement user create \\\n  --user-email newuser@example.com \\\n  --role-slug <role-slug>\n```\n\n## Update a user's role\n\n```bash\ncargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>\n```\n\n## Remove a user from the workspace\n\n```bash\ncargo-ai workspaceManagement user remove --user-uuid <uuid>\n```\n\n## Find the current user's details\n\n```bash\ncargo-ai whoami\n# → Returns your user UUID, email, and active workspace UUID\n```\n\n## Audit workspace members\n\nList all users and their roles:\n\n```bash\n# 1. List all users\ncargo-ai workspaceManagement user list\n# → Note roleSlug for each user\n\n# 2. List all roles to map slugs to role names\ncargo-ai workspaceManagement role list\n# → Cross-reference roleSlug values\n```\n\nFile v1.2.2:references/response-shapes.md\n\n# Response shapes\n\nJSON response structures returned by Cargo CLI commands used in the `cargo-workspace-management` skill.\n\n## cargo-ai whoami\n\n```json\n{\n  \"user\": {\n    \"uuid\": \"user-uuid\",\n    \"email\": \"user@example.com\",\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Doe\"\n  },\n  \"workspace\": {\n    \"uuid\": \"workspace-uuid\",\n    \"name\": \"Acme Corp\"\n  }\n}\n```\n\n## cargo-ai workspaceManagement user list\n\n```json\n{\n  \"users\": [\n    {\n      \"uuid\": \"user-uuid\",\n      \"email\": \"user@example.com\",\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Doe\",\n      \"role\": { \"uuid\": \"role-uuid\", \"slug\": \"member\" },\n      \"createdAt\": \"2025-01-01T00:00:00Z\"\n    }\n  ]\n}\n```\n\n**Key fields:** `uuid`, `email`, `firstName`, `lastName`, `role.slug` (the assigned role).\n\n## cargo-ai workspaceManagement role list\n\n```json\n{\n  \"roles\": [\n    {\n      \"uuid\": \"role-uuid\",\n      \"slug\": \"admin\"\n    },\n    {\n      \"uuid\": \"role-uuid-2\",\n      \"slug\": \"member\"\n    }\n  ]\n}\n```\n\n## cargo-ai workspaceManagement token list\n\n```json\n{\n  \"tokens\": [\n    {\n      \"uuid\": \"token-uuid\",\n      \"name\": \"CI/CD pipeline\",\n      \"permissions\": null,\n      \"workspaceUuid\": \"workspace-uuid\",\n      \"userUuid\": \"user-uuid\",\n      \"createdAt\": \"2025-01-01T00:00:00Z\",\n      \"deletedAt\": null\n    }\n  ]\n}\n```\n\n**Note:** Token values are not returned in `token list`. The actual token string is only returned once at creation time.\n\n**Key fields:**\n\n- `name`: human-readable label assigned at creation (`--name` flag).\n- `permissions`: `null` means the token mirrors the permissions of its owning user (the user identified by `userUuid`) — its effective access is bounded by what that user can do. When non-null, it is an array of permission rules `{ effect, resources, actions }` that scope the token explicitly. CLI-created tokens are always `null`; explicitly scoped tokens are configured via the API or the Cargo app.\n- `deletedAt`: `null` for active tokens; an ISO timestamp once the token has been removed.\n\n## cargo-ai workspaceManagement token create\n\n```json\n{\n  \"token\": {\n    \"uuid\": \"token-uuid\",\n    \"token\": \"<token-value>\",\n    \"name\": \"CI/CD pipeline\",\n    \"permissions\": null,\n    \"workspaceUuid\": \"workspace-uuid\",\n    \"userUuid\": \"user-uuid\",\n    \"createdAt\": \"2025-01-01T00:00:00Z\",\n    \"deletedAt\": null\n  }\n}\n```\n\n**Important:** Save the `token` value immediately — it is shown only once and cannot be retrieved again. The `name` you pass via `--name` is echoed back in the response and shown in `token list`. The `userUuid` is the user whose permissions the token inherits when `permissions` is `null`.\n\n### Permission shape (when not null)\n\nWhen a token has been explicitly scoped (via API or app), `permissions` is an array of rules:\n\n```json\n[\n  {\n    \"effect\": \"allow\",\n    \"resources\": [\"<workflow-uuid>\", \"<folder-uuid>\"],\n    \"actions\": [\"orchestration:workflow:read\", \"orchestration:workflow:write\"]\n  },\n  {\n    \"effect\": \"deny\",\n    \"resources\": null,\n    \"actions\": [\"workspaceManagement:write\"]\n  }\n]\n```\n\n- `effect`: `\"allow\"` or `\"deny\"`.\n- `resources`: array of resource UUIDs (workflow, folder, etc.) that the rule applies to, or `null` for workspace-wide.\n- `actions`: array of dotted action strings, e.g. `\"orchestration:*\"`, `\"orchestration:workflow:read\"`, `\"workspaceManagement:folder:write\"`, `\"ai:agent:write\"`. The `*` wildcard at any level grants every action below it.\n\nWhen `permissions` is non-null, the rules are evaluated independently of the owning user — the token's access is exactly what the rules describe, regardless of what `userUuid` can do.\n\n## cargo-ai workspaceManagement folder list\n\n```json\n{\n  \"folders\": [\n    {\n      \"uuid\": \"folder-uuid\",\n      \"workspaceUuid\": \"...\",\n      \"parentUuid\": null,\n      \"kind\": \"play\",\n      \"name\": \"Q1 Campaigns\",\n      \"emojiSlug\": \"rocket\",\n      \"isReadOnly\": false,\n      \"createdAt\": \"2025-01-01T00:00:00Z\",\n      \"updatedAt\": \"2025-01-15T00:00:00Z\",\n      \"deletedAt\": null\n    }\n  ]\n}\n```\n\n**Key fields:** `uuid`, `name`, `kind` (`play`, `tool`, `agent`, or `file`), `emojiSlug`, `parentUuid` (null for root folders).\n\n## cargo-ai workspaceManagement file list-columns\n\n```json\n{\n  \"columns\": [\n    { \"type\": \"string\", \"name\": \"name\" },\n    { \"type\": \"string\", \"name\": \"domain\" },\n    { \"type\": \"string\", \"name\": \"employee_count\" },\n    { \"type\": \"string\", \"name\": \"industry\" }\n  ]\n}\n```\n\nEach column has a `type` (always `\"string\"` for CSV files) and a `name`. Use the `name` values to map CSV data to workflow input fields when creating a batch.\n\nFile v1.2.2:references/troubleshooting.md\n\n# Troubleshooting\n\nCommon errors and recovery steps for `cargo-workspace-management` commands.\n\n> **If the table below does not resolve the issue, or you (user or agent) are stuck on any Cargo CLI command after ≥ 2 failed attempts, send a workspace management report:**\n>\n> ```bash\n> cargo-ai workspaceManagement report create \\\n>   --title \"<one-line summary>\" \\\n>   --description \"<command run, error message, what you expected, UUIDs involved>\"\n> ```\n>\n> See `examples/reports.md` for guidance on what to include. Reports are how the Cargo team improves the CLI and these skills.\n\n## General\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `{\"errorMessage\": \"...\"}` with non-zero exit | Any CLI error | Read the `errorMessage` — it usually says exactly what's wrong |\n| `command not found: cargo-ai` | CLI not installed or not in PATH | Run `npm install -g @cargo-ai/cli` or prefix with `npx @cargo-ai/cli` |\n| `Unauthorized` or `Forbidden` | Bad or expired credentials, or insufficient permissions | Re-run `cargo-ai login --oauth` (browser sign-in) or `cargo-ai login --token <token>`; verify with `cargo-ai whoami`; use an admin account/token for workspace management |\n\n## Users\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `user create` fails with permission error | Token lacks admin access | Use a token belonging to a workspace admin |\n| `user create` fails with \"role not found\" | Wrong role UUID | Run `workspaceManagement role list` to get valid role UUIDs |\n| `user remove` fails | Attempting to remove the last admin | Promote another user to admin before removing |\n| User can't log in after being created | Email invitation not accepted | Ask the user to check their email for the workspace invitation |\n\n## Tokens\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `token create` exits with `error: required option '--name <name>' not specified` | `--name` is required since the named-token migration | Pass `--name \"<descriptive label>\"` (e.g. `--name \"CI/CD pipeline\"`) |\n| `token create` rejected with `error: unknown option '--from-user'` | Legacy flag — removed when tokens gained `name` and `permissions` | Drop `--from-user`; use `--name <name>` instead. CLI-created tokens already inherit the creating user's permissions (`permissions: null`) |\n| Lost the token value after creation | Token value only shown once | Remove the token and create a new one (with the same `--name`); store the new value securely |\n| `token remove` fails | Token is currently in use by active processes | Wait for processes to finish, or rotate to a new token first then remove the old one |\n| `Unauthorized` errors in CI/CD with a CLI-created token | Token mirrors the creating user's permissions; that user lost access (role downgraded, removed, etc.) | Verify the token still exists with `workspaceManagement token list`; check the role of the user in `userUuid` (`workspaceManagement user list`); restore the user's permissions, or recreate the token under a user with the access you need |\n| `Unauthorized` errors in CI/CD with an explicitly scoped token | `permissions` array is too narrow for the action being attempted | Inspect the token's `permissions` field via `workspaceManagement token list`; widen via the API/app, or replace with a `permissions: null` token created by a user that has the required access |\n| Two tokens look identical in `token list` | Both were created without a meaningful `--name` | Use `--name` consistently — the name is the only label distinguishing tokens in the listing |\n\n## Folders\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `folder remove` fails | Folder still contains resources | Move or remove all resources from the folder before deleting it |\n| `folder get` returns not found | Wrong folder UUID | Re-run `folder list` to get the correct UUID |\n\n## Files\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `file list-columns` returns empty | Wrong `s3-filename` or file has no headers | Verify the `s3-filename` from the upload response; ensure the CSV has a header row |\n| `file upload` fails | File too large or unsupported format | Check file size limits; ensure the file is a CSV or supported format |\n\n## When nothing else works — submit a report\n\nWhenever the CLI is failing in a way none of the tables above explain, the syntax for a flag is unclear, the agent is looping on the same task, or a needed capability appears to be missing — escalate by submitting a workspace management report:\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"<short summary>\" \\\n  --description \"<exact command, errorMessage, expected vs actual, UUIDs>\"\n```\n\nTrigger conditions (any one is enough):\n\n- A command failed ≥ 2 times in a row on the same task.\n- The user or agent does not know which flag / JSON shape to use, and `--help` plus the skill references do not resolve it.\n- A documented behavior contradicts what you observe.\n- A feature seems to be missing entirely.\n\nSee `examples/reports.md` for full templates.\n\nFile v1.2.2:skill-card.md\n\n## Description:\n\nAdminister Cargo workspaces by managing members, roles, API tokens, folders, workspace files, reports, and optional session records through the Cargo CLI.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[cargo-ai](https://clawhub.ai/user/cargo-ai)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, workspace administrators, and agent operators use this skill to administer a Cargo workspace from the CLI, including user access, API tokens, folders, files, feedback reports, and session records.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: The skill can guide high-impact workspace administration actions, including user, role, token, folder, file, report, and session writes.\n\nMitigation: Confirm the active workspace and intended target before running write commands; use admin credentials only for operations that require them.\n\nRisk: API token creation returns a token value once, and mishandling it can expose workspace access.\n\nMitigation: Store new tokens immediately in an approved secrets manager, redact token values from logs and reports, and rotate or remove unused tokens.\n\nRisk: Workspace file uploads can send sensitive local data to Cargo storage.\n\nMitigation: Upload only files intended for Cargo storage and review file contents before upload.\n\nRisk: Optional Claude session hooks can persist local hook configuration and record transcript-derived session summaries.\n\nMitigation: Enable session hooks only with organizational approval and avoid recording sensitive session details.\n\nRisk: Feedback reports and session shares may include commands, errors, UUIDs, or operational context.\n\nMitigation: Redact secrets and sensitive business data before submitting reports or sharing session activity.\n\n## Reference(s):\n\n- [ClawHub skill page](https://clawhub.ai/cargo-ai/skills/cargo-workspace-management)\n- [Cargo skills homepage](https://github.com/getcargohq/cargo-skills)\n- [Response shapes](references/response-shapes.md)\n- [Troubleshooting](references/troubleshooting.md)\n- [User management examples](references/examples/users.md)\n- [API token examples](references/examples/tokens.md)\n- [Folder examples](references/examples/folders.md)\n- [Report examples](references/examples/reports.md)\n- [Session tracking examples](references/examples/sessions.md)\n\n## Skill Output:\n\n**Output Type(s):** [text, markdown, shell commands, configuration, guidance]\n\n**Output Format:** [Markdown guidance with inline bash commands and JSON response examples]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [Requires Cargo CLI authentication and an active workspace; user, role, and token writes require admin access.]\n\n## Skill Version(s):\n\n1.2.2 (source: frontmatter and release evidence)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v1.2.2:skill-metadata.json\n\n{\n  \"$comment\": \"Generated by .github/scripts/skills-metadata.mjs — do not hand-edit. Regenerate with: node .github/scripts/skills-metadata.mjs --write .\",\n  \"name\": \"cargo-workspace-management\",\n  \"version\": \"1.2.2\",\n  \"documents\": [\n    {\n      \"path\": \"SKILL.md\",\n      \"kind\": \"entrypoint\",\n      \"title\": \"Cargo CLI — Workspace\"\n    },\n    {\n      \"path\": \"references/examples/folders.md\",\n      \"kind\": \"example\",\n      \"title\": \"Folder examples\"\n    },\n    {\n      \"path\": \"references/examples/reports.md\",\n      \"kind\": \"example\",\n      \"title\": \"Report examples\"\n    },\n    {\n      \"path\": \"references/examples/sessions.md\",\n      \"kind\": \"example\",\n      \"title\": \"Session tracking examples\"\n    },\n    {\n      \"path\": \"references/examples/tokens.md\",\n      \"kind\": \"example\",\n      \"title\": \"API token examples\"\n    },\n    {\n      \"path\": \"references/examples/users.md\",\n      \"kind\": \"example\",\n      \"title\": \"User management examples\"\n    },\n    {\n      \"path\": \"references/response-shapes.md\",\n      \"kind\": \"reference\",\n      \"title\": \"Response shapes\"\n    },\n    {\n      \"path\": \"references/troubleshooting.md\",\n      \"kind\": \"reference\",\n      \"title\": \"Troubleshooting\"\n    }\n  ],\n  \"contentHash\": \"802458dbfde95c8c5fb41388e5df4a00cc061cf6cbed1cd912d52b393d21c42c\"\n}\n\nArchive v1.2.1: 11 files, 17485 bytes\n\nFiles: references/examples/folders.md (1583b), references/examples/reports.md (6138b), references/examples/sessions.md (3664b), references/examples/tokens.md (2032b), references/examples/users.md (1258b), references/response-shapes.md (4525b), references/troubleshooting.md (5031b), skill-card.md (3085b), skill-metadata.json (1290b), SKILL.md (10722b), _meta.json (145b)\n\nFile v1.2.1:SKILL.md\n\n---\nname: cargo-workspace-management\ndescription: Manage workspace users, API tokens, folders, roles, and submit reports to workspace management using the Cargo CLI. Use when the user wants to invite or manage workspace members, create or rotate API tokens, organize resources into folders, inspect workspace roles and permissions, or submit a report to workspace management when the CLI fails or is misused.\nversion: \"1.2.1\"\ncompatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n  author: getcargo\n  openclaw:\n    requires:\n      bins:\n        - cargo-ai\n    install:\n      - kind: node\n        package: \"@cargo-ai/cli@latest\"\n        bins:\n          - cargo-ai\n    homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Workspace\n\nWorkspace administration: managing users, API tokens, folders, roles, workspace-level files, and submitting reports to workspace management.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/users.md` for user invite and management examples.\n> See `references/examples/tokens.md` for API token creation and rotation examples.\n> See `references/examples/folders.md` for organizing resources into folders.\n> See `references/examples/reports.md` for examples of submitting workspace management reports.\n> See `references/examples/sessions.md` for session tracking — the Cargo installer scaffolds the Claude Code SessionStart + Stop + SessionEnd hooks automatically.\n\n## Prerequisites\n\nSee [`../cargo/references/prerequisites.md`](../cargo/references/prerequisites.md) for install, login (`--oauth` / `--token`), JSON output conventions, and error shapes. Verify the session with `cargo-ai whoami` before running any of the commands below.\n\n**Admin-only:** user, role, and token writes require a token with admin access on the workspace. Folder writes and `report create` work with non-admin tokens.\n\n## Discover resources first\n\n```bash\ncargo-ai whoami                        # current user and active workspace\ncargo-ai workspaceManagement user list           # all workspace members\ncargo-ai workspaceManagement role list           # available roles\ncargo-ai workspaceManagement token list          # all API tokens\ncargo-ai workspaceManagement folder list         # all folders\n```\n\n## Quick reference\n\n```bash\ncargo-ai whoami\ncargo-ai workspaceManagement user list\ncargo-ai workspaceManagement user create --user-email <email> --role-slug <slug>\ncargo-ai workspaceManagement token list\ncargo-ai workspaceManagement token create --name <name>\ncargo-ai workspaceManagement token remove <token-uuid>\ncargo-ai workspaceManagement folder list\ncargo-ai workspaceManagement folder create --name <name> --emoji-slug <slug> --kind <kind>\ncargo-ai workspaceManagement report create --title <title> --description <description>\ncargo-ai workspaceManagement session upsert --session-id <id> --title <title> --summary <summary> [--finished]\n```\n\n## Current user and workspace\n\n```bash\n# Get your current user and workspace context\ncargo-ai whoami\n# → Returns your user UUID, email, and active workspace UUID\n```\n\n## Users\n\n```bash\n# List all workspace members\ncargo-ai workspaceManagement user list\n\n# Invite a new user (requires their email and a role)\ncargo-ai workspaceManagement user create \\\n  --user-email user@example.com \\\n  --role-slug <role-slug>\n\n# Update a user's role\ncargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>\n\n# Remove a user from the workspace\ncargo-ai workspaceManagement user remove --user-uuid <uuid>\n```\n\n## Roles\n\nRoles define what users can do in the workspace.\n\n```bash\n# List available roles\ncargo-ai workspaceManagement role list\n```\n\nAlways check available roles before inviting users — use the `slug` from `role list` when creating or updating users.\n\n## API tokens\n\nEach token has a human-readable `name` and a `permissions` field. Tokens created via the CLI are issued with `permissions: null`, which means the token mirrors the permissions of its owning user (the user who ran `token create`) — so a token's effective access is bounded by what that user can do in the workspace. Fine-grained permission scoping (an explicit allow/deny list) is configured via the API or the Cargo app.\n\n```bash\n# List all API tokens (includes name and permissions of each token)\ncargo-ai workspaceManagement token list\n\n# Create a new token — --name is required\ncargo-ai workspaceManagement token create --name \"CI/CD pipeline\"\n# → Returns the token value — store it securely, it won't be shown again\n\n# Remove a token\ncargo-ai workspaceManagement token remove <token-uuid>\n```\n\n**Naming:** Pick a `--name` that makes the token's purpose obvious in `token list` later (e.g. `\"GitHub Actions — production\"`, `\"Local dev — alice\"`, `\"Zapier integration\"`). The name is the only way to tell tokens apart in the listing.\n\n**Security:** Token values are only shown once at creation. Store them in a secrets manager (e.g. GitHub Secrets, AWS Secrets Manager).\n\n## Folders\n\nFolders organize resources (plays, tools, agents) in the Cargo app.\n\n```bash\n# List all folders\ncargo-ai workspaceManagement folder list\n\n# Create a folder (kind: \"tool\", \"play\", \"agent\", or \"file\")\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\n\n# Get a folder\ncargo-ai workspaceManagement folder get <folder-uuid>\n\n# Update a folder\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\n\n# Remove a folder\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Reports\n\nSubmit a report to workspace management. **Use this whenever the CLI is failing, behaving unexpectedly, lacks a capability you need, or whenever you (user or agent) are struggling to accomplish a task with the CLI.** This is the official feedback channel — every report is reviewed by the Cargo team and used to improve the CLI, its skills, and the underlying APIs.\n\n```bash\n# Submit a report to workspace management\ncargo-ai workspaceManagement report create \\\n  --title \"<short summary>\" \\\n  --description \"<detailed description, including the command(s) tried and the error(s) seen>\"\n```\n\n**When to send a report (non-exhaustive):**\n\n- A command exits non-zero with an `errorMessage` you cannot resolve from `--help` or `references/troubleshooting.md`.\n- The CLI is being misused or the syntax is unclear (e.g. you can't figure out which flag to pass, or the JSON schema for `--filter` / `--nodes` / `--action` is ambiguous).\n- A user or AI agent is repeatedly retrying the same command without progress (≥ 2 failed attempts on the same task).\n- A documented command does not behave as the skill describes, or a response shape differs from what `references/response-shapes.md` documents.\n- A capability appears to be missing entirely (no command exists for what you need to do).\n- An async operation never reaches a terminal status, or returns inconsistent results across runs.\n\n**What to put in the report:**\n\n- `--title`: one-line summary of the problem (e.g. `\"batch create fails with 'playNotCompatible' on tool workflow\"`).\n- `--description`: include the exact command(s) executed (with sensitive values redacted), the JSON `errorMessage`, what you expected, what you tried, and any relevant UUIDs (run, batch, workflow, model). The more context you provide, the faster it can be triaged.\n\n```bash\n# Example: report a CLI struggle after multiple failed attempts\ncargo-ai workspaceManagement report create \\\n  --title \"segment fetch returns empty results despite matching records in UI\" \\\n  --description \"Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\\\"conjunction\\\":\\\"and\\\",\\\"groups\\\":[...]}'. Got 0 records. The same filter shows 1,200 matches in the app UI. Tried both --filter and --segment-uuid; both return empty. Expected: the same records as the UI.\"\n```\n\n> Do not silently give up on a failing CLI task. **Send a report.** This closes the feedback loop so the CLI and these skills can be improved.\n\n## Sessions\n\nRecord a Claude Code session in `workspace_management.sessions`. One row per `(workspaceUuid, sessionId)`. Used by the `cargo` router's Claude Code SessionStart + Stop + SessionEnd hook recipe — see [`../cargo/SKILL.md`](../cargo/SKILL.md) for when to wire them up.\n\n```bash\n# Upsert a session. Idempotent on --session-id within the workspace.\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<short title>\" \\\n  --summary \"<one-or-two sentence summary>\"\n\n# Same call, but also stamp finished_at = now\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<final title>\" \\\n  --summary \"<final summary>\" \\\n  --finished\n```\n\n- `--session-id`, `--title`, `--summary` are required on every call. `title` and `summary` are `NOT NULL` in the schema — pass placeholders on the start call and overwrite on the end call.\n- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` for an explicit timestamp instead.\n- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.\n\nReturns the upserted session as JSON. The Cargo installer (`curl -fsSL https://api.getcargo.io/install.sh | sh`) wires SessionStart + Stop + SessionEnd hooks that call this command automatically: SessionStart writes a placeholder, the per-turn Stop hook checkpoints the row (no `--finished`), and SessionEnd writes the transcript-driven AI summary with `--finished` — see [`references/examples/sessions.md`](references/examples/sessions.md).\n\n## Workspace files\n\nWorkspace files are CSVs or other data files uploaded for use in batch runs.\n\n```bash\n# Upload a file\ncargo-ai workspaceManagement file upload --file <path-to-file>\n# → Returns s3Filename\n\n# Inspect a file's columns before running a batch\ncargo-ai workspaceManagement file list-columns --s3-filename <s3-filename>\n# → Returns column names to use when mapping to workflow inputs\n```\n\nThe `s3-filename` is returned when uploading a file via `cargo-ai workspaceManagement file upload`. See the `cargo-orchestration` skill's `references/examples/tools.md` for the full file upload and batch run workflow.\n\n## Help\n\nEvery command supports `--help`:\n\n```bash\ncargo-ai workspaceManagement user create --help\ncargo-ai workspaceManagement token create --help\ncargo-ai workspaceManagement folder create --help\n```\n\nFile v1.2.1:_meta.json\n\n{\n  \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n  \"slug\": \"cargo-workspace-management\",\n  \"version\": \"1.2.1\",\n  \"publishedAt\": 1786484679958\n}\n\nFile v1.2.1:references/examples/folders.md\n\n# Folder examples\n\nFolders organize resources (plays, tools, agents) in the Cargo app for easier navigation.\n\n## List all folders\n\n```bash\ncargo-ai workspaceManagement folder list\n```\n\n## Create a folder\n\nRequires `--name`, `--emoji-slug`, and `--kind`. Kind determines what resources the folder can contain: `play`, `tool`, `agent`, or `file`.\n\n```bash\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\ncargo-ai workspaceManagement folder create --name \"Outbound - SDR Team\" --emoji-slug \"briefcase\" --kind \"tool\"\ncargo-ai workspaceManagement folder create --name \"AI Assistants\" --emoji-slug \"robot\" --kind \"agent\"\n```\n\n## Get a folder\n\n```bash\ncargo-ai workspaceManagement folder get <folder-uuid>\n```\n\n## Update a folder\n\n```bash\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --emoji-slug \"star\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --parent-uuid <parent-folder-uuid>\n```\n\n## Remove a folder\n\n```bash\n# Remove all resources from the folder first (via the Cargo app or by updating each resource)\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Find a folder UUID for assigning resources\n\n```bash\n# 1. List folders to find the one you want\ncargo-ai workspaceManagement folder list\n# → Note the \"uuid\" for the target folder\n\n# 2. When creating or updating a play/tool/agent, pass the folder UUID\n# (Folder assignment is typically done via play/tool/agent update commands)\n```\n\nFile v1.2.1:references/examples/reports.md\n\n# Report examples\n\n`cargo-ai workspaceManagement report create` submits a report to **workspace management** — the Cargo team's official feedback channel for the CLI and its skills.\n\n**Always send a report when:**\n\n- A CLI command fails and the cause is not obvious from `--help`, `references/response-shapes.md`, or `references/troubleshooting.md`.\n- The user or the AI agent is struggling to use the CLI: repeated failed attempts (≥ 2) on the same task, ambiguous flags, unclear JSON schemas, or commands that don't behave as documented.\n- A capability seems to be missing entirely (no command exists for the operation needed).\n- A response shape, error message, or async behavior contradicts what the skills describe.\n- The CLI is being used incorrectly and the correct usage is not discoverable from the existing documentation.\n\nReports are how these skills and the CLI improve. **Do not give up silently — file a report.**\n\nThe channel also carries **consented session-shares** (see the last example): at the natural end of a session, ask the user once whether to send the session's activity to the Cargo team. Consented real session traces are the fastest product-learning loop the team has — wins are as valuable as failures.\n\n## Submit a report\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"<one-line summary of the problem>\" \\\n  --description \"<exact command, error, expected vs actual, relevant UUIDs>\"\n```\n\nBoth `--title` and `--description` are required. The command returns the created report as JSON.\n\n## What to include in the description\n\nAlways include, when relevant:\n\n- The exact command(s) you ran, with secrets/tokens redacted.\n- The full `errorMessage` from the JSON output.\n- What you expected to happen and what actually happened.\n- Any UUIDs referenced (run, batch, workflow, model, segment, agent, connecto\n\nArchive v1.2.0: 10 files, 16811 bytes\n\nFiles: references/examples/folders.md (1583b), references/examples/reports.md (6138b), references/examples/sessions.md (3664b), references/examples/tokens.md (2032b), references/examples/users.md (1258b), references/response-shapes.md (4525b), references/troubleshooting.md (5031b), skill-card.md (2932b), SKILL.md (10679b), _meta.json (145b)\n\nArchive v1.1.0: 10 files, 16261 bytes\n\nFiles: references/examples/folders.md (1583b), references/examples/reports.md (4754b), references/examples/sessions.md (3664b), references/examples/tokens.md (2032b), references/examples/users.md (1258b), references/response-shapes.md (4525b), references/troubleshooting.md (5031b), skill-card.md (3135b), SKILL.md (10679b), _meta.json (145b)\n\nArchive v1.0.2: 10 files, 15849 bytes\n\nFiles: references/examples/folders.md (1583b), references/examples/reports.md (4754b), references/examples/sessions.md (2998b), references/examples/tokens.md (2032b), references/examples/users.md (1258b), references/response-shapes.md (4525b), references/troubleshooting.md (5031b), skill-card.md (2881b), SKILL.md (10527b), _meta.json (145b)\n\nArchive v1.0.1: 10 files, 16081 bytes\n\nFiles: references/examples/folders.md (1583b), references/examples/reports.md (4754b), references/examples/sessions.md (4562b), references/examples/tokens.md (2032b), references/examples/users.md (1258b), references/response-shapes.md (4525b), references/troubleshooting.md (5031b), skill-card.md (2963b), SKILL.md (10339b), _meta.json (145b)\n\nArchive v1.0.0: 9 files, 13691 bytes\n\nFiles: references/examples/folders.md (1583b), references/examples/reports.md (4754b), references/examples/tokens.md (2032b), references/examples/users.md (1258b), references/response-shapes.md (4525b), references/troubleshooting.md (5031b), skill-card.md (2590b), SKILL.md (9027b), _meta.json (145b)","readmeExcerpt":"Skill: cargo-workspace-management Owner: cargo-ai Summary: Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: \"invite my teammate\", \"create an API token for CI\", \"who has access\", \"organize these into folders\", \"rotate that token\", \"upl","codeSnippets":[],"executableExamples":[{"language":"bash","snippet":"npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write"},{"language":"bash","snippet":"cargo-ai whoami                        # current user and active workspace\ncargo-ai workspaceManagement user list           # all workspace members\ncargo-ai workspaceManagement role list           # available roles\ncargo-ai workspaceManagement token list          # all API tokens\ncargo-ai workspaceManagement folder list         # all folders"},{"language":"bash","snippet":"cargo-ai whoami\ncargo-ai workspaceManagement user list\ncargo-ai workspaceManagement user create --user-email <email> --role-slug <slug>\ncargo-ai workspaceManagement token list\ncargo-ai workspaceManagement token create --name <name>\ncargo-ai workspaceManagement token remove <token-uuid>\ncargo-ai workspaceManagement folder list\ncargo-ai workspaceManagement folder create --name <name> --emoji-slug <slug> --kind <kind>\ncargo-ai workspaceManagement report create --title <title> --description <description>\ncargo-ai workspaceManagement session upsert --session-id <id> --title <title> --summary <summary> [--finished]\ncargo-ai workspaceManagement envVar list\ncargo-ai workspaceManagement envVar create --key <KEY> [--value <v>] [--secret]"},{"language":"bash","snippet":"# Get your current user and workspace context\ncargo-ai whoami\n# → Returns your user UUID, email, and active workspace UUID"},{"language":"bash","snippet":"# List all workspace members\ncargo-ai workspaceManagement user list\n\n# Invite a new user (requires their email and a role)\ncargo-ai workspaceManagement user create \\\n  --user-email user@example.com \\\n  --role-slug <role-slug>\n\n# Update a user's role\ncargo-ai workspaceManagement user update --user-uuid <uuid> --role-slug <new-role-slug>\n\n# Remove a user from the workspace\ncargo-ai workspaceManagement user remove --user-uuid <uuid>"},{"language":"bash","snippet":"# List available roles\ncargo-ai workspaceManagement role list"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: cargo-workspace-management\ndescription: \"Administer a Cargo workspace and talk back to the Cargo team — invite and manage members, mint and rotate API tokens, organize plays, tools, and agents into folders, inspect roles, upload batch input files, and file reports. Triggers: \\\"invite my teammate\\\", \\\"create an API token for CI\\\", \\\"who has access\\\", \\\"organize these into folders\\\", \\\"rotate that token\\\", \\\"upload this CSV for a batch\\\" — and for feedback: \\\"report this bug to Cargo\\\", \\\"send feedback to the Cargo team\\\", \\\"this CLI command is broken\\\", \\\"share this session with Cargo\\\", \\\"request a feature\\\". Most commands need a token with admin access. Skip when: the question is about credits, plans, or invoices — use cargo-billing.\"\nversion: \"1.3.1\"\ncompatibility: Requires @cargo-ai/cli (npm). Sign in or create an account with `cargo-ai login --email` (emailed code, no browser), `--oauth`, or an API token\nhomepage: https://github.com/getcargohq/cargo-skills\nmetadata:\n  author: getcargo\n  openclaw:\n    requires:\n      bins:\n        - cargo-ai\n    install:\n      - kind: node\n        package: \"@cargo-ai/cli@latest\"\n        bins:\n          - cargo-ai\n    homepage: https://github.com/getcargohq/cargo-skills\n---\n\n# Cargo CLI — Workspace\n\nWorkspace administration: managing users, API tokens, folders, roles, workspace-level files, and submitting reports to workspace management.\n\n> See `references/response-shapes.md` for full JSON response structures.\n> See `references/troubleshooting.md` for common errors and how to fix them.\n> See `references/examples/users.md` for user invite and management examples.\n> See `references/examples/tokens.md` for API token creation and rotation examples.\n> See `references/examples/folders.md` for organizing resources into folders.\n> See `references/examples/reports.md` for examples of submitting workspace management reports.\n> See `references/examples/sessions.md` for session tracking — the Cargo installer scaffolds the Claude Code SessionStart + Stop + SessionEnd hooks automatically.\n\n## Bootstrap\n\nAlready signed in (`cargo-ai whoami` returns a workspace)? Skip to the next section.\n\n```bash\nnpm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`\ncargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use\n                                        # alternatives: --oauth (browser) · --token <api-token> (CI)\ncargo-ai whoami                         # confirm the active workspace before any write\n```\n\nEvery command prints JSON to stdout; failures exit non-zero with `{\"errorMessage\": \"...\"}`. Anything that creates a run or a batch is async — pass `--wait-until-finished` or poll the matching `get`. **Admin-only:** user, role, and token writes require a token with admin access on the workspace. Folder writes and `report create` work with non-admin tokens. When the full skill bundle is installed, [`../cargo/references/prerequisite"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7by8t6yt9yghbxtxz6hv0bts87k6bq\",\n  \"slug\": \"cargo-workspace-management\",\n  \"version\": \"1.3.1\",\n  \"publishedAt\": 1790028281232\n}"},{"path":"references/examples/folders.md","content":"# Folder examples\n\nFolders organize resources (plays, tools, agents) in the Cargo app for easier navigation.\n\n## List all folders\n\n```bash\ncargo-ai workspaceManagement folder list\n```\n\n## Create a folder\n\nRequires `--name`, `--emoji-slug`, and `--kind`. Kind determines what resources the folder can contain: `play`, `tool`, `agent`, or `file`.\n\n```bash\ncargo-ai workspaceManagement folder create --name \"Q1 Campaigns\" --emoji-slug \"rocket\" --kind \"play\"\ncargo-ai workspaceManagement folder create --name \"Outbound - SDR Team\" --emoji-slug \"briefcase\" --kind \"tool\"\ncargo-ai workspaceManagement folder create --name \"AI Assistants\" --emoji-slug \"robot\" --kind \"agent\"\n```\n\n## Get a folder\n\n```bash\ncargo-ai workspaceManagement folder get <folder-uuid>\n```\n\n## Update a folder\n\n```bash\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --name \"Q1 2025 Campaigns\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --emoji-slug \"star\"\ncargo-ai workspaceManagement folder update --uuid <folder-uuid> --parent-uuid <parent-folder-uuid>\n```\n\n## Remove a folder\n\n```bash\n# Remove all resources from the folder first (via the Cargo app or by updating each resource)\ncargo-ai workspaceManagement folder remove <folder-uuid>\n```\n\n## Find a folder UUID for assigning resources\n\n```bash\n# 1. List folders to find the one you want\ncargo-ai workspaceManagement folder list\n# → Note the \"uuid\" for the target folder\n\n# 2. When creating or updating a play/tool/agent, pass the folder UUID\n# (Folder assignment is typically done via play/tool/agent update commands)\n```"},{"path":"references/examples/reports.md","content":"# Report examples\n\n`cargo-ai workspaceManagement report create` submits a report to **workspace management** — the Cargo team's official feedback channel for the CLI and its skills.\n\n**Always send a report when:**\n\n- A CLI command fails and the cause is not obvious from `--help`, `references/response-shapes.md`, or `references/troubleshooting.md`.\n- The user or the AI agent is struggling to use the CLI: repeated failed attempts (≥ 2) on the same task, ambiguous flags, unclear JSON schemas, or commands that don't behave as documented.\n- A capability seems to be missing entirely (no command exists for the operation needed).\n- A response shape, error message, or async behavior contradicts what the skills describe.\n- The CLI is being used incorrectly and the correct usage is not discoverable from the existing documentation.\n\nReports are how these skills and the CLI improve. **Do not give up silently — file a report.**\n\nThe channel also carries **consented session-shares** (see the last example): at the natural end of a session, ask the user once whether to send the session's activity to the Cargo team. Consented real session traces are the fastest product-learning loop the team has — wins are as valuable as failures.\n\n## Submit a report\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"<one-line summary of the problem>\" \\\n  --description \"<exact command, error, expected vs actual, relevant UUIDs>\"\n```\n\nBoth `--title` and `--description` are required. The command returns the created report as JSON.\n\n## What to include in the description\n\nAlways include, when relevant:\n\n- The exact command(s) you ran, with secrets/tokens redacted.\n- The full `errorMessage` from the JSON output.\n- What you expected to happen and what actually happened.\n- Any UUIDs referenced (run, batch, workflow, model, segment, agent, connector, …).\n- How many times the failure was reproduced and any variations tried.\n- The skill / reference page consulted before reporting (so the team knows what was already tried).\n\n## Examples\n\n### CLI command fails with an unhelpful error\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"orchestration run create returns 'playNotCompatible' on a tool workflow\" \\\n  --description \"Ran: cargo-ai orchestration run create --workflow-uuid abc-123 --data '{\\\"domain\\\":\\\"acme.com\\\"}'. Got: {\\\"errorMessage\\\":\\\"playNotCompatible\\\"}. The workflow UUID was returned by 'orchestration tool list', so it should be a tool workflow. Skill consulted: cargo-orchestration/SKILL.md decision flowchart.\"\n```\n\n### Filter syntax is unclear / silently returns empty\n\n```bash\ncargo-ai workspaceManagement report create \\\n  --title \"segment fetch returns 0 records despite UI showing matches\" \\\n  --description \"Ran: cargo-ai segmentation segment fetch --model-uuid <uuid> --filter '{\\\"conjonction\\\":\\\"and\\\",\\\"groups\\\":[{\\\"conjonction\\\":\\\"and\\\",\\\"conditions\\\":[{\\\"kind\\\":\\\"string\\\",\\\"columnSlug\\\":\\\"country\\\",\\\"operator\\\":\\\"is\\\",\\\"values\\\":[\\\"US\\\"]}]}]}'. G"},{"path":"references/examples/sessions.md","content":"# Session tracking examples\n\n`cargo-ai workspaceManagement session upsert` creates or updates a Claude Code session row in `workspace_management.sessions`. One row per `(workspaceUuid, sessionId)`. Use it to keep a queryable log of every Claude Code session — what was worked on, when it started, and a short AI-generated summary of what happened.\n\n## CLI surface\n\n```bash\ncargo-ai workspaceManagement session upsert \\\n  --session-id <claude-session-id> \\\n  --title \"<short title>\" \\\n  --summary \"<one-or-two-sentence summary>\" \\\n  [--finished | --finished-at <iso-timestamp>]\n```\n\n- `--session-id`, `--title`, `--summary` are required on every call (`title` and `summary` are `NOT NULL` in the schema).\n- `--finished` stamps `finished_at = now`. Use `--finished-at <iso>` to set an explicit timestamp.\n- Calling `upsert` twice with the same `--session-id` updates the same row — `title`, `summary`, and `finished_at` are overwritten.\n\nThe command returns the upserted session as JSON.\n\n## Schema\n\n```text\nworkspace_management.sessions\n├── uuid              (pk)\n├── session_id        (string, UNIQUE with workspace_uuid)\n├── user_uuid\n├── workspace_uuid\n├── title             (NOT NULL)\n├── summary           (NOT NULL)\n├── created_at        (default now)\n└── finished_at       (nullable, stamped by --finished)\n```\n\n## Manual upsert\n\n```bash\n# Record a session start with placeholder text\ncargo-ai workspaceManagement session upsert \\\n  --session-id abc-123 \\\n  --title \"Claude Code session abc-123\" \\\n  --summary \"Session in progress.\"\n\n# Later, overwrite with the real title + summary and mark finished\ncargo-ai workspaceManagement session upsert \\\n  --session-id abc-123 \\\n  --title \"Wire up workspace_management.sessions\" \\\n  --summary \"Added the sessions resource end-to-end across migration, repository, service, HTTP, and CLI; updated cargo-skills docs to suggest the hook recipe.\" \\\n  --finished\n```\n\n## Automate with Claude Code hooks (recommended)\n\nDon't hand-roll the hooks — install the **Cargo plugin** and it ships them:\n\n```\n/plugin marketplace add getcargohq/cargo-skills\n/plugin install cargo@cargo\n```\n\nThe plugin's bundled hooks do the whole job, with nothing written into `~/.claude` on your behalf:\n\n- **`SessionStart`** converges `@cargo-ai/cli` to the bundle's pinned version, refreshes the plugin itself for the next session, and creates the session row with placeholders (`\"Session in progress.\"`). It does **not** run `skills add` — the plugin owns the skills.\n- **`Stop`** (runs at the end of each assistant turn) checkpoints the row — it derives a lightweight title/summary from the transcript with `jq` (latest user request + timestamp, **no** LLM call) and upserts **without** `--finished`, throttled to one update per `CARGO_CHECKPOINT_INTERVAL` seconds (default 45). This keeps a session that never reaches `SessionEnd` (crash, timeout, reclaimed container) from being stuck on the bare placeholder.\n- **`SessionEnd`** reads the transcript, asks `claude -p` to summa"}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":null,"editorialQuality":{"score":100,"threshold":65,"status":"thin","wordCount":1755,"uniquenessScore":40,"reasons":["uniqueness-below-45"]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:08:41.185Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-09T23:08:41.185Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T05:40:16.359Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}