[docs] Documentation Updates

.github/ISSUE_TEMPLATE/bug_report.md

@@ -3,7 +3,7 @@ name: Bug report
 about: Create a report to help us improve
 title: "[bug] Something went wrong"
 labels: bug
-assignees: KCarretto
+assignees: ''
 
 ---
 
@@ -12,6 +12,7 @@ A clear and concise description of what the bug is.
 
 **To Reproduce**
 Steps to reproduce the behavior:
+
 1. Go to '...'
 2. Click on '....'
 3. Scroll down to '....'
@@ -24,15 +25,17 @@ A clear and concise description of what you expected to happen.
 If applicable, add screenshots to help explain your problem.
 
 **Desktop (please complete the following information):**
- - OS: [e.g. iOS]
- - Browser [e.g. chrome, safari]
- - Version [e.g. 22]
+
+- OS: [e.g. iOS]
+- Browser [e.g. chrome, safari]
+- Version [e.g. 22]
 
 **Smartphone (please complete the following information):**
- - Device: [e.g. iPhone6]
- - OS: [e.g. iOS8.1]
- - Browser [e.g. stock browser, safari]
- - Version [e.g. 22]
+
+- Device: [e.g. iPhone6]
+- OS: [e.g. iOS8.1]
+- Browser [e.g. stock browser, safari]
+- Version [e.g. 22]
 
 **Additional context**
 Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -2,7 +2,7 @@
 name: Feature request
 about: Suggest an idea for this project
 title: "[feature] Something to do"
-labels: enhancement
+labels: feature
 assignees: ''
 
 ---

.github/ISSUE_TEMPLATE/feedback.md

@@ -0,0 +1,20 @@
+---
+name: Feedback
+about: Provide feedback for this project
+title: "[feedback] Something that went well / needs improvement"
+labels: feedback
+assignees: ''
+
+---
+
+**Is your feedback related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshot here.

README.md

