Dev

.github/workflows/docs.yml

@@ -0,0 +1,44 @@
+name: Documentation
+
+on:
+  push:
+    branches: [ main, develop ]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    branches: [ main, develop ]
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+      - 'requirements-docs.txt'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5.0.1
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install dependencies
+        run: pip install -r requirements-docs.txt
+
+      - name: Build documentation
+        run: mkdocs build --strict

.github/workflows/validate-packages.yml → .github/workflows/package-validation.yml

@@ -1,10 +1,10 @@
-name: Validate Packages
+name: Package Validation
 
 on:
   push:
     paths:
       - 'packages/**/*.json'
-      - '.github/workflows/validate-packages.yml'
+      - '.github/workflows/package-validation.yml'
   pull_request:
     paths:
       - 'packages/**/*.json'
@@ -85,10 +85,16 @@ jobs:
                   fi
                 done
 
-                # Validate source object
-                if ! python3 -c "import json, sys; data = json.load(open('$pkg')); sys.exit(0 if isinstance(data.get('source'), dict) and 'type' in data.get('source', {}) and 'url' in data.get('source', {}) else 1)" 2>/dev/null; then
+                # Validate source object (url for git/tarball/zip; path for type local)
+                if ! python3 -c "
+import json, sys
+data = json.load(open('$pkg'))
+s = data.get('source', {})
+ok = isinstance(s, dict) and 'type' in s and ('url' in s or (s.get('type') == 'local' and 'path' in s))
+sys.exit(0 if ok else 1)
+" 2>/dev/null; then
                   echo "❌ Invalid or missing 'source' object in $pkg"
-                  echo "  Source must be an object with 'type' and 'url' fields"
+                  echo "  Source must have 'type' and either 'url' (git/tarball/zip) or 'path' (local)"
                   FAILED=1
                 fi
 
@@ -187,6 +193,11 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }}
+
       - name: Test package parsing
         run: cargo test test_parse_all_packages
 
@@ -262,6 +273,11 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }}
+
       - name: Build TSI
         run: cargo build --release
 
@@ -285,4 +301,3 @@ jobs:
 
           echo "Testing dependency resolution for zlib..."
           tsi install zlib --force 2>&1 | head -30 || echo "Install test completed (may have build errors, but resolution worked)"
-

.github/workflows/release.yml

@@ -41,6 +41,11 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ matrix.platform }}-cargo-${{ hashFiles('Cargo.lock') }}
+
       - name: Build
         run: cargo build --release
 

.github/workflows/rust-ci.yml

@@ -0,0 +1,41 @@
+name: Rust CI
+
+on:
+  workflow_call:
+    inputs:
+      runner:
+        description: 'Runner (e.g. ubuntu-latest, macos-latest, windows-latest)'
+        required: true
+        type: string
+
+permissions:
+  contents: read
+
+jobs:
+  rust:
+    name: Rust (build, test, clippy, fmt)
+    runs-on: ${{ inputs.runner }}
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5.0.1
+
+      - name: Install Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Cargo
+        uses: Swatinem/rust-cache@v2
+        with:
+          key: ${{ runner.os }}-cargo-${{ hashFiles('Cargo.lock') }}
+
+      - name: Build
+        run: cargo build --release
+
+      - name: Run tests
+        run: cargo test
+
+      - name: Run clippy
+        run: cargo clippy -- -D warnings
+
+      - name: Check formatting
+        run: cargo fmt --check

.github/workflows/test.yml

@@ -22,28 +22,11 @@ permissions:
 
 jobs:
   test:
-    name: Test Rust
-    runs-on: ${{ matrix.os }}
+    name: Test Rust (${{ matrix.os }})
+    uses: ./.github/workflows/rust-ci.yml
+    with:
+      runner: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v5.0.1
-
-      - name: Install Rust
-        uses: dtolnay/rust-toolchain@stable
-
-      - name: Build
-        run: cargo build --release
-
-      - name: Run tests
-        run: cargo test
-
-      - name: Run clippy
-        run: cargo clippy -- -D warnings
-
-      - name: Check formatting
-        run: cargo fmt --check

.gitlab-ci.yml

@@ -1,3 +1,6 @@
+# GitLab CI: mirrors the Rust CI steps from .github/workflows/rust-ci.yml.
+# Primary CI is GitHub Actions; this file is for GitLab-based mirrors and forks.
+
 stages:
   - test
   - lint

docs/developer-guide/architecture.md

@@ -18,7 +18,7 @@ TSI is implemented in Rust with a single static binary and zero runtime dependen
 
 - **Language**: Rust (edition 2021)
 - **Build System**: Cargo
-- **Dependencies**: Minimal crates (serde, clap, reqwest, etc.)
+- **Dependencies**: Minimal crates (serde, clap, ureq, etc.)
 - **Output**: Single executable (`tsi` or `tsi.exe`)
 
 ### Module Layout

docs/workflows/automation.md

@@ -229,6 +229,10 @@ The workflows integrate with your CI/CD pipeline:
 - Package tests run on new versions
 - Automated checks ensure quality
 
