refactor: implement repository_dispatch architecture for documentation sync

Co-authored-by: neilime <314088+neilime@users.noreply.github.com>

Author: Copilot

.github/EXAMPLES.md

@@ -0,0 +1,275 @@
+# Documentation Sync - Usage Examples
+
+This document provides examples of how to use the repository_dispatch-based documentation sync system.
+
+## Basic Examples
+
+### Example 1: Basic Configuration
+
+Minimal configuration for syncing documentation:
+
+```yaml
+name: Push Documentation to Portal
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'README.md'
+  workflow_dispatch:
+
+jobs:
+  push-docs:
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@main
+    with:
+      source_repo: 'my-project'
+      target_path: 'projects/my-project'
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```
+
+### Example 2: Custom Documentation Path
+
+If your documentation is in a non-standard location:
+
+```yaml
+jobs:
+  push-docs:
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@main
+    with:
+      source_repo: 'my-project'
+      docs_path: 'documentation'
+      target_path: 'projects/my-project'
+      include_readme: false
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```
+
+### Example 3: Sync from Multiple Branches
+
+Sync documentation from both main and develop branches:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+      - develop
+    paths:
+      - 'docs/**'
+      - 'README.md'
+
+jobs:
+  push-docs-main:
+    if: github.ref == 'refs/heads/main'
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@main
+    with:
+      source_repo: 'my-project'
+      target_path: 'projects/my-project'
+      branch: 'main'
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+
+  push-docs-dev:
+    if: github.ref == 'refs/heads/develop'
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@main
+    with:
+      source_repo: 'my-project'
+      target_path: 'projects/my-project-dev'
+      branch: 'develop'
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```
+
+### Example 4: With Manual Trigger Only
+
+For projects that want to control when documentation is synced:
+
+```yaml
+on:
+  workflow_dispatch:
+    inputs:
+      sync_readme:
+        description: 'Include README.md'
+        required: false
+        type: boolean
+        default: true
+
+jobs:
+  push-docs:
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@main
+    with:
+      source_repo: 'my-project'
+      target_path: 'projects/my-project'
+      include_readme: ${{ inputs.sync_readme }}
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```
+
+## Testing
+
+### Testing the Dispatcher
+
+1. Set up the workflow in your project repository
+2. Add the `PUBLIC_DOCS_TOKEN` secret with `repo` scope
+3. Make a commit to `docs/**` or `README.md`
+4. Check the Actions tab in your repository for dispatcher execution
+5. Check the Actions tab in public-docs for receiver execution
+6. Verify the documentation appears in the portal
+
+### Local Testing
+
+You can't test the dispatcher locally, but you can validate your documentation:
+
+```bash
+# In your project repository
+cd docs
+# Ensure all markdown files are valid
+find . -name "*.md" -exec markdown-lint {} \;
+```
+
+## Troubleshooting
+
+### Workflow not triggering
+
+**Symptoms:**
+```
+No workflow runs appear in Actions tab
+```
+
+**Solutions:**
+1. Verify the workflow file is in `.github/workflows/` directory
+2. Check the `paths` filter matches your documentation structure
+3. Ensure you're pushing to the correct branch
+4. Validate the workflow YAML syntax
+
+### Token permission errors
+
+**Symptoms:**
+```
+❌ Error: Resource not accessible by integration
+```
+
+**Solutions:**
+1. Verify `PUBLIC_DOCS_TOKEN` secret exists in your repository
+2. Ensure the token has `repo` scope (not just `public_repo`)
+3. Confirm the token hasn't expired
+4. Test token permissions:
+   ```bash
+   curl -H "Authorization: token $TOKEN" \
+     https://api.github.com/repos/hoverkraft-tech/public-docs/dispatches
+   ```
+
+### Documentation not appearing
+
+**Symptoms:**
+```
+Dispatcher runs successfully but docs don't appear in portal
+```
+
+**Solutions:**
+1. Check if receiver workflow ran in public-docs
+2. Review receiver workflow logs for build validation errors
+3. Verify the `target_path` is correct
+4. Ensure documentation files are `.md` or `.mdx`
+5. Check that frontmatter in docs is valid YAML
+
+### Build validation fails
+
+**Symptoms:**
+```
+Receiver workflow fails during build step
+```
+
+**Solutions:**
+1. Review the build logs in the receiver workflow
+2. Common issues:
+   - Invalid markdown syntax
+   - Broken frontmatter YAML
+   - Invalid relative links
+   - Missing images or assets referenced in docs
+3. Test locally in public-docs:
+   ```bash
+   # Clone public-docs
+   git clone https://github.com/hoverkraft-tech/public-docs
+   cd public-docs/application
+   # Add your docs manually to test
+   npm ci
+   npm run build
+   ```
+
+### Large documentation bundles
+
+**Symptoms:**
+```
+❌ Error: Payload too large
+```
+
+**Solutions:**
+1. GitHub Actions has limits on payload size
+2. Reduce documentation size:
+   - Move large images to a separate hosting service
+   - Split very large documents into smaller files
+   - Exclude unnecessary files from docs directory
+3. Consider using git submodules for very large documentation sets
+
+## Best Practices
+
+1. **Keep documentation focused**: Only include necessary documentation files
+2. **Validate locally**: Test markdown and build before committing
+3. **Use frontmatter**: Add metadata to help with organization
+4. **Monitor workflows**: Check both dispatcher and receiver logs regularly
+5. **Test incrementally**: Push small changes to verify everything works
+6. **Use semantic paths**: Choose clear, descriptive target_path values
+
+## Advanced Usage
+
+### Conditional Syncing
+
+Only sync when specific files change:
+
+```yaml
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**/*.md'
+      - '!docs/drafts/**'
+
+jobs:
+  push-docs:
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@main
+    with:
+      source_repo: 'my-project'
+      target_path: 'projects/my-project'
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```
+
+### Multiple Documentation Sections
+
+Sync different documentation sections to different paths:
+
+```yaml
+jobs:
+  push-user-docs:
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@main
+    with:
+      source_repo: 'my-project'
+      docs_path: 'docs/users'
+      target_path: 'projects/my-project/users'
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+
+  push-dev-docs:
+    uses: hoverkraft-tech/public-docs/.github/workflows/sync-docs-dispatcher.yml@main
+    with:
+      source_repo: 'my-project'
+      docs_path: 'docs/developers'
+      target_path: 'projects/my-project/developers'
+    secrets:
+      PUBLIC_DOCS_TOKEN: ${{ secrets.PUBLIC_DOCS_TOKEN }}
+```