From 78ce5003e1359cc05db4b647918806ba734258af Mon Sep 17 00:00:00 2001 From: Kyle Isom Date: Thu, 2 Apr 2026 15:14:13 -0700 Subject: [PATCH] Update PLATFORM_EVOLUTION.md and TOOLING.md for current state Reflect Phase E in progress, add orion to fleet, mark mcdoc as deployed, remove deprecated mcdeploy, update multi-arch fleet info, and add mcdoc/mcq to tooling tables. Co-Authored-By: Claude Opus 4.6 (1M context) --- PLATFORM_EVOLUTION.md | 13 ++++++++----- TOOLING.md | 19 ++++++++++++------- 2 files changed, 20 insertions(+), 12 deletions(-) diff --git a/PLATFORM_EVOLUTION.md b/PLATFORM_EVOLUTION.md index b439412..cabe553 100644 --- a/PLATFORM_EVOLUTION.md +++ b/PLATFORM_EVOLUTION.md @@ -5,7 +5,7 @@ from its current manually-wired state to fully declarative deployment. It is a living design document — not a spec, not a commitment, but a record of where we are, where we want to be, and what's between. -Last updated: 2026-03-28 (Phases A + B + C + D complete) +Last updated: 2026-04-02 (Phases A–D complete, Phase E in progress) --- @@ -324,9 +324,11 @@ mcproxyctl, TOML editing, cert generation, or DNS zone editing. ### Immediate Next Steps -1. **Phase E: Multi-node agent management** — see below. -2. **mcdoc implementation** — fully designed, no platform evolution - dependency. Deployable now with the new route system. +1. **Phase E: Multi-node agent management** — see below. See + `docs/phase-e-plan.md` for the detailed Phase E design and + `docs/architecture-v2.md` for the v2 master/agent architecture. +2. **mcdoc** — deployed (v0.1.0 on rift). Serves rendered markdown + from Gitea via mc-proxy. #### 10. Agent Binary Location Convention @@ -380,8 +382,9 @@ Different for NixOS vs Debian. | Node | OS | Arch | Status | |------|----|------|--------| | rift | NixOS | amd64 | Operational, single MCP agent | -| hyperborea | Debian (RPi) | arm64 | Online, needs agent provisioning | +| hyperborea | Debian (RPi) | arm64 | Online, agent provisioning planned | | svc | Debian | amd64 | Runs MCIAS, needs agent for public edge services | +| orion | NixOS | amd64 | Provisioned, offline for maintenance | --- diff --git a/TOOLING.md b/TOOLING.md index ab79665..22eaa1b 100644 --- a/TOOLING.md +++ b/TOOLING.md @@ -8,12 +8,11 @@ Go binaries built with `CGO_ENABLED=0` and installed via Nix flakes. | Tool | Project | Purpose | Install target | |------|---------|---------|---------------| | `mcp` | mcp | Control plane CLI — deploy, status, lifecycle, file transfer | vade, orion | -| `mcp-agent` | mcp | Control plane agent — per-node container management daemon | rift (systemd) | +| `mcp-agent` | mcp | Control plane agent — per-node container management daemon | rift, svc (systemd) | | `mciasctl` | mcias | MCIAS admin CLI — accounts, tokens, policies | vade, orion, rift | | `mciasgrpcctl` | mcias | MCIAS gRPC debug CLI | vade, orion, rift | | `mcproxyctl` | mc-proxy | MC-Proxy admin CLI — routes, firewall, status | vade, orion, rift | | `mcrctl` | mcr | MCR admin CLI — repositories, policies, audit | vade, orion, rift | -| `mcdeploy` | mcdeploy | Deployment CLI — deprecated, superseded by MCP (archived) | — | ### Server-only binaries (not installed as tools) @@ -29,6 +28,8 @@ These run inside containers and are not installed on operator workstations: | `mc-proxy` | mc-proxy | TLS proxy server | | `mcns` | mcns | DNS server | | `mcat` | mcat | Login policy tester web app | +| `mcdoc` | mcdoc | Documentation server | +| `mcq` | mcq | Document review queue | ## Installation @@ -46,15 +47,18 @@ via `mcpkg.nix` in the NixOS configuration. Adding a tool: - Build: `pkgs.buildGoModule` with `vendorHash = null` (vendored deps). - ldflags: `-s -w -X main.version=${version}`. - `subPackages`: list only the client binaries, not servers. -- `system`: `x86_64-linux` (all machines are x86_64). +- `system`: `x86_64-linux` for rift, svc, and orion; `aarch64-linux` + for hyperborea. Flakes that target the full fleet should support both. ### MCP agent The `mcp-agent` is a special case: it runs as a systemd service on managed nodes (not as a container, since it manages containers). Its -flake exposes both `mcp` (client) and `mcp-agent` (server). The NixOS -config in `configs/mcp.nix` references the Nix package path for the -agent binary. +flake exposes both `mcp` (client) and `mcp-agent` (server). Phase E is +moving the agent binary to `/srv/mcp/mcp-agent` on all nodes — NixOS +`ExecStart` will point there instead of a nix store path, and Debian +nodes use the same layout. svc already follows this convention. See +`docs/phase-e-plan.md` for details. ## Flake status @@ -63,9 +67,10 @@ agent binary. | mcias | Yes | mciasctl, mciasgrpcctl | Yes | | | mc-proxy | Yes | mcproxyctl | Yes | | | mcr | Yes | mcrctl | Yes | | -| mcdeploy | Yes | mcdeploy | No | Deprecated, remove from mcpkg.nix | | mcp | Yes | mcp, mcp-agent | Yes | Agent also used by mcp.nix systemd unit | | mcns | No | — | No | Server-only, no client tool yet | | metacrypt | No | — | No | Server-only, no client tool yet | | mcat | No | — | No | Server-only, no client tool yet | +| mcdoc | No | — | No | Server-only, deployed as container | +| mcq | No | — | No | Server-only, document review queue | | mcdsl | No | — | No | Library, no binaries |