Add mcdeploy to project maps, update MCDoc status

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

CLAUDE.md

@@ -18,8 +18,10 @@ Metacircular is a multi-service personal infrastructure platform. This root repo
 | `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 |
 | `mcp/` | Control plane — operator-driven deployment, service registry, container lifecycle (master/agent) | Go |
+| `mcdeploy/` | Deployment CLI — tactical bridge tool for build, push, deploy operations | 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) | — |
+| `docs/` | Platform-wide documentation (architecture overview, deployment guide) | Markdown |
 
 Each subproject has its own `CLAUDE.md`, `ARCHITECTURE.md`, `Makefile`, and `go.mod`. When working in a subproject, read its own CLAUDE.md first.
 

README.md

@@ -25,7 +25,8 @@ lives in [docs/metacircular.md](docs/metacircular.md).
 | **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 — 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 |
+| **MCDoc** | Documentation server — renders markdown from Gitea, serves public docs. | Implemented |
+| **MCDeploy** | Deployment CLI — single-binary tool for build, push, deploy, cert renewal, and status. Tactical bridge tool while MCP capabilities mature. | Active dev |
 
 Shared library: **MCDSL** — standard library for all services (auth, db,
 config, TLS server, CSRF, snapshots).
@@ -102,6 +103,7 @@ metacircular/
 ├── mcns/           DNS server
 ├── mcat/           Login policy tester
 ├── mcdsl/          Standard library (shared packages)
+├── mcdeploy/       Deployment CLI tool
 ├── mcdoc/          Documentation server
 ├── ca/             PKI infrastructure (dev/test, not source code)
 └── docs/           Platform-wide documentation

STATUS.md

@@ -1,6 +1,6 @@
 # Metacircular Platform Status
 
-Last updated: 2026-03-26
+Last updated: 2026-03-27
 
 ## Platform Overview
 
@@ -16,12 +16,13 @@ deployed on rift, serving authoritative DNS.
 |---------|---------|------------|----------|------|
 | MCIAS | v1.8.0 | Maintenance | Yes | (separate) |
 | Metacrypt | v1.1.0 | Production | Yes | rift |
-| MC-Proxy | v1.1.0 | Maintenance | Yes | rift |
+| MC-Proxy | v1.2.1 | Maintenance | Yes | rift |
 | MCR | v1.2.0 | Production | Yes | rift |
 | MCAT | v1.1.0 | Complete | Unknown | — |
 | MCDSL | v1.2.0 | Stable | N/A (library) | — |
 | MCNS | v1.1.0 | Production | Yes | rift |
-| MCP | v0.3.0 | Production | Yes | rift |
+| MCDoc | v0.1.0 | Production | Yes | rift |
+| MCP | v0.4.0 | Production | Yes | rift |
 | MCDeploy | v0.2.0 | Active dev | N/A (CLI tool) | — |
 
 ## Service Details
@@ -52,12 +53,12 @@ deployed on rift, serving authoritative DNS.
 
 ### MC-Proxy — TLS Proxy and Router
 
-- **Version:** v1.1.0. Phases 1-8 complete.
+- **Version:** v1.2.1.
 - **Phase:** Maintenance. Stable and actively routing traffic on rift.
 - **Deployment:** Running on rift. Fronts Metacrypt, MCR, and sgard on ports
   443, 8443, and 9443. Prometheus metrics on 127.0.0.1:9091.
-- **Recent work:** MCR route additions, Nix flake, L7 backend cert handling,
-  Prometheus metrics, L7 policies.
+- **Recent work:** Route persistence (SQLite), idempotent AddRoute (upsert),
+  golangci-lint v2 compliance, module path migration to mc/ org.
 - **Artifacts:** systemd units (service + backup timer), Docker Compose
   (standard + rift), install and backup scripts, rift config.
 
@@ -104,19 +105,33 @@ deployed on rift, serving authoritative DNS.
 - **Artifacts:** Dockerfile, Docker Compose (rift), MCP service definition,
   systemd units, install script, example config.
 
+### MCDoc — Documentation Server
+
+- **Version:** v0.1.0.
+- **Phase:** Production. Fetches and renders markdown documentation from Gitea.
+- **Deployment:** Running on rift as a container, fronted by MC-Proxy on
+  port 443 (L7).
+- **Recent work:** Initial implementation, Gitea content fetching, goldmark
+  rendering with syntax highlighting, webhook-driven refresh.
+- **Artifacts:** Dockerfile, MCP service definition.
+
 ### MCP — Control Plane
 
-- **Version:** v0.3.0.
-- **Phase:** Production. Phases 0-4 complete. Deployed to rift, managing all
-  platform containers.
+- **Version:** v0.4.0.
+- **Phase:** Production. Phases 0-4 complete. Phase C (automated TLS cert
+  provisioning) implemented. Deployed to rift, managing all platform containers.
 - **Deployment:** Running on rift. Agent as systemd service under `mcp` user
   with rootless podman. Manages metacrypt, mc-proxy, mcr, and mcns containers.
 - **Architecture:** Two components — `mcp` CLI (thin client on vade) and
   `mcp-agent` (per-node daemon with SQLite registry, podman management,
-  monitoring with drift/flap detection). gRPC-only (no REST).
+  monitoring with drift/flap detection, route registration with mc-proxy during
+  deploy/stop, automated TLS cert provisioning for L7 routes via Metacrypt CA).
+  gRPC-only (no REST).
 - **Recent work:** Full v1 implementation (12 RPCs, 15 CLI commands),
   deployment to rift, container migration from kyle→mcp user, service
-  definition authoring.
+  definition authoring. Phase C automated TLS cert provisioning for L7 routes,
+  mc-proxy route registration during deploy, mc-proxy dependency updated to
+  v1.2.0, module path migration.
 - **Artifacts:** systemd service (NixOS), TLS cert from Metacrypt, service
   definition files, design docs.
 

docs/metacircular.md

@@ -48,11 +48,11 @@ the spec disagree, one of them has a bug.
 
 ## High-Level Overview
 
-Metacircular infrastructure is built from six core components, plus a shared
-standard library (**MCDSL**) that provides the common patterns all services
-depend on (auth integration, database setup, config loading, HTTP/gRPC server
-bootstrapping, CSRF, web session management, health checks, snapshots, and
-service directory archiving):
+Metacircular infrastructure is built from six core components and a
+documentation server, plus a shared standard library (**MCDSL**) that provides
+the common patterns all services depend on (auth integration, database setup,
+config loading, HTTP/gRPC server bootstrapping, CSRF, web session management,
+health checks, snapshots, and service directory archiving):
 
 - **MCIAS** — Identity and access. The root of trust for all other services.
   Handles authentication, token issuance, role management, and login policy
@@ -75,6 +75,10 @@ service directory archiving):
   accepts outside connections, and routes them to the correct service — either
   as raw TCP passthrough or via TLS-terminating HTTP/2 reverse proxy.
 
+- **MCDoc** — Documentation server. Fetches markdown from Gitea repositories,
+  renders HTML with syntax highlighting, serves a navigable documentation site.
+  Public-facing, no MCIAS authentication required.
+
 These components form a dependency graph rooted at MCIAS:
 
 ```
