Add xaflogic agents: context files any AI agent can use

The tool could describe an XAF application but had nowhere useful to put the
description. This adds the output that needs no infrastructure at all: AGENTS.md,
CLAUDE.md and .github/copilot-instructions.md, written next to the analyzed
solution. No account, no key, no server.

The output is tiered, and that is the design rather than an optimization.
AGENTS.md is prepended to every request an agent makes in the repository, so its
cost is paid on every question forever. Putting 70 KB of entity detail there
would crowd out the thing the user actually asked. So the index stays around
11 KB and the detail goes to .xaflogic/, which agents open only when a question
needs it.

The most valuable section is the smallest. Ground rules state which ORM this
application uses and which APIs therefore do not exist in it; that the
inventories are complete, so an entity that does not appear genuinely does not
exist rather than living in an unread file; and that some behavior lives in the
Model Editor and cannot be inferred from C# at all. Those paragraphs address the
specific ways agents are confidently wrong about unfamiliar XAF codebases.

Conventions are inferred from the codebase itself -- namespaces, folder layout,
base classes, whether associations are named, whether validation is attributes or
code -- so suggested code matches the surrounding style instead of a tutorial.
Criteria expressions are quoted verbatim from the source, because XAF's criteria
language is neither SQL nor C# and examples teach it better than description.

Generated text is written between markers. A CLAUDE.md someone has been keeping
notes in survives regeneration, and repeated runs are byte-identical: the first
implementation grew the file by one blank line per run, which in a repository
becomes a spurious diff every time and trains people to stop reading them.

IDocumentationSink makes the destination a choice. PeopleWorks Copilot is now one
implementation behind that interface, with its upload logic unchanged.

Fixes an extraction bug found by reading the generated output against a real
19-entity application: ModuleAnalyzer accepted any invocation whose expression
contained "Add", so AdditionalExportedTypes.Add(typeof(Cliente)) was reported as
a required XAF module. The list of twelve genuine modules had nine business
entities and six framework base types mixed into it. Being wrong under an
authoritative heading is worse than being absent, and this would have shipped
into every generated AGENTS.md.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: peopleworks

CHANGELOG.md

@@ -7,12 +7,39 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- **`xaflogic agents`** — writes `AGENTS.md`, `CLAUDE.md` and `.github/copilot-instructions.md`
+  so any AI coding agent understands the analyzed application. No account, key or server.
+  - Output is **tiered**: a compact index (~11 KB) that agents load on every request, and detail
+    files in `.xaflogic/` (~70 KB) they open only when a question needs them. An `AGENTS.md` is
+    prepended to every conversation, so putting the full documentation there would consume the
+    context the user's actual question needs.
+  - The index leads with **ground rules**: which ORM this application uses and which APIs
+    therefore do not exist in it, that the inventories are complete so an absent entity is
+    genuinely absent, and that some behavior lives in the Model Editor rather than in C#.
+  - **Conventions are inferred from the codebase** — namespaces, folder layout, base classes, how
+    associations and validation are written — so generated code matches the surrounding style
+    instead of a generic tutorial.
+  - Includes **real criteria expressions** taken from the source. XAF's criteria language is
+    neither SQL nor C#, and worked examples teach the dialect better than a description of it.
+  - Generated text is written between markers: anything you wrote by hand is preserved, and
+    regenerating produces byte-identical output when nothing has changed.
+- `IDocumentationSink`, making a publishing target something the caller chooses. PeopleWorks
+  Copilot is now one implementation of it rather than the destination the tool is built around.
+
+### Fixed
+
+- `ModuleAnalyzer` reported business entities as required XAF modules. It accepted any invocation
+  whose expression contained `Add`, so `AdditionalExportedTypes.Add(typeof(Cliente))` was read as
+  a module dependency. On a real project this listed nine entities and six framework base types
+  among twelve genuine modules. It now matches the target collection, and
+  `AdditionalExportedTypes` feeds the registered-types list where it belongs.
+
 ### Planned
 
-- `AGENTS.md` / `CLAUDE.md` / `copilot-instructions.md` output — no infrastructure required
 - MCP server, so any agent can query an XAF codebase live
 - Agent skill installable from this repository, alongside DevExpress's own `dx-xaf` plugin
