Organize docs under docs directory

h4x3rotab · h4x3rotab · commit 27743b56c188 · 2026-05-23T09:26:54.000Z
diff --git a/README.md b/README.md
@@ -392,7 +392,7 @@ The policy checks include:
 If the evidence matches, the workload receives scoped service identity.
 If it does not match, it cannot join the service layer.
 
-See [`ATTESTATION.md`](ATTESTATION.md) for the exact evidence format and
+See [`docs/attestation.md`](docs/attestation.md) for the exact evidence format and
 verification flow.
 
 ## How It Works
@@ -408,7 +408,7 @@ standard infrastructure:
 - a small peer transport so CVMs can talk privately across the provider
   network.
 
-Read [`ARCHITECTURE.md`](ARCHITECTURE.md) when you want the lower-level
+Read [`docs/architecture.md`](docs/architecture.md) when you want the lower-level
 design.
 
 ## Development
@@ -445,14 +445,16 @@ docker build -t service-mesh-mesh-sidecar-check -f mesh-sidecar/Dockerfile .
 
 ## More Docs
 
-- [`ATTESTATION.md`](ATTESTATION.md): trust flow and evidence checks.
-- [`ARCHITECTURE.md`](ARCHITECTURE.md): lower-level network and service
+- [`docs/attestation.md`](docs/attestation.md): trust flow and evidence checks.
+- [`docs/architecture.md`](docs/architecture.md): lower-level network and service
   design.
-- [`FAILOVER.md`](FAILOVER.md): failover tests and measured recovery
+- [`docs/failover.md`](docs/failover.md): failover tests and measured recovery
   times.
-- [`ROBUSTNESS.md`](ROBUSTNESS.md): failure modes and mitigations.
-- [`PUBLISHING.md`](PUBLISHING.md): image publishing and provenance.
-- [`PROGRESS.md`](PROGRESS.md): current status and remaining work.
+- [`docs/robustness.md`](docs/robustness.md): failure modes and mitigations.
+- [`docs/publishing.md`](docs/publishing.md): image publishing and provenance.
+- [`docs/progress.md`](docs/progress.md): current status and remaining work.
+- [`docs/design/README.md`](docs/design/README.md): design notes and handoff
+  docs for open or historical implementation work.
 
 ## Current Limits
 
diff --git a/bootstrap-secrets/main.go b/bootstrap-secrets/main.go
@@ -77,7 +77,7 @@ func main() {
 	// so per-CVM derivation can't produce the cluster-wide identical
 	// material those consumers need. They come from Terraform-
 	// generated env instead. See cluster.tf and
-	// design/attestation-admission.md for the principled fix.
+	// ../docs/design/attestation-admission.md for the principled fix.
 	//
 	// What's still derived here is intentionally narrow:
 	//   turn:    handed to mesh-conn for coturn auth (the actual
diff --git a/cluster-example/cluster.tf b/cluster-example/cluster.tf
@@ -38,7 +38,7 @@ provider "phala" {}
 # These three secrets MUST be byte-identical across every CVM that
 # joins the cluster (gossip auth, Patroni replication, Patroni superuser).
 # The principled answer is "derive them in the TEE, never let a human
-# touch them" — see attestation-admission.md.
+# touch them" — see ../docs/design/attestation-admission.md.
 #
 # Migration note: in the v0.3 MIG model, all coordinators share ONE
 # `app_id` and each workload group app has its own `app_id`, so within
diff --git a/cluster-example/rollout.sh b/cluster-example/rollout.sh
@@ -164,7 +164,7 @@ What we're waiting on:
     health, snapshot, and leader-transfer scaffolding below while using
     the provider's app-revision fan-out path deliberately.
 
-See ./PROGRESS.md for current status.
+See ../docs/progress.md for current status.
 ==============================================================================
 
 EOF
diff --git a/coordinator/docker-compose.yaml b/coordinator/docker-compose.yaml
@@ -4,7 +4,7 @@
 #
 # Image tags pin to `:latest` from GHCR for clarity here; pin to
 # `:sha-<full-sha>` (or a digest) for production deploys — see
-# PUBLISHING.md.
+# ../docs/publishing.md.
 
 services:
   coturn:
diff --git a/docs/architecture.md b/docs/architecture.md
@@ -438,7 +438,7 @@ instead of a generic TCP connect check.
   generated in Terraform and broadcast via env; attestation-rooted
   admission will replace this with TEE-derived material). RPC is
   plaintext. Both are confined to inside the overlay, but a full
