docs: document shareable media artifact links and artifact media pages

[hongyi-chen]

Summary

A missing_docs drift-watch run detected two new surfaces that ship the same user-facing capability and had no docs coverage:

• A new server-side agent tool, get_media_artifact_links, which returns shareable links to a run's Computer Use screenshots and video recordings so an agent can include them in a Slack message, an issue or PR comment, a Linear comment, or a chat reply.
• A new Oz web app route, artifacts/:artifactUid, the per-artifact media page those links open.

Both are enabled in production (media_artifact_links_tool and artifact_media_page_links in config/prod.yaml). The same rollout also changed what Link only attachments point at: PR links now open the artifact's media page rather than the run page, so the existing wording on the artifacts page was stale.

Changes

src/content/docs/agents/capabilities/computer-use/artifacts-in-prs.mdx

• Corrected the Link only attachment mode description: links open a media page showing the single capture.
• Added a "Sharing captures outside pull requests" section covering where shared links can go, the media page URL shape, permission checking on open, how each attachment mode (Link only / Embed / Disabled) behaves, and how to ask for it in a prompt.
• Added a media page bullet to "Where else artifacts appear".

src/content/docs/platform/oz-web-app.mdx

• Added an "Artifact media pages" subsection under Runs describing the /artifacts/<artifact-uid> page and its access behavior.

Source of truth

• logic/ai/multi_agent/runtime/get_media_artifact_links.go — link building, attachment-mode gating, embed URLs and video thumbnails.
• logic/ai/multi_agent/artifact_attachments/media_page_links.go — MediaPageArtifactURL (<oz origin>/artifacts/<uuid>).
• client/packages/agents/src/pages/Artifacts/index.tsx — public media viewer; public artifacts render without auth, private ones redirect to login.

Validation

• npm run build passes.
• check_links.py reports 0 broken links (including the new #artifact-media-pages anchor).

Deferred findings from this audit run

Summarized in full in the companion audit-bookkeeping PR:

• OpenAPI spec drift for three released endpoints (GET /agent/artifacts/{artifactUid}/download, GET /agent/run-by-external-reference, POST /agent/runs/{runId}/scores) — belongs to the sync-openapi-spec skill, and the regenerated subset would also pull in research-preview Agent Memory schemas, which needs a policy decision first.
• Factory MCP OAuth discovery routes and GET /factory/{uid}/metrics — mapped internal (unreleased product / x-internal in the canonical spec).
• 30 low-severity terminology flags, verified as false positives.

Co-Authored-By: Oz oz-agent@warp.dev
Co-Authored-By: Warp Agent agent@warp.dev

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 5, 2026 7:26pm

[oz-for-oss]

@hongyi-chen

I'm starting a first review of this pull request.

You can view the conversation on Warp.

I completed the review and no human review was requested for this pull request.

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

Overview

This PR documents shareable Computer Use media artifact links and the per-artifact media page in the Oz web app, and updates the existing pull request attachment wording to match the new link target.

Concerns

• One non-blocking docs style issue: avoid hardcoding the Oz web app host in body prose when the page already uses the shared variable system.

Verdict

Found: 0 critical, 0 important, 1 suggestions

Approve with nits

Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[oz-for-oss]

💡 [SUGGESTION] Avoid hardcoding oz.warp.dev; this page already imports VARS, so referencing the route keeps the copy resilient to web app URL changes.

Suggested change

	Each link opens a media page in the {VARS.WEB_APP} that shows one capture — for example, `https://oz.warp.dev/artifacts/ARTIFACT_UID`, where `ARTIFACT_UID` identifies the screenshot or recording. Access is checked when the link is opened, so a link is safe to paste into an external tool: viewers who can't access the run are asked to sign in and are turned away if they lack permission.
	Each link opens a media page in the {VARS.WEB_APP} that shows one capture. The URL uses the `/artifacts/<artifact-uid>` path, where `<artifact-uid>` identifies the screenshot or recording. Access is checked when the link is opened, so a link is safe to paste into an external tool: viewers who can't access the run are asked to sign in and are turned away if they lack permission.