@xonovex/skills 0.1.0

package/skills/cmake-guidelines/reference/fetchcontent.md

@@ -0,0 +1,32 @@
+# fetchcontent: Dependency Management with FetchContent
+
+**Guideline:** Use FetchContent to fetch and build external dependencies from source at configure time.
+
+**Rationale:** FetchContent ensures dependencies are built with the same compiler and settings as your project, providing reproducible builds without system installation.
+
+**Example:**
+
+```cmake
+include(FetchContent)
+
+# Fetch external dependency
+FetchContent_Declare(
+    fmt
+    GIT_REPOSITORY https://github.com/fmtlib/fmt.git
+    GIT_TAG 10.1.1
+    GIT_SHALLOW TRUE
+)
+
+FetchContent_MakeAvailable(fmt)
+
+# Use the dependency
+add_executable(app src/main.cpp)
+target_link_libraries(app PRIVATE fmt::fmt)
+```
+
+**Techniques:**
+- FetchContent_Declare(): Declare dependency with git repo and version pin
+- GIT_TAG: Pin exact version for reproducible builds
+- GIT_SHALLOW: Use shallow clone for faster fetching
+- FetchContent_MakeAvailable(): Fetch and populate dependency with one call
+- Populate: Use FetchContent_GetProperties() for conditional population control

package/skills/cmake-guidelines/reference/find-package.md

@@ -0,0 +1,29 @@
+# find-package: Dependency Management with find_package
+
+**Guideline:** Use find_package to locate and link system-installed dependencies.
+
+**Rationale:** System-installed packages are pre-built and optimized for the platform, reducing build times and disk usage when available.
+
+**Example:**
+
+```cmake
+# Find system-installed package
+find_package(Boost 1.80 REQUIRED COMPONENTS system filesystem)
+
+add_executable(app src/main.cpp)
+target_link_libraries(app PRIVATE Boost::system Boost::filesystem)
+
+# Optional dependency
+find_package(OpenSSL)
+if(OpenSSL_FOUND)
+    target_link_libraries(app PRIVATE OpenSSL::SSL OpenSSL::Crypto)
+    target_compile_definitions(app PRIVATE HAVE_OPENSSL=1)
+endif()
+```
+
+**Techniques:**
+- REQUIRED: Fail build if package not found, use for mandatory dependencies
+- COMPONENTS: Specify individual package parts to reduce linking
+- Namespaced targets: Use Boost::system, OpenSSL::SSL for safe target linking
+- \*_FOUND variable: Check if optional dependency is available before using
+- Conditional linking: Add target_compile_definitions when dependencies found

package/skills/cmake-guidelines/reference/generator-expressions.md

@@ -0,0 +1,34 @@
+# generator-expressions: Generator Expressions
+
+**Guideline:** Use generator expressions for conditional and context-dependent CMake settings.
+
+**Rationale:** Generator expressions evaluate at build time, allowing different settings based on compiler, platform, configuration, or build/install context.
+
+**Example:**
+
+```cmake
+# Build/Install interface paths
+target_include_directories(mylib PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)
+
+# Compiler-specific options
+target_compile_options(mylib PRIVATE
+    $<$<CXX_COMPILER_ID:GNU>:-fno-rtti>
+    $<$<CXX_COMPILER_ID:MSVC>:/GR->
+)
+
+# Configuration and platform-specific settings
+target_compile_definitions(mylib PRIVATE
+    $<$<CONFIG:Debug>:DEBUG_MODE=1>
+    $<$<PLATFORM_ID:Linux>:LINUX_BUILD>
+)
+```
+
+**Techniques:**
+- BUILD_INTERFACE/INSTALL_INTERFACE: Different paths for build vs installed consumption
+- CXX_COMPILER_ID: Detect compiler and apply vendor-specific flags
+- CONFIG: Apply Debug or Release build-specific settings
+- PLATFORM_ID: Apply Linux, Windows, Darwin-specific settings
+- Nested conditions: Chain $<$<X>:$<Y:value>>> for complex logic

package/skills/cmake-guidelines/reference/installation.md

