refactor!: rename project to bot-bottle

Assisted-by: Codex

docs/research/manifest-format-and-grouping.md

@@ -1,6 +1,6 @@
 # Manifest format and grouping
 
-Two open questions for claude-bottle's manifest layer after PRD 0011:
+Two open questions for bot-bottle's manifest layer after PRD 0011:
 
 1. **Grouping.** Keep bottles and agents in the same manifest file
    (today's shape), or split them — one file per bottle and one
@@ -8,7 +8,7 @@ Two open questions for claude-bottle's manifest layer after PRD 0011:
 2. **Format.** Stay on JSON, switch to YAML, or move to a Markdown
    spec with YAML frontmatter. The Markdown option splits into two
    sub-flavors: reuse Claude Code's existing subagent format with
-   bottle-specific extensions, or invent a claude-bottle-owned
+   bottle-specific extensions, or invent a bot-bottle-owned
    Markdown spec used for both agents and bottles.
 
 The trust boundary from PRD 0011 — bottle infrastructure lives in
@@ -19,8 +19,8 @@ will be once a user has 5+ bottles and 10+ agents.
 
 ## Why this matters
 
-Current shape: one JSON file at `$HOME/claude-bottle.json` (and
-optionally `$CWD/claude-bottle.json` for cwd-defined agents). After
+Current shape: one JSON file at `$HOME/bot-bottle.json` (and
+optionally `$CWD/bot-bottle.json` for cwd-defined agents). After
 PRD 0011, the home file owns bottles + home agents; the cwd file is
 agents-only.
 
@@ -48,7 +48,7 @@ the inflection point has been reached.
 
 ### Option A: one file for both (current)
 
-`$HOME/claude-bottle.json` contains `bottles:` and `agents:`. Cwd
+`$HOME/bot-bottle.json` contains `bottles:` and `agents:`. Cwd
 file (optional) contains `agents:` only.
 
 **Pros**
@@ -74,16 +74,16 @@ file (optional) contains `agents:` only.
 
 ### Option B: file per thing
 
-Bottles live as `$HOME/.claude-bottle/bottles/<name>.<ext>`. Agents
-live as `$HOME/.claude-bottle/agents/<name>.<ext>` (home agents)
-and `$CWD/.claude-bottle/agents/<name>.<ext>` (cwd agents). The
+Bottles live as `$HOME/.bot-bottle/bottles/<name>.<ext>`. Agents
+live as `$HOME/.bot-bottle/agents/<name>.<ext>` (home agents)
+and `$CWD/.bot-bottle/agents/<name>.<ext>` (cwd agents). The
 resolver globs each directory.
 
 **Pros**
 
 - Scales to N bottles + N agents without any single file growing.
-- Trust boundary expresses on disk: `$HOME/.claude-bottle/bottles/`
-  is the only place bottles can come from. `$CWD/.claude-bottle/`
+- Trust boundary expresses on disk: `$HOME/.bot-bottle/bottles/`
+  is the only place bottles can come from. `$CWD/.bot-bottle/`
   can only contribute agents. No resolver logic needed to enforce
   it — the file paths are the enforcement.
 - Aligns with Claude Code's existing model: each subagent already
@@ -147,7 +147,7 @@ preserves this format.
 
 ### Option 2: full YAML
 
-`$HOME/claude-bottle.yaml` (or `.yml`). Parser pulls in PyYAML (or
+`$HOME/bot-bottle.yaml` (or `.yml`). Parser pulls in PyYAML (or
 ruamel.yaml).
 
 **Pros**
@@ -172,14 +172,14 @@ ruamel.yaml).
   users will reach for one (Jinja, Helm-style) and then we're in
   yaml-as-template-language territory.
 
-### Option 3: reuse Claude Code's subagent spec (Markdown + YAML frontmatter), with claude-bottle extensions
+### Option 3: reuse Claude Code's subagent spec (Markdown + YAML frontmatter), with bot-bottle extensions
 
 Claude Code already stores subagents at `~/.claude/agents/<name>.md`
 with YAML frontmatter and a Markdown body. Frontmatter today
 carries fields like `name`, `description`, `model`, `color`,
 `memory`; the body is the system prompt. Adding fields like
-`bottle: dev` and a `claude_bottle:` sub-block to the same
-frontmatter would make each claude-bottle agent a drop-in addition
+`bottle: dev` and a `bot_bottle:` sub-block to the same
+frontmatter would make each bot-bottle agent a drop-in addition
 to Claude Code's agent directory.
 
 ```markdown
@@ -188,12 +188,12 @@ name: implementer
 description: Implements features against PRDs in this repo
 model: opus
 bottle: dev
-claude_bottle:
+bot_bottle:
   skills: [init-prd]
 ---
 
 You are a feature-implementation agent running inside an
-ephemeral claude-bottle sandbox. The host has copied the user's
+ephemeral bot-bottle sandbox. The host has copied the user's
 project into /home/node/workspace...
 ```
 
@@ -202,7 +202,7 @@ infrastructure, not behavior. Either:
 
 - (3a) Bottles stay JSON / YAML; only agents adopt the
   MD+frontmatter format. Mixed-format manifest.
-- (3b) Bottles adopt MD+frontmatter too, using a claude-bottle-only
+- (3b) Bottles adopt MD+frontmatter too, using a bot-bottle-only
   schema. Then we're really doing option 4 for bottles + option 3
   for agents. Two formats but one parser.
 
@@ -214,7 +214,7 @@ infrastructure, not behavior. Either:
 - Each agent's prompt lives naturally as Markdown body — long
   prompts read well, can use headings/lists/code blocks.
 - File-per-thing falls out automatically (one MD per agent).
-- Claude Code may eventually consume claude-bottle's agent files
+- Claude Code may eventually consume bot-bottle's agent files
   directly, doubling their utility.
 
 **Cons**
@@ -222,7 +222,7 @@ infrastructure, not behavior. Either:
 - **Coupling to Claude Code's spec.** Anthropic owns that schema;
   field names and semantics can change. Today's `model` /
   `description` / `memory` are stable, but tomorrow's may not be.
-  Our `bottle:` / `claude_bottle:` extensions could collide with
+  Our `bottle:` / `bot_bottle:` extensions could collide with
   future official fields.
 - The agent file's frontmatter starts to carry two unrelated
   schemas: Claude Code's (model, description) and ours (bottle,
@@ -233,28 +233,28 @@ infrastructure, not behavior. Either:
   frontmatter library (python-frontmatter) or hand-parse the
   `---` block and feed it to PyYAML. Either way, a new dep.
 
-### Option 4: invent a claude-bottle MD spec, used for both agents and bottles
+### Option 4: invent a bot-bottle MD spec, used for both agents and bottles
 
 ```markdown
 ---
-# $HOME/.claude-bottle/agents/implementer.md
+# $HOME/.bot-bottle/agents/implementer.md
 bottle: dev
 skills: [init-prd]
 ---
 
 You are a feature-implementation agent running inside an
-ephemeral claude-bottle sandbox...
+ephemeral bot-bottle sandbox...
 ```
 
 ```markdown
 ---
-# $HOME/.claude-bottle/bottles/dev.md
+# $HOME/.bot-bottle/bottles/dev.md
 cred_proxy:
   routes:
     - path: /anthropic/
       upstream: https://api.anthropic.com
       auth_scheme: Bearer
-      token_ref: CLAUDE_BOTTLE_OAUTH_TOKEN
+      token_ref: BOT_BOTTLE_OAUTH_TOKEN
       role: anthropic-base-url
 egress:
   allowlist: [example.com]
@@ -273,8 +273,8 @@ for publishing scoped packages.
   documentation (why does this bottle exist? what tokens does it
   hold? who owns the keys?).
 - Not coupled to Claude Code's schema; we own the spec.
-- Trust boundary on disk: `$HOME/.claude-bottle/bottles/` is the
-  only place bottles can come from; `$CWD/.claude-bottle/agents/`
+- Trust boundary on disk: `$HOME/.bot-bottle/bottles/` is the
+  only place bottles can come from; `$CWD/.bot-bottle/agents/`
   is the only thing cwd contributes.
 - Agent files in this spec are *almost* compatible with Claude
   Code's subagent format. If we keep the `name` / `description`
@@ -308,14 +308,14 @@ grouping fits how users iterate on agents (write a prompt, save,
 launch).
 
 Between option 3 (reuse CC spec) and option 4 (new spec): the
-appealing middle ground is "claude-bottle agents follow the CC
+appealing middle ground is "bot-bottle agents follow the CC
 subagent shape closely (name / description / model + bottle and
 skills extensions) so they drop into `~/.claude/agents/` as a
 side effect, while bottles use the same MD+frontmatter shape but
-with claude-bottle's own schema and live in a dedicated directory."
+with bot-bottle's own schema and live in a dedicated directory."
 This:
 
-- gives agents both a claude-bottle launch story AND a Claude Code
+- gives agents both a bot-bottle launch story AND a Claude Code
   invocation story from the same file;
 - keeps bottles entirely under our schema (no Anthropic dependency
   for the security-load-bearing config);
@@ -343,18 +343,18 @@ per-file grouping (which is the bigger UX win), and the per-file
 shape is what makes the trust boundary self-documenting on disk.
 
 The dependency cost (PyYAML) is the main thing that needs an
-explicit yes from the user — claude-bottle today has zero
+explicit yes from the user — bot-bottle today has zero
 third-party Python deps for production code, and adopting one
 crosses a clean architectural line. If "low deps" stays a hard
 constraint, the alternative is to hand-parse the frontmatter block
 and feed it to a minimal YAML subset parser (the keys
-claude-bottle uses are all flat string/list/dict — no anchors, no
+bot-bottle uses are all flat string/list/dict — no anchors, no
 multi-line block scalars, no implicit type coercion).
 
 If we don't want to commit to the move yet, the next-cheapest
 option is keeping JSON but splitting into per-file (option B ×
-option 1): `$HOME/.claude-bottle/bottles/<name>.json` +
-`$HOME/.claude-bottle/agents/<name>.json`. Most of the scaling
+option 1): `$HOME/.bot-bottle/bottles/<name>.json` +
+`$HOME/.bot-bottle/agents/<name>.json`. Most of the scaling
 wins; none of the body-prose or dependency story.
 
 ## Open questions
@@ -362,7 +362,7 @@ wins; none of the body-prose or dependency story.
 - **Does Claude Code object to extra frontmatter fields?** Test:
   drop a file with `bottle:` in `~/.claude/agents/` and see if CC
   warns / ignores / breaks. If it warns, we'd want a different
-  field name (e.g. `claude-bottle-bottle`) or a namespaced block.
+  field name (e.g. `bot-bottle-bottle`) or a namespaced block.
 - **Migration story.** Is the project willing to ship a one-shot
   `./cli.py migrate-manifest` command that does the JSON → MD
   conversion? Or do users just rewrite by hand from the new docs?
@@ -370,8 +370,8 @@ wins; none of the body-prose or dependency story.
   empty body, is the MD-with-frontmatter format still warranted?
   An alternative is YAML for bottles only (no body, but with
   comments) and MD+frontmatter for agents.
-- **Dotfiles vs not.** `$HOME/.claude-bottle/` or
-  `$HOME/claude-bottle/`? The hidden dotfile shape matches dev
+- **Dotfiles vs not.** `$HOME/.bot-bottle/` or
+  `$HOME/bot-bottle/`? The hidden dotfile shape matches dev
   conventions (`.config/`, `.ssh/`); the visible shape signals
   "this is a real thing you own."
 - **PyYAML hard dep, or minimal subset parser?** Trade-off between