Sync docs from main: add --username, BasicAuth docs to configure-connection.md and AGENTS.md auth field groups

Co-authored-by: ewega <26189114+ewega@users.noreply.github.com>

Author: Copilot

.github/copilot-instructions.md

@@ -80,6 +80,7 @@ When performing a code review on this repository:
 - Confirm imports follow stdlib → external → internal ordering
 - Flag any hardcoded plugin names outside `connectionRegistry`
 - Verify `doGet[T]`/`doPost[T]` generics are used instead of raw HTTP calls
+- Check that new plugin-specific flags are registered in `ConnectionFlags`/`ScopeFlags` on the `ConnectionDef` for dynamic validation
 - Check terminal output follows spacing rules from `terminal-output.instructions.md`
 - Verify new commands have test files alongside them
 - Ensure README command reference table is updated for new/renamed commands

AGENTS.md

@@ -60,6 +60,14 @@ gh devlake
 ### Plugin System
 Plugins are defined via `ConnectionDef` structs in `cmd/connection_types.go`. Each entry declares the plugin slug, endpoint, rate limits, prompt labels, PAT resolution keys, and scope handler. To add a new DevOps tool, add a `ConnectionDef` to `connectionRegistry` — token resolution, org prompts, and connection creation all derive from these fields automatically. See the `devlake-dev-integration` skill for full details.
 
+Key `ConnectionDef` field groups:
+- **Identity & endpoints**: `Plugin`, `DisplayName`, `Endpoint`, `Available`
+- **Org/enterprise**: `NeedsOrg`, `NeedsEnterprise`, `NeedsOrgOrEnt`, `OrgPrompt`, `EnterprisePrompt`
+- **Auth**: `AuthMethod` (default `"AccessToken"`; set `"BasicAuth"` for Jenkins/Bitbucket/Jira), `NeedsUsername`, `UsernamePrompt`, `UsernameEnvVars`, `UsernameEnvFileKeys`
+- **Token/PAT**: `TokenPrompt`, `EnvVarNames`, `EnvFileKeys`, `RequiredScopes`, `ScopeHint`
+- **Scope metadata**: `ScopeIDField` (JSON field name for scope IDs, e.g. `"githubId"`, `"id"`), `HasRepoScopes` (true when scopes carry a FullName tracked as repos), `ScopeFunc`
+- **Dynamic flag validation**: `ConnectionFlags`, `ScopeFlags` — slices of `FlagDef` that declare which plugin-specific flags apply. At runtime, `warnIrrelevantFlags()` warns when a user passes a flag that doesn't apply to the selected plugin, and `printContextualFlagHelp()` shows applicable flags in interactive mode.
+
 **One plugin per invocation.** Flag-based commands target a single `--plugin`. Interactive mode walks through plugins sequentially.
 
 ### Design Principles

docs/configure-connection.md

@@ -28,7 +28,8 @@ Aliases: `connections`
 | `--name` | `Plugin - org` | Connection display name |
 | `--endpoint` | `https://api.github.com/` | API endpoint (use for GitHub Enterprise Server) |
 | `--proxy` | | HTTP proxy URL |
-| `--token` | | GitHub PAT (highest priority source) |
+| `--token` | | GitHub PAT (highest priority source). For BasicAuth plugins (Jenkins, Bitbucket, Jira), this is the password. |
+| `--username` | | Username for BasicAuth plugins (Jenkins, Bitbucket, Jira). Not used by GitHub or Copilot. |
 | `--env-file` | `.devlake.env` | Path to env file containing PAT |
 | `--skip-cleanup` | `false` | Don't delete `.devlake.env` after setup |
 
@@ -50,6 +51,17 @@ For each plugin, the CLI resolves the PAT in this order (see [token-handling.md]
 3. Plugin-specific environment variable (same key names, from shell environment)
 4. Interactive masked prompt (terminal fallback)
 
+### Username Resolution (BasicAuth plugins)
+
+For plugins that use BasicAuth (e.g. Jenkins, Bitbucket, Jira), the `--username` flag is resolved in this order:
+
+1. `--username` flag
+2. `.devlake.env` file — checked for plugin-specific keys (e.g. `JENKINS_USERNAME`)
+3. Plugin-specific environment variable (from shell environment)
+4. Interactive prompt (terminal fallback)
+
+When `--username` is provided for a plugin that uses AccessToken auth (like GitHub or Copilot), the CLI prints a warning that the flag is not applicable.
+
 ### What It Does
 
 1. Auto-discovers DevLake instance (state file → localhost ports → `--url`)
@@ -81,6 +93,9 @@ gh devlake configure connection --plugin github --org my-org \
 # With proxy
 gh devlake configure connection --plugin github --org my-org --proxy http://proxy:8080
 
+# BasicAuth plugin (e.g. Jenkins)
+gh devlake configure connection --plugin jenkins --username admin --token mypassword
+
 # Interactive (no --plugin — prompts for everything)
 gh devlake configure connection
 ```