@@ -0,0 +1,38 @@
+# installation: Installation
+
+**Guideline:** Configure installation rules to enable package distribution and consumption via find_package.
+
+**Rationale:** Proper installation allows your library to be installed system-wide or in custom locations and discovered by other CMake projects.
+
+**Example:**
+
+```cmake
+# Install targets with export
+install(TARGETS mylib app
+    EXPORT mylib-targets
+    LIBRARY DESTINATION lib
+    ARCHIVE DESTINATION lib
+    RUNTIME DESTINATION bin
+    INCLUDES DESTINATION include
+)
+
+# Install headers
+install(DIRECTORY include/
+    DESTINATION include
+    FILES_MATCHING PATTERN "*.h"
+)
+
+# Export targets for find_package discovery
+install(EXPORT mylib-targets
+    FILE mylib-targets.cmake
+    NAMESPACE mylib::
+    DESTINATION lib/cmake/mylib
+)
+```
+
+**Techniques:**
+- install(TARGETS): Install libraries and executables with type-specific destinations
+- EXPORT: Create importable CMake files for downstream find_package() calls
+- DESTINATION: Set lib/bin/include paths for each artifact type
+- NAMESPACE: Prefix exported targets (mylib::) to prevent naming conflicts
+- install(DIRECTORY): Install headers with glob patterns for selective inclusion

package/skills/cmake-guidelines/reference/project-structure.md

@@ -0,0 +1,40 @@
+# project-structure: Basic Project Structure
+
+**Guideline:** Set up CMake projects with modern target-based configuration using CMake 3.20 or higher.
+
+**Rationale:** A well-structured CMakeLists.txt establishes build requirements, project metadata, and target definitions that form the foundation for maintainable builds.
+
+**Example:**
+
+```cmake
+cmake_minimum_required(VERSION 3.20)
+project(demo VERSION 1.0.0 DESCRIPTION "Example" LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+# Build library
+add_library(core src/core.cpp src/utils.cpp)
+target_include_directories(core PUBLIC
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)
+target_compile_features(core PUBLIC cxx_std_20)
+
+# Build executable
+add_executable(app src/main.cpp)
+target_link_libraries(app PRIVATE core)
+
+# Testing
+enable_testing()
+add_executable(core_test tests/core_test.cpp)
+target_link_libraries(core_test PRIVATE core)
+add_test(NAME core_test COMMAND core_test)
+```
+
+**Techniques:**
+- cmake_minimum_required(): Set 3.20+ for modern CMake features
+- project(): Declare name, version, description, and required languages
+- add_library/add_executable(): Create targets for libraries and binaries
+- target_include_directories(): Configure include paths with generator expressions
+- target_compile_features(): Require specific C++ standard like cxx_std_20

package/skills/cmake-guidelines/reference/target-types.md

@@ -0,0 +1,37 @@
+# target-types: Target Types
+
+**Guideline:** Choose appropriate target types based on how the code will be consumed.
+
+**Rationale:** Different target types optimize for different use cases: shared libraries for runtime linking, static for embedding, header-only for templates, object for reusing compiled code.
+
+**Example:**
+
+```cmake
+# Normal library (static or shared based on BUILD_SHARED_LIBS)
+add_library(mylib src/lib.cpp)
+
+# Explicit static library
+add_library(static_lib STATIC src/static.cpp)
+
+# Explicit shared library
+add_library(shared_lib SHARED src/shared.cpp)
+
+# Header-only library
+add_library(header_only INTERFACE)
+target_include_directories(header_only INTERFACE include)
+
+# Object library for intermediate compilation
+add_library(objects OBJECT src/common.cpp)
+target_link_libraries(mylib PRIVATE objects)
+
+# Executable and GUI app
+add_executable(app src/main.cpp)
+add_executable(gui WIN32 MACOSX_BUNDLE src/gui.cpp)
+```
+
+**Techniques:**
+- add_library() without type: Let BUILD_SHARED_LIBS control static vs shared
+- STATIC: Always statically link, good for embedded or single-binary scenarios
+- SHARED: Dynamic library for runtime linking and flexible updates
+- INTERFACE: Header-only library with no compiled code
+- OBJECT: Intermediate object library for sharing compiled units across targets

package/skills/cmake-guidelines/reference/testing.md

