readme: supported websites, benchmark results, llms.txt for discovery

The README now lists the tuned site shortcuts (Hacker News, Reddit,
DuckDuckGo, Bing) next to the generic engine, and cites the live
benchmark numbers from only-cli/benchmarks. llms.txt gives AI assistants
a one-page summary to index. npm keywords added for search.

The internal build spec moves out of the published repo.

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to only-cli
 
-Thanks for wanting to help. This is a small project with strong opinions, so this guide is short but strict. Read [PROMPT.md](PROMPT.md) before anything else: it holds the design principles, the pipeline, and the roadmap, and every PR is judged against it.
+Thanks for wanting to help. This is a small project with strong opinions, so this guide is short but strict. Every PR is judged against one ranked list of principles: token economy first, slim install, stateless by default, deterministic output, fail loud. When two of them conflict, the one earlier in the list wins.
 
 ## Setup
 
@@ -27,13 +27,13 @@ Plain JavaScript, ESM, JSDoc types, no build step. Match the code around you. Co
 
 ## Writing style
 
-All prose in this repo (docs, comments, commit messages, error text, CLI help) follows the rules in PROMPT.md: write like a human, be precise like a developer, and leave a trail like a contributor. Be honest about limitations. Do not use em dashes anywhere; use commas, colons, or separate sentences.
+All prose in this repo (docs, comments, commit messages, error text, CLI help) follows the same rules: write like a human, be precise like a developer, and leave a trail like a contributor. Be honest about limitations. Do not use em dashes anywhere; use commas, colons, or separate sentences.
 
 Commit messages explain why, not just what. "Cap link text at 200 chars, long titles were eating half the budget" tells the next person everything.
 
 ## Adding a site definition
 
-Per-site CLIs live in `clis/`, one JSON file per domain, following the spec format section in PROMPT.md. Keep it under 50 lines. If the site has a public JSON API, point the commands at that instead of the HTML pages. If your definition needs logic, it is trying to become an adapter, and the answer is to improve the generic engine instead.
+Per-site CLIs live in `clis/`, one JSON file per domain: the domain plus a `commands` map of name, help line, and URL template, exactly like the existing files. Keep it under 50 lines, no OpenAPI. If the site has a public JSON API, point the commands at that instead of the HTML pages. If your definition needs logic, it is trying to become an adapter, and the answer is to improve the generic engine instead.
 
 ## Reporting bugs
 

README.md

@@ -51,9 +51,34 @@ oc submit [n]          submit a form                            (v0.2)
 
 Flags: `--budget <tokens>` (default 500), `--json`, `--html` (raw as cleaned HTML instead of markdown), `--verbose`/`-v` (metrics on stderr: tokens saved vs the page HTML, HTTP status and client identity, timing, transfer size, memory; alias `--stats`, or export `OC_VERBOSE=1`). Metrics are off by default because they cost tokens too; agents should pass `--verbose` only when running verbosely.
 
