create-foldkit-app 0.10.0 → 0.10.1

package/dist/commands/create.js

@@ -81,12 +81,15 @@ const displaySuccessMessage = (name, packageManager) => Effect.gen(function* ()
     yield* Console.log('');
     yield* Console.log(chalk.bold('AI-Assisted Development'));
     yield* Console.log('');
-    yield* Console.log('  Clone Foldkit as a submodule so your AI assistant can\n' +
-        '  reference the source, examples, and documentation:');
+    yield* Console.log('  Vendor Foldkit in as a git subtree so your AI assistant can\n' +
+        '  reference the source, examples, and documentation. Commit\n' +
+        '  the scaffold first so subtree has a base commit to merge into:');
     yield* Console.log('');
     yield* Console.log(`  > ${chalk.cyan('cd')} ${name}`);
     yield* Console.log(`  > ${chalk.cyan('git init')}`);
-    yield* Console.log(`  > ${chalk.cyan('git submodule add https://github.com/foldkit/foldkit.git repos/foldkit')}`);
+    yield* Console.log(`  > ${chalk.cyan('git add .')}`);
+    yield* Console.log(`  > ${chalk.cyan('git commit -m "chore: initial commit"')}`);
+    yield* Console.log(`  > ${chalk.cyan('git subtree add --prefix=repos/foldkit https://github.com/foldkit/foldkit.git main --squash')}`);
     yield* Console.log('');
     yield* Console.log(`  Details: ${chalk.cyan('foldkit.dev/ai/overview')}`);
     yield* Console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-foldkit-app",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Create Foldkit applications",
   "type": "module",
   "main": "./dist/index.js",

package/templates/base/AGENTS.md

@@ -2,11 +2,11 @@
 
 This is a Foldkit app — a framework built on Effect-TS.
 
-If `./repos/foldkit` exists, it contains the full Foldkit repository as a git submodule. The `examples/` directory and `packages/typing-game/client/src/` in particular are the best reference for what idiomatic Foldkit apps look like.
+If `./repos/foldkit` exists, it contains the full Foldkit repository, vendored in as a git subtree. The `examples/` directory and `packages/typing-game/client/src/` in particular are the best reference for what idiomatic Foldkit apps look like. Treat the subtree as read-only reference: never import from `repos/foldkit/` in your project source. Imports must come from the `foldkit` npm package.
 
-If `./repos/foldkit` does not exist and the line below says `submodule_prompted: false`, offer to run `git submodule add https://github.com/foldkit/foldkit.git repos/foldkit` — this gives you access to the full source, examples, and docs. Whether the user accepts or declines, update the value to `true` so it isn't asked again.
+If `./repos/foldkit` does not exist and the line below says `subtree_prompted: false`, offer to run `git subtree add --prefix=repos/foldkit https://github.com/foldkit/foldkit.git main --squash`. This gives you access to the full source, examples, and docs. Whether the user accepts or declines, update the value to `true` so it isn't asked again.
 
-submodule_prompted: false
+subtree_prompted: false
 
 ## Project Conventions
 
@@ -133,6 +133,8 @@ Don't reach for Mount just because the work happens to coincide with an element
 
 ### File Organization
 
+A Foldkit app lives in two files. `src/main.ts` holds the pure definitions: Model, Messages, init, update, view. `src/entry.ts` imports them and boots the runtime with `Runtime.makeProgram` and `Runtime.run`. `index.html` references `entry.ts`. The split keeps `main.ts` importable from tests without booting a runtime as a side effect. Never call `Runtime.run` from `main.ts`.
+
 Use uppercase section headers (`// MODEL`, `// MESSAGE`, `// INIT`, `// UPDATE`, `// COMMAND`, `// VIEW`) to make files easier to skim. These are for wayfinding — they make it clear where things live and where new code should go. Use domain-specific headers too when it helps (e.g. `// PHYSICS`, `// ROUTING`).
 
 Even after extracting some sections to their own files (e.g. `message.ts`), the remaining file may still benefit from headers. Extract to separate files when it helps with organization.
@@ -143,7 +145,7 @@ Test update functions with `foldkit/test`. Since update is pure — `(Model, Mes
 
 Use `Story.story` to chain steps into a readable narrative: set initial Model → send Message → assert → resolve Command → assert again. Use `Scene.scene` for feature-level testing through the view — clicking buttons, typing into inputs, pressing keys — with accessible locators (`Scene.role`, `Scene.label`, `Scene.placeholder`). Every `Command.define` must include result Message schemas so Commands can be resolved in tests.
 
-If the `repos/foldkit` submodule is available, study the `.test.ts` files in `repos/foldkit/examples/` for patterns — they cover simple Command resolution, multi-step interactions, and Submodel OutMessage assertions.
+If the `repos/foldkit` subtree is available, study the `.test.ts` files in `repos/foldkit/examples/` for patterns — they cover simple Command resolution, multi-step interactions, and Submodel OutMessage assertions.
 
 ## Debugging with Foldkit DevTools
 

package/templates/base/index.html

@@ -8,6 +8,6 @@
   </head>
   <body>
     <div id="root"></div>
-    <script type="module" src="./src/main.ts"></script>
+    <script type="module" src="./src/entry.ts"></script>
   </body>
 </html>

package/templates/base/vite.config.ts

@@ -5,6 +5,6 @@ import { defineConfig } from 'vite'
 export default defineConfig({
   plugins: [tailwindcss(), foldkit({ devToolsMcpPort: 9988 })],
   optimizeDeps: {
-    entries: ['src/main.ts'],
+    entries: ['src/entry.ts'],
   },
 })