@lunnoa/client 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunnoa/client",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "TypeScript SDK for building applications on top of Lunnoa Automate — typed client for the Public API (agents, workflows, executions, entities, knowledge, queues), SSE agent chat streaming, and deployment-specific codegen",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -34,26 +34,23 @@
     "typecheck": "tsc --noEmit",
     "check:codegen-sample": "node --experimental-strip-types scripts/check-codegen-sample.ts && tsc --noEmit -p scripts/tsconfig.codegen-sample.json",
     "test:acceptance": "tsx scripts/acceptance-soak.ts",
+    "prepare": "node -e \"for (const d of ['.cursor/skills', '.claude/skills']) require('fs').cpSync('skills', d, { recursive: true, force: true })\"",
     "prepublishOnly": "pnpm run build",
     "release": "semantic-release"
   },
   "dependencies": {
+    "@ai-sdk/react": "^3.0.230",
     "ai": "^6.0.199"
   },
   "peerDependencies": {
-    "@ai-sdk/react": "^3.0.0 || ^4.0.0",
     "react": "^18.0.0 || ^19.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
       "optional": true
-    },
-    "@ai-sdk/react": {
-      "optional": true
     }
   },
   "devDependencies": {
-    "@ai-sdk/react": "^3.0.230",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^12.0.0",

package/skills/lunnoa-client/SKILL.md

@@ -57,9 +57,10 @@ Run these before inventing resources or shipping UI code:
 3. **Discover before inventing** — prefer the CLI (JSON for agents), then
    the SDK: `npx @lunnoa/client tools list --json --for-agent`,
    `tools get <actionId> --json`, `apps list`, `connections list`,
-   `agents|workflows|entity-types|projects list`, `features`.
+   `agents|workflows|entity-types|tables|projects list`, `tables get <slugOrId>`,
+   `features`.
    SDK equivalents: `workflowApps.list()`, `agents.list`, `workflows.list`,
-   `entityTypes.list`, `discovery.enabledFeatures()`.
+   `entityTypes.list`, `tables.list`, `discovery.enabledFeatures()`.
    Do not invent catalogue action ids.
 4. **Run vs deploy** — Ad-hoc: `actions.run` / `runs.start` /
    `workflows.execute`. Durable shared automation: CLI
@@ -141,12 +142,12 @@ const { user, status, login, logout, verify2faLogin } = useLunnoaAuth();
 const lunnoa = useLunnoaClient(); // same client for entities / actions / chat
 const { progress } = useExecutionProgress(executionId);
 const { waiting, pendingInput, submitInput } = useNeedsInput(progress);
-const { messages, send, stop, taskId } = useAgentChat(agentId); // peer: @ai-sdk/react
+const { messages, send, stop, taskId } = useAgentChat(agentId);
 const { items, decide } = useApprovalsInbox({ pollIntervalMs: 15_000 });
 const { data, setPage } = useEntityList({ objectTypeSlug: 'invoice' });
 ```
 
-Peers: `react` ≥ 18 for `/react`; `@ai-sdk/react` only for `useAgentChat`.
+Peer: `react` ≥ 18 for `/react`. `@ai-sdk/react` ships with the SDK (no extra install).
 Errors are `LunnoaApiError` with `.status`, `.body`, `.isUnauthorized`,
 `.isForbidden`, `.isRateLimited`. A 403 means the key's role or the
 deployment's licence edition does not cover the endpoint.
@@ -193,8 +194,20 @@ const workflows = await lunnoa.workflows.list({ expansion: ['description', 'isAc
 const entityTypes = await lunnoa.entityTypes.list({
   expansion: ['attributeSchema', 'stateSchema'],
 });
+
+// Tables: small reference / lookup data (list omits rows; get includes them)
+const tables = await lunnoa.tables.list();
+const costCentres = await lunnoa.tables.getBySlug('cost_centres'); // or tables.get(id)
+await lunnoa.tables.upsertBySlug({
+  slug: 'cost_centres',
+  columns: [{ key: 'code' }, { key: 'owner' }],
+  rows: [{ code: 'CC-100', owner: 'Finance' }],
+}); // managedByCode defaults to true; omitted columns/rows are kept
 ```
 
+- Use a **Table** for slowly changing reference data under ~10k rows; anything
+  that grows per transaction (invoice, ticket, case) is an **entity**.
+
 - `attributeSchema.sections[].fields[]` defines each entity field: `id`
   (attribute key), `label`, `type` (`text`, `number`, `currency`, `date`,
   `dropdown` with `config.options`, `boolean`, ...), `required`. Build forms
@@ -430,8 +443,7 @@ for await (const chunk of stream) {
 }
 ```
 
-- **React apps:** prefer `useAgentChat` from `@lunnoa/client/react` (optional
-  peer `@ai-sdk/react`), which wraps AI SDK `useChat` + `DefaultChatTransport`
+- **React apps:** prefer `useAgentChat` from `@lunnoa/client/react`, which wraps AI SDK `useChat` + `DefaultChatTransport`
   pointed at
   `${baseUrl}/api/agents/${agentId}/tasks/${taskId}/stream-message` with an
   `Authorization` header. You can also wire `useChat` yourself. Use

package/skills/lunnoa-solution-design/SKILL.md

@@ -4,7 +4,7 @@ description: >-
   Acts as a Lunnoa business analyst / solution designer for vibecoders and
   partners. Interviews the human about triggers, actors, data, HITL, and
   integrations; maps intent to Lunnoa primitives (actions, workflows, agents,
-  entities, approvals, queues); produces a short build brief; then hands off
+  entities, tables, approvals, queues); produces a short build brief; then hands off
   to the lunnoa-client skill for implementation. Use when requirements are
   unclear, the user asks what to build on Lunnoa, how to design a workflow or
   agent, whether to use an agent vs workflow, or before writing @lunnoa/client
@@ -50,6 +50,7 @@ interrogation.
 ### Data and knowledge
 
 - Structured business records (invoice, order, ticket) → **Entities**
+- Small reference / lookup data (cost centres, price list) → **Tables**
 - Free-form conversation / reasoning → **Agent** chat
 - Documents / notebooks the model should search → **Knowledge**
 - Transient run output only → Executions / Tasks
@@ -86,9 +87,19 @@ interrogation.
 | Reusable automation + triggers | Saved **Workflow** (UI or CLI deploy) | Schedules/webhooks live on workflows |
 | Reasoning + tools + conversation | **Agent** | Tools = workflows, actions, knowledge |
 | Structured CRUD / portals | **Entities** + schemas | Codegen for typed accessors |
+| Reference / lookup data | **Tables** | `tables.upsertBySlug`; workflows use the Tables Lookup action |
 | Human review inbox | **Approvals** | |
 | Assigned human work items | **Queues** | |
 
+### Objects (entities) vs Tables
+
+- **Object (entity)** = a business record with identity and lifecycle
+  (invoice, ticket, case): states and state history, linked to
+  executions / agents / queues, has a business key, grows with transactions.
+- **Table** = small, slowly changing reference data (cost-centre mapping,
+  price list, country codes), under ~10k rows (rows live in one JSON blob).
+- Anything that grows per transaction is an **Object**, never a Table.
+
 ### Hard product rules (enforce these)
 
 1. **Agents have no schedules or event triggers.** If something must run on a
@@ -105,6 +116,10 @@ interrogation.
    automation → CLI `workflows deploy` / `agents deploy` by slug.
 5. **UI is headless.** `@lunnoa/client` has no design system. Optional React
    hooks in `@lunnoa/client/react`. Partners bring their own UI.
+6. **Reuse before create.** Before proposing any new entity type, table,
+   workflow, or agent, run `npx @lunnoa/client entity-types list --json`,
+   `tables list --json`, `workflows list --json`, and `agents list --json`.
+   The build brief must state explicitly what is **reused** vs **created**.
 
 ### Common anti-patterns to reject
 
@@ -134,15 +149,16 @@ can execute. Use this shape:
 
 ### Discovery (run first)
 - [ ] `npx @lunnoa/client tools list --json --for-agent` then `tools get <id>`
-- [ ] agents / workflows / entity-types / projects list — reuse before create
+- [ ] agents / workflows / entity-types / tables / projects list — reuse before create
 - [ ] codegen — if building typed entity/workflow accessors
 
-### Resources
-| Kind | Slug / id | Create or reuse | Notes |
+### Resources (every row says REUSED or CREATED)
+| Kind | Slug / id | Reused / created | Notes |
 |---|---|---|---|
 | Workflow | … | … | steps / trigger |
 | Agent | … | … | model, tools |
 | Entity type | … | … | if portal CRUD |
+| Table | … | … | reference / lookup data |
 | Knowledge | … | … | if RAG |
 
 ### Runtime paths