@@ -0,0 +1,30 @@
+# testing: Testing with CTest
+
+**Guideline:** Use CTest to integrate automated testing into the build system.
+
+**Rationale:** CTest provides a standardized way to run tests across platforms with features like timeouts, labels, and parallel execution.
+
+**Example:**
+
+```cmake
+# Enable testing
+enable_testing()
+
+# Add test executable
+add_executable(unit_tests tests/test_core.cpp tests/test_utils.cpp)
+target_link_libraries(unit_tests PRIVATE core gtest_main)
+
+# Register test cases
+add_test(NAME unit_tests COMMAND unit_tests)
+add_test(NAME integration_test COMMAND app --test-mode WORKING_DIRECTORY ${CMAKE_BINARY_DIR})
+
+# Set test properties
+set_tests_properties(unit_tests PROPERTIES TIMEOUT 30 LABELS "unit")
+```
+
+**Techniques:**
+- enable_testing(): Enable the testing feature in CMake project
+- add_test(): Register test executable or command with optional working directory
+- set_tests_properties(): Set timeout, labels, or other test attributes
+- add_executable() for tests: Build test binaries separately from production code
+- LABELS: Tag tests for selective running with ctest -L filter

package/skills/cmake-guidelines/reference/visibility-specifiers.md

@@ -0,0 +1,32 @@
+# visibility-specifiers: Visibility Specifiers
+
+**Guideline:** Use PUBLIC, PRIVATE, and INTERFACE to control how target properties propagate to consumers.
+
+**Rationale:** Proper visibility prevents leaking implementation details and ensures consumers get only the dependencies they need, reducing coupling and build times.
+
+**Example:**
+
+```cmake
+# PUBLIC: Library AND consumers need this
+target_include_directories(mylib PUBLIC include)
+target_compile_definitions(mylib PUBLIC USE_FEATURE=1)
+
+# PRIVATE: Only library needs this
+target_include_directories(mylib PRIVATE src/internal)
+target_compile_definitions(mylib PRIVATE DEBUG_MODE=1)
+
+# INTERFACE: Only consumers need this
+add_library(header_only INTERFACE)
+target_include_directories(header_only INTERFACE include)
+
+# Linking with visibility
+add_executable(app src/main.cpp)
+target_link_libraries(app PRIVATE mylib PUBLIC common INTERFACE interface)
+```
+
+**Techniques:**
+- PUBLIC: Properties visible to both target and all downstream consumers
+- PRIVATE: Properties used only by target, not propagated to consumers
+- INTERFACE: Properties for consumers only, not used by target itself
+- Consistent visibility: Apply same visibility to includes, links, definitions, options
+- Minimize PUBLIC: Reduce PUBLIC properties to shrink transitive dependencies

package/skills/content-guidelines/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: content-guidelines
+description: >-
+  Trigger on content creation tasks with bilingual requirements. Use when creating bilingual content with structured formatting. Apply for news curation, port/ship guides, travel guides. Keywords: bilingual, CEFR, B1-B2 proficiency, content frontmatter, news articles, travel guides, humanize, web research.
+---
+
+# Content Creation Guidelines
+
+## Core Principles
+
+- **Research First** - Verify with web search and web fetch, triangulate facts
+- **Bilingual Content** - Support multiple languages with CEFR proficiency levels
+- **Structured Format** - Follow exact structure with proper front-matter
+- **Natural Language** - CEFR B1-B2, personal "you" voice, no emojis, see [reference/humanize.md](reference/humanize.md)
+
+## Workflow
+
+- **Research** - Use WebSearch and WebFetch to gather and verify information
+- **Draft** - Follow structured format with proper front-matter
+- **Generate** - Create markdown files for each language
+- **Validate** - Verify links, addresses, factual accuracy
+
+## Language Standards
+
+- **Proficiency** - CEFR B1-B2 by default (configurable)
+- **Style** - Short sentences (<20 words), 60% informative / 40% conversational
+- **Paraphrasing** - Never copy text verbatim from sources
+
+## Progressive Disclosure
+
+### Content Types
+- Read [reference/news.md](reference/news.md) - Auto-curate latest news with bilingual summaries
+- Read [reference/travelguide.md](reference/travelguide.md) - Multi-language travel destination guides
+
+### Writing Quality
+- Read [reference/humanize.md](reference/humanize.md) - Remove AI patterns and make text natural

package/skills/content-guidelines/reference/humanize.md

