### Setup Rust Toolchain and Git

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation.md

Installs or updates the Rust toolchain to the required version and verifies the presence of Git for project management.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup update stable
rustc --version
git --version
```

--------------------------------

### Rust Crate Root Documentation Example (`lib.rs`)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Provides an example of documentation comments for the root of a Rust crate (`lib.rs`). It includes a module-level summary, a quick start example, and a link to design documents (ADRs).

```rust
// lib.rs
//! Fast LAFS-compliant message delivery.
//!
//! Provides agents with SSE, webhook, and polling transport with automatic fallback.
//!
//! # Quick Start
//!
//! ```rust
//! let client = signaldock::Client::connect("ws://localhost:9000")?;
//! client.send("agent-b", "hello").await?;
//! # Ok::<(), Box<dyn std::error::Error>>(())
//! ```
//!
//! # Design
//!
//! See [ADR-001](../docs/dev/adr/001-transport-protocol.md).
```

--------------------------------

### Troubleshoot and Configure Environment

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation.md

Provides commands to fix common issues such as missing PATH entries, permission errors, and outdated Rust versions.

```bash
# Add to PATH
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Fix permissions
sudo chown -R $(whoami) ~/.cargo

# Update Rust
rustup update stable
```

--------------------------------

### Initialize and Verify Ferrous Forge

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation-guide.md

Commands to initialize the tool after installation and verify the current version or access help documentation.

```bash
ferrous-forge init
ferrous-forge --version
ferrous-forge --help
```

--------------------------------

### Setup Development Environment (Bash)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/CONTRIBUTING.md

Commands to clone the Ferrous Forge repository, install Rust, build the project, run tests, and execute the project with verbose output.

```bash
# Clone the repository
git clone https://github.com/yourusername/ferrous-forge
cd ferrous-forge

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Build the project
cargo build

# Run tests
cargo test

# Run with verbose output for development
cargo run -- --verbose
```

--------------------------------

### Configure Nix Flakes for Ferrous Forge

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation-guide.md

Example configuration for integrating Ferrous Forge into a project using Nix flakes.

```nix
{
  inputs.ferrous-forge.url = "github:kryptobaseddev/ferrous-forge";
  
  outputs = { self, nixpkgs, ferrous-forge }: {
    # ...
  };
}
```

--------------------------------

### Initialize Ferrous Forge

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation.md

Initializes Ferrous Forge either system-wide or within a specific project directory to configure linting, formatting, and CI/CD templates.

```bash
ferrous-forge init
cd my-project
ferrous-forge init --project
```

--------------------------------

### Build and Install mdBook Environment

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Shell commands to install necessary mdBook plugins, generate Rust API documentation, and build the final prose documentation site.

```bash
cargo install mdbook mdbook-linkcheck mdbook-mermaid mdbook-toc --locked
cargo doc --no-deps
cp -r target/doc/ docs/src/api/
cd docs && mdbook build
```

--------------------------------

### Rust Function Documentation Example with Examples, Errors, and Links

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Illustrates comprehensive documentation for a public Rust function. It includes a concise summary, detailed explanations, an `# Errors` section listing possible error variants, and a runnable `# Examples` section using `include_bytes!`.

```rust
/// Returns the decoded payload from a signed LAFS envelope.
///
/// Verifies HMAC-SHA256 before deserializing.
///
/// # Errors
///
/// - [`Error::InvalidSignature`] — HMAC verification failed
/// - [`Error::Malformed`] — deserialization failed
///
/// # Examples
///
/// ```rust
/// # use my_crate::decode_envelope;
/// let bytes = include_bytes!("../tests/fixtures/valid-envelope.bin");
/// let payload = decode_envelope(bytes)?;
/// assert_eq!(payload.version, 1);
/// # Ok::<(), Box<dyn std::error::Error>>(())
/// ```
pub fn decode_envelope(bytes: &[u8]) -> Result<Payload, Error> { ... }
```

--------------------------------

### Install Ferrous Forge CLI

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/README.md

Provides installation commands for various package managers and the Rust crates.io registry.

```bash
cargo install ferrous-forge
brew install ferrous-forge
yay -S ferrous-forge
nix-env -iA ferrous-forge
choco install ferrous-forge
```

--------------------------------

### Install Ferrous Forge via Cargo

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation.md

Installs the latest version of Ferrous Forge from crates.io and verifies the installation by checking the version.

```bash
cargo install ferrous-forge
ferrous-forge --version
```

--------------------------------

### Hiding Boilerplate in Rust Doc Tests

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Illustrates how to use lines prefixed with `# ` to hide setup code in Rust documentation examples, making the rendered documentation cleaner while still ensuring the code compiles and runs.

```rust
/// ```rust
/// # use my_crate::Client;
/// # let rt = tokio::runtime::Runtime::new().unwrap();
/// # rt.block_on(async {
/// let client = Client::new("https://api.example.com");
/// let agent = client.fetch("cleo").await?;
/// println!("Got agent: {}", agent.name);
/// # Ok::<(), Box<dyn std::error::Error>>(()) 
/// # });
/// ```

```

--------------------------------

### Using Ferrous Forge Commands (Bash)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/dev/rust-ecosystem-guide.md

Examples of commands provided by Ferrous Forge after installation. It includes initializing new projects and potentially hijacking standard commands like `cargo new`.

```bash
# After installation, users get:
ferrous-forge init     # <- This is a BINARY created by our crate
cargo new my-project   # <- This gets hijacked by our system

```

--------------------------------

### Local Development Environment Setup

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/DOGFOODING.md

Commands for maintainers to initialize the project and install safety hooks locally. This ensures developers are running the same validation checks as the CI pipeline.

```bash
cargo install --path .
ferrous-forge init --project
ferrous-forge safety install
```

--------------------------------

### Rust Documentation Section Examples: Safety, Errors, Panics

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Provides concrete examples of how to document specific sections in Rust code, including `# Safety` for unsafe functions, `# Errors` for functions returning `Result`, and `# Panics` for functions that can panic.

```rust
/// # Safety
///
/// `ptr` must be non-null, properly aligned for `T`, and valid for reads.
/// The memory must not be mutated for the duration of the returned reference.
pub unsafe fn as_ref_unchecked<T>(ptr: *const T) -> &'static T { ... }

/// # Errors
///
/// Returns [`Error::Timeout`] if the upstream did not respond within the configured deadline.
/// Returns [`Error::Unauthorized`] if the token is expired or invalid.
pub async fn fetch(&self, id: &str) -> Result<Agent, Error> { ... }

/// # Panics
///
/// Panics if `capacity` is zero.
pub fn new(capacity: usize) -> Self { ... }
```

--------------------------------

### Code Documentation Example (Rust)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/CONTRIBUTING.md

An example of documenting a public Rust function using doc comments, including arguments, return values, and usage examples.

```rust
/// Processes input according to standards.
///
/// # Arguments
/// * `input` - The data to process
///
/// # Returns
/// Processed result or error
///
/// # Examples
/// ```
/// let result = process("data")?;
/// ```
pub fn process(input: &str) -> Result<String> {
    // Implementation
}
```

--------------------------------

### Check Cargo Wrapper Installation

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Verifies if the Ferrous Forge cargo wrapper is installed and accessible in the system's PATH.

```bash
ls -la ~/.local/bin/cargo
which -a cargo
```

--------------------------------

### Typical Ferrous Forge Usage (Bash)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/dev/rust-ecosystem-guide.md

Illustrates the correct way to install and use Ferrous Forge as a system-wide development tool. It emphasizes installation via `cargo install` rather than adding it as a typical library dependency.

```bash
# Users don't use it as a library dependency:
cargo add ferrous-forge  # ❌ Not typical usage

# Users install it as a system tool:
cargo install ferrous-forge  # ✅ Correct usage

```

--------------------------------

### Generate Shell Completions

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation-guide.md

Commands to generate and install shell auto-completion scripts for bash, zsh, and fish shells.

```bash
ferrous-forge completions bash > ~/.local/share/bash-completion/completions/ferrous-forge
ferrous-forge completions zsh > ~/.zsh/completions/_ferrous-forge
ferrous-forge completions fish > ~/.config/fish/completions/ferrous-forge.fish
```

--------------------------------

### Install Ferrous Forge via Package Managers

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation-guide.md

Commands to install the Ferrous Forge CLI using common system package managers. These commands assume the respective package manager is configured on the host system.

```bash
brew tap kryptobaseddev/tap
brew install ferrous-forge
```

```bash
yay -S ferrous-forge
```

```bash
nix-env -iA nixpkgs.ferrous-forge
```

```powershell
choco install ferrous-forge
```

```bash
cargo install ferrous-forge
```

--------------------------------

### Install Forge CLI via Package Managers

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/ideas/Forge-README.md

Commands to install the Forge CLI tool across different environments including Rust Cargo, npm, Homebrew, Arch Linux, and Nix.

```bash
cargo install forge
```

```bash
npm install -D @forge/cli
```

```bash
brew install forge
yay -S forge
nix-env -iA forge
```

--------------------------------

### Rust Binary Crate Example

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/dev/rust-ecosystem-guide.md

Demonstrates a Rust binary crate, typically defined in `main.rs`. This type of crate produces an executable program.

```rust
// src/main.rs - Creates an executable program
fn main() {
    println!("This is an executable!");
}