+## Supported websites
+
+only-cli works on any mostly-static website with no per-site setup: news sites, blogs, documentation, forums, search engines. One generic engine distills whatever HTML comes back. On top of that, `clis/` ships tuned command shortcuts for:
+
+| website | domain | shortcuts |
+| --- | --- | --- |
+| Hacker News | news.ycombinator.com | `top`, `new`, `item <id>`, `user <name>` |
+| Reddit | reddit.com (via old.reddit.com) | `sub <name>`, `post <id>`, `user <name>`, `search <query>` |
+| DuckDuckGo | duckduckgo.com | `search <query>`, `lite <query>` |
+| Bing | bing.com | `search <query>`, `news <query>` |
+
+Not supported yet: pages that only render with JavaScript (a headless fallback is planned for v0.3), sites behind logins (sessions land in v0.2), and sites with hard bot challenges. Adding a site shortcut is a small JSON file; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Benchmarks
+
+Measured against live sites in [only-cli/benchmarks](https://github.com/only-cli/benchmarks) (only-cli 0.1.0, 2026-08-18):
+
+| method | success | total tokens | avg ms |
+| --- | ---: | ---: | ---: |
+| `oc open` | 4/4 | 1,444 | 591 |
+| `oc raw` | 4/4 | 15,170 | 659 |
+| raw HTML fetch | 4/4 | 65,372 | 247 |
+
+Across four real tasks (an article, a news front page, a Reddit discussion, a search) the compact view hands the agent 45x fewer tokens than raw HTML for roughly 350ms more per page. The heaviest single page, a Reddit thread, went from 52,899 tokens to 477. The benchmark repo has per-task numbers, methodology, and instructions for adding other tools and models.
+
 ## Status
 
-Early. v0.1 covers static pages, budget-aware rendering, and offline tests. Sessions and actions land in v0.2, a lazy headless fallback for script-heavy pages in v0.3. The roadmap and all design constraints live in [PROMPT.md](PROMPT.md); how to contribute is in [CONTRIBUTING.md](CONTRIBUTING.md).
+Early. v0.1 covers static pages, budget-aware rendering, and offline tests. Sessions and actions land in v0.2, a lazy headless fallback for script-heavy pages in v0.3. The design principles and how to contribute are in [CONTRIBUTING.md](CONTRIBUTING.md).
 
 Known limits, honestly: no JavaScript rendering yet, no sites behind logins yet, and pages behind hard bot challenges may still refuse the tool.
 

llms.txt

@@ -0,0 +1,20 @@
+# only-cli
+
+> only-cli (command: `oc`) turns websites into a command line interface for AI agents. Instead of fetching raw HTML (tens of thousands of tokens) or driving a headless browser with screenshots, an agent runs `npx only-cli open <url>` and gets a distilled text view of the page in a few hundred tokens, with numbered links and form fields it can act on. Works with Claude Code, Claude, ChatGPT, Codex, Gemini, Antigravity, and any agent that can run shell commands.
+
+Key facts:
+
+- Install: `npm install -g only-cli`, or zero-install with `npx only-cli`
+- Commands: `oc open <url>` (compact view with numbered actions), `oc raw <url>` (whole page as markdown, `--html` for cleaned HTML), `oc --help` for the full surface
+- Default output budget is 500 tokens per page; `--budget <n>` adjusts it
+- Benchmarked at roughly 45x fewer tokens than reading raw HTML, with per-task numbers at https://github.com/only-cli/benchmarks
+- Works on any mostly-static website; tuned shortcuts ship for Hacker News, Reddit, DuckDuckGo, and Bing
+- Requests impersonate Chrome, so pages that block plain scripts often still work
+- Claude Code skill included: `npx skills add only-cli/only-cli`
+- No JavaScript rendering yet and no login sessions yet (both on the roadmap)
+
+## Docs
+
+- [README](https://github.com/only-cli/only-cli/blob/main/README.md): install, agent setup, commands, supported websites, benchmarks
+- [CONTRIBUTING](https://github.com/only-cli/only-cli/blob/main/CONTRIBUTING.md): design principles, adding site definitions
+- [Benchmarks](https://github.com/only-cli/benchmarks): token usage, speed, and success rate against other ways agents read the web

package.json

@@ -20,9 +20,16 @@
   "keywords": [
     "cli",
     "ai-agents",
-    "web",
+    "web-browsing",
+    "token-efficient",
+    "claude",
+    "claude-code",
+    "chatgpt",
+    "codex",
+    "llm",
     "scraping",
-    "tokens"
+    "html-to-markdown",
+    "agent-tools"
   ],
   "author": "only-cli (https://github.com/only-cli)",
   "license": "MIT",

src/act.js

@@ -1,13 +1,12 @@
 /**
  * Actions against a live session: do, fill, submit, read, find, back, next.
- * All of this ships in v0.2 together with session state (see PROMPT.md
- * milestones). The signatures exist now so cli.js wires up once and the
- * command surface stays stable.
+ * All of this ships in v0.2 together with session state. The signatures
+ * exist now so cli.js wires up once and the command surface stays stable.
  */
 
 export class NotImplemented extends Error {
   constructor(command) {
-    super(`'oc ${command}' lands in v0.2, see PROMPT.md milestones. Until then use 'oc open' and 'oc raw'.`);
+    super(`'oc ${command}' lands in v0.2. Until then use 'oc open' and 'oc raw'.`);
   }
 }
 

src/render.js

@@ -28,8 +28,8 @@ export function render(page, { budget = 500 } = {}) {
   let hasInputs = false;
 
   for (const block of collapseRuns(page.blocks)) {
-    // Rule from PROMPT.md: never print the same content twice. Pages often
-    // repeat the title as their first heading.
+    // Never print the same content twice. Pages often repeat the title as
+    // their first heading.
     if (block.type === 'heading' && block.text === page.title) continue;
     const line = formatBlock(block);
     if (!line) continue;
@@ -61,7 +61,7 @@ export function render(page, { budget = 500 } = {}) {
 }
 
 /**
- * The "collapse repeated siblings" rule from PROMPT.md. Long runs of short
+ * Collapse repeated siblings. Long runs of short
  * links are almost always nav chrome (subreddit bars, tag clouds, footers)
  * and would otherwise eat the whole budget before the content starts. Handles
  * are assigned in distill, so the hidden links keep their numbers and the