diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index b35de7b..f5881e7 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -1,45 +1,58 @@
 # Clone the repository
 
-git clone <https://github.com/hyperpolymath/http-capability-gateway.git>
+git clone https://github.com/hyperpolymath/http-capability-gateway.git
 cd http-capability-gateway
 
-# Using Nix (recommended for reproducibility)
+# Using Toolbox
 
-nix develop
+toolbox create http-capability-gateway-dev
+toolbox enter http-capability-gateway-dev
 
-# Or using toolbox/distrobox
+# Install dependencies manually
 
-toolbox create http-capability-gateway-dev toolbox enter
-http-capability-gateway-dev \# Install dependencies manually
+mix deps.get
 
 # Verify setup
 
-just check \# or: cargo check / mix compile / etc. just test \# Run test
-suite
-
-
-    ### Repository Structure
-
-http-capability-gateway/ ├── src/ \# Source code (Perimeter 1-2) ├──
-lib/ \# Library code (Perimeter 1-2) ├── extensions/ \# Extensions
-(Perimeter 2) ├── plugins/ \# Plugins (Perimeter 2) ├── tools/ \#
-Tooling (Perimeter 2) ├── docs/ \# Documentation (Perimeter 3) │ ├──
-architecture/ \# ADRs, specs (Perimeter 2) │ └── proposals/ \# RFCs
-(Perimeter 3) ├── examples/ \# Examples (Perimeter 3) ├── spec/ \# Spec
-tests (Perimeter 3) ├── tests/ \# Test suite (Perimeter 2-3) ├──
-.well-known/ \# Protocol files (Perimeter 1-3) ├── .github/ \# GitHub
-config (Perimeter 1) │ ├── ISSUE_TEMPLATE/ │ └── workflows/ ├──
-CHANGELOG.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md \# This file ├──
-GOVERNANCE.md ├── LICENSE ├── MAINTAINERS.md ├── README.adoc ├──
-SECURITY.md ├── flake.nix \# Nix flake (Perimeter 1) └── Justfile \#
-Task runner (Perimeter 1)
-
-
-    ---
-
-    ## How to Contribute
-
-    ### Reporting Bugs
+just validate   # or: cargo check / mix compile / etc.
+just test    # Run test suite
+
+## Repository Structure
+
+```text
+http-capability-gateway/
+├── src/ # Source code (Perimeter 1-2)
+├── lib/ # Library code (Perimeter 1-2)
+├── extensions/ # Extensions (Perimeter 2)
+├── plugins/ # Plugins (Perimeter 2)
+├── tools/ # Tooling (Perimeter 2)
+├── docs/ # Documentation (Perimeter 3)
+│   ├── architecture/ # ADRs, specs (Perimeter 2)
+│   └── proposals/ # RFCs (Perimeter 3)
+├── examples/ # Examples (Perimeter 3)
+├── spec/ # Spec tests (Perimeter 3)
+├── tests/ # Test suite (Perimeter 2-3)
+├── .well-known/ # Protocol files (Perimeter 1-3)
+├── .github/ # GitHub config (Perimeter 1)
+│   ├── CONTRIBUTING.md # This file
+│   ├── ISSUE_TEMPLATE/
+│   └── workflows/
+├── CHANGELOG.md
+├── CODE_OF_CONDUCT.md
+├── GOVERNANCE.md
+├── LICENSE
+├── MAINTAINERS.md
+├── README.adoc
+├── SECURITY.md
+├── flake.nix # Nix flake (Perimeter 1)
+└── Justfile # Task runner (Perimeter 1)
+```
+
+---
+
+## How to Contribute
+
+### Reporting Bugs
 
     **Before reporting**:
     1. Search existing issues
@@ -56,7 +69,7 @@ Task runner (Perimeter 1)
     - Expected vs actual behaviour
     - Logs, screenshots, or minimal reproduction
 
-    ### Suggesting Features
+### Suggesting Features
 
     **Before suggesting**:
     1. Check the [roadmap](ROADMAP.md) if available
@@ -72,7 +85,7 @@ Task runner (Perimeter 1)
     - Alternatives considered
     - Which perimeter this affects
 
-    ### Your First Contribution
+### Your First Contribution
 
     Look for issues labelled:
 
@@ -83,22 +96,31 @@ Task runner (Perimeter 1)
 
     ---
 
-    ## Development Workflow
+## Development Workflow
+
+### Branch Naming
 
-    ### Branch Naming
+```text
+docs/short-description # Documentation (P3)
+test/what-added # Test additions (P3)
+feat/short-description # New features (P2)
+fix/issue-number-description # Bug fixes (P2)
+refactor/what-changed # Code improvements (P2)
+security/what-fixed # Security fixes (P1-2)
+```
 
-docs/short-description \# Documentation (P3) test/what-added \# Test
-additions (P3) feat/short-description \# New features (P2)
-fix/issue-number-description \# Bug fixes (P2) refactor/what-changed \#
-Code improvements (P2) security/what-fixed \# Security fixes (P1-2)
 
+### Commit Messages
 
-    ### Commit Messages
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
 
-    We follow [Conventional Commits](https://www.conventionalcommits.org/):
+```text
+type(scope): description
 
-():
+Body: what changed and why.
 
-\[optional body\]
+Footer: issue reference, e.g. Closes #123
+[optional body]
 
-\[optional footer\]
+[optional footer]
+```