@abloatai/ablo 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.5.1
+
+### Patch Changes
+
+- Docs: add a React quick-start (provider + `useAblo`), plain-language rewrite, and a "Set up with Claude Code" section.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -8,7 +8,7 @@ silently overwrite each other, expose who's working on what, and leave a record
 of who changed what.
 
 ```txt
-schema -> ablo.<model>.create/load/update(...)
+schema -> ablo.<model>.create/retrieve/load/update/intent(...)
 ```
 
 ## Install
@@ -29,8 +29,7 @@ export ABLO_API_KEY=sk_test_...
 ```
 
 In the browser, connect through the React provider (`<AbloProvider>`), which
-authenticates with the signed-in user's session — never the raw API key. Do not
-ship `ABLO_API_KEY` in a browser bundle.
+authenticates with the signed-in user's session — never the raw API key.
 
 ## Quick Start
 
@@ -78,13 +77,58 @@ Pass `schema` to get typed models like `ablo.weatherReports.update(...)`. Omit i
 only for the lower-level client used by custom agents and MCP routes that can't
 import your app's schema.
 
-Run the package example from this directory:
+## React
 
-```bash
-cd examples
-ABLO_API_KEY=sk_test_... npx tsx quickstart.ts
+In a React app it's the **same `ablo.<model>` API** — just mounted through a
+provider and read with hooks, from `@abloatai/ablo/react`. Wrap your tree once;
+everything inside is live.
+
+```tsx
+import { AbloProvider, useAblo } from '@abloatai/ablo/react';
+import { schema } from './ablo.schema';
+
+function App() {
+  return (
+    <AbloProvider schema={schema}>
+      <Report id="report_stockholm" />
+    </AbloProvider>
+  );
+}
+
+function Report({ id }: { id: string }) {
+  // Reactive read: this re-renders whenever the row changes — whether you,
+  // a teammate, or an agent changed it.
+  const report = useAblo((ablo) => ablo.weatherReports.retrieve(id));
+  const ablo = useAblo();
+
+  if (!report) return null;
+
+  // Write: same method as the server example above. Optimistic; fans out.
+  return (
+    <button onClick={() => ablo?.weatherReports.update(id, { status: 'ready' })}>
+      {report.status}
+    </button>
+  );
+}
 ```
 
+`<AbloProvider>` owns the connection and authenticates with the signed-in user's
+session — no API key in the browser. That's the whole loop: read with
+`useAblo(selector)`, write with `ablo.<model>`, and every other client (human or
+agent) on that row sees it in real time. See [React](./docs/react.md) for
+`fallback`, `bootstrapMode`, presence, and status hooks.
+
+## Set up with Claude Code
+
+The package ships an `llms.txt` — a compact, LLM-readable map of the whole API.
+Point your coding agent at it and let it do the integration:
+
+> Read `node_modules/@abloatai/ablo/llms.txt`, then add an Ablo schema and
+> `<AbloProvider>` to this app and wire up my first create / retrieve / update.
+
+It scaffolds the schema, sets up the provider, and writes your first
+`ablo.<model>` calls — the same shape as the Quick Start above.
+
 For a production integration with React, an existing backend, Data Source, and
 future agents, read [Integration Guide](./docs/integration-guide.md).
 
@@ -190,24 +234,6 @@ Most reads are `retrieve` — it's the everyday path, especially inside `useAblo
   guarantee a row is hydrated before you read it — initial fetch, SSR, scripts, or
   any non-reactive runtime.
 
-## Persistence
-
-Ablo keeps local state in memory by default. That keeps the SDK focused on
-coordinating shared state, rather than silently turning every browser app into
-an offline database it didn't ask for.
-
-Opt into a durable browser cache and offline write queue when you want it:
-
-```ts
-const ablo = Ablo({
-  schema,
-  apiKey: process.env.ABLO_API_KEY,
-  persistence: 'indexeddb',
-});
-```
-
-Node, SSR, tests, and agents use volatile in-memory persistence automatically.
-
 ## Connect Your Database
 
 Every schema model has a backing store. By default, Ablo stores rows for the
@@ -216,30 +242,16 @@ write to Ablo-managed state.
 
 If your existing database stays the source of truth, connect it as a Data
 Source: Ablo sends signed commit requests to an endpoint you host, and your app
-writes its own database. Ablo never sees your database credentials — only the
-API key:
-
-```bash
-# stays in your app — Ablo never receives this
-DATABASE_URL=postgres://...
-
-# the only Ablo credential your app needs
-ABLO_API_KEY=sk_live_...
-```
+writes its own database. Your `DATABASE_URL` stays in your app — Ablo only ever
+sees the API key.
 
 See [Connect Your Database](./docs/data-sources.md) for the route and commit shape.
 
-## Agent Runs
-
-Most agent workers should import the same schema and use
-`ablo.<model>.load(...)` plus `ablo.<model>.update(...)`. The schema-less
-`agent.run(...)` wrapper exists for advanced workers that intentionally cannot
-import the app schema.
-
 ## Production Reference
 
 - [Guarantees](./docs/guarantees.md) — confirmed writes, stale-write protection, intent coordination, and agent lifecycle.
 - [Integration Guide](./docs/integration-guide.md) — pick the backing mode and integrate React, Data Source, multiplayer, and agents.
+- [React](./docs/react.md) — `<AbloProvider>`, `useAblo`, presence, status, and bootstrap gating.
 - [Client Behavior](./docs/client-behavior.md) — options, errors, retries, timeouts, and public imports.
 - [Connect Your Database](./docs/data-sources.md) — keep canonical rows in your app database without giving Ablo database credentials.
 - [Existing Python Backend](./docs/examples/existing-python-backend.md) — migrate existing Python endpoints to multiplayer and agent-safe writes gradually.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abloatai/ablo",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "State control API for AI agents and collaborative apps.",
   "license": "Apache-2.0",
   "type": "module",