@hydranium/cli 1.0.0-next.31 → 1.0.0-next.312

package/src/commands/init-templates.ts

@@ -22,6 +22,9 @@
  *   `bin` key, the DI module filename, and the data-server port command.
  * - `__CONFIG_ROOT_CONST__` — SCREAMING_SNAKE project id, naming the
  *   `lsp.configurationRoot` constant a multi-grammar project binds.
+ * - `__PROTOCOL_PACKAGE__` — the protocol member's package name, scope
+ *   included, which the server and every client import ids and wire types
+ *   from.
  *
  * GRAMMAR tokens, substituted once per grammar:
  *
@@ -29,6 +32,8 @@
  *   Drives the PER-LANGUAGE generated symbols (`<grammar>GeneratedModule`,
  *   `<grammar>LanguageMetaData`).
  * - `__GRAMMAR_ID__` — kebab grammar id: the `.langium` filename.
+ * - `__GRAMMAR_ID_CONST__` — SCREAMING_SNAKE grammar id, prefixing the
+ *   diagram's type-id constants.
  * - `__LANGUAGE_ID__` — kebab routing key: the `langium-config` entry id and
  *   its TextMate output.
  * - `__EXTENSION__` — the grammar's FIRST file extension, without the dot.
@@ -49,10 +54,19 @@
  * generator emits `interface <projectName>Element` as the base type every rule
  * extends, which a rule of that name would collide with.
  *
- * Kept as in-source strings (not on-disk assets) so no build-time copy step
- * is needed and the substitution is unit-testable. The `.ts` / `.langium` / JSON
- * templates are derived from the in-repo reference example so the generated project
- * compiles against the real `@hydranium/*` API once `langium generate` has run.
+ * The project is two packages and a starter workspace, each in its own
+ * directory: `server/` (the grammar, the language and its heads), `protocol/`
+ * (what the server and its clients both import, so a client never installs
+ * Langium), and `workspace/` (starter model files every host and the CLI
+ * open). A standalone project adds a root manifest naming them as npm
+ * workspaces; a workspace member joins the surrounding root instead.
+ *
+ * A file that is fixed text with tokens lives in the `templates/` tree the
+ * package ships beside `lib`, at the path it is emitted at, tokens included
+ * (each ignore file without its dot); one computed from the composition is
+ * built here. The tree is read synchronously, so `runInit` stays synchronous,
+ * and it is neither formatted with the repo's settings nor given a license
+ * header, since either would change what `init` emits.
  *
  * Two conventions the templates follow deliberately:
  *
@@ -72,8 +86,9 @@
  *   over; the adopter's own formatter settles it.
  */
 
+import { readFileSync } from 'node:fs';
 import { readCliVersion } from '../cli-version.js';
-import type { InitComposition, InitFile, InitGrammarNames, InitHead } from './init.js';
+import type { InitComposition, InitFile, InitGrammarNames, InitHead, InitMember } from './init.js';
 import type { JsonValue } from './init-workspace.js';
 
 /** One template file: its path (tokens allowed) and its content (tokens allowed). */
@@ -82,16 +97,6 @@ export interface InitTemplate {
    content: string;
 }
 
