Skip to content

docs: clarify factory integration setup prerequisites - #1071

Draft
rachaelrenk wants to merge 1 commit into
rrenk/teams-workspaces-rolesfrom
rrenk/team-factory-permissions
Draft

rachaelrenk wants to merge 1 commit into
rrenk/teams-workspaces-rolesfrom
rrenk/team-factory-permissions

Conversation

@rachaelrenk

Copy link
Copy Markdown
Contributor

What this feature does

Factory setup separates shared integration authorization, attaching an existing connection, and linking a personal account. These updates put the responsible Warp and provider administrators beside setup steps, explain Slack's manager-first prerequisite, and make Azure DevOps permissions guidance discoverable. This documents existing setup paths, not a new feature release.

Summary

PR 2 of the teams, workspaces, and factory-access work, kept separate from #1067 as requested.

Stacked base: rrenk/teams-workspaces-roles (#1067), not main. Merge the base first and retarget this PR afterward. Only seven public documentation pages differ from that base; the usability-toolkit governance work is not implemented here.

Changes

  • Give blocked Editors a task-local handoff in Connect your factory before provider authorization.
  • Separate personal account linking, a missing shared connection, and attaching an existing connection.
  • State Slack's shared manager prerequisite in Prerequisites and before factory-app setup; retain subsequent user provisioning authorization and Slack app approval.
  • Name the Warp coordinator, Jira site approver, and factory Editor separately. Explain who requests another person's Jira approval.
  • Preserve Azure DevOps's separate Entra/Azure approvers and Basic-seat caveat; replace an unqualified setup handoff with an admin-coordinated path.
  • Add Azure to the integration-permissions index using the existing identities/approval guidance, explicitly not a complete OAuth scope inventory.
  • Clarify GitLab's self-serve versus Enterprise administration terminology and narrow the general role summary to coordination rather than a universal API denial.

Content design plan

Reader and job: A factory Editor or team administrator connecting an existing factory to a service, possibly needing another person to approve access.

Gap: The reference definitions explain roles, but connection steps omit the necessary actor or shared-setup dependency. A reader can reach the right page yet still hit an avoidable authorization dead end.

Change: Correct and extend the existing connection procedures and permission index with short prerequisites, links, and handoffs. Preserve provider inventories and avoid a new permission matrix, new public pages, or unconfirmed guarantees about every reconnect/delegation path.

Usability validation

Retested the newly generated local HTML, starting at the homepage and following Factory quickstart → Connect your factory → provider guides and the permission index. This was a rendered text/link walkthrough, not a logged-in product test.

Question Retest result
Q13: Personal linking, shared authorization, or existing attachment? Clear at the connection step, with a direct role reference and a separate personal Jira link.
Q14: Who coordinates a missing connection, and whom should a blocked Editor ask? Clear recommended handoff before provider approval.
Q15: Who can initiate delegated setup? Jira's requesting-admin handoff is clear. Azure's administrative coordination path is clearer, but definitive eligibility for every Manager setup-link path remains an owner-review question; no universal member-denial claim is added.
Q16: Where are provider permissions and the Slack prerequisite? The connection page links the index; Azure has bounded identity/approval links; Slack's shared-manager-before-factory-app dependency is explicit.

All selected new role, manager, personal-link, and Azure inventory anchors were present in the built HTML. Absolute cross-space links were resolved against the local proposed tree for this retest, not silently followed into older production content.

Validation

  • npm run typecheck: 0 errors, 7 hints.
  • Heading-variable tests: 5 passed.
  • Build: 426 generated HTML pages; 3,684 TOC entries validated.
  • Homepage JSON-LD validation: passed.
  • Internal-link scan: 425 Markdown files, 5,310 links, 0 broken.
  • Audit-script tests: 35 passed, including the base PR's consolidated-Teams seed regression.
  • Scoped before/after style checks: no new findings across the seven edited pages.
  • Existing heading anchors and permission-inventory table rows retained; the index gains the Azure row.
  • git diff --check: passed.
  • Relevant integration availability was checked in committed production configuration. This does not establish the deployed revision, runtime overrides, or successful provider consent.

Inherited length exceptions

Slack, Jira, and GitLab already exceed the combined-page budget. Their before/after word counts are 2,240 → 2,349; 1,691 → 1,751; and 1,563 → 1,592, respectively. The added material supplies prerequisites and actor handoffs; removing valid provider inventories or unrelated workflows to meet a budget would broaden this correction and lose useful information. These inherited overages remain explicit review findings, not an all-pass compression claim. No callouts or public pages were added. Connect your factory, Azure, and the general roles page remain within budget; the permissions index is a reference.

Local Node 25 is outside the declared package engine range; checks completed. Trunk is unavailable. No product settings, integration installations, credentials, or billing were changed.

Unverified claims

  • Live Slack manager authorization, provider approval, and subsequent factory-app provisioning were not exercised. The revised instructions use the verified sequence and existing setup context, not a newly invented UI button.
  • Exact member eligibility across Azure Manager setup/delegation paths, and Jira's distinct direct claim/reconnect/rebind path, still require owner reconciliation. The text recommends admin coordination rather than claiming every member is denied or publishing a new permission guarantee.
  • The deployed browser/server revision, effective account policies, and live provider consent remain unverified.

The repository contract checker can include markers inherited from the stacked base when comparing against main. They remain listed here, although these are not new PR 2 claims:

  • Standard factory-plan roles confirmed by Jason. Confirm legacy Terminal subscriptions and customer-facing treatment of account-specific entitlements before merge.
    Base role reference, “Managing admins.”
  • Exercise both the member-menu and editable-role-column paths in the production Admin Panel before merge, including demotion and confirmation behavior.
    Base role reference, “Promoting or demoting admins.”
  • confirm what team admins see when a workspace limit blocks usage before documenting that notice
    Base workspace reference, “Workspace spend limits.”
  • Confirm the launch setup flow and Blueprint preview against the live product; replace the removed agent-selection screenshot with current setup proof before publication.
    Base factory quickstart; its existing live-preview marker is unchanged.

Documentation risk

Risk: engineering-review-required
Rationale: Changes integration prerequisites and actor handoffs; live consent is untested and Azure/Jira policy reconciliation and inherited length exceptions remain explicit.
Source files consulted: Existing factory connection and provider guides, human/factory role references, and private implementation evidence retained in the internal plan.
Requested engineering reviewers: none
Engineering review status: pending
Docs override: none

Ownership lookup spans multiple engineers, so no reviewer is automatically requested.

Follow-ups

  • Resolve the owner-review questions before making stronger universal eligibility statements.
  • Retest actual browser/provider approval with authorized accounts before representing those product flows as passed.
  • The separate Docs usability validation toolkit has a handoff plan; no governance resources or generation workflow are changed in this PR.

Agent artifacts

Co-Authored-By: Warp agent@warp.dev

Put actor prerequisites beside setup, distinguish shared and per-factory Slack authorization, and index Azure DevOps without inventing a scope inventory.

Co-Authored-By: Warp <agent@warp.dev>
@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
docs Ready Ready Preview Nov 19, 2026 9:59pm UTC

Request Review

This branch was successfully deployed

1 active deployment
Preview — 8cbb3e3b Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

warpy-factory Opened by the Warp factory agents

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant