create-monolayer-app 0.5.1 → 0.6.1

package/template/.agents/skills/kysely/references/official-docs-map.md

@@ -0,0 +1,97 @@
+# Official Kysely PostgreSQL documentation map
+
+This map points to the PostgreSQL sections represented in `https://kysely.dev/llms-full.txt`.
+
+The source was retrieved on 2026-08-22. Open the source page when an exact API detail can change the implementation.
+
+## Start and setup
+
+| Topic | Official source | Use |
+| --- | --- | --- |
+| Introduction | https://kysely.dev/docs/intro.md | Product scope and type inference |
+| Getting started | https://kysely.dev/docs/getting-started.md | PostgreSQL installation, types, instance, and CRUD |
+| PostgreSQL dialect | https://kysely-org.github.io/kysely-apidoc/classes/PostgresDialect.html | `PostgresDialect` setup and configuration |
+| Generating types | https://kysely.dev/docs/generating-types.md | Schema type generators |
+| Supabase | https://kysely.dev/docs/integrations/supabase.md | Supabase type translation |
+| LLM documents | https://kysely.dev/docs/integrations/llms.md | Official LLM document policy |
+
+## Query examples
+
+| Group | Example | Official source |
+| --- | --- | --- |
+| CTE | Data changes | https://kysely.dev/docs/examples/cte/inserts-updates-and-deletions.md |
+| CTE | Selects | https://kysely.dev/docs/examples/cte/simple-selects.md |
+| Delete | One row | https://kysely.dev/docs/examples/delete/single-row.md |
+| Insert | Complex values | https://kysely.dev/docs/examples/insert/complex-values.md |
+| Insert | Subquery | https://kysely.dev/docs/examples/insert/insert-subquery.md |
+| Insert | Multiple rows | https://kysely.dev/docs/examples/insert/multiple-rows.md |
+| Insert | Returning data | https://kysely.dev/docs/examples/insert/returning-data.md |
+| Insert | One row | https://kysely.dev/docs/examples/insert/single-row.md |
+| Join | Aliased inner join | https://kysely.dev/docs/examples/join/aliased-inner-join.md |
+| Join | Complex join | https://kysely.dev/docs/examples/join/complex-join.md |
+| Join | Simple inner join | https://kysely.dev/docs/examples/join/simple-inner-join.md |
+| Join | Subquery join | https://kysely.dev/docs/examples/join/subquery-join.md |
+| Merge | Source row existence | https://kysely.dev/docs/examples/merge/source-row-existence.md |
+| Merge | Temporary changes table | https://kysely.dev/docs/examples/merge/temporary-changes-table.md |
+| Select | One column | https://kysely.dev/docs/examples/select/a-single-column.md |
+| Select | Aliases | https://kysely.dev/docs/examples/select/aliases.md |
+| Select | All columns | https://kysely.dev/docs/examples/select/all-columns.md |
+| Select | All table columns | https://kysely.dev/docs/examples/select/all-columns-of-a-table.md |
+| Select | Qualified column | https://kysely.dev/docs/examples/select/column-with-a-table.md |
+| Select | Complex selections | https://kysely.dev/docs/examples/select/complex-selections.md |
+| Select | Distinct | https://kysely.dev/docs/examples/select/distinct.md |
+| Select | Distinct on | https://kysely.dev/docs/examples/select/distinct-on.md |
+| Select | Function calls | https://kysely.dev/docs/examples/select/function-calls.md |
+| Select | Generic find query | https://kysely.dev/docs/examples/select/generic-find-query.md |
+| Select | Multiple columns | https://kysely.dev/docs/examples/select/multiple-columns.md |
+| Select | Nested array | https://kysely.dev/docs/examples/select/nested-array.md |
+| Select | Nested object | https://kysely.dev/docs/examples/select/nested-object.md |
+| Select | Not null | https://kysely.dev/docs/examples/select/not-null.md |
+| Transaction | Controlled | https://kysely.dev/docs/examples/transactions/controlled-transaction.md |
+| Transaction | Savepoints | https://kysely.dev/docs/examples/transactions/controlled-transaction-w-savepoints.md |
+| Transaction | Callback | https://kysely.dev/docs/examples/transactions/simple-transaction.md |
+| Update | Complex values | https://kysely.dev/docs/examples/update/complex-values.md |
+| Update | One row | https://kysely.dev/docs/examples/update/single-row.md |
+| Where | Complex clause | https://kysely.dev/docs/examples/where/complex-where-clause.md |
+| Where | Conditional calls | https://kysely.dev/docs/examples/where/conditional-where-calls.md |
+| Where | Object filter | https://kysely.dev/docs/examples/where/object-filter.md |
+| Where | OR | https://kysely.dev/docs/examples/where/or-where.md |
+| Where | Simple clause | https://kysely.dev/docs/examples/where/simple-where-clause.md |
+| Where | IN | https://kysely.dev/docs/examples/where/where-in.md |
+
+Each official page links to exact builder signatures in the generated API documentation.
+
+## System behavior
+
+| Topic | Official source | Use |
+| --- | --- | --- |
+| Execution flow | https://kysely.dev/docs/execution.md | Query transformation, compilation, `pg` work, and result transformation |
+| Migrations | https://kysely.dev/docs/migrations.md | Migration files, order, providers, and locks |
+| Plugin system | https://kysely.dev/docs/plugins.md | Plugin registration and built-in plugins |
+| Playground | https://kysely.dev/docs/playground.md | Query experiments and examples |
+
+## Recipes
+
+| Topic | Official source |
+| --- | --- |
+| Conditional selects | https://kysely.dev/docs/recipes/conditional-selects.md |
+| Data types | https://kysely.dev/docs/recipes/data-types.md |
+| Deduplicate joins | https://kysely.dev/docs/recipes/deduplicate-joins.md |
+| Deep TypeScript types | https://kysely.dev/docs/recipes/excessively-deep-types.md |
+| Expressions | https://kysely.dev/docs/recipes/expressions.md |
+| Extending Kysely | https://kysely.dev/docs/recipes/extending-kysely.md |
+| Introspection | https://kysely.dev/docs/recipes/introspecting-relation-metadata.md |
+| Logging | https://kysely.dev/docs/recipes/logging.md |
+| Raw SQL | https://kysely.dev/docs/recipes/raw-sql.md |
+| Reusable helpers | https://kysely.dev/docs/recipes/reusable-helpers.md |
+| Database schemas | https://kysely.dev/docs/recipes/schemas.md |
+| Split build and execution | https://kysely.dev/docs/recipes/splitting-query-building-and-execution.md |
+
+## Exact APIs
+
+Use the generated API documentation for classes, interfaces, overloads, and version-specific examples:
+
+- https://kysely-org.github.io/kysely-apidoc/
+- The declaration files in the installed `kysely` package
+
+Prefer local declarations when the installed package version differs from the current website.

