@loadbare/app 0.8.0 → 0.8.1

package/dist/build/skills-cli.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * loadbare-app — commands that are not the build.
+ *
+ *   loadbare-app skills install [--copy] [--dir <path>]
+ *
+ * Installs the agent skills that ship in this package into `.agents/skills`
+ * and `.claude/skills`, or into `--dir` alone — see build/skills.ts.  Nothing
+ * goes to stdout; every line is progress, on stderr.
+ */
+export {};
+//# sourceMappingURL=skills-cli.d.ts.map

package/dist/build/skills-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-cli.d.ts","sourceRoot":"","sources":["../../build/skills-cli.ts"],"names":[],"mappings":";AACA;;;;;;;;GAQG"}

package/dist/build/skills-cli.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * loadbare-app — commands that are not the build.
+ *
+ *   loadbare-app skills install [--copy] [--dir <path>]
+ *
+ * Installs the agent skills that ship in this package into `.agents/skills`
+ * and `.claude/skills`, or into `--dir` alone — see build/skills.ts.  Nothing
+ * goes to stdout; every line is progress, on stderr.
+ */
+import { parseArgs } from "node:util";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { findPackageRoot } from "./package-root.js";
+import { installSkills, SKILL_DESTINATIONS } from "./skills.js";
+const USAGE = "usage: loadbare-app skills install [--copy] [--dir <path>]";
+async function main() {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            allowPositionals: true,
+            options: {
+                copy: { type: "boolean", default: false },
+                dir: { type: "string" },
+            },
+        });
+    }
+    catch (err) {
+        console.error(`loadbare-app: ${err.message}`);
+        console.error(USAGE);
+        return 1;
+    }
+    const { values, positionals } = parsed;
+    if (positionals.join(" ") !== "skills install") {
+        console.error(USAGE);
+        return 1;
+    }
+    // Source and compiled output sit at different depths, so the package is
+    // found by walking up rather than by counting.
+    const packageRoot = await findPackageRoot(path.dirname(fileURLToPath(import.meta.url)));
+    const source = path.join(packageRoot, "skills");
+    const destinations = values.dir ? [values.dir] : SKILL_DESTINATIONS;
+    const result = installSkills({
+        source,
+        destinations,
+        copy: values.copy,
+        cwd: process.cwd(),
+        log: (line) => console.error(line),
+    });
+    // An install with no skills in it is a packaging fault, not a user error,
+    // and saying where it looked is what makes that diagnosable.
+    if (result.names.length === 0) {
+        console.error(`loadbare-app: this install of @loadbare/app carries no skills (looked in ${source})`);
+        return 1;
+    }
+    console.error("");
+    if (result.copiedInstead) {
+        console.error("Some links could not be created and those skills were copied instead.");
+        console.error("A copy does not follow the package when it is upgraded — rerun this");
+        console.error("command after an upgrade, or use --copy everywhere and commit the result.");
+        console.error("");
+    }
+    if (values.copy) {
+        console.error("These are copies.  Commit them, and rerun this command after upgrading");
+        console.error("@loadbare/app so the skill matches the framework.");
+    }
+    else {
+        console.error("These are links into node_modules.  To keep them out of git:");
+        console.error("");
+        for (const destination of destinations) {
+            for (const name of result.names) {
+                console.error(`    ${path.join(destination, name)}`);
+            }
+        }
+    }
+    console.error("");
+    console.error("Start your agent from this directory and it will find them.");
+    return result.refused > 0 ? 1 : 0;
+}
+process.exitCode = await main();
+//# sourceMappingURL=skills-cli.js.map

