docs(agents): adopt AGENTS.md as canonical AI brief; restructure into TOC + sub-files

.github/copilot-instructions.md

@@ -0,0 +1,16 @@
+# Copilot instructions — Fallout
+
+This repository uses **[AGENTS.md](https://github.com/ChrisonSimtian/Fallout/blob/main/AGENTS.md)** at the repo root as the canonical brief for AI coding tools. Read it for the full guidance — project layout, semver policy, PR-creation flow, conventions, what-not-to-do list, and useful pointers.
+
+The most important rules in short:
+
+- **Central package versions only** — add to `Directory.Packages.props`, never `Version=` inline on a `PackageReference`.
+- **Tests live next to code**: every `src/Foo` has a `tests/Foo.Tests` sibling. Mirror namespaces.
+- **License header on every source file** — copy from a neighbour when adding new ones.
+- **Semver discipline**: any breaking change (commit `!` suffix or `BREAKING CHANGE:` footer) bumps `version.json` major in the same PR, adds the `breaking-change` label, opens the PR body with a `⚠️ Breaking change` callout, and adds a `CHANGELOG.md` entry under `[Unreleased] — <next-major>`.
+- **Every PR gets a `target/vN` label** at creation time (default `target/v<current-major>` from `version.json`; use `target/v<next-major>` if the PR is breaking).
+- **Stay on xUnit + FluentAssertions + Verify.** Don't introduce new test frameworks.
+- **No `.editorconfig` or `*.DotSettings`** — they were removed during the takeover and stay removed.
+- **Tool wrappers** live as `.json` under `src/Fallout.Common/Tools/<Tool>/<Tool>.json`; the `.cs` next to them is generated by `./build.ps1 GenerateTools` and must not be committed.
+
+When unsure, defer to AGENTS.md.

AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md
+
+Guidance for AI coding tools (Claude Code, GitHub Copilot, Cursor, Aider, Codex, etc.) working in this repo.
+
+This is the **canonical brief**. Tool-specific instruction files (`CLAUDE.md`, `.github/copilot-instructions.md`) point here.
+
+## What this project is
+
+**Fallout** — a build automation system for C#/.NET, hard-fork successor to [NUKE](https://github.com/nuke-build/nuke). 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 NUKE by [matkoch](https://github.com/matkoch); under new maintenance as of 2026 and being renamed to Fallout. The codebase is mature, large, and has long-standing conventions — prefer matching existing patterns over introducing new ones.
+
+**Rebrand status:** the structural rename has landed — namespaces (`Fallout.*`), package IDs, project filenames, and the global tool name (`dotnet fallout`) are all in place. Legacy `Nuke.*` lives on only as the consumer transition shims under `src/Shims/`. See [docs/rebrand-plan.md](docs/rebrand-plan.md) for the locked namespace mapping.
+
+**Active major: v11 ([milestone #6](https://github.com/ChrisonSimtian/Fallout/milestone/6))** — rebrand completion + plugin-architecture internal foundation. **No public plugin SDK in v11** — that's v12 ([milestone #7](https://github.com/ChrisonSimtian/Fallout/milestone/7)). v11 internal middleware/listener interfaces stay `internal`; do not expose via `InternalsVisibleTo` to non-test assemblies. See [docs/roadmap.md](docs/roadmap.md) and the five open RFCs ([#97](https://github.com/ChrisonSimtian/Fallout/issues/97)–[#101](https://github.com/ChrisonSimtian/Fallout/issues/101)) driving v12 design.
+
+## 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 `fallout.slnx` (new XML solution format, not `.sln`).
+
+## Common commands
+
+```powershell
+./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 fallout.slnx
+dotnet test tests/Fallout.Common.Tests/Fallout.Common.Tests.csproj
+```
+
+Do not commit code generated by `GenerateTools` — generated code is regenerated manually once per release.
+
+## Critical rules (read this every session)
+
+1. **At PR-creation time, follow the [PR-creation flow](docs/agents/release-and-versioning.md#pr-creation-flow) in `docs/agents/release-and-versioning.md`.** Every PR gets a `target/vN` label; breaking changes additionally get a `breaking-change` label, a `⚠️ Breaking change` callout, a `version.json` major bump in the same PR, and a `CHANGELOG.md` entry. This is non-negotiable — review will block.
+2. **Central package versions only** — add to `Directory.Packages.props`, never `Version=` inline.
+3. **Tests next to code** — every `src/Foo` has a `tests/Foo.Tests` sibling. Mirror namespaces.
+4. **License header on every source file** — copy from a neighbour.
+5. **Stay on xUnit + FluentAssertions + Verify.** Don't introduce new test frameworks.
+6. **No `.editorconfig` or `*.DotSettings`** — they were removed during the takeover. Don't reintroduce without a maintainer-level decision.
+
+Full conventions + what-not-to-do list: [docs/agents/conventions.md](docs/agents/conventions.md).
+
+## Where to look next
+
+- **[docs/agents/repository-layout.md](docs/agents/repository-layout.md)** — full directory structure, project groupings, transition-shim strategy
+- **[docs/agents/release-and-versioning.md](docs/agents/release-and-versioning.md)** — branching, semver policy, PR-creation flow, release pipeline, NuGet gotchas
+- **[docs/agents/conventions.md](docs/agents/conventions.md)** — conventions, what-not-to-do list, tool-wrapper recipe
+- **[docs/architecture.md](docs/architecture.md)** — high-level architecture overview
+- **[docs/rebrand-plan.md](docs/rebrand-plan.md)** — namespace mapping + bridge strategy
+- **[docs/roadmap.md](docs/roadmap.md)** — v11/v12/v13 milestones and RFCs
+- **[docs/dependencies.md](docs/dependencies.md)** — third-party dependencies (update when adding meaningful libraries)
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — contributor-facing flow (branching, PR review, merging convention)
+
+## Useful pointers
+
+- The `build/Build.*.cs` files are the canonical example of how to consume the framework — read these when reasoning about user-facing APIs.
+- `src/Fallout.Common/Tools/<Tool>/<Tool>.json` files are the source of truth for tool wrappers; the `.cs` next to them is generated.
+- Source generators (`src/Fallout.SourceGenerators`) produce per-target code at compile time — if a symbol seems missing, check whether it's generated.
+- The Verify snapshots (`*.verified.txt`, `*.verified.cs`) under `tests/` are the contract for generator output; review carefully when they change.