@stndrds/cli 1.0.0-alpha.192 → 1.0.0-alpha.194

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/program.ts
-import chalk5 from "chalk";
+import chalk6 from "chalk";
 import { Command } from "commander";
 
 // src/client.ts
@@ -26,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);
@@ -91,7 +92,7 @@ function getClientFromCommand(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 });
+  return createClient({ apiUrl: root.apiUrl, apiKey: root.apiKey, tenantId: root.tenant });
 }
 
 // src/commands/auth.ts
@@ -505,6 +506,11 @@ function registerRootCommands(program) {
 }
 
 // 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) => {
@@ -517,6 +523,197 @@ function registerSchemaCommand(program) {
     const result = await client.get(`/schema/objects/${objectName}`);
     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);
+    }
+  });
+}
+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).`
+      )
+    );
+  } else {
+    console.info(chalk5.green("\n\u2713 No unexpected drift."));
+  }
+}
+function resolveStandardsDir() {
+  let dir = process.cwd();
+  while (true) {
+    if (existsSync(join2(dir, "package.json"))) {
+      return join2(dir, ".standards");
+    }
+    const parent = join2(dir, "..");
+    if (parent === dir) break;
+    dir = parent;
+  }
+  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
@@ -527,7 +724,7 @@ function isPublicCommand(actionCommand) {
 }
 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");
+  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);
@@ -544,9 +741,10 @@ function createProgram() {
     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(
-        chalk5.red(
+        chalk6.red(
           `\u2717 Error: No Standards instance configured. Run "standards login" or pass --api-key.`
         )
       );
@@ -560,12 +758,12 @@ async function runProgram(argv = process.argv) {
   await program.parseAsync(argv).catch((error) => {
     if (error instanceof ApiClientError) {
       if (error.statusCode > 0) {
-        console.error(chalk5.red(`\u2717 Error (${error.statusCode}): ${error.message}`));
+        console.error(chalk6.red(`\u2717 Error (${error.statusCode}): ${error.message}`));
       } else {
-        console.error(chalk5.red(`\u2717 Error: ${error.message}`));
+        console.error(chalk6.red(`\u2717 Error: ${error.message}`));
       }
     } else if (error instanceof Error) {
-      console.error(chalk5.red(`\u2717 Error: ${error.message}`));
+      console.error(chalk6.red(`\u2717 Error: ${error.message}`));
     }
     process.exit(1);
   });

package/package.json

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