-  setup would also configure TLS for RPC. See [ROBUSTNESS.md](ROBUSTNESS.md).
+  setup would also configure TLS for RPC. See [robustness.md](robustness.md).
 
 ## What's nice about this shape
 
diff --git a/docs/attestation.md b/docs/attestation.md
diff --git a/docs/design/README.md b/docs/design/README.md
@@ -4,8 +4,9 @@ This directory holds design briefs and handoff notes for open or
 partially landed work on `service-mesh`. Each doc is structured
 so an agent (or a person) can pick it up cold and continue.
 
-The user-facing docs (`README.md`, `ARCHITECTURE.md`, `FAILOVER.md`,
-`PUBLISHING.md`, `ROBUSTNESS.md`) describe what's *shipping today*.
+The user-facing docs (`../../README.md`, `../architecture.md`,
+`../failover.md`, `../publishing.md`, `../robustness.md`)
+describe what's *shipping today*.
 This directory describes what's *next*. They're intentionally
 separated so a user landing on the example doesn't get a roadmap
 in their face.
diff --git a/docs/design/attestation-admission.md b/docs/design/attestation-admission.md
@@ -1,7 +1,7 @@
 # Design: Attestation Admission Follow-Ups
 
 Phase 1 admission is implemented. The shipped path is documented in
-`../ATTESTATION.md` and enforced by:
+`../attestation.md` and enforced by:
 
 - Terraform preflight-derived `compose_hash` policy.
 - Terraform-declared workload identities and optional `peer_id`.
diff --git a/docs/design/terraform-slot-api.md b/docs/design/terraform-slot-api.md
diff --git a/docs/design/workload-groups-refactor.md b/docs/design/workload-groups-refactor.md
diff --git a/docs/failover.md b/docs/failover.md
@@ -219,7 +219,7 @@ A few-MB pgdata transferred in ~18 seconds end-to-end. The dataset
 is small enough that handshake/startup overhead dominates, so this
 trace should be read as a recovery-path check rather than a bandwidth
 benchmark. For a current full service-mesh datapoint, see
-`ARCHITECTURE.md`.
+`architecture.md`.
 
 The path itself is the proof point: Patroni correctly detects empty
 pgdata, picks `bootstrap from leader` (not WAL replay), pulls the full
diff --git a/docs/progress.md b/docs/progress.md
diff --git a/docs/publishing.md b/docs/publishing.md
diff --git a/docs/robustness.md b/docs/robustness.md
@@ -201,7 +201,7 @@ path. It is **NOT a SPOF for established direct traffic**.
 - peer VIPs `127.50.0.<vip>` (one per peer, in PEERS_JSON)
 - the runtime port allowlist from `MESH_CONN_ALLOWLIST`
   (generated by `mesh-sidecar/entrypoint.sh`, deliberately small —
-  see ARCHITECTURE.md)
+  see architecture.md)
 - the 3-byte stream header (tag, port-uint16-BE)
 - the per-stream pumps (UDP length-prefix, TCP raw splice)
 - one accept-loop per peer pair to demux incoming streams
@@ -315,7 +315,7 @@ depth.
   operational.
 - **Real registry** — Sigstore-attested GHCR images via
   `.github/workflows/publish.yml`. See
-  `PUBLISHING.md`.
+  `publishing.md`.
 - **Gossip key wired in (workaround)** — `cluster.tf`
   generates a `random_bytes` and broadcasts it to every CVM via
   env; `mesh-sidecar/entrypoint.sh` passes it as
@@ -428,7 +428,7 @@ Honest answer: not really. Each layer earns its place.
 - **Consul's UDP-and-TCP-on-the-same-port** forces a multiplexer
   over the punched path.
 - QUIC is the obvious multiplexer over a lossy UDP underlay (yamux
-  was tried and discarded — see ARCHITECTURE.md).
+  was tried and discarded — see architecture.md).
 - **Per-peer loopback VIPs** are the *one* clever-and-ours
   technique, and they exist because Consul's own protocol assumes
   every peer can be reached at a stable address. The peer-VIP plane
