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.
2026-03-06 15:01:38 +01:00
parent 5d17564608
commit 45844de534
3384 changed files with 13894 additions and 586586 deletions
--- a/.github/MAINTENANCE.md
+++ b/.github/MAINTENANCE.md
@@ -80,13 +80,13 @@ Before ANY commit that adds/modifies skills, run the chain:
    git commit -m "chore: sync generated files"
    ```
    > 🔴 **CRITICAL**: If you skip this, CI will fail with "Detected uncommitted changes".
-    > See [docs/CI_DRIFT_FIX.md](../docs/CI_DRIFT_FIX.md) for details.
+    > See [`docs/maintainers/ci-drift-fix.md`](../docs/maintainers/ci-drift-fix.md) for details.

 ### B. When You Merge a PR (Step-by-Step)

 **Before merging:**

-1.  **CI is green** — All Validation Chain and catalog steps passed (see [workflows/ci.yml](workflows/ci.yml)).
+1.  **CI is green** — Validation, reference checks, tests, and generated artifact steps passed (see [`.github/workflows/ci.yml`](workflows/ci.yml)).
 2.  **No drift** — PR does not introduce uncommitted generated-file changes; if the "Check for Uncommitted Drift" step failed, ask the author to run `npm run chain` and `npm run catalog` and commit the result.
 3.  **Quality Bar** — PR description confirms the [Quality Bar Checklist](.github/PULL_REQUEST_TEMPLATE.md) (metadata, risk label, credits if applicable).
 4.  **Issue link** — If the PR fixes an issue, the PR description should contain `Closes #N` or `Fixes #N` so GitHub auto-closes the issue on merge.
@@ -134,21 +134,21 @@ GitHub's anchor generation breaks if headers have emojis.
 If you update installation instructions or tool compatibility, you MUST update all 3 files:

 1.  `README.md` (Source of Truth)
-2.  `docs/GETTING_STARTED.md` (Beginner Guide)
-3.  `docs/FAQ.md` (Troubleshooting)
+2.  `docs/users/getting-started.md` (Beginner Guide)
+3.  `docs/users/faq.md` (Troubleshooting)

 _Common pitfall: Updating the clone URL in README but leaving an old one in FAQ._

 ### C. Statistics Consistency (CRITICAL)

-If you add/remove skills, you **MUST** ensure the total count is identical in ALL locations.
-**Do not allow drift** (e.g., 560 in title, 558 in header).
+If you add/remove skills, you **MUST** ensure generated counts and user-facing claims stay aligned.

 Locations to check:

-1.  **Title of `README.md`**: "1,200+ Agentic Skills..."
-2.  **`## Full Skill Registry (1,200+/1,200+)` header**.
-3.  **`docs/GETTING_STARTED.md` intro**.
+1.  `README.md`
+2.  `package.json` description
+3.  `skills_index.json` and generated catalog artifacts
+4.  Any user docs that deliberately hardcode counts

 ### D. Credits Policy (Who goes where?)

@@ -166,7 +166,7 @@ Locations to check:

 If you touch any Workflows-related artifact, keep all workflow surfaces in sync:

-1. `docs/WORKFLOWS.md` (human-readable playbooks)
+1. `docs/users/workflows.md` (human-readable playbooks)
 2. `data/workflows.json` (machine-readable schema)
 3. `skills/antigravity-workflows/SKILL.md` (orchestration entrypoint)

@@ -177,8 +177,8 @@ Rules:
 - If a workflow references optional skills not yet merged (example: `go-playwright`), mark them explicitly as **optional** in docs.
 - If workflow onboarding text is changed, update the docs trinity:
  - `README.md`
-  - `docs/GETTING_STARTED.md`
-  - `docs/FAQ.md`
+  - `docs/users/getting-started.md`
+  - `docs/users/faq.md`

 ---

@@ -192,7 +192,7 @@ Reject any PR that fails this:
 2.  **Safety**: `risk: offensive` used for red-team tools?
 3.  **Clarity**: Does it say _when_ to use it?
 4.  **Examples**: Copy-pasteable code blocks?
-5.  **Actions**: "Run this command" vs "Think about this".
+5.  **Limitations / Safety Notes**: Edge cases and risk boundaries are stated clearly.

 ### B. Risk Labels (V4)