package/template/.agents/skills/kysely/references/query-building.md

@@ -0,0 +1,119 @@
+# Query building
+
+Use this reference for query structure and execution methods. Check the official API types for exact overloads.
+
+## Selects
+
+Start with `selectFrom`. Select only the columns required by the consumer.
+
+```typescript
+const person = await db
+  .selectFrom("person")
+  .select(["id", "first_name", "last_name"])
+  .where("id", "=", personId)
+  .executeTakeFirst()
+```
+
+Use `selectAll("table")` when a consumer requires every table column. Use `as` aliases for stable result property names.
+
+Use these execution methods intentionally:
+
+| Method | Result |
+| --- | --- |
+| `execute()` | All result rows |
+| `executeTakeFirst()` | The first row or `undefined` |
+| `executeTakeFirstOrThrow()` | The first row or an exception |
+
+## Filters
+
+Repeated `where` calls use `AND`. Use the expression builder for grouped Boolean logic.
+
+```typescript
+const rows = await db
+  .selectFrom("person")
+  .selectAll()
+  .where(({ and, eb, or }) =>
+    or([
+      eb("status", "=", "active"),
+      and([
+        eb("status", "=", "pending"),
+        eb("created_at", ">", cutoff),
+      ]),
+    ])
+  )
+  .execute()
+```
+
+Use `whereRef` when both operands are column references. Use `is` and `is not` for explicit null comparisons.
+
+Reassign immutable builders when conditions add filters:
+
+```typescript
+let query = db.selectFrom("person").selectAll()
+
+if (firstName !== undefined) {
+  query = query.where("first_name", "=", firstName)
+}
+```
+
+## Joins and subqueries
+
+Use the short join overload for simple equality joins.
+
+```typescript
+const rows = await db
+  .selectFrom("person")
+  .innerJoin("pet", "pet.owner_id", "person.id")
+  .select(["person.id", "pet.name as pet_name"])
+  .execute()
+```
+
+Use a join callback for grouped conditions. Alias joined tables and subqueries when names can conflict.
+
+Correlate subqueries with `whereRef`. Add `as` when a selected expression needs a result property.
+
+## Inserts, updates, and deletes
+
+```typescript
+const inserted = await db
+  .insertInto("person")
+  .values(newPerson)
+  .returningAll()
+  .executeTakeFirstOrThrow()
+
+await db
+  .updateTable("person")
+  .set(personUpdate)
+  .where("id", "=", personId)
+  .executeTakeFirst()
+
+await db
+  .deleteFrom("person")
+  .where("id", "=", personId)
+  .executeTakeFirst()
+```
+
+Use PostgreSQL `RETURNING` through `returning` or `returningAll`. Check mutation metadata when the query returns no row data.
+
+Use an expression callback in `values` or `set` for subqueries, column calculations, or database functions.
+
+## CTEs and merge queries
+
+Use `with` for common table expressions. PostgreSQL CTEs can contain supported data changes.
+
+Use `withRecursive` for recursive CTEs. Keep the anchor and recursive member types compatible.
+
+Use `mergeInto` only when the PostgreSQL server supports `MERGE`. Model every matched and unmatched branch explicitly.
+
+## PostgreSQL checks
+
+Confirm these features before a query uses them:
+
+- `RETURNING`
+- `DISTINCT ON`
+- Data-changing CTEs
+- `MERGE` support in the server version
+- `UPDATE FROM`
+- JSON and JSONB functions
+- Row lock clauses
+- PostgreSQL data types, defaults, and extensions

