Update docs

[MrHinsh]

This pull request introduces significant improvements to the documentation and configuration of the Scrum Guide Expansion Pack project. The main focus is on clarifying the site's architecture, restructuring content around a versioned guides model, and marking legacy content for backward compatibility. Updates also include enhanced guidance for AI assistants and improved documentation of the Hugo module-based template system.

Key changes include:

---

Content Architecture and Structure

• Refactored documentation (docs/architecture.md, docs/content-management.md) to describe a versioned guides model: each guide (core or extension) is a self-contained, version-controlled document supporting multiple languages and independent updates. Legacy creator content is now explicitly marked and separated. [1] [2] [3]
• Updated content structure examples and explanations to reflect the new organization, emphasizing core and extension guides, versioning, translation directories, and legacy content.

---

Legacy Content and Backward Compatibility

• Marked the creators/ section and related navigation/menu items as LEGACY throughout configuration and documentation, clarifying its backward compatibility status and that it is no longer actively maintained. [1] [2] [3] [4]

---

Hugo Module and Template Management

• Expanded documentation to explain the use of the Hugo Module system for template management, where base templates are imported from an external module (github.com/nkdAgility/HugoGuides/module), and local templates are only overrides or site-specific.
• Updated the site architecture documentation to show the new layouts and template hierarchy under the Hugo module approach.

---

AI Assistant Guidance

• Added explicit guidance and links for AI assistants in the project documentation (docs/README.md), directing them to a dedicated agent guide for working with the codebase.

---

Workflow and Codeowners Updates

• Updated .github/CODEOWNERS to reflect the new content structure, assigning owners to new extension guide directories and clarifying ownership for legacy and new sections.
• Added warnings and comments to the Azure Static Web Apps workflow file, marking it as deprecated and not to be edited or enabled.
• Minor formatting and consistency changes in workflow YAML files.

These changes collectively modernize the project's documentation and configuration, making the structure clearer for contributors, maintainers, and automated tools.

---

This change is 

[github-actions]

Azure Static Web Apps: Your stage site is ready! Visit it here: https://agreeable-island-0c966e810-333.centralus.6.azurestaticapps.net

[Copilot]

Pull request overview

This pull request comprehensively modernizes the project's documentation and configuration to support a versioned guides architecture. The changes introduce a clear content structure where each guide (core or extension) is self-contained with version control, multilingual support, and independent update cycles. Legacy creator content is explicitly marked for backward compatibility while new content follows the versioned model.

Changes:

• Introduced versioned guides model with clear documentation of core guide vs extension guides architecture
• Added comprehensive AI assistant guide (agents.md) with detailed deployment workflow, task instructions, and safety warnings
• Marked legacy content (creators/) throughout configuration and documentation for backward compatibility
• Documented Hugo Module system for template management, clarifying that base templates come from external module
• Enhanced contributor guidance with detailed workflows for common tasks (adding guides, translations, PDFs, contributors)

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
readme.md	Expanded contribution instructions with 10 common tasks, translation guidelines, and admin workflows
docs/troubleshooting.md	Minor formatting improvements (blank line additions)
docs/translations.md	Updated to reflect versioned guide structure with legacy content notation
docs/simple-pdf-generation.md	Expanded PDF script documentation with versioned guides support, parameters, and output examples
docs/getting-started.md	Updated project structure to show versioned guides, Hugo module architecture, and extended guide list
docs/development.md	Documented Hugo module system, clarified template structure, updated deployment environment descriptions
docs/deployment.md	Clarified deployment workflow with semantic versioning, added environment tables, workflow descriptions, and decision guides
docs/content-management.md	Introduced versioned guides model, documented contributor attribution system with githubUsername preference
docs/configuration.md	Added legacy markers to creators menu items and routes
docs/architecture.md	Documented Hugo module system, versioned guides architecture, and local vs module template structure
docs/README.md	Added link to new AI agent guide
agents.md	New file: Comprehensive 712-line AI assistant guide with deployment model, workflows, tasks, and warnings
.github/workflows/azure-static-web-apps-agreeable-island-0c966e810.yml	Added prominent warnings marking workflow as deprecated/legacy (DO NOT USE)
.github/copilot-instructions.md	Refactored to reference agents.md as primary AI guide, condensed to quick reference format
.github/CODEOWNERS	Updated ownership structure to reflect versioned extension guides instead of old structure

Comments suppressed due to low confidence (3)

.github/workflows/azure-static-web-apps-agreeable-island-0c966e810.yml:90

• The workflow file contains duplicate content. Lines 1-48 define a complete workflow, and then lines 49-90+ appear to define the same workflow again with slightly different configuration. This creates invalid YAML with two name: keys and two on: keys at the same level. The file should only contain one workflow definition. Based on the warning comments at the top stating this is a legacy/deprecated workflow, the entire duplicate section (lines 49 onwards) should be removed.

name: Azure Static Web Apps CI/CD

on:
  workflow_dispatch:
    inputs:
      branch:
        description: "Branch to deploy"
        required: false
        default: "main"

jobs:
  build_and_deploy_job:
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: true
          lfs: false

      - name: Setup Hugo
        uses: peaceiris/actions-hugo@v3
        with:
          hugo-version: "0.146.0"
          extended: true

      - name: Build Hugo site
        run: hugo --minify --environment production
        working-directory: ./site

      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_AGREEABLE_ISLAND_0C966E810 }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          action: "upload"
          app_location: "./site"
          api_location: ""
          output_location: "public"
          skip_app_build: true

docs/architecture.md:211

