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

Reconcile docs: add mcdoc to project map, mark mcdsl gap done

Browse Source 
- CLAUDE.md: add mcdoc to project map and dependency graph
- PLATFORM_EVOLUTION.md: mark gap #1 (mcdsl versioning) as done —
  all services already use tagged versions with no replace directives.
  Add immediate next steps section.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Kyle Isom
2026-03-27 00:27:04 -07:00
parent 1def85f1eb
commit 8c6dd18d49
2 changed files with 29 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CLAUDE.md
View File

@@ -16,6 +16,7 @@ Metacircular is a multi-service personal infrastructure platform. This root repo
| `mcr/` | OCI container registry — integrated with MCIAS for auth and policy-based push/pull | 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 |
| `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 |
| `ca/` | PKI infrastructure and secrets for dev/test (not source code, gitignored) | — |
@@ -30,6 +31,7 @@ mcias (standalone — no MCIAS dependency)
├── metacrypt (uses MCIAS for auth)
├── 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)
└── mcat (tests MCIAS login policies)
```

47
PLATFORM_EVOLUTION.md
View File

@@ -178,24 +178,15 @@ about one node, one mc-proxy, or loopback-only backends.
### What needs to change
#### 1. mcdsl: Proper Module Versioning
#### 1. mcdsl: Proper Module Versioning — DONE
**Gap**: mcdsl is used via `replace` directives and sibling directory
hacks. Docker builds require the source tree to be adjacent. This is
fragile and violates normal Go module conventions.
**Work**:
- Tag mcdsl releases with semver (e.g., `v1.0.0`, `v1.1.0`).
- Remove all `replace` directives from consuming services' `go.mod`
files. Services import mcdsl by URL and version like any other
dependency.
- Docker builds fetch mcdsl via the Go module proxy / Gitea — no local
source tree required.
- `uses_mcdsl` is eliminated from service definitions and build config.
**Depends on**: Gitea module hosting working correctly for
`git.wntrmute.dev/kyle/mcdsl` (it should already — Go modules over
git are standard).
mcdsl is already properly versioned and released:
- Tagged releases: `v0.1.0`, `v1.0.0`, `v1.0.1`
- All consuming services import by URL with pinned versions
(mcr, mcat, mcns, mc-proxy → `v1.0.0`; metacrypt → `v1.0.1`)
- No `replace` directives anywhere
- Docker builds use standard `go mod download`
- `uses_mcdsl` eliminated from service definitions and docs
#### 2. MCP Agent: Port Assignment
@@ -317,7 +308,7 @@ The dependencies form a rough order:
```
Phase A — Independent groundwork (parallel):
#1 mcdsl proper module versioning
#1 mcdsl proper module versioning ✓ DONE
#2 MCP agent port assignment
#5 mc-proxy route persistence
#9 $PORT convention in applications
@@ -337,8 +328,11 @@ Phase D — DNS:
(depends on #8)
```
After Phase A, mcdsl builds are clean and services can be deployed
with agent-assigned ports (manually registered in mc-proxy).
Phase A is partially complete. mcdsl is done. The remaining Phase A
work (#2, #5, #9) can proceed in parallel.
After Phase A, services can be deployed with agent-assigned ports
(manually registered in mc-proxy).
After Phase B, the manual steps are: cert provisioning and DNS. This
is the biggest quality-of-life improvement — no more manual port
@@ -350,6 +344,19 @@ After Phase D, `mcp deploy` is fully declarative.
Each phase is independently useful and deployable.
### Immediate Next Steps
1. **mc-proxy route persistence (#5)** — mc-proxy already has SQLite
and a gRPC API. Persist routes in the database, load on startup.
This unblocks Phase B with no external dependencies.
2. **MCP agent port assignment (#2)** — new service definition parser,
port allocation, `$PORT_*` injection. Can develop in parallel with
#5.
3. **$PORT convention (#9)** — small per-service config change. Can
start incrementally now, but only useful once #2 is deployed.
4. **mcdoc implementation** — fully designed, no platform evolution
dependency. Deployable with a manually assigned port today.
---
## Open Questions