chore: reorganization compliance: layout_conventions

.gitignore

@@ -1,63 +1,69 @@
-CLAUDE.md
-.claude
-utils/save*sh
-COMMIT_MESSAGE.md
-wrks
-nushell
-nushell-*
-*.tar.gz 
-#*-nushell-plugins.tar.gz
-github-com
-.coder
-target
-distribution
-.qodo
-# enviroment to load on bin/build
+# Claude Code session files (NOT configuration)
+.coder/
+
+# Working directory (experiments, archives)
+.wrks/
+
+# Build artifacts
+target/
+distribution/
+
+# Cargo lock (keep for binaries, ignore for libraries)
+# Cargo.lock is currently tracked - keep as is
+
+# SBOM files (generated, not committed)
+*.sbom.json
+*.sbom.xml
+*.cyclonedx.json
+*.spdx.json
+*.bom.json
+
+# Environment files
 .env
-# OSX trash
+.envrc
+
+# OS-specific
 .DS_Store
+*.pyc
 
-# Vscode files
-.vscode
-
-# Emacs save files
+# Editor files - Emacs
 *~
 \#*\#
 .\#*
 
-# Vim-related files
+# Editor files - Vim
 [._]*.s[a-w][a-z]
 [._]s[a-w][a-z]
 *.un~
 Session.vim
 .netrwhist
 
-# cscope-related files
+# Editor files - VSCode
+.vscode/
+
+# Editor files - Tags
 cscope.*
-
-# User cluster configs
-.kubeconfig
-
 .tags*
 
-# direnv .envrc files
-.envrc
+# Development tools
+.qodo/
+.kubeconfig
 
-# make-related metadata
+# CI/CD metadata
 /.make/
 
-# Just in time generated data in the source, should never be committed
+# Test data
 /test/e2e/generated/bindata.go
 
-# This file used by some vendor repos (e.g. github.com/go-openapi/...) to store secret variables and should not be ignored
+# Vendor workspace
+/Godeps/_workspace
+/bazel-*
+
+# Generated patches
+vendordiff.patch
+
+# Drone secret file (exception - DO NOT ignore)
 !\.drone\.sec
 
-# Godeps workspace
-/Godeps/_workspace
-
-/bazel-*
-*.pyc
-
-# generated by verify-vendor.sh
-vendordiff.patch
+# Claude local settings only
 .claude/settings.local.json

README.md

@@ -1,7 +1,7 @@
 # SecretumVault
 
 <div align="center">
-  <img src="imgs/secretumvault-logo-h.svg" alt="SecretumVault Logo" width="600" />
+  <img src="assets/logos/secretumvault-logo-h.svg" alt="SecretumVault Logo" width="600" />
 </div>
 
 **Post-quantum cryptographic secrets vault for modern infrastructure**
@@ -62,25 +62,25 @@ git clone https://github.com/secretumvault/secretumvault.git
 cd secretumvault
 
 # Build and start
-docker build -t secretumvault:latest .
-docker-compose up -d
+docker build -t secretumvault:latest -f deploy/docker/Dockerfile .
+docker-compose -f deploy/docker/docker-compose.yml up -d
 
 # Verify
 curl http://localhost:8200/v1/sys/health
 
 # View logs
-docker-compose logs -f vault
+docker-compose -f deploy/docker/docker-compose.yml logs -f vault
 ```
 
 ### Kubernetes Deployment
 
 ```bash
 # Deploy to cluster
-kubectl apply -f k8s/01-namespace.yaml
-kubectl apply -f k8s/02-configmap.yaml
-kubectl apply -f k8s/03-deployment.yaml
-kubectl apply -f k8s/04-service.yaml
-kubectl apply -f k8s/05-etcd.yaml
+kubectl apply -f deploy/k8s/01-namespace.yaml
+kubectl apply -f deploy/k8s/02-configmap.yaml
+kubectl apply -f deploy/k8s/03-deployment.yaml
+kubectl apply -f deploy/k8s/04-service.yaml
+kubectl apply -f deploy/k8s/05-etcd.yaml
 
 # Port-forward and access
 kubectl -n secretumvault port-forward svc/vault 8200:8200
@@ -91,12 +91,12 @@ curl http://localhost:8200/v1/sys/health
 
 ```bash
 # Install with default configuration
-helm install vault helm/ \
+helm install vault deploy/helm/ \
   --namespace secretumvault \
   --create-namespace
 
 # Customize backends and engines
-helm install vault helm/ \
+helm install vault deploy/helm/ \
   --namespace secretumvault \
   --create-namespace \
   --set vault.config.storageBackend=postgresql \
@@ -371,7 +371,7 @@ Full API reference: `docs/API.md`
 ### Docker
 
 ```bash
-docker build -t secretumvault:latest .
+docker build -t secretumvault:latest -f deploy/docker/Dockerfile .
 docker run -p 8200:8200 \
   -v /etc/secretumvault:/etc/secretumvault:ro \
   secretumvault:latest
@@ -380,7 +380,7 @@ docker run -p 8200:8200 \
 ### Docker Compose
 
 ```bash
-docker-compose up -d
+docker-compose -f deploy/docker/docker-compose.yml up -d
 ```
 
 Includes: vault, etcd, surrealdb, postgres, prometheus, grafana
