Improve roadmap troubleshooting docs and clarify session/auth error messages

[Copilot]

This takes a small roadmap item from Phase C: improve exception clarity and troubleshooting guidance. It makes common auth/session failures easier to diagnose and documents the current unit-vs-integration test workflow in one place.

• Error messages

  • Reworded high-friction failures to point at the likely remediation path instead of surfacing generic errors.
  • Updated:
    • LoginError for invalid credentials
    • missing sesskey after login
    • missing webservice token / sesskey in MoodleSession
    • tokenless webservice calls
    • course listing without token or sesskey

• Troubleshooting documentation

  • Added docs/troubleshooting.md with targeted guidance for:
    • invalid login / CAS setup issues
    • missing token or sesskey
    • course-listing credential failures
    • integration test configuration and local environment issues
  • Linked the new page into MkDocs navigation.

• Contributor guidance

  • Updated docs/development.md to reflect the current test-layer split:
    • tests/unit/ for fast Moodle-free smoke tests
    • integration tests opt-in via --integration
  • Added concise troubleshooting notes for common test setup failures.

• Focused regression coverage

  • Added unit tests for the revised user-facing error wording to keep the new diagnostics stable.

Example of the new messaging shape:

raise LoginError(
    "Moodle login failed: invalid username or password. "
    "Verify MOODLE_USERNAME and MOODLE_PASSWORD, and enable CAS "
    "login if your site requires single sign-on."
)

• Docs preview
  • Added a dedicated troubleshooting page to the docs site.

---

🔒 GitHub Advanced Security automatically protects Copilot coding agent pull requests. You can protect all pull requests by enabling Advanced Security for your repositories. Learn more about Advanced Security.