@@ -204,7 +208,7 @@ MCIAS evaluates login policy against the service context, verifies credentials,
 and returns a bearer token. The MCIAS Go client library
 (`git.wntrmute.dev/mc/mcias/clients/go`) handles this flow.
 
-**Status:** Implemented. v1.7.0. Feature-complete with active refinement
+**Status:** Implemented. v1.8.0. Feature-complete with active refinement
 (WebAuthn/FIDO2 passkeys, TOTP 2FA, service-context login policies).
 
 ---
@@ -255,7 +259,7 @@ core.
 operations on which engine mounts. Priority-based evaluation, default deny,
 admin bypass. See Metacrypt's `POLICY.md` for the full model.
 
-**Status:** Implemented. All four engine types complete — CA (with ACME
+**Status:** Implemented. v1.1.0. All four engine types complete — CA (with ACME
 support), SSH CA, transit encryption, and user-to-user encryption.
 
 ---
@@ -286,7 +290,7 @@ serves the container images that MCP deploys across the platform.
 is scheduled, MCP tells the node's agent which image to pull and where to get
 it. MCR sits behind an MC-Proxy instance for TLS routing.
 
-**Status:** Implemented. Phase 13 (deployment artifacts) complete.
+**Status:** Implemented. v1.2.0. All implementation phases complete.
 
 ---
 
@@ -333,7 +337,9 @@ two instances — an edge proxy on a public VPS and an origin proxy on the
 private network, connected over the overlay with PROXY protocol preserving
 client IPs across the hop.
 
-**Status:** Implemented.
+**Status:** Implemented. v1.2.1. Route state persisted in SQLite with
+write-through semantics. gRPC admin API with idempotent AddRoute for runtime
+route management.
 
 ---
 
@@ -375,7 +381,7 @@ 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:** Implemented. v1.0.0. Custom Go DNS server deployed on rift,
+**Status:** Implemented. v1.1.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.
@@ -452,11 +458,14 @@ 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:** Implemented. v0.1.0. Deployed on rift managing all platform
-containers. Two components — `mcp` CLI (operator workstation) and
+**Status:** Implemented. v0.4.0. Deployed on rift managing all platform
+containers. Route declarations with automatic port allocation (`$PORT` /
+`$PORT_<NAME>` env vars passed to containers). MC-Proxy route registration
+during deploy and stop. Automated TLS cert provisioning for L7 routes via
+Metacrypt CA (Phase C). 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.
+monitoring with drift/flap detection). gRPC-only (no REST). 12+ RPCs,
+15+ CLI commands.
 
 ---
 
