@ngxtm/devkit 3.14.0 → 3.16.0

package/merged-commands/server-management.md

@@ -1,7 +1,9 @@
 ---
 name: server-management
-description: Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.
+description: "Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands."
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+risk: unknown
+source: community
 ---
 
 # Server Management
@@ -159,3 +161,6 @@ When something's wrong:
 ---
 
 > **Remember:** A well-managed server is boring. That's the goal.
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/service-mesh-expert.md

@@ -1,6 +1,8 @@
 ---
 name: service-mesh-expert
 description: "Expert service mesh architect specializing in Istio, Linkerd, and cloud-native networking patterns. Masters traffic management, security policies, observability integration, and multi-cluster mesh con"
+risk: unknown
+source: community
 ---
 
 # Service Mesh Expert

package/merged-commands/service-mesh-observability.md

@@ -1,6 +1,8 @@
 ---
 name: service-mesh-observability
-description: Implement comprehensive observability for service meshes including distributed tracing, metrics, and visualization. Use when setting up mesh monitoring, debugging latency issues, or implementing SLOs for service communication.
+description: "Implement comprehensive observability for service meshes including distributed tracing, metrics, and visualization. Use when setting up mesh monitoring, debugging latency issues, or implementing SL..."
+risk: unknown
+source: community
 ---
 
 # Service Mesh Observability

package/merged-commands/shader-programming-glsl.md

@@ -0,0 +1,121 @@
+---
+name: shader-programming-glsl
+description: Expert guide for writing efficient GLSL shaders (Vertex/Fragment) for web and game engines, covering syntax, uniforms, and common effects.
+risk: safe
+source: community
+---
+
+# Shader Programming GLSL
+
+## Overview
+
+A comprehensive guide to writing GPU shaders using GLSL (OpenGL Shading Language). Learn syntax, uniforms, varying variables, and key mathematical concepts like swizzling and vector operations for visual effects.
+
+## When to Use This Skill
+
+- Use when creating custom visual effects in WebGL, Three.js, or game engines.
+- Use when optimizing graphics rendering performance.
+- Use when implementing post-processing effects (blur, bloom, color correction).
+- Use when procedurally generating textures or geometry on the GPU.
+
+## Step-by-Step Guide
+
+### 1. Structure: Vertex vs. Fragment
+
+Understand the pipeline:
+- **Vertex Shader**: Transforms 3D coordinates to 2D screen space (`gl_Position`).
+- **Fragment Shader**: Colors individual pixels (`gl_FragColor`).
+
+```glsl
+// Vertex Shader (basic)
+attribute vec3 position;
+uniform mat4 modelViewMatrix;
+uniform mat4 projectionMatrix;
+
+void main() {
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+```
+
+```glsl
+// Fragment Shader (basic)
+uniform vec3 color;
+
+void main() {
+    gl_FragColor = vec4(color, 1.0);
+}
+```
+
+### 2. Uniforms and Varyings
+
+- `uniform`: Data constant for all vertices/fragments (passed from CPU).
+- `varying`: Data interpolated from vertex to fragment shader.
+
+```glsl
+// Passing UV coordinates
+varying vec2 vUv;
+
+// In Vertex Shader
+void main() {
+    vUv = uv;
+    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+}
+
+// In Fragment Shader
+void main() {
+    // Gradient based on UV
+    gl_FragColor = vec4(vUv.x, vUv.y, 1.0, 1.0);
+}
+```
+
+### 3. Swizzling & Vector Math
+
+Access vector components freely: `vec4 color = vec4(1.0, 0.5, 0.0, 1.0);`
+- `color.rgb` -> `vec3(1.0, 0.5, 0.0)`
+- `color.zyx` -> `vec3(0.0, 0.5, 1.0)` (reordering)
+
+## Examples
+
+### Example 1: Simple Raymarching (SDF Sphere)
+
+```glsl
+float sdSphere(vec3 p, float s) {
+    return length(p) - s;
+}
+
+void mainImage(out vec4 fragColor, in vec2 fragCoord) {
+    vec2 uv = (fragCoord - 0.5 * iResolution.xy) / iResolution.y;
+    vec3 ro = vec3(0.0, 0.0, -3.0); // Ray Origin
+    vec3 rd = normalize(vec3(uv, 1.0)); // Ray Direction
+    
+    float t = 0.0;
+    for(int i = 0; i < 64; i++) {
+        vec3 p = ro + rd * t;
+        float d = sdSphere(p, 1.0); // Sphere radius 1.0
+        if(d < 0.001) break;
+        t += d;
+    }
+    
+    vec3 col = vec3(0.0);
+    if(t < 10.0) {
+        vec3 p = ro + rd * t;
+        vec3 normal = normalize(p);
+        col = normal * 0.5 + 0.5; // Color by normal
+    }
+    
+    fragColor = vec4(col, 1.0);
+}
+```
+
+## Best Practices
+
+- ✅ **Do:** Use `mix()` for linear interpolation instead of manual math.
+- ✅ **Do:** Use `step()` and `smoothstep()` for thresholding and soft edges (avoid `if` branches).
+- ✅ **Do:** Pack data into vectors (`vec4`) to minimize memory access.
+- ❌ **Don't:** Use heavy branching (`if-else`) inside loops if possible; it hurts GPU parallelism.
+- ❌ **Don't:** Calculate constant values inside the shader; pre-calculate them on the CPU (uniforms).
+
+## Troubleshooting
+
+**Problem:** Shader compiles but screen is black.
+**Solution:** Check if `gl_Position.w` is correct (usually 1.0). Check if uniforms are actually being set from the host application. Verify UV coordinates are within [0, 1].