package/template/.agents/skills/kysely/references/transactions.md

@@ -0,0 +1,47 @@
+# Transactions
+
+Use this reference for atomic work, controlled transactions, and savepoints.
+
+## Callback transactions
+
+Use a callback transaction for normal atomic work.
+
+```typescript
+const pet = await db.transaction().execute(async (trx) => {
+  const person = await trx
+    .insertInto("person")
+    .values(newPerson)
+    .returning("id")
+    .executeTakeFirstOrThrow()
+
+  return trx
+    .insertInto("pet")
+    .values({ ...newPet, owner_id: person.id })
+    .returningAll()
+    .executeTakeFirstOrThrow()
+})
+```
+
+The callback commits when it returns. An exception rolls back the transaction and returns the exception to the caller.
+
+Pass `trx` to all repository functions that participate in the transaction. Avoid accidental calls through the root `db` instance.
+
+## Controlled transactions
+
+Use a controlled transaction when the code must select the commit or rollback point.
+
+```typescript
+const trx = await db.startTransaction().execute()
+
+try {
+  await doWork(trx)
+  await trx.commit().execute()
+} catch (error) {
+  await trx.rollback().execute()
+  throw error
+}
+```
+
+Use `savepoint`, `rollbackToSavepoint`, and `releaseSavepoint` for a recoverable part of a controlled transaction.
+
+Confirm PostgreSQL and `pg` behavior for transaction settings, savepoints, isolation levels, and access modes.

package/template/.agents/skills/kysely/references/troubleshooting-and-boundaries.md

