@loxtep/sdk 0.7.14 → 0.7.17

package/dist/index.js

@@ -13,4 +13,5 @@ export * from './types/index.js';
 export * from './codegen/index.js';
 export * from './skills/index.js';
 export * from './authoring/index.js';
+export { buildSdkIngestBundle } from './lib/sdk-ingest-bundle.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,OAAO,EAAE,oBAAoB,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/lib/sdk-ingest-bundle.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Build SDK ingest workflow bundle files (connector + connection + source data product).
+ */
+export interface SdkIngestBundleParams {
+    organization_id: string;
+    project_id: string;
+    domain_id: string;
+    connector_id: string;
+    data_product_name: string;
+    workflow_name?: string;
+    user_id?: string;
+    workflow_id?: string;
+    connection_id?: string;
+    data_product_id?: string;
+}
+export interface SdkIngestBundleResult {
+    workflow_id: string;
+    connection_id: string;
+    data_product_id: string;
+    data_product_name: string;
+    files: Record<string, Record<string, unknown>>;
+}
+export declare function buildSdkIngestBundle(params: SdkIngestBundleParams): SdkIngestBundleResult;
+//# sourceMappingURL=sdk-ingest-bundle.d.ts.map

package/dist/lib/sdk-ingest-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-ingest-bundle.d.ts","sourceRoot":"","sources":["../../src/lib/sdk-ingest-bundle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAChD;AAED,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG,qBAAqB,CAqEzF"}

package/dist/lib/sdk-ingest-bundle.js

@@ -0,0 +1,73 @@
+/**
+ * Build SDK ingest workflow bundle files (connector + connection + source data product).
+ */
+import { randomUUID } from 'node:crypto';
+export function buildSdkIngestBundle(params) {
+    const workflowId = params.workflow_id ?? randomUUID();
+    const connectionId = params.connection_id ?? randomUUID();
+    const dataProductId = params.data_product_id ?? randomUUID();
+    const now = new Date().toISOString();
+    const workflowName = params.workflow_name ?? 'SDK App Events Ingest';
+    const files = {
+        'workflow.json': {
+            workflow_id: workflowId,
+            organization_id: params.organization_id,
+            project_id: params.project_id,
+            name: workflowName,
+            workflow_type: 'ingestion',
+            domain_id: params.domain_id,
+            status: 'active',
+            configuration: {},
+            metadata: { ingestion_method: 'sdk' },
+            created_at: now,
+            updated_at: now,
+        },
+        [`connections/${connectionId}.json`]: {
+            connection_id: connectionId,
+            organization_id: params.organization_id,
+            project_id: params.project_id,
+            workflow_id: workflowId,
+            connector_id: params.connector_id,
+            key: 'sdk-input',
+            name: 'SDK Input',
+            type: 'sdk',
+            status: 'active',
+            configuration: {
+                sdk_type: 'nodejs',
+                event_type: params.data_product_name,
+            },
+            created_at: now,
+            updated_at: now,
+        },
+        [`data-products/${dataProductId}.json`]: {
+            data_product_id: dataProductId,
+            organization_id: params.organization_id,
+            project_id: params.project_id,
+            workflow_id: workflowId,
+            upstream_entity_id: connectionId,
+            upstream_entity_type: 'connections',
+            domain_id: params.domain_id,
+            name: params.data_product_name,
+            kind: 'source',
+            status: 'draft',
+            owner: params.user_id ? { user_id: params.user_id } : {},
+            governance: {
+                classification: 'internal',
+                pii_fields: [],
+                compliance_requirements: [],
+                tags: [],
+            },
+            metadata: {},
+            created_at: now,
+            updated_at: now,
+        },
+    };
+    return {
+        workflow_id: workflowId,
+        connection_id: connectionId,
+        data_product_id: dataProductId,
+        data_product_name: params.data_product_name,
+        files,
+    };
+}
+//# sourceMappingURL=sdk-ingest-bundle.js.map

