create-koppajs 1.0.0 → 1.1.0

package/bin/create-koppajs.js

@@ -1,175 +1,201 @@
-#!/usr/bin/env node
-
-import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, statSync } from "node:fs";
-import { basename, join, dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { createInterface } from "node:readline";
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const TEMPLATE_DIR = join(__dirname, "..", "template");
-const CLI_PKG = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
-
-// ── Args ────────────────────────────────────────────────────────────
-
-function parseArgs(argv) {
-  const raw = argv.slice(2);
-  return {
-    help: raw.includes("--help") || raw.includes("-h"),
-    version: raw.includes("--version") || raw.includes("-v"),
-    projectName: raw.find((a) => !a.startsWith("-")) || null,
-  };
-}
-
-// ── Help / Version ──────────────────────────────────────────────────
-
-function printHelp() {
-  console.log(`
-  create-koppajs v${CLI_PKG.version}
-
-  Scaffold a new KoppaJS project.
-
-  Usage:
-    pnpm create koppajs [project-name]
-    npm create koppajs [project-name]
-    npx create-koppajs [project-name]
-
-  Options:
-    --help, -h       Show this help message
-    --version, -v    Show version number
-
-  Example:
-    pnpm create koppajs my-app
-`);
-}
-
-function printVersion() {
-  console.log(CLI_PKG.version);
-}
-
-// ── Prompt ──────────────────────────────────────────────────────────
-
-function promptProjectName() {
-  return new Promise((res, rej) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    let answered = false;
-    rl.on("close", () => {
-      if (!answered) rej(new Error("Input closed before a project name was provided."));
-    });
-    rl.question("  Project name: ", (answer) => {
-      answered = true;
-      rl.close();
-      res(answer.trim());
-    });
-  });
-}
-
-// ── Validation ──────────────────────────────────────────────────────
-
-function validateProjectName(name) {
-  if (!name) {
-    console.error("\n  Error: Project name cannot be empty.\n");
-    process.exit(1);
-  }
-  if (name === "." || name === "..") {
-    console.error(`\n  Error: Invalid project name "${name}".\n`);
-    process.exit(1);
-  }
-  if (name.includes("/") || name.includes("\\")) {
-    console.error("\n  Error: Project name must not contain path separators.\n");
-    process.exit(1);
-  }
-}
-
-// ── Target directory ────────────────────────────────────────────────
-
-function ensureTargetDir(targetPath) {
-  if (existsSync(targetPath) && readdirSync(targetPath).length > 0) {
-    console.error(`\n  Error: Directory "${basename(targetPath)}" already exists and is not empty.\n`);
-    process.exit(1);
-  }
-  mkdirSync(targetPath, { recursive: true });
-}
-
-// ── Copy ────────────────────────────────────────────────────────────
-
-// npm excludes .gitignore from published packages — ship as _gitignore
-// and rename during scaffolding (same approach as create-vite).
-const RENAME_FILES = { _gitignore: ".gitignore" };
-
-function copyDirRecursive(src, dest) {
-  mkdirSync(dest, { recursive: true });
-  for (const entry of readdirSync(src)) {
-    const srcPath = join(src, entry);
-    const destName = RENAME_FILES[entry] || entry;
-    const destPath = join(dest, destName);
-    if (statSync(srcPath).isDirectory()) {
-      copyDirRecursive(srcPath, destPath);
-    } else {
-      copyFileSync(srcPath, destPath);
-    }
-  }
-}
-
-// ── Patch package.json ──────────────────────────────────────────────
-
-function patchPackageJson(destDir, projectName) {
-  const pkgPath = join(destDir, "package.json");
-  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-  pkg.name = projectName;
-  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
-}
-
-// ── Patch README ────────────────────────────────────────────────────
-
-function patchReadme(destDir, projectName) {
-  const readmePath = join(destDir, "README.md");
-  let content = readFileSync(readmePath, "utf-8");
-  content = content.replaceAll("__PROJECT_NAME__", projectName);
-  writeFileSync(readmePath, content);
-}
-
-// ── Final output ────────────────────────────────────────────────────
-
-function printNextSteps(projectName) {
-  console.log("  Done! Next steps:\n");
-  console.log(`    cd ${projectName}`);
-  console.log("    pnpm install");
-  console.log("    pnpm dev\n");
-}
-
-// ── Main ────────────────────────────────────────────────────────────
-
-async function main() {
-  const { help, version, projectName: argName } = parseArgs(process.argv);
-
-  if (help) {
-    printHelp();
-    process.exit(0);
-  }
-
-  if (version) {
-    printVersion();
-    process.exit(0);
-  }
-
-  const projectName = argName || (await promptProjectName());
-
-  validateProjectName(projectName);
-
-  const targetDir = resolve(process.cwd(), projectName);
-
-  ensureTargetDir(targetDir);
-
-  console.log(`\n  Scaffolding KoppaJS project: ${projectName}\n`);
-
-  copyDirRecursive(TEMPLATE_DIR, targetDir);
-  patchPackageJson(targetDir, projectName);
-  patchReadme(targetDir, projectName);
-  printNextSteps(projectName);
-}
-
-main().catch((err) => {
-  console.error(`\n  Error: ${err.message}\n`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, copyFileSync, statSync } from "node:fs";
+import { basename, join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+export const TEMPLATE_DIR = join(__dirname, "..", "template");
+const CLI_PKG = JSON.parse(readFileSync(join(__dirname, "..", "package.json"), "utf-8"));
+
+// ── Args ────────────────────────────────────────────────────────────
+
+export function parseArgs(argv) {
+  const raw = argv.slice(2);
+  return {
+    help: raw.includes("--help") || raw.includes("-h"),
+    version: raw.includes("--version") || raw.includes("-v"),
+    projectName: raw.find((a) => !a.startsWith("-")) || null,
+  };
+}
+
+// ── Help / Version ──────────────────────────────────────────────────
+
+export function printHelp() {
+  console.log(`
+  create-koppajs v${CLI_PKG.version}
+
+  Scaffold a new KoppaJS project.
+
+  Usage:
+    pnpm create koppajs [project-name]
+    npm create koppajs [project-name]
+    npx create-koppajs [project-name]
+
+  Options:
+    --help, -h       Show this help message
+    --version, -v    Show version number
+
+  Example:
+    pnpm create koppajs my-app
+`);
+}
+
+export function printVersion() {
+  console.log(CLI_PKG.version);
+}
+
+// ── Prompt ──────────────────────────────────────────────────────────
+
+export function promptProjectName() {
+  return new Promise((res, rej) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let answered = false;
+    rl.on("close", () => {
+      if (!answered) rej(new Error("Input closed before a project name was provided."));
+    });
+    rl.question("  Project name: ", (answer) => {
+      answered = true;
+      rl.close();
+      res(answer.trim());
+    });
+  });
+}
+
+// ── Validation ──────────────────────────────────────────────────────
+
+export function validateProjectName(name) {
+  if (!name) {
+    throw new Error("Project name cannot be empty.");
+  }
+  if (name === "." || name === "..") {
+    throw new Error(`Invalid project name "${name}".`);
+  }
+  if (name.includes("/") || name.includes("\\")) {
+    throw new Error("Project name must not contain path separators.");
+  }
+}
+
+// ── Target directory ────────────────────────────────────────────────
+
+export function ensureTargetDir(targetPath) {
+  if (existsSync(targetPath) && readdirSync(targetPath).length > 0) {
+    throw new Error(`Directory "${basename(targetPath)}" already exists and is not empty.`);
+  }
+  mkdirSync(targetPath, { recursive: true });
+}
+
+// ── Copy ────────────────────────────────────────────────────────────
+
+// npm excludes .gitignore from published packages — ship as _gitignore
+// and rename during scaffolding (same approach as create-vite).
+const RENAME_FILES = {
+  _editorconfig: ".editorconfig",
+  _gitattributes: ".gitattributes",
+  _github: ".github",
+  _gitignore: ".gitignore",
+  _husky: ".husky",
+  _npmrc: ".npmrc",
+  _prettierignore: ".prettierignore",
+};
+
+export function copyDirRecursive(src, dest) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src)) {
+    const srcPath = join(src, entry);
+    const destName = RENAME_FILES[entry] || entry;
+    const destPath = join(dest, destName);
+    if (statSync(srcPath).isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// ── Patch package.json ──────────────────────────────────────────────
+
+export function patchPackageJson(destDir, projectName) {
+  const pkgPath = join(destDir, "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  pkg.name = projectName;
+  writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+
+// ── Patch README ────────────────────────────────────────────────────
+
+function patchTextFile(destDir, relativePath, projectName) {
+  const filePath = join(destDir, relativePath);
+  let content = readFileSync(filePath, "utf-8");
+  content = content.replaceAll("__PROJECT_NAME__", projectName);
+  writeFileSync(filePath, content);
+}
+
+export function patchReadme(destDir, projectName) {
+  patchTextFile(destDir, "README.md", projectName);
+}
+
+export function patchChangelog(destDir, projectName) {
+  patchTextFile(destDir, "CHANGELOG.md", projectName);
+}
+
+export function patchReleaseNotes(destDir, projectName) {
+  patchTextFile(destDir, "RELEASE.md", projectName);
+}
+
+// ── Final output ────────────────────────────────────────────────────
+
+export function printNextSteps(projectName) {
+  console.log("  Done! Next steps:\n");
+  console.log(`    cd ${projectName}`);
+  console.log("    pnpm install");
+  console.log("    pnpm dev\n");
+}
+
+// ── Main ────────────────────────────────────────────────────────────
+
+export async function runCli(argv = process.argv, cwd = process.cwd()) {
+  const { help, version, projectName: argName } = parseArgs(argv);
+
+  if (help) {
+    printHelp();
+    return 0;
+  }
+
+  if (version) {
+    printVersion();
+    return 0;
+  }
+
+  const projectName = argName || (await promptProjectName());
+
+  validateProjectName(projectName);
+
+  const targetDir = resolve(cwd, projectName);
+
+  ensureTargetDir(targetDir);
+
+  console.log(`\n  Scaffolding KoppaJS project: ${projectName}\n`);
+
+  copyDirRecursive(TEMPLATE_DIR, targetDir);
+  patchPackageJson(targetDir, projectName);
+  patchReadme(targetDir, projectName);
+  patchChangelog(targetDir, projectName);
+  patchReleaseNotes(targetDir, projectName);
+  printNextSteps(projectName);
+
+  return 0;
+}
+
+function isDirectExecution() {
+  return Boolean(process.argv[1]) && resolve(process.argv[1]) === __filename;
+}
+
+if (isDirectExecution()) {
+  runCli().catch((err) => {
+    console.error(`\n  Error: ${err.message}\n`);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,34 +1,54 @@
-{
-  "name": "create-koppajs",
-  "version": "1.0.0",
-  "private": false,
-  "type": "module",
-  "description": "Scaffold a new KoppaJS project in seconds.",
-  "bin": {
-    "create-koppajs": "./bin/create-koppajs.js"
-  },
-  "files": [
-    "bin",
-    "template",
-    "README.md",
-    "LICENSE"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "lint": "node -c bin/create-koppajs.js",
-    "test": "node ./bin/create-koppajs.js --help",
-    "smoke": "node scripts/smoke-test.mjs"
-  },
-  "author": "Bastian Bensch",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/koppajs/create-koppajs"
-  },
-  "homepage": "https://github.com/koppajs/create-koppajs#readme",
-  "bugs": {
-    "url": "https://github.com/koppajs/create-koppajs/issues"
-  }
-}
+{
+  "name": "create-koppajs",
+  "version": "1.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Scaffold a new KoppaJS project in seconds.",
+  "bin": {
+    "create-koppajs": "./bin/create-koppajs.js"
+  },
+  "files": [
+    "bin",
+    "template",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "packageManager": "pnpm@10.12.1",
+  "engines": {
+    "node": ">=20",
+    "pnpm": ">=10"
+  },
+  "scripts": {
+    "check:meta": "node scripts/check-meta-layer.mjs",
+    "lint": "node scripts/lint.mjs",
+    "format:check": "node scripts/format-check.mjs",
+    "check:cli": "node ./bin/create-koppajs.js --help && node ./bin/create-koppajs.js --version",
+    "test:unit": "node scripts/run-unit-tests.mjs",
+    "test:watch": "node scripts/run-unit-tests.mjs --watch",
+    "test:smoke": "node scripts/smoke-test.mjs",
+    "test:template-build": "node scripts/template-build-test.mjs",
+    "test": "npm run test:unit && npm run test:smoke",
+    "pack:dry-run": "npm pack --dry-run",
+    "check": "npm run check:meta && npm run lint && npm run format:check && npm run check:cli && npm test && npm run pack:dry-run",
+    "release:check": "npm run check && npm run test:template-build",
+    "prepare": "husky",
+    "clean": "node scripts/clean.mjs"
+  },
+  "author": "Bastian Bensch",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/koppajs/create-koppajs"
+  },
+  "homepage": "https://github.com/koppajs/create-koppajs#readme",
+  "bugs": {
+    "url": "https://github.com/koppajs/create-koppajs/issues"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.1.0",
+    "@commitlint/config-conventional": "^20.0.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^16.3.3"
+  }
+}

package/template/AI_CONSTITUTION.md

@@ -0,0 +1,50 @@
+# AI Constitution
+
+## Purpose
+
+This repository is a KoppaJS starter scaffolded from the official minimal Vite
+and TypeScript baseline. Its job is to stay small, understandable, runnable,
+and trustworthy.
+
+## Core principles
+
+- Optimize for clarity over feature breadth.
+- Keep the bootstrap path obvious: one HTML shell, one TypeScript entrypoint, one root view.
+- Prefer published npm packages over local `file:` links in this repository.
+- Keep the starter close to real production usage, but do not turn it into a framework showcase.
+- Treat the meta layer as part of the product. If architecture or workflow changes, the documentation must change in the same update.
+
+## Architectural philosophy
+
+- `index.html` is the static document shell only.
+- `src/main.ts` is the only bootstrap module and the only place that registers root-level components with `Core.take(...)`.
+- `.kpa` files are the primary unit for simple UI composition, local state, and component-scoped styling.
+- When logic becomes reusable, branch-heavy, or worth unit testing, extract it from `.kpa` blocks into `.ts` modules.
+- Global CSS stays minimal. Component visuals belong inside component-local CSS blocks unless they are true application-wide primitives.
+
+## Collaboration rules for humans and AI
+
+1. Read [DECISION_HIERARCHY.md](./DECISION_HIERARCHY.md), [ARCHITECTURE.md](./ARCHITECTURE.md), [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md), [TESTING_STRATEGY.md](./TESTING_STRATEGY.md), and any relevant spec or ADR before editing code.
+2. Follow `spec -> quality plan -> implementation -> documentation` for any non-trivial change.
+3. Do not silently change public component tags, bootstrap flow, dependency sourcing, or the starter's setup instructions.
+4. Prefer existing repository patterns over inventing new structure.
+5. If a change affects architecture, module boundaries, build tooling, testing, or contributor workflow, update the meta layer in the same change.
+6. Record durable architectural decisions in `docs/adr/`.
+7. If code and documentation disagree, resolve the mismatch before merging further changes.
+
+## Change triggers
+
+- New subsystem or folder: update [ARCHITECTURE.md](./ARCHITECTURE.md) and [docs/architecture/module-boundaries.md](./docs/architecture/module-boundaries.md).
+- New enduring technical decision: add or update an ADR in [docs/adr](./docs/adr).
+- New development convention: update [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md).
+- New quality gate or test level: update [TESTING_STRATEGY.md](./TESTING_STRATEGY.md) and [docs/quality/quality-gates.md](./docs/quality/quality-gates.md).
+- New user-visible capability: create or update a spec in [docs/specs](./docs/specs).
+
+## Definition of done
+
+A change is not complete until:
+
+- the code or docs are aligned with the actual repository state,
+- applicable specs and ADRs are updated,
+- required quality checks have run,
+- contributor-facing guidance still matches the project.

package/template/ARCHITECTURE.md

@@ -0,0 +1,86 @@
+# Architecture
+
+This repository is a minimal KoppaJS application starter. It intentionally demonstrates a small end-to-end path: HTML shell, TypeScript bootstrap, a root KoppaJS view, and a single interactive child component. The repository also carries a small quality and release automation layer so the starter stays runnable, trustworthy, and maintainable as it evolves.
+
+## System overview
+
+- `index.html` provides the document shell, loads global CSS, declares the `<app-view>` root element, and imports the TypeScript entrypoint.
+- `src/main.ts` imports `@koppajs/koppajs-core`, registers local components with `Core.take(...)`, and invokes `Core()` exactly once to bootstrap the app.
+- `src/app-view.kpa` is the root UI shell. It arranges the page and composes the interactive example component.
+- `src/counter-component.kpa` is the example stateful leaf component. It owns its own `count` state and button event handlers.
+- `src/style.css` contains the global reset only.
+- `public/` contains static assets referenced by the HTML shell or components.
+- `vite.config.mjs` wires the KoppaJS Vite plugin into the build and applies a small repo-local compatibility transform so `.kpa` files are emitted as valid ES modules.
+- `vitest.config.mjs` reuses the Vite config so unit and integration tests exercise the same `.kpa` loading path as the application.
+- `playwright.config.ts` runs a Chromium smoke test against `vite preview`, which keeps the minimal UI starter covered by one real browser path.
+- `CHANGELOG.md` records official tagged milestones for the repository.
+- `RELEASE.md` documents the maintainer release path across `develop`, `release/*`, and `main`.
+- `commitlint.config.mjs` defines the repository's commit message convention.
+- `.github/workflows/release.yml` reruns validation for `vX.Y.Z` tags, checks version alignment, and creates GitHub Releases.
+- `tests/unit/` covers isolated logic such as the `.kpa` module export normalization helper.
+- `tests/integration/` covers application bootstrap wiring without requiring a full browser run.
+- `tests/e2e/` covers the observable starter flow in a real browser.
+- `tsconfig.json` enforces strict TypeScript rules for source, tests, and TypeScript config files. `.kpa` compilation is still handled by the KoppaJS Vite plugin.
+
+More detailed boundaries live in [docs/architecture/module-boundaries.md](./docs/architecture/module-boundaries.md).
+
+## Runtime flow
+
+1. The browser loads [`index.html`](./index.html).
+2. The document loads [`src/style.css`](./src/style.css) and [`src/main.ts`](./src/main.ts).
+3. [`src/main.ts`](./src/main.ts) registers `app-view` and `counter-component` with KoppaJS Core, then calls `Core()`.
+4. KoppaJS instantiates `<app-view>`.
+5. [`src/app-view.kpa`](./src/app-view.kpa) renders the starter shell and nests `<counter-component>`.
+6. [`src/counter-component.kpa`](./src/counter-component.kpa) handles button clicks, mutates local state, and re-renders the displayed value.
+
+## Quality automation layer
+
+- `eslint.config.mjs` lint-checks TypeScript source plus the TypeScript- and JavaScript-based tooling files.
+- `prettier.config.mjs` and `.editorconfig` keep supported text files consistent without introducing formatter-specific rules into ESLint.
+- `.npmrc` enforces the declared engine floor during installs.
+- `.husky/pre-commit` runs `lint-staged` so staged files get a fast local quality pass before commit.
+- `.husky/commit-msg` validates commit headers with `commitlint`.
+- `.github/workflows/ci.yml` runs the full repository validation flow on GitHub.
+- `.github/workflows/release.yml` runs tagged release validation and creates GitHub Releases for matching versions.
+- Stylelint is intentionally absent for now because the important styles live inside `.kpa` blocks and the repository does not yet have a low-friction, first-class way to lint those embedded blocks without giving a misleading sense of coverage.
+
+## Module responsibilities
+
+| Module                          | Responsibility                                                                             | Must not do                                                           |
+| ------------------------------- | ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
+| `index.html`                    | Declare root tag and static assets                                                         | Hold business logic or feature wiring                                 |
+| `CHANGELOG.md`                  | Record official tagged release notes                                                       | Become a scratchpad for speculative work or duplicate repository docs |
+| `RELEASE.md`                    | Define the maintainer release procedure                                                    | Drift away from actual branch, tag, or workflow behavior              |
+| `commitlint.config.mjs`         | Define commit message validation rules                                                     | Expand into unrelated repository lint policy                          |
+| `src/main.ts`                   | Bootstrap and component registration                                                       | Accumulate feature logic, state, or DOM manipulation                  |
+| `src/app-view.kpa`              | Root layout and composition                                                                | Own unrelated business workflows or register components               |
+| `src/counter-component.kpa`     | Local interactive example state                                                            | Reach into global DOM or mutate app shell concerns                    |
+| `src/style.css`                 | Global reset/base rules                                                                    | Contain feature-specific visuals that belong to components            |
+| `public/`                       | Static assets                                                                              | Store generated build output or source code                           |
+| `tests/unit/`                   | Isolated tests for helper or tooling logic                                                 | Production runtime side effects or browser-only expectations          |
+| `tests/integration/`            | Wiring tests across bootstrap boundaries                                                   | Full browser assertions already covered by Playwright                 |
+| `tests/e2e/`                    | Real browser smoke coverage of the starter UI                                              | Deep implementation-detail assertions or brittle CSS-driven flows     |
+| `vite.config.mjs`               | Build and dev server integration, including the `.kpa` module export compatibility wrapper | Application runtime logic                                             |
+| `vitest.config.mjs`             | Unit and integration test runner configuration                                             | Runtime feature code                                                  |
+| `playwright.config.ts`          | Browser smoke-test orchestration against preview output                                    | Application runtime logic                                             |
+| `.github/workflows/release.yml` | Tagged release validation and GitHub Release creation                                      | Publish to npm while the repository remains private                   |
+
+## Invariants
+
+- There is exactly one application bootstrap path.
+- The root tag in `index.html` must match a component registered in `src/main.ts`.
+- `Core()` is called once from `src/main.ts`.
+- Official releases require matching versions across `package.json`, `CHANGELOG.md`, and `vX.Y.Z` tags.
+- Maintainer commits are expected to follow Conventional Commits.
+- No routing, persistence, network calls, or global client-side state are part of the baseline starter.
+- Stateful behavior remains local unless a documented new subsystem justifies centralization.
+- `pnpm check` remains fast enough for routine local use.
+- Playwright coverage stays focused on critical smoke coverage unless the UI grows into a broader workflow surface.
+- The repository remains `private` until an explicit decision changes the release target.
+
+## Extension guidance
+
+- Add new components under `src/` and compose them from `app-view.kpa` or other components.
+- Extract shared logic into `.ts` modules when it becomes reusable or deserves focused testing.
+- Add a spec before introducing new user-visible behavior.
+- Add an ADR before introducing architecture-changing capabilities such as routing, data fetching, persistence, state containers, SSR, or a new testing stack.

package/template/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Change Log
+
+All notable changes to **__PROJECT_NAME__** are documented in this file.
+
+This project uses a manual, tag-driven release process.
+Only tagged versions represent official releases.
+
+---
+
+## [Unreleased]
+
+This section is intentionally empty.
+
+Changes will only appear here when they:
+
+- alter the project's observable behavior,
+- change contributor or maintainer workflow,
+- or modify documented repository guarantees.
+
+---
+
+## [1.0.0] — Initial Scaffold Baseline
+
+**2026-03-17**
+
+Initial scaffold created from the current official KoppaJS starter baseline.
+
+### Included
+
+- a minimal KoppaJS app shell with `app-view` and `counter-component`
+- bootstrap through `Core.take(...)` and `Core()`
+- ESLint, Prettier, Vitest, Playwright, Husky, and GitHub Actions CI
+- explicit architecture, ADR, spec, testing, and contributor documentation
+- a tag-driven GitHub release workflow for repository snapshots