package/dist/build/skills-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills-cli.js","sourceRoot":"","sources":["../../build/skills-cli.ts"],"names":[],"mappings":"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","sourcesContent":["#!/usr/bin/env node\n/**\n * loadbare-app — commands that are not the build.\n *\n *   loadbare-app skills install [--copy] [--dir <path>]\n *\n * Installs the agent skills that ship in this package into `.agents/skills`\n * and `.claude/skills`, or into `--dir` alone — see build/skills.ts.  Nothing\n * goes to stdout; every line is progress, on stderr.\n */\n\nimport { parseArgs } from \"node:util\";\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { findPackageRoot } from \"./package-root.js\";\nimport { installSkills, SKILL_DESTINATIONS } from \"./skills.js\";\n\nconst USAGE = \"usage: loadbare-app skills install [--copy] [--dir <path>]\";\n\nasync function main(): Promise<number> {\n  let parsed;\n  try {\n    parsed = parseArgs({\n      allowPositionals: true,\n      options: {\n        copy: { type: \"boolean\", default: false },\n        dir: { type: \"string\" },\n      },\n    });\n  } catch (err) {\n    console.error(`loadbare-app: ${(err as Error).message}`);\n    console.error(USAGE);\n    return 1;\n  }\n\n  const { values, positionals } = parsed;\n  if (positionals.join(\" \") !== \"skills install\") {\n    console.error(USAGE);\n    return 1;\n  }\n\n  // Source and compiled output sit at different depths, so the package is\n  // found by walking up rather than by counting.\n  const packageRoot = await findPackageRoot(\n    path.dirname(fileURLToPath(import.meta.url)),\n  );\n  const source = path.join(packageRoot, \"skills\");\n  const destinations = values.dir ? [values.dir] : SKILL_DESTINATIONS;\n\n  const result = installSkills({\n    source,\n    destinations,\n    copy: values.copy!,\n    cwd: process.cwd(),\n    log: (line) => console.error(line),\n  });\n\n  // An install with no skills in it is a packaging fault, not a user error,\n  // and saying where it looked is what makes that diagnosable.\n  if (result.names.length === 0) {\n    console.error(\n      `loadbare-app: this install of @loadbare/app carries no skills (looked in ${source})`,\n    );\n    return 1;\n  }\n\n  console.error(\"\");\n  if (result.copiedInstead) {\n    console.error(\n      \"Some links could not be created and those skills were copied instead.\",\n    );\n    console.error(\n      \"A copy does not follow the package when it is upgraded — rerun this\",\n    );\n    console.error(\n      \"command after an upgrade, or use --copy everywhere and commit the result.\",\n    );\n    console.error(\"\");\n  }\n\n  if (values.copy) {\n    console.error(\n      \"These are copies.  Commit them, and rerun this command after upgrading\",\n    );\n    console.error(\"@loadbare/app so the skill matches the framework.\");\n  } else {\n    console.error(\n      \"These are links into node_modules.  To keep them out of git:\",\n    );\n    console.error(\"\");\n    for (const destination of destinations) {\n      for (const name of result.names) {\n        console.error(`    ${path.join(destination, name)}`);\n      }\n    }\n  }\n\n  console.error(\"\");\n  console.error(\"Start your agent from this directory and it will find them.\");\n\n  return result.refused > 0 ? 1 : 0;\n}\n\nprocess.exitCode = await main();\n"]}

package/dist/build/skills.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Put the agent skills that ship in this package where a coding agent will
+ * find them.
+ *
+ * The same command as `loadbare-db skills install`, and deliberately a copy
+ * of it rather than a shared module: `@loadbare/db` shares no code with this
+ * package, and this package imports nothing from the repository.
+ *
+ * A symlink by default, because the point is that the skill tracks the
+ * dependency: `npm install @loadbare/app@next` and the skill moves with it.
+ * `copy` is for a team that would rather commit the text than have every
+ * clone depend on `node_modules` being populated.
+ *
+ * Nothing is done to `.gitignore`.  Whether these paths are committed is a
+ * decision about the project, and the command that installs a file is not the
+ * one to make it.
+ */
+/**
+ * Where a coding agent looks for skills.
+ *
+ * `.agents/skills` is the vendor-neutral location, read by Codex, Cursor and
+ * Copilot; `.claude/skills` is Claude Code's, and Cursor reads it too.  Both
+ * are written rather than guessing from what happens to be configured.
+ */
+export declare const SKILL_DESTINATIONS: string[];
+export interface InstallOptions {
+    /** The directory holding one subdirectory per skill. */
+    source: string;
+    /** The directories to install into. */
+    destinations: string[];
+    /** Copy rather than link. */
+    copy: boolean;
+    /** The project root; a link to a package inside it is relative. */
+    cwd: string;
+    /** Where progress goes, one line at a time. */
+    log: (line: string) => void;
+}
+export interface InstallResult {
+    names: string[];
+    refused: number;
+    /** A link was refused by the platform and a copy made in its place. */
+    copiedInstead: boolean;
+}
+/** The skills under `source`: each directory holding a `SKILL.md`. */
+export declare function shippedSkills(source: string): string[];
+export declare function installSkills(options: InstallOptions): InstallResult;
+//# sourceMappingURL=skills.d.ts.map