@@ -461,10 +461,13 @@ secretumvault/
 │   │   └── router.rs           # Request routing to engines
 │   ├── telemetry.rs            # Metrics, logging, audit
 │   └── lib.rs                  # Library exports
-├── Dockerfile                  # Multi-stage container build
-├── docker-compose.yml          # Complete dev environment
-├── docker/config/              # Docker configuration files
-├── k8s/                        # Kubernetes manifests
+├── deploy/                      # Deployment configurations
+│   ├── docker/                 # Docker deployment
+│   │   ├── Dockerfile          # Multi-stage container build
+│   │   ├── docker-compose.yml  # Complete dev environment
+│   │   └── config/             # Docker-specific config
+│   ├── helm/                   # Helm charts for Kubernetes
+│   └── k8s/                    # Raw Kubernetes manifests
 │   ├── 01-namespace.yaml
 │   ├── 02-configmap.yaml
 │   ├── 03-deployment.yaml

assets/README.md

@@ -0,0 +1,13 @@
+# SecretumVault Assets
+
+Brand assets, logos, icons, and visual identity.
+
+## Structure
+
+- **logos/** - SecretumVault logos in various formats and sizes
+- **icons/** - Application icons and favicon
+- **branding/** - Brand guidelines, showcase, and identity resources
+
+## Usage
+
+All assets are SVG format (vector) for scalability. See `branding/brand-guidelines.md` for usage guidelines.

assets/branding/brand-guidelines.md

@@ -254,7 +254,7 @@ font-family: 'Space Grotesk', sans-serif;
 
 ```html
 <header>
-    <img src="/imgs/secretumvault-logo-h.svg"
+    <img src="/assets/logos/secretumvault-logo-h.svg"
          alt="SecretumVault"
          width="240" height="72">
 </header>
@@ -263,14 +263,14 @@ font-family: 'Space Grotesk', sans-serif;
 ### Favicon
 
 ```html
-<link rel="icon" type="image/svg+xml" href="/imgs/secretumvault-icon.svg">
+<link rel="icon" type="image/svg+xml" href="/assets/icons/secretumvault-icon.svg">
 ```
 
 ### Documentation Header
 
 ```html
 <div style="background: #0A1929; padding: 2rem;">
-    <img src="/imgs/secretumvault-logo.svg"
+    <img src="/assets/logos/secretumvault-logo.svg"
          alt="SecretumVault"
          width="200" height="280">
 </div>
@@ -280,7 +280,7 @@ font-family: 'Space Grotesk', sans-serif;
 
 ```html
 <nav>
-    <img src="/imgs/secretumvault-icon.svg"
+    <img src="/assets/icons/secretumvault-icon.svg"
          alt="SecretumVault"
          width="32" height="32">
 </nav>
@@ -290,7 +290,7 @@ font-family: 'Space Grotesk', sans-serif;
 
 ```html
 <div style="background: #0A1929; text-align: center; padding: 4rem 2rem;">
-    <img src="/imgs/secretumvault-logo.svg"
+    <img src="/assets/logos/secretumvault-logo.svg"
          alt="SecretumVault Logo"
          width="280" height="280">
 </div>
@@ -300,7 +300,7 @@ font-family: 'Space Grotesk', sans-serif;
 
 ```html
 <section style="background: #FFFFFF; padding: 3rem;">
-    <img src="/imgs/secretumvault-logo-s.svg"
+    <img src="/assets/logos/secretumvault-logo-s.svg"
          alt="SecretumVault"
          width="200" height="280">
 </section>
@@ -411,7 +411,10 @@ All branding assets are located in the project:
 
 ```
 secretumvault/
-├── imgs/
+├── assets/
+│   ├── logos/
+│   ├── icons/
+│   └── branding/
 │   ├── secretumvault-logo.svg (animated vertical)
 │   ├── secretumvault-logo-s.svg (static vertical)
 │   ├── secretumvault-logo-h.svg (animated horizontal)
@@ -430,10 +433,10 @@ secretumvault/
 
 ## Interactive Asset Gallery
 
-An interactive gallery with dark/light mode toggle, copy-to-clipboard functionality, and detailed specifications is available in `imgs/index.html`. This gallery displays all logo variants, color palettes, typography samples, and scalability tests.
+An interactive gallery with dark/light mode toggle, copy-to-clipboard functionality, and detailed specifications is available in `assets/branding/index.html`. This gallery displays all logo variants, color palettes, typography samples, and scalability tests.
 
 To view the gallery:
-1. Open `imgs/index.html` in a web browser
+1. Open `assets/branding/index.html` in a web browser
 2. Toggle between dark and light modes
 3. Click color codes to copy to clipboard
 4. View logos at different sizes and devices
@@ -451,7 +454,7 @@ To view the gallery:
 ## Questions & Support
 
 For branding questions or asset requests, refer to:
-- Interactive Asset Gallery: `imgs/index.html`
+- Interactive Asset Gallery: `assets/branding/index.html`
 - Project Architecture: `docs/secretumvault-complete-architecture.md`
 - Asset Gallery: Open in browser for dark/light mode toggles and copy-to-clipboard functionality
 

docs/BRAND-GUIDELINES.md

@@ -1,462 +0,0 @@
-<div style="text-align: center; margin: 40px 0;">
-    <img src="../imgs/secretumvault-logo.svg" alt="SecretumVault Logo" width="280" height="280" style="max-width: 100%; height: auto;">
-</div>
-
-# SecretumVault Branding Guidelines
-
-## Overview
-
-SecretumVault is a post-quantum cryptographic secrets management system designed for modern cloud infrastructure. The brand identity reflects security, innovation, and technical sophistication through a cohesive visual system combining vault imagery with quantum-inspired elements. This guide covers logo systems, color palettes, typography, usage guidelines, and practical integration examples.
-
----
-
-## Logo System
-
-### Available Logo Variants
-
-SecretumVault provides multiple logo variants to accommodate different use cases and layouts:
-
-| Variant | File | ViewBox | Best For | Features |
-|---------|------|---------|----------|----------|
-| **Vertical Animated** | `secretumvault-logo.svg` | 200×280 px | Hero sections, interactive displays | Rotating orbits, pulsing core |
-| **Vertical Static** | `secretumvault-logo-s.svg` | 200×280 px | Print, documentation, static layouts | No animations, full color |
-| **Horizontal Animated** | `secretumvault-logo-h.svg` | 400×120 px | Navigation bars, headers | Rotating orbits, space-efficient |
-| **Horizontal Static** | `secretumvault-logo-h-s.svg` | 400×120 px | Print headers, static layouts | No animations, horizontal format |
-| **Animated Icon** | `secretumvault-icon.svg` | 200×200 px | App icons, favicons, UI elements | Full animations, square format |
-| **Static Icon** | `secretumvault-icon-s.svg` | 200×200 px | Favicon, print, badges | No animations, square format |
-| **B&W Logo** | `secretumvault-logo-bn.svg` | 200×200 px | Print (grayscale), restricted color | Single color, monochrome |
-| **B&W Icon** | `secretumvault-icon-bn.svg` | 200×200 px | Print, B&W documents | Single color, monochrome |
-
-### Logo Composition
-
-The vault icon consists of:
-
-- **Outer Ring (Dashed):** Cyan glow with rotating animation (20s cycle)
-- **Inner Circle:** Gradient fill (deep vault → primary → secondary)
-- **Central Node:** Quantum cyan core with pulsing effect (5.2px → 6.5px → 5.2px, 2s cycle)
-- **Orbital Electrons:** Four cyan dots rotating around the core (8s clockwise)
-- **Secondary Orbit:** Four purple dots at diagonal positions (12s counterclockwise)
-- **Vault Handle:** Gold-accented bar and circular ring overlay
-- **Text:** "SecretumVault" in Space Grotesk Bold, Quantum Cyan (#00D9FF)
-
-### Sizing & Clear Space
-
-**Minimum Sizes:**
-- **Logo (full):** 120px wide minimum
-- **Icon only:** 32px minimum
-- **Favicon:** 16px or 32px
-
-**Clear Space:**
-Maintain clear space around the logo equal to half the logo height on all sides. For a 120px logo, maintain 60px clear space on all sides.
-
----
-
-## Icon System
-
-### Icon Scalability
-
-Icons maintain clarity and recognizability across all sizes:
-
-| Size | Use Case |
-|------|----------|
-| 16px | Favicon, small UI elements |
-| 24px | Toolbar icons, small badges |
-| 32px | Standard app icons, navigation |
-| 48px | Medium app icons, avatar sizes |
-| 64px | Large app icons, decorative elements |
-| 128px | Application splash screens |
-| 256px | High-resolution favicons |
-| 512px | Marketing, high-DPI displays |
-
-### When to Use Each Variant
-
-**Full Logo (`secretumvault-logo.svg`, `secretumvault-logo-s.svg`)**
-- Hero sections and landing pages
-- Marketing materials and presentations
-- Documentation headers
-- Standalone brand applications
-
-**Horizontal Logo (`secretumvault-logo-h.svg`)**
-- Header/navbar branding
-- Horizontal banner designs
-- Social media headers
-- Documentation breadcrumbs
-- Minimum width: 240px
-
-**Icon Only (`secretumvault-icon.svg`, `secretumvault-icon-s.svg`)**
-- UI navigation and buttons
-- Favicons and application icons
-- Small badges and labels
-- Quick reference elements
-- Available at all standard icon sizes
-
----
-
-## Color Palette
-
-### Primary Colors
-
-| Name | Hex | RGB | Use |
-|------|-----|-----|-----|
-| Deep Vault | #0a1929 | rgb(10, 25, 41) | Background, dark areas |
-| Primary | #1a2744 | rgb(26, 39, 68) | Main logo fill, primary UI |
-| Secondary | #2a3f6a | rgb(42, 63, 106) | Secondary fills, gradients |
-| Quantum Cyan | #00d9ff | rgb(0, 217, 255) | Accents, highlights, text |
-
-### Accent Colors
-
-| Name | Hex | RGB | Use |
-|------|-----|-----|-----|
-| Gold Accent | #ffd700 | rgb(255, 215, 0) | Vault handle, emphasis |
-| Purple Accent | #8b5cf6 | rgb(139, 92, 246) | Secondary orbit, decorative |
-
-### Color Usage Guidelines
-
-- **Quantum Cyan (#00D9FF):** Primary interactive elements, links, highlights
-- **Gold (#ffd700):** Call-to-action buttons, important features
-- **Purple (#8b5cf6):** Secondary information, decorative elements
-- **Primary Blue (#1a2744):** Logo fill, main backgrounds
-- **Secondary Blue (#2a3f6a):** Gradients, borders, secondary backgrounds
-
-### Background Compatibility
-
-**Dark Backgrounds** ✅
-- Quantum Deep: #0A1929
-- Quantum Blue: #1A2744
-- Black: #000000
-
-Use: `secretumvault-logo.svg`, `secretumvault-logo-bn.svg`, or `secretumvault-icon.svg`
-
-**Light Backgrounds** ✅
-- White: #FFFFFF
-- Off-white: #F5F5F5
-- Light gray: #E8E8E8
-
-Use: `secretumvault-logo-s.svg` or `secretumvault-logo-bn.svg`
-
-**Avoid** ❌
-- Patterned backgrounds
-- Complex images
-- Colors with insufficient contrast
-
-### Accessibility
-
-- Maintain sufficient contrast for text (WCAG AA minimum 4.5:1 for regular text)
-- Avoid color-only differentiation; use patterns or text labels
-- Test color combinations with color-blind friendly tools
-
----
-
-## Typography
-
-### Primary Typeface: Space Grotesk
-
-- **Font Family:** Space Grotesk
-- **Category:** Sans Serif
-- **Weights:** 400 (Regular), 600 (Semi-Bold), 700 (Bold)
-- **Source:** Google Fonts
-- **License:** Open Source (Open Font License)
-
-#### Google Fonts Import
-
-```html
-<link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;600;700&display=swap" rel="stylesheet">
-```
-
-#### CSS Usage
-
-```css
-font-family: 'Space Grotesk', sans-serif;
-```
-
-### Typography Hierarchy
-
-| Element | Font | Weight | Size | Use |
-|---------|------|--------|------|-----|
-| Logo Text | Space Grotesk | 700 | 32-48px | Logo wordmark |
-| Heading 1 | Space Grotesk | 700 | 3rem | Page titles |
-| Heading 2 | Space Grotesk | 700 | 1.8rem | Section headers |
-| Heading 3 | Space Grotesk | 600 | 1.2rem | Subsection headers |
-| Body Text | System Sans | 400 | 1rem | Documentation, content |
-| Code | Monospace | 400 | 0.85-0.9rem | Code blocks |
-
-### Logo Text Color
-
-- **Light Mode:** #1A2744 (Deep Primary)
-- **Dark Mode:** #00D9FF (Quantum Cyan)
-
----
-
-## Animation Guidelines
-
-### When to Use Animated Logos
-
-- Hero sections with user attention
-- Loading indicators
-- Interactive UI elements
-- Marketing videos
-- Promotional materials
-
-### When to Use Static Logos
-
-- Navigation bars
-- Footers
-- Print materials
-- Emails
-- Documents
-- Favicons
-- Small UI elements
-
-### Animated Logo Specifications
-
-| Animation | Duration | Direction | Range/Loop |
-|-----------|----------|-----------|-----------|
-| Outer Ring Rotation | 20s | Clockwise | 0° → 360°, infinite |
-| Central Core Pulsing | 2s | - | 5.2px → 6.5px → 5.2px, infinite |
-| Orbital Electrons | 8s | Clockwise | 360° rotation, infinite |
-| Secondary Orbit | 12s | Counterclockwise | 360° rotation, infinite |
-
----
-
-## Usage Guidelines
-
-### DO ✓
-
-- Use complete logos with proper text and icon
-- Maintain clear space around logos (20px minimum)
-- Use appropriate variant for the medium (animated for web, static for print)
-- Scale logos proportionally
-- Use provided SVG files for vector graphics
-- Apply logos on contrasting backgrounds for visibility
-- Use recommended color combinations
-- Test logos across different screen sizes and devices
-- Use descriptive alt text: `alt="SecretumVault logo"` or `alt="Vault security icon"`
-
-### DON'T ✗
-
-- Distort or skew the logo (non-proportional scaling)
-- Change logo colors without explicit approval
-- Add effects (shadows, glows) beyond original design
-- Rotate logos at unusual angles
-- Use logo on cluttered backgrounds
-- Mix animated and static versions together
-- Rasterize SVGs without maintaining resolution
-- Remove or modify individual logo elements
-- Use logo without adequate clear space
-- Apply logos too small (below minimum size)
-- Use vague alt text: `alt="logo.svg"` or `alt="image"`
-
----
-
-## Integration Examples
-
-### Web Header
-
-```html
-<header>
-    <img src="/imgs/secretumvault-logo-h.svg"
-         alt="SecretumVault"
-         width="240" height="72">
-</header>
-```
-
-### Favicon
-
-```html
-<link rel="icon" type="image/svg+xml" href="/imgs/secretumvault-icon.svg">
-```
-
-### Documentation Header
-
-```html
-<div style="background: #0A1929; padding: 2rem;">
-    <img src="/imgs/secretumvault-logo.svg"
-         alt="SecretumVault"
-         width="200" height="280">
-</div>
-```
-
-### UI Navigation
-
-```html
-<nav>
-    <img src="/imgs/secretumvault-icon.svg"
-         alt="SecretumVault"
-         width="32" height="32">
-</nav>
-```
-
-### Hero Section (Animated)
-
-```html
-<div style="background: #0A1929; text-align: center; padding: 4rem 2rem;">
-    <img src="/imgs/secretumvault-logo.svg"
-         alt="SecretumVault Logo"
-         width="280" height="280">
-</div>
-```
-
-### Static Background with Logo
-
-```html
-<section style="background: #FFFFFF; padding: 3rem;">
-    <img src="/imgs/secretumvault-logo-s.svg"
-         alt="SecretumVault"
-         width="200" height="280">
-</section>
-```
-
----
-
-## File Formats
-
-### Primary Format: SVG
-
-All official logos are provided as Scalable Vector Graphics (SVG):
-
-**Advantages:**
-- Resolution-independent scaling
-- Animated elements support
-- Reduced file size
-- Full browser support
-
-**Usage:** Web, digital displays, high-quality print output
-
-### Export Guidelines for Other Formats
-
-If exporting to raster formats (PNG, JPG):
-
-- **PNG:** Recommended for web (supports transparency)
-  - Minimum 2x resolution for Retina displays
-  - Optimize with tools like TinyPNG or ImageOptim
-- **PDF:** For print distribution (maintains vector quality)
-- **JPG:** Not recommended (no transparency, quality loss)
-
-### Export Settings
-
-When exporting from SVG:
-
-- **Minimum DPI:** 300 for print
-- **Color Space:** sRGB for web, CMYK for commercial print
-- **Transparency:** Preserve alpha channel for PNG
-- **Optimization:** Remove metadata, optimize paths
-
----
-
-## Social Media Specifications
-
-| Platform | Format | Recommended Size | Logo Variant |
-|----------|--------|------------------|--------------|
-| Twitter | Square | 400×400px | Icon or Vertical |
-| LinkedIn | Square | 400×400px | Icon or Vertical |
-| GitHub | Square | 200×200px | Icon |
-| Facebook | Square | 1200×1200px | Icon or Vertical |
-| Email Signature | Horizontal | 400×120px | Horizontal Static |
-
----
-
-## Print Implementation
-
-- Use `secretumvault-logo-s.svg` (static version)
-- Export to PDF for best print quality
-- Ensure minimum size of 1 inch (25.4mm)
-- Verify color accuracy with print vendor
-- Use CMYK color profile for commercial printing
-- Maintain clear space in print layouts
-
-### Export for Print
-
-If exporting SVG to raster for print:
-- Minimum 300 DPI
-- Maintain aspect ratio
-- Use PNG with transparency or PDF
-- Recommended tools: Inkscape, Adobe Illustrator, or online converters
-
----
-
-## Design System Integration
-
-### Quantum Vault Visual Language
-
-The SecretumVault logo employs a quantum theme that reflects the post-quantum cryptography foundation:
-
-- **Vault Imagery:** Security and protection
-- **Circular Orbital Pattern:** Quantum mechanics and atomic structure
-- **Rotating Elements:** Continuous motion and dynamism
-- **Cyan Accent:** Innovation and cutting-edge technology
-- **Gold Accents:** Value and trust
-
-### Design Token Usage
-
-```css
-/* Color Tokens */
---sv-primary: #1a2744;
---sv-secondary: #2a3f6a;
---sv-cyan: #00d9ff;
---sv-gold: #ffd700;
---sv-purple: #8b5cf6;
-
-/* Typography Tokens */
---font-primary: 'Space Grotesk', sans-serif;
---font-weight-regular: 400;
---font-weight-semi-bold: 600;
---font-weight-bold: 700;
-```
-
----
-
-## Asset Locations
-
-All branding assets are located in the project:
-
-```
-secretumvault/
-├── imgs/
-│   ├── secretumvault-logo.svg (animated vertical)
-│   ├── secretumvault-logo-s.svg (static vertical)
-│   ├── secretumvault-logo-h.svg (animated horizontal)
-│   ├── secretumvault-logo-h-s.svg (static horizontal)
-│   ├── secretumvault-icon.svg (animated icon)
-│   ├── secretumvault-icon-s.svg (static icon)
-│   ├── secretumvault-logo-bn.svg (B&W logo)
-│   ├── secretumvault-icon-bn.svg (B&W icon)
-│   ├── index.html (interactive asset gallery)
-│   └── BRAND-GUIDELINES.md (this file)
-└── docs/
-    └── BRAND-GUIDELINES.md (comprehensive documentation)
-```
-
----
-
-## Interactive Asset Gallery
-
-An interactive gallery with dark/light mode toggle, copy-to-clipboard functionality, and detailed specifications is available in `imgs/index.html`. This gallery displays all logo variants, color palettes, typography samples, and scalability tests.
-
-To view the gallery:
-1. Open `imgs/index.html` in a web browser
-2. Toggle between dark and light modes
-3. Click color codes to copy to clipboard
-4. View logos at different sizes and devices
-
----
-
-## Version History
-
-| Version | Date | Changes |
-|---------|------|---------|
-| 1.0 | 2025-12-22 | Initial brand guidelines consolidating logo systems, color palettes, typography, usage guidelines, integration examples, and practical implementation guidance |
-
----
-
-## Questions & Support
-
-For branding questions or asset requests, refer to:
-- Interactive Asset Gallery: `imgs/index.html`
-- Project Architecture: `docs/secretumvault-complete-architecture.md`
-- Asset Gallery: Open in browser for dark/light mode toggles and copy-to-clipboard functionality
-
----
-
-**SecretumVault** — Post-quantum cryptographic secrets management for modern infrastructure
-
-Made with ❤️ • Built in Rust

docs/README.md

@@ -1,7 +1,7 @@
 # SecretumVault Documentation
 
 <div align="center">
-  <img src="../imgs/secretumvault-logo-h.svg" alt="SecretumVault Logo" width="600" />
+  <img src="../assets/logos/secretumvault-logo-h.svg" alt="SecretumVault Logo" width="600" />
 </div>
 
 Complete documentation for SecretumVault secrets management system.
@@ -9,19 +9,19 @@ Complete documentation for SecretumVault secrets management system.
 ## Documentation Index
 
 ### Getting Started
-- **[Architecture](ARCHITECTURE.md)** - System design, components, and data flow
-- **[How-To Guide](HOWOTO.md)** - Step-by-step instructions for common tasks
-- **[Configuration](CONFIGURATION.md)** - Complete configuration reference and options
-- **[Features Control](FEATURES_CONTROL.md)** - Build features and Justfile recipes
+- **[Architecture](architecture/overview.md)** - System design, components, and data flow
+- **[How-To Guide](user-guide/howto.md)** - Step-by-step instructions for common tasks
+- **[Configuration](user-guide/configuration.md)** - Complete configuration reference and options
+- **[Features Control](development/features-control.md)** - Build features and Justfile recipes
 
 ### Operations & Development
-- **[Deployment Guide](../DEPLOYMENT.md)** - Docker, Kubernetes, and Helm deployment
+- **[Deployment Guide](operations/deployment.md)** - Docker, Kubernetes, and Helm deployment
 - **[API Reference](API.md)** - HTTP API endpoints and request/response formats
 - **[Security Guidelines](SECURITY.md)** - Security best practices and hardening
 
 ### Build & Features
-- **[Build Features](BUILD_FEATURES.md)** - Cargo features, compilation options, dependencies
-- **[Post-Quantum Cryptography](PQC_SUPPORT.md)** - PQC algorithms, backend support, configuration
+- **[Build Features](development/build-features.md)** - Cargo features, compilation options, dependencies
+- **[Post-Quantum Cryptography](development/pqc-support.md)** - PQC algorithms, backend support, configuration
 - **[Development Guide](DEVELOPMENT.md)** - Building, testing, and contributing
 
 ---
@@ -31,31 +31,31 @@ Complete documentation for SecretumVault secrets management system.
 ### I want to...
 
 **Deploy SecretumVault**
-→ Start with [Deployment Guide](../DEPLOYMENT.md)
+→ Start with [Deployment Guide](operations/deployment.md)
 
 **Understand the architecture**
-→ Read [Architecture](ARCHITECTURE.md)
+→ Read [Architecture](architecture/overview.md)
 
 **Configure vault for my environment**
-→ See [Configuration](CONFIGURATION.md)
+→ See [Configuration](user-guide/configuration.md)
 
 **Use the REST API**
 → Check [API Reference](API.md)
 
 **Set up authentication and policies**
-→ Follow [How-To: Setup Authorization](HOWOTO.md#setup-authorization)
+→ Follow [How-To: Setup Authorization](user-guide/howto.md#setup-authorization)
 
 **Integrate with Kubernetes**
-→ See [How-To: Kubernetes Integration](HOWOTO.md#integrate-with-kubernetes)
+→ See [How-To: Kubernetes Integration](user-guide/howto.md#integrate-with-kubernetes)
 
 **Enable post-quantum cryptography**
-→ Read [PQC Support Guide](PQC_SUPPORT.md), [Configuration: Crypto Backends](CONFIGURATION.md#crypto-backends), or [Build Features: PQC](BUILD_FEATURES.md#post-quantum-cryptography)
+→ Read [PQC Support Guide](development/pqc-support.md), [Configuration: Crypto Backends](user-guide/configuration.md#crypto-backends), or [Build Features: PQC](development/build-features.md#post-quantum-cryptography)
 
 **Rotate secrets automatically**
-→ Check [How-To: Secret Rotation](HOWOTO.md#secret-rotation)
+→ Check [How-To: Secret Rotation](user-guide/howto.md#secret-rotation)
 
 **Set up monitoring**
-→ See [How-To: Monitoring](HOWOTO.md#monitor--troubleshoot)
+→ See [How-To: Monitoring](user-guide/howto.md#monitor--troubleshoot)
 
 **Contribute code**
 → Read [Development Guide](DEVELOPMENT.md)
@@ -67,17 +67,25 @@ Complete documentation for SecretumVault secrets management system.
 ```
 docs/
 ├── README.md                          # This file
