flashcatcloud · flashduty · Sep 22, 2026
diff --git a/en/ai-sre/agents.mdx b/en/ai-sre/agents.mdx
@@ -49,13 +49,22 @@ The platform ships several **bootstrap Subagents** that work out of the box:
 | `general` | General-purpose worker with full tool access. Use it to offload work whose intermediate steps would otherwise pollute the parent's context (long reports, multi-file edits, end-to-end builds, repeated probing). Dispatch several in parallel for independent units of work |
 | `explore` | Read-only investigator restricted to `grep` / `glob` / `read`; it cannot write or execute. Returns a compact summary rather than raw search output — ideal for locating evidence inside a codebase or knowledge dump |
 
-**In the conversation**: each dispatch also appears as a **task card** in the conversation stream and shares the same status lifecycle as an A2A delegation (initializing / in progress / awaiting input / awaiting authorization / completed / failed (including orphaned) / interrupted / killed). The difference is the badge — a Subagent task card carries an `Agent` badge, whereas an A2A delegation carries an `A2A` badge.
+**In the conversation**: each dispatch also appears as a **task card** in the conversation stream and shares the same status lifecycle as an A2A delegation (initializing / in progress / awaiting input / awaiting authorization / completed / failed (including orphaned) / interrupted / killed). The difference is the badge — a Subagent task card carries an `Agent` badge, whereas an A2A delegation carries an `A2A` badge. A Subagent card's reference line also leads its right-hand side with the **execution environment this dispatch runs in** (the cloud environment, or the BYOC Runner's name), so you can see where a subtask executed straight from the card — see "Dispatch target environment" below.
 
 **Runtime limits**:
 
 - **Concurrency cap**: a session runs **at most 20 Subagents concurrently** (`TaskMaxConcurrentPerSession = 20`). This caps how many run at the same instant, not how many a session dispatches over its lifetime — completing one frees a slot, so total work is unbounded. Dispatching past the cap errors (`too many active subagents (… running, limit 20)`), prompting the model to stop and wait for the running ones to finish before dispatching the rest.
 - **Nesting depth**: a dispatch chain nests **at most 3 levels deep** (`TaskMaxNestingDepth = 3`), preventing a Subagent from spawning itself indefinitely.
 
