Provnai Ecosystem Automation Guide#

This document explains exactly how the provnaidev documentation portal stays synchronized across multiple independent repositories (vex, vex-sdk, vex-explorer, etc.) with zero manual intervention.

The Problem#

The VEX ecosystem is composed of several specialized repositories. Manually updating the documentation portal every time a new version of the SDK or Core is published is unsustainable and error-prone.

The Architecture: "Zero-Touch Sync"#

We utilize a Webhook-driven synchronization pipeline.

1. The Origin: A developer pushes code or creates a new Release in an upstream repository (e.g., vex-sdk).
2. The Trigger: A GitHub Action in that upstream repository automatically fires an HTTP POST request to the Provnaidev Railway Webhook.
3. The Aggregator: Railway triggers a fresh Next.js build of the dev portal. The build phase runs scripts/sync-docs.js.
4. Multi-Repo Cloning: sync-docs.js automatically clones the vex, vex-sdk, and vex-explorer repositories into the temporary .repos/ build cache.
5. The Hub Generation: The script parses every Cargo.toml and package.json across these clones, extracting versions and descriptions to dynamically generate the unified api-reference.mdx Hub.
6. Live: The new interactive documentation is deployed globally.

Setup Instructions for Upstream Repositories#

To link a new repository (like vex-sdk) to this automation pipeline, you only need to do two things:

1. Add the Railway Webhook Secret#

Go to your upstream repository on GitHub:

• Settings -> Secrets and variables -> Actions
• Click New repository secret
• Name: RAILWAY_DOCS_WEBHOOK_URL
• Value: (Retrieve this from your Railway provnaidev project -> Settings -> Deployments -> Webhook).

2. Add the GitHub Action#

Create this exact file in your upstream repository at .github/workflows/trigger-docs.yml:

name: Trigger Dev Portal Sync

on:
  release:
    types: [published]
  push:
    branches:
      - main
    paths:
      - 'Cargo.toml'
      - 'package.json'
      - 'docs/**'
      - 'README.md'

jobs:
  ping-railway:
    name: Ping Railway Webhook
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Railway Deployment
        run: |
          curl -X POST -H "Content-Type: application/json" -d '{}' \
          \${{ secrets.RAILWAY_DOCS_WEBHOOK_URL }}

Adding New Repositories to the Hub#

To make provnaidev aware of a new repository:

1. Open scripts/sync-docs.js in the provnaidev repository.
2. Add the repository to the ECOSYSTEM_REPOS array at the top of the file:
   JAVASCRIPT

   Copy

   const ECOSYSTEM_REPOS = [
       { name: 'vex', url: 'https://github.com/provnai/vex.git' },
       { name: 'vex-sdk', url: 'https://github.com/provnai/vex-sdk.git' },
       { name: 'vex-explorer', url: 'https://github.com/provnai/vex-explorer.git' }
   ];
   

3. Commit and push. The pipeline will automatically handle the rest.