Merge pull request #141 from aicodingstack/agent/project-review-foundation

feat: establish project maintenance and trust foundation

Author: ericyangpan

.github/CODEOWNERS

@@ -15,18 +15,18 @@
 /manifests/**/*.json @aicodingstack/maintainers
 
 # Schema files - require careful review as they affect validation
-/manifests/schemas/**/*.json @aicodingstack/maintainers
+/manifests/$schemas/**/*.json @aicodingstack/maintainers
 
 # Build and validation scripts - require careful review
-/scripts/**/*.mjs @aicodingstack/maintainers
+/scripts/**/*.ts @aicodingstack/maintainers
 
 # GitHub Actions workflows - require review for security
 /.github/workflows/**/*.yml @aicodingstack/maintainers
 
 # Configuration files
 /package.json @aicodingstack/maintainers
 /tsconfig.json @aicodingstack/maintainers
-/next.config.mjs @aicodingstack/maintainers
+/next.config.ts @aicodingstack/maintainers
 /wrangler.toml @aicodingstack/maintainers
 
 # Documentation - can be reviewed by broader team

.github/ISSUE_TEMPLATE/config.yml

@@ -7,5 +7,5 @@ contact_links:
     url: https://github.com/aicodingstack/aicodingstack.io/blob/main/docs
     about: Read the technical documentation
   - name: Schema Documentation
-    url: https://github.com/aicodingstack/aicodingstack.io/tree/main/manifests/schemas
+    url: https://github.com/aicodingstack/aicodingstack.io/tree/main/manifests/%24schemas
     about: View JSON schema documentation for manifests

.github/ISSUE_TEMPLATE/metadata_contribution.yml

@@ -8,7 +8,7 @@ body:
       value: |
         Thank you for contributing to AI Coding Stack! This form will guide you through adding or updating metadata for AI coding tools.
 