@@ -0,0 +1,67 @@
+# Troubleshooting and boundaries
+
+Use this reference when TypeScript output, `pg` output, PostgreSQL behavior, or Kysely scope is unclear.
+
+## Type and runtime mismatch
+
+Kysely types cannot convert `pg` values. First inspect the PostgreSQL value and the `pg` parser.
+
+Then align the `Database` type with the observed runtime value. Configure a `pg` parser when the application requires another value type.
+
+## Nullable results
+
+A SQL predicate can prove a column is not null while Kysely keeps its nullable type.
+
+Use `$narrowType<{ column: NotNull }>()` for a proven row property. Use `$notNull()` for a proven selected expression.
+
+Keep the proof next to the narrowing call. Joins, subqueries, and aggregate behavior can invalidate an assumed proof.
+
+## Deep TypeScript types
+
+Complex CTEs and nested helpers can cause TypeScript error TS2589. Use `$assertType<Shape>()` at a stable subquery boundary.
+
+Kysely requires the asserted type to be structurally equal. This method removes the complex internal type without reducing type safety.
+
+A display-only `Simplify<T>` helper does not remove the underlying complex type.
+
+## Conditional row shapes
+
+Direct reassignment loses added type information when `select`, `returning`, or a join changes the builder type.
+
+Use `$if` for optional row properties. Use separate code branches for distinct result unions.
+
+## Duplicate joins
+
+Independent conditional selections can add the same join more than once. Use `DeduplicateJoinsPlugin` when this dynamic design is necessary.
+
+The plugin compares query structures and can miss complex equivalent joins. Prefer one explicit join when the query can express that design clearly.
+
+## Relation loading
+
+Kysely has no relation model or automatic relation loader. Build the required SQL shape explicitly.
+
+Import `jsonArrayFrom` and `jsonObjectFrom` from `kysely/helpers/postgres`.
+
+These helpers use PostgreSQL JSON functions. Confirm that the `pg` configuration returns JSON and JSONB values with the expected runtime types.
+
+## Database schemas
+
+For a fixed schema set, use qualified table keys such as `user.permission` in the `Database` interface.
+
+For tenant schemas, use `db.withSchema(tenant)` after the application validates the tenant identifier.
+
+Explicitly qualified tables keep their schema under `withSchema`. Add those qualified names to the `Database` interface.
+
+## Raw SQL boundary
+
+Normal `sql` interpolation parameterizes values. Identifier and raw-text helpers insert SQL structure.
+
+Map external input to a fixed identifier allowlist before it reaches `sql.ref`, `sql.table`, `sql.id`, or `db.dynamic.ref`.
+
+Keep `sql.raw` for static or trusted SQL text. Give every `sql<T>` result the actual database output type.
+
+## PostgreSQL boundary
+
+When a query compiles but fails, compare the generated SQL with the PostgreSQL version and documentation.
+
+Check aliases, placeholders, `RETURNING`, JSON functions, `UPDATE FROM`, CTE behavior, merge clauses, and PostgreSQL data types.

package/template/.agents/skills/kysely/references/types.md

@@ -0,0 +1,58 @@
+# PostgreSQL types
+
+Use this reference for schema types, operation types, generated types, and `pg` runtime values.
+
+## Database type
+
+The `Database` interface maps each table name to one table interface.
+
+```typescript
+import type {
+  ColumnType,
+  Generated,
+  Insertable,
+  Selectable,
+  Updateable,
+} from "kysely"
+
+interface PersonTable {
+  id: Generated<number>
+  first_name: string
+  last_name: string | null
+  created_at: ColumnType<Date, string | undefined, never>
+}
+
+interface Database {
+  person: PersonTable
+}
+
+type Person = Selectable<PersonTable>
+type NewPerson = Insertable<PersonTable>
+type PersonUpdate = Updateable<PersonTable>
+```
+
+Table properties describe columns. Use `null` for a nullable PostgreSQL column.
+
+Keep table properties required. Kysely calculates operation-specific optional properties from column wrappers.
+
+Use `Generated<T>` for values that PostgreSQL generates. Use `ColumnType<Select, Insert, Update>` when operation types differ.
+
+Use `Selectable`, `Insertable`, and `Updateable` for application data. Keep table interfaces inside the `Database` type boundary.
+
+## Runtime values
+
+Kysely controls TypeScript types only. `pg` controls runtime JavaScript values.
+
+Align each column type with the value that `pg` returns. Configure `pg` parsers when the application requires different runtime values.
+
+## Generated types
+
+Production systems usually generate the `Database` type from the deployed PostgreSQL schema. Official documentation lists these third-party generators:
+
+- `kysely-codegen` for PostgreSQL schema introspection
+- `prisma-kysely` for Prisma schemas
+- `kanel-kysely` for PostgreSQL
+
+Verify generated types against `pg` output. Generator output cannot change runtime values.
+
+Supabase projects can translate generated Supabase types with `kysely-supabase` and `KyselifyDatabase`.

