diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 000000000..77834a53a
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "statusLine": {
+    "type": "command",
+    "command": "pwsh -NoProfile -Command '$input | & (Get-ChildItem $HOME/.claude/plugins/cache/myfoodbag/mfb-statusline/*/statusline-command.ps1 | Select-Object -Last 1)'"
+  },
+  "enabledPlugins": {
+    "mfb-statusline@myfoodbag": true
+  },
+  "permissions": {
+    "allow": [
+      "Bash(dotnet build:*)",
+      "Bash(dotnet test:*)",
+      "Bash(dotnet restore:*)",
+      "Bash(dotnet pack:*)",
+      "Bash(dotnet --info)",
+      "Bash(dotnet --version)",
+      "Bash(dotnet list:*)",
+      "Bash(./build.ps1:*)",
+      "Bash(./build.sh:*)",
+      "Bash(./build.cmd:*)",
+      "Bash(pwsh ./build.ps1:*)",
+      "Bash(git status)",
+      "Bash(git status:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git show:*)",
+      "Bash(git branch:*)",
+      "Bash(git remote -v)",
+      "Bash(git rev-parse:*)",
+      "Bash(git ls-files:*)",
+      "Bash(git config --get:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(gh issue list:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh run list:*)",
+      "Bash(gh run view:*)",
+      "Bash(gh workflow list:*)",
+      "Bash(gh api:*)"
+    ],
+    "deny": [
+      "Bash(git push --force:*)",
+      "Bash(git push -f:*)",
+      "Bash(git reset --hard:*)",
+      "Bash(git clean -f:*)",
+      "Bash(rm -rf:*)"
+    ]
+  }
+}
diff --git a/.gitignore b/.gitignore
index e070853bb..99b948e9a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -56,3 +56,7 @@ _dotTrace*
 
 # Tests
 *.received.txt