+### GitLab CI
+
+**Primary CI is GitHub Actions.** A [`.gitlab-ci.yml`](../../.gitlab-ci.yml) file is provided for GitLab-based mirrors and forks. It mirrors the Rust build, test, clippy, and fmt steps from [`.github/workflows/rust-ci.yml`](../../.github/workflows/rust-ci.yml). When updating Rust CI behavior, keep both in sync so GitLab users get the same checks.
+
 ## See Also
 
 - [Version Discovery](version-discovery.md) - Detailed version discovery documentation

docs/workflows/triggers.md

@@ -20,20 +20,38 @@ This document explains when each workflow runs and what triggers them.
   - Only other workflow files change
 
 **Jobs:**
-- `test`: Tests Rust build and functionality (matrix: ubuntu-latest, macos-latest, windows-latest); runs `cargo build --release`, `cargo test`, `cargo clippy`, `cargo fmt --check`
+- `test`: Calls the reusable [Rust CI](.github/workflows/rust-ci.yml) workflow (matrix: ubuntu-latest, macos-latest, windows-latest); runs build, test, clippy, fmt with Cargo caching.
 
 **Manual Trigger:** Yes, can be triggered manually via `workflow_dispatch`
 
-## Validate Packages Workflow
+## Documentation Workflow
 
-**File:** `.github/workflows/validate-packages.yml`
+**File:** `.github/workflows/docs.yml`
+
+**Purpose:** Builds MkDocs documentation so doc issues are caught on PRs before release.
+
+**Triggers:**
+- ✅ **Runs when:**
+  - `docs/**` - Documentation source
+  - `mkdocs.yml` - MkDocs config
+  - `requirements-docs.txt` - Doc dependencies
+  - `.github/workflows/docs.yml` - The workflow file itself
+
+**Jobs:**
+- `build`: Sets up Python, installs doc dependencies, runs `mkdocs build --strict`.
+
+**Manual Trigger:** Yes, via `workflow_dispatch`
+
+## Package Validation Workflow
+
+**File:** `.github/workflows/package-validation.yml`
 
 **Purpose:** Validates package JSON files and ensures TSI can parse them
 
 **Triggers:**
 - ✅ **Only runs when package files change:**
   - `packages/**/*.json` - Package definition files
-  - `.github/workflows/validate-packages.yml` - The workflow file itself
+  - `.github/workflows/package-validation.yml` - The workflow file itself
 
 - ❌ **Does NOT run when:**
   - TSI source code changes
@@ -89,13 +107,14 @@ This document explains when each workflow runs and what triggers them.
 
 ## Summary
 
-| Workflow | Triggers on Source Code | Triggers on Packages | Triggers on Tag | Scheduled |
-|----------|-------------------------|---------------------|-----------------|-----------|
-| TSI Tests | ✅ Yes | ✅ Yes | ❌ No | ❌ No |
-| Validate Packages | ❌ No | ✅ Yes | ❌ No | ❌ No |
-| Release (binaries + docs) | ❌ No | ❌ No | ✅ Yes | ❌ No |
-| Discover Versions | ❌ No | ❌ No | ❌ No | ✅ Weekly |
-| Sync External | ❌ No | ❌ No | ❌ No | ❌ No |
+| Workflow | Triggers on Source Code | Triggers on Packages | Triggers on Docs | Triggers on Tag | Scheduled |
+|----------|-------------------------|---------------------|------------------|-----------------|-----------|
+| TSI Tests | ✅ Yes | ✅ Yes | ❌ No | ❌ No | ❌ No |
+| Documentation | ❌ No | ❌ No | ✅ Yes | ❌ No | ❌ No |
+| Package Validation | ❌ No | ✅ Yes | ❌ No | ❌ No | ❌ No |
+| Release (binaries + docs) | ❌ No | ❌ No | ❌ No | ✅ Yes | ❌ No |
+| Discover Versions | ❌ No | ❌ No | ❌ No | ❌ No | ✅ Weekly |
+| Sync External | ❌ No | ❌ No | ❌ No | ❌ No | ❌ No |
 
 ## Benefits
 
@@ -115,7 +134,7 @@ git commit -am "test: source code change"
 git push
 ```
 
-**Expected:** TSI Tests workflow runs, Validate Packages does NOT run
+**Expected:** TSI Tests workflow runs, Package Validation does NOT run
 
 ### Test 2: Package File Change
 
@@ -126,7 +145,7 @@ git commit -am "test: package change"
 git push
 ```
 
-**Expected:** Both TSI Tests and Validate Packages workflows run (both trigger on `packages/**`)
+**Expected:** Both TSI Tests and Package Validation workflows run (both trigger on `packages/**`)
 
 ### Test 3: Documentation Change
 

mkdocs.yml

@@ -71,6 +71,7 @@ nav:
   - Reference:
     - CLI Reference: reference/cli-reference.md
     - Package Repository: reference/package-repository.md
+    - Basic Packages: Basic_Packages.md
     - Scripts: reference/scripts.md
     - Bootstrap Options: reference/bootstrap-options.md