create-monolayer-app 0.5.1 → 0.6.3

package/template/.agents/skills/vitest/references/advanced-environments.md

@@ -0,0 +1,26 @@
+# Environments
+
+Select an environment from the APIs that the test needs.
+
+| Execution    | Use                                                  |
+| ------------ | ---------------------------------------------------- |
+| `node`       | Server logic and code without DOM requirements       |
+| `jsdom`      | DOM emulation in Node.js                             |
+| `happy-dom`  | Alternative DOM emulation with different API support |
+| Browser Mode | Actual browser behavior through a browser provider   |
+
+The template currently uses `node`. DOM environments require their corresponding packages. Check installed dependencies before you select one.
+
+Use a file comment when one file needs a different Node.js environment:
+
+```ts
+// @vitest-environment jsdom
+```
+
+Browser Mode uses `test.browser` configuration. It is not an `environment: "browser"` option. Use a browser project when tests need actual layout, focus, or browser integration. Mock external service boundaries while retaining real UI behavior.
+
+A custom environment exports an object that matches `Environment` from `vitest/runtime` in Vitest 5. Define its Vite environment and cleanup behavior from the installed types. Avoid adding a custom environment when an existing environment meets the need.
+
+For CSS import errors in an external dependency chain, inspect `server.deps.inline`. Include the relevant chain only when transformation is necessary. A simulated DOM does not prove browser rendering behavior.
+
+Sources: [Environments](https://vitest.dev/guide/environment), [Browser Mode](https://vitest.dev/guide/browser/).

package/template/.agents/skills/vitest/references/advanced-projects.md

@@ -0,0 +1,31 @@
+# Projects
+
+Use `test.projects` when test groups need different environments or runner settings. Give each project a distinct name. Use `defineProject` for an independent project file.
+
+```ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    projects: [
+      {
+        test: {
+          name: "unit",
+          environment: "node",
+          include: ["src/**/*.test.ts"],
+        },
+      },
+    ],
+  },
+});
+```
+
+In Vitest 5, inline projects inherit their declaring configuration by default. Arrays such as `setupFiles` concatenate. `name` and `projects` do not inherit. Root `globalSetup` runs once and does not inherit into child projects. A project's own `tags` replace the inherited tags. Use `extends: false` when a project must be independent.
+
+Vitest 4 requires explicit `extends: true` for this inheritance.
+
+Projects referenced as files or directories do not inherit root settings automatically. Merge a shared configuration explicitly when necessary. Referenced configurations can define nested projects in Vitest 5. Avoid merging a root `projects` list back into its children.
+
+Keep coverage and reporters at the root. Use `--project` to select projects through the local runner. Inspect shared Vite server behavior when plugin initialization must occur separately.
+
+Sources: [Projects](https://vitest.dev/guide/projects), [Version compatibility](version-compatibility.md).

package/template/.agents/skills/vitest/references/advanced-type-testing.md

@@ -0,0 +1,30 @@
+# Type testing
+
+Use `expectTypeOf` or `assertType` for TypeScript contracts. Run a compiler check to evaluate those contracts. Ordinary runtime execution does not check TypeScript types.
+
+Put dedicated type tests in files that match `typecheck.include`, normally `*.test-d.ts`:
+
+```ts
+import { assertType, describe, expectTypeOf, test } from "vitest";
+
+describe("record shape", () => {
+  test("preserves field types", () => {
+    const record = { id: "record-1", revision: 1 };
+    expectTypeOf(record).toEqualTypeOf<{ id: string; revision: number }>();
+    assertType<string>(record.id);
+  });
+});
+```
+
+Enable type checks through the local runner:
+
+```sh
+npm exec --no -- vitest run --typecheck
+npm exec --no -- vitest run --typecheck.only
+```
+
+Dedicated type test files undergo static analysis. They do not execute their callbacks or lifecycle hooks. Keep runtime assertions in runtime test files. Overlapping runtime and type patterns can produce separate results for the same file.
+
+Use `toEqualTypeOf` for type equality. Use the installed assignability matcher for subtype checks. Keep `@ts-expect-error` comments specific to the intended compiler error. A misspelled identifier can otherwise satisfy an expected-error test. Run the application's complete type check when changes affect its consumers.
+
+Source: [Type testing](https://vitest.dev/guide/testing-types).

package/template/.agents/skills/vitest/references/advanced-vi.md

@@ -0,0 +1,23 @@
+# Vi utilities
+
+## Mock cleanup
+
+| Operation | Effect |
+| --- | --- |
+| `vi.clearAllMocks()` | Clears call history and preserves implementations. |
+| `vi.resetAllMocks()` | Clears history and resets implementations to their original mock state. |
+| `vi.restoreAllMocks()` | Restores original object descriptors for `vi.spyOn` spies. |
+| `vi.unstubAllGlobals()` | Restores globals changed with `vi.stubGlobal`. |
+| `vi.unstubAllEnvs()` | Restores environment values changed with `vi.stubEnv`. |
+
+`vi.restoreAllMocks()` does not clear retained spy history or remove module mocks. `vi.fn(implementation).mockReset()` restores the initial implementation. A reset of `vi.fn()` restores an empty function. Vitest 5 enables `clearMocks` by default. Call history can still conflict between concurrent tests.
+
+## Timers and modules
+
+Use `vi.useFakeTimers()` before code schedules timers. Await `vi.advanceTimersByTimeAsync()` when timer callbacks use promises. Use `vi.setSystemTime()` to control the clock. It does not execute scheduled timers. Restore real timers after each applicable test.
+
+`vi.resetModules()` clears the module cache for subsequent imports. It does not remove mock registrations or repeat existing static imports.
+
+Use `vi.waitFor` when a callback must stop throwing. Use `vi.waitUntil` when its result must become truthy. Use Vitest 5's `vi.when` for argument-dependent mock behavior when ordinary mock implementations become unclear. Check its installed signature before use.
+
+Sources: [Vi API](https://vitest.dev/api/vi), [Mock API](https://vitest.dev/api/mock).

package/template/.agents/skills/vitest/references/core-cli.md

@@ -0,0 +1,23 @@
+# CLI
+
+Prefer the existing package scripts when they invoke the correct local runner. Check the manifest before you assume that a `test` script exists. The template currently has no test script.
+
+Run these examples from the application directory with its installed dependencies:
+
+```sh
+npm exec --no -- vitest --version
+npm exec --no -- vitest --help
+npm exec --no -- vitest list
+npm exec --no -- vitest run
+npm exec --no -- vitest run src/parser.test.ts -t "rejects empty input"
+npm exec --no -- vitest watch src/parser.test.ts
+npm exec --no -- vitest related src/parser.ts --run
+```
+
+Replace example paths with existing application files. Use `run` for commands that must finish. The default command can enter watch mode in an interactive terminal. `related` follows the import graph. It cannot resolve arbitrary paths that application code calculates at runtime.
+
+Use `--config` when the task requires an explicit configuration file. Use `--project` for a named project. Use `--coverage.enabled=false` for focused feedback when configuration enables coverage. Run complete coverage separately when required.
+
+Inspect `list` output when a command discovers no tests. Check the working directory, configuration, include patterns, and filters. Do not use `--passWithNoTests` to conceal missing tests.
+
+Source: [CLI](https://vitest.dev/guide/cli).

package/template/.agents/skills/vitest/references/core-config.md

@@ -0,0 +1,24 @@
+# Configuration
+
+Import `defineConfig` from `vitest/config`. Put runner options inside `test`. Put Vite options, such as `resolve.alias` and `plugins`, at the top level.
+
+```ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    environment: "node",
+    include: ["src/**/*.test.ts"],
+  },
+});
+```
+
+A separate `vitest.config.ts` takes priority over `vite.config.ts`. It does not automatically merge the application configuration. Use `mergeConfig` when tests need selected Vite settings. Check application plugins before you include them in a test process. Extend `configDefaults.exclude` when additional exclusions must preserve the defaults.
+
+Use `setupFiles` for setup that each test file requires. Use `globalSetup` for resources that span the run. Global setup executes outside test workers. Use `provide` and `inject` for serializable values across that boundary.
+
+## Template discovery
+
+The current template includes `.test.ts` files under `src`, `lib`, and `app`. Its patterns exclude `.test.tsx` files and tests under `vendor`. A CLI filename filter does not add excluded files to discovery. Its `virtual:db-migrations` alias resolves to a test fixture. Preserve that alias when tests depend on it. Recheck these facts after configuration changes.
+
+Sources: [Configuration](https://vitest.dev/config/), [Projects](advanced-projects.md).

package/template/.agents/skills/vitest/references/core-describe.md

@@ -0,0 +1,24 @@
+# Describe API
+
+Use `describe` to group tests with the same subject or setup. `suite` is an alias. Keep the hierarchy shallow enough to make test names clear.
+
+```ts
+import { describe, expect, test } from "vitest";
+
+describe.each([
+  { input: "one", expected: "ONE" },
+  { input: "two", expected: "TWO" },
+])("conversion of $input", ({ input, expected }) => {
+  test("returns uppercase text", () => {
+    expect(input.toUpperCase()).toBe(expected);
+  });
+});
+```
+
+Suite options apply to child tests unless a child overrides them. Use suite options for shared timeouts or concurrency when that behavior fits all children. Use `describe.each` for repeated suite cases. Use `describe.for` when the case should remain one value.
+
+Suite callbacks collect tests before test execution. Do not put assertions, service calls, or resource setup in the collection callback. Use lifecycle hooks or fixtures for setup and cleanup. Keep `vi.mock` at module scope in Vitest 5.
+
+`describe.concurrent` permits child tests to overlap. Use `{ concurrent: false }` for a child that needs sequential execution. This setting does not serialize other files that share an external resource. See [concurrency](features-concurrency.md) for those boundaries.
+
+Source: [Describe API](https://vitest.dev/api/describe).

package/template/.agents/skills/vitest/references/core-expect.md

@@ -0,0 +1,35 @@
+# Expect API
+
+Select assertions that check the required result.
+
+| Result                              | Matcher                            |
+| ----------------------------------- | ---------------------------------- |
+| Primitive value or object identity  | `toBe`                             |
+| Complete object structure and types | `toStrictEqual`                    |
+| Required object fields              | `toMatchObject`                    |
+| Synchronous error                   | `toThrow` with an expected message |
+| Promise result or error             | Await `resolves` or `rejects`      |
+| Mock arguments                      | `toHaveBeenCalledWith`             |
+| Eventual state                      | Await `expect.poll`                |
+
+```ts
+import { describe, expect, test } from "vitest";
+
+describe("asynchronous results", () => {
+  test("returns the result", async () => {
+    await expect(Promise.resolve({ count: 2 })).resolves.toStrictEqual({
+      count: 2,
+    });
+  });
+
+  test("reports the failure", async () => {
+    await expect(Promise.reject(new Error("Missing record"))).rejects.toThrow("Missing record");
+  });
+});
+```
+
+Pass a callback to `toThrow` for synchronous operations. Do not call the operation before the assertion receives it. Use asymmetric matchers only for fields that the contract permits to vary. Use `expect.assertions` when callback execution could otherwise leave no assertion.
+
+A false result does not make `vi.waitFor` retry. Use an assertion that throws, or use `vi.waitUntil` for a truthy condition. Use the context's `expect` for concurrent snapshots and assertion counts.
+
+Sources: [Expect API](https://vitest.dev/api/expect), [Vi API](https://vitest.dev/api/vi).

package/template/.agents/skills/vitest/references/core-hooks.md

@@ -0,0 +1,26 @@
+# Hooks
+
+Use `beforeEach` and `afterEach` for resources that each test requires. Use `beforeAll` and `afterAll` for resources that the suite shares. Await asynchronous setup and cleanup.
+
+```ts
+import { afterEach, describe, expect, test, vi } from "vitest";
+
+describe("runtime configuration", () => {
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  test("uses the test region", () => {
+    vi.stubEnv("APP_REGION", "test-region");
+    expect(process.env.APP_REGION).toBe("test-region");
+  });
+});
+```
+
+A setup hook can return a cleanup callback. Vitest runs that callback after the corresponding explicit cleanup hooks. Hook ordering depends on `sequence.hooks`. Inspect that setting before a test depends on cleanup order.
+
+`aroundEach` wraps per-test setup, execution, and cleanup. `aroundAll` wraps a suite. Call and await the supplied execution function. Use `try` and `finally` when resource release must occur after a failure.
+
+Use the context's `onTestFinished` for cleanup that belongs to one concurrent test. Use `onTestFailed` for failure evidence. Concurrent hooks must not change shared globals or resources without isolation. Increase a hook timeout only when the operation needs that time.
+
+Source: [Hooks API](https://vitest.dev/api/hooks).

package/template/.agents/skills/vitest/references/core-test-api.md

@@ -0,0 +1,29 @@
+# Test API
+
+`test` and `it` define tests with the same API. Use a name that states the expected behavior. Put options before the callback.
+
+```ts
+import { describe, expect, test } from "vitest";
+
+describe("number conversion", () => {
+  test("converts a decimal", { timeout: 1_000 }, async () => {
+    const value = await Promise.resolve(Number("12"));
+    expect(value).toBe(12);
+  });
+
+  test.each([
+    ["0", 0],
+    ["12", 12],
+  ])("converts %s", (input, expected) => {
+    expect(Number(input)).toBe(expected);
+  });
+});
+```
+
+Use `test.each` for data cases with separate arguments. Use `test.for` when each case needs the test context. For array cases, `test.for` passes the array as one argument.
+
+Use `test.concurrent` only for independent tests. Use `{ concurrent: false }` to override inherited concurrency. A retry repeats the test and its per-test setup. Do not use retries as the only correction for unstable behavior.
+
+A callback without an implementation creates a pending test. Keep pending cases separate from completion evidence. Use `.only`, `.skip`, and conditional selection only within repository rules. Remove temporary selection before completion.
+
+Source: [Test API](https://vitest.dev/api/test).

package/template/.agents/skills/vitest/references/features-benchmarking.md

@@ -0,0 +1,25 @@
+# Benchmarking
+
+Vitest 5 provides `bench` through the test context. Do not import a top-level `bench` function from `vitest` for this version.
+
+Put benchmark tests in a file that matches `benchmark.include`, such as `parser.bench.ts`:
+
+```ts
+import { describe, test } from "vitest";
+
+describe("parser throughput", () => {
+  test("measures JSON parsing", async ({ bench }) => {
+    await bench("parse a record", () => {
+      return JSON.parse('{"state":"ready","revision":1}');
+    }).run();
+  });
+});
+```
+
+Run `vitest bench --run` through the local installation for one benchmark run. Use `benchmark.enabled` when the regular run must also include benchmarks. The fixture is unavailable in ordinary test files outside benchmark discovery.
+
+Use `bench.compare` for comparisons within the same measurement conditions. Use a practical tolerance for performance assertions. Use `writeResult` to save a result and `bench.from` to read a baseline. Give baseline files names that identify the measured version.
+
+Consume or return computed results to reduce dead-code elimination. Keep warmup, input data, and the runtime consistent across comparisons. Worker load and module transformation can affect measurements. Do not infer production performance from one local result.
+
+Source: [Benchmarking](https://vitest.dev/guide/benchmarking).

package/template/.agents/skills/vitest/references/features-concurrency.md

@@ -0,0 +1,20 @@
+# Concurrency
+
+Distinguish file parallelism from concurrency inside one file. Vitest normally runs files in separate workers. Tests inside each file normally run sequentially.
+
+| Setting                  | Boundary                             |
+| ------------------------ | ------------------------------------ |
+| `maxWorkers`             | Maximum workers for files            |
+| `fileParallelism: false` | Sequential files within the run      |
+| `test.concurrent`        | Overlapping tests in one worker      |
+| `maxConcurrency`         | Maximum concurrent tests             |
+| `{ concurrent: false }`  | Override inherited test concurrency  |
+| `--shard=1/3`            | Select one part of a distributed run |
+
+Use concurrent tests for independent asynchronous operations. Synchronous CPU work does not gain worker parallelism from `test.concurrent`.
+
+Use the context's `expect` for concurrent snapshots and assertion counts. Use per-test fixtures and cleanup for mutable resources. Avoid overlapping tests that change shared timers, environment values, or mock implementations. Vitest 5's automatic mock clearing can affect another concurrent test's call history.
+
+Separate workers do not isolate an external database, filesystem path, or service account. Give each test independent resources where possible. A sequential suite does not serialize other files or other processes. Inspect resource ownership before changing isolation settings. Do not disable isolation only to hide test-order dependencies.
+
+Source: [Parallelism](https://vitest.dev/guide/parallelism).

package/template/.agents/skills/vitest/references/features-context.md

@@ -0,0 +1,27 @@
+# Test context and fixtures
+
+Use the callback's context for values that belong to one test. The context includes `expect`, `task`, `signal`, and cleanup hooks. Pass `signal` to cancellable operations when a test timeout must stop the operation.
+
+Use `test.extend` for reusable typed fixtures. The builder API supports inferred fixture types in Vitest 4.1 and later.
+
+```ts
+import { describe, test as baseTest } from "vitest";
+
+const test = baseTest
+  .extend("settings", { region: "test-region" })
+  .extend("region", async ({ settings }) => settings.region);
+
+describe("fixture dependencies", () => {
+  test("provides the configured region", ({ expect, region }) => {
+    expect(region).toBe("test-region");
+  });
+});
+```
+
+For a resource fixture, register its teardown with `onCleanup` in the builder callback's second argument. Register one cleanup callback per fixture. Combine related release operations in that callback when necessary.
+
+The object syntax supports setup before `await use(value)` and teardown after it. Fixtures initialize when requested unless their options make them automatic. Choose test scope for mutable state that each test must own. Use a broader scope only when resource sharing remains safe.
+
+Global setup values cross worker boundaries through `provide` and `inject`. Those values must support serialization.
+
+Source: [Test context](https://vitest.dev/guide/test-context).

package/template/.agents/skills/vitest/references/features-coverage.md

@@ -0,0 +1,17 @@
+# Coverage
+
+Use the existing provider and source boundaries. Vitest supports V8 and Istanbul coverage through separate companion packages. Match the provider package version to the runner version. The template selects V8, but its manifest does not currently declare `@vitest/coverage-v8`. Check the local installation before a coverage run. Do not accept an automatic package installation without the task's dependency-change scope.
+
+Use the application's local runner:
+
+```sh
+npm exec --no -- vitest run --coverage
+```
+
+Use `coverage.include` to define the measured source files. Review exclusions for tests, generated output, and entrypoints. The template currently measures `src/**/*.ts`. That setting does not measure all application code under `lib` or `app`. State the measured scope in the result.
+
+A filtered run can fail global thresholds because it leaves other source files unexecuted. Disable coverage for focused development feedback when necessary. Then run the complete required suite with coverage enabled.
+
+Inspect missing branches and failure behavior before adding tests. Do not lower thresholds, narrow source patterns, or add ignore comments to obtain a pass. Separate passing assertions from provider failures and threshold failures.
+
+Sources: [Coverage](https://vitest.dev/guide/coverage), [Coverage configuration](https://vitest.dev/config/coverage).

package/template/.agents/skills/vitest/references/features-filtering.md

@@ -0,0 +1,24 @@
+# Filtering
+
+Use a file filter first when the affected file is known. This avoids collecting unrelated files for a name filter. A positional file filter matches path substrings. It is not a glob or regular expression.
+
+Run these examples through the application's local runner:
+
+```sh
+npm exec --no -- vitest run src/parser.test.ts
+npm exec --no -- vitest run src/parser.test.ts -t "rejects empty input"
+npm exec --no -- vitest run src/parser.test.ts:20
+npm exec --no -- vitest related src/parser.ts --run
+npm exec --no -- vitest run --changed=HEAD
+npm exec --no -- vitest run --project=unit
+```
+
+Replace the paths and line number with actual test locations. A line filter requires the complete filename and extension. Line ranges are not supported.
+
+`-t` matches the full test name. Vitest 5 joins suite names and the test name with `>`. A pattern for one name segment avoids separator differences between major versions.
+
+`related` follows imports from the specified source files. `--changed` uses Git changes and their affected tests. Neither proves that an external service integration works.
+
+Inspect `vitest list` when selection gives no tests. Configuration include patterns still apply to positional filters. Use [tags](features-test-tags.md) for category expressions.
+
+Source: [Test filtering](https://vitest.dev/guide/filtering).

package/template/.agents/skills/vitest/references/features-mocking.md

@@ -0,0 +1,32 @@
+# Mocking
+
+Keep application logic real where practical. Mock external service boundaries with the behavior that each test requires.
+
+`vi.mock` replaces an imported module before static imports execute. Put `vi.mock`, `vi.unmock`, and `vi.hoisted` at module scope. Vitest 5 rejects these calls inside suites, tests, functions, or blocks. Use `vi.hoisted` for values that a mock factory needs before imports.
+
+The following example assumes an adjacent `gateway.ts` module with a `read` export:
+
+```ts
+import { describe, expect, test, vi } from "vitest";
+import { read } from "./gateway";
+
+const mocks = vi.hoisted(() => ({
+  read: vi.fn<(id: string) => Promise<string>>(),
+}));
+
+vi.mock(import("./gateway"), () => ({ read: mocks.read }));
+
+describe("gateway substitution", () => {
+  test("returns the configured response", async () => {
+    mocks.read.mockResolvedValueOnce("ready");
+    await expect(read("record-1")).resolves.toBe("ready");
+    expect(mocks.read).toHaveBeenCalledWith("record-1");
+  });
+});
+```
+
+Use `vi.doMock` for subsequent dynamic imports when the factory needs runtime values. It does not replace existing static imports. Use `importOriginal` for partial replacements. Include a `default` property when the module has a default export.
+
+`vi.mocked` changes TypeScript's view of a value. It does not create a runtime mock. Browser Mode requires `{ spy: true }` when tracking native module exports.
+
+Sources: [Module mocking](https://vitest.dev/guide/mocking/modules), [Vi API](https://vitest.dev/api/vi).

package/template/.agents/skills/vitest/references/features-reporters.md

@@ -0,0 +1,22 @@
+# Reporters
+
+Select terminal output for developers and machine output for CI consumers. Configure reporters at the root when using projects.
+
+```ts
+import { configDefaults, defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    reporters: [...configDefaults.reporters, "junit"],
+    outputFile: { junit: "reports/tests.xml" },
+  },
+});
+```
+
+An explicit reporter list replaces the automatic selection. Extend `configDefaults.reporters` when the task needs the default selection as well. Without explicit configuration, Vitest selects output for the execution environment. It can add GitHub Actions output or select compact output for coding agents.
+
+Use `verbose` when individual test names help diagnosis. Use JSON or JUnit for a machine consumer. Specify output paths when CI requires a stable artifact location. The HTML reporter uses its `outputDir` option. Check whether its companion package is installed before use.
+
+Keep test reports separate from coverage reports. A passing machine report does not establish coverage thresholds or external service acceptance. Check the command exit status as well as the report file.
+
+Source: [Reporters](https://vitest.dev/guide/reporters).

package/template/.agents/skills/vitest/references/features-snapshots.md

@@ -0,0 +1,23 @@
+# Snapshots
+
+Use snapshots for output whose complete shape matters. Use direct assertions when a small contract gives clearer failure evidence.
+
+```ts
+import { describe, expect, test } from "vitest";
+
+describe("status serialization", () => {
+  test("keeps the status text", () => {
+    expect("ready").toMatchInlineSnapshot('"ready"');
+  });
+});
+```
+
+Use `toMatchSnapshot` for a separate snapshot file. Use `toMatchInlineSnapshot` when the expected output belongs beside the test. Await `toMatchFileSnapshot` for a file comparison.
+
+Stabilize dates, generated identifiers, and ordering before snapshot comparison. Use property matchers when specific values may vary. Use custom serializers only when they improve the result's meaning.
+
+Inspect each snapshot change before acceptance. Run `vitest run <file> --update` through the local runner for an intended update. Commit the snapshot with its test. An update can record a defect if the received output is wrong.
+
+Use the context's `expect` for concurrent tests. Browser screenshots and ARIA snapshots require their applicable browser APIs. A DOM serialization does not prove layout, focus behavior, or accessibility.
+
+Source: [Snapshots](https://vitest.dev/guide/snapshot).

package/template/.agents/skills/vitest/references/features-test-tags.md

@@ -0,0 +1,30 @@
+# Test tags
+
+Tags require Vitest 4.1 or later. Use tags for categories that span files and share timeout or retry options. Use projects when environments or worker settings differ.
+
+Declare each tag in the configuration:
+
+```ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    tags: [{ name: "database", timeout: 30_000 }, { name: "slow" }],
+  },
+});
+```
+
+Apply `{ tags: ["database"] }` in a test's options. Suite tags apply to child tests. A `@module-tag` comment applies to all tests in the file. Unknown tags fail by default through `strictTags`. Keep this check unless the task requires permissive tags.
+
+Run tag commands through the local installation:
+
+```sh
+npm exec --no -- vitest run --tags-filter "database && !slow"
+npm exec --no -- vitest --list-tags
+```
+
+Expressions support conjunction, disjunction, negation, parentheses, and wildcard names. When tags conflict, lower numeric priorities win. Tag order resolves remaining conflicts. Explicit test options take priority over tags.
+
+Use `TestRunner.matchesTags` when expensive setup depends on the active tag expression. Check its installed API before use. Do not add retries to a tag as the only correction for unstable tests.
+
+Sources: [Test tags](https://vitest.dev/guide/test-tags), [Tag configuration](https://vitest.dev/config/tags).

package/template/.agents/skills/vitest/references/version-compatibility.md

@@ -0,0 +1,19 @@
+# Version compatibility
+
+Use installed package types when documentation describes a different release. Use versioned documentation for Vitest 4 tasks.
+
+| Area | Vitest 5 behavior | Action |
+| --- | --- | --- |
+| Runtime | Requires Node.js 22.12 or later and Vite 6.4 or later | Check the installed package's engine constraints. |
+| Mock history | `clearMocks` defaults to `true` | Make required calls inside each test or its setup. |
+| Name filters | Full names use `>` between suite segments | Match one segment or use an explicit separator. |
+| Inline projects | Root configuration applies by default | Inspect inherited arrays and setup files. |
+| Referenced projects | Configuration files retain independent settings | Share configuration explicitly when necessary. |
+| Hoisted mocks | Nested `vi.mock`, `vi.unmock`, and `vi.hoisted` calls throw | Put these calls at module scope. |
+| Benchmarks | Tests receive the `bench` fixture | Replace top-level `bench` imports during migration. |
+
+Inline projects can share their declaring Vite server in Vitest 5. Inspect plugin initialization when project behavior changes. Use `sharedViteServer: false` only when separate initialization is necessary.
+
+Vitest 4 benchmark examples use a different API. Do not copy them into Vitest 5 tests. Keep companion Vitest packages aligned with the runner version.
+
+Sources: [Vitest 5 migration](https://vitest.dev/guide/migration/), [Vitest 4 documentation](https://v4.vitest.dev/guide/).

package/template/.claude/CLAUDE.md

@@ -12,9 +12,9 @@ Oxlint + Oxfmt (the underlying engine) provides robust linting and formatting. M
 
 ---
 
-## Monolayer Application Permissions
+## Application Permissions
 
-Preserve existing authentication and workspace role behavior during feature work, including demos. Use [monolayer-application-permissions](.agents/skills/monolayer-application-permissions/SKILL.md) for application content access, editing interactions, or authentication/context changes.
+Preserve existing authentication and workspace role behavior during feature work, including demos. Use [application-permissions](.agents/skills/application-permissions/SKILL.md) for application content access, editing interactions, or authentication/context changes.
 
 The default development role is `owner`, so testing only with that role can miss permission errors affecting other users. When verifying role-dependent behavior, temporarily change the role in the `import.meta.env.DEV` branch of [lib/user-context.server.ts](lib/user-context.server.ts):
 

package/template/.react-router/types/+routes.ts

@@ -0,0 +1,41 @@
+// Generated by React Router
+
+import "react-router"
+
+declare module "react-router" {
+  interface Register {
+    pages: Pages
+    routeFiles: RouteFiles
+    routeModules: RouteModules
+  }
+}
+
+type Pages = {
+  "/": {
+    params: {};
+  };
+  "/resources/files": {
+    params: {};
+  };
+};
+
+type RouteFiles = {
+  "root.tsx": {
+    id: "root";
+    page: "/" | "/resources/files";
+  };
+  "routes/home.tsx": {
+    id: "routes/home";
+    page: "/";
+  };
+  "routes/files.ts": {
+    id: "routes/files";
+    page: "/resources/files";
+  };
+};
+
+type RouteModules = {
+  "root": typeof import("./app/root.tsx");
+  "routes/home": typeof import("./app/routes/home.tsx");
+  "routes/files": typeof import("./app/routes/files.ts");
+};

package/template/.react-router/types/+server-build.d.ts

@@ -0,0 +1,18 @@
+// Generated by React Router
+
+declare module "virtual:react-router/server-build" {
+  import { ServerBuild } from "react-router";
+  export const assets: ServerBuild["assets"];
+  export const assetsBuildDirectory: ServerBuild["assetsBuildDirectory"];
+  export const basename: ServerBuild["basename"];
+  export const entry: ServerBuild["entry"];
+  export const future: ServerBuild["future"];
+  export const isSpaMode: ServerBuild["isSpaMode"];
+  export const prerender: ServerBuild["prerender"];
+  export const publicPath: ServerBuild["publicPath"];
+  export const routeDiscovery: ServerBuild["routeDiscovery"];
+  export const routes: ServerBuild["routes"];
+  export const ssr: ServerBuild["ssr"];
+  export const allowedActionOrigins: ServerBuild["allowedActionOrigins"];
+  export const unstable_getCriticalCss: ServerBuild["unstable_getCriticalCss"];
+}