docs: group flags by plugin applicability in connection and scope add help text

[Copilot]

Users had no way to know which flags apply to which plugin without reading source code — all flags were listed flat with no plugin attribution.

Changes

• cmd/configure_connection_add.go — replaced bare token resolution note with structured sections: Shared flags (all plugins), GitHub Copilot-specific flags (--enterprise, --org), and per-plugin usage examples
• cmd/configure_scope_add.go — replaced two-line example block with structured sections: Shared flags, GitHub-specific flags (repos, DORA config), GitHub Copilot-specific flags (--enterprise), and per-plugin examples with --connection-id

No behavioral changes — flag wiring is untouched.

$ gh devlake configure scope add --help

Shared flags (all plugins):
  --plugin             Plugin to configure (required in flag mode)
  --connection-id      Connection ID (required in flag mode)
  --org                Organization slug

GitHub-specific flags:
  --repos              Comma-separated repos (owner/repo)
  --repos-file         Path to file with repos (one per line)
  --deployment-pattern Regex to match deployment workflows
  --production-pattern Regex to match production environment
  --incident-label     Issue label for incidents

GitHub Copilot-specific flags:
  --enterprise         Enterprise slug (enables enterprise-level metrics)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Document plugin-specific flag applicability in help text</issue_title>
<issue_description>## Problem

