From 9b0224729449df7e0f82ea22f6cd0b2d25d90b3b Mon Sep 17 00:00:00 2001
From: jamesshenry <git@mail.jamesshenry.dev>
Date: Tue, 2 Jun 2026 12:44:25 +0100
Subject: [PATCH] feat: init command adds instructions.md help file

---
 src/Loom.Build/Commands.cs                    |  1 +
 src/Loom.Build/Properties/launchSettings.json |  2 +-
 src/Loom.Build/Setup.cs                       | 77 +++++++++++++++++++
 3 files changed, 79 insertions(+), 1 deletion(-)

diff --git a/src/Loom.Build/Commands.cs b/src/Loom.Build/Commands.cs
index 1748222..39dd983 100644
--- a/src/Loom.Build/Commands.cs
+++ b/src/Loom.Build/Commands.cs
@@ -94,6 +94,7 @@ public async Task Init(bool force = false)
             await Setup.InitializeWorkspace(selectedSln, selectedProj, force);
             await Setup.InitializeWorkflows(force);
             await Setup.InitializeDependabot(force);
+            await Setup.InitializeInstructionsMd();
         }
         catch (Exception ex)
         {
diff --git a/src/Loom.Build/Properties/launchSettings.json b/src/Loom.Build/Properties/launchSettings.json
index 1f8fb69..4bf63e3 100644
--- a/src/Loom.Build/Properties/launchSettings.json
+++ b/src/Loom.Build/Properties/launchSettings.json
@@ -2,7 +2,7 @@
   "profiles": {
     "loom.example": {
       "commandName": "Project",
-      "commandLineArgs": "test",
+      "commandLineArgs": "init",
       "workingDirectory": "C:/source/personal/typical",
     }
   }
diff --git a/src/Loom.Build/Setup.cs b/src/Loom.Build/Setup.cs
index a9b1032..ac95d7a 100644
--- a/src/Loom.Build/Setup.cs
+++ b/src/Loom.Build/Setup.cs
@@ -221,4 +221,81 @@ internal static async Task InitializeDependabot(bool force)
             AnsiConsole.MarkupLine("[green]dependabot.yml created in .github[/]");
         }
     }
+
+    internal static async Task InitializeInstructionsMd()
+    {
+        var buildDir = Path.Combine(Environment.CurrentDirectory, ".build");
+        if (!Directory.Exists(buildDir))
+            Directory.CreateDirectory(buildDir);
+
+        var instructionsMd = Path.Combine(buildDir, "instructions.md");
+
+        string content = """
+# Loom Build Instructions
+
+## Prerequisites
+
+- .NET SDK from `global.json`
+- Tool manifest in `dotnet-tools.json`
+
+Install/restore tools:
+
+```bash
+dotnet tool restore
+```
+
+Required tools and dependent Loom modules:
+
+| Tool Command | Tool Package | Dependent Module(s) |
+| --- | --- | --- |
+| `loom` | `loom.build` | CLI entry point used to run all targets/modules |
+| `minver` | `minver-cli` | `MinVerModule` |
+| `vpk` | `vpk` | `VelopackReleaseModule` |
+| `reportgenerator` | `dotnet-reportgenerator-globaltool` | `ReportGeneratorModule` |
+
+## Setup
+
+Initialize Loom files:
+
+```bash
+dotnet loom init
+```
+
+Run tests:
+
+```bash
+dotnet loom test
+```
+
+Run release pipeline:
+
+```bash
+dotnet loom release
+```
+
+## Enable NuGet and GitHub Releases
+
+To allow upload/publishing modules to run, enable the following flags in `.build/loom.json`:
+
+```json
+{
+    "workspace": {
+        "enableNugetUpload": true,
+        "enableGithubRelease": true
+    }
+}
+```
+
+Also configure required GitHub secrets:
+
+- `GITHUB_TOKEN` is the built-in GitHub Actions token (`secrets.GITHUB_TOKEN`).
+- Create a repository secret named `NUGET_API_KEY`.
+
+See release workflow setup in [.github/workflows/release.yml](../.github/workflows/release.yml).
+
+""";
+
+        await File.WriteAllTextAsync(instructionsMd, content);
+        AnsiConsole.MarkupLine("[green]instructions.md updated in .build[/]");
+    }
 }