feat(setup): guide setup and bot PAT creation

README.md

@@ -60,6 +60,10 @@ on the exact existing branch and push normal commits, but do not create, rename,
 delete, replace, or force-push managed branches.
 
 The setup PAT entered by the operator is separate from the workflow `PAT` Secret.
+Interactive setup can guide creation of both via GitHub's prefilled PAT form:
+picks the permission-affecting setup options first, then the operator creates a temporary setup token, and the bot account creates the
+persistent workflow token. GitHub handles account switching, 2FA, repository
+selection, and final creation; Copilot never creates or revokes either token.
 Use `copilot setup --dry-run` to inspect the plan before making local or remote
 changes. See the complete [How to use](https://docs.page/vypdev/copilot/how-to-use)
 guide and [Authentication](https://docs.page/vypdev/copilot/authentication).

docs/authentication.mdx

@@ -12,6 +12,41 @@ For [guarded PR approval](/pull-requests/guarded-approval), this same runtime PA
 
 The setup PAT and workflow PAT may have different owners and permissions. Do not paste the workflow PAT into the setup prompt unless you intentionally want the same token to perform both roles.
 
+## Assisted creation in the terminal
+
+When `copilot setup` needs a PAT interactively, it offers a guided link (the
+default) or manual entry. In guided mode it first asks the setup choices that
+determine PAT permissions: issue workflows, initial tag, Secret and Variable
+management and storage scope, PR approval mode, and Projects. Choices already
+fixed by flags or `--config` are not asked. You review the resulting grants
+before the link appears; these answers carry into the full wizard without being
+asked twice. The link is still **provisional** for facts that require GitHub
+inspection, such as existing Secrets, inherited organization resources, and a
+missing credential-health workflow. If the final plan needs
+additional grants, setup stops before applying it and prints a corrected link.
+Update the PAT in GitHub or create a replacement, then rerun setup. Guided
+setup shows the account returned by GitHub and asks you to confirm it.
+
+After the plan, the bot link uses the selected workflow permissions. Enter the
+expected bot login first: setup resolves its GitHub numeric ID, then checks the
+PAT's own `/user` identity against that ID before any Secret write. A manual or
+non-interactive PAT retains the existing permission audit but does **not** gain
+this extra identity binding. A wrong bot account blocks installation.
+
+Both links use GitHub's [documented fine-grained PAT form](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+They do not sign you in, complete 2FA, generate or revoke a token, or choose
+an individual repository. Check the active browser account, change **All
+repositories** to **Only select repositories**, select only the
+target repository, and review the final GitHub form. A guided setup PAT uses a
+one-day suggested expiry; delete it yourself in [GitHub PAT Settings](https://github.com/settings/personal-access-tokens)
+afterward. The bot PAT uses a 90-day suggested expiry, may be shortened by
+organization policy, and remains in Actions Secret `PAT`; arrange renewal
+before it expires. If guarded approval requires `Checks`, GitHub's fine-grained
+PAT cannot prefill or provide that permission. Setup omits the guided bot link
+for that plan; review a compatible manually created credential and the
+permission audit instead. Existing command-line token flags also remain, but
+putting a PAT in a command can expose it in shell history or process listings.
+
 ## Permission tables in `copilot setup`
 
 Immediately before each hidden PAT prompt, interactive setup prints a

docs/configuration.mdx

@@ -185,10 +185,20 @@ storage:
       OPENAI_API_KEY: organization
 ```
 
-The immutable questionnaire first inspects the repository and reports repository-scoped resources, organization resources available to that repository, repository visibility, and access errors. It then asks separately about Secret and Variable storage. Each accepted answer creates a fresh configuration snapshot; defaults, overrides, prior answers, and the result do not share mutable nested references. Repository resources take precedence over organization resources. With `preserveExisting: true`, an effective organization resource is inherited instead of being shadowed by a new repository value; add a name under `storage.secrets.overrides` or `storage.variables.overrides` when a repository-specific value is intentional.
+Guided setup asks the permission-affecting Secret and Variable management and default-scope questions before the setup PAT is created. After token authentication, the remaining questionnaire inspects the repository and reports repository-scoped resources, organization resources available to that repository, visibility, and access errors. Remote-dependent inherited-resource overrides are asked then; they may require a corrected PAT. Each accepted answer creates a fresh configuration snapshot; defaults, overrides, prior answers, and the result do not share mutable nested references. Repository resources take precedence over organization resources. With `preserveExisting: true`, an effective organization resource is inherited instead of being shadowed by a new repository value; add a name under `storage.secrets.overrides` or `storage.variables.overrides` when a repository-specific value is intentional.
 
 Organization storage is available only for organization-owned repositories and requires organization Actions permissions on the setup PAT. If only one class should be global, set that class to `organization` and leave the other at `repository`. `--skip-secrets` and `--skip-variables` disable their respective setup operations without changing the other class.
 
+Interactive PAT guidance does not add configuration keys: it is a one-run
+choice at each hidden prompt. The setup-PAT form link contains grants derived
+from reviewed local intent; remote-only conditions are disclosed separately
+and may require correction after inspection. The bot-PAT
+link is built from the final workflow permission policy and suggests a 90-day
+expiry; the bot account owner must renew it and replace Secret `PAT` before
+expiration. Manual and non-interactive token inputs keep their existing
+precedence and validation. See [authentication](/authentication) for the
+GitHub-owned creation, account verification, and deletion steps.
+
 `--non-interactive` constructs no terminal and resolves only defaults, config,
 flags, and explicit external inputs. `--yes` approves the final plan but never
 invents a missing token, credential, target, or storage prerequisite. There is

docs/development/architecture.mdx

@@ -152,6 +152,7 @@ The setup policy is intentionally split by responsibility:
   resolution and effective-resource preservation.
 - `setup_configuration_clone_policy.ts` owns reference-isolated configuration copies.
 - `setup_questionnaire_policy.ts` owns setup states, questions, transitions, and answers.
+- `setup_pat_intent_policy.ts` identifies setup choices fixed by local inputs and owner-kind conflicts.
 - `setup_configuration_plan.ts` owns the reviewable provisioning plan.
 - `setup_token_permission_policy.ts` owns the setup/workflow PAT permission
   catalogs, conditional capability projection, strongest-level normalization,
@@ -160,6 +161,21 @@ The setup policy is intentionally split by responsibility:
 - `setup_resource_provisioning.ts` owns grouping and port calls for Variables
   and Secrets.
 
+Assisted PAT creation uses the existing permission policy as its only grant
+source. Guided setup runs a permission-intent phase of the same questionnaire
+before token entry, projects local choices through the setup permission policy,
+and carries the draft and answered IDs into the remaining questionnaire. The
+projection leaves remote-only grants unresolved for the final audit. The pure
+`setup_pat_creation_url_policy.ts` maps required grants to
+documented GitHub form parameters and rejects unsupported grants; it never
+receives token material. `setup.ts` wires the terminal choice and hidden input
+to that policy. In guided bot mode, the identity query adapter resolves the
+chosen login through GitHub and identifies the supplied PAT through `/user`;
+the application use case compares immutable numeric IDs before local setup
+can write Secrets. GitHub owns the browser session, 2FA, token generation, and
+deletion. Manual and unattended inputs retain the prior audit without the new
+bot-ID assertion.
+
 PAT permission validation follows the same dependency rule. The application
 `SetupTokenPermissionsUseCase` validates identity before invoking the narrow
 `SetupTokenPermissionQueryPort`; the infrastructure adapter performs only safe

docs/how-to-use.mdx

@@ -38,6 +38,22 @@ If the checkout does not include the compiled `build/` folder (e.g. it is gitign
 
 Once installed, the `copilot` command is available globally. Repository-dependent commands such as `copilot setup`, `copilot doctor`, `copilot check-progress`, `copilot think`, and `copilot do` must be run **from the root of the target repository**. The `copilot upgrade`, `copilot --version`, and help flows can run from any directory. Commands that access GitHub accept `--token` or `PERSONAL_ACCESS_TOKEN` from the environment. `copilot setup` and `copilot doctor` securely prompt for the setup PAT when run interactively; no `.env` file is read or created. `copilot setup --dry-run` is the only setup mode that can run without a token. See [CLI commands](/single-actions/workflow-and-cli).
 
+Interactive `copilot setup` offers a guided GitHub link or manual entry for each
+PAT. The first link prepares a short-lived **setup PAT** for the person
+configuring the repository. Before showing it, guided setup asks only the local
+choices that affect its grants, shows an exact permission preview and notes
+what remains unknown until GitHub is inspected. The later questionnaire reuses
+those answers. The second link, after the setup plan, prepares the
+**workflow PAT** for the bot account. Open each link in the appropriate GitHub
+account, complete GitHub's sign-in/2FA, change **All repositories** to **Only
+select repositories**, and **select only the intended repository**
+on the form, review the grants, and paste the generated value into the hidden
+terminal prompt. The links prefill fields; they neither create a PAT nor select
+an individual repository. The setup PAT is suggested for one day and must be
+deleted by you in GitHub after the run. The bot PAT is suggested for 90 days,
+remains active as Actions Secret `PAT`, and needs renewal before expiry. See
+[authentication](/authentication) for permission and recovery details.
+
 If you previously installed Copilot from a local checkout, installing the published
 package with pnpm switches the same `copilot` command to the published package.
 Check which executable and package are active:
@@ -112,14 +128,14 @@ The complete command reference, including every supported option, is in [Workflo
     copilot setup
     ```
 
-    Before applying the plan, the wizard securely asks for the setup PAT. For automation, pass it explicitly or through the environment:
+    In guided interactive setup, answer the short permission-intent questions and review the proposed grants before creating the setup PAT in GitHub. The wizard then securely asks for the token and continues with the remaining plan questions. For automation, pass it explicitly or through the environment:
 
     ```bash
     PERSONAL_ACCESS_TOKEN=your_setup_pat copilot setup --non-interactive --yes --skip-secrets
     # or: copilot setup --token your_setup_pat
     ```
 
-    The wizard shows a reviewable plan and asks for confirmation. Its forward-only questionnaire keeps defaults and every answer immutable; cancel and rerun if you need to revise an earlier stage. `Ctrl-C` or end-of-input exits 130 with no writes, while declining the final plan exits 0 with no writes. Use `copilot setup --dry-run` to inspect the plan without a token or changes.
+    The wizard shows a reviewable plan and asks for confirmation. You may revise the pre-PAT intent before opening GitHub; after entering the PAT, the remaining questionnaire is forward-only. Cancel and rerun to revise an earlier stage. `Ctrl-C` or end-of-input exits 130 with no writes before application, while declining the final plan exits 0 with no writes. Use `copilot setup --dry-run` to inspect the plan without a token or changes.
 
     In automation, `--non-interactive` creates no terminal. `--yes` approves only the final plan: it does not supply a missing setup PAT, workflow credential, provider credential, target, organization prerequisite, or permission acknowledgement. If every required read is verified or positively operationally usable but safe probes cannot prove required writes, inspect the PAT settings first and pass the separate `--confirm-unverifiable-write-permissions` flag. It never bypasses missing or unusable unverifiable read access.
 

docs/security-operations/operations/troubleshooting.mdx

@@ -9,6 +9,20 @@ If guarded PR approval is missing, run `copilot doctor` and inspect the ordered
 
 This guide helps you resolve common issues you might encounter while using Copilot. Expand the section that matches your problem.
 
+If the guided setup PAT belongs to the wrong account, decline the account
+confirmation, delete the unintended PAT in [GitHub PAT Settings](https://github.com/settings/personal-access-tokens),
+and rerun setup in the correct browser account. If the final permission table
+requires more than the reviewed local-intent link, inspect the named grant
+delta, use the corrected link printed by setup, and rerun; no approved setup
+mutation has started. If the final plan removes grants, your existing PAT may
+have excess access; replace it for strict least privilege. A guided bot PAT
+created while signed into another account fails the numeric-ID check before
+the Secret is written. Delete that unused PAT and create one as the chosen bot.
+If setup fails after applying changes, inspect the Actions Secret name and
+scope before revoking or replacing the bot PAT: it may already be active.
+Cancelling setup never revokes either PAT. Delete an unused setup PAT in GitHub;
+renew an installed bot PAT before its suggested 90-day expiry.
+
 <AccordionGroup>
   <Accordion title="Setup is cancelled or doctor shows skipped checks" icon="circle-exclamation">
     **Setup cancellation:** `Ctrl-C` or end-of-input intentionally exits 130 and