@volter/twin-standard 1.0.127 → 1.0.129

package/dist/src/create-pack.d.ts

@@ -31,7 +31,6 @@ export declare function packIndexFile(dir: string, vendor: string): string;
 export declare function serverFile(vendor: string, grpc: boolean, wire?: boolean): string;
 /** A pack's tsconfig.json, a fixed file: what the grade's typecheck (soundness) compiles, the pack and its lanes. */
 export declare const TSCONFIG: string;
-/** The fixed files of a new pack, by path, for a vendor: what nobody should write by hand. */
 export declare function initFiles(vendor: string): Record<string, string>;
 /** The fixed files of a pack of lanes (Cloudflare's API and R2, Sigstore's Fulcio and Rekor): each lane a derived
  *  surface of its own under `<lane>/src`, keeping the vendor's one store and sharing its `src/semantics/shared.ts`, and the

package/dist/src/create-pack.js

@@ -361,6 +361,43 @@ export const TSCONFIG = `${JSON.stringify({
     exclude: ['node_modules'],
 }, null, 2)}\n`;
 /** The fixed files of a new pack, by path, for a vendor: what nobody should write by hand. */
+function customerReadme(vendor) {
+    return `# @volter/twin-${vendor}
+
+FILL: the customer outcome this twin enables with the vendor's unchanged SDK.
+
+## Use it in a World
+
+Choose this package's exact release in the [catalog](https://world.volter.ai/twins/${vendor}).
+Its Setup tab supplies release-specific installation and World initialization commands.
+Review the selected vendor, retain its package/version and lockfile, and run the app through
+the World. [First local World](https://world-docs.volter.ai/docs/getting-started) explains the shared workflow.
+
+## SDK workflow
+
+FILL: the public vendor quickstart, pinned SDK/API versions and methods used by journeys/first-use.json.
+FILL: a short unchanged-SDK example with asserted returned data and its expected result.
+FILL: normal environment names, structurally valid throwaway credentials, required backing and API-created prerequisites.
+
+## Data and behavior
+
+FILL: what is synthetic stored state, what is a scenario or labeled stub, and how to inspect the result.
+FILL: the workflow's stop/resume and reset behavior; state any non-applicable retained-readback scope.
+Do not use real vendor credentials for local substitution.
+
+## Scope and limits
+
+FILL: supported customer operations and explicit gaps; generated surface counts are not a full SDK claim.
+FILL: limitations specific to this vendor (for example model quality, real delivery or unsupported APIs).
+The catalog's Evidence tab records actual measured journeys and their exact tool versions.
+
+## Package facts
+
+Protocol 3; vendor specification in spec/, provenance in spec/SOURCE.md.
+FILL: license, Node requirement, kernel compatibility and the public issue tracker from package.json.
+Contributor mechanics belong to the [pack procedure](https://world-docs.volter.ai/docs/contributing/architecture#creating-a-pack).
+`;
+}
 export function initFiles(vendor) {
     const Name = pascal(vendor);
     const semantics = `${Name[0].toLowerCase()}${Name.slice(1)}Semantics`;
@@ -371,7 +408,7 @@ export function initFiles(vendor) {
             peerDependencies: { '@volter/world-core': '*' }, engines: { node: '>=22.3' },
         }, null, 2)}\n`,
         'tsconfig.json': TSCONFIG,
-        'README.md': `# @volter/twin-${vendor}\n\nThe ${vendor} twin (Protocol 3). Its surface is derived from the vendor's spec (\`spec/\`, provenance in\n\`spec/SOURCE.md\`); what it serves and why is its manifest and semantics.\n\nRules, layout and tools: twin-world's architecture ("Protocol 3", "The catalog: where twins come from").\n`,
+        'README.md': customerReadme(vendor),
         'journeys/demand.json': `${JSON.stringify({ measured: 'FILL: when and how the applications were read', applications: [] }, null, 1)}\n`,
         // Deliberately incomplete: the author supplies the SDK entry with the outline, before semantics. Keeping the file
         // present prevents a new vendor from falling back to an older standard fixture; empty commands cannot qualify.
@@ -401,7 +438,7 @@ export function laneInitFiles(vendor, lanes) {
     const single = initFiles(vendor);
     const files = {
         'package.json': single['package.json'].replace('"spec",', lanes.map((l) => `"${l}",`).join('\n    ')),
-        'README.md': `# @volter/twin-${vendor}\n\nThe ${vendor} twin (Protocol 3), one lane per API: ${lanes.map((l) => `\`${l}/\``).join(', ')}, each derived from its own spec\n(\`<lane>/spec/\`, provenance in its SOURCE.md). FILL: what each lane is of.\n`,
+        'README.md': customerReadme(vendor).replace('Protocol 3; vendor specification in spec/, provenance in spec/SOURCE.md.', `Protocol 3; API lanes: ${lanes.map(l => `\`${l}/\``).join(', ')}. Vendor specifications and provenance live in each lane's spec/ and spec/SOURCE.md. FILL: the customer scope of each lane.`),
         'journeys/demand.json': single['journeys/demand.json'],
         'journeys/first-use.json': single['journeys/first-use.json'],
         'tsconfig.json': TSCONFIG,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/twin-standard",
