kopular 1.2.6 → 1.3.1

package/GUIDE.md

@@ -25,6 +25,12 @@ hint — so running a separate build before it only adds a round-trip (the build
 well under a second). `ks check src/app.ks` type-checks without building, for when you only
 want the errors.
 
+**A fresh `kp new` project's `src/` is exactly three files, all shown in this guide:**
+`app.ks` (the block above), `counter.ks` (the `Counter` class under Components, plus
+`using "kopular";`), and `counter.html` (its template, right below it). `index.html` already
+maps every Kopular module and never needs editing. There's nothing else to discover — read
+the task, then write your files.
+
 ## The language you need
 
 - `Type name = value;` for every local — no `let`/`var`, no inference on declarations.

package/bin/kp.mjs

@@ -180,15 +180,8 @@ const COUNTER_KS_TEMPLATE = `using "kopular";
 
 class Counter : Component {
   public state<number> Count;
-
-  constructor() : base() {
-    this.Count = state(0);
-  }
-
-  public void Increment() {
-    this.Count.Value = this.Count.Value + 1;
-  }
-
+  constructor() : base() { this.Count = state(0); }
+  public void Increment() { this.Count.Value = this.Count.Value + 1; }
   template from "./counter.html";
 }
 `;
@@ -203,6 +196,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 +236,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.6",
+  "version": "1.3.1",
   "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",