+
+# Claude Code — local-only files (shared settings.json IS committed)
+.claude/settings.local.json
+.claude/.credentials*
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..435bdff01
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,94 @@
+# CLAUDE.md
+
+Guidance for Claude Code (and other AI assistants) when working in this repo.
+
+## What this project is
+
+[NUKE](https://nuke.build) — a build automation system for C#/.NET. The build is itself a C# console app (`build/_build.csproj`), so any change to the framework can be dogfooded by running `./build.ps1` (Windows) or `./build.sh`.
+
+Originally a single-maintainer project ([matkoch](https://github.com/matkoch)); now under new maintenance. The codebase is mature, large, and has long-standing conventions — prefer matching existing patterns over introducing new ones.
+
+## Stack
+
+- .NET SDK pinned in `global.json` (currently `10.0.100`, `rollForward: latestMinor`).
+- Central package versions in `Directory.Packages.props` — never add a `Version=` to an individual `PackageReference`.
+- xUnit + FluentAssertions + Verify.Xunit for tests.
+- Solution file is `nuke-common.slnx` (new XML solution format, not `.sln`).
+
+## Solution layout
+
+Source projects live under `source/`. The high-level grouping:
+
+| Area | Projects |
+|---|---|
+| Core framework | `Nuke.Common`, `Nuke.Build`, `Nuke.Build.Shared`, `Nuke.Components`, `Nuke.Tooling` |
+| Code generation | `Nuke.SourceGenerators`, `Nuke.Tooling.Generator` |
+| Models | `Nuke.ProjectModel`, `Nuke.SolutionModel` |
+| Tooling | `Nuke.GlobalTool`, `Nuke.MSBuildTasks` |
+| Utilities | `Nuke.Utilities`, `Nuke.Utilities.IO.Compression`, `Nuke.Utilities.IO.Globbing`, `Nuke.Utilities.Net`, `Nuke.Utilities.Text.Json`, `Nuke.Utilities.Text.Yaml` |
+| Tests | Each project has a sibling `*.Tests` project |
+
+The build itself lives under `build/` (the `Build.*.cs` partial files split targets by concern: `Build.CI.GitHubActions.cs`, `Build.Licenses.cs`, etc.).
+
+Tool wrappers (the `.json` schemas Claude is most likely asked to extend) live under `source/Nuke.Common/Tools/<Tool>/<Tool>.json`.
+
+## Common commands
+
+```powershell
+# Build the build
+./build.ps1                          # default target = Pack
+./build.ps1 Compile
+./build.ps1 Test
+./build.ps1 GenerateTools            # regenerate tool wrappers from JSON
+./build.ps1 --help                   # list all targets and parameters
+
+# Or via dotnet directly when iterating on a single project
+dotnet build nuke-common.slnx
+dotnet test source/Nuke.Common.Tests/Nuke.Common.Tests.csproj
+```
+
+Do not commit code generated by `GenerateTools` — per `CONTRIBUTING.md`, generated code is regenerated manually once per release.
+
+## Branching & releases
+
+GitFlow:
+- `develop` — integration branch, base for all PRs
+- `release/*` — release stabilization
+- `master` — published releases (publishes to public NuGet)
+- `hotfix/*` — patches against `master`
+
+Alpha packages flow to the Feedz feed (`https://f.feedz.io/nuke/alpha/nuget`) from `develop` via the GitHub Actions `AlphaDeployment` workflow. Public NuGet publishes happen from `master`/`release/*` via AppVeyor.
+
+Versioning is driven by GitVersion (`GitVersion.yml`).
+
+## Conventions worth respecting
+
+- **Centralized package versions** — add new packages to `Directory.Packages.props`, never inline.
+- **Tool wrappers**: copy/paste from neighbours; cover full commands; use `<c>`, `<a>`, `<ul>`/`<ol>`, `<em>`, `<para/>` in `help`; don't write `secret: false` or `default: xxx`.
+- **Tests next to code**: every `Foo` project has a `Foo.Tests` project. Mirror the namespace.
+- **Coding style**: enforced via `.editorconfig` + ReSharper settings (`*.DotSettings`). Don't fight the formatter.
+- **Telemetry opt-out is set in test runs** (`NUKE_TELEMETRY_OPTOUT=true`). Keep it that way.
+- **License header**: every source file starts with the `// Copyright … Maintainers of NUKE.` block — copy from a neighbouring file when adding new ones.
+
+## What not to do
+
+- Don't add `secret`/`default` defaults to tool JSON files (see CONTRIBUTING.md).
+- Don't introduce a new test framework or assertion library — stay on xUnit + FluentAssertions + Verify.
+- Don't commit `output/`, `external/`, or any `bin/`/`obj/` directory.
+- Don't commit `nuke-global.sln` or other `nuke-global.*` files — they're generated by `GenerateGlobalSolution`.
+- Don't bypass `Directory.Packages.props` or `Directory.Build.targets`.
+- Don't rewrite Matt's prior conventions wholesale — discuss in an issue first.
+
+## When asked to add a tool wrapper
+
+1. Find the closest existing tool under `source/Nuke.Common/Tools/<Tool>/<Tool>.json`.
+2. Copy its shape; cover a full command with all arguments.
+3. Run `./build.ps1 GenerateTools` to verify it generates cleanly.
+4. Do **not** commit the generated `.cs` output.
+
+## Useful pointers for AI assistants
+
+- The `build/Build.*.cs` files are the canonical example of how to consume NUKE — read these when reasoning about user-facing APIs.
+- `Nuke.Common/Tools/<Tool>/<Tool>.json` files are the source of truth for tool wrappers; the `.cs` next to them is generated.
+- Source generators (`Nuke.SourceGenerators`) produce per-target code at compile time — if a symbol seems missing, check whether it's generated.
+- The Verify snapshots (`*.verified.txt`) under test projects are the contract for generator output; review carefully when they change.
