From 162afc44d58e10d4a3fadfeedf3f68507a9187aa Mon Sep 17 00:00:00 2001 From: Kyle Isom Date: Fri, 27 Mar 2026 02:08:45 -0700 Subject: [PATCH] Update platform docs: accuracy audit and module path migration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - MCNS/MCP status: Planned → Implemented (both deployed on rift) - Add mcp/, mcns/, mcdoc/ to project map and repo structure - Fix MCNS description from CoreDNS precursor to custom Go DNS server - Fix versions: MCR v1.1.0, MCDSL v1.1.0, MCIAS v1.7.0 - Update mcdsl adoption status (metacrypt now migrated) - Fix engineering-standards: Go 1.25 builder, proto v1 conventions - Update PLATFORM_EVOLUTION gap #8 (MCNS API exists) - Migrate all module path references from kyle/ to mc/ org - Fix diagrams: MCP Slave → MCP Agent, Docker → Podman Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 6 ++++-- README.md | 10 +++++++--- STATUS.md | 16 ++++++++-------- docs/metacircular.md | 28 +++++++++++++++++----------- engineering-standards.md | 17 +++++++++-------- 5 files changed, 45 insertions(+), 32 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index d1db766..ecdcbeb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -17,7 +17,8 @@ Metacircular is a multi-service personal infrastructure platform. This root repo | `mcat/` | MCIAS login policy tester — lightweight web app to test and audit login policies | Go | | `mcdsl/` | Standard library — shared packages for auth, db, config, HTTP/gRPC servers, CSRF, snapshots | Go | | `mcdoc/` | Documentation server — renders markdown from Gitea, serves public docs via mc-proxy | Go | -| `mcns/` | Networking service — CoreDNS precursor serving internal DNS zones until full MCNS is built | CoreDNS | +| `mcp/` | Control plane — operator-driven deployment, service registry, container lifecycle (master/agent) | Go | +| `mcns/` | Networking service — custom Go DNS server, authoritative for internal zones | Go | | `ca/` | PKI infrastructure and secrets for dev/test (not source code, gitignored) | — | Each subproject has its own `CLAUDE.md`, `ARCHITECTURE.md`, `Makefile`, and `go.mod`. When working in a subproject, read its own CLAUDE.md first. @@ -32,7 +33,8 @@ mcias (standalone — no MCIAS dependency) ├── mc-proxy (uses MCIAS for admin auth) ├── mcr (uses MCIAS for auth + policy) ├── mcdoc (public, no MCIAS — fetches docs from Gitea) - ├── mcns (will use MCIAS for auth; CoreDNS precursor for now) + ├── mcp (uses MCIAS for auth; orchestrates deployment and lifecycle) + ├── mcns (uses MCIAS for auth; authoritative DNS for internal zones) └── mcat (tests MCIAS login policies) ``` diff --git a/README.md b/README.md index 19ba29e..8d3f1a6 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,9 @@ lives in [docs/metacircular.md](docs/metacircular.md). | **Metacrypt** | Cryptographic services — PKI/CA, transit encryption, encrypted secret storage behind a seal/unseal barrier. Issues TLS certificates for the platform. | Implemented | | **MCR** | Container registry — OCI-compliant image storage with MCIAS auth and policy-controlled push/pull. | Implemented | | **MC-Proxy** | Node ingress — TLS proxy and router. L4 passthrough or L7 terminating (per-route), PROXY protocol, firewall with rate limiting and GeoIP. | Implemented | -| **MCNS** | Networking — DNS and address management for the platform. | Planned | -| **MCP** | Control plane — operator-driven deployment, service registry, data transfer, master/agent container lifecycle. | Planned | +| **MCNS** | Networking — authoritative DNS for internal platform zones, upstream forwarding. | Implemented | +| **MCP** | Control plane — operator-driven deployment, service registry, data transfer, master/agent container lifecycle. | Implemented | +| **MCDoc** | Documentation server — renders markdown from Gitea, serves public docs. | In progress | Shared library: **MCDSL** — standard library for all services (auth, db, config, TLS server, CSRF, snapshots). @@ -63,7 +64,7 @@ workstation) and manages containers via the local runtime. Core infrastructure │ └───────────┘ │ │ │ │ │ ┌───▼┐ ┌──▼─┐ ┌─▼──┐ ┌─────┐ │ │ │ α │ │ β │ │ γ │ │ MCP │ │ - │ └────┘ └────┘ └────┘ │Slave│ │ + │ └────┘ └────┘ └────┘ │Agent│ │ │ └──┬──┘ │ │ ┌────▼───┐│ │ │Container│ @@ -97,8 +98,11 @@ metacircular/ ├── metacrypt/ Cryptographic service engine ├── mcr/ Container registry ├── mc-proxy/ TLS proxy and router +├── mcp/ Control plane (master/agent) +├── mcns/ DNS server ├── mcat/ Login policy tester ├── mcdsl/ Standard library (shared packages) +├── mcdoc/ Documentation server ├── ca/ PKI infrastructure (dev/test, not source code) └── docs/ Platform-wide documentation ``` diff --git a/STATUS.md b/STATUS.md index 4e83319..fe79d80 100644 --- a/STATUS.md +++ b/STATUS.md @@ -17,9 +17,9 @@ deployed on rift, serving authoritative DNS. | MCIAS | v1.7.0 | Maintenance | Yes | (separate) | | Metacrypt | v1.0.0 | Production | Yes | rift | | MC-Proxy | v1.0.0 | Maintenance | Yes | rift | -| MCR | v1.0.0 | Production | Yes | rift | +| MCR | v1.1.0 | Production | Yes | rift | | MCAT | v1.0.0 | Complete | Unknown | — | -| MCDSL | v1.0.0 | Stable | N/A (library) | — | +| MCDSL | v1.1.0 | Stable | N/A (library) | — | | MCNS | v1.0.0 | Production | Yes | rift | | MCP | v0.1.0 | Production | Yes | rift | | MCDeploy | v0.1.0 | Active dev | N/A (CLI tool) | — | @@ -63,7 +63,7 @@ deployed on rift, serving authoritative DNS. ### MCR — Container Registry -- **Version:** v1.0.0. All implementation phases complete. +- **Version:** v1.1.0. All implementation phases complete. - **Phase:** Production. Deployed on rift, serving container images. - **Deployment:** Running on rift as two containers (mcr API + mcr-web), fronted by MC-Proxy on ports 443 (web, L7), 8443 (API, L4), and @@ -85,14 +85,14 @@ deployed on rift, serving authoritative DNS. ### MCDSL — Standard Library -- **Version:** v1.0.0. -- **Phase:** Stable. All 9 packages implemented and tested (87 tests). Being - adopted across the platform. +- **Version:** v1.1.0. +- **Phase:** Stable. All 9 packages implemented and tested. Being adopted + across the platform. - **Deployment:** N/A (Go library, imported by other services). - **Packages:** auth, db, config, httpserver, grpcserver, csrf, web, health, archive. -- **Adoption:** mcat, mc-proxy, and mcr migrated. metacrypt and mcias - pending. +- **Adoption:** mcat and mc-proxy on v1.0.0. mcr, mcns, and metacrypt on + v1.1.0. mcias pending. ### MCNS — Networking Service diff --git a/docs/metacircular.md b/docs/metacircular.md index 337288c..65214ff 100644 --- a/docs/metacircular.md +++ b/docs/metacircular.md @@ -107,10 +107,10 @@ that participates in the Metacircular platform. │ └───────────┘ │ │ │ │ │ ┌───▼┐ ┌──▼─┐ ┌─▼──┐ ┌─────┐ │ │ │ α │ │ β │ │ γ │ │ MCP │ │ - │ └────┘ └────┘ └────┘ │Slave│ │ + │ └────┘ └────┘ └────┘ │Agent│ │ │ └──┬──┘ │ │ ┌────▼───┐│ - │ │Docker/ ││ + │ │Podman/ ││ │ │etc. ││ │ └────────┘│ └──────────────────────────────────────────────┘ @@ -202,9 +202,10 @@ section with the MCIAS server URL, a `service_name`, and optional `tags`. At login time, the service forwards credentials to MCIAS along with this context. MCIAS evaluates login policy against the service context, verifies credentials, and returns a bearer token. The MCIAS Go client library -(`git.wntrmute.dev/kyle/mcias/clients/go`) handles this flow. +(`git.wntrmute.dev/mc/mcias/clients/go`) handles this flow. -**Status:** Implemented. v1.0.0 complete. +**Status:** Implemented. v1.7.0. Feature-complete with active refinement +(WebAuthn/FIDO2 passkeys, TOTP 2FA, service-context login policies). --- @@ -343,7 +344,7 @@ as the name resolution layer for the Metacircular network. Service discovery (which services run where) is owned by MCP; MCNS translates those assignments into DNS records. -**What it will provide:** +**What it provides:** - **Internal DNS.** MCNS is authoritative for the internal zones of the Metacircular network. Three zones serve different purposes: @@ -374,9 +375,10 @@ services can use stable DNS names in their configs (e.g., `mcias.svc.mcp.metacircular.net` in `[mcias] server_url`) that survive migration without config changes. -**Status:** Not yet implemented. A CoreDNS precursor currently serves the -internal zones (`svc.mcp.metacircular.net` and `mcp.metacircular.net`) as an -interim solution until the full MCNS service is built. +**Status:** Implemented. v1.0.0. Custom Go DNS server deployed on rift, +serving two authoritative zones (`svc.mcp.metacircular.net` and +`mcp.metacircular.net`) plus upstream forwarding. REST + gRPC APIs with +MCIAS auth. Records stored in SQLite. --- @@ -387,7 +389,7 @@ deployment model is operator-driven: the user says "deploy service α" and MCP handles the rest. MCP Master runs on the operator's workstation; agents run on each managed node. -**What it will provide:** +**What it provides:** - **Service registry.** MCP is the source of truth for what is running where. It tracks every service, which node it's on, and its current state. Other @@ -422,7 +424,7 @@ each managed node. - **Container lifecycle.** Start, stop, restart, and update containers on nodes. MCP Master issues commands; agents on each node execute them against - the local container runtime (Docker, etc.). + the local container runtime (rootless Podman). - **Master/agent architecture.** MCP Master runs on the operator's machine. Agents run on every managed node, receiving C2 (command and control) from @@ -450,7 +452,11 @@ services it depends on. can deploy them. The systemd unit files exist as a fallback and for bootstrap — the long-term deployment model is MCP-managed containers. -**Status:** Not yet implemented. +**Status:** Implemented. v0.1.0. Deployed on rift managing all platform +containers. Two components — `mcp` CLI (operator workstation) and +`mcp-agent` (per-node daemon with SQLite registry, rootless Podman, +monitoring with drift/flap detection). gRPC-only (no REST). 12 RPCs, +15 CLI commands. --- diff --git a/engineering-standards.md b/engineering-standards.md index 8c7b843..7752983 100644 --- a/engineering-standards.md +++ b/engineering-standards.md @@ -140,12 +140,12 @@ but the top-level skeleton is fixed. Services hosted on `git.wntrmute.dev` use: ``` -git.wntrmute.dev/kyle/ +git.wntrmute.dev/mc/ ``` ### Shared Libraries (mcdsl) -The `mcdsl` module (`git.wntrmute.dev/kyle/mcdsl`) is the platform's +The `mcdsl` module (`git.wntrmute.dev/mc/mcdsl`) is the platform's standard library — shared packages for auth, database, config, HTTP/gRPC servers, CSRF, snapshots, and other cross-cutting concerns. @@ -153,13 +153,13 @@ mcdsl is a normal Go module, versioned and tagged per standard SDLC conventions. Services import it like any other dependency: ```go -import "git.wntrmute.dev/kyle/mcdsl/auth" +import "git.wntrmute.dev/mc/mcdsl/auth" ``` And reference it in `go.mod` with a tagged version: ``` -require git.wntrmute.dev/kyle/mcdsl v1.2.0 +require git.wntrmute.dev/mc/mcdsl v1.2.0 ``` **Rules:** @@ -206,7 +206,7 @@ lint: proto: protoc --go_out=. --go_opt=module= \ --go-grpc_out=. --go-grpc_opt=module= \ - proto//v2/*.proto + proto//v1/*.proto proto-lint: buf lint @@ -296,7 +296,7 @@ Access Service). No service maintains its own user database. - Client sends credentials to the service's `/v1/auth/login` endpoint. - The service forwards them to MCIAS via the client library - (`git.wntrmute.dev/kyle/mcias/clients/go`). + (`git.wntrmute.dev/mc/mcias/clients/go`). - On success, MCIAS returns a bearer token. The service returns it to the client and optionally sets it as a cookie for the web UI. - Subsequent requests include the token via `Authorization: Bearer ` @@ -586,7 +586,7 @@ systemd services. Both paths are first-class. Multi-stage builds: -1. **Builder**: `golang:1.23-alpine`. Compile with `CGO_ENABLED=0`, strip +1. **Builder**: `golang:1.25-alpine`. Compile with `CGO_ENABLED=0`, strip symbols. 2. **Runtime**: `alpine:3.21`. Non-root user (``), minimal attack surface. @@ -1054,7 +1054,8 @@ make proto-lint # if proto files changed ### Proto Changes -1. Edit `.proto` files in `proto//v2/`. +1. Edit `.proto` files in `proto//v/` (start at v1; only + create v2 for breaking changes). 2. Run `make proto` to regenerate Go code. 3. Run `make proto-lint` to check for linting violations and breaking changes. 4. Update REST routes to match the new/changed RPCs.