docs(jira): document scoped API token support (authType, gateway routing, limitations)

[aaight]

Summary

Documents the JIRA scoped-token support shipped across MNG-1736..MNG-1744. Documentation-only — no code or behavior change. Captures the verified scoped-token contract from the MNG-1735 research so operators understand setup, required scopes, gateway routing, and the known ack-reaction limitation.

Issue: https://linear.app/issue/MNG-1745
(full URL: https://linear.app/mongrel/issue/MNG-1745/as-an-operator-i-want-documentation-for-jira-scoped-tokens-so-that-i)

What changed

• docs/getting-started.md — new "Scoped API tokens (authType)" subsection under the Jira setup section: the authType: "scoped" config option with a CLI example, HTTP Basic (email:api_token) for both modes, site-URL vs. Atlassian-gateway routing (https://api.atlassian.com/ex/jira/{cloudId}), cloudId discovery via /_edge/tenant_info, required scopes, and the three scoped-token limitations (ack reactions unavailable, webhook auto-registration 401/403 → manual path, accessible-resources not used).
• docs/architecture/08-config-credentials.md — new "JIRA authentication modes (scoped tokens)" subsection under Credential Resolution + threaded authType into the withJiraCredentials example. Covers the shared resolveJiraApiBaseUrl host table, CASCADE_JIRA_AUTH_TYPE env-var threading, required scopes, and the ack-reaction limitation.
• docs/architecture/06-integration-layer.md — two bullets on the JIRA provider: the authType config field and the shared resolveJiraApiBaseUrl host-resolution contract (with a cross-link to 08-config-credentials.md).
• src/integrations/README.md — new "JIRA authentication modes (scoped tokens)" section documenting the authType config field, the resolveJiraApiBaseUrl single-source-of-truth host resolver (its call sites), required scopes, and the ack-reaction limitation.
• CLAUDE.md (+ AGENTS.md, a symlink → identical) — short "JIRA scoped tokens" note near the environment/credentials section.

Documented facts (verified in-code)

• Scoped tokens use HTTP Basic (email:api_token), not Bearer — authType selects the host, not the auth scheme (src/jira/api-host.ts, src/jira/authType.ts).
• Scoped mode routes REST v3 through https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/...; cloudId resolved from ${baseUrl}/_edge/tenant_info (always the site URL) and cached per baseUrl.
• Direct site REST v3 calls can fail under a scoped token → the gateway is the supported path.
• accessible-resources is OAuth 2.0 / 3LO guidance and returns 401 for scoped API tokens → not used for cloudId.
• Ack reactions (/rest/reactions/1.0/) are unavailable on the gateway → degrade to a skipped no-op, never fail a run.
• Programmatic /rest/api/3/webhook management needs webhook scopes / app eligibility; 401/403 → manual webhook registration.

No live tenant, customer, or personal-email names are included — examples use acme / yourorg / example.

Testing

• npx vitest run --project unit-core tests/unit/architecture-docs.test.ts → 41/41 pass (doc-drift guards, active-link resolution, and the CLAUDE.md/AGENTS.md sync guard all green).
• Docs-only diff: zero .ts/.tsx/.js/.jsx files changed, so lint and typecheck are unaffected.

Acceptance criteria

• Getting-started / config-credentials docs the API-token-with-scopes option, gateway routing, required scopes, and the ack-reaction limitation
• Integration-layer / README notes the authType config field and the shared resolveJiraApiBaseUrl host-resolution contract
• CLAUDE.md and AGENTS.md updated in sync with a JIRA scoped-token note
• architecture-docs.test.ts doc-drift + CLAUDE/AGENTS sync guards stay green

🤖 Generated with Claude Code

🕵️ claude-code · claude-opus-4-8 · run details

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[nhopeatall]

Summary

APPROVE — documentation-only PR; every technical claim is verified accurate against the current code, all four acceptance criteria are met, and the doc-drift / CLAUDE↔AGENTS sync guards pass (41/41).

Verification performed

I cross-checked each documented fact against the source rather than trusting the PR description:

• resolveJiraApiBaseUrl(creds) (src/jira/api-host.ts) — confirmed: basic/absent → creds.baseUrl; scoped → https://api.atlassian.com/ex/jira/{cloudId} via jiraClient.getCloudId.
• getCloudId (src/jira/client.ts) — confirmed it always hits ${creds.baseUrl}/_edge/tenant_info (site URL, never the gateway) and caches per baseUrl.
• normalizeJiraAuthType (src/jira/authType.ts) — confirmed absent/unknown → 'basic'.
• jiraConfigSchema.authType (src/integrations/pm/jira/config-schema.ts) — confirmed z.enum(['basic','scoped']).optional(), non-secret.
• HTTP Basic for both modes — confirmed Basic ${base64(email:apiToken)} in getCloudId; no Bearer branch.
• Ack-reaction degradation — confirmed both jiraClient.addCommentReaction and JiraPlatformClient.postReaction short-circuit under authType === 'scoped' and stay on the site URL; /rest/reactions/1.0/ usage matches.
• Webhook 401/403 → manual path — confirmed jiraCreateWebhook (src/api/routers/webhooks/jira.ts) builds an actionable message pointing at System → WebHooks; required scopes (read:jira-work + manage:jira-webhook; granular read:field:jira + read:project:jira + write:webhook:jira) match the docs.
• CASCADE_JIRA_AUTH_TYPE — confirmed injected by augmentProjectSecrets (src/backends/secretBuilder.ts) as jiraConfig.authType ?? 'basic'.
• Discovery threading — confirmed configToCredentials (baseUrl→base_url, authType→auth_type) and createDiscoveryProvider in the JIRA manifest thread authType.
• Cross-link — 06-integration-layer.md anchor #jira-authentication-modes-scoped-tokens resolves to the ### JIRA authentication modes (scoped tokens) heading in 08-config-credentials.md.
• Webhook route — getting-started's /jira/webhook matches webhookRoute: '/jira/webhook' in the manifest.
• CLAUDE↔AGENTS sync — AGENTS.md is a symlink to CLAUDE.md, so they stay byte-identical.
• Privacy — no live tenant/customer/personal-email data; only acme / yourorg / example placeholders. No internal MNG- refs leak into the user-facing getting-started/architecture docs (they appear only in the dev-facing README/CLAUDE.md).
• Tests — npx vitest run --project unit-core tests/unit/architecture-docs.test.ts → 41/41 pass locally; CI 7/7 green.

No blocking or should-fix issues. The content is intentionally mirrored across the operator (getting-started), architecture (06/08), dev (README), and agent (CLAUDE.md) surfaces — that matches the work item's declared key-files list and the repo's existing convention, not a defect.

🕵️ claude-code · claude-opus-4-8 · run details