package/template/.agents/skills/persistent-app-data/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: persistent-app-data
+description: >
+  Add persistent data to applications through the existing DSQLKysely client.
+---
+
+# Persistent App Data
+
+Use Kysely through the existing `DSQLKysely` client for persistent application records.
+Keep database access in server code.
+
+## Sources and related skills
+
+Paths below refer to the application root, including applications copied from this template.
+
+- Read [lib/db/client.ts](../../../lib/db/client.ts) for the shared `db` export.
+- Read [migrations](references/migrations.md) when you create, apply, or reverse a schema migration.
+- Read [generated types](references/generated-types.md) when you generate or inspect database types after a schema change.
+- Use the adjacent [Kysely skill](../kysely/SKILL.md) for queries, expressions, transactions, and general migration guidance.
+- Use [Application Permissions](../application-permissions/SKILL.md) for shared content access and server writes.
+
+The application client and migration commands define the template-specific behavior.
+Apply these constraints when general Kysely guidance permits more PostgreSQL features.
+
+## Client and environment
+
+Import the shared `db` from `lib/db/client.ts` in server modules.
+Use the application import conventions for the relative path or alias.
+Do not create a separate client, pool, dialect, or ORM for feature code.
+Do not replace persistent records with browser storage, JSON files, or process memory.
+
+The [client implementation](../../../vendor/kysely-dsql/dsql/dsql-kysely.ts) selects the database from `NODE_ENV`:
+
+| `NODE_ENV`             | Database     | Configuration               |
+| ---------------------- | ------------ | --------------------------- |
+| `development` or unset | Local PGlite | `./.pglite_development`     |
+| `test`                 | Local PGlite | `./.pglite_test`            |
+| `production`           | Aurora DSQL  | Required `CLUSTER_ENDPOINT` |
+
+Other non-production values also select the development database.
+Local database paths depend on the process working directory.
+Run application commands from the application root.
+Keep local PGlite directories out of commits.
+
+## Schema and plugin rules
+
+Require an `updated_at` column with `timestamptz NOT NULL DEFAULT now()` on each application table.
+The default supplies the initial timestamp.
+
+The [plugin list](../../../vendor/kysely-dsql/plugins/index.ts) applies to the shared client.
+Do not disable these plugins to avoid the required column.
+
+- `CamelCasePlugin` maps camelCase application identifiers to snake_case SQL identifiers.
+- `AutoUpdatedAtPlugin` supplies `updated_at` on updates unless the query supplies that column.
+
+Use camelCase names in application queries and generated types, including `updatedAt`.
+
+Use the restricted schema builders from `DSQLKysely`.
+Keep schema changes within the restrictions in [compatibility-rules.ts](../../../vendor/kysely-dsql/dsql/compatibility-rules.ts).
+Do not bypass restrictions through casts, another dialect, or raw SQL.
+Check UUID identifiers when a design would otherwise need auto-increment columns.
+
+The local PGlite dialect does not use the production DSQL query compiler.
+A successful local query does not prove production SQL compatibility.
+Inspect the production compiler and restricted builders when a change needs indexes or uncommon SQL.
+The current compiler supplies asynchronous index syntax in production.
+
+## Verification
+
+Verify that saved records survive the required reload or restart.
+Verify viewer denial and permitted writer behavior when server writes change.
+
+Report local results separately from production DSQL verification.
+Identify any unverified SQL compatibility or migration behavior in the completion report.

package/template/.agents/skills/persistent-app-data/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Persistent App Data"
+  short_description: "Use the existing DSQL client and migrations"
+  default_prompt: "Use $persistent-app-data to add persistent data to this application."

package/template/.agents/skills/persistent-app-data/references/generated-types.md