-├── ARCHITECTURE.md                    # System architecture and design
-├── CONFIGURATION.md                   # Configuration reference
-├── HOWOTO.md                          # Step-by-step how-to guides
-├── API.md                             # REST API reference
-├── BUILD_FEATURES.md                  # Cargo features and build options
-├── PQC_SUPPORT.md                     # Post-quantum cryptography support
-├── DEVELOPMENT.md                     # Development and contribution guide
-├── SECURITY.md                        # Security guidelines and best practices
+├── index.md                           # mdBook introduction
+├── user-guide/
+│   ├── README.md
+│   ├── configuration.md               # Configuration reference
+│   └── howto.md                       # Step-by-step how-to guides
+├── architecture/
+│   ├── README.md
+│   ├── overview.md                    # System architecture and design
+│   └── complete-architecture.md       # Detailed architecture reference
+├── operations/
+│   ├── README.md
+│   └── deployment.md                  # Deployment guide
+└── development/
+    ├── README.md
+    ├── build-features.md             # Cargo features and build options
+    ├── features-control.md           # Feature control and Justfile recipes
+    └── pqc-support.md                # Post-quantum cryptography support
 └── ../
     ├── README.md                      # Main overview
-    ├── DEPLOYMENT.md                  # Deployment guide (Docker, K8s, Helm)
     └── Cargo.toml                     # Rust manifest with all dependencies
 ```
 
@@ -295,10 +303,10 @@ See [How-To: Troubleshooting](HOWOTO.md#monitor--troubleshoot) for detailed guid
 
 ## Next Steps
 
-1. **New to SecretumVault?** → Read [Architecture](ARCHITECTURE.md)
-2. **Want to deploy?** → Follow [Deployment Guide](../DEPLOYMENT.md)
-3. **Ready to use?** → Start with [How-To Guides](HOWOTO.md)
-4. **Need to configure?** → Check [Configuration Reference](CONFIGURATION.md)
+1. **New to SecretumVault?** → Read [Architecture](architecture/overview.md)
+2. **Want to deploy?** → Follow [Deployment Guide](operations/deployment.md)
+3. **Ready to use?** → Start with [How-To Guides](user-guide/howto.md)
+4. **Need to configure?** → Check [Configuration Reference](user-guide/configuration.md)
 5. **Building a feature?** → See [Development Guide](DEVELOPMENT.md)
 
 ---

docs/architecture/README.md

@@ -0,0 +1,14 @@
+# Architecture Documentation
+
+System design, components, and architectural decisions.
+
+## Contents
+
+- **[Architecture Overview](overview.md)** - High-level system design and components
+- **[Complete Architecture](complete-architecture.md)** - Detailed architecture reference document
+
+## Quick Links
+
+- [Back to Documentation Index](../README.md)
+- [User Guide](../user-guide/)
+- [Development Guide](../development/)

docs/architecture/complete-architecture.md

@@ -1136,7 +1136,8 @@ prometheus_port = 9090
 secretumvault/
 ├── Cargo.toml
 ├── README.md
-├── svault.toml.example
+├── config/
+│   └── svault.toml.example
 │
 ├── src/
 │   ├── lib.rs

docs/development/README.md

@@ -0,0 +1,15 @@
+# Development Documentation
+
+Documentation for developers building and extending SecretumVault.
+
+## Contents
+
+- **[Build Features](build-features.md)** - Cargo features, compilation options, dependencies
+- **[Features Control](features-control.md)** - Build features and Justfile recipes
+- **[Post-Quantum Cryptography](pqc-support.md)** - PQC algorithms, backend support, configuration
+
+## Quick Links
+
+- [Back to Documentation Index](../README.md)
+- [Architecture](../architecture/)
+- [User Guide](../user-guide/)

docs/index.md

@@ -0,0 +1,20 @@
+# SecretumVault Documentation
+
+Welcome to the SecretumVault documentation.
+
+SecretumVault is a post-quantum cryptographic secrets vault for modern infrastructure, combining:
+- Post-quantum cryptography (ML-KEM-768, ML-DSA-65) with classical crypto
+- Multiple secrets engines (KV, Transit, Dynamic, PKI)
+- Cedar policy-based authorization (attribute-based access control)
+- Flexible storage backends (SurrealDB, filesystem, etcd, PostgreSQL)
+
+## Documentation Sections
+
+- **[User Guide](user-guide/)** - Installation, configuration, and how-to guides
+- **[Architecture](architecture/)** - System design and architectural decisions
+- **[Operations](operations/)** - Deployment and operational procedures
+- **[Development](development/)** - Build features, development guide, and PQC support
+
+---
+
+For a complete index, see [README.md](README.md).

docs/operations/README.md

@@ -0,0 +1,13 @@
+# Operations Guide
+
+Documentation for operators deploying and maintaining SecretumVault in production.
+
+## Contents
+
+- **[Deployment](deployment.md)** - Docker, Kubernetes, Helm deployment guides
+
+## Quick Links
+
+- [Back to Documentation Index](../README.md)
+- [User Guide](../user-guide/)
+- [Architecture](../architecture/)

docs/operations/deployment.md

@@ -4,7 +4,7 @@ This guide covers deployment of SecretumVault using Docker, Docker Compose, Kube
 
 ## Table of Contents
 
-1. [Local Development with Docker Compose](#local-development-with-docker-compose)
+1. [Local Development with Docker Compose](#local-development-with-docker-compose -f deploy/docker/docker-compose.yml)
 2. [Kubernetes Deployment](#kubernetes-deployment)
 3. [Helm Installation](#helm-installation)
 4. [Configuration](#configuration)
@@ -25,21 +25,21 @@ This guide covers deployment of SecretumVault using Docker, Docker Compose, Kube
 
 ```bash
 # Build the vault image
