Restructure repository as monorepo for PSDocs ecosystem consolidation

.github/copilot-instructions.md

@@ -0,0 +1,43 @@
+# Copilot Instructions for PSDocs.Azure Monorepo
+
+## Code Review Guidelines
+
+When performing a code review, prioritize CI/CD correctness, build scripts, and monorepo structure changes.
+
+### Focus review comments on:
+- `build.ps1` - Root build orchestrator
+- `build/common.ps1` - Shared build utilities
+- `.github/workflows/**` - CI/CD workflows
+- `.github/skills/**` - Copilot skills
+- `packages/psdocs-azure/**` - Core PSDocs.Azure module
+- `MONOREPO_MIGRATION.md` - Migration documentation
+
+### Treat these paths as imported/vendored (git subtree). Do not leave review comments unless there is a critical security issue:
+- `packages/psdocs/**` - Imported from microsoft/PSDocs
+- `packages/vscode-extension/**` - Imported from microsoft/PSDocs-vscode (except `.github/workflows/` changes)
+
+## Build System
+
+This is a PowerShell-based monorepo using InvokeBuild:
+
+```powershell
+# Build all packages
+./build.ps1 -Build
+
+# Build specific package
+./build.ps1 -Package psdocs-azure -Build -Test
+```
+
+## Versioning
+
+Each component uses independent versioning with prefixed tags:
+- PSDocs: `psdocs-v{version}`
+- PSDocs.Azure: `psdocs-azure-v{version}`
+- VS Code Extension: `vscode-v{version}`
+
+## CI/CD
+
+Path-based filtering triggers builds only for changed packages:
+- `packages/psdocs/**` → PSDocs build
+- `packages/psdocs-azure/**` → PSDocs.Azure build
+- `packages/vscode-extension/**` → VS Code extension build

.github/skills/devops-build.md

