archive: prune stale dirs, move actual content to docs/

Deleted stale (Python-era artifacts, superseded by DB):
- archive/oikos-cards/ (46 files, predecessor to DB entity graph)
- archive/ledger/ (5-line JSONL fragment, superseded by DB audit log)

Moved to docs/ (actual, current architecture docs):
- docs/infrastructure/ — 12 infrastructure docs (network, DNS, mesh,
  SSH, ingress, media-permissions, backups, homelab-context, auto-deploy,
  VPS-hardening, monitoring, check-lifecycle)
- docs/secrets/ — secrets README and rotation runbook
- docs/GLOSSARY.md — 28-term homelab glossary

Added STALE.md markers to hermes-plans/ and secrets-issuance/.
Added MOVED.md pointers in archive sources.
Updated docs/index.md to include new paths.

docs/secrets/README.md

@@ -0,0 +1,63 @@
+# secrets/
+
+SOPS-encrypted YAML files. The plaintext lives only in transit and in the
+operator's head — committed files are always ciphertext.
+
+## Conventions
+
+- One file per logical grouping (e.g. `gitea-tokens.yaml`, `webhook-hmacs.yaml`,
+  `api-keys.yaml`).
+- Recipients are declared in `../../.sops.yaml` by path-regex, not per-file.
+- The plaintext schema inside each file is free-form YAML; the consumer code
+  decides what it expects (e.g. `gitea-tokens.yaml` contains
+  `{"<host>": "ghp_xxx"}`).
+
+## How to add a secret
+
+```bash
+# 1. Decide which clients should be able to decrypt it; edit ../../.sops.yaml to
+#    list their age public keys for the new path_regex.
+# 2. Create the plaintext, encrypt in place:
+sops -e --in-place secrets/my-thing.yaml
+# 3. Commit + push. The 5-min sync propagates to every recipient.
+```
+
+## How to consume a secret
+
+```bash
+# On any client that's a recipient:
+homelab secret my-thing               # prints plaintext
+# Or programmatically:
+sops -d /opt/homelab-context/secrets/my-thing.yaml
+```
+
+The `mcp` tool `list_my_secrets(caller_pubkey)` returns the names of secrets
+the caller can decrypt. The MCP server never reads plaintext — decryption
+stays client-side.
+
+## Granting / revoking access
+
+To grant a new recipient: edit `../../.sops.yaml` to add their age pubkey, then
+re-key every affected file:
+
+```bash
+sops updatekeys -y secrets/my-thing.yaml
+```
+
+To revoke: remove the recipient from `../../.sops.yaml` and `sops updatekeys` —
+but remember this only protects future ciphertext. Past plaintext the client
+already decrypted is gone from your control. Rotate the underlying credential
+if compromise is suspected.
+
+`homelab client remove <name>` does the recipient removal + `updatekeys` for
+you, and prints the rotation checklist as a follow-up.
+
+## hello.yaml — bootstrap decrypt test
+
+`secrets/hello.yaml` is encrypted to every enrolled client. Used by Phase 3a
+verification to confirm the end-to-end decrypt path works on a freshly-
+bootstrapped machine. Content is intentionally trivial:
+
+```yaml
+greeting: hello from the homelab
+```

docs/secrets/rotation.md

@@ -0,0 +1,100 @@
+# Secret rotation runbook (Phase 5)
+
+Rotation cadences per secret type. All rotation is automated via Infisical;
+this runbook covers the manual verification and DR procedures.
+
+## Rotation schedule
+
+| Secret | Cadence | Method |
+|--------|---------|--------|
+| OpenRouter API key | 90 days | Infisical rotation policy → update `OPENROUTER_API_KEY` env |
+| MCP bearer token | 30 days | Infisical random password generation |
+| Approval HMAC secret | 90 days | Infisical random password generation |
+| Matrix access token | 90 days | Manual (Matrix does not support automated rotation) |
+| Age DR key (SOPS fallback) | Never | Static — stored offline for DR only |
+
+## How to rotate a secret
+
+### Automated (Infisical)
+```bash
+# Secrets managed by Infisical rotate automatically per the policy above.
+# To force an immediate rotation:
+infisical secrets rotate --project-id $INFISICAL_PROJECT_ID \
+  --secret-name <secret-key> --env dev
+
+# Verify the new value is available:
+oikos secret list
+```
+
+### Manual (SOPS fallback)
+```bash
+# If Infisical is unavailable, use the SOPS DR fallback:
+sops -d secrets/<name>.yaml
+
+# To rotate a SOPS secret:
+sops -e --in-place secrets/<name>.yaml   # edit in place
+```
+
+## Rotation verification
+
+After any rotation, verify the consuming services still work:
+
+```bash
+# 1. OpenRouter key: test Hermes query
+curl -s -X POST http://localhost:8092/query \
+  -H "Content-Type: application/json" \
+  -d '{"query":"fleet health"}'
+
+# 2. MCP bearer token: test MCP connection
+curl -s -X POST http://localhost:8092/query \
+  -H "Content-Type: application/json" \
+  -d '{"tool":"list_entities","args":{"limit":1}}'
+
+# 3. Approval HMAC: create a test execution
+curl -s -X POST http://localhost:8092/query \
+  -H "Content-Type: application/json" \
+  -d '{"query":"restart caddy"}'
+```
+
+## Disaster recovery
+
+If Infisical is completely unavailable:
+
+```bash
+# 1. Export SOPS DR fallback
+oikos secret export-sops > /tmp/sops-dr-backup.txt
+
+# 2. Configure services to use SOPS fallback
+# Set OIKOS_SECRETS_DIR=/opt/homelab-context/secrets
+# This switches the secrets manager to SOPS-only mode.
+
+# 3. Restart services
+docker compose restart api hermes notifier scheduler
+```
+
+## Restore drill
+
+Run monthly:
+
+```bash
+# 1. Export all secrets from Infisical
+oikos secret list
+
+# 2. Simulate Infisical outage: stop the container
+docker compose stop infisical
+
+# 3. Verify SOPS fallback works
+OIKOS_SECRETS_DIR=./secrets oikos secret list
+
+# 4. Restore Infisical
+docker compose start infisical
+sleep 5
+
+# 5. Verify Infisical primary works again
+oikos secret list
+```
+
+## Changelog
+
+### 2026-07-07 — initial rotation runbook
+Phase 5 rotation cadences, verification steps, and DR restore drill.