Populate best practices from claude-foundations

Migrates 20 topic files from claude-foundations/best-practices/ to this
standalone repo. Adds BESTPRACTICES.md index, CLAUDE.md conventions, and
updated README.md. Container agents clone this repo to /best-practices.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

README.md

@@ -1,3 +1,51 @@
 # best-practices
 
-Cross-project best practices extracted from real project work
+Cross-project best practices extracted from real project work via the `/distill-best-practices` skill.
+
+## How It Works
+
+The knowledge distillation pipeline in `claude-foundations` processes session logs and memory files from all tracked projects, extracting generalisable practices into topic files here.
+
+### Pipeline
+
+1. **`/log`** — Captures session decisions and gotchas into per-project `memory/log/`
+2. **`/reflect-logs`** — Processes logs into structured topic memory files
+3. **`/distill-best-practices`** — Reads memory files across projects, proposes updates to this repo
+
+### For Humans
+
+Browse `BESTPRACTICES.md` for the full index. Each topic file is self-contained.
+
+### For Agents
+
+Container agents get this repo cloned to `/best-practices`. Read `BESTPRACTICES.md` for the index, then read only the topic files relevant to your task.
+
+## Topics
+
+| File | Description |
+|------|-------------|
+| `ansible.md` | Inventory, templates, idempotency, credential safety |
+| `database-selection.md` | SQLite vs PostgreSQL decision criteria |
+| `debugging.md` | Systematic diagnosis, full-chain testing, common pitfalls |
+| `docker.md` | gosu PID 1, GIT_SSH_COMMAND scope, slim image patterns |
+| `docker-uid-matching.md` | UID wrapper entrypoint, gosu pattern |
+| `documentation.md` | CLAUDE.md, MEMORY.md, FUTURE.md, README.md structure |
+| `git-source-control.md` | Commit practices, GitOps workflows, remote conventions |
+| `helm.md` | Schema validation, version verification, values structure |
+| `kubernetes.md` | Volume mounts, deployment strategies, naming, bootstrap ordering |
+| `linting.md` | Tool choices per language, PostToolUse hook, pre-commit |
+| `milestones.md` | Milestone workflow, verification, reflection process |
+| `networking.md` | nftables, systemd sockets, Docker forwarding, TLS |
+| `octopus-process-templates.md` | OCL syntax, step templates, Platform Hub patterns |
+| `scripting.md` | Shell conventions, verification scripts, idempotency |
+| `secrets-management.md` | SOPS + age, credential handling, encryption gotchas |
+| `security-architecture.md` | Server boundary rule, proxy patterns, defense in depth |
+| `skills-development.md` | Skill authoring, context injection, tool restrictions |
+| `spec-driven-development.md` | Spec structure, requirement numbering, test-first workflow |
+| `test-driven-development.md` | Edge case discovery, property-based testing, AI agent patterns |
+| `validation.md` | Validate locally, deploy once; full-chain testing |
+
+## Source Control
+
+- **Gitea:** `skynet/best-practices`
+- **Remote:** `git@gitea.oreillyit.nz-ai-enablement:skynet/best-practices.git`