diff --git a/docs/examples/microbots_introduction/code/app.ts b/docs/examples/microbots_introduction/code/app.ts
new file mode 100644
index 0000000..c08f7f6
--- /dev/null
+++ b/docs/examples/microbots_introduction/code/app.ts
@@ -0,0 +1,13 @@
+// app.ts — A simple greeting function with a syntax error
+function greet(name: string) {
+ const message: string = `Hello, ${name}!`
+ console.log(message)
+}
+
+// Missing closing parenthesis on the type annotation
+function add(a: number, b: number: number {
+ return a + b;
+}
+
+greet("Microbots");
+console.log(add(2, 3));
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/index.md b/docs/getting-started/home.md
similarity index 96%
rename from docs/index.md
rename to docs/getting-started/home.md
index 97ca984..74a33af 100644
--- a/docs/index.md
+++ b/docs/getting-started/home.md
@@ -44,7 +44,7 @@ print(data.results)
## ⚙️ How it works
-
+
MicroBots creates a containerized environment and mounts the specified directory, restricting permissions to read-only or read/write based on the Bot used. This ensures AI agents operate within defined boundaries, enhancing security and control over code modifications while protecting the local environment.
diff --git a/docs/authentication.md b/docs/guides/advanced/authentication.md
similarity index 100%
rename from docs/authentication.md
rename to docs/guides/advanced/authentication.md
diff --git a/docs/copilot-bot.md b/docs/guides/bots/copilot-bot.md
similarity index 100%
rename from docs/copilot-bot.md
rename to docs/guides/bots/copilot-bot.md
diff --git a/docs/guides/create-your-first-microbot-project/conclusion.md b/docs/guides/create-your-first-microbot-project/conclusion.md
new file mode 100644
index 0000000..8c692b6
--- /dev/null
+++ b/docs/guides/create-your-first-microbot-project/conclusion.md
@@ -0,0 +1,32 @@
+# Conclusion
+
+### Introduction
+
+You have now built a complete Microbots project: a sample TypeScript application with a deliberate error, a `LogAnalysisBot` script that points at the build log, and a successful run that produced a root-cause analysis. This article recaps what happened under the hood during that run and surveys the other bots the framework provides, so you can decide which one to reach for next.
+
+## What Just Happened
+
+When you executed `python3 log_analysis_bot.py`, the framework performed the following steps on your behalf:
+
+1. **Created a Docker container** with the `code` folder mounted using the appropriate permissions (read-only, in this case).
+2. **Sent your task** to the LLM along with a system prompt tailored to the `LogAnalysisBot` role.
+3. **Executed commands** inside the container as directed by the LLM (for example, `ls`, `cat`, `nl`, and `sed`).
+4. **Returned the result** as a `BotRunResult` containing the bot's analysis and root-cause report.
+
+Your host filesystem was protected the entire time. The `LogAnalysisBot` physically could not write to your files — every command ran inside Docker's isolation boundary, on top of an OverlayFS read-only mount.
+
+## Available Bots
+
+Beyond the `LogAnalysisBot` used in this guide, Microbots provides several other bots tailored for different use cases — each with its own permission level to ensure least-privilege access:
+
+| Bot | Permission | Description |
+|-----|-----------|-------------|
+| `ReadingBot` | Read-only | Reads files and extracts information based on instructions. |
+| `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 instant root-cause debugging. |
+| `AgentBoss` | — | Orchestrates multiple bots for complex multi-step tasks. |
+
+## Conclusion
+
+In this guide series, you installed Microbots, configured an Azure OpenAI provider, built a sample TypeScript project with a deliberate error, ran the `LogAnalysisBot` against the resulting build log, and reviewed how the framework isolates every command in Docker. To extend what you have built, explore the [API Reference](../../api-reference/microbots/MicroBot.md) for each bot listed above, or read the [Microbots : Safety First Agentic Workflow](../../blog/microbots-safety-first-ai-agent.md) blog for a deeper look at the safety architecture.
diff --git a/docs/guides/create-your-first-microbot-project/log-analysis-bot.md b/docs/guides/create-your-first-microbot-project/log-analysis-bot.md
new file mode 100644
index 0000000..7aa8dca
--- /dev/null
+++ b/docs/guides/create-your-first-microbot-project/log-analysis-bot.md
@@ -0,0 +1,73 @@
+# LogAnalysisBot
+
+### Introduction
+
+The `LogAnalysisBot` is a read-only bot that mounts a target folder, inspects log files, and identifies the root cause of failures. Because the mount is read-only, the bot can correlate compiler errors with source code without ever modifying the project on disk.
+
+In this guide, you will create the Python script that configures and runs a `LogAnalysisBot` against the `build.log` you generated earlier. By the end, the script will be ready to execute, and you will understand each constructor argument and `run()` parameter the bot exposes.
+
+## Prerequisites
+
+To complete this guide, you will need:
+
+- A Microbots project with the package installed and an `.env` file configured. See the [Microbot Installation](../getting-started/installation-guide.md) guide.
+- A `code/` folder containing `app.ts` and `build.log`. See the [Sample Project Creation and First Run](sample-project-and-first-run.md) guide.
+
+## Step 1 — Creating the Bot Script
+
+In this step, you will add a Python script at the root of the project that imports the `LogAnalysisBot` class, instantiates it, and points it at the build log.
+
+Create a file named `log_analysis_bot.py` in the root of your `microbots-introduction` project with the following content:
+
+```python title="log_analysis_bot.py" linenums="1"
+--8<-- "docs/examples/microbots_introduction/log_analysis_bot.py"
+```
+
+The script does four things in order: it configures logging, imports `LogAnalysisBot`, instantiates the bot, and calls `run()` to analyze the log file. The next step explains each of these responsibilities and the arguments they accept.
+
+## Step 2 — Understanding the Script
+
+This step walks through the script section by section so you understand what each block does and how to adapt it to your own projects.
+
+- **Lines 1–3:**
+ ```python
+ import logging
+
+ logging.basicConfig(level=logging.INFO)
+ ```
+ Configures logging at the `INFO` level so you can see the bot's reasoning steps as it executes. Microbots automatically loads environment variables from a `.env` file in your project root, so no explicit `load_dotenv()` call is required.
+
+- **Line 5:**
+ ```python
+ from microbots import LogAnalysisBot
+ ```
+ Imports `LogAnalysisBot` from the `microbots` package.
+
+- **Lines 7–10:**
+ ```python
+ my_bot = LogAnalysisBot(
+ model="azure-openai/gpt-5-swe-agent",
+ folder_to_mount="code",
+ )
+ ```
+ Creates a `LogAnalysisBot` instance configured with the Azure OpenAI model and the local `code/` folder. The folder is mounted as **read-only** inside the Docker container, so the bot can read source files but never modify them. For the full list of constructor arguments, defaults, and types, see the API Reference [`LogAnalysisBot`](../../api-reference/microbots/bot/LogAnalysisBot.md).
+
+- **Lines 12–15:**
+ ```python
+ result = my_bot.run(
+ file_name="code/build.log",
+ timeout_in_seconds=600,
+ )
+ ```
+ Calls `my_bot.run()`, pointing the bot at `code/build.log` with a 10-minute timeout. The bot spins up a container, reads the log, correlates errors with source files, and returns its analysis. For the full list of `run()` parameters (including `max_iterations` and other defaults), see the API Reference [`LogAnalysisBot`](../../api-reference/microbots/bot/LogAnalysisBot.md).
+
+- **Line 16:**
+ ```python
+ print(result.result)
+ ```
+ Prints the bot's root-cause analysis. The `run()` method returns a `BotRunResult` object that exposes the bot's output, completion status, and any error encountered. For the complete field list, see the API Reference [`BotRunResult`](../../api-reference/microbots/MicroBot.md#microbots.MicroBot.BotRunResult).
+
+## Conclusion
+
+In this guide, you created the `log_analysis_bot.py` script that instantiates a `LogAnalysisBot`, points it at the `code/` folder, and calls `run()` against `build.log`. You also reviewed every constructor and `run()` argument the bot exposes. Continue to the [Output and Log Parsing](output-and-log-parsing.md) guide to execute the script and walk through the output the bot produces.
+
diff --git a/docs/guides/create-your-first-microbot-project/output-and-log-parsing.md b/docs/guides/create-your-first-microbot-project/output-and-log-parsing.md
new file mode 100644
index 0000000..9096f5d
--- /dev/null
+++ b/docs/guides/create-your-first-microbot-project/output-and-log-parsing.md
@@ -0,0 +1,146 @@
+# Output and Log Parsing
+
+### Introduction
+
+With the `log_analysis_bot.py` script in place, the next task is to execute it and interpret the output. Microbots emits two complementary streams: structured logger output that traces every container action and LLM iteration, and the bot's final analysis returned through `result.result`.
+
+In this guide, you will run the script, inspect the full logger output to see how the bot reasons over the build log, and review the root-cause analysis that `LogAnalysisBot` produces.
+
+## Prerequisites
+
+To complete this guide, you will need:
+
+- A `log_analysis_bot.py` script at the root of your project. See the [LogAnalysisBot](log-analysis-bot.md) guide.
+- A `code/` folder containing `app.ts` and `build.log`. See the [Sample Project Creation and First Run](sample-project-and-first-run.md) guide.
+- Docker running on your machine. See the [Pre-requisites](../getting-started/prerequisites.md#step-2-installing-docker) guide.
+
+## Step 1 — Running the Bot
+
+In this step, you will execute the script you created in the previous guide and let the `LogAnalysisBot` analyze the build log.
+
+From the root of the `microbots-introduction` project, with your virtual environment activated, run:
+
+```bash title="Terminal"
+python3 log_analysis_bot.py
+```
+
+The `LogAnalysisBot` spins up a Docker container, mounts the `code` folder as read-only, copies `build.log` into `/var/log/` inside the container, and uses the LLM to analyze the log file and report the root cause.
+
+## Step 2 — Tracing the Bot's Reasoning Through the Logger Output
+
+In this step, you will read through the `INFO`-level logger output that Microbots emits during a run, broken into the six stages that make up the bot's lifecycle: container setup, task start, log inspection, source-file correlation, root-cause identification, and teardown. This trace is what `logging.basicConfig(level=logging.INFO)` enables in the script.
+
+Tracing the logger output matters when you are **debugging** an unexpected result, **understanding** how a bot decomposes a task into shell commands, or **auditing** which files and commands the LLM touched inside the container. For day-to-day usage — where you only care about the final answer — you can rely on `result.result` alone.
+
+!!! tip "Skip ahead if you only need the final answer"
+ If you are not interested in the bot's internal reasoning trace, you can skip directly to [Step 3 — Reviewing the Root-Cause Analysis](#step-3-reviewing-the-root-cause-analysis), which covers the value returned in `result.result`.
+
+Because the script sets `logging.basicConfig(level=logging.INFO)`, the run produces detailed step-by-step output. Rather than reproducing the full transcript, the snippets below walk through the run in order, with a short explanation of what is happening at each stage.
+
+### 1. Environment setup
+
+When the script starts, the `LocalDockerEnvironment` provisions an isolated working directory on the host, starts a fresh Docker container, sets up the read-only OverlayFS mount for the `code` folder, and copies `build.log` into the container's `/var/log/` directory:
+
+```text title="Environment setup"
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:🗂️ Created working directory at /home/sikannan/MICROBOTS_WORKDIR_18da47d7
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:📦 Volume mapping: /mnt/c/Users/sikannan/codeBase/microbots-examples/code → /ro/code
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:🚀 Started container b4826a8d41b7 with image kavyasree261002/shell_server:latest on host port 35291
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:🔒 Set up overlay mount for read-only directory at /workdir/code
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:✅ Successfully copied /mnt/c/Users/sikannan/codeBase/microbots-examples/code/build.log to container:/var/log
+```
+
+### 2. Task starts and the LLM lists the log directory
+
+The bot sends the task prompt to the LLM, which decides to begin by listing `/var/log` to find which file to inspect. Each iteration is logged as a `Step-N` block with the LLM's thoughts, the command it issued, and the command's output:
+
+```text title="Step 1 — list /var/log"
+INFO: MicroBot : ℹ️ TASK STARTED :
+ Analyze the log file `/var/log`
+INFO: MicroBot :-------------------- Step-1 --------------------
+INFO: MicroBot : 💭 LLM thoughts: First, I need to see what log files exist in /var/log to determine which one to analyze.
+INFO: MicroBot : ➡️ LLM tool call : "ls -1 /var/log"
+INFO: MicroBot : ⬅️ Command output:
+ShellCommunicator.log
+build.log
+dpkg.log
+...
+```
+
+### 3. The LLM inspects `build.log`
+
+Steps 2 and 3 show the LLM gauging the log size with `wc -l` and then reading the file with `cat`. The TypeScript compiler errors surface here, giving the LLM concrete error codes (`TS1005`, `TS1128`) and line numbers to follow:
+
+```text title="Step 3 — read build.log"
+INFO: MicroBot :-------------------- Step-3 --------------------
+INFO: MicroBot : 💭 LLM thoughts: The build.log is small, so I can safely view it to check for errors.
+INFO: MicroBot : ➡️ LLM tool call : "cat /var/log/build.log"
+INFO: MicroBot : ⬅️ Command output:
+app.ts(8,34): error TS1005: ',' expected.
+app.ts(8,43): error TS1005: ',' expected.
+app.ts(9,12): error TS1005: ':' expected.
+app.ts(9,14): error TS1005: ',' expected.
+app.ts(10,1): error TS1128: Declaration or statement expected.
+```
+
+### 4. The LLM correlates errors with the source file
+
+Now that the LLM knows the error originates in `app.ts`, it lists the mounted `code` folder and reads `app.ts` with line numbers (`nl -ba`) so it can locate the exact malformed line:
+
+```text title="Step 5 — read app.ts with line numbers"
+INFO: MicroBot :-------------------- Step-5 --------------------
+INFO: MicroBot : 💭 LLM thoughts: Open the TypeScript file to inspect the syntax around lines 8-10 where errors are reported.
+INFO: MicroBot : ➡️ LLM tool call : "nl -ba //workdir/code/app.ts | sed -n '1,40p'"
+INFO: MicroBot : ⬅️ Command output:
+ 7 // Missing closing parenthesis on the type annotation
+ 8 function add(a: number, b: number: number {
+ 9 return a + b;
+ 10 }
+```
+
+### 5. Root cause is identified and the task completes
+
+The LLM has enough context to conclude. It returns `task_done: True` with a final reasoning trace that pinpoints the malformed signature on line 8 and proposes the corrected version. This is what later becomes `result.result`:
+
+```text title="Final thoughts"
+INFO: MicroBot : 💭 LLM final thoughts: Root cause identified from /var/log/build.log: TypeScript compilation fails due to a syntax error in //workdir/code/app.ts at line 8. The function declaration is malformed: `function add(a: number, b: number: number {` has an extra `: number` after `b` and is missing the closing parenthesis before the return type. Correct signature should be: `function add(a: number, b: number): number {`.
+INFO: MicroBot :🔚 TASK COMPLETED
+```
+
+### 6. Container teardown
+
+Finally, the environment unmounts the overlay, removes the overlay directories, and deletes the working directory — leaving no trace on the host:
+
+```text title="Teardown"
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:🛠️ Tearing down overlay mount for code
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:✅ Unmounted overlay for code
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:🛑 Removing overlay dirs at //workdir/code and /workdir/overlay/
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:🗑️ Removed overlay directories for code
+INFO:microbots.environment.local_docker.LocalDockerEnvironment:🗑️ Removed working directory at /home/sikannan/MICROBOTS_WORKDIR_18da47d7
+```
+
+## Step 3 — Reviewing the Root-Cause Analysis
+
+In this step, you will inspect the value returned through `result.result`, which is the bot's final analysis. This is the artifact that downstream automation (a CI pipeline, a chat notification, an issue tracker) typically consumes.
+
+The `print(result.result)` call at the end of the script writes output similar to the following:
+
+```text title="Output"
+Root cause identified from /var/log/build.log: TypeScript
+compilation fails due to a syntax error in //workdir/code/
+app.ts at line 8. The function declaration is malformed:
+ `function add(a: number, b: number: number {`
+ has an extra `: number` after `b` and is missing the closing
+ parenthesis before the return type. This triggers TS1005
+ (',' expected) and subsequently TS1128 (Declaration or
+ statement expected). Correct signature should be:
+ `function add(a: number, b: number): number {`.
+```
+
+The `LogAnalysisBot` read `build.log`, correlated the compiler errors with the source code in `app.ts`, identified the malformed type annotation as the root cause, and proposed a corrected function signature — without any human intervention.
+
+!!! tip "DevOps Integration"
+ This pattern integrates naturally into CI/CD pipelines. Point the `LogAnalysisBot` at build logs, test reports, or deployment logs from tools like GitHub Actions, Azure DevOps, Jenkins, or GitLab CI — and get instant root-cause analysis delivered as part of your pipeline output.
+
+## Conclusion
+
+In this guide, you executed the `log_analysis_bot.py` script, traced the bot's reasoning through the logger output, and reviewed the root-cause analysis returned in `result.result`. Continue to the [Conclusion](conclusion.md) guide to see what Microbots did under the hood and to explore the other bots available in the framework.
diff --git a/docs/guides/create-your-first-microbot-project/sample-project-and-first-run.md b/docs/guides/create-your-first-microbot-project/sample-project-and-first-run.md
new file mode 100644
index 0000000..270b3d8
--- /dev/null
+++ b/docs/guides/create-your-first-microbot-project/sample-project-and-first-run.md
@@ -0,0 +1,92 @@
+# Sample Project Creation and First Run
+
+### Introduction
+
+Before running a Microbot, you need a target project for it to analyze. In this guide, you will create a small TypeScript project that contains a deliberate syntax error and capture the resulting compiler errors in a build log. The error and log together give the `LogAnalysisBot` something concrete to reason about in the next guide.
+
+By the end of this guide, you will have a `code/` folder with a broken TypeScript source file and a `build.log` file that records the failed compilation — the inputs the bot will use to demonstrate root-cause analysis.
+
+## Prerequisites
+
+To complete this guide, you will need:
+
+- A working Microbots project directory with the package installed and an `.env` file configured. See the [Microbot Installation](../getting-started/installation-guide.md) guide.
+- The **TypeScript compiler** (`tsc`) available on your `PATH`. Install it globally with `npm install -g typescript`. See the [TypeScript installation guide](https://www.typescriptlang.org/download) for details.
+
+## Step 1 — Creating the Code Directory
+
+In this step, you will add a sub-directory inside your Microbots project where the sample source files will live. Keeping the sample code in a dedicated folder lets you mount only that folder into the bot's container later.
+
+From the root of your `microbots-introduction` project, create a `code` directory:
+
+```bash title="Terminal"
+mkdir code
+```
+
+The `mkdir` command creates a new folder named `code` next to the `.venv` and `.env` files you created earlier.
+
+## Step 2 — Adding a TypeScript File With a Deliberate Error
+
+In this step, you will add a TypeScript file that contains a malformed function signature. The error is intentional — it is what the `LogAnalysisBot` will diagnose later.
+
+Create a file named `code/app.ts` with the following content:
+
+```typescript title="code/app.ts" linenums="1"
+--8<-- "docs/examples/microbots_introduction/code/app.ts"
+```
+
+The function `add` on line 8 has a malformed type annotation: `b: number: number` instead of `b: number): number`. The closing parenthesis is missing before the return-type annotation, so the TypeScript compiler will fail to parse the function.
+
+## Step 3 — Generating the Build Log
+
+In this step, you will run the TypeScript compiler against `app.ts` and capture both standard output and standard error into a `build.log` file. The bot will read this log to identify what went wrong.
+
+Before invoking the compiler, confirm that **Node.js** and the **TypeScript compiler (`tsc`)** are installed and reachable from your terminal:
+
+```bash title="Terminal"
+node --version
+tsc --version
+```
+
+Both commands should print a version number. `node --version` prints the installed Node.js runtime (for example, `v20.11.0`), and `tsc --version` prints the TypeScript compiler version (for example, `Version 5.4.5`).
+
+!!! note "If either command is missing"
+ - **Node.js not found** — Install it from [nodejs.org](https://nodejs.org/) (the LTS release is recommended) and re-open your terminal.
+ - **`tsc` not found** — Install the TypeScript compiler globally with `npm install -g typescript`, then re-run `tsc --version` to confirm it is on your `PATH`.
+
+From the project root, run the compiler and redirect its output to `build.log`:
+
+```bash title="Terminal"
+cd code
+tsc app.ts > build.log 2>&1
+cd ..
+```
+
+The `tsc app.ts` command invokes the TypeScript compiler on `app.ts`. The redirection `> build.log 2>&1` writes both standard output (`stdout`) and standard error (`stderr`) into the same file, so any compiler diagnostics are captured.
+
+Open `code/build.log` to confirm it contains the compiler errors:
+
+```log title="code/build.log"
+app.ts(8,34): error TS1005: ',' expected.
+app.ts(8,43): error TS1005: ',' expected.
+app.ts(9,12): error TS1005: ':' expected.
+app.ts(9,14): error TS1005: ',' expected.
+app.ts(10,1): error TS1128: Declaration or statement expected.
+```
+
+Your project folder should now have the following structure:
+
+```text title="Project layout"
+microbots-introduction/
+├── .venv
+├── .env
+└── code/
+ ├── app.ts
+ ├── app.js
+ └── build.log
+```
+
+## Conclusion
+
+In this guide, you created a `code/` directory, added a TypeScript file with a deliberate syntax error, and generated a `build.log` file that captures the compilation failure. With these inputs in place, continue to the [LogAnalysisBot](log-analysis-bot.md) guide to write the script that points a bot at this log and produces a root-cause analysis.
+
diff --git a/docs/guides/getting-started/installation-guide.md b/docs/guides/getting-started/installation-guide.md
new file mode 100644
index 0000000..23e15ad
--- /dev/null
+++ b/docs/guides/getting-started/installation-guide.md
@@ -0,0 +1,85 @@
+# Microbot Installation
+
+### Introduction
+
+With Python and Docker in place, the next task is to install the `microbots` package into an isolated Python environment and configure the LLM provider that the bots will use. Isolating dependencies in a virtual environment prevents version conflicts with other Python projects on your machine, and storing credentials in a `.env` file keeps API keys out of source control.
+
+In this guide, you will create a project directory, set up a Python virtual environment, install the `microbots` package, and configure **Azure OpenAI** as the LLM provider through a `.env` file. By the end, your project will be ready to run its first bot.
+
+## Prerequisites
+
+To complete this guide, you will need:
+
+- **Python 3.10 or later, but below 3.13** installed on your machine. See the [Pre-requisites](prerequisites.md#step-1-installing-python) guide.
+- **Docker** installed and running. See the [Pre-requisites](prerequisites.md#step-2-installing-docker) guide.
+- An **Azure OpenAI** resource with an API key, endpoint URL, and a deployed model. See the [Azure OpenAI documentation](https://learn.microsoft.com/azure/ai-services/openai/how-to/create-resource) for setup instructions.
+
+!!! warning "Python 3.13 is not supported"
+ Some of the `microbots` dependencies do not yet support Python 3.13. Use a Python version that is **at least 3.10 and below 3.13** (for example, 3.10, 3.11, or 3.12). You can check your version with `python3 --version`.
+
+## Step 1 — Setting Up the Project Directory
+
+In this step, you will create a project folder and a Python virtual environment that isolates the `microbots` package and its dependencies from your system Python installation.
+
+Create a project folder for your bot and navigate into it:
+
+```bash title="Terminal"
+mkdir microbots-introduction
+cd microbots-introduction
+```
+
+The `mkdir` command creates a new directory named `microbots-introduction`, and `cd` makes it your working directory.
+
+Next, create a Python virtual environment inside the project folder:
+
+```bash title="Terminal"
+python3 -m venv .venv
+```
+
+The `-m venv` flag tells Python to run the built-in `venv` module, which creates an isolated environment in the `.venv` directory. Any packages installed while this environment is active will be scoped to this project only.
+
+Activate the virtual environment so subsequent `pip` commands install packages into it:
+
+```bash title="Terminal"
+source .venv/bin/activate
+```
+
+When activation succeeds, your shell prompt will be prefixed with `(.venv)`.
+
+Finally, install the `microbots` package from PyPI:
+
+```bash title="Terminal"
+pip install microbots
+```
+
+This downloads `microbots` and its dependencies into the active virtual environment.
+
+You have now created a project folder and installed the `microbots` package into an isolated environment. In the next step, you will configure the LLM provider credentials.
+
+## Step 2 — Configuring the LLM Provider
+
+In this step, you will configure the credentials Microbots uses to authenticate with an LLM. Microbots currently supports **Azure OpenAI**, **Anthropic**, and **Ollama** as LLM providers. This guide uses **Azure OpenAI**.
+
+You will need three values from your Azure OpenAI resource:
+
+- An **API key** (`OPEN_AI_KEY`)
+- An **endpoint URL** (`OPEN_AI_END_POINT`)
+- A **deployed model name**
+
+Create a file named `.env` in the root of your project and add the following content:
+
+```env title=".env"
+OPEN_AI_END_POINT="https://your-resource-name.openai.azure.com"
+OPEN_AI_KEY="your-api-key-here"
+OPEN_AI_API_VERSION="2023-03-15-preview"
+```
+
+Replace `your-resource-name` with the name of your Azure OpenAI resource and `your-api-key-here` with the key from the Azure portal. The `OPEN_AI_API_VERSION` value pins the Azure OpenAI REST API version that the framework uses; keep the value shown unless your resource requires a different version.
+
+!!! note
+ For advanced authentication options (Azure AD tokens, managed identity, service principals), see the [Authentication Guide](../advanced/authentication.md).
+
+## Conclusion
+
+In this guide, you set up an isolated Python virtual environment, installed the `microbots` package, and configured the Azure OpenAI credentials your bots will use. Your project is now ready for its first bot run. Continue with the [Sample Project Creation and First Run](../create-your-first-microbot-project/sample-project-and-first-run.md) guide to create a sample TypeScript project and execute the `LogAnalysisBot` against it.
+
diff --git a/docs/guides/getting-started/introduction.md b/docs/guides/getting-started/introduction.md
new file mode 100644
index 0000000..43ff9c7
--- /dev/null
+++ b/docs/guides/getting-started/introduction.md
@@ -0,0 +1,37 @@
+# Microbots : Introduction
+
+**Published on:** April 15, 2026 | **Author:** Siva Kannan
+
+### Introduction
+
+Microbots is a lightweight, extensible AI agent framework for code comprehension and controlled file edits. It is designed for developers who want to embed LLM-driven automation into their pipelines without exposing the host machine, source files, or credentials to the model.
+
+## What Microbots Provides
+
+Microbots mounts a target directory with explicit read-only or read/write permissions, so an LLM can inspect, refactor, or generate files with least-privilege access. Every command an agent executes runs inside a disposable Docker container, which means the host machine, files, and credentials are never directly exposed to the model.
+
+## How It Works (At a Glance)
+
+
+
+When a bot is invoked, Microbots provisions a containerized environment and mounts the specified directory with the permission level the bot requires (`READ_ONLY` or `READ_WRITE`). The LLM drives the bot in an iterative loop — issuing shell commands, reading their output, and reasoning over the results — but every command executes inside the container. This boundary is what keeps the AI agent operating within defined limits, protecting the local environment and giving you predictable, reviewable control over any code modifications.
+
+## Safety Features
+
+Microbots enforces safety through five reinforcing layers:
+
+- **Container isolation** runs every command inside a disposable Docker container.
+- **OverlayFS** provides copy-on-write filesystem protection, so changes never touch the underlying mount.
+- **OS-level permission labels** (`READ_ONLY` and `READ_WRITE`) are enforced on every mounted folder.
+- **Dangerous command detection** validates each command and blocks destructive patterns before execution.
+- **Iteration budget management** caps sub-agent loops to prevent runaway costs.
+
+The core philosophy is simple — assume the LLM will eventually produce a harmful command, and architect the system so that it does not matter when it does.
+
+!!! tip "Want to understand the details?"
+ Read the [Microbots : Safety First Agentic Workflow](../../blog/microbots-safety-first-ai-agent.md) article for a deep dive into the architecture and all five layers of defense.
+
+## Conclusion
+
+In this article, you reviewed what Microbots is and the five-layer safety model that keeps every agent action contained. Next, set up the development environment by following the [Pre-requisites](prerequisites.md) guide to install Python and Docker, then continue with the [Microbot Installation](installation-guide.md) guide to install the package and configure your LLM provider.
+
diff --git a/docs/guides/getting-started/prerequisites.md b/docs/guides/getting-started/prerequisites.md
new file mode 100644
index 0000000..ca50430
--- /dev/null
+++ b/docs/guides/getting-started/prerequisites.md
@@ -0,0 +1,73 @@
+# Pre-requisites
+
+### Introduction
+
+Before installing the `microbots` package, you must prepare your machine with the two tools the framework depends on: **Python** for the runtime, and **Docker** for the sandboxed execution environment that isolates every agent command.
+
+In this guide, you will install a supported Python version (3.10 or later, but below 3.13), install Docker, and verify that both tools are available from your terminal. Once you finish, your environment will be ready for the [Microbot Installation](installation-guide.md) guide.
+
+!!! warning "External Links Disclaimer"
+ This document contains links to external documentation that may change or be removed over time. All external references were verified at the time of writing and are only considered valid as of the publication date.
+
+## Step 1 — Installing Python
+
+Microbots requires **Python 3.10 or later, but below 3.13** (for example, 3.10, 3.11, or 3.12). Python 3.13 is not yet supported because some `microbots` dependencies have not released 3.13-compatible wheels. In this step, you will install Python and confirm it is on your `PATH`.
+
+Choose the instructions that match your operating system:
+
+- **Windows:** Download the latest installer from [python.org](https://www.python.org/downloads/). During installation, check **"Add Python to PATH"** so that `python` and `pip` are available from any terminal.
+- **Linux:** Python is often pre-installed. If it is not, install it using your distribution's package manager:
+
+ ```bash title="Terminal"
+ # Ubuntu / Debian
+ sudo apt update && sudo apt install python3 python3-pip python3-venv
+
+ # Fedora
+ sudo dnf install python3 python3-pip
+ ```
+
+ The `python3-venv` package is required on Debian-based systems so you can create isolated virtual environments later.
+
+After installation, verify that Python and `pip` are available:
+
+```bash title="Terminal"
+python3 --version
+pip3 --version
+```
+
+You should see a version that is **at least 3.10 and below 3.13**. If both commands succeed, Python is ready, and you can move on to installing Docker.
+
+## Step 2 — Installing Docker
+
+Microbots runs all agent commands inside Docker containers, which means Docker must be installed and running before any bot can execute. In this step, you will install Docker and verify that the daemon is reachable.
+
+Choose the instructions that match your operating system:
+
+- **Windows / macOS:** Download and install [Docker Desktop](https://www.docker.com/products/docker-desktop/). After installation, launch Docker Desktop so that the daemon is running in the background.
+- **Linux:** Follow the official [Docker Engine installation guide](https://docs.docker.com/engine/install/) for your distribution. After installation, you must start the Docker daemon and grant your user permission to access the Docker socket — otherwise running a bot will fail with `PermissionError: [Errno 13] Permission denied` on `/var/run/docker.sock`.
+
+ ```bash title="Terminal"
+ # Start the Docker daemon now and on every boot
+ sudo systemctl enable --now docker
+
+ # Add your user to the docker group so you don't need sudo
+ sudo usermod -aG docker $USER
+
+ # Apply the new group in the current shell (alternatively, log out and back in)
+ newgrp docker
+ ```
+
+After installation, verify that Docker is installed and the daemon is responsive:
+
+```bash title="Terminal"
+docker --version
+docker ps # should succeed without sudo
+docker run hello-world
+```
+
+The first command prints the installed Docker version. `docker ps` confirms your user can talk to the daemon without `sudo`. The last command pulls the `hello-world` image and runs it in a container — if you see a "Hello from Docker!" message, the daemon is reachable.
+
+## Conclusion
+
+In this guide, you installed a supported Python version (3.10 or later, but below 3.13) and Docker, and you confirmed both tools are working from your terminal. Your machine is now ready to install the `microbots` package. Continue with the [Microbot Installation](installation-guide.md) guide to set up your project and configure an LLM provider.
+
diff --git a/docs/guides/index.md b/docs/guides/index.md
new file mode 100644
index 0000000..a5516b5
--- /dev/null
+++ b/docs/guides/index.md
@@ -0,0 +1,57 @@
+# Guides
+
+Explore the Microbots guides to learn what the framework provides, how to install it, how to build your first project, and how to extend it with custom tools and advanced authentication. The guides are grouped by purpose so you can pick the right starting point for your task.
+
+If you are new to Microbots, start with the [Microbots Introduction](introduction.md), then walk through the [Installation Guide](#installation-guide) and [Create Your First Microbot Project](#create-your-first-microbot-project) end-to-end.
+
+## Microbots Introduction
+
+Read the [Microbots Introduction](introduction.md) to learn what Microbots is and the five-layer safety model that keeps every agent action contained.
+
+## Installation Guide
+
+Install the prerequisites and set up the `microbots` package with your LLM provider. Read these articles in order.
+
+| # | Guide | Description |
+|---|-------|-------------|
+| 1 | [Pre-requisites](getting-started/prerequisites.md) | Install Python 3.10+ and Docker, and verify both are available from your terminal. |
+| 2 | [Microbot Installation](getting-started/installation-guide.md) | Create a project, set up a virtual environment, install the `microbots` package, and configure Azure OpenAI credentials. |
+
+## Create Your First Microbot Project
+
+Build a complete project that runs the `LogAnalysisBot` against a deliberately broken TypeScript build log. Read these articles in order after finishing the Getting Started section.
+
+| # | Guide | Description |
+|---|-------|-------------|
+| 1 | [Sample Project Creation and First Run](create-your-first-microbot-project/sample-project-and-first-run.md) | Create a sample TypeScript project with a deliberate syntax error and capture the compiler output in `build.log`. |
+| 2 | [LogAnalysisBot](create-your-first-microbot-project/log-analysis-bot.md) | Write the Python script that instantiates a `LogAnalysisBot` and points it at the build log. |
+| 3 | [Output and Log Parsing](create-your-first-microbot-project/output-and-log-parsing.md) | Run the bot, trace its reasoning through the logger output, and review the root-cause analysis. |
+| 4 | [Conclusion](create-your-first-microbot-project/conclusion.md) | Recap what happened under the hood and survey the other bots available in the framework. |
+
+## Bots
+
+Reference guides for individual bot types beyond the ones used in the walkthrough.
+
+| Guide | Description |
+|-------|-------------|
+| [CopilotBot](bots/copilot-bot.md) | Use `CopilotBot` for AI-assisted coding workflows. |
+
+## Tools
+
+Extend a bot's capabilities with your own tools.
+
+| Guide | Description |
+|-------|-------------|
+| [Custom Tool Integration Walkthrough](tools/tesseract_ocr_tool_use.md) | Build and integrate a custom tool (Tesseract OCR) into a Microbots workflow. |
+
+## Advanced
+
+Deeper configuration topics for production deployments.
+
+| Guide | Description |
+|-------|-------------|
+| [Authentication](advanced/authentication.md) | Configure Azure AD tokens, managed identity, and service principals. |
+
+## Contributing to the Docs
+
+Before authoring or editing documentation, read the [Technical Writing Guidelines](technical-writing-guidelines.md) — they define the style, structure, formatting, and terminology conventions used across every Microbots article.
diff --git a/docs/guides/introduction.md b/docs/guides/introduction.md
new file mode 100644
index 0000000..b973041
--- /dev/null
+++ b/docs/guides/introduction.md
@@ -0,0 +1,37 @@
+# Microbots : Introduction
+
+**Published on:** April 15, 2026 | **Author:** Siva Kannan
+
+### Introduction
+
+Microbots is a lightweight, extensible AI agent framework for code comprehension and controlled file edits. It is designed for developers who want to embed LLM-driven automation into their pipelines without exposing the host machine, source files, or credentials to the model.
+
+## What Microbots Provides
+
+Microbots mounts a target directory with explicit read-only or read/write permissions, so an LLM can inspect, refactor, or generate files with least-privilege access. Every command an agent executes runs inside a disposable Docker container, which means the host machine, files, and credentials are never directly exposed to the model.
+
+## How It Works (At a Glance)
+
+
+
+When a bot is invoked, Microbots provisions a containerized environment and mounts the specified directory with the permission level the bot requires (`READ_ONLY` or `READ_WRITE`). The LLM drives the bot in an iterative loop — issuing shell commands, reading their output, and reasoning over the results — but every command executes inside the container. This boundary is what keeps the AI agent operating within defined limits, protecting the local environment and giving you predictable, reviewable control over any code modifications.
+
+## Safety Features
+
+Microbots enforces safety through five reinforcing layers:
+
+- **Container isolation** runs every command inside a disposable Docker container.
+- **OverlayFS** provides copy-on-write filesystem protection, so changes never touch the underlying mount.
+- **OS-level permission labels** (`READ_ONLY` and `READ_WRITE`) are enforced on every mounted folder.
+- **Dangerous command detection** validates each command and blocks destructive patterns before execution.
+- **Iteration budget management** caps sub-agent loops to prevent runaway costs.
+
+The core philosophy is simple — assume the LLM will eventually produce a harmful command, and architect the system so that it does not matter when it does.
+
+!!! tip "Want to understand the details?"
+ Read the [Microbots : Safety First Agentic Workflow](../blog/microbots-safety-first-ai-agent.md) article for a deep dive into the architecture and all five layers of defense.
+
+## Conclusion
+
+In this article, you reviewed what Microbots is and the five-layer safety model that keeps every agent action contained. Next, set up the development environment by following the [Pre-requisites](getting-started/prerequisites.md) guide to install Python and Docker, then continue with the [Microbot Installation](getting-started/installation-guide.md) guide to install the package and configure your LLM provider.
+
diff --git a/docs/guides/technical-writing-guidelines.md b/docs/guides/technical-writing-guidelines.md
new file mode 100644
index 0000000..aeccf76
--- /dev/null
+++ b/docs/guides/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/guides/tools/tesseract_ocr_tool_use.md
similarity index 100%
rename from docs/blog/guides/tesseract_ocr_tool_use.md
rename to docs/guides/tools/tesseract_ocr_tool_use.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 34a415d..6d9be80 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -56,17 +56,30 @@ markdown_extensions:
- pymdownx.tabbed:
alternate_style: true
- admonition
+ - pymdownx.details
- tables
- attr_list
+ - md_in_html
nav:
- - Getting Started:
- - Home: index.md
- Guides:
- - CopilotBot: copilot-bot.md
- - Authentication: authentication.md
+ - guides/index.md
+ - "Microbots Introduction": guides/introduction.md
+ - Installation Guide:
+ - "Pre-requisites": guides/getting-started/prerequisites.md
+ - "Microbot Installation": guides/getting-started/installation-guide.md
+ - Create Your First Microbot Project:
+ - "Sample Project Creation and First Run": guides/create-your-first-microbot-project/sample-project-and-first-run.md
+ - "LogAnalysisBot": guides/create-your-first-microbot-project/log-analysis-bot.md
+ - "Output and Log Parsing": guides/create-your-first-microbot-project/output-and-log-parsing.md
+ - "Conclusion": guides/create-your-first-microbot-project/conclusion.md
+ - Bots:
+ - CopilotBot: guides/bots/copilot-bot.md
- Tools:
- - "Custom Tool Integration Walkthrough": blog/guides/tesseract_ocr_tool_use.md
+ - "Custom Tool Integration Walkthrough": guides/tools/tesseract_ocr_tool_use.md
+ - Advanced:
+ - Authentication: guides/advanced/authentication.md
+ - "Technical Writing Guidelines": guides/technical-writing-guidelines.md
- Blogs:
- blog/index.md
- "Microbots : Safety First Agentic Workflow": blog/microbots-safety-first-ai-agent.md