@odla-ai/cli 0.3.0 → 0.4.0

package/skills/odla/references/build.md

@@ -0,0 +1,58 @@
+# Build a new odla app (greenfield)
+
+Exact commands, verified against `@odla-ai/cli`. ⏸ marks a human step.
+
+## 1. Scaffold
+
+```
+npx @odla-ai/cli init --app-id my-app --name "My App"
+```
+
+Writes `odla.config.mjs`, `src/odla/schema.mjs`, `src/odla/rules.mjs`, and adds
+`.odla/*` + `.dev.vars` to `.gitignore`. Edit `schema.mjs` to declare your
+namespaces (e.g. `notes`). Leave `rules.mjs` as-is for now — provision generates
+deny-all rules from the schema. To turn on auth/observability, add `"o11y"` to
+`services` and an `auth.clerk` block in `odla.config.mjs` (init leaves it
+commented).
+
+## 2. Provision  ⏸ device-code approval
+
+```
+npx odla-ai provision --write-dev-vars
+```
+
+Prints a short device code and a link. ⏸ The human opens https://odla.ai, signs
+in, and approves the code — no secret passes through the chat. Provision then:
+creates the app, enables its services, mints the db key (and the o11y ingest
+token when o11y is enabled), pushes schema + rules, and writes `.dev.vars`
+(`0600`, gitignored). Verify with `npx odla-ai doctor` — it prints the app,
+envs, services, and flags anything unset.
+
+## 3. Build
+
+`npm i` only the SDKs you need (see `references/sdks.md`) and write the app. Read
+each package's `node_modules/@odla-ai/<pkg>/llms.txt` for its full API. The
+`examples/saas` app in the odla-ai repo is a complete realtime app to mirror.
+
+## 4. Run locally
+
+```
+npx wrangler dev
+```
+
+`wrangler dev` auto-loads `.dev.vars`. Exercise the app. A default-deny `403`
+means the namespace has no rule yet — add one in `src/odla/rules.mjs`
+(deliberately; e.g. `{ notes: { view: "auth.signedIn", create: "auth.signedIn" } }`),
+re-provision to push it, and retry.
+
+## 5. Ship  ⏸ human checkpoint
+
+Add `"prod"` to `envs`, provision again (prod tenant = the bare `appId`), then:
+
+```
+npx odla-ai secrets push --env prod --yes   # pushes ODLA_API_KEY (+ ODLA_O11Y_TOKEN if o11y)
+npx wrangler deploy
+```
+
+Verify with `npx odla-ai smoke --env prod`. Point env vars at the service custom
+domains, never `*.workers.dev` (Workers can't fetch same-account workers.dev).

package/skills/odla/references/sdks.md

@@ -0,0 +1,64 @@
+# odla SDK cheat-sheet
+
+Install only what the app needs. Every package ships an `llms.txt` in
+`node_modules/@odla-ai/<pkg>/` with the full, current API — read it. Minimal
+real usage below.
+
+## @odla-ai/db — realtime graph database
+
+Data is **namespaces** of rows, declared in `src/odla/schema.mjs`, gated by
+default-deny `src/odla/rules.mjs`. Isomorphic (browser + Worker).
+
+```ts
+// browser client — token from your IdP (Clerk):
+const db = init({ appId, endpoint, getToken });
+const { data } = useQuery({ notes: { $: { order: { createdAt: "asc" } } } });
+transact(db.tx.notes[crypto.randomUUID()].update({ text, createdAt: Date.now() }));
+```
+
+Worker/admin side: `init({ appId: tenantId, adminToken: env.ODLA_API_KEY, endpoint })`
+— the admin key bypasses rules, so a worker-mediated backend needs none.
+
+## @odla-ai/auth-clerk — sign-in (Clerk; runs on Preact or React)
+
+```tsx
+<ClerkGate publishableKey={pk} appearance={clerkAppearanceFromTokens()}>
+  <SignedOut><SignIn routing="hash" /></SignedOut>
+  <SignedIn>{/* useClerkAuth().getToken → db init; <UserButton/> signs out */}</SignedIn>
+</ClerkGate>
+```
+
+The publishable key is public; `provision` stores it (`setAuth`). Rules evaluate
+the signed-in user's JWT as `auth` — e.g. `auth.signedIn`, `auth.email`.
+
+## @odla-ai/ai — inference (Claude / GPT / Gemini)
+
+```ts
+const { ai } = await initFromPlatform({ platform, appId, env, db });
+await ai.chat({ messages }); // provider/model + key resolved from the platform vault
+```
+
+No API key in your code or env — it lives in the tenant vault; `provision`
+stores it when the configured `ai.keyEnv` is set at provision time.
+
+## @odla-ai/o11y — observability (Cloudflare Workers)
+
+```ts
+export default withObservability(handler);          // traces fetch/cron/bindings
+count("http.requests", 1, { "http.route": path });   // metrics
+recordError(err, { route, code });                   // structured errors
+```
+
+Set `ODLA_O11Y_ENDPOINT` + `ODLA_O11Y_SERVICE` (vars) and `ODLA_O11Y_TOKEN`
+(secret) — `provision` mints the token when `o11y` is in `services`. First-party
+hosting binds `ODLA_O11Y_COLLECTOR` instead (no endpoint/token).
+
+## Others
+
+- **@odla-ai/ui** — design system: CSS tokens, five themes, component styles,
+  chart helpers.
+- **@odla-ai/kg** — ontology-driven knowledge graph: source connectors, LLM
+  extraction, provenance-preserving writes.
+- **@odla-ai/blog** — static-first blogging; files in, site out.
+- **@odla-ai/apps** — control-plane SDK (create apps, toggle services); the CLI
+  and registry usually handle this for you.