From d1275f00757146645ae891d6da92e390d4256c98 Mon Sep 17 00:00:00 2001
From: Oliver Lipkau <oliver@lipkau.net>
Date: Tue, 19 May 2026 23:53:40 +0200
Subject: [PATCH] Enrich JiraAgilePS docs with practical guides

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/JiraAgilePS/command-guide.md   | 52 +++++++++++++++++++++++++++++
 docs/JiraAgilePS/getting-started.md | 48 ++++++++++++++++++++++++++
 docs/JiraAgilePS/index.md           | 27 +++++++++++----
 3 files changed, 120 insertions(+), 7 deletions(-)
 create mode 100644 docs/JiraAgilePS/command-guide.md
 create mode 100644 docs/JiraAgilePS/getting-started.md

diff --git a/docs/JiraAgilePS/command-guide.md b/docs/JiraAgilePS/command-guide.md
new file mode 100644
index 0000000..a4ca29a
--- /dev/null
+++ b/docs/JiraAgilePS/command-guide.md
@@ -0,0 +1,52 @@
+---
+layout: documentation
+title: Command guide
+permalink: /docs/JiraAgilePS/command-guide/
+---
+# JiraAgilePS command guide
+
+This page summarizes the commands currently available in JiraAgilePS and shows practical examples.
+
+## Get-Board
+
+Use this to list boards or fetch specific boards by ID.
+
+```powershell
+# List boards (paged)
+JiraAgilePS\Get-Board -Credential $cred
+
+# Fetch specific boards by id
+JiraAgilePS\Get-Board -BoardId 101, 205 -Credential $cred
+```
+
+## Get-Sprint
+
+Use this to list sprints for a board, optionally filtered by state.
+
+```powershell
+$board = JiraAgilePS\Get-Board -Credential $cred | Select-Object -First 1
+
+# All sprints for a board
+JiraAgilePS\Get-Sprint -Board $board -Credential $cred
+
+# Only active sprints
+JiraAgilePS\Get-Sprint -Board $board -State Active -Credential $cred
+```
+
+## Add-IssueToSprint
+
+Use this to move one or more issues into a sprint.
+
+```powershell
+$board  = JiraAgilePS\Get-Board -Credential $cred | Select-Object -First 1
+$sprint = JiraAgilePS\Get-Sprint -Board $board -State Active -Credential $cred | Select-Object -First 1
+$issue  = Get-JiraIssue -Issue "PROJ-123" -Credential $cred
+
+JiraAgilePS\Add-IssueToSprint -Issue $issue -Sprint $sprint -Credential $cred
+```
+
+## Notes
+
+- JiraAgilePS extends JiraPS, so keep JiraPS session setup in place.
+- Use module-qualified command names (`JiraAgilePS\...`) when you want to avoid command name ambiguity.
+- For module source and issue tracking, see <https://github.com/AtlassianPS/JiraAgilePS>.
diff --git a/docs/JiraAgilePS/getting-started.md b/docs/JiraAgilePS/getting-started.md
new file mode 100644
index 0000000..1a5af83
--- /dev/null
+++ b/docs/JiraAgilePS/getting-started.md
@@ -0,0 +1,48 @@
+---
+layout: documentation
+title: Getting started
+permalink: /docs/JiraAgilePS/getting-started/
+---
+# Getting started with JiraAgilePS
+
+JiraAgilePS builds on JiraPS session and server configuration.  
+If JiraPS is already working in your environment, JiraAgilePS can use the same connection context.
+
+## 1. Install and import
+
+```powershell
+Install-Module JiraPS -Scope CurrentUser
+Install-Module JiraAgilePS -Scope CurrentUser
+
+Import-Module JiraPS
+Import-Module JiraAgilePS
+```
+
+## 2. Connect to Jira
+
+```powershell
+Set-JiraConfigServer "https://yourcompany.atlassian.net"
+$cred = Get-Credential
+New-JiraSession -Credential $cred
+```
+
+## 3. Confirm module commands
+
+```powershell
+Get-Command -Module JiraAgilePS
+```
+
+At the moment, the module exposes:
+
+- `Get-Board`
+- `Get-Sprint`
+- `Add-IssueToSprint`
+
+## 4. First board and sprint query
+
+```powershell
+$board = JiraAgilePS\Get-Board -Credential $cred | Select-Object -First 1
+JiraAgilePS\Get-Sprint -Board $board -Credential $cred
+```
+
+If this returns data, your environment is ready for sprint automation workflows.
diff --git a/docs/JiraAgilePS/index.md b/docs/JiraAgilePS/index.md
index 79835d4..20706e7 100644
--- a/docs/JiraAgilePS/index.md
+++ b/docs/JiraAgilePS/index.md
@@ -7,15 +7,28 @@ permalink: /docs/JiraAgilePS/
 
 JiraAgilePS extends JiraPS with Jira Agile functionality.
 
-If you are exploring what it can do, start here:
+This section is for practical, task-focused usage when you need to work with boards and sprints in automation scripts.
 
-1. Read the module overview: [/module/JiraAgilePS/](/module/JiraAgilePS/).
-2. Open the source and usage notes: <https://github.com/AtlassianPS/JiraAgilePS>.
-3. Discover commands in your shell:
+## What you can do
+
+JiraAgilePS currently focuses on three core operations:
+
+1. List boards (`Get-Board`)
+2. List sprint data for a board (`Get-Sprint`)
+3. Move issues into a sprint (`Add-IssueToSprint`)
+
+## Start here
+
+1. [Getting started](/docs/JiraAgilePS/getting-started/)
+2. [Command guide and examples](/docs/JiraAgilePS/command-guide/)
+3. Module landing page: [/module/JiraAgilePS/](/module/JiraAgilePS/)
+4. Source repository: <https://github.com/AtlassianPS/JiraAgilePS>
+
+## Quick discovery
 
 ```powershell
 Get-Command -Module JiraAgilePS
-Get-Help Get-JiraAgileBoard -Full
+Get-Help JiraAgilePS\Get-Board -Full
+Get-Help JiraAgilePS\Get-Sprint -Full
+Get-Help JiraAgilePS\Add-IssueToSprint -Full
 ```
-
-As we publish richer command reference pages, they will appear in this section.