replicas-cli 0.2.180 → 0.2.182

package/dist/index.mjs

@@ -8105,6 +8105,1102 @@ function extractPrNumber(url) {
   return parsed ? String(parsed.number) : null;
 }
 
+// ../shared/src/default-skills/replicas-agent/abilities/docker.ts
+var SECTION = `### Docker
+Start and use the Docker daemon in Replicas workspaces. Docker is pre-installed but the daemon does not auto-start.
+
+**Reference:** \`references/DOCKER.md\`
+
+Use this when:
+- You need to run \`docker\` or \`docker compose\` commands
+- You need to build or run Docker containers
+- Your task involves containerized services or Docker-based workflows`;
+var REFERENCE = `# Docker
+
+Docker is pre-installed in Replicas workspaces, but the daemon does **not** auto-start. You must start it manually before running any \`docker\` or \`docker compose\` commands.
+
+## Starting the Docker Daemon
+
+\`\`\`bash
+sudo service docker start
+\`\`\`
+
+After starting, verify the daemon is running:
+
+\`\`\`bash
+docker info
+\`\`\`
+
+## Important Notes
+
+- **Start once per session.** The daemon stays running until the workspace shuts down. You do not need to restart it between commands.
+- **Check before starting.** If you are unsure whether the daemon is already running, check first to avoid an unnecessary restart:
+  \`\`\`bash
+  docker info > /dev/null 2>&1 || sudo service docker start
+  \`\`\`
+- **Sudo is required** for starting the daemon, but regular \`docker\` commands run without sudo (the user is in the \`docker\` group).
+`;
+var DOCKER_ABILITY = {
+  label: "Docker",
+  description: "Start the daemon, build/run containers, drive `docker compose`.",
+  bullet: "- Using Docker (starting the daemon, running containers, docker compose)",
+  section: SECTION,
+  referenceFile: { name: "DOCKER.md", content: REFERENCE }
+};
+
+// ../shared/src/default-skills/replicas-agent/abilities/github.ts
+var SECTION2 = `### GitHub
+Use the pre-authenticated \`gh\` CLI for pull requests, issues, actions, and API calls.
+
+**Reference:** \`references/GITHUB.md\`
+
+Use this when:
+- You need to create, review, or manage pull requests
+- You need to interact with GitHub issues or actions
+- You need to use the GitHub API for advanced operations
+- You need to include images in PR descriptions`;
+var REFERENCE2 = `# GitHub Integration
+
+This guide covers how to interact with GitHub from within your Replicas workspace.
+
+## Prerequisites
+
+The \`gh\` CLI is pre-installed and authenticated in your workspace. You can verify this:
+
+\`\`\`bash
+gh auth status
+\`\`\`
+
+If authenticated, you can immediately use \`gh\` for all GitHub operations. No additional setup is needed.
+
+## Using the \`gh\` CLI
+
+The GitHub CLI (\`gh\`) is the recommended way to interact with GitHub. It handles authentication, pagination, and API formatting automatically.
+
+### Pull Requests
+
+\`\`\`bash
+# Create a PR
+gh pr create --title "Title" --body "Description"
+
+# List open PRs
+gh pr list
+
+# View a specific PR
+gh pr view 123
+
+# Review/check PR status
+gh pr checks 123
+
+# Merge a PR
+gh pr merge 123
+\`\`\`
+
+### Issues
+
+\`\`\`bash
+# Create an issue
+gh issue create --title "Title" --body "Description"
+
+# View an issue
+gh issue view 123
+
+# List issues
+gh issue list
+
+# Close an issue
+gh issue close 123
+
+# Add a comment
+gh issue comment 123 --body "Your comment"
+\`\`\`
+
+### Repository Operations
+
+\`\`\`bash
+# View repo info
+gh repo view
+
+# Clone a repo
+gh repo clone owner/repo
+
+# List releases
+gh release list
+\`\`\`
+
+### GitHub Actions / Checks
+
+\`\`\`bash
+# List workflow runs
+gh run list
+
+# View a specific run
+gh run view RUN_ID
+
+# Watch a run in progress
+gh run watch RUN_ID
+
+# Re-run failed jobs
+gh run rerun RUN_ID --failed
+\`\`\`
+
+### GitHub API (Advanced)
+
+For operations not covered by \`gh\` subcommands, use the API directly:
+
+\`\`\`bash
+# GET request
+gh api repos/owner/repo/pulls/123/comments
+
+# POST request
+gh api repos/owner/repo/issues/123/comments -f body="Comment text"
+
+# GraphQL query
+gh api graphql -f query='{ repository(owner: "owner", name: "repo") { issues(first: 10) { nodes { title number } } } }'
+\`\`\`
+
+### Working with PR Reviews
+
+\`\`\`bash
+# View PR comments
+gh api repos/owner/repo/pulls/123/comments
+
+# View PR review comments
+gh api repos/owner/repo/pulls/123/reviews
+
+# Submit a review
+gh pr review 123 --approve
+gh pr review 123 --request-changes --body "Changes needed"
+\`\`\`
+
+## Image Uploads in PRs
+
+GitHub does NOT have a public API for uploading images to PRs/issues. When you need to include images:
+- Do NOT use placeholder image URLs
+- Do NOT commit screenshots as files to the repository
+- Upload images to Imgur (or another external host) and use the returned URLs in your PR markdown
+- If you were triggered from Slack, also upload the images to the Slack thread so the user can see them directly
+`;
+var GITHUB_ABILITY = {
+  label: "GitHub",
+  description: "Pre-authenticated `gh` CLI for PRs, issues, releases, and GraphQL.",
+  bullet: "- Interacting with GitHub (creating PRs, managing issues, using the API, etc.)",
+  section: SECTION2,
+  referenceFile: { name: "GITHUB.md", content: REFERENCE2 }
+};
+
+// ../shared/src/default-skills/replicas-agent/abilities/google.ts
+var SECTION3 = `### Google Workspace (Docs, Sheets, Forms, Drive)
+Create and edit Google Docs, Sheets, and Forms via the Replicas gateway. Files are owned by Replicas \u2014 the integration cannot access pre-existing Google content created outside of it.
+
+**Reference:** \`references/GOOGLE.md\`
+
+Use this when:
+- You need to create or edit a Google Doc, Sheet, or Form
+- You need to share, rename, move, or delete a Replicas-created Google file
+- You need to read responses from a Replicas-created Google Form`;
+var REFERENCE3 = `# Google Workspace (Docs, Sheets, Forms, Drive)
+
+This guide covers how to create and edit Google Docs, Sheets, and Forms \u2014 plus do basic Drive file operations \u2014 from inside a Replicas workspace, using the monolith as a gateway to Google's APIs.
+
+## Prerequisites
+
+The integration is configured at the org or user level by the Replicas admin. From inside a workspace you don't have a Google access token directly; instead you call the monolith's \`/v1/gdrive/*\` endpoints, authenticated with your workspace's engine secret. The monolith refreshes the org's (or user's) Google access token and proxies the call.
+
+Quick check that the integration is connected:
+
+\`\`\`bash
+curl -s -X GET "$MONOLITH_URL/v1/gdrive/credentials" \\
+  -H "Authorization: Bearer $REPLICAS_ENGINE_SECRET" \\
+  -H "X-Workspace-Id: $WORKSPACE_ID"
+\`\`\`
+
+- If \`hasCredentials\` is \`true\`: you're good to go.
+- If \`hasCredentials\` is \`false\`: Google has not been connected for this org. Ask the user to go to **Settings \u2192 Integrations \u2192 Google** in the [Replicas dashboard](https://replicas.dev) and connect a Google account. Do not attempt Google operations until it's connected.
+
+Standard auth headers used by every call below:
+
+\`\`\`
+Authorization: Bearer $REPLICAS_ENGINE_SECRET
+X-Workspace-Id: $WORKSPACE_ID
+\`\`\`
+
+For brevity the examples below use a shell variable:
+
+\`\`\`bash
+GDRIVE_AUTH=(-H "Authorization: Bearer $REPLICAS_ENGINE_SECRET" -H "X-Workspace-Id: $WORKSPACE_ID")
+\`\`\`
+
+## Important constraint: drive.file scope
+
+The integration uses the **sensitive-tier \`drive.file\` scope**. That means Replicas can only read and edit Google files **it created itself**. It **cannot**:
+
+- Read or edit a user's pre-existing Google Docs, Sheets, or Forms \u2014 even ones that were shared with the connected Google account.
+- List or search the user's broader Drive.
+- Touch any file that was not created via these gateway endpoints.
+
+If the user asks you to edit an existing doc that Replicas didn't create, tell them this constraint and offer to create a new doc that mirrors what they want.
+
+## Google Docs
+
+### Create a new doc
+
+\`\`\`bash
+curl -s -X POST "$MONOLITH_URL/v1/gdrive/docs" "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{"title":"Meeting notes 2026-05-14"}'
+\`\`\`
+
+Returns the full Doc object; grab \`.documentId\` for follow-up calls.
+
+### Read a doc
+
+\`\`\`bash
+curl -s "$MONOLITH_URL/v1/gdrive/docs/$DOC_ID" "\${GDRIVE_AUTH[@]}"
+\`\`\`
+
+Returns the full document structure \u2014 \`body.content\` is an ordered list of structural elements (paragraphs, tables, etc.) with character indexes you can target for edits.
+
+### Edit a doc (batchUpdate)
+
+The Docs API edits use a list of [structural requests](https://developers.google.com/workspace/docs/api/reference/rest/v1/documents/request). Insert text, then style it; or insert tables, images, page breaks, etc.
+
+\`\`\`bash
+curl -s -X POST "$MONOLITH_URL/v1/gdrive/docs/$DOC_ID/batchUpdate" "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "requests": [
+      { "insertText": { "location": { "index": 1 }, "text": "Hello, world!\\n" } }
+    ]
+  }'
+\`\`\`
+
+Common request types:
+
+- \`insertText\` \u2014 insert plain text at a given index
+- \`deleteContentRange\` \u2014 delete a range
+- \`replaceAllText\` \u2014 find-and-replace
+- \`updateTextStyle\` \u2014 bold/italic/colors/fonts/sizes for a range
+- \`updateParagraphStyle\` \u2014 headings (\`HEADING_1\`..\`HEADING_6\`), alignment, spacing
+- \`createParagraphBullets\` \u2014 turn paragraphs into bulleted/numbered lists
+- \`insertTable\` \u2014 insert a table
+- \`insertInlineImage\` \u2014 insert an image from a URL
+
+Edits are verbose but powerful. Prefer batching many requests into a single \`batchUpdate\` call rather than making many round trips \u2014 it's faster and keeps the doc state consistent.
+
+## Google Sheets
+
+### Create a new spreadsheet
+
+\`\`\`bash
+curl -s -X POST "$MONOLITH_URL/v1/gdrive/sheets" "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{"title":"Q2 metrics"}'
+\`\`\`
+
+Returns the full Spreadsheet object; grab \`.spreadsheetId\`.
+
+### Read a range of cells
+
+\`\`\`bash
+# Range is in A1 notation, e.g. "Sheet1!A1:C10"
+curl -s "$MONOLITH_URL/v1/gdrive/sheets/$SHEET_ID/values/$(printf %s 'Sheet1!A1:C10' | jq -sRr @uri)" \\
+  "\${GDRIVE_AUTH[@]}"
+\`\`\`
+
+### Write a range of cells
+
+\`\`\`bash
+curl -s -X PUT \\
+  "$MONOLITH_URL/v1/gdrive/sheets/$SHEET_ID/values/$(printf %s 'Sheet1!A1:B2' | jq -sRr @uri)?valueInputOption=USER_ENTERED" \\
+  "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "range": "Sheet1!A1:B2",
+    "majorDimension": "ROWS",
+    "values": [
+      ["Name", "Revenue"],
+      ["Q1",   "=SUM(B3:B100)"]
+    ]
+  }'
+\`\`\`
+
+\`valueInputOption=USER_ENTERED\` makes formulas evaluate as if a human typed them. Use \`RAW\` to write literal strings.
+
+### Bulk operations (formatting, charts, new tabs, etc.)
+
+\`\`\`bash
+curl -s -X POST "$MONOLITH_URL/v1/gdrive/sheets/$SHEET_ID/batchUpdate" "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{ "requests": [ { "addSheet": { "properties": { "title": "Raw data" } } } ] }'
+\`\`\`
+
+\`batchUpdate\` accepts an array of [Sheets API requests](https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/request) \u2014 addSheet, updateSheetProperties, repeatCell, addChart, autoResizeDimensions, etc.
+
+## Google Forms
+
+### Create a new form
+
+\`\`\`bash
+curl -s -X POST "$MONOLITH_URL/v1/gdrive/forms" "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{"title":"Customer feedback"}'
+\`\`\`
+
+Returns the form. Grab \`.formId\`.
+
+### Add questions / edit form structure
+
+The Forms API uses its own \`batchUpdate\`:
+
+\`\`\`bash
+curl -s -X POST "$MONOLITH_URL/v1/gdrive/forms/$FORM_ID/batchUpdate" "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "requests": [
+      {
+        "createItem": {
+          "item": {
+            "title": "How likely are you to recommend us?",
+            "questionItem": {
+              "question": {
+                "required": true,
+                "scaleQuestion": { "low": 0, "high": 10, "lowLabel": "Not at all", "highLabel": "Very likely" }
+              }
+            }
+          },
+          "location": { "index": 0 }
+        }
+      }
+    ]
+  }'
+\`\`\`
+
+See the [Forms API Request reference](https://developers.google.com/workspace/forms/api/reference/rest/v1/forms/request) for all supported request types \u2014 text questions, multiple choice, checkboxes, scale, grid, date, time, file upload, section breaks, branching logic, quiz settings, etc.
+
+### Read responses
+
+\`\`\`bash
+curl -s "$MONOLITH_URL/v1/gdrive/forms/$FORM_ID/responses" "\${GDRIVE_AUTH[@]}"
+\`\`\`
+
+Pagination: pass \`?pageToken=...&pageSize=...\` to walk through responses.
+
+## Drive operations (only on Replicas-created files)
+
+### Share a file with a person
+
+\`\`\`bash
+curl -s -X POST "$MONOLITH_URL/v1/gdrive/files/$FILE_ID/permissions" "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "type": "user",
+    "role": "writer",
+    "emailAddress": "alice@example.com",
+    "sendNotificationEmail": true
+  }'
+\`\`\`
+
+Roles: \`reader\`, \`commenter\`, \`writer\`. Types: \`user\`, \`group\`, \`domain\`, \`anyone\`.
+
+### Make a file viewable by anyone with the link
+
+\`\`\`bash
+curl -s -X POST "$MONOLITH_URL/v1/gdrive/files/$FILE_ID/permissions" "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{ "type": "anyone", "role": "reader" }'
+\`\`\`
+
+### List existing permissions
+
+\`\`\`bash
+curl -s "$MONOLITH_URL/v1/gdrive/files/$FILE_ID/permissions" "\${GDRIVE_AUTH[@]}"
+\`\`\`
+
+### Rename / move a file
+
+\`\`\`bash
+curl -s -X PATCH "$MONOLITH_URL/v1/gdrive/files/$FILE_ID" "\${GDRIVE_AUTH[@]}" \\
+  -H "Content-Type: application/json" \\
+  -d '{"name":"Final report.docx"}'
+\`\`\`
+
+To move into a folder, also pass \`addParents\` and \`removeParents\` as query parameters per [Drive API docs](https://developers.google.com/workspace/drive/api/reference/rest/v3/files/update).
+
+### Get file metadata
+
+\`\`\`bash
+curl -s "$MONOLITH_URL/v1/gdrive/files/$FILE_ID?fields=id,name,mimeType,webViewLink,parents,modifiedTime" \\
+  "\${GDRIVE_AUTH[@]}"
+\`\`\`
+
+\`webViewLink\` is the human-shareable URL that opens in Google Docs/Sheets/Forms.
+
+### Delete a file
+
+\`\`\`bash
+curl -s -X DELETE "$MONOLITH_URL/v1/gdrive/files/$FILE_ID" "\${GDRIVE_AUTH[@]}"
+\`\`\`
+
+### List Replicas-created files
+
+\`\`\`bash
+curl -s "$MONOLITH_URL/v1/gdrive/files?pageSize=50" "\${GDRIVE_AUTH[@]}"
+\`\`\`
+
+Pass \`?q=...\` to filter using [Drive API search syntax](https://developers.google.com/workspace/drive/api/guides/search-files). Only files the app created or was granted access to will appear.
+
+## Tips
+
+- **Always return the \`webViewLink\`** to the user when you create or edit a file so they can open it. Get it from \`/v1/gdrive/files/$FILE_ID?fields=webViewLink\` or from \`documents.documentId\` \u2192 \`https://docs.google.com/document/d/$ID/edit\`.
+- **Batch your edits.** A single \`batchUpdate\` with 20 requests beats 20 round-trips.
+- **Watch error responses.** A 412 from the gateway means the org has no Google credentials connected \u2014 tell the user to connect Google in the dashboard. Other 4xx responses come straight from Google and usually explain the issue clearly.
+`;
+var GOOGLE_ABILITY = {
+  label: "Google Workspace",
+  description: "Create / edit Docs, Sheets, Forms, and Drive files via the Replicas gateway.",
+  bullet: "- Interacting with Google Workspace (creating and editing Docs, Sheets, and Forms, sharing files, reading form responses, etc.)",
+  section: SECTION3,
+  referenceFile: { name: "GOOGLE.md", content: REFERENCE3 }
+};
+
+// ../shared/src/default-skills/replicas-agent/abilities/linear.ts
+var SECTION4 = `### Linear
+Fetch issues, update state, add comments, and search via the Linear GraphQL API.
+
+**Reference:** \`references/LINEAR.md\`
+
+Use this when:
+- You encounter a Linear issue link and need to understand the task
+- You need to update an issue's state (e.g. mark as done)
+- You need to comment on or search for Linear issues`;
+var REFERENCE4 = `# Linear Integration
+
+This guide covers how to interact with Linear from within your Replicas workspace.
+
+## Prerequisites
+
+Check if the \`LINEAR_ACCESS_TOKEN\` environment variable is set:
+
+\`\`\`bash
+echo "\${LINEAR_ACCESS_TOKEN:+set}"
+\`\`\`
+
+- If **set**: Your workspace has Linear access. You can use the Linear GraphQL API as described below.
+- If **not set**: Linear has not been configured for this workspace. The user needs to connect Linear in the [Replicas dashboard](https://replicas.dev) under their organization's integration settings. Let the user know and do not attempt Linear operations.
+
+## Using the Linear API
+
+Linear uses a GraphQL API at \`https://api.linear.app/graphql\`. All requests use the \`$LINEAR_ACCESS_TOKEN\` for authentication.
+
+### Fetching an Issue
+
+If you encounter a Linear issue link (e.g. \`https://linear.app/team/issue/ENG-123\`), the identifier is the last path segment (\`ENG-123\`).
+
+\`\`\`bash
+curl -s -X POST https://api.linear.app/graphql \\
+  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "query": "query { issues(filter: { identifier: { eq: \\"ENG-123\\" } }) { nodes { id identifier title description state { name } assignee { name } parent { identifier title description } } } }"
+  }'
+\`\`\`
+
+### Updating Issue State
+
+\`\`\`bash
+curl -s -X POST https://api.linear.app/graphql \\
+  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "query": "mutation { issueUpdate(id: \\"ISSUE_UUID\\", input: { stateId: \\"STATE_UUID\\" }) { success issue { identifier state { name } } } }"
+  }'
+\`\`\`
+
+To find available states, query: \`query { workflowStates { nodes { id name } } }\`
+
+### Adding a Comment
+
+\`\`\`bash
+curl -s -X POST https://api.linear.app/graphql \\
+  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "query": "mutation { commentCreate(input: { issueId: \\"ISSUE_UUID\\", body: \\"Your comment here\\" }) { success comment { id } } }"
+  }'
+\`\`\`
+
+### Searching Issues
+
+\`\`\`bash
+curl -s -X POST https://api.linear.app/graphql \\
+  -H "Authorization: Bearer $LINEAR_ACCESS_TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "query": "query { issueSearch(query: \\"search terms\\", first: 10) { nodes { identifier title state { name } } } }"
+  }'
+\`\`\`
+
+### Other Operations
+
+The Linear GraphQL API supports creating issues, managing projects, labels, cycles, and more. For the full schema and documentation, see: https://developers.linear.app/docs/graphql/working-with-the-graphql-api
+`;
+var LINEAR_ABILITY = {
+  label: "Linear",
+  description: "Fetch issues, post comments, update states via the Linear GraphQL API.",
+  bullet: "- Interacting with Linear (fetching issues, updating state, commenting, etc.)",
+  section: SECTION4,
+  referenceFile: { name: "LINEAR.md", content: REFERENCE4 }
+};
+
+// ../shared/src/default-skills/replicas-agent/abilities/media.ts
+var SECTION5 = `### Media
+Share screenshots, screen recordings, generated diagrams, and audio clips inline in the Replicas chat (and as references in external messages).
+
+**Reference:** \`references/MEDIA.md\`
+
+Use this when:
+- You produce a screenshot, recording, generated image, or audio clip the user should see
+- You record video output (browser automation, screen capture) \u2014 including the recommended aspect ratio and FPS
+- You need to embed media in a Slack/Linear/GitHub message AND keep a referenceable copy in the Replicas dashboard`;
+var REFERENCE5 = `# Media (Screenshots, Recordings, Audio)
+
+This guide covers how to share screenshots, screen recordings, generated diagrams, and audio clips with the user inline in the Replicas chat.
+
+## Prerequisites
+
+The \`replicas\` CLI is pre-installed and authenticated in your workspace. No additional setup is needed.
+
+## When to upload
+
+Upload to Replicas in these cases \u2014 and **only** these cases:
+
+1. **Media you produce.** Any screenshot, screen recording, generated diagram, or audio clip you create that the user might want to see. Upload before doing anything else with the file (analyzing, deleting, sending elsewhere). This applies even when you're also sending the file to Slack, Linear, GitHub, etc.
+2. **Files the user explicitly asks you to upload.** If the user sends or points at a file (image, video, audio) and asks you to upload it, run \`replicas media upload\`. Otherwise leave it alone \u2014 files in the workspace the user did not ask about should not be auto-uploaded as media.
+3. **Anything you plan to share externally (Slack, Linear, GitHub, etc.).** Upload to Replicas *in addition to* the platform's native upload. Never as a replacement.
+
+If none of these apply, don't upload.
+
+## Uploading
+
+\`\`\`bash
+replicas media upload <path-to-file> [<path-to-file> ...]
+\`\`\`
+
+Pass one or more file paths. Uploading several files in a single invocation is preferred over running the command repeatedly \u2014 it's faster and keeps the output grouped.
+
+For each file, the CLI prints two lines:
+
+1. \`![filename](<api-url>)\` \u2014 the chat embed (renders inline in Replicas chat only; see below).
+2. \`View in Replicas: <deep-link>\` \u2014 a per-file dashboard URL of the form \`https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id>\` that opens directly to that specific file.
+
+Match each "View in Replicas" line to the embed line directly above it \u2014 that's the deep link for that file.
+
+## How to use the output
+
+### CRITICAL: the markdown embed URL is for Replicas chat only
+
+The URL inside \`![filename](...)\` points at \`api.tryreplicas.com/v1/media/<id>\`. This is **not a public URL** \u2014 it requires the Replicas chat's authenticated session, which resolves it to a presigned download. Anywhere else (Slack, Linear, GitHub, a browser tab the user opens directly, a customer copy-pasting from chat), it returns \`{"error":"Missing authorization token"}\` and renders as a broken image.
+
+**Never paste this URL outside your Replicas chat reply.** Not in Slack messages, not in Linear comments, not in PR descriptions or commit messages, not in external docs \u2014 nowhere a non-Replicas surface will render it.
+
+### Always render dashboard URLs as \`[View in Replicas](<url>)\` hyperlinks
+
+Whenever you share a workspace dashboard URL \u2014 in chat or anywhere else \u2014 format it as a markdown hyperlink labeled **View in Replicas**:
+
+\`\`\`markdown
+[View in Replicas](https://tryreplicas.com/workspaces/<workspace-id>?mode=media&media=<media-id>)
+\`\`\`
+
+Never paste the raw URL. Raw URLs look unpolished.
+
+Two flavors of dashboard URL the CLI gives you:
+
+- **Per-file deep link** (default \u2014 what \`replicas media upload\` prints): \`...?mode=media&media=<media-id>\` opens the dashboard scrolled to that specific file. Use this whenever you're linking to *one* file.
+- **Media tab link** (no \`media=\` param): \`...?mode=media\` opens the workspace's media tab listing all files. Use this only when you're pointing at the collection, not a specific file (rare \u2014 you almost always have a specific file in mind).
+
+### In your Replicas chat reply
+
+Include each markdown embed line **verbatim** where you want that file to render inline. The chat substitutes each one with an embedded image, video, or audio player. Multiple embeds can appear in a single reply.
+
+After (or alongside) the embeds, include a \`[View in Replicas](<deep-link>)\` hyperlink for each file using the per-file URL the CLI printed for that file. This lets the user jump to the specific item in the media tab.
+
+### On external platforms (Slack, Linear, GitHub, etc.)
+
+Do **both** of these \u2014 neither alone is sufficient:
+
+1. Upload the raw bytes via that platform's own upload API (Slack \`files.upload\`, Linear attachments, Imgur for GitHub PR/issue images, etc.) so the recipient actually sees the media.
+2. Include a \`[View in Replicas](<deep-link>)\` hyperlink \u2014 use the per-file deep link the CLI printed for that file (\`...?mode=media&media=<media-id>\`), so the recipient lands directly on that specific item.
+
+Do **not** include the \`![filename](https://api.tryreplicas.com/...)\` markdown embed in external messages. It will render as a broken image / 401 for the recipient.
+
+## Recording defaults
+
+When you record video (browser automation, screen capture, etc.):
+
+- **Aspect ratio:** 16:9 (1920\xD71080 or 1280\xD7720)
+- **Frame rate:** 60 FPS or whatever the user specifies
+
+Tools like Playwright default to a low frame rate that produces choppy playback \u2014 explicitly configure recording dimensions and FPS:
+
+\`\`\`ts
+const context = await browser.newContext({
+  recordVideo: { dir: './videos', size: { width: 1280, height: 720 } },
+});
+\`\`\`
+
+For \`ffmpeg\` screen captures, pass \`-r 30\` (or \`-r 60\`) to set the frame rate.
+
+## Supported formats
+
+Auto-detected from the filename extension:
+
+| Extension | Kind |
+|---|---|
+| \`png\`, \`jpg\`, \`jpeg\`, \`webp\` | image |
+| \`mp4\`, \`webm\` | video |
+| \`mp3\`, \`wav\` | audio |
+
+For other extensions, pass \`--kind image|video|audio\` explicitly. The kind applies to every file in that invocation, so group files of the same kind together:
+
+\`\`\`bash
+replicas media upload diagram.svg --kind image
+replicas media upload chart-a.svg chart-b.svg --kind image
+\`\`\`
+
+## Options
+
+- \`--kind <image|video|audio>\` \u2014 override auto-detection
+- \`--session-id <id>\` \u2014 associate the upload with a specific session
+`;
+var MEDIA_ABILITY = {
+  label: "Media",
+  description: "Share screenshots, recordings, generated images, and audio clips.",
+  bullet: "- Sharing media (screenshots, screen recordings, generated diagrams, audio clips) \u2014 including in your Replicas chat reply and to external platforms",
+  section: SECTION5,
+  referenceFile: { name: "MEDIA.md", content: REFERENCE5 }
+};
+
+// ../shared/src/default-skills/replicas-agent/abilities/previews.ts
+var SECTION6 = `### Previews
+Expose locally running services (web apps, APIs, databases) as public preview URLs so humans can interact with them directly.
+
+**Reference:** \`references/PREVIEWS.md\`
+
+Use this when:
+- You need to start a service that a human should view or interact with
+- The task involves UI work that benefits from human review
+- You are verifying frontend/backend integrations visually`;
+var REFERENCE6 = `# Preview URLs
+
+When you run services on ports \u2014 such as a web app, API server, or database \u2014 humans may want to interact with them directly. You can expose your locally running services as public preview URLs.
+
+## Running Services for Preview
+
+Services must run as detached background processes so they survive after your command session ends. Do not leave them attached to a foreground terminal.
+
+Some potential methods:
+\`\`\`bash
+# Start a detached service with logging
+setsid -f bash -lc 'cd /path/to/app && exec yarn dev >> /tmp/app.log 2>&1'
+
+# For daemons like Docker
+nohup dockerd > /tmp/dockerd.log 2>&1 &
+\`\`\`
+
+After starting a service:
+1. Verify the process is running: \`pgrep -af 'yarn dev'\`
+2. Check logs for readiness: \`tail -f /tmp/app.log\`
+3. Confirm it's actually serving: \`curl -s http://localhost:3000\` (or appropriate health check)
+4. Only create the preview after the service is healthy
+
+If a prior detached process exists on the same port, stop it before restarting.
+
+## Creating Previews
+
+\`\`\`bash
+# Expose a local port as a public URL
+replicas preview create <port>
+
+# Expose a port with authentication (requires Replicas login to access)
+replicas preview create <port> --authenticated
+
+# List all active preview URLs
+replicas preview list
+\`\`\`
+
+The \`create\` command prints the public URL. You can also read all active previews from \`~/.replicas/preview-ports.json\`.
+
+## Authenticated vs Unauthenticated Previews
+
+Previews can optionally require cookie-based authentication. When \`--authenticated\` is set, only users who are logged in to replicas.dev can access the preview.
+
+**When to use \`--authenticated\`:**
+- Frontends / web apps that humans will view directly in their browser. Since the user is already logged in to replicas.dev, the auth cookie is automatically present and the preview works seamlessly.
+
+**When NOT to use \`--authenticated\`:**
+- Backend APIs and other services that are called by frontend code. The frontend runs in the user's browser under a different origin, so it cannot forward the Replicas auth cookie to the backend. Making backends authenticated will cause cross-service requests to fail with 401 errors.
+
+**Rule of thumb:** Make frontend previews authenticated, leave backend/API previews unauthenticated.
+
+## Cross-Service References
+
+When you expose multiple services that reference each other, you must update their configuration so they use preview URLs instead of \`localhost\`.
+
+**Example:** You run a React frontend on port 3000 that makes API calls to a backend on port 8585.
+
+1. Create previews for both:
+   \`\`\`bash
+   replicas preview create 8585
+   # Output: https://8585-<hash>.replicas.dev
+   replicas preview create 3000 --authenticated
+   # Output: https://3000-<hash>.replicas.dev
+   \`\`\`
+
+2. Update the frontend's environment so its API base URL points to the backend's **preview URL**, not \`localhost:8585\`. For example, set \`REACT_APP_API_URL=https://8585-<hash>.replicas.dev\` or update the relevant config file.
+
+**Why?** The frontend works on \`localhost\` for you because both services run on the same machine. But a human viewing the preview is on a different machine \u2014 requests to \`localhost:8585\` from their browser will fail. They need the public preview URL instead.
+
+## When to Create Previews
+
+- After starting any service that a human should be able to view or interact with
+- When verifying frontend/backend integrations visually
+- When the task involves UI work that benefits from human review
+
+It is your responsibility to make previews work for outsiders as well as they work for you on localhost. If at any time you need to see the public URLs that have been created, read \`~/.replicas/preview-ports.json\`.
+`;
+var PREVIEWS_ABILITY = {
+  label: "Previews",
+  description: "Expose locally running services on public preview URLs for humans.",
+  bullet: "- Creating preview URLs for locally running services",
+  section: SECTION6,
+  referenceFile: { name: "PREVIEWS.md", content: REFERENCE6 }
+};
+
+// ../shared/src/default-skills/replicas-agent/abilities/replicas.ts
+var SECTION7 = `### Replicas (in-workspace CLI)
+Take action *with* Replicas itself \u2014 manage automations, environments (variables, files), repos, and \`replicas.json\` config \u2014 using the pre-installed, pre-authenticated \`replicas\` CLI.
+
+**Reference:** \`references/REPLICAS.md\`
+
+Use this when:
+- The user asks you to create, edit, run, or delete an automation
+- The user asks you to manage environments, environment variables, or environment files
+- The user asks "what envs / repos / automations do I have?"
+- The user asks you to scaffold a \`replicas.json\` / \`replicas.yaml\` in a repo`;
+var REFERENCE7 = `# Replicas (in-workspace CLI)
+
+This guide covers how to take action *with* Replicas itself from inside a Replicas workspace \u2014 managing automations, environments (and their variables/files), repos, previews, and the user's \`replicas.json\` config \u2014 using the pre-installed \`replicas\` CLI.
+
+When the user asks _about_ Replicas (concepts, pricing, how a feature works), check https://docs.replicas.dev first. When the user asks you to _do_ something in their Replicas org, this is the file to use.
+
+## Prerequisites
+
+The CLI is pre-installed in every workspace and pre-authenticated using the workspace's engine secret. You do **not** need to log in or set an API key. Verify:
+
+\`\`\`bash
+replicas whoami
+\`\`\`
+
+Expected output (in agent mode):
+
+\`\`\`
+Workspace identity:
+  Workspace ID:    <uuid>
+  Organization ID: <uuid>
+\`\`\`
+
+If you get "Not logged in", the workspace is misconfigured \u2014 surface this to the user instead of trying to work around it.
+
+In agent mode the CLI hides commands that don't make sense for in-workspace agents (\`login\`, \`logout\`, \`codex-auth\`, \`claude-auth\`, \`org switch\`, \`config\`, \`interact\`, \`code\`, replica/workspace top-level CRUD). What you have is:
+
+| Command | What it does |
+| --- | --- |
+| \`replicas whoami\` | Print the workspace + org identity |
+| \`replicas init\` | Create a \`replicas.json\` / \`replicas.yaml\` in the current directory |
+| \`replicas connect <name>\` | SSH into another workspace (requires user creds \u2014 usually only useful when scripting locally) |
+| \`replicas repos\` | List repos connected to the org |
+| \`replicas environment ...\` | Manage environments, env vars, env files |
+| \`replicas automation ...\` | Manage automations (cron + GitHub event triggers) |
+| \`replicas preview ...\` | Register / list preview URLs (covered in \`PREVIEWS.md\`) |
+| \`replicas media ...\` | Upload screenshots, videos, audio (covered in \`MEDIA.md\`) |
+
+\`replicas <command> --help\` is always the source of truth for flags.
+
+## Picking the right command for the user's request
+
+| User says... | Run |
+| --- | --- |
+| "What environments do I have?" | \`replicas environment list\` |
+| "Add API key X to my staging env" | \`replicas environment vars set <env> <KEY> <VALUE>\` |
+| "Make me a \`.env\` file in the workspace with these vars" | \`replicas environment files set <env> .env --content "..."\` |
+| "Create a new env for my \`acme/web\` repo" | \`replicas environment create <name> -r acme/web\` |
+| "What automations do I have?" | \`replicas automation list\` |
+| "Run my nightly automation now" | \`replicas automation run <id>\` |
+| "Make an automation that runs every weekday at 9am" | \`replicas automation create\` (interactive) or \`--trigger-cron "0 9 * * 1-5"\` |
+| "Make an automation that runs when a PR opens on \`acme/web\`" | \`replicas automation create ... --trigger-github pull_request.opened --trigger-github-repos acme/web\` |
+| "What repos are connected?" | \`replicas repos\` |
+| "Set up a \`replicas.json\` in this repo" | \`replicas init\` (\`-y\` for YAML) |
+
+## Environments
+
+Environments are the org-scoped *primitives* workspaces are built from. Each environment can bind to one repository (or repository set), carry environment variables, project files, enabled skills, and MCP servers. The \`Global\` environment is special \u2014 its vars/files/skills/MCPs apply to *every* workspace in the org, but it has no repo binding and can't back a workspace on its own.
+
+### List / get / create / edit / delete
+
+\`\`\`bash
+replicas environment list
+replicas environment get <id-or-name>          # use "global" for the Global env
+replicas environment create [name] \\
+  --description "..." \\
+  --repository <repo-name-or-id> \\
+  --system-prompt "..."
+replicas environment edit <id-or-name> \\
+  --name "..." --description "..." \\
+  --repository <repo-name-or-id>          # pass empty string to unbind
+replicas environment delete <id-or-name> [--force]
+\`\`\`
+
+Notes:
+- Environments resolve by **name or UUID**. \`global\` is an alias for the org's Global env.
+- Non-global envs need a repo (or repo set) to back a workspace. If you \`create\` without \`--repository\`, the CLI prompts; in non-interactive contexts pass \`-r\`.
+- \`edit\` on the Global env is rejected by the API \u2014 manage its contents through the \`vars\` / \`files\` subcommands instead.
+
+### Environment variables
+
+\`\`\`bash
+replicas environment vars list <env>
+replicas environment vars set <env> <KEY> <VALUE>     # upsert (create or update)
+replicas environment vars delete <env> <KEY|VARIABLE_ID> [--force]
+\`\`\`
+
+\`vars set\` is upsert: if a variable with that key already exists, it's updated; otherwise created. The CLI accepts either the variable's \`key\` or its UUID for \`delete\`.
+
+These variables are injected into every workspace built from this environment as actual \`env\` vars \u2014 perfect for API keys, feature flags, etc. Anything you want available to the agent's tools (Claude, codex, your code, etc.) goes here.
+
+### Environment files
+
+Files materialize on the workspace filesystem when a workspace starts, at the destination path you specify. Use this for things like \`.env\` files at the repo root, dotfiles in \`~\`, prompt files for agents, etc.
+
+\`\`\`bash
+replicas environment files list <env>
+replicas environment files set <env> <destination-path> --content "..."        # inline
+replicas environment files set <env> <destination-path> --file <local-path>    # from local file
+replicas environment files set <env> <destination-path> --file <local-path> --name "Friendly name"
+replicas environment files delete <env> <destination-path|FILE_ID> [--force]
+\`\`\`
+
+Constraints:
+- Each file is capped at 64KB.
+- \`set\` is upsert (matched by destination path).
+- The display \`--name\` defaults to the basename of the destination path; override only if it would be unclear in the dashboard list.
+
+## Automations
+
+Automations are saved prompts with one or more triggers (cron schedules and/or GitHub events). When fired, they create a workspace using the configured environment and run the prompt with the user's coding agent.
+
+### List / get / run / delete
+
+\`\`\`bash
+replicas automation list
+replicas automation get <id>
+replicas automation run <id>          # cron-triggered automations only
+replicas automation delete <id> [--force]
+\`\`\`
+
+### Create
+
+Either fully flag-driven or fully interactive \u2014 the CLI prompts for anything you don't pass.
+
+\`\`\`bash
+# Cron trigger
+replicas automation create "Nightly typecheck" \\
+  --prompt "Run \\\`bun typecheck\\\` and report any new errors" \\
+  --environment <env-name-or-id> \\
+  --trigger-cron "0 4 * * *" \\
+  --trigger-cron-timezone "America/New_York"
+
+# GitHub trigger (filter to specific repos)
+replicas automation create "Review my PRs" \\
+  --prompt "Leave a code review on this PR" \\
+  --environment <env-name-or-id> \\
+  --trigger-github pull_request.opened \\
+  --trigger-github-repos acme/web,acme/api
+
+# Disable on creation
+replicas automation create ... --disabled
+
+# Workspace lifecycle
+replicas automation create ... --lifecycle delete_when_done
+replicas automation create ... --lifecycle delete_after_inactivity --auto-stop-minutes 30
+\`\`\`
+
+When the user says "make me an automation that...", default to **picking the environment for them by listing the available envs** and asking only when the user hasn't already pinned one. Same for repos in GitHub triggers. Don't pepper the user with questions you can answer by reading the existing config.
+
+### Edit
+
+\`\`\`bash
+replicas automation edit <id> \\
+  --name "..." \\
+  --prompt "..." \\
+  --enabled true|false \\
+  --environment <env-name-or-id> \\
+  --trigger-cron "0 4 * * *"   # replaces existing triggers
+\`\`\`
+
+\`replicas automation edit <id>\` with no flags drops into interactive mode.
+
+## Repositories
+
+Read-only listing of repos connected to the org. Use when the user asks "what repos can I use?", or to validate a \`--repository\` value before passing it to \`environment create\` / \`automation create\`:
+
+\`\`\`bash
+replicas repos
+\`\`\`
+
+Repos are connected via the GitHub integration in the dashboard \u2014 not from the CLI. If the user wants a repo connected, point them at the dashboard rather than trying to do it yourself.
+
+## \`replicas.json\` / \`replicas.yaml\`
+
+\`replicas init\` creates a starter config in the current directory. \`-y\` writes YAML, \`-f\` overwrites an existing file. This file controls per-repo workspace setup (warm hooks, start hooks, organization scoping for GitHub triggers). When the user asks to "set up Replicas in this repo", run \`replicas init\` and then edit the generated file based on what they need.
+
+## When NOT to use the CLI
+
+- **Don't use the CLI to reach into other tools' state** (Linear, Slack, GitHub) \u2014 those have dedicated skill references in this directory.
+- **Don't try to install Replicas, log in, or switch orgs** \u2014 those flows are user-facing and aren't available in agent mode anyway.
+- **Don't create workspaces** from inside an existing workspace just to run a command. You're already in one.
+
+## Common errors
+
+- \`Missing Replicas-Org-Id header\` \u2192 the workspace is hitting an older monolith that doesn't yet recognize agent auth on this endpoint. Surface this to the user; don't try to work around it by faking headers.
+- \`Workspace not found\` \u2192 the workspace was deleted while you were running. Stop and tell the user.
+- \`An environment with this name already exists\` \u2192 use \`environment edit\` instead, or pick a different name.
+- \`Cannot delete the global environment\` \u2192 there is exactly one Global env per org and it's permanent. Manage its *contents* (\`vars\`, \`files\`) instead.
+`;
+var REPLICAS_ABILITY = {
+  label: "Replicas",
+  description: "Teach the agent about Replicas itself \u2014 automations, environments, the in-workspace CLI.",
+  // No bullet — help_instructions covers the `replicas` CLI surface in detail.
+  bullet: "",
+  section: SECTION7,
+  referenceFile: { name: "REPLICAS.md", content: REFERENCE7 },
+  locked: true
+};
+
+// ../shared/src/default-skills/replicas-agent/abilities/slack.ts
+var SECTION8 = `### Slack
+Send messages, read threads, search conversations, and upload files via the Slack Web API.
+
+**Reference:** \`references/SLACK.md\`
+
+Use this when:
+- You need to send a message to a Slack channel or thread
+- You need to read or fetch a Slack conversation
+- You encounter a Slack message link and need to retrieve its content
+- The task asks you to notify, update, or communicate via Slack`;
+var REFERENCE8 = `# Slack Integration
+
+This guide covers how to interact with Slack from within your Replicas workspace.
+
+## Prerequisites
+
+Check if the \`SLACK_BOT_TOKEN\` environment variable is set:
+
+\`\`\`bash
+echo "\${SLACK_BOT_TOKEN:+set}"
+\`\`\`
+
+- If **set**: Your workspace has Slack access. You can use the Slack Web API as described below.
+- If **not set**: Slack has not been configured for this workspace. The user needs to connect Slack in the [Replicas dashboard](https://replicas.dev) under their organization's integration settings. Let the user know and do not attempt Slack operations.
+
+## Using the Slack API
+
+All requests use the \`$SLACK_BOT_TOKEN\` for authentication via the Slack Web API.
+
+### Fetching a Thread from a Slack Link
+
+If you encounter a Slack message link (e.g. \`https://team.slack.com/archives/C0123ABC/p1234567890123456\`), extract the channel ID and thread timestamp:
+
+- **Channel ID**: The segment after \`/archives/\` (e.g. \`C0123ABC\`)
+- **Thread TS**: The \`p\` value with a dot inserted before the last 6 digits (e.g. \`p1234567890123456\` -> \`1234567890.123456\`)
+
+\`\`\`bash
+curl -s "https://slack.com/api/conversations.replies?channel=CHANNEL_ID&ts=THREAD_TS" \\
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN"
+\`\`\`
+
+### Sending a Message
+
+\`\`\`bash
+curl -s -X POST "https://slack.com/api/chat.postMessage" \\
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \\
+  -H "Content-Type: application/json" \\
+  -d '{
+    "channel": "CHANNEL_ID",
+    "text": "Your message here",
+    "thread_ts": "OPTIONAL_THREAD_TS"
+  }'
+\`\`\`
+
+Omit \`thread_ts\` to post a new message to the channel. Include it to reply in a thread.
+
+### Searching Messages
+
+\`\`\`bash
+curl -s "https://slack.com/api/search.messages?query=YOUR_SEARCH_QUERY" \\
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN"
+\`\`\`
+
+### Uploading Files
+
+\`\`\`bash
+curl -s -X POST "https://slack.com/api/files.uploadV2" \\
+  -H "Authorization: Bearer $SLACK_BOT_TOKEN" \\
+  -F "channel_id=CHANNEL_ID" \\
+  -F "file=@/path/to/file" \\
+  -F "title=File title"
+\`\`\`
+
+### Other Operations
+
+You can list channels, read channel history, add reactions, and perform any other operation supported by the Slack Web API using the same authentication pattern.
+
+For full API documentation, see: https://docs.slack.dev/apis/web-api/
+`;
+var SLACK_ABILITY = {
+  label: "Slack",
+  description: "Send messages, read threads, search conversations, upload files.",
+  bullet: "- Interacting with Slack (sending messages, reading threads, etc.)",
+  section: SECTION8,
+  referenceFile: { name: "SLACK.md", content: REFERENCE8 }
+};
+
+// ../shared/src/default-skills/replicas-agent/registry.ts
+var REPLICAS_AGENT_ABILITY_REGISTRY = {
+  replicas: REPLICAS_ABILITY,
+  docker: DOCKER_ABILITY,
+  github: GITHUB_ABILITY,
+  google: GOOGLE_ABILITY,
+  linear: LINEAR_ABILITY,
+  media: MEDIA_ABILITY,
+  previews: PREVIEWS_ABILITY,
+  slack: SLACK_ABILITY
+};
+var REPLICAS_AGENT_ABILITIES = Object.keys(
+  REPLICAS_AGENT_ABILITY_REGISTRY
+);
+
+// ../shared/src/routes/preferences.ts
+var DEFAULT_REPLICAS_AGENT_ABILITIES = Object.fromEntries(
+  REPLICAS_AGENT_ABILITIES.map((key) => [key, true])
+);
+var DEFAULT_DEFAULT_SKILLS = {
+  replicas_agent: {
+    enabled: true,
+    abilities: { ...DEFAULT_REPLICAS_AGENT_ABILITIES }
+  }
+};
+
 // ../shared/src/prompts.ts
 var REPLICAS_INSTRUCTIONS_TAG = "replicas_instructions";
 function removeTag(text, tag) {
@@ -14843,7 +15939,7 @@ Deleted file ${pathOrId}.
 }
 
 // src/index.ts
-var CLI_VERSION = "0.2.180";
+var CLI_VERSION = "0.2.182";
 function parseBooleanOption(value) {
   if (value === "true") return true;
   if (value === "false") return false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "replicas-cli",
-  "version": "0.2.180",
+  "version": "0.2.182",
   "description": "CLI for managing Replicas workspaces - SSH into cloud dev environments with automatic port forwarding",
   "main": "dist/index.mjs",
   "bin": {