package/dist/build/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../../build/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAcH;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,UAAuC,CAAC;AAEvE,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6BAA6B;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,+CAA+C;IAC/C,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,aAAa,EAAE,OAAO,CAAC;CACxB;AAwCD,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAUtD;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAsDpE"}

package/dist/build/skills.js

@@ -0,0 +1,124 @@
+/**
+ * Put the agent skills that ship in this package where a coding agent will
+ * find them.
+ *
+ * The same command as `loadbare-db skills install`, and deliberately a copy
+ * of it rather than a shared module: `@loadbare/db` shares no code with this
+ * package, and this package imports nothing from the repository.
+ *
+ * A symlink by default, because the point is that the skill tracks the
+ * dependency: `npm install @loadbare/app@next` and the skill moves with it.
+ * `copy` is for a team that would rather commit the text than have every
+ * clone depend on `node_modules` being populated.
+ *
+ * Nothing is done to `.gitignore`.  Whether these paths are committed is a
+ * decision about the project, and the command that installs a file is not the
+ * one to make it.
+ */
+import { cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, symlinkSync, } from "node:fs";
+import path from "node:path";
+/**
+ * Where a coding agent looks for skills.
+ *
+ * `.agents/skills` is the vendor-neutral location, read by Codex, Cursor and
+ * Copilot; `.claude/skills` is Claude Code's, and Cursor reads it too.  Both
+ * are written rather than guessing from what happens to be configured.
+ */
+export const SKILL_DESTINATIONS = [".agents/skills", ".claude/skills"];
+/** `absent` covers a dangling symlink, which `existsSync` reports as missing. */
+function entryKind(p) {
+    let stat;
+    try {
+        stat = lstatSync(p);
+    }
+    catch {
+        return "absent";
+    }
+    if (stat.isSymbolicLink())
+        return "symlink";
+    if (stat.isDirectory())
+        return "directory";
+    return "other";
+}
+/** The `name:` a skill directory declares, or null if there is no skill there. */
+function declaredSkillName(dir) {
+    try {
+        const match = /^name:\s*(\S+)\s*$/m.exec(readFileSync(path.join(dir, "SKILL.md"), "utf-8"));
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A link into `node_modules` is relative, so the project stays movable and the
+ * link means the same thing to everyone who checks it out.  A globally
+ * installed package gets an absolute path, since a relative one breaks the
+ * moment the project moves.
+ */
+function linkTarget(from, to, cwd) {
+    const inside = path.resolve(from).startsWith(path.resolve(cwd) + path.sep);
+    return inside
+        ? path.relative(path.dirname(path.resolve(cwd, to)), path.resolve(from))
+        : path.resolve(from);
+}
+/** The skills under `source`: each directory holding a `SKILL.md`. */
+export function shippedSkills(source) {
+    if (!existsSync(source))
+        return [];
+    return readdirSync(source, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() &&
+        existsSync(path.join(source, entry.name, "SKILL.md")))
+        .map((entry) => entry.name)
+        .sort();
+}
+export function installSkills(options) {
+    const { source, destinations, copy, cwd, log } = options;
+    const names = shippedSkills(source);
+    let refused = 0;
+    let copiedInstead = false;
+    for (const destination of destinations) {
+        for (const name of names) {
+            const from = path.join(source, name);
+            const to = path.join(destination, name);
+            const at = path.resolve(cwd, to);
+            const kind = entryKind(at);
+            // A directory this command wrote says so on its own front matter, and
+            // is replaced.  Anything else at that path belongs to someone, and a
+            // skill install is not permitted to be the thing that lost it.
+            if (kind === "directory" && declaredSkillName(at) !== name) {
+                log(`  refused ${to} — a directory is already there and is not the ${name} skill`);
+                refused++;
+                continue;
+            }
+            if (kind === "other") {
+                log(`  refused ${to} — a file is already there`);
+                refused++;
+                continue;
+            }
+            mkdirSync(path.resolve(cwd, destination), { recursive: true });
+            rmSync(at, { recursive: true, force: true });
+            if (copy) {
+                cpSync(from, at, { recursive: true });
+                log(`  copied  ${to}`);
+                continue;
+            }
+            try {
+                symlinkSync(linkTarget(from, to, cwd), at, "dir");
+                log(`  linked  ${to}`);
+            }
+            catch (error) {
+                // Windows refuses a symlink to an unprivileged process unless
+                // developer mode is on.  A copy is the same skill, so the install
+                // succeeds and the difference is reported rather than raised.
+                if (error.code !== "EPERM")
+                    throw error;
+                cpSync(from, at, { recursive: true });
+                copiedInstead = true;
+                log(`  copied  ${to}`);
+            }
+        }
+    }
+    return { names, refused, copiedInstead };
+}
+//# sourceMappingURL=skills.js.map

package/dist/build/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../../build/skills.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Put the agent skills that ship in this package where a coding agent will\n * find them.\n *\n * The same command as `loadbare-db skills install`, and deliberately a copy\n * of it rather than a shared module: `@loadbare/db` shares no code with this\n * package, and this package imports nothing from the repository.\n *\n * A symlink by default, because the point is that the skill tracks the\n * dependency: `npm install @loadbare/app@next` and the skill moves with it.\n * `copy` is for a team that would rather commit the text than have every\n * clone depend on `node_modules` being populated.\n *\n * Nothing is done to `.gitignore`.  Whether these paths are committed is a\n * decision about the project, and the command that installs a file is not the\n * one to make it.\n */\n\nimport {\n  cpSync,\n  existsSync,\n  lstatSync,\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  rmSync,\n  symlinkSync,\n} from \"node:fs\";\nimport path from \"node:path\";\n\n/**\n * Where a coding agent looks for skills.\n *\n * `.agents/skills` is the vendor-neutral location, read by Codex, Cursor and\n * Copilot; `.claude/skills` is Claude Code's, and Cursor reads it too.  Both\n * are written rather than guessing from what happens to be configured.\n */\nexport const SKILL_DESTINATIONS = [\".agents/skills\", \".claude/skills\"];\n\nexport interface InstallOptions {\n  /** The directory holding one subdirectory per skill. */\n  source: string;\n  /** The directories to install into. */\n  destinations: string[];\n  /** Copy rather than link. */\n  copy: boolean;\n  /** The project root; a link to a package inside it is relative. */\n  cwd: string;\n  /** Where progress goes, one line at a time. */\n  log: (line: string) => void;\n}\n\nexport interface InstallResult {\n  names: string[];\n  refused: number;\n  /** A link was refused by the platform and a copy made in its place. */\n  copiedInstead: boolean;\n}\n\n/** `absent` covers a dangling symlink, which `existsSync` reports as missing. */\nfunction entryKind(p: string): \"absent\" | \"symlink\" | \"directory\" | \"other\" {\n  let stat;\n  try {\n    stat = lstatSync(p);\n  } catch {\n    return \"absent\";\n  }\n  if (stat.isSymbolicLink()) return \"symlink\";\n  if (stat.isDirectory()) return \"directory\";\n  return \"other\";\n}\n\n/** The `name:` a skill directory declares, or null if there is no skill there. */\nfunction declaredSkillName(dir: string): string | null {\n  try {\n    const match = /^name:\\s*(\\S+)\\s*$/m.exec(\n      readFileSync(path.join(dir, \"SKILL.md\"), \"utf-8\"),\n    );\n    return match?.[1] ?? null;\n  } catch {\n    return null;\n  }\n}\n\n/**\n * A link into `node_modules` is relative, so the project stays movable and the\n * link means the same thing to everyone who checks it out.  A globally\n * installed package gets an absolute path, since a relative one breaks the\n * moment the project moves.\n */\nfunction linkTarget(from: string, to: string, cwd: string): string {\n  const inside = path.resolve(from).startsWith(path.resolve(cwd) + path.sep);\n  return inside\n    ? path.relative(path.dirname(path.resolve(cwd, to)), path.resolve(from))\n    : path.resolve(from);\n}\n\n/** The skills under `source`: each directory holding a `SKILL.md`. */\nexport function shippedSkills(source: string): string[] {\n  if (!existsSync(source)) return [];\n  return readdirSync(source, { withFileTypes: true })\n    .filter(\n      (entry) =>\n        entry.isDirectory() &&\n        existsSync(path.join(source, entry.name, \"SKILL.md\")),\n    )\n    .map((entry) => entry.name)\n    .sort();\n}\n\nexport function installSkills(options: InstallOptions): InstallResult {\n  const { source, destinations, copy, cwd, log } = options;\n  const names = shippedSkills(source);\n  let refused = 0;\n  let copiedInstead = false;\n\n  for (const destination of destinations) {\n    for (const name of names) {\n      const from = path.join(source, name);\n      const to = path.join(destination, name);\n      const at = path.resolve(cwd, to);\n      const kind = entryKind(at);\n\n      // A directory this command wrote says so on its own front matter, and\n      // is replaced.  Anything else at that path belongs to someone, and a\n      // skill install is not permitted to be the thing that lost it.\n      if (kind === \"directory\" && declaredSkillName(at) !== name) {\n        log(\n          `  refused ${to} — a directory is already there and is not the ${name} skill`,\n        );\n        refused++;\n        continue;\n      }\n      if (kind === \"other\") {\n        log(`  refused ${to} — a file is already there`);\n        refused++;\n        continue;\n      }\n\n      mkdirSync(path.resolve(cwd, destination), { recursive: true });\n      rmSync(at, { recursive: true, force: true });\n\n      if (copy) {\n        cpSync(from, at, { recursive: true });\n        log(`  copied  ${to}`);\n        continue;\n      }\n\n      try {\n        symlinkSync(linkTarget(from, to, cwd), at, \"dir\");\n        log(`  linked  ${to}`);\n      } catch (error) {\n        // Windows refuses a symlink to an unprivileged process unless\n        // developer mode is on.  A copy is the same skill, so the install\n        // succeeds and the difference is reported rather than raised.\n        if ((error as NodeJS.ErrnoException).code !== \"EPERM\") throw error;\n        cpSync(from, at, { recursive: true });\n        copiedInstead = true;\n        log(`  copied  ${to}`);\n      }\n    }\n  }\n\n  return { names, refused, copiedInstead };\n}\n"]}

