docs: clarify user requirements for built-in Jira tools

[warp-agent-staging]

Summary

Add a short caution under Jira Permissions so readers know when built-in Jira tools work and when to use a managed Atlassian MCP install. Only src/content/docs/factories/integrations/jira.mdx changes.

Related issues

None; requested documentation clarification.

Validation

• Supported Node 24: npm ci, npm run typecheck (0 errors, 0 warnings), and npm run build passed.
• python3 .agents/skills/style_lint/style_lint.py --changed passed; five glossary warnings are in unchanged text.
• git diff --check passed. Trunk lint/format skipped because Trunk is not installed; no test suite for this copy-only edit.
• Chromium on Linux verified the actual compiled callout, full text, bold settings path, and exact MCP link, with no clipping. Local Vercel analytics scripts returned 404s; page rendering was unaffected.

Screenshots

Computer-use screenshots

View rendered Jira callout — current shortened caution under Permissions, after verifying the MCP link.

Private artifact links require authorized Warp access. The managed artifact tool omitted its screenshot block; the stored capture was recovered from run metadata.

Follow-ups

None; other pages and product behavior remain unchanged.

Content design plan

• Reader and job: A factory author choosing how a run accesses Jira.
• Gap today: Permissions omit built-in tool eligibility and the alternative for runs without a person.
• Change: One caution with the account-linking path and existing MCP docs link; no setup guide or internals.

Documentation risk

Risk: engineering-review-required
Rationale: Clarifies Jira availability, permission scope, and the account-linking path against the current server code and production configuration.
Source files consulted: warp-server/logic/ai/ambient_agents/managed_mcp/warp_jira_mcp/resolver.go@85056cb3d3fa795c48d73660812d73fce78987d9, warp-server/jira/jiraclient/client.go@85056cb3d3fa795c48d73660812d73fce78987d9, warp-server/jira/jiraclient/user_tokens.go@85056cb3d3fa795c48d73660812d73fce78987d9, warp-server/config/prod.yaml@85056cb3d3fa795c48d73660812d73fce78987d9, warp-server/client/packages/factory/src/components/jira-user-connection-prompt.tsx@85056cb3d3fa795c48d73660812d73fce78987d9, src/content/docs/platform/mcp.mdx@f9e0c8a04105f96ed12b929e8240e25e90aedb4d
Requested engineering reviewers: none; assignment deferred to factory handoff
Engineering review status: approved
Engineering review evidence: jasonkeung approved the current head (review)
Docs override: none

Unverified claims

No VERIFY markers. Source verification for the current Marketplace app:

• Run identity: resolveMCPActorAccountID uses the human creator's Jira account binding, or the Jira-triggering actor. Other runs return an empty actor ID.
• Read authorization: gated denies user-scoped reads without an actor, otherwise replaces the installation bearer with the actor's offline user token. Production config enables this for the Marketplace app; the older distribution app remains disabled. The installation still supplies the site and app credentials, so this user-level read check is additional to the connected-integration authorization described on the MCP page.
• Account-linking path: The product's connection prompt says: “In Jira, open your profile → Personal settings → Warp to connect your account.”
• Independent MCP access: Managed MCP authentication stores credentials ahead of time; cloud runs use them without browser login. Atlassian's official MCP documentation confirms its server provides Jira access with OAuth authentication.

[vercel]

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

Project	Deployment	Actions	Updated
docs	Ready	Preview	Oct 5, 2026 5:26pm UTC

[warp-agent-staging]

This PR was generated with Warp.

Comment @warp-staging-factory on this PR to send it follow-up work.

 

[warp-for-oss]

@warp-agent-staging[bot]

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 /warp-agent-review on this pull request to retrigger a review (up to 3 times on the same pull request).

Powered by Oz

[warp-for-oss]

Overview

This PR adds a caution to the Jira factory integration docs explaining when built-in Jira tools can use a user-linked Atlassian account and when managed Atlassian MCP is the right fallback. I found no approved spec context to validate against, and the docs-only change did not introduce security-sensitive behavior.

Concerns

• The new callout uses a full docs.warp.dev URL for an internal docs link; the docs style guide and surrounding page use root-relative links within this Starlight space.

Verdict

Found: 0 critical, 0 important, 1 suggestions

Approve with nits

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

Powered by Oz

[github-actions]

Review summary

The independent agent completed its review for this commit.

Findings

• src/content/docs/factories/integrations/jira.mdx:82 — [SUGGESTION] The caution says built-in tools "read Jira as the person who created the run", but the bullet above says the run "executes as the agent selected by the automation, not as that Jira user". Requested change: add a clause saying only Jira reads use the creator's linked account, and avoid implying the same for writes.
• src/content/docs/factories/integrations/jira.mdx:82 — [SUGGESTION] The caution repeats the account-linking requirement already covered in the first Permissions bullet and the linked platform page, and uses "built-in Jira tools" instead of the page's "Warp-managed integration tools". Requested change: fold the new facts into the existing bullet or drop the repeated linking sentence, and align the terminology.
• src/content/docs/factories/integrations/jira.mdx:82 — [SUGGESTION] The link /platform/mcp/ opens the top of the MCP page, but managed-install steps are under ## OAuth authentication. Requested change: link /platform/mcp/#oauth-authentication, and confirm with the engineering reviewer whether /platform/mcp/'s statement that Warp-managed integration tools work in runs the integration didn't trigger needs a matching update for Jira.

Verdict

Approve with nits