Add a provider-neutral first-push credential walkthrough to Module 8 (scopes, non-echo, caching) #39

New Issue

2026-06-22T14:23:56-04:00

claude commented

2026-06-22 14:23:56 -04:00

Problem

For a learner who has never used git, creating a credential and pushing the first time is the single most likely place to get stuck, and all of Unit 2 depends on the remote existing. The module flags this as "the most common first-push wall" but gives it little detail. Most importantly, it never mentions token SCOPES — a token that exists but lacks repo/write scope authenticates and then 403s on push, a distinct cause with a different fix (edit scopes, not regenerate) that the module currently mislabels.

Evidence

modules/08-remotes-and-hosting/README.md failure mode #1 (~lines 105-110): "for HTTPS, generate a personal access token … use it as your password when prompted; for SSH, generate a key (ssh-keygen) …"; lab: "Set this up first; failure mode #1 … is the most common first-push wall." The word "scope" never appears; non-echoing paste and credential caching are not mentioned.

Why it matters

A misdiagnosed wall on a load-bearing first-push step; "almost always a dead password/missing token" hides the scope cause. Affects the M8→Unit 2 chain and the honesty promise.

Proposed change

Add a provider-neutral "Getting a credential (the shape)" callout (lead with the scope gotcha):

Settings → tokens → create; must select repo/write scope, and a missing scope looks like an auth failure but is fixed by editing scopes, not regenerating.
Token is shown once — copy it now.
(Lighter, optional for this IT-pro audience) the pasted token won't appear on screen; a credential helper remembers it after first success.
Mark volatile UI labels Verify-before-publish.

Acceptance criteria

The module distinguishes a missing-scope failure (edit scopes) from a missing/dead token (create one).
The callout is provider-neutral and flags volatile UI labels Verify-before-publish.

Affected files

modules/08-remotes-and-hosting/README.md

References

Source finding F22 (realVotes 3/3).

Filed from an adversarial multi-agent course review (217 raw findings → 54 adversarially-verified survivors). Scoped for manual review; intentionally not auto-assigned to an agent.

## Problem For a learner who has never used git, creating a credential and pushing the first time is the single most likely place to get stuck, and all of Unit 2 depends on the remote existing. The module flags this as "the most common first-push wall" but gives it little detail. Most importantly, it never mentions token SCOPES — a token that exists but lacks `repo`/write scope authenticates and then 403s on push, a distinct cause with a different fix (edit scopes, not regenerate) that the module currently mislabels. ## Evidence `modules/08-remotes-and-hosting/README.md` failure mode #1 (~lines 105-110): "for HTTPS, generate a personal access token … use it as your password when prompted; for SSH, generate a key (`ssh-keygen`) …"; lab: "Set this up first; failure mode #1 … is the most common first-push wall." The word "scope" never appears; non-echoing paste and credential caching are not mentioned. ## Why it matters A misdiagnosed wall on a load-bearing first-push step; "almost always a dead password/missing token" hides the scope cause. Affects the M8→Unit 2 chain and the honesty promise. ## Proposed change Add a provider-neutral "Getting a credential (the shape)" callout (lead with the scope gotcha): - Settings → tokens → create; must select `repo`/write scope, and a missing scope looks like an auth failure but is fixed by editing scopes, not regenerating. - Token is shown once — copy it now. - (Lighter, optional for this IT-pro audience) the pasted token won't appear on screen; a credential helper remembers it after first success. Mark volatile UI labels Verify-before-publish. ## Acceptance criteria - [ ] The module distinguishes a missing-scope failure (edit scopes) from a missing/dead token (create one). - [ ] The callout is provider-neutral and flags volatile UI labels Verify-before-publish. ## Affected files - `modules/08-remotes-and-hosting/README.md` ## References Source finding F22 (realVotes 3/3). --- *Filed from an adversarial multi-agent course review (217 raw findings → 54 adversarially-verified survivors). Scoped for manual review; intentionally not auto-assigned to an agent.*