docs: restructure documentation, add CLI reference and workflows

.github/workflows/release.yml → .github/workflows/release-cli.yml

@@ -1,9 +1,9 @@
-name: Release
+name: Release CLI
 
 on:
   push:
     tags:
-      - 'v*'
+      - 'cli-*'
 
 permissions:
   contents: write
@@ -12,34 +12,6 @@ env:
   CARGO_TERM_COLOR: always
 
 jobs:
-  # Job 1: Package distributable templates
-  package-templates:
-    name: Package Templates
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Read version from Cargo.toml
-        id: version
-        run: |
-          VERSION=$(grep '^version' cli/Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
-          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
-
-      - name: Create distribution ZIP
-        run: |
-          mkdir -p dist-staging
-          cp -a dist/. dist-staging/
-          cd dist-staging
-          zip -r "../devtrail-v${{ steps.version.outputs.version }}.zip" .
-          cd ..
-
-      - name: Upload template artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: templates
-          path: devtrail-v${{ steps.version.outputs.version }}.zip
-
-  # Job 2: Build CLI binaries (cross-platform)
   build-cli:
     name: Build CLI (${{ matrix.target }})
     runs-on: ${{ matrix.os }}
@@ -71,13 +43,23 @@ jobs:
         if: matrix.os == 'ubuntu-latest'
         run: sudo apt-get update && sudo apt-get install -y libssl-dev pkg-config
 
-      - name: Read version
+      - name: Extract version from tag
         id: version
         shell: bash
         run: |
-          VERSION=$(grep '^version' cli/Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          VERSION="${GITHUB_REF_NAME#cli-}"
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
+      - name: Verify Cargo.toml version matches tag
+        shell: bash
+        run: |
+          CARGO_VERSION=$(grep '^version' cli/Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          TAG_VERSION="${GITHUB_REF_NAME#cli-}"
+          if [ "$CARGO_VERSION" != "$TAG_VERSION" ]; then
+            echo "ERROR: Cargo.toml version ($CARGO_VERSION) does not match tag version ($TAG_VERSION)"
+            exit 1
+          fi
+
       - name: Build release binary
         run: cargo build --release --manifest-path cli/Cargo.toml --target ${{ matrix.target }}
 
@@ -106,18 +88,17 @@ jobs:
           name: cli-${{ matrix.target }}
           path: ${{ env.ARCHIVE }}
 
-  # Job 3: Create GitHub Release
   create-release:
     name: Create Release
-    needs: [package-templates, build-cli]
+    needs: [build-cli]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
-      - name: Read version
+      - name: Extract version from tag
         id: version
         run: |
-          VERSION=$(grep '^version' cli/Cargo.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')
+          VERSION="${GITHUB_REF_NAME#cli-}"
           echo "version=$VERSION" >> "$GITHUB_OUTPUT"
 
       - name: Download all artifacts
@@ -136,6 +117,6 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           gh release create "${{ github.ref_name }}" \
-            --title "DevTrail ${{ github.ref_name }}" \
+            --title "DevTrail CLI ${{ steps.version.outputs.version }}" \
             --generate-notes \
             release/*

.github/workflows/release-framework.yml

@@ -0,0 +1,39 @@
+name: Release Framework
+
+on:
+  push:
+    tags:
+      - 'fw-*'
+
+permissions:
+  contents: write
+
+jobs:
+  package-framework:
+    name: Package Framework
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION="${GITHUB_REF_NAME#fw-}"
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Create distribution ZIP
+        run: |
+          mkdir -p dist-staging
+          cp -a dist/. dist-staging/
+          cd dist-staging
+          zip -r "../devtrail-fw-${{ steps.version.outputs.version }}.zip" .
+          cd ..
+
+      - name: Create GitHub Release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ github.ref_name }}" \
+            --title "DevTrail Framework ${{ steps.version.outputs.version }}" \
+            --generate-notes \
+            "devtrail-fw-${{ steps.version.outputs.version }}.zip"

CONTRIBUTING.md

@@ -314,23 +314,27 @@ The release binary is optimized with LTO and stripped for minimal size.
 
 ```
 cli/src/
-├── main.rs          # Entry point + clap CLI definition
+├── main.rs              # Entry point + clap CLI definition
 ├── commands/
-│   ├── mod.rs       # Subcommand routing
-│   ├── init.rs      # devtrail init [path]
-│   ├── update.rs    # devtrail update
-│   ├── remove.rs    # devtrail remove [--full]
-│   ├── update_cli.rs # devtrail update-cli
-│   └── about.rs     # devtrail about
-├── config.rs        # Config and checksums management
-├── download.rs      # GitHub Releases download
-├── inject.rs        # Directive file injection (markers)
-├── manifest.rs      # dist-manifest.yml parsing
-├── platform.rs      # OS/arch detection for binary downloads
-├── self_update.rs   # CLI binary self-update logic
-└── utils.rs         # Helpers (hashing, colors, paths)
+│   ├── mod.rs           # Subcommand routing
+│   ├── init.rs          # devtrail init [path]
+│   ├── update.rs        # devtrail update (combined)
+│   ├── update_framework.rs # devtrail update-framework
+│   ├── update_cli.rs    # devtrail update-cli
+│   ├── remove.rs        # devtrail remove [--full]
+│   ├── status.rs        # devtrail status [path]
+│   └── about.rs         # devtrail about
+├── config.rs            # Config and checksums management
+├── download.rs          # GitHub Releases API (prefix-filtered)
+├── inject.rs            # Directive file injection (markers)
+├── manifest.rs          # dist-manifest.yml parsing
+├── platform.rs          # OS/arch detection for binary downloads
+├── self_update.rs       # CLI binary self-update logic
+└── utils.rs             # Helpers (hashing, colors, paths)
 ```
 
+> **Note**: Framework and CLI use independent versioning (`fw-*` and `cli-*` tags). See [CLI Reference](docs/adopters/CLI-REFERENCE.md#versioning) for details.
+
 ---
 
 ## Questions?

README.md

@@ -123,30 +123,41 @@ devtrail init .
 
 The CLI downloads the latest DevTrail release, sets up the framework, and configures your AI agent directive files automatically.
 
-```bash
-# Update DevTrail documents to latest version
-devtrail update
+### Versioning
 
-# Update the CLI binary itself
-devtrail update-cli
+DevTrail uses independent version tags for each component:
 
-# Show authorship and license info
-devtrail about
+| Component | Tag prefix | Example | Includes |
+|-----------|-----------|---------|----------|
+| Framework | `fw-` | `fw-2.1.0` | Templates, governance, directives, scripts |
+| CLI | `cli-` | `cli-1.0.0` | The `devtrail` binary |
 
-# Remove DevTrail
-devtrail remove
-```
+Check installed versions with `devtrail status` or `devtrail about`.
+
+### CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `devtrail init [path]` | Initialize DevTrail in a project |
+| `devtrail update` | Update both framework and CLI |
+| `devtrail update-framework` | Update only the framework |
+| `devtrail update-cli` | Update the CLI binary |
+| `devtrail remove [--full]` | Remove DevTrail from project |
+| `devtrail status [path]` | Show installation health and doc stats |
+| `devtrail about` | Show version and license info |
+
+See [CLI Reference](docs/adopters/CLI-REFERENCE.md) for detailed usage.
 
 ### Option 2: Manual Setup
 
 ```bash
-# Download the latest release ZIP from GitHub
-# https://github.com/StrangeDaysTech/devtrail/releases/latest
+# Download the latest framework release ZIP from GitHub
+# Go to https://github.com/StrangeDaysTech/devtrail/releases
+# and download the latest fw-* release (e.g., fw-2.1.0)
 
 # Extract and copy to your project
-cp -r .devtrail your-project/
-cp DEVTRAIL.md your-project/
-cp -r scripts your-project/
+unzip devtrail-fw-*.zip -d your-project/
+cd your-project
 
 # Commit
 git add .devtrail/ DEVTRAIL.md scripts/
@@ -166,17 +177,19 @@ DevTrail documentation is organized by audience:
 | [**Adopters**](docs/adopters/) | Teams adopting DevTrail in their projects | [ADOPTION-GUIDE.md](docs/adopters/ADOPTION-GUIDE.md) |
 | [**Contributors**](docs/contributors/) | Developers contributing to DevTrail | [TRANSLATION-GUIDE.md](docs/contributors/TRANSLATION-GUIDE.md) |
 
-**Adopters**: Follow the [Adoption Guide](docs/adopters/ADOPTION-GUIDE.md) for step-by-step instructions, migration strategies for existing projects, and team rollout plans.
+**Adopters**: Follow the [Adoption Guide](docs/adopters/ADOPTION-GUIDE.md) for step-by-step instructions, the [CLI Reference](docs/adopters/CLI-REFERENCE.md) for command details, and the [Workflows Guide](docs/adopters/WORKFLOWS.md) for daily usage patterns.
 
 **Contributors**: See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines, and the [Translation Guide](docs/contributors/TRANSLATION-GUIDE.md) for adding new languages.
 
 ### Key References
 
 | Document | Description |
 |----------|-------------|
-| [**📘 Quick Reference**](dist/.devtrail/QUICK-REFERENCE.md) | One-page overview of document types and naming |
+| [**Quick Reference**](dist/.devtrail/QUICK-REFERENCE.md) | One-page overview of document types and naming |
 | [DEVTRAIL.md](dist/DEVTRAIL.md) | Unified governance rules (source of truth) |
 | [ADOPTION-GUIDE.md](docs/adopters/ADOPTION-GUIDE.md) | Adoption guide for new/existing projects |
+| [CLI-REFERENCE.md](docs/adopters/CLI-REFERENCE.md) | Complete CLI command reference |
+| [WORKFLOWS.md](docs/adopters/WORKFLOWS.md) | Recommended daily workflows and team patterns |
 
 ### Internal Structure
 

cli/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "devtrail-cli"
-version = "2.1.0"
+version = "1.0.0"
 edition = "2021"
 description = "CLI tool for DevTrail - Documentation Governance for AI-Assisted Development"
 license = "MIT"

cli/src/commands/about.rs

@@ -1,6 +1,8 @@
 use anyhow::Result;
 use colored::Colorize;
 
+use crate::manifest::DistManifest;
+
 pub fn run() -> Result<()> {
     let version = env!("CARGO_PKG_VERSION");
     let description = env!("CARGO_PKG_DESCRIPTION");
@@ -15,6 +17,19 @@ pub fn run() -> Result<()> {
         "DevTrail CLI".bold(),
         format!("v{version}").dimmed()
     );
+
+    // Show framework version if installed
+    if let Ok(cwd) = std::env::current_dir() {
+        let manifest_path = cwd.join(".devtrail/dist-manifest.yml");
+        if let Ok(manifest) = DistManifest::load(&manifest_path) {
+            println!(
+                "  {} {}",
+                "Framework:".dimmed(),
+                format!("v{}", manifest.version).dimmed()
+            );
+        }
+    }
+
     println!("  {}", description.dimmed());
     println!();
     println!("  {}  {}", "Author:".cyan(), authors);

cli/src/commands/mod.rs

@@ -4,3 +4,4 @@ pub mod remove;
 pub mod status;
 pub mod update;
 pub mod update_cli;
+pub mod update_framework;

cli/src/commands/status.rs

@@ -53,11 +53,14 @@ pub fn run(path: &str) -> Result<()> {
     let version = load_version(&target);
     let language = load_language(&target);
 
+    let cli_version = env!("CARGO_PKG_VERSION");
+
     println!();
     println!("{}", "DevTrail Status".bold());
-    println!("  {}  {}", "Path:".dimmed(), target.display());
-    println!("  {}  {}", "Version:".dimmed(), version);
-    println!("  {} {}", "Language:".dimmed(), language);
+    println!("  {}      {}", "Path:".dimmed(), target.display());
+    println!("  {} {}", "Framework:".dimmed(), version);
+    println!("  {}       {}", "CLI:".dimmed(), cli_version);
+    println!("  {}  {}", "Language:".dimmed(), language);
 
     // Phase 2: Structure check
     println!();