Fix critical end-user journey gaps surfaced in v0.2 audit

Four gaps caught by the end-to-end audit against this repo, the
playground, and the prior agentfolio trial-memory notes:

1. Add 'workflow' scope preflight to both install skills. Default
   'gh auth login' lacks the workflow scope, so the user's first
   'git push' of a .lock.yml fails with "refusing to allow an
   OAuth App to create or update workflow without 'workflow' scope".
   Agentfolio memory flagged this gotcha; the plugin never checked
   for it until now. Fix: 'gh auth refresh -s workflow -h github.com'.

2. Stale "Every push to main" claim on update-docs in README.md and
   CONTRIBUTING.md. update-docs switched to 'schedule: daily' in
   d4295cf earlier today. Also cleaned up a stale pr-nitpick-reviewer
   reference in CONTRIBUTING (we removed it from dogfooding in b3f6341).

3. Strengthen the 'claude setup-token' TTY warning in auth.md. The
   command opens a browser auth flow and silently hangs in headless
   containers, SSH without forwarding, and the Claude Code REPL
   itself. New note: run it on a local laptop, paste the token into
   'gh secret set' (which doesn't need a browser) elsewhere.

4. Fix reviewer-agent pipeline-summary run-id lookup. Instruction
   said 'gh run list --workflow=<name>.yml' but the actual files
   are <name>.lock.yml. Switched to --workflow="<Display Name>"
   form, which is more stable (file names could change; display
   names are human-authored).

Caught before the audit caused a real user to trip, but flagging:
(2) and (3) directly, (1) inherited from the author's own past
agentfolio session (the dev environment's privileged setup masked
it from the dogfood), (4) degraded silently in dogfood #6 without
anyone noticing.

Author: verkyyi

CONTRIBUTING.md

@@ -98,8 +98,8 @@ If a workflow `.md` source needs changing:
 
 1. Fork the repo and create a branch: `git checkout -b <type>/<short-description>`
 2. Make changes and test locally.
-3. Open a draft PR against `main`. Draft PRs trigger the `pr-nitpick-reviewer` workflow on `/nit` — use it for style feedback before marking ready.
-4. The `update-docs` workflow runs on every push to `main` and will open a follow-up PR if your change creates a documentation gap.
+3. Open a draft PR against `main`.
+4. The `update-docs` workflow runs on a daily schedule (and is manually dispatchable via `gh workflow run update-docs.lock.yml`); it opens a follow-up PR when your change creates a documentation gap.
 
 Branch naming conventions:
 

README.md

@@ -99,7 +99,7 @@ This repo dogfoods three workflows on itself, chosen as genuinely useful for a s
 | Workflow | Trigger | Purpose |
 |---|---|---|
 | [daily-repo-status](.github/workflows/daily-repo-status.md) | Daily | Opens a `[repo-status]` issue summarizing recent activity — the recommended first-run starter |
-| [update-docs](.github/workflows/update-docs.md) | Every push to `main` | Detects documentation drift and opens draft PRs to keep docs in sync with code changes |
+| [update-docs](.github/workflows/update-docs.md) | Daily + manual | Detects documentation drift and opens draft PRs to keep docs in sync with code changes |
 | [weekly-research](.github/workflows/weekly-research.md) | Weekly (Monday) | Strategic research across Anthropic policy, plugin ecosystem, gh-aw upstream, competitors, and solo-founder hiring signal |
 
 All three use `engine: claude` and are pre-configured with the [OAuth token tweak](skills/install-workflow/auth.md). The agent-team pattern under [catalog/agent-team/](catalog/agent-team/README.md) is *not* installed here — it lives in a separate playground repo, since running it here would aim the implementer agent at this repo's own code.

catalog/agent-team/reviewer-agent.md

@@ -142,7 +142,15 @@ Then take the **one** action matching the verdict:
   <!-- /agent-team:summary -->
   ```
 
-  To fill in the `<spec-run-id>`, `<plan-run-id>`, `<impl-run-id>` fields: use `gh run list --workflow=<name>.yml --json databaseId,createdAt,conclusion --limit 10` and pick the most recent successful run of each stage that precedes yours in time. If a run-id lookup fails for any stage, write `(run link unavailable)` in that row instead of guessing — don't block the pipeline on a cosmetic link.
+  To fill in the `<spec-run-id>`, `<plan-run-id>`, `<impl-run-id>` fields, use the workflow display name (not the file name):
+
+  ```
+  gh run list --workflow="Spec Agent"        --json databaseId,createdAt,conclusion --limit 10
+  gh run list --workflow="Planner Agent"     --json databaseId,createdAt,conclusion --limit 10
+  gh run list --workflow="Implementer Agent" --json databaseId,createdAt,conclusion --limit 10
+  ```
+
+  Pick the most recent **successful** run of each stage that precedes yours in time. If a run-id lookup fails for any stage, write `(run link unavailable)` in that row instead of guessing — don't block the pipeline on a cosmetic link.
 
 - **Kickback** → Add `state:impl-needed` to the issue (cosmetic breadcrumb). Remove `state:review-needed`. **Dispatch the implementer-agent workflow** with:
     - `issue_number`: from your input

skills/install-agent-team/SKILL.md

@@ -31,6 +31,7 @@ One paragraph: four workflows will be added, one auth secret will be set, seven
 Check in parallel:
 
 - `gh` CLI authenticated (`gh auth status`)
+- **`workflow` scope present on the `gh` token** (`gh auth status -t 2>&1 | grep -i 'token scopes'`). Without it, the user's first `git push` of `.github/workflows/*.lock.yml` will fail with *"refusing to allow an OAuth App to create or update workflow ... without `workflow` scope"*. If missing, have the user run `gh auth refresh -s workflow -h github.com` (browser flow, ~30 sec) before continuing.
 - `gh aw` extension installed (`gh extension list | grep gh-aw`)
 - Current dir is a git repo clean enough to commit (`git status --porcelain`)
 - User has write access to `origin` (`gh repo view --json viewerPermission`)

skills/install-workflow/SKILL.md

@@ -10,7 +10,13 @@ Install one workflow from the upstream `githubnext/agentics` catalog into the cu
 ## Flow
 
 1. If the user didn't name a workflow, pitch `daily-repo-status` as the recommended starter — it creates a daily GitHub issue summarizing repo activity, needs only read + issue-create permissions, and gives visible value on the first run. Offer to proceed with it, or run `/discover-workflows` for the full catalog. Otherwise, treat the name as a workflow in `githubnext/agentics/workflows/` — `gh aw add <workflow>` in Step 4 will fail cleanly if the name doesn't resolve.
-2. Check prerequisites: `gh` CLI authenticated, `gh aw` extension installed, write access to the repo. Surface missing pieces plainly; don't try to install tools on the user's behalf.
+2. Check prerequisites:
+   - `gh` CLI authenticated (`gh auth status`)
+   - `gh aw` extension installed (`gh extension list | grep gh-aw`)
+   - Write access to the repo (`gh repo view --json viewerPermission`)
+   - **`workflow` scope present on the `gh` token** — check via `gh auth status -t 2>&1 | grep -i 'token scopes'` or inspect the scopes line. Without it, the user's first `git push` of the generated `.lock.yml` will fail with *"refusing to allow an OAuth App to create or update workflow ... without `workflow` scope"*. If missing, have the user run `gh auth refresh -s workflow -h github.com` (one-line fix, opens a browser auth flow for the scope bump) before proceeding.
+
+   Surface missing pieces plainly; don't try to install tools on the user's behalf.
 3. Pick auth path and set the secret — see `auth.md`. Ask once: subscription or API key? Before asking, check `gh secret list` — if the matching secret already exists, skip the setup and use it. Otherwise, for OAuth path guide the user through `claude setup-token` + `gh secret set CLAUDE_CODE_OAUTH_TOKEN`; for API-key path, `gh secret set ANTHROPIC_API_KEY`.
 4. Run `gh aw add <workflow>` — fetches source and compiles the `.lock.yml`. **The name must be fully qualified** as `githubnext/agentics/<workflow>` (bare names fail with "invalid workflow specification").
 5. Inspect the fetched `.md` for an `engine:` field. Upstream agentics workflows that omit `engine:` default to the `copilot` engine — which ignores the Claude secret and won't use your auth. If missing, add `engine: claude` to the frontmatter and run `gh aw compile <workflow>` to regenerate the `.lock.yml`.

skills/install-workflow/auth.md

@@ -18,14 +18,16 @@ Never guess. Ask if ambiguous.
 
 ### Step 1 — generate the subscription OAuth token
 
-The user runs, in a real TTY:
+The user runs, in a real TTY **on a machine with a browser available**:
 
 ```
 claude setup-token
 ```
 
 Opens browser auth flow, prints a token starting with `sk-ant-oat01-...`. The skill never sees the token.
 
+**Do NOT run this inside**: headless containers / dev-containers without port forwarding, SSH sessions without browser forwarding, CI runners, or the Claude Code REPL itself — the command will silently hang waiting for a browser callback that never arrives. When in doubt, run it on the user's local laptop and paste the token into `gh secret set` in Step 2 (which can run anywhere, since stdin-piped secret values don't need a browser).
+
 ### Step 2 — set the repo secret
 
 ```