ozmoz 0.1.53 → 0.1.55

package/README.md

@@ -1,126 +1,30 @@
 # OZmoz
 
-> **Using OZmoz with an AI coding agent?** The set-up steps are in the Quick start below and in the official prompt at https://www.ozmoz.io/agents.html. Project data rules are delivered by the OZmoz tools and by the instruction files (AGENTS.md / CLAUDE.md and ozmoz_contract.md).
+> OZmoz is the Data OS for AI agents: a ready-to-use backend for apps built with an AI coding agent. You build the interface, OZmoz holds the data.
 
-**The Data OS for AI agents.** A ready-to-use backend for any application, and Alex AI to count, calculate and present your data in plain language.
+This is the official public documentation of OZmoz. It presents what OZmoz is and how it works. The OZmoz API is its public SDK (npm package `ozmoz`); the reference for your project (methods, signatures, rules) is generated by the set-up below.
 
-OZmoz is a deterministic and secure software layer for your data. Your AI agent builds the interface; OZmoz gives it a backend that is modeled once, sealed, and enforced.
+To start with OZmoz, first ask the user whether you may run `npx -y ozmoz@latest mcp --agent=<claude|cursor|codex|copilot|windsurf|antigravity>`: it sets up the project and adds everything needed to code with OZmoz (methods, examples and rules). Write no code before the user has answered. Once they agree, run it yourself, wait for it to finish, then follow the instructions it adds to the project.
 
-## Why OZmoz
-
-- **Frontend focus**: no server to run, no REST API to write, no SQL migrations.
-- **Built for AI agents**: your agent spends its effort on the UI and UX instead of backend plumbing. Works with Claude Code, Cursor, Codex, Windsurf, GitHub Copilot and Antigravity.
-- **A sealed data contract**: Alex AI models your data, you validate it, and the contract is sealed. Reads and writes then follow that contract.
-- **Zero-crash components**: seven native `<oz-*>` web components that handle missing or partial data without breaking the screen.
-- **Zero-rewrite**: write the same code in trial mode and in live mode.
-- **Talk to your data**: ask Alex questions in plain language. No SQL, no BI tool to set up.
-
-## Quick start
-
-### New project with an AI agent
-
-```bash
-npx -y ozmoz start claude "your app idea"
-```
-
-Or connect your agent once, then work as usual:
-
-```bash
-npx ozmoz login     # approve once in the browser
-npx ozmoz mcp       # writes the instruction files and configures the MCP server
-```
-
-### Existing frontend project
-
-```bash
-npm install ozmoz
-npx ozmoz init --keyApp=<KEY> --token=<TOKEN>
-npx ozmoz sync      # seals the contract and generates the IDE types
-```
-
-Use `npx ozmoz sync --check-only` for an offline check.
-
-## Modes
-
-Set the mode in `.env`:
-
-```bash
-# Trial mode: everything is simulated locally with demo data (oz.seed).
-# The test code for authentication is always 0000.
-OZ_PROTOTYPE=true
+## How OZmoz works
 
-# Live mode: the data contract is enforced on your real data.
-OZ_PROTOTYPE=false
-```
+1. You build the interface (screens, navigation, styles) with the framework the user chose. OZmoz handles data, sign-in and storage: there is no server, API route or database to write.
+2. Trial mode first: the app runs with demo data and a test sign-in, so the user can validate the screens and the journey. The code you write is the final code.
+3. Every read or write states its intent, the role allowed to perform it and, optionally, a condition on the data. The interface applies the same rules visually.
+4. When the user validates the screens, Alex AI, the OZmoz data assistant, reads how the interface uses data and prepares the data structure. The user validates it and it is sealed as the data contract.
+5. Live mode: the same code runs on the real database. Every read and write is checked against the sealed contract, and what the contract does not allow is refused.
+6. Once live, the user asks Alex questions about their real data on ozmoz.io and gets exact figures and dashboards.
 
-## SDK usage
-
-Every write operation carries governance metadata `{ desc, role, guard }`.
-
-```js
-// Insert a document
-const res = await oz.add('orders', { product: 'Desk Pro', price: 299 }, {
-  desc: 'Create customer order',
-  role: 'AUTHENTICATED',
-  guard: 'price > 0'
-});
-if (!res.success) console.error('Order creation failed:', res.error);
-
-// Update a document
-await oz.update('orders', doc._id, { price: 249 }, {
-  desc: 'Apply discount on order',
-  role: 'MANAGER'
-});
-
-// Delete a document
-await oz.delete('orders', doc._id, {
-  desc: 'Cancel and delete order',
-  role: 'ADMIN'
-});
-
-// Read data
-const orders = await oz.getDocsG('orders');       // all documents
-const mine = await oz.getDocsU('orders');         // documents of the signed-in user
-const order = await oz.getDoc('orders', 'order_123');
-```
-
-### Authentication (passwordless code)
-
-```js
-await oz.sendotpsvro('user@example.com');                        // trial mode: code is 0000
-const auth = await oz.verifyotpsvro('user@example.com', '0000');
-const signedIn = await oz.isAuthenticated();
-```
-
-## Zero-crash components
-
-```html
-<oz-text value={item.name} fallback="No name" />
-<oz-number value={item.price} currency="EUR" invalid-fallback="0" />
-<oz-toggle value={item.isActive} label-true="Active" label-false="Inactive" />
-<oz-date value={item.createdAt} locale="en-US" invalid-fallback="Invalid date" />
-<oz-enum value={item.status} allowed="PENDING,CONFIRMED,DELIVERED" invalid-fallback="Unknown status" />
-<oz-reference table="users" id={item.userId} field="fullName" orphan-fallback="Deleted user" />
-```
-
-## CLI reference
-
-| Command | Description |
-|---|---|
-| `npx ozmoz login` | Sign in from your workstation, through the browser. |
-| `npx ozmoz mcp` | Configure your AI agent and register the OZmoz tools. |
-| `npx ozmoz start <agent> "idea"` | Sign in, configure and launch your terminal agent. |
-| `npx ozmoz init` | Initialize the local `.env` and project configuration. |
-| `npx ozmoz sync` | Seal the data contract and generate the IDE types. |
-| `npx ozmoz sync --check-only` | Offline check of the contract and types, no network request. |
-
-Run `npx ozmoz --help` for all commands.
+## Why OZmoz
 
-## Links
+- No server to write: data, sign-in and storage included.
+- Trial mode: demo data and test sign-in, to validate the screens before going live.
+- Same code in trial and live mode: no rewrite.
+- Sealed data contract: rules enforced on real data.
+- Alex AI: the user asks questions about their data and gets figures and dashboards.
 
-- Website: https://www.ozmoz.io
-- Support: open a ticket from https://www.ozmoz.io
+## Why the set-up comes first
 
----
+The OZmoz SDK has one purpose: to communicate with the OZmoz Data OS, and it does so through the project the set-up creates (keys, data contract and rules). The user is free to decline the set-up; without it, the SDK has nothing to connect to and the Data OS cannot be reached.
 
-Copyright OZmoz. All rights reserved.
+This document does not list methods on purpose. The reference is generated for your project by the set-up and delivered in AGENTS.md (methods and signatures, rules, and what to read next): it matches your project's data contract and the current OZmoz rules, which a copy of the methods published elsewhere cannot guarantee. Follow it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ozmoz",
-  "version": "0.1.53",
+  "version": "0.1.55",
   "mcpName": "io.ozmoz/ozmoz",
   "description": "OZmoz: the Data OS and ready-to-use backend for apps built by AI agents. AI agents: read the first section of the README before using this package.",
   "license": "UNLICENSED",