-        Please check our [Schema Documentation](https://github.com/aicodingstack/aicodingstack.io/tree/main/manifests/schemas) to understand the required fields.
+        Please check our [Schema Documentation](https://github.com/aicodingstack/aicodingstack.io/tree/main/manifests/%24schemas) to understand the required fields.
 
   - type: dropdown
     id: contribution-type
@@ -95,9 +95,9 @@ body:
         For **Providers**: Include supported models, API documentation
 
         See schema files for complete field requirements:
-        - [Model Schema](https://github.com/aicodingstack/aicodingstack.io/blob/main/manifests/schemas/model.schema.json)
-        - [IDE Schema](https://github.com/aicodingstack/aicodingstack.io/blob/main/manifests/schemas/ide.schema.json)
-        - [CLI Schema](https://github.com/aicodingstack/aicodingstack.io/blob/main/manifests/schemas/cli.schema.json)
+        - [Model Schema](https://github.com/aicodingstack/aicodingstack.io/blob/main/manifests/%24schemas/model.schema.json)
+        - [IDE Schema](https://github.com/aicodingstack/aicodingstack.io/blob/main/manifests/%24schemas/ide.schema.json)
+        - [CLI Schema](https://github.com/aicodingstack/aicodingstack.io/blob/main/manifests/%24schemas/cli.schema.json)
       placeholder: |
         Example for a model:
         - Size: 175B parameters

.github/pull_request_template.md

@@ -55,9 +55,9 @@ Closes #(issue number)
 <!-- Describe how you tested your changes -->
 
 - [ ] Local build passes (`npm run build`)
-- [ ] All validation checks pass (`npm run validate:manifests`)
+- [ ] All validation checks pass (`npm run test:validate`)
 - [ ] URL validation passes (`npm run validate:urls`)
-- [ ] Linting passes (`npm run lint`)
+- [ ] Static analysis passes (`npm run biome:check`)
 - [ ] Spell check passes (`npm run spell`)
 
 ## Screenshots (if applicable)

.github/workflows/ci.yml

@@ -108,6 +108,9 @@ jobs:
         env:
           BUILD_TIME: ${{ github.event.head_commit.timestamp }}
 
+      - name: Verify generated source is current
+        run: git diff --exit-code -- src/lib/generated
+
       - name: Upload build artifacts
         uses: actions/upload-artifact@v6
         with:
@@ -125,8 +128,8 @@ jobs:
     steps:
       - name: Check all jobs
         run: |
-          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" ]]; then
-            echo "One or more CI jobs failed"
+          if [[ "${{ contains(needs.*.result, 'failure') }}" == "true" || "${{ contains(needs.*.result, 'cancelled') }}" == "true" || "${{ contains(needs.*.result, 'skipped') }}" == "true" ]]; then
+            echo "One or more required CI jobs failed, were cancelled, or were skipped"
             exit 1
           fi
           echo "All CI jobs passed successfully"

.github/workflows/deploy-staging.yml

@@ -1,8 +1,7 @@
 name: Deploy Staging
 
 on:
-  push:
-    branches: [develop]
+  workflow_dispatch:
 
 concurrency:
   group: staging-deploy
@@ -38,7 +37,7 @@ jobs:
       - name: Build with OpenNext
         run: npm run build
         env:
-          BUILD_TIME: ${{ github.event.head_commit.timestamp }}
+          BUILD_TIME: ${{ github.event.repository.updated_at }}
 
       - name: Deploy to Staging
         run: npx --no-install opennextjs-cloudflare deploy --env staging

.github/workflows/scheduled-checks.yml

@@ -1,23 +1,19 @@
-name: Scheduled Checks
+name: Scheduled URL Checks
 
 on:
   schedule:
     # Run URL validation every Monday at 00:00 UTC
     - cron: '0 0 * * 1'
-    # Run GitHub stars update daily at 06:00 UTC
-    - cron: '0 6 * * *'
   workflow_dispatch: # Allow manual triggering
 
 permissions:
-  contents: write
-  pull-requests: write
+  contents: read
   issues: write
 
 jobs:
   validate-urls:
     name: Validate URLs
     runs-on: ubuntu-latest
-    if: github.event.schedule == '0 0 * * 1' || github.event_name == 'workflow_dispatch'
     steps:
       - name: Checkout code
         uses: actions/checkout@v6
@@ -37,7 +33,7 @@ jobs:
         continue-on-error: true
 
       - name: Create issue if URLs are broken
-        if: failure()
+        if: steps.validate.outcome == 'failure'
         uses: actions/github-script@v8
         with:
           script: |
@@ -75,78 +71,27 @@ jobs:
                 body: body,
                 labels: ['automated', 'url-validation', 'maintenance']
               });
+            } else {
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issues.data[0].number,
+                body: body
+              });
             }
 
-  update-github-stars:
-    name: Update GitHub Stars
-    runs-on: ubuntu-latest
-    if: github.event.schedule == '0 6 * * *' || github.event_name == 'workflow_dispatch'
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v6
-        with:
-          node-version: '22'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
-      # TODO: Configure GITHUB_TOKEN with appropriate permissions
-      # The fetch-github-stars script may need authentication
-      - name: Fetch GitHub stars
-        run: npm run fetch:github-stars
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        continue-on-error: true
-
-      - name: Check for changes
-        id: git-check
-        run: |
-          git diff --exit-code manifests/ || echo "changed=true" >> $GITHUB_OUTPUT
-
-      - name: Create pull request
-        if: steps.git-check.outputs.changed == 'true'
-        uses: peter-evans/create-pull-request@v8
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
-          commit-message: 'chore: update GitHub stars data'
-          title: '🌟 Update GitHub Stars Data'
-          body: |
-            ## Automated GitHub Stars Update
-
-            This PR updates the GitHub stars count for tools in our manifest files.
-
-            **Updated:** ${{ steps.git-check.outputs.changed }}
-
-            ### Changes
-            - Fetched latest star counts from GitHub API
-            - Updated manifest files with current data
-
-            ### Review Checklist
-            - [ ] Verify star counts look reasonable
-            - [ ] No unexpected changes to other fields
-
-            ---
-            *This PR was automatically created by the scheduled GitHub stars update workflow.*
-          branch: automated/update-github-stars
-          delete-branch: true
-          labels: |
-            automated
-            metadata
-            github-stars
+      - name: Fail workflow after reporting broken URLs
+        if: steps.validate.outcome == 'failure'
+        run: exit 1
 
   workflow-summary:
     name: Workflow Summary
     runs-on: ubuntu-latest
-    needs: [validate-urls, update-github-stars]
+    needs: [validate-urls]
     if: always()
     steps:
       - name: Summary
         run: |
           echo "## Scheduled Checks Summary" >> $GITHUB_STEP_SUMMARY
           echo "" >> $GITHUB_STEP_SUMMARY
           echo "- URL Validation: ${{ needs.validate-urls.result }}" >> $GITHUB_STEP_SUMMARY
-          echo "- GitHub Stars Update: ${{ needs.update-github-stars.result }}" >> $GITHUB_STEP_SUMMARY

.github/workflows/update-github-stars.yml

@@ -41,7 +41,7 @@ jobs:
       - name: Check for changes
         id: git-check
         run: |
-          git diff --exit-code manifests/github-stars.json src/lib/generated/github-stars.ts || echo "changes=true" >> $GITHUB_OUTPUT
+          git diff --exit-code data/github-stars.json src/lib/generated/github-stars.ts || echo "changes=true" >> $GITHUB_OUTPUT
 
       - name: Create Pull Request
         if: steps.git-check.outputs.changes == 'true'
@@ -55,7 +55,7 @@ jobs:
             Automated weekly update of GitHub stars data.
 
             ### Changes
-            - Updated `manifests/github-stars.json` with latest star counts
+            - Updated `data/github-stars.json` with latest star counts
             - Regenerated `src/lib/generated/github-stars.ts`
 
             ### Source

CONTRIBUTING.md

@@ -73,7 +73,7 @@ Want to contribute code? Great! Please:
 
 ### Prerequisites
 
-- **Node.js**: 20.x or higher
+- **Node.js**: 22.x or higher
 - **npm**: Latest version
 - **Git**: For version control
 
@@ -85,7 +85,7 @@ git clone https://github.com/aicodingstack/aicodingstack.io.git
 cd aicodingstack.io
 
 # Install dependencies
-npm install
+npm ci
 
 # Run validation tests
 npm run test:validate
@@ -106,9 +106,10 @@ Visit `http://localhost:3000` to see the site.
 - `npm run build` - Build for production
 - `npm run test:validate` - Run repository validation tests (schemas, translations, alignment, etc.)
 - `npm run test:urls` - Check URL accessibility (networked; CI-oriented)
-- `npm run lint` - Run ESLint
+- `npm run biome:check` - Run static analysis
+- `npm run type-check` - Run TypeScript checks
 - `npm run spell` - Run spell checker
-- `npm test` - Run tests (if available)
+- `npm test` - Run the Vitest suite in watch mode
 
 ## Manifest File Guidelines
 
@@ -121,61 +122,34 @@ All manifest files must conform to their respective JSON schemas located in `man
 - [Model Schema](manifests/$schemas/model.schema.json)
 - [Provider Schema](manifests/$schemas/provider.schema.json)
 
-### Example: Adding a New IDE
-
-Create a file in `manifests/ides/your-ide.json`:
-
-```json
-{
-  "name": "Your IDE",
-  "id": "your-ide",
-  "vendor": "Your Company",
-  "description": "A brief description of what makes this IDE unique",
-  "websiteUrl": "https://example.com",
-  "docsUrl": "https://docs.example.com",
-  "latestVersion": "1.0.0",
-  "platforms": ["Windows", "macOS", "Linux"],
-  "pricing": {
-    "model": "freemium",
-    "free": true
-  }
-}
-```
+### Examples
 
-### Example: Adding a New Model
-
-Create a file in `manifests/models/your-model.json`:
-
-```json
-{
-  "name": "Your Model",
-  "id": "your-model",
-  "vendor": "Your Company",
-  "size": "175B",
-  "contextWindow": 128000,
-  "maxOutput": 4096,
-  "pricing": {
-    "input": 0.01,
-    "output": 0.03,
-    "currency": "USD",
-    "unit": "1K tokens"
-  },
-  "urls": {
-    "website": "https://example.com",
-    "documentation": "https://docs.example.com"
-  }
-}
-```
+The schemas are authoritative and require fields that differ by category. Start from a current, validated manifest rather than copying an abbreviated snippet:
+
+- [IDE example](manifests/ides/cursor.json)
+- [Model example](manifests/models/gpt-5-2.json)
+
+Copy the closest existing manifest, update its `$schema`, `id`, content, translations, and URLs, then run the validation commands below.
 
 ### Field Requirements
 
-#### Common Fields (All Types)
-- **`name`**: Official product name (required)
-- **`id`**: Lowercase, hyphenated identifier (required, unique)
-- **`vendor`**: Company or organization name (required)
-- **`description`**: Clear, concise description (required)
-- **`websiteUrl`**: Official website (required)
-- **`docsUrl`**: Documentation URL (recommended)
+#### Common Fields (Most Types)
+
+- **`$schema`**: Relative path to the category schema
+- **`name`**: Official product name
+- **`id`**: Lowercase, hyphenated identifier that matches the filename
+- **`vendor`**: Company or organization name
+- **`description`**: Clear, concise default-language description
+- **`translations`**: Localized fields required by the category schema
+- **`websiteUrl`**: Official website
+- **`docsUrl`**: Documentation URL
+- **`sources`**: Authoritative URLs supporting the record or named fields
+- **`lastVerifiedAt`**: Date the cited facts were last reviewed
+- **`verifiedBy`**: GitHub handle or automation identifier responsible for the review
+- **`confidence`**: `high`, `medium`, or `low`, based on source quality and recency
+
+For new or updated records marked `verified: true`, include the provenance fields above. See
+[Data Trust and Verification](docs/DATA-TRUST.md) for the badge semantics and rollout policy.
 
 #### Model-Specific Fields
 - **`size`**: Model size (e.g., "175B", "70B")
@@ -257,7 +231,8 @@ chore(deps): update Next.js to 15.1.0
 3. ✅ **Validate locally**:
    ```bash
    npm run test:validate
-   npm run test:urls
+   npm run biome:check
+   npm run type-check
    npm run spell
    npm run build
    ```
@@ -275,7 +250,7 @@ chore(deps): update Next.js to 15.1.0
 
 ### Review Process
 
-- **Automated checks**: CI must pass (lint, validate, build)
+- **Automated checks**: CI must pass (Biome, types, validation, spell check, and build)
 - **Maintainer review**: At least 1 approval required
 - **Response time**: We aim to review within 3-5 business days
 - **Merge**: Once approved, maintainers will merge your PR

README.md

@@ -122,7 +122,7 @@ All manifest files are automatically validated against JSON schemas. Make sure y
 
 ## Tech Stack
 
-- **Framework**: Next.js 15 with App Router
+- **Framework**: Next.js 16 with App Router
 - **Styling**: Tailwind CSS 4
 - **Internationalization**: next-intl
 - **Content**: MDX for documentation