@graph8/sdk 0.362.0 → 0.373.0

package/dist/types/blocks/add.d.ts

@@ -7,8 +7,9 @@
  * Never overwrites a file that differs from the template unless `--force`;
  * prints a diff summary instead. Re-running is a no-op.
  */
+import { installedRel } from "./paths";
 import { type Block, type Registry } from "./registry";
-export declare const ADD_USAGE = "Usage: npx @graph8/sdk add <block>[/<Component>] [options]\n\nCopy a graph8 block (components, hooks, recipes) into your app. The block's\ndependencies (always including `foundation`) are added first.\n  --dir <path>      project root (default: current directory)\n  --target <path>   where to copy, relative to --dir (default: components/g8)\n  --dry-run         print what would change, write and install nothing\n  --force           overwrite files that differ from the template\n  --no-install      do not install missing peer dependencies\nExisting files are never overwritten without --force. Installed blocks are\nrecorded in graph8.json so re-runs do nothing.";
+export declare const ADD_USAGE = "Usage: npx @graph8/sdk add <block>[/<Component>] [options]\n\nCopy a graph8 block (components, hooks, recipes) into your app. The block's\ndependencies (always including `foundation`) are added first.\n  --dir <path>      project root (default: current directory)\n  --target <path>   where to copy, relative to --dir (default: components/g8)\n  --dry-run         print what would change, write and install nothing\n  --force           overwrite files that differ from the template\n  --no-install      do not install missing peer dependencies\n  --routes          also add the block's screens as routes and sidebar entries (lib/nav.ts, plus the\n                    lucide-react icon dependency). Automatic in apps made with `create --blocks`; off by\n                    default in apps made from a named stack (create apollo, starter, ...), where running it once opts the\n                    app in, so later add calls wire routes without the flag\nExisting files are never overwritten without --force. Installed blocks are\nrecorded in graph8.json so re-runs do nothing.";
 export interface AddOptions {
     spec: string;
     dir: string;
@@ -16,6 +17,10 @@ export interface AddOptions {
     dryRun: boolean;
     force: boolean;
     install: boolean;
+    /** Inside an app made by `create`: also add the block's screens as routes and nav entries. Default true. */
+    wireScreens?: boolean;
+    /** `--routes`: opt in to route + nav wiring in a created app that was not made with `create --blocks` (a named stack). */
+    routes?: boolean;
 }
 export declare function parseAddArgs(argv: string[]): AddOptions;
 export type PackageManager = "pnpm" | "yarn" | "bun" | "npm";
@@ -29,9 +34,12 @@ export interface AddIO {
     err: (line: string) => void;
     /** Run a command in `cwd`; returns the exit code. */
     spawn: (cmd: string, args: string[], cwd: string) => number;
+    /** Directory holding `next-app/` (the package's `templates/`); needed to write screen routes. */
+    templatesRoot?: string;
+    /** The package's own package.json (for the lucide-react range of nav icons). */
+    sdkPackageJson?: string;
 }
-/** Where a file at `rel` (inside the block dir) lands, relative to the block's install dir. */
-export declare function installedRel(rel: string): string | null;
+export { installedRel };
 interface RewriteCtx {
     reg: Registry;
     targetAbs: string;
@@ -50,4 +58,3 @@ export declare function rewriteImports(content: string, ctx: RewriteCtx): string
 export declare function diffSummary(before: string, after: string): string;
 /** Run `add`. Returns the process exit code. */
 export declare function runAdd(opts: AddOptions, reg: Registry, io: AddIO, cwd: string): number;
-export {};

package/dist/types/blocks/brand.d.ts

@@ -0,0 +1,122 @@
+/**
+ * `graph8-sdk brand` (and the brand flags of `create`): give a generated app its own name, colour and logo, and
+ * white-label every graph8 link-out in its blocks.
+ *
+ *   - g8.config.ts      `export const brand = { name, appUrl, linkLabel, logo }`, read by the app shell
+ *                       (name, logo) and, through <BrandProvider>, by every block (link-out label and URL)
+ *   - app/globals.css   a generated region with --brand, --brand-foreground, --brand-50..900 and --primary,
+ *                       light and dark, each foreground checked for WCAG AA (4.5:1) and adjusted if needed
+ *   - public/brand/     the logo, copied
+ *
+ * Every write is a marker region or a whole file the CLI owns, so running it again with the same input changes
+ * nothing. Node only; no new dependencies.
+ */
+export type Rgb = [number, number, number];
+/** `#abc` / `#aabbcc` (any case, `#` optional) -> `#aabbcc`, or null. */
+export declare function normalizeHex(input: string): string | null;
+export declare function hexToRgb(hex: string): Rgb;
+export declare function rgbToHex([r, g, b]: Rgb): string;
+/** WCAG 2 relative luminance. */
+export declare function luminance(hex: string): number;
+/** WCAG 2 contrast ratio, 1 to 21. */
+export declare function contrast(a: string, b: string): number;
+/** Mix `hex` toward `toward` by `amount` (0 keeps hex, 1 gives toward), in sRGB. */
+export declare function mix(hex: string, toward: string, amount: number): string;
+/** The app's canvases and ink (templates/next-app/app/globals.css). */
+export declare const CANVAS: {
+    readonly light: "#ffffff";
+    readonly dark: "#111110";
+};
+export declare const INK: {
+    readonly light: "#16140f";
+    readonly dark: "#f2efe9";
+};
+/** WCAG AA: 4.5:1 for text on the brand colour; 3:1 for the brand colour against the canvas (UI components). */
+export declare const AA_TEXT = 4.5;
+export declare const AA_UI = 3;
+export interface BrandSwatch {
+    /** The brand colour as used (adjusted when the input could not carry readable text). */
+    brand: string;
+    /** Text on the brand colour: always at least 4.5:1 against `brand`. */
+    foreground: string;
+    /** 50..900 tints and shades; 500 is `brand`. */
+    scale: Record<string, string>;
+    /** brand against the canvas. */
+    canvasContrast: number;
+}
+export interface BrandTheme {
+    light: BrandSwatch;
+    dark: BrandSwatch;
+    /** What was adjusted or is worth knowing, for the CLI to print. */
+    notes: string[];
+}
+/** Light and dark swatches from a brand colour (and an optional explicit dark one). Throws on a bad hex. */
+export declare function brandTheme(color: string, darkColor?: string): BrandTheme;
+export declare const CSS_START = "/* graph8:brand:start */";
+export declare const CSS_END = "/* graph8:brand:end */";
+/** The generated CSS region (markers included). */
+export declare function brandCss(theme: BrandTheme, source: {
+    color: string;
+    dark?: string;
+}): string;
+/** `css` with the brand region replaced, or appended (after the app's own token blocks, so it wins). */
+export declare function applyCssRegion(css: string, region: string): string;
+export interface BrandFields {
+    name: string;
+    appUrl: string;
+    linkLabel: string;
+    logo?: string;
+}
+export declare const DEFAULT_FIELDS: Omit<BrandFields, "name">;
+export declare const CONFIG_FILE = "g8.config.ts";
+/** The whole g8.config.ts a created app starts with. */
+export declare function renderBrandConfig(f: BrandFields): string;
+/** The values in a g8.config.ts region (best effort), or null when the file has no region. */
+export declare function readBrandConfig(source: string): Partial<BrandFields> | null;
+/** The config with its region rewritten, or null when the user owns the file (no markers). */
+export declare function applyBrandConfig(source: string, f: BrandFields): string | null;
+export declare const BRAND_USAGE = "Usage: npx @graph8/sdk brand [options]\n\nBrand an app made by `create` (run it in the app's root). Every option is optional; values you leave out stay.\n  --name <text>              the app's name (sidebar, page title)\n  --brand-color <hex>        primary colour, e.g. \"#0f62fe\": writes --brand, a 50-900 scale and --primary into\n                             app/globals.css, with button text checked for WCAG AA (adjusted when needed)\n  --dark-brand-color <hex>   the colour in dark mode (default: derived from --brand-color, lightened if too dark)\n  --logo <path>              an svg, png, jpg, webp or gif (max 512 KB), copied to public/brand/ and shown in the sidebar\n  --app-url <url>            white-label: where link-outs go (default https://app.graph8.com)\n  --link-label <text>        white-label: what the platform is called in copy and links (default graph8)\n  --from-org                 fill in what you did not pass from the organization's Brand Kit (needs G8_API_KEY in the\n                             environment or .env.local): name, primary colour, logo. Running brand with no options\n                             does the same when the kit has something. Values you pass always win; they replace what the app has now.\n  --no-org-brand             never read the Brand Kit\n  --dir <path>               the app's root (default: current directory)\n  --dry-run                  print what would change, write nothing\nRunning it again with the same options changes nothing.";
+export interface BrandOptions {
+    dir: string;
+    name?: string;
+    color?: string;
+    darkColor?: string;
+    logo?: string;
+    appUrl?: string;
+    linkLabel?: string;
+    dryRun?: boolean;
+    /** `--from-org`, or a bare `brand`: fill the gaps from the org's Brand Kit. */
+    fromOrg?: boolean;
+    /** `--no-org-brand`. */
+    noOrgBrand?: boolean;
+}
+/** The brand flags (shared with `create`). Returns true when `argv[i]` was one; `next()` consumes its value. */
+export declare function takeBrandFlag(o: Partial<BrandOptions>, flag: string, next: () => string): boolean;
+export declare function hasBrandInput(o: Partial<BrandOptions>): boolean;
+export declare function parseBrandArgs(argv: string[]): BrandOptions;
+export declare const LOGO_TYPES: string[];
+export declare const MAX_LOGO_BYTES: number;
+export type OrgBrandValues = Pick<BrandOptions, "name" | "color" | "logo">;
+/** Explicit options win per field; org values fill only what the user left out. */
+export declare function mergeOrgBrand<T extends Partial<BrandOptions>>(explicit: T | undefined, org: OrgBrandValues, skip?: {
+    name?: boolean;
+}): T;
+export interface BrandIO {
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+interface Planned {
+    rel: string;
+    content: string | Buffer | null;
+    note?: string;
+}
+/** Why these brand options cannot be applied, or null. `create` checks this before it writes anything. */
+export declare function brandProblem(o: Omit<BrandOptions, "dir">, cwd: string): string | null;
+/** Plan every write `brand` makes. Pure apart from reading files. */
+export declare function planBrand(o: BrandOptions, root: string, cwd: string, fallbackName?: string): {
+    files: Planned[];
+    notes: string[];
+};
+/** Run `brand`. Returns the exit code. */
+export declare function runBrand(given: BrandOptions, io: BrandIO, cwd: string, fallbackName?: string, org?: OrgBrandValues): number;
+export {};

package/dist/types/blocks/compose.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Screens as routes: which pages and sidebar entries an app gets for a set of blocks.
+ *
+ * A block declares them in `block.json` `screens` (optional). Without it they are derived from the
+ * components named `<Name>Screen` (`ContactsScreen` -> `/contacts`, "Contacts"). A block with no Screen at all
+ * falls back to its first component that needs no props, the way stacks always did, and `fallback` marks it so
+ * `create` and `doctor` can warn. Used by `create --blocks`, `add` (inside a created app) and `doctor`.
+ *
+ * Node only. Reads block sources (to find which components take required props); writes nothing.
+ */
+import { type Block, type Registry, type Stack } from "./registry";
+export interface ResolvedScreen {
+    block: string;
+    component: string;
+    /** Unique across the app once passed through `composeNav`. */
+    path: string;
+    label: string;
+    icon: string;
+    group: string;
+    description?: string;
+    /** True when the block ships no `*Screen`: this is its first component that needs no props. */
+    fallback: boolean;
+}
+/** lucide-react icon per block id (all verified to exist by the test suite); a screen can override it. */
+export declare const BLOCK_ICONS: Record<string, string>;
+export declare const FALLBACK_ICON = "LayoutGrid";
+/**
+ * Whether the component can render with no props. Conservative: anything it cannot read (an imported props type,
+ * a re-export, an unusual signature) counts as "needs props", so a fallback never picks a component that would crash.
+ */
+export declare function takesNoRequiredProps(source: string, name: string): boolean;
+/** The screens of one block (declared, else derived, else the no-props fallback). Never throws on odd manifests. */
+export declare function screensOf(block: Block): ResolvedScreen[];
+/** True when the block ships a finished screen (declared or a `*Screen` component), not just the fallback. */
+export declare const hasRealScreen: (block: Block) => boolean;
+export interface ComposeOptions {
+    /** Include the (no-`Screen`) fallback pages of dependency blocks too. Default false. */
+    withDepsScreens?: boolean;
+    /** Include no dependency screens at all. Default false. */
+    noDepsScreens?: boolean;
+    title?: string;
+}
+export interface Composed {
+    stack: Stack;
+    screens: ResolvedScreen[];
+    /** Plain-language problems the person should know about (blocks with only a fallback page, none at all). */
+    warnings: string[];
+}
+/**
+ * The app for `ids`: requested blocks first (in the order given), then the screens of their dependencies that are
+ * user-facing. `home` is the analytics screen when there is one, else the first screen.
+ */
+export declare function composeApp(reg: Registry, ids: string[], opts?: ComposeOptions): Composed;

package/dist/types/blocks/create.d.ts

@@ -7,9 +7,11 @@
  * Node only. Reads `templates/next-app/**` (shipped in the package) and the
  * block registry; writes only inside `<dir>`.
  */
+import { type OrgBrandValues, type BrandOptions } from "./brand";
 import { type AddIO, type PackageManager } from "./add";
+import { componentImportPath, navParts, navUsesExtras, pageFileFor, render } from "./navfile";
 import { type Registry, type Stack, type StackNav } from "./registry";
-export declare const CREATE_USAGE = "Usage: npx @graph8/sdk create <stack> <dir> [options]\n\nScaffold a Next.js (App Router, TypeScript, Tailwind CSS v4) app for a stack and\ninstall the stack's blocks into it. Run `graph8-sdk list` to see the stacks.\n  --package-manager <npm|pnpm|yarn|bun>   default: the one running the command, else npm\n  --no-install      write the files and blocks, do not install dependencies\n  --dry-run         print what would be written, write and install nothing\n  --force           allow a non-empty <dir> (template files are overwritten, and graph8.json\n                    is reset: blocks you added to that app earlier are no longer recorded)\nThen: set G8_API_KEY in <dir>/.env.local and run `npx @graph8/sdk doctor --stack <stack>`.";
+export declare const CREATE_USAGE = "Usage: npx @graph8/sdk create <stack> <dir> [options]\n\nScaffold a Next.js (App Router, TypeScript, Tailwind CSS v4) app for a stack and\ninstall the stack's blocks into it. Run `graph8-sdk list` to see the stacks.\n  --package-manager <npm|pnpm|yarn|bun>   default: the one running the command, else npm\n  --no-install      write the files and blocks, do not install dependencies\n  --dry-run         print what would be written, write and install nothing\n  --force           allow a non-empty <dir> (template files are overwritten, and graph8.json\n                    is reset: blocks you added to that app earlier are no longer recorded)\nThen: `npm run dev` in <dir>, open http://localhost:3000 and paste a graph8 API key (local preview), and run\n`npx @graph8/sdk doctor --stack <stack>` (add --production before going live).\n\nOr pick the features yourself, for any app (also: `create custom --blocks ...`):\n  npx @graph8/sdk create --blocks <id,id,...> [--title \"Acme CRM\"] <dir> [options]\nEvery requested block's dependencies come with it. The app gets one route and one sidebar entry per finished\nScreen of the requested blocks, plus the user-facing Screens of their dependencies (asking for deals also gives\nyou crm's screens). `/` opens the analytics screen if you asked for one, else the first screen.\n  --title <text>          the app's name (default: graph8 app)\n  --with-deps-screens     also add the plain fallback page of dependency blocks that have no Screen\n  --no-deps-screens       add screens only for the blocks you named\nRun `graph8-sdk list` to see each block and which have Screens.\n\nBrand it (any stack or --blocks; the same as running `graph8-sdk brand` in the new app afterwards):\n  --name <text>             the app's name (with --blocks, the same as --title)\n  --brand-color <hex>       primary colour, AA-checked; --dark-brand-color <hex> for dark mode\n  --logo <path>             svg/png/jpg/webp/gif, shown in the sidebar\n  --app-url <url>           white-label: where \"Open in graph8\" links go; --link-label <text>: what they call it\nWith a graph8 API key (G8_API_KEY in the environment or .env.local) the org's Brand Kit fills in what you did not\npass: the app name, the primary colour and the logo (downloaded into public/brand/). No key, no kit or an error:\nthe default look, one info line, never a failure. --no-org-brand skips it.\nA directory literally named `custom` would read as the alias: pass `--blocks crm ./custom`.";
 export interface CreateOptions {
     stack: string;
     dir: string;
@@ -17,8 +19,27 @@ export interface CreateOptions {
     install: boolean;
     dryRun: boolean;
     force: boolean;
+    /** `create --blocks a,b`: a custom app from these blocks instead of a named stack (`stack` is then "custom"). */
+    blocks?: string[];
+    title?: string;
+    /** Dependency-block screens: `default` (their finished Screens), `with` (plus fallback pages) or `none`. */
+    depsScreens?: "default" | "with" | "none";
+    /** `--name`, `--brand-color`, `--logo`, ...: applied with `graph8-sdk brand` once the app is written. */
+    brand?: Omit<BrandOptions, "dir" | "dryRun">;
+    /** false with `--no-org-brand`: do not pull the org's Brand Kit. */
+    orgBrand?: false;
 }
 export declare function parseCreateArgs(argv: string[]): CreateOptions;
+/** What `graph8.json` records about a custom app, so `add` and `doctor` know its routes. */
+export interface AppRecord {
+    title: string;
+    blocks: string[];
+    screens: {
+        block: string;
+        component: string;
+        path: string;
+    }[];
+}
 export interface CreateIO extends AddIO {
     /** Directory holding `next-app/` (the package's `templates/`). */
     templatesRoot: string;
@@ -26,35 +47,21 @@ export interface CreateIO extends AddIO {
     sdkPackageJson?: string;
     /** npm_config_user_agent, to default the package manager. */
     userAgent?: string;
+    /** Name, colour and logo pulled from the org's Brand Kit (see orgBrand.ts); explicit brand flags win. */
+    orgBrand?: OrgBrandValues;
 }
 export declare function packageManagerFromUserAgent(ua: string | undefined): PackageManager;
 /** A valid npm package name from a directory name. */
 export declare function appNameFor(dir: string): string;
-/** Replace `{{key}}`; a placeholder with no value is a template bug, not something to ship. */
-export declare function render(template: string, vars: Record<string, string>): string;
 interface OutFile {
     rel: string;
     content: string;
 }
-/** Route file for a nav path: `/` -> app/page.tsx, `/a/b` -> app/a/b/page.tsx. */
-export declare function pageFileFor(navPath: string): string;
 /** Why this stack cannot be scaffolded, or null. */
 export declare function stackProblem(reg: Registry, stack: Stack): string | null;
 /** Absolute path of a nav entry's hand-written page template, or null when it uses the generic route page. */
 export declare function stackPageFile(reg: Registry, stack: Stack, n: StackNav): string | null;
-/** True when any nav entry uses `icon`, `group` or `description`. */
-export declare function navUsesExtras(stack: Stack): boolean;
-/**
- * The three pieces of `lib/nav.ts`. A stack that uses none of the optional nav fields gets exactly the
- * plain `{ label, path }[]` file it always did; otherwise a typed `NavItem[]` whose icons are real
- * lucide-react imports (only the ones used).
- */
-export declare function navParts(stack: Stack): {
-    navImports: string;
-    navType: string;
-    navJson: string;
-};
-export declare function planCreate(reg: Registry, stack: Stack, appName: string, pm: PackageManager, io: CreateIO): OutFile[];
+export declare function planCreate(reg: Registry, stack: Stack, appName: string, pm: PackageManager, io: CreateIO, app?: AppRecord): OutFile[];
 /** Run `create`. Returns the process exit code. */
-export declare function runCreate(opts: CreateOptions, reg: Registry, io: CreateIO, cwd: string): number;
-export {};
+export declare function runCreate(given: CreateOptions, reg: Registry, io: CreateIO, cwd: string): number;
+export { componentImportPath, navParts, navUsesExtras, pageFileFor, render };

package/dist/types/blocks/doctor.d.ts

@@ -7,12 +7,16 @@
  * never printed, not even in an error.
  */
 import { type Registry } from "./registry";
-export declare const DOCTOR_USAGE = "Usage: npx @graph8/sdk doctor [--stack <id>] [--blocks a,b] [--dir <path>] [--strict]\n\nCheck that this project is ready for graph8 blocks:\n  - G8_API_KEY (env or .env.local) is valid\n  - the key's scopes cover the blocks you chose\n  - the organization's subscription is active\n  - a checklist of in-app setup each block needs\nWith --stack it also lists \"Flows\": block components that no page of the stack reaches\n(a warning; --strict makes them fail the run).\nWith no --stack/--blocks, the blocks recorded in graph8.json are checked.\nOptional G8_API_URL points at a non-default API. Exit code 0 when all checks\npass, 1 otherwise.";
+export declare const DOCTOR_USAGE = "Usage: npx @graph8/sdk doctor [--stack <id>] [--blocks a,b] [--dir <path>] [--strict] [--production] [--fix-prefixes]\n\nCheck that this project is ready for graph8 blocks:\n  - G8_API_KEY (env or .env.local) is valid\n  - the key's scopes cover the blocks you chose\n  - the organization's subscription is active\n  - a checklist of in-app setup each block needs\nWith --stack it also lists \"Flows\": block components that no page of the stack reaches\n(a warning; --strict makes them fail the run).\nWith no --stack/--blocks, the blocks recorded in graph8.json are checked.\nIt also reads the proxy route (app/api/g8/[...path]/route.ts) and warns about what is left before going live:\n  --production      fail instead: no `authorize` (local preview would be the only gate), no allowedPrefixes,\n                    or a dangerouslyAllow* switch on; and the key must come from the environment\n  --fix-prefixes    rewrite the route's generated allowedPrefixes from the installed blocks (graph8.json), then exit\n                    (no network). A route written before 0.367.0 is upgraded only if its list is still the default.\nOptional G8_API_URL points at a non-default API. Exit code 0 when all checks\npass, 1 otherwise.";
 export interface DoctorOptions {
     stack?: string;
     blocks: string[];
     dir: string;
     strict?: boolean;
+    /** Going-live gate: route problems fail the run instead of warning. */
+    production?: boolean;
+    /** Rewrite the route's generated allowedPrefixes and exit. */
+    fixPrefixes?: boolean;
 }
 export declare function parseDoctorArgs(argv: string[]): DoctorOptions;
 export interface DoctorIO {
@@ -21,6 +25,7 @@ export interface DoctorIO {
     env: Record<string, string | undefined>;
     fetch?: typeof fetch;
 }
+export declare function readSetting(name: string, root: string, env: DoctorIO["env"]): string | undefined;
 /** Same rules as the server's `key_has_scope`. */
 export declare function scopeGranted(granted: string[], required: string): boolean;
 /** Run doctor. Returns the exit code: 0 when every check passes. */

package/dist/types/blocks/flows.d.ts

@@ -14,7 +14,13 @@ export interface UnreachedComponent {
     component: string;
 }
 /**
- * Components of the stack's own blocks (the foundation's shared UI is exempt) that no
+ * Library blocks hold shared building blocks that other blocks import, not pages of their own: the foundation's shared
+ * UI and the pickers. A stack installs them whole but each screen uses only some, so they are never "unreached".
+ * Every other block is judged component by component.
+ */
+export declare const LIBRARY_BLOCKS: ReadonlySet<string>;
+/**
+ * Components of the stack's own blocks (library blocks are exempt) that no
  * generated page reaches, directly or through a Screen that imports them.
  */
 export declare function unreachedComponents(reg: Registry, stack: Stack): UnreachedComponent[];

package/dist/types/blocks/navfile.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pieces of a created app that `create` and `add` both write: route page files, `lib/nav.ts` and
+ * template rendering. Shared so a screen added later looks exactly like one generated up front.
+ */
+import type { Block, Stack } from "./registry";
+/** Replace `{{key}}`; a placeholder with no value is a template bug, not something to ship. */
+export declare function render(template: string, vars: Record<string, string>): string;
+/** Route file for a nav path: `/` -> app/page.tsx, `/a/b` -> app/a/b/page.tsx. */
+export declare function pageFileFor(navPath: string): string;
+export declare function componentImportPath(block: Block, file: string): string;
+/** The nav fields `lib/nav.ts` carries. */
+export interface NavEntry {
+    label: string;
+    path: string;
+    icon?: string;
+    group?: string;
+    description?: string;
+}
+/** True when any nav entry uses `icon`, `group` or `description`. */
+export declare function navUsesExtras(nav: NavEntry[]): boolean;
+/**
+ * The three pieces of `lib/nav.ts`. A stack that uses none of the optional nav fields gets exactly the
+ * plain `{ label, path }[]` file it always did; otherwise a typed `NavItem[]` whose icons are real
+ * lucide-react imports (only the ones used).
+ */
+export declare function navPartsFor(nav: NavEntry[]): {
+    navImports: string;
+    navType: string;
+    navJson: string;
+};
+export declare function navParts(stack: Stack): {
+    navImports: string;
+    navType: string;
+    navJson: string;
+};

package/dist/types/blocks/orgBrand.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Pull the organization's Brand Kit into a new app: `create` and `brand --from-org`.
+ *
+ * Reads two Developer API operations with the project's key (the same resolution `doctor` uses: G8_API_KEY from
+ * the environment, then .env.local; G8_API_URL for a non-default API):
+ *   - get_brand_kit_overview_brand_kit_get  -> logo_url, design_tokens.colors, source_url (scope campaigns:read)
+ *   - describe_current_key_me_get           -> org_name
+ * The kit has ONE logo URL (no light/dark/icon variant), a measured colour palette and fonts, a tagline and voice
+ * traits. Only the name, the primary colour and the logo map onto the brand inputs; fonts, tagline and voice have no
+ * SDK brand input and are ignored.
+ *
+ * Never fails the caller: no key, a 4xx/5xx, a network error, a timeout or an empty kit all give `{}` plus one info
+ * line. The key is never printed or written. The logo is downloaded to a temp file (https or data: URL, an image type,
+ * at most 512 KB) so `brand` copies it into public/brand/ like any `--logo` file: nothing is hot-linked.
+ */
+import { mergeOrgBrand, type OrgBrandValues } from "./brand";
+export { mergeOrgBrand, type OrgBrandValues };
+export interface OrgBrandPull {
+    values: OrgBrandValues;
+    /** One line for the CLI to print. */
+    info: string;
+    /** Remove the temp logo file. */
+    cleanup: () => void;
+}
+export interface OrgBrandIO {
+    env: Record<string, string | undefined>;
+    fetch?: typeof fetch;
+}
+/** The primary colour of the kit's measured tokens, or null. */
+export declare function pickColor(tokens: unknown): string | null;
+/** A display name that is safe to write into generated files. */
+export declare function cleanName(v: unknown): string | null;
+/** Pull name, primary colour and logo from the org's Brand Kit. Never throws. */
+export declare function pullOrgBrand(io: OrgBrandIO, root: string): Promise<OrgBrandPull>;

package/dist/types/blocks/paths.d.ts

@@ -0,0 +1,4 @@
+/** Tiny path helpers shared by `add`, `create` and the screen wiring (kept free of imports to avoid cycles). */
+export declare const posix: (p: string) => string;
+/** Where a file at `rel` (inside the block dir) lands, relative to the block's install dir. */
+export declare function installedRel(rel: string): string | null;

package/dist/types/blocks/prefixes.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The proxy route's `allowedPrefixes`, derived instead of hand-written: the first path segment of every contract
+ * operation the installed blocks declare (`GET /contacts/{id}` -> "contacts"). Never wider than what the blocks
+ * declare. `create` and `add` write them between two marker comments in `app/api/g8/[...path]/route.ts`;
+ * `doctor --fix-prefixes` rewrites them; `doctor` reads the route to say what is still open before going live.
+ *
+ * Pure string functions (no file system), so they are easy to test.
+ */
+import type { Block } from "./registry";
+export declare const PREFIX_START = "// graph8:allowed-prefixes:start";
+export declare const PREFIX_END = "// graph8:allowed-prefixes:end";
+/** "contacts" for `/contacts/{id}`; null for an unknown operation or a path that starts with a parameter. */
+export declare function prefixOf(operationId: string): string | null;
+/** Sorted, distinct prefixes of every operation the blocks declare. */
+export declare function derivePrefixes(blocks: readonly Pick<Block, "operations">[]): string[];
+/** `["a", "b", ...]` wrapped at about 110 columns, as the TypeScript expression of the generated line. */
+export declare function formatPrefixes(prefixes: readonly string[]): string;
+/** The generated region, markers included. */
+export declare function prefixRegion(prefixes: readonly string[]): string;
+/** True when the route file has the generated region. */
+export declare function hasPrefixRegion(source: string): boolean;
+/** The route with its generated region replaced, or null when it has no region (the user owns the list). */
+export declare function applyPrefixes(source: string, prefixes: readonly string[]): string | null;
+/** A pre-0.367 route whose allowedPrefixes line is still the untouched `undefined` default, upgraded to a region. */
+export declare function upgradeLegacyRoute(source: string, prefixes: readonly string[]): string | null;
+export interface RouteFacts {
+    /** `authorize` is set (not commented out). */
+    authorize: boolean;
+    localPreview: boolean;
+    dangerouslyAllowUnauthenticated: boolean;
+    dangerouslyAllowAllPaths: boolean;
+    /** The literal list, undefined when it is `undefined`, "custom" when it is not a literal list. */
+    prefixes: string[] | undefined | "custom";
+    generated: boolean;
+}
+/** What a route file configures, read from its source (best effort, for `doctor`). */
+export declare function inspectRoute(source: string): RouteFacts;

package/dist/types/blocks/registry.d.ts

@@ -38,6 +38,21 @@ export interface BlockPrerequisite {
     where: "app" | "api";
     verify?: string;
 }
+/** Optional `block.json` `screens` entry: how a finished screen appears as a route and a sidebar entry in a created app. */
+export interface BlockScreen {
+    /** A component of this block. */
+    component: string;
+    /** Route path (`/contacts`). Must be static; made unique across an app by prefixing the block id. */
+    path: string;
+    label: string;
+    /** lucide-react export name. */
+    icon?: string;
+    /** Sidebar section (default: the block title). */
+    group?: string;
+    description?: string;
+    /** Sort position inside the block (lower first). */
+    order?: number;
+}
 export interface BlockManifest {
     id: string;
     title: string;
@@ -46,6 +61,8 @@ export interface BlockManifest {
     dependsOn: string[];
     operations: string[];
     components: BlockComponent[];
+    /** Optional route metadata; absent means derive it from the components named `*Screen`. */
+    screens?: BlockScreen[];
     hooks: BlockHook[];
     lib: {
         file: string;

package/dist/types/blocks/screens.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `graph8-sdk add <block>` inside an app that `create` made: give the new block's finished screens a route and a
+ * sidebar entry too, so the app the person asked for keeps working as they grow it.
+ *
+ * Idempotent and conservative: a page whose content differs from what we would generate is never touched (the
+ * person edited it), a nav entry for an existing path is never duplicated, and a `lib/nav.ts` we cannot read
+ * back (hand-edited beyond the generated shape) is left alone with the entries printed instead.
+ *
+ * Node only. Pure planning: returns the files to write; the caller prints and writes them.
+ */
+import { type NavEntry } from "./navfile";
+import type { Block, Registry } from "./registry";
+export interface WiredFile {
+    rel: string;
+    content: string;
+    action: "create" | "update" | "unchanged";
+}
+export interface ScreenWiring {
+    files: WiredFile[];
+    /** Plain lines to print after the file list ("kept your edited app/x/page.tsx", manual nav entries). */
+    notes: string[];
+    /** Screens now recorded in graph8.json (existing ones are not repeated). */
+    screens: {
+        block: string;
+        component: string;
+        path: string;
+    }[];
+    /** True when an icon import was written, so `lucide-react` must be installed. */
+    usesIcons: boolean;
+}
+export interface WireInput {
+    reg: Registry;
+    root: string;
+    /** Install directory relative to the project root (`components/g8`). */
+    target: string;
+    /** Blocks to wire, dependencies first; the last one is the block the person asked for. */
+    blocks: Block[];
+    templatesRoot: string;
+    /** The ledger's stack id, written into the generated page comment ("custom" for `create --blocks` apps). */
+    stackId: string;
+    /** Screens already recorded in graph8.json, to stay idempotent. */
+    recorded: {
+        block: string;
+        component: string;
+        path: string;
+    }[];
+}
+/** Parse the generated `lib/nav.ts` back into entries, or null when it is not in the generated shape. */
+export declare function parseNavFile(text: string): {
+    header: string;
+    items: NavEntry[];
+} | null;
+export declare function planScreenWiring(input: WireInput): ScreenWiring | null;

package/dist/types/cli.d.ts

@@ -4,10 +4,13 @@
  *   npx @graph8/sdk init-agent [--claude] [--codex] [--cursor] [--dry-run]
  *   npx @graph8/sdk list | search <text> | add <block>[/<Component>] | doctor
  *   npx @graph8/sdk create <stack> <dir>
+ *   npx @graph8/sdk create --blocks <ids> [--title "Acme CRM"] <dir>
+ *   npx @graph8/sdk brand [--name "Acme"] [--brand-color "#0f62fe"] [--logo ./logo.svg] [--app-url ...] [--link-label ...]
  *
  * Node only. Built as a separate entry (dist/cli.js), so nothing here reaches
  * the browser bundle or the package's main exports.
  */
+import type { OrgBrandValues } from "./blocks/brand";
 export interface CliIO {
     cwd: string;
     out: (line: string) => void;
@@ -24,6 +27,8 @@ export interface CliIO {
     env?: Record<string, string | undefined>;
     /** fetch for `doctor`. Default: global fetch. */
     fetch?: typeof fetch;
+    /** Name, colour and logo pulled from the org's Brand Kit by `runCliAsync` for `create` and `brand`. */
+    orgBrand?: OrgBrandValues;
 }
 export declare function runCli(argv: string[], io: CliIO): number;
 /** Like `runCli`, plus the commands that talk to the network (`doctor`). */

package/dist/types/errors.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `G8Error`: the one error class every graph8 call throws (server SDK and the browser block client).
+ *
+ * It lives in its own tiny entry, `@graph8/sdk/errors`, so browser code that only needs the error class
+ * (the blocks' `g8-client`, `ApiError`) does not pull the whole SDK into a page bundle.
+ *
+ * One identity everywhere: the class is registered on `globalThis` under a well-known symbol, and the
+ * first copy loaded wins. `@graph8/sdk` and `@graph8/sdk/errors` are separate bundles with their own copy
+ * of this file, so without the registry `err instanceof G8Error` would depend on which entry created the
+ * error. With it, both entries export the very same class.
+ */
+declare class G8ErrorClass extends Error {
+    readonly status: number;
+    readonly type: string;
+    readonly code?: string;
+    readonly requestId?: string;
+    readonly detail?: unknown;
+    /** True when the failure class is transient (429/5xx/network). */
+    readonly retryable: boolean;
+    constructor(args: {
+        message: string;
+        status: number;
+        type: string;
+        code?: string;
+        requestId?: string;
+        detail?: unknown;
+        retryable?: boolean;
+    });
+}
+/** Thrown on any failed graph8 call: `status`, `type`, `code`, `requestId`, `detail`, `retryable`. */
+export declare const G8Error: typeof G8ErrorClass;
+export type G8Error = G8ErrorClass;
+export {};

package/dist/types/http.d.ts

@@ -18,24 +18,8 @@
  * `fetch` and `sleep` are injectable so the retry/backoff logic is
  * deterministically unit-testable without real timers or network.
  */
-export declare class G8Error extends Error {
-    readonly status: number;
-    readonly type: string;
-    readonly code?: string;
-    readonly requestId?: string;
-    readonly detail?: unknown;
-    /** True when the failure class is transient (429/5xx/network). */
-    readonly retryable: boolean;
-    constructor(args: {
-        message: string;
-        status: number;
-        type: string;
-        code?: string;
-        requestId?: string;
-        detail?: unknown;
-        retryable?: boolean;
-    });
-}
+import { G8Error } from "./errors";
+export { G8Error };
 /** 429 and 5xx are the transient classes worth retrying. */
 export declare function isRetryableStatus(status: number): boolean;
 /**