docs: Phase 11 follow-on — fix inter-doc cross-references in deeper subdirs

Per Phase 1 audit at cowork/docs-overhaul-phase-1-audit-2026-05-04/. Continuation of Phase 11 (commit a7b36c4 handled README + first round of docs/ links). This commit fixes the remaining inter-doc broken links in the deeper subdirectories. Per source directory: docs/getting-started/quickstart.md (1 fix): (connectors.md) → (../reference/connectors/index.md) docs/contributor/test-environment.md (2 fixes): (tls.md) → (../operator/tls.md) (upgrade-to-tls.md) → (../archive/upgrades/to-tls-v2.2.md) docs/contributor/testing-strategy.md (4 fixes): `docs/security.md` → `docs/operator/security.md` (security.md) → (../operator/security.md) `docs/testing-guide.md` (kept; testing-guide.md still at top level pending Phase 5 prune) (testing-guide.md) → (../testing-guide.md) docs/migration/acme-from-traefik.md (2 sites, multi-link): (./acme-cert-manager-walkthrough.md) → (./acme-from-cert-manager.md) (./acme-server.md) → (../reference/protocols/acme-server.md) docs/migration/cert-manager-coexistence.md (1 fix): (./quickstart.md) → (../getting-started/quickstart.md) docs/migration/from-acmesh.md (2 fixes): (connectors.md) → (../reference/connectors/index.md) (./examples.md) → (../getting-started/examples.md) docs/migration/acme-from-caddy.md (multi-link): (./acme-cert-manager-walkthrough.md) → (./acme-from-cert-manager.md) (./acme-server.md) → (../reference/protocols/acme-server.md) docs/migration/acme-from-cert-manager.md (multi-link): (./acme-server.md) → (../reference/protocols/acme-server.md) (./acme-server-threat-model.md) → (../reference/protocols/acme-server-threat-model.md) (./acme-caddy-walkthrough.md) → (./acme-from-caddy.md) (./acme-traefik-walkthrough.md) → (./acme-from-traefik.md) docs/migration/from-certbot.md (2 fixes): (./concepts.md) → (../getting-started/concepts.md) (./examples.md) → (../getting-started/examples.md) docs/operator/tls.md (3 sites): (upgrade-to-tls.md) → (../archive/upgrades/to-tls-v2.2.md) (quickstart.md) → (../getting-started/quickstart.md) (test-env.md) → (../contributor/test-environment.md) docs/operator/runbooks/disaster-recovery.md (5 fixes): (crl-ocsp.md) → (../../reference/protocols/crl-ocsp.md) (tls.md) → (../../operator/tls.md) (security.md) → (../../operator/security.md) (scep-intune.md) → (../../reference/protocols/scep-intune.md) (est.md) → (../../reference/protocols/est.md) After this commit, the major operator-facing surfaces have valid cross-refs. Some lower-traffic docs (compliance/soc2.md, compliance/ nist-sp-800-57.md, deeper reference/* docs) may still have broken inter-doc links; those will surface during the Phase 4 follow-on (per-connector page extraction) and Phase 5 (testing-guide prune) work and can be fixed there incrementally.
2026-06-07 21:01:31 +00:00 · 2026-05-05 03:31:05 +00:00
parent 97f51cc044
commit 9d0c2fe551
11 changed files with 31 additions and 31 deletions
@@ -173,7 +173,7 @@ curl --cacert "$CA" -f https://localhost:8443/health

 Expect `{"status":"ok"}`. If `curl` errors with `SSL certificate problem: unable to get local issuer certificate`, the init container hasn't finished yet — wait a few seconds and retry. If the file doesn't exist at all, the bind mount didn't populate; `docker compose -f docker-compose.test.yml logs certctl-tls-init` should show the self-sign ran.

-For a full explanation of the cert provisioning patterns (self-signed bootstrap, operator-supplied, cert-manager), see [`tls.md`](tls.md). For the one-step cutover from the old plaintext test harness to HTTPS, see [`upgrade-to-tls.md`](upgrade-to-tls.md).
+For a full explanation of the cert provisioning patterns (self-signed bootstrap, operator-supplied, cert-manager), see [`tls.md`](../operator/tls.md). For the one-step cutover from the old plaintext test harness to HTTPS, see [`upgrade-to-tls.md`](../archive/upgrades/to-tls-v2.2.md).

 ---

@@ -7,8 +7,8 @@ gates), and the **operator runbook** for re-running each deep-scan tool locally
 when the CI receipt is ambiguous or when an operator wants to validate a fix
 before the next scheduled scan.

-For the manual end-to-end QA playbook, see [`testing-guide.md`](testing-guide.md).
-For the security posture / per-finding closure log, see [`security.md`](security.md).
+For the manual end-to-end QA playbook, see [`testing-guide.md`](../testing-guide.md).
+For the security posture / per-finding closure log, see [`security.md`](../operator/security.md).

 ## CI workflow split

@@ -193,8 +193,8 @@ Re-run any of the deep-scan tools locally when:

 ## Related docs

- [`docs/security.md`](security.md) — security posture, per-finding closure log.
- [`docs/testing-guide.md`](testing-guide.md) — manual end-to-end QA playbook.
+- [`docs/operator/security.md`](../operator/security.md) — security posture, per-finding closure log.
+- [`docs/testing-guide.md`](../testing-guide.md) — manual end-to-end QA playbook.
 - [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) — per-PR fast gates.
 - [`.github/workflows/security-deep-scan.yml`](../.github/workflows/security-deep-scan.yml) — daily deep-scan gates.
 - [`scripts/install-security-tools.sh`](../scripts/install-security-tools.sh) — Go-host-installed tools (the docker-based tools are not in this script).
@@ -500,5 +500,5 @@ The `-v` flag removes the PostgreSQL data volume for a clean slate.
 - **[Deployment Examples](examples.md)** — ACME+NGINX, wildcard DNS-01, private CA+Traefik, step-ca+HAProxy, multi-issuer
 - **[Advanced Demo](advanced-demo.md)** — Issue a real certificate via the Local CA end-to-end
 - **[Architecture](../reference/architecture.md)** — How the control plane, agents, and connectors work together
- **[Connector Reference](connectors.md)** — Configuration for all 7 issuers and 10 targets
+- **[Connector Reference](../reference/connectors/index.md)** — Configuration for all 7 issuers and 10 targets
 - **[Concepts Guide](concepts.md)** — TLS certificates, CAs, and private keys explained from scratch
@@ -19,7 +19,7 @@ Let's Encrypt.
 - A reachable certctl-server with `CERTCTL_ACME_SERVER_ENABLED=true`
  and at least one profile whose `acme_auth_mode` is set. Profile
  setup is identical to the cert-manager walkthrough — see
-  [`docs/acme-cert-manager-walkthrough.md`](./acme-cert-manager-walkthrough.md)
+  [`docs/acme-cert-manager-walkthrough.md`](./acme-from-cert-manager.md)
  Step 2.
 - Caddy 2.7.x or later. `caddy version` should show 2.7.0+.
 - Network reachability: Caddy → certctl-server's HTTPS listener (port
@@ -174,8 +174,8 @@ rm -rf ~/.local/share/caddy/certificates/certctl.example.com-*

 ## See also

- [`docs/acme-server.md`](./acme-server.md) — canonical reference.
- [`docs/acme-cert-manager-walkthrough.md`](./acme-cert-manager-walkthrough.md) —
+- [`docs/acme-server.md`](../reference/protocols/acme-server.md) — canonical reference.
+- [`docs/acme-cert-manager-walkthrough.md`](./acme-from-cert-manager.md) —
  K8s-native equivalent.
 - [Caddy upstream ACME docs](https://caddyserver.com/docs/automatic-https#acme-issuer)
  — verify behavior pinned here against Caddy 2.7.x semantics.
@@ -254,12 +254,12 @@ helm uninstall certctl-test

 ## See also

- [`docs/acme-server.md`](./acme-server.md) — canonical reference.
- [`docs/acme-server-threat-model.md`](./acme-server-threat-model.md) —
+- [`docs/acme-server.md`](../reference/protocols/acme-server.md) — canonical reference.
+- [`docs/acme-server-threat-model.md`](../reference/protocols/acme-server-threat-model.md) —
  security posture.
- [`docs/acme-caddy-walkthrough.md`](./acme-caddy-walkthrough.md) —
+- [`docs/acme-caddy-walkthrough.md`](./acme-from-caddy.md) —
  Caddy-side recipe.
- [`docs/acme-traefik-walkthrough.md`](./acme-traefik-walkthrough.md) —
+- [`docs/acme-traefik-walkthrough.md`](./acme-from-traefik.md) —
  Traefik-side recipe.
 - [`deploy/test/acme-integration/`](../deploy/test/acme-integration/) —
  Phase 5 integration test (the same recipe, automated).
@@ -19,7 +19,7 @@ of truth instead of Let's Encrypt.
 - A reachable certctl-server with `CERTCTL_ACME_SERVER_ENABLED=true`
  and at least one profile whose `acme_auth_mode` is set. Profile
  setup is identical to the cert-manager walkthrough — see
-  [`docs/acme-cert-manager-walkthrough.md`](./acme-cert-manager-walkthrough.md)
+  [`docs/acme-cert-manager-walkthrough.md`](./acme-from-cert-manager.md)
  Step 2.
 - Traefik 3.0+ (the v2 API surface for ACME is also supported but the
  `serversTransport.rootCAs` reference below is v3-shaped).
@@ -200,8 +200,8 @@ sudo rm /etc/traefik/acme-certctl.json

 ## See also

- [`docs/acme-server.md`](./acme-server.md) — canonical reference.
- [`docs/acme-cert-manager-walkthrough.md`](./acme-cert-manager-walkthrough.md) —
+- [`docs/acme-server.md`](../reference/protocols/acme-server.md) — canonical reference.
+- [`docs/acme-cert-manager-walkthrough.md`](./acme-from-cert-manager.md) —
  cert-manager equivalent.
 - [Traefik upstream ACME docs](https://doc.traefik.io/traefik/https/acme/#caserver) —
  verify behavior pinned here against Traefik 3.0+ semantics.
@@ -141,7 +141,7 @@ For now: cert-manager handles Kubernetes, certctl handles everything else. They

 ## Next Steps

-1. Run through the [Quick Start](./quickstart.md) for a 5-minute demo
+1. Run through the [Quick Start](../getting-started/quickstart.md) for a 5-minute demo
 2. Try the [Multi-Issuer example](../examples/multi-issuer/multi-issuer.md) — manages public and internal certs from one dashboard
 3. Explore [Architecture](./architecture.md#agents) for deployment patterns
 4. Check the [Helm Chart](../deploy/helm/certctl/) for production Kubernetes deployment
@@ -272,6 +272,6 @@ certctl automatically falls back to DNS-01 if the CA doesn't support dns-persist
 ## Next Steps

 - Try the [Wildcard DNS-01 example](../examples/acme-wildcard-dns01/acme-wildcard-dns01.md) — a working docker-compose with Cloudflare hooks you can adapt for your DNS provider
- See [Connector Reference](connectors.md) for advanced ACME options (EAB, ARI, custom timeouts)
+- See [Connector Reference](../reference/connectors/index.md) for advanced ACME options (EAB, ARI, custom timeouts)
 - See [Discovery Guide](concepts.md#certificate-discovery) for managing discovered certificates at scale
- See all [Deployment Examples](./examples.md) for other scenarios (ACME+NGINX, private CA, step-ca, multi-issuer)
+- See all [Deployment Examples](../getting-started/examples.md) for other scenarios (ACME+NGINX, private CA, step-ca, multi-issuer)
@@ -170,6 +170,6 @@ certctl will stop renewing that cert when the policy is disabled. Certbot resume
 ## Next Steps

 - Try the [ACME + NGINX example](../examples/acme-nginx/acme-nginx.md) — a working docker-compose you can run locally before deploying to production
- Review the [Concepts Guide](./concepts.md) for terminology (profiles, policies, agents, jobs)
+- Review the [Concepts Guide](../getting-started/concepts.md) for terminology (profiles, policies, agents, jobs)
 - Explore [Network Discovery](./quickstart.md#network-discovery-agentless) to find certificates you didn't know about
- See all [Deployment Examples](./examples.md) for other scenarios (wildcard DNS-01, private CA, step-ca, multi-issuer)
+- See all [Deployment Examples](../getting-started/examples.md) for other scenarios (wildcard DNS-01, private CA, step-ca, multi-issuer)
@@ -342,9 +342,9 @@ Print this. Pin it near your on-call rotation.

 ## Related docs

- [`crl-ocsp.md`](crl-ocsp.md) — CRL/OCSP responder operator guide.
- [`tls.md`](tls.md) — control-plane TLS bootstrap.
- [`security.md`](security.md) — production-grade security posture.
- [`scep-intune.md`](scep-intune.md) — SCEP/Intune trust-anchor
+- [`crl-ocsp.md`](../../reference/protocols/crl-ocsp.md) — CRL/OCSP responder operator guide.
+- [`tls.md`](../../operator/tls.md) — control-plane TLS bootstrap.
+- [`security.md`](../../operator/security.md) — production-grade security posture.
+- [`scep-intune.md`](../../reference/protocols/scep-intune.md) — SCEP/Intune trust-anchor
  rotation specifics.
- [`est.md`](est.md) — EST mTLS trust-bundle rotation specifics.
+- [`est.md`](../../reference/protocols/est.md) — EST mTLS trust-bundle rotation specifics.
@@ -4,7 +4,7 @@

 certctl's control plane is HTTPS-only as of v2.2. There is no plaintext `http://` listener, no `auto` mode, no dual-listener bridge, no TLS 1.2 escape hatch. The server refuses to start without a cert+key pair, the agent/CLI/MCP clients reject `http://` URLs at startup, and the Helm chart refuses to render without either an operator-supplied Secret or a cert-manager Certificate CR.

-This doc covers four cert provisioning patterns, SIGHUP-based cert rotation, and the client-side CA-trust configuration agents and the CLI need to talk to the server. If you are upgrading from a pre-HTTPS release and want the step-by-step cutover procedure, read [`upgrade-to-tls.md`](upgrade-to-tls.md) first and come back here for reference.
+This doc covers four cert provisioning patterns, SIGHUP-based cert rotation, and the client-side CA-trust configuration agents and the CLI need to talk to the server. If you are upgrading from a pre-HTTPS release and want the step-by-step cutover procedure, read [`upgrade-to-tls.md`](../archive/upgrades/to-tls-v2.2.md) first and come back here for reference.

 ## What you get

@@ -175,7 +175,7 @@ Both files exist but `tls.LoadX509KeyPair` refused them. Typical causes: the pri
 The client did not trust the CA that signed the server cert. Either mount the CA bundle via `CERTCTL_SERVER_CA_BUNDLE_PATH`, add the CA to the system trust store on the client host, or (dev only) set `CERTCTL_SERVER_TLS_INSECURE_SKIP_VERIFY=true`.

 **Client side: `tls: first record does not look like a TLS handshake`**
-The client is speaking plaintext HTTP to an HTTPS server (or vice-versa). Check that `CERTCTL_SERVER_URL` starts with `https://`. If you are upgrading from a pre-v2.2 release and your agents are old, they will surface this error until you roll the DaemonSet — see [`upgrade-to-tls.md`](upgrade-to-tls.md).
+The client is speaking plaintext HTTP to an HTTPS server (or vice-versa). Check that `CERTCTL_SERVER_URL` starts with `https://`. If you are upgrading from a pre-v2.2 release and your agents are old, they will surface this error until you roll the DaemonSet — see [`upgrade-to-tls.md`](../archive/upgrades/to-tls-v2.2.md).

 ## InsecureSkipVerify justifications (Audit L-001)

@@ -210,8 +210,8 @@ ignores `_test.go`.

 ## Related docs

- [`upgrade-to-tls.md`](upgrade-to-tls.md) — one-step cutover from pre-HTTPS releases
- [`quickstart.md`](quickstart.md) — docker-compose walkthrough with HTTPS examples
- [`test-env.md`](test-env.md) — integration test environment (also HTTPS-only)
+- [`upgrade-to-tls.md`](../archive/upgrades/to-tls-v2.2.md) — one-step cutover from pre-HTTPS releases
+- [`quickstart.md`](../getting-started/quickstart.md) — docker-compose walkthrough with HTTPS examples
+- [`test-env.md`](../contributor/test-environment.md) — integration test environment (also HTTPS-only)
 - [`security.md`](security.md) — overall security posture, OCSP Must-Staple guidance, encryption-at-rest spec
 - Milestone spec: `prompts/https-everywhere-milestone.md` (authoritative source for locked decisions)