```

--------------------------------

### Example Unit Test (Rust)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/CONTRIBUTING.md

A basic example of a unit test function within a Rust module, demonstrating arrange, act, and assert steps.

```rust
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_feature() {
        // Arrange
        let input = "test";
        
        // Act
        let result = process(input);
        
        // Assert
        assert_eq!(result, expected);
    }
}
```

--------------------------------

### Install Ferrous Forge via Homebrew

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/packaging/homebrew/README.md

Commands to install the Ferrous Forge package using the official tap or a direct URL to the formula file. This is the primary method for deploying the binary on supported platforms.

```bash
brew tap kryptobaseddev/tap
brew install ferrous-forge
```

```bash
brew install https://raw.githubusercontent.com/kryptobaseddev/ferrous-forge/main/packaging/homebrew/ferrous-forge.rb
```

--------------------------------

### Install Ferrous Forge CLI

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/editors/vscode/README.md

Install the required Ferrous Forge binary via Cargo. This is a prerequisite for the VS Code extension to perform local validation.

```bash
cargo install ferrous-forge
```

```bash
git clone https://github.com/kryptobaseddev/ferrous-forge.git
cd ferrous-forge
cargo install --path .
```

--------------------------------

### Install Ferrous Forge using nix profile (flakes)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/packaging/nix/README.md

Installs the Ferrous Forge package using `nix profile install` for projects utilizing Nix flakes. This command directly installs the package from its GitHub repository.

```bash
nix profile install github:kryptobaseddev/ferrous-forge
```

--------------------------------

### Install Ferrous Forge using nix-env

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/packaging/nix/README.md

Installs the Ferrous Forge package using the `nix-env` command. This is a straightforward method for users who manage packages with `nix-env`.

```bash
nix-env -iA nixpkgs.ferrous-forge
```

--------------------------------

### Check Pre-commit Hook Executability

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Verifies that the .git/hooks/pre-commit script has execute permissions and makes it executable if necessary.

```bash
ls -la .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit
```

--------------------------------

### Rust Library Crate Example

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/dev/rust-ecosystem-guide.md

Illustrates a Rust library crate, identified by `lib.rs`. This type of crate provides functionality that can be used by other programs.

```rust
// src/lib.rs - Provides functionality for OTHER programs to use
pub fn some_function() -> String {
    "Hello from library!".to_string()
}

```

--------------------------------

### List Ferrous Forge Configuration

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Displays the current configuration settings loaded by Ferrous Forge, helping to debug configuration loading issues.

```bash
ferrous-forge config --list
```

--------------------------------

### Fix Issues and Commit with Hooks

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Demonstrates the workflow of fixing code issues identified by Ferrous Forge and then committing the changes with hooks enabled.

```bash
ferrous-forge fix
git add -A
git commit
```

--------------------------------

### cargo-rdme Configuration and Usage

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Example configurations for `cargo-rdme`, including specifying the README path and setting base URLs for intra-links. Also shows how `//!` comments in `lib.rs` are used to populate the README.

```markdown
# My Crate

<!-- cargo-rdme start -->
...auto-generated from lib.rs //! comments...
<!-- cargo-rdme end -->

## License
...

```

```rust
//! Fast LAFS-compliant message delivery.
//!
//! # Quick Start
//!
//! ```rust
//! let client = signaldock::Client::connect("ws://localhost:9000")?;
//! client.send("agent-b", "hello").await?;
//! # Ok::<(), Box<dyn std::error::Error>>(()) 
//! ```

```

```toml
[readme]
path = "README.md"

[intralinks]
docs-rs-base-url = "https://docs.rs"