@@ -0,0 +1,23 @@
+# Generated types
+
+Generate the database types from the migrated development database before test or production use.
+Run the commands from the application root.
+
+## Generator behavior
+
+The [generator](../../../../vendor/kysely-dsql/generator/generate-types-from-pglite.ts) reads `./.pglite_development`.
+It writes `lib/db/db.ts` and table files under `lib/db/tables/`.
+It skips type generation when `NODE_ENV` equals `test` or `production`.
+The post-migration hooks still call the generator in those environments.
+
+Use `NODE_ENV=development npm run db:create-types` to generate types separately.
+For schema changes, use the [migration procedure](migrations.md#creating-and-applying-a-migration).
+Its post-migration hook generates the types after a successful migration.
+
+## Generated files
+
+Use the same generated types in all environments.
+Do not hand-edit `db.ts` or generated table files.
+Include generated changes with their schema migrations.
+Use the generated row, insert, and update types when applicable.
+Check that the generated types match the migrated schema.

package/template/.agents/skills/persistent-app-data/references/migrations.md

@@ -0,0 +1,68 @@
+# Migrations
+
+Use the application migration commands to create, apply, or reverse schema changes.
+Run the commands from the application root.
+
+## Sources and constraints
+
+Read [package.json](../../../../package.json) for the database commands and lifecycle hooks.
+Read [.config/kysely.config.ts](../../../../.config/kysely.config.ts) for migration configuration.
+
+Inspect the existing migrations before a schema change.
+Keep the generated `DSQLKysely<any>` parameter in `up` and `down`.
+Do not import the current `Database` type into historical migrations.
+Implement the forward change in `up` and the reverse change in `down`.
+Report any reverse operation that can remove saved data.
+
+The migration configuration disables transactions around migrations.
+Do not assume that a failed migration rolls back earlier statements.
+Check reverse migrations only against disposable local data.
+
+## Commands
+
+Use `npm run` so the existing post-migration hooks execute.
+
+| Command                             | Result                                                                       |
+| ----------------------------------- | ---------------------------------------------------------------------------- |
+| `npm run migrate:make -- add-tasks` | Creates an empty timestamped migration in `lib/db/migrations/`.              |
+| `npm run migrate:latest`            | Applies all pending migrations. Runs the type generation hook after success. |
+| `npm run migrate:up`                | Applies one pending migration. Runs the type generation hook after success.  |
+| `npm run migrate:down`              | Reverses one applied migration. Runs the type generation hook after success. |
+| `npm run migrate:list`              | Lists migrations and their status.                                           |
+
+Use lowercase letters, digits, and single hyphens for migration names.
+Replace `add-tasks` with the name of the required change.
+
+## Creating and applying a migration
+
+Use this procedure for a schema change in the development database.
+
+1. **Create the migration** with `npm run migrate:make -- <name>`.
+2. **Implement `up` and `down`** with the restricted schema API.
+3. **Run `NODE_ENV=development npm run migrate:latest`.**
+4. **Inspect the generated database and table types.** See [generated types](generated-types.md).
+5. If the requested feature needs server queries, **implement them through the shared `db`.**
+6. **Run the checks** that cover the changed behavior.
+
+The development database contains the schema changes.
+The post-migration hook generates the types from that database.
+
+## Deployed database
+
+The built image decides the deployed database. The `pg` dependency adds the `monolayer/postgres` buildpack, so the deployment creates one Aurora DSQL cluster for the application. The `lib/db/migrations/` directory adds the `monolayer/kysely-migrations` buildpack. Each deployment then runs `migrate:latest` before it changes the web function.
+
+A failed migration stops the deployment, and the previous version continues to serve traffic. Do not remove `pg` from a deployed application. The deployment fails, and the database stays.
+
+Apply these rules to each migration:
+
+- Use one DDL statement in each migration. DSQL permits one DDL statement in a transaction and no DDL with DML.
+- Write DDL that can run again, for example `ifNotExists()` on a table.
+- Write additive changes only. The previous version continues to use the database during the migration.
+- Do not use `migrate:down` to undo a deployment.
+- Wait for asynchronous index jobs when later code needs the index.
+
+## Verification
+
+Run `NODE_ENV=development npm run migrate:list` after a development migration.
+Apply migrations separately with `NODE_ENV=test npm run migrate:latest` before tests that need the local test database.
+Check that schema changes generate the expected types without manual edits.

package/template/.agents/skills/vitest/GENERATION.md

@@ -0,0 +1,25 @@
+# Generation information
+
+- Refresh date: 2026-10-17.
+- Target: Vitest 5.
+- Template installation: Vitest 5.0.5.
+- Primary source: [official Vitest documentation](https://vitest.dev/).
+- Source index: [documentation for agents](https://vitest.dev/llms.txt).
+- Version changes: [Vitest 5 migration guide](https://vitest.dev/guide/migration/).
+
+The previous skill records generation on 2026-06-22 from commit `3f60d0893affbda989404555136fe20a6086d4e6`. This refresh uses the published documentation and the installed package types. It does not claim a Git commit for the published website. The original skill credits Anthony Fu.
+
+Each reference links to its applicable official sources. The summaries use Simplified Technical English. Existing reference filenames remain available.
+
+## Refresh procedure
+
+1. Check the target manifest, lockfile, installed version, configuration, and adjacent tests.
+2. Read the applicable official documentation.
+3. Compare version changes with the installed package types.
+4. Update the affected summaries and examples.
+5. Record the refresh date and verified version here.
+6. Validate the skill frontmatter and local links.
+7. Format the changed Markdown files.
+8. Review the full diff for architecture canvas impact.
+
+Do not change application dependencies or test configuration as part of a documentation refresh.

package/template/.agents/skills/vitest/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: vitest
+description: Write, debug, and configure Vitest tests. Use for assertions, mocks, fixtures, coverage, filtering, environments, projects, snapshots, benchmarks, and type tests.
+metadata:
+  author: Anthony Fu
+  version: "2026.10.17"
+  source: Regenerated from official Vitest documentation at https://vitest.dev
+---
+
+# Vitest
+
+Write tests that check observable behavior. Use the installed Vitest version and the application configuration as the API authority.
+
+## Workflow
+
+1. Read the application guide, package manifest, lockfile, Vitest configuration, and adjacent tests.
+2. Check the installed Vitest version and its package exports.
+3. Select the applicable reference below.
+4. Write tests for the changed behavior and its relevant failure conditions.
+5. Run the focused tests with the application's local Vitest installation.
+6. Complete the checks that the repository requires for the change.
+
+Use explicit imports from `vitest` unless the application enables globals. Keep assertions inside test callbacks. Use `async` callbacks for asynchronous tests. Await promise assertions and asynchronous cleanup.
+
+Keep committed tests free of `.only` and `.skip`. Use typed mocks at external service boundaries. Keep coverage thresholds and source boundaries unchanged.
+
+A focused run gives development feedback. It does not replace complete coverage when the repository requires coverage. Report assertion failures, execution restrictions, and missing dependencies separately.
+
+## Version boundary
+
+These references target Vitest 5. The template manifest declares `^5.0.0`. Its lockfile and installed package resolve to `5.0.5` at regeneration. The parent monorepo uses a separate Vitest 4 catalog.
+
+Use the target application's installation for commands. Do not infer its version from the parent workspace. Read [version compatibility](references/version-compatibility.md) before migration work or work with another major version. Read [generation information](GENERATION.md) for the source and refresh procedure.
+
+## Reference map
+
+Read only the references that apply to the task.
+
+| Task                                      | Reference                                           |
+| ----------------------------------------- | --------------------------------------------------- |
+| Configure discovery, aliases, or setup    | [Configuration](references/core-config.md)          |
+| Run tests or inspect CLI options          | [CLI](references/core-cli.md)                       |
+| Define tests, options, or data cases      | [Test API](references/core-test-api.md)             |
+| Group tests and apply suite options       | [Describe API](references/core-describe.md)         |
+| Select assertions or await results        | [Expect API](references/core-expect.md)             |
+| Set up resources and release them         | [Hooks](references/core-hooks.md)                   |
+| Mock modules and service boundaries       | [Mocking](references/features-mocking.md)           |
+| Select mock cleanup or timer utilities    | [Vi utilities](references/advanced-vi.md)           |
+| Create or update snapshots                | [Snapshots](references/features-snapshots.md)       |
+| Configure and verify coverage             | [Coverage](references/features-coverage.md)         |
+| Share fixtures and test context           | [Test context](references/features-context.md)      |
+| Select parallel execution settings        | [Concurrency](references/features-concurrency.md)   |
+| Select files, names, or changed tests     | [Filtering](references/features-filtering.md)       |
+| Apply category options and tag filters    | [Test tags](references/features-test-tags.md)       |
+| Configure terminal or CI reports          | [Reporters](references/features-reporters.md)       |
+| Measure performance                       | [Benchmarking](references/features-benchmarking.md) |
+| Select Node.js, DOM, or browser execution | [Environments](references/advanced-environments.md) |
+| Check TypeScript contracts                | [Type testing](references/advanced-type-testing.md) |
+| Configure multiple test projects          | [Projects](references/advanced-projects.md)         |