Additional Doc Restructure

operations/foundations/documentation-styling.md

@@ -0,0 +1,177 @@
+## Purpose
+This document defines the **authoritative documentation style contract** used throughout the Bunny Lab homelab documentation.
+
+It is intended to be provided to:
+- AI assistants
+- Automation tools
+- Contributors
+
+The goal is to ensure all documentation is:
+- Technically precise
+- CLI-first
+- Easy to audit
+- Easy to reproduce
+
+---
+
+## General Writing Principles
+- Write for experienced operators, not beginners
+- Prefer **explicit commands** over descriptive prose
+- Avoid narrative filler
+- Assume the reader understands the underlying technologies
+
+---
+
+## Document Flow and Structure
+Documentation is written with the assumption that the reader:
+- Reads **top to bottom**
+- Executes actions within the **current section**
+- Does not require explicit step numbering
+
+Sections define **context and scope**.  
+Ordering is implicit and intentional.
+
+---
+
+## Core Sections (Recommended)
+Most documents should include, at minimum:
+- **Purpose** (why this doc exists)
+- **Assumptions** (platform, privileges, prerequisites)
+- **Procedure** (commands and configuration)
+
+Include these when applicable:
+- **Architectural Overview** (diagram or flow)
+- **Validation** (explicit checks with expected output)
+- **Troubleshooting** → **Symptoms** / **Resolution**
+
+---
+
+## Headings
+- `#` — Document title (one per document)
+- `##` — Major logical phases or topics
+- `###` — Subsections only when needed
+
+Headings replace the need for numbered steps.
+
+Avoid over-fragmentation.
+
+---
+
+## Admonitions
+Admonitions are **intentional and sparse**, not decorative.
+
+Use them to:
+- Highlight irreversible actions
+- Call out one-time decisions
+- Enforce safety boundaries
+
+Common forms:
+```markdown
+!!! warning "Important"
+!!! note
+!!! tip
+!!! success
+```
+
+Do **not** restate obvious information inside admonitions.
+
+---
+
+## Code Blocks (Critical)
+Code blocks are the **primary instructional vehicle**.
+
+### Rules
+- Always fenced
+- Always copy/paste-ready
+- Prefer fewer, larger blocks over many small ones
+- Use inline shell comments (`#`) to explain intent
+
+Example:
+```sh
+# Enable iSCSI service and persist across reboots
+service iscsitarget start
+sysrc iscsitarget_enable=YES
+```
+
+Avoid explanatory prose between every command.
+
+---
+
+## Shell Fencing
+- Use ```sh for shell commands
+- Use ``` for diagrams or pseudo-structure
+- Do not mix command output with commands unless explicitly labeled
+
+---
+
+## Inline Code
+Use backticks for:
+- Dataset names
+- Volume groups
+- Filenames
+- Command names
+- One-off parameters
+
+Example:
+`CLUSTER-STORAGE/iscsi-proxmox`
+
+---
+
+## Lists
+- Use bullet lists for inventories, criteria, and checks
+- Avoid numbered lists for procedures
+- Ordering is conveyed by section layout, not numbering
+
+---
+
+## Diagrams
+- ASCII diagrams only
+- Used to describe hierarchy or flow
+- Must reinforce understanding, not decorate
+
+---
+
+## Validation Sections
+Validation is **mandatory** for any procedure that affects:
+- Storage
+- Networking
+- Virtualization
+- Data integrity
+
+Validation lists should be explicit and testable.
+
+For lower-risk or informational documents, validation is optional.
+
+---
+
+## Tone and Voice
+- Neutral
+- Operational
+- Conservative
+- “Boring is correct”
+
+Avoid:
+- Marketing language
+- Storytelling
+- Over-explanation
+
+---
+
+## Anti-Patterns (Do Not Use)
+- Numbered procedural steps
+- GUI-only workflows when CLI exists
+- Excessive screenshots
+- One-command-per-codeblock sprawl
+- Implicit assumptions
+- Hidden prerequisites
+
+---
+
+## Summary
+Bunny Lab documentation prioritizes:
+- Determinism
+- Safety
+- Reproducibility
+- Auditability
+
+If a step cannot be reproduced from the documentation alone, it is incomplete.

operations/foundations/index.md

@@ -0,0 +1,40 @@
+# Foundations
+## Purpose
+Defines the baseline documentation standards, shared references, and structural conventions used everywhere else in this knowledgebase.
+
+## Includes
+- Documentation styling contract
+- Inventory and naming conventions
+- Shared templates and glossary references
+
+## New Document Template
+````markdown
+# <Document Title>
+## Purpose
+<one paragraph describing why this exists>
+
+!!! info "Assumptions"
+    - <OS / platform / privilege assumptions>
+    - <required tools or prerequisites>
+
+## Scope
+- <what is covered>
+- <what is explicitly out of scope>
+
+## Procedure
+```sh
+# Commands go here (grouped and annotated)
+```
+
+## Validation
+- <command + expected result>
+
+## Troubleshooting
+### Symptoms
+- <what you see>
+
+### Resolution
+```sh
+# Fix steps
+```
+````

operations/foundations/templates/document-template.md

@@ -0,0 +1,31 @@
+**Purpose**: PLACEHOLDER
+
+## Docker Configuration
+```yaml title="docker-compose.yml"
+PLACEHOLDER
+```
+
+```yaml title=".env"
+PLACEHOLDER
+```
+
+## Traefik Reverse Proxy Configuration
+If the container does not run on the same host as Traefik, you will need to manually add configuration to Traefik's dynamic config file, outlined below.
+```yaml
+http:
+  routers:
+    PLACEHOLDER:
+      entryPoints:
+        - websecure
+      tls:
+        certResolver: myresolver
+      service: PLACEHOLDER
+      rule: Host(`PLACEHOLDER.bunny-lab.io`)
+
+  services:
+    PLACEHOLDER:
+      loadBalancer:
+        servers:
+          - url: http://PLACEHOLDER:80
+        passHostHeader: true
+```