package/dist/lib/sdk-ingest-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-ingest-bundle.js","sourceRoot":"","sources":["../../src/lib/sdk-ingest-bundle.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAuBzC,MAAM,UAAU,oBAAoB,CAAC,MAA6B;IAChE,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,IAAI,UAAU,EAAE,CAAC;IACtD,MAAM,YAAY,GAAG,MAAM,CAAC,aAAa,IAAI,UAAU,EAAE,CAAC;IAC1D,MAAM,aAAa,GAAG,MAAM,CAAC,eAAe,IAAI,UAAU,EAAE,CAAC;IAC7D,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,YAAY,GAAG,MAAM,CAAC,aAAa,IAAI,uBAAuB,CAAC;IAErE,MAAM,KAAK,GAA4C;QACrD,eAAe,EAAE;YACf,WAAW,EAAE,UAAU;YACvB,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,IAAI,EAAE,YAAY;YAClB,aAAa,EAAE,WAAW;YAC1B,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,MAAM,EAAE,QAAQ;YAChB,aAAa,EAAE,EAAE;YACjB,QAAQ,EAAE,EAAE,gBAAgB,EAAE,KAAK,EAAE;YACrC,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,GAAG;SAChB;QACD,CAAC,eAAe,YAAY,OAAO,CAAC,EAAE;YACpC,aAAa,EAAE,YAAY;YAC3B,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,WAAW,EAAE,UAAU;YACvB,YAAY,EAAE,MAAM,CAAC,YAAY;YACjC,GAAG,EAAE,WAAW;YAChB,IAAI,EAAE,WAAW;YACjB,IAAI,EAAE,KAAK;YACX,MAAM,EAAE,QAAQ;YAChB,aAAa,EAAE;gBACb,QAAQ,EAAE,QAAQ;gBAClB,UAAU,EAAE,MAAM,CAAC,iBAAiB;aACrC;YACD,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,GAAG;SAChB;QACD,CAAC,iBAAiB,aAAa,OAAO,CAAC,EAAE;YACvC,eAAe,EAAE,aAAa;YAC9B,eAAe,EAAE,MAAM,CAAC,eAAe;YACvC,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,WAAW,EAAE,UAAU;YACvB,kBAAkB,EAAE,YAAY;YAChC,oBAAoB,EAAE,aAAa;YACnC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,IAAI,EAAE,MAAM,CAAC,iBAAiB;YAC9B,IAAI,EAAE,QAAQ;YACd,MAAM,EAAE,OAAO;YACf,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE;YACxD,UAAU,EAAE;gBACV,cAAc,EAAE,UAAU;gBAC1B,UAAU,EAAE,EAAE;gBACd,uBAAuB,EAAE,EAAE;gBAC3B,IAAI,EAAE,EAAE;aACT;YACD,QAAQ,EAAE,EAAE;YACZ,UAAU,EAAE,GAAG;YACf,UAAU,EAAE,GAAG;SAChB;KACF,CAAC;IAEF,OAAO;QACL,WAAW,EAAE,UAAU;QACvB,aAAa,EAAE,YAAY;QAC3B,eAAe,EAAE,aAAa;QAC9B,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,KAAK;KACN,CAAC;AACJ,CAAC"}

package/docs/code-first-cli.md

@@ -5,10 +5,10 @@ deploy to a runtime instance — without using the Studio UI as your source of
 truth.
 
 Start with the [Getting Started Guide](./getting-started.md) if you have not
-yet run `login`, `init`, `attach`, and `generate`.
+yet run `login`, `init`, and `attach`.
 
-For **application code** that calls platform APIs or streams events after
-deploy, use `LoxtepClient.fromWorkspace()` (see Getting Started, Step 7–8).
+**Sending events from your app without authoring workflow modules first?**
+Use [SDK-first ingest](./sdk-first-ingest.md) instead of this guide.
 
 ---
 

