@carthooks/arcubase-cli 0.1.4 → 0.1.5

package/dist/tests/execute_validation.test.js

@@ -60,6 +60,61 @@ test('admin api-prefixed command executes against external root path', async ()
     assert.equal(out.kind, 'result');
     assert.equal(out.data.url, 'https://arcubase.example.com/apps/app_1/entity-shares');
 });
+test('app inventory returns apps with entity lists', async () => {
+    const calls = [];
+    const out = await executeCLI('admin', ['app', 'inventory'], env, async (url, init) => {
+        calls.push(`${init?.method ?? 'GET'} ${String(url)}`);
+        if (String(url) === 'https://arcubase.example.com/apps') {
+            return new Response(JSON.stringify({
+                data: [
+                    { id: 101, name: 'Workspace' },
+                    { id: 102, name: 'CRM' },
+                ],
+            }), { status: 200 });
+        }
+        if (String(url) === 'https://arcubase.example.com/apps/101/entities') {
+            return new Response(JSON.stringify({
+                data: [
+                    { id: 201, name: 'Orders' },
+                    { id: 202, name: 'Customers' },
+                ],
+            }), { status: 200 });
+        }
+        if (String(url) === 'https://arcubase.example.com/apps/102/entities') {
+            return new Response(JSON.stringify({
+                data: [
+                    { id: 203, name: 'Leads' },
+                ],
+            }), { status: 200 });
+        }
+        return new Response('{}', { status: 404 });
+    });
+    assert.equal(out.kind, 'result');
+    assert.deepEqual(out.data, {
+        apps: [
+            {
+                id: '101',
+                name: 'Workspace',
+                entities: [
+                    { id: '201', name: 'Orders' },
+                    { id: '202', name: 'Customers' },
+                ],
+            },
+            {
+                id: '102',
+                name: 'CRM',
+                entities: [
+                    { id: '203', name: 'Leads' },
+                ],
+            },
+        ],
+    });
+    assert.deepEqual(calls, [
+        'GET https://arcubase.example.com/apps',
+        'POST https://arcubase.example.com/apps/101/entities',
+        'POST https://arcubase.example.com/apps/102/entities',
+    ]);
+});
 test('admin save entity treats top-level error body as failure even on http 200', async () => {
     const bodyFile = tempJSONFile({
         id: 2188889845,
@@ -183,7 +238,7 @@ test('delete entity row rejects selection type outside ids', async () => {
         },
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'delete-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('user', ['rows', 'delete-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
     }, (error) => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
@@ -228,7 +283,7 @@ test('selection action accepts condition selection with selectAll', async () =>
             ],
         },
     });
-    const out = await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    const out = await executeCLI('user', ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
     assert.equal(out.kind, 'result');
     assert.equal(out.data.selection.type, 'condition');
     assert.equal(out.data.selection.condition.selectAll, true);
@@ -244,7 +299,7 @@ test('selection action accepts condition selection with filter_* keys', async ()
             },
         },
     });
-    const out = await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    const out = await executeCLI('user', ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
     assert.equal(out.kind, 'result');
     assert.equal(out.data.selection.type, 'condition');
     assert.equal(out.data.selection.condition.selectAll, true);
@@ -259,7 +314,7 @@ test('selection action accepts condition selection with selectAll only for batch
             },
         },
     });
-    const out = await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'batch_print', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    const out = await executeCLI('user', ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'batch_print', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
     assert.equal(out.kind, 'result');
     assert.equal(out.data.selection.type, 'condition');
     assert.equal(out.data.selection.condition.selectAll, true);
@@ -270,7 +325,7 @@ test('selection action accepts all selection for query-style actions', async ()
             type: 'all',
         },
     });
-    const out = await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
+    const out = await executeCLI('user', ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile], env, async (_url, init) => new Response(String(init?.body ?? '{}'), { status: 200 }));
     assert.equal(out.kind, 'result');
     assert.equal(out.data.selection.type, 'all');
 });
@@ -286,7 +341,7 @@ test('selection action rejects condition selection for query action', async () =
         },
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('user', ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'query', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
     }, (error) => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