package/merged-commands/shellcheck-configuration.md

@@ -1,6 +1,8 @@
 ---
 name: shellcheck-configuration
-description: Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability.
+description: "Master ShellCheck static analysis configuration and usage for shell script quality. Use when setting up linting infrastructure, fixing code issues, or ensuring script portability."
+risk: unknown
+source: community
 ---
 
 # ShellCheck Configuration and Static Analysis

package/merged-commands/shodan-reconnaissance.md

@@ -1,9 +1,11 @@
 ---
-name: Shodan Reconnaissance and Pentesting
-description: This skill should be used when the user asks to "search for exposed devices on the internet," "perform Shodan reconnaissance," "find vulnerable services using Shodan," "scan IP ranges with Shodan," or "discover IoT devices and open ports." It provides comprehensive guidance for using Shodan's search engine, CLI, and API for penetration testing reconnaissance.
+name: shodan-reconnaissance
+description: "This skill should be used when the user asks to \"search for exposed devices on the internet,\" \"perform Shodan reconnaissance,\" \"find vulnerable services using Shodan,\" \"scan IP ranges..."
 metadata:
   author: zebbern
   version: "1.1"
+risk: unknown
+source: community
 ---
 
 # Shodan Reconnaissance and Pentesting
@@ -501,3 +503,6 @@ shodan download network_scan.json.gz 'net:192.168.1.0/24'
 | Rate Limit Exceeded | >1 request/second | Add `time.sleep(1)` between API requests |
 | Empty Search Results | Too specific or syntax error | Use quotes for phrases: `'org:"Company Name"'`; broaden criteria |
 | Downloaded File Won't Parse | Corrupted or wrong format | Verify with `gunzip -t file.gz`, re-download with `--limit` |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/shopify-apps.md

@@ -1,7 +1,8 @@
 ---
 name: shopify-apps
-description: "Expert patterns for Shopify app development including Remix/React Router apps, embedded apps with App Bridge, webhook handling, GraphQL Admin API, Polaris components, billing, and app extensions. Use when: shopify app, shopify, embedded app, polaris, app bridge."
+description: "Expert patterns for Shopify app development including Remix/React Router apps, embedded apps with App Bridge, webhook handling, GraphQL Admin API, Polaris components, billing, and app extensions. U..."
 source: vibeship-spawner-skills (Apache 2.0)
+risk: unknown
 ---
 
 # Shopify Apps
@@ -40,3 +41,6 @@ Secure webhook processing with HMAC verification
 | Issue | high | ## Use GraphQL for all new code |
 | Issue | high | ## Use latest App Bridge via script tag |
 | Issue | high | ## Implement all GDPR handlers |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/shopify-automation.md