@@ -11,15 +11,43 @@
 [![Rust Report Card](https://rust-reportcard.xuri.me/badge/github.com/spellshift/realm)](https://rust-reportcard.xuri.me/report/github.com/spellshift/realm)
 [![Docs](https://img.shields.io/badge/read%20our-docs-informational)](https://docs.realm.pub/)
 
-Realm is a cross platform Red Team engagement platform with a focus on automation and reliability.
+[Realm](https://github.com/spellshift/realm) is an Adversary Emulation Framework with a **focus on scalability, reliability, and automation**. It is highly performant and is designed for engagements of any size (up to many thousands of beacons). [Get started in minutes](https://docs.realm.pub/user-guide/getting-started).
 
-https://github.com/spellshift/realm/assets/16250309/7b5834d9-a864-490a-96e5-8d83b276af11
+<https://github.com/spellshift/realm/assets/16250309/7b5834d9-a864-490a-96e5-8d83b276af11>
 
-## Features
+## Feature Highlights
+
+- **Eldritch, a Pythonic DSL for Offensive Security:** Ditch clunky scripting and embrace [Eldritch](https://docs.realm.pub/user-guide/eldritch), Realm's Pythonic [Domain Specific Language (DSL)](https://en.wikipedia.org/wiki/Domain-specific_language) based on [Google Starlark](https://github.com/bazelbuild/starlark/blob/master/spec.md#starlark-language-specification). Write clear, concise, reuseable code that reflects your strategic thinking and streamlines offensive operations. [Eldritch](https://docs.realm.pub/user-guide/eldritch) is natively compiled to Rust, providing a performant abstraction for low-level system interactions.
+
+- **Effortless Multi-Host Management:** Juggling tasks across numerous machines during complex engagements? Realm simplifies the process, enabling you to control agents on multiple hosts simultaneously.
+
+- **Native GCP Integration:** Leverage the power and scalability of Google Cloud directly within your red team engagements. Realm seamlessly integrates with GCP services, boosting your attack capabilities without reinventing the wheel.
+
+- **Stateless Server Architecture:** While Realm officially supports GCP, you may deploy it's [stateless docker container](https://hub.docker.com/r/spellshift/tavern) to any environment that best fits your needs.
+
+- **Focus on Reliability:** Realm always prioritizes quality over quantity, enabling operators to focus on the engagement instead of spending hours troubleshooting bugs. Extensive testing and rigorous code review ensure unwavering reliability, while an intuitive design and clear documentation keep the learning curve minimal. After reaching a stable `1.0.0` release, Realm will follow [Semantic Versioning](https://semver.org/), ensuring the stability of older deployments.
+
+## Quick Start
+
+*To deploy a production ready instance see the [setup guide](https://docs.realm.pub/user-guide/tavern).*
+
+```bash
+# Clone Realm
+git clone https://github.com/spellshift/realm.git && cd realm
+
+# Start Tavern (Server)
+go run ./tavern
+
+# In a new terminal,
+# Start Imix (Agent)
+cd realm/implants/imix && cargo run
+```
+
+## Project Components
 
 ### Agent (imix)
 
-- Written in rust with support for MacOS, Linux, and Windows.
+- Written in Rust with support for MacOS, Linux, and Windows.
 - Supports long running tasks by reading output from tasks in real time.
 - Interval callback times.
 - Simple file based configuration.
@@ -41,29 +69,40 @@ https://github.com/spellshift/realm/assets/16250309/7b5834d9-a864-490a-96e5-8d83
 - Remote execution over SSH.
 - And much much more: <https://docs.realm.pub/user-guide/eldritch>
 
-## Quickstart guide
+## Want to contribute?
 
-*To deploy a production ready instance see the [tavern setup guide](https://docs.realm.pub/user-guide/tavern).*
+Check out our [developer docs!](https://docs.realm.pub/dev-guide/introduction)
 
-### Start the server
+## Contact Support
 
-```bash
-git clone https://github.com/spellshift/realm.git && cd realm
+Need a hand? We're here to help! If you're facing an issue with Realm, we're happy to assist! To ensure we can provide the best support, please [create an issue on our Github](https://github.com/spellshift/realm/issues/new?labels=bug&template=bug_report.md).
 
-go run ./tavern
+### Bug Support
 
-# If you'd like to test without deploying an agent use the test data.
-ENABLE_TEST_DATA=1 go run ./tavern
-```
+When opening your issue, please include:
 
-### Start the agent
+- A clear and concise description of the problem you're encountering.
+- Any relevant error messages or logs.
+- Steps to reproduce the issue (if possible).
+- Impacted Realm version and operating system.
 
-```bash
-git clone https://github.com/spellshift/realm.git
-cd realm/implants/imix && cargo run
+The more information you provide, the faster we can investigate and help you resolve the issue.
 
-```
+### Feature Requests & Feedback
+
+Realm lives and breathes through its users. Your insights and experiences are crucial in guiding its development and ensuring it continues to empower your mission. Please don't hesitate to reach out!
+
+**Remember:**
+
+- Be respectful and constructive in your feedback ([code of conduct](https://github.com/spellshift/realm/blob/main/CODE_OF_CONDUCT.md)).
+- Search for existing discussions or feature requests before creating new ones.
+- The more details you provide, the better we can understand your needs and respond effectively.
+- Together, we can shape Realm into an incredible framework. **Thank you for being part of the adventure!**
+
+#### Feature Requests
+
+Do you have an idea for a feature that would supercharge your workflow? We're all ears! [Open an issue on GitHub](https://github.com/spellshift/realm/issues/new?labels=feature&projects=&template=feature_request.md&title=%5Bfeature%5D+Something+to+do) and share your detailed proposal. Be sure to explain the problem you're facing, the solution you envision, and how it would benefit other users. The more information you provide, the better we can understand your needs and assess the feasibility of implementing your suggestion.
 
-## Want to contribute start here
+#### Provide Feedback
 
-<https://docs.realm.pub/dev-guide/introduction>
+Love something about Realm? Feel something could be improved? Let us know! Your feedback, good or bad, helps us make Realm better for everyone. [Open an issue on GitHub](https://github.com/spellshift/realm/issues/new?labels=feedback&projects=&template=feedback.md&title=%5Bfeedback%5D+Something+to+improve) outlining your thoughts, whether it's a praiseworthy feature, a usability concern, or a suggestion for improvement. Every bit of your feedback helps us refine Realm and make it an even more valuable tool in your red teaming toolbox.

docs/README.md

@@ -1,16 +1,23 @@
+# Updating Docs
+
+Note: All commands should be run from the docs folder (e.g. realm/docs)
+
 ## Testing Changes
-_All commands should be run from the docs folder (e.g. realm/docs)_
 
 Ensure you have installed the dependencies:
-```
+
+```sh
+gem install bundler -v '2.3.27'
 bundle install
 ```
 
 Run the documentation locally with:
-```
+
+```sh
 bundle exec jekyll serve --livereload
 ```
 
 ## Docsy Jekyll Template
+
 * [Source on Github](https://github.com/vsoch/docsy-jekyll)
 * [View on Github Pages](https://vsoch.github.io/docsy-jekyll/)

docs/_data/navigation.yml

@@ -1,6 +1,11 @@
 - title: About
   url: about
+
 - title: User Guide
-  url: user-guide
+  url: user-guide/getting-started
+
+- title: Admin Guide
+  url: admin-guide/tavern
+
 - title: Developer Guide
-  url: dev-guide
+  url: dev-guide/introduction

docs/_data/toc.yml

@@ -1,10 +1,8 @@
 - title: User Guide
-  url: user-guide
+  url: user-guide/getting-started
   links:
     - title: "Getting Started"
       url: "user-guide/getting-started"
-    - title: "Tavern"
-      url: "user-guide/tavern"
     - title: "UI"
       url: "user-guide/ui"
     - title: "Imix"
@@ -16,33 +14,40 @@
       children:
         - title: Standard Library
           url: "user-guide/eldritch#standard-library"
+    - title: "Terminology"
+      url: "user-guide/terminology"
+
+- title: Admin Guide
+  url: admin-guide/tavern
+  links:
+    - title: "Tavern"
+      url: "admin-guide/tavern"
+      children:
+        - title: "Configuration"
+          url: "admin-guide/tavern#configuration"
+        - title: "User Interface"
+          url: "admin-guide/tavern#user-interface"
+        - title: "GraphQL API"
+          url: "admin-guide/tavern#graphql-api"
 - title: Developer Guide
-  url: dev-guide
+  url: dev-guide/introduction
   links:
     - title: "Introduction"
       url: "dev-guide/introduction"
       children:
         - title: "Contribution Guidelines"
           url: "dev-guide/introduction#contribution-guidelines"
-        - title: "Terminology"
-          url: "dev-guide/introduction#terminology"
         - title: "Project Structure"
           url: "dev-guide/introduction#project-structure"
         - title: "Where to Start?"
           url: "dev-guide/introduction#where-to-start"
     - title: "Tavern"
       url: "dev-guide/tavern"
       children:
-        - title: "Configuration"
-          url: "dev-guide/tavern#configuration"
-        - title: "User Interface"
-          url: "dev-guide/tavern#user-interface"
         - title: "CDN API"
-          url: "dev-guide/tavern#cdn-api"
-        - title: "GraphQL API"
-          url: "dev-guide/tavern#graphql-api"
+          url: "admin-guide/tavern#cdn-api"
         - title: "Agent Development"
-          url: "dev-guide/tavern#agent-development"
+          url: "admin-guide/tavern#agent-development"
     - title: "Eldritch"
       url: "dev-guide/eldritch"
       children:
@@ -53,8 +58,8 @@
         - title: "OS Specific functions"
           url: "dev-guide/eldritch#os-specific-functions"
         - title: "Notes about using dictionary type Dict"
-          url: "dev-guide/eldritch#notes-about-using-dictionary-type-dict"
+          url: "dev-guide/eldritch#using-dict"
         - title: "Notes about asynchronous Eldritch code"
-          url: "dev-guide/eldritch#notes-about-asynchronous-eldritch-code"
+          url: "dev-guide/eldritch#using-async"
 - title: "About"
   url: "about"