Update platform docs: accuracy audit and module path migration

- 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) <noreply@anthropic.com>
2026-03-27 02:08:45 -07:00
parent 21e2aadeb5
commit 162afc44d5
5 changed files with 45 additions and 32 deletions
--- 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)
 ```

--- 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
 ```
--- 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

--- 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.

 ---

--- 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/<service>
+git.wntrmute.dev/mc/<service>
 ```

 ### 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=<module> \
 		--go-grpc_out=. --go-grpc_opt=module=<module> \
-		proto/<service>/v2/*.proto
+		proto/<service>/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 <token>`
@@ -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 (`<service>`), minimal attack
   surface.
@@ -1054,7 +1054,8 @@ make proto-lint   # if proto files changed

 ### Proto Changes

-1. Edit `.proto` files in `proto/<service>/v2/`.
+1. Edit `.proto` files in `proto/<service>/v<N>/` (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.