@@ -0,0 +1,173 @@
+---
+name: shopify-automation
+description: "Automate Shopify tasks via Rube MCP (Composio): products, orders, customers, inventory, collections. Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# Shopify Automation via Rube MCP
+
+Automate Shopify operations through Composio's Shopify toolkit via Rube MCP.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Shopify connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `shopify`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `shopify`
+3. If connection is not ACTIVE, follow the returned auth link to complete Shopify OAuth
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Manage Products
+
+**When to use**: User wants to list, search, create, or manage products
+
+**Tool sequence**:
+1. `SHOPIFY_GET_PRODUCTS` / `SHOPIFY_GET_PRODUCTS_PAGINATED` - List products [Optional]
+2. `SHOPIFY_GET_PRODUCT` - Get single product details [Optional]
+3. `SHOPIFY_BULK_CREATE_PRODUCTS` - Create products in bulk [Optional]
+4. `SHOPIFY_GET_PRODUCTS_COUNT` - Get product count [Optional]
+
+**Key parameters**:
+- `product_id`: Product ID for single retrieval
+- `title`: Product title
+- `vendor`: Product vendor
+- `status`: 'active', 'draft', or 'archived'
+
+**Pitfalls**:
+- Paginated results require cursor-based pagination for large catalogs
+- Product variants are nested within the product object
+
+### 2. Manage Orders
+
+**When to use**: User wants to list, search, or inspect orders
+
+**Tool sequence**:
+1. `SHOPIFY_GET_ORDERS_WITH_FILTERS` - List orders with filters [Required]
+2. `SHOPIFY_GET_ORDER` - Get single order details [Optional]
+3. `SHOPIFY_GET_FULFILLMENT` - Get fulfillment details [Optional]
+4. `SHOPIFY_GET_FULFILLMENT_EVENTS` - Track fulfillment events [Optional]
+
+**Key parameters**:
+- `status`: Order status filter ('any', 'open', 'closed', 'cancelled')
+- `financial_status`: Payment status filter
+- `fulfillment_status`: Fulfillment status filter
+- `order_id`: Order ID for single retrieval
+- `created_at_min`/`created_at_max`: Date range filters
+
+**Pitfalls**:
+- Order IDs are numeric; use string format for API calls
+- Default order listing may not include all statuses; specify 'any' for all
+
+### 3. Manage Customers
+
+**When to use**: User wants to list or search customers
+
+**Tool sequence**:
+1. `SHOPIFY_GET_ALL_CUSTOMERS` - List all customers [Required]
+
+**Key parameters**:
+- `limit`: Number of customers per page
+- `since_id`: Pagination cursor
+
+**Pitfalls**:
+- Customer data includes order count and total spent
+- Large customer lists require pagination
+
+### 4. Manage Collections
+
+**When to use**: User wants to manage product collections
+
+**Tool sequence**:
+1. `SHOPIFY_GET_SMART_COLLECTIONS` - List smart collections [Optional]
+2. `SHOPIFY_GET_SMART_COLLECTION_BY_ID` - Get collection details [Optional]
+3. `SHOPIFY_CREATE_SMART_COLLECTIONS` - Create a smart collection [Optional]
+4. `SHOPIFY_ADD_PRODUCT_TO_COLLECTION` - Add product to collection [Optional]
+5. `SHOPIFY_GET_PRODUCTS_IN_COLLECTION` - List products in collection [Optional]
+
+**Key parameters**:
+- `collection_id`: Collection ID
+- `product_id`: Product ID for adding to collection
+- `rules`: Smart collection rules for automatic inclusion
+
+**Pitfalls**:
+- Smart collections auto-populate based on rules; manual collections use custom collections API
+- Collection count endpoints provide approximate counts
+
+### 5. Manage Inventory
+
+**When to use**: User wants to check or manage inventory levels
+
+**Tool sequence**:
+1. `SHOPIFY_GET_INVENTORY_LEVELS` / `SHOPIFY_RETRIEVES_A_LIST_OF_INVENTORY_LEVELS` - Check stock [Required]
+2. `SHOPIFY_LIST_LOCATION` - List store locations [Optional]
+
+**Key parameters**:
+- `inventory_item_ids`: Inventory item IDs to check
+- `location_ids`: Location IDs to filter by
+
+**Pitfalls**:
+- Inventory is tracked per variant per location
+- Location IDs are required for multi-location stores
+
+## Common Patterns
+
+### Pagination
+
+- Use `limit` and `page_info` cursor for paginated results
+- Check response for `next` link header
+- Continue until no more pages available
+
+### GraphQL Queries
+
+For advanced operations:
+```
+1. Call SHOPIFY_GRAPH_QL_QUERY with custom query
+2. Parse response from data object
+```
+
+## Known Pitfalls
+
+**API Versioning**:
+- Shopify REST API has versioned endpoints
+- Some features require specific API versions
+
+**Rate Limits**:
+- REST API: 2 requests/second for standard plans
+- GraphQL: 1000 cost points per second
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List products | SHOPIFY_GET_PRODUCTS | (filters) |
+| Get product | SHOPIFY_GET_PRODUCT | product_id |
+| Products paginated | SHOPIFY_GET_PRODUCTS_PAGINATED | limit, page_info |
+| Bulk create | SHOPIFY_BULK_CREATE_PRODUCTS | products |
+| Product count | SHOPIFY_GET_PRODUCTS_COUNT | (none) |
+| List orders | SHOPIFY_GET_ORDERS_WITH_FILTERS | status, financial_status |
+| Get order | SHOPIFY_GET_ORDER | order_id |
+| List customers | SHOPIFY_GET_ALL_CUSTOMERS | limit |
+| Shop details | SHOPIFY_GET_SHOP_DETAILS | (none) |
+| Validate access | SHOPIFY_VALIDATE_ACCESS | (none) |
+| Smart collections | SHOPIFY_GET_SMART_COLLECTIONS | (none) |
+| Products in collection | SHOPIFY_GET_PRODUCTS_IN_COLLECTION | collection_id |
+| Inventory levels | SHOPIFY_GET_INVENTORY_LEVELS | inventory_item_ids |
+| Locations | SHOPIFY_LIST_LOCATION | (none) |
+| Fulfillment | SHOPIFY_GET_FULFILLMENT | order_id, fulfillment_id |
+| GraphQL | SHOPIFY_GRAPH_QL_QUERY | query |
+| Bulk query | SHOPIFY_BULK_QUERY_OPERATION | query |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/shopify-development.md

