Chore/deps and docs

AGENTS.md

@@ -0,0 +1,129 @@
+# Agent Instructions
+
+Guidance for AI agents working in **Atom**, an opinionated, type-safe build automation framework
+for .NET. Keep changes focused; `README.md` and `docs/` describe consumer-facing usage.
+
+## Repository map
+
+| Area | Purpose |
+|------|---------|
+| `src/Invex.Atom.Build` | Core build definitions, targets, parameters, secrets, artifacts, hosting, and lifecycle hooks |
+| `src/Invex.Atom.Workflows` | Workflow definitions, triggers, and options |
+| `src/Invex.Atom.Module.*` | Built-in modules for .NET, GitHub Actions, Azure DevOps, GitVersion, and Azure services |
+| `src/Invex.Atom.Build.Analyzers` / `SourceGenerators` | Roslyn analyzers and generated build entry points |
+| `src/Invex.Atom.Tool` | The `Invex.Atom.Tool` global tool |
+| `tests/` | NUnit tests, snapshots, and the published `Invex.Atom.TestUtils` helpers |
+| `_atom/` | This repository's own Atom build definition |
+| `samples/` | Small consumer examples |
+| `docs/`, `api/` | DocFX documentation source and generated API content |
+
+The solution is `Invex.Atom.slnx`. The repository currently requires the .NET 10 SDK; libraries
+and tests target `net8.0`, `net9.0`, and `net10.0`, while the build project targets `net10.0`.
+There is no `global.json`, so use the installed .NET 10 SDK selected by the environment.
+
+## Build, test, and cleanup
+
+Run commands from the repository root:
+
+```shell
+dotnet build Invex.Atom.slnx
+dotnet test Invex.Atom.slnx
+```
+
+The repository's own build targets can also be used:
+
+```shell
+atom PackProjects
+atom TestProjects
+atom BuildDocs
+atom ServeDocs
+```
+
+`atom` is the `Invex.Atom.Tool` global tool. The equivalent form is
+`dotnet run --project _atom -- <target>`.
+
+After making C# changes, run ReSharper cleanup over the solution:
+
+```powershell
+$sdk = dotnet --version
+jb cleanupcode Invex.Atom.slnx --include="**.cs" --toolset-path="C:\Program Files\dotnet\sdk\$sdk\MSBuild.dll"
+```
+
+If `jb` is unavailable, install it with
+`dotnet tool install --global JetBrains.ReSharper.GlobalTools`. The explicit `--toolset-path`
+ensures cleanup uses the selected .NET SDK's MSBuild rather than an incompatible Visual Studio
+BuildTools installation. Cleanup honors `.editorconfig` and `Invex.Atom.sln.DotSettings`.
+
+## Build and language conventions
+
+- `ImplicitUsings`, nullable reference types, documentation generation, and
+  `TreatWarningsAsErrors` are enabled in `Directory.Build.props`.
+- Global usings belong in each project's `_usings.cs`, not in individual source files.
+- Add XML documentation to every new public type and member in `src/`, matching the existing
+  style and accurately describing nullability, return values, retries, and caching.
+- Add `[PublicAPI]` to new public types where the public API analyzer applies.
+- Some generated-code projects and tests explicitly suppress `CS1591`; do not broaden the
+  repository-wide warning suppressions to hide missing documentation.
+- Keep cross-member implementation helpers `internal`; expose only the intended consumer API.
+- The IDE can report false errors for `[GeneratedRegex]` partial members; `dotnet build` is the
+  source of truth for those members.
+
+## Atom architecture
+
+- A build is an `internal interface IBuild` annotated with `[BuildDefinition]` and
+  `[GenerateEntryPoint]`, extending `IBuildDefinition` or
+  `IWorkflowBuildDefinition` plus module interfaces.
+- Targets use the fluent API for descriptions, dependencies, parameters, artifacts, variables,
+  and execution.
+- Parameters and secrets use `[ParamDefinition]` / `[SecretDefinition]` and
+  `GetParam(() => Property)`. Secrets are masked in logs.
+- Providers are the extension points for secrets, artifacts, variables, build identity/version,
+  timestamps, paths, and outcome reports. See `docs/developer-guide/`.
+- Workflow definitions describe triggers, targets, matrices, options, and GitHub Actions or
+  Azure DevOps output types.
+
+## Generated workflows
+
+The committed workflow files under `.github/workflows/`, `.github/dependabot.yml`, and
+`.devops/workflows/` are generated from `_atom/IBuild.cs`. When changing targets, workflow
+definitions, triggers, options, or parameters/secrets that affect them, run:
+
+```shell
+atom gen
+```
+
+Commit the generated files with the source change. Never hand-edit generated workflow files.
+
+## Versioning and commits
+
+Use Conventional Commits; `GitVersion.yml` maps prefixes as follows:
+
+| Prefix | Version bump |
+|--------|--------------|
+| `breaking:` / `major:` | Major |
+| `feat:` / `feature:` / `minor:` | Minor |
+| `fix:` / `patch:` | Patch |
+| `semver-none` / `semver-skip` | No bump |
+
+## Testing and Verify snapshots
+
+Tests use NUnit, Shouldly, FakeItEasy, and Verify (`Verify.NUnit`). Workflow and source-generator
+tests compare output with committed `*.verified.txt` files. A mismatch creates a corresponding
+`*.received.txt` file:
+
+1. Fix the implementation if the output is unintended.
+2. If the output is intentional, replace the matching `.verified.txt` with the received output,
+   remove `.received.txt`, and rerun `dotnet test`.
+3. Keep approved snapshot changes intentional because PR validation checks the snapshots for
+   breaking API changes.
+
+## Change checklist
+
+1. Follow existing patterns and make a precise, surgical change.
+2. Add public API documentation and `[PublicAPI]` where applicable.
+3. Build and test the solution.
+4. Run `jb cleanupcode` and include its relevant formatting changes.
+5. Update `README.md` or the relevant documentation for consumer-facing behavior.
+6. Run `atom gen` whenever generated workflows are affected.
+
+Do not commit secrets, generated planning notes, or unrelated formatting changes.