```

--------------------------------

### Reset Ferrous Forge Installation

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation.md

Completely removes the Ferrous Forge installation and configuration files to allow for a clean reinstallation.

```bash
ferrous-forge uninstall --confirm
rm -rf ~/.config/ferrous-forge
cargo install ferrous-forge
ferrous-forge init
```

--------------------------------

### Jenkins Pipeline for Ferrous Forge (Groovy)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/integration.md

Defines a Jenkins declarative pipeline to integrate Ferrous Forge validation. It includes stages for setup (installing Ferrous Forge) and validation.

```groovy
pipeline {
  agent any
  
  stages {
    stage('Setup') {
      steps {
        sh 'cargo install ferrous-forge'
      }
    }
    
    stage('Validate') {
      steps {
        sh 'ferrous-forge validate'
      }
    }
  }
}
```

--------------------------------

### Verify Ferrous Forge Installation

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Checks if the 'ferrous-forge' executable exists in the expected location and lists installed Cargo packages to confirm successful installation.

```bash
ls -la ~/.cargo/bin/ferrous-forge
cargo install --list | grep ferrous-forge
```

--------------------------------

### Force Update Ferrous Forge Installation

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Installs or updates the Ferrous Forge tool to the latest version, using the '--force' flag to overwrite existing installations.

```bash
cargo install ferrous-forge --force
```

--------------------------------

### Rust Documentation Generation with rustdoc, cargo-rdme, and mdBook

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Explains the tools and processes used to generate different forms of documentation for the project. This includes API references, README files, and user guides, highlighting the source of each output and the commands used.

```markdown
| Output | Source | Tool | Command |
|--------|--------|------|---------|
| `target/doc/` (API reference) | `///` and `//!` in `src/` | rustdoc | `cargo doc --no-deps` |
| `README.md` | `//!` in `lib.rs` | cargo-rdme | `cargo rdme` |
| `book/` (guides + API link) | `docs/src/` markdown | mdBook | `mdbook build` |
```

--------------------------------

### Rust Beginner Learning Binary Crate (Rust)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/dev/rust-ecosystem-guide.md

A simple Rust code example for beginners learning to create a basic binary crate. This serves as a contrast to the complexity of Ferrous Forge, which is a sophisticated CLI tool with library components and system integration.

```rust
// You're learning to create:
fn main() {           // ← Simple binary crate
    println!("Hello!");
}

// Ferrous Forge is:
// - Complex binary crate (CLI tool)
// - With library components (reusable code)  
// - Plus system integration (shell hijacking)
// - Plus package management (templates, updates)

```

--------------------------------

### Manually Install Specific Ferrous Forge Version

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Installs a specific version of Ferrous Forge, useful for rolling back to a known stable version or testing a particular release.

```bash
cargo install ferrous-forge --version 1.7.0 --force
```

--------------------------------

### Recommended Cargo.toml Starter Block for Rust Libraries

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

This TOML block is designed for new Rust library crates. It enforces linting rules across Rust, Rustdoc, and Clippy to ensure code quality and documentation standards without requiring manual source file modifications. It sets specific warning and deny levels for various linting categories.

```toml
[lints.rust]
missing_docs = "warn"

[lints.rustdoc]
broken_intra_doc_links   = "deny"
invalid_html_tags        = "deny"
missing_crate_level_docs = "warn"
bare_urls                = "warn"
redundant_explicit_links = "warn"
unescaped_backticks      = "warn"

[lints.clippy]
missing_safety_doc           = "deny"
missing_errors_doc           = "warn"
missing_panics_doc           = "warn"
empty_docs                   = "warn"
doc_markdown                 = "warn"
needless_doctest_main        = "warn"
suspicious_doc_comments      = "warn"
too_long_first_doc_paragraph = "warn"

```

--------------------------------

### Initialize Ferrous Forge in Projects

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/README.md

Commands to set up Ferrous Forge in new or existing Rust projects, generating necessary configuration and Git hook files.

```bash
cargo new my-project
cd my-project
ferrous-forge init --project

cd existing-project
ferrous-forge init --project
ferrous-forge fix
```

--------------------------------

### Clear Cargo Registry Cache

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Removes corrupted or outdated cached registry data for Cargo, which can sometimes resolve installation or update issues.

```bash
rm -rf ~/.cargo/registry/cache
cargo clean
```

--------------------------------

### Fix Cargo Ownership Issues

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Resolves 'Permission denied' errors during Cargo installation by ensuring the current user owns the .cargo directory.

```bash
sudo chown -R $(whoami) ~/.cargo
```

--------------------------------

### Clear Cargo Cache and Reinstall

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Clears all cached Cargo data and then reinstalls Ferrous Forge, useful for resolving complex update or installation issues.

```bash
cargo cache -a
cargo install ferrous-forge
```

--------------------------------

### Generate and Check Rust Documentation Coverage

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Commands to generate documentation with coverage reports and to fail CI if the doc coverage falls below a specified threshold. Requires nightly Rust.

```bash
# Human-readable table
RUSTDOCFLAGS="-Z unstable-options --show-coverage" \
  cargo +nightly doc --no-deps 2>&1