package/docs/examples/generate-ingest-bundle.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+/**
+ * Greenfield SDK ingest — one-shot provision via CLI (preferred) or bundle JSON for manual save.
+ *
+ * Run from your Loxtep workspace root (after login, init, attach):
+ *
+ *   pnpm exec loxtep ingest provision --name app-events
+ *
+ * Or generate bundle JSON only:
+ *
+ *   node node_modules/@loxtep/sdk/docs/examples/generate-ingest-bundle.mjs
+ *   pnpm exec loxtep bundle save --dry-run
+ *   pnpm exec loxtep bundle save
+ */
+
+import { LoxtepClient, buildSdkIngestBundle } from '@loxtep/sdk';
+import { randomUUID } from 'node:crypto';
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+const DATA_PRODUCT_NAME = process.env.LOXTEP_DATA_PRODUCT_NAME ?? 'app-events';
+const WORKFLOW_NAME = process.env.LOXTEP_WORKFLOW_NAME ?? 'SDK App Events Ingest';
+const AUTO_SAVE = process.env.LOXTEP_AUTO_SAVE === '1';
+
+async function main() {
+  const client = await LoxtepClient.fromWorkspace();
+
+  const user = await client.session.get_current_user();
+  const organizationId = user.organization_id ?? client.organization_id;
+  const projectId = client.project_id;
+  const instanceId = client.instance_id;
+
+  if (!organizationId || !projectId) {
+    console.error(
+      'Missing organization_id or project_id. Run from a workspace after `loxtep init`.'
+    );
+    process.exit(1);
+  }
+  if (!instanceId) {
+    console.error('Missing instance_id. Run `loxtep attach --instance <id>` first.');
+    process.exit(1);
+  }
+
+  let domainId = process.env.LOXTEP_DOMAIN_ID;
+  if (!domainId) {
+    const domains = await client.define.domains.list({ page_size: 20 });
+    const items = domains.items ?? [];
+    if (items.length === 0) {
+      console.error(
+        'No domains found. Create one in the Web UI (Governance → Domains) or set LOXTEP_DOMAIN_ID.'
+      );
+      process.exit(1);
+    }
+    domainId = items[0].domain_id;
+    console.error(`Using domain: ${items[0].name} (${domainId})`);
+  }
+
+  console.error('Creating SDK connector…');
+  const connector = await client.connect.connectors.create({
+    connector_type: 'sdk',
+    metadata: { name: 'SDK Connector', created_by: 'generate-ingest-bundle' },
+  });
+
+  const bundle = buildSdkIngestBundle({
+    organization_id: organizationId,
+    project_id: projectId,
+    domain_id: domainId,
+    connector_id: connector.connector_id,
+    data_product_name: DATA_PRODUCT_NAME,
+    workflow_name: WORKFLOW_NAME,
+    user_id: user.user_id,
+    workflow_id: randomUUID(),
+    connection_id: randomUUID(),
+    data_product_id: randomUUID(),
+  });
+
+  mkdirSync('.loxtep', { recursive: true });
+  const outPath = join('.loxtep', 'sdk-ingest-bundle.json');
+  writeFileSync(outPath, JSON.stringify({ project_id: projectId, files: bundle.files }, null, 2));
+
+  console.log(
+    JSON.stringify(
+      {
+        connector_id: connector.connector_id,
+        workflow_id: bundle.workflow_id,
+        data_product_id: bundle.data_product_id,
+        data_product_name: bundle.data_product_name,
+        bundle_path: outPath,
+      },
+      null,
+      2
+    )
+  );
+
+  if (AUTO_SAVE) {
+    console.error('Saving workflow bundle (LOXTEP_AUTO_SAVE=1)…');
+    const saveResult = await client.build.workflows.save_workflow_bundle(projectId, {
+      files: bundle.files,
+      dry_run: false,
+    });
+    console.error('Deploying…');
+    const deployResult = await client.build.workflows.deploy({
+      project_id: projectId,
+      instance_id: instanceId,
+    });
+    console.log(JSON.stringify({ save: saveResult, deploy: deployResult }, null, 2));
+    console.error(`
+Provisioned. Write events:
+  LOXTEP_DATA_PRODUCT_NAME=${DATA_PRODUCT_NAME} node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
+`);
+    return;
+  }
+
+  console.error(`
+Next steps (no MCP required)
+────────────────────────────
+Preferred — one command:
+  pnpm exec loxtep ingest provision --name ${DATA_PRODUCT_NAME}
+
+Or save the generated bundle:
+  pnpm exec loxtep bundle save --dry-run --file ${outPath}
+  pnpm exec loxtep bundle save --file ${outPath}
+  pnpm exec loxtep workflows deploy --project-id ${projectId} --instance-id ${instanceId}
+
+Write events:
+  LOXTEP_DATA_PRODUCT_NAME=${DATA_PRODUCT_NAME} node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
+`);
+}
+
+main().catch(err => {
+  console.error(err instanceof Error ? err.message : err);
+  process.exit(1);
+});

