@stndrds/cli 1.0.0-alpha.2 → 1.0.0-alpha.201

package/dist/assets/schema-builder-reference.md

@@ -0,0 +1,513 @@
+# Standards Schema Builder — Reference
+
+## Overview
+
+Standards uses a fluent builder API to define your data schema in TypeScript.
+All objects and attributes declared in code are **system** (immutable at runtime).
+Users can extend your schema at runtime by adding custom attributes via the UI.
+
+## Importing
+
+```typescript
+import {
+  object,
+  text, richtext,
+  number, currency,
+  checkbox,
+  date,
+  phone,
+  select, multiselect, status,
+  relation,
+  user,
+  file, document,
+  location,
+  formula, rollup,
+} from "@stndrds/schema";
+```
+
+## `object()` — Define an Object (table)
+
+```typescript
+const DEAL = object({ name: "deals", label: "Deal" })
+  .pluralLabel("Deals")
+  .description("Sales opportunities")
+  .icon("briefcase")
+  .order(10)                              // sidebar display order
+  .labelExpression("{{ name }}")         // REQUIRED — how records display
+  .attribute(text({ name: "name", label: "Name" }).required())
+  .attribute(number({ name: "amount", label: "Amount" }))
+  .build();
+```
+
+Object names must be **kebab-case** (e.g. `"deals"`, `"order-items"`). Max 63 characters.
+
+The `.build()` call is required at the end. The returned value is the `ObjectDefinition`.
+
+### `.sealed()` — Prevent custom attributes
+
+Marks this object as closed: `standards diff` will error if any user-created
+custom attribute is found in the DB that is not listed in `.tolerate()`.
+
+```typescript
+object({ name: "invoice", label: "Invoice" })
+  .sealed()
+  .labelExpression("{{ ref }}")
+  .attribute(number({ name: "amount", label: "Amount" }))
+  .build();
+```
+
+### `.tolerate(["name"])` — Acknowledge known custom attributes
+
+On a **sealed** object: these names won't cause a CI failure.
+On an **extensible** object: purely documentary.
+
+```typescript
+object({ name: "invoice", label: "Invoice" })
+  .sealed()
+  .tolerate(["legacy_ref", "old_notes"])
+  .labelExpression("{{ ref }}")
+  .attribute(number({ name: "amount", label: "Amount" }))
+  .build();
+```
+
+### `.labelExpression()` — Display template (REQUIRED)
+
+Every object must declare a label expression. Uses `{{ attribute }}` syntax.
+Pipes are supported: `{{ name | UPPER }}`, `{{ name | capitalize }}`, `{{ name | trim }}`, `{{ name | LOWER }}`.
+
+```typescript
+.labelExpression("{{ firstName }} {{ lastName }}")
+.labelExpression("{{ name | UPPER }}")
+.labelExpression("{{ ref }} — {{ title }}")
+```
+
+### Other object methods
+
+| Method | Purpose |
+|---|---|
+| `.pluralLabel("Deals")` | Plural form shown in collections |
+| `.description("...")` | Shown in admin UI tooltips |
+| `.icon("briefcase")` | Icon name from `@stndrds/constants` |
+| `.order(10)` | Sidebar sort order (lower = first) |
+
+---
+
+## Attribute Types
+
+All attribute builders accept `{ name, label }` as first argument.
+`name` must be **camelCase** or **snake_case**, unique within the object.
+
+### `text()` — Plain text
+
+```typescript
+text({ name: "name", label: "Name" })
+  .required()
+  .minLength(1)
+  .maxLength(255)
+  .pattern("^[A-Z].*")     // custom regex
+  .email()                  // shortcut: validates as email
+  .url()                    // shortcut: validates as URL
+  .slug()                   // shortcut: validates as slug (a-z0-9-)
+  .placeholder("Enter name...")
+```
+
+Use `.multiline()` for longer plain text:
+
+```typescript
+text({ name: "notes", label: "Notes" })
+  .multiline()
+  .optional()
+  .placeholder("Add notes...")
+```
+
+### `richtext()` — Rich text (Tiptap editor)
+
+```typescript
+richtext({ name: "description", label: "Description" }).required()
+```
+
+### `number()` — Numeric value
+
+```typescript
+number({ name: "amount", label: "Amount" })
+  .decimal(2)       // decimal with 2 places (default unit="decimal")
+  .integer()        // whole numbers only (unit="integer", decimals=0)
+  .percentage()     // percentage display (unit="percentage")
+  .min(0)
+  .max(100)
+  .required()
+```
+
+Use `.renderAs("rating")` for rating UI backed by a number:
+
+```typescript
+number({ name: "score", label: "Score" })
+  .renderAs("rating")
+  .max(5)
+```
+
+### `currency()` — Monetary amount with currency code
+
+```typescript
+currency({ name: "price", label: "Price" })
+  .defaultCurrency("EUR")
+  .allowedCurrencies(["EUR", "USD", "GBP"])
+  .allowNegative()
+  .required()
+```
+
+### `checkbox()` — Boolean toggle
+
+```typescript
+checkbox({ name: "isVerified", label: "Verified" })
+  .defaultValue(false)
+```
+
+### `date()` — Date picker
+
+```typescript
+date({ name: "closeDate", label: "Close Date" })
+  .format("short")          // "short" | "long" | "full" | "relative"
+  .minDate("2024-01-01")
+  .maxDate("2030-12-31")
+  .required()
+```
+
+### `phone()` — Phone number with country code
+
+```typescript
+phone({ name: "mobile", label: "Mobile" })
+  .defaultCountry("FRA")    // ISO 3166-1 alpha-3 country code
+  .required()
+```
+
+### `select()` — Single-choice dropdown
+
+```typescript
+select({ name: "status", label: "Status" })
+  .options([
+    { label: "Lead",   value: "lead",   color: "blue" },
+    { label: "Client", value: "client", color: "green" },
+  ])
+  .required()
+```
+
+Options shape: `{ label: string, value: string, color?: string, description?: string }`.
+Colors: `"gray"` | `"red"` | `"orange"` | `"yellow"` | `"green"` | `"blue"` | `"purple"`.
+
+Use `.option({ ... })` to append a single option instead of replacing all.
+
+### `multiselect()` — Multi-choice dropdown
+
+Same API as `select()`, but the value is an array of selected option values.
+
+```typescript
+multiselect({ name: "tags", label: "Tags" })
+  .options([
+    { label: "Urgent",  value: "urgent",  color: "red" },
+    { label: "Pending", value: "pending", color: "orange" },
+  ])
+```
+
+### `status()` — Status with workflow groups
+
+Like `select()` but options support a `group` field for visual grouping.
+
+```typescript
+status({ name: "stage", label: "Stage" })
+  .options([
+    { label: "To Do",       value: "todo",        color: "gray",  group: "idle" },
+    { label: "In Progress", value: "in_progress", color: "blue",  group: "in_progress" },
+    { label: "Done",        value: "done",        color: "green", group: "finished" },
+  ])
+  .required()
+```
+
+Option groups: `"idle"` | `"in_progress"` | `"finished"`. The `group` field is optional.
+
+### `user()` — User reference
+
+```typescript
+user({ name: "owner", label: "Owner" })
+  .multiple()                 // allow multiple actors
+  .types(["user", "agent"])   // allow users, agents, or both
+  .required()
+```
+
+### `file()` — File upload
+
+```typescript
+file({ name: "attachment", label: "Attachment" })
+  .multiple()                                // allow multiple files
+  .maxFiles(5)
+  .maxSize(10 * 1024 * 1024)                 // 10 MB in bytes
+  .allowedTypes(["image/png", "image/jpeg", "application/pdf"])
+  .required()
+```
+
+### `document()` — Structured document with slots and edge properties
+
+Documents wrap files with agent-compatible processing and edge-level metadata.
+
+```typescript
+document({ name: "contracts", label: "Contracts" })
+  .slots([{ name: "file", label: "File", acceptedMimeTypes: ["application/pdf"] }])
+  .qualifyWith(
+    date({ name: "signedDate", label: "Signed Date" }),
+    select({ name: "status", label: "Status" }).options([
+      { label: "Pending",   value: "pending",   color: "orange" },
+      { label: "Validated", value: "validated", color: "green" },
+    ])
+  )
+```
+
+For multi-sided documents (e.g. identity card), define slots:
+
+```typescript
+document({ name: "identityDoc", label: "Identity Document" })
+  .slots([
+    {
+      name: "recto",
+      label: "Front",
+      required: true,
+      acceptedMimeTypes: ["image/*", "application/pdf"],
+      maxSizeBytes: 10 * 1024 * 1024,
+    },
+    {
+      name: "verso",
+      label: "Back",
+      required: false,
+      acceptedMimeTypes: ["image/*", "application/pdf"],
+      maxSizeBytes: 10 * 1024 * 1024,
+    },
+  ])
+```
+
+### `location()` — Address / geographic location
+
+```typescript
+location({ name: "address", label: "Address" })
+  .granularity("full")         // "full" | "address" | "city" | "state" | "country"
+  .defaultCountry("FRA")
+  .allowedCountries(["FRA", "BEL", "CHE"])
+  .required()
+```
+
+### `relation()` — Record reference (single or many)
+
+```typescript
+// Single relation (default cardinality: "one")
+relation({ name: "company", label: "Company" })
+  .to("companies")
+  .required()
+
+// Multi relation
+relation({ name: "contacts", label: "Contacts" })
+  .to("contacts")
+  .many()
+
+// Polymorphic (multiple targets)
+relation({ name: "linked", label: "Linked" })
+  .to("companies")
+  .to("contacts")
+  .many()
+
+// Universal (link to any object)
+relation({ name: "reference", label: "Reference" })
+  .toAny()
+  .many()
+```
+
+**Qualified relations** — add metadata on each edge:
+
+```typescript
+relation({ name: "shareholders", label: "Shareholders" })
+  .to("contacts")
+  .many()
+  .qualifyWith(
+    select({ name: "role", label: "Role" }).options([
+      { label: "Founder", value: "founder", color: "blue" },
+      { label: "Investor", value: "investor", color: "green" },
+    ]).required(),
+    number({ name: "shares", label: "Shares %" }).min(0).max(100),
+  )
+```
+
+**Bilateral relations** — automatically sync the reverse side:
+
+```typescript
+relation({ name: "relationships", label: "Relationships" })
+  .to("contacts")
+  .many()
+  .bilateral({ object: "contacts", attribute: "relationships" })
+  .qualifyWith(
+    select({ name: "type", label: "Type" }).options([...]).required()
+  )
+```
+
+Multi-relation constraints:
+
+```typescript
+.maxItems(10)  // maximum number of linked records
+```
+
+### `formula()` — Computed read-only value
+
+Formula attributes cannot be required (they are always read-only).
+
+```typescript
+formula({ name: "total", label: "Total" })
+  .expression("price * quantity")
+  .returns("number")   // "text" | "number" | "boolean" | "date"
+  .decimals(2)
+
+formula({ name: "fullName", label: "Full Name" })
+  .expression("CONCAT(firstName, ' ', lastName)")
+  .returns("text")
+```
+
+### `rollup()` — Aggregation from related records
+
+Rollup attributes cannot be required (they are always read-only).
+
+```typescript
+// Sum a numeric field across related records
+rollup({ name: "totalRevenue", label: "Total Revenue" })
+  .from("orders")           // name of the relation attribute on THIS object
+  .aggregate("amount")      // attribute name on the RELATED object
+  .using("sum")
+  .decimals(2)
+
+// Count related records
+rollup({ name: "orderCount", label: "Order Count" })
+  .from("orders")
+  .aggregate("id")
+  .using("count")
+```
+
+Available `.using()` functions:
+- Numeric only: `"sum"` | `"avg"`
+- Date only: `"earliest"` | `"latest"`
+- Universal: `"count"` | `"countValues"` | `"countUniqueValues"` | `"countEmpty"` | `"percentEmpty"` | `"percentNotEmpty"` | `"original"`
+
+The `"original"` function returns raw values as an array rendered as the target type.
+When using `"original"` on a select/status/multiselect, also call `.targetType()` and `.targetOptions()`:
+
+```typescript
+rollup({ name: "dealStages", label: "Deal Stages" })
+  .from("deals")
+  .aggregate("stage")
+  .using("original")
+  .targetType("status")
+  .targetOptions([
+    { label: "Open", value: "open", color: "blue" },
+    { label: "Won",  value: "won",  color: "green" },
+    { label: "Lost", value: "lost", color: "red" },
+  ])
+```
+
+---
+
+## Common Attribute Options (all types)
+
+```typescript
+.required()                             // value is mandatory
+.optional()                             // value is optional (default)
+.hidden()                               // hidden from default UI views
+.description("Tooltip help text")       // shown as tooltip in UI
+.icon("star")                           // IconName from @stndrds/constants
+.placeholder("Enter a value...")        // input placeholder text
+.order(5)                               // display order within the form
+.defaultValue(...)                      // pre-fill new records
+```
+
+---
+
+## Promoting a Custom Attribute
+
+When a user has created a custom attribute and you want to make it system:
+
+**Before (user-created in DB, not in code):**
+```
+drift: deal.urgence (text, label: "Urgence")
+```
+
+**After (promoted to system in code):**
+```typescript
+const DEAL = object({ name: "deals", label: "Deal" })
+  .labelExpression("{{ name }}")
+  .attribute(text({ name: "name", label: "Name" }).required())
+  .attribute(text({ name: "urgence", label: "Urgence" }))  // ← add this
+  .build();
+```
+
+On next boot, the existing custom attribute is automatically promoted to system.
+
+---
+
+## Tolerating a Custom Attribute (sealed objects only)
+
+When you seal an object but want to acknowledge an existing custom attribute:
+
+```typescript
+const INVOICE = object({ name: "invoice", label: "Invoice" })
+  .sealed()
+  .tolerate(["legacy_ref"])   // ← known custom attr, won't fail CI
+  .labelExpression("{{ ref }}")
+  .attribute(text({ name: "ref", label: "Reference" }).required())
+  .build();
+```
+
+---
+
+## Migrations
+
+When you rename or change the type of an attribute, declare a migration.
+Versions must start at 2 and be sequential (2, 3, 4, ...).
+
+```typescript
+object({ name: "deals", label: "Deal" })
+  .migration(2, (m) => m.renameAttribute("old_name", "new_name"))
+  .migration(3, (m) => m.changeType("score", "text", "number", { transform: (v) => v }))
+  .migration(4, (m) => m.removeAttribute("deprecated_field"))
+  .labelExpression("{{ new_name }}")
+  .attribute(text({ name: "new_name", label: "Name" }).required())
+  .build();
+```
+
+Available migration operations:
+- `m.renameAttribute(from, to)` — rename an attribute
+- `m.changeType(name, fromType, toType, options?)` — change attribute type
+- `m.removeAttribute(name)` — permanently remove an attribute
+- `m.addAttribute(attribute)` — add a new attribute via migration
+- `m.updateConfig(name, config)` — patch attribute config (label, options, etc.)
+
+---
+
+## Type Inference
+
+Extract TypeScript types from your schema builders for use in frontend code:
+
+```typescript
+// ✅ Correct: infer types from the builder (before .build())
+const dealBuilder = object({ name: "deals", label: "Deal" })
+  .labelExpression("{{ name }}")
+  .attribute(text({ name: "name", label: "Name" }).required())
+  .attribute(number({ name: "amount", label: "Amount" }));
+
+type DealRecord = typeof dealBuilder.$infer.record;   // full record with id, timestamps
+type DealCreate = typeof dealBuilder.$infer.create;   // input for creation
+type DealUpdate = typeof dealBuilder.$infer.update;   // input for partial update
+
+// Export the compiled definition separately
+export const DEAL = dealBuilder.build();
+```
+
+You can also use `ExtractRecord` from `@stndrds/schema`:
+
+```typescript
+import { ExtractRecord } from "@stndrds/schema";
+type DealRecord = ExtractRecord<typeof dealBuilder>;  // same as $infer.record
+```
+
+Note: `ExtractRecord` works on the **builder** (`typeof dealBuilder`), not the compiled definition (`typeof DEAL`).

