GitHub Pages Sync

This skill ensures the public GitHub Pages site (site-docs/) stays synchronized with source code and internal documentation changes.

When This Skill Activates

Automatic Triggers

1. Code changes in core modules - synapse/*.py, synapse/commands/*.py
2. Profile changes - synapse/profiles/*.yaml
3. Plugin/Skill changes - plugins/**/*
4. Configuration changes - pyproject.toml (version, dependencies, entry points)
5. Internal doc changes - guides/*.md, docs/*.md, README.md
6. Site-docs changes - site-docs/** (direct edits to the published site)

Manual Invocation

• /github-pages-sync - Run full site-docs synchronization check

Workflow

Phase 1: Detect Changes

When code or internal docs are modified, identify affected site-docs pages by consulting references/source-site-mapping.md.

Quick Reference - Common Patterns:

Change Type	Primary site-docs Pages	Secondary Pages
CLI command	reference/cli.md	guide/agent-management.md, guide/communication.md
API endpoint	reference/api.md	advanced/authentication.md
Profile setting	concepts/profiles.md, reference/profiles-yaml.md	reference/ports.md
Environment variable	reference/configuration.md	guide/settings.md
New feature	index.md	Relevant guide/ or concepts/ page
Version bump	changelog.md	index.md (badges)

Phase 2: Propose Updates

For each affected site-docs page:

1. Read the current page content
2. Identify the specific section to update
3. Propose the minimal necessary change
4. Present changes to user for approval

Update Principles:

• Maintain MkDocs Material formatting (admonitions, tabs, code annotations)
• Update only affected sections — do not rewrite entire pages
• Keep index.md concise; put details in guide/ or reference/ pages
• Preserve existing Mermaid diagrams unless the architecture changed
• Ensure nav structure in mkdocs.yml stays consistent

Phase 3: Apply Updates

After user approval:

1. Apply changes to affected site-docs/ pages
2. Update mkdocs.yml nav if new pages were added
3. Update changelog.md if the change is user-facing

Phase 4: Verify

Run build verification:

uv run mkdocs build --strict

Check for:

1. Build success - No warnings or errors in strict mode
2. Broken links - All internal cross-references resolve
3. Nav consistency - mkdocs.yml nav matches actual files in site-docs/

Page Categories

High Traffic (Update Promptly)

Page	Purpose	Update Frequency
index.md	Landing page, first impression	Every major feature
getting-started/quickstart.md	First-time user experience	Install/setup changes
reference/cli.md	CLI command reference	Every CLI change
reference/api.md	API endpoint reference	Every API change

Core Guides

Page	Purpose	Update Frequency
guide/agent-management.md	Agent lifecycle	Agent workflow changes
guide/communication.md	Inter-agent messaging	Protocol changes
guide/agent-teams.md	Team orchestration	Team feature changes
guide/settings.md	Configuration guide	Setting changes

Deep Reference

Page	Purpose	Update Frequency
concepts/architecture.md	System design	Architecture changes
concepts/a2a-protocol.md	A2A protocol details	Protocol changes
reference/configuration.md	Full config reference	Setting additions
reference/profiles-yaml.md	YAML schema	Profile format changes

Reference Files

For detailed page inventory and source-to-page mappings, consult:

• references/source-site-mapping.md - Source file to site-docs page relationships
• references/site-inventory.md - Complete list of all site-docs pages and their roles

Special Cases

Version Updates

When pyproject.toml version changes:

1. Update changelog.md with release notes
2. Check if index.md badges need updating

New Feature Addition

For major new features:

1. Add to index.md feature highlights
2. Create or update relevant page in guide/ or concepts/
3. Update reference/cli.md and/or reference/api.md
4. Add to mkdocs.yml nav if a new page was created
5. Update getting-started/quickstart.md if the feature affects onboarding

New CLI Command

1. Add to reference/cli.md with full syntax and examples
2. Update relevant guide/ page with usage context
3. Update getting-started/quickstart.md if commonly used

Deprecation

When deprecating features:

1. Mark as deprecated with admonition in relevant pages
2. Add migration guide if needed
3. Update changelog.md
4. Remove from getting-started/quickstart.md examples