@relvehq/agent-ready 0.2.1 → 0.3.1

package/README.md

@@ -8,10 +8,10 @@ they got before.
 - **Serve**: Markdown on `Accept: text/markdown`, on `<page>.md` and on
   `?format=md`, plus a generated [`/llms.txt`](https://llmstxt.org). No AI
   runs per request: it is plain code, in milliseconds.
-- **Refine** (optional, with your own prompt files): an AI model writes a
-  better Markdown file for each page ahead of time, a script checks every
-  number and URL against the page,
-  and unchanged pages are skipped on the next run.
+- **Refine** (optional, with your own OpenAI key): one command writes a
+  better Markdown file for each page ahead of time with Relve's prompt, a
+  check compares every number and URL against the page, and unchanged pages
+  are skipped (free) on the next run.
 - **Proof**: a free checker that scores any site out of 100, and a dashboard
   of which AI agents read which pages.
 
@@ -168,28 +168,50 @@ Most CDNs (CloudFront included) don't vary their cache on `Accept`, so:
   HTML. Safe, just not Markdown. `.md` URLs always work; reliable negotiation
   needs `Accept` in the CDN cache key.
 
-## Refine: better Markdown, written ahead of time
+## Refine: better Markdown with your own OpenAI key
+
+One command, run from your project root with `OPENAI_API_KEY` in `.env.local`,
+`.env` or the shell:
 
 ```
-npx agent-ready refine --site https://your-site.com --prompts ./prompts --sitemap --limit 20 --dry-run
-npx agent-ready refine --site https://your-site.com --prompts ./prompts --site-name "Your Name" --sitemap --limit 20
+npx agent-ready refine --site https://your-site.com --sitemap --dry-run
+npx agent-ready refine --site https://your-site.com --sitemap
 ```
 
-For each page: fetch it, extract its text, links, JSON-LD and a fingerprint;
-skip it if the fingerprint matches the saved file; otherwise fill the prompt,
-call the model once, check the result, retry once with the problems listed,
-and save `<out>/<path>.md` plus `<out>/<path>.json` (default out:
-`.agent-ready/md`). `--dry-run` only reads pages: no model call, nothing written.
-
-| Setting | |
+For each page the command fetches the HTML itself and sends it to the Relve
+API (`relvehq.com`) with your key in a header. Relve's prompt runs on Relve's
+server: it extracts the page, calls OpenAI with your key, checks the result
+(every number and URL must be on the page; one retry), and returns the
+Markdown. The command saves `<out>/<path>.md` plus `<out>/<path>.json`
+(default out: `.agent-ready/md`).
+
+- **Cost:** your own OpenAI usage, one model call per changed page (roughly
+  a few thousand tokens each with the default `gpt-4o`, about 1 to 2 cents a
+  page). Relve charges nothing.
+- **Your key:** used for that call only. Relve does not store or log it, and
+  it is never written to the output files.
+- **Re-run when content changes.** Each saved `.json` holds the page's
+  fingerprint; it is sent along, and an unchanged page comes back as
+  `unchanged` with no model call (free). `--force` rewrites everything.
+- **Optional in CI or deploy:** run the command before `next build` (with
+  `OPENAI_API_KEY` as a secret) and commit or ship `.agent-ready/md`.
+
+| Option | |
 |---|---|
-| `OPENAI_API_KEY` | OpenAI, default model `gpt-4o` |
-| `ANTHROPIC_API_KEY` | Claude, default model `claude-opus-5-5` |
-| `AGENT_READY_MODEL` | any other model id, e.g. `gpt-4o-mini` |
+| `--sitemap` / `--paths /a,/b` | which pages (sitemap at `<site>/sitemap.xml`) |
+| `--model` | `gpt-4o` (default, most accurate), `gpt-4.1`, `gpt-4.1-mini`, `gpt-4o-mini` (cheapest; can mix up whose price is whose on busy pages) |
+| `--site-name` | your brand name, used in the documents |
+| `--out`, `--limit`, `--concurrency` (2), `--force`, `--dry-run` | `--dry-run` lists the pages: no API call, nothing written |
+| `AGENT_READY_REFINE_ENDPOINT` | another API URL (testing) |
+
+The run ends with `written / unchanged / rejected / errors` and the token
+total. Rejected and failed pages are listed with their code (for example
+`too_little_text`) and nothing is saved for them; the exit code is then 1.
+If OpenAI rejects the key or your account is out of quota, the run stops at
+the first page and says so.
 
-Keys are read from `.env.local` and `.env`. Serve the files from the route
-file (`fileStore` is Node only, so keep it out of `agent-ready.config.ts`,
-which the Edge middleware imports):
+Serve the files from the route file (`fileStore` is Node only, so keep it
+out of `agent-ready.config.ts`, which the Edge middleware imports):
 
 ```ts
 // app/%5F%5Fmd/[[...path]]/route.ts
@@ -209,10 +231,14 @@ required section is missing, it has more or fewer than one H1, HTML tags, a
 wrong fingerprint, or it is over the token budget. It cannot catch a reworded
 claim, so read a sample before you switch on.
 
-**The prompt.** The package ships none. Point `refine` at a folder of prompt
-files with `--prompts <dir>` (several: `a,b`) or the `AGENT_READY_PROMPTS`
-variable (`.env.local`, `.env` or the shell); without one it stops before
-fetching anything. A prompt file is Markdown with `## SYSTEM`, `## USER`
+**Advanced: your own prompts.** The package ships no prompt. With
+`--prompts <dir>` (several: `a,b`) or the `AGENT_READY_PROMPTS` variable
+(`.env.local`, `.env` or the shell), `refine` runs your prompt files on your
+machine instead of calling the Relve API, with `OPENAI_API_KEY` (default
+model `gpt-4o`) or `ANTHROPIC_API_KEY` (default `claude-opus-5-5`);
+`AGENT_READY_MODEL` picks another model. The steps are the same: fetch,
+extract, skip unchanged, fill the prompt, one model call, check, one retry,
+save. A prompt file is Markdown with `## SYSTEM`, `## USER`
 (`{{PAGE_URL}}`, `{{PAGE_TEXT}}`, `{{PAGE_LINKS}}`, `{{JSON_LD}}`,
 `{{SOURCE_HASH}}`) and a `## Settings` table (`page_type`, `version`,
 `required_sections`, `token_budget`). A `page_type` of `page` takes every
@@ -327,8 +353,9 @@ if (d.markdown) {
 ```
 agent-ready init   [--stack next|node|wordpress] [--dry-run] [--force] [--cwd <dir>]
 agent-ready check  <url> [--json]
-agent-ready refine --site <origin> (--paths /a,/b | --sitemap) --prompts <dir> [--site-name <name>]
+agent-ready refine --site <origin> (--paths /a,/b | --sitemap) [--model <id>] [--site-name <name>]
                    [--out <dir>] [--limit <n>] [--force] [--concurrency <n>] [--dry-run]
+                   [--prompts <dir>]   (advanced: your own prompts, run locally)
 agent-ready stats  --log <hits.jsonl> [--days <n>] [--json]
 ```