```

```bash
# Add to CI to fail below a threshold:
# Requires nightly + jq
RUSTDOCFLAGS="-Z unstable-options --show-coverage --output-format json" \
  cargo +nightly doc --no-deps -q 2>&1 \
  | jq 'to_entries[] | select(.key | endswith(".rs")) | .value | .with_docs / .total' \
  | awk '{if ($1 < 0.90) { print "Doc coverage below 90%"; exit 1 }}'

```

--------------------------------

### GitHub Actions CI/CD Workflow for Ferrous Forge (YAML)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/integration.md

Defines a GitHub Actions workflow to automatically validate code using Ferrous Forge on push or pull request events. It includes steps to check out code, install Rust, install Ferrous Forge, and run the validation command.

```yaml
name: Ferrous Forge Validation

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          components: rustfmt, clippy
      
      - name: Install Ferrous Forge
        run: cargo install ferrous-forge
      
      - name: Run Ferrous Forge Validation
        run: ferrous-forge validate
```

--------------------------------

### Update Ferrous Forge

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/installation-guide.md

Methods for updating the Ferrous Forge binary, including the built-in update command and package manager specific upgrade commands.

```bash
ferrous-forge update
```

```bash
brew update && brew upgrade ferrous-forge
yay -Syu ferrous-forge
nix-env -uA nixpkgs.ferrous-forge
choco upgrade ferrous-forge
cargo install ferrous-forge --force
```

--------------------------------

### Generate README from Rust Source with cargo-rdme

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Instructions for using `cargo-rdme` to automatically generate or update the `README.md` file from `lib.rs`'s `//!` comments. This ensures the README stays synchronized with the library's documentation.

```bash
cargo install cargo-rdme --locked
cargo rdme           # sync README now
cargo rdme --check   # CI: exit non-zero if README is out of sync

```

--------------------------------

### Configure mdBook Project Settings

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Defines the configuration for an mdBook project, including output settings, preprocessors for Mermaid diagrams and table of contents, and link checking policies.

```toml
[book]
title = "My Crate"
src = "src"

[output.html]
git-repository-url = "https://github.com/your-org/your-crate"

[preprocessor.mermaid]
command = "mdbook-mermaid"

[preprocessor.toc]
command = "mdbook-toc"

[output.linkcheck]
warning-policy = "error"
exclude = ["https://crates.io/.*"]
```

--------------------------------

### Show Ferrous Forge Configuration Sources

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/troubleshooting.md

Lists the files and locations from which Ferrous Forge is loading its configuration, aiding in verifying the correct configuration file is being used.

```bash
ferrous-forge config --sources
```

--------------------------------

### CircleCI Configuration for Ferrous Forge (YAML)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/integration.md

Configures a CircleCI pipeline to validate code using Ferrous Forge. It specifies a Rust Docker image and includes steps to install Ferrous Forge and run the validation command.

```yaml
version: 2.1

jobs:
  ferrous-forge:
    docker:
      - image: rust:latest
    steps:
      - checkout
      - run:
          name: Install Ferrous Forge
          command: cargo install ferrous-forge
      - run:
          name: Validate Code
          command: ferrous-forge validate

workflows:
  version: 2
  validate:
    jobs:
      - ferrous-forge
```

--------------------------------

### Automate Documentation CI Pipeline

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

A GitHub Actions workflow that enforces documentation standards, including linting, broken link checks, doc tests, and README synchronization.

