feat(cli): guided credential setup for non-technical users (tracker MCP on doc-collab flavors)

[Lillevang]

Status: needs careful design — NOT in scope for now. This captures the problem and a recommended direction. The interaction model for guiding non-technical users without building a full wizard is the hard part and must be designed deliberately before any implementation. Tagged needs-refinement, no milestone.

Persona

A non-technical project/program manager — comfortable with PM work, not comfortable in a terminal (think: a program manager in her 60s). She wants to scaffold a project-management or claude-cowork workspace and may want to wire a tracker MCP (Azure DevOps, GitHub, or Jira) so her agent can read/write work items. She is the target user for the doc-collab flavors, and she is exactly the user most likely to hit a dead-end at the credential step.

Important context about the doc-collab flavors (shapes the whole design)

The project-management and claude-cowork flavors are not like the code flavors:

• No .devcontainer and no assumption of a git repo. They scaffold a folder structure and some .md files.
• They will most likely live in a regular folder or a shared folder (e.g. OneDrive), not a cloned repo.
• The actual work in these workspaces centers on .md, .docx, .xlsx, .pptx, .txt files — documents, not source code.

This matters because the existing credential guidance (env vars, .gitignore, "restart your MCP client") implicitly assumes a developer in a shell, in a git repo, possibly in a container. None of those hold here.

What she sees today — the four dead-ends

The secure-token plumbing from #17 is correct and unchanged (${env:VAR} references in .mcp.json, gitignored secret file, gh auth reuse). The gap is purely that the guidance assumes a shell-fluent reader. Concretely, running the scaffold + add-tracker leaves her at four walls:

1. Token/scope creation. She's told she needs a PAT / API token but not where to create it or which scopes to select.
2. Giving the token to the tool. Setting a persistent environment variable assumes shell knowledge she doesn't have.
3. "Restart your MCP client." Jargon with no concrete steps.
4. Silent wrong-scope failure. A missing/under-scoped token isn't caught at setup; it surfaces later as a raw Requires authentication — the worst dead-end, because it's far from the cause.

Recommended direction (smallest dead-end-free path — no full wizard)

A set-credential subcommand scoped to the doc-collab flavors, layering four UX moves on the existing #17 plumbing:

• Scope-preset deep links. Open (or print) the exact GitHub/ADO/Jira token-creation URL with the right scopes pre-selected, so she doesn't have to navigate provider settings.
• Write the credential for her, into the gitignored secret file — rather than telling her to export a shell variable. (See open question on the delivery mechanism below — this is the load-bearing uncertainty.)
• Validate before proceeding. Make a cheap test API call at setup time so she learns the token works now, with a plain-language result, instead of discovering a bad token three steps later.
• Reuse gh auth when already authenticated, so GitHub needs no manually-created token at all.

Plain-language errors throughout ("that token doesn't have permission to read work items — here's how to fix it" rather than Requires authentication).

Deliberately not a wizard. Per the #22 "no full interactive wizard" lean, this stays a single guided primitive. If PMs still stall after this ships, an interactive TTY flow can be added later as a thin wrapper over the same set-credential primitive — not a separate code path.

Open questions (must be settled in the careful-design pass)

1. Credential delivery mechanism — load-bearing. With no devcontainer and possibly no git repo, how does the credential actually reach the MCP client at launch? ${env:VAR} requires the var to be in the MCP client's environment. Does writing a secret/.env file in the workspace actually get sourced by the MCP client for these flavors, or does the variable need to be set at the OS/user level? If a workspace file isn't sourced, "write it for her" doesn't wire anything up. Verify how each MCP client (Claude Code / Codex) picks up the var in a no-container, non-shell context before committing to a mechanism.
2. Cross-platform reality. This persona is plausibly on Windows with the workspace in OneDrive. Deep-link opening, secret-file location, and how the env var is set all differ from the macOS/Linux dev case. The design must be correct on Windows, not just POSIX.
3. The interaction model without a wizard. How much hand-holding is "guided" vs. "a wizard"? Where exactly is the line? This is the careful-design question the maintainer flagged.
4. Per-tracker instruction maintenance. Deep links and scope presets for GitHub/ADO/Jira are external surfaces that drift; who maintains them and how do we avoid stale links.
5. Naming/shape: a set-credential subcommand vs. folding into add-tracker's flow.

Bloat to resist

• A GUI / desktop app entry point (rejected — against the small-and-simple ethos; out of scope).
• A full multi-screen interactive wizard (defer; only a thin TTY wrapper later if needed).
• Storing secrets anywhere new or bespoke — reuse the PM flavor: secure token/secret management for MCP trackers #17 mechanism, don't invent a vault.

Provisional acceptance criteria (pending the design pass)

• A non-technical user can go from "I have no token" to "my agent can read/write work items" without editing .mcp.json by hand or knowing shell commands.
• The flow links to the exact token-creation page with correct scopes per tracker.
• The token is validated with a real call before the flow reports success; failures explain the cause in plain language.
• Existing gh auth is detected and reused (no manual token for GitHub in that case).
• Works on Windows with a workspace in a shared folder (OneDrive), not just POSIX/git-repo setups.
• No full wizard; the guided primitive is the surface.