@@ -1,10 +1,12 @@
 ---
 name: shopify-development
-description: |
+description: "|"
   Build Shopify apps, extensions, themes using GraphQL Admin API, Shopify CLI, Polaris UI, and Liquid.
   TRIGGER: "shopify", "shopify app", "checkout extension", "admin extension", "POS extension",
   "shopify theme", "liquid template", "polaris", "shopify graphql", "shopify webhook",
   "shopify billing", "app subscription", "metafields", "shopify functions"
+risk: unknown
+source: community
 ---
 
 # Shopify Development Skill
@@ -364,3 +366,6 @@ For detailed implementation guides, read these files:
 - Polaris Design System: https://polaris.shopify.com
 
 API Version: 2026-01 (quarterly releases, 12-month deprecation window)
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/signup-flow-cro.md

@@ -1,6 +1,8 @@
 ---
 name: signup-flow-cro
-description: When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions "signup conversions," "registration friction," "signup form optimization," "free trial signup," "reduce signup dropoff," or "account creation flow." For post-signup onboarding, see onboarding-cro. For lead capture forms (not account creation), see form-cro.
+description: "When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions \"signup conversions,\" \"registration friction,\" \"signup..."
+risk: unknown
+source: community
 ---
 
 # Signup Flow CRO
@@ -353,3 +355,6 @@ If you need more context:
 - **form-cro**: For non-signup forms (lead capture, contact)
 - **page-cro**: For the landing page leading to signup
 - **ab-test-setup**: For testing signup flow changes
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/similarity-search-patterns.md

@@ -1,6 +1,8 @@
 ---
 name: similarity-search-patterns
-description: Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieval performance.
+description: "Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieval performance."
+risk: unknown
+source: community
 ---
 
 # Similarity Search Patterns

package/merged-commands/skill/sync.md

@@ -1,108 +1,176 @@
 ---
-description: Sync new skills from upstream repos with AI evaluation
-argument-hint: [options]
+description: Sync skills, rules, and external-skills from upstream repos with AI evaluation
+argument-hint: [--auto] [--dry-run]
 ---
 
-# Sync Skills from Upstream
+# Sync from Upstream
 
-> AI-assisted upstream skill sync: fetch, evaluate, select, build.
+> AI-driven upstream sync: fetch, evaluate new+updated skills/rules/external-skills, apply, build, commit.
 
-## Workflow
+## Arguments
 
-### Step 1: Pre-flight Check
+Parse `$ARGUMENTS` for flags:
+- `--auto`: Fully autonomous — sync all useful new items, accept all updates, no user questions
+- `--dry-run`: Show report only, don't copy or commit anything
 