-docker build -t secretumvault:latest .
+docker build -t secretumvault:latest -f deploy/docker/Dockerfile .
 
 # Start all services
-docker-compose up -d
+docker-compose -f deploy/docker/docker-compose.yml up -d
 
 # Verify services are running
-docker-compose ps
+docker-compose -f deploy/docker/docker-compose.yml ps
 
 # View logs
-docker-compose logs -f vault
+docker-compose -f deploy/docker/docker-compose.yml logs -f vault
 ```
 
 ### Services Included
 
-The docker-compose.yml includes:
+The docker-compose -f deploy/docker/docker-compose.yml.yml includes:
 
 - **vault**: SecretumVault server (port 8200 API, 9090 metrics)
 - **etcd**: Distributed key-value store for secrets (port 2379)
@@ -64,17 +64,17 @@ Configuration is mounted from `docker/config/svault.toml`. Modify this file to:
 curl http://localhost:8200/v1/sys/health
 
 # Check etcd health
-docker-compose exec etcd etcdctl --endpoints=http://localhost:2379 endpoint health
+docker-compose -f deploy/docker/docker-compose.yml exec etcd etcdctl --endpoints=http://localhost:2379 endpoint health
 ```
 
 ### Cleanup
 
 ```bash
 # Stop all services
-docker-compose down
+docker-compose -f deploy/docker/docker-compose.yml down
 
 # Remove volumes (WARNING: deletes all data)
-docker-compose down -v
+docker-compose -f deploy/docker/docker-compose.yml down -v
 ```
 
 ## Kubernetes Deployment
