docs(factories): document Linear integration - #527
Merged
hongyi-chen merged 7 commits intoAug 17, 2026
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
hongyi-chen
force-pushed
the
hyc/factories-integration-linear
branch
from
August 14, 2026 17:43
005faad to
f74b9c6
Compare
Co-Authored-By: Warp Agent <agent@warp.dev>
hongyi-chen
force-pushed
the
hyc/factories-integration-linear
branch
from
August 15, 2026 23:55
f74b9c6 to
ffb08e5
Compare
Collaborator
Author
|
/oz-review |
Contributor
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
![oz-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Linear factory integration page with documentation for authorization, trigger configuration, event routing, writeback behavior, and troubleshooting.
Concerns
- No blocking concerns found in the changed documentation.
- Spec alignment:
spec_context.mdreports no approved or repository spec context for this PR. - Security: No security findings in this docs-only diff.
Audit
- Comments: No doc comments, code comments, or tests were added or changed in the diff.
- Tests: No test files were changed; validation evidence is provided in the PR description.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Contributor
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Linear factory integration page with documentation for authorization, trigger configuration, event routing, writeback behavior, and troubleshooting.
Concerns
- No blocking concerns found in the changed documentation.
- Spec alignment:
spec_context.mdreports no approved or repository spec context for this PR. - Security: No security findings in this docs-only diff.
Audit
- Comments: No doc comments, code comments, or tests were added or changed in the diff.
- Tests: No test files were changed; validation evidence is provided in the PR description.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Collaborator
Author
|
/oz-review |
Contributor
|
I'm re-reviewing this pull request in response to a review request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
Contributor
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Linear factory integration page with full documentation for prerequisites, setup, event routing, outputs, continuity, writeback boundaries, and troubleshooting.
Concerns
- No blocking concerns found in the attached diff.
- No implementation-vs-spec drift was reviewed because the attached spec context says no approved or repository spec context was found.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
hongyi-chen
marked this pull request as ready for review
August 16, 2026 00:36
Contributor
|
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 Powered by Oz |
Contributor
There was a problem hiding this comment.
Overview
This PR replaces the placeholder Factories Linear page with factory-specific documentation for authorization, trigger routing, agent-session continuity, writeback behavior, and troubleshooting. I reviewed the attached annotated diff, docs repository guidance, and the supplemental security checklist; no blocking issues were found.
Concerns
- No important concerns found in the changed lines.
- No approved or repository spec context was provided for implementation drift review.
Verdict
Found: 0 critical, 0 important, 0 suggestions
Approve
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
Restructure the page in plainer language without changing any
verified claims:
- Open with the two-part mental model (connection grants access,
automations route work) instead of abstract phrasing
- Split the dense agent-session paragraph into a dedicated
'Route agent sessions' subsection
- Move the OAuth-scope-vs-routing caveat and the duplicate-run
hazard into :::caution callouts
- Rename jargon headings ('Writeback and operational boundaries'
-> 'What the factory can do in Linear') and simplify table cells
- Trim redundant sentences throughout
Co-Authored-By: Warp <agent@warp.dev>
Polish pass for external readers:
- Replace the Linear activity-type enumeration ('thoughts, actions,
plan changes, final responses, and errors') with plain descriptions
of what shows up in the session
- Fold the session fallback into 'Route agent sessions' and drop the
'configured fallback behavior' routing mechanics
- Rephrase 'requester attribution' and 'artifact links' in
user-facing terms
Co-Authored-By: Warp <agent@warp.dev>
moirahuang
reviewed
Aug 17, 2026
| --- | ||
|
|
||
| Linear integration documentation for Warp Factories will land in a follow-up PR. | ||
| Connect Linear to your factory so the issues your team already tracks can start factory work, and progress flows back to those issues. Two parts work together: |
There was a problem hiding this comment.
let's update the text to match the description here https://docs.google.com/document/d/1Uc7bMNgq-ljg0Fd2sinx-J1kodNalNvl9ZW_QfHlusw/edit?tab=t.j4k4oeqbgre0#heading=h.dief3quxwuny
aka
Connect Warp to Linear to send issues directly into your software factory. Assign an issue to your factory or tag it in a comment, and the factory will pick up the issue with its full context.
From there, your factory will spec, implement, review, and verify any work assigned to it. As work progresses, the factory keeps the Linear issue updated so your team can follow along without switching tools.
When human input is needed, your team can respond in Linear or open the live factory run to inspect and steer the agent directly.
Collaborator
Author
There was a problem hiding this comment.
Done in 704e615 — the intro now uses the description copy from the doc verbatim, and the frontmatter description was updated to match.
|
|
||
| ## Connect and configure Linear | ||
|
|
||
| 1. In your factory setup, open **Connect your issue trackers**. On the **Linear** row, click **Connect**. |
There was a problem hiding this comment.
i'd propose we separate setting up for the first time vs. configuring. aka we should make it clear what is through the onboarding flow vs. what is through the factory management / integrations page. mind directing the agent to make this split and i can re-review after?
Collaborator
Author
There was a problem hiding this comment.
Done in 704e615 — split into "Connect Linear during factory setup" (the Connect your issue trackers step in the setup flow) and "Connect Linear from factory settings" (Settings > Factory integrations), with trigger configuration in its own section. Both connect paths note that they seed the default agent-session routing automation. Ready for re-review.
- Replace the intro with the launch-approved Linear description copy - Split setup into first-time factory setup vs. factory settings, per review - Move trigger configuration into its own section and note the Not connected state in the Add trigger menu - Editorial polish: sharper frontmatter description, prerequisite wording, expected outcomes after connect steps, clearer link text Co-Authored-By: Warp <agent@warp.dev>
- Promote Route agent sessions to its own section directly after the connect paths, matching the assign-or-tag flow the intro describes - Orient trigger steps from the Automations page (New > Add trigger) - Tighten section leads and the settings parity outcome sentence Co-Authored-By: Warp <agent@warp.dev>
hongyi-chen
added a commit
that referenced
this pull request
Aug 17, 2026
… and cross-page seams (#557) * docs(factories): convert relative links to root-absolute on launch pages Relative links resolve against the page's trailing-slash URL at runtime (./x becomes /factories/<page>/x), so they 404 even though the file-based CI link checker passes. #550 swept the pages merged before it; the pages that landed after (#516 overview/how-it-works, #520 connect, #527 Linear) reintroduced the pattern. Converts all of them to the repo's root-absolute trailing-slash convention. Co-Authored-By: Warp <agent@warp.dev> * docs(factories): fix cross-page seams left by the stacked launch PRs - Map the setup wizard's Code toggle to the Implement role (quickstart vs factory-agents used different names for the same role) - Map lifecycle stage names to the Activity view's UI names (Planning, Building), which how-factories-work never connected - Define a Factory MCP task as the factory's work item; the page used 'task' throughout without bridging to the term the rest of the section uses - Link connect-your-factory to the automation-filters page (#551 added the page after #520 merged, so the hub never referenced it) - Align 'cancelled' spelling on the Jira page with the rest of the section - Replace two 'cloud agent identity' usages with 'cloud agent' per the terminology glossary (platform/agents.mdx) Co-Authored-By: Warp <agent@warp.dev> --------- Co-authored-by: Warp <agent@warp.dev>
hongyi-chen
added a commit
that referenced
this pull request
Aug 18, 2026
* chore: gate factory launch
Placeholder commit to open a draft PR that will gate the factory launch.
Co-Authored-By: Warp Agent <agent@warp.dev>
* Factory launch (8/18): Automation Platform rename infra + Factories tab scaffold (#513)
* feat: scaffold Factories tab and Automation Platform rename infra
- Add new top-level Factories sidebar topic with 6 stub pages
(Overview, Quickstart, How Factories work, Configure your Factory,
Connect your Factory, Infrastructure & security) per HYC's IA doc
- Relabel the Oz tab to Automation Platform and reorganize its 10
subsections into 6 groups (Cloud Agents, Environments, Integrations,
Orchestration, Self-hosting, API/SDK); all page slugs unchanged
- Add vars.ts entries: API_SDK_NAME (rename-sensitive) and
FACTORY_WEB_APP/FACTORY_WEB_APP_URL (net-new, for platform.warp.dev)
- Extend style_lint.py RENAME_SENSITIVE_VAR_STRINGS to catch bare "Oz"
and "Oz Platform", with longest-match dedup so specific matches
(Oz CLI, Oz Platform, etc.) aren't double-flagged by the general
bare "Oz" entry
- Add Automation Platform + Warp Factories terminology.md entries
- Migrate platform/index.mdx prose to the vars system
- Add redirect for /platform/software-factory -> /factories/ (content
migration to the new tab flagged for HYC, not deleted)
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs: migrate hardcoded Oz product names to vars in agents/terminal/getting-started
Replace hardcoded rename-sensitive Oz-branded strings (Oz, Oz CLI, Oz web
app, Oz API, Oz API & SDK, Oz Platform, Oz run) with {VARS.*} references
in body prose (and {{TOKEN}} in frontmatter) across:
- src/content/docs/agents/**
- src/content/docs/terminal/comparisons and terminal/input/classic-input
- src/content/docs/getting-started/migrate-to-warp-from-claude-code
- src/content/docs/index.mdx and quickstart.mdx
Left unmigrated (intentional, per scope): image alt/figcaption text that
transcribes actual on-screen branding of existing screenshots/graphics,
and Oz mentions inside fenced code blocks (example prompts).
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs: migrate reference/ Oz-branded strings to vars, add CLI deprecation banner
Migrate hardcoded Oz product-name strings (Oz CLI, Oz web app, oz.warp.dev, Oz dashboard, Oz run, Oz API & SDK, Oz Platform, bare Oz) to the vars system across src/content/docs/reference/cli/** and src/content/docs/reference/api-and-sdk/**, using {VARS.KEY} in MDX body prose and {{TOKEN}} in frontmatter. Add a shared deprecation callout to the top of every reference/cli/* page pointing to the Warp Agent CLI as the replacement for the Oz CLI. Relabel the Reference tab's CLI sidebar entry to 'Oz CLI (legacy)' in src/sidebar.ts.
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs: migrate hardcoded Oz strings to vars system in guides, support-and-community, enterprise, changelog
Replace hardcoded rename-sensitive Oz-branded strings (Oz CLI, Oz web app,
oz.warp.dev, Oz dashboard, Oz run, Oz API & SDK, Oz Platform, bare Oz) with
src/data/vars.ts references ({VARS.KEY} in body prose, {{TOKEN}} in
frontmatter) across all guides/, support-and-community/, enterprise/, and
changelog/ files containing product-name mentions.
Left unmigrated (intentional, per style_lint OZ_TERMS_TO_AVOID / screenshot
alt-text exceptions):
- changelog/2026.mdx:501 'Oz agents' (wording issue, not vars issue)
- changelog/2026.mdx:629 'Oz cloud agent' (wording issue)
- changelog/2026.mdx:787 'the Oz agent' (wording issue)
- changelog/2026.mdx:1362 image alt text describing the 2026.02.10 launch screenshot
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs: migrate Oz platform strings to vars in platform/ directory
Replace hardcoded rename-sensitive strings (Oz, Oz Platform, Oz CLI,
Oz web app, Oz dashboard, Oz run, Oz API & SDK) with {VARS.*} in body
prose and {{TOKEN}} in frontmatter across src/content/docs/platform/,
excluding index.mdx and software-factory.mdx which are handled
separately.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: resolve topic-resolution build failures and lint false positives
- Add back platform/oz-web-app to the Automation Platform sidebar
(accidentally dropped during the reorg, broke the build)
- Give the Automation Platform topic an explicit id and associate the
orphaned platform/software-factory page with it via topic frontmatter,
since it's no longer listed in any sidebar but still needs a topic to
resolve (content stays as source material for HYC's Factories migration)
- Fix style_lint.py's check_hardcoded_vars to match on word boundaries
instead of plain substring search, so short literals like bare "Oz"
don't false-positive inside unrelated tokens (e.g. a YouTube share
link's si=OzvuInMl8DoNR97R query param)
- Fix style_lint.py's video-title check to recognize JSX expression
titles, not just quoted string literals
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: convert broken VARS markdown links to JSX anchors
MDX doesn't evaluate {} expressions inside plain markdown link
destination syntax [text](url) -- only inside JSX. 12 links across 8
reference/ pages used [label]({VARS.WEB_APP_URL}/path) syntax, which
the internal link checker correctly flagged as broken (the literal
string "{VARS.WEB_APP_URL}/path" isn't a real path).
Converted all 12 to the <a href={...}>label</a> JSX pattern already
used elsewhere in the codebase, using a template literal when a path
suffix is appended to the base URL.
Verified with:
- python3 .agents/skills/check_for_broken_links/check_links.py --internal-only (0 broken links, was 12)
- npm run build (370 pages, clean)
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: merge software-factory redirect entries to stay under Vercel's route limit
Vercel deployment was failing with errorCode "too_many_routes":
"Maximum number of routes (rewrites, redirects, etc) exceeded. Max is
2048, received 2049." The repo's vercel.json is already right at that
ceiling (~2047 processed routes on the base branch), and my two
separate redirect entries for /platform/software-factory (trailing
and non-trailing slash) each counted as a route, pushing the total
over by one.
Merged the two entries into a single rule using an optional trailing
slash pattern ("/platform/software-factory/?"), matching both URL
forms with one redirect instead of two.
Verified with npm run build (370 pages, clean).
Note for follow-up: the docs repo is now sitting almost exactly at
Vercel's 2048-route hard limit. Any future redirect addition (by
anyone) risks tripping this same failure. Worth a separate pass to
audit and consolidate redundant slash-variant redirect pairs across
vercel.json to create headroom.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: use valid Vercel redirect syntax for software-factory redirect
The previous fix used /platform/software-factory/? as the source
pattern to match both trailing-slash variants in one entry, but
Vercel rejected it with errorCode invalid-route-source-pattern (? is
not valid syntax in this position for Vercel redirect sources).
Reverted to a single plain entry using only the trailing-slash
canonical form (matching the simple, proven syntax used by the
adjacent /agent-platform/ entry), still keeping the net route count
at +1 instead of +2 to stay under the 2048 route cap.
Verified with npm run build (370 pages, clean) and a JSON validity
check on vercel.json.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: address PR review feedback
Automated (oz-for-oss) review comments:
- Revert incorrect variableization of the "Oz by Warp GitHub App"
proper noun in reference/cli/integration-setup.mdx,
reference/cli/api-keys.mdx, and enterprise/team-management/
admin-panel.mdx. This is a literal, external GitHub App display
name, not a docs-rename-sensitive string -- flipping
WARP_AUTOMATION_PLATFORM would otherwise make these pages document
a GitHub App name that doesn't actually exist.
- Fix sidebar.ts's hardcoded "Oz API & SDK reference" cross-link
label to use {VARS.API_SDK_NAME} via a template literal, so it
participates in the rename. Also imported VARS in sidebar.ts and
applied the same fix to the "Oz CLI (legacy)" label I introduced
earlier in this PR.
- (The flagged broken-markdown-link issue in reference/cli/api-keys.mdx
was already fixed in a prior commit on this branch.)
Human review feedback (rachaelrenk):
- Fixed several places where "{VARS.WARP_AUTOMATION_PLATFORM} platform"
would read as a duplicated word once the var's value changes to
something like "Automation Platform" (e.g. "Automation Platform
platform"). Removed the redundant literal "platform" suffix in 5
MDX body occurrences and 2 frontmatter occurrences, since the var's
value already conveys "platform" on its own.
- Wrapped the 6 Factories stub pages in an explicit sidebar group
(matching how every other topic in sidebar.ts organizes its items)
instead of leaving them as bare top-level entries, which is what
was likely causing them to render as headings instead of pages
under one collapsible "Factories" section.
Verified with npm run build (370 pages, clean), the internal link
checker (0 broken links), and style_lint.py --all (confirmed the
"Oz by Warp" reversions and "platform platform" fixes landed as
expected, no regressions).
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: remove {VARS.X} expressions from heading text (breaks TOC/anchors)
Starlight's "On this page" TOC and heading-anchor-id generation extract
heading text from the raw MDX AST before JSX expressions are evaluated,
so a heading like `### {VARS.WARP_AGENT_CLI}` doesn't render "Oz CLI"
in the TOC/anchor -- it renders the literal, unevaluated expression
source ("VARS.WARP_AGENT_CLI"), producing anchor ids like
"#varswarp_agent_cli" and a "On this page" entry reading
"VARS.WARP_AGENT_CLI" verbatim. The heading text in the page body
renders correctly (full MDX/JSX evaluation), so this only surfaces in
the TOC sidebar and in the URL fragment for that heading.
Found and fixed 40 occurrences across 21 files. In each case, reworded
the heading to avoid embedding a {VARS.X} expression, while keeping
{VARS.X} usable in the body prose beneath it (unaffected by this bug):
- Headings that were only "{VARS.X}" (e.g. "### {VARS.WEB_APP}") became
static, descriptive text ("### Web app", "### CLI", "### API", etc.)
- Headings mixing static text + a var were reworded to drop the var
while preserving meaning (e.g. "## How runners fit into the
{VARS.WARP_AUTOMATION_PLATFORM}" -> "## How runners fit into cloud
agent runs")
- The one historical changelog heading ("Introducing Oz: orchestration
for cloud agents") was set to literal "Oz" text instead of the var,
since it's a dated historical announcement and shouldn't silently
reword itself when the var flips
Also fixed a related, unrelated heading collision on
agents/capabilities/computer-use/index.mdx: its own "## Overview"
heading collided with Starlight's synthetic top-of-page "Overview" TOC
entry (auto-generated for intro content before the first heading),
producing two adjacent "Overview" rows in the TOC. Renamed to
"## Capabilities" to match its actual content.
Per review feedback, also normalized the Computer Use API section to
consistently use {VARS.API_SDK_NAME} (matching the page's own later,
correct usage) instead of "{VARS.WARP_AUTOMATION_PLATFORM} API", since
both phrases link to the same /reference/api-and-sdk/ page and the
future name for that page is "Warp API & SDK", not "Automation
Platform API".
Verified with:
- npm run build (370 pages, clean)
- Inspected the built HTML for agents/capabilities/computer-use/index.html:
TOC and anchor ids now read "Capabilities", "CLI", "API", "Web app"
instead of "VARS.WARP_AGENT_CLI" / duplicate "Overview" / broken ids
- python3 .agents/skills/check_for_broken_links/check_links.py --internal-only (0 broken links)
- style_lint.py --all (no new hardcoded-var regressions)
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: use plain Warp instead of the automation-platform var on Agent Memory page
Per review feedback: "Agent Memory gives agents in Automation Platform
persistent memory..." reads awkwardly once the WARP_AUTOMATION_PLATFORM
var flips. Since "Warp" is already a locked, stable product name (not
rename-sensitive), it's the safer and more natural choice here.
Applied the same reasoning consistently across the rest of the page,
not just the flagged frontmatter line, since the same "lives on
Automation Platform" / "runs on Automation Platform" pattern recurs in
several other sentences and would have reintroduced the same
awkwardness once the var value changes:
- Frontmatter description
- "lives on Warp" / "part of Warp" / "run on Warp"
- "Warp extracts/saves/searches/creates..." (subject of a sentence)
Left one occurrence alone ("self-hosted {VARS.WARP_AUTOMATION_PLATFORM}")
since that specifically references the self-hostable orchestration
platform as a technical concept, not a generic "in Warp" phrasing.
Also normalized the "Programmatic API access" bullet to use
{VARS.API_SDK_NAME} instead of "{VARS.WARP_AUTOMATION_PLATFORM} API",
consistent with the same fix applied elsewhere in this PR (both link
to /reference/api-and-sdk/, and the correct future name is "Warp API
& SDK", not "Automation Platform API").
Verified with npm run build (370 pages, clean).
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: correct WARP_AUTOMATION_PLATFORM -> API_SDK_NAME mismatches (post-flip audit, round 1)
Following up on the "Automation Platform API" bug caught in review: audited
every {VARS.WARP_AUTOMATION_PLATFORM} usage across the docs for the same
class of issue and found it recurring in 14 more files (~25 occurrences).
Root cause: whenever prose names the actual API/SDK product surface (usually
as "the [X] API" linking to /reference/api-and-sdk/, or an "[X] API and SDK"
phrase), it must use {VARS.API_SDK_NAME} (future value "Warp API & SDK"),
not {VARS.WARP_AUTOMATION_PLATFORM} + a literal " API"/" SDK" suffix (which
would render the invented, non-canonical name "Warp Automation Platform
API" once the platform var flips). This is a wrong-var bug, not just a
grammar/redundancy issue -- the two vars name different things.
Fixed across: platform/overview.mdx, platform/quickstart.mdx,
reference/api-and-sdk/{index,quickstart,demo-sentry-monitoring-with-sdk}.mdx,
reference/api-and-sdk/troubleshooting/{index,errors/index}.mdx,
reference/cli/{index,artifacts}.mdx, reference/index.mdx,
platform/team-access-billing-and-identity.mdx,
support-and-community/plans-and-billing/{credits,platform-credits}.mdx,
guides/agent-workflows/how-to-run-multiple-ai-coding-agents.mdx.
Where a sentence names the API/SDK as a generic noun without further
qualification (not the proper name of the product), simplified to plain
"API"/"the API" instead of introducing an unnecessary var, e.g. "calls the
API (directly or via an SDK)" and "The Python SDK ... calls the API from
Python services".
Also applied the same generic-scaffolding-to-plain-"Warp" simplification
established on the Agent Memory page fix earlier in this PR, for sentences
like "another agent CLI outside of {var}" and "uploads to {var} --
screenshots...", since "Warp" is the stable, locked product name and reads
correctly regardless of how WARP_AUTOMATION_PLATFORM resolves.
One grammar fix: "An {VARS.WARP_AUTOMATION_PLATFORM} cloud environment"
(reference/api-and-sdk/quickstart.mdx) used "An" for agreement with "Oz"
today, but "Warp Automation Platform" needs "A" -- reworded to "A cloud
environment" to avoid the var/article dependency entirely.
Broader audit scope covered in this pass (per user direction, judging
DASHBOARD/PLATFORM_RUN under the same-shape assumption where their future
value is still TBD): swept the whole docs tree for the API_SDK_NAME
mismatch class, redundant trailing-word duplication (e.g. "platform
platform"), and "an {VAR}" article-agreement breaks across all six
rename-sensitive vars (WARP_AUTOMATION_PLATFORM, WARP_AGENT_CLI, WEB_APP,
DASHBOARD, PLATFORM_RUN, API_SDK_NAME). No further redundant-word or
article-agreement issues were found beyond what's fixed here.
Not yet exhaustively reviewed: the full ~300-occurrence long tail of plain
{VARS.WARP_AUTOMATION_PLATFORM} usages for subtler phrasing/tone issues
(the kind fixed on the Agent Memory page) -- flagging as a follow-up since
that requires reading full sentence context per occurrence rather than
pattern-matching, and is lower risk than the two bug classes fixed here.
Verified with:
- npm run build (370 pages, clean)
- check_for_broken_links.py --internal-only (0 broken links, 3495 checked)
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: round 2 of post-rename vars audit across the site
Continues the systematic sweep of {VARS.X} usages for issues that would
only surface after the Oz -> Warp Automation Platform rename ships.
Fixes applied:
- "platform...platform" duplicate wording (7 more instances across
agents/index.mdx, enterprise/index.mdx, enterprise/getting-started/*,
and root index.mdx), matching the earlier computer-use/index.mdx fix.
- Leftover un-migrated literal "Oz agents" / "@Oz" mentions in
reference/cli/integration-setup.mdx (missed in the original migration).
- Leftover un-migrated VideoEmbed title in platform/oz-web-app.mdx.
- Reworded platform/team-access-billing-and-identity.mdx:160, which
incorrectly described personal-token auth as "authenticating as
{platform}" instead of authenticating as the triggering user.
Policy decision (confirmed with user): changelog/2026.mdx entries are
dated historical records of what shipped under the Oz brand at the time.
Reverted all ~58 rename-sensitive var usages in that file
(WARP_AUTOMATION_PLATFORM, WARP_AGENT_CLI, PLATFORM_RUN, DASHBOARD,
WEB_APP, WEB_APP_URL) back to their current literal Oz-branded text, so
historical entries don't get silently rewritten when the rename ships.
This is consistent with the earlier "Introducing Oz" launch-heading fix
in the same file. Removed the now-unused VARS import from that file.
Verified: clean build (370 pages), 0 broken internal links, and no new
hardcoded-var lint regressions (all 71 remaining findings are pre-existing
exceptions in files untouched by this round).
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: swap Factories tab icon from server to setting (gear)
Starlight's built-in icon set has no literal factory glyph, so a true
factory-with-smokestack icon would need an icon-library plugin (e.g.
Phosphor or Material Symbols via starlight-plugin-icons) plus a Sidebar
component override -- out of scope for now. Using 'setting' (gear) as a
placeholder since it's the closest built-in match to automated machinery,
and it's visually distinct from the icons on the Terminal (laptop) and
Automation Platform (cloud-download) tabs.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: remove redundant top-level API tab, fix stale Oz icon check
The horizontal "API" tab duplicated a link already present in the
Reference tab's sidebar (API & SDK > API Reference > /api). Both pointed
to the same standalone Scalar-rendered page.
The original reason for splitting /api into its own top-level topic was
that Scalar is a different rendering framework than the rest of the
Astro/Starlight site, so /api can't have a normal per-topic sidebar tree
(hence it was a link-only topic with no `items`). That constraint only
explains why /api itself can't be a full Starlight topic -- it doesn't
require /api to also have its own top-level nav pill. The destination
remains fully reachable:
- From the Reference tab's existing "API Reference" sidebar link
- From WarpTopbar.astro's own breadcrumb/nav on the /api page itself,
which already links back to "API & SDK" and "Quickstart"
Removing the topic entry needed no other changes: WarpTopicNav.astro just
renders whatever topics exist, and the search breadcrumb label map in
CustomSidebar.astro is keyed off URL segments, not the topic list.
Also fixed a related stale reference in WarpTopicNav.astro: the custom
cloud-icon override still checked `topic.label === 'Oz'`, left over from
before the Automation Platform rename. Updated to `'Automation Platform'`
so the custom SVG actually renders again instead of silently falling
back to Starlight's generic cloud-download icon. Removed the now-dead
`</>`-bracket icon branch for the deleted API topic.
Verified: clean build (370 pages, /api page itself untouched) and 0
broken internal links.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: rename Reference tab to "API & Reference", surface API Reference link
Per HYC/Rachael's Slack discussion following the top-level API tab
removal: HYC flagged that dropping the tab could make the standalone
Scalar-rendered /api page harder to discover. Two changes address that
without re-adding the redundant top-level tab:
1. Renamed the "Reference" tab to "API & Reference" so the tab label
itself signals that API docs live there.
2. Promoted the "API Reference" link from 3 levels deep (Reference >
API & SDK > 3rd item) to a new "Technical Reference" group at the very
top of the tab's sidebar, as the first item -- immediately visible
without expanding anything. The group's second item is a renamed
self-link ("Overview") to the former bare "Technical reference" page
link, following the same self-link-as-first-child pattern already used
by other groups in this file (e.g. Self-hosting > Overview).
Also updated two lower-priority, non-interactive spots that mirrored the
old "Reference" label for consistency: the llms.txt generator's
customSets list (astro.config.mjs) and the search-result breadcrumb label
map (CustomSidebar.astro).
Verified: clean build (370 pages) and 0 broken internal links.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: put Overview before API Reference under Technical Reference
Order flip only, per feedback on the previous commit.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: restructure Cloud Agents group per HYC feedback
Addresses HYC's follow-up feedback on the Automation Platform tab:
1. Renamed the bare "Agents" sidebar item to "Cloud agent accounts",
matching the page's own H1 exactly. The generic "Agents" label was
confusing sitting inside a "Cloud Agents" group, and easily conflated
with the different "agents" meaning used under Harnesses (Warp Agent,
Claude Code, Codex).
2. Converted it into a small group and nested Skills as agents, MCP
servers, and Secrets beneath it, replacing the removed "API / SDK"
group entirely (which is now empty since its 4th item, a duplicate
cross-link to /reference/api-and-sdk/, was already identified as
actively breaking topic-detection for that page and removed).
Skills and Secrets are literal properties of a cloud agent identity
(POST /agent/identities accepts `skills` and `secrets` directly); MCP
is per-run rather than identity-scoped, so added a bridging
"## Capabilities" section to agents.mdx explicitly covering both
identity-level and run-level capabilities.
3. Reordered the Cloud Agents group per HYC's note that individual cloud
agents should be introduced before the tooling for monitoring them:
Quickstart -> Oz platform -> Cloud agent accounts (+ capabilities) ->
Viewing cloud agent runs -> Managing cloud agents -> Oz web app ->
Handoff -> Harnesses -> Access/billing/identity -> FAQs.
("Managing cloud agents" was previously positioned above the page
that actually defines what a cloud agent is.)
Verified: clean build (370 pages) and 0 broken internal links.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: rename subgroup to Warp Cloud Agents, relabel Overview to Cloud agent accounts
The subgroup label 'Cloud agent accounts' was too narrow for its actual
contents -- Skills as agents, MCP servers, and Secrets are cloud-agent
capabilities generally (per HYC/Rachael Slack discussion), not
account/identity-specific. Renamed the subgroup to 'Warp Cloud Agents'
(broader, factually accurate: all 4 pages are genuinely about cloud
agents) and moved the more specific 'Cloud agent accounts' label down to
just the Overview item (platform/agents.mdx), where it's fully accurate.
Accepted a slight nesting redundancy with the parent 'Cloud Agents'
group per explicit direction.
Verified: clean build (370 pages) and 0 broken internal links.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: lead Warp Cloud Agents with the Warp Agent page, move it above Oz platform
HYC review feedback on the restructured Cloud Agents group.
- Move the Warp Agent harness page into the Warp Cloud Agents subgroup as
its Overview, and drop it from the Harnesses subgroup.
- Move the Warp Cloud Agents subgroup above the Oz platform entry.
- Point the Warp Agent page at its new siblings, splitting Related pages
into the agents in this section and the harness comparison.
The page keeps its /platform/harnesses/warp-agent slug, so all six
inbound links stay valid and no redirects are needed. The Harnesses
overview still links to it, so it remains reachable from that group.
Cloud agent accounts stays its own page: it carries the
/agent/identities endpoint table, plan limits, service accounts, and
pull request authorship rules, none of which the harness page covers.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix: land the Automation Platform tab on the platform overview
The tab pointed at /platform/, so clicking "Automation Platform" opened a
page titled "Cloud agents overview". The platform overview it should have
opened already exists at /platform/overview.
Retarget the tab to /platform/overview/ and move /platform/ into the
Cloud Agents group as that group's Overview.
Did not swap the two page bodies, which was the other option considered.
The URLs are already aligned with their content, and each carries 16
legacy redirects that match:
/platform/overview <- /agent-platform/warp-platform,
/cloud-agents-platform, /agent-platform/platform
/platform/ <- /agent-platform/ambient-agents,
/cloud-agents-overview
Swapping the bodies would have sent all 32 legacy URLs to the opposite of
what they ask for, inverted 17 internal links across 10 files that read
"the Automation Platform" and point at /platform/overview/, and broken an
#execution-hosts anchor link from platform/environments.mdx.
Precedent for a non-root tab target: the Changelog tab links to
/changelog/2026/.
Also on the platform overview:
- Add a Warp Factories section, framed as composing the primitives the
page describes. The page previously mentioned Factories zero times,
which is a gap now that Factor which is a gap now that Factor which is th which is a gap now that Factor which is a gap now that Factor whicexp which is a gap now that Factor which is a gap now that Factor duplicated "Using cloud agents with or without the Warp
app" section with a "Where to g app" section with a "Where to g app" section with a "Where to g appch app" section with a "Where to g app" section with aunt stays at 2037.
Co-Authored-By: Warp Agent <agent@warp.dev>
* refactor(sidebar): split agent runtime from agent configuration
Per HYC's review on 8/14, which chose Option 1 from the three proposed.
This supersedes 763abea0, which made the Warp Agent harness page the
Overview of a "Warp Cloud Agents" group. That group mixed one
Warp-Agent-specific page with four cross-harness ones, so a Codex user
looking for Secrets had to find it under a Warp-branded heading.
Cloud Agents now reads:
Overview / Quickstart
Harnesses Overview, Warp Agent (Default), Claude Code,
Codex, Authentication
Agent configuration Cloud agent accounts, Skills as agents,
MCP servers, Secrets
Operations Session sharing, Managing cloud agents, Oz web app
Handoff
Access, billing, and identity / Cloud agent FAQs
HYC asked to confirm everything in Agent configuration is cross-harness,
and flagged Cloud agent accounts as a likely exception. Audited all four:
- platform/agents zero references to any harness, Warp Agent,
Claude, or Codex
- skills-as-agents - skills-as-agents - skills-as-agents - skills-as-agent uses OPENAI_API_KEY as its example; both
third third thirdharness constraint
So nothing needed calling out. Recorded in a sidebar comment so the
group does not silently reacquire Warp-specific pages.
Operations groups the three surfaces HYC lisOperations groups the three surfaces HYC lisOperations groups theg Operations groups the three surfaces HYC lup. The name mirrors the "Management and observability"
section of the platform overview, which covers thessection of the platform overview, which covers thessection of the platrom "Viewing cloud agent
runs" to "Session sharing". The page is titled "Cloud agent session
sharing", so the old label sent readers somewhere they did not expect.
- Revert the Related pages split on warp-agent.mdx from 763abea0. The
"agents in this section" framing only held while that page was a
section overview.
- Delete the old collapsed Harnesses group, which would otherwise have
listed the same four pages twice.
No slugs change: no redirects, no broken links, route count still 2037.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix(platform): correct group label, heading levels, and two content issues
From a top-to-bottom review of the Automation Platform tab.
Sidebar
- Rename the 'Self-hosting' group to 'Deployment and hosting'. The group
holds a comparison page, a Warp-HOSTED page, and the self-hosting set,
so the old label filed 'Warp-hosted agents' under its own opposite.
- Qualify two labels inside that group. With the group renamed, a bare
'Overview' and 'Quickstart' read as the group's rather than
self-hosting's. Both now match their page titles.
deployment-patterns.mdx
- Promote every heading one level. The page had no H2 at all: it opened
with an H4, used H3 for its three patterns, and H4 beneath. Starlight
builds the on-page table of contents from H2s, so the page had none.
integrations/bitbucket.mdx
- 'Step 4: Test your environment' was an H2 while Steps 1-3 were H3s
under the two H2 deployment variants, so Step 4 rendered as a sibling
of the variants rather than continuing either sequence. It is a of the variants rather than continuing either sequence. It is a ofso.
integrations/index.mdx
- Drop the second of two consecutive :::note ca- Drop the second of two coegration setup, which the Get started list alr- Drop the second of two consecutive :::note ca- Drop the second of he {WARP_AGENT_CLI}'. Integrations
run on the platform; the CLI is one trigger among six, which the
Triggers page states plainly. The replacem Triggers page states plainly. The replacem Triggers page slugs change: no redirects, no broken links, route count still 2037.
Co-Authored-By: Warp Agent <agent@warp.dev>
* refactor(sidebar): split Triggers and Integrations into sibling groups
Triggers was nested inside Integrations, which inverted the concept.
platform/triggers lists integrations as one of six trigger types,
alongside schedules, the CLI, the API, GitHub, and GitHub Actions. So
the content said Triggers contains Integrations while the nav said the
reverse. The sidebar comment showed the nesting was inherited from an
earlier prototype rather than chosen.
They are now siblings:
Triggers Triggers overview, Scheduled agents quickstart,
Scheduled agents
Integrations Integrations overview, Integrations quickstart, Slack,
Linear, Jira, GitHub, GitHub Actions, Azure DevOps,
Bitbucket, GitLab, cloud providers
Siblings rather than nesting Integrations under Triggers, which would
have pushed 11 pages four levels deep for a relationship the overview
pages can state in prose.
Also add the return cross-link. Triggers already pointed at Integrations
three times; Integrations did not point back. Its intro now names
Triggers as the full set of ways to start a run.
Grouping is independent of slugs, so no files move, no redirects, and no
links change. 52 pages links change. 52 pages links change. 52 pages links change. 52 pt@warp.dev>
* refactor(sidebar): merge Triggers & integrations, collapse level-2 groups
Supersedes 248e6035, which split Triggers and Integrations into sibling
groups. Siblings implied the two are peers, which they are not:
platform/triggers lists integrations as one of six trigger types. But
nesting either inside the other is also wrong -- Triggers under
Integrations inverts the concept, and Integrations under Triggers buries
11 pages four levels deep. A single group named for both sidesteps the
question, and the overview pages carry the actual relationship in prose.
The return cross-link added in 248e6035 stays. Triggers overview is still
a distinct page, and the Integrations intro still needs to name it as the
full set of ways to start a run.
Separately, collapse the three level-2 groups added in 42b84229:
Harnesses, Agent configuration, and Operations. Every other level-2 group
on the site already sets collapsed: true -- Blocks, Capabilities,
Interacting with agents, Handoff, GitHub Actions -- so these three were
the only ones expanding on load, which made the tab open long and
inconsistent with the rest of the docs.
Also normalize the indentation of the ClouAlso normalize the indentation of the ClouAlso han its siblings. No rendering change.
52 pages in the tab, none listed twice. No slugs change.
Co-Authored-By: Warp Agent <agent@warp.dev>
* refactor(sidebar): nest Scheduled agents and Integrations subgroups
Shortens the Triggers & integrations group from 14 visible rows to 3.
Overview platform/triggers
Scheduled agents collapsed: Overview, Quickstart
Integrations collapsed: Overview, Quickstart, Slack, Linear,
Jira, GitHub, GitHub Actions, Azure DevOps,
Bitbucket, GitLab, cloud providers
Both new subgroups follow the Overview-then-Quickstart shape the GitHub
Actions subgroup already uses. Nesting GitHub Actions one level deeper
matches existing precedent: the Agents tab nests Computer Use inside
Capabilities inside Warp Agents.
platform/triggers becomes the group overview, so its intro now names
integrations explicitly instead of only 'schedules, webhooks, or other
automation patterns'.
Kept both overview pages rather than merging them into one. Merging
would mean deleting a page, and the two are not comparable:
platform/integrations has 20 inbound links and 19 legacy redirect
sources, against 4 and 0 for platform/triggers. Deleting the more
established of the two to save a single sidebar row is a bad trade, and
with Integrations now a subgroup it needs its own overview regardless.
52 pages in the tab, none listed twice. No slugs change.
Co-Authored-By: Warp Agent <agent@warp.dev>
* fix(platform): hardcode @Oz mention handle instead of variabilizing it
18 places across 9 files wrote the Slack and Linear mention handle as
@{VARS.WARP_AUTOMATION_PLATFORM}. That renders as "@Oz" today, so it
looks correct, but the variable flips to the new product name at rename.
Every one of these would have silently become "Tag @Automation Platform
in a message" -- an invalid handle -- with nothing failing in CI to catch
it.
A mention handle is a literal string a user types. It is not the product
name appearing in prose, and it does not necessarily change when the
product name changes. The GitHub handle was already correctly hardcoded
as @oz-agent in 31 places; this brings Slack and Linear in line.
Rendering is unchanged: WARP_AUTOMATION_PLATFORM is currently "Oz", so
these already displayed as "@Oz".
Also teaches the style linter the same distinction. The hardcoded-var
rule matched "Oz" inside "@Oz" via its word boundary, so hardcoding
raised the repo total from 1148 to 1167. The rule now skips an
"@"-prefixed occurrence. The exemption is per-occurrence, not per-line:
a line containing both "@Oz" and "Oz web app" still flags the latter.
Repo total is back to 1148.
The correct post-rename handle is still an open product question. It is
flagged inline on the changed lines for review.
Co-Authored-By: Warp Agent <agent@warp.dev>
* Add a hairline separator above the page footer CTA
HYC's review asked for a visual break between page content and the
"See something wrong? Edit this page or open an issue" CTA, which
previously ran on directly after the last line of prose and read like a
trailing sentence of the article.
Adds a border-top to the page footer in FeedbackFooter.astro, using the
same treatment already applied to the "On this page" panel footer in
CustomPageSidebar.astro (1px, --sl-color-hairline-light). The rule sits
inside .sl-container, so it spans the content column rather than
full-bleed like Starlight's ContentPanel divider.
Also drops a dead `margin-top: 2rem` from the same rule. The footer is a
sibling of .sl-markdown-content inside Starlight's ContentPanel, whose
`.sl-container > * + *` rule (0,1,1) outranks a bare `footer` selector
(0,0,1), so the gap above the footer has always been 1.5rem. Space below
the rule is now set with padding-top, which nothing else targets, so the
1.5rem above and below is symmetric and under our control.
The /api reference is unaffected: it renders DocsFeedbackLinks in its own
fixed-position card, not through this footer.
Verified: build clean at 370 pages; the separator renders on standard and
splash (404) pages; /api emits no page footer.
Co-Authored-By: Warp <agent@warp.dev>
* refactor(sidebar): shorten the Support tab and relabel two platform groups
Addresses HYC's final round of structural feedback on the tab bar and the
Automation Platform tab.
- 'Support & Community' -> 'Support'. The horizontal tab bar was wrapping
to a second line early; this was the longest label after 'Automation
Platform'. Total tab-label length drops from 102 to 89 characters across
the 9 tabs, a 13% trim, and 'Automation Platform' (19) and
'API & Reference' (15) are now the longest remaining.
- Community group moved to the bottom of the Support tab. Readers enter
this tab for help far more often than for community links, so
troubleshooting, plans and billing, and privacy now come first.
- 'Deployment and hosting' -> 'Deployment & hosting'.
- 'Operations' -> 'Management & Observability', matching the section name
already used on the platform overview.
Labels only. No slugs, redirects, or page content change.
Verified in built output: the Support tab renders with group order
Troubleshooting -> Plans -> Privacy -> Community; 'Operations' and
'Deployment and hosting' no longer appear anywhere; build clean at 370
pages.
Co-Authored-By: Warp <agent@warp.dev>
* refactor(sidebar): label follow-ups on the Support and platform tabs
Two consistency fixes on top of the previous commit.
- Support tab's bare first item: 'Support and Community' -> 'Overview'.
The tab is now 'Support', so repeating the old two-part name in the
first item was stale. 'Overview' also matches the bare first item on the
Automation Platform, API & Reference, and Enterprise tabs. The page's own
'Support & Community' H1 and title are intentionally left alone, so the
page keeps its search and SEO surface.
- 'Management & Observability' -> 'Management & observability', matching
the sentence case used by its sibling labels ('Triggers & integrations',
'Infrastructure & security') and by the platform overview section of the
same name.
Verified in built output: no 'Support and Community' left in the sidebar,
the page title still renders, and no capital-O variant survives.
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): add launch documentation foundation (#537)
Co-authored-by: Warp Agent <agent@warp.dev>
* docs: add Warp Factories to docs landing pages (#538)
* docs: add Warp Factories cross-links
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs: clarify Factories cross-link copy for external readers
Rewrite the four Warp Factories blurbs in plain, benefit-led language:
- Replace the repeated 'coordinates specialized cloud agents across
software development workflows' phrasing with concrete descriptions
grounded in the terminology glossary (triage, spec, implement,
review, verify; humans approve key decisions).
- Drop internal implementation jargon ('Oz primitives',
'cloud-run primitives') from user-facing copy.
- Fix the dangling modifier on the Guides landing page.
- Simplify the Enterprise product-list intro and make the Factories
bullet parallel with the other product bullets.
- Match the root landing page's section pattern (divider, bold name,
arrow link) and move 'Early Access' into prose.
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): document factory agents (#518)
* docs(factories): document factory agent roles
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs(factories): rewrite factory agents page in plain language
Remove undefined jargon that confused readers: 'intake' becomes plain
descriptions of work entering the factory, 'seeded' becomes 'default',
and phrases like 'advisory verdict', 'prompt appendix', 'parent-child
lineage', and 'correlated mistakes' are rewritten to say what they mean.
Same verified facts, human approval gates, and security caveats; clearer
sentences, second-person voice, and simpler section names.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): address feedback on factory agents page
Drop 'specialists' wording in favor of plain 'agents', link computer use
from the implement and verification sections, surface custom agents and
automations in the default roles section, and call out that agent
configuration can be stored as version-controlled code.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): address harness plan gating and config-editing review feedback
- Note that third-party harnesses require a Build plan or higher, with a
link to warp.dev/pricing (verified against warp-server billing tiers:
free.yaml sets third_party_enabled false; all paid bases set it true)
- Rework 'Configure agent behavior' to state clearly that a Warp-managed
factory repo supports both the visual agent editor and the code-based
editing flow, while a team-owned GitHub repo is file-only with read-only
control room settings
- Reword the custom-agents opener to drop the 'aren't a ceiling' phrasing
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* Restyle the Factories "Early Access" topic badge and fix nav wrap (#543)
* Restyle the Factories "Early Access" topic badge
The topic nav rendered Starlight's default <Badge>, a monospace
bordered box that clashed with the nav's Inter type and was wide
enough to wrap "Guides" onto a second header row at common laptop
widths (~1300-1460px).
- Render the badge as a compact brand pill (Inter 11px/600, accent
tint, fully rounded) in both the top nav and the mobile drawer
topic list.
- Retune the nav's responsive fallbacks: drop per-item icons below
94rem (the ten-topic row no longer fits with icons below ~1460px)
and hide the badge below 80rem so the row survives down to
~1160px before wrapping.
Co-Authored-By: Warp <agent@warp.dev>
* Temporarily add PR screenshot assets (removed in next commit)
* Remove temporary PR screenshot assets
The images stay referenceable in the PR description via the previous
commit's raw.githubusercontent.com URLs; the tree stays clean.
---------
Co-authored-by: Warp <agent@warp.dev>
* Anchor the active topic tab underline to the header divider (#545)
* Anchor the active topic tab underline to the header divider
The 2px accent underline for the active topic tab hugged the tab
label mid-header, floating ~14px above the header's bottom hairline.
Anchor it to the divider instead (the Cursor/Devin docs pattern):
- Stretch the nav -> ul -> li -> a chain to the header's full content
height, with tab content centered by the link's own flex alignment.
- Offset the underline by --sl-nav-pad-y so it rests flush on the
1px border-bottom drawn by Starlight's header.
- In the crowded <=80rem band, where the tab list may wrap to two
rows inside the taller header, fall back to the previous
tab-hugging underline so a wrapped row-one tab doesn't leave the
line stranded between rows.
- Inset the focus-visible ring since the links now span the full
header content height.
Verified in headless Chromium from 900-1600px: single row >=1160px,
line flush on the divider >=1300px (1281+ once icons drop), correct
fallbacks below.
Co-Authored-By: Warp <agent@warp.dev>
* Temporarily add PR screenshot assets (removed in next commit)
* Remove temporary PR screenshot assets
The images stay referenceable in the PR description via the previous
commit's raw.githubusercontent.com URLs; the tree stays clean.
---------
Co-authored-by: Warp <agent@warp.dev>
* docs(factories): document Slack integration (#525)
* docs(factories): document Jira integration (#528)
* docs(factories): document Jira integration
Co-Authored-By: Warp Agent <agent@warp.dev>
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): clarify Jira integration page
Editorial pass for external readers:
- Lead with the user flow in plain language instead of internal routing
vocabulary
- Restructure setup into three clean steps with the automation example
nested under its step, and explain the example inline
- Consolidate trigger/filter behavior into one section, removing repeated
explanations of when the event fires and keyword case-insensitivity
- Replace internal jargon (seeds, intake, factory admission, issue
mutations) with plain wording
- Surface the filters-vs-access caveat as a caution callout and group
permissions/reliability notes into a scannable list
- Align title and headers with the sibling Linear page; use root-relative
link for the platform setup page
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): center Jira page on Warp, not Rovo
Reduce Rovo mentions from six to one. The remaining mention is a
recognition pointer in prerequisites (Jira lists the Warp agent among
Atlassian's Rovo agents); everywhere else the actors are Warp and the
factory agent, and sessions are just agent sessions.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): address Jira page review feedback
- Inline the app install and workspace connection steps instead of
bouncing readers to the platform setup page mid-procedure; keep that
page as a supplementary deep link and plainly note that its
warp-agent label flow is for standalone cloud agents, not factories.
- Note the agent runs in the cloud and link cloud agent session
sharing for watching the full run from the factory.
- Drop the repeated-deliveries bullet (internal dedup detail with no
user action).
- Reword the code-access bullet: connecting Jira grants no repository
access, and agent PRs go through the usual review process.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): address Jira page review feedback (round 2)
- Document the automation editor's Jira trigger (Add trigger > Jira >
Agent session created), now that the control room editor supports it
alongside GitHub, GitLab, Linear, and Slack triggers. Keep definitions
as code as the alternative path.
- Correct the access caution: Jira access is workspace-wide today (no
per-team or per-project scoping exists yet), so drop the inaccurate
suggestion that the Warp app's Jira authorization can be scoped by
project.
- Remove the now-false claim that a new session on the same work item
always starts a separate run.
- Rewrite the Permissions bullet: the Jira user who starts a session
must connect their Jira account to Warp before a run starts (new
user-binding gate); the run still executes as the automation's agent,
not as that Jira user.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): fix four accuracy issues from adversarial review
- Add the missing per-factory Jira connection step (Settings > Jira >
Connect/Install, select projects, Enable). Without it, the automation
editor's Add trigger > Jira entry stays a disabled not-connected item
(confirmed via AutomationEditor.tsx/TriggerMenu.tsx/
JiraIntegrationConnect.tsx and the editor's own test suite).
- Correct the access caution: project_keys does control whether a given
automation fires (provider_jira.go's evalFilter), it just isn't an
access boundary across teams in the same workspace. Left the last
sentence about no team/project scoping untouched.
- Rewrite the Permissions bullet: a bound Jira actor becomes the run's
creator/ActorUserID (automation_dispatch_jira.go), while the
automation's agent remains the ExecutionPrincipal either way.
- Make the definitions-as-code alternative self-contained (factory.yaml
integration declaration + automation file path) instead of depending
on the still-stubbed factory-as-code page.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): remove em dashes from Jira setup steps per style guide
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
Co-authored-by: warp-agent-staging[bot] <240773466+warp-agent-staging[bot]@users.noreply.github.com>
* docs(factories): document the control room (#531)
* docs(factories): document the control room
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs(factories): clarify control room copy
Editorial pass on the control room page for external readers:
- Replace internal jargon (web surface, source mode, terminal state,
polling interval, atomic commit) with plain language
- State Activity's default filters directly instead of "two defaults
shape what you see"
- Restructure dense comma lists into scannable bullets (dashboard
metrics, run pane actions, Code tab source modes, editor boundaries)
- Explain what the scorer Self-improvement toggle does, per the UI copy
- Fix inverted phrasing ("the automation editor overrides no execution
settings") and cut duplicated sidebar orientation
No factual changes; all labels and behavior stay as verified.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): trim UI narration from control room page
Cut prose that describes what UI elements do rather than documenting
behavior: search/filter/sort control walkthroughs, filter chip and URL
state mechanics, pane field inventories, refresh cadence, and editor
form-field enumerations. Kept the semantics readers can't infer from
the UI: default Activity filters, metric definitions and cost caveats,
the Stop task warning, source-mode boundaries, and read-only rules.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): control room feedback — session steering, self-improvement, code tab
- Replace the 'no way to steer' note: View session opens the run's shared
agent session (cloud agent session sharing) for real-time follow-ups.
- Add the Self-improvement page to the pages table and scorer section;
drop the stale claim that the Dashboard lists self-improvement PRs.
- Link the Code tab section to Factory definitions as code, align its
source modes with the current UI (GitHub links out; live-managed), and
document the in-room branch review (Request changes / Approve & merge).
- Refresh details: harness is editable in the agent editor, Scorers are
read-only for file-managed factories, work-item pane shows origin and
View agent, Cost per PR expands into most expensive PRs.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): address control room review feedback
- List Integrations among the team-level sidebar pages
- Clarify Settings manages the integrations the factory can access
- Mention the Complete and Cancelled terminal stages on Activity
- Contrast runs with Activity work items
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): clarify Jira access-scoping gap is coming, not available (#548)
PR #528 (already merged) left the access caution flat: 'Warp doesn't yet
offer a way to scope Jira access by team or project.' The requester asked
to verify whether installing the Warp Jira app itself supports scoping
access to specific projects before deciding on wording.
Checked forge-jira/manifest.yml: the app requests classic, site-wide
scopes (read:jira-work, read:jira-user, write:jira-work), not
project-scoped grants, and neither platform/integrations/jira.mdx's
install flow nor the factory's own Settings > Jira connection
(JiraIntegrationConnect.tsx) offers a way to restrict the app's own Jira
access by project — project selection there only seeds automation
defaults. So install-level project scoping does not exist today,
confirming the requester's own suspicion.
Reworded the caution's last sentence to state the coming Warp
team-level Jira scoping feature instead of a flat 'not available',
leaving the already-correct project_keys-is-not-an-access-boundary
guidance untouched. Kept the ':::caution' aside type per this repo's
own convention (limitations/caveats, not destructive/irreversible
actions) rather than introducing an unsupported type.
Co-authored-by: warp-agent-staging[bot] <240773466+warp-agent-staging[bot]@users.noreply.github.com>
Co-authored-by: Warp <agent@warp.dev>
* docs(factories): document Factory MCP (#521)
* docs(factories): document Factory MCP
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs(factories): make the Factory MCP page reader-focused
- Lead with what you can do and add example prompts; make clear your
agent calls the tools for you
- Replace the tool-by-tool sequence diagram (Mermaid isn't rendered by
this site) and the agent operating rules (error-code handling,
reference resolution order, fan-out restrictions) with two plain
workflows: send new work, and pick up a task locally
- Keep the load-bearing caveats: full-permission auth, non-locking
pickup, push-before-handback, handback vs complete
- Simplify the tool table to purpose-only and add a Related pages
section
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): give Factory MCP setup instructions directly
Replace "get connection details from Warp or your factory
administrator" with the actual quickstart: the endpoint URL
(https://app.warp.dev/api/v1/mcp/factory, verified against warp-server
route registration and the client's builtin server config), a Claude
Code one-liner, the standard mcpServers JSON snippet, and the bearer
header form for API-key automation. Browser OAuth on first connect is
backed by the server's RFC 8414/9728 discovery metadata for this
endpoint.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): cross-link factory pages and enrich MCP-in-Warp link
- Point the MCP-in-Warp related-pages entry at the catalog of MCP
servers you can add to Warp directly
- Link foreman to the factory agents page and control room to its page
- Include Jira in the intake paths alongside Slack, Linear, and GitHub
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): document measurement and improvement (#522)
* docs(factories): document measurement and improvement
Co-Authored-By: Warp Agent <agent@warp.dev>
* Simplify measure-and-improve language
Rewrite the page in plainer language based on review feedback:
- Rename the jargon table headers (Boundary/Limitation -> Keep in mind)
- Drop the 25-lines-per-engineer-hour heuristic explanation; describe
Time saved simply as a directional estimate
- Merge the two dense metric-caveat paragraphs into one
- Shorten Scorer, benchmark, Self-improvement, and improvement-loop
sections without changing verified behavior claims
Co-Authored-By: Warp <agent@warp.dev>
* Drop Keep in mind columns; state facts in descriptions
Reviewer feedback: docs should read as objective statements, not
advice. Both tables are now two columns, with measurement facts folded
into the metric descriptions and coverage facts kept in the caution
block.
Co-Authored-By: Warp <agent@warp.dev>
* Remove remaining implementation details and duplication
- Metric rows describe only what each metric shows; GitHub App
coverage facts live in the caution block alone
- Cut UI inventory (median/mean/By complexity/By size views,
scoreboard, scatter plot) and billing-rate conversion detail
- Replace jargon: eligible, lower-bound, freeze, clusters, PR
signals, webhook data
- Dedupe Self-improvement paragraphs and the three-newest-PRs fact,
fix the ambiguous pronoun, drop the closing aphorism and generic
benchmark advice already covered by loop step 4
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): address measure-and-improve review feedback
- Trim the dashboard caution to the actionable GitHub App coverage
caveat; move the run-count composition into the interpretation
paragraph and drop the opaque merge-rate sentence
- Add a Mermaid diagram to the practical improvement loop showing the
monitoring cycle and where Self-improvement joins it
- Link definitions as code from the Self-improvement section,
explaining that follow-up runs improve the versioned factory
definition through reviewable pull requests
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): align Scorer docs with current UI per review
- Replace the all-agents/pause framing with the actual model: Scorers
apply to selected agents, and setting the sample rate to 0 stops
automatic scoring.
- Drop the Manual/Periodic mode table; describe automatic scoring at
sample rate > 0 plus on-demand scoring of a single conversation.
- Remove the Analysis model setting paragraph, which may be dropped
from the product.
- Polish: list the Agent(s) to evaluate field in UI order, introduce
'benchmark suite' before use, and update improvement-loop steps to
match the pause-less model.
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): use root-absolute links on merged factory pages (#550)
* docs(factories): fix relative links and non-rendering mermaid on merged pages
Convert all 31 relative internal links across factory-agents,
factory-mcp, measure-and-improve, and the Jira/Slack integration pages
to root-absolute paths with trailing slashes. Relative links resolve
against Starlight's trailing-slash page URLs (../platform/x becomes
/factories/platform/x) and 404 in the browser, while the file-path-based
CI link checker stays green — the same breakage bnavetta flagged on the
infrastructure page in #523.
Also remove the mermaid flowchart from measure-and-improve: the docs
site has no mermaid renderer, so the block displayed as a raw code
fence. The numbered improvement-loop list directly below it already
narrates every node and edge, so no information is lost.
Only pages whose owning PRs (#518, #521, #522, #525, #528) have already
merged are touched; open factory PRs own different files.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): restore improvement-loop mermaid diagram
Mermaid rendering shipped on main in c35aab4 (#515) after
hyc/factory-launch forked, so the diagram only failed to render because
the launch branch predates the renderer. Restore it; this PR now only
converts relative links to root-absolute paths.
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp <agent@warp.dev>
* docs(factories): document integrations and intake (#520)
* docs(factories): document integrations and intake
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs(factories): replace intake jargon with plain language on connect page
Rewrites Connect your factory so external readers don't need internal
vocabulary to follow it:
- Drop 'intake' everywhere (intake paths, intake boundaries, how intake
works); use plain framing like 'how work reaches your factory'.
- Dissolve the 'Intake boundaries' grab-bag table into a 'Good to know'
list scoped to user-facing behavior, and move provider authorization
mechanics to the per-provider integration guides.
- Remove internal implementation details: seeded tracker skill and
prompt appendix, retry-safety guidance for receiving workflows,
subscription-matching plumbing, and the unexplained 'managed factory'
qualifier.
- Simplify the flow diagram and setup steps; gloss 'foreman agent' and
'work item' on first mention per the terminology glossary.
Validated with npm run build (377 pages), the style_lint skill
(--changed, no findings for this page), and the broken-links checker
(0 broken links).
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): link provider mentions to their integration guides
Link Slack, GitHub, Linear, Jira, and Factory MCP from the source table,
the default-automation bullets, and the tracker-selection note so readers
can jump straight to the relevant guide from wherever a provider is
mentioned.
Validated with the style_lint skill (no findings for this page) and the
broken-links checker (0 broken links).
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): Jira work goes to Warp, surfaced through Rovo
The agent users assign or mention in Jira is Warp (the rovo:agentConnector
module named 'Warp' in forge-jira/manifest.yml), not a generic Rovo agent.
Rovo is Atlassian's framework that surfaces it; the conversation still
happens in a Rovo agent session (A2A agent_session_created ingress).
Reword the source table, Jira default-automation bullet, and integration
guides bullet accordingly, and align 'Rovo agent session' phrasing with
the Jira integration guide.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): de-emphasize Rovo on the connect overview
Lead with what matters to the reader: Jira work items are assigned to
Warp. Drop the remaining Rovo mentions from the source table, the Jira
integration-guides bullet, and the follow-ups note — the Jira guide
covers the Rovo session mechanics.
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): tighten connect page from review feedback
- Drop the vague 'What you get back' table column; the intro already
covers results posting back to the source
- Expand the foreman description: what it orchestrates (triage, spec,
implementation, review) and where it pauses for humans
- Replace the marketing-toned 'You stay in control of what ships'
bullet with a factual pull-request hand-off note
- Remove em dashes from procedural steps and reduce them elsewhere
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): document Linear integration (#527)
* docs(factories): document Linear integration
Co-Authored-By: Warp Agent <agent@warp.dev>
* docs(factories): rewrite Linear page for clarity
Restructure the page in plainer language without changing any
verified claims:
- Open with the two-part mental model (connection grants access,
automations route work) instead of abstract phrasing
- Split the dense agent-session paragraph into a dedicated
'Route agent sessions' subsection
- Move the OAuth-scope-vs-routing caveat and the duplicate-run
hazard into :::caution callouts
- Rename jargon headings ('Writeback and operational boundaries'
-> 'What the factory can do in Linear') and simplify table cells
- Trim redundant sentences throughout
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): remove internal vocabulary from Linear page
Polish pass for external readers:
- Replace the Linear activity-type enumeration ('thoughts, actions,
plan changes, final responses, and errors') with plain descriptions
of what shows up in the session
- Fold the session fallback into 'Route agent sessions' and drop the
'configured fallback behavior' routing mechanics
- Rephrase 'requester attribution' and 'artifact links' in
user-facing terms
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): address review feedback on Linear page
- Replace the intro with the launch-approved Linear description copy
- Split setup into first-time factory setup vs. factory settings, per review
- Move trigger configuration into its own section and note the Not
connected state in the Add trigger menu
- Editorial polish: sharper frontmatter description, prerequisite
wording, expected outcomes after connect steps, clearer link text
Co-Authored-By: Warp <agent@warp.dev>
* docs(factories): polish Linear page structure and flow
- Promote Route agent sessions to its own section directly after the
connect paths, matching the assign-or-tag flow the intro describes
- Orient trigger steps from the Automations page (New > Add trigger)
- Tighten section leads and the settings parity outcome sentence
Co-Authored-By: Warp <agent@warp.dev>
---------
Co-authored-by: Warp Agent <agent@warp.dev>
* docs(factories): document infrastructure and security (#523)
* docs(factories): document infrastructure …
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds factory-specific Linear documentation covering workspace authorization, issue/comment triggers, agent-session routing through definitions as code, session-only requester identity linking, same-issue continuity, rich writeback, loop prevention, and troubleshooting.
Final size: 889 prose words. Generic provider installation details remain in the existing platform integration page; this PR focuses only on factory-specific behavior.
Foundation
Shared navigation, route placeholders, Early Access badge support, and guide migrations are merged in #537. This PR now contains only its feature-owned files and passes CI independently.
Validation
npm run typecheck: 0 errorsnpm run build: 377 pages builtLatest source refresh
Adds Linear multi-team onboarding/routing while preserving session-only identity binding and definitions-as-code agent-session trigger configuration.
Verified against Warp
e72fd7aacand warp-server9be39e484b. Broken, placeholder, partial, and spec-only surfaces remain excluded.Proposed reviewers
Based on the Warp Factories Soft Launch (August 18th) tracker. For planning only; no review requests have been sent.
@moirahuang@liliwilson@jasonkeungScreenshots
Not included. The page uses a compact trigger/context/output table and links to the existing provider setup page; no approved factory-specific UI assets exist yet.
Unverified claims
None — UI labels, event classes, filters, authorization boundaries, continuity, and writeback behavior were verified against source.
Conversation: https://staging.warp.dev/conversation/5ff89820-2d80-4518-981e-178845029de1
Plans: https://staging.warp.dev/drive/notebook/7ZPKWz7hM5I59o4Gg2ptYi and https://staging.warp.dev/drive/notebook/DpRWhMQ0DLCajPPMggXw5e
Co-Authored-By: Warp Agent agent@warp.dev