+**Dispatch target environment**: `agent_dispatch` also takes an optional `environment` argument that decides **which execution environment** the subtask runs in. Its values are:
+
+- **Omitted (the default)**: the subagent runs in the **same** environment as the current session and **shares its filesystem** — it can read your workspace's files directly. Naming the environment the session is *already* in (say, passing `cloud` from a cloud session) has the same result: an inheritance, not a second sandbox.
+- **`cloud`**: runs in a **fresh cloud environment** — an ephemeral container with its own filesystem and the account's default egress policy.
+- **A BYOC Runner's environment_id**: runs on **that Runner**. The selectable targets are **account-scope Runners** plus the Runners of the **team the session is bound to**, and online ones only; same-named Runners are tagged with their team so they can be told apart. `agent_dispatch`'s own description lists them, and each Runner's id is the value to pass. Naming an unusable Runner (offline, nonexistent, or belonging to another team) makes the dispatch fail outright with the reason — it is never silently re-routed elsewhere.
+- **Subagents only**: passing `environment` for an A2A Agent is rejected — a remote agent executes in its own environment and has no placement to choose; to move work to another environment, dispatch a Subagent.
+
+**A cross-environment dispatch cannot read the parent's files**: a child session shares the parent's sandbox / workspace only when its execution environment is **exactly the same**; dispatched to another environment, it gets **its own** sandbox or Runner scratch directory and **cannot see your (the parent's) files**. So put everything it needs **in the prompt** (file contents, paths, parameters, constraints) instead of writing "read file x in the workspace", and expect results back as **text** or through an external system (git, a ticket). See [Environments (BYOC)](/en/ai-sre/environments) for how the environments themselves differ and how to pick one.
+
 <Note>
 **Subagents currently have no user-facing create / management UI.** They are a built-in runtime capability: you can observe Subagent task cards and their sub-session traces within a session, but you cannot add, edit, or delete a Subagent the way you can an A2A Agent. This page (Agents) currently manages only A2A Agents.
 </Note>

diff --git a/en/ai-sre/artifacts.mdx b/en/ai-sre/artifacts.mdx
@@ -1,6 +1,6 @@
 ---
 title: Artifacts
-description: The artifact gallery collects files that AI SRE sessions produce with the present_files tool and publish with the publish_artifact tool — web pages, reports, images, PDFs, source code, data files, and more (for example, /insight reports). Search, filter or change scope, rename, share (account-only or a public link), download, and delete them here.
+description: The artifact gallery collects files that AI SRE sessions produce with the present_files tool and then publish either with the publish_artifact tool (HTML and Markdown only) or through the console's Publish to artifact gallery action (images, PDFs, source code, data files, and more) — for example, /insight reports. Search, filter or change scope, rename, pin, share (account-only or a public link), download, and delete them here.
 keywords: ["AI SRE", "Artifacts", "present_files", "publish_artifact", "insight report", "artifact gallery", "public link", "share"]
 sidebarTitle: Artifacts
 ---
@@ -13,7 +13,10 @@ sidebarTitle: Artifacts
 
 ---
 
-An artifact is a file AI SRE produces in a session with the `present_files` tool and then publishes to the artifact gallery with the `publish_artifact` tool. The most typical case is a self-contained HTML report or page — for example, the operational insight report generated by typing `/insight` in a session — but publishable types go well beyond that:
+An artifact is a file AI SRE produces in a session with the `present_files` tool and then publishes to the artifact gallery. There are two publish paths, and they accept different types:
+
+- **The agent's `publish_artifact` tool**: publishes HTML / Markdown documents only (`.html` `.htm` `.md` `.markdown`) — a self-contained report or page, most typically the operational insight report generated by typing `/insight` in a session. Every other type is rejected with `unsupported_format`.
+- **The "Publish to artifact gallery" button next to a `present_files` file in the console** (see [Creating an artifact](#creating-an-artifact) below): publishes the wider set of types:
 
 | Category | Common extensions |
 |---|---|
@@ -24,7 +27,7 @@ An artifact is a file AI SRE produces in a session with the `present_files` tool
 | Source code | `.py` `.go` `.js` `.mjs` `.ts` `.jsx` `.tsx` `.java` `.c` `.h` `.cpp` `.cs` `.rb` `.rs` `.php` `.sh` `.sql` `.kt` `.swift` `.scala` `.css` `.vue` `.svelte` `.proto` `.tf` `.hcl`, and more |
 | Archives | `.zip` `.tar` `.gz` `.tgz` |
 
-Files outside the publishable range don't show a "Publish to artifact gallery" button in the session.
+Files outside the table above don't show a "Publish to artifact gallery" button in the session.
 
 A published artifact initially inherits its source session's scope: artifacts from a personal session belong to their creator ("Personal"); artifacts from a session bound to a team belong to that team and can be shared with other account members. Users with edit permission can change the scope later.
 
@@ -56,22 +59,41 @@ The top-right of the list page offers a **Card view / List view** toggle; your c
 | From conversation | Title of the source conversation; click to jump to it. Shows plain text "Conversation deleted" when the source conversation was deleted or has no title |
 | Created at | Artifact creation time |
 | Updated at | Artifact last-updated time |
+| Pin | An icon-only button (the column has no header); click it to pin or unpin the artifact for yourself — see [Pinning](#pinning) below |
 | Actions | Rename, download, delete, etc. |
 
 The **Created at** and **Updated at** columns support header sorting (ascending / descending toggle); sorting is executed server-side, with **Updated at descending** as the default.
 
-Scope, search term, sorting, and page number are all reflected in the page URL (for example `?scope=team&teams=1,2&q=rebuild&page=2`), so copying the address shares or bookmarks a **filtered** list; returning from an artifact's detail page also lands back on the same filters and position instead of resetting to the default view.
+Whichever sort you pick, **the artifacts you pinned always come first** (most recently pinned first), and the chosen sort orders the rest.
+
+Scope, search term, sorting, page number, and page size are all reflected in the page URL (for example `?scope=team&teams=1,2&q=rebuild&page=2&size=48`), so copying the address shares or bookmarks a **filtered** list; returning from an artifact's detail page also lands back on the same filters and position instead of resetting to the default view.
+
+Page size can be **12 / 24 / 48**, defaulting to **24** (the URL's `?size=`; a value equal to the default is not written to the address). If the address is hand-edited to some other number, the nearest option is used rather than the literal value.
 
 ### Artifact cards
 
 Each card shows:
 
-- A kind icon in the preview area: determined by file extension and content type — images, PDF, HTML, Markdown, tables (CSV / TSV), JSON, archives, and source code each get a dedicated icon, falling back to a generic file icon when the type can't be recognized;
+- A preview area rendering a **thumbnail of the artifact's own content**: HTML takes the head of the file (up to 256 KiB) and scales a desktop page laid out at 1200×630 into the box, Markdown is typeset onto that same scaled page, images show the image itself, and plain text shows its first 24 lines (up to 1400 characters). PDF and every other non-renderable kind show an empty frame. The thumbnail is a non-interactive still image — it renders inside a `sandbox=''` frame, so scripts don't run and links and buttons don't respond. It is also lazy: nothing is signed or downloaded until the card comes near the viewport (about 400px), and an empty skeleton frame shows until then;
+- The kind icon: determined by file extension and content type — images, PDF, HTML, Markdown, tables (CSV / TSV), JSON, archives, and source code each get a dedicated icon, falling back to a generic file icon when the type can't be recognized. It is a 30×30 badge straddling the divider between thumbnail and body, rather than filling the preview area;
 - The title (single line, truncated beyond that; hover to see the full title);
-- A single **Edited …** relative timestamp (the artifact's last update time; for an artifact never updated after creation, the update time is its creation time) — just now / N minutes ago / N hours ago / N days ago. Relative time is used at any age: an older artifact still shows "Nd ago" instead of falling back to a concrete date. Hover the timestamp for the exact time down to the minute, and note that the **Created at** / **Updated at** columns of the list view give exact times directly;
-- A scope badge in the bottom right: team artifacts show the team name (highlighted green); personal artifacts show the creator's name (gray).
+- A single **Edited …** relative timestamp in the grey caption line under the title (the artifact's last update time; for an artifact never updated after creation, the update time is its creation time) — just now / N minutes ago / N hours ago / N days ago. Relative time is used at any age: an older artifact still shows "Nd ago" instead of falling back to a concrete date. Hover the timestamp for the exact time down to the minute, and note that the **Created at** / **Updated at** columns of the list view give exact times directly;
+- The same caption line also carries the scope (a small icon plus a name: team artifacts show the team name, personal artifacts show the creator's name) — cards no longer use coloured scope badges; badges appear only in the list view and on the detail page. When the artifact has a live public link, the caption line leads with a small globe glyph that has a tooltip; a pinned artifact shows a pin glyph at the end of the caption line.
+
+Clicking the card body opens the artifact's detail page. Hovering over a card reveals a "More actions" button in the top-right corner (always visible on touch devices), with an equally hover-only pin button beside it — one click pins or unpins. The public-link preview inside the share panel uses this same thumbnail.
+
+### Pinning
 
-Clicking the card body opens the artifact's detail page. Hovering over a card reveals a "More actions" button in the top-right corner (always visible on touch devices).
+Every list row and every card has a pin button — on a card it sits in the top-right corner next to "More actions" and appears on hover (always visible on touch devices); in the list it is a fixed-width column of its own, between "Updated at" and the action buttons. The first item in the "More actions" menu is the same toggle, labelled "Pin" or "Unpin" according to the current state.
+
+Pinning is **a personal preference, not an edit**:
+
+- You can pin any artifact you can see — other people's personal artifacts and team artifacts included — with **no edit permission required** (rename, change scope, and delete do require it);
+- A pin only floats the artifact to the top of **your own** gallery. It does not change the artifact's content, title, or scope, and it does not affect the order anyone else sees;
+- Pinning and unpinning are both idempotent: re-pinning only refreshes the pin time (a later pin time sorts higher), and unpinning an artifact that was never pinned does not fail;
+- Pinning refetches the whole page. The server owns the ordering, so pinning an artifact on page 2 moves it to page 1 rather than reordering in place.
+
+The `pinned_at` field on a gallery list item is **the calling person's own** pin time (unix milliseconds); it is absent when the artifact is not pinned — so the same artifact can carry a different `pinned_at` for each member.
 
 ### Creating an artifact
 
@@ -93,6 +115,7 @@ The "More actions" menu on each card offers:
 
 | Action | Notes |
 |---|---|
+| Pin / Unpin | The menu's first item, labelled "Pin" (when not pinned) or "Unpin". Pinning is a **personal preference** and skips the edit-permission check entirely — you can pin any artifact you can see, and it only changes the order of your own list without modifying the artifact (see [Pinning](#pinning) above) |
 | Copy link | Copies the full URL of the artifact's detail page, which you can share with other account members |
 | Download | Only appears when the artifact is linked to a file (`file_id` is non-empty); downloads the original file |
 | Rename | Only appears when you have edit permission on the artifact; opens a dialog to change the title |
@@ -120,6 +143,10 @@ Below the title there is a **source-session strip**:
 
 The body renders the artifact according to its actual content type (for example, an HTML report renders inline as a page).
 
+<Note>
+On a phone the detail page degrades to a **read-only reader**: the title is no longer editable inline, the share, change-scope, and delete entries are all hidden, and the toolbar drops the back-to-list button, the file-kind icon, the scope badge, the public-link badge, the "Edited …" time, and the "Recently updated from session" entry, keeping only the title and the artifact body. When the artifact is linked to a file, **Download** remains available under "More actions". The list page and card view are unaffected.
+</Note>
+
 ## Share an artifact
 
 ---
@@ -159,6 +186,28 @@ Visitors who open a public link see a read-only content page: next to the title,
 Artifacts larger than **16 MiB** can't generate a public link — you'll see a notice that the artifact exceeds the size limit. You can still share it using "Account only" mode.
 </Note>
 
+## Update a published artifact
+
+---
+
+Republishing the same file does **not** silently overwrite a published artifact. When the agent updates one with `publish_artifact`, it must pass both the artifact's `artifact_id` and the `if_revision` returned by the previous publication (an opaque revision fingerprint shaped like `rev_…`):
+
+| Case | Result envelope | Outcome |
+|---|---|---|
+| `artifact_id` and `if_revision` both match | `status: published`, with an `operation` (`created` / `updated` / `unchanged`) and a new `revision` | The artifact is updated in place (an `unchanged` operation means the content did not change); the link and artifact ID stay the same |
+| Only a file path was given (no `artifact_id`) and the content differs from the published version | `status: needs_review`, `reason: explicit_artifact_id_required` | Nothing is published |
+| `artifact_id` was given but `if_revision` was not | `status: needs_review`, `reason: revision_required` | Nothing is published |
+| `if_revision` does not match the current revision (the artifact changed after you got the revision) | `status: needs_review`, `reason: revision_conflict` | Nothing is published |
+
+On `needs_review`, the agent also writes a copy of the **currently published content** into the session workspace along with the current `revision`; it reads that copy, merges deliberately, and retries with the same `artifact_id` and the new `revision` instead of overwriting blindly.
+
+A few more details:
+
+- When the content is byte-identical to the published version, the result is `operation: unchanged` and the artifact is left alone.
+- Re-presenting the same file with `present_files` does **not** update a published artifact — it only offers preview and download; publishing an update goes through `publish_artifact`.
+- If the artifact was deleted, a path-based republish fails with `artifact_deleted` instead of reviving it; only the "Publish to artifact gallery" button next to the `present_files` file in a session restores a deleted artifact.
+- Failures come back with a code: `unsupported_format` / `permission_denied` / `artifact_deleted` / `storage_unavailable` / `file_too_large` / `invalid_path`, of which `storage_unavailable` is retryable. When the commit cannot be confirmed the tool returns `status: unknown` with an `op_…` operation ID, and the agent does not create a second artifact.
+
 ## Permissions
 
 ---
@@ -171,7 +220,7 @@ Whether an artifact is editable (rename, change scope, delete) is determined by
 | Account Owner / admin | Has management access to any artifact in the account, personal or team scope |
 | Team member (team artifacts only) | When an artifact belongs to a team (`team_id > 0`), other members of that team can also manage it |
 
-Artifacts you cannot edit only expose read-only actions such as "Copy link" and "Download" — the "Rename" and "Delete" buttons do not appear.
+Artifacts you cannot edit only expose read-only actions such as "Pin", "Copy link", and "Download" — the "Rename" and "Delete" buttons do not appear. **Pinning is not part of that check**: it is a personal preference rather than an edit, so you can pin any artifact you can see (other members' personal artifacts included), and it only changes your own list order, affecting nobody else.
 
 <Note>
 This differs from the automation rule permission model: the account Owner / admins have management access to **any** artifact, including other members' personal artifacts — there is no "no exemption for personal resources" restriction here.