-Verify clean working directory:
-```bash
-git status --porcelain
-```
-If not clean → ask user to commit or stash first.
+## Workflow
 
-### Step 2: Fetch Upstream
+### Step 1: Pre-flight
 
-Run the sync script to clone upstream repos and get a report:
+Check git status:
 ```bash
-npm run sync:upstream
+git status --porcelain
 ```
 
-This creates a sync branch and clones repos to temp directory.
+- If **clean** → proceed
+- If **dirty + `--auto`** → run `git stash push -m "devkit-sync-stash"`
+- If **dirty + interactive** → ask user to commit/stash or continue with stash
 
-### Step 3: Evaluate New Skills
+Remember if stash was created (for restore later).
 
-After the script runs, it shows which skills are new. For each **new** skill:
+### Step 2: Fetch & Report
 
-1. Read its `SKILL.md` from the temp directory
-2. Evaluate:
-   - **Useful**: Skill covers a distinct domain not already well-covered
-   - **Duplicate**: Similar skill already exists in the local collection
-   - **Irrelevant**: Too niche or low quality
+Run the sync script with JSON output:
+```bash
+node scripts/manual-sync.js --no-branch --json
+```
 
-3. Present summary to user:
+Parse the JSON output. It contains:
+```json
+{
+  "tempDir": "/tmp/devkit-sync",
+  "skills": { "new": [...], "updated": [...], "unchanged": N },
+  "rules": { "new": [...], "updated": [...], "unchanged": N },
+  "external-skills": [{ "name": "...", "localExists": bool, "upstreamVersion": "...", "localVersion": "...", "checkFiles": [...], "tempPath": "..." }]
+}
 ```
-Upstream sync found N new skills:
 
-✅ Useful (X):
-  - skill-name: short reason
-  - skill-name: short reason
+If all categories have 0 new and 0 updated → report "Already up to date" and stop.
 
-⚠️ Possibly duplicate (Y):
-  - skill-name: overlaps with existing-skill
+### Step 3: Evaluate New Skills
 
-❌ Skip (Z):
-  - skill-name: reason
+For each item in `skills.new`:
+1. Read its `SKILL.md` from the `path` field in the report
+2. Classify:
+   - **Useful**: Covers a distinct domain, well-structured, actionable content
+   - **Duplicate**: Similar skill already exists (check by name/description against skills-compact.json)
+   - **Skip**: Too niche, low quality, or just "be a senior X engineer" with no real content
+3. In `--auto` mode: sync all useful, skip duplicates and low quality
+4. In interactive mode: present summary and ask user using `AskUserQuestion`
 
-Sync options:
-  1. Sync all useful (X skills)
-  2. Sync all useful + duplicates (X+Y skills)
-  3. Let me choose manually
+Summary format:
 ```
+Upstream sync found N new skills:
 
-### Step 4: Copy Selected Skills
-
-Use `AskUserQuestion` to get user's choice. Then for selected skills:
-
-```bash
-cp -r /tmp/devkit-sync/{source}/{skill-name} ./skills/{skill-name}
+✅ Useful (X): skill-a, skill-b, ...
+⚠️ Duplicate (Y): skill-c (overlaps existing-skill), ...
+❌ Skip (Z): skill-d (reason), ...
 ```
 
-### Step 5: Rebuild Indexes
+### Step 3.5: Evaluate Updated Skills
+
+For each item in `skills.updated`:
+1. Read **both** upstream SKILL.md (from tempDir) and local SKILL.md
+2. Compare and summarize what changed
+3. Classify:
+   - **Accept**: Upstream adds substantial new content (new sections, patterns, commands)
+   - **Skip**: Changes are trivial (formatting only) or local version is superior/customized
+4. In `--auto` mode: accept all non-trivial updates
+5. In interactive mode: present changes summary and ask user
+
+### Step 4: Evaluate External Skills
+
+For each item in `external-skills`:
+1. Check if local skill exists (`localExists` field)
+2. If exists:
+   a. Read `UPSTREAM.md` from `skills/{name}/UPSTREAM.md` for sync guide
+   b. Read the relevant `checkFiles` from `tempPath` in the report
+   c. Compare with local `SKILL.md`
+   d. Check version: if `upstreamVersion` differs from `localVersion` → needs update
+   e. Follow UPSTREAM.md guide: preserve devkit-specific sections, update upstream-derived content
+   f. Update `upstream-version` in SKILL.md frontmatter to `upstreamVersion` value
+3. If not exists: report it as available but don't auto-create (manual setup needed)
+4. In `--auto` mode: apply all detected changes following UPSTREAM.md rules
+5. In interactive mode: show what changed and ask user
+
+### Step 5: Evaluate Rules
+
+For each item in `rules.new`:
+1. Read the rule content from `path` field
+2. Classify: useful (covers new pattern) or skip (duplicate/too generic)
+3. In `--auto` mode: sync all useful
+4. In interactive mode: ask user
+
+For each item in `rules.updated`:
+1. Compare upstream and local content
+2. Accept meaningful updates, skip trivial ones
+
+### Step 6: Apply Changes
+
+If `--dry-run` → skip this step, just show what would be done.
+
+For selected items:
+- **New skills**: `node scripts/manual-sync.js --copy <name>` for each
+- **Updated skills**: Read upstream SKILL.md, use Write tool to update local SKILL.md (preserve local customizations if any)
+- **New rules**: `node scripts/manual-sync.js --copy <name>` for each
+- **Updated rules**: Use Write tool to update local rule files
+- **External skills**: Use Write tool to edit SKILL.md following UPSTREAM.md guide
+
+### Step 7: Rebuild & Verify
 
 ```bash
 npm run build
 ```
 
-This regenerates all indexes (merged-commands, rules-index, skills-index, skills-compact).
+- If **success** → proceed to commit
+- If **failure** → rollback ALL changes:
+  ```bash
+  git checkout -- .
+  ```
+  If stash was created: `git stash pop`
+  Report the build error and stop.
 
-### Step 6: Review & Commit
+### Step 8: Commit
 
-Show summary of changes:
+Stage and commit the changes:
 ```bash
