Update SDK pages

Author: tailor-docs-bot[bot]

docs/sdk/cli-reference.md

@@ -35,10 +35,14 @@ Commands that only perform side effects and do not define a structured result ma
 even when `--json` is passed.
 
 Errors, warnings, progress, and diagnostic messages are written to stderr. After argument parsing,
-a command failure under `--json` emits a JSON error envelope to stderr. CLI errors include a stable
-`error.code` and may include structured `error.next` and `error.context` fields for automated
-recovery. Diagnostic lines may precede the error envelope, and stdout is not guaranteed to contain
-an error object.
+a command failure under `--json` emits a JSON error envelope to stderr. Failures you can act on — an
+invalid or missing option, a resource that does not exist, an invalid configuration, or an unmet
+precondition — carry a stable `error.code` such as `PROFILE_NOT_FOUND`, `TAILORDB_NAMESPACE_NOT_FOUND`,
+or `MIGRATION_SCRIPT_REQUIRED`. Where a remediation exists, the envelope also includes
+`error.suggestion`, `error.help` (the `--help` invocation for the failing command), `error.next` (a
+runnable command), or `error.context`. `UNEXPECTED_ERROR` marks failures without a dedicated code,
+including SDK-internal errors. Diagnostic lines may precede the error envelope, and stdout is not
+guaranteed to contain an error object.
 
 Authentication failures distinguish missing credentials (`AUTH_TOKEN_NOT_FOUND`), a missing saved
 user (`AUTH_USER_NOT_FOUND`), an expired token (`AUTH_TOKEN_EXPIRED`), and a failed token refresh
@@ -67,6 +71,33 @@ Capture the original failure's stderr and exit code before retrying. Argument pa
 before the CLI starts may produce plain text even with `--json`. A failed deployment may have
 already applied changes, so inspect its output before deciding to run it again.
 
+### GitHub Actions Annotations
+
+When `GITHUB_ACTIONS` is exactly `true`, a command that ends in failure also writes one
+`::error::` workflow command to stderr, so the failure appears as an annotation on the run
+instead of only inside the scrolled log. The annotation repeats what the CLI already prints:
+its `title` is the error code (`AUTH_TOKEN_NOT_FOUND`, `PLUGIN_GENERATION_FAILED`, ...), and its
+body carries the same details, suggestion, and next action. Colors are stripped and newlines are
+encoded, so the annotation is a single line.
+
+Exactly one annotation is written per failed command, and only for the failure that ends it.
+Warnings and individually reported problems stay plain stderr output. The bundled CLI plugins
+(`seed`, `setup`, `tailordb-erd`) annotate their failures the same way. A command that exits
+without reporting through the CLI's error path, such as one relaying a failed remote execution,
+writes no annotation.
+
+Set `TAILOR_GITHUB_ACTIONS_ANNOTATIONS=false` (also `off`, `no`, or `0`) to turn annotations off.
+Passing `--json` also suppresses them, so a workflow step that parses `--json` output gets only the
+error envelope on stderr. The flag is honored even when the command fails during argument parsing,
+before the envelope itself becomes available.
+
+An annotation does not by itself fail a step: the step still fails on the CLI's exit code, which
+is unchanged. Workflows that already echo their own `::error::` around the CLI keep working;
+those messages describe the workflow's own checks, which can fail even when the CLI succeeds.
+
+Annotations do not yet carry `file=`/`line=` source locations, and `generate` and `deploy` do not
+group their per-service progress.
+
 ## Common Options
 
 The following options are available for most commands:
@@ -116,6 +147,7 @@ You can use environment variables to configure workspace and authentication:
 | `TAILOR_BUNDLE_CONCURRENCY`                  | Max concurrent bundle workers for `deploy` (resolvers/executors/workflows). Defaults to CPU count     |
 | `TAILOR_APPLY_CONCURRENCY`                   | Max concurrent platform RPCs during `apply`/`deploy`. Defaults to 16                                  |
 | `VISUAL` / `EDITOR`                          | Preferred editor for commands that open files (e.g., `vim`, `code`, `nano`)                           |
+| `TAILOR_GITHUB_ACTIONS_ANNOTATIONS`          | GitHub Actions failure annotations: `on` (default) or `off`                                           |
 | `TAILOR_CRASH_REPORTS_LOCAL`                 | Local crash log writing: `on` (default) or `off`                                                      |
 | `TAILOR_CRASH_REPORTS_REMOTE`                | Automatic crash report submission: `off` (default) or `on`                                            |
 

