Staging

.github/workflows/generate-docs.yaml

@@ -35,6 +35,6 @@ jobs:
         run: |
           git config user.name "github-actions"
           git config user.email "github-actions@github.com"
-          git add Shared.Rcl/wwwroot/raw_docs/CommandIndex.md Shared.Rcl/wwwroot/raw_docs/Commands.md
+          git add Shared.Rcl/wwwroot/raw_docs/cli-commands-index.md Shared.Rcl/wwwroot/raw_docs/cli-commands.md
           git commit -m "Update CLI docs" || echo "No changes to commit"
           git push

.github/workflows/publish-cli.yml

@@ -4,9 +4,9 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "RackPeek version (e.g. 0.1.0)"
+        description: "RackPeek version (e.g. 2.2.0)"
         required: true
-        default: "0.0.3"
+        default: "2.2.0"
 
 permissions:
   contents: write

.github/workflows/publish-docker.yaml

@@ -4,9 +4,9 @@ on:
   workflow_dispatch:
     inputs:
       version:
-        description: "RackPeek version (e.g. v1.0.0)"
+        description: "RackPeek version (e.g. v2.2.0)"
         required: true
-        default: "v0.0.12"
+        default: "v2.2.0"
 
 permissions:
   contents: read

.github/workflows/test.yml

@@ -26,6 +26,59 @@ jobs:
         run: dotnet format --verify-no-changes
 
 
+  discovery-tests:
+    name: Discovery Tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    needs: format
+
+    # Discovery runs on the machines being inventoried rather than on the RackPeek
+    # host, so its tests are the ones that have to pass on every platform. They are
+    # driven entirely from captured fixtures and never read the runner itself.
+    # windows-latest joins this list when the Windows probe lands.
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Restore
+        run: dotnet restore Tests.Discovery
+
+      - name: Run Discovery Tests
+        run: dotnet test Tests.Discovery --configuration Release --verbosity normal
+
+
+  mcp-tests:
+    name: MCP Tests
+    runs-on: ubuntu-latest
+    needs: format
+
+    # Every MCP test is end-to-end: a real MCP client speaking streamable HTTP to the
+    # real server over WebApplicationFactory, asserting on the YAML that lands on disk.
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup .NET
+        uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: 10.0.x
+
+      - name: Restore
+        run: dotnet restore Tests.Mcp
+
+      - name: Run MCP Tests
+        run: dotnet test Tests.Mcp --configuration Release --verbosity normal
+
+
   cli-tests:
     name: CLI Tests
     runs-on: ubuntu-latest

.gitignore

@@ -427,3 +427,4 @@ FodyWeavers.xsd
 
 # macOS
 .DS_Store
+ISSUE_TRIAGE.md

AGENTS.md

@@ -207,7 +207,7 @@ When you change persisted YAML shape, the PR **must** include:
 
 ## 7. CLI surface
 
-The full command tree is documented in `docs/Commands.md` and `docs/CommandIndex.md` (auto-generated by `generate-docs.sh`). At a glance:
+The full command tree is documented in `Shared.Rcl/wwwroot/raw_docs/cli-commands.md` and `Shared.Rcl/wwwroot/raw_docs/cli-commands-index.md` (auto-generated by `generate-docs.sh`). At a glance:
 
 ```
 rpk <kind> <verb> [name] [flags]
@@ -311,8 +311,9 @@ Default branches: feature work targets `staging`; releases flow `staging → mai
 | `docs/development/contribution-guidelines.md` | PR process |
 | `docs/development/dev-cheat-sheet.md` | Build / release / Docker / Playwright details |
 | `docs/development/dev-setup.md` | First-time environment setup |
+| `docs/development/release-guide.md` | End-to-end release process (version bump, docs regen, publish workflows) |
 | `docs/development/testing-guidelines.md` | Testing philosophy + examples |