package/docs/examples/write-events.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * Write sample events to a deployed source data product via get_writer.
+ *
+ * Prerequisites: login, init, attach, SDK ingest workflow deployed (see sdk-first-ingest.md).
+ *
+ *   node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
+ *
+ * Env:
+ *   LOXTEP_DATA_PRODUCT_NAME  default: app-events
+ */
+
+import { LoxtepClient } from '@loxtep/sdk';
+
+const DATA_PRODUCT_NAME = process.env.LOXTEP_DATA_PRODUCT_NAME ?? 'app-events';
+
+async function main() {
+  const client = await LoxtepClient.fromWorkspace();
+
+  console.error(`Opening writer for data product "${DATA_PRODUCT_NAME}"…`);
+  const writer = await client.get_writer(DATA_PRODUCT_NAME);
+
+  const events = [
+    {
+      event_id: `evt_${Date.now()}_1`,
+      occurred_at: new Date().toISOString(),
+      payload: { source: 'write-events.mjs', action: 'example_write', index: 1 },
+    },
+    {
+      event_id: `evt_${Date.now()}_2`,
+      occurred_at: new Date().toISOString(),
+      payload: { source: 'write-events.mjs', action: 'example_write', index: 2 },
+    },
+  ];
+
+  for (const event of events) {
+    writer.write(event);
+    console.log(JSON.stringify({ written: event.event_id }));
+  }
+
+  await writer.close();
+  console.error('Writer closed — events flushed.');
+}
+
+main().catch(err => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(message);
+  if (/not deployed/i.test(message)) {
+    console.error(
+      '\nDeploy an SDK ingestion workflow first. See nodejs/docs/sdk-first-ingest.md'
+    );
+  }
+  process.exit(1);
+});

package/docs/getting-started.md

@@ -1,9 +1,13 @@
 # SDK Getting Started Guide
 
 Get from zero to a working Loxtep workspace: authenticate, scaffold a project,
-attach to a runtime instance, and generate typed constants. Stream read/write
-comes **after** you deploy a workflow that publishes a data product.
+attach to a runtime instance, **provision your first source data product**, and
+write events with `get_writer`.
 
