@lunnoa/client 1.4.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunnoa/client",
-  "version": "1.4.0",
+  "version": "2.0.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",
@@ -39,22 +39,18 @@
     "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,13 +57,15 @@ 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 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
-   `npx @lunnoa/client workflows|agents deploy` (upsert by slug).
+   `npx @lunnoa/client workflows|agents deploy`. Upsert is by slug
+   inside the workspace on the API key. URL and API key are enough.
 5. **Toolkit boundary** — Client `defineAction` ≠ toolkit `createAction`.
 
 ---
@@ -141,12 +143,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 +195,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
@@ -306,7 +320,6 @@ const result = await lunnoa.actions.run({
   appId: 'http',
   actionId: 'http_action_send-request',
   // connectionId: '<Connection.id UUID>', // required if needsConnection + multiple
-  // projectId: '<project UUID>',          // required if multiple projects
   input: { method: 'GET', url: 'https://example.com' },
   name: 'Ping example',
 });
@@ -377,11 +390,11 @@ npx @lunnoa/client connections list --app gmail --json
 `tools get` returns `inputConfig` / `inputFields` and a `defineAction` sketch.
 `tools list` is compact; use `get` for the schema. `--json` is for coding agents.
 
-Deploy to Automate UI (upsert by slug; prefer CLI):
+Deploy to Automate UI (upsert by slug inside the workspace on the API key; prefer CLI):
 
 ```bash
-npx @lunnoa/client workflows deploy ./ping.ts --url … --api-key … --project-id …
-npx @lunnoa/client agents deploy ./triage.ts --url … --api-key … --project-id …
+npx @lunnoa/client workflows deploy ./ping.ts --url … --api-key …
+npx @lunnoa/client agents deploy ./triage.ts --url … --api-key …
 ```
 
 `defineAction` binds catalogue actions only. Toolkit `createAction` is a
@@ -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
 
@@ -130,19 +145,20 @@ can execute. Use this shape:
 
 ### Auth
 - Pattern: A (server API key) | B (browser JWT)
-- Notes: <CORS, BFF, project id, env vars>
+- Notes: <CORS, BFF, env vars LUNNOA_URL and LUNNOA_API_KEY>
 
 ### 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 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