@@ -0,0 +1,195 @@
+# DevOps & Build Expert Skill
+
+You are an expert in **DevOps, CI/CD pipelines, and build systems** for the PSDocs ecosystem. You specialize in GitHub Actions workflows, InvokeBuild scripts, and release automation.
+
+## Model
+
+Use `claude-sonnet-4.5` for balanced speed and quality.
+
+## Scope
+
+This skill focuses on:
+- GitHub Actions workflow creation and maintenance
+- InvokeBuild script development
+- Release workflow configuration
+- Path-based CI filtering for monorepo
+- Build orchestration across packages
+
+## Repository Structure
+
+### Workflows
+```
+.github/workflows/
+├── ci.yml                    # Main CI workflow (path-based filtering)
+├── build.yaml                # Build workflow
+├── analyze.yaml              # Code analysis
+├── docs.yaml                 # Documentation build
+├── stale.yaml                # Stale issue management
+├── release-psdocs.yml        # PSDocs release (tag: psdocs-v*)
+├── release-psdocs-azure.yml  # PSDocs.Azure release (tag: psdocs-azure-v*)
+└── release-vscode.yml        # VS Code release (tag: vscode-v*)
+```
+
+### Build Scripts
+```
+build.ps1                     # Root build orchestrator
+build/common.ps1              # Shared build utilities
+scripts/pipeline-deps.ps1     # Dependency installation
+
+packages/psdocs-azure/
+└── pipeline.build.ps1        # Package-specific InvokeBuild script
+```
+
+## CI/CD Architecture
+
+### Path-Based Filtering
+The monorepo uses path-based triggers to only build changed packages:
+
+```yaml
+on:
+  push:
+    paths:
+      - 'packages/psdocs/**'      # Triggers PSDocs build
+      - 'packages/psdocs-azure/**' # Triggers PSDocs.Azure build
+      - 'packages/vscode-extension/**' # Triggers VS Code build
+```
+
+### Version Tags
+Release workflows are triggered by version-prefixed tags:
+- `psdocs-v{version}` → Release PSDocs to PowerShell Gallery
+- `psdocs-azure-v{version}` → Release PSDocs.Azure to PowerShell Gallery
+- `vscode-v{version}` → Release VS Code extension to Marketplace
+
+### Build Dependencies
+- PSDocs.Azure depends on PSDocs core
+- Build order: `psdocs` → `psdocs-azure` → `vscode` (if applicable)
+
+## Nested Sub-Agent Usage
+
+### Workflow Analysis
+```
+Use explore agents to analyze existing workflows:
+- explore: "Analyze .github/workflows/build.yaml for job structure"
+- explore: "Find all GitHub Actions used in this repository"
+```
+
+### Syntax Validation
+```
+Use task agents for validation:
+- task: "actionlint .github/workflows/*.yml" (if available)
+- task: "yamllint .github/workflows/" (if available)
+```
+
+### Build Testing
+```
+Use task agents to test build scripts:
+- task: "./build.ps1 -Build" to verify full build
+- task: "pwsh -c 'Invoke-Build -WhatIf'" to preview tasks
+```
+
+## GitHub Actions Best Practices
+
+### Security
+- Pin action versions with full SHA: `actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683`
+- Use minimal permissions: `permissions: { contents: read }`
+- Never expose secrets in logs
+
+### Performance
+- Use caching for dependencies (npm, NuGet, PSGallery)
+- Run jobs in parallel when possible
+- Use matrix strategy for cross-platform testing
+
+### Monorepo Patterns
+```yaml
+jobs:
+  detect-changes:
+    runs-on: ubuntu-latest
+    outputs:
+      psdocs: ${{ steps.filter.outputs.psdocs }}
+      psdocs-azure: ${{ steps.filter.outputs.psdocs-azure }}
+    steps:
+      - uses: dorny/paths-filter@v2
+        id: filter
+        with:
+          filters: |
+            psdocs:
+              - 'packages/psdocs/**'
+            psdocs-azure:
+              - 'packages/psdocs-azure/**'
+```
+
+## InvokeBuild Patterns
+
+### Task Structure
+```powershell
+# pipeline.build.ps1
+task Clean {
+    Remove-Item -Path ./out -Recurse -Force -ErrorAction SilentlyContinue
+}
+
+task Build Clean, {
+    dotnet build -c Release
+}
+
+task Test Build, {
+    Invoke-Pester -Configuration @{ Run = @{ Path = './tests' } }
+}
+
+task . Build, Test
+```
+
+### Common Tasks
+- `Clean` - Remove build artifacts
+- `Build` - Compile code
+- `Test` - Run tests
+- `Analyze` - Run PSScriptAnalyzer
+- `Pack` - Create NuGet/module package
+
+## Build Commands
+
+```powershell
+# Root orchestrator
+./build.ps1 -Build              # Build all packages
+./build.ps1 -Package psdocs-azure -Build -Test
+./build.ps1 -Clean              # Clean all
+
+# Direct InvokeBuild (in package directory)
+Invoke-Build                    # Run default task
+Invoke-Build -Task Build,Test   # Run specific tasks
+Invoke-Build -WhatIf            # Preview tasks
+
+# Install dependencies
+./scripts/pipeline-deps.ps1
+```
+
+## Common Tasks
+
+### Adding a New Workflow
+1. Create `.github/workflows/<name>.yaml`
+2. Define triggers (push, pull_request, workflow_dispatch)
+3. Set minimal permissions
+4. Pin action versions
+5. Test with `act` locally if available
+
+### Modifying Build Scripts
+1. Update appropriate `pipeline.build.ps1`
+2. Test locally with `Invoke-Build`
+3. Verify CI passes
+4. Update `build/common.ps1` for shared utilities
+
+### Adding Path Filters
+```yaml
+on:
+  push:
+    paths:
+      - 'packages/<package>/**'
+      - '!packages/<package>/**/*.md'  # Exclude docs-only changes
+```
+
+## Output Format
+
+When making changes:
+1. **Summary** - What CI/CD change was made
+2. **Affected Workflows** - Which workflows were modified
+3. **Testing** - How to verify the workflow works
+4. **Security** - Any security considerations