Rewrite the README for first-time readers

Author: TheGreatAxios

README.md

@@ -1,12 +1,16 @@
 # @corbits/embedding
 
-One API for every embedding provider. Point at any OpenAI-compatible `/v1/embeddings` endpoint, swap models with a config change, and get ordered vectors back.
+Embedding vectors for Interchange agents: a retrieval primitive (a small search building block) that plugs into `@intx/inference`.
 
-OpenAI, Ollama, TEI, vLLM, and Jina all serve the same wire shape. This package is one code path over that shape, with parameters for what varies between providers:
+An embedding is a list of numbers that captures what a piece of text means. Similar texts get similar numbers, so you can search by meaning. This package sends your text to an embedding model and gives you the vectors back in order. It works with any server that speaks the OpenAI embeddings format, including OpenAI, Ollama, TEI, vLLM and Jina. To switch models, change the config. It does not store or search vectors. For that, pair it with [`@corbits/memory`](https://github.com/corbitsdev/corbits-memory).
 
-- `dimensions` — Matryoshka truncation for models that support it, including OpenAI `text-embedding-3` (down to 256), Jina v3 (32), and Jina v4 (128). Sent only when set, so models without MRL stay happy.
-- `encodingFormat` — `float` (default) or compact `base64`.
-- `batchSize` — inputs per request (default 32). Tune it to provider caps and per-request token ceilings.
+## Where it fits
+
+[Interchange](https://github.com/faremeter/interchange) runs AI agents with their own identity and permissions. Corbits packages add the parts an agent product needs around it.
+
+- **Runs in:** any process. That can be the Interchange hub (the server that manages tenants and agents), an agent sidecar (the runtime next to each agent), or a plain script. No hub is needed.
+- **Plugs into:** [`@intx/inference`](https://github.com/faremeter/interchange) for retries and error types, and [`@intx/types`](https://github.com/faremeter/interchange).
+- **Pairs with:** [`@corbits/reranking`](https://github.com/corbitsdev/corbits-reranking) to sort search results, and [`@corbits/memory`](https://github.com/corbitsdev/corbits-memory) to store and search vectors.
 
 ## Install
 
@@ -18,6 +22,8 @@ Runs on Bun >= 1.2 or Node >= 24.
 
 ## Quickstart
 
+This example needs a local Ollama with the model pulled: `ollama pull nomic-embed-text`.
+
 ```ts
 import { embedTexts } from "@corbits/embedding";
 
@@ -30,24 +36,73 @@ const vectors = await embedTexts(["a", "b"], config);
 console.log(vectors.length, vectors[0]?.length); // 2 768
 ```
 
-`embedTexts(texts, config, options?)` batches sequentially, posts each batch to
-`{baseURL}/embeddings`, and returns vectors in input order. `options` is
-optional: `deps` (defaults to global `fetch` and `@intx/inference`'s
-`createDefaultScheduler()`),
-`retryPolicy`, `extractRetryAfterMs`, and `signal`.
+## Reference
+
+| Export                                       | Description                                                 |
+| -------------------------------------------- | ----------------------------------------------------------- |
+| `embedTexts(texts, config, options?)`        | Embeds the texts and returns one vector per text, in order. |
+| `probeEmbedDims(config, options?)`           | Embeds one test string and returns the vector length.       |
+| `EmbedConfigSchema`, `EmbedConfig`           | Schema and type for `config`.                               |
+| `EmbedOptions`                               | Type for `options`.                                         |
+| `EmbeddingRequestError`                      | Thrown when a request fails.                                |
+| `RequestDependencies`, `RetryAfterExtractor` | Types for `options.deps` and `options.extractRetryAfterMs`. |
+
+### Config
 
-## Dimensionality
+| Field            | Type                   | Description                                                                |
+| ---------------- | ---------------------- | -------------------------------------------------------------------------- |
+| `baseURL`        | `string`               | Server root with its version path, such as `http://host:11434/v1`.         |
+| `model`          | `string`               | Model name.                                                                |
+| `apiKey`         | `string?`              | Sent as a bearer token.                                                    |
+| `dimensions`     | `number?`              | Asks for shorter vectors. Only some models support it. Sent only when set. |
+| `encodingFormat` | `"float" \| "base64"?` | Wire format. Defaults to `float`. You always get numbers back.             |
+| `batchSize`      | `number?`              | Texts per request. Defaults to 32.                                         |
+| `timeoutMs`      | `number?`              | Time limit per request. Defaults to 30000.                                 |
 
-`probeEmbedDims(config)` embeds one probe string and reports the length received. Dimensionality follows the provider and the `dimensions` setting, so callers that persist vectors discover it at startup and treat a model swap as a migration. Representative widths: 1536 for OpenAI `text-embedding-3-small`, 768 for `nomic-embed-text`, 384 for `bge-small-en-v1.5`.
+### Options
 
-## Errors
+| Field                 | Description                                                                     |
+| --------------------- | ------------------------------------------------------------------------------- |
+| `deps`                | `{ fetch, scheduler }`. Defaults to global `fetch` and Interchange's scheduler. |
+| `retryPolicy`         | Decides when to retry. Defaults to Interchange's policy.                        |
+| `extractRetryAfterMs` | Reads how long the server asks you to wait. Defaults to `Retry-After`.          |
+| `signal`              | Cancels the requests.                                                           |
 
-Every request failure — transport, HTTP status, or a 200 with an unexpected body — throws `EmbeddingRequestError` (`extends Error`), carrying the classified `InferenceError` as `reason` and the request `url`. A config that fails `EmbedConfigSchema` throws arktype's `TraversalError` before any request.
+### Errors
+
+A failed request throws `EmbeddingRequestError`. Its `reason` says what went wrong, and `url` says where. A bad config throws before any request is sent.
+
+### Vector length
+
+Each model returns vectors of a fixed length. `nomic-embed-text` returns 768 numbers, and OpenAI `text-embedding-3-small` returns 1536. If you store vectors, call `probeEmbedDims` at startup to learn the length. Changing models changes the length, so treat it like a database migration.
 
 ## Using with Interchange
 
-Requests go through `deps.fetch`, failures are classified into `@intx/inference`'s `InferenceError`, and `createDefaultRetryPolicy` decides retries: a 429 backs off and retries, a credential failure does not. `@intx/inference` and `@intx/types` are peer dependencies, so the host's Interchange version is the one used.
+`@intx/inference` and `@intx/types` are peer dependencies. Your host's Interchange version supplies them. Rate limits (HTTP 429) are retried after a pause. Bad credentials are not retried.
+
+The scheduler is the Interchange object that times retries. To share one with the rest of your host, pass it in:
+
+```ts
+import { createDefaultScheduler } from "@intx/inference";
+import { embedTexts } from "@corbits/embedding";
+
+const scheduler = createDefaultScheduler();
+const config = {
+  baseURL: "http://localhost:11434/v1",
+  model: "nomic-embed-text",
+};
+const vectors = await embedTexts(["hello"], config, {
+  deps: { fetch, scheduler },
+});
+```
+
+## Upgrading from 0.1
+
+- Install `@intx/inference` and `@intx/types` (^0.4.0) yourself. They are now peer dependencies.
+- `ModelRequestError` is renamed to `EmbeddingRequestError`.
+- `runJSONRequest`, `extractRetryAfterMs` and `RunRequestOptions` are no longer exported. To change how retry waits are read, pass `options.extractRetryAfterMs`.
+- Config and returned vectors are unchanged.
 
 ## License
 
-LGPL-2.1-only — see [`LICENSE`](LICENSE).
+[LGPL-2.1-only](https://github.com/corbitsdev/corbits-embedding/blob/main/LICENSE)