@@ -0,0 +1,30 @@
+# humanize: Make Writing Sound Human
+
+**Guideline:** Remove AI patterns from documentation to make it sound natural and professional.
+
+**Rationale:** AI-generated text contains recognizable patterns (forced casual tone, filler phrases, excessive formatting) that diminish credibility and readability.
+
+**Example:**
+
+Before:
+```markdown
+## Phase 1: Setup (Est. 2-3 days)
+Let's dive in! TD-01: Configure Database ✅
+This involves database connection. In other words:
+- Connect to PostgreSQL - primary data store
+- Set up migrations - easy fix though
+```
+
+After:
+```markdown
+## Setup
+Configure database by connecting to PostgreSQL as primary data store and setting up migrations.
+```
+
+**Techniques:**
+- Remove task IDs: Strip TD-01, TASK-001, phase structures, time estimations
+- Replace filler: Remove "Let's dive in", "here's the thing", "easy fix though"
+- Simplify punctuation: Use commas instead of dashes (", " not " - ")
+- Prose over bullets: Use paragraphs where logical flow works better
+- Remove enthusiasm: Eliminate excessive exclamation marks, emojis, meta-commentary
+- Keep accuracy: Maintain technical precision while removing fluff

package/skills/content-guidelines/reference/news.md

@@ -0,0 +1,28 @@
+# news: Auto-Curate Latest News Stories
+
+**Guideline:** Research and write news stories in multiple languages with verified facts triangulated from 3+ sources.
+
+**Rationale:** Bilingual news requires triangulating sources to discard clickbait while paraphrasing to avoid plagiarism and maintain credibility.
+
+**Example:**
+
+```yaml
+---
+title: "Headline (35-45 words)"
+slug: "story-slug"
+summary: "Concise summary"
+created_at: "2024-01-24T12:00:00Z"
+image_url: "royalty-free-url"
+lang: "en"
+---
+```
+
+Write in CEFR B1-B2 level with short sentences (<20 words) and bullet points for skimming.
+
+**Techniques:**
+- WebSearch verification: Find 3+ credible sources per story, use date filters
+- Triangulate facts: Cross-check claims, discard unsourced or clickbait content
+- Paraphrase: Never copy verbatim, use original wording while preserving meaning
+- Language standards: Target CEFR B1-B2 with natural, concise prose
+- Headlines: Write 35-45 word summaries that are authoritative yet friendly
+- Filename format: Use `slug.lang.md` convention for bilingual organization

package/skills/content-guidelines/reference/travelguide.md

@@ -0,0 +1,31 @@
+# travelguide: Create Comprehensive Travel Guides
+
+**Guideline:** Create multi-language travel guides balancing engaging narrative with practical, web-verifiable information.
+
+**Rationale:** Comprehensive guides help travelers plan effectively while capturing destination essence through knowledgeable narrative.
+
+**Example:**
+
+Structure:
+1. Introduction (200-300 words): Hook, key logistics, duration
+2. Logistics (400-500 words): Location, hours, transport, tips
+3. Attractions (500-600 words): 3-5 essential with access, duration, cost, hours, tip
+4. Itineraries (600-800 words): Budget/family/premium types, half/full-day options
+5. Practical Info (400-500 words): Payment, language, weather, safety, customs
+
+Front-matter:
+```yaml
+title: "Destination Name"
+slug: "destination-slug"
+summary: "Brief summary"
+created_at: "ISO timestamp"
+lang: "en"
+```
+
+**Techniques:**
+- WebSearch research: Gather current, comprehensive information before writing
+- Narrative style: Write as knowledgeable friend, pack practical value into prose
+- Language standards: CEFR B1-B2, <20 word sentences, **bold** for critical details
+- Attractions details: Include access methods, duration, cost, hours, insider tips
+- Accessibility: Include information for travelers with disabilities
+- Verification: All information must be web-verifiable and current

package/skills/docker-guidelines/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: docker-guidelines
+description: >-
+  Trigger on `Dockerfile`, `docker-compose.yml`, `.dockerignore` files. Use when writing Docker configurations for containerized applications. Apply for multi-stage builds, security hardening, production deployments. Keywords: Dockerfile, multi-stage, alpine/distroless, layer caching, non-root, secrets, health checks, BuildKit.
+---
+
+# Docker Coding Guidelines
+
+## Essentials
+
+- **Build optimization** - Multi-stage builds, small base images (alpine/distroless), see [reference/multi-stage-builds.md](reference/multi-stage-builds.md)
+- **Layer caching** - Order layers for caching, copy lockfiles before source, see [reference/layer-caching.md](reference/layer-caching.md)
+- **Security** - Run as non-root, least privilege, no secrets in images, see [reference/security.md](reference/security.md)
+- **Configuration** - Externalize config via env/volumes, pin versions, see [reference/production-config.md](reference/production-config.md)
+- **Quality** - Use BuildKit and hadolint, add health endpoints, see [reference/production-config.md](reference/production-config.md)
+
+## Progressive disclosure
+
+- Read [reference/multi-stage-builds.md](reference/multi-stage-builds.md) - When creating production images or optimizing build process
+- Read [reference/layer-caching.md](reference/layer-caching.md) - When builds are slow or cache invalidates frequently
+- Read [reference/security.md](reference/security.md) - When hardening images or handling secrets
+- Read [reference/production-config.md](reference/production-config.md) - When adding health checks or configuring for orchestration
+- Read [reference/docker-compose.md](reference/docker-compose.md) - When defining multi-service local development environments

