kopular 1.2.5 → 1.3.0

package/GUIDE.md

@@ -19,7 +19,11 @@ app.Mount(document.body);
 ```
 
 Run `npm run build && npm run serve`, or `npm start` (a scaffolded project already has
-both scripts). `ks check src/app.ks` type-checks without building, if you just want errors.
+both scripts). **Verify with one command, not two:** whatever runs your app or its tests
+builds first, and a compile failure stops it right there with every error and its `fix:`
+hint — so running a separate build before it only adds a round-trip (the build itself takes
+well under a second). `ks check src/app.ks` type-checks without building, for when you only
+want the errors.
 
 ## The language you need
 

package/bin/kp.mjs

@@ -203,6 +203,31 @@ Counter app = new Counter();
 app.Mount(document.body);
 `;
 
+// Loaded automatically at session start by AI coding agents (AGENTS.md is the
+// cross-tool convention; Claude Code reads CLAUDE.md, which imports it). Kept
+// deliberately tiny, because it sits in every request's context. Its one job is
+// routing: an agent that opens node_modules/kopular/LLM.md (~53K chars) before
+// GUIDE.md (~15K) pays for that on every call after, and benchmark transcripts
+// showed agents never read a project's README unprompted.
+const AGENTS_MD_TEMPLATE = `# Notes for AI coding agents
+
+This app is KopScript + Kopular: a typed language that compiles to JavaScript, and is
+probably not in your training data.
+
+- **Read \`node_modules/kopular/GUIDE.md\` first**, in full: one page covering the language
+  subset, components, templates, forms, HTTP and routing. Search the much longer
+  \`node_modules/kopular/LLM.md\` and \`node_modules/kopscript/LLM.md\` only for what it
+  doesn't cover.
+- **Check your work with one command.** \`npm run build\` compiles \`src/app.ks\` and every file
+  it \`using\`s in well under a second and prints every error with a \`fix:\` hint. Anything
+  that runs the app or its tests builds first, so don't run a separate build before it.
+- Kopular's source in \`node_modules\` isn't its documentation — try GUIDE.md, the compiler's
+  hint, then the LLM.md references before reading it.
+`;
+
+const CLAUDE_MD_TEMPLATE = `@AGENTS.md
+`;
+
 function scaffoldProject(dirPath) {
   const name = basename(dirPath);
   if (existsSync(dirPath) && readdirSync(dirPath).length > 0) {
@@ -218,6 +243,8 @@ function scaffoldProject(dirPath) {
   writeFileSync(join(dirPath, "index.html"), indexHtmlTemplate(), "utf-8");
   writeFileSync(join(dirPath, ".gitignore"), GITIGNORE_TEMPLATE, "utf-8");
   writeFileSync(join(dirPath, "README.md"), readmeTemplate(name), "utf-8");
+  writeFileSync(join(dirPath, "AGENTS.md"), AGENTS_MD_TEMPLATE, "utf-8");
+  writeFileSync(join(dirPath, "CLAUDE.md"), CLAUDE_MD_TEMPLATE, "utf-8");
   writeFileSync(join(dirPath, "scripts", "serve.mjs"), SERVE_MJS_TEMPLATE, "utf-8");
   writeFileSync(join(dirPath, "scripts", "vendor-kopular.mjs"), VENDOR_KOPULAR_MJS_TEMPLATE, "utf-8");
   writeFileSync(join(dirPath, "src", "counter.ks"), COUNTER_KS_TEMPLATE, "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kopular",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "description": "Kopular: a small component framework for KopScript — components, reactive state, constructor-injected services, routing, real compiled templates, and HTTP, with no DI container",
   "type": "module",
   "license": "MIT",