package/docs/reference/widgets.md

@@ -19,8 +19,8 @@ npm install @loadbare/widgets
 export default ["@loadbare/widgets"];
 ```
 
-See [Using Widget Libraries](../tutorials/090-using-widget-libraries.md) for
-what listing a package does, and [The Builder](./builder.md#where-the-builder-looks)
+See [Widgets from packages](./builder.md#widgets-from-packages) for what
+listing a package does, and [The Builder](./builder.md#where-the-builder-looks)
 for where a listed package sits in the cascade.
 
 ## `lb-input`

package/package.json

@@ -1,18 +1,21 @@
 {
   "name": "@loadbare/app",
   "description": "High performance web app framework for server-bound applications",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "type": "module",
   "files": [
     "dist",
     "docs",
+    "skills/loadbare-app/SKILL.md",
+    "skills/loadbare-app/references",
     "README.md"
   ],
   "publishConfig": {
     "access": "public"
   },
   "bin": {
-    "loadbare-app-build": "dist/build/cli.js"
+    "loadbare-app-build": "dist/build/cli.js",
+    "loadbare-app": "dist/build/skills-cli.js"
   },
   "exports": {
     ".": "./dist/hub/lb-hub.browser.js",
@@ -31,8 +34,9 @@
     "release:major": "node ../../scripts/bump-release.mjs major",
     "prebuild": "node --eval \"fs.rmSync('dist',{recursive:true,force:true})\" --input-type=module",
     "build:server": "tsc --project tsconfig.build.json",
-    "build": "npm run build:server",
-    "postbuild": "node --eval \"fs.chmodSync('dist/build/cli.js', 0o755)\" --input-type=module && node ../../scripts/check-dist-imports.mjs",
+    "build:skills": "node scripts/build-skills.mjs",
+    "build": "npm run build:server && npm run build:skills",
+    "postbuild": "node --eval \"for (const f of ['dist/build/cli.js','dist/build/skills-cli.js']) fs.chmodSync(f, 0o755)\" --input-type=module && node ../../scripts/check-dist-imports.mjs",
     "test": "tsx --test \"tests/**/*.test.ts\"",
     "typecheck": "tsc --noEmit",
     "format": "prettier --write .",

package/skills/loadbare-app/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: loadbare-app
+description: Build server-bound web applications with Loadbare/app. Covers the file conventions the builder finds by name (`chrome.html`, `*.page.html`, `*.queries.ts`, `*.requests.ts`, `imports.ts`, `<tag>.html`, `<tag>.browser.ts`); the `lb-*` attribute vocabulary that binds HTML to server data and sends requests (`lb-list`, `lb-row`, `lb-cell`, `lb-key`, `lb-show`, `lb-action`); build-time widget expansion with `exp-*` parameters, `lb-slot` and `lb-template`; custom element code; the Express wiring with `hubRoutes`; and the `@loadbare/widgets` library. Use whenever a task involves `@loadbare/app`, `@loadbare/widgets`, `loadbare-app-build`, an `lb-` attribute, or a page, query, request or widget file in a Loadbare application. The model is not React, htmx or REST, and cannot be inferred from them.
+license: Apache-2.0
+metadata:
+  package: "@loadbare/app"
+  homepage: https://gitlab.com/kendowns/loadbare
+---
+
+# Working with Loadbare/app
+
+Loadbare/app builds a whole application into one HTML document, one client
+script and one stylesheet.  The server answers named queries with rows and
+performs named requests; the browser lands those rows on elements that name
+them.  No component renders anything, and no page fetches anything.
+
+The wire is relational.  A name answers with one row or a set of rows, a
+row holds cells, and a cell holds one value.  Hold on to that: most wrong
+designs come from sending a shape a relational answer cannot have.
+
+## Build every change before handing it over
+
+`loadbare-app-build` is the checker.  It expands every page and widget and
+refuses what it cannot ship, naming the tag and the file:
+
+```bash
+loadbare-app-build --src src --out dist
+```
+
+It exits non-zero on the first failure and prints
+`loadbare-app-build: <message>`.  A clean run prints the files it wrote and
+the number of custom elements it bundled.
+
+Type-check the server side as well:
+
+```bash
+tsc --noEmit
+```
+
+`dist/pages.ts` imports page files with their `.ts` extensions, so the
+application's `tsconfig.json` needs `allowImportingTsExtensions`.
+
+**Write, build, fix, repeat until it is clean.**  Then start the server:
+`createHub` refuses a query that answers with the wrong shape and a page
+that declares a reserved name, and those refusals only appear at run time.
+Restart the server after adding or changing a `.queries.ts` or
+`.requests.ts` file.
+
+## The shape of an application
+
+The builder classifies files by name, never by directory:
+
+```
+src/
+  chrome.html              exactly one; the document every page lands in
+  imports.ts               at most one; the widget packages to scan
+  00-reset.css             any .css anywhere, concatenated
+  pages/
+    index.page.html        the page for /
+    members.page.html      the page for /members
+    members.queries.ts     what members displays
+    members.requests.ts    what members may be asked to do
+  widgets/
+    note-card.html         the markup <note-card> expands into
+    visit-count.browser.ts the class <visit-count> registers
+server.ts
+```
+
+The chrome carries `<lb-hub>` inside `<body>`, an empty `<main>` inside the
+hub, and `<script src="/client.js" defer>`.  Everything a user touches sits
+inside `<lb-hub>`.
+
+A page is an HTML fragment that lands in `<main>`:
+
+```html
+<!-- src/pages/members.page.html -->
+<p lb-row="dues">Collected this year: <span lb-cell="total"></span></p>
+
+<section lb-list="roster">
+  <form lb-action="lb-row-insert">
+    <input lb-cell="name" />
+    <button type="submit">Add</button>
+  </form>
+  <ul>
+    <template lb-key="id">
+      <li>
+        <span lb-cell="name"></span>
+        <button lb-action="lb-row-delete">Remove</button>
+      </li>
+    </template>
+  </ul>
+</section>
+```
+
+```ts
+// src/pages/members.queries.ts
+import { list, row, type Queries } from "@loadbare/app/server";
+
+export const queries: Queries = {
+  dues: row((ctx) => ctx.db.duesTotal()),
+  roster: list((ctx) => ctx.db.members()),
+};
+```
+
+```ts
+// src/pages/members.requests.ts
+import { patch, type Requests } from "@loadbare/app/server";
+
+export const requests: Requests = {
+  crud: {
+    roster: {
+      rowInsert: {
+        run: async (ctx, { values }) => ({
+          roster: patch({ rows: [await ctx.db.addMember(values)] }),
+        }),
+        refresh: ["dues"],
+      },
+      rowDelete: {
+        run: async (ctx, { key }) => {
+          await ctx.db.removeMember(key);
+          return { roster: patch({ drop: [key] }) };
+        },
+        refresh: ["dues"],
+      },
+    },
+  },
+};
+```
+
+## Where front-end knowledge misleads
+
+Re-read this list when a build fails or a design will not fit.  Each item is
+a place a reasonable instinct from React, Vue, htmx or REST produces an
+error or a dead end.
+
+**There is no template language.**  No `{#if}`, no `v-for`, no `map()`.  A
+list is an element carrying `lb-list` with a `<template lb-key="...">`
+inside it, and the hub clones the template once per row.  A condition is
+`lb-show="<column>"`: write every possibility into the page and let a column
+decide which is present.  The column must be a boolean or null; the string
+`"false"` counts as present.
+
+**`{{placeholder}}` is build time only.**  It reads an `exp-` attribute on
+the tag, never data.  Write it as an entire attribute value or an entire
+text node.  Name parameters in lowercase with hyphens: HTML lowercases
+`exp-inputClass` before expansion sees it.
+
+**Scope comes from ancestry, not props.**  An `lb-cell` binds to the row on
+its nearest ancestor carrying `lb-row` or a live list row.  An element
+outside every scope displays nothing.  A value of `lb-cell` is a column name.
+
+**One name, one cardinality.**  Declare every query with `row()` or
+`list()`.  A page that needs the same data as a row and as a set declares
+two queries.
+
+**A cell never holds rows.**  Master-detail is a row and a list under two
+names.  Many masters with their details is one list of joined rows, grouped
+for display by a widget's `lbPlaceRow`.  A list nested inside another list's
+rows receives the same rows in every outer row; use it for a picker, never
+for per-row detail.
+
+**A URL names a page, never a resource.**  Do not design `/accounts/42`.  A
+row is addressed by `list` and `key`, taken from where the element sits.
+Queries take no arguments from the browser; which record a page shows is
+server state reached through `ctx`.
+
+**There are no endpoints to write.**  `hubRoutes(hub, contextFor)` is the
+whole data channel.  Declare every action under `actions` and every
+permitted operation under `crud`; anything undeclared is refused.
+
+**All three CRUD operations are list operations.**  Each needs a key, and a
+key exists only on a live row inside `lb-list`.  An `lb-row` scope is
+read-only; give a writable single row a list that answers with one row.
+
+**Write `rowUpdate` as a partial update.**  A form sends every cell it
+holds; a widget carrying `lb-cell` and `lb-action="lb-row-update"` sends its
+one cell.  Set the columns `values` names, leave the rest alone, and check
+the names against the columns the page may edit.
+
+**Put `lb-row-insert` and `lb-row-update` on a `<form>` or a button.**  The
+hub gathers the nearest `<form>`, `<tr>` or live row.  Cells in a bare
+`<div>` belong to no row and the request is refused.  A native `<input>`
+carrying `lb-row-update` is refused; commit one cell with a widget such as
+`<lb-input>`.  Inside a form, leave `lb-action` off the widgets.
+
+**Return a patch when the change has a known extent.**  `patch({ rows })`
+for rows added or edited, `patch({ drop })` for keys removed, with
+`refresh: []`.  List a query in `refresh` only when its membership or order
+changed in a way the operation cannot name.
+
+**Format values in the query.**  The hub does no type conversion.  What a
+number, date or null looks like is decided on the server.
+
+**Checkboxes, radio buttons and file inputs are not bound.**  They receive
+no value and are not gathered.  This is an open item, not a mistake in the
+page.
+
+**`lb-` belongs to Loadbare.**  Invent no `lb-` attribute, and name no
+query or action with the prefix.  Import attribute names in widget code from
+`@loadbare/app/constants`; never write them as string literals.
+
+**Name a widget script `<tag>.browser.ts`.**  A plain `<tag>.ts` stays on
+the server and the tag goes unregistered.
+
+**Light DOM, global CSS.**  No shadow root, no scoping.  Style empty lists
+with `[lb-row-count="0"]`, pending requests with `[lb-pending]`, and failed
+ones with `[lb-error]`.
+
+**Host at the origin root.**  The hub reaches its route by absolute path, so
+a subpath such as `example.com/myapp/` does not work.
+
+## Widgets
+
+A widget is `<tag>.html`, `<tag>.browser.ts`, or both, and a tag with
+neither is a build error.  The HTML is expanded at build time into the tag's
+children; the class is an ordinary custom element with no base class.
+
+Reach for a widget only when plain HTML cannot do the job.  A list, a form
+and a condition need none.  A widget exists to wrap a control that decides
+its own moment to send (`<lb-input>` on `change`), or to place and scaffold
+rows (`lbPlaceRow`, `lbRowsLanded`).
+
+Before writing one, check `@loadbare/widgets`: `lb-input`, `lb-select`,
+`lb-options`, `lb-table`, `lb-picker`, `lb-unknown-page`.  Install it and
+list it in `src/imports.ts`:
+
+```ts
+export default ["@loadbare/widgets"];
+```
+
+The application's own definition of a tag overrides a package's.
+
+## Reference material
+
+Read these when the summary above does not settle the question.  They ship
+with the package, so no network is needed.
+
+- [`references/overview.md`](references/overview.md) — the map of the
+  reference, by part of the application.
+- [`references/data-binding.md`](references/data-binding.md) — every `lb-`
+  attribute, requests, forms, conditions and request state.  Start here for
+  anything in a page.
+- [`references/page-files.md`](references/page-files.md) — queries,
+  `onPageEnter`, actions, CRUD, refresh and patch.
+- [`references/custom-elements.md`](references/custom-elements.md) —
+  expansion, parameters, slots, destinations, and widget code.
+- [`references/chrome.md`](references/chrome.md) — the chrome,
+  navigation and `lb-navigation`.
+- [`references/server.md`](references/server.md) — the Express server and
+  the request context.
+- [`references/builder.md`](references/builder.md) — the builder's options,
+  what it reads, and where it looks.
+- [`references/css.md`](references/css.md) — how stylesheets are ordered.
+- [`references/widgets.md`](references/widgets.md) — the basic widget
+  library.
+- [`references/TECHREF-1.0.md`](references/TECHREF-1.0.md) — the reserved
+  names, and the open items that block 1.0.  Read it before designing around
+  something the other references do not mention.