Add documentation for GitHub Copilot coding agent

This document serves as the primary reference for GitHub Copilot when assisting with contributions to the Layer5 Documentation site. It outlines AI model selection, project overview, technology stack, core principles, development workflow, content guidelines, and more.

Signed-off-by: Lee Calcote <lee.calcote@layer5.io>

Author: leecalcote

.github/agents/documentation.agent.md

@@ -0,0 +1,317 @@
+# GitHub Copilot Custom Coding Agent Instructions
+
+## AI Model Selection
+
+**IMPORTANT**: When using GitHub Copilot, always select the most powerful AI model available (e.g., GPT-4, Claude 3.5 Sonnet, or the latest advanced model) for code generation, review, and assistance tasks. More powerful models provide better code quality, deeper understanding of context, and more accurate suggestions aligned with project standards.
+
+## Project Overview
+
+The Layer5 Docs website is a Hugo-based documentation site that serves as the primary documentation resource for Layer5 products, hosted at https://github.com/layer5io/docs and live at https://docs.layer5.io. It provides comprehensive documentation for Layer5 Cloud, Kanvas, and related products, offering tutorials, guides, and reference materials for users and contributors in the cloud native ecosystem.
+
+## Technology Stack
+
+- **Framework**: Hugo (extended version with SCSS support)
+- **Theme**: Docsy (Google's documentation theme)
+- **Language**: Go templates, HTML, CSS/SCSS, JavaScript
+- **Content**: Markdown with Hugo shortcodes
+- **Package Manager**: npm
+- **Node Version**: See `.nvmrc`
+- **Build System**: Hugo CLI, Make
+
+## Core Principles
+
+### 1. Minimal, Surgical Changes
+- Make the **smallest possible changes** to accomplish the goal
+- Never delete or modify working code unless absolutely necessary
+- Focus on precise, targeted modifications rather than wholesale rewrites
+- Preserve existing patterns and conventions unless explicitly changing them
+
+### 2. Code Quality Standards
+- Follow the existing code style and patterns in the repository
+- Ensure proper indentation and formatting in templates and content
+- Write clean, readable, self-documenting code with minimal comments unless necessary for complex logic
+- Maintain accessibility standards (WCAG 2.1)
+
+### 3. Testing and Validation
+- Always validate changes work before considering them complete
+- Build the site and verify rendered content: `make build` or `hugo`
+- Run the site locally: `make site` or `hugo server -D -F`
+- Test changes incrementally and iteratively
+
+## Project Structure
+
+```
+docs/
+├── .github/                 # GitHub configuration and workflows
+├── assets/                  # Site assets (CSS, JS, images)
+├── charts/                  # Chart files
+├── content/
+│   └── en/                 # English content
+│       ├── cloud/          # Layer5 Cloud documentation
+│       ├── kanvas/         # Kanvas documentation
+│       ├── contributing/   # Contribution guidelines
+│       └── videos/         # Video content
+├── data/                   # Hugo data files
+├── layouts/                # Hugo templates and layouts
+│   ├── _default/           # Default layouts
+│   ├── partials/           # Partial templates
+│   └── shortcodes/         # Custom shortcodes
+├── static/                 # Static assets
+├── hugo.toml               # Hugo configuration
+├── package.json            # npm dependencies
+├── Makefile                # Build automation
+└── CONTRIBUTING.md         # Contribution guidelines
+```
+
+## Development Workflow
+
+1. Create a branch and pull request in this repo. 
+2. Don't fork this repo.
+
+### Setup
+```bash
+# Install dependencies (required for fresh clone)
+make setup
+# or
+npm install
+```
+
+### Development
+```bash
+# Start development server with drafts and future content
+make site
+# or
+hugo server -D -F
+```
+
+### Building
+```bash
+# Build for production
+make build
+# or
+hugo
+
+# Clean and rebuild
+make clean
+```
+
+### Docker Development
+```bash
+# Run with Docker (requires Docker Desktop 4.24+ or Docker Compose 2.22+)
+make docker
+```
+
+## Content Guidelines
+
+### Tone and Style
+- Use a **professional yet approachable** tone
+- Content should be clear, concise, and welcoming to both technical and non-technical audiences
+- Align with Layer5's mission of empowering engineers to "expect more from their infrastructure"
+- Use American English spelling and grammar
+
+### Markdown Content
+- All documentation content is written in Markdown
+- Place content files in appropriate directories under `content/en/`
+- Include proper frontmatter with metadata:
+
+```yaml
+---
+title: "Page Title"
+description: "Short description for SEO (150-160 chars)"
+weight: 10  # Optional: controls ordering in navigation
+---
+```
+
+### Hugo Shortcodes
+Use the project's custom shortcodes for enhanced content:
+
+```markdown
+{{< alert type="success" title="Note" >}} Your Note {{< /alert >}}
+```
+
+Alert types:
+- `type="danger"`: Critical alerts (security-related or breaking changes)
+- `type="info"`: General informational content
+- `type="warning"`: Important warnings that need attention
+- `type="note"`: Neutral notes and tips
+- `type="success"`: Positive outcomes or confirmations
+
+### Image Guidelines
+- Use the following syntax: `![alt text](/path/to/image.svg)` or `<img src="" alt="" />`
+- Always provide complete image paths for subpages
+- Add `data-modal="false"` to prevent images from opening in a modal
+- Always include descriptive alt text for accessibility and SEO
+
+### Content Restrictions
+- **No external images**: Use local assets only
+- **No placeholder text**: Provide complete, production-ready content
+- **No sensitive data**: Never include API keys, credentials, or personal information
+- **Use proper terminology**: "Meshery" not "meshery", "Kanvas" not "canvas", "Layer5" not "layer5"
+
+## Template Guidelines
+
+### Hugo Templates
+- Follow Go template syntax conventions
+- Use partials for reusable template components
+- Maintain consistent indentation in templates
+- Use Hugo's built-in functions when possible
+
+### Styling
+- SCSS files are located in `assets/`
+- Follow existing CSS class naming conventions
+- Ensure responsive design is maintained
+- Use theme variables when possible
+
+## Accessibility
+
+**Required Standards**: WCAG 2.1 Level AA
+
+- **Images**: Always include descriptive `alt` text
+- **Interactive elements**: Ensure keyboard navigation support
+- **ARIA labels**: Use when semantic HTML is insufficient
+- **Color contrast**: Maintain at least 4.5:1 ratio for text
+- **Semantic HTML**: Use appropriate HTML5 elements
+
+## Git Workflow
+
+### Commit Messages
+Follow Conventional Commits format:
+
+```
+<type>(<scope>): <subject>
+```
+
+**Types**:
+- `feat`: New feature or content
+- `fix`: Bug fix or correction
+- `docs`: Documentation changes
+- `style`: Formatting changes (no logic change)
+- `refactor`: Code refactoring
+- `chore`: Build process, tooling, dependencies
+
+**Examples**:
+```
+feat(cloud): add workspace documentation
+fix(kanvas): correct broken link in navigation
+docs(contributing): update setup instructions
+```
+
+### Pull Requests
+- Submit all changes as PRs to the `master` branch
+- Reference related issues in PR description
+- Ensure CI checks pass before requesting review
+- Sign-off commits with `git commit -s`
+
+### Branch Naming
+Use descriptive, kebab-case names:
+- `feat/add-cloud-security-docs`
+- `fix/navigation-broken-link`
+- `docs/update-contributing-guide`
+
+## Troubleshooting
+
+### Build Errors
+- Check `hugo.toml` for configuration issues
+- Clear cache: `hugo --cleanDestinationDir`
+- Reinstall dependencies: `rm -rf node_modules && npm install`
+- Verify Hugo extended version is installed
+
+### Content Issues
+- Validate Markdown syntax and frontmatter
+- Check for unclosed shortcodes
+- Verify file paths are correct and case-sensitive
+
+### Development Server Issues
+- Ensure Go is installed (required): `go version`
+- Check Node.js version matches `.nvmrc`
+- Verify Hugo extended version is installed
+
+## Security Best Practices
+
+- Never commit secrets, API keys, or credentials
+- Use environment variables for sensitive configuration
+- Keep dependencies up to date
+- Follow CSP headers and security configurations
+
+## Community and Resources
+
+### Documentation
+- Layer5 Community Handbook: https://layer5.io/community/handbook
+- Meshery Documentation: https://docs.meshery.io
+- Hugo Documentation: https://gohugo.io/documentation/
+
+### Getting Help
+- Layer5 Slack: https://slack.layer5.io
+- Discussion Forum: https://discuss.layer5.io
+- GitHub Issues: https://github.com/layer5io/docs/issues
+
+### Code of Conduct
+All contributions must adhere to the [Layer5 Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Summary Checklist for Contributions
+
+Before submitting a PR, verify:
+
+### Content Quality
+- [ ] Content is clear, accurate, and complete
+- [ ] Proper frontmatter is included
+- [ ] Images have descriptive alt text
+- [ ] Links are valid and accessible
+- [ ] Terminology is correct (Meshery, Kanvas, Layer5)
+- [ ] American English spelling and grammar
+
+### Technical Quality
+- [ ] Build completes successfully (`make build`)
+- [ ] Site renders correctly locally (`make site`)
+- [ ] Changes are minimal and surgical
+- [ ] No placeholder content or sensitive data
+- [ ] Responsive design is maintained
+
+### Accessibility
+- [ ] All images have alt text
+- [ ] Proper heading hierarchy
+- [ ] Keyboard navigation works
+- [ ] Color contrast meets WCAG standards
+
+### Git
+- [ ] Commit messages follow Conventional Commits
+- [ ] Commits are signed off (`git commit -s`)
+- [ ] PR references related issues
+
+## Example Documentation Page
+
+```markdown
+---
+title: "Getting Started with Layer5 Cloud"
+description: "Learn how to set up your Layer5 Cloud account and start managing your cloud native infrastructure with ease."
+weight: 1
+---
+
+# Getting Started with Layer5 Cloud
+
+This guide walks you through setting up your Layer5 Cloud account and exploring key features.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+- A GitHub or Google account for authentication
+- Basic familiarity with cloud native concepts
+
+## Creating Your Account
+
+1. Visit [Layer5 Cloud](https://cloud.layer5.io)
+2. Click **Sign Up** and choose your authentication method
+3. Complete your profile setup
+
+{{< alert type="info" title="Tip" >}}
+You can link multiple authentication providers to a single account.
+{{< /alert >}}
+
+## Next Steps
+
+- [Explore Workspaces](/cloud/spaces/workspaces/)
+- [Learn about Organizations](/cloud/identity/organizations/)
+- [Set up API Tokens](/cloud/security/tokens/)
+```
+
+This document serves as the primary reference for GitHub Copilot when assisting with contributions to the Layer5 Documentation site. Always prioritize minimal changes, maintain existing patterns, and ensure quality through building and testing.