@@ -204,14 +204,25 @@ Reject any PR that fails this:

 ## 4. 🚀 Release Workflow

-When cutting a new version (e.g., v4.1.0):
+When cutting a new version, follow the maintainer playbook in [`docs/maintainers/release-process.md`](../docs/maintainers/release-process.md).

 **Release checklist (order matters):**  
-Validate → Changelog → Bump `package.json` (and README if needed) → Commit & push → Create GitHub Release with tag **matching** `package.json` (e.g. `v4.1.0` ↔ `"version": "4.1.0"`) → npm publish (manual or via CI) → Close any remaining linked issues.
+Operational verification → Changelog → Bump `package.json` (and README if needed) → Commit & push → Create GitHub Release with tag matching `package.json` → npm publish (manual or via CI) → Close remaining linked issues.

 ---

-1.  **Run Full Validation**: `python3 scripts/validate_skills.py --strict`
+1.  **Run release verification**:
+    ```bash
+    npm run validate
+    npm run validate:references
+    npm run sync:all
+    npm run test
+    npm run app:build
+    ```
+    Optional diagnostic pass:
+    ```bash
+    npm run validate:strict
+    ```
 2.  **Update Changelog**: Add the new release section to `CHANGELOG.md`.
 3.  **Bump Version**:
    - Update `package.json` → `"version": "X.Y.Z"` (source of truth for npm).
@@ -224,12 +235,12 @@ Validate → Changelog → Bump `package.json` (and README if needed) → Commit
    Use the GitHub CLI:

    ```bash
-    # Prepare release notes (copy the new section from CHANGELOG.md into release_notes.md, or use CHANGELOG excerpt)
+    # Prepare release notes (copy the new section from CHANGELOG.md into docs/maintainers/release-process.md, or use CHANGELOG excerpt)
    # Then create the tag AND the release page (tag must match package.json version, e.g. v4.1.0)
-    gh release create v4.0.0 --title "v4.0.0 - [Theme Name]" --notes-file release_notes.md
+    gh release create v4.0.0 --title "v4.0.0 - [Theme Name]" --notes-file docs/maintainers/release-process.md
    ```

-    **Important:** The release tag (e.g. `v4.1.0`) must match `package.json`'s `"version": "4.1.0"`. The [Publish to npm](workflows/publish-npm.yml) workflow runs on **Release published** and will run `npm publish`; npm rejects republishing the same version.
+    **Important:** The release tag must match `package.json`'s version. The [Publish to npm](workflows/publish-npm.yml) workflow runs on **Release published** and will run `npm publish`; npm rejects republishing the same version.

    _Or create the release manually via GitHub UI > Releases > Draft a new release, then publish._

--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -6,12 +6,13 @@ Please include a summary of the change and which skill is added or fixed.

 **All items must be checked before merging.**

- [ ] **Standards**: I have read `docs/QUALITY_BAR.md` and `docs/SECURITY_GUARDRAILS.md`.
- [ ] **Metadata**: The `SKILL.md` frontmatter is valid (checked with `scripts/validate_skills.py`).
- [ ] **Risk Label**: I have assigned the correct `risk:` tag (`none`, `safe`, `critical`, `offensive`).
+- [ ] **Standards**: I have read `docs/contributors/quality-bar.md` and `docs/contributors/security-guardrails.md`.
+- [ ] **Metadata**: The `SKILL.md` frontmatter is valid (checked with `npm run validate`).
+- [ ] **Risk Label**: I have assigned the correct `risk:` tag (`none`, `safe`, `critical`, `offensive`, or `unknown` for legacy/unclassified content).
 - [ ] **Triggers**: The "When to use" section is clear and specific.
 - [ ] **Security**: If this is an _offensive_ skill, I included the "Authorized Use Only" disclaimer.
 - [ ] **Local Test**: I have verified the skill works locally.
+- [ ] **Repo Checks**: I ran `npm run validate:references` if my change affected docs, bundles, workflows, or generated artifacts.
 - [ ] **Credits**: I have added the source credit in `README.md` (if applicable).

 ## Type of Change
--- a/.github/workflows/ci.yml
+++ b/.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)