-git diff --stat
+git add skills/ rules/ merged-commands/ SKILLS_INDEX.md skills-index.json skills-compact.json rules-index.json
 ```
 
-Ask user if they want to commit:
-```bash
-git add skills/ merged-commands/ SKILLS_INDEX.md skills-index.json skills-compact.json rules-index.json
-git commit -m "feat(skills): sync N new skills from upstream"
+Commit message format:
+```
+feat(skills): sync N new, M updated skills from upstream
 ```
 
-## Options
+Adjust the message based on what was actually synced (skills, rules, external-skills).
 
-- `$ARGUMENTS` can specify:
-  - `--auto`: Skip evaluation, sync all new skills automatically
-  - `--dry-run`: Only show report, don't copy anything
-  - A specific upstream name to sync from (e.g., `antigravity` or `agent-assistant`)
+If stash was created earlier: `git stash pop` to restore user's changes.
 
 ## Evaluation Criteria
 
-When evaluating skills, consider:
-- Does it cover a technology the project uses or might use?
-- Is there already a similar skill? (check by name and description)
-- Is the SKILL.md well-structured with actionable content?
-- Is it too generic (just says "be a senior X engineer")?
+### New Skills
+- **Useful**: Covers distinct domain, well-structured SKILL.md, actionable patterns/commands
+- **Duplicate**: Similar name or description to existing skill in skills-compact.json
+- **Skip**: Too niche, low quality, just "be a senior X engineer" boilerplate
+
+### Updated Skills
+- **Accept**: Upstream adds substantial new content (new sections, patterns, examples)
+- **Skip**: Changes are trivial (whitespace, formatting) or local version is customized and superior
+
+### External Skills
+- Follow UPSTREAM.md guide in each skill directory
+- Always update version tracking
+- Never overwrite devkit-specific frontmatter (`triggers`, `role`, `scope`, `output-format`)
+
+### Rules
+- **Accept**: Rule covers useful pattern not in existing rules
+- **Skip**: Duplicate or too generic
 
 ## Important
 
-- **NEVER** auto-sync without user confirmation (unless `--auto` flag)
-- **ALWAYS** run `npm run build` after copying skills
-- Keep the sync branch for PR review if needed
-- The temp directory is at the path shown by the sync script output
+- In interactive mode, **ALWAYS** ask before applying changes
+- In `--auto` mode, proceed fully autonomously
+- **ALWAYS** run `npm run build` after applying changes
+- **ALWAYS** rollback on build failure via `git checkout -- .`
+- Use `node scripts/manual-sync.js --copy` or Write tool for file operations — **NEVER** use `cp -r` (Windows incompatible)
+- The temp directory path is in the JSON report's `tempDir` field