Several flags on configure connection and configure scope are plugin-specific, but this isn't documented anywhere in the CLI help text. Users don't know which flags apply to which plugin without trial and error or reading source code. This will get worse as more plugins are added (#13 GitLab, #14 Azure DevOps).

Connection flags with plugin-specific applicability

Flag	Applies to	Notes
--token	All plugins	Shared — but future plugins may use different auth (e.g., OAuth)
--org	GitHub (optional), Copilot (required unless enterprise provided)	Different semantics per plugin
--enterprise	Copilot only	Ignored by GitHub
--endpoint	All plugins	But default differs per plugin
--proxy	All plugins	Shared

Scope flags with plugin-specific applicability

Flag	Applies to	Notes
--repos	GitHub only	Not applicable to Copilot
--repos-file	GitHub only	Not applicable to Copilot
--deployment-pattern	GitHub only	DORA config
--production-pattern	GitHub only	DORA config
--incident-label	GitHub only	DORA config
--enterprise	Copilot only	Not applicable to GitHub
--org	Both	But different semantics

Current help output (scope example)

$ gh devlake configure scope add --help

Flags:
      --connection-id int         Connection ID (auto-detected if omitted)
      --deployment-pattern string Regex to match deployment workflows (default "(?i)deploy")
      --enterprise string         Enterprise slug (enables enterprise-level metrics)
      --incident-label string     Issue label for incidents (default "incident")
      --org string                Organization slug
      --plugin string             Plugin to configure (github, gh-copilot)
      --production-pattern string Regex to match production environment (default "(?i)prod")
      --repos string              Comma-separated repos (owner/repo)
      --repos-file string         Path to file with repos (one per line)

All flags are mixed together with no indication of which apply to which plugin.

Dependencies

Blocked by:

• configure connection add: Extract connection creation into add subcommand #54 (connection add) — Long text moves to add subcommand created there
• configure scope add/list/delete: Add CRUD subcommands for scope management #55 (scope CRUD) — Long text moves to add subcommand created there

Blocks:

• Dynamic plugin-specific flag validation and contextual help #59 (dynamic flag validation) — Option A text will be superseded by auto-generated text in Dynamic plugin-specific flag validation and contextual help #59

Parallel with: #57 (ScopeFunc) — independent changes, no file overlap

Proposed solution (Option A: help text annotations)

Update the Long description text on configure connection add and configure scope add to clearly document which flags apply to which plugin. This is a pure documentation improvement — no behavioral changes.

Scope add — updated Long text

Adds repository scopes and scope-configs to existing DevLake connections.

Shared flags (all plugins):
  --plugin             Plugin to configure (required in flag mode)
  --connection-id      Connection ID (required in flag mode)
  --org                Organization slug

GitHub-specific flags:
  --repos              Comma-separated repos (owner/repo)
  --repos-file         Path to file with repos (one per line)
  --deployment-pattern Regex to match deployment workflows
  --production-pattern Regex to match production environment
  --incident-label     Issue label for incidents

GitHub Copilot-specific flags:
  --enterprise         Enterprise slug (enables enterprise-level metrics)

Example (GitHub):
  gh devlake configure scope add --plugin github --connection-id 1 --org my-org --repos org/repo1,org/repo2

Example (Copilot):
  gh devlake configure scope add --plugin gh-copilot --connection-id 2 --org my-org --enterprise my-ent

Connection add — updated Long text

Creates a single DevLake plugin connection.

Shared flags (all plugins):
  --plugin             Plugin to configure
  --token              Personal access token
  --name               Connection display name
  --endpoint           API endpoint override
  --proxy              HTTP proxy URL

GitHub Copilot-specific flags:
  --enterprise         Enterprise slug
  --org                Organization slug (required unless enterprise provided)

Token resolution order:
  --token flag → .devlake.env → environment variable → masked prompt

Implementation

1. Update Long text in configure connection add (or current configureConnectionsCmd until configure connection add: Extract connection creation into add subcommand #54 ships)
2. Update Long text in configure scope add (or current scope command until configure scope add/list/delete: Add CRUD subcommands for scope management #55 ships)
3. Add per-plugin examples in the Long text to show typ...

• Fixes Document plugin-specific flag applicability in help text #58

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR improves the CLI help text for gh devlake configure connection add and gh devlake configure scope add by grouping flags into shared vs plugin-specific sections, so users can tell which flags apply to GitHub vs GitHub Copilot without reading source.

Changes:

• Restructures configure connection add Long help into shared vs Copilot-specific flags + examples.
• Restructures configure scope add Long help into shared vs GitHub vs Copilot flags + examples.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
cmd/configure_connection_add.go	Updates Long help text to group flags by applicability and add per-plugin examples.
cmd/configure_scope_add.go	Updates Long help text to group flags by applicability and add per-plugin examples.

Comments suppressed due to low confidence (3)

cmd/configure_scope_add.go:27

• The help text says --connection-id is “required in flag mode”, but the flag definition and implementation both treat it as optional (auto-detected if omitted via resolveConnectionID, and it can prompt if multiple exist). Suggest rewording this line to reflect that --connection-id is optional/auto-detected, otherwise users may think they must always provide it.

Shared flags (all plugins):
  --plugin             Plugin to configure (required in flag mode)
  --connection-id      Connection ID (required in flag mode)
  --org                Organization slug

cmd/configure_connection_add.go:46

• The help text labels --org as “GitHub Copilot-specific”, but the flag is registered on this command for all plugins and is used even when the selected plugin doesn’t require it (e.g., it’s prompted/accepted and stored in state for downstream scope commands). Consider moving --org into the shared section (with a note about plugin-specific semantics) to avoid misleading GitHub users (your GitHub example also uses --org).

This issue also appears on line 45 of the same file.

GitHub Copilot-specific flags:
  --enterprise   Enterprise slug
  --org          Organization slug (required unless enterprise provided)

cmd/configure_connection_add.go:55

• This help text states --org is “required unless enterprise provided” for Copilot, but runAddConnection doesn’t currently enforce “org OR enterprise” for gh-copilot (it only enforces def.NeedsOrg, and gh-copilot uses NeedsOrgOrEnt). Either update the help text to match current behavior, or add validation/prompting so at least one of --org / --enterprise is required for Copilot connections.

  --enterprise   Enterprise slug
  --org          Organization slug (required unless enterprise provided)

Token resolution order:
  --token flag → .devlake.env → environment variable → masked prompt

Example (GitHub):
  gh devlake configure connection add --plugin github --token ghp_xxx --org my-org

Example (Copilot):
  gh devlake configure connection add --plugin gh-copilot --token ghp_xxx --org my-org --enterprise my-ent`,