@loxtep/sdk 0.7.0 → 0.7.6

package/CHANGELOG.md

@@ -6,6 +6,69 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.6] - 2026-07-23
+
+### Added
+
+- **`loxtep --version`** (also `-V` and `loxtep version`) prints the installed
+  `@loxtep/sdk` semver, e.g. `@loxtep/sdk 0.7.6`.
+
+## [0.7.5] - 2026-07-23
+
+### Changed
+
+- **CLI help** (`loxtep --help`) reorganized under **MCP-aligned SDK facades**
+  (Session, Workspace, Build, Define, Review, Query, Observe, Context) instead
+  of a flat command list. Help text lives in `src/cli/help.ts`.
+
+## [0.7.4] - 2026-07-23
+
+### Changed
+
+- **Documentation** defaults to **pnpm** (`pnpm add`, `pnpm exec loxtep`) instead of
+  npm/npx across README, getting started, quick reference, and SDK pairing.
+- **New guide:** [`docs/code-first-cli.md`](./docs/code-first-cli.md) documents the
+  `loxtep init → attach → generate → test → deploy` workflow, when init is
+  required vs login-only programmatic use, and cross-links from getting started
+  and quick reference.
+- CLI auth hints now reference `pnpm exec loxtep login` for consistency with docs.
+
+## [0.7.3] - 2026-07-23
+
+### Fixed
+
+- **`loxtep login`** now saves credentials to **`./.loxtep/credentials.json`** in
+  the current working directory by default (not `~/.loxtep/credentials.json`).
+  Use `--global` for the home-directory path. Read resolution walks upward for
+  a local `credentials.json` before falling back to global.
+
+## [0.7.2] - 2026-07-23
+
+### Changed
+
+- **Documentation** aligned with **v0.7.0+ MCP facade API**: README, getting
+  started, quick reference, event replay cookbook, and AGENTS guidance now use
+  `client.get_writer` / `client.get_reader` and facade paths
+  (`client.build.*`, `client.observe.*`, etc.) instead of removed flat
+  namespaces (`client.data_products`, `client.workflows`, …).
+- **Module export docs** corrected: import from `@loxtep/sdk` (and
+  `@loxtep/sdk/errors` only for the errors subpath).
+
+## [0.7.1] - 2026-07-23
+
+### Security
+
+- **js-yaml** upgraded to **4.3.0+** ([GHSA-52cp-r559-cp3m](https://github.com/advisories/GHSA-52cp-r559-cp3m) /
+  CVE-2026-59869): fixes quadratic CPU use from chained YAML merge-key (`<<:`) documents.
+
+### Changed
+
+- **leo-sdk** bumped **7.1.12 → 7.1.21** (latest npm; lodash already at 4.18.x upstream).
+- **Dependency overrides** (transitive hardening for npm consumers):
+  - `uuid` → **^11.1.0** (leo-sdk still declares 8.x)
+  - `fast-csv` → **^5.0.7** (drops deprecated `lodash.isequal`; leo-sdk still declares 4.x)
+  - `lodash` → **^4.18.0** (unchanged)
+
 ## [0.7.0] - 2026-07-23
 
 ### Breaking changes — MCP-aligned client facades

package/README.md

@@ -1,15 +1,31 @@
 # Loxtep Node.js SDK
 
-Client for the Loxtep API, organized around one journey: **ingest → define →
-deliver**. Install the SDK and get to your first event in five steps (below),
-then reach for the namespace that matches the stage you're in:
+Client for the Loxtep API. Since **v0.7.0**, the public surface mirrors the
+**10 hosted MCP tool facades** (no flat top-level namespaces like
+`client.workflows` or `client.data_products`).
 
-- **Ingest** — `triggers`, `connectors`, `workflows`, `data_products.get_writer`
-- **Define** — `data_products`, `schemas`, `quality`, `catalog`, `discovery`,
-  `domains`, `standards`, `data_contracts`, `thesaurus`, `procedures`
-- **Deliver** — `data_products` (reader/stream/replay/query), `targets`
-- **Advanced / platform** — `projects`, `templates`, `instances`, `observe`,
-  `queues`, `metrics`
+| MCP facade | SDK namespace | Examples |
+| --- | --- | --- |
+| `loxtep_session` | `client.session` | `get_current_user()` |
+| `loxtep_connect` | `client.connect` | `.connectors.*`, `.templates.*` |
+| `loxtep_workspace` | `client.workspace` | `.projects.*`, `.instances.*` |
+| `loxtep_build` | `client.build` | `.workflows.*`, `.triggers.*`, `.data_products.*`, `.targets.*` |
+| `loxtep_define` | `client.define` | `.schemas.*`, `.quality.*`, `.domains.*`, … |
+| `loxtep_meaning` | `client.meaning` | `.thesaurus.*` |
+| `loxtep_review` | `client.review` | `.approvals.*`, `.improvements.*` |
+| `loxtep_query` | `client.query` | `.catalog.*`, `.discovery.*`, `.query()` |
+| `loxtep_observe` | `client.observe` | `.stream_config()`, `.open_reader()` |
+| `loxtep_context` | `client.context` | `.procedures.*`, `.activity.*`, … |
+
+**Stream I/O** uses top-level helpers (not nested under a facade):
+`await client.get_writer('data-product-name')` and
+`await client.get_reader('data-product-name')`.
+
+Full mapping table: [`docs/sdk-mcp-mapping.md`](./docs/sdk-mcp-mapping.md).
+**Upgrading from 0.6.x:** replace `client.data_products` →
+`client.build.data_products` (CRUD/stream/replay) or `client.get_writer` /
+`client.get_reader` (recommended write/read path); `client.workflows` →
+`client.build.workflows`; etc.
 
 **Node.js 22+** is the supported runtime (`engines` in `package.json`). **Live**
 queue/flow writes use the **Loxtep stream** data plane; configure stream bus
@@ -22,7 +38,7 @@ This SDK supports two developer workflows:
 
 | Path | Use case | Entry point |
 |------|----------|-------------|
-| **Programmatic** | Write/read events from application code (microservices, lambdas, scripts) | `LoxtepClient` → `data_products.get_writer` / `get_reader` |
+| **Programmatic** | Write/read events from application code (microservices, lambdas, scripts) | `LoxtepClient` → `get_writer` / `get_reader` |
 | **Code-first CLI** | Author workflows as TypeScript, test locally, deploy via CI | `loxtep init → attach → generate → test → deploy` |
 
 There are also two additional paths that don't require this SDK:
@@ -38,19 +54,19 @@ All paths are documented in the [Loxtep Quickstart](https://docs.loxtep.io/quick
 1. **Install**
 
    ```bash
-   npm install @loxtep/sdk
+   pnpm add @loxtep/sdk
    ```
 
 2. **Log in**
 
    ```bash
-   npx loxtep login
+   pnpm exec loxtep login
    ```
 
    A browser window opens — sign in to Loxtep and you're authenticated.
-   Tokens are saved to `~/.loxtep/credentials.json` and refresh automatically.
+   Tokens are saved to `./.loxtep/credentials.json` (use `--global` for home dir).
 
-   > **CI/headless:** Use `npx loxtep login --email you@co.com --password ...`
+   > **CI/headless:** Use `pnpm exec loxtep login --email you@co.com --password ...`
    > or set `LOXTEP_AUTH_TOKEN` in your environment.
 
 3. **Create a client, write and read events**
@@ -63,8 +79,8 @@ All paths are documented in the [Loxtep Quickstart](https://docs.loxtep.io/quick
      auth: { type: 'jwt', token: process.env.LOXTEP_AUTH_TOKEN! },
    });
 
-   // Write events to a data product
-   const writer = await client.data_products.get_writer('shopify_gql_customer');
+   // Write events to a data product (top-level — resolves deployment metadata)
+   const writer = await client.get_writer('shopify_gql_customer');
    writer.write({
      customer_id: '123',
      name: 'Alice',
@@ -73,7 +89,7 @@ All paths are documented in the [Loxtep Quickstart](https://docs.loxtep.io/quick
    await writer.close();
 
    // Read events from a data product
-   const reader = await client.data_products.get_reader('shopify_gql_customer');
+   const reader = await client.get_reader('shopify_gql_customer');
    for await (const event of reader) {
      console.log(event);
    }
@@ -87,44 +103,45 @@ All paths are documented in the [Loxtep Quickstart](https://docs.loxtep.io/quick
    `await client.observe.stream_config()` returns stream resource names
    needed for the data plane. Merge into
    `new LoxtepClient({ ...opts, streams: { ...partial } })` with your
-   JWT-backed client. Note: `data_products.get_writer` and `get_reader` resolve
-   stream config automatically — this is only needed for manual bus access.
+   JWT-backed client. `get_writer` / `get_reader` resolve stream config
+   automatically — this step is only needed for manual bus access via
+   `client.observe.open_reader()`.
 
 ---
 
 ## Quick start — Code-first CLI (init → deploy)
 
-For developers who author workflows as TypeScript and want the full local-dev-to-production lifecycle:
+For developers who author workflows as TypeScript and want the full local-dev-to-production lifecycle, see the dedicated **[Code-first CLI guide](./docs/code-first-cli.md)**. Quick version:
 
 ```bash
 # 1. Install
-npm install @loxtep/sdk
+pnpm add @loxtep/sdk
 
 # 2. Authenticate
-npx loxtep login
+pnpm exec loxtep login
 
 # 3. Scaffold a project from a template
-npx loxtep init --template shopify-orders
+pnpm exec loxtep init --template shopify-orders
 
 # 4. Bind to a runtime instance
-npx loxtep attach --instance prod
+pnpm exec loxtep attach --instance prod
 
 # 5. Generate typed workspace constants
-npx loxtep generate
+pnpm exec loxtep generate
 
 # 6. Author a workflow (see authoring module docs below)
 
 # 7. Test locally with a sample event
-npx loxtep test orders-enricher --event ./events/order-created.json
+pnpm exec loxtep test orders-enricher --event ./events/order-created.json
 
 # 8. Deploy to the workflow engine
-npx loxtep deploy
+pnpm exec loxtep deploy
 ```
 
 The `generate` step produces `.loxtep/generated/index.ts` with typed constants for every data product, connector, domain, and queue in your workspace. Import them in your workflow modules for compile-time safety:
 
 ```ts
-import { defineDataWorkflow, on } from '@loxtep/sdk/authoring'
+import { defineDataWorkflow, on } from '@loxtep/sdk'
 import { workspace } from './.loxtep/generated'
 
 export default defineDataWorkflow({
@@ -146,71 +163,76 @@ See `loxtep init --help`, `loxtep attach --help`, etc. for all flags. The full C
 
 ## API surface
 
-Every method is `snake_case`. Namespaces are grouped by the stage of the journey
-they serve, and labelled by *kind*: **Resource** (full CRUD), **Reference**
-(read-only), **Runtime** (live stream I/O).
-
-### Ingest — connect sources, write events
-
-- **triggers** *(Resource)* – `get`, `list`, `create`, `update`, `delete`,
-  `test` — ingest source bindings (external systems that feed a workflow)
-- **connectors** *(Resource)* – `list`, `get`, `create`, `update`, `delete`,
-  `test`, `get_oauth_url` — org-level catalog of connectable system types
-- **workflows** *(Resource)* – `list`, `get`, `create`, `get_graph`, `deploy` —
-  the ingestion → transformation → export DAG
-- **data_products.get_writer(name)** *(Runtime)* – the write path for events
-
-### Define — semantics, schema, quality, governance
-
-- **data_products** *(Resource + Runtime)* – `get`, `get_lexicon`, `list`,
-  `search`, `query`, `list_tables`, `get_queue_info`, `get_reader_checkpoint`,
-  `create`, `readiness`, `promote`, `get_usage_map`, `invalidate_cache`
-- **schemas** *(Reference)* – `get`, `list`, `tag_pii_fields`
-- **quality** *(Resource)* – `list`, `get`, `create`
-- **catalog** *(Reference)* – `search`
-- **discovery** *(Reference)* – `search`, `get_evidence`, `get_lineage_impact`,
-  `get_governance_flags`, `run`
-- **domains** *(Reference)* – `list`, `get`
-- **standards** *(Reference)* – `list`, `get`
-- **data_contracts** *(Resource)* – `list`, `get`, `create`, `update`, `delete`
-- **thesaurus** *(Reference)* – `list_terms`, `resolve_canonical_key`,
-  `append_synonym`
-- **procedures** *(Reference)* – `list`
-
-### Deliver — consume and route data
-
-- **data_products** *(Runtime)* – `get_reader`, `stream`, `replay`
-- **targets** *(Resource)* – `list`, `get`, `create`, `update`, `delete` —
-  delivery sink bindings (webhook, API, export, DB sync, BI, event stream)
-
-### Advanced / platform
-
-- **projects** *(Resource)* – `list`, `get`, `create`, `update`, `delete`,
-  `apply_template`, `repository`
-- **templates** *(Reference)* – `list`, `get`
-- **instances** *(Reference)* – `list`, `get`, `get_stream_config`
-- **observe** – `status`, `stream_config`
-- **queues** – `get_queue_metadata`, `get_reader_checkpoint`, `open_reader`,
-  `open_writer`
-- **metrics** – `log`, `get_reporter`
+Every method is `snake_case`. Use the **10 MCP-aligned facades** on
+`LoxtepClient` (see table at the top). Nested APIs keep descriptive names
+(`workflows`, `data_products`, `connectors`, …) under their facade.
+
+### Top-level stream I/O (preferred)
+
+- **`get_writer(name_or_id)`** — write path; resolves queue, bot, stream config
+- **`get_reader(name_or_id)`** — async iterable read path
+- **`LoxtepClient.fromWorkspace()`** — construct from `.loxtep/project.json` +
+  `~/.loxtep/credentials.json` (env overrides: `LOXTEP_API_URL`, `LOXTEP_TOKEN`, …)
+
+### `client.build` (MCP: loxtep_build)
+
+- **`.workflows`** — `list`, `get`, `create`, `get_graph`, `deploy`; low-level
+  `.get_writer(workflow_id, { bot_id, … })` escape hatch
+- **`.triggers`** — `get`, `list`, `create`, `update`, `delete`, `test`
+- **`.data_products`** — CRUD, `stream`, `replay`, `get_queue_info`,
+  `invalidate_cache`, … (for writes/reads by name, prefer top-level
+  `client.get_writer` / `get_reader`)
+- **`.targets`** — delivery sink bindings (`list`, `get`, `create`, `update`, `delete`)
+
+### `client.connect` (MCP: loxtep_connect)
+
+- **`.connectors`** — org-level connector credentials
+- **`.templates`** — starter templates (`list`, `get`, `apply_template` on projects)
+
+### `client.workspace` (MCP: loxtep_workspace)
+
+- **`.projects`** — `list`, `get`, `create`, `update`, `delete`, `apply_template`
+- **`.instances`** — `list`, `get`, stream config helpers
+
+### `client.define` (MCP: loxtep_define)
+
+- **`.schemas`**, **`.quality`**, **`.standards`**, **`.data_contracts`**, **`.domains`**
+
+### `client.query` (MCP: loxtep_query)
+
+- **`.catalog`**, **`.discovery`**, **`.query()`**, **`.list_tables()`**, **`.search()`**
+
+### `client.observe` (MCP: loxtep_observe)
+
+- **`status()`**, **`stream_config()`**, **`open_reader()`**, **`open_writer()`**,
+  **`get_queue_metadata()`**, **`get_reader_checkpoint()`**
+
+### Other facades
+
+- **`client.session`** — `get_current_user`, `get_current_organization`, `logout`
+- **`client.meaning`** — `.thesaurus.*`
+- **`client.review`** — `.approvals.*`, `.improvements.*`
+- **`client.context`** — `.procedures.*`, `.activity.*`, `.process_intelligence.*`
+- **`client.metrics`** — `log`, `get_reporter` (stub until metrics wiring lands)
+
+See [`docs/sdk-mcp-mapping.md`](./docs/sdk-mcp-mapping.md) for the full MCP ↔ SDK table.
 
 ## Data product writer and reader
 
-`await client.data_products.get_writer('name')` resolves the data product's
-queue, bot identity, and stream bus config automatically, then returns a
-**FlowWriter**:
+`await client.get_writer('name')` resolves the data product's queue, bot
+identity, and stream bus config automatically, then returns a **FlowWriter**:
 
 ```ts
-const writer = await client.data_products.get_writer('shopify_gql_customer');
+const writer = await client.get_writer('shopify_gql_customer');
 writer.write({ customer_id: '123', name: 'Alice', email: 'alice@example.com' });
 await writer.close();
 ```
 
-`await client.data_products.get_reader('name')` returns an async iterable over
-the data product's queue:
+`await client.get_reader('name')` returns an async iterable over the data
+product's queue:
 
 ```ts
-const reader = await client.data_products.get_reader('shopify_gql_customer');
+const reader = await client.get_reader('shopify_gql_customer');
 for await (const event of reader) {
   console.log(event);
 }
@@ -221,13 +243,13 @@ Options:
 - **Writer**: `{ bot_id?, batch_size?, max_retries? }`
 - **Reader**: `{ bot_id?, from?, batch_size? }`
 
-Cache: call `client.data_products.invalidate_cache('name')` to force
+Cache: call `client.build.data_products.invalidate_cache('name')` to force
 re-resolution on the next call.
 
 ## Stream helpers
 
-Use `mapStream` and `filterStream` with `data_products.stream()`,
-`data_products.replay()`, or `queues.open_reader().read()`:
+Use `mapStream` and `filterStream` with `client.build.data_products.stream()`,
+`client.build.data_products.replay()`, or `client.observe.open_reader().read()`:
 
 ```ts
 import { mapStream, filterStream } from '@loxtep/sdk';
@@ -257,10 +279,10 @@ const client = new LoxtepClient({
 });
 
 // List targets for a data product
-const { items, pagination } = await client.targets.list('dp_abc123');
+const { items, pagination } = await client.build.targets.list('dp_abc123');
 
 // Create a webhook target
-const webhook = await client.targets.create('dp_abc123', {
+const webhook = await client.build.targets.create('dp_abc123', {
   targetType: 'webhook',
   name: 'Order notifications',
   endpoint_url: 'https://example.com/webhooks/orders',
@@ -268,23 +290,24 @@ const webhook = await client.targets.create('dp_abc123', {
 });
 
 // Update a target
-await client.targets.update('dp_abc123', webhook.consumption_id, {
+await client.build.targets.update('dp_abc123', webhook.consumption_id, {
   is_active: false,
 });
 
 // Delete a target
-await client.targets.delete('dp_abc123', webhook.consumption_id);
+await client.build.targets.delete('dp_abc123', webhook.consumption_id);
 ```
 
 ## Documentation
 
-- **Getting started** – Zero to first event in under 5 minutes.
-- **Quick reference** – Single-page cheat sheet.
-- **Event replay cookbook** – Replay events from a data product or queue.
-- **MCP + SDK pairing** – One auth story, when MCP vs SDK.
-- **MCP → SDK mapping** – Agent-oriented table.
+- **[Getting started](./docs/getting-started.md)** – Zero to first event in under 5 minutes (programmatic; no init).
+- **[Code-first CLI](./docs/code-first-cli.md)** – `loxtep init`, attach, generate, test, deploy.
+- **[Quick reference](./docs/quick-reference.md)** – Single-page cheat sheet.
+- **[Event replay cookbook](./docs/event-replay-cookbook.md)** – Replay events from a data product or queue.
+- **[MCP + SDK pairing](./docs/sdk-pairing.md)** – One auth story, when MCP vs SDK.
+- **[MCP → SDK mapping](./docs/sdk-mcp-mapping.md)** – Agent-oriented table.
 - **Typed errors** – `import { … } from '@loxtep/sdk/errors'`.
-- **API reference** – `npm run docs` (Typedoc).
+- **API reference** – `pnpm run docs` (Typedoc).
 
 ## CLI reference
 
@@ -348,141 +371,56 @@ loxtep metrics rate-limits
 
 ## Module exports
 
-The SDK also ships standalone modules for configuration, authentication,
-code generation, skill scoping, and workflow authoring. Import them directly
-from the relevant subpath.
-
-### `config` module
-
-```typescript
-import { loadConfig, loadConfigSync, saveConfig } from '@loxtep/sdk/config';
-```
-
-| Export | Type | Description |
-| --- | --- | --- |
-| `loadConfig` | function | Load config from env vars and optional file (async). Precedence: env > file > defaults |
-| `loadConfigSync` | function | Synchronous variant of `loadConfig` using `readFileSync` |
-| `saveConfig` | function | Persist config (api_url, org/project/instance IDs) to file. No secrets written to disk |
-| `parseStreamsPartial` | function | Extract a partial bus config from unknown JSON, keeping only valid stream resource keys |
-| `getConfigDir` | function | Return the default config directory path (`~/.loxtep`) |
-| `getDefaultConfigPath` | function | Return the default config file path (`~/.loxtep/config.json`) |
-| `buildAuthServiceUrl` | function | Build the full URL for auth endpoints (`/auth/login`, `/auth/refresh`) with path prefix |
-| `extendClientBaseUrl` | function | Extend `api_url` with a microservice path segment, avoiding duplication |
-| `buildPlatformRequestUrl` | function | Build a full request URL for the shared control-plane host, handling microservice routing |
-| `resolveAutoConfig` | function | Resolve configuration with full precedence: env > explicit > workspace files |
-
-### `auth` module
-
-```typescript
-import { login, refresh, browserLogin, TokenManager } from '@loxtep/sdk/auth';
-```
-
-| Export | Type | Description |
-| --- | --- | --- |
-| `decodeJwtPayload` | function | Decode JWT payload to read `exp` (expiry) without verification. Client-side only |
-| `login` | function | Authenticate with email/password via `POST /auth/login`. Returns access + refresh tokens |
-| `refresh` | function | Refresh an access token via `POST /auth/refresh` |
-| `browserLogin` | function | Run OAuth 2.1 browser-based login flow with a localhost callback server |
-| `TokenManager` | class | In-memory token manager with auto-refresh support. No tokens persisted to disk |
-| `LoginMfaRequiredError` | class | Error thrown when login returns 403 and the user must supply a TOTP code |
-
-### `codegen` module
-
-```typescript
-import { loadWorkspaceContext, deriveKey, normalizeContext, emitArtifact, writeArtifact, computeCounts } from '@loxtep/sdk/codegen';
-```
-
-| Export | Type | Description |
-| --- | --- | --- |
-| `loadWorkspaceContext` | function | Fetch all workspace resources from the control plane and assemble a `WorkspaceContext` |
-| `deriveKey` | function | Derive a deterministic, valid TypeScript identifier key from a resource name |
-| `normalizeContext` | function | Transform raw `WorkspaceContext` into canonical `NormalizedContext` with stable keys and id-sorted ordering |
-| `emitArtifact` | function | Render a `NormalizedContext` into a complete TypeScript source string with `as const` exports |
-| `writeArtifact` | function | Atomic file write of the generated artifact; returns per-resource-type counts |
-| `computeCounts` | function | Compute per-resource-type counts from a `NormalizedContext` |
-
-### `skills` module
-
-```typescript
-import { checkScope, parseSkillYaml, loadSkillsFromDirectory } from '@loxtep/sdk/skills';
-```
-
-| Export | Type | Description |
-| --- | --- | --- |
-| `checkScope` | function | Fail-closed scope decision: check whether an operation on a resource is permitted by a skill |
-| `checkScopeByName` | function | Resolve a skill by name from a map and check scope in one step |
-| `parseSkillYaml` | function | Parse a YAML string into a validated `SkillDefinition` |
-| `loadSkillFromFile` | function | Load a single skill definition from a `.yaml` file path |
-| `loadSkillsFromDirectory` | function | Load all skill definitions from a `.loxtep/skills/` directory |
-| `validateSkillReferences` | function | Validate all skill resource references against the loaded `WorkspaceContext` |
-| `formatSkillValidationErrors` | function | Format skill validation errors into human-readable messages |
-| `SkillDefinitionSchema` | object | Zod schema for validating skill definition YAML structure |
-
-### `authoring` module
+The SDK re-exports configuration, authentication, codegen, skill scoping,
+workflow authoring, HTTP, checkpoint, and streaming helpers from the main
+entry point. **`@loxtep/sdk/errors`** is the only additional published
+subpath (see `package.json` `exports`).
 
 ```typescript
-import { defineDataWorkflow, on, createToolbox, agent } from '@loxtep/sdk/authoring';
+import {
+  LoxtepClient,
+  loadConfig,
+  login,
+  defineDataWorkflow,
+  on,
+  checkScope,
+  signRequest,
+  createMemoryCheckpointStore,
+  DataProductResolver,
+} from '@loxtep/sdk';
+
+import { ValidationError, parseHttpError } from '@loxtep/sdk/errors';
 ```
 
-| Export | Type | Description |
-| --- | --- | --- |
-| `defineDataWorkflow` | function | Validate and return a `DataWorkflowModule` spec. Throws `ValidationError` on invalid input |
-| `on` | object | Trigger builders: `queueEvent`, `connectorEvent`, `schedule`, `webhook` |
-| `createToolbox` | function | Create a deterministic typed platform-call toolbox (no model in the loop) |
-| `agent` | function | Agentic operation entry point with scope enforcement and action trace |
-| `validateAgentOptions` | function | Validate agent options (prompt length, skills references) against available skills |
-| `computeReachableScope` | function | Compute the union of all resource scopes from supplied skill definitions |
-| `enforceAgentScope` | function | Check whether a resource access is within the merged scope of the agent's skills |
-| `createScopeGuardedToolbox` | function | Create a scope-guarded proxy that enforces scope and records traces before every call |
-| `compileModule` | function | Pure compiler: lower a `DataWorkflowModule` into `GraphPatchOp[]` for deployment |
-| `computeRemovalSet` | function | Compute workflows present on instance but absent from project modules (for cleanup) |
-| `ActionTrace` | class | Mutable action trace recorder with monotonically increasing sequence numbers |
-| `AgentScopeError` | class | Error thrown when an agentic operation is blocked due to a scope violation |
-| `ToolboxOperationError` | class | Error thrown when a toolbox operation fails (network, validation, or platform error) |
-
-### `http` module
+### Selected exports (import from `@loxtep/sdk` unless noted)
 
-```typescript
-import { signRequest, LoxtepHttpClient } from '@loxtep/sdk/http';
-```
+**Config:** `loadConfig`, `loadConfigSync`, `saveConfig`, `parseStreamsPartial`,
+`getConfigDir`, `getDefaultConfigPath`, `buildAuthServiceUrl`,
+`buildPlatformRequestUrl`, `resolveAutoConfig`
 
-| Export | Type | Description |
-| --- | --- | --- |
-| `signRequest` | function | Sign an HTTP request with AWS SigV4 for API Gateway (`execute-api`). Returns headers including `Authorization` and `x-amz-*` |
-| `LoxtepHttpClient` | class | HTTP client that signs requests with AWS SigV4 and attaches JWT. Provides `get`, `post`, `put`, `delete` helpers with retry on 5xx/network errors and typed Loxtep errors on 4xx |
+**Auth:** `decodeJwtPayload`, `login`, `refresh`, `browserLogin`, `TokenManager`,
+`LoginMfaRequiredError`
 
-### `checkpoint` module
-
-```typescript
-import { createMemoryCheckpointStore } from '@loxtep/sdk/checkpoint';
-```
+**Codegen:** `loadWorkspaceContext`, `deriveKey`, `normalizeContext`, `emitArtifact`,
+`writeArtifact`, `computeCounts`
 
-| Export | Type | Description |
-| --- | --- | --- |
-| `createMemoryCheckpointStore` | function | Create an in-memory checkpoint store for stream/replay resume. Suitable for tests or single-process use |
+**Skills:** `checkScope`, `checkScopeByName`, `parseSkillYaml`, `loadSkillFromFile`,
+`loadSkillsFromDirectory`, `validateSkillReferences`, `formatSkillValidationErrors`,
+`SkillDefinitionSchema`
 
-### Error classes
+**Authoring:** `defineDataWorkflow`, `on`, `createToolbox`, `agent`,
+`validateAgentOptions`, `compileModule`, `ActionTrace`, `AgentScopeError`,
+`ToolboxOperationError`
 
-```typescript
-import { AuthorizationError, ConflictError, ValidationError, DefinitionValidationError, SchemaValidationError, CheckpointError, parseHttpError } from '@loxtep/sdk/errors';
-```
+**HTTP:** `signRequest`, `LoxtepHttpClient`
 
-| Export | Type | Description |
-| --- | --- | --- |
-| `AuthorizationError` | class | 403 — Insufficient permissions |
-| `ConflictError` | class | 409 — Resource already exists or version conflict |
-| `ValidationError` | class | 400 — Invalid input with optional `field_errors` array |
-| `DefinitionValidationError` | class | 400 — Payload doesn't match data product definition (schema validation failures) |
-| `SchemaValidationError` | class | Alias for `DefinitionValidationError` (backend terminology) |
-| `CheckpointError` | class | 500 — Failed to save or load a stream checkpoint |
-| `parseHttpError` | function | Map an HTTP status code and response body to the appropriate typed Loxtep error class |
+**Checkpoint:** `createMemoryCheckpointStore`
 
-### `DataProductResolver` class
+**Streaming:** `mapStream`, `filterStream`
 
-```typescript
-import { DataProductResolver } from '@loxtep/sdk/client';
-```
+**Errors** (from `@loxtep/sdk/errors`): `AuthorizationError`, `ConflictError`,
+`ValidationError`, `DefinitionValidationError`, `SchemaValidationError`,
+`CheckpointError`, `parseHttpError`
 
-| Export | Type | Description |
-| --- | --- | --- |
-| `DataProductResolver` | class | Resolves a data product name or UUID into full runtime configuration (queue name, bot_id, stream bus resources). Caches results in memory. Used internally by `client.data_products.get_writer`/`get_reader` |
+**Resolver:** `DataProductResolver`, `AmbiguityError` — used internally by
+`get_writer` / `get_reader`; import when building custom resolution logic.

package/dist/cli/commands/config-cmd.js

@@ -316,10 +316,10 @@ export async function runConfigExportFromConnector(connectorId, options = {}) {
 export async function runInit() {
     console.log(`Loxtep CLI — setup checklist:
 
-  Config is stored at ~/.loxtep/config.json. Auth tokens are stored at ~/.loxtep/credentials.json.
+  Config is stored at ~/.loxtep/config.json. Auth tokens default to ./.loxtep/credentials.json (use loxtep login --global for ~/.loxtep/credentials.json).
 
   1. loxtep config set api_url <https://your-api-host>   (host only; no trailing /app)
-  2. loxtep login   (stores credentials at ~/.loxtep/credentials.json; or set LOXTEP_AUTH_TOKEN env var)
+  2. loxtep login   (stores credentials at ./.loxtep/credentials.json by default; or set LOXTEP_AUTH_TOKEN env var)
   3. (Legacy only) loxtep config set api_path_prefix <one ms>  if you must pin a single microservice base URL (LOXTEP_API_PATH_PREFIX); default is per-path platform routing
   4. Optional: loxtep config set organization_id <uuid> | project_id <uuid> | instance_id <uuid> | region <aws-region>
      (saved to ~/.loxtep/config.json; used as defaults for LoxtepClient constructor)
@@ -327,7 +327,7 @@ export async function runInit() {
   6. From a connector: loxtep config export --from-connector <uuid>
      From a data product: loxtep config export --from-data-product <uuid>
 
-  Auth precedence: LOXTEP_AUTH_TOKEN env var → ~/.loxtep/credentials.json (from loxtep login).
+  Auth precedence: LOXTEP_AUTH_TOKEN env var → ./.loxtep/credentials.json (walk up from cwd) → ~/.loxtep/credentials.json.
   Docs: package docs/sdk-pairing.md and docs/sdk-control-vs-data-plane.md (npm pack path: node_modules/@loxtep/sdk/docs/...).
 `);
 }

package/dist/cli/commands/login.d.ts

@@ -20,9 +20,8 @@ export interface LoginOptions {
     /** For tests: credentials file path to write. Takes precedence over --local/--global. */
     credentialsPath?: string;
     /**
-     * Force credentials scope: `local` writes to `<project>/.loxtep/credentials.json`
-     * (requires a project found via `.loxtep/project.json`); `global` writes to
-     * `~/.loxtep/credentials.json`. Default: local when run inside a project, else global.
+     * Force credentials scope: `local` writes to `./.loxtep/credentials.json` under
+     * `cwd` (default); `global` writes to `~/.loxtep/credentials.json`.
      */
     scope?: CredentialsScope;
     /** Working directory used to resolve the project for local scoping (default: `process.cwd()`). */

package/dist/cli/commands/login.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/login.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAuBD;;GAEG;AACH,wBAAsB,QAAQ,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAmIxE"}
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/login.ts"],"names":[],"mappings":"AAIA,OAAO,EAIL,KAAK,gBAAgB,EACtB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,KAAK,CAAC,EAAE,gBAAgB,CAAC;IACzB,kGAAkG;IAClG,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,oDAAoD;IACpD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAuBD;;GAEG;AACH,wBAAsB,QAAQ,CAAC,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAqIxE"}