-- `IDocumentationSink` abstraction, making PeopleWorks Copilot one target among several
 - AI provider abstraction (OpenAI, Azure OpenAI, Anthropic, Ollama) for `--enrich`
 - xUnit test suite over a synthetic XAF fixture that needs no DevExpress reference
 - Optional DevExpress ground-truth catalog, generated locally by licensees

README.md

@@ -56,16 +56,36 @@ tool never links against DevExpress assemblies:
 ```bash
 dotnet tool install -g XafLogicExplainer.Cli
 
-# Extract, writing Markdown + JSON into .xaflogic-output/
-xaflogic extract --project "C:\MySolution\MyApp.Module"
+xaflogic agents --project "C:\MySolution\MyApp.Module"
 ```
 
-Documentation is generated in **English or Spanish** (`--lang en|es`).
+That writes `AGENTS.md`, `CLAUDE.md` and `.github/copilot-instructions.md` at your solution root.
+No account, no API key, no server. Your agent understands the application on its next question.
+
+### What it writes, and why it is split in two
+
+`AGENTS.md` is prepended to *every* request an agent makes in the repository, so its cost is paid
+forever. Dumping 70 KB of entity detail there would crowd out the actual question. So the output is
+tiered:
+
+| | | |
+| --- | --- | --- |
+| `AGENTS.md` | ~11 KB | Always loaded: ground rules, complete inventories, conventions, recipes |
+| `.xaflogic/*.md` | ~70 KB | Opened on demand: full properties, handler code, rule messages, `.xafml` |
+
+The most valuable part is the smallest. `AGENTS.md` opens with **ground rules** — that this
+application uses XPO and never EF Core, that the inventories are *complete* so anything absent
+genuinely does not exist, and that some behavior lives in the Model Editor rather than in C#. Those
+few paragraphs stop most of the confident invention agents produce about unfamiliar XAF codebases.
+
+Existing files are never clobbered: generated text lives between markers, anything you wrote by
+hand is preserved, and regenerating is byte-identical when nothing changed.
 
 ### Commands
 
 | Command | What it does |
 | --- | --- |
+| `agents` | **Write `AGENTS.md` / `CLAUDE.md` / Copilot instructions for your agent** |
 | `extract` | Read the project, write Markdown + JSON locally |
 | `diff` | Compare against the previous extraction and report what changed |
 | `status` | Show the change-detection hash and whether a re-extract is needed |
@@ -75,6 +95,8 @@ Documentation is generated in **English or Spanish** (`--lang en|es`).
 | `config` | Set defaults in `~/.xaflogic/config.json` |
 | `projects` | Manage several XAF projects; most commands accept `--all` |
 
+Documentation is generated in **English or Spanish** (`--lang en|es`).
+
 Useful flags: `--orm auto\|xpo\|efcore`, `--lang en\|es`, `--enrich` (AI-generated business-logic
 summaries per controller and action), `--force`, `--all`.
 
@@ -93,15 +115,14 @@ applications. The agent-facing surface is what is landing now, in the open.
 | ✅ | Incremental change detection, diff reports, multi-project, watch mode |
 | ✅ | AI enrichment of controllers and actions (`--enrich`) |
 | ✅ | Blazor in-app help panel |
-| 🚧 | **`AGENTS.md` / `CLAUDE.md` output** — zero infrastructure, works for everyone |
+| ✅ | **`AGENTS.md` / `CLAUDE.md` / Copilot instructions** — zero infrastructure, works for everyone |
+| ✅ | Pluggable publishing targets (`IDocumentationSink`) |
 | 🚧 | **MCP server** — let any agent query your XAF app live |
 | 🚧 | **Claude Code / Copilot / Cursor skill**, installable from this repo |
-| 🚧 | Pluggable publishing targets (`IDocumentationSink`) |
 | 🚧 | xUnit test suite over a synthetic XAF fixture |
 
-Today the only remote publishing target is PeopleWorks Copilot, which is where this tool grew up.
-That is being generalized: it becomes one sink among several, and the interesting outputs
-(`AGENTS.md`, MCP) need no server at all.
+PeopleWorks Copilot, where this tool grew up, is now one sink among several rather than the
+destination everything was built around. The outputs that matter most need no server at all.
 
 ## Repository layout
 

