create-objectstack 17.2.0 → 17.4.0

package/CHANGELOG.md

@@ -1,5 +1,195 @@
 # create-objectstack
 
+## 17.4.0
+
+### Minor Changes
+
+- 4998efa: Scaffolded projects now ship a CI workflow, and a `lint` script for it to run.
+  The blank template carries `.github/workflows/ci.yml` — one job, on `push` and
+  `pull_request`: checkout, pnpm, Node 22, `pnpm install --frozen-lockfile`, then
+  `pnpm validate`, `pnpm lint` and `pnpm typecheck`.
+  
+  `lint` is new to the template (`objectstack lint`). It is not a second spelling
+  of `validate`: the two share the authoring-rule engine but only `lint` runs the
+  hook-body lowering check, which catches handlers that have silently stopped
+  lowering to metadata-only bodies — a change of deployment shape produced by a
+  refactor that looks like tidying.
+  
+  The scaffolder already created `.github/` at runtime for a single file
+  (`copilot-instructions.md`) while the template's gates shipped as npm scripts
+  nothing ever ran, so a fresh project started with no CI at all — and ObjectStack
+  metadata mistakes fail silently at runtime, which makes `objectstack validate`
+  the only place they surface early. That gate is now unskippable for a human and
+  for an AI agent authoring metadata in the project, instead of advisory.
+  
+  Existing projects are unaffected; copy the file from a fresh scaffold to adopt
+  it.
+- 813d6c5: `npx create-objectstack` now declares the same TypeScript range as `os init` and
+  `os create`, and the value is generated rather than restated.
+  
+  Three scaffolders write a new project's `package.json`, and the range that
+  decides whether that project type-checks at all had split: `os init` and
+  `os create` emitted `typescript: ^5.3.0` from a shared emission policy, while
+  this package's bundled template carried `^6.0.0`. Two projects created the same
+  day got different TypeScript **majors** depending on which documented entry
+  point the reader followed.
+  
+  - **What changed for a scaffolded project.** Its declared `typescript`
+    devDependency floor moves from `^6.0.0` to `^5.3.0`. Both resolve to the same
+    installed compiler on a fresh install; what moves is the floor the project
+    **declares**, and a floor is a support promise. `^5.3.0` is the promise the
+    docs already make — "ObjectStack works with TypeScript 5.3+" on the getting
+    started page, "TypeScript 5.3.0 or later" in the deployment troubleshooting
+    page — and it is measured rather than assumed: TypeScript 5.3.3 type-checks
+    every shape these scaffolders emit with results identical to 6.0.3. The repo's
+    own `typescript@^6.0.3` devDependency is deliberately not this value; the same
+    doc sentence states both halves ("…but the project itself is built and tested
+    against TypeScript 6.x"). `engines.pnpm` was already in agreement and is now
+    held there by the same mechanism.
+  - **Why the value is generated.** This package cannot import from
+    `@objectstack/cli`: the dependency edge runs the other way, and the `npx`
+    package must not pull the CLI's package closure. So the values are stamped
+    into the bundled template at build time by
+    `scripts/sync-scaffold-emission-policy.mjs`, read out of the same
+    `SCAFFOLD_*` constants the other two scaffolders import, and
+    `pnpm check:scaffold-emission-policy` reddens the moment the inlined values
+    disagree with that source. Editing the two into agreement by hand would have
+    left them free to diverge again on the next move, silently, for the same
+    structural reason — which is how they diverged the first time.
+- fd75728: Scaffolded projects now install the AI skills bundle for **one** agent runtime
+  instead of every runtime the skills CLI knows, so the bundle is committed once.
+  
+  **Route B of the two the card offered was taken**, and the choice was measured
+  rather than argued. Against `skills@1.5.23` and the 11-skill catalog, the old
+  `--all` (shorthand for `--skill '*' --agent '*' -y`) wrote the same bundle to
+  three destinations — `.agents/` (46 real files, 604,102 B), `agent/` (46 real
+  files, 602,682 B, identical bodies with re-serialised frontmatter) and
+  `.claude/` (11 symlinks into `.agents/`). The template's `.gitignore` excluded
+  none of it, so a new project's first `git add -A` staged 22 `SKILL.md` paths
+  plus 11 symlinks. That reached the initial commit of a real app before anyone
+  noticed.
+  
+  The scaffolder now runs
+  `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y`,
+  which writes 46 real files to `.claude/skills/` and nothing else: 11 staged
+  `SKILL.md` paths, no symlinks, and a clone of that commit has readable skill
+  files on every platform.
+  
+  Route A (keep `--all`, exclude the duplicates in the template `_gitignore`) was
+  built and cloned, not reasoned about, and both of its shapes were rejected.
+  Ignoring `.agents/` and `agent/` while committing `.claude/` gives a fresh
+  cloner 11 dangling symlinks and zero readable `SKILL.md`. Ignoring only
+  `agent/` works on POSIX but commits 11 symlinks that a `core.symlinks=false`
+  clone — git-for-Windows' default — materialises as ordinary files whose whole
+  content is the link target. `--all --copy`, the other way to make `.claude/`
+  real, fans out to 56 destination directories totalling 33.8 MB. A denylist is
+  also the wrong shape regardless of which paths it names: this package does not
+  choose the destination set, the skills CLI does, and it moves with that
+  package's releases.
+  
+  The cost is the multi-runtime default, and it is paid in the open: the closing
+  summary now always prints an **AI Skills** block naming where the bundle landed
+  and the one-line command for any other runtime, one agent at a time. The
+  bundle is identical whichever agent is named.
+  
+  Existing projects are unaffected. To shrink one that already carries the
+  triplicate, delete `.agents/` and `agent/` and re-run the single-agent command
+  above; `skills-lock.json` records source and hash, not paths, so it does not
+  change.
+
+## 17.3.0
+
+### Minor Changes
+
+- 366f895: feat(auth): migrate `@better-auth/scim` from `1.7.0-rc.1` to stable `1.7.1` — the whole-model SCIM migration (#3653, epic #11632)
+  
+  The stable line is the rc.2-lineage rewrite: the rc.1 `scimProvider` model,
+  `/scim/generate-token` endpoint and `storeSCIMToken` option no longer exist,
+  replaced by seven new models and a three-way connection contract. This lands
+  the migration atomically:
+  
+  - **Seven new platform objects** back the stable models —
+    `sys_scim_connection_binding`, `sys_scim_group`, `sys_scim_group_member`,
+    `sys_scim_identity_tombstone`, `sys_scim_projection_grant`,
+    `sys_scim_subject`, `sys_scim_user` — bridged via `AUTH_MODEL_TO_PROTOCOL`,
+    registered in the platform-object-names registry, listed in
+    `BETTER_AUTH_MANAGED_OBJECTS`, and column-pinned by the parity gate (whose
+    `KNOWN_UNMAPPED_MODELS` shrinks to the empty set: the rc.1-era group
+    provisioning gap — IdP `/Groups` pushes hitting tables that did not exist —
+    is closed).
+  - **SCIM connections stay runtime data.** The stable constructor is satisfied
+    with an application-owned `authentication.verifyBearerToken` that resolves
+    the connection from a row at request time — not static boot config, and not
+    the upstream `managedConnections` catalog (deliberately not adopted).
+  - **ObjectStack owns SCIM credentials outright** (stable upstream stores no
+    credential at all): `sys_scim_connection_credential` plus
+    `scim-connection-service.ts` mint/digest/verify. At rest only an
+    HMAC-SHA-256 keyed by the deployment auth secret (base64url,
+    domain-separated) is stored — at parity or better than the rc.1 unsalted
+    SHA-256 — pinned by `credential-at-rest-posture.test.ts` including live
+    401 paths for forged, revoked and expired bearers.
+  - **The ObjectQL better-auth adapter gains native transactions**
+    (`engine.transaction`, fail-closed on drivers without `beginTransaction`),
+    which stable scim requires by assertion for atomic provisioning writes.
+  - **Scaffold suppression retired**: the `@better-auth/scim>better-call`
+    `allowedVersions` entry (CLI renderer + blank template) is gone — stable
+    1.7.1 peers `better-call@1.4.0` exactly — and its presence ratchets flipped
+    to absence pins. The `better-auth>better-sqlite3` and four
+    `@better-auth/utils` entries stay; their retirement conditions are separate
+    and unmet.
+  - The pin resolves **1.7.1 exactly** (not `^1.7.1`): 1.7.2 peers
+    `better-auth`/`@better-auth/core` at `^1.7.2`, which only the workspace
+    overrides' silencing would "satisfy" while the family is 1.7.1. Floating is
+    its own follow-up.
+  
+  **Semver: minor, argued.** The rc.1 SCIM surface this replaces (generate-token
+  endpoint, rc.1 bearer tokens, `sys_scim_provider` rows) changes incompatibly —
+  but that surface is default-off (`OS_SCIM_ENABLED`), was shipped with a
+  documented "do not let the IdP push groups" boundary, and the maintainer ruled
+  (2026-08-25) that SCIM has no real customers and old data need not carry: the
+  one binding constraint is that an existing system upgrades smoothly, which it
+  does — every table the installed library can write exists at this version, and
+  SCIM-disabled deployments see no behavior change. A major would move the whole
+  fixed version group for a feature surface with zero consumers. Deployments
+  that had SCIM enabled must mint new connection credentials (digests are not
+  portable from rc.1 on any path — IdP token reissue is a migration-day
+  operator action regardless of semver level). `sys_scim_provider` itself is
+  NOT removed here; its retirement is tracked separately (#11757).
+
+### Patch Changes
+
+- c6c7fec: fix(create-objectstack): stop reporting a failed pnpm probe as a deliberate npm choice (#11616)
+  
+  `detectPackageManager()` was `try { execSync('pnpm --version') } catch { return
+  'npm' }`, so every failure mode collapsed into one answer. `npm install` in the
+  scaffolder's output meant either *this machine has no pnpm* or *the probe
+  threw*, and nothing — no log line, no message — could tell the two apart.
+  
+  That second case is reachable on an ordinary developer machine, not just in
+  theory: `pnpm --version` resolves through Corepack and therefore depends on the
+  directory it runs in. Measured on one machine, one binary, two directories —
+  `10.31.0` inside a repo that pins `packageManager`, `10.33.0` outside it, where
+  Corepack has to resolve, and may have to fetch, a version nothing pinned. A
+  user who has pnpm installed but is on a slow or offline network was silently
+  told to run npm.
+  
+  The probe now reports why as well as what:
+  
+  - `probe: 'ok'` — pnpm answered, so pnpm is used (unchanged, silent).
+  - `probe: 'absent'` — no pnpm on PATH at all, so npm is a real choice
+    (unchanged, silent).
+  - `probe: 'failed'` — pnpm **is** on PATH and the probe still threw. npm is
+    used exactly as before, and the run now says so, naming the underlying
+    failure: `pnpm is installed but \`pnpm --version\` failed (<reason>); using
+    npm as a fallback.`
+  
+  **Which package manager a run uses is unchanged in all three cases** — it is
+  still pnpm if and only if the probe succeeded. The PATH lookup that separates
+  `absent` from `failed` runs only after the decision is already made and feeds
+  the message alone, so a miss there can change a warning's wording and never the
+  tool's behaviour. The only output that moves is one warning in a case that was
+  previously silent and wrong.
+
 ## 17.2.0
 
 ### Minor Changes

package/README.md

@@ -56,9 +56,12 @@ you so rather than failing as an unknown template.
    every object name in the template is re-prefixed to match
    (`blank_note` → `my_app_note`).
 2. Installs dependencies (pnpm if available, otherwise npm).
-3. Installs the ObjectStack AI skills bundle for coding agents
-   (`npx skills add objectstack-ai/objectstack/skills --all` — scoped to the
-   curated `skills/` catalog).
+3. Installs the ObjectStack AI skills bundle for **one** coding agent —
+   `npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y`,
+   scoped to the curated `skills/` catalog. One agent, not `--all`, so the
+   bundle lands in exactly one directory (`.claude/skills/`) and a scaffolded
+   project commits it once; `src/skills-install.ts` carries the measurement.
+   The closing summary prints the same command for any other runtime.
 4. Writes `AGENTS.md` and `.github/copilot-instructions.md` with the project
    conventions — unless the template ships its own.
 

package/dist/index.js

@@ -6,9 +6,57 @@ import {
 // src/index.ts
 import { Command } from "commander";
 import chalk2 from "chalk";
-import fs4 from "fs";
-import path4 from "path";
+import fs5 from "fs";
+import path5 from "path";
+import { execSync as execSync2 } from "child_process";
+
+// src/detect-package-manager.ts
+import fs from "fs";
+import path from "path";
 import { execSync } from "child_process";
+function resolveOnPath(cmd, env = process.env) {
+  const raw = env.PATH ?? "";
+  if (!raw) return null;
+  const exts = process.platform === "win32" ? (env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean) : [""];
+  for (const dir of raw.split(path.delimiter)) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = path.join(dir, cmd + ext);
+      try {
+        if (fs.statSync(candidate).isFile()) return candidate;
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+function probeFailureDetail(err) {
+  const e = err ?? {};
+  if (e.signal) return `killed by ${e.signal}`;
+  const stderr = e.stderr == null ? "" : String(e.stderr);
+  const firstLine = stderr.split("\n").map((l) => l.trim()).find((l) => l.length > 0);
+  if (firstLine) return firstLine.length > 200 ? `${firstLine.slice(0, 197)}...` : firstLine;
+  if (typeof e.code === "string") return e.code;
+  if (typeof e.status === "number") return `exited ${e.status}`;
+  const msg = (e.message ?? "").split("\n")[0]?.trim();
+  return msg || "unknown error";
+}
+function defaultProbe() {
+  execSync("pnpm --version", { stdio: ["ignore", "ignore", "pipe"] });
+}
+function detectPackageManager(deps = {}) {
+  const probe = deps.probe ?? defaultProbe;
+  const pnpmOnPath = deps.pnpmOnPath ?? (() => resolveOnPath("pnpm") !== null);
+  try {
+    probe();
+    return { pm: "pnpm", probe: "ok" };
+  } catch (err) {
+    if (!pnpmOnPath()) return { pm: "npm", probe: "absent" };
+    return { pm: "npm", probe: "failed", detail: probeFailureDetail(err) };
+  }
+}
+
+// src/index.ts
 import { fileURLToPath } from "url";
 
 // src/pkg-utils.ts
@@ -25,41 +73,41 @@ function syncObjectStackDeps(pkg, version) {
 }
 
 // src/template-copy.ts
-import fs from "fs";
-import path from "path";
+import fs2 from "fs";
+import path2 from "path";
 var TEMPLATE_FILE_ALIASES = /* @__PURE__ */ new Map([
   ["_gitignore", ".gitignore"]
 ]);
 function copyDir(src, dest, collected, rel = "") {
-  fs.mkdirSync(dest, { recursive: true });
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const srcPath = path.join(src, entry.name);
+  fs2.mkdirSync(dest, { recursive: true });
+  for (const entry of fs2.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path2.join(src, entry.name);
     const outName = entry.isFile() ? TEMPLATE_FILE_ALIASES.get(entry.name) ?? entry.name : entry.name;
-    const destPath = path.join(dest, outName);
+    const destPath = path2.join(dest, outName);
     const relPath = rel ? `${rel}/${outName}` : outName;
     if (entry.isDirectory()) {
       copyDir(srcPath, destPath, collected, relPath);
     } else if (entry.isFile()) {
-      fs.copyFileSync(srcPath, destPath);
+      fs2.copyFileSync(srcPath, destPath);
       collected.push(relPath);
     }
   }
 }
 
 // src/rewrite-identity.ts
-import fs2 from "fs";
-import path2 from "path";
+import fs3 from "fs";
+import path3 from "path";
 var CONFIG_NAMESPACE_RE = /\bnamespace:\s*(['"`])([a-z0-9_]+)\1/i;
 function readTemplateNamespace(targetDir) {
-  const configPath = path2.join(targetDir, "objectstack.config.ts");
-  if (fs2.existsSync(configPath)) {
-    const m = CONFIG_NAMESPACE_RE.exec(fs2.readFileSync(configPath, "utf8"));
+  const configPath = path3.join(targetDir, "objectstack.config.ts");
+  if (fs3.existsSync(configPath)) {
+    const m = CONFIG_NAMESPACE_RE.exec(fs3.readFileSync(configPath, "utf8"));
     if (m) return m[2];
   }
-  const manifestPath = path2.join(targetDir, "objectstack.manifest.json");
-  if (fs2.existsSync(manifestPath)) {
+  const manifestPath = path3.join(targetDir, "objectstack.manifest.json");
+  if (fs3.existsSync(manifestPath)) {
     try {
-      const m = JSON.parse(fs2.readFileSync(manifestPath, "utf8"));
+      const m = JSON.parse(fs3.readFileSync(manifestPath, "utf8"));
       if (typeof m.namespace === "string" && m.namespace) return m.namespace;
     } catch {
     }
@@ -67,9 +115,9 @@ function readTemplateNamespace(targetDir) {
   return void 0;
 }
 function tsFiles(dir, out = []) {
-  if (!fs2.existsSync(dir)) return out;
-  for (const entry of fs2.readdirSync(dir, { withFileTypes: true })) {
-    const full = path2.join(dir, entry.name);
+  if (!fs3.existsSync(dir)) return out;
+  for (const entry of fs3.readdirSync(dir, { withFileTypes: true })) {
+    const full = path3.join(dir, entry.name);
     if (entry.isDirectory()) {
       if (entry.name === "node_modules") continue;
       tsFiles(full, out);
@@ -83,7 +131,7 @@ var namePrefixRe = (ns, flags) => new RegExp(`(\\bname:\\s*)(['"\`])${ns}_([a-z0
 function rewriteObjectNamePrefix(dir, from, to) {
   let rewritten = 0;
   for (const file of tsFiles(dir)) {
-    const before = fs2.readFileSync(file, "utf8");
+    const before = fs3.readFileSync(file, "utf8");
     const after = before.replace(
       namePrefixRe(from, "g"),
       (_m, prefix, q, rest) => {
@@ -91,7 +139,7 @@ function rewriteObjectNamePrefix(dir, from, to) {
         return `${prefix}${q}${to}_${rest}${q}`;
       }
     );
-    if (after !== before) fs2.writeFileSync(file, after);
+    if (after !== before) fs3.writeFileSync(file, after);
   }
   return rewritten;
 }
@@ -99,11 +147,11 @@ function findStaleNamespacePrefixes(dir, oldNs) {
   const re = namePrefixRe(oldNs, "");
   const stale = [];
   for (const file of tsFiles(dir)) {
-    const lines = fs2.readFileSync(file, "utf8").split("\n");
+    const lines = fs3.readFileSync(file, "utf8").split("\n");
     for (let i = 0; i < lines.length; i++) {
       if (re.test(lines[i])) {
         stale.push({
-          file: path2.relative(dir, file),
+          file: path3.relative(dir, file),
           line: i + 1,
           text: lines[i].trim()
         });
@@ -138,13 +186,13 @@ function templateNames() {
 }
 
 // src/runtime-image.ts
-import fs3 from "fs";
-import path3 from "path";
+import fs4 from "fs";
+import path4 from "path";
 var RUNTIME_FROM_RE = /^FROM ghcr\.io\/objectstack-ai\/objectstack:([A-Za-z0-9_][A-Za-z0-9_.+-]*)[ \t]*$/;
 var PINNABLE_VERSION_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
 var PROSE_COMMENT_RE = /^#[ \t]+\S/;
 function readResolvedCliVersion(targetDir) {
-  const pkgPath = path3.join(
+  const pkgPath = path4.join(
     targetDir,
     "node_modules",
     "@objectstack",
@@ -152,7 +200,7 @@ function readResolvedCliVersion(targetDir) {
     "package.json"
   );
   try {
-    const version = JSON.parse(fs3.readFileSync(pkgPath, "utf8")).version;
+    const version = JSON.parse(fs4.readFileSync(pkgPath, "utf8")).version;
     return typeof version === "string" && PINNABLE_VERSION_RE.test(version) ? version : void 0;
   } catch {
     return void 0;
@@ -170,10 +218,10 @@ function pinRuntimeImage(targetDir, version) {
   if (!PINNABLE_VERSION_RE.test(version)) {
     return { pinned: false, reason: `'${version}' is not a pinnable version` };
   }
-  const dockerfile = path3.join(targetDir, "Dockerfile");
+  const dockerfile = path4.join(targetDir, "Dockerfile");
   let text;
   try {
-    text = fs3.readFileSync(dockerfile, "utf8");
+    text = fs4.readFileSync(dockerfile, "utf8");
   } catch {
     return { pinned: false, reason: "no Dockerfile in the scaffolded project" };
   }
@@ -193,10 +241,23 @@ function pinRuntimeImage(targetDir, version) {
   if (!check || check[1] !== version) {
     return { pinned: false, reason: "rewrite did not produce the pinned tag" };
   }
-  fs3.writeFileSync(dockerfile, pinnedText);
+  fs4.writeFileSync(dockerfile, pinnedText);
   return { pinned: true, tag: version };
 }
 
+// src/skills-install.ts
+var SKILLS_CATALOG = "objectstack-ai/objectstack/skills";
+var DEFAULT_SKILLS_AGENT = "claude-code";
+var DEFAULT_SKILLS_DIR = ".claude/skills/";
+var EXAMPLE_OTHER_AGENT = "codex";
+function skillsAddArgs(agent) {
+  return `skills add ${SKILLS_CATALOG} --skill '*' --agent ${agent} -y`;
+}
+var SKILLS_INSTALL_COMMAND = `npx -y ${skillsAddArgs(DEFAULT_SKILLS_AGENT)}`;
+function skillsInstallHint(agent) {
+  return `npx ${skillsAddArgs(agent)}`;
+}
+
 // src/banner.ts
 import chalk from "chalk";
 var PREFIX = "   \u25C6 Create ObjectStack ";
@@ -219,8 +280,8 @@ function renderVersionBanner(version) {
 
 // src/index.ts
 var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path4.dirname(__filename2);
-var BUNDLED_TEMPLATES_DIR = path4.resolve(__dirname2, "templates");
+var __dirname2 = path5.dirname(__filename2);
+var BUNDLED_TEMPLATES_DIR = path5.resolve(__dirname2, "templates");
 function toTitleCase(str) {
   return str.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
@@ -237,8 +298,8 @@ function sanitizeNamespace(name) {
 }
 function readCliVersion() {
   try {
-    const pkgPath = path4.resolve(__dirname2, "..", "package.json");
-    const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf8"));
+    const pkgPath = path5.resolve(__dirname2, "..", "package.json");
+    const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf8"));
     return String(pkg.version || "0.0.0");
   } catch {
     return "0.0.0";
@@ -264,17 +325,9 @@ function printStep(msg) {
 function printWarning(msg) {
   console.log(chalk2.yellow(`  \u26A0 ${msg}`));
 }
-function detectPackageManager() {
-  try {
-    execSync("pnpm --version", { stdio: "ignore" });
-    return "pnpm";
-  } catch {
-    return "npm";
-  }
-}
 function loadBundled(templateDir, targetDir) {
-  const src = path4.join(BUNDLED_TEMPLATES_DIR, templateDir);
-  if (!fs4.existsSync(src)) {
+  const src = path5.join(BUNDLED_TEMPLATES_DIR, templateDir);
+  if (!fs5.existsSync(src)) {
     throw new Error(`Bundled template missing on disk: ${src}`);
   }
   const collected = [];
@@ -284,39 +337,39 @@ function loadBundled(templateDir, targetDir) {
 function rewriteProjectIdentity(targetDir, projectName, namespace) {
   const title = toTitleCase(projectName);
   const templateNamespace = readTemplateNamespace(targetDir);
-  const pkgPath = path4.join(targetDir, "package.json");
-  if (fs4.existsSync(pkgPath)) {
+  const pkgPath = path5.join(targetDir, "package.json");
+  if (fs5.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf8"));
+      const pkg = JSON.parse(fs5.readFileSync(pkgPath, "utf8"));
       pkg.name = projectName;
       syncObjectStackDeps(pkg, readCliVersion());
-      fs4.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+      fs5.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
     } catch {
     }
   }
-  const manifestPath = path4.join(targetDir, "objectstack.manifest.json");
-  if (fs4.existsSync(manifestPath)) {
+  const manifestPath = path5.join(targetDir, "objectstack.manifest.json");
+  if (fs5.existsSync(manifestPath)) {
     try {
-      const m = JSON.parse(fs4.readFileSync(manifestPath, "utf8"));
+      const m = JSON.parse(fs5.readFileSync(manifestPath, "utf8"));
       m.name = projectName;
       m.displayName = title;
       if ("namespace" in m) m.namespace = namespace;
       delete m.description;
-      fs4.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
+      fs5.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
     } catch {
     }
   }
-  const configPath = path4.join(targetDir, "objectstack.config.ts");
-  if (fs4.existsSync(configPath)) {
-    let cfg = fs4.readFileSync(configPath, "utf8");
+  const configPath = path5.join(targetDir, "objectstack.config.ts");
+  if (fs5.existsSync(configPath)) {
+    let cfg = fs5.readFileSync(configPath, "utf8");
     cfg = cfg.replace(/(\bid:\s*)(['"`])[^'"`]*\2/, `$1$2${projectName}$2`);
     cfg = cfg.replace(/(\bnamespace:\s*)(['"`])[^'"`]*\2/, `$1$2${namespace}$2`);
     cfg = cfg.replace(/(\bname:\s*)(['"`])[^'"`]*\2/, `$1$2${title}$2`);
     cfg = cfg.replace(/^[ \t]*description:\s*(['"`])[^'"`]*\1,?\r?\n/m, "");
-    fs4.writeFileSync(configPath, cfg);
+    fs5.writeFileSync(configPath, cfg);
   }
   if (templateNamespace && namespace !== templateNamespace) {
-    const srcDir = path4.join(targetDir, "src");
+    const srcDir = path5.join(targetDir, "src");
     rewriteObjectNamePrefix(srcDir, templateNamespace, namespace);
     const stale = findStaleNamespacePrefixes(srcDir, templateNamespace);
     if (stale.length > 0) {
@@ -330,32 +383,32 @@ The generated project would fail 'objectstack build' on the \${namespace}_\${sho
       );
     }
   }
-  const readmePath = path4.join(targetDir, "README.md");
-  if (fs4.existsSync(readmePath)) {
-    let md = fs4.readFileSync(readmePath, "utf8");
+  const readmePath = path5.join(targetDir, "README.md");
+  if (fs5.existsSync(readmePath)) {
+    let md = fs5.readFileSync(readmePath, "utf8");
     md = md.replace(/^#\s+.*$/m, `# ${title}`);
-    fs4.writeFileSync(readmePath, md);
+    fs5.writeFileSync(readmePath, md);
   }
   writeAgentGuides(targetDir, title, projectName);
 }
 function writeAgentGuides(targetDir, title, projectName) {
-  const templatePath = path4.join(BUNDLED_TEMPLATES_DIR, "AGENTS.md");
+  const templatePath = path5.join(BUNDLED_TEMPLATES_DIR, "AGENTS.md");
   let template;
   try {
-    template = fs4.readFileSync(templatePath, "utf8");
+    template = fs5.readFileSync(templatePath, "utf8");
   } catch (err) {
     if (err?.code === "ENOENT") return;
     throw err;
   }
   const rendered = template.replace(/\{\{PROJECT_TITLE\}\}/g, title).replace(/\{\{PROJECT_NAME\}\}/g, projectName);
-  writeIfAbsent(path4.join(targetDir, "AGENTS.md"), rendered);
-  const copilotPath = path4.join(targetDir, ".github", "copilot-instructions.md");
-  fs4.mkdirSync(path4.dirname(copilotPath), { recursive: true });
+  writeIfAbsent(path5.join(targetDir, "AGENTS.md"), rendered);
+  const copilotPath = path5.join(targetDir, ".github", "copilot-instructions.md");
+  fs5.mkdirSync(path5.dirname(copilotPath), { recursive: true });
   writeIfAbsent(copilotPath, rendered);
 }
 function topLevelNames(dir) {
   try {
-    return new Set(fs4.readdirSync(dir));
+    return new Set(fs5.readdirSync(dir));
   } catch {
     return /* @__PURE__ */ new Set();
   }
@@ -398,7 +451,7 @@ function printCreatedSummary(targetDir, opts) {
 }
 function writeIfAbsent(filePath, contents) {
   try {
-    fs4.writeFileSync(filePath, contents, { flag: "wx" });
+    fs5.writeFileSync(filePath, contents, { flag: "wx" });
   } catch (err) {
     if (err?.code !== "EEXIST") throw err;
   }
@@ -428,18 +481,25 @@ var program = new Command().name("create-objectstack").description("Create a new
   }
   const template = lookup.template;
   const cwd = process.cwd();
-  const projectName = name || path4.basename(cwd);
+  const projectName = name || path5.basename(cwd);
   const namespace = sanitizeNamespace(projectName);
-  const targetDir = name ? path4.resolve(cwd, name) : cwd;
+  const targetDir = name ? path5.resolve(cwd, name) : cwd;
   const isCurrentDir = targetDir === cwd;
-  const pm = detectPackageManager();
+  const detected = detectPackageManager();
+  const pm = detected.pm;
+  if (detected.probe === "failed") {
+    printWarning(
+      `pnpm is installed but \`pnpm --version\` failed (${detected.detail}); using npm as a fallback. The commands below name npm because the probe did not answer, not because this project prefers it.`
+    );
+    console.log("");
+  }
   printKV("Environment", projectName);
   printKV("Namespace", namespace);
   printKV("Template", `${options.template} \u2014 ${template.description}`);
   printKV("Directory", targetDir);
   console.log("");
-  if (!isCurrentDir && fs4.existsSync(targetDir)) {
-    const existing = fs4.readdirSync(targetDir);
+  if (!isCurrentDir && fs5.existsSync(targetDir)) {
+    const existing = fs5.readdirSync(targetDir);
     if (existing.length > 0) {
       printError(`Directory already exists and is not empty: ${targetDir}`);
       process.exit(1);
@@ -447,7 +507,7 @@ var program = new Command().name("create-objectstack").description("Create a new
   }
   const targetWasEmpty = topLevelNames(targetDir).size === 0;
   try {
-    fs4.mkdirSync(targetDir, { recursive: true });
+    fs5.mkdirSync(targetDir, { recursive: true });
     const createdFiles = loadBundled(template.source.dir, targetDir);
     rewriteProjectIdentity(targetDir, projectName, namespace);
     printSuccess(`Template files written (${createdFiles.length})`);
@@ -456,7 +516,7 @@ var program = new Command().name("create-objectstack").description("Create a new
       printStep("Installing dependencies...");
       let installed = false;
       try {
-        execSync(`${pm} install`, { stdio: "inherit", cwd: targetDir });
+        execSync2(`${pm} install`, { stdio: "inherit", cwd: targetDir });
         installed = true;
         console.log("");
       } catch {
@@ -479,17 +539,20 @@ var program = new Command().name("create-objectstack").description("Create a new
       }
     }
     const beforeSkills = topLevelNames(targetDir);
+    let skillsInstalled = false;
     if (!options.skipInstall && !options.skipSkills) {
       printStep("Installing AI skills for your coding agent...");
       try {
-        execSync("npx -y skills add objectstack-ai/objectstack/skills --all", {
+        execSync2(SKILLS_INSTALL_COMMAND, {
           stdio: "inherit",
           cwd: targetDir
         });
+        skillsInstalled = true;
         console.log("");
       } catch {
         printWarning(
-          "Skills installation skipped. Run manually:\n    npx skills add objectstack-ai/objectstack/skills"
+          `Skills installation skipped. Run manually:
+    ${skillsInstallHint(DEFAULT_SKILLS_AGENT)}`
         );
         console.log("");
       }
@@ -513,10 +576,23 @@ var program = new Command().name("create-objectstack").description("Create a new
     console.log(chalk2.dim(`    ${devLabel.padEnd(labelWidth)}# Start development server`));
     console.log(chalk2.dim(`    ${validateLabel.padEnd(labelWidth)}# Verify metadata: schema + predicates + bindings`));
     console.log(chalk2.dim(`    ${" ".repeat(labelWidth)}# (run after every metadata edit \u2014 see AGENTS.md)`));
-    if (options.skipInstall || options.skipSkills) {
-      console.log("");
+    console.log("");
+    if (skillsInstalled) {
+      console.log(chalk2.bold("  AI Skills:"));
+      console.log(
+        chalk2.dim(
+          `    Installed for ${DEFAULT_SKILLS_AGENT} \u2192 ${DEFAULT_SKILLS_DIR} \u2014 commit it with your project.`
+        )
+      );
+      console.log(chalk2.dim("    Using a different agent? Add it one runtime at a time:"));
+      console.log(chalk2.dim(`      ${skillsInstallHint(EXAMPLE_OTHER_AGENT)}`));
+      console.log(chalk2.dim("      (`npx skills add --help` lists every agent name)"));
+    } else {
       console.log(chalk2.bold("  AI Skills (recommended):"));
-      console.log(chalk2.dim("    npx skills add objectstack-ai/objectstack/skills"));
+      console.log(chalk2.dim(`    ${skillsInstallHint(DEFAULT_SKILLS_AGENT)}`));
+      console.log(
+        chalk2.dim(`    Replace \`${DEFAULT_SKILLS_AGENT}\` with your own agent runtime if it differs.`)
+      );
     }
     console.log("");
   } catch (error) {

package/dist/templates/AGENTS.md

@@ -73,13 +73,19 @@ Run `npm run build` when you need the compiled `dist/objectstack.json` artifact.
 
 ## AI Skills
 
-This project uses ObjectStack skills from `objectstack-ai/objectstack`.
-Install or update skills with the standard [skills CLI](https://skills.sh/):
+This project uses ObjectStack skills from `objectstack-ai/objectstack`. They
+were installed for one agent runtime, live in `.claude/skills/`, and are
+committed with the project. Install or update them with the standard
+[skills CLI](https://skills.sh/), naming your runtime:
 
 ```bash
-npx skills add objectstack-ai/objectstack/skills
+npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
 ```
 
+Adding a second runtime? Re-run it with that runtime's `--agent` name.
+⛔ Do not use `--all`: it writes the same bundle to `.agents/`, `agent/` and
+`.claude/` at once, and all three then land in your next commit.
+
 Skills are triggered automatically based on task context:
 
 | Skill | Trigger Context |

package/dist/templates/blank/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+# Continuous integration for this ObjectStack app.
+#
+# ObjectStack metadata fails SILENTLY at runtime, not at edit time: a mistyped
+# permission grant or a bare field name in an action predicate raises nothing,
+# it just behaves wrongly for whoever hits it first. `objectstack validate` is
+# where that class surfaces — and running it is something a human, or an AI
+# agent authoring metadata in this project, has to remember. This workflow is
+# what makes it unskippable. AGENTS.md carries the authoring conventions it
+# enforces.
+#
+# One job, one file: a starting point, not a CI framework. Grow it with the
+# project — add a step when you add a script, a second job when you deploy.
+
+name: CI
+
+on: [push, pull_request]
+
+# Read-only. Nothing here writes to the repository or publishes anything.
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Validate
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v7
+
+      # pnpm BEFORE setup-node, deliberately. `cache: pnpm` below makes
+      # setup-node shell out to pnpm to locate the store, so pnpm has to be on
+      # PATH by then. Reversed, this does not degrade — the job dies in the
+      # setup step with "Unable to locate executable file: pnpm".
+      #
+      # `version` is explicit because this project declares no `packageManager`
+      # field — pinning one would make the project pnpm-only, and a
+      # corepack-driven npm or yarn then refuses to run in it — so
+      # pnpm/action-setup has nothing to resolve from. Keep this in step with
+      # the `engines.pnpm` floor in package.json.
+      - uses: pnpm/action-setup@v6
+        with:
+          version: 10
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '22'
+          cache: pnpm
+
+      # `--frozen-lockfile` installs exactly what the lockfile records and fails
+      # when the two disagree, so `pnpm-lock.yaml` has to be committed.
+      # Scaffolding wrote it for you unless you passed `--skip-install`; in that
+      # case run `pnpm install` once and commit the result.
+      - run: pnpm install --frozen-lockfile
+
+      # The gate this file exists for: schema, CEL predicates and widget
+      # bindings. The same checks `pnpm build` runs, without producing an
+      # artifact.
+      - run: pnpm validate
+
+      # Not a second spelling of `validate`. The two share the authoring-rule
+      # engine but not the rule set — the hook-body lowering check, which
+      # catches handlers that silently stop lowering to metadata-only bodies
+      # (a change of deployment shape, from a refactor that looks like
+      # tidying), runs here and nowhere else.
+      - run: pnpm lint
+
+      - run: pnpm typecheck

package/dist/templates/blank/README.md

@@ -100,6 +100,8 @@ After editing any metadata, run:
 
 ```bash
 pnpm validate     # schema + CEL predicates + widget bindings (no artifact)
+pnpm lint         # authoring rules validate does not run — e.g. a handler that
+                  # stopped lowering to a metadata-only body
 pnpm typecheck    # TypeScript types against @objectstack/spec
 ```
 
@@ -138,5 +140,10 @@ covered in [Self-Hosted Deployment](https://objectstack.ai/docs/deployment/self-
 - Add a flow or automation: see `objectstack-automation`.
 - Add an AI agent: see `objectstack-ai`.
 
-Skills are installed with `npx skills add objectstack-ai/objectstack/skills`
-(see `AGENTS.md`) and also show up in the in-IDE assistant catalog.
+Skills live in `.claude/skills/` and are committed with this project, once.
+They are installed one agent runtime at a time (see `AGENTS.md`), and also show
+up in the in-IDE assistant catalog:
+
+```bash
+npx skills add objectstack-ai/objectstack/skills --skill '*' --agent claude-code -y
+```

package/dist/templates/blank/package.json

@@ -11,6 +11,7 @@
     "start": "objectstack start",
     "build": "objectstack build",
     "validate": "objectstack validate",
+    "lint": "objectstack lint",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -23,6 +24,6 @@
   },
   "devDependencies": {
     "@objectstack/cli": "^17.0.0",
-    "typescript": "^6.0.0"
+    "typescript": "^5.3.0"
   }
 }

package/dist/templates/blank/pnpm-workspace.yaml

@@ -44,12 +44,9 @@ allowBuilds:
 #   sign-in and adapter find/update/delete — 1.7.1 behaves identically on
 #   better-sqlite3 13.0.3 and on 12.11.1. The upstream range is stale.
 #
-#   @better-auth/scim (held at a release candidate deliberately, not by
-#   neglect) peers better-call at an exact 1.3.7, while better-auth itself
-#   depends on 1.4.0. A better-auth plugin has to share the host's better-call
-#   instance, so the single 1.4.0 copy is the correct resolution rather than a
-#   skew to repair. This entry retires when SCIM moves off the rc: stable
-#   @better-auth/scim 1.7.1 already peers better-call 1.4.0.
+#   (The '@better-auth/scim>better-call' entry that used to sit here retired
+#   with the scim release-candidate pin — stable @better-auth/scim 1.7.1 peers
+#   better-call 1.4.0 exactly, so the skew it declared away is gone.)
 #
 #   @better-auth/core, @better-auth/oauth-provider, @better-auth/scim and
 #   @better-auth/sso each peer an exact @better-auth/utils 0.4.2, while the
@@ -75,7 +72,6 @@ allowBuilds:
 peerDependencyRules:
   allowedVersions:
     'better-auth>better-sqlite3': '13'
-    '@better-auth/scim>better-call': '1.4.0'
     '@better-auth/core>@better-auth/utils': '0.5.0'
     '@better-auth/oauth-provider>@better-auth/utils': '0.5.0'
     '@better-auth/scim>@better-auth/utils': '0.5.0'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-objectstack",
-  "version": "17.2.0",
+  "version": "17.4.0",
   "description": "Create a new ObjectStack project — npx create-objectstack",
   "bin": {
     "create-objectstack": "./bin/create-objectstack.js"
@@ -28,7 +28,8 @@
     "@types/node": "^26.2.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.10"
+    "vitest": "^4.1.10",
+    "yaml": "^2.9.0"
   },
   "repository": {
     "type": "git",
@@ -49,7 +50,7 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "node ../../scripts/sync-scaffold-emission-policy.mjs && tsup && node ../../scripts/check-dts-emitted.mjs",
     "typecheck": "tsc --noEmit",
     "dev": "tsup --watch",
     "test": "vitest run"