docs(examples): add advanced examples (union, recursive JSON, explicit Infer)

The basic example only covers an object of primitives. Add an
`examples/advanced` package showing the three patterns that need extra
notation, each materialized into a concrete `.gen.ts` type:

- a discriminated union that narrows on a `kind` literal;
- a recursive/cyclic JSON value, which needs a hand-written self-referential
  type, a `GenericSchema<…>` annotation to break the inference cycle, and
  `lazy(() => …)` at each self-reference (without the annotation the recursive
  position silently degrades to `any`);
- the explicit `export type T = Infer<typeof schema>` marker for a
  helper-built schema that syntactic auto-discovery cannot find.

`main.ts` consumes the generated types and pins `null` in the JSON output via
typed assignments, so codegen dropping a member would fail the type-check.
Link the new package from the root and basic READMEs.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: ushironoko

README.md

@@ -162,6 +162,11 @@ a documented mapping (and warns on anything it cannot represent).
 - **`union`** emits a single schema-level issue on failure (no per-member aggregation yet).
 - **`pipe(schema, transform(fn))`** infers `fn`'s input from an explicit parameter annotation; annotate it (`transform((s: string) => …)`) when the input isn't otherwise constrained.
 
+## Examples
+
+- [`examples/basic`](examples/basic) — the smallest end-to-end loop: schema → generated type → validate.
+- [`examples/advanced`](examples/advanced) — discriminated unions, recursive (cyclic) schemas (`lazy` + `GenericSchema`), and the explicit `export type T = Infer<typeof schema>` marker.
+
 ## Development
 
 ```bash

bun.lock

@@ -0,0 +1,109 @@
+# @tskm/example-advanced
+
+Three patterns past the [basic loop](../basic): **discriminated unions, recursive (cyclic)
+schemas, and the explicit `Infer` marker.** Each schema is materialized into a concrete
+`.gen.ts` type by `tskm gen`, so consuming it ([`src/main.ts`](src/main.ts)) costs the type
+system nothing.
+
+## 1. Discriminated union
+
+[`src/union.schema.ts`](src/union.schema.ts) — every member carries a `kind` literal:
+
+```ts
+export const shapeSchema = union([
+  object({ kind: literal("circle"), radius: number() }),
+  object({ kind: literal("rectangle"), width: number(), height: number() }),
+  object({ kind: literal("text"), content: string() }),
+])
+```
+
+generates the full union as a concrete type ([`union.schema.gen.ts`](src/union.schema.gen.ts)),
+which narrows on `kind` like any hand-written union:
+
+```ts
+export type Shape = {
+  kind: "circle";
+  radius: number;
+} | {
+  kind: "rectangle";
+  width: number;
+  height: number;
+} | {
+  kind: "text";
+  content: string;
+}
+```
+
+## 2. Recursive / cyclic schema — the special notation
+
+[`src/json.schema.ts`](src/json.schema.ts) models a JSON value, which is both a **union** and
+**recursive** (a JSON value contains JSON values). TypeScript cannot *infer* a self-referential
+type, so a recursive schema needs three things that a normal schema does not:
+
+1. **Hand-write the recursive type** — `Json` mentions `Json`.
+2. **Annotate the const** with `GenericSchema<Json>` — this breaks the inference cycle.
+3. **Wrap each self-reference in `lazy(() => …)`** — so the schema object can be built before
+   it finishes referring to itself (the getter runs on first parse).
+
+```ts
+export type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
+
+export const jsonSchema: GenericSchema<Json> = union([
+  string(),
+  number(),
+  boolean(),
+  null_(),
+  array(lazy(() => jsonSchema)),
+  record(lazy(() => jsonSchema)),
+])
+```
+
+`tskm gen` materializes a correct **self-referential** type ([`json.schema.gen.ts`](src/json.schema.gen.ts)):
+
+```ts
+export type Json = string | number | boolean | Json[] | {
+  [x: string]: Json;
+} | null
+```
+
+> **The annotation is required, not optional.** Without `GenericSchema<Json>` the recursive
+> position silently degrades to `any` — tskm's fail-closed guard only inspects the top-level
+> type, not nested `any`, so codegen would emit a wrong type with no diagnostic. (At runtime
+> `lazy` follows the input's depth and is not cycle-guarded, so a pathologically deep value can
+> overflow the stack.)
+
+## 3. The explicit `Infer` marker — opt-in discovery
+
+tskm's auto-discovery is syntactic: it only finds a **direct** `export const x = object(…)`
+(or another tskm factory). A schema built by a **helper** is invisible to it. In
+[`src/book.schema.ts`](src/book.schema.ts) the const's initializer is a call to `makeEntity`,
+not a tskm factory:
+
+```ts
+function makeEntity<E extends ObjectEntries>(entries: E) {
+  return object({ id: string(), ...entries })
+}
+
+export const bookSchema = makeEntity({ title: string(), pages: number() })
+
+// Opt in explicitly — this marker is what `tskm gen` keys on.
+export type Book = Infer<typeof bookSchema>
+```
+
+`export type T = Infer<typeof schema>` (or `InferOutput<…>`) tells the compiler to materialize
+that schema anyway. It writes the concrete `Book` into [`book.schema.gen.ts`](src/book.schema.gen.ts);
+import `Book` from there. (`tskm gen --mode inplace` rewrites the marker *in place* instead of
+writing a sidecar — see the root README.)
+
+## Generate
+
+From the repository root (after `bun install` + `bun run build`):
+
+```bash
+node packages/compiler/dist/cli.mjs gen --root examples/advanced
+# in a published project this is simply:  npx tskm gen   (or  bunx tskm gen)
+```
+
+`tsconfig.json` maps `@tskm/core` to the workspace source via `paths` so the checker can resolve
+the inferred output type. In a real project `@tskm/core` is a normal dependency and no `paths`
+entry is needed.

examples/advanced/README.md

@@ -0,0 +1,12 @@
+{
+  "name": "@tskm/example-advanced",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "dependencies": {
+    "@tskm/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@tskm/compiler": "workspace:*"
+  }
+}

examples/advanced/package.json

@@ -0,0 +1,7 @@
+// AUTO-GENERATED by tskm. Do not edit.
+
+export type Book = {
+  id: string;
+  title: string;
+  pages: number;
+}

examples/advanced/src/book.schema.gen.ts

@@ -0,0 +1,19 @@
+import { type Infer, number, type ObjectEntries, object, string } from "@tskm/core"
+
+// tskm's auto-discovery is syntactic and conservative: it only matches a *direct*
+// `export const x = object(…)` (or another tskm factory). A schema returned by a HELPER is
+// invisible to it — the initializer here is a call to `makeEntity`, not to a tskm factory.
+function makeEntity<E extends ObjectEntries>(entries: E) {
+  return object({ id: string(), ...entries })
+}
+
+export const bookSchema = makeEntity({
+  title: string(),
+  pages: number(),
+})
+
+// So you opt in explicitly. `export type … = Infer<typeof schema>` is the marker `tskm gen`
+// keys on; it materializes the concrete `Book` type into book.schema.gen.ts. Import `Book`
+// from the generated file (main.ts) — this alias stays the generic, type-level form and
+// exists purely to tell the compiler "also generate this one".
+export type Book = Infer<typeof bookSchema>

examples/advanced/src/book.schema.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by tskm. Do not edit.
+
+export type Json = string | number | boolean | Json[] | {
+  [x: string]: Json;
+} | null

examples/advanced/src/json.schema.gen.ts

@@ -0,0 +1,34 @@
+import {
+  array,
+  boolean,
+  type GenericSchema,
+  lazy,
+  null_,
+  number,
+  record,
+  string,
+  union,
+} from "@tskm/core"
+
+// A recursive (self-referential / cyclic) schema. TypeScript cannot INFER a type that
+// refers to itself, so a recursive schema needs three special things:
+//
+//   1. Hand-write the recursive type — `Json` mentions `Json`.
+//   2. Annotate the const with `GenericSchema<Json>` — this breaks the inference cycle so
+//      the schema type-checks against the hand-written shape.
+//   3. Wrap each self-reference in `lazy(() => jsonSchema)` so the schema object can be
+//      constructed before it finishes referring to itself (the getter runs on first parse).
+//
+// The annotation is REQUIRED, not optional: without it the recursive position silently
+// degrades to `any` (tskm's fail-closed guard only inspects the top-level type, not nested
+// `any`), so codegen would quietly emit a wrong type with no diagnostic.
+export type Json = string | number | boolean | null | Json[] | { [key: string]: Json }
+
+export const jsonSchema: GenericSchema<Json> = union([
+  string(),
+  number(),
+  boolean(),
+  null_(),
+  array(lazy(() => jsonSchema)),
+  record(lazy(() => jsonSchema)),
+])

examples/advanced/src/json.schema.ts

@@ -0,0 +1,54 @@
+import { parse, safeParse } from "@tskm/core"
+import type { Book } from "./book.schema.gen.ts"
+import { bookSchema } from "./book.schema.ts"
+import type { Json } from "./json.schema.gen.ts"
+import { jsonSchema } from "./json.schema.ts"
+import type { Shape } from "./union.schema.gen.ts"
+import { shapeSchema } from "./union.schema.ts"
+
+// 1. Discriminated union — the generated `Shape` narrows on `kind`, with no
+//    `Infer<typeof shapeSchema>` paid at the use site.
+const shapes: Shape[] = [
+  { kind: "circle", radius: 2 },
+  { kind: "rectangle", width: 3, height: 4 },
+  { kind: "text", content: "hello" },
+]
+for (const shape of shapes) {
+  switch (shape.kind) {
+    case "circle":
+      console.log("circle area:", Math.PI * shape.radius ** 2)
+      break
+    case "rectangle":
+      console.log("rect area:", shape.width * shape.height)
+      break
+    case "text":
+      console.log("text:", shape.content)
+      break
+  }
+}
+const parsedShape = parse(shapeSchema, { kind: "circle", radius: 1 })
+console.log("parsed shape kind:", parsedShape.kind)
+
+// 2. Recursive JSON value — the generated `Json` is self-referential AND keeps `null`.
+//    These assignments force every member to exist: if codegen ever dropped `null`,
+//    arrays, or the record case, `tsgo --noEmit` over this file would fail to compile.
+const jsonNull: Json = null
+const jsonArray: Json = [1, "two", true, null]
+const jsonObject: Json = { a: 1, b: [null], c: { nested: "deep" } }
+console.log("json values:", jsonNull, jsonArray, jsonObject)
+
+const parsedJson = parse(jsonSchema, { items: [1, null, "x"], ok: true })
+console.log("parsed json:", JSON.stringify(parsedJson))
+
+// A function is not valid JSON — the recursive union rejects it.
+const notJson = safeParse(jsonSchema, () => 1)
+console.log("function is valid JSON?", notJson.success)
+
+// 3. Explicit `Infer` marker — `bookSchema` is built by a helper, so auto-discovery
+//    skips it; the `export type Book = Infer<…>` marker is what made `tskm gen` emit
+//    the concrete `Book` type that we import here.
+const book: Book = { id: "b1", title: "Types", pages: 200 }
+const bookResult = safeParse(bookSchema, book)
+if (bookResult.success) {
+  console.log("book ok:", bookResult.output.title)
+}

examples/advanced/src/main.ts

@@ -0,0 +1,13 @@
+// AUTO-GENERATED by tskm. Do not edit.
+
+export type Shape = {
+  kind: "circle";
+  radius: number;
+} | {
+  kind: "rectangle";
+  width: number;
+  height: number;
+} | {
+  kind: "text";
+  content: string;
+}