-| `docs/Commands.md` / `docs/CommandIndex.md` | Auto-generated CLI reference |
+| `Shared.Rcl/wwwroot/raw_docs/cli-commands.md` / `cli-commands-index.md` | Auto-generated CLI reference |
 | `schemas/v1,v2,v3/` | Versioned YAML schemas |
 | `README.md` | User-facing overview, Docker install, links |
 | `LICENSE` | License terms |

README.md

@@ -1,11 +1,11 @@
 [![RackPeek demo](./assets/rackpeek_banner_thin.png)](./assets/rackpeek_banner_thin.png)
 
-![Version](https://img.shields.io/badge/Version-2.1.0-2ea44f) ![Status](https://img.shields.io/badge/Status-Stable-success)
+![Version](https://img.shields.io/badge/Version-2.2.0-2ea44f) ![Status](https://img.shields.io/badge/Status-Stable-success)
 [![Join our Discord](https://img.shields.io/badge/Discord-Join%20Us-7289DA?logo=discord&logoColor=white)](https://discord.gg/egXRPdesee) [![Live Demo](https://img.shields.io/badge/Live%20Demo-Try%20RackPeek%20Online-2ea44f?logo=githubpages&logoColor=white)](https://timmoth.github.io/RackPeek/) [![Docker Hub](https://img.shields.io/badge/Docker%20Hub-rackpeek-2496ED?logo=docker&logoColor=white)](https://hub.docker.com/r/aptacode/rackpeek/)
 
 RackPeek is a webui & CLI tool for documenting and managing home lab and small-scale IT infrastructure.
 
-It helps you track hardware, services, networks, and their relationships in a clear, scriptable, and reusable way without enterprise bloat or proprietary lock-in or drowning in unnecessary metadata or process.
+It helps you track hardware, services, networks, and their relationships in a clear, scriptable, and reusable way without enterprise bloat or proprietary lock-in or drowning in unnecessary metadata or process. It can auto-discover what's already running (`rpk discover system / docker / proxmox / network`), and its built-in MCP server lets AI assistants query and manage your inventory.
 
 ### The roadmap for the next wave of features is actively being discussed, please make your voice heard! 
 
@@ -85,6 +85,12 @@ volumes:
 * 
   [**Ansible Inventory Generator Guide**](https://timmoth.github.io/RackPeek/docs/ansible-generator-guide)
 
+* 
+  [**Auto Discovery Guide**](https://timmoth.github.io/RackPeek/docs/discovery-guide)
+
+* 
+  [**MCP Server Guide**](https://timmoth.github.io/RackPeek/docs/mcp-guide) — let AI assistants query, manage and build your stack over the built-in `/mcp` endpoint
+
 * 
   [**CLI Commands Reference**](https://timmoth.github.io/RackPeek/docs/cli-commands)
 

RackPeek.Domain/Api/UpsertInventoryUseCase.cs

@@ -2,6 +2,7 @@
 using System.ComponentModel.DataAnnotations;
 using System.Text.Json;
 using System.Text.Json.Serialization;
+using RackPeek.Domain.Discovery;
 using RackPeek.Domain.Persistence;
 using RackPeek.Domain.Persistence.Yaml;
 using RackPeek.Domain.Resources;
@@ -62,6 +63,19 @@ public async Task<ImportYamlResponse> ExecuteAsync(ImportYamlRequest request) {
         List<Resource>? incomingResources = incomingRoot.Resources;
         IReadOnlyList<Resource> currentResources = await repo.GetAllOfTypeAsync<Resource>();
 
+        IReadOnlyList<Connection> currentConnections = await repo.GetConnectionsAsync();
+
+        // Line discovered resources up with what they already map to before anything
+        // else looks at names, so the diff below reports against the right resources.
+        // A dry run gets the same reconciliation but is not allowed to improve stored
+        // names, because that rewrites the inventory and a dry run must not.
+        DiscoveryIdResolver.ResolveNames(
+            currentResources,
+            incomingResources,
+            incomingRoot.Connections,
+            currentConnections,
+            !request.DryRun);
+
         IGrouping<string, Resource>? duplicate = incomingResources
             .GroupBy(r => r.Name, StringComparer.OrdinalIgnoreCase)
             .FirstOrDefault(g => g.Count() > 1);
@@ -118,7 +132,6 @@ public async Task<ImportYamlResponse> ExecuteAsync(ImportYamlRequest request) {
             else if (oldYaml != newYaml) response.Updated.Add(incoming.Name);
         }
 
-        IReadOnlyList<Connection> currentConnections = await repo.GetConnectionsAsync();
         List<Connection>? mergedConnections = ConnectionMerger.Merge(
             currentConnections,
             incomingRoot.Connections,

RackPeek.Domain/Discovery/ArpTableParser.cs

@@ -0,0 +1,107 @@
+using System.Net;
+using System.Net.Sockets;
+
+namespace RackPeek.Domain.Discovery;
+
+/// <summary>
+///     Reads an ARP table into ip → MAC, from either format the probe can produce:
+///     Linux's <c>/proc/net/arp</c> or BSD/macOS <c>arp -an</c> output. MACs are
+///     normalised (lowercase, zero-padded octets) because macOS prints <c>1:0:5e:…</c>
+///     where Linux prints <c>01:00:5e:…</c> — and the MAC seeds the discovery id, so
+///     the same machine must hash the same from every workstation. Pure; never throws.
+/// </summary>
+public static class ArpTableParser {
+    public static IReadOnlyDictionary<string, string> Parse(string? text) {
+        var result = new Dictionary<string, string>(StringComparer.Ordinal);
+
+        if (string.IsNullOrWhiteSpace(text))
+            return result;
+
+        foreach (var line in text.Split('\n')) {
+            (string Ip, string Mac)? entry = ParseLine(line.Trim());
+
+            if (entry != null)
+                result.TryAdd(entry.Value.Ip, entry.Value.Mac);
+        }
+
+        return result;
+    }
+
+    private static (string Ip, string Mac)? ParseLine(string line) {
+        if (line.Length == 0)
+            return null;
+
+        // BSD/macOS: "? (192.168.1.1) at a4:91:b1:4e:3c:20 on en0 ifscope [ethernet]"
+        var open = line.IndexOf('(');
+        var close = line.IndexOf(')');
+
+        if (open >= 0 && close > open) {
+            var ip = line[(open + 1)..close];
+            var at = line.IndexOf(" at ", close, StringComparison.Ordinal);
+
+            if (at < 0 || !IsIpv4(ip))
+                return null;
+
+            var rest = line[(at + 4)..];
+            var end = rest.IndexOf(' ');
+            var mac = NormaliseMac(end > 0 ? rest[..end] : rest);
+
+            return mac == null ? null : (ip, mac);
+        }
+
+        var columns = line.Split(' ', '\t', StringSplitOptions.RemoveEmptyEntries);
+
+        if (columns.Length < 2 || !IsIpv4(columns[0]))
+            return null;
+
+        // Linux /proc/net/arp: "192.168.1.1  0x1  0x2  a4:91:b1:4e:3c:20  *  eth0"
+        if (columns.Length >= 4 && columns[1].StartsWith("0x", StringComparison.Ordinal)) {
+            // Flags 0x0 marks an entry the kernel gave up resolving.
+            if (columns[2] == "0x0")
+                return null;
+
+            var linuxMac = NormaliseMac(columns[3]);
+
+            return linuxMac == null ? null : (columns[0], linuxMac);
+        }
+
+        // Windows arp -a: "192.168.1.1           a4-91-b1-4e-3c-20     dynamic"
+        var windowsMac = NormaliseMac(columns[1]);
+
+        return windowsMac == null ? null : (columns[0], windowsMac);
+    }
+
+    /// <summary>
+    ///     Lowercase, colon-separated, zero-padded — or null for anything that is not a
+    ///     usable MAC. Accepts Windows' dash separators so the same machine hashes the
+    ///     same from every platform's ARP output.
+    /// </summary>
+    public static string? NormaliseMac(string? raw) {
+        if (string.IsNullOrWhiteSpace(raw))
+            return null;
+
+        var parts = raw.Trim().Split(':', '-');
+
+        if (parts.Length != 6)
+            return null;
+
+        var octets = new string[6];
+
+        for (var i = 0; i < 6; i++) {
+            var part = parts[i];
+
+            if (part.Length is 0 or > 2 || !part.All(Uri.IsHexDigit))
+                return null;
+
+            octets[i] = part.Length == 1 ? "0" + char.ToLowerInvariant(part[0]) : part.ToLowerInvariant();
+        }
+
+        var mac = string.Join(':', octets);
+
+        // All-zero means the neighbour never answered — no identity there.
+        return mac == "00:00:00:00:00:00" ? null : mac;
+    }
+
+    private static bool IsIpv4(string value) =>
+        IPAddress.TryParse(value, out IPAddress? ip) && ip.AddressFamily == AddressFamily.InterNetwork;
+}

RackPeek.Domain/Discovery/DiscoveryDocument.cs

@@ -0,0 +1,15 @@
+using RackPeek.Domain.Persistence.Yaml;
+using RackPeek.Domain.Resources;
+
+namespace RackPeek.Domain.Discovery;
+
+/// <summary>Renders discovered resources as a RackPeek YAML document.</summary>
+public static class DiscoveryDocument {
+    public static string ToYaml(IEnumerable<Resource> resources) {
+        return YamlResourceCollection.SerializeRootAsync(new YamlRoot {
+            Version = RackPeekConfigMigrationDeserializer.ListOfMigrations.Count,
+            Resources = resources.ToList(),
+            Connections = []
+        });
+    }
+}

RackPeek.Domain/Discovery/DiscoveryId.cs

@@ -0,0 +1,49 @@
+using System.Security.Cryptography;
+using System.Text;
+
+namespace RackPeek.Domain.Discovery;
+
+/// <summary>
+///     Deterministic, globally unique identity for a discovered resource.
+///     Format: <c>rpk1:{scheme}:{16 hex chars}</c>
+///     The hash keeps low-value identifiers (machine-id, MAC) out of a config file
+///     that is frequently committed to a public repository. Note this is
+///     obfuscation rather than secrecy: the salt is public, so a low entropy seed
+///     such as a MAC address remains recoverable by brute force.
+/// </summary>
+public static class DiscoveryId {
+    public const string Prefix = "rpk1";
+    public const string SystemScheme = "sys";
+    public const string DockerScheme = "docker";
+    public const string NetworkScheme = "net";
+
+    public static string Create(string scheme, string seed) {
+        if (string.IsNullOrWhiteSpace(scheme))
+            throw new ArgumentException("Scheme is required.", nameof(scheme));
+
+        if (string.IsNullOrWhiteSpace(seed))
+            throw new ArgumentException("Seed is required.", nameof(seed));
+
+        var hash = SHA256.HashData(Encoding.UTF8.GetBytes($"{Prefix}:{scheme}:{seed}"));
+
+        return $"{Prefix}:{scheme}:{Convert.ToHexString(hash, 0, 8).ToLowerInvariant()}";
+    }
+
+    /// <summary>The scheme segment of an id — "sys" for rpk1:sys:… — or null for anything malformed.</summary>
+    public static string? Scheme(string? discoveryId) {
+        if (string.IsNullOrWhiteSpace(discoveryId))
+            return null;
+
+        var parts = discoveryId.Split(':');
+
+        return parts.Length == 3 ? parts[1] : null;
+    }
+
+    /// <summary>Short, stable fragment used to disambiguate generated names.</summary>
+    public static string ShortSuffix(string discoveryId) {
+        var lastColon = discoveryId.LastIndexOf(':');
+        var hash = lastColon >= 0 ? discoveryId[(lastColon + 1)..] : discoveryId;
+
+        return hash.Length <= 8 ? hash : hash[..8];
+    }
+}