# Plan: Make README.md and docs/index.html more catchy

## Problem

Both files currently read like feature checklists. The tagline ("A small, powerful, open-source CLI coding agent that works with open models") is accurate but bland. The feature cards are generic — "tool-calling loop", "sandboxed by default", "zero config" could describe half a dozen tools. Nothing grabs a reader and says *this is why you'd pick Swival*.

## Decisions

- **Positioning:** LM Studio and HuggingFace Inference API are presented as near-equal paths. LM Studio leads slightly (zero-config auto-discovery is the sharper hook) but HuggingFace is a first-class option, not an afterthought.
- **Quantitative claims:** Use rough order-of-magnitude phrasing ("a few thousand lines") instead of exact counts that go stale.
- **Competitors:** No competitor names in public copy. Keep positioning implicit.

## What actually makes Swival different

Ranked by how compelling they are to someone browsing GitHub:

1. **Your models, your way** — Swival connects to LM Studio or HuggingFace Inference API. With LM Studio, it auto-discovers your loaded model — zero config. With HuggingFace, point it at any supported model or your own dedicated endpoint. Either way, you pick the model and the infrastructure.

2. **Small enough to read and hack** — The entire agent is a few thousand lines of Python with no framework. You can read the whole thing in an afternoon. People who run local models tend to want to understand and modify their tools — Swival is built to be transparent.

3. **Portable skills** — The progressive-disclosure skills system (compact catalog in system prompt, full instructions loaded on demand, supporting files accessible via read_file) is a genuinely different approach from stuffing everything into a system prompt. Skills are directories with a SKILL.md file — easy to write, easy to share, easy to version.

4. **Think tool that works with any model** — Structured multi-step reasoning with revisions, branches, and persistent notes that survive context compaction. This works with any model that supports function calling — including your local Qwen or LLaMA.

5. **Evaluation reports** — `--report report.json` captures per-call LLM timing, tool success/failure, context compaction events, and guardrail interventions. Designed for systematically benchmarking local models on coding tasks.

6. **Unix-native** — stdout is exclusively the final answer. All diagnostics go to stderr. You can pipe Swival's output directly into another command or file.

## What to de-emphasize

- **Sandboxing** — Every serious agent has some form of sandboxing. It's not unique and not a complete security boundary. Keep it as a brief mention, not a headline feature.
- **"Tool-calling loop"** — Too generic. Every agent does this. Instead, mention the specific tools that are interesting (3-pass fuzzy edit matching, SSRF-protected fetch).
- **Provider details** — Both providers belong in the hero/tagline, but the specifics of configuring each one belong in the docs, not the landing page.
- **Context management** — Interesting technically but not a selling point for the landing page.

## Proposed changes

### README.md

**New tagline area:**
- Lead: "A coding agent for open models"
- Second line: something like "Swival connects to LM Studio or HuggingFace Inference API, sends your task, and runs an autonomous tool loop until the job is done. With LM Studio it auto-discovers your loaded model — zero config. A few thousand lines of Python, no framework."
- Kill the current "It's what I use every day" line — it's honest but doesn't sell

**New structure:**
1. One-liner + expanded tagline (2-3 sentences)
2. Quickstart (keep, it's good and short)
3. "What makes it different" section with 4-5 short paragraphs (not feature cards), each with a bold lead sentence:
   - Your models, your way (both providers)
   - Small enough to read and hack
   - Portable skills
   - Structured thinking for any model
   - Built for benchmarking (`--report`)
4. Documentation links (keep)

**Tone and style:**
- Direct, slightly opinionated, written by a human. Good English that flows well, not the stiff cadence of AI-generated copy.
- No em dashes. Use periods, commas, or parentheses instead.
- The current README is already close to this. Just needs sharper hooks.

### docs/index.html

**Hero section:**
- Change h1 to something punchier: "A coding agent for open models"
- Tagline paragraph: tighter, mention both LM Studio and HuggingFace up front, emphasize auto-discovery for LM Studio and model choice for HuggingFace
- Terminal example: keep as-is, it's clean

**Feature cards — replace the current four with:**
1. **Your models, your way** — Auto-discovers your LM Studio model, or point it at any HuggingFace model or dedicated endpoint. You pick the model and the infrastructure.
2. **Small and hackable** — A few thousand lines of Python, no framework. Read the whole agent in an afternoon. Modify it to fit your workflow.
3. **Portable skills** — Drop a SKILL.md in a directory, and the agent learns new capabilities on demand. Easy to write, share, and version.
4. **Built for benchmarking** — JSON evaluation reports capture timing, tool usage, and context events. Compare models systematically.

(Drop "sandboxed by default" and "tool-calling loop" as headline cards. Sandboxing can be a brief note under quickstart or a docs link.)

**Meta/OG/Twitter tags:**
- Update `<title>` to match new h1
- Update `<meta name="description">` to match new tagline
- Update all `og:title`, `og:description`, `twitter:title`, `twitter:description` to stay consistent with the new hero copy

**Quickstart section:** Present two parallel paths — LM Studio (current steps, keep them) and a short HuggingFace alternative (3 lines: set HF_TOKEN, install, run with `--provider huggingface --model ...`). Add a note about the REPL being good for exploration. Add a one-line callout near the quickstart steps (not in the hero): "Recommended first model: [qwen3-coder-next](https://huggingface.co/unsloth/Qwen3-Coder-Next-GGUF) — great quality/speed tradeoff on local hardware."

## What NOT to change

- The terminal mockup in index.html — it's visually effective
- The documentation links structure in README.md
- Keep existing LM Studio quickstart steps; add HF path without bloating the section
- The overall visual design / CSS of the landing page

## Done checklist

- [ ] README.md updated with new tagline, structure, and tone
- [ ] docs/index.html hero section updated
- [ ] docs/index.html feature cards replaced
- [ ] docs/index.html `<title>`, `<meta>`, OG, and Twitter tags all consistent with new hero copy
- [ ] No broken links (run `uv run --group website python build.py` which checks links)
- [ ] No hard-coded file/line counts that will go stale
- [ ] HuggingFace presented as near-equal with LM Studio (hero/tagline, feature cards, and quickstart)
- [ ] No competitor names in public-facing copy
- [ ] Eyeball mobile layout in browser (the CSS is already responsive, just verify nothing breaks)

## Out of scope

- **Logo redesign** — track separately as a design ticket; don't let it block this copy pass.
