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>

documentation.md

@@ -0,0 +1,65 @@
+# Documentation Standards
+
+Every project maintains four core markdown files.
+
+## CLAUDE.md
+
+The primary reference for Claude sessions. Should contain:
+- Project overview and architecture
+- Repository structure (keep updated as the project evolves)
+- Key design decisions with rationale
+- Conventions and coding standards
+- Environment details (IPs, URLs, credential references — never actual values)
+- Common operations / how-to recipes
+- Put critical rules at the top — Claude reads sequentially and earlier content has more influence
+
+## MEMORY.md (Tiered Memory System)
+
+Long-running projects accumulate significant context. Use a **tiered memory** structure:
+
+**MEMORY.md** is a **thin index only** — one-line descriptions with links to topic files in `memory/`. No content lives in MEMORY.md itself. Keep it under ~50 lines.
+
+**memory/** contains the actual content, split by topic:
+- `memory/project-status.md` — Current milestone, what's next, blockers
+- `memory/gotchas-<topic>.md` — Gotchas grouped by technology
+- `memory/process-lessons.md` — How-to-work-with-this-repo lessons
+- `memory/m<N>-reflection.md` — One file per milestone reflection
+- `memory/decisions.md` — Architecture and design decisions
+
+**Principles:**
+- Split by topic, not by time
+- Index descriptions matter — they're used to decide what to read
+- Prune aggressively — stale memory is worse than no memory
+- Each file should be self-contained and greppable
+- Deduplicate with CLAUDE.md — stable conventions go in CLAUDE.md, learnings and gotchas go in memory
+
+## FUTURE.md
+
+Backlog of improvement ideas, each with:
+- **Problem:** What's painful or manual today
+- **Idea:** What the improvement looks like
+- **Open questions:** Unknowns to research before starting
+- **Depends on:** Other items or milestones that should come first
+
+## README.md
+
+Human-readable project documentation:
+- Architecture summary
+- Quick start / setup instructions
+- Milestone table with status
+- Scripts section listing every script with purpose and usage
+
+## Extract Reusable Patterns Early
+
+When a reusable pattern emerges during project work (a gotcha that applies to any project using the same tool, a process lesson that generalises), extract it into a best-practices guide immediately rather than waiting for a dedicated distillation pass. The guide pays for itself when used to audit and improve the current project in the same session, and benefits all future projects.
+
+## CONTEXT.md (Active Work Focus)
+
+Tells Claude (and independent agents) what the project is currently working on. Follows the same thin-index pattern as MEMORY.md.
+
+**CONTEXT.md** is a thin index with links to `context/<topic>.md` detail files.
+
+**Principles:**
+- Keep it current — remove entries when work is complete
+- Orient agents — this is the primary mechanism for pointing independent agents at the right work
+- Complement, don't duplicate — CLAUDE.md has conventions, MEMORY.md has learnings, CONTEXT.md has the current focus