src/XafLogicExplainer.Cli/Program.cs

@@ -10,6 +10,7 @@
 using XafLogicExplainer.Core.Diff;
 using XafLogicExplainer.Core.Generators;
 using XafLogicExplainer.Core.Hashing;
+using XafLogicExplainer.Core.Sinks;
 using Microsoft.Extensions.AI;
 using OpenAI;
 using XafLogicExplainer.Core.Models;
@@ -21,7 +22,7 @@
 if (args.Length == 0 || args.Contains("--help") || args.Contains("-h"))
 {
     AnsiConsole.Write(new FigletText("XAF Logic").Color(Color.Blue));
-    AnsiConsole.MarkupLine("[grey]Extract, document, and sync XAF project logic to PeopleWorks Copilot[/]");
+    AnsiConsole.MarkupLine("[grey]Teach your AI coding agent what your XAF application actually does[/]");
     AnsiConsole.WriteLine();
 }
 
@@ -1370,10 +1371,204 @@ await AnsiConsole.Status().Spinner(Spinner.Known.Dots).StartAsync("Comparing sna
 
 rootCommand.AddCommand(diffCommand);
 
+// ============================================================
+// COMMAND: agents
+// ============================================================
+var agentsCommand = new Command(
+    "agents",
+    "Generate AGENTS.md, CLAUDE.md and Copilot instructions so AI agents understand this XAF app");
+
+var agentsOutputOption = new Option<string?>(
+    "--output",
+    "Where to write (default: the solution or repository root above the module)");
+var agentsOnlyOption = new Option<string?>(
+    "--only",
+    "Limit the files written: agents, claude, copilot (comma-separated)");
+
+agentsCommand.AddOption(projectPathOption);
+agentsCommand.AddOption(languageOption);
+agentsCommand.AddOption(forceOption);
+agentsCommand.AddOption(ormOption);
+agentsCommand.AddOption(allOption);
+agentsCommand.AddOption(enrichOption);
+agentsCommand.AddOption(agentsOutputOption);
+agentsCommand.AddOption(agentsOnlyOption);
+
+// InvocationContext rather than a typed handler: SetHandler tops out at eight parameters, and
+// this command already sits at that boundary. sync and watch resolve options the same way.
+agentsCommand.SetHandler(async (context) =>
+{
+    var agentsProjectPath = context.ParseResult.GetValueForOption(projectPathOption);
+    var agentsLanguage = context.ParseResult.GetValueForOption(languageOption);
+    var agentsForce = context.ParseResult.GetValueForOption(forceOption);
+    var agentsOrm = context.ParseResult.GetValueForOption(ormOption);
+    var agentsAll = context.ParseResult.GetValueForOption(allOption);
+    var agentsEnrich = context.ParseResult.GetValueForOption(enrichOption);
+    var agentsOutput = context.ParseResult.GetValueForOption(agentsOutputOption);
+    var agentsOnly = context.ParseResult.GetValueForOption(agentsOnlyOption);
+
+    var agentsConfig = ConfigHelper.Load();
+    var agentsOptions = ParseAgentTargets(agentsOnly, agentsOutput);
+
+    if (agentsAll)
+    {
+        if (agentsConfig.Projects.Count == 0)
+        {
+            AnsiConsole.MarkupLine("[red]✗[/] No projects configured. Add one with: [cyan]xaflogic projects add[/]");
+            return;
+        }
+
+        foreach (var configured in agentsConfig.Projects)
+        {
+            AnsiConsole.WriteLine();
+            AnsiConsole.MarkupLine($"[bold blue]▸ {Markup.Escape(configured.Name)}[/]");
+
+            await GenerateAgentFiles(
+                configured.ProjectPath,
+                configured.Language ?? agentsLanguage ?? agentsConfig.Language ?? "es",
+                configured.Orm ?? agentsOrm,
+                agentsForce,
+                agentsEnrich,
+                agentsOptions,
+                agentsConfig);
+        }
+
+        return;
+    }
+
+    var singleProjectPath = agentsProjectPath ?? agentsConfig.ProjectPath;
+
+    if (string.IsNullOrEmpty(singleProjectPath) || !Directory.Exists(singleProjectPath))
+    {
+        AnsiConsole.MarkupLine("[red]✗[/] --project is required. Set it with: [cyan]xaflogic config --project <path>[/]");
+        return;
+    }
+
+    await GenerateAgentFiles(
+        singleProjectPath,
+        agentsLanguage ?? agentsConfig.Language ?? "es",
+        agentsOrm ?? agentsConfig.Orm,
+        agentsForce,
+        agentsEnrich,
+        agentsOptions,
+        agentsConfig);
+});
+
+rootCommand.AddCommand(agentsCommand);
+
 // ============================================================
 // HELPERS
 // ============================================================
 
+// Turns the --only and --output values into sink options.
+static AgentFilesOptions ParseAgentTargets(string? only, string? output)
+{
+    if (string.IsNullOrWhiteSpace(only))
+        return new AgentFilesOptions { OutputRoot = output };
+
+    var requested = only
+        .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
+        .Select(t => t.ToLowerInvariant())
+        .ToHashSet();
+
+    return new AgentFilesOptions
+    {
+        OutputRoot = output,
+        WriteAgentsMd = requested.Contains("agents"),
+        WriteClaudeMd = requested.Contains("claude"),
+        WriteCopilotInstructions = requested.Contains("copilot"),
+    };
+}
+
+// Extracts one project and writes the agent-facing context files.
+static async Task GenerateAgentFiles(
+    string projectPath,
+    string language,
+    string? orm,
+    bool force,
+    bool enrich,
+    AgentFilesOptions options,
+    CliConfig config)
+{
+    if (!Directory.Exists(projectPath))
+    {
+        AnsiConsole.MarkupLine($"[red]✗[/] Not found: {Markup.Escape(projectPath)}");
+        return;
+    }
+
+    var agentHashCalc = new ProjectHashCalculator();
+    if (!force && !agentHashCalc.HasChanged(projectPath))
+    {
+        AnsiConsole.MarkupLine("[yellow]⊘[/] No source changes since the last run. Use [cyan]--force[/] to regenerate anyway.");
+        return;
+    }
+
+    ExtractedProject agentProject = null!;
+    await AnsiConsole.Status().Spinner(Spinner.Known.Dots).StartAsync("Reading the application...", async ctx =>
+    {
+        var agentExtractor = new LogicExtractor();
+        agentProject = agentExtractor.ExtractFromSourceDirectory(projectPath, BuildExtractionOptions(language, orm));
+        await Task.CompletedTask;
+    });
+
+    if (enrich)
+    {
+        await EnrichWithAi(agentProject, config, language);
+    }
+
+    var agentGenerator = new MarkdownDocumentationGenerator(language);
+    var agentSections = agentGenerator.GenerateSections(agentProject);
+
+    var agentSink = new AgentFilesSink(options, ThisAssemblyVersion());
+    var agentResult = await agentSink.PublishAsync(agentProject, agentSections);
+
+    if (!agentResult.Success)
+    {
+        AnsiConsole.MarkupLine($"[red]✗[/] {Markup.Escape(agentResult.Summary)}");
+        return;
+    }
+
+    agentHashCalc.SaveHash(projectPath, agentProject.SourceHash);
+
+    // What the agent now knows, stated as facts rather than file sizes -- the point of the command
+    // is the knowledge, not the bytes.
+    var agentActions = agentProject.Controllers.Sum(c => c.Actions.Count);
+    var knows = new Table().Border(TableBorder.Rounded).AddColumn("Your agent now knows").AddColumn("");
+    knows.AddRow("Business entities", agentProject.Entities.Count.ToString());
+    knows.AddRow("Controllers", agentProject.Controllers.Count.ToString());
+    knows.AddRow("Actions", agentActions.ToString());
+    knows.AddRow("ORM", agentProject.OrmType);
+    if (agentProject.Navigation.Count > 0)
+        knows.AddRow("Navigation groups", agentProject.Navigation.Count.ToString());
+    if (agentProject.ModelEditorInfo is { } modelInfo && modelInfo.Views.Count > 0)
+        knows.AddRow("Model Editor views", modelInfo.Views.Count.ToString());
+    AnsiConsole.Write(knows);
+
+    AnsiConsole.WriteLine();
+    foreach (var artifact in agentResult.Artifacts.Where(a =>
+                 !a.Contains(AgentContextGenerator.DetailFolder, StringComparison.Ordinal)))
+    {
+        AnsiConsole.MarkupLine($"[green]✓[/] {Markup.Escape(artifact)}");
+    }
+
+    var detailCount = agentResult.Artifacts.Count(a =>
+        a.Contains(AgentContextGenerator.DetailFolder, StringComparison.Ordinal));
+    if (detailCount > 0)
+    {
+        AnsiConsole.MarkupLine(
+            $"[grey]+ {detailCount} detail files in {AgentContextGenerator.DetailFolder}/ (read on demand, not loaded every request)[/]");
+    }
+
+    AnsiConsole.WriteLine();
+    AnsiConsole.MarkupLine("[grey]Ask your agent something only this codebase could answer.[/]");
+}
+
+// The tool version, stamped into generated files so a stale one can be identified.
+static string ThisAssemblyVersion() =>
+    System.Reflection.Assembly.GetExecutingAssembly().GetName().Version is { } v
+        ? $"{v.Major}.{v.Minor}.{v.Build}"
+        : "0.9.0";
+
 static ExtractionOptions BuildExtractionOptions(string language, string? orm = null)
 {
     var options = new ExtractionOptions

src/XafLogicExplainer.CopilotSync/Sinks/PeopleWorksCopilotSink.cs

@@ -0,0 +1,65 @@
+using XafLogicExplainer.Core.Interfaces;
+using XafLogicExplainer.Core.Models;
+using XafLogicExplainer.CopilotSync.Services;
+
+namespace XafLogicExplainer.CopilotSync.Sinks;
+
+/// <summary>
+/// Publishes extracted documentation to a PeopleWorks Copilot resource.
+/// </summary>
+/// <remarks>
+/// A thin adapter over <see cref="DocumentationUploader"/>, which holds the upload logic and is
+/// unchanged by this type. Its purpose is to make the remote target one
+/// <see cref="IDocumentationSink"/> among several rather than the destination the tool is built
+/// around, so a caller can choose where documentation goes without knowing what it is talking to.
+/// </remarks>
+public sealed class PeopleWorksCopilotSink : IDocumentationSink
+{
+    private readonly DocumentationUploader _uploader;
+    private readonly Action<string>? _onProgress;
+
+    /// <summary>Creates the sink.</summary>
+    /// <param name="uploader">The configured uploader.</param>
+    /// <param name="onProgress">Optional progress callback, surfaced to the console by the CLI.</param>
+    public PeopleWorksCopilotSink(DocumentationUploader uploader, Action<string>? onProgress = null)
+    {
+        _uploader = uploader;
+        _onProgress = onProgress;
+    }
+
+    /// <inheritdoc />
+    public string Name => "peopleworks-copilot";
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// True, and deliberately visible: this sink sends documentation derived from the analyzed
+    /// source code to a remote service, which is a decision a caller should be able to see before
+    /// making it.
+    /// </remarks>
+    public bool IsRemote => true;
+
+    /// <inheritdoc />
+    public async Task<SinkResult> PublishAsync(
+        ExtractedProject project,
+        IReadOnlyList<DocumentSection> sections,
+        CancellationToken cancellationToken = default)
+    {
+        // The uploader renders its own sections from the project, because it also produces a
+        // combined document and needs the two to agree. The sections passed in are therefore
+        // unused here -- other sinks want them, this one does not.
+        var result = await _uploader.UploadProjectDocumentationAsync(project, _onProgress);
+
+        if (!result.Success)
+        {
+            var detail = result.Errors.Count > 0
+                ? string.Join("; ", result.Errors)
+                : result.Message;
+
+            return SinkResult.Fail($"Upload failed: {detail}");
+        }
+
+        return SinkResult.Ok(
+            $"{result.DocumentsUploaded} documents uploaded",
+            result.UploadedDocuments.Select(d => d.FileName).ToList());
+    }
+}