From 8808997c9eefd1d7f3d63240f5052a5c7e658c8f Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 1 Jan 2026 09:10:22 +0000
Subject: [PATCH 1/2] Initial plan


From e2bcfec22558f3e9b6f1c25fcb6c9f4b7340717c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Thu, 1 Jan 2026 09:16:28 +0000
Subject: [PATCH 2/2] Add getting started guide and sample walkthrough

Co-authored-by: SamuelMcAravey <11021165+SamuelMcAravey@users.noreply.github.com>
---
 README.md                             |   8 +
 docs/00-overview/getting-started.md   | 393 ++++++++++++++++++++++++
 examples/sample-walkthrough/README.md | 410 ++++++++++++++++++++++++++
 3 files changed, 811 insertions(+)
 create mode 100644 docs/00-overview/getting-started.md
 create mode 100644 examples/sample-walkthrough/README.md

diff --git a/README.md b/README.md
index 5e4650c3..b23b9cea 100644
--- a/README.md
+++ b/README.md
@@ -3,12 +3,20 @@
 Workbench is a .NET CLI for managing Workbench documentation, work items, and
 contracts in this repo.
 
+## Getting Started
+
+**New to Workbench?** Start here:
+
+- **[Getting Started Guide](docs/00-overview/getting-started.md)**: Step-by-step tutorial covering installation, initialization, creating work items, and validation.
+- **[Sample Walkthrough](examples/sample-walkthrough/)**: Hands-on example demonstrating the complete Workbench workflow.
+
 ## Repository map
 
 - `src/Workbench`: CLI source code.
 - `tests/`: automated tests.
 - `docs/`: product, architecture, contracts, decisions, and runbooks.
 - `docs/70-work/`: active and completed work items plus templates.
+- `examples/`: sample walkthroughs and demonstrations.
 - `assets/`: static assets used by docs or tooling.
 - `artifacts/`: build outputs and local artifacts.
 - `testdata/`: fixtures for parsing and validation tests.
