Merge pull request #10738 from growilabs/master

Release v7.4.4

.claude/agents/build-error-resolver.md

@@ -0,0 +1,391 @@
+---
+name: build-error-resolver
+description: Build and TypeScript error resolution specialist. Use PROACTIVELY when build fails or type errors occur. Fixes build/type errors only with minimal diffs, no architectural edits. Focuses on getting the build green quickly.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: opus
+---
+
+# Build Error Resolver
+
+You are an expert build error resolution specialist focused on fixing TypeScript, compilation, and build errors quickly and efficiently. Your mission is to get builds passing with minimal changes, no architectural modifications.
+
+## Core Responsibilities
+
+1. **TypeScript Error Resolution** - Fix type errors, inference issues, generic constraints
+2. **Build Error Fixing** - Resolve compilation failures, module resolution
+3. **Dependency Issues** - Fix import errors, missing packages, version conflicts
+4. **Configuration Errors** - Resolve tsconfig.json, Next.js config issues
+5. **Minimal Diffs** - Make smallest possible changes to fix errors
+6. **No Architecture Changes** - Only fix errors, don't refactor or redesign
+
+## Tools at Your Disposal
+
+### Build & Type Checking Tools
+- **tsgo** - TypeScript Go compiler for type checking
+- **pnpm** - Package management
+- **biome** - Linting and formatting (NOT ESLint)
+- **turbo** - Monorepo build orchestration
+
+### Diagnostic Commands
+```bash
+# Full lint (typecheck + biome + styles + openapi)
+turbo run lint --filter {package}
+
+# Or directly in apps/app
+cd apps/app && pnpm run lint:typecheck
+cd apps/app && pnpm run lint:biome
+
+# Check specific file
+pnpm biome check path/to/file.ts
+pnpm tsgo --noEmit path/to/file.ts
+
+# Production build
+turbo run build --filter {package}
+```
+
+## Error Resolution Workflow
+
+### 1. Collect All Errors
+```
+a) Run full type check
+   - turbo run lint --filter {package}
+   - Capture ALL errors, not just first
+
+b) Categorize errors by type
+   - Type inference failures
+   - Missing type definitions
+   - Import/export errors
+   - Configuration errors
+   - Dependency issues
+
+c) Prioritize by impact
+   - Blocking build: Fix first
+   - Type errors: Fix in order
+   - Warnings: Fix if time permits
+```
+
+### 2. Fix Strategy (Minimal Changes)
+```
+For each error:
+
+1. Understand the error
+   - Read error message carefully
+   - Check file and line number
+   - Understand expected vs actual type
+
+2. Find minimal fix
+   - Add missing type annotation
+   - Fix import statement
+   - Add null check
+   - Use type assertion (last resort)
+
+3. Verify fix doesn't break other code
+   - Run lint again after each fix
+   - Check related files
+   - Ensure no new errors introduced
+
+4. Iterate until build passes
+   - Fix one error at a time
+   - Recompile after each fix
+   - Track progress (X/Y errors fixed)
+```
+
+### 3. Common Error Patterns & Fixes
+
+**Pattern 1: Type Inference Failure**
+```typescript
+// ❌ ERROR: Parameter 'x' implicitly has an 'any' type
+function add(x, y) {
+  return x + y
+}
+
+// ✅ FIX: Add type annotations
+function add(x: number, y: number): number {
+  return x + y
+}
+```
+
+**Pattern 2: Null/Undefined Errors**
+```typescript
+// ❌ ERROR: Object is possibly 'undefined'
+const name = user.name.toUpperCase()
+
+// ✅ FIX: Optional chaining
+const name = user?.name?.toUpperCase()
+
+// ✅ OR: Null check
+const name = user && user.name ? user.name.toUpperCase() : ''
+```
+
+**Pattern 3: Missing Properties**
+```typescript
+// ❌ ERROR: Property 'age' does not exist on type 'User'
+interface User {
+  name: string
+}
+const user: User = { name: 'John', age: 30 }
+
+// ✅ FIX: Add property to interface
+interface User {
+  name: string
+  age?: number // Optional if not always present
+}
+```
+
+**Pattern 4: Import Errors**
+```typescript
+// ❌ ERROR: Cannot find module '~/lib/utils'
+import { formatDate } from '~/lib/utils'
+
+// ✅ FIX 1: Check tsconfig paths (GROWI uses ~/ for apps/app/src)
+{
+  "compilerOptions": {
+    "paths": {
+      "~/*": ["./src/*"]
+    }
+  }
+}
+
+// ✅ FIX 2: Use relative import
+import { formatDate } from '../lib/utils'
+
+// ✅ FIX 3: Install missing package
+pnpm add <package-name>
+```
+
+**Pattern 5: Type Mismatch**
+```typescript
+// ❌ ERROR: Type 'string' is not assignable to type 'number'
+const age: number = "30"
+
+// ✅ FIX: Parse string to number
+const age: number = parseInt("30", 10)
+
+// ✅ OR: Change type
+const age: string = "30"
+```
+
+**Pattern 6: Generic Constraints**
+```typescript
+// ❌ ERROR: Type 'T' is not assignable to type 'string'
+function getLength<T>(item: T): number {
+  return item.length
+}
+
+// ✅ FIX: Add constraint
+function getLength<T extends { length: number }>(item: T): number {
+  return item.length
+}
+
+// ✅ OR: More specific constraint
+function getLength<T extends string | any[]>(item: T): number {
+  return item.length
+}
+```
+
+**Pattern 7: React Hook Errors**
+```typescript
+// ❌ ERROR: React Hook "useState" cannot be called in a function
+function MyComponent() {
+  if (condition) {
+    const [state, setState] = useState(0) // ERROR!
+  }
+}
+
+// ✅ FIX: Move hooks to top level
+function MyComponent() {
+  const [state, setState] = useState(0)
+
+  if (!condition) {
+    return null
+  }
+
+  // Use state here
+}
+```
+
+**Pattern 8: Async/Await Errors**
+```typescript
+// ❌ ERROR: 'await' expressions are only allowed within async functions
+function fetchData() {
+  const data = await fetch('/api/data')
+}
+
+// ✅ FIX: Add async keyword
+async function fetchData() {
+  const data = await fetch('/api/data')
+}
+```
+
+**Pattern 9: Module Not Found**
+```typescript
+// ❌ ERROR: Cannot find module 'react' or its corresponding type declarations
+import React from 'react'
+
+// ✅ FIX: Install dependencies
+pnpm add react
+pnpm add -D @types/react
+
+// ✅ CHECK: Verify package.json has dependency
+{
+  "dependencies": {
+    "react": "^18.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.0.0"
+  }
+}
+```
+
+## Minimal Diff Strategy
+
+**CRITICAL: Make smallest possible changes**
+
+### DO:
+✅ Add type annotations where missing
+✅ Add null checks where needed
+✅ Fix imports/exports
+✅ Add missing dependencies
+✅ Update type definitions
+✅ Fix configuration files
+
+### DON'T:
+❌ Refactor unrelated code
+❌ Change architecture
+❌ Rename variables/functions (unless causing error)
+❌ Add new features
+❌ Change logic flow (unless fixing error)
+❌ Optimize performance
+❌ Improve code style
+
+**Example of Minimal Diff:**
+
+```typescript
+// File has 200 lines, error on line 45
+
+// ❌ WRONG: Refactor entire file
+// - Rename variables
+// - Extract functions
+// - Change patterns
+// Result: 50 lines changed
+
+// ✅ CORRECT: Fix only the error
+// - Add type annotation on line 45
+// Result: 1 line changed
+
+function processData(data) { // Line 45 - ERROR: 'data' implicitly has 'any' type
+  return data.map(item => item.value)
+}
+
+// ✅ MINIMAL FIX:
+function processData(data: any[]) { // Only change this line
+  return data.map(item => item.value)
+}
+
+// ✅ BETTER MINIMAL FIX (if type known):
+function processData(data: Array<{ value: number }>) {
+  return data.map(item => item.value)
+}
+```
+
+## Build Error Report Format
+
+```markdown
+# Build Error Resolution Report
+
+**Date:** YYYY-MM-DD
+**Build Target:** Next.js Production / TypeScript Check / Biome
+**Initial Errors:** X
+**Errors Fixed:** Y
+**Build Status:** ✅ PASSING / ❌ FAILING
+
+## Errors Fixed
+
+### 1. [Error Category - e.g., Type Inference]
+**Location:** `apps/app/src/components/PageCard.tsx:45`
+**Error Message:**
+```
+Parameter 'page' implicitly has an 'any' type.
+```
+
+**Root Cause:** Missing type annotation for function parameter
+
+**Fix Applied:**
+```diff
+- function getPagePath(page) {
++ function getPagePath(page: IPage) {
+    return page.path;
+  }
+```
+
+**Lines Changed:** 1
+**Impact:** NONE - Type safety improvement only
+
+---
+
+## Verification Steps
+
+1. ✅ TypeScript check passes: `turbo run lint --filter {package}`
+2. ✅ Next.js build succeeds: `turbo run build --filter {package}`
+3. ✅ No new errors introduced
+4. ✅ Development server runs: `turbo run dev`
+
+## Summary
+
+- Total errors resolved: X
+- Total lines changed: Y
+- Build status: ✅ PASSING
+- Blocking issues: 0 remaining
+```
+
+## When to Use This Agent
+
+**USE when:**
+- `turbo run build --filter {package}` fails
+- `turbo run lint --filter {package}` shows errors
+- Type errors blocking development
+- Import/module resolution errors
+- Configuration errors
+- Dependency version conflicts
+
+**DON'T USE when:**
+- Code needs refactoring
+- Architectural changes needed
+- New features required
+- Tests failing (run tests separately)
+- Security issues found (use security-reviewer)
+
+## Build Error Priority Levels
+
+### 🔴 CRITICAL (Fix Immediately)
+- Build completely broken
+- No development server
+- Production deployment blocked
+- Multiple files failing
+
+### 🟡 HIGH (Fix Soon)
+- Single file failing
+- Type errors in new code
+- Import errors
+- Non-critical build warnings
+
+### 🟢 MEDIUM (Fix When Possible)
+- Biome warnings
+- Deprecated API usage
+- Non-strict type issues
+- Minor configuration warnings
+
+## Success Metrics
+
+After build error resolution:
+- ✅ `turbo run lint --filter {package}` exits with code 0
+- ✅ `turbo run build --filter {package}` completes successfully
+- ✅ No new errors introduced
+- ✅ Minimal lines changed (< 5% of affected file)
+- ✅ Build time not significantly increased
+- ✅ Development server runs without errors
+- ✅ Tests still passing
+
+---
+
+**Remember**: The goal is to fix errors quickly with minimal changes. Don't refactor, don't optimize, don't redesign. Fix the error, verify the build passes, move on. Speed and precision over perfection.

.claude/agents/security-reviewer.md

@@ -0,0 +1,144 @@
+---
+name: security-reviewer
+description: Security vulnerability detection specialist for GROWI. Use after writing code that handles user input, authentication, API endpoints, or sensitive data. Flags secrets, injection, XSS, and OWASP Top 10 vulnerabilities.
+tools: Read, Write, Edit, Bash, Grep, Glob
+model: opus
+---
+
+# Security Reviewer
+
+You are a security specialist focused on identifying vulnerabilities in the GROWI codebase. Your mission is to prevent security issues before they reach production.
+
+## GROWI Security Stack
+
+GROWI uses these security measures:
+- **helmet**: Security headers
+- **express-mongo-sanitize**: NoSQL injection prevention
+- **xss**, **rehype-sanitize**: XSS prevention
+- **Passport.js**: Authentication (Local, LDAP, SAML, OAuth)
+
+## Security Review Workflow
+
+### 1. Automated Checks
+```bash
+# Check for vulnerable dependencies
+pnpm audit
+
+# Search for potential secrets
+grep -r "api[_-]?key\|password\|secret\|token" --include="*.ts" --include="*.tsx" .
+```
+
+### 2. OWASP Top 10 Checklist
+
+1. **Injection (NoSQL)** - Are Mongoose queries safe? No string concatenation in queries?
+2. **Broken Authentication** - Passwords hashed? Sessions secure? Passport configured correctly?
+3. **Sensitive Data Exposure** - Secrets in env vars? HTTPS enforced? Logs sanitized?
+4. **Broken Access Control** - Authorization on all routes? CORS configured?
+5. **Security Misconfiguration** - Helmet enabled? Debug mode off in production?
+6. **XSS** - Output escaped? Content-Security-Policy set?
+7. **Components with Vulnerabilities** - `pnpm audit` clean?
+8. **Insufficient Logging** - Security events logged?
+
+## Vulnerability Patterns
+
+### Hardcoded Secrets (CRITICAL)
+```typescript
+// ❌ CRITICAL
+const apiKey = "sk-xxxxx"
+
+// ✅ CORRECT
+const apiKey = process.env.API_KEY
+```
+
+### NoSQL Injection (CRITICAL)
+```typescript
+// ❌ CRITICAL: Unsafe query
+const user = await User.findOne({ email: req.body.email, password: req.body.password })
+
+// ✅ CORRECT: Use express-mongo-sanitize middleware + validate input
+```
+
+### XSS (HIGH)
+```typescript
+// ❌ HIGH: Direct HTML insertion
+element.innerHTML = userInput
+
+// ✅ CORRECT: Use textContent or sanitize
+element.textContent = userInput
+// OR use xss library
+import xss from 'xss'
+element.innerHTML = xss(userInput)
+```
+
+### SSRF (HIGH)
+```typescript
+// ❌ HIGH: User-controlled URL
+const response = await fetch(userProvidedUrl)
+
+// ✅ CORRECT: Validate URL against allowlist
+const allowedDomains = ['api.example.com']
+const url = new URL(userProvidedUrl)
+if (!allowedDomains.includes(url.hostname)) {
+  throw new Error('Invalid URL')
+}
+```
+
+### Authorization Check (CRITICAL)
+```typescript
+// ❌ CRITICAL: No authorization
+app.get('/api/page/:id', async (req, res) => {
+  const page = await Page.findById(req.params.id)
+  res.json(page)
+})
+
+// ✅ CORRECT: Check user access
+app.get('/api/page/:id', loginRequired, async (req, res) => {
+  const page = await Page.findById(req.params.id)
+  if (!page.isAccessibleBy(req.user)) {
+    return res.status(403).json({ error: 'Forbidden' })
+  }
+  res.json(page)
+})
+```
+
+## Security Report Format
+
+```markdown
+## Security Review Summary
+- **Critical Issues:** X
+- **High Issues:** Y
+- **Risk Level:** 🔴 HIGH / 🟡 MEDIUM / 🟢 LOW
+
+### Issues Found
+1. **[SEVERITY]** Description @ `file:line`
+   - Impact: ...
+   - Fix: ...
+```
+
+## When to Review
+
+**ALWAYS review when:**
+- New API endpoints added
+- Authentication/authorization changed
+- User input handling added
+- Database queries modified
+- File upload features added
+- Dependencies updated
+
+## Best Practices
+
+1. **Defense in Depth** - Multiple security layers
+2. **Least Privilege** - Minimum permissions
+3. **Fail Securely** - Errors don't expose data
+4. **Separation of Concerns** - Isolate security-critical code
+5. **Keep it Simple** - Complex code has more vulnerabilities
+6. **Don't Trust Input** - Validate everything
+7. **Update Regularly** - Keep dependencies current
+
+## Emergency Response
+
+If CRITICAL vulnerability found:
+1. Document the issue
+2. Provide secure code fix
+3. Check if vulnerability was exploited
+4. Rotate any exposed secrets

.claude/commands/kiro/spec-design.md

@@ -0,0 +1,179 @@
+---
+description: Create comprehensive technical design for a specification
+allowed-tools: Bash, Glob, Grep, LS, Read, Write, Edit, MultiEdit, Update, WebSearch, WebFetch
+argument-hint: <feature-name> [-y]
+---
+
+# Technical Design Generator
+
+<background_information>
+- **Mission**: Generate comprehensive technical design document that translates requirements (WHAT) into architectural design (HOW)
+- **Success Criteria**:
+  - All requirements mapped to technical components with clear interfaces
+  - Appropriate architecture discovery and research completed
+  - Design aligns with steering context and existing patterns
+  - Visual diagrams included for complex architectures
+</background_information>
+
+<instructions>
+## Core Task
+Generate technical design document for feature **$1** based on approved requirements.
+
+## Execution Steps
+
+### Step 1: Load Context
+
+**Read all necessary context**:
+- `.kiro/specs/$1/spec.json`, `requirements.md`, `design.md` (if exists)
+- **Entire `.kiro/steering/` directory** for complete project memory
+- `.kiro/settings/templates/specs/design.md` for document structure
+- `.kiro/settings/rules/design-principles.md` for design principles
+- `.kiro/settings/templates/specs/research.md` for discovery log structure
+
+**Validate requirements approval**:
+- If `-y` flag provided ($2 == "-y"): Auto-approve requirements in spec.json
+- Otherwise: Verify approval status (stop if unapproved, see Safety & Fallback)
+
+### Step 2: Discovery & Analysis
+
+**Critical: This phase ensures design is based on complete, accurate information.**
+
+1. **Classify Feature Type**:
+   - **New Feature** (greenfield) → Full discovery required
+   - **Extension** (existing system) → Integration-focused discovery
+   - **Simple Addition** (CRUD/UI) → Minimal or no discovery
+   - **Complex Integration** → Comprehensive analysis required
+
+2. **Execute Appropriate Discovery Process**:
+   
+   **For Complex/New Features**:
+   - Read and execute `.kiro/settings/rules/design-discovery-full.md`
+   - Conduct thorough research using WebSearch/WebFetch:
+     - Latest architectural patterns and best practices
+     - External dependency verification (APIs, libraries, versions, compatibility)
+     - Official documentation, migration guides, known issues
+     - Performance benchmarks and security considerations
+   
+   **For Extensions**:
+   - Read and execute `.kiro/settings/rules/design-discovery-light.md`
+   - Focus on integration points, existing patterns, compatibility
+   - Use Grep to analyze existing codebase patterns
+   
+   **For Simple Additions**:
+   - Skip formal discovery, quick pattern check only
+
+3. **Retain Discovery Findings for Step 3**:
+- External API contracts and constraints
+- Technology decisions with rationale
+- Existing patterns to follow or extend
+- Integration points and dependencies
+- Identified risks and mitigation strategies
+- Potential architecture patterns and boundary options (note details in `research.md`)
+- Parallelization considerations for future tasks (capture dependencies in `research.md`)
+
+4. **Persist Findings to Research Log**:
+- Create or update `.kiro/specs/$1/research.md` using the shared template
+- Summarize discovery scope and key findings (Summary section)
+- Record investigations in Research Log topics with sources and implications
+- Document architecture pattern evaluation, design decisions, and risks using the template sections
+- Use the language specified in spec.json when writing or updating `research.md`
+
+### Step 3: Generate Design Document
+
+1. **Load Design Template and Rules**:
+- Read `.kiro/settings/templates/specs/design.md` for structure
+- Read `.kiro/settings/rules/design-principles.md` for principles
+
+2. **Generate Design Document**:
+- **Follow specs/design.md template structure and generation instructions strictly**
+- **Integrate all discovery findings**: Use researched information (APIs, patterns, technologies) throughout component definitions, architecture decisions, and integration points
+- If existing design.md found in Step 1, use it as reference context (merge mode)
+- Apply design rules: Type Safety, Visual Communication, Formal Tone
+- Use language specified in spec.json
+- Ensure sections reflect updated headings ("Architecture Pattern & Boundary Map", "Technology Stack & Alignment", "Components & Interface Contracts") and reference supporting details from `research.md`
+
+3. **Update Metadata** in spec.json:
+- Set `phase: "design-generated"`
+- Set `approvals.design.generated: true, approved: false`
+- Set `approvals.requirements.approved: true`
+- Update `updated_at` timestamp
+
+## Critical Constraints
+ - **Type Safety**:
+   - Enforce strong typing aligned with the project's technology stack.
+   - For statically typed languages, define explicit types/interfaces and avoid unsafe casts.
+   - For TypeScript, never use `any`; prefer precise types and generics.
+   - For dynamically typed languages, provide type hints/annotations where available (e.g., Python type hints) and validate inputs at boundaries.
+   - Document public interfaces and contracts clearly to ensure cross-component type safety.
+- **Latest Information**: Use WebSearch/WebFetch for external dependencies and best practices
+- **Steering Alignment**: Respect existing architecture patterns from steering context
+- **Template Adherence**: Follow specs/design.md template structure and generation instructions strictly
+- **Design Focus**: Architecture and interfaces ONLY, no implementation code
+- **Requirements Traceability IDs**: Use numeric requirement IDs only (e.g. "1.1", "1.2", "3.1", "3.3") exactly as defined in requirements.md. Do not invent new IDs or use alphabetic labels.
+</instructions>
+
+## Tool Guidance
+- **Read first**: Load all context before taking action (specs, steering, templates, rules)
+- **Research when uncertain**: Use WebSearch/WebFetch for external dependencies, APIs, and latest best practices
+- **Analyze existing code**: Use Grep to find patterns and integration points in codebase
+- **Write last**: Generate design.md only after all research and analysis complete
+
+## Output Description
+
+**Command execution output** (separate from design.md content):
+
+Provide brief summary in the language specified in spec.json:
+
+1. **Status**: Confirm design document generated at `.kiro/specs/$1/design.md`
+2. **Discovery Type**: Which discovery process was executed (full/light/minimal)
+3. **Key Findings**: 2-3 critical insights from `research.md` that shaped the design
+4. **Next Action**: Approval workflow guidance (see Safety & Fallback)
+5. **Research Log**: Confirm `research.md` updated with latest decisions
+
+**Format**: Concise Markdown (under 200 words) - this is the command output, NOT the design document itself
+
+**Note**: The actual design document follows `.kiro/settings/templates/specs/design.md` structure.
+
+## Safety & Fallback
+
+### Error Scenarios
+
+**Requirements Not Approved**:
+- **Stop Execution**: Cannot proceed without approved requirements
+- **User Message**: "Requirements not yet approved. Approval required before design generation."
+- **Suggested Action**: "Run `/kiro:spec-design $1 -y` to auto-approve requirements and proceed"
+
+**Missing Requirements**:
+- **Stop Execution**: Requirements document must exist
+- **User Message**: "No requirements.md found at `.kiro/specs/$1/requirements.md`"
+- **Suggested Action**: "Run `/kiro:spec-requirements $1` to generate requirements first"
+
+**Template Missing**:
+- **User Message**: "Template file missing at `.kiro/settings/templates/specs/design.md`"
+- **Suggested Action**: "Check repository setup or restore template file"
+- **Fallback**: Use inline basic structure with warning
+
+**Steering Context Missing**:
+- **Warning**: "Steering directory empty or missing - design may not align with project standards"
+- **Proceed**: Continue with generation but note limitation in output
+
+**Discovery Complexity Unclear**:
+- **Default**: Use full discovery process (`.kiro/settings/rules/design-discovery-full.md`)
+- **Rationale**: Better to over-research than miss critical context
+- **Invalid Requirement IDs**:
+  - **Stop Execution**: If requirements.md is missing numeric IDs or uses non-numeric headings (for example, "Requirement A"), stop and instruct the user to fix requirements.md before continuing.
+
+### Next Phase: Task Generation
+
+**If Design Approved**:
+- Review generated design at `.kiro/specs/$1/design.md`
+- **Optional**: Run `/kiro:validate-design $1` for interactive quality review
+- Then `/kiro:spec-tasks $1 -y` to generate implementation tasks
+
+**If Modifications Needed**:
+- Provide feedback and re-run `/kiro:spec-design $1`
+- Existing design used as reference (merge mode)
+
+**Note**: Design approval is mandatory before proceeding to task generation.
+
+think hard

.claude/commands/kiro/spec-impl.md

@@ -0,0 +1,110 @@
+---
+description: Execute spec tasks using TDD methodology
+allowed-tools: Bash, Read, Write, Edit, MultiEdit, Grep, Glob, LS, WebFetch, WebSearch
+argument-hint: <feature-name> [task-numbers]
+---
+
+# Implementation Task Executor
+
+<background_information>
+- **Mission**: Execute implementation tasks using Test-Driven Development methodology based on approved specifications
+- **Success Criteria**:
+  - All tests written before implementation code
+  - Code passes all tests with no regressions
+  - Tasks marked as completed in tasks.md
+  - Implementation aligns with design and requirements
+</background_information>
+
+<instructions>
+## Core Task
+Execute implementation tasks for feature **$1** using Test-Driven Development.
+
+## Execution Steps
+
+### Step 1: Load Context
+
+**Read all necessary context**:
+- `.kiro/specs/$1/spec.json`, `requirements.md`, `design.md`, `tasks.md`
+- **Entire `.kiro/steering/` directory** for complete project memory
+
+**Validate approvals**:
+- Verify tasks are approved in spec.json (stop if not, see Safety & Fallback)
+
+### Step 2: Select Tasks
+
+**Determine which tasks to execute**:
+- If `$2` provided: Execute specified task numbers (e.g., "1.1" or "1,2,3")
+- Otherwise: Execute all pending tasks (unchecked `- [ ]` in tasks.md)
+
+### Step 3: Execute with TDD
+
+For each selected task, follow Kent Beck's TDD cycle:
+
+1. **RED - Write Failing Test**:
+   - Write test for the next small piece of functionality
+   - Test should fail (code doesn't exist yet)
+   - Use descriptive test names
+
+2. **GREEN - Write Minimal Code**:
+   - Implement simplest solution to make test pass
+   - Focus only on making THIS test pass
+   - Avoid over-engineering
+
+3. **REFACTOR - Clean Up**:
+   - Improve code structure and readability
+   - Remove duplication
+   - Apply design patterns where appropriate
+   - Ensure all tests still pass after refactoring
+
+4. **VERIFY - Validate Quality**:
+   - All tests pass (new and existing)
+   - No regressions in existing functionality
+   - Code coverage maintained or improved
+
+5. **MARK COMPLETE**:
+   - Update checkbox from `- [ ]` to `- [x]` in tasks.md
+
+## Critical Constraints
+- **TDD Mandatory**: Tests MUST be written before implementation code
+- **Task Scope**: Implement only what the specific task requires
+- **Test Coverage**: All new code must have tests
+- **No Regressions**: Existing tests must continue to pass
+- **Design Alignment**: Implementation must follow design.md specifications
+</instructions>
+
+## Tool Guidance
+- **Read first**: Load all context before implementation
+- **Test first**: Write tests before code
+- Use **WebSearch/WebFetch** for library documentation when needed
+
+## Output Description
+
+Provide brief summary in the language specified in spec.json:
+
+1. **Tasks Executed**: Task numbers and test results
+2. **Status**: Completed tasks marked in tasks.md, remaining tasks count
+
+**Format**: Concise (under 150 words)
+
+## Safety & Fallback
+
+### Error Scenarios
+
+**Tasks Not Approved or Missing Spec Files**:
+- **Stop Execution**: All spec files must exist and tasks must be approved
+- **Suggested Action**: "Complete previous phases: `/kiro:spec-requirements`, `/kiro:spec-design`, `/kiro:spec-tasks`"
+
+**Test Failures**:
+- **Stop Implementation**: Fix failing tests before continuing
+- **Action**: Debug and fix, then re-run
+
+### Task Execution
+
+**Execute specific task(s)**:
+- `/kiro:spec-impl $1 1.1` - Single task
+- `/kiro:spec-impl $1 1,2,3` - Multiple tasks
+
+**Execute all pending**:
+- `/kiro:spec-impl $1` - All unchecked tasks
+
+think

.claude/commands/kiro/spec-init.md

@@ -0,0 +1,65 @@
+---
+description: Initialize a new specification with detailed project description
+allowed-tools: Bash, Read, Write, Glob
+argument-hint: <project-description>
+---
+
+# Spec Initialization
+
+<background_information>
+- **Mission**: Initialize the first phase of spec-driven development by creating directory structure and metadata for a new specification
+- **Success Criteria**:
+  - Generate appropriate feature name from project description
+  - Create unique spec structure without conflicts
+  - Provide clear path to next phase (requirements generation)
+</background_information>
+
+<instructions>
+## Core Task
+Generate a unique feature name from the project description ($ARGUMENTS) and initialize the specification structure.
+
+## Execution Steps
+1. **Check Uniqueness**: Verify `.kiro/specs/` for naming conflicts (append number suffix if needed)
+2. **Create Directory**: `.kiro/specs/[feature-name]/`
+3. **Initialize Files Using Templates**:
+   - Read `.kiro/settings/templates/specs/init.json`
+   - Read `.kiro/settings/templates/specs/requirements-init.md`
+   - Replace placeholders:
+     - `{{FEATURE_NAME}}` → generated feature name
+     - `{{TIMESTAMP}}` → current ISO 8601 timestamp
+     - `{{PROJECT_DESCRIPTION}}` → $ARGUMENTS
+   - Write `spec.json` and `requirements.md` to spec directory
+
+## Important Constraints
+- DO NOT generate requirements/design/tasks at this stage
+- Follow stage-by-stage development principles
+- Maintain strict phase separation
+- Only initialization is performed in this phase
+</instructions>
+
+## Tool Guidance
+- Use **Glob** to check existing spec directories for name uniqueness
+- Use **Read** to fetch templates: `init.json` and `requirements-init.md`
+- Use **Write** to create spec.json and requirements.md after placeholder replacement
+- Perform validation before any file write operation
+
+## Output Description
+Provide output in the language specified in `spec.json` with the following structure:
+
+1. **Generated Feature Name**: `feature-name` format with 1-2 sentence rationale
+2. **Project Summary**: Brief summary (1 sentence)
+3. **Created Files**: Bullet list with full paths
+4. **Next Step**: Command block showing `/kiro:spec-requirements <feature-name>`
+5. **Notes**: Explain why only initialization was performed (2-3 sentences on phase separation)
+
+**Format Requirements**:
+- Use Markdown headings (##, ###)
+- Wrap commands in code blocks
+- Keep total output concise (under 250 words)
+- Use clear, professional language per `spec.json.language`
+
+## Safety & Fallback
+- **Ambiguous Feature Name**: If feature name generation is unclear, propose 2-3 options and ask user to select
+- **Template Missing**: If template files don't exist in `.kiro/settings/templates/specs/`, report error with specific missing file path and suggest checking repository setup
+- **Directory Conflict**: If feature name already exists, append numeric suffix (e.g., `feature-name-2`) and notify user of automatic conflict resolution
+- **Write Failure**: Report error with specific path and suggest checking permissions or disk space

.claude/commands/kiro/spec-requirements.md

@@ -0,0 +1,98 @@
+---
+description: Generate comprehensive requirements for a specification
+allowed-tools: Bash, Glob, Grep, LS, Read, Write, Edit, MultiEdit, Update, WebSearch, WebFetch
+argument-hint: <feature-name>
+---
+
+# Requirements Generation
+
+<background_information>
+- **Mission**: Generate comprehensive, testable requirements in EARS format based on the project description from spec initialization
+- **Success Criteria**:
+  - Create complete requirements document aligned with steering context
+  - Follow the project's EARS patterns and constraints for all acceptance criteria
+  - Focus on core functionality without implementation details
+  - Update metadata to track generation status
+</background_information>
+
+<instructions>
+## Core Task
+Generate complete requirements for feature **$1** based on the project description in requirements.md.
+
+## Execution Steps
+
+1. **Load Context**:
+   - Read `.kiro/specs/$1/spec.json` for language and metadata
+   - Read `.kiro/specs/$1/requirements.md` for project description
+   - **Load ALL steering context**: Read entire `.kiro/steering/` directory including:
+     - Default files: `structure.md`, `tech.md`, `product.md`
+     - All custom steering files (regardless of mode settings)
+     - This provides complete project memory and context
+
+2. **Read Guidelines**:
+   - Read `.kiro/settings/rules/ears-format.md` for EARS syntax rules
+   - Read `.kiro/settings/templates/specs/requirements.md` for document structure
+
+3. **Generate Requirements**:
+   - Create initial requirements based on project description
+   - Group related functionality into logical requirement areas
+   - Apply EARS format to all acceptance criteria
+   - Use language specified in spec.json
+
+4. **Update Metadata**:
+   - Set `phase: "requirements-generated"`
+   - Set `approvals.requirements.generated: true`
+   - Update `updated_at` timestamp
+
+## Important Constraints
+- Focus on WHAT, not HOW (no implementation details)
+- Requirements must be testable and verifiable
+- Choose appropriate subject for EARS statements (system/service name for software)
+- Generate initial version first, then iterate with user feedback (no sequential questions upfront)
+- Requirement headings in requirements.md MUST include a leading numeric ID only (for example: "Requirement 1", "1.", "2 Feature ..."); do not use alphabetic IDs like "Requirement A".
+</instructions>
+
+## Tool Guidance
+- **Read first**: Load all context (spec, steering, rules, templates) before generation
+- **Write last**: Update requirements.md only after complete generation
+- Use **WebSearch/WebFetch** only if external domain knowledge needed
+
+## Output Description
+Provide output in the language specified in spec.json with:
+
+1. **Generated Requirements Summary**: Brief overview of major requirement areas (3-5 bullets)
+2. **Document Status**: Confirm requirements.md updated and spec.json metadata updated
+3. **Next Steps**: Guide user on how to proceed (approve and continue, or modify)
+
+**Format Requirements**:
+- Use Markdown headings for clarity
+- Include file paths in code blocks
+- Keep summary concise (under 300 words)
+
+## Safety & Fallback
+
+### Error Scenarios
+- **Missing Project Description**: If requirements.md lacks project description, ask user for feature details
+- **Ambiguous Requirements**: Propose initial version and iterate with user rather than asking many upfront questions
+- **Template Missing**: If template files don't exist, use inline fallback structure with warning
+- **Language Undefined**: Default to English (`en`) if spec.json doesn't specify language
+- **Incomplete Requirements**: After generation, explicitly ask user if requirements cover all expected functionality
+- **Steering Directory Empty**: Warn user that project context is missing and may affect requirement quality
+- **Non-numeric Requirement Headings**: If existing headings do not include a leading numeric ID (for example, they use "Requirement A"), normalize them to numeric IDs and keep that mapping consistent (never mix numeric and alphabetic labels).
+
+### Next Phase: Design Generation
+
+**If Requirements Approved**:
+- Review generated requirements at `.kiro/specs/$1/requirements.md`
+- **Optional Gap Analysis** (for existing codebases):
+  - Run `/kiro:validate-gap $1` to analyze implementation gap with current code
+  - Identifies existing components, integration points, and implementation strategy
+  - Recommended for brownfield projects; skip for greenfield
+- Then `/kiro:spec-design $1 -y` to proceed to design phase
+
+**If Modifications Needed**:
+- Provide feedback and re-run `/kiro:spec-requirements $1`
+
+**Note**: Approval is mandatory before proceeding to design phase.
+
+think

.claude/commands/kiro/spec-status.md

@@ -0,0 +1,87 @@
+---
+description: Show specification status and progress
+allowed-tools: Bash, Read, Glob, Write, Edit, MultiEdit, Update
+argument-hint: <feature-name>
+---
+
+# Specification Status
+
+<background_information>
+- **Mission**: Display comprehensive status and progress for a specification
+- **Success Criteria**:
+  - Show current phase and completion status
+  - Identify next actions and blockers
+  - Provide clear visibility into progress
+</background_information>
+
+<instructions>
+## Core Task
+Generate status report for feature **$1** showing progress across all phases.
+
+## Execution Steps
+
+### Step 1: Load Spec Context
+- Read `.kiro/specs/$1/spec.json` for metadata and phase status
+- Read existing files: `requirements.md`, `design.md`, `tasks.md` (if they exist)
+- Check `.kiro/specs/$1/` directory for available files
+
+### Step 2: Analyze Status
+
+**Parse each phase**:
+- **Requirements**: Count requirements and acceptance criteria
+- **Design**: Check for architecture, components, diagrams
+- **Tasks**: Count completed vs total tasks (parse `- [x]` vs `- [ ]`)
+- **Approvals**: Check approval status in spec.json
+
+### Step 3: Generate Report
+
+Create report in the language specified in spec.json covering:
+1. **Current Phase & Progress**: Where the spec is in the workflow
+2. **Completion Status**: Percentage complete for each phase
+3. **Task Breakdown**: If tasks exist, show completed/remaining counts
+4. **Next Actions**: What needs to be done next
+5. **Blockers**: Any issues preventing progress
+
+## Critical Constraints
+- Use language from spec.json
+- Calculate accurate completion percentages
+- Identify specific next action commands
+</instructions>
+
+## Tool Guidance
+- **Read**: Load spec.json first, then other spec files as needed
+- **Parse carefully**: Extract completion data from tasks.md checkboxes
+- Use **Glob** to check which spec files exist
+
+## Output Description
+
+Provide status report in the language specified in spec.json:
+
+**Report Structure**:
+1. **Feature Overview**: Name, phase, last updated
+2. **Phase Status**: Requirements, Design, Tasks with completion %
+3. **Task Progress**: If tasks exist, show X/Y completed
+4. **Next Action**: Specific command to run next
+5. **Issues**: Any blockers or missing elements
+
+**Format**: Clear, scannable format with emojis (✅/⏳/❌) for status
+
+## Safety & Fallback
+
+### Error Scenarios
+
+**Spec Not Found**:
+- **Message**: "No spec found for `$1`. Check available specs in `.kiro/specs/`"
+- **Action**: List available spec directories
+
+**Incomplete Spec**:
+- **Warning**: Identify which files are missing
+- **Suggested Action**: Point to next phase command
+
+### List All Specs
+
+To see all available specs:
+- Run with no argument or use wildcard
+- Shows all specs in `.kiro/specs/` with their status
+
+think

.claude/commands/kiro/spec-tasks.md

@@ -0,0 +1,138 @@
+---
+description: Generate implementation tasks for a specification
+allowed-tools: Read, Write, Edit, MultiEdit, Glob, Grep
+argument-hint: <feature-name> [-y] [--sequential]
+---
+
+# Implementation Tasks Generator
+
+<background_information>
+- **Mission**: Generate detailed, actionable implementation tasks that translate technical design into executable work items
+- **Success Criteria**:
+  - All requirements mapped to specific tasks
+  - Tasks properly sized (1-3 hours each)
+  - Clear task progression with proper hierarchy
+  - Natural language descriptions focused on capabilities
+</background_information>
+
+<instructions>
+## Core Task
+Generate implementation tasks for feature **$1** based on approved requirements and design.
+
+## Execution Steps
+
+### Step 1: Load Context
+
+**Read all necessary context**:
+- `.kiro/specs/$1/spec.json`, `requirements.md`, `design.md`
+- `.kiro/specs/$1/tasks.md` (if exists, for merge mode)
+- **Entire `.kiro/steering/` directory** for complete project memory
+
+**Validate approvals**:
+- If `-y` flag provided ($2 == "-y"): Auto-approve requirements and design in spec.json
+- Otherwise: Verify both approved (stop if not, see Safety & Fallback)
+- Determine sequential mode based on presence of `--sequential`
+
+### Step 2: Generate Implementation Tasks
+
+**Load generation rules and template**:
+- Read `.kiro/settings/rules/tasks-generation.md` for principles
+- If `sequential` is **false**: Read `.kiro/settings/rules/tasks-parallel-analysis.md` for parallel judgement criteria
+- Read `.kiro/settings/templates/specs/tasks.md` for format (supports `(P)` markers)
+
+**Generate task list following all rules**:
+- Use language specified in spec.json
+- Map all requirements to tasks
+- When documenting requirement coverage, list numeric requirement IDs only (comma-separated) without descriptive suffixes, parentheses, translations, or free-form labels
+- Ensure all design components included
+- Verify task progression is logical and incremental
+- Collapse single-subtask structures by promoting them to major tasks and avoid duplicating details on container-only major tasks (use template patterns accordingly)
+- Apply `(P)` markers to tasks that satisfy parallel criteria (omit markers in sequential mode)
+- Mark optional test coverage subtasks with `- [ ]*` only when they strictly cover acceptance criteria already satisfied by core implementation and can be deferred post-MVP
+- If existing tasks.md found, merge with new content
+
+### Step 3: Finalize
+
+**Write and update**:
+- Create/update `.kiro/specs/$1/tasks.md`
+- Update spec.json metadata:
+  - Set `phase: "tasks-generated"`
+  - Set `approvals.tasks.generated: true, approved: false`
+  - Set `approvals.requirements.approved: true`
+  - Set `approvals.design.approved: true`
+  - Update `updated_at` timestamp
+
+## Critical Constraints
+- **Follow rules strictly**: All principles in tasks-generation.md are mandatory
+- **Natural Language**: Describe what to do, not code structure details
+- **Complete Coverage**: ALL requirements must map to tasks
+- **Maximum 2 Levels**: Major tasks and sub-tasks only (no deeper nesting)
+- **Sequential Numbering**: Major tasks increment (1, 2, 3...), never repeat
+- **Task Integration**: Every task must connect to the system (no orphaned work)
+</instructions>
+
+## Tool Guidance
+- **Read first**: Load all context, rules, and templates before generation
+- **Write last**: Generate tasks.md only after complete analysis and verification
+
+## Output Description
+
+Provide brief summary in the language specified in spec.json:
+
+1. **Status**: Confirm tasks generated at `.kiro/specs/$1/tasks.md`
+2. **Task Summary**: 
+   - Total: X major tasks, Y sub-tasks
+   - All Z requirements covered
+   - Average task size: 1-3 hours per sub-task
+3. **Quality Validation**:
+   - ✅ All requirements mapped to tasks
+   - ✅ Task dependencies verified
+   - ✅ Testing tasks included
+4. **Next Action**: Review tasks and proceed when ready
+
+**Format**: Concise (under 200 words)
+
+## Safety & Fallback
+
+### Error Scenarios
+
+**Requirements or Design Not Approved**:
+- **Stop Execution**: Cannot proceed without approved requirements and design
+- **User Message**: "Requirements and design must be approved before task generation"
+- **Suggested Action**: "Run `/kiro:spec-tasks $1 -y` to auto-approve both and proceed"
+
+**Missing Requirements or Design**:
+- **Stop Execution**: Both documents must exist
+- **User Message**: "Missing requirements.md or design.md at `.kiro/specs/$1/`"
+- **Suggested Action**: "Complete requirements and design phases first"
+
+**Incomplete Requirements Coverage**:
+- **Warning**: "Not all requirements mapped to tasks. Review coverage."
+- **User Action Required**: Confirm intentional gaps or regenerate tasks
+
+**Template/Rules Missing**:
+- **User Message**: "Template or rules files missing in `.kiro/settings/`"
+- **Fallback**: Use inline basic structure with warning
+- **Suggested Action**: "Check repository setup or restore template files"
+- **Missing Numeric Requirement IDs**:
+  - **Stop Execution**: All requirements in requirements.md MUST have numeric IDs. If any requirement lacks a numeric ID, stop and request that requirements.md be fixed before generating tasks.
+
+### Next Phase: Implementation
+
+**Before Starting Implementation**:
+- **IMPORTANT**: Clear conversation history and free up context before running `/kiro:spec-impl`
+- This applies when starting first task OR switching between tasks
+- Fresh context ensures clean state and proper task focus
+
+**If Tasks Approved**:
+- Execute specific task: `/kiro:spec-impl $1 1.1` (recommended: clear context between each task)
+- Execute multiple tasks: `/kiro:spec-impl $1 1.1,1.2` (use cautiously, clear context between tasks)
+- Without arguments: `/kiro:spec-impl $1` (executes all pending tasks - NOT recommended due to context bloat)
+
+**If Modifications Needed**:
+- Provide feedback and re-run `/kiro:spec-tasks $1`
+- Existing tasks used as reference (merge mode)
+
+**Note**: The implementation phase will guide you through executing tasks with appropriate context and validation.
+
+think

.claude/commands/kiro/steering-custom.md

@@ -0,0 +1,127 @@
+---
+description: Create custom steering documents for specialized project contexts
+allowed-tools: Bash, Read, Write, Edit, MultiEdit, Glob, Grep, LS
+---
+
+# Kiro Custom Steering Creation
+
+<background_information>
+**Role**: Create specialized steering documents beyond core files (product, tech, structure).
+
+**Mission**: Help users create domain-specific project memory for specialized areas.
+
+**Success Criteria**:
+- Custom steering captures specialized patterns
+- Follows same granularity principles as core steering
+- Provides clear value for specific domain
+</background_information>
+
+<instructions>
+## Workflow
+
+1. **Ask user** for custom steering needs:
+   - Domain/topic (e.g., "API standards", "testing approach")
+   - Specific requirements or patterns to document
+
+2. **Check if template exists**:
+   - Load from `.kiro/settings/templates/steering-custom/{name}.md` if available
+   - Use as starting point, customize based on project
+
+3. **Analyze codebase** (JIT) for relevant patterns:
+   - **Glob** for related files
+   - **Read** for existing implementations
+   - **Grep** for specific patterns
+
+4. **Generate custom steering**:
+   - Follow template structure if available
+   - Apply principles from `.kiro/settings/rules/steering-principles.md`
+   - Focus on patterns, not exhaustive lists
+   - Keep to 100-200 lines (2-3 minute read)
+
+5. **Create file** in `.kiro/steering/{name}.md`
+
+## Available Templates
+
+Templates available in `.kiro/settings/templates/steering-custom/`:
+
+1. **api-standards.md** - REST/GraphQL conventions, error handling
+2. **testing.md** - Test organization, mocking, coverage
+3. **security.md** - Auth patterns, input validation, secrets
+4. **database.md** - Schema design, migrations, query patterns
+5. **error-handling.md** - Error types, logging, retry strategies
+6. **authentication.md** - Auth flows, permissions, session management
+7. **deployment.md** - CI/CD, environments, rollback procedures
+
+Load template when needed, customize for project.
+
+## Steering Principles
+
+From `.kiro/settings/rules/steering-principles.md`:
+
+- **Patterns over lists**: Document patterns, not every file/component
+- **Single domain**: One topic per file
+- **Concrete examples**: Show patterns with code
+- **Maintainable size**: 100-200 lines typical
+- **Security first**: Never include secrets or sensitive data
+
+</instructions>
+
+## Tool guidance
+
+- **Read**: Load template, analyze existing code
+- **Glob**: Find related files for pattern analysis
+- **Grep**: Search for specific patterns
+- **LS**: Understand relevant structure
+
+**JIT Strategy**: Load template only when creating that type of steering.
+
+## Output description
+
+Chat summary with file location (file created directly).
+
+```
+✅ Custom Steering Created
+
+## Created:
+- .kiro/steering/api-standards.md
+
+## Based On:
+- Template: api-standards.md
+- Analyzed: src/api/ directory patterns
+- Extracted: REST conventions, error format
+
+## Content:
+- Endpoint naming patterns
+- Request/response format
+- Error handling conventions
+- Authentication approach
+
+Review and customize as needed.
+```
+
+## Examples
+
+### Success: API Standards
+**Input**: "Create API standards steering"  
+**Action**: Load template, analyze src/api/, extract patterns  
+**Output**: api-standards.md with project-specific REST conventions
+
+### Success: Testing Strategy
+**Input**: "Document our testing approach"  
+**Action**: Load template, analyze test files, extract patterns  
+**Output**: testing.md with test organization and mocking strategies
+
+## Safety & Fallback
+
+- **No template**: Generate from scratch based on domain knowledge
+- **Security**: Never include secrets (load principles)
+- **Validation**: Ensure doesn't duplicate core steering content
+
+## Notes
+
+- Templates are starting points, customize for project
+- Follow same granularity principles as core steering
+- All steering files loaded as project memory
+- Custom files equally important as core files
+- Avoid documenting agent-specific tooling directories (e.g. `.cursor/`, `.gemini/`, `.claude/`)
+- Light references to `.kiro/specs/` and `.kiro/steering/` are acceptable; avoid other `.kiro/` directories

.claude/commands/kiro/steering.md

@@ -0,0 +1,143 @@
+---
+description: Manage .kiro/steering/ as persistent project knowledge
+allowed-tools: Bash, Read, Write, Edit, MultiEdit, Glob, Grep, LS
+---
+
+# Kiro Steering Management
+
+<background_information>
+**Role**: Maintain `.kiro/steering/` as persistent project memory.
+
+**Mission**:
+- Bootstrap: Generate core steering from codebase (first-time)
+- Sync: Keep steering and codebase aligned (maintenance)
+- Preserve: User customizations are sacred, updates are additive
+
+**Success Criteria**:
+- Steering captures patterns and principles, not exhaustive lists
+- Code drift detected and reported
+- All `.kiro/steering/*.md` treated equally (core + custom)
+</background_information>
+
+<instructions>
+## Scenario Detection
+
+Check `.kiro/steering/` status:
+
+**Bootstrap Mode**: Empty OR missing core files (product.md, tech.md, structure.md)  
+**Sync Mode**: All core files exist
+
+---
+
+## Bootstrap Flow
+
+1. Load templates from `.kiro/settings/templates/steering/`
+2. Analyze codebase (JIT):
+   - `glob_file_search` for source files
+   - `read_file` for README, package.json, etc.
+   - `grep` for patterns
+3. Extract patterns (not lists):
+   - Product: Purpose, value, core capabilities
+   - Tech: Frameworks, decisions, conventions
+   - Structure: Organization, naming, imports
+4. Generate steering files (follow templates)
+5. Load principles from `.kiro/settings/rules/steering-principles.md`
+6. Present summary for review
+
+**Focus**: Patterns that guide decisions, not catalogs of files/dependencies.
+
+---
+
+## Sync Flow
+
+1. Load all existing steering (`.kiro/steering/*.md`)
+2. Analyze codebase for changes (JIT)
+3. Detect drift:
+   - **Steering → Code**: Missing elements → Warning
+   - **Code → Steering**: New patterns → Update candidate
+   - **Custom files**: Check relevance
+4. Propose updates (additive, preserve user content)
+5. Report: Updates, warnings, recommendations
+
+**Update Philosophy**: Add, don't replace. Preserve user sections.
+
+---
+
+## Granularity Principle
+
+From `.kiro/settings/rules/steering-principles.md`:
+
+> "If new code follows existing patterns, steering shouldn't need updating."
+
+Document patterns and principles, not exhaustive lists.
+
+**Bad**: List every file in directory tree  
+**Good**: Describe organization pattern with examples
+
+</instructions>
+
+## Tool guidance
+
+- `glob_file_search`: Find source/config files
+- `read_file`: Read steering, docs, configs
+- `grep`: Search patterns
+- `list_dir`: Analyze structure
+
+**JIT Strategy**: Fetch when needed, not upfront.
+
+## Output description
+
+Chat summary only (files updated directly).
+
+### Bootstrap:
+```
+✅ Steering Created
+
+## Generated:
+- product.md: [Brief description]
+- tech.md: [Key stack]
+- structure.md: [Organization]
+
+Review and approve as Source of Truth.
+```
+
+### Sync:
+```
+✅ Steering Updated
+
+## Changes:
+- tech.md: React 18 → 19
+- structure.md: Added API pattern
+
+## Code Drift:
+- Components not following import conventions
+
+## Recommendations:
+- Consider api-standards.md
+```
+
+## Examples
+
+### Bootstrap
+**Input**: Empty steering, React TypeScript project  
+**Output**: 3 files with patterns - "Feature-first", "TypeScript strict", "React 19"
+
+### Sync
+**Input**: Existing steering, new `/api` directory  
+**Output**: Updated structure.md, flagged non-compliant files, suggested api-standards.md
+
+## Safety & Fallback
+
+- **Security**: Never include keys, passwords, secrets (see principles)
+- **Uncertainty**: Report both states, ask user
+- **Preservation**: Add rather than replace when in doubt
+
+## Notes
+
+- All `.kiro/steering/*.md` loaded as project memory
+- Templates and principles are external for customization
+- Focus on patterns, not catalogs
+- "Golden Rule": New code following patterns shouldn't require steering updates
+- Avoid documenting agent-specific tooling directories (e.g. `.cursor/`, `.gemini/`, `.claude/`)
+- `.kiro/settings/` content should NOT be documented in steering files (settings are metadata, not project knowledge)
+- Light references to `.kiro/specs/` and `.kiro/steering/` are acceptable; avoid other `.kiro/` directories

.claude/commands/kiro/validate-design.md

@@ -0,0 +1,92 @@
+---
+description: Interactive technical design quality review and validation
+allowed-tools: Read, Glob, Grep
+argument-hint: <feature-name>
+---
+
+# Technical Design Validation
+
+<background_information>
+- **Mission**: Conduct interactive quality review of technical design to ensure readiness for implementation
+- **Success Criteria**:
+  - Critical issues identified (maximum 3 most important concerns)
+  - Balanced assessment with strengths recognized
+  - Clear GO/NO-GO decision with rationale
+  - Actionable feedback for improvements if needed
+</background_information>
+
+<instructions>
+## Core Task
+Interactive design quality review for feature **$1** based on approved requirements and design document.
+
+## Execution Steps
+
+1. **Load Context**:
+   - Read `.kiro/specs/$1/spec.json` for language and metadata
+   - Read `.kiro/specs/$1/requirements.md` for requirements
+   - Read `.kiro/specs/$1/design.md` for design document
+   - **Load ALL steering context**: Read entire `.kiro/steering/` directory including:
+     - Default files: `structure.md`, `tech.md`, `product.md`
+     - All custom steering files (regardless of mode settings)
+     - This provides complete project memory and context
+
+2. **Read Review Guidelines**:
+   - Read `.kiro/settings/rules/design-review.md` for review criteria and process
+
+3. **Execute Design Review**:
+   - Follow design-review.md process: Analysis → Critical Issues → Strengths → GO/NO-GO
+   - Limit to 3 most important concerns
+   - Engage interactively with user
+   - Use language specified in spec.json for output
+
+4. **Provide Decision and Next Steps**:
+   - Clear GO/NO-GO decision with rationale
+   - Guide user on proceeding based on decision
+
+## Important Constraints
+- **Quality assurance, not perfection seeking**: Accept acceptable risk
+- **Critical focus only**: Maximum 3 issues, only those significantly impacting success
+- **Interactive approach**: Engage in dialogue, not one-way evaluation
+- **Balanced assessment**: Recognize both strengths and weaknesses
+- **Actionable feedback**: All suggestions must be implementable
+</instructions>
+
+## Tool Guidance
+- **Read first**: Load all context (spec, steering, rules) before review
+- **Grep if needed**: Search codebase for pattern validation or integration checks
+- **Interactive**: Engage with user throughout the review process
+
+## Output Description
+Provide output in the language specified in spec.json with:
+
+1. **Review Summary**: Brief overview (2-3 sentences) of design quality and readiness
+2. **Critical Issues**: Maximum 3, following design-review.md format
+3. **Design Strengths**: 1-2 positive aspects
+4. **Final Assessment**: GO/NO-GO decision with rationale and next steps
+
+**Format Requirements**:
+- Use Markdown headings for clarity
+- Follow design-review.md output format
+- Keep summary concise
+
+## Safety & Fallback
+
+### Error Scenarios
+- **Missing Design**: If design.md doesn't exist, stop with message: "Run `/kiro:spec-design $1` first to generate design document"
+- **Design Not Generated**: If design phase not marked as generated in spec.json, warn but proceed with review
+- **Empty Steering Directory**: Warn user that project context is missing and may affect review quality
+- **Language Undefined**: Default to English (`en`) if spec.json doesn't specify language
+
+### Next Phase: Task Generation
+
+**If Design Passes Validation (GO Decision)**:
+- Review feedback and apply changes if needed
+- Run `/kiro:spec-tasks $1` to generate implementation tasks
+- Or `/kiro:spec-tasks $1 -y` to auto-approve and proceed directly
+
+**If Design Needs Revision (NO-GO Decision)**:
+- Address critical issues identified
+- Re-run `/kiro:spec-design $1` with improvements
+- Re-validate with `/kiro:validate-design $1`
+
+**Note**: Design validation is recommended but optional. Quality review helps catch issues early.

.claude/commands/kiro/validate-gap.md

@@ -0,0 +1,88 @@
+---
+description: Analyze implementation gap between requirements and existing codebase
+allowed-tools: Bash, Glob, Grep, Read, Write, Edit, MultiEdit, WebSearch, WebFetch
+argument-hint: <feature-name>
+---
+
+# Implementation Gap Validation
+
+<background_information>
+- **Mission**: Analyze the gap between requirements and existing codebase to inform implementation strategy
+- **Success Criteria**:
+  - Comprehensive understanding of existing codebase patterns and components
+  - Clear identification of missing capabilities and integration challenges
+  - Multiple viable implementation approaches evaluated
+  - Technical research needs identified for design phase
+</background_information>
+
+<instructions>
+## Core Task
+Analyze implementation gap for feature **$1** based on approved requirements and existing codebase.
+
+## Execution Steps
+
+1. **Load Context**:
+   - Read `.kiro/specs/$1/spec.json` for language and metadata
+   - Read `.kiro/specs/$1/requirements.md` for requirements
+   - **Load ALL steering context**: Read entire `.kiro/steering/` directory including:
+     - Default files: `structure.md`, `tech.md`, `product.md`
+     - All custom steering files (regardless of mode settings)
+     - This provides complete project memory and context
+
+2. **Read Analysis Guidelines**:
+   - Read `.kiro/settings/rules/gap-analysis.md` for comprehensive analysis framework
+
+3. **Execute Gap Analysis**:
+   - Follow gap-analysis.md framework for thorough investigation
+   - Analyze existing codebase using Grep and Read tools
+   - Use WebSearch/WebFetch for external dependency research if needed
+   - Evaluate multiple implementation approaches (extend/new/hybrid)
+   - Use language specified in spec.json for output
+
+4. **Generate Analysis Document**:
+   - Create comprehensive gap analysis following the output guidelines in gap-analysis.md
+   - Present multiple viable options with trade-offs
+   - Flag areas requiring further research
+
+## Important Constraints
+- **Information over Decisions**: Provide analysis and options, not final implementation choices
+- **Multiple Options**: Present viable alternatives when applicable
+- **Thorough Investigation**: Use tools to deeply understand existing codebase
+- **Explicit Gaps**: Clearly flag areas needing research or investigation
+</instructions>
+
+## Tool Guidance
+- **Read first**: Load all context (spec, steering, rules) before analysis
+- **Grep extensively**: Search codebase for patterns, conventions, and integration points
+- **WebSearch/WebFetch**: Research external dependencies and best practices when needed
+- **Write last**: Generate analysis only after complete investigation
+
+## Output Description
+Provide output in the language specified in spec.json with:
+
+1. **Analysis Summary**: Brief overview (3-5 bullets) of scope, challenges, and recommendations
+2. **Document Status**: Confirm analysis approach used
+3. **Next Steps**: Guide user on proceeding to design phase
+
+**Format Requirements**:
+- Use Markdown headings for clarity
+- Keep summary concise (under 300 words)
+- Detailed analysis follows gap-analysis.md output guidelines
+
+## Safety & Fallback
+
+### Error Scenarios
+- **Missing Requirements**: If requirements.md doesn't exist, stop with message: "Run `/kiro:spec-requirements $1` first to generate requirements"
+- **Requirements Not Approved**: If requirements not approved, warn user but proceed (gap analysis can inform requirement revisions)
+- **Empty Steering Directory**: Warn user that project context is missing and may affect analysis quality
+- **Complex Integration Unclear**: Flag for comprehensive research in design phase rather than blocking
+- **Language Undefined**: Default to English (`en`) if spec.json doesn't specify language
+
+### Next Phase: Design Generation
+
+**If Gap Analysis Complete**:
+- Review gap analysis insights
+- Run `/kiro:spec-design $1` to create technical design document
+- Or `/kiro:spec-design $1 -y` to auto-approve requirements and proceed directly
+
+**Note**: Gap analysis is optional but recommended for brownfield projects to inform design decisions.

.claude/commands/kiro/validate-impl.md

@@ -0,0 +1,138 @@
+---
+description: Validate implementation against requirements, design, and tasks
+allowed-tools: Bash, Glob, Grep, Read, LS
+argument-hint: [feature-name] [task-numbers]
+---
+
+# Implementation Validation
+
+<background_information>
+- **Mission**: Verify that implementation aligns with approved requirements, design, and tasks
+- **Success Criteria**:
+  - All specified tasks marked as completed
+  - Tests exist and pass for implemented functionality
+  - Requirements traceability confirmed (EARS requirements covered)
+  - Design structure reflected in implementation
+  - No regressions in existing functionality
+</background_information>
+
+<instructions>
+## Core Task
+Validate implementation for feature(s) and task(s) based on approved specifications.
+
+## Execution Steps
+
+### 1. Detect Validation Target
+
+**If no arguments provided** (`$1` empty):
+- Parse conversation history for `/kiro:spec-impl <feature> [tasks]` commands
+- Extract feature names and task numbers from each execution
+- Aggregate all implemented tasks by feature
+- Report detected implementations (e.g., "user-auth: 1.1, 1.2, 1.3")
+- If no history found, scan `.kiro/specs/` for features with completed tasks `[x]`
+
+**If feature provided** (`$1` present, `$2` empty):
+- Use specified feature
+- Detect all completed tasks `[x]` in `.kiro/specs/$1/tasks.md`
+
+**If both feature and tasks provided** (`$1` and `$2` present):
+- Validate specified feature and tasks only (e.g., `user-auth 1.1,1.2`)
+
+### 2. Load Context
+
+For each detected feature:
+- Read `.kiro/specs/<feature>/spec.json` for metadata
+- Read `.kiro/specs/<feature>/requirements.md` for requirements
+- Read `.kiro/specs/<feature>/design.md` for design structure
+- Read `.kiro/specs/<feature>/tasks.md` for task list
+- **Load ALL steering context**: Read entire `.kiro/steering/` directory including:
+  - Default files: `structure.md`, `tech.md`, `product.md`
+  - All custom steering files (regardless of mode settings)
+
+### 3. Execute Validation
+
+For each task, verify:
+
+#### Task Completion Check
+- Checkbox is `[x]` in tasks.md
+- If not completed, flag as "Task not marked complete"
+
+#### Test Coverage Check
+- Tests exist for task-related functionality
+- Tests pass (no failures or errors)
+- Use Bash to run test commands (e.g., `npm test`, `pytest`)
+- If tests fail or don't exist, flag as "Test coverage issue"
+
+#### Requirements Traceability
+- Identify EARS requirements related to the task
+- Use Grep to search implementation for evidence of requirement coverage
+- If requirement not traceable to code, flag as "Requirement not implemented"
+
+#### Design Alignment
+- Check if design.md structure is reflected in implementation
+- Verify key interfaces, components, and modules exist
+- Use Grep/LS to confirm file structure matches design
+- If misalignment found, flag as "Design deviation"
+
+#### Regression Check
+- Run full test suite (if available)
+- Verify no existing tests are broken
+- If regressions detected, flag as "Regression detected"
+
+### 4. Generate Report
+
+Provide summary in the language specified in spec.json:
+- Validation summary by feature
+- Coverage report (tasks, requirements, design)
+- Issues and deviations with severity (Critical/Warning)
+- GO/NO-GO decision
+
+## Important Constraints
+- **Conversation-aware**: Prioritize conversation history for auto-detection
+- **Non-blocking warnings**: Design deviations are warnings unless critical
+- **Test-first focus**: Test coverage is mandatory for GO decision
+- **Traceability required**: All requirements must be traceable to implementation
+</instructions>
+
+## Tool Guidance
+- **Conversation parsing**: Extract `/kiro:spec-impl` patterns from history
+- **Read context**: Load all specs and steering before validation
+- **Bash for tests**: Execute test commands to verify pass status
+- **Grep for traceability**: Search codebase for requirement evidence
+- **LS/Glob for structure**: Verify file structure matches design
+
+## Output Description
+
+Provide output in the language specified in spec.json with:
+
+1. **Detected Target**: Features and tasks being validated (if auto-detected)
+2. **Validation Summary**: Brief overview per feature (pass/fail counts)
+3. **Issues**: List of validation failures with severity and location
+4. **Coverage Report**: Requirements/design/task coverage percentages
+5. **Decision**: GO (ready for next phase) / NO-GO (needs fixes)
+
+**Format Requirements**:
+- Use Markdown headings and tables for clarity
+- Flag critical issues with ⚠️ or 🔴
+- Keep summary concise (under 400 words)
+
+## Safety & Fallback
+
+### Error Scenarios
+- **No Implementation Found**: If no `/kiro:spec-impl` in history and no `[x]` tasks, report "No implementations detected"
+- **Test Command Unknown**: If test framework unclear, warn and skip test validation (manual verification required)
+- **Missing Spec Files**: If spec.json/requirements.md/design.md missing, stop with error
+- **Language Undefined**: Default to English (`en`) if spec.json doesn't specify language
+
+### Next Steps Guidance
+
+**If GO Decision**:
+- Implementation validated and ready
+- Proceed to deployment or next feature
+
+**If NO-GO Decision**:
+- Address critical issues listed
+- Re-run `/kiro:spec-impl <feature> [tasks]` for fixes
+- Re-validate with `/kiro:validate-impl [feature] [tasks]`
+
+**Note**: Validation is recommended after implementation to ensure spec alignment and quality.

.claude/commands/learn.md

@@ -0,0 +1,80 @@
+---
+name: learn
+description: /learn - Pattern Extraction for GROWI
+---
+
+# /learn - Pattern Extraction for GROWI
+
+Extract reusable problem-solving patterns from development sessions and save them as auto-invoked Skills.
+
+## Core Purpose
+
+Capture "non-trivial problems" solved during GROWI development, converting them into reusable skills that will be automatically applied in future sessions.
+
+## Pattern Categories to Extract
+
+Focus on four key areas:
+
+1. **Error Resolution** — Document what went wrong, root causes, and fixes applicable to similar issues (e.g., Mongoose query pitfalls, Next.js hydration errors, TypeScript strict mode issues)
+
+2. **Debugging Techniques** — Capture non-obvious diagnostic steps and tool combinations (e.g., MongoDB query profiling, React DevTools with Jotai, Vitest debugging patterns)
+
+3. **Workarounds** — Record library quirks, API limitations, and version-specific solutions (e.g., @headless-tree edge cases, Socket.io reconnection handling, SWR cache invalidation)
+
+4. **GROWI Patterns** — Note codebase conventions, architecture decisions, and integration approaches (e.g., feature-based structure, Jotai + Socket.io sync, API v3 design patterns)
+
+## Skill File Structure
+
+Extracted patterns are saved in `.claude/skills/learned/{topic-name}/SKILL.md` with:
+
+```yaml
+---
+name: descriptive-name
+description: Brief description (auto-invoked when working on related code)
+---
+
+## Problem
+[What was the issue]
+
+## Solution
+[How it was solved]
+
+## Example
+[Code snippet or scenario]
+
+## When to Apply
+[Specific conditions where this pattern is useful]
+```
+
+## GROWI-Specific Examples
+
+Topics commonly learned in GROWI development:
+- `virtualized-tree-patterns` — @headless-tree + @tanstack/react-virtual optimizations
+- `socket-jotai-integration` — Real-time state synchronization patterns
+- `api-v3-error-handling` — RESTful API error response patterns
+- `jotai-atom-composition` — Derived atoms and state composition
+- `mongodb-query-optimization` — Mongoose indexing and aggregation patterns
+
+## Quality Guidelines
+
+**Extract:**
+- Patterns that will save time in future sessions
+- Non-obvious solutions worth remembering
+- Integration techniques between GROWI's tech stack
+- Performance optimizations with measurable impact
+
+**Avoid:**
+- Trivial fixes (typos, syntax errors)
+- One-time issues (service outages, environment-specific problems)
+- Information already documented in existing Skills
+- Feature-specific details (these stay in code comments)
+
+## Workflow
+
+1. User triggers `/learn` after solving a complex problem
+2. Review the session to identify valuable patterns
+3. Draft skill file(s) with clear structure
+4. Save to `.claude/skills/learned/{topic-name}/SKILL.md`
+5. Skills automatically apply in future sessions when working on related code
+
+Learned skills are automatically invoked based on their description when working on related code.

.claude/commands/tdd.md

@@ -0,0 +1,186 @@
+---
+name: tdd
+description: Enforce test-driven development workflow. Scaffold interfaces, generate tests FIRST, then implement minimal code to pass. Ensure 80%+ coverage.
+---
+
+# TDD Command
+
+This command enforces test-driven development methodology for GROWI.
+
+## What This Command Does
+
+1. **Scaffold Interfaces** - Define types/interfaces first
+2. **Generate Tests First** - Write failing tests (RED)
+3. **Implement Minimal Code** - Write just enough to pass (GREEN)
+4. **Refactor** - Improve code while keeping tests green (REFACTOR)
+5. **Verify Coverage** - Ensure 80%+ test coverage
+
+## When to Use
+
+Use `/tdd` when:
+- Implementing new features
+- Adding new functions/components
+- Fixing bugs (write test that reproduces bug first)
+- Refactoring existing code
+- Building critical business logic
+
+## TDD Cycle
+
+```
+RED → GREEN → REFACTOR → REPEAT
+
+RED:      Write a failing test
+GREEN:    Write minimal code to pass
+REFACTOR: Improve code, keep tests passing
+REPEAT:   Next feature/scenario
+```
+
+## Example Usage
+
+```
+User: /tdd I need a function to validate page paths
+
+Agent:
+```
+
+# TDD Session: Page Path Validator
+
+## Step 1: Define Interface (SCAFFOLD)
+
+```typescript
+// src/utils/page-path-validator.ts
+export interface ValidationResult {
+  isValid: boolean;
+  errorMessage?: string;
+}
+
+export function validatePagePath(path: string): ValidationResult {
+  throw new Error('Not implemented');
+}
+```
+
+## Step 2: Write Failing Test (RED)
+
+```typescript
+// src/utils/page-path-validator.spec.ts
+describe('validatePagePath', () => {
+  it('should return valid for correct path', () => {
+    const result = validatePagePath('/user/docs/page');
+    expect(result.isValid).toBe(true);
+  });
+
+  it('should reject path without leading slash', () => {
+    const result = validatePagePath('user/docs');
+    expect(result.isValid).toBe(false);
+    expect(result.errorMessage).toBeDefined();
+  });
+
+  it('should reject empty path', () => {
+    const result = validatePagePath('');
+    expect(result.isValid).toBe(false);
+  });
+});
+```
+
+## Step 3: Run Tests - Verify FAIL
+
+```bash
+turbo run test --filter @growi/app -- src/utils/page-path-validator.spec.ts
+
+FAIL src/utils/page-path-validator.spec.ts
+  ✕ should return valid for correct path
+    Error: Not implemented
+```
+
+✅ Tests fail as expected. Ready to implement.
+
+## Step 4: Implement Minimal Code (GREEN)
+
+```typescript
+export function validatePagePath(path: string): ValidationResult {
+  if (!path) {
+    return { isValid: false, errorMessage: 'Path cannot be empty' };
+  }
+  if (!path.startsWith('/')) {
+    return { isValid: false, errorMessage: 'Path must start with /' };
+  }
+  return { isValid: true };
+}
+```
+
+## Step 5: Run Tests - Verify PASS
+
+```bash
+turbo run test --filter @growi/app -- src/utils/page-path-validator.spec.ts
+
+PASS  ✓ All tests passing!
+```
+
+## Step 6: Check Coverage
+
+```bash
+cd {package_dir} && pnpm vitest run --coverage src/utils/page-path-validator.spec.ts
+
+Coverage: 100% ✅ (Target: 80%)
+```
+
+## TDD Best Practices
+
+**DO:**
+- ✅ Write the test FIRST, before any implementation
+- ✅ Run tests and verify they FAIL before implementing
+- ✅ Write minimal code to make tests pass
+- ✅ Refactor only after tests are green
+- ✅ Add edge cases and error scenarios
+- ✅ Aim for 80%+ coverage (100% for critical code)
+- ✅ Use `vitest-mock-extended` for type-safe mocks
+
+**DON'T:**
+- ❌ Write implementation before tests
+- ❌ Skip running tests after each change
+- ❌ Write too much code at once
+- ❌ Ignore failing tests
+- ❌ Test implementation details (test behavior)
+- ❌ Mock everything (prefer integration tests)
+
+## Test Types to Include
+
+**Unit Tests** (`*.spec.ts`):
+- Happy path scenarios
+- Edge cases (empty, null, max values)
+- Error conditions
+- Boundary values
+
+**Integration Tests** (`*.integ.ts`):
+- API endpoints
+- Database operations
+- External service calls
+
+**Component Tests** (`*.spec.tsx`):
+- React components with hooks
+- User interactions
+- Jotai state integration
+
+## Coverage Requirements
+
+- **80% minimum** for all code
+- **100% required** for:
+  - Authentication/authorization logic
+  - Security-critical code
+  - Core business logic (page operations, permissions)
+  - Data validation utilities
+
+## Important Notes
+
+**MANDATORY**: Tests must be written BEFORE implementation. The TDD cycle is:
+
+1. **RED** - Write failing test
+2. **GREEN** - Implement to pass
+3. **REFACTOR** - Improve code
+
+Never skip the RED phase. Never write code before tests.
+
+## Related Skills
+
+This command uses patterns from:
+- **growi-testing-patterns** - Vitest, React Testing Library, vitest-mock-extended

.claude/rules/coding-style.md

@@ -0,0 +1,217 @@
+# Coding Style
+
+General coding standards and best practices. These rules apply to all code in the GROWI monorepo.
+
+## Immutability (CRITICAL)
+
+ALWAYS create new objects, NEVER mutate:
+
+```typescript
+// ❌ WRONG: Mutation
+function updateUser(user, name) {
+  user.name = name  // MUTATION!
+  return user
+}
+
+// ✅ CORRECT: Immutability
+function updateUser(user, name) {
+  return {
+    ...user,
+    name
+  }
+}
+
+// ✅ CORRECT: Array immutable update
+const updatedPages = pages.map(p => p.id === id ? { ...p, title: newTitle } : p);
+
+// ❌ WRONG: Array mutation
+pages[index].title = newTitle;
+```
+
+## File Organization
+
+MANY SMALL FILES > FEW LARGE FILES:
+
+- High cohesion, low coupling
+- 200-400 lines typical, 800 max
+- Functions < 50 lines
+- Extract utilities from large components
+- Organize by feature/domain, not by type
+
+## Naming Conventions
+
+### Variables and Functions
+
+- **camelCase** for variables and functions
+- **PascalCase** for classes, interfaces, types, React components
+- **UPPER_SNAKE_CASE** for constants
+
+```typescript
+const pageId = '123';
+const MAX_PAGE_SIZE = 1000;
+
+function getPageById(id: string) { }
+class PageService { }
+interface PageData { }
+type PageStatus = 'draft' | 'published';
+```
+
+### Files and Directories
+
+- **PascalCase** for React components: `Button.tsx`, `PageTree.tsx`
+- **kebab-case** for utilities: `page-utils.ts`
+- **lowercase** for directories: `features/page-tree/`, `utils/`
+
+## Export Style
+
+**Prefer named exports** over default exports:
+
+```typescript
+// ✅ Good: Named exports
+export const MyComponent = () => { };
+export function myFunction() { }
+export class MyClass { }
+
+// ❌ Avoid: Default exports
+export default MyComponent;
+```
+
+**Why?**
+- Better refactoring (IDEs can reliably rename across files)
+- Better tree shaking
+- Explicit imports improve readability
+- No ambiguity (import name matches export name)
+
+**Exception**: Next.js pages require default exports.
+
+## Type Safety
+
+**Always provide explicit types** for function parameters and return values:
+
+```typescript
+// ✅ Good: Explicit types
+function createPage(path: string, body: string): Promise<Page> {
+  // ...
+}
+
+// ❌ Avoid: Implicit any
+function createPage(path, body) {
+  // ...
+}
+```
+
+Use `import type` for type-only imports:
+
+```typescript
+import type { PageData } from '~/interfaces/page';
+```
+
+## Error Handling
+
+ALWAYS handle errors comprehensively:
+
+```typescript
+try {
+  const result = await riskyOperation();
+  return result;
+} catch (error) {
+  logger.error('Operation failed:', { error, context });
+  throw new Error('Detailed user-friendly message');
+}
+```
+
+## Async/Await
+
+Prefer async/await over Promise chains:
+
+```typescript
+// ✅ Good: async/await
+async function loadPages() {
+  const pages = await fetchPages();
+  const enriched = await enrichPageData(pages);
+  return enriched;
+}
+
+// ❌ Avoid: Promise chains
+function loadPages() {
+  return fetchPages()
+    .then(pages => enrichPageData(pages))
+    .then(enriched => enriched);
+}
+```
+
+## Comments
+
+**Write comments in English** (even for Japanese developers):
+
+```typescript
+// ✅ Good: English comment
+// Calculate the total number of pages in the workspace
+
+// ❌ Avoid: Japanese comment
+// ワークスペース内のページ総数を計算
+```
+
+**When to comment**:
+- Complex algorithms or business logic
+- Non-obvious workarounds
+- Public APIs and interfaces
+
+**When NOT to comment**:
+- Self-explanatory code (good naming is better)
+- Restating what the code does
+
+## Test File Placement
+
+**Co-locate tests with source files** in the same directory:
+
+```
+src/utils/
+├── helper.ts
+└── helper.spec.ts        # Test next to source
+
+src/components/Button/
+├── Button.tsx
+└── Button.spec.tsx       # Test next to component
+```
+
+### Test File Naming
+
+- Unit tests: `*.spec.{ts,js}`
+- Integration tests: `*.integ.ts`
+- Component tests: `*.spec.{tsx,jsx}`
+
+## Git Commit Messages
+
+Follow conventional commit format:
+
+```
+<type>(<scope>): <subject>
+
+<body>
+```
+
+**Types**: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
+
+**Example**:
+```
+feat(page-tree): add virtualization for large trees
+
+Implemented react-window for virtualizing page tree
+to improve performance with 10k+ pages.
+```
+
+## Code Quality Checklist
+
+Before marking work complete:
+
+- [ ] Code is readable and well-named
+- [ ] Functions are small (<50 lines)
+- [ ] Files are focused (<800 lines)
+- [ ] No deep nesting (>4 levels)
+- [ ] Proper error handling
+- [ ] No console.log statements (use logger)
+- [ ] No mutation (immutable patterns used)
+- [ ] Named exports (except Next.js pages)
+- [ ] English comments
+- [ ] Co-located tests

.claude/rules/performance.md

@@ -0,0 +1,37 @@
+# Performance Optimization
+
+## Model Selection Strategy
+
+**Haiku** - Lightweight tasks:
+- Frequent, simple agent invocations
+- Straightforward code generation
+- Worker agents in multi-agent systems
+
+**Sonnet** - Standard development:
+- Main development work
+- Orchestrating multi-agent workflows
+- Most coding tasks
+
+**Opus** - Complex reasoning:
+- Architectural decisions
+- Difficult debugging
+- Research and analysis
+
+## Context Window Management
+
+Avoid last 20% of context for:
+- Large-scale refactoring
+- Multi-file feature implementation
+- Complex debugging sessions
+
+Lower context sensitivity:
+- Single-file edits
+- Simple bug fixes
+- Documentation updates
+
+## Build Troubleshooting
+
+If build fails:
+1. Use **build-error-resolver** agent
+2. Run `turbo run lint --filter {package}`
+3. Fix incrementally, verify after each fix

.claude/rules/security.md

@@ -0,0 +1,33 @@
+# Security Guidelines
+
+## Mandatory Security Checks
+
+Before ANY commit:
+- [ ] No hardcoded secrets (API keys, passwords, tokens)
+- [ ] All user inputs validated and sanitized
+- [ ] NoSQL injection prevention (use Mongoose properly)
+- [ ] XSS prevention (sanitize HTML output)
+- [ ] CSRF protection enabled
+- [ ] Authentication/authorization verified
+- [ ] Error messages don't leak sensitive data
+
+## Secret Management
+
+```typescript
+// NEVER: Hardcoded secrets
+const apiKey = "sk-xxxxx"
+
+// ALWAYS: Environment variables
+const apiKey = process.env.API_KEY
+if (!apiKey) {
+  throw new Error('API_KEY not configured')
+}
+```
+
+## Security Response Protocol
+
+If security issue found:
+1. STOP immediately
+2. Use **security-reviewer** agent
+3. Fix CRITICAL issues before continuing
+4. Rotate any exposed secrets

.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [[ \"$FILE\" == */apps/* ]] || [[ \"$FILE\" == */packages/* ]]; then REPO_ROOT=$(echo \"$FILE\" | sed 's|/\\(apps\\|packages\\)/.*|/|'); cd \"$REPO_ROOT\" && pnpm biome check --write \"$FILE\" 2>/dev/null || true; fi",
+            "timeout": 30,
+            "description": "Auto-format edited files in apps/* and packages/* with Biome"
+          }
+        ]
+      }
+    ]
+  }
+}

