From fcafb671d353a4eebf1d51989a59bb0d6130c9a5 Mon Sep 17 00:00:00 2001
From: CleverThis <hal9000@cleverthis.com>
Date: Mon, 4 May 2026 19:21:46 +0000
Subject: [PATCH] docs: add quick start guide (PR #9245)

Add docs/quickstart.md with end-to-end quick start guide covering
prerequisites, installation, project creation, resource registration,
plan/apply workflow, and troubleshooting.

Update mkdocs.yml navigation to include Quick Start page and rename
ADR-028 title to Skill/Tool Abstraction Definition.

Update CHANGELOG.md with quick start guide entry.

Closes #9245
---
 CHANGELOG.md       |  1 +
 docs/quickstart.md | 43 +++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml         |  3 ++-
 3 files changed, 46 insertions(+), 1 deletion(-)
 create mode 100644 docs/quickstart.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0663943a4..9443dec44 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -31,6 +31,7 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- **Quick Start Guide** (PR #9245): Added `docs/quickstart.md` with an end-to-end quick start guide covering prerequisites, installation, project creation, resource registration, plan/apply workflow, and troubleshooting. Updated `mkdocs.yml` navigation to include the Quick Start page.
 
 - **Plan checkpoint management CLI commands** (#8683): Added `agents plan checkpoint-list <plan-id>` and `agents plan checkpoint-delete <checkpoint-id>` commands. Listing output now highlights checkpoint ID, type, created timestamp, reason, phase, and decision linkage with a concise field summary footer across rich/table/json/yaml formats. Deletion supports batch IDs, interactive confirmation (skip with `--yes`), and structured JSON/YAML responses for automation-friendly scripting.
 - **Invariant Remove CLI Command** (#8530): Implemented `agents invariant remove <id>` command that soft-deletes an invariant by ID. The command displays a confirmation prompt before removal (bypassable with `--yes`/`-y`), outputs the removed invariant ID on success, and shows a clear error message when the invariant ID does not exist. Supports `--format` flag for JSON and YAML output. Full BDD test coverage and Robot Framework integration tests included.
diff --git a/docs/quickstart.md b/docs/quickstart.md
new file mode 100644
index 000000000..f495088ea
--- /dev/null
+++ b/docs/quickstart.md
@@ -0,0 +1,43 @@
+# Quick Start Guide
+
+This quick start guide will walk you through creating a new project, registering a resource, running a plan, and applying changes with CleverAgents.
+
+## Prerequisites
+
+- Python 3.11+ and virtualenv
+- Git
+- A working CleverAgents installation (see development/testing.md for details)
+
+## Install (local development)
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+```
+
+## Create a new project
+
+```bash
+# Create a new directory for your project
+mkdir my-project && cd my-project
+# Initialize a CleverAgents project (example command)
+cleveragents init --name my-project
+```
+
+## Register a resource
+
+Create a resource file under `resources/` (example YAML) and register it with the CLI or API.
+
+## Plan and apply
+
+```bash
+# Generate a plan
+cleveragents plan --project my-project
+# Review the plan, then apply
+cleveragents apply --project my-project
+```
+
+## Troubleshooting
+
+If you encounter issues running the examples above, consult `docs/development/testing.md` and the project README for local development tips.
diff --git a/mkdocs.yml b/mkdocs.yml
index 5d0e312b0..ec60f314f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -60,6 +60,7 @@ nav:
     - Reference/Command Input & Sessions: tui/input-and-sessions.md
     - Configuration, Key Bindings & Integration: tui/configuration-and-integration.md
   - FAQ: faq.md
+  - Quick Start: quickstart.md
   - Changelog: CHANGELOG.md
   - Contributing: CONTRIBUTING.md
   - Reference: reference/
@@ -92,7 +93,7 @@ nav:
     - ADR-025 Observability & Logging: adr/ADR-025-observability-and-logging.md
     - ADR-026 Agent-to-Agent Protocol (A2A): adr/ADR-026-agent-client-protocol.md
     - ADR-027 Language Server Protocol (LSP) Integration: adr/ADR-027-language-server-protocol.md
-    - ADR-028 Agent Skills Standard (AgentSkills.io): adr/ADR-028-agent-skills-standard.md
+    - ADR-028 Skill/Tool Abstraction Definition: adr/ADR-028-agent-skills-standard.md
     - ADR-029 Model Context Protocol (MCP) Adoption: adr/ADR-029-model-context-protocol.md
     - ADR-030 Skill Abstraction Definition: adr/ADR-030-skill-abstraction-definition.md
     - ADR-031 Actor Abstraction Definition: adr/ADR-031-actor-abstraction-definition.md