refactor: reorganize repo docs and tooling layout

Consolidate the repository into clearer apps, tools, and layered docs areas so contributors can navigate and maintain it more reliably. Align validation, metadata sync, and CI around the same canonical workflow to reduce drift across local checks and GitHub Actions.

.github/workflows/ci.yml

@@ -25,18 +25,6 @@ jobs:
         run: |
           pip install pyyaml
 
-      - name: 🔍 Validate Skills (Soft Mode)
-        run: |
-          python3 scripts/validate_skills.py
-
-      - name: 🏗️ Generate Index
-        run: |
-          python3 scripts/generate_index.py
-
-      - name: 📝 Update README
-        run: |
-          python3 scripts/update_readme.py
-
       - name: Set up Node
         uses: actions/setup-node@v4
         with:
@@ -45,6 +33,31 @@ jobs:
       - name: Install npm dependencies
         run: npm ci
 
+      - name: Verify directory structure
+        run: |
+          test -d skills/
+          test -d apps/web-app/
+          test -d tools/scripts/
+          test -d tools/lib/
+          test -f README.md
+          test -f CONTRIBUTING.md
+
+      - name: 🔍 Validate Skills (Soft Mode)
+        run: |
+          npm run validate
+
+      - name: 🔗 Validate References
+        run: |
+          npm run validate:references
+
+      - name: 🏗️ Generate Index
+        run: |
+          npm run index
+
+      - name: 📝 Update README
+        run: |
+          npm run readme
+
       - name: Audit npm dependencies
         run: npm audit --audit-level=high
         continue-on-error: true
@@ -60,8 +73,8 @@ jobs:
       - name: Set up GitHub credentials (for auto-sync)
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: |
-          git config --global user.name 'github-actions[bot]'
-          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
           git remote set-url origin https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git
 
       - name: Auto-commit registry drift (main only)