@@ -301,7 +356,7 @@ test('selection action rejects all selection for archive action', async () => {
         },
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('user', ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
     }, (error) => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
@@ -320,7 +375,7 @@ test('selection action rejects selectAll-only condition for archive action', asy
         },
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('user', ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
     }, (error) => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
@@ -337,7 +392,7 @@ test('insert entity rejects local file path for file field and points to arcubas
     });
     const calls = [];
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
+        await executeCLI('user', ['rows', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
             calls.push({ url: String(url), method: init?.method });
             if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
                 return new Response(JSON.stringify({
@@ -378,7 +433,7 @@ test('update row rejects object value for image field and requires upload array'
         },
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async (url, init) => {
+        await executeCLI('user', ['rows', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async (url, init) => {
             if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
                 return new Response(JSON.stringify({
                     data: {
@@ -416,7 +471,7 @@ test('insert entity accepts upload array for file field after schema preflight',
         },
     });
     const calls = [];
-    const out = await executeCLI('user', ['workflow', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
+    const out = await executeCLI('user', ['rows', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
         calls.push({ url: String(url), method: init?.method });
         if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
             return new Response(JSON.stringify({
@@ -454,7 +509,7 @@ test('insert entity decorates upload bind failures with actionable guidance', as
         },
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
+        await executeCLI('user', ['rows', 'insert-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async (url, init) => {
             if (String(url) === 'https://arcubase.example.com/entity/app_1/entity_1' && init?.method === 'GET') {
                 return new Response(JSON.stringify({
                     data: {
@@ -492,7 +547,7 @@ test('selection action rejects condition selection without selectAll', async ()
         },
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('user', ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
     }, (error) => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
@@ -512,7 +567,7 @@ test('selection action rejects condition selection that uses text_search instead
         },
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('user', ['rows', 'query-entity-selection', '--app-id', 'app_1', '--entity-id', 'entity_1', '--action', 'archive', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
     }, (error) => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
@@ -604,7 +659,7 @@ test('query entity rejects camelCase viewMode and points to row crud doc', async
         viewMode: 'grid',
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'query-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('user', ['rows', 'query-entity', '--app-id', 'app_1', '--entity-id', 'entity_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
     }, (error) => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
@@ -624,7 +679,7 @@ test('update entity row rejects fields key', async () => {
         changed_fields: [1002],
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('user', ['rows', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
     }, (error) => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');
@@ -641,7 +696,7 @@ test('update entity row rejects changed_fields that are missing from data', asyn
         changed_fields: [1003],
     });
     await assert.rejects(async () => {
-        await executeCLI('user', ['workflow', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
+        await executeCLI('user', ['rows', 'update-entity-row', '--app-id', 'app_1', '--entity-id', 'entity_1', '--row-id', 'row_1', '--body-file', bodyFile], env, async () => new Response('{}', { status: 200 }));
     }, (error) => {
         assert.ok(error instanceof CLIError);
         assert.equal(error.code, 'BODY_VALIDATION_FAILED');

package/dist/tests/help.test.js

@@ -24,9 +24,10 @@ test('module help prints create-entity command', async () => {
     const out = await executeCLI('admin', ['app', '--help'], env, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
     assert.match(out.text, /create-entity/);
+    assert.match(out.text, /inventory/);
 });
 test('module help does not require runtime env', async () => {
-    const out = await executeCLI('user', ['workflow', '--help'], undefined, async () => new Response('{}'));
+    const out = await executeCLI('user', ['rows', '--help'], undefined, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
     assert.match(out.text, /delete-entity-row/);
 });
@@ -37,19 +38,19 @@ test('command help prints normalized external endpoint', async () => {
     assert.doesNotMatch(out.text, /endpoint: \/api\//);
 });
 test('command help does not require runtime env', async () => {
-    const out = await executeCLI('user', ['workflow', 'delete-entity-row', '--help'], undefined, async () => new Response('{}'));
+    const out = await executeCLI('user', ['rows', 'delete-entity-row', '--help'], undefined, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
     assert.match(out.text, /endpoint: \/entity\/:app_id\/:entity_id\/delete-item/);
 });
 test('command help prints runtime doc hints for request body commands', async () => {
-    const out = await executeCLI('user', ['workflow', 'update-entity-row', '--help'], undefined, async () => new Response('{}'));
+    const out = await executeCLI('user', ['rows', 'update-entity-row', '--help'], undefined, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
     assert.match(out.text, /docs:/);
     assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/row-crud\.md/);
     assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/README\.md/);
 });
 test('command help prints query-file support', async () => {
-    const out = await executeCLI('user', ['workflow', 'query-entity', '--help'], undefined, async () => new Response('{}'));
+    const out = await executeCLI('user', ['rows', 'query-entity', '--help'], undefined, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
     assert.match(out.text, /query flags: --query-file/);
 });
@@ -59,19 +60,25 @@ test('command help without request body can still point to lifecycle and example
     assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/table-lifecycle\.md/);
     assert.match(out.text, /\/opt\/arcubase-sdk\/docs\/runtime-reference\/examples\/README\.md/);
 });
+test('app inventory help explains app discovery purpose', async () => {
+    const out = await executeCLI('admin', ['app', 'inventory', '--help'], undefined, async () => new Response('{}'));
+    assert.equal(out.kind, 'help');
+    assert.match(out.text, /list all accessible apps and each app entity list/);
+    assert.match(out.text, /use this before asking the user for app_id/);
+});
 test('admin-save-entity help prints row-operation next step', async () => {
     const out = await executeCLI('admin', ['entity', 'admin-save-entity', '--help'], undefined, async () => new Response('{}'));
     assert.equal(out.kind, 'help');
     assert.match(out.text, /switch to arcubase for row operations/);
-    assert.match(out.text, /arcubase workflow insert-entity/);
-    assert.match(out.text, /arcubase workflow query-entity/);
+    assert.match(out.text, /arcubase rows insert-entity/);
+    assert.match(out.text, /arcubase rows query-entity/);
 });
 test('wrong admin workflow command points to arcubase row command', async () => {
     await assert.rejects(() => executeCLI('admin', ['workflow', 'insert-entity'], env, async () => new Response('{}')), (error) => {
         assert.equal(error.code, 'UNKNOWN_COMMAND');
-        assert.equal(error.details?.reason, 'workflow insert-entity is a row operation, not an arcubase-admin command');
-        assert.equal(error.details?.hint, 'use: arcubase workflow insert-entity');
-        assert.ok((error.details?.suggestions ?? []).includes('arcubase workflow insert-entity'));
+        assert.equal(error.details?.reason, 'workflow insert-entity is not a valid command group; use arcubase rows for row operations');
+        assert.equal(error.details?.hint, 'use: arcubase rows insert-entity');
+        assert.ok((error.details?.suggestions ?? []).includes('arcubase rows insert-entity'));
         return true;
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carthooks/arcubase-cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Arcubase runtime CLI for admin and user command execution",
   "type": "module",
   "main": "./dist/index.js",

package/sdk-dist/api/admin/app.ts

@@ -13,7 +13,8 @@ import type {
   AppUpdateAppRespVO,
   AppUpdateI18nReqVO,
   AppUpdateI18nRespVO,
-  AppGetEntitiesRespVO
+  AppGetEntitiesRespVO,
+  AppListRespVO
 } from '../../types/app'
 import type {
   AppDeleteWidgetsRespVO,
@@ -46,6 +47,12 @@ export async function createAppByTenants(
   return getDefaultClient().post('/apps', data)
 }
 
+// @endpoint GET /apps
+// @controller App.ListApps
+export async function listApps(): Promise<AppListRespVO> {
+  return getDefaultClient().get('/apps')
+}
+
 // @endpoint POST /apps/:id/entities
 // @controller App.CreateEntity
 export async function createEntity(

package/sdk-dist/docs/runtime-reference/README.md

@@ -25,6 +25,7 @@ Do not start from raw HTTP methods or paths. Start from the CLI command.
 
 Use `arcubase-admin` for:
 
+- app discovery
 - app creation
 - entity shell creation
 - entity schema save
@@ -33,6 +34,7 @@ Use `arcubase-admin` for:
 Common commands:
 
 ```bash
+arcubase-admin app inventory
 arcubase-admin app create-app-by-tenants --body-file create-app.json
 arcubase-admin app create-entity --id <app_id> --body-file create-entity.json
 arcubase-admin entity admin-get-entity-info --app-id <app_id> --entity-id <entity_id>
@@ -54,22 +56,23 @@ Use `arcubase` for:
 Common commands:
 
 ```bash
-arcubase workflow insert-entity --app-id <app_id> --entity-id <entity_id> --body-file insert.json
-arcubase workflow query-entity --app-id <app_id> --entity-id <entity_id> --body-file query.json
-arcubase workflow update-entity-row --app-id <app_id> --entity-id <entity_id> --row-id <row_id> --body-file update.json
-arcubase workflow delete-entity-row --app-id <app_id> --entity-id <entity_id> --body-file delete.json
-arcubase workflow restore-entity-row --app-id <app_id> --entity-id <entity_id> --body-file restore.json
-arcubase workflow query-entity-selection --app-id <app_id> --entity-id <entity_id> --action archive --body-file selection.json
+arcubase rows insert-entity --app-id <app_id> --entity-id <entity_id> --body-file insert.json
+arcubase rows query-entity --app-id <app_id> --entity-id <entity_id> --body-file query.json
+arcubase rows update-entity-row --app-id <app_id> --entity-id <entity_id> --row-id <row_id> --body-file update.json
+arcubase rows delete-entity-row --app-id <app_id> --entity-id <entity_id> --body-file delete.json
+arcubase rows restore-entity-row --app-id <app_id> --entity-id <entity_id> --body-file restore.json
+arcubase rows query-entity-selection --app-id <app_id> --entity-id <entity_id> --action archive --body-file selection.json
 arcubase entity update-entity-bulk --app-id <app_id> --entity-id <entity_id> --body-file bulk-update.json
 arcubase entity invoke-entity-batch-operator --app-id <app_id> --entity-id <entity_id> --body-file invoke-batch-operator.json
 ```
 
 Hard rule:
 
+- all Arcubase work starts by identifying the target app
 - `arcubase-admin` stops at schema save
 - all row operations must switch to `arcubase`
-- do not use `arcubase-admin workflow insert-entity`
-- do not use `arcubase-admin workflow query-entity`
+- do not use `arcubase-admin` for row insertion or row queries
+- do not ask the user for `entity_id` when creating a new table
 
 ## Required file inputs
 
@@ -86,7 +89,7 @@ Use `--query-file` when the command needs query-string parameters that do not be
 Current important example:
 
 ```bash
-arcubase workflow query-entity \
+arcubase rows query-entity \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --query-file archived-query.json \
@@ -140,10 +143,16 @@ When a command is tied to a common task, `--help` should print:
 
 If you need to create a table:
 
-1. read `table-lifecycle.md`
-2. read `entity-schema.md`
-3. read `entity-schema/README.md`
-4. open the exact field-type page you need
+1. read `app-discovery.md`
+2. read `table-lifecycle.md`
+3. read `entity-schema.md`
+4. read `entity-schema/README.md`
+5. open the exact field-type page you need
+
+If you need to find an existing app or choose the right app:
+
+1. read `app-discovery.md`
+2. run `arcubase-admin app inventory`
 
 If you need row CRUD:
 
@@ -164,6 +173,8 @@ If you need search, selection, tags, bulk update, or batch operator:
 
 ## Covered now
 
+- `app-discovery.md`
+  - resolve the target app before asking the user for ids
 - `table-lifecycle.md`
   - app shell, entity shell, schema save, readiness probe
 - `entity-schema.md`
@@ -182,6 +193,3 @@ If you need search, selection, tags, bulk update, or batch operator:
   - business-shaped schema and payload templates
 
 ## Reserved expansion
-
-- `workflow/README.md`
-  - reserved for future workflow-specific CLI docs

package/sdk-dist/docs/runtime-reference/app-discovery.md

@@ -0,0 +1,68 @@
+# App Discovery
+
+Arcubase is a headless app platform.
+
+Core concepts:
+
+- app: the top-level business container
+- entity: a table inside an app
+- row: a record inside an entity
+
+Hard rule:
+
+- every operation happens inside one app
+- find the target app before schema work or row work
+
+Do not ask the user for `app_id` unless:
+
+- there is no matching app
+- there are multiple matching apps and you cannot resolve the ambiguity
+
+Do not ask the user for `entity_id` when creating a new table.
+Entity ids are assigned by Arcubase.
+
+## First command
+
+Use the inventory command first:
+
+```bash
+arcubase-admin app inventory
+```
+
+It returns:
+
+- every accessible app
+- each app id and app name
+- each app entity list
+
+Use it to resolve:
+
+- which existing app matches the user's business name
+- whether the table already exists
+- whether the user is talking about the wrong app
+
+## Resolution order
+
+1. if the user gives an app name, run `arcubase-admin app inventory`
+2. match the app by name yourself
+3. if the match is unique, continue without asking for `app_id`
+4. if there is no match, ask which app to use
+5. if there are multiple matches, ask the user to choose by app name
+
+## Existing app flow
+
+If the app already exists:
+
+1. run `arcubase-admin app inventory`
+2. find the app id
+3. inspect the existing entity list
+4. decide whether to create a new entity or write rows into an existing entity
+
+## New app flow
+
+If the user clearly wants a brand-new app:
+
+1. create the app with `arcubase-admin app create-app-by-tenants`
+2. create the entity shell
+3. save the schema
+4. switch to `arcubase rows ...` for row operations

package/sdk-dist/docs/runtime-reference/entity-schema/README.md

@@ -54,8 +54,8 @@ If you need row payloads, read:
 Current important row rules:
 
 - row delete / restore uses:
-  - `arcubase workflow delete-entity-row`
-  - `arcubase workflow restore-entity-row`
+  - `arcubase rows delete-entity-row`
+  - `arcubase rows restore-entity-row`
   - `selection.type = "ids"`
 - `subform` row values use:
   - `[{ "id": 0, "fields": { ... } }]`

package/sdk-dist/docs/runtime-reference/entity-schema/subform.md

@@ -43,8 +43,8 @@ Subform field.
 
 For row commands such as:
 
-- `arcubase workflow insert-entity`
-- `arcubase workflow update-entity-row`
+- `arcubase rows insert-entity`
+- `arcubase rows update-entity-row`
 
 the current writable row shape is:
 

package/sdk-dist/docs/runtime-reference/entity-schema.md

@@ -30,7 +30,7 @@ The current direct-write path is:
 1. create the entity shell
 2. fetch the current shell
 3. save the full schema
-4. probe rows with `arcubase workflow query-entity`
+4. probe rows with `arcubase rows query-entity`
 
 Do not treat shell creation as “table created”.
 
@@ -180,7 +180,7 @@ Also:
 Do not call schema creation successful until:
 
 1. `arcubase-admin entity admin-save-entity ...` succeeds without top-level `error`
-2. `arcubase workflow query-entity ...` succeeds against the saved table
+2. `arcubase rows query-entity ...` succeeds against the saved table
 
 If row probing still fails, the table is not ready.
 

package/sdk-dist/docs/runtime-reference/examples/README.md

@@ -16,7 +16,7 @@ These examples are not raw tenant exports.
 
 - Keep table names and field names in English.
 - Remove company-specific words.
-- Remove region-specific words when they are not essential to the workflow.
+- Remove region-specific words when they are not essential to the business process.
 - Prefer neutral names such as `sku_code`, `sales_order`, `goods_receipt`, and `stock_issue`.
 - When a save payload needs shell values, replace placeholder tokens such as `__APP_ID__`, `__ENTITY_ID__`, and `__SCHEMA_VERSION__` from the current shell returned by:
 

package/sdk-dist/docs/runtime-reference/examples/oms-01/README.md

@@ -1,6 +1,6 @@
 # OMS Example 01
 
-This example set models a compact order-management workflow.
+This example set models a compact order-management example.
 
 It is intentionally generic:
 
@@ -70,7 +70,7 @@ This example rewrites them into generic names such as:
 - `sales-order.selection.condition.json`
 - `sales-order.bulk-update.json`
 
-## Save workflow
+## Save sequence
 
 For every `*.schema.json` file:
 
@@ -143,13 +143,13 @@ arcubase-admin entity admin-save-entity --app-id <app_id> --entity-id <entity_id
 Insert one row:
 
 ```bash
-arcubase workflow insert-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.row.insert.json
+arcubase rows insert-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.row.insert.json
 ```
 
 Query rows:
 
 ```bash
-arcubase workflow query-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.query.json
+arcubase rows query-entity --app-id <app_id> --entity-id <entity_id> --body-file sales-order.query.json
 ```
 
 ## Placeholder rules

package/sdk-dist/docs/runtime-reference/examples/oms-01/app-overview.md

@@ -76,4 +76,4 @@ Purpose:
 - country-specific code naming
 - tenant-specific internal labels
 - region-specific channel names
-- company-specific workflow terms
+- company-specific process terms

package/sdk-dist/docs/runtime-reference/row-crud.md

@@ -7,7 +7,7 @@ Use this page for direct row operations with `arcubase`.
 Command:
 
 ```bash
-arcubase workflow insert-entity \
+arcubase rows insert-entity \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file insert.json
@@ -46,7 +46,7 @@ The returned value is the new `row_id`.
 Command:
 
 ```bash
-arcubase workflow query-entity \
+arcubase rows query-entity \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file query.json
@@ -85,7 +85,7 @@ Typical row shape:
 Command:
 
 ```bash
-arcubase workflow get-entity-row \
+arcubase rows get-entity-row \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --row-id <row_id>
@@ -98,7 +98,7 @@ Use this when you already know the row id and want the full record payload.
 Command:
 
 ```bash
-arcubase workflow update-entity-row \
+arcubase rows update-entity-row \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --row-id <row_id> \
@@ -139,7 +139,7 @@ The update command returns `true`, not the updated row body.
 Command:
 
 ```bash
-arcubase workflow delete-entity-row \
+arcubase rows delete-entity-row \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file delete.json
@@ -167,7 +167,7 @@ Rules:
 Command:
 
 ```bash
-arcubase workflow restore-entity-row \
+arcubase rows restore-entity-row \
   --app-id <app_id> \
   --entity-id <entity_id> \
   --body-file restore.json