create-koppajs 1.2.2 → 1.2.3

package/template-overlays/router/src/not-found-page.kpa

@@ -1,69 +1,37 @@
 [template]
-  <section class="page-card page-card--missing">
-    <p class="section-label">404</p>
-    <h2 class="page-title">Page not found</h2>
-    <p class="page-text">
-      The router starter includes an explicit catch-all route, so unmatched URLs
-      still render a predictable fallback page instead of failing silently.
-    </p>
-
-    <div class="page-actions">
-      <a data-route="/" href="/" class="page-link">Return home</a>
-    </div>
+  <section class="page">
+    <p class="eyebrow">404</p>
+    <h1>Page not found</h1>
+    <p>The router fallback route rendered this page for an unknown URL.</p>
+    <a data-route="/" href="/" class="page-link">Return home</a>
   </section>
 [/template]
 
 [css]
-  .page-card {
-    display: flex;
-    flex-direction: column;
+  .page {
+    display: grid;
     gap: 1rem;
-    padding: 1.5rem;
-    border: 1px solid rgba(248, 113, 113, 0.24);
-    border-radius: 1.75rem;
-    background: linear-gradient(180deg, rgba(61, 12, 22, 0.5), rgba(11, 22, 40, 0.88));
-    box-shadow: var(--shadow);
   }
 
-  .section-label {
-    color: #fda4af;
+  .eyebrow {
+    color: var(--accent);
     font-size: 0.8rem;
-    letter-spacing: 0.28em;
+    letter-spacing: 0.2em;
     text-transform: uppercase;
   }
 
-  .page-title {
-    font-size: clamp(1.7rem, 3vw, 2.5rem);
+  h1 {
+    font-size: clamp(2rem, 4vw, 3rem);
     line-height: 1.1;
   }
 
-  .page-text {
-    color: #fecdd3;
+  p {
+    color: var(--muted);
     line-height: 1.7;
-    max-width: 58ch;
-  }
-
-  .page-actions {
-    display: flex;
   }
 
   .page-link {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    min-height: 2.8rem;
-    padding: 0 1.25rem;
-    border-radius: 999px;
-    background: rgba(253, 164, 175, 0.12);
-    border: 1px solid rgba(253, 164, 175, 0.4);
-    color: #fff1f2;
-    text-decoration: none;
-  }
-
-  @media (max-width: 640px) {
-    .page-card {
-      padding: 1.15rem;
-      border-radius: 1.25rem;
-    }
+    width: fit-content;
+    color: var(--accent);
   }
 [/css]

package/template-overlays/router/src/router-page.kpa

@@ -1,102 +1,67 @@
 [template]
-  <section class="page-card">
-    <div class="page-copy">
-      <p class="section-label">Second page</p>
-      <h2 class="page-title">Router is active</h2>
-      <p class="page-text">
-        This view is rendered into <code>#app-outlet</code> by
-        <code>KoppajsRouter</code>. The active navigation state and the browser
-        URL are both managed by the router runtime.
-      </p>
+  <section class="page">
+    <p class="eyebrow">Router route</p>
+    <h1>Routing is active</h1>
+    <p>
+      This page is rendered for <code>/router</code>. Links with
+      <code>data-route</code> are handled by <code>KoppajsRouter</code>, and a
+      catch-all route handles unknown paths.
+    </p>
 
-      <ul class="feature-list">
-        <li>Routes are defined in <code>src/main.ts</code>.</li>
-        <li>Links opt into delegated navigation through <code>data-route</code>.</li>
-        <li>A catch-all route is already wired for unmatched paths.</li>
-      </ul>
+    <ul class="route-list" aria-label="Configured routes">
+      <li><code>/</code> renders <code>home-page</code></li>
+      <li><code>/router</code> renders <code>router-page</code></li>
+      <li><code>*</code> renders <code>not-found-page</code></li>
+    </ul>
 
-      <div class="page-actions">
-        <a data-route="/" href="/" class="page-link">Back to home</a>
-      </div>
-    </div>
+    <a data-route="/" href="/" class="page-link">Back home</a>
   </section>
 [/template]
 
 [css]
-  .page-card {
-    padding: 1.5rem;
-    border: 1px solid var(--border);
-    border-radius: 1.75rem;
-    background: var(--surface-strong);
-    box-shadow: var(--shadow);
-    backdrop-filter: blur(18px);
-  }
-
-  .page-copy {
-    display: flex;
-    flex-direction: column;
+  .page {
+    display: grid;
     gap: 1rem;
   }
 
-  .section-label {
+  .eyebrow {
     color: var(--accent);
     font-size: 0.8rem;
-    letter-spacing: 0.28em;
+    letter-spacing: 0.2em;
     text-transform: uppercase;
   }
 
-  .page-title {
-    font-size: clamp(1.7rem, 3vw, 2.5rem);
+  h1 {
+    font-size: clamp(2rem, 4vw, 3rem);
     line-height: 1.1;
   }
 
-  .page-text {
+  p {
+    max-width: 62ch;
     color: var(--muted);
     line-height: 1.7;
-    max-width: 58ch;
   }
 
   code {
-    color: var(--accent-strong);
+    color: var(--accent);
   }
 
-  .feature-list {
-    list-style: none;
+  .route-list {
     display: grid;
-    gap: 0.8rem;
-    color: var(--text);
-  }
-
-  .feature-list li {
-    padding: 0.95rem 1rem;
-    border-radius: 1rem;
-    border: 1px solid rgba(100, 220, 232, 0.18);
-    background: rgba(100, 220, 232, 0.06);
+    gap: 0.6rem;
+    list-style: none;
+    max-width: 34rem;
   }
 
-  .page-actions {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 0.8rem;
+  .route-list li {
+    padding: 0.8rem 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.75rem;
+    background: var(--surface);
   }
 
   .page-link {
-    display: inline-flex;
-    align-items: center;
-    justify-content: center;
-    min-height: 2.8rem;
-    padding: 0 1.25rem;
-    border-radius: 999px;
-    background: rgba(100, 220, 232, 0.1);
-    border: 1px solid rgba(100, 220, 232, 0.3);
-    color: var(--accent-strong);
-    text-decoration: none;
-  }
-
-  @media (max-width: 640px) {
-    .page-card {
-      padding: 1.15rem;
-      border-radius: 1.25rem;
-    }
+    width: fit-content;
+    color: var(--accent);
   }
 [/css]

package/template-overlays/router/src/style.css

@@ -1,16 +1,12 @@
 :root {
   color-scheme: dark;
-  --app-bg: #08111f;
-  --app-bg-accent: #102742;
-  --surface: rgba(9, 16, 31, 0.78);
-  --surface-strong: rgba(11, 22, 40, 0.92);
-  --border: rgba(148, 163, 184, 0.2);
+  --app-bg: #0f1117;
+  --surface: #171b29;
+  --border: #2a3042;
   --text: #edf6ff;
   --muted: #a7bfd7;
   --accent: #64dce8;
-  --accent-strong: #97f3fb;
-  --shadow: 0 24px 80px rgba(0, 0, 0, 0.32);
-  font-family: "Space Grotesk", "Avenir Next", "Segoe UI", sans-serif;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
 }
 
 * {
@@ -19,29 +15,9 @@
   padding: 0;
 }
 
-html {
-  min-height: 100%;
-  background:
-    radial-gradient(
-      circle at top left,
-      rgba(100, 220, 232, 0.16),
-      transparent 30%
-    ),
-    radial-gradient(
-      circle at bottom right,
-      rgba(16, 39, 66, 0.55),
-      transparent 32%
-    ),
-    linear-gradient(
-      160deg,
-      var(--app-bg) 0%,
-      #060c18 45%,
-      var(--app-bg-accent) 100%
-    );
-}
-
 body {
   min-height: 100vh;
+  background: var(--app-bg);
   color: var(--text);
 }
 

package/template/AI_CONSTITUTION.md

@@ -1,50 +0,0 @@
-# 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

@@ -1,84 +0,0 @@
-# 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 without local compatibility layers.
-- `vitest.config.mjs` reuses the Vite config so 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/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/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 through the upstream KoppaJS Vite plugin | 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

@@ -1,35 +0,0 @@
-# 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]
-
-### Changed
-
-- raised the minimum Node.js version to `>=22` and expanded CI coverage to
-  Node 24
-- refreshed the starter dependency baseline to the current `@koppajs/koppajs-core`
-  and `@koppajs/koppajs-vite-plugin` releases
-- removed the obsolete local `.kpa` export wrapper because the upstream Vite
-  plugin already emits valid ES modules
-
----
-
-## [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

package/template/CONTRIBUTING.md

@@ -1,89 +0,0 @@
-# Contributing
-
-## Setup
-
-Requirements:
-
-- Node.js >= 22
-- pnpm 10 or newer
-
-Install and run:
-
-```bash
-pnpm install
-pnpm dev
-```
-
-Install the Playwright browser once if you plan to run browser smoke tests locally:
-
-```bash
-pnpm exec playwright install chromium
-```
-
-Useful commands:
-
-```bash
-pnpm lint
-pnpm format:check
-pnpm typecheck
-pnpm test:run
-pnpm test:coverage
-pnpm test:e2e
-pnpm check
-pnpm validate
-pnpm release:check
-pnpm build
-pnpm serve
-```
-
-Commit messages use Conventional Commits.
-Examples:
-
-```text
-feat: add release baseline
-docs: update contributing guide
-fix: align bootstrap docs
-```
-
-## Workflow
-
-1. Read [DECISION_HIERARCHY.md](./DECISION_HIERARCHY.md), [ARCHITECTURE.md](./ARCHITECTURE.md), and any relevant spec or ADR before changing source files.
-2. For non-trivial work, update or create the relevant spec in [docs/specs](./docs/specs) first.
-3. If the change alters architecture, tooling, public tags, or repository workflow, add or update an ADR in [docs/adr](./docs/adr).
-4. Implement the smallest change that satisfies the spec.
-5. Run the applicable quality gates from [TESTING_STRATEGY.md](./TESTING_STRATEGY.md). Use `pnpm check` for the local baseline and `pnpm validate` before merge when the UI, bootstrap, or tooling changed.
-6. If the change touches versioning, changelog, or release automation, update `CHANGELOG.md`, `RELEASE.md`, and the affected workflow in the same change.
-7. Update architecture, development, testing, and README docs when the actual project state changes.
-
-## Releases
-
-- Release notes live in [`CHANGELOG.md`](./CHANGELOG.md).
-- The maintainer release procedure lives in [`RELEASE.md`](./RELEASE.md).
-- Releases are prepared on `develop`, moved through `release/*`, merged into `main`, and tagged as `vX.Y.Z`.
-- The release workflow creates GitHub Releases only. The repository starts
-  `private`, so no npm publish step is configured by default.
-- Run `pnpm release:check` before cutting a release tag.
-
-## Commit policy
-
-- Commit messages are validated by `.husky/commit-msg` using `commitlint`.
-- Use Conventional Commits such as `feat: ...`, `fix: ...`, `docs: ...`, `test: ...`, `ci: ...`, or `chore: ...`.
-- Keep the commit header at 72 characters or fewer.
-- Merge, revert, `fixup!`, and `squash!` commits may bypass validation when Git creates them automatically.
-
-## Pull request expectations
-
-- Keep the starter minimal unless expansion is explicitly approved.
-- Explain user-visible behavior changes and architecture-impacting decisions.
-- Do not silently swap dependency sources, add build tools, or introduce new subsystems.
-- Keep docs and code aligned in the same change.
-- Keep hooks fast; heavy validation belongs in `pnpm validate` and CI, not in `pre-commit`.
-
-## AI-assisted contributions
-
-AI contributors follow the same rules as humans:
-
-- read governing docs before editing,
-- prefer existing patterns,
-- do not invent architecture casually,
-- update the meta layer whenever structure or rules change.

package/template/DECISION_HIERARCHY.md

@@ -1,32 +0,0 @@
-# Decision Hierarchy
-
-When repository documents conflict, use this order of precedence.
-
-1. Approved specifications in [`docs/specs/`](./docs/specs)
-2. Architecture Decision Records in [`docs/adr/`](./docs/adr)
-3. [`AI_CONSTITUTION.md`](./AI_CONSTITUTION.md)
-4. [`ARCHITECTURE.md`](./ARCHITECTURE.md) and supporting architecture docs in [`docs/architecture/`](./docs/architecture)
-5. [`DEVELOPMENT_RULES.md`](./DEVELOPMENT_RULES.md) and [`TESTING_STRATEGY.md`](./TESTING_STRATEGY.md)
-6. Quality and maintenance guidance in [`docs/quality/`](./docs/quality) and [`docs/meta/`](./docs/meta)
-7. Contributor guidance and examples in [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`README.md`](./README.md), and inline comments
-
-## Interpretation rules
-
-- The most specific document wins when two documents have the same rank.
-- A newer document does not override a higher-ranked document by default.
-- If a lower-ranked document is wrong, fix it instead of following it.
-- If no applicable spec exists for a non-trivial change, create or update one before implementation.
-- If a change would invalidate an ADR, create a superseding ADR instead of silently drifting away from it.
-
-## Required reading order for non-trivial changes
-
-1. This file
-2. [AI_CONSTITUTION.md](./AI_CONSTITUTION.md)
-3. [ARCHITECTURE.md](./ARCHITECTURE.md)
-4. Relevant spec in [docs/specs](./docs/specs)
-5. Relevant ADR in [docs/adr](./docs/adr)
-6. [DEVELOPMENT_RULES.md](./DEVELOPMENT_RULES.md) and [TESTING_STRATEGY.md](./TESTING_STRATEGY.md)
-
-## Escalation rule
-
-When a change creates a new lasting rule, boundary, or tradeoff, encode it as a spec or ADR rather than relying on chat history or commit messages.

package/template/DEVELOPMENT_RULES.md

@@ -1,57 +0,0 @@
-# Development Rules
-
-## Scope
-
-These rules describe how code and documentation are expected to evolve in this repository.
-
-## Source layout rules
-
-- Keep `index.html` as a static shell with asset references and the single root element.
-- Keep `src/main.ts` limited to bootstrap concerns: imports, `Core.take(...)` registrations, and the single public bootstrap call via `Core()`.
-- Use `.kpa` files for UI composition, local component state, and component-scoped CSS.
-- If logic becomes reusable, asynchronous, or branch-heavy, move it into `.ts` modules under `src/`.
-- Keep `public/` for static assets only.
-- Keep automated tests under `tests/`, split by `unit`, `integration`, and `e2e` only when each level is meaningfully used.
-
-## Naming conventions
-
-- Custom element names must be kebab-case.
-- Root-level application components should use `app-` prefixes when they represent app shells or app-wide structure.
-- Component filenames should match their primary exported or registered concept.
-- New files and folders should use descriptive names over abbreviations.
-
-## Dependency rules
-
-- Runtime dependencies must be justified by a concrete need in a spec or ADR.
-- Prefer browser APIs and KoppaJS primitives before adding helper libraries.
-- Keep this repository wired to published npm packages unless there is an explicit ADR stating otherwise.
-- Build tooling changes must update contributor docs and architecture docs in the same change.
-- Quality tooling must stay proportionate to the starter. Prefer one clear tool per job over overlapping stacks.
-
-## Coding patterns
-
-- Favor simple, local state over premature abstraction.
-- Keep methods short and named by behavior.
-- Avoid hidden side effects during import.
-- Keep CSS local to components unless the style truly applies application-wide.
-- Preserve strict TypeScript settings; do not weaken `tsconfig.json` to work around errors.
-- Give interactive controls stable accessible names when feasible so smoke tests can target public semantics instead of brittle selectors.
-- Keep Playwright assertions user-facing. Implementation-detail checks belong in Vitest, not in browser tests.
-
-## Forbidden without a spec and ADR
-
-- Introducing routing
-- Adding global state containers
-- Adding network or persistence layers
-- Introducing SSR, multi-page bootstraps, or multiple root entries
-- Switching dependency sourcing from npm packages to local monorepo links
-- Expanding the starter into a multi-feature demo application
-- Adding heavyweight hooks that run the entire suite on every commit
-
-## Documentation obligations
-
-- Update [ARCHITECTURE.md](./ARCHITECTURE.md) when source layout or runtime flow changes.
-- Update [TESTING_STRATEGY.md](./TESTING_STRATEGY.md) when quality gates or tooling change.
-- Update or create a spec in [docs/specs](./docs/specs) for user-visible changes.
-- Add an ADR in [docs/adr](./docs/adr) for durable technical decisions.
-- Update [docs/quality/quality-gates.md](./docs/quality/quality-gates.md) when scripts, hooks, CI checks, or browser-smoke expectations change.