package/skills/docker-guidelines/reference/docker-compose.md

@@ -0,0 +1,40 @@
+# docker-compose: Docker Compose Configuration
+
+**Guideline:** Use Docker Compose for development with proper secrets, volumes, and health checks.
+
+**Rationale:** Simplifies multi-container orchestration during development; secrets, volumes, and health checks mirror production while maintaining security.
+
+**Example:**
+
+```yaml
+services:
+  app:
+    build: {context: ., target: runtime}
+    environment:
+      - NODE_ENV=production
+      - DATABASE_URL_FILE=/run/secrets/db_url
+    secrets: [db_url]
+    volumes: [app-data:/app/data]
+    ports: ["3000:3000"]
+    healthcheck:
+      test: ["CMD", "node", "healthcheck.js"]
+      interval: 30s
+      timeout: 3s
+      retries: 3
+    restart: unless-stopped
+
+secrets:
+  db_url:
+    file: ./secrets/db_url.txt
+
+volumes:
+  app-data:
+```
+
+**Techniques:**
+- Build configuration: Specify build context and target stage in compose
+- Secrets management: Use secrets section for sensitive data, never environment vars
+- Volume mounting: Mount volumes for persistent data matching production layout
+- Health checks: Configure health checks matching Dockerfile definitions
+- Restart policy: Set `unless-stopped` for development persistence
+- Port mapping: Expose ports for local development access

package/skills/docker-guidelines/reference/layer-caching.md

@@ -0,0 +1,25 @@
+# layer-caching: Layer Caching Strategy
+
+**Guideline:** Order Dockerfile commands least-to-most frequently changing to maximize cache reuse.
+
+**Rationale:** Docker caches each layer; changes invalidate subsequent layers. Proper ordering minimizes rebuild time.
+
+**Example:**
+
+```dockerfile
+FROM node:22-alpine
+WORKDIR /app
+COPY package-lock.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+```
+
+**Techniques:**
+- Copy lockfiles first: package-lock.json, poetry.lock rarely change
+- Install dependencies: Run before copying source to cache dependency layer
+- Copy source last: src/, config files change frequently
+- Build commands: Run after source copy, invalidates only build layer
+- Order principle: Static → dependencies → source → build
+- Cache validation: Check Docker BUILDKIT with --progress=plain for cache hits
+- Multi-stage: Use separate stages for different cache patterns

package/skills/docker-guidelines/reference/multi-stage-builds.md