.claude/skills/learned/.gitkeep

@@ -0,0 +1,27 @@
+# Learned Skills Directory
+
+This directory contains Skills learned from development sessions using the `/learn` command.
+
+Each learned skill is automatically applied when working on related code based on its description.
+
+## Structure
+
+```
+learned/
+├── {topic-name-1}/
+│   └── SKILL.md
+├── {topic-name-2}/
+│   └── SKILL.md
+└── {topic-name-3}/
+    └── SKILL.md
+```
+
+## How Skills Are Created
+
+Use the `/learn` command after completing a feature or solving a complex problem:
+
+```
+/learn
+```
+
+Claude will extract reusable patterns and save them as Skills in this directory.

.claude/skills/monorepo-overview/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: monorepo-overview
+description: GROWI monorepo structure, workspace organization, and architectural principles. Auto-invoked for all GROWI development work.
+user-invocable: false
+---
+
+# GROWI Monorepo Overview
+
+GROWI is a team collaboration wiki platform built as a monorepo using **pnpm workspace + Turborepo**.
+
+## Monorepo Structure
+
+```
+growi/
+├── apps/                    # Applications
+│   ├── app/                # Main GROWI application (Next.js + Express + MongoDB)
+│   ├── pdf-converter/      # PDF conversion microservice (Ts.ED + Puppeteer)
+│   └── slackbot-proxy/     # Slack integration proxy (Ts.ED + TypeORM + MySQL)
+├── packages/               # Shared libraries
+│   ├── core/              # Core utilities and shared logic
+│   ├── core-styles/       # Common styles (SCSS)
+│   ├── editor/            # Markdown editor components
+│   ├── ui/                # UI component library
+│   ├── pluginkit/         # Plugin framework
+│   ├── slack/             # Slack integration utilities
+│   ├── presentation/      # Presentation mode
+│   ├── pdf-converter-client/ # PDF converter client library
+│   └── remark-*/          # Markdown plugins (remark-lsx, remark-drawio, etc.)
+└── Configuration files
+    ├── pnpm-workspace.yaml
+    ├── turbo.json
+    ├── package.json
+    └── .changeset/
+```
+
+## Workspace Management
+
+### pnpm Workspace
+
+All packages are managed via **pnpm workspace**. Package references use the `workspace:` protocol:
+
+```json
+{
+  "dependencies": {
+    "@growi/core": "workspace:^",
+    "@growi/ui": "workspace:^"
+  }
+}
+```
+
+### Turborepo Orchestration
+
+Turborepo handles task orchestration with caching and parallelization:
+
+```bash
+# Run tasks across all workspaces
+turbo run dev
+turbo run test
+turbo run lint
+turbo run build
+
+# Filter to specific package
+turbo run test --filter @growi/app
+turbo run lint --filter @growi/core
+```
+
+## Architectural Principles
+
+### 1. Feature-Based Architecture (Recommended)
+
+**All packages should prefer feature-based organization**:
+
+```
+{package}/src/
+├── features/              # Feature modules
+│   ├── {feature-name}/
+│   │   ├── index.ts      # Main export
+│   │   ├── interfaces/   # TypeScript types
+│   │   ├── server/       # Server-side logic (if applicable)
+│   │   ├── client/       # Client-side logic (if applicable)
+│   │   └── utils/        # Shared utilities
+```
+
+**Benefits**:
+- Clear boundaries between features
+- Easy to locate related code
+- Facilitates gradual migration from legacy structure
+
+### 2. Server-Client Separation
+
+For full-stack packages (like apps/app), separate server and client logic:
+
+- **Server code**: Node.js runtime, database access, API routes
+- **Client code**: Browser runtime, React components, UI state
+
+This enables better code splitting and prevents server-only code from being bundled into client.
+
+### 3. Shared Libraries in packages/
+
+Common code should be extracted to `packages/`:
+
+- **core**: Utilities, constants, type definitions
+- **ui**: Reusable React components
+- **editor**: Markdown editor
+- **pluginkit**: Plugin system framework
+
+## Version Management with Changeset
+
+GROWI uses **Changesets** for version management and release notes:
+
+```bash
+# Add a changeset (after making changes)
+npx changeset
+
+# Version bump (generates CHANGELOGs and updates versions)
+pnpm run version-subpackages
+
+# Publish packages to npm (for @growi/core, @growi/pluginkit)
+pnpm run release-subpackages
+```
+
+### Changeset Workflow
+
+1. Make code changes
+2. Run `npx changeset` and describe the change
+3. Commit both code and `.changeset/*.md` file
+4. On release, run `pnpm run version-subpackages`
+5. Changesets automatically updates `CHANGELOG.md` and `package.json` versions
+
+### Version Schemes
+
+- **Main app** (`apps/app`): Manual versioning with RC prereleases
+  - `pnpm run version:patch`, `pnpm run version:prerelease`
+- **Shared libraries** (`packages/core`, `packages/pluginkit`): Changeset-managed
+- **Microservices** (`apps/pdf-converter`, `apps/slackbot-proxy`): Independent versioning
+
+## Package Categories
+
+### Applications (apps/)
+
+| Package | Description | Tech Stack |
+|---------|-------------|------------|
+| **@growi/app** | Main wiki application | Next.js (Pages Router), Express, MongoDB, Jotai, SWR |
+| **@growi/pdf-converter** | PDF export service | Ts.ED, Puppeteer |
+| **@growi/slackbot-proxy** | Slack bot proxy | Ts.ED, TypeORM, MySQL |
+
+### Core Libraries (packages/)
+
+| Package | Description | Published to npm |
+|---------|-------------|------------------|
+| **@growi/core** | Core utilities | ✅ |
+| **@growi/pluginkit** | Plugin framework | ✅ |
+| **@growi/ui** | UI components | ❌ (internal) |
+| **@growi/editor** | Markdown editor | ❌ (internal) |
+| **@growi/core-styles** | Common styles | ❌ (internal) |
+
+## Development Workflow
+
+### Initial Setup
+
+```bash
+# Install dependencies for all packages
+pnpm install
+
+# Bootstrap (install + build dependencies)
+turbo run bootstrap
+```
+
+### Daily Development
+
+```bash
+# Start all dev servers (apps/app + dependencies)
+turbo run dev
+
+# Run tests for specific package
+turbo run test --filter @growi/app
+
+# Lint specific package
+turbo run lint --filter @growi/core
+```
+
+### Cross-Package Development
+
+When modifying shared libraries (packages/*), ensure dependent apps reflect changes:
+
+1. Make changes to `packages/core`
+2. Turborepo automatically detects changes and rebuilds dependents
+3. Test in `apps/app` to verify
+
+## Key Configuration Files
+
+- **pnpm-workspace.yaml**: Defines workspace packages
+- **turbo.json**: Turborepo pipeline configuration
+- **.changeset/config.json**: Changeset configuration
+- **tsconfig.base.json**: Base TypeScript config for all packages
+- **vitest.workspace.mts**: Vitest workspace config
+- **biome.json**: Biome linter/formatter config
+
+## Design Principles Summary
+
+1. **Feature Isolation**: Use feature-based architecture for new code
+2. **Server-Client Separation**: Keep server and client code separate
+3. **Shared Libraries**: Extract common code to packages/
+4. **Type-Driven Development**: Define interfaces before implementation
+5. **Progressive Enhancement**: Migrate legacy code gradually
+6. **Version Control**: Use Changesets for release management

.claude/skills/tech-stack/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: tech-stack
+description: GROWI technology stack, build tools, and global commands. Auto-invoked for all GROWI development work.
+user-invocable: false
+---
+
+# GROWI Tech Stack
+
+## Core Technologies
+
+- **TypeScript** ~5.0.0
+- **Node.js** ^18 || ^20
+- **MongoDB** with **Mongoose** ^6.13.6 (apps/app)
+- **MySQL** with **TypeORM** 0.2.x (apps/slackbot-proxy)
+
+## Frontend Framework
+
+- **React** 18.x
+- **Next.js** (Pages Router) - Full-stack framework for apps/app
+
+## State Management & Data Fetching (Global Standard)
+
+- **Jotai** - Atomic state management (recommended for all packages with UI state)
+  - Use for UI state, form state, modal state, etc.
+  - Lightweight, TypeScript-first, minimal boilerplate
+
+- **SWR** ^2.3.2 - Data fetching with caching
+  - Use for API data fetching with automatic revalidation
+  - Works seamlessly with RESTful APIs
+
+### Why Jotai + SWR?
+
+- **Separation of concerns**: Jotai for UI state, SWR for server state
+- **Performance**: Fine-grained reactivity (Jotai) + intelligent caching (SWR)
+- **Type safety**: Both libraries have excellent TypeScript support
+- **Simplicity**: Minimal API surface, easy to learn
+
+## Build & Development Tools
+
+### Package Management
+- **pnpm** 10.4.1 - Package manager (faster, more efficient than npm/yarn)
+
+### Monorepo Orchestration
+- **Turborepo** ^2.1.3 - Build system with caching and parallelization
+
+### Linter & Formatter
+- **Biome** ^2.2.6 - Unified linter and formatter (recommended)
+  - Replaces ESLint + Prettier
+  - Significantly faster (10-100x)
+  - Configuration: `biome.json`
+
+```bash
+# Lint and format check
+biome check <files>
+
+# Auto-fix issues
+biome check --write <files>
+```
+
+- **Stylelint** ^16.5.0 - SCSS/CSS linter
+  - Configuration: `.stylelintrc.js`
+
+```bash
+# Lint styles
+stylelint "src/**/*.scss"
+```
+
+### Testing
+- **Vitest** ^2.1.1 - Unit and integration testing (recommended)
+  - Fast, Vite-powered
+  - Jest-compatible API
+  - Configuration: `vitest.workspace.mts`
+
+- **React Testing Library** ^16.0.1 - Component testing
+  - User-centric testing approach
+
+- **vitest-mock-extended** ^2.0.2 - Type-safe mocking
+  - TypeScript autocomplete for mocks
+
+- **Playwright** ^1.49.1 - E2E testing
+  - Cross-browser testing
+
+## Essential Commands (Global)
+
+### Development
+
+```bash
+# Start all dev servers (apps/app + dependencies)
+turbo run dev
+
+# Start dev server for specific package
+turbo run dev --filter @growi/app
+
+# Install dependencies for all packages
+pnpm install
+
+# Bootstrap (install + build dependencies)
+turbo run bootstrap
+```
+
+### Testing & Quality
+
+```bash
+# Run tests for specific package
+turbo run test --filter @growi/app
+
+# Run linters for specific package
+turbo run lint --filter @growi/app
+```
+
+### Building
+
+```bash
+# Build all packages
+turbo run build
+
+# Build specific package
+turbo run build --filter @growi/core
+```
+
+## Turborepo Task Filtering
+
+Turborepo uses `--filter` to target specific packages:
+
+```bash
+# Run task for single package
+turbo run test --filter @growi/app
+
+# Run task for multiple packages
+turbo run build --filter @growi/core --filter @growi/ui
+
+# Run task for package and its dependencies
+turbo run build --filter @growi/app...
+```
+
+## Important Configuration Files
+
+### Workspace Configuration
+- **pnpm-workspace.yaml** - Defines workspace packages
+  ```yaml
+  packages:
+    - 'apps/*'
+    - 'packages/*'
+  ```
+
+### Build Configuration
+- **turbo.json** - Turborepo pipeline configuration
+  - Defines task dependencies, caching, and outputs
+
+### TypeScript Configuration
+- **tsconfig.base.json** - Base TypeScript config extended by all packages
+  - **Target**: ESNext
+  - **Module**: ESNext
+  - **Strict Mode**: Enabled (`strict: true`)
+  - **Module Resolution**: Bundler
+  - **Allow JS**: true (for gradual migration)
+  - **Isolated Modules**: true (required for Vite, SWC)
+
+Package-specific tsconfig.json example:
+```json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.spec.ts"]
+}
+```
+
+### Testing Configuration
+- **vitest.workspace.mts** - Vitest workspace config
+  - Defines test environments (Node.js, happy-dom)
+  - Configures coverage
+
+### Linter Configuration
+- **biome.json** - Biome linter/formatter config
+  - Rules, ignore patterns, formatting options
+
+## Development Best Practices
+
+### Command Usage
+
+1. **Always use Turborepo for cross-package tasks**:
+   - ✅ `turbo run test --filter @growi/app`
+   - ❌ `cd apps/app && pnpm test` (bypasses Turborepo caching)
+
+2. **Use pnpm for package management**:
+   - ✅ `pnpm install`
+   - ❌ `npm install` or `yarn install`
+
+3. **Run tasks from workspace root**:
+   - Turborepo handles cross-package dependencies
+   - Caching works best from root
+
+### State Management Guidelines
+
+1. **Use Jotai for UI state**:
+   ```typescript
+   // Example: Modal state
+   import { atom } from 'jotai';
+
+   export const isModalOpenAtom = atom(false);
+   ```
+
+2. **Use SWR for server state**:
+   ```typescript
+   // Example: Fetching pages
+   import useSWR from 'swr';
+
+   const { data, error, isLoading } = useSWR('/api/pages', fetcher);
+   ```
+
+3. **Avoid mixing concerns**:
+   - Don't store server data in Jotai atoms
+   - Don't manage UI state with SWR
+
+## Migration Notes
+
+- **New packages**: Use Biome + Vitest from the start
+- **Legacy packages**: Can continue using existing tools during migration
+- **Gradual migration**: Prefer updating to Biome + Vitest when modifying existing files
+
+## Technology Decisions
+
+### Why Next.js Pages Router (not App Router)?
+
+- GROWI started before App Router was stable
+- Pages Router is well-established and stable
+- Migration to App Router is being considered for future versions
+
+### Why Jotai (not Redux/Zustand)?
+
+- **Atomic approach**: More flexible than Redux, simpler than Recoil
+- **TypeScript-first**: Excellent type inference
+- **Performance**: Fine-grained reactivity, no unnecessary re-renders
+- **Minimal boilerplate**: Less code than Redux
+
+### Why SWR (not React Query)?
+
+- **Simplicity**: Smaller API surface
+- **Vercel integration**: Built by Vercel (same as Next.js)
+- **Performance**: Optimized for Next.js SSR/SSG
+
+### Why Biome (not ESLint + Prettier)?
+
+- **Speed**: 10-100x faster than ESLint
+- **Single tool**: Replaces both ESLint and Prettier
+- **Consistency**: No conflicts between linter and formatter
+- **Growing ecosystem**: Active development, Rust-based
+
+## Package-Specific Tech Stacks
+
+Different apps in the monorepo may use different tech stacks:
+
+- **apps/app**: Next.js + Express + MongoDB + Jotai + SWR
+- **apps/pdf-converter**: Ts.ED + Puppeteer
+- **apps/slackbot-proxy**: Ts.ED + TypeORM + MySQL
+
+See package-specific CLAUDE.md or skills for details.

.claude/skills/testing-patterns-with-vitest/SKILL.md

@@ -0,0 +1,436 @@
+---
+name: testing-patterns-with-vitest
+description: GROWI testing patterns with Vitest, React Testing Library, and vitest-mock-extended. Auto-invoked for all GROWI development work.
+user-invocable: false
+---
+
+# GROWI Testing Patterns
+
+GROWI uses **Vitest** for all testing (unit, integration, component). This skill covers universal testing patterns applicable across the monorepo.
+
+## Test File Placement (Global Standard)
+
+Place test files **in the same directory** as the source file:
+
+```
+src/components/Button/
+├── Button.tsx
+└── Button.spec.tsx       # Component test
+
+src/utils/
+├── helper.ts
+└── helper.spec.ts        # Unit test
+
+src/services/api/
+├── pageService.ts
+└── pageService.integ.ts  # Integration test
+```
+
+## Test Types & Environments
+
+| File Pattern | Type | Environment | Use Case |
+|--------------|------|-------------|----------|
+| `*.spec.{ts,js}` | Unit Test | Node.js | Pure functions, utilities, services |
+| `*.integ.ts` | Integration Test | Node.js + DB | API routes, database operations |
+| `*.spec.{tsx,jsx}` | Component Test | happy-dom | React components |
+
+Vitest automatically selects the environment based on file extension and configuration.
+
+## Vitest Configuration
+
+### Global APIs (No Imports Needed)
+
+All GROWI packages configure Vitest globals in `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "types": ["vitest/globals"]
+  }
+}
+```
+
+This enables auto-import of testing APIs:
+
+```typescript
+// No imports needed!
+describe('MyComponent', () => {
+  it('should render', () => {
+    expect(true).toBe(true);
+  });
+
+  beforeEach(() => {
+    // Setup
+  });
+
+  afterEach(() => {
+    // Cleanup
+  });
+});
+```
+
+**Available globals**: `describe`, `it`, `test`, `expect`, `beforeEach`, `afterEach`, `beforeAll`, `afterAll`, `vi`
+
+## Type-Safe Mocking with vitest-mock-extended
+
+### Basic Usage
+
+`vitest-mock-extended` provides **fully type-safe mocks** with TypeScript autocomplete:
+
+```typescript
+import { mockDeep, type DeepMockProxy } from 'vitest-mock-extended';
+
+// Create type-safe mock
+const mockRouter: DeepMockProxy<NextRouter> = mockDeep<NextRouter>();
+
+// TypeScript autocomplete works!
+mockRouter.asPath = '/test-path';
+mockRouter.query = { id: '123' };
+mockRouter.push.mockResolvedValue(true);
+
+// Use in tests
+expect(mockRouter.push).toHaveBeenCalledWith('/new-path');
+```
+
+### Complex Types with Optional Properties
+
+```typescript
+interface ComplexProps {
+  currentPageId?: string | null;
+  currentPathname?: string | null;
+  data?: Record<string, unknown>;
+  onSubmit?: (value: string) => void;
+}
+
+const mockProps: DeepMockProxy<ComplexProps> = mockDeep<ComplexProps>();
+mockProps.currentPageId = 'page-123';
+mockProps.data = { key: 'value' };
+mockProps.onSubmit?.mockImplementation((value) => {
+  console.log(value);
+});
+```
+
+### Why vitest-mock-extended?
+
+- ✅ **Type safety**: Catches typos at compile time
+- ✅ **Autocomplete**: IDE suggestions for all properties/methods
+- ✅ **Deep mocking**: Automatically mocks nested objects
+- ✅ **Vitest integration**: Works seamlessly with `vi.fn()`
+
+## React Testing Library Patterns
+
+### Basic Component Test
+
+```typescript
+import { render } from '@testing-library/react';
+import { Button } from './Button';
+
+describe('Button', () => {
+  it('should render with text', () => {
+    const { getByText } = render(<Button>Click me</Button>);
+    expect(getByText('Click me')).toBeInTheDocument();
+  });
+
+  it('should call onClick when clicked', async () => {
+    const onClick = vi.fn();
+    const { getByRole } = render(<Button onClick={onClick}>Click</Button>);
+
+    const button = getByRole('button');
+    await userEvent.click(button);
+
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+});
+```
+
+### Testing with Jotai (Global Pattern)
+
+When testing components that use Jotai atoms, wrap with `<Provider>`:
+
+```typescript
+import { render } from '@testing-library/react';
+import { Provider } from 'jotai';
+
+const renderWithJotai = (ui: React.ReactElement) => {
+  const Wrapper = ({ children }: { children: React.ReactNode }) => (
+    <Provider>{children}</Provider>
+  );
+  return render(ui, { wrapper: Wrapper });
+};
+
+describe('ComponentWithJotai', () => {
+  it('should render with atom state', () => {
+    const { getByText } = renderWithJotai(<MyComponent />);
+    expect(getByText('Hello')).toBeInTheDocument();
+  });
+});
+```
+
+### Isolated Jotai Scope (For Testing)
+
+To isolate atom state between tests:
+
+```typescript
+import { createScope } from 'jotai-scope';
+
+describe('ComponentWithIsolatedState', () => {
+  it('test 1', () => {
+    const scope = createScope();
+    const { getByText } = renderWithJotai(<MyComponent />, scope);
+    // ...
+  });
+
+  it('test 2', () => {
+    const scope = createScope(); // Fresh scope
+    const { getByText } = renderWithJotai(<MyComponent />, scope);
+    // ...
+  });
+});
+```
+
+## Async Testing Patterns (Global Standard)
+
+### Using `act()` and `waitFor()`
+
+When testing async state updates:
+
+```typescript
+import { waitFor, act } from '@testing-library/react';
+import { renderHook } from '@testing-library/react';
+
+test('async hook', async () => {
+  const { result } = renderHook(() => useMyAsyncHook());
+
+  // Trigger async action
+  await act(async () => {
+    result.current.triggerAsyncAction();
+  });
+
+  // Wait for state update
+  await waitFor(() => {
+    expect(result.current.isLoading).toBe(false);
+  });
+
+  expect(result.current.data).toBeDefined();
+});
+```
+
+### Testing Async Functions
+
+```typescript
+it('should fetch data successfully', async () => {
+  const data = await fetchData();
+  expect(data).toEqual({ id: '123', name: 'Test' });
+});
+
+it('should handle errors', async () => {
+  await expect(fetchDataWithError()).rejects.toThrow('Error');
+});
+```
+
+## Advanced Assertions
+
+### Object Matching
+
+```typescript
+expect(mockFunction).toHaveBeenCalledWith(
+  expect.objectContaining({
+    pathname: '/expected-path',
+    data: expect.any(Object),
+    timestamp: expect.any(Number),
+  })
+);
+```
+
+### Array Matching
+
+```typescript
+expect(result).toEqual(
+  expect.arrayContaining([
+    expect.objectContaining({ id: '123' }),
+    expect.objectContaining({ id: '456' }),
+  ])
+);
+```
+
+### Partial Matching
+
+```typescript
+expect(user).toMatchObject({
+  name: 'John',
+  email: 'john@example.com',
+  // Other properties are ignored
+});
+```
+
+## Test Structure Best Practices
+
+### AAA Pattern (Arrange-Act-Assert)
+
+```typescript
+describe('MyComponent', () => {
+  beforeEach(() => {
+    vi.clearAllMocks(); // Clear mocks before each test
+  });
+
+  describe('rendering', () => {
+    it('should render with default props', () => {
+      // Arrange: Setup test data
+      const props = { title: 'Test' };
+
+      // Act: Render component
+      const { getByText } = render(<MyComponent {...props} />);
+
+      // Assert: Verify output
+      expect(getByText('Test')).toBeInTheDocument();
+    });
+  });
+
+  describe('user interactions', () => {
+    it('should submit form on button click', async () => {
+      // Arrange
+      const onSubmit = vi.fn();
+      const { getByRole, getByLabelText } = render(
+        <MyForm onSubmit={onSubmit} />
+      );
+
+      // Act
+      await userEvent.type(getByLabelText('Name'), 'John');
+      await userEvent.click(getByRole('button', { name: 'Submit' }));
+
+      // Assert
+      expect(onSubmit).toHaveBeenCalledWith({ name: 'John' });
+    });
+  });
+});
+```
+
+### Nested `describe` for Organization
+
+```typescript
+describe('PageService', () => {
+  describe('createPage', () => {
+    it('should create a page successfully', async () => {
+      // ...
+    });
+
+    it('should throw error if path is invalid', async () => {
+      // ...
+    });
+  });
+
+  describe('updatePage', () => {
+    it('should update page content', async () => {
+      // ...
+    });
+  });
+});
+```
+
+## Common Mocking Patterns
+
+### Mocking SWR
+
+```typescript
+vi.mock('swr', () => ({
+  default: vi.fn(() => ({
+    data: mockData,
+    error: null,
+    isLoading: false,
+    mutate: vi.fn(),
+  })),
+}));
+```
+
+### Mocking Modules
+
+```typescript
+// Mock entire module
+vi.mock('~/services/PageService', () => ({
+  PageService: {
+    findById: vi.fn().mockResolvedValue({ id: '123', title: 'Test' }),
+    create: vi.fn().mockResolvedValue({ id: '456', title: 'New' }),
+  },
+}));
+
+// Use in test
+import { PageService } from '~/services/PageService';
+
+it('should call PageService.findById', async () => {
+  await myFunction();
+  expect(PageService.findById).toHaveBeenCalledWith('123');
+});
+```
+
+### Mocking Specific Functions
+
+```typescript
+import { myFunction } from '~/utils/myUtils';
+
+vi.mock('~/utils/myUtils', () => ({
+  myFunction: vi.fn().mockReturnValue('mocked'),
+  otherFunction: vi.fn(), // Mock other exports
+}));
+```
+
+## Integration Tests (with Database)
+
+Integration tests (*.integ.ts) can access in-memory databases:
+
+```typescript
+describe('PageService Integration', () => {
+  beforeEach(async () => {
+    // Setup: Seed test data
+    await Page.create({ path: '/test', body: 'content' });
+  });
+
+  afterEach(async () => {
+    // Cleanup: Clear database
+    await Page.deleteMany({});
+  });
+
+  it('should create a page', async () => {
+    const page = await PageService.create({
+      path: '/new-page',
+      body: 'content',
+    });
+
+    expect(page._id).toBeDefined();
+    expect(page.path).toBe('/new-page');
+  });
+});
+```
+
+## Testing Checklist
+
+Before committing tests, ensure:
+
+- ✅ **Co-location**: Test files are next to source files
+- ✅ **Descriptive names**: Test descriptions clearly state what is being tested
+- ✅ **AAA pattern**: Tests follow Arrange-Act-Assert structure
+- ✅ **Mocks cleared**: Use `beforeEach(() => vi.clearAllMocks())`
+- ✅ **Async handled**: Use `async/await` and `waitFor()` for async operations
+- ✅ **Type safety**: Use `vitest-mock-extended` for type-safe mocks
+- ✅ **Isolated state**: Jotai tests use separate scopes if needed
+
+## Running Tests
+
+```bash
+# Run all tests for a package
+turbo run test --filter @growi/app
+
+# Run specific test file
+cd {package_dir} && pnpm vitest run src/components/Button/Button.spec.tsx
+```
+
+## Summary: GROWI Testing Philosophy
+
+1. **Co-locate tests**: Keep tests close to source code
+2. **Type-safe mocks**: Use `vitest-mock-extended` for TypeScript support
+3. **React Testing Library**: Test user behavior, not implementation details
+4. **Async patterns**: Use `act()` and `waitFor()` for async state updates
+5. **Jotai integration**: Wrap components with `<Provider>` for atom state
+6. **Clear structure**: Use nested `describe` and AAA pattern
+7. **Clean mocks**: Always clear mocks between tests
+
+These patterns apply to **all GROWI packages** with React/TypeScript code.

.devcontainer/app/devcontainer.json

@@ -30,6 +30,8 @@
         "editorconfig.editorconfig",
         "shinnn.stylelint",
         "stylelint.vscode-stylelint",
+        // TypeScript (Native Preview)
+        "typescriptteam.native-preview",
         // Test
         "vitest.explorer",
         "ms-playwright.playwright",

.gitignore

@@ -37,7 +37,7 @@ yarn-error.log*
 
 # IDE, dev #
 .idea
-.claude
+**/.claude/settings.local.json
 *.orig
 *.code-workspace
 *.timestamp-*.mjs

.kiro/settings/rules/design-discovery-full.md

@@ -0,0 +1,93 @@
+# Full Discovery Process for Technical Design
+
+## Objective
+Conduct comprehensive research and analysis to ensure the technical design is based on complete, accurate, and up-to-date information.
+
+## Discovery Steps
+
+### 1. Requirements Analysis
+**Map Requirements to Technical Needs**
+- Extract all functional requirements from EARS format
+- Identify non-functional requirements (performance, security, scalability)
+- Determine technical constraints and dependencies
+- List core technical challenges
+
+### 2. Existing Implementation Analysis
+**Understand Current System** (if modifying/extending):
+- Analyze codebase structure and architecture patterns
+- Map reusable components, services, utilities
+- Identify domain boundaries and data flows
+- Document integration points and dependencies
+- Determine approach: extend vs refactor vs wrap
+
+### 3. Technology Research
+**Investigate Best Practices and Solutions**:
+- **Use WebSearch** to find:
+  - Latest architectural patterns for similar problems
+  - Industry best practices for the technology stack
+  - Recent updates or changes in relevant technologies
+  - Common pitfalls and solutions
+
+- **Use WebFetch** to analyze:
+  - Official documentation for frameworks/libraries
+  - API references and usage examples
+  - Migration guides and breaking changes
+  - Performance benchmarks and comparisons
+
+### 4. External Dependencies Investigation
+**For Each External Service/Library**:
+- Search for official documentation and GitHub repositories
+- Verify API signatures and authentication methods
+- Check version compatibility with existing stack
+- Investigate rate limits and usage constraints
+- Find community resources and known issues
+- Document security considerations
+- Note any gaps requiring implementation investigation
+
+### 5. Architecture Pattern & Boundary Analysis
+**Evaluate Architectural Options**:
+- Compare relevant patterns (MVC, Clean, Hexagonal, Event-driven)
+- Assess fit with existing architecture and steering principles
+- Identify domain boundaries and ownership seams required to avoid team conflicts
+- Consider scalability implications and operational concerns
+- Evaluate maintainability and team expertise
+- Document preferred pattern and rejected alternatives in `research.md`
+
+### 6. Risk Assessment
+**Identify Technical Risks**:
+- Performance bottlenecks and scaling limits
+- Security vulnerabilities and attack vectors
+- Integration complexity and coupling
+- Technical debt creation vs resolution
+- Knowledge gaps and training needs
+
+## Research Guidelines
+
+### When to Search
+**Always search for**:
+- External API documentation and updates
+- Security best practices for authentication/authorization
+- Performance optimization techniques for identified bottlenecks
+- Latest versions and migration paths for dependencies
+
+**Search if uncertain about**:
+- Architectural patterns for specific use cases
+- Industry standards for data formats/protocols
+- Compliance requirements (GDPR, HIPAA, etc.)
+- Scalability approaches for expected load
+
+### Search Strategy
+1. Start with official sources (documentation, GitHub)
+2. Check recent blog posts and articles (last 6 months)
+3. Review Stack Overflow for common issues
+4. Investigate similar open-source implementations
+
+## Output Requirements
+Capture all findings that impact design decisions in `research.md` using the shared template:
+- Key insights affecting architecture, technology alignment, and contracts
+- Constraints discovered during research
+- Recommended approaches and selected architecture pattern with rationale
+- Rejected alternatives and trade-offs (documented in the Design Decisions section)
+- Updated domain boundaries that inform Components & Interface Contracts
+- Risks and mitigation strategies
+- Gaps requiring further investigation during implementation

.kiro/settings/rules/design-discovery-light.md

@@ -0,0 +1,49 @@
+# Light Discovery Process for Extensions
+
+## Objective
+Quickly analyze existing system and integration requirements for feature extensions.
+
+## Focused Discovery Steps
+
+### 1. Extension Point Analysis
+**Identify Integration Approach**:
+- Locate existing extension points or interfaces
+- Determine modification scope (files, components)
+- Check for existing patterns to follow
+- Identify backward compatibility requirements
+
+### 2. Dependency Check
+**Verify Compatibility**:
+- Check version compatibility of new dependencies
+- Validate API contracts haven't changed
+- Ensure no breaking changes in pipeline
+
+### 3. Quick Technology Verification
+**For New Libraries Only**:
+- Use WebSearch for official documentation
+- Verify basic usage patterns
+- Check for known compatibility issues
+- Confirm licensing compatibility
+- Record key findings in `research.md` (technology alignment section)
+
+### 4. Integration Risk Assessment
+**Quick Risk Check**:
+- Impact on existing functionality
+- Performance implications
+- Security considerations
+- Testing requirements
+
+## When to Escalate to Full Discovery
+Switch to full discovery if you find:
+- Significant architectural changes needed
+- Complex external service integrations
+- Security-sensitive implementations
+- Performance-critical components
+- Unknown or poorly documented dependencies
+
+## Output Requirements
+- Clear integration approach (note boundary impacts in `research.md`)
+- List of files/components to modify
+- New dependencies with versions
+- Integration risks and mitigations
+- Testing focus areas

.kiro/settings/rules/design-principles.md

@@ -0,0 +1,182 @@
+# Technical Design Rules and Principles
+
+## Core Design Principles
+
+### 1. Type Safety is Mandatory
+- **NEVER** use `any` type in TypeScript interfaces
+- Define explicit types for all parameters and returns
+- Use discriminated unions for error handling
+- Specify generic constraints clearly
+
+### 2. Design vs Implementation
+- **Focus on WHAT, not HOW**
+- Define interfaces and contracts, not code
+- Specify behavior through pre/post conditions
+- Document architectural decisions, not algorithms
+
+### 3. Visual Communication
+- **Simple features**: Basic component diagram or none
+- **Medium complexity**: Architecture + data flow
+- **High complexity**: Multiple diagrams (architecture, sequence, state)
+- **Always pure Mermaid**: No styling, just structure
+
+### 4. Component Design Rules
+- **Single Responsibility**: One clear purpose per component
+- **Clear Boundaries**: Explicit domain ownership
+- **Dependency Direction**: Follow architectural layers
+- **Interface Segregation**: Minimal, focused interfaces
+- **Team-safe Interfaces**: Design boundaries that allow parallel implementation without merge conflicts
+- **Research Traceability**: Record boundary decisions and rationale in `research.md`
+
+### 5. Data Modeling Standards
+- **Domain First**: Start with business concepts
+- **Consistency Boundaries**: Clear aggregate roots
+- **Normalization**: Balance between performance and integrity
+- **Evolution**: Plan for schema changes
+
+### 6. Error Handling Philosophy
+- **Fail Fast**: Validate early and clearly
+- **Graceful Degradation**: Partial functionality over complete failure
+- **User Context**: Actionable error messages
+- **Observability**: Comprehensive logging and monitoring
+
+### 7. Integration Patterns
+- **Loose Coupling**: Minimize dependencies
+- **Contract First**: Define interfaces before implementation
+- **Versioning**: Plan for API evolution
+- **Idempotency**: Design for retry safety
+- **Contract Visibility**: Surface API and event contracts in design.md while linking extended details from `research.md`
+
+## Documentation Standards
+
+### Language and Tone
+- **Declarative**: "The system authenticates users" not "The system should authenticate"
+- **Precise**: Specific technical terms over vague descriptions
+- **Concise**: Essential information only
+- **Formal**: Professional technical writing
+
+### Structure Requirements
+- **Hierarchical**: Clear section organization
+- **Traceable**: Requirements to components mapping
+- **Complete**: All aspects covered for implementation
+- **Consistent**: Uniform terminology throughout
+- **Focused**: Keep design.md centered on architecture and contracts; move investigation logs and lengthy comparisons to `research.md`
+
+## Section Authoring Guidance
+
+### Global Ordering
+- Default flow: Overview → Goals/Non-Goals → Requirements Traceability → Architecture → Technology Stack → System Flows → Components & Interfaces → Data Models → Optional sections.
+- Teams may swap Traceability earlier or place Data Models nearer Architecture when it improves clarity, but keep section headings intact.
+- Within each section, follow **Summary → Scope → Decisions → Impacts/Risks** so reviewers can scan consistently.
+
+### Requirement IDs
+- Reference requirements as `2.1, 2.3` without prefixes (no “Requirement 2.1”).
+- All requirements MUST have numeric IDs. If a requirement lacks a numeric ID, stop and fix `requirements.md` before continuing.
+- Use `N.M`-style numeric IDs where `N` is the top-level requirement number from requirements.md (for example, Requirement 1 → 1.1, 1.2; Requirement 2 → 2.1, 2.2).
+- Every component, task, and traceability row must reference the same canonical numeric ID.
+
+### Technology Stack
+- Include ONLY layers impacted by this feature (frontend, backend, data, messaging, infra).
+- For each layer specify tool/library + version + the role it plays; push extended rationale, comparisons, or benchmarks to `research.md`.
+- When extending an existing system, highlight deviations from the current stack and list new dependencies.
+
+### System Flows
+- Add diagrams only when they clarify behavior:  
+  - **Sequence** for multi-step interactions  
+  - **Process/State** for branching rules or lifecycle  
+  - **Data/Event** for pipelines or async patterns
+- Always use pure Mermaid. If no complex flow exists, omit the entire section.
+
+### Requirements Traceability
+- Use the standard table (`Requirement | Summary | Components | Interfaces | Flows`) to prove coverage.
+- Collapse to bullet form only when a single requirement maps 1:1 to a component.
+- Prefer the component summary table for simple mappings; reserve the full traceability table for complex or compliance-sensitive requirements.
+- Re-run this mapping whenever requirements or components change to avoid drift.
+
+### Components & Interfaces Authoring
+- Group components by domain/layer and provide one block per component.
+- Begin with a summary table listing Component, Domain, Intent, Requirement coverage, key dependencies, and selected contracts.
+- Table fields: Intent (one line), Requirements (`2.1, 2.3`), Owner/Reviewers (optional).
+- Dependencies table must mark each entry as Inbound/Outbound/External and assign Criticality (`P0` blocking, `P1` high-risk, `P2` informational).
+- Summaries of external dependency research stay here; detailed investigation (API signatures, rate limits, migration notes) belongs in `research.md`.
+- design.md must remain a self-contained reviewer artifact. Reference `research.md` only for background, and restate any conclusions or decisions here.
+- Contracts: tick only the relevant types (Service/API/Event/Batch/State). Unchecked types should not appear later in the component section.
+- Service interfaces must declare method signatures, inputs/outputs, and error envelopes. API/Event/Batch contracts require schema tables or bullet lists covering trigger, payload, delivery, idempotency.
+- Use **Integration & Migration Notes**, **Validation Hooks**, and **Open Questions / Risks** to document rollout strategy, observability, and unresolved decisions.
+- Detail density rules:
+  - **Full block**: components introducing new boundaries (logic hooks, shared services, external integrations, data layers).
+  - **Summary-only**: presentational/UI components with no new boundaries (plus a short Implementation Note if needed).
+- Implementation Notes must combine Integration / Validation / Risks into a single bulleted subsection to reduce repetition.
+- Prefer lists or inline descriptors for short data (dependencies, contract selections). Use tables only when comparing multiple items.
+
+### Shared Interfaces & Props
+- Define a base interface (e.g., `BaseUIPanelProps`) for recurring UI components and extend it per component to capture only the deltas.
+- Hooks, utilities, and integration adapters that introduce new contracts should still include full TypeScript signatures.
+- When reusing a base contract, reference it explicitly (e.g., “Extends `BaseUIPanelProps` with `onSubmitAnswer` callback”) instead of duplicating the code block.
+
+### Data Models
+- Domain Model covers aggregates, entities, value objects, domain events, and invariants. Add Mermaid diagrams only when relationships are non-trivial.
+- Logical Data Model should articulate structure, indexing, sharding, and storage-specific considerations (event store, KV/wide-column) relevant to the change.
+- Data Contracts & Integration section documents API payloads, event schemas, and cross-service synchronization patterns when the feature crosses boundaries.
+- Lengthy type definitions or vendor-specific option objects should be placed in the Supporting References section within design.md, linked from the relevant section. Investigation notes stay in `research.md`.
+- Supporting References usage is optional; only create it when keeping the content in the main body would reduce readability. All decisions must still appear in the main sections so design.md stands alone.
+
+### Error/Testing/Security/Performance Sections
+- Record only feature-specific decisions or deviations. Link or reference organization-wide standards (steering) for baseline practices instead of restating them.
+
+### Diagram & Text Deduplication
+- Do not restate diagram content verbatim in prose. Use the text to highlight key decisions, trade-offs, or impacts that are not obvious from the visual.
+- When a decision is fully captured in the diagram annotations, a short “Key Decisions” bullet is sufficient.
+
+### General Deduplication
+- Avoid repeating the same information across Overview, Architecture, and Components. Reference earlier sections when context is identical.
+- If a requirement/component relationship is captured in the summary table, do not rewrite it elsewhere unless extra nuance is added.
+
+## Diagram Guidelines
+
+### When to include a diagram
+- **Architecture**: Use a structural diagram when 3+ components or external systems interact.
+- **Sequence**: Draw a sequence diagram when calls/handshakes span multiple steps.
+- **State / Flow**: Capture complex state machines or business flows in a dedicated diagram.
+- **ER**: Provide an entity-relationship diagram for non-trivial data models.
+- **Skip**: Minor one-component changes generally do not need diagrams.
+
+### Mermaid requirements
+```mermaid
+graph TB
+    Client --> ApiGateway
+    ApiGateway --> ServiceA
+    ApiGateway --> ServiceB
+    ServiceA --> Database
+```
+
+- **Plain Mermaid only** – avoid custom styling or unsupported syntax.
+- **Node IDs** – alphanumeric plus underscores only (e.g., `Client`, `ServiceA`). Do not use `@`, `/`, or leading `-`.
+- **Labels** – simple words. Do not embed parentheses `()`, square brackets `[]`, quotes `"`, or slashes `/`.
+  - ❌ `DnD[@dnd-kit/core]` → invalid ID (`@`).
+  - ❌ `UI[KanbanBoard(React)]` → invalid label (`()`).
+  - ✅ `DndKit[dnd-kit core]` → use plain text in labels, keep technology details in the accompanying description.
+  - ℹ️ Mermaid strict-mode will otherwise fail with errors like `Expecting 'SQE' ... got 'PS'`; remove punctuation from labels before rendering.
+- **Edges** – show data or control flow direction.
+- **Groups** – using Mermaid subgraphs to cluster related components is allowed; use it sparingly for clarity.
+
+## Quality Metrics
+### Design Completeness Checklist
+- All requirements addressed
+- No implementation details leaked
+- Clear component boundaries
+- Explicit error handling
+- Comprehensive test strategy
+- Security considered
+- Performance targets defined
+- Migration path clear (if applicable)
+
+### Common Anti-patterns to Avoid
+❌ Mixing design with implementation
+❌ Vague interface definitions
+❌ Missing error scenarios
+❌ Ignored non-functional requirements
+❌ Overcomplicated architectures
+❌ Tight coupling between components
+❌ Missing data consistency strategy
+❌ Incomplete dependency analysis

.kiro/settings/rules/design-review.md

@@ -0,0 +1,110 @@
+# Design Review Process
+
+## Objective
+Conduct interactive quality review of technical design documents to ensure they are solid enough to proceed to implementation with acceptable risk.
+
+## Review Philosophy
+- **Quality assurance, not perfection seeking**
+- **Critical focus**: Limit to 3 most important concerns
+- **Interactive dialogue**: Engage with designer, not one-way evaluation
+- **Balanced assessment**: Recognize strengths and weaknesses
+- **Clear decision**: Definitive GO/NO-GO with rationale
+
+## Scope & Non-Goals
+
+- Scope: Evaluate the quality of the design document against project context and standards to decide GO/NO-GO.
+- Non-Goals: Do not perform implementation-level design, deep technology research, or finalize technology choices. Defer such items to the design phase iteration.
+
+## Core Review Criteria
+
+### 1. Existing Architecture Alignment (Critical)
+- Integration with existing system boundaries and layers
+- Consistency with established architectural patterns
+- Proper dependency direction and coupling management
+- Alignment with current module organization
+
+### 2. Design Consistency & Standards
+- Adherence to project naming conventions and code standards
+- Consistent error handling and logging strategies
+- Uniform configuration and dependency management
+- Alignment with established data modeling patterns
+
+### 3. Extensibility & Maintainability
+- Design flexibility for future requirements
+- Clear separation of concerns and single responsibility
+- Testability and debugging considerations
+- Appropriate complexity for requirements
+
+### 4. Type Safety & Interface Design
+- Proper type definitions and interface contracts
+- Avoidance of unsafe patterns (e.g., `any` in TypeScript)
+- Clear API boundaries and data structures
+- Input validation and error handling coverage
+
+## Review Process
+
+### Step 1: Analyze
+Analyze design against all review criteria, focusing on critical issues impacting integration, maintainability, complexity, and requirements fulfillment.
+
+### Step 2: Identify Critical Issues (≤3)
+For each issue:
+```
+🔴 **Critical Issue [1-3]**: [Brief title]
+**Concern**: [Specific problem]
+**Impact**: [Why it matters]
+**Suggestion**: [Concrete improvement]
+**Traceability**: [Requirement ID/section from requirements.md]
+**Evidence**: [Design doc section/heading]
+```
+
+### Step 3: Recognize Strengths
+Acknowledge 1-2 strong aspects to maintain balanced feedback.
+
+### Step 4: Decide GO/NO-GO
+- **GO**: No critical architectural misalignment, requirements addressed, clear implementation path, acceptable risks
+- **NO-GO**: Fundamental conflicts, critical gaps, high failure risk, disproportionate complexity
+
+## Traceability & Evidence
+
+- Link each critical issue to the relevant requirement(s) from `requirements.md` (ID or section).
+- Cite evidence locations in the design document (section/heading, diagram, or artifact) to support the assessment.
+- When applicable, reference constraints from steering context to justify the issue.
+
+## Output Format
+
+### Design Review Summary
+2-3 sentences on overall quality and readiness.
+
+### Critical Issues (≤3)
+For each: Issue, Impact, Recommendation, Traceability (e.g., 1.1, 1.2), Evidence (design.md section).
+
+### Design Strengths
+1-2 positive aspects.
+
+### Final Assessment
+Decision (GO/NO-GO), Rationale (1-2 sentences), Next Steps.
+
+### Interactive Discussion
+Engage on designer's perspective, alternatives, clarifications, and necessary changes.
+
+## Length & Focus
+
+- Summary: 2–3 sentences
+- Each critical issue: 5–7 lines total (including Issue/Impact/Recommendation/Traceability/Evidence)
+- Overall review: keep concise (~400 words guideline)
+
+## Review Guidelines
+
+1. **Critical Focus**: Only flag issues that significantly impact success
+2. **Constructive Tone**: Provide solutions, not just criticism
+3. **Interactive Approach**: Engage in dialogue rather than one-way evaluation
+4. **Balanced Assessment**: Recognize both strengths and weaknesses
+5. **Clear Decision**: Make definitive GO/NO-GO recommendation
+6. **Actionable Feedback**: Ensure all suggestions are implementable
+
+## Final Checklist
+
+- **Critical Issues ≤ 3** and each includes Impact and Recommendation
+- **Traceability**: Each issue references requirement ID/section
+- **Evidence**: Each issue cites design doc location
+- **Decision**: GO/NO-GO with clear rationale and next steps

.kiro/settings/rules/ears-format.md

@@ -0,0 +1,49 @@
+# EARS Format Guidelines
+
+## Overview
+EARS (Easy Approach to Requirements Syntax) is the standard format for acceptance criteria in spec-driven development.
+
+EARS patterns describe the logical structure of a requirement (condition + subject + response) and are not tied to any particular natural language.  
+All acceptance criteria should be written in the target language configured for the specification (for example, `spec.json.language` / `en`).  
+Keep EARS trigger keywords and fixed phrases in English (`When`, `If`, `While`, `Where`, `The system shall`, `The [system] shall`) and localize only the variable parts (`[event]`, `[precondition]`, `[trigger]`, `[feature is included]`, `[response/action]`) into the target language. Do not interleave target-language text inside the trigger or fixed English phrases themselves.
+
+## Primary EARS Patterns
+
+### 1. Event-Driven Requirements
+- **Pattern**: When [event], the [system] shall [response/action]
+- **Use Case**: Responses to specific events or triggers
+- **Example**: When user clicks checkout button, the Checkout Service shall validate cart contents
+
+### 2. State-Driven Requirements
+- **Pattern**: While [precondition], the [system] shall [response/action]
+- **Use Case**: Behavior dependent on system state or preconditions
+- **Example**: While payment is processing, the Checkout Service shall display loading indicator
+
+### 3. Unwanted Behavior Requirements
+- **Pattern**: If [trigger], the [system] shall [response/action]
+- **Use Case**: System response to errors, failures, or undesired situations
+- **Example**: If invalid credit card number is entered, then the website shall display error message
+
+### 4. Optional Feature Requirements
+- **Pattern**: Where [feature is included], the [system] shall [response/action]
+- **Use Case**: Requirements for optional or conditional features
+- **Example**: Where the car has a sunroof, the car shall have a sunroof control panel
+
+### 5. Ubiquitous Requirements
+- **Pattern**: The [system] shall [response/action]
+- **Use Case**: Always-active requirements and fundamental system properties
+- **Example**: The mobile phone shall have a mass of less than 100 grams
+
+## Combined Patterns
+- While [precondition], when [event], the [system] shall [response/action]
+- When [event] and [additional condition], the [system] shall [response/action]
+
+## Subject Selection Guidelines
+- **Software Projects**: Use concrete system/service name (e.g., "Checkout Service", "User Auth Module")
+- **Process/Workflow**: Use responsible team/role (e.g., "Support Team", "Review Process")
+- **Non-Software**: Use appropriate subject (e.g., "Marketing Campaign", "Documentation")
+
+## Quality Criteria
+- Requirements must be testable, verifiable, and describe a single behavior.
+- Use objective language: "shall" for mandatory behavior, "should" for recommendations; avoid ambiguous terms.
+- Follow EARS syntax: [condition], the [system] shall [response/action].

.kiro/settings/rules/gap-analysis.md

@@ -0,0 +1,144 @@
+# Gap Analysis Process
+
+## Objective
+Analyze the gap between requirements and existing codebase to inform implementation strategy decisions.
+
+## Analysis Framework
+
+### 1. Current State Investigation
+
+- Scan for domain-related assets:
+  - Key files/modules and directory layout
+  - Reusable components/services/utilities
+  - Dominant architecture patterns and constraints
+
+- Extract conventions:
+  - Naming, layering, dependency direction
+  - Import/export patterns and dependency hotspots
+  - Testing placement and approach
+
+- Note integration surfaces:
+  - Data models/schemas, API clients, auth mechanisms
+
+### 2. Requirements Feasibility Analysis
+
+- From EARS requirements, list technical needs:
+  - Data models, APIs/services, UI/components
+  - Business rules/validation
+  - Non-functionals: security, performance, scalability, reliability
+
+- Identify gaps and constraints:
+  - Missing capabilities in current codebase
+  - Unknowns to be researched later (mark as "Research Needed")
+  - Constraints from existing architecture and patterns
+
+- Note complexity signals:
+  - Simple CRUD / algorithmic logic / workflows / external integrations
+
+### 3. Implementation Approach Options
+
+#### Option A: Extend Existing Components
+**When to consider**: Feature fits naturally into existing structure
+
+- **Which files/modules to extend**:
+  - Identify specific files requiring changes
+  - Assess impact on existing functionality
+  - Evaluate backward compatibility concerns
+
+- **Compatibility assessment**:
+  - Check if extension respects existing interfaces
+  - Verify no breaking changes to consumers
+  - Assess test coverage impact
+
+- **Complexity and maintainability**:
+  - Evaluate cognitive load of additional functionality
+  - Check if single responsibility principle is maintained
+  - Assess if file size remains manageable
+
+**Trade-offs**:
+- ✅ Minimal new files, faster initial development
+- ✅ Leverages existing patterns and infrastructure
+- ❌ Risk of bloating existing components
+- ❌ May complicate existing logic
+
+#### Option B: Create New Components
+**When to consider**: Feature has distinct responsibility or existing components are already complex
+
+- **Rationale for new creation**:
+  - Clear separation of concerns justifies new file
+  - Existing components are already complex
+  - Feature has distinct lifecycle or dependencies
+
+- **Integration points**:
+  - How new components connect to existing system
+  - APIs or interfaces exposed
+  - Dependencies on existing components
+
+- **Responsibility boundaries**:
+  - Clear definition of what new component owns
+  - Interfaces with existing components
+  - Data flow and control flow
+
+**Trade-offs**:
+- ✅ Clean separation of concerns
+- ✅ Easier to test in isolation
+- ✅ Reduces complexity in existing components
+- ❌ More files to navigate
+- ❌ Requires careful interface design
+
+#### Option C: Hybrid Approach
+**When to consider**: Complex features requiring both extension and new creation
+
+- **Combination strategy**:
+  - Which parts extend existing components
+  - Which parts warrant new components
+  - How they interact
+
+- **Phased implementation**:
+  - Initial phase: minimal viable changes
+  - Subsequent phases: refactoring or new components
+  - Migration strategy if needed
+
+- **Risk mitigation**:
+  - Incremental rollout approach
+  - Feature flags or configuration
+  - Rollback strategy
+
+**Trade-offs**:
+- ✅ Balanced approach for complex features
+- ✅ Allows iterative refinement
+- ❌ More complex planning required
+- ❌ Potential for inconsistency if not well-coordinated
+### 4. Out-of-Scope for Gap Analysis
+
+- Defer deep research activities to the design phase.
+- Record unknowns as concise "Research Needed" items only.
+
+### 5. Implementation Complexity & Risk
+
+  - Effort:
+    - S (1–3 days): existing patterns, minimal deps, straightforward integration
+    - M (3–7 days): some new patterns/integrations, moderate complexity
+    - L (1–2 weeks): significant functionality, multiple integrations or workflows
+    - XL (2+ weeks): architectural changes, unfamiliar tech, broad impact
+  - Risk:
+    - High: unknown tech, complex integrations, architectural shifts, unclear perf/security path
+    - Medium: new patterns with guidance, manageable integrations, known perf solutions
+    - Low: extend established patterns, familiar tech, clear scope, minimal integration
+
+### Output Checklist
+
+- Requirement-to-Asset Map with gaps tagged (Missing / Unknown / Constraint)
+- Options A/B/C with short rationale and trade-offs
+- Effort (S/M/L/XL) and Risk (High/Medium/Low) with one-line justification each
+- Recommendations for design phase:
+  - Preferred approach and key decisions
+  - Research items to carry forward
+
+## Principles
+
+- **Information over decisions**: Provide analysis and options, not final choices
+- **Multiple viable options**: Offer credible alternatives when applicable
+- **Explicit gaps and assumptions**: Flag unknowns and constraints clearly
+- **Context-aware**: Align with existing patterns and architecture limits
+- **Transparent effort and risk**: Justify labels succinctly

.kiro/settings/rules/steering-principles.md

@@ -0,0 +1,90 @@
+# Steering Principles
+
+Steering files are **project memory**, not exhaustive specifications.
+
+---
+
+## Content Granularity
+
+### Golden Rule
+> "If new code follows existing patterns, steering shouldn't need updating."
+
+### ✅ Document
+- Organizational patterns (feature-first, layered)
+- Naming conventions (PascalCase rules)
+- Import strategies (absolute vs relative)
+- Architectural decisions (state management)
+- Technology standards (key frameworks)
+
+### ❌ Avoid
+- Complete file listings
+- Every component description
+- All dependencies
+- Implementation details
+- Agent-specific tooling directories (e.g. `.cursor/`, `.gemini/`, `.claude/`)
+- Detailed documentation of `.kiro/` metadata directories (settings, automation)
+
+### Example Comparison
+
+**Bad** (Specification-like):
+```markdown
+- /components/Button.tsx - Primary button with variants
+- /components/Input.tsx - Text input with validation
+- /components/Modal.tsx - Modal dialog
+... (50+ files)
+```
+
+**Good** (Project Memory):
+```markdown
+## UI Components (`/components/ui/`)
+Reusable, design-system aligned primitives
+- Named by function (Button, Input, Modal)
+- Export component + TypeScript interface
+- No business logic
+```
+
+---
+
+## Security
+
+Never include:
+- API keys, passwords, credentials
+- Database URLs, internal IPs
+- Secrets or sensitive data
+
+---
+
+## Quality Standards
+
+- **Single domain**: One topic per file
+- **Concrete examples**: Show patterns with code
+- **Explain rationale**: Why decisions were made
+- **Maintainable size**: 100-200 lines typical
+
+---
+
+## Preservation (when updating)
+
+- Preserve user sections and custom examples
+- Additive by default (add, don't replace)
+- Add `updated_at` timestamp
+- Note why changes were made
+
+---
+
+## Notes
+
+- Templates are starting points, customize as needed
+- Follow same granularity principles as core steering
+- All steering files loaded as project memory
+- Light references to `.kiro/specs/` and `.kiro/steering/` are acceptable; avoid other `.kiro/` directories
+- Custom files equally important as core files
+
+---
+
+## File-Specific Focus
+
+- **product.md**: Purpose, value, business context (not exhaustive features)
+- **tech.md**: Key frameworks, standards, conventions (not all dependencies)
+- **structure.md**: Organization patterns, naming rules (not directory trees)
+- **Custom files**: Specialized patterns (API, testing, security, etc.)

.kiro/settings/rules/tasks-generation.md

@@ -0,0 +1,131 @@
+# Task Generation Rules
+
+## Core Principles
+
+### 1. Natural Language Descriptions
+Focus on capabilities and outcomes, not code structure.
+
+**Describe**:
+- What functionality to achieve
+- Business logic and behavior
+- Features and capabilities
+- Domain language and concepts
+- Data relationships and workflows
+
+**Avoid**:
+- File paths and directory structure
+- Function/method names and signatures
+- Type definitions and interfaces
+- Class names and API contracts
+- Specific data structures
+
+**Rationale**: Implementation details (files, methods, types) are defined in design.md. Tasks describe the functional work to be done.
+
+### 2. Task Integration & Progression
+
+**Every task must**:
+- Build on previous outputs (no orphaned code)
+- Connect to the overall system (no hanging features)
+- Progress incrementally (no big jumps in complexity)
+- Validate core functionality early in sequence
+- Respect architecture boundaries defined in design.md (Architecture Pattern & Boundary Map)
+- Honor interface contracts documented in design.md
+- Use major task summaries sparingly—omit detail bullets if the work is fully captured by child tasks.
+
+**End with integration tasks** to wire everything together.
+
+### 3. Flexible Task Sizing
+
+**Guidelines**:
+- **Major tasks**: As many sub-tasks as logically needed (group by cohesion)
+- **Sub-tasks**: 1-3 hours each, 3-10 details per sub-task
+- Balance between too granular and too broad
+
+**Don't force arbitrary numbers** - let logical grouping determine structure.
+
+### 4. Requirements Mapping
+
+**End each task detail section with**:
+- `_Requirements: X.X, Y.Y_` listing **only numeric requirement IDs** (comma-separated). Never append descriptive text, parentheses, translations, or free-form labels.
+- For cross-cutting requirements, list every relevant requirement ID. All requirements MUST have numeric IDs in requirements.md. If an ID is missing, stop and correct requirements.md before generating tasks.
+- Reference components/interfaces from design.md when helpful (e.g., `_Contracts: AuthService API`)
+
+### 5. Code-Only Focus
+
+**Include ONLY**:
+- Coding tasks (implementation)
+- Testing tasks (unit, integration, E2E)
+- Technical setup tasks (infrastructure, configuration)
+
+**Exclude**:
+- Deployment tasks
+- Documentation tasks
+- User testing
+- Marketing/business activities
+
+### Optional Test Coverage Tasks
+
+- When the design already guarantees functional coverage and rapid MVP delivery is prioritized, mark purely test-oriented follow-up work (e.g., baseline rendering/unit tests) as **optional** using the `- [ ]*` checkbox form.
+- Only apply the optional marker when the sub-task directly references acceptance criteria from requirements.md in its detail bullets.
+- Never mark implementation work or integration-critical verification as optional—reserve `*` for auxiliary/deferrable test coverage that can be revisited post-MVP.
+
+## Task Hierarchy Rules
+
+### Maximum 2 Levels
+- **Level 1**: Major tasks (1, 2, 3, 4...)
+- **Level 2**: Sub-tasks (1.1, 1.2, 2.1, 2.2...)
+- **No deeper nesting** (no 1.1.1)
+- If a major task would contain only a single actionable item, collapse the structure and promote the sub-task to the major level (e.g., replace `1.1` with `1.`).
+- When a major task exists purely as a container, keep the checkbox description concise and avoid duplicating detailed bullets—reserve specifics for its sub-tasks.
+
+### Sequential Numbering
+- Major tasks MUST increment: 1, 2, 3, 4, 5...
+- Sub-tasks reset per major task: 1.1, 1.2, then 2.1, 2.2...
+- Never repeat major task numbers
+
+### Parallel Analysis (default)
+- Assume parallel analysis is enabled unless explicitly disabled (e.g. `--sequential` flag).
+- Identify tasks that can run concurrently when **all** conditions hold:
+  - No data dependency on other pending tasks
+  - No shared file or resource contention
+  - No prerequisite review/approval from another task
+- Validate that identified parallel tasks operate within separate boundaries defined in the Architecture Pattern & Boundary Map.
+- Confirm API/event contracts from design.md do not overlap in ways that cause conflicts.
+- Append `(P)` immediately after the task number for each parallel-capable task:
+  - Example: `- [ ] 2.1 (P) Build background worker`
+  - Apply to both major tasks and sub-tasks when appropriate.
+- If sequential mode is requested, omit `(P)` markers entirely.
+- Group parallel tasks logically (same parent when possible) and highlight any ordering caveats in detail bullets.
+- Explicitly call out dependencies that prevent `(P)` even when tasks look similar.
+
+### Checkbox Format
+```markdown
+- [ ] 1. Major task description
+- [ ] 1.1 Sub-task description
+  - Detail item 1
+  - Detail item 2
+  - _Requirements: X.X_
+
+- [ ] 1.2 Sub-task description
+  - Detail items...
+  - _Requirements: Y.Y_
+
+- [ ] 1.3 Sub-task description
+  - Detail items...
+  - _Requirements: Z.Z, W.W_
+
+- [ ] 2. Next major task (NOT 1 again!)
+- [ ] 2.1 Sub-task...
+```
+
+## Requirements Coverage
+
+**Mandatory Check**:
+- ALL requirements from requirements.md MUST be covered
+- Cross-reference every requirement ID with task mappings
+- If gaps found: Return to requirements or design phase
+- No requirement should be left without corresponding tasks
+
+Use `N.M`-style numeric requirement IDs where `N` is the top-level requirement number from requirements.md (for example, Requirement 1 → 1.1, 1.2; Requirement 2 → 2.1, 2.2), and `M` is a local index within that requirement group.
+
+Document any intentionally deferred requirements with rationale.

.kiro/settings/rules/tasks-parallel-analysis.md

@@ -0,0 +1,34 @@
+# Parallel Task Analysis Rules
+
+## Purpose
+Provide a consistent way to identify implementation tasks that can be safely executed in parallel while generating `tasks.md`.
+
+## When to Consider Tasks Parallel
+Only mark a task as parallel-capable when **all** of the following are true:
+
+1. **No data dependency** on pending tasks.
+2. **No conflicting files or shared mutable resources** are touched.
+3. **No prerequisite review/approval** from another task is required beforehand.
+4. **Environment/setup work** needed by this task is already satisfied or covered within the task itself.
+
+## Marking Convention
+- Append `(P)` immediately after the numeric identifier for each qualifying task.
+  - Example: `- [ ] 2.1 (P) Build background worker for emails`
+- Apply `(P)` to both major tasks and sub-tasks when appropriate.
+- If sequential execution is requested (e.g. via `--sequential` flag), omit `(P)` markers entirely.
+- Keep `(P)` **outside** of checkbox brackets to avoid confusion with completion state.
+
+## Grouping & Ordering Guidelines
+- Group parallel tasks under the same parent whenever the work belongs to the same theme.
+- List obvious prerequisites or caveats in the detail bullets (e.g., "Requires schema migration from 1.2").
+- When two tasks look similar but are not parallel-safe, call out the blocking dependency explicitly.
+- Skip marking container-only major tasks (those without their own actionable detail bullets) with `(P)`—evaluate parallel execution at the sub-task level instead.
+
+## Quality Checklist
+Before marking a task with `(P)`, ensure you have:
+
+- Verified that running this task concurrently will not create merge or deployment conflicts.
+- Captured any shared state expectations in the detail bullets.
+- Confirmed that the implementation can be tested independently.
+
+If any check fails, **do not** mark the task with `(P)` and explain the dependency in the task details.

.kiro/settings/templates/specs/design.md

@@ -0,0 +1,276 @@
+# Design Document Template
+
+---
+**Purpose**: Provide sufficient detail to ensure implementation consistency across different implementers, preventing interpretation drift.
+
+**Approach**:
+- Include essential sections that directly inform implementation decisions
+- Omit optional sections unless critical to preventing implementation errors
+- Match detail level to feature complexity
+- Use diagrams and tables over lengthy prose
+
+**Warning**: Approaching 1000 lines indicates excessive feature complexity that may require design simplification.
+---
+
+> Sections may be reordered (e.g., surfacing Requirements Traceability earlier or moving Data Models nearer Architecture) when it improves clarity. Within each section, keep the flow **Summary → Scope → Decisions → Impacts/Risks** so reviewers can scan consistently.
+
+## Overview 
+2-3 paragraphs max
+**Purpose**: This feature delivers [specific value] to [target users].
+**Users**: [Target user groups] will utilize this for [specific workflows].
+**Impact** (if applicable): Changes the current [system state] by [specific modifications].
+
+
+### Goals
+- Primary objective 1
+- Primary objective 2  
+- Success criteria
+
+### Non-Goals
+- Explicitly excluded functionality
+- Future considerations outside current scope
+- Integration points deferred
+
+## Architecture
+
+> Reference detailed discovery notes in `research.md` only for background; keep design.md self-contained for reviewers by capturing all decisions and contracts here.
+> Capture key decisions in text and let diagrams carry structural detail—avoid repeating the same information in prose.
+
+### Existing Architecture Analysis (if applicable)
+When modifying existing systems:
+- Current architecture patterns and constraints
+- Existing domain boundaries to be respected
+- Integration points that must be maintained
+- Technical debt addressed or worked around
+
+### Architecture Pattern & Boundary Map
+**RECOMMENDED**: Include Mermaid diagram showing the chosen architecture pattern and system boundaries (required for complex features, optional for simple additions)
+
+**Architecture Integration**:
+- Selected pattern: [name and brief rationale]
+- Domain/feature boundaries: [how responsibilities are separated to avoid conflicts]
+- Existing patterns preserved: [list key patterns]
+- New components rationale: [why each is needed]
+- Steering compliance: [principles maintained]
+
+### Technology Stack
+
+| Layer | Choice / Version | Role in Feature | Notes |
+|-------|------------------|-----------------|-------|
+| Frontend / CLI | | | |
+| Backend / Services | | | |
+| Data / Storage | | | |
+| Messaging / Events | | | |
+| Infrastructure / Runtime | | | |
+
+> Keep rationale concise here and, when more depth is required (trade-offs, benchmarks), add a short summary plus pointer to the Supporting References section and `research.md` for raw investigation notes.
+
+## System Flows
+
+Provide only the diagrams needed to explain non-trivial flows. Use pure Mermaid syntax. Common patterns:
+- Sequence (multi-party interactions)
+- Process / state (branching logic or lifecycle)
+- Data / event flow (pipelines, async messaging)
+
+Skip this section entirely for simple CRUD changes.
+> Describe flow-level decisions (e.g., gating conditions, retries) briefly after the diagram instead of restating each step.
+
+## Requirements Traceability
+
+Use this section for complex or compliance-sensitive features where requirements span multiple domains. Straightforward 1:1 mappings can rely on the Components summary table.
+
+Map each requirement ID (e.g., `2.1`) to the design elements that realize it.
+
+| Requirement | Summary | Components | Interfaces | Flows |
+|-------------|---------|------------|------------|-------|
+| 1.1 | | | | |
+| 1.2 | | | | |
+
+> Omit this section only when a single component satisfies a single requirement without cross-cutting concerns.
+
+## Components and Interfaces
+
+Provide a quick reference before diving into per-component details.
+
+- Summaries can be a table or compact list. Example table:
+  | Component | Domain/Layer | Intent | Req Coverage | Key Dependencies (P0/P1) | Contracts |
+  |-----------|--------------|--------|--------------|--------------------------|-----------|
+  | ExampleComponent | UI | Displays XYZ | 1, 2 | GameProvider (P0), MapPanel (P1) | Service, State |
+- Only components introducing new boundaries (e.g., logic hooks, external integrations, persistence) require full detail blocks. Simple presentation components can rely on the summary row plus a short Implementation Note.
+
+Group detailed blocks by domain or architectural layer. For each detailed component, list requirement IDs as `2.1, 2.3` (omit “Requirement”). When multiple UI components share the same contract, reference a base interface/props definition instead of duplicating code blocks.
+
+### [Domain / Layer]
+
+#### [Component Name]
+
+| Field | Detail |
+|-------|--------|
+| Intent | 1-line description of the responsibility |
+| Requirements | 2.1, 2.3 |
+| Owner / Reviewers | (optional) |
+
+**Responsibilities & Constraints**
+- Primary responsibility
+- Domain boundary and transaction scope
+- Data ownership / invariants
+
+**Dependencies**
+- Inbound: Component/service name — purpose (Criticality)
+- Outbound: Component/service name — purpose (Criticality)
+- External: Service/library — purpose (Criticality)
+
+Summarize external dependency findings here; deeper investigation (API signatures, rate limits, migration notes) lives in `research.md`.
+
+**Contracts**: Service [ ] / API [ ] / Event [ ] / Batch [ ] / State [ ]  ← check only the ones that apply.
+
+##### Service Interface
+```typescript
+interface [ComponentName]Service {
+  methodName(input: InputType): Result<OutputType, ErrorType>;
+}
+```
+- Preconditions:
+- Postconditions:
+- Invariants:
+
+##### API Contract
+| Method | Endpoint | Request | Response | Errors |
+|--------|----------|---------|----------|--------|
+| POST | /api/resource | CreateRequest | Resource | 400, 409, 500 |
+
+##### Event Contract
+- Published events:  
+- Subscribed events:  
+- Ordering / delivery guarantees:
+
+##### Batch / Job Contract
+- Trigger:  
+- Input / validation:  
+- Output / destination:  
+- Idempotency & recovery:
+
+##### State Management
+- State model:  
+- Persistence & consistency:  
+- Concurrency strategy:
+
+**Implementation Notes**
+- Integration: 
+- Validation: 
+- Risks:
+
+## Data Models
+
+Focus on the portions of the data landscape that change with this feature.
+
+### Domain Model
+- Aggregates and transactional boundaries
+- Entities, value objects, domain events
+- Business rules & invariants
+- Optional Mermaid diagram for complex relationships
+
+### Logical Data Model
+
+**Structure Definition**:
+- Entity relationships and cardinality
+- Attributes and their types
+- Natural keys and identifiers
+- Referential integrity rules
+
+**Consistency & Integrity**:
+- Transaction boundaries
+- Cascading rules
+- Temporal aspects (versioning, audit)
+
+### Physical Data Model
+**When to include**: When implementation requires specific storage design decisions
+
+**For Relational Databases**:
+- Table definitions with data types
+- Primary/foreign keys and constraints
+- Indexes and performance optimizations
+- Partitioning strategy for scale
+
+**For Document Stores**:
+- Collection structures
+- Embedding vs referencing decisions
+- Sharding key design
+- Index definitions
+
+**For Event Stores**:
+- Event schema definitions
+- Stream aggregation strategies
+- Snapshot policies
+- Projection definitions
+
+**For Key-Value/Wide-Column Stores**:
+- Key design patterns
+- Column families or value structures
+- TTL and compaction strategies
+
+### Data Contracts & Integration
+
+**API Data Transfer**
+- Request/response schemas
+- Validation rules
+- Serialization format (JSON, Protobuf, etc.)
+
+**Event Schemas**
+- Published event structures
+- Schema versioning strategy
+- Backward/forward compatibility rules
+
+**Cross-Service Data Management**
+- Distributed transaction patterns (Saga, 2PC)
+- Data synchronization strategies
+- Eventual consistency handling
+
+Skip subsections that are not relevant to this feature.
+
+## Error Handling
+
+### Error Strategy
+Concrete error handling patterns and recovery mechanisms for each error type.
+
+### Error Categories and Responses
+**User Errors** (4xx): Invalid input → field-level validation; Unauthorized → auth guidance; Not found → navigation help
+**System Errors** (5xx): Infrastructure failures → graceful degradation; Timeouts → circuit breakers; Exhaustion → rate limiting  
+**Business Logic Errors** (422): Rule violations → condition explanations; State conflicts → transition guidance
+
+**Process Flow Visualization** (when complex business logic exists):
+Include Mermaid flowchart only for complex error scenarios with business workflows.
+
+### Monitoring
+Error tracking, logging, and health monitoring implementation.
+
+## Testing Strategy
+
+### Default sections (adapt names/sections to fit the domain)
+- Unit Tests: 3–5 items from core functions/modules (e.g., auth methods, subscription logic)
+- Integration Tests: 3–5 cross-component flows (e.g., webhook handling, notifications)
+- E2E/UI Tests (if applicable): 3–5 critical user paths (e.g., forms, dashboards)
+- Performance/Load (if applicable): 3–4 items (e.g., concurrency, high-volume ops)
+
+## Optional Sections (include when relevant)
+
+### Security Considerations
+_Use this section for features handling auth, sensitive data, external integrations, or user permissions. Capture only decisions unique to this feature; defer baseline controls to steering docs._
+- Threat modeling, security controls, compliance requirements
+- Authentication and authorization patterns
+- Data protection and privacy considerations
+
+### Performance & Scalability
+_Use this section when performance targets, high load, or scaling concerns exist. Record only feature-specific targets or trade-offs and rely on steering documents for general practices._
+- Target metrics and measurement strategies
+- Scaling approaches (horizontal/vertical)
+- Caching strategies and optimization techniques
+
+### Migration Strategy
+Include a Mermaid flowchart showing migration phases when schema/data movement is required.
+- Phase breakdown, rollback triggers, validation checkpoints
+
+## Supporting References (Optional)
+- Create this section only when keeping the information in the main body would hurt readability (e.g., very long TypeScript definitions, vendor option matrices, exhaustive schema tables). Keep decision-making context in the main sections so the design stays self-contained.
+- Link to the supporting references from the main text instead of inlining large snippets.
+- Background research notes and comparisons continue to live in `research.md`, but their conclusions must be summarized in the main design.

.kiro/settings/templates/specs/init.json

@@ -0,0 +1,22 @@
+{
+  "feature_name": "{{FEATURE_NAME}}",
+  "created_at": "{{TIMESTAMP}}",
+  "updated_at": "{{TIMESTAMP}}",
+  "language": "en",
+  "phase": "initialized",
+  "approvals": {
+    "requirements": {
+      "generated": false,
+      "approved": false
+    },
+    "design": {
+      "generated": false,
+      "approved": false
+    },
+    "tasks": {
+      "generated": false,
+      "approved": false
+    }
+  },
+  "ready_for_implementation": false
+}

.kiro/settings/templates/specs/requirements-init.md

@@ -0,0 +1,9 @@
+# Requirements Document
+
+## Project Description (Input)
+{{PROJECT_DESCRIPTION}}
+
+## Requirements
+<!-- Will be generated in /kiro:spec-requirements phase -->
+
+

.kiro/settings/templates/specs/requirements.md

@@ -0,0 +1,26 @@
+# Requirements Document
+
+## Introduction
+{{INTRODUCTION}}
+
+## Requirements
+
+### Requirement 1: {{REQUIREMENT_AREA_1}}
+<!-- Requirement headings MUST include a leading numeric ID only (for example: "Requirement 1: ...", "1. Overview", "2 Feature: ..."). Alphabetic IDs like "Requirement A" are not allowed. -->
+**Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
+
+#### Acceptance Criteria
+1. When [event], the [system] shall [response/action]
+2. If [trigger], then the [system] shall [response/action]
+3. While [precondition], the [system] shall [response/action]
+4. Where [feature is included], the [system] shall [response/action]
+5. The [system] shall [response/action]
+
+### Requirement 2: {{REQUIREMENT_AREA_2}}
+**Objective:** As a {{ROLE}}, I want {{CAPABILITY}}, so that {{BENEFIT}}
+
+#### Acceptance Criteria
+1. When [event], the [system] shall [response/action]
+2. When [event] and [condition], the [system] shall [response/action]
+
+<!-- Additional requirements follow the same pattern -->

.kiro/settings/templates/specs/research.md

@@ -0,0 +1,61 @@
+# Research & Design Decisions Template
+
+---
+**Purpose**: Capture discovery findings, architectural investigations, and rationale that inform the technical design.
+
+**Usage**:
+- Log research activities and outcomes during the discovery phase.
+- Document design decision trade-offs that are too detailed for `design.md`.
+- Provide references and evidence for future audits or reuse.
+---
+
+## Summary
+- **Feature**: `<feature-name>`
+- **Discovery Scope**: New Feature / Extension / Simple Addition / Complex Integration
+- **Key Findings**:
+  - Finding 1
+  - Finding 2
+  - Finding 3
+
+## Research Log
+Document notable investigation steps and their outcomes. Group entries by topic for readability.
+
+### [Topic or Question]
+- **Context**: What triggered this investigation?
+- **Sources Consulted**: Links, documentation, API references, benchmarks
+- **Findings**: Concise bullet points summarizing the insights
+- **Implications**: How this affects architecture, contracts, or implementation
+
+_Repeat the subsection for each major topic._
+
+## Architecture Pattern Evaluation
+List candidate patterns or approaches that were considered. Use the table format where helpful.
+
+| Option | Description | Strengths | Risks / Limitations | Notes |
+|--------|-------------|-----------|---------------------|-------|
+| Hexagonal | Ports & adapters abstraction around core domain | Clear boundaries, testable core | Requires adapter layer build-out | Aligns with existing steering principle X |
+
+## Design Decisions
+Record major decisions that influence `design.md`. Focus on choices with significant trade-offs.
+
+### Decision: `<Title>`
+- **Context**: Problem or requirement driving the decision
+- **Alternatives Considered**:
+  1. Option A — short description
+  2. Option B — short description
+- **Selected Approach**: What was chosen and how it works
+- **Rationale**: Why this approach fits the current project context
+- **Trade-offs**: Benefits vs. compromises
+- **Follow-up**: Items to verify during implementation or testing
+
+_Repeat the subsection for each decision._
+
+## Risks & Mitigations
+- Risk 1 — Proposed mitigation
+- Risk 2 — Proposed mitigation
+- Risk 3 — Proposed mitigation
+
+## References
+Provide canonical links and citations (official docs, standards, ADRs, internal guidelines).
+- [Title](https://example.com) — brief note on relevance
+- ...

.kiro/settings/templates/specs/tasks.md

@@ -0,0 +1,21 @@
+# Implementation Plan
+
+## Task Format Template
+
+Use whichever pattern fits the work breakdown:
+
+### Major task only
+- [ ] {{NUMBER}}. {{TASK_DESCRIPTION}}{{PARALLEL_MARK}}
+  - {{DETAIL_ITEM_1}} *(Include details only when needed. If the task stands alone, omit bullet items.)*
+  - _Requirements: {{REQUIREMENT_IDS}}_
+
+### Major + Sub-task structure
+- [ ] {{MAJOR_NUMBER}}. {{MAJOR_TASK_SUMMARY}}
+- [ ] {{MAJOR_NUMBER}}.{{SUB_NUMBER}} {{SUB_TASK_DESCRIPTION}}{{SUB_PARALLEL_MARK}}
+  - {{DETAIL_ITEM_1}}
+  - {{DETAIL_ITEM_2}}
+  - _Requirements: {{REQUIREMENT_IDS}}_ *(IDs only; do not add descriptions or parentheses.)*
+
+> **Parallel marker**: Append ` (P)` only to tasks that can be executed in parallel. Omit the marker when running in `--sequential` mode.
+>
+> **Optional test coverage**: When a sub-task is deferrable test work tied to acceptance criteria, mark the checkbox as `- [ ]*` and explain the referenced requirements in the detail bullets.

.kiro/settings/templates/steering-custom/api-standards.md

@@ -0,0 +1,69 @@
+# API Standards
+
+[Purpose: consistent API patterns for naming, structure, auth, versioning, and errors]
+
+## Philosophy
+- Prefer predictable, resource-oriented design
+- Be explicit in contracts; minimize breaking changes
+- Secure by default (auth first, least privilege)
+
+## Endpoint Pattern
+```
+/{version}/{resource}[/{id}][/{sub-resource}]
+```
+Examples:
+- `/api/v1/users`
+- `/api/v1/users/:id`
+- `/api/v1/users/:id/posts`
+
+HTTP verbs:
+- GET (read, safe, idempotent)
+- POST (create)
+- PUT/PATCH (update)
+- DELETE (remove, idempotent)
+
+## Request/Response
+
+Request (typical):
+```json
+{ "data": { ... }, "metadata": { "requestId": "..." } }
+```
+
+Success:
+```json
+{ "data": { ... }, "meta": { "timestamp": "...", "version": "..." } }
+```
+
+Error:
+```json
+{ "error": { "code": "ERROR_CODE", "message": "...", "field": "optional" } }
+```
+(See error-handling for rules.)
+
+## Status Codes (pattern)
+- 2xx: Success (200 read, 201 create, 204 delete)
+- 4xx: Client issues (400 validation, 401/403 auth, 404 missing)
+- 5xx: Server issues (500 generic, 503 unavailable)
+Choose the status that best reflects the outcome.
+
+## Authentication
+- Credentials in standard location
+```
+Authorization: Bearer {token}
+```
+- Reject unauthenticated before business logic
+
+## Versioning
+- Version via URL/header/media-type
+- Breaking change → new version
+- Non-breaking → same version
+- Provide deprecation window and comms
+
+## Pagination/Filtering (if applicable)
+- Pagination: `page`, `pageSize` or cursor-based
+- Filtering: explicit query params
+- Sorting: `sort=field:asc|desc`
+Return pagination metadata in `meta`.
+
+---
+_Focus on patterns and decisions, not endpoint catalogs._

.kiro/settings/templates/steering-custom/authentication.md

@@ -0,0 +1,67 @@
+# Authentication & Authorization Standards
+
+[Purpose: unify auth model, token/session lifecycle, permission checks, and security]
+
+## Philosophy
+- Clear separation: authentication (who) vs authorization (what)
+- Secure by default: least privilege, fail closed, short-lived tokens
+- UX-aware: friction where risk is high, smooth otherwise
+
+## Authentication
+
+### Method (choose + rationale)
+- Options: JWT, Session, OAuth2, hybrid
+- Choice: [our method] because [reason]
+
+### Flow (high-level)
+```
+1) User proves identity (credentials or provider)
+2) Server verifies and issues token/session
+3) Client sends token per request
+4) Server verifies token and proceeds
+```
+
+### Token/Session Lifecycle
+- Storage: httpOnly cookie or Authorization header
+- Expiration: short-lived access, longer refresh (if used)
+- Refresh: rotate tokens; respect revocation
+- Revocation: blacklist/rotate on logout/compromise
+
+### Security Pattern
+- Enforce TLS; never expose tokens to JS when avoidable
+- Bind token to audience/issuer; include minimal claims
+- Consider device binding and IP/risk checks for sensitive actions
+
+## Authorization
+
+### Permission Model
+- Choose one: RBAC / ABAC / ownership-based / hybrid
+- Define roles/attributes centrally; avoid hardcoding across codebase
+
+### Checks (where to enforce)
+- Route/middleware: coarse-grained gate
+- Domain/service: fine-grained decisions
+- UI: conditional rendering (no security reliance)
+
+Example pattern:
+```typescript
+requirePermission('resource:action'); // route
+if (!user.can('resource:action')) throw ForbiddenError(); // domain
+```
+
+### Ownership
+- Pattern: owner OR privileged role can act
+- Verify on entity boundary before mutation
+
+## Passwords & MFA
+- Passwords: strong policy, hashed (bcrypt/argon2), never plaintext
+- Reset: time-limited token, single-use, notify user
+- MFA: step-up for risky operations (policy-driven)
+
+## API-to-API Auth
+- Use API keys or OAuth client credentials
+- Scope keys minimally; rotate and audit usage
+- Rate limit by identity (user/key)
+
+---
+_Focus on patterns and decisions. No library-specific code._

.kiro/settings/templates/steering-custom/database.md

@@ -0,0 +1,46 @@
+# Database Standards
+
+[Purpose: guide schema design, queries, migrations, and integrity]
+
+## Philosophy
+- Model the domain first; optimize after correctness
+- Prefer explicit constraints; let database enforce invariants
+- Query only what you need; measure before optimizing
+
+## Naming & Types
+- Tables: `snake_case`, plural (`users`, `order_items`)
+- Columns: `snake_case` (`created_at`, `user_id`)
+- FKs: `{table}_id` referencing `{table}.id`
+- Types: timezone-aware timestamps; strong IDs; precise money types
+
+## Relationships
+- 1:N: FK in child
+- N:N: join table with compound key
+- 1:1: FK + UNIQUE
+
+## Migrations
+- Immutable migrations; always add rollback
+- Small, focused steps; test on non-prod first
+- Naming: `{seq}_{action}_{object}` (e.g., `002_add_email_index`)
+
+## Query Patterns
+- ORM for simple CRUD and safety; raw SQL for complex/perf-critical
+- Avoid N+1 (eager load/batching); paginate large sets
+- Index FKs and frequently filtered/sorted columns
+
+## Connection & Transactions
+- Use pooling (size/timeouts based on workload)
+- One connection per unit of work; close/return promptly
+- Wrap multi-step changes in transactions
+
+## Data Integrity
+- Use NOT NULL/UNIQUE/CHECK/FK constraints
+- Validate at DB when appropriate (defense in depth)
+- Prefer generated columns for consistent derivations
+
+## Backup & Recovery
+- Regular backups with retention; test restores
+- Document RPO/RTO targets; monitor backup jobs
+
+---
+_Focus on patterns and decisions. No environment-specific settings._

.kiro/settings/templates/steering-custom/deployment.md

@@ -0,0 +1,54 @@
+# Deployment Standards
+
+[Purpose: safe, repeatable releases with clear environment and pipeline patterns]
+
+## Philosophy
+- Automate; test before deploy; verify after deploy
+- Prefer incremental rollout with fast rollback
+- Production changes must be observable and reversible
+
+## Environments
+- Dev: fast iteration; debugging enabled
+- Staging: mirrors prod; release validation
+- Prod: hardened; monitored; least privilege
+
+## CI/CD Flow
+```
+Code → Test → Build → Scan → Deploy (staged) → Verify
+```
+Principles:
+- Fail fast on tests/scans; block deploy
+- Artifact builds are reproducible (lockfiles, pinned versions)
+- Manual approval for prod; auditable trail
+
+## Deployment Strategies
+- Rolling: gradual instance replacement
+- Blue-Green: switch traffic between two pools
+- Canary: small % users first, expand on health
+Choose per risk profile; document default.
+
+## Zero-Downtime & Migrations
+- Health checks gate traffic; graceful shutdown
+- Backwards-compatible DB changes during rollout
+- Separate migration step; test rollback paths
+
+## Rollback
+- Keep previous version ready; automate revert
+- Rollback faster than fix-forward; document triggers
+
+## Configuration & Secrets
+- 12-factor config via env; never commit secrets
+- Secret manager; rotate; least privilege; audit access
+- Validate required env vars at startup
+
+## Health & Monitoring
+- Endpoints: `/health`, `/health/live`, `/health/ready`
+- Monitor latency, error rate, throughput, saturation
+- Alerts on SLO breaches/spikes; tune to avoid fatigue
+
+## Incident Response & DR
+- Standard playbook: detect → assess → mitigate → communicate → resolve → post-mortem
+- Backups with retention; test restore; defined RPO/RTO
+
+---
+_Focus on rollout patterns and safeguards. No provider-specific steps._

.kiro/settings/templates/steering-custom/error-handling.md

@@ -0,0 +1,59 @@
+# Error Handling Standards
+
+[Purpose: unify how errors are classified, shaped, propagated, logged, and monitored]
+
+## Philosophy
+- Fail fast where possible; degrade gracefully at system boundaries
+- Consistent error shape across the stack (human + machine readable)
+- Handle known errors close to source; surface unknowns to a global handler
+
+## Classification (decide handling by source)
+- Client: Input/validation/user action issues → 4xx
+- Server: System failures/unexpected exceptions → 5xx
+- Business: Rule/state violations → 4xx (e.g., 409)
+- External: 3rd-party/network failures → map to 5xx or 4xx with context
+
+## Error Shape (single canonical format)
+```json
+{
+  "error": {
+    "code": "ERROR_CODE",
+    "message": "Human-readable message",
+    "requestId": "trace-id",
+    "timestamp": "ISO-8601"
+  }
+}
+```
+Principles: stable code enums, no secrets, include trace info.
+
+## Propagation (where to convert)
+- API layer: Convert domain errors → HTTP status + canonical body
+- Service layer: Throw typed business errors, avoid stringly-typed errors
+- Data/external layer: Wrap provider errors with safe, actionable codes
+- Unknown errors: Bubble to global handler → 500 + generic message
+
+Example pattern:
+```typescript
+try { return await useCase(); }
+catch (e) {
+  if (e instanceof BusinessError) return respondMapped(e);
+  logError(e); return respondInternal();
+}
+```
+
+## Logging (context over noise)
+Log: operation, userId (if available), code, message, stack, requestId, minimal context.
+Do not log: passwords, tokens, secrets, full PII, full bodies with sensitive data.
+Levels: ERROR (failures), WARN (recoverable/edge), INFO (key events), DEBUG (diagnostics).
+
+## Retry (only when safe)
+Retry when: network/timeouts/transient 5xx AND operation is idempotent.
+Do not retry: 4xx, business errors, non-idempotent flows.
+Strategy: exponential backoff + jitter, capped attempts; require idempotency keys.
+
+## Monitoring & Health
+Track: error rates by code/category, latency, saturation; alert on spikes/SLI breaches.
+Expose health: `/health` (live), `/health/ready` (ready). Link errors to traces.
+
+---
+_Focus on patterns and decisions. No implementation details or exhaustive lists._

.kiro/settings/templates/steering-custom/security.md

@@ -0,0 +1,55 @@
+# Security Standards
+
+[Purpose: define security posture with patterns for validation, authz, secrets, and data]
+
+## Philosophy
+- Defense in depth; least privilege; secure by default; fail closed
+- Validate at boundaries; sanitize for context; never trust input
+- Separate authentication (who) and authorization (what)
+
+## Input & Output
+- Validate at API boundaries and UI forms; enforce types and constraints
+- Sanitize/escape based on destination (HTML, SQL, shell, logs)
+- Prefer allow-lists over block-lists; reject early with minimal detail
+
+## Authentication & Authorization
+- Authentication: verify identity; issue short-lived tokens/sessions
+- Authorization: check permissions before actions; deny by default
+- Centralize policies; avoid duplicating checks across code
+
+Pattern:
+```typescript
+if (!user.hasPermission('resource:action')) throw ForbiddenError();
+```
+
+## Secrets & Configuration
+- Never commit secrets; store in secret manager or env
+- Rotate regularly; audit access; scope minimal
+- Validate required env vars at startup; fail fast on missing
+
+## Sensitive Data
+- Minimize collection; mask/redact in logs; encrypt at rest and in transit
+- Restrict access by role/need-to-know; track access to sensitive records
+
+## Session/Token Security
+- httpOnly + secure cookies where possible; TLS everywhere
+- Short expiration; rotate on refresh; revoke on logout/compromise
+- Bind tokens to audience/issuer; include minimal claims
+
+## Logging (security-aware)
+- Log auth attempts, permission denials, and sensitive operations
+- Never log passwords, tokens, secrets, full PII; avoid full bodies
+- Include requestId and context to correlate events
+
+## Headers & Transport
+- Enforce TLS; HSTS
+- Set security headers (CSP, X-Frame-Options, X-Content-Type-Options)
+- Prefer modern crypto; disable weak protocols/ciphers
+
+## Vulnerability Posture
+- Prefer secure libraries; keep dependencies updated
+- Static/dynamic scans in CI; track and remediate
+- Educate team on common classes; encode as patterns above
+
+---
+_Focus on patterns and principles. Link concrete configs to ops docs._

.kiro/settings/templates/steering-custom/testing.md

@@ -0,0 +1,47 @@
+# Testing Standards
+
+[Purpose: guide what to test, where tests live, and how to structure them]
+
+## Philosophy
+- Test behavior, not implementation
+- Prefer fast, reliable tests; minimize brittle mocks
+- Cover critical paths deeply; breadth over 100% pursuit
+
+## Organization
+Options:
+- Co-located: `component.tsx` + `component.test.tsx`
+- Separate: `/src/...` and `/tests/...`
+Pick one as default; allow exceptions with rationale.
+
+Naming:
+- Files: `*.test.*` or `*.spec.*`
+- Suites: what is under test; Cases: expected behavior
+
+## Test Types
+- Unit: single unit, mocked dependencies, very fast
+- Integration: multiple units together, mock externals only
+- E2E: full flows, minimal mocks, only for critical journeys
+
+## Structure (AAA)
+```typescript
+it('does X when Y', () => {
+  // Arrange
+  const input = setup();
+  // Act
+  const result = act(input);
+  // Assert
+  expect(result).toEqual(expected);
+});
+```
+
+## Mocking & Data
+- Mock externals (API/DB); never mock the system under test
+- Use factories/fixtures; reset state between tests
+- Keep test data minimal and intention-revealing
+
+## Coverage
+- Target: [% overall]; higher for critical domains
+- Enforce thresholds in CI; exceptions require review rationale
+
+---
+_Focus on patterns and decisions. Tool-specific config lives elsewhere._

.kiro/settings/templates/steering/product.md

@@ -0,0 +1,18 @@
+# Product Overview
+
+[Brief description of what this product does and who it serves]
+
+## Core Capabilities
+
+[3-5 key capabilities, not exhaustive features]
+
+## Target Use Cases
+
+[Primary scenarios this product addresses]
+
+## Value Proposition
+
+[What makes this product unique or valuable]
+
+---
+_Focus on patterns and purpose, not exhaustive feature lists_

.kiro/settings/templates/steering/structure.md

@@ -0,0 +1,41 @@
+# Project Structure
+
+## Organization Philosophy
+
+[Describe approach: feature-first, layered, domain-driven, etc.]
+
+## Directory Patterns
+
+### [Pattern Name]
+**Location**: `/path/`  
+**Purpose**: [What belongs here]  
+**Example**: [Brief example]
+
+### [Pattern Name]
+**Location**: `/path/`  
+**Purpose**: [What belongs here]  
+**Example**: [Brief example]
+
+## Naming Conventions
+
+- **Files**: [Pattern, e.g., PascalCase, kebab-case]
+- **Components**: [Pattern]
+- **Functions**: [Pattern]
+
+## Import Organization
+
+```typescript
+// Example import patterns
+import { Something } from '@/path'  // Absolute
+import { Local } from './local'     // Relative
+```
+
+**Path Aliases**:
+- `@/`: [Maps to]
+
+## Code Organization Principles
+
+[Key architectural patterns and dependency rules]
+
+---
+_Document patterns, not file trees. New files following patterns shouldn't require updates_

.kiro/settings/templates/steering/tech.md

@@ -0,0 +1,45 @@
+# Technology Stack
+
+## Architecture
+
+[High-level system design approach]
+
+## Core Technologies
+
+- **Language**: [e.g., TypeScript, Python]
+- **Framework**: [e.g., React, Next.js, Django]
+- **Runtime**: [e.g., Node.js 20+]
+
+## Key Libraries
+
+[Only major libraries that influence development patterns]
+
+## Development Standards
+
+### Type Safety
+[e.g., TypeScript strict mode, no `any`]
+
+### Code Quality
+[e.g., ESLint, Prettier rules]
+
+### Testing
+[e.g., Jest, coverage requirements]
+
+## Development Environment
+
+### Required Tools
+[Key tools and version requirements]
+
+### Common Commands
+```bash
+# Dev: [command]
+# Build: [command]
+# Test: [command]
+```
+
+## Key Technical Decisions
+
+[Important architectural choices and rationale]
+
+---
+_Document standards and patterns, not every dependency_

.kiro/steering/product.md

@@ -0,0 +1,34 @@
+# Product Overview
+
+GROWI is a team collaboration wiki platform using Markdown, designed to help teams document, share, and organize knowledge effectively.
+
+## Core Capabilities
+
+1. **Hierarchical Wiki Pages**: Tree-structured page organization with path-based navigation (`/path/to/page`)
+2. **Markdown-First Editing**: Rich Markdown support with extensions (drawio, lsx, math) and real-time collaborative editing
+3. **Authentication Integrations**: Multiple auth methods (LDAP, SAML, OAuth, Passkey) for enterprise environments
+4. **Plugin System**: Extensible architecture via `@growi/pluginkit` for custom remark plugins and functionality
+5. **Multi-Service Architecture**: Modular services (PDF export, Slack integration) deployed independently
+
+## Target Use Cases
+
+- **Team Documentation**: Technical documentation, meeting notes, project wikis
+- **Knowledge Management**: Searchable, organized information repository
+- **Enterprise Deployment**: Self-hosted wiki with SSO/LDAP integration
+- **Developer Teams**: Markdown-native, Git-friendly documentation workflow
+
+## Value Proposition
+
+- **Open Source**: MIT licensed, self-hostable, community-driven
+- **Markdown Native**: First-class Markdown support with powerful extensions
+- **Hierarchical Organization**: Intuitive path-based page structure (unlike flat wikis)
+- **Enterprise Ready**: Authentication integrations, access control, scalability
+- **Extensible**: Plugin system for customization without forking
+
+## Deployment Models
+
+- **Self-Hosted**: Docker, Kubernetes, or bare metal deployment
+- **Microservices**: Optional services (pdf-converter, slackbot-proxy) for enhanced functionality
+
+---
+_Focus on patterns and purpose, not exhaustive feature lists_

.kiro/steering/structure.md

@@ -0,0 +1,14 @@
+# Project Structure
+
+@.claude/skills/monorepo-overview/SKILL.md
+
+## cc-sdd Specific Notes
+
+### Specification Storage
+- All specifications are stored in `.kiro/specs/{feature-name}/`
+- Each spec contains: `spec.json`, `requirements.md`, `design.md`, `tasks.md`
+
+### Feature Placement
+When implementing new features via `/kiro:spec-impl`:
+- Create feature modules in `src/features/{feature-name}/`
+- Follow the server-client separation pattern documented in the skill above

.kiro/steering/tdd.md

@@ -0,0 +1,22 @@
+# Test-Driven Development
+
+@.claude/commands/tdd.md
+@.claude/skills/testing-patterns-with-vitest/SKILL.md
+
+## cc-sdd Integration
+
+### TDD in spec-impl Workflow
+When executing `/kiro:spec-impl`, the TDD cycle is mandatory:
+
+1. **Each task → TDD cycle**: RED → GREEN → REFACTOR
+2. **Tests trace to requirements**: Test names should reference EARS requirement IDs
+3. **Coverage gates completion**: Task is not complete until coverage targets met
+
+### Validation Before Task Completion
+```bash
+# Verify tests pass
+turbo run test --filter {package}
+
+# Check coverage (80% minimum)
+cd {package_dir} && pnpm vitest run --coverage src/utils/page-path-validator.spec.ts
+```

.kiro/steering/tech.md

@@ -0,0 +1,15 @@
+# Technology Stack
+
+@.claude/skills/tech-stack/SKILL.md
+
+## cc-sdd Specific Notes
+
+### Specification Language
+All spec files (requirements.md, design.md, tasks.md) should be written in English unless explicitly configured otherwise in spec.json.
+
+### Build Verification
+Before marking tasks complete in `/kiro:spec-impl`, ensure:
+```bash
+turbo run lint --filter @growi/app
+turbo run test --filter @growi/app
+```

.mcp.json

@@ -12,9 +12,10 @@
         "git+https://github.com/oraios/serena",
         "serena-mcp-server",
         "--context",
-        "ide-assistant",
+        "claude-code",
         "--project",
-        "."
+        ".",
+        "--enable-web-dashboard=false"
       ],
       "env": {}
     }

.serena/memories/apps-app-detailed-architecture.md

@@ -1,104 +0,0 @@
-# apps/app アーキテクチャ詳細ガイド
-
-## 概要
-`apps/app` は GROWI のメインアプリケーションで、Next.js ベースのフルスタック Web アプリケーションです。
-
-## エントリーポイント
-- **サーバーサイド**: `server/app.ts` - OpenTelemetry 初期化と Crowi サーバー起動を担当
-- **クライアントサイド**: `pages/_app.page.tsx` - Next.js アプリのルートコンポーネント
-
-## ディレクトリ構成の方針
-
-### フィーチャーベース（新しい方針）
-`features/` ディレクトリは機能ごとに整理され、各フィーチャーは以下の構造を持つ：
-- `interfaces/` - TypeScript 型定義
-- `server/` - サーバーサイドロジック（models, routes, services）
-- `client/` - クライアントサイドロジック（components, stores, services）
-- `utils/` - 共通ユーティリティ
-
-#### 主要フィーチャー
-- `openai/` - AI アシスタント機能（OpenAI 統合）
-- `external-user-group/` - 外部ユーザーグループ管理
-- `page-bulk-export/` - ページ一括エクスポート
-- `growi-plugin/` - プラグインシステム
-- `search/` - 検索機能
-- `mermaid/` - Mermaid 図表レンダリング
-- `plantuml/` - PlantUML 図表レンダリング
-- `callout/` - コールアウト（注意書き）機能
-- `comment/` - コメント機能
-- `templates/` - テンプレート機能
-- `rate-limiter/` - レート制限
-- `opentelemetry/` - テレメトリ・監視
-
-### レガシー構造（段階的移行予定）
-
-#### ユニバーサル（サーバー・クライアント共通）
-- `components/` - React コンポーネント（ページレベル、レイアウト、共通）
-- `interfaces/` - TypeScript インターフェース
-- `models/` - データモデル定義
-- `services/` - ビジネスロジック（レンダラーなど）
-- `stores-universal/` - ユニバーサル状態管理（SWR コンテキスト等）
-
-#### サーバーサイド専用
-- `server/` - サーバーサイドコード
-  - `models/` - Mongoose モデル
-  - `routes/` - Express ルート（API v3含む）
-  - `service/` - サーバーサイドサービス
-  - `middlewares/` - Express ミドルウェア
-  - `util/` - サーバーサイドユーティリティ
-  - `events/` - イベントエミッター
-  - `crowi/` - アプリケーション初期化
-
-#### クライアントサイド専用
-- `client/` - クライアントサイドコード
-  - `components/` - React コンポーネント
-  - `services/` - クライアントサイドサービス
-  - `util/` - クライアントサイドユーティリティ
-  - `interfaces/` - クライアント固有の型定義
-  - `models/` - クライアントサイドモデル
-
-#### Next.js Pages Router
-- `pages/` - Next.js ページルート
-  - `admin/` - 管理画面ページ
-  - `me/` - ユーザー設定ページ
-  - `[[...path]]/` - 動的ページルート（Catch-all）
-  - `share/` - 共有ページ
-  - `login/` - ログインページ
-
-#### 状態管理・UI
-- `states/` - Jotai 状態管理（ページ、UI、サーバー設定）
-- `stores/` - レガシー状態管理（段階的に states/ に移行）
-- `styles/` - SCSS スタイル
-
-#### その他
-- `utils/` - 汎用ユーティリティ
-- `migrations/` - データベースマイグレーション
-- `@types/` - TypeScript 型拡張
-
-## 開発指針
-
-### 新機能開発
-新しい機能は `features/` ディレクトリにフィーチャーベースで実装し、以下を含める：
-1. インターフェース定義
-2. サーバーサイド実装（必要に応じて）
-3. クライアントサイド実装（必要に応じて）
-4. 共通ユーティリティ
-
-### 既存機能の改修
-既存のレガシー構造は段階的に features/ に移行することが推奨される。
-
-### 重要な技術スタック
-- **フレームワーク**: Next.js (Pages Router)
-- **状態管理**: Jotai (新), SWR (データフェッチング)
-- **スタイル**: SCSS, CSS Modules
-- **サーバー**: Express.js
-- **データベース**: MongoDB (Mongoose)
-- **型システム**: TypeScript
-- **監視**: OpenTelemetry
-
-## 特記事項
-- AI 統合機能（OpenAI）は最も複雑なフィーチャーの一つ
-- プラグインシステムにより機能拡張可能
-- 多言語対応（i18next）
-- 複数の認証方式サポート
-- レート制限・セキュリティ機能内蔵

.serena/memories/apps-app-development-patterns.md

@@ -1,162 +0,0 @@
-# apps/app 開発ワークフロー・パターン集
-
-## よくある開発パターン
-
-### 新しいページ作成
-1. `pages/` にページファイル作成（`.page.tsx`）
-2. 必要に応じてレイアウト定義
-3. サーバーサイドプロパティ設定 (`getServerSideProps`)
-4. 状態管理セットアップ
-5. スタイル追加
-
-### 新しい API エンドポイント
-1. `server/routes/apiv3/` にルートファイル作成
-2. バリデーション定義
-3. サービス層実装
-4. レスポンス形式定義
-5. OpenAPI 仕様更新
-
-### 新しいフィーチャー実装
-1. `features/新機能名/` ディレクトリ作成
-2. `interfaces/` で型定義
-3. `server/` でバックエンド実装
-4. `client/` でフロントエンド実装
-5. `utils/` で共通ロジック
-
-### コンポーネント作成
-1. 適切なディレクトリに配置
-2. TypeScript プロパティ定義
-3. CSS Modules でスタイル
-4. JSDoc コメント追加
-5. テストファイル作成
-
-## 重要な設計パターン
-
-### SWR データフェッチング
-```typescript
-const { data, error, mutate } = useSWR('/api/v3/pages', fetcher);
-```
-
-### Jotai 状態管理
-```typescript
-const pageAtom = atom(initialPageState);
-const [page, setPage] = useAtom(pageAtom);
-```
-
-### CSS Modules スタイリング
-```scss
-.componentName {
-  @extend %some-placeholder;
-  @include some-mixin;
-}
-```
-
-### API ルート実装
-```typescript
-export const getPageHandler = async(req: NextApiRequest, res: NextApiResponse) => {
-  // バリデーション
-  // ビジネスロジック
-  // レスポンス
-};
-```
-
-## ファイル構成のベストプラクティス
-
-### フィーチャーディレクトリ例
-```
-features/my-feature/
-├── interfaces/
-│   └── my-feature.ts
-├── server/
-│   ├── models/
-│   ├── routes/
-│   └── services/
-├── client/
-│   ├── components/
-│   ├── stores/
-│   └── services/
-└── utils/
-    └── common-logic.ts
-```
-
-### コンポーネントディレクトリ例
-```
-components/MyComponent/
-├── MyComponent.tsx
-├── MyComponent.module.scss
-├── MyComponent.spec.tsx
-├── index.ts
-└── sub-components/
-```
-
-## 開発時のチェックリスト
-
-### コード品質
-- [ ] TypeScript エラーなし
-- [ ] テストケース作成
-- [ ] 型安全性確保
-- [ ] パフォーマンス影響確認
-
-### 機能要件
-- [ ] 国際化対応（i18n）
-- [ ] セキュリティチェック
-- [ ] アクセシビリティ対応
-- [ ] レスポンシブデザイン
-- [ ] エラーハンドリング
-
-### API 設計
-- [ ] RESTful 設計原則
-- [ ] 適切な HTTP ステータスコード
-- [ ] バリデーション実装
-- [ ] レート制限対応
-- [ ] ドキュメント更新
-
-## デバッグ・トラブルシューティング
-
-### よくある問題
-1. **型エラー**: tsconfig.json 設定確認
-2. **スタイル適用されない**: CSS Modules インポート確認
-3. **API エラー**: ミドルウェア順序確認
-4. **状態同期問題**: SWR キー重複確認
-5. **ビルドエラー**: 依存関係バージョン確認
-
-### デバッグツール
-- Next.js Dev Tools
-- React Developer Tools
-- Network タブ（API 監視）
-- Console ログ
-- Lighthouse（パフォーマンス）
-
-## パフォーマンス最適化
-
-### フロントエンド
-- コンポーネント lazy loading
-- 画像最適化
-- Bundle サイズ監視
-- メモ化（useMemo, useCallback）
-
-### バックエンド
-- データベースクエリ最適化
-- キャッシュ戦略
-- 非同期処理
-- リソース使用量監視
-
-## セキュリティ考慮事項
-
-### 実装時の注意
-- 入力サニタイゼーション
-- CSRF 対策
-- XSS 防止
-- 認証・認可チェック
-- 機密情報の適切な取り扱い
-
-## デプロイ・運用
-
-### 環境設定
-- 環境変数管理
-- データベース接続
-- 外部サービス連携
-- ログ設定
-- 監視設定
-
-このガイドは apps/app の開発を効率的に進めるための包括的な情報源として活用してください。

.serena/memories/apps-app-google-workspace-oauth2-mail.md

@@ -1,37 +0,0 @@
-# Google Workspace OAuth 2.0 メール送信機能実装計画
-
-## 概要
-
-Google Workspace (Gmail) の OAuth 2.0 (XOAUTH2) 認証を使ったメール送信機能を実装する。2025年5月1日以降、Gmail SMTP ではユーザー名とパスワード認証がサポートされなくなったため、OAuth 2.0 への移行が必要。
-
-## 背景
-
-- **問題**: Gmail SMTP でのユーザー名・パスワード認証が2025年5月1日にサポート終了
-- **解決策**: OAuth 2.0 (XOAUTH2) 認証方式の実装
-- **参考**: https://support.google.com/a/answer/2956491?hl=ja
-- **ライブラリ**: nodemailer v6.9.15 は OAuth 2.0 をサポート済み（バージョンアップ不要）
-
-## 技術仕様
-
-### 必須設定パラメータ
-
-| パラメータ | 説明 | セキュリティ |
-|-----------|------|------------|
-| `mail:oauth2ClientId` | Google Cloud Console で取得する OAuth 2.0 クライアント ID | 通常 |
-| `mail:oauth2ClientSecret` | OAuth 2.0 クライアントシークレット | `isSecret: true` |
-| `mail:oauth2RefreshToken` | OAuth 2.0 リフレッシュトークン | `isSecret: true` |
-| `mail:oauth2User` | 送信者のGmailアドレス | 通常 |
-
-### nodemailer 設定例
-
-```typescript
-const transportOptions = {
-  service: 'gmail',
-  auth: {
-    type: 'OAuth2',
-    user: 'user@example.com',
-    clientId: 'CLIENT_ID',
-    clientSecret: 'CLIENT_SECRET',
-    refreshToken: 'REFRESH_TOKEN',
-  },
-};

.serena/memories/apps-app-technical-specs.md

@@ -1,35 +0,0 @@
-# apps/app 技術仕様
-
-## ファイル構造・命名
-- Next.js: `*.page.tsx`
-- テスト: `*.spec.ts`, `*.integ.ts`
-- コンポーネント: `ComponentName.tsx`
-
-## API構造
-- **API v3**: `server/routes/apiv3/` (RESTful + OpenAPI準拠)
-- **Features API**: `features/*/server/routes/`
-
-## 状態管理
-- **Jotai** (推奨): `states/` - アトミック分離
-- **SWR**: `stores/` - データフェッチ・キャッシュ
-
-## データベース
-- **Mongoose**: `server/models/` (スキーマ定義)
-- **Serializers**: `serializers/` (レスポンス変換)
-
-## セキュリティ・i18n
-- **認証**: 複数プロバイダー + アクセストークン
-- **XSS対策**: `services/general-xss-filter/`
-- **i18n**: next-i18next (サーバー・クライアント両対応)
-
-## システム機能
-- **検索**: Elasticsearch統合
-- **監視**: OpenTelemetry (`features/opentelemetry/`)
-- **プラグイン**: 動的読み込み (`features/growi-plugin/`)
-
-## 開発ガイドライン
-1. 新機能は `features/` 実装
-2. TypeScript strict準拠
-3. Jotai状態管理優先
-4. API v3形式
-5. セキュリティ・i18n・テスト必須

.serena/memories/coding_conventions.md

@@ -1,61 +0,0 @@
-# コーディング規約とスタイルガイド
-
-## Linter・フォーマッター設定
-
-### Biome設定（統一予定）
-- **適用範囲**: 
-  - dist/, node_modules/, coverage/ などは除外
-  - .next/, bin/, config/ などのビルド成果物は除外
-  - package.json などの設定ファイルは除外
-- **推奨**: 新規開発では Biome を使用
-
-## TypeScript設定
-- **ターゲット**: ESNext
-- **モジュール**: ESNext  
-- **厳格モード**: 有効（strict: true）
-- **モジュール解決**: Bundler
-- **その他**:
-  - allowJs: true（JSファイルも許可）
-  - skipLibCheck: true（型チェックの最適化）
-  - isolatedModules: true（単独モジュールとしてコンパイル）
-
-## Stylelint設定
-- SCSS/CSSファイルに対して適用
-- recess-order設定を使用（プロパティの順序規定）
-- recommended-scss設定を適用
-
-## ファイル命名規則
-- TypeScript/JavaScriptファイル: キャメルケースまたはケバブケース
-- コンポーネントファイル: PascalCase（Reactコンポーネント）
-- 設定ファイル: ドット記法（.biome.json など）
-
-## テストファイル命名規則（Vitest）
-vitest.workspace.mts の設定に基づく：
-
-### 単体テスト（Unit Test）
-- **ファイル名**: `*.spec.{ts,js}`
-- **環境**: Node.js
-- **例**: `utils.spec.ts`, `helper.spec.js`
-
-### 統合テスト（Integration Test）
-- **ファイル名**: `*.integ.ts`
-- **環境**: Node.js（MongoDB設定あり）
-- **例**: `api.integ.ts`, `service.integ.ts`
-
-### コンポーネントテスト（Component Test）
-- **ファイル名**: `*.spec.{tsx,jsx}`
-- **環境**: happy-dom
-- **例**: `Button.spec.tsx`, `Modal.spec.jsx`
-
-## ディレクトリ構造の規則
-- `src/`: ソースコード
-- `test/`: Jest用の古いテストファイル（廃止予定）
-- `test-with-vite/`: Vitest用の新しいテストファイル
-- `playwright/`: E2Eテストファイル
-- `config/`: 設定ファイル
-- `public/`: 静的ファイル
-- `dist/`: ビルド出力
-
-## 移行ガイドライン
-- 新規開発: Biome + Vitest を使用
-- 既存コード: 段階的に Jest → Vitest に移行

.serena/memories/project_overview.md

@@ -1,26 +0,0 @@
-# GROWIプロジェクト概要
-
-## 目的
-GROWIは、マークダウンを使用したチームコラボレーションソフトウェアです。Wikiとドキュメント作成ツールの機能を持ち、チーム間の情報共有とコラボレーションを促進します。
-
-## プロジェクトの詳細
-- **プロジェクト名**: GROWI
-- **バージョン**: 7.3.0-RC.0
-- **ライセンス**: MIT
-- **作者**: Yuki Takei <yuki@weseek.co.jp>
-- **リポジトリ**: https://github.com/growilabs/growi.git
-- **公式サイト**: https://growi.org
-
-## 主な特徴
-- Markdownベースのドキュメント作成
-- チームコラボレーション機能
-- Wikiのような情報共有プラットフォーム
-- ドキュメント管理とバージョン管理
-
-## アーキテクチャ
-- **モノレポ構成**: pnpm workspace + Turbo.js を使用
-- **主要アプリケーション**: apps/app (メインアプリケーション)
-- **追加アプリケーション**: 
-  - apps/pdf-converter (PDF変換サービス)
-  - apps/slackbot-proxy (Slackボットプロキシ)
-- **パッケージ**: packages/ 配下に複数の共有ライブラリ

.serena/memories/project_structure.md

@@ -1,89 +0,0 @@
-# プロジェクト構造
-
-## ルートディレクトリ構造
-```
-growi/
-├── apps/                    # アプリケーション群
-│   ├── app/                # メインのGROWIアプリケーション
-│   ├── pdf-converter/      # PDF変換サービス
-│   └── slackbot-proxy/     # Slackボットプロキシ
-├── packages/               # 共有パッケージ群
-│   ├── core/              # コアライブラリ
-│   ├── core-styles/       # 共通スタイル
-│   ├── editor/            # エディターコンポーネント
-│   ├── pluginkit/         # プラグインキット
-│   ├── ui/                # UIコンポーネント
-│   ├── presentation/      # プレゼンテーション層
-│   ├── preset-templates/  # テンプレート
-│   ├── preset-themes/     # テーマ
-│   └── remark-*/          # remarkプラグイン群
-├── bin/                   # ユーティリティスクリプト
-└── 設定ファイル群
-```
-
-## メインアプリケーション (apps/app/)
-```
-apps/app/
-├── src/                   # ソースコード
-├── test/                  # 古いJestテストファイル（廃止予定）
-├── test-with-vite/        # 新しいVitestテストファイル
-├── playwright/            # E2Eテスト（Playwright）
-├── config/                # 設定ファイル
-├── public/                # 静的ファイル
-├── docker/                # Docker関連
-├── bin/                   # スクリプト
-└── 設定ファイル群
-```
-
-## テストディレクトリの詳細
-
-### test/ (廃止予定)
-- Jest用の古いテストファイル
-- 段階的にtest-with-vite/に移行予定
-- 新規テストは作成しない
-
-### test-with-vite/
-- Vitest用の新しいテストファイル
-- 新規テストはここに作成
-- セットアップファイル: `setup/mongoms.ts` (MongoDB用)
-
-### playwright/
-- E2Eテスト用ディレクトリ
-- ブラウザ操作を含むテスト
-
-## テストファイルの配置ルール
-
-### Vitestテストファイル
-以下のパターンでソースコードと同じディレクトリまたはtest-with-vite/配下に配置：
-
-- **単体テスト**: `*.spec.{ts,js}`
-- **統合テスト**: `*.integ.ts` 
-- **コンポーネントテスト**: `*.spec.{tsx,jsx}`
-
-例：
-```
-src/
-├── utils/
-│   ├── helper.ts
-│   └── helper.spec.ts       # 単体テスト
-├── components/
-│   ├── Button.tsx
-│   └── Button.spec.tsx      # コンポーネントテスト
-└── services/
-    ├── api.ts
-    └── api.integ.ts         # 統合テスト
-```
-
-## パッケージ（packages/）
-各パッケージは独立したnpmパッケージとして管理され、以下の構造を持つ：
-- `src/`: ソースコード
-- `dist/`: ビルド出力
-- `package.json`: パッケージ設定
-- `tsconfig.json`: TypeScript設定
-
-## 重要な設定ファイル
-- **pnpm-workspace.yaml**: ワークスペース設定
-- **turbo.json**: Turbo.jsビルド設定
-- **tsconfig.base.json**: TypeScript基本設定
-- **biome.json**: Biome linter/formatter設定
-- **vitest.workspace.mts**: Vitestワークスペース設定

.serena/memories/task_completion_checklist.md

@@ -1,94 +0,0 @@
-# タスク完了時のチェックリスト
-
-## コードを書いた後に必ず実行すべきコマンド
-
-### 1. Lint・フォーマットの実行
-```bash
-# 【推奨】Biome実行（新規開発）
-pnpm run lint:biome
-
-# 【過渡期】全てのLint実行（既存コード）
-pnpm run lint
-
-# 個別実行（必要に応じて）
-pnpm run lint:styles      # Stylelint
-pnpm run lint:typecheck   # TypeScript型チェック
-```
-
-### 2. テストの実行
-```bash
-# 【推奨】Vitestテスト実行（新規開発）
-pnpm run test:vitest
-
-# 【過渡期】全てのテスト実行（既存コード）
-pnpm run test
-
-# 個別実行
-pnpm run test:jest        # Jest（廃止予定）
-pnpm run test:vitest {target-file-name}     # Vitest
-```
-
-### 3. E2Eテストの実行（重要な機能変更時）
-```bash
-cd apps/app
-npx playwright test
-```
-
-### 4. ビルドの確認
-```bash
-# メインアプリケーションのビルド
-pnpm run app:build
-
-# 関連パッケージのビルド
-turbo run build
-```
-
-### 5. 動作確認
-```bash
-# 開発サーバーでの動作確認
-cd apps/app && pnpm run dev
-
-# または本番ビルドでの確認
-pnpm start
-```
-
-## 特別な確認事項
-
-### OpenAPI仕様の確認（API変更時）
-```bash
-cd apps/app
-pnpm run openapi:generate-spec:apiv3
-pnpm run lint:openapi:apiv3
-```
-
-### データベーススキーマ変更時
-```bash
-cd apps/app
-pnpm run dev:migrate:status  # 現在の状態確認
-pnpm run dev:migrate         # マイグレーション実行
-```
-
-## テストファイル作成時の注意
-
-### 新規テストファイル
-- **単体テスト**: `*.spec.{ts,js}` (Node.js環境)
-- **統合テスト**: `*.integ.ts` (Node.js + MongoDB環境)  
-- **コンポーネントテスト**: `*.spec.{tsx,jsx}` (happy-dom環境)
-- test-with-vite/ または対象ファイルと同じディレクトリに配置
-
-### 既存テストの修正
-- test/ 配下のJestテストは段階的に移行
-- 可能であればtest-with-vite/にVitestテストとして書き直し
-
-## コミット前の最終チェック
-1. Biome エラーが解消されているか
-2. Vitestテスト（または過渡期はJest）がパスしているか
-3. 重要な変更はPlaywright E2Eテストも実行
-4. ビルドが成功するか
-5. 変更による既存機能への影響がないか
-6. 適切なコミットメッセージを作成したか
-
-## 移行期間中の注意事項
-- 新規開発: Biome + Vitest を使用
-- 既存コード修正: 可能な限り Biome + Vitest に移行
-- レガシーツールは段階的に廃止予定

.serena/memories/tech_stack.md

@@ -1,41 +0,0 @@
-# 技術スタック & 開発環境
-
-## コア技術
-- **TypeScript** ~5.0.0 + **Next.js** (React)
-- **Node.js** ^20||^22 + **MongoDB** + **Mongoose** ^6.13.6
-- **pnpm** 10.4.1 + **Turbo** ^2.1.3 (モノレポ)
-
-## 状態管理・データ
-- **Jotai**: アトミック状態管理（推奨）
-- **SWR** ^2.3.2: データフェッチ・キャッシュ
-
-## 開発ツール移行状況
-| 従来 | 移行先 | 状況 |
-|------|--------|------|
-| ESLint | **Biome** | 新規推奨 |
-| Jest | **Vitest** + **Playwright** | 新規推奨 |
-
-## 主要コマンド
-```bash
-# 開発
-cd apps/app && pnpm run dev
-
-# 品質チェック
-pnpm run lint:biome        # 新規推奨
-pnpm run lint:typecheck    # 型チェック正式コマンド
-pnpm run test:vitest       # 新規推奨
-
-# ビルド
-pnpm run app:build
-turbo run build           # 並列ビルド
-```
-
-## ファイル命名規則
-- Next.js: `*.page.tsx`
-- テスト: `*.spec.ts` (Vitest), `*.integ.ts`
-- コンポーネント: `ComponentName.tsx`
-
-## API・アーキテクチャ
-- **API v3**: `server/routes/apiv3/` (RESTful + OpenAPI)
-- **Features**: `features/*/` (機能別分離)
-- **SCSS**: CSS Modules使用

.serena/memories/vitest-testing-tips-and-best-practices.md

@@ -1,95 +0,0 @@
-# Vitest + TypeScript Testing Guide
-
-## 核心技術要素
-
-### tsconfig.json最適設定
-```json
-{
-  "compilerOptions": {
-    "types": ["vitest/globals"]  // グローバルAPI: describe, it, expect等をインポート不要化
-  }
-}
-```
-
-### vitest-mock-extended: 型安全モッキング
-```typescript
-import { mockDeep, type DeepMockProxy } from 'vitest-mock-extended';
-
-// 完全型安全なNext.js Routerモック
-const mockRouter: DeepMockProxy<NextRouter> = mockDeep<NextRouter>();
-mockRouter.asPath = '/test-path';  // TypeScript補完・型チェック有効
-
-// 複雑なUnion型も完全サポート
-interface ComplexProps {
-  currentPageId?: string | null;
-  currentPathname?: string | null;
-}
-const mockProps: DeepMockProxy<ComplexProps> = mockDeep<ComplexProps>();
-```
-
-### React Testing Library + Jotai統合
-```typescript
-const renderWithProvider = (ui: React.ReactElement, scope?: Scope) => {
-  const Wrapper = ({ children }: { children: React.ReactNode }) => (
-    <Provider scope={scope}>{children}</Provider>
-  );
-  return render(ui, { wrapper: Wrapper });
-};
-```
-
-## 実践パターン
-
-### 非同期テスト
-```typescript
-import { waitFor, act } from '@testing-library/react';
-
-await act(async () => {
-  result.current.triggerAsyncAction();
-});
-
-await waitFor(() => {
-  expect(result.current.isLoading).toBe(false);
-});
-```
-
-### 詳細アサーション
-```typescript
-expect(mockFunction).toHaveBeenCalledWith(
-  expect.objectContaining({
-    pathname: '/expected-path',
-    data: expect.any(Object)
-  })
-);
-```
-
-## 実行コマンド
-
-### 基本テスト実行
-```bash
-# Vitest単体
-pnpm run test:vitest
-
-# Vitest単体（coverageあり）
-pnpm run test:vitest:coverage
-
-# 特定ファイルのみ実行（coverageあり）
-pnpm run test:vitest src/path/to/test.spec.tsx
-```
-
-### package.jsonスクリプト参照
-```json
-{
-  "scripts": {
-    "test": "run-p test:*",
-    "test:jest": "cross-env NODE_ENV=test TS_NODE_PROJECT=test/integration/tsconfig.json jest",
-    "test:vitest": "vitest run --coverage"
-  }
-}
-```
-
-## Jest→Vitest移行要点
-- `jest.config.js` → `vitest.config.ts`
-- `@types/jest` → `vitest/globals`
-- ESModulesネイティブサポート → 高速起動・実行
-
-この設定により型安全性と保守性を両立した高品質テストが可能。

.serena/project.yml

@@ -22,7 +22,7 @@ read_only: false
 
 # list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
 # Below is the complete list of tools for convenience.
-# To make sure you have the latest list of tools, and to view their descriptions, 
+# To make sure you have the latest list of tools, and to view their descriptions,
 # execute `uv run scripts/print_tool_overview.py`.
 #
 #  * `activate_project`: Activates a project by name.
@@ -59,7 +59,7 @@ read_only: false
 #  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
 #  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
 #  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
-excluded_tools: []
+excluded_tools: ["check_onboarding_performed", "execute_shell_command", "initial_instructions", "onboarding", "prepare_for_new_conversation", "read_memory", "write_memory", "list_memories", "delete_memory"]
 
 # initial prompt for the project. It will always be given to the LLM upon activating the project
 # (contrary to the memories, which are loaded on demand).

.serena/serena_config.yml

@@ -1,10 +0,0 @@
-web_dashboard: false
-# whether to open the Serena web dashboard (which will be accessible through your web browser) that
-# shows Serena's current session logs - as an alternative to the GUI log window which
-# is supported on all platforms.
-
-web_dashboard_open_on_launch: false
-# whether to open a browser window with the web dashboard when Serena starts (provided that web_dashboard
-# is enabled). If set to False, you can still open the dashboard manually by navigating to
-# http://localhost:24282/dashboard/ in your web browser (24282 = 0x5EDA, SErena DAshboard).
-# If you have multiple instances running, a higher port will be used; try port 24283, 24284, etc.

.vscode/mcp.json

@@ -13,7 +13,10 @@
         "serena",
         "start-mcp-server",
         "--context",
-        "ide-assistant"
+        "ide",
+        "--project",
+        ".",
+        "--enable-web-dashboard=false"
       ]
     }
   }

AGENTS.md

@@ -1,74 +1,140 @@
 # AGENTS.md
 
-GROWI is a team collaboration wiki platform built with Next.js, Express, and MongoDB. This guide helps AI coding agents navigate the monorepo and work effectively with GROWI's architecture.
+GROWI is a team collaboration wiki platform built with Next.js, Express, and MongoDB. This guide provides essential instructions for AI coding agents working with the GROWI codebase.
 
-## Language
+## Language Policy
 
-If we detect at the beginning of a conversation that the user's primary language is not English, we will always respond in that language. However, we may retain technical terms in English if necessary.
+**Response Language**: If we detect at the beginning of a conversation that the user's primary language is not English, we will always respond in that language. However, technical terms may remain in English when appropriate.
 
-When generating source code, all comments and explanations within the code will be written in English.
+**Code Comments**: When generating source code, all comments and explanations within the code must be written in English, regardless of the conversation language.
 
 ## Project Overview
 
-GROWI is a team collaboration software using markdown - a wiki platform with hierarchical page organization. It's built with Next.js, Express, MongoDB, and includes features like real-time collaborative editing, authentication integrations, and plugin support.
+GROWI is a team collaboration wiki platform using Markdown, featuring hierarchical page organization, real-time collaborative editing, authentication integrations, and plugin support. Built as a monorepo with Next.js, Express, and MongoDB.
 
-## Development Tools
-- **Package Manager**: pnpm with workspace support
-- **Build System**: Turborepo for monorepo orchestration
-- **Code Quality**: 
-  - Biome for linting and formatting
-  - Stylelint for SCSS/CSS
+## Knowledge Base
 
-## Development Commands
+### Claude Code Skills (Auto-Invoked)
 
-### Core Development
-- `turbo run bootstrap` - Install dependencies for all workspace packages
-- `turbo run dev` - Start development server (automatically runs migrations and pre-builds styles)
+Technical information is available in **Claude Code Skills** (`.claude/skills/`), which are automatically invoked during development.
 
-### Production Commands
-- `pnpm run app:build` - Build GROWI app client and server for production
-- `pnpm run app:server` - Launch GROWI app server in production mode
-- `pnpm start` - Build and start the application (runs both build and server commands)
+**Global Skills** (always loaded):
 
-### Database Migrations
-- `pnpm run migrate` - Run MongoDB migrations (production)
-- `turbo run dev:migrate @apps/app` - Run migrations in development (or wait for automatic execution with dev)
-- `cd apps/app && pnpm run dev:migrate:status` - Check migration status
-- `cd apps/app && pnpm run dev:migrate:down` - Rollback last migration
+| Skill | Description |
+|-------|-------------|
+| **monorepo-overview** | Monorepo structure, workspace organization, Changeset versioning |
+| **tech-stack** | Technology stack, pnpm/Turborepo, TypeScript, Biome |
+| **testing-patterns-with-vitest** | Vitest, React Testing Library, vitest-mock-extended |
 
-### Testing and Quality
-- `turbo run test @apps/app` - Run Jest and Vitest test suites with coverage
-- `turbo run lint @apps/app` - Run all linters (TypeScript, Biome, Stylelint, OpenAPI)
-- `cd apps/app && pnpm run lint:typecheck` - TypeScript type checking only
-- `cd apps/app && pnpm run test:vitest` - Run Vitest unit tests
-- `cd apps/app && pnpm run test:jest` - Run Jest integration tests
+**Rules** (always applied):
 
-### Development Utilities  
-- `cd apps/app && pnpm run repl` - Start Node.js REPL with application context loaded
-- `turbo run pre:styles @apps/app` - Pre-build styles with Vite
+| Rule | Description |
+|------|-------------|
+| **coding-style** | Coding conventions, naming, exports, immutability, comments |
+| **security** | Security checklist, secret management, OWASP vulnerability prevention |
+| **performance** | Model selection, context management, build troubleshooting |
 
-## Architecture Overview
+**Agents** (specialized):
 
-### Monorepo Structure
-- `/apps/app/` - Main GROWI application (Next.js frontend + Express backend)
-- `/apps/pdf-converter/` - PDF conversion microservice
-- `/apps/slackbot-proxy/` - Slack integration proxy service
-- `/packages/` - Shared libraries and components
+| Agent | Description |
+|-------|-------------|
+| **build-error-resolver** | TypeScript/build error resolution with minimal diffs |
+| **security-reviewer** | Security vulnerability detection, OWASP Top 10 |
 
-## File Organization Patterns
+**Commands** (user-invocable):
 
-### Components
-- Use TypeScript (.tsx) for React components
-- Co-locate styles as `.module.scss` files
-- Export components through `index.ts` files where appropriate
-- Group related components in feature-based directories
+| Command | Description |
+|---------|-------------|
+| **/tdd** | Test-driven development workflow |
+| **/learn** | Extract reusable patterns from sessions |
 
-### Tests
-- Unit Test: `*.spec.ts`
-- Integration Test: `*.integ.ts`
-- Component Test: `*.spec.tsx`
+**apps/app Skills** (loaded when working in apps/app):
 
+| Skill | Description |
+|-------|-------------|
+| **app-architecture** | Next.js Pages Router, Express, feature-based structure |
+| **app-commands** | apps/app specific commands (migrations, OpenAPI, etc.) |
+| **app-specific-patterns** | Jotai/SWR patterns, router mocking, API routes |
+
+### Package-Specific CLAUDE.md
+
+Each application has its own CLAUDE.md with detailed instructions:
+
+- `apps/app/CLAUDE.md` - Main GROWI application
+- `apps/pdf-converter/CLAUDE.md` - PDF conversion microservice
+- `apps/slackbot-proxy/CLAUDE.md` - Slack integration proxy
+
+### Serena Memories
+
+Additional detailed specifications are stored in **Serena memories** and can be referenced when needed for specific features or subsystems.
+
+## Quick Reference
+
+### Essential Commands (Global)
+
+```bash
+# Development
+turbo run dev                    # Start all dev servers
+
+# Quality Checks (use Turborepo for caching)
+turbo run lint --filter @growi/app
+turbo run test --filter @growi/app
+
+# Production
+pnpm run app:build              # Build main app
+pnpm start                      # Build and start
+```
+
+### Key Directories
+
+```
+growi/
+├── apps/
+│   ├── app/                # Main GROWI application (Next.js + Express)
+│   ├── pdf-converter/      # PDF conversion microservice
+│   └── slackbot-proxy/     # Slack integration proxy
+├── packages/               # Shared libraries (@growi/core, @growi/ui, etc.)
+└── .claude/
+    ├── skills/             # Claude Code skills (auto-loaded)
+    ├── rules/              # Coding standards (always applied)
+    ├── agents/             # Specialized agents
+    └── commands/           # User-invocable commands (/tdd, /learn)
+```
+
+## Development Guidelines
+
+1. **Feature-Based Architecture**: Create new features in `features/{feature-name}/`
+2. **Server-Client Separation**: Keep server and client code separate
+3. **State Management**: Jotai for UI state, SWR for data fetching
+4. **Named Exports**: Prefer named exports (except Next.js pages)
+5. **Test Co-location**: Place test files next to source files
+6. **Type Safety**: Use strict TypeScript throughout
+7. **Changeset**: Use `npx changeset` for version management
+
+## Before Committing
+
+Always execute these checks:
+
+```bash
+# From workspace root (recommended)
+turbo run lint:typecheck --filter @growi/app
+turbo run lint:biome --filter @growi/app
+turbo run test --filter @growi/app
+turbo run build --filter @growi/app
+```
+
+Or from apps/app directory:
+
+```bash
+pnpm run lint:typecheck
+pnpm run lint:biome
+pnpm run test
+pnpm run build
+```
 
 ---
 
-When working with this codebase, always run the appropriate linting and testing commands before committing changes. The application uses strict TypeScript checking and comprehensive test coverage requirements.
+For detailed information, refer to:
+- **Rules**: `.claude/rules/` (coding standards)
+- **Skills**: `.claude/skills/` (technical knowledge)
+- **Package docs**: `apps/*/CLAUDE.md` (package-specific)

CLAUDE.md

@@ -1 +1,48 @@
 @AGENTS.md
+
+# AI-DLC and Spec-Driven Development
+
+Kiro-style Spec Driven Development implementation on AI-DLC (AI Development Life Cycle)
+
+## Project Context
+
+### Paths
+- Steering: `.kiro/steering/`
+- Specs: `.kiro/specs/`
+
+### Steering vs Specification
+
+**Steering** (`.kiro/steering/`) - Guide AI with project-wide rules and context
+**Specs** (`.kiro/specs/`) - Formalize development process for individual features
+
+### Active Specifications
+- Check `.kiro/specs/` for active specifications
+- Use `/kiro:spec-status [feature-name]` to check progress
+
+## Development Guidelines
+- Think in English, generate responses in English. All Markdown content written to project files (e.g., requirements.md, design.md, tasks.md, research.md, validation reports) MUST be written in the target language configured for this specification (see spec.json.language).
+
+## Minimal Workflow
+- Phase 0 (optional): `/kiro:steering`, `/kiro:steering-custom`
+- Phase 1 (Specification):
+  - `/kiro:spec-init "description"`
+  - `/kiro:spec-requirements {feature}`
+  - `/kiro:validate-gap {feature}` (optional: for existing codebase)
+  - `/kiro:spec-design {feature} [-y]`
+  - `/kiro:validate-design {feature}` (optional: design review)
+  - `/kiro:spec-tasks {feature} [-y]`
+- Phase 2 (Implementation): `/kiro:spec-impl {feature} [tasks]`
+  - `/kiro:validate-impl {feature}` (optional: after implementation)
+- Progress check: `/kiro:spec-status {feature}` (use anytime)
+
+## Development Rules
+- 3-phase approval workflow: Requirements → Design → Tasks → Implementation
+- Human review required each phase; use `-y` only for intentional fast-track
+- Keep steering current and verify alignment with `/kiro:spec-status`
+- Follow the user's instructions precisely, and within that scope act autonomously: gather the necessary context and complete the requested work end-to-end in this run, asking questions only when essential information is missing or the instructions are critically ambiguous.
+
+## Steering Configuration
+- Load entire `.kiro/steering/` as project memory
+- Default files: `product.md`, `tech.md`, `structure.md`
+- Custom files are supported (managed via `/kiro:steering-custom`)
+

apps/app/.claude/skills/app-architecture/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: app-architecture
+description: GROWI main application (apps/app) architecture, directory structure, and design patterns. Auto-invoked when working in apps/app.
+user-invocable: false
+---
+
+# App Architecture (apps/app)
+
+The main GROWI application is a **full-stack Next.js application** with Express.js backend and MongoDB database.
+
+For technology stack details, see the global `tech-stack` skill.
+
+## Directory Structure
+
+```
+apps/app/src/
+├── pages/                 # Next.js Pages Router (*.page.tsx)
+├── features/             # Feature modules (recommended for new code)
+│   └── {feature-name}/
+│       ├── index.ts      # Public exports
+│       ├── interfaces/   # TypeScript types
+│       ├── server/       # models/, routes/, services/
+│       └── client/       # components/, states/, hooks/
+├── server/               # Express server (legacy)
+│   ├── models/           # Mongoose models
+│   ├── routes/apiv3/     # RESTful API v3
+│   └── services/         # Business logic
+├── components/           # React components (legacy)
+├── states/               # Jotai atoms
+└── stores-universal/     # SWR hooks
+```
+
+## Feature-Based Architecture
+
+Organize code by **business feature** rather than by technical layer:
+
+```
+❌ Layer-based (old):          ✅ Feature-based (new):
+├── models/User.ts             ├── features/user/
+├── routes/user.ts             │   ├── server/models/User.ts
+├── components/UserList.tsx    │   ├── server/routes/user.ts
+                               │   └── client/components/UserList.tsx
+```
+
+### Creating a New Feature
+
+1. Create `features/{feature-name}/`
+2. Define interfaces in `interfaces/`
+3. Implement server logic in `server/` (models, routes, services)
+4. Implement client logic in `client/` (components, hooks, states)
+5. Export public API through `index.ts`
+
+## Entry Points
+
+- **Server**: `server/app.ts` - Express + Next.js initialization
+- **Client**: `pages/_app.page.tsx` - Jotai + SWR providers
+- **Wiki Pages**: `pages/[[...path]]/index.page.tsx` - Catch-all route (SSR)
+
+## API Design (RESTful API v3)
+
+Routes in `server/routes/apiv3/` with OpenAPI specs:
+
+```typescript
+/**
+ * @openapi
+ * /api/v3/pages/{id}:
+ *   get:
+ *     summary: Get page by ID
+ */
+router.get('/pages/:id', async (req, res) => {
+  const page = await PageService.findById(req.params.id);
+  res.json(page);
+});
+```
+
+## State Management
+
+- **Jotai**: UI state (modals, forms) in `states/`
+- **SWR**: Server data (pages, users) in `stores-universal/`
+
+For detailed patterns, see `app-specific-patterns` skill.
+
+## Design Principles
+
+1. **Feature Isolation**: New features self-contained in `features/`
+2. **Server-Client Separation**: Prevent server code bundled into client
+3. **API-First**: Define OpenAPI specs before implementation
+4. **Type-Driven**: Define interfaces before implementation
+5. **Progressive Migration**: Gradually move legacy code to `features/`
+
+## Legacy Migration
+
+Legacy directories (`components/`, `server/models/`, `client/`) should be gradually migrated to `features/`:
+
+- New features → `features/`
+- Bug fixes → Can stay in legacy
+- Refactoring → Move to `features/`
+
+## Summary
+
+1. **New features**: `features/{feature-name}/` structure
+2. **Server-client separation**: Keep separate
+3. **API-first**: OpenAPI specs for API v3
+4. **State**: Jotai (UI) + SWR (server data)
+5. **Progressive migration**: No rush for stable legacy code

apps/app/.claude/skills/app-commands/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: app-commands
+description: GROWI main application (apps/app) specific commands and scripts. Auto-invoked when working in apps/app.
+user-invocable: false
+---
+
+# App Commands (apps/app)
+
+Commands specific to the main GROWI application. For global commands (turbo, pnpm), see the global `tech-stack` skill.
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| **Migration** | `pnpm run dev:migrate` |
+| **OpenAPI generate** | `pnpm run openapi:generate-spec:apiv3` |
+| **REPL console** | `pnpm run console` |
+| **Visual regression** | `pnpm run reg:run` |
+| **Version bump** | `pnpm run version:patch` |
+
+## Database Migration
+
+```bash
+# Run pending migrations
+pnpm run dev:migrate
+
+# Check migration status
+pnpm run dev:migrate:status
+
+# Apply migrations
+pnpm run dev:migrate:up
+
+# Rollback last migration
+pnpm run dev:migrate:down
+
+# Production migration
+pnpm run migrate
+```
+
+**Note**: Migrations use `migrate-mongo`. Files are in `config/migrate-mongo/`.
+
+### Creating a New Migration
+
+```bash
+# Create migration file manually in config/migrate-mongo/
+# Format: YYYYMMDDHHMMSS-migration-name.js
+
+# Test migration cycle
+pnpm run dev:migrate:up
+pnpm run dev:migrate:down
+pnpm run dev:migrate:up
+```
+
+## OpenAPI Commands
+
+```bash
+# Generate OpenAPI spec for API v3
+pnpm run openapi:generate-spec:apiv3
+
+# Validate API v3 spec
+pnpm run lint:openapi:apiv3
+
+# Generate operation IDs
+pnpm run openapi:build:generate-operation-ids
+```
+
+Generated specs output to `tmp/openapi-spec-apiv3.json`.
+
+## Style Pre-build (Vite)
+
+```bash
+# Development mode
+pnpm run dev:pre:styles
+
+# Production mode
+pnpm run pre:styles
+```
+
+Pre-builds SCSS styles into CSS bundles using Vite.
+
+## Debug & Utility
+
+### REPL Console
+
+```bash
+pnpm run console
+# or
+pnpm run repl
+```
+
+Interactive Node.js REPL with Mongoose models loaded. Useful for debugging database queries.
+
+### Visual Regression Testing
+
+```bash
+pnpm run reg:run
+```
+
+## Version Commands
+
+```bash
+# Bump patch version (e.g., 7.4.3 → 7.4.4)
+pnpm run version:patch
+
+# Create prerelease (e.g., 7.4.4 → 7.4.5-RC.0)
+pnpm run version:prerelease
+
+# Create preminor (e.g., 7.4.4 → 7.5.0-RC.0)
+pnpm run version:preminor
+```
+
+## Production
+
+```bash
+# Start server (after build)
+pnpm run server
+
+# Start for CI environments
+pnpm run server:ci
+```
+
+**Note**: `preserver` hook automatically runs migrations before starting.
+
+## CI/CD
+
+```bash
+# Launch dev server for CI
+pnpm run launch-dev:ci
+
+# Start production server for CI
+pnpm run server:ci
+```
+
+## Environment Variables
+
+Development uses `dotenv-flow`:
+
+- `.env` - Default values
+- `.env.local` - Local overrides (not committed)
+- `.env.development` - Development-specific
+- `.env.production` - Production-specific
+
+See `.env.example` for available variables.
+
+## Troubleshooting
+
+### Migration Issues
+
+```bash
+pnpm run dev:migrate:status   # Check status
+pnpm run dev:migrate:down     # Rollback
+pnpm run dev:migrate:up       # Re-apply
+```
+
+### Build Issues
+
+```bash
+pnpm run clean                # Clear artifacts
+pnpm run build                # Rebuild
+```

apps/app/.claude/skills/app-specific-patterns/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: app-specific-patterns
+description: GROWI main application (apps/app) specific patterns for Next.js, Jotai, SWR, and testing. Auto-invoked when working in apps/app.
+user-invocable: false
+---
+
+# App Specific Patterns (apps/app)
+
+For general testing patterns, see the global `testing-patterns-with-vitest` skill.
+
+## Next.js Pages Router
+
+### File Naming
+
+Pages must use `.page.tsx` suffix:
+
+```
+pages/
+├── _app.page.tsx           # App wrapper
+├── [[...path]]/index.page.tsx  # Catch-all wiki pages
+└── admin/index.page.tsx    # Admin pages
+```
+
+### getLayout Pattern
+
+```typescript
+// pages/admin/index.page.tsx
+import type { NextPageWithLayout } from '~/interfaces/next-page';
+
+const AdminPage: NextPageWithLayout = () => <AdminDashboard />;
+
+AdminPage.getLayout = (page) => <AdminLayout>{page}</AdminLayout>;
+
+export default AdminPage;
+```
+
+## Jotai State Management
+
+### Directory Structure
+
+```
+src/states/
+├── ui/
+│   ├── sidebar/              # Multi-file feature
+│   ├── device.ts             # Single-file feature
+│   └── modal/                # 1 modal = 1 file
+│       ├── page-create.ts
+│       └── page-delete.ts
+├── page/                     # Page data state
+├── server-configurations/
+└── context.ts
+
+features/{name}/client/states/  # Feature-scoped atoms
+```
+
+### Placement Rules
+
+| Category | Location |
+|----------|----------|
+| UI state | `states/ui/` |
+| Modal state | `states/ui/modal/` (1 file per modal) |
+| Page data | `states/page/` |
+| Feature-specific | `features/{name}/client/states/` |
+
+### Derived Atoms
+
+```typescript
+import { atom } from 'jotai';
+
+export const currentPageAtom = atom<Page | null>(null);
+
+// Derived (read-only)
+export const currentPagePathAtom = atom((get) => {
+  return get(currentPageAtom)?.path ?? null;
+});
+```
+
+## SWR Data Fetching
+
+### Directory
+
+```
+src/stores-universal/
+├── pages.ts       # Page hooks
+├── users.ts       # User hooks
+└── admin/settings.ts
+```
+
+### Patterns
+
+```typescript
+import useSWR from 'swr';
+import useSWRImmutable from 'swr/immutable';
+
+// Auto-revalidation
+export const usePageList = () => useSWR<Page[]>('/api/v3/pages', fetcher);
+
+// No auto-revalidation (static data)
+export const usePageById = (id: string | null) =>
+  useSWRImmutable<Page>(id ? `/api/v3/pages/${id}` : null, fetcher);
+```
+
+## Testing (apps/app Specific)
+
+### Mocking Next.js Router
+
+```typescript
+import { mockDeep } from 'vitest-mock-extended';
+import type { NextRouter } from 'next/router';
+
+const createMockRouter = (overrides = {}) => {
+  const mock = mockDeep<NextRouter>();
+  mock.pathname = '/test';
+  mock.push.mockResolvedValue(true);
+  return Object.assign(mock, overrides);
+};
+
+vi.mock('next/router', () => ({
+  useRouter: () => createMockRouter(),
+}));
+```
+
+### Testing with Jotai
+
+```typescript
+import { Provider } from 'jotai';
+import { useHydrateAtoms } from 'jotai/utils';
+
+const HydrateAtoms = ({ initialValues, children }) => {
+  useHydrateAtoms(initialValues);
+  return children;
+};
+
+const renderWithJotai = (ui, initialValues = []) => render(
+  <Provider>
+    <HydrateAtoms initialValues={initialValues}>{ui}</HydrateAtoms>
+  </Provider>
+);
+
+// Usage
+renderWithJotai(<PageHeader />, [[currentPageAtom, mockPage]]);
+```
+
+### Testing SWR
+
+```typescript
+import { SWRConfig } from 'swr';
+
+const wrapper = ({ children }) => (
+  <SWRConfig value={{ dedupingInterval: 0, provider: () => new Map() }}>
+    {children}
+  </SWRConfig>
+);
+
+const { result } = renderHook(() => usePageById('123'), { wrapper });
+```
+
+## Path Aliases
+
+Always use `~/` for imports:
+
+```typescript
+import { PageService } from '~/server/services/PageService';
+import { currentPageAtom } from '~/states/page/page-atoms';
+```
+
+## Summary
+
+1. **Next.js**: `.page.tsx` suffix, `getLayout` for layouts
+2. **Jotai**: `states/` global, `features/*/client/states/` feature-scoped
+3. **SWR**: `stores-universal/`, null key for conditional fetch
+4. **Testing**: Mock router, hydrate Jotai, wrap SWR config
+5. **Imports**: Always `~/` path alias

apps/app/AGENTS.md

@@ -1,84 +1,157 @@
-# GROWI Main Application Development Guide
-
-## Overview
-
-This guide provides comprehensive documentation for AI coding agents working on the GROWI main application (`/apps/app/`). GROWI is a team collaboration wiki platform built with Next.js, Express, and MongoDB.
-
-## Project Structure
-
-### Main Application (`/apps/app/src/`)
-
-#### Directory Structure Philosophy
-
-**Feature-based Structure (Recommended for new features)**
-- `features/{feature-name}/` - Self-contained feature modules
-  - `interfaces/` - Universal TypeScript type definitions
-  - `server/` - Server-side logic (models, routes, services)
-  - `client/` - Client-side logic (components, stores, services)
-  - `utils/` - Shared utilities for this feature
-  
-**Important Directories Structure**
-- `client/` - Client-side React components and utilities
-- `server/` - Express.js backend
-- `components/` - Universal React components
-- `pages/` - Next.js Pages Router
-- `states/` - Jotai state management
-- `stores/` - SWR-based state stores
-- `stores-universal/` - Universal SWR-based state stores
-- `styles/` - SCSS stylesheets with modular architecture
-- `migrations/` - MongoDB database migration scripts
-- `interfaces/` - Universal TypeScript type definitions
-- `models/` - Universal Data model definitions
-
-### Key Technical Details
-
-**Frontend Stack**
-- **Framework**: Next.js (Pages Router) with React
-- **Language**: TypeScript (strict mode enabled)
-- **Styling**: SCSS with CSS Modules by Bootstrap 5
-- **State Management**:
-  - **Jotai** (Primary, Recommended): Atomic state management for UI and application state
-  - **SWR**: Data fetching, caching, and revalidation
-  - **Unstated**: Legacy (being phased out, replaced by Jotai)
-- **Testing**: 
-  - Vitest for unit tests (`*.spec.ts`, `*.spec.tsx`)
-  - Jest for integration tests (`*.integ.ts`)
-  - React Testing Library for component testing
-  - Playwright for E2E testing
-- **i18n**: next-i18next for internationalization
-
-**Backend Stack**
-- **Runtime**: Node.js
-- **Framework**: Express.js with TypeScript
-- **Database**: MongoDB with Mongoose ODM
-- **Migration System**: migrate-mongo
-- **Authentication**: Passport.js with multiple strategies (local, LDAP, OAuth, SAML)
-- **Real-time**: Socket.io for collaborative editing and notifications
-- **Search**: Elasticsearch integration (optional)
-- **Observability**: OpenTelemetry integration
-
-**Common Commands**
+# GROWI Main Application (apps/app)
+
+The main GROWI wiki application - a full-stack Next.js application with Express.js backend and MongoDB database.
+
+## Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| **Frontend** | Next.js 14 (Pages Router), React 18 |
+| **Backend** | Express.js with custom server |
+| **Database** | MongoDB with Mongoose ^6.13.6 |
+| **State** | Jotai (UI state) + SWR (server state) |
+| **API** | RESTful API v3 with OpenAPI specs |
+| **Testing** | Vitest, React Testing Library |
+
+## Quick Reference
+
+### Essential Commands
+
 ```bash
-# Type checking only
-cd apps/app && pnpm run lint:typecheck
+# Development
+pnpm run dev                    # Start dev server (or turbo run dev from root)
+pnpm run dev:migrate            # Run database migrations
+
+# Quality Checks
+pnpm run lint:typecheck         # TypeScript type check
+pnpm run lint:biome             # Biome linter
+pnpm run test                   # Run tests
+
+# Build
+pnpm run build                  # Build for production
+```
+
+### Key Directories
+
+```
+src/
+├── pages/                 # Next.js Pages Router (*.page.tsx)
+├── features/             # Feature modules (recommended for new code)
+│   └── {feature-name}/
+│       ├── server/       # Server-side (models, routes, services)
+│       └── client/       # Client-side (components, hooks, states)
+├── server/               # Express server (legacy structure)
+│   ├── models/           # Mongoose models
+│   ├── routes/apiv3/     # API v3 routes
+│   └── services/         # Business logic
+├── components/           # React components (legacy)
+├── states/               # Jotai atoms
+└── stores-universal/     # SWR hooks
+```
+
+## Development Guidelines
+
+### 1. Feature-Based Architecture (New Code)
+
+Create new features in `features/{feature-name}/`:
+
+```
+features/my-feature/
+├── index.ts              # Public exports
+├── interfaces/           # TypeScript types
+├── server/
+│   ├── models/           # Mongoose models
+│   ├── routes/           # Express routes
+│   └── services/         # Business logic
+└── client/
+    ├── components/       # React components
+    ├── hooks/            # Custom hooks
+    └── states/           # Jotai atoms
+```
+
+### 2. State Management
 
-# Run specific test file
-turbo run test:vitest @apps/app -- src/path/to/test.spec.tsx
+- **Jotai**: UI state (modals, forms, selections)
+- **SWR**: Server data (pages, users, API responses)
 
-# Check migration status
-cd apps/app && pnpm run dev:migrate:status
+```typescript
+// Jotai for UI state
+import { atom } from 'jotai';
+export const isModalOpenAtom = atom(false);
 
-# Start REPL with app context
-cd apps/app && pnpm run repl
+// SWR for server data
+import useSWR from 'swr';
+export const usePageById = (id: string) => useSWR(`/api/v3/pages/${id}`);
 ```
 
-### Important Technical Specifications
+### 3. Next.js Pages
+
+Use `.page.tsx` suffix and `getLayout` pattern:
+
+```typescript
+// pages/admin/index.page.tsx
+import type { NextPageWithLayout } from '~/interfaces/next-page';
+
+const AdminPage: NextPageWithLayout = () => <AdminDashboard />;
+AdminPage.getLayout = (page) => <AdminLayout>{page}</AdminLayout>;
+export default AdminPage;
+```
+
+### 4. API Routes (Express)
+
+Add routes to `server/routes/apiv3/` with OpenAPI docs:
+
+```typescript
+/**
+ * @openapi
+ * /api/v3/pages/{id}:
+ *   get:
+ *     summary: Get page by ID
+ */
+router.get('/pages/:id', async (req, res) => {
+  const page = await PageService.findById(req.params.id);
+  res.json(page);
+});
+```
+
+### 5. Path Aliases
+
+Use `~/` for absolute imports:
+
+```typescript
+import { PageService } from '~/server/services/PageService';
+import { Button } from '~/components/Button';
+```
+
+## Before Committing
+
+```bash
+pnpm run lint:typecheck   # 1. Type check
+pnpm run lint:biome       # 2. Lint
+pnpm run test             # 3. Run tests
+pnpm run build            # 4. Verify build (optional)
+```
+
+## Key Features
+
+| Feature | Directory | Description |
+|---------|-----------|-------------|
+| Page Tree | `features/page-tree/` | Hierarchical page navigation |
+| OpenAI | `features/openai/` | AI assistant integration |
+| Search | `features/search/` | Elasticsearch full-text search |
+| Plugins | `features/growi-plugin/` | Plugin system |
+| OpenTelemetry | `features/opentelemetry/` | Monitoring/telemetry |
+
+## Skills (Auto-Loaded)
+
+When working in this directory, these skills are automatically loaded:
+
+- **app-architecture** - Directory structure, feature-based patterns
+- **app-commands** - apps/app specific commands (migrations, OpenAPI, etc.)
+- **app-specific-patterns** - Jotai/SWR/Next.js patterns, testing
 
-**Entry Points**
-- **Server**: `server/app.ts` - Handles OpenTelemetry initialization and Crowi server startup
-- **Client**: `pages/_app.page.tsx` - Root Next.js application component
-  - `pages/[[...path]]/` - Dynamic catch-all page routes
+Plus all global skills (monorepo-overview, tech-stack, testing-patterns-with-vitest).
 
 ---
 
-*This guide was compiled from project memory files to assist AI coding agents in understanding the GROWI application architecture and development practices.*
+For detailed patterns and examples, refer to the Skills in `.claude/skills/`.

apps/app/config/next-i18next.config.d.ts

@@ -0,0 +1,4 @@
+import type { UserConfig } from 'next-i18next';
+
+declare const config: UserConfig;
+export = config;

apps/app/jest.config.js

@@ -1,86 +0,0 @@
-// For a detailed explanation regarding each configuration property, visit:
-// https://jestjs.io/docs/en/configuration.html
-
-const MODULE_NAME_MAPPING = {
-  '^\\^/(.+)$': '<rootDir>/$1',
-  '^~/(.+)$': '<rootDir>/src/$1',
-};
-
-module.exports = {
-  // Indicates whether each individual test should be reported during the run
-  verbose: true,
-
-  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx'],
-
-  projects: [
-    {
-      displayName: 'server',
-
-      transform: {
-        '^.+\\.(t|j)sx?$': '@swc-node/jest',
-      },
-
-      rootDir: '.',
-      roots: ['<rootDir>'],
-      testMatch: [
-        '<rootDir>/test/integration/**/*.test.ts',
-        '<rootDir>/test/integration/**/*.test.js',
-      ],
-      // https://regex101.com/r/jTaxYS/1
-      modulePathIgnorePatterns: [
-        '<rootDir>/test/integration/*.*/v5(..*)*.[t|j]s',
-      ],
-      testEnvironment: 'node',
-      globalSetup: '<rootDir>/test/integration/global-setup.js',
-      globalTeardown: '<rootDir>/test/integration/global-teardown.js',
-      setupFilesAfterEnv: ['<rootDir>/test/integration/setup.js'],
-
-      // Automatically clear mock calls and instances between every test
-      clearMocks: true,
-      moduleNameMapper: MODULE_NAME_MAPPING,
-    },
-    {
-      displayName: 'server-v5',
-
-      transform: {
-        '^.+\\.(t|j)sx?$': '@swc-node/jest',
-      },
-
-      rootDir: '.',
-      roots: ['<rootDir>'],
-      testMatch: [
-        '<rootDir>/test/integration/**/v5.*.test.ts',
-        '<rootDir>/test/integration/**/v5.*.test.js',
-      ],
-
-      testEnvironment: 'node',
-      globalSetup: '<rootDir>/test/integration/global-setup.js',
-      globalTeardown: '<rootDir>/test/integration/global-teardown.js',
-      setupFilesAfterEnv: ['<rootDir>/test/integration/setup.js'],
-
-      // Automatically clear mock calls and instances between every test
-      clearMocks: true,
-      moduleNameMapper: MODULE_NAME_MAPPING,
-    },
-  ],
-
-  // Automatically clear mock calls and instances between every test
-  clearMocks: true,
-
-  // Indicates whether the coverage information should be collected while executing the test
-  collectCoverage: true,
-
-  // An array of glob patterns indicating a set of files for which coverage information should be collected
-  // collectCoverageFrom: undefined,
-
-  // The directory where Jest should output its coverage files
-  coverageDirectory: 'coverage',
-
-  // An array of regexp pattern strings used to skip coverage collection
-  coveragePathIgnorePatterns: [
-    'index.ts',
-    '/config/',
-    '/resource/',
-    '/node_modules/',
-  ],
-};

apps/app/nodemon.json

@@ -9,7 +9,6 @@
     "src/client",
     "src/**/client",
     "test",
-    "test-with-vite",
     "tmp",
     "*.mongodb.js"
   ]

apps/app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@growi/app",
-  "version": "7.4.3",
+  "version": "7.4.4-RC.0",
   "license": "MIT",
   "private": "true",
   "scripts": {
@@ -26,7 +26,7 @@
     "dev:migrate:down": "pnpm run dev:migrate-mongo down -f config/migrate-mongo-config.js",
     "//// for CI": "",
     "launch-dev:ci": "cross-env NODE_ENV=development pnpm run dev:migrate && pnpm run ts-node src/server/app.ts --ci",
-    "lint:typecheck": "vue-tsc --noEmit",
+    "lint:typecheck": "tsgo --noEmit",
     "lint:biome": "biome check --diagnostic-level=error",
     "lint:styles": "stylelint \"src/**/*.scss\"",
     "lint:openapi:apiv3": "node node_modules/swagger2openapi/oas-validate tmp/openapi-spec-apiv3.json",
@@ -34,12 +34,11 @@
     "lint": "run-p lint:**",
     "prelint:openapi:apiv3": "pnpm run openapi:generate-spec:apiv3",
     "prelint:openapi:apiv1": "pnpm run openapi:generate-spec:apiv1",
-    "test": "run-p test:jest test:vitest:coverage",
-    "test:jest": "cross-env NODE_ENV=test TS_NODE_PROJECT=test/integration/tsconfig.json jest",
-    "test:vitest": "vitest run",
-    "test:vitest:coverage": "COLUMNS=200 vitest run --coverage",
-    "jest:run": "cross-env NODE_ENV=test TS_NODE_PROJECT=test/integration/tsconfig.json jest --passWithNoTests -- ",
-    "reg:run": "reg-suit run",
+    "test": "vitest run",
+    "test:coverage": "run-p test:coverage:* test:integ",
+    "test:coverage:unit": "COLUMNS=200 vitest run --coverage --project=app-unit",
+    "test:coverage:components": "COLUMNS=200 vitest run --coverage --project=app-components",
+    "test:integ": "vitest run --project=app-integration",
     "//// misc": "",
     "console": "npm run repl",
     "repl": "cross-env NODE_ENV=development npm run ts-node src/server/repl.ts",
@@ -274,8 +273,6 @@
     "@headless-tree/react": "^1.5.3",
     "@next/bundle-analyzer": "^14.1.3",
     "@popperjs/core": "^2.11.8",
-    "@swc-node/jest": "^1.8.1",
-    "@swc/jest": "^0.2.36",
     "@tanstack/react-virtual": "^3.13.12",
     "@testing-library/jest-dom": "^6.5.0",
     "@testing-library/user-event": "^14.5.2",
@@ -283,7 +280,6 @@
     "@types/bunyan": "^1.8.11",
     "@types/express": "^4.17.21",
     "@types/hast": "^3.0.4",
-    "@types/jest": "^29.5.2",
     "@types/js-cookie": "^3.0.6",
     "@types/ldapjs": "^2.2.5",
     "@types/mdast": "^4.0.4",
@@ -316,14 +312,12 @@
     "i18next-hmr": "^3.1.3",
     "i18next-http-backend": "^2.6.2",
     "i18next-localstorage-backend": "^4.2.0",
-    "jest": "^29.5.0",
-    "jest-date-mock": "^1.0.8",
-    "jest-localstorage-mock": "^2.4.14",
     "jotai-devtools": "^0.11.0",
     "load-css-file": "^1.0.0",
     "material-icons": "^1.11.3",
     "mdast-util-directive": "^3.0.0",
     "mdast-util-find-and-replace": "^3.0.1",
+    "mongodb-connection-string-url": "^7.0.0",
     "mongodb-memory-server-core": "^9.1.1",
     "morgan": "^1.10.0",
     "null-loader": "^4.0.1",

apps/app/playwright/30-search/search.spect.ts → apps/app/playwright/30-search/search.spec.ts

@@ -239,3 +239,70 @@ test('Search current tree by word is successfully loaded', async ({ page }) => {
   await expect(page.getByTestId('search-result-list')).toBeVisible();
   await expect(page.getByTestId('search-result-content')).toBeVisible();
 });
+
+test.describe('Search result navigation and repeated search', () => {
+  test('Repeated search works', async ({ page }) => {
+    // Step 1: Start from the home page and reload to clear any state
+    await page.goto('/');
+    await page.reload();
+
+    // Step 2: Open search modal and search for "sandbox"
+    await page.getByTestId('open-search-modal-button').click();
+    await expect(page.getByTestId('search-modal')).toBeVisible();
+    await page.locator('.form-control').fill('sandbox');
+
+    // Step 3: Submit the search by clicking on "search in all" menu item
+    await expect(page.getByTestId('search-all-menu-item')).toBeVisible();
+    await page.getByTestId('search-all-menu-item').click();
+
+    // Step 4: Verify that the search page is displayed with results
+    await expect(page.getByTestId('search-result-base')).toBeVisible();
+    await expect(page.getByTestId('search-result-list')).toBeVisible();
+    await expect(page.getByTestId('search-result-content')).toBeVisible();
+    await expect(page).toHaveURL(/\/_search\?q=sandbox/);
+
+    // Step 5: Click on the first search result to navigate to a page
+    const sandboxPageLink = page
+      .getByTestId('search-result-list')
+      .getByRole('link', { name: 'Sandbox' })
+      .first();
+    await sandboxPageLink.click();
+    await expect(page).toHaveTitle(/Sandbox/);
+
+    // Step 6: Wait for leaving search results and verify page content is displayed
+    await expect(page.getByTestId('search-result-base')).not.toBeVisible();
+    // Verify page body is rendered (not empty due to stale atom data)
+    await expect(page.locator('.wiki')).toBeVisible();
+    await expect(page.locator('.wiki')).not.toBeEmpty();
+
+    // Step 7: From the navigated page, open search modal again
+    await page.getByTestId('open-search-modal-button').click();
+    await expect(page.getByTestId('search-modal')).toBeVisible();
+
+    // Step 8: Search for the same keyword ("sandbox")
+    await page.locator('.form-control').fill('sandbox');
+
+    // Step 9: Submit the search by clicking on "search in all" menu item
+    await expect(page.getByTestId('search-all-menu-item')).toBeVisible();
+    await page.getByTestId('search-all-menu-item').click();
+
+    // Step 10: Verify that the search page is displayed with results
+    await expect(page.getByTestId('search-result-base')).toBeVisible();
+    await expect(page.getByTestId('search-result-list')).toBeVisible();
+    await expect(page.getByTestId('search-result-content')).toBeVisible();
+    await expect(page).toHaveURL(/\/_search\?q=sandbox/);
+
+    // Step 11: Click on the second search result to navigate to a page
+    const mathPageLink = page
+      .getByTestId('search-result-list')
+      .getByRole('link', { name: 'Math' })
+      .first();
+    await mathPageLink.click();
+    // and verify the page that is not Sandbox is loaded
+    await expect(page).not.toHaveTitle(/Sandbox/);
+
+    // Step 12: Verify page body is rendered (not empty due to stale atom data)
+    await expect(page.locator('.wiki')).toBeVisible();
+    await expect(page.locator('.wiki')).not.toBeEmpty();
+  });
+});

apps/app/public/static/locales/ja_JP/admin.json

@@ -456,6 +456,18 @@
       "tag_names": "タグ名",
       "tag_attributes": "タグ属性",
       "import_recommended": "{{target}} のおすすめをインポート"
+    },
+    "content-disposition_header": "Content-Disposition MIMEタイプ設定",
+    "content-disposition_options": {
+      "add_header": "MIMEタイプを追加する",
+      "note": "注意: MIMEタイプを追加すると、もう一方のリストからは自動的に削除されます。",
+      "inline_header": "インライン MIMEタイプ",
+      "attachment_header": "添付ファイル MIMEタイプ",
+      "inline_button": "インライン",
+      "no_inline": "設定済みのインラインタイプはありません。",
+      "no_attachment": "設定済みの添付ファイルタイプはありません。",
+      "attachment_button": "添付ファイル",
+      "remove_button": "削除"
     }
   },
   "customize_settings": {

apps/app/src/client/components/Admin/Customize/CustomizeLogoSetting.tsx

@@ -1,4 +1,4 @@
-import React, { type JSX, useCallback, useState } from 'react';
+import React, { type JSX, useCallback, useRef, useState } from 'react';
 import { useAtomValue, useSetAtom } from 'jotai';
 import { useTranslation } from 'react-i18next';
 
@@ -32,6 +32,14 @@ const CustomizeLogoSetting = (): JSX.Element => {
     isDefaultLogo ?? true,
   );
   const [retrieveError, setRetrieveError] = useState<any>();
+  const fileInputRef = useRef<HTMLInputElement | null>(null);
+  const isSystemError: boolean = retrieveError != null;
+  const isLogoSettingIncomplete: boolean =
+    !isDefaultLogoSelected &&
+    uploadLogoSrc == null &&
+    !isCustomizedLogoUploaded;
+  const isUpdateButtonDisabled: boolean =
+    isSystemError || isLogoSettingIncomplete;
 
   const onSelectFile = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
     if (e.target.files != null && e.target.files.length > 0) {
@@ -58,6 +66,22 @@ const CustomizeLogoSetting = (): JSX.Element => {
     }
   }, [t, isDefaultLogoSelected]);
 