docs/sdk/plugin/custom.md

@@ -324,6 +324,37 @@ const AuditLog = await getGeneratedTable(configPath, "@example/audit-log", null,
 5. Caches the result to avoid redundant processing
 6. Returns the generated table matching the specified kind
 
+## getExtendedTable Helper
+
+A table that plugins are attached to gains the fields those plugins return in `extends.fields`, but only in the table `tailor generate` registers — the object exported from the table's source file stays as written. `getExtendedTable()` returns the table with every plugin-added field applied, so tooling that reads the table at runtime sees the same fields `tailor generate` does.
+
+```typescript
+import { join } from "node:path";
+import { getExtendedTable } from "@tailor-platform/sdk/plugin";
+import { customer } from "./tailordb/customer";
+
+const configPath = join(import.meta.dirname, "./tailor.config.ts");
+
+const extendedCustomer = await getExtendedTable(configPath, customer);
+extendedCustomer.fields.deletedAt; // added by a plugin attached with .plugin()
+```
+
+**Parameters:**
+
+- `configPath`: Path to `tailor.config.ts` (absolute or relative to cwd)
+- `sourceTable`: The TailorDB table as exported from its source file
+
+**How it works:**
+
+1. Returns `sourceTable` itself when no plugin is attached to it
+2. Loads and caches the config from the given path
+3. Auto-resolves the namespace from config
+4. Calls each attached plugin's `onTableLoaded()` in the order of the `.plugin()` calls, each seeing the fields the plugins before it added
+5. Caches the result per config path and table
+6. Returns a new table with the added fields; `sourceTable` is not changed
+
+The seed schema files `tailor generate` writes for tables with plugins attached use this helper, so `tailor seed validate` checks plugin-added fields like the table's own.
+
 ## Examples
 
 ### Definition-time Plugin (Soft Delete)
@@ -646,10 +677,11 @@ of whether `.files()` or `.plugin()` was called first. `tailor generate` also re
 collision at runtime, as a backstop for any case a table's static type doesn't otherwise catch.
 
 This only affects the table's static type. The corresponding field exists on the table's
-generated schema, and on the table object's own `fields`, only after `tailor generate` actually
-applies `extends.fields`. Before that, reading an injected field directly off the table
-(`table.fields.status`) returns `undefined`, and `pickFields(["status"])` throws — call these only
-with the table's originally declared fields, not ones a plugin injects.
+generated schema, and on the table `tailor generate` registers, only once `extends.fields` is
+applied; the table object exported from the source file never gains it. Reading an injected field
+directly off that object (`table.fields.status`) returns `undefined`, and `pickFields(["status"])`
+throws — call these only with the table's originally declared fields, or load the table with
+[`getExtendedTable()`](#getextendedtable-helper) first.
 
 To keep the declared type and the runtime implementation in sync, give `Plugin`'s optional third
 type parameter the same shape and use it inside `onTableLoaded`:

docs/sdk/testing.md

@@ -149,26 +149,30 @@ Pass `{ onUnhandled: "error" }` to make an unmatched query fail instead of retur
 
 Instead of staging responses, back TailorDB with `@electric-sql/pglite` — an in-memory PostgreSQL (install it as a devDependency) — so the queries a resolver, executor, or workflow job issues through `getDB()` execute against real data. `getDB(namespace)` needs no test-side swap: acquire the mock, and each namespace you list resolves to its PGlite instance.
 
-Create the tables the test touches with `CREATE TABLE` statements matching the generated Kysely types — `text` for string and enum fields, `timestamptz` for date/datetime, `jsonb` for nested objects. The schema only has to match what your code reads and writes, not TailorDB's storage; relations are not enforced.
+Let `kyselyTypePlugin` generate the `CREATE TABLE` script for you: set `pgliteSchemaPath` next to `distPath`, and `tailor generate` writes a module exporting one script per namespace, derived from the same table definitions as the Kysely types.
+
+```typescript
+// tailor.config.ts
+kyselyTypePlugin({
+  distPath: "./generated/db.ts",
+  pgliteSchemaPath: "./generated/db.pglite.ts",
+});
+```
+
+Run the namespace's script once per PGlite instance. Every statement is `IF NOT EXISTS`, so applying it again to an instance that already has the tables is harmless.
 
 ```typescript
 import { PGlite } from "@electric-sql/pglite";
 import { mockTailordbWithPGlite } from "@tailor-platform/sdk/vitest";
 import { afterAll, beforeAll, expect, test } from "vitest";
 import { getDB } from "../generated/db";
+import { pgliteSchema } from "../generated/db.pglite";
 import resolver from "./upsertUsers";
 
 const pglite = new PGlite();
 
 beforeAll(async () => {
-  await pglite.exec(`
-    CREATE TABLE "User" (
-      "id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
-      "name" text NOT NULL,
-      "email" text NOT NULL,
-      "age" integer NOT NULL
-    );
-  `);
+  await pglite.exec(pgliteSchema["main-db"]);
 });
 
 afterAll(async () => {
@@ -201,21 +205,19 @@ test("upserts against real rows", async () => {
 });
 ```
 
-A `.serial()` field is omitted from generated `getDB()` inserts, so its PGlite column must generate a value. Use an identity for an integer serial. For a formatted string serial, create a sequence and reproduce the format in its `DEFAULT` expression:
+The generated columns follow the Kysely types, not TailorDB's storage: `text` for string and enum fields, `timestamptz` for datetime, `date` and `time` for date and time, `numeric` for decimal, rounded to the configured scale and read back with exactly that many fractional digits, `jsonb` for nested objects (and arrays of them), Postgres arrays for other array fields. `id` is a generated `uuid` primary key, `.unique()` fields and unique `.indexes()` are enforced, so `ON CONFLICT` upserts behave, and `.default()` values become column defaults (`"now"` becomes the current time). `.serial()` fields are assigned by the database from the configured `start`, `maxValue`, and format. Relations are not enforced.
 
-```sql
-CREATE SEQUENCE "invoiceNumberSequence" START WITH 1000;
-CREATE TABLE "Invoice" (
-  "sequentialId" integer GENERATED BY DEFAULT AS IDENTITY (START WITH 1),
-  "invoiceNumber" text NOT NULL
-    DEFAULT ('INV-' || lpad(nextval('"invoiceNumberSequence"')::text, 5, '0'))
-);
-```
+What the script cannot reproduce:
+
+- Hooks, validations, and permissions do not run. A required field whose value only its own field-level create hook supplies is created nullable, so inserts that omit it succeed; give it a `.default()` if the test reads it back. A field filled by a table-level hook stays `NOT NULL`, as its Kysely type still requires it on insert.
+- Serial formats are reproduced for a single `%d`, `%x`, or `%X` specifier with an optional zero-padded width; an octal `%o` format fails generation with an error naming the field.
+- A datetime inside a nested object reads back as a string from `jsonb`, not a `Date`.
+- On a persistent PGlite (`dataDir`), tables created by an earlier run are kept as they were; drop them or start from an empty directory after changing a table definition.
 
-PGlite does not apply the TailorDB `.serial()` configuration itself. Match the `start`, `format`, and any limit that the behavior under test relies on.
+To hand-write DDL instead — for a table not in the schema, or to add a constraint — run your own statements after the script, or without it.
 
 - The PGlite instance is yours: the mock never closes it, so close it in `afterAll`. Reuse one instance across a suite — creating one per test is slow.
-- Pass the same instance under several namespaces to drive them against one shared database.
+- Pass the same instance under several namespaces to drive them against one shared database. Two namespaces with a same-named table cannot share one instance, because the second script leaves the first table as it is.
 - Seed through `getDB` itself. When a column type rejects a value that only the test must stage, use `createKyselyPGlite<Unmigrated<...>>(pglite)` instead — see [Testing Migrations Locally](services/tailordb-migration.md#testing-migrations-locally). This only affects test setup; it cannot supply a `.serial()` value for an insert issued by the code under test.
 - Transactions on a shared instance are serialized: while one is open, queries from other `getDB` instances wait. Do not use `test.concurrent` with a shared instance, and do not query the same instance through a second `getDB` from inside a transaction — that waits on itself.
 - PGlite runs full PostgreSQL while TailorDB supports a subset of it, and TailorDB hooks, validations, and permissions do not run here — a test passing on PGlite can still behave differently on the platform. Keep [`mockTailordb`](#tailordb-mock) or [`createKyselyMock`](#kysely-layer-mock-createkyselymock) tests for query shape and error paths, and E2E tests for platform behavior.