@@ -0,0 +1,37 @@
+# multi-stage-builds: Multi-Stage Build Pattern
+
+**Guideline:** Separate build and runtime stages to minimize production image size and attack surface.
+
+**Rationale:** Multi-stage builds use full-featured build envs while keeping runtime images minimal; reduces size, attack surface, deployment time.
+
+**Example:**
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+
+FROM node:22-alpine AS deps
+WORKDIR /app
+COPY package.json pnpm-lock.yaml ./
+RUN corepack enable && pnpm i --frozen-lockfile
+
+FROM node:22-alpine AS build
+WORKDIR /app
+COPY --from=deps /app/node_modules node_modules
+COPY . .
+RUN pnpm build
+
+FROM gcr.io/distroless/nodejs22
+WORKDIR /app
+USER nonroot:nonroot
+COPY --from=build /app/dist dist
+ENV NODE_ENV=production
+EXPOSE 3000
+CMD ["dist/server.js"]
+```
+
+**Techniques:**
+- Stage separation: Use distinct dependencies, build, and runtime stages
+- Artifact copying: Copy only necessary outputs between stages
+- Minimal runtime: Use distroless or alpine for production image
+- Named stages: Use AS for clarity in multi-stage builds
+- Size optimization: Reduces image size by excluding build tools from runtime

package/skills/docker-guidelines/reference/production-config.md

@@ -0,0 +1,32 @@
+# production-config: Production Configuration
+
+**Guideline:** Configure with health checks, externalized config, proper lifecycle management.
+
+**Rationale:** Health checks enable failure detection, env vars allow deployment-specific config, volumes preserve data.
+
+**Example:**
+
+```dockerfile
+# syntax=docker/dockerfile:1.7
+FROM node:22-alpine
+WORKDIR /app
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s \
+  CMD node healthcheck.js || exit 1
+
+ENV NODE_ENV=production PORT=3000 LOG_LEVEL=info
+
+VOLUME /app/data
+
+EXPOSE 3000
+USER node:node
+CMD ["node", "dist/server.js"]
+```
+
+**Techniques:**
+- Health checks: Add HEALTHCHECK for orchestration failure detection
+- Environment config: Use ENV for deployment-specific configuration
+- Persistent volumes: Define VOLUME for data that must survive restarts
+- Port exposure: Use EXPOSE to document container ports
+- Non-root user: Set USER for security and orchestration requirements
+- BuildKit syntax: Use syntax directive for advanced features

package/skills/docker-guidelines/reference/security.md

@@ -0,0 +1,27 @@
+# security: Security Best Practices
+
+**Guideline:** Pin versions, run non-root, externalize secrets to limit attack surface.
+
+**Rationale:** Multiple defense layers: pinned versions prevent supply chain attacks, non-root limits breach damage, externalized secrets prevent leaks.
+
+**Example:**
+
+```dockerfile
+FROM node:22.1.0-alpine3.19
+
+RUN addgroup -g 1001 -S nodejs && \
+    adduser -S nodejs -u 1001
+USER nodejs:nodejs
+
+ENV DATABASE_URL_FILE=/run/secrets/db_url
+
+RUN mkdir /tmp/app-cache && chown nodejs:nodejs /tmp/app-cache
+VOLUME /tmp/app-cache
+```
+
+**Techniques:**
+- Version pinning: Pin base image version including OS version for supply chain security
+- Non-root user: Create and use non-root USER to limit breach damage
+- Secret externalization: Never copy secrets into image; use environment or mounts
+- Read-only filesystem: Use read-only root with writable VOLUME for security
+- Defense layers: Combine multiple tactics (pinning, user, secrets) for defense-in-depth

package/skills/express.js-guidelines/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: express.js-guidelines
+description: >-
+  Trigger on `*.ts` files with Express imports or `@types/express`. Use when building Express 5+ API servers. Apply for route organization, error handling, authentication, testing. Keywords: Express, routes, controllers, middleware, Zod validation, JWT, error handling, CORS, Morgan.
+---
+
+# Express.js Coding Guidelines
+
+## Requirements
+
+- Express ≥ 5, TypeScript ≥ 5.8, Helmet/CORS/Morgan, Zod.
+
+## Essentials
+
+- **Project structure** - Routes, controllers, middleware as separate modules, see [reference/project-structure.md](reference/project-structure.md)
+- **Input validation** - Validate params/body/query with Zod at route edges, see [reference/validation.md](reference/validation.md)
+- **Error handling** - Central error handler, never leak stack traces in prod, see [reference/error-handling.md](reference/error-handling.md)
+- **Authentication** - JWT auth with role/permission middleware, see [reference/authentication.md](reference/authentication.md)
+- **Response format** - Consistent JSON shape and status codes, see [reference/responses.md](reference/responses.md)
+- **Testing** - Unit-test controllers/middleware, integration-test routes, see [reference/testing.md](reference/testing.md)
+
+## Progressive disclosure
+
+- Read [reference/project-structure.md](reference/project-structure.md) - When organizing a new Express project
+- Read [reference/routes.md](reference/routes.md) - When defining REST endpoints or route patterns
+- Read [reference/controllers.md](reference/controllers.md) - When implementing request handlers
+- Read [reference/validation.md](reference/validation.md) - When adding input validation to routes
+- Read [reference/authentication.md](reference/authentication.md) - When implementing JWT auth or session management
+- Read [reference/error-handling.md](reference/error-handling.md) - When centralizing error responses
+- Read [reference/responses.md](reference/responses.md) - When standardizing API response formats
+- Read [reference/app-setup.md](reference/app-setup.md) - When configuring Express app initialization
+- Read [reference/testing.md](reference/testing.md) - When writing unit or integration tests