+> **SDK-first ingest (login → init → attach → write):**
+> [SDK-first ingest](./sdk-first-ingest.md) — the primary path when your app
+> sends events via the SDK (no SaaS connector first).
+>
 > **Other paths:** [Code-first CLI](./code-first-cli.md) (`init → attach →
 > generate → test → deploy`), [Agent-first MCP](https://github.com/LoxtepInc/loxtep-plugins-skills),
 > or the **Web UI** at [app.loxtep.io](https://app.loxtep.io).
@@ -17,9 +21,10 @@ comes **after** you deploy a workflow that publishes a data product.
 - [Step 3: Scaffold a Workspace](#step-3-scaffold-a-workspace)
 - [Step 4: Attach to an Instance](#step-4-attach-to-an-instance)
 - [Step 5: Generate Typed Constants](#step-5-generate-typed-constants)
-- [Step 6: Explore the Platform](#step-6-explore-the-platform)
-- [Step 7: Use the SDK in Application Code](#step-7-use-the-sdk-in-application-code)
-- [Step 8: Write and Read Events (after deploy)](#step-8-write-and-read-events-after-deploy)
+- [Step 6: Your first data product (SDK ingest)](#step-6-your-first-data-product-sdk-ingest)
+- [Step 7: Explore the platform (optional)](#step-7-explore-the-platform-optional)
+- [Step 8: Use the SDK in application code](#step-8-use-the-sdk-in-application-code)
+- [Step 9: Write and read events](#step-9-write-and-read-events)
 - [Troubleshooting](#troubleshooting)
 - [Next Steps](#next-steps)
 
@@ -77,10 +82,20 @@ export LOXTEP_AUTH_TOKEN="your-jwt-token"
 
 ## Step 3: Scaffold a Workspace
 
+Log in **before** `init` so the CLI registers a real platform project (not a
+local-only id that breaks `attach` / `generate` later):
+
 ```bash
 pnpm exec loxtep init
 ```
 
+Bind an **existing** org project instead of creating one:
+
+```bash
+pnpm exec loxtep init --project-id <project-uuid>
+pnpm exec loxtep projects list   # discover UUIDs
+```
+
 Optional starter template:
 
 ```bash
@@ -91,12 +106,35 @@ This creates:
 
 | Path | Purpose |
 | --- | --- |
-| `.loxtep/project.json` | Project identity; updated by `attach` |
+| `.loxtep/project.json` | **Project identity** — includes `project_id` (UUID) registered on the platform |
 | `workflows/` | Workflow modules you author and deploy |
 | `connectors/`, `domains/`, `data-products/` | Code-first resource folders |
 
-`init` can run before or after `login`. Platform project registration happens
-when you're authenticated; local scaffolding always succeeds.
+### What is a project?
+
+A **project** is your Loxtep workspace on the platform: the container for
+workflows, connectors, and deploy targets. `init` registers one in your org and
+writes its `project_id` into `.loxtep/project.json`. Most CLI commands read
+that file automatically when you run them from the workspace directory.
+
+To see your current project id:
+
+```bash
+pnpm exec loxtep config list
+# or
+cat .loxtep/project.json
+```
+
+To list every project in your organization (for example, if you skipped `init`
+or work outside the scaffolded folder):
+
+```bash
+pnpm exec loxtep projects list
+```
+
+If you ran `init` before logging in and have a stale `proj_local_*` id in
+`.loxtep/project.json`, run `loxtep login` then `loxtep init` again — it
+registers a platform project and replaces the local id.
 
 ---
 
@@ -125,20 +163,58 @@ products, connectors, domains, queues, workflows). Re-run after platform changes
 
 ---
 
-## Step 6: Explore the Platform
+## Step 6: Your first data product (SDK ingest)
+
+After `attach`, the usual greenfield goal is: **provision a source data product
+on your instance, then call `get_writer` from your app.**
+
+`get_writer` needs **deployment metadata** (queues and bots created at deploy
+time). Creating a catalog row alone is not enough.
+
+**Recommended:** follow **[SDK-first ingest](./sdk-first-ingest.md)** end to end.
+Short version:
 
 ```bash
+pnpm exec loxtep domains list
+
+# One command: SDK connector + workflow bundle + deploy (no MCP)
+pnpm exec loxtep ingest provision --name app-events
+
 pnpm exec loxtep data-products list
-pnpm exec loxtep workflows list --project-id <project-id>
+node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
+```
+
+Do **not** expect `pnpm exec loxtep data-products create` alone to enable
+streaming — it registers catalog metadata without runtime bindings.
+
+---
+
+## Step 7: Explore the platform (optional)
+
+Run these **from your workspace directory** (where `.loxtep/project.json` lives)
+after Steps 3–4:
+
+```bash
+pnpm exec loxtep config list          # confirms project_id + instance_id
+pnpm exec loxtep data-products list   # org-wide catalog
+pnpm exec loxtep workflows list       # uses project_id from project.json
 pnpm exec loxtep domains list
 ```
 
-On a new account, **data products may be empty** until you create and deploy
-workflows (CLI, MCP, or Web UI). That's expected — don't call `get_writer` yet.
+If you are not in a scaffolded workspace, list projects first and pass an id
+explicitly:
+
+```bash
+pnpm exec loxtep projects list
+pnpm exec loxtep workflows list --project-id <project-id-from-list>
+```
+
+On a new account, **data products may be empty** until you complete
+[Step 6](#step-6-your-first-data-product-sdk-ingest). That's expected.
 
 ---
 
-## Step 7: Use the SDK in Application Code
+## Step 8: Use the SDK in application code
 
 Prefer workspace auto-config instead of hand-building `api_url` and tokens:
 
@@ -164,33 +240,22 @@ const instances = await client.workspace.instances.list();
 
 ---
 
-## Step 8: Write and Read Events (after deploy)
-
-`get_writer` and `get_reader` resolve queue, bot, and stream configuration from
-**deployment metadata**. They only work for data products that exist **and** are
-deployed on your attached instance.
-
-1. Author a workflow under `workflows/` (see [Code-first CLI](./code-first-cli.md)).
-2. `pnpm exec loxtep deploy`
-3. Confirm the data product name:
-
-   ```bash
-   pnpm exec loxtep data-products list
-   ```
+## Step 9: Write and read events
 
-4. Stream from application code:
+After [Step 6](#step-6-your-first-data-product-sdk-ingest), stream from
+application code:
 
 ```typescript
 const client = await LoxtepClient.fromWorkspace();
 
-const writer = await client.get_writer('orders'); // use your deployed name
+const writer = await client.get_writer('app-events'); // name from Step 6 / data-products list
 writer.write({
   order_id: 'ord_1',
   total: 99.5,
 });
 await writer.close();
 
-const reader = await client.get_reader('orders', {
+const reader = await client.get_reader('app-events', {
   bot_id: 'my-app-reader',
 });
 for await (const event of reader) {
@@ -273,6 +338,7 @@ data product UUID instead of a name.
 
 | Resource | Description |
 |----------|-------------|
+| [SDK-first ingest](./sdk-first-ingest.md) | Greenfield: provision + `get_writer` |
 | [Code-first CLI guide](./code-first-cli.md) | Workflow modules, `test`, `deploy` |
 | [Quick Reference Card](./quick-reference.md) | Cheat sheet for common operations |
 | [Event Replay Cookbook](./event-replay-cookbook.md) | Replay and reprocess historical events |

package/docs/quick-reference.md

@@ -1,8 +1,8 @@
 # SDK Quick Reference Card
 
 Concise cheat sheet for common Loxtep SDK operations (Node.js).
-For full walkthroughs, see the [Getting Started Guide](./getting-started.md)
-or [Code-first CLI guide](./code-first-cli.md).
+For full walkthroughs, see [SDK-first ingest](./sdk-first-ingest.md),
+[Getting Started Guide](./getting-started.md), or [Code-first CLI guide](./code-first-cli.md).
 
 ---
 
@@ -183,10 +183,24 @@ const hits = await client.query.catalog.search({ query: 'orders' });
 Workspace lifecycle (requires `loxtep init` first — see [Code-first CLI guide](./code-first-cli.md)):
 
 ```bash
-pnpm exec loxtep init [--template shopify-orders]
 pnpm exec loxtep login
-pnpm exec loxtep attach --instance prod
+pnpm exec loxtep init
+pnpm exec loxtep attach --instance <instance-id>
 pnpm exec loxtep generate
+```
+
+**SDK-first ingest** (after attach — see [SDK-first ingest](./sdk-first-ingest.md)):
+
+```bash
+pnpm exec loxtep domains list
+node node_modules/@loxtep/sdk/docs/examples/generate-ingest-bundle.mjs
+pnpm exec loxtep workflows deploy --project-id <id> --instance-id <id>
+node node_modules/@loxtep/sdk/docs/examples/write-events.mjs
+```
+
+Code-first workflow modules:
+
+```bash
 pnpm exec loxtep test my-module --event ./events/sample.json
 pnpm exec loxtep deploy
 ```