docs: explain the profile model and why 'default' stays - #176
Merged
Conversation
Closes out the headline question from the credential-UX review: should the 'default' profile exist at all? Decision: yes - documented here so the reasoning survives. - '<service>/default' is the codified family-wide convention (cli-common working-with-secrets.md par.2.1, credstore.DefaultProfile); removing or renaming it breaks every existing install and diverges gro from its siblings for no mechanical gain. - Naming profiles after accounts can't be the default: emails aren't valid ref segments ([A-Za-z0-9_-]), and the account is only known AFTER auth. Users who want purposeful names have them: init --profile work. - The actual failure mode was never the name - it was an invisible pointer that silently went stale. That is fixed mechanically: profiles list (visibility), attributed auth errors (blame the right profile), init target naming + --profile (no silent overwrites), profiles use (deliberate binding). This section makes the model explicit for users: profiles are independent, the active binding is inspectable and deliberate, adding never overwrites.
piekstra-dev
approved these changes
Aug 12, 2026
piekstra-dev
left a comment
piekstra-dev
left a comment
There was a problem hiding this comment.
Automated PR Review
Reviewed commit: c8b12737f08d
Profile: reviewer - Posting as: piekstra-dev
Summary
| Reviewer | Findings |
|---|---|
| documentation:docs | 0 |
Reviewer Coverage
| Reviewer | Status | Inspected | Skipped | Constraints |
|---|---|---|---|---|
| documentation:docs | complete_broad | README.md | unavailable | The new section's claim that profile names allow only letters, digits, -, and _ reflects a validation rule presumed to live in the sibling cli-common repo, which is not checked out here; not independently verifiable from this repo's source. |
0 PR discussion threads considered. 0 summarized; 0 resolved.
Completed in 1m 46s | $0.81 | claude-sonnet-5 | cr 0.10.268
| Field | Value |
|---|---|
| Model | claude-sonnet-5 |
| Reviewers | documentation:docs |
| Engine | claude_cli · claude-sonnet-5 |
| Reviewed by | cr · piekstra-dev |
| Duration | 1m 46s wall · 1m 35s compute |
| Cost | $0.81 |
| Tokens | 44 in / 7.3k out |
Per-workstream usage
| Workstream | Model | In | Out | Cache read | Cache create | Cost | Duration |
|---|---|---|---|---|---|---|---|
| orchestrator-selection | claude-sonnet-5 | 6 | 655 | 58.9k | 11.9k | $0.10 | 14s |
| documentation:docs | claude-sonnet-5 | 32 | 6.3k | 737.4k | 47.2k | $0.60 | 1m 12s |
| orchestrator-rollup | claude-sonnet-5 | 6 | 366 | 65.8k | 14.0k | $0.11 | 9s |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
Closes out the headline question from the credential-UX review: should the
defaultprofile exist at all? It was reconsidered seriously — the incident that prompted it was real (a silently-stale active profile misread as "gro is dead").Decision: keep
default; fix the failure mode mechanically<service>/defaultis the codified family-wide convention (cli-commonworking-with-secrets.md§2.1,credstore.DefaultProfile— same asatlassian-cli/default). Removing or renaming it is a breaking change for every existing install and diverges gro from its siblings, for no mechanical gain.[A-Za-z0-9_-]), and the account is only known after authentication. Users who want purposeful names already have them:gro init --profile work.profiles list(visibility), attributed auth errors (blames the right profile, points at the list), init target naming +--profile(no silent overwrites),profiles use(deliberate binding).What
A README section ("Profiles: how gro handles multiple Google accounts") making the model explicit: profiles are independent; the active binding is visible and deliberate; adding an account never overwrites one. Placed directly above the existing per-invocation
--refsection.Docs only; no code changes.