From ffb139b83092b93f4332dfae5409b83aafa8d22e Mon Sep 17 00:00:00 2001
From: Lewan24
Date: Tue, 16 Sep 2025 12:10:55 +0200
Subject: [PATCH 01/19] add file to automate building and punhing to docker hub
repo. Modify docker-compose to use image from dockerhub
---
DbBackupService/buildAndDeployDocker.bat | 3 +++
DbBackupService/docker-compose.yml | 31 +++++++++++++++---------
2 files changed, 23 insertions(+), 11 deletions(-)
create mode 100644 DbBackupService/buildAndDeployDocker.bat
diff --git a/DbBackupService/buildAndDeployDocker.bat b/DbBackupService/buildAndDeployDocker.bat
new file mode 100644
index 0000000..13b0ec6
--- /dev/null
+++ b/DbBackupService/buildAndDeployDocker.bat
@@ -0,0 +1,3 @@
+docker build -t lewan24/octobackup:latest -f ./Src/Bootstraper/Server/Server.Api/Dockerfile .
+
+docker push lewan24/octobackup:latest
\ No newline at end of file
diff --git a/DbBackupService/docker-compose.yml b/DbBackupService/docker-compose.yml
index e2b1169..663bf82 100644
--- a/DbBackupService/docker-compose.yml
+++ b/DbBackupService/docker-compose.yml
@@ -1,25 +1,34 @@
services:
- server.api:
- image: server.api
+ octobackup:
+ # local testing
+ #image: server.api
+ image: lewan24/octobackup
container_name: octobackup
restart: always
- build:
- context: .
- dockerfile: Src/Bootstraper/Server/Server.Api/Dockerfile
+ # local testing
+ #build:
+ #context: .
+ #dockerfile: Src/Bootstraper/Server/Server.Api/Dockerfile
ports:
- "10000:80"
- "10443:443"
environment:
ASPNETCORE_ENVIRONMENT: Production
ASPNETCORE_URLS: "https://+;http://+"
- Kestrel__Certificates__Default__Path: "/app/Certificate/OctoBackupCert.pfx" # your cert, could be anything to only run if you use proxy
- Kestrel__Certificates__Default__Password: "Password" # generated cert password
+ # your cert, could be anything to only run if you use proxy
+ Kestrel__Certificates__Default__Path: "/app/Certificate/OctoBackupCert.pfx"
+ # generated cert password
+ Kestrel__Certificates__Default__Password: "Password"
# \/ change on production
- CRYPTO_KEY: "C5Znh9Rwota8gSeeTLCMn4ag0OvD5vI9aj0me39/G0g=" # base64 crypto key used to encrypt data
+ # base64 crypto key used to encrypt data
+ CRYPTO_KEY: "C5Znh9Rwota8gSeeTLCMn4ag0OvD5vI9aj0me39/G0g="
volumes:
- - ./certs/:/app/Certificate/:ro # certificate location
- #- serviceDb:/db # local database with users, app data, settings etc.
- #- backups:/backups # directory where all backups made are stored. You can bind it to external server
+ # certificate location
+ - ./certs/:/app/Certificate/:ro
+ # local database with users, app data, settings etc.
+ #- serviceDb:/db
+ # directory where all backups made are stored. You can bind it to external server
+ #- backups:/backups
# uncomment to bind local db and backups directories
#volumes:
From 579a819da5ef4a5a04dc5bdd9a3a1b033133e9eb Mon Sep 17 00:00:00 2001
From: Lewan24
Date: Tue, 16 Sep 2025 12:41:26 +0200
Subject: [PATCH 02/19] Update script
---
DbBackupService/buildAndDeployDocker.bat | 1 -
1 file changed, 1 deletion(-)
diff --git a/DbBackupService/buildAndDeployDocker.bat b/DbBackupService/buildAndDeployDocker.bat
index 13b0ec6..44d5dd6 100644
--- a/DbBackupService/buildAndDeployDocker.bat
+++ b/DbBackupService/buildAndDeployDocker.bat
@@ -1,3 +1,2 @@
docker build -t lewan24/octobackup:latest -f ./Src/Bootstraper/Server/Server.Api/Dockerfile .
-
docker push lewan24/octobackup:latest
\ No newline at end of file
From 5bd0bed591d96fad3cab7ed3ee2af6789a16b031 Mon Sep 17 00:00:00 2001
From: Artur Lewandowski
Date: Fri, 10 Oct 2025 20:28:03 +0200
Subject: [PATCH 03/19] Update all nuget packages
---
.../Bootstraper/Client/Client.UI/Client.UI.csproj | 12 ++++++------
.../Bootstraper/Server/Server.Api/Server.Api.csproj | 10 +++++-----
.../Modules.Administration.Api.csproj | 4 ++--
.../Modules.Administration.Application.csproj | 8 ++++----
.../Modules.Administration.Shared.csproj | 2 +-
.../Modules.Auth.Api/Modules.Auth.Api.csproj | 6 +++---
.../Modules.Auth.Application.csproj | 10 +++++-----
.../Modules.Auth.Core/Modules.Auth.Core.csproj | 2 +-
.../Modules.Auth.Infrastructure.csproj | 10 +++++-----
.../Modules.Auth.Shared/Modules.Auth.Shared.csproj | 6 +++---
.../Modules.Backup.Api/Modules.Backup.Api.csproj | 2 +-
.../Modules.Backup.Application.csproj | 8 ++++----
.../Modules.Backup.Core/Modules.Backup.Core.csproj | 4 ++--
.../Modules.Backup.Infrastructure.csproj | 10 +++++-----
.../Modules.Crypto.Api/Modules.Crypto.Api.csproj | 2 +-
.../Modules.Crypto.Application.csproj | 4 ++--
.../Shared/Modules.Shared/Modules.Shared.csproj | 2 +-
17 files changed, 51 insertions(+), 51 deletions(-)
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj b/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj
index d69e034..dc43ea9 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj
@@ -8,13 +8,13 @@
-
-
+
+
-
-
-
-
+
+
+
+
diff --git a/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj b/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj
index 47d9e58..d717a60 100644
--- a/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj
+++ b/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj
@@ -11,16 +11,16 @@
-
-
-
+
+
+
all
runtime; build; native; contentfiles; analyzers; buildtransitive
-
+
-
+
diff --git a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj
index 3076d4e..6b87ce1 100644
--- a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj
+++ b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj
@@ -7,8 +7,8 @@
-
-
+
+
diff --git a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj
index 61d6c1b..2ea4e10 100644
--- a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj
+++ b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj
@@ -7,10 +7,10 @@
-
-
-
-
+
+
+
+
diff --git a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj
index a18c998..23e7245 100644
--- a/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj
+++ b/DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj
@@ -7,7 +7,7 @@
-
+
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj
index 2d55a5f..d39bca7 100644
--- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj
@@ -7,9 +7,9 @@
-
-
-
+
+
+
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj
index 9e9608e..19dc069 100644
--- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj
@@ -7,11 +7,11 @@
-
-
-
-
-
+
+
+
+
+
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj
index 16137a8..ff8066c 100644
--- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj
@@ -7,7 +7,7 @@
-
+
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj
index d7e62da..c2987fc 100644
--- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj
@@ -7,14 +7,14 @@
-
-
-
+
+
+
all
runtime; build; native; contentfiles; analyzers; buildtransitive
-
-
+
+
all
runtime; build; native; contentfiles; analyzers; buildtransitive
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj
index ad3439f..7a9ec3b 100644
--- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj
@@ -8,9 +8,9 @@
-
-
-
+
+
+
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj
index b4150cb..ff72da4 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj
@@ -7,7 +7,7 @@
-
+
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj
index 97cc065..5a6ccb8 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj
@@ -7,11 +7,11 @@
-
-
-
+
+
+
-
+
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj
index 914af75..88eacff 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj
@@ -11,8 +11,8 @@
-
-
+
+
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj
index 01b3154..1c8e642 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj
@@ -7,17 +7,17 @@
-
-
+
+
all
runtime; build; native; contentfiles; analyzers; buildtransitive
-
-
+
+
all
runtime; build; native; contentfiles; analyzers; buildtransitive
-
+
diff --git a/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj b/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj
index 34e04cd..487f897 100644
--- a/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj
+++ b/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj
@@ -7,7 +7,7 @@
-
+
diff --git a/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj b/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj
index c2de560..240f615 100644
--- a/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj
+++ b/DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj
@@ -7,8 +7,8 @@
-
-
+
+
diff --git a/DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj b/DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj
index b86eab4..289af4f 100644
--- a/DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj
+++ b/DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj
@@ -7,7 +7,7 @@
-
+
From db604a8c9f033514baa2565c936b6e6d028da5c9 Mon Sep 17 00:00:00 2001
From: Artur Lewandowski
Date: Fri, 10 Oct 2025 20:53:16 +0200
Subject: [PATCH 04/19] Update dockerfile for better security image
---
DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile | 4 ++--
1 file changed, 2 insertions(+), 2 deletions(-)
diff --git a/DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile b/DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile
index 9894e5b..a39765d 100644
--- a/DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile
+++ b/DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile
@@ -1,5 +1,5 @@
# ============= BUILD STAGE =============
-FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
+FROM mcr.microsoft.com/dotnet/sdk:9.0-bookworm-slim AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
@@ -18,7 +18,7 @@ RUN dotnet publish "Server.Api.csproj" \
# ============= RUNTIME STAGE =============
-FROM mcr.microsoft.com/dotnet/aspnet:9.0 AS runtime
+FROM mcr.microsoft.com/dotnet/aspnet:9.0-bookworm-slim AS runtime
WORKDIR /app
From 50dc548bbe16b4a1c60df15b6a57db6092e09294 Mon Sep 17 00:00:00 2001
From: artur
Date: Mon, 13 Oct 2025 10:01:35 +0200
Subject: [PATCH 05/19] Fix ports range Fix performed backup localization Fix
db localization
---
.../Dialogs/Servers/CreateServerDialog.razor | 8 +-
.../Dialogs/Servers/EditServerDialog.razor | 8 +-
.../Services/DbBackupService.cs | 10 +-
.../Entities/DbContext/DbServerConnection.cs | 2 +-
.../Entities/DbContext/DbServerTunnel.cs | 6 +-
.../BackupsDbContextModelSnapshot.cs | 10 +-
...1013075224_ChangeIntsToUShorts.Designer.cs | 291 ++++++++++++++++++
.../20251013075224_ChangeIntsToUShorts.cs | 22 ++
.../Dtos/ServerConnectionDto.cs | 4 +-
.../Dtos/ServerTunnelDto.cs | 9 +-
.../Shared/Modules.Shared/Common/DbCommon.cs | 6 +-
11 files changed, 347 insertions(+), 29 deletions(-)
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor
index 86a1156..e95d3ad 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor
@@ -29,7 +29,7 @@
For="@(() => _server.ServerHost)"/>
-
-
-
-
-
-
-
-
error => logger.LogWarning(error)
);
- if (!string.IsNullOrWhiteSpace(compressedFilename))
+ if (!string.IsNullOrWhiteSpace(newDbBackup.FilePath))
logger.LogInformation("Successfully created and compressed backup: [{Database}], [{ZipFile}]",
- db.GetDatabaseName(), compressedFilename);
+ db.GetDatabaseName(), newDbBackup.FilePath);
return new Success();
}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs
index ac4c39b..f7babfa 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs
@@ -8,7 +8,7 @@ public sealed record DbServerConnection
public bool IsDisabled { get; set; }
public string ConnectionName { get; set; } = "Example";
public required string ServerHost { get; set; }
- public required short ServerPort { get; set; }
+ public required ushort ServerPort { get; set; }
public required string DbName { get; set; }
public DatabaseType DbType { get; set; } = DatabaseType.MySql;
public required string DbUser { get; set; }
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs
index 45912c1..2f0cff7 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs
@@ -4,15 +4,15 @@ public sealed record DbServerTunnel
{
public Guid Id { get; init; } = Guid.CreateVersion7();
public required string ServerHost { get; set; }
- public int SshPort { get; set; } = 22;
+ public ushort SshPort { get; set; } = 22;
public required string Username { get; set; }
public bool UsePasswordAuth { get; set; } = true;
public string? Password { get; set; }
public string? PrivateKeyContent { get; set; }
public string? PrivateKeyPassphrase { get; set; }
- public int LocalPort { get; set; }
+ public ushort LocalPort { get; set; }
public required string RemoteHost { get; set; }
- public int RemotePort { get; set; }
+ public ushort RemotePort { get; set; }
public string? Description { get; set; }
public bool IsActive { get; set; }
}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
index 8aa73a4..712d263 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
@@ -15,7 +15,7 @@ partial class BackupsDbContextModelSnapshot : ModelSnapshot
protected override void BuildModel(ModelBuilder modelBuilder)
{
#pragma warning disable 612, 618
- modelBuilder.HasAnnotation("ProductVersion", "9.0.8");
+ modelBuilder.HasAnnotation("ProductVersion", "9.0.9");
modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b =>
{
@@ -125,7 +125,7 @@ protected override void BuildModel(ModelBuilder modelBuilder)
.IsRequired()
.HasColumnType("TEXT");
- b.Property("ServerPort")
+ b.Property("ServerPort")
.HasColumnType("INTEGER");
b.Property("TunnelId")
@@ -148,7 +148,7 @@ protected override void BuildModel(ModelBuilder modelBuilder)
b.Property("IsActive")
.HasColumnType("INTEGER");
- b.Property("LocalPort")
+ b.Property("LocalPort")
.HasColumnType("INTEGER");
b.Property("Password")
@@ -164,14 +164,14 @@ protected override void BuildModel(ModelBuilder modelBuilder)
.IsRequired()
.HasColumnType("TEXT");
- b.Property("RemotePort")
+ b.Property("RemotePort")
.HasColumnType("INTEGER");
b.Property("ServerHost")
.IsRequired()
.HasColumnType("TEXT");
- b.Property("SshPort")
+ b.Property("SshPort")
.HasColumnType("INTEGER");
b.Property("UsePasswordAuth")
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs
new file mode 100644
index 0000000..7e41884
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs
@@ -0,0 +1,291 @@
+//
+using System;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
+using Modules.Backup.Infrastructure.DbContexts;
+
+#nullable disable
+
+namespace Modules.Backup.Infrastructure.Migrations
+{
+ [DbContext(typeof(BackupsDbContext))]
+ [Migration("20251013075224_ChangeIntsToUShorts")]
+ partial class ChangeIntsToUShorts
+ {
+ ///
+ protected override void BuildTargetModel(ModelBuilder modelBuilder)
+ {
+#pragma warning disable 612, 618
+ modelBuilder.HasAnnotation("ProductVersion", "9.0.9");
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("AutomaticBackupTestConfigs");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupSchedule", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ConfigurationJson")
+ .HasColumnType("TEXT");
+
+ b.Property("DbConnectionId")
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("Name")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("NextBackupDate")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("Schedules");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupTest", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("BackupId")
+ .HasColumnType("TEXT");
+
+ b.Property("ErrorMessage")
+ .HasColumnType("TEXT");
+
+ b.Property("IsSuccess")
+ .HasColumnType("INTEGER");
+
+ b.Property("TestedOn")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("BackupsTests");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerConnection", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("AutoTestBackupsConfigId")
+ .HasColumnType("TEXT");
+
+ b.Property("BackupEncryptionKeyHas")
+ .HasColumnType("TEXT");
+
+ b.Property("ConnectionName")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbName")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbPasswd")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbType")
+ .HasColumnType("INTEGER");
+
+ b.Property("DbUser")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("IsDisabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("IsTunnelRequired")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("TunnelId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("DbConnections");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerTunnel", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("Description")
+ .HasColumnType("TEXT");
+
+ b.Property("IsActive")
+ .HasColumnType("INTEGER");
+
+ b.Property("LocalPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("Password")
+ .HasColumnType("TEXT");
+
+ b.Property("PrivateKeyContent")
+ .HasColumnType("TEXT");
+
+ b.Property("PrivateKeyPassphrase")
+ .HasColumnType("TEXT");
+
+ b.Property("RemoteHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("RemotePort")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("SshPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("UsePasswordAuth")
+ .HasColumnType("INTEGER");
+
+ b.Property("Username")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("DbServerTunnels");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.PerformedBackup", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("CreatedOn")
+ .HasColumnType("TEXT");
+
+ b.Property("FilePath")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("Name")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerConnectionId")
+ .HasColumnType("TEXT");
+
+ b.Property("TestId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("Backups");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServerBackupsConfiguration", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.Property("TimeInDaysToHoldBackups")
+ .HasColumnType("INTEGER");
+
+ b.HasKey("Id");
+
+ b.ToTable("Configurations");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServersUsers", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.Property("UserId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("UsersServers");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.UserNotificationsSettings", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnChanges")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnErrors")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnFailedBackups")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnFailedTests")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnSuccessfulBackup")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnUpdates")
+ .HasColumnType("INTEGER");
+
+ b.Property("UserId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("UsersNotificationsSettings");
+ });
+#pragma warning restore 612, 618
+ }
+ }
+}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs
new file mode 100644
index 0000000..a3d7494
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs
@@ -0,0 +1,22 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Modules.Backup.Infrastructure.Migrations
+{
+ ///
+ public partial class ChangeIntsToUShorts : Migration
+ {
+ ///
+ protected override void Up(MigrationBuilder migrationBuilder)
+ {
+
+ }
+
+ ///
+ protected override void Down(MigrationBuilder migrationBuilder)
+ {
+
+ }
+ }
+}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs
index 10a682d..c070a9e 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs
@@ -8,7 +8,9 @@ public record ServerConnectionDto
public Guid Id { get; init; } = Guid.CreateVersion7();
[Required] public string ConnectionName { get; set; } = "Example";
[Required] public required string ServerHost { get; set; }
- [Required] public required short ServerPort { get; set; }
+ [Required]
+ [Range(0, ushort.MaxValue)]
+ public required ushort ServerPort { get; set; }
[Required] public required string DbName { get; set; }
[Required] public DatabaseType DbType { get; set; } = DatabaseType.MySql;
[Required] public required string DbUser { get; set; }
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs
index 19c2997..0445ff2 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs
@@ -16,7 +16,8 @@ public record ServerTunnelDto
/// Port serwera SSH (domyślnie 22, w twoim przykładzie 80)
///
[Required]
- public int SshPort { get; set; } = 22;
+ [Range(0, ushort.MaxValue)]
+ public ushort SshPort { get; set; } = 22;
///
/// Użytkownik SSH (np. user)
@@ -48,7 +49,8 @@ public record ServerTunnelDto
/// Lokalny port, na którym wystawiony będzie tunel (np. 8543)
///
[Required]
- public int LocalPort { get; set; }
+ [Range(0, ushort.MaxValue)]
+ public ushort LocalPort { get; set; }
///
/// Zdalny host, do którego tunel ma przekierowywać (np. pgsqldomain.com)
@@ -60,7 +62,8 @@ public record ServerTunnelDto
/// Zdalny port usługi (np. 5432 dla PostgreSQL, 3306 dla MySQL)
///
[Required]
- public int RemotePort { get; set; }
+ [Range(0, ushort.MaxValue)]
+ public ushort RemotePort { get; set; }
///
/// Opis tunelu (opcjonalny, do UI)
diff --git a/DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs b/DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs
index 226cb54..82e1ea1 100644
--- a/DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs
+++ b/DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs
@@ -4,7 +4,7 @@ public static class DbCommon
{
private static readonly string DbFolder = GetDbDirectory();
- public static readonly string DbPath = Path.Join(DbFolder, "OctoBackup.db");
+ public static readonly string DbPath = Path.Join(DbFolder, "Config", "OctoBackup.db");
private static string GetDbDirectory()
=> Path.Combine(Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData), "OctoBackup");
@@ -13,5 +13,9 @@ public static void CreateDbDirectoryIfNotExists()
{
if (!Directory.Exists(DbFolder))
Directory.CreateDirectory(DbFolder);
+
+ var configDir = Path.GetDirectoryName(DbPath) ?? DbFolder;
+ if (!Directory.Exists(configDir))
+ Directory.CreateDirectory(configDir);
}
}
\ No newline at end of file
From d1258fe361cd77f187a6e55832edf1b146e8a9db Mon Sep 17 00:00:00 2001
From: artur
Date: Mon, 13 Oct 2025 10:26:53 +0200
Subject: [PATCH 06/19] Fix downloading backups
---
.../Modules.Backup.Application/Services/DbBackupService.cs | 6 +++++-
DbBackupService/buildAndDeployDocker.bat | 0
2 files changed, 5 insertions(+), 1 deletion(-)
mode change 100644 => 100755 DbBackupService/buildAndDeployDocker.bat
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
index e73e496..cbb8424 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
@@ -211,7 +211,11 @@ public async Task, string>> GetAllBackups(string?
var fileName = server is not null
? $"{server.DbName}_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip"
: $"DbBackup_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip";
- return (backup.FilePath, "application/zip", fileName);
+
+ if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development")
+ return (backup.FilePath, "application/zip", fileName);
+
+ return (Path.Combine("app", backup.FilePath), "application/zip", fileName);
}
private async Task> PerformBackup(List serversConnections)
diff --git a/DbBackupService/buildAndDeployDocker.bat b/DbBackupService/buildAndDeployDocker.bat
old mode 100644
new mode 100755
From 1a31c89aee98a2d53adf10e30a1302975e94aa5c Mon Sep 17 00:00:00 2001
From: artur
Date: Mon, 13 Oct 2025 10:36:59 +0200
Subject: [PATCH 07/19] Fix downloading backup
---
.../Modules.Backup.Application/Services/DbBackupService.cs | 5 +----
1 file changed, 1 insertion(+), 4 deletions(-)
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
index cbb8424..97461dc 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
@@ -212,10 +212,7 @@ public async Task, string>> GetAllBackups(string?
? $"{server.DbName}_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip"
: $"DbBackup_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip";
- if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development")
- return (backup.FilePath, "application/zip", fileName);
-
- return (Path.Combine("app", backup.FilePath), "application/zip", fileName);
+ return (backup.FilePath, "application/zip", fileName);
}
private async Task> PerformBackup(List serversConnections)
From 00421403f06e2eeb21dea6cad252b911eaf3ab3a Mon Sep 17 00:00:00 2001
From: artur
Date: Mon, 13 Oct 2025 11:28:52 +0200
Subject: [PATCH 08/19] Fix Downloading final fix
---
.../Modules.Backup.Application/Services/DbBackupService.cs | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
index 97461dc..53b4def 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
@@ -212,7 +212,7 @@ public async Task, string>> GetAllBackups(string?
? $"{server.DbName}_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip"
: $"DbBackup_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip";
- return (backup.FilePath, "application/zip", fileName);
+ return (Path.Combine(backup.FilePath), "application/zip", fileName);
}
private async Task> PerformBackup(List serversConnections)
From acc7c574f7268ca010ceef5956337f50413297f4 Mon Sep 17 00:00:00 2001
From: Artur Lewandowski
Date: Sat, 25 Oct 2025 23:14:48 +0200
Subject: [PATCH 09/19] Fix backup path for downloading. Implement ssl mode
selecting while creating and editing server. Implement selecting ssl mode in
servers connections. Add ssl boolean to server connection entity Add
migration
---
.../Dialogs/Servers/CreateServerDialog.razor | 9 +-
.../Dialogs/Servers/EditServerDialog.razor | 9 +-
.../Services/DbBackupService.cs | 9 +-
.../Services/ServersService.cs | 3 +
.../Static/ServerConnectionTester.cs | 8 +-
.../Entities/DbContext/DbServerConnection.cs | 1 +
.../20251025203420_AddSslToEntity.Designer.cs | 294 ++++++++++++++++++
.../20251025203420_AddSslToEntity.cs | 29 ++
.../BackupsDbContextModelSnapshot.cs | 3 +
.../Dtos/ServerConnectionDto.cs | 1 +
DbBackupService/docker-composetest.yml | 36 +++
11 files changed, 393 insertions(+), 9 deletions(-)
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs
create mode 100644 DbBackupService/docker-composetest.yml
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor
index e95d3ad..283695c 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor
@@ -70,11 +70,16 @@
For="@(() => _server.DbPasswd)"/>
-
-
+
+
+
+
+
@if (_server.IsTunnelRequired)
{
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor
index 693b629..8485ccd 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor
@@ -70,11 +70,16 @@
For="@(() => Server.DbPasswd)"/>
-
-
+
+
+
+
+
@if (Server.IsTunnelRequired)
{
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
index 53b4def..631a27a 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
@@ -211,8 +211,13 @@ public async Task, string>> GetAllBackups(string?
var fileName = server is not null
? $"{server.DbName}_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip"
: $"DbBackup_{backup.CreatedOn:yyyy-MM-dd_hh-mm}.zip";
-
- return (Path.Combine(backup.FilePath), "application/zip", fileName);
+
+ var filePath = backup.FilePath;
+ if (!Path.IsPathRooted(filePath))
+ filePath = Path.Combine(AppContext.BaseDirectory, filePath);
+
+ logger.LogInformation("Downloading {BackupPath}...", filePath);
+ return (filePath, "application/zip", fileName);
}
private async Task> PerformBackup(List serversConnections)
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs
index 962eb58..4d9d6c5 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs
@@ -76,6 +76,7 @@ public async Task, string>> GetServers(string? i
DbName = server.DbName,
DbType = server.DbType,
DbUser = server.DbUser,
+ SsL = server.SsL,
IsTunnelRequired = server.IsTunnelRequired,
AutoTestBackupsConfigId = server.AutoTestBackupsConfigId
};
@@ -209,6 +210,7 @@ public async Task> CreateServer(ServerConnectionDto newSe
DbType = newServer.DbType,
DbUser = newServer.DbUser,
DbPasswd = encryptedDbPasswd ?? throw new ArgumentException("Db password can't be null"),
+ SsL = newServer.SsL,
IsTunnelRequired = newServer.IsTunnelRequired,
IsDisabled = false
};
@@ -345,6 +347,7 @@ public async Task> EditServer(ServerConnectionDto server)
dbServer.DbName = server.DbName;
dbServer.DbType = server.DbType;
dbServer.DbUser = server.DbUser;
+ dbServer.SsL = server.SsL;
if (!string.IsNullOrWhiteSpace(server.DbPasswd))
{
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs
index 9ad1f3c..7a7b1f4 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs
@@ -80,7 +80,8 @@ internal static class ServerConnectionTester
Database = conn.DbName,
UserID = conn.DbUser,
Password = decryptedDbPasswd,
- ConnectionTimeout = 5
+ ConnectionTimeout = 5,
+ SslMode = conn.SsL ? MySqlSslMode.Required : MySqlSslMode.None,
}.ToString()),
DatabaseType.PostgreSql => new NpgsqlConnection(
@@ -92,7 +93,8 @@ internal static class ServerConnectionTester
Username = conn.DbUser,
Password = decryptedDbPasswd,
Timeout = 5,
- CommandTimeout = 5
+ CommandTimeout = 5,
+ SslMode = conn.SsL ? SslMode.Require : SslMode.Disable,
}.ToString()),
DatabaseType.SqlServer => new SqlConnection(
@@ -103,7 +105,7 @@ internal static class ServerConnectionTester
UserID = conn.DbUser,
Password = decryptedDbPasswd,
ConnectTimeout = 5,
- TrustServerCertificate = true
+ TrustServerCertificate = conn.SsL
}.ToString()),
_ => throw new NotSupportedException($"Unsupported DB type: {conn.DbType}")
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs
index f7babfa..a12c7a8 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs
@@ -13,6 +13,7 @@ public sealed record DbServerConnection
public DatabaseType DbType { get; set; } = DatabaseType.MySql;
public required string DbUser { get; set; }
public required string DbPasswd { get; set; }
+ public bool SsL { get; set; } = true;
public bool IsTunnelRequired { get; set; }
public Guid TunnelId { get; set; }
public string? BackupEncryptionKeyHas { get; set; }
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs
new file mode 100644
index 0000000..b81e3e1
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs
@@ -0,0 +1,294 @@
+//
+using System;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
+using Modules.Backup.Infrastructure.DbContexts;
+
+#nullable disable
+
+namespace Modules.Backup.Infrastructure.DbContexts.Migrations
+{
+ [DbContext(typeof(BackupsDbContext))]
+ [Migration("20251025203420_AddSslToEntity")]
+ partial class AddSslToEntity
+ {
+ ///
+ protected override void BuildTargetModel(ModelBuilder modelBuilder)
+ {
+#pragma warning disable 612, 618
+ modelBuilder.HasAnnotation("ProductVersion", "9.0.9");
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("AutomaticBackupTestConfigs");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupSchedule", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ConfigurationJson")
+ .HasColumnType("TEXT");
+
+ b.Property("DbConnectionId")
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("Name")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("NextBackupDate")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("Schedules");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupTest", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("BackupId")
+ .HasColumnType("TEXT");
+
+ b.Property("ErrorMessage")
+ .HasColumnType("TEXT");
+
+ b.Property("IsSuccess")
+ .HasColumnType("INTEGER");
+
+ b.Property("TestedOn")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("BackupsTests");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerConnection", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("AutoTestBackupsConfigId")
+ .HasColumnType("TEXT");
+
+ b.Property("BackupEncryptionKeyHas")
+ .HasColumnType("TEXT");
+
+ b.Property("ConnectionName")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbName")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbPasswd")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbType")
+ .HasColumnType("INTEGER");
+
+ b.Property("DbUser")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("IsDisabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("IsTunnelRequired")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("SsL")
+ .HasColumnType("INTEGER");
+
+ b.Property("TunnelId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("DbConnections");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerTunnel", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("Description")
+ .HasColumnType("TEXT");
+
+ b.Property("IsActive")
+ .HasColumnType("INTEGER");
+
+ b.Property("LocalPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("Password")
+ .HasColumnType("TEXT");
+
+ b.Property("PrivateKeyContent")
+ .HasColumnType("TEXT");
+
+ b.Property("PrivateKeyPassphrase")
+ .HasColumnType("TEXT");
+
+ b.Property("RemoteHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("RemotePort")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("SshPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("UsePasswordAuth")
+ .HasColumnType("INTEGER");
+
+ b.Property("Username")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("DbServerTunnels");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.PerformedBackup", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("CreatedOn")
+ .HasColumnType("TEXT");
+
+ b.Property("FilePath")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("Name")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerConnectionId")
+ .HasColumnType("TEXT");
+
+ b.Property("TestId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("Backups");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServerBackupsConfiguration", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.Property("TimeInDaysToHoldBackups")
+ .HasColumnType("INTEGER");
+
+ b.HasKey("Id");
+
+ b.ToTable("Configurations");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServersUsers", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.Property("UserId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("UsersServers");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.UserNotificationsSettings", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnChanges")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnErrors")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnFailedBackups")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnFailedTests")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnSuccessfulBackup")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnUpdates")
+ .HasColumnType("INTEGER");
+
+ b.Property("UserId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("UsersNotificationsSettings");
+ });
+#pragma warning restore 612, 618
+ }
+ }
+}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs
new file mode 100644
index 0000000..d3204e1
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs
@@ -0,0 +1,29 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Modules.Backup.Infrastructure.DbContexts.Migrations
+{
+ ///
+ public partial class AddSslToEntity : Migration
+ {
+ ///
+ protected override void Up(MigrationBuilder migrationBuilder)
+ {
+ migrationBuilder.AddColumn(
+ name: "SsL",
+ table: "DbConnections",
+ type: "INTEGER",
+ nullable: false,
+ defaultValue: false);
+ }
+
+ ///
+ protected override void Down(MigrationBuilder migrationBuilder)
+ {
+ migrationBuilder.DropColumn(
+ name: "SsL",
+ table: "DbConnections");
+ }
+ }
+}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
index 712d263..9ccb2e7 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
@@ -128,6 +128,9 @@ protected override void BuildModel(ModelBuilder modelBuilder)
b.Property("ServerPort")
.HasColumnType("INTEGER");
+ b.Property("SsL")
+ .HasColumnType("INTEGER");
+
b.Property("TunnelId")
.HasColumnType("TEXT");
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs
index c070a9e..cebe973 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs
@@ -15,6 +15,7 @@ public record ServerConnectionDto
[Required] public DatabaseType DbType { get; set; } = DatabaseType.MySql;
[Required] public required string DbUser { get; set; }
public string? DbPasswd { get; set; }
+ public bool SsL { get; set; } = true;
public bool IsTunnelRequired { get; set; }
public ServerTunnelDto? Tunnel { get; set; }
diff --git a/DbBackupService/docker-composetest.yml b/DbBackupService/docker-composetest.yml
new file mode 100644
index 0000000..030a236
--- /dev/null
+++ b/DbBackupService/docker-composetest.yml
@@ -0,0 +1,36 @@
+services:
+ octobackup:
+ # local testing
+ image: server.api
+ #image: lewan24/octobackup
+ container_name: octobackup
+ restart: always
+ # local testing
+ build:
+ context: .
+ dockerfile: Src/Bootstraper/Server/Server.Api/Dockerfile
+ ports:
+ - "10000:80"
+ - "10443:443"
+ environment:
+ ASPNETCORE_ENVIRONMENT: Production
+ ASPNETCORE_URLS: "https://+;http://+"
+ # your cert, could be anything to only run if you use proxy
+ Kestrel__Certificates__Default__Path: "/app/Certificate/OctoBackupCert.pfx"
+ # generated cert password
+ Kestrel__Certificates__Default__Password: "Password"
+ # \/ change on production
+ # base64 crypto key used to encrypt data
+ CRYPTO_KEY: "C5Znh9Rwota8gSeeTLCMn4ag0OvD5vI9aj0me39/G0g="
+ volumes:
+ # certificate location
+ - ./certs/:/app/Certificate/:ro
+ # local database with users, app data, settings etc.
+ - serviceDb:/app/OctoBackup/Config
+ # directory where all backups made are stored. You can bind it to external server
+ #- backups:/app/OctoBackup/backups
+
+# uncomment to bind local db and backups directories
+volumes:
+ serviceDb:
+ #backups:
\ No newline at end of file
From 3ddb684def9b8f30c8f49e6c499f8e2b1147c81e Mon Sep 17 00:00:00 2001
From: Artur Lewandowski
Date: Sat, 25 Oct 2025 23:27:38 +0200
Subject: [PATCH 10/19] Update docker compose files
---
DbBackupService/docker-compose.yml | 8 ++++----
.../{docker-composetest.yml => docker-composedev.yml} | 2 +-
2 files changed, 5 insertions(+), 5 deletions(-)
rename DbBackupService/{docker-composetest.yml => docker-composedev.yml} (96%)
diff --git a/DbBackupService/docker-compose.yml b/DbBackupService/docker-compose.yml
index 663bf82..3e1defa 100644
--- a/DbBackupService/docker-compose.yml
+++ b/DbBackupService/docker-compose.yml
@@ -26,10 +26,10 @@
# certificate location
- ./certs/:/app/Certificate/:ro
# local database with users, app data, settings etc.
- #- serviceDb:/db
- # directory where all backups made are stored. You can bind it to external server
- #- backups:/backups
-
+ #- serviceDb:/app/OctoBackup/Config
+ # directory where all backups made are stored. You can bind it to external server
+ #- backups:/app/OctoBackup/Backups
+
# uncomment to bind local db and backups directories
#volumes:
#serviceDb:
diff --git a/DbBackupService/docker-composetest.yml b/DbBackupService/docker-composedev.yml
similarity index 96%
rename from DbBackupService/docker-composetest.yml
rename to DbBackupService/docker-composedev.yml
index 030a236..7e1f4c1 100644
--- a/DbBackupService/docker-composetest.yml
+++ b/DbBackupService/docker-composedev.yml
@@ -28,7 +28,7 @@
# local database with users, app data, settings etc.
- serviceDb:/app/OctoBackup/Config
# directory where all backups made are stored. You can bind it to external server
- #- backups:/app/OctoBackup/backups
+ #- backups:/app/OctoBackup/Backups
# uncomment to bind local db and backups directories
volumes:
From 25118cd806c13c22ac4d2741ac2d53c7ef2b3ad1 Mon Sep 17 00:00:00 2001
From: Artur Lewandowski
Date: Sun, 26 Oct 2025 11:28:24 +0100
Subject: [PATCH 11/19] Implement profile panel. Implement changing password
and email Change dashboard design for user and admin
---
.../Client/Client.UI/Client.UI.csproj | 4 -
.../Client.UI/Data/Services/ProfileService.cs | 14 +++
.../AdministrationDashboard.razor | 24 ++--
.../Authorization/Account/ProfileIndex.razor | 113 ++++++++++++++++++
.../{Account => Common}/AuthorizeUser.razor | 1 +
.../{Account => Common}/ConfirmPassword.razor | 0
.../{Account => Common}/Login.razor | 0
.../{Account => Common}/Register.razor | 0
.../Client/Client.UI/Pages/Dashboard.razor | 27 ++---
.../Bootstraper/Client/Client.UI/Program.cs | 1 +
.../Endpoints/AuthEndpoints.cs | 4 +
.../Operations/AuthOperations.cs | 8 ++
.../Interfaces/IAuthService.cs | 1 +
.../Services/AuthService.cs | 36 +++++-
.../ActionsRequests/ChangeEmailRequest.cs | 13 ++
15 files changed, 203 insertions(+), 43 deletions(-)
create mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs
create mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor
rename DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/{Account => Common}/AuthorizeUser.razor (99%)
rename DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/{Account => Common}/ConfirmPassword.razor (100%)
rename DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/{Account => Common}/Login.razor (100%)
rename DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/{Account => Common}/Register.razor (100%)
create mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj b/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj
index dc43ea9..23f6918 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj
@@ -17,10 +17,6 @@
-
-
-
-
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs b/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs
new file mode 100644
index 0000000..c66b930
--- /dev/null
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs
@@ -0,0 +1,14 @@
+using Modules.Auth.Shared.ActionsRequests;
+using OneOf;
+using OneOf.Types;
+
+namespace Client.UI.Data.Services;
+
+public sealed class ProfileService(TokenHttpClientService api)
+{
+ public async Task> ChangeEmail(ChangeEmailRequest request)
+ => await api.PostAsync("/api/auth/ChangeEmail", request);
+
+ public async Task>? ChangePassword(ChangePasswordRequest request)
+ => await api.PostAsync("/api/auth/ChangePassword", request);
+}
\ No newline at end of file
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor
index 47cac85..e36788a 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor
@@ -5,55 +5,49 @@
Administration Dashboard
-
+
Panel Administracyjny
-
+
Użytkownicy
124
-
-
- Grupy uprawnień
- 5
-
-
-
+
Serwery
18
-
+
Tunele
7
-
+
- Backupy
+ Wykonane Backupy
2 354
-
+
Średnio backupów w miesiącu
80
-
+
Ilość zrobionych testów
1743
-
+
Testy udane
96%
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor
new file mode 100644
index 0000000..370b673
--- /dev/null
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor
@@ -0,0 +1,113 @@
+@page "/account/profile"
+
+@using Client.UI.Data.Services
+@using Modules.Auth.Shared.ActionsRequests
+
+@inject AuthStateProvider Auth
+@inject ISnackbar SnackBar
+@inject ProfileService Profile
+@inject NavigationManager NavigationManager
+
+
+
+ Your Profile
+ Welcome back, @_userEmail!
+
+
+
+
+
+
+
+
+
+ Change Email
+
+
+
+
+
+
+ Update
+
+
+
+
+
+
+
+
+
+
+
+
+ Change Password
+
+
+
+
+
+
+
+ Update
+
+
+
+
+
+
+
+
+@code {
+ private string _userEmail = "Loading...";
+
+ private ChangeEmailRequest _changeEmailRequest = new();
+ private ChangePasswordRequest _changePasswordRequest = new();
+
+ private bool _isChanging;
+
+ protected override async Task OnInitializedAsync()
+ {
+ await Auth.AuthorizeUser(returnPageAfterValidPasswordAuthorization: "account-profile");
+
+ var authState = await Auth.GetAuthenticationStateAsync();
+ _userEmail = authState.User.Identity?.Name ?? "Unknown user";
+ }
+
+ private async Task ChangeEmail()
+ {
+ _isChanging = true;
+
+ var result = await Profile.ChangeEmail(_changeEmailRequest);
+
+ result.Switch(
+ _ =>
+ {
+ SnackBar.Add("Email updated successfully. Login again to confirm new email changes.", Severity.Success);
+ NavigationManager.NavigateTo("/", true);
+ },
+ error => SnackBar.Add(error, Severity.Error)
+ );
+
+ _isChanging = false;
+ }
+
+ private async Task ChangePassword()
+ {
+ _isChanging = true;
+
+ var result = await Profile.ChangePassword(_changePasswordRequest)!;
+
+ result.Switch(
+ _ => SnackBar.Add("Password updated successfully.", Severity.Success),
+ error => SnackBar.Add(error, Severity.Error)
+ );
+
+ _isChanging = false;
+ }
+}
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/AuthorizeUser.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/AuthorizeUser.razor
similarity index 99%
rename from DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/AuthorizeUser.razor
rename to DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/AuthorizeUser.razor
index e5354e3..0b68a88 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/AuthorizeUser.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/AuthorizeUser.razor
@@ -1,4 +1,5 @@
@page "/authorizeuser"
+
@using Blazored.LocalStorage
@using Client.UI.Data.Interfaces
@using Client.UI.Data.Services
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ConfirmPassword.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/ConfirmPassword.razor
similarity index 100%
rename from DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ConfirmPassword.razor
rename to DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/ConfirmPassword.razor
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/Login.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Login.razor
similarity index 100%
rename from DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/Login.razor
rename to DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Login.razor
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/Register.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Register.razor
similarity index 100%
rename from DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/Register.razor
rename to DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Register.razor
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor
index 9e3f253..7555e0c 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor
@@ -5,54 +5,41 @@
Dashboard
-
+
My Dashboard
-
- Moje Role
- Admin, User
-
-
-
-
- Moje Grupy
- Localhost, Domain, Test
-
-
-
-
Obsługiwane Serwery
4
-
+
Moje Tunele
2
-
+
- Backupy
+ Wykonane Backupy
245
-
+
Średnio backupów w miesiącu
20
-
+
Ilość zrobionych testów
180
-
+
Testy udane
94%
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs b/DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs
index 47ea4d8..cb12d4a 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs
@@ -31,6 +31,7 @@
builder.Services.AddScoped();
builder.Services.AddScoped();
builder.Services.AddScoped();
+builder.Services.AddScoped();
builder.Logging.AddFilter((category, level)
=> level >= LogLevel.Warning ||
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs
index cac678d..e33b82a 100644
--- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs
@@ -41,6 +41,10 @@ private static void MapAuthPosts(this RouteGroupBuilder api)
api.MapPost("ChangePassword", AuthOperations.ChangePassword)
.WithSummary("Change user's password")
.AddEndpointFilter();
+
+ api.MapPost("ChangeEmail", AuthOperations.ChangeEmail)
+ .WithSummary("Change user's email address")
+ .AddEndpointFilter();
api.MapPost("CanLogIn", AuthOperations.CanLogIn)
.WithSummary("Check if user can be logged in");
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs
index 16bb4c9..07e9b7c 100644
--- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs
@@ -30,6 +30,14 @@ public static Task ChangePassword(
{
return authService.ChangePassword(context, request);
}
+
+ public static Task ChangeEmail(
+ HttpContext context,
+ [FromBody] ChangeEmailRequest request,
+ [FromServices] IAuthService authService)
+ {
+ return authService.ChangeEmail(context, request);
+ }
public static Task CanLogIn(
HttpContext context,
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs
index c3655b9..6c93cd4 100644
--- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs
@@ -8,6 +8,7 @@ public interface IAuthService
{
Task Login(HttpContext context, LoginRequest? request);
Task ChangePassword(HttpContext context, ChangePasswordRequest request);
+ Task ChangeEmail(HttpContext context, ChangeEmailRequest request);
Task CanLogIn(HttpContext context, LoginRequest? request);
Task Register(HttpContext context, RegisterRequest request);
Task Logout(HttpContext context);
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs
index ad30811..1493a6f 100644
--- a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs
@@ -35,7 +35,7 @@ public async Task Login(HttpContext context, LoginRequest? request)
var user = await userManager.FindByEmailAsync(request!.Email);
if (user is null)
- return Results.NotFound("Taki użytkownik nie istnieje.");
+ return Results.NotFound("This user does not exist.");
await signInManager.SignInAsync(user, request.RememberMe);
@@ -54,14 +54,42 @@ public async Task ChangePassword(HttpContext context, ChangePasswordReq
if (!IsValidChangePasswordRequest(request, out var error))
return Results.BadRequest(error);
- var user = await userManager.FindByEmailAsync(context.User.Identity?.Name!);
+ var user = await userManager.FindByNameAsync(context.User.Identity?.Name!);
if (user is null)
- return Results.BadRequest("Nie można znaleźć użytkownika");
+ return Results.BadRequest("Can't find user.");
var result = await userManager.ChangePasswordAsync(user, request.CurrentPassword, request.NewPassword);
return result.Succeeded
? Results.Ok()
- : Results.BadRequest("Błąd przy zmianie hasła, sprawdź dane i wymagania.");
+ : Results.BadRequest("Error while changing password. Check your password and try again.");
+ }
+
+ public async Task ChangeEmail(HttpContext context, ChangeEmailRequest request)
+ {
+ logger.LogInformation("Changing email address for {UserName} to new one: [{NewEmail}]...", context.User.Identity?.Name, request.NewEmail);
+
+ if (string.IsNullOrWhiteSpace(request.NewEmail) || string.IsNullOrWhiteSpace(request.ConfirmNewEmail))
+ return Results.BadRequest("Cant process empty email address.");
+
+ if (request.NewEmail != request.ConfirmNewEmail)
+ return Results.BadRequest("Emails do not match.");
+
+ var user = await userManager.FindByNameAsync(context.User.Identity?.Name!);
+ if (user is null)
+ return Results.BadRequest("Can't find user.");
+
+ var changeEmailToken = await userManager.GenerateChangeEmailTokenAsync(user, request.NewEmail);
+ var result = await userManager.ChangeEmailAsync(user, request.NewEmail, changeEmailToken);
+
+ if (result.Succeeded)
+ {
+ await userManager.SetUserNameAsync(user, request.NewEmail);
+ await Logout(context);
+ }
+
+ return result.Succeeded
+ ? Results.Ok()
+ : Results.BadRequest("Error while changing email address. Try again later.");
}
public async Task CanLogIn(HttpContext context, LoginRequest? request)
diff --git a/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs
new file mode 100644
index 0000000..ac5c07c
--- /dev/null
+++ b/DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs
@@ -0,0 +1,13 @@
+using System.ComponentModel.DataAnnotations;
+
+namespace Modules.Auth.Shared.ActionsRequests;
+
+public sealed class ChangeEmailRequest
+{
+ [Required] [MaxLength(60)] public string NewEmail { get; set; } = null!;
+
+ [Required]
+ [MaxLength(60)]
+ [Compare(nameof(NewEmail))]
+ public string ConfirmNewEmail { get; set; } = null!;
+}
\ No newline at end of file
From f30f5816630f0c695e6cafc1ced222a411574da2 Mon Sep 17 00:00:00 2001
From: Artur Lewandowski
Date: Sun, 26 Oct 2025 12:35:40 +0100
Subject: [PATCH 12/19] Implement statistics for user and admin dashboards
---
.../Data/Services/BackupsHttpClientService.cs | 9 ++
.../AdministrationDashboard.razor | 27 ++--
.../Client/Client.UI/Pages/Dashboard.razor | 25 +++-
.../Modules.Backup.Api/Extensions.cs | 2 +
.../Modules.Backup.Api/Statistics/StatsEO.cs | 53 ++++++++
.../Modules.Backup.Application/Extensions.cs | 4 +-
.../Services/StatisticsService.cs | 122 ++++++++++++++++++
.../Dtos/AdminDashboardDto.cs | 12 ++
.../Dtos/UserDashboardDto.cs | 11 ++
9 files changed, 248 insertions(+), 17 deletions(-)
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs b/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs
index e093dfc..a7568bb 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs
@@ -80,4 +80,13 @@ public async Task> EditAutoTestBackupConfig(AutoTestBacku
{
return await api.PostAsync("/api/servers/EditAutoTestConfig", config);
}
+
+ public async Task> GetMyDashboardAsync()
+ {
+ return await api.GetAsync("/api/statistics/MyDashboard");
+ }
+ public async Task> GetAdminDashboardAsync()
+ {
+ return await api.GetAsync("/api/statistics/AdminDashboard");
+ }
}
\ No newline at end of file
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor
index e36788a..6315e52 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor
@@ -1,7 +1,11 @@
@page "/administration/dashboard"
+
@using Client.UI.Data.Services
+@using Modules.Backup.Shared.Dtos
@inject AuthStateProvider Auth
+@inject BackupsHttpClientService BackupService
+@inject ISnackbar Snackbar
Administration Dashboard
@@ -13,54 +17,61 @@
Użytkownicy
- 124
+ @_dashboard.UsersCount
Serwery
- 18
+ @_dashboard.ServersCount
Tunele
- 7
+ @_dashboard.TunnelsCount
Wykonane Backupy
- 2 354
+ @_dashboard.AllBackups
Średnio backupów w miesiącu
- 80
+ @_dashboard.AvgBackupsPerMonth
Ilość zrobionych testów
- 1743
+ @_dashboard.AllTests
Testy udane
- 96%
+ @_dashboard.TestsSuccessRate%
@code{
-
+ private AdminDashboardDto _dashboard = new();
+
protected override async Task OnInitializedAsync()
{
await Auth.AuthorizeUser(returnPageAfterValidPasswordAuthorization: "administration-dashboard");
+
+ var result = await BackupService.GetAdminDashboardAsync();
+ result.Switch(
+ dashboard => _dashboard = dashboard,
+ error => Snackbar.Add(error, Severity.Error)
+ );
}
}
\ No newline at end of file
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor
index 7555e0c..bd9c81e 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor
@@ -1,7 +1,11 @@
@page "/dashboard"
+
@using Client.UI.Data.Services
+@using Modules.Backup.Shared.Dtos
@inject AuthStateProvider Auth
+@inject BackupsHttpClientService BackupService
+@inject ISnackbar Snackbar
Dashboard
@@ -12,47 +16,54 @@
Obsługiwane Serwery
- 4
+ @_dashboard.ServersCount
Moje Tunele
- 2
+ @_dashboard.TunnelsCount
Wykonane Backupy
- 245
+ @_dashboard.PerformedBackups
Średnio backupów w miesiącu
- 20
+ @_dashboard.AvgBackupsPerMonth
Ilość zrobionych testów
- 180
+ @_dashboard.PerformedTests
Testy udane
- 94%
+ @_dashboard.TestsSuccessRate%
@code{
-
+ private UserDashboardDto _dashboard = new();
+
protected override async Task OnInitializedAsync()
{
await Auth.AuthorizeUser(returnPageAfterValidPasswordAuthorization: "dashboard");
+
+ var result = await BackupService.GetMyDashboardAsync();
+ result.Switch(
+ dashboard => _dashboard = dashboard,
+ error => Snackbar.Add(error, Severity.Error)
+ );
}
}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Extensions.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Extensions.cs
index a20cd5f..8bebcf5 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Extensions.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Extensions.cs
@@ -3,6 +3,7 @@
using Modules.Backup.Api.Backups;
using Modules.Backup.Api.Schedules;
using Modules.Backup.Api.Servers;
+using Modules.Backup.Api.Statistics;
using Modules.Backup.Application;
using Modules.Backup.Infrastructure;
@@ -23,6 +24,7 @@ public static WebApplication MapBackupModuleEndpoints(this WebApplication app)
app.MapBackupEndpoints();
app.MapServersEndpoints();
app.MapSchedulesEndpoints();
+ app.MapStatsEndpoints();
return app;
}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs
new file mode 100644
index 0000000..8740abc
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs
@@ -0,0 +1,53 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
+using Microsoft.AspNetCore.Mvc;
+using Modules.Backup.Application.Services;
+using Modules.Shared.Attributes;
+
+namespace Modules.Backup.Api.Statistics;
+
+internal static class StatisticsEndpoints
+{
+ public static WebApplication MapStatsEndpoints(this WebApplication app)
+ {
+ var api = app.MapGroup("/api/statistics")
+ .RequireAuthorization()
+ .AddEndpointFilter();
+
+ api.MapGet("MyDashboard", StatisticsOperations.GetMyDashboard)
+ .WithSummary("Get user statistics for Dashboard");
+
+ api.MapGet("AdminDashboard", StatisticsOperations.GetAdminDashboard)
+ .WithSummary("Get Admin statistics for Dashboard")
+ .AddEndpointFilter();
+
+ return app;
+ }
+}
+
+internal abstract record StatisticsOperations
+{
+ public static async Task GetMyDashboard(
+ HttpContext context,
+ [FromServices] StatisticsService service)
+ {
+ var result = await service.GetMyDashboard(context.User.Identity?.Name);
+
+ return result.Match(
+ TypedResults.Ok,
+ TypedResults.BadRequest
+ );
+ }
+
+ public static async Task GetAdminDashboard(
+ HttpContext context,
+ [FromServices] StatisticsService service)
+ {
+ var result = await service.GetAdminDashboard();
+
+ return result.Match(
+ TypedResults.Ok,
+ TypedResults.BadRequest
+ );
+ }
+}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Extensions.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Extensions.cs
index bfef5d5..fbdd7e8 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Extensions.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Extensions.cs
@@ -10,9 +10,9 @@ public static IServiceCollection AddApplicationLayer(this IServiceCollection ser
{
services.AddScoped();
services.AddScoped();
-
services.AddScoped();
-
+ services.AddScoped();
+
services.AddTransient();
return services;
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs
new file mode 100644
index 0000000..f3cfbae
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs
@@ -0,0 +1,122 @@
+using Microsoft.AspNetCore.Identity;
+using Microsoft.EntityFrameworkCore;
+using Modules.Auth.Core.Entities;
+using Modules.Auth.Infrastructure.DbContexts;
+using Modules.Backup.Core.Entities.DbContext;
+using Modules.Backup.Infrastructure.DbContexts;
+using Modules.Backup.Shared.Dtos;
+using OneOf;
+
+namespace Modules.Backup.Application.Services;
+
+public sealed class StatisticsService(BackupsDbContext appDb,
+ AppIdentityDbContext identityDb,
+ UserManager userManager,
+ ServersService serversService)
+{
+ public async Task> GetMyDashboard(string? identityName)
+ {
+ if (string.IsNullOrEmpty(identityName))
+ return "Can't access identity name";
+
+ var user = await userManager.FindByNameAsync(identityName);
+ if (user is null)
+ return "Can't find user";
+
+ var myServersListResult = await serversService.GetAvailableServersBasic(identityName);
+ var serversList = myServersListResult.IsT0 ? myServersListResult.AsT0 : new();
+
+ var tunnelsCount = 0;
+ var backupsCount = 0;
+
+ var now = DateTime.UtcNow;
+ var sixMonthsAgo = now.AddMonths(-6);
+ List backupsLast6Months = new();
+
+ var totalTests = 0;
+ var successTests = 0;
+
+ foreach (var server in serversList)
+ {
+ var dbServer = appDb.DbConnections.First(x => x.Id == server.Id);
+
+ var tunnelId = dbServer?.TunnelId;
+ var doesTunnelExist = appDb.DbServerTunnels.FirstOrDefault(x => x.Id == tunnelId);
+
+ if (doesTunnelExist is not null)
+ tunnelsCount++;
+
+ var backups = appDb.Backups
+ .AsNoTracking()
+ .Where(x => x.ServerConnectionId == dbServer!.Id);
+
+ backupsCount += backups.Count();
+ backupsLast6Months.AddRange(backups
+ .Where(b => b.CreatedOn >= sixMonthsAgo && b.ServerConnectionId == dbServer!.Id));
+
+ foreach (var backup in backups)
+ {
+ if (backup.TestId is null)
+ continue;
+
+ totalTests++;
+
+ if (appDb.BackupsTests.First(x => x.Id == backup.TestId).IsSuccess)
+ successTests++;
+ }
+ }
+
+ var avgBackupsPerMonth = backupsLast6Months
+ .GroupBy(b => new { b.CreatedOn.Year, b.CreatedOn.Month })
+ .Select(g => g.Count())
+ .DefaultIfEmpty(0)
+ .Average();
+
+ var testsSuccessRate = totalTests == 0 ? 0 : (100 * successTests / totalTests);
+
+ var dashboard = new UserDashboardDto
+ {
+ ServersCount = serversList.Count,
+ TunnelsCount = tunnelsCount,
+ PerformedBackups = backupsCount,
+ AvgBackupsPerMonth = (int)avgBackupsPerMonth,
+ PerformedTests = totalTests,
+ TestsSuccessRate = testsSuccessRate
+ };
+
+ return dashboard;
+ }
+
+ public async Task> GetAdminDashboard()
+ {
+ var now = DateTime.UtcNow;
+ var sixMonthsAgo = now.AddMonths(-6);
+
+ var backupsLast6Months = await appDb.Backups
+ .Where(b => b.CreatedOn >= sixMonthsAgo)
+ .ToListAsync();
+
+ var avgBackupsPerMonth = backupsLast6Months
+ .GroupBy(b => new { b.CreatedOn.Year, b.CreatedOn.Month })
+ .Select(g => g.Count())
+ .DefaultIfEmpty(0)
+ .Average();
+
+ var totalTests = await appDb.BackupsTests.CountAsync();
+ var successTests = await appDb.BackupsTests.CountAsync(x => x.IsSuccess);
+ var testsSuccessRate = totalTests == 0 ? 0 : (100 * successTests / totalTests);
+
+ var dashboard = new AdminDashboardDto
+ {
+ UsersCount = await identityDb.Users.CountAsync(),
+ ServersCount = await appDb.DbConnections.CountAsync(),
+ TunnelsCount = await appDb.DbServerTunnels.CountAsync(),
+ AllBackups = await appDb.Backups.CountAsync(),
+ AvgBackupsPerMonth = (int)avgBackupsPerMonth,
+ AllTests = totalTests,
+ TestsSuccessRate = testsSuccessRate
+ };
+
+ return dashboard;
+ }
+}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs
new file mode 100644
index 0000000..233418e
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs
@@ -0,0 +1,12 @@
+namespace Modules.Backup.Shared.Dtos;
+
+public class AdminDashboardDto
+{
+ public int UsersCount { get; set; }
+ public int ServersCount { get; set; }
+ public int TunnelsCount { get; set; }
+ public int AllBackups { get; set; }
+ public int AvgBackupsPerMonth { get; set; }
+ public int AllTests { get; set; }
+ public int TestsSuccessRate { get; set; }
+}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs
new file mode 100644
index 0000000..90a0dc8
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs
@@ -0,0 +1,11 @@
+namespace Modules.Backup.Shared.Dtos;
+
+public class UserDashboardDto
+{
+ public int ServersCount { get; set; }
+ public int TunnelsCount { get; set; }
+ public int PerformedBackups { get; set; }
+ public int AvgBackupsPerMonth { get; set; }
+ public int PerformedTests { get; set; }
+ public int TestsSuccessRate { get; set; }
+}
\ No newline at end of file
From 9a85d613708211b90431a939841f7465b65098ea Mon Sep 17 00:00:00 2001
From: Artur Lewandowski
Date: Sun, 26 Oct 2025 13:03:18 +0100
Subject: [PATCH 13/19] Change deleting old backups entries to soft delete for
future statistics
---
.../Pages/BackupsModule/MyBackups.razor | 13 +-
.../Services/DbBackupService.cs | 10 +-
.../Entities/DbContext/PerformedBackup.cs | 1 +
...6120032_AddSoftDeleteToBackups.Designer.cs | 297 ++++++++++++++++++
.../20251026120032_AddSoftDeleteToBackups.cs | 29 ++
.../BackupsDbContextModelSnapshot.cs | 3 +
.../Dtos/PerformedBackupDto.cs | 1 +
7 files changed, 347 insertions(+), 7 deletions(-)
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor
index 81599a4..0477f98 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor
@@ -81,9 +81,18 @@
-
+
-
+ @if (context.IsDisabled)
+ {
+
+
+
+ }
+ else
+ {
+
+ }
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
index 631a27a..1ce2f96 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
@@ -146,6 +146,7 @@ public async Task, string>> GetAllBackups(string?
FilePath = x.FilePath,
Name = x.Name,
ServerConnectionId = x.ServerConnectionId,
+ IsDisabled = x.IsSoftDeleted,
Test = dbContext.BackupsTests.AsNoTracking().Where(y => y.BackupId == x.Id).Select(y =>
new BackupTestDto
{
@@ -159,7 +160,7 @@ public async Task, string>> GetAllBackups(string?
foreach (var server in dbServers)
backups.AddRange(dbContext.Backups
.AsNoTracking()
- .Where(x => x.ServerConnectionId == server.Id)
+ .Where(x => x.ServerConnectionId == server.Id && !x.IsSoftDeleted)
.Select(x => new PerformedBackupDto
{
Id = x.Id,
@@ -275,11 +276,10 @@ await DeleteOldBackup.Delete(backupPath.DirectoryPath, serverConfig.TimeInDaysTo
x.CreatedOn < cutoffDate);
if (serverActualBackups.Any())
{
- dbContext.Backups.RemoveRange(serverActualBackups);
+ foreach (var backup in serverActualBackups)
+ backup.IsSoftDeleted = true;
+
await dbContext.SaveChangesAsync();
-
- logger.LogInformation("Successfully cleaned [{DeletedCount}] old backups entries",
- serverActualBackups.Count());
}
var serverConn = db.GetServerConnection();
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs
index 022dd8f..e70dae4 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs
@@ -8,4 +8,5 @@ public sealed record PerformedBackup
public Guid? TestId { get; set; }
public Guid? ServerConnectionId { get; set; }
public required string FilePath { get; set; }
+ public bool IsSoftDeleted { get; set; } = false;
}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs
new file mode 100644
index 0000000..a4c62da
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs
@@ -0,0 +1,297 @@
+//
+using System;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
+using Modules.Backup.Infrastructure.DbContexts;
+
+#nullable disable
+
+namespace Modules.Backup.Infrastructure.DbContexts.Migrations
+{
+ [DbContext(typeof(BackupsDbContext))]
+ [Migration("20251026120032_AddSoftDeleteToBackups")]
+ partial class AddSoftDeleteToBackups
+ {
+ ///
+ protected override void BuildTargetModel(ModelBuilder modelBuilder)
+ {
+#pragma warning disable 612, 618
+ modelBuilder.HasAnnotation("ProductVersion", "9.0.9");
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("AutomaticBackupTestConfigs");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupSchedule", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ConfigurationJson")
+ .HasColumnType("TEXT");
+
+ b.Property("DbConnectionId")
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("Name")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("NextBackupDate")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("Schedules");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupTest", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("BackupId")
+ .HasColumnType("TEXT");
+
+ b.Property("ErrorMessage")
+ .HasColumnType("TEXT");
+
+ b.Property("IsSuccess")
+ .HasColumnType("INTEGER");
+
+ b.Property("TestedOn")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("BackupsTests");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerConnection", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("AutoTestBackupsConfigId")
+ .HasColumnType("TEXT");
+
+ b.Property("BackupEncryptionKeyHas")
+ .HasColumnType("TEXT");
+
+ b.Property("ConnectionName")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbName")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbPasswd")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbType")
+ .HasColumnType("INTEGER");
+
+ b.Property("DbUser")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("IsDisabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("IsTunnelRequired")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("SsL")
+ .HasColumnType("INTEGER");
+
+ b.Property("TunnelId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("DbConnections");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerTunnel", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("Description")
+ .HasColumnType("TEXT");
+
+ b.Property("IsActive")
+ .HasColumnType("INTEGER");
+
+ b.Property("LocalPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("Password")
+ .HasColumnType("TEXT");
+
+ b.Property("PrivateKeyContent")
+ .HasColumnType("TEXT");
+
+ b.Property("PrivateKeyPassphrase")
+ .HasColumnType("TEXT");
+
+ b.Property("RemoteHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("RemotePort")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("SshPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("UsePasswordAuth")
+ .HasColumnType("INTEGER");
+
+ b.Property("Username")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("DbServerTunnels");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.PerformedBackup", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("CreatedOn")
+ .HasColumnType("TEXT");
+
+ b.Property("FilePath")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("IsSoftDeleted")
+ .HasColumnType("INTEGER");
+
+ b.Property("Name")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerConnectionId")
+ .HasColumnType("TEXT");
+
+ b.Property("TestId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("Backups");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServerBackupsConfiguration", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.Property("TimeInDaysToHoldBackups")
+ .HasColumnType("INTEGER");
+
+ b.HasKey("Id");
+
+ b.ToTable("Configurations");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServersUsers", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.Property("UserId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("UsersServers");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.UserNotificationsSettings", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnChanges")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnErrors")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnFailedBackups")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnFailedTests")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnSuccessfulBackup")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnUpdates")
+ .HasColumnType("INTEGER");
+
+ b.Property("UserId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("UsersNotificationsSettings");
+ });
+#pragma warning restore 612, 618
+ }
+ }
+}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs
new file mode 100644
index 0000000..1b42efe
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs
@@ -0,0 +1,29 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Modules.Backup.Infrastructure.DbContexts.Migrations
+{
+ ///
+ public partial class AddSoftDeleteToBackups : Migration
+ {
+ ///
+ protected override void Up(MigrationBuilder migrationBuilder)
+ {
+ migrationBuilder.AddColumn(
+ name: "IsSoftDeleted",
+ table: "Backups",
+ type: "INTEGER",
+ nullable: false,
+ defaultValue: false);
+ }
+
+ ///
+ protected override void Down(MigrationBuilder migrationBuilder)
+ {
+ migrationBuilder.DropColumn(
+ name: "IsSoftDeleted",
+ table: "Backups");
+ }
+ }
+}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
index 9ccb2e7..702584d 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
@@ -202,6 +202,9 @@ protected override void BuildModel(ModelBuilder modelBuilder)
.IsRequired()
.HasColumnType("TEXT");
+ b.Property("IsSoftDeleted")
+ .HasColumnType("INTEGER");
+
b.Property("Name")
.IsRequired()
.HasColumnType("TEXT");
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs
index d891a55..6192f35 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs
@@ -8,4 +8,5 @@ public class PerformedBackupDto
public BackupTestDto? Test { get; set; }
public Guid? ServerConnectionId { get; set; }
public string? FilePath { get; set; }
+ public bool IsDisabled { get; set; } = false;
}
\ No newline at end of file
From d7e6dc50044c75808461113e50ae4d53281fdd93 Mon Sep 17 00:00:00 2001
From: artur
Date: Thu, 30 Oct 2025 10:29:30 +0100
Subject: [PATCH 14/19] Fix error with depreceated mysqldump Implement
mariadb-dump if mysqldump does not work Add ssl to dump
---
.../Entities/Databases/MySqlDatabase.cs | 27 ++++++++++++++++---
1 file changed, 23 insertions(+), 4 deletions(-)
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs
index 7eee151..29c6f89 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs
@@ -30,22 +30,23 @@ private async Task PerformBackupWithDump(string fullFilePath)
var hostPort = GetHostAndPort();
var decryptedDbPassword = _cryptoService.Decrypt(_serverConnection.DbPasswd);
- var args =
+ var baseArgs =
$"-h {hostPort.Host} -P {hostPort.Port} -u {_serverConnection.DbUser} -p{decryptedDbPassword} {_serverConnection.DbName}";
+ var mySqlSsl = GetServerConnection().SsL ? "--ssl-mode=PREFERRED" : "--ssl-mode=DISABLED";
var process = new Process
{
StartInfo = new ProcessStartInfo
{
FileName = "mysqldump",
- Arguments = args,
+ Arguments = $"{mySqlSsl} {baseArgs}",
RedirectStandardOutput = true,
RedirectStandardError = true,
UseShellExecute = false,
CreateNoWindow = true
}
};
-
+
await using var fs = new FileStream(fullFilePath, FileMode.Create, FileAccess.Write);
process.Start();
await process.StandardOutput.BaseStream.CopyToAsync(fs);
@@ -53,7 +54,25 @@ private async Task PerformBackupWithDump(string fullFilePath)
await process.WaitForExitAsync();
if (process.ExitCode != 0)
- throw new Exception($"mysqldump failed: {error}");
+ {
+ if (error.Contains("mariadb-dump", StringComparison.OrdinalIgnoreCase))
+ {
+ process.Kill();
+ var mariaSqlSsl = GetServerConnection().SsL ? "--ssl-verify-server-cert" : "--ssl=0";
+ process.StartInfo.FileName = "mariadb-dump";
+ process.StartInfo.Arguments = $"{mariaSqlSsl} {baseArgs}";
+
+ process.Start();
+ await process.StandardOutput.BaseStream.CopyToAsync(fs);
+ error = await process.StandardError.ReadToEndAsync();
+ await process.WaitForExitAsync();
+
+ if (process.ExitCode != 0)
+ throw new Exception($"mariadb-dump failed: {error}");
+ }
+ else
+ throw new Exception($"mysqldump failed: {error}");
+ }
}
private async Task PerformBackupWithLibrary(string fullFilePath)
From a226a2fa602c54710efe6ca5fdfdbced540d4575 Mon Sep 17 00:00:00 2001
From: artur
Date: Tue, 4 Nov 2025 10:41:32 +0100
Subject: [PATCH 15/19] Add msgboxes confirmations to delete buttons. Translate
index page
---
.../AdministrationUsersManagement.razor | 30 ++++--
.../Pages/BackupsModule/MySchedules.razor | 34 ++++---
.../Pages/BackupsModule/MyServers.razor | 52 ++++++----
.../Client/Client.UI/Pages/Index.razor | 97 +++++++++++--------
4 files changed, 130 insertions(+), 83 deletions(-)
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor
index 380c6e5..cfcd959 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor
@@ -39,7 +39,7 @@
{
+ OnClick="@(() => ToggleBlock(context))" Disabled="@_isProcessing">
Block
}
@@ -47,7 +47,7 @@
{
+ OnClick="@(() => ToggleBlock(context))" Disabled="@_isProcessing">
Unblock
}
@@ -104,18 +104,28 @@
StateHasChanged();
}
- private async Task ToggleBlock(string userId)
+ private async Task ToggleBlock(UserDto user)
{
- _isProcessing = true;
+ var blockadeString = user.IsBlocked ? "unblock" : "block";
+ bool? msgBoxResult = await DialogService.ShowMessageBox(
+ "Warning",
+ $"Are you sure that you want to {blockadeString} this user?",
+ yesText:"Yes!", cancelText:"Cancel");
+
+ if (msgBoxResult is not null)
+ {
+ _isProcessing = true;
- var result = await Service.ToggleUserBlockade(userId);
+ var result = await Service.ToggleUserBlockade(user.Id.ToString());
- result.Switch(
- async void (_) => await FetchUsers(),
- error => Snackbar.Add(error, Severity.Error)
- );
+ result.Switch(
+ async void (_) => await FetchUsers(),
+ error => Snackbar.Add(error, Severity.Error)
+ );
+
+ _isProcessing = false;
+ }
- _isProcessing = false;
}
private async Task OpenEditUserDialog(UserDto user)
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor
index a96751d..eba0591 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor
@@ -123,20 +123,28 @@
private async Task DeleteSchedule(Guid id)
{
- _isProcessing = true;
-
- var result = await Service.DeleteScheduleAsync(id);
-
- result.Switch(
- async void (_) =>
- {
- Snackbar.Add("Successfully removed schedule.", Severity.Success);
- await FetchSchedules();
- },
- error => Snackbar.Add(error, Severity.Error)
- );
+ bool? msgBoxResult = await DialogService.ShowMessageBox(
+ "Warning",
+ (MarkupString) "Are you sure that you want to permanently delete this schedule? This can not be undone!",
+ yesText:"Permanently delete", cancelText:"Cancel");
+
+ if (msgBoxResult is not null)
+ {
+ _isProcessing = true;
+
+ var result = await Service.DeleteScheduleAsync(id);
- _isProcessing = false;
+ result.Switch(
+ async void (_) =>
+ {
+ Snackbar.Add("Successfully removed schedule.", Severity.Success);
+ await FetchSchedules();
+ },
+ error => Snackbar.Add(error, Severity.Error)
+ );
+
+ _isProcessing = false;
+ }
}
private async Task OpenNewScheduleDialog()
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor
index 993c69a..280950e 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor
@@ -159,16 +159,24 @@
private async Task DisableServer(Guid id)
{
- _isProcessing = true;
-
- var result = await Service.ToggleServerDisabledStatus(id);
-
- result.Switch(
- success => _ = FetchServers(),
- error => Snackbar.Add(error, Severity.Error)
- );
-
- _isProcessing = false;
+ bool? msgBoxResult = await DialogService.ShowMessageBox(
+ "Warning",
+ (MarkupString) "Are you sure that you want to disable this server? This can be undone after contacting to Administrator.",
+ yesText:"Disable", cancelText:"Cancel");
+
+ if(msgBoxResult is not null)
+ {
+ _isProcessing = true;
+
+ var result = await Service.ToggleServerDisabledStatus(id);
+
+ result.Switch(
+ success => _ = FetchServers(),
+ error => Snackbar.Add(error, Severity.Error)
+ );
+
+ _isProcessing = false;
+ }
}
private async Task OpenEditServerDialog(ServerConnectionDto server)
@@ -213,16 +221,24 @@
private async Task DeleteServer(Guid serverId)
{
- _isProcessing = true;
-
- var result = await Service.CascadeDeleteServer(serverId);
+ bool? msgBoxResult = await DialogService.ShowMessageBox(
+ "Warning",
+ (MarkupString) "Are you sure that you want to delete this server? This can not be undone!",
+ yesText:"Delete Permanently!", cancelText:"Cancel");
+
+ if (msgBoxResult is not null)
+ {
+ _isProcessing = true;
+
+ var result = await Service.CascadeDeleteServer(serverId);
- result.Switch(
- success => _ = FetchServers(),
- error => Snackbar.Add(error, Severity.Error)
- );
+ result.Switch(
+ success => _ = FetchServers(),
+ error => Snackbar.Add(error, Severity.Error)
+ );
- _isProcessing = false;
+ _isProcessing = false;
+ }
}
private async Task PerformServerBackup(Guid serverId)
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor
index 73019e8..580a0e6 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor
@@ -6,31 +6,25 @@
- Witaj w OctoBackup
+ Welcome in OctoBackup
- Tutaj znajdziesz najnowsze informacje, aktualizacje i linki do dokumentacji systemu.
+ Here you will find the latest information, updates, and links to system documentation.
- Dołącz do nas i korzystaj z możliwości
- systemu!
-
+ Join us and enjoy the benefits of the system!
- Nie masz jeszcze konta? Dołącz do
- nas!
-
-
- Stwórz nowe konto i ciesz się możliwościa korzystania z OctoBackup!
-
+ Don't have an account yet? Join us now!
+ Create a new account and enjoy using OctoBackup!
- Zarejestruj się
+ Sign up
@@ -39,15 +33,12 @@
- Posiadasz już konto w systemie?
-
-
- Zaloguj się do swojego konta w OctoBackup!
-
+ Do you already have an account in the system?
+ Log in to your OctoBackup account!
- Zaloguj się
+ Log in
@@ -57,17 +48,17 @@
- Nowości
+ What's New
- Dodano obsługę wielu baz danych w jednym backupie.
+ An example of a new feature that improves system usability
2025-08-25
- Usprawniono autoryzację użytkowników i system powiadomień.
+ Another example of a new feature enabling advanced backup scheduling
2025-08-20
@@ -76,38 +67,60 @@
- Dokumentacja i zasoby
+ Documentation and resources
-
-
-
- API Documentation
-
- Pełna dokumentacja API do integracji z systemem OctoBackup.
-
-
-
-
- Otwórz dokumentację
-
-
-
-
+ @if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Production")
+ {
+
+
+
+ Documentation
+
+ Complete documentation for the OctoBackup system.
+
+
+
+
+ Open documentation
+
+
+
+
+ }
+ else
+ {
+
+
+
+ Documentation
+
+ API documentation for the OctoBackup system.
+
+
+
+
+ Open API documentation
+
+
+
+
+ }
- Wiki / Instrukcje
+ Wiki / Instructions
- Szybki dostęp do poradników i instrukcji użytkowania.
+ Quick access to guides and user manuals.
-
- Otwórz Wiki
+ Open Wiki
From 9ff30decee0b9d39a43748731ca19cdd4b782aeb Mon Sep 17 00:00:00 2001
From: artur
Date: Tue, 4 Nov 2025 11:31:40 +0100
Subject: [PATCH 16/19] Add BackupsTests Module with test api and example
method to api. Implement creating test container and retrieving its guid.
---
DbBackupService/OctoBackup.sln | 10 ++++
.../Bootstraper/Server/Server.Api/Program.cs | 3 ++
.../Server/Server.Api/Server.Api.csproj | 1 +
.../BackupsTestsEO.cs | 54 +++++++++++++++++++
.../Modules.BackupsTests.Api/Extensions.cs | 19 +++++++
.../Modules.BackupsTests.Api.csproj | 20 +++++++
6 files changed, 107 insertions(+)
create mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs
create mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs
create mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj
diff --git a/DbBackupService/OctoBackup.sln b/DbBackupService/OctoBackup.sln
index a96186c..34d4313 100644
--- a/DbBackupService/OctoBackup.sln
+++ b/DbBackupService/OctoBackup.sln
@@ -64,6 +64,10 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Modules.Crypto.Shared", "Sr
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Modules.Crypto.Api", "Src\Modules\CryptoModule\Modules.Crypto.Api\Modules.Crypto.Api.csproj", "{81471CFC-061C-48E4-ACCA-FBE583DCAC01}"
EndProject
+Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "BackupsTests", "BackupsTests", "{7141A8CE-79EE-4C76-8AA6-E5D074650290}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Modules.BackupsTests.Api", "Src\Modules\BackupsTests\Modules.BackupsTests.Api\Modules.BackupsTests.Api.csproj", "{1DE044F9-AEBE-4384-8766-7B60BD829C01}"
+EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
@@ -146,6 +150,10 @@ Global
{81471CFC-061C-48E4-ACCA-FBE583DCAC01}.Debug|Any CPU.Build.0 = Debug|Any CPU
{81471CFC-061C-48E4-ACCA-FBE583DCAC01}.Release|Any CPU.ActiveCfg = Release|Any CPU
{81471CFC-061C-48E4-ACCA-FBE583DCAC01}.Release|Any CPU.Build.0 = Release|Any CPU
+ {1DE044F9-AEBE-4384-8766-7B60BD829C01}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+ {1DE044F9-AEBE-4384-8766-7B60BD829C01}.Debug|Any CPU.Build.0 = Debug|Any CPU
+ {1DE044F9-AEBE-4384-8766-7B60BD829C01}.Release|Any CPU.ActiveCfg = Release|Any CPU
+ {1DE044F9-AEBE-4384-8766-7B60BD829C01}.Release|Any CPU.Build.0 = Release|Any CPU
EndGlobalSection
GlobalSection(SolutionProperties) = preSolution
HideSolutionNode = FALSE
@@ -178,6 +186,8 @@ Global
{32E6D088-AFE2-42A8-BE7F-7FC5348E356D} = {7EFE67DE-F557-4212-BF9E-57F7F1DAECA7}
{8F76EA6E-8657-4581-9666-F484BE627D45} = {7EFE67DE-F557-4212-BF9E-57F7F1DAECA7}
{81471CFC-061C-48E4-ACCA-FBE583DCAC01} = {7EFE67DE-F557-4212-BF9E-57F7F1DAECA7}
+ {7141A8CE-79EE-4C76-8AA6-E5D074650290} = {00FABD4C-5920-4940-A122-342F45F5B31A}
+ {1DE044F9-AEBE-4384-8766-7B60BD829C01} = {7141A8CE-79EE-4C76-8AA6-E5D074650290}
EndGlobalSection
GlobalSection(ExtensibilityGlobals) = postSolution
SolutionGuid = {05F3A4BF-6277-46FD-9537-F78E8FABE0DA}
diff --git a/DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs b/DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs
index 4b6cbf9..c599572 100644
--- a/DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs
+++ b/DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs
@@ -12,6 +12,7 @@
using Modules.Backup.Application.Workers;
using Modules.Backup.Infrastructure.DbContexts;
using Modules.Backup.Shared.Hubs;
+using Modules.BackupsTests.Api;
using Modules.Crypto.Api;
using Modules.Shared.Common;
using OpenTelemetry.Exporter;
@@ -41,6 +42,7 @@
builder.Services.AddOpenApi();
builder.Services.AddBackupModule();
+builder.Services.AddBackupsTestsModule();
builder.Services.AddLogging(logging =>
{
@@ -181,6 +183,7 @@
app.UseRouting();
app.MapBackupModuleEndpoints();
+app.MapBackupsTestsModuleEndpoints();
app.MapAuthModuleEndpoints();
app.MapAdministrationModuleEndpoints();
diff --git a/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj b/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj
index d717a60..d60cc8f 100644
--- a/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj
+++ b/DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj
@@ -27,6 +27,7 @@
+
diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs
new file mode 100644
index 0000000..9e8fcea
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs
@@ -0,0 +1,54 @@
+using System.Diagnostics;
+using DotNet.Testcontainers.Builders;
+using Microsoft.AspNetCore.Builder;
+using Microsoft.AspNetCore.Http;
+using Microsoft.Extensions.Logging;
+using Modules.Shared.Attributes;
+
+namespace Modules.BackupsTests.Api;
+
+internal static class BackupsTestsEndpoints
+{
+ public static WebApplication MapBackupsTestsEndpoints(this WebApplication app)
+ {
+ var api = app.MapGroup("/api/BackupsTests");
+ // .RequireAuthorization()
+ // .AddEndpointFilter();
+
+ api.MapGet("RunTest", BackupsTestsOperations.RunTest)
+ .WithSummary("Run test dev container");
+
+ return app;
+ }
+}
+
+internal abstract record BackupsTestsOperations
+{
+ public static async Task RunTest(
+ HttpContext context,
+ ILogger logger)
+ {
+ var container = new ContainerBuilder()
+ .WithImage("testcontainers/helloworld:1.3.0")
+ .WithPortBinding(8080, true)
+ // Wait until the HTTP endpoint of the container is available.
+ .WithWaitStrategy(Wait.ForUnixContainer().UntilHttpRequestIsSucceeded(r => r.ForPort(8080)))
+ .Build();
+
+ await container.StartAsync()
+ .ConfigureAwait(false);
+
+ using var httpClient = new HttpClient();
+
+ // Construct the request URI by specifying the scheme, hostname, assigned random host port, and the endpoint "uuid".
+ var requestUri = new UriBuilder(Uri.UriSchemeHttp, container.Hostname, container.GetMappedPublicPort(8080), "uuid").Uri;
+
+ // Send an HTTP GET request to the specified URI and retrieve the response as a string.
+ var guid = await httpClient.GetStringAsync(requestUri).ConfigureAwait(false);
+
+ Debug.Assert(Guid.TryParse(guid, out _));
+ logger.LogInformation("Success guid: {ContainerGuid}", guid);
+
+ return TypedResults.Ok(guid);
+ }
+}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs
new file mode 100644
index 0000000..1b81d65
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs
@@ -0,0 +1,19 @@
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.DependencyInjection;
+
+namespace Modules.BackupsTests.Api;
+
+public static class Extensions
+{
+ public static IServiceCollection AddBackupsTestsModule(this IServiceCollection services)
+ {
+ return services;
+ }
+
+ public static WebApplication MapBackupsTestsModuleEndpoints(this WebApplication app)
+ {
+ app.MapBackupsTestsEndpoints();
+
+ return app;
+ }
+}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj
new file mode 100644
index 0000000..ebb7576
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj
@@ -0,0 +1,20 @@
+
+
+
+ net9.0
+ enable
+ enable
+
+
+
+
+
+
+
+
+
+
+
+
+
+
From 792fd8bb4805226fdd79459844525012124f78e1 Mon Sep 17 00:00:00 2001
From: artur
Date: Wed, 5 Nov 2025 09:43:39 +0100
Subject: [PATCH 17/19] Change test status from bool to Enum Implement first
preview of creating test mysql container and recovering test local sql file.
---
.../Pages/BackupsModule/MyBackups.razor | 41 ++-
.../Services/DbBackupService.cs | 4 +-
.../Services/StatisticsService.cs | 5 +-
.../Entities/DbContext/BackupTest.cs | 6 +-
.../BackupsDbContextModelSnapshot.cs | 2 +-
...3810_ChangeEntityAddTestStatus.Designer.cs | 297 ++++++++++++++++++
...0251105083810_ChangeEntityAddTestStatus.cs | 28 ++
.../Dtos/BackupTestDto.cs | 6 +-
.../Dtos/PerformedBackupDto.cs | 4 +-
.../Enums/ETestStatus.cs | 8 +
.../BackupsTestsEO.cs | 96 +++++-
.../Modules.BackupsTests.Api.csproj | 6 +
12 files changed, 465 insertions(+), 38 deletions(-)
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs
create mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs
diff --git a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor
index 0477f98..d90b85a 100644
--- a/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor
+++ b/DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor
@@ -8,6 +8,7 @@
@using Client.UI.Data.Services
@using Microsoft.AspNetCore.SignalR.Client
@using Modules.Backup.Shared.Dtos
+@using Modules.Backup.Shared.Enums
@using Modules.Backup.Shared.Hubs
@implements IDisposable
@@ -38,7 +39,7 @@
File Location
- Test
+ Test
Status
@@ -63,15 +64,25 @@
@if (context.Test is not null)
{
- if (context.Test.IsSuccess)
+ switch (context.Test.Status)
{
- OK
- }
- else
- {
-
- Error
-
+ case ETestStatus.Success:
+ OK
+ break;
+
+ case ETestStatus.Failure:
+
+ Error
+
+ break;
+
+ case ETestStatus.Running:
+ Running
+ break;
+
+ default:
+ Not implemented status
+ break;
}
}
else
@@ -101,16 +112,20 @@
Href="@(Nav.ToAbsoluteUri($"/api/backups/download?id={context.Id}").ToString())"/>
- @switch (context.Test?.IsSuccess)
+ Disabled="@((context.Test?.Status == ETestStatus.Running) && context.Test is not null)">
+ @switch (context.Test?.Status)
{
- case true:
+ case ETestStatus.Success:
Successful Test
break;
- case false:
+ case ETestStatus.Failure:
Retry Test
break;
+
+ case ETestStatus.Running:
+ Test currently running...
+ break;
default:
Perform Test
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
index 1ce2f96..9384d63 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
@@ -152,7 +152,7 @@ public async Task, string>> GetAllBackups(string?
{
Id = y.Id,
ErrorMessage = y.ErrorMessage,
- IsSuccess = y.IsSuccess,
+ Status = y.Status,
TestedOn = y.TestedOn
}).FirstOrDefault()
}).ToList();
@@ -173,7 +173,7 @@ public async Task, string>> GetAllBackups(string?
{
Id = y.Id,
ErrorMessage = y.ErrorMessage,
- IsSuccess = y.IsSuccess,
+ Status = y.Status,
TestedOn = y.TestedOn
}).FirstOrDefault()
}));
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs
index f3cfbae..031f8df 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs
@@ -5,6 +5,7 @@
using Modules.Backup.Core.Entities.DbContext;
using Modules.Backup.Infrastructure.DbContexts;
using Modules.Backup.Shared.Dtos;
+using Modules.Backup.Shared.Enums;
using OneOf;
namespace Modules.Backup.Application.Services;
@@ -61,7 +62,7 @@ public async Task> GetMyDashboard(string? identi
totalTests++;
- if (appDb.BackupsTests.First(x => x.Id == backup.TestId).IsSuccess)
+ if (appDb.BackupsTests.First(x => x.Id == backup.TestId).Status == ETestStatus.Success)
successTests++;
}
}
@@ -103,7 +104,7 @@ public async Task> GetAdminDashboard()
.Average();
var totalTests = await appDb.BackupsTests.CountAsync();
- var successTests = await appDb.BackupsTests.CountAsync(x => x.IsSuccess);
+ var successTests = await appDb.BackupsTests.CountAsync(x => x.Status == ETestStatus.Success);
var testsSuccessRate = totalTests == 0 ? 0 : (100 * successTests / totalTests);
var dashboard = new AdminDashboardDto
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs
index da830f6..c41fc90 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs
@@ -1,10 +1,12 @@
-namespace Modules.Backup.Core.Entities.DbContext;
+using Modules.Backup.Shared.Enums;
+
+namespace Modules.Backup.Core.Entities.DbContext;
public sealed record BackupTest
{
public Guid Id { get; set; }
public Guid BackupId { get; set; }
public DateTime TestedOn { get; set; }
- public bool IsSuccess { get; set; }
+ public ETestStatus Status { get; set; } = ETestStatus.Running;
public string? ErrorMessage { get; set; }
}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
index 702584d..d7c64ad 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs
@@ -73,7 +73,7 @@ protected override void BuildModel(ModelBuilder modelBuilder)
b.Property("ErrorMessage")
.HasColumnType("TEXT");
- b.Property("IsSuccess")
+ b.Property("Status")
.HasColumnType("INTEGER");
b.Property("TestedOn")
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs
new file mode 100644
index 0000000..a929a82
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs
@@ -0,0 +1,297 @@
+//
+using System;
+using Microsoft.EntityFrameworkCore;
+using Microsoft.EntityFrameworkCore.Infrastructure;
+using Microsoft.EntityFrameworkCore.Migrations;
+using Microsoft.EntityFrameworkCore.Storage.ValueConversion;
+using Modules.Backup.Infrastructure.DbContexts;
+
+#nullable disable
+
+namespace Modules.Backup.Infrastructure.Migrations
+{
+ [DbContext(typeof(BackupsDbContext))]
+ [Migration("20251105083810_ChangeEntityAddTestStatus")]
+ partial class ChangeEntityAddTestStatus
+ {
+ ///
+ protected override void BuildTargetModel(ModelBuilder modelBuilder)
+ {
+#pragma warning disable 612, 618
+ modelBuilder.HasAnnotation("ProductVersion", "9.0.9");
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.AutomaticBackupTestConfig", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("AutomaticBackupTestConfigs");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupSchedule", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ConfigurationJson")
+ .HasColumnType("TEXT");
+
+ b.Property("DbConnectionId")
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("Name")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("NextBackupDate")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("Schedules");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.BackupTest", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("BackupId")
+ .HasColumnType("TEXT");
+
+ b.Property("ErrorMessage")
+ .HasColumnType("TEXT");
+
+ b.Property("Status")
+ .HasColumnType("INTEGER");
+
+ b.Property("TestedOn")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("BackupsTests");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerConnection", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("AutoTestBackupsConfigId")
+ .HasColumnType("TEXT");
+
+ b.Property("BackupEncryptionKeyHas")
+ .HasColumnType("TEXT");
+
+ b.Property("ConnectionName")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbName")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbPasswd")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("DbType")
+ .HasColumnType("INTEGER");
+
+ b.Property("DbUser")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("IsDisabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("IsTunnelRequired")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("SsL")
+ .HasColumnType("INTEGER");
+
+ b.Property("TunnelId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("DbConnections");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.DbServerTunnel", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("Description")
+ .HasColumnType("TEXT");
+
+ b.Property("IsActive")
+ .HasColumnType("INTEGER");
+
+ b.Property("LocalPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("Password")
+ .HasColumnType("TEXT");
+
+ b.Property("PrivateKeyContent")
+ .HasColumnType("TEXT");
+
+ b.Property("PrivateKeyPassphrase")
+ .HasColumnType("TEXT");
+
+ b.Property("RemoteHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("RemotePort")
+ .HasColumnType("INTEGER");
+
+ b.Property("ServerHost")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("SshPort")
+ .HasColumnType("INTEGER");
+
+ b.Property("UsePasswordAuth")
+ .HasColumnType("INTEGER");
+
+ b.Property("Username")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("DbServerTunnels");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.PerformedBackup", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("CreatedOn")
+ .HasColumnType("TEXT");
+
+ b.Property("FilePath")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("IsSoftDeleted")
+ .HasColumnType("INTEGER");
+
+ b.Property("Name")
+ .IsRequired()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerConnectionId")
+ .HasColumnType("TEXT");
+
+ b.Property("TestId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("Backups");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServerBackupsConfiguration", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.Property("TimeInDaysToHoldBackups")
+ .HasColumnType("INTEGER");
+
+ b.HasKey("Id");
+
+ b.ToTable("Configurations");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.ServersUsers", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("ServerId")
+ .HasColumnType("TEXT");
+
+ b.Property("UserId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("UsersServers");
+ });
+
+ modelBuilder.Entity("Modules.Backup.Core.Entities.DbContext.UserNotificationsSettings", b =>
+ {
+ b.Property("Id")
+ .ValueGeneratedOnAdd()
+ .HasColumnType("TEXT");
+
+ b.Property("IsEnabled")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnChanges")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnErrors")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnFailedBackups")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnFailedTests")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnSuccessfulBackup")
+ .HasColumnType("INTEGER");
+
+ b.Property("NotifyOnUpdates")
+ .HasColumnType("INTEGER");
+
+ b.Property("UserId")
+ .HasColumnType("TEXT");
+
+ b.HasKey("Id");
+
+ b.ToTable("UsersNotificationsSettings");
+ });
+#pragma warning restore 612, 618
+ }
+ }
+}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs
new file mode 100644
index 0000000..82e09c0
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs
@@ -0,0 +1,28 @@
+using Microsoft.EntityFrameworkCore.Migrations;
+
+#nullable disable
+
+namespace Modules.Backup.Infrastructure.Migrations
+{
+ ///
+ public partial class ChangeEntityAddTestStatus : Migration
+ {
+ ///
+ protected override void Up(MigrationBuilder migrationBuilder)
+ {
+ migrationBuilder.RenameColumn(
+ name: "IsSuccess",
+ table: "BackupsTests",
+ newName: "Status");
+ }
+
+ ///
+ protected override void Down(MigrationBuilder migrationBuilder)
+ {
+ migrationBuilder.RenameColumn(
+ name: "Status",
+ table: "BackupsTests",
+ newName: "IsSuccess");
+ }
+ }
+}
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs
index 3b9f9c0..1bd9ca2 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs
@@ -1,9 +1,11 @@
-namespace Modules.Backup.Shared.Dtos;
+using Modules.Backup.Shared.Enums;
+
+namespace Modules.Backup.Shared.Dtos;
public class BackupTestDto
{
public Guid Id { get; set; } = Guid.CreateVersion7();
public DateTime TestedOn { get; set; }
- public bool IsSuccess { get; set; }
+ public ETestStatus Status { get; set; }
public string? ErrorMessage { get; set; }
}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs
index 6192f35..e7e4082 100644
--- a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs
@@ -1,4 +1,6 @@
-namespace Modules.Backup.Shared.Dtos;
+using System.Data;
+
+namespace Modules.Backup.Shared.Dtos;
public class PerformedBackupDto
{
diff --git a/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs
new file mode 100644
index 0000000..a507425
--- /dev/null
+++ b/DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs
@@ -0,0 +1,8 @@
+namespace Modules.Backup.Shared.Enums;
+
+public enum ETestStatus
+{
+ Running,
+ Success,
+ Failure
+}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs
index 9e8fcea..51758be 100644
--- a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs
+++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs
@@ -4,6 +4,7 @@
using Microsoft.AspNetCore.Http;
using Microsoft.Extensions.Logging;
using Modules.Shared.Attributes;
+using MySqlConnector;
namespace Modules.BackupsTests.Api;
@@ -15,7 +16,7 @@ public static WebApplication MapBackupsTestsEndpoints(this WebApplication app)
// .RequireAuthorization()
// .AddEndpointFilter();
- api.MapGet("RunTest", BackupsTestsOperations.RunTest)
+ api.MapPost("RunTest", BackupsTestsOperations.RunTest)
.WithSummary("Run test dev container");
return app;
@@ -28,27 +29,92 @@ public static async Task RunTest(
HttpContext context,
ILogger logger)
{
+ //TODO: Implement accepting id of backup, get it from db, check file path, file name, unzip file etc
+ // TODO: Implement additional status for backup test like running, failed, success etc
+ var backupFolder = "/home/artur/.local/share/OctoBackup/Backups/localhost_3306/app"; // lokalny folder z dump.sql
+ var dbName = "app";
+ var password = "toor";
+
+ logger.LogInformation("Budowanie kontenera");
+ // 1️⃣ Tworzymy kontener MySQL z mapowaniem folderu backupu
var container = new ContainerBuilder()
- .WithImage("testcontainers/helloworld:1.3.0")
- .WithPortBinding(8080, true)
- // Wait until the HTTP endpoint of the container is available.
- .WithWaitStrategy(Wait.ForUnixContainer().UntilHttpRequestIsSucceeded(r => r.ForPort(8080)))
+ .WithImage("mysql:8.0")
+ .WithEnvironment("MYSQL_ROOT_PASSWORD", password)
+ .WithEnvironment("MYSQL_DATABASE", dbName)
+ .WithBindMount(backupFolder, "/backup")
+ .WithPortBinding(3306, true)
+ .WithWaitStrategy(Wait.ForUnixContainer().UntilMessageIsLogged("ready for connections"))
.Build();
- await container.StartAsync()
- .ConfigureAwait(false);
+ logger.LogInformation("Startuje kontener");
+ await container.StartAsync().ConfigureAwait(false);
+
+ logger.LogInformation("Pobieram dane kontenera");
+ var host = container.Hostname;
+ var port = container.GetMappedPublicPort(3306);
+
+ logger.LogInformation("Hostname: {Host}, Port: {Port}", host, port);
+
+ logger.LogInformation("Czekam na możliwość podlaczenia sie do bazy");
+ // 2️⃣ Czekamy aż MySQL wystartuje
+ var connStr = $"Server={host};Port={port};User ID=root;Password={password};Database={dbName};SslMode=none;AllowPublicKeyRetrieval=True";
+ await WaitForDatabaseAsync(connStr);
+
+ logger.LogInformation("Przywracam backup");
+ // 3️⃣ Przywrócenie backupu (załóżmy że dump.sql leży w /backup)
+ await container.ExecAsync(["bash", "-c", $"mysql -uroot -p{password} {dbName} < /backup/2025.11.05.08.04.sql"]);
+
+ // 4️⃣ Sprawdzenie czy są tabele inne niż systemowe
+ await using var conn = new MySqlConnection(connStr);
+ await conn.OpenAsync();
- using var httpClient = new HttpClient();
+ logger.LogInformation("Sprawdzam czy zostaly jakies tabele stworzone");
+ var cmd = new MySqlCommand(
+ "SELECT TABLE_NAME FROM information_schema.tables WHERE table_schema = @db AND TABLE_NAME NOT LIKE 'sys_%';",
+ conn);
+ cmd.Parameters.AddWithValue("@db", dbName);
- // Construct the request URI by specifying the scheme, hostname, assigned random host port, and the endpoint "uuid".
- var requestUri = new UriBuilder(Uri.UriSchemeHttp, container.Hostname, container.GetMappedPublicPort(8080), "uuid").Uri;
+ var tables = new List();
+ await using var reader = await cmd.ExecuteReaderAsync();
+ while (await reader.ReadAsync())
+ tables.Add(reader.GetString(0));
- // Send an HTTP GET request to the specified URI and retrieve the response as a string.
- var guid = await httpClient.GetStringAsync(requestUri).ConfigureAwait(false);
+ logger.LogInformation("Znalezione tabele: {Tables}", string.Join(", ", tables));
- Debug.Assert(Guid.TryParse(guid, out _));
- logger.LogInformation("Success guid: {ContainerGuid}", guid);
+ logger.LogInformation("Stopuje i usuwam testowy kontener");
+ await container.StopAsync();
+ await container.DisposeAsync();
+
+ logger.LogInformation("Zwracam wynik");
+ return TypedResults.Ok(new
+ {
+ Tables = tables,
+ Success = tables.Count > 0
+ });
+ }
+
+ private static async Task WaitForDatabaseAsync(string connStr)
+ {
+ var timeout = TimeSpan.FromSeconds(30);
+ var sw = Stopwatch.StartNew();
+
+ Exception exception = new();
- return TypedResults.Ok(guid);
+ while (sw.Elapsed < timeout)
+ {
+ try
+ {
+ await using var conn = new MySqlConnection(connStr);
+ await conn.OpenAsync();
+ return;
+ }
+ catch (Exception ex)
+ {
+ exception = ex;
+ await Task.Delay(1000);
+ }
+ }
+
+ throw new Exception($"MySQL container did not start in time. Error: {exception.Message}", exception);
}
}
\ No newline at end of file
diff --git a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj
index ebb7576..bbb034c 100644
--- a/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj
+++ b/DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj
@@ -17,4 +17,10 @@
+
+
+ ..\..\..\..\..\..\..\..\.nuget\packages\mysqlconnector\2.4.0\lib\net9.0\MySqlConnector.dll
+
+
+
From 6df1edb9f12e098a94fd547a8f931dae2b98c245 Mon Sep 17 00:00:00 2001
From: Artur Lewandowski
Date: Thu, 22 Oct 2026 01:03:42 +0200
Subject: [PATCH 18/19] Refactor code. Change blazor wasm to react vite.
Upgrade project to .net 10. Clean up. Implement OWASP Top 10. Fix found bugs
while testing. Change UI design.
---
.agents/skills/feature-arch/SKILL.md | 110 +
.../bound-event-based-communication.md | 84 +
.../references/bound-feature-isolation.md | 88 +
.../bound-feature-scoped-routing.md | 76 +
.../references/bound-feature-size.md | 74 +
.../references/bound-interface-contracts.md | 83 +
.../references/bound-minimize-shared-state.md | 73 +
.../references/fcomp-colocate-styles.md | 88 +
.../fcomp-composition-over-props.md | 100 +
.../fcomp-container-presentational.md | 99 +
.../references/fcomp-error-boundaries.md | 99 +
.../fcomp-props-as-data-boundary.md | 88 +
.../references/fcomp-single-responsibility.md | 99 +
.../references/fquery-avoid-n-plus-one.md | 80 +
.../fquery-colocate-with-feature.md | 70 +
.../references/fquery-feature-scoped-keys.md | 72 +
.../references/fquery-parallel-fetching.md | 71 +
.../fquery-server-component-fetching.md | 88 +
.../fquery-single-responsibility.md | 66 +
.../references/fstate-context-sparingly.md | 73 +
.../fstate-feature-scoped-stores.md | 79 +
.../references/fstate-lift-minimally.md | 85 +
.../references/fstate-reset-on-unmount.md | 89 +
.../fstate-server-state-separation.md | 93 +
.../references/import-avoid-barrel-files.md | 63 +
.../references/import-no-cross-feature.md | 84 +
.../references/import-path-aliases.md | 64 +
.../references/import-public-api.md | 67 +
.../references/import-type-only.md | 81 +
.../references/import-unidirectional-flow.md | 82 +
.../references/name-descriptive-exports.md | 65 +
.../references/name-feature-naming.md | 60 +
.../references/name-file-conventions.md | 79 +
.../references/struct-app-layer.md | 73 +
.../references/struct-feature-folders.md | 70 +
.../struct-feature-self-contained.md | 62 +
.../references/struct-flat-hierarchy.md | 58 +
.../references/struct-optional-segments.md | 72 +
.../references/struct-shared-layer.md | 68 +
.../references/test-colocate-with-feature.md | 78 +
.../references/test-feature-isolation.md | 88 +
.../test-integration-at-app-layer.md | 87 +
.../references/test-shared-utilities.md | 94 +
.agents/skills/msw/SKILL.md | 121 +
.../references/advanced-bypass-requests.md | 81 +
.../msw/references/advanced-cookies-auth.md | 119 +
.../references/advanced-dynamic-scenarios.md | 114 +
.../msw/references/advanced-file-uploads.md | 109 +
.../advanced-playwright-integration.md | 78 +
.../msw/references/advanced-vitest-browser.md | 100 +
.../references/advanced-websocket-mocking.md | 87 +
.../msw/references/debug-common-issues.md | 79 +
.../msw/references/debug-lifecycle-events.md | 88 +
.../msw/references/debug-request-logging.md | 113 +
.../references/debug-verify-interception.md | 95 +
.../msw/references/graphql-batched-queries.md | 93 +
.../msw/references/graphql-error-responses.md | 119 +
.../references/graphql-operation-handlers.md | 101 +
.../msw/references/graphql-schema-first.md | 76 +
.../references/graphql-variables-access.md | 123 +
.../msw/references/handler-absolute-urls.md | 70 +
.../msw/references/handler-domain-grouping.md | 81 +
.../references/handler-happy-path-first.md | 60 +
.../handler-request-body-parsing.md | 76 +
.../references/handler-resolver-argument.md | 86 +
.../handler-reusability-environments.md | 80 +
.../references/handler-shared-resolvers.md | 99 +
.../references/handler-v2-response-syntax.md | 94 +
.../msw/references/match-custom-predicate.md | 99 +
.../msw/references/match-handler-order.md | 93 +
.../msw/references/match-http-methods.md | 98 +
.../msw/references/match-query-params.md | 89 +
.../msw/references/match-url-patterns.md | 87 +
.../msw/references/response-custom-headers.md | 125 +
.../references/response-delay-realistic.md | 92 +
.../references/response-error-simulation.md | 110 +
.../response-http-response-helpers.md | 83 +
.../references/response-one-time-handlers.md | 103 +
.../msw/references/response-streaming.md | 114 +
.../msw/references/setup-lifecycle-hooks.md | 57 +
.../msw/references/setup-node-version.md | 72 +
.../setup-server-node-entrypoint.md | 45 +
.../msw/references/setup-typescript-config.md | 74 +
.../references/setup-unhandled-requests.md | 70 +
.../references/setup-worker-script-commit.md | 65 +
.../msw/references/test-async-utilities.md | 81 +
.../test-avoid-request-assertions.md | 87 +
.../references/test-clear-request-cache.md | 85 +
.../references/test-concurrent-boundary.md | 88 +
.../msw/references/test-fake-timers-config.md | 91 +
.../msw/references/test-jsdom-environment.md | 67 +
.../msw/references/test-reset-handlers.md | 63 +
.agents/skills/nextjs/SKILL.md | 115 +
.../references/action-error-handling.md | 75 +
.../references/action-optimistic-updates.md | 74 +
.../references/action-pending-states.md | 68 +
.../nextjs/references/action-revalidation.md | 78 +
.../references/action-server-action-forms.md | 75 +
.../nextjs/references/build-barrel-files.md | 50 +
.../references/build-dynamic-imports.md | 62 +
.../references/build-external-packages.md | 48 +
.../build-optimize-package-imports.md | 42 +
.../references/build-turbopack-config.md | 71 +
.../nextjs/references/cache-fetch-options.md | 53 +
.../nextjs/references/cache-react-cache.md | 58 +
.../references/cache-revalidate-path.md | 62 +
.../nextjs/references/cache-revalidate-tag.md | 65 +
.../nextjs/references/cache-segment-config.md | 63 +
.../references/cache-use-cache-directive.md | 57 +
.../references/client-children-pattern.md | 75 +
.../references/client-hydration-mismatch.md | 101 +
.../references/client-third-party-scripts.md | 67 +
.../references/client-use-client-boundary.md | 72 +
.../references/meta-generate-metadata.md | 70 +
.../references/meta-opengraph-images.md | 72 +
.../skills/nextjs/references/meta-robots.md | 68 +
.../skills/nextjs/references/meta-sitemap.md | 76 +
.../references/route-instant-navigations.md | 97 +
.../references/route-intercepting-routes.md | 76 +
.../nextjs/references/route-not-found.md | 59 +
.../references/route-parallel-routes.md | 79 +
.../references/route-partial-prefetching.md | 87 +
.../nextjs/references/route-prefetching.md | 71 +
.../nextjs/references/route-proxy-ts.md | 62 +
.../server-avoid-client-fetching.md | 71 +
.../references/server-component-streaming.md | 70 +
.../references/server-data-colocation.md | 63 +
.../references/server-error-handling.md | 79 +
.../references/server-parallel-fetching.md | 69 +
.../references/server-preload-pattern.md | 68 +
.../nextjs/references/stream-error-tsx.md | 67 +
.../nextjs/references/stream-loading-tsx.md | 63 +
.../references/stream-nested-suspense.md | 82 +
.../references/stream-skeleton-matching.md | 72 +
.../references/stream-suspense-boundaries.md | 62 +
.agents/skills/nuqs/SKILL.md | 110 +
.../references/advanced-custom-parsers.md | 70 +
.../nuqs/references/advanced-eq-function.md | 94 +
.../references/advanced-framework-adapters.md | 82 +
.../nuqs/references/advanced-url-keys.md | 62 +
.../nuqs/references/debug-common-errors.md | 53 +
.../nuqs/references/debug-enable-logging.md | 51 +
.../skills/nuqs/references/debug-testing.md | 55 +
.../nuqs/references/history-back-sync.md | 51 +
.../references/history-push-navigation.md | 76 +
.../references/history-replace-ephemeral.md | 87 +
.../references/history-scroll-behavior.md | 60 +
.../nuqs/references/parser-array-format.md | 59 +
.../nuqs/references/parser-date-format.md | 67 +
.../nuqs/references/parser-enum-validation.md | 81 +
.../nuqs/references/parser-hex-colors.md | 68 +
.../nuqs/references/parser-index-offset.md | 72 +
.../nuqs/references/parser-json-validation.md | 97 +
.../references/parser-use-typed-parsers.md | 58 +
.../nuqs/references/parser-with-default.md | 65 +
.../nuqs/references/perf-avoid-rerender.md | 88 +
.../nuqs/references/perf-clear-on-default.md | 55 +
.../nuqs/references/perf-debounce-search.md | 82 +
.../nuqs/references/perf-serialize-utility.md | 81 +
.../nuqs/references/perf-throttle-updates.md | 66 +
.../nuqs/references/server-next15-async.md | 80 +
.../references/server-parse-before-get.md | 82 +
.../references/server-search-params-cache.md | 78 +
.../nuqs/references/server-shallow-false.md | 74 +
.../nuqs/references/server-share-parsers.md | 74 +
.../nuqs/references/server-use-transition.md | 96 +
.../nuqs/references/setup-import-server.md | 72 +
.../nuqs/references/setup-nextjs-version.md | 64 +
.../nuqs/references/setup-nuqs-adapter.md | 77 +
.../nuqs/references/setup-shared-parsers.md | 73 +
.../nuqs/references/setup-use-client.md | 69 +
.../nuqs/references/state-avoid-derived.md | 84 +
.../nuqs/references/state-clear-with-null.md | 81 +
.../references/state-controlled-inputs.md | 83 +
.../references/state-functional-updates.md | 68 +
.../references/state-options-inheritance.md | 78 +
.../nuqs/references/state-setter-return.md | 78 +
.../nuqs/references/state-use-query-states.md | 75 +
.agents/skills/playwright/SKILL.md | 114 +
.../references/arch-cleanup-state.md | 83 +
.../playwright/references/arch-fixtures.md | 89 +
.../references/arch-page-object-model.md | 80 +
.../references/arch-parallel-execution.md | 75 +
.../references/arch-test-isolation.md | 61 +
.../references/arch-test-production.md | 74 +
.../references/assert-aria-snapshots.md | 58 +
.../playwright/references/auth-api-login.md | 99 +
.../references/auth-multiple-roles.md | 111 +
.../references/auth-parallel-workers.md | 101 +
.../references/auth-session-storage.md | 106 +
.../references/auth-storage-state.md | 97 +
.../references/debug-ci-reporters.md | 81 +
.../playwright/references/debug-inspector.md | 86 +
.../references/debug-screenshots-videos.md | 85 +
.../references/debug-trace-viewer.md | 79 +
.../playwright/references/loc-avoid-xpath.md | 64 +
.../references/loc-chained-locators.md | 87 +
.../playwright/references/loc-data-testid.md | 80 +
.../references/loc-frame-locator.md | 45 +
.../references/loc-label-selectors.md | 78 +
.../references/loc-placeholder-selector.md | 87 +
.../references/loc-role-selectors.md | 74 +
.../references/loc-text-selectors.md | 77 +
.../references/mock-abort-requests.md | 107 +
.../references/mock-api-responses.md | 91 +
.../playwright/references/mock-har-files.md | 100 +
.../references/mock-intercept-modify.md | 101 +
.../references/mock-network-conditions.md | 98 +
.../references/next-app-router-navigation.md | 87 +
.../references/next-baseurl-config.md | 108 +
.../references/next-server-actions.md | 90 +
.../references/next-server-components.md | 92 +
.../references/next-wait-hydration.md | 103 +
.../references/perf-browser-selection.md | 99 +
.../playwright/references/perf-headless-ci.md | 100 +
.../playwright/references/perf-retries.md | 100 +
.../references/perf-reuse-server.md | 87 +
.../playwright/references/perf-sharding.md | 105 +
.../references/wait-action-retries.md | 83 +
.../references/wait-avoid-hard-waits.md | 90 +
.../references/wait-custom-timeout.md | 98 +
.../references/wait-network-idle.md | 65 +
.../references/wait-soft-assertions.md | 78 +
.../references/wait-web-first-assertions.md | 91 +
.agents/skills/react-hook-form/SKILL.md | 119 +
.../references/adv-devtools-performance.md | 69 +
.../references/adv-formprovider-memo.md | 78 +
.../references/adv-opaque-types.md | 52 +
.../references/adv-testing-wrapper.md | 63 +
.../array-complete-default-objects.md | 66 +
.../array-separate-crud-operations.md | 76 +
.../array-unique-fieldarray-per-name.md | 58 +
.../references/array-use-field-id-as-key.md | 54 +
.../array-virtualization-formprovider.md | 64 +
.../ctrl-avoid-double-registration.md | 46 +
.../references/ctrl-controller-field-props.md | 56 +
.../ctrl-local-state-combination.md | 69 +
...ctrl-single-usecontroller-per-component.md | 66 +
.../ctrl-usecontroller-isolation.md | 64 +
.../formcfg-async-default-values.md | 69 +
.../references/formcfg-default-values.md | 57 +
.../references/formcfg-revalidate-mode.md | 52 +
.../references/formcfg-should-unregister.md | 64 +
.../formcfg-useeffect-dependency.md | 54 +
.../references/formcfg-validation-mode.md | 55 +
.../formstate-avoid-isvalid-with-onsubmit.md | 57 +
.../formstate-destructure-formstate.md | 48 +
...ormstate-getfieldstate-for-single-field.md | 54 +
.../formstate-subscribe-to-specific-fields.md | 54 +
.../formstate-useformstate-isolation.md | 65 +
.../integ-mui-controller-pattern.md | 59 +
.../references/integ-shadcn-form-import.md | 64 +
.../references/integ-shadcn-select-wiring.md | 64 +
.../integ-typed-submit-server-action.md | 52 +
.../references/integ-value-transform.md | 59 +
.../references/sub-avoid-watch-in-render.md | 48 +
.../references/sub-deep-subscription.md | 62 +
.../sub-useformcontext-sparingly.md | 58 +
.../references/sub-usewatch-default-value.md | 50 +
.../references/sub-usewatch-over-watch.md | 58 +
.../references/sub-usewatch-with-getvalues.md | 54 +
.../references/sub-watch-specific-fields.md | 54 +
.../references/valid-delay-error.md | 52 +
.../valid-dynamic-schema-factory.md | 57 +
.../valid-error-message-strategy.md | 82 +
.../references/valid-form-level-validate.md | 47 +
.../references/valid-inline-vs-resolver.md | 63 +
.../references/valid-native-validation.md | 60 +
.../references/valid-resolver-caching.md | 58 +
.../references/valid-trigger-should-touch.md | 44 +
.agents/skills/react/SKILL.md | 87 +
.agents/skills/react/references/_sections.md | 46 +
.../references/conc-automatic-batching.md | 64 +
.../react/references/conc-concurrent-safe.md | 71 +
.../references/conc-suspense-fallback.md | 66 +
.../references/conc-use-deferred-value.md | 65 +
.../react/references/conc-use-transition.md | 75 +
.../react/references/conc-view-transitions.md | 81 +
.../references/data-cache-deduplication.md | 60 +
.../react/references/data-error-boundaries.md | 76 +
.../references/data-parallel-fetching.md | 74 +
.../references/data-suspense-data-fetching.md | 76 +
.../skills/react/references/data-use-hook.md | 77 +
.../references/effect-avoid-unnecessary.md | 69 +
.../skills/react/references/effect-cleanup.md | 75 +
.../references/effect-object-dependencies.md | 56 +
.../references/effect-use-browser-only.md | 62 +
.../references/effect-use-effect-event.md | 53 +
.../effect-use-sync-external-store.md | 80 +
.../skills/react/references/form-actions.md | 83 +
.../react/references/form-use-action-state.md | 80 +
.../react/references/form-use-form-status.md | 68 +
.../react/references/form-use-optimistic.md | 77 +
.../react/references/form-validation.md | 89 +
.../react/references/memo-avoid-premature.md | 68 +
.../skills/react/references/memo-compiler.md | 84 +
.../react/references/memo-react-memo.md | 72 +
.../react/references/memo-use-callback.md | 70 +
.../skills/react/references/memo-use-memo.md | 53 +
.../react/references/rcomp-composition.md | 75 +
.../references/rcomp-controlled-components.md | 63 +
.../react/references/rcomp-fragment-refs.md | 71 +
.../react/references/rcomp-key-reset.md | 74 +
.../react/references/rcomp-render-props.md | 69 +
.../references/rsc-avoid-client-only-libs.md | 66 +
.../references/rsc-composition-pattern.md | 90 +
.../react/references/rsc-context-provider.md | 50 +
.../references/rsc-data-fetching-server.md | 68 +
.../references/rsc-serializable-props.md | 70 +
.../references/rsc-server-client-boundary.md | 63 +
.../skills/react/references/rsc-streaming.md | 64 +
.../references/rstate-context-optimization.md | 68 +
.../react/references/rstate-derived-values.md | 70 +
.../references/rstate-functional-updates.md | 58 +
.../references/rstate-lazy-initialization.md | 59 +
.../react/references/rstate-use-reducer.md | 77 +
.agents/skills/shadcn/SKILL.md | 110 +
.../references/ally-ensure-color-contrast.md | 62 +
.../ally-maintain-focus-management.md | 84 +
.../ally-preserve-aria-attributes.md | 77 +
.../ally-preserve-keyboard-navigation.md | 72 +
.../references/ally-provide-sr-only-labels.md | 75 +
.../references/arch-current-cli-registry.md | 61 +
.../arch-extend-variants-with-cva.md | 67 +
...-forward-refs-for-composable-components.md | 83 +
.../arch-isolate-component-variants.md | 82 +
...arch-preserve-radix-primitive-structure.md | 57 +
.../references/arch-unified-radix-package.md | 44 +
.../arch-use-asChild-for-custom-triggers.md | 49 +
.../arch-use-cn-for-class-merging.md | 62 +
.../comp-combine-command-with-popover.md | 106 +
.../comp-compose-with-compound-components.md | 104 +
.../comp-create-reusable-form-fields.md | 157 +
.../references/comp-nest-dialogs-correctly.md | 108 +
.../comp-use-drawer-for-mobile-modals.md | 128 +
.../comp-use-slot-pattern-for-flexibility.md | 118 +
.../data-empty-states-with-guidance.md | 95 +
.../references/data-paginate-server-side.md | 108 +
.../data-use-skeleton-loading-states.md | 104 +
...a-use-tanstack-table-for-complex-tables.md | 121 +
.../references/data-virtualize-large-lists.md | 82 +
.../form-handle-async-validation.md | 104 +
.../form-reset-form-state-correctly.md | 92 +
.../form-show-validation-errors-correctly.md | 58 +
.../form-use-react-hook-form-integration.md | 106 +
.../form-use-zod-for-schema-validation.md | 86 +
...rf-avoid-unnecessary-rerenders-in-forms.md | 88 +
.../references/perf-debounce-search-inputs.md | 85 +
.../perf-lazy-load-heavy-components.md | 90 +
.../perf-memoize-expensive-renders.md | 90 +
.../references/perf-optimize-icon-imports.md | 60 +
.../state-colocate-state-with-components.md | 103 +
.../state-lift-state-to-appropriate-level.md | 103 +
...e-prefer-uncontrolled-for-simple-inputs.md | 91 +
.../state-use-controlled-dialog-state.md | 127 +
.../style-avoid-important-overrides.md | 58 +
.../style-consistent-spacing-scale.md | 67 +
.../references/style-dark-mode-support.md | 83 +
.../style-responsive-design-patterns.md | 75 +
.../style-use-css-variables-for-theming.md | 56 +
.../style-use-tailwind-theme-extend.md | 63 +
.agents/skills/tailwind/SKILL.md | 109 +
.../tailwind/references/anim-3d-transforms.md | 56 +
.../references/anim-gpu-accelerated.md | 47 +
.../references/anim-gradient-interpolation.md | 46 +
.../references/anim-starting-style.md | 63 +
.../tailwind/references/build-cli-package.md | 43 +
.../references/build-content-detection.md | 44 +
.../tailwind/references/build-css-import.md | 36 +
.../tailwind/references/build-node-version.md | 44 +
.../references/build-postcss-simplify.md | 40 +
.../tailwind/references/build-vite-plugin.md | 39 +
.../references/bundle-avoid-cdn-production.md | 56 +
.../references/bundle-avoid-preprocessors.md | 53 +
.../references/bundle-css-minification.md | 57 +
.../bundle-remove-unused-plugins.md | 55 +
.../references/bundle-split-critical-css.md | 62 +
.../references/comp-avoid-apply-overuse.md | 58 +
.../references/comp-container-customize.md | 59 +
.../references/comp-reference-directive.md | 59 +
.../tailwind/references/comp-smart-sorting.md | 50 +
.../references/comp-utility-file-scope.md | 61 +
.../references/gen-avoid-theme-bloat.md | 47 +
.../references/gen-css-first-config.md | 54 +
.../references/gen-css-variable-syntax.md | 43 +
.../references/gen-dynamic-utilities.md | 51 +
.../tailwind/references/gen-oklch-colors.md | 40 +
.../references/gen-utility-directive.md | 52 +
.../references/resp-container-queries.md | 55 +
.../references/resp-custom-breakpoints.md | 54 +
.../references/resp-hover-capability.md | 60 +
.../references/resp-logical-properties.md | 51 +
.../tailwind/references/resp-mobile-first.md | 48 +
.../tailwind/references/theme-color-scheme.md | 55 +
.../references/theme-dark-mode-class.md | 59 +
.../references/theme-prefix-variables.md | 56 +
.../references/theme-runtime-variables.md | 55 +
.../references/theme-semantic-tokens.md | 65 +
.../references/util-explicit-colors.md | 43 +
.../references/util-gradient-via-none.md | 37 +
.../references/util-important-modifier.md | 43 +
.../references/util-opacity-modifier.md | 50 +
.../references/util-renamed-utilities.md | 45 +
.../references/util-variant-stacking.md | 41 +
.agents/skills/tanstack-query/SKILL.md | 117 +
.../references/cache-enabled-option.md | 76 +
.../references/cache-global-defaults.md | 73 +
.../cache-invalidation-precision.md | 78 +
.../cache-placeholder-vs-initial.md | 69 +
.../references/cache-refetch-triggers.md | 68 +
.../references/cache-staletime-gctime.md | 71 +
.../references/error-conditional-retry.md | 93 +
.../references/error-display-patterns.md | 100 +
.../references/error-global-handler.md | 91 +
.../references/error-retry-config.md | 80 +
.../references/error-throw-on-error.md | 96 +
.../references/infinite-flatten-pages.md | 108 +
.../references/infinite-loading-states.md | 96 +
.../references/infinite-max-pages.md | 86 +
.../references/infinite-refetch-behavior.md | 79 +
.../references/mutation-avoid-parallel.md | 92 +
.../references/mutation-cancel-queries.md | 72 +
.../mutation-invalidate-onsettled.md | 66 +
.../references/mutation-optimistic-updates.md | 81 +
.../references/mutation-setquerydata.md | 67 +
.../references/prefetch-avoid-waterfalls.md | 98 +
.../references/prefetch-flatten-api.md | 70 +
.../references/prefetch-in-queryfn.md | 97 +
.../references/prefetch-infinite-query.md | 60 +
.../references/prefetch-on-hover.md | 94 +
.../references/prefetch-server-components.md | 88 +
.../references/render-notify-props.md | 66 +
.../references/render-select-derived.md | 86 +
.../references/render-select-memoize.md | 75 +
.../references/render-structural-sharing.md | 88 +
.../references/render-tracked-props.md | 80 +
.../suspense-boundaries-placement.md | 97 +
.../references/suspense-error-boundaries.md | 100 +
.../references/suspense-parallel-queries.md | 93 +
.../references/suspense-use-suspense-hooks.md | 66 +
.../references/tquery-always-arrays.md | 49 +
.../references/tquery-colocate-keys.md | 66 +
.../references/tquery-hierarchical-keys.md | 61 +
.../references/tquery-key-factories.md | 58 +
.../references/tquery-options-pattern.md | 78 +
.../references/tquery-serializable-objects.md | 60 +
.agents/skills/tdd/SKILL.md | 114 +
.../tdd/references/assert-custom-matchers.md | 86 +
.../tdd/references/assert-error-messages.md | 64 +
.../assert-no-assertions-antipattern.md | 70 +
.../tdd/references/assert-snapshot-testing.md | 71 +
.../references/assert-specific-assertions.md | 71 +
.../references/cycle-maintain-test-list.md | 68 +
.../references/cycle-minimal-code-to-pass.md | 62 +
.../references/cycle-refactor-after-green.md | 58 +
.../tdd/references/cycle-small-increments.md | 69 +
.../cycle-verify-test-fails-first.md | 64 +
.../tdd/references/cycle-write-test-first.md | 63 +
.../references/data-avoid-mystery-guests.md | 62 +
.../tdd/references/data-builder-pattern.md | 99 +
.../tdd/references/data-minimal-setup.md | 69 +
.../tdd/references/data-unique-identifiers.md | 79 +
.../tdd/references/data-use-factories.md | 87 +
.../tdd/references/design-aaa-pattern.md | 68 +
.../references/design-avoid-logic-in-tests.md | 74 +
.../design-descriptive-test-names.md | 64 +
.../design-one-assertion-per-test.md | 66 +
...design-test-behavior-not-implementation.md | 69 +
.../tdd/references/design-test-edge-cases.md | 83 +
.../references/isolate-deterministic-tests.md | 80 +
.../isolate-mock-external-dependencies.md | 69 +
.../tdd/references/isolate-no-shared-state.md | 73 +
.../isolate-prefer-stubs-over-mocks.md | 72 +
.../isolate-use-dependency-injection.md | 91 +
.../tdd/references/org-file-structure.md | 76 +
.../tdd/references/org-group-by-behavior.md | 68 +
.../tdd/references/org-parameterized-tests.md | 79 +
.../tdd/references/org-setup-teardown.md | 84 +
.../tdd/references/org-test-utilities.md | 98 +
.../references/perf-avoid-network-calls.md | 78 +
.../skills/tdd/references/perf-avoid-sleep.md | 82 +
.../tdd/references/perf-fast-unit-tests.md | 48 +
.../tdd/references/perf-fix-flaky-tests.md | 83 +
.../tdd/references/perf-parallelize-tests.md | 87 +
.../tdd/references/strat-coverage-targets.md | 70 +
.../references/strat-e2e-critical-paths.md | 78 +
.../strat-integration-boundaries.md | 79 +
.../tdd/references/strat-mutation-testing.md | 71 +
.../tdd/references/strat-test-pyramid.md | 58 +
.agents/skills/typescript/SKILL.md | 103 +
.../references/advanced-branded-types.md | 83 +
.../references/advanced-satisfies-operator.md | 94 +
.../advanced-template-literal-types.md | 105 +
.../references/async-avoid-loop-await.md | 78 +
.../async-avoid-unnecessary-async.md | 61 +
.../references/async-defer-await.md | 74 +
.../references/async-explicit-return-types.md | 79 +
.../references/async-parallel-promises.md | 63 +
.../references/mem-avoid-closure-leaks.md | 88 +
.../references/mem-avoid-global-state.md | 97 +
.../references/mem-cleanup-event-listeners.md | 111 +
.../typescript/references/mem-clear-timers.md | 106 +
.../mem-use-weakmap-for-metadata.md | 84 +
.../references/module-avoid-barrel-imports.md | 70 +
.../module-avoid-circular-dependencies.md | 92 +
.../module-control-types-inclusion.md | 92 +
.../references/module-dynamic-imports.md | 78 +
.../references/module-use-type-imports.md | 80 +
.../runtime-avoid-object-spread-in-loops.md | 79 +
.../runtime-cache-property-access.md | 85 +
.../runtime-prefer-array-methods.md | 73 +
.../runtime-use-for-of-for-iteration.md | 89 +
.../references/runtime-use-set-for-lookups.md | 64 +
.../references/runtime-use-string-methods.md | 79 +
.../references/safety-assertion-functions.md | 92 +
.../references/safety-const-assertions.md | 77 +
.../references/safety-exhaustive-checks.md | 83 +
.../safety-prefer-unknown-over-any.md | 76 +
.../references/safety-strict-null-checks.md | 72 +
.../references/safety-use-type-guards.md | 86 +
.../references/tscfg-enable-incremental.md | 68 +
.../references/tscfg-exclude-properly.md | 85 +
.../references/tscfg-isolate-modules.md | 68 +
.../references/tscfg-project-references.md | 97 +
.../references/tscfg-skip-lib-check.md | 63 +
.../references/tscfg-strict-function-types.md | 67 +
.../references/tscfg-typescript-7.md | 75 +
.../references/type-avoid-deep-generics.md | 81 +
.../references/type-avoid-large-unions.md | 57 +
.../references/type-explicit-return-types.md | 65 +
.../type-extract-conditional-types.md | 57 +
.../type-interfaces-over-intersections.md | 41 +
.../references/type-limit-recursion-depth.md | 65 +
.../references/type-simplify-mapped-types.md | 71 +
.agents/skills/ui-design/SKILL.md | 102 +
.../ui-design/references/access-alt-text.md | 63 +
.../references/access-aria-labels.md | 57 +
.../references/access-focus-indicators.md | 53 +
.../references/access-heading-hierarchy.md | 48 +
.../references/access-keyboard-navigation.md | 52 +
.../references/access-semantic-html.md | 53 +
.../references/access-target-size.md | 56 +
.../references/anim-duration-easing.md | 77 +
.../references/anim-gpu-properties.md | 75 +
.../references/anim-reduced-motion.md | 82 +
.../ui-design/references/anim-will-change.md | 78 +
.../references/color-contrast-ratio.md | 67 +
.../ui-design/references/color-dark-mode.md | 74 +
.../references/color-not-only-indicator.md | 79 +
.../references/color-semantic-palette.md | 64 +
.../ui-design/references/cwv-critical-css.md | 55 +
.../ui-design/references/cwv-improve-inp.md | 70 +
.../references/cwv-lazy-load-offscreen.md | 60 +
.../ui-design/references/cwv-minimize-cls.md | 66 +
.../ui-design/references/cwv-optimize-lcp.md | 59 +
.../references/cwv-responsive-images.md | 63 +
.../ui-design/references/form-autocomplete.md | 62 +
.../references/form-error-messages.md | 61 +
.../references/form-inline-validation.md | 67 +
.../ui-design/references/form-input-types.md | 63 +
.../ui-design/references/form-labels-above.md | 74 +
.../ui-design/references/layout-f-pattern.md | 65 +
.../references/layout-grid-system.md | 67 +
.../references/layout-proximity-grouping.md | 57 +
.../ui-design/references/layout-single-cta.md | 64 +
.../references/layout-visual-hierarchy.md | 69 +
.../ui-design/references/layout-whitespace.md | 70 +
.../references/resp-container-queries.md | 64 +
.../references/resp-fluid-typography.md | 65 +
.../ui-design/references/resp-mobile-first.md | 83 +
.../references/resp-touch-targets.md | 67 +
.../references/resp-viewport-meta.md | 57 +
.../ui-design/references/typo-font-display.md | 61 +
.../ui-design/references/typo-line-height.md | 66 +
.../references/typo-preload-fonts.md | 62 +
.../references/typo-readable-line-length.md | 58 +
.../references/typo-system-font-stack.md | 57 +
.../vercel-composition-patterns/SKILL.md | 74 +
.../rules/architecture-avoid-boolean-props.md | 102 +
.../rules/architecture-compound-components.md | 112 +
.../patterns-children-over-render-props.md | 87 +
.../rules/patterns-explicit-variants.md | 100 +
.../rules/react19-no-forwardref.md | 42 +
.../rules/state-context-interface.md | 191 +
.../rules/state-decouple-implementation.md | 113 +
.../rules/state-lift-state.md | 125 +
.../vercel-react-best-practices/SKILL.md | 134 +
.../rules/advanced-effect-event-deps.md | 56 +
.../rules/advanced-event-handler-refs.md | 55 +
.../rules/advanced-init-once.md | 42 +
.../rules/advanced-use-latest.md | 39 +
.../rules/async-api-routes.md | 38 +
.../async-cheap-condition-before-await.md | 37 +
.../rules/async-defer-await.md | 82 +
.../rules/async-dependencies.md | 51 +
.../rules/async-parallel.md | 28 +
.../rules/async-suspense-boundaries.md | 99 +
.../rules/bundle-analyzable-paths.md | 63 +
.../rules/bundle-barrel-imports.md | 60 +
.../rules/bundle-conditional.md | 31 +
.../rules/bundle-defer-third-party.md | 49 +
.../rules/bundle-dynamic-imports.md | 35 +
.../rules/bundle-preload.md | 50 +
.../rules/client-event-listeners.md | 74 +
.../rules/client-localstorage-schema.md | 71 +
.../rules/client-passive-event-listeners.md | 48 +
.../rules/client-swr-dedup.md | 56 +
.../rules/js-batch-dom-css.md | 107 +
.../rules/js-cache-function-results.md | 80 +
.../rules/js-cache-property-access.md | 28 +
.../rules/js-cache-storage.md | 70 +
.../rules/js-combine-iterations.md | 32 +
.../rules/js-early-exit.md | 50 +
.../rules/js-flatmap-filter.md | 60 +
.../rules/js-hoist-regexp.md | 45 +
.../rules/js-index-maps.md | 37 +
.../rules/js-length-check-first.md | 49 +
.../rules/js-min-max-loop.md | 82 +
.../rules/js-request-idle-callback.md | 105 +
.../rules/js-set-map-lookups.md | 24 +
.../rules/js-tosorted-immutable.md | 57 +
.../rules/rendering-activity.md | 26 +
.../rules/rendering-animate-svg-wrapper.md | 47 +
.../rules/rendering-conditional-render.md | 40 +
.../rules/rendering-content-visibility.md | 38 +
.../rules/rendering-hoist-jsx.md | 46 +
.../rules/rendering-hydration-no-flicker.md | 82 +
.../rendering-hydration-suppress-warning.md | 30 +
.../rules/rendering-resource-hints.md | 85 +
.../rules/rendering-script-defer-async.md | 68 +
.../rules/rendering-svg-precision.md | 28 +
.../rules/rendering-usetransition-loading.md | 79 +
.../rules/rerender-defer-reads.md | 39 +
.../rules/rerender-dependencies.md | 45 +
.../rules/rerender-derived-state-no-effect.md | 40 +
.../rules/rerender-derived-state.md | 29 +
.../rules/rerender-functional-setstate.md | 74 +
.../rules/rerender-lazy-state-init.md | 58 +
.../rules/rerender-memo-with-default-value.md | 38 +
.../rules/rerender-memo.md | 44 +
.../rules/rerender-move-effect-to-event.md | 45 +
.../rules/rerender-no-inline-components.md | 82 +
.../rerender-simple-expression-in-memo.md | 35 +
.../rules/rerender-split-combined-hooks.md | 64 +
.../rules/rerender-transitions.md | 40 +
.../rules/rerender-use-deferred-value.md | 59 +
.../rerender-use-ref-transient-values.md | 73 +
.../rules/server-after-nonblocking.md | 73 +
.../rules/server-auth-actions.md | 96 +
.../rules/server-cache-lru.md | 41 +
.../rules/server-cache-react.md | 76 +
.../rules/server-dedup-props.md | 65 +
.../rules/server-hoist-static-io.md | 149 +
.../rules/server-no-shared-module-state.md | 50 +
.../rules/server-parallel-fetching.md | 83 +
.../rules/server-parallel-nested-fetching.md | 34 +
.../rules/server-serialization.md | 38 +
.agents/skills/vitest/SKILL.md | 122 +
.../vitest/references/assert-edge-cases.md | 83 +
.../references/assert-expect-assertions.md | 95 +
.../assert-one-assertion-concept.md | 94 +
.../references/assert-specific-matchers.md | 83 +
.../references/assert-toequal-vs-tobe.md | 91 +
.../vitest/references/async-act-wrapper.md | 79 +
.../references/async-await-assertions.md | 45 +
.../references/async-concurrent-expect.md | 60 +
.../vitest/references/async-error-handling.md | 72 +
.../vitest/references/async-fake-timers.md | 82 +
.../references/async-return-promises.md | 60 +
.../references/async-waitfor-polling.md | 84 +
.../references/env-browser-api-mocking.md | 96 +
.../vitest/references/env-globals-config.md | 85 +
.../references/env-per-file-override.md | 115 +
.../vitest/references/env-setup-files.md | 94 +
.../references/mock-avoid-overmocking.md | 98 +
.../references/mock-clear-between-tests.md | 86 +
.../mock-implementation-not-value.md | 81 +
.../vitest/references/mock-msw-network.md | 96 +
.../vitest/references/mock-spyon-vs-mock.md | 85 +
.../vitest/references/mock-type-safety.md | 97 +
.../references/mock-vi-mock-hoisting.md | 95 +
.../vitest/references/org-describe-nesting.md | 85 +
.../vitest/references/org-file-colocation.md | 93 +
.../vitest/references/org-test-naming.md | 86 +
.../vitest/references/org-test-skip-only.md | 75 +
.../vitest/references/perf-bail-fast-fail.md | 84 +
.../references/perf-bench-test-context.md | 59 +
.../references/perf-disable-isolation.md | 91 +
.../vitest/references/perf-happy-dom.md | 103 +
.../vitest/references/perf-pool-selection.md | 78 +
.../vitest/references/perf-run-mode-ci.md | 93 +
.../skills/vitest/references/perf-sharding.md | 101 +
.../references/setup-avoid-shared-state.md | 98 +
.../references/setup-beforeall-expensive.md | 81 +
.../references/setup-beforeeach-cleanup.md | 83 +
.../vitest/references/setup-reset-modules.md | 91 +
.../vitest/references/setup-restore-mocks.md | 88 +
.../vitest/references/setup-test-factories.md | 104 +
.../references/setup-vitest5-migration.md | 64 +
.../vitest/references/snap-avoid-large.md | 76 +
.../vitest/references/snap-describe-intent.md | 78 +
.../references/snap-inline-over-file.md | 73 +
.../vitest/references/snap-review-updates.md | 79 +
.../references/snap-stable-serialization.md | 97 +
.agents/skills/web-design-guidelines/SKILL.md | 39 +
.agents/skills/zod/SKILL.md | 128 +
.../zod/references/compose-intersection.md | 147 +
.../zod/references/compose-lazy-recursive.md | 154 +
.agents/skills/zod/references/compose-pipe.md | 113 +
.../zod/references/compose-preprocess.md | 142 +
.../zod/references/compose-shared-schemas.md | 138 +
.../error-avoid-throwing-in-refine.md | 127 +
.../zod/references/error-custom-messages.md | 113 +
.agents/skills/zod/references/error-i18n.md | 141 +
.../zod/references/error-path-for-nested.md | 133 +
.../zod/references/error-use-flatten.md | 85 +
.../references/object-discriminated-unions.md | 138 +
.../object-extend-for-composition.md | 145 +
.../references/object-optional-vs-nullable.md | 117 +
.../references/object-partial-for-updates.md | 142 +
.../skills/zod/references/object-pick-omit.md | 146 +
.../zod/references/object-strict-vs-strip.md | 70 +
.../parse-async-for-async-refinements.md | 118 +
.../parse-avoid-double-validation.md | 129 +
.../zod/references/parse-handle-all-issues.md | 125 +
.../zod/references/parse-never-trust-json.md | 113 +
.../zod/references/parse-use-safeparse.md | 102 +
.../zod/references/parse-validate-early.md | 120 +
.../parse-validate-for-boolean-checks.md | 64 +
.agents/skills/zod/references/perf-arrays.md | 153 +
.../references/perf-avoid-dynamic-creation.md | 97 +
.../zod/references/perf-cache-schemas.md | 138 +
.../zod/references/perf-compile-schemas.md | 76 +
.../zod/references/perf-lazy-loading.md | 135 +
.../skills/zod/references/perf-zod-mini.md | 110 +
.../skills/zod/references/refine-add-path.md | 141 +
.agents/skills/zod/references/refine-catch.md | 143 +
.../skills/zod/references/refine-defaults.md | 131 +
.../zod/references/refine-transform-coerce.md | 105 +
.../skills/zod/references/refine-use-codec.md | 41 +
.../zod/references/refine-vs-superrefine.md | 152 +
.../references/schema-avoid-optional-abuse.md | 93 +
.../schema-coercion-for-form-data.md | 88 +
.../references/schema-string-validations.md | 114 +
.../skills/zod/references/schema-use-enums.md | 115 +
.../schema-use-primitives-correctly.md | 61 +
.../references/schema-use-unknown-not-any.md | 88 +
.../zod/references/type-branded-types.md | 102 +
.../zod/references/type-enable-strict-mode.md | 130 +
.../type-export-schemas-and-types.md | 116 +
.../zod/references/type-input-vs-output.md | 116 +
.../skills/zod/references/type-use-z-infer.md | 110 +
.claude/skills/feature-arch/SKILL.md | 110 +
.../bound-event-based-communication.md | 84 +
.../references/bound-feature-isolation.md | 88 +
.../bound-feature-scoped-routing.md | 76 +
.../references/bound-feature-size.md | 74 +
.../references/bound-interface-contracts.md | 83 +
.../references/bound-minimize-shared-state.md | 73 +
.../references/fcomp-colocate-styles.md | 88 +
.../fcomp-composition-over-props.md | 100 +
.../fcomp-container-presentational.md | 99 +
.../references/fcomp-error-boundaries.md | 99 +
.../fcomp-props-as-data-boundary.md | 88 +
.../references/fcomp-single-responsibility.md | 99 +
.../references/fquery-avoid-n-plus-one.md | 80 +
.../fquery-colocate-with-feature.md | 70 +
.../references/fquery-feature-scoped-keys.md | 72 +
.../references/fquery-parallel-fetching.md | 71 +
.../fquery-server-component-fetching.md | 88 +
.../fquery-single-responsibility.md | 66 +
.../references/fstate-context-sparingly.md | 73 +
.../fstate-feature-scoped-stores.md | 79 +
.../references/fstate-lift-minimally.md | 85 +
.../references/fstate-reset-on-unmount.md | 89 +
.../fstate-server-state-separation.md | 93 +
.../references/import-avoid-barrel-files.md | 63 +
.../references/import-no-cross-feature.md | 84 +
.../references/import-path-aliases.md | 64 +
.../references/import-public-api.md | 67 +
.../references/import-type-only.md | 81 +
.../references/import-unidirectional-flow.md | 82 +
.../references/name-descriptive-exports.md | 65 +
.../references/name-feature-naming.md | 60 +
.../references/name-file-conventions.md | 79 +
.../references/struct-app-layer.md | 73 +
.../references/struct-feature-folders.md | 70 +
.../struct-feature-self-contained.md | 62 +
.../references/struct-flat-hierarchy.md | 58 +
.../references/struct-optional-segments.md | 72 +
.../references/struct-shared-layer.md | 68 +
.../references/test-colocate-with-feature.md | 78 +
.../references/test-feature-isolation.md | 88 +
.../test-integration-at-app-layer.md | 87 +
.../references/test-shared-utilities.md | 94 +
.claude/skills/msw/SKILL.md | 121 +
.../references/advanced-bypass-requests.md | 81 +
.../msw/references/advanced-cookies-auth.md | 119 +
.../references/advanced-dynamic-scenarios.md | 114 +
.../msw/references/advanced-file-uploads.md | 109 +
.../advanced-playwright-integration.md | 78 +
.../msw/references/advanced-vitest-browser.md | 100 +
.../references/advanced-websocket-mocking.md | 87 +
.../msw/references/debug-common-issues.md | 79 +
.../msw/references/debug-lifecycle-events.md | 88 +
.../msw/references/debug-request-logging.md | 113 +
.../references/debug-verify-interception.md | 95 +
.../msw/references/graphql-batched-queries.md | 93 +
.../msw/references/graphql-error-responses.md | 119 +
.../references/graphql-operation-handlers.md | 101 +
.../msw/references/graphql-schema-first.md | 76 +
.../references/graphql-variables-access.md | 123 +
.../msw/references/handler-absolute-urls.md | 70 +
.../msw/references/handler-domain-grouping.md | 81 +
.../references/handler-happy-path-first.md | 60 +
.../handler-request-body-parsing.md | 76 +
.../references/handler-resolver-argument.md | 86 +
.../handler-reusability-environments.md | 80 +
.../references/handler-shared-resolvers.md | 99 +
.../references/handler-v2-response-syntax.md | 94 +
.../msw/references/match-custom-predicate.md | 99 +
.../msw/references/match-handler-order.md | 93 +
.../msw/references/match-http-methods.md | 98 +
.../msw/references/match-query-params.md | 89 +
.../msw/references/match-url-patterns.md | 87 +
.../msw/references/response-custom-headers.md | 125 +
.../references/response-delay-realistic.md | 92 +
.../references/response-error-simulation.md | 110 +
.../response-http-response-helpers.md | 83 +
.../references/response-one-time-handlers.md | 103 +
.../msw/references/response-streaming.md | 114 +
.../msw/references/setup-lifecycle-hooks.md | 57 +
.../msw/references/setup-node-version.md | 72 +
.../setup-server-node-entrypoint.md | 45 +
.../msw/references/setup-typescript-config.md | 74 +
.../references/setup-unhandled-requests.md | 70 +
.../references/setup-worker-script-commit.md | 65 +
.../msw/references/test-async-utilities.md | 81 +
.../test-avoid-request-assertions.md | 87 +
.../references/test-clear-request-cache.md | 85 +
.../references/test-concurrent-boundary.md | 88 +
.../msw/references/test-fake-timers-config.md | 91 +
.../msw/references/test-jsdom-environment.md | 67 +
.../msw/references/test-reset-handlers.md | 63 +
.claude/skills/nextjs/SKILL.md | 115 +
.../references/action-error-handling.md | 75 +
.../references/action-optimistic-updates.md | 74 +
.../references/action-pending-states.md | 68 +
.../nextjs/references/action-revalidation.md | 78 +
.../references/action-server-action-forms.md | 75 +
.../nextjs/references/build-barrel-files.md | 50 +
.../references/build-dynamic-imports.md | 62 +
.../references/build-external-packages.md | 48 +
.../build-optimize-package-imports.md | 42 +
.../references/build-turbopack-config.md | 71 +
.../nextjs/references/cache-fetch-options.md | 53 +
.../nextjs/references/cache-react-cache.md | 58 +
.../references/cache-revalidate-path.md | 62 +
.../nextjs/references/cache-revalidate-tag.md | 65 +
.../nextjs/references/cache-segment-config.md | 63 +
.../references/cache-use-cache-directive.md | 57 +
.../references/client-children-pattern.md | 75 +
.../references/client-hydration-mismatch.md | 101 +
.../references/client-third-party-scripts.md | 67 +
.../references/client-use-client-boundary.md | 72 +
.../references/meta-generate-metadata.md | 70 +
.../references/meta-opengraph-images.md | 72 +
.../skills/nextjs/references/meta-robots.md | 68 +
.../skills/nextjs/references/meta-sitemap.md | 76 +
.../references/route-instant-navigations.md | 97 +
.../references/route-intercepting-routes.md | 76 +
.../nextjs/references/route-not-found.md | 59 +
.../references/route-parallel-routes.md | 79 +
.../references/route-partial-prefetching.md | 87 +
.../nextjs/references/route-prefetching.md | 71 +
.../nextjs/references/route-proxy-ts.md | 62 +
.../server-avoid-client-fetching.md | 71 +
.../references/server-component-streaming.md | 70 +
.../references/server-data-colocation.md | 63 +
.../references/server-error-handling.md | 79 +
.../references/server-parallel-fetching.md | 69 +
.../references/server-preload-pattern.md | 68 +
.../nextjs/references/stream-error-tsx.md | 67 +
.../nextjs/references/stream-loading-tsx.md | 63 +
.../references/stream-nested-suspense.md | 82 +
.../references/stream-skeleton-matching.md | 72 +
.../references/stream-suspense-boundaries.md | 62 +
.claude/skills/nuqs/SKILL.md | 110 +
.../references/advanced-custom-parsers.md | 70 +
.../nuqs/references/advanced-eq-function.md | 94 +
.../references/advanced-framework-adapters.md | 82 +
.../nuqs/references/advanced-url-keys.md | 62 +
.../nuqs/references/debug-common-errors.md | 53 +
.../nuqs/references/debug-enable-logging.md | 51 +
.../skills/nuqs/references/debug-testing.md | 55 +
.../nuqs/references/history-back-sync.md | 51 +
.../references/history-push-navigation.md | 76 +
.../references/history-replace-ephemeral.md | 87 +
.../references/history-scroll-behavior.md | 60 +
.../nuqs/references/parser-array-format.md | 59 +
.../nuqs/references/parser-date-format.md | 67 +
.../nuqs/references/parser-enum-validation.md | 81 +
.../nuqs/references/parser-hex-colors.md | 68 +
.../nuqs/references/parser-index-offset.md | 72 +
.../nuqs/references/parser-json-validation.md | 97 +
.../references/parser-use-typed-parsers.md | 58 +
.../nuqs/references/parser-with-default.md | 65 +
.../nuqs/references/perf-avoid-rerender.md | 88 +
.../nuqs/references/perf-clear-on-default.md | 55 +
.../nuqs/references/perf-debounce-search.md | 82 +
.../nuqs/references/perf-serialize-utility.md | 81 +
.../nuqs/references/perf-throttle-updates.md | 66 +
.../nuqs/references/server-next15-async.md | 80 +
.../references/server-parse-before-get.md | 82 +
.../references/server-search-params-cache.md | 78 +
.../nuqs/references/server-shallow-false.md | 74 +
.../nuqs/references/server-share-parsers.md | 74 +
.../nuqs/references/server-use-transition.md | 96 +
.../nuqs/references/setup-import-server.md | 72 +
.../nuqs/references/setup-nextjs-version.md | 64 +
.../nuqs/references/setup-nuqs-adapter.md | 77 +
.../nuqs/references/setup-shared-parsers.md | 73 +
.../nuqs/references/setup-use-client.md | 69 +
.../nuqs/references/state-avoid-derived.md | 84 +
.../nuqs/references/state-clear-with-null.md | 81 +
.../references/state-controlled-inputs.md | 83 +
.../references/state-functional-updates.md | 68 +
.../references/state-options-inheritance.md | 78 +
.../nuqs/references/state-setter-return.md | 78 +
.../nuqs/references/state-use-query-states.md | 75 +
.claude/skills/playwright/SKILL.md | 114 +
.../references/arch-cleanup-state.md | 83 +
.../playwright/references/arch-fixtures.md | 89 +
.../references/arch-page-object-model.md | 80 +
.../references/arch-parallel-execution.md | 75 +
.../references/arch-test-isolation.md | 61 +
.../references/arch-test-production.md | 74 +
.../references/assert-aria-snapshots.md | 58 +
.../playwright/references/auth-api-login.md | 99 +
.../references/auth-multiple-roles.md | 111 +
.../references/auth-parallel-workers.md | 101 +
.../references/auth-session-storage.md | 106 +
.../references/auth-storage-state.md | 97 +
.../references/debug-ci-reporters.md | 81 +
.../playwright/references/debug-inspector.md | 86 +
.../references/debug-screenshots-videos.md | 85 +
.../references/debug-trace-viewer.md | 79 +
.../playwright/references/loc-avoid-xpath.md | 64 +
.../references/loc-chained-locators.md | 87 +
.../playwright/references/loc-data-testid.md | 80 +
.../references/loc-frame-locator.md | 45 +
.../references/loc-label-selectors.md | 78 +
.../references/loc-placeholder-selector.md | 87 +
.../references/loc-role-selectors.md | 74 +
.../references/loc-text-selectors.md | 77 +
.../references/mock-abort-requests.md | 107 +
.../references/mock-api-responses.md | 91 +
.../playwright/references/mock-har-files.md | 100 +
.../references/mock-intercept-modify.md | 101 +
.../references/mock-network-conditions.md | 98 +
.../references/next-app-router-navigation.md | 87 +
.../references/next-baseurl-config.md | 108 +
.../references/next-server-actions.md | 90 +
.../references/next-server-components.md | 92 +
.../references/next-wait-hydration.md | 103 +
.../references/perf-browser-selection.md | 99 +
.../playwright/references/perf-headless-ci.md | 100 +
.../playwright/references/perf-retries.md | 100 +
.../references/perf-reuse-server.md | 87 +
.../playwright/references/perf-sharding.md | 105 +
.../references/wait-action-retries.md | 83 +
.../references/wait-avoid-hard-waits.md | 90 +
.../references/wait-custom-timeout.md | 98 +
.../references/wait-network-idle.md | 65 +
.../references/wait-soft-assertions.md | 78 +
.../references/wait-web-first-assertions.md | 91 +
.claude/skills/react-hook-form/SKILL.md | 119 +
.../references/adv-devtools-performance.md | 69 +
.../references/adv-formprovider-memo.md | 78 +
.../references/adv-opaque-types.md | 52 +
.../references/adv-testing-wrapper.md | 63 +
.../array-complete-default-objects.md | 66 +
.../array-separate-crud-operations.md | 76 +
.../array-unique-fieldarray-per-name.md | 58 +
.../references/array-use-field-id-as-key.md | 54 +
.../array-virtualization-formprovider.md | 64 +
.../ctrl-avoid-double-registration.md | 46 +
.../references/ctrl-controller-field-props.md | 56 +
.../ctrl-local-state-combination.md | 69 +
...ctrl-single-usecontroller-per-component.md | 66 +
.../ctrl-usecontroller-isolation.md | 64 +
.../formcfg-async-default-values.md | 69 +
.../references/formcfg-default-values.md | 57 +
.../references/formcfg-revalidate-mode.md | 52 +
.../references/formcfg-should-unregister.md | 64 +
.../formcfg-useeffect-dependency.md | 54 +
.../references/formcfg-validation-mode.md | 55 +
.../formstate-avoid-isvalid-with-onsubmit.md | 57 +
.../formstate-destructure-formstate.md | 48 +
...ormstate-getfieldstate-for-single-field.md | 54 +
.../formstate-subscribe-to-specific-fields.md | 54 +
.../formstate-useformstate-isolation.md | 65 +
.../integ-mui-controller-pattern.md | 59 +
.../references/integ-shadcn-form-import.md | 64 +
.../references/integ-shadcn-select-wiring.md | 64 +
.../integ-typed-submit-server-action.md | 52 +
.../references/integ-value-transform.md | 59 +
.../references/sub-avoid-watch-in-render.md | 48 +
.../references/sub-deep-subscription.md | 62 +
.../sub-useformcontext-sparingly.md | 58 +
.../references/sub-usewatch-default-value.md | 50 +
.../references/sub-usewatch-over-watch.md | 58 +
.../references/sub-usewatch-with-getvalues.md | 54 +
.../references/sub-watch-specific-fields.md | 54 +
.../references/valid-delay-error.md | 52 +
.../valid-dynamic-schema-factory.md | 57 +
.../valid-error-message-strategy.md | 82 +
.../references/valid-form-level-validate.md | 47 +
.../references/valid-inline-vs-resolver.md | 63 +
.../references/valid-native-validation.md | 60 +
.../references/valid-resolver-caching.md | 58 +
.../references/valid-trigger-should-touch.md | 44 +
.claude/skills/react/SKILL.md | 87 +
.claude/skills/react/references/_sections.md | 46 +
.../references/conc-automatic-batching.md | 64 +
.../react/references/conc-concurrent-safe.md | 71 +
.../references/conc-suspense-fallback.md | 66 +
.../references/conc-use-deferred-value.md | 65 +
.../react/references/conc-use-transition.md | 75 +
.../react/references/conc-view-transitions.md | 81 +
.../references/data-cache-deduplication.md | 60 +
.../react/references/data-error-boundaries.md | 76 +
.../references/data-parallel-fetching.md | 74 +
.../references/data-suspense-data-fetching.md | 76 +
.../skills/react/references/data-use-hook.md | 77 +
.../references/effect-avoid-unnecessary.md | 69 +
.../skills/react/references/effect-cleanup.md | 75 +
.../references/effect-object-dependencies.md | 56 +
.../references/effect-use-browser-only.md | 62 +
.../references/effect-use-effect-event.md | 53 +
.../effect-use-sync-external-store.md | 80 +
.../skills/react/references/form-actions.md | 83 +
.../react/references/form-use-action-state.md | 80 +
.../react/references/form-use-form-status.md | 68 +
.../react/references/form-use-optimistic.md | 77 +
.../react/references/form-validation.md | 89 +
.../react/references/memo-avoid-premature.md | 68 +
.../skills/react/references/memo-compiler.md | 84 +
.../react/references/memo-react-memo.md | 72 +
.../react/references/memo-use-callback.md | 70 +
.../skills/react/references/memo-use-memo.md | 53 +
.../react/references/rcomp-composition.md | 75 +
.../references/rcomp-controlled-components.md | 63 +
.../react/references/rcomp-fragment-refs.md | 71 +
.../react/references/rcomp-key-reset.md | 74 +
.../react/references/rcomp-render-props.md | 69 +
.../references/rsc-avoid-client-only-libs.md | 66 +
.../references/rsc-composition-pattern.md | 90 +
.../react/references/rsc-context-provider.md | 50 +
.../references/rsc-data-fetching-server.md | 68 +
.../references/rsc-serializable-props.md | 70 +
.../references/rsc-server-client-boundary.md | 63 +
.../skills/react/references/rsc-streaming.md | 64 +
.../references/rstate-context-optimization.md | 68 +
.../react/references/rstate-derived-values.md | 70 +
.../references/rstate-functional-updates.md | 58 +
.../references/rstate-lazy-initialization.md | 59 +
.../react/references/rstate-use-reducer.md | 77 +
.claude/skills/shadcn/SKILL.md | 110 +
.../references/ally-ensure-color-contrast.md | 62 +
.../ally-maintain-focus-management.md | 84 +
.../ally-preserve-aria-attributes.md | 77 +
.../ally-preserve-keyboard-navigation.md | 72 +
.../references/ally-provide-sr-only-labels.md | 75 +
.../references/arch-current-cli-registry.md | 61 +
.../arch-extend-variants-with-cva.md | 67 +
...-forward-refs-for-composable-components.md | 83 +
.../arch-isolate-component-variants.md | 82 +
...arch-preserve-radix-primitive-structure.md | 57 +
.../references/arch-unified-radix-package.md | 44 +
.../arch-use-asChild-for-custom-triggers.md | 49 +
.../arch-use-cn-for-class-merging.md | 62 +
.../comp-combine-command-with-popover.md | 106 +
.../comp-compose-with-compound-components.md | 104 +
.../comp-create-reusable-form-fields.md | 157 +
.../references/comp-nest-dialogs-correctly.md | 108 +
.../comp-use-drawer-for-mobile-modals.md | 128 +
.../comp-use-slot-pattern-for-flexibility.md | 118 +
.../data-empty-states-with-guidance.md | 95 +
.../references/data-paginate-server-side.md | 108 +
.../data-use-skeleton-loading-states.md | 104 +
...a-use-tanstack-table-for-complex-tables.md | 121 +
.../references/data-virtualize-large-lists.md | 82 +
.../form-handle-async-validation.md | 104 +
.../form-reset-form-state-correctly.md | 92 +
.../form-show-validation-errors-correctly.md | 58 +
.../form-use-react-hook-form-integration.md | 106 +
.../form-use-zod-for-schema-validation.md | 86 +
...rf-avoid-unnecessary-rerenders-in-forms.md | 88 +
.../references/perf-debounce-search-inputs.md | 85 +
.../perf-lazy-load-heavy-components.md | 90 +
.../perf-memoize-expensive-renders.md | 90 +
.../references/perf-optimize-icon-imports.md | 60 +
.../state-colocate-state-with-components.md | 103 +
.../state-lift-state-to-appropriate-level.md | 103 +
...e-prefer-uncontrolled-for-simple-inputs.md | 91 +
.../state-use-controlled-dialog-state.md | 127 +
.../style-avoid-important-overrides.md | 58 +
.../style-consistent-spacing-scale.md | 67 +
.../references/style-dark-mode-support.md | 83 +
.../style-responsive-design-patterns.md | 75 +
.../style-use-css-variables-for-theming.md | 56 +
.../style-use-tailwind-theme-extend.md | 63 +
.claude/skills/tailwind/SKILL.md | 109 +
.../tailwind/references/anim-3d-transforms.md | 56 +
.../references/anim-gpu-accelerated.md | 47 +
.../references/anim-gradient-interpolation.md | 46 +
.../references/anim-starting-style.md | 63 +
.../tailwind/references/build-cli-package.md | 43 +
.../references/build-content-detection.md | 44 +
.../tailwind/references/build-css-import.md | 36 +
.../tailwind/references/build-node-version.md | 44 +
.../references/build-postcss-simplify.md | 40 +
.../tailwind/references/build-vite-plugin.md | 39 +
.../references/bundle-avoid-cdn-production.md | 56 +
.../references/bundle-avoid-preprocessors.md | 53 +
.../references/bundle-css-minification.md | 57 +
.../bundle-remove-unused-plugins.md | 55 +
.../references/bundle-split-critical-css.md | 62 +
.../references/comp-avoid-apply-overuse.md | 58 +
.../references/comp-container-customize.md | 59 +
.../references/comp-reference-directive.md | 59 +
.../tailwind/references/comp-smart-sorting.md | 50 +
.../references/comp-utility-file-scope.md | 61 +
.../references/gen-avoid-theme-bloat.md | 47 +
.../references/gen-css-first-config.md | 54 +
.../references/gen-css-variable-syntax.md | 43 +
.../references/gen-dynamic-utilities.md | 51 +
.../tailwind/references/gen-oklch-colors.md | 40 +
.../references/gen-utility-directive.md | 52 +
.../references/resp-container-queries.md | 55 +
.../references/resp-custom-breakpoints.md | 54 +
.../references/resp-hover-capability.md | 60 +
.../references/resp-logical-properties.md | 51 +
.../tailwind/references/resp-mobile-first.md | 48 +
.../tailwind/references/theme-color-scheme.md | 55 +
.../references/theme-dark-mode-class.md | 59 +
.../references/theme-prefix-variables.md | 56 +
.../references/theme-runtime-variables.md | 55 +
.../references/theme-semantic-tokens.md | 65 +
.../references/util-explicit-colors.md | 43 +
.../references/util-gradient-via-none.md | 37 +
.../references/util-important-modifier.md | 43 +
.../references/util-opacity-modifier.md | 50 +
.../references/util-renamed-utilities.md | 45 +
.../references/util-variant-stacking.md | 41 +
.claude/skills/tanstack-query/SKILL.md | 117 +
.../references/cache-enabled-option.md | 76 +
.../references/cache-global-defaults.md | 73 +
.../cache-invalidation-precision.md | 78 +
.../cache-placeholder-vs-initial.md | 69 +
.../references/cache-refetch-triggers.md | 68 +
.../references/cache-staletime-gctime.md | 71 +
.../references/error-conditional-retry.md | 93 +
.../references/error-display-patterns.md | 100 +
.../references/error-global-handler.md | 91 +
.../references/error-retry-config.md | 80 +
.../references/error-throw-on-error.md | 96 +
.../references/infinite-flatten-pages.md | 108 +
.../references/infinite-loading-states.md | 96 +
.../references/infinite-max-pages.md | 86 +
.../references/infinite-refetch-behavior.md | 79 +
.../references/mutation-avoid-parallel.md | 92 +
.../references/mutation-cancel-queries.md | 72 +
.../mutation-invalidate-onsettled.md | 66 +
.../references/mutation-optimistic-updates.md | 81 +
.../references/mutation-setquerydata.md | 67 +
.../references/prefetch-avoid-waterfalls.md | 98 +
.../references/prefetch-flatten-api.md | 70 +
.../references/prefetch-in-queryfn.md | 97 +
.../references/prefetch-infinite-query.md | 60 +
.../references/prefetch-on-hover.md | 94 +
.../references/prefetch-server-components.md | 88 +
.../references/render-notify-props.md | 66 +
.../references/render-select-derived.md | 86 +
.../references/render-select-memoize.md | 75 +
.../references/render-structural-sharing.md | 88 +
.../references/render-tracked-props.md | 80 +
.../suspense-boundaries-placement.md | 97 +
.../references/suspense-error-boundaries.md | 100 +
.../references/suspense-parallel-queries.md | 93 +
.../references/suspense-use-suspense-hooks.md | 66 +
.../references/tquery-always-arrays.md | 49 +
.../references/tquery-colocate-keys.md | 66 +
.../references/tquery-hierarchical-keys.md | 61 +
.../references/tquery-key-factories.md | 58 +
.../references/tquery-options-pattern.md | 78 +
.../references/tquery-serializable-objects.md | 60 +
.claude/skills/tdd/SKILL.md | 114 +
.../tdd/references/assert-custom-matchers.md | 86 +
.../tdd/references/assert-error-messages.md | 64 +
.../assert-no-assertions-antipattern.md | 70 +
.../tdd/references/assert-snapshot-testing.md | 71 +
.../references/assert-specific-assertions.md | 71 +
.../references/cycle-maintain-test-list.md | 68 +
.../references/cycle-minimal-code-to-pass.md | 62 +
.../references/cycle-refactor-after-green.md | 58 +
.../tdd/references/cycle-small-increments.md | 69 +
.../cycle-verify-test-fails-first.md | 64 +
.../tdd/references/cycle-write-test-first.md | 63 +
.../references/data-avoid-mystery-guests.md | 62 +
.../tdd/references/data-builder-pattern.md | 99 +
.../tdd/references/data-minimal-setup.md | 69 +
.../tdd/references/data-unique-identifiers.md | 79 +
.../tdd/references/data-use-factories.md | 87 +
.../tdd/references/design-aaa-pattern.md | 68 +
.../references/design-avoid-logic-in-tests.md | 74 +
.../design-descriptive-test-names.md | 64 +
.../design-one-assertion-per-test.md | 66 +
...design-test-behavior-not-implementation.md | 69 +
.../tdd/references/design-test-edge-cases.md | 83 +
.../references/isolate-deterministic-tests.md | 80 +
.../isolate-mock-external-dependencies.md | 69 +
.../tdd/references/isolate-no-shared-state.md | 73 +
.../isolate-prefer-stubs-over-mocks.md | 72 +
.../isolate-use-dependency-injection.md | 91 +
.../tdd/references/org-file-structure.md | 76 +
.../tdd/references/org-group-by-behavior.md | 68 +
.../tdd/references/org-parameterized-tests.md | 79 +
.../tdd/references/org-setup-teardown.md | 84 +
.../tdd/references/org-test-utilities.md | 98 +
.../references/perf-avoid-network-calls.md | 78 +
.../skills/tdd/references/perf-avoid-sleep.md | 82 +
.../tdd/references/perf-fast-unit-tests.md | 48 +
.../tdd/references/perf-fix-flaky-tests.md | 83 +
.../tdd/references/perf-parallelize-tests.md | 87 +
.../tdd/references/strat-coverage-targets.md | 70 +
.../references/strat-e2e-critical-paths.md | 78 +
.../strat-integration-boundaries.md | 79 +
.../tdd/references/strat-mutation-testing.md | 71 +
.../tdd/references/strat-test-pyramid.md | 58 +
.claude/skills/typescript/SKILL.md | 103 +
.../references/advanced-branded-types.md | 83 +
.../references/advanced-satisfies-operator.md | 94 +
.../advanced-template-literal-types.md | 105 +
.../references/async-avoid-loop-await.md | 78 +
.../async-avoid-unnecessary-async.md | 61 +
.../references/async-defer-await.md | 74 +
.../references/async-explicit-return-types.md | 79 +
.../references/async-parallel-promises.md | 63 +
.../references/mem-avoid-closure-leaks.md | 88 +
.../references/mem-avoid-global-state.md | 97 +
.../references/mem-cleanup-event-listeners.md | 111 +
.../typescript/references/mem-clear-timers.md | 106 +
.../mem-use-weakmap-for-metadata.md | 84 +
.../references/module-avoid-barrel-imports.md | 70 +
.../module-avoid-circular-dependencies.md | 92 +
.../module-control-types-inclusion.md | 92 +
.../references/module-dynamic-imports.md | 78 +
.../references/module-use-type-imports.md | 80 +
.../runtime-avoid-object-spread-in-loops.md | 79 +
.../runtime-cache-property-access.md | 85 +
.../runtime-prefer-array-methods.md | 73 +
.../runtime-use-for-of-for-iteration.md | 89 +
.../references/runtime-use-set-for-lookups.md | 64 +
.../references/runtime-use-string-methods.md | 79 +
.../references/safety-assertion-functions.md | 92 +
.../references/safety-const-assertions.md | 77 +
.../references/safety-exhaustive-checks.md | 83 +
.../safety-prefer-unknown-over-any.md | 76 +
.../references/safety-strict-null-checks.md | 72 +
.../references/safety-use-type-guards.md | 86 +
.../references/tscfg-enable-incremental.md | 68 +
.../references/tscfg-exclude-properly.md | 85 +
.../references/tscfg-isolate-modules.md | 68 +
.../references/tscfg-project-references.md | 97 +
.../references/tscfg-skip-lib-check.md | 63 +
.../references/tscfg-strict-function-types.md | 67 +
.../references/tscfg-typescript-7.md | 75 +
.../references/type-avoid-deep-generics.md | 81 +
.../references/type-avoid-large-unions.md | 57 +
.../references/type-explicit-return-types.md | 65 +
.../type-extract-conditional-types.md | 57 +
.../type-interfaces-over-intersections.md | 41 +
.../references/type-limit-recursion-depth.md | 65 +
.../references/type-simplify-mapped-types.md | 71 +
.claude/skills/ui-design/SKILL.md | 102 +
.../ui-design/references/access-alt-text.md | 63 +
.../references/access-aria-labels.md | 57 +
.../references/access-focus-indicators.md | 53 +
.../references/access-heading-hierarchy.md | 48 +
.../references/access-keyboard-navigation.md | 52 +
.../references/access-semantic-html.md | 53 +
.../references/access-target-size.md | 56 +
.../references/anim-duration-easing.md | 77 +
.../references/anim-gpu-properties.md | 75 +
.../references/anim-reduced-motion.md | 82 +
.../ui-design/references/anim-will-change.md | 78 +
.../references/color-contrast-ratio.md | 67 +
.../ui-design/references/color-dark-mode.md | 74 +
.../references/color-not-only-indicator.md | 79 +
.../references/color-semantic-palette.md | 64 +
.../ui-design/references/cwv-critical-css.md | 55 +
.../ui-design/references/cwv-improve-inp.md | 70 +
.../references/cwv-lazy-load-offscreen.md | 60 +
.../ui-design/references/cwv-minimize-cls.md | 66 +
.../ui-design/references/cwv-optimize-lcp.md | 59 +
.../references/cwv-responsive-images.md | 63 +
.../ui-design/references/form-autocomplete.md | 62 +
.../references/form-error-messages.md | 61 +
.../references/form-inline-validation.md | 67 +
.../ui-design/references/form-input-types.md | 63 +
.../ui-design/references/form-labels-above.md | 74 +
.../ui-design/references/layout-f-pattern.md | 65 +
.../references/layout-grid-system.md | 67 +
.../references/layout-proximity-grouping.md | 57 +
.../ui-design/references/layout-single-cta.md | 64 +
.../references/layout-visual-hierarchy.md | 69 +
.../ui-design/references/layout-whitespace.md | 70 +
.../references/resp-container-queries.md | 64 +
.../references/resp-fluid-typography.md | 65 +
.../ui-design/references/resp-mobile-first.md | 83 +
.../references/resp-touch-targets.md | 67 +
.../references/resp-viewport-meta.md | 57 +
.../ui-design/references/typo-font-display.md | 61 +
.../ui-design/references/typo-line-height.md | 66 +
.../references/typo-preload-fonts.md | 62 +
.../references/typo-readable-line-length.md | 58 +
.../references/typo-system-font-stack.md | 57 +
.../vercel-composition-patterns/SKILL.md | 74 +
.../rules/architecture-avoid-boolean-props.md | 102 +
.../rules/architecture-compound-components.md | 112 +
.../patterns-children-over-render-props.md | 87 +
.../rules/patterns-explicit-variants.md | 100 +
.../rules/react19-no-forwardref.md | 42 +
.../rules/state-context-interface.md | 191 +
.../rules/state-decouple-implementation.md | 113 +
.../rules/state-lift-state.md | 125 +
.../vercel-react-best-practices/SKILL.md | 134 +
.../rules/advanced-effect-event-deps.md | 56 +
.../rules/advanced-event-handler-refs.md | 55 +
.../rules/advanced-init-once.md | 42 +
.../rules/advanced-use-latest.md | 39 +
.../rules/async-api-routes.md | 38 +
.../async-cheap-condition-before-await.md | 37 +
.../rules/async-defer-await.md | 82 +
.../rules/async-dependencies.md | 51 +
.../rules/async-parallel.md | 28 +
.../rules/async-suspense-boundaries.md | 99 +
.../rules/bundle-analyzable-paths.md | 63 +
.../rules/bundle-barrel-imports.md | 60 +
.../rules/bundle-conditional.md | 31 +
.../rules/bundle-defer-third-party.md | 49 +
.../rules/bundle-dynamic-imports.md | 35 +
.../rules/bundle-preload.md | 50 +
.../rules/client-event-listeners.md | 74 +
.../rules/client-localstorage-schema.md | 71 +
.../rules/client-passive-event-listeners.md | 48 +
.../rules/client-swr-dedup.md | 56 +
.../rules/js-batch-dom-css.md | 107 +
.../rules/js-cache-function-results.md | 80 +
.../rules/js-cache-property-access.md | 28 +
.../rules/js-cache-storage.md | 70 +
.../rules/js-combine-iterations.md | 32 +
.../rules/js-early-exit.md | 50 +
.../rules/js-flatmap-filter.md | 60 +
.../rules/js-hoist-regexp.md | 45 +
.../rules/js-index-maps.md | 37 +
.../rules/js-length-check-first.md | 49 +
.../rules/js-min-max-loop.md | 82 +
.../rules/js-request-idle-callback.md | 105 +
.../rules/js-set-map-lookups.md | 24 +
.../rules/js-tosorted-immutable.md | 57 +
.../rules/rendering-activity.md | 26 +
.../rules/rendering-animate-svg-wrapper.md | 47 +
.../rules/rendering-conditional-render.md | 40 +
.../rules/rendering-content-visibility.md | 38 +
.../rules/rendering-hoist-jsx.md | 46 +
.../rules/rendering-hydration-no-flicker.md | 82 +
.../rendering-hydration-suppress-warning.md | 30 +
.../rules/rendering-resource-hints.md | 85 +
.../rules/rendering-script-defer-async.md | 68 +
.../rules/rendering-svg-precision.md | 28 +
.../rules/rendering-usetransition-loading.md | 79 +
.../rules/rerender-defer-reads.md | 39 +
.../rules/rerender-dependencies.md | 45 +
.../rules/rerender-derived-state-no-effect.md | 40 +
.../rules/rerender-derived-state.md | 29 +
.../rules/rerender-functional-setstate.md | 74 +
.../rules/rerender-lazy-state-init.md | 58 +
.../rules/rerender-memo-with-default-value.md | 38 +
.../rules/rerender-memo.md | 44 +
.../rules/rerender-move-effect-to-event.md | 45 +
.../rules/rerender-no-inline-components.md | 82 +
.../rerender-simple-expression-in-memo.md | 35 +
.../rules/rerender-split-combined-hooks.md | 64 +
.../rules/rerender-transitions.md | 40 +
.../rules/rerender-use-deferred-value.md | 59 +
.../rerender-use-ref-transient-values.md | 73 +
.../rules/server-after-nonblocking.md | 73 +
.../rules/server-auth-actions.md | 96 +
.../rules/server-cache-lru.md | 41 +
.../rules/server-cache-react.md | 76 +
.../rules/server-dedup-props.md | 65 +
.../rules/server-hoist-static-io.md | 149 +
.../rules/server-no-shared-module-state.md | 50 +
.../rules/server-parallel-fetching.md | 83 +
.../rules/server-parallel-nested-fetching.md | 34 +
.../rules/server-serialization.md | 38 +
.claude/skills/vitest/SKILL.md | 122 +
.../vitest/references/assert-edge-cases.md | 83 +
.../references/assert-expect-assertions.md | 95 +
.../assert-one-assertion-concept.md | 94 +
.../references/assert-specific-matchers.md | 83 +
.../references/assert-toequal-vs-tobe.md | 91 +
.../vitest/references/async-act-wrapper.md | 79 +
.../references/async-await-assertions.md | 45 +
.../references/async-concurrent-expect.md | 60 +
.../vitest/references/async-error-handling.md | 72 +
.../vitest/references/async-fake-timers.md | 82 +
.../references/async-return-promises.md | 60 +
.../references/async-waitfor-polling.md | 84 +
.../references/env-browser-api-mocking.md | 96 +
.../vitest/references/env-globals-config.md | 85 +
.../references/env-per-file-override.md | 115 +
.../vitest/references/env-setup-files.md | 94 +
.../references/mock-avoid-overmocking.md | 98 +
.../references/mock-clear-between-tests.md | 86 +
.../mock-implementation-not-value.md | 81 +
.../vitest/references/mock-msw-network.md | 96 +
.../vitest/references/mock-spyon-vs-mock.md | 85 +
.../vitest/references/mock-type-safety.md | 97 +
.../references/mock-vi-mock-hoisting.md | 95 +
.../vitest/references/org-describe-nesting.md | 85 +
.../vitest/references/org-file-colocation.md | 93 +
.../vitest/references/org-test-naming.md | 86 +
.../vitest/references/org-test-skip-only.md | 75 +
.../vitest/references/perf-bail-fast-fail.md | 84 +
.../references/perf-bench-test-context.md | 59 +
.../references/perf-disable-isolation.md | 91 +
.../vitest/references/perf-happy-dom.md | 103 +
.../vitest/references/perf-pool-selection.md | 78 +
.../vitest/references/perf-run-mode-ci.md | 93 +
.../skills/vitest/references/perf-sharding.md | 101 +
.../references/setup-avoid-shared-state.md | 98 +
.../references/setup-beforeall-expensive.md | 81 +
.../references/setup-beforeeach-cleanup.md | 83 +
.../vitest/references/setup-reset-modules.md | 91 +
.../vitest/references/setup-restore-mocks.md | 88 +
.../vitest/references/setup-test-factories.md | 104 +
.../references/setup-vitest5-migration.md | 64 +
.../vitest/references/snap-avoid-large.md | 76 +
.../vitest/references/snap-describe-intent.md | 78 +
.../references/snap-inline-over-file.md | 73 +
.../vitest/references/snap-review-updates.md | 79 +
.../references/snap-stable-serialization.md | 97 +
.claude/skills/web-design-guidelines/SKILL.md | 39 +
.claude/skills/zod/SKILL.md | 128 +
.../zod/references/compose-intersection.md | 147 +
.../zod/references/compose-lazy-recursive.md | 154 +
.claude/skills/zod/references/compose-pipe.md | 113 +
.../zod/references/compose-preprocess.md | 142 +
.../zod/references/compose-shared-schemas.md | 138 +
.../error-avoid-throwing-in-refine.md | 127 +
.../zod/references/error-custom-messages.md | 113 +
.claude/skills/zod/references/error-i18n.md | 141 +
.../zod/references/error-path-for-nested.md | 133 +
.../zod/references/error-use-flatten.md | 85 +
.../references/object-discriminated-unions.md | 138 +
.../object-extend-for-composition.md | 145 +
.../references/object-optional-vs-nullable.md | 117 +
.../references/object-partial-for-updates.md | 142 +
.../skills/zod/references/object-pick-omit.md | 146 +
.../zod/references/object-strict-vs-strip.md | 70 +
.../parse-async-for-async-refinements.md | 118 +
.../parse-avoid-double-validation.md | 129 +
.../zod/references/parse-handle-all-issues.md | 125 +
.../zod/references/parse-never-trust-json.md | 113 +
.../zod/references/parse-use-safeparse.md | 102 +
.../zod/references/parse-validate-early.md | 120 +
.../parse-validate-for-boolean-checks.md | 64 +
.claude/skills/zod/references/perf-arrays.md | 153 +
.../references/perf-avoid-dynamic-creation.md | 97 +
.../zod/references/perf-cache-schemas.md | 138 +
.../zod/references/perf-compile-schemas.md | 76 +
.../zod/references/perf-lazy-loading.md | 135 +
.../skills/zod/references/perf-zod-mini.md | 110 +
.../skills/zod/references/refine-add-path.md | 141 +
.claude/skills/zod/references/refine-catch.md | 143 +
.../skills/zod/references/refine-defaults.md | 131 +
.../zod/references/refine-transform-coerce.md | 105 +
.../skills/zod/references/refine-use-codec.md | 41 +
.../zod/references/refine-vs-superrefine.md | 152 +
.../references/schema-avoid-optional-abuse.md | 93 +
.../schema-coercion-for-form-data.md | 88 +
.../references/schema-string-validations.md | 114 +
.../skills/zod/references/schema-use-enums.md | 115 +
.../schema-use-primitives-correctly.md | 61 +
.../references/schema-use-unknown-not-any.md | 88 +
.../zod/references/type-branded-types.md | 102 +
.../zod/references/type-enable-strict-mode.md | 130 +
.../type-export-schemas-and-types.md | 116 +
.../zod/references/type-input-vs-output.md | 116 +
.../skills/zod/references/type-use-z-infer.md | 110 +
.config/dotnet-tools.json | 13 +
.dockerignore | 20 +
.env.example | 26 +
.github/SECURITY.md | 3 +
.github/workflows/dotnet.yml | 46 +-
.gitignore | 19 +-
AGENTS.md | 28 +
Backend/Directory.Build.props | 12 +
Backend/Dockerfile | 21 +
Backend/docker/mysql-init.sh | 9 +
.../Endpoints/AdministrationEndpoints.cs | 11 +-
.../Modules.Administration.Api/Extensions.cs | 4 +-
.../Modules.Administration.Api.csproj | 13 +
.../Operations/AdministrationOperations.cs | 9 +-
.../Extensions.cs | 4 +-
.../Modules.Administration.Application.csproj | 15 +
.../Services/AdminModuleApi.cs | 4 +-
.../Services/AdminService.cs | 113 +
.../Interfaces/IAdminModuleApi.cs | 4 +-
.../Modules.Administration.Shared.csproj | 9 +
.../Endpoints/AuthEndpoints.cs | 35 +-
.../AuthModule/Modules.Auth.Api/Extensions.cs | 4 +-
.../Modules.Auth.Api/Modules.Auth.Api.csproj | 15 +
.../Operations/AuthOperations.cs | 36 +-
.../Modules.Auth.Application/Extensions.cs | 6 +-
.../Interfaces/IAuthService.cs | 8 +-
.../Modules.Auth.Application.csproj | 14 +
.../Services/AuthService.cs | 168 +-
.../Modules.Auth.Core/Entities/AppUser.cs | 4 +-
.../Entities/AuthSettings.cs | 2 +-
.../Modules.Auth.Core/Entities/TokenModel.cs | 2 +-
.../Modules.Auth.Core.csproj | 10 +
.../DbContexts/AppIdentityDbContext.cs | 4 +-
.../DbContexts/AppIdentityDbContextFactory.cs | 4 +-
.../20250825091711_Initial.Designer.cs | 0
.../Migrations/20250825091711_Initial.cs | 0
...50902202604_AddIsBlockedColumn.Designer.cs | 0
.../20250902202604_AddIsBlockedColumn.cs | 0
...021180313_UpgradeNet10Identity.Designer.cs | 307 ++
.../20261021180313_UpgradeNet10Identity.cs | 22 +
.../AppIdentityDbContextModelSnapshot.cs | 2 +-
.../Modules.Auth.Infrastructure/Extensions.cs | 6 +-
.../Modules.Auth.Infrastructure.csproj | 31 +
.../ActionsRequests/ChangeEmailRequest.cs | 15 +
.../ActionsRequests/ChangePasswordRequest.cs | 15 +
.../ActionsRequests/EditUserRequest.cs | 8 +-
.../ActionsRequests/LoginRequest.cs | 6 +-
.../ActionsRequests/RegisterRequest.cs | 2 +-
.../Modules.Auth.Shared/Dtos/UserDto.cs | 2 +-
.../Entities/CurrentUser.cs | 2 +-
.../Modules.Auth.Shared.csproj | 10 +
.../Static/Entities/AppRoles.cs | 2 +-
.../Backups/BackupQueueEndpoints.cs | 29 +
.../Modules.Backup.Api/Backups/BackupsEo.cs | 38 +-
.../Modules.Backup.Api/Extensions.cs | 5 +-
.../Modules.Backup.Api.csproj | 11 +
.../Schedules/SchedulesEo.cs | 7 +-
.../Security/ResourceAccessFilter.cs | 50 +
.../Modules.Backup.Api/Servers/ServersEo.cs | 24 +-
.../Modules.Backup.Api/Statistics/StatsEO.cs | 7 +-
.../Modules.Backup.Application/Extensions.cs | 11 +-
.../Interfaces/IBackupExecutor.cs | 10 +
.../Interfaces/IDbBackupService.cs | 4 +-
.../Interfaces/IEmailProviderService.cs | 4 +-
.../Modules.Backup.Application.csproj | 22 +
.../Services/BackupExecutor.cs | 66 +
.../Services/BackupQueueCoordinator.cs | 10 +
.../Services/BackupQueueProcessor.cs | 179 +
.../Services/BackupQueueService.cs | 210 +
.../Services/BackupTarget.cs | 22 +
.../Services/DbBackupService.cs | 156 +
.../Services/EmailProviderService.cs | 4 +-
.../Services/NotifyService.cs | 34 +
.../Services/SchedulesService.cs | 14 +-
.../Services/ServersService.cs | 108 +-
.../Services/StatisticsService.cs | 28 +-
.../Static/ServerConnectionTester.cs | 25 +-
.../Workers/BackupWorker.cs | 50 +
.../Entities/Databases/DatabaseBase.cs | 23 +-
.../Entities/Databases/MySqlDatabase.cs | 17 +
.../Entities/Databases/PostgreSqlDatabase.cs | 15 +
.../Entities/Databases/SqlServerDatabase.cs | 23 +
.../DbContext/AutomaticBackupTestConfig.cs | 4 +-
.../Entities/DbContext/BackupRequest.cs | 30 +
.../Entities/DbContext/BackupSchedule.cs | 4 +-
.../Entities/DbContext/BackupTest.cs | 4 +-
.../Entities/DbContext/DbServerConnection.cs | 4 +-
.../Entities/DbContext/DbServerTunnel.cs | 4 +-
.../Entities/DbContext/PerformedBackup.cs | 4 +-
.../DbContext/ServerBackupsConfiguration.cs | 14 +-
.../Entities/DbContext/ServersUsers.cs | 4 +-
.../DbContext/UserNotificationsSettings.cs | 4 +-
.../Models/AppEmailConfigurationModel.cs | 4 +-
.../Models/ApplicationConfigurationModel.cs | 2 +-
.../Entities/Models/BackupDayTime.cs | 4 +-
.../Entities/Models/EWeekDay.cs | 4 +-
.../Models/EmailProviderConfigurationModel.cs | 4 +-
.../Entities/Models/MailModel.cs | 3 +
.../EmptyListOfConfigurationsException.cs | 2 +-
.../Interfaces/IDatabase.cs | 4 +-
.../Modules.Backup.Core.csproj | 25 +
.../StaticClasses/CompressBackupFile.cs | 4 +-
.../StaticClasses/DeleteOldBackup.cs | 2 +-
.../StaticClasses/DumpFailureException.cs | 43 +
.../StaticClasses/DumpProcess.cs | 80 +
.../StaticClasses/MySqlDumpClient.cs | 67 +
.../StaticClasses/PrepareEmailMessageBody.cs | 4 +-
.../StaticClasses/SafeBackupPath.cs | 29 +
.../StaticClasses/SshHostKeys.cs | 22 +
.../StaticClasses/SshTunnelHelper.cs | 14 +-
.../Configuration/LoggerPrepareSetup.cs | 2 +-
.../PrepareApplicationSettings.cs | 2 +-
.../DbContexts/BackupsDbContext.cs | 17 +-
.../20250903215501_Initial.Designer.cs | 0
.../Migrations/20250903215501_Initial.cs | 0
...0904111233_AddPKToServersUsers.Designer.cs | 0
.../20250904111233_AddPKToServersUsers.cs | 0
...09144138_UpdateSchedulesEntity.Designer.cs | 0
.../20250909144138_UpdateSchedulesEntity.cs | 0
...AddPEMPassphraseToTunnelEntity.Designer.cs | 0
...10104700_AddPEMPassphraseToTunnelEntity.cs | 0
...911091310_UpdateBackupsColumns.Designer.cs | 0
.../20250911091310_UpdateBackupsColumns.cs | 0
...50911125405_UpdateBackupEntity.Designer.cs | 0
.../20250911125405_UpdateBackupEntity.cs | 0
...2706_ModifyNullsInBackupEntity.Designer.cs | 0
...0250911172706_ModifyNullsInBackupEntity.cs | 0
.../20251025203420_AddSslToEntity.Designer.cs | 0
.../20251025203420_AddSslToEntity.cs | 0
...6120032_AddSoftDeleteToBackups.Designer.cs | 0
.../20251026120032_AddSoftDeleteToBackups.cs | 0
...03734_AddPersistentBackupQueue.Designer.cs | 376 ++
...20261021203734_AddPersistentBackupQueue.cs | 76 +
.../BackupsDbContextModelSnapshot.cs | 81 +-
.../Extensions.cs | 4 +-
...225_UpdateAutoTestConfigEntity.Designer.cs | 0
...251010094225_UpdateAutoTestConfigEntity.cs | 0
...1013075224_ChangeIntsToUShorts.Designer.cs | 0
.../20251013075224_ChangeIntsToUShorts.cs | 0
...3810_ChangeEntityAddTestStatus.Designer.cs | 0
...0251105083810_ChangeEntityAddTestStatus.cs | 0
.../Modules.Backup.Infrastructure.csproj | 30 +
.../Dtos/AdminDashboardDto.cs | 4 +-
.../Dtos/AutoTestBackupConfigDto.cs | 2 +-
.../Dtos/BackupRequestDto.cs | 10 +
.../Dtos/BackupScheduleConfiguration.cs | 4 +-
.../Dtos/BackupTestDto.cs | 4 +-
.../Dtos/BackupsScheduleDto.cs | 4 +-
.../Dtos/PerformedBackupDto.cs | 4 +-
.../Dtos/ServerConnectionDto.cs | 7 +-
.../Dtos/ServerNameIdDto.cs | 3 +
.../Dtos/ServerTunnelDto.cs | 4 +-
.../Dtos/ServersUsersListDto.cs | 4 +-
.../Dtos/UserDashboardDto.cs | 4 +-
.../Enums/DatabaseType.cs | 4 +-
.../Enums/ETestStatus.cs | 2 +-
.../Helpers/BackupScheduleHelper.cs | 11 +-
.../Modules.Backup.Shared/Hubs/BackupHub.cs | 10 +
.../Modules.Backup.Shared.csproj | 10 +
.../Requests/ModifyServerAccessRequest.cs | 4 +-
.../Modules.Crypto.Api/Extension.cs | 4 +-
.../Modules.Crypto.Api.csproj | 12 +
.../Modules.Crypto.Application/Extensions.cs | 4 +-
.../Modules.Crypto.Application.csproj | 12 +
.../Services/CryptoService.cs | 38 +-
.../Interfaces/ICryptoService.cs | 4 +-
.../Modules.Crypto.Shared.csproj | 7 +
.../AdminTokenAuthorizationFilter.cs | 13 +
.../Attributes/RequestValidationFilter.cs | 19 +
.../Common/ApiBaseController.cs | 4 +-
.../Shared/Modules.Shared/Common/DbCommon.cs | 29 +
.../Modules.Shared/Modules.Shared.csproj | 17 +
.../Settings/ApplicationSettings.cs | 49 +
.../ApplicationSettingsEndpoints.cs | 35 +
.../Configuration/DevelopmentSettings.cs | 91 +
.../Configuration/FileApplicationSettings.cs | 86 +
Backend/src/Server.Api/Program.cs | 167 +
.../Server.Api/Properties/launchSettings.json | 1 +
.../Security/ApiExceptionHandler.cs | 15 +
.../src/Server.Api/Security/BootstrapAdmin.cs | 23 +
Backend/src/Server.Api/Server.Api.csproj | 21 +
.../Server.Api/appsettings.Development.json | 25 +
Backend/src/Server.Api/appsettings.json | 44 +
.../DumpToolFixture/DumpToolFixture.csproj | 8 +
Backend/tests/DumpToolFixture/Program.cs | 26 +
.../MySqlDumpSmoke/MySqlDumpSmoke.csproj | 11 +
Backend/tests/MySqlDumpSmoke/Program.cs | 49 +
.../ApplicationSettingsTests.cs | 181 +
.../OctoBackup.Tests/BackupQueueTests.cs | 320 ++
.../DevelopmentSettingsTests.cs | 77 +
.../OctoBackup.Tests/DumpProcessTests.cs | 100 +
.../OctoBackup.Tests/OctoBackup.Tests.csproj | 17 +
.../tests/OctoBackup.Tests/SecurityTests.cs | 119 +
DbBackupService/.dockerignore | 25 -
DbBackupService/OctoBackup.sln | 195 -
DbBackupService/Src/.dockerignore | 30 -
.../Bootstraper/Client/Client.UI/App.razor | 45 -
.../Client/Client.UI/Client.UI.csproj | 26 -
.../HttpTokenAuthHeaderHandler.cs | 18 -
.../Data/Interfaces/IAuthHttpClientService.cs | 61 -
.../Services/AdministrationHttpService.cs | 52 -
.../AuthHttpClientHttpClientService.cs | 194 -
.../Data/Services/AuthStateProvider.cs | 161 -
.../Data/Services/BackupsHttpClientService.cs | 92 -
.../Client.UI/Data/Services/ProfileService.cs | 14 -
.../Data/Services/TokenHttpClientService.cs | 87 -
.../Client/Client.UI/Layout/AuthLayout.razor | 27 -
.../Client.UI/Layout/AuthorizedNavMenu.razor | 55 -
.../Client/Client.UI/Layout/DefaultLayout.cs | 40 -
.../Client/Client.UI/Layout/MainLayout.razor | 150 -
.../Layout/NotAuthorizedNavMenu.razor | 17 -
.../AdministrationDashboard.razor | 77 -
.../AdministrationServersUsers.razor | 121 -
.../AdministrationUsersManagement.razor | 164 -
.../AddUserToServerDialog.razor | 64 -
.../ManageUsersInServerDialog.razor | 98 -
.../UsersManagement/CreateNewUserDialog.razor | 101 -
.../UsersManagement/EditUserDialog.razor | 128 -
.../Authorization/Account/ProfileIndex.razor | 113 -
.../Authorization/Common/AuthorizeUser.razor | 33 -
.../Common/ConfirmPassword.razor | 107 -
.../Pages/Authorization/Common/Login.razor | 121 -
.../Pages/Authorization/Common/Register.razor | 119 -
.../Schedule/BackupScheduleDialog.razor | 195 -
.../Dialogs/Servers/CreateServerDialog.razor | 257 --
...ditServerAutoTestConfigurationDialog.razor | 90 -
.../Dialogs/Servers/EditServerDialog.razor | 258 --
.../Dialogs/Servers/TestServerDialog.razor | 76 -
.../Pages/BackupsModule/MyBackups.razor | 192 -
.../Pages/BackupsModule/MySchedules.razor | 208 -
.../Pages/BackupsModule/MyServers.razor | 267 --
.../AuthorizingUserInfoComponent.razor | 25 -
.../Client/Client.UI/Pages/Dashboard.razor | 69 -
.../Client/Client.UI/Pages/Index.razor | 139 -
.../Bootstraper/Client/Client.UI/Program.cs | 40 -
.../Client.UI/Properties/launchSettings.json | 15 -
.../Bootstraper/Client/Client.UI/Routes.razor | 16 -
.../Client/Client.UI/_Imports.razor | 13 -
.../Client/Client.UI/wwwroot/css/app.css | 92 -
.../wwwroot/media/OctoBackupLogo.png | Bin 117472 -> 0 bytes
.../Server.Api/Common/SeqConfiguration.cs | 3 -
.../Bootstraper/Server/Server.Api/Dockerfile | 51 -
.../Bootstraper/Server/Server.Api/Program.cs | 209 -
.../Server.Api/Properties/launchSettings.json | 28 -
.../Server/Server.Api/Server.Api.csproj | 35 -
.../Server.Api/appsettings.Development.json | 8 -
.../Server/Server.Api/appsettings.json | 31 -
.../Modules.Administration.Api.csproj | 19 -
.../Modules.Administration.Application.csproj | 22 -
.../Services/AdminService.cs | 102 -
.../Modules.Administration.Shared.csproj | 13 -
.../Modules.Auth.Api/Modules.Auth.Api.csproj | 22 -
.../Modules.Auth.Application.csproj | 22 -
.../Services/TokenValidationService.cs | 54 -
.../Modules.Auth.Core.csproj | 13 -
.../Modules.Auth.Infrastructure.csproj | 33 -
.../Repositories/IUserTokenService.cs | 8 -
.../Repositories/UserTokenService.cs | 22 -
.../ActionsRequests/ChangeEmailRequest.cs | 13 -
.../ActionsRequests/ChangePasswordRequest.cs | 15 -
.../ActionsRequests/TokenValidationRequest.cs | 3 -
.../Entities/TokenModelDto.cs | 8 -
.../Interfaces/ITokenValidationService.cs | 9 -
.../Modules.Auth.Shared.csproj | 17 -
.../Static/Entities/AuthHeaderName.cs | 6 -
.../Setters/HttpClientAuthHeaderSetter.cs | 20 -
.../Modules.Backup.Api.csproj | 15 -
.../Modules.Backup.Application.csproj | 26 -
.../Services/DbBackupService.cs | 335 --
.../Services/NotifyService.cs | 64 -
.../Workers/BackupWorker.cs | 38 -
.../Entities/Databases/MySqlDatabase.cs | 97 -
.../Entities/Databases/PostgreSqlDatabase.cs | 113 -
.../Entities/Databases/SqlServerDatabase.cs | 82 -
.../Entities/Models/MailModel.cs | 3 -
.../Modules.Backup.Core.csproj | 24 -
.../StaticClasses/ToolChecker.cs | 34 -
.../Modules.Backup.Infrastructure.csproj | 32 -
.../Dtos/ServerNameIdDto.cs | 3 -
.../Modules.Backup.Shared/Hubs/BackupHub.cs | 54 -
.../Modules.Backup.Shared.csproj | 14 -
.../BackupsTestsEO.cs | 120 -
.../Modules.BackupsTests.Api/Extensions.cs | 19 -
.../Modules.BackupsTests.Api.csproj | 26 -
.../Modules.Crypto.Api.csproj | 17 -
.../Modules.Crypto.Application.csproj | 18 -
.../Modules.Crypto.Shared.csproj | 9 -
.../AdminTokenAuthorizationFilter.cs | 39 -
.../AllowWithoutTokenValidationAttribute.cs | 9 -
.../BasicTokenAuthorizationFilter.cs | 47 -
.../Shared/Modules.Shared/Common/DbCommon.cs | 21 -
.../Modules.Shared/Modules.Shared.csproj | 23 -
DbBackupService/buildAndDeployDocker.bat | 2 -
DbBackupService/certs/OctoBackupCert.pfx | Bin 2652 -> 0 bytes
DbBackupService/docker-compose.yml | 36 -
DbBackupService/docker-composedev.yml | 36 -
Frontend/Dockerfile | 18 +
Frontend/docker/10-local-tls.sh | 13 +
Frontend/docker/default.conf | 55 +
Frontend/e2e/workspace.spec.ts | 203 +
Frontend/index.html | 14 +
Frontend/package-lock.json | 3881 +++++++++++++++++
Frontend/package.json | 36 +
Frontend/playwright.config.ts | 25 +
Frontend/scripts/run-tool.mjs | 86 +
Frontend/scripts/start-test-api.mjs | 43 +
Frontend/src/app/App.tsx | 334 ++
Frontend/src/features/account/AccountPage.tsx | 117 +
.../admin/ApplicationSettingsPage.tsx | 347 ++
Frontend/src/features/admin/UsersPage.tsx | 202 +
Frontend/src/features/auth/AuthPage.tsx | 144 +
Frontend/src/features/backups/BackupsPage.tsx | 163 +
Frontend/src/features/dashboard/Dashboard.tsx | 260 ++
.../src/features/queue/QueueHero.test.tsx | 128 +
Frontend/src/features/queue/QueueHero.tsx | 125 +
Frontend/src/features/queue/QueuePage.tsx | 206 +
Frontend/src/features/queue/useBackupQueue.ts | 73 +
.../features/schedules/SchedulesPage.test.tsx | 51 +
.../src/features/schedules/SchedulesPage.tsx | 285 ++
Frontend/src/features/servers/ServerForm.tsx | 250 ++
Frontend/src/features/servers/ServersPage.tsx | 363 ++
Frontend/src/main.tsx | 25 +
Frontend/src/shared/api.test.ts | 41 +
Frontend/src/shared/api.ts | 63 +
Frontend/src/shared/types.ts | 75 +
Frontend/src/shared/ui.tsx | 134 +
Frontend/src/styles.css | 1900 ++++++++
Frontend/src/test/setup.ts | 1 +
Frontend/src/vite-env.d.ts | 1 +
Frontend/tsconfig.json | 19 +
Frontend/vite.config.ts | 21 +
OctoBackup.sln | 363 ++
README.md | 153 +-
README_PL.md | 83 -
agent/skills/feature-arch/SKILL.md | 109 +
.../bound-event-based-communication.md | 84 +
.../references/bound-feature-isolation.md | 88 +
.../bound-feature-scoped-routing.md | 76 +
.../references/bound-feature-size.md | 74 +
.../references/bound-interface-contracts.md | 83 +
.../references/bound-minimize-shared-state.md | 73 +
.../references/fcomp-colocate-styles.md | 88 +
.../fcomp-composition-over-props.md | 100 +
.../fcomp-container-presentational.md | 99 +
.../references/fcomp-error-boundaries.md | 99 +
.../fcomp-props-as-data-boundary.md | 88 +
.../references/fcomp-single-responsibility.md | 99 +
.../references/fquery-avoid-n-plus-one.md | 80 +
.../fquery-colocate-with-feature.md | 70 +
.../references/fquery-feature-scoped-keys.md | 72 +
.../references/fquery-parallel-fetching.md | 71 +
.../fquery-server-component-fetching.md | 88 +
.../fquery-single-responsibility.md | 66 +
.../references/fstate-context-sparingly.md | 73 +
.../fstate-feature-scoped-stores.md | 79 +
.../references/fstate-lift-minimally.md | 85 +
.../references/fstate-reset-on-unmount.md | 89 +
.../fstate-server-state-separation.md | 93 +
.../references/import-avoid-barrel-files.md | 63 +
.../references/import-no-cross-feature.md | 84 +
.../references/import-path-aliases.md | 64 +
.../references/import-public-api.md | 67 +
.../references/import-type-only.md | 81 +
.../references/import-unidirectional-flow.md | 82 +
.../references/name-descriptive-exports.md | 65 +
.../references/name-feature-naming.md | 60 +
.../references/name-file-conventions.md | 79 +
.../references/struct-app-layer.md | 73 +
.../references/struct-feature-folders.md | 70 +
.../struct-feature-self-contained.md | 62 +
.../references/struct-flat-hierarchy.md | 58 +
.../references/struct-optional-segments.md | 72 +
.../references/struct-shared-layer.md | 68 +
.../references/test-colocate-with-feature.md | 78 +
.../references/test-feature-isolation.md | 88 +
.../test-integration-at-app-layer.md | 87 +
.../references/test-shared-utilities.md | 94 +
agent/skills/msw/SKILL.md | 120 +
.../references/advanced-bypass-requests.md | 81 +
.../msw/references/advanced-cookies-auth.md | 119 +
.../references/advanced-dynamic-scenarios.md | 114 +
.../msw/references/advanced-file-uploads.md | 109 +
.../advanced-playwright-integration.md | 78 +
.../msw/references/advanced-vitest-browser.md | 100 +
.../references/advanced-websocket-mocking.md | 87 +
.../msw/references/debug-common-issues.md | 79 +
.../msw/references/debug-lifecycle-events.md | 88 +
.../msw/references/debug-request-logging.md | 113 +
.../references/debug-verify-interception.md | 95 +
.../msw/references/graphql-batched-queries.md | 93 +
.../msw/references/graphql-error-responses.md | 119 +
.../references/graphql-operation-handlers.md | 101 +
.../msw/references/graphql-schema-first.md | 76 +
.../references/graphql-variables-access.md | 123 +
.../msw/references/handler-absolute-urls.md | 70 +
.../msw/references/handler-domain-grouping.md | 81 +
.../references/handler-happy-path-first.md | 60 +
.../handler-request-body-parsing.md | 76 +
.../references/handler-resolver-argument.md | 86 +
.../handler-reusability-environments.md | 80 +
.../references/handler-shared-resolvers.md | 99 +
.../references/handler-v2-response-syntax.md | 94 +
.../msw/references/match-custom-predicate.md | 99 +
.../msw/references/match-handler-order.md | 93 +
.../msw/references/match-http-methods.md | 98 +
.../msw/references/match-query-params.md | 89 +
.../msw/references/match-url-patterns.md | 87 +
.../msw/references/response-custom-headers.md | 125 +
.../references/response-delay-realistic.md | 92 +
.../references/response-error-simulation.md | 110 +
.../response-http-response-helpers.md | 83 +
.../references/response-one-time-handlers.md | 103 +
.../msw/references/response-streaming.md | 114 +
.../msw/references/setup-lifecycle-hooks.md | 57 +
.../msw/references/setup-node-version.md | 72 +
.../setup-server-node-entrypoint.md | 45 +
.../msw/references/setup-typescript-config.md | 74 +
.../references/setup-unhandled-requests.md | 70 +
.../references/setup-worker-script-commit.md | 65 +
.../msw/references/test-async-utilities.md | 81 +
.../test-avoid-request-assertions.md | 87 +
.../references/test-clear-request-cache.md | 85 +
.../references/test-concurrent-boundary.md | 88 +
.../msw/references/test-fake-timers-config.md | 91 +
.../msw/references/test-jsdom-environment.md | 67 +
.../msw/references/test-reset-handlers.md | 63 +
agent/skills/nextjs/SKILL.md | 114 +
.../references/action-error-handling.md | 75 +
.../references/action-optimistic-updates.md | 74 +
.../references/action-pending-states.md | 68 +
.../nextjs/references/action-revalidation.md | 78 +
.../references/action-server-action-forms.md | 75 +
.../nextjs/references/build-barrel-files.md | 50 +
.../references/build-dynamic-imports.md | 62 +
.../references/build-external-packages.md | 48 +
.../build-optimize-package-imports.md | 42 +
.../references/build-turbopack-config.md | 71 +
.../nextjs/references/cache-fetch-options.md | 53 +
.../nextjs/references/cache-react-cache.md | 58 +
.../references/cache-revalidate-path.md | 62 +
.../nextjs/references/cache-revalidate-tag.md | 65 +
.../nextjs/references/cache-segment-config.md | 63 +
.../references/cache-use-cache-directive.md | 57 +
.../references/client-children-pattern.md | 75 +
.../references/client-hydration-mismatch.md | 101 +
.../references/client-third-party-scripts.md | 67 +
.../references/client-use-client-boundary.md | 72 +
.../references/meta-generate-metadata.md | 70 +
.../references/meta-opengraph-images.md | 72 +
agent/skills/nextjs/references/meta-robots.md | 68 +
.../skills/nextjs/references/meta-sitemap.md | 76 +
.../references/route-instant-navigations.md | 97 +
.../references/route-intercepting-routes.md | 76 +
.../nextjs/references/route-not-found.md | 59 +
.../references/route-parallel-routes.md | 79 +
.../references/route-partial-prefetching.md | 87 +
.../nextjs/references/route-prefetching.md | 71 +
.../nextjs/references/route-proxy-ts.md | 62 +
.../server-avoid-client-fetching.md | 71 +
.../references/server-component-streaming.md | 70 +
.../references/server-data-colocation.md | 63 +
.../references/server-error-handling.md | 79 +
.../references/server-parallel-fetching.md | 69 +
.../references/server-preload-pattern.md | 68 +
.../nextjs/references/stream-error-tsx.md | 67 +
.../nextjs/references/stream-loading-tsx.md | 63 +
.../references/stream-nested-suspense.md | 82 +
.../references/stream-skeleton-matching.md | 72 +
.../references/stream-suspense-boundaries.md | 62 +
agent/skills/nuqs/SKILL.md | 109 +
.../references/advanced-custom-parsers.md | 70 +
.../nuqs/references/advanced-eq-function.md | 94 +
.../references/advanced-framework-adapters.md | 82 +
.../nuqs/references/advanced-url-keys.md | 62 +
.../nuqs/references/debug-common-errors.md | 53 +
.../nuqs/references/debug-enable-logging.md | 51 +
agent/skills/nuqs/references/debug-testing.md | 55 +
.../nuqs/references/history-back-sync.md | 51 +
.../references/history-push-navigation.md | 76 +
.../references/history-replace-ephemeral.md | 87 +
.../references/history-scroll-behavior.md | 60 +
.../nuqs/references/parser-array-format.md | 59 +
.../nuqs/references/parser-date-format.md | 67 +
.../nuqs/references/parser-enum-validation.md | 81 +
.../nuqs/references/parser-hex-colors.md | 68 +
.../nuqs/references/parser-index-offset.md | 72 +
.../nuqs/references/parser-json-validation.md | 97 +
.../references/parser-use-typed-parsers.md | 58 +
.../nuqs/references/parser-with-default.md | 65 +
.../nuqs/references/perf-avoid-rerender.md | 88 +
.../nuqs/references/perf-clear-on-default.md | 55 +
.../nuqs/references/perf-debounce-search.md | 82 +
.../nuqs/references/perf-serialize-utility.md | 81 +
.../nuqs/references/perf-throttle-updates.md | 66 +
.../nuqs/references/server-next15-async.md | 80 +
.../references/server-parse-before-get.md | 82 +
.../references/server-search-params-cache.md | 78 +
.../nuqs/references/server-shallow-false.md | 74 +
.../nuqs/references/server-share-parsers.md | 74 +
.../nuqs/references/server-use-transition.md | 96 +
.../nuqs/references/setup-import-server.md | 72 +
.../nuqs/references/setup-nextjs-version.md | 64 +
.../nuqs/references/setup-nuqs-adapter.md | 77 +
.../nuqs/references/setup-shared-parsers.md | 73 +
.../nuqs/references/setup-use-client.md | 69 +
.../nuqs/references/state-avoid-derived.md | 84 +
.../nuqs/references/state-clear-with-null.md | 81 +
.../references/state-controlled-inputs.md | 83 +
.../references/state-functional-updates.md | 68 +
.../references/state-options-inheritance.md | 78 +
.../nuqs/references/state-setter-return.md | 78 +
.../nuqs/references/state-use-query-states.md | 75 +
agent/skills/playwright/SKILL.md | 113 +
.../references/arch-cleanup-state.md | 83 +
.../playwright/references/arch-fixtures.md | 89 +
.../references/arch-page-object-model.md | 80 +
.../references/arch-parallel-execution.md | 75 +
.../references/arch-test-isolation.md | 61 +
.../references/arch-test-production.md | 74 +
.../references/assert-aria-snapshots.md | 58 +
.../playwright/references/auth-api-login.md | 99 +
.../references/auth-multiple-roles.md | 111 +
.../references/auth-parallel-workers.md | 101 +
.../references/auth-session-storage.md | 106 +
.../references/auth-storage-state.md | 97 +
.../references/debug-ci-reporters.md | 81 +
.../playwright/references/debug-inspector.md | 86 +
.../references/debug-screenshots-videos.md | 85 +
.../references/debug-trace-viewer.md | 79 +
.../playwright/references/loc-avoid-xpath.md | 64 +
.../references/loc-chained-locators.md | 87 +
.../playwright/references/loc-data-testid.md | 80 +
.../references/loc-frame-locator.md | 45 +
.../references/loc-label-selectors.md | 78 +
.../references/loc-placeholder-selector.md | 87 +
.../references/loc-role-selectors.md | 74 +
.../references/loc-text-selectors.md | 77 +
.../references/mock-abort-requests.md | 107 +
.../references/mock-api-responses.md | 91 +
.../playwright/references/mock-har-files.md | 100 +
.../references/mock-intercept-modify.md | 101 +
.../references/mock-network-conditions.md | 98 +
.../references/next-app-router-navigation.md | 87 +
.../references/next-baseurl-config.md | 108 +
.../references/next-server-actions.md | 90 +
.../references/next-server-components.md | 92 +
.../references/next-wait-hydration.md | 103 +
.../references/perf-browser-selection.md | 99 +
.../playwright/references/perf-headless-ci.md | 100 +
.../playwright/references/perf-retries.md | 100 +
.../references/perf-reuse-server.md | 87 +
.../playwright/references/perf-sharding.md | 105 +
.../references/wait-action-retries.md | 83 +
.../references/wait-avoid-hard-waits.md | 90 +
.../references/wait-custom-timeout.md | 98 +
.../references/wait-network-idle.md | 65 +
.../references/wait-soft-assertions.md | 78 +
.../references/wait-web-first-assertions.md | 91 +
agent/skills/react-hook-form/SKILL.md | 118 +
.../references/adv-devtools-performance.md | 69 +
.../references/adv-formprovider-memo.md | 78 +
.../references/adv-opaque-types.md | 52 +
.../references/adv-testing-wrapper.md | 63 +
.../array-complete-default-objects.md | 66 +
.../array-separate-crud-operations.md | 76 +
.../array-unique-fieldarray-per-name.md | 58 +
.../references/array-use-field-id-as-key.md | 54 +
.../array-virtualization-formprovider.md | 64 +
.../ctrl-avoid-double-registration.md | 46 +
.../references/ctrl-controller-field-props.md | 56 +
.../ctrl-local-state-combination.md | 69 +
...ctrl-single-usecontroller-per-component.md | 66 +
.../ctrl-usecontroller-isolation.md | 64 +
.../formcfg-async-default-values.md | 69 +
.../references/formcfg-default-values.md | 57 +
.../references/formcfg-revalidate-mode.md | 52 +
.../references/formcfg-should-unregister.md | 64 +
.../formcfg-useeffect-dependency.md | 54 +
.../references/formcfg-validation-mode.md | 55 +
.../formstate-avoid-isvalid-with-onsubmit.md | 57 +
.../formstate-destructure-formstate.md | 48 +
...ormstate-getfieldstate-for-single-field.md | 54 +
.../formstate-subscribe-to-specific-fields.md | 54 +
.../formstate-useformstate-isolation.md | 65 +
.../integ-mui-controller-pattern.md | 59 +
.../references/integ-shadcn-form-import.md | 64 +
.../references/integ-shadcn-select-wiring.md | 64 +
.../integ-typed-submit-server-action.md | 52 +
.../references/integ-value-transform.md | 59 +
.../references/sub-avoid-watch-in-render.md | 48 +
.../references/sub-deep-subscription.md | 62 +
.../sub-useformcontext-sparingly.md | 58 +
.../references/sub-usewatch-default-value.md | 50 +
.../references/sub-usewatch-over-watch.md | 58 +
.../references/sub-usewatch-with-getvalues.md | 54 +
.../references/sub-watch-specific-fields.md | 54 +
.../references/valid-delay-error.md | 52 +
.../valid-dynamic-schema-factory.md | 57 +
.../valid-error-message-strategy.md | 82 +
.../references/valid-form-level-validate.md | 47 +
.../references/valid-inline-vs-resolver.md | 63 +
.../references/valid-native-validation.md | 60 +
.../references/valid-resolver-caching.md | 58 +
.../references/valid-trigger-should-touch.md | 44 +
agent/skills/react/SKILL.md | 86 +
agent/skills/react/references/_sections.md | 46 +
.../references/conc-automatic-batching.md | 64 +
.../react/references/conc-concurrent-safe.md | 71 +
.../references/conc-suspense-fallback.md | 66 +
.../references/conc-use-deferred-value.md | 65 +
.../react/references/conc-use-transition.md | 75 +
.../react/references/conc-view-transitions.md | 81 +
.../references/data-cache-deduplication.md | 60 +
.../react/references/data-error-boundaries.md | 76 +
.../references/data-parallel-fetching.md | 74 +
.../references/data-suspense-data-fetching.md | 76 +
.../skills/react/references/data-use-hook.md | 77 +
.../references/effect-avoid-unnecessary.md | 69 +
.../skills/react/references/effect-cleanup.md | 75 +
.../references/effect-object-dependencies.md | 56 +
.../references/effect-use-browser-only.md | 62 +
.../references/effect-use-effect-event.md | 53 +
.../effect-use-sync-external-store.md | 80 +
agent/skills/react/references/form-actions.md | 83 +
.../react/references/form-use-action-state.md | 80 +
.../react/references/form-use-form-status.md | 68 +
.../react/references/form-use-optimistic.md | 77 +
.../react/references/form-validation.md | 89 +
.../react/references/memo-avoid-premature.md | 68 +
.../skills/react/references/memo-compiler.md | 84 +
.../react/references/memo-react-memo.md | 72 +
.../react/references/memo-use-callback.md | 70 +
.../skills/react/references/memo-use-memo.md | 53 +
.../react/references/rcomp-composition.md | 75 +
.../references/rcomp-controlled-components.md | 63 +
.../react/references/rcomp-fragment-refs.md | 71 +
.../react/references/rcomp-key-reset.md | 74 +
.../react/references/rcomp-render-props.md | 69 +
.../references/rsc-avoid-client-only-libs.md | 66 +
.../references/rsc-composition-pattern.md | 90 +
.../react/references/rsc-context-provider.md | 50 +
.../references/rsc-data-fetching-server.md | 68 +
.../references/rsc-serializable-props.md | 70 +
.../references/rsc-server-client-boundary.md | 63 +
.../skills/react/references/rsc-streaming.md | 64 +
.../references/rstate-context-optimization.md | 68 +
.../react/references/rstate-derived-values.md | 70 +
.../references/rstate-functional-updates.md | 58 +
.../references/rstate-lazy-initialization.md | 59 +
.../react/references/rstate-use-reducer.md | 77 +
agent/skills/shadcn/SKILL.md | 109 +
.../references/ally-ensure-color-contrast.md | 62 +
.../ally-maintain-focus-management.md | 84 +
.../ally-preserve-aria-attributes.md | 77 +
.../ally-preserve-keyboard-navigation.md | 72 +
.../references/ally-provide-sr-only-labels.md | 75 +
.../references/arch-current-cli-registry.md | 61 +
.../arch-extend-variants-with-cva.md | 67 +
...-forward-refs-for-composable-components.md | 83 +
.../arch-isolate-component-variants.md | 82 +
...arch-preserve-radix-primitive-structure.md | 57 +
.../references/arch-unified-radix-package.md | 44 +
.../arch-use-asChild-for-custom-triggers.md | 49 +
.../arch-use-cn-for-class-merging.md | 62 +
.../comp-combine-command-with-popover.md | 106 +
.../comp-compose-with-compound-components.md | 104 +
.../comp-create-reusable-form-fields.md | 157 +
.../references/comp-nest-dialogs-correctly.md | 108 +
.../comp-use-drawer-for-mobile-modals.md | 128 +
.../comp-use-slot-pattern-for-flexibility.md | 118 +
.../data-empty-states-with-guidance.md | 95 +
.../references/data-paginate-server-side.md | 108 +
.../data-use-skeleton-loading-states.md | 104 +
...a-use-tanstack-table-for-complex-tables.md | 121 +
.../references/data-virtualize-large-lists.md | 82 +
.../form-handle-async-validation.md | 104 +
.../form-reset-form-state-correctly.md | 92 +
.../form-show-validation-errors-correctly.md | 58 +
.../form-use-react-hook-form-integration.md | 106 +
.../form-use-zod-for-schema-validation.md | 86 +
...rf-avoid-unnecessary-rerenders-in-forms.md | 88 +
.../references/perf-debounce-search-inputs.md | 85 +
.../perf-lazy-load-heavy-components.md | 90 +
.../perf-memoize-expensive-renders.md | 90 +
.../references/perf-optimize-icon-imports.md | 60 +
.../state-colocate-state-with-components.md | 103 +
.../state-lift-state-to-appropriate-level.md | 103 +
...e-prefer-uncontrolled-for-simple-inputs.md | 91 +
.../state-use-controlled-dialog-state.md | 127 +
.../style-avoid-important-overrides.md | 58 +
.../style-consistent-spacing-scale.md | 67 +
.../references/style-dark-mode-support.md | 83 +
.../style-responsive-design-patterns.md | 75 +
.../style-use-css-variables-for-theming.md | 56 +
.../style-use-tailwind-theme-extend.md | 63 +
agent/skills/tailwind/SKILL.md | 108 +
.../tailwind/references/anim-3d-transforms.md | 56 +
.../references/anim-gpu-accelerated.md | 47 +
.../references/anim-gradient-interpolation.md | 46 +
.../references/anim-starting-style.md | 63 +
.../tailwind/references/build-cli-package.md | 43 +
.../references/build-content-detection.md | 44 +
.../tailwind/references/build-css-import.md | 36 +
.../tailwind/references/build-node-version.md | 44 +
.../references/build-postcss-simplify.md | 40 +
.../tailwind/references/build-vite-plugin.md | 39 +
.../references/bundle-avoid-cdn-production.md | 56 +
.../references/bundle-avoid-preprocessors.md | 53 +
.../references/bundle-css-minification.md | 57 +
.../bundle-remove-unused-plugins.md | 55 +
.../references/bundle-split-critical-css.md | 62 +
.../references/comp-avoid-apply-overuse.md | 58 +
.../references/comp-container-customize.md | 59 +
.../references/comp-reference-directive.md | 59 +
.../tailwind/references/comp-smart-sorting.md | 50 +
.../references/comp-utility-file-scope.md | 61 +
.../references/gen-avoid-theme-bloat.md | 47 +
.../references/gen-css-first-config.md | 54 +
.../references/gen-css-variable-syntax.md | 43 +
.../references/gen-dynamic-utilities.md | 51 +
.../tailwind/references/gen-oklch-colors.md | 40 +
.../references/gen-utility-directive.md | 52 +
.../references/resp-container-queries.md | 55 +
.../references/resp-custom-breakpoints.md | 54 +
.../references/resp-hover-capability.md | 60 +
.../references/resp-logical-properties.md | 51 +
.../tailwind/references/resp-mobile-first.md | 48 +
.../tailwind/references/theme-color-scheme.md | 55 +
.../references/theme-dark-mode-class.md | 59 +
.../references/theme-prefix-variables.md | 56 +
.../references/theme-runtime-variables.md | 55 +
.../references/theme-semantic-tokens.md | 65 +
.../references/util-explicit-colors.md | 43 +
.../references/util-gradient-via-none.md | 37 +
.../references/util-important-modifier.md | 43 +
.../references/util-opacity-modifier.md | 50 +
.../references/util-renamed-utilities.md | 45 +
.../references/util-variant-stacking.md | 41 +
agent/skills/tanstack-query/SKILL.md | 116 +
.../references/cache-enabled-option.md | 76 +
.../references/cache-global-defaults.md | 73 +
.../cache-invalidation-precision.md | 78 +
.../cache-placeholder-vs-initial.md | 69 +
.../references/cache-refetch-triggers.md | 68 +
.../references/cache-staletime-gctime.md | 71 +
.../references/error-conditional-retry.md | 93 +
.../references/error-display-patterns.md | 100 +
.../references/error-global-handler.md | 91 +
.../references/error-retry-config.md | 80 +
.../references/error-throw-on-error.md | 96 +
.../references/infinite-flatten-pages.md | 108 +
.../references/infinite-loading-states.md | 96 +
.../references/infinite-max-pages.md | 86 +
.../references/infinite-refetch-behavior.md | 79 +
.../references/mutation-avoid-parallel.md | 92 +
.../references/mutation-cancel-queries.md | 72 +
.../mutation-invalidate-onsettled.md | 66 +
.../references/mutation-optimistic-updates.md | 81 +
.../references/mutation-setquerydata.md | 67 +
.../references/prefetch-avoid-waterfalls.md | 98 +
.../references/prefetch-flatten-api.md | 70 +
.../references/prefetch-in-queryfn.md | 97 +
.../references/prefetch-infinite-query.md | 60 +
.../references/prefetch-on-hover.md | 94 +
.../references/prefetch-server-components.md | 88 +
.../references/render-notify-props.md | 66 +
.../references/render-select-derived.md | 86 +
.../references/render-select-memoize.md | 75 +
.../references/render-structural-sharing.md | 88 +
.../references/render-tracked-props.md | 80 +
.../suspense-boundaries-placement.md | 97 +
.../references/suspense-error-boundaries.md | 100 +
.../references/suspense-parallel-queries.md | 93 +
.../references/suspense-use-suspense-hooks.md | 66 +
.../references/tquery-always-arrays.md | 49 +
.../references/tquery-colocate-keys.md | 66 +
.../references/tquery-hierarchical-keys.md | 61 +
.../references/tquery-key-factories.md | 58 +
.../references/tquery-options-pattern.md | 78 +
.../references/tquery-serializable-objects.md | 60 +
agent/skills/tdd/SKILL.md | 113 +
.../tdd/references/assert-custom-matchers.md | 86 +
.../tdd/references/assert-error-messages.md | 64 +
.../assert-no-assertions-antipattern.md | 70 +
.../tdd/references/assert-snapshot-testing.md | 71 +
.../references/assert-specific-assertions.md | 71 +
.../references/cycle-maintain-test-list.md | 68 +
.../references/cycle-minimal-code-to-pass.md | 62 +
.../references/cycle-refactor-after-green.md | 58 +
.../tdd/references/cycle-small-increments.md | 69 +
.../cycle-verify-test-fails-first.md | 64 +
.../tdd/references/cycle-write-test-first.md | 63 +
.../references/data-avoid-mystery-guests.md | 62 +
.../tdd/references/data-builder-pattern.md | 99 +
.../tdd/references/data-minimal-setup.md | 69 +
.../tdd/references/data-unique-identifiers.md | 79 +
.../tdd/references/data-use-factories.md | 87 +
.../tdd/references/design-aaa-pattern.md | 68 +
.../references/design-avoid-logic-in-tests.md | 74 +
.../design-descriptive-test-names.md | 64 +
.../design-one-assertion-per-test.md | 66 +
...design-test-behavior-not-implementation.md | 69 +
.../tdd/references/design-test-edge-cases.md | 83 +
.../references/isolate-deterministic-tests.md | 80 +
.../isolate-mock-external-dependencies.md | 69 +
.../tdd/references/isolate-no-shared-state.md | 73 +
.../isolate-prefer-stubs-over-mocks.md | 72 +
.../isolate-use-dependency-injection.md | 91 +
.../tdd/references/org-file-structure.md | 76 +
.../tdd/references/org-group-by-behavior.md | 68 +
.../tdd/references/org-parameterized-tests.md | 79 +
.../tdd/references/org-setup-teardown.md | 84 +
.../tdd/references/org-test-utilities.md | 98 +
.../references/perf-avoid-network-calls.md | 78 +
.../skills/tdd/references/perf-avoid-sleep.md | 82 +
.../tdd/references/perf-fast-unit-tests.md | 48 +
.../tdd/references/perf-fix-flaky-tests.md | 83 +
.../tdd/references/perf-parallelize-tests.md | 87 +
.../tdd/references/strat-coverage-targets.md | 70 +
.../references/strat-e2e-critical-paths.md | 78 +
.../strat-integration-boundaries.md | 79 +
.../tdd/references/strat-mutation-testing.md | 71 +
.../tdd/references/strat-test-pyramid.md | 58 +
agent/skills/typescript/SKILL.md | 102 +
.../references/advanced-branded-types.md | 83 +
.../references/advanced-satisfies-operator.md | 94 +
.../advanced-template-literal-types.md | 105 +
.../references/async-avoid-loop-await.md | 78 +
.../async-avoid-unnecessary-async.md | 61 +
.../references/async-defer-await.md | 74 +
.../references/async-explicit-return-types.md | 79 +
.../references/async-parallel-promises.md | 63 +
.../references/mem-avoid-closure-leaks.md | 88 +
.../references/mem-avoid-global-state.md | 97 +
.../references/mem-cleanup-event-listeners.md | 111 +
.../typescript/references/mem-clear-timers.md | 106 +
.../mem-use-weakmap-for-metadata.md | 84 +
.../references/module-avoid-barrel-imports.md | 70 +
.../module-avoid-circular-dependencies.md | 92 +
.../module-control-types-inclusion.md | 92 +
.../references/module-dynamic-imports.md | 78 +
.../references/module-use-type-imports.md | 80 +
.../runtime-avoid-object-spread-in-loops.md | 79 +
.../runtime-cache-property-access.md | 85 +
.../runtime-prefer-array-methods.md | 73 +
.../runtime-use-for-of-for-iteration.md | 89 +
.../references/runtime-use-set-for-lookups.md | 64 +
.../references/runtime-use-string-methods.md | 79 +
.../references/safety-assertion-functions.md | 92 +
.../references/safety-const-assertions.md | 77 +
.../references/safety-exhaustive-checks.md | 83 +
.../safety-prefer-unknown-over-any.md | 76 +
.../references/safety-strict-null-checks.md | 72 +
.../references/safety-use-type-guards.md | 86 +
.../references/tscfg-enable-incremental.md | 68 +
.../references/tscfg-exclude-properly.md | 85 +
.../references/tscfg-isolate-modules.md | 68 +
.../references/tscfg-project-references.md | 97 +
.../references/tscfg-skip-lib-check.md | 63 +
.../references/tscfg-strict-function-types.md | 67 +
.../references/tscfg-typescript-7.md | 75 +
.../references/type-avoid-deep-generics.md | 81 +
.../references/type-avoid-large-unions.md | 57 +
.../references/type-explicit-return-types.md | 65 +
.../type-extract-conditional-types.md | 57 +
.../type-interfaces-over-intersections.md | 41 +
.../references/type-limit-recursion-depth.md | 65 +
.../references/type-simplify-mapped-types.md | 71 +
agent/skills/ui-design/SKILL.md | 101 +
.../ui-design/references/access-alt-text.md | 63 +
.../references/access-aria-labels.md | 57 +
.../references/access-focus-indicators.md | 53 +
.../references/access-heading-hierarchy.md | 48 +
.../references/access-keyboard-navigation.md | 52 +
.../references/access-semantic-html.md | 53 +
.../references/access-target-size.md | 56 +
.../references/anim-duration-easing.md | 77 +
.../references/anim-gpu-properties.md | 75 +
.../references/anim-reduced-motion.md | 82 +
.../ui-design/references/anim-will-change.md | 78 +
.../references/color-contrast-ratio.md | 67 +
.../ui-design/references/color-dark-mode.md | 74 +
.../references/color-not-only-indicator.md | 79 +
.../references/color-semantic-palette.md | 64 +
.../ui-design/references/cwv-critical-css.md | 55 +
.../ui-design/references/cwv-improve-inp.md | 70 +
.../references/cwv-lazy-load-offscreen.md | 60 +
.../ui-design/references/cwv-minimize-cls.md | 66 +
.../ui-design/references/cwv-optimize-lcp.md | 59 +
.../references/cwv-responsive-images.md | 63 +
.../ui-design/references/form-autocomplete.md | 62 +
.../references/form-error-messages.md | 61 +
.../references/form-inline-validation.md | 67 +
.../ui-design/references/form-input-types.md | 63 +
.../ui-design/references/form-labels-above.md | 74 +
.../ui-design/references/layout-f-pattern.md | 65 +
.../references/layout-grid-system.md | 67 +
.../references/layout-proximity-grouping.md | 57 +
.../ui-design/references/layout-single-cta.md | 64 +
.../references/layout-visual-hierarchy.md | 69 +
.../ui-design/references/layout-whitespace.md | 70 +
.../references/resp-container-queries.md | 64 +
.../references/resp-fluid-typography.md | 65 +
.../ui-design/references/resp-mobile-first.md | 83 +
.../references/resp-touch-targets.md | 67 +
.../references/resp-viewport-meta.md | 57 +
.../ui-design/references/typo-font-display.md | 61 +
.../ui-design/references/typo-line-height.md | 66 +
.../references/typo-preload-fonts.md | 62 +
.../references/typo-readable-line-length.md | 58 +
.../references/typo-system-font-stack.md | 57 +
.../vercel-composition-patterns/SKILL.md | 73 +
.../rules/architecture-avoid-boolean-props.md | 102 +
.../rules/architecture-compound-components.md | 112 +
.../patterns-children-over-render-props.md | 87 +
.../rules/patterns-explicit-variants.md | 100 +
.../rules/react19-no-forwardref.md | 42 +
.../rules/state-context-interface.md | 191 +
.../rules/state-decouple-implementation.md | 113 +
.../rules/state-lift-state.md | 125 +
.../vercel-react-best-practices/SKILL.md | 133 +
.../rules/advanced-effect-event-deps.md | 56 +
.../rules/advanced-event-handler-refs.md | 55 +
.../rules/advanced-init-once.md | 42 +
.../rules/advanced-use-latest.md | 39 +
.../rules/async-api-routes.md | 38 +
.../async-cheap-condition-before-await.md | 37 +
.../rules/async-defer-await.md | 82 +
.../rules/async-dependencies.md | 51 +
.../rules/async-parallel.md | 28 +
.../rules/async-suspense-boundaries.md | 99 +
.../rules/bundle-analyzable-paths.md | 63 +
.../rules/bundle-barrel-imports.md | 60 +
.../rules/bundle-conditional.md | 31 +
.../rules/bundle-defer-third-party.md | 49 +
.../rules/bundle-dynamic-imports.md | 35 +
.../rules/bundle-preload.md | 50 +
.../rules/client-event-listeners.md | 74 +
.../rules/client-localstorage-schema.md | 71 +
.../rules/client-passive-event-listeners.md | 48 +
.../rules/client-swr-dedup.md | 56 +
.../rules/js-batch-dom-css.md | 107 +
.../rules/js-cache-function-results.md | 80 +
.../rules/js-cache-property-access.md | 28 +
.../rules/js-cache-storage.md | 70 +
.../rules/js-combine-iterations.md | 32 +
.../rules/js-early-exit.md | 50 +
.../rules/js-flatmap-filter.md | 60 +
.../rules/js-hoist-regexp.md | 45 +
.../rules/js-index-maps.md | 37 +
.../rules/js-length-check-first.md | 49 +
.../rules/js-min-max-loop.md | 82 +
.../rules/js-request-idle-callback.md | 105 +
.../rules/js-set-map-lookups.md | 24 +
.../rules/js-tosorted-immutable.md | 57 +
.../rules/rendering-activity.md | 26 +
.../rules/rendering-animate-svg-wrapper.md | 47 +
.../rules/rendering-conditional-render.md | 40 +
.../rules/rendering-content-visibility.md | 38 +
.../rules/rendering-hoist-jsx.md | 46 +
.../rules/rendering-hydration-no-flicker.md | 82 +
.../rendering-hydration-suppress-warning.md | 30 +
.../rules/rendering-resource-hints.md | 85 +
.../rules/rendering-script-defer-async.md | 68 +
.../rules/rendering-svg-precision.md | 28 +
.../rules/rendering-usetransition-loading.md | 79 +
.../rules/rerender-defer-reads.md | 39 +
.../rules/rerender-dependencies.md | 45 +
.../rules/rerender-derived-state-no-effect.md | 40 +
.../rules/rerender-derived-state.md | 29 +
.../rules/rerender-functional-setstate.md | 74 +
.../rules/rerender-lazy-state-init.md | 58 +
.../rules/rerender-memo-with-default-value.md | 38 +
.../rules/rerender-memo.md | 44 +
.../rules/rerender-move-effect-to-event.md | 45 +
.../rules/rerender-no-inline-components.md | 82 +
.../rerender-simple-expression-in-memo.md | 35 +
.../rules/rerender-split-combined-hooks.md | 64 +
.../rules/rerender-transitions.md | 40 +
.../rules/rerender-use-deferred-value.md | 59 +
.../rerender-use-ref-transient-values.md | 73 +
.../rules/server-after-nonblocking.md | 73 +
.../rules/server-auth-actions.md | 96 +
.../rules/server-cache-lru.md | 41 +
.../rules/server-cache-react.md | 76 +
.../rules/server-dedup-props.md | 65 +
.../rules/server-hoist-static-io.md | 149 +
.../rules/server-no-shared-module-state.md | 50 +
.../rules/server-parallel-fetching.md | 83 +
.../rules/server-parallel-nested-fetching.md | 34 +
.../rules/server-serialization.md | 38 +
agent/skills/vitest/SKILL.md | 121 +
.../vitest/references/assert-edge-cases.md | 83 +
.../references/assert-expect-assertions.md | 95 +
.../assert-one-assertion-concept.md | 94 +
.../references/assert-specific-matchers.md | 83 +
.../references/assert-toequal-vs-tobe.md | 91 +
.../vitest/references/async-act-wrapper.md | 79 +
.../references/async-await-assertions.md | 45 +
.../references/async-concurrent-expect.md | 60 +
.../vitest/references/async-error-handling.md | 72 +
.../vitest/references/async-fake-timers.md | 82 +
.../references/async-return-promises.md | 60 +
.../references/async-waitfor-polling.md | 84 +
.../references/env-browser-api-mocking.md | 96 +
.../vitest/references/env-globals-config.md | 85 +
.../references/env-per-file-override.md | 115 +
.../vitest/references/env-setup-files.md | 94 +
.../references/mock-avoid-overmocking.md | 98 +
.../references/mock-clear-between-tests.md | 86 +
.../mock-implementation-not-value.md | 81 +
.../vitest/references/mock-msw-network.md | 96 +
.../vitest/references/mock-spyon-vs-mock.md | 85 +
.../vitest/references/mock-type-safety.md | 97 +
.../references/mock-vi-mock-hoisting.md | 95 +
.../vitest/references/org-describe-nesting.md | 85 +
.../vitest/references/org-file-colocation.md | 93 +
.../vitest/references/org-test-naming.md | 86 +
.../vitest/references/org-test-skip-only.md | 75 +
.../vitest/references/perf-bail-fast-fail.md | 84 +
.../references/perf-bench-test-context.md | 59 +
.../references/perf-disable-isolation.md | 91 +
.../vitest/references/perf-happy-dom.md | 103 +
.../vitest/references/perf-pool-selection.md | 78 +
.../vitest/references/perf-run-mode-ci.md | 93 +
.../skills/vitest/references/perf-sharding.md | 101 +
.../references/setup-avoid-shared-state.md | 98 +
.../references/setup-beforeall-expensive.md | 81 +
.../references/setup-beforeeach-cleanup.md | 83 +
.../vitest/references/setup-reset-modules.md | 91 +
.../vitest/references/setup-restore-mocks.md | 88 +
.../vitest/references/setup-test-factories.md | 104 +
.../references/setup-vitest5-migration.md | 64 +
.../vitest/references/snap-avoid-large.md | 76 +
.../vitest/references/snap-describe-intent.md | 78 +
.../references/snap-inline-over-file.md | 73 +
.../vitest/references/snap-review-updates.md | 79 +
.../references/snap-stable-serialization.md | 97 +
agent/skills/web-design-guidelines/SKILL.md | 38 +
agent/skills/zod/SKILL.md | 127 +
.../zod/references/compose-intersection.md | 147 +
.../zod/references/compose-lazy-recursive.md | 154 +
agent/skills/zod/references/compose-pipe.md | 113 +
.../zod/references/compose-preprocess.md | 142 +
.../zod/references/compose-shared-schemas.md | 138 +
.../error-avoid-throwing-in-refine.md | 127 +
.../zod/references/error-custom-messages.md | 113 +
agent/skills/zod/references/error-i18n.md | 141 +
.../zod/references/error-path-for-nested.md | 133 +
.../zod/references/error-use-flatten.md | 85 +
.../references/object-discriminated-unions.md | 138 +
.../object-extend-for-composition.md | 145 +
.../references/object-optional-vs-nullable.md | 117 +
.../references/object-partial-for-updates.md | 142 +
.../skills/zod/references/object-pick-omit.md | 146 +
.../zod/references/object-strict-vs-strip.md | 70 +
.../parse-async-for-async-refinements.md | 118 +
.../parse-avoid-double-validation.md | 129 +
.../zod/references/parse-handle-all-issues.md | 125 +
.../zod/references/parse-never-trust-json.md | 113 +
.../zod/references/parse-use-safeparse.md | 102 +
.../zod/references/parse-validate-early.md | 120 +
.../parse-validate-for-boolean-checks.md | 64 +
agent/skills/zod/references/perf-arrays.md | 153 +
.../references/perf-avoid-dynamic-creation.md | 97 +
.../zod/references/perf-cache-schemas.md | 138 +
.../zod/references/perf-compile-schemas.md | 76 +
.../zod/references/perf-lazy-loading.md | 135 +
agent/skills/zod/references/perf-zod-mini.md | 110 +
.../skills/zod/references/refine-add-path.md | 141 +
agent/skills/zod/references/refine-catch.md | 143 +
.../skills/zod/references/refine-defaults.md | 131 +
.../zod/references/refine-transform-coerce.md | 105 +
.../skills/zod/references/refine-use-codec.md | 41 +
.../zod/references/refine-vs-superrefine.md | 152 +
.../references/schema-avoid-optional-abuse.md | 93 +
.../schema-coercion-for-form-data.md | 88 +
.../references/schema-string-validations.md | 114 +
.../skills/zod/references/schema-use-enums.md | 115 +
.../schema-use-primitives-correctly.md | 61 +
.../references/schema-use-unknown-not-any.md | 88 +
.../zod/references/type-branded-types.md | 102 +
.../zod/references/type-enable-strict-mode.md | 130 +
.../type-export-schemas-and-types.md | 116 +
.../zod/references/type-input-vs-output.md | 116 +
.../skills/zod/references/type-use-z-infer.md | 110 +
certs/.gitignore | 2 +
compose.dbs.yaml | 70 +
compose.yaml | 61 +
docs/ARCHITECTURE.md | 142 +
docs/DESIGN.md | 65 +
docs/MIGRATION.md | 245 ++
docs/OPERATIONS.md | 388 ++
docs/PRODUCT.md | 37 +
docs/README_PL.md | 90 +
docs/ROADMAP.md | 42 +
docs/SECURITY.md | 94 +
.../diagrams/BackupService_MapaMysli.png | Bin
.../diagrams/ServiceLogicProject.drawio | 0
.../ServiceLogicProject_v1.0_Drawio.jpg | Bin
.../ServiceLogicProject_v1.2_Drawio.png | Bin
global.json | 1 +
scripts/check-compose.mjs | 203 +
scripts/dev.mjs | 126 +
skills-lock.json | 113 +
2609 files changed, 189466 insertions(+), 7299 deletions(-)
create mode 100644 .agents/skills/feature-arch/SKILL.md
create mode 100644 .agents/skills/feature-arch/references/bound-event-based-communication.md
create mode 100644 .agents/skills/feature-arch/references/bound-feature-isolation.md
create mode 100644 .agents/skills/feature-arch/references/bound-feature-scoped-routing.md
create mode 100644 .agents/skills/feature-arch/references/bound-feature-size.md
create mode 100644 .agents/skills/feature-arch/references/bound-interface-contracts.md
create mode 100644 .agents/skills/feature-arch/references/bound-minimize-shared-state.md
create mode 100644 .agents/skills/feature-arch/references/fcomp-colocate-styles.md
create mode 100644 .agents/skills/feature-arch/references/fcomp-composition-over-props.md
create mode 100644 .agents/skills/feature-arch/references/fcomp-container-presentational.md
create mode 100644 .agents/skills/feature-arch/references/fcomp-error-boundaries.md
create mode 100644 .agents/skills/feature-arch/references/fcomp-props-as-data-boundary.md
create mode 100644 .agents/skills/feature-arch/references/fcomp-single-responsibility.md
create mode 100644 .agents/skills/feature-arch/references/fquery-avoid-n-plus-one.md
create mode 100644 .agents/skills/feature-arch/references/fquery-colocate-with-feature.md
create mode 100644 .agents/skills/feature-arch/references/fquery-feature-scoped-keys.md
create mode 100644 .agents/skills/feature-arch/references/fquery-parallel-fetching.md
create mode 100644 .agents/skills/feature-arch/references/fquery-server-component-fetching.md
create mode 100644 .agents/skills/feature-arch/references/fquery-single-responsibility.md
create mode 100644 .agents/skills/feature-arch/references/fstate-context-sparingly.md
create mode 100644 .agents/skills/feature-arch/references/fstate-feature-scoped-stores.md
create mode 100644 .agents/skills/feature-arch/references/fstate-lift-minimally.md
create mode 100644 .agents/skills/feature-arch/references/fstate-reset-on-unmount.md
create mode 100644 .agents/skills/feature-arch/references/fstate-server-state-separation.md
create mode 100644 .agents/skills/feature-arch/references/import-avoid-barrel-files.md
create mode 100644 .agents/skills/feature-arch/references/import-no-cross-feature.md
create mode 100644 .agents/skills/feature-arch/references/import-path-aliases.md
create mode 100644 .agents/skills/feature-arch/references/import-public-api.md
create mode 100644 .agents/skills/feature-arch/references/import-type-only.md
create mode 100644 .agents/skills/feature-arch/references/import-unidirectional-flow.md
create mode 100644 .agents/skills/feature-arch/references/name-descriptive-exports.md
create mode 100644 .agents/skills/feature-arch/references/name-feature-naming.md
create mode 100644 .agents/skills/feature-arch/references/name-file-conventions.md
create mode 100644 .agents/skills/feature-arch/references/struct-app-layer.md
create mode 100644 .agents/skills/feature-arch/references/struct-feature-folders.md
create mode 100644 .agents/skills/feature-arch/references/struct-feature-self-contained.md
create mode 100644 .agents/skills/feature-arch/references/struct-flat-hierarchy.md
create mode 100644 .agents/skills/feature-arch/references/struct-optional-segments.md
create mode 100644 .agents/skills/feature-arch/references/struct-shared-layer.md
create mode 100644 .agents/skills/feature-arch/references/test-colocate-with-feature.md
create mode 100644 .agents/skills/feature-arch/references/test-feature-isolation.md
create mode 100644 .agents/skills/feature-arch/references/test-integration-at-app-layer.md
create mode 100644 .agents/skills/feature-arch/references/test-shared-utilities.md
create mode 100644 .agents/skills/msw/SKILL.md
create mode 100644 .agents/skills/msw/references/advanced-bypass-requests.md
create mode 100644 .agents/skills/msw/references/advanced-cookies-auth.md
create mode 100644 .agents/skills/msw/references/advanced-dynamic-scenarios.md
create mode 100644 .agents/skills/msw/references/advanced-file-uploads.md
create mode 100644 .agents/skills/msw/references/advanced-playwright-integration.md
create mode 100644 .agents/skills/msw/references/advanced-vitest-browser.md
create mode 100644 .agents/skills/msw/references/advanced-websocket-mocking.md
create mode 100644 .agents/skills/msw/references/debug-common-issues.md
create mode 100644 .agents/skills/msw/references/debug-lifecycle-events.md
create mode 100644 .agents/skills/msw/references/debug-request-logging.md
create mode 100644 .agents/skills/msw/references/debug-verify-interception.md
create mode 100644 .agents/skills/msw/references/graphql-batched-queries.md
create mode 100644 .agents/skills/msw/references/graphql-error-responses.md
create mode 100644 .agents/skills/msw/references/graphql-operation-handlers.md
create mode 100644 .agents/skills/msw/references/graphql-schema-first.md
create mode 100644 .agents/skills/msw/references/graphql-variables-access.md
create mode 100644 .agents/skills/msw/references/handler-absolute-urls.md
create mode 100644 .agents/skills/msw/references/handler-domain-grouping.md
create mode 100644 .agents/skills/msw/references/handler-happy-path-first.md
create mode 100644 .agents/skills/msw/references/handler-request-body-parsing.md
create mode 100644 .agents/skills/msw/references/handler-resolver-argument.md
create mode 100644 .agents/skills/msw/references/handler-reusability-environments.md
create mode 100644 .agents/skills/msw/references/handler-shared-resolvers.md
create mode 100644 .agents/skills/msw/references/handler-v2-response-syntax.md
create mode 100644 .agents/skills/msw/references/match-custom-predicate.md
create mode 100644 .agents/skills/msw/references/match-handler-order.md
create mode 100644 .agents/skills/msw/references/match-http-methods.md
create mode 100644 .agents/skills/msw/references/match-query-params.md
create mode 100644 .agents/skills/msw/references/match-url-patterns.md
create mode 100644 .agents/skills/msw/references/response-custom-headers.md
create mode 100644 .agents/skills/msw/references/response-delay-realistic.md
create mode 100644 .agents/skills/msw/references/response-error-simulation.md
create mode 100644 .agents/skills/msw/references/response-http-response-helpers.md
create mode 100644 .agents/skills/msw/references/response-one-time-handlers.md
create mode 100644 .agents/skills/msw/references/response-streaming.md
create mode 100644 .agents/skills/msw/references/setup-lifecycle-hooks.md
create mode 100644 .agents/skills/msw/references/setup-node-version.md
create mode 100644 .agents/skills/msw/references/setup-server-node-entrypoint.md
create mode 100644 .agents/skills/msw/references/setup-typescript-config.md
create mode 100644 .agents/skills/msw/references/setup-unhandled-requests.md
create mode 100644 .agents/skills/msw/references/setup-worker-script-commit.md
create mode 100644 .agents/skills/msw/references/test-async-utilities.md
create mode 100644 .agents/skills/msw/references/test-avoid-request-assertions.md
create mode 100644 .agents/skills/msw/references/test-clear-request-cache.md
create mode 100644 .agents/skills/msw/references/test-concurrent-boundary.md
create mode 100644 .agents/skills/msw/references/test-fake-timers-config.md
create mode 100644 .agents/skills/msw/references/test-jsdom-environment.md
create mode 100644 .agents/skills/msw/references/test-reset-handlers.md
create mode 100644 .agents/skills/nextjs/SKILL.md
create mode 100644 .agents/skills/nextjs/references/action-error-handling.md
create mode 100644 .agents/skills/nextjs/references/action-optimistic-updates.md
create mode 100644 .agents/skills/nextjs/references/action-pending-states.md
create mode 100644 .agents/skills/nextjs/references/action-revalidation.md
create mode 100644 .agents/skills/nextjs/references/action-server-action-forms.md
create mode 100644 .agents/skills/nextjs/references/build-barrel-files.md
create mode 100644 .agents/skills/nextjs/references/build-dynamic-imports.md
create mode 100644 .agents/skills/nextjs/references/build-external-packages.md
create mode 100644 .agents/skills/nextjs/references/build-optimize-package-imports.md
create mode 100644 .agents/skills/nextjs/references/build-turbopack-config.md
create mode 100644 .agents/skills/nextjs/references/cache-fetch-options.md
create mode 100644 .agents/skills/nextjs/references/cache-react-cache.md
create mode 100644 .agents/skills/nextjs/references/cache-revalidate-path.md
create mode 100644 .agents/skills/nextjs/references/cache-revalidate-tag.md
create mode 100644 .agents/skills/nextjs/references/cache-segment-config.md
create mode 100644 .agents/skills/nextjs/references/cache-use-cache-directive.md
create mode 100644 .agents/skills/nextjs/references/client-children-pattern.md
create mode 100644 .agents/skills/nextjs/references/client-hydration-mismatch.md
create mode 100644 .agents/skills/nextjs/references/client-third-party-scripts.md
create mode 100644 .agents/skills/nextjs/references/client-use-client-boundary.md
create mode 100644 .agents/skills/nextjs/references/meta-generate-metadata.md
create mode 100644 .agents/skills/nextjs/references/meta-opengraph-images.md
create mode 100644 .agents/skills/nextjs/references/meta-robots.md
create mode 100644 .agents/skills/nextjs/references/meta-sitemap.md
create mode 100644 .agents/skills/nextjs/references/route-instant-navigations.md
create mode 100644 .agents/skills/nextjs/references/route-intercepting-routes.md
create mode 100644 .agents/skills/nextjs/references/route-not-found.md
create mode 100644 .agents/skills/nextjs/references/route-parallel-routes.md
create mode 100644 .agents/skills/nextjs/references/route-partial-prefetching.md
create mode 100644 .agents/skills/nextjs/references/route-prefetching.md
create mode 100644 .agents/skills/nextjs/references/route-proxy-ts.md
create mode 100644 .agents/skills/nextjs/references/server-avoid-client-fetching.md
create mode 100644 .agents/skills/nextjs/references/server-component-streaming.md
create mode 100644 .agents/skills/nextjs/references/server-data-colocation.md
create mode 100644 .agents/skills/nextjs/references/server-error-handling.md
create mode 100644 .agents/skills/nextjs/references/server-parallel-fetching.md
create mode 100644 .agents/skills/nextjs/references/server-preload-pattern.md
create mode 100644 .agents/skills/nextjs/references/stream-error-tsx.md
create mode 100644 .agents/skills/nextjs/references/stream-loading-tsx.md
create mode 100644 .agents/skills/nextjs/references/stream-nested-suspense.md
create mode 100644 .agents/skills/nextjs/references/stream-skeleton-matching.md
create mode 100644 .agents/skills/nextjs/references/stream-suspense-boundaries.md
create mode 100644 .agents/skills/nuqs/SKILL.md
create mode 100644 .agents/skills/nuqs/references/advanced-custom-parsers.md
create mode 100644 .agents/skills/nuqs/references/advanced-eq-function.md
create mode 100644 .agents/skills/nuqs/references/advanced-framework-adapters.md
create mode 100644 .agents/skills/nuqs/references/advanced-url-keys.md
create mode 100644 .agents/skills/nuqs/references/debug-common-errors.md
create mode 100644 .agents/skills/nuqs/references/debug-enable-logging.md
create mode 100644 .agents/skills/nuqs/references/debug-testing.md
create mode 100644 .agents/skills/nuqs/references/history-back-sync.md
create mode 100644 .agents/skills/nuqs/references/history-push-navigation.md
create mode 100644 .agents/skills/nuqs/references/history-replace-ephemeral.md
create mode 100644 .agents/skills/nuqs/references/history-scroll-behavior.md
create mode 100644 .agents/skills/nuqs/references/parser-array-format.md
create mode 100644 .agents/skills/nuqs/references/parser-date-format.md
create mode 100644 .agents/skills/nuqs/references/parser-enum-validation.md
create mode 100644 .agents/skills/nuqs/references/parser-hex-colors.md
create mode 100644 .agents/skills/nuqs/references/parser-index-offset.md
create mode 100644 .agents/skills/nuqs/references/parser-json-validation.md
create mode 100644 .agents/skills/nuqs/references/parser-use-typed-parsers.md
create mode 100644 .agents/skills/nuqs/references/parser-with-default.md
create mode 100644 .agents/skills/nuqs/references/perf-avoid-rerender.md
create mode 100644 .agents/skills/nuqs/references/perf-clear-on-default.md
create mode 100644 .agents/skills/nuqs/references/perf-debounce-search.md
create mode 100644 .agents/skills/nuqs/references/perf-serialize-utility.md
create mode 100644 .agents/skills/nuqs/references/perf-throttle-updates.md
create mode 100644 .agents/skills/nuqs/references/server-next15-async.md
create mode 100644 .agents/skills/nuqs/references/server-parse-before-get.md
create mode 100644 .agents/skills/nuqs/references/server-search-params-cache.md
create mode 100644 .agents/skills/nuqs/references/server-shallow-false.md
create mode 100644 .agents/skills/nuqs/references/server-share-parsers.md
create mode 100644 .agents/skills/nuqs/references/server-use-transition.md
create mode 100644 .agents/skills/nuqs/references/setup-import-server.md
create mode 100644 .agents/skills/nuqs/references/setup-nextjs-version.md
create mode 100644 .agents/skills/nuqs/references/setup-nuqs-adapter.md
create mode 100644 .agents/skills/nuqs/references/setup-shared-parsers.md
create mode 100644 .agents/skills/nuqs/references/setup-use-client.md
create mode 100644 .agents/skills/nuqs/references/state-avoid-derived.md
create mode 100644 .agents/skills/nuqs/references/state-clear-with-null.md
create mode 100644 .agents/skills/nuqs/references/state-controlled-inputs.md
create mode 100644 .agents/skills/nuqs/references/state-functional-updates.md
create mode 100644 .agents/skills/nuqs/references/state-options-inheritance.md
create mode 100644 .agents/skills/nuqs/references/state-setter-return.md
create mode 100644 .agents/skills/nuqs/references/state-use-query-states.md
create mode 100644 .agents/skills/playwright/SKILL.md
create mode 100644 .agents/skills/playwright/references/arch-cleanup-state.md
create mode 100644 .agents/skills/playwright/references/arch-fixtures.md
create mode 100644 .agents/skills/playwright/references/arch-page-object-model.md
create mode 100644 .agents/skills/playwright/references/arch-parallel-execution.md
create mode 100644 .agents/skills/playwright/references/arch-test-isolation.md
create mode 100644 .agents/skills/playwright/references/arch-test-production.md
create mode 100644 .agents/skills/playwright/references/assert-aria-snapshots.md
create mode 100644 .agents/skills/playwright/references/auth-api-login.md
create mode 100644 .agents/skills/playwright/references/auth-multiple-roles.md
create mode 100644 .agents/skills/playwright/references/auth-parallel-workers.md
create mode 100644 .agents/skills/playwright/references/auth-session-storage.md
create mode 100644 .agents/skills/playwright/references/auth-storage-state.md
create mode 100644 .agents/skills/playwright/references/debug-ci-reporters.md
create mode 100644 .agents/skills/playwright/references/debug-inspector.md
create mode 100644 .agents/skills/playwright/references/debug-screenshots-videos.md
create mode 100644 .agents/skills/playwright/references/debug-trace-viewer.md
create mode 100644 .agents/skills/playwright/references/loc-avoid-xpath.md
create mode 100644 .agents/skills/playwright/references/loc-chained-locators.md
create mode 100644 .agents/skills/playwright/references/loc-data-testid.md
create mode 100644 .agents/skills/playwright/references/loc-frame-locator.md
create mode 100644 .agents/skills/playwright/references/loc-label-selectors.md
create mode 100644 .agents/skills/playwright/references/loc-placeholder-selector.md
create mode 100644 .agents/skills/playwright/references/loc-role-selectors.md
create mode 100644 .agents/skills/playwright/references/loc-text-selectors.md
create mode 100644 .agents/skills/playwright/references/mock-abort-requests.md
create mode 100644 .agents/skills/playwright/references/mock-api-responses.md
create mode 100644 .agents/skills/playwright/references/mock-har-files.md
create mode 100644 .agents/skills/playwright/references/mock-intercept-modify.md
create mode 100644 .agents/skills/playwright/references/mock-network-conditions.md
create mode 100644 .agents/skills/playwright/references/next-app-router-navigation.md
create mode 100644 .agents/skills/playwright/references/next-baseurl-config.md
create mode 100644 .agents/skills/playwright/references/next-server-actions.md
create mode 100644 .agents/skills/playwright/references/next-server-components.md
create mode 100644 .agents/skills/playwright/references/next-wait-hydration.md
create mode 100644 .agents/skills/playwright/references/perf-browser-selection.md
create mode 100644 .agents/skills/playwright/references/perf-headless-ci.md
create mode 100644 .agents/skills/playwright/references/perf-retries.md
create mode 100644 .agents/skills/playwright/references/perf-reuse-server.md
create mode 100644 .agents/skills/playwright/references/perf-sharding.md
create mode 100644 .agents/skills/playwright/references/wait-action-retries.md
create mode 100644 .agents/skills/playwright/references/wait-avoid-hard-waits.md
create mode 100644 .agents/skills/playwright/references/wait-custom-timeout.md
create mode 100644 .agents/skills/playwright/references/wait-network-idle.md
create mode 100644 .agents/skills/playwright/references/wait-soft-assertions.md
create mode 100644 .agents/skills/playwright/references/wait-web-first-assertions.md
create mode 100644 .agents/skills/react-hook-form/SKILL.md
create mode 100644 .agents/skills/react-hook-form/references/adv-devtools-performance.md
create mode 100644 .agents/skills/react-hook-form/references/adv-formprovider-memo.md
create mode 100644 .agents/skills/react-hook-form/references/adv-opaque-types.md
create mode 100644 .agents/skills/react-hook-form/references/adv-testing-wrapper.md
create mode 100644 .agents/skills/react-hook-form/references/array-complete-default-objects.md
create mode 100644 .agents/skills/react-hook-form/references/array-separate-crud-operations.md
create mode 100644 .agents/skills/react-hook-form/references/array-unique-fieldarray-per-name.md
create mode 100644 .agents/skills/react-hook-form/references/array-use-field-id-as-key.md
create mode 100644 .agents/skills/react-hook-form/references/array-virtualization-formprovider.md
create mode 100644 .agents/skills/react-hook-form/references/ctrl-avoid-double-registration.md
create mode 100644 .agents/skills/react-hook-form/references/ctrl-controller-field-props.md
create mode 100644 .agents/skills/react-hook-form/references/ctrl-local-state-combination.md
create mode 100644 .agents/skills/react-hook-form/references/ctrl-single-usecontroller-per-component.md
create mode 100644 .agents/skills/react-hook-form/references/ctrl-usecontroller-isolation.md
create mode 100644 .agents/skills/react-hook-form/references/formcfg-async-default-values.md
create mode 100644 .agents/skills/react-hook-form/references/formcfg-default-values.md
create mode 100644 .agents/skills/react-hook-form/references/formcfg-revalidate-mode.md
create mode 100644 .agents/skills/react-hook-form/references/formcfg-should-unregister.md
create mode 100644 .agents/skills/react-hook-form/references/formcfg-useeffect-dependency.md
create mode 100644 .agents/skills/react-hook-form/references/formcfg-validation-mode.md
create mode 100644 .agents/skills/react-hook-form/references/formstate-avoid-isvalid-with-onsubmit.md
create mode 100644 .agents/skills/react-hook-form/references/formstate-destructure-formstate.md
create mode 100644 .agents/skills/react-hook-form/references/formstate-getfieldstate-for-single-field.md
create mode 100644 .agents/skills/react-hook-form/references/formstate-subscribe-to-specific-fields.md
create mode 100644 .agents/skills/react-hook-form/references/formstate-useformstate-isolation.md
create mode 100644 .agents/skills/react-hook-form/references/integ-mui-controller-pattern.md
create mode 100644 .agents/skills/react-hook-form/references/integ-shadcn-form-import.md
create mode 100644 .agents/skills/react-hook-form/references/integ-shadcn-select-wiring.md
create mode 100644 .agents/skills/react-hook-form/references/integ-typed-submit-server-action.md
create mode 100644 .agents/skills/react-hook-form/references/integ-value-transform.md
create mode 100644 .agents/skills/react-hook-form/references/sub-avoid-watch-in-render.md
create mode 100644 .agents/skills/react-hook-form/references/sub-deep-subscription.md
create mode 100644 .agents/skills/react-hook-form/references/sub-useformcontext-sparingly.md
create mode 100644 .agents/skills/react-hook-form/references/sub-usewatch-default-value.md
create mode 100644 .agents/skills/react-hook-form/references/sub-usewatch-over-watch.md
create mode 100644 .agents/skills/react-hook-form/references/sub-usewatch-with-getvalues.md
create mode 100644 .agents/skills/react-hook-form/references/sub-watch-specific-fields.md
create mode 100644 .agents/skills/react-hook-form/references/valid-delay-error.md
create mode 100644 .agents/skills/react-hook-form/references/valid-dynamic-schema-factory.md
create mode 100644 .agents/skills/react-hook-form/references/valid-error-message-strategy.md
create mode 100644 .agents/skills/react-hook-form/references/valid-form-level-validate.md
create mode 100644 .agents/skills/react-hook-form/references/valid-inline-vs-resolver.md
create mode 100644 .agents/skills/react-hook-form/references/valid-native-validation.md
create mode 100644 .agents/skills/react-hook-form/references/valid-resolver-caching.md
create mode 100644 .agents/skills/react-hook-form/references/valid-trigger-should-touch.md
create mode 100644 .agents/skills/react/SKILL.md
create mode 100644 .agents/skills/react/references/_sections.md
create mode 100644 .agents/skills/react/references/conc-automatic-batching.md
create mode 100644 .agents/skills/react/references/conc-concurrent-safe.md
create mode 100644 .agents/skills/react/references/conc-suspense-fallback.md
create mode 100644 .agents/skills/react/references/conc-use-deferred-value.md
create mode 100644 .agents/skills/react/references/conc-use-transition.md
create mode 100644 .agents/skills/react/references/conc-view-transitions.md
create mode 100644 .agents/skills/react/references/data-cache-deduplication.md
create mode 100644 .agents/skills/react/references/data-error-boundaries.md
create mode 100644 .agents/skills/react/references/data-parallel-fetching.md
create mode 100644 .agents/skills/react/references/data-suspense-data-fetching.md
create mode 100644 .agents/skills/react/references/data-use-hook.md
create mode 100644 .agents/skills/react/references/effect-avoid-unnecessary.md
create mode 100644 .agents/skills/react/references/effect-cleanup.md
create mode 100644 .agents/skills/react/references/effect-object-dependencies.md
create mode 100644 .agents/skills/react/references/effect-use-browser-only.md
create mode 100644 .agents/skills/react/references/effect-use-effect-event.md
create mode 100644 .agents/skills/react/references/effect-use-sync-external-store.md
create mode 100644 .agents/skills/react/references/form-actions.md
create mode 100644 .agents/skills/react/references/form-use-action-state.md
create mode 100644 .agents/skills/react/references/form-use-form-status.md
create mode 100644 .agents/skills/react/references/form-use-optimistic.md
create mode 100644 .agents/skills/react/references/form-validation.md
create mode 100644 .agents/skills/react/references/memo-avoid-premature.md
create mode 100644 .agents/skills/react/references/memo-compiler.md
create mode 100644 .agents/skills/react/references/memo-react-memo.md
create mode 100644 .agents/skills/react/references/memo-use-callback.md
create mode 100644 .agents/skills/react/references/memo-use-memo.md
create mode 100644 .agents/skills/react/references/rcomp-composition.md
create mode 100644 .agents/skills/react/references/rcomp-controlled-components.md
create mode 100644 .agents/skills/react/references/rcomp-fragment-refs.md
create mode 100644 .agents/skills/react/references/rcomp-key-reset.md
create mode 100644 .agents/skills/react/references/rcomp-render-props.md
create mode 100644 .agents/skills/react/references/rsc-avoid-client-only-libs.md
create mode 100644 .agents/skills/react/references/rsc-composition-pattern.md
create mode 100644 .agents/skills/react/references/rsc-context-provider.md
create mode 100644 .agents/skills/react/references/rsc-data-fetching-server.md
create mode 100644 .agents/skills/react/references/rsc-serializable-props.md
create mode 100644 .agents/skills/react/references/rsc-server-client-boundary.md
create mode 100644 .agents/skills/react/references/rsc-streaming.md
create mode 100644 .agents/skills/react/references/rstate-context-optimization.md
create mode 100644 .agents/skills/react/references/rstate-derived-values.md
create mode 100644 .agents/skills/react/references/rstate-functional-updates.md
create mode 100644 .agents/skills/react/references/rstate-lazy-initialization.md
create mode 100644 .agents/skills/react/references/rstate-use-reducer.md
create mode 100644 .agents/skills/shadcn/SKILL.md
create mode 100644 .agents/skills/shadcn/references/ally-ensure-color-contrast.md
create mode 100644 .agents/skills/shadcn/references/ally-maintain-focus-management.md
create mode 100644 .agents/skills/shadcn/references/ally-preserve-aria-attributes.md
create mode 100644 .agents/skills/shadcn/references/ally-preserve-keyboard-navigation.md
create mode 100644 .agents/skills/shadcn/references/ally-provide-sr-only-labels.md
create mode 100644 .agents/skills/shadcn/references/arch-current-cli-registry.md
create mode 100644 .agents/skills/shadcn/references/arch-extend-variants-with-cva.md
create mode 100644 .agents/skills/shadcn/references/arch-forward-refs-for-composable-components.md
create mode 100644 .agents/skills/shadcn/references/arch-isolate-component-variants.md
create mode 100644 .agents/skills/shadcn/references/arch-preserve-radix-primitive-structure.md
create mode 100644 .agents/skills/shadcn/references/arch-unified-radix-package.md
create mode 100644 .agents/skills/shadcn/references/arch-use-asChild-for-custom-triggers.md
create mode 100644 .agents/skills/shadcn/references/arch-use-cn-for-class-merging.md
create mode 100644 .agents/skills/shadcn/references/comp-combine-command-with-popover.md
create mode 100644 .agents/skills/shadcn/references/comp-compose-with-compound-components.md
create mode 100644 .agents/skills/shadcn/references/comp-create-reusable-form-fields.md
create mode 100644 .agents/skills/shadcn/references/comp-nest-dialogs-correctly.md
create mode 100644 .agents/skills/shadcn/references/comp-use-drawer-for-mobile-modals.md
create mode 100644 .agents/skills/shadcn/references/comp-use-slot-pattern-for-flexibility.md
create mode 100644 .agents/skills/shadcn/references/data-empty-states-with-guidance.md
create mode 100644 .agents/skills/shadcn/references/data-paginate-server-side.md
create mode 100644 .agents/skills/shadcn/references/data-use-skeleton-loading-states.md
create mode 100644 .agents/skills/shadcn/references/data-use-tanstack-table-for-complex-tables.md
create mode 100644 .agents/skills/shadcn/references/data-virtualize-large-lists.md
create mode 100644 .agents/skills/shadcn/references/form-handle-async-validation.md
create mode 100644 .agents/skills/shadcn/references/form-reset-form-state-correctly.md
create mode 100644 .agents/skills/shadcn/references/form-show-validation-errors-correctly.md
create mode 100644 .agents/skills/shadcn/references/form-use-react-hook-form-integration.md
create mode 100644 .agents/skills/shadcn/references/form-use-zod-for-schema-validation.md
create mode 100644 .agents/skills/shadcn/references/perf-avoid-unnecessary-rerenders-in-forms.md
create mode 100644 .agents/skills/shadcn/references/perf-debounce-search-inputs.md
create mode 100644 .agents/skills/shadcn/references/perf-lazy-load-heavy-components.md
create mode 100644 .agents/skills/shadcn/references/perf-memoize-expensive-renders.md
create mode 100644 .agents/skills/shadcn/references/perf-optimize-icon-imports.md
create mode 100644 .agents/skills/shadcn/references/state-colocate-state-with-components.md
create mode 100644 .agents/skills/shadcn/references/state-lift-state-to-appropriate-level.md
create mode 100644 .agents/skills/shadcn/references/state-prefer-uncontrolled-for-simple-inputs.md
create mode 100644 .agents/skills/shadcn/references/state-use-controlled-dialog-state.md
create mode 100644 .agents/skills/shadcn/references/style-avoid-important-overrides.md
create mode 100644 .agents/skills/shadcn/references/style-consistent-spacing-scale.md
create mode 100644 .agents/skills/shadcn/references/style-dark-mode-support.md
create mode 100644 .agents/skills/shadcn/references/style-responsive-design-patterns.md
create mode 100644 .agents/skills/shadcn/references/style-use-css-variables-for-theming.md
create mode 100644 .agents/skills/shadcn/references/style-use-tailwind-theme-extend.md
create mode 100644 .agents/skills/tailwind/SKILL.md
create mode 100644 .agents/skills/tailwind/references/anim-3d-transforms.md
create mode 100644 .agents/skills/tailwind/references/anim-gpu-accelerated.md
create mode 100644 .agents/skills/tailwind/references/anim-gradient-interpolation.md
create mode 100644 .agents/skills/tailwind/references/anim-starting-style.md
create mode 100644 .agents/skills/tailwind/references/build-cli-package.md
create mode 100644 .agents/skills/tailwind/references/build-content-detection.md
create mode 100644 .agents/skills/tailwind/references/build-css-import.md
create mode 100644 .agents/skills/tailwind/references/build-node-version.md
create mode 100644 .agents/skills/tailwind/references/build-postcss-simplify.md
create mode 100644 .agents/skills/tailwind/references/build-vite-plugin.md
create mode 100644 .agents/skills/tailwind/references/bundle-avoid-cdn-production.md
create mode 100644 .agents/skills/tailwind/references/bundle-avoid-preprocessors.md
create mode 100644 .agents/skills/tailwind/references/bundle-css-minification.md
create mode 100644 .agents/skills/tailwind/references/bundle-remove-unused-plugins.md
create mode 100644 .agents/skills/tailwind/references/bundle-split-critical-css.md
create mode 100644 .agents/skills/tailwind/references/comp-avoid-apply-overuse.md
create mode 100644 .agents/skills/tailwind/references/comp-container-customize.md
create mode 100644 .agents/skills/tailwind/references/comp-reference-directive.md
create mode 100644 .agents/skills/tailwind/references/comp-smart-sorting.md
create mode 100644 .agents/skills/tailwind/references/comp-utility-file-scope.md
create mode 100644 .agents/skills/tailwind/references/gen-avoid-theme-bloat.md
create mode 100644 .agents/skills/tailwind/references/gen-css-first-config.md
create mode 100644 .agents/skills/tailwind/references/gen-css-variable-syntax.md
create mode 100644 .agents/skills/tailwind/references/gen-dynamic-utilities.md
create mode 100644 .agents/skills/tailwind/references/gen-oklch-colors.md
create mode 100644 .agents/skills/tailwind/references/gen-utility-directive.md
create mode 100644 .agents/skills/tailwind/references/resp-container-queries.md
create mode 100644 .agents/skills/tailwind/references/resp-custom-breakpoints.md
create mode 100644 .agents/skills/tailwind/references/resp-hover-capability.md
create mode 100644 .agents/skills/tailwind/references/resp-logical-properties.md
create mode 100644 .agents/skills/tailwind/references/resp-mobile-first.md
create mode 100644 .agents/skills/tailwind/references/theme-color-scheme.md
create mode 100644 .agents/skills/tailwind/references/theme-dark-mode-class.md
create mode 100644 .agents/skills/tailwind/references/theme-prefix-variables.md
create mode 100644 .agents/skills/tailwind/references/theme-runtime-variables.md
create mode 100644 .agents/skills/tailwind/references/theme-semantic-tokens.md
create mode 100644 .agents/skills/tailwind/references/util-explicit-colors.md
create mode 100644 .agents/skills/tailwind/references/util-gradient-via-none.md
create mode 100644 .agents/skills/tailwind/references/util-important-modifier.md
create mode 100644 .agents/skills/tailwind/references/util-opacity-modifier.md
create mode 100644 .agents/skills/tailwind/references/util-renamed-utilities.md
create mode 100644 .agents/skills/tailwind/references/util-variant-stacking.md
create mode 100644 .agents/skills/tanstack-query/SKILL.md
create mode 100644 .agents/skills/tanstack-query/references/cache-enabled-option.md
create mode 100644 .agents/skills/tanstack-query/references/cache-global-defaults.md
create mode 100644 .agents/skills/tanstack-query/references/cache-invalidation-precision.md
create mode 100644 .agents/skills/tanstack-query/references/cache-placeholder-vs-initial.md
create mode 100644 .agents/skills/tanstack-query/references/cache-refetch-triggers.md
create mode 100644 .agents/skills/tanstack-query/references/cache-staletime-gctime.md
create mode 100644 .agents/skills/tanstack-query/references/error-conditional-retry.md
create mode 100644 .agents/skills/tanstack-query/references/error-display-patterns.md
create mode 100644 .agents/skills/tanstack-query/references/error-global-handler.md
create mode 100644 .agents/skills/tanstack-query/references/error-retry-config.md
create mode 100644 .agents/skills/tanstack-query/references/error-throw-on-error.md
create mode 100644 .agents/skills/tanstack-query/references/infinite-flatten-pages.md
create mode 100644 .agents/skills/tanstack-query/references/infinite-loading-states.md
create mode 100644 .agents/skills/tanstack-query/references/infinite-max-pages.md
create mode 100644 .agents/skills/tanstack-query/references/infinite-refetch-behavior.md
create mode 100644 .agents/skills/tanstack-query/references/mutation-avoid-parallel.md
create mode 100644 .agents/skills/tanstack-query/references/mutation-cancel-queries.md
create mode 100644 .agents/skills/tanstack-query/references/mutation-invalidate-onsettled.md
create mode 100644 .agents/skills/tanstack-query/references/mutation-optimistic-updates.md
create mode 100644 .agents/skills/tanstack-query/references/mutation-setquerydata.md
create mode 100644 .agents/skills/tanstack-query/references/prefetch-avoid-waterfalls.md
create mode 100644 .agents/skills/tanstack-query/references/prefetch-flatten-api.md
create mode 100644 .agents/skills/tanstack-query/references/prefetch-in-queryfn.md
create mode 100644 .agents/skills/tanstack-query/references/prefetch-infinite-query.md
create mode 100644 .agents/skills/tanstack-query/references/prefetch-on-hover.md
create mode 100644 .agents/skills/tanstack-query/references/prefetch-server-components.md
create mode 100644 .agents/skills/tanstack-query/references/render-notify-props.md
create mode 100644 .agents/skills/tanstack-query/references/render-select-derived.md
create mode 100644 .agents/skills/tanstack-query/references/render-select-memoize.md
create mode 100644 .agents/skills/tanstack-query/references/render-structural-sharing.md
create mode 100644 .agents/skills/tanstack-query/references/render-tracked-props.md
create mode 100644 .agents/skills/tanstack-query/references/suspense-boundaries-placement.md
create mode 100644 .agents/skills/tanstack-query/references/suspense-error-boundaries.md
create mode 100644 .agents/skills/tanstack-query/references/suspense-parallel-queries.md
create mode 100644 .agents/skills/tanstack-query/references/suspense-use-suspense-hooks.md
create mode 100644 .agents/skills/tanstack-query/references/tquery-always-arrays.md
create mode 100644 .agents/skills/tanstack-query/references/tquery-colocate-keys.md
create mode 100644 .agents/skills/tanstack-query/references/tquery-hierarchical-keys.md
create mode 100644 .agents/skills/tanstack-query/references/tquery-key-factories.md
create mode 100644 .agents/skills/tanstack-query/references/tquery-options-pattern.md
create mode 100644 .agents/skills/tanstack-query/references/tquery-serializable-objects.md
create mode 100644 .agents/skills/tdd/SKILL.md
create mode 100644 .agents/skills/tdd/references/assert-custom-matchers.md
create mode 100644 .agents/skills/tdd/references/assert-error-messages.md
create mode 100644 .agents/skills/tdd/references/assert-no-assertions-antipattern.md
create mode 100644 .agents/skills/tdd/references/assert-snapshot-testing.md
create mode 100644 .agents/skills/tdd/references/assert-specific-assertions.md
create mode 100644 .agents/skills/tdd/references/cycle-maintain-test-list.md
create mode 100644 .agents/skills/tdd/references/cycle-minimal-code-to-pass.md
create mode 100644 .agents/skills/tdd/references/cycle-refactor-after-green.md
create mode 100644 .agents/skills/tdd/references/cycle-small-increments.md
create mode 100644 .agents/skills/tdd/references/cycle-verify-test-fails-first.md
create mode 100644 .agents/skills/tdd/references/cycle-write-test-first.md
create mode 100644 .agents/skills/tdd/references/data-avoid-mystery-guests.md
create mode 100644 .agents/skills/tdd/references/data-builder-pattern.md
create mode 100644 .agents/skills/tdd/references/data-minimal-setup.md
create mode 100644 .agents/skills/tdd/references/data-unique-identifiers.md
create mode 100644 .agents/skills/tdd/references/data-use-factories.md
create mode 100644 .agents/skills/tdd/references/design-aaa-pattern.md
create mode 100644 .agents/skills/tdd/references/design-avoid-logic-in-tests.md
create mode 100644 .agents/skills/tdd/references/design-descriptive-test-names.md
create mode 100644 .agents/skills/tdd/references/design-one-assertion-per-test.md
create mode 100644 .agents/skills/tdd/references/design-test-behavior-not-implementation.md
create mode 100644 .agents/skills/tdd/references/design-test-edge-cases.md
create mode 100644 .agents/skills/tdd/references/isolate-deterministic-tests.md
create mode 100644 .agents/skills/tdd/references/isolate-mock-external-dependencies.md
create mode 100644 .agents/skills/tdd/references/isolate-no-shared-state.md
create mode 100644 .agents/skills/tdd/references/isolate-prefer-stubs-over-mocks.md
create mode 100644 .agents/skills/tdd/references/isolate-use-dependency-injection.md
create mode 100644 .agents/skills/tdd/references/org-file-structure.md
create mode 100644 .agents/skills/tdd/references/org-group-by-behavior.md
create mode 100644 .agents/skills/tdd/references/org-parameterized-tests.md
create mode 100644 .agents/skills/tdd/references/org-setup-teardown.md
create mode 100644 .agents/skills/tdd/references/org-test-utilities.md
create mode 100644 .agents/skills/tdd/references/perf-avoid-network-calls.md
create mode 100644 .agents/skills/tdd/references/perf-avoid-sleep.md
create mode 100644 .agents/skills/tdd/references/perf-fast-unit-tests.md
create mode 100644 .agents/skills/tdd/references/perf-fix-flaky-tests.md
create mode 100644 .agents/skills/tdd/references/perf-parallelize-tests.md
create mode 100644 .agents/skills/tdd/references/strat-coverage-targets.md
create mode 100644 .agents/skills/tdd/references/strat-e2e-critical-paths.md
create mode 100644 .agents/skills/tdd/references/strat-integration-boundaries.md
create mode 100644 .agents/skills/tdd/references/strat-mutation-testing.md
create mode 100644 .agents/skills/tdd/references/strat-test-pyramid.md
create mode 100644 .agents/skills/typescript/SKILL.md
create mode 100644 .agents/skills/typescript/references/advanced-branded-types.md
create mode 100644 .agents/skills/typescript/references/advanced-satisfies-operator.md
create mode 100644 .agents/skills/typescript/references/advanced-template-literal-types.md
create mode 100644 .agents/skills/typescript/references/async-avoid-loop-await.md
create mode 100644 .agents/skills/typescript/references/async-avoid-unnecessary-async.md
create mode 100644 .agents/skills/typescript/references/async-defer-await.md
create mode 100644 .agents/skills/typescript/references/async-explicit-return-types.md
create mode 100644 .agents/skills/typescript/references/async-parallel-promises.md
create mode 100644 .agents/skills/typescript/references/mem-avoid-closure-leaks.md
create mode 100644 .agents/skills/typescript/references/mem-avoid-global-state.md
create mode 100644 .agents/skills/typescript/references/mem-cleanup-event-listeners.md
create mode 100644 .agents/skills/typescript/references/mem-clear-timers.md
create mode 100644 .agents/skills/typescript/references/mem-use-weakmap-for-metadata.md
create mode 100644 .agents/skills/typescript/references/module-avoid-barrel-imports.md
create mode 100644 .agents/skills/typescript/references/module-avoid-circular-dependencies.md
create mode 100644 .agents/skills/typescript/references/module-control-types-inclusion.md
create mode 100644 .agents/skills/typescript/references/module-dynamic-imports.md
create mode 100644 .agents/skills/typescript/references/module-use-type-imports.md
create mode 100644 .agents/skills/typescript/references/runtime-avoid-object-spread-in-loops.md
create mode 100644 .agents/skills/typescript/references/runtime-cache-property-access.md
create mode 100644 .agents/skills/typescript/references/runtime-prefer-array-methods.md
create mode 100644 .agents/skills/typescript/references/runtime-use-for-of-for-iteration.md
create mode 100644 .agents/skills/typescript/references/runtime-use-set-for-lookups.md
create mode 100644 .agents/skills/typescript/references/runtime-use-string-methods.md
create mode 100644 .agents/skills/typescript/references/safety-assertion-functions.md
create mode 100644 .agents/skills/typescript/references/safety-const-assertions.md
create mode 100644 .agents/skills/typescript/references/safety-exhaustive-checks.md
create mode 100644 .agents/skills/typescript/references/safety-prefer-unknown-over-any.md
create mode 100644 .agents/skills/typescript/references/safety-strict-null-checks.md
create mode 100644 .agents/skills/typescript/references/safety-use-type-guards.md
create mode 100644 .agents/skills/typescript/references/tscfg-enable-incremental.md
create mode 100644 .agents/skills/typescript/references/tscfg-exclude-properly.md
create mode 100644 .agents/skills/typescript/references/tscfg-isolate-modules.md
create mode 100644 .agents/skills/typescript/references/tscfg-project-references.md
create mode 100644 .agents/skills/typescript/references/tscfg-skip-lib-check.md
create mode 100644 .agents/skills/typescript/references/tscfg-strict-function-types.md
create mode 100644 .agents/skills/typescript/references/tscfg-typescript-7.md
create mode 100644 .agents/skills/typescript/references/type-avoid-deep-generics.md
create mode 100644 .agents/skills/typescript/references/type-avoid-large-unions.md
create mode 100644 .agents/skills/typescript/references/type-explicit-return-types.md
create mode 100644 .agents/skills/typescript/references/type-extract-conditional-types.md
create mode 100644 .agents/skills/typescript/references/type-interfaces-over-intersections.md
create mode 100644 .agents/skills/typescript/references/type-limit-recursion-depth.md
create mode 100644 .agents/skills/typescript/references/type-simplify-mapped-types.md
create mode 100644 .agents/skills/ui-design/SKILL.md
create mode 100644 .agents/skills/ui-design/references/access-alt-text.md
create mode 100644 .agents/skills/ui-design/references/access-aria-labels.md
create mode 100644 .agents/skills/ui-design/references/access-focus-indicators.md
create mode 100644 .agents/skills/ui-design/references/access-heading-hierarchy.md
create mode 100644 .agents/skills/ui-design/references/access-keyboard-navigation.md
create mode 100644 .agents/skills/ui-design/references/access-semantic-html.md
create mode 100644 .agents/skills/ui-design/references/access-target-size.md
create mode 100644 .agents/skills/ui-design/references/anim-duration-easing.md
create mode 100644 .agents/skills/ui-design/references/anim-gpu-properties.md
create mode 100644 .agents/skills/ui-design/references/anim-reduced-motion.md
create mode 100644 .agents/skills/ui-design/references/anim-will-change.md
create mode 100644 .agents/skills/ui-design/references/color-contrast-ratio.md
create mode 100644 .agents/skills/ui-design/references/color-dark-mode.md
create mode 100644 .agents/skills/ui-design/references/color-not-only-indicator.md
create mode 100644 .agents/skills/ui-design/references/color-semantic-palette.md
create mode 100644 .agents/skills/ui-design/references/cwv-critical-css.md
create mode 100644 .agents/skills/ui-design/references/cwv-improve-inp.md
create mode 100644 .agents/skills/ui-design/references/cwv-lazy-load-offscreen.md
create mode 100644 .agents/skills/ui-design/references/cwv-minimize-cls.md
create mode 100644 .agents/skills/ui-design/references/cwv-optimize-lcp.md
create mode 100644 .agents/skills/ui-design/references/cwv-responsive-images.md
create mode 100644 .agents/skills/ui-design/references/form-autocomplete.md
create mode 100644 .agents/skills/ui-design/references/form-error-messages.md
create mode 100644 .agents/skills/ui-design/references/form-inline-validation.md
create mode 100644 .agents/skills/ui-design/references/form-input-types.md
create mode 100644 .agents/skills/ui-design/references/form-labels-above.md
create mode 100644 .agents/skills/ui-design/references/layout-f-pattern.md
create mode 100644 .agents/skills/ui-design/references/layout-grid-system.md
create mode 100644 .agents/skills/ui-design/references/layout-proximity-grouping.md
create mode 100644 .agents/skills/ui-design/references/layout-single-cta.md
create mode 100644 .agents/skills/ui-design/references/layout-visual-hierarchy.md
create mode 100644 .agents/skills/ui-design/references/layout-whitespace.md
create mode 100644 .agents/skills/ui-design/references/resp-container-queries.md
create mode 100644 .agents/skills/ui-design/references/resp-fluid-typography.md
create mode 100644 .agents/skills/ui-design/references/resp-mobile-first.md
create mode 100644 .agents/skills/ui-design/references/resp-touch-targets.md
create mode 100644 .agents/skills/ui-design/references/resp-viewport-meta.md
create mode 100644 .agents/skills/ui-design/references/typo-font-display.md
create mode 100644 .agents/skills/ui-design/references/typo-line-height.md
create mode 100644 .agents/skills/ui-design/references/typo-preload-fonts.md
create mode 100644 .agents/skills/ui-design/references/typo-readable-line-length.md
create mode 100644 .agents/skills/ui-design/references/typo-system-font-stack.md
create mode 100644 .agents/skills/vercel-composition-patterns/SKILL.md
create mode 100644 .agents/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md
create mode 100644 .agents/skills/vercel-composition-patterns/rules/architecture-compound-components.md
create mode 100644 .agents/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md
create mode 100644 .agents/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md
create mode 100644 .agents/skills/vercel-composition-patterns/rules/react19-no-forwardref.md
create mode 100644 .agents/skills/vercel-composition-patterns/rules/state-context-interface.md
create mode 100644 .agents/skills/vercel-composition-patterns/rules/state-decouple-implementation.md
create mode 100644 .agents/skills/vercel-composition-patterns/rules/state-lift-state.md
create mode 100644 .agents/skills/vercel-react-best-practices/SKILL.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/advanced-init-once.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/advanced-use-latest.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-api-routes.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-defer-await.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-dependencies.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-parallel.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-conditional.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/bundle-preload.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/client-event-listeners.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/client-swr-dedup.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-cache-function-results.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-cache-property-access.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-cache-storage.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-combine-iterations.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-early-exit.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-flatmap-filter.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-index-maps.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-length-check-first.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-min-max-loop.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-request-idle-callback.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-activity.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-resource-hints.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-dependencies.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-derived-state.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-memo.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-transitions.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-auth-actions.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-cache-lru.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-cache-react.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-dedup-props.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-hoist-static-io.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md
create mode 100644 .agents/skills/vercel-react-best-practices/rules/server-serialization.md
create mode 100644 .agents/skills/vitest/SKILL.md
create mode 100644 .agents/skills/vitest/references/assert-edge-cases.md
create mode 100644 .agents/skills/vitest/references/assert-expect-assertions.md
create mode 100644 .agents/skills/vitest/references/assert-one-assertion-concept.md
create mode 100644 .agents/skills/vitest/references/assert-specific-matchers.md
create mode 100644 .agents/skills/vitest/references/assert-toequal-vs-tobe.md
create mode 100644 .agents/skills/vitest/references/async-act-wrapper.md
create mode 100644 .agents/skills/vitest/references/async-await-assertions.md
create mode 100644 .agents/skills/vitest/references/async-concurrent-expect.md
create mode 100644 .agents/skills/vitest/references/async-error-handling.md
create mode 100644 .agents/skills/vitest/references/async-fake-timers.md
create mode 100644 .agents/skills/vitest/references/async-return-promises.md
create mode 100644 .agents/skills/vitest/references/async-waitfor-polling.md
create mode 100644 .agents/skills/vitest/references/env-browser-api-mocking.md
create mode 100644 .agents/skills/vitest/references/env-globals-config.md
create mode 100644 .agents/skills/vitest/references/env-per-file-override.md
create mode 100644 .agents/skills/vitest/references/env-setup-files.md
create mode 100644 .agents/skills/vitest/references/mock-avoid-overmocking.md
create mode 100644 .agents/skills/vitest/references/mock-clear-between-tests.md
create mode 100644 .agents/skills/vitest/references/mock-implementation-not-value.md
create mode 100644 .agents/skills/vitest/references/mock-msw-network.md
create mode 100644 .agents/skills/vitest/references/mock-spyon-vs-mock.md
create mode 100644 .agents/skills/vitest/references/mock-type-safety.md
create mode 100644 .agents/skills/vitest/references/mock-vi-mock-hoisting.md
create mode 100644 .agents/skills/vitest/references/org-describe-nesting.md
create mode 100644 .agents/skills/vitest/references/org-file-colocation.md
create mode 100644 .agents/skills/vitest/references/org-test-naming.md
create mode 100644 .agents/skills/vitest/references/org-test-skip-only.md
create mode 100644 .agents/skills/vitest/references/perf-bail-fast-fail.md
create mode 100644 .agents/skills/vitest/references/perf-bench-test-context.md
create mode 100644 .agents/skills/vitest/references/perf-disable-isolation.md
create mode 100644 .agents/skills/vitest/references/perf-happy-dom.md
create mode 100644 .agents/skills/vitest/references/perf-pool-selection.md
create mode 100644 .agents/skills/vitest/references/perf-run-mode-ci.md
create mode 100644 .agents/skills/vitest/references/perf-sharding.md
create mode 100644 .agents/skills/vitest/references/setup-avoid-shared-state.md
create mode 100644 .agents/skills/vitest/references/setup-beforeall-expensive.md
create mode 100644 .agents/skills/vitest/references/setup-beforeeach-cleanup.md
create mode 100644 .agents/skills/vitest/references/setup-reset-modules.md
create mode 100644 .agents/skills/vitest/references/setup-restore-mocks.md
create mode 100644 .agents/skills/vitest/references/setup-test-factories.md
create mode 100644 .agents/skills/vitest/references/setup-vitest5-migration.md
create mode 100644 .agents/skills/vitest/references/snap-avoid-large.md
create mode 100644 .agents/skills/vitest/references/snap-describe-intent.md
create mode 100644 .agents/skills/vitest/references/snap-inline-over-file.md
create mode 100644 .agents/skills/vitest/references/snap-review-updates.md
create mode 100644 .agents/skills/vitest/references/snap-stable-serialization.md
create mode 100644 .agents/skills/web-design-guidelines/SKILL.md
create mode 100644 .agents/skills/zod/SKILL.md
create mode 100644 .agents/skills/zod/references/compose-intersection.md
create mode 100644 .agents/skills/zod/references/compose-lazy-recursive.md
create mode 100644 .agents/skills/zod/references/compose-pipe.md
create mode 100644 .agents/skills/zod/references/compose-preprocess.md
create mode 100644 .agents/skills/zod/references/compose-shared-schemas.md
create mode 100644 .agents/skills/zod/references/error-avoid-throwing-in-refine.md
create mode 100644 .agents/skills/zod/references/error-custom-messages.md
create mode 100644 .agents/skills/zod/references/error-i18n.md
create mode 100644 .agents/skills/zod/references/error-path-for-nested.md
create mode 100644 .agents/skills/zod/references/error-use-flatten.md
create mode 100644 .agents/skills/zod/references/object-discriminated-unions.md
create mode 100644 .agents/skills/zod/references/object-extend-for-composition.md
create mode 100644 .agents/skills/zod/references/object-optional-vs-nullable.md
create mode 100644 .agents/skills/zod/references/object-partial-for-updates.md
create mode 100644 .agents/skills/zod/references/object-pick-omit.md
create mode 100644 .agents/skills/zod/references/object-strict-vs-strip.md
create mode 100644 .agents/skills/zod/references/parse-async-for-async-refinements.md
create mode 100644 .agents/skills/zod/references/parse-avoid-double-validation.md
create mode 100644 .agents/skills/zod/references/parse-handle-all-issues.md
create mode 100644 .agents/skills/zod/references/parse-never-trust-json.md
create mode 100644 .agents/skills/zod/references/parse-use-safeparse.md
create mode 100644 .agents/skills/zod/references/parse-validate-early.md
create mode 100644 .agents/skills/zod/references/parse-validate-for-boolean-checks.md
create mode 100644 .agents/skills/zod/references/perf-arrays.md
create mode 100644 .agents/skills/zod/references/perf-avoid-dynamic-creation.md
create mode 100644 .agents/skills/zod/references/perf-cache-schemas.md
create mode 100644 .agents/skills/zod/references/perf-compile-schemas.md
create mode 100644 .agents/skills/zod/references/perf-lazy-loading.md
create mode 100644 .agents/skills/zod/references/perf-zod-mini.md
create mode 100644 .agents/skills/zod/references/refine-add-path.md
create mode 100644 .agents/skills/zod/references/refine-catch.md
create mode 100644 .agents/skills/zod/references/refine-defaults.md
create mode 100644 .agents/skills/zod/references/refine-transform-coerce.md
create mode 100644 .agents/skills/zod/references/refine-use-codec.md
create mode 100644 .agents/skills/zod/references/refine-vs-superrefine.md
create mode 100644 .agents/skills/zod/references/schema-avoid-optional-abuse.md
create mode 100644 .agents/skills/zod/references/schema-coercion-for-form-data.md
create mode 100644 .agents/skills/zod/references/schema-string-validations.md
create mode 100644 .agents/skills/zod/references/schema-use-enums.md
create mode 100644 .agents/skills/zod/references/schema-use-primitives-correctly.md
create mode 100644 .agents/skills/zod/references/schema-use-unknown-not-any.md
create mode 100644 .agents/skills/zod/references/type-branded-types.md
create mode 100644 .agents/skills/zod/references/type-enable-strict-mode.md
create mode 100644 .agents/skills/zod/references/type-export-schemas-and-types.md
create mode 100644 .agents/skills/zod/references/type-input-vs-output.md
create mode 100644 .agents/skills/zod/references/type-use-z-infer.md
create mode 100644 .claude/skills/feature-arch/SKILL.md
create mode 100644 .claude/skills/feature-arch/references/bound-event-based-communication.md
create mode 100644 .claude/skills/feature-arch/references/bound-feature-isolation.md
create mode 100644 .claude/skills/feature-arch/references/bound-feature-scoped-routing.md
create mode 100644 .claude/skills/feature-arch/references/bound-feature-size.md
create mode 100644 .claude/skills/feature-arch/references/bound-interface-contracts.md
create mode 100644 .claude/skills/feature-arch/references/bound-minimize-shared-state.md
create mode 100644 .claude/skills/feature-arch/references/fcomp-colocate-styles.md
create mode 100644 .claude/skills/feature-arch/references/fcomp-composition-over-props.md
create mode 100644 .claude/skills/feature-arch/references/fcomp-container-presentational.md
create mode 100644 .claude/skills/feature-arch/references/fcomp-error-boundaries.md
create mode 100644 .claude/skills/feature-arch/references/fcomp-props-as-data-boundary.md
create mode 100644 .claude/skills/feature-arch/references/fcomp-single-responsibility.md
create mode 100644 .claude/skills/feature-arch/references/fquery-avoid-n-plus-one.md
create mode 100644 .claude/skills/feature-arch/references/fquery-colocate-with-feature.md
create mode 100644 .claude/skills/feature-arch/references/fquery-feature-scoped-keys.md
create mode 100644 .claude/skills/feature-arch/references/fquery-parallel-fetching.md
create mode 100644 .claude/skills/feature-arch/references/fquery-server-component-fetching.md
create mode 100644 .claude/skills/feature-arch/references/fquery-single-responsibility.md
create mode 100644 .claude/skills/feature-arch/references/fstate-context-sparingly.md
create mode 100644 .claude/skills/feature-arch/references/fstate-feature-scoped-stores.md
create mode 100644 .claude/skills/feature-arch/references/fstate-lift-minimally.md
create mode 100644 .claude/skills/feature-arch/references/fstate-reset-on-unmount.md
create mode 100644 .claude/skills/feature-arch/references/fstate-server-state-separation.md
create mode 100644 .claude/skills/feature-arch/references/import-avoid-barrel-files.md
create mode 100644 .claude/skills/feature-arch/references/import-no-cross-feature.md
create mode 100644 .claude/skills/feature-arch/references/import-path-aliases.md
create mode 100644 .claude/skills/feature-arch/references/import-public-api.md
create mode 100644 .claude/skills/feature-arch/references/import-type-only.md
create mode 100644 .claude/skills/feature-arch/references/import-unidirectional-flow.md
create mode 100644 .claude/skills/feature-arch/references/name-descriptive-exports.md
create mode 100644 .claude/skills/feature-arch/references/name-feature-naming.md
create mode 100644 .claude/skills/feature-arch/references/name-file-conventions.md
create mode 100644 .claude/skills/feature-arch/references/struct-app-layer.md
create mode 100644 .claude/skills/feature-arch/references/struct-feature-folders.md
create mode 100644 .claude/skills/feature-arch/references/struct-feature-self-contained.md
create mode 100644 .claude/skills/feature-arch/references/struct-flat-hierarchy.md
create mode 100644 .claude/skills/feature-arch/references/struct-optional-segments.md
create mode 100644 .claude/skills/feature-arch/references/struct-shared-layer.md
create mode 100644 .claude/skills/feature-arch/references/test-colocate-with-feature.md
create mode 100644 .claude/skills/feature-arch/references/test-feature-isolation.md
create mode 100644 .claude/skills/feature-arch/references/test-integration-at-app-layer.md
create mode 100644 .claude/skills/feature-arch/references/test-shared-utilities.md
create mode 100644 .claude/skills/msw/SKILL.md
create mode 100644 .claude/skills/msw/references/advanced-bypass-requests.md
create mode 100644 .claude/skills/msw/references/advanced-cookies-auth.md
create mode 100644 .claude/skills/msw/references/advanced-dynamic-scenarios.md
create mode 100644 .claude/skills/msw/references/advanced-file-uploads.md
create mode 100644 .claude/skills/msw/references/advanced-playwright-integration.md
create mode 100644 .claude/skills/msw/references/advanced-vitest-browser.md
create mode 100644 .claude/skills/msw/references/advanced-websocket-mocking.md
create mode 100644 .claude/skills/msw/references/debug-common-issues.md
create mode 100644 .claude/skills/msw/references/debug-lifecycle-events.md
create mode 100644 .claude/skills/msw/references/debug-request-logging.md
create mode 100644 .claude/skills/msw/references/debug-verify-interception.md
create mode 100644 .claude/skills/msw/references/graphql-batched-queries.md
create mode 100644 .claude/skills/msw/references/graphql-error-responses.md
create mode 100644 .claude/skills/msw/references/graphql-operation-handlers.md
create mode 100644 .claude/skills/msw/references/graphql-schema-first.md
create mode 100644 .claude/skills/msw/references/graphql-variables-access.md
create mode 100644 .claude/skills/msw/references/handler-absolute-urls.md
create mode 100644 .claude/skills/msw/references/handler-domain-grouping.md
create mode 100644 .claude/skills/msw/references/handler-happy-path-first.md
create mode 100644 .claude/skills/msw/references/handler-request-body-parsing.md
create mode 100644 .claude/skills/msw/references/handler-resolver-argument.md
create mode 100644 .claude/skills/msw/references/handler-reusability-environments.md
create mode 100644 .claude/skills/msw/references/handler-shared-resolvers.md
create mode 100644 .claude/skills/msw/references/handler-v2-response-syntax.md
create mode 100644 .claude/skills/msw/references/match-custom-predicate.md
create mode 100644 .claude/skills/msw/references/match-handler-order.md
create mode 100644 .claude/skills/msw/references/match-http-methods.md
create mode 100644 .claude/skills/msw/references/match-query-params.md
create mode 100644 .claude/skills/msw/references/match-url-patterns.md
create mode 100644 .claude/skills/msw/references/response-custom-headers.md
create mode 100644 .claude/skills/msw/references/response-delay-realistic.md
create mode 100644 .claude/skills/msw/references/response-error-simulation.md
create mode 100644 .claude/skills/msw/references/response-http-response-helpers.md
create mode 100644 .claude/skills/msw/references/response-one-time-handlers.md
create mode 100644 .claude/skills/msw/references/response-streaming.md
create mode 100644 .claude/skills/msw/references/setup-lifecycle-hooks.md
create mode 100644 .claude/skills/msw/references/setup-node-version.md
create mode 100644 .claude/skills/msw/references/setup-server-node-entrypoint.md
create mode 100644 .claude/skills/msw/references/setup-typescript-config.md
create mode 100644 .claude/skills/msw/references/setup-unhandled-requests.md
create mode 100644 .claude/skills/msw/references/setup-worker-script-commit.md
create mode 100644 .claude/skills/msw/references/test-async-utilities.md
create mode 100644 .claude/skills/msw/references/test-avoid-request-assertions.md
create mode 100644 .claude/skills/msw/references/test-clear-request-cache.md
create mode 100644 .claude/skills/msw/references/test-concurrent-boundary.md
create mode 100644 .claude/skills/msw/references/test-fake-timers-config.md
create mode 100644 .claude/skills/msw/references/test-jsdom-environment.md
create mode 100644 .claude/skills/msw/references/test-reset-handlers.md
create mode 100644 .claude/skills/nextjs/SKILL.md
create mode 100644 .claude/skills/nextjs/references/action-error-handling.md
create mode 100644 .claude/skills/nextjs/references/action-optimistic-updates.md
create mode 100644 .claude/skills/nextjs/references/action-pending-states.md
create mode 100644 .claude/skills/nextjs/references/action-revalidation.md
create mode 100644 .claude/skills/nextjs/references/action-server-action-forms.md
create mode 100644 .claude/skills/nextjs/references/build-barrel-files.md
create mode 100644 .claude/skills/nextjs/references/build-dynamic-imports.md
create mode 100644 .claude/skills/nextjs/references/build-external-packages.md
create mode 100644 .claude/skills/nextjs/references/build-optimize-package-imports.md
create mode 100644 .claude/skills/nextjs/references/build-turbopack-config.md
create mode 100644 .claude/skills/nextjs/references/cache-fetch-options.md
create mode 100644 .claude/skills/nextjs/references/cache-react-cache.md
create mode 100644 .claude/skills/nextjs/references/cache-revalidate-path.md
create mode 100644 .claude/skills/nextjs/references/cache-revalidate-tag.md
create mode 100644 .claude/skills/nextjs/references/cache-segment-config.md
create mode 100644 .claude/skills/nextjs/references/cache-use-cache-directive.md
create mode 100644 .claude/skills/nextjs/references/client-children-pattern.md
create mode 100644 .claude/skills/nextjs/references/client-hydration-mismatch.md
create mode 100644 .claude/skills/nextjs/references/client-third-party-scripts.md
create mode 100644 .claude/skills/nextjs/references/client-use-client-boundary.md
create mode 100644 .claude/skills/nextjs/references/meta-generate-metadata.md
create mode 100644 .claude/skills/nextjs/references/meta-opengraph-images.md
create mode 100644 .claude/skills/nextjs/references/meta-robots.md
create mode 100644 .claude/skills/nextjs/references/meta-sitemap.md
create mode 100644 .claude/skills/nextjs/references/route-instant-navigations.md
create mode 100644 .claude/skills/nextjs/references/route-intercepting-routes.md
create mode 100644 .claude/skills/nextjs/references/route-not-found.md
create mode 100644 .claude/skills/nextjs/references/route-parallel-routes.md
create mode 100644 .claude/skills/nextjs/references/route-partial-prefetching.md
create mode 100644 .claude/skills/nextjs/references/route-prefetching.md
create mode 100644 .claude/skills/nextjs/references/route-proxy-ts.md
create mode 100644 .claude/skills/nextjs/references/server-avoid-client-fetching.md
create mode 100644 .claude/skills/nextjs/references/server-component-streaming.md
create mode 100644 .claude/skills/nextjs/references/server-data-colocation.md
create mode 100644 .claude/skills/nextjs/references/server-error-handling.md
create mode 100644 .claude/skills/nextjs/references/server-parallel-fetching.md
create mode 100644 .claude/skills/nextjs/references/server-preload-pattern.md
create mode 100644 .claude/skills/nextjs/references/stream-error-tsx.md
create mode 100644 .claude/skills/nextjs/references/stream-loading-tsx.md
create mode 100644 .claude/skills/nextjs/references/stream-nested-suspense.md
create mode 100644 .claude/skills/nextjs/references/stream-skeleton-matching.md
create mode 100644 .claude/skills/nextjs/references/stream-suspense-boundaries.md
create mode 100644 .claude/skills/nuqs/SKILL.md
create mode 100644 .claude/skills/nuqs/references/advanced-custom-parsers.md
create mode 100644 .claude/skills/nuqs/references/advanced-eq-function.md
create mode 100644 .claude/skills/nuqs/references/advanced-framework-adapters.md
create mode 100644 .claude/skills/nuqs/references/advanced-url-keys.md
create mode 100644 .claude/skills/nuqs/references/debug-common-errors.md
create mode 100644 .claude/skills/nuqs/references/debug-enable-logging.md
create mode 100644 .claude/skills/nuqs/references/debug-testing.md
create mode 100644 .claude/skills/nuqs/references/history-back-sync.md
create mode 100644 .claude/skills/nuqs/references/history-push-navigation.md
create mode 100644 .claude/skills/nuqs/references/history-replace-ephemeral.md
create mode 100644 .claude/skills/nuqs/references/history-scroll-behavior.md
create mode 100644 .claude/skills/nuqs/references/parser-array-format.md
create mode 100644 .claude/skills/nuqs/references/parser-date-format.md
create mode 100644 .claude/skills/nuqs/references/parser-enum-validation.md
create mode 100644 .claude/skills/nuqs/references/parser-hex-colors.md
create mode 100644 .claude/skills/nuqs/references/parser-index-offset.md
create mode 100644 .claude/skills/nuqs/references/parser-json-validation.md
create mode 100644 .claude/skills/nuqs/references/parser-use-typed-parsers.md
create mode 100644 .claude/skills/nuqs/references/parser-with-default.md
create mode 100644 .claude/skills/nuqs/references/perf-avoid-rerender.md
create mode 100644 .claude/skills/nuqs/references/perf-clear-on-default.md
create mode 100644 .claude/skills/nuqs/references/perf-debounce-search.md
create mode 100644 .claude/skills/nuqs/references/perf-serialize-utility.md
create mode 100644 .claude/skills/nuqs/references/perf-throttle-updates.md
create mode 100644 .claude/skills/nuqs/references/server-next15-async.md
create mode 100644 .claude/skills/nuqs/references/server-parse-before-get.md
create mode 100644 .claude/skills/nuqs/references/server-search-params-cache.md
create mode 100644 .claude/skills/nuqs/references/server-shallow-false.md
create mode 100644 .claude/skills/nuqs/references/server-share-parsers.md
create mode 100644 .claude/skills/nuqs/references/server-use-transition.md
create mode 100644 .claude/skills/nuqs/references/setup-import-server.md
create mode 100644 .claude/skills/nuqs/references/setup-nextjs-version.md
create mode 100644 .claude/skills/nuqs/references/setup-nuqs-adapter.md
create mode 100644 .claude/skills/nuqs/references/setup-shared-parsers.md
create mode 100644 .claude/skills/nuqs/references/setup-use-client.md
create mode 100644 .claude/skills/nuqs/references/state-avoid-derived.md
create mode 100644 .claude/skills/nuqs/references/state-clear-with-null.md
create mode 100644 .claude/skills/nuqs/references/state-controlled-inputs.md
create mode 100644 .claude/skills/nuqs/references/state-functional-updates.md
create mode 100644 .claude/skills/nuqs/references/state-options-inheritance.md
create mode 100644 .claude/skills/nuqs/references/state-setter-return.md
create mode 100644 .claude/skills/nuqs/references/state-use-query-states.md
create mode 100644 .claude/skills/playwright/SKILL.md
create mode 100644 .claude/skills/playwright/references/arch-cleanup-state.md
create mode 100644 .claude/skills/playwright/references/arch-fixtures.md
create mode 100644 .claude/skills/playwright/references/arch-page-object-model.md
create mode 100644 .claude/skills/playwright/references/arch-parallel-execution.md
create mode 100644 .claude/skills/playwright/references/arch-test-isolation.md
create mode 100644 .claude/skills/playwright/references/arch-test-production.md
create mode 100644 .claude/skills/playwright/references/assert-aria-snapshots.md
create mode 100644 .claude/skills/playwright/references/auth-api-login.md
create mode 100644 .claude/skills/playwright/references/auth-multiple-roles.md
create mode 100644 .claude/skills/playwright/references/auth-parallel-workers.md
create mode 100644 .claude/skills/playwright/references/auth-session-storage.md
create mode 100644 .claude/skills/playwright/references/auth-storage-state.md
create mode 100644 .claude/skills/playwright/references/debug-ci-reporters.md
create mode 100644 .claude/skills/playwright/references/debug-inspector.md
create mode 100644 .claude/skills/playwright/references/debug-screenshots-videos.md
create mode 100644 .claude/skills/playwright/references/debug-trace-viewer.md
create mode 100644 .claude/skills/playwright/references/loc-avoid-xpath.md
create mode 100644 .claude/skills/playwright/references/loc-chained-locators.md
create mode 100644 .claude/skills/playwright/references/loc-data-testid.md
create mode 100644 .claude/skills/playwright/references/loc-frame-locator.md
create mode 100644 .claude/skills/playwright/references/loc-label-selectors.md
create mode 100644 .claude/skills/playwright/references/loc-placeholder-selector.md
create mode 100644 .claude/skills/playwright/references/loc-role-selectors.md
create mode 100644 .claude/skills/playwright/references/loc-text-selectors.md
create mode 100644 .claude/skills/playwright/references/mock-abort-requests.md
create mode 100644 .claude/skills/playwright/references/mock-api-responses.md
create mode 100644 .claude/skills/playwright/references/mock-har-files.md
create mode 100644 .claude/skills/playwright/references/mock-intercept-modify.md
create mode 100644 .claude/skills/playwright/references/mock-network-conditions.md
create mode 100644 .claude/skills/playwright/references/next-app-router-navigation.md
create mode 100644 .claude/skills/playwright/references/next-baseurl-config.md
create mode 100644 .claude/skills/playwright/references/next-server-actions.md
create mode 100644 .claude/skills/playwright/references/next-server-components.md
create mode 100644 .claude/skills/playwright/references/next-wait-hydration.md
create mode 100644 .claude/skills/playwright/references/perf-browser-selection.md
create mode 100644 .claude/skills/playwright/references/perf-headless-ci.md
create mode 100644 .claude/skills/playwright/references/perf-retries.md
create mode 100644 .claude/skills/playwright/references/perf-reuse-server.md
create mode 100644 .claude/skills/playwright/references/perf-sharding.md
create mode 100644 .claude/skills/playwright/references/wait-action-retries.md
create mode 100644 .claude/skills/playwright/references/wait-avoid-hard-waits.md
create mode 100644 .claude/skills/playwright/references/wait-custom-timeout.md
create mode 100644 .claude/skills/playwright/references/wait-network-idle.md
create mode 100644 .claude/skills/playwright/references/wait-soft-assertions.md
create mode 100644 .claude/skills/playwright/references/wait-web-first-assertions.md
create mode 100644 .claude/skills/react-hook-form/SKILL.md
create mode 100644 .claude/skills/react-hook-form/references/adv-devtools-performance.md
create mode 100644 .claude/skills/react-hook-form/references/adv-formprovider-memo.md
create mode 100644 .claude/skills/react-hook-form/references/adv-opaque-types.md
create mode 100644 .claude/skills/react-hook-form/references/adv-testing-wrapper.md
create mode 100644 .claude/skills/react-hook-form/references/array-complete-default-objects.md
create mode 100644 .claude/skills/react-hook-form/references/array-separate-crud-operations.md
create mode 100644 .claude/skills/react-hook-form/references/array-unique-fieldarray-per-name.md
create mode 100644 .claude/skills/react-hook-form/references/array-use-field-id-as-key.md
create mode 100644 .claude/skills/react-hook-form/references/array-virtualization-formprovider.md
create mode 100644 .claude/skills/react-hook-form/references/ctrl-avoid-double-registration.md
create mode 100644 .claude/skills/react-hook-form/references/ctrl-controller-field-props.md
create mode 100644 .claude/skills/react-hook-form/references/ctrl-local-state-combination.md
create mode 100644 .claude/skills/react-hook-form/references/ctrl-single-usecontroller-per-component.md
create mode 100644 .claude/skills/react-hook-form/references/ctrl-usecontroller-isolation.md
create mode 100644 .claude/skills/react-hook-form/references/formcfg-async-default-values.md
create mode 100644 .claude/skills/react-hook-form/references/formcfg-default-values.md
create mode 100644 .claude/skills/react-hook-form/references/formcfg-revalidate-mode.md
create mode 100644 .claude/skills/react-hook-form/references/formcfg-should-unregister.md
create mode 100644 .claude/skills/react-hook-form/references/formcfg-useeffect-dependency.md
create mode 100644 .claude/skills/react-hook-form/references/formcfg-validation-mode.md
create mode 100644 .claude/skills/react-hook-form/references/formstate-avoid-isvalid-with-onsubmit.md
create mode 100644 .claude/skills/react-hook-form/references/formstate-destructure-formstate.md
create mode 100644 .claude/skills/react-hook-form/references/formstate-getfieldstate-for-single-field.md
create mode 100644 .claude/skills/react-hook-form/references/formstate-subscribe-to-specific-fields.md
create mode 100644 .claude/skills/react-hook-form/references/formstate-useformstate-isolation.md
create mode 100644 .claude/skills/react-hook-form/references/integ-mui-controller-pattern.md
create mode 100644 .claude/skills/react-hook-form/references/integ-shadcn-form-import.md
create mode 100644 .claude/skills/react-hook-form/references/integ-shadcn-select-wiring.md
create mode 100644 .claude/skills/react-hook-form/references/integ-typed-submit-server-action.md
create mode 100644 .claude/skills/react-hook-form/references/integ-value-transform.md
create mode 100644 .claude/skills/react-hook-form/references/sub-avoid-watch-in-render.md
create mode 100644 .claude/skills/react-hook-form/references/sub-deep-subscription.md
create mode 100644 .claude/skills/react-hook-form/references/sub-useformcontext-sparingly.md
create mode 100644 .claude/skills/react-hook-form/references/sub-usewatch-default-value.md
create mode 100644 .claude/skills/react-hook-form/references/sub-usewatch-over-watch.md
create mode 100644 .claude/skills/react-hook-form/references/sub-usewatch-with-getvalues.md
create mode 100644 .claude/skills/react-hook-form/references/sub-watch-specific-fields.md
create mode 100644 .claude/skills/react-hook-form/references/valid-delay-error.md
create mode 100644 .claude/skills/react-hook-form/references/valid-dynamic-schema-factory.md
create mode 100644 .claude/skills/react-hook-form/references/valid-error-message-strategy.md
create mode 100644 .claude/skills/react-hook-form/references/valid-form-level-validate.md
create mode 100644 .claude/skills/react-hook-form/references/valid-inline-vs-resolver.md
create mode 100644 .claude/skills/react-hook-form/references/valid-native-validation.md
create mode 100644 .claude/skills/react-hook-form/references/valid-resolver-caching.md
create mode 100644 .claude/skills/react-hook-form/references/valid-trigger-should-touch.md
create mode 100644 .claude/skills/react/SKILL.md
create mode 100644 .claude/skills/react/references/_sections.md
create mode 100644 .claude/skills/react/references/conc-automatic-batching.md
create mode 100644 .claude/skills/react/references/conc-concurrent-safe.md
create mode 100644 .claude/skills/react/references/conc-suspense-fallback.md
create mode 100644 .claude/skills/react/references/conc-use-deferred-value.md
create mode 100644 .claude/skills/react/references/conc-use-transition.md
create mode 100644 .claude/skills/react/references/conc-view-transitions.md
create mode 100644 .claude/skills/react/references/data-cache-deduplication.md
create mode 100644 .claude/skills/react/references/data-error-boundaries.md
create mode 100644 .claude/skills/react/references/data-parallel-fetching.md
create mode 100644 .claude/skills/react/references/data-suspense-data-fetching.md
create mode 100644 .claude/skills/react/references/data-use-hook.md
create mode 100644 .claude/skills/react/references/effect-avoid-unnecessary.md
create mode 100644 .claude/skills/react/references/effect-cleanup.md
create mode 100644 .claude/skills/react/references/effect-object-dependencies.md
create mode 100644 .claude/skills/react/references/effect-use-browser-only.md
create mode 100644 .claude/skills/react/references/effect-use-effect-event.md
create mode 100644 .claude/skills/react/references/effect-use-sync-external-store.md
create mode 100644 .claude/skills/react/references/form-actions.md
create mode 100644 .claude/skills/react/references/form-use-action-state.md
create mode 100644 .claude/skills/react/references/form-use-form-status.md
create mode 100644 .claude/skills/react/references/form-use-optimistic.md
create mode 100644 .claude/skills/react/references/form-validation.md
create mode 100644 .claude/skills/react/references/memo-avoid-premature.md
create mode 100644 .claude/skills/react/references/memo-compiler.md
create mode 100644 .claude/skills/react/references/memo-react-memo.md
create mode 100644 .claude/skills/react/references/memo-use-callback.md
create mode 100644 .claude/skills/react/references/memo-use-memo.md
create mode 100644 .claude/skills/react/references/rcomp-composition.md
create mode 100644 .claude/skills/react/references/rcomp-controlled-components.md
create mode 100644 .claude/skills/react/references/rcomp-fragment-refs.md
create mode 100644 .claude/skills/react/references/rcomp-key-reset.md
create mode 100644 .claude/skills/react/references/rcomp-render-props.md
create mode 100644 .claude/skills/react/references/rsc-avoid-client-only-libs.md
create mode 100644 .claude/skills/react/references/rsc-composition-pattern.md
create mode 100644 .claude/skills/react/references/rsc-context-provider.md
create mode 100644 .claude/skills/react/references/rsc-data-fetching-server.md
create mode 100644 .claude/skills/react/references/rsc-serializable-props.md
create mode 100644 .claude/skills/react/references/rsc-server-client-boundary.md
create mode 100644 .claude/skills/react/references/rsc-streaming.md
create mode 100644 .claude/skills/react/references/rstate-context-optimization.md
create mode 100644 .claude/skills/react/references/rstate-derived-values.md
create mode 100644 .claude/skills/react/references/rstate-functional-updates.md
create mode 100644 .claude/skills/react/references/rstate-lazy-initialization.md
create mode 100644 .claude/skills/react/references/rstate-use-reducer.md
create mode 100644 .claude/skills/shadcn/SKILL.md
create mode 100644 .claude/skills/shadcn/references/ally-ensure-color-contrast.md
create mode 100644 .claude/skills/shadcn/references/ally-maintain-focus-management.md
create mode 100644 .claude/skills/shadcn/references/ally-preserve-aria-attributes.md
create mode 100644 .claude/skills/shadcn/references/ally-preserve-keyboard-navigation.md
create mode 100644 .claude/skills/shadcn/references/ally-provide-sr-only-labels.md
create mode 100644 .claude/skills/shadcn/references/arch-current-cli-registry.md
create mode 100644 .claude/skills/shadcn/references/arch-extend-variants-with-cva.md
create mode 100644 .claude/skills/shadcn/references/arch-forward-refs-for-composable-components.md
create mode 100644 .claude/skills/shadcn/references/arch-isolate-component-variants.md
create mode 100644 .claude/skills/shadcn/references/arch-preserve-radix-primitive-structure.md
create mode 100644 .claude/skills/shadcn/references/arch-unified-radix-package.md
create mode 100644 .claude/skills/shadcn/references/arch-use-asChild-for-custom-triggers.md
create mode 100644 .claude/skills/shadcn/references/arch-use-cn-for-class-merging.md
create mode 100644 .claude/skills/shadcn/references/comp-combine-command-with-popover.md
create mode 100644 .claude/skills/shadcn/references/comp-compose-with-compound-components.md
create mode 100644 .claude/skills/shadcn/references/comp-create-reusable-form-fields.md
create mode 100644 .claude/skills/shadcn/references/comp-nest-dialogs-correctly.md
create mode 100644 .claude/skills/shadcn/references/comp-use-drawer-for-mobile-modals.md
create mode 100644 .claude/skills/shadcn/references/comp-use-slot-pattern-for-flexibility.md
create mode 100644 .claude/skills/shadcn/references/data-empty-states-with-guidance.md
create mode 100644 .claude/skills/shadcn/references/data-paginate-server-side.md
create mode 100644 .claude/skills/shadcn/references/data-use-skeleton-loading-states.md
create mode 100644 .claude/skills/shadcn/references/data-use-tanstack-table-for-complex-tables.md
create mode 100644 .claude/skills/shadcn/references/data-virtualize-large-lists.md
create mode 100644 .claude/skills/shadcn/references/form-handle-async-validation.md
create mode 100644 .claude/skills/shadcn/references/form-reset-form-state-correctly.md
create mode 100644 .claude/skills/shadcn/references/form-show-validation-errors-correctly.md
create mode 100644 .claude/skills/shadcn/references/form-use-react-hook-form-integration.md
create mode 100644 .claude/skills/shadcn/references/form-use-zod-for-schema-validation.md
create mode 100644 .claude/skills/shadcn/references/perf-avoid-unnecessary-rerenders-in-forms.md
create mode 100644 .claude/skills/shadcn/references/perf-debounce-search-inputs.md
create mode 100644 .claude/skills/shadcn/references/perf-lazy-load-heavy-components.md
create mode 100644 .claude/skills/shadcn/references/perf-memoize-expensive-renders.md
create mode 100644 .claude/skills/shadcn/references/perf-optimize-icon-imports.md
create mode 100644 .claude/skills/shadcn/references/state-colocate-state-with-components.md
create mode 100644 .claude/skills/shadcn/references/state-lift-state-to-appropriate-level.md
create mode 100644 .claude/skills/shadcn/references/state-prefer-uncontrolled-for-simple-inputs.md
create mode 100644 .claude/skills/shadcn/references/state-use-controlled-dialog-state.md
create mode 100644 .claude/skills/shadcn/references/style-avoid-important-overrides.md
create mode 100644 .claude/skills/shadcn/references/style-consistent-spacing-scale.md
create mode 100644 .claude/skills/shadcn/references/style-dark-mode-support.md
create mode 100644 .claude/skills/shadcn/references/style-responsive-design-patterns.md
create mode 100644 .claude/skills/shadcn/references/style-use-css-variables-for-theming.md
create mode 100644 .claude/skills/shadcn/references/style-use-tailwind-theme-extend.md
create mode 100644 .claude/skills/tailwind/SKILL.md
create mode 100644 .claude/skills/tailwind/references/anim-3d-transforms.md
create mode 100644 .claude/skills/tailwind/references/anim-gpu-accelerated.md
create mode 100644 .claude/skills/tailwind/references/anim-gradient-interpolation.md
create mode 100644 .claude/skills/tailwind/references/anim-starting-style.md
create mode 100644 .claude/skills/tailwind/references/build-cli-package.md
create mode 100644 .claude/skills/tailwind/references/build-content-detection.md
create mode 100644 .claude/skills/tailwind/references/build-css-import.md
create mode 100644 .claude/skills/tailwind/references/build-node-version.md
create mode 100644 .claude/skills/tailwind/references/build-postcss-simplify.md
create mode 100644 .claude/skills/tailwind/references/build-vite-plugin.md
create mode 100644 .claude/skills/tailwind/references/bundle-avoid-cdn-production.md
create mode 100644 .claude/skills/tailwind/references/bundle-avoid-preprocessors.md
create mode 100644 .claude/skills/tailwind/references/bundle-css-minification.md
create mode 100644 .claude/skills/tailwind/references/bundle-remove-unused-plugins.md
create mode 100644 .claude/skills/tailwind/references/bundle-split-critical-css.md
create mode 100644 .claude/skills/tailwind/references/comp-avoid-apply-overuse.md
create mode 100644 .claude/skills/tailwind/references/comp-container-customize.md
create mode 100644 .claude/skills/tailwind/references/comp-reference-directive.md
create mode 100644 .claude/skills/tailwind/references/comp-smart-sorting.md
create mode 100644 .claude/skills/tailwind/references/comp-utility-file-scope.md
create mode 100644 .claude/skills/tailwind/references/gen-avoid-theme-bloat.md
create mode 100644 .claude/skills/tailwind/references/gen-css-first-config.md
create mode 100644 .claude/skills/tailwind/references/gen-css-variable-syntax.md
create mode 100644 .claude/skills/tailwind/references/gen-dynamic-utilities.md
create mode 100644 .claude/skills/tailwind/references/gen-oklch-colors.md
create mode 100644 .claude/skills/tailwind/references/gen-utility-directive.md
create mode 100644 .claude/skills/tailwind/references/resp-container-queries.md
create mode 100644 .claude/skills/tailwind/references/resp-custom-breakpoints.md
create mode 100644 .claude/skills/tailwind/references/resp-hover-capability.md
create mode 100644 .claude/skills/tailwind/references/resp-logical-properties.md
create mode 100644 .claude/skills/tailwind/references/resp-mobile-first.md
create mode 100644 .claude/skills/tailwind/references/theme-color-scheme.md
create mode 100644 .claude/skills/tailwind/references/theme-dark-mode-class.md
create mode 100644 .claude/skills/tailwind/references/theme-prefix-variables.md
create mode 100644 .claude/skills/tailwind/references/theme-runtime-variables.md
create mode 100644 .claude/skills/tailwind/references/theme-semantic-tokens.md
create mode 100644 .claude/skills/tailwind/references/util-explicit-colors.md
create mode 100644 .claude/skills/tailwind/references/util-gradient-via-none.md
create mode 100644 .claude/skills/tailwind/references/util-important-modifier.md
create mode 100644 .claude/skills/tailwind/references/util-opacity-modifier.md
create mode 100644 .claude/skills/tailwind/references/util-renamed-utilities.md
create mode 100644 .claude/skills/tailwind/references/util-variant-stacking.md
create mode 100644 .claude/skills/tanstack-query/SKILL.md
create mode 100644 .claude/skills/tanstack-query/references/cache-enabled-option.md
create mode 100644 .claude/skills/tanstack-query/references/cache-global-defaults.md
create mode 100644 .claude/skills/tanstack-query/references/cache-invalidation-precision.md
create mode 100644 .claude/skills/tanstack-query/references/cache-placeholder-vs-initial.md
create mode 100644 .claude/skills/tanstack-query/references/cache-refetch-triggers.md
create mode 100644 .claude/skills/tanstack-query/references/cache-staletime-gctime.md
create mode 100644 .claude/skills/tanstack-query/references/error-conditional-retry.md
create mode 100644 .claude/skills/tanstack-query/references/error-display-patterns.md
create mode 100644 .claude/skills/tanstack-query/references/error-global-handler.md
create mode 100644 .claude/skills/tanstack-query/references/error-retry-config.md
create mode 100644 .claude/skills/tanstack-query/references/error-throw-on-error.md
create mode 100644 .claude/skills/tanstack-query/references/infinite-flatten-pages.md
create mode 100644 .claude/skills/tanstack-query/references/infinite-loading-states.md
create mode 100644 .claude/skills/tanstack-query/references/infinite-max-pages.md
create mode 100644 .claude/skills/tanstack-query/references/infinite-refetch-behavior.md
create mode 100644 .claude/skills/tanstack-query/references/mutation-avoid-parallel.md
create mode 100644 .claude/skills/tanstack-query/references/mutation-cancel-queries.md
create mode 100644 .claude/skills/tanstack-query/references/mutation-invalidate-onsettled.md
create mode 100644 .claude/skills/tanstack-query/references/mutation-optimistic-updates.md
create mode 100644 .claude/skills/tanstack-query/references/mutation-setquerydata.md
create mode 100644 .claude/skills/tanstack-query/references/prefetch-avoid-waterfalls.md
create mode 100644 .claude/skills/tanstack-query/references/prefetch-flatten-api.md
create mode 100644 .claude/skills/tanstack-query/references/prefetch-in-queryfn.md
create mode 100644 .claude/skills/tanstack-query/references/prefetch-infinite-query.md
create mode 100644 .claude/skills/tanstack-query/references/prefetch-on-hover.md
create mode 100644 .claude/skills/tanstack-query/references/prefetch-server-components.md
create mode 100644 .claude/skills/tanstack-query/references/render-notify-props.md
create mode 100644 .claude/skills/tanstack-query/references/render-select-derived.md
create mode 100644 .claude/skills/tanstack-query/references/render-select-memoize.md
create mode 100644 .claude/skills/tanstack-query/references/render-structural-sharing.md
create mode 100644 .claude/skills/tanstack-query/references/render-tracked-props.md
create mode 100644 .claude/skills/tanstack-query/references/suspense-boundaries-placement.md
create mode 100644 .claude/skills/tanstack-query/references/suspense-error-boundaries.md
create mode 100644 .claude/skills/tanstack-query/references/suspense-parallel-queries.md
create mode 100644 .claude/skills/tanstack-query/references/suspense-use-suspense-hooks.md
create mode 100644 .claude/skills/tanstack-query/references/tquery-always-arrays.md
create mode 100644 .claude/skills/tanstack-query/references/tquery-colocate-keys.md
create mode 100644 .claude/skills/tanstack-query/references/tquery-hierarchical-keys.md
create mode 100644 .claude/skills/tanstack-query/references/tquery-key-factories.md
create mode 100644 .claude/skills/tanstack-query/references/tquery-options-pattern.md
create mode 100644 .claude/skills/tanstack-query/references/tquery-serializable-objects.md
create mode 100644 .claude/skills/tdd/SKILL.md
create mode 100644 .claude/skills/tdd/references/assert-custom-matchers.md
create mode 100644 .claude/skills/tdd/references/assert-error-messages.md
create mode 100644 .claude/skills/tdd/references/assert-no-assertions-antipattern.md
create mode 100644 .claude/skills/tdd/references/assert-snapshot-testing.md
create mode 100644 .claude/skills/tdd/references/assert-specific-assertions.md
create mode 100644 .claude/skills/tdd/references/cycle-maintain-test-list.md
create mode 100644 .claude/skills/tdd/references/cycle-minimal-code-to-pass.md
create mode 100644 .claude/skills/tdd/references/cycle-refactor-after-green.md
create mode 100644 .claude/skills/tdd/references/cycle-small-increments.md
create mode 100644 .claude/skills/tdd/references/cycle-verify-test-fails-first.md
create mode 100644 .claude/skills/tdd/references/cycle-write-test-first.md
create mode 100644 .claude/skills/tdd/references/data-avoid-mystery-guests.md
create mode 100644 .claude/skills/tdd/references/data-builder-pattern.md
create mode 100644 .claude/skills/tdd/references/data-minimal-setup.md
create mode 100644 .claude/skills/tdd/references/data-unique-identifiers.md
create mode 100644 .claude/skills/tdd/references/data-use-factories.md
create mode 100644 .claude/skills/tdd/references/design-aaa-pattern.md
create mode 100644 .claude/skills/tdd/references/design-avoid-logic-in-tests.md
create mode 100644 .claude/skills/tdd/references/design-descriptive-test-names.md
create mode 100644 .claude/skills/tdd/references/design-one-assertion-per-test.md
create mode 100644 .claude/skills/tdd/references/design-test-behavior-not-implementation.md
create mode 100644 .claude/skills/tdd/references/design-test-edge-cases.md
create mode 100644 .claude/skills/tdd/references/isolate-deterministic-tests.md
create mode 100644 .claude/skills/tdd/references/isolate-mock-external-dependencies.md
create mode 100644 .claude/skills/tdd/references/isolate-no-shared-state.md
create mode 100644 .claude/skills/tdd/references/isolate-prefer-stubs-over-mocks.md
create mode 100644 .claude/skills/tdd/references/isolate-use-dependency-injection.md
create mode 100644 .claude/skills/tdd/references/org-file-structure.md
create mode 100644 .claude/skills/tdd/references/org-group-by-behavior.md
create mode 100644 .claude/skills/tdd/references/org-parameterized-tests.md
create mode 100644 .claude/skills/tdd/references/org-setup-teardown.md
create mode 100644 .claude/skills/tdd/references/org-test-utilities.md
create mode 100644 .claude/skills/tdd/references/perf-avoid-network-calls.md
create mode 100644 .claude/skills/tdd/references/perf-avoid-sleep.md
create mode 100644 .claude/skills/tdd/references/perf-fast-unit-tests.md
create mode 100644 .claude/skills/tdd/references/perf-fix-flaky-tests.md
create mode 100644 .claude/skills/tdd/references/perf-parallelize-tests.md
create mode 100644 .claude/skills/tdd/references/strat-coverage-targets.md
create mode 100644 .claude/skills/tdd/references/strat-e2e-critical-paths.md
create mode 100644 .claude/skills/tdd/references/strat-integration-boundaries.md
create mode 100644 .claude/skills/tdd/references/strat-mutation-testing.md
create mode 100644 .claude/skills/tdd/references/strat-test-pyramid.md
create mode 100644 .claude/skills/typescript/SKILL.md
create mode 100644 .claude/skills/typescript/references/advanced-branded-types.md
create mode 100644 .claude/skills/typescript/references/advanced-satisfies-operator.md
create mode 100644 .claude/skills/typescript/references/advanced-template-literal-types.md
create mode 100644 .claude/skills/typescript/references/async-avoid-loop-await.md
create mode 100644 .claude/skills/typescript/references/async-avoid-unnecessary-async.md
create mode 100644 .claude/skills/typescript/references/async-defer-await.md
create mode 100644 .claude/skills/typescript/references/async-explicit-return-types.md
create mode 100644 .claude/skills/typescript/references/async-parallel-promises.md
create mode 100644 .claude/skills/typescript/references/mem-avoid-closure-leaks.md
create mode 100644 .claude/skills/typescript/references/mem-avoid-global-state.md
create mode 100644 .claude/skills/typescript/references/mem-cleanup-event-listeners.md
create mode 100644 .claude/skills/typescript/references/mem-clear-timers.md
create mode 100644 .claude/skills/typescript/references/mem-use-weakmap-for-metadata.md
create mode 100644 .claude/skills/typescript/references/module-avoid-barrel-imports.md
create mode 100644 .claude/skills/typescript/references/module-avoid-circular-dependencies.md
create mode 100644 .claude/skills/typescript/references/module-control-types-inclusion.md
create mode 100644 .claude/skills/typescript/references/module-dynamic-imports.md
create mode 100644 .claude/skills/typescript/references/module-use-type-imports.md
create mode 100644 .claude/skills/typescript/references/runtime-avoid-object-spread-in-loops.md
create mode 100644 .claude/skills/typescript/references/runtime-cache-property-access.md
create mode 100644 .claude/skills/typescript/references/runtime-prefer-array-methods.md
create mode 100644 .claude/skills/typescript/references/runtime-use-for-of-for-iteration.md
create mode 100644 .claude/skills/typescript/references/runtime-use-set-for-lookups.md
create mode 100644 .claude/skills/typescript/references/runtime-use-string-methods.md
create mode 100644 .claude/skills/typescript/references/safety-assertion-functions.md
create mode 100644 .claude/skills/typescript/references/safety-const-assertions.md
create mode 100644 .claude/skills/typescript/references/safety-exhaustive-checks.md
create mode 100644 .claude/skills/typescript/references/safety-prefer-unknown-over-any.md
create mode 100644 .claude/skills/typescript/references/safety-strict-null-checks.md
create mode 100644 .claude/skills/typescript/references/safety-use-type-guards.md
create mode 100644 .claude/skills/typescript/references/tscfg-enable-incremental.md
create mode 100644 .claude/skills/typescript/references/tscfg-exclude-properly.md
create mode 100644 .claude/skills/typescript/references/tscfg-isolate-modules.md
create mode 100644 .claude/skills/typescript/references/tscfg-project-references.md
create mode 100644 .claude/skills/typescript/references/tscfg-skip-lib-check.md
create mode 100644 .claude/skills/typescript/references/tscfg-strict-function-types.md
create mode 100644 .claude/skills/typescript/references/tscfg-typescript-7.md
create mode 100644 .claude/skills/typescript/references/type-avoid-deep-generics.md
create mode 100644 .claude/skills/typescript/references/type-avoid-large-unions.md
create mode 100644 .claude/skills/typescript/references/type-explicit-return-types.md
create mode 100644 .claude/skills/typescript/references/type-extract-conditional-types.md
create mode 100644 .claude/skills/typescript/references/type-interfaces-over-intersections.md
create mode 100644 .claude/skills/typescript/references/type-limit-recursion-depth.md
create mode 100644 .claude/skills/typescript/references/type-simplify-mapped-types.md
create mode 100644 .claude/skills/ui-design/SKILL.md
create mode 100644 .claude/skills/ui-design/references/access-alt-text.md
create mode 100644 .claude/skills/ui-design/references/access-aria-labels.md
create mode 100644 .claude/skills/ui-design/references/access-focus-indicators.md
create mode 100644 .claude/skills/ui-design/references/access-heading-hierarchy.md
create mode 100644 .claude/skills/ui-design/references/access-keyboard-navigation.md
create mode 100644 .claude/skills/ui-design/references/access-semantic-html.md
create mode 100644 .claude/skills/ui-design/references/access-target-size.md
create mode 100644 .claude/skills/ui-design/references/anim-duration-easing.md
create mode 100644 .claude/skills/ui-design/references/anim-gpu-properties.md
create mode 100644 .claude/skills/ui-design/references/anim-reduced-motion.md
create mode 100644 .claude/skills/ui-design/references/anim-will-change.md
create mode 100644 .claude/skills/ui-design/references/color-contrast-ratio.md
create mode 100644 .claude/skills/ui-design/references/color-dark-mode.md
create mode 100644 .claude/skills/ui-design/references/color-not-only-indicator.md
create mode 100644 .claude/skills/ui-design/references/color-semantic-palette.md
create mode 100644 .claude/skills/ui-design/references/cwv-critical-css.md
create mode 100644 .claude/skills/ui-design/references/cwv-improve-inp.md
create mode 100644 .claude/skills/ui-design/references/cwv-lazy-load-offscreen.md
create mode 100644 .claude/skills/ui-design/references/cwv-minimize-cls.md
create mode 100644 .claude/skills/ui-design/references/cwv-optimize-lcp.md
create mode 100644 .claude/skills/ui-design/references/cwv-responsive-images.md
create mode 100644 .claude/skills/ui-design/references/form-autocomplete.md
create mode 100644 .claude/skills/ui-design/references/form-error-messages.md
create mode 100644 .claude/skills/ui-design/references/form-inline-validation.md
create mode 100644 .claude/skills/ui-design/references/form-input-types.md
create mode 100644 .claude/skills/ui-design/references/form-labels-above.md
create mode 100644 .claude/skills/ui-design/references/layout-f-pattern.md
create mode 100644 .claude/skills/ui-design/references/layout-grid-system.md
create mode 100644 .claude/skills/ui-design/references/layout-proximity-grouping.md
create mode 100644 .claude/skills/ui-design/references/layout-single-cta.md
create mode 100644 .claude/skills/ui-design/references/layout-visual-hierarchy.md
create mode 100644 .claude/skills/ui-design/references/layout-whitespace.md
create mode 100644 .claude/skills/ui-design/references/resp-container-queries.md
create mode 100644 .claude/skills/ui-design/references/resp-fluid-typography.md
create mode 100644 .claude/skills/ui-design/references/resp-mobile-first.md
create mode 100644 .claude/skills/ui-design/references/resp-touch-targets.md
create mode 100644 .claude/skills/ui-design/references/resp-viewport-meta.md
create mode 100644 .claude/skills/ui-design/references/typo-font-display.md
create mode 100644 .claude/skills/ui-design/references/typo-line-height.md
create mode 100644 .claude/skills/ui-design/references/typo-preload-fonts.md
create mode 100644 .claude/skills/ui-design/references/typo-readable-line-length.md
create mode 100644 .claude/skills/ui-design/references/typo-system-font-stack.md
create mode 100644 .claude/skills/vercel-composition-patterns/SKILL.md
create mode 100644 .claude/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md
create mode 100644 .claude/skills/vercel-composition-patterns/rules/architecture-compound-components.md
create mode 100644 .claude/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md
create mode 100644 .claude/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md
create mode 100644 .claude/skills/vercel-composition-patterns/rules/react19-no-forwardref.md
create mode 100644 .claude/skills/vercel-composition-patterns/rules/state-context-interface.md
create mode 100644 .claude/skills/vercel-composition-patterns/rules/state-decouple-implementation.md
create mode 100644 .claude/skills/vercel-composition-patterns/rules/state-lift-state.md
create mode 100644 .claude/skills/vercel-react-best-practices/SKILL.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/advanced-init-once.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/advanced-use-latest.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-api-routes.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-defer-await.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-dependencies.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-parallel.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-conditional.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/bundle-preload.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/client-event-listeners.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/client-swr-dedup.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-cache-function-results.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-cache-property-access.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-cache-storage.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-combine-iterations.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-early-exit.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-flatmap-filter.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-index-maps.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-length-check-first.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-min-max-loop.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-request-idle-callback.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-activity.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-resource-hints.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-dependencies.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-derived-state.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-memo.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-transitions.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-auth-actions.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-cache-lru.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-cache-react.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-dedup-props.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-hoist-static-io.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md
create mode 100644 .claude/skills/vercel-react-best-practices/rules/server-serialization.md
create mode 100644 .claude/skills/vitest/SKILL.md
create mode 100644 .claude/skills/vitest/references/assert-edge-cases.md
create mode 100644 .claude/skills/vitest/references/assert-expect-assertions.md
create mode 100644 .claude/skills/vitest/references/assert-one-assertion-concept.md
create mode 100644 .claude/skills/vitest/references/assert-specific-matchers.md
create mode 100644 .claude/skills/vitest/references/assert-toequal-vs-tobe.md
create mode 100644 .claude/skills/vitest/references/async-act-wrapper.md
create mode 100644 .claude/skills/vitest/references/async-await-assertions.md
create mode 100644 .claude/skills/vitest/references/async-concurrent-expect.md
create mode 100644 .claude/skills/vitest/references/async-error-handling.md
create mode 100644 .claude/skills/vitest/references/async-fake-timers.md
create mode 100644 .claude/skills/vitest/references/async-return-promises.md
create mode 100644 .claude/skills/vitest/references/async-waitfor-polling.md
create mode 100644 .claude/skills/vitest/references/env-browser-api-mocking.md
create mode 100644 .claude/skills/vitest/references/env-globals-config.md
create mode 100644 .claude/skills/vitest/references/env-per-file-override.md
create mode 100644 .claude/skills/vitest/references/env-setup-files.md
create mode 100644 .claude/skills/vitest/references/mock-avoid-overmocking.md
create mode 100644 .claude/skills/vitest/references/mock-clear-between-tests.md
create mode 100644 .claude/skills/vitest/references/mock-implementation-not-value.md
create mode 100644 .claude/skills/vitest/references/mock-msw-network.md
create mode 100644 .claude/skills/vitest/references/mock-spyon-vs-mock.md
create mode 100644 .claude/skills/vitest/references/mock-type-safety.md
create mode 100644 .claude/skills/vitest/references/mock-vi-mock-hoisting.md
create mode 100644 .claude/skills/vitest/references/org-describe-nesting.md
create mode 100644 .claude/skills/vitest/references/org-file-colocation.md
create mode 100644 .claude/skills/vitest/references/org-test-naming.md
create mode 100644 .claude/skills/vitest/references/org-test-skip-only.md
create mode 100644 .claude/skills/vitest/references/perf-bail-fast-fail.md
create mode 100644 .claude/skills/vitest/references/perf-bench-test-context.md
create mode 100644 .claude/skills/vitest/references/perf-disable-isolation.md
create mode 100644 .claude/skills/vitest/references/perf-happy-dom.md
create mode 100644 .claude/skills/vitest/references/perf-pool-selection.md
create mode 100644 .claude/skills/vitest/references/perf-run-mode-ci.md
create mode 100644 .claude/skills/vitest/references/perf-sharding.md
create mode 100644 .claude/skills/vitest/references/setup-avoid-shared-state.md
create mode 100644 .claude/skills/vitest/references/setup-beforeall-expensive.md
create mode 100644 .claude/skills/vitest/references/setup-beforeeach-cleanup.md
create mode 100644 .claude/skills/vitest/references/setup-reset-modules.md
create mode 100644 .claude/skills/vitest/references/setup-restore-mocks.md
create mode 100644 .claude/skills/vitest/references/setup-test-factories.md
create mode 100644 .claude/skills/vitest/references/setup-vitest5-migration.md
create mode 100644 .claude/skills/vitest/references/snap-avoid-large.md
create mode 100644 .claude/skills/vitest/references/snap-describe-intent.md
create mode 100644 .claude/skills/vitest/references/snap-inline-over-file.md
create mode 100644 .claude/skills/vitest/references/snap-review-updates.md
create mode 100644 .claude/skills/vitest/references/snap-stable-serialization.md
create mode 100644 .claude/skills/web-design-guidelines/SKILL.md
create mode 100644 .claude/skills/zod/SKILL.md
create mode 100644 .claude/skills/zod/references/compose-intersection.md
create mode 100644 .claude/skills/zod/references/compose-lazy-recursive.md
create mode 100644 .claude/skills/zod/references/compose-pipe.md
create mode 100644 .claude/skills/zod/references/compose-preprocess.md
create mode 100644 .claude/skills/zod/references/compose-shared-schemas.md
create mode 100644 .claude/skills/zod/references/error-avoid-throwing-in-refine.md
create mode 100644 .claude/skills/zod/references/error-custom-messages.md
create mode 100644 .claude/skills/zod/references/error-i18n.md
create mode 100644 .claude/skills/zod/references/error-path-for-nested.md
create mode 100644 .claude/skills/zod/references/error-use-flatten.md
create mode 100644 .claude/skills/zod/references/object-discriminated-unions.md
create mode 100644 .claude/skills/zod/references/object-extend-for-composition.md
create mode 100644 .claude/skills/zod/references/object-optional-vs-nullable.md
create mode 100644 .claude/skills/zod/references/object-partial-for-updates.md
create mode 100644 .claude/skills/zod/references/object-pick-omit.md
create mode 100644 .claude/skills/zod/references/object-strict-vs-strip.md
create mode 100644 .claude/skills/zod/references/parse-async-for-async-refinements.md
create mode 100644 .claude/skills/zod/references/parse-avoid-double-validation.md
create mode 100644 .claude/skills/zod/references/parse-handle-all-issues.md
create mode 100644 .claude/skills/zod/references/parse-never-trust-json.md
create mode 100644 .claude/skills/zod/references/parse-use-safeparse.md
create mode 100644 .claude/skills/zod/references/parse-validate-early.md
create mode 100644 .claude/skills/zod/references/parse-validate-for-boolean-checks.md
create mode 100644 .claude/skills/zod/references/perf-arrays.md
create mode 100644 .claude/skills/zod/references/perf-avoid-dynamic-creation.md
create mode 100644 .claude/skills/zod/references/perf-cache-schemas.md
create mode 100644 .claude/skills/zod/references/perf-compile-schemas.md
create mode 100644 .claude/skills/zod/references/perf-lazy-loading.md
create mode 100644 .claude/skills/zod/references/perf-zod-mini.md
create mode 100644 .claude/skills/zod/references/refine-add-path.md
create mode 100644 .claude/skills/zod/references/refine-catch.md
create mode 100644 .claude/skills/zod/references/refine-defaults.md
create mode 100644 .claude/skills/zod/references/refine-transform-coerce.md
create mode 100644 .claude/skills/zod/references/refine-use-codec.md
create mode 100644 .claude/skills/zod/references/refine-vs-superrefine.md
create mode 100644 .claude/skills/zod/references/schema-avoid-optional-abuse.md
create mode 100644 .claude/skills/zod/references/schema-coercion-for-form-data.md
create mode 100644 .claude/skills/zod/references/schema-string-validations.md
create mode 100644 .claude/skills/zod/references/schema-use-enums.md
create mode 100644 .claude/skills/zod/references/schema-use-primitives-correctly.md
create mode 100644 .claude/skills/zod/references/schema-use-unknown-not-any.md
create mode 100644 .claude/skills/zod/references/type-branded-types.md
create mode 100644 .claude/skills/zod/references/type-enable-strict-mode.md
create mode 100644 .claude/skills/zod/references/type-export-schemas-and-types.md
create mode 100644 .claude/skills/zod/references/type-input-vs-output.md
create mode 100644 .claude/skills/zod/references/type-use-z-infer.md
create mode 100644 .config/dotnet-tools.json
create mode 100644 .dockerignore
create mode 100644 .env.example
create mode 100644 .github/SECURITY.md
create mode 100644 AGENTS.md
create mode 100644 Backend/Directory.Build.props
create mode 100644 Backend/Dockerfile
create mode 100644 Backend/docker/mysql-init.sh
rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Api/Endpoints/AdministrationEndpoints.cs (74%)
rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Api/Extensions.cs (93%)
create mode 100644 Backend/src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj
rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Api/Operations/AdministrationOperations.cs (84%)
rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Application/Extensions.cs (88%)
create mode 100644 Backend/src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj
rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Application/Services/AdminModuleApi.cs (84%)
create mode 100644 Backend/src/Modules/AdministrationModule/Modules.Administration.Application/Services/AdminService.cs
rename {DbBackupService/Src => Backend/src}/Modules/AdministrationModule/Modules.Administration.Shared/Interfaces/IAdminModuleApi.cs (58%)
create mode 100644 Backend/src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Api/Endpoints/AuthEndpoints.cs (57%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Api/Extensions.cs (93%)
create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Api/Operations/AuthOperations.cs (65%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Application/Extensions.cs (76%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Application/Interfaces/IAuthService.cs (63%)
create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Application/Services/AuthService.cs (55%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Core/Entities/AppUser.cs (75%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Core/Entities/AuthSettings.cs (99%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Core/Entities/TokenModel.cs (99%)
create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/AppIdentityDbContext.cs (92%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/AppIdentityDbContextFactory.cs (91%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20250825091711_Initial.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20250825091711_Initial.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20250902202604_AddIsBlockedColumn.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20250902202604_AddIsBlockedColumn.cs (100%)
create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20261021180313_UpgradeNet10Identity.Designer.cs
create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/20261021180313_UpgradeNet10Identity.cs
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/DbContexts/Migrations/AppIdentityDbContextModelSnapshot.cs (99%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Infrastructure/Extensions.cs (82%)
create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj
create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs
create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangePasswordRequest.cs
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/EditUserRequest.cs (69%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/LoginRequest.cs (52%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/RegisterRequest.cs (99%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/Dtos/UserDto.cs (99%)
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/Entities/CurrentUser.cs (99%)
create mode 100644 Backend/src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj
rename {DbBackupService/Src => Backend/src}/Modules/AuthModule/Modules.Auth.Shared/Static/Entities/AppRoles.cs (99%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Api/Backups/BackupQueueEndpoints.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Backups/BackupsEo.cs (67%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Extensions.cs (92%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Schedules/SchedulesEo.cs (95%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Api/Security/ResourceAccessFilter.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Servers/ServersEo.cs (92%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Api/Statistics/StatsEO.cs (93%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Extensions.cs (62%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Interfaces/IBackupExecutor.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Interfaces/IDbBackupService.cs (76%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Interfaces/IEmailProviderService.cs (80%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupExecutor.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupQueueCoordinator.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupQueueProcessor.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupQueueService.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/BackupTarget.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Services/EmailProviderService.cs (99%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Services/NotifyService.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Services/SchedulesService.cs (83%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Services/ServersService.cs (88%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Services/StatisticsService.cs (96%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Application/Static/ServerConnectionTester.cs (86%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Application/Workers/BackupWorker.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/DatabaseBase.cs (75%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/PostgreSqlDatabase.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/SqlServerDatabase.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/AutomaticBackupTestConfig.cs (76%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupRequest.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupSchedule.cs (93%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/BackupTest.cs (88%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerConnection.cs (95%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/DbServerTunnel.cs (92%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/PerformedBackup.cs (86%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/ServerBackupsConfiguration.cs (70%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/ServersUsers.cs (76%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/DbContext/UserNotificationsSettings.cs (89%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/AppEmailConfigurationModel.cs (81%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/ApplicationConfigurationModel.cs (99%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/BackupDayTime.cs (67%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/EWeekDay.cs (69%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Entities/Models/EmailProviderConfigurationModel.cs (88%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Entities/Models/MailModel.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Exceptions/EmptyListOfConfigurationsException.cs (82%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/Interfaces/IDatabase.cs (92%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/StaticClasses/CompressBackupFile.cs (98%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/StaticClasses/DeleteOldBackup.cs (99%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/DumpFailureException.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/DumpProcess.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/MySqlDumpClient.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/StaticClasses/PrepareEmailMessageBody.cs (95%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/SafeBackupPath.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/SshHostKeys.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Core/StaticClasses/SshTunnelHelper.cs (77%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Configuration/LoggerPrepareSetup.cs (99%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Configuration/PrepareApplicationSettings.cs (99%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/BackupsDbContext.cs (55%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250903215501_Initial.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250903215501_Initial.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250904111233_AddPKToServersUsers.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250904111233_AddPKToServersUsers.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250909144138_UpdateSchedulesEntity.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250909144138_UpdateSchedulesEntity.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250910104700_AddPEMPassphraseToTunnelEntity.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250910104700_AddPEMPassphraseToTunnelEntity.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911091310_UpdateBackupsColumns.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911091310_UpdateBackupsColumns.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911125405_UpdateBackupEntity.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911125405_UpdateBackupEntity.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911172706_ModifyNullsInBackupEntity.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20250911172706_ModifyNullsInBackupEntity.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251025203420_AddSslToEntity.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20251026120032_AddSoftDeleteToBackups.cs (100%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20261021203734_AddPersistentBackupQueue.Designer.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/20261021203734_AddPersistentBackupQueue.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/DbContexts/Migrations/BackupsDbContextModelSnapshot.cs (78%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Extensions.cs (85%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251010094225_UpdateAutoTestConfigEntity.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251010094225_UpdateAutoTestConfigEntity.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251013075224_ChangeIntsToUShorts.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.Designer.cs (100%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Infrastructure/Migrations/20251105083810_ChangeEntityAddTestStatus.cs (100%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/AdminDashboardDto.cs (88%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/AutoTestBackupConfigDto.cs (98%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupRequestDto.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupScheduleConfiguration.cs (93%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupTestDto.cs (86%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/BackupsScheduleDto.cs (90%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/PerformedBackupDto.cs (94%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerConnectionDto.cs (86%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerNameIdDto.cs
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerTunnelDto.cs (97%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServersUsersListDto.cs (84%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Dtos/UserDashboardDto.cs (87%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Enums/DatabaseType.cs (61%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Enums/ETestStatus.cs (98%)
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Helpers/BackupScheduleHelper.cs (86%)
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Shared/Hubs/BackupHub.cs
create mode 100644 Backend/src/Modules/BackupModule/Modules.Backup.Shared/Modules.Backup.Shared.csproj
rename {DbBackupService/Src => Backend/src}/Modules/BackupModule/Modules.Backup.Shared/Requests/ModifyServerAccessRequest.cs (54%)
rename {DbBackupService/Src => Backend/src}/Modules/CryptoModule/Modules.Crypto.Api/Extension.cs (83%)
create mode 100644 Backend/src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj
rename {DbBackupService/Src => Backend/src}/Modules/CryptoModule/Modules.Crypto.Application/Extensions.cs (86%)
create mode 100644 Backend/src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj
rename {DbBackupService/Src => Backend/src}/Modules/CryptoModule/Modules.Crypto.Application/Services/CryptoService.cs (63%)
rename {DbBackupService/Src => Backend/src}/Modules/CryptoModule/Modules.Crypto.Shared/Interfaces/ICryptoService.cs (71%)
create mode 100644 Backend/src/Modules/CryptoModule/Modules.Crypto.Shared/Modules.Crypto.Shared.csproj
create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Attributes/AdminTokenAuthorizationFilter.cs
create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Attributes/RequestValidationFilter.cs
rename {DbBackupService/Src => Backend/src}/Modules/Shared/Modules.Shared/Common/ApiBaseController.cs (79%)
create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Common/DbCommon.cs
create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Modules.Shared.csproj
create mode 100644 Backend/src/Modules/Shared/Modules.Shared/Settings/ApplicationSettings.cs
create mode 100644 Backend/src/Server.Api/Configuration/ApplicationSettingsEndpoints.cs
create mode 100644 Backend/src/Server.Api/Configuration/DevelopmentSettings.cs
create mode 100644 Backend/src/Server.Api/Configuration/FileApplicationSettings.cs
create mode 100644 Backend/src/Server.Api/Program.cs
create mode 100644 Backend/src/Server.Api/Properties/launchSettings.json
create mode 100644 Backend/src/Server.Api/Security/ApiExceptionHandler.cs
create mode 100644 Backend/src/Server.Api/Security/BootstrapAdmin.cs
create mode 100644 Backend/src/Server.Api/Server.Api.csproj
create mode 100644 Backend/src/Server.Api/appsettings.Development.json
create mode 100644 Backend/src/Server.Api/appsettings.json
create mode 100644 Backend/tests/DumpToolFixture/DumpToolFixture.csproj
create mode 100644 Backend/tests/DumpToolFixture/Program.cs
create mode 100644 Backend/tests/MySqlDumpSmoke/MySqlDumpSmoke.csproj
create mode 100644 Backend/tests/MySqlDumpSmoke/Program.cs
create mode 100644 Backend/tests/OctoBackup.Tests/ApplicationSettingsTests.cs
create mode 100644 Backend/tests/OctoBackup.Tests/BackupQueueTests.cs
create mode 100644 Backend/tests/OctoBackup.Tests/DevelopmentSettingsTests.cs
create mode 100644 Backend/tests/OctoBackup.Tests/DumpProcessTests.cs
create mode 100644 Backend/tests/OctoBackup.Tests/OctoBackup.Tests.csproj
create mode 100644 Backend/tests/OctoBackup.Tests/SecurityTests.cs
delete mode 100644 DbBackupService/.dockerignore
delete mode 100644 DbBackupService/OctoBackup.sln
delete mode 100644 DbBackupService/Src/.dockerignore
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/App.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Client.UI.csproj
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/HttpHandlers/HttpTokenAuthHeaderHandler.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Interfaces/IAuthHttpClientService.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/AdministrationHttpService.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/AuthHttpClientHttpClientService.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/AuthStateProvider.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/BackupsHttpClientService.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/ProfileService.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Data/Services/TokenHttpClientService.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/AuthLayout.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/AuthorizedNavMenu.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/DefaultLayout.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/MainLayout.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Layout/NotAuthorizedNavMenu.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationDashboard.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationServersUsers.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/AdministrationUsersManagement.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/Dialogs/ServersUsersManagement/AddUserToServerDialog.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/Dialogs/ServersUsersManagement/ManageUsersInServerDialog.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/Dialogs/UsersManagement/CreateNewUserDialog.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Administration/Dialogs/UsersManagement/EditUserDialog.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Account/ProfileIndex.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/AuthorizeUser.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/ConfirmPassword.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Login.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Authorization/Common/Register.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Schedule/BackupScheduleDialog.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/CreateServerDialog.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerAutoTestConfigurationDialog.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/EditServerDialog.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/Dialogs/Servers/TestServerDialog.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyBackups.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MySchedules.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/BackupsModule/MyServers.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Components/AuthorizingUserInfoComponent.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Dashboard.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Pages/Index.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Program.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Properties/launchSettings.json
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/Routes.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/_Imports.razor
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/wwwroot/css/app.css
delete mode 100644 DbBackupService/Src/Bootstraper/Client/Client.UI/wwwroot/media/OctoBackupLogo.png
delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Common/SeqConfiguration.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Dockerfile
delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Program.cs
delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Properties/launchSettings.json
delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/Server.Api.csproj
delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/appsettings.Development.json
delete mode 100644 DbBackupService/Src/Bootstraper/Server/Server.Api/appsettings.json
delete mode 100644 DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Api/Modules.Administration.Api.csproj
delete mode 100644 DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Modules.Administration.Application.csproj
delete mode 100644 DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Application/Services/AdminService.cs
delete mode 100644 DbBackupService/Src/Modules/AdministrationModule/Modules.Administration.Shared/Modules.Administration.Shared.csproj
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Api/Modules.Auth.Api.csproj
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Modules.Auth.Application.csproj
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Application/Services/TokenValidationService.cs
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Core/Modules.Auth.Core.csproj
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Modules.Auth.Infrastructure.csproj
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Repositories/IUserTokenService.cs
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Infrastructure/Repositories/UserTokenService.cs
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangeEmailRequest.cs
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/ChangePasswordRequest.cs
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/ActionsRequests/TokenValidationRequest.cs
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Entities/TokenModelDto.cs
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Interfaces/ITokenValidationService.cs
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Modules.Auth.Shared.csproj
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Static/Entities/AuthHeaderName.cs
delete mode 100644 DbBackupService/Src/Modules/AuthModule/Modules.Auth.Shared/Static/Setters/HttpClientAuthHeaderSetter.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Api/Modules.Backup.Api.csproj
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Modules.Backup.Application.csproj
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/DbBackupService.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Services/NotifyService.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Application/Workers/BackupWorker.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/MySqlDatabase.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/PostgreSqlDatabase.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Databases/SqlServerDatabase.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Entities/Models/MailModel.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/Modules.Backup.Core.csproj
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Core/StaticClasses/ToolChecker.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Infrastructure/Modules.Backup.Infrastructure.csproj
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Dtos/ServerNameIdDto.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Hubs/BackupHub.cs
delete mode 100644 DbBackupService/Src/Modules/BackupModule/Modules.Backup.Shared/Modules.Backup.Shared.csproj
delete mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/BackupsTestsEO.cs
delete mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Extensions.cs
delete mode 100644 DbBackupService/Src/Modules/BackupsTests/Modules.BackupsTests.Api/Modules.BackupsTests.Api.csproj
delete mode 100644 DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Api/Modules.Crypto.Api.csproj
delete mode 100644 DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Application/Modules.Crypto.Application.csproj
delete mode 100644 DbBackupService/Src/Modules/CryptoModule/Modules.Crypto.Shared/Modules.Crypto.Shared.csproj
delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Attributes/AdminTokenAuthorizationFilter.cs
delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Attributes/AllowWithoutTokenValidationAttribute.cs
delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Attributes/BasicTokenAuthorizationFilter.cs
delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Common/DbCommon.cs
delete mode 100644 DbBackupService/Src/Modules/Shared/Modules.Shared/Modules.Shared.csproj
delete mode 100755 DbBackupService/buildAndDeployDocker.bat
delete mode 100644 DbBackupService/certs/OctoBackupCert.pfx
delete mode 100644 DbBackupService/docker-compose.yml
delete mode 100644 DbBackupService/docker-composedev.yml
create mode 100644 Frontend/Dockerfile
create mode 100644 Frontend/docker/10-local-tls.sh
create mode 100644 Frontend/docker/default.conf
create mode 100644 Frontend/e2e/workspace.spec.ts
create mode 100644 Frontend/index.html
create mode 100644 Frontend/package-lock.json
create mode 100644 Frontend/package.json
create mode 100644 Frontend/playwright.config.ts
create mode 100644 Frontend/scripts/run-tool.mjs
create mode 100644 Frontend/scripts/start-test-api.mjs
create mode 100644 Frontend/src/app/App.tsx
create mode 100644 Frontend/src/features/account/AccountPage.tsx
create mode 100644 Frontend/src/features/admin/ApplicationSettingsPage.tsx
create mode 100644 Frontend/src/features/admin/UsersPage.tsx
create mode 100644 Frontend/src/features/auth/AuthPage.tsx
create mode 100644 Frontend/src/features/backups/BackupsPage.tsx
create mode 100644 Frontend/src/features/dashboard/Dashboard.tsx
create mode 100644 Frontend/src/features/queue/QueueHero.test.tsx
create mode 100644 Frontend/src/features/queue/QueueHero.tsx
create mode 100644 Frontend/src/features/queue/QueuePage.tsx
create mode 100644 Frontend/src/features/queue/useBackupQueue.ts
create mode 100644 Frontend/src/features/schedules/SchedulesPage.test.tsx
create mode 100644 Frontend/src/features/schedules/SchedulesPage.tsx
create mode 100644 Frontend/src/features/servers/ServerForm.tsx
create mode 100644 Frontend/src/features/servers/ServersPage.tsx
create mode 100644 Frontend/src/main.tsx
create mode 100644 Frontend/src/shared/api.test.ts
create mode 100644 Frontend/src/shared/api.ts
create mode 100644 Frontend/src/shared/types.ts
create mode 100644 Frontend/src/shared/ui.tsx
create mode 100644 Frontend/src/styles.css
create mode 100644 Frontend/src/test/setup.ts
create mode 100644 Frontend/src/vite-env.d.ts
create mode 100644 Frontend/tsconfig.json
create mode 100644 Frontend/vite.config.ts
create mode 100644 OctoBackup.sln
delete mode 100644 README_PL.md
create mode 100644 agent/skills/feature-arch/SKILL.md
create mode 100644 agent/skills/feature-arch/references/bound-event-based-communication.md
create mode 100644 agent/skills/feature-arch/references/bound-feature-isolation.md
create mode 100644 agent/skills/feature-arch/references/bound-feature-scoped-routing.md
create mode 100644 agent/skills/feature-arch/references/bound-feature-size.md
create mode 100644 agent/skills/feature-arch/references/bound-interface-contracts.md
create mode 100644 agent/skills/feature-arch/references/bound-minimize-shared-state.md
create mode 100644 agent/skills/feature-arch/references/fcomp-colocate-styles.md
create mode 100644 agent/skills/feature-arch/references/fcomp-composition-over-props.md
create mode 100644 agent/skills/feature-arch/references/fcomp-container-presentational.md
create mode 100644 agent/skills/feature-arch/references/fcomp-error-boundaries.md
create mode 100644 agent/skills/feature-arch/references/fcomp-props-as-data-boundary.md
create mode 100644 agent/skills/feature-arch/references/fcomp-single-responsibility.md
create mode 100644 agent/skills/feature-arch/references/fquery-avoid-n-plus-one.md
create mode 100644 agent/skills/feature-arch/references/fquery-colocate-with-feature.md
create mode 100644 agent/skills/feature-arch/references/fquery-feature-scoped-keys.md
create mode 100644 agent/skills/feature-arch/references/fquery-parallel-fetching.md
create mode 100644 agent/skills/feature-arch/references/fquery-server-component-fetching.md
create mode 100644 agent/skills/feature-arch/references/fquery-single-responsibility.md
create mode 100644 agent/skills/feature-arch/references/fstate-context-sparingly.md
create mode 100644 agent/skills/feature-arch/references/fstate-feature-scoped-stores.md
create mode 100644 agent/skills/feature-arch/references/fstate-lift-minimally.md
create mode 100644 agent/skills/feature-arch/references/fstate-reset-on-unmount.md
create mode 100644 agent/skills/feature-arch/references/fstate-server-state-separation.md
create mode 100644 agent/skills/feature-arch/references/import-avoid-barrel-files.md
create mode 100644 agent/skills/feature-arch/references/import-no-cross-feature.md
create mode 100644 agent/skills/feature-arch/references/import-path-aliases.md
create mode 100644 agent/skills/feature-arch/references/import-public-api.md
create mode 100644 agent/skills/feature-arch/references/import-type-only.md
create mode 100644 agent/skills/feature-arch/references/import-unidirectional-flow.md
create mode 100644 agent/skills/feature-arch/references/name-descriptive-exports.md
create mode 100644 agent/skills/feature-arch/references/name-feature-naming.md
create mode 100644 agent/skills/feature-arch/references/name-file-conventions.md
create mode 100644 agent/skills/feature-arch/references/struct-app-layer.md
create mode 100644 agent/skills/feature-arch/references/struct-feature-folders.md
create mode 100644 agent/skills/feature-arch/references/struct-feature-self-contained.md
create mode 100644 agent/skills/feature-arch/references/struct-flat-hierarchy.md
create mode 100644 agent/skills/feature-arch/references/struct-optional-segments.md
create mode 100644 agent/skills/feature-arch/references/struct-shared-layer.md
create mode 100644 agent/skills/feature-arch/references/test-colocate-with-feature.md
create mode 100644 agent/skills/feature-arch/references/test-feature-isolation.md
create mode 100644 agent/skills/feature-arch/references/test-integration-at-app-layer.md
create mode 100644 agent/skills/feature-arch/references/test-shared-utilities.md
create mode 100644 agent/skills/msw/SKILL.md
create mode 100644 agent/skills/msw/references/advanced-bypass-requests.md
create mode 100644 agent/skills/msw/references/advanced-cookies-auth.md
create mode 100644 agent/skills/msw/references/advanced-dynamic-scenarios.md
create mode 100644 agent/skills/msw/references/advanced-file-uploads.md
create mode 100644 agent/skills/msw/references/advanced-playwright-integration.md
create mode 100644 agent/skills/msw/references/advanced-vitest-browser.md
create mode 100644 agent/skills/msw/references/advanced-websocket-mocking.md
create mode 100644 agent/skills/msw/references/debug-common-issues.md
create mode 100644 agent/skills/msw/references/debug-lifecycle-events.md
create mode 100644 agent/skills/msw/references/debug-request-logging.md
create mode 100644 agent/skills/msw/references/debug-verify-interception.md
create mode 100644 agent/skills/msw/references/graphql-batched-queries.md
create mode 100644 agent/skills/msw/references/graphql-error-responses.md
create mode 100644 agent/skills/msw/references/graphql-operation-handlers.md
create mode 100644 agent/skills/msw/references/graphql-schema-first.md
create mode 100644 agent/skills/msw/references/graphql-variables-access.md
create mode 100644 agent/skills/msw/references/handler-absolute-urls.md
create mode 100644 agent/skills/msw/references/handler-domain-grouping.md
create mode 100644 agent/skills/msw/references/handler-happy-path-first.md
create mode 100644 agent/skills/msw/references/handler-request-body-parsing.md
create mode 100644 agent/skills/msw/references/handler-resolver-argument.md
create mode 100644 agent/skills/msw/references/handler-reusability-environments.md
create mode 100644 agent/skills/msw/references/handler-shared-resolvers.md
create mode 100644 agent/skills/msw/references/handler-v2-response-syntax.md
create mode 100644 agent/skills/msw/references/match-custom-predicate.md
create mode 100644 agent/skills/msw/references/match-handler-order.md
create mode 100644 agent/skills/msw/references/match-http-methods.md
create mode 100644 agent/skills/msw/references/match-query-params.md
create mode 100644 agent/skills/msw/references/match-url-patterns.md
create mode 100644 agent/skills/msw/references/response-custom-headers.md
create mode 100644 agent/skills/msw/references/response-delay-realistic.md
create mode 100644 agent/skills/msw/references/response-error-simulation.md
create mode 100644 agent/skills/msw/references/response-http-response-helpers.md
create mode 100644 agent/skills/msw/references/response-one-time-handlers.md
create mode 100644 agent/skills/msw/references/response-streaming.md
create mode 100644 agent/skills/msw/references/setup-lifecycle-hooks.md
create mode 100644 agent/skills/msw/references/setup-node-version.md
create mode 100644 agent/skills/msw/references/setup-server-node-entrypoint.md
create mode 100644 agent/skills/msw/references/setup-typescript-config.md
create mode 100644 agent/skills/msw/references/setup-unhandled-requests.md
create mode 100644 agent/skills/msw/references/setup-worker-script-commit.md
create mode 100644 agent/skills/msw/references/test-async-utilities.md
create mode 100644 agent/skills/msw/references/test-avoid-request-assertions.md
create mode 100644 agent/skills/msw/references/test-clear-request-cache.md
create mode 100644 agent/skills/msw/references/test-concurrent-boundary.md
create mode 100644 agent/skills/msw/references/test-fake-timers-config.md
create mode 100644 agent/skills/msw/references/test-jsdom-environment.md
create mode 100644 agent/skills/msw/references/test-reset-handlers.md
create mode 100644 agent/skills/nextjs/SKILL.md
create mode 100644 agent/skills/nextjs/references/action-error-handling.md
create mode 100644 agent/skills/nextjs/references/action-optimistic-updates.md
create mode 100644 agent/skills/nextjs/references/action-pending-states.md
create mode 100644 agent/skills/nextjs/references/action-revalidation.md
create mode 100644 agent/skills/nextjs/references/action-server-action-forms.md
create mode 100644 agent/skills/nextjs/references/build-barrel-files.md
create mode 100644 agent/skills/nextjs/references/build-dynamic-imports.md
create mode 100644 agent/skills/nextjs/references/build-external-packages.md
create mode 100644 agent/skills/nextjs/references/build-optimize-package-imports.md
create mode 100644 agent/skills/nextjs/references/build-turbopack-config.md
create mode 100644 agent/skills/nextjs/references/cache-fetch-options.md
create mode 100644 agent/skills/nextjs/references/cache-react-cache.md
create mode 100644 agent/skills/nextjs/references/cache-revalidate-path.md
create mode 100644 agent/skills/nextjs/references/cache-revalidate-tag.md
create mode 100644 agent/skills/nextjs/references/cache-segment-config.md
create mode 100644 agent/skills/nextjs/references/cache-use-cache-directive.md
create mode 100644 agent/skills/nextjs/references/client-children-pattern.md
create mode 100644 agent/skills/nextjs/references/client-hydration-mismatch.md
create mode 100644 agent/skills/nextjs/references/client-third-party-scripts.md
create mode 100644 agent/skills/nextjs/references/client-use-client-boundary.md
create mode 100644 agent/skills/nextjs/references/meta-generate-metadata.md
create mode 100644 agent/skills/nextjs/references/meta-opengraph-images.md
create mode 100644 agent/skills/nextjs/references/meta-robots.md
create mode 100644 agent/skills/nextjs/references/meta-sitemap.md
create mode 100644 agent/skills/nextjs/references/route-instant-navigations.md
create mode 100644 agent/skills/nextjs/references/route-intercepting-routes.md
create mode 100644 agent/skills/nextjs/references/route-not-found.md
create mode 100644 agent/skills/nextjs/references/route-parallel-routes.md
create mode 100644 agent/skills/nextjs/references/route-partial-prefetching.md
create mode 100644 agent/skills/nextjs/references/route-prefetching.md
create mode 100644 agent/skills/nextjs/references/route-proxy-ts.md
create mode 100644 agent/skills/nextjs/references/server-avoid-client-fetching.md
create mode 100644 agent/skills/nextjs/references/server-component-streaming.md
create mode 100644 agent/skills/nextjs/references/server-data-colocation.md
create mode 100644 agent/skills/nextjs/references/server-error-handling.md
create mode 100644 agent/skills/nextjs/references/server-parallel-fetching.md
create mode 100644 agent/skills/nextjs/references/server-preload-pattern.md
create mode 100644 agent/skills/nextjs/references/stream-error-tsx.md
create mode 100644 agent/skills/nextjs/references/stream-loading-tsx.md
create mode 100644 agent/skills/nextjs/references/stream-nested-suspense.md
create mode 100644 agent/skills/nextjs/references/stream-skeleton-matching.md
create mode 100644 agent/skills/nextjs/references/stream-suspense-boundaries.md
create mode 100644 agent/skills/nuqs/SKILL.md
create mode 100644 agent/skills/nuqs/references/advanced-custom-parsers.md
create mode 100644 agent/skills/nuqs/references/advanced-eq-function.md
create mode 100644 agent/skills/nuqs/references/advanced-framework-adapters.md
create mode 100644 agent/skills/nuqs/references/advanced-url-keys.md
create mode 100644 agent/skills/nuqs/references/debug-common-errors.md
create mode 100644 agent/skills/nuqs/references/debug-enable-logging.md
create mode 100644 agent/skills/nuqs/references/debug-testing.md
create mode 100644 agent/skills/nuqs/references/history-back-sync.md
create mode 100644 agent/skills/nuqs/references/history-push-navigation.md
create mode 100644 agent/skills/nuqs/references/history-replace-ephemeral.md
create mode 100644 agent/skills/nuqs/references/history-scroll-behavior.md
create mode 100644 agent/skills/nuqs/references/parser-array-format.md
create mode 100644 agent/skills/nuqs/references/parser-date-format.md
create mode 100644 agent/skills/nuqs/references/parser-enum-validation.md
create mode 100644 agent/skills/nuqs/references/parser-hex-colors.md
create mode 100644 agent/skills/nuqs/references/parser-index-offset.md
create mode 100644 agent/skills/nuqs/references/parser-json-validation.md
create mode 100644 agent/skills/nuqs/references/parser-use-typed-parsers.md
create mode 100644 agent/skills/nuqs/references/parser-with-default.md
create mode 100644 agent/skills/nuqs/references/perf-avoid-rerender.md
create mode 100644 agent/skills/nuqs/references/perf-clear-on-default.md
create mode 100644 agent/skills/nuqs/references/perf-debounce-search.md
create mode 100644 agent/skills/nuqs/references/perf-serialize-utility.md
create mode 100644 agent/skills/nuqs/references/perf-throttle-updates.md
create mode 100644 agent/skills/nuqs/references/server-next15-async.md
create mode 100644 agent/skills/nuqs/references/server-parse-before-get.md
create mode 100644 agent/skills/nuqs/references/server-search-params-cache.md
create mode 100644 agent/skills/nuqs/references/server-shallow-false.md
create mode 100644 agent/skills/nuqs/references/server-share-parsers.md
create mode 100644 agent/skills/nuqs/references/server-use-transition.md
create mode 100644 agent/skills/nuqs/references/setup-import-server.md
create mode 100644 agent/skills/nuqs/references/setup-nextjs-version.md
create mode 100644 agent/skills/nuqs/references/setup-nuqs-adapter.md
create mode 100644 agent/skills/nuqs/references/setup-shared-parsers.md
create mode 100644 agent/skills/nuqs/references/setup-use-client.md
create mode 100644 agent/skills/nuqs/references/state-avoid-derived.md
create mode 100644 agent/skills/nuqs/references/state-clear-with-null.md
create mode 100644 agent/skills/nuqs/references/state-controlled-inputs.md
create mode 100644 agent/skills/nuqs/references/state-functional-updates.md
create mode 100644 agent/skills/nuqs/references/state-options-inheritance.md
create mode 100644 agent/skills/nuqs/references/state-setter-return.md
create mode 100644 agent/skills/nuqs/references/state-use-query-states.md
create mode 100644 agent/skills/playwright/SKILL.md
create mode 100644 agent/skills/playwright/references/arch-cleanup-state.md
create mode 100644 agent/skills/playwright/references/arch-fixtures.md
create mode 100644 agent/skills/playwright/references/arch-page-object-model.md
create mode 100644 agent/skills/playwright/references/arch-parallel-execution.md
create mode 100644 agent/skills/playwright/references/arch-test-isolation.md
create mode 100644 agent/skills/playwright/references/arch-test-production.md
create mode 100644 agent/skills/playwright/references/assert-aria-snapshots.md
create mode 100644 agent/skills/playwright/references/auth-api-login.md
create mode 100644 agent/skills/playwright/references/auth-multiple-roles.md
create mode 100644 agent/skills/playwright/references/auth-parallel-workers.md
create mode 100644 agent/skills/playwright/references/auth-session-storage.md
create mode 100644 agent/skills/playwright/references/auth-storage-state.md
create mode 100644 agent/skills/playwright/references/debug-ci-reporters.md
create mode 100644 agent/skills/playwright/references/debug-inspector.md
create mode 100644 agent/skills/playwright/references/debug-screenshots-videos.md
create mode 100644 agent/skills/playwright/references/debug-trace-viewer.md
create mode 100644 agent/skills/playwright/references/loc-avoid-xpath.md
create mode 100644 agent/skills/playwright/references/loc-chained-locators.md
create mode 100644 agent/skills/playwright/references/loc-data-testid.md
create mode 100644 agent/skills/playwright/references/loc-frame-locator.md
create mode 100644 agent/skills/playwright/references/loc-label-selectors.md
create mode 100644 agent/skills/playwright/references/loc-placeholder-selector.md
create mode 100644 agent/skills/playwright/references/loc-role-selectors.md
create mode 100644 agent/skills/playwright/references/loc-text-selectors.md
create mode 100644 agent/skills/playwright/references/mock-abort-requests.md
create mode 100644 agent/skills/playwright/references/mock-api-responses.md
create mode 100644 agent/skills/playwright/references/mock-har-files.md
create mode 100644 agent/skills/playwright/references/mock-intercept-modify.md
create mode 100644 agent/skills/playwright/references/mock-network-conditions.md
create mode 100644 agent/skills/playwright/references/next-app-router-navigation.md
create mode 100644 agent/skills/playwright/references/next-baseurl-config.md
create mode 100644 agent/skills/playwright/references/next-server-actions.md
create mode 100644 agent/skills/playwright/references/next-server-components.md
create mode 100644 agent/skills/playwright/references/next-wait-hydration.md
create mode 100644 agent/skills/playwright/references/perf-browser-selection.md
create mode 100644 agent/skills/playwright/references/perf-headless-ci.md
create mode 100644 agent/skills/playwright/references/perf-retries.md
create mode 100644 agent/skills/playwright/references/perf-reuse-server.md
create mode 100644 agent/skills/playwright/references/perf-sharding.md
create mode 100644 agent/skills/playwright/references/wait-action-retries.md
create mode 100644 agent/skills/playwright/references/wait-avoid-hard-waits.md
create mode 100644 agent/skills/playwright/references/wait-custom-timeout.md
create mode 100644 agent/skills/playwright/references/wait-network-idle.md
create mode 100644 agent/skills/playwright/references/wait-soft-assertions.md
create mode 100644 agent/skills/playwright/references/wait-web-first-assertions.md
create mode 100644 agent/skills/react-hook-form/SKILL.md
create mode 100644 agent/skills/react-hook-form/references/adv-devtools-performance.md
create mode 100644 agent/skills/react-hook-form/references/adv-formprovider-memo.md
create mode 100644 agent/skills/react-hook-form/references/adv-opaque-types.md
create mode 100644 agent/skills/react-hook-form/references/adv-testing-wrapper.md
create mode 100644 agent/skills/react-hook-form/references/array-complete-default-objects.md
create mode 100644 agent/skills/react-hook-form/references/array-separate-crud-operations.md
create mode 100644 agent/skills/react-hook-form/references/array-unique-fieldarray-per-name.md
create mode 100644 agent/skills/react-hook-form/references/array-use-field-id-as-key.md
create mode 100644 agent/skills/react-hook-form/references/array-virtualization-formprovider.md
create mode 100644 agent/skills/react-hook-form/references/ctrl-avoid-double-registration.md
create mode 100644 agent/skills/react-hook-form/references/ctrl-controller-field-props.md
create mode 100644 agent/skills/react-hook-form/references/ctrl-local-state-combination.md
create mode 100644 agent/skills/react-hook-form/references/ctrl-single-usecontroller-per-component.md
create mode 100644 agent/skills/react-hook-form/references/ctrl-usecontroller-isolation.md
create mode 100644 agent/skills/react-hook-form/references/formcfg-async-default-values.md
create mode 100644 agent/skills/react-hook-form/references/formcfg-default-values.md
create mode 100644 agent/skills/react-hook-form/references/formcfg-revalidate-mode.md
create mode 100644 agent/skills/react-hook-form/references/formcfg-should-unregister.md
create mode 100644 agent/skills/react-hook-form/references/formcfg-useeffect-dependency.md
create mode 100644 agent/skills/react-hook-form/references/formcfg-validation-mode.md
create mode 100644 agent/skills/react-hook-form/references/formstate-avoid-isvalid-with-onsubmit.md
create mode 100644 agent/skills/react-hook-form/references/formstate-destructure-formstate.md
create mode 100644 agent/skills/react-hook-form/references/formstate-getfieldstate-for-single-field.md
create mode 100644 agent/skills/react-hook-form/references/formstate-subscribe-to-specific-fields.md
create mode 100644 agent/skills/react-hook-form/references/formstate-useformstate-isolation.md
create mode 100644 agent/skills/react-hook-form/references/integ-mui-controller-pattern.md
create mode 100644 agent/skills/react-hook-form/references/integ-shadcn-form-import.md
create mode 100644 agent/skills/react-hook-form/references/integ-shadcn-select-wiring.md
create mode 100644 agent/skills/react-hook-form/references/integ-typed-submit-server-action.md
create mode 100644 agent/skills/react-hook-form/references/integ-value-transform.md
create mode 100644 agent/skills/react-hook-form/references/sub-avoid-watch-in-render.md
create mode 100644 agent/skills/react-hook-form/references/sub-deep-subscription.md
create mode 100644 agent/skills/react-hook-form/references/sub-useformcontext-sparingly.md
create mode 100644 agent/skills/react-hook-form/references/sub-usewatch-default-value.md
create mode 100644 agent/skills/react-hook-form/references/sub-usewatch-over-watch.md
create mode 100644 agent/skills/react-hook-form/references/sub-usewatch-with-getvalues.md
create mode 100644 agent/skills/react-hook-form/references/sub-watch-specific-fields.md
create mode 100644 agent/skills/react-hook-form/references/valid-delay-error.md
create mode 100644 agent/skills/react-hook-form/references/valid-dynamic-schema-factory.md
create mode 100644 agent/skills/react-hook-form/references/valid-error-message-strategy.md
create mode 100644 agent/skills/react-hook-form/references/valid-form-level-validate.md
create mode 100644 agent/skills/react-hook-form/references/valid-inline-vs-resolver.md
create mode 100644 agent/skills/react-hook-form/references/valid-native-validation.md
create mode 100644 agent/skills/react-hook-form/references/valid-resolver-caching.md
create mode 100644 agent/skills/react-hook-form/references/valid-trigger-should-touch.md
create mode 100644 agent/skills/react/SKILL.md
create mode 100644 agent/skills/react/references/_sections.md
create mode 100644 agent/skills/react/references/conc-automatic-batching.md
create mode 100644 agent/skills/react/references/conc-concurrent-safe.md
create mode 100644 agent/skills/react/references/conc-suspense-fallback.md
create mode 100644 agent/skills/react/references/conc-use-deferred-value.md
create mode 100644 agent/skills/react/references/conc-use-transition.md
create mode 100644 agent/skills/react/references/conc-view-transitions.md
create mode 100644 agent/skills/react/references/data-cache-deduplication.md
create mode 100644 agent/skills/react/references/data-error-boundaries.md
create mode 100644 agent/skills/react/references/data-parallel-fetching.md
create mode 100644 agent/skills/react/references/data-suspense-data-fetching.md
create mode 100644 agent/skills/react/references/data-use-hook.md
create mode 100644 agent/skills/react/references/effect-avoid-unnecessary.md
create mode 100644 agent/skills/react/references/effect-cleanup.md
create mode 100644 agent/skills/react/references/effect-object-dependencies.md
create mode 100644 agent/skills/react/references/effect-use-browser-only.md
create mode 100644 agent/skills/react/references/effect-use-effect-event.md
create mode 100644 agent/skills/react/references/effect-use-sync-external-store.md
create mode 100644 agent/skills/react/references/form-actions.md
create mode 100644 agent/skills/react/references/form-use-action-state.md
create mode 100644 agent/skills/react/references/form-use-form-status.md
create mode 100644 agent/skills/react/references/form-use-optimistic.md
create mode 100644 agent/skills/react/references/form-validation.md
create mode 100644 agent/skills/react/references/memo-avoid-premature.md
create mode 100644 agent/skills/react/references/memo-compiler.md
create mode 100644 agent/skills/react/references/memo-react-memo.md
create mode 100644 agent/skills/react/references/memo-use-callback.md
create mode 100644 agent/skills/react/references/memo-use-memo.md
create mode 100644 agent/skills/react/references/rcomp-composition.md
create mode 100644 agent/skills/react/references/rcomp-controlled-components.md
create mode 100644 agent/skills/react/references/rcomp-fragment-refs.md
create mode 100644 agent/skills/react/references/rcomp-key-reset.md
create mode 100644 agent/skills/react/references/rcomp-render-props.md
create mode 100644 agent/skills/react/references/rsc-avoid-client-only-libs.md
create mode 100644 agent/skills/react/references/rsc-composition-pattern.md
create mode 100644 agent/skills/react/references/rsc-context-provider.md
create mode 100644 agent/skills/react/references/rsc-data-fetching-server.md
create mode 100644 agent/skills/react/references/rsc-serializable-props.md
create mode 100644 agent/skills/react/references/rsc-server-client-boundary.md
create mode 100644 agent/skills/react/references/rsc-streaming.md
create mode 100644 agent/skills/react/references/rstate-context-optimization.md
create mode 100644 agent/skills/react/references/rstate-derived-values.md
create mode 100644 agent/skills/react/references/rstate-functional-updates.md
create mode 100644 agent/skills/react/references/rstate-lazy-initialization.md
create mode 100644 agent/skills/react/references/rstate-use-reducer.md
create mode 100644 agent/skills/shadcn/SKILL.md
create mode 100644 agent/skills/shadcn/references/ally-ensure-color-contrast.md
create mode 100644 agent/skills/shadcn/references/ally-maintain-focus-management.md
create mode 100644 agent/skills/shadcn/references/ally-preserve-aria-attributes.md
create mode 100644 agent/skills/shadcn/references/ally-preserve-keyboard-navigation.md
create mode 100644 agent/skills/shadcn/references/ally-provide-sr-only-labels.md
create mode 100644 agent/skills/shadcn/references/arch-current-cli-registry.md
create mode 100644 agent/skills/shadcn/references/arch-extend-variants-with-cva.md
create mode 100644 agent/skills/shadcn/references/arch-forward-refs-for-composable-components.md
create mode 100644 agent/skills/shadcn/references/arch-isolate-component-variants.md
create mode 100644 agent/skills/shadcn/references/arch-preserve-radix-primitive-structure.md
create mode 100644 agent/skills/shadcn/references/arch-unified-radix-package.md
create mode 100644 agent/skills/shadcn/references/arch-use-asChild-for-custom-triggers.md
create mode 100644 agent/skills/shadcn/references/arch-use-cn-for-class-merging.md
create mode 100644 agent/skills/shadcn/references/comp-combine-command-with-popover.md
create mode 100644 agent/skills/shadcn/references/comp-compose-with-compound-components.md
create mode 100644 agent/skills/shadcn/references/comp-create-reusable-form-fields.md
create mode 100644 agent/skills/shadcn/references/comp-nest-dialogs-correctly.md
create mode 100644 agent/skills/shadcn/references/comp-use-drawer-for-mobile-modals.md
create mode 100644 agent/skills/shadcn/references/comp-use-slot-pattern-for-flexibility.md
create mode 100644 agent/skills/shadcn/references/data-empty-states-with-guidance.md
create mode 100644 agent/skills/shadcn/references/data-paginate-server-side.md
create mode 100644 agent/skills/shadcn/references/data-use-skeleton-loading-states.md
create mode 100644 agent/skills/shadcn/references/data-use-tanstack-table-for-complex-tables.md
create mode 100644 agent/skills/shadcn/references/data-virtualize-large-lists.md
create mode 100644 agent/skills/shadcn/references/form-handle-async-validation.md
create mode 100644 agent/skills/shadcn/references/form-reset-form-state-correctly.md
create mode 100644 agent/skills/shadcn/references/form-show-validation-errors-correctly.md
create mode 100644 agent/skills/shadcn/references/form-use-react-hook-form-integration.md
create mode 100644 agent/skills/shadcn/references/form-use-zod-for-schema-validation.md
create mode 100644 agent/skills/shadcn/references/perf-avoid-unnecessary-rerenders-in-forms.md
create mode 100644 agent/skills/shadcn/references/perf-debounce-search-inputs.md
create mode 100644 agent/skills/shadcn/references/perf-lazy-load-heavy-components.md
create mode 100644 agent/skills/shadcn/references/perf-memoize-expensive-renders.md
create mode 100644 agent/skills/shadcn/references/perf-optimize-icon-imports.md
create mode 100644 agent/skills/shadcn/references/state-colocate-state-with-components.md
create mode 100644 agent/skills/shadcn/references/state-lift-state-to-appropriate-level.md
create mode 100644 agent/skills/shadcn/references/state-prefer-uncontrolled-for-simple-inputs.md
create mode 100644 agent/skills/shadcn/references/state-use-controlled-dialog-state.md
create mode 100644 agent/skills/shadcn/references/style-avoid-important-overrides.md
create mode 100644 agent/skills/shadcn/references/style-consistent-spacing-scale.md
create mode 100644 agent/skills/shadcn/references/style-dark-mode-support.md
create mode 100644 agent/skills/shadcn/references/style-responsive-design-patterns.md
create mode 100644 agent/skills/shadcn/references/style-use-css-variables-for-theming.md
create mode 100644 agent/skills/shadcn/references/style-use-tailwind-theme-extend.md
create mode 100644 agent/skills/tailwind/SKILL.md
create mode 100644 agent/skills/tailwind/references/anim-3d-transforms.md
create mode 100644 agent/skills/tailwind/references/anim-gpu-accelerated.md
create mode 100644 agent/skills/tailwind/references/anim-gradient-interpolation.md
create mode 100644 agent/skills/tailwind/references/anim-starting-style.md
create mode 100644 agent/skills/tailwind/references/build-cli-package.md
create mode 100644 agent/skills/tailwind/references/build-content-detection.md
create mode 100644 agent/skills/tailwind/references/build-css-import.md
create mode 100644 agent/skills/tailwind/references/build-node-version.md
create mode 100644 agent/skills/tailwind/references/build-postcss-simplify.md
create mode 100644 agent/skills/tailwind/references/build-vite-plugin.md
create mode 100644 agent/skills/tailwind/references/bundle-avoid-cdn-production.md
create mode 100644 agent/skills/tailwind/references/bundle-avoid-preprocessors.md
create mode 100644 agent/skills/tailwind/references/bundle-css-minification.md
create mode 100644 agent/skills/tailwind/references/bundle-remove-unused-plugins.md
create mode 100644 agent/skills/tailwind/references/bundle-split-critical-css.md
create mode 100644 agent/skills/tailwind/references/comp-avoid-apply-overuse.md
create mode 100644 agent/skills/tailwind/references/comp-container-customize.md
create mode 100644 agent/skills/tailwind/references/comp-reference-directive.md
create mode 100644 agent/skills/tailwind/references/comp-smart-sorting.md
create mode 100644 agent/skills/tailwind/references/comp-utility-file-scope.md
create mode 100644 agent/skills/tailwind/references/gen-avoid-theme-bloat.md
create mode 100644 agent/skills/tailwind/references/gen-css-first-config.md
create mode 100644 agent/skills/tailwind/references/gen-css-variable-syntax.md
create mode 100644 agent/skills/tailwind/references/gen-dynamic-utilities.md
create mode 100644 agent/skills/tailwind/references/gen-oklch-colors.md
create mode 100644 agent/skills/tailwind/references/gen-utility-directive.md
create mode 100644 agent/skills/tailwind/references/resp-container-queries.md
create mode 100644 agent/skills/tailwind/references/resp-custom-breakpoints.md
create mode 100644 agent/skills/tailwind/references/resp-hover-capability.md
create mode 100644 agent/skills/tailwind/references/resp-logical-properties.md
create mode 100644 agent/skills/tailwind/references/resp-mobile-first.md
create mode 100644 agent/skills/tailwind/references/theme-color-scheme.md
create mode 100644 agent/skills/tailwind/references/theme-dark-mode-class.md
create mode 100644 agent/skills/tailwind/references/theme-prefix-variables.md
create mode 100644 agent/skills/tailwind/references/theme-runtime-variables.md
create mode 100644 agent/skills/tailwind/references/theme-semantic-tokens.md
create mode 100644 agent/skills/tailwind/references/util-explicit-colors.md
create mode 100644 agent/skills/tailwind/references/util-gradient-via-none.md
create mode 100644 agent/skills/tailwind/references/util-important-modifier.md
create mode 100644 agent/skills/tailwind/references/util-opacity-modifier.md
create mode 100644 agent/skills/tailwind/references/util-renamed-utilities.md
create mode 100644 agent/skills/tailwind/references/util-variant-stacking.md
create mode 100644 agent/skills/tanstack-query/SKILL.md
create mode 100644 agent/skills/tanstack-query/references/cache-enabled-option.md
create mode 100644 agent/skills/tanstack-query/references/cache-global-defaults.md
create mode 100644 agent/skills/tanstack-query/references/cache-invalidation-precision.md
create mode 100644 agent/skills/tanstack-query/references/cache-placeholder-vs-initial.md
create mode 100644 agent/skills/tanstack-query/references/cache-refetch-triggers.md
create mode 100644 agent/skills/tanstack-query/references/cache-staletime-gctime.md
create mode 100644 agent/skills/tanstack-query/references/error-conditional-retry.md
create mode 100644 agent/skills/tanstack-query/references/error-display-patterns.md
create mode 100644 agent/skills/tanstack-query/references/error-global-handler.md
create mode 100644 agent/skills/tanstack-query/references/error-retry-config.md
create mode 100644 agent/skills/tanstack-query/references/error-throw-on-error.md
create mode 100644 agent/skills/tanstack-query/references/infinite-flatten-pages.md
create mode 100644 agent/skills/tanstack-query/references/infinite-loading-states.md
create mode 100644 agent/skills/tanstack-query/references/infinite-max-pages.md
create mode 100644 agent/skills/tanstack-query/references/infinite-refetch-behavior.md
create mode 100644 agent/skills/tanstack-query/references/mutation-avoid-parallel.md
create mode 100644 agent/skills/tanstack-query/references/mutation-cancel-queries.md
create mode 100644 agent/skills/tanstack-query/references/mutation-invalidate-onsettled.md
create mode 100644 agent/skills/tanstack-query/references/mutation-optimistic-updates.md
create mode 100644 agent/skills/tanstack-query/references/mutation-setquerydata.md
create mode 100644 agent/skills/tanstack-query/references/prefetch-avoid-waterfalls.md
create mode 100644 agent/skills/tanstack-query/references/prefetch-flatten-api.md
create mode 100644 agent/skills/tanstack-query/references/prefetch-in-queryfn.md
create mode 100644 agent/skills/tanstack-query/references/prefetch-infinite-query.md
create mode 100644 agent/skills/tanstack-query/references/prefetch-on-hover.md
create mode 100644 agent/skills/tanstack-query/references/prefetch-server-components.md
create mode 100644 agent/skills/tanstack-query/references/render-notify-props.md
create mode 100644 agent/skills/tanstack-query/references/render-select-derived.md
create mode 100644 agent/skills/tanstack-query/references/render-select-memoize.md
create mode 100644 agent/skills/tanstack-query/references/render-structural-sharing.md
create mode 100644 agent/skills/tanstack-query/references/render-tracked-props.md
create mode 100644 agent/skills/tanstack-query/references/suspense-boundaries-placement.md
create mode 100644 agent/skills/tanstack-query/references/suspense-error-boundaries.md
create mode 100644 agent/skills/tanstack-query/references/suspense-parallel-queries.md
create mode 100644 agent/skills/tanstack-query/references/suspense-use-suspense-hooks.md
create mode 100644 agent/skills/tanstack-query/references/tquery-always-arrays.md
create mode 100644 agent/skills/tanstack-query/references/tquery-colocate-keys.md
create mode 100644 agent/skills/tanstack-query/references/tquery-hierarchical-keys.md
create mode 100644 agent/skills/tanstack-query/references/tquery-key-factories.md
create mode 100644 agent/skills/tanstack-query/references/tquery-options-pattern.md
create mode 100644 agent/skills/tanstack-query/references/tquery-serializable-objects.md
create mode 100644 agent/skills/tdd/SKILL.md
create mode 100644 agent/skills/tdd/references/assert-custom-matchers.md
create mode 100644 agent/skills/tdd/references/assert-error-messages.md
create mode 100644 agent/skills/tdd/references/assert-no-assertions-antipattern.md
create mode 100644 agent/skills/tdd/references/assert-snapshot-testing.md
create mode 100644 agent/skills/tdd/references/assert-specific-assertions.md
create mode 100644 agent/skills/tdd/references/cycle-maintain-test-list.md
create mode 100644 agent/skills/tdd/references/cycle-minimal-code-to-pass.md
create mode 100644 agent/skills/tdd/references/cycle-refactor-after-green.md
create mode 100644 agent/skills/tdd/references/cycle-small-increments.md
create mode 100644 agent/skills/tdd/references/cycle-verify-test-fails-first.md
create mode 100644 agent/skills/tdd/references/cycle-write-test-first.md
create mode 100644 agent/skills/tdd/references/data-avoid-mystery-guests.md
create mode 100644 agent/skills/tdd/references/data-builder-pattern.md
create mode 100644 agent/skills/tdd/references/data-minimal-setup.md
create mode 100644 agent/skills/tdd/references/data-unique-identifiers.md
create mode 100644 agent/skills/tdd/references/data-use-factories.md
create mode 100644 agent/skills/tdd/references/design-aaa-pattern.md
create mode 100644 agent/skills/tdd/references/design-avoid-logic-in-tests.md
create mode 100644 agent/skills/tdd/references/design-descriptive-test-names.md
create mode 100644 agent/skills/tdd/references/design-one-assertion-per-test.md
create mode 100644 agent/skills/tdd/references/design-test-behavior-not-implementation.md
create mode 100644 agent/skills/tdd/references/design-test-edge-cases.md
create mode 100644 agent/skills/tdd/references/isolate-deterministic-tests.md
create mode 100644 agent/skills/tdd/references/isolate-mock-external-dependencies.md
create mode 100644 agent/skills/tdd/references/isolate-no-shared-state.md
create mode 100644 agent/skills/tdd/references/isolate-prefer-stubs-over-mocks.md
create mode 100644 agent/skills/tdd/references/isolate-use-dependency-injection.md
create mode 100644 agent/skills/tdd/references/org-file-structure.md
create mode 100644 agent/skills/tdd/references/org-group-by-behavior.md
create mode 100644 agent/skills/tdd/references/org-parameterized-tests.md
create mode 100644 agent/skills/tdd/references/org-setup-teardown.md
create mode 100644 agent/skills/tdd/references/org-test-utilities.md
create mode 100644 agent/skills/tdd/references/perf-avoid-network-calls.md
create mode 100644 agent/skills/tdd/references/perf-avoid-sleep.md
create mode 100644 agent/skills/tdd/references/perf-fast-unit-tests.md
create mode 100644 agent/skills/tdd/references/perf-fix-flaky-tests.md
create mode 100644 agent/skills/tdd/references/perf-parallelize-tests.md
create mode 100644 agent/skills/tdd/references/strat-coverage-targets.md
create mode 100644 agent/skills/tdd/references/strat-e2e-critical-paths.md
create mode 100644 agent/skills/tdd/references/strat-integration-boundaries.md
create mode 100644 agent/skills/tdd/references/strat-mutation-testing.md
create mode 100644 agent/skills/tdd/references/strat-test-pyramid.md
create mode 100644 agent/skills/typescript/SKILL.md
create mode 100644 agent/skills/typescript/references/advanced-branded-types.md
create mode 100644 agent/skills/typescript/references/advanced-satisfies-operator.md
create mode 100644 agent/skills/typescript/references/advanced-template-literal-types.md
create mode 100644 agent/skills/typescript/references/async-avoid-loop-await.md
create mode 100644 agent/skills/typescript/references/async-avoid-unnecessary-async.md
create mode 100644 agent/skills/typescript/references/async-defer-await.md
create mode 100644 agent/skills/typescript/references/async-explicit-return-types.md
create mode 100644 agent/skills/typescript/references/async-parallel-promises.md
create mode 100644 agent/skills/typescript/references/mem-avoid-closure-leaks.md
create mode 100644 agent/skills/typescript/references/mem-avoid-global-state.md
create mode 100644 agent/skills/typescript/references/mem-cleanup-event-listeners.md
create mode 100644 agent/skills/typescript/references/mem-clear-timers.md
create mode 100644 agent/skills/typescript/references/mem-use-weakmap-for-metadata.md
create mode 100644 agent/skills/typescript/references/module-avoid-barrel-imports.md
create mode 100644 agent/skills/typescript/references/module-avoid-circular-dependencies.md
create mode 100644 agent/skills/typescript/references/module-control-types-inclusion.md
create mode 100644 agent/skills/typescript/references/module-dynamic-imports.md
create mode 100644 agent/skills/typescript/references/module-use-type-imports.md
create mode 100644 agent/skills/typescript/references/runtime-avoid-object-spread-in-loops.md
create mode 100644 agent/skills/typescript/references/runtime-cache-property-access.md
create mode 100644 agent/skills/typescript/references/runtime-prefer-array-methods.md
create mode 100644 agent/skills/typescript/references/runtime-use-for-of-for-iteration.md
create mode 100644 agent/skills/typescript/references/runtime-use-set-for-lookups.md
create mode 100644 agent/skills/typescript/references/runtime-use-string-methods.md
create mode 100644 agent/skills/typescript/references/safety-assertion-functions.md
create mode 100644 agent/skills/typescript/references/safety-const-assertions.md
create mode 100644 agent/skills/typescript/references/safety-exhaustive-checks.md
create mode 100644 agent/skills/typescript/references/safety-prefer-unknown-over-any.md
create mode 100644 agent/skills/typescript/references/safety-strict-null-checks.md
create mode 100644 agent/skills/typescript/references/safety-use-type-guards.md
create mode 100644 agent/skills/typescript/references/tscfg-enable-incremental.md
create mode 100644 agent/skills/typescript/references/tscfg-exclude-properly.md
create mode 100644 agent/skills/typescript/references/tscfg-isolate-modules.md
create mode 100644 agent/skills/typescript/references/tscfg-project-references.md
create mode 100644 agent/skills/typescript/references/tscfg-skip-lib-check.md
create mode 100644 agent/skills/typescript/references/tscfg-strict-function-types.md
create mode 100644 agent/skills/typescript/references/tscfg-typescript-7.md
create mode 100644 agent/skills/typescript/references/type-avoid-deep-generics.md
create mode 100644 agent/skills/typescript/references/type-avoid-large-unions.md
create mode 100644 agent/skills/typescript/references/type-explicit-return-types.md
create mode 100644 agent/skills/typescript/references/type-extract-conditional-types.md
create mode 100644 agent/skills/typescript/references/type-interfaces-over-intersections.md
create mode 100644 agent/skills/typescript/references/type-limit-recursion-depth.md
create mode 100644 agent/skills/typescript/references/type-simplify-mapped-types.md
create mode 100644 agent/skills/ui-design/SKILL.md
create mode 100644 agent/skills/ui-design/references/access-alt-text.md
create mode 100644 agent/skills/ui-design/references/access-aria-labels.md
create mode 100644 agent/skills/ui-design/references/access-focus-indicators.md
create mode 100644 agent/skills/ui-design/references/access-heading-hierarchy.md
create mode 100644 agent/skills/ui-design/references/access-keyboard-navigation.md
create mode 100644 agent/skills/ui-design/references/access-semantic-html.md
create mode 100644 agent/skills/ui-design/references/access-target-size.md
create mode 100644 agent/skills/ui-design/references/anim-duration-easing.md
create mode 100644 agent/skills/ui-design/references/anim-gpu-properties.md
create mode 100644 agent/skills/ui-design/references/anim-reduced-motion.md
create mode 100644 agent/skills/ui-design/references/anim-will-change.md
create mode 100644 agent/skills/ui-design/references/color-contrast-ratio.md
create mode 100644 agent/skills/ui-design/references/color-dark-mode.md
create mode 100644 agent/skills/ui-design/references/color-not-only-indicator.md
create mode 100644 agent/skills/ui-design/references/color-semantic-palette.md
create mode 100644 agent/skills/ui-design/references/cwv-critical-css.md
create mode 100644 agent/skills/ui-design/references/cwv-improve-inp.md
create mode 100644 agent/skills/ui-design/references/cwv-lazy-load-offscreen.md
create mode 100644 agent/skills/ui-design/references/cwv-minimize-cls.md
create mode 100644 agent/skills/ui-design/references/cwv-optimize-lcp.md
create mode 100644 agent/skills/ui-design/references/cwv-responsive-images.md
create mode 100644 agent/skills/ui-design/references/form-autocomplete.md
create mode 100644 agent/skills/ui-design/references/form-error-messages.md
create mode 100644 agent/skills/ui-design/references/form-inline-validation.md
create mode 100644 agent/skills/ui-design/references/form-input-types.md
create mode 100644 agent/skills/ui-design/references/form-labels-above.md
create mode 100644 agent/skills/ui-design/references/layout-f-pattern.md
create mode 100644 agent/skills/ui-design/references/layout-grid-system.md
create mode 100644 agent/skills/ui-design/references/layout-proximity-grouping.md
create mode 100644 agent/skills/ui-design/references/layout-single-cta.md
create mode 100644 agent/skills/ui-design/references/layout-visual-hierarchy.md
create mode 100644 agent/skills/ui-design/references/layout-whitespace.md
create mode 100644 agent/skills/ui-design/references/resp-container-queries.md
create mode 100644 agent/skills/ui-design/references/resp-fluid-typography.md
create mode 100644 agent/skills/ui-design/references/resp-mobile-first.md
create mode 100644 agent/skills/ui-design/references/resp-touch-targets.md
create mode 100644 agent/skills/ui-design/references/resp-viewport-meta.md
create mode 100644 agent/skills/ui-design/references/typo-font-display.md
create mode 100644 agent/skills/ui-design/references/typo-line-height.md
create mode 100644 agent/skills/ui-design/references/typo-preload-fonts.md
create mode 100644 agent/skills/ui-design/references/typo-readable-line-length.md
create mode 100644 agent/skills/ui-design/references/typo-system-font-stack.md
create mode 100644 agent/skills/vercel-composition-patterns/SKILL.md
create mode 100644 agent/skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md
create mode 100644 agent/skills/vercel-composition-patterns/rules/architecture-compound-components.md
create mode 100644 agent/skills/vercel-composition-patterns/rules/patterns-children-over-render-props.md
create mode 100644 agent/skills/vercel-composition-patterns/rules/patterns-explicit-variants.md
create mode 100644 agent/skills/vercel-composition-patterns/rules/react19-no-forwardref.md
create mode 100644 agent/skills/vercel-composition-patterns/rules/state-context-interface.md
create mode 100644 agent/skills/vercel-composition-patterns/rules/state-decouple-implementation.md
create mode 100644 agent/skills/vercel-composition-patterns/rules/state-lift-state.md
create mode 100644 agent/skills/vercel-react-best-practices/SKILL.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/advanced-effect-event-deps.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/advanced-event-handler-refs.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/advanced-init-once.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/advanced-use-latest.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/async-api-routes.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/async-cheap-condition-before-await.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/async-defer-await.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/async-dependencies.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/async-parallel.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/async-suspense-boundaries.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-analyzable-paths.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-barrel-imports.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-conditional.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-defer-third-party.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-dynamic-imports.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/bundle-preload.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/client-event-listeners.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/client-localstorage-schema.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/client-passive-event-listeners.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/client-swr-dedup.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-batch-dom-css.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-cache-function-results.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-cache-property-access.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-cache-storage.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-combine-iterations.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-early-exit.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-flatmap-filter.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-hoist-regexp.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-index-maps.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-length-check-first.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-min-max-loop.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-request-idle-callback.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-set-map-lookups.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/js-tosorted-immutable.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-activity.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-animate-svg-wrapper.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-conditional-render.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-content-visibility.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-hoist-jsx.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-hydration-no-flicker.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-hydration-suppress-warning.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-resource-hints.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-script-defer-async.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-svg-precision.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rendering-usetransition-loading.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-defer-reads.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-dependencies.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-derived-state-no-effect.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-derived-state.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-functional-setstate.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-lazy-state-init.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-memo-with-default-value.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-memo.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-move-effect-to-event.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-no-inline-components.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-simple-expression-in-memo.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-split-combined-hooks.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-transitions.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-use-deferred-value.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/rerender-use-ref-transient-values.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-after-nonblocking.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-auth-actions.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-cache-lru.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-cache-react.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-dedup-props.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-hoist-static-io.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-no-shared-module-state.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-parallel-fetching.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-parallel-nested-fetching.md
create mode 100644 agent/skills/vercel-react-best-practices/rules/server-serialization.md
create mode 100644 agent/skills/vitest/SKILL.md
create mode 100644 agent/skills/vitest/references/assert-edge-cases.md
create mode 100644 agent/skills/vitest/references/assert-expect-assertions.md
create mode 100644 agent/skills/vitest/references/assert-one-assertion-concept.md
create mode 100644 agent/skills/vitest/references/assert-specific-matchers.md
create mode 100644 agent/skills/vitest/references/assert-toequal-vs-tobe.md
create mode 100644 agent/skills/vitest/references/async-act-wrapper.md
create mode 100644 agent/skills/vitest/references/async-await-assertions.md
create mode 100644 agent/skills/vitest/references/async-concurrent-expect.md
create mode 100644 agent/skills/vitest/references/async-error-handling.md
create mode 100644 agent/skills/vitest/references/async-fake-timers.md
create mode 100644 agent/skills/vitest/references/async-return-promises.md
create mode 100644 agent/skills/vitest/references/async-waitfor-polling.md
create mode 100644 agent/skills/vitest/references/env-browser-api-mocking.md
create mode 100644 agent/skills/vitest/references/env-globals-config.md
create mode 100644 agent/skills/vitest/references/env-per-file-override.md
create mode 100644 agent/skills/vitest/references/env-setup-files.md
create mode 100644 agent/skills/vitest/references/mock-avoid-overmocking.md
create mode 100644 agent/skills/vitest/references/mock-clear-between-tests.md
create mode 100644 agent/skills/vitest/references/mock-implementation-not-value.md
create mode 100644 agent/skills/vitest/references/mock-msw-network.md
create mode 100644 agent/skills/vitest/references/mock-spyon-vs-mock.md
create mode 100644 agent/skills/vitest/references/mock-type-safety.md
create mode 100644 agent/skills/vitest/references/mock-vi-mock-hoisting.md
create mode 100644 agent/skills/vitest/references/org-describe-nesting.md
create mode 100644 agent/skills/vitest/references/org-file-colocation.md
create mode 100644 agent/skills/vitest/references/org-test-naming.md
create mode 100644 agent/skills/vitest/references/org-test-skip-only.md
create mode 100644 agent/skills/vitest/references/perf-bail-fast-fail.md
create mode 100644 agent/skills/vitest/references/perf-bench-test-context.md
create mode 100644 agent/skills/vitest/references/perf-disable-isolation.md
create mode 100644 agent/skills/vitest/references/perf-happy-dom.md
create mode 100644 agent/skills/vitest/references/perf-pool-selection.md
create mode 100644 agent/skills/vitest/references/perf-run-mode-ci.md
create mode 100644 agent/skills/vitest/references/perf-sharding.md
create mode 100644 agent/skills/vitest/references/setup-avoid-shared-state.md
create mode 100644 agent/skills/vitest/references/setup-beforeall-expensive.md
create mode 100644 agent/skills/vitest/references/setup-beforeeach-cleanup.md
create mode 100644 agent/skills/vitest/references/setup-reset-modules.md
create mode 100644 agent/skills/vitest/references/setup-restore-mocks.md
create mode 100644 agent/skills/vitest/references/setup-test-factories.md
create mode 100644 agent/skills/vitest/references/setup-vitest5-migration.md
create mode 100644 agent/skills/vitest/references/snap-avoid-large.md
create mode 100644 agent/skills/vitest/references/snap-describe-intent.md
create mode 100644 agent/skills/vitest/references/snap-inline-over-file.md
create mode 100644 agent/skills/vitest/references/snap-review-updates.md
create mode 100644 agent/skills/vitest/references/snap-stable-serialization.md
create mode 100644 agent/skills/web-design-guidelines/SKILL.md
create mode 100644 agent/skills/zod/SKILL.md
create mode 100644 agent/skills/zod/references/compose-intersection.md
create mode 100644 agent/skills/zod/references/compose-lazy-recursive.md
create mode 100644 agent/skills/zod/references/compose-pipe.md
create mode 100644 agent/skills/zod/references/compose-preprocess.md
create mode 100644 agent/skills/zod/references/compose-shared-schemas.md
create mode 100644 agent/skills/zod/references/error-avoid-throwing-in-refine.md
create mode 100644 agent/skills/zod/references/error-custom-messages.md
create mode 100644 agent/skills/zod/references/error-i18n.md
create mode 100644 agent/skills/zod/references/error-path-for-nested.md
create mode 100644 agent/skills/zod/references/error-use-flatten.md
create mode 100644 agent/skills/zod/references/object-discriminated-unions.md
create mode 100644 agent/skills/zod/references/object-extend-for-composition.md
create mode 100644 agent/skills/zod/references/object-optional-vs-nullable.md
create mode 100644 agent/skills/zod/references/object-partial-for-updates.md
create mode 100644 agent/skills/zod/references/object-pick-omit.md
create mode 100644 agent/skills/zod/references/object-strict-vs-strip.md
create mode 100644 agent/skills/zod/references/parse-async-for-async-refinements.md
create mode 100644 agent/skills/zod/references/parse-avoid-double-validation.md
create mode 100644 agent/skills/zod/references/parse-handle-all-issues.md
create mode 100644 agent/skills/zod/references/parse-never-trust-json.md
create mode 100644 agent/skills/zod/references/parse-use-safeparse.md
create mode 100644 agent/skills/zod/references/parse-validate-early.md
create mode 100644 agent/skills/zod/references/parse-validate-for-boolean-checks.md
create mode 100644 agent/skills/zod/references/perf-arrays.md
create mode 100644 agent/skills/zod/references/perf-avoid-dynamic-creation.md
create mode 100644 agent/skills/zod/references/perf-cache-schemas.md
create mode 100644 agent/skills/zod/references/perf-compile-schemas.md
create mode 100644 agent/skills/zod/references/perf-lazy-loading.md
create mode 100644 agent/skills/zod/references/perf-zod-mini.md
create mode 100644 agent/skills/zod/references/refine-add-path.md
create mode 100644 agent/skills/zod/references/refine-catch.md
create mode 100644 agent/skills/zod/references/refine-defaults.md
create mode 100644 agent/skills/zod/references/refine-transform-coerce.md
create mode 100644 agent/skills/zod/references/refine-use-codec.md
create mode 100644 agent/skills/zod/references/refine-vs-superrefine.md
create mode 100644 agent/skills/zod/references/schema-avoid-optional-abuse.md
create mode 100644 agent/skills/zod/references/schema-coercion-for-form-data.md
create mode 100644 agent/skills/zod/references/schema-string-validations.md
create mode 100644 agent/skills/zod/references/schema-use-enums.md
create mode 100644 agent/skills/zod/references/schema-use-primitives-correctly.md
create mode 100644 agent/skills/zod/references/schema-use-unknown-not-any.md
create mode 100644 agent/skills/zod/references/type-branded-types.md
create mode 100644 agent/skills/zod/references/type-enable-strict-mode.md
create mode 100644 agent/skills/zod/references/type-export-schemas-and-types.md
create mode 100644 agent/skills/zod/references/type-input-vs-output.md
create mode 100644 agent/skills/zod/references/type-use-z-infer.md
create mode 100644 certs/.gitignore
create mode 100644 compose.dbs.yaml
create mode 100644 compose.yaml
create mode 100644 docs/ARCHITECTURE.md
create mode 100644 docs/DESIGN.md
create mode 100644 docs/MIGRATION.md
create mode 100644 docs/OPERATIONS.md
create mode 100644 docs/PRODUCT.md
create mode 100644 docs/README_PL.md
create mode 100644 docs/ROADMAP.md
create mode 100644 docs/SECURITY.md
rename BackupService_MapaMysli.png => docs/diagrams/BackupService_MapaMysli.png (100%)
rename ServiceLogicProject.drawio => docs/diagrams/ServiceLogicProject.drawio (100%)
rename ServiceLogicProject_v1.0_Drawio.jpg => docs/diagrams/ServiceLogicProject_v1.0_Drawio.jpg (100%)
rename ServiceLogicProject_v1.2_Drawio.png => docs/diagrams/ServiceLogicProject_v1.2_Drawio.png (100%)
create mode 100644 global.json
create mode 100644 scripts/check-compose.mjs
create mode 100644 scripts/dev.mjs
create mode 100644 skills-lock.json
diff --git a/.agents/skills/feature-arch/SKILL.md b/.agents/skills/feature-arch/SKILL.md
new file mode 100644
index 0000000..f9552bc
--- /dev/null
+++ b/.agents/skills/feature-arch/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: feature-arch
+description: Feature-based React folder structure and module boundaries.
+---
+
+# Feature-Based Architecture Best Practices
+
+Comprehensive architecture guide for organizing React applications by features, enabling scalable development with independent teams. Contains 42 rules across 8 categories, prioritized by impact from critical (directory structure, imports) to incremental (naming conventions).
+
+## When to Apply
+
+Reference these guidelines when:
+- Creating new features or modules
+- Organizing project directory structure
+- Setting up import rules and boundaries
+- Implementing data fetching patterns
+- Composing components from multiple features
+- Reviewing code for architecture violations
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Directory Structure | CRITICAL | `struct-` |
+| 2 | Import & Dependencies | CRITICAL | `import-` |
+| 3 | Module Boundaries | HIGH | `bound-` |
+| 4 | Data Fetching | HIGH | `fquery-` |
+| 5 | Component Organization | MEDIUM-HIGH | `fcomp-` |
+| 6 | State Management | MEDIUM | `fstate-` |
+| 7 | Testing Strategy | MEDIUM | `test-` |
+| 8 | Naming Conventions | LOW | `name-` |
+
+## Quick Reference
+
+### 1. Directory Structure (CRITICAL)
+
+- `struct-feature-folders` - Organize by feature, not technical type
+- `struct-feature-self-contained` - Make features self-contained
+- `struct-shared-layer` - Use shared layer for truly generic code only
+- `struct-flat-hierarchy` - Keep directory hierarchy flat
+- `struct-optional-segments` - Include only necessary segments
+- `struct-app-layer` - Separate app layer from features
+
+### 2. Import & Dependencies (CRITICAL)
+
+- `import-unidirectional-flow` - Enforce unidirectional import flow
+- `import-no-cross-feature` - Prohibit cross-feature imports
+- `import-public-api` - Export through public API only
+- `import-avoid-barrel-files` - Avoid deep barrel file re-exports
+- `import-path-aliases` - Use consistent path aliases
+- `import-type-only` - Use type-only imports for types
+
+### 3. Module Boundaries (HIGH)
+
+- `bound-feature-isolation` - Enforce feature isolation
+- `bound-interface-contracts` - Define explicit interface contracts
+- `bound-feature-scoped-routing` - Scope routing to feature concerns
+- `bound-minimize-shared-state` - Minimize shared state between features
+- `bound-event-based-communication` - Use events for cross-feature communication
+- `bound-feature-size` - Keep features appropriately sized
+
+### 4. Data Fetching (HIGH)
+
+- `fquery-single-responsibility` - Keep query functions single-purpose
+- `fquery-colocate-with-feature` - Colocate data fetching with features
+- `fquery-parallel-fetching` - Fetch independent data in parallel
+- `fquery-avoid-n-plus-one` - Avoid N+1 query patterns
+- `fquery-feature-scoped-keys` - Use feature-scoped query keys
+- `fquery-server-component-fetching` - Fetch at server component level
+
+### 5. Component Organization (MEDIUM-HIGH)
+
+- `fcomp-single-responsibility` - Apply single responsibility to components
+- `fcomp-composition-over-props` - Prefer composition over prop drilling
+- `fcomp-container-presentational` - Separate container and presentational concerns
+- `fcomp-props-as-data-boundary` - Use props as feature boundaries
+- `fcomp-colocate-styles` - Colocate styles with components
+- `fcomp-error-boundaries` - Use feature-level error boundaries
+
+### 6. State Management (MEDIUM)
+
+- `fstate-feature-scoped-stores` - Scope state stores to features
+- `fstate-server-state-separation` - Separate server state from client state
+- `fstate-lift-minimally` - Lift state only as high as necessary
+- `fstate-context-sparingly` - Use context sparingly for feature state
+- `fstate-reset-on-unmount` - Reset feature state on unmount
+
+### 7. Testing Strategy (MEDIUM)
+
+- `test-colocate-with-feature` - Colocate tests with features
+- `test-feature-isolation` - Test features in isolation
+- `test-shared-utilities` - Create feature-specific test utilities
+- `test-integration-at-app-layer` - Write integration tests at app layer
+
+### 8. Naming Conventions (LOW)
+
+- `name-feature-naming` - Use domain-driven feature names
+- `name-file-conventions` - Use consistent file naming conventions
+- `name-descriptive-exports` - Use descriptive export names
+
+## How to Use
+
+Read `references/.md` for each rule above that matches the task: why it matters, then incorrect vs. correct code.
+
+The layering and boundary rules align with Feature-Sliced Design (FSD), the most widely adopted React architecture standard; see [feature-sliced.design](https://feature-sliced.design/) for the full methodology.
+
+## Related Skills
+
+- For data fetching, see `tanstack-query` skill
+- For React component patterns, see `react` skill
diff --git a/.agents/skills/feature-arch/references/bound-event-based-communication.md b/.agents/skills/feature-arch/references/bound-event-based-communication.md
new file mode 100644
index 0000000..9fc72ed
--- /dev/null
+++ b/.agents/skills/feature-arch/references/bound-event-based-communication.md
@@ -0,0 +1,84 @@
+---
+title: Use Events for Cross-Feature Communication
+impact: MEDIUM-HIGH
+impactDescription: Decouples features at runtime; enables loose coupling without direct imports
+tags: bound, events, communication, decoupling
+---
+
+## Use Events for Cross-Feature Communication
+
+When features must communicate without direct dependencies, use an event-based approach. This keeps features loosely coupled while allowing them to react to each other's actions.
+
+**Incorrect (direct coupling):**
+
+```typescript
+// src/features/order/hooks/useOrder.ts
+import { clearCart } from '@/features/cart/stores/cartStore';
+import { showNotification } from '@/features/notification/stores/notificationStore';
+import { sendAnalytics } from '@/features/analytics/utils/analytics';
+
+export function useOrder() {
+ async function submitOrder(data: OrderData) {
+ const order = await createOrder(data);
+
+ // Directly calling into other features
+ clearCart();
+ showNotification({ type: 'success', message: 'Order placed!' });
+ sendAnalytics('order_completed', { orderId: order.id });
+ }
+}
+```
+
+**Correct (event-based communication):**
+
+```typescript
+// src/shared/events/eventBus.ts
+type EventMap = {
+ 'order:completed': { orderId: string; total: number };
+ 'order:failed': { error: string };
+ 'user:logged-in': { userId: string };
+ 'user:logged-out': void;
+};
+
+export const eventBus = createEventBus();
+
+// src/features/order/hooks/useOrder.ts
+import { eventBus } from '@/shared/events/eventBus';
+
+export function useOrder() {
+ async function submitOrder(data: OrderData) {
+ const order = await createOrder(data);
+ eventBus.emit('order:completed', { orderId: order.id, total: order.total });
+ }
+}
+
+// src/features/cart/hooks/useCartSync.ts
+import { eventBus } from '@/shared/events/eventBus';
+import { useCartStore } from '../stores/cartStore';
+
+export function useCartSync() {
+ useEffect(() => {
+ return eventBus.on('order:completed', () => {
+ useCartStore.getState().clearCart();
+ });
+ }, []);
+}
+
+// src/features/notification/hooks/useOrderNotifications.ts
+import { eventBus } from '@/shared/events/eventBus';
+
+export function useOrderNotifications() {
+ useEffect(() => {
+ return eventBus.on('order:completed', ({ orderId }) => {
+ showNotification({ type: 'success', message: `Order ${orderId} placed!` });
+ });
+ }, []);
+}
+```
+
+**Benefits:**
+- Order feature doesn't know about cart, notifications, or analytics
+- New features can subscribe to events without modifying order
+- Easy to test each feature in isolation
+
+Reference: [Feature-Sliced Design](https://feature-sliced.design/)
diff --git a/.agents/skills/feature-arch/references/bound-feature-isolation.md b/.agents/skills/feature-arch/references/bound-feature-isolation.md
new file mode 100644
index 0000000..74182c0
--- /dev/null
+++ b/.agents/skills/feature-arch/references/bound-feature-isolation.md
@@ -0,0 +1,88 @@
+---
+title: Enforce Feature Isolation
+impact: HIGH
+impactDescription: Changes in one feature have zero impact on others; enables fearless refactoring
+tags: bound, isolation, coupling, independence
+---
+
+## Enforce Feature Isolation
+
+Each feature should be modifiable, testable, and deployable without affecting other features. When features are isolated, refactoring is safe and localized. When they're coupled, every change risks cascading failures.
+
+**Incorrect (coupled features):**
+
+```typescript
+// src/features/order/hooks/useOrder.ts
+import { useCart } from '@/features/cart/hooks/useCart';
+import { useUser } from '@/features/user/hooks/useUser';
+import { usePayment } from '@/features/payment/hooks/usePayment';
+
+export function useOrder() {
+ const cart = useCart();
+ const user = useUser();
+ const payment = usePayment();
+
+ // Tightly coupled to 3 other features
+ // Change in any feature can break orders
+ async function submitOrder() {
+ const order = {
+ items: cart.items,
+ userId: user.id,
+ paymentMethod: payment.selectedMethod,
+ };
+ // ...
+ }
+}
+```
+
+**Correct (isolated with dependency injection):**
+
+```typescript
+// src/features/order/hooks/useOrder.ts
+interface OrderDependencies {
+ items: CartItem[];
+ userId: string;
+ paymentMethod: PaymentMethod;
+}
+
+export function useOrder() {
+ async function submitOrder(deps: OrderDependencies) {
+ const order = {
+ items: deps.items,
+ userId: deps.userId,
+ paymentMethod: deps.paymentMethod,
+ };
+ // ...
+ }
+
+ return { submitOrder };
+}
+
+// src/app/pages/CheckoutPage.tsx - composition at app layer
+import { useCart } from '@/features/cart';
+import { useUser } from '@/features/user';
+import { usePayment } from '@/features/payment';
+import { useOrder } from '@/features/order';
+
+export function CheckoutPage() {
+ const cart = useCart();
+ const user = useUser();
+ const payment = usePayment();
+ const order = useOrder();
+
+ const handleSubmit = () => {
+ order.submitOrder({
+ items: cart.items,
+ userId: user.id,
+ paymentMethod: payment.selectedMethod,
+ });
+ };
+}
+```
+
+**Benefits:**
+- Order feature can be tested with mock dependencies
+- Cart, user, and payment can change without breaking orders
+- Clear contract between features
+
+Reference: [Feature-Sliced Design](https://feature-sliced.design/)
diff --git a/.agents/skills/feature-arch/references/bound-feature-scoped-routing.md b/.agents/skills/feature-arch/references/bound-feature-scoped-routing.md
new file mode 100644
index 0000000..69e00bb
--- /dev/null
+++ b/.agents/skills/feature-arch/references/bound-feature-scoped-routing.md
@@ -0,0 +1,76 @@
+---
+title: Scope Routing to Feature Concerns
+impact: HIGH
+impactDescription: Enables feature-level code splitting; prevents routing configuration sprawl
+tags: bound, routing, scope, navigation
+---
+
+## Scope Routing to Feature Concerns
+
+Route definitions belong in the app layer, but route parameters and navigation logic relevant to a feature can be encapsulated within that feature. This keeps routing concerns organized while maintaining the app layer's ownership of the route tree.
+
+**Incorrect (routing logic scattered):**
+
+```typescript
+// src/features/user/components/UserProfile.tsx
+import { useNavigate, useParams } from 'react-router-dom';
+
+export function UserProfile() {
+ const navigate = useNavigate();
+ const { userId } = useParams(); // Feature assumes route structure
+
+ const goToSettings = () => {
+ navigate(`/users/${userId}/settings`); // Hardcoded route
+ };
+}
+```
+
+**Correct (feature owns its route utilities):**
+
+```typescript
+// src/features/user/routes.ts
+export const userRoutes = {
+ profile: (userId: string) => `/users/${userId}`,
+ settings: (userId: string) => `/users/${userId}/settings`,
+ orders: (userId: string) => `/users/${userId}/orders`,
+} as const;
+
+// src/features/user/hooks/useUserParams.ts
+import { useParams } from 'react-router-dom';
+
+export function useUserParams() {
+ const { userId } = useParams<{ userId: string }>();
+ if (!userId) throw new Error('userId is required');
+ return { userId };
+}
+
+// src/features/user/components/UserProfile.tsx
+import { useNavigate } from 'react-router-dom';
+import { userRoutes } from '../routes';
+import { useUserParams } from '../hooks/useUserParams';
+
+export function UserProfile() {
+ const navigate = useNavigate();
+ const { userId } = useUserParams();
+
+ const goToSettings = () => {
+ navigate(userRoutes.settings(userId)); // Uses feature's route builder
+ };
+}
+
+// src/app/routes/index.tsx
+import { userRoutes } from '@/features/user';
+import { UserProfile, UserSettings } from '@/features/user';
+
+export const routes = [
+ { path: userRoutes.profile(':userId'), element: },
+ { path: userRoutes.settings(':userId'), element: },
+];
+```
+
+**Benefits:**
+- Route paths are centralized per feature
+- Refactoring routes only requires changes in one place
+- Type-safe route parameters
+
+Reference: [Feature-Sliced Design](https://feature-sliced.design/)
diff --git a/.agents/skills/feature-arch/references/bound-feature-size.md b/.agents/skills/feature-arch/references/bound-feature-size.md
new file mode 100644
index 0000000..c8895fe
--- /dev/null
+++ b/.agents/skills/feature-arch/references/bound-feature-size.md
@@ -0,0 +1,74 @@
+---
+title: Keep Features Appropriately Sized
+impact: MEDIUM
+impactDescription: Right-sized features balance cohesion and manageability
+tags: bound, size, cohesion, splitting
+---
+
+## Keep Features Appropriately Sized
+
+Features should be large enough to be meaningful but small enough to be maintainable. A feature that's too small creates unnecessary fragmentation; one that's too large becomes a mini-monolith.
+
+**Incorrect (too granular):**
+
+```
+src/features/
+├── user-avatar/ # Too small - just one component
+├── user-name/ # Too small
+├── user-email/ # Too small
+├── user-profile/ # Could contain all of these
+└── user-settings/
+```
+
+**Incorrect (too large):**
+
+```
+src/features/
+└── user/
+ ├── components/
+ │ ├── UserAvatar.tsx
+ │ ├── UserProfile.tsx
+ │ ├── UserSettings.tsx
+ │ ├── UserOrders.tsx # Orders is a separate domain
+ │ ├── UserPayments.tsx # Payments is a separate domain
+ │ ├── UserSubscription.tsx # Subscription is a separate domain
+ │ └── ... 30 more files
+ └── hooks/
+ └── ... 20 hooks
+```
+
+**Correct (cohesive features):**
+
+```
+src/features/
+├── user/ # Core user identity
+│ ├── components/
+│ │ ├── UserAvatar.tsx
+│ │ ├── UserProfile.tsx
+│ │ └── UserSettings.tsx
+│ └── hooks/
+│ └── useUser.ts
+├── orders/ # Separate domain
+│ ├── components/
+│ │ ├── OrderList.tsx
+│ │ └── OrderDetail.tsx
+│ └── hooks/
+│ └── useOrders.ts
+├── payments/ # Separate domain
+│ └── ...
+└── subscription/ # Separate domain
+ └── ...
+```
+
+**Sizing guidelines:**
+- 5-15 components per feature is typical
+- If a feature has 20+ files, consider splitting
+- If a feature has only 1-2 files, consider merging
+- Features should map to business domains, not UI components
+
+**Signs a feature is too large:**
+- Multiple developers frequently conflict in the same feature
+- Parts of the feature change at different rates
+- Some parts are used independently of others
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/bound-interface-contracts.md b/.agents/skills/feature-arch/references/bound-interface-contracts.md
new file mode 100644
index 0000000..ac07bd4
--- /dev/null
+++ b/.agents/skills/feature-arch/references/bound-interface-contracts.md
@@ -0,0 +1,83 @@
+---
+title: Define Explicit Interface Contracts
+impact: HIGH
+impactDescription: Prevents implicit dependencies; enables parallel feature development
+tags: bound, interfaces, contracts, types
+---
+
+## Define Explicit Interface Contracts
+
+When features need to interact, define explicit interfaces that describe the contract. This makes dependencies visible and allows features to be developed in parallel against the contract.
+
+**Incorrect (implicit interface):**
+
+```typescript
+// src/features/checkout/components/CheckoutForm.tsx
+export function CheckoutForm({ onSuccess }) {
+ // What shape does onSuccess expect?
+ // What data should be passed?
+ const handleSubmit = () => {
+ onSuccess(someData); // Caller must guess the shape
+ };
+}
+```
+
+**Correct (explicit contract):**
+
+```typescript
+// src/features/checkout/types.ts
+export interface CheckoutResult {
+ orderId: string;
+ total: number;
+ items: Array<{ id: string; quantity: number }>;
+}
+
+export interface CheckoutFormProps {
+ userId: string;
+ cartItems: CartItem[];
+ onSuccess: (result: CheckoutResult) => void;
+ onError: (error: CheckoutError) => void;
+}
+
+// src/features/checkout/components/CheckoutForm.tsx
+export function CheckoutForm({ userId, cartItems, onSuccess, onError }: CheckoutFormProps) {
+ const handleSubmit = async () => {
+ try {
+ const result = await processCheckout(userId, cartItems);
+ onSuccess({
+ orderId: result.id,
+ total: result.total,
+ items: result.items.map(i => ({ id: i.id, quantity: i.qty })),
+ });
+ } catch (err) {
+ onError(normalizeError(err));
+ }
+ };
+}
+```
+
+**Contract patterns:**
+
+```typescript
+// Render prop contract
+interface UserListProps {
+ renderUser: (user: User) => ReactNode;
+ renderEmpty?: () => ReactNode;
+}
+
+// Slot contract
+interface DashboardProps {
+ header: ReactNode;
+ sidebar: ReactNode;
+ content: ReactNode;
+}
+
+// Data contract
+interface AnalyticsEvent {
+ name: string;
+ properties: Record;
+ timestamp: number;
+}
+```
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/bound-minimize-shared-state.md b/.agents/skills/feature-arch/references/bound-minimize-shared-state.md
new file mode 100644
index 0000000..2ec1e12
--- /dev/null
+++ b/.agents/skills/feature-arch/references/bound-minimize-shared-state.md
@@ -0,0 +1,73 @@
+---
+title: Minimize Shared State Between Features
+impact: HIGH
+impactDescription: Reduces coupling surface area; prevents state synchronization bugs
+tags: bound, state, coupling, shared
+---
+
+## Minimize Shared State Between Features
+
+When multiple features share state, they become implicitly coupled. Changes to that state affect all dependent features. Prefer passing data as props or using feature-local state with explicit synchronization points.
+
+**Incorrect (shared global state):**
+
+```typescript
+// src/stores/globalStore.ts
+export const globalStore = create((set) => ({
+ user: null,
+ cart: { items: [] },
+ notifications: [],
+ theme: 'light',
+ // Every feature reaches into this store
+}));
+
+// src/features/checkout/components/CheckoutForm.tsx
+import { globalStore } from '@/stores/globalStore';
+
+export function CheckoutForm() {
+ const cart = globalStore(s => s.cart);
+ const user = globalStore(s => s.user);
+ // Checkout is now coupled to global store shape
+}
+```
+
+**Correct (feature-scoped state with explicit boundaries):**
+
+```typescript
+// src/features/cart/stores/cartStore.ts
+export const useCartStore = create((set) => ({
+ items: [],
+ addItem: (item) => set(s => ({ items: [...s.items, item] })),
+ removeItem: (id) => set(s => ({ items: s.items.filter(i => i.id !== id) })),
+}));
+
+// src/features/cart/index.ts
+export { useCartStore } from './stores/cartStore';
+export type { CartItem } from './types';
+
+// src/app/pages/CheckoutPage.tsx
+import { useCartStore } from '@/features/cart';
+import { CheckoutForm } from '@/features/checkout';
+
+export function CheckoutPage() {
+ const items = useCartStore(s => s.items);
+ // App layer reads cart and passes to checkout
+ return ;
+}
+
+// src/features/checkout/components/CheckoutForm.tsx
+interface CheckoutFormProps {
+ items: CartItem[]; // Receives data via props, not global state
+}
+
+export function CheckoutForm({ items }: CheckoutFormProps) {
+ // No knowledge of cart store
+}
+```
+
+**When shared state is acceptable:**
+- Auth state (current user) - rarely changes, many features need it
+- Theme/locale - application-wide concerns
+- Feature flags - read-only, system-level
+
+Reference: [Feature-Sliced Design](https://feature-sliced.design/)
diff --git a/.agents/skills/feature-arch/references/fcomp-colocate-styles.md b/.agents/skills/feature-arch/references/fcomp-colocate-styles.md
new file mode 100644
index 0000000..c078fc0
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fcomp-colocate-styles.md
@@ -0,0 +1,88 @@
+---
+title: Colocate Styles with Components
+impact: MEDIUM
+impactDescription: Enables complete component portability; prevents orphaned styles
+tags: comp, styles, colocation, css
+---
+
+## Colocate Styles with Components
+
+Keep component styles in the same location as the component. When styles are centralized or in a global stylesheet, components lose independence and style changes become risky.
+
+**Incorrect (centralized styles):**
+
+```
+src/
+├── styles/
+│ ├── components/
+│ │ ├── UserCard.css
+│ │ ├── PostList.css
+│ │ └── CommentSection.css
+│ └── global.css
+└── features/
+ └── user/
+ └── components/
+ └── UserCard.tsx # Imports from ../../styles/components/
+```
+
+**Correct (colocated styles):**
+
+```
+src/features/user/
+├── components/
+│ ├── UserCard.tsx
+│ ├── UserCard.module.css # CSS Modules
+│ └── UserAvatar.tsx
+└── ...
+```
+
+```typescript
+// src/features/user/components/UserCard.tsx
+import styles from './UserCard.module.css';
+
+export function UserCard({ user }: { user: User }) {
+ return (
+
+
+
{user.name}
+
+ );
+}
+```
+
+**With Tailwind (styles in component):**
+
+```typescript
+// src/features/user/components/UserCard.tsx
+export function UserCard({ user }: { user: User }) {
+ return (
+
+
+
{user.name}
+
+ );
+}
+```
+
+**Shared styles belong in shared:**
+
+```
+src/shared/
+├── styles/
+│ ├── reset.css # Global reset
+│ └── variables.css # Design tokens
+└── components/
+ ├── Button/
+ │ ├── Button.tsx
+ │ └── Button.module.css
+ └── Input/
+ ├── Input.tsx
+ └── Input.module.css
+```
+
+**Benefits:**
+- Moving a component moves its styles
+- Deleting a component deletes its styles
+- No orphaned CSS
+
+Reference: [CSS Modules Documentation](https://github.com/css-modules/css-modules)
diff --git a/.agents/skills/feature-arch/references/fcomp-composition-over-props.md b/.agents/skills/feature-arch/references/fcomp-composition-over-props.md
new file mode 100644
index 0000000..7d7b2f7
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fcomp-composition-over-props.md
@@ -0,0 +1,100 @@
+---
+title: Prefer Composition Over Prop Drilling
+impact: MEDIUM-HIGH
+impactDescription: Eliminates prop drilling; enables flexible slot-based component design
+tags: comp, composition, children, slots
+---
+
+## Prefer Composition Over Prop Drilling
+
+When components need to render content from different features, use composition (children, render props, slots) instead of passing data down through multiple layers. This keeps components decoupled and flexible.
+
+**Incorrect (prop drilling):**
+
+```typescript
+// Props must pass through every layer
+function Page({ user, cart, notifications }) {
+ return ;
+}
+
+function Layout({ user, cart, notifications }) {
+ return (
+
+
+
+
+ );
+}
+
+function Header({ user, cart, notifications }) {
+ return (
+
+ );
+}
+```
+
+**Correct (composition with slots):**
+
+```typescript
+// Layout accepts composed children
+interface LayoutProps {
+ header: ReactNode;
+ children: ReactNode;
+}
+
+function Layout({ header, children }: LayoutProps) {
+ return (
+
+
+ {children}
+
+ );
+}
+
+// Page composes features at the top level
+function Page() {
+ return (
+
+ {/* Feature handles its own data */}
+ {/* Feature handles its own data */}
+ {/* Feature handles its own data */}
+ >
+ }
+ >
+
+
+ );
+}
+```
+
+**Render props for flexible rendering:**
+
+```typescript
+interface DataTableProps {
+ data: T[];
+ renderRow: (item: T) => ReactNode;
+ renderEmpty?: () => ReactNode;
+}
+
+function DataTable({ data, renderRow, renderEmpty }: DataTableProps) {
+ if (data.length === 0) {
+ return renderEmpty?.() ?? ;
+ }
+ return ;
+}
+
+// Usage - feature controls rendering
+ }
+ renderEmpty={() => }
+/>
+```
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/fcomp-container-presentational.md b/.agents/skills/feature-arch/references/fcomp-container-presentational.md
new file mode 100644
index 0000000..8749881
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fcomp-container-presentational.md
@@ -0,0 +1,99 @@
+---
+title: Separate Container and Presentational Concerns
+impact: MEDIUM
+impactDescription: Enables design system reuse; keeps business logic testable
+tags: comp, container, presentational, separation
+---
+
+## Separate Container and Presentational Concerns
+
+Distinguish between components that manage data/state (containers) and components that render UI (presentational). Presentational components are reusable and easy to test; containers coordinate business logic.
+
+**Incorrect (mixed concerns):**
+
+```typescript
+// Component does everything - hard to reuse or test
+function UserCard() {
+ const [user, setUser] = useState(null);
+ const [isEditing, setIsEditing] = useState(false);
+
+ useEffect(() => {
+ fetchUser(userId).then(setUser);
+ }, [userId]);
+
+ const handleSave = async (data: UserData) => {
+ await updateUser(userId, data);
+ setUser({ ...user, ...data });
+ setIsEditing(false);
+ };
+
+ if (!user) return ;
+
+ return (
+
+ {isEditing ? (
+
+ ) : (
+ <>
+
+
{user.name}
+
{user.email}
+
setIsEditing(true)}>Edit
+ >
+ )}
+
+ );
+}
+```
+
+**Correct (separated concerns):**
+
+```typescript
+// Presentational - pure rendering, easy to test and reuse
+interface UserCardProps {
+ user: User;
+ onEdit: () => void;
+}
+
+function UserCard({ user, onEdit }: UserCardProps) {
+ return (
+
+
+
{user.name}
+
{user.email}
+
Edit
+
+ );
+}
+
+// Container - manages data and state
+function UserCardContainer({ userId }: { userId: string }) {
+ const { data: user, isLoading } = useUser(userId);
+ const [isEditing, setIsEditing] = useState(false);
+ const updateMutation = useUpdateUser();
+
+ if (isLoading) return ;
+
+ if (isEditing) {
+ return (
+ {
+ updateMutation.mutate({ userId, data });
+ setIsEditing(false);
+ }}
+ onCancel={() => setIsEditing(false)}
+ />
+ );
+ }
+
+ return setIsEditing(true)} />;
+}
+```
+
+**Benefits:**
+- UserCard can be used in Storybook, tests, anywhere
+- Business logic is concentrated in container
+- Presentational components are pure functions of props
+
+Reference: [React Patterns - Container/Presentational](https://reactpatterns.com/)
diff --git a/.agents/skills/feature-arch/references/fcomp-error-boundaries.md b/.agents/skills/feature-arch/references/fcomp-error-boundaries.md
new file mode 100644
index 0000000..ea84b65
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fcomp-error-boundaries.md
@@ -0,0 +1,99 @@
+---
+title: Use Feature-Level Error Boundaries
+impact: MEDIUM
+impactDescription: Isolates failures to single features; prevents full-page crashes
+tags: comp, error-boundary, resilience, isolation
+---
+
+## Use Feature-Level Error Boundaries
+
+Wrap each feature's root component in an error boundary. When a feature fails, only that feature shows an error state while the rest of the page remains functional.
+
+**Incorrect (single app-level boundary):**
+
+```typescript
+// Single error boundary - any feature crash takes down entire app
+function App() {
+ return (
+ }>
+
+
+ );
+}
+
+function Dashboard() {
+ return (
+
+ {/* Crash here = full page error */}
+
+
+
+ );
+}
+```
+
+**Correct (feature-level boundaries):**
+
+```typescript
+// src/shared/components/FeatureErrorBoundary.tsx
+interface FeatureErrorBoundaryProps {
+ feature: string;
+ children: ReactNode;
+ fallback?: ReactNode;
+}
+
+export function FeatureErrorBoundary({
+ feature,
+ children,
+ fallback,
+}: FeatureErrorBoundaryProps) {
+ return (
+ }
+ onError={(error) => logError(error, { feature })}
+ >
+ {children}
+
+ );
+}
+
+// src/app/pages/DashboardPage.tsx
+function Dashboard() {
+ return (
+
+
+ {/* Crash here = only this section shows error */}
+
+
+
+ {/* Still works even if UserProfile crashed */}
+
+
+
+ {/* Still works */}
+
+
+ );
+}
+```
+
+**Graceful fallback UI:**
+
+```typescript
+function FeatureErrorFallback({ feature }: { feature: string }) {
+ return (
+
+
+ Unable to load {feature}. Try again
+
+
+ );
+}
+```
+
+**Benefits:**
+- One feature failing doesn't crash the page
+- Errors are attributed to specific features
+- Users can continue using working features
+
+Reference: [React Error Boundaries](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary)
diff --git a/.agents/skills/feature-arch/references/fcomp-props-as-data-boundary.md b/.agents/skills/feature-arch/references/fcomp-props-as-data-boundary.md
new file mode 100644
index 0000000..5f38bc1
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fcomp-props-as-data-boundary.md
@@ -0,0 +1,88 @@
+---
+title: Use Props as Feature Boundaries
+impact: MEDIUM-HIGH
+impactDescription: Creates clear interfaces between features; enables feature composition
+tags: comp, props, interface, boundary
+---
+
+## Use Props as Feature Boundaries
+
+When features interact, use props to define the interface. The receiving component should not know about the providing feature's internals. This creates a clear boundary that allows either side to change independently.
+
+**Incorrect (feature internals exposed):**
+
+```typescript
+// Checkout component knows about Cart's internal structure
+import { useCartStore } from '@/features/cart/stores/cartStore';
+
+function CheckoutSummary() {
+ // Directly accessing cart's internal state structure
+ const items = useCartStore(s => s.items);
+ const appliedCoupons = useCartStore(s => s.coupons);
+ const shippingMethod = useCartStore(s => s.shipping.method);
+
+ // If cart store changes structure, this breaks
+ return ...
;
+}
+```
+
+**Correct (props as boundary):**
+
+```typescript
+// Define explicit interface for what checkout needs
+interface CheckoutSummaryProps {
+ items: Array<{
+ id: string;
+ name: string;
+ price: number;
+ quantity: number;
+ }>;
+ subtotal: number;
+ discount: number;
+ shipping: number;
+ total: number;
+}
+
+function CheckoutSummary({ items, subtotal, discount, shipping, total }: CheckoutSummaryProps) {
+ // Component only knows about its props, not cart internals
+ return (
+
+ {items.map(item => (
+
+ ))}
+
+ {discount > 0 && }
+
+
+
+ );
+}
+
+// App layer transforms cart state to checkout props
+function CheckoutPage() {
+ const cart = useCartStore();
+
+ // Transformation happens at composition point
+ const summaryProps = {
+ items: cart.items.map(i => ({
+ id: i.id,
+ name: i.product.name,
+ price: i.product.price,
+ quantity: i.quantity,
+ })),
+ subtotal: cart.getSubtotal(),
+ discount: cart.getDiscount(),
+ shipping: cart.getShippingCost(),
+ total: cart.getTotal(),
+ };
+
+ return ;
+}
+```
+
+**Benefits:**
+- CheckoutSummary doesn't import from cart feature
+- Cart can restructure without breaking checkout
+- CheckoutSummary is easily testable with mock props
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/fcomp-single-responsibility.md b/.agents/skills/feature-arch/references/fcomp-single-responsibility.md
new file mode 100644
index 0000000..5c48826
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fcomp-single-responsibility.md
@@ -0,0 +1,99 @@
+---
+title: Apply Single Responsibility to Components
+impact: MEDIUM-HIGH
+impactDescription: Enables parallel development and isolated testing; reduces component complexity
+tags: comp, single-responsibility, separation, focused
+---
+
+## Apply Single Responsibility to Components
+
+Each component should do one thing well. When a component handles multiple concerns (rendering, data fetching, business logic), it becomes hard to test, reuse, and maintain. Split into focused components.
+
+**Incorrect (multiple responsibilities):**
+
+```typescript
+// src/features/post/components/Post.tsx
+export function Post({ postId }: { postId: string }) {
+ // Data fetching
+ const [post, setPost] = useState(null);
+ const [comments, setComments] = useState([]);
+
+ useEffect(() => {
+ fetchPost(postId).then(setPost);
+ fetchComments(postId).then(setComments);
+ }, [postId]);
+
+ // Business logic
+ const handleLike = async () => { ... };
+ const handleComment = async () => { ... };
+
+ // Rendering post AND comments AND forms
+ return (
+
+
{post?.title}
+
{post?.content}
+
Like
+
+ {comments.map(c => {c.text} )}
+
+
+
+ );
+}
+```
+
+**Correct (single responsibility each):**
+
+```typescript
+// src/features/post/components/PostContent.tsx
+interface PostContentProps {
+ post: Post;
+ onLike: () => void;
+}
+
+export function PostContent({ post, onLike }: PostContentProps) {
+ return (
+
+ {post.title}
+ {post.content}
+
+
+ );
+}
+
+// src/features/comment/components/CommentList.tsx
+interface CommentListProps {
+ comments: Comment[];
+}
+
+export function CommentList({ comments }: CommentListProps) {
+ return (
+
+ {comments.map(c => )}
+
+ );
+}
+
+// src/app/posts/[id]/page.tsx (composition at app layer)
+export async function PostPage({ postId }: { postId: string }) {
+ const [post, comments] = await Promise.all([
+ getPost(postId),
+ getComments(postId),
+ ]);
+
+ return (
+ <>
+ likePost(postId)} />
+
+
+ >
+ );
+}
+```
+
+**Benefits:**
+- PostContent can be tested without comments
+- CommentList can be reused elsewhere
+- Each component is ~20-50 lines, easy to understand
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/fquery-avoid-n-plus-one.md b/.agents/skills/feature-arch/references/fquery-avoid-n-plus-one.md
new file mode 100644
index 0000000..7928481
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fquery-avoid-n-plus-one.md
@@ -0,0 +1,80 @@
+---
+title: Avoid N+1 Query Patterns
+impact: HIGH
+impactDescription: Prevents request count from scaling with data size; eliminates O(N) network calls
+tags: query, n-plus-one, performance, batching
+---
+
+## Avoid N+1 Query Patterns
+
+N+1 queries occur when you fetch a list and then individually fetch related data for each item. This creates N+1 requests instead of 2, causing performance to degrade with data growth.
+
+**Incorrect (N+1 pattern):**
+
+```typescript
+// 1 request for posts + N requests for authors = N+1 total
+export async function PostList() {
+ const posts = await getPosts(); // 1 request
+
+ // N additional requests!
+ const postsWithAuthors = await Promise.all(
+ posts.map(async (post) => ({
+ ...post,
+ author: await getUser(post.authorId), // 1 request per post
+ }))
+ );
+
+ return postsWithAuthors.map(post => );
+}
+```
+
+**Correct (batched query):**
+
+```typescript
+// src/features/user/api/get-users-by-ids.ts
+export async function getUsersByIds(ids: string[]) {
+ return prisma.user.findMany({
+ where: { id: { in: ids } },
+ });
+}
+
+// 2 requests total regardless of post count
+export async function PostList() {
+ const posts = await getPosts(); // 1 request
+
+ const authorIds = [...new Set(posts.map(p => p.authorId))];
+ const authors = await getUsersByIds(authorIds); // 1 request
+ const authorsById = new Map(authors.map(a => [a.id, a]));
+
+ const postsWithAuthors = posts.map(post => ({
+ ...post,
+ author: authorsById.get(post.authorId),
+ }));
+
+ return postsWithAuthors.map(post => );
+}
+```
+
+**Alternative: Lazy load where appropriate:**
+
+```typescript
+// If authors are rarely viewed, lazy load on demand
+export function PostCard({ post }: { post: Post }) {
+ const [showAuthor, setShowAuthor] = useState(false);
+
+ return (
+
+ {post.title}
+ setShowAuthor(true)}>Show Author
+ {showAuthor && }
+
+ );
+}
+```
+
+**When to accept N+1:**
+- N is always small (< 5 items)
+- Data is heavily cached and cache hits are near 100%
+- Lazy loading is appropriate (user rarely views related data)
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/fquery-colocate-with-feature.md b/.agents/skills/feature-arch/references/fquery-colocate-with-feature.md
new file mode 100644
index 0000000..300527d
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fquery-colocate-with-feature.md
@@ -0,0 +1,70 @@
+---
+title: Colocate Data Fetching with Features
+impact: HIGH
+impactDescription: Makes features self-contained; enables independent API evolution
+tags: query, colocation, data-fetching, feature
+---
+
+## Colocate Data Fetching with Features
+
+Data fetching logic belongs within the feature that owns the data. When API calls are scattered in a central api/ folder, features lose independence and changes require coordinating across multiple locations.
+
+**Incorrect (centralized API layer):**
+
+```
+src/
+├── api/
+│ ├── users.ts # All user API calls
+│ ├── posts.ts # All post API calls
+│ ├── comments.ts # All comment API calls
+│ └── orders.ts # All order API calls
+└── features/
+ ├── user/
+ │ └── components/ # Components import from ../../../api/users
+ └── post/
+ └── components/ # Components import from ../../../api/posts
+```
+
+**Correct (colocated with features):**
+
+```
+src/features/
+├── user/
+│ ├── api/
+│ │ ├── get-user.ts
+│ │ ├── update-user.ts
+│ │ └── delete-user.ts
+│ ├── components/
+│ │ └── UserProfile.tsx
+│ └── hooks/
+│ └── useUser.ts
+└── post/
+ ├── api/
+ │ ├── get-post.ts
+ │ ├── get-posts.ts
+ │ └── create-post.ts
+ ├── components/
+ │ └── PostList.tsx
+ └── hooks/
+ └── usePosts.ts
+```
+
+```typescript
+// src/features/user/hooks/useUser.ts
+import { getUser } from '../api/get-user';
+
+export function useUser(userId: string) {
+ return useQuery({
+ queryKey: ['user', userId],
+ queryFn: () => getUser(userId),
+ });
+}
+```
+
+**Benefits:**
+- Adding a feature includes its API calls
+- Removing a feature removes its API calls
+- Feature can evolve its API independently
+- Related code is always together
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/fquery-feature-scoped-keys.md b/.agents/skills/feature-arch/references/fquery-feature-scoped-keys.md
new file mode 100644
index 0000000..fa45890
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fquery-feature-scoped-keys.md
@@ -0,0 +1,72 @@
+---
+title: Use Feature-Scoped Query Keys
+impact: MEDIUM-HIGH
+impactDescription: Enables targeted cache invalidation; prevents accidental cache collisions
+tags: query, cache, keys, tanstack-query
+---
+
+## Use Feature-Scoped Query Keys
+
+Query keys should be hierarchical with the feature name as the root. This enables precise cache invalidation and prevents key collisions between features.
+
+**Incorrect (flat, collision-prone keys):**
+
+```typescript
+// src/features/user/hooks/useUser.ts
+useQuery({ queryKey: ['user', userId], ... });
+
+// src/features/admin/hooks/useUser.ts
+useQuery({ queryKey: ['user', userId], ... }); // Collides with above!
+
+// Hard to invalidate all user queries
+queryClient.invalidateQueries({ queryKey: ['user'] }); // Might affect admin too
+```
+
+**Correct (feature-scoped key factory):**
+
+```typescript
+// src/features/user/query-keys.ts
+export const userKeys = {
+ all: ['user'] as const,
+ lists: () => [...userKeys.all, 'list'] as const,
+ list: (filters: UserFilters) => [...userKeys.lists(), filters] as const,
+ details: () => [...userKeys.all, 'detail'] as const,
+ detail: (id: string) => [...userKeys.details(), id] as const,
+};
+
+// src/features/user/hooks/useUser.ts
+import { userKeys } from '../query-keys';
+
+export function useUser(userId: string) {
+ return useQuery({
+ queryKey: userKeys.detail(userId),
+ queryFn: () => getUser(userId),
+ });
+}
+
+// src/features/admin/query-keys.ts
+export const adminUserKeys = {
+ all: ['admin', 'user'] as const,
+ detail: (id: string) => [...adminUserKeys.all, 'detail', id] as const,
+};
+```
+
+**Invalidation patterns:**
+
+```typescript
+// Invalidate all user data
+queryClient.invalidateQueries({ queryKey: userKeys.all });
+
+// Invalidate only user lists (not details)
+queryClient.invalidateQueries({ queryKey: userKeys.lists() });
+
+// Invalidate specific user
+queryClient.invalidateQueries({ queryKey: userKeys.detail(userId) });
+```
+
+**Benefits:**
+- Clear ownership of cache keys
+- Predictable invalidation scope
+- No accidental cross-feature cache interference
+
+Reference: [TanStack Query - Query Keys](https://tanstack.com/query/latest/docs/framework/react/guides/query-keys)
diff --git a/.agents/skills/feature-arch/references/fquery-parallel-fetching.md b/.agents/skills/feature-arch/references/fquery-parallel-fetching.md
new file mode 100644
index 0000000..045c755
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fquery-parallel-fetching.md
@@ -0,0 +1,71 @@
+---
+title: Fetch Independent Data in Parallel
+impact: HIGH
+impactDescription: Reduces total load time by ~50% for pages with multiple data sources
+tags: query, parallel, performance, waterfall
+---
+
+## Fetch Independent Data in Parallel
+
+When a component needs multiple pieces of unrelated data, fetch them in parallel using Promise.all(). Sequential fetching creates waterfalls where total time equals the sum of all requests.
+
+**Incorrect (sequential waterfall):**
+
+```typescript
+// Each request waits for the previous one
+// Total time: 200ms + 150ms + 100ms = 450ms
+export async function DashboardPage() {
+ const user = await getUser(userId); // 200ms
+ const orders = await getOrders(userId); // 150ms
+ const notifications = await getNotifications(userId); // 100ms
+
+ return ;
+}
+```
+
+**Correct (parallel fetching):**
+
+```typescript
+// All requests start simultaneously
+// Total time: max(200ms, 150ms, 100ms) = 200ms
+export async function DashboardPage() {
+ const [user, orders, notifications] = await Promise.all([
+ getUser(userId), // 200ms
+ getOrders(userId), // 150ms
+ getNotifications(userId), // 100ms
+ ]);
+
+ return ;
+}
+```
+
+**With React Query:**
+
+```typescript
+// src/app/pages/DashboardPage.tsx
+export function DashboardPage({ userId }: { userId: string }) {
+ // These queries run in parallel automatically
+ const userQuery = useUser(userId);
+ const ordersQuery = useOrders(userId);
+ const notificationsQuery = useNotifications(userId);
+
+ if (userQuery.isLoading || ordersQuery.isLoading || notificationsQuery.isLoading) {
+ return ;
+ }
+
+ return (
+
+ );
+}
+```
+
+**When sequential is necessary:**
+- Second request depends on first request's result
+- Rate limiting requires throttled requests
+- User must complete a step before seeing next data
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/fquery-server-component-fetching.md b/.agents/skills/feature-arch/references/fquery-server-component-fetching.md
new file mode 100644
index 0000000..e71c562
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fquery-server-component-fetching.md
@@ -0,0 +1,88 @@
+---
+title: Fetch at Server Component Level
+impact: MEDIUM-HIGH
+impactDescription: Eliminates client-server waterfalls; reduces bundle size by keeping fetch logic on server
+tags: query, server-components, rsc, next.js
+---
+
+## Fetch at Server Component Level
+
+In React Server Component architectures, fetch data in server components and pass to client components as props. This eliminates client-server waterfalls and keeps data fetching off the client bundle.
+
+**Incorrect (client component fetching):**
+
+```typescript
+// src/features/post/components/PostPage.tsx
+'use client';
+
+export function PostPage({ postId }: { postId: string }) {
+ const [post, setPost] = useState(null);
+
+ useEffect(() => {
+ fetch(`/api/posts/${postId}`) // Client-server waterfall
+ .then(res => res.json())
+ .then(setPost);
+ }, [postId]);
+
+ if (!post) return ;
+ return ;
+}
+```
+
+**Correct (server component fetching):**
+
+```typescript
+// src/features/post/components/PostPage.tsx (Server Component)
+import { getPost } from '../api/get-post';
+import { PostContent } from './PostContent'; // Client component
+
+export async function PostPage({ postId }: { postId: string }) {
+ const post = await getPost(postId); // Fetches on server
+
+ return ;
+}
+
+// src/features/post/components/PostContent.tsx
+'use client';
+
+interface PostContentProps {
+ post: Post; // Receives data as props, no fetching
+}
+
+export function PostContent({ post }: PostContentProps) {
+ const [likes, setLikes] = useState(post.likes);
+
+ return (
+
+ {post.title}
+ {post.content}
+ setLikes(l => l + 1)} />
+
+ );
+}
+```
+
+**Composition pattern:**
+
+```typescript
+// src/app/posts/[id]/page.tsx (Server Component)
+import { PostPage } from '@/features/post';
+import { Comments } from '@/features/comment';
+
+export default async function Page({ params }: { params: { id: string } }) {
+ // Parallel fetch at app layer
+ const [post, comments] = await Promise.all([
+ getPost(params.id),
+ getComments(params.id),
+ ]);
+
+ return (
+ <>
+
+
+ >
+ );
+}
+```
+
+Reference: [Next.js - Data Fetching](https://nextjs.org/docs/app/building-your-application/data-fetching)
diff --git a/.agents/skills/feature-arch/references/fquery-single-responsibility.md b/.agents/skills/feature-arch/references/fquery-single-responsibility.md
new file mode 100644
index 0000000..6705133
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fquery-single-responsibility.md
@@ -0,0 +1,66 @@
+---
+title: Keep Query Functions Single-Purpose
+impact: HIGH
+impactDescription: Prevents query permutation explosion as features grow
+tags: query, single-responsibility, data-fetching, api
+---
+
+## Keep Query Functions Single-Purpose
+
+Each query function should fetch one type of data. Avoid creating variations that combine multiple concerns. When features need combined data, fetch separately and compose at the component level.
+
+**Incorrect (query permutations):**
+
+```typescript
+// src/features/post/api/queries.ts
+
+// Creates combinatorial explosion as requirements grow
+export async function getPost(id: string) { ... }
+export async function getPostWithComments(id: string) { ... }
+export async function getPostWithAuthor(id: string) { ... }
+export async function getPostWithCommentsAndAuthor(id: string) { ... }
+export async function getPostWithCommentsAndAuthorAndLikes(id: string) { ... }
+// N relations = 2^N possible combinations
+```
+
+**Correct (single-purpose queries):**
+
+```typescript
+// src/features/post/api/get-post.ts
+export async function getPost(id: string) {
+ return prisma.post.findUnique({ where: { id } });
+}
+
+// src/features/comment/api/get-comments.ts
+export async function getComments(postId: string) {
+ return prisma.comment.findMany({ where: { postId } });
+}
+
+// src/features/user/api/get-user.ts
+export async function getUser(id: string) {
+ return prisma.user.findUnique({ where: { id } });
+}
+
+// Component composes what it needs
+export async function PostPage({ postId }: { postId: string }) {
+ const [post, comments] = await Promise.all([
+ getPost(postId),
+ getComments(postId),
+ ]);
+
+ return (
+
+
+
+
+ );
+}
+```
+
+**Benefits:**
+- Linear growth: N relations = N query functions
+- Each query is independently cacheable
+- Parallel fetching via Promise.all()
+- Each feature owns its own data fetching
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/fstate-context-sparingly.md b/.agents/skills/feature-arch/references/fstate-context-sparingly.md
new file mode 100644
index 0000000..024db1b
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fstate-context-sparingly.md
@@ -0,0 +1,73 @@
+---
+title: Use Context Sparingly for Feature State
+impact: MEDIUM
+impactDescription: Prevents context re-render cascades; keeps features portable
+tags: state, context, provider, scope
+---
+
+## Use Context Sparingly for Feature State
+
+Context is useful for dependency injection and app-wide configuration, but causes re-render cascades when used for frequently-changing state. Prefer feature stores or local state for dynamic data.
+
+**Incorrect (frequently changing data in context):**
+
+```typescript
+// Every context consumer re-renders on any cart change
+const CartContext = createContext(null);
+
+function CartProvider({ children }) {
+ const [items, setItems] = useState([]);
+ const [total, setTotal] = useState(0);
+
+ const addItem = (item) => {
+ setItems([...items, item]); // Re-renders all consumers
+ setTotal(total + item.price);
+ };
+
+ return (
+
+ {children} {/* Every consumer re-renders */}
+
+ );
+}
+
+// Components re-render even if they only use `total`
+function CartIcon() {
+ const { total } = useContext(CartContext); // Re-renders when items change
+ return {total} ;
+}
+```
+
+**Correct (store with selectors):**
+
+```typescript
+// src/features/cart/stores/cartStore.ts
+export const useCartStore = create((set, get) => ({
+ items: [],
+ addItem: (item) => set(s => ({ items: [...s.items, item] })),
+ getTotal: () => get().items.reduce((sum, i) => sum + i.price, 0),
+}));
+
+// Only re-renders when selected state changes
+function CartIcon() {
+ const total = useCartStore(s => s.items.reduce((sum, i) => sum + i.price, 0));
+ return {total} ;
+}
+
+function CartItemCount() {
+ const count = useCartStore(s => s.items.length); // Only re-renders when count changes
+ return {count} ;
+}
+```
+
+**When context is appropriate:**
+- Dependency injection (API client, auth)
+- Theme/locale (changes rarely)
+- Feature flags (read-only)
+
+**When to use stores:**
+- Frequently updating state
+- Multiple components need different slices
+- Need fine-grained subscriptions
+
+Reference: [Zustand Documentation](https://zustand-demo.pmnd.rs/)
diff --git a/.agents/skills/feature-arch/references/fstate-feature-scoped-stores.md b/.agents/skills/feature-arch/references/fstate-feature-scoped-stores.md
new file mode 100644
index 0000000..e03fd9f
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fstate-feature-scoped-stores.md
@@ -0,0 +1,79 @@
+---
+title: Scope State Stores to Features
+impact: MEDIUM
+impactDescription: Prevents global state coupling; enables feature-level state reset and testing
+tags: state, stores, scope, feature
+---
+
+## Scope State Stores to Features
+
+Each feature should own its state store. When state is global, features become coupled through shared state, making them impossible to develop, test, or remove independently.
+
+**Incorrect (global monolithic store):**
+
+```typescript
+// src/stores/store.ts
+export const useStore = create((set) => ({
+ // User feature state
+ user: null,
+ userLoading: false,
+ setUser: (user) => set({ user }),
+
+ // Cart feature state
+ cartItems: [],
+ addToCart: (item) => set(s => ({ cartItems: [...s.cartItems, item] })),
+
+ // Notification feature state
+ notifications: [],
+ addNotification: (n) => set(s => ({ notifications: [...s.notifications, n] })),
+
+ // Everything mixed together - impossible to isolate
+}));
+```
+
+**Correct (feature-scoped stores):**
+
+```typescript
+// src/features/user/stores/userStore.ts
+export const useUserStore = create((set) => ({
+ user: null,
+ isLoading: false,
+ setUser: (user) => set({ user }),
+ clearUser: () => set({ user: null }),
+}));
+
+// src/features/cart/stores/cartStore.ts
+export const useCartStore = create((set) => ({
+ items: [],
+ addItem: (item) => set(s => ({ items: [...s.items, item] })),
+ removeItem: (id) => set(s => ({ items: s.items.filter(i => i.id !== id) })),
+ clearCart: () => set({ items: [] }),
+}));
+
+// src/features/notification/stores/notificationStore.ts
+export const useNotificationStore = create((set) => ({
+ notifications: [],
+ add: (n) => set(s => ({ notifications: [...s.notifications, n] })),
+ dismiss: (id) => set(s => ({
+ notifications: s.notifications.filter(n => n.id !== id),
+ })),
+}));
+```
+
+**Feature exposes store via public API:**
+
+```typescript
+// src/features/cart/index.ts
+export { useCartStore } from './stores/cartStore';
+export type { CartItem } from './types';
+
+// Other features use the exported store
+import { useCartStore } from '@/features/cart';
+```
+
+**Benefits:**
+- Feature can be removed along with its store
+- Tests can reset feature state independently
+- Clear ownership of state
+
+Reference: [Feature-Sliced Design](https://feature-sliced.design/)
diff --git a/.agents/skills/feature-arch/references/fstate-lift-minimally.md b/.agents/skills/feature-arch/references/fstate-lift-minimally.md
new file mode 100644
index 0000000..d78ab16
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fstate-lift-minimally.md
@@ -0,0 +1,85 @@
+---
+title: Lift State Only as High as Necessary
+impact: MEDIUM
+impactDescription: Reduces re-renders; keeps state close to where it's used
+tags: state, lifting, locality, performance
+---
+
+## Lift State Only as High as Necessary
+
+State should live in the lowest common ancestor of components that need it. Lifting state too high causes unnecessary re-renders and makes the state's purpose unclear.
+
+**Incorrect (state lifted too high):**
+
+```typescript
+// State in app root - causes full tree re-render on every keystroke
+function App() {
+ const [searchQuery, setSearchQuery] = useState('');
+ const [sortOrder, setSortOrder] = useState('asc');
+ const [selectedTab, setSelectedTab] = useState('all');
+
+ return (
+
+
+
+
+
{/* Re-renders on every search keystroke */}
+
+ );
+}
+```
+
+**Correct (state at lowest necessary level):**
+
+```typescript
+function App() {
+ return (
+
+
+
+ {/* Never re-renders due to search/sort */}
+
+ );
+}
+
+function MainContent() {
+ const [selectedTab, setSelectedTab] = useState('all');
+
+ return (
+ <>
+
+
+ >
+ );
+}
+
+function ProductList({ selectedTab }: { selectedTab: string }) {
+ // Search and sort state only affects ProductList subtree
+ const [searchQuery, setSearchQuery] = useState('');
+ const [sortOrder, setSortOrder] = useState('asc');
+
+ return (
+
+ );
+}
+```
+
+**Decision guide:**
+
+| Situation | Where to put state |
+|-----------|-------------------|
+| Single component uses it | In that component |
+| Sibling components share it | In parent |
+| Distant components share it | Context or store |
+| Server data | Query library |
+
+Reference: [React Docs - Sharing State](https://react.dev/learn/sharing-state-between-components)
diff --git a/.agents/skills/feature-arch/references/fstate-reset-on-unmount.md b/.agents/skills/feature-arch/references/fstate-reset-on-unmount.md
new file mode 100644
index 0000000..b0b9e67
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fstate-reset-on-unmount.md
@@ -0,0 +1,89 @@
+---
+title: Reset Feature State on Unmount
+impact: MEDIUM
+impactDescription: Prevents stale state bugs; ensures clean feature initialization
+tags: state, reset, cleanup, unmount
+---
+
+## Reset Feature State on Unmount
+
+When a feature unmounts, reset its state to prevent stale data from appearing when the feature remounts. Persistent stores can cause bugs when users navigate away and back.
+
+**Incorrect (stale state persists):**
+
+```typescript
+// User views checkout, abandons, browses, returns to checkout
+// Sees old form data from previous session
+const useCheckoutStore = create((set) => ({
+ shippingAddress: null,
+ paymentMethod: null,
+ setShipping: (addr) => set({ shippingAddress: addr }),
+}));
+
+function CheckoutPage() {
+ const { shippingAddress } = useCheckoutStore();
+ // shippingAddress still has old data from previous visit
+ return ;
+}
+```
+
+**Correct (reset on unmount):**
+
+```typescript
+// src/features/checkout/stores/checkoutStore.ts
+const initialState = {
+ shippingAddress: null,
+ paymentMethod: null,
+ step: 1,
+};
+
+export const useCheckoutStore = create((set) => ({
+ ...initialState,
+ setShipping: (addr) => set({ shippingAddress: addr }),
+ setPayment: (method) => set({ paymentMethod: method }),
+ nextStep: () => set(s => ({ step: s.step + 1 })),
+ reset: () => set(initialState),
+}));
+
+// src/features/checkout/components/CheckoutPage.tsx
+function CheckoutPage() {
+ const reset = useCheckoutStore(s => s.reset);
+
+ useEffect(() => {
+ // Reset when leaving checkout
+ return () => reset();
+ }, [reset]);
+
+ return ;
+}
+```
+
+**Alternative: Feature-scoped store instance:**
+
+```typescript
+// src/features/checkout/CheckoutProvider.tsx
+const CheckoutContext = createContext(null);
+
+export function CheckoutProvider({ children }) {
+ // New store instance created each mount
+ const storeRef = useRef();
+ if (!storeRef.current) {
+ storeRef.current = createCheckoutStore();
+ }
+
+ return (
+
+ {children}
+
+ );
+}
+
+// Store is automatically fresh on each mount
+```
+
+**When NOT to reset:**
+- User preferences (theme, language)
+- Draft content (auto-saved forms)
+- Explicitly preserved state (shopping cart)
+
+Reference: [Zustand - Resetting State](https://zustand-demo.pmnd.rs/)
diff --git a/.agents/skills/feature-arch/references/fstate-server-state-separation.md b/.agents/skills/feature-arch/references/fstate-server-state-separation.md
new file mode 100644
index 0000000..87ebceb
--- /dev/null
+++ b/.agents/skills/feature-arch/references/fstate-server-state-separation.md
@@ -0,0 +1,93 @@
+---
+title: Separate Server State from Client State
+impact: MEDIUM
+impactDescription: Eliminates manual cache sync; leverages query library optimizations
+tags: state, server-state, client-state, tanstack-query
+---
+
+## Separate Server State from Client State
+
+Server state (data from API) and client state (UI state, form state) have different characteristics. Server state should be managed by a query library; client state by local state or stores. Mixing them leads to stale data and sync bugs.
+
+**Incorrect (server state in client store):**
+
+```typescript
+// src/stores/userStore.ts
+export const useUserStore = create((set) => ({
+ users: [],
+ isLoading: false,
+
+ // Manual fetching logic
+ fetchUsers: async () => {
+ set({ isLoading: true });
+ const users = await api.getUsers();
+ set({ users, isLoading: false });
+ },
+
+ // Manual cache invalidation
+ invalidate: () => {
+ // How do we know when to refetch?
+ // What about stale data?
+ // What about deduplication?
+ },
+}));
+```
+
+**Correct (server state in query library):**
+
+```typescript
+// src/features/user/hooks/useUsers.ts
+// Server state - managed by TanStack Query
+export function useUsers(filters: UserFilters) {
+ return useQuery({
+ queryKey: userKeys.list(filters),
+ queryFn: () => getUsers(filters),
+ staleTime: 60_000, // Built-in cache management
+ });
+}
+
+// src/features/user/stores/userUIStore.ts
+// Client state - UI-only concerns
+export const useUserUIStore = create((set) => ({
+ selectedUserId: null,
+ filterPanelOpen: false,
+ sortOrder: 'asc' as const,
+
+ selectUser: (id) => set({ selectedUserId: id }),
+ toggleFilterPanel: () => set(s => ({ filterPanelOpen: !s.filterPanelOpen })),
+ setSortOrder: (order) => set({ sortOrder: order }),
+}));
+```
+
+**Usage:**
+
+```typescript
+function UserListPage() {
+ // Server state
+ const { data: users, isLoading } = useUsers({ active: true });
+
+ // Client state
+ const { selectedUserId, selectUser, sortOrder } = useUserUIStore();
+
+ const sortedUsers = useMemo(() =>
+ [...(users ?? [])].sort((a, b) =>
+ sortOrder === 'asc' ? a.name.localeCompare(b.name) : b.name.localeCompare(a.name)
+ ),
+ [users, sortOrder]
+ );
+
+ return ;
+}
+```
+
+**Server state characteristics:**
+- Fetched from external source
+- Can become stale
+- Needs refetching, deduplication, caching
+
+**Client state characteristics:**
+- Created locally
+- Never stale (source of truth is client)
+- No network concerns
+
+Reference: [TanStack Query - Overview](https://tanstack.com/query/latest/docs/framework/react/overview)
diff --git a/.agents/skills/feature-arch/references/import-avoid-barrel-files.md b/.agents/skills/feature-arch/references/import-avoid-barrel-files.md
new file mode 100644
index 0000000..9f4b49d
--- /dev/null
+++ b/.agents/skills/feature-arch/references/import-avoid-barrel-files.md
@@ -0,0 +1,63 @@
+---
+title: Avoid Deep Barrel File Re-exports
+impact: HIGH
+impactDescription: Prevents tree-shaking failures; reduces bundle size by avoiding unused code
+tags: import, barrel-files, tree-shaking, bundle-size
+---
+
+## Avoid Deep Barrel File Re-exports
+
+While feature index.ts files are useful for public APIs, avoid creating nested barrel files that re-export everything. Deep barrel chains prevent bundlers from tree-shaking unused code and can cause performance issues in development.
+
+**Incorrect (barrel chain):**
+
+```typescript
+// src/features/user/components/index.ts
+export * from './UserProfile';
+export * from './UserSettings';
+export * from './UserAvatar';
+export * from './UserBadge';
+// ... 20 more exports
+
+// src/features/user/index.ts
+export * from './components'; // Re-exports everything
+export * from './hooks';
+export * from './utils';
+
+// Consumer imports one component but bundles all
+import { UserAvatar } from '@/features/user';
+```
+
+**Correct (explicit exports):**
+
+```typescript
+// src/features/user/index.ts
+// Explicit, named exports - bundler knows exactly what's used
+export { UserProfile } from './components/UserProfile';
+export { UserSettings } from './components/UserSettings';
+export { UserAvatar } from './components/UserAvatar';
+export { useUser } from './hooks/useUser';
+export type { User } from './types';
+
+// Consumer
+import { UserAvatar } from '@/features/user'; // Only UserAvatar bundled
+```
+
+**Alternative for large features:**
+
+```typescript
+// Direct imports for specific needs
+import { UserAvatar } from '@/features/user/components/UserAvatar';
+
+// This is acceptable when:
+// 1. Feature has 15+ exports
+// 2. Consumer only needs one specific item
+// 3. Bundle size is critical
+```
+
+**When barrel files are OK:**
+- Feature public API (index.ts) with explicit exports
+- Small features with < 10 exports
+- Type-only exports (no runtime impact)
+
+Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)
diff --git a/.agents/skills/feature-arch/references/import-no-cross-feature.md b/.agents/skills/feature-arch/references/import-no-cross-feature.md
new file mode 100644
index 0000000..4d13027
--- /dev/null
+++ b/.agents/skills/feature-arch/references/import-no-cross-feature.md
@@ -0,0 +1,84 @@
+---
+title: Prohibit Cross-Feature Imports
+impact: CRITICAL
+impactDescription: Prevents feature coupling; enables independent feature development
+tags: import, cross-feature, coupling, isolation
+---
+
+## Prohibit Cross-Feature Imports
+
+Features must not import directly from other features. When features need to interact, compose them at the app layer. Direct cross-feature imports create hidden dependencies that make features impossible to modify independently.
+
+**Incorrect (cross-feature imports):**
+
+```typescript
+// src/features/checkout/components/CheckoutSummary.tsx
+import { ProductCard } from '@/features/product/components/ProductCard'; // WRONG
+import { useCart } from '@/features/cart/hooks/useCart'; // WRONG
+import { UserAddress } from '@/features/user/components/UserAddress'; // WRONG
+
+export function CheckoutSummary() {
+ const cart = useCart();
+ return (
+
+ {cart.items.map(item =>
)}
+
+
+ );
+}
+```
+
+**Correct (composition at app layer):**
+
+```typescript
+// src/features/checkout/components/CheckoutSummary.tsx
+interface CheckoutSummaryProps {
+ items: CartItem[];
+ renderProduct: (item: CartItem) => ReactNode;
+ addressSection: ReactNode;
+}
+
+export function CheckoutSummary({ items, renderProduct, addressSection }: CheckoutSummaryProps) {
+ return (
+
+ {items.map(renderProduct)}
+ {addressSection}
+
+ );
+}
+
+// src/app/pages/CheckoutPage.tsx
+import { CheckoutSummary } from '@/features/checkout';
+import { ProductCard } from '@/features/product';
+import { UserAddress } from '@/features/user';
+import { useCart } from '@/features/cart';
+
+export function CheckoutPage() {
+ const cart = useCart();
+ return (
+ }
+ addressSection={ }
+ />
+ );
+}
+```
+
+**ESLint enforcement per feature:**
+
+```javascript
+// .eslintrc.js
+rules: {
+ 'import/no-restricted-paths': ['error', {
+ zones: [
+ { target: './src/features/checkout', from: './src/features/product' },
+ { target: './src/features/checkout', from: './src/features/cart' },
+ { target: './src/features/checkout', from: './src/features/user' },
+ // Add for each feature combination
+ ],
+ }],
+}
+```
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/import-path-aliases.md b/.agents/skills/feature-arch/references/import-path-aliases.md
new file mode 100644
index 0000000..3711c99
--- /dev/null
+++ b/.agents/skills/feature-arch/references/import-path-aliases.md
@@ -0,0 +1,64 @@
+---
+title: Use Consistent Path Aliases
+impact: HIGH
+impactDescription: Eliminates ../../../ chains; makes imports self-documenting
+tags: import, aliases, paths, navigation
+---
+
+## Use Consistent Path Aliases
+
+Configure path aliases to avoid relative import chains. Aliases make imports self-documenting by showing feature ownership clearly and survive file relocations within the same feature.
+
+**Incorrect (deep relative paths):**
+
+```typescript
+// src/features/checkout/components/PaymentForm.tsx
+import { Button } from '../../../shared/components/Button';
+import { useAuth } from '../../../features/auth/hooks/useAuth'; // Also wrong: cross-feature
+import { formatCurrency } from '../../../shared/utils/formatCurrency';
+import { useCheckout } from '../hooks/useCheckout';
+```
+
+**Correct (path aliases):**
+
+```typescript
+// src/features/checkout/components/PaymentForm.tsx
+import { Button } from '@/shared/components/Button';
+import { formatCurrency } from '@/shared/utils/formatCurrency';
+import { useCheckout } from '../hooks/useCheckout'; // Same feature = relative OK
+```
+
+**tsconfig.json:**
+
+```json
+{
+ "compilerOptions": {
+ "paths": {
+ "@/*": ["./src/*"],
+ "@/shared/*": ["./src/shared/*"],
+ "@/features/*": ["./src/features/*"],
+ "@/app/*": ["./src/app/*"]
+ }
+ }
+}
+```
+
+**Guidelines:**
+- Use `@/` prefix for absolute imports from src
+- Use relative imports (`./`, `../`) within the same feature
+- Relative imports within a feature make the feature more portable
+
+**Vite configuration:**
+
+```typescript
+// vite.config.ts
+export default defineConfig({
+ resolve: {
+ alias: {
+ '@': path.resolve(__dirname, './src'),
+ },
+ },
+});
+```
+
+Reference: [Robin Wieruch - React Folder Structure](https://www.robinwieruch.de/react-folder-structure/)
diff --git a/.agents/skills/feature-arch/references/import-public-api.md b/.agents/skills/feature-arch/references/import-public-api.md
new file mode 100644
index 0000000..766d3e9
--- /dev/null
+++ b/.agents/skills/feature-arch/references/import-public-api.md
@@ -0,0 +1,67 @@
+---
+title: Export Through Public API Only
+impact: CRITICAL
+impactDescription: Prevents deep imports; enables internal refactoring without breaking consumers
+tags: import, public-api, encapsulation, index
+---
+
+## Export Through Public API Only
+
+Each feature should have a single entry point (index.ts) that exports its public API. External code should never import internal files directly. This allows internal restructuring without affecting consumers.
+
+**Incorrect (deep imports into feature internals):**
+
+```typescript
+// src/app/pages/UserPage.tsx
+import { UserProfile } from '@/features/user/components/UserProfile';
+import { useUser } from '@/features/user/hooks/useUser';
+import { formatUserName } from '@/features/user/utils/formatters';
+import { User } from '@/features/user/types/user';
+```
+
+**Correct (import from public API):**
+
+```typescript
+// src/features/user/index.ts (public API)
+export { UserProfile } from './components/UserProfile';
+export { UserSettings } from './components/UserSettings';
+export { useUser } from './hooks/useUser';
+export type { User, UserRole } from './types';
+// Note: formatUserName is NOT exported - it's internal
+
+// src/app/pages/UserPage.tsx
+import { UserProfile, useUser } from '@/features/user';
+import type { User } from '@/features/user';
+```
+
+**Internal file can import freely:**
+
+```typescript
+// src/features/user/components/UserProfile.tsx
+import { useUser } from '../hooks/useUser';
+import { formatUserName } from '../utils/formatters'; // Internal util
+import type { User } from '../types';
+```
+
+**ESLint enforcement:**
+
+```javascript
+// .eslintrc.js
+rules: {
+ 'no-restricted-imports': ['error', {
+ patterns: [
+ {
+ group: ['@/features/*/components/*', '@/features/*/hooks/*', '@/features/*/utils/*'],
+ message: 'Import from feature index.ts instead',
+ },
+ ],
+ }],
+}
+```
+
+**Benefits:**
+- Refactor internal structure without breaking external imports
+- Clear contract of what a feature provides
+- Smaller, focused public surface area
+
+Reference: [Feature-Sliced Design](https://feature-sliced.design/)
diff --git a/.agents/skills/feature-arch/references/import-type-only.md b/.agents/skills/feature-arch/references/import-type-only.md
new file mode 100644
index 0000000..2fed447
--- /dev/null
+++ b/.agents/skills/feature-arch/references/import-type-only.md
@@ -0,0 +1,81 @@
+---
+title: Use Type-Only Imports for Types
+impact: MEDIUM
+impactDescription: Enables cross-feature type sharing without runtime coupling
+tags: import, types, typescript, type-only
+---
+
+## Use Type-Only Imports for Types
+
+Use `import type` syntax when importing only TypeScript types. This ensures types are stripped at compile time and allows sharing types across features without creating runtime dependencies.
+
+**Incorrect (mixing type and value imports):**
+
+```typescript
+// src/features/checkout/components/CheckoutForm.tsx
+import { User, useUser } from '@/features/user'; // Creates runtime dependency for type
+
+export function CheckoutForm({ userId }: { userId: string }) {
+ // We only need the User type, not useUser
+ const [user, setUser] = useState(null);
+}
+```
+
+**Correct (separate type imports):**
+
+```typescript
+// src/features/checkout/components/CheckoutForm.tsx
+import type { User } from '@/features/user'; // Type-only, no runtime dependency
+
+export function CheckoutForm({ userId }: { userId: string }) {
+ const [user, setUser] = useState(null);
+}
+```
+
+**Shared types for cross-feature contracts:**
+
+```typescript
+// src/shared/types/entities.ts
+export interface User {
+ id: string;
+ email: string;
+ name: string;
+}
+
+export interface Product {
+ id: string;
+ name: string;
+ price: number;
+}
+
+// Features import shared types
+// src/features/checkout/types.ts
+import type { User, Product } from '@/shared/types/entities';
+
+export interface CheckoutItem {
+ product: Product;
+ quantity: number;
+}
+
+export interface CheckoutSession {
+ user: User;
+ items: CheckoutItem[];
+}
+```
+
+**Benefits:**
+- No runtime bundle impact for type-only imports
+- Clear distinction between runtime and compile-time dependencies
+- Enables type sharing without architectural coupling
+
+**TypeScript configuration:**
+
+```json
+{
+ "compilerOptions": {
+ "verbatimModuleSyntax": true // Enforces type-only imports
+ }
+}
+```
+
+Reference: [TypeScript Handbook - Type-Only Imports](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export)
diff --git a/.agents/skills/feature-arch/references/import-unidirectional-flow.md b/.agents/skills/feature-arch/references/import-unidirectional-flow.md
new file mode 100644
index 0000000..e3fb5ef
--- /dev/null
+++ b/.agents/skills/feature-arch/references/import-unidirectional-flow.md
@@ -0,0 +1,82 @@
+---
+title: Enforce Unidirectional Import Flow
+impact: CRITICAL
+impactDescription: Prevents circular dependencies; enables deterministic build order
+tags: import, unidirectional, dependencies, architecture
+---
+
+## Enforce Unidirectional Import Flow
+
+Imports must flow in one direction: `shared → features → app`. Features can import from shared, and app can import from both, but never the reverse. This prevents circular dependencies that cause build failures and makes the dependency graph predictable.
+
+**Incorrect (bidirectional imports):**
+
+```typescript
+// src/shared/utils/analytics.ts
+import { useAuth } from '@/features/auth/hooks/useAuth'; // WRONG: shared → features
+
+export function trackEvent(event: string) {
+ const { user } = useAuth();
+ // ...
+}
+```
+
+```typescript
+// src/features/user/components/UserProfile.tsx
+import { AppLayout } from '@/app/layouts/AppLayout'; // WRONG: features → app
+
+export function UserProfile() {
+ return ... ;
+}
+```
+
+**Correct (unidirectional flow):**
+
+```typescript
+// Dependency flow: shared → features → app
+
+// src/shared/utils/analytics.ts
+export function trackEvent(event: string, userId?: string) {
+ // No feature imports - userId passed as parameter
+}
+
+// src/features/user/components/UserProfile.tsx
+import { formatDate } from '@/shared/utils/formatDate'; // OK: shared used by feature
+import { trackEvent } from '@/shared/utils/analytics';
+
+export function UserProfile({ user }) {
+ useEffect(() => {
+ trackEvent('profile_view', user.id);
+ }, []);
+ return ...
;
+}
+
+// src/app/pages/UserPage.tsx
+import { UserProfile } from '@/features/user'; // OK: app uses features
+import { AppLayout } from '@/app/layouts/AppLayout';
+
+export function UserPage() {
+ return (
+
+
+
+ );
+}
+```
+
+**ESLint enforcement:**
+
+```javascript
+// .eslintrc.js
+rules: {
+ 'import/no-restricted-paths': ['error', {
+ zones: [
+ { target: './src/shared', from: './src/features' },
+ { target: './src/shared', from: './src/app' },
+ { target: './src/features', from: './src/app' },
+ ],
+ }],
+}
+```
+
+Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)
diff --git a/.agents/skills/feature-arch/references/name-descriptive-exports.md b/.agents/skills/feature-arch/references/name-descriptive-exports.md
new file mode 100644
index 0000000..11e0aea
--- /dev/null
+++ b/.agents/skills/feature-arch/references/name-descriptive-exports.md
@@ -0,0 +1,65 @@
+---
+title: Use Descriptive Export Names
+impact: LOW
+impactDescription: Enables IDE autocomplete; makes imports self-documenting
+tags: name, exports, descriptive, clarity
+---
+
+## Use Descriptive Export Names
+
+Export names should be descriptive and unique across the codebase. Generic names like `Card`, `List`, or `Button` cause confusion when multiple features export similar components.
+
+**Incorrect (generic export names):**
+
+```typescript
+// src/features/user/components/Card.tsx
+export function Card({ user }) { ... } // Which card?
+
+// src/features/product/components/Card.tsx
+export function Card({ product }) { ... } // Collision!
+
+// Import confusion
+import { Card } from '@/features/user'; // UserCard? ProductCard?
+import { Card as ProductCard } from '@/features/product'; // Requires alias
+```
+
+**Correct (descriptive export names):**
+
+```typescript
+// src/features/user/components/UserCard.tsx
+export function UserCard({ user }: { user: User }) { ... }
+
+// src/features/product/components/ProductCard.tsx
+export function ProductCard({ product }: { product: Product }) { ... }
+
+// Clear imports
+import { UserCard } from '@/features/user';
+import { ProductCard } from '@/features/product';
+```
+
+**Naming patterns:**
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| Feature component | `{Feature}{Component}` | `UserProfile`, `CartSummary` |
+| Feature hook | `use{Feature}{Action}` | `useUserAuth`, `useCartItems` |
+| Feature API | `{action}{Feature}` | `getUser`, `updateCart` |
+| Feature store | `use{Feature}Store` | `useCartStore`, `useUserStore` |
+
+**Exception for shared components:**
+
+```typescript
+// Shared components can use generic names - they're not feature-specific
+// src/shared/components/Button.tsx
+export function Button({ children, ...props }) { ... }
+
+// src/shared/components/Card.tsx
+export function Card({ children, ...props }) { ... }
+```
+
+**Benefits:**
+- IDE autocomplete shows meaningful options
+- Imports are self-documenting
+- No aliasing required
+
+Reference: [React Naming Conventions](https://react.dev/learn/thinking-in-react)
diff --git a/.agents/skills/feature-arch/references/name-feature-naming.md b/.agents/skills/feature-arch/references/name-feature-naming.md
new file mode 100644
index 0000000..dfcb6ce
--- /dev/null
+++ b/.agents/skills/feature-arch/references/name-feature-naming.md
@@ -0,0 +1,60 @@
+---
+title: Use Domain-Driven Feature Names
+impact: LOW
+impactDescription: Improves discoverability; aligns code with business terminology
+tags: name, features, domain, naming
+---
+
+## Use Domain-Driven Feature Names
+
+Name features after business domains, not technical implementations. This makes the codebase navigable for non-developers and ensures feature boundaries align with business boundaries.
+
+**Incorrect (technical naming):**
+
+```text
+src/features/
+├── data-grid/ # What data? What domain?
+├── form-handler/ # What form? What entity?
+├── api-client/ # Generic technical concern
+├── modal-manager/ # UI pattern, not domain
+└── list-view/ # Generic view pattern
+```
+
+**Correct (domain naming):**
+
+```text
+src/features/
+├── user/ # User management domain
+├── product/ # Product catalog domain
+├── cart/ # Shopping cart domain
+├── checkout/ # Checkout/payment domain
+├── order/ # Order management domain
+├── notification/ # Notification domain
+└── search/ # Search domain
+```
+
+**Naming guidelines:**
+
+| Domain | Good Name | Bad Name |
+|--------|-----------|----------|
+| User management | `user`, `account` | `profile-component` |
+| Product catalog | `product`, `catalog` | `item-list` |
+| Shopping | `cart`, `checkout` | `purchase-flow` |
+| Authentication | `auth` | `login-system` |
+
+**Sub-features:**
+
+```text
+src/features/
+├── user/
+│ ├── ... # Core user feature
+├── user-preferences/ # Distinct sub-domain
+└── user-notifications/ # Another sub-domain
+```
+
+**Ask these questions:**
+- Would a product manager understand this name?
+- Does this map to a business capability?
+- Would this name make sense in a requirements document?
+
+Reference: [Bounded Context - Martin Fowler](https://martinfowler.com/bliki/BoundedContext.html)
diff --git a/.agents/skills/feature-arch/references/name-file-conventions.md b/.agents/skills/feature-arch/references/name-file-conventions.md
new file mode 100644
index 0000000..9325e0b
--- /dev/null
+++ b/.agents/skills/feature-arch/references/name-file-conventions.md
@@ -0,0 +1,79 @@
+---
+title: Use Consistent File Naming Conventions
+impact: LOW
+impactDescription: Enables pattern-based tooling; reduces cognitive load
+tags: name, files, conventions, consistency
+---
+
+## Use Consistent File Naming Conventions
+
+Establish and follow consistent file naming patterns. This enables automated tooling, makes files predictable, and reduces decision fatigue.
+
+**Incorrect (inconsistent naming):**
+
+```
+src/features/user/
+├── components/
+│ ├── UserProfile.tsx # PascalCase
+│ ├── user-avatar.tsx # kebab-case
+│ ├── userBadge.tsx # camelCase
+│ └── User_Settings.tsx # Snake_Case
+├── hooks/
+│ ├── useUser.ts # camelCase
+│ └── use-auth.ts # kebab-case
+└── api/
+ ├── getUser.ts # camelCase
+ └── user-api.ts # kebab-case
+```
+
+**Correct (consistent conventions):**
+
+```
+src/features/user/
+├── components/
+│ ├── UserProfile.tsx # PascalCase for components
+│ ├── UserAvatar.tsx
+│ ├── UserBadge.tsx
+│ └── UserSettings.tsx
+├── hooks/
+│ ├── useUser.ts # camelCase with use prefix
+│ └── useUserAuth.ts
+├── api/
+│ ├── get-user.ts # kebab-case for non-components
+│ ├── update-user.ts
+│ └── delete-user.ts
+├── stores/
+│ └── user-store.ts # kebab-case
+├── types/
+│ └── index.ts
+└── utils/
+ └── format-user-name.ts # kebab-case
+```
+
+**Recommended conventions:**
+
+| File Type | Convention | Example |
+|-----------|------------|---------|
+| React components | PascalCase | `UserProfile.tsx` |
+| Hooks | camelCase with use prefix | `useUser.ts` |
+| API functions | kebab-case | `get-user.ts` |
+| Stores | kebab-case | `user-store.ts` |
+| Utilities | kebab-case | `format-date.ts` |
+| Types | index.ts or kebab-case | `types/index.ts` |
+| Tests | match source + .test | `UserProfile.test.tsx` |
+
+**ESLint enforcement:**
+
+```javascript
+// .eslintrc.js
+rules: {
+ 'unicorn/filename-case': ['error', {
+ cases: {
+ pascalCase: true, // For .tsx files
+ kebabCase: true, // For .ts files
+ },
+ }],
+}
+```
+
+Reference: [Airbnb React Style Guide](https://github.com/airbnb/javascript/tree/master/react)
diff --git a/.agents/skills/feature-arch/references/struct-app-layer.md b/.agents/skills/feature-arch/references/struct-app-layer.md
new file mode 100644
index 0000000..564304e
--- /dev/null
+++ b/.agents/skills/feature-arch/references/struct-app-layer.md
@@ -0,0 +1,73 @@
+---
+title: Separate App Layer from Features
+impact: HIGH
+impactDescription: Isolates global concerns; enables feature modules to remain pure
+tags: struct, app-layer, providers, routing
+---
+
+## Separate App Layer from Features
+
+The app layer handles global concerns: routing, providers, initialization, and global layouts. Features should not contain routing logic or provider setup. This separation allows features to be portable and testable in isolation.
+
+**Incorrect (routing and providers mixed with features):**
+
+```
+src/features/user/
+├── components/
+│ └── UserProfile.tsx
+├── UserRoutes.tsx # Routing logic in feature
+└── UserProvider.tsx # Provider in feature
+```
+
+```typescript
+// src/features/user/UserRoutes.tsx
+import { Routes, Route } from 'react-router-dom';
+
+export function UserRoutes() {
+ return (
+
+ } />
+ } />
+
+ );
+}
+```
+
+**Correct (app layer owns routing and providers):**
+
+```
+src/
+├── app/
+│ ├── providers/
+│ │ ├── AuthProvider.tsx
+│ │ ├── QueryProvider.tsx
+│ │ └── index.tsx
+│ ├── routes/
+│ │ ├── index.tsx
+│ │ └── protected-routes.tsx
+│ └── App.tsx
+└── features/
+ └── user/
+ ├── components/
+ │ ├── UserProfile.tsx
+ │ └── UserSettings.tsx
+ └── index.ts
+```
+
+```typescript
+// src/app/routes/index.tsx
+import { UserProfile, UserSettings } from '@/features/user';
+
+export const routes = [
+ { path: '/profile', element: },
+ { path: '/settings', element: },
+];
+```
+
+**App layer responsibilities:**
+- Route definitions and navigation
+- Provider composition (Auth, Query, Theme)
+- Global error boundaries
+- Application initialization
+
+Reference: [Feature-Sliced Design](https://feature-sliced.design/)
diff --git a/.agents/skills/feature-arch/references/struct-feature-folders.md b/.agents/skills/feature-arch/references/struct-feature-folders.md
new file mode 100644
index 0000000..8740ce2
--- /dev/null
+++ b/.agents/skills/feature-arch/references/struct-feature-folders.md
@@ -0,0 +1,70 @@
+---
+title: Organize by Feature, Not Technical Type
+impact: CRITICAL
+impactDescription: Eliminates cross-file navigation; reduces onboarding time by 50%+
+tags: struct, organization, feature-folders, scalability
+---
+
+## Organize by Feature, Not Technical Type
+
+Technical grouping (components/, hooks/, utils/) forces developers to navigate multiple directories for single features. Feature-based organization colocates all related code, making features self-documenting and independently deployable.
+
+**Incorrect (technical grouping):**
+
+```
+src/
+├── components/
+│ ├── PostCard.tsx
+│ ├── CommentList.tsx
+│ └── UserAvatar.tsx
+├── hooks/
+│ ├── usePost.ts
+│ ├── useComments.ts
+│ └── useUser.ts
+├── api/
+│ ├── posts.ts
+│ ├── comments.ts
+│ └── users.ts
+└── utils/
+ ├── postHelpers.ts
+ └── commentHelpers.ts
+```
+
+**Correct (feature-based grouping):**
+
+```
+src/
+├── features/
+│ ├── post/
+│ │ ├── components/
+│ │ │ └── PostCard.tsx
+│ │ ├── hooks/
+│ │ │ └── usePost.ts
+│ │ ├── api/
+│ │ │ └── get-post.ts
+│ │ └── utils/
+│ │ └── postHelpers.ts
+│ ├── comment/
+│ │ ├── components/
+│ │ │ └── CommentList.tsx
+│ │ ├── hooks/
+│ │ │ └── useComments.ts
+│ │ └── api/
+│ │ └── get-comments.ts
+│ └── user/
+│ ├── components/
+│ │ └── UserAvatar.tsx
+│ └── hooks/
+│ └── useUser.ts
+└── shared/
+ └── components/
+ └── Button.tsx
+```
+
+**Benefits:**
+- Adding a feature = adding one folder
+- Removing a feature = removing one folder
+- Feature ownership is immediately clear
+- Teams can work on different features without conflicts
+
+Reference: [Robin Wieruch - React Feature Architecture](https://www.robinwieruch.de/react-feature-architecture/)
diff --git a/.agents/skills/feature-arch/references/struct-feature-self-contained.md b/.agents/skills/feature-arch/references/struct-feature-self-contained.md
new file mode 100644
index 0000000..1a377b9
--- /dev/null
+++ b/.agents/skills/feature-arch/references/struct-feature-self-contained.md
@@ -0,0 +1,62 @@
+---
+title: Make Features Self-Contained
+impact: CRITICAL
+impactDescription: Enables independent deployment and parallel team development
+tags: struct, isolation, self-contained, modularity
+---
+
+## Make Features Self-Contained
+
+Each feature folder should contain everything needed to implement that feature. When a feature requires code from multiple places, it becomes entangled with other features and cannot evolve independently.
+
+**Incorrect (scattered feature code):**
+
+```typescript
+// src/components/checkout/CheckoutForm.tsx
+import { useCart } from '../../hooks/useCart';
+import { validateCard } from '../../utils/validation';
+import { CartSummary } from '../cart/CartSummary';
+import { paymentApi } from '../../api/payment';
+
+export function CheckoutForm() {
+ const cart = useCart();
+ // Feature depends on 4 different locations
+}
+```
+
+**Correct (self-contained feature):**
+
+```typescript
+// src/features/checkout/components/CheckoutForm.tsx
+import { useCart } from '../hooks/useCart';
+import { validateCard } from '../utils/validation';
+import { CartSummary } from '../components/CartSummary';
+import { submitPayment } from '../api/submit-payment';
+
+export function CheckoutForm() {
+ const cart = useCart();
+ // All imports are within the feature
+}
+```
+
+**Feature folder structure:**
+
+```
+features/checkout/
+├── api/
+│ └── submit-payment.ts
+├── components/
+│ ├── CheckoutForm.tsx
+│ └── CartSummary.tsx
+├── hooks/
+│ └── useCart.ts
+├── utils/
+│ └── validation.ts
+└── index.ts
+```
+
+**When NOT to use this pattern:**
+- Truly generic utilities (date formatting, string helpers) belong in `shared/`
+- UI primitives (Button, Input) belong in `shared/components/`
+
+Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)
diff --git a/.agents/skills/feature-arch/references/struct-flat-hierarchy.md b/.agents/skills/feature-arch/references/struct-flat-hierarchy.md
new file mode 100644
index 0000000..4a21b00
--- /dev/null
+++ b/.agents/skills/feature-arch/references/struct-flat-hierarchy.md
@@ -0,0 +1,58 @@
+---
+title: Keep Directory Hierarchy Flat
+impact: CRITICAL
+impactDescription: Reduces cognitive load; prevents 5+ level deep import paths
+tags: struct, nesting, hierarchy, navigation
+---
+
+## Keep Directory Hierarchy Flat
+
+Deep nesting creates long import paths, makes file relocation difficult, and obscures the overall structure. Limit nesting to 2-3 levels within features.
+
+**Incorrect (deep nesting):**
+
+```
+src/features/checkout/
+├── components/
+│ ├── form/
+│ │ ├── fields/
+│ │ │ ├── payment/
+│ │ │ │ └── CardInput.tsx
+│ │ │ └── shipping/
+│ │ │ └── AddressInput.tsx
+│ │ └── FormWrapper.tsx
+│ └── summary/
+│ └── OrderSummary.tsx
+```
+
+```typescript
+// Import path is 6 levels deep
+import { CardInput } from '../../../components/form/fields/payment/CardInput';
+```
+
+**Correct (flat hierarchy):**
+
+```
+src/features/checkout/
+├── components/
+│ ├── CardInput.tsx
+│ ├── AddressInput.tsx
+│ ├── FormWrapper.tsx
+│ └── OrderSummary.tsx
+```
+
+```typescript
+// Import path is 2 levels
+import { CardInput } from '../components/CardInput';
+```
+
+**When deeper nesting is acceptable:**
+- Feature has 20+ components (consider splitting into sub-features)
+- Clear categorical distinction (e.g., `forms/` vs `displays/`)
+
+**Guidelines:**
+- Maximum 3 levels within a feature folder
+- If you need deeper nesting, the feature is likely too large
+- Prefer flat with clear naming over deep with vague naming
+
+Reference: [Robin Wieruch - React Folder Structure](https://www.robinwieruch.de/react-folder-structure/)
diff --git a/.agents/skills/feature-arch/references/struct-optional-segments.md b/.agents/skills/feature-arch/references/struct-optional-segments.md
new file mode 100644
index 0000000..419ed23
--- /dev/null
+++ b/.agents/skills/feature-arch/references/struct-optional-segments.md
@@ -0,0 +1,72 @@
+---
+title: Include Only Necessary Segments
+impact: HIGH
+impactDescription: Prevents empty folder clutter; keeps features minimal and focused
+tags: struct, segments, minimal, pragmatic
+---
+
+## Include Only Necessary Segments
+
+Not every feature needs every segment (components/, hooks/, api/, utils/, types/). Start with only what the feature requires and add segments as complexity grows. Empty folders add noise and suggest over-engineering.
+
+**Incorrect (every segment even when unused):**
+
+```
+src/features/notification/
+├── api/ # Empty - notifications are client-side only
+├── components/
+│ └── Toast.tsx
+├── hooks/
+│ └── useNotification.ts
+├── stores/ # Empty - using context instead
+├── types/
+│ └── index.ts # Just re-exports one interface
+└── utils/ # Empty
+```
+
+**Correct (only necessary segments):**
+
+```
+src/features/notification/
+├── components/
+│ └── Toast.tsx
+├── hooks/
+│ └── useNotification.ts
+└── types.ts # Single file, not a folder with one file
+```
+
+**Another example - simple feature:**
+
+```
+src/features/theme/
+├── ThemeProvider.tsx
+├── useTheme.ts
+└── index.ts
+```
+
+**Complex feature with all segments:**
+
+```
+src/features/checkout/
+├── api/
+│ ├── submit-order.ts
+│ └── validate-address.ts
+├── components/
+│ ├── CheckoutForm.tsx
+│ ├── PaymentSection.tsx
+│ └── ShippingSection.tsx
+├── hooks/
+│ ├── useCheckout.ts
+│ └── usePaymentMethods.ts
+├── stores/
+│ └── checkout-store.ts
+├── types/
+│ └── index.ts
+├── utils/
+│ └── validation.ts
+└── index.ts
+```
+
+**Guideline:** Add segments when you have 2+ files that would go there.
+
+Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)
diff --git a/.agents/skills/feature-arch/references/struct-shared-layer.md b/.agents/skills/feature-arch/references/struct-shared-layer.md
new file mode 100644
index 0000000..9702454
--- /dev/null
+++ b/.agents/skills/feature-arch/references/struct-shared-layer.md
@@ -0,0 +1,68 @@
+---
+title: Use Shared Layer for Truly Generic Code Only
+impact: CRITICAL
+impactDescription: Prevents shared/ from becoming a dumping ground; maintains feature boundaries
+tags: struct, shared, reusability, generic
+---
+
+## Use Shared Layer for Truly Generic Code Only
+
+The shared layer should contain only code with high reusability and minimal business logic. When business-specific code lands in shared/, it creates hidden dependencies and prevents features from being truly independent.
+
+**Incorrect (business logic in shared):**
+
+```
+src/shared/
+├── components/
+│ ├── Button.tsx # Generic - OK
+│ ├── ProductCard.tsx # Business-specific - WRONG
+│ └── UserBadge.tsx # Business-specific - WRONG
+├── hooks/
+│ ├── useDebounce.ts # Generic - OK
+│ └── useCheckout.ts # Business-specific - WRONG
+└── utils/
+ ├── formatDate.ts # Generic - OK
+ └── calculateTax.ts # Business-specific - WRONG
+```
+
+**Correct (shared is generic only):**
+
+```
+src/shared/
+├── components/
+│ ├── Button.tsx
+│ ├── Input.tsx
+│ ├── Modal.tsx
+│ └── Tooltip.tsx
+├── hooks/
+│ ├── useDebounce.ts
+│ ├── useLocalStorage.ts
+│ └── useMediaQuery.ts
+└── utils/
+ ├── formatDate.ts
+ ├── formatCurrency.ts
+ └── cn.ts
+```
+
+```
+src/features/product/
+├── components/
+│ └── ProductCard.tsx # Business component lives with feature
+└── ...
+
+src/features/checkout/
+├── hooks/
+│ └── useCheckout.ts # Business hook lives with feature
+├── utils/
+│ └── calculateTax.ts # Business util lives with feature
+└── ...
+```
+
+**Litmus test for shared/:**
+- Would this be useful in a completely different project?
+- Does it contain zero business domain knowledge?
+- Is it used by 3+ features?
+
+If any answer is "no", it belongs in a feature folder.
+
+Reference: [Feature-Sliced Design](https://feature-sliced.design/)
diff --git a/.agents/skills/feature-arch/references/test-colocate-with-feature.md b/.agents/skills/feature-arch/references/test-colocate-with-feature.md
new file mode 100644
index 0000000..20324b2
--- /dev/null
+++ b/.agents/skills/feature-arch/references/test-colocate-with-feature.md
@@ -0,0 +1,78 @@
+---
+title: Colocate Tests with Features
+impact: MEDIUM
+impactDescription: Makes test coverage visible; ensures tests move with features
+tags: test, colocation, organization, feature
+---
+
+## Colocate Tests with Features
+
+Tests should live in the same feature folder as the code they test. When tests are in a separate tests/ folder, they become disconnected from the code, leading to missing coverage and orphaned tests.
+
+**Incorrect (centralized test folder):**
+
+```
+src/
+├── features/
+│ ├── user/
+│ │ └── components/
+│ │ └── UserProfile.tsx
+│ └── cart/
+│ └── hooks/
+│ └── useCart.ts
+└── tests/ # Disconnected from features
+ ├── user/
+ │ └── UserProfile.test.tsx
+ └── cart/
+ └── useCart.test.ts
+```
+
+**Correct (colocated tests):**
+
+```
+src/features/
+├── user/
+│ ├── components/
+│ │ ├── UserProfile.tsx
+│ │ └── __tests__/
+│ │ └── UserProfile.test.tsx
+│ └── hooks/
+│ ├── useUser.ts
+│ └── __tests__/
+│ └── useUser.test.ts
+└── cart/
+ ├── hooks/
+ │ ├── useCart.ts
+ │ └── __tests__/
+ │ └── useCart.test.ts
+ └── api/
+ ├── get-cart.ts
+ └── __tests__/
+ └── get-cart.test.ts
+```
+
+**Alternative: Adjacent files:**
+
+```
+src/features/user/components/
+├── UserProfile.tsx
+└── UserProfile.test.tsx # Same folder, no __tests__ subfolder
+```
+
+**Benefits:**
+- Moving a feature moves its tests
+- Deleting a feature deletes its tests
+- Test coverage is visible in the feature folder
+- Easy to see what's tested at a glance
+
+**vitest.config.ts:**
+
+```typescript
+export default defineConfig({
+ test: {
+ include: ['src/**/*.test.{ts,tsx}'],
+ },
+});
+```
+
+Reference: [Bulletproof React - Project Structure](https://github.com/alan2207/bulletproof-react/blob/master/docs/project-structure.md)
diff --git a/.agents/skills/feature-arch/references/test-feature-isolation.md b/.agents/skills/feature-arch/references/test-feature-isolation.md
new file mode 100644
index 0000000..7915afb
--- /dev/null
+++ b/.agents/skills/feature-arch/references/test-feature-isolation.md
@@ -0,0 +1,88 @@
+---
+title: Test Features in Isolation
+impact: MEDIUM
+impactDescription: Enables faster tests; provides clear failure attribution
+tags: test, isolation, mocking, independence
+---
+
+## Test Features in Isolation
+
+Feature tests should mock cross-feature dependencies. When tests use real implementations of other features, they become slow, flaky, and failures are hard to attribute.
+
+**Incorrect (integrated feature tests):**
+
+```typescript
+// Testing checkout feature but using real cart and user features
+describe('CheckoutForm', () => {
+ it('submits order', async () => {
+ // Test depends on cart and user working correctly
+ render(
+
+
+
+
+
+
+
+ );
+
+ // If cart has a bug, checkout tests fail
+ // Slow because it's testing 3 features
+ });
+});
+```
+
+**Correct (isolated feature tests):**
+
+```typescript
+// src/features/checkout/components/__tests__/CheckoutForm.test.tsx
+describe('CheckoutForm', () => {
+ const mockItems = [
+ { id: '1', name: 'Product', price: 100, quantity: 2 },
+ ];
+
+ it('submits order with provided items', async () => {
+ const onSubmit = vi.fn();
+
+ render(
+
+ );
+
+ await userEvent.click(screen.getByRole('button', { name: /submit/i }));
+
+ expect(onSubmit).toHaveBeenCalledWith({
+ items: mockItems,
+ userId: 'user-123',
+ });
+ });
+
+ it('shows empty state when no items', () => {
+ render( );
+
+ expect(screen.getByText(/cart is empty/i)).toBeInTheDocument();
+ });
+});
+```
+
+**Mock cross-feature hooks:**
+
+```typescript
+// Mock the cart feature's exported hook
+vi.mock('@/features/cart', () => ({
+ useCart: () => ({
+ items: [{ id: '1', name: 'Test', price: 50, quantity: 1 }],
+ total: 50,
+ }),
+}));
+```
+
+**Benefits:**
+- Fast tests (no unnecessary dependencies)
+- Clear failure attribution
+- Tests document the feature's interface
+
+Reference: [Testing Library - Guiding Principles](https://testing-library.com/docs/guiding-principles)
diff --git a/.agents/skills/feature-arch/references/test-integration-at-app-layer.md b/.agents/skills/feature-arch/references/test-integration-at-app-layer.md
new file mode 100644
index 0000000..4ed73d5
--- /dev/null
+++ b/.agents/skills/feature-arch/references/test-integration-at-app-layer.md
@@ -0,0 +1,87 @@
+---
+title: Write Integration Tests at App Layer
+impact: MEDIUM
+impactDescription: Verifies feature composition; catches integration bugs
+tags: test, integration, e2e, app-layer
+---
+
+## Write Integration Tests at App Layer
+
+While features should be tested in isolation, integration tests that verify features work together belong at the app layer. This matches the composition structure of the application.
+
+**Incorrect (integration tests inside features):**
+
+```typescript
+// src/features/checkout/__tests__/checkout-integration.test.tsx
+// WRONG: Integration test inside a feature folder
+import { CartProvider } from '@/features/cart';
+import { UserProvider } from '@/features/user';
+import { CheckoutForm } from '../components/CheckoutForm';
+
+describe('Checkout Integration', () => {
+ it('completes checkout with cart and user', async () => {
+ render(
+
+
+
+
+
+ );
+ // Feature test depends on other features
+ });
+});
+```
+
+**Correct (integration tests at app layer):**
+
+```typescript
+// src/app/__tests__/checkout-flow.test.tsx
+// Correct: Integration test at app layer where features are composed
+describe('Checkout Flow Integration', () => {
+ it('completes order from cart to confirmation', async () => {
+ render(
+
+
+
+ );
+
+ // Add product to cart (cart feature)
+ await userEvent.click(screen.getByRole('button', { name: /add to cart/i }));
+
+ // Navigate to checkout (routing)
+ await userEvent.click(screen.getByRole('link', { name: /checkout/i }));
+
+ // Fill checkout form (checkout feature)
+ await userEvent.type(screen.getByLabelText(/email/i), 'test@example.com');
+ await userEvent.click(screen.getByRole('button', { name: /place order/i }));
+
+ // Verify confirmation (order feature)
+ expect(await screen.findByText(/order confirmed/i)).toBeInTheDocument();
+ });
+});
+```
+
+**E2E tests for critical paths:**
+
+```typescript
+// e2e/checkout.spec.ts
+test('complete purchase flow', async ({ page }) => {
+ await page.goto('/products');
+ await page.click('[data-testid="add-to-cart"]');
+ await page.click('[data-testid="go-to-checkout"]');
+ await page.fill('[name="email"]', 'test@example.com');
+ await page.click('text=Place Order');
+ await expect(page.locator('text=Order Confirmed')).toBeVisible();
+});
+```
+
+**Test layer structure:**
+
+```
+tests/
+├── unit/ # Fast, isolated tests (run on every commit)
+├── integration/ # Feature composition tests (run on PR)
+└── e2e/ # Full user journeys (run before deploy)
+```
+
+Reference: [Testing Trophy - Kent C. Dodds](https://kentcdodds.com/blog/the-testing-trophy-and-testing-classifications)
diff --git a/.agents/skills/feature-arch/references/test-shared-utilities.md b/.agents/skills/feature-arch/references/test-shared-utilities.md
new file mode 100644
index 0000000..ea4d93d
--- /dev/null
+++ b/.agents/skills/feature-arch/references/test-shared-utilities.md
@@ -0,0 +1,94 @@
+---
+title: Create Feature-Specific Test Utilities
+impact: MEDIUM
+impactDescription: Reduces test boilerplate; ensures consistent test setup
+tags: test, utilities, helpers, fixtures
+---
+
+## Create Feature-Specific Test Utilities
+
+Each feature should have its own test utilities: factories, fixtures, and render wrappers. Shared test utilities become coupled to all features and are hard to maintain.
+
+**Incorrect (global test utilities):**
+
+```typescript
+// src/testing/utils.ts - One file for all features
+export function createMockUser() { ... }
+export function createMockProduct() { ... }
+export function createMockOrder() { ... }
+export function renderWithProviders(ui: ReactNode) {
+ return render(ui, {
+ wrapper: ({ children }) => (
+
+
+
+
+ {children}
+
+
+
+
+ ),
+ });
+}
+```
+
+**Correct (feature-specific utilities):**
+
+```typescript
+// src/features/user/testing/factories.ts
+export function createUser(overrides?: Partial): User {
+ return {
+ id: faker.string.uuid(),
+ email: faker.internet.email(),
+ name: faker.person.fullName(),
+ ...overrides,
+ };
+}
+
+// src/features/user/testing/render.tsx
+export function renderUserFeature(ui: ReactNode) {
+ const queryClient = new QueryClient({
+ defaultOptions: { queries: { retry: false } },
+ });
+
+ return render(ui, {
+ wrapper: ({ children }) => (
+
+ {children}
+
+ ),
+ });
+}
+
+// src/features/user/testing/index.ts
+export { createUser } from './factories';
+export { renderUserFeature } from './render';
+
+// Usage in tests
+import { createUser, renderUserFeature } from '../testing';
+
+describe('UserProfile', () => {
+ it('displays user name', () => {
+ const user = createUser({ name: 'Jane Doe' });
+ renderUserFeature( );
+ expect(screen.getByText('Jane Doe')).toBeInTheDocument();
+ });
+});
+```
+
+**Shared testing utilities (truly generic):**
+
+```typescript
+// src/shared/testing/query-client.ts
+export function createTestQueryClient() {
+ return new QueryClient({
+ defaultOptions: {
+ queries: { retry: false },
+ mutations: { retry: false },
+ },
+ });
+}
+```
+
+Reference: [Testing Library - Setup](https://testing-library.com/docs/react-testing-library/setup)
diff --git a/.agents/skills/msw/SKILL.md b/.agents/skills/msw/SKILL.md
new file mode 100644
index 0000000..9df0ca7
--- /dev/null
+++ b/.agents/skills/msw/SKILL.md
@@ -0,0 +1,121 @@
+---
+name: msw
+description: MSW 2 API mocking for tests.
+---
+
+# MSW Best Practices
+
+Comprehensive API mocking guide for MSW v2 applications (current: MSW 2.15), designed for AI agents and LLMs. Contains 48 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.
+
+## When to Apply
+
+Reference these guidelines when:
+- Setting up MSW for testing or development
+- Writing or organizing request handlers
+- Configuring test environments with MSW
+- Mocking REST or GraphQL APIs
+- Debugging handler matching issues
+- Testing error states and edge cases
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Setup & Initialization | CRITICAL | `setup-` |
+| 2 | Handler Architecture | CRITICAL | `handler-` |
+| 3 | Test Integration | HIGH | `test-` |
+| 4 | Response Patterns | HIGH | `response-` |
+| 5 | Request Matching | MEDIUM-HIGH | `match-` |
+| 6 | GraphQL Mocking | MEDIUM | `graphql-` |
+| 7 | Advanced Patterns | MEDIUM | `advanced-` |
+| 8 | Debugging & Performance | LOW | `debug-` |
+
+## Quick Reference
+
+### 1. Setup & Initialization (CRITICAL)
+
+- `setup-server-node-entrypoint` - Use correct entrypoint for Node.js (msw/node)
+- `setup-lifecycle-hooks` - Configure server lifecycle in test setup
+- `setup-worker-script-commit` - Commit worker script to version control
+- `setup-node-version` - Require Node.js 18+ for MSW v2
+- `setup-unhandled-requests` - Configure unhandled request behavior
+- `setup-typescript-config` - Configure TypeScript for MSW v2
+
+### 2. Handler Architecture (CRITICAL)
+
+- `handler-happy-path-first` - Define happy path handlers as baseline
+- `handler-domain-grouping` - Group handlers by domain
+- `handler-absolute-urls` - Use absolute URLs in handlers
+- `handler-shared-resolvers` - Extract shared response logic into resolvers
+- `handler-v2-response-syntax` - Use MSW v2 response syntax
+- `handler-request-body-parsing` - Explicitly parse request bodies
+- `handler-resolver-argument` - Destructure resolver arguments correctly
+- `handler-reusability-environments` - Share handlers across environments
+
+### 3. Test Integration (HIGH)
+
+- `test-reset-handlers` - Reset handlers after each test
+- `test-avoid-request-assertions` - Avoid direct request assertions
+- `test-concurrent-boundary` - Use server.boundary() for concurrent tests
+- `test-fake-timers-config` - Configure fake timers to preserve queueMicrotask
+- `test-async-utilities` - Use async testing utilities for mock responses
+- `test-clear-request-cache` - Clear request library caches between tests
+- `test-jsdom-environment` - Use correct JSDOM environment for Jest
+
+### 4. Response Patterns (HIGH)
+
+- `response-http-response-helpers` - Use HttpResponse static methods
+- `response-delay-realistic` - Add delays only for timing behavior under test
+- `response-error-simulation` - Simulate error responses correctly
+- `response-one-time-handlers` - Use one-time handlers for sequential scenarios
+- `response-custom-headers` - Set response headers correctly
+- `response-streaming` - Mock streaming responses with ReadableStream
+
+### 5. Request Matching (MEDIUM-HIGH)
+
+- `match-url-patterns` - Use URL path parameters correctly
+- `match-query-params` - Access query parameters from request URL
+- `match-custom-predicate` - Use custom predicates for complex matching
+- `match-http-methods` - Match HTTP methods explicitly
+- `match-handler-order` - Order handlers from specific to general
+
+### 6. GraphQL Mocking (MEDIUM)
+
+- `graphql-operation-handlers` - Use operation name for GraphQL matching
+- `graphql-error-responses` - Return GraphQL errors in correct format
+- `graphql-batched-queries` - Handle batched GraphQL queries
+- `graphql-variables-access` - Access GraphQL variables correctly
+- `graphql-schema-first` - Resolve operations against a GraphQL schema
+
+### 7. Advanced Patterns (MEDIUM)
+
+- `advanced-bypass-requests` - Use bypass() for passthrough requests
+- `advanced-cookies-auth` - Handle cookies and authentication
+- `advanced-dynamic-scenarios` - Implement dynamic mock scenarios
+- `advanced-vitest-browser` - Configure MSW for Vitest browser mode
+- `advanced-file-uploads` - Mock file upload endpoints
+- `advanced-websocket-mocking` - Mock WebSocket connections with ws.link
+- `advanced-playwright-integration` - Use defineNetworkFixture from @msw/playwright
+
+### 8. Debugging & Performance (LOW)
+
+- `debug-lifecycle-events` - Use lifecycle events for debugging
+- `debug-verify-interception` - Verify request interception is working
+- `debug-common-issues` - Know common MSW issues and fixes
+- `debug-request-logging` - Log request details for debugging
+
+## How to Use
+
+Run in the project root first:
+
+```bash
+npx -y @pymodel/react-frontend-skills detect # installed vs. targeted versions
+npx -y @pymodel/react-frontend-skills scan --skill msw # deprecated APIs → rule IDs
+```
+
+Read `references/.md` for each rule above that matches the task and for each `scan` hit: why it matters, then incorrect vs. correct code.
+
+## Related Skills
+
+- For consuming mocked APIs, see `tanstack-query` skill
+- For test framework patterns, see `vitest`; for methodology, see `tdd`
diff --git a/.agents/skills/msw/references/advanced-bypass-requests.md b/.agents/skills/msw/references/advanced-bypass-requests.md
new file mode 100644
index 0000000..85c5dda
--- /dev/null
+++ b/.agents/skills/msw/references/advanced-bypass-requests.md
@@ -0,0 +1,81 @@
+---
+title: Use bypass() for Passthrough Requests
+impact: MEDIUM
+impactDescription: Enables mixing real and mocked APIs; supports hybrid testing
+tags: advanced, bypass, passthrough, real-api, proxy
+---
+
+## Use bypass() for Passthrough Requests
+
+Use `bypass()` to mark requests that should skip MSW interception and hit the real server. This enables hybrid scenarios where some APIs are mocked and others are real.
+
+**Incorrect (request creates infinite loop):**
+
+```typescript
+// Making a fetch inside a handler without bypass creates infinite recursion
+http.get('/api/user', async () => {
+ // This request is intercepted by this same handler!
+ const realResponse = await fetch('/api/user') // Infinite loop
+ return realResponse
+})
+```
+
+**Correct (bypass MSW interception):**
+
+```typescript
+import { http, HttpResponse, bypass } from 'msw'
+
+export const handlers = [
+ // Proxy to real API and modify response
+ http.get('/api/user', async ({ request }) => {
+ // bypass() marks the request to skip MSW
+ const realResponse = await fetch(bypass(request))
+ const realData = await realResponse.json()
+
+ // Augment real data with mock data
+ return HttpResponse.json({
+ ...realData,
+ mockField: 'added by MSW',
+ })
+ }),
+
+ // Conditional passthrough
+ http.get('/api/data', async ({ request }) => {
+ const url = new URL(request.url)
+
+ // Only mock in test environment
+ if (url.searchParams.get('mock') !== 'true') {
+ return fetch(bypass(request))
+ }
+
+ return HttpResponse.json({ mocked: true })
+ }),
+]
+```
+
+**Using passthrough() for unconditional passthrough:**
+
+```typescript
+import { http, passthrough } from 'msw'
+
+export const handlers = [
+ // Always pass through to real API
+ http.get('/api/analytics/*', () => {
+ return passthrough()
+ }),
+
+ // Pass through external APIs
+ http.all('https://external-service.com/*', () => {
+ return passthrough()
+ }),
+]
+```
+
+**Difference between bypass and passthrough:**
+- `bypass(request)`: Use inside a handler to make a real request
+- `passthrough()`: Return from handler to let the original request through
+
+**When NOT to use this pattern:**
+- Fully mocked environments should avoid real API calls
+
+Reference: [MSW bypass API](https://mswjs.io/docs/api/bypass)
diff --git a/.agents/skills/msw/references/advanced-cookies-auth.md b/.agents/skills/msw/references/advanced-cookies-auth.md
new file mode 100644
index 0000000..8ff09b5
--- /dev/null
+++ b/.agents/skills/msw/references/advanced-cookies-auth.md
@@ -0,0 +1,119 @@
+---
+title: Handle Cookies and Authentication
+impact: MEDIUM
+impactDescription: Enables session-based auth testing; validates auth flows
+tags: advanced, cookies, authentication, session, auth
+---
+
+## Handle Cookies and Authentication
+
+Access cookies from the `cookies` object in resolvers and set cookies via response headers. This enables testing of session-based authentication flows.
+
+**Incorrect (ignoring authentication state):**
+
+```typescript
+// Always returns user regardless of auth state
+http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+})
+```
+
+**Correct (cookie-based auth handling):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Login sets session cookie
+ http.post('/api/login', async ({ request }) => {
+ const { email, password } = await request.json()
+
+ if (email === 'john@example.com' && password === 'password') {
+ return HttpResponse.json(
+ { user: { id: '1', email } },
+ {
+ headers: {
+ 'Set-Cookie': 'session=abc123; Path=/; HttpOnly; SameSite=Strict',
+ },
+ }
+ )
+ }
+
+ return HttpResponse.json(
+ { error: 'Invalid credentials' },
+ { status: 401 }
+ )
+ }),
+
+ // Protected endpoint checks cookie
+ http.get('/api/user', ({ cookies }) => {
+ if (!cookies.session) {
+ return HttpResponse.json(
+ { error: 'Not authenticated' },
+ { status: 401 }
+ )
+ }
+
+ // In real app, validate session token
+ return HttpResponse.json({
+ id: '1',
+ name: 'John',
+ email: 'john@example.com',
+ })
+ }),
+
+ // Logout clears cookie
+ http.post('/api/logout', () => {
+ return new HttpResponse(null, {
+ status: 200,
+ headers: {
+ 'Set-Cookie': 'session=; Path=/; Expires=Thu, 01 Jan 1970 00:00:00 GMT',
+ },
+ })
+ }),
+]
+```
+
+**Bearer token authentication:**
+
+```typescript
+http.get('/api/protected', ({ request }) => {
+ const authHeader = request.headers.get('Authorization')
+
+ if (!authHeader?.startsWith('Bearer ')) {
+ return HttpResponse.json(
+ { error: 'Missing token' },
+ { status: 401 }
+ )
+ }
+
+ const token = authHeader.slice(7)
+
+ // Validate token (simplified)
+ if (token === 'valid-token') {
+ return HttpResponse.json({ data: 'protected content' })
+ }
+
+ return HttpResponse.json(
+ { error: 'Invalid token' },
+ { status: 403 }
+ )
+})
+```
+
+**Multiple cookies:**
+
+```typescript
+http.get('/api/preferences', ({ cookies }) => {
+ return HttpResponse.json({
+ theme: cookies.theme || 'light',
+ language: cookies.lang || 'en',
+ userId: cookies.session ? '1' : null,
+ })
+})
+```
+
+**When NOT to use this pattern:**
+- Public endpoints that don't require authentication
+
+Reference: [MSW Cookies](https://mswjs.io/docs/concepts/request-handler#cookies)
diff --git a/.agents/skills/msw/references/advanced-dynamic-scenarios.md b/.agents/skills/msw/references/advanced-dynamic-scenarios.md
new file mode 100644
index 0000000..ab894ed
--- /dev/null
+++ b/.agents/skills/msw/references/advanced-dynamic-scenarios.md
@@ -0,0 +1,114 @@
+---
+title: Implement Dynamic Mock Scenarios
+impact: MEDIUM
+impactDescription: Enables runtime mock state changes; supports complex test flows
+tags: advanced, dynamic, scenarios, state, runtime
+---
+
+## Implement Dynamic Mock Scenarios
+
+Use module-level state or scenario flags to switch between different mock behaviors at runtime. This enables testing different application states without restarting tests.
+
+**Incorrect (static handlers for all scenarios):**
+
+```typescript
+// Can't test different user states without test setup changes
+http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'John', plan: 'free' })
+})
+```
+
+**Correct (dynamic scenario switching):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+// Scenario state
+type Scenario = 'default' | 'premium' | 'expired' | 'error'
+let currentScenario: Scenario = 'default'
+
+// Export function to change scenario
+export function setScenario(scenario: Scenario) {
+ currentScenario = scenario
+}
+
+export const handlers = [
+ http.get('/api/user', () => {
+ switch (currentScenario) {
+ case 'premium':
+ return HttpResponse.json({
+ name: 'John',
+ plan: 'premium',
+ features: ['feature1', 'feature2', 'feature3'],
+ })
+
+ case 'expired':
+ return HttpResponse.json({
+ name: 'John',
+ plan: 'expired',
+ features: [],
+ message: 'Please renew your subscription',
+ })
+
+ case 'error':
+ return HttpResponse.json(
+ { error: 'Service unavailable' },
+ { status: 503 }
+ )
+
+ default:
+ return HttpResponse.json({
+ name: 'John',
+ plan: 'free',
+ features: ['feature1'],
+ })
+ }
+ }),
+]
+```
+
+**Usage in tests:**
+
+```typescript
+import { setScenario } from '../mocks/handlers'
+
+describe('Subscription', () => {
+ afterEach(() => {
+ setScenario('default') // Reset after each test
+ })
+
+ it('shows premium features for premium users', async () => {
+ setScenario('premium')
+ render( )
+ expect(await screen.findByText('Premium Features')).toBeInTheDocument()
+ })
+
+ it('shows renewal prompt for expired users', async () => {
+ setScenario('expired')
+ render( )
+ expect(await screen.findByText('Please renew')).toBeInTheDocument()
+ })
+})
+```
+
+**URL-based scenarios (for development):**
+
+```typescript
+http.get('/api/user', ({ request }) => {
+ const url = new URL(request.url)
+ const scenario = url.searchParams.get('_scenario')
+
+ if (scenario === 'error') {
+ return new HttpResponse(null, { status: 500 })
+ }
+
+ return HttpResponse.json({ name: 'John' })
+})
+
+// In browser: /dashboard?_scenario=error
+```
+
+**When NOT to use this pattern:**
+- Simple tests with single states don't need scenario complexity
+
+Reference: [Dynamic Mock Scenarios](https://mswjs.io/docs/best-practices/dynamic-mock-scenarios)
diff --git a/.agents/skills/msw/references/advanced-file-uploads.md b/.agents/skills/msw/references/advanced-file-uploads.md
new file mode 100644
index 0000000..28191fe
--- /dev/null
+++ b/.agents/skills/msw/references/advanced-file-uploads.md
@@ -0,0 +1,109 @@
+---
+title: Mock File Upload Endpoints
+impact: MEDIUM
+impactDescription: Tests file upload forms and progress indicators
+tags: advanced, upload, file, formdata, multipart
+---
+
+## Mock File Upload Endpoints
+
+Parse `FormData` from requests to mock file upload endpoints. Access uploaded files and other form fields through the standard `FormData` API.
+
+**Incorrect (ignoring multipart data):**
+
+```typescript
+// Can't access uploaded file
+http.post('/api/upload', () => {
+ return HttpResponse.json({ success: true })
+})
+```
+
+**Correct (parsing FormData):**
+
+```typescript
+import { http, HttpResponse, delay } from 'msw'
+
+export const handlers = [
+ // Single file upload
+ http.post('/api/upload', async ({ request }) => {
+ const formData = await request.formData()
+ const file = formData.get('file') as File
+
+ if (!file) {
+ return HttpResponse.json(
+ { error: 'No file provided' },
+ { status: 400 }
+ )
+ }
+
+ // Simulate upload delay based on file size
+ await delay(Math.min(file.size / 1000, 2000))
+
+ return HttpResponse.json({
+ id: crypto.randomUUID(),
+ filename: file.name,
+ size: file.size,
+ mimeType: file.type,
+ url: `https://cdn.example.com/uploads/${file.name}`,
+ })
+ }),
+
+ // Multiple files
+ http.post('/api/upload-multiple', async ({ request }) => {
+ const formData = await request.formData()
+ const files = formData.getAll('files') as File[]
+
+ const results = files.map((file) => ({
+ id: crypto.randomUUID(),
+ filename: file.name,
+ size: file.size,
+ }))
+
+ return HttpResponse.json({ files: results })
+ }),
+
+ // File with additional form fields
+ http.post('/api/profile/avatar', async ({ request }) => {
+ const formData = await request.formData()
+ const avatar = formData.get('avatar') as File
+ const userId = formData.get('userId') as string
+
+ if (!avatar || !userId) {
+ return HttpResponse.json(
+ { error: 'Missing required fields' },
+ { status: 400 }
+ )
+ }
+
+ return HttpResponse.json({
+ userId,
+ avatarUrl: `https://cdn.example.com/avatars/${userId}/${avatar.name}`,
+ })
+ }),
+]
+```
+
+**Validating file types:**
+
+```typescript
+http.post('/api/upload/image', async ({ request }) => {
+ const formData = await request.formData()
+ const file = formData.get('image') as File
+
+ const allowedTypes = ['image/jpeg', 'image/png', 'image/gif']
+
+ if (!allowedTypes.includes(file.type)) {
+ return HttpResponse.json(
+ { error: 'Invalid file type. Allowed: JPEG, PNG, GIF' },
+ { status: 415 }
+ )
+ }
+
+ return HttpResponse.json({ success: true, url: '/uploaded.jpg' })
+})
+```
+
+**When NOT to use this pattern:**
+- JSON-only APIs don't need FormData parsing
+
+Reference: [MSW file uploads](https://mswjs.io/docs/http/mocking-responses/file-uploads)
diff --git a/.agents/skills/msw/references/advanced-playwright-integration.md b/.agents/skills/msw/references/advanced-playwright-integration.md
new file mode 100644
index 0000000..40a9eb1
--- /dev/null
+++ b/.agents/skills/msw/references/advanced-playwright-integration.md
@@ -0,0 +1,78 @@
+---
+title: Use defineNetworkFixture from @msw/playwright
+impact: MEDIUM
+impactDescription: controls MSW network from Playwright tests without cross-process worker hacks
+tags: msw, playwright, e2e, network, fixture
+---
+
+## Use defineNetworkFixture from @msw/playwright
+
+The official [`@msw/playwright`](https://github.com/mswjs/msw/tree/master/packages/playwright) binding lets Playwright tests use the familiar `setupWorker()` API (`use`, `resetHandlers`) directly from the Node.js test process. Without it, overriding handlers requires clunky `page.evaluate(() => window.msw.worker.use(...))` bridges because the worker lives in the browser process.
+
+**Incorrect (cross-process worker references):**
+
+```typescript
+test('shows dashboard', async ({ page }) => {
+ // Requires exposing msw on window and serializing overrides
+ // across the test<->browser process boundary
+ await page.evaluate(() => {
+ const { worker, http } = window.msw
+ worker.use(http.get('/user', () => new Response('{}')))
+ })
+ await page.goto('/dashboard')
+})
+```
+
+**Correct (network fixture in the setup file):**
+
+```typescript
+// playwright.setup.ts
+import { test as testBase } from '@playwright/test'
+import { type AnyHandler } from 'msw'
+import { defineNetworkFixture, type NetworkFixture } from '@msw/playwright'
+import { handlers } from '../mocks/handlers.js'
+
+interface Fixtures {
+ handlers: Array
+ network: NetworkFixture
+}
+
+export const test = testBase.extend({
+ // Initial list of the network handlers
+ handlers: [handlers, { option: true }],
+
+ network: [
+ async ({ context, handlers }, use) => {
+ const network = defineNetworkFixture({ context, handlers })
+ await network.enable()
+ await use(network)
+ await network.disable()
+ },
+ { auto: true },
+ ],
+})
+```
+
+**Correct (override handlers from the test itself):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+import { test } from './playwright.setup.js'
+
+test('displays the user dashboard', async ({ network, page }) => {
+ network.use(
+ http.get('/user', () =>
+ HttpResponse.json({ id: 'abc-123', firstName: 'John' }),
+ ),
+ )
+
+ await page.goto('/dashboard')
+})
+```
+
+**Notes:**
+
+- Install with `npm i msw @msw/playwright`; no worker script initialization is needed — the package provisions interception through Playwright's `page.route()` until cross-process interception ships.
+- `page.route()` limitations apply (e.g., no request bodies for some redirects); treat the transport as an implementation detail.
+- WebSocket links via `ws.link()` work, but relative WebSocket URLs resolve against the most recently created page in the context.
+- For Vitest browser mode, do not use this package — use the plain browser integration with a test-context fixture instead (see [advanced-vitest-browser](advanced-vitest-browser.md)).
diff --git a/.agents/skills/msw/references/advanced-vitest-browser.md b/.agents/skills/msw/references/advanced-vitest-browser.md
new file mode 100644
index 0000000..59442a0
--- /dev/null
+++ b/.agents/skills/msw/references/advanced-vitest-browser.md
@@ -0,0 +1,100 @@
+---
+title: Configure MSW for Vitest Browser Mode
+impact: MEDIUM
+impactDescription: Enables browser-environment testing with proper worker setup
+tags: advanced, vitest, browser, worker, testing
+---
+
+## Configure MSW for Vitest Browser Mode
+
+Extend Vitest's test context to include the MSW worker when testing in browser mode. This ensures proper worker lifecycle management per test.
+
+**Incorrect (global worker without test context):**
+
+```typescript
+// Worker state leaks between tests
+import { worker } from './mocks/browser'
+
+beforeAll(() => worker.start())
+afterAll(() => worker.stop())
+
+// Tests can't override handlers safely
+```
+
+**Correct (extended test context):**
+
+```typescript
+// test-extend.ts
+import { test as testBase } from 'vitest'
+import { worker } from './mocks/browser'
+
+export const test = testBase.extend({
+ worker: [
+ async ({}, use) => {
+ // Start worker before test
+ await worker.start({
+ onUnhandledRequest: 'error',
+ })
+
+ // Provide worker to test
+ await use(worker)
+
+ // Reset handlers after test
+ worker.resetHandlers()
+ },
+ {
+ auto: true, // Automatically available to all tests
+ },
+ ],
+})
+
+export { expect } from 'vitest'
+```
+
+```typescript
+// user.test.ts
+import { http, HttpResponse } from 'msw'
+import { test, expect } from './test-extend'
+import { Dashboard } from './components/Dashboard'
+
+test('displays user data', async ({ worker }) => {
+ // Worker is automatically started
+ render( )
+ expect(await screen.findByText('John')).toBeInTheDocument()
+})
+
+test('handles error state', async ({ worker }) => {
+ // Override handlers for this test
+ worker.use(
+ http.get('/api/user', () => {
+ return new HttpResponse(null, { status: 500 })
+ })
+ )
+
+ render( )
+ expect(await screen.findByText('Error loading')).toBeInTheDocument()
+})
+```
+
+**Vitest config for browser mode:**
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+ test: {
+ browser: {
+ enabled: true,
+ name: 'chromium',
+ provider: 'playwright',
+ },
+ setupFiles: ['./vitest.setup.ts'],
+ },
+})
+```
+
+**When NOT to use this pattern:**
+- Node.js tests should use `setupServer` instead
+
+Reference: [MSW Vitest Browser Mode](https://mswjs.io/docs/recipes/vitest-browser-mode)
diff --git a/.agents/skills/msw/references/advanced-websocket-mocking.md b/.agents/skills/msw/references/advanced-websocket-mocking.md
new file mode 100644
index 0000000..322fb66
--- /dev/null
+++ b/.agents/skills/msw/references/advanced-websocket-mocking.md
@@ -0,0 +1,87 @@
+---
+title: Mock WebSocket Connections with ws.link
+impact: MEDIUM
+impactDescription: tests realtime features (chat, live feeds) without a real server
+tags: msw, websocket, ws, realtime, socket.io
+---
+
+## Mock WebSocket Connections with ws.link
+
+MSW 2.x intercepts WebSocket connections with the `ws` namespace. `ws.link(url)` creates a WebSocket link handler; its `connection` event gives you the `client` and `server` connection objects to mock a realtime session.
+
+**Incorrect (mocking WebSocket with ad-hoc stubs):**
+
+```typescript
+// Replacing the global WebSocket with a hand-rolled fake
+class FakeWebSocket {
+ send = vi.fn()
+ close = vi.fn()
+ addEventListener = vi.fn()
+}
+vi.stubGlobal('WebSocket', FakeWebSocket)
+// Breaks on every real-world protocol nuance; skips MSW's
+// handler model entirely, so no shared mock scenarios
+```
+
+**Correct (use a WebSocket link handler):**
+
+```typescript
+import { ws } from 'msw'
+
+const chat = ws.link('wss://api.example.com/chat')
+
+export const handlers = [
+ chat.addEventListener('connection', ({ client, server }) => {
+ // Greet the connected client immediately
+ client.send(JSON.stringify({ type: 'welcome' }))
+
+ // Echo incoming client messages back
+ client.addEventListener('message', (event) => {
+ client.send(JSON.stringify({ type: 'ack', data: event.data }))
+ })
+ }),
+]
+```
+
+**Forward between client and actual server:**
+
+```typescript
+chat.addEventListener('connection', ({ client, server }) => {
+ server.connect()
+
+ // Pass client messages through to the real server
+ client.addEventListener('message', (event) => {
+ server.send(event.data)
+ })
+
+ // Observe server messages without changing them
+ server.addEventListener('message', (event) => {
+ client.send(event.data)
+ })
+})
+```
+
+**Mock Socket.IO with the official binding:**
+
+```typescript
+import { ws } from 'msw'
+import { toSocketIo } from '@mswjs/socket.io-binding'
+
+const chat = ws.link('wss://chat.example.com')
+
+export const handlers = [
+ chat.addEventListener('connection', (connection) => {
+ const io = toSocketIo(connection)
+
+ io.client.on('hello', (username) => {
+ io.client.emit('message', `hello, ${username}!`)
+ })
+ }),
+]
+```
+
+**Notes:**
+
+- The connection listener arguments include `client`, `server`, `params` (path parameters from the link URL), and connection `info`.
+- Call `server.connect()` only when you want to establish the actual underlying server connection; omit it for fully mocked sessions.
+- WebSocket links go in the same `handlers` array as `http`/`graphql` handlers and work in browser, Node.js, and React Native integrations.
diff --git a/.agents/skills/msw/references/debug-common-issues.md b/.agents/skills/msw/references/debug-common-issues.md
new file mode 100644
index 0000000..56c3a2a
--- /dev/null
+++ b/.agents/skills/msw/references/debug-common-issues.md
@@ -0,0 +1,79 @@
+---
+title: Know Common MSW Issues and Fixes
+impact: LOW
+impactDescription: Quick reference for frequent problems; reduces debugging time
+tags: debug, troubleshooting, issues, fixes, reference
+---
+
+## Know Common MSW Issues and Fixes
+
+Reference this checklist when MSW behaves unexpectedly. Most issues fall into a few common categories that have well-known solutions.
+
+**Incorrect (handler not matching due to relative URL):**
+
+```typescript
+// Node.js environment - handler never matches
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Relative URL doesn't match absolute request URLs
+ http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+ }),
+]
+
+// When fetch('http://localhost:3000/api/user') is called,
+// the handler doesn't match because '/api/user' !== 'http://localhost:3000/api/user'
+```
+
+**Correct (handler matches with wildcard):**
+
+```typescript
+// Node.js environment - handler matches any origin
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Wildcard matches any origin prefix
+ http.get('*/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+ }),
+]
+
+// Now fetch('http://localhost:3000/api/user') matches correctly
+```
+
+## Common Issues Quick Reference
+
+**Issue: "fetch is not defined"**
+- Fix: Upgrade Node.js to 18+ (native fetch support)
+
+**Issue: Body parsing hangs with fake timers**
+```typescript
+// Fix: Exclude queueMicrotask from fake timers
+vi.useFakeTimers({
+ toFake: ['setTimeout', 'setInterval', 'Date'],
+ // queueMicrotask NOT faked
+})
+```
+
+**Issue: Stale responses from cache**
+```typescript
+// Fix: Clear request library cache between tests
+afterEach(() => {
+ cache.clear() // SWR
+ queryClient.clear() // TanStack Query
+})
+```
+
+**Issue: MSW v1 code in v2 project**
+```typescript
+// v2 correct syntax:
+http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+})
+```
+
+**When NOT to use this pattern:**
+- Reference only; not all issues apply to every project
+
+Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/)
diff --git a/.agents/skills/msw/references/debug-lifecycle-events.md b/.agents/skills/msw/references/debug-lifecycle-events.md
new file mode 100644
index 0000000..cb4fdee
--- /dev/null
+++ b/.agents/skills/msw/references/debug-lifecycle-events.md
@@ -0,0 +1,88 @@
+---
+title: Use Lifecycle Events for Debugging
+impact: LOW
+impactDescription: Provides visibility into request interception; aids troubleshooting
+tags: debug, lifecycle, events, logging, observability
+---
+
+## Use Lifecycle Events for Debugging
+
+Subscribe to lifecycle events to observe request interception, matching, and responses. This is invaluable for debugging why handlers aren't matching or responses aren't arriving.
+
+**Incorrect (guessing why requests fail):**
+
+```typescript
+// No visibility into what MSW is doing
+const server = setupServer(...handlers)
+server.listen()
+
+// Tests fail mysteriously - is the handler matching? Is the response correct?
+```
+
+**Correct (lifecycle event logging):**
+
+```typescript
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+const server = setupServer(...handlers)
+
+// Log all intercepted requests
+server.events.on('request:start', ({ request }) => {
+ console.log('MSW intercepted:', request.method, request.url)
+})
+
+// Log when a handler matches
+server.events.on('request:match', ({ request }) => {
+ console.log('MSW matched:', request.method, request.url)
+})
+
+// Log completed responses
+server.events.on('request:end', ({ request, response }) => {
+ console.log(
+ 'MSW responded:',
+ request.method,
+ request.url,
+ '→',
+ response.status
+ )
+})
+
+// Log unhandled requests
+server.events.on('request:unhandled', ({ request }) => {
+ console.warn('MSW unhandled:', request.method, request.url)
+})
+```
+
+**Conditional logging:**
+
+```typescript
+// Only log in debug mode
+if (process.env.DEBUG_MSW) {
+ server.events.on('request:start', ({ request }) => {
+ console.log('[MSW]', request.method, request.url)
+ })
+}
+```
+
+**Event types:**
+- `request:start` - Request intercepted by MSW
+- `request:match` - Handler found for request
+- `request:unhandled` - No handler matched
+- `request:end` - Response sent (mocked or passthrough)
+- `response:mocked` - Mocked response sent
+- `response:bypass` - Request passed through to network
+
+**Cleanup:**
+
+```typescript
+// Remove event listeners when done
+const unsubscribe = server.events.on('request:start', handler)
+unsubscribe() // Remove listener
+```
+
+**When NOT to use this pattern:**
+- Production builds should not include debug logging
+- CI environments may want minimal logging for cleaner output
+
+Reference: [MSW Lifecycle Events](https://mswjs.io/docs/api/life-cycle-events)
diff --git a/.agents/skills/msw/references/debug-request-logging.md b/.agents/skills/msw/references/debug-request-logging.md
new file mode 100644
index 0000000..87f2a2a
--- /dev/null
+++ b/.agents/skills/msw/references/debug-request-logging.md
@@ -0,0 +1,113 @@
+---
+title: Log Request Details for Debugging
+impact: LOW
+impactDescription: Provides detailed request inspection; identifies payload issues
+tags: debug, logging, request, inspection, development
+---
+
+## Log Request Details for Debugging
+
+Create a debugging middleware handler to log full request details. This helps identify issues with request payloads, headers, and authentication.
+
+**Incorrect (no request visibility):**
+
+```typescript
+// Can't see what's being sent to handlers
+http.post('/api/user', async ({ request }) => {
+ const body = await request.json()
+ // body is unexpected - but why?
+ return HttpResponse.json({ error: 'Invalid data' }, { status: 400 })
+})
+```
+
+**Correct (detailed request logging):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+// Debug middleware - add as first handler
+const debugHandler = http.all('*', async ({ request }) => {
+ const url = new URL(request.url)
+ const clone = request.clone()
+
+ console.group(`[MSW] ${request.method} ${url.pathname}`)
+ console.log('Full URL:', request.url)
+ console.log('Headers:', Object.fromEntries(request.headers.entries()))
+
+ // Log body for non-GET requests
+ if (request.method !== 'GET' && request.method !== 'HEAD') {
+ const contentType = request.headers.get('Content-Type')
+
+ if (contentType?.includes('application/json')) {
+ console.log('Body (JSON):', await clone.json())
+ } else if (contentType?.includes('multipart/form-data')) {
+ const formData = await clone.formData()
+ console.log('Body (FormData):', Object.fromEntries(formData.entries()))
+ } else {
+ console.log('Body (Text):', await clone.text())
+ }
+ }
+
+ console.groupEnd()
+
+ // Don't return - let next handler process the request
+})
+
+export const handlers = [
+ debugHandler, // Must be first
+ // ... other handlers
+]
+```
+
+**Conditional debug mode:**
+
+```typescript
+const DEBUG = process.env.DEBUG_MSW === 'true'
+
+export const handlers = [
+ ...(DEBUG ? [debugHandler] : []),
+ // ... other handlers
+]
+```
+
+**Response logging:**
+
+```typescript
+// Log responses using lifecycle events
+server.events.on('request:end', async ({ request, response }) => {
+ if (!response) return
+
+ const clone = response.clone()
+ const contentType = response.headers.get('Content-Type')
+
+ console.log(`[MSW Response] ${request.method} ${request.url}`)
+ console.log('Status:', response.status)
+
+ if (contentType?.includes('application/json')) {
+ console.log('Body:', await clone.json())
+ }
+})
+```
+
+**Development browser logging:**
+
+```typescript
+// mocks/browser.ts
+import { setupWorker } from 'msw/browser'
+import { handlers } from './handlers'
+
+export const worker = setupWorker(...handlers)
+
+// Enable detailed logging in development
+if (process.env.NODE_ENV === 'development') {
+ worker.start({
+ onUnhandledRequest: 'warn',
+ })
+}
+```
+
+**When NOT to use this pattern:**
+- Remove debug logging before committing/production
+- CI should use minimal logging for cleaner output
+
+Reference: [MSW Lifecycle Events](https://mswjs.io/docs/api/life-cycle-events)
diff --git a/.agents/skills/msw/references/debug-verify-interception.md b/.agents/skills/msw/references/debug-verify-interception.md
new file mode 100644
index 0000000..2b618c1
--- /dev/null
+++ b/.agents/skills/msw/references/debug-verify-interception.md
@@ -0,0 +1,95 @@
+---
+title: Verify Request Interception is Working
+impact: LOW
+impactDescription: Confirms MSW is active; identifies setup failures early
+tags: debug, verification, setup, troubleshooting, runbook
+---
+
+## Verify Request Interception is Working
+
+Add a verification step to confirm MSW is intercepting requests. This catches configuration issues before they cause mysterious test failures.
+
+**Incorrect (assuming MSW is working):**
+
+```typescript
+// No verification - tests fail with confusing errors
+beforeAll(() => server.listen())
+
+it('fetches user', async () => {
+ // If MSW isn't working, this hits real API or fails silently
+ const response = await fetch('/api/user')
+})
+```
+
+**Correct (verify interception):**
+
+```typescript
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+const server = setupServer(...handlers)
+
+beforeAll(() => {
+ server.listen()
+
+ // Verify MSW is intercepting
+ server.events.on('request:start', ({ request }) => {
+ console.log('✓ MSW intercepted:', request.method, request.url)
+ })
+})
+
+// Or create a verification test
+describe('MSW Setup', () => {
+ it('intercepts requests', async () => {
+ let intercepted = false
+
+ server.events.on('request:start', () => {
+ intercepted = true
+ })
+
+ await fetch('/api/health')
+
+ expect(intercepted).toBe(true)
+ })
+})
+```
+
+**Debugging checklist when handlers don't match:**
+
+```typescript
+// Step 1: Verify interception is happening
+server.events.on('request:start', ({ request }) => {
+ console.log('Intercepted URL:', request.url) // Check if URL is absolute
+ console.log('Intercepted method:', request.method)
+})
+
+// Step 2: Add console.log inside handler
+http.get('/api/user', () => {
+ console.log('Handler matched!') // If this doesn't log, handler isn't matching
+ return HttpResponse.json({ name: 'John' })
+})
+
+// Step 3: Check handler URL vs request URL
+// Common issues:
+// - Handler: '/api/user' but request goes to 'http://localhost:3000/api/user'
+// - Environment variable in URL is undefined
+// - Typo in URL path
+```
+
+**Browser verification:**
+
+```typescript
+// In browser console
+const { worker } = await import('./mocks/browser')
+await worker.start()
+
+// Check if worker script is accessible
+fetch('/mockServiceWorker.js')
+ .then((r) => r.ok ? 'Worker script found' : 'Worker script missing')
+ .then(console.log)
+```
+
+**When NOT to use this pattern:**
+- Stable test suites don't need verification in every run
+
+Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/)
diff --git a/.agents/skills/msw/references/graphql-batched-queries.md b/.agents/skills/msw/references/graphql-batched-queries.md
new file mode 100644
index 0000000..257d624
--- /dev/null
+++ b/.agents/skills/msw/references/graphql-batched-queries.md
@@ -0,0 +1,93 @@
+---
+title: Handle Batched GraphQL Queries
+impact: MEDIUM
+impactDescription: Supports Apollo batching; prevents unhandled batch requests
+tags: graphql, batching, apollo, performance, advanced
+---
+
+## Handle Batched GraphQL Queries
+
+Create a custom handler for batched GraphQL queries when using Apollo Client's batch link or similar. Batched requests send multiple operations in a single HTTP request.
+
+**Incorrect (individual handlers don't match batches):**
+
+```typescript
+// These won't match a batched request containing both queries
+graphql.query('GetUser', () => {
+ return HttpResponse.json({ data: { user: { name: 'John' } } })
+})
+
+graphql.query('GetPosts', () => {
+ return HttpResponse.json({ data: { posts: [] } })
+})
+
+// Batched request is unhandled!
+```
+
+**Correct (batch handler with individual resolution):**
+
+```typescript
+import { http, HttpResponse, getResponse, bypass } from 'msw'
+
+export function batchedGraphQLQuery(url: string, handlers: RequestHandler[]) {
+ return http.post(url, async ({ request }) => {
+ const requestClone = request.clone()
+ const payload = await request.json()
+
+ // Ignore non-batched requests
+ if (!Array.isArray(payload)) {
+ return
+ }
+
+ // Resolve each query in the batch
+ const responses = await Promise.all(
+ payload.map(async (operation) => {
+ const queryRequest = new Request(requestClone.url, {
+ method: 'POST',
+ headers: requestClone.headers,
+ body: JSON.stringify(operation),
+ })
+
+ const response = await getResponse(handlers, queryRequest)
+ return response || fetch(bypass(queryRequest))
+ })
+ )
+
+ // Combine responses into batch format
+ const results = await Promise.all(
+ responses.map((response) => response?.json())
+ )
+
+ return HttpResponse.json(results)
+ })
+}
+```
+
+```typescript
+// Usage
+import { graphql, HttpResponse } from 'msw'
+import { batchedGraphQLQuery } from './batchedGraphQLQuery'
+
+const graphqlHandlers = [
+ graphql.query('GetUser', () => {
+ return HttpResponse.json({
+ data: { user: { id: '1', name: 'John' } },
+ })
+ }),
+ graphql.query('GetPosts', () => {
+ return HttpResponse.json({
+ data: { posts: [{ id: '1', title: 'Post 1' }] },
+ })
+ }),
+]
+
+export const handlers = [
+ batchedGraphQLQuery('/graphql', graphqlHandlers),
+ ...graphqlHandlers, // Also handle non-batched requests
+]
+```
+
+**When NOT to use this pattern:**
+- Apps not using query batching don't need batch handlers
+
+Reference: [MSW GraphQL Query Batching](https://mswjs.io/docs/graphql/mocking-responses/query-batching)
diff --git a/.agents/skills/msw/references/graphql-error-responses.md b/.agents/skills/msw/references/graphql-error-responses.md
new file mode 100644
index 0000000..36f6bc2
--- /dev/null
+++ b/.agents/skills/msw/references/graphql-error-responses.md
@@ -0,0 +1,119 @@
+---
+title: Return GraphQL Errors in Correct Format
+impact: MEDIUM
+impactDescription: Ensures GraphQL clients parse errors correctly; tests error handling
+tags: graphql, errors, format, validation, response
+---
+
+## Return GraphQL Errors in Correct Format
+
+Return GraphQL errors in the standard `errors` array format. GraphQL errors are different from HTTP errors - they use status 200 with an `errors` field in the response body.
+
+**Incorrect (HTTP-style error response):**
+
+```typescript
+// GraphQL clients won't recognize this as a GraphQL error
+graphql.query('GetUser', () => {
+ return HttpResponse.json(
+ { error: 'User not found' },
+ { status: 404 }
+ )
+})
+```
+
+**Correct (GraphQL error format):**
+
+```typescript
+import { graphql, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Single error
+ graphql.query('GetUser', () => {
+ return HttpResponse.json({
+ data: null,
+ errors: [
+ {
+ message: 'User not found',
+ extensions: {
+ code: 'NOT_FOUND',
+ },
+ },
+ ],
+ })
+ }),
+
+ // Validation errors with paths
+ graphql.mutation('CreateUser', () => {
+ return HttpResponse.json({
+ data: null,
+ errors: [
+ {
+ message: 'Invalid email format',
+ path: ['createUser', 'email'],
+ extensions: {
+ code: 'VALIDATION_ERROR',
+ field: 'email',
+ },
+ },
+ {
+ message: 'Name is required',
+ path: ['createUser', 'name'],
+ extensions: {
+ code: 'VALIDATION_ERROR',
+ field: 'name',
+ },
+ },
+ ],
+ })
+ }),
+
+ // Partial success with errors
+ graphql.query('GetUsers', () => {
+ return HttpResponse.json({
+ data: {
+ users: [
+ { id: '1', name: 'John' },
+ null, // This user failed to load
+ { id: '3', name: 'Jane' },
+ ],
+ },
+ errors: [
+ {
+ message: 'Failed to load user',
+ path: ['users', 1],
+ extensions: { code: 'INTERNAL_ERROR' },
+ },
+ ],
+ })
+ }),
+
+ // Authentication error
+ graphql.query('GetPrivateData', () => {
+ return HttpResponse.json({
+ data: null,
+ errors: [
+ {
+ message: 'Not authenticated',
+ extensions: {
+ code: 'UNAUTHENTICATED',
+ },
+ },
+ ],
+ })
+ }),
+]
+```
+
+**Network-level errors (rare):**
+
+```typescript
+// For complete request failures, use HTTP error
+graphql.query('GetUser', () => {
+ return HttpResponse.error() // Network failure
+})
+```
+
+**When NOT to use this pattern:**
+- True network failures (DNS, connection) use `HttpResponse.error()`
+
+Reference: [GraphQL Spec - Errors](https://spec.graphql.org/October2021/#sec-Errors)
diff --git a/.agents/skills/msw/references/graphql-operation-handlers.md b/.agents/skills/msw/references/graphql-operation-handlers.md
new file mode 100644
index 0000000..398067e
--- /dev/null
+++ b/.agents/skills/msw/references/graphql-operation-handlers.md
@@ -0,0 +1,101 @@
+---
+title: Use Operation Name for GraphQL Matching
+impact: MEDIUM
+impactDescription: Enables precise operation targeting; prevents query/mutation conflicts
+tags: graphql, operation, query, mutation, matching
+---
+
+## Use Operation Name for GraphQL Matching
+
+Match GraphQL operations by their operation name, not by URL. All GraphQL requests typically go to the same endpoint (`/graphql`), so operation name is the discriminator.
+
+**Incorrect (URL-based matching for GraphQL):**
+
+```typescript
+// All GraphQL requests go to /graphql - this catches everything!
+http.post('/graphql', () => {
+ return HttpResponse.json({ data: { user: { name: 'John' } } })
+})
+```
+
+**Correct (operation-based matching):**
+
+```typescript
+import { graphql, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Match query by operation name
+ graphql.query('GetUser', () => {
+ return HttpResponse.json({
+ data: {
+ user: {
+ id: '1',
+ name: 'John',
+ email: 'john@example.com',
+ },
+ },
+ })
+ }),
+
+ // Match mutation by operation name
+ graphql.mutation('CreateUser', async ({ variables }) => {
+ return HttpResponse.json({
+ data: {
+ createUser: {
+ id: crypto.randomUUID(),
+ name: variables.name,
+ email: variables.email,
+ },
+ },
+ })
+ }),
+
+ // Separate handlers for different queries
+ graphql.query('GetUsers', () => {
+ return HttpResponse.json({
+ data: {
+ users: [
+ { id: '1', name: 'John' },
+ { id: '2', name: 'Jane' },
+ ],
+ },
+ })
+ }),
+]
+```
+
+**Access operation variables:**
+
+```typescript
+graphql.query('GetUser', ({ variables }) => {
+ // variables matches your GraphQL query variables
+ return HttpResponse.json({
+ data: {
+ user: {
+ id: variables.id,
+ name: 'John',
+ },
+ },
+ })
+})
+
+// Query from client:
+// query GetUser($id: ID!) { user(id: $id) { id name } }
+// variables: { id: "123" }
+```
+
+**Custom GraphQL endpoint:**
+
+```typescript
+// If your GraphQL endpoint isn't /graphql
+graphql.link('https://api.example.com/gql').query('GetUser', () => {
+ return HttpResponse.json({
+ data: { user: { name: 'John' } },
+ })
+})
+```
+
+**When NOT to use this pattern:**
+- REST APIs should use `http.*` handlers, not GraphQL handlers
+
+Reference: [MSW GraphQL API](https://mswjs.io/docs/api/graphql)
diff --git a/.agents/skills/msw/references/graphql-schema-first.md b/.agents/skills/msw/references/graphql-schema-first.md
new file mode 100644
index 0000000..2979951
--- /dev/null
+++ b/.agents/skills/msw/references/graphql-schema-first.md
@@ -0,0 +1,76 @@
+---
+title: Resolve Operations Against a GraphQL Schema
+impact: MEDIUM
+impactDescription: schema-accurate mocks without hand-writing response shapes
+tags: msw, graphql, schema, operation
+---
+
+## Resolve Operations Against a GraphQL Schema
+
+Instead of hand-writing every mocked GraphQL response, execute intercepted operations against a real schema with the `graphql` package inside a `graphql.operation()` catch-all handler. Responses stay schema-valid as operations evolve, and resolvers live in one place.
+
+**Incorrect (hand-maintained response shapes per operation):**
+
+```typescript
+// Every handler duplicates the response shape; a schema change
+// silently leaves stale mocks that no longer match production
+export const handlers = [
+ graphql.query('GetUser', () =>
+ HttpResponse.json({ data: { user: { id: '1', firstName: 'John' } } }),
+ ),
+ graphql.query('GetUserWithPosts', () =>
+ HttpResponse.json({
+ data: { user: { id: '1', firstName: 'John', posts: [] } },
+ }),
+ ),
+]
+```
+
+**Correct (schema-first resolution):**
+
+```typescript
+import { graphql, HttpResponse } from 'msw'
+import { graphql as executeGraphql, buildSchema } from 'graphql'
+
+const schema = buildSchema(`
+ type User {
+ id: ID!
+ firstName: String!
+ }
+
+ type Query {
+ user(id: ID!): User
+ }
+`)
+
+const data = {
+ users: [
+ { id: '1', name: 'John' },
+ { id: '2', name: 'Kate' },
+ ],
+}
+
+export const handlers = [
+ graphql.operation(async ({ query, variables }) => {
+ const { data, errors } = await executeGraphql({
+ schema,
+ source: query,
+ variableValues: variables,
+ rootValue: {
+ user(args) {
+ return data.users.find((user) => user.id === args.id)
+ },
+ },
+ })
+
+ return HttpResponse.json({ data, errors })
+ }),
+]
+```
+
+**Notes:**
+
+- `graphql.operation()` matches every operation; place more specific named-operation handlers above it when you need per-test overrides.
+- The `graphql` package (`buildSchema`, `graphql()`) is a peer dependency you install alongside MSW.
+- Because resolution runs against the schema, invalid client queries surface real GraphQL `errors` in the mocked response — useful for testing error UI.
+- Pair with [graphql-operation-handlers](graphql-operation-handlers.md) for targeted overrides and [graphql-error-responses](graphql-error-responses.md) for error-shape rules.
diff --git a/.agents/skills/msw/references/graphql-variables-access.md b/.agents/skills/msw/references/graphql-variables-access.md
new file mode 100644
index 0000000..9853b9b
--- /dev/null
+++ b/.agents/skills/msw/references/graphql-variables-access.md
@@ -0,0 +1,123 @@
+---
+title: Access GraphQL Variables Correctly
+impact: MEDIUM
+impactDescription: Enables dynamic mock responses based on query input
+tags: graphql, variables, dynamic, input, resolver
+---
+
+## Access GraphQL Variables Correctly
+
+Access GraphQL variables through the `variables` property in the resolver argument. Use them to return dynamic responses based on query input.
+
+**Incorrect (ignoring variables):**
+
+```typescript
+// Returns same user regardless of which ID is requested
+graphql.query('GetUser', () => {
+ return HttpResponse.json({
+ data: {
+ user: { id: '1', name: 'John' },
+ },
+ })
+})
+```
+
+**Correct (using variables for dynamic responses):**
+
+```typescript
+import { graphql, HttpResponse } from 'msw'
+
+// Mock data store
+const users = new Map([
+ ['1', { id: '1', name: 'John', email: 'john@example.com' }],
+ ['2', { id: '2', name: 'Jane', email: 'jane@example.com' }],
+])
+
+export const handlers = [
+ graphql.query('GetUser', ({ variables }) => {
+ const user = users.get(variables.id)
+
+ if (!user) {
+ return HttpResponse.json({
+ data: null,
+ errors: [{ message: 'User not found' }],
+ })
+ }
+
+ return HttpResponse.json({
+ data: { user },
+ })
+ }),
+
+ // Mutation with input variables
+ graphql.mutation('UpdateUser', ({ variables }) => {
+ const { id, input } = variables
+ const existingUser = users.get(id)
+
+ if (!existingUser) {
+ return HttpResponse.json({
+ data: null,
+ errors: [{ message: 'User not found' }],
+ })
+ }
+
+ const updatedUser = { ...existingUser, ...input }
+ users.set(id, updatedUser)
+
+ return HttpResponse.json({
+ data: { updateUser: updatedUser },
+ })
+ }),
+
+ // Pagination with variables
+ graphql.query('GetUsers', ({ variables }) => {
+ const { first = 10, after } = variables
+ const allUsers = Array.from(users.values())
+
+ let startIndex = 0
+ if (after) {
+ startIndex = allUsers.findIndex((u) => u.id === after) + 1
+ }
+
+ const pageUsers = allUsers.slice(startIndex, startIndex + first)
+ const hasNextPage = startIndex + first < allUsers.length
+
+ return HttpResponse.json({
+ data: {
+ users: {
+ edges: pageUsers.map((user) => ({
+ node: user,
+ cursor: user.id,
+ })),
+ pageInfo: {
+ hasNextPage,
+ endCursor: pageUsers[pageUsers.length - 1]?.id,
+ },
+ },
+ },
+ })
+ }),
+]
+```
+
+**Type-safe variables:**
+
+```typescript
+type GetUserVariables = {
+ id: string
+}
+
+graphql.query('GetUser', ({ variables }) => {
+ // variables.id is typed as string
+ return HttpResponse.json({
+ data: {
+ user: { id: variables.id, name: 'John' },
+ },
+ })
+})
+```
+
+**When NOT to use this pattern:**
+- Queries without variables don't need variable access
+
+Reference: [MSW GraphQL Intercepting Operations](https://mswjs.io/docs/graphql/intercepting-operations)
diff --git a/.agents/skills/msw/references/handler-absolute-urls.md b/.agents/skills/msw/references/handler-absolute-urls.md
new file mode 100644
index 0000000..5f6b8fd
--- /dev/null
+++ b/.agents/skills/msw/references/handler-absolute-urls.md
@@ -0,0 +1,70 @@
+---
+title: Use Absolute URLs in Handlers
+impact: CRITICAL
+impactDescription: Prevents URL mismatch failures; required for Node.js environments
+tags: handler, url, absolute, node, matching
+---
+
+## Use Absolute URLs in Handlers
+
+Use absolute URLs or URL patterns in request handlers. Node.js environments require absolute URLs for proper matching, and relative URLs cause silent handler failures.
+
+**Incorrect (relative URLs in Node.js context):**
+
+```typescript
+// mocks/handlers.ts
+export const handlers = [
+ // Relative URL - may not match in Node.js tests
+ http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+ }),
+]
+
+// Test makes request to full URL
+await fetch('http://localhost:3000/api/user')
+// Handler doesn't match - request goes unhandled
+```
+
+**Correct (absolute URLs or wildcards):**
+
+```typescript
+// mocks/handlers.ts
+export const handlers = [
+ // Absolute URL - matches reliably
+ http.get('http://localhost:3000/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+ }),
+]
+```
+
+**Better (wildcard for any origin):**
+
+```typescript
+// mocks/handlers.ts
+export const handlers = [
+ // Wildcard matches any origin - most flexible
+ http.get('*/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+ }),
+
+ // Or use path patterns that MSW resolves against baseURL
+ http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+ }),
+]
+```
+
+**Environment variable pitfall:**
+
+```typescript
+// AVOID: Environment variable not set in tests
+const API_URL = process.env.API_URL // undefined in tests!
+
+http.get(`${API_URL}/user`, () => { /* ... */ })
+// Results in: http.get('undefined/user', ...) - never matches
+```
+
+**When NOT to use this pattern:**
+- Browser environments with properly configured base URLs may use relative paths
+
+Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/)
diff --git a/.agents/skills/msw/references/handler-domain-grouping.md b/.agents/skills/msw/references/handler-domain-grouping.md
new file mode 100644
index 0000000..0302e5d
--- /dev/null
+++ b/.agents/skills/msw/references/handler-domain-grouping.md
@@ -0,0 +1,81 @@
+---
+title: Group Handlers by Domain
+impact: CRITICAL
+impactDescription: Reduces maintenance overhead; scales to large APIs without N×M complexity
+tags: handler, organization, domain, modules, scalability
+---
+
+## Group Handlers by Domain
+
+Split handlers into separate files organized by domain or feature area. This prevents a single handlers file from becoming unmanageable and enables selective handler composition for different test scenarios.
+
+**Incorrect (monolithic handler file):**
+
+```typescript
+// mocks/handlers.ts - 500+ lines, unmaintainable
+export const handlers = [
+ // User endpoints
+ http.get('/api/user', () => { /* ... */ }),
+ http.post('/api/user', () => { /* ... */ }),
+ http.delete('/api/user/:id', () => { /* ... */ }),
+ // Auth endpoints
+ http.post('/api/login', () => { /* ... */ }),
+ http.post('/api/logout', () => { /* ... */ }),
+ // Product endpoints
+ http.get('/api/products', () => { /* ... */ }),
+ // ... 50 more endpoints mixed together
+]
+```
+
+**Correct (domain-organized handlers):**
+
+```typescript
+// mocks/handlers/user.ts
+import { http, HttpResponse } from 'msw'
+
+export const userHandlers = [
+ http.get('/api/user', () => {
+ return HttpResponse.json({ id: '1', name: 'John' })
+ }),
+ http.post('/api/user', async ({ request }) => {
+ const user = await request.json()
+ return HttpResponse.json(user, { status: 201 })
+ }),
+ http.delete('/api/user/:id', ({ params }) => {
+ return new HttpResponse(null, { status: 204 })
+ }),
+]
+```
+
+```typescript
+// mocks/handlers/auth.ts
+import { http, HttpResponse } from 'msw'
+
+export const authHandlers = [
+ http.post('/api/login', async ({ request }) => {
+ const { email, password } = await request.json()
+ return HttpResponse.json({ token: 'jwt-token' })
+ }),
+ http.post('/api/logout', () => {
+ return new HttpResponse(null, { status: 200 })
+ }),
+]
+```
+
+```typescript
+// mocks/handlers/index.ts - compose all handlers
+import { userHandlers } from './user'
+import { authHandlers } from './auth'
+import { productHandlers } from './products'
+
+export const handlers = [
+ ...userHandlers,
+ ...authHandlers,
+ ...productHandlers,
+]
+```
+
+**When NOT to use this pattern:**
+- Small projects with fewer than 10 endpoints may use a single file
+
+Reference: [Structuring Handlers - Group by Domain](https://mswjs.io/docs/best-practices/structuring-handlers)
diff --git a/.agents/skills/msw/references/handler-happy-path-first.md b/.agents/skills/msw/references/handler-happy-path-first.md
new file mode 100644
index 0000000..f214391
--- /dev/null
+++ b/.agents/skills/msw/references/handler-happy-path-first.md
@@ -0,0 +1,60 @@
+---
+title: Define Happy Path Handlers as Baseline
+impact: CRITICAL
+impactDescription: Establishes reliable baseline; enables clean runtime overrides
+tags: handler, structure, happy-path, baseline, organization
+---
+
+## Define Happy Path Handlers as Baseline
+
+Define success-state handlers in a central `handlers.ts` file as your baseline. This establishes a reliable foundation that runtime overrides can modify for error scenarios, keeping test-specific edge cases separate from normal behavior.
+
+**Incorrect (mixing success and error states):**
+
+```typescript
+// mocks/handlers.ts - cluttered with all scenarios
+export const handlers = [
+ http.get('/user', () => HttpResponse.json({ name: 'John' })),
+ http.get('/user', () => new HttpResponse(null, { status: 401 })),
+ http.get('/user', () => new HttpResponse(null, { status: 500 })),
+ http.get('/user', () => HttpResponse.error()),
+ // Confusing: which handler runs? Last one wins but intent unclear
+]
+```
+
+**Correct (happy path baseline with runtime overrides):**
+
+```typescript
+// mocks/handlers.ts - clean success states only
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ http.get('/api/user', () => {
+ return HttpResponse.json({ id: '1', name: 'John Maverick' })
+ }),
+ http.post('/api/login', async ({ request }) => {
+ const { email } = await request.json()
+ return HttpResponse.json({ token: 'mock-jwt-token', email })
+ }),
+]
+```
+
+```typescript
+// user.test.ts - override for specific scenarios
+import { http, HttpResponse } from 'msw'
+import { server } from '../mocks/node'
+
+it('handles authentication error', () => {
+ server.use(
+ http.get('/api/user', () => {
+ return new HttpResponse(null, { status: 401 })
+ })
+ )
+ // Test error handling...
+})
+```
+
+**When NOT to use this pattern:**
+- Single-use test utilities that will never need runtime overrides
+
+Reference: [Structuring Handlers](https://mswjs.io/docs/best-practices/structuring-handlers)
diff --git a/.agents/skills/msw/references/handler-request-body-parsing.md b/.agents/skills/msw/references/handler-request-body-parsing.md
new file mode 100644
index 0000000..25f3235
--- /dev/null
+++ b/.agents/skills/msw/references/handler-request-body-parsing.md
@@ -0,0 +1,76 @@
+---
+title: Explicitly Parse Request Bodies
+impact: CRITICAL
+impactDescription: v2 no longer auto-parses bodies; missing parsing returns undefined
+tags: handler, request, body, parsing, json
+---
+
+## Explicitly Parse Request Bodies
+
+MSW v2 does not automatically parse request bodies based on Content-Type. You must explicitly call `.json()`, `.text()`, `.formData()`, or `.arrayBuffer()` on the request object.
+
+**Incorrect (assuming auto-parsed body):**
+
+```typescript
+// MSW v1 pattern - body was auto-parsed
+http.post('/api/user', ({ request }) => {
+ const body = request.body // a ReadableStream in v2, not parsed data
+ return HttpResponse.json({ id: '1', ...body })
+})
+```
+
+**Correct (explicit body parsing):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // JSON body
+ http.post('/api/user', async ({ request }) => {
+ const body = await request.json()
+ return HttpResponse.json({ id: '1', ...body }, { status: 201 })
+ }),
+
+ // Text body
+ http.post('/api/text', async ({ request }) => {
+ const text = await request.text()
+ return HttpResponse.text(`Received: ${text}`)
+ }),
+
+ // Form data
+ http.post('/api/upload', async ({ request }) => {
+ const formData = await request.formData()
+ const file = formData.get('file')
+ return HttpResponse.json({ filename: file?.name })
+ }),
+
+ // ArrayBuffer for binary
+ http.post('/api/binary', async ({ request }) => {
+ const buffer = await request.arrayBuffer()
+ return HttpResponse.json({ bytes: buffer.byteLength })
+ }),
+]
+```
+
+**Typed body parsing:**
+
+```typescript
+interface CreateUserRequest {
+ name: string
+ email: string
+}
+
+http.post('/api/user', async ({ request }) => {
+ const body = await request.json() as CreateUserRequest
+ return HttpResponse.json({
+ id: crypto.randomUUID(),
+ name: body.name,
+ email: body.email,
+ })
+})
+```
+
+**When NOT to use this pattern:**
+- GET requests typically don't have bodies and don't need parsing
+
+Reference: [MSW v2 Migration - Request Changes](https://mswjs.io/docs/migrations/1.x-to-2.x/)
diff --git a/.agents/skills/msw/references/handler-resolver-argument.md b/.agents/skills/msw/references/handler-resolver-argument.md
new file mode 100644
index 0000000..9794299
--- /dev/null
+++ b/.agents/skills/msw/references/handler-resolver-argument.md
@@ -0,0 +1,86 @@
+---
+title: Destructure Resolver Arguments Correctly
+impact: CRITICAL
+impactDescription: Wrong destructuring pattern causes undefined values; silent failures
+tags: handler, resolver, params, cookies, request, destructuring
+---
+
+## Destructure Resolver Arguments Correctly
+
+MSW v2 passes a single object argument to resolvers containing `request`, `params`, `cookies`, and other properties. Destructure from this object instead of using multiple arguments.
+
+**Incorrect (v1 multiple arguments pattern):**
+
+```typescript
+// MSW v1 pattern - does not work in v2
+http.get('/api/user/:id', (req, res, ctx) => {
+ const userId = req.params.id // undefined!
+ return res(ctx.json({ id: userId }))
+})
+```
+
+**Correct (v2 single object argument):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Destructure from single argument object
+ http.get('/api/user/:id', ({ request, params, cookies }) => {
+ return HttpResponse.json({
+ id: params.id,
+ sessionId: cookies.sessionId,
+ userAgent: request.headers.get('User-Agent'),
+ })
+ }),
+]
+```
+
+**Available resolver properties:**
+
+```typescript
+http.post('/api/data', async (info) => {
+ // Full request object
+ const { request } = info
+
+ // URL path parameters
+ const { params } = info // { id: '123' } for /api/data/:id
+
+ // Parsed cookies from Cookie header
+ const { cookies } = info // { session: 'abc', token: 'xyz' }
+
+ // Request URL as string (not URL object)
+ const url = new URL(request.url)
+
+ // Request method
+ const method = request.method
+
+ // Request headers
+ const authHeader = request.headers.get('Authorization')
+
+ // Request body (must await)
+ const body = await request.json()
+
+ return HttpResponse.json({ success: true })
+})
+```
+
+**Type-safe params:**
+
+```typescript
+// Define params type for better type safety
+type UserParams = {
+ id: string
+ orgId: string
+}
+
+http.get('/api/org/:orgId/user/:id', ({ params }) => {
+ // params.id and params.orgId are typed as string
+ return HttpResponse.json({ userId: params.id, orgId: params.orgId })
+})
+```
+
+**When NOT to use this pattern:**
+- This is the only pattern in MSW v2; no alternatives
+
+Reference: [MSW v2 Migration - Resolver Changes](https://mswjs.io/docs/migrations/1.x-to-2.x/)
diff --git a/.agents/skills/msw/references/handler-reusability-environments.md b/.agents/skills/msw/references/handler-reusability-environments.md
new file mode 100644
index 0000000..17db61e
--- /dev/null
+++ b/.agents/skills/msw/references/handler-reusability-environments.md
@@ -0,0 +1,80 @@
+---
+title: Share Handlers Across Environments
+impact: CRITICAL
+impactDescription: Single source of truth; eliminates mock drift between dev/test
+tags: handler, reuse, environment, browser, node, integration
+---
+
+## Share Handlers Across Environments
+
+Define handlers once and reuse them across browser (development) and Node.js (testing) environments. This ensures mock behavior is consistent and prevents drift between development and test mocks.
+
+**Incorrect (duplicate handlers per environment):**
+
+```typescript
+// mocks/browser-handlers.ts - browser development
+export const browserHandlers = [
+ http.get('/api/user', () => HttpResponse.json({ name: 'Dev User' })),
+]
+
+// mocks/test-handlers.ts - tests (different implementation!)
+export const testHandlers = [
+ http.get('/api/user', () => HttpResponse.json({ name: 'Test User' })),
+]
+// Mock behavior differs between environments - bugs hide until production
+```
+
+**Correct (shared handlers, environment-specific setup):**
+
+```typescript
+// mocks/handlers.ts - single source of truth
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ http.get('/api/user', () => {
+ return HttpResponse.json({ id: '1', name: 'John Maverick' })
+ }),
+ http.get('/api/posts', () => {
+ return HttpResponse.json([
+ { id: '1', title: 'First Post' },
+ { id: '2', title: 'Second Post' },
+ ])
+ }),
+]
+```
+
+```typescript
+// mocks/browser.ts - browser setup
+import { setupWorker } from 'msw/browser'
+import { handlers } from './handlers'
+
+export const worker = setupWorker(...handlers)
+```
+
+```typescript
+// mocks/node.ts - Node.js setup
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)
+```
+
+```typescript
+// src/index.tsx - conditional browser activation
+async function enableMocking() {
+ if (process.env.NODE_ENV !== 'development') {
+ return
+ }
+ const { worker } = await import('./mocks/browser')
+ return worker.start()
+}
+
+enableMocking().then(() => {
+ ReactDOM.createRoot(document.getElementById('root')!).render( )
+})
+```
+
+**When NOT to use this pattern:**
+- Environment-specific handlers (e.g., browser-only features) can be added via separate arrays
+
+Reference: [MSW Comparison - Reusability](https://mswjs.io/docs/comparison)
diff --git a/.agents/skills/msw/references/handler-shared-resolvers.md b/.agents/skills/msw/references/handler-shared-resolvers.md
new file mode 100644
index 0000000..80bccb6
--- /dev/null
+++ b/.agents/skills/msw/references/handler-shared-resolvers.md
@@ -0,0 +1,99 @@
+---
+title: Extract Shared Response Logic into Resolvers
+impact: CRITICAL
+impactDescription: Eliminates duplication; ensures consistent mock responses across tests
+tags: handler, resolver, reuse, abstraction, dry
+---
+
+## Extract Shared Response Logic into Resolvers
+
+Extract repetitive response logic into reusable resolver functions. This ensures consistency across handlers and reduces maintenance when response shapes change.
+
+**Incorrect (duplicated response logic):**
+
+```typescript
+// mocks/handlers.ts
+export const handlers = [
+ http.get('/api/user/:id', ({ params }) => {
+ return HttpResponse.json({
+ id: params.id,
+ name: 'John',
+ email: 'john@example.com',
+ createdAt: new Date().toISOString(),
+ updatedAt: new Date().toISOString(),
+ })
+ }),
+ http.get('/api/users', () => {
+ return HttpResponse.json([
+ {
+ id: '1',
+ name: 'John',
+ email: 'john@example.com',
+ createdAt: new Date().toISOString(), // Duplicated shape
+ updatedAt: new Date().toISOString(),
+ },
+ // ... more users with same structure
+ ])
+ }),
+]
+```
+
+**Correct (shared resolver factories):**
+
+```typescript
+// mocks/factories/user.ts
+import { faker } from '@faker-js/faker'
+
+export function createMockUser(overrides: Partial = {}): User {
+ return {
+ id: faker.string.uuid(),
+ name: faker.person.fullName(),
+ email: faker.internet.email(),
+ createdAt: faker.date.past().toISOString(),
+ updatedAt: faker.date.recent().toISOString(),
+ ...overrides,
+ }
+}
+```
+
+```typescript
+// mocks/handlers/user.ts
+import { http, HttpResponse } from 'msw'
+import { createMockUser } from '../factories/user'
+
+export const userHandlers = [
+ http.get('/api/user/:id', ({ params }) => {
+ return HttpResponse.json(createMockUser({ id: params.id as string }))
+ }),
+ http.get('/api/users', () => {
+ return HttpResponse.json([
+ createMockUser(),
+ createMockUser(),
+ createMockUser(),
+ ])
+ }),
+]
+```
+
+**Higher-order handler for cross-cutting concerns:**
+
+```typescript
+// mocks/utils/withAuth.ts
+import { HttpResponse } from 'msw'
+import type { HttpResponseResolver } from 'msw'
+
+export function withAuth(resolver: HttpResponseResolver): HttpResponseResolver {
+ return ({ request, ...rest }) => {
+ const authHeader = request.headers.get('Authorization')
+ if (!authHeader?.startsWith('Bearer ')) {
+ return new HttpResponse(null, { status: 401 })
+ }
+ return resolver({ request, ...rest })
+ }
+}
+```
+
+**When NOT to use this pattern:**
+- One-off handlers for specific test scenarios don't need abstraction
+
+Reference: [Structuring Handlers](https://mswjs.io/docs/best-practices/structuring-handlers)
diff --git a/.agents/skills/msw/references/handler-v2-response-syntax.md b/.agents/skills/msw/references/handler-v2-response-syntax.md
new file mode 100644
index 0000000..bc5d190
--- /dev/null
+++ b/.agents/skills/msw/references/handler-v2-response-syntax.md
@@ -0,0 +1,94 @@
+---
+title: Use MSW v2 Response Syntax
+impact: CRITICAL
+impactDescription: v1 syntax breaks in v2; causes complete handler failure
+tags: handler, response, v2, HttpResponse, migration
+---
+
+## Use MSW v2 Response Syntax
+
+MSW v2 replaces the composition-based `res(ctx.json())` syntax with native `Response` and `HttpResponse`. Using v1 syntax in v2 causes handlers to fail silently.
+
+**Incorrect (v1 composition syntax):**
+
+```typescript
+// MSW v1 syntax - does not work in v2
+import { rest } from 'msw'
+
+export const handlers = [
+ rest.get('/api/user', (req, res, ctx) => {
+ return res(
+ ctx.status(200),
+ ctx.json({ name: 'John' }),
+ ctx.delay(100)
+ )
+ }),
+]
+```
+
+**Correct (v2 HttpResponse syntax):**
+
+```typescript
+// MSW v2 syntax
+import { http, HttpResponse, delay } from 'msw'
+
+export const handlers = [
+ http.get('/api/user', async () => {
+ await delay(100)
+ return HttpResponse.json(
+ { name: 'John' },
+ { status: 200 }
+ )
+ }),
+]
+```
+
+**Common v2 response patterns:**
+
+```typescript
+import { http, HttpResponse, delay } from 'msw'
+
+export const handlers = [
+ // JSON response
+ http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+ }),
+
+ // Text response
+ http.get('/api/text', () => {
+ return HttpResponse.text('Hello, World!')
+ }),
+
+ // XML response
+ http.get('/api/xml', () => {
+ return HttpResponse.xml('John ')
+ }),
+
+ // Empty response with status
+ http.delete('/api/user/:id', () => {
+ return new HttpResponse(null, { status: 204 })
+ }),
+
+ // Custom headers
+ http.get('/api/data', () => {
+ return HttpResponse.json(
+ { data: 'value' },
+ {
+ headers: {
+ 'X-Custom-Header': 'custom-value',
+ },
+ }
+ )
+ }),
+
+ // Network error
+ http.get('/api/error', () => {
+ return HttpResponse.error()
+ }),
+]
+```
+
+**When NOT to use this pattern:**
+- Projects still on MSW v1 should use the v1 syntax until migration
+
+Reference: [MSW v2 Migration Guide](https://mswjs.io/docs/migrations/1.x-to-2.x/)
diff --git a/.agents/skills/msw/references/match-custom-predicate.md b/.agents/skills/msw/references/match-custom-predicate.md
new file mode 100644
index 0000000..f537d4c
--- /dev/null
+++ b/.agents/skills/msw/references/match-custom-predicate.md
@@ -0,0 +1,99 @@
+---
+title: Use Custom Predicates for Complex Matching
+impact: MEDIUM-HIGH
+impactDescription: Enables header-based, body-based, and conditional request matching
+tags: match, predicate, custom, conditional, advanced
+---
+
+## Use Custom Predicates for Complex Matching
+
+Use a predicate function instead of a URL string for complex matching logic. This enables matching based on headers, request body, cookies, or any combination of request properties.
+
+**Incorrect (multiple handlers for same URL):**
+
+```typescript
+// Awkward - two handlers for same URL with different behavior
+http.get('/api/data', () => {
+ return HttpResponse.json({ public: true })
+})
+
+// How to handle authenticated vs unauthenticated?
+```
+
+**Correct (predicate-based matching):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Match based on header presence
+ http.get('/api/data', ({ request }) => {
+ const authHeader = request.headers.get('Authorization')
+
+ if (authHeader?.startsWith('Bearer ')) {
+ return HttpResponse.json({ data: 'authenticated content' })
+ }
+
+ return HttpResponse.json(
+ { error: 'Unauthorized' },
+ { status: 401 }
+ )
+ }),
+]
+```
+
+**Predicate function syntax:**
+
+```typescript
+// Match by custom criteria
+http.all(
+ ({ request }) => {
+ // Return true to match this request
+ return request.url.includes('/api/') &&
+ request.headers.get('X-Custom-Header') === 'special'
+ },
+ () => {
+ return HttpResponse.json({ matched: true })
+ }
+)
+```
+
+**Match by request body content:**
+
+```typescript
+http.post(
+ '/api/action',
+ async ({ request }) => {
+ const body = await request.clone().json()
+
+ // Different response based on action type
+ if (body.action === 'create') {
+ return HttpResponse.json({ id: '1', created: true })
+ }
+ if (body.action === 'delete') {
+ return new HttpResponse(null, { status: 204 })
+ }
+
+ return HttpResponse.json(
+ { error: 'Unknown action' },
+ { status: 400 }
+ )
+ }
+)
+```
+
+**Match by cookie value:**
+
+```typescript
+http.get('/api/user', ({ cookies }) => {
+ if (cookies.role === 'admin') {
+ return HttpResponse.json({ permissions: ['read', 'write', 'delete'] })
+ }
+ return HttpResponse.json({ permissions: ['read'] })
+})
+```
+
+**When NOT to use this pattern:**
+- Simple URL-based matching is clearer when sufficient
+
+Reference: [MSW Custom Request Predicate](https://mswjs.io/docs/best-practices/custom-request-predicate)
diff --git a/.agents/skills/msw/references/match-handler-order.md b/.agents/skills/msw/references/match-handler-order.md
new file mode 100644
index 0000000..6f7b804
--- /dev/null
+++ b/.agents/skills/msw/references/match-handler-order.md
@@ -0,0 +1,93 @@
+---
+title: Order Handlers from Specific to General
+impact: MEDIUM-HIGH
+impactDescription: Prevents general handlers from shadowing specific ones
+tags: match, order, priority, specific, general
+---
+
+## Order Handlers from Specific to General
+
+Place more specific handlers before general ones in the handlers array. MSW matches handlers in order, and the first match wins. A wildcard handler placed first will shadow all subsequent handlers.
+
+**Incorrect (general handler shadows specific):**
+
+```typescript
+export const handlers = [
+ // Wildcard matches first - specific handlers never reached!
+ http.get('/api/*', () => {
+ return HttpResponse.json({ fallback: true })
+ }),
+
+ // Never matches because /api/* already caught it
+ http.get('/api/user/:id', ({ params }) => {
+ return HttpResponse.json({ id: params.id, name: 'John' })
+ }),
+]
+```
+
+**Correct (specific before general):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Most specific handlers first
+ http.get('/api/user/:id/settings', ({ params }) => {
+ return HttpResponse.json({ userId: params.id, theme: 'dark' })
+ }),
+
+ http.get('/api/user/:id', ({ params }) => {
+ return HttpResponse.json({ id: params.id, name: 'John' })
+ }),
+
+ http.get('/api/users', () => {
+ return HttpResponse.json([{ id: '1' }, { id: '2' }])
+ }),
+
+ // General fallback last
+ http.get('/api/*', () => {
+ return HttpResponse.json(
+ { error: 'Not found' },
+ { status: 404 }
+ )
+ }),
+]
+```
+
+**Middleware with passthrough:**
+
+```typescript
+export const handlers = [
+ // Middleware runs first but doesn't return - passes through
+ http.all('*', async () => {
+ await delay(50) // Add delay to all requests
+ // No return = continue to next handler
+ }),
+
+ // Specific handlers still match
+ http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+ }),
+]
+```
+
+**Runtime handler precedence:**
+
+```typescript
+// Initial handlers
+const server = setupServer(
+ http.get('/api/user', () => HttpResponse.json({ name: 'John' }))
+)
+
+// Runtime handlers are PREPENDED (take precedence)
+server.use(
+ http.get('/api/user', () => HttpResponse.json({ name: 'Jane' }))
+)
+
+// Request to /api/user returns { name: 'Jane' }
+```
+
+**When NOT to use this pattern:**
+- Single handlers don't have ordering concerns
+
+Reference: [MSW Handler Precedence](https://mswjs.io/docs/concepts/request-handler)
diff --git a/.agents/skills/msw/references/match-http-methods.md b/.agents/skills/msw/references/match-http-methods.md
new file mode 100644
index 0000000..04d7f6d
--- /dev/null
+++ b/.agents/skills/msw/references/match-http-methods.md
@@ -0,0 +1,98 @@
+---
+title: Match HTTP Methods Explicitly
+impact: MEDIUM-HIGH
+impactDescription: Prevents cross-method interference; models REST APIs correctly
+tags: match, methods, http, get, post, put, delete
+---
+
+## Match HTTP Methods Explicitly
+
+Use method-specific handlers (`http.get`, `http.post`, etc.) instead of `http.all`. This prevents a GET handler from accidentally matching POST requests and ensures correct REST API simulation.
+
+**Incorrect (catching unintended methods):**
+
+```typescript
+// Matches ALL methods - GET, POST, PUT, DELETE, etc.
+http.all('/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+})
+
+// POST /api/user also returns user JSON instead of creating
+```
+
+**Correct (method-specific handlers):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // GET - retrieve resource
+ http.get('/api/user/:id', ({ params }) => {
+ return HttpResponse.json({ id: params.id, name: 'John' })
+ }),
+
+ // POST - create resource
+ http.post('/api/user', async ({ request }) => {
+ const body = await request.json()
+ return HttpResponse.json(
+ { id: crypto.randomUUID(), ...body },
+ { status: 201 }
+ )
+ }),
+
+ // PUT - replace resource
+ http.put('/api/user/:id', async ({ params, request }) => {
+ const body = await request.json()
+ return HttpResponse.json({ id: params.id, ...body })
+ }),
+
+ // PATCH - partial update
+ http.patch('/api/user/:id', async ({ params, request }) => {
+ const updates = await request.json()
+ return HttpResponse.json({ id: params.id, name: 'John', ...updates })
+ }),
+
+ // DELETE - remove resource
+ http.delete('/api/user/:id', () => {
+ return new HttpResponse(null, { status: 204 })
+ }),
+
+ // HEAD - metadata only
+ http.head('/api/user/:id', () => {
+ return new HttpResponse(null, {
+ headers: { 'X-User-Exists': 'true' },
+ })
+ }),
+
+ // OPTIONS - CORS preflight
+ http.options('/api/*', () => {
+ return new HttpResponse(null, {
+ headers: {
+ 'Access-Control-Allow-Origin': '*',
+ 'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE',
+ },
+ })
+ }),
+]
+```
+
+**When to use http.all:**
+
+```typescript
+// Global middleware (logging, delay)
+http.all('*', async () => {
+ await delay(50)
+ // No return - continues to next handler
+})
+
+// Catch-all fallback for testing
+http.all('/api/*', () => {
+ console.warn('Unhandled API request')
+ return new HttpResponse(null, { status: 404 })
+})
+```
+
+**When NOT to use this pattern:**
+- Middleware handlers that should apply to all methods can use `http.all`
+
+Reference: [MSW HTTP Handlers](https://mswjs.io/docs/api/http)
diff --git a/.agents/skills/msw/references/match-query-params.md b/.agents/skills/msw/references/match-query-params.md
new file mode 100644
index 0000000..8e9bb12
--- /dev/null
+++ b/.agents/skills/msw/references/match-query-params.md
@@ -0,0 +1,89 @@
+---
+title: Access Query Parameters from Request URL
+impact: MEDIUM-HIGH
+impactDescription: Enables filtering, pagination, and search mocking
+tags: match, query, search-params, url, filtering
+---
+
+## Access Query Parameters from Request URL
+
+Parse query parameters from `request.url` using the `URL` constructor. MSW does not automatically parse query strings, so you must extract them manually.
+
+**Incorrect (assuming params includes query string):**
+
+```typescript
+http.get('/api/users', ({ params }) => {
+ // params does NOT contain query parameters!
+ const page = params.page // undefined
+ return HttpResponse.json([])
+})
+```
+
+**Correct (parse from request.url):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ http.get('/api/users', ({ request }) => {
+ const url = new URL(request.url)
+ const page = url.searchParams.get('page') || '1'
+ const limit = url.searchParams.get('limit') || '10'
+ const search = url.searchParams.get('search')
+
+ // Mock paginated response
+ const pageNum = parseInt(page, 10)
+ const limitNum = parseInt(limit, 10)
+
+ return HttpResponse.json({
+ data: mockUsers.slice((pageNum - 1) * limitNum, pageNum * limitNum),
+ meta: {
+ page: pageNum,
+ limit: limitNum,
+ total: mockUsers.length,
+ },
+ })
+ }),
+
+ // Filtering by query params
+ http.get('/api/products', ({ request }) => {
+ const url = new URL(request.url)
+ const category = url.searchParams.get('category')
+ const minPrice = url.searchParams.get('minPrice')
+ const maxPrice = url.searchParams.get('maxPrice')
+
+ let products = [...mockProducts]
+
+ if (category) {
+ products = products.filter((p) => p.category === category)
+ }
+ if (minPrice) {
+ products = products.filter((p) => p.price >= Number(minPrice))
+ }
+ if (maxPrice) {
+ products = products.filter((p) => p.price <= Number(maxPrice))
+ }
+
+ return HttpResponse.json(products)
+ }),
+]
+```
+
+**Multiple values for same parameter:**
+
+```typescript
+http.get('/api/items', ({ request }) => {
+ const url = new URL(request.url)
+ // /api/items?tag=red&tag=blue&tag=green
+ const tags = url.searchParams.getAll('tag') // ['red', 'blue', 'green']
+
+ return HttpResponse.json(
+ mockItems.filter((item) => tags.some((tag) => item.tags.includes(tag)))
+ )
+})
+```
+
+**When NOT to use this pattern:**
+- Endpoints that don't use query parameters
+
+Reference: [MSW query parameters](https://mswjs.io/docs/http/intercepting-requests/query-parameters)
diff --git a/.agents/skills/msw/references/match-url-patterns.md b/.agents/skills/msw/references/match-url-patterns.md
new file mode 100644
index 0000000..ef096cb
--- /dev/null
+++ b/.agents/skills/msw/references/match-url-patterns.md
@@ -0,0 +1,87 @@
+---
+title: Use URL Path Parameters Correctly
+impact: MEDIUM-HIGH
+impactDescription: Prevents silent handler mismatches; enables dynamic URL matching
+tags: match, url, params, path-parameters, dynamic
+---
+
+## Use URL Path Parameters Correctly
+
+Use `:paramName` syntax for dynamic path segments. Parameters are available in the resolver's `params` object. Incorrect patterns cause handlers to never match.
+
+**Incorrect (literal URL instead of pattern):**
+
+```typescript
+// Only matches exact string "/api/user/123"
+http.get('/api/user/123', () => {
+ return HttpResponse.json({ name: 'John' })
+})
+
+// Request to /api/user/456 is unhandled
+```
+
+**Correct (parameterized URL):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Matches /api/user/123, /api/user/abc, etc.
+ http.get('/api/user/:id', ({ params }) => {
+ return HttpResponse.json({ id: params.id, name: 'John' })
+ }),
+
+ // Multiple parameters
+ http.get('/api/org/:orgId/user/:userId', ({ params }) => {
+ return HttpResponse.json({
+ orgId: params.orgId,
+ userId: params.userId,
+ })
+ }),
+
+ // Optional parameters (use separate handlers)
+ http.get('/api/posts', () => {
+ return HttpResponse.json([{ id: '1' }, { id: '2' }])
+ }),
+ http.get('/api/posts/:postId', ({ params }) => {
+ return HttpResponse.json({ id: params.postId })
+ }),
+]
+```
+
+**Wildcard patterns:**
+
+```typescript
+// Match any path starting with /api/
+http.get('/api/*', () => {
+ return HttpResponse.json({ fallback: true })
+})
+
+// Match any origin with specific path
+http.get('*/api/user', () => {
+ return HttpResponse.json({ name: 'John' })
+})
+
+// Match all requests of a method
+http.get('*', () => {
+ return HttpResponse.json({ catchAll: true })
+})
+```
+
+**Type-safe parameters:**
+
+```typescript
+type UserParams = {
+ userId: string
+}
+
+http.get('/api/user/:userId', ({ params }) => {
+ // params.userId is typed as string
+ return HttpResponse.json({ id: params.userId })
+})
+```
+
+**When NOT to use this pattern:**
+- Exact URL matching for specific endpoints that never vary
+
+Reference: [MSW Request Matching](https://mswjs.io/docs/http/intercepting-requests)
diff --git a/.agents/skills/msw/references/response-custom-headers.md b/.agents/skills/msw/references/response-custom-headers.md
new file mode 100644
index 0000000..e59b273
--- /dev/null
+++ b/.agents/skills/msw/references/response-custom-headers.md
@@ -0,0 +1,125 @@
+---
+title: Set Response Headers Correctly
+impact: HIGH
+impactDescription: Ensures CORS, caching, and authentication headers work as expected
+tags: response, headers, cors, cache-control, authentication
+---
+
+## Set Response Headers Correctly
+
+Set appropriate response headers to simulate real API behavior. Headers like `Set-Cookie`, `Cache-Control`, and CORS headers affect how your application handles responses.
+
+**Incorrect (missing important headers):**
+
+```typescript
+http.post('/api/login', () => {
+ // Missing Set-Cookie header - authentication won't work
+ return HttpResponse.json({ user: { id: '1' } })
+})
+
+http.get('/api/data', () => {
+ // Missing caching headers - can't test cache behavior
+ return HttpResponse.json({ data: 'value' })
+})
+```
+
+**Correct (explicit headers):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // Authentication with cookies
+ http.post('/api/login', () => {
+ return HttpResponse.json(
+ { user: { id: '1', name: 'John' } },
+ {
+ headers: {
+ 'Set-Cookie': 'session=abc123; Path=/; HttpOnly',
+ },
+ }
+ )
+ }),
+
+ // Caching headers
+ http.get('/api/static-data', () => {
+ return HttpResponse.json(
+ { version: '1.0' },
+ {
+ headers: {
+ 'Cache-Control': 'public, max-age=3600',
+ 'ETag': '"abc123"',
+ },
+ }
+ )
+ }),
+
+ // No-cache for dynamic data
+ http.get('/api/user', () => {
+ return HttpResponse.json(
+ { name: 'John' },
+ {
+ headers: {
+ 'Cache-Control': 'no-store',
+ },
+ }
+ )
+ }),
+
+ // Pagination headers
+ http.get('/api/users', () => {
+ return HttpResponse.json(
+ [{ id: '1' }, { id: '2' }],
+ {
+ headers: {
+ 'X-Total-Count': '100',
+ 'X-Page': '1',
+ 'X-Per-Page': '10',
+ 'Link': '; rel="next"',
+ },
+ }
+ )
+ }),
+
+ // Rate limiting headers
+ http.get('/api/limited', () => {
+ return HttpResponse.json(
+ { data: 'value' },
+ {
+ headers: {
+ 'X-RateLimit-Limit': '100',
+ 'X-RateLimit-Remaining': '99',
+ 'X-RateLimit-Reset': String(Date.now() + 3600000),
+ },
+ }
+ )
+ }),
+]
+```
+
+**Testing rate limit handling:**
+
+```typescript
+it('shows rate limit warning when approaching limit', async () => {
+ server.use(
+ http.get('/api/data', () => {
+ return HttpResponse.json(
+ { data: 'value' },
+ {
+ headers: {
+ 'X-RateLimit-Remaining': '5',
+ },
+ }
+ )
+ })
+ )
+
+ render( )
+ expect(await screen.findByText('Rate limit warning')).toBeInTheDocument()
+})
+```
+
+**When NOT to use this pattern:**
+- Tests not concerned with header-specific behavior can omit custom headers
+
+Reference: [MSW HttpResponse Options](https://mswjs.io/docs/api/http-response)
diff --git a/.agents/skills/msw/references/response-delay-realistic.md b/.agents/skills/msw/references/response-delay-realistic.md
new file mode 100644
index 0000000..df3bb83
--- /dev/null
+++ b/.agents/skills/msw/references/response-delay-realistic.md
@@ -0,0 +1,92 @@
+---
+title: Add Delays Only for Timing Behavior Under Test
+impact: HIGH
+impactDescription: exercises loading, timeout, cancellation, and race behavior without slowing every test
+tags: response, delay, async, loading, timing
+---
+
+## Add Delays Only for Timing Behavior Under Test
+
+Keep baseline handlers deterministic and fast. Add `delay()` in the specific test or development scenario whose contract includes a loading state, timeout, cancellation, race, or hung request. A random global delay makes tests slower and less reproducible.
+
+**Correct (deterministic baseline handlers):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ http.get('/api/user', () =>
+ HttpResponse.json({ name: 'John' })
+ ),
+]
+```
+
+Override timing in the test that needs it:
+
+```typescript
+import { delay, http, HttpResponse } from 'msw'
+
+it('shows loading while the request is pending', async () => {
+ server.use(
+ http.get('/api/user', async () => {
+ await delay(100)
+ return HttpResponse.json({ name: 'John' })
+ })
+ )
+
+ render( )
+
+ expect(screen.getByText('Loading…')).toBeInTheDocument()
+ expect(await screen.findByText('John')).toBeInTheDocument()
+})
+```
+
+**Delay modes:**
+
+```typescript
+// Explicit, reproducible delay - use this when a test needs visible pending time
+await delay(200)
+
+// 'real' / bare delay(): randomized 100-400ms in the browser,
+// but a fixed 5ms under Node, so it will not make a loading state observable there
+await delay('real')
+
+// Infinite delay - simulates a hung request. Under Node this is setTimeout's
+// max int with .unref(), so it will not keep the process alive
+await delay('infinite')
+```
+
+Use `delay('infinite')` only when the test controls cancellation or timeout.
+
+**Incorrect (a global delay applied to every handler):**
+
+```typescript
+import { http, delay } from 'msw'
+
+export const handlers = [
+ // Slows every test in the suite to buy timing realism no assertion depends on
+ http.all('*', async () => {
+ await delay(100)
+ // No return = continue to the next matching handler
+ }),
+
+ http.get('/api/user', () => HttpResponse.json({ name: 'John' })),
+]
+```
+
+Do not use arbitrary delay values to wait in the test itself:
+
+```typescript
+render( )
+await new Promise((resolve) => setTimeout(resolve, 200))
+expect(screen.getByText('John')).toBeInTheDocument()
+```
+
+Assert observable state with the testing framework's async utilities instead:
+
+```typescript
+render( )
+expect(await screen.findByText('John')).toBeInTheDocument()
+```
+
+Reference: [MSW delay API](https://mswjs.io/docs/api/delay)
diff --git a/.agents/skills/msw/references/response-error-simulation.md b/.agents/skills/msw/references/response-error-simulation.md
new file mode 100644
index 0000000..8d42124
--- /dev/null
+++ b/.agents/skills/msw/references/response-error-simulation.md
@@ -0,0 +1,110 @@
+---
+title: Simulate Error Responses Correctly
+impact: HIGH
+impactDescription: Validates error handling; catches missing error states in UI
+tags: response, error, status, network-error, HttpResponse
+---
+
+## Simulate Error Responses Correctly
+
+Use proper HTTP status codes and `HttpResponse.error()` for network errors. Different error types require different handling in your application, and correct simulation ensures your error handling works.
+
+**Incorrect (ambiguous error responses):**
+
+```typescript
+// Unclear what type of error this represents
+http.get('/api/user', () => {
+ return HttpResponse.json({ error: 'Something went wrong' })
+})
+
+// Missing status code - defaults to 200!
+http.get('/api/user', () => {
+ return new HttpResponse('Error occurred')
+})
+```
+
+**Correct (explicit error types):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+// HTTP 4xx - Client errors
+http.get('/api/user/:id', () => {
+ return HttpResponse.json(
+ { error: 'User not found' },
+ { status: 404 }
+ )
+})
+
+http.post('/api/user', () => {
+ return HttpResponse.json(
+ { error: 'Validation failed', fields: ['email'] },
+ { status: 400 }
+ )
+})
+
+http.get('/api/protected', () => {
+ return HttpResponse.json(
+ { error: 'Unauthorized' },
+ { status: 401 }
+ )
+})
+
+http.get('/api/admin', () => {
+ return HttpResponse.json(
+ { error: 'Forbidden' },
+ { status: 403 }
+ )
+})
+
+// HTTP 5xx - Server errors
+http.get('/api/user', () => {
+ return HttpResponse.json(
+ { error: 'Internal server error' },
+ { status: 500 }
+ )
+})
+
+http.get('/api/data', () => {
+ return new HttpResponse(null, { status: 503 }) // Service unavailable
+})
+
+// Network error (connection failure, DNS failure, etc.)
+http.get('/api/user', () => {
+ return HttpResponse.error() // Causes fetch to reject
+})
+```
+
+**Testing error handling:**
+
+```typescript
+it('displays 404 message when user not found', async () => {
+ server.use(
+ http.get('/api/user/:id', () => {
+ return HttpResponse.json(
+ { error: 'User not found' },
+ { status: 404 }
+ )
+ })
+ )
+
+ render( )
+ expect(await screen.findByText('User not found')).toBeInTheDocument()
+})
+
+it('handles network failure gracefully', async () => {
+ server.use(
+ http.get('/api/user', () => {
+ return HttpResponse.error()
+ })
+ )
+
+ render( )
+ expect(await screen.findByText('Network error')).toBeInTheDocument()
+})
+```
+
+**When NOT to use this pattern:**
+- Happy path tests should use success responses
+
+Reference: [MSW HttpResponse API](https://mswjs.io/docs/api/http-response)
diff --git a/.agents/skills/msw/references/response-http-response-helpers.md b/.agents/skills/msw/references/response-http-response-helpers.md
new file mode 100644
index 0000000..a5a9408
--- /dev/null
+++ b/.agents/skills/msw/references/response-http-response-helpers.md
@@ -0,0 +1,83 @@
+---
+title: Use HttpResponse Static Methods
+impact: HIGH
+impactDescription: Automatic Content-Type headers; cleaner syntax; type safety
+tags: response, HttpResponse, json, text, xml, helpers
+---
+
+## Use HttpResponse Static Methods
+
+Use `HttpResponse.json()`, `HttpResponse.text()`, and other static methods instead of manually constructing responses. These methods automatically set correct Content-Type headers and provide cleaner, more readable code.
+
+**Incorrect (manual response construction):**
+
+```typescript
+http.get('/api/user', () => {
+ // Verbose, easy to forget Content-Type header
+ return new Response(
+ JSON.stringify({ name: 'John' }),
+ {
+ status: 200,
+ headers: {
+ 'Content-Type': 'application/json',
+ },
+ }
+ )
+})
+```
+
+**Correct (HttpResponse static methods):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+ // JSON - sets Content-Type: application/json automatically
+ http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'John', email: 'john@example.com' })
+ }),
+
+ // JSON with status code
+ http.post('/api/user', () => {
+ return HttpResponse.json(
+ { id: '1', message: 'Created' },
+ { status: 201 }
+ )
+ }),
+
+ // Text - sets Content-Type: text/plain
+ http.get('/api/text', () => {
+ return HttpResponse.text('Hello, World!')
+ }),
+
+ // XML - sets Content-Type: application/xml
+ http.get('/api/xml', () => {
+ return HttpResponse.xml('John ')
+ }),
+
+ // HTML - sets Content-Type: text/html
+ http.get('/page', () => {
+ return HttpResponse.html('Hello ')
+ }),
+
+ // ArrayBuffer for binary data
+ http.get('/api/file', () => {
+ const buffer = new ArrayBuffer(8)
+ return HttpResponse.arrayBuffer(buffer, {
+ headers: { 'Content-Type': 'application/octet-stream' },
+ })
+ }),
+
+ // FormData
+ http.get('/api/form', () => {
+ const form = new FormData()
+ form.append('field', 'value')
+ return HttpResponse.formData(form)
+ }),
+]
+```
+
+**When NOT to use this pattern:**
+- Custom Content-Types not covered by helpers may need manual `new Response()`
+
+Reference: [MSW HttpResponse API](https://mswjs.io/docs/api/http-response)
diff --git a/.agents/skills/msw/references/response-one-time-handlers.md b/.agents/skills/msw/references/response-one-time-handlers.md
new file mode 100644
index 0000000..8d26c55
--- /dev/null
+++ b/.agents/skills/msw/references/response-one-time-handlers.md
@@ -0,0 +1,103 @@
+---
+title: Use One-Time Handlers for Sequential Scenarios
+impact: HIGH
+impactDescription: Models realistic multi-step flows; tests retry logic correctly
+tags: response, once, one-time, sequential, retry
+---
+
+## Use One-Time Handlers for Sequential Scenarios
+
+Use the `{ once: true }` option for handlers that should only respond once, then fall back to the next matching handler. This is essential for testing retry logic, sequential API calls, or state changes between requests.
+
+**Incorrect (permanent override prevents testing retries):**
+
+```typescript
+it('retries after failure', async () => {
+ server.use(
+ http.get('/api/user', () => {
+ return new HttpResponse(null, { status: 500 })
+ })
+ )
+
+ render( )
+
+ // Component retries, but always gets 500 - can't test success after retry
+ await userEvent.click(screen.getByRole('button', { name: 'Retry' }))
+ // Still failing...
+})
+```
+
+**Correct (one-time handler for first request):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+it('retries after failure and succeeds', async () => {
+ server.use(
+ http.get(
+ '/api/user',
+ () => {
+ return new HttpResponse(null, { status: 500 })
+ },
+ { once: true } // Only affects first request
+ )
+ )
+
+ render( )
+
+ // First request fails
+ expect(await screen.findByText('Error loading user')).toBeInTheDocument()
+
+ // Retry succeeds (uses baseline happy-path handler)
+ await userEvent.click(screen.getByRole('button', { name: 'Retry' }))
+ expect(await screen.findByText('John')).toBeInTheDocument()
+})
+```
+
+**Sequential state changes:**
+
+```typescript
+it('shows optimistic update then server response', async () => {
+ let callCount = 0
+
+ server.use(
+ http.post('/api/like', () => {
+ callCount++
+ if (callCount === 1) {
+ // First call - slow response simulates network
+ return HttpResponse.json({ likes: 11 })
+ }
+ // Subsequent calls
+ return HttpResponse.json({ likes: 12 })
+ })
+ )
+
+ // Test optimistic update behavior
+})
+```
+
+**Multiple sequential states:**
+
+```typescript
+server.use(
+ // First request: pending
+ http.get('/api/order/:id', () => {
+ return HttpResponse.json({ status: 'pending' })
+ }, { once: true }),
+
+ // Second request: processing
+ http.get('/api/order/:id', () => {
+ return HttpResponse.json({ status: 'processing' })
+ }, { once: true }),
+
+ // Third+ requests: completed
+ http.get('/api/order/:id', () => {
+ return HttpResponse.json({ status: 'completed' })
+ })
+)
+```
+
+**When NOT to use this pattern:**
+- Single-state tests that don't involve retries or polling
+
+Reference: [Network Behavior Overrides](https://mswjs.io/docs/best-practices/network-behavior-overrides)
diff --git a/.agents/skills/msw/references/response-streaming.md b/.agents/skills/msw/references/response-streaming.md
new file mode 100644
index 0000000..3d82862
--- /dev/null
+++ b/.agents/skills/msw/references/response-streaming.md
@@ -0,0 +1,114 @@
+---
+title: Mock Streaming Responses with ReadableStream
+impact: HIGH
+impactDescription: Tests streaming UIs, chat interfaces, and progressive loading
+tags: response, streaming, ReadableStream, sse, progressive
+---
+
+## Mock Streaming Responses with ReadableStream
+
+Use `ReadableStream` to mock streaming responses for Server-Sent Events (SSE), chunked transfers, or streaming APIs. This enables testing of real-time features and progressive UI updates.
+
+**Incorrect (returning complete response immediately):**
+
+```typescript
+// Chat response arrives all at once - doesn't test streaming UI
+http.post('/api/chat', () => {
+ return HttpResponse.json({
+ message: 'Here is the complete response all at once',
+ })
+})
+```
+
+**Correct (streaming response):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+// Text streaming (like AI chat)
+http.post('/api/chat', () => {
+ const encoder = new TextEncoder()
+ const chunks = ['Hello', ' ', 'world', '!']
+
+ const stream = new ReadableStream({
+ async start(controller) {
+ for (const chunk of chunks) {
+ controller.enqueue(encoder.encode(chunk))
+ await new Promise((resolve) => setTimeout(resolve, 100))
+ }
+ controller.close()
+ },
+ })
+
+ return new HttpResponse(stream, {
+ headers: {
+ 'Content-Type': 'text/plain',
+ 'Transfer-Encoding': 'chunked',
+ },
+ })
+})
+```
+
+**Server-Sent Events (SSE):**
+
+```typescript
+http.get('/api/events', () => {
+ const encoder = new TextEncoder()
+ const events = [
+ { id: '1', data: { message: 'First event' } },
+ { id: '2', data: { message: 'Second event' } },
+ { id: '3', data: { message: 'Third event' } },
+ ]
+
+ const stream = new ReadableStream({
+ async start(controller) {
+ for (const event of events) {
+ const sseMessage = `id: ${event.id}\ndata: ${JSON.stringify(event.data)}\n\n`
+ controller.enqueue(encoder.encode(sseMessage))
+ await new Promise((resolve) => setTimeout(resolve, 200))
+ }
+ controller.close()
+ },
+ })
+
+ return new HttpResponse(stream, {
+ headers: {
+ 'Content-Type': 'text/event-stream',
+ 'Cache-Control': 'no-cache',
+ 'Connection': 'keep-alive',
+ },
+ })
+})
+```
+
+**JSON streaming (newline-delimited):**
+
+```typescript
+http.get('/api/stream-json', () => {
+ const encoder = new TextEncoder()
+ const items = [
+ { id: 1, name: 'Item 1' },
+ { id: 2, name: 'Item 2' },
+ { id: 3, name: 'Item 3' },
+ ]
+
+ const stream = new ReadableStream({
+ async start(controller) {
+ for (const item of items) {
+ controller.enqueue(encoder.encode(JSON.stringify(item) + '\n'))
+ await new Promise((resolve) => setTimeout(resolve, 100))
+ }
+ controller.close()
+ },
+ })
+
+ return new HttpResponse(stream, {
+ headers: { 'Content-Type': 'application/x-ndjson' },
+ })
+})
+```
+
+**When NOT to use this pattern:**
+- APIs that return complete responses don't need streaming mocks
+
+Reference: [MSW ReadableStream Support](https://mswjs.io/blog/introducing-msw-2.0)
diff --git a/.agents/skills/msw/references/setup-lifecycle-hooks.md b/.agents/skills/msw/references/setup-lifecycle-hooks.md
new file mode 100644
index 0000000..9c6269d
--- /dev/null
+++ b/.agents/skills/msw/references/setup-lifecycle-hooks.md
@@ -0,0 +1,57 @@
+---
+title: Configure Server Lifecycle in Test Setup
+impact: CRITICAL
+impactDescription: Prevents handler leakage and ensures test isolation; eliminates flaky tests
+tags: setup, lifecycle, vitest, jest, beforeAll, afterEach
+---
+
+## Configure Server Lifecycle in Test Setup
+
+Server lifecycle hooks must be configured in test setup files to ensure proper initialization, cleanup between tests, and graceful shutdown. Missing hooks cause handler pollution and unpredictable test behavior.
+
+**Incorrect (no lifecycle management):**
+
+```typescript
+// handlers.test.ts
+import { server } from './mocks/node'
+
+// Server never started, handlers never reset
+// Tests may pass/fail randomly depending on execution order
+it('fetches user', async () => {
+ const response = await fetch('/user')
+ // This fails silently - no mocking active
+})
+```
+
+**Correct (proper lifecycle hooks):**
+
+```typescript
+// vitest.setup.ts or setupTests.ts
+import { beforeAll, afterEach, afterAll } from 'vitest'
+import { server } from './mocks/node'
+
+// Start server before all tests
+beforeAll(() => server.listen())
+
+// Reset handlers after each test to ensure isolation
+afterEach(() => server.resetHandlers())
+
+// Clean shutdown after all tests complete
+afterAll(() => server.close())
+```
+
+**Jest equivalent:**
+
+```typescript
+// setupTests.ts
+import { server } from './mocks/node'
+
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+```
+
+**When NOT to use this pattern:**
+- Browser-based tests use `worker.start()` and `worker.stop()` instead
+
+Reference: [MSW Quick Start - Test Setup](https://mswjs.io/docs/quick-start)
diff --git a/.agents/skills/msw/references/setup-node-version.md b/.agents/skills/msw/references/setup-node-version.md
new file mode 100644
index 0000000..ffec58c
--- /dev/null
+++ b/.agents/skills/msw/references/setup-node-version.md
@@ -0,0 +1,72 @@
+---
+title: Require Node.js 18+ for MSW v2
+impact: CRITICAL
+impactDescription: MSW v2 requires Node 18+; older versions cause complete failure
+tags: setup, node, version, requirements, compatibility
+---
+
+## Require Node.js 18+ for MSW v2
+
+MSW v2 sets Node.js 18.0.0 as the minimum supported version. Older versions lack native `fetch` and other required APIs, causing complete mocking failure.
+
+**Incorrect (using unsupported Node version):**
+
+```json
+// package.json
+{
+ "engines": {
+ "node": ">=14.0.0"
+ }
+}
+```
+
+```bash
+# Node 16 - MSW v2 fails silently or throws cryptic errors
+$ node -v
+v16.20.0
+
+$ npm test
+# ReferenceError: fetch is not defined
+# or: Cannot read properties of undefined
+```
+
+**Correct (enforce Node 18+ requirement):**
+
+```json
+// package.json
+{
+ "engines": {
+ "node": ">=18.0.0"
+ }
+}
+```
+
+```yaml
+# .nvmrc
+18
+```
+
+```yaml
+# CI configuration (GitHub Actions)
+jobs:
+ test:
+ runs-on: ubuntu-latest
+ strategy:
+ matrix:
+ node-version: [18, 20, 22]
+```
+
+**Verify installation:**
+
+```bash
+# Check Node version
+node -v # Should be v18.x.x or higher
+
+# Check MSW version
+npm ls msw # Should be v2.x.x
+```
+
+**When NOT to use this pattern:**
+- If stuck on Node 16, use MSW v1.x instead (with different API patterns)
+
+Reference: [MSW v2 Migration - Requirements](https://mswjs.io/docs/migrations/1.x-to-2.x/)
diff --git a/.agents/skills/msw/references/setup-server-node-entrypoint.md b/.agents/skills/msw/references/setup-server-node-entrypoint.md
new file mode 100644
index 0000000..36abfbe
--- /dev/null
+++ b/.agents/skills/msw/references/setup-server-node-entrypoint.md
@@ -0,0 +1,45 @@
+---
+title: Use Correct Entrypoint for Node.js
+impact: CRITICAL
+impactDescription: Zero mocking if wrong entrypoint; 100% test failures
+tags: setup, entrypoint, node, server, msw-node
+---
+
+## Use Correct Entrypoint for Node.js
+
+MSW v2 separates browser and Node.js entrypoints. Using the wrong import causes complete mocking failure with no interception occurring.
+
+**Incorrect (importing from wrong path):**
+
+```typescript
+// This imports browser code into Node.js - mocking silently fails
+import { setupServer } from 'msw'
+import { setupWorker } from 'msw'
+
+const server = setupServer(...handlers)
+```
+
+**Correct (using msw/node entrypoint):**
+
+```typescript
+// Node.js environments (tests, SSR) use msw/node
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+export const server = setupServer(...handlers)
+```
+
+**Browser environments use msw/browser:**
+
+```typescript
+// Browser environments use msw/browser
+import { setupWorker } from 'msw/browser'
+import { handlers } from './handlers'
+
+export const worker = setupWorker(...handlers)
+```
+
+**When NOT to use this pattern:**
+- Never deviate from this pattern; entrypoint selection is binary based on environment
+
+Reference: [MSW Node.js Integration](https://mswjs.io/docs/integrations/node)
diff --git a/.agents/skills/msw/references/setup-typescript-config.md b/.agents/skills/msw/references/setup-typescript-config.md
new file mode 100644
index 0000000..b609e97
--- /dev/null
+++ b/.agents/skills/msw/references/setup-typescript-config.md
@@ -0,0 +1,74 @@
+---
+title: Configure TypeScript for MSW v2
+impact: CRITICAL
+impactDescription: TypeScript 4.8+ required; incorrect config causes type errors
+tags: setup, typescript, configuration, types, compiler
+---
+
+## Configure TypeScript for MSW v2
+
+MSW v2 requires TypeScript 4.8+ for proper type inference. Incorrect TypeScript configuration causes confusing type errors and prevents proper handler typing.
+
+**Incorrect (outdated TypeScript or missing config):**
+
+```json
+// tsconfig.json - missing moduleResolution
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ESNext"
+ // No moduleResolution - imports fail to resolve
+ }
+}
+```
+
+```typescript
+// Type errors due to incorrect resolution
+import { http, HttpResponse } from 'msw'
+// Error: Cannot find module 'msw' or its corresponding type declarations
+```
+
+**Correct (proper TypeScript configuration):**
+
+```json
+// tsconfig.json
+{
+ "compilerOptions": {
+ "target": "ES2020",
+ "module": "ESNext",
+ "moduleResolution": "bundler", // or "node16" / "nodenext"
+ "esModuleInterop": true,
+ "strict": true,
+ "skipLibCheck": true
+ }
+}
+```
+
+**Typed handlers with proper inference:**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+
+interface User {
+ id: string
+ name: string
+ email: string
+}
+
+export const handlers = [
+ http.get('/api/user/:id', ({ params }) => {
+ // params.id is typed as string
+ return HttpResponse.json({
+ id: params.id,
+ name: 'John Doe',
+ email: 'john@example.com',
+ })
+ }),
+]
+```
+
+**When NOT to use this pattern:**
+- JavaScript-only projects don't need TypeScript configuration
+- Projects using older bundlers may need `moduleResolution: "node"`
+
+Reference: [MSW v2 Migration - TypeScript](https://mswjs.io/docs/migrations/1.x-to-2.x/)
diff --git a/.agents/skills/msw/references/setup-unhandled-requests.md b/.agents/skills/msw/references/setup-unhandled-requests.md
new file mode 100644
index 0000000..69f3bf8
--- /dev/null
+++ b/.agents/skills/msw/references/setup-unhandled-requests.md
@@ -0,0 +1,70 @@
+---
+title: Configure Unhandled Request Behavior
+impact: CRITICAL
+impactDescription: Catches missing handlers immediately; prevents silent test failures
+tags: setup, unhandled, error, configuration, onUnhandledRequest
+---
+
+## Configure Unhandled Request Behavior
+
+Configure `onUnhandledRequest: 'error'` to fail tests when requests lack handlers. This catches missing mocks immediately instead of allowing silent network calls or undefined behavior.
+
+**Incorrect (default silent behavior):**
+
+```typescript
+// mocks/node.ts
+import { setupServer } from 'msw/node'
+import { handlers } from './handlers'
+
+// Default behavior: warns but doesn't fail
+// Unhandled requests may hit real APIs or return undefined
+export const server = setupServer(...handlers)
+```
+
+```typescript
+// Test passes despite missing handler - false positive!
+it('submits form', async () => {
+ await submitForm({ email: 'test@example.com' })
+ // POST /submit has no handler but test doesn't fail
+ expect(screen.getByText('Success')).toBeInTheDocument()
+})
+```
+
+**Correct (strict unhandled request handling):**
+
+```typescript
+// vitest.setup.ts
+import { server } from './mocks/node'
+
+beforeAll(() => {
+ server.listen({
+ onUnhandledRequest: 'error', // Fail on any unhandled request
+ })
+})
+
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+```
+
+**Custom handling for specific URLs:**
+
+```typescript
+beforeAll(() => {
+ server.listen({
+ onUnhandledRequest(request, print) {
+ // Allow certain requests through (e.g., static assets)
+ if (request.url.includes('/static/')) {
+ return
+ }
+ // Error on all other unhandled requests
+ print.error()
+ },
+ })
+})
+```
+
+**When NOT to use this pattern:**
+- Development environments may prefer `'warn'` for less disruptive feedback
+- Integration tests that intentionally hit real endpoints
+
+Reference: [MSW Best Practices - Avoid Request Assertions](https://mswjs.io/docs/best-practices/avoid-request-assertions/)
diff --git a/.agents/skills/msw/references/setup-worker-script-commit.md b/.agents/skills/msw/references/setup-worker-script-commit.md
new file mode 100644
index 0000000..ad9a013
--- /dev/null
+++ b/.agents/skills/msw/references/setup-worker-script-commit.md
@@ -0,0 +1,65 @@
+---
+title: Commit Worker Script to Version Control
+impact: CRITICAL
+impactDescription: Eliminates setup friction for team members; prevents CI failures
+tags: setup, worker, git, mockServiceWorker, browser
+---
+
+## Commit Worker Script to Version Control
+
+The `mockServiceWorker.js` file generated by `msw init` should be committed to Git. This ensures team members and CI environments can run browser tests without additional setup commands.
+
+**Incorrect (gitignoring worker script):**
+
+```gitignore
+# .gitignore
+# This forces every developer to run msw init manually
+public/mockServiceWorker.js
+```
+
+```bash
+# New team member clones repo, runs tests, gets cryptic errors
+# because worker script doesn't exist
+npm test
+# Error: Cannot find mockServiceWorker.js
+```
+
+**Correct (commit and auto-update worker script):**
+
+```bash
+# Generate worker script with --save flag
+npx msw init public/ --save
+```
+
+```json
+// package.json - auto-updates worker on msw version changes
+{
+ "msw": {
+ "workerDirectory": ["public"]
+ }
+}
+```
+
+```gitignore
+# .gitignore - do NOT ignore the worker script
+# public/mockServiceWorker.js <- remove this line
+```
+
+**Monorepo configuration:**
+
+```json
+// Root package.json for monorepos
+{
+ "msw": {
+ "workerDirectory": [
+ "apps/web/public",
+ "apps/admin/public"
+ ]
+ }
+}
+```
+
+**When NOT to use this pattern:**
+- If treating as generated artifact, ensure CI runs `msw init` before tests
+
+Reference: [Managing the Worker](https://mswjs.io/docs/best-practices/managing-the-worker/)
diff --git a/.agents/skills/msw/references/test-async-utilities.md b/.agents/skills/msw/references/test-async-utilities.md
new file mode 100644
index 0000000..d228a71
--- /dev/null
+++ b/.agents/skills/msw/references/test-async-utilities.md
@@ -0,0 +1,81 @@
+---
+title: Use Async Testing Utilities for Mock Responses
+impact: HIGH
+impactDescription: Prevents race conditions; ensures responses arrive before assertions
+tags: test, async, waitFor, findBy, testing-library, race-condition
+---
+
+## Use Async Testing Utilities for Mock Responses
+
+Use async testing utilities (`findBy`, `waitFor`) instead of `getBy` or manual `setTimeout` when testing components that make API calls. Mock responses are asynchronous, and synchronous assertions will fail before data arrives.
+
+**Incorrect (synchronous assertions):**
+
+```typescript
+it('displays user name', () => {
+ render( )
+
+ // Fails! Response hasn't arrived yet
+ expect(screen.getByText('John')).toBeInTheDocument()
+})
+
+// Also incorrect - arbitrary timeout
+it('displays user name', async () => {
+ render( )
+
+ await new Promise((resolve) => setTimeout(resolve, 100))
+
+ // Flaky - 100ms might not be enough, or wastes time if faster
+ expect(screen.getByText('John')).toBeInTheDocument()
+})
+```
+
+**Correct (async testing utilities):**
+
+```typescript
+import { render, screen, waitFor } from '@testing-library/react'
+
+it('displays user name', async () => {
+ render( )
+
+ // findBy* returns a promise that resolves when element appears
+ expect(await screen.findByText('John')).toBeInTheDocument()
+})
+
+// For non-element assertions, use waitFor
+it('updates document title', async () => {
+ render( )
+
+ await waitFor(() => {
+ expect(document.title).toBe('John - Profile')
+ })
+})
+
+// For multiple elements
+it('displays user list', async () => {
+ render( )
+
+ const users = await screen.findAllByRole('listitem')
+ expect(users).toHaveLength(3)
+})
+```
+
+**With loading states:**
+
+```typescript
+it('shows loading then content', async () => {
+ render( )
+
+ // Loading state appears immediately
+ expect(screen.getByText('Loading...')).toBeInTheDocument()
+
+ // Content replaces loading after response
+ expect(await screen.findByText('John')).toBeInTheDocument()
+ expect(screen.queryByText('Loading...')).not.toBeInTheDocument()
+})
+```
+
+**When NOT to use this pattern:**
+- Synchronous operations that don't involve API calls can use `getBy`
+
+Reference: [Testing Library Async Methods](https://testing-library.com/docs/dom-testing-library/api-async/)
diff --git a/.agents/skills/msw/references/test-avoid-request-assertions.md b/.agents/skills/msw/references/test-avoid-request-assertions.md
new file mode 100644
index 0000000..159a84c
--- /dev/null
+++ b/.agents/skills/msw/references/test-avoid-request-assertions.md
@@ -0,0 +1,87 @@
+---
+title: Avoid Direct Request Assertions
+impact: HIGH
+impactDescription: Tests implementation details; breaks on refactors that preserve behavior
+tags: test, assertions, anti-pattern, implementation-details, behavior
+---
+
+## Avoid Direct Request Assertions
+
+Do not assert that specific requests were made with specific parameters. This tests implementation details rather than behavior. Instead, assert on your application's reaction to responses.
+
+**Incorrect (asserting request details):**
+
+```typescript
+it('sends correct data when creating user', async () => {
+ const requestSpy = vi.fn()
+
+ server.use(
+ http.post('/api/user', async ({ request }) => {
+ requestSpy(await request.json())
+ return HttpResponse.json({ id: '1' })
+ })
+ )
+
+ await createUser({ name: 'John', email: 'john@example.com' })
+
+ // Testing implementation details - what if we add a field?
+ expect(requestSpy).toHaveBeenCalledWith({
+ name: 'John',
+ email: 'john@example.com',
+ })
+})
+```
+
+**Correct (assert behavior through responses):**
+
+```typescript
+it('creates user and shows success message', async () => {
+ server.use(
+ http.post('/api/user', async ({ request }) => {
+ const body = await request.json()
+ // Validate in handler - returns error if invalid
+ if (!body.email) {
+ return HttpResponse.json(
+ { error: 'Email required' },
+ { status: 400 }
+ )
+ }
+ return HttpResponse.json({ id: '1', ...body }, { status: 201 })
+ })
+ )
+
+ render( )
+ await userEvent.type(screen.getByLabelText('Name'), 'John')
+ await userEvent.type(screen.getByLabelText('Email'), 'john@example.com')
+ await userEvent.click(screen.getByRole('button', { name: 'Create' }))
+
+ // Assert application behavior, not request details
+ expect(await screen.findByText('User created!')).toBeInTheDocument()
+})
+```
+
+**For one-way requests (analytics, logging):**
+
+```typescript
+import { server } from './mocks/node'
+
+it('tracks page view', async () => {
+ const trackingPromise = new Promise((resolve) => {
+ server.events.on('request:end', ({ request }) => {
+ if (request.url.includes('/analytics')) {
+ resolve()
+ }
+ })
+ })
+
+ render( )
+
+ // Verify the request was made without asserting payload
+ await expect(trackingPromise).resolves.toBeUndefined()
+})
+```
+
+**When NOT to use this pattern:**
+- Analytics/telemetry testing may require request payload verification via lifecycle events
+
+Reference: [Avoid Request Assertions](https://mswjs.io/docs/best-practices/avoid-request-assertions/)
diff --git a/.agents/skills/msw/references/test-clear-request-cache.md b/.agents/skills/msw/references/test-clear-request-cache.md
new file mode 100644
index 0000000..8f62502
--- /dev/null
+++ b/.agents/skills/msw/references/test-clear-request-cache.md
@@ -0,0 +1,85 @@
+---
+title: Clear Request Library Caches Between Tests
+impact: HIGH
+impactDescription: Prevents stale cached responses; ensures fresh mock data per test
+tags: test, cache, swr, react-query, tanstack-query, isolation
+---
+
+## Clear Request Library Caches Between Tests
+
+Clear data fetching library caches between tests. Libraries like SWR, TanStack Query, and Apollo cache responses, causing tests to receive stale data from previous tests instead of fresh mocked responses.
+
+**Incorrect (cached data leaks between tests):**
+
+```typescript
+// test-a.spec.ts
+it('displays original user', async () => {
+ // Response cached by SWR/React Query
+ render( )
+ expect(await screen.findByText('John')).toBeInTheDocument()
+})
+
+// test-b.spec.ts
+it('displays updated user', async () => {
+ server.use(
+ http.get('/api/user', () => {
+ return HttpResponse.json({ name: 'Jane' }) // Different user
+ })
+ )
+ render( )
+ // FAILS! Cache returns 'John' from previous test
+ expect(await screen.findByText('Jane')).toBeInTheDocument()
+})
+```
+
+**Correct (clear caches in test setup):**
+
+```typescript
+// SWR cache clearing
+import { cache } from 'swr'
+
+afterEach(() => {
+ // Clear SWR cache
+ cache.clear()
+})
+```
+
+```typescript
+// TanStack Query cache clearing
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+
+const createTestQueryClient = () =>
+ new QueryClient({
+ defaultOptions: {
+ queries: { retry: false, gcTime: 0 },
+ },
+ })
+
+const renderWithClient = (ui: React.ReactElement) => {
+ const testQueryClient = createTestQueryClient()
+ return render(
+ {ui}
+ )
+}
+
+// Each test gets fresh QueryClient with no cached data
+it('displays user', async () => {
+ renderWithClient( )
+ expect(await screen.findByText('John')).toBeInTheDocument()
+})
+```
+
+```typescript
+// Apollo Client cache clearing
+import { ApolloClient, InMemoryCache } from '@apollo/client'
+
+afterEach(async () => {
+ await client.clearStore()
+ // or client.resetStore() to refetch active queries
+})
+```
+
+**When NOT to use this pattern:**
+- Tests intentionally verifying cache behavior should not clear caches
+
+Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/)
diff --git a/.agents/skills/msw/references/test-concurrent-boundary.md b/.agents/skills/msw/references/test-concurrent-boundary.md
new file mode 100644
index 0000000..6735330
--- /dev/null
+++ b/.agents/skills/msw/references/test-concurrent-boundary.md
@@ -0,0 +1,88 @@
+---
+title: Use server.boundary() for Concurrent Tests
+impact: HIGH
+impactDescription: Enables parallel test execution; prevents cross-test handler pollution
+tags: test, concurrent, boundary, isolation, parallel
+---
+
+## Use server.boundary() for Concurrent Tests
+
+Wrap concurrent tests in `server.boundary()` to isolate handler overrides. Without boundaries, concurrent tests share handlers, causing race conditions and unpredictable failures.
+
+**Incorrect (concurrent tests without boundaries):**
+
+```typescript
+// Tests run in parallel - handlers leak between them
+it.concurrent('fetches user', async () => {
+ // Uses initial handlers
+ const response = await fetch('https://api.example.com/user')
+ expect(response.ok).toBe(true)
+})
+
+it.concurrent('handles error', async () => {
+ server.use(
+ http.get('https://api.example.com/user', () => {
+ return new HttpResponse(null, { status: 500 })
+ })
+ )
+ // This override might affect the other concurrent test!
+ const response = await fetch('https://api.example.com/user')
+ expect(response.status).toBe(500)
+})
+```
+
+**Correct (boundary-isolated concurrent tests):**
+
+```typescript
+import { http, HttpResponse } from 'msw'
+import { setupServer } from 'msw/node'
+
+const server = setupServer(
+ http.get('https://api.example.com/user', () => {
+ return HttpResponse.json({ name: 'John' })
+ })
+)
+
+beforeAll(() => server.listen())
+afterAll(() => server.close())
+
+it.concurrent(
+ 'fetches user',
+ server.boundary(async () => {
+ const response = await fetch('https://api.example.com/user')
+ const user = await response.json()
+ expect(user).toEqual({ name: 'John' })
+ })
+)
+
+it.concurrent(
+ 'handles server error',
+ server.boundary(async () => {
+ // Override is scoped to this boundary only
+ server.use(
+ http.get('https://api.example.com/user', () => {
+ return new HttpResponse(null, { status: 500 })
+ })
+ )
+ const response = await fetch('https://api.example.com/user')
+ expect(response.status).toBe(500)
+ })
+)
+
+it.concurrent(
+ 'handles network error',
+ server.boundary(async () => {
+ server.use(
+ http.get('https://api.example.com/user', () => {
+ return HttpResponse.error()
+ })
+ )
+ await expect(fetch('https://api.example.com/user')).rejects.toThrow()
+ })
+)
+```
+
+**When NOT to use this pattern:**
+- Sequential tests (non-concurrent) can use standard `afterEach` reset pattern
+
+Reference: [server.boundary() API](https://mswjs.io/docs/api/setup-server/boundary)
diff --git a/.agents/skills/msw/references/test-fake-timers-config.md b/.agents/skills/msw/references/test-fake-timers-config.md
new file mode 100644
index 0000000..1dbca38
--- /dev/null
+++ b/.agents/skills/msw/references/test-fake-timers-config.md
@@ -0,0 +1,91 @@
+---
+title: Configure Fake Timers to Preserve queueMicrotask
+impact: HIGH
+impactDescription: Prevents request body parsing from hanging indefinitely
+tags: test, timers, jest, vitest, queueMicrotask, fake-timers
+---
+
+## Configure Fake Timers to Preserve queueMicrotask
+
+When using fake timers, configure them to not mock `queueMicrotask`. The global `fetch` uses `queueMicrotask` internally for body parsing, and mocking it causes `request.json()` and similar methods to hang forever.
+
+**Incorrect (default fake timers):**
+
+```typescript
+// vitest.config.ts or jest.config.js
+beforeEach(() => {
+ vi.useFakeTimers() // Mocks ALL timer functions including queueMicrotask
+})
+
+// Test hangs indefinitely
+it('parses request body', async () => {
+ server.use(
+ http.post('/api/user', async ({ request }) => {
+ const body = await request.json() // Never resolves!
+ return HttpResponse.json(body)
+ })
+ )
+
+ await fetch('/api/user', {
+ method: 'POST',
+ body: JSON.stringify({ name: 'John' }),
+ })
+})
+```
+
+**Correct (exclude queueMicrotask from fake timers):**
+
+```typescript
+// Vitest
+beforeEach(() => {
+ vi.useFakeTimers({
+ toFake: [
+ 'setTimeout',
+ 'setInterval',
+ 'clearTimeout',
+ 'clearInterval',
+ 'setImmediate',
+ 'clearImmediate',
+ 'Date',
+ ],
+ // queueMicrotask is NOT in the list - remains real
+ })
+})
+
+// Or more explicitly with shouldAdvanceTime
+beforeEach(() => {
+ vi.useFakeTimers({ shouldAdvanceTime: true })
+})
+```
+
+```typescript
+// Jest
+beforeEach(() => {
+ jest.useFakeTimers({
+ doNotFake: ['queueMicrotask'], // Explicitly preserve queueMicrotask
+ })
+})
+```
+
+**Alternative - advance timers after async operations:**
+
+```typescript
+it('handles delayed response', async () => {
+ vi.useFakeTimers()
+
+ const fetchPromise = fetch('/api/user')
+
+ // Advance timers to allow microtasks to process
+ await vi.runAllTimersAsync()
+
+ const response = await fetchPromise
+ expect(response.ok).toBe(true)
+
+ vi.useRealTimers()
+})
+```
+
+**When NOT to use this pattern:**
+- If not using fake timers, this configuration is unnecessary
+
+Reference: [MSW Debugging Runbook](https://mswjs.io/docs/runbook/)
diff --git a/.agents/skills/msw/references/test-jsdom-environment.md b/.agents/skills/msw/references/test-jsdom-environment.md
new file mode 100644
index 0000000..de100b0
--- /dev/null
+++ b/.agents/skills/msw/references/test-jsdom-environment.md
@@ -0,0 +1,67 @@
+---
+title: Use Correct JSDOM Environment for Jest
+impact: HIGH
+impactDescription: Prevents Node.js global conflicts; ensures proper fetch availability
+tags: test, jest, jsdom, environment, configuration
+---
+
+## Use Correct JSDOM Environment for Jest
+
+Use `jest-fixed-jsdom` instead of `jest-environment-jsdom` when testing with MSW in Jest. Standard JSDOM uses browser export conditions but runs in Node.js, causing conflicts with MSW's entrypoints.
+
+**Incorrect (standard jsdom environment):**
+
+```javascript
+// jest.config.js
+module.exports = {
+ testEnvironment: 'jsdom', // Uses browser exports incorrectly
+}
+```
+
+```typescript
+// Tests fail with cryptic errors
+// TypeError: Cannot read properties of undefined
+// or: fetch is not defined
+```
+
+**Correct (use jest-fixed-jsdom):**
+
+```bash
+npm install -D jest-fixed-jsdom
+```
+
+```javascript
+// jest.config.js
+module.exports = {
+ testEnvironment: 'jest-fixed-jsdom',
+}
+```
+
+**Alternative - migrate to Vitest:**
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+ test: {
+ environment: 'jsdom', // Vitest handles this correctly
+ setupFiles: ['./vitest.setup.ts'],
+ },
+})
+```
+
+**Why this matters:**
+
+JSDOM uses browser export conditions by default, causing packages like MSW to use browser-specific code in a Node.js context. This leads to:
+- Missing Node.js globals
+- Incorrect module resolution
+- Silent failures or cryptic errors
+
+`jest-fixed-jsdom` and Vitest correctly handle the Node.js/browser boundary.
+
+**When NOT to use this pattern:**
+- Vitest users don't need this; Vitest handles environments correctly
+- Node-only tests (no DOM) should use `testEnvironment: 'node'`
+
+Reference: [MSW v2 Migration - Jest/JSDOM](https://mswjs.io/docs/migrations/1.x-to-2.x/)
diff --git a/.agents/skills/msw/references/test-reset-handlers.md b/.agents/skills/msw/references/test-reset-handlers.md
new file mode 100644
index 0000000..3831bce
--- /dev/null
+++ b/.agents/skills/msw/references/test-reset-handlers.md
@@ -0,0 +1,63 @@
+---
+title: Reset Handlers After Each Test
+impact: HIGH
+impactDescription: Prevents handler pollution; eliminates test order dependencies
+tags: test, reset, isolation, afterEach, resetHandlers
+---
+
+## Reset Handlers After Each Test
+
+Call `server.resetHandlers()` in `afterEach` to remove runtime handlers added during tests. Without reset, handlers from one test can affect subsequent tests, causing mysterious failures that depend on test execution order.
+
+**Incorrect (no handler reset):**
+
+```typescript
+// test-a.spec.ts
+it('handles server error', () => {
+ server.use(
+ http.get('/api/user', () => new HttpResponse(null, { status: 500 }))
+ )
+ // Test passes...
+})
+
+// test-b.spec.ts - runs after test-a
+it('displays user name', () => {
+ // FAILS! Still receiving 500 error from test-a's handler
+ render( )
+ expect(screen.getByText('John')).toBeInTheDocument()
+})
+```
+
+**Correct (reset in afterEach):**
+
+```typescript
+// vitest.setup.ts
+import { server } from './mocks/node'
+
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers()) // Clean slate for each test
+afterAll(() => server.close())
+```
+
+```typescript
+// user.test.ts
+it('handles server error', () => {
+ server.use(
+ http.get('/api/user', () => new HttpResponse(null, { status: 500 }))
+ )
+ render( )
+ expect(screen.getByRole('alert')).toHaveTextContent('Error')
+})
+// Handler is removed after this test completes
+
+it('displays user name', () => {
+ // Uses baseline happy-path handler
+ render( )
+ expect(screen.getByText('John')).toBeInTheDocument()
+})
+```
+
+**When NOT to use this pattern:**
+- `server.boundary()` provides automatic isolation for concurrent tests
+
+Reference: [Network Behavior Overrides](https://mswjs.io/docs/best-practices/network-behavior-overrides)
diff --git a/.agents/skills/nextjs/SKILL.md b/.agents/skills/nextjs/SKILL.md
new file mode 100644
index 0000000..40ddc37
--- /dev/null
+++ b/.agents/skills/nextjs/SKILL.md
@@ -0,0 +1,115 @@
+---
+name: nextjs
+description: Next.js 16 App Router caching and routing.
+---
+
+# Next.js Community Next.js 16 App Router Best Practices
+
+Comprehensive performance optimization guide for Next.js 16 App Router applications, maintained by the Next.js Community. Contains 42 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation. Two rules cover Next.js 16.3 preview features (Instant Navigations, Partial Prefetching), gated behind `cacheComponents` and `partialPrefetching`.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new Next.js 16 App Router code
+- Configuring caching strategies with 'use cache' directive
+- Implementing server components and data fetching
+- Setting up routing with parallel and intercepting routes
+- Creating server actions for form handling and mutations
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Build & Bundle Optimization | CRITICAL | `build-` |
+| 2 | Caching Strategy | CRITICAL | `cache-` |
+| 3 | Server Components & Data Fetching | HIGH | `server-` |
+| 4 | Routing & Navigation | HIGH | `route-` |
+| 5 | Server Actions & Mutations | MEDIUM-HIGH | `action-` |
+| 6 | Streaming & Loading States | MEDIUM | `stream-` |
+| 7 | Metadata & SEO | MEDIUM | `meta-` |
+| 8 | Client Components | LOW-MEDIUM | `client-` |
+
+## Quick Reference
+
+### 1. Build & Bundle Optimization (CRITICAL)
+
+- `build-optimize-package-imports` - Configure optimizePackageImports for Icon Libraries
+- `build-dynamic-imports` - Use Dynamic Imports for Heavy Components
+- `build-barrel-files` - Avoid Barrel File Imports in App Router
+- `build-turbopack-config` - Configure Turbopack at the top level
+- `build-external-packages` - Configure Server External Packages for Node Dependencies
+
+### 2. Caching Strategy (CRITICAL)
+
+- `cache-use-cache-directive` - Use 'use cache' with Cache Components
+- `cache-revalidate-tag` - Use revalidateTag with cacheLife Profiles
+- `cache-fetch-options` - Configure Fetch Cache Options Explicitly
+- `cache-revalidate-path` - Use revalidatePath for Route-Level Cache Invalidation
+- `cache-react-cache` - Use React cache() for Request Deduplication
+- `cache-segment-config` - Match route configuration to the active cache model
+
+### 3. Server Components & Data Fetching (HIGH)
+
+- `server-parallel-fetching` - Fetch Data in Parallel in Server Components
+- `server-component-streaming` - Stream Server Components for Progressive Loading
+- `server-data-colocation` - Colocate Data Fetching with Components
+- `server-preload-pattern` - Use Preload Pattern for Critical Data
+- `server-avoid-client-fetching` - Avoid Client-Side Data Fetching for Initial Data
+- `server-error-handling` - Handle Server Component Errors Gracefully
+
+### 4. Routing & Navigation (HIGH)
+
+- `route-parallel-routes` - Use Parallel Routes for Independent Content
+- `route-intercepting-routes` - Use Intercepting Routes for Modal Patterns
+- `route-prefetching` - Configure Link Prefetching Appropriately
+- `route-instant-navigations` - Make Navigations Instant with Stream, Cache, or Block (16.3 preview)
+- `route-partial-prefetching` - Use Partial Prefetching for Reusable Route Shells (16.3 preview)
+- `route-proxy-ts` - Use proxy.ts for Network Boundary Logic
+- `route-not-found` - Use notFound() for Missing Resources
+
+### 5. Server Actions & Mutations (MEDIUM-HIGH)
+
+- `action-server-action-forms` - Use Server Actions for Form Submissions
+- `action-pending-states` - Show Pending States with useFormStatus
+- `action-error-handling` - Handle Server Action Errors Gracefully
+- `action-optimistic-updates` - Use Optimistic Updates for Instant Feedback
+- `action-revalidation` - Revalidate Cache After Mutations
+
+### 6. Streaming & Loading States (MEDIUM)
+
+- `stream-suspense-boundaries` - Place Suspense Boundaries Strategically
+- `stream-loading-tsx` - Use loading.tsx for Route-Level Loading States
+- `stream-error-tsx` - Use error.tsx for Route-Level Error Boundaries
+- `stream-skeleton-matching` - Match Skeleton Dimensions to Actual Content
+- `stream-nested-suspense` - Nest Suspense for Progressive Disclosure
+
+### 7. Metadata & SEO (MEDIUM)
+
+- `meta-generate-metadata` - Use generateMetadata for Dynamic Metadata
+- `meta-sitemap` - Generate Sitemaps Dynamically
+- `meta-robots` - Configure Robots for Crawl Control
+- `meta-opengraph-images` - Generate Dynamic OpenGraph Images
+
+### 8. Client Components (LOW-MEDIUM)
+
+- `client-use-client-boundary` - Minimize 'use client' Boundary Scope
+- `client-children-pattern` - Pass Server Components as Children to Client Components
+- `client-hydration-mismatch` - Avoid Hydration Mismatches
+- `client-third-party-scripts` - Load Third-Party Scripts Efficiently
+
+## How to Use
+
+Run in the project root first:
+
+```bash
+npx -y @pymodel/react-frontend-skills detect # installed vs. targeted versions
+npx -y @pymodel/react-frontend-skills scan --skill nextjs # deprecated APIs → rule IDs
+```
+
+Read `references/.md` for each rule above that matches the task and for each `scan` hit: why it matters, then incorrect vs. correct code.
+
+## Related Skills
+
+- For React 19 fundamentals, see `react` skill
+- For data fetching patterns, see `tanstack-query` skill
+- For client-side forms, see `react-hook-form` skill
diff --git a/.agents/skills/nextjs/references/action-error-handling.md b/.agents/skills/nextjs/references/action-error-handling.md
new file mode 100644
index 0000000..98eba94
--- /dev/null
+++ b/.agents/skills/nextjs/references/action-error-handling.md
@@ -0,0 +1,75 @@
+---
+title: Handle Server Action Errors Gracefully
+impact: MEDIUM-HIGH
+impactDescription: prevents silent failures, better error UX
+tags: action, error-handling, validation, useActionState
+---
+
+## Handle Server Action Errors Gracefully
+
+Return error states from Server Actions instead of throwing. Use `useActionState` to manage form state and display errors.
+
+**Incorrect (unhandled errors):**
+
+```typescript
+async function createPost(formData: FormData) {
+ 'use server'
+
+ const title = formData.get('title') as string
+ await db.posts.create({ data: { title } })
+ // If validation fails or DB errors, user sees nothing
+}
+```
+
+**Correct (returning error state):**
+
+```typescript
+// actions.ts
+'use server'
+
+type ActionState = {
+ error?: string
+ success?: boolean
+}
+
+export async function createPost(
+ prevState: ActionState,
+ formData: FormData
+): Promise {
+ const title = formData.get('title') as string
+
+ if (!title || title.length < 3) {
+ return { error: 'Title must be at least 3 characters' }
+ }
+
+ try {
+ await db.posts.create({ data: { title } })
+ revalidatePath('/posts')
+ return { success: true }
+ } catch (e) {
+ return { error: 'Failed to create post. Please try again.' }
+ }
+}
+
+// page.tsx
+'use client'
+
+import { useActionState } from 'react'
+import { createPost } from './actions'
+
+export default function NewPostForm() {
+ const [state, formAction, isPending] = useActionState(createPost, {})
+
+ return (
+
+ )
+}
+```
+
+Reference: [useActionState](https://react.dev/reference/react/useActionState)
diff --git a/.agents/skills/nextjs/references/action-optimistic-updates.md b/.agents/skills/nextjs/references/action-optimistic-updates.md
new file mode 100644
index 0000000..31b1afe
--- /dev/null
+++ b/.agents/skills/nextjs/references/action-optimistic-updates.md
@@ -0,0 +1,74 @@
+---
+title: Use Optimistic Updates for Instant Feedback
+impact: MEDIUM
+impactDescription: instant UI response, better perceived performance
+tags: action, optimistic, useOptimistic, mutation
+---
+
+## Use Optimistic Updates for Instant Feedback
+
+Use `useOptimistic` to update UI immediately before the server confirms. If the action fails, React reverts to the previous state.
+
+**Incorrect (waiting for server response):**
+
+```typescript
+'use client'
+
+import { useState } from 'react'
+
+export function LikeButton({ postId, initialLikes }: { postId: string; initialLikes: number }) {
+ const [likes, setLikes] = useState(initialLikes)
+ const [isLiking, setIsLiking] = useState(false)
+
+ async function handleLike() {
+ setIsLiking(true)
+ const newLikes = await likePost(postId) // Wait for server
+ setLikes(newLikes)
+ setIsLiking(false)
+ }
+
+ return (
+
+ {likes} {isLiking ? '...' : '❤️'}
+
+ )
+}
+// UI updates only after the server round trip.
+```
+
+**Correct (optimistic update):**
+
+```typescript
+'use client'
+
+import { useOptimistic } from 'react'
+import { likePost } from './actions'
+
+export function LikeButton({ postId, initialLikes }: { postId: string; initialLikes: number }) {
+ const [optimisticLikes, addOptimisticLike] = useOptimistic(
+ initialLikes,
+ (state, _) => state + 1
+ )
+
+ async function handleLike() {
+ addOptimisticLike(null) // Instant UI update
+ await likePost(postId) // Server update in background
+ // If fails, React reverts automatically
+ }
+
+ return (
+
+ )
+}
+// Instant feedback, reverts on failure
+```
+
+**When to use:**
+- Like/vote buttons
+- Adding items to cart
+- Toggling favorites
+- Any action where instant feedback improves UX
diff --git a/.agents/skills/nextjs/references/action-pending-states.md b/.agents/skills/nextjs/references/action-pending-states.md
new file mode 100644
index 0000000..9cea961
--- /dev/null
+++ b/.agents/skills/nextjs/references/action-pending-states.md
@@ -0,0 +1,68 @@
+---
+title: Show Pending States with useFormStatus
+impact: MEDIUM-HIGH
+impactDescription: better UX during form submission
+tags: action, useFormStatus, pending, loading
+---
+
+## Show Pending States with useFormStatus
+
+Use `useFormStatus` to show loading indicators and disable buttons during form submission. This provides immediate feedback to users.
+
+**Incorrect (no feedback during submission):**
+
+```typescript
+// app/posts/new/page.tsx
+export default function NewPostPage() {
+ async function createPost(formData: FormData) {
+ 'use server'
+ await db.posts.create({ data: { title: formData.get('title') } })
+ }
+
+ return (
+
+ )
+}
+```
+
+**Correct (pending state with useFormStatus):**
+
+```typescript
+// app/posts/new/page.tsx
+import { SubmitButton } from './submit-button'
+
+export default function NewPostPage() {
+ async function createPost(formData: FormData) {
+ 'use server'
+ await db.posts.create({ data: { title: formData.get('title') } })
+ }
+
+ return (
+
+ )
+}
+
+// submit-button.tsx
+'use client'
+
+import { useFormStatus } from 'react-dom'
+
+export function SubmitButton() {
+ const { pending } = useFormStatus()
+
+ return (
+
+ {pending ? 'Creating...' : 'Create Post'}
+
+ )
+}
+```
+
+**Note:** `useFormStatus` must be used in a child component of the form, not in the same component as the form element.
diff --git a/.agents/skills/nextjs/references/action-revalidation.md b/.agents/skills/nextjs/references/action-revalidation.md
new file mode 100644
index 0000000..ad7b791
--- /dev/null
+++ b/.agents/skills/nextjs/references/action-revalidation.md
@@ -0,0 +1,78 @@
+---
+title: Revalidate Cache After Mutations
+impact: MEDIUM
+impactDescription: ensures fresh data after changes
+tags: action, revalidation, cache, mutation
+---
+
+## Revalidate Cache After Mutations
+
+After a mutation, invalidate only cached reads affected by the write. Use `revalidatePath` for route-level invalidation, `revalidateTag(tag, 'max')` for stale-while-revalidate content, or `updateTag(tag)` inside a Server Action for immediate read-your-writes behavior.
+
+**Incorrect (stale cache after mutation):**
+
+```typescript
+'use server'
+
+export async function deletePost(postId: string) {
+ await db.posts.delete({ where: { id: postId } })
+ redirect('/posts')
+ // Posts list still shows deleted post from cache!
+}
+```
+
+**Correct (invalidating cache):**
+
+```typescript
+'use server'
+
+import { revalidatePath, revalidateTag, updateTag } from 'next/cache'
+import { redirect } from 'next/navigation'
+
+export async function deletePost(postId: string) {
+ await db.posts.delete({ where: { id: postId } })
+
+ // Option 1: Revalidate specific path
+ revalidatePath('/posts')
+
+ // Option 2: expire and immediately refresh for this user's write
+ updateTag('posts')
+
+ redirect('/posts')
+}
+
+export async function updatePost(postId: string, formData: FormData) {
+ await db.posts.update({
+ where: { id: postId },
+ data: { title: formData.get('title') }
+ })
+
+ // Revalidate both the list and detail pages
+ revalidatePath('/posts')
+ revalidatePath(`/posts/${postId}`)
+}
+```
+
+**Revalidation strategies:**
+
+```typescript
+// Specific route
+revalidatePath('/posts')
+
+// Dynamic route with specific ID
+revalidatePath(`/posts/${postId}`)
+
+// All routes using a layout
+revalidatePath('/dashboard', 'layout')
+
+// Stale-while-revalidate for webhook/content updates
+revalidateTag('posts', 'max')
+
+// Immediate read-your-writes in a Server Action
+updateTag('posts')
+updateTag(`post-${postId}`)
+```
+
+`updateTag` requires `cacheComponents: true` and can only be called from a Server Action. In Route Handlers and webhooks use `revalidateTag(tag, 'max')` instead.
+
+Reference: [Next.js updating cached data](https://nextjs.org/docs/app/getting-started/caching-and-revalidating#updating-data)
diff --git a/.agents/skills/nextjs/references/action-server-action-forms.md b/.agents/skills/nextjs/references/action-server-action-forms.md
new file mode 100644
index 0000000..13d1655
--- /dev/null
+++ b/.agents/skills/nextjs/references/action-server-action-forms.md
@@ -0,0 +1,75 @@
+---
+title: Use Server Actions for Form Submissions
+impact: MEDIUM-HIGH
+impactDescription: eliminates API routes, type-safe mutations
+tags: action, server-action, form, mutation
+---
+
+## Use Server Actions for Form Submissions
+
+Server Actions handle form submissions directly without creating API routes. They're type-safe, progressively enhanced, and integrate with caching.
+
+**Incorrect (API route for form handling):**
+
+```typescript
+// app/api/posts/route.ts
+export async function POST(request: Request) {
+ const data = await request.json()
+ const post = await db.posts.create({ data })
+ return Response.json(post)
+}
+
+// app/posts/new/page.tsx
+'use client'
+
+export default function NewPostPage() {
+ const handleSubmit = async (e) => {
+ e.preventDefault()
+ const formData = new FormData(e.target)
+ await fetch('/api/posts', {
+ method: 'POST',
+ body: JSON.stringify(Object.fromEntries(formData))
+ })
+ }
+ // Requires client component, manual fetch, no type safety
+}
+```
+
+**Correct (Server Action):**
+
+```typescript
+// app/posts/new/page.tsx
+import { redirect } from 'next/navigation'
+import { revalidatePath } from 'next/cache'
+
+export default function NewPostPage() {
+ async function createPost(formData: FormData) {
+ 'use server'
+
+ const title = formData.get('title') as string
+ const content = formData.get('content') as string
+
+ const post = await db.posts.create({
+ data: { title, content }
+ })
+
+ revalidatePath('/posts')
+ redirect(`/posts/${post.id}`)
+ }
+
+ return (
+
+ )
+}
+// Works without JS, type-safe, integrated caching
+```
+
+**Benefits:**
+- Progressive enhancement (works without JavaScript)
+- Type-safe with TypeScript
+- Direct cache invalidation
+- No API route boilerplate
diff --git a/.agents/skills/nextjs/references/build-barrel-files.md b/.agents/skills/nextjs/references/build-barrel-files.md
new file mode 100644
index 0000000..2a7dcd0
--- /dev/null
+++ b/.agents/skills/nextjs/references/build-barrel-files.md
@@ -0,0 +1,50 @@
+---
+title: Avoid Barrel File Imports in App Router
+impact: CRITICAL
+impactDescription: 2-10× faster dev startup
+tags: build, imports, barrel-files, tree-shaking
+---
+
+## Avoid Barrel File Imports in App Router
+
+Barrel files (index.ts with re-exports) prevent tree-shaking and slow down development. Import directly from source files instead.
+
+**Incorrect (imports through barrel file):**
+
+```typescript
+// lib/utils/index.ts (barrel file)
+export * from './formatDate'
+export * from './formatCurrency'
+export * from './validateEmail'
+// ... 50 more exports
+
+// app/dashboard/page.tsx
+import { formatDate } from '@/lib/utils'
+// Loads all 50+ modules even though only formatDate is used
+```
+
+**Correct (direct import):**
+
+```typescript
+// app/dashboard/page.tsx
+import { formatDate } from '@/lib/utils/formatDate'
+// Loads only the formatDate module
+```
+
+**Alternative (path aliases):**
+
+```typescript
+// tsconfig.json
+{
+ "compilerOptions": {
+ "paths": {
+ "@/utils/*": ["./lib/utils/*"]
+ }
+ }
+}
+
+// app/dashboard/page.tsx
+import { formatDate } from '@/utils/formatDate'
+```
+
+**Note:** If you must use barrel files, configure `optimizePackageImports` or use explicit named exports instead of `export *`.
diff --git a/.agents/skills/nextjs/references/build-dynamic-imports.md b/.agents/skills/nextjs/references/build-dynamic-imports.md
new file mode 100644
index 0000000..3a2156d
--- /dev/null
+++ b/.agents/skills/nextjs/references/build-dynamic-imports.md
@@ -0,0 +1,62 @@
+---
+title: Use Dynamic Imports for Heavy Components
+impact: CRITICAL
+impactDescription: 30-70% smaller initial bundle
+tags: build, dynamic-import, code-splitting, lazy-loading
+---
+
+## Use Dynamic Imports for Heavy Components
+
+Large components like charts, editors, or maps should load on demand. Use `next/dynamic` to split them into separate bundles that load only when rendered.
+
+**Incorrect (always included in main bundle):**
+
+```typescript
+import HeavyChart from '@/components/HeavyChart'
+import CodeEditor from '@/components/CodeEditor'
+
+export default function Dashboard() {
+ const [showChart, setShowChart] = useState(false)
+
+ return (
+
+ {showChart && }
+
+
+ )
+}
+// Both components in initial bundle (~500KB added)
+```
+
+**Correct (loaded on demand):**
+
+```typescript
+'use client' // ssr: false is not allowed in Server Components
+
+import { useState } from 'react'
+import dynamic from 'next/dynamic'
+
+const HeavyChart = dynamic(() => import('@/components/HeavyChart'), {
+ loading: () =>
+})
+
+const CodeEditor = dynamic(() => import('@/components/CodeEditor'), {
+ ssr: false // Client-only component
+})
+
+export default function Dashboard() {
+ const [showChart, setShowChart] = useState(false)
+
+ return (
+
+ {showChart && }
+
+
+ )
+}
+// Components loaded only when rendered
+```
+
+**When to use `ssr: false`:** For libraries that touch `window` or `document` when imported, or when you also want the code split out of the server bundle. It only works from a Client Component. For a component that merely reads browser APIs while rendering, React 19.3's `use(browser())` inside `` skips its server render without a dynamic import (see the react skill's `effect-use-browser-only`).
+
+Reference: [Dynamic Imports](https://nextjs.org/docs/app/building-your-application/optimizing/lazy-loading)
diff --git a/.agents/skills/nextjs/references/build-external-packages.md b/.agents/skills/nextjs/references/build-external-packages.md
new file mode 100644
index 0000000..a48d386
--- /dev/null
+++ b/.agents/skills/nextjs/references/build-external-packages.md
@@ -0,0 +1,48 @@
+---
+title: Configure Server External Packages for Node Dependencies
+impact: HIGH
+impactDescription: prevents bundling issues, faster builds
+tags: build, external-packages, node-modules, server
+---
+
+## Configure Server External Packages for Node Dependencies
+
+Some Node.js packages with native bindings or complex dependencies should not be bundled. Use `serverExternalPackages` to exclude them from the server bundle.
+
+**Incorrect (bundling native modules):**
+
+```typescript
+// next.config.ts
+const nextConfig = {
+ // No external packages configured
+}
+
+// lib/pdf.ts
+import puppeteer from 'puppeteer'
+// Build fails or produces oversized bundles
+```
+
+**Correct (excluding native modules):**
+
+```typescript
+// next.config.ts
+const nextConfig = {
+ serverExternalPackages: [
+ 'puppeteer',
+ 'sharp',
+ 'canvas',
+ '@prisma/client',
+ 'bcrypt'
+ ]
+}
+
+// lib/pdf.ts
+import puppeteer from 'puppeteer'
+// Loaded at runtime from node_modules
+```
+
+**Common packages to externalize:**
+- Database drivers: `@prisma/client`, `pg`, `mysql2`
+- Image processing: `sharp`, `canvas`
+- Native bindings: `bcrypt`, `argon2`
+- Browser automation: `puppeteer`, `playwright`
diff --git a/.agents/skills/nextjs/references/build-optimize-package-imports.md b/.agents/skills/nextjs/references/build-optimize-package-imports.md
new file mode 100644
index 0000000..7a5e01a
--- /dev/null
+++ b/.agents/skills/nextjs/references/build-optimize-package-imports.md
@@ -0,0 +1,42 @@
+---
+title: Configure optimizePackageImports for Icon Libraries
+impact: CRITICAL
+impactDescription: 200-800ms faster imports, 50-80% smaller bundles
+tags: build, imports, tree-shaking, icons, turbopack
+---
+
+## Configure optimizePackageImports for Icon Libraries
+
+Icon libraries like `lucide-react` export hundreds of modules. Without optimization, importing one icon loads the entire library. Configure `optimizePackageImports` to automatically tree-shake unused exports.
+
+**Incorrect (loads entire library):**
+
+```typescript
+// next.config.ts
+const nextConfig = {
+ // No optimization configured
+}
+
+// components/Header.tsx
+import { Menu, X, Search } from 'lucide-react'
+// Loads 1,583 modules, adds ~2.8s to dev startup
+```
+
+**Correct (loads only used icons):**
+
+```typescript
+// next.config.ts
+const nextConfig = {
+ experimental: {
+ optimizePackageImports: ['lucide-react', '@heroicons/react', '@mui/icons-material']
+ }
+}
+
+// components/Header.tsx
+import { Menu, X, Search } from 'lucide-react'
+// Loads only 3 modules (~2KB vs ~1MB)
+```
+
+**Note:** Next.js 16 automatically optimizes common libraries. Add custom libraries that export many modules.
+
+Reference: [How we optimized package imports in Next.js](https://vercel.com/blog/how-we-optimized-package-imports-in-next-js)
diff --git a/.agents/skills/nextjs/references/build-turbopack-config.md b/.agents/skills/nextjs/references/build-turbopack-config.md
new file mode 100644
index 0000000..c8a52eb
--- /dev/null
+++ b/.agents/skills/nextjs/references/build-turbopack-config.md
@@ -0,0 +1,71 @@
+---
+title: Configure Turbopack at the Top Level
+impact: CRITICAL
+impactDescription: uses the supported Next.js 16 bundler and cache configuration
+tags: build, turbopack, caching, development
+---
+
+## Configure Turbopack at the Top Level
+
+Next.js 16 uses Turbopack by default for both `next dev` and `next build`. Turbopack filesystem caching is also enabled by default for development and production builds. Do not add an opt-in flag merely to obtain the default behavior.
+
+**Incorrect (removed or fictitious options):**
+
+```typescript
+const nextConfig = {
+ experimental: {
+ turbo: {
+ persistentCaching: true,
+ },
+ },
+}
+```
+
+**Correct (only configure supported custom behavior):**
+
+```typescript
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+ turbopack: {
+ rules: {
+ '*.svg': {
+ loaders: ['@svgr/webpack'],
+ as: '*.js',
+ },
+ },
+ },
+}
+
+export default nextConfig
+```
+
+```bash
+# Turbopack is the default in Next.js 16.
+next dev
+next build
+
+# Use Webpack only when an unresolved compatibility requirement demands it.
+next build --webpack
+```
+
+A custom `webpack` configuration makes the default `next build` fail rather than silently ignoring that configuration. Migrate the configuration, explicitly choose `--webpack`, or deliberately use `--turbopack` after confirming the Webpack customization is unnecessary.
+
+The filesystem cache is local build output and must remain uncommitted. In Next.js 16.3+, both caches default to `true`. Set the documented experimental keys only to override those defaults for a demonstrated environment-specific reason:
+
+```typescript
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+ experimental: {
+ turbopackFileSystemCacheForDev: false,
+ turbopackFileSystemCacheForBuild: false,
+ },
+}
+
+export default nextConfig
+```
+
+References:
+- [Next.js 16 upgrade guide](https://nextjs.org/docs/app/guides/upgrading/version-16#turbopack-by-default)
+- [Turbopack filesystem cache](https://nextjs.org/docs/app/api-reference/config/next-config-js/turbopackFileSystemCache)
diff --git a/.agents/skills/nextjs/references/cache-fetch-options.md b/.agents/skills/nextjs/references/cache-fetch-options.md
new file mode 100644
index 0000000..c940217
--- /dev/null
+++ b/.agents/skills/nextjs/references/cache-fetch-options.md
@@ -0,0 +1,53 @@
+---
+title: Configure Fetch Cache Options Explicitly
+impact: HIGH
+impactDescription: makes runtime freshness and revalidation behavior deliberate
+tags: cache, fetch, revalidate, data-fetching
+---
+
+## Configure Fetch Cache Options Explicitly
+
+In Next.js 15 and 16, a server `fetch()` without an explicit cache policy is not cached at runtime. Build-time prerendering may still reuse it during the build. State the intended policy instead of relying on older defaults.
+
+**Incorrect (assuming an implicit runtime cache):**
+
+```typescript
+export async function getProducts() {
+ // This is fresh at runtime in Next.js 15 and 16; it is not an implicit
+ // persistent cache entry.
+ return fetch('https://api.example.com/products')
+}
+```
+
+**Correct (policies match each data contract):**
+
+```typescript
+export default async function Page() {
+ const config = await fetch('https://api.example.com/config', {
+ cache: 'force-cache',
+ })
+
+ const user = await fetch(`https://api.example.com/users/${userId}`, {
+ cache: 'no-store',
+ })
+
+ const products = await fetch('https://api.example.com/products', {
+ next: { revalidate: 300 },
+ })
+
+ const posts = await fetch('https://api.example.com/posts', {
+ next: { tags: ['posts'] },
+ })
+}
+```
+
+Choose from the data contract:
+
+- Request-specific, authorization-dependent, or real-time data: `cache: 'no-store'`.
+- Reusable immutable data: `cache: 'force-cache'`.
+- Reusable data with a bounded freshness window: `next: { revalidate: seconds }`.
+- Reusable data requiring on-demand invalidation: attach `next.tags` and use the matching invalidation API.
+
+Do not cache personalized responses under a key shared by users. Also distinguish the persistent Data Cache from request memoization: identical GET fetches can be deduplicated during one server render without becoming cross-request cached data.
+
+Reference: [Next.js fetch API](https://nextjs.org/docs/app/api-reference/functions/fetch)
diff --git a/.agents/skills/nextjs/references/cache-react-cache.md b/.agents/skills/nextjs/references/cache-react-cache.md
new file mode 100644
index 0000000..6331c49
--- /dev/null
+++ b/.agents/skills/nextjs/references/cache-react-cache.md
@@ -0,0 +1,58 @@
+---
+title: Use React cache() for Request Deduplication
+impact: HIGH
+impactDescription: eliminates duplicate fetches per request
+tags: cache, react-cache, deduplication, server-components
+---
+
+## Use React cache() for Request Deduplication
+
+Wrap data fetching functions with `cache()` to deduplicate identical calls within a single render pass. Multiple components can call the same function without triggering multiple fetches.
+
+**Incorrect (duplicate fetches):**
+
+```typescript
+// lib/data.ts
+export async function getUser(id: string) {
+ const res = await fetch(`/api/users/${id}`)
+ return res.json()
+}
+
+// components/Header.tsx
+export async function Header({ userId }: { userId: string }) {
+ const user = await getUser(userId) // Fetch #1
+ return Welcome, {user.name}
+}
+
+// components/Sidebar.tsx
+export async function Sidebar({ userId }: { userId: string }) {
+ const user = await getUser(userId) // Fetch #2 - duplicate!
+ return {user.role === 'admin' && }
+}
+```
+
+**Correct (deduplicated with cache):**
+
+```typescript
+// lib/data.ts
+import { cache } from 'react'
+
+export const getUser = cache(async (id: string) => {
+ const res = await fetch(`/api/users/${id}`)
+ return res.json()
+})
+
+// components/Header.tsx
+export async function Header({ userId }: { userId: string }) {
+ const user = await getUser(userId) // Fetch
+ return Welcome, {user.name}
+}
+
+// components/Sidebar.tsx
+export async function Sidebar({ userId }: { userId: string }) {
+ const user = await getUser(userId) // Cached result reused
+ return {user.role === 'admin' && }
+}
+```
+
+**Note:** React `cache()` deduplicates within a single request. For cross-request caching, use `unstable_cache` or the `'use cache'` directive.
diff --git a/.agents/skills/nextjs/references/cache-revalidate-path.md b/.agents/skills/nextjs/references/cache-revalidate-path.md
new file mode 100644
index 0000000..27ae2bf
--- /dev/null
+++ b/.agents/skills/nextjs/references/cache-revalidate-path.md
@@ -0,0 +1,62 @@
+---
+title: Use revalidatePath for Route-Level Cache Invalidation
+impact: HIGH
+impactDescription: invalidates all cached data for a route
+tags: cache, revalidate-path, invalidation, server-actions
+---
+
+## Use revalidatePath for Route-Level Cache Invalidation
+
+Use `revalidatePath` to invalidate all cached data associated with a specific route. Prefer `revalidateTag` for granular control.
+
+**Incorrect (forgetting to revalidate after mutation):**
+
+```typescript
+'use server'
+
+export async function createPost(formData: FormData) {
+ const title = formData.get('title') as string
+ const content = formData.get('content') as string
+
+ await db.posts.create({ data: { title, content } })
+
+ // User doesn't see new post until cache expires!
+}
+```
+
+**Correct (revalidating after mutation):**
+
+```typescript
+'use server'
+
+import { revalidatePath } from 'next/cache'
+import { redirect } from 'next/navigation'
+
+export async function createPost(formData: FormData) {
+ const title = formData.get('title') as string
+ const content = formData.get('content') as string
+
+ const post = await db.posts.create({ data: { title, content } })
+
+ revalidatePath('/posts') // Invalidate posts list
+ redirect(`/posts/${post.id}`) // Navigate to new post
+}
+```
+
+**Path patterns:**
+
+```typescript
+// Specific route
+revalidatePath('/posts')
+
+// Dynamic route
+revalidatePath('/posts/[slug]', 'page')
+
+// Layout and all child routes
+revalidatePath('/dashboard', 'layout')
+
+// Entire app (use sparingly)
+revalidatePath('/', 'layout')
+```
+
+**Note:** `redirect` must be called after `revalidatePath` as it throws internally.
diff --git a/.agents/skills/nextjs/references/cache-revalidate-tag.md b/.agents/skills/nextjs/references/cache-revalidate-tag.md
new file mode 100644
index 0000000..80227f8
--- /dev/null
+++ b/.agents/skills/nextjs/references/cache-revalidate-tag.md
@@ -0,0 +1,65 @@
+---
+title: Use revalidateTag with cacheLife Profiles
+impact: CRITICAL
+impactDescription: stale-while-revalidate behavior, instant updates
+tags: cache, revalidate-tag, cache-life, invalidation
+---
+
+## Use revalidateTag with cacheLife Profiles
+
+Next.js 16 deprecates the single-argument `revalidateTag(tag)` form and reports it as a TypeScript error. Pass a cache-life profile such as `'max'` for stale-while-revalidate behavior, or choose `updateTag()` in a Server Action when the current user must immediately read their own write.
+
+**Incorrect (old revalidateTag API):**
+
+```typescript
+// app/actions.ts
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function updateProduct(id: string, data: FormData) {
+ await db.products.update({ where: { id }, data })
+
+ // Deprecated single-argument API; fails current Next.js type checking.
+ revalidateTag('products')
+}
+```
+
+**Correct (revalidateTag with cacheLife):**
+
+```typescript
+// app/actions.ts
+'use server'
+
+import { revalidateTag } from 'next/cache'
+
+export async function updateProduct(id: string, data: FormData) {
+ await db.products.update({ where: { id }, data })
+
+ // Recommended: 'max' enables stale-while-revalidate
+ revalidateTag('products', 'max')
+}
+
+// 'max' (recommended): serve cached data immediately and refresh in the
+// background the next time the tag is visited (stale-while-revalidate)
+// Built-in cacheLife profiles: 'max', 'hours', 'days', 'weeks'
+// For immediate read-your-writes updates use updateTag(tag) in a Server Action,
+// or revalidateTag(tag, { expire: 0 }) for webhooks needing instant expiry
+```
+
+**Tagging cached data:**
+
+```typescript
+// lib/data.ts
+'use cache'
+
+import { cacheTag } from 'next/cache'
+
+export async function getProducts() {
+ cacheTag('products')
+ const res = await fetch('https://api.store.com/products')
+ return res.json()
+}
+```
+
+Reference: [Next.js revalidateTag](https://nextjs.org/docs/app/api-reference/functions/revalidateTag)
diff --git a/.agents/skills/nextjs/references/cache-segment-config.md b/.agents/skills/nextjs/references/cache-segment-config.md
new file mode 100644
index 0000000..fdd669d
--- /dev/null
+++ b/.agents/skills/nextjs/references/cache-segment-config.md
@@ -0,0 +1,63 @@
+---
+title: Match Route Configuration to the Active Cache Model
+impact: MEDIUM-HIGH
+impactDescription: avoids mixing incompatible Cache Components and legacy segment options
+tags: cache, segment-config, dynamic, revalidate, cache-components
+---
+
+## Match Route Configuration to the Active Cache Model
+
+Next.js 16 supports two caching models. First determine whether `cacheComponents: true` is enabled.
+
+### Cache Components enabled
+
+Use `'use cache'`, `cacheLife()`, `cacheTag()`, ``, and request-time APIs. Exporting `dynamic`, `revalidate`, `fetchCache`, `dynamicParams`, `runtime`, or `experimental_ppr` from a page, layout, or route is a build error when `cacheComponents` is enabled. Remove them rather than layering them onto the new model.
+
+**Incorrect (legacy segment exports under Cache Components):**
+
+```typescript
+// app/about/page.tsx
+export const dynamic = 'force-static'
+export const revalidate = 86400
+```
+
+**Correct (Cache Components model):**
+
+```typescript
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = { cacheComponents: true }
+export default nextConfig
+```
+
+```typescript
+// app/about/page.tsx
+import { cacheLife } from 'next/cache'
+
+export default async function AboutPage() {
+ 'use cache'
+ cacheLife('days')
+
+ const team = await getTeam()
+ return
+}
+```
+
+### Cache Components disabled (previous model)
+
+Route segment configuration remains available. Use it only when the whole segment genuinely shares that rendering policy; prefer per-fetch controls for mixed data.
+
+```typescript
+export const dynamic = 'force-static'
+export const revalidate = 86400
+
+export default async function AboutPage() {
+ const team = await getTeam()
+ return
+}
+```
+
+For request-specific routes in the previous model, use `dynamic = 'force-dynamic'` or explicit uncached fetches. `generateStaticParams()` controls which dynamic route parameters are generated; it is not itself a cache invalidation API.
+
+Reference: [Next.js route segment config](https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config)
diff --git a/.agents/skills/nextjs/references/cache-use-cache-directive.md b/.agents/skills/nextjs/references/cache-use-cache-directive.md
new file mode 100644
index 0000000..991bc79
--- /dev/null
+++ b/.agents/skills/nextjs/references/cache-use-cache-directive.md
@@ -0,0 +1,57 @@
+---
+title: Use 'use cache' with Cache Components
+impact: CRITICAL
+impactDescription: opts stable work into the Next.js 16 Cache Components model
+tags: cache, use-cache, directive, data-fetching, cache-components
+---
+
+## Use 'use cache' with Cache Components
+
+The `'use cache'` directive is part of Next.js 16 Cache Components. Enable the model with top-level `cacheComponents: true`, then place the directive at file, component, or function scope for work whose inputs and outputs are serializable and safe to reuse.
+
+**Incorrect (reading request-time data inside a cached scope):**
+
+```typescript
+import { cookies } from 'next/headers'
+
+export async function getDashboard() {
+ 'use cache'
+ const userId = (await cookies()).get('userId')?.value
+ return getDashboardForUser(userId)
+}
+```
+
+Request-time APIs cannot be called inside a cached scope, and caching personalized output under shared arguments can leak data.
+
+**Correct (enable Cache Components and cache stable inputs):**
+
+```typescript
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = { cacheComponents: true }
+export default nextConfig
+```
+
+```typescript
+// lib/data.ts
+import { cacheLife, cacheTag } from 'next/cache'
+
+export async function getProducts() {
+ 'use cache'
+ cacheLife('hours')
+ cacheTag('products')
+
+ const response = await fetch('https://api.store.com/products')
+ if (!response.ok) throw new Error('Failed to load products')
+ return response.json()
+}
+```
+
+Without `'use cache'`, runtime fetches remain fresh by default. With it, the cached function follows its cache-life profile and can be invalidated through its tags; it is not necessarily cached forever.
+
+Do not read request-time values such as `cookies()`, `headers()`, or `searchParams` inside a cached scope. Read them outside and pass only the minimal serializable value as an argument. Do not cache personalized data under shared arguments.
+
+If `cacheComponents` is not enabled, follow the previous caching model (`fetch` cache options and, where needed, `unstable_cache`) rather than copying `'use cache'` into the app. Enabling Cache Components is a model change, not a rename-only migration.
+
+Reference: [Next.js Cache Components](https://nextjs.org/docs/app/getting-started/cache-components)
diff --git a/.agents/skills/nextjs/references/client-children-pattern.md b/.agents/skills/nextjs/references/client-children-pattern.md
new file mode 100644
index 0000000..3125c4d
--- /dev/null
+++ b/.agents/skills/nextjs/references/client-children-pattern.md
@@ -0,0 +1,75 @@
+---
+title: Pass Server Components as Children to Client Components
+impact: LOW-MEDIUM
+impactDescription: keeps static content on server, reduces bundle
+tags: client, children, composition, server-components
+---
+
+## Pass Server Components as Children to Client Components
+
+Client Components can render Server Components passed as children. This keeps static content server-rendered while adding interactivity.
+
+**Incorrect (converting children to Client Components):**
+
+```typescript
+// components/Modal.tsx
+'use client'
+
+import { ProductDetails } from './ProductDetails' // Forces this to be client
+
+export function Modal({ productId }) {
+ const [isOpen, setIsOpen] = useState(false)
+
+ return (
+ <>
+ setIsOpen(true)}>View Details
+ {isOpen && (
+
+
{/* Now client-rendered */}
+
+ )}
+ >
+ )
+}
+```
+
+**Correct (children pattern keeps server content):**
+
+```typescript
+// components/Modal.tsx
+'use client'
+
+import { ReactNode, useState } from 'react'
+
+export function Modal({ children, trigger }: { children: ReactNode; trigger: string }) {
+ const [isOpen, setIsOpen] = useState(false)
+
+ return (
+ <>
+ setIsOpen(true)}>{trigger}
+ {isOpen && (
+
+ setIsOpen(false)}>Close
+ {children} {/* Server Component passed as children */}
+
+ )}
+ >
+ )
+}
+
+// app/product/[id]/page.tsx (Server Component)
+export default async function ProductPage({ params }) {
+ const product = await getProduct(params.id)
+
+ return (
+
+ {/* Stays server-rendered */}
+
+ )
+}
+```
+
+**Benefits:**
+- `ProductDetails` remains a Server Component
+- Data fetching happens on server
+- Only Modal interactivity ships to client
diff --git a/.agents/skills/nextjs/references/client-hydration-mismatch.md b/.agents/skills/nextjs/references/client-hydration-mismatch.md
new file mode 100644
index 0000000..40718b4
--- /dev/null
+++ b/.agents/skills/nextjs/references/client-hydration-mismatch.md
@@ -0,0 +1,101 @@
+---
+title: Avoid Hydration Mismatches
+impact: LOW-MEDIUM
+impactDescription: prevents React warnings, ensures correct rendering
+tags: client, hydration, mismatch, ssr
+---
+
+## Avoid Hydration Mismatches
+
+Server and client must render identical HTML. Avoid browser-only APIs, timestamps, and random values during initial render.
+
+**Incorrect (hydration mismatch):**
+
+```typescript
+'use client'
+
+export function Greeting() {
+ // Different on server vs client
+ const time = new Date().toLocaleTimeString()
+
+ return Current time: {time}
+}
+// Server renders "10:30:00", client hydrates with "10:30:01" → mismatch!
+```
+
+**Correct (defer client-only values):**
+
+```typescript
+'use client'
+
+import { useState, useEffect } from 'react'
+
+export function Greeting() {
+ const [time, setTime] = useState(null)
+
+ useEffect(() => {
+ setTime(new Date().toLocaleTimeString())
+ const interval = setInterval(() => {
+ setTime(new Date().toLocaleTimeString())
+ }, 1000)
+ return () => clearInterval(interval)
+ }, [])
+
+ // Render nothing or placeholder on server
+ if (!time) return Loading time...
+
+ return Current time: {time}
+}
+```
+
+**Correct (React 19.3+: skip server rendering for the component):**
+
+```typescript
+'use client'
+
+import { Suspense, use, useEffect, useState } from 'react'
+import { browser } from 'react-dom'
+
+function Clock() {
+ use(browser('shows the user local time')) // server renders the fallback
+ const [time, setTime] = useState(() => new Date().toLocaleTimeString())
+
+ useEffect(() => {
+ const interval = setInterval(() => setTime(new Date().toLocaleTimeString()), 1000)
+ return () => clearInterval(interval)
+ }, [])
+
+ return Current time: {time}
+}
+
+export function Greeting() {
+ return (
+ Loading time... }>
+
+
+ )
+}
+```
+
+This drops the `null` state and the extra render. The effect remains only for the interval. See the react skill's `effect-use-browser-only`.
+
+**Alternative (suppressHydrationWarning for known differences):**
+
+```typescript
+'use client'
+
+export function Timestamp() {
+ return (
+
+ {new Date().toLocaleTimeString()}
+
+ )
+}
+// Use sparingly - only when mismatch is intentional
+```
+
+**Common causes:**
+- `Date.now()`, `Math.random()`
+- `window.innerWidth`, `navigator.userAgent`
+- Browser extensions modifying HTML
+- Different locales on server/client
diff --git a/.agents/skills/nextjs/references/client-third-party-scripts.md b/.agents/skills/nextjs/references/client-third-party-scripts.md
new file mode 100644
index 0000000..fa1a839
--- /dev/null
+++ b/.agents/skills/nextjs/references/client-third-party-scripts.md
@@ -0,0 +1,67 @@
+---
+title: Load Third-Party Scripts Efficiently
+impact: LOW-MEDIUM
+impactDescription: prevents blocking, improves LCP
+tags: client, scripts, third-party, performance
+---
+
+## Load Third-Party Scripts Efficiently
+
+Use `next/script` for third-party scripts with appropriate loading strategies. Avoid blocking the main thread with synchronous scripts.
+
+**Incorrect (blocking script in head):**
+
+```typescript
+// app/layout.tsx
+export default function RootLayout({ children }) {
+ return (
+
+
+
+ {/* Blocks rendering until script loads */}
+
+ {children}
+
+ )
+}
+```
+
+**Correct (next/script with strategy):**
+
+```typescript
+// app/layout.tsx
+import Script from 'next/script'
+
+export default function RootLayout({ children }) {
+ return (
+
+
+ {children}
+
+ {/* Analytics - load after page is interactive */}
+
+
+ {/* Chat widget - load when idle */}
+
+
+ {/* Rare critical bootstrap that must run before hydration */}
+
+
+
+ )
+}
+```
+
+**Strategy guide:**
+- `beforeInteractive` - Critical scripts (rare)
+- `afterInteractive` - Analytics, tracking (default)
+- `lazyOnload` - Chat widgets, social buttons
+- `worker` - Experimental and version/router constrained; verify support in the installed Next.js docs
diff --git a/.agents/skills/nextjs/references/client-use-client-boundary.md b/.agents/skills/nextjs/references/client-use-client-boundary.md
new file mode 100644
index 0000000..a03d79a
--- /dev/null
+++ b/.agents/skills/nextjs/references/client-use-client-boundary.md
@@ -0,0 +1,72 @@
+---
+title: Minimize 'use client' Boundary Scope
+impact: LOW-MEDIUM
+impactDescription: reduces client JS, better performance
+tags: client, use-client, boundary, hydration
+---
+
+## Minimize 'use client' Boundary Scope
+
+Keep `'use client'` boundaries as small as possible. Only the interactive parts need to be Client Components.
+
+**Incorrect (entire page as Client Component):**
+
+```typescript
+'use client'
+
+export default function ProductPage({ product }) {
+ const [quantity, setQuantity] = useState(1)
+
+ return (
+
+
{product.name}
+
{product.description}
{/* Static, doesn't need client */}
+
{/* Static, doesn't need client */}
+
{/* Static, doesn't need client */}
+
+ {/* Only this needs interactivity */}
+
setQuantity(+e.target.value)} />
+
addToCart(product.id, quantity)}>Add to Cart
+
+ )
+}
+// Entire page hydrates on client
+```
+
+**Correct (minimal Client Component):**
+
+```typescript
+// app/product/[id]/page.tsx (Server Component)
+export default async function ProductPage({ params }) {
+ const product = await getProduct(params.id)
+
+ return (
+
+
{product.name}
+
{product.description}
+
+
+
+ {/* Only interactive part is client */}
+
+
+ )
+}
+
+// components/AddToCartButton.tsx
+'use client'
+
+import { useState } from 'react'
+
+export function AddToCartButton({ productId }: { productId: string }) {
+ const [quantity, setQuantity] = useState(1)
+
+ return (
+
+ setQuantity(+e.target.value)} />
+ addToCart(productId, quantity)}>Add to Cart
+
+ )
+}
+// Only button hydrates, rest is static HTML
+```
diff --git a/.agents/skills/nextjs/references/meta-generate-metadata.md b/.agents/skills/nextjs/references/meta-generate-metadata.md
new file mode 100644
index 0000000..86c78af
--- /dev/null
+++ b/.agents/skills/nextjs/references/meta-generate-metadata.md
@@ -0,0 +1,70 @@
+---
+title: Use generateMetadata for Dynamic Metadata
+impact: MEDIUM
+impactDescription: dynamic SEO, social sharing optimization
+tags: meta, generateMetadata, seo, dynamic
+---
+
+## Use generateMetadata for Dynamic Metadata
+
+Export `generateMetadata` to create dynamic metadata based on route parameters and fetched data. This enables unique titles, descriptions, and OpenGraph images per page.
+
+**Incorrect (static metadata for dynamic pages):**
+
+```typescript
+// app/product/[id]/page.tsx
+export const metadata = {
+ title: 'Product', // Same for all products!
+ description: 'View product details'
+}
+
+export default async function ProductPage({ params }) {
+ const product = await getProduct(params.id)
+ return
+}
+```
+
+**Correct (dynamic metadata per product):**
+
+```typescript
+// app/product/[id]/page.tsx
+import type { Metadata } from 'next'
+
+export async function generateMetadata({
+ params
+}: {
+ params: { id: string }
+}): Promise {
+ const product = await getProduct(params.id)
+
+ return {
+ title: product.name,
+ description: product.description,
+ openGraph: {
+ title: product.name,
+ description: product.description,
+ images: [
+ {
+ url: product.image,
+ width: 1200,
+ height: 630,
+ alt: product.name
+ }
+ ]
+ },
+ twitter: {
+ card: 'summary_large_image',
+ title: product.name,
+ description: product.description,
+ images: [product.image]
+ }
+ }
+}
+
+export default async function ProductPage({ params }) {
+ const product = await getProduct(params.id) // Deduplicated with cache()
+ return
+}
+```
+
+**Note:** Next.js automatically deduplicates `fetch` calls, so `generateMetadata` and the page can call `getProduct` without duplicate requests.
diff --git a/.agents/skills/nextjs/references/meta-opengraph-images.md b/.agents/skills/nextjs/references/meta-opengraph-images.md
new file mode 100644
index 0000000..dba8d0f
--- /dev/null
+++ b/.agents/skills/nextjs/references/meta-opengraph-images.md
@@ -0,0 +1,72 @@
+---
+title: Generate Dynamic OpenGraph Images
+impact: LOW-MEDIUM
+impactDescription: better social sharing, higher CTR
+tags: meta, opengraph, image, social
+---
+
+## Generate Dynamic OpenGraph Images
+
+Use `opengraph-image.tsx` to generate dynamic social preview images. This creates unique, branded images for each page.
+
+**Incorrect (missing or generic OG images):**
+
+```typescript
+// No OG image configured
+// Social shares show generic placeholder or nothing
+```
+
+**Correct (dynamic OG image generation):**
+
+```typescript
+// app/blog/[slug]/opengraph-image.tsx
+import { ImageResponse } from 'next/og'
+
+export const runtime = 'edge'
+export const alt = 'Blog post cover'
+export const size = { width: 1200, height: 630 }
+export const contentType = 'image/png'
+
+export default async function Image({
+ params
+}: {
+ params: { slug: string }
+}) {
+ const post = await getPost(params.slug)
+
+ return new ImageResponse(
+ (
+
+
+ {post.title}
+
+
+ {post.author} · {post.readTime} min read
+
+
+ ),
+ { ...size }
+ )
+}
+```
+
+**Static fallback for routes without dynamic image:**
+
+```typescript
+// app/opengraph-image.png
+// Place a static image in the route for default OG image
+```
+
+Reference: [OpenGraph Images](https://nextjs.org/docs/app/api-reference/file-conventions/metadata/opengraph-image)
diff --git a/.agents/skills/nextjs/references/meta-robots.md b/.agents/skills/nextjs/references/meta-robots.md
new file mode 100644
index 0000000..fb8548b
--- /dev/null
+++ b/.agents/skills/nextjs/references/meta-robots.md
@@ -0,0 +1,68 @@
+---
+title: Configure Robots for Crawl Control
+impact: MEDIUM
+impactDescription: prevents indexing of private pages
+tags: meta, robots, seo, crawling
+---
+
+## Configure Robots for Crawl Control
+
+Use `robots.ts` and per-page robots metadata to control which pages search engines can crawl and index.
+
+**Incorrect (no robots configuration):**
+
+```typescript
+// No robots.ts
+// Search engines may index admin pages, staging URLs, etc.
+```
+
+**Correct (robots.ts for global rules):**
+
+```typescript
+// app/robots.ts
+import type { MetadataRoute } from 'next'
+
+export default function robots(): MetadataRoute.Robots {
+ const baseUrl = process.env.NEXT_PUBLIC_BASE_URL
+
+ return {
+ rules: [
+ {
+ userAgent: '*',
+ allow: '/',
+ disallow: ['/admin/', '/api/', '/dashboard/']
+ }
+ ],
+ sitemap: `${baseUrl}/sitemap.xml`
+ }
+}
+```
+
+**Per-page robots metadata:**
+
+```typescript
+// app/dashboard/page.tsx
+import type { Metadata } from 'next'
+
+export const metadata: Metadata = {
+ robots: {
+ index: false,
+ follow: false,
+ nocache: true,
+ googleBot: {
+ index: false,
+ follow: false
+ }
+ }
+}
+
+export default function DashboardPage() {
+ // Private dashboard content
+}
+```
+
+**Common patterns:**
+- `index: false` - Don't show in search results
+- `follow: false` - Don't follow links on this page
+- `nocache` - Don't cache this page
+- `noarchive` - Don't show cached version in results
diff --git a/.agents/skills/nextjs/references/meta-sitemap.md b/.agents/skills/nextjs/references/meta-sitemap.md
new file mode 100644
index 0000000..4264787
--- /dev/null
+++ b/.agents/skills/nextjs/references/meta-sitemap.md
@@ -0,0 +1,76 @@
+---
+title: Generate Sitemaps Dynamically
+impact: MEDIUM
+impactDescription: improved crawlability, faster indexing
+tags: meta, sitemap, seo, crawling
+---
+
+## Generate Sitemaps Dynamically
+
+Create dynamic sitemaps that include all your pages with proper last-modified dates. This helps search engines discover and index content efficiently.
+
+**Incorrect (static sitemap missing dynamic routes):**
+
+```xml
+
+
+
+ https://example.com/
+
+
+ https://example.com/about
+
+
+
+```
+
+**Correct (dynamic sitemap.ts):**
+
+```typescript
+// app/sitemap.ts
+import type { MetadataRoute } from 'next'
+
+export default async function sitemap(): Promise {
+ const products = await getProducts()
+ const posts = await getPosts()
+
+ const productUrls = products.map((product) => ({
+ url: `https://example.com/products/${product.slug}`,
+ lastModified: product.updatedAt,
+ changeFrequency: 'weekly' as const,
+ priority: 0.8
+ }))
+
+ const postUrls = posts.map((post) => ({
+ url: `https://example.com/blog/${post.slug}`,
+ lastModified: post.updatedAt,
+ changeFrequency: 'monthly' as const,
+ priority: 0.6
+ }))
+
+ return [
+ {
+ url: 'https://example.com',
+ lastModified: new Date(),
+ changeFrequency: 'daily',
+ priority: 1
+ },
+ ...productUrls,
+ ...postUrls
+ ]
+}
+```
+
+**For large sites (50,000+ URLs), split into multiple sitemaps:**
+
+```typescript
+// app/sitemap/[id]/route.ts
+export async function GET(
+ request: Request,
+ { params }: { params: { id: string } }
+) {
+ const page = parseInt(params.id)
+ const products = await getProductsPage(page, 10000)
+ // Generate sitemap XML for this page
+}
+```
diff --git a/.agents/skills/nextjs/references/route-instant-navigations.md b/.agents/skills/nextjs/references/route-instant-navigations.md
new file mode 100644
index 0000000..445fc74
--- /dev/null
+++ b/.agents/skills/nextjs/references/route-instant-navigations.md
@@ -0,0 +1,97 @@
+---
+title: Make Navigations Instant with Stream, Cache, or Block
+impact: HIGH
+impactDescription: SPA-like instant navigations in a server-driven app
+tags: route, navigation, instant, suspense, use-cache, cache-components, instant-insights
+---
+
+## Make Navigations Instant with Stream, Cache, or Block
+
+> **Next.js 16.3 (preview, `next@preview`).** Requires `cacheComponents: true` in `next.config.ts`. Both the feature flags (`cacheComponents`, `partialPrefetching`) are planned to become defaults in a future major release.
+
+In a server-driven app, a navigation that `await`s data on the server blocks until the network roundtrip completes: click → nothing → page. Next.js 16.3 makes slow navigations a development error (the **Instant Insights** panel) and gives you three ways to resolve each one:
+
+- **Stream** with `` — the user instantly sees a loading state, then UI streams in.
+- **Cache** with `'use cache'` — the user instantly sees previously cached UI reused between requests.
+- **Block** with `export const instant = false` — deliberately keep the navigation server-bound (e.g., a blog that never shows a loading shell for posts).
+
+**Incorrect (accidental blocking navigation):**
+
+```typescript
+// app/products/[id]/page.tsx
+export default async function ProductPage({ params }) {
+ const { id } = await params
+ const product = await getProduct(id) // No Suspense, no 'use cache'
+ return
+}
+// Click → blank frame until the server roundtrip finishes.
+// Instant Insights reports this as a slow navigation in dev.
+```
+
+**Correct (stream for instant shell):**
+
+```typescript
+// app/products/[id]/page.tsx
+import { Suspense } from 'react'
+
+export default async function ProductPage({ params }) {
+ const { id } = await params
+ return (
+ }>
+
+
+ )
+}
+// Click → skeleton renders instantly, details stream in.
+```
+
+**Correct (cache for instant cached UI):**
+
+```typescript
+// app/products/[id]/data.ts
+export async function getProduct(id: string) {
+ 'use cache'
+ const product = await db.product.findUnique({ where: { id } })
+ return product
+}
+// Repeat visits render instantly from the cached entry.
+```
+
+**Correct (explicit opt-out when the route must block):**
+
+```typescript
+// app/blog/[slug]/page.tsx
+export const instant = false
+
+export default async function PostPage({ params }) {
+ const post = await getPost((await params).slug)
+ return
+}
+// Navigations stay server-bound by choice; the dev error goes away.
+```
+
+**Catch regressions with the Playwright `instant` helper:**
+
+```typescript
+import { expect, test } from '@playwright/test'
+import { instant } from '@next/playwright'
+
+test('product title is available immediately', async ({ page }) => {
+ await page.goto('/products/shoes')
+
+ // Assert what is visible without waiting for the network
+ await instant(page, async () => {
+ await page.click('a[href="/products/hats"]')
+ await expect(page.locator('h1')).toContainText('Baseball Cap')
+ await expect(page.getByText('Checking inventory...')).toBeVisible()
+ })
+
+ await expect(page.getByText('12 in stock')).toBeVisible()
+})
+```
+
+**Notes:**
+
+- Enable with `cacheComponents: true`; combine with `partialPrefetching: true` for the shell prefetching that makes the first click instant (see [route-partial-prefetching](route-partial-prefetching.md)).
+- The **Navigation Inspector** in Next.js DevTools pauses a navigation at the shell so you can see what displays instantly versus after the network hop.
+- Known preview issues: Instant Insights tooling is unreliable in Safari — use Chrome or Firefox in development. Accessing `params` inside a shell with Partial Prefetching can block without being reported (fixed during the preview cycle).
diff --git a/.agents/skills/nextjs/references/route-intercepting-routes.md b/.agents/skills/nextjs/references/route-intercepting-routes.md
new file mode 100644
index 0000000..f734060
--- /dev/null
+++ b/.agents/skills/nextjs/references/route-intercepting-routes.md
@@ -0,0 +1,76 @@
+---
+title: Use Intercepting Routes for Modal Patterns
+impact: HIGH
+impactDescription: enables shareable modal URLs, better UX
+tags: route, intercepting-routes, modal, navigation
+---
+
+## Use Intercepting Routes for Modal Patterns
+
+Intercepting routes display content in a modal when navigating client-side, while showing the full page on direct access or refresh. Perfect for image galleries, login modals, and detail views.
+
+**Incorrect (client-state modal without URL):**
+
+```typescript
+'use client'
+
+export default function PhotoGallery({ photos }) {
+ const [selectedPhoto, setSelectedPhoto] = useState(null)
+
+ return (
+
+ {photos.map(photo => (
+
setSelectedPhoto(photo)}
+ />
+ ))}
+ {selectedPhoto && (
+ setSelectedPhoto(null)}>
+
+
+ )}
+
+ )
+}
+// Modal not shareable, lost on refresh
+```
+
+**Correct (intercepting route):**
+
+```text
+app/
+├── @modal/
+│ ├── (.)photo/[id]/
+│ │ └── page.tsx # Shows in modal on client nav
+│ └── default.tsx
+├── photo/[id]/
+│ └── page.tsx # Shows full page on direct access
+└── page.tsx # Gallery
+```
+
+```typescript
+// app/@modal/(.)photo/[id]/page.tsx
+import { Modal } from '@/components/Modal'
+
+export default async function PhotoModal({ params }: { params: { id: string } }) {
+ const photo = await getPhoto(params.id)
+ return (
+
+
+
+ )
+}
+
+// app/photo/[id]/page.tsx
+export default async function PhotoPage({ params }: { params: { id: string } }) {
+ const photo = await getPhoto(params.id)
+ return // Full page
+}
+```
+
+**Interception conventions:**
+- `(.)` - Same level
+- `(..)` - One level up
+- `(..)(..)` - Two levels up
+- `(...)` - From root
diff --git a/.agents/skills/nextjs/references/route-not-found.md b/.agents/skills/nextjs/references/route-not-found.md
new file mode 100644
index 0000000..04b829c
--- /dev/null
+++ b/.agents/skills/nextjs/references/route-not-found.md
@@ -0,0 +1,59 @@
+---
+title: Use notFound() for Missing Resources
+impact: MEDIUM
+impactDescription: proper 404 handling, better SEO
+tags: route, not-found, 404, error-handling
+---
+
+## Use notFound() for Missing Resources
+
+Call `notFound()` when a dynamic resource doesn't exist. This renders the closest `not-found.tsx` and returns a proper 404 status code.
+
+**Incorrect (rendering empty state for missing data):**
+
+```typescript
+// app/product/[id]/page.tsx
+export default async function ProductPage({ params }: { params: { id: string } }) {
+ const product = await getProduct(params.id)
+
+ if (!product) {
+ return Product not found
// Returns 200, bad for SEO
+ }
+
+ return
+}
+```
+
+**Correct (using notFound()):**
+
+```typescript
+// app/product/[id]/page.tsx
+import { notFound } from 'next/navigation'
+
+export default async function ProductPage({ params }: { params: { id: string } }) {
+ const product = await getProduct(params.id)
+
+ if (!product) {
+ notFound() // Returns 404, renders not-found.tsx
+ }
+
+ return
+}
+
+// app/product/[id]/not-found.tsx
+export default function ProductNotFound() {
+ return (
+
+
Product Not Found
+
The product you're looking for doesn't exist.
+
Browse all products
+
+ )
+}
+```
+
+**Benefits:**
+- Correct 404 HTTP status for SEO
+- Crawlers understand the page doesn't exist
+- Custom UI for missing resources
+- Can be nested per route segment
diff --git a/.agents/skills/nextjs/references/route-parallel-routes.md b/.agents/skills/nextjs/references/route-parallel-routes.md
new file mode 100644
index 0000000..6c624b1
--- /dev/null
+++ b/.agents/skills/nextjs/references/route-parallel-routes.md
@@ -0,0 +1,79 @@
+---
+title: Use Parallel Routes for Independent Content
+impact: HIGH
+impactDescription: independent loading, streaming, error handling
+tags: route, parallel-routes, slots, layout
+---
+
+## Use Parallel Routes for Independent Content
+
+Parallel routes (slots) render multiple pages simultaneously in the same layout. Each slot can have independent loading, error, and streaming states.
+
+**Incorrect (sequential rendering in single page):**
+
+```typescript
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+ const analytics = await fetchAnalytics() // Slow
+ const notifications = await fetchNotifications()
+ const activity = await fetchActivity()
+
+ return (
+
+ )
+}
+// All sections wait for slowest fetch
+```
+
+**Correct (parallel routes with independent streaming):**
+
+```text
+app/dashboard/
+├── layout.tsx
+├── @analytics/
+│ ├── page.tsx
+│ └── loading.tsx
+├── @notifications/
+│ ├── page.tsx
+│ └── loading.tsx
+└── @activity/
+ ├── page.tsx
+ └── loading.tsx
+```
+
+```typescript
+// app/dashboard/layout.tsx
+export default function DashboardLayout({
+ analytics,
+ notifications,
+ activity
+}: {
+ analytics: React.ReactNode
+ notifications: React.ReactNode
+ activity: React.ReactNode
+}) {
+ return (
+
+ {analytics}
+ {notifications}
+ {activity}
+
+ )
+}
+
+// app/dashboard/@analytics/page.tsx
+export default async function AnalyticsSlot() {
+ const data = await fetchAnalytics()
+ return
+}
+// Each slot streams independently
+```
+
+**Benefits:**
+- Each slot loads independently
+- Each slot has its own loading.tsx
+- Each slot can have its own error.tsx
diff --git a/.agents/skills/nextjs/references/route-partial-prefetching.md b/.agents/skills/nextjs/references/route-partial-prefetching.md
new file mode 100644
index 0000000..9fdab2d
--- /dev/null
+++ b/.agents/skills/nextjs/references/route-partial-prefetching.md
@@ -0,0 +1,87 @@
+---
+title: Use Partial Prefetching for Reusable Route Shells
+impact: HIGH
+impactDescription: one prefetch per route instead of per link, instant first click
+tags: route, prefetching, partial-prefetching, shell, link, navigation
+---
+
+## Use Partial Prefetching for Reusable Route Shells
+
+> **Next.js 16.3 (preview, `next@preview`).** Requires `cacheComponents: true` and `partialPrefetching: true` in `next.config.ts`. Planned to become the default behavior in a future major release.
+
+Before 16.2, Next.js sent a prefetch request for **every link** in the viewport — even many links to the same route, producing a flurry of requests on scroll. 16.3 replaces this with a single-page-app trick: **prefetch one reusable loading shell per route**, fetched once and cached on the client for the session.
+
+```typescript
+// next.config.ts
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+ cacheComponents: true,
+ partialPrefetching: true,
+}
+
+export default nextConfig
+```
+
+**Incorrect (relying on per-link prefetch for responsiveness):**
+
+```typescript
+// A sidebar with twenty chat links fires a prefetch per link,
+// most of them for the same /chat/[id] route
+export function Sidebar({ chats }) {
+ return (
+
+ {chats.map((chat) => (
+
+ {chat.name}
+
+ ))}
+
+ )
+}
+// Wasteful: the same route shell is fetched once per link
+```
+
+**Correct (let the shell be prefetched once per route):**
+
+```typescript
+// With partialPrefetching enabled, Next.js prefetches a single
+// reusable shell for /chat/[id], plus one per other distinct route
+export function Sidebar({ chats }) {
+ return (
+
+ {chats.map((chat) => (
+
+ {chat.name}
+
+ ))}
+
+ )
+}
+// One request for the route, cached across all twenty links
+```
+
+**Prefetch more than the shell for specific links:**
+
+```tsx
+// Opt a single link into deeper prefetching so the chat header
+// "pops in" instantly instead of waiting for the network
+
+ {chat.name}
+
+```
+
+With ` `, Next.js still does not render the entire route. It renders down to content that is:
+
+- available synchronously,
+- known from the URL (`params`, `searchParams`), or
+- marked with `'use cache'`.
+
+This removes the all-or-nothing choice: the instant shell is the baseline, and ` ` plus `'use cache'` adds per-link depth only where it pays off.
+
+**Notes:**
+
+- Inspect what a shell contains with the **Navigation Inspector** in Next.js DevTools — it pauses each navigation at the shell so you can see what renders instantly versus after the network hop.
+- Actual prefetching happens only in production builds; in development the Inspector simulates it.
+- Because shells are reused across links, they are the foundation for upcoming offline navigation support.
+- Pair with [route-instant-navigations](route-instant-navigations.md) (Stream / Cache / Block) so each route actually has an instant shell to prefetch.
diff --git a/.agents/skills/nextjs/references/route-prefetching.md b/.agents/skills/nextjs/references/route-prefetching.md
new file mode 100644
index 0000000..40a1f04
--- /dev/null
+++ b/.agents/skills/nextjs/references/route-prefetching.md
@@ -0,0 +1,71 @@
+---
+title: Configure Link Prefetching Appropriately
+impact: MEDIUM-HIGH
+impactDescription: instant navigation for likely destinations
+tags: route, prefetching, link, navigation
+---
+
+## Configure Link Prefetching Appropriately
+
+Next.js automatically prefetches linked routes. Control this behavior based on route importance and user likelihood to navigate.
+
+**Incorrect (no prefetch consideration):**
+
+```typescript
+// Prefetches all links, including rarely used ones
+export default function Navigation() {
+ return (
+
+ Home
+ Products
+ Settings {/* Rarely accessed */}
+ Terms {/* Rarely accessed */}
+
+ )
+}
+// Wastes bandwidth prefetching unlikely routes
+```
+
+**Correct (strategic prefetching):**
+
+```typescript
+export default function Navigation() {
+ return (
+
+ {/* High-traffic routes - prefetch (default) */}
+ Home
+ Products
+
+ {/* Low-traffic routes - disable prefetch */}
+ Settings
+ Terms
+
+ )
+}
+```
+
+**Prefetch on hover for conditional routes:**
+
+```typescript
+'use client'
+
+import { useRouter } from 'next/navigation'
+
+export function ProductCard({ product }) {
+ const router = useRouter()
+
+ return (
+ router.prefetch(`/product/${product.id}`)}
+ onClick={() => router.push(`/product/${product.id}`)}
+ >
+ {product.name}
+
+ )
+}
+// Prefetches only when user shows intent
+```
+
+**Note:** In production, prefetching only loads the shared layout and static portions of the route.
+
+**Next.js 16.3 preview changes this model:** with `partialPrefetching: true`, Next.js prefetches one reusable shell per route (fetched once, cached across links) instead of per link, and `prefetch={true}` becomes an opt-in for deeper per-link prefetching. Slow navigations become dev errors under `cacheComponents: true` — see [route-partial-prefetching](route-partial-prefetching.md) and [route-instant-navigations](route-instant-navigations.md).
diff --git a/.agents/skills/nextjs/references/route-proxy-ts.md b/.agents/skills/nextjs/references/route-proxy-ts.md
new file mode 100644
index 0000000..f6f32dd
--- /dev/null
+++ b/.agents/skills/nextjs/references/route-proxy-ts.md
@@ -0,0 +1,62 @@
+---
+title: Use proxy.ts for Network Boundary Logic
+impact: MEDIUM-HIGH
+impactDescription: clearer network boundary, Node.js runtime
+tags: route, proxy, middleware, network
+---
+
+## Use proxy.ts for Network Boundary Logic
+
+Next.js 16 deprecates the `middleware.ts` convention in favor of `proxy.ts` for network-boundary logic. `proxy.ts` uses the Node.js runtime and its runtime cannot be configured. If an existing boundary requires the Edge runtime, keep `middleware.ts` until the installed Next.js version provides a documented migration path.
+
+**Incorrect (old middleware.ts pattern):**
+
+```typescript
+// middleware.ts (deprecated in Next.js 16)
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function middleware(request: NextRequest) {
+ const token = request.cookies.get('token')
+ if (!token) {
+ return NextResponse.redirect(new URL('/login', request.url))
+ }
+}
+
+export const config = {
+ matcher: '/dashboard/:path*'
+}
+```
+
+**Correct (proxy.ts in Next.js 16):**
+
+```typescript
+// proxy.ts
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export function proxy(request: NextRequest) {
+ const token = request.cookies.get('token')
+
+ // Full Node.js APIs available (not Edge)
+ if (!token) {
+ return NextResponse.redirect(new URL('/login', request.url))
+ }
+
+ // Add headers, rewrite, etc.
+ const response = NextResponse.next()
+ response.headers.set('x-custom-header', 'value')
+ return response
+}
+
+export const config = {
+ matcher: '/dashboard/:path*'
+}
+```
+
+**Migration:**
+1. Rename `middleware.ts` → `proxy.ts`
+2. Rename exported function `middleware` → `proxy`
+3. Remove Edge-only assumptions and verify Node.js runtime behavior; otherwise retain `middleware.ts` for the Edge requirement
+
+Reference: [Next.js proxy file convention](https://nextjs.org/docs/app/api-reference/file-conventions/proxy)
diff --git a/.agents/skills/nextjs/references/server-avoid-client-fetching.md b/.agents/skills/nextjs/references/server-avoid-client-fetching.md
new file mode 100644
index 0000000..983a588
--- /dev/null
+++ b/.agents/skills/nextjs/references/server-avoid-client-fetching.md
@@ -0,0 +1,71 @@
+---
+title: Avoid Client-Side Data Fetching for Initial Data
+impact: MEDIUM-HIGH
+impactDescription: eliminates client waterfalls, better SEO
+tags: server, data-fetching, seo, waterfalls
+---
+
+## Avoid Client-Side Data Fetching for Initial Data
+
+Fetch initial page data in Server Components, not with `useEffect` or client-side libraries. Client-side fetching creates waterfalls and hurts SEO.
+
+**Incorrect (client-side fetch with useEffect):**
+
+```typescript
+'use client'
+
+import { useState, useEffect } from 'react'
+
+export default function ProductsPage() {
+ const [products, setProducts] = useState([])
+ const [loading, setLoading] = useState(true)
+
+ useEffect(() => {
+ fetch('/api/products')
+ .then(res => res.json())
+ .then(data => {
+ setProducts(data)
+ setLoading(false)
+ })
+ }, [])
+
+ if (loading) return
+ return
+}
+// Waterfall: HTML → JS → Hydrate → Fetch → Render
+// Empty for SEO crawlers
+```
+
+**Correct (Server Component fetch):**
+
+```typescript
+// app/products/page.tsx
+export default async function ProductsPage() {
+ const products = await fetch('https://api.store.com/products')
+ .then(res => res.json())
+
+ return
+}
+// Single request, data included in HTML, SEO-friendly
+```
+
+**When to use client-side fetching:**
+- User-initiated actions (load more, search)
+- Real-time updates (polling, WebSocket)
+- After-interaction data (comments on expand)
+
+**Recommended client-side library:**
+
+```typescript
+'use client'
+
+import useSWR from 'swr'
+
+export function SearchResults({ query }: { query: string }) {
+ const { data, isLoading } = useSWR(
+ query ? `/api/search?q=${query}` : null,
+ fetcher
+ )
+ // Client fetch appropriate for user-initiated search
+}
+```
diff --git a/.agents/skills/nextjs/references/server-component-streaming.md b/.agents/skills/nextjs/references/server-component-streaming.md
new file mode 100644
index 0000000..5c868e6
--- /dev/null
+++ b/.agents/skills/nextjs/references/server-component-streaming.md
@@ -0,0 +1,70 @@
+---
+title: Stream Server Components for Progressive Loading
+impact: HIGH
+impactDescription: faster Time to First Byte, progressive rendering
+tags: server, streaming, suspense, progressive-loading
+---
+
+## Stream Server Components for Progressive Loading
+
+Split data-intensive Server Components and wrap them in Suspense to stream HTML progressively. Fast components render immediately while slow ones load.
+
+**Incorrect (all-or-nothing rendering):**
+
+```typescript
+// app/page.tsx
+export default async function Page() {
+ const user = await fetchUser() // 100ms
+ const posts = await fetchPosts() // 500ms
+ const analytics = await fetchAnalytics() // 2000ms
+
+ return (
+
+ )
+}
+// Nothing renders until analytics completes (2100ms)
+```
+
+**Correct (progressive streaming):**
+
+```typescript
+// app/page.tsx
+import { Suspense } from 'react'
+
+export default function Page() {
+ return (
+
+
}>
+
+
+
}>
+
+
+
}>
+
+
+
+ )
+}
+
+// Each component fetches its own data
+async function Header() {
+ const user = await fetchUser()
+ return
+}
+
+async function Analytics() {
+ const data = await fetchAnalytics()
+ return
+}
+// Header renders in 100ms, Posts in 500ms, Analytics in 2000ms
+```
+
+**Benefits:**
+- First paint happens immediately
+- Each section appears as soon as its data is ready
+- Slow components don't block fast ones
diff --git a/.agents/skills/nextjs/references/server-data-colocation.md b/.agents/skills/nextjs/references/server-data-colocation.md
new file mode 100644
index 0000000..684e528
--- /dev/null
+++ b/.agents/skills/nextjs/references/server-data-colocation.md
@@ -0,0 +1,63 @@
+---
+title: Colocate Data Fetching with Components
+impact: HIGH
+impactDescription: eliminates prop drilling, enables streaming
+tags: server, colocation, data-fetching, architecture
+---
+
+## Colocate Data Fetching with Components
+
+Fetch data where it's needed, not in parent components. This enables independent streaming and eliminates prop drilling.
+
+**Incorrect (fetching in parent, prop drilling):**
+
+```typescript
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+ const user = await fetchUser()
+ const orders = await fetchOrders(user.id)
+ const notifications = await fetchNotifications(user.id)
+
+ return (
+
+
+
+
+
+ )
+}
+// All data fetched sequentially, no streaming possible
+```
+
+**Correct (colocated data fetching):**
+
+```typescript
+// app/dashboard/page.tsx
+import { Suspense } from 'react'
+
+export default function DashboardPage() {
+ return (
+
+ }>
+
+
+ }>
+
+
+ }>
+
+
+
+ )
+}
+
+// components/OrderList.tsx
+async function OrderList() {
+ const user = await getUser() // Deduplicated with cache()
+ const orders = await fetchOrders(user.id)
+ return
+}
+// Each component fetches what it needs, streams independently
+```
+
+**Note:** Use `cache()` to deduplicate shared data like user across components.
diff --git a/.agents/skills/nextjs/references/server-error-handling.md b/.agents/skills/nextjs/references/server-error-handling.md
new file mode 100644
index 0000000..cb55364
--- /dev/null
+++ b/.agents/skills/nextjs/references/server-error-handling.md
@@ -0,0 +1,79 @@
+---
+title: Handle Server Component Errors Gracefully
+impact: MEDIUM
+impactDescription: prevents full page crashes, better UX
+tags: server, error-handling, error-boundary, resilience
+---
+
+## Handle Server Component Errors Gracefully
+
+Use error boundaries and try/catch to handle failures gracefully. A single failed fetch shouldn't crash the entire page.
+
+**Incorrect (unhandled error crashes page):**
+
+```typescript
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+ const analytics = await fetchAnalytics() // If this fails, entire page crashes
+
+ return (
+
+ )
+}
+```
+
+**Correct (graceful error handling):**
+
+```typescript
+// app/dashboard/page.tsx
+import { Suspense } from 'react'
+import { ErrorBoundary } from 'react-error-boundary'
+
+export default function DashboardPage() {
+ return (
+
+ )
+}
+
+// Or use error.tsx for route-level errors
+// app/dashboard/error.tsx
+'use client'
+
+export default function Error({
+ error,
+ reset
+}: {
+ error: Error
+ reset: () => void
+}) {
+ return (
+
+
Something went wrong
+ reset()}>Try again
+
+ )
+}
+```
+
+**Try/catch for specific components:**
+
+```typescript
+async function Analytics() {
+ try {
+ const data = await fetchAnalytics()
+ return
+ } catch (error) {
+ return
+ }
+}
+```
diff --git a/.agents/skills/nextjs/references/server-parallel-fetching.md b/.agents/skills/nextjs/references/server-parallel-fetching.md
new file mode 100644
index 0000000..9fe6d1e
--- /dev/null
+++ b/.agents/skills/nextjs/references/server-parallel-fetching.md
@@ -0,0 +1,69 @@
+---
+title: Fetch Data in Parallel in Server Components
+impact: HIGH
+impactDescription: eliminates server-side waterfalls, 2-5× faster
+tags: server, parallel, data-fetching, promise-all
+---
+
+## Fetch Data in Parallel in Server Components
+
+Initiate all independent data fetches simultaneously using `Promise.all()`. Sequential awaits create server-side waterfalls that multiply latency.
+
+**Incorrect (sequential fetches, 3 round trips):**
+
+```typescript
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+ const user = await fetchUser() // 200ms
+ const orders = await fetchOrders() // 150ms
+ const notifications = await fetchNotifications() // 100ms
+ // Total: 450ms (sequential)
+
+ return (
+
+ )
+}
+```
+
+**Correct (parallel fetches, 1 round trip):**
+
+```typescript
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+ const [user, orders, notifications] = await Promise.all([
+ fetchUser(), // 200ms
+ fetchOrders(), // 150ms (parallel)
+ fetchNotifications() // 100ms (parallel)
+ ])
+ // Total: 200ms (longest request)
+
+ return (
+
+ )
+}
+```
+
+**With dependent data:**
+
+```typescript
+export default async function DashboardPage() {
+ // First fetch user (needed for subsequent queries)
+ const user = await fetchUser()
+
+ // Then fetch user-dependent data in parallel
+ const [orders, preferences] = await Promise.all([
+ fetchOrders(user.id),
+ fetchPreferences(user.id)
+ ])
+
+ return
+}
+```
diff --git a/.agents/skills/nextjs/references/server-preload-pattern.md b/.agents/skills/nextjs/references/server-preload-pattern.md
new file mode 100644
index 0000000..d4848cd
--- /dev/null
+++ b/.agents/skills/nextjs/references/server-preload-pattern.md
@@ -0,0 +1,68 @@
+---
+title: Use Preload Pattern for Critical Data
+impact: MEDIUM-HIGH
+impactDescription: starts fetches earlier in render tree
+tags: server, preload, data-fetching, optimization
+---
+
+## Use Preload Pattern for Critical Data
+
+Export a `preload` function that initiates data fetching at the top of the component tree. This starts fetches earlier, reducing time to first byte.
+
+**Incorrect (data fetch starts late in component tree):**
+
+```typescript
+// app/product/[id]/page.tsx
+export default async function ProductPage({ params }: { params: { id: string } }) {
+ return (
+
+
+
+
{/* Fetch starts here */}
+
+ )
+}
+
+async function ProductDetails({ id }: { id: string }) {
+ const product = await getProduct(id) // Fetch delayed by parent render
+ return {product.name}
+}
+```
+
+**Correct (preload starts fetch immediately):**
+
+```typescript
+// lib/data.ts
+import { cache } from 'react'
+
+export const getProduct = cache(async (id: string) => {
+ const res = await fetch(`/api/products/${id}`)
+ return res.json()
+})
+
+export const preloadProduct = (id: string) => {
+ void getProduct(id) // Start fetch, don't await
+}
+
+// app/product/[id]/page.tsx
+import { preloadProduct, getProduct } from '@/lib/data'
+
+export default async function ProductPage({ params }: { params: { id: string } }) {
+ preloadProduct(params.id) // Start fetch immediately
+
+ return (
+
+ )
+}
+
+async function ProductDetails({ id }: { id: string }) {
+ const product = await getProduct(id) // Uses cached promise
+ return {product.name}
+}
+```
+
+**Note:** The `cache()` wrapper ensures the preloaded data is reused by child components.
diff --git a/.agents/skills/nextjs/references/stream-error-tsx.md b/.agents/skills/nextjs/references/stream-error-tsx.md
new file mode 100644
index 0000000..39156a9
--- /dev/null
+++ b/.agents/skills/nextjs/references/stream-error-tsx.md
@@ -0,0 +1,67 @@
+---
+title: Use error.tsx for Route-Level Error Boundaries
+impact: MEDIUM
+impactDescription: graceful error recovery, prevents full page crashes
+tags: stream, error, error-boundary, recovery
+---
+
+## Use error.tsx for Route-Level Error Boundaries
+
+Create `error.tsx` files to catch errors in route segments. Users can retry without navigating away or losing state.
+
+**Incorrect (unhandled errors crash the page):**
+
+```typescript
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+ const data = await fetchData() // If this throws, entire app crashes
+ return
+}
+```
+
+**Correct (error.tsx catches and recovers):**
+
+```typescript
+// app/dashboard/error.tsx
+'use client' // Error components must be Client Components
+
+import { useEffect } from 'react'
+
+export default function DashboardError({
+ error,
+ reset
+}: {
+ error: Error & { digest?: string }
+ reset: () => void
+}) {
+ useEffect(() => {
+ // Log to error reporting service
+ console.error(error)
+ }, [error])
+
+ return (
+
+
Something went wrong loading the dashboard
+ reset()}
+ className="mt-2 px-4 py-2 bg-red-600 text-white rounded"
+ >
+ Try again
+
+
+ )
+}
+```
+
+**Error boundary hierarchy:**
+
+```text
+app/
+├── error.tsx # Catches errors in all routes
+├── global-error.tsx # Catches errors in root layout
+└── dashboard/
+ ├── error.tsx # Catches errors in dashboard routes only
+ └── page.tsx
+```
+
+**Note:** `error.tsx` doesn't catch errors in the same segment's `layout.tsx`. Place `error.tsx` in the parent segment to catch layout errors.
diff --git a/.agents/skills/nextjs/references/stream-loading-tsx.md b/.agents/skills/nextjs/references/stream-loading-tsx.md
new file mode 100644
index 0000000..a5f2956
--- /dev/null
+++ b/.agents/skills/nextjs/references/stream-loading-tsx.md
@@ -0,0 +1,63 @@
+---
+title: Use loading.tsx for Route-Level Loading States
+impact: MEDIUM
+impactDescription: automatic loading UI, instant navigation feedback
+tags: stream, loading, skeleton, navigation
+---
+
+## Use loading.tsx for Route-Level Loading States
+
+Create `loading.tsx` files to show instant loading UI during route transitions. Next.js automatically wraps the page in Suspense with this component as fallback.
+
+**Incorrect (no loading state):**
+
+```text
+app/dashboard/
+└── page.tsx
+# Navigation to /dashboard shows blank screen until data loads
+```
+
+**Correct (loading.tsx for instant feedback):**
+
+```text
+app/dashboard/
+├── loading.tsx
+└── page.tsx
+```
+
+```typescript
+// app/dashboard/loading.tsx
+export default function DashboardLoading() {
+ return (
+
+ )
+}
+
+// app/dashboard/page.tsx
+export default async function DashboardPage() {
+ const data = await fetchDashboardData()
+ return
+}
+```
+
+**Best practices:**
+- Match skeleton structure to actual content
+- Use CSS animations for polish
+- Keep skeletons lightweight (no data fetching)
+- Nest loading.tsx for granular control
+
+```text
+app/dashboard/
+├── loading.tsx # Dashboard skeleton
+├── page.tsx
+└── analytics/
+ ├── loading.tsx # Analytics-specific skeleton
+ └── page.tsx
+```
diff --git a/.agents/skills/nextjs/references/stream-nested-suspense.md b/.agents/skills/nextjs/references/stream-nested-suspense.md
new file mode 100644
index 0000000..4d593de
--- /dev/null
+++ b/.agents/skills/nextjs/references/stream-nested-suspense.md
@@ -0,0 +1,82 @@
+---
+title: Nest Suspense for Progressive Disclosure
+impact: LOW-MEDIUM
+impactDescription: fine-grained loading control, better UX
+tags: stream, suspense, nested, progressive
+---
+
+## Nest Suspense for Progressive Disclosure
+
+Nest Suspense boundaries to create progressive loading experiences. Outer boundaries show first, inner boundaries refine as data loads.
+
+**Incorrect (flat Suspense structure):**
+
+```typescript
+export default function ProductPage() {
+ return (
+
+
}>
+
+
+
}>
+
+
+
}>
+
+
+
+ )
+}
+// All sections load independently, no visual hierarchy
+```
+
+**Correct (nested progressive disclosure):**
+
+```typescript
+export default function ProductPage() {
+ return (
+
+ {/* Product details load first - critical content */}
+
}>
+
+
+ {/* Reviews load after product - secondary content */}
+
}>
+
+
+ {/* Related products load last - tertiary content */}
+
}>
+
+
+
+
+
+ )
+}
+// Content reveals progressively: Product → Reviews → Related
+```
+
+**Alternative (prioritized parallel loading):**
+
+```typescript
+export default function ProductPage() {
+ return (
+
+ {/* Critical path - no Suspense, blocks render */}
+
+
+
+ {/* Primary content */}
+
}>
+
+
+
+ {/* Secondary content - lower priority */}
+
}>
+
+
+
+
+ )
+}
+```
diff --git a/.agents/skills/nextjs/references/stream-skeleton-matching.md b/.agents/skills/nextjs/references/stream-skeleton-matching.md
new file mode 100644
index 0000000..7127588
--- /dev/null
+++ b/.agents/skills/nextjs/references/stream-skeleton-matching.md
@@ -0,0 +1,72 @@
+---
+title: Match Skeleton Dimensions to Actual Content
+impact: MEDIUM
+impactDescription: prevents layout shift, better CLS score
+tags: stream, skeleton, layout-shift, cls
+---
+
+## Match Skeleton Dimensions to Actual Content
+
+Loading skeletons should match the dimensions of actual content to prevent layout shift (CLS). Use fixed heights or aspect ratios.
+
+**Incorrect (skeleton causes layout shift):**
+
+```typescript
+// loading.tsx
+export default function Loading() {
+ return
+}
+
+// page.tsx
+export default async function Page() {
+ const data = await fetchData()
+ return (
+ {/* Height doesn't match skeleton */}
+
+
+ )
+}
+// Page jumps from 32px to 256px when content loads
+```
+
+**Correct (skeleton matches content dimensions):**
+
+```typescript
+// loading.tsx
+export default function Loading() {
+ return (
+
+ {/* Header skeleton - matches actual header height */}
+
+
+ {/* Card grid skeleton - matches actual card dimensions */}
+
+ {[1, 2, 3].map(i => (
+
+ ))}
+
+
+ )
+}
+
+// page.tsx
+export default async function Page() {
+ const data = await fetchData()
+ return (
+
+
{data.title}
+
+ {data.cards.map(card => (
+
+ ))}
+
+
+ )
+}
+// No layout shift - skeleton and content have same dimensions
+```
+
+**Tips:**
+- Use the same CSS classes for skeleton and content containers
+- Set explicit heights on dynamic content
+- Use `aspect-ratio` for images and videos
diff --git a/.agents/skills/nextjs/references/stream-suspense-boundaries.md b/.agents/skills/nextjs/references/stream-suspense-boundaries.md
new file mode 100644
index 0000000..c4d84dd
--- /dev/null
+++ b/.agents/skills/nextjs/references/stream-suspense-boundaries.md
@@ -0,0 +1,62 @@
+---
+title: Place Suspense Boundaries Strategically
+impact: MEDIUM
+impactDescription: faster perceived performance, progressive loading
+tags: stream, suspense, loading, progressive
+---
+
+## Place Suspense Boundaries Strategically
+
+Wrap slow components in Suspense to show meaningful content immediately. Place boundaries around content that fetches data independently.
+
+**Incorrect (single Suspense for entire page):**
+
+```typescript
+// app/dashboard/page.tsx
+import { Suspense } from 'react'
+
+export default function DashboardPage() {
+ return (
+ }>
+
+
+ )
+}
+// User sees full-page spinner until everything loads
+```
+
+**Correct (granular Suspense boundaries):**
+
+```typescript
+// app/dashboard/page.tsx
+import { Suspense } from 'react'
+
+export default function DashboardPage() {
+ return (
+
+ {/* Fast content renders immediately */}
+
+
+ {/* Each section loads independently */}
+ }>
+
+
+
+ }>
+
+
+
+ }>
+
+
+
+ )
+}
+// Header shows instantly, widgets stream in as they load
+```
+
+**Guidelines for Suspense boundaries:**
+- Wrap each independent data-fetching component
+- Group related components in single boundary
+- Keep fallbacks similar in size to actual content (prevent layout shift)
+- Prioritize above-the-fold content
diff --git a/.agents/skills/nuqs/SKILL.md b/.agents/skills/nuqs/SKILL.md
new file mode 100644
index 0000000..3587371
--- /dev/null
+++ b/.agents/skills/nuqs/SKILL.md
@@ -0,0 +1,110 @@
+---
+name: nuqs
+description: nuqs type-safe URL search-param state.
+---
+
+# Community nuqs Best Practices for Next.js
+
+Comprehensive guide for type-safe URL query state management with nuqs in Next.js applications. Contains 42 rules across 8 categories, prioritized by impact to guide code generation, refactoring, and code review.
+
+## When to Apply
+
+Reference these guidelines when:
+- Implementing URL-based state with nuqs
+- Setting up nuqs in a Next.js project
+- Configuring parsers for URL parameters
+- Integrating URL state with Server Components
+- Optimizing URL update performance
+- Debugging nuqs-related issues
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Parser Configuration | CRITICAL | `parser-` |
+| 2 | Adapter & Setup | CRITICAL | `setup-` |
+| 3 | State Management | HIGH | `state-` |
+| 4 | Server Integration | HIGH | `server-` |
+| 5 | Performance Optimization | MEDIUM | `perf-` |
+| 6 | History & Navigation | MEDIUM | `history-` |
+| 7 | Debugging & Testing | LOW-MEDIUM | `debug-` |
+| 8 | Advanced Patterns | LOW | `advanced-` |
+
+## Quick Reference
+
+### 1. Parser Configuration (CRITICAL)
+
+- [`parser-use-typed-parsers`](references/parser-use-typed-parsers.md) - Use typed parsers for non-string values
+- [`parser-with-default`](references/parser-with-default.md) - Use withDefault for non-nullable state
+- [`parser-enum-validation`](references/parser-enum-validation.md) - Use enum parsers for constrained values
+- [`parser-array-format`](references/parser-array-format.md) - Choose correct array parser format
+- [`parser-json-validation`](references/parser-json-validation.md) - Validate JSON parser input
+- [`parser-date-format`](references/parser-date-format.md) - Select appropriate date parser
+- [`parser-index-offset`](references/parser-index-offset.md) - Use parseAsIndex for 1-based URL display
+- [`parser-hex-colors`](references/parser-hex-colors.md) - Use parseAsHex for color values
+
+### 2. Adapter & Setup (CRITICAL)
+
+- [`setup-nuqs-adapter`](references/setup-nuqs-adapter.md) - Wrap app with NuqsAdapter
+- [`setup-use-client`](references/setup-use-client.md) - Add 'use client' directive for hooks
+- [`setup-import-server`](references/setup-import-server.md) - Import server utilities from nuqs/server
+- [`setup-nextjs-version`](references/setup-nextjs-version.md) - Ensure compatible Next.js version
+- [`setup-shared-parsers`](references/setup-shared-parsers.md) - Define shared parsers in dedicated file
+
+### 3. State Management (HIGH)
+
+- [`state-use-query-states`](references/state-use-query-states.md) - Use useQueryStates for related parameters
+- [`state-functional-updates`](references/state-functional-updates.md) - Use functional updates for derived state
+- [`state-clear-with-null`](references/state-clear-with-null.md) - Clear URL parameters with null
+- [`state-controlled-inputs`](references/state-controlled-inputs.md) - Handle controlled input value properly
+- [`state-avoid-derived`](references/state-avoid-derived.md) - Avoid derived state from URL parameters
+- [`state-options-inheritance`](references/state-options-inheritance.md) - Use withOptions for parser-level configuration
+- [`state-setter-return`](references/state-setter-return.md) - Use setter return value for URL access
+
+### 4. Server Integration (HIGH)
+
+- [`server-search-params-cache`](references/server-search-params-cache.md) - Use createSearchParamsCache for Server Components
+- [`server-shallow-false`](references/server-shallow-false.md) - Use shallow:false to trigger server re-renders
+- [`server-use-transition`](references/server-use-transition.md) - Integrate useTransition for loading states
+- [`server-parse-before-get`](references/server-parse-before-get.md) - Call parse() before get() in Server Components
+- [`server-share-parsers`](references/server-share-parsers.md) - Share parsers between client and server
+- [`server-next15-async`](references/server-next15-async.md) - Handle async searchParams in Next.js 15+
+
+### 5. Performance Optimization (MEDIUM)
+
+- [`perf-throttle-updates`](references/perf-throttle-updates.md) - Throttle URL updates with limitUrlUpdates
+- [`perf-clear-on-default`](references/perf-clear-on-default.md) - Use clearOnDefault for clean URLs
+- [`perf-avoid-rerender`](references/perf-avoid-rerender.md) - Memoize components using URL state
+- [`perf-serialize-utility`](references/perf-serialize-utility.md) - Use createSerializer for link URLs
+- [`perf-debounce-search`](references/perf-debounce-search.md) - Debounce server-bound search updates
+
+### 6. History & Navigation (MEDIUM)
+
+- [`history-push-navigation`](references/history-push-navigation.md) - Use history:push for navigation-like state
+- [`history-replace-ephemeral`](references/history-replace-ephemeral.md) - Use history:replace for ephemeral state
+- [`history-scroll-behavior`](references/history-scroll-behavior.md) - Control scroll behavior on URL changes
+- [`history-back-sync`](references/history-back-sync.md) - Handle browser back/forward navigation
+
+### 7. Debugging & Testing (LOW-MEDIUM)
+
+- [`debug-enable-logging`](references/debug-enable-logging.md) - Enable debug logging for troubleshooting
+- [`debug-common-errors`](references/debug-common-errors.md) - Diagnose common nuqs errors
+- [`debug-testing`](references/debug-testing.md) - Test components with URL state
+
+### 8. Advanced Patterns (LOW)
+
+- [`advanced-custom-parsers`](references/advanced-custom-parsers.md) - Create custom parsers for complex types
+- [`advanced-url-keys`](references/advanced-url-keys.md) - Use urlKeys for shorter URLs
+- [`advanced-eq-function`](references/advanced-eq-function.md) - Implement eq function for object parsers
+- [`advanced-framework-adapters`](references/advanced-framework-adapters.md) - Use framework-specific adapters
+
+## How to Use
+
+Run in the project root first:
+
+```bash
+npx -y @pymodel/react-frontend-skills detect # installed vs. targeted versions
+npx -y @pymodel/react-frontend-skills scan --skill nuqs # deprecated APIs → rule IDs
+```
+
+Read `references/.md` for each rule above that matches the task and for each `scan` hit: why it matters, then incorrect vs. correct code.
diff --git a/.agents/skills/nuqs/references/advanced-custom-parsers.md b/.agents/skills/nuqs/references/advanced-custom-parsers.md
new file mode 100644
index 0000000..95c776e
--- /dev/null
+++ b/.agents/skills/nuqs/references/advanced-custom-parsers.md
@@ -0,0 +1,70 @@
+---
+title: Create Custom Parsers for Complex Types
+impact: LOW
+impactDescription: prevents runtime errors from string coercion
+tags: advanced, createParser, custom, serialize, parse
+---
+
+## Create Custom Parsers for Complex Types
+
+When built-in parsers don't fit your needs, create custom parsers with `createParser`. Define `parse`, `serialize`, and optionally `eq` for equality checking.
+
+**Incorrect (manual parsing in component):**
+
+```tsx
+'use client'
+import { useQueryState } from 'nuqs'
+
+interface SortState {
+ id: string
+ desc: boolean
+}
+
+export default function SortableTable() {
+ const [sortRaw, setSortRaw] = useQueryState('sort')
+ // Manual parsing scattered across component
+ const sort: SortState = sortRaw
+ ? { id: sortRaw.split(':')[0], desc: sortRaw.split(':')[1] === 'desc' }
+ : { id: 'name', desc: false }
+
+ const handleSort = (id: string) => {
+ // Manual serialization
+ setSortRaw(`${id}:${sort.id === id && !sort.desc ? 'desc' : 'asc'}`)
+ }
+}
+```
+
+**Correct (custom parser):**
+
+```tsx
+'use client'
+import { useQueryState, createParser } from 'nuqs'
+
+interface SortState {
+ id: string
+ desc: boolean
+}
+
+const parseAsSort = createParser({
+ parse(query) {
+ const [id = '', direction = ''] = query.split(':')
+ return { id, desc: direction === 'desc' }
+ },
+ serialize(value) {
+ return `${value.id}:${value.desc ? 'desc' : 'asc'}`
+ },
+ eq(a, b) {
+ return a.id === b.id && a.desc === b.desc
+ }
+})
+
+export default function SortableTable() {
+ const [sort, setSort] = useQueryState(
+ 'sort',
+ parseAsSort.withDefault({ id: 'name', desc: false })
+ )
+ // Type-safe, reusable, with proper equality checking
+}
+```
+
+Reference: [nuqs Custom Parsers](https://nuqs.dev/docs/parsers/making-your-own)
diff --git a/.agents/skills/nuqs/references/advanced-eq-function.md b/.agents/skills/nuqs/references/advanced-eq-function.md
new file mode 100644
index 0000000..670d0d5
--- /dev/null
+++ b/.agents/skills/nuqs/references/advanced-eq-function.md
@@ -0,0 +1,94 @@
+---
+title: Implement eq Function for Object Parsers
+impact: LOW
+impactDescription: prevents unnecessary URL updates for equivalent objects
+tags: advanced, eq, equality, objects, optimization
+---
+
+## Implement eq Function for Object Parsers
+
+When creating custom parsers for objects, implement the `eq` function to define equality. Without it, nuqs uses reference equality, causing unnecessary URL updates for equivalent but different object instances.
+
+**Incorrect (reference equality):**
+
+```tsx
+import { createParser } from 'nuqs'
+
+interface Filters {
+ minPrice: number
+ maxPrice: number
+}
+
+const parseAsFilters = createParser({
+ parse(query) {
+ const [min, max] = query.split('-').map(Number)
+ return { minPrice: min, maxPrice: max }
+ },
+ serialize({ minPrice, maxPrice }) {
+ return `${minPrice}-${maxPrice}`
+ }
+ // Missing eq - uses reference equality
+})
+
+// Problem: setting same values creates new object references
+setFilters({ minPrice: 0, maxPrice: 100 })
+setFilters({ minPrice: 0, maxPrice: 100 }) // Triggers URL update even though values are same
+```
+
+**Correct (value equality):**
+
+```tsx
+import { createParser } from 'nuqs'
+
+interface Filters {
+ minPrice: number
+ maxPrice: number
+}
+
+const parseAsFilters = createParser({
+ parse(query) {
+ const [min, max] = query.split('-').map(Number)
+ return { minPrice: min, maxPrice: max }
+ },
+ serialize({ minPrice, maxPrice }) {
+ return `${minPrice}-${maxPrice}`
+ },
+ eq(a, b) {
+ return a.minPrice === b.minPrice && a.maxPrice === b.maxPrice
+ }
+})
+
+// Now same values don't trigger unnecessary updates
+setFilters({ minPrice: 0, maxPrice: 100 })
+setFilters({ minPrice: 0, maxPrice: 100 }) // No URL update - values are equal
+```
+
+**For arrays:**
+
+```tsx
+const parseAsIdList = createParser({
+ parse(query) {
+ return query.split(',').map(Number)
+ },
+ serialize(value) {
+ return value.join(',')
+ },
+ eq(a, b) {
+ return a.length === b.length && a.every((v, i) => v === b[i])
+ }
+})
+```
+
+**For nested objects:**
+
+```tsx
+import isEqual from 'lodash/isEqual' // or deep-equal
+
+const parseAsConfig = createParser({
+ parse: JSON.parse,
+ serialize: JSON.stringify,
+ eq: isEqual // Deep equality comparison
+})
+```
+
+Reference: [nuqs Custom Parsers](https://nuqs.dev/docs/parsers/making-your-own)
diff --git a/.agents/skills/nuqs/references/advanced-framework-adapters.md b/.agents/skills/nuqs/references/advanced-framework-adapters.md
new file mode 100644
index 0000000..2ef6086
--- /dev/null
+++ b/.agents/skills/nuqs/references/advanced-framework-adapters.md
@@ -0,0 +1,82 @@
+---
+title: Use Framework-Specific Adapters
+impact: LOW
+impactDescription: prevents URL sync failures in non-Next.js apps
+tags: advanced, adapters, remix, react-router, frameworks
+---
+
+## Use Framework-Specific Adapters
+
+nuqs works with multiple React frameworks through adapters. Use the correct adapter for your framework to ensure proper URL synchronization.
+
+**Incorrect (wrong adapter for React Router):**
+
+```tsx
+// src/main.tsx
+import { NuqsAdapter } from 'nuqs/adapters/next/app' // Wrong!
+import { BrowserRouter } from 'react-router-dom'
+
+function App() {
+ return (
+
+ {/* This won't work with React Router */}
+
+
+
+ )
+}
+```
+
+**Correct (React Router v7/v8 adapter):**
+
+```tsx
+// src/main.tsx
+import { NuqsAdapter } from 'nuqs/adapters/react-router/v7'
+import { BrowserRouter } from 'react-router'
+
+function App() {
+ return (
+
+
+
+
+
+ )
+}
+```
+
+On React Router v8, import from `nuqs/adapters/react-router/v8` instead — it currently re-exports the v7 adapter, but pinning the v8 path keeps your imports correct if the implementations ever diverge.
+
+**TanStack Router (experimental):**
+
+```tsx
+// src/routes/__root.tsx
+import { NuqsAdapter } from 'nuqs/adapters/tanstack-router'
+import { Outlet, createRootRoute } from '@tanstack/react-router'
+
+export const Route = createRootRoute({
+ component: () => (
+
+
+
+ ),
+})
+```
+
+Requires `@tanstack/react-router` v1; this adapter is currently experimental.
+
+**Available adapters:**
+
+| Framework | Import Path |
+|-----------|-------------|
+| Next.js App Router | `nuqs/adapters/next/app` |
+| Next.js Pages Router | `nuqs/adapters/next/pages` |
+| React Router v6 | `nuqs/adapters/react-router/v6` |
+| React Router v7 | `nuqs/adapters/react-router/v7` |
+| React Router v8 | `nuqs/adapters/react-router/v8` |
+| TanStack Router (experimental) | `nuqs/adapters/tanstack-router` |
+| Remix | `nuqs/adapters/remix` |
+| Plain React | `nuqs/adapters/react` |
+| Testing | `nuqs/adapters/testing` |
+
+Reference: [nuqs Adapters](https://nuqs.dev/docs/adapters)
diff --git a/.agents/skills/nuqs/references/advanced-url-keys.md b/.agents/skills/nuqs/references/advanced-url-keys.md
new file mode 100644
index 0000000..f1945c9
--- /dev/null
+++ b/.agents/skills/nuqs/references/advanced-url-keys.md
@@ -0,0 +1,62 @@
+---
+title: Use urlKeys for Shorter URLs
+impact: LOW
+impactDescription: reduces URL length by 50-70% for verbose params
+tags: advanced, urlKeys, serializer, url-length, abbreviation
+---
+
+## Use urlKeys for Shorter URLs
+
+Map verbose parameter names to shorter URL keys for cleaner, more shareable URLs while keeping descriptive names in code.
+
+**Incorrect (verbose URL parameters):**
+
+```tsx
+'use client'
+import { useQueryStates, parseAsFloat, parseAsInteger } from 'nuqs'
+
+export default function MapView() {
+ const [coords, setCoords] = useQueryStates({
+ latitude: parseAsFloat.withDefault(0),
+ longitude: parseAsFloat.withDefault(0),
+ zoomLevel: parseAsInteger.withDefault(10)
+ })
+ // URL: ?latitude=48.8566&longitude=2.3522&zoomLevel=12
+ // Long, harder to share, uses more bandwidth
+
+ return
+}
+```
+
+**Correct (abbreviated URL keys):**
+
+```tsx
+'use client'
+import { useQueryStates, parseAsFloat, parseAsInteger } from 'nuqs'
+
+export default function MapView() {
+ const [coords, setCoords] = useQueryStates(
+ {
+ latitude: parseAsFloat.withDefault(0),
+ longitude: parseAsFloat.withDefault(0),
+ zoomLevel: parseAsInteger.withDefault(10)
+ },
+ {
+ urlKeys: {
+ latitude: 'lat',
+ longitude: 'lng',
+ zoomLevel: 'z'
+ }
+ }
+ )
+ // URL: ?lat=48.8566&lng=2.3522&z=12
+ // Shorter, cleaner URLs
+
+ // Code still uses descriptive names
+ console.log(coords.latitude, coords.longitude, coords.zoomLevel)
+
+ return
+}
+```
+
+Reference: [nuqs urlKeys](https://nuqs.dev/docs/utilities)
diff --git a/.agents/skills/nuqs/references/debug-common-errors.md b/.agents/skills/nuqs/references/debug-common-errors.md
new file mode 100644
index 0000000..79f0801
--- /dev/null
+++ b/.agents/skills/nuqs/references/debug-common-errors.md
@@ -0,0 +1,53 @@
+---
+title: Diagnose Common nuqs Errors
+impact: LOW-MEDIUM
+impactDescription: reduces debugging time from hours to minutes
+tags: debug, errors, troubleshooting, common-issues, hydration
+---
+
+## Diagnose Common nuqs Errors
+
+Reference for diagnosing frequent nuqs issues and their solutions.
+
+**Incorrect (missing adapter causes cryptic error):**
+
+```tsx
+// app/layout.tsx - Missing NuqsAdapter
+export default function RootLayout({ children }) {
+ return (
+
+ {children}
+
+ )
+}
+// Error: "Cannot read property 'push' of undefined"
+```
+
+**Correct (add NuqsAdapter):**
+
+```tsx
+// app/layout.tsx
+import { NuqsAdapter } from 'nuqs/adapters/next/app'
+
+export default function RootLayout({ children }) {
+ return (
+
+
+ {children}
+
+
+ )
+}
+```
+
+**Other common errors and fixes:**
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| "Hooks can only be called inside Client Components" | Missing 'use client' | Add `'use client'` directive |
+| "Uncontrolled input" warning | Value is null | Use `value={query ?? ''}` |
+| Hydration mismatch | Different defaults | Use shared parsers with withDefault |
+| URL not updating | Missing adapter or old Next.js | Check adapter and version |
+| State undefined in Server Component | Missing parse() | Call `parse()` before `get()` |
+
+Reference: [nuqs Documentation](https://nuqs.dev/docs)
diff --git a/.agents/skills/nuqs/references/debug-enable-logging.md b/.agents/skills/nuqs/references/debug-enable-logging.md
new file mode 100644
index 0000000..964d89b
--- /dev/null
+++ b/.agents/skills/nuqs/references/debug-enable-logging.md
@@ -0,0 +1,51 @@
+---
+title: Enable Debug Logging for Troubleshooting
+impact: LOW-MEDIUM
+impactDescription: reduces debugging time by 5-10×
+tags: debug, logging, localStorage, troubleshooting, devtools
+---
+
+## Enable Debug Logging for Troubleshooting
+
+Enable nuqs debug logs to understand state changes, URL updates, and timing. Useful for diagnosing issues with state synchronization or unexpected behavior.
+
+**Incorrect (no visibility into nuqs operations):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Counter() {
+ const [count, setCount] = useQueryState('count', parseAsInteger.withDefault(0))
+ // Something's not working, but no way to see what nuqs is doing
+ // Have to guess and add console.logs everywhere
+
+ return setCount(c => c + 1)}>{count}
+}
+```
+
+**Correct (enable debug logging):**
+
+```javascript
+// Run in browser DevTools console FIRST
+localStorage.debug = 'nuqs'
+// Then reload the page
+// Now you see: [nuqs] useQueryState 'count' initialized with 0
+// And: [nuqs] useQueryState 'count' updated to 1
+```
+
+**Disable when done:**
+
+```javascript
+// Run in browser DevTools console
+delete localStorage.debug
+```
+
+**Performance timing markers:**
+
+Debug mode also records User Timing markers visible in the Performance tab:
+- `nuqs:parse` - Time to parse URL parameters
+- `nuqs:serialize` - Time to serialize state to URL
+- `nuqs:update` - Time for URL update
+
+Reference: [nuqs Debugging](https://nuqs.dev/docs)
diff --git a/.agents/skills/nuqs/references/debug-testing.md b/.agents/skills/nuqs/references/debug-testing.md
new file mode 100644
index 0000000..ee7493e
--- /dev/null
+++ b/.agents/skills/nuqs/references/debug-testing.md
@@ -0,0 +1,55 @@
+---
+title: Test Components with URL State
+impact: LOW-MEDIUM
+impactDescription: enables reliable CI/CD testing of nuqs components
+tags: debug, testing, jest, vitest, react-testing-library
+---
+
+## Test Components with URL State
+
+Test components that use nuqs by providing the NuqsTestingAdapter and controlling URL state in tests.
+
+**Incorrect (test fails without adapter):**
+
+```tsx
+// components/Pagination.test.tsx
+import { render, screen } from '@testing-library/react'
+import Pagination from './Pagination'
+
+it('displays current page', () => {
+ render( ) // Fails: no NuqsAdapter
+ expect(screen.getByText('Page 1')).toBeInTheDocument()
+})
+```
+
+**Correct (use NuqsTestingAdapter):**
+
+```tsx
+// test/utils.tsx
+import { NuqsTestingAdapter } from 'nuqs/adapters/testing'
+import { render, type RenderOptions } from '@testing-library/react'
+
+export function renderWithNuqs(
+ ui: React.ReactElement,
+ { searchParams = {}, ...options }: RenderOptions & { searchParams?: Record } = {}
+) {
+ return render(
+
+ {ui}
+ ,
+ options
+ )
+}
+
+// components/Pagination.test.tsx
+import { screen } from '@testing-library/react'
+import { renderWithNuqs } from '@/test/utils'
+import Pagination from './Pagination'
+
+it('displays current page from URL', () => {
+ renderWithNuqs( , { searchParams: { page: '5' } })
+ expect(screen.getByText('Page 5')).toBeInTheDocument()
+})
+```
+
+Reference: [nuqs Testing Adapter](https://nuqs.dev/docs/testing)
diff --git a/.agents/skills/nuqs/references/history-back-sync.md b/.agents/skills/nuqs/references/history-back-sync.md
new file mode 100644
index 0000000..205dc0b
--- /dev/null
+++ b/.agents/skills/nuqs/references/history-back-sync.md
@@ -0,0 +1,51 @@
+---
+title: Handle Browser Back/Forward Navigation
+impact: MEDIUM
+impactDescription: prevents stale UI after browser navigation
+tags: history, back-button, forward, popstate, sync
+---
+
+## Handle Browser Back/Forward Navigation
+
+nuqs automatically syncs state with URL when users navigate with browser back/forward buttons. Ensure your UI handles these state changes correctly.
+
+**Incorrect (local state gets out of sync):**
+
+```tsx
+'use client'
+import { useState, useEffect } from 'react'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [urlPage] = useQueryState('page', parseAsInteger.withDefault(1))
+ const [localPage, setLocalPage] = useState(urlPage)
+ // User navigates back - urlPage updates but localPage doesn't!
+
+ return Page {localPage}
// Shows stale value
+}
+```
+
+**Correct (use URL state directly):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1).withOptions({
+ history: 'push'
+ }))
+ // User: page 1 → 2 → 3
+ // Back button: page becomes 2 (automatic)
+ // UI re-renders with new page value
+
+ return (
+
+
Page {page}
+
setPage(p => p + 1)}>Next
+
+ )
+}
+```
+
+Reference: [nuqs Documentation](https://nuqs.dev/docs)
diff --git a/.agents/skills/nuqs/references/history-push-navigation.md b/.agents/skills/nuqs/references/history-push-navigation.md
new file mode 100644
index 0000000..b545e1f
--- /dev/null
+++ b/.agents/skills/nuqs/references/history-push-navigation.md
@@ -0,0 +1,76 @@
+---
+title: Use history:push for Navigation-Like State
+impact: MEDIUM
+impactDescription: enables back button for state navigation
+tags: history, push, navigation, back-button, ux
+---
+
+## Use history:push for Navigation-Like State
+
+Use `history: 'push'` when state changes represent navigation that users would expect to undo with the back button (pagination, tabs, modal state).
+
+**Incorrect (replace loses navigation history):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
+ // history: 'replace' (default)
+ // User clicks page 1 → 2 → 3 → back button → leaves site!
+
+ return (
+
+ setPage(p => p - 1)}>Previous
+ Page {page}
+ setPage(p => p + 1)}>Next
+
+ )
+}
+```
+
+**Correct (push enables back navigation):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1).withOptions({
+ history: 'push'
+ }))
+ // User clicks page 1 → 2 → 3 → back button → page 2
+
+ return (
+
+ setPage(p => p - 1)}>Previous
+ Page {page}
+ setPage(p => p + 1)}>Next
+
+ )
+}
+```
+
+**Typical use cases for history:push:**
+- Pagination
+- Tab selection
+- Modal open/close state
+- Step-by-step wizards
+- Filter panel expansion
+
+**Mix modes when needed:**
+
+```tsx
+const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1).withOptions({
+ history: 'push'
+}))
+
+// Programmatic navigation pushes
+setPage(5)
+
+// But "reset" replaces to avoid back-button spam
+setPage(1, { history: 'replace' })
+```
+
+Reference: [nuqs History Option](https://nuqs.dev/docs/options)
diff --git a/.agents/skills/nuqs/references/history-replace-ephemeral.md b/.agents/skills/nuqs/references/history-replace-ephemeral.md
new file mode 100644
index 0000000..77b03f5
--- /dev/null
+++ b/.agents/skills/nuqs/references/history-replace-ephemeral.md
@@ -0,0 +1,87 @@
+---
+title: Use history:replace for Ephemeral State
+impact: MEDIUM
+impactDescription: prevents history pollution from frequent updates
+tags: history, replace, ephemeral, typing, slider
+---
+
+## Use history:replace for Ephemeral State
+
+Use `history: 'replace'` (default) for state that changes frequently or represents intermediate values users wouldn't want to navigate through (typing, sliders, filters).
+
+**Correct (replace for typing):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function SearchBox() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault(''))
+ // history: 'replace' (default)
+ // Typing "react" doesn't create 5 history entries
+
+ return (
+ setQuery(e.target.value)}
+ placeholder="Search..."
+ />
+ )
+}
+```
+
+**Incorrect (push for typing):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function SearchBox() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault('').withOptions({
+ history: 'push' // Don't do this!
+ }))
+ // Typing "react" creates entries: r, re, rea, reac, react
+ // Back button is unusable
+
+ return (
+ setQuery(e.target.value)}
+ />
+ )
+}
+```
+
+**Typical use cases for history:replace (default):**
+- Search input text
+- Slider/range values
+- Real-time filter changes
+- Sort order selection
+- Any rapidly-changing state
+
+**Hybrid pattern (replace during typing, push on submit):**
+
+```tsx
+'use client'
+import { useState } from 'react'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function SearchForm() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault(''))
+ const [input, setInput] = useState(query)
+
+ const handleSubmit = (e: React.FormEvent) => {
+ e.preventDefault()
+ setQuery(input, { history: 'push' }) // Push on explicit submit
+ }
+
+ return (
+
+ setInput(e.target.value)} />
+ Search
+
+ )
+}
+```
+
+Reference: [nuqs History Option](https://nuqs.dev/docs/options)
diff --git a/.agents/skills/nuqs/references/history-scroll-behavior.md b/.agents/skills/nuqs/references/history-scroll-behavior.md
new file mode 100644
index 0000000..2c41343
--- /dev/null
+++ b/.agents/skills/nuqs/references/history-scroll-behavior.md
@@ -0,0 +1,60 @@
+---
+title: Control Scroll Behavior on URL Changes
+impact: MEDIUM
+impactDescription: prevents jarring scroll jumps on state changes
+tags: history, scroll, ux, navigation, viewport
+---
+
+## Control Scroll Behavior on URL Changes
+
+By default, nuqs doesn't scroll on URL changes. Use the `scroll` option to control whether state changes scroll to the top of the page.
+
+**Incorrect (unwanted scroll on filter change):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function FilterPanel() {
+ const [filter, setFilter] = useQueryState('filter', parseAsString.withDefault('').withOptions({
+ scroll: true // Bad for filters - user loses their place!
+ }))
+
+ return (
+ setFilter(e.target.value)}>
+ All
+ Active
+
+ )
+}
+```
+
+**Correct (no scroll for filters, scroll for pagination):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString, parseAsInteger } from 'nuqs'
+
+export default function SearchPage() {
+ // No scroll for filters - user stays in place
+ const [filter, setFilter] = useQueryState('filter', parseAsString.withDefault(''))
+
+ // Scroll for pagination - user sees new content from top
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1).withOptions({
+ scroll: true,
+ history: 'push'
+ }))
+
+ return (
+
+ setFilter(e.target.value)}>
+ All
+ Active
+
+ setPage(p => p + 1)}>Next Page
+
+ )
+}
+```
+
+Reference: [nuqs Scroll Option](https://nuqs.dev/docs/options)
diff --git a/.agents/skills/nuqs/references/parser-array-format.md b/.agents/skills/nuqs/references/parser-array-format.md
new file mode 100644
index 0000000..2ade6b0
--- /dev/null
+++ b/.agents/skills/nuqs/references/parser-array-format.md
@@ -0,0 +1,59 @@
+---
+title: Choose Correct Array Parser Format
+impact: CRITICAL
+impactDescription: prevents API integration failures from wrong URL format
+tags: parser, parseAsArrayOf, parseAsNativeArrayOf, arrays, url-format
+---
+
+## Choose Correct Array Parser Format
+
+nuqs offers two array formats with different URL representations. Choose based on your backend API expectations and URL readability requirements.
+
+**Incorrect (wrong format for backend):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsArrayOf, parseAsString } from 'nuqs'
+
+export default function TagFilter() {
+ const [tags, setTags] = useQueryState(
+ 'tags',
+ parseAsArrayOf(parseAsString).withDefault([])
+ )
+ // URL: ?tags=react,nextjs
+ // But backend expects: ?tag=react&tag=nextjs
+ // API receives single string "react,nextjs" instead of array!
+}
+```
+
+**Correct (match backend expectations):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsNativeArrayOf, parseAsString } from 'nuqs'
+
+export default function TagFilter() {
+ const [tags, setTags] = useQueryState(
+ 'tag', // Note: singular key name
+ parseAsNativeArrayOf(parseAsString).withDefault([])
+ )
+ // URL: ?tag=react&tag=nextjs
+ // Backend correctly receives array ['react', 'nextjs']
+
+ return (
+
+ Tags: {tags.join(', ')}
+ setTags([...tags, 'new-tag'])}>Add
+
+ )
+}
+```
+
+**When to use each:**
+
+| Format | URL Example | Use When |
+|--------|-------------|----------|
+| `parseAsArrayOf` | `?ids=1,2,3` | Compact URLs, numeric IDs, custom backends |
+| `parseAsNativeArrayOf` | `?tag=a&tag=b` | Standard form encoding, PHP/Rails backends |
+
+Reference: [nuqs Array Parsers](https://nuqs.dev/docs/parsers)
diff --git a/.agents/skills/nuqs/references/parser-date-format.md b/.agents/skills/nuqs/references/parser-date-format.md
new file mode 100644
index 0000000..7b857e9
--- /dev/null
+++ b/.agents/skills/nuqs/references/parser-date-format.md
@@ -0,0 +1,67 @@
+---
+title: Select Appropriate Date Parser
+impact: CRITICAL
+impactDescription: prevents timezone bugs and parsing failures
+tags: parser, parseAsTimestamp, parseAsIsoDateTime, parseAsIsoDate, dates
+---
+
+## Select Appropriate Date Parser
+
+nuqs provides three date parsers with different URL formats and precision. Choose based on your requirements for time precision and URL readability.
+
+**Incorrect (wrong parser for use case):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsIsoDateTime } from 'nuqs'
+
+export default function DateRangePicker() {
+ const [startDate, setStartDate] = useQueryState('start', parseAsIsoDateTime)
+ // URL: ?start=2024-01-01T00:00:00.000Z
+ // Problem: User selected "Jan 1" but URL shows timezone complexity
+ // Better: Use parseAsIsoDate for date-only pickers
+
+ return (
+ setStartDate(new Date(e.target.value))}
+ />
+ )
+}
+```
+
+**Correct (match parser to use case):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsIsoDate, parseAsTimestamp } from 'nuqs'
+
+export default function DateRangePicker() {
+ // For date-only picker: clean URL
+ const [startDate, setStartDate] = useQueryState('start', parseAsIsoDate)
+ // URL: ?start=2024-01-01
+
+ // For precise timestamps: use parseAsTimestamp
+ const [lastModified, setLastModified] = useQueryState('modified', parseAsTimestamp)
+ // URL: ?modified=1704067200000
+
+ return (
+ setStartDate(new Date(e.target.value))}
+ />
+ )
+}
+```
+
+**When to use each:**
+
+| Parser | URL Format | Use Case |
+|--------|------------|----------|
+| `parseAsTimestamp` | `1704067200000` | Precise timestamps, API integration |
+| `parseAsIsoDateTime` | `2024-01-01T12:00:00.000Z` | Debugging, shareable URLs with time |
+| `parseAsIsoDate` | `2024-01-01` | Date pickers, calendar views |
+
+Reference: [nuqs Date Parsers](https://nuqs.dev/docs/parsers)
diff --git a/.agents/skills/nuqs/references/parser-enum-validation.md b/.agents/skills/nuqs/references/parser-enum-validation.md
new file mode 100644
index 0000000..5fc29c5
--- /dev/null
+++ b/.agents/skills/nuqs/references/parser-enum-validation.md
@@ -0,0 +1,81 @@
+---
+title: Use Enum Parsers for Constrained Values
+impact: CRITICAL
+impactDescription: prevents invalid state from URL manipulation
+tags: parser, parseAsStringEnum, parseAsStringLiteral, validation, security
+---
+
+## Use Enum Parsers for Constrained Values
+
+When state should only accept specific values (like status, sort direction, or view mode), use enum or literal parsers. This prevents invalid values from URL tampering and provides type safety.
+
+**Incorrect (accepts any string):**
+
+```tsx
+'use client'
+import { useQueryState } from 'nuqs'
+
+type SortOrder = 'asc' | 'desc'
+
+export default function SortableList() {
+ const [sort, setSort] = useQueryState('sort')
+ // sort is string | null - accepts ANY value
+ // URL: ?sort=malicious works silently
+
+ const sortOrder = sort as SortOrder // Unsafe cast!
+
+ return (
+ setSort(e.target.value)}
+ >
+ Ascending
+ Descending
+
+ )
+}
+```
+
+**Correct (validated enum):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsStringLiteral } from 'nuqs'
+
+const sortOrders = ['asc', 'desc'] as const
+
+export default function SortableList() {
+ const [sort, setSort] = useQueryState(
+ 'sort',
+ parseAsStringLiteral(sortOrders).withDefault('asc')
+ )
+ // sort is 'asc' | 'desc' - invalid values return null/default
+ // URL: ?sort=malicious → falls back to 'asc'
+
+ return (
+ setSort(e.target.value as typeof sort)}>
+ Ascending
+ Descending
+
+ )
+}
+```
+
+**Alternative (TypeScript enum):**
+
+```tsx
+import { parseAsStringEnum } from 'nuqs'
+
+enum Status {
+ Active = 'active',
+ Inactive = 'inactive',
+ Pending = 'pending'
+}
+
+const [status, setStatus] = useQueryState(
+ 'status',
+ parseAsStringEnum(Object.values(Status)).withDefault(Status.Active)
+)
+```
+
+Reference: [nuqs Enum Parsers](https://nuqs.dev/docs/parsers)
diff --git a/.agents/skills/nuqs/references/parser-hex-colors.md b/.agents/skills/nuqs/references/parser-hex-colors.md
new file mode 100644
index 0000000..60ddc17
--- /dev/null
+++ b/.agents/skills/nuqs/references/parser-hex-colors.md
@@ -0,0 +1,68 @@
+---
+title: Use parseAsHex for Color Values
+impact: MEDIUM
+impactDescription: 50% shorter URLs for color parameters
+tags: parser, parseAsHex, colors, hexadecimal
+---
+
+## Use parseAsHex for Color Values
+
+When storing color values in URLs, `parseAsHex` provides cleaner hexadecimal representation instead of decimal numbers.
+
+**Incorrect (decimal in URL):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function ColorPicker() {
+ const [color, setColor] = useQueryState(
+ 'color',
+ parseAsInteger.withDefault(0xff0000)
+ )
+ // URL: ?color=16711680 (not human-readable)
+
+ const hexString = color.toString(16).padStart(6, '0')
+
+ return (
+ setColor(parseInt(e.target.value.slice(1), 16))}
+ />
+ )
+}
+```
+
+**Correct (hex in URL):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsHex } from 'nuqs'
+
+export default function ColorPicker() {
+ const [color, setColor] = useQueryState(
+ 'color',
+ parseAsHex.withDefault(0xff0000)
+ )
+ // URL: ?color=ff0000 (human-readable)
+ // State: 16711680 (number for calculations)
+
+ const hexString = color.toString(16).padStart(6, '0')
+
+ return (
+ setColor(parseInt(e.target.value.slice(1), 16))}
+ />
+ )
+}
+```
+
+**Benefits:**
+- URLs are readable: `?color=ff0000` vs `?color=16711680`
+- State is numeric for calculations
+- Standard hex color format in URL
+
+Reference: [nuqs parseAsHex](https://nuqs.dev/docs/parsers)
diff --git a/.agents/skills/nuqs/references/parser-index-offset.md b/.agents/skills/nuqs/references/parser-index-offset.md
new file mode 100644
index 0000000..8ad2bca
--- /dev/null
+++ b/.agents/skills/nuqs/references/parser-index-offset.md
@@ -0,0 +1,72 @@
+---
+title: Use parseAsIndex for 1-Based URL Display
+impact: HIGH
+impactDescription: eliminates off-by-one errors between URL and code
+tags: parser, parseAsIndex, pagination, zero-indexed, one-indexed
+---
+
+## Use parseAsIndex for 1-Based URL Display
+
+Arrays are 0-indexed in JavaScript, but users expect 1-indexed URLs (page 1, item 1). `parseAsIndex` automatically converts between them.
+
+**Incorrect (manual conversion):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
+ // URL: ?page=1
+ // Array index: need page - 1 everywhere
+
+ const items = ['a', 'b', 'c', 'd', 'e']
+ const currentItem = items[page - 1] // Manual conversion
+
+ return (
+
+
Page {page}: {currentItem}
+
setPage(p => p + 1)}>Next
+
+ )
+}
+```
+
+**Correct (automatic conversion):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsIndex } from 'nuqs'
+
+export default function Pagination() {
+ const [pageIndex, setPageIndex] = useQueryState(
+ 'page',
+ parseAsIndex.withDefault(0)
+ )
+ // URL: ?page=1 (user-friendly, 1-indexed)
+ // State: 0 (code-friendly, 0-indexed)
+
+ const items = ['a', 'b', 'c', 'd', 'e']
+ const currentItem = items[pageIndex] // Direct array access
+
+ return (
+
+
Page {pageIndex + 1}: {currentItem}
+
setPageIndex(i => i + 1)}>Next
+
+ )
+}
+```
+
+**How it works:**
+- URL `?page=1` → State `0`
+- URL `?page=5` → State `4`
+- State `0` → URL `?page=1`
+- State `4` → URL `?page=5`
+
+**Benefits:**
+- No off-by-one bugs
+- Array indices work directly
+- URLs are human-friendly
+
+Reference: [nuqs parseAsIndex](https://nuqs.dev/docs/parsers)
diff --git a/.agents/skills/nuqs/references/parser-json-validation.md b/.agents/skills/nuqs/references/parser-json-validation.md
new file mode 100644
index 0000000..51e3054
--- /dev/null
+++ b/.agents/skills/nuqs/references/parser-json-validation.md
@@ -0,0 +1,97 @@
+---
+title: Validate JSON Parser Input
+impact: CRITICAL
+impactDescription: prevents runtime crashes from malformed URL data
+tags: parser, parseAsJson, validation, type-guard, security
+---
+
+## Validate JSON Parser Input
+
+`parseAsJson` accepts a validation function. Without validation, malformed or malicious JSON in the URL causes runtime errors or security issues.
+
+**Incorrect (no validation):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsJson } from 'nuqs'
+
+interface Filters {
+ minPrice: number
+ maxPrice: number
+ categories: string[]
+}
+
+export default function FilterPanel() {
+ const [filters, setFilters] = useQueryState(
+ 'filters',
+ parseAsJson() // No validation!
+ )
+ // URL: ?filters={"malicious":true} passes through
+ // URL: ?filters=notjson crashes
+
+ return {filters?.minPrice}
+}
+```
+
+**Correct (with validation):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsJson } from 'nuqs'
+
+interface Filters {
+ minPrice: number
+ maxPrice: number
+ categories: string[]
+}
+
+function isValidFilters(value: unknown): value is Filters {
+ if (!value || typeof value !== 'object') return false
+ const obj = value as Record
+ return (
+ typeof obj.minPrice === 'number' &&
+ typeof obj.maxPrice === 'number' &&
+ Array.isArray(obj.categories) &&
+ obj.categories.every(c => typeof c === 'string')
+ )
+}
+
+export default function FilterPanel() {
+ const [filters, setFilters] = useQueryState(
+ 'filters',
+ parseAsJson(isValidFilters).withDefault({
+ minPrice: 0,
+ maxPrice: 1000,
+ categories: []
+ })
+ )
+ // Invalid JSON returns null, falls back to default
+
+ return (
+
+ Price: {filters.minPrice} - {filters.maxPrice}
+
+ )
+}
+```
+
+**Alternative (with Zod):**
+
+```tsx
+import { z } from 'zod'
+
+const FiltersSchema = z.object({
+ minPrice: z.number(),
+ maxPrice: z.number(),
+ categories: z.array(z.string())
+})
+
+const [filters, setFilters] = useQueryState(
+ 'filters',
+ parseAsJson>(
+ (value) => FiltersSchema.safeParse(value).success ? value : null
+ )
+)
+```
+
+Reference: [nuqs JSON Parser](https://nuqs.dev/docs/parsers)
diff --git a/.agents/skills/nuqs/references/parser-use-typed-parsers.md b/.agents/skills/nuqs/references/parser-use-typed-parsers.md
new file mode 100644
index 0000000..6c9daa4
--- /dev/null
+++ b/.agents/skills/nuqs/references/parser-use-typed-parsers.md
@@ -0,0 +1,58 @@
+---
+title: Use Typed Parsers for Non-String Values
+impact: CRITICAL
+impactDescription: prevents runtime type errors and hydration mismatches
+tags: parser, type-safety, parseAsInteger, parseAsFloat, parseAsBoolean
+---
+
+## Use Typed Parsers for Non-String Values
+
+URL query parameters are always strings. Without typed parsers, you'll get string values where you expect numbers or booleans, causing type errors and incorrect comparisons.
+
+**Incorrect (string instead of number):**
+
+```tsx
+'use client'
+import { useQueryState } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page')
+ // page is string | null, not number
+ // page + 1 = "11" not 2 when page is "1"
+
+ return (
+ setPage(String(Number(page) + 1))}>
+ Next Page
+
+ )
+}
+```
+
+**Correct (typed parser):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger)
+ // page is number | null
+ // Arithmetic works correctly
+
+ return (
+ setPage((p) => (p ?? 0) + 1)}>
+ Next Page
+
+ )
+}
+```
+
+**Available parsers:**
+- `parseAsInteger` - integers
+- `parseAsFloat` - decimal numbers
+- `parseAsBoolean` - true/false
+- `parseAsTimestamp` - Date from milliseconds
+- `parseAsIsoDateTime` - Date from ISO string
+- `parseAsJson()` - JSON objects
+
+Reference: [nuqs Parsers Documentation](https://nuqs.dev/docs/parsers)
diff --git a/.agents/skills/nuqs/references/parser-with-default.md b/.agents/skills/nuqs/references/parser-with-default.md
new file mode 100644
index 0000000..c94bd97
--- /dev/null
+++ b/.agents/skills/nuqs/references/parser-with-default.md
@@ -0,0 +1,65 @@
+---
+title: Use withDefault for Non-Nullable State
+impact: CRITICAL
+impactDescription: eliminates null checks throughout component tree
+tags: parser, withDefault, null-safety, type-inference
+---
+
+## Use withDefault for Non-Nullable State
+
+Without `withDefault`, query state is always nullable (`T | null`). This forces null checks everywhere the value is used. Use `withDefault` to provide a fallback value and get non-nullable types.
+
+**Incorrect (nullable state, null checks everywhere):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Counter() {
+ const [count, setCount] = useQueryState('count', parseAsInteger)
+ // count is number | null
+
+ return (
+
+ {/* Null check required */}
+
Count: {count ?? 0}
+ {/* Null check required */}
+
setCount((count ?? 0) + 1)}>
+ Increment
+
+
+ )
+}
+```
+
+**Correct (non-nullable with default):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Counter() {
+ const [count, setCount] = useQueryState(
+ 'count',
+ parseAsInteger.withDefault(0)
+ )
+ // count is number (never null)
+
+ return (
+
+
Count: {count}
+
setCount(c => c + 1)}>
+ Increment
+
+
+ )
+}
+```
+
+**Benefits:**
+- TypeScript infers non-nullable type
+- No null coalescing needed
+- Functional updates work without null checks
+- Default appears in URL only when `clearOnDefault: false`
+
+Reference: [nuqs withDefault](https://nuqs.dev/docs/parsers)
diff --git a/.agents/skills/nuqs/references/perf-avoid-rerender.md b/.agents/skills/nuqs/references/perf-avoid-rerender.md
new file mode 100644
index 0000000..9dd3a4a
--- /dev/null
+++ b/.agents/skills/nuqs/references/perf-avoid-rerender.md
@@ -0,0 +1,88 @@
+---
+title: Memoize Components Using URL State
+impact: MEDIUM
+impactDescription: prevents unnecessary re-renders on URL changes
+tags: perf, memo, re-renders, optimization, react
+---
+
+## Memoize Components Using URL State
+
+When URL state changes, all components using that state re-render. Use `React.memo` and extract URL-dependent logic to prevent cascading re-renders.
+
+**Incorrect (entire page re-renders):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function SearchPage() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault(''))
+
+ return (
+
+
+ {/* Re-renders on every query change */}
+
+
+ )
+}
+
+function ExpensiveSidebar() {
+ // Heavy computation that doesn't need query
+ return
+}
+```
+
+**Correct (memoized components):**
+
+```tsx
+'use client'
+import { memo } from 'react'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function SearchPage() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault(''))
+
+ return (
+
+
+ {/* Memoized - doesn't re-render */}
+
+
+ )
+}
+
+const ExpensiveSidebar = memo(function ExpensiveSidebar() {
+ return
+})
+```
+
+**Alternative (extract hook usage):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString } from 'nuqs'
+
+// Only this component re-renders on query change
+function SearchSection() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault(''))
+
+ return (
+ <>
+
+
+ >
+ )
+}
+
+export default function SearchPage() {
+ return (
+
+
+ {/* Not affected by query changes */}
+
+ )
+}
+```
+
+Reference: [React memo](https://react.dev/reference/react/memo)
diff --git a/.agents/skills/nuqs/references/perf-clear-on-default.md b/.agents/skills/nuqs/references/perf-clear-on-default.md
new file mode 100644
index 0000000..c55dff2
--- /dev/null
+++ b/.agents/skills/nuqs/references/perf-clear-on-default.md
@@ -0,0 +1,55 @@
+---
+title: Use clearOnDefault for Clean URLs
+impact: MEDIUM
+impactDescription: reduces URL length by 20-50% for default values
+tags: perf, clearOnDefault, url-cleanup, defaults, seo
+---
+
+## Use clearOnDefault for Clean URLs
+
+By default, nuqs removes parameters from the URL when they match the default value. This keeps URLs clean. Set `clearOnDefault: false` only when you need the parameter always visible.
+
+**Incorrect (default always shown in URL):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1).withOptions({
+ clearOnDefault: false // Unnecessary!
+ }))
+ // URL always shows ?page=1 even on first page
+ // Clutters shareable URLs, hurts SEO
+
+ return setPage(1)}>First
+}
+```
+
+**Correct (clean URLs by default):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
+ // clearOnDefault: true (default)
+ // page=1: URL is /search (clean)
+ // page=2: URL is /search?page=2
+
+ return (
+
+ setPage(1)}>First
+ setPage(p => p + 1)}>Next
+
+ )
+}
+```
+
+**When clearOnDefault: false is appropriate:**
+- Analytics tracking requires all parameters
+- API expects explicit parameter even for default
+- Debugging where you need to see all state
+
+Reference: [nuqs clearOnDefault](https://nuqs.dev/docs/options)
diff --git a/.agents/skills/nuqs/references/perf-debounce-search.md b/.agents/skills/nuqs/references/perf-debounce-search.md
new file mode 100644
index 0000000..9b9de59
--- /dev/null
+++ b/.agents/skills/nuqs/references/perf-debounce-search.md
@@ -0,0 +1,82 @@
+---
+title: Debounce Server-Bound Search Updates
+impact: MEDIUM
+impactDescription: avoids a server request for each intermediate search value
+tags: perf, debounce, limitUrlUpdates, search, server-load
+---
+
+## Debounce Server-Bound Search Updates
+
+For `shallow: false` searches, use nuqs' `debounce()` rate limit so the URL and server update after typing settles. The hook state still updates immediately. Prefer a call-level debounce because clearing the field or pressing Enter usually needs an immediate update.
+
+**Incorrect (every value triggers server navigation):**
+
+```tsx
+const [query, setQuery] = useQueryState(
+ 'q',
+ parseAsString.withOptions({ shallow: false })
+)
+
+ setQuery(event.target.value)} />
+```
+
+**Correct (rate-limit the server-bound URL update):**
+
+```tsx
+'use client'
+
+import { useTransition } from 'react'
+import {
+ debounce,
+ defaultRateLimit,
+ parseAsString,
+ useQueryState,
+} from 'nuqs'
+
+export default function SearchBox() {
+ const [isPending, startTransition] = useTransition()
+ const [query, setQuery] = useQueryState(
+ 'q',
+ parseAsString.withDefault('').withOptions({
+ shallow: false,
+ startTransition,
+ })
+ )
+
+ return (
+
+ Search
+ {
+ const value = event.target.value
+ void setQuery(value || null, {
+ limitUrlUpdates:
+ value === '' ? defaultRateLimit : debounce(500),
+ })
+ }}
+ onKeyDown={(event) => {
+ if (event.key === 'Enter') {
+ void setQuery(query || null, {
+ limitUrlUpdates: defaultRateLimit,
+ })
+ }
+ }}
+ />
+ {isPending ? Searching… : null}
+
+ )
+}
+```
+
+Debouncing URL writes is intended for server-side fetching through RSCs or route loaders. If TanStack Query or another client library fetches from the hook's returned state, debounce that state before invoking the client query instead; nuqs state itself is immediate.
+
+`useDeferredValue` defers rendering work; it does not impose a fixed debounce window and is not a substitute for controlling server request frequency:
+
+```tsx
+// This can defer rendering but does not guarantee one request after 500 ms.
+const deferredQuery = useDeferredValue(query)
+useQuery({ queryKey: ['search', deferredQuery], queryFn: search })
+```
+
+Reference: [nuqs debounce option](https://nuqs.dev/docs/options#debounce)
diff --git a/.agents/skills/nuqs/references/perf-serialize-utility.md b/.agents/skills/nuqs/references/perf-serialize-utility.md
new file mode 100644
index 0000000..0159cc1
--- /dev/null
+++ b/.agents/skills/nuqs/references/perf-serialize-utility.md
@@ -0,0 +1,81 @@
+---
+title: Use createSerializer for Link URLs
+impact: MEDIUM
+impactDescription: enables SSR-compatible URL generation without hooks
+tags: perf, createSerializer, links, navigation, ssr
+---
+
+## Use createSerializer for Link URLs
+
+When generating URLs for links or navigation without needing state, use `createSerializer`. This avoids unnecessary hook usage and works in Server Components.
+
+**Incorrect (hook for URL generation only):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function PaginationLinks({ totalPages }: { totalPages: number }) {
+ const [page] = useQueryState('page', parseAsInteger.withDefault(1))
+
+ // Using state just to generate URLs
+ return (
+
+ {Array.from({ length: totalPages }, (_, i) => (
+
+ {i + 1}
+
+ ))}
+
+ )
+}
+```
+
+**Correct (serializer utility):**
+
+```tsx
+// lib/searchParams.ts
+import { createSerializer, parseAsInteger, parseAsString } from 'nuqs/server'
+
+export const searchParams = {
+ q: parseAsString,
+ page: parseAsInteger.withDefault(1)
+}
+
+export const serialize = createSerializer(searchParams)
+
+// components/PaginationLinks.tsx (can be Server Component)
+import { serialize } from '@/lib/searchParams'
+
+export default function PaginationLinks({ totalPages }: { totalPages: number }) {
+ return (
+
+ {Array.from({ length: totalPages }, (_, i) => (
+
+ {i + 1}
+
+ ))}
+
+ )
+}
+```
+
+**Building on existing URL:**
+
+```tsx
+import { serialize } from '@/lib/searchParams'
+
+// Preserve existing params, change page
+const currentParams = { q: 'react', page: 1 }
+const nextPageUrl = `?${serialize({ ...currentParams, page: 2 })}`
+// Result: ?q=react&page=2
+```
+
+**With base URL:**
+
+```tsx
+const url = serialize('/search', { q: 'react', page: 1 })
+// Result: /search?q=react&page=1
+```
+
+Reference: [nuqs createSerializer](https://nuqs.dev/docs/utilities)
diff --git a/.agents/skills/nuqs/references/perf-throttle-updates.md b/.agents/skills/nuqs/references/perf-throttle-updates.md
new file mode 100644
index 0000000..796fe76
--- /dev/null
+++ b/.agents/skills/nuqs/references/perf-throttle-updates.md
@@ -0,0 +1,66 @@
+---
+title: Throttle Rapid URL Updates
+impact: MEDIUM
+impactDescription: respects browser History API limits and bounds server updates
+tags: perf, limitUrlUpdates, throttle, rate-limiting, slider
+---
+
+## Throttle Rapid URL Updates
+
+nuqs already applies a browser-adapted default throttle to URL writes. Increase it only when high-frequency state changes should update the URL or a `shallow: false` server route less often. Since nuqs 2.5, use `limitUrlUpdates: throttle(ms)`; `throttleMs` is deprecated.
+
+**Incorrect (deprecated option):**
+
+```tsx
+useQueryState(
+ 'volume',
+ parseAsInteger.withDefault(50).withOptions({ throttleMs: 100 })
+)
+```
+
+When the default browser-adapted limit is sufficient, no custom option is needed:
+
+```tsx
+const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
+```
+
+**Correct (current rate-limit API):**
+
+```tsx
+'use client'
+
+import { parseAsInteger, throttle, useQueryState } from 'nuqs'
+
+export default function VolumeSlider() {
+ const [volume, setVolume] = useQueryState(
+ 'volume',
+ parseAsInteger.withDefault(50).withOptions({
+ limitUrlUpdates: throttle(100),
+ })
+ )
+
+ return (
+ setVolume(Number(event.target.value))}
+ />
+ )
+}
+```
+
+The hook state updates immediately; only the URL write and any `shallow: false` server request are rate-limited.
+
+Use a call-level override when one update must bypass the configured throttle:
+
+```tsx
+import { defaultRateLimit } from 'nuqs'
+
+await setVolume(50, { limitUrlUpdates: defaultRateLimit })
+```
+
+Use `debounce()` rather than `throttle()` when only the final high-frequency value matters. Values below nuqs/browser minimums may be ignored, so do not use a zero-duration throttle as an "immediate" escape hatch.
+
+Reference: [nuqs rate-limiting options](https://nuqs.dev/docs/options#rate-limiting-url-updates)
diff --git a/.agents/skills/nuqs/references/server-next15-async.md b/.agents/skills/nuqs/references/server-next15-async.md
new file mode 100644
index 0000000..b85ee52
--- /dev/null
+++ b/.agents/skills/nuqs/references/server-next15-async.md
@@ -0,0 +1,80 @@
+---
+title: Handle Async searchParams in Next.js 15+
+impact: HIGH
+impactDescription: prevents build errors in Next.js 15 with async props
+tags: server, nextjs15, async, searchParams, promise
+---
+
+## Handle Async searchParams in Next.js 15+
+
+In Next.js 15+, `searchParams` is a Promise that must be awaited. Using it directly without await causes TypeScript errors and runtime issues.
+
+**Incorrect (Next.js 15+ without await):**
+
+```tsx
+// app/search/page.tsx
+import { searchParamsCache } from '@/lib/searchParams'
+
+type PageProps = {
+ searchParams: { q?: string } // Wrong type for Next.js 15+
+}
+
+export default async function SearchPage({ searchParams }: PageProps) {
+ // searchParams is a Promise, not an object
+ const { q } = searchParamsCache.parse(searchParams) // Type error
+}
+```
+
+**Correct (Next.js 15+):**
+
+```tsx
+// app/search/page.tsx
+import { searchParamsCache } from '@/lib/searchParams'
+import type { SearchParams } from 'nuqs/server'
+
+type PageProps = {
+ searchParams: Promise // Correct type
+}
+
+export default async function SearchPage({ searchParams }: PageProps) {
+ // Await the Promise
+ const { q, page } = await searchParamsCache.parse(searchParams)
+
+ return
+}
+```
+
+**For Next.js 14 and earlier:**
+
+```tsx
+// app/search/page.tsx
+import { searchParamsCache } from '@/lib/searchParams'
+
+type PageProps = {
+ searchParams: Record
+}
+
+export default function SearchPage({ searchParams }: PageProps) {
+ // No await needed in Next.js 14
+ const { q, page } = searchParamsCache.parse(searchParams)
+
+ return
+}
+```
+
+**Version-agnostic pattern:**
+
+```tsx
+import type { SearchParams } from 'nuqs/server'
+
+type PageProps = {
+ searchParams: Promise
+}
+
+export default async function SearchPage({ searchParams }: PageProps) {
+ // Works in both Next.js 14 and 15
+ const { q } = await searchParamsCache.parse(searchParams)
+}
+```
+
+Reference: [Next.js 15 Migration](https://nextjs.org/docs/app/building-your-application/upgrading/version-15)
diff --git a/.agents/skills/nuqs/references/server-parse-before-get.md b/.agents/skills/nuqs/references/server-parse-before-get.md
new file mode 100644
index 0000000..11d135a
--- /dev/null
+++ b/.agents/skills/nuqs/references/server-parse-before-get.md
@@ -0,0 +1,82 @@
+---
+title: Call parse() Before get() in Server Components
+impact: HIGH
+impactDescription: prevents undefined values and runtime errors
+tags: server, parse, get, searchParamsCache, initialization
+---
+
+## Call parse() Before get() in Server Components
+
+`createSearchParamsCache` requires calling `parse()` at the page level before calling `get()` in nested components. Forgetting `parse()` causes `get()` to return undefined or throw.
+
+**Incorrect (missing parse):**
+
+```tsx
+// app/search/page.tsx
+import { ResultsHeader } from './ResultsHeader'
+
+export default async function SearchPage({ searchParams }) {
+ // Missing: await searchParamsCache.parse(searchParams)
+
+ return (
+
+ {/* Will fail or return undefined */}
+
+
+ )
+}
+
+// components/ResultsHeader.tsx
+import { searchParamsCache } from '@/lib/searchParams'
+
+export function ResultsHeader() {
+ const query = searchParamsCache.get('q') // Error: cache not initialized
+ return Results for {query}
+}
+```
+
+**Correct (parse at page level):**
+
+```tsx
+// app/search/page.tsx
+import { searchParamsCache } from '@/lib/searchParams'
+import { ResultsHeader } from './ResultsHeader'
+import type { SearchParams } from 'nuqs/server'
+
+type PageProps = {
+ searchParams: Promise
+}
+
+export default async function SearchPage({ searchParams }: PageProps) {
+ // Parse FIRST, before rendering any children
+ await searchParamsCache.parse(searchParams)
+
+ return (
+
+ {/* Now get() works */}
+
+
+ )
+}
+
+// components/ResultsHeader.tsx
+import { searchParamsCache } from '@/lib/searchParams'
+
+export function ResultsHeader() {
+ const query = searchParamsCache.get('q') // Works correctly
+ return Results for {query}
+}
+```
+
+**Parse and destructure in one step:**
+
+```tsx
+export default async function SearchPage({ searchParams }: PageProps) {
+ const { q, page } = await searchParamsCache.parse(searchParams)
+ // Use q and page directly, or let children use get()
+
+ return
+}
+```
+
+Reference: [nuqs Server Cache](https://nuqs.dev/docs/server-side)
diff --git a/.agents/skills/nuqs/references/server-search-params-cache.md b/.agents/skills/nuqs/references/server-search-params-cache.md
new file mode 100644
index 0000000..a37b686
--- /dev/null
+++ b/.agents/skills/nuqs/references/server-search-params-cache.md
@@ -0,0 +1,78 @@
+---
+title: Use createSearchParamsCache for Server Components
+impact: HIGH
+impactDescription: eliminates prop drilling across N component levels
+tags: server, createSearchParamsCache, server-components, type-safety
+---
+
+## Use createSearchParamsCache for Server Components
+
+In Server Components, use `createSearchParamsCache` to access URL parameters with type safety. This avoids prop drilling and provides the same parsers as client-side hooks.
+
+**Incorrect (manual parsing):**
+
+```tsx
+// app/search/page.tsx
+type PageProps = {
+ searchParams: Promise<{ q?: string; page?: string }>
+}
+
+export default async function SearchPage({ searchParams }: PageProps) {
+ const params = await searchParams
+ const query = params.q ?? ''
+ const page = parseInt(params.page ?? '1', 10) // Manual parsing
+ // No type safety, parsing logic duplicated
+
+ return
+}
+```
+
+**Correct (search params cache):**
+
+```tsx
+// lib/searchParams.ts
+import {
+ createSearchParamsCache,
+ parseAsString,
+ parseAsInteger
+} from 'nuqs/server'
+
+export const searchParamsCache = createSearchParamsCache({
+ q: parseAsString.withDefault(''),
+ page: parseAsInteger.withDefault(1)
+})
+
+// app/search/page.tsx
+import { searchParamsCache } from '@/lib/searchParams'
+import type { SearchParams } from 'nuqs/server'
+
+type PageProps = {
+ searchParams: Promise
+}
+
+export default async function SearchPage({ searchParams }: PageProps) {
+ // Parse once at page level
+ const { q, page } = await searchParamsCache.parse(searchParams)
+
+ return
+}
+```
+
+**Access in nested Server Components:**
+
+```tsx
+// components/ResultsHeader.tsx
+import { searchParamsCache } from '@/lib/searchParams'
+
+export function ResultsHeader() {
+ // No props needed - access from cache
+ const query = searchParamsCache.get('q')
+ const page = searchParamsCache.get('page')
+
+ return Results for "{query}" (Page {page})
+}
+```
+
+**Important:** Call `parse()` once at the page level before using `get()` in nested components.
+
+Reference: [nuqs Server-Side](https://nuqs.dev/docs/server-side)
diff --git a/.agents/skills/nuqs/references/server-shallow-false.md b/.agents/skills/nuqs/references/server-shallow-false.md
new file mode 100644
index 0000000..6ca0ef6
--- /dev/null
+++ b/.agents/skills/nuqs/references/server-shallow-false.md
@@ -0,0 +1,74 @@
+---
+title: Use shallow:false to Trigger Server Re-renders
+impact: HIGH
+impactDescription: enables server-side data refetching on URL change
+tags: server, shallow, server-components, data-fetching, rsc
+---
+
+## Use shallow:false to Trigger Server Re-renders
+
+By default, nuqs updates are client-side only (`shallow: true`). Set `shallow: false` to trigger Server Component re-renders when URL changes, enabling server-side data fetching.
+
+**Incorrect (server data never refreshes):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
+ // shallow: true (default) - server doesn't see URL changes
+ // Server-fetched data stays stale
+
+ return setPage(p => p + 1)}>Next
+}
+```
+
+**Correct (server refetches on change):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1).withOptions({
+ shallow: false // Notify server of URL changes
+ }))
+ // Server Components re-render with new page value
+
+ return setPage(p => p + 1)}>Next
+}
+```
+
+**With loading state using useTransition:**
+
+```tsx
+'use client'
+import { useTransition } from 'react'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [isLoading, startTransition] = useTransition()
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1).withOptions({
+ shallow: false,
+ startTransition // Shows loading during server fetch
+ }))
+
+ return (
+
+ {isLoading && Loading... }
+ setPage(p => p + 1)} disabled={isLoading}>
+ Next
+
+
+ )
+}
+```
+
+**When to use shallow:false:**
+- Pagination with server-fetched data
+- Search that triggers server queries
+- Filters that affect server-rendered content
+- Any state that affects Server Component output
+
+Reference: [nuqs Shallow Option](https://nuqs.dev/docs/options)
diff --git a/.agents/skills/nuqs/references/server-share-parsers.md b/.agents/skills/nuqs/references/server-share-parsers.md
new file mode 100644
index 0000000..09e6795
--- /dev/null
+++ b/.agents/skills/nuqs/references/server-share-parsers.md
@@ -0,0 +1,74 @@
+---
+title: Share Parsers Between Client and Server
+impact: HIGH
+impactDescription: prevents client/server hydration mismatches
+tags: server, parsers, shared, consistency, client-server
+---
+
+## Share Parsers Between Client and Server
+
+Define parsers once and reuse them in both `createSearchParamsCache` (server) and `useQueryState` (client). This ensures consistent parsing behavior and prevents bugs from mismatched configurations.
+
+**Incorrect (separate definitions):**
+
+```tsx
+// app/search/page.tsx (Server)
+import { createSearchParamsCache, parseAsInteger } from 'nuqs/server'
+
+const cache = createSearchParamsCache({
+ page: parseAsInteger.withDefault(1)
+})
+
+// components/Pagination.tsx (Client)
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export function Pagination() {
+ // Different default - inconsistent!
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(0))
+}
+```
+
+**Correct (shared definition):**
+
+```tsx
+// lib/searchParams.ts
+import { parseAsInteger, parseAsString } from 'nuqs' // Works for both
+
+export const searchParamsParsers = {
+ q: parseAsString.withDefault(''),
+ page: parseAsInteger.withDefault(1),
+ limit: parseAsInteger.withDefault(10)
+}
+
+// lib/searchParams.server.ts
+import { createSearchParamsCache } from 'nuqs/server'
+import { searchParamsParsers } from './searchParams'
+
+export const searchParamsCache = createSearchParamsCache(searchParamsParsers)
+
+// app/search/page.tsx (Server)
+import { searchParamsCache } from '@/lib/searchParams.server'
+
+export default async function SearchPage({ searchParams }) {
+ const { q, page } = await searchParamsCache.parse(searchParams)
+ return
+}
+
+// components/Pagination.tsx (Client)
+'use client'
+import { useQueryState } from 'nuqs'
+import { searchParamsParsers } from '@/lib/searchParams'
+
+export function Pagination() {
+ const [page, setPage] = useQueryState('page', searchParamsParsers.page)
+ // Uses same parser with same default as server
+}
+```
+
+**Benefits:**
+- Single source of truth for defaults
+- TypeScript catches inconsistencies
+- Easier to update configuration
+
+Reference: [nuqs Documentation](https://nuqs.dev/docs)
diff --git a/.agents/skills/nuqs/references/server-use-transition.md b/.agents/skills/nuqs/references/server-use-transition.md
new file mode 100644
index 0000000..f41ba3e
--- /dev/null
+++ b/.agents/skills/nuqs/references/server-use-transition.md
@@ -0,0 +1,96 @@
+---
+title: Integrate useTransition for Loading States
+impact: HIGH
+impactDescription: 100% visibility into server fetch pending state
+tags: server, useTransition, loading, suspense, streaming
+---
+
+## Integrate useTransition for Loading States
+
+When using `shallow: false`, integrate React's `useTransition` to track when the server is fetching new data. This enables loading indicators during URL-triggered server updates.
+
+**Incorrect (no loading feedback):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function SearchBox() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault('').withOptions({
+ shallow: false
+ }))
+ // User types, waits with no feedback while server fetches
+
+ return (
+ setQuery(e.target.value)}
+ placeholder="Search..."
+ />
+ )
+}
+```
+
+**Correct (loading state):**
+
+```tsx
+'use client'
+import { useTransition } from 'react'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function SearchBox() {
+ const [isLoading, startTransition] = useTransition()
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault('').withOptions({
+ shallow: false,
+ startTransition
+ }))
+
+ return (
+
+ setQuery(e.target.value)}
+ placeholder="Search..."
+ />
+ {isLoading && }
+
+ )
+}
+```
+
+**With disabled interaction during load:**
+
+```tsx
+'use client'
+import { useTransition } from 'react'
+import { useQueryStates, parseAsString, parseAsInteger } from 'nuqs'
+
+export default function FilterPanel() {
+ const [isLoading, startTransition] = useTransition()
+ const [filters, setFilters] = useQueryStates(
+ {
+ category: parseAsString.withDefault(''),
+ page: parseAsInteger.withDefault(1)
+ },
+ {
+ shallow: false,
+ startTransition
+ }
+ )
+
+ return (
+
+ setFilters({ category: e.target.value, page: 1 })}
+ >
+ All
+ Electronics
+
+ {isLoading && Updating results...
}
+
+ )
+}
+```
+
+Reference: [nuqs useTransition Integration](https://nuqs.dev/docs/options)
diff --git a/.agents/skills/nuqs/references/setup-import-server.md b/.agents/skills/nuqs/references/setup-import-server.md
new file mode 100644
index 0000000..0e91af1
--- /dev/null
+++ b/.agents/skills/nuqs/references/setup-import-server.md
@@ -0,0 +1,72 @@
+---
+title: Import Server Utilities from nuqs/server
+impact: CRITICAL
+impactDescription: prevents RSC-to-client boundary contamination errors
+tags: setup, nuqs/server, imports, createSearchParamsCache, server-components
+---
+
+## Import Server Utilities from nuqs/server
+
+Server-side utilities like `createSearchParamsCache` must be imported from `nuqs/server`, not `nuqs`. The main `nuqs` export includes the `'use client'` directive which contaminates Server Components.
+
+**Incorrect (wrong import):**
+
+```tsx
+// lib/searchParams.ts
+import { createSearchParamsCache, parseAsString } from 'nuqs'
+// Error: This import adds 'use client' to your server code
+
+export const searchParamsCache = createSearchParamsCache({
+ q: parseAsString.withDefault('')
+})
+```
+
+**Correct (server import):**
+
+```tsx
+// lib/searchParams.ts
+import {
+ createSearchParamsCache,
+ parseAsString,
+ parseAsInteger
+} from 'nuqs/server'
+// No 'use client' directive - safe for Server Components
+
+export const searchParamsCache = createSearchParamsCache({
+ q: parseAsString.withDefault(''),
+ page: parseAsInteger.withDefault(1)
+})
+```
+
+**Usage in Server Component:**
+
+```tsx
+// app/search/page.tsx
+import { searchParamsCache } from '@/lib/searchParams'
+import type { SearchParams } from 'nuqs/server'
+
+type PageProps = {
+ searchParams: Promise
+}
+
+export default async function SearchPage({ searchParams }: PageProps) {
+ const { q, page } = await searchParamsCache.parse(searchParams)
+
+ return (
+
+
Results for: {q}
+
Page: {page}
+
+ )
+}
+```
+
+**What to import from where:**
+
+| Import | Source | Use In |
+|--------|--------|--------|
+| `useQueryState`, `useQueryStates` | `nuqs` | Client Components |
+| `createSearchParamsCache` | `nuqs/server` | Server Components |
+| Parsers (`parseAsString`, etc.) | `nuqs/server` for server, `nuqs` for client | Either |
+
+Reference: [nuqs Server-Side](https://nuqs.dev/docs/server-side)
diff --git a/.agents/skills/nuqs/references/setup-nextjs-version.md b/.agents/skills/nuqs/references/setup-nextjs-version.md
new file mode 100644
index 0000000..573f98e
--- /dev/null
+++ b/.agents/skills/nuqs/references/setup-nextjs-version.md
@@ -0,0 +1,64 @@
+---
+title: Verify Framework Compatibility Before Setup
+impact: CRITICAL
+impactDescription: selects the supported nuqs adapter and framework range
+tags: setup, nextjs, version, compatibility, adapters
+---
+
+## Verify Framework Compatibility Before Setup
+
+nuqs 2.x supports Next.js 14.2 or newer for both App and Pages Routers. Earlier Next.js releases require the legacy nuqs 1.x line; do not combine nuqs 2.x with an unsupported router version.
+
+| Framework/router | Supported range for nuqs 2.x |
+| --- | --- |
+| Next.js App or Pages Router | `next >= 14.2.0` |
+| React SPA | `react >= 18.2 \|\| ^19` |
+| React Router v6 | `react-router-dom ^6` |
+| React Router v7 | `react-router ^7` |
+| React Router v8 | `react-router ^8` |
+| TanStack Router (experimental) | `@tanstack/react-router ^1` |
+
+**Incorrect (nuqs 2 with an unsupported Next.js release):**
+
+```json
+{
+ "dependencies": {
+ "next": "13.5.0",
+ "nuqs": "^2.0.0"
+ }
+}
+```
+
+**Correct (supported Next.js range):**
+
+```json
+{
+ "dependencies": {
+ "next": "^16.0.0",
+ "nuqs": "^2.0.0"
+ }
+}
+```
+
+Inspect the installed versions rather than copying a version into `package.json`:
+
+```bash
+npm ls nuqs next react react-router react-router-dom
+```
+
+Choose the adapter that matches the actual router:
+
+```tsx
+// Next.js App Router
+import { NuqsAdapter } from 'nuqs/adapters/next/app'
+
+// Next.js Pages Router
+import { NuqsAdapter } from 'nuqs/adapters/next/pages'
+
+// Mixed Next.js routers (slightly larger unified adapter)
+import { NuqsAdapter } from 'nuqs/adapters/next'
+```
+
+When upgrading a working application, follow the nuqs migration guide and the framework's own migration guide; a blind `@latest` install can combine multiple unrelated major migrations.
+
+Reference: [nuqs installation and compatibility](https://nuqs.dev/docs/installation)
diff --git a/.agents/skills/nuqs/references/setup-nuqs-adapter.md b/.agents/skills/nuqs/references/setup-nuqs-adapter.md
new file mode 100644
index 0000000..86e1892
--- /dev/null
+++ b/.agents/skills/nuqs/references/setup-nuqs-adapter.md
@@ -0,0 +1,77 @@
+---
+title: Wrap App with NuqsAdapter
+impact: CRITICAL
+impactDescription: prevents 100% of hook failures from missing provider
+tags: setup, NuqsAdapter, provider, app-router, pages-router
+---
+
+## Wrap App with NuqsAdapter
+
+nuqs requires the `NuqsAdapter` provider to function. Without it, `useQueryState` hooks won't sync with the URL and may throw errors.
+
+**Incorrect (missing adapter):**
+
+```tsx
+// src/app/layout.tsx
+export default function RootLayout({
+ children
+}: {
+ children: React.ReactNode
+}) {
+ return (
+
+ {children}
+
+ )
+}
+// useQueryState calls will fail silently or throw
+```
+
+**Correct (App Router):**
+
+```tsx
+// src/app/layout.tsx
+import { NuqsAdapter } from 'nuqs/adapters/next/app'
+
+export default function RootLayout({
+ children
+}: {
+ children: React.ReactNode
+}) {
+ return (
+
+
+ {children}
+
+
+ )
+}
+```
+
+**Correct (Pages Router):**
+
+```tsx
+// src/pages/_app.tsx
+import type { AppProps } from 'next/app'
+import { NuqsAdapter } from 'nuqs/adapters/next/pages'
+
+export default function MyApp({ Component, pageProps }: AppProps) {
+ return (
+
+
+
+ )
+}
+```
+
+**Available adapters:**
+- `nuqs/adapters/next/app` - Next.js App Router
+- `nuqs/adapters/next/pages` - Next.js Pages Router
+- `nuqs/adapters/react` - Plain React (with react-router)
+- `nuqs/adapters/remix` - Remix
+- `nuqs/adapters/react-router/v6` - React Router v6
+- `nuqs/adapters/react-router/v7` - React Router v7
+- `nuqs/adapters/react-router/v8` - React Router v8 (re-exports v7; pin for future compatibility)
+- `nuqs/adapters/tanstack-router` - TanStack Router v1 (experimental)
+
+Reference: [nuqs Adapters](https://nuqs.dev/docs/adapters)
diff --git a/.agents/skills/nuqs/references/setup-shared-parsers.md b/.agents/skills/nuqs/references/setup-shared-parsers.md
new file mode 100644
index 0000000..95e3f6a
--- /dev/null
+++ b/.agents/skills/nuqs/references/setup-shared-parsers.md
@@ -0,0 +1,73 @@
+---
+title: Define Shared Parsers in Dedicated File
+impact: HIGH
+impactDescription: prevents parser mismatch bugs between components
+tags: setup, parsers, organization, reusability, consistency
+---
+
+## Define Shared Parsers in Dedicated File
+
+When multiple components use the same URL parameters, define parsers in a shared file. This prevents mismatches where one component uses `parseAsInteger` and another uses `parseAsString` for the same parameter.
+
+**Incorrect (duplicate parser definitions):**
+
+```tsx
+// components/Pagination.tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
+ return setPage(p => p + 1)}>Next
+}
+
+// components/PageInfo.tsx
+'use client'
+import { useQueryState } from 'nuqs'
+
+export function PageInfo() {
+ const [page] = useQueryState('page') // String parser - mismatch!
+ return Page: {page} // Shows "1" not 1
+}
+```
+
+**Correct (shared parsers):**
+
+```tsx
+// lib/searchParams.ts
+import { parseAsInteger, parseAsString, parseAsStringLiteral } from 'nuqs'
+
+export const searchParams = {
+ page: parseAsInteger.withDefault(1),
+ query: parseAsString.withDefault(''),
+ sort: parseAsStringLiteral(['asc', 'desc'] as const).withDefault('asc')
+}
+
+// components/Pagination.tsx
+'use client'
+import { useQueryState } from 'nuqs'
+import { searchParams } from '@/lib/searchParams'
+
+export function Pagination() {
+ const [page, setPage] = useQueryState('page', searchParams.page)
+ return setPage(p => p + 1)}>Next
+}
+
+// components/PageInfo.tsx
+'use client'
+import { useQueryState } from 'nuqs'
+import { searchParams } from '@/lib/searchParams'
+
+export function PageInfo() {
+ const [page] = useQueryState('page', searchParams.page)
+ return Page: {page} // Correctly typed as number
+}
+```
+
+**Benefits:**
+- Single source of truth for parser configuration
+- TypeScript catches mismatches at compile time
+- Easy to update defaults in one place
+- Shared between client and server (with proper imports)
+
+Reference: [nuqs Documentation](https://nuqs.dev/docs)
diff --git a/.agents/skills/nuqs/references/setup-use-client.md b/.agents/skills/nuqs/references/setup-use-client.md
new file mode 100644
index 0000000..92172ba
--- /dev/null
+++ b/.agents/skills/nuqs/references/setup-use-client.md
@@ -0,0 +1,69 @@
+---
+title: Add 'use client' Directive for Hooks
+impact: CRITICAL
+impactDescription: prevents build-breaking hook errors in RSC
+tags: setup, use-client, server-components, client-components
+---
+
+## Add 'use client' Directive for Hooks
+
+`useQueryState` and `useQueryStates` are React hooks that require client-side rendering. Using them in Server Components causes build errors.
+
+**Incorrect (missing directive):**
+
+```tsx
+// app/search/page.tsx
+import { useQueryState } from 'nuqs'
+
+export default function SearchPage() {
+ const [query, setQuery] = useQueryState('q')
+ // Error: Hooks can only be called inside Client Components
+
+ return setQuery(e.target.value)} />
+}
+```
+
+**Correct (client component):**
+
+```tsx
+// app/search/page.tsx
+'use client'
+
+import { useQueryState } from 'nuqs'
+
+export default function SearchPage() {
+ const [query, setQuery] = useQueryState('q')
+
+ return setQuery(e.target.value)} />
+}
+```
+
+**Alternative (extract to client component):**
+
+```tsx
+// app/search/page.tsx (Server Component)
+import SearchInput from './SearchInput'
+
+export default function SearchPage() {
+ return (
+
+
Search
+
+
+ )
+}
+
+// app/search/SearchInput.tsx (Client Component)
+'use client'
+
+import { useQueryState } from 'nuqs'
+
+export default function SearchInput() {
+ const [query, setQuery] = useQueryState('q')
+ return setQuery(e.target.value)} />
+}
+```
+
+**Note:** For reading search params in Server Components without hooks, use `createSearchParamsCache` from `nuqs/server`.
+
+Reference: [nuqs Server-Side](https://nuqs.dev/docs/server-side)
diff --git a/.agents/skills/nuqs/references/state-avoid-derived.md b/.agents/skills/nuqs/references/state-avoid-derived.md
new file mode 100644
index 0000000..a409cec
--- /dev/null
+++ b/.agents/skills/nuqs/references/state-avoid-derived.md
@@ -0,0 +1,84 @@
+---
+title: Avoid Derived State from URL Parameters
+impact: HIGH
+impactDescription: prevents sync bugs and unnecessary re-renders
+tags: state, derived-state, anti-pattern, single-source-of-truth
+---
+
+## Avoid Derived State from URL Parameters
+
+Don't copy URL state into local `useState`. This creates two sources of truth that can drift out of sync. Use the URL state directly or compute derived values.
+
+**Incorrect (duplicated state):**
+
+```tsx
+'use client'
+import { useState, useEffect } from 'react'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [urlPage] = useQueryState('page', parseAsInteger.withDefault(1))
+ const [page, setPage] = useState(urlPage) // Duplicated!
+
+ useEffect(() => {
+ setPage(urlPage) // Sync attempt - can cause loops
+ }, [urlPage])
+
+ return Page: {page}
+}
+```
+
+**Correct (single source of truth):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
+
+ return Page: {page}
+}
+```
+
+**For derived values, use useMemo:**
+
+```tsx
+'use client'
+import { useMemo } from 'react'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Pagination() {
+ const [page] = useQueryState('page', parseAsInteger.withDefault(1))
+
+ // Derived value, not duplicated state
+ const isFirstPage = useMemo(() => page === 1, [page])
+ const pageRange = useMemo(
+ () => ({ start: (page - 1) * 10, end: page * 10 }),
+ [page]
+ )
+
+ return (
+
+ Page: {page}
+ {isFirstPage && (First page) }
+
+ )
+}
+```
+
+**Exception: Debounced input**
+
+```tsx
+// OK to have local state for debounced input
+const [query, setQuery] = useQueryState('q')
+const [inputValue, setInputValue] = useState(query ?? '')
+
+// Debounce URL updates
+useEffect(() => {
+ const timeout = setTimeout(() => setQuery(inputValue || null), 300)
+ return () => clearTimeout(timeout)
+}, [inputValue, setQuery])
+```
+
+Reference: [React Derived State](https://react.dev/learn/you-might-not-need-an-effect#updating-state-based-on-props-or-state)
diff --git a/.agents/skills/nuqs/references/state-clear-with-null.md b/.agents/skills/nuqs/references/state-clear-with-null.md
new file mode 100644
index 0000000..20085b1
--- /dev/null
+++ b/.agents/skills/nuqs/references/state-clear-with-null.md
@@ -0,0 +1,81 @@
+---
+title: Clear URL Parameters with null
+impact: HIGH
+impactDescription: reduces URL clutter by removing unnecessary parameters
+tags: state, null, clear, url-cleanup, reset
+---
+
+## Clear URL Parameters with null
+
+To remove a parameter from the URL, set it to `null`. Setting to empty string (`''`) or `0` keeps the parameter in the URL with that value.
+
+**Incorrect (empty string in URL):**
+
+```tsx
+'use client'
+import { useQueryState } from 'nuqs'
+
+export default function SearchBox() {
+ const [query, setQuery] = useQueryState('q')
+
+ const clear = () => setQuery('')
+ // URL: ?q= (empty but parameter remains)
+
+ return (
+
+ setQuery(e.target.value)} />
+ Clear
+
+ )
+}
+```
+
+**Correct (null removes parameter):**
+
+```tsx
+'use client'
+import { useQueryState } from 'nuqs'
+
+export default function SearchBox() {
+ const [query, setQuery] = useQueryState('q')
+
+ const clear = () => setQuery(null)
+ // URL: / (parameter removed entirely)
+
+ return (
+
+ setQuery(e.target.value || null)}
+ />
+ Clear
+
+ )
+}
+```
+
+**Pattern: Convert empty to null on change:**
+
+```tsx
+ setQuery(e.target.value || null)}
+/>
+// Empty input → null → clean URL
+// "search term" → "search term" → ?q=search+term
+```
+
+**With typed parsers:**
+
+```tsx
+const [count, setCount] = useQueryState('count', parseAsInteger)
+
+// Clear the parameter
+setCount(null) // URL: /
+
+// With default, null resets to default behavior
+const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1))
+setPage(null) // URL: / (page defaults to 1, not shown)
+```
+
+Reference: [nuqs Documentation](https://nuqs.dev/docs)
diff --git a/.agents/skills/nuqs/references/state-controlled-inputs.md b/.agents/skills/nuqs/references/state-controlled-inputs.md
new file mode 100644
index 0000000..c48f833
--- /dev/null
+++ b/.agents/skills/nuqs/references/state-controlled-inputs.md
@@ -0,0 +1,83 @@
+---
+title: Handle Controlled Input Value Properly
+impact: HIGH
+impactDescription: prevents uncontrolled to controlled warnings
+tags: state, controlled-inputs, forms, null-handling, react
+---
+
+## Handle Controlled Input Value Properly
+
+React requires controlled inputs to always have a defined `value`. Since nuqs returns `null` when a parameter is absent, you must provide a fallback for input elements.
+
+**Incorrect (uncontrolled warning):**
+
+```tsx
+'use client'
+import { useQueryState } from 'nuqs'
+
+export default function SearchBox() {
+ const [query, setQuery] = useQueryState('q')
+ // query is string | null
+
+ return (
+ setQuery(e.target.value)}
+ />
+ )
+}
+// Warning: A component is changing an uncontrolled input to be controlled
+```
+
+**Correct (fallback value):**
+
+```tsx
+'use client'
+import { useQueryState } from 'nuqs'
+
+export default function SearchBox() {
+ const [query, setQuery] = useQueryState('q')
+
+ return (
+ setQuery(e.target.value || null)}
+ />
+ )
+}
+```
+
+**Alternative (withDefault):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function SearchBox() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault(''))
+ // query is string (never null)
+
+ return (
+ setQuery(e.target.value)}
+ />
+ )
+}
+```
+
+**For select elements:**
+
+```tsx
+const [sort, setSort] = useQueryState(
+ 'sort',
+ parseAsStringLiteral(['asc', 'desc'] as const).withDefault('asc')
+)
+
+ setSort(e.target.value as typeof sort)}>
+ Ascending
+ Descending
+
+```
+
+Reference: [React Controlled Components](https://react.dev/reference/react-dom/components/input#controlling-an-input-with-a-state-variable)
diff --git a/.agents/skills/nuqs/references/state-functional-updates.md b/.agents/skills/nuqs/references/state-functional-updates.md
new file mode 100644
index 0000000..68dcd59
--- /dev/null
+++ b/.agents/skills/nuqs/references/state-functional-updates.md
@@ -0,0 +1,68 @@
+---
+title: Use Functional Updates for State Derived from Previous Value
+impact: HIGH
+impactDescription: prevents stale closure bugs and race conditions
+tags: state, functional-updates, closures, setState, increment
+---
+
+## Use Functional Updates for State Derived from Previous Value
+
+When the new state depends on the previous state (incrementing, toggling, appending), use functional updates. Direct state references in closures can be stale.
+
+**Incorrect (stale closure):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Counter() {
+ const [count, setCount] = useQueryState('count', parseAsInteger.withDefault(0))
+
+ const incrementTwice = () => {
+ setCount(count + 1) // Uses stale `count`
+ setCount(count + 1) // Still uses same stale `count`
+ // Result: increments by 1, not 2
+ }
+
+ return +2
+}
+```
+
+**Correct (functional update):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsInteger } from 'nuqs'
+
+export default function Counter() {
+ const [count, setCount] = useQueryState('count', parseAsInteger.withDefault(0))
+
+ const incrementTwice = () => {
+ setCount(c => c + 1) // Gets latest value
+ setCount(c => c + 1) // Gets updated value
+ // Result: correctly increments by 2
+ }
+
+ return +2
+}
+```
+
+**More examples:**
+
+```tsx
+// Toggle boolean
+const [enabled, setEnabled] = useQueryState('enabled', parseAsBoolean.withDefault(false))
+setEnabled(e => !e)
+
+// Append to array
+const [tags, setTags] = useQueryState(
+ 'tags',
+ parseAsArrayOf(parseAsString).withDefault([])
+)
+setTags(t => [...t, 'new-tag'])
+
+// Remove from array
+setTags(t => t.filter(tag => tag !== 'remove-me'))
+```
+
+Reference: [nuqs State Updates](https://nuqs.dev/docs)
diff --git a/.agents/skills/nuqs/references/state-options-inheritance.md b/.agents/skills/nuqs/references/state-options-inheritance.md
new file mode 100644
index 0000000..5c81051
--- /dev/null
+++ b/.agents/skills/nuqs/references/state-options-inheritance.md
@@ -0,0 +1,78 @@
+---
+title: Use withOptions for Parser-Level Configuration
+impact: MEDIUM
+impactDescription: reduces boilerplate and ensures consistent behavior
+tags: state, withOptions, configuration, parsers, reusability
+---
+
+## Use withOptions for Parser-Level Configuration
+
+Instead of passing options to every `useQueryState` call, configure options on the parser itself with `withOptions`. This ensures consistent behavior and reduces repetition.
+
+**Incorrect (repeated options):**
+
+```tsx
+'use client'
+import { throttle, useQueryState, parseAsString } from 'nuqs'
+
+export default function SearchPage() {
+ const [query, setQuery] = useQueryState('q', {
+ ...parseAsString,
+ shallow: false,
+ limitUrlUpdates: throttle(500),
+ history: 'push'
+ })
+
+ const [filter, setFilter] = useQueryState('filter', {
+ ...parseAsString,
+ shallow: false,
+ limitUrlUpdates: throttle(500),
+ history: 'push'
+ })
+
+ // Repeated configuration for each parameter
+}
+```
+
+**Correct (parser-level options):**
+
+```tsx
+// lib/searchParams.ts
+import { parseAsString, parseAsInteger, throttle } from 'nuqs'
+
+const serverSyncOptions = {
+ shallow: false,
+ limitUrlUpdates: throttle(500),
+ history: 'push' as const
+}
+
+export const searchParams = {
+ query: parseAsString.withDefault('').withOptions(serverSyncOptions),
+ filter: parseAsString.withDefault('').withOptions(serverSyncOptions),
+ page: parseAsInteger.withDefault(1).withOptions(serverSyncOptions)
+}
+
+// components/SearchPage.tsx
+'use client'
+import { useQueryState } from 'nuqs'
+import { searchParams } from '@/lib/searchParams'
+
+export default function SearchPage() {
+ const [query, setQuery] = useQueryState('q', searchParams.query)
+ const [filter, setFilter] = useQueryState('filter', searchParams.filter)
+ const [page, setPage] = useQueryState('page', searchParams.page)
+
+ // All use the same options consistently
+}
+```
+
+**Options can be chained:**
+
+```tsx
+parseAsInteger
+ .withDefault(1)
+ .withOptions({ shallow: false })
+ .withOptions({ limitUrlUpdates: throttle(300) }) // Merges with previous options
+```
+
+Reference: [nuqs Options](https://nuqs.dev/docs/options)
diff --git a/.agents/skills/nuqs/references/state-setter-return.md b/.agents/skills/nuqs/references/state-setter-return.md
new file mode 100644
index 0000000..a67acc0
--- /dev/null
+++ b/.agents/skills/nuqs/references/state-setter-return.md
@@ -0,0 +1,78 @@
+---
+title: Use Setter Return Value for URL Access
+impact: MEDIUM
+impactDescription: enables accurate URL tracking for analytics/sharing
+tags: state, setter, return-value, url, analytics
+---
+
+## Use Setter Return Value for URL Access
+
+The state setter returns a Promise that resolves to the new URL search string. Use this for analytics, logging, or when you need the resulting URL immediately.
+
+**Incorrect (manually constructing URL):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function ShareButton() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault(''))
+
+ const share = () => {
+ setQuery('shared-term')
+ // Manual URL construction - may not match nuqs output
+ const url = `${window.location.pathname}?q=shared-term`
+ navigator.clipboard.writeText(url)
+ }
+
+ return Share
+}
+```
+
+**Correct (use return value):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsString } from 'nuqs'
+
+export default function ShareButton() {
+ const [query, setQuery] = useQueryState('q', parseAsString.withDefault(''))
+
+ const share = async () => {
+ const searchString = await setQuery('shared-term')
+ // searchString is "q=shared-term" or similar
+ const url = `${window.location.origin}${window.location.pathname}?${searchString}`
+ await navigator.clipboard.writeText(url)
+ }
+
+ return Share
+}
+```
+
+**For analytics:**
+
+```tsx
+const trackSearch = async (term: string) => {
+ const searchString = await setQuery(term)
+ analytics.track('search', {
+ term,
+ url: `?${searchString}`
+ })
+}
+```
+
+**With useQueryStates:**
+
+```tsx
+const [coords, setCoords] = useQueryStates({
+ lat: parseAsFloat,
+ lng: parseAsFloat
+})
+
+const shareLocation = async () => {
+ const searchString = await setCoords({ lat: 48.8566, lng: 2.3522 })
+ // searchString: "lat=48.8566&lng=2.3522"
+}
+```
+
+Reference: [nuqs Documentation](https://nuqs.dev/docs)
diff --git a/.agents/skills/nuqs/references/state-use-query-states.md b/.agents/skills/nuqs/references/state-use-query-states.md
new file mode 100644
index 0000000..d08ee37
--- /dev/null
+++ b/.agents/skills/nuqs/references/state-use-query-states.md
@@ -0,0 +1,75 @@
+---
+title: Use useQueryStates for Related Parameters
+impact: HIGH
+impactDescription: atomic updates prevent intermediate invalid states
+tags: state, useQueryStates, batching, atomic, related-params
+---
+
+## Use useQueryStates for Related Parameters
+
+When multiple URL parameters are logically related (like coordinates, date ranges, or filters), use `useQueryStates` for atomic updates. Multiple `useQueryState` calls update the URL independently, causing intermediate states.
+
+**Incorrect (separate hooks, non-atomic):**
+
+```tsx
+'use client'
+import { useQueryState, parseAsFloat } from 'nuqs'
+
+export default function MapView() {
+ const [lat, setLat] = useQueryState('lat', parseAsFloat.withDefault(0))
+ const [lng, setLng] = useQueryState('lng', parseAsFloat.withDefault(0))
+ const [zoom, setZoom] = useQueryState('zoom', parseAsFloat.withDefault(10))
+
+ const goToParis = () => {
+ setLat(48.8566) // URL update 1
+ setLng(2.3522) // URL update 2
+ setZoom(12) // URL update 3
+ // Three separate URL updates, three history entries if using push
+ }
+
+ return Go to Paris
+}
+```
+
+**Correct (single hook, atomic):**
+
+```tsx
+'use client'
+import { useQueryStates, parseAsFloat, parseAsInteger } from 'nuqs'
+
+export default function MapView() {
+ const [coords, setCoords] = useQueryStates({
+ lat: parseAsFloat.withDefault(0),
+ lng: parseAsFloat.withDefault(0),
+ zoom: parseAsInteger.withDefault(10)
+ })
+
+ const goToParis = () => {
+ setCoords({
+ lat: 48.8566,
+ lng: 2.3522,
+ zoom: 12
+ })
+ // Single atomic URL update
+ }
+
+ return (
+
+
Location: {coords.lat}, {coords.lng} (zoom: {coords.zoom})
+
Go to Paris
+
+ )
+}
+```
+
+**Partial updates also work:**
+
+```tsx
+// Only update zoom, keep lat/lng
+setCoords({ zoom: 15 })
+
+// Update lat/lng, keep zoom
+setCoords({ lat: 51.5074, lng: -0.1278 })
+```
+
+Reference: [nuqs useQueryStates](https://nuqs.dev/docs/batching)
diff --git a/.agents/skills/playwright/SKILL.md b/.agents/skills/playwright/SKILL.md
new file mode 100644
index 0000000..df4fd43
--- /dev/null
+++ b/.agents/skills/playwright/SKILL.md
@@ -0,0 +1,114 @@
+---
+name: playwright
+description: Playwright end-to-end tests and flaky-test fixes.
+---
+
+# Playwright + Next.js Testing Best Practices
+
+Comprehensive testing optimization guide for Playwright with Next.js applications. Contains 45 rules across 8 categories, prioritized by impact to guide reliable, fast, and maintainable E2E tests.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing new Playwright tests for Next.js apps
+- Debugging flaky or failing tests
+- Optimizing test execution speed
+- Setting up authentication state reuse
+- Configuring CI/CD pipelines for testing
+- Testing Server Components and App Router features
+- Reviewing test code for reliability issues
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Test Architecture | CRITICAL | `arch-` |
+| 2 | Selectors & Locators | CRITICAL | `loc-` |
+| 3 | Waiting & Assertions | HIGH | `wait-` |
+| 4 | Authentication & State | HIGH | `auth-` |
+| 5 | Mocking & Network | MEDIUM-HIGH | `mock-` |
+| 6 | Next.js Integration | MEDIUM | `next-` |
+| 7 | Performance & Speed | MEDIUM | `perf-` |
+| 8 | Debugging & CI | LOW-MEDIUM | `debug-` |
+
+## Quick Reference
+
+### 1. Test Architecture (CRITICAL)
+
+- [`arch-test-isolation`](references/arch-test-isolation.md) - Use fresh browser context for each test
+- [`arch-parallel-execution`](references/arch-parallel-execution.md) - Enable parallel test execution
+- [`arch-page-object-model`](references/arch-page-object-model.md) - Use Page Object Model for complex pages
+- [`arch-fixtures`](references/arch-fixtures.md) - Use fixtures for shared setup
+- [`arch-test-production`](references/arch-test-production.md) - Test against production builds
+- [`arch-cleanup-state`](references/arch-cleanup-state.md) - Clean up test state after each test
+
+### 2. Selectors & Locators (CRITICAL)
+
+- [`loc-role-selectors`](references/loc-role-selectors.md) - Use role-based selectors over CSS
+- [`loc-data-testid`](references/loc-data-testid.md) - Use data-testid for dynamic elements
+- [`loc-label-selectors`](references/loc-label-selectors.md) - Use getByLabel for form inputs
+- [`loc-text-selectors`](references/loc-text-selectors.md) - Use getByText for static content
+- [`loc-avoid-xpath`](references/loc-avoid-xpath.md) - Avoid XPath selectors
+- [`loc-chained-locators`](references/loc-chained-locators.md) - Chain locators for specificity
+- [`loc-placeholder-selector`](references/loc-placeholder-selector.md) - Use getByPlaceholder sparingly
+- [`loc-frame-locator`](references/loc-frame-locator.md) - Locate elements inside iframes with frameLocator
+
+### 3. Waiting & Assertions (HIGH)
+
+- [`wait-web-first-assertions`](references/wait-web-first-assertions.md) - Use web-first assertions
+- [`assert-aria-snapshots`](references/assert-aria-snapshots.md) - Assert accessibility structure with aria snapshots
+- [`wait-avoid-hard-waits`](references/wait-avoid-hard-waits.md) - Avoid hard waits
+- [`wait-network-idle`](references/wait-network-idle.md) - Wait for observable readiness, not network idle
+- [`wait-action-retries`](references/wait-action-retries.md) - Let actions auto-wait before interacting
+- [`wait-soft-assertions`](references/wait-soft-assertions.md) - Use soft assertions for non-critical checks
+- [`wait-custom-timeout`](references/wait-custom-timeout.md) - Configure timeouts appropriately
+
+### 4. Authentication & State (HIGH)
+
+- [`auth-storage-state`](references/auth-storage-state.md) - Reuse authentication with storage state
+- [`auth-multiple-roles`](references/auth-multiple-roles.md) - Use separate storage states for different roles
+- [`auth-session-storage`](references/auth-session-storage.md) - Handle session storage for auth
+- [`auth-api-login`](references/auth-api-login.md) - Use API login for faster auth setup
+- [`auth-parallel-workers`](references/auth-parallel-workers.md) - Use worker-scoped auth for parallel tests
+
+### 5. Mocking & Network (MEDIUM-HIGH)
+
+- [`mock-api-responses`](references/mock-api-responses.md) - Mock API responses for deterministic tests
+- [`mock-intercept-modify`](references/mock-intercept-modify.md) - Intercept and modify real responses
+- [`mock-har-files`](references/mock-har-files.md) - Use HAR files for complex mock scenarios
+- [`mock-abort-requests`](references/mock-abort-requests.md) - Abort unnecessary requests
+- [`mock-network-conditions`](references/mock-network-conditions.md) - Simulate network conditions
+
+### 6. Next.js Integration (MEDIUM)
+
+- [`next-wait-hydration`](references/next-wait-hydration.md) - Wait for hydration before interacting
+- [`next-server-components`](references/next-server-components.md) - Test server components correctly
+- [`next-app-router-navigation`](references/next-app-router-navigation.md) - Test App Router navigation patterns
+- [`next-server-actions`](references/next-server-actions.md) - Test server actions end-to-end
+- [`next-baseurl-config`](references/next-baseurl-config.md) - Configure baseURL for clean navigation
+
+### 7. Performance & Speed (MEDIUM)
+
+- [`perf-sharding`](references/perf-sharding.md) - Use sharding for large test suites
+- [`perf-headless-ci`](references/perf-headless-ci.md) - Use headless mode in CI
+- [`perf-browser-selection`](references/perf-browser-selection.md) - Select browsers strategically
+- [`perf-reuse-server`](references/perf-reuse-server.md) - Reuse a matching local server when safe
+- [`perf-retries`](references/perf-retries.md) - Use retries to detect and diagnose flakiness
+
+### 8. Debugging & CI (LOW-MEDIUM)
+
+- [`debug-trace-viewer`](references/debug-trace-viewer.md) - Use trace viewer for failed tests
+- [`debug-screenshots-videos`](references/debug-screenshots-videos.md) - Capture screenshots and videos on failure
+- [`debug-inspector`](references/debug-inspector.md) - Use Playwright Inspector for interactive debugging
+- [`debug-ci-reporters`](references/debug-ci-reporters.md) - Configure reporters for CI integration
+
+## How to Use
+
+Run in the project root first:
+
+```bash
+npx -y @pymodel/react-frontend-skills detect # installed vs. targeted versions
+npx -y @pymodel/react-frontend-skills scan --skill playwright # deprecated APIs → rule IDs
+```
+
+Read `references/.md` for each rule above that matches the task and for each `scan` hit: why it matters, then incorrect vs. correct code.
diff --git a/.agents/skills/playwright/references/arch-cleanup-state.md b/.agents/skills/playwright/references/arch-cleanup-state.md
new file mode 100644
index 0000000..cb88e38
--- /dev/null
+++ b/.agents/skills/playwright/references/arch-cleanup-state.md
@@ -0,0 +1,83 @@
+---
+title: Clean Up Test State After Each Test
+impact: CRITICAL
+impactDescription: prevents cascading failures from leftover data
+tags: arch, cleanup, teardown, state, afterEach
+---
+
+## Clean Up Test State After Each Test
+
+Leftover state from tests can cause subsequent tests to fail. Clean up any data created during tests, especially when using shared databases or external services.
+
+**Incorrect (no cleanup, state accumulates):**
+
+```typescript
+// tests/posts.spec.ts
+test('create new post', async ({ page }) => {
+ await page.goto('/posts/new');
+ await page.getByLabel('Title').fill('Test Post');
+ await page.getByLabel('Content').fill('Test content');
+ await page.getByRole('button', { name: 'Publish' }).click();
+ await expect(page.getByText('Post published')).toBeVisible();
+ // Post remains in database, affects other tests
+});
+
+test('list shows no posts for new user', async ({ page }) => {
+ await page.goto('/posts');
+ // Fails because previous test created a post
+ await expect(page.getByText('No posts yet')).toBeVisible();
+});
+```
+
+**Correct (cleanup after each test):**
+
+```typescript
+// tests/posts.spec.ts
+import { test, expect } from '@playwright/test';
+
+let createdPostIds: string[] = [];
+
+test.afterEach(async ({ request }) => {
+ // Clean up any posts created during the test
+ for (const postId of createdPostIds) {
+ await request.delete(`/api/posts/${postId}`);
+ }
+ createdPostIds = [];
+});
+
+test('create new post', async ({ page, request }) => {
+ await page.goto('/posts/new');
+ await page.getByLabel('Title').fill('Test Post');
+ await page.getByLabel('Content').fill('Test content');
+ await page.getByRole('button', { name: 'Publish' }).click();
+
+ // Track created post for cleanup
+ const postId = await page.getByTestId('post-id').textContent();
+ createdPostIds.push(postId!);
+
+ await expect(page.getByText('Post published')).toBeVisible();
+});
+
+test('list shows no posts for new user', async ({ page }) => {
+ await page.goto('/posts');
+ // Clean state - no posts from previous test
+ await expect(page.getByText('No posts yet')).toBeVisible();
+});
+```
+
+**Alternative (use test database reset):**
+
+```typescript
+// global-setup.ts
+export default async function globalSetup() {
+ // Reset test database before test run
+ await resetTestDatabase();
+}
+
+// playwright.config.ts
+export default defineConfig({
+ globalSetup: require.resolve('./global-setup'),
+});
+```
+
+Reference: [Playwright Test Hooks](https://playwright.dev/docs/test-fixtures#automatic-fixtures)
diff --git a/.agents/skills/playwright/references/arch-fixtures.md b/.agents/skills/playwright/references/arch-fixtures.md
new file mode 100644
index 0000000..e627340
--- /dev/null
+++ b/.agents/skills/playwright/references/arch-fixtures.md
@@ -0,0 +1,89 @@
+---
+title: Use Fixtures for Shared Setup
+impact: CRITICAL
+impactDescription: eliminates setup duplication across tests
+tags: arch, fixtures, setup, reusable, dependency-injection
+---
+
+## Use Fixtures for Shared Setup
+
+Repeating setup code in every test is error-prone and slow. Fixtures provide reusable, composable setup that Playwright manages automatically.
+
+**Incorrect (duplicated setup in each test):**
+
+```typescript
+// tests/admin.spec.ts
+test('admin can view users', async ({ page }) => {
+ // Setup duplicated in every admin test
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('admin@example.com');
+ await page.getByLabel('Password').fill('adminpass');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/admin/dashboard');
+
+ await page.goto('/admin/users');
+ await expect(page.getByRole('table')).toBeVisible();
+});
+
+test('admin can create user', async ({ page }) => {
+ // Same setup repeated
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('admin@example.com');
+ await page.getByLabel('Password').fill('adminpass');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/admin/dashboard');
+
+ await page.goto('/admin/users/new');
+ // ...
+});
+```
+
+**Correct (custom fixture):**
+
+```typescript
+// fixtures/admin.ts
+import { test as base, expect } from '@playwright/test';
+
+type AdminFixtures = {
+ adminPage: Page;
+};
+
+export const test = base.extend({
+ adminPage: async ({ page }, use) => {
+ // Setup: login as admin
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('admin@example.com');
+ await page.getByLabel('Password').fill('adminpass');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/admin/dashboard');
+
+ // Provide the authenticated page to the test
+ await use(page);
+
+ // Teardown: logout (optional)
+ await page.goto('/logout');
+ },
+});
+
+export { expect };
+
+// tests/admin.spec.ts
+import { test, expect } from '../fixtures/admin';
+
+test('admin can view users', async ({ adminPage }) => {
+ await adminPage.goto('/admin/users');
+ await expect(adminPage.getByRole('table')).toBeVisible();
+});
+
+test('admin can create user', async ({ adminPage }) => {
+ await adminPage.goto('/admin/users/new');
+ await expect(adminPage.getByRole('form')).toBeVisible();
+});
+```
+
+**Benefits:**
+- DRY principle enforced
+- Automatic setup and teardown
+- Composable fixtures for complex scenarios
+
+Reference: [Playwright Fixtures](https://playwright.dev/docs/test-fixtures)
diff --git a/.agents/skills/playwright/references/arch-page-object-model.md b/.agents/skills/playwright/references/arch-page-object-model.md
new file mode 100644
index 0000000..f8d725d
--- /dev/null
+++ b/.agents/skills/playwright/references/arch-page-object-model.md
@@ -0,0 +1,80 @@
+---
+title: Use Page Object Model for Complex Pages
+impact: CRITICAL
+impactDescription: reduces selector maintenance by 70%
+tags: arch, pom, page-object, abstraction, maintenance
+---
+
+## Use Page Object Model for Complex Pages
+
+Duplicating selectors across tests creates a maintenance burden. Page objects centralize selectors and actions, so UI changes require updates in one place.
+
+**Incorrect (selectors scattered across tests):**
+
+```typescript
+// tests/login.spec.ts
+test('successful login', async ({ page }) => {
+ await page.goto('/login');
+ await page.locator('input[name="email"]').fill('user@example.com');
+ await page.locator('input[name="password"]').fill('password123');
+ await page.locator('button[type="submit"]').click();
+ await expect(page.locator('.dashboard-header')).toBeVisible();
+});
+
+// tests/logout.spec.ts
+test('logout from dashboard', async ({ page }) => {
+ // Same selectors duplicated
+ await page.locator('input[name="email"]').fill('user@example.com');
+ await page.locator('input[name="password"]').fill('password123');
+ await page.locator('button[type="submit"]').click();
+ // If selector changes, both files need updates
+});
+```
+
+**Correct (Page Object Model):**
+
+```typescript
+// pages/LoginPage.ts
+import { Page, Locator, expect } from '@playwright/test';
+
+export class LoginPage {
+ readonly page: Page;
+ readonly emailInput: Locator;
+ readonly passwordInput: Locator;
+ readonly submitButton: Locator;
+
+ constructor(page: Page) {
+ this.page = page;
+ this.emailInput = page.getByLabel('Email');
+ this.passwordInput = page.getByLabel('Password');
+ this.submitButton = page.getByRole('button', { name: 'Sign in' });
+ }
+
+ async goto() {
+ await this.page.goto('/login');
+ }
+
+ async login(email: string, password: string) {
+ await this.emailInput.fill(email);
+ await this.passwordInput.fill(password);
+ await this.submitButton.click();
+ }
+}
+
+// tests/login.spec.ts
+import { LoginPage } from '../pages/LoginPage';
+
+test('successful login', async ({ page }) => {
+ const loginPage = new LoginPage(page);
+ await loginPage.goto();
+ await loginPage.login('user@example.com', 'password123');
+ await expect(page.getByTestId('dashboard-header')).toBeVisible();
+});
+```
+
+**Benefits:**
+- Single source of truth for selectors
+- Readable, domain-specific test code
+- Easy to update when UI changes
+
+Reference: [Playwright Page Object Models](https://playwright.dev/docs/pom)
diff --git a/.agents/skills/playwright/references/arch-parallel-execution.md b/.agents/skills/playwright/references/arch-parallel-execution.md
new file mode 100644
index 0000000..84119c8
--- /dev/null
+++ b/.agents/skills/playwright/references/arch-parallel-execution.md
@@ -0,0 +1,75 @@
+---
+title: Enable Parallel Test Execution
+impact: CRITICAL
+impactDescription: 2-10× faster test suites
+tags: arch, parallel, workers, performance, configuration
+---
+
+## Enable Parallel Test Execution
+
+Running tests sequentially wastes CI time. Playwright supports parallel execution at both file and test level—configure workers based on your CI resources.
+
+**Incorrect (sequential execution):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ workers: 1, // Forces sequential execution
+ fullyParallel: false,
+});
+
+// Test suite takes 10 minutes
+```
+
+**Correct (parallel execution):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ // CI: 4 workers. Locally, undefined = Playwright's default (half the CPU cores)
+ workers: process.env.CI ? 4 : undefined,
+ fullyParallel: true,
+});
+
+// tests/dashboard.spec.ts
+import { test, expect } from '@playwright/test';
+
+// fullyParallel: true already runs these tests in parallel; no describe.configure needed
+
+test('loads user stats', async ({ page }) => {
+ await page.goto('/dashboard/stats');
+ await expect(page.getByTestId('stats-panel')).toBeVisible();
+});
+
+test('loads notifications', async ({ page }) => {
+ await page.goto('/dashboard/notifications');
+ await expect(page.getByTestId('notification-list')).toBeVisible();
+});
+
+test('loads settings', async ({ page }) => {
+ await page.goto('/dashboard/settings');
+ await expect(page.getByTestId('settings-form')).toBeVisible();
+});
+```
+
+**Tests that share one resource: use a lock (Playwright 1.63+):**
+
+Don't drop to `workers: 1` or serial mode because a few tests share one account, database row or external sandbox. Give those tests the same `lock` name: Playwright runs them one at a time, across files, workers and projects, while everything else stays parallel.
+
+```typescript
+test('updates billing address', { lock: 'billing-account' }, async ({ page }) => {
+ // ...
+});
+
+test.describe('plan changes', { lock: ['billing-account', 'stripe-sandbox'] }, () => {
+ // every test here holds both locks
+});
+```
+
+In a file that is not fully parallel (the default or serial mode), a lock on any test is held for the whole file.
+
+**When NOT to use parallel execution:**
+- Tests with intentional sequential dependencies (prefer making them independent)
+- Resources that can't be isolated per test even with locks
+
+Reference: [Playwright Parallelism](https://playwright.dev/docs/test-parallel) · [Test locks](https://playwright.dev/docs/test-parallel#test-locks)
diff --git a/.agents/skills/playwright/references/arch-test-isolation.md b/.agents/skills/playwright/references/arch-test-isolation.md
new file mode 100644
index 0000000..51c2aea
--- /dev/null
+++ b/.agents/skills/playwright/references/arch-test-isolation.md
@@ -0,0 +1,61 @@
+---
+title: Use Fresh Browser Context for Each Test
+impact: CRITICAL
+impactDescription: eliminates cross-test state pollution
+tags: arch, isolation, context, browser, fixtures
+---
+
+## Use Fresh Browser Context for Each Test
+
+Tests that share browser state can pass or fail unpredictably based on execution order. Playwright creates a fresh context per test by default—never disable this behavior.
+
+**Incorrect (shared state between tests):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ use: {
+ // Reusing context causes state leakage
+ launchOptions: {
+ args: ['--disable-web-security'],
+ },
+ },
+});
+
+// tests/checkout.spec.ts
+test('add to cart', async ({ page }) => {
+ await page.goto('/product/1');
+ await page.getByRole('button', { name: 'Add to Cart' }).click();
+ // Cart state persists to next test!
+});
+
+test('checkout empty cart', async ({ page }) => {
+ await page.goto('/checkout');
+ // Fails because cart has items from previous test
+ await expect(page.getByText('Your cart is empty')).toBeVisible();
+});
+```
+
+**Correct (isolated context per test):**
+
+```typescript
+// tests/checkout.spec.ts
+test('add to cart', async ({ page }) => {
+ await page.goto('/product/1');
+ await page.getByRole('button', { name: 'Add to Cart' }).click();
+ await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+
+test('checkout empty cart', async ({ page }) => {
+ // Fresh context - no cart items from previous test
+ await page.goto('/checkout');
+ await expect(page.getByText('Your cart is empty')).toBeVisible();
+});
+```
+
+**Benefits:**
+- Tests can run in any order
+- Failures are isolated and easier to debug
+- Parallel execution becomes safe
+
+Reference: [Playwright Test Isolation](https://playwright.dev/docs/browser-contexts)
diff --git a/.agents/skills/playwright/references/arch-test-production.md b/.agents/skills/playwright/references/arch-test-production.md
new file mode 100644
index 0000000..03ce89d
--- /dev/null
+++ b/.agents/skills/playwright/references/arch-test-production.md
@@ -0,0 +1,74 @@
+---
+title: Test Against Production Builds
+impact: CRITICAL
+impactDescription: catches build-only bugs, matches real behavior
+tags: arch, production, build, next-start, configuration
+---
+
+## Test Against Production Builds
+
+A development server cannot validate production-only bundling, environment, and runtime behavior. Run CI/release E2E suites against a production build. A separate development-server smoke project may be useful for fast local feedback, but it does not replace the production-mode gate.
+
+**Incorrect (testing dev server):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ webServer: {
+ command: 'npm run dev', // Dev server has different behavior
+ url: 'http://localhost:3000',
+ reuseExistingServer: !process.env.CI,
+ },
+});
+
+// Tests pass in dev but fail in production due to:
+// - Hot reload interference
+// - Unminified code paths
+// - Development-only error boundaries
+```
+
+**Correct (testing production build):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ webServer: {
+ command: 'npm run build && npm run start',
+ url: 'http://localhost:3000',
+ reuseExistingServer: !process.env.CI,
+ timeout: 120000, // Build can take time
+ },
+});
+
+// package.json
+{
+ "scripts": {
+ "build": "next build",
+ "start": "next start",
+ "test:e2e": "playwright test",
+ "test:e2e:ci": "npm run build && playwright test"
+ }
+}
+```
+
+**Alternative (pre-built for faster local iteration):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ webServer: {
+ command: process.env.CI
+ ? 'npm run build && npm run start'
+ : 'npm run start', // Assumes build exists locally
+ url: 'http://localhost:3000',
+ reuseExistingServer: !process.env.CI,
+ },
+});
+```
+
+**Benefits:**
+- Tests match production behavior exactly
+- Catches minification and tree-shaking bugs
+- Validates environment variable handling
+
+Reference: [Next.js Testing with Playwright](https://nextjs.org/docs/pages/guides/testing/playwright)
diff --git a/.agents/skills/playwright/references/assert-aria-snapshots.md b/.agents/skills/playwright/references/assert-aria-snapshots.md
new file mode 100644
index 0000000..d7d1633
--- /dev/null
+++ b/.agents/skills/playwright/references/assert-aria-snapshots.md
@@ -0,0 +1,58 @@
+---
+title: Assert Accessibility Structure with Aria Snapshots
+impact: MEDIUM
+impactDescription: resilient UI structure assertions that survive styling changes
+tags: playwright, aria, snapshot, accessibility, assertions
+---
+
+## Assert Accessibility Structure with Aria Snapshots
+
+ARIA snapshots capture a page or element's accessibility tree as YAML — roles, names, and hierarchy without classes or styles. Asserting against them verifies what users and assistive tech actually see, and unlike DOM snapshots they survive CSS refactors.
+
+**Incorrect (asserting on implementation details):**
+
+```typescript
+test('dashboard renders', async ({ page }) => {
+ await page.goto('/dashboard')
+ // Breaks on any markup/styling change; says nothing
+ // about the page's semantic structure
+ await expect(page.locator('div.container > section:nth-child(2)')).toBeVisible()
+})
+```
+
+**Correct (inline aria snapshot):**
+
+```typescript
+test('dashboard renders', async ({ page }) => {
+ await page.goto('https://demo.playwright.dev/todomvc/')
+
+ await expect(page).toMatchAriaSnapshot(`
+ - heading "todos"
+ - textbox "What needs to be done?"
+ `)
+})
+```
+
+**Store baselines in separate files:**
+
+```typescript
+// Saves/loads main.aria.yml next to the test file
+await expect(page.getByRole('main')).toMatchAriaSnapshot({
+ name: 'main.aria.yml',
+})
+```
+
+**Generate a baseline first, then tighten it:**
+
+```typescript
+// Empty template records the current structure; run with
+// npx playwright test --update-snapshots to write it
+await expect(page.getByRole('main')).toMatchAriaSnapshot('')
+```
+
+**Notes:**
+
+- `locator.ariaSnapshot()` captures the YAML string directly; options include `depth` (limit tree size), `boxes` (append bounding boxes), and `mode: "ai"` for AI-optimized output.
+- Snapshot files use the `.aria.yml` extension and are stored in a directory named after the test file by default.
+- Update stale baselines with `npx playwright test --update-snapshots` after intentional structure changes.
+- Combine with [wait-web-first-assertions](wait-web-first-assertions.md) — `toMatchAriaSnapshot` is a web-first assertion that auto-waits.
diff --git a/.agents/skills/playwright/references/auth-api-login.md b/.agents/skills/playwright/references/auth-api-login.md
new file mode 100644
index 0000000..3529a07
--- /dev/null
+++ b/.agents/skills/playwright/references/auth-api-login.md
@@ -0,0 +1,99 @@
+---
+title: Use API Login for Faster Auth Setup
+impact: HIGH
+impactDescription: faster than UI login
+tags: auth, api, request, login, performance
+---
+
+## Use API Login for Faster Auth Setup
+
+UI-based login requires rendering pages and interacting with forms. API-based login directly calls the auth endpoint, saving significant time.
+
+**Incorrect (slow UI login):**
+
+```typescript
+// auth.setup.ts
+setup('authenticate', async ({ page }) => {
+ // UI login: ~2-5 seconds
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('user@example.com');
+ await page.getByLabel('Password').fill('password');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/dashboard');
+
+ await page.context().storageState({ path: 'playwright/.auth/user.json' });
+});
+```
+
+**Correct (fast API login):**
+
+```typescript
+// auth.setup.ts
+import { test as setup } from '@playwright/test';
+
+setup('authenticate', async ({ request }) => {
+ // API login avoids rendering and interacting with the login UI.
+ const response = await request.post('/api/auth/login', {
+ data: {
+ email: 'user@example.com',
+ password: 'password',
+ },
+ });
+
+ // Verify login succeeded
+ expect(response.ok()).toBeTruthy();
+
+ // Save auth state from response cookies
+ await request.storageState({ path: 'playwright/.auth/user.json' });
+});
+
+// playwright.config.ts
+export default defineConfig({
+ projects: [
+ { name: 'setup', testMatch: /.*\.setup\.ts/ },
+ {
+ name: 'tests',
+ use: { storageState: 'playwright/.auth/user.json' },
+ dependencies: ['setup'],
+ },
+ ],
+});
+```
+
+**Combined approach (API + set storage):**
+
+```typescript
+// For apps where API sets cookies directly
+setup('authenticate via API', async ({ request, browser }) => {
+ // Call login API
+ await request.post('/api/auth/login', {
+ data: { email: 'user@example.com', password: 'password' },
+ });
+
+ // If API returns token to be stored client-side
+ const context = await browser.newContext();
+ const page = await context.newPage();
+
+ // Navigate to set any client-side auth state
+ await page.goto('/');
+ await page.evaluate((token) => {
+ localStorage.setItem('authToken', token);
+ }, 'token-from-api');
+
+ await context.storageState({ path: 'playwright/.auth/user.json' });
+ await context.close();
+});
+```
+
+**Benefits:**
+- Usually faster and less coupled to login-page presentation
+- No UI rendering overhead
+- More reliable (no form interaction)
+- Tests auth API endpoint as side effect
+
+**When to still use UI login:**
+- Testing the login flow itself
+- Auth flow has complex multi-step UI
+- Third-party OAuth that can't be bypassed
+
+Reference: [Playwright API Request Context](https://playwright.dev/docs/api-testing)
diff --git a/.agents/skills/playwright/references/auth-multiple-roles.md b/.agents/skills/playwright/references/auth-multiple-roles.md
new file mode 100644
index 0000000..d8feebf
--- /dev/null
+++ b/.agents/skills/playwright/references/auth-multiple-roles.md
@@ -0,0 +1,111 @@
+---
+title: Use Separate Storage States for Different Roles
+impact: HIGH
+impactDescription: test role-specific features efficiently
+tags: auth, roles, storage-state, admin, user
+---
+
+## Use Separate Storage States for Different Roles
+
+When testing features for different user roles (admin, user, guest), create separate storage states. This avoids re-authentication while testing role-specific functionality.
+
+**Incorrect (single auth state, role switching):**
+
+```typescript
+// tests/admin.spec.ts
+test('admin can delete users', async ({ page }) => {
+ // Logout from default user
+ await page.goto('/logout');
+
+ // Login as admin
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('admin@example.com');
+ await page.getByLabel('Password').fill('adminpass');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+
+ await page.goto('/admin/users');
+ await page.getByTestId('user-row-1').getByRole('button', { name: 'Delete' }).click();
+});
+```
+
+**Correct (multiple storage states):**
+
+```typescript
+// auth.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+setup('authenticate as user', async ({ page }) => {
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('user@example.com');
+ await page.getByLabel('Password').fill('userpass');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/dashboard');
+ await page.context().storageState({ path: 'playwright/.auth/user.json' });
+});
+
+setup('authenticate as admin', async ({ page }) => {
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('admin@example.com');
+ await page.getByLabel('Password').fill('adminpass');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/admin');
+ await page.context().storageState({ path: 'playwright/.auth/admin.json' });
+});
+
+// playwright.config.ts
+export default defineConfig({
+ projects: [
+ { name: 'setup', testMatch: /.*\.setup\.ts/ },
+
+ {
+ name: 'user-tests',
+ testDir: './tests/user',
+ use: { storageState: 'playwright/.auth/user.json' },
+ dependencies: ['setup'],
+ },
+
+ {
+ name: 'admin-tests',
+ testDir: './tests/admin',
+ use: { storageState: 'playwright/.auth/admin.json' },
+ dependencies: ['setup'],
+ },
+ ],
+});
+
+// tests/user/dashboard.spec.ts
+test('user sees limited menu', async ({ page }) => {
+ await page.goto('/dashboard');
+ await expect(page.getByRole('link', { name: 'Admin' })).toBeHidden();
+});
+
+// tests/admin/users.spec.ts
+test('admin can delete users', async ({ page }) => {
+ await page.goto('/admin/users');
+ await expect(page.getByRole('button', { name: 'Delete' })).toBeVisible();
+});
+```
+
+**Test unauthenticated flows:**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ projects: [
+ // No storage state for unauthenticated tests
+ {
+ name: 'guest-tests',
+ testDir: './tests/guest',
+ // No storageState - tests run as logged out user
+ },
+ ],
+});
+
+// tests/guest/login.spec.ts
+test('redirects to login when not authenticated', async ({ page }) => {
+ await page.goto('/dashboard');
+ await expect(page).toHaveURL('/login');
+});
+```
+
+Reference: [Playwright Testing Multiple Roles](https://playwright.dev/docs/auth#testing-multiple-roles-together)
diff --git a/.agents/skills/playwright/references/auth-parallel-workers.md b/.agents/skills/playwright/references/auth-parallel-workers.md
new file mode 100644
index 0000000..536bbd2
--- /dev/null
+++ b/.agents/skills/playwright/references/auth-parallel-workers.md
@@ -0,0 +1,101 @@
+---
+title: Use Worker-Scoped Auth for Parallel Tests
+impact: MEDIUM-HIGH
+impactDescription: enables parallel testing with unique sessions
+tags: auth, parallel, workers, fixtures, isolation
+---
+
+## Use Worker-Scoped Auth for Parallel Tests
+
+When running tests in parallel, each worker needs its own authentication to avoid conflicts. Use worker-scoped fixtures to authenticate once per worker with unique test accounts.
+
+**Incorrect (shared auth in parallel):**
+
+```typescript
+// All parallel workers use same auth state
+// Causes conflicts when tests modify user data
+export default defineConfig({
+ workers: 4,
+ use: {
+ storageState: 'playwright/.auth/user.json', // Same for all workers!
+ },
+});
+```
+
+**Correct (worker-scoped auth fixtures):**
+
+```typescript
+// fixtures/auth.ts
+import { test as base } from '@playwright/test';
+
+// Test users - one per potential parallel worker
+const testUsers = [
+ { email: 'test1@example.com', password: 'pass1' },
+ { email: 'test2@example.com', password: 'pass2' },
+ { email: 'test3@example.com', password: 'pass3' },
+ { email: 'test4@example.com', password: 'pass4' },
+];
+
+export const test = base.extend<{}, { workerStorageState: string }>({
+ // Worker-scoped fixture - runs once per worker
+ workerStorageState: [
+ async ({ browser }, use, workerInfo) => {
+ // Each worker gets unique user based on parallelIndex
+ const user = testUsers[workerInfo.parallelIndex % testUsers.length];
+
+ const fileName = `playwright/.auth/worker-${workerInfo.parallelIndex}.json`;
+
+ // Authenticate this worker's user
+ const context = await browser.newContext();
+ const page = await context.newPage();
+
+ await page.goto('/login');
+ await page.getByLabel('Email').fill(user.email);
+ await page.getByLabel('Password').fill(user.password);
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/dashboard');
+
+ await context.storageState({ path: fileName });
+ await context.close();
+
+ await use(fileName);
+ },
+ { scope: 'worker' },
+ ],
+
+ // Override storageState to use worker-specific auth
+ storageState: async ({ workerStorageState }, use) => {
+ await use(workerStorageState);
+ },
+});
+
+export { expect } from '@playwright/test';
+
+// tests/dashboard.spec.ts
+import { test, expect } from '../fixtures/auth';
+
+test('user can update profile', async ({ page }) => {
+ // Each worker has isolated user - no conflicts
+ await page.goto('/profile');
+ await page.getByLabel('Bio').fill('Updated bio');
+ await page.getByRole('button', { name: 'Save' }).click();
+ await expect(page.getByText('Profile updated')).toBeVisible();
+});
+```
+
+**Create test users in setup:**
+
+```typescript
+// global-setup.ts
+export default async function globalSetup() {
+ // Ensure test users exist before tests run
+ for (let i = 0; i < 4; i++) {
+ await createTestUser({
+ email: `test${i + 1}@example.com`,
+ password: `pass${i + 1}`,
+ });
+ }
+}
+```
+
+Reference: [Playwright Worker-Scoped Fixtures](https://playwright.dev/docs/auth#authenticating-in-ui-mode)
diff --git a/.agents/skills/playwright/references/auth-session-storage.md b/.agents/skills/playwright/references/auth-session-storage.md
new file mode 100644
index 0000000..2458471
--- /dev/null
+++ b/.agents/skills/playwright/references/auth-session-storage.md
@@ -0,0 +1,106 @@
+---
+title: Handle Session Storage for Auth
+impact: HIGH
+impactDescription: preserves auth state that uses sessionStorage
+tags: auth, session-storage, storage-state, workaround, tokens
+---
+
+## Handle Session Storage for Auth
+
+Playwright's `storageState` saves cookies and localStorage, but NOT sessionStorage (which is tab-specific). For apps using sessionStorage for auth tokens, use workarounds to preserve state.
+
+**Incorrect (sessionStorage not persisted):**
+
+```typescript
+// Your app stores JWT in sessionStorage
+sessionStorage.setItem('authToken', 'jwt-token-here');
+
+// auth.setup.ts
+setup('authenticate', async ({ page }) => {
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('user@example.com');
+ await page.getByLabel('Password').fill('password');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+
+ // This ONLY saves cookies and localStorage, NOT sessionStorage!
+ await page.context().storageState({ path: 'playwright/.auth/user.json' });
+});
+
+// Tests fail because sessionStorage auth token is lost
+```
+
+**Correct (save and restore sessionStorage manually):**
+
+```typescript
+// auth.setup.ts
+import { test as setup } from '@playwright/test';
+import fs from 'fs';
+
+setup('authenticate', async ({ page }) => {
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('user@example.com');
+ await page.getByLabel('Password').fill('password');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/dashboard');
+
+ // Save regular storage state
+ await page.context().storageState({ path: 'playwright/.auth/user.json' });
+
+ // Save sessionStorage separately
+ const sessionStorage = await page.evaluate(() =>
+ JSON.stringify(sessionStorage)
+ );
+ fs.writeFileSync('playwright/.auth/session.json', sessionStorage);
+});
+
+// fixtures/auth.ts
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+
+export const test = base.extend({
+ page: async ({ page }, use) => {
+ // Restore sessionStorage before each test
+ const sessionStorageData = fs.readFileSync(
+ 'playwright/.auth/session.json',
+ 'utf-8'
+ );
+
+ await page.addInitScript((data) => {
+ const entries = JSON.parse(data);
+ for (const [key, value] of Object.entries(entries)) {
+ window.sessionStorage.setItem(key, value as string);
+ }
+ }, sessionStorageData);
+
+ await use(page);
+ },
+});
+
+// tests/dashboard.spec.ts
+import { test } from '../fixtures/auth';
+
+test('dashboard loads with session token', async ({ page }) => {
+ await page.goto('/dashboard');
+ await expect(page.getByTestId('user-profile')).toBeVisible();
+});
+```
+
+**Alternative: use API to set auth:**
+
+```typescript
+// If your app accepts auth via API
+test.beforeEach(async ({ page, request }) => {
+ // Get token via API
+ const response = await request.post('/api/auth/login', {
+ data: { email: 'user@example.com', password: 'password' },
+ });
+ const { token } = await response.json();
+
+ // Set token in sessionStorage before navigating
+ await page.addInitScript((authToken) => {
+ window.sessionStorage.setItem('authToken', authToken);
+ }, token);
+});
+```
+
+Reference: [Playwright Session Storage](https://playwright.dev/docs/auth#session-storage)
diff --git a/.agents/skills/playwright/references/auth-storage-state.md b/.agents/skills/playwright/references/auth-storage-state.md
new file mode 100644
index 0000000..69fe2a1
--- /dev/null
+++ b/.agents/skills/playwright/references/auth-storage-state.md
@@ -0,0 +1,97 @@
+---
+title: Reuse Authentication with Storage State
+impact: HIGH
+impactDescription: 60-80% reduction in test execution time
+tags: auth, storage-state, session, cookies, login
+---
+
+## Reuse Authentication with Storage State
+
+Logging in for every test wastes time. Playwright can save and reuse authentication state (cookies, localStorage), eliminating repeated logins.
+
+**Incorrect (login in every test):**
+
+```typescript
+// tests/dashboard.spec.ts
+test('view user stats', async ({ page }) => {
+ // Login repeated in every single test
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('user@example.com');
+ await page.getByLabel('Password').fill('password123');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/dashboard');
+
+ await expect(page.getByTestId('stats')).toBeVisible();
+});
+
+test('view notifications', async ({ page }) => {
+ // Same login code repeated
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('user@example.com');
+ await page.getByLabel('Password').fill('password123');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/dashboard');
+
+ await page.goto('/notifications');
+ await expect(page.getByTestId('notification-list')).toBeVisible();
+});
+```
+
+**Correct (storage state reuse):**
+
+```typescript
+// auth.setup.ts
+import { test as setup, expect } from '@playwright/test';
+
+const authFile = 'playwright/.auth/user.json';
+
+setup('authenticate', async ({ page }) => {
+ await page.goto('/login');
+ await page.getByLabel('Email').fill('user@example.com');
+ await page.getByLabel('Password').fill('password123');
+ await page.getByRole('button', { name: 'Sign in' }).click();
+ await page.waitForURL('/dashboard');
+
+ // Save authentication state
+ await page.context().storageState({ path: authFile });
+});
+
+// playwright.config.ts
+export default defineConfig({
+ projects: [
+ // Setup project runs first
+ { name: 'setup', testMatch: /.*\.setup\.ts/ },
+
+ // Tests use saved auth state
+ {
+ name: 'chromium',
+ use: {
+ ...devices['Desktop Chrome'],
+ storageState: 'playwright/.auth/user.json',
+ },
+ dependencies: ['setup'],
+ },
+ ],
+});
+
+// tests/dashboard.spec.ts
+test('view user stats', async ({ page }) => {
+ // Already logged in via storage state!
+ await page.goto('/dashboard');
+ await expect(page.getByTestId('stats')).toBeVisible();
+});
+
+test('view notifications', async ({ page }) => {
+ await page.goto('/notifications');
+ await expect(page.getByTestId('notification-list')).toBeVisible();
+});
+```
+
+**Add `.auth` to `.gitignore`:**
+
+```gitignore
+# playwright/.auth contains sensitive session data
+playwright/.auth/
+```
+
+Reference: [Playwright Authentication](https://playwright.dev/docs/auth)
diff --git a/.agents/skills/playwright/references/debug-ci-reporters.md b/.agents/skills/playwright/references/debug-ci-reporters.md
new file mode 100644
index 0000000..ed60162
--- /dev/null
+++ b/.agents/skills/playwright/references/debug-ci-reporters.md
@@ -0,0 +1,81 @@
+---
+title: Configure Reporters for CI Integration
+impact: LOW-MEDIUM
+impactDescription: 2× faster CI failure triage
+tags: debug, reporters, ci, github, annotations
+---
+
+## Configure Reporters for CI Integration
+
+Choose reporters that integrate with your CI system. GitHub Actions annotations, JUnit XML, and HTML reports each serve different purposes.
+
+**Incorrect (default reporter only):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ // Default reporter only shows console output
+ // No CI integration, no artifacts
+});
+
+// CI output:
+// FAILED tests/login.spec.ts:15
+// Error: expect(locator).toBeVisible()
+// - No GitHub annotations
+// - No browsable report
+// - Hard to find in CI logs
+```
+
+**Correct (multi-reporter for CI):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ reporter: process.env.CI
+ ? [
+ ['github'], // GitHub Actions annotations
+ ['junit', { outputFile: 'test-results/junit.xml' }], // CI systems
+ ['html', { open: 'never' }], // Detailed HTML report
+ ]
+ : [
+ ['list'], // Console output
+ ['html', { open: 'on-failure' }], // Open HTML on failure
+ ],
+});
+
+// CI output now includes:
+// - Inline annotations on PR files
+// - JUnit for CI dashboards
+// - HTML report artifact
+```
+
+**JUnit for CI dashboards:**
+
+```yaml
+# .github/workflows/test.yml
+- name: Run tests
+ run: npx playwright test
+
+- name: Publish Test Results
+ uses: dorny/test-reporter@v1
+ if: always()
+ with:
+ name: Playwright Tests
+ path: test-results/junit.xml
+ reporter: java-junit
+```
+
+**HTML report hosting:**
+
+```yaml
+# .github/workflows/test.yml
+- name: Upload HTML Report
+ uses: actions/upload-artifact@v4
+ if: always()
+ with:
+ name: playwright-report
+ path: playwright-report/
+ retention-days: 14
+```
+
+Reference: [Playwright Reporters](https://playwright.dev/docs/test-reporters)
diff --git a/.agents/skills/playwright/references/debug-inspector.md b/.agents/skills/playwright/references/debug-inspector.md
new file mode 100644
index 0000000..fbf199f
--- /dev/null
+++ b/.agents/skills/playwright/references/debug-inspector.md
@@ -0,0 +1,86 @@
+---
+title: Use Playwright Inspector for Interactive Debugging
+impact: LOW-MEDIUM
+impactDescription: 5× faster test development and debugging
+tags: debug, inspector, breakpoints, interactive, development
+---
+
+## Use Playwright Inspector for Interactive Debugging
+
+Playwright Inspector lets you step through tests interactively, inspect selectors, and generate code. Use it for developing new tests and debugging failures.
+
+**Incorrect (blind debugging):**
+
+```typescript
+// tests/checkout.spec.ts
+test('complete checkout', async ({ page }) => {
+ await page.goto('/checkout');
+
+ // Something fails here but you don't know why
+ await page.getByRole('button', { name: 'Pay' }).click();
+ // Error: locator.click: Target closed
+
+ // Without inspector, you're guessing:
+ // - Is the button there?
+ // - Is it visible?
+ // - Is there an overlay blocking it?
+});
+
+// Run: npx playwright test
+// Output: Error with no visual context
+```
+
+**Correct (interactive debugging):**
+
+```typescript
+// tests/checkout.spec.ts
+test('complete checkout', async ({ page }) => {
+ await page.goto('/checkout');
+
+ // Add breakpoint to pause and inspect
+ await page.pause();
+
+ // Now you can:
+ // - See the actual page state
+ // - Test different selectors
+ // - Step through one action at a time
+ await page.getByRole('button', { name: 'Pay' }).click();
+});
+
+// Run: npx playwright test --debug
+// Inspector opens with full visibility
+```
+
+**Launch inspector methods:**
+
+```bash
+# Run all tests with inspector
+npx playwright test --debug
+
+# Run specific test with inspector
+npx playwright test tests/login.spec.ts --debug
+
+# Debug specific test by name
+npx playwright test -g "login flow" --debug
+```
+
+**VS Code integration:**
+
+```json
+// .vscode/launch.json
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "node",
+ "request": "launch",
+ "name": "Debug Playwright Tests",
+ "runtimeExecutable": "npx",
+ "runtimeArgs": ["playwright", "test", "--debug"],
+ "console": "integratedTerminal"
+ }
+ ]
+}
+```
+
+Reference: [Playwright Inspector](https://playwright.dev/docs/debug#playwright-inspector)
diff --git a/.agents/skills/playwright/references/debug-screenshots-videos.md b/.agents/skills/playwright/references/debug-screenshots-videos.md
new file mode 100644
index 0000000..718ad77
--- /dev/null
+++ b/.agents/skills/playwright/references/debug-screenshots-videos.md
@@ -0,0 +1,85 @@
+---
+title: Capture Screenshots and Videos on Failure
+impact: LOW-MEDIUM
+impactDescription: faster failure investigation
+tags: debug, screenshots, video, failure, artifacts
+---
+
+## Capture Screenshots and Videos on Failure
+
+Visual artifacts provide immediate insight into what the page looked like when a test failed. Configure automatic capture for efficient debugging.
+
+**Incorrect (no artifact capture):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ use: {
+ // No screenshot or video configuration
+ // When tests fail, you only get error messages
+ },
+});
+
+// Test failure output:
+// Error: expect(locator).toBeVisible()
+// Locator: getByText('Welcome')
+// - No visual of actual page state
+// - No recording of what led to failure
+```
+
+**Correct (capture on failure):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ use: {
+ // Screenshots on failure
+ screenshot: 'only-on-failure',
+
+ // Video on failure
+ video: 'retain-on-failure',
+ },
+});
+
+// Test failure now includes:
+// - Screenshot of final page state
+// - Video of entire test execution
+```
+
+**Video configuration options:**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ use: {
+ video: {
+ mode: 'retain-on-failure',
+ size: { width: 1280, height: 720 }, // Video resolution
+ },
+ },
+});
+```
+
+**CI artifact upload:**
+
+```yaml
+# .github/workflows/test.yml
+- name: Run tests
+ run: npx playwright test
+
+- name: Upload screenshots and videos
+ uses: actions/upload-artifact@v4
+ if: failure()
+ with:
+ name: test-artifacts
+ path: |
+ test-results/**/*.png
+ test-results/**/*.webm
+ retention-days: 7
+```
+
+**Storage considerations:**
+
+Artifact sizes vary substantially by viewport, duration, assets, and trace settings. Capture screenshots on failure, retain video selectively, and use `trace: 'on-first-retry'` or another deliberate policy. Measure CI artifact volume and apply retention limits rather than relying on fixed size estimates.
+
+Reference: [Playwright Screenshots](https://playwright.dev/docs/screenshots)
diff --git a/.agents/skills/playwright/references/debug-trace-viewer.md b/.agents/skills/playwright/references/debug-trace-viewer.md
new file mode 100644
index 0000000..5601f42
--- /dev/null
+++ b/.agents/skills/playwright/references/debug-trace-viewer.md
@@ -0,0 +1,79 @@
+---
+title: Use Trace Viewer for Failed Tests
+impact: LOW-MEDIUM
+impactDescription: 10× faster debugging with step-by-step replay
+tags: debug, trace, viewer, debugging, failure-analysis
+---
+
+## Use Trace Viewer for Failed Tests
+
+Playwright's Trace Viewer shows a step-by-step replay of test execution including screenshots, DOM snapshots, network requests, and console logs. Essential for debugging CI failures.
+
+**Incorrect (no trace capture configured):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ use: {
+ // No trace configuration
+ // When tests fail in CI, you have no visibility into what happened
+ },
+});
+
+// Test fails in CI - you only see error message
+// No way to see page state, network requests, or console logs
+```
+
+**Correct (trace on failure):**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ use: {
+ // Record a trace on the first retry of a failed test (requires retries > 0)
+ trace: 'on-first-retry',
+
+ // Alternative options:
+ // trace: 'on' - Always capture (large files)
+ // trace: 'retain-on-failure' - Keep only for failures
+ // trace: 'off' - Never capture
+ },
+});
+```
+
+Playwright 1.63 can also record accessibility-tree (aria) snapshots, shown in the trace viewer's "Display Aria" view. Pick which snapshots to record with the object form: `trace: { mode: 'on-first-retry', snapshots: { dom: true, aria: true, screen: true } }`. Steps can carry context into the trace and reporters: `test.step('Checkout', body, { subtitle: 'guest user', params: { sku } })`.
+
+**View traces locally:**
+
+```bash
+# After test failure, open trace
+npx playwright show-trace test-results/test-name/trace.zip
+
+# Or view in browser
+npx playwright show-trace --browser
+
+# Opens interactive viewer with:
+# - Timeline of actions
+# - Screenshots at each step
+# - Network requests
+# - Console logs
+# - DOM snapshots
+```
+
+**Download traces from CI:**
+
+```yaml
+# .github/workflows/test.yml
+- name: Run tests
+ run: npx playwright test
+
+- name: Upload trace artifacts
+ uses: actions/upload-artifact@v4
+ if: failure() # Only upload on failure
+ with:
+ name: playwright-traces
+ path: test-results/
+ retention-days: 7
+```
+
+Reference: [Playwright Trace Viewer](https://playwright.dev/docs/trace-viewer)
diff --git a/.agents/skills/playwright/references/loc-avoid-xpath.md b/.agents/skills/playwright/references/loc-avoid-xpath.md
new file mode 100644
index 0000000..3b5b095
--- /dev/null
+++ b/.agents/skills/playwright/references/loc-avoid-xpath.md
@@ -0,0 +1,64 @@
+---
+title: Avoid XPath Selectors
+impact: HIGH
+impactDescription: DOM-structure selectors are brittle and do not express user-facing contracts
+tags: loc, xpath, performance, selectors, anti-pattern
+---
+
+## Avoid XPath Selectors
+
+XPath selectors often encode DOM structure rather than user-visible behavior, so they break easily when markup changes. Prefer Playwright's role, label, text, test-id, and filtering locators. Treat maintainability and actionability as the reason; selector timing depends on the page and browser.
+
+**Incorrect (XPath selectors):**
+
+```typescript
+// tests/table.spec.ts
+test('edit user in table', async ({ page }) => {
+ await page.goto('/admin/users');
+
+ // Slow: full DOM traversal
+ await page.locator('//table//tr[contains(.,"john@example.com")]//button[text()="Edit"]').click();
+
+ // Brittle: breaks if table structure changes
+ await page.locator('//div[@class="container"]/div[2]/table/tbody/tr[3]/td[4]/button').click();
+
+ // Hard to read and maintain
+ await page.locator('//button[ancestor::tr[descendant::td[text()="Active"]]]').click();
+});
+```
+
+**Correct (role-based and CSS alternatives):**
+
+```typescript
+// tests/table.spec.ts
+test('edit user in table', async ({ page }) => {
+ await page.goto('/admin/users');
+
+ // Find row by content, then action button
+ const userRow = page.getByRole('row', { name: /john@example.com/ });
+ await userRow.getByRole('button', { name: 'Edit' }).click();
+
+ // Or use data-testid for complex tables
+ await page.getByTestId('user-row-john').getByRole('button', { name: 'Edit' }).click();
+});
+```
+
+**Alternative approaches for complex queries:**
+
+```typescript
+// Filter locators instead of XPath
+const activeUsers = page.getByRole('row').filter({
+ has: page.getByText('Active'),
+});
+await activeUsers.first().getByRole('button', { name: 'Edit' }).click();
+
+// Chain locators for specificity
+await page
+ .getByRole('table', { name: 'Users' })
+ .getByRole('row')
+ .filter({ hasText: 'john@example.com' })
+ .getByRole('button', { name: 'Edit' })
+ .click();
+```
+
+Reference: [Playwright Locator Best Practices](https://playwright.dev/docs/best-practices#use-locators)
diff --git a/.agents/skills/playwright/references/loc-chained-locators.md b/.agents/skills/playwright/references/loc-chained-locators.md
new file mode 100644
index 0000000..8fd5401
--- /dev/null
+++ b/.agents/skills/playwright/references/loc-chained-locators.md
@@ -0,0 +1,87 @@
+---
+title: Chain Locators for Specificity
+impact: HIGH
+impactDescription: reduces ambiguity without brittle selectors
+tags: loc, chaining, filter, specificity, locators
+---
+
+## Chain Locators for Specificity
+
+When a single locator matches multiple elements, chain locators to narrow scope. This is more maintainable than complex CSS or XPath selectors.
+
+**Incorrect (overly specific single selector):**
+
+```typescript
+// tests/products.spec.ts
+test('add featured product to cart', async ({ page }) => {
+ await page.goto('/products');
+
+ // Brittle: depends on exact DOM structure
+ await page.locator('section.featured-products div.product-card:first-child button.add-to-cart').click();
+
+ // Ambiguous: might match wrong element
+ await page.getByRole('button', { name: 'Add to Cart' }).click();
+});
+```
+
+**Correct (chained locators):**
+
+```typescript
+// tests/products.spec.ts
+test('add featured product to cart', async ({ page }) => {
+ await page.goto('/products');
+
+ // Chain from container to specific element
+ const featuredSection = page.getByRole('region', { name: 'Featured Products' });
+ const firstProduct = featuredSection.getByTestId('product-card').first();
+ await firstProduct.getByRole('button', { name: 'Add to Cart' }).click();
+});
+```
+
+**Using filter for conditional matching:**
+
+```typescript
+// Find product by name, then interact with it
+const productCard = page
+ .getByTestId('product-card')
+ .filter({ hasText: 'Wireless Headphones' });
+
+await productCard.getByRole('button', { name: 'Add to Cart' }).click();
+
+// Filter by child element
+const discountedProducts = page
+ .getByTestId('product-card')
+ .filter({ has: page.getByText('Sale') });
+
+await expect(discountedProducts).toHaveCount(3);
+```
+
+**Visible elements only (Playwright 1.63+):**
+
+Responsive layouts often render the same control twice, once per breakpoint, with one copy hidden. Use `.visible()` rather than `.first()` or the `:visible` CSS pseudo-class. Visibility is checked each time the locator is used.
+
+```typescript
+await page.getByRole('button', { name: 'Menu' }).visible().click();
+
+// The opposite: match only hidden copies
+page.getByRole('button', { name: 'Menu' }).filter({ visible: false });
+```
+
+**Combining multiple filters:**
+
+```typescript
+// Products that are both in-stock AND discounted
+const availableDeals = page
+ .getByTestId('product-card')
+ .filter({ has: page.getByText('In Stock') })
+ .filter({ has: page.getByTestId('discount-badge') });
+
+await availableDeals.first().click();
+```
+
+**Benefits:**
+- Each step is readable and debuggable
+- Survives partial DOM changes
+- Self-documenting test intent
+
+Reference: [Playwright Filtering Locators](https://playwright.dev/docs/locators#filtering-locators)
diff --git a/.agents/skills/playwright/references/loc-data-testid.md b/.agents/skills/playwright/references/loc-data-testid.md
new file mode 100644
index 0000000..a62d677
--- /dev/null
+++ b/.agents/skills/playwright/references/loc-data-testid.md
@@ -0,0 +1,80 @@
+---
+title: Use data-testid for Dynamic Elements
+impact: CRITICAL
+impactDescription: stable selectors for dynamic content
+tags: loc, data-testid, testing, selectors, attributes
+---
+
+## Use data-testid for Dynamic Elements
+
+When elements lack accessible names or roles, use `data-testid` attributes. These are explicitly for testing and won't change during normal development.
+
+**Incorrect (fragile selectors for dynamic content):**
+
+```typescript
+// tests/dashboard.spec.ts
+test('shows user stats', async ({ page }) => {
+ await page.goto('/dashboard');
+
+ // Breaks when text formatting changes
+ await expect(page.locator('text=Active Users: 42')).toBeVisible();
+
+ // Breaks when CSS class changes
+ await expect(page.locator('.stat-card:first-child .value')).toHaveText('42');
+
+ // Breaks when order changes
+ await expect(page.locator('div:nth-child(3)')).toContainText('Revenue');
+});
+```
+
+**Correct (data-testid for dynamic elements):**
+
+```typescript
+// components/StatsCard.tsx
+export function StatsCard({ label, value }: Props) {
+ return (
+
+ {label}
+
+ {value}
+
+
+ );
+}
+
+// tests/dashboard.spec.ts
+test('shows user stats', async ({ page }) => {
+ await page.goto('/dashboard');
+
+ // Stable selectors using data-testid
+ await expect(page.getByTestId('stat-active-users')).toBeVisible();
+ await expect(page.getByTestId('stat-active-users-value')).toHaveText('42');
+ await expect(page.getByTestId('stat-revenue')).toBeVisible();
+});
+```
+
+**Custom test ID attribute:**
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+ use: {
+ // Use custom attribute if data-testid conflicts with existing code
+ testIdAttribute: 'data-pw',
+ },
+});
+
+// component.tsx
+Submit
+
+// test.spec.ts
+await page.getByTestId('submit-button').click();
+```
+
+**When to use data-testid:**
+- Dynamic content without stable text
+- Multiple similar elements (list items, cards)
+- Elements generated by third-party libraries
+- Complex interactive components
+
+Reference: [Playwright Test ID](https://playwright.dev/docs/locators#locate-by-test-id)
diff --git a/.agents/skills/playwright/references/loc-frame-locator.md b/.agents/skills/playwright/references/loc-frame-locator.md
new file mode 100644
index 0000000..715db6f
--- /dev/null
+++ b/.agents/skills/playwright/references/loc-frame-locator.md
@@ -0,0 +1,45 @@
+---
+title: Locate Elements Inside iframes with frameLocator
+impact: HIGH
+impactDescription: page locators do not pierce iframes; payment, captcha and embed widgets need a frame locator
+tags: locators, iframe, frameLocator, third-party, embeds
+---
+
+## Locate Elements Inside iframes with frameLocator
+
+Locators from `page.getByRole()` and friends only search the main document. Content inside an `