• The "Key Templates" section lists templates without clarifying which are module-provided vs. local overrides. Based on the earlier documentation in this file (line 180), baseof.html, home.html, single.html, and list.html come from the Hugo module, not local layouts. Consider adding a note or reorganizing this section to clarify: "Module-Provided Templates (from HugoGuides):" followed by the list, to avoid confusion.

### Key Templates

- **`baseof.html`** - Base template with common HTML structure
- **`home.html`** - Homepage template (renamed from `index.html`)
- **`single.html`** - Individual page template
- **`list.html`** - List/index page template
- **`all.html`** - New catch-all template for any page type

docs/deployment.md:505

• Duplicate "Post-deployment Checklist" sections. The same checklist appears at lines 476-483 and again at lines 498-505 with identical content. One of these duplicate sections should be removed to avoid confusion and maintain cleaner documentation.

### Post-deployment Checklist

- ✅ **Verify site loads** correctly
- ✅ **Check all languages** work
- ✅ **Test download links** and PDFs
- ✅ **Monitor performance** metrics
- ✅ **Check analytics** tracking
- ✅ **Validate SEO** elements

[Copilot]

Inconsistent placeholder naming for PR numbers across documentation. This file uses {PR#} while docs/deployment.md and other documentation files use {PullRequestId} for the same concept. For consistency, consider using {PullRequestId} throughout all documentation files.

Suggested change

	2. Visit PR preview site: `https://agreeable-island-0c966e810-{PR#}.centralus.6.azurestaticapps.net`
	- Replace `{PR#}` with the actual PR number (e.g., PR #42 → `...810-42.centralus...`)
	2. Visit PR preview site: `https://agreeable-island-0c966e810-{PullRequestId}.centralus.6.azurestaticapps.net`
	- Replace `{PullRequestId}` with the actual PR number (e.g., PR #42 → `...810-42.centralus...`)

[Copilot]

Inconsistent capitalization of front matter keys. Line 72 uses Type: "guide" and line 73 uses Layout: "root" (both capitalized), while the version content example below uses lowercase type: guide (line 106). Hugo is case-sensitive for front matter keys, so this inconsistency could cause issues. Verify the correct capitalization and ensure consistency across all examples.

Suggested change

	Type: "guide"
	Layout: "root"
	type: "guide"
	layout: "root"

[Copilot]

Missing code owners for /site/content/software-engineering-practices/. Line 42 defines the path but has no owners assigned (no @username following it). This should either have owners assigned or be removed if ownership is intentionally unassigned.

Suggested change

	/site/content/software-engineering-practices/
	/site/content/software-engineering-practices/ @ViralGoodAgile @rjocham

[Copilot]

The directory name contains a spelling error: "depoyment" should be "deployment". While the CODEOWNERS entry correctly matches the existing directory name, both the directory /site/content/emergent-strategy-and-depoyment/ and this CODEOWNERS entry have the same typo. Consider renaming the directory to emergent-strategy-and-deployment and updating this entry accordingly in a future PR.

Suggested change

	/site/content/emergent-strategy-and-depoyment/ @Tom-Gilb
	/site/content/emergent-strategy-and-deployment/ @Tom-Gilb

[Copilot]

Inconsistent placeholder naming for PR numbers. The file uses both {PullRequestId} (line 57) and {PR#} (line 462) to represent the same concept. For consistency with the rest of the documentation (docs/deployment.md uses {PullRequestId}), this should use {PullRequestId} throughout, or at minimum be consistent within the same file.

Suggested change

	2. Visit PR preview site: `https://agreeable-island-0c966e810-{PR#}.centralus.6.azurestaticapps.net`
	- Replace `{PR#}` with the actual PR number
	2. Visit PR preview site: `https://agreeable-island-0c966e810-{PullRequestId}.centralus.6.azurestaticapps.net`
	- Replace `{PullRequestId}` with the actual PR number

[Copilot]

Spelling inconsistency with directory name. Line 209 lists emergent-strategy-and-deployment but the actual directory is named emergent-strategy-and-depoyment (with "depoyment" spelled incorrectly). This documentation should match the actual directory name, or the directory should be renamed and this documentation would then be correct.

Suggested change

	- `complexity`, `psychological-safety-in-scrum-teams`, `adaptive-enterprise`, `adaptive-executive`, `ai-and-scrum`, `emergent-strategy-and-deployment`, `holistic-testing`, `multi-team-scrum`, `operating-models`, `planguage`, `product-thinking`, `software-engineering-practices`, `strategy-as-an-empirical-capability`, `scrum-on-one-page` (Extension Guides)
	- `complexity`, `psychological-safety-in-scrum-teams`, `adaptive-enterprise`, `adaptive-executive`, `ai-and-scrum`, `emergent-strategy-and-depoyment`, `holistic-testing`, `multi-team-scrum`, `operating-models`, `planguage`, `product-thinking`, `software-engineering-practices`, `strategy-as-an-empirical-capability`, `scrum-on-one-page` (Extension Guides)

[Copilot]

Inconsistent placeholder naming for PR numbers. This file uses {PR-NUMBER} while other documentation files use {PullRequestId}. For consistency across all documentation, use the same placeholder format (preferably {PullRequestId} which matches docs/deployment.md and other files).

Suggested change

	- **Canary**: [agreeable-island-0c966e810-{PR-NUMBER}.centralus.6.azurestaticapps.net](https://agreeable-island-0c966e810-{PR-NUMBER}.centralus.6.azurestaticapps.net/) - **Test environment with latest changes in the PR - Deleted after PR closed**
	- **Canary**: [agreeable-island-0c966e810-{PullRequestId}.centralus.6.azurestaticapps.net](https://agreeable-island-0c966e810-{PullRequestId}.centralus.6.azurestaticapps.net/) - **Test environment with latest changes in the PR - Deleted after PR closed**