-  "version": "1.0.127",
+  "version": "1.0.129",
   "description": "The Protocol 3 standard for Volter twin packs: the criteria a pack is graded by, the grader, the gate a pack repository and the twin catalog run on every change and submission, and the spec derivation the grade checks against. Pin a version: every place a pack is judged judges by that standard.",
   "keywords": [
     "twin",
@@ -75,7 +75,7 @@
     "yaml": "2.9.0"
   },
   "peerDependencies": {
-    "@volter/world-core": "3.0.135",
+    "@volter/world-core": "3.0.137",
     "@volter/world-runtime": "*",
     "playwright": "^1.63.0"
   },

package/src/create-pack.ts

@@ -352,6 +352,44 @@ export const TSCONFIG = `${JSON.stringify({
 }, null, 2)}\n`;
 
 /** The fixed files of a new pack, by path, for a vendor: what nobody should write by hand. */
+function customerReadme(vendor: string): string {
+  return `# @volter/twin-${vendor}
+
+FILL: the customer outcome this twin enables with the vendor's unchanged SDK.
+
+## Use it in a World
+
+Choose this package's exact release in the [catalog](https://world.volter.ai/twins/${vendor}).
+Its Setup tab supplies release-specific installation and World initialization commands.
+Review the selected vendor, retain its package/version and lockfile, and run the app through
+the World. [First local World](https://world-docs.volter.ai/docs/getting-started) explains the shared workflow.
+
+## SDK workflow
+
+FILL: the public vendor quickstart, pinned SDK/API versions and methods used by journeys/first-use.json.
+FILL: a short unchanged-SDK example with asserted returned data and its expected result.
+FILL: normal environment names, structurally valid throwaway credentials, required backing and API-created prerequisites.
+
+## Data and behavior
+
+FILL: what is synthetic stored state, what is a scenario or labeled stub, and how to inspect the result.
+FILL: the workflow's stop/resume and reset behavior; state any non-applicable retained-readback scope.
+Do not use real vendor credentials for local substitution.
+
+## Scope and limits
+
+FILL: supported customer operations and explicit gaps; generated surface counts are not a full SDK claim.
+FILL: limitations specific to this vendor (for example model quality, real delivery or unsupported APIs).
+The catalog's Evidence tab records actual measured journeys and their exact tool versions.
+
+## Package facts
+
+Protocol 3; vendor specification in spec/, provenance in spec/SOURCE.md.
+FILL: license, Node requirement, kernel compatibility and the public issue tracker from package.json.
+Contributor mechanics belong to the [pack procedure](https://world-docs.volter.ai/docs/contributing/architecture#creating-a-pack).
+`;
+}
+
 export function initFiles(vendor: string): Record<string, string> {
   const Name = pascal(vendor);
   const semantics = `${Name[0]!.toLowerCase()}${Name.slice(1)}Semantics`;
@@ -362,7 +400,7 @@ export function initFiles(vendor: string): Record<string, string> {
       peerDependencies: { '@volter/world-core': '*' }, engines: { node: '>=22.3' },
     }, null, 2)}\n`,
     'tsconfig.json': TSCONFIG,
-    'README.md': `# @volter/twin-${vendor}\n\nThe ${vendor} twin (Protocol 3). Its surface is derived from the vendor's spec (\`spec/\`, provenance in\n\`spec/SOURCE.md\`); what it serves and why is its manifest and semantics.\n\nRules, layout and tools: twin-world's architecture ("Protocol 3", "The catalog: where twins come from").\n`,
+    'README.md': customerReadme(vendor),
     'journeys/demand.json': `${JSON.stringify({ measured: 'FILL: when and how the applications were read', applications: [] }, null, 1)}\n`,
     // Deliberately incomplete: the author supplies the SDK entry with the outline, before semantics. Keeping the file
     // present prevents a new vendor from falling back to an older standard fixture; empty commands cannot qualify.
@@ -393,7 +431,7 @@ export function laneInitFiles(vendor: string, lanes: string[]): Record<string, s
   const single = initFiles(vendor);
   const files: Record<string, string> = {
     'package.json': single['package.json']!.replace('"spec",', lanes.map((l) => `"${l}",`).join('\n    ')),
-    'README.md': `# @volter/twin-${vendor}\n\nThe ${vendor} twin (Protocol 3), one lane per API: ${lanes.map((l) => `\`${l}/\``).join(', ')}, each derived from its own spec\n(\`<lane>/spec/\`, provenance in its SOURCE.md). FILL: what each lane is of.\n`,
+    'README.md': customerReadme(vendor).replace('Protocol 3; vendor specification in spec/, provenance in spec/SOURCE.md.', `Protocol 3; API lanes: ${lanes.map(l => `\`${l}/\``).join(', ')}. Vendor specifications and provenance live in each lane's spec/ and spec/SOURCE.md. FILL: the customer scope of each lane.`),
     'journeys/demand.json': single['journeys/demand.json']!,
     'journeys/first-use.json': single['journeys/first-use.json']!,
     'tsconfig.json': TSCONFIG,