Related

• PM flavor: secure token/secret management for MCP trackers #17 — secure token mechanism (this builds on it, doesn't change it).
• Spike: make bootstrap seamless — minimize user effort to enable the agent #22 — "no full interactive wizard" bloat-to-resist (the tension this issue must respect).
• feat(cli): support local visibility — ignore the agent-init scaffold in the committed .gitignore #51/feat(cli): support global-default visibility — ignore the agent-init scaffold in all repos via core.excludesfile #52/feat(cli): support hidden visibility — fully hide the scaffold in one repo via .git/info/exclude (no committed trace) #53 — visibility modes (mostly N/A for doc-collab, which is out of scope for hiding).
• Surfaced by a UX ideation pass on the non-technical PM persona, 2026-05-25.

[Lillevang]

Recommended approach + refinement notes

Following a technical analysis of the codebase and a maintainer clarification on the credential-delivery question.

Credential delivery — the load-bearing question, now mostly answered

The open question was how a credential actually reaches the MCP client at launch in a no-container, non-shell context. Maintainer clarification: as long as .mcp.json sits in the folder being worked in, the MCP server is picked up — confirmed for project-management in Claude Code. So the .mcp.json-in-workspace mechanism is the right one; we do not need to mutate the user's OS environment.

Two things still need empirical verification before the design freezes (filed as testing issues):

• test: verify tracker MCP credential resolution works in Codex #68 — does the same .mcp.json-in-folder + ${env:VAR} resolution work in Codex?
• test: verify tracker MCP works for the claude-cowork flavor (Claude Code) #69 — does it work for claude-cowork, which has never been tested with an MCP server and currently ships no .mcp.json (and add-tracker rejects it)?

Confirmed concern: a workspace-level .env is not assumed to be auto-sourced — the secret must be present in the environment the MCP client launches with. The "write the credential for her" UX must target a mechanism that's actually read at launch, not just drop a .env and hope. #68/#69 will pin the exact mechanism per client.

Recommended implementation shape (once #68/#69 land)

Three pieces, sequenced so the low-risk parts can move independently of the design-heavy subcommand:

1. Make trackers declarative (low-risk, unblocks now). Add TokenURL, Scopes []string, and SecretEnvVars []string to the Tracker struct (internal/trackers/tracker.go), populated from the scope prose already in the integration READMEs. Immediately improves add-tracker's printed guidance (deep links + exact scopes) with no UX commitment.
2. Add a credverify package (low-risk, unblocks now). One validator per tracker doing a cheap authenticated call (GitHub /user, ADO connectionData, Jira /myself) behind an injected http.Client, so wrong-scope/expired tokens fail loudly with a plain-language message instead of a later raw Requires authentication. Keeps the trackers package pure and the network code unit-testable with a fake client. Can be wired into add-tracker first.
3. set-credential subcommand (design-gated). A separate primitive — NOT folded into add-tracker, which should stay pure/idempotent/non-interactive. It resolves the tracker, surfaces the scope-preset deep link, accepts/reuses the token (gh auth token for GitHub), writes it via the test: verify tracker MCP credential resolution works in Codex #68/test: verify tracker MCP works for the claude-cowork flavor (Claude Code) #69-confirmed mechanism, validates with credverify, and reports in plain language. Gate it to doc-collab flavors via a new SupportsCredentialSetup capability flag on Flavor (mirroring the existing SupportsAgentsOnly pattern), not by inspecting flavor internals. No scaffold-engine changes needed. Honors the Spike: make bootstrap seamless — minimize user effort to enable the agent #22 "no full wizard" lean — a thin TTY wrapper over this primitive can come later if PMs still stall.

Decisions still needed before step 3

• claude-cowork scope: it has no tracker plumbing today. Either scope set-credential to project-management only, or enable trackers for claude-cowork first (ship .mcp.json, relax the add-tracker guard) — tracked in test: verify tracker MCP works for the claude-cowork flavor (Claude Code) #69 and related to Offer tracker MCP (GitHub/ADO/Jira) as an optional add-on to all flavors #18.
• Guided vs. wizard line (Spike: make bootstrap seamless — minimize user effort to enable the agent #22) — where the primitive stops (e.g. is stdin token entry already "wizard"?).
• External drift — deep-link URLs/scopes for GitHub/ADO/Jira rot over time; needs a maintenance owner (ADO is already the least-mature integration).

Suggested sequencing

Steps 1 and 2 are independent, low-risk, and high-value — they could be split into their own issues and move now (improving add-tracker immediately) while #68/#69 resolve the delivery mechanism. Step 3 (set-credential) stays blocked on #68/#69 + the claude-cowork and guided-vs-wizard decisions.

Builds on #17 (don't change the secret mechanism); respects #22 (no wizard). Visibility modes (#51–#53) are N/A for doc-collab flavors.