bot-bottle/docs/research/polish-priorities.md

# Closing the maturity gap: polish priorities

Research into what would close the perceived maturity gap between
claude-bottle and a "polished" comparable like claudebox. Motivated
by adopter feedback citing first-run friction, manifest authoring,
and distribution as the dominant obstacles to recommending the tool
to others.

## Summary

"Polish" in tool-of-this-shape means a specific set of properties,
most of which aren't features. Ranked roughly by leverage on the
perceived maturity gap:

1. First-run friction reduction — no manifest authoring required
2. Error messages that tell the user what to do next
3. Single-command distribution (`brew`, `curl | sh`, `go install`)
4. Tagged releases and a real CHANGELOG
5. JSON schema for the manifest with editor integration
6. A starter library of bottles/agents for common shapes
7. A docs site, not just the README
8. Cross-platform CI

Realistic effort: 4–6 weeks of focused part-time work for one person.
The single highest-impact item is collapsing first-run setup from
"five steps including authoring JSON" to "one command produces a
working agent" — that one change closes most of the perceived
maturity gap on its own. Everything else compounds, but it compounds
on top of working onboarding.

## Dimensions in detail

### Onboarding friction

A first-time user today goes through five steps: install Docker,
install `uv`, set `CLAUDE_BOTTLE_OAUTH_TOKEN`, write
`claude-bottle.json`, run `./cli.py start`. One of those is
"author a JSON manifest." Polished tools in this category let
users skip that step on day one. The fix is an `init` subcommand
that drops a working `claude-bottle.json` with a default `coder`
bottle/agent into the user's home directory and prints the next
command to run.

### Error messages

Missing Docker, missing OAuth token, manifest typo, image build
failure — each should print a one-line fix rather than a stack
trace. claudebox handles this well; claude-bottle currently exits
on `die()` calls that vary in helpfulness. A focused pass over
every `die()` site, ensuring each message says what failed *and*
what to do, is cheap and compounds across every user interaction.

### Distribution

`brew install claude-bottle` or `curl | sh`, not "clone the repo,
install Python deps, `chmod cli.py`." The single highest-leverage
polish item, and the one that interacts with the language choice
covered in `bash-vs-python-vs-go.md`. Staying on Python means a
brew formula and a published `pip` package; switching to Go means
a single static binary via `goreleaser`. Either path is real work;
the Python path is shorter (~3 days) and the Go path produces a
better long-term distribution story (~1–2 weeks plus a rewrite).

### Versioning

Tagged releases with semver and a maintained CHANGELOG. Migration
notes when the manifest schema changes. The mechanical cost is
small; the signal value is large.

### Schema

A JSON schema for `claude-bottle.json` published with a `$schema`
URL gives VSCode and Cursor users autocomplete and inline
validation. ~½ day to author the schema, plus a few hours to
publish it where editors can fetch it.

### Starter library

A `contrib/` directory with five working bottle/agent pairs
covering common shapes — generic coder, sysadmin, data analyst,
research bot, deploy helper. Lowers the "I have a use case but no
template" threshold without requiring users to learn the manifest
format from scratch.

### Documentation site

A small site (mdBook, Docusaurus, or similar) with conceptual
overview, recipes, troubleshooting, and FAQ. Search. The README is
a landing page; the docs are the manual. Most published tools at
the maturity level being compared against have both.

### Cross-platform CI

Tests run against macOS arm64, macOS amd64, and Linux amd64 in CI.
Catches regressions in the test matrix surfaced in
`bash-vs-python-vs-go.md` before users do.

## Estimated ordering

Working from highest leverage downward, with rough effort estimates
for one person:

1. Quickstart with `init` subcommand and default manifest — 1 week
2. Error message audit + JSON schema — 3 days
3. Tagged release v0.1.0 + CHANGELOG — 1 day
4. Brew formula (Python path) or Go rewrite for single-binary
   distribution — 3 days to 2 weeks
5. Starter library + recipes — 1 week
6. Docs site — 1 week
7. Cross-platform CI — 3 days

Total: 4–6 weeks of focused part-time work. With realistic
side-project pacing, 3–4 months elapsed.

## What "polish" is not

Common conflations to avoid burning effort on:

- **More features.** The existing feature set is the right one; the
  gap is reliability and onboarding, not capability. Adding features
  before the existing ones feel finished moves perceived maturity in
  the wrong direction.
- **Marketing surface.** "Trusted by" logos and adoption pages are
  not the polish HN responds to. A docs site with real recipes is
  worth ten landing-page redesigns.
- **Aesthetic work.** The project already has a logo. Aesthetic
  polish is well below functional polish in priority.
- **A web UI.** Sometimes mentioned as a polish item; it isn't, at
  this stage. A web UI for browsing bottles is a feature; the
  current CLI works. Build the UI when distribution and onboarding
  are solved, not before.

## Recommendation

Treat the ordered list above as the polish roadmap and resist
deviating to feature work until at least items 1–4 ship. Item 1 (the
`init` subcommand and default manifest) is the single most valuable
change and should be done first regardless of what else gets cut.
Item 4 (single-command distribution) is the second most valuable and
the one that signals "this is a real tool" to a non-author reader
more than any other change.

The decision on item 4 — brew formula vs Go rewrite — should be
deferred until items 1–3 ship and the project has real adoption
data on whether Python distribution is causing bug reports. Until
then, the cheaper Python-path version is the right choice.