docs(onboarding): gate Step 6.2 watch check on notifications token scope

[serenakeyitan]

Fixes #332.

Problem

gh api /repos/<repo>/subscription returns 404 for every repo when the user's gh token lacks the notifications OAuth scope — which default gh auth login does not grant (typical scopes are admin:org, gist, repo, workflow). An agent following Step 6.2 on a default token would:

1. Run the check → get 404.
2. Conclude "not watching," tell the user to click Watch → All Activity.
3. User already is watching, clicks again, refreshes, agent re-runs → still 404.
4. Stuck.

Change

Step 6.2 now:

1. Runs gh auth status | grep notifications first.
2. If absent, tells the user to run gh auth refresh -h github.com -s notifications (interactive) and waits for confirmation.
3. Only then runs the /subscription check.

Also added a Pitfalls bullet so agents skimming ahead still catch the trap.

Test plan

• Read Step 6.2: flow is scope check → refresh if needed → subscription check.
• Read Pitfalls bullet: explains 404-without-scope explicitly.
• No changes outside skills/first-tree/references/onboarding.md.

Discovered during v0.2.15 onboarding test.

[yuezengwu]

The new scope gate still has a false-positive path: gh auth status 2>&1 | grep -i 'notifications' is not scoped to the active github.com account. On setups with multiple hosts or multiple stored accounts, that grep can match a different host/account that has the scope, so the agent skips the refresh and lands back in the same /subscription 404 loop for the account it is actually using. Please scope the check to the active github.com auth context (for example gh auth status --active --hostname github.com 2>&1 | grep -i 'notifications') and mirror that wording in the pitfalls note.

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.

[yuezengwu]

This check is too broad for the problem you’re trying to solve. gh auth status reports all known hosts and, on a host, can include multiple stored accounts; a plain grep can succeed on some other host/account that has notifications while the active github.com account still lacks it. In that case the agent would skip the refresh and the later /subscription call would still 404. Please scope the probe to the active github.com auth context, e.g. gh auth status --active --hostname github.com 2>&1 | grep -i 'notifications'.

[serenakeyitan]

Thanks — good catch. Pushed 045ad06 scoping both the Step 6.2 check and the Pitfalls bullet to gh auth status --active --hostname github.com so the grep only sees the active github.com account's token scopes. Verified against my own multi-output gh auth status — the scoped form cleanly returns just the active account's block.

[yuezengwu]

LGTM — 045ad06 scopes both the Step 6.2 check and the Pitfalls bullet to gh auth status --active --hostname github.com, which closes the multi-host / multi-account false-positive path. Thanks for the quick turnaround.

This reply was drafted by breeze, an autonomous agent running on behalf of the account owner.