Improve rules guidance in the deep dive and rules docs

[continue]

Overview

This PR improves the rules documentation based on user feedback from Slack thread about confusion with Hub/VSCode rules integration.

Changes Made

Documentation Improvements

****:

• Added comprehensive "Understanding Hub vs Local Rules Integration" section
• Documented rules loading order and behavior differences
• Added detailed "Working Between Hub and Local Rules" workflow instructions
• Created troubleshooting section addressing common issues:
  • Rules not syncing between Hub and VSCode
  • Inaccurate edit links (references CON-3084)
  • Rules not appearing in assistant

****:

• Enhanced "How Rules Work" section with clearer location guidance
• Added visual comparison of Local vs Hub rules management
• Included quick setup recommendations

Key User Experience Improvements

1. Clear expectations: Users now understand why rules created in one place don't automatically appear in the other
2. Workflow guidance: Step-by-step instructions for moving rules between Hub and local
3. Troubleshooting: Common issues and solutions clearly documented
4. Issue tracking: References Linear issue CON-3084 for the link accuracy problem

Addresses User Feedback

From the Slack thread, users reported:

• ✅ Confusion about rules deep dive documentation
• ✅ Not understanding how to sync rules between VSCode and Hub
• ✅ Inaccurate links when editing rules (documented with workarounds)
• ✅ Need for clearer workflow guidance

Testing

• Reviewed existing documentation structure
• Ensured all links work correctly
• Validated Markdown formatting and syntax
• Confirmed references to related Linear issues are accurate

Related Issues

• Addresses CON-4145: Improve rules guidance in the deep dive and rules docs
• References CON-2970: Improve rules guidance
• References CON-3084: Links to hub rules in extension do not point to correct URL
• References CON-3904: Clicking edit on the rules page tries to open the rule on the hub

---

This agent session was created by tingwai and co-authored by Continue noreply@continue.dev.

---

Summary by cubic

Improved the rules docs to clearly explain Hub vs local rules, loading order, and workflows, plus added troubleshooting to reduce confusion between VSCode and Hub. This clarifies the edit link behavior and workarounds tied to Linear issue CON-3084.

• New Features
  • Added “Hub vs Local Rules” overview with rules loading order.
  • Step-by-step workflows for using Hub rules via config and promoting local rules to Hub.
  • Quick setup guidance in rules.mdx for local and shared rules.
  • Troubleshooting for sync expectations, incorrect edit links (CON-3084), and rules not appearing.

[github-actions]

⚠️ PR Title Format

Your PR title doesn't follow the conventional commit format, but this won't block your PR from being merged. We recommend using this format for better project organization.

Expected Format:

<type>[optional scope]: <description>

Examples:

• feat: add changelog generation support
• fix: resolve login redirect issue
• docs: update README with new instructions
• chore: update dependencies

Valid Types:

feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert

This helps with:

• 📝 Automatic changelog generation
• 🚀 Automated semantic versioning
• 📊 Better project history tracking

This is a non-blocking warning - your PR can still be merged without fixing this.

[Patrick-Erichsen]

I think one of the main benefits is that it's version controlled alongside your code

[Patrick-Erichsen]

Could mention that it's easy to include in multiple agents. Also maybe give some examples of a hub rule vs project rule, eg hub rule for org wide things like "always use X library for Y task" and project rule like "remember to generate migrations after modifying the db"