-/**
- * The version every framework package carries before the first release.
- *
- * A scaffold made by a CLI still at this version pins a range the registry
- * cannot serve, so the emitted README keeps its yalc note and `init` keeps its
- * install warning while — and only while — it holds: from a published CLI the
- * derived pins resolve and either note would be false as printed.
- */
-export const UNPUBLISHED_FRAMEWORK_VERSION = '0.0.0';
-
 /**
  * The version `init` pins every `@hydranium/*` dependency at: the scaffolding
  * CLI's own.
@@ -122,12 +127,49 @@ function screamingSnake(projectId: string): string {
    return projectId.replace(/-/g, '_').toUpperCase();
 }
 
+/**
+ * A member's package name: `<id>-<member>`, under the scope when there is one.
+ *
+ * Suffixed even for the server, because a project of several packages has no
+ * member entitled to the bare id, and a later client or host would otherwise
+ * read as a part of the server.
+ */
+export function memberPackageName(composition: InitComposition, member: InitMember): string {
+   const { scope } = composition.packaging;
+   const name = `${composition.projectId}-${member}`;
+   return scope === undefined ? name : `${scope}/${name}`;
+}
+
+/**
+ * The composition as one member sees it: inside a workspace, its placement
+ * sits one directory below the project's, so its `extends` and its lint
+ * config path reach one level further up.
+ */
+function forMember(composition: InitComposition, member: InitMember): InitComposition {
+   const workspace = composition.packaging.workspace;
+   if (workspace === undefined) {
+      return composition;
+   }
+   return {
+      ...composition,
+      packaging: {
+         ...composition.packaging,
+         workspace: {
+            ...workspace,
+            targetPath: `${workspace.targetPath}/${member}`,
+            baseTsconfig: workspace.baseTsconfig === undefined ? undefined : `../${workspace.baseTsconfig}`
+         }
+      }
+   };
+}
+
 /** Substitute the project-tier tokens. */
 function project(text: string, composition: InitComposition): string {
    return text
       .replace(/__NAME__/g, composition.name)
       .replace(/__PROJECT_ID__/g, composition.projectId)
-      .replace(/__CONFIG_ROOT_CONST__/g, screamingSnake(composition.projectId));
+      .replace(/__CONFIG_ROOT_CONST__/g, screamingSnake(composition.projectId))
+      .replace(/__PROTOCOL_PACKAGE__/g, memberPackageName(composition, 'protocol'));
 }
 
 /**
@@ -140,6 +182,7 @@ function project(text: string, composition: InitComposition): string {
  */
 function grammarTier(text: string, grammar: InitGrammarNames): string {
    return text
+      .replace(/__GRAMMAR_ID_CONST__/g, screamingSnake(grammar.grammarId))
       .replace(/__GRAMMAR_ID__/g, grammar.grammarId)
       .replace(/__GRAMMAR__/g, grammar.grammar)
       .replace(/__LANGUAGE_ID__/g, grammar.languageId)
@@ -153,6 +196,30 @@ function render(text: string, composition: InitComposition, grammar: InitGrammar
    return grammarTier(project(text, composition), grammar);
 }
 
+/** The template tree, the same two levels up from `src/commands` and `lib/commands`. */
+const TEMPLATES = new URL('../../templates/', import.meta.url);
+
+/** One template file's text. */
+function template(path: string): string {
+   return readFileSync(new URL(path, TEMPLATES), 'utf-8');
+}
+
+/** A template emitted once per project at its own path, rendered with the project tokens. */
+function projectTemplate(path: string, composition: InitComposition): InitFile {
+   return { path, content: project(template(path), composition) };
+}
+
+/** A template emitted once per grammar, its path rendered like its content. */
+function grammarTemplate(path: string, composition: InitComposition, grammar: InitGrammarNames): InitFile {
+   return { path: render(path, composition, grammar), content: render(template(path), composition, grammar) };
+}
+
+/** An ignore file, stored without its dot because `npm pack` drops a nested `.gitignore` and applies it as an ignore file. */
+function ignoreFile(directory: string): InitFile {
+   const prefix = directory === '' ? '' : `${directory}/`;
+   return { path: `${prefix}.gitignore`, content: template(`${prefix}gitignore`) };
+}
+
 /** A comma-separated list of single-quoted TypeScript/JS string literals. */
 function quotedList(values: readonly string[]): string {
    return values.map(value => `'${value}'`).join(', ');
@@ -177,7 +244,7 @@ function columnsFor(composition: InitComposition): number {
 
 /**
  * A named import on one line while it fits the column budget, else one symbol
- * per line. Emitted files are supposed to pass a prettier check as-is, and the
+ * per line. Emitted files are supposed to pass a format check as-is, and the
  * generated-module import grows by one symbol per grammar.
  */
 function importList(symbols: readonly string[], from: string, columns: number, typeOnly = false): string {
@@ -198,9 +265,13 @@ function arrayLiteral(elements: readonly string[], indent: string, columns: numb
  * The FRAMEWORK packages each head adds, carrying no version: every
  * `@hydranium/*` pin is derived at scaffold time from {@link frameworkPin}, so
  * none of them can name a version its siblings were not published at.
+ *
+ * `base` is every head set's: the services every head serves from are composed
+ * the same with or without an LSP head.
  */
-const HEAD_FRAMEWORK_DEPENDENCIES: Record<InitHead, readonly string[]> = {
-   lsp: ['@hydranium/core', '@hydranium/langium', '@hydranium/protocol'],
+const HEAD_FRAMEWORK_DEPENDENCIES: Record<InitHead | 'base', readonly string[]> = {
+   base: ['@hydranium/core', '@hydranium/langium', '@hydranium/protocol'],
+   lsp: [],
    data: ['@hydranium/data-server'],
    glsp: ['@hydranium/glsp-server']
 };
@@ -221,15 +292,22 @@ const HEAD_FRAMEWORK_DEPENDENCIES: Record<InitHead, readonly string[]> = {
  * `overrides` block exists to prevent — so a repo gate holds each entry here
  * against the manifest that declares it.
  *
- * `langium` is required by `lsp` even though hand-written code goes through the
+ * `langium` is required even though hand-written code goes through the
  * `@hydranium/langium` chokepoint, because `langium-cli` emits direct imports
- * into the generated files and regenerates them on every build.
+ * into the generated files and regenerates them on every build. The `vscode-*`
+ * packages are required peers of `@hydranium/core`, so they are `base` too.
  */
-const HEAD_THIRD_PARTY_DEPENDENCIES: Record<InitHead, Readonly<Record<string, string>>> = {
-   lsp: {
+const HEAD_THIRD_PARTY_DEPENDENCIES: Record<InitHead | 'base', Readonly<Record<string, string>>> = {
+   base: {
       langium: '4.3.1',
-      'vscode-languageserver': '~10.0.1'
+      // Exact, as are the protocol and transport it pins, so Langium and the
+      // framework share their copies; across copies, an error a handler throws
+      // or returns loses its code, and a later patch can pin another protocol.
+      'vscode-languageserver': '10.0.1',
+      'vscode-jsonrpc': '9.0.0',
+      'vscode-languageserver-protocol': '3.18.1'
    },
+   lsp: {},
    data: {},
    glsp: {
       '@eclipse-glsp/graph': '2.7.0',
@@ -241,26 +319,86 @@ const HEAD_THIRD_PARTY_DEPENDENCIES: Record<InitHead, Readonly<Record<string, st
    }
 };
 
-/** The dependency block for a head set, merged and sorted as npm writes it. */
+/**
+ * What each head adds to the protocol member, which carries only what a
+ * client may install. Keyed by head because the `glsp` head implies a diagram,
+ * whose element ids extend GLSP's default type names.
+ */
+const PROTOCOL_THIRD_PARTY_DEPENDENCIES: Record<InitHead, Readonly<Record<string, string>>> = {
+   lsp: {},
+   data: {},
+   glsp: { '@eclipse-glsp/protocol': '2.7.0' }
+};
+
+/**
+ * The exact pins of `heads`, for a workspace root to declare too. npm installs a
+ * root's own dependencies at the top of the tree, so another member's version of
+ * one nests beneath that member instead of taking the place of the copy this
+ * package shares with the framework.
+ */
+export function workspaceRootPins(heads: readonly InitHead[]): ReadonlyArray<readonly [string, string]> {
+   return [
+      ...Object.entries(HEAD_THIRD_PARTY_DEPENDENCIES.base),
+      ...heads.flatMap(head => [
+         ...Object.entries(HEAD_THIRD_PARTY_DEPENDENCIES[head]),
+         ...Object.entries(PROTOCOL_THIRD_PARTY_DEPENDENCIES[head])
+      ])
+   ]
+      .filter(([, version]) => /^\d+\.\d+\.\d+$/.test(version))
+      .sort(([left], [right]) => left.localeCompare(right));
+}
+
+/** Whether an npm version is 11.6.0 or later, the first that installs `vitest` 4.1's peer set; `11.6.0-rc.1` is earlier. */
+function installsVitest41(npmVersion: string | undefined): boolean {
+   const [release, prerelease] = (npmVersion ?? '0.0.0').split('-', 2);
+   const [major, minor, patch] = release.split('.').map(Number);
+   return major > 11 || (major === 11 && (minor > 6 || (minor === 6 && (patch > 0 || prerelease === undefined))));
+}
+
+/**
+ * Whether the scaffold holds `vitest` below 4.1, whose peer set crashes npm
+ * before 11.6 (every npm a Node 22 release bundles) on the first install. Only a
+ * workspace root declaring a newer npm lifts it, and only when `init` runs under
+ * an npm known to be newer: npm does not enforce `packageManager`.
+ */
+function pinsVitest(composition: InitComposition): boolean {
+   const workspace = composition.packaging.workspace;
+   return !(installsVitest41(workspace?.packageManagerNpm) && installsVitest41(workspace?.npmVersion));
+}
+
+/**
+ * The version a member pins a sibling member at: exact, at the version every
+ * member starts with. npm links a sibling only when the range admits its local
+ * version, and otherwise looks for it in the registry, where it was never
+ * published.
+ */
+const MEMBER_PIN = '0.0.0';
+
+/** A dependency block, sorted as npm writes it. */
+function sortedBlock(dependencies: Readonly<Record<string, string>>, indent: string): string {
+   return Object.keys(dependencies)
+      .sort()
+      .map(name => `${indent}"${name}": "${dependencies[name]}"`)
+      .join(',\n');
+}
+
+/** The server's dependency block: the base and head set's packages and the protocol member. */
 function dependencyBlock(composition: InitComposition, indent: string): string {
-   const merged: Record<string, string> = {};
-   for (const head of composition.heads) {
+   const merged: Record<string, string> = { [memberPackageName(composition, 'protocol')]: MEMBER_PIN };
+   for (const head of ['base', ...composition.heads] as const) {
       Object.assign(merged, HEAD_THIRD_PARTY_DEPENDENCIES[head]);
       for (const framework of HEAD_FRAMEWORK_DEPENDENCIES[head]) {
          merged[framework] = frameworkPin(composition);
       }
    }
-   return Object.keys(merged)
-      .sort()
-      .map(name => `${indent}"${name}": "${merged[name]}"`)
-      .join(',\n');
+   return sortedBlock(merged, indent);
 }
 
 // JSON at two-space indent, not the three the `.ts` templates use: that is the
 // npm convention, and `npm install` rewrites `package.json` at two spaces
 // regardless — so three would not survive the adopter's first install.
 //
-// The KEY ORDER is `prettier-plugin-packagejson`'s canonical one, `private`
+// The KEY ORDER is the one Oxfmt's `sortPackageJson` canonicalises to, `private`
 // before `license` included. Any other order is rewritten by the scaffolded
 // project's own first `format` run — a diff on a file the adopter never touched
 // — and it makes a byte-compare against a formatted copy of this emission
@@ -280,6 +418,11 @@ function dependencyBlock(composition: InitComposition, indent: string): string {
 // from this package's own grammar and can reach a consumer from nowhere else; a
 // listed path that does not exist yet is inert.
 //
+// `exports` puts `createServices`, the one module reading the real filesystem,
+// behind `./node`, so the root loads in a browser worker that has no `node:fs`.
+// `./lib/*` and `./package.json` stay reachable for a host that resolves
+// `<server>/lib/main.js` to spawn the server.
+//
 // `repository` is deliberately NOT emitted while `author` is emitted empty. An
 // empty `author` is the form `npm init` itself writes and asserts nothing, but
 // `repository` is CONSUMED — the registry page, `npm repo` and publish
@@ -291,16 +434,9 @@ const PACKAGE_JSON = `{
   "version": "0.0.0",
 __PRIVATE__  "description": "__NAME__ language server, built with the Hydranium framework.",
   "keywords": [
-    "hydranium",
-    "langium",
-    "language-server",
-    "__PROJECT_ID__"
-  ],
+__KEYWORDS__  ],
   "license": "UNLICENSED",
   "author": "",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "bin": {
 __BIN__  },
   "files": [
@@ -308,17 +444,32 @@ __BIN__  },
     "src",
     "syntaxes"
   ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./node": {
+      "types": "./lib/node/services.d.ts",
+      "default": "./lib/node/services.js"
+    },
+    "./lib/*": "./lib/*",
+    "./package.json": "./package.json"
+  },
   "scripts": {
-    "build": "npm run generate && tsc",
+    "build": "npm run generate && tsc -b",
     "clean": "rimraf lib syntaxes src/language-server/generated src/language-server/generated-hydranium tsconfig.tsbuildinfo",
     "generate": "npm run langium:generate && npm run generate:transfer-model",
-    "generate:transfer-model": "hydranium-cli generate-transfer-model --ast-file src/language-server/generated/ast.ts --augmentation-file src/language-server/ast.ts --out-file src/language-server/generated-hydranium/transfer-model.ts --ast-builder-file src/language-server/generated-hydranium/ast-builder.ts --element-type-name __NAME__Element --terminals-name __NAME__Terminals --regen-command \\"Run: __NPM_RUN__ generate:transfer-model\\"",
+    "generate:transfer-model": "hydranium-cli generate-transfer-model --ast-file src/language-server/generated/ast.ts --augmentation-file src/language-server/ast.ts --out-file ../protocol/src/generated-hydranium/transfer-model.ts --ast-builder-file src/language-server/generated-hydranium/ast-builder.ts --languages-file ../protocol/src/generated-hydranium/languages.ts --element-type-name __NAME__Element --terminals-name __NAME__Terminals --regen-command \\"Run: __NPM_RUN__ generate:transfer-model\\"",
     "langium:generate": "langium generate",
     "langium:watch": "langium generate --watch",
-__LINT__    "start": "node lib/main.js --stdio",
+__LINT__    "start": "node lib/main.js__START_ARGS__",
     "test": "npm run typecheck:test && vitest run",
     "typecheck:test": "tsc --noEmit -p tsconfig.test.json",
-    "watch": "tsc --watch"
+    "watch": "tsc -b --watch"
   },
   "dependencies": {
 __DEPENDENCIES__
@@ -328,8 +479,8 @@ __DEPENDENCIES__
     "@types/node": "^22.0.0",
     "langium-cli": "4.3.0",
     "rimraf": "^5.0.0",
-    "typescript": "^5.8.0",
-    "vitest": "^4.0.0"
+    "typescript": "^7.0.2",
+    "vitest": "__VITEST__"
   },
   "engines": {
     "node": ">=22.13"
@@ -338,16 +489,17 @@ __DEPENDENCIES__
 `;
 
 /**
- * How the scaffold names `npm run` when talking about itself.
+ * How the scaffold names `npm run` for one member's script.
  *
- * A workspace member's scripts are routinely invoked from the repo root, where
- * a bare `npm run` reaches the ROOT manifest and fails — so the regen hint a
- * generated file prints has to name the package, or it sends every reader who
- * follows it to the wrong place.
+ * Always with `--prefix`, from the directory commands are run in: the
+ * workspace root for a member, the project root for a standalone project. A
+ * bare `npm run` there reaches the ROOT manifest and fails, and the regen hint
+ * a generated file prints is read in `protocol/` as well, where the script it
+ * names does not exist.
  */
-function npmRun(composition: InitComposition): string {
+function npmRun(composition: InitComposition, member: InitMember): string {
    const workspace = composition.packaging.workspace;
-   return workspace === undefined ? 'npm run' : `npm --prefix ${workspace.targetPath} run`;
+   return `npm --prefix ${workspace === undefined ? member : `${workspace.targetPath}/${member}`} run`;
 }
 
 /**
@@ -359,7 +511,7 @@ function npmRun(composition: InitComposition): string {
  * name. Without the second key a scaffolded project has no command line that
  * reaches its own data head at all.
  *
- * Alphabetical, because `prettier-plugin-packagejson` sorts `bin` and any other
+ * Alphabetical, because Oxfmt's `sortPackageJson` sorts `bin` and any other
  * order is rewritten by the scaffolded project's first `format` run.
  */
 function binBlock(composition: InitComposition): string {
@@ -370,21 +522,39 @@ function binBlock(composition: InitComposition): string {
    return entries.map(([name, target]) => `    "${name}": "${target}"`).join(',\n') + '\n';
 }
 
-/** `package.json` with the name, the private flag and the dependency block all derived. */
+/**
+ * A member's `lint` script line, over `directories`, or nothing.
+ *
+ * Emitted only where a root lint config says the repo lints. The absence is
+ * the dangerous direction: a task runner runs a script only where one is
+ * declared, so a package with no `lint` is SKIPPED rather than reported, and
+ * that reads as a clean lint. A wrong invocation is one visible line to edit.
+ */
+function lintScript(member: InitComposition, directories: string): string {
+   const workspace = member.packaging.workspace;
+   if (workspace?.oxlintConfig !== undefined) {
+      const config = `${'../'.repeat(workspace.targetPath.split('/').length)}${workspace.oxlintConfig}`;
+      return `    "lint": "oxlint --report-unused-disable-directives --format stylish --config ${config} ${directories} --max-warnings 0",\n`;
+   }
+   return workspace?.eslintConfig !== undefined ? `    "lint": "eslint ${directories} --max-warnings 0",\n` : '';
+}
+
+/** The server's `package.json`, with the name, the private flag and the dependency block all derived. */
 function packageJson(composition: InitComposition): string {
-   const { scope } = composition.packaging;
-   const packageName = scope === undefined ? composition.projectId : `${scope}/${composition.projectId}`;
-   // Emitted only where a root eslint config says the repo lints. The absence is
-   // the dangerous direction: a task runner runs a script only where one is
-   // declared, so a package with no `lint` is SKIPPED rather than reported, and
-   // that reads as a clean lint. A wrong invocation is one visible line to edit.
-   const lint = composition.packaging.workspace?.eslintConfig === undefined ? '' : '    "lint": "eslint src test --max-warnings 0",\n';
+   const keywords =
+      ['hydranium', 'langium', 'language-server', composition.projectId]
+         .sort()
+         .map(keyword => `    ${JSON.stringify(keyword)}`)
+         .join(',\n') + '\n';
    return project(PACKAGE_JSON, composition)
-      .replace('__PACKAGE_NAME__', packageName)
+      .replace('__PACKAGE_NAME__', memberPackageName(composition, 'server'))
+      .replace('__KEYWORDS__', keywords)
       .replace('__BIN__', binBlock(composition))
-      .replace('__LINT__', lint)
+      .replace('__LINT__', lintScript(forMember(composition, 'server'), 'src test'))
+      .replace('__START_ARGS__', composition.heads.includes('lsp') ? ' --stdio' : ' ../workspace')
+      .replace('__VITEST__', pinsVitest(composition) ? '~4.0.18' : '^4.0.0')
       .replace('__PRIVATE__', composition.packaging.private ? '  "private": true,\n' : '')
-      .replace('__NPM_RUN__', npmRun(composition))
+      .replace('__NPM_RUN__', npmRun(composition, 'server'))
       .replace('__FRAMEWORK_PIN__', frameworkPin(composition))
       .replace('__DEPENDENCIES__', dependencyBlock(composition, '    '));
 }
@@ -439,6 +609,11 @@ const TSCONFIG_COMPILER_OPTIONS: ReadonlyArray<readonly [string, JsonValue]> = [
    ['outDir', 'lib'],
    ['strict', true],
    ['esModuleInterop', true],
+   // A server that renders its own user-facing messages loads a catalogue, and
+   // a catalogue is JSON. Without this the import does not resolve at all, and
+   // without the `include` glob below a composite project rejects it with
+   // TS6307 naming neither cause.
+   ['resolveJsonModule', true],
    ['skipLibCheck', true],
    ['declaration', true],
    ['experimentalDecorators', true],
@@ -447,6 +622,24 @@ const TSCONFIG_COMPILER_OPTIONS: ReadonlyArray<readonly [string, JsonValue]> = [
    ['types', ['node']]
 ];
 
+/** The protocol member's compiler options, pruned against a workspace base like the server's. */
+const PROTOCOL_COMPILER_OPTIONS: ReadonlyArray<readonly [string, JsonValue]> = [
+   ['target', 'ES2022'],
+   ['lib', ['ES2022']],
+   ['module', 'NodeNext'],
+   ['moduleResolution', 'NodeNext'],
+   ['rootDir', 'src'],
+   ['outDir', 'lib'],
+   ['strict', true],
+   ['skipLibCheck', true],
+   ['declaration', true],
+   // The server's `tsc -b` builds this project through a reference, which
+   // `tsc` refuses unless the referenced project is composite.
+   ['composite', true],
+   // No ambient Node types: a browser client compiles against this package.
+   ['types', []]
+];
+
 /**
  * The options that describe where THIS package's own files live. Never pruned,
  * and emitted first in the workspace case: a base config that supplied them
@@ -455,9 +648,20 @@ const TSCONFIG_COMPILER_OPTIONS: ReadonlyArray<readonly [string, JsonValue]> = [
  */
 const PACKAGE_LOCAL_OPTIONS: readonly string[] = ['rootDir', 'outDir'];
 
-/** Compare two JSON option values. Sound here because compiler options are scalars and flat arrays. */
-function jsonEquals(left: JsonValue | undefined, right: JsonValue): boolean {
-   return JSON.stringify(left) === JSON.stringify(right);
+/**
+ * The enum-valued options of {@link TSCONFIG_COMPILER_OPTIONS}, whose values
+ * `tsc` reads case-insensitively, so `nodenext` and `NodeNext` are one value.
+ * An enum-valued option added there belongs here too.
+ */
+const CASE_INSENSITIVE_OPTIONS: readonly string[] = ['target', 'lib', 'module', 'moduleResolution'];
+
+/** Compare two option values. Sound here because compiler options are scalars and flat arrays. */
+function optionEquals(key: string, left: JsonValue | undefined, right: JsonValue): boolean {
+   const normalise = (value: JsonValue | undefined) => {
+      const text = JSON.stringify(value);
+      return CASE_INSENSITIVE_OPTIONS.includes(key) ? text?.toLowerCase() : text;
+   };
+   return normalise(left) === normalise(right);
 }
 
 /**
@@ -467,112 +671,55 @@ function jsonEquals(left: JsonValue | undefined, right: JsonValue): boolean {
  * the same key: inheriting `"module": "CommonJS"` where the scaffold needs
  * `NodeNext` would break every emitted import, so a differing base value is a
  * reason to keep the override rather than to trust the parent.
+ *
+ * `member` is the composition as that member sees it, so `extends` reaches the
+ * workspace base from the member's own directory.
  */
-function tsconfigJson(composition: InitComposition): string {
-   const workspace = composition.packaging.workspace;
+function tsconfigJson(
+   member: InitComposition,
+   compilerOptions: ReadonlyArray<readonly [string, JsonValue]>,
+   include: string,
+   references = ''
+): string {
+   const workspace = member.packaging.workspace;
    const base = workspace?.baseTsconfig === undefined ? undefined : (workspace.baseCompilerOptions ?? {});
    const options =
       base === undefined
-         ? TSCONFIG_COMPILER_OPTIONS
+         ? compilerOptions
          : [
-              ...TSCONFIG_COMPILER_OPTIONS.filter(([key]) => PACKAGE_LOCAL_OPTIONS.includes(key)),
-              ...TSCONFIG_COMPILER_OPTIONS.filter(([key, value]) => !PACKAGE_LOCAL_OPTIONS.includes(key) && !jsonEquals(base[key], value))
+              ...compilerOptions.filter(([key]) => PACKAGE_LOCAL_OPTIONS.includes(key)),
+              ...compilerOptions.filter(([key, value]) => !PACKAGE_LOCAL_OPTIONS.includes(key) && !optionEquals(key, base[key], value))
            ];
    const extendsLine = workspace?.baseTsconfig === undefined ? '' : `  "extends": "${workspace.baseTsconfig}",\n`;
    const body = options.map(([key, value]) => `    "${key}": ${JSON.stringify(value)}`).join(',\n');
-   return `{\n${extendsLine}  "compilerOptions": {\n${body}\n  },\n  "include": ["src"]\n}\n`;
-}
-
-// `isolatedModules` is what makes this check agree with the transform that
-// actually runs the tests. `npm test` is `typecheck:test && vitest run`, and
-// vitest compiles through esbuild — a per-file transform with no type
-// information, which cannot tell a re-exported TYPE from a re-exported value.
-// Without the flag `tsc` accepts `export { SomeType } from './x'` that esbuild
-// then emits as a real import of a symbol that does not exist at runtime, so
-// the typecheck passes and the suite fails with a confusing missing-export.
-const TSCONFIG_TEST = `{
-  "extends": "./tsconfig.json",
-  "compilerOptions": {
-    "rootDir": ".",
-    "noEmit": true,
-    "isolatedModules": true,
-    "types": ["node"]
-  },
-  "include": ["src", "test"]
+   const referencesLine = references === '' ? '' : `,\n  "references": ${references}`;
+   return `{\n${extendsLine}  "compilerOptions": {\n${body}\n  },\n  "include": ${include}${referencesLine}\n}\n`;
 }
-`;
-
-const VITEST_CONFIG = `import { defineConfig } from 'vitest/config';
-
-// Vitest transforms TypeScript itself and resolves \`.js\` specifiers to their
-// \`.ts\` source, so tests import from \`../src/\` with the same specifiers the
-// compiled output uses. \`include\` is scoped to \`test/\` so \`lib/\` is never
-// scanned; \`npm test\` runs \`typecheck:test\` first, because the esbuild
-// transform strips types without checking them.
-
-export default defineConfig({
-   test: {
-      environment: 'node',
-      include: ['test/**/*.{test,spec}.ts']
-   }
-});
-`;
-
-const GITIGNORE = `node_modules/
-lib/
-*.tsbuildinfo
-
-# Langium-generated TextMate grammar (rewritten by every \`langium generate\`).
-syntaxes/
-`;
 
 /**
- * The workspace-member `.gitignore` — one entry, and the one entry a root
- * cannot be assumed to have.
- *
- * A member inherits the root's rules, and `node_modules/`, `lib/` and
- * `*.tsbuildinfo` are in every monorepo root already, so repeating them here
- * would be three lines to keep in step for no coverage. `syntaxes/` is not like
- * them: it is a Langium artefact, so a root that has never held a Langium
- * package has no rule for it, and the first `langium generate` then offers
- * generated output up for commit with nothing to warn the adopter. Dropping the
- * whole file rather than this subset is the mistake this template exists to
- * undo.
+ * The server's `tsconfig.json`. It references the protocol member, so `tsc -b`
+ * compiles protocol first, after `generate` has written its generated modules.
  */
-const GITIGNORE_WORKSPACE_MEMBER = `# The workspace root already covers \`node_modules/\`, \`lib/\` and \`*.tsbuildinfo\`.
-# It has no reason to know about this one: the TextMate grammar is a Langium
-# artefact, rewritten by every \`langium generate\`, so a root that has never held
-# a Langium package ignores nothing here and the generated file is offered for
-# commit.
-syntaxes/
-`;
-
-/** The terminals every grammar needs, shared verbatim by the fragment and the lone-grammar case. */
-const TERMINALS = `hidden terminal WS: /\\s+/;
-terminal ID: /[_a-zA-Z][\\w_]*/;
-hidden terminal SL_COMMENT: /\\/\\/[^\\n\\r]*/;
-hidden terminal ML_COMMENT: /\\/\\*[\\s\\S]*?\\*\\//;
-`;
+function serverTsconfigJson(composition: InitComposition): string {
+   return tsconfigJson(
+      forMember(composition, 'server'),
+      TSCONFIG_COMPILER_OPTIONS,
+      '["src", "src/**/*.json"]',
+      '[{ "path": "../protocol" }]'
+   );
+}
 
 /**
- * The shared lexical fragment, emitted only for a multi-grammar project.
- *
- * The alternative — every grammar declaring its own `WS` / `ID` — lets the token
- * sets drift apart.
+ * The terminals every grammar needs: the shared fragment's text after its
+ * leading comment run, so a lone grammar declares the same set.
  */
-const COMMON_GRAMMAR = `// Shared lexical basis for this project's grammars. Imported, never registered:
-// it has no entry rule and no \`langium-config.json\` entry, so it is a fragment
-// rather than a language.
-//
-// Keeping the tokens here rather than in one of the languages means a grammar
-// imports \`common\` for its TOKENS and another language only when it needs that
-// language's TYPES — separate reasons that are worth keeping separate.
-
-${TERMINALS}`;
+function terminals(): string {
+   return template('server/src/grammar/common.langium').replace(/^(\/\/.*\n)*\n/, '');
+}
 
 /** One starter grammar. `shared` decides whether it imports the fragment or declares its own terminals. */
 function grammarFile(shared: boolean): string {
-   const lexis = shared ? "import './common'\n" : `\n${TERMINALS}`;
+   const lexis = shared ? "import './common'\n" : `\n${terminals()}`;
    return `grammar __GRAMMAR__
 ${shared ? '\n' + lexis : ''}
 // A minimal starter grammar — replace with your own language. \`__NODE_RULE__\` is
@@ -761,185 +908,100 @@ ${returnType}
    return project(text, composition);
 }
 
-const SERVICES = `// Zero-arg service factory for the headless \`hydranium-cli\` tooling: the
-// \`reflect\` / \`lint-grammar\` / \`validate\` subcommands import this via
-// \`--services ./lib/services.js\`. The head wires its own filesystem here.
-//
-// The contract is language-count-agnostic — a second grammar needs no edit here.
-
-import { NodeFileSystem } from '@hydranium/core/node';
-import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
-
-export function createServices(): ReturnType<typeof create__NAME__Services> {
-   return create__NAME__Services({ ...NodeFileSystem });
+/** One exported constant of the protocol member's `head-ports.ts`. */
+interface HeadPortConstant {
+   readonly name: string;
+   readonly value: string;
+   readonly doc: string;
 }
-`;
-
-const AST = `// The language's AST entry point: a re-export of what \`langium generate\`
-// emits, plus anywhere you augment those types.
-//
-// Import the AST from HERE rather than from \`./generated/ast.js\`, so any
-// augmentation below travels with every import. One \`langium-cli\` run over N
-// grammars emits ONE combined AST module sharing one reflection, so a further
-// grammar needs no change here.
-//
-// \`generate:transfer-model\` reads this file as its \`--augmentation-file\`: the
-// generated wire types are derived from the AST *as augmented*, not from the
-// raw generated module. Augment a type here and the transfer model follows.
-//
-// A \`@derived\` property is computed at build time rather than parsed, so it is
-// declared here and populated by an AST-extension contribution:
-//
-// declare module './generated/ast.js' {
-//    interface __ENTRY_RULE__ {
-//       /** @derived Populated by an \`ast.extensions.computedProperties\` contribution. */
-//       readonly _summary?: string;
-//    }
-// }
-
-export * from './generated/ast.js';
-`;
 
 /**
- * The starter serializer — the concrete-syntax emitter for ONE grammar.
+ * How a host finds each socket head's port, in emission order: an LSP request
+ * when the LSP head publishes the ports, else the environment variable
+ * `main.ts` reads a port from.
  *
- * Emitted per grammar, not per project, because `services.serializer.Serializer`
- * is a per-language slot and a serializer is grammar-shaped by definition. That
- * is also why the framework refuses to default it: its `UnboundSerializer`
- * throws, naming the binding to add, rather than guessing a syntax.
- */
-const SERIALIZER = `// Concrete-syntax emitter for __GRAMMAR__ — the parser's inverse, turning a
-// model back into text this grammar accepts. Derived from the starter grammar
-// exactly as \`generated/ast.ts\` is, so replacing the grammar replaces this too.
-//
-// Without it every structured write fails: the framework's default binding at
-// \`services.serializer.Serializer\` THROWS, because a concrete syntax is
-// language knowledge no framework can derive. \`ModelService.update\` / \`save\`,
-// the data head's \`saveModelDocument\` and a GLSP \`SaveModelAction\` all reach
-// it.
-//
-// \`AbstractSerializer\`'s generic property walk lays out FORMAT-structured
-// output — its YAML and JSON subclasses are what it exists for — and cannot
-// produce a keyword-delimited syntax like \`node a -> b\`. So \`serializeNode\` is
-// a per-\`$type\` emitter here and the two array hooks are unreachable.
-
-import { AbstractSerializer } from '@hydranium/core';
-import type { AstNode } from '@hydranium/langium';
-import { type __ENTRY_RULE__, type __NODE_RULE__, is__ENTRY_RULE__, is__NODE_RULE__ } from './ast.js';
-
-export class __GRAMMAR__Serializer extends AbstractSerializer<__ENTRY_RULE__> {
-   protected override serializeNode(node: AstNode | Record<string, unknown>): string {
-      if (is__ENTRY_RULE__(node)) {
-         return node.nodes.map(child => this.emitNode(child)).join('\\n');
-      }
-      if (is__NODE_RULE__(node)) {
-         return this.emitNode(node);
-      }
-      // Defensive: a rule added to the grammar with no emitter added here.
-      throw new Error(\`__GRAMMAR__Serializer: no emitter for $type \${(node as AstNode).$type}\`);
-   }
-
-   /** Unreachable — this grammar's one list is emitted by its \`__ENTRY_RULE__\` parent. */
-   protected override serializeArray(): string {
-      throw new Error('__GRAMMAR__Serializer: arrays are emitted by the per-$type parent, not the generic dispatch.');
-   }
-
-   /** Unreachable — same reasoning as {@link serializeArray}. */
-   protected override serializeReferenceArray(): string {
-      throw new Error('__GRAMMAR__Serializer: reference arrays are emitted by the per-$type parent, not the generic dispatch.');
-   }
-
-   /**
-    * \`serializeReferenceText\` rather than \`node.target?.$refText\`: it is the one
-    * read that spans BOTH input shapes. A transfer model reaching
-    * \`serializeTransfer\` carries \`target\` as a plain string rather than a
-    * \`Reference\`, and a serializer that reaches for \`$refText\` directly emits
-    * the AST correctly and drops every reference on the transfer path.
-    */
-   private emitNode(node: __NODE_RULE__): string {
-      const target = this.serializeReferenceText(node.target);
-      return target === undefined ? \`node \${node.name}\` : \`node \${node.name} -> \${target}\`;
-   }
-}
-`;
-
-/**
- * The exported constant names for the head set, in emission order. Both are
- * keyed by the PROJECT rather than by a language: one server of each kind per
+ * Keyed by the PROJECT rather than by a language: one server of each kind per
  * process serves every registered grammar, so a language-derived name would tie
  * a project-level endpoint to whichever grammar was scaffolded first.
  */
-function portCommandNames(composition: InitComposition): string[] {
+function headPortConstants(composition: InitComposition): HeadPortConstant[] {
    const upper = screamingSnake(composition.projectId);
-   return [
-      ...(composition.heads.includes('data') ? [`${upper}_DATA_SERVER_PORT_COMMAND`] : []),
-      ...(composition.heads.includes('glsp') ? [`${upper}_GLSP_PORT_COMMAND`] : [])
+   const lsp = composition.heads.includes('lsp');
+   const heads = [
+      ...(composition.heads.includes('data') ? [{ key: 'DATA_SERVER', path: 'data-server', label: 'data-server' }] : []),
+      ...(composition.heads.includes('glsp') ? [{ key: 'GLSP_SERVER', path: 'glsp-server', label: 'GLSP' }] : [])
    ];
+   return heads.map(head =>
+      lsp
+         ? {
+              name: `${upper}_${head.key}_PORT_COMMAND`,
+              value: `${composition.projectId}/${head.path}/port`,
+              doc: `LSP request the host queries to discover the ${head.label} socket port.`
+           }
+         : {
+              name: `${upper}_${head.key}_PORT_ENV`,
+              value: `${upper}_${head.key}_PORT`,
+              doc: `Environment variable naming the ${head.label} socket port when no \`--${head.path}-port\` flag does.`
+           }
+   );
 }
 
 /**
- * The socket heads' discovery commands, as an importable module.
+ * The socket heads' port commands or variables, in the protocol member.
  *
- * Deliberately NOT declared in `main.ts`. A host shell has to name the same
- * string to reach the head, and `main.ts` opens a connection at module scope,
- * so importing a constant from it would start a server. A host that retypes the
- * literal instead gets no error when it drifts: the framework's port poll
- * defaults to `findPortAttempts = -1`, so a wrong command retries forever
- * rather than failing.
+ * A host shell has to name the same string the server reads, and reaches it
+ * here without depending on the server. A host that retypes the literal
+ * instead gets no error when it drifts: the framework's port poll defaults to
+ * `findPortAttempts = -1`, so a wrong command retries forever rather than
+ * failing, and a wrong variable is never read.
  */
 function headPortsFile(composition: InitComposition): string {
-   const upper = screamingSnake(composition.projectId);
-   const data = composition.heads.includes('data');
-   const glsp = composition.heads.includes('glsp');
-   const blocks = [
-      ...(data
-         ? [
-              `/** LSP request the host queries to discover the data-server socket port. */\nexport const ${upper}_DATA_SERVER_PORT_COMMAND = '${composition.projectId}/data-server/port';`
-           ]
-         : []),
-      ...(glsp
-         ? [
-              `/** LSP request the host queries to discover the GLSP socket port. */\nexport const ${upper}_GLSP_PORT_COMMAND = '${composition.projectId}/glsp/port';`
-           ]
-         : [])
-   ];
-   return `// The LSP requests a host queries to discover this server's socket head${blocks.length > 1 ? 's' : ''}.
+   const constants = headPortConstants(composition);
+   const blocks = constants.map(constant => `/** ${constant.doc} */\nexport const ${constant.name} = '${constant.value}';`);
+   const heads = `socket head${blocks.length > 1 ? 's' : ''}`;
+   const opening = composition.heads.includes('lsp')
+      ? `// The LSP requests a host queries to discover this server's ${heads}.`
+      : `// The environment variables that name the ports of this server's ${heads}.`;
+   const usage = composition.heads.includes('lsp')
+      ? `// The server publishes them and a host shell has to name the same string to
+// reach the head; both import them from here. A shell that retypes the literal
+// gets no error when it drifts: the framework's port poll retries indefinitely
+// by default.`
+      : `// The server reads them and a process that starts it sets them; both import
+// them from here. A variable retyped with a typo is never read, and the head
+// then listens on whichever port is free.`;
+   return `${opening}
 //
-// Both are keyed by the PROJECT, not the language: one server of each kind per
+// ${blocks.length > 1 ? 'Both are' : 'It is'} keyed by the PROJECT, not the language: one server of each kind per
 // process serves every registered grammar, so a language-derived name would tie
 // a project-level endpoint to whichever grammar was scaffolded first.
 //
-// They live here rather than in \`main.ts\` because a host shell has to name the
-// same string to reach the head, and \`main.ts\` is an executable entry — nothing
-// can import from it. A shell that retypes the literal gets no error when it
-// drifts: the framework's port poll retries indefinitely by default. Import
-// these instead, and assert any host-side copy against them.
+${usage}
 
 ${blocks.join('\n\n')}
 `;
 }
 
-const INDEX = `// Public surface of the __NAME__ language server: the DI factory, the generated
-// AST, and the headless \`createServices\` entry.
+/**
+ * The server's root entry: the DI factory, the generated AST and each diagram
+ * module, all loadable in a browser worker.
+ */
+function indexFile(composition: InitComposition): string {
+   const diagrams = composition.grammars.filter(grammar => grammar.diagram);
+   const diagramPhrase = diagrams.length === 0 ? '' : diagrams.length === 1 ? ', plus the diagram module' : ', plus the diagram modules';
+   const text = `// Public surface of the __NAME__ language server: the DI factory and the
+// generated AST${diagramPhrase}.
 //
-// The entry points under \`src/\` are deliberately NOT re-exported. Each opens a
-// transport at module scope, so importing one starts a server as a side effect
-// — which is why they are \`bin\` targets and this file is \`main\`.
+// Everything here loads in a browser worker as well as in Node, so a host can
+// compose the language wherever it runs it. \`createServices\`, which reads the
+// real filesystem, is the package's \`./node\` entry instead. The entry points
+// under \`src/\` are not re-exported either: each opens a transport at module
+// scope, so importing one starts a server, which is why they are \`bin\` targets.
 
 export * from './language-server/__PROJECT_ID__-module.js';
 export * from './language-server/ast.js';
-export { createServices } from './services.js';
-`;
-
-/**
- * The public surface, plus the head-port commands when there is a socket head.
- *
- * The commands belong here rather than only in `head-ports.ts` so a host shell
- * reaches them from the package root, the same way it reaches `createServices`.
- */
-function indexFile(composition: InitComposition): string {
-   const base = project(INDEX, composition);
-   return portCommandNames(composition).length ? `${base}export * from './head-ports.js';\n` : base;
+${diagrams.map(grammar => `export * from './glsp/${grammar.grammarId}/diagram-module.js';\n`).join('')}`;
+   return project(text, composition);
 }
 
 /**
@@ -969,10 +1031,12 @@ function mainFile(composition: InitComposition): string {
    const columns = columnsFor(composition);
    const roots = [...composition.grammars.map(grammar => grammar.entryRule)].sort();
    const upper = screamingSnake(composition.projectId);
+   const lsp = composition.heads.includes('lsp');
    const data = composition.heads.includes('data');
    const glsp = composition.heads.includes('glsp');
    const diagrams = composition.grammars.filter(grammar => grammar.diagram);
    const plural = roots.length > 1 ? 's' : '';
+   const portFlags = [...(data ? ['--data-server-port'] : []), ...(glsp ? ['--glsp-server-port'] : [])];
 
    const headNames = composition.heads.map(head =>
       head === 'lsp' ? 'the Langium LSP head' : head === 'data' ? 'a socket data-server (model server) head' : 'a GLSP head'
@@ -986,7 +1050,7 @@ function mainFile(composition: InitComposition): string {
    // `reflect-metadata` must be imported before anything that reads a
    // decorator's emitted metadata, which inversify does at module scope.
    const reflectImport = glsp ? "import 'reflect-metadata';\n" : '';
-   const coreNodeSymbols = ['NodeFileSystem', ...(data ? ['publishPortOnLspConnection', 'startSocketServer'] : [])];
+   const coreNodeSymbols = ['NodeFileSystem', ...(data ? [...(lsp ? ['publishPortOnLspConnection'] : []), 'startSocketServer'] : [])];
    const glspImports = glsp
       ? `import { ServerModule } from '@eclipse-glsp/server/node.js';
 import { GlspClientLogger, HydraniumGlspAppModule } from '@hydranium/glsp-server';
@@ -1003,46 +1067,59 @@ import { startGlspServer } from '@hydranium/glsp-server/node';
 // \`TransferElement\` structurally, so naming the AST type here compiles fine and
 // silently tells every typed client that a reference is a resolvable object
 // rather than a name.
-${importList(roots, './language-server/generated-hydranium/transfer-model.js', columns, true)}
+${importList(roots, memberPackageName(composition, 'protocol'), columns, true)}
 `
       : '';
 
-   // The commands live in `head-ports.ts`, not here: a host shell has to name
-   // the same string to reach the head, and this file is an executable entry, so
-   // nothing can import from it.
-   const portCommands = portCommandNames(composition).length
-      ? importList(portCommandNames(composition), './head-ports.js', columns) + '\n'
-      : '';
-
-   const dataBlock = data
-      ? `
+   // The names live in the protocol member, not here: a host shell has to name
+   // the same string to reach the head, and this file is an executable entry,
+   // so nothing can import from it.
+   const portNames = headPortConstants(composition).map(constant => constant.name);
+   const portImports = portNames.length ? importList(portNames, memberPackageName(composition, 'protocol'), columns) + '\n' : '';
+
+   const dataBlock = !data
+      ? ''
+      : !lsp
+        ? `
+// Data-server head: each accepted client gets its own DataServer.
+const dataServer = startSocketServer(
+   { shared, workspace, port: portFrom('data-server-port', ${upper}_DATA_SERVER_PORT_ENV), logTag: 'ModelServer', logger: shared.Logger },
+   dataConnection => {
+      new DataServer<${roots.join(' | ')}>(dataConnection, shared);
+      return { dispose: () => undefined };
+   }
+);
+`
+        : `
 // Data-server head alongside LSP: binds an ephemeral port, published over the LSP
 // connection for the host to discover. Each accepted client gets its own DataServer.
 //
 // Neither the bind nor the publish may be swallowed: either failure leaves the LSP
 // head serving text edits while every data client waits on a port command that was
 // never registered, and the launcher reports a bind failure only if given a logger.
-const dataServer = startSocketServer({ port: 0, logTag: 'ModelServer', logger: shared.Logger }, dataConnection => {
+const dataServer = startSocketServer({ shared, port: 0, logTag: 'ModelServer', logger: shared.Logger }, dataConnection => {
    new DataServer<${roots.join(' | ')}>(dataConnection, shared);
    return { dispose: () => undefined };
 });
 dataServer.started
-   .then(() => {
-      const { port } = dataServer;
-      if (port === undefined) {
-         // \`started\` resolves only once the address is resolved, so this is
-         // unreachable; a non-null assertion in its place would publish
-         // \`undefined\`, which the host cannot tell from an unreachable port.
-         throw new Error('the data head started without a resolved port');
-      }
-      publishPortOnLspConnection(shared.lsp.Connection, ${upper}_DATA_SERVER_PORT_COMMAND, port);
-   })
+   .then(
+      () => {
+         const { port } = dataServer;
+         if (port === undefined) {
+            // \`started\` resolves only once the address is resolved, so this is
+            // unreachable; a non-null assertion in its place would publish
+            // \`undefined\`, which the host cannot tell from an unreachable port.
+            throw new Error('the data head started without a resolved port');
+         }
+         publishPortOnLspConnection(shared.lsp.Connection, ${upper}_DATA_SERVER_PORT_COMMAND, port);
+      },
+      // The launcher logged its own bind failure; the rejection is control flow.
+      () => undefined
+   )
    .catch((error: unknown) => {
-      const reason = error instanceof Error ? error.message : String(error);
-      shared.Logger.error(\`[ModelServer] Could not publish the data-server port: \${reason}\`);
+      shared.Logger.error(\`[ModelServer] Could not publish the data-server port: \${describeErrorWithStack(error)}\`);
    });
-`
-      : '';
+`;
 
    const glspBlock = glsp
       ? `
@@ -1051,49 +1128,115 @@ dataServer.started
 // grammar a request concerns, so nothing per-language belongs there — each
 // diagram module declares its own language instead.
 //
-// GLSP framework logs route through the LSP connection rather than stdout, which
-// IS the LSP transport in stdio mode; writing there corrupts the protocol stream.
+${
+   lsp
+      ? `// GLSP framework logs route through the LSP connection rather than stdout, which
+// IS the LSP transport in stdio mode; writing there corrupts the protocol stream.`
+      : `// GLSP framework logs route through the framework's logger to stderr. GLSP's
+// own startup line goes to stdout, beside the ports line below.`
+}
 const glspServer = startGlspServer({
    // The GLSP log threshold lives on the logger, not beside it: the framework
    // replaces GLSP's own \`Logger\` binding, so a launcher-level \`logLevel\` would
    // be discarded. The logger tracks the framework's process-wide threshold, so
-   // \`HYDRANIUM_LOG_LEVEL\` and the LSP log-level setting govern GLSP output too;
+   // \`HYDRANIUM_LOG_LEVEL\` ${lsp ? 'and the LSP log-level setting govern' : 'governs'} GLSP output too;
    // pass \`logLevel\` only to make GLSP quieter than the rest of the server.
    createLogger: caller => new GlspClientLogger(shared, { component: caller }),
    serverModule: new ServerModule()${diagrams.map(grammar => `.configureDiagramModule(new ${grammar.grammar}DiagramModule())`).join('')},
    appModules: [new HydraniumGlspAppModule({ shared })],
-   lspConnection: shared.lsp.Connection,
-   portCommand: ${upper}_GLSP_PORT_COMMAND
+${
+   lsp
+      ? `   lspConnection: shared.lsp.Connection,
+   portCommand: ${upper}_GLSP_SERVER_PORT_COMMAND`
+      : `   workspace,
+   port: portFrom('glsp-server-port', ${upper}_GLSP_SERVER_PORT_ENV),
+   logger: shared.Logger`
+}
 });
-void glspServer;
-`
+${lsp ? 'void glspServer;\n' : ''}`
       : '';
 
+   const lspImports = `// The framework's entry point, NOT Langium's \`@hydranium/langium/lsp\` one. It is
+// signature-compatible and delegates straight through; what it adds first is
+// \`assertLspHeadComposed\`, which fails the start if the LSP head's SHARED module
+// was never composed. Reaching for Langium's is the natural mistake and it is
+// silent: the server boots, links and completes, while echo suppression, the
+// didChangeContent debounce and the last-client-close rebuild are all inert.
+import { startLanguageServer, withHydraniumLspFeatures } from '@hydranium/core/lsp';
+import { ProposedFeatures, createConnection } from 'vscode-languageserver/node';
+`;
+
+   const lspStart = `
+const connection = createConnection(withHydraniumLspFeatures(ProposedFeatures.all));
+const { shared } = create__NAME__Services({ connection, ...NodeFileSystem });
+startLanguageServer(shared);
+`;
+
+   // No LSP client names the workspace or asks for the ports here, so the
+   // command line does, and the ports go to stdout once every head listens.
+   const servers = [...(data ? ['dataServer'] : []), ...(glsp ? ['glspServer'] : [])];
+   const socketStart = `
+const { values, positionals } = parseArgs({
+   options: { ${portFlags.map(flag => `'${flag.slice(2)}': { type: 'string' }`).join(', ')} },
+   allowPositionals: true
+});
+// The workspace root: the first argument, else the process cwd.
+const workspace = positionals[0] ?? process.cwd();
+
+/** A head's port: its flag, else its environment variable, else 0 for any free port. */
+function portFrom(flag: keyof typeof values, variable: string): number {
+   const text = values[flag] ?? process.env[variable] ?? '0';
+   const port = Number(text);
+   // Decimal digits only: \`Number\` also reads '' as 0 and takes '1e3' or '0x10'.
+   if (!/^\\d+$/.test(text) || port > 65_535) {
+      throw new Error(\`--\${flag} or \${variable} is '\${text}', not a port\`);
+   }
+   return port;
+}
+
+const { shared } = create__NAME__Services({ ...NodeFileSystem });
+`;
+   const portsLine = `
+// One JSON line on stdout once every head listens, for the process that started
+// this one to read the ports from: the one line that starts with \`{\`. Each
+// head brings the workspace up before it listens; a head that fails to start
+// has logged why and ends the process, which would otherwise serve without it.
+Promise.all([${servers.map(server => `${server}.started`).join(', ')}]).then(
+   () => process.stdout.write(\`\${JSON.stringify({ ${servers.map(server => `${server}: ${server}.port`).join(', ')} })}\\n\`),
+   () => process.exit(1)
+);
+`;
+
+   const invocation = lsp
+      ? `// Invocation: \`node lib/main.js --stdio\`, or the package's \`__PROJECT_ID__\` bin
+// script.`
+      : `// Invocation: \`node lib/main.js [<workspace-path>] ${portFlags.map(flag => `[${flag} <port>]`).join(' ')}\`,
+// or the package's \`__PROJECT_ID__\` bin script. Each port falls back to its
+// environment variable, then to any free port.`;
+   const dataNote = !data
+      ? ''
+      : lsp
+        ? `
+//
+// NOT the entry the data-server subcommands of \`hydranium-cli\` speak to: stdio
+// here carries LSP, and the data head is a socket whose port is published over
+// the LSP connection. Those subcommands spawn \`data-server-main.js\`.`
+        : `
+//
+// NOT the entry the data-server subcommands of \`hydranium-cli\` speak to: they
+// drive the data protocol over a child's stdio, and the data head here is a
+// socket. Those subcommands spawn \`data-server-main.js\`.`;
+
    const text = `${SHEBANG}// Standalone entry point: starts ${headSummary} in the same
 // process, so every head shares one model store.
-// Invocation: \`node lib/main.js --stdio\`, or the package's \`__PROJECT_ID__\` bin
-// script.${
-      data
-         ? `
-//
-// NOT the entry \`hydranium-cli query\` / \`save\` / \`projects\` / \`watch\` speak to:
-// stdio here carries LSP, and the data head is a socket whose port is published
-// over the LSP connection. Those subcommands spawn \`data-server-main.js\`.`
-         : ''
-   }
+${invocation}${dataNote}
 //
 // Everything here runs at module scope, so this file is an executable rather
 // than a library entry — import \`./index.js\` instead to compose the language.
 
 ${reflectImport}${glspImports}${importList(coreNodeSymbols, '@hydranium/core/node', columns)}
-${data ? "import { DataServer } from '@hydranium/data-server';\n" : ''}import { startLanguageServer } from '@hydranium/langium/lsp';
-import { ProposedFeatures, createConnection } from 'vscode-languageserver/node';
-${diagramImports}${transferImports}import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
-${portCommands === '' ? '' : '\n' + portCommands}
-const connection = createConnection(ProposedFeatures.all);
-const { shared } = create__NAME__Services({ connection, ...NodeFileSystem });
-startLanguageServer(shared);
-${dataBlock}${glspBlock}`;
+${data ? "import { DataServer } from '@hydranium/data-server';\n" : ''}${data && lsp ? "import { describeErrorWithStack } from '@hydranium/protocol';\n" : ''}${lsp ? lspImports : "import { parseArgs } from 'node:util';\n"}${diagramImports}${transferImports}import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
+${portImports === '' ? '' : '\n' + portImports}${lsp ? lspStart : socketStart}${dataBlock}${glspBlock}${lsp ? '' : portsLine}`;
    return project(text, composition);
 }
 
@@ -1101,13 +1244,12 @@ ${dataBlock}${glspBlock}`;
  * The second executable entry: the data head alone, on stdio.
  *
  * Emitted with the `data` head because it is the ONLY command line that reaches
- * that head from outside the editor. `main.ts` gives stdio to LSP and publishes
- * the data head's socket port over the LSP connection, so a client that is not
- * an LSP client cannot discover it — which is every one of `hydranium-cli`'s
- * `query` / `save` / `projects` / `watch`, all of which drive the data protocol
- * over a spawned child's stdin/stdout. Without this file a scaffolded project
- * has no `--server` value, and the closest guess — the LSP entry — fails as an
- * unrecognised method rather than as a missing head.
+ * that head from outside the editor. `main.ts` serves the data head on a
+ * socket, so a client driving the data protocol over a spawned child's
+ * stdin/stdout cannot reach it — which is every data-server subcommand of
+ * `hydranium-cli`. Without this file a scaffolded project has no `--server`
+ * value, and the closest guess, `main.ts`, fails as an unrecognised method or
+ * an unknown flag rather than as a missing head.
  *
  * A separate process rather than a flag on `main.ts`: only one protocol can own
  * stdio, so the two entries are mutually exclusive by construction.
@@ -1118,21 +1260,27 @@ function dataServerMainFile(composition: InitComposition): string {
    const plural = roots.length > 1 ? 's' : '';
 
    const text = `${SHEBANG}// Standalone entry point: a data-server head on **stdio**, with no LSP head in
-// the process. This is the transport \`hydranium-cli\` speaks — \`query\`, \`save\`,
-// \`projects\` and \`watch\` all spawn a server command and drive JSON-RPC over its
-// stdin/stdout — so it is what makes those subcommands usable against this
-// language.
+// the process. This is the transport \`hydranium-cli\` speaks — its data-server
+// subcommands spawn a server command and drive JSON-RPC over its stdin/stdout —
+// so it is what makes those subcommands usable against this language.
 //
 // Invocation: \`node lib/data-server-main.js [<workspace-path>]\`, or the
 // package's \`__PROJECT_ID__-data-server\` bin script. The workspace path defaults to
 // the process cwd, which is what the CLI's \`--cwd\` sets on the child.
 //
-// Contrast with \`main.ts\`, the editor entry: there the LSP head owns stdio and
+${
+   composition.heads.includes('lsp')
+      ? `// Contrast with \`main.ts\`, the editor entry: there the LSP head owns stdio and
 // the data head is a socket published over the LSP connection. Here there is no
 // LSP connection at all, so the workspace initialization an
 // \`initialize\`/\`initialized\` pair would otherwise drive has to happen here —
 // which is why this entry uses \`startStdioServer\` rather than wiring a
-// connection directly.
+// connection directly.`
+      : `// Contrast with \`main.ts\`, where the data head is a socket whose port it
+// prints. Here it owns stdio, and as there, no LSP connection drives the
+// workspace initialization, so \`startStdioServer\` brings the workspace up
+// before it listens.`
+}
 //
 // Everything here runs at module scope, so this file is an executable rather
 // than a library entry — import \`./index.js\` instead to compose the language.
@@ -1140,7 +1288,7 @@ function dataServerMainFile(composition: InitComposition): string {
 ${importList(['NodeFileSystem', 'startStdioServer'], '@hydranium/core/node', columns)}
 import { DataServer } from '@hydranium/data-server';
 // The TRANSFER root${plural}, not the AST one${plural} — same reasoning as \`main.ts\`.
-${importList(roots, './language-server/generated-hydranium/transfer-model.js', columns, true)}
+${importList(roots, memberPackageName(composition, 'protocol'), columns, true)}
 import { create__NAME__Services } from './language-server/__PROJECT_ID__-module.js';
 
 const { shared } = create__NAME__Services({ ...NodeFileSystem });
@@ -1189,7 +1337,7 @@ function servicesTest(composition: InitComposition): string {
 // is missing from the composition.
 
 import { describe, expect, it } from 'vitest';
-import { createServices } from '../src/services.js';
+import { createServices } from '../src/node/services.js';
 
 describe('__NAME__ services', () => {
    it('composes the DI tree and registers ${title}', () => {
@@ -1259,8 +1407,8 @@ function serializationTest(composition: InitComposition): string {
    const transferTypes = composition.grammars.map(grammar => `${grammar.entryRule} as Transfer${grammar.entryRule}`);
    const text = `// Round-trips each grammar through its serializer: parse the source, serialize
 // the model, compare the text. The serializer is the parser's inverse, so this
-// is the assertion that keeps \`ModelService.update\` / \`save\` writing files the
-// language server can read back.
+// is the assertion that keeps a client session's \`update\` / \`save\` writing
+// files the language server can read back.
 //
 // The transfer case is the one that catches the mistake worth catching.
 // \`ModelService.modelToText\` short-circuits only a RAW STRING, so a typed model
@@ -1270,8 +1418,8 @@ function serializationTest(composition: InitComposition): string {
 import { parseHelper } from '@hydranium/core/testing';
 import { describe, expect, it } from 'vitest';
 ${importList(astTypes, '../src/language-server/ast.js', columns, true)}
-${importList(transferTypes, '../src/language-server/generated-hydranium/transfer-model.js', columns, true)}
-import { createServices } from '../src/services.js';
+${importList(transferTypes, memberPackageName(composition, 'protocol'), columns, true)}
+import { createServices } from '../src/node/services.js';
 
 ${composition.grammars.map(grammar => render(SERIALIZATION_SUITE, composition, grammar)).join('\n\n')}
 `;
@@ -1398,7 +1546,7 @@ function grammarTest(composition: InitComposition, header: string, imports: read
 import { parseHelper } from '@hydranium/core/testing';
 import { describe, expect, it } from 'vitest';
 ${imports.join('\n')}${imports.length ? '\n' : ''}${importList(astTypes, '../src/language-server/ast.js', columns, true)}
-import { createServices } from '../src/services.js';
+import { createServices } from '../src/node/services.js';
 
 ${composition.grammars.map(grammar => render(suite, composition, grammar)).join('\n\n')}
 `;
@@ -1429,6 +1577,7 @@ function readme(composition: InitComposition): string {
    const multi = composition.grammars.length > 1;
    const data = composition.heads.includes('data');
    const primaryExtension = composition.grammars[0].extensions[0];
+   const diagramCount = composition.grammars.filter(grammar => grammar.diagram).length;
    const grammarBullets = composition.grammars.map(
       grammar => `- \`src/grammar/${grammar.grammarId}.langium\` — the \`${grammar.grammar}\` grammar (.${grammar.extensions.join(', .')})`
    );
@@ -1439,20 +1588,6 @@ function readme(composition: InitComposition): string {
       '',
       '## Getting started',
       '',
-      // Conditional on the pin this scaffold actually carries — see
-      // `UNPUBLISHED_FRAMEWORK_VERSION`.
-      ...(composition.frameworkVersion === UNPUBLISHED_FRAMEWORK_VERSION
-         ? [
-              '> **Pre-publish note.** `@hydranium/*` is not on npm yet, so the `0.0.0`',
-              '> pins below are placeholders and `npm install` will fail with a 404 until',
-              '> the framework is released. Until then, supply the packages from a local',
-              '> framework checkout with [yalc](https://github.com/wclr/yalc) — a plain',
-              '> `file:` path or `npm link` is not enough, because the framework packages',
-              '> depend on each other by version and npm would try to fetch those from the',
-              '> registry too.',
-              ''
-           ]
-         : []),
       '```bash',
       'npm install',
       'npm run langium:generate   # generate the AST from the grammar',
@@ -1467,25 +1602,26 @@ function readme(composition: InitComposition): string {
       // nowhere else.
       '```bash',
       '# Grammar / AST reflection',
-      'npx hydranium-cli reflect --services ./lib/services.js',
+      'npx hydranium-cli reflect --services ./lib/node/services.js',
       '',
       '# Grammar-convention lint (CI gate)',
-      'npx hydranium-cli lint-grammar --services ./lib/services.js',
+      'npx hydranium-cli lint-grammar --services ./lib/node/services.js',
       '',
       '# Validate a workspace of model files (non-zero exit on errors)',
-      'npx hydranium-cli validate --services ./lib/services.js <workspace-dir>',
+      'npx hydranium-cli validate --services ./lib/node/services.js ../workspace',
       ...(data
          ? [
               '',
               '# Data-head operations. `--server` is a command line the CLI spawns and then',
               "# drives the data protocol over the child's stdin/stdout, so it has to name",
-              '# `data-server-main.js` — `main.js` gives stdio to LSP and answers these',
-              '# methods with "Unhandled method".',
+              ...(composition.heads.includes('lsp')
+                 ? ['# `data-server-main.js` — `main.js` gives stdio to LSP and answers these', '# methods with "Unhandled method".']
+                 : ['# `data-server-main.js` — `main.js` serves the data head on a socket.']),
               '#',
               '# The workspace goes to the ENTRY, not to `--cwd`: `--cwd` re-roots the child,',
               '# so a relative entry path is refused by name (an absolute one is fine).',
-              'npx hydranium-cli projects --server "node ./lib/data-server-main.js <workspace-dir>"',
-              `npx hydranium-cli query --server "node ./lib/data-server-main.js <workspace-dir>" --uri <file:// URI of a .${primaryExtension} file>`
+              'npx hydranium-cli projects --server "node ./lib/data-server-main.js ../workspace"',
+              `npx hydranium-cli query --server "node ./lib/data-server-main.js ../workspace" --uri <file:// URI of ../workspace/nodes.${primaryExtension}>`
            ]
          : []),
       '```',
@@ -1499,8 +1635,8 @@ function readme(composition: InitComposition): string {
          grammar =>
             `- \`src/language-server/${grammar.grammarId}-serializer.ts\` — emits \`${grammar.grammar}\` back to text (the framework defaults this to a throw)`
       ),
-      '- `src/services.ts` — zero-arg `createServices()` for the headless CLI',
-      '- `src/index.ts` — the package entry (`main`): DI factory + generated AST',
+      "- `src/node/services.ts` — zero-arg `createServices()` for the headless CLI, the package's `./node` entry",
+      `- \`src/index.ts\` — the package root, loadable in a browser worker: DI factory + generated AST${diagramCount === 0 ? '' : diagramCount === 1 ? ' + diagram module' : ' + diagram modules'}`,
       `- \`src/main.ts\` — starts ${composition.heads.join(' + ')}, the \`__PROJECT_ID__\` bin entry`,
       ...(data
          ? [
@@ -1512,8 +1648,9 @@ function readme(composition: InitComposition): string {
          .filter(grammar => grammar.diagram)
          .map(
             grammar =>
-               `- \`src/glsp/${grammar.grammarId}/\` — the \`${grammar.grammar}\` diagram: type ids, state, storage, submission handler, GModel factory, configuration, create-node handler, DI module`
+               `- \`src/glsp/${grammar.grammarId}/\` — the \`${grammar.grammar}\` diagram: state, storage, submission handler, GModel factory, configuration, create-node handler, DI module`
          ),
+      `- \`../protocol/\` — the \`${memberPackageName(composition, 'protocol')}\` package: what this server and its clients both import (language ids, ${headPortConstants(composition).length === 0 ? '' : composition.heads.includes('lsp') ? 'port commands, ' : 'port variables, '}${composition.grammars.some(grammar => grammar.diagram) ? 'diagram ids, ' : ''}the transfer model), written partly by \`npm run generate\``,
       '- `test/services.test.ts` — the DI tree composes; grows as your language does',
       '- `test/parsing.test.ts` / `linking.test.ts` / `validating.test.ts` — the three tiers a new language breaks first',
       '- `test/serialization.test.ts` — each grammar round-trips through its serializer',
@@ -1566,6 +1703,24 @@ function readme(composition: InitComposition): string {
       'atomic set and depends on a single physical copy, so a floating range can',
       'silently resolve a second one.',
       '',
+      '`vscode-languageserver` is pinned to `10.0.1`, and',
+      '`vscode-languageserver-protocol` and `vscode-jsonrpc` to the `3.18.1` and',
+      '`9.0.0` it pins, so Langium, the LSP connection and the framework share one',
+      'copy of each. With two, an error a Langium handler returns, such as a request',
+      'for a document the server does not have, reaches the client as a result, and a',
+      'framework error your own LSP handler throws loses its code. The Langium 4.4',
+      'upgrade',
+      '([eclipse-emfcloud/hydranium#142](https://github.com/eclipse-emfcloud/hydranium/issues/142))',
+      'replaces these pins.',
+      '',
+      ...(pinsVitest(composition)
+         ? [
+              '`vitest` is held below 4.1, whose peer set crashes the npm every Node 22',
+              'release bundles. Raise it once every npm that installs this project is',
+              '11.6 or later.',
+              ''
+           ]
+         : []),
       '## If your repo gates license headers',
       '',
       'The emitted `.ts` files carry no copyright header — the scaffold cannot know',
@@ -1585,10 +1740,9 @@ function readme(composition: InitComposition): string {
 /**
  * The GLSP files for ONE grammar's diagram.
  *
- * Per grammar rather than per project because a diagram type has exactly one
- * grammar — `AbstractHydraniumGlspDiagramModule.declareLanguage()` returns that
- * grammar's `LanguageMetaData`, and it is bound on the SESSION container so a
- * grammar with no diagram can sit on the same server.
+ * Per grammar rather than per project because the state, storage and GModel
+ * factory are typed over that grammar's model, and a grammar with no diagram
+ * can sit on the same server.
  *
  * The index and the computed-bounds handler are framework classes used
  * unmodified; storage and the submission handler are thin typed subclasses,
@@ -1602,157 +1756,11 @@ function readme(composition: InitComposition): string {
  */
 function glspFiles(composition: InitComposition, grammar: InitGrammarNames): InitFile[] {
    const columns = columnsFor(composition);
-   const upper = screamingSnake(grammar.grammarId);
-   const dir = `src/glsp/${grammar.grammarId}`;
-   const render = (text: string): string => grammarTier(project(text, composition), grammar);
-
-   const types = `// GLSP diagram-type and element-type ids for the __GRAMMAR__ diagram.
-//
-// **Authoritative half of a client/server contract.** Every id here has to be
-// registered on the client too: sprotty's registries are exact-key maps with no
-// prefix fallback, so an id the client does not know yields an element with none
-// of a node's features, rendered by \`MissingView\` with only a
-// \`no registered view for type '…'\` console warning. Nothing fails server-side.
-//
-// The ids stay namespaced under the GLSP defaults (\`node:\` / \`edge:\`) so a
-// reader can tell a node id from an edge id at a glance.
-
-import { DefaultTypes } from '@eclipse-glsp/server';
-
-/**
- * The GLSP diagram type — the string GLSP routes every per-diagram-type request
- * by. Mirrored by the client; a mismatch silently DROPS the request rather than
- * reporting an unknown diagram type. Same value as the language id, so the two
- * cannot drift apart as a diagram gains element types.
- */
-export const ${upper}_DIAGRAM_TYPE = '__LANGUAGE_ID__';
-
-/** A \`__NODE_RULE__\` — the starter grammar's one named, referenceable node. */
-export const ${upper}_NODE_TYPE = \`\${DefaultTypes.NODE}:__GRAMMAR_ID__-node\`;
-
-/** A resolved \`target\` reference, drawn as a connection between two nodes. */
-export const ${upper}_EDGE_TYPE = \`\${DefaultTypes.EDGE}:__GRAMMAR_ID__-target\`;
-`;
-
-   const state = `// GLSP state for the __GRAMMAR__ diagram.
-//
-// \`FullTextHydraniumGlspState\` is the simplest of the framework source-model
-// strategies (the others project a structured transfer model, over one document
-// or several): the source model is the whole document text, serialised through
-// the per-URI \`Serializer\` and round-tripped by re-parsing. Both seams resolve
-// through shared services, so narrowing the root type is all an adopter adds.
-//
-// It cannot field-merge — every concurrent edit on a whole-document model is a
-// same-document collision, so undo / redo degrade to drop-on-divergence. Move to
-// \`ReconcilingTransferHydraniumGlspState\` when you need field-level undo.
-
-import { FullTextHydraniumGlspState } from '@hydranium/glsp-server';
-import { injectable } from 'inversify';
-import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
-
-@injectable()
-export class __GRAMMAR__GlspState extends FullTextHydraniumGlspState<__ENTRY_RULE__> {}
-`;
-
-   const storage = `// Source-model storage for the __GRAMMAR__ diagram, inheriting both framework
-// defaults: \`loadSourceModel\` (open + settle + \`setSourceRoot\`) and
-// \`saveSourceModel\` (through \`ModelService.save\` → the per-URI \`Serializer\` →
-// the multi-client text store → \`WritableFileSystemProvider\`).
-//
-// The subclass exists so a bespoke load or save has a stable place to land.
-
-import { type FullTextSourceModel, HydraniumGlspStorage } from '@hydranium/glsp-server';
-import { injectable } from 'inversify';
-import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
-
-@injectable()
-export class __GRAMMAR__GlspStorage extends HydraniumGlspStorage<__ENTRY_RULE__, FullTextSourceModel> {}
-`;
-
-   const submission = `// Submission handler for the __GRAMMAR__ diagram.
-//
-// Inherits the framework's \`readyEvent = IntegrityService.SettledState\`, which
-// is load-bearing rather than incidental: the GModel factory resolves
-// \`target.ref\`, so it needs a fully-linked AST. Without the gate those reads
-// fire mid-build and warn about resolution before scopes are computed.
-//
-// Only \`formatSourceRoot\` is overridden, so the submit log names the model and
-// its node count instead of a bare \`$type\`.
-
-import { ModelState } from '@eclipse-glsp/server';
-import { type FullTextSourceModel, HydraniumGlspSubmissionHandler } from '@hydranium/glsp-server';
-import { inject, injectable } from 'inversify';
-import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
-import type { __GRAMMAR__GlspState } from './state.js';
-
-@injectable()
-export class __GRAMMAR__SubmissionHandler extends HydraniumGlspSubmissionHandler<__ENTRY_RULE__, FullTextSourceModel> {
-   @inject(ModelState) declare protected modelState: __GRAMMAR__GlspState;
-
-   protected override formatSourceRoot(root: __ENTRY_RULE__ | undefined): string {
-      return root ? \`__ENTRY_RULE__ nodes=\${root.nodes.length}\` : 'none';
-   }
-}
-`;
-
-   const factory = `// AST → GModel for the __GRAMMAR__ diagram: one node per \`__NODE_RULE__\`, one
-// edge per resolved \`target\` reference.
-//
-// Ids come from the index rather than being composed here, so the id strategy
-// stays in one place. Nodes are emitted before edges, because a GLSP edge
-// pointing at an id that does not exist fails client-side with a far less
-// obvious error than a missing edge. An unresolved reference is SKIPPED rather
-// than treated as an error: a dangling reference is ordinary editing state, and
-// the LSP head already reports it as a diagnostic.
-
-import { DefaultTypes, GEdge, GGraph, GLabel, type GModelFactory, GNode, ModelState } from '@eclipse-glsp/server';
-import { inject, injectable } from 'inversify';
-import type { __ENTRY_RULE__ } from '../../language-server/ast.js';
-import { ${upper}_EDGE_TYPE, ${upper}_NODE_TYPE } from './types.js';
-import type { __GRAMMAR__GlspState } from './state.js';
-
-@injectable()
-export class __GRAMMAR__GModelFactory implements GModelFactory {
-   @inject(ModelState) protected readonly modelState!: __GRAMMAR__GlspState;
-
-   createModel(): void {
-      const root = this.modelState.sourceRoot;
-      const graph = GGraph.builder().id(this.modelState.sourceUri).build();
-      if (root) {
-         this.buildGraph(root, graph);
-      }
-      this.modelState.updateRoot(graph);
-   }
-
-   protected buildGraph(root: __ENTRY_RULE__, graph: GGraph): void {
-      for (const node of root.nodes) {
-         const id = this.modelState.index.createId(node);
-         graph.children.push(
-            GNode.builder()
-               .id(id)
-               .type(${upper}_NODE_TYPE)
-               .add(GLabel.builder().id(\`\${id}_name\`).text(node.name).type(DefaultTypes.LABEL).build())
-               .build()
-         );
-      }
-      for (const node of root.nodes) {
-         const target = node.target?.ref;
-         if (!target) {
-            continue;
-         }
-         const sourceId = this.modelState.index.createId(node);
-         graph.children.push(
-            GEdge.builder()
-               .id(\`\${sourceId}_target\`)
-               .type(${upper}_EDGE_TYPE)
-               .sourceId(sourceId)
-               .targetId(this.modelState.index.createId(target))
-               .build()
-         );
-      }
-   }
-}
-`;
+   const fixed = (file: string): InitFile => grammarTemplate(`server/src/glsp/__GRAMMAR_ID__/${file}`, composition, grammar);
+   const computed = (file: string, text: string): InitFile => ({
+      path: `server/src/glsp/${grammar.grammarId}/${file}`,
+      content: render(text, composition, grammar)
+   });
 
    const configuration = `// Diagram configuration for the __GRAMMAR__ diagram.
 //
@@ -1777,7 +1785,7 @@ ${importList(
    columns
 )}
 import { injectable } from 'inversify';
-import { ${upper}_EDGE_TYPE, ${upper}_NODE_TYPE } from './types.js';
+import { __GRAMMAR_ID_CONST___EDGE_TYPE, __GRAMMAR_ID_CONST___NODE_TYPE } from '__PROTOCOL_PACKAGE__';
 
 @injectable()
 export class __GRAMMAR__DiagramConfiguration implements DiagramConfiguration {
@@ -1789,7 +1797,7 @@ export class __GRAMMAR__DiagramConfiguration implements DiagramConfiguration {
 
    readonly shapeTypeHints: ShapeTypeHint[] = [
       {
-         elementTypeId: ${upper}_NODE_TYPE,
+         elementTypeId: __GRAMMAR_ID_CONST___NODE_TYPE,
          deletable: false,
          reparentable: false,
          repositionable: false,
@@ -1799,107 +1807,19 @@ export class __GRAMMAR__DiagramConfiguration implements DiagramConfiguration {
 
    readonly edgeTypeHints: EdgeTypeHint[] = [
       {
-         elementTypeId: ${upper}_EDGE_TYPE,
+         elementTypeId: __GRAMMAR_ID_CONST___EDGE_TYPE,
          deletable: false,
          repositionable: false,
          routable: false,
-         sourceElementTypeIds: [${upper}_NODE_TYPE],
-         targetElementTypeIds: [${upper}_NODE_TYPE]
+         sourceElementTypeIds: [__GRAMMAR_ID_CONST___NODE_TYPE],
+         targetElementTypeIds: [__GRAMMAR_ID_CONST___NODE_TYPE]
       }
    ];
 }
-`;
-
-   const createHandler = `// The starter operation handler for the __GRAMMAR__ diagram: the tool-palette
-// entry that creates a \`__NODE_RULE__\`.
-//
-// **Deleting this file and its \`configureOperationHandlers\` registration in
-// \`diagram-module.ts\` gives a read-only viewer**, and nothing else has to change
-// — creation is offered through the palette rather than through a type hint, so
-// every hint in \`diagram-configuration.ts\` is already \`false\`. The scaffold emits
-// the editable direction because that asymmetry runs one way: editable →
-// read-only is a deletion the compiler checks, while read-only → editable is
-// authoring against a seam you have not used yet.
-//
-// **It composes TEXT rather than mutating the AST.** The source model of
-// \`FullTextHydraniumGlspState\` is the document text, and reading it back through
-// \`state.sourceModel\` serialises the AST through the per-URI \`Serializer\`, which
-// this scaffold does not bind — so that getter throws until you do. Appending a
-// declaration to the text the parser last read needs no serializer, which is what
-// makes a scaffolded diagram editable on day one. Bind a \`Serializer\` at
-// \`services.serializer.Serializer\` and this becomes a
-// \`HydraniumGlspRecordingCommand\` over \`state.sourceModel\` instead — the same
-// binding the diagram's own save action needs.
-//
-// **The drop location is discarded.** \`needsClientLayout\` is \`true\` and the
-// starter grammar persists no bounds, so there is nowhere to put a coordinate: the
-// node is appended at the end of the document and the client places it.
-//
-// Like \`types.ts\`, \`gmodel-factory.ts\` and \`diagram-configuration.ts\`, this file
-// knows the starter grammar's concrete syntax — the \`node\` keyword below is that
-// grammar's. Replacing the grammar means replacing these four together.
-
-import { type Command, type CreateNodeOperation, JsonCreateNodeOperationHandler, type MaybePromise } from '@eclipse-glsp/server';
-import { findNextUnique } from '@hydranium/protocol';
-import { injectable } from 'inversify';
-import { ${upper}_NODE_TYPE } from './types.js';
-import type { __GRAMMAR__GlspState } from './state.js';
-
-/** Proposed name for a new node, uniquified against the ones the document already has. */
-const NODE_NAME_STEM = 'Node';
-
-@injectable()
-export class __GRAMMAR__CreateNodeOperationHandler extends JsonCreateNodeOperationHandler {
-   declare protected modelState: __GRAMMAR__GlspState;
-
-   /** The palette's word for the thing it creates, so a noun rather than an action. */
-   override readonly label = '__NODE_RULE__';
-   elementTypeIds = [${upper}_NODE_TYPE];
-
-   override createCommand(operation: CreateNodeOperation): MaybePromise<Command | undefined> {
-      if (!this.elementTypeIds.includes(operation.elementTypeId)) {
-         return undefined;
-      }
-      const state = this.modelState;
-      const before = this.documentText();
-      const after = this.withNode(
-         before,
-         findNextUnique(
-            NODE_NAME_STEM,
-            state.sourceRoot.nodes.map(node => node.name)
-         )
-      );
-      // Whole-document undo, which is all a full-text source model can offer: it
-      // has exactly one field, so there is nothing to merge a concurrent edit into.
-      return {
-         execute: () => state.updateSourceModel({ text: after }),
-         undo: () => state.updateSourceModel({ text: before }),
-         redo: () => state.updateSourceModel({ text: after })
-      };
-   }
-
-   /** The text the captured source root was parsed from — the baseline an edit appends to. */
-   protected documentText(): string {
-      return this.modelState.sourceRoot.$document?.textDocument.getText() ?? '';
-   }
-
-   /** \`text\` with one more node declaration, under exactly one trailing newline. */
-   protected withNode(text: string, name: string): string {
-      const body = text.trimEnd();
-      const declaration = \`node \${name}\`;
-      return body.length === 0 ? \`\${declaration}\\n\` : \`\${body}\\n\${declaration}\\n\`;
-   }
-}
 `;
 
    const module = `// GLSP diagram module for __GRAMMAR__ — the DI wiring of one diagram type.
 //
-// \`declareLanguage\` is the multi-grammar seam: it binds the grammar this diagram
-// edits on the SESSION container, so \`modelState.diagramLanguage\` and the
-// per-language lookups resolve to __LANGUAGE_ID__. That is what stops one
-// diagram type from fighting over a process-wide binding when a project holds
-// several grammars — a grammar with no diagram is registered on the same server.
-//
 // \`configureActionHandlers\` REBINDS rather than adds: GLSP's own
 // \`DiagramModule\` already registers \`ComputedBoundsActionHandler\`, and two
 // handlers for one action would both run.
@@ -1926,27 +1846,21 @@ ${importList(
    true
 )}
 import { ComputedBoundsActionHandler } from '@eclipse-glsp/server';
-import type { LanguageMetaData } from '@hydranium/langium';
 ${importList(
    ['HydraniumGlspComputedBoundsActionHandler', 'AbstractHydraniumGlspDiagramModule', 'HydraniumGlspIndex'],
    '@hydranium/glsp-server',
    columns
 )}
-import { __GRAMMAR__LanguageMetaData } from '../../language-server/generated/module.js';
 import { __GRAMMAR__CreateNodeOperationHandler } from './create-node-operation-handler.js';
 import { __GRAMMAR__DiagramConfiguration } from './diagram-configuration.js';
 import { __GRAMMAR__GModelFactory } from './gmodel-factory.js';
 import { __GRAMMAR__GlspState } from './state.js';
 import { __GRAMMAR__GlspStorage } from './storage.js';
 import { __GRAMMAR__SubmissionHandler } from './submission-handler.js';
-import { ${upper}_DIAGRAM_TYPE } from './types.js';
+import { __GRAMMAR_ID_CONST___DIAGRAM_TYPE } from '__PROTOCOL_PACKAGE__';
 
 export class __GRAMMAR__DiagramModule extends AbstractHydraniumGlspDiagramModule {
-   readonly diagramType = ${upper}_DIAGRAM_TYPE;
-
-   protected override declareLanguage(): LanguageMetaData {
-      return __GRAMMAR__LanguageMetaData;
-   }
+   readonly diagramType = __GRAMMAR_ID_CONST___DIAGRAM_TYPE;
 
    protected override bindModelState(): BindingTarget<ModelState> {
       return { service: __GRAMMAR__GlspState };
@@ -1986,68 +1900,83 @@ export class __GRAMMAR__DiagramModule extends AbstractHydraniumGlspDiagramModule
 `;
 
    return [
-      { path: `${dir}/types.ts`, content: render(types) },
-      { path: `${dir}/state.ts`, content: render(state) },
-      { path: `${dir}/storage.ts`, content: render(storage) },
-      { path: `${dir}/submission-handler.ts`, content: render(submission) },
-      { path: `${dir}/gmodel-factory.ts`, content: render(factory) },
-      { path: `${dir}/diagram-configuration.ts`, content: render(configuration) },
-      { path: `${dir}/create-node-operation-handler.ts`, content: render(createHandler) },
-      { path: `${dir}/diagram-module.ts`, content: render(module) }
+      fixed('state.ts'),
+      fixed('storage.ts'),
+      fixed('submission-handler.ts'),
+      fixed('gmodel-factory.ts'),
+      computed('diagram-configuration.ts', configuration),
+      fixed('create-node-operation-handler.ts'),
+      computed('diagram-module.ts', module),
+      grammarTemplate('server/test/__GRAMMAR_ID__-diagram.test.ts', composition, grammar)
    ];
 }
 
 /**
- * Every file the scaffold emits, fully rendered.
+ * The server member: the grammar, the language and its heads.
  *
  * Grammar-count-dependent emissions live here rather than in a template string:
  * one `.langium` file per grammar, and the shared `common.langium` fragment only
  * when there is more than one grammar to share it.
  */
-export function buildInitTemplates(composition: InitComposition): InitFile[] {
+function serverFiles(composition: InitComposition): InitFile[] {
    const multi = composition.grammars.length > 1;
    const grammarFiles: InitFile[] = composition.grammars.map(grammar => ({
-      path: `src/grammar/${grammar.grammarId}.langium`,
+      path: `server/src/grammar/${grammar.grammarId}.langium`,
       content: render(grammarFile(multi), composition, grammar)
    }));
+   // The shared lexical fragment, only for several grammars: each declaring its
+   // own `WS` / `ID` lets the token sets drift apart.
    if (multi) {
-      grammarFiles.unshift({ path: 'src/grammar/common.langium', content: COMMON_GRAMMAR });
+      grammarFiles.unshift(projectTemplate('server/src/grammar/common.langium', composition));
    }
 
    const diagramFiles = composition.grammars.filter(grammar => grammar.diagram).flatMap(grammar => glspFiles(composition, grammar));
 
    return [
-      { path: 'package.json', content: packageJson(composition) },
-      { path: 'langium-config.json', content: langiumConfig(composition) },
-      { path: 'tsconfig.json', content: tsconfigJson(composition) },
-      { path: 'tsconfig.test.json', content: TSCONFIG_TEST },
-      { path: 'vitest.config.ts', content: VITEST_CONFIG },
-      {
-         path: '.gitignore',
-         content: composition.packaging.workspace === undefined ? GITIGNORE : GITIGNORE_WORKSPACE_MEMBER
-      },
-      { path: 'README.md', content: readme(composition) },
+      { path: 'server/package.json', content: packageJson(composition) },
+      { path: 'server/langium-config.json', content: langiumConfig(composition) },
+      { path: 'server/tsconfig.json', content: serverTsconfigJson(composition) },
+      // `isolatedModules` is what makes this check agree with the transform that
+      // actually runs the tests. `npm test` is `typecheck:test && vitest run`, and
+      // vitest compiles each file on its own — a transform with no type
+      // information, which cannot tell a re-exported TYPE from a re-exported value.
+      // Without the flag `tsc` accepts `export { SomeType } from './x'` that the
+      // transform then emits as a real import of a symbol that does not exist at
+      // runtime, so the typecheck passes and the suite fails with a confusing
+      // missing-export.
+      projectTemplate('server/tsconfig.test.json', composition),
+      // Found by name, unlike `tsconfig.test.json`. Under vite 8, vitest's transform
+      // applies a tsconfig only to the files its own `include` lists, so without this
+      // a test declaring a decorated class fails to load.
+      projectTemplate('server/test/tsconfig.json', composition),
+      projectTemplate('server/vitest.config.ts', composition),
+      // Written for a workspace member too: its root may not ignore `lib/` (a `yo
+      // langium` root ignores `out/`), and a rule the root repeats costs nothing.
+      ignoreFile('server'),
+      { path: 'server/README.md', content: readme(composition) },
       ...grammarFiles,
-      { path: `src/language-server/${composition.projectId}-module.ts`, content: moduleFile(composition) },
-      { path: 'src/language-server/ast.ts', content: render(AST, composition, composition.grammars[0]) },
-      ...composition.grammars.map(grammar => ({
-         path: `src/language-server/${grammar.grammarId}-serializer.ts`,
-         content: render(SERIALIZER, composition, grammar)
-      })),
-      { path: 'src/index.ts', content: indexFile(composition) },
-      { path: 'src/services.ts', content: project(SERVICES, composition) },
-      { path: 'src/main.ts', content: mainFile(composition) },
-      ...(composition.heads.includes('data') ? [{ path: 'src/data-server-main.ts', content: dataServerMainFile(composition) }] : []),
-      ...(portCommandNames(composition).length ? [{ path: 'src/head-ports.ts', content: headPortsFile(composition) }] : []),
+      { path: `server/src/language-server/${composition.projectId}-module.ts`, content: moduleFile(composition) },
+      grammarTemplate('server/src/language-server/ast.ts', composition, composition.grammars[0]),
+      // Per grammar, because `services.serializer.Serializer` is a per-language slot
+      // and a serializer is grammar-shaped by definition. That is also why the
+      // framework refuses to default it: its `UnboundSerializer` throws, naming the
+      // binding to add, rather than guessing a syntax.
+      ...composition.grammars.map(grammar =>
+         grammarTemplate('server/src/language-server/__GRAMMAR_ID__-serializer.ts', composition, grammar)
+      ),
+      { path: 'server/src/index.ts', content: indexFile(composition) },
+      projectTemplate('server/src/node/services.ts', composition),
+      { path: 'server/src/main.ts', content: mainFile(composition) },
+      ...(composition.heads.includes('data') ? [{ path: 'server/src/data-server-main.ts', content: dataServerMainFile(composition) }] : []),
       ...diagramFiles,
-      { path: 'test/services.test.ts', content: servicesTest(composition) },
-      { path: 'test/parsing.test.ts', content: grammarTest(composition, PARSING_HEADER, [], PARSING_SUITE) },
+      { path: 'server/test/services.test.ts', content: servicesTest(composition) },
+      { path: 'server/test/parsing.test.ts', content: grammarTest(composition, PARSING_HEADER, [], PARSING_SUITE) },
       {
-         path: 'test/linking.test.ts',
+         path: 'server/test/linking.test.ts',
          content: grammarTest(composition, LINKING_HEADER, ["import { AstUtils } from '@hydranium/langium';"], LINKING_SUITE)
       },
       {
-         path: 'test/validating.test.ts',
+         path: 'server/test/validating.test.ts',
          content: grammarTest(
             composition,
             VALIDATING_HEADER,
@@ -2055,6 +1984,171 @@ export function buildInitTemplates(composition: InitComposition): InitFile[] {
             VALIDATING_SUITE
          )
       },
-      { path: 'test/serialization.test.ts', content: serializationTest(composition) }
+      { path: 'server/test/serialization.test.ts', content: serializationTest(composition) }
+   ];
+}
+
+/**
+ * The protocol member's `package.json`.
+ *
+ * Its `build` runs the server's `generate` first, because the server writes
+ * this package's `generated-hydranium/` modules from the grammar: a runner that
+ * builds in dependency order reaches this package before the server, and would
+ * otherwise compile modules that do not exist yet. A full build therefore
+ * generates twice; the second pass rewrites nothing.
+ */
+function protocolPackageJson(composition: InitComposition): string {
+   const member = forMember(composition, 'protocol');
+   const dependencies: Record<string, string> = {};
+   for (const head of composition.heads) {
+      Object.assign(dependencies, PROTOCOL_THIRD_PARTY_DEPENDENCIES[head]);
+   }
+   const dependencyLines =
+      Object.keys(dependencies).length === 0 ? '' : `  "dependencies": {\n${sortedBlock(dependencies, '    ')}\n  },\n`;
+   return `{
+  "name": "${memberPackageName(composition, 'protocol')}",
+  "version": "0.0.0",
+${composition.packaging.private ? '  "private": true,\n' : ''}  "description": "What the ${composition.name} language server and its clients share: language ids, wire types and diagram ids.",
+  "license": "UNLICENSED",
+  "author": "",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "npm --prefix ../server run generate && tsc -b",
+    "clean": "rimraf lib tsconfig.tsbuildinfo",
+${lintScript(member, 'src')}    "watch": "tsc -b --watch"
+  },
+${dependencyLines}  "devDependencies": {
+    "rimraf": "^5.0.0",
+    "typescript": "^7.0.2"
+  },
+  "engines": {
+    "node": ">=22.13"
+  }
+}
+`;
+}
+
+/** The protocol member's root entry, one re-export per module. */
+function protocolIndexFile(composition: InitComposition): string {
+   const modules = [
+      './generated-hydranium/languages.js',
+      './generated-hydranium/transfer-model.js',
+      ...(headPortConstants(composition).length ? ['./head-ports.js'] : []),
+      ...composition.grammars.filter(grammar => grammar.diagram).map(grammar => `./${grammar.grammarId}-diagram-types.js`)
+   ];
+   const text = `// What the __NAME__ server and its clients both import. A client depends on
+// this package instead of the server, so it never installs Langium to reach a
+// constant or a wire type.
+//
+// The server's \`generate\` writes \`generated-hydranium/\` from the grammar;
+// commit those modules with the grammar change that produced them.
+
+${modules.map(module => `export * from '${module}';`).join('\n')}
+`;
+   return project(text, composition);
+}
+
+/** The protocol member's README. */
+function protocolReadme(composition: InitComposition): string {
+   const lines = [
+      `# ${memberPackageName(composition, 'protocol')}`,
+      '',
+      'What the __NAME__ language server and its clients both import, so a client',
+      'never depends on the server or installs Langium.',
+      '',
+      '- `src/generated-hydranium/languages.ts` — each language id and its file extensions',
+      '- `src/generated-hydranium/transfer-model.ts` — the wire types of the model, references as plain strings',
+      ...(headPortConstants(composition).length === 0
+         ? []
+         : composition.heads.includes('lsp')
+           ? ['- `src/head-ports.ts` — the LSP requests a host sends to find the socket heads']
+           : ["- `src/head-ports.ts` — the environment variables naming the socket heads' ports"]),
+      ...composition.grammars
+         .filter(grammar => grammar.diagram)
+         .map(grammar => `- \`src/${grammar.grammarId}-diagram-types.ts\` — the \`${grammar.grammar}\` diagram's type ids`),
+      '',
+      "The server's `npm run generate` writes `src/generated-hydranium/` from the",
+      'grammar, and `npm run build` here runs it first. Commit the generated',
+      'modules with the grammar change that produced them.',
+      ''
+   ];
+   return project(lines.join('\n'), composition);
+}
+
+/** The protocol member: everything the server and its clients both import. */
+function protocolFiles(composition: InitComposition): InitFile[] {
+   return [
+      { path: 'protocol/package.json', content: protocolPackageJson(composition) },
+      { path: 'protocol/tsconfig.json', content: tsconfigJson(forMember(composition, 'protocol'), PROTOCOL_COMPILER_OPTIONS, '["src"]') },
+      ignoreFile('protocol'),
+      { path: 'protocol/README.md', content: protocolReadme(composition) },
+      { path: 'protocol/src/index.ts', content: protocolIndexFile(composition) },
+      ...(headPortConstants(composition).length ? [{ path: 'protocol/src/head-ports.ts', content: headPortsFile(composition) }] : []),
+      ...composition.grammars
+         .filter(grammar => grammar.diagram)
+         .map(grammar => grammarTemplate('protocol/src/__GRAMMAR_ID__-diagram-types.ts', composition, grammar))
+   ];
+}
+
+/**
+ * The starter model files every host and the CLI open, two per language: one
+ * declaring nodes, one referencing a node in the other file.
+ *
+ * Named by extension alone, since `init` refuses two grammars sharing one.
+ */
+function workspaceFiles(composition: InitComposition): InitFile[] {
+   return composition.grammars.flatMap(grammar => [
+      grammarTemplate('workspace/nodes.__EXTENSION__', composition, grammar),
+      grammarTemplate('workspace/references.__EXTENSION__', composition, grammar)
+   ]);
+}
+
+/**
+ * A standalone project's root: the members as npm workspaces.
+ *
+ * Always private: it is never published, whatever `--public` makes of the
+ * members. npm runs a script across the members in the order listed here, not
+ * by their dependencies; listing protocol first is safe because its `build`
+ * runs the server's `generate` before compiling.
+ */
+function rootFiles(composition: InitComposition): InitFile[] {
+   const content = `{
+  "name": "${composition.projectId}-root",
+  "version": "0.0.0",
+  "private": true,
+  "workspaces": [
+    "protocol",
+    "server"
+  ],
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "clean": "npm run clean --workspaces --if-present",
+    "test": "npm test --workspaces --if-present"
+  },
+  "engines": {
+    "node": ">=22.13"
+  }
+}
+`;
+   return [{ path: 'package.json', content }, ignoreFile('')];
+}
+
+/**
+ * Every file the scaffold emits, fully rendered, at its path in the project
+ * directory. A workspace member's project gets no root of its own: it joins the
+ * surrounding workspace, whose manifest `init` prints the changes for.
+ */
+export function buildInitTemplates(composition: InitComposition): InitFile[] {
+   return [
+      ...(composition.packaging.workspace === undefined ? rootFiles(composition) : []),
+      ...protocolFiles(composition),
+      ...serverFiles(composition),
+      ...workspaceFiles(composition)
    ];
 }