Instruction file imported from jreichert/cursor_base_rules (.cursor/rules/_docs-github-integration.mdc). Copyright stays with the author.

IMPORTANT: These instructions must be followed when applying this rule

• Apply this rule if the user's request includes any of the following terms (case-insensitive):
  'github', 'foss', 'open source', 'public documentation', 'github wiki', 'repository setup'

• Apply this rule if the underlying intent is to prepare a project for GitHub or open source visibility, even if those exact words are not used.

• ❗ Do not apply this rule in any other situation unless you are highly confident that the user is asking to perform a matching action. If that happens, stop and ask the user for confirmation before continuing.

GitHub Integration Standards

GitHub Wiki Structure

Home Page (.github/wiki/Home.md)

# Project Name

## Quick Start
Brief overview and getting started guide

## Architecture Overview
High-level system architecture and design principles

## Tech Stack
Programming languages, frameworks, and tools

## Features
Key features and capabilities

## Configuration
Environment setup and configuration

## Contributing
How to contribute to the project

## Support
Getting help and support

Sidebar Navigation (.github/wiki/_Sidebar.md)

# Navigation

- [Home](Home)
- [Architecture](hexagonal_architecture)
- [Component Diagram](component_diagram)
- [Architectural Choices](architectural_choices)
- [Environment Setup](environment_setup)
- [UML Diagrams](uml/README)

Page Navigation Standards

• Back to Home - Every page links back to Home.md
• Previous/Next - Sequential navigation between related pages
• Anchor links - Section-specific navigation within pages
• Cross-references - Links to related documentation

Documentation Organization

Public vs. Internal Documentation

• Public (.github/wiki/) - Current state, architecture, setup, features
• Internal (docs/) - Change history, development notes, internal processes
• Clear separation - No duplication between public and internal docs

Documentation Migration

• Move, don't copy - Avoid maintaining parallel documentation sets
• Update references - Fix all cross-references after moving files
• Verify links - Ensure all navigation links work correctly
• Test rendering - Verify documentation displays properly in wiki

File Organization

.github/wiki/
├── Home.md                    # Main entry point
├── _Sidebar.md                # Navigation
├── hexagonal_architecture.md  # Architecture docs
├── component_diagram.md       # Visual docs
├── architectural_choices.md   # Tech decisions
├── environment_setup.md       # Setup guide
└── uml/                       # Visual documentation
    ├── README.md
    └── *.puml                 # UML diagrams

FOSS Documentation Standards

Public Documentation Requirements

• Clear overview - What the project does and why it exists
• Architecture explanation - How the system is designed
• Setup instructions - How to get started quickly
• Feature documentation - What capabilities are available
• Contributing guidelines - How others can contribute

Documentation Quality

• Professional appearance - Clean, well-formatted documentation
• Comprehensive coverage - All major aspects documented
• Easy navigation - Clear structure and cross-references
• Up-to-date content - Reflects current project state

Accessibility

• Clear language - Avoid jargon, explain technical terms
• Logical structure - Organized in a logical flow
• Visual aids - Diagrams and examples where helpful
• Multiple entry points - Different ways to find information

Implementation Process

Setup Phase

1. Create .github/wiki/ directory
2. Move current state documentation
3. Create home page and sidebar
4. Add navigation links
5. Update cross-references

Quality Assurance

• All links work correctly
• Documentation renders properly
• Navigation is intuitive
• Content is comprehensive
• No broken references

Maintenance

• Keep current - Update documentation as project evolves
• Review regularly - Ensure documentation stays accurate
• Gather feedback - Improve based on user experience
• Version control - Track documentation changes

Examples

• Input: "Set up GitHub Wiki for our FOSS project"

• Output: Create .github/wiki/ with home page, sidebar, move current docs, add navigation, update all references

• Input: "Make our documentation public on GitHub"

• Output: Organize docs for public visibility, create comprehensive home page, establish clear navigation structure

• Input: "Make our documentation public on GitHub"

• Output: Organize docs for public visibility, create comprehensive home page, establish clear navigation structure