diff --git a/README.md b/README.md
index a28723e..07bf5dd 100644
--- a/README.md
+++ b/README.md
@@ -92,6 +92,12 @@ The `WritingBot` will read and write the files inside `code` folder based on spe
The MicroBots create a containerized environment and mount the specified directory with restricting the permissions to read-only or read/write based on Bot used. It ensures that the AI agents operate within defined boundaries which enhances security and control over code modifications as well as protecting the local environment.
+## π― Getting Started
+
+Ready to build your first Microbot project? Follow the step-by-step onboarding guide:
+
+β‘οΈ **[Get Started with Microbots](https://microsoft.github.io/microbots/getting-started/prerequisites/)**
+
#Legal Notice
Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoftβs Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-partyβs policies.
\ No newline at end of file
diff --git a/docs/guides/assets/azure-managed-identity-setup/mi-01-create-form.png b/docs/advanced/assets/azure-managed-identity-setup/mi-01-create-form.png
similarity index 100%
rename from docs/guides/assets/azure-managed-identity-setup/mi-01-create-form.png
rename to docs/advanced/assets/azure-managed-identity-setup/mi-01-create-form.png
diff --git a/docs/guides/assets/azure-managed-identity-setup/mi-02-overview.png b/docs/advanced/assets/azure-managed-identity-setup/mi-02-overview.png
similarity index 100%
rename from docs/guides/assets/azure-managed-identity-setup/mi-02-overview.png
rename to docs/advanced/assets/azure-managed-identity-setup/mi-02-overview.png
diff --git a/docs/guides/assets/azure-managed-identity-setup/sc-01-new-arm.png b/docs/advanced/assets/azure-managed-identity-setup/sc-01-new-arm.png
similarity index 100%
rename from docs/guides/assets/azure-managed-identity-setup/sc-01-new-arm.png
rename to docs/advanced/assets/azure-managed-identity-setup/sc-01-new-arm.png
diff --git a/docs/guides/assets/azure-managed-identity-setup/sc-02-managed-identity-form.png b/docs/advanced/assets/azure-managed-identity-setup/sc-02-managed-identity-form.png
similarity index 100%
rename from docs/guides/assets/azure-managed-identity-setup/sc-02-managed-identity-form.png
rename to docs/advanced/assets/azure-managed-identity-setup/sc-02-managed-identity-form.png
diff --git a/docs/authentication.md b/docs/advanced/authentication.md
similarity index 100%
rename from docs/authentication.md
rename to docs/advanced/authentication.md
diff --git a/docs/guides/azure-managed-identity-setup.md b/docs/advanced/azure-managed-identity-setup.md
similarity index 99%
rename from docs/guides/azure-managed-identity-setup.md
rename to docs/advanced/azure-managed-identity-setup.md
index 40e29c3..f56d85b 100644
--- a/docs/guides/azure-managed-identity-setup.md
+++ b/docs/advanced/azure-managed-identity-setup.md
@@ -259,5 +259,5 @@ One identity, one service connection, many Microbots pipelines.
## Next Steps
- **Conceptual background** β [Understanding RBAC & Authentication](../blog/rbac-authentication.md)
-- **All authentication options** β [Authentication Setup](../authentication.md)
+- **All authentication options** β [Authentication Setup](authentication.md)
- **Why secret-less matters** β [Microbots: Safety First Agentic Workflow](../blog/microbots-safety-first-ai-agent.md)
diff --git a/docs/copilot-bot.md b/docs/advanced/bots/copilot-bot.md
similarity index 100%
rename from docs/copilot-bot.md
rename to docs/advanced/bots/copilot-bot.md
diff --git a/docs/advanced/technical-writing-guidelines.md b/docs/advanced/technical-writing-guidelines.md
new file mode 100644
index 0000000..aeccf76
--- /dev/null
+++ b/docs/advanced/technical-writing-guidelines.md
@@ -0,0 +1,384 @@
+# Technical Writing Guidelines
+
+This guide defines the writing standards for all Microbots documentation β tutorials, guides, API references, and blog posts. Following these guidelines ensures that every article is consistent in quality, tone, and structure.
+
+*This guide is inspired by and adapted from [DigitalOcean's Technical Writing Guidelines](https://www.digitalocean.com/community/tutorials/digitalocean-s-technical-writing-guidelines), licensed under [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/).*
+
+There are four sections in this guide:
+
+- **Style**, our high-level approach to writing technical content
+- **Structure**, an explanation of our layout and content expectations
+- **Formatting**, a Markdown reference for MkDocs Material
+- **Terminology**, a guide to common terms and word usage
+
+Read the **Style** and **Structure** sections in their entirety before you begin writing. Use the **Formatting** and **Terminology** sections as references while drafting.
+
+---
+
+## Style
+
+Microbots documentation is written for developers and engineers who want to learn, build, and automate with confidence. Every article should be:
+
+- Comprehensive and written for all experience levels
+- Technically detailed and correct
+- Practical, useful, and self-contained
+- Friendly but formal
+
+### Comprehensive and Written for All Experience Levels
+
+Articles should be as clear and detailed as possible without making assumptions about the reader's background knowledge.
+
+Explicitly include every command a reader needs β from creating a virtual environment to the final working setup. Provide all explanations and background information the reader needs to understand the tutorial. The goal is for readers to **learn the concepts**, not just copy and paste code.
+
+**Avoid** words like "simple," "straightforward," "easy," "simply," "obviously," and "just." These words make assumptions about the reader's knowledge. A reader who hears something is "easy" may be frustrated when they encounter an issue. Instead, encourage readers by providing the explanations they need to be successful.
+
+### Technically Detailed and Correct
+
+Articles must be technically accurate and follow industry best practices. Do not provide large blocks of configuration or code and ask readers to paste it, trusting that it works and is safe. Provide all the details necessary for readers to understand and trust the article.
+
+- Every command should have a detailed explanation, including options and flags as necessary.
+- Every block of code should be followed by prose that describes what it does and why it works that way.
+- When you ask the reader to execute a command or modify a file, first explain what it does and why.
+
+**Authors must test their tutorials** by following them exactly as written on a fresh environment to ensure accuracy and identify missing steps.
+
+### Practical, Useful, and Self-contained
+
+Once a reader has finished an article, they should have installed, built, or set up something from start to finish. Emphasize a practical approach β at the end of an article, the reader should have a usable environment or example to build upon.
+
+- Link to existing Microbots documentation as prerequisites that readers should complete before beginning the tutorial.
+- Link to other Microbots articles for additional information within the body of the tutorial.
+- Only send readers to external sites when there is no existing Microbots article and the information cannot be summarized inline.
+
+### Friendly but Formal
+
+Articles aim for a friendly but formal tone. This means articles do not include jargon, memes, excessive slang, emoji, or jokes. We write for a global audience, so aim for a tone that works across language and cultural boundaries.
+
+- **Do not** use the first person singular (e.g., "I think β¦").
+- **Use** the second person (e.g., "You will configure β¦") to keep the focus on the reader and what they will accomplish.
+- In some cases, use the first person plural (e.g., "We will examine β¦").
+
+Use motivational language focused on outcomes. For example, instead of "You will learn how to install Microbots," write "In this tutorial, you will install Microbots and create your first bot." This approach motivates the reader and focuses on the goal.
+
+---
+
+## Structure
+
+Microbots articles have a consistent structure that includes an introduction, prerequisites, and a conclusion. The specific structure depends on the type of article.
+
+### Procedural Tutorials (Step-by-step)
+
+```
+# Title (H1)
+### Introduction (H3)
+## Prerequisites (H2)
+## Step 1 β Doing the First Thing (H2)
+## Step 2 β Doing the Next Thing (H2)
+β¦
+## Step n β Doing the Last Thing (H2)
+## Conclusion (H2)
+```
+
+### Conceptual Articles
+
+```
+# Title (H1)
+### Introduction (H3)
+## Prerequisites (optional) (H2)
+## Subtopic 1 (H2)
+## Subtopic 2 (H2)
+β¦
+## Subtopic n (H2)
+## Conclusion (H2)
+```
+
+### Title
+
+Think carefully about what the reader will accomplish by following your tutorial. Include the **goal** of the tutorial in the title, not just the tools involved. Keep titles under 60 characters when possible.
+
+**Good:** "Microbots : Introduction, Installation Guide and Creating Your First MicroBot"
+
+The title should communicate both the tool and the outcome.
+
+### Introduction
+
+The introduction is typically one to three paragraphs. Its purpose is to motivate the reader, set expectations, and summarize what they will do. Answer these questions:
+
+1. **What** is the tutorial about? What software is involved?
+2. **Why** should the reader learn this? What are the practical benefits?
+3. **What will the reader do** in this tutorial? Be specific.
+4. **What will the reader have accomplished** when finished? What new skills will they have?
+
+Keep the focus on the reader. Use "you will configure" rather than "we will learn how to."
+
+### Prerequisites
+
+The Prerequisites section spells out exactly what the reader should have or do before starting. Format it as a **checklist** the reader can follow:
+
+```markdown
+## Prerequisites
+
+To complete this tutorial, you will need:
+
+- **Python 3.10+** installed on your machine. See the [Pre-requisites](../getting-started/prerequisites.md) guide.
+- **Docker** installed and running. See the [Pre-requisites](../getting-started/prerequisites.md#docker) guide.
+- A working **Azure OpenAI** API key, endpoint, and deployed model. See the [Microbot Installation](../getting-started/installation-guide.md) guide.
+```
+
+Each prerequisite must link to an existing Microbots article or official documentation. Be specific β "Familiarity with Python" is not actionable; instead write "Familiarity with Python virtual environments. See [Python venv documentation](https://docs.python.org/3/library/venv.html)."
+
+### Steps
+
+Steps are the core of your tutorial. Each step:
+
+- Begins with a **level 2 heading** in the format: `## Step N β Gerund Phrase`
+- Starts with an introductory sentence describing what the reader will do and why
+- Contains commands, code listings, files, and explanations
+
+**Example:**
+
+```markdown
+## Step 1 β Setting Up the Project Directory
+
+In this step, you will create a project folder and initialize a Python virtual environment. This isolates your dependencies from the system Python installation.
+```
+
+### Transitions
+
+Each step should end with a brief closing sentence that:
+
+1. Summarizes what the reader accomplished
+2. Introduces what they will do next
+
+**Example:**
+
+> You have now installed the Microbots package and configured your LLM credentials. In the next step, you will create a sample project with a deliberate error for the bot to analyze.
+
+Vary the language so transitions do not feel repetitive.
+
+### Conclusion
+
+The conclusion summarizes what the reader accomplished. Use "you configured" or "you built" rather than "we learned how to."
+
+Include:
+
+- A brief recap of what was accomplished
+- Suggestions for what the reader can do next
+- Links to related Microbots tutorials or API references
+- Links to external resources where appropriate
+
+---
+
+## Formatting
+
+Microbots documentation is written in Markdown and rendered with MkDocs Material. Follow these formatting conventions.
+
+### Headers
+
+| Level | Usage |
+|-------|-------|
+| H1 (`#`) | Title only β one per article |
+| H2 (`##`) | Major sections: Introduction, Prerequisites, Steps, Conclusion |
+| H3 (`###`) | Subsections within a step or section |
+| H4 (`####`) | Use sparingly; prefer restructuring into multiple steps instead |
+
+For procedural tutorials, step headers should include step numbers followed by an em dash (β) and use the gerund (-ing form):
+
+```markdown
+## Step 1 β Installing Microbots
+```
+
+### Line-level Formatting
+
+**Bold** text should be used for:
+
+- Visible GUI text
+- Hostnames and usernames
+- Term lists
+- Emphasis when changing context (e.g., switching to a different terminal)
+
+*Italics* should only be used when introducing technical terms. For example: *The Microbots framework uses OverlayFS for copy-on-write filesystem protection.*
+
+`Inline code` formatting should be used for:
+
+- Command names, like `pip`
+- Package names, like `microbots`
+- File names and paths, like `~/.env`
+- Example URLs, like `https://your-resource-name.openai.azure.com`
+- Ports, like `:8000`
+- Key presses, in ALL CAPS, like `ENTER`. For simultaneous keys, use `CTRL+C`
+
+### Code Blocks
+
+Code blocks should be used for:
+
+- Commands the reader needs to execute
+- Files and scripts
+- Terminal output
+- Interactive dialogues
+
+Always include a **title** on code blocks using the `title` attribute:
+
+````markdown
+```bash title="Terminal"
+pip install microbots
+```
+````
+
+For file contents, use the filename as the title:
+
+````markdown
+```python title="log_analysis_bot.py" linenums="1"
+from microbots import LogAnalysisBot
+```
+````
+
+#### Explaining Commands
+
+Every command should be preceded by a description of what it does. After the command, provide additional details about arguments and flags:
+
+````markdown
+Execute the following command to create a Python virtual environment:
+
+```bash title="Terminal"
+python -m venv .venv
+```
+
+The `-m venv` flag tells Python to run the `venv` module, which creates an isolated virtual environment in the `.venv` directory.
+````
+
+#### Showing Output
+
+Separate command output from the command itself using a distinct code block with an explanatory sentence:
+
+````markdown
+Run the bot:
+
+```bash title="Terminal"
+python log_analysis_bot.py
+```
+
+The program's output will print to the screen:
+
+```text title="Output"
+Root cause identified from /var/log/build.log: ...
+```
+````
+
+#### Highlighting Changes
+
+When modifying an existing file, show the relevant section and explain what changed and why. Use comments or callouts to draw attention to the specific lines.
+
+### Admonitions
+
+Use MkDocs Material admonitions for notes, warnings, and tips:
+
+```markdown
+!!! note
+ For advanced authentication options, see the Authentication Guide.
+
+!!! warning
+ This action will delete all data in the container.
+
+!!! tip
+ You can use `logging.basicConfig(level=logging.INFO)` to see step-by-step bot output.
+```
+
+Use them sparingly. Reserve `warning` for actions that could cause data loss or security issues. Use `tip` for helpful but optional information.
+
+### Images
+
+When including images:
+
+- Use descriptive alt text for screen reader accessibility
+- Use the `.png` file format
+- Place images in the `docs/images/` directory under a subfolder named after the article
+- Keep image height as short as possible
+
+```markdown
+
+```
+
+### Navigation Cards
+
+Use navigation cards (rather than plain-text links) for Previous/Next links. Place the **Previous** card at the top of the article and the **Next** card at the bottom:
+
+```html
+
+
+
+
+
+```
+
+For articles that have prerequisites the reader should complete first, add prerequisite cards at the top alongside the Previous card:
+
+```html
+
+```
+
+---
+
+## Terminology
+
+### Users and Variables
+
+- Use `your-resource-name` as the default placeholder for Azure resource names.
+- Use `your-api-key-here` as the default placeholder for API keys.
+- Always highlight variables that readers need to change.
+
+### Bot Names
+
+Use the official class name with proper capitalization:
+
+| Correct | Incorrect |
+|---------|-----------|
+| `LogAnalysisBot` | Log Analysis Bot, loganalysisbot |
+| `ReadingBot` | Reading Bot, readingbot |
+| `WritingBot` | Writing Bot, writingbot |
+| `BrowsingBot` | Browsing Bot, browsingbot |
+| `AgentBoss` | Agent Boss, agentboss |
+| `CopilotBot` | Copilot Bot, copilotbot |
+
+### LLM Providers
+
+Use the provider/model format when referencing models:
+
+- `azure-openai/gpt-5-swe-agent`
+- `anthropic/claude-sonnet-4-20250514`
+- `ollama/llama3`
+
+### Permission Labels
+
+Use ALL CAPS for permission labels: `READ_ONLY`, `READ_WRITE`.
+
+### Software and Tools
+
+- Use the official capitalization from the project's website: **Docker**, **Python**, **MkDocs**, **TypeScript**.
+- Link to the software's home page the first time it is mentioned.
+
+### Technical Best Practices
+
+- Always test tutorials on a fresh environment before submitting.
+- Use the `--8<--` snippet syntax for including example files rather than duplicating code.
+- Keep code examples minimal and focused on the concept being taught.
+- Ensure all external links are valid at the time of writing and add the External Links Disclaimer admonition when external links are present.
diff --git a/docs/blog/guides/tesseract_ocr_tool_use.md b/docs/advanced/tools/tesseract_ocr_tool_use.md
similarity index 100%
rename from docs/blog/guides/tesseract_ocr_tool_use.md
rename to docs/advanced/tools/tesseract_ocr_tool_use.md
diff --git a/docs/blog/microbots-customizability.md b/docs/blog/microbots-customizability.md
index 55da047..a551074 100644
--- a/docs/blog/microbots-customizability.md
+++ b/docs/blog/microbots-customizability.md
@@ -59,7 +59,7 @@ uninstall_commands:
No Python code. No changes to MicroBot. Tools can be `internal` (runs inside the Docker sandbox) or `external` (runs on the host β useful for sub-agents or host-side logic).
> **Want to build one end-to-end?**
-> Walk through [Custom Tool Integration: Tesseract OCR](../blog/guides/tesseract_ocr_tool_use.md) β it builds a production-ready OCR tool from scratch and uses it to extract form fields from scanned documents.
+> Walk through [Custom Tool Integration: Tesseract OCR](../advanced/tools/tesseract_ocr_tool_use.md) β it builds a production-ready OCR tool from scratch and uses it to extract form fields from scanned documents.
---
diff --git a/docs/blog/rbac-authentication.md b/docs/blog/rbac-authentication.md
index 8c0dadb..ecaa20c 100644
--- a/docs/blog/rbac-authentication.md
+++ b/docs/blog/rbac-authentication.md
@@ -2,7 +2,7 @@
Microbots supports both API Key and Azure AD authentication for LLM providers. This guide breaks down how each method works, what Azure RBAC is, and which one to use for your setup.
-For setup instructions, see the [Authentication setup guide](../authentication.md).
+For setup instructions, see the [Authentication setup guide](../advanced/authentication.md).
---
@@ -166,6 +166,6 @@ az role assignment create \
## Next Steps
-- **Set up API Key auth** β [Authentication Guide: API Key](../authentication.md#1-api-key-authentication-default)
-- **Set up Azure AD auth** β [Authentication Guide: Azure AD](../authentication.md#2-azure-ad-token-authentication)
+- **Set up API Key auth** β [Authentication Guide: API Key](../advanced/authentication.md#1-api-key-authentication-default)
+- **Set up Azure AD auth** β [Authentication Guide: Azure AD](../advanced/authentication.md#2-azure-ad-token-authentication)
- **Understand the safety model** β [Safety-First Agentic Workflow](../blog/microbots-safety-first-ai-agent.md)
diff --git a/docs/examples/microbots_introduction/code/app.c b/docs/examples/microbots_introduction/code/app.c
new file mode 100644
index 0000000..faa0945
--- /dev/null
+++ b/docs/examples/microbots_introduction/code/app.c
@@ -0,0 +1,12 @@
+// app.c β A simple greeting program with a syntax error
+#include
+
+int add(int a, int b) {
+ return a + b
+}
+
+int main(void) {
+ printf("Hello, Microbots!\n");
+ printf("2 + 3 = %d\n", add(2, 3));
+ return 0;
+}
diff --git a/docs/examples/microbots_introduction/log_analysis_bot.py b/docs/examples/microbots_introduction/log_analysis_bot.py
new file mode 100644
index 0000000..d8841fb
--- /dev/null
+++ b/docs/examples/microbots_introduction/log_analysis_bot.py
@@ -0,0 +1,16 @@
+import logging
+
+logging.basicConfig(level=logging.INFO)
+
+from microbots import LogAnalysisBot
+
+my_bot = LogAnalysisBot(
+ model="azure-openai/gpt-5-swe-agent",
+ folder_to_mount="code",
+)
+
+result = my_bot.run(
+ file_name="code/build.log",
+ timeout_in_seconds=600,
+)
+print(result.result)
diff --git a/docs/getting-started/conclusion.md b/docs/getting-started/conclusion.md
new file mode 100644
index 0000000..4161205
--- /dev/null
+++ b/docs/getting-started/conclusion.md
@@ -0,0 +1,27 @@
+# Conclusion
+
+You built a complete Microbots project β a sample C application with a deliberate error and a `LogAnalysisBot` run that produced a root-cause analysis without ever modifying your host filesystem.
+
+## What Just Happened
+
+`python3 log_analysis_bot.py` triggered the framework to:
+
+1. **Create a Docker container** with `code/` mounted read-only via OverlayFS.
+2. **Send the task** to the LLM with a `LogAnalysisBot` system prompt.
+3. **Execute shell commands** inside the container (`ls`, `cat`, `nl`, β¦) as directed by the LLM.
+4. **Return a `BotRunResult`** containing the root-cause analysis.
+
+The host filesystem was never writable from the bot.
+
+## Available Bots
+
+| Bot | Permission | Description |
+|-----|-----------|-------------|
+| `ReadingBot` | Read-only | Reads files and extracts information. |
+| `WritingBot` | Read-write | Reads and writes files to fix issues or generate code. |
+| `BrowsingBot` | β | Browses the web to gather information. |
+| `LogAnalysisBot` | Read-only | Analyzes logs for root-cause debugging. |
+| `AgentBoss` | β | Orchestrates multiple bots for complex tasks. |
+
+Explore the [API Reference](../api-reference/microbots/MicroBot.md) for each bot, or read the [Microbots : Safety First Agentic Workflow](../blog/microbots-safety-first-ai-agent.md) blog for the safety architecture.
+
diff --git a/docs/getting-started/create-your-first-microbot-project/index.md b/docs/getting-started/create-your-first-microbot-project/index.md
new file mode 100644
index 0000000..7359fe4
--- /dev/null
+++ b/docs/getting-started/create-your-first-microbot-project/index.md
@@ -0,0 +1,85 @@
+# Create Your First Microbot Project
+
+Create a sample C project with a deliberate compile error.
+Generate a build log. Run a `LogAnalysisBot` against it.
+
+**Requires:** `gcc` (preinstalled on most Linux distributions, or `sudo apt install build-essential`).
+
+## Step 1 β Create the Sample Project
+
+From the root of your `microbots-introduction` project, create a `code/` folder:
+
+```bash title="Terminal"
+mkdir code
+```
+
+Add a C file with a deliberate syntax error:
+
+```c title="code/app.c" linenums="1"
+--8<-- "docs/examples/microbots_introduction/code/app.c"
+```
+
+Line 5 is missing the trailing `;` after `return a + b`, so `gcc` will fail.
+
+## Step 2 β Generate the Build Log
+
+```bash title="Terminal"
+cd code
+gcc app.c > build.log 2>&1
+cd ..
+```
+
+`code/build.log` should contain:
+
+```log title="code/build.log"
+app.c: In function βaddβ:
+app.c:5:17: error: expected β;β before β}β token
+ 5 | return a + b
+ | ^
+ | ;
+ 6 | }
+ | ~
+```
+
+Project layout:
+
+```text title="Project layout"
+microbots-introduction/
+βββ .venv
+βββ .env
+βββ code/
+ βββ app.c
+ βββ build.log
+```
+
+## Step 3 β Write the Bot Script
+
+Create `log_analysis_bot.py` at the project root:
+
+```python title="log_analysis_bot.py" linenums="1"
+--8<-- "docs/examples/microbots_introduction/log_analysis_bot.py"
+```
+
+The script mounts `code/` **read-only** inside Docker,
+Runs `LogAnalysisBot` against `code/build.log` with a 10-minute timeout.
+Prints the root-cause analysis from `result.result`
+
+## Step 4 β Run the Bot
+
+From the project root, with your virtual environment activated:
+
+```bash title="Terminal"
+python3 log_analysis_bot.py
+```
+
+`print(result.result)` outputs the root-cause analysis:
+
+```text title="Output"
+Root cause identified: The build failed due to a syntax error in
+//workdir/code/app.c at line 5. The function add(int a, int b) has
+a missing semicolon after the return statement (`return a + b`).
+This matches the compiler error in /var/log/build.log: "error:
+expected ';' before '}' token". Fix by adding a semicolon: `return a + b;`.
+```
+
+Continue with [Conclusion](../conclusion.md).
diff --git a/docs/getting-started/installation-guide.md b/docs/getting-started/installation-guide.md
new file mode 100644
index 0000000..1eb832b
--- /dev/null
+++ b/docs/getting-started/installation-guide.md
@@ -0,0 +1,39 @@
+# Microbot Installation
+
+Install the `microbots` package and configure an LLM provider.
+
+## Step 1 β Setting Up the Project Directory
+
+Create a project folder, activate a virtual environment, and install the `microbots` package:
+
+```bash title="Terminal"
+mkdir microbots-introduction
+cd microbots-introduction
+python3 -m venv .venv
+source .venv/bin/activate
+pip install microbots
+```
+
+When the venv is active, your shell prompt is prefixed with `(.venv)` as below:
+
+```bash title="Terminal"
+(.venv) user@host:~/microbots-introduction$
+```
+
+## Step 2 β Configuring the LLM Provider
+
+Microbots supports **Azure OpenAI**, **OpenAI**, **Anthropic**, and **Ollama**. This guide uses Azure OpenAI.
+
+Create a `.env` file in the project root:
+
+```env title=".env"
+AZURE_OPENAI_ENDPOINT="https://your-resource-name.openai.azure.com"
+AZURE_OPENAI_API_KEY="your-api-key-here"
+AZURE_OPENAI_API_VERSION="2023-03-15-preview"
+```
+
+Replace `your-resource-name` and `your-api-key-here` with values from the Azure portal.
+
+Continue with the [Sample Project Creation and First Run](create-your-first-microbot-project/index.md) guide.
+
+
diff --git a/docs/getting-started/prerequisites.md b/docs/getting-started/prerequisites.md
new file mode 100644
index 0000000..756e868
--- /dev/null
+++ b/docs/getting-started/prerequisites.md
@@ -0,0 +1,57 @@
+# Pre-requisites
+
+Install
+1. **Python** (the runtime)
+2. **Docker** (the sandboxed execution environment) before running any bot.
+
+## Step 1 β Installing Python
+
+Microbots requires **Python 3.10 or later, but below 3.13**
+
+Ubuntu / Debian:
+
+```bash title="Terminal"
+sudo apt update && sudo apt install python3 python3-pip python3-venv
+```
+
+Fedora:
+
+```bash title="Terminal"
+sudo dnf install python3 python3-pip
+```
+
+Verify the installation:
+
+```bash title="Terminal"
+python3 --version
+pip3 --version
+```
+
+Confirm the version is **at least 3.10 and below 3.13**.
+
+## Step 2 β Installing Docker
+
+On macOS, install [Docker Desktop](https://www.docker.com/products/docker-desktop/) and launch it.
+
+On Linux, follow the [Docker Engine installation guide](https://docs.docker.com/engine/install/), then enable the daemon and add your user to the `docker` group:
+
+```bash title="Terminal"
+sudo systemctl enable --now docker
+sudo usermod -aG docker $USER
+newgrp docker
+```
+
+Without this, bots fail with `PermissionError: [Errno 13] Permission denied` on `/var/run/docker.sock`.
+
+Verify the installation:
+
+```bash title="Terminal"
+docker --version
+docker ps # should succeed without sudo
+docker run hello-world
+```
+
+A "Hello from Docker!" message confirms the daemon is reachable.
+
+Continue with the [Microbot Installation](installation-guide.md) guide.
+
diff --git a/docs/index.md b/docs/index.md
index 7fa858b..0be135c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,3 +1,8 @@
+---
+hide:
+ - navigation
+---
+
# π€ Microbots
MicroBots is a lightweight, extensible AI agent for code comprehension and controlled file edits. It integrates cleanly into automation pipelines, mounting a target directory with explicit read-only or read/write modes so LLMs can safely inspect, refactor, or generate files with least-privilege access.
@@ -63,3 +68,12 @@ AZURE_OPENAI_API_VERSION=2025-03-01-preview
- [GitHub Repository](https://github.com/microsoft/minions)
- [Contributing Guide](https://github.com/microsoft/minions/blob/main/CONTRIBUTING.md)
- [Code of Conduct](https://github.com/microsoft/minions/blob/main/CODE_OF_CONDUCT.md)
+
+---
+
+## π― Getting Started
+
+Ready to build your first Microbot project? Follow the step-by-step onboarding guide:
+
+β‘οΈ **[Get Started with Microbots](getting-started/prerequisites.md)**
+
diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
index cd9e94d..a10efd2 100644
--- a/docs/stylesheets/extra.css
+++ b/docs/stylesheets/extra.css
@@ -169,3 +169,59 @@
.doc.doc-heading code {
cursor: pointer;
}
+
+/* Navigation cards for Previous / Next / Prerequisite links */
+.nav-cards {
+ display: flex;
+ gap: 1rem;
+ flex-wrap: wrap;
+ margin: 1.5rem 0;
+}
+
+.nav-card {
+ flex: 1;
+ min-width: 200px;
+ border: 1px solid var(--md-default-fg-color--lightest);
+ border-radius: 8px;
+ padding: 1rem 1.2rem;
+ background: var(--md-code-bg-color);
+ transition: transform 0.2s, box-shadow 0.2s, border-color 0.2s;
+ text-decoration: none;
+ color: inherit;
+ display: block;
+}
+
+.nav-card:hover {
+ transform: translateY(-2px);
+ box-shadow: 0 4px 16px rgba(0, 0, 0, 0.15);
+ border-color: var(--md-accent-fg-color, #526cfe);
+ text-decoration: none;
+ color: inherit;
+}
+
+.nav-card-label {
+ font-size: 0.75rem;
+ font-weight: 600;
+ text-transform: uppercase;
+ letter-spacing: 0.05em;
+ color: var(--md-default-fg-color--light);
+ margin-bottom: 0.3rem;
+}
+
+.nav-card-title {
+ font-size: 1rem;
+ font-weight: 700;
+ color: var(--md-accent-fg-color, #526cfe);
+}
+
+.nav-card--prev {
+ text-align: left;
+}
+
+.nav-card--next {
+ text-align: right;
+}
+
+.nav-card--prereq {
+ border-left: 3px solid var(--md-accent-fg-color, #526cfe);
+}
diff --git a/mkdocs.yml b/mkdocs.yml
index 4028ca9..767870b 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -52,24 +52,34 @@ markdown_extensions:
- pymdownx.highlight:
anchor_linenums: true
- pymdownx.superfences
- - pymdownx.snippets
+ - pymdownx.snippets:
+ base_path: ['.', 'docs']
+ check_paths: true
- pymdownx.tabbed:
alternate_style: true
- admonition
+ - pymdownx.details
- tables
- attr_list
+ - md_in_html
nav:
+ - Introduction: index.md
- Getting Started:
- - Home: index.md
- - Guides:
- - CopilotBot: copilot-bot.md
- - "Authentication Setup": authentication.md
- - "Azure Managed Identity & Service Connection Setup": guides/azure-managed-identity-setup.md
+ - "Pre-requisites": getting-started/prerequisites.md
+ - "Microbot Installation": getting-started/installation-guide.md
+ - "Create Your First Microbot Project": getting-started/create-your-first-microbot-project/index.md
+ - "Conclusion": getting-started/conclusion.md
+ - Advanced:
+ - Bots:
+ - CopilotBot: advanced/bots/copilot-bot.md
+ - "Authentication Setup": advanced/authentication.md
+ - "Azure Managed Identity & Service Connection Setup": advanced/azure-managed-identity-setup.md
- Tools:
- - "Custom Tool Integration Walkthrough": blog/guides/tesseract_ocr_tool_use.md
- - Blogs:
- - blog/index.md
+ - "Custom Tool Integration Walkthrough": advanced/tools/tesseract_ocr_tool_use.md
+ - "Technical Writing Guidelines": advanced/technical-writing-guidelines.md
+ - Blog:
+ - "Blog Posts": blog/index.md
- "Microbots : Safety First Agentic Workflow": blog/microbots-safety-first-ai-agent.md
- "Microbots : Customizability at Every Layer": blog/microbots-customizability.md
- "Understanding RBAC & Authentication": blog/rbac-authentication.md