Refresh developer documentation and add agent guidance

.vscode/launch.json

@@ -5,26 +5,35 @@
    "version": "0.2.0",
    "configurations": [
         {
-            "name": "Git Credential Manager (get)",
+            "name": "gcm get",
             "type": "coreclr",
             "request": "launch",
             "preLaunchTask": "build",
-            // If you have changed target frameworks, make sure to update the program path.
-            "program": "${workspaceFolder}/out/shared/Git-Credential-Manager/bin/Debug/net10.0/git-credential-manager.dll",
+            "program": "${workspaceFolder}/out/bin/git-credential-manager/debug/git-credential-manager.dll",
             "args": ["get"],
-            "cwd": "${workspaceFolder}/out/shared/Git-Credential-Manager",
+            "cwd": "${workspaceFolder}",
             "console": "integratedTerminal",
             "stopAtEntry": false,
         },
         {
-            "name": "Git Credential Manager (store)",
+            "name": "gcm store",
             "type": "coreclr",
             "request": "launch",
             "preLaunchTask": "build",
-            // If you have changed target frameworks, make sure to update the program path.
-            "program": "${workspaceFolder}/out/shared/Git-Credential-Manager/bin/Debug/net10.0/git-credential-manager.dll",
+            "program": "${workspaceFolder}/out/bin/git-credential-manager/debug/git-credential-manager.dll",
             "args": ["store"],
-            "cwd": "${workspaceFolder}/out/shared/Git-Credential-Manager",
+            "cwd": "${workspaceFolder}",
+            "console": "integratedTerminal",
+            "stopAtEntry": false,
+        },
+        {
+            "name": "gcm erase",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build",
+            "program": "${workspaceFolder}/out/bin/git-credential-manager/debug/git-credential-manager.dll",
+            "args": ["erase"],
+            "cwd": "${workspaceFolder}",
             "console": "integratedTerminal",
             "stopAtEntry": false,
         },

.vscode/tasks.json

@@ -11,21 +11,21 @@
             },
             "args": [
                 "build",
-                "${workspaceFolder}/Git-Credential-Manager.sln",
+                "${workspaceFolder}/git-credential-manager.slnx",
             ],
             "problemMatcher": "$msCompile"
         },
         {
             "label": "test",
             "command": "dotnet",
-            "type": "shell",
+            "type": "process",
             "group":{
                 "kind": "test",
                 "isDefault": true
             },
             "args": [
                 "test",
-                "${workspaceFolder}/Git-Credential-Manager.sln"
+                "${workspaceFolder}/git-credential-manager.slnx"
             ],
             "presentation": {
                 "reveal": "always",
@@ -35,13 +35,13 @@
         {
             "label": "test with coverage",
             "command": "dotnet",
-            "type": "shell",
+            "type": "process",
             "group": "test",
             "args": [
                 "test",
-                "${workspaceFolder}/Git-Credential-Manager.sln",
+                "${workspaceFolder}/git-credential-manager.slnx",
                 "--collect",
-                "'XPlat Code Coverage'",
+                "XPlat Code Coverage",
                 "--settings",
                 "${workspaceFolder}/.code-coverage/coverlet.settings.xml"
             ],
@@ -53,10 +53,13 @@
         {
             "label": "report coverage - nix",
             "command": "dotnet",
-            "type": "shell",
+            "type": "process",
             "group": "test",
             "args": [
-                "~/.nuget/packages/reportgenerator/*/*/net10.0/ReportGenerator.dll",
+                "exec",
+                "--roll-forward",
+                "Major",
+                "${env:HOME}/.nuget/packages/reportgenerator/5.3.10/tools/net8.0/ReportGenerator.dll",
                 "-reports:${workspaceFolder}/**/TestResults/**/coverage.cobertura.xml",
                 "-targetdir:${workspaceFolder}/out/code-coverage"
             ],
@@ -68,10 +71,13 @@
         {
             "label": "report coverage - win",
             "command": "dotnet",
-            "type": "shell",
+            "type": "process",
             "group": "test",
             "args": [
-                "${env:USERROFILE}/.nuget/packages/reportgenerator/*/*/net10.0/ReportGenerator.dll",
+                "exec",
+                "--roll-forward",
+                "Major",
+                "${env:USERPROFILE}/.nuget/packages/reportgenerator/5.3.10/tools/net8.0/ReportGenerator.dll",
                 "-reports:${workspaceFolder}/**/TestResults/**/coverage.cobertura.xml",
                 "-targetdir:${workspaceFolder}/out/code-coverage"
             ],

AGENTS.md

@@ -0,0 +1,88 @@
+# Agent instructions
+
+Follow [CONTRIBUTING.md](CONTRIBUTING.md) when contributing to Git Credential
+Manager. Keep changes focused, match existing code style, and include tests and
+documentation for behaviour changes.
+
+## Ethos
+
+Git Credential Manager is an open source project that values collaboration,
+code quality, and adherence to best practices, whilst still being pragmatic
+about trade-offs and exceptions to the rules. Don't be afraid to make pragmatic
+decisions when necessary, but have a good and well argued rationale.
+
+We try to not favor any particular platform, technology, or approach without
+good reason, and aim to avoid hacks and workarounds where possible.
+
+Be kind, be honest, and respectful.
+
+## Project guidance
+
+Read the guidance relevant to your change:
+
+- [Development and debugging](docs/development.md): setup, build commands,
+  debugging, testing, coverage, and documentation checks.
+- [Architecture](docs/architecture.md): project boundaries, command execution,
+  platform abstractions, credential storage, and error handling.
+- [Host provider specification](docs/hostprovider.md): provider selection,
+  credential operations, protocol responses, and authentication interaction.
+- [Main thread dispatcher](docs/dispatcher.md): UI and broker threading,
+  lifecycle rules, and testing seams.
+- [Documentation index](docs/README.md): user-facing configuration and
+  provider-specific guidance.
+- [SECURITY.md](SECURITY.md): private reporting of security vulnerabilities.
+
+## Making changes
+
+- Inspect the affected implementation and tests before editing. Reuse existing
+  helpers and patterns rather than introducing parallel implementations.
+- Preserve Windows, macOS, and Linux behaviour. Use `ICommandContext` services
+  and existing platform abstractions; reuse mocks from `src/TestInfrastructure`
+  instead of accessing live services in unit tests.
+- Keep Git's credential stdin/stdout separate from user interaction.
+  Use `ICommandContext.Console` for messages and prompts, and secret-aware
+  tracing for sensitive values. Respect interaction and prompt settings.
+- Follow the dispatcher rules for main-thread work. Do not eagerly start the
+  UI framework or block its main loop on asynchronous work.
+- Keep dependencies, reflection, and serialization compatible with Native AOT
+  and trimming. Use the existing source-generated JSON contexts and central
+  package versions in `Directory.Packages.props`.
+- Update user documentation when changing configuration, environment variables,
+  commands, or authentication behaviour. Update developer documentation when
+  changing architecture, APIs, build tooling, or test workflows.
+- Do not hand-edit generated artifacts under `out/`. Do not use real secrets
+  in source, tests, examples, or ordinary trace messages.
+- Avoid making drive-by changes to other pieces of code; focus on the area
+  relevant to your change.
+- If making changes directly outside the scope of the request would make things
+  clearer/cleaning and more maintainable, make the change or refactor as a
+  standalone change in a commit first, then a second commit to introduce your
+  main change.
+- Stop and ask when requirements or repository rules are unclear.
+
+## Validation
+
+For every code change, build and run the full solution test suite:
+
+```shell
+dotnet build git-credential-manager.slnx
+dotnet test git-credential-manager.slnx
+```
+
+Targeted tests can help during development but do not replace the full run.
+Platform-specific tests skip on other operating systems; CI provides the
+cross-platform matrix.
+
+Exercise changed UI flows through the main executable. Validate publishing or
+packaging changes with the applicable distribution build on its host OS; an
+ordinary build does not validate Native AOT publishing. See the development
+guide for commands.
+
+For documentation-only changes, follow best practices for Markdown and use
+common linters to check for spelling mistakes and layout issues.
+
+## Commits
+
+Use logical commits and follow the
+[commit guidance](CONTRIBUTING.md#commits) for area-prefixed imperative subjects,
+explanatory bodies, sign-offs, and AI-assistance trailers.

CONTRIBUTING.md

@@ -19,16 +19,15 @@ you agree to abide by its terms.
 ## Submitting a pull request
 
 1. [Fork][fork] and clone the repository
-1. Configure and install the dependencies: `dotnet restore`
-1. Make sure the tests pass on your machine: `dotnet test`
+1. Follow [development setup][development] and restore dependencies:
+   `dotnet restore`
+1. Make sure the full solution test suite passes on your machine:
+   `dotnet test git-credential-manager.slnx`
 1. Create a new branch: `git switch -c my-branch-name`
-1. Make your change, add tests, and make sure the tests still pass
-1. For UI updates, test your changes by executing a `dotnet run` in applicable
-   UI-related project directories:
-    - `Atlassian.Bitbucket.UI.Avalonia`
-    - `GitHub.UI.Avalonia`
-    - `Atlassian.Bitbucket.UI.Windows`
-    - `GitHub.UI.Windows`
+1. Make your change, add tests, and make sure all tests pass
+1. For UI updates, exercise the relevant flow through the main executable:
+   `dotnet run --project src/git-credential-manager -- get`.
+   See [debugging instructions][debugging] for stdin and startup arguments.
 1. Organize your changes into one or more [logical, descriptive commits][commits].
 1. Push to your fork and [submit a pull request][pr]
 1. Pat your self on the back and wait for your pull request to be reviewed and
@@ -40,22 +39,56 @@ request being accepted:
 - Match existing code style.
 - Write tests.
 - Keep your change as focused as possible. If there are multiple changes you
-   would like to make that are not dependent upon each other, consider
-   submitting them as separate pull requests.
+  would like to make that are not dependent upon each other, consider
+  submitting them as separate pull requests.
+
+Run the full solution test suite for every code change. Targeted tests are useful
+while iterating, but do not replace the full run. Platform-specific tests skip
+on other operating systems; CI covers the Windows, macOS, and Linux matrix.
+See [testing][testing] for test infrastructure and coverage instructions.
+
+## Commits
+
+Make each commit one logical change. Include the tests and documentation for a
+behaviour change in the same commit; keep unrelated refactors and formatting
+separate.
+
+Use `area: short imperative summary` for the subject, with a concrete area,
+lowercase text after the colon, no trailing period, and at most 72 characters.
+Explain why the change is needed in the body, wrapping prose at about 72
+characters.
+
+Credit meaningful AI assistance with `Assisted-by: <human-readable model name>`.
+We don't require the `Signed-off-by` trailer (`git commit -s`) on commits, but
+it is recommended.
+
+Please watch [this very helpful video][commits-video] that outlines the commit
+message conventions and best practices for open source projects.
+
+## Development resources
+
+The [developer documentation index][developer-docs] links to build, debugging,
+architecture, threading, and provider guidance.
 
 ## Resources
 
 - [How to Contribute to Open Source][how-to-contribute]
 - [Using Pull Requests][prs]
 - [GitHub Help][github-help]
+- [Writing Commits For You, Your Friends, And Your Future Self][commits-video]
 
 [code-of-conduct]: CODE_OF_CONDUCT.md
-[commits]: https://www.youtube.com/watch?v=4qLtKx9S9a8
+[commits]: #commits
+[commits-video]: https://www.youtube.com/watch?v=4qLtKx9S9a8
 [contribute-under-repo-license]: https://help.github.com/articles/github-terms-of-service/#6-contributions-under-repository-license
 [fork]: https://github.com/git-ecosystem/git-credential-manager/fork
 [github-help]: https://help.github.com
 [how-to-contribute]: https://opensource.guide/how-to-contribute/
 [issue]: https://github.com/git-ecosystem/git-credential-manager/issues/new/choose
 [license]: LICENSE
+[debugging]: docs/development.md#debugging
+[developer-docs]: docs/README.md#developer-documentation
+[development]: docs/development.md
 [pr]: https://github.com/git-ecosystem/git-credential-manager/compare
 [prs]: https://help.github.com/articles/about-pull-requests/
+[testing]: docs/development.md#testing

docs/README.md

@@ -1,6 +1,8 @@
-# User documentation
+# Documentation
 
-The following are links to GCM user support documentation:
+## User documentation
+
+The following are links to user support documentation:
 
 - [Frequently asked questions][gcm-faq]
 - [Command-line usage][gcm-usage]
@@ -9,17 +11,34 @@ The following are links to GCM user support documentation:
 - [Enterprise configuration][gcm-enterprise-config]
 - [Network and HTTP configuration][gcm-net-config]
 - [Credential stores][gcm-credstores]
-- [Host provider specification][gcm-host-provider]
 - [Azure Repos OAuth tokens][gcm-azure-tokens]
 - [Azure Managed Identities and Service Principals][gcm-misp]
 - [Azure Workload Identity Federation Workflows][gcm-azure-wif]
 - [GitLab support][gcm-gitlab]
+- [Bitbucket authentication][gcm-bitbucket]
 - [Generic OAuth support][gcm-oauth]
 - [NTLM and Kerberos authentication][gcm-ntlm-kerberos]
 
+## Developer documentation
+
+These are links helpful for developers of Git Credential Manager:
+
+- [Contributing][gcm-contributing]
+- [Development, debugging, and testing][gcm-development]
+- [Architecture][gcm-architecture]
+- [Main thread dispatcher (UI thread)][gcm-dispatcher]
+- [Host provider specification][gcm-host-provider]
+- [Bitbucket development][gcm-bitbucket-dev]
+
+[gcm-architecture]: architecture.md
 [gcm-azure-tokens]: azrepos-users-and-tokens.md
+[gcm-bitbucket]: bitbucket-authentication.md
+[gcm-bitbucket-dev]: bitbucket-development.md
 [gcm-config]: configuration.md
+[gcm-contributing]: ../CONTRIBUTING.md
 [gcm-credstores]: credstores.md
+[gcm-development]: development.md
+[gcm-dispatcher]: dispatcher.md
 [gcm-enterprise-config]: enterprise-config.md
 [gcm-env]: environment.md
 [gcm-faq]: faq.md