README.md

@@ -7,6 +7,17 @@
 Atom is an opinionated, type-safe build automation framework for .NET. It enables you to define your build logic in C#,
 debug it like standard code, and automatically generate CI/CD configuration files for GitHub Actions and Azure DevOps.
 
+## Requirements
+
+- .NET 10 SDK
+- A .NET project containing an Atom build definition (commonly `_atom/_atom.csproj`)
+
+Install the CLI once if you want to invoke builds from any directory:
+
+```shell
+dotnet tool install --global Invex.Atom.Tool
+```
+
 ## Why Atom?
 
 ### Zero Context Switching
@@ -35,15 +46,15 @@ Reduces boilerplate by automatically discovering targets and parameters.
 
 > [!NOTE]
 >
-> It is recommended to use the atom dotnet tool to invoke atom projects:
+> It is recommended to use the `atom` dotnet tool to invoke Atom projects:
 >
-> `dotnet tool install -g Invex.Atom.Tool`
+> `dotnet tool install --global Invex.Atom.Tool`
 >
-> ` atom ...`
+> `atom ...`
 >
 > However, the dotnet cli can also be used directly:
 >
-> `dotnet run -- ...`
+> `dotnet run --project _atom -- ...`
 
 1. Create a .NET 10 project
 

docfx-theme/public/main.css

@@ -0,0 +1,6 @@
+#logo {
+  width: 32px !important;
+  height: 32px !important;
+  object-fit: contain !important;
+  margin-right: 8px !important;
+}

docfx.json

@@ -34,6 +34,7 @@
       },
       {
         "files": [
+          "api/toc.yml",
           "api/**.yml",
           "api/index.md"
         ]
@@ -48,7 +49,8 @@
     "resource": [
       {
         "files": [
-          "images/**"
+          "images/**",
+          "LICENSE.txt"
         ]
       }
     ],
@@ -58,6 +60,7 @@
     "globalMetadata": {
       "_appTitle": "Atom",
       "_appName": "Atom",
+      "_appLogoPath": "images/icon.png",
       "_appFooter": "Atom — Build Automation for .NET",
       "_enableSearch": true,
       "_disableContribution": false,
@@ -71,10 +74,11 @@
       "default",
       "modern"
     ],
+    "theme": [
+      "docfx-theme"
+    ],
     "postProcessors": [],
     "keepFileLink": false,
     "disableGitFeatures": false
   }
 }
-
-

docs/built-in-targets/generate-workflow-files.md

@@ -31,8 +31,9 @@ atom Gen
 
 Your build must:
 
-1. Inherit from `WorkflowBuildDefinition` (or implement `IWorkflowBuildDefinition`).
-2. Override the `Workflows` property with at least one definition.
+1. Implement `IWorkflowBuildDefinition` (or derive from `WorkflowBuildDefinition`).
+2. Define `IWorkflowBuildDefinition.Workflows` with at least one definition. Interface builds
+   explicitly implement the property; partial classes override it.
 3. Inherit a platform module interface (`IGithubWorkflows`, `IDevopsWorkflows`, or both) so the corresponding
    workflow writer is registered.