diff --git a/docs/00-overview/getting-started.md b/docs/00-overview/getting-started.md
new file mode 100644
index 00000000..15580ddf
--- /dev/null
+++ b/docs/00-overview/getting-started.md
@@ -0,0 +1,393 @@
+---
+workbench:
+  type: guide
+  workItems:
+    - TASK-0011
+  codeRefs: []
+owner: platform
+status: active
+updated: 2026-01-01
+---
+
+# Getting Started with Workbench
+
+Welcome to Workbench! This guide will walk you through installing and using
+Workbench to manage documentation, work items, and contracts in your repository.
+
+## What is Workbench?
+
+Workbench is a .NET CLI tool that helps you manage structured documentation and
+work items directly in your git repository. It provides:
+
+- Work item tracking with GitHub integration
+- Structured documentation with front matter and schemas
+- Navigation and validation tools
+- Voice-powered documentation and work item creation
+- Terminal UI for interactive workflows
+
+## Prerequisites
+
+- .NET SDK `10.0.100` or later (check with `dotnet --version`)
+- Git installed and configured
+- A git repository (existing or new)
+- Optional: GitHub CLI (`gh`) for GitHub integration
+- Optional: OpenAI API key for AI-powered features
+
+## Installation
+
+### Option 1: Build from source (current)
+
+Clone the Workbench repository and build it:
+
+```bash
+git clone https://github.com/bravellian/workbench.git
+cd workbench
+dotnet build Workbench.slnx
+```
+
+Run Workbench using:
+
+```bash
+dotnet run --project src/Workbench/Workbench.csproj -- <command>
+```
+
+Or create an alias for convenience:
+
+```bash
+# Add to your ~/.bashrc or ~/.zshrc
+alias workbench='dotnet run --project /path/to/workbench/src/Workbench/Workbench.csproj --'
+```
+
+### Option 2: Install as a .NET tool (future)
+
+Once published to NuGet, you'll be able to install globally:
+
+```bash
+dotnet tool install -g Workbench
+```
+
+### Option 3: Use a native binary
+
+Build a native binary for your platform:
+
+```bash
+# macOS ARM64
+dotnet publish src/Workbench/Workbench.csproj -c Release -r osx-arm64
+
+# macOS x64
+dotnet publish src/Workbench/Workbench.csproj -c Release -r osx-x64
+
+# Linux x64
+dotnet publish src/Workbench/Workbench.csproj -c Release -r linux-x64
+
+# Windows x64
+dotnet publish src/Workbench/Workbench.csproj -c Release -r win-x64
+```
+
+The binary will be in `src/Workbench/bin/Release/net10.0/<runtime>/publish/`.
+
+## Quick Start
+
+### 1. Initialize a repository
+
+Navigate to your git repository (or create a new one):
+
+```bash
+mkdir my-project
+cd my-project
+git init
+```
+
+Run the initialization wizard:
+
+```bash
+workbench init
+```
+
+This interactive wizard will:
+- Create the default folder structure (`docs/`, `docs/70-work/`, etc.)
+- Set up configuration in `.workbench/config.json`
+- Create templates for work items and documentation
+- Optionally configure OpenAI integration
+- Guide you through credential storage options
+
+For non-interactive setup:
+
+```bash
+workbench init --non-interactive --skip-wizard
+```
+
+### 2. Verify your setup
+
+Check that everything is configured correctly:
+
+```bash
+workbench doctor
+```
+
+This command validates:
+- Git is installed and the repository is initialized
+- Configuration is valid
+- Required directories exist
+- GitHub provider is configured (if applicable)
+
+### 3. Create your first work item
+
+#### Using the interactive wizard
+
+Launch the wizard:
+
+```bash
+workbench run
+```
+
+Follow the prompts to create a work item with the right type, title, and metadata.
+
+#### Using the command line
+
+Create a task directly:
+
+```bash
+workbench item new --type task --title "Set up project documentation" --priority high
+```
+
+This creates a new work item file in `docs/70-work/items/` with:
+- A unique ID (e.g., `TASK-0001`)
+- YAML front matter with metadata
+- A markdown body with sections for summary and acceptance criteria
+
+#### Using voice input
+
+Record a work item using your voice:
+
+```bash
+workbench voice workitem --type task
+```
+
+Requires `OPENAI_API_KEY` environment variable for transcription.
+
+### 4. View and manage work items
+
+List all open work items:
+
+```bash
+workbench item list
+```
+
+Show details of a specific item:
+
+```bash
+workbench item show TASK-0001
+```
+
+Update the status of a work item:
+
+```bash
+workbench item status TASK-0001 in-progress
+```
+
+Close a completed work item:
+
+```bash
+workbench item close TASK-0001 --move
+```
+
+The `--move` flag moves the item to `docs/70-work/done/`.
+
+### 5. Create documentation
+
+Create a feature specification:
+
+```bash
+workbench doc new --type spec --title "User authentication flow" --work-item TASK-0001
+```
+
+Create an architecture decision record:
+
+```bash
+workbench doc new --type adr --title "Use JWT for authentication"
+```
+
+Create a runbook:
+
+```bash
+workbench doc new --type runbook --title "Deploy to production"
+```
+
+### 6. Sync and validate
+
+Sync work items with GitHub issues:
+
+```bash
+workbench sync --items --issues
+```
+
+Update navigation and indexes:
+
+```bash
+workbench nav sync
+```
+
+Validate all work items, links, and schemas:
+
+```bash
+workbench validate
+```
+
+Use `--strict` in CI to treat warnings as errors:
+
+```bash
+workbench validate --strict
+```
+
+## Common Workflows
+
+### Creating a work item with a branch and PR
+
+Use the `promote` command for the full workflow:
+
+```bash
+workbench promote --type task --title "Add user search feature" --start --pr --draft
+```
+
+This:
+1. Creates a work item
+2. Creates and checks out a branch
+3. Makes an initial commit
+4. Creates a draft GitHub PR
+5. Links the PR to the work item
+
+### Importing GitHub issues as work items
+
+Import one or more issues:
+
+```bash
+workbench item import --issue 42 --issue 18
+```
+
+Or sync all unlinked issues:
+
+```bash
+workbench sync --import-issues
+```
+
+### Working with documentation
+
+Create a spec and link it to a work item:
+
+```bash
+workbench doc new --type spec --title "Payment processing" --work-item TASK-0005
+```
+
+Link an existing doc to a work item:
+
+```bash
+workbench item link TASK-0005 --spec docs/10-product/payment-spec.md
+```
+
+### Using AI features
+
+Generate a work item from freeform text:
+
+```bash
+workbench item generate --prompt "Add support for exporting data to CSV format"
+```
+
+Summarize documentation changes:
+
+```bash
+workbench doc summarize --staged
+```
+
+## Configuration
+
+Workbench reads configuration from `.workbench/config.json`. View the current config:
+
+```bash
+workbench config show
+```
+
+Update a specific setting:
+
+```bash
+workbench config set --path github.owner --value "myorg"
+```
+
+### GitHub Integration
+
+Workbench supports two GitHub providers:
+
+1. **gh CLI** (recommended): Uses the GitHub CLI's authentication
+2. **Octokit**: Uses a personal access token
+
+Set your provider in config:
+
+```bash
+workbench config set --path github.provider --value "gh"
+```
+
+For Octokit, store your token securely:
+
+```bash
+workbench config credentials set --key GITHUB_TOKEN --value "ghp_..."
+```
+
+### OpenAI Integration
+
+For AI-powered features (voice transcription, work item generation), configure OpenAI:
+
+```bash
+workbench config credentials set --key WORKBENCH_AI_OPENAI_KEY --value "sk-..."
+```
+
+Optional settings:
+
+```bash
+export WORKBENCH_AI_TRANSCRIPTION_MODEL="gpt-4o-mini-transcribe"
+export WORKBENCH_AI_TRANSCRIPTION_LANGUAGE="en"
+```
+
+## Next Steps
+
+- **Explore the [CLI reference](../30-contracts/cli-help.md)** for all available commands
+- **Read the [feature spec](../10-product/feature-spec-cli-onboarding-wizard.md)** for the onboarding wizard
+- **Try the [sample walkthrough](../../examples/sample-walkthrough/)** for a hands-on example
+- **Check the [documentation structure](documentation-structure.md)** to understand how docs are organized
+- **Review [ADRs](../40-decisions/README.md)** to understand architectural decisions
+
+## Troubleshooting
+
+### "Not a git repository" error
+
+Ensure you're in a git repository:
+
+```bash
+git init
+```
+
+### "GitHub provider not configured" warning
+
+Either install and authenticate with `gh`:
+
+```bash
+gh auth login
+```
+
+Or configure an Octokit token as described in the GitHub Integration section.
+
+### ".NET SDK not found" error
+
+Install .NET SDK 10.0.100 or later from [dotnet.microsoft.com](https://dotnet.microsoft.com/).
+
+### Voice features not working
+
+Ensure you have:
+- Set `OPENAI_API_KEY` environment variable
+- Granted microphone permissions to your terminal (macOS: System Settings → Privacy & Security → Microphone)
+
+## Getting Help
+
+- **CLI help**: Run `workbench --help` or `workbench <command> --help`
+- **Documentation**: Browse the `docs/` directory
+- **Issues**: Report issues at [github.com/bravellian/workbench/issues](https://github.com/bravellian/workbench/issues)
+- **Community**: Join discussions at [github.com/bravellian/workbench/discussions](https://github.com/bravellian/workbench/discussions)
diff --git a/examples/sample-walkthrough/README.md b/examples/sample-walkthrough/README.md
new file mode 100644
index 00000000..745fbe70
--- /dev/null
+++ b/examples/sample-walkthrough/README.md
@@ -0,0 +1,410 @@
+# Sample Workbench Walkthrough
+
+This directory contains a step-by-step walkthrough that demonstrates Workbench
+in action with real examples. Follow along to see the complete workflow from
+initialization to validation.
+
+## What You'll Learn
+
+- How to initialize a Workbench repository
+- Creating and managing work items
+- Writing structured documentation
+- Linking docs and work items
+- Validating your repository
+- GitHub integration basics
+
+## Prerequisites
+
+- Workbench installed (see [Getting Started](../../docs/00-overview/getting-started.md))
+- A test git repository (or use the steps below to create one)
+- Optional: GitHub CLI (`gh`) for GitHub integration features
+
+## Walkthrough Steps
+
+### Step 1: Create a test repository
+
+```bash
+# Create a new directory for testing
+mkdir workbench-demo
+cd workbench-demo
+
+# Initialize git
+git init
+git config user.name "Your Name"
+git config user.email "your.email@example.com"
+
+# Create initial commit
+echo "# Workbench Demo" > README.md
+git add README.md
+git commit -m "Initial commit"
+```
+
+### Step 2: Initialize Workbench
+
+Run the interactive initialization:
+
+```bash
+workbench init
+```
+
+When prompted:
+- **Scaffold default structure?** Yes
+- **Add front matter to existing docs?** Yes (if you have any)
+- **Configure OpenAI?** Skip (or configure if you have an API key)
+- **Credential storage location?** Local file (for demo purposes)
+- **Launch wizard after init?** Yes (or No if you prefer to follow manually)
+
+**What happened?**
+- Created `.workbench/config.json` with default settings
+- Created directory structure:
+  - `docs/00-overview/` through `docs/70-work/`
+  - `docs/70-work/items/` for active work items
+  - `docs/70-work/done/` for completed work items
+  - `docs/70-work/templates/` for work item templates
+- Created template files for bug, task, and spike work items
+- Added `.workbench/credentials.env` to `.gitignore` (if using local storage)
+
+### Step 3: Verify the setup
+
+Check that everything is configured correctly:
+
+```bash
+workbench doctor
+```
+
+You should see output indicating:
+- ✓ Git repository found
+- ✓ Configuration valid
+- ✓ Required directories exist
+- ⚠ GitHub provider (warning is OK if not configured)
+- ⚠ OpenAI credentials (warning is OK if not configured)
+
+### Step 4: Create your first work item
+
+Create a task to add a user guide:
+
+```bash
+workbench item new --type task \
+  --title "Create user guide for the API" \
+  --priority high \
+  --owner platform
+```
+
+**Result:** A new file is created at `docs/70-work/items/TASK-0001-create-user-guide-for-the-api.md`
+
+View the created work item:
+
+```bash
+workbench item show TASK-0001
+```
+
+Or open it directly:
+
+```bash
+cat docs/70-work/items/TASK-0001-create-user-guide-for-the-api.md
+```
+
+### Step 5: Create another work item
+
+Create a bug to fix:
+
+```bash
+workbench item new --type bug \
+  --title "Fix authentication timeout issue" \
+  --priority critical \
+  --status in-progress
+```
+
+**Result:** Creates `docs/70-work/items/BUG-0001-fix-authentication-timeout-issue.md`
+
+### Step 6: List your work items
+
+See all open work items:
+
+```bash
+workbench item list
+```
+
+Filter by type or status:
+
+```bash
+workbench item list --type task
+workbench item list --status in-progress
+```
+
+### Step 7: Create documentation
+
+Create a feature specification:
+
+```bash
+workbench doc new --type spec \
+  --title "API Authentication Flow" \
+  --work-item TASK-0001
+```
+
+This creates a spec document and automatically links it to `TASK-0001`.
+
+Create an architecture decision record:
+
+```bash
+workbench doc new --type adr \
+  --title "Use JWT tokens for API authentication"
+```
+
+### Step 8: Manually edit a work item
+
+Open `docs/70-work/items/TASK-0001-create-user-guide-for-the-api.md` and add content:
+
+```markdown
+## Summary
+
+Create comprehensive user documentation for the REST API, including authentication,
+endpoints, and code examples.
+
+## Acceptance criteria
+
+- [ ] Document all public API endpoints
+- [ ] Include authentication setup guide
+- [ ] Provide code examples in Python and JavaScript
+- [ ] Add troubleshooting section
+- [ ] Review with product team
+
+## Notes
+
+- Target audience: external developers
+- Should integrate with existing docs site
+```
+
+### Step 9: Link documents and work items
+
+Link the ADR to the bug work item:
+
+```bash
+workbench item link BUG-0001 \
+  --adr docs/40-decisions/use-jwt-tokens-for-api-authentication.md
+```
+
+View the updated work item to see the link:
+
+```bash
+workbench item show BUG-0001
+```
+
+### Step 10: Update work item status
+
+Mark the bug as ready for review:
+
+```bash
+workbench item status BUG-0001 done --note "Implemented JWT authentication with 30min timeout"
+```
+
+### Step 11: Sync navigation and indexes
+
+Update all navigation indexes in README files:
+
+```bash
+workbench nav sync
+```
+
+**What happened?**
+- Updated `docs/70-work/README.md` with a workboard table
+- Updated `docs/README.md` with doc indexes
+- Updated `README.md` in the repo root with work item stats
+
+Check the changes:
+
+```bash
+cat docs/70-work/README.md
+cat docs/README.md
+```
+
+### Step 12: Validate the repository
+
+Run validation to check for issues:
+
+```bash
+workbench validate
+```
+
+This checks:
+- Work item YAML front matter is valid
+- Document front matter is valid
+- Links between docs and work items are correct
+- No duplicate IDs
+- No broken internal links
+
+Fix any issues reported, then run again:
+
+```bash
+workbench validate --strict
+```
+
+In `--strict` mode, warnings become errors (useful for CI).
+
+### Step 13: Close a work item
+
+Mark the bug as done and move it to the done directory:
+
+```bash
+workbench item close BUG-0001 --move
+```
+
+**Result:** The file moves from `docs/70-work/items/` to `docs/70-work/done/`
+
+Verify by listing items with done items included:
+
+```bash
+workbench item list --include-done
+```
+
+### Step 14: Commit your work
+
+Review what was created:
+
+```bash
+git status
+```
+
+Commit the changes:
+
+```bash
+git add .
+git commit -m "Initialize Workbench and create sample work items"
+```
+
+## Advanced: GitHub Integration
+
+If you want to try GitHub integration, you'll need:
+
+1. A GitHub repository
+2. GitHub CLI authenticated (`gh auth login`)
+
+Then you can:
+
+### Create a work item with a branch and PR
+
+```bash
+workbench promote --type task \
+  --title "Add rate limiting to API" \
+  --start --pr --draft
+```
+
+This creates:
+- A work item (`TASK-0002` or next available ID)
+- A git branch (`work/TASK-0002-add-rate-limiting-to-api`)
+- An initial commit
+- A draft GitHub pull request
+- Links the PR to the work item
+
+### Import GitHub issues as work items
+
+```bash
+workbench item import --issue 42
+```
+
+### Sync work items with GitHub issues
+
+```bash
+workbench sync --items --issues
+```
+
+This syncs status and metadata between work items and GitHub issues.
+
+## Expected Directory Structure
+
+After completing this walkthrough, your repository should look like:
+
+```
+workbench-demo/
+├── .git/
+├── .gitignore
+├── .workbench/
+│   ├── config.json
+│   └── credentials.env (if using local storage)
+├── README.md
+└── docs/
+    ├── README.md
+    ├── 00-overview/
+    │   └── README.md
+    ├── 10-product/
+    │   ├── README.md
+    │   └── api-authentication-flow.md
+    ├── 20-architecture/
+    │   └── README.md
+    ├── 30-contracts/
+    │   └── README.md
+    ├── 40-decisions/
+    │   ├── README.md
+    │   └── use-jwt-tokens-for-api-authentication.md
+    ├── 50-runbooks/
+    │   └── README.md
+    ├── 60-tracking/
+    │   └── README.md
+    ├── 70-work/
+    │   ├── README.md
+    │   ├── items/
+    │   │   └── TASK-0001-create-user-guide-for-the-api.md
+    │   ├── done/
+    │   │   └── BUG-0001-fix-authentication-timeout-issue.md
+    │   └── templates/
+    │       ├── bug.md
+    │       ├── task.md
+    │       └── spike.md
+    └── templates/
+        ├── README.md
+        ├── adr.md
+        ├── contract.md
+        ├── feature-spec.md
+        └── runbook.md
+```
+
+## Common Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `workbench init` | Initialize Workbench in a repository |
+| `workbench doctor` | Verify configuration and environment |
+| `workbench item new` | Create a new work item |
+| `workbench item list` | List work items |
+| `workbench item show <ID>` | Show work item details |
+| `workbench item status <ID> <status>` | Update work item status |
+| `workbench item close <ID>` | Mark work item as done |
+| `workbench doc new` | Create a new document |
+| `workbench item link <ID>` | Link docs/PRs/issues to a work item |
+| `workbench nav sync` | Update navigation and indexes |
+| `workbench validate` | Validate work items, links, and schemas |
+| `workbench sync` | Full sync (items, docs, nav) |
+
+## Next Steps
+
+- **Read the [Getting Started guide](../../docs/00-overview/getting-started.md)** for more details
+- **Explore the [CLI reference](../../docs/30-contracts/cli-help.md)** for all commands
+- **Review [ADRs](../../docs/40-decisions/README.md)** to understand design decisions
+- **Try the voice features** if you have an OpenAI API key
+- **Integrate with your CI/CD** using `workbench validate --strict`
+
+## Troubleshooting
+
+### "Work item ID already exists"
+
+The ID counter is tracked in the file system. If you delete work items, the IDs
+won't be reused. This is by design to prevent ID conflicts.
+
+### "Invalid front matter"
+
+Check that your YAML front matter is valid. Use `workbench validate` to see
+specific errors.
+
+### "Link validation failed"
+
+Ensure all linked files exist and paths are correct. Use relative paths from the
+repository root (e.g., `docs/10-product/my-spec.md`).
+
+## Clean Up
+
+To remove the demo repository:
+
+```bash
+cd ..
+rm -rf workbench-demo
+```