@@ -90,15 +90,15 @@ docker-compose down -v
 
 ```bash
 # Deploy to 'secretumvault' namespace
-kubectl apply -f k8s/01-namespace.yaml
-kubectl apply -f k8s/02-configmap.yaml
-kubectl apply -f k8s/03-deployment.yaml
-kubectl apply -f k8s/04-service.yaml
-kubectl apply -f k8s/05-etcd.yaml
+kubectl apply -f deploy/k8s/01-namespace.yaml
+kubectl apply -f deploy/k8s/02-configmap.yaml
+kubectl apply -f deploy/k8s/03-deployment.yaml
+kubectl apply -f deploy/k8s/04-service.yaml
+kubectl apply -f deploy/k8s/05-etcd.yaml
 
 # Optional: Additional storage backends
-kubectl apply -f k8s/06-surrealdb.yaml
-kubectl apply -f k8s/07-postgresql.yaml
+kubectl apply -f deploy/k8s/06-surrealdb.yaml
+kubectl apply -f deploy/k8s/07-postgresql.yaml
 
 # Verify deployment
 kubectl -n secretumvault get pods -w
@@ -177,12 +177,12 @@ kubectl delete -f k8s/
 # helm repo update
 
 # Install from local chart
-helm install vault helm/ \
+helm install vault deploy/helm/ \
   --namespace secretumvault \
   --create-namespace
 
 # Or with custom values
-helm install vault helm/ \
+helm install vault deploy/helm/ \
   --namespace secretumvault \
   --create-namespace \
   --values helm/custom-values.yaml
@@ -207,22 +207,22 @@ Customize deployment via values overrides:
 
 ```bash
 # Enable SurrealDB backend