package/dist/bin.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
-// src/bin.ts
-import chalk3 from "chalk";
+// src/program.ts
+import chalk6 from "chalk";
 import { Command } from "commander";
 
 // src/client.ts
@@ -13,7 +13,9 @@ var ApiClientError = class extends Error {
   }
 };
 function buildUrl(base, path, params) {
-  const url = new URL(path, base);
+  const normalizedBase = base.endsWith("/") ? base : `${base}/`;
+  const normalizedPath = path.replace(/^\/+/, "");
+  const url = new URL(normalizedPath, normalizedBase);
   if (params) {
     for (const [key, value] of Object.entries(params)) {
       if (value !== void 0 && value !== null) {
@@ -24,10 +26,11 @@ function buildUrl(base, path, params) {
   return url.toString();
 }
 function createClient(config) {
-  const { apiUrl, apiKey } = config;
+  const { apiUrl, apiKey, tenantId } = config;
   const headers = {
     Authorization: `Bearer ${apiKey}`,
-    "Content-Type": "application/json"
+    "Content-Type": "application/json",
+    ...tenantId ? { "X-Tenant-ID": tenantId } : {}
   };
   async function request(method, path, options) {
     const url = buildUrl(apiUrl, path, options?.params);
@@ -75,10 +78,48 @@ function createClient(config) {
 }
 
 // src/commands/auth.ts
-import chalk2 from "chalk";
+import chalk from "chalk";
+
+// src/commands/common.ts
+function getGlobalOptions(cmd) {
+  return cmd.optsWithGlobals();
+}
+function getFormat(cmd) {
+  return getGlobalOptions(cmd).format;
+}
+function getClientFromCommand(cmd) {
+  const root = getGlobalOptions(cmd);
+  if (!(root.apiUrl && root.apiKey)) {
+    throw new Error('No Standards instance configured. Run "standards login" or pass --api-key.');
+  }
+  return createClient({ apiUrl: root.apiUrl, apiKey: root.apiKey, tenantId: root.tenant });
+}
+
+// src/commands/auth.ts
+function registerAuthCommand(program) {
+  const auth = program.command("auth").description("Inspect CLI authentication");
+  auth.command("whoami").description("Show current configuration and validate API key").action(async (_opts, cmd) => {
+    const root = getGlobalOptions(cmd);
+    const client = getClientFromCommand(cmd);
+    const write = (msg) => process.stdout.write(`${msg}
+`);
+    write(chalk.bold("Standards CLI Configuration"));
+    write(`  API URL:  ${root.apiUrl}`);
+    write(`  API Key:  ${root.apiKey ? `${root.apiKey.slice(0, 8)}...` : chalk.red("not set")}`);
+    write("");
+    const keys = await client.get("/api-keys");
+    write(chalk.green("\u2713 API key is valid"));
+    if (Array.isArray(keys) && keys.length > 0) {
+      const activeKeys = keys.filter(
+        (key) => typeof key === "object" && key !== null && !("revokedAt" in key && key.revokedAt)
+      );
+      write(`  Active keys: ${activeKeys.length}`);
+    }
+  });
+}
 
 // src/output.ts
-import chalk from "chalk";
+import chalk2 from "chalk";
 import Table from "cli-table3";
 var MAX_CELL_WIDTH = 50;
 function truncate(value, maxLength) {
@@ -107,7 +148,7 @@ function formatTable(items) {
   if (items.length === 0) return "No results.";
   const headers = Object.keys(items[0]);
   const table = new Table({
-    head: headers.map((h) => chalk.bold(h)),
+    head: headers.map((h) => chalk2.bold(h)),
     style: { head: [], border: [] }
   });
   for (const item of items) {
@@ -137,224 +178,596 @@ function formatOutput(data, format) {
 `);
 }
 
-// src/commands/auth.ts
-function getClientFromCommand(cmd) {
-  const root = cmd.optsWithGlobals();
-  return createClient({ apiUrl: root.apiUrl, apiKey: root.apiKey });
-}
-function getFormat(cmd) {
-  return cmd.optsWithGlobals().format;
-}
-function registerAuthCommand(program2) {
-  const auth = program2.command("auth").description("Manage authentication and API keys");
-  auth.command("whoami").description("Show current configuration and validate API key").action(async (_opts, cmd) => {
-    const root = cmd.optsWithGlobals();
-    const client = getClientFromCommand(cmd);
-    const write = (msg) => process.stdout.write(`${msg}
-`);
-    write(chalk2.bold("Standards CLI Configuration"));
-    write(`  API URL:  ${root.apiUrl}`);
-    write(`  API Key:  ${root.apiKey ? `${root.apiKey.slice(0, 8)}...` : chalk2.red("not set")}`);
-    write("");
-    const keys = await client.get("/api-keys");
-    write(chalk2.green("\u2713 API key is valid"));
-    if (Array.isArray(keys) && keys.length > 0) {
-      write(`  Active keys: ${keys.length}`);
-    }
-  });
-  auth.command("create-key").description("Create a new API key").requiredOption("--name <name>", "name for the API key").option("--expires <date>", "expiration date (ISO 8601)").action(async (opts, cmd) => {
-    const client = getClientFromCommand(cmd);
-    const body = {
-      name: opts.name,
-      permissions: []
-    };
-    if (opts.expires) body.expiresAt = opts.expires;
-    const result = await client.post("/api-keys", body);
-    formatOutput(result, getFormat(cmd));
-  });
-}
-
 // src/commands/documents.ts
-function getClientFromCommand2(cmd) {
-  const root = cmd.optsWithGlobals();
-  return createClient({ apiUrl: root.apiUrl, apiKey: root.apiKey });
-}
-function getFormat2(cmd) {
-  return cmd.optsWithGlobals().format;
-}
-function registerDocumentsCommand(program2) {
-  const documents = program2.command("documents").description("Manage documents");
-  documents.command("list").description("List documents").option("--status <status>", "filter by processing status").option("--limit <n>", "max documents to return").option("--offset <n>", "number of documents to skip").action(async (opts, cmd) => {
-    const client = getClientFromCommand2(cmd);
+function registerDocumentsCommand(program) {
+  const documents = program.command("documents").description("Manage documents");
+  documents.command("list").description("List documents").option("--limit <n>", "max documents to return").option("--offset <n>", "number of documents to skip").action(async (opts, cmd) => {
+    const client = getClientFromCommand(cmd);
     const params = {};
-    if (opts.status) params.processingStatus = opts.status;
     if (opts.limit) params.limit = opts.limit;
     if (opts.offset) params.offset = opts.offset;
     const result = await client.get("/documents", params);
-    formatOutput(result, getFormat2(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   documents.command("get").description("Get a document by ID").argument("<id>", "document ID").action(async (id, _opts, cmd) => {
-    const client = getClientFromCommand2(cmd);
+    const client = getClientFromCommand(cmd);
     const result = await client.get(`/documents/${id}`);
-    formatOutput(result, getFormat2(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   documents.command("create").description("Create a new document").requiredOption("--title <title>", "document title").option("--values <json>", "document values as JSON string").action(async (opts, cmd) => {
-    const client = getClientFromCommand2(cmd);
+    const client = getClientFromCommand(cmd);
     const body = { title: opts.title };
     if (opts.values) body.values = JSON.parse(opts.values);
     const result = await client.post("/documents", body);
-    formatOutput(result, getFormat2(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   documents.command("update").description("Update a document").argument("<id>", "document ID").option("--title <title>", "new title").option("--values <json>", "new values as JSON string").action(async (id, opts, cmd) => {
-    const client = getClientFromCommand2(cmd);
+    const client = getClientFromCommand(cmd);
     const body = {};
     if (opts.title) body.title = opts.title;
     if (opts.values) body.values = JSON.parse(opts.values);
     const result = await client.patch(`/documents/${id}`, body);
-    formatOutput(result, getFormat2(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   documents.command("delete").description("Delete a document").argument("<id>", "document ID").action(async (id, _opts, cmd) => {
-    const client = getClientFromCommand2(cmd);
+    const client = getClientFromCommand(cmd);
     await client.delete(`/documents/${id}`);
     process.stdout.write(`Document ${id} deleted.
 `);
   });
   documents.command("preview").description("Get preview file for a document").argument("<id>", "document ID").action(async (id, _opts, cmd) => {
-    const client = getClientFromCommand2(cmd);
+    const client = getClientFromCommand(cmd);
     const result = await client.get(`/documents/${id}/preview`);
-    formatOutput(result, getFormat2(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   documents.command("slots").description("List slots for a document").argument("<id>", "document ID").action(async (id, _opts, cmd) => {
-    const client = getClientFromCommand2(cmd);
+    const client = getClientFromCommand(cmd);
     const result = await client.get(`/documents/${id}/slots`);
-    formatOutput(result, getFormat2(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   documents.command("add-slot").description("Add a file slot to a document").argument("<id>", "document ID").requiredOption("--slot-name <name>", "slot name").requiredOption("--file-id <fileId>", "file ID").action(async (id, opts, cmd) => {
-    const client = getClientFromCommand2(cmd);
+    const client = getClientFromCommand(cmd);
     const result = await client.post(`/documents/${id}/slots`, {
       slotName: opts.slotName,
       fileId: opts.fileId
     });
-    formatOutput(result, getFormat2(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   documents.command("remove-slot").description("Remove a slot from a document").argument("<id>", "document ID").argument("<slotId>", "slot ID").action(async (id, slotId, _opts, cmd) => {
-    const client = getClientFromCommand2(cmd);
+    const client = getClientFromCommand(cmd);
     await client.delete(`/documents/${id}/slots/${slotId}`);
     process.stdout.write(`Slot ${slotId} removed.
 `);
   });
 }
 
-// src/commands/records.ts
-function getClientFromCommand3(cmd) {
-  const root = cmd.optsWithGlobals();
-  return createClient({ apiUrl: root.apiUrl, apiKey: root.apiKey });
-}
-function getFormat3(cmd) {
-  return cmd.optsWithGlobals().format;
+// src/commands/keys.ts
+import chalk3 from "chalk";
+function registerKeysCommand(program) {
+  const keys = program.command("keys").description("Manage Standards API keys");
+  keys.command("list").description("List API keys").action(async (_opts, cmd) => {
+    const client = getClientFromCommand(cmd);
+    const result = await client.get("/api-keys");
+    formatOutput(result, getFormat(cmd));
+  });
+  keys.command("create").description("Create a new API key").requiredOption("--name <name>", "name for the API key").option("--expires <date>", "expiration date (ISO 8601)").option("--yes", "create without confirmation").action(async (opts, cmd) => {
+    if (!opts.yes) {
+      throw new Error('Creating API keys is explicit. Re-run with "--yes" to confirm.');
+    }
+    const client = getClientFromCommand(cmd);
+    const body = {
+      name: opts.name,
+      permissions: []
+    };
+    if (opts.expires) body.expiresAt = opts.expires;
+    const result = await client.post("/api-keys", body);
+    formatOutput(result, getFormat(cmd));
+  });
+  keys.command("revoke").description("Revoke an API key").argument("<id>", "API key ID").option("--yes", "revoke without confirmation").action(async (id, opts, cmd) => {
+    if (!opts.yes) {
+      throw new Error('Revoking API keys is explicit. Re-run with "--yes" to confirm.');
+    }
+    const client = getClientFromCommand(cmd);
+    await client.delete(`/api-keys/${id}`);
+    process.stdout.write(`${chalk3.green("\u2713")} API key ${id} revoked.
+`);
+  });
 }
+
+// src/commands/records.ts
 function parseSortFlag(sort) {
   const [attribute, direction = "asc"] = sort.split(":");
-  return JSON.stringify([{ attribute, direction }]);
+  return [{ attribute, direction }];
 }
-function registerRecordsCommand(program2) {
-  const records = program2.command("records").description("Manage records (CRUD + search)");
+function registerRecordsCommand(program) {
+  const records = program.command("records").description("Manage records (CRUD + search)");
   records.command("list").description("List records for an object").argument("<object>", "object name (e.g. contacts)").option("--limit <n>", "max records to return").option("--offset <n>", "number of records to skip").option("--sort <sort>", 'sort rule as "attribute:direction"').option("--filter <json>", "filter state as JSON string").action(async (objectName, opts, cmd) => {
-    const client = getClientFromCommand3(cmd);
-    const params = {};
-    if (opts.limit) params.limit = opts.limit;
-    if (opts.offset) params.offset = opts.offset;
-    if (opts.sort) params.sorts = parseSortFlag(opts.sort);
-    if (opts.filter) params.filters = opts.filter;
-    const result = await client.get(`/records/${objectName}`, params);
-    formatOutput(result, getFormat3(cmd));
+    const client = getClientFromCommand(cmd);
+    const body = {};
+    if (opts.limit) body.limit = Number(opts.limit);
+    if (opts.offset) body.offset = Number(opts.offset);
+    if (opts.sort) body.sorts = parseSortFlag(opts.sort);
+    if (opts.filter) body.filters = JSON.parse(opts.filter);
+    const result = await client.post(`/records/${objectName}/list`, body);
+    formatOutput(result, getFormat(cmd));
   });
   records.command("get").description("Get a record by ID").argument("<object>", "object name").argument("<id>", "record ID").action(async (objectName, id, _opts, cmd) => {
-    const client = getClientFromCommand3(cmd);
+    const client = getClientFromCommand(cmd);
     const result = await client.get(`/records/${objectName}/${id}`);
-    formatOutput(result, getFormat3(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   records.command("create").description("Create a new record").argument("<object>", "object name").option("--data <json>", "record data as JSON string").action(async (objectName, opts, cmd) => {
     const data = opts.data ? JSON.parse(opts.data) : {};
-    const client = getClientFromCommand3(cmd);
-    const result = await client.post(`/records/${objectName}`, data);
-    formatOutput(result, getFormat3(cmd));
+    const client = getClientFromCommand(cmd);
+    const result = await client.post(`/records/${objectName}`, { data });
+    formatOutput(result, getFormat(cmd));
   });
   records.command("update").description("Update a record").argument("<object>", "object name").argument("<id>", "record ID").option("--data <json>", "fields to update as JSON string").action(async (objectName, id, opts, cmd) => {
     const data = opts.data ? JSON.parse(opts.data) : {};
-    const client = getClientFromCommand3(cmd);
+    const client = getClientFromCommand(cmd);
     const result = await client.put(`/records/${objectName}/${id}`, data);
-    formatOutput(result, getFormat3(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   records.command("delete").description("Delete a record").argument("<object>", "object name").argument("<id>", "record ID").action(async (objectName, id, _opts, cmd) => {
-    const client = getClientFromCommand3(cmd);
+    const client = getClientFromCommand(cmd);
     await client.delete(`/records/${objectName}/${id}`);
     process.stdout.write(`Record ${id} deleted.
 `);
   });
   records.command("search").description("Full-text search records").argument("<object>", "object name").requiredOption("--query <q>", "search query string").option("--limit <n>", "max records to return").option("--offset <n>", "number of records to skip").option("--sort <sort>", 'sort rule as "attribute:direction"').option("--filter <json>", "filter state as JSON string").action(async (objectName, opts, cmd) => {
-    const client = getClientFromCommand3(cmd);
-    const params = { q: opts.query };
-    if (opts.limit) params.limit = opts.limit;
-    if (opts.offset) params.offset = opts.offset;
-    if (opts.sort) params.sorts = parseSortFlag(opts.sort);
-    if (opts.filter) params.filters = opts.filter;
-    const result = await client.get(`/records/${objectName}/search`, params);
-    formatOutput(result, getFormat3(cmd));
+    const client = getClientFromCommand(cmd);
+    const body = { q: opts.query };
+    if (opts.limit) body.limit = Number(opts.limit);
+    if (opts.offset) body.offset = Number(opts.offset);
+    if (opts.sort) body.sorts = parseSortFlag(opts.sort);
+    if (opts.filter) body.filters = JSON.parse(opts.filter);
+    const result = await client.post(`/records/${objectName}/search`, body);
+    formatOutput(result, getFormat(cmd));
   });
 }
 
-// src/commands/schema.ts
-function getClientFromCommand4(cmd) {
-  const root = cmd.optsWithGlobals();
-  return createClient({ apiUrl: root.apiUrl, apiKey: root.apiKey });
+// src/commands/root.ts
+import { stdin as input, stdout as output } from "process";
+import { createInterface } from "readline/promises";
+import chalk4 from "chalk";
+
+// src/config.ts
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+var DEFAULT_API_URL = "http://localhost:4100/v1";
+var ENV_PROFILE_NAME = "sandbox";
+function getDefaultApiUrl() {
+  return DEFAULT_API_URL;
+}
+function getConfigPath() {
+  const configDir = process.env.STANDARDS_CONFIG_DIR ?? join(homedir(), ".standards");
+  return join(configDir, "config.json");
+}
+async function readConfig() {
+  try {
+    const raw = await readFile(getConfigPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      currentProfile: parsed.currentProfile,
+      profiles: parsed.profiles ?? {}
+    };
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return { profiles: {} };
+    }
+    throw error;
+  }
+}
+async function writeConfig(config) {
+  const path = getConfigPath();
+  await mkdir(dirname(path), { recursive: true, mode: 448 });
+  await writeFile(path, `${JSON.stringify(config, null, 2)}
+`, { mode: 384 });
+}
+async function upsertProfile(input2) {
+  const config = await readConfig();
+  config.profiles[input2.name] = {
+    apiUrl: input2.apiUrl,
+    apiKey: input2.apiKey
+  };
+  config.currentProfile = input2.name;
+  await writeConfig(config);
 }
-function getFormat4(cmd) {
-  return cmd.optsWithGlobals().format;
+async function setCurrentProfile(name) {
+  const config = await readConfig();
+  if (!config.profiles[name]) {
+    throw new Error(`Unknown Standards instance "${name}"`);
+  }
+  config.currentProfile = name;
+  await writeConfig(config);
+}
+async function removeProfile(name) {
+  const config = await readConfig();
+  const profileName = name ?? config.currentProfile;
+  if (!profileName) return;
+  delete config.profiles[profileName];
+  if (config.currentProfile === profileName) {
+    config.currentProfile = void 0;
+  }
+  await writeConfig(config);
 }
-function registerSchemaCommand(program2) {
-  const schema = program2.command("schema").description("Inspect schema objects and attributes");
+async function listProfiles() {
+  const config = await readConfig();
+  const profiles = Object.entries(config.profiles).sort(([a], [b]) => a.localeCompare(b)).map(([name, profile]) => ({
+    name,
+    apiUrl: profile.apiUrl,
+    current: config.currentProfile === name
+  }));
+  const envProfile = getEnvProfile();
+  if (envProfile) {
+    profiles.push({
+      name: ENV_PROFILE_NAME,
+      apiUrl: envProfile.apiUrl,
+      current: !config.currentProfile,
+      source: "env"
+    });
+  }
+  return profiles;
+}
+async function getActiveProfile() {
+  const config = await readConfig();
+  if (!config.currentProfile) {
+    const envProfile = getEnvProfile();
+    return envProfile ? { name: ENV_PROFILE_NAME, ...envProfile } : null;
+  }
+  const profile = config.profiles[config.currentProfile];
+  if (!profile) return null;
+  return { name: config.currentProfile, ...profile };
+}
+function getEnvProfile() {
+  if (!process.env.STANDARDS_API_KEY) return null;
+  return {
+    apiUrl: process.env.STANDARDS_API_URL ?? DEFAULT_API_URL,
+    apiKey: process.env.STANDARDS_API_KEY
+  };
+}
+async function resolveCliConfig(options) {
+  if (options.apiUrl || options.apiKey) {
+    return {
+      apiUrl: options.apiUrl ?? process.env.STANDARDS_API_URL ?? DEFAULT_API_URL,
+      apiKey: options.apiKey ?? process.env.STANDARDS_API_KEY
+    };
+  }
+  const config = await readConfig();
+  const profileName = options.instance ?? config.currentProfile;
+  if (profileName) {
+    const profile = config.profiles[profileName];
+    if (!profile) throw new Error(`Unknown Standards instance "${profileName}"`);
+    return {
+      apiUrl: profile.apiUrl,
+      apiKey: profile.apiKey,
+      profileName
+    };
+  }
+  return {
+    apiUrl: process.env.STANDARDS_API_URL ?? DEFAULT_API_URL,
+    apiKey: process.env.STANDARDS_API_KEY
+  };
+}
+
+// src/commands/root.ts
+async function promptForMissingValue(label) {
+  const rl = createInterface({ input, output });
+  try {
+    const value = await rl.question(`${label}: `);
+    return value.trim();
+  } finally {
+    rl.close();
+  }
+}
+function registerRootCommands(program) {
+  program.command("login").description("Connect the CLI to a Standards instance").option("--url <url>", "Standards API URL", getDefaultApiUrl()).option("--key <key>", "API key to store for this instance").option("--name <name>", "local instance name", "local").action(async (opts) => {
+    const apiKey = opts.key ?? await promptForMissingValue("API key");
+    if (!apiKey) throw new Error("API key is required");
+    const client = createClient({ apiUrl: opts.url, apiKey });
+    await client.get("/api-keys");
+    await upsertProfile({ name: opts.name, apiUrl: opts.url, apiKey });
+    process.stdout.write(
+      `${chalk4.green("\u2713")} Standards instance "${opts.name}" saved and selected.
+`
+    );
+    process.stdout.write(`  API URL: ${opts.url}
+`);
+    process.stdout.write(`  API Key: ${apiKey.slice(0, 8)}...
+`);
+    process.stdout.write(`  Use it with: standards --instance ${opts.name} <command>
+`);
+  });
+  program.command("use").description("Select the active Standards instance").argument("<name>", "instance name").action(async (name) => {
+    await setCurrentProfile(name);
+    process.stdout.write(`${chalk4.green("\u2713")} Standards instance "${name}" selected.
+`);
+  });
+  program.command("instances").description("List configured Standards instances").action(async (_opts, cmd) => {
+    const profiles = await listProfiles();
+    formatOutput(profiles, getFormat(cmd));
+  });
+  program.command("current").description("Show the active Standards instance").action(async () => {
+    const profile = await getActiveProfile();
+    if (!profile) {
+      process.stdout.write(`No Standards instance selected. Run "standards login".
+`);
+      return;
+    }
+    process.stdout.write(`${profile.name} ${profile.apiUrl}
+`);
+  });
+  program.command("logout").description("Remove a Standards instance from local CLI config").argument("[name]", "instance name, defaults to current").action(async (name) => {
+    await removeProfile(name);
+    process.stdout.write(`${chalk4.green("\u2713")} Standards instance removed.
+`);
+  });
+}
+
+// src/commands/schema.ts
+import { createHash } from "crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { join as join2 } from "path";
+import { fileURLToPath } from "url";
+import chalk5 from "chalk";
+function registerSchemaCommand(program) {
+  const schema = program.command("schema").description("Inspect schema objects and attributes");
   schema.command("list").description("List all schema objects").action(async (_opts, cmd) => {
-    const client = getClientFromCommand4(cmd);
+    const client = getClientFromCommand(cmd);
     const result = await client.get("/schema/objects");
-    formatOutput(result, getFormat4(cmd));
+    formatOutput(result, getFormat(cmd));
   });
   schema.command("inspect").description("Inspect an object (attributes, types, views)").argument("<object>", "object name or ID").action(async (objectName, _opts, cmd) => {
-    const client = getClientFromCommand4(cmd);
+    const client = getClientFromCommand(cmd);
     const result = await client.get(`/schema/objects/${objectName}`);
-    formatOutput(result, getFormat4(cmd));
+    formatOutput(result, getFormat(cmd));
+  });
+  schema.command("diff").description("Show runtime drift between DB and code schema").option("--object <name>", "Scope to a single object").option("--quiet", "Exit code only, no output").action(async (opts, cmd) => {
+    const format = getFormat(cmd);
+    const result = await fetchDrift(getClientFromCommand(cmd), opts.object);
+    if (format === "json" && cmd.getOptionValueSourceWithGlobals("format") !== "default") {
+      formatOutput(result, "json");
+    } else if (!opts.quiet) {
+      printDiffOutput(result);
+    }
+    process.exit(result.hasUnexpectedDrift ? 1 : 0);
+  });
+  schema.command("pull").description("Generate an AI-ready prompt to resolve schema drift").option("--object <name>", "Scope to a single object").option("--no-save", "Print to stdout only, do not write to .standards/").option("--output <file>", "Write prompt to a specific file path").action(async (opts, cmd) => {
+    const result = await fetchDrift(getClientFromCommand(cmd), opts.object);
+    const totalDrift = result.summary.totalCustomObjects + result.summary.totalCustomAttributes;
+    if (totalDrift === 0) {
+      console.info(chalk5.green("\u2713 No drift detected \u2014 nothing to pull."));
+      process.exit(0);
+    }
+    const globalOpts = cmd.optsWithGlobals();
+    const prompt = buildPullPrompt(result, globalOpts.apiUrl ?? "unknown");
+    const shouldSave = opts.save !== false;
+    if (opts.output) {
+      writeFileSync(opts.output, prompt, "utf-8");
+      console.info(chalk5.green(`\u2713 Prompt written to ${opts.output}`));
+      return;
+    }
+    if (shouldSave) {
+      const standardsDir = resolveStandardsDir();
+      const pullsDir = join2(standardsDir, "pulls");
+      const diffDir = join2(standardsDir, "diff");
+      mkdirSync(pullsDir, { recursive: true });
+      mkdirSync(diffDir, { recursive: true });
+      const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+      const hash = createHash("sha1").update(JSON.stringify(result)).digest("hex").slice(0, 6);
+      const filename = join2(pullsDir, `${date}-${hash}.md`);
+      writeFileSync(filename, prompt, "utf-8");
+      writeFileSync(join2(diffDir, "latest.json"), JSON.stringify(result, null, 2), "utf-8");
+      console.info(chalk5.green(`\u2713 Pull prompt written to ${filename}`));
+      console.info(chalk5.dim("  Copy-paste its contents into your LLM to resolve the drift."));
+    } else {
+      process.stdout.write(prompt);
+    }
   });
 }
-
-// src/bin.ts
-var program = new Command();
-program.name("standards").description("CLI to interact with Standards API").version("1.0.0-alpha.1").option("--format <format>", "output format (json, table, csv)", "json").option(
-  "--api-url <url>",
-  "API base URL",
-  process.env.STANDARDS_API_URL ?? "http://localhost:4100"
-).option("--api-key <key>", "API key for authentication", process.env.STANDARDS_API_KEY);
-registerRecordsCommand(program);
-registerSchemaCommand(program);
-registerDocumentsCommand(program);
-registerAuthCommand(program);
-program.hook("preAction", (_thisCommand, _actionCommand) => {
-  const opts = program.opts();
-  if (!opts.apiKey) {
-    console.error(
-      chalk3.red("\u2717 Error: No API key configured. Set STANDARDS_API_KEY or use --api-key")
+var fetchDrift = (client, object) => client.get("/schema/drift", object ? { object } : {});
+var relationTag = (attr) => attr.isRelation ? " [relation]" : "";
+var attrInline = (attr) => {
+  const suffix = attr.tolerated ? ", tolerated" : `${relationTag(attr)}, label: "${attr.label}"`;
+  return `   \xB7 ${attr.name} (${attr.type}${suffix})`;
+};
+function printDiffOutput(result) {
+  const lines = [];
+  for (const obj of result.customObjects) {
+    lines.push(chalk5.yellow(`\u26A0  ${obj.name} (${obj.label}) \u2014 custom object, not in code`));
+    lines.push(chalk5.dim('   \u2192 Run "standards pull" to promote or leave.'));
+  }
+  for (const entry of result.systemObjectDrift) {
+    const unexpected = entry.sealed ? entry.customAttributes.filter((a) => !a.tolerated) : [];
+    const tolerated = entry.customAttributes.filter((a) => a.tolerated);
+    if (entry.sealed && unexpected.length > 0) {
+      lines.push(
+        chalk5.red(
+          `\u2717  ${entry.objectName} \u2014 ${unexpected.length} unexpected custom attribute(s) (sealed object)`
+        )
+      );
+      for (const attr of unexpected) lines.push(chalk5.red(attrInline(attr)));
+      lines.push(chalk5.dim('   \u2192 Run "standards pull" to promote or tolerate these attributes.'));
+      if (tolerated.length > 0) {
+        lines.push(chalk5.dim(`   Also tolerated: ${tolerated.length} attribute(s)`));
+        for (const attr of tolerated) lines.push(chalk5.dim(attrInline(attr)));
+      }
+      continue;
+    }
+    const okAttrs = entry.sealed ? tolerated : entry.customAttributes;
+    if (okAttrs.length === 0) continue;
+    const okSuffix = entry.sealed ? "tolerated custom attribute(s) (sealed)" : "custom attribute(s) (extensible)";
+    lines.push(chalk5.green(`\u2713  ${entry.objectName} \u2014 ${okAttrs.length} ${okSuffix}`));
+    for (const attr of okAttrs) lines.push(chalk5.dim(attrInline(attr)));
+  }
+  if (lines.length === 0) {
+    console.info(chalk5.green("\u2713 No drift detected."));
+    return;
+  }
+  console.info(lines.join("\n"));
+  if (result.hasUnexpectedDrift) {
+    console.info(
+      chalk5.red(
+        `
+\u2717 Unexpected drift: ${result.summary.totalUnexpected} attribute(s) on sealed object(s).`
+      )
     );
-    process.exit(1);
+  } else {
+    console.info(chalk5.green("\n\u2713 No unexpected drift."));
   }
-});
-program.parseAsync(process.argv).catch((error) => {
-  if (error instanceof ApiClientError) {
-    if (error.statusCode > 0) {
-      console.error(chalk3.red(`\u2717 Error (${error.statusCode}): ${error.message}`));
-    } else {
-      console.error(chalk3.red(`\u2717 Error: ${error.message}`));
+}
+function resolveStandardsDir() {
+  let dir = process.cwd();
+  while (true) {
+    if (existsSync(join2(dir, "package.json"))) {
+      return join2(dir, ".standards");
     }
-  } else if (error instanceof Error) {
-    console.error(chalk3.red(`\u2717 Error: ${error.message}`));
+    const parent = join2(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
   }
-  process.exit(1);
-});
+  return join2(process.cwd(), ".standards");
+}
+function buildPullPrompt(result, instanceUrl) {
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const builderRef = loadBuilderReference();
+  const formatAttr = (attr) => {
+    const toleratedNote = attr.tolerated ? " *(already tolerated)*" : "";
+    return `  - ${attr.name}${relationTag(attr)}${toleratedNote} \u2014 type: ${attr.type}, label: "${attr.label}"`;
+  };
+  const lines = [
+    "# Standards Schema Pull",
+    "generated-with: standards-cli",
+    `generated-at: ${now}`,
+    `instance: ${instanceUrl}`,
+    "",
+    "---",
+    "",
+    "## Standards Schema Builder \u2014 Reference",
+    "",
+    builderRef,
+    "",
+    "---",
+    "",
+    "## Runtime Drift",
+    "",
+    "The following attributes and objects exist in the database but are not declared",
+    "in the code schema. For each one, the user will decide what to do.",
+    ""
+  ];
+  if (result.customObjects.length > 0) {
+    lines.push("### Custom Objects (not declared in code)");
+    lines.push("");
+    for (const obj of result.customObjects) {
+      lines.push(`**${obj.name}** \u2014 label: "${obj.label}"`);
+      for (const attr of obj.attributes) lines.push(formatAttr(attr));
+      lines.push("");
+    }
+  }
+  if (result.systemObjectDrift.length > 0) {
+    lines.push("### Custom Attributes on Existing Objects");
+    lines.push("");
+    for (const entry of result.systemObjectDrift) {
+      const sealedNote = entry.sealed ? " **(sealed \u2014 CI fails until resolved)**" : " (extensible)";
+      lines.push(`**${entry.objectName}**${sealedNote} \u2014 label: "${entry.objectLabel}"`);
+      for (const attr of entry.customAttributes) lines.push(formatAttr(attr));
+      lines.push("");
+    }
+  }
+  lines.push("---");
+  lines.push("");
+  lines.push("## Your Task");
+  lines.push("");
+  lines.push("1. **Explore the codebase** to find the schema files where each object is declared");
+  lines.push('   (look for `object("name")` calls importing from `@stndrds/schema`)');
+  lines.push("");
+  lines.push("2. **Present each attribute and custom object to the user**, one object at a time.");
+  lines.push("   For each, explain what it is and ask the user to choose:");
+  lines.push(
+    "   - **Promote** \u2192 will add `.attribute(...)` to the object builder (becomes system on next boot)"
+  );
+  lines.push(
+    '   - **Tolerate** \u2192 will add to `.tolerate(["name"])` (required on sealed objects to fix CI)'
+  );
+  lines.push("   - **Leave** \u2192 do nothing (will keep appearing in future `standards diff` runs)");
+  lines.push("");
+  lines.push("3. **Collect all decisions** before writing any code. Once the user has decided");
+  lines.push("   for every attribute, **apply all changes in one pass**.");
+  lines.push("");
+  lines.push("4. **Verify** by running: `standards diff`");
+  lines.push("");
+  lines.push("Refer to the Standards Schema Builder Reference above for the exact API.");
+  lines.push(
+    "For relation attributes, use the `relation()` builder with bilateral config if needed."
+  );
+  return lines.join("\n");
+}
+function loadBuilderReference() {
+  const candidates = [
+    join2(fileURLToPath(new URL(".", import.meta.url)), "../assets/schema-builder-reference.md"),
+    join2(process.cwd(), "packages/cli/src/assets/schema-builder-reference.md")
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      return readFileSync(candidate, "utf-8");
+    }
+  }
+  return "[Standards Schema Builder Reference \u2014 see packages/cli/src/assets/schema-builder-reference.md]";
+}
+
+// src/program.ts
+var PUBLIC_COMMANDS = /* @__PURE__ */ new Set(["login", "use", "instances", "current", "logout", "help"]);
+function isPublicCommand(actionCommand) {
+  if (PUBLIC_COMMANDS.has(actionCommand.name())) return true;
+  return actionCommand.parent?.name() === "auth" && actionCommand.name() === "help";
+}
+function createProgram() {
+  const program = new Command();
+  program.name("standards").description("CLI to interact with Standards API").version("1.0.0-alpha.139").option("--format <format>", "output format (json, table, csv)", "json").option("--api-url <url>", "API base URL").option("--api-key <key>", "API key for authentication").option("--instance <name>", "Standards instance profile to use").option("--tenant <id>", "Tenant ID (multi-tenant setups, defaults to primary tenant)");
+  registerRootCommands(program);
+  registerRecordsCommand(program);
+  registerSchemaCommand(program);
+  registerDocumentsCommand(program);
+  registerKeysCommand(program);
+  registerAuthCommand(program);
+  program.hook("preAction", async (_thisCommand, actionCommand) => {
+    const raw = program.opts();
+    const resolved = await resolveCliConfig({
+      apiUrl: raw.apiUrl,
+      apiKey: raw.apiKey,
+      instance: raw.instance
+    });
+    program.setOptionValue("apiUrl", resolved.apiUrl);
+    program.setOptionValue("apiKey", resolved.apiKey);
+    program.setOptionValue("profileName", resolved.profileName);
+    program.setOptionValue("tenant", raw.tenant);
+    if (!(resolved.apiKey || isPublicCommand(actionCommand))) {
+      console.error(
+        chalk6.red(
+          `\u2717 Error: No Standards instance configured. Run "standards login" or pass --api-key.`
+        )
+      );
+      process.exit(1);
+    }
+  });
+  return program;
+}
+async function runProgram(argv = process.argv) {
+  const program = createProgram();
+  await program.parseAsync(argv).catch((error) => {
+    if (error instanceof ApiClientError) {
+      if (error.statusCode > 0) {
+        console.error(chalk6.red(`\u2717 Error (${error.statusCode}): ${error.message}`));
+      } else {
+        console.error(chalk6.red(`\u2717 Error: ${error.message}`));
+      }
+    } else if (error instanceof Error) {
+      console.error(chalk6.red(`\u2717 Error: ${error.message}`));
+    }
+    process.exit(1);
+  });
+}
+
+// src/bin.ts
+await runProgram();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stndrds/cli",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.201",
   "description": "CLI tool to interact with Standards API",
   "type": "module",
   "bin": {