+  const clearFileInput = useCallback(() => {
+    if (fileInputRef.current) {
+      fileInputRef.current.value = '';
+    }
+  }, []);
+
+  const resetFileSelectionState = useCallback(() => {
+    clearFileInput();
+    setUploadLogoSrc(null);
+  }, [clearFileInput]);
+
+  const onCloseCropModal = useCallback(() => {
+    resetFileSelectionState();
+    setIsImageCropModalShow(false);
+  }, [resetFileSelectionState]);
+
   const onClickDeleteBtn = useCallback(async () => {
     try {
       await apiv3Delete('/customize-setting/delete-brand-logo');
@@ -68,12 +92,13 @@ const CustomizeLogoSetting = (): JSX.Element => {
           ns: 'commons',
         }),
       );
+      resetFileSelectionState();
     } catch (err) {
       toastError(err);
       setRetrieveError(err);
       throw new Error('Failed to delete logo');
     }
-  }, [setIsCustomizedLogoUploaded, t]);
+  }, [setIsCustomizedLogoUploaded, t, resetFileSelectionState]);
 
   const processImageCompletedHandler = useCallback(
     async (croppedImage) => {
@@ -196,6 +221,7 @@ const CustomizeLogoSetting = (): JSX.Element => {
                       onChange={onSelectFile}
                       name="brandLogo"
                       accept="image/*"
+                      ref={fileInputRef}
                     />
                   </div>
                 </div>
@@ -203,7 +229,7 @@ const CustomizeLogoSetting = (): JSX.Element => {
             </div>
             <AdminUpdateButtonRow
               onClick={onClickSubmit}
-              disabled={retrieveError != null}
+              disabled={isUpdateButtonDisabled}
             />
           </div>
         </div>
@@ -212,7 +238,7 @@ const CustomizeLogoSetting = (): JSX.Element => {
       <ImageCropModal
         isShow={isImageCropModalShow}
         src={uploadLogoSrc}
-        onModalClose={() => setIsImageCropModalShow(false)}
+        onModalClose={onCloseCropModal}
         onImageProcessCompleted={processImageCompletedHandler}
         isCircular={false}
         showCropOption={false}

apps/app/src/client/components/Admin/Security/LdapAuthTestModal.jsx

@@ -56,6 +56,9 @@ LdapAuthTestModal.propTypes = {
   onClose: PropTypes.func.isRequired,
 };
 
+/**
+ * @type {React.ComponentType<{ isOpen: boolean, onClose: () => void }>}
+ */
 const LdapAuthTestModalWrapper = withUnstatedContainers(LdapAuthTestModal, []);
 
 export default LdapAuthTestModalWrapper;

apps/app/src/client/components/Admin/Users/GrantAdminButton.tsx

@@ -7,11 +7,14 @@ import { toastError, toastSuccess } from '~/client/util/toastr';
 
 import { withUnstatedContainers } from '../../UnstatedUtils';
 
-type GrantAdminButtonProps = {
-  adminUsersContainer: AdminUsersContainer;
+type GrantAdminButtonExternalProps = {
   user: IUserHasId;
 };
 
+type GrantAdminButtonProps = GrantAdminButtonExternalProps & {
+  adminUsersContainer: AdminUsersContainer;
+};
+
 const GrantAdminButton = (props: GrantAdminButtonProps): JSX.Element => {
   const { t } = useTranslation('admin');
   const { adminUsersContainer, user } = props;
@@ -40,8 +43,9 @@ const GrantAdminButton = (props: GrantAdminButtonProps): JSX.Element => {
 /**
  * Wrapper component for using unstated
  */
-const GrantAdminButtonWrapper: React.ForwardRefExoticComponent<
-  Pick<any, string | number | symbol> & React.RefAttributes<any>
-> = withUnstatedContainers(GrantAdminButton, [AdminUsersContainer]);
+const GrantAdminButtonWrapper = withUnstatedContainers<
+  GrantAdminButtonExternalProps,
+  GrantAdminButtonProps
+>(GrantAdminButton, [AdminUsersContainer]);
 
 export default GrantAdminButtonWrapper;

apps/app/src/client/components/Admin/Users/SendInvitationEmailButton.jsx

@@ -55,6 +55,9 @@ const SendInvitationEmailButton = (props) => {
   );
 };
 
+/**
+ * @type {React.ComponentType<{ user: import('@growi/core').IUserHasId, isInvitationEmailSended: boolean, onSuccessfullySentInvitationEmail: () => void }>}
+ */
 const SendInvitationEmailButtonWrapper = withUnstatedContainers(
   SendInvitationEmailButton,
   [AdminUsersContainer],

apps/app/src/client/components/Admin/Users/StatusActivateButton.jsx

@@ -52,6 +52,7 @@ const StatusActivateFormWrapperFC = (props) => {
 
 /**
  * Wrapper component for using unstated
+ * @type {React.ComponentType<{ user: import('@growi/core').IUserHasId }>}
  */
 const StatusActivateFormWrapper = withUnstatedContainers(
   StatusActivateFormWrapperFC,

apps/app/src/client/components/Admin/Users/UserMenu.tsx

@@ -18,11 +18,14 @@ import UserRemoveButton from './UserRemoveButton';
 
 import styles from './UserMenu.module.scss';
 
-type UserMenuProps = {
-  adminUsersContainer: AdminUsersContainer;
+type UserMenuExternalProps = {
   user: IUserHasId;
 };
 
+type UserMenuProps = UserMenuExternalProps & {
+  adminUsersContainer: AdminUsersContainer;
+};
+
 const UserMenu = (props: UserMenuProps) => {
   const { t } = useTranslation('admin');
 
@@ -146,8 +149,9 @@ const UserMenu = (props: UserMenuProps) => {
 /**
  * Wrapper component for using unstated
  */
-const UserMenuWrapper: React.ForwardRefExoticComponent<
-  Pick<any, string | number | symbol> & React.RefAttributes<any>
-> = withUnstatedContainers(UserMenu, [AdminUsersContainer]);
+const UserMenuWrapper = withUnstatedContainers<
+  UserMenuExternalProps,
+  UserMenuProps
+>(UserMenu, [AdminUsersContainer]);
 
 export default UserMenuWrapper;

apps/app/src/client/components/Admin/Users/UserRemoveButton.jsx

@@ -60,6 +60,7 @@ const UserRemoveButtonWrapperFC = (props) => {
 
 /**
  * Wrapper component for using unstated
+ * @type {React.ComponentType<{ user: import('@growi/core').IUserHasId }>}
  */
 const UserRemoveButtonWrapper = withUnstatedContainers(
   UserRemoveButtonWrapperFC,

apps/app/src/client/components/Admin/Users/UserTable.tsx

@@ -10,7 +10,9 @@ import { withUnstatedContainers } from '../../UnstatedUtils';
 import { SortIcons } from './SortIcons';
 import UserMenu from './UserMenu';
 
-type UserTableProps = {
+type UserTableExternalProps = Record<string, never>;
+
+type UserTableProps = UserTableExternalProps & {
   adminUsersContainer: AdminUsersContainer;
 };
 
@@ -189,8 +191,9 @@ const UserTable = (props: UserTableProps) => {
   );
 };
 
-const UserTableWrapper = withUnstatedContainers(UserTable, [
-  AdminUsersContainer,
-]);
+const UserTableWrapper = withUnstatedContainers<
+  UserTableExternalProps,
+  UserTableProps
+>(UserTable, [AdminUsersContainer]);
 
 export default UserTableWrapper;

apps/app/src/client/components/InstallerForm.tsx

@@ -5,7 +5,7 @@ import { AllLang, Lang } from '@growi/core';
 import { LoadingSpinner } from '@growi/ui/dist/components';
 import { useTranslation } from 'next-i18next';
 
-import { i18n as i18nConfig } from '^/config/next-i18next.config';
+import * as nextI18nConfig from '^/config/next-i18next.config';
 
 import { apiv3Post } from '~/client/util/apiv3-client';
 import { useTWithOpt } from '~/client/util/t-with-opt';
@@ -16,6 +16,8 @@ import styles from './InstallerForm.module.scss';
 
 const moduleClass = styles['installer-form'] ?? '';
 
+const i18nConfig = nextI18nConfig.i18n;
+
 type Props = {
   minPasswordLength: number;
 };

apps/app/src/client/components/Me/AccessTokenScopeList.tsx

@@ -9,6 +9,8 @@ import styles from './AccessTokenScopeList.module.scss';
 
 const moduleClass = styles['access-token-scope-list'] ?? '';
 
+// biome-ignore lint/suspicious/noTsIgnore: Suppress auto fix by lefthook
+// @ts-ignore - Scope type causes "Type instantiation is excessively deep" with tsgo
 interface scopeObject {
   [key: string]: Scope | scopeObject;
 }

apps/app/src/client/components/Me/BasicInfoSettings.tsx

@@ -1,9 +1,9 @@
-import React, { type JSX, useEffect, useState } from 'react';
+import { type JSX, useEffect, useState } from 'react';
 import type { IUser } from '@growi/core/dist/interfaces';
 import { useAtomValue } from 'jotai';
 import { i18n, useTranslation } from 'next-i18next';
 
-import { i18n as i18nConfig } from '^/config/next-i18next.config';
+import * as nextI18nConfig from '^/config/next-i18next.config';
 
 import { toastError, toastSuccess } from '~/client/util/toastr';
 import { registrationWhitelistAtom } from '~/states/server-configurations';
@@ -12,6 +12,8 @@ import {
   useUpdateBasicInfo,
 } from '~/stores/personal-settings';
 
+const i18nConfig = nextI18nConfig.i18n;
+
 export const BasicInfoSettings = (): JSX.Element => {
   const { t } = useTranslation();
   const registrationWhitelist = useAtomValue(registrationWhitelistAtom);

apps/app/src/client/components/Navbar/GrowiContextualSubNavigation.tsx

@@ -191,7 +191,7 @@ const PageOperationMenuItems = (
             <DropdownItem
               onClick={openPageBulkExportSelectModal}
               className="grw-page-control-dropdown-item"
-              disabled={!isUploadEnabled ?? true}
+              disabled={!isUploadEnabled}
             >
               <span className="material-symbols-outlined me-1 grw-page-control-dropdown-icon">
                 cloud_download

apps/app/src/client/components/UnstatedUtils.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Subscribe } from 'unstated';
+import { type Container, Subscribe } from 'unstated';
 
 /**
  * generate K/V object by specified instances
@@ -41,21 +41,35 @@ function generateAutoNamedProps(instances) {
  *    )}
  *  </Subscribe>
  */
-export function withUnstatedContainers<T, P>(
-  Component,
-  containerClasses,
+export function withUnstatedContainers<
+  ExternalProps extends Record<string, unknown>,
+  InternalProps extends ExternalProps = ExternalProps,
+>(
+  Component: React.ComponentType<InternalProps>,
+  containerClasses: (typeof Container)[],
 ): React.ForwardRefExoticComponent<
-  React.PropsWithoutRef<P> & React.RefAttributes<T>
+  React.PropsWithoutRef<ExternalProps> & React.RefAttributes<unknown>
 > {
-  const unstatedContainer = React.forwardRef<T, P>((props, ref) => (
-    // wrap with <Subscribe></Subscribe>
-    <Subscribe to={containerClasses}>
-      {(...containers) => {
-        const propsForContainers = generateAutoNamedProps(containers);
-        return <Component {...props} {...propsForContainers} ref={ref} />;
-      }}
-    </Subscribe>
-  ));
+  const unstatedContainer = React.forwardRef<unknown, ExternalProps>(
+    (props, ref) => (
+      // wrap with <Subscribe></Subscribe>
+      <Subscribe to={containerClasses}>
+        {(...containers) => {
+          // Container props are dynamically generated based on class names
+          const propsForContainers = generateAutoNamedProps(containers) as Omit<
+            InternalProps,
+            keyof ExternalProps
+          >;
+          const mergedProps = {
+            ...props,
+            ...propsForContainers,
+            ref,
+          } as InternalProps & { ref: typeof ref };
+          return <Component {...mergedProps} />;
+        }}
+      </Subscribe>
+    ),
+  );
   unstatedContainer.displayName = 'unstatedContainer';
   return unstatedContainer;
 }

apps/app/src/client/util/scope-util.ts

@@ -17,8 +17,9 @@ function parseSubScope(
 
   for (const action of actions) {
     if (typeof subObjForActions[action] === 'string') {
+      // Safe: parseScopes only accepts SCOPE constant which contains valid Scope strings
       result[`${action.toLowerCase()}:${parentKey.toLowerCase()}`] =
-        subObjForActions[action];
+        subObjForActions[action] as Scope;
       subObjForActions[action] = undefined;
     }
   }
@@ -38,6 +39,7 @@ function parseSubScope(
       for (const action of actions) {
         const val = subObjForActions[action]?.[ck];
         if (typeof val === 'string') {
+          // Safe: parseScopes only accepts SCOPE constant which contains valid Scope strings
           result[`${action.toLowerCase()}:${parentKey.toLowerCase()}:all`] =
             val as Scope;
         }
@@ -87,6 +89,7 @@ export function parseScopes({
       for (const action of actions) {
         const val = scopes[action]?.[key];
         if (typeof val === 'string') {
+          // Safe: parseScopes only accepts SCOPE constant which contains valid Scope strings
           allObj[`${action.toLowerCase()}:all`] = val as Scope;
         }
       }

apps/app/src/components/PageView/PageAlerts/FixPageGrantAlert/FixPageGrantAlert.tsx

@@ -61,7 +61,7 @@ export const FixPageGrantAlert = (): JSX.Element => {
   const currentUser = useCurrentUser();
   const pageData = useCurrentPageData();
 
-  const hasParent = pageData?.parent != null ?? false;
+  const hasParent = pageData?.parent != null;
   const pageId = pageData?._id;
 
   const { data: dataIsGrantNormalized } = useSWRxCurrentGrantData(

apps/app/src/features/external-user-group/server/routes/apiv3/external-user-group-relation.ts

@@ -6,6 +6,8 @@ import type { IExternalUserGroupRelationHasId } from '~/features/external-user-g
 import ExternalUserGroupRelation from '~/features/external-user-group/server/models/external-user-group-relation';
 import type Crowi from '~/server/crowi';
 import { accessTokenParser } from '~/server/middlewares/access-token-parser';
+import adminRequiredFactory from '~/server/middlewares/admin-required';
+import loginRequiredFactory from '~/server/middlewares/login-required';
 import { serializeUserGroupRelationSecurely } from '~/server/models/serializers/user-group-relation-serializer';
 import type { ApiV3Response } from '~/server/routes/apiv3/interfaces/apiv3-response';
 import loggerFactory from '~/utils/logger';
@@ -14,14 +16,11 @@ const logger = loggerFactory('growi:routes:apiv3:user-group-relation');
 
 const express = require('express');
 const { query } = require('express-validator');
-
 const router = express.Router();
 
 module.exports = (crowi: Crowi): Router => {
-  const loginRequiredStrictly = require('~/server/middlewares/login-required')(
-    crowi,
-  );
-  const adminRequired = require('~/server/middlewares/admin-required')(crowi);
+  const loginRequiredStrictly = loginRequiredFactory(crowi);
+  const adminRequired = adminRequiredFactory(crowi);
 
   const validators = {
     list: [

apps/app/src/features/external-user-group/server/routes/apiv3/external-user-group.ts

@@ -12,7 +12,9 @@ import type { PageActionOnGroupDelete } from '~/interfaces/user-group';
 import type Crowi from '~/server/crowi';
 import { accessTokenParser } from '~/server/middlewares/access-token-parser';
 import { generateAddActivityMiddleware } from '~/server/middlewares/add-activity';
+import adminRequiredFactory from '~/server/middlewares/admin-required';
 import { apiV3FormValidator } from '~/server/middlewares/apiv3-form-validator';
+import loginRequiredFactory from '~/server/middlewares/login-required';
 import { serializeUserGroupRelationSecurely } from '~/server/models/serializers/user-group-relation-serializer';
 import type { ApiV3Response } from '~/server/routes/apiv3/interfaces/apiv3-response';
 import { configManager } from '~/server/service/config-manager';
@@ -43,13 +45,11 @@ interface AuthorizedRequest extends Request {
  *            type: number
  */
 module.exports = (crowi: Crowi): Router => {
-  const loginRequiredStrictly = require('~/server/middlewares/login-required')(
-    crowi,
-  );
-  const adminRequired = require('~/server/middlewares/admin-required')(crowi);
+  const loginRequiredStrictly = loginRequiredFactory(crowi);
+  const adminRequired = adminRequiredFactory(crowi);
   const addActivity = generateAddActivityMiddleware();
 
-  const activityEvent = crowi.event('activity');
+  const activityEvent = crowi.events.activity;
 
   const isExecutingSync = () => {
     return (

apps/app/test/integration/service/external-user-group-sync.test.ts → apps/app/src/features/external-user-group/server/service/external-user-group-sync.integ.ts

@@ -1,21 +1,35 @@
-import type { IUserHasId } from '@growi/core';
+import type { IPage, IUserHasId } from '@growi/core';
 import mongoose, { Types } from 'mongoose';
-
 import {
-  ExternalGroupProviderType,
-  type ExternalUserGroupTreeNode,
-  type IExternalUserGroup,
-  type IExternalUserGroupHasId,
-} from '../../../src/features/external-user-group/interfaces/external-user-group';
-import ExternalUserGroup from '../../../src/features/external-user-group/server/models/external-user-group';
-import ExternalUserGroupRelation from '../../../src/features/external-user-group/server/models/external-user-group-relation';
-import ExternalUserGroupSyncService from '../../../src/features/external-user-group/server/service/external-user-group-sync';
-import type Crowi from '../../../src/server/crowi';
-import ExternalAccount from '../../../src/server/models/external-account';
-import { configManager } from '../../../src/server/service/config-manager';
-import instanciateExternalAccountService from '../../../src/server/service/external-account';
-import PassportService from '../../../src/server/service/passport';
-import { getInstance } from '../setup-crowi';
+  afterEach,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+  vi,
+} from 'vitest';
+import { mock } from 'vitest-mock-extended';
+
+import { getInstance } from '^/test/setup/crowi';
+
+import type Crowi from '~/server/crowi';
+import ExternalAccount from '~/server/models/external-account';
+import type { PageModel } from '~/server/models/page';
+import { configManager } from '~/server/service/config-manager';
+import instanciateExternalAccountService from '~/server/service/external-account';
+import type PassportService from '~/server/service/passport';
+import type { S2sMessagingService } from '~/server/service/s2s-messaging/base';
+
+import type {
+  ExternalUserGroupTreeNode,
+  IExternalUserGroup,
+  IExternalUserGroupHasId,
+} from '../../interfaces/external-user-group';
+import { ExternalGroupProviderType } from '../../interfaces/external-user-group';
+import ExternalUserGroup from '../models/external-user-group';
+import ExternalUserGroupRelation from '../models/external-user-group-relation';
+import ExternalUserGroupSyncService from './external-user-group-sync';
 
 // dummy class to implement generateExternalUserGroupTrees which returns test data
 class TestExternalUserGroupSyncService extends ExternalUserGroupSyncService {
@@ -41,7 +55,6 @@ class TestExternalUserGroupSyncService extends ExternalUserGroupSyncService {
     };
     const parentNode: ExternalUserGroupTreeNode = {
       id: 'cn=parentGroup,ou=groups,dc=example,dc=org',
-      // name is undefined
       userInfos: [
         {
           id: 'parentGroupUser',
@@ -55,7 +68,6 @@ class TestExternalUserGroupSyncService extends ExternalUserGroupSyncService {
     };
     const grandParentNode: ExternalUserGroupTreeNode = {
       id: 'cn=grandParentGroup,ou=groups,dc=example,dc=org',
-      // email is undefined
       userInfos: [
         {
           id: 'grandParentGroupUser',
@@ -87,8 +99,6 @@ class TestExternalUserGroupSyncService extends ExternalUserGroupSyncService {
   }
 }
 
-const testService = new TestExternalUserGroupSyncService(null, null);
-
 const checkGroup = (
   group: IExternalUserGroupHasId,
   expected: Omit<IExternalUserGroup, 'createdAt'>,
@@ -107,7 +117,8 @@ const checkSync = async (autoGenerateUserOnGroupSync = true) => {
   const grandParentGroup = await ExternalUserGroup.findOne({
     name: 'grandParentGroup',
   });
-  checkGroup(grandParentGroup, {
+  expect(grandParentGroup).not.toBeNull();
+  checkGroup(grandParentGroup!, {
     externalId: 'cn=grandParentGroup,ou=groups,dc=example,dc=org',
     name: 'grandParentGroup',
     description: 'this is a grand parent group',
@@ -116,27 +127,30 @@ const checkSync = async (autoGenerateUserOnGroupSync = true) => {
   });
 
   const parentGroup = await ExternalUserGroup.findOne({ name: 'parentGroup' });
-  checkGroup(parentGroup, {
+  expect(parentGroup).not.toBeNull();
+  checkGroup(parentGroup!, {
     externalId: 'cn=parentGroup,ou=groups,dc=example,dc=org',
     name: 'parentGroup',
     description: 'this is a parent group',
     provider: 'ldap',
-    parent: grandParentGroup._id,
+    parent: grandParentGroup!._id,
   });
 
   const childGroup = await ExternalUserGroup.findOne({ name: 'childGroup' });
-  checkGroup(childGroup, {
+  expect(childGroup).not.toBeNull();
+  checkGroup(childGroup!, {
     externalId: 'cn=childGroup,ou=groups,dc=example,dc=org',
     name: 'childGroup',
     description: 'this is a child group',
     provider: 'ldap',
-    parent: parentGroup._id,
+    parent: parentGroup!._id,
   });
 
   const previouslySyncedGroup = await ExternalUserGroup.findOne({
     name: 'previouslySyncedGroup',
   });
-  checkGroup(previouslySyncedGroup, {
+  expect(previouslySyncedGroup).not.toBeNull();
+  checkGroup(previouslySyncedGroup!, {
     externalId: 'cn=previouslySyncedGroup,ou=groups,dc=example,dc=org',
     name: 'previouslySyncedGroup',
     description: 'this is a previouslySynced group',
@@ -145,16 +159,16 @@ const checkSync = async (autoGenerateUserOnGroupSync = true) => {
   });
 
   const grandParentGroupRelations = await ExternalUserGroupRelation.find({
-    relatedGroup: grandParentGroup._id,
+    relatedGroup: grandParentGroup!._id,
   });
   const parentGroupRelations = await ExternalUserGroupRelation.find({
-    relatedGroup: parentGroup._id,
+    relatedGroup: parentGroup!._id,
   });
   const childGroupRelations = await ExternalUserGroupRelation.find({
-    relatedGroup: childGroup._id,
+    relatedGroup: childGroup!._id,
   });
   const previouslySyncedGroupRelations = await ExternalUserGroupRelation.find({
-    relatedGroup: previouslySyncedGroup._id,
+    relatedGroup: previouslySyncedGroup!._id,
   });
 
   if (autoGenerateUserOnGroupSync) {
@@ -205,7 +219,7 @@ const checkSync = async (autoGenerateUserOnGroupSync = true) => {
       'previouslySyncedGroupUser',
     );
 
-    const userPages = await mongoose.model('Page').find({
+    const userPages = await mongoose.model<IPage>('Page').find({
       path: {
         $in: [
           '/user/childGroupUser',
@@ -225,16 +239,76 @@ const checkSync = async (autoGenerateUserOnGroupSync = true) => {
 };
 
 describe('ExternalUserGroupSyncService.syncExternalUserGroups', () => {
-  let crowi: Crowi;
+  let testService: TestExternalUserGroupSyncService;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let Page: PageModel;
+  let rootPageId: Types.ObjectId;
+  let userPageId: Types.ObjectId;
 
   beforeAll(async () => {
-    crowi = await getInstance();
+    // Initialize configManager
+    const s2sMessagingServiceMock = mock<S2sMessagingService>();
+    configManager.setS2sMessagingService(s2sMessagingServiceMock);
+    await configManager.loadConfigs();
+
+    const crowi: Crowi = await getInstance();
+
+    // Initialize models with crowi mock
+    const pageModule = await import('~/server/models/page');
+    Page = pageModule.default(crowi);
+
+    const userModule = await import('~/server/models/user/index');
+    userModule.default(crowi);
+
+    // Initialize services with mocked PassportService
     await configManager.updateConfig('app:isV5Compatible', true);
-    const passportService = new PassportService(crowi);
-    instanciateExternalAccountService(passportService);
+
+    // Create PassportService mock with required methods for externalAccountService
+    const passportServiceMock = mock<PassportService>({
+      isSameUsernameTreatedAsIdenticalUser: vi.fn().mockReturnValue(false),
+      isSameEmailTreatedAsIdenticalUser: vi.fn().mockReturnValue(false),
+    });
+    instanciateExternalAccountService(passportServiceMock);
+
+    // Create root page and /user page for UserEvent.onActivated to work
+    rootPageId = new Types.ObjectId();
+    userPageId = new Types.ObjectId();
+
+    // Check if root page already exists
+    const existingRootPage = await Page.findOne({ path: '/' });
+    if (existingRootPage == null) {
+      await Page.insertMany([
+        {
+          _id: rootPageId,
+          path: '/',
+          grant: Page.GRANT_PUBLIC,
+        },
+      ]);
+    } else {
+      rootPageId = existingRootPage._id;
+    }
+
+    // Check if /user page already exists
+    const existingUserPage = await Page.findOne({ path: '/user' });
+    if (existingUserPage == null) {
+      await Page.insertMany([
+        {
+          _id: userPageId,
+          path: '/user',
+          grant: Page.GRANT_PUBLIC,
+          parent: rootPageId,
+          isEmpty: true,
+        },
+      ]);
+    } else {
+      userPageId = existingUserPage._id;
+    }
   });
 
   beforeEach(async () => {
+    // Create new testService instance for each test to reset syncStatus
+    testService = new TestExternalUserGroupSyncService(null, null);
+
     await ExternalUserGroup.create({
       name: 'nameBeforeEdit',
       description: 'this is a description before edit',
@@ -284,7 +358,7 @@ describe('ExternalUserGroupSyncService.syncExternalUserGroups', () => {
       'external-user-group:ldap:preserveDeletedGroups': false,
     };
 
-    beforeAll(async () => {
+    beforeEach(async () => {
       await configManager.updateConfigs(configParams);
     });
 
@@ -300,7 +374,7 @@ describe('ExternalUserGroupSyncService.syncExternalUserGroups', () => {
       'external-user-group:ldap:preserveDeletedGroups': true,
     };
 
-    beforeAll(async () => {
+    beforeEach(async () => {
       await configManager.updateConfigs(configParams);
     });
 
@@ -316,7 +390,7 @@ describe('ExternalUserGroupSyncService.syncExternalUserGroups', () => {
       'external-user-group:ldap:preserveDeletedGroups': false,
     };
 
-    beforeAll(async () => {
+    beforeEach(async () => {
       await configManager.updateConfigs(configParams);
 
       const groupId = new Types.ObjectId();

apps/app/test/integration/service/ldap-user-group-sync.test.ts → apps/app/src/features/external-user-group/server/service/ldap-user-group-sync.integ.ts

@@ -1,11 +1,16 @@
 import ldap, { type Client } from 'ldapjs';
+import { beforeAll, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mock } from 'vitest-mock-extended';
 
-import { LdapUserGroupSyncService } from '../../../src/features/external-user-group/server/service/ldap-user-group-sync';
-import type Crowi from '../../../src/server/crowi';
-import { configManager } from '../../../src/server/service/config-manager';
-import { ldapService } from '../../../src/server/service/ldap';
-import PassportService from '../../../src/server/service/passport';
-import { getInstance } from '../setup-crowi';
+import { getInstance } from '^/test/setup/crowi';
+
+import type Crowi from '~/server/crowi';
+import { configManager } from '~/server/service/config-manager';
+import { ldapService } from '~/server/service/ldap';
+import PassportService from '~/server/service/passport';
+import type { S2sMessagingService } from '~/server/service/s2s-messaging/base';
+
+import { LdapUserGroupSyncService } from './ldap-user-group-sync';
 
 describe('LdapUserGroupSyncService.generateExternalUserGroupTrees', () => {
   let crowi: Crowi;
@@ -23,10 +28,10 @@ describe('LdapUserGroupSyncService.generateExternalUserGroupTrees', () => {
       'ldap://openldap:1389/dc=example,dc=org',
   };
 
-  jest.mock('../../../src/server/service/ldap');
-  const mockBind = jest.spyOn(ldapService, 'bind');
-  const mockLdapSearch = jest.spyOn(ldapService, 'search');
-  const mockLdapCreateClient = jest.spyOn(ldap, 'createClient');
+  const mockBind = vi.spyOn(ldapService, 'bind');
+  const mockSearchGroupDir = vi.spyOn(ldapService, 'searchGroupDir');
+  const mockSearch = vi.spyOn(ldapService, 'search');
+  const mockLdapCreateClient = vi.spyOn(ldap, 'createClient');
 
   beforeAll(async () => {
     crowi = await getInstance();
@@ -42,77 +47,79 @@ describe('LdapUserGroupSyncService.generateExternalUserGroupTrees', () => {
     const passportService = new PassportService(crowi);
     ldapUserGroupSyncService = new LdapUserGroupSyncService(
       passportService,
-      null,
+      mock<S2sMessagingService>(),
       null,
     );
   });
 
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
   describe('When there is no circular reference in group tree', () => {
     it('creates ExternalUserGroupTrees', async () => {
-      // mock search on LDAP server
-      mockLdapSearch.mockImplementation((filter, base) => {
-        if (base === 'ou=groups,dc=example,dc=org') {
-          // search groups
-          return Promise.resolve([
+      // mock searchGroupDir for group entries
+      mockSearchGroupDir.mockResolvedValue([
+        {
+          objectName: 'cn=childGroup,ou=groups,dc=example,dc=org',
+          attributes: [
+            { type: 'cn', values: ['childGroup'] },
+            { type: 'description', values: ['this is a child group'] },
             {
-              objectName: 'cn=childGroup,ou=groups,dc=example,dc=org',
-              attributes: [
-                { type: 'cn', values: ['childGroup'] },
-                { type: 'description', values: ['this is a child group'] },
-                {
-                  type: 'member',
-                  values: ['cn=childGroupUser,ou=users,dc=example,dc=org'],
-                },
-              ],
+              type: 'member',
+              values: ['cn=childGroupUser,ou=users,dc=example,dc=org'],
             },
+          ],
+        },
+        {
+          objectName: 'cn=parentGroup,ou=groups,dc=example,dc=org',
+          attributes: [
+            { type: 'cn', values: ['parentGroup'] },
+            { type: 'description', values: ['this is a parent group'] },
             {
-              objectName: 'cn=parentGroup,ou=groups,dc=example,dc=org',
-              attributes: [
-                { type: 'cn', values: ['parentGroup'] },
-                { type: 'description', values: ['this is a parent group'] },
-                {
-                  type: 'member',
-                  values: [
-                    'cn=childGroup,ou=groups,dc=example,dc=org',
-                    'cn=parentGroupUser,ou=users,dc=example,dc=org',
-                  ],
-                },
+              type: 'member',
+              values: [
+                'cn=childGroup,ou=groups,dc=example,dc=org',
+                'cn=parentGroupUser,ou=users,dc=example,dc=org',
               ],
             },
-            // root node
+          ],
+        },
+        // root node
+        {
+          objectName: 'cn=grandParentGroup,ou=groups,dc=example,dc=org',
+          attributes: [
+            { type: 'cn', values: ['grandParentGroup'] },
             {
-              objectName: 'cn=grandParentGroup,ou=groups,dc=example,dc=org',
-              attributes: [
-                { type: 'cn', values: ['grandParentGroup'] },
-                {
-                  type: 'description',
-                  values: ['this is a grand parent group'],
-                },
-                {
-                  type: 'member',
-                  values: [
-                    'cn=parentGroup,ou=groups,dc=example,dc=org',
-                    'cn=grandParentGroupUser,ou=users,dc=example,dc=org',
-                  ],
-                },
-              ],
+              type: 'description',
+              values: ['this is a grand parent group'],
             },
-            // another root node
             {
-              objectName: 'cn=rootGroup,ou=groups,dc=example,dc=org',
-              attributes: [
-                { type: 'cn', values: ['rootGroup'] },
-                { type: 'description', values: ['this is a root group'] },
-                {
-                  type: 'member',
-                  values: ['cn=rootGroupUser,ou=users,dc=example,dc=org'],
-                },
+              type: 'member',
+              values: [
+                'cn=parentGroup,ou=groups,dc=example,dc=org',
+                'cn=grandParentGroupUser,ou=users,dc=example,dc=org',
               ],
             },
-          ]);
-        }
+          ],
+        },
+        // another root node
+        {
+          objectName: 'cn=rootGroup,ou=groups,dc=example,dc=org',
+          attributes: [
+            { type: 'cn', values: ['rootGroup'] },
+            { type: 'description', values: ['this is a root group'] },
+            {
+              type: 'member',
+              values: ['cn=rootGroupUser,ou=users,dc=example,dc=org'],
+            },
+          ],
+        },
+      ]);
+
+      // mock search for user lookups
+      mockSearch.mockImplementation((_filter, base) => {
         if (base === 'cn=childGroupUser,ou=users,dc=example,dc=org') {
-          // search childGroupUser
           return Promise.resolve([
             {
               objectName: 'cn=childGroupUser,ou=users,dc=example,dc=org',
@@ -124,7 +131,6 @@ describe('LdapUserGroupSyncService.generateExternalUserGroupTrees', () => {
             },
           ]);
         }
-        // search parentGroupUser
         if (base === 'cn=parentGroupUser,ou=users,dc=example,dc=org') {
           return Promise.resolve([
             {
@@ -137,7 +143,6 @@ describe('LdapUserGroupSyncService.generateExternalUserGroupTrees', () => {
             },
           ]);
         }
-        // search grandParentGroupUser
         if (base === 'cn=grandParentGroupUser,ou=users,dc=example,dc=org') {
           return Promise.resolve([
             {
@@ -150,7 +155,6 @@ describe('LdapUserGroupSyncService.generateExternalUserGroupTrees', () => {
             },
           ]);
         }
-        // search rootGroupUser
         if (base === 'cn=rootGroupUser,ou=users,dc=example,dc=org') {
           return Promise.resolve([
             {
@@ -243,52 +247,46 @@ describe('LdapUserGroupSyncService.generateExternalUserGroupTrees', () => {
 
   describe('When there is a circular reference in group tree', () => {
     it('rejects creating ExternalUserGroupTrees', async () => {
-      // mock search on LDAP server
-      mockLdapSearch.mockImplementation((filter, base) => {
-        if (base === 'ou=groups,dc=example,dc=org') {
-          // search groups
-          return Promise.resolve([
-            // childGroup and parentGroup have circular reference
+      // mock searchGroupDir for group entries with circular reference
+      mockSearchGroupDir.mockResolvedValue([
+        // childGroup and parentGroup have circular reference
+        {
+          objectName: 'cn=childGroup,ou=groups,dc=example,dc=org',
+          attributes: [
+            { type: 'cn', values: ['childGroup'] },
+            { type: 'description', values: ['this is a child group'] },
             {
-              objectName: 'cn=childGroup,ou=groups,dc=example,dc=org',
-              attributes: [
-                { type: 'cn', values: ['childGroup'] },
-                { type: 'description', values: ['this is a child group'] },
-                {
-                  type: 'member',
-                  values: ['cn=parentGroup,ou=groups,dc=example,dc=org'],
-                },
-              ],
+              type: 'member',
+              values: ['cn=parentGroup,ou=groups,dc=example,dc=org'],
             },
+          ],
+        },
+        {
+          objectName: 'cn=parentGroup,ou=groups,dc=example,dc=org',
+          attributes: [
+            { type: 'cn', values: ['parentGroup'] },
+            { type: 'description', values: ['this is a parent group'] },
             {
-              objectName: 'cn=parentGroup,ou=groups,dc=example,dc=org',
-              attributes: [
-                { type: 'cn', values: ['parentGroup'] },
-                { type: 'description', values: ['this is a parent group'] },
-                {
-                  type: 'member',
-                  values: ['cn=childGroup,ou=groups,dc=example,dc=org'],
-                },
-              ],
+              type: 'member',
+              values: ['cn=childGroup,ou=groups,dc=example,dc=org'],
             },
+          ],
+        },
+        {
+          objectName: 'cn=grandParentGroup,ou=groups,dc=example,dc=org',
+          attributes: [
+            { type: 'cn', values: ['grandParentGroup'] },
             {
-              objectName: 'cn=grandParentGroup,ou=groups,dc=example,dc=org',
-              attributes: [
-                { type: 'cn', values: ['grandParentGroup'] },
-                {
-                  type: 'description',
-                  values: ['this is a grand parent group'],
-                },
-                {
-                  type: 'member',
-                  values: ['cn=parentGroup,ou=groups,dc=example,dc=org'],
-                },
-              ],
+              type: 'description',
+              values: ['this is a grand parent group'],
             },
-          ]);
-        }
-        return Promise.reject(new Error('not found'));
-      });
+            {
+              type: 'member',
+              values: ['cn=parentGroup,ou=groups,dc=example,dc=org'],
+            },
+          ],
+        },
+      ]);
 
       await expect(
         ldapUserGroupSyncService?.generateExternalUserGroupTrees(),

apps/app/src/features/growi-plugin/server/routes/apiv3/admin/index.ts

@@ -6,6 +6,8 @@ import mongoose from 'mongoose';
 
 import type Crowi from '~/server/crowi';
 import { accessTokenParser } from '~/server/middlewares/access-token-parser';
+import adminRequiredFactory from '~/server/middlewares/admin-required';
+import loginRequiredFactory from '~/server/middlewares/login-required';
 import type { ApiV3Response } from '~/server/routes/apiv3/interfaces/apiv3-response';
 
 import { GrowiPlugin } from '../../../models';
@@ -28,15 +30,15 @@ const validator = {
 };
 
 module.exports = (crowi: Crowi): Router => {
-  const loginRequiredStrictly = require('~/server/middlewares/login-required')(
-    crowi,
-  );
-  const adminRequired = require('~/server/middlewares/admin-required')(crowi);
+  const loginRequiredStrictly = loginRequiredFactory(crowi);
+  const adminRequired = adminRequiredFactory(crowi);
 
   const router = express.Router();
 
   router.get(
     '/',
+    // biome-ignore lint/suspicious/noTsIgnore: Suppress auto fix by lefthook
+    // @ts-ignore - Scope type causes "Type instantiation is excessively deep" with tsgo
     accessTokenParser([SCOPE.READ.ADMIN.PLUGIN]),
     loginRequiredStrictly,
     adminRequired,