docs(tokens): rewrite token model documentation for clarity + explicit minimum scopes #356

New issue

Closed

opened 2026-07-03 23:42:48 +02:00 by bosun · 1 comment

bosun commented

2026-07-03 23:42:48 +02:00

Owner

Empirical finding (external cold-read round 2)

External reviewer: "Token model is complicated" — the docs explain token modes, but "works without a token" is heavily qualified. Protected branches and required checks push adopters toward a bot PAT and whitelist configuration. But the docs bury the requirement.

Related to round-1 #333 which we thought we closed. Round-2 finding is that the rewrite (#333/#349) still doesn't clearly answer the adopter's practical question: "What token do I actually need, with what scopes, for MY situation?"

Blocking rationale

External review: "I would not give it a Forgejo/Codeberg token on a real repo." Trust-breaking. Adopters cannot make the token decision from docs alone.

Fix path

Add a Token Decision Matrix at top of integration.md: adopter answers 3 questions (protected main? required checks? autonomous manifest updates?), matrix outputs required token scope
Explicit minimum scopes named per matrix path ("read:repository + write:issue" NOT "repository:read+write" generic)
Explicit example token YAML block for each matrix path
Sample bot user setup instructions (recommended, not tribal knowledge)
Failure-mode examples: what error do you see if the token scope is wrong?

Verification AC

Every path adopter might follow leads to an explicit answer on token scope
External cold-read round 3 finds no token-model complexity objection

Anchor

External outside-model cold-read round 2 (fresh ChatGPT session, 2026-07-03 late) returned new findings after Pilot Cold-Read delta had cleared. External verdict: 'promising but not yet trustworthy.' Operator ratified delta plan 2026-07-03 23:35. This tracker addresses one of the round-2 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

## Empirical finding (external cold-read round 2) External reviewer: "Token model is complicated" — the docs explain token modes, but "works without a token" is heavily qualified. Protected branches and required checks push adopters toward a bot PAT and whitelist configuration. But the docs bury the requirement. Related to round-1 #333 which we thought we closed. Round-2 finding is that the rewrite (#333/#349) still doesn't clearly answer the adopter's practical question: "What token do I actually need, with what scopes, for MY situation?" ## Blocking rationale External review: "I would not give it a Forgejo/Codeberg token on a real repo." Trust-breaking. Adopters cannot make the token decision from docs alone. ## Fix path - Add a Token Decision Matrix at top of integration.md: adopter answers 3 questions (protected main? required checks? autonomous manifest updates?), matrix outputs required token scope - Explicit minimum scopes named per matrix path ("read:repository + write:issue" NOT "repository:read+write" generic) - Explicit example `token` YAML block for each matrix path - Sample bot user setup instructions (recommended, not tribal knowledge) - Failure-mode examples: what error do you see if the token scope is wrong? ## Verification AC - Every path adopter might follow leads to an explicit answer on token scope - External cold-read round 3 finds no token-model complexity objection ## Anchor External outside-model cold-read round 2 (fresh ChatGPT session, 2026-07-03 late) returned new findings after Pilot Cold-Read delta had cleared. External verdict: 'promising but not yet trustworthy.' Operator ratified delta plan 2026-07-03 23:35. This tracker addresses one of the round-2 findings. Success criterion: subsequent external cold-read returns no further objections of this class.

bosun added the

priority/high

size/M

kind/docs

labels

2026-07-03 23:42:48 +02:00

quartermaster referenced this issue from a commit

2026-07-04 00:03:00 +02:00

docs(tokens): token decision matrix + failure modes + bot provisioning (#356)

quartermaster referenced this issue

2026-07-04 00:03:29 +02:00

docs: round-2 adopter-honesty bundle — tokens + Codeberg positioning + tag creation (#356 #358 #359) #364

quartermaster referenced this issue from a commit

2026-07-04 00:10:32 +02:00

docs(tokens): token decision matrix + failure modes + bot provisioning (#356)

release-bot referenced this issue

2026-07-04 00:10:59 +02:00

chore(release): v0.26.0 #327

quartermaster commented

2026-07-04 00:15:13 +02:00

Owner

Delta merged via PR #364 at 886abbb. Token Decision Matrix (3-question tree → path α/γ per adopter situation) + Sample Failure Modes (4 concrete errors + fixes) + Bot User Provisioning (5-step walkthrough) + secrets: inherit wiring example all landed in docs/integration.md. Retires the 'token model is complicated' trust-dent.

Delta merged via [PR #364](https://git.frankenbit.de/frankenbit/release-toolkit/pulls/364) at 886abbb. Token Decision Matrix (3-question tree → path α/γ per adopter situation) + Sample Failure Modes (4 concrete errors + fixes) + Bot User Provisioning (5-step walkthrough) + `secrets: inherit` wiring example all landed in `docs/integration.md`. Retires the 'token model is complicated' trust-dent.

quartermaster closed this issue

2026-07-04 00:15:13 +02:00