Add comprehensive GitHub Copilot instructions for static documentation site

.github/copilot-instructions.md

@@ -0,0 +1,161 @@
+# UIS Automation GitHub Pages Documentation Site
+
+Always reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.
+
+This is a static GitHub Pages documentation site that serves pre-built React component documentation using React Styleguidist. The site showcases University of Cambridge UI Automation components including AppBar, NavigationPanel, and related navigation components.
+
+## Critical Understanding
+
+**THIS IS A DEPLOYMENT REPOSITORY, NOT A SOURCE REPOSITORY**
+- Contains only pre-built, compiled JavaScript bundles and static assets
+- No source code, package.json, build scripts, or development dependencies
+- Changes to components must be made in the source repository, not here
+- This repository only contains the built documentation output
+
+## Working Effectively
+
+### Serving the Site Locally
+- `cd /home/runner/work/uisautomation.github.io/uisautomation.github.io` - Navigate to repository root
+- `python3 -m http.server 8000` - Start local HTTP server. Takes ~2 seconds to start. NEVER CANCEL.
+- Access site at `http://localhost:8000`
+- Stop server with `pkill -f "python3 -m http.server"` when done
+
+### No Build Process Required
+- **DO NOT** try to run `npm install`, `npm run build`, or any build commands
+- **DO NOT** look for package.json, webpack config, or build scripts - they don't exist
+- The site is already compiled and ready to serve
+
+### Repository Structure
+- `index.html` - Main documentation page entry point
+- `build/` - Contains compiled JavaScript bundles (main.js, bundle.js, etc.)
+- `asset-manifest.json` - Maps logical names to hashed bundle filenames
+- `service-worker.js` - Provides offline functionality
+- `precache-manifest.*.js` - Service worker precache configuration
+- `.nojekyll` - Tells GitHub Pages to serve files as-is without Jekyll processing
+
+## Validation Scenarios
+
+**ALWAYS** manually validate the site functionality using these comprehensive scenarios after making any changes:
+
+### Basic Site Functionality (Required)
+1. **Start local server**: `python3 -m http.server 8000` (takes ~2 seconds)
+2. **Navigate to site**: Open `http://localhost:8000` in browser
+3. **Verify page loads**: Check title is "Documentation Style Guide"
+4. **Verify components list**: Confirm sidebar shows all 10 components (AppBar through NavigationPanelSectionLink)
+
+### Interactive Features Testing (Required)
+1. **Test component navigation**: Click on "NavigationPanel" in sidebar - should scroll to that section
+2. **Test component filtering**: Type "Avatar" in "Filter by name" box - should show only NavigationPanelAvatar
+3. **Test isolated view**: Click "Open isolated" link for any component - should open component in isolated view
+4. **Test code examples**: Verify "View Code" buttons expand/collapse code examples
+5. **Test external links**: Verify links to UIS DevOps and other external sites are present and clickable
+
+### Content Validation (Required)
+1. **Verify all 10 components present**:
+   - AppBar
+   - ChooseColumnsDialog
+   - NavigationPanel
+   - NavigationPanelAvatar
+   - NavigationPanelFooter
+   - NavigationPanelFooterLink
+   - NavigationPanelLogo
+   - NavigationPanelSection
+   - NavigationPanelSectionAnchor
+   - NavigationPanelSectionLink
+
+2. **Verify component examples render**: Each component should show visual examples with interactive elements
+3. **Verify service worker**: Check browser developer tools - should show service worker registered
+4. **Verify React Styleguidist attribution**: Footer should show "Created with React Styleguidist"
+
+### Performance and Error Validation (Required)
+1. **Check console for errors**: Open browser developer tools - should have no critical JavaScript errors
+2. **Verify offline functionality**: Refresh page multiple times - should load consistently
+3. **Test responsive design**: Resize browser window - navigation should adapt to different screen sizes
+
+## File Change Validation
+
+Since this is a static deployment repository, most changes will involve updating the pre-built files:
+
+### After Updating Built Files
+1. **ALWAYS** run the complete validation scenarios above
+2. **Check asset manifest**: Verify `asset-manifest.json` references match actual files in `build/`
+3. **Verify service worker**: If bundle names changed, ensure `service-worker.js` and `precache-manifest.*.js` are updated
+4. **Test isolated views**: Ensure component isolation still works after bundle updates
+
+### JavaScript Bundle Updates
+- Bundle files use content hashes (e.g., `main.b17af953.js`)
+- When updating bundles, ensure `index.html`, `asset-manifest.json`, and precache manifest reference the correct hashed filenames
+- **NEVER** manually edit bundle contents - they are generated by the source repository build process
+
+## Common Tasks
+
+### Repository Status Check
+```bash
+cd /home/runner/work/uisautomation.github.io/uisautomation.github.io
+ls -la
+# Should show: .nojekyll, asset-manifest.json, build/, index.html, precache-manifest.*.js, service-worker.js
+```
+
+### Quick Site Test
+```bash
+cd /home/runner/work/uisautomation.github.io/uisautomation.github.io
+python3 -m http.server 8000 &
+sleep 3
+curl -I http://localhost:8000  # Should return 200 OK
+pkill -f "python3 -m http.server"
+```
+
+### File Integrity Check
+```bash
+cd /home/runner/work/uisautomation.github.io/uisautomation.github.io
+# Verify core files exist
+test -f index.html && echo "✓ index.html exists"
+test -f asset-manifest.json && echo "✓ asset-manifest.json exists"
+test -d build && echo "✓ build directory exists"
+test -f service-worker.js && echo "✓ service-worker.js exists"
+```
+
+## Key Information
+
+### Site Purpose
+- Documentation site for University of Cambridge UI Automation React components
+- Built using React Styleguidist for component documentation
+- Served via GitHub Pages at `uisautomation.github.io`
+
+### Technology Stack
+- **React Styleguidist**: Documentation generator for React components
+- **Workbox**: Service worker library for offline functionality
+- **GitHub Pages**: Static site hosting
+- **Python HTTP Server**: For local development testing
+
+### Source Repository
+- The actual component source code and development happens in a separate repository
+- This repository receives automated deployments of the built documentation
+- Original commit shows "Generated react component documentation" by GitHub Robot User
+
+### Limitations
+- **Cannot modify component behavior**: This repository only contains built output
+- **Cannot run development tools**: No development dependencies or build tools available
+- **Cannot debug component source**: Only minified/bundled JavaScript available
+- **No testing framework**: Site testing must be done manually through browser validation
+
+## Troubleshooting
+
+### If Site Doesn't Load
+1. Check if Python HTTP server is running: `ps aux | grep "python3 -m http.server"`
+2. Verify port 8000 is available: `netstat -ln | grep :8000`
+3. Check for file permission issues: `ls -la` in repository root
+
+### If Components Don't Display
+1. Check browser developer tools console for JavaScript errors
+2. Verify bundle files exist in `build/` directory
+3. Confirm `asset-manifest.json` has correct file references
+4. Test in different browser to rule out browser-specific issues
+
+### If Filtering/Navigation Broken
+1. Verify React Styleguidist JavaScript bundles loaded correctly
+2. Check service worker status in browser developer tools
+3. Clear browser cache and reload
+4. Confirm no network errors blocking JavaScript execution
+
+Remember: This is a static documentation deployment repository. All development and source code changes happen elsewhere. Focus on validating the deployed documentation works correctly rather than modifying the components themselves.