docs: add client lifecycle plan, cleanup stale files, document repo for 3 audiences

Problem: Repo had no developer guide, no client onboarding doc, no agent
dev instructions. Stale files (675KB SQL dump, one-off convert script,
legacy MCP builder) cluttered the tree. Client enrollment was a documented
intention with no Go implementation.

Changes:
- New docs: CONTRIBUTING.md (dev setup), CLIENTS.md (client onboarding),
  .agents/dev/CONTRIBUTING.md (agent codebase map)
- New plan: plans/2026-07-07-client-lifecycle-in-go.md — full client
  lifecycle (planned→provisioning→active→deprecated→destroyed) in Go,
  replacing archived Python secrets-issuance, adding client API endpoints
  and 6 missing MCP tools
- Cleanup: deleted archive/convert-wiki.py (one-off), archive/mcp/
  build_host_files.py (legacy), backups/pre-deploy-7f7d039.sql (local)
- Fixes: plans/index.md duplicate row removed, README.md repo layout
  updated for current state, AGENTS.md header points to new guides

Risk: low. Docs only + stale file deletion. No code changes. New plan is
proposal, not implementation.
Verification: git diff reviewed, all changes are prose/docs/plans.

CLIENTS.md

@@ -0,0 +1,117 @@
+# Oikos — client guide
+
+If you are a homelab machine, this is what Oikos is and what it gives you.
+If you are an AI agent running on this machine, also read [AGENTS.md](AGENTS.md).
+
+## What is Oikos?
+
+Oikos is the agentic operating system for the **hubris** Proxmox homelab. It
+observes state, classifies actions against policy, executes approved
+procedures, learns from outcomes, and notifies the operator. It runs as a
+Docker stack on mac-mini and exposes an MCP server + REST API.
+
+## What Oikos provides
+
+| Capability | How you access it |
+|------------|-------------------|
+| Entity query (topology, blast radius) | MCP `get_entity`, `get_blast_radius` |
+| Full-text knowledge search | MCP `search_knowledge` |
+| Service status + logs | MCP `get_service_status`, `tail_log` |
+| LXC inventory + state | MCP `list_lxcs`, `get_lxc_state` |
+| Context cards | MCP `explain` |
+| Pre-flight risk classification | MCP `preflight` |
+| Change history | MCP `get_change_history` |
+| State snapshot (health, disk, drift) | MCP `get_state_snapshot` |
+| Secrets (Infisical) | REST API + `oikos secret` CLI |
+| Approval tokens | Matrix via notifier |
+
+All MCP tools are read-only. Mutations use the `homelab` CLI with operator
+approval.
+
+## Enrollment
+
+Enrolled clients have a checkout at `/opt/homelab-context/`. If this
+directory does not exist, the client is not enrolled.
+
+To enroll:
+```bash
+# Run from an existing enrolled client
+homelab client add <hostname>
+```
+
+This runs `bootstrap.sh` on the target, which:
+1. Clones the repo to `/opt/homelab-context/`
+2. Configures the auto-sync timer
+3. Provisions agent persona from `hermes/SOUL.md` (on Hermes agents)
+4. Installs Caveman tooling for terse communication
+
+## After enrollment
+
+### What changes on your machine
+
+- `/opt/homelab-context/` — the repo checkout, your source of truth
+- `/opt/homelab-context/inventory.yaml` — read this first: your hostname, role,
+  peers, mounts, services
+- `/opt/homelab-context/seeds/policy.yaml` — rules for what actions you can
+  take autonomously vs. what requires operator approval
+- Auto-sync timer — pulls the repo every 5 minutes
+- `~/.hermes/SOUL.md` — agent persona (on Hermes agents)
+- `~/bin/caveman_wrapper.sh` — terse communication tooling
+
+### Your identity
+
+Your identity in the homelab is defined in `inventory.yaml`. Run `hostname`
+(Linux) or `scutil --get LocalHostName` (macOS), then look up your entry.
+It tells you your role, what services you host, what's mounted, and your
+mesh address.
+
+### Source of truth hierarchy
+
+1. **Postgres database** (runtime) — authoritative for entities, knowledge,
+   signals, ledger. Query via MCP or REST API.
+2. **Repo at `/opt/homelab-context/`** — bootstrap seeds + documentation.
+   On disk, available offline.
+3. **Never guess.** If data is missing, query MCP. If MCP is down, grep the
+   clone.
+
+## The sync timer
+
+Every 5 minutes, `systemd` (Linux) or `launchd` (macOS) runs:
+
+1. `git pull` via `tools/post-pull.sh`
+2. Any `tools/*.setup.sh` scripts that need to run
+
+This keeps your checkout current and applies tooling updates automatically.
+To trigger sync manually: `sudo homelab sync`.
+
+## Making changes
+
+- **Read state**: use MCP tools or the repo checkout
+- **Mutate state** (restart, edit config, deploy): classify the action against
+  `seeds/policy.yaml`:
+  - `read_only` / `reversible_low` — execute directly
+  - `config_mutation` / `destructive` — request operator approval via the
+    `homelab` CLI
+- **Secrets**: use Infisical (primary) or SOPS (fallback). Never hardcode.
+- **Knowledge**: if you observe a discrepancy between docs and live state,
+  update the DB via the API in the same session. Run `oikos export` to
+  regenerate seeds.
+
+## MCP endpoint
+
+```
+https://mcp.hubris.network/mcp
+```
+
+Available tools are listed in [AGENTS.md](AGENTS.md#3-the-mcp-server).
+
+## Communication mode
+
+Apply [.agents/shared/caveman.md](.agents/shared/caveman.md) — terse,
+fragment-heavy communication. Drop filler, keep substance.
+
+## Related
+
+- [AGENTS.md](AGENTS.md) — full agent orientation (read this first)
+- [OIKOS.md](.agents/OIKOS.md) — operating model, OODA loop, risk classes
+- [CONTRIBUTING.md](CONTRIBUTING.md) — developer guide for the Oikos codebase