```yaml
name: Documentation
on: [push, pull_request]

jobs:
  lint-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Rust stable
        uses: dtolnay/rust-toolchain@stable
        with:
          components: clippy
      - name: cargo check (missing_docs)
        run: cargo check
      - name: cargo clippy (doc lints)
        run: |
          cargo clippy -- \
            -D clippy::missing_safety_doc \
            -W clippy::missing_errors_doc \
            -W clippy::missing_panics_doc \
            -W clippy::empty_docs \
            -W clippy::doc_markdown
      - name: cargo doc (broken links + html)
        run: |
          RUSTDOCFLAGS="\
            -D rustdoc::broken_intra_doc_links \
            -D rustdoc::invalid_html_tags \
            -W rustdoc::bare_urls" \
          cargo doc --no-deps --all-features
      - name: cargo test --doc
        run: cargo test --doc
      - name: Check README is in sync
        run: |
          cargo install cargo-rdme --locked
          cargo rdme --check
  build-book:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install mdbook tools
        run: |
          cargo install mdbook --locked
          cargo install mdbook-linkcheck --locked
      - name: Build prose docs
        run: cd docs && mdbook build
```

--------------------------------

### Rust Public API Documentation Standards

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/standards.md

Illustrates the requirement for documenting all public Rust items, starting with a one-line summary. The preferred method includes a detailed description, arguments, return values, and examples, as shown in the documented function.

```rust
// ❌ Missing documentation
pub fn process(data: &str) -> Result<String> {
    // ...
}

// ✅ Properly documented
/// Processes the input data and returns the transformed result.
///
/// # Arguments
/// * `data` - The input string to process
///
/// # Returns
/// The processed string or an error if processing fails
///
/// # Examples
/// ```
/// let result = process("hello")?;
/// assert_eq!(result, "HELLO");
/// ```
pub fn process(data: &str) -> Result<String> {
    // ...
}
```

--------------------------------

### GitLab CI Configuration for Ferrous Forge (YAML)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/integration.md

Sets up a GitLab CI pipeline to validate code with Ferrous Forge. It uses a Rust Docker image, installs Ferrous Forge, and runs the validation command. Caching is configured for the target and .cargo directories.

```yaml
ferrous-forge:
  stage: test
  image: rust:latest
  before_script:
    - cargo install ferrous-forge
  script:
    - ferrous-forge validate
  cache:
    paths:
      - target/
      - .cargo/
```

--------------------------------

### Test Local Homebrew Formula Build

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/packaging/homebrew/README.md

Commands to install the package from a local formula file and run the built-in test suite to ensure functionality.

```bash
brew install --build-from-source ./ferrous-forge.rb
brew test ferrous-forge
```

--------------------------------

### Forge Unified Configuration Example (TOML)

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/ideas/Forge-VISION.md

Illustrates the hierarchical TOML configuration file for Forge, showing user defaults and language-specific settings. This unified configuration simplifies managing standards across different programming languages.

```toml
# ~/.config/forge/config.toml (User defaults)
[validation]
max_file_lines = 500
require_documentation = true
# Language-specific sections
[language.rust]
edition = "2024"
unsafe_forbidden = true
[language.typescript]
target = "ES2022"
strict = true
[language.go]
go_version = "1.23"
[language.python]
python_version = "3.12"
```

--------------------------------

### Forge CLI: Project Initialization and Validation

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/ideas/Forge-VISION.md

Demonstrates initializing Forge in a project, detecting languages, configuring standards, and validating code quality across multiple languages. This CLI workflow streamlines the setup and maintenance of code standards.

```bash
# Forge auto-detects languages in your project
$ forge init --project
Detected languages: Rust, TypeScript, Go
Installing safety pipeline for all detected languages...
# All languages use the same config hierarchy
$ forge config lock required_edition --reason="Team decision"
✅ Locked for Rust: required_edition
✅ Locked for TypeScript: target
✅ Locked for Go: go_version
# One command validates everything
$ forge validate
🦀 Rust: 0 violations
⚡ TypeScript: 1 violation (missing TSDoc on public export)
🐹 Go: 0 violations
🐍 Python: 2 violations (line too long)
# Safety pipeline blocks commits in ALL languages
$ git commit -m "feat: add feature"
🛡️ Forge blocked commit:
  - TypeScript: Missing TSDoc (see src/api.ts:42)
  - Python: Line too long (see src/utils.py:15)
# One bypass works across languages
$ forge safety bypass --stage=pre-commit --reason="WIP"
✅ Bypass active for: Rust, TypeScript, Go, Python
```

--------------------------------

### Run Rust Doc Tests

Source: https://github.com/kryptobaseddev/ferrous-forge/blob/main/docs/RUSTDOC-STANDARDS.md

Commands to execute all documentation tests within a Rust project. The `--nocapture` flag can be used to display output from `println!` statements for debugging.

```bash
cargo test --doc
cargo test --doc -- --nocapture    # show println! output for debugging

```