docs: clarify bespoke bottles and example-team documentation (#51)

- Add intro explaining bespoke vs curated bottles
- Replace misleading "air-gapped" bullet with "team standardization"
- Remove invalid JSON comments, move explanations to prose
- Add manifest field explanations (tools vs plugins vs opencode_plugins)
- Fix sg/superego naming consistency
- Make example path explicit with placeholder
- Expand Figma troubleshooting with full steps
- Clarify SETUP.md audience (for AI assistants)

Co-authored-by: Muness Castle <[email protected]>
Co-authored-by: Claude Opus 4.5 <[email protected]>

Author: 3 people

bottles/example-team/README.md

@@ -1,14 +1,18 @@
 # Example Team Bottle
 
+This is a template for teams sharing a bottle configuration via version control. Copy this folder to your project (e.g., `dev_tools/bottle/`) and customize it.
+
 ## Quick Start
 
 ```bash
-bash dev_tools/bottle/bootstrap.sh
+bash <your-path>/bootstrap.sh
 ```
 
+(Replace `<your-path>` with wherever you copied this folder, e.g., `dev_tools/bottle`)
+
 This runs through:
 1. **Bottle install** - Installs all tools from `manifest.json`
-2. **OpenCode integrate** - Configures plugins/MCP in project root
+2. **OpenCode integrate** - Configures plugins and MCP servers in your project
 
 ## What Gets Installed
 
@@ -17,7 +21,7 @@ This runs through:
 | **opencode** | AI coding assistant |
 | **ba** | Task tracking - claim/finish work items |
 | **wm** | Working memory - context from past sessions |
-| **superego** | Metacognitive review - sanity check before commits |
+| **superego** (`sg`) | Metacognitive review - sanity check before commits |
 | **azure-cli** | Azure resource management |
 | **Figma MCP** | Design context - share Figma URLs |
 
@@ -54,7 +58,7 @@ wm dive-prep "intent"    # Prepare context
 wm show                  # Show context
 ```
 
-### Metacognitive Review (sg)
+### Metacognitive Review (`sg`)
 ```bash
 sg review                # Review before commit
 ```
@@ -67,7 +71,9 @@ sg review                # Review before commit
 → Run: `bash dev_tools/bottle/bootstrap.sh`
 
 **"Figma not working"**
-→ Set `FIGMA_API_KEY` in `~/.zshrc`
+→ Get an API key from https://www.figma.com/developers/api#access-tokens
+→ Add to `~/.zshrc`: `export FIGMA_API_KEY="your-key"`
+→ Run `source ~/.zshrc`
 
 ---
 

bottles/example-team/SETUP.md

@@ -1,6 +1,6 @@
 # SETUP.md - Example Team
 
-AI assistant guidance for environment setup and troubleshooting.
+This file is for AI assistants (Claude Code, OpenCode, etc.) to read when helping with environment setup and troubleshooting.
 
 ## Environment Check
 
@@ -67,7 +67,7 @@ wm dive-prep "intent" # Prepare context for session
 wm show               # Show current context
 ```
 
-### Metacognitive Review (sg)
+### Metacognitive Review (`sg`)
 ```bash
 sg review             # Review before commit
 ```

docs/bespoke.md

@@ -1,13 +1,13 @@
 # Bespoke Bottles
 
-Bespoke bottles let you create custom tool configurations with pinned versions, independent of curated bottle updates.
+While `stable` and `edge` bottles are curated by Open Horizon Labs and update automatically, a bespoke bottle is one you create and maintain yourself. You control exactly which tools and versions it contains.
 
 ## When to Use Bespoke Bottles
 
 - **Version pinning**: Lock specific versions you've tested together
 - **Custom tool sets**: Include only the tools you need
 - **Experimentation**: Test new versions before they hit stable
-- **Offline/air-gapped**: Pre-configure manifests for environments without internet
+- **Full ownership**: Define and maintain your own toolstack, independent of upstream releases
 
 ## Creating a Bespoke Bottle
 
@@ -64,16 +64,24 @@ This copies the current stable manifest as your starting point:
 }
 ```
 
+**Manifest fields:**
+- `tools`: CLI tools to install (e.g., `ba`, `wm`). These are the actual binaries.
+- `plugins`: Claude Code plugins to configure. Often matches your tools list.
+- `opencode_plugins`: OpenCode-specific plugins (separate from Claude Code).
+- `prerequisites`: Dependencies users need before installing (informational).
+
 ## Editing the Manifest
 
 Edit `~/.bottle/bottles/mystack/manifest.json` to customize:
 
 ### Pin a Specific Version
 
+Pin `wm` to an older version you've tested:
+
 ```json
 {
   "tools": {
-    "wm": "0.2.2",  // Pin to older version
+    "wm": "0.2.2",
     "ba": "0.2.1",
     "superego": "0.9.0"
   }
@@ -82,26 +90,29 @@ Edit `~/.bottle/bottles/mystack/manifest.json` to customize:
 
 ### Remove Tools You Don't Need
 
+Remove `wm` and `oh-mcp` by omitting them from `tools`, and update the `plugins` list to match:
+
 ```json
 {
   "tools": {
     "ba": "0.2.1",
     "superego": "0.9.0"
-    // Removed wm and oh-mcp
   },
-  "plugins": ["ba", "superego"]  // Update plugins list too
+  "plugins": ["ba", "superego"]
 }
 ```
 
 ### Add a Tool Not in Stable
 
+Add `datasphere` to your tool set:
+
 ```json
 {
   "tools": {
     "ba": "0.2.1",
     "wm": "0.3.1",
     "superego": "0.9.0",
-    "datasphere": "0.1.0"  // Added datasphere
+    "datasphere": "0.1.0"
   },
   "plugins": ["ba", "superego", "wm", "datasphere"]
 }