-helm install vault helm/ -n secretumvault --create-namespace \
+helm install vault deploy/helm/ -n secretumvault --create-namespace \
   --set vault.config.storageBackend=surrealdb \
   --set surrealdb.enabled=true
 
 # Enable PostgreSQL for dynamic secrets
-helm install vault helm/ -n secretumvault --create-namespace \
+helm install vault deploy/helm/ -n secretumvault --create-namespace \
   --set postgresql.enabled=true \
   --set vault.config.engines.database=true
 
 # Enable monitoring
-helm install vault helm/ -n secretumvault --create-namespace \
+helm install vault deploy/helm/ -n secretumvault --create-namespace \
   --set monitoring.prometheus.enabled=true \
   --set monitoring.grafana.enabled=true
 
 # Change vault replicas
-helm install vault helm/ -n secretumvault --create-namespace \
+helm install vault deploy/helm/ -n secretumvault --create-namespace \
   --set vault.replicas=3
 ```
 

docs/user-guide/README.md

@@ -0,0 +1,14 @@
+# User Guide
+
+Documentation for end users configuring and using SecretumVault.
+
+## Contents
+
+- **[Configuration](configuration.md)** - Complete configuration reference and options
+- **[How-To Guides](howto.md)** - Step-by-step instructions for common tasks
+
+## Quick Links
+
+- [Back to Documentation Index](../README.md)
+- [Architecture Documentation](../architecture/)
+- [Operations Guide](../operations/)