docs: improve operator onboarding runbooks

README.md

@@ -28,6 +28,25 @@ Write agentic workflows in natural language markdown, and run them in GitHub Act
 
 Ready to get your first agentic workflow running? Follow our step-by-step [Quick Start Guide](https://github.github.com/gh-aw/setup/quick-start/) to install the extension, add a sample workflow, and see it in action.
 
+## Local Repository Runbook
+
+For contributors working in this repository:
+
+```bash
+make deps-dev
+make build
+make test
+make lint
+```
+
+For docs development:
+
+```bash
+make dev-docs
+```
+
+This starts the docs site at `http://localhost:4321`. For a production docs build, run `make build-docs`.
+
 ## Overview
 
 Learn about the concepts behind agentic workflows, explore available workflow types, and understand how AI can automate your repository tasks. See [How It Works](https://github.github.com/gh-aw/introduction/how-they-work/).

docs/README.md

@@ -1,41 +1,48 @@
-# Startlight Docs
-
-## Project Structure
-
-Inside of your Astro + Starlight project, you'll see the following folders and files:
-
-```text
-.
-├── public/
-├── src/
-│   ├── assets/
-│   ├── content/
-│   │   └── docs/
-│   └── content.config.ts
-├── astro.config.mjs
-├── package.json
-└── tsconfig.json
+# gh-aw Documentation Workspace
+
+This directory contains the Astro/Starlight site for GitHub Agentic Workflows docs.
+
+## Operator Quick Start
+
+Run all commands from the repository root:
+
+```bash
+make deps-docs
+make dev-docs
+```
+
+Then open `http://localhost:4321`.
+
+## Build and Preview
+
+```bash
+make build-docs
+make preview-docs
 ```
 
-Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+`build-docs` writes the static site to `docs/dist`.
 
-Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+## Where To Edit Content
 
-Static assets, like favicons, can be placed in the `public/` directory.
+- Main docs pages: `docs/src/content/docs/`
+- Blog pages: `docs/src/content/docs/blog/`
+- Public static assets: `docs/public/`
+- Starlight config: `docs/astro.config.mjs`
 
-## 🧞 Commands
+## Suggested Validation Before PR
 
-All commands are run from the root of the project, from a terminal:
+From repository root:
+
+```bash
+make lint
+make test
+make build-docs
+```
 
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `npm install`             | Installs dependencies                            |
-| `npm run dev`             | Starts local dev server at `localhost:4321`      |
-| `npm run build`           | Build your production site to `./dist/`          |
-| `npm run preview`         | Preview your build locally, before deploying     |
-| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `npm run astro -- --help` | Get help using the Astro CLI                     |
+For a docs-only change, this keeps checks aligned with repo standards while confirming docs compile.
 
-## Want to learn more?
+## Troubleshooting
 
-Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
+- Reinstall docs dependencies: `make deps-docs`
+- Remove docs build artifacts: `make clean-docs`
+- If Astro dev fails after dependency updates, rerun `make deps-docs` and then `make dev-docs`

install.md

@@ -30,7 +30,7 @@ You should see version information displayed. If you encounter an error, check t
 
 - GitHub CLI (`gh`) is installed and authenticated
 - The installation script completed without errors
-- `~/.local/share/gh/extensions` is in your PATH
+- The extension appears in `gh extension list`
 
 ## Step 2: Initialize Repository for Agentic Workflows
 
@@ -58,6 +58,7 @@ Check what files were created:
 
 ```bash
 git status
+git diff --stat
 ```
 
 You should see new/modified files including:
@@ -69,24 +70,28 @@ You should see new/modified files including:
 - `.vscode/mcp.json`
 - And several other configuration files
 
-## Step 4: Commit and Push Changes
+## Step 4: Commit on a Branch and Open a PR
 
-Commit the initialization changes:
+Use a dedicated branch and avoid blanket staging:
 
 ```bash
-git add .
+git switch -c chore/init-gh-aw
+git add .gitattributes
+git add .github/aw .github/agents .github/workflows/copilot-setup-steps.yml
+git add .vscode/settings.json .vscode/mcp.json
 git commit -m "Initialize repository for GitHub Agentic Workflows"
-git push
+git push -u origin chore/init-gh-aw
+gh pr create --fill
 ```
 
-If there is branch protection on the default branch, create a pull request instead and report the link to the pull request.
+If your org requires a custom PR template or labels, add those during `gh pr create`.
 
 ## Troubleshooting
 
 ### Installation fails
 
 - **Issue**: `gh aw version` shows "unknown command"
-- **Solution**: Verify GitHub CLI is installed with `gh --version`, then re-run the installation script
+- **Solution**: Verify GitHub CLI is installed with `gh --version`, run `gh extension list`, and then re-run the installation script if `aw` is missing
 
 ### Missing authentication
 
@@ -103,7 +108,7 @@ If there is branch protection on the default branch, create a pull request inste
 After successful initialization, the user can:
 
 - **Add workflows from repos**: `gh aw add githubnext/agentics`
-- **Create new workflows**: `gh aw new <workflow-name>` os using the agent
+- **Create new workflows**: `gh aw new <workflow-name>` or using the agent
 - **Use the AI agent**: Type `/agent` in GitHub Copilot Chat and select `agentic-workflows`
 - **Read documentation**: View `.github/aw/github-agentic-workflows.md`