mc/metacircular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update platform docs: accuracy audit and module path migration

Browse Source 
- 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>
This commit is contained in:
Kyle Isom
2026-03-27 02:08:45 -07:00
parent 21e2aadeb5
commit 162afc44d5
5 changed files with 45 additions and 32 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
CLAUDE.md
View File

@@ -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 | | `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 | | `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 | | `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) | — | | `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. 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) ├── mc-proxy (uses MCIAS for admin auth)
├── mcr (uses MCIAS for auth + policy) ├── mcr (uses MCIAS for auth + policy)
├── mcdoc (public, no MCIAS — fetches docs from Gitea) ├── 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) └── mcat (tests MCIAS login policies)
``` ```

10
README.md
View File

@@ -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 | | **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 | | **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 | | **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 | | **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. | Planned | | **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, Shared library: **MCDSL** — standard library for all services (auth, db,
config, TLS server, CSRF, snapshots). config, TLS server, CSRF, snapshots).
@@ -63,7 +64,7 @@ workstation) and manages containers via the local runtime. Core infrastructure
│ └───────────┘ │ │ │ │ │ └───────────┘ │ │ │ │
│ ┌───▼┐ ┌──▼─┐ ┌─▼──┐ ┌─────┐ │ │ ┌───▼┐ ┌──▼─┐ ┌─▼──┐ ┌─────┐ │
│ │ α │ │ β │ │ γ │ │ MCP │ │ │ │ α │ │ β │ │ γ │ │ MCP │ │
│ └────┘ └────┘ └────┘ │Slave│ │ │ └────┘ └────┘ └────┘ │Agent│ │
│ └──┬──┘ │ │ └──┬──┘ │
│ ┌────▼───┐│ │ ┌────▼───┐│
│ │Container│ │ │Container│
@@ -97,8 +98,11 @@ metacircular/
├── metacrypt/ Cryptographic service engine ├── metacrypt/ Cryptographic service engine
├── mcr/ Container registry ├── mcr/ Container registry
├── mc-proxy/ TLS proxy and router ├── mc-proxy/ TLS proxy and router
├── mcp/ Control plane (master/agent)
├── mcns/ DNS server
├── mcat/ Login policy tester ├── mcat/ Login policy tester
├── mcdsl/ Standard library (shared packages) ├── mcdsl/ Standard library (shared packages)
├── mcdoc/ Documentation server
├── ca/ PKI infrastructure (dev/test, not source code) ├── ca/ PKI infrastructure (dev/test, not source code)
└── docs/ Platform-wide documentation └── docs/ Platform-wide documentation
``` ```

16
STATUS.md
View File

@@ -17,9 +17,9 @@ deployed on rift, serving authoritative DNS.
| MCIAS | v1.7.0 | Maintenance | Yes | (separate) | | MCIAS | v1.7.0 | Maintenance | Yes | (separate) |
| Metacrypt | v1.0.0 | Production | Yes | rift | | Metacrypt | v1.0.0 | Production | Yes | rift |
| MC-Proxy | v1.0.0 | Maintenance | 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 | — | | 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 | | MCNS | v1.0.0 | Production | Yes | rift |
| MCP | v0.1.0 | Production | Yes | rift | | MCP | v0.1.0 | Production | Yes | rift |
| MCDeploy | v0.1.0 | Active dev | N/A (CLI tool) | — | | MCDeploy | v0.1.0 | Active dev | N/A (CLI tool) | — |
@@ -63,7 +63,7 @@ deployed on rift, serving authoritative DNS.
### MCR — Container Registry ### 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. - **Phase:** Production. Deployed on rift, serving container images.
- **Deployment:** Running on rift as two containers (mcr API + mcr-web), - **Deployment:** Running on rift as two containers (mcr API + mcr-web),
fronted by MC-Proxy on ports 443 (web, L7), 8443 (API, L4), and 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 ### MCDSL — Standard Library
- **Version:** v1.0.0. - **Version:** v1.1.0.
- **Phase:** Stable. All 9 packages implemented and tested (87 tests). Being - **Phase:** Stable. All 9 packages implemented and tested. Being adopted
adopted across the platform. across the platform.
- **Deployment:** N/A (Go library, imported by other services). - **Deployment:** N/A (Go library, imported by other services).
- **Packages:** auth, db, config, httpserver, grpcserver, csrf, web, health, - **Packages:** auth, db, config, httpserver, grpcserver, csrf, web, health,
archive. archive.
- **Adoption:** mcat, mc-proxy, and mcr migrated. metacrypt and mcias - **Adoption:** mcat and mc-proxy on v1.0.0. mcr, mcns, and metacrypt on
pending. v1.1.0. mcias pending.
### MCNS — Networking Service ### MCNS — Networking Service