diff --git a/mesh-conn/main.go b/mesh-conn/main.go
@@ -55,7 +55,7 @@
 // congestion control, and stream-multiplexing — it's exactly what a
 // lossy UDP underlay needs. The previous yamux build died at 3KB-260KB
 // depending on path; current service-mesh bandwidth is documented in
-// ARCHITECTURE.md from real-env benchmarks.
+// docs/architecture.md from real-env benchmarks.
 
 package main
 
@@ -486,7 +486,7 @@ func (m *Mesh) runPeerLink(ctx context.Context, peer Peer) {
 // lexicographically SMALLER id retries after 2 s, the larger-id side
 // after 5 s. The asymmetry exists to break the convergence bug where
 // two peers indefinitely supersede each other's in-flight handshakes
-// on near-simultaneous restart — see ROBUSTNESS.md "ICE auth-race
+// on near-simultaneous restart — see docs/robustness.md "ICE auth-race
 // convergence" for the failure analysis.
 //
 // Mechanism: with a fixed retry both peers republish auth at the
diff --git a/mesh-sidecar/entrypoint.sh b/mesh-sidecar/entrypoint.sh
@@ -208,7 +208,7 @@ CONSUL_ARGS=(
   -hcl='connect { enabled = true }'
   # WORKAROUND: GOSSIP_KEY is generated in Terraform and broadcast
   # to every CVM via env. Attestation-rooted admission will replace
-  # this with TEE-rooted material — see design/attestation-admission.md.
+  # this with TEE-rooted material — see ../docs/design/attestation-admission.md.
   -encrypt="${GOSSIP_KEY:?GOSSIP_KEY required}"
   -log-level=INFO
 )
@@ -592,7 +592,7 @@ HCL
 
     # Default-allow intentions per parent. Tightening this to per-pair
     # allow + default-deny is straightforward but out of scope here;
-    # see design/attestation-admission.md for the longer-term shape.
+    # see ../docs/design/attestation-admission.md for the longer-term shape.
     jq -r '[.[].parent] | unique | .[]' <<<"$MESH_ROUTES_JSON" | while IFS= read -r parent; do
       [ -z "$parent" ] && continue
       CONSUL_HTTP_TOKEN="${CONSUL_MANAGEMENT_TOKEN:-}" consul config write - <<HCL || true
diff --git a/patroni/entrypoint.sh b/patroni/entrypoint.sh
@@ -12,7 +12,7 @@
 # Terraform-generated env (PATRONI_SUPERUSER_PW, PATRONI_REPLICATION_PW)
 # broadcast identically to every postgres CVM. Attestation-rooted admission
 # will replace this with TEE-rooted material; see
-# design/attestation-admission.md.
+# ../docs/design/attestation-admission.md.
 
 set -e
 

Original file line number	Diff line number	Diff line change
`@@ -38,7 +38,7 @@ provider "phala" {}`
`38`	`38`	`# These three secrets MUST be byte-identical across every CVM that`
`39`	`39`	`# joins the cluster (gossip auth, Patroni replication, Patroni superuser).`
`40`	`40`	`# The principled answer is "derive them in the TEE, never let a human`
`41`		`-# touch them" — see attestation-admission.md.`
	`41`	`+# touch them" — see ../docs/design/attestation-admission.md.`
`42`	`42`	`#`
`43`	`43`	`# Migration note: in the v0.3 MIG model, all coordinators share ONE`
`44`	`44`	# `app_id` and each workload group app has its own `app_id`, so within
Original file line number	Diff line number	Diff line change
`@@ -4,7 +4,7 @@`
`4`	`4`	`#`
`5`	`5`	# Image tags pin to `:latest` from GHCR for clarity here; pin to
`6`	`6`	# `:sha-<full-sha>` (or a digest) for production deploys — see
`7`		`-# PUBLISHING.md.`
	`7`	`+# ../docs/publishing.md.`
`8`	`8`
`9`	`9`	`services:`
`10`	`10`	`coturn:`