@@ -663,20 +672,22 @@ renew certificates programmatically.
 
 ### How Services Get Certificates Today
 
-Currently, certificates are provisioned through Metacrypt's **REST API or web
-UI** and placed into each service's `/srv/<service>/certs/` directory. This is
-a manual process — the operator issues a certificate, downloads it, and
-deploys the files. The ACME client library exists but is not yet integrated
-into any service.
+For services deployed via MCP with L7 routes, certificates are provisioned
+automatically during deploy — MCP uses the Metacrypt ACME client library to
+obtain certs and transfers them to the node. For other services and during
+bootstrap, certificates are provisioned through Metacrypt's **REST API or web
+UI** and placed into each service's `/srv/<service>/certs/` directory manually.
 
-### How It Will Work With MCP
+### How MCP Automates Certificates
 
-MCP is the natural place to automate certificate provisioning:
+MCP automates certificate provisioning for deploy workflows, with renewal and
+migration automation planned:
 
-- **Initial deploy.** When MCP deploys a new service, it can provision a
-  certificate from Metacrypt (via the ACME client library or the REST API),
-  transfer the cert and key to the node as part of the config push to
-  `/srv/<service>/certs/`, and start the service with valid TLS material.
+- **Initial deploy.** When MCP deploys a new service, it provisions a
+  certificate from Metacrypt (via the ACME client library), transfers the cert
+  and key to the node as part of the config push to `/srv/<service>/certs/`,
+  and starts the service with valid TLS material. For L7 routes, MCP also
+  provisions a TLS certificate for MC-Proxy's termination endpoint.
 
 - **Renewal.** MCP knows what services are running and when their certificates
   expire. It can renew certificates before expiry by re-running the ACME flow
@@ -689,10 +700,8 @@ MCP is the natural place to automate certificate provisioning:
   for the new name.
 
 - **MC-Proxy L7 routes.** MC-Proxy's L7 mode requires certificate/key pairs
-  for TLS termination. MCP (or the operator) can provision these from
-  Metacrypt and push them to MC-Proxy's cert directory. MC-Proxy's
-  architecture doc lists ACME integration and Metacrypt key storage as future
-  work.
+  for TLS termination. MCP provisions these from Metacrypt during deploy and
+  pushes them to the node alongside the route registration.
 
 ### Trust Distribution
 
@@ -793,8 +802,13 @@ Operator workstation (vade)
          │
          ├── Scheduling: select Node C (best fit)
          │
-         ├── Provision TLS certificate from Metacrypt
-         │     (ACME flow or REST API)
+         ├── Port assignment: allocate a free host port for each
+         │     declared route (passed as $PORT / $PORT_<NAME> env vars)
+         │
+         ├── Provision TLS certificate from Metacrypt CA
+         │     (ACME client library) for the service
+         │     — for L7 routes, also provision a cert for MC-Proxy
+         │       TLS termination
          │
          ├── C2 to Node C agent:
          │     1. Create /srv/α/ directory structure
@@ -802,15 +816,15 @@ Operator workstation (vade)
          │     3. Transfer TLS cert+key → /srv/α/certs/
          │     4. Transfer root CA cert → /srv/α/certs/ca.pem
          │     5. Pull image from MCR
-         │     6. Start container
+         │     6. Start container with $PORT / $PORT_<NAME> env vars
+         │
+         ├── Register routes with MC-Proxy
+         │     (gRPC AddRoute for each declared route)
          │
          ├── Update service registry: α → Node C
          │
-         ├── Push DNS update to MCNS:
-         │     α.svc.mcp.metacircular.net → Node C address
-         │
-         └── (Optionally) update MC-Proxy route table
-              if α needs external ingress
+         └── Push DNS update to MCNS:
+               α.svc.mcp.metacircular.net → Node C address
 ```
 
 ### 4. Migration

docs/packaging-and-deployment.md

@@ -592,7 +592,8 @@ For reference, these services are operational on the platform:
 |---------|---------|------|---------|
 | MCIAS | v1.8.0 | (separate) | Identity and access |
 | Metacrypt | v1.1.0 | rift | Cryptographic service, PKI/CA |
-| MC-Proxy | v1.1.0 | rift | TLS proxy and router |
+| MC-Proxy | v1.2.1 | rift | TLS proxy and router |
 | MCR | v1.2.0 | rift | Container registry |
 | MCNS | v1.1.0 | rift | Authoritative DNS |
-| MCP | v0.3.0 | rift | Control plane agent |
+| MCDoc | v0.1.0 | rift | Documentation server |
+| MCP | v0.4.0 | rift | Control plane agent |