28
docs/metacircular.md
View File

@@ -107,10 +107,10 @@ that participates in the Metacircular platform.
│ └───────────┘ │ │ │ │ │ └───────────┘ │ │ │ │
│ ┌───▼┐ ┌──▼─┐ ┌─▼──┐ ┌─────┐ │ │ ┌───▼┐ ┌──▼─┐ ┌─▼──┐ ┌─────┐ │
│ │ α │ │ β │ │ γ │ │ MCP │ │ │ │ α │ │ β │ │ γ │ │ MCP │ │
│ └────┘ └────┘ └────┘ │Slave│ │ │ └────┘ └────┘ └────┘ │Agent│ │
│ └──┬──┘ │ │ └──┬──┘ │
│ ┌────▼───┐│ │ ┌────▼───┐│
│ │Docker/ ││ │ │Podman/ ││
│ │etc. ││ │ │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. login time, the service forwards credentials to MCIAS along with this context.
MCIAS evaluates login policy against the service context, verifies credentials, MCIAS evaluates login policy against the service context, verifies credentials,
and returns a bearer token. The MCIAS Go client library 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 (which services run where) is owned by MCP; MCNS translates those assignments
into DNS records. into DNS records.
**What it will provide:** **What it provides:**
- **Internal DNS.** MCNS is authoritative for the internal zones of the - **Internal DNS.** MCNS is authoritative for the internal zones of the
Metacircular network. Three zones serve different purposes: 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 `mcias.svc.mcp.metacircular.net` in `[mcias] server_url`) that survive
migration without config changes. migration without config changes.
**Status:** Not yet implemented. A CoreDNS precursor currently serves the **Status:** Implemented. v1.0.0. Custom Go DNS server deployed on rift,
internal zones (`svc.mcp.metacircular.net` and `mcp.metacircular.net`) as an serving two authoritative zones (`svc.mcp.metacircular.net` and
interim solution until the full MCNS service is built. `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 handles the rest. MCP Master runs on the operator's workstation; agents run on
each managed node. each managed node.
**What it will provide:** **What it provides:**
- **Service registry.** MCP is the source of truth for what is running where. - **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 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 - **Container lifecycle.** Start, stop, restart, and update containers on
nodes. MCP Master issues commands; agents on each node execute them against 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. - **Master/agent architecture.** MCP Master runs on the operator's machine.
Agents run on every managed node, receiving C2 (command and control) from 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 — can deploy them. The systemd unit files exist as a fallback and for bootstrap —
the long-term deployment model is MCP-managed containers. 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.
--- ---

17
engineering-standards.md
View File

@@ -140,12 +140,12 @@ but the top-level skeleton is fixed.
Services hosted on `git.wntrmute.dev` use: Services hosted on `git.wntrmute.dev` use:
``` ```
git.wntrmute.dev/kyle/<service> git.wntrmute.dev/mc/<service>
``` ```
### Shared Libraries (mcdsl) ### 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, standard library — shared packages for auth, database, config,
HTTP/gRPC servers, CSRF, snapshots, and other cross-cutting concerns. 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: conventions. Services import it like any other dependency:
```go ```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: 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:** **Rules:**
@@ -206,7 +206,7 @@ lint:
proto: proto:
protoc --go_out=. --go_opt=module=<module> \ protoc --go_out=. --go_opt=module=<module> \
--go-grpc_out=. --go-grpc_opt=module=<module> \ --go-grpc_out=. --go-grpc_opt=module=<module> \
proto/<service>/v2/*.proto proto/<service>/v1/*.proto
proto-lint: proto-lint:
buf 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. - Client sends credentials to the service's `/v1/auth/login` endpoint.
- The service forwards them to MCIAS via the client library - 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 - 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. client and optionally sets it as a cookie for the web UI.
- Subsequent requests include the token via `Authorization: Bearer <token>` - Subsequent requests include the token via `Authorization: Bearer <token>`
@@ -586,7 +586,7 @@ systemd services. Both paths are first-class.
Multi-stage builds: 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. symbols.
2. **Runtime**: `alpine:3.21`. Non-root user (`<service>`), minimal attack 2. **Runtime**: `alpine:3.21`. Non-root user (`<service>`), minimal attack
surface. surface.
@@ -1054,7 +1054,8 @@ make proto-lint # if proto files changed
### Proto Changes ### 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. 2. Run `make proto` to regenerate Go code.
3. Run `make proto-lint` to check for linting violations and breaking changes. 3. Run `make proto-lint` to check for linting violations and breaking changes.
4. Update REST routes to match the new/changed RPCs. 4. Update REST routes to match the new/changed RPCs.