[burigolucas]

Description

This PR improves the developer experience around ansible-lint offline/Tier 1 CI by documenting how mocking works, expanding mock lists to cover own-collection roles invoked via import_role, and rewriting the CI failure hint so contributors know exactly what to add and where.

What changed

.ansible-lint-ci

• Clarified the comment block explaining why both private-collection FQCNs and own-collection roles invoked via ansible.builtin.import_role need mocking.
• Added multiple own-collection roles that are invoked with import_role in playbooks and therefore fail syntax-check[specific] without a mock entry.

.github/workflows/ansible-lint.yml

• Replaced the generic "how to fix" hint with two focused troubleshooting blocks:
  • syntax-check[unknown-module] — explains that private-module FQCNs must be added to mock_modules.
  • syntax-check[specific] role not found — explains the import_role vs include_role parse-time/runtime distinction and how to add the FQCN to mock_roles.
  • Kept a third block with the correct local-repro commands (ansible-galaxy collection install . --force then ansible-lint -c .ansible-lint-ci).

CONTRIBUTING.md

• Added a new Mocking Unavailable Modules and Roles subsection under CI Checks.
• Explains when mock_modules vs mock_roles must be updated and the key import_role / include_role distinction.
• Warns contributors not to add mock entries to .ansible-lint (the full config) so Tier 2 CI keeps real dependency validation.

.github/pull_request_template.md

• Added a CI checklist item reminding contributors to update mock_modules/mock_roles when adding tasks that use private or own-collection FQCNs.

Impact

• Tier 1 (ansible-lint offline) CI passes for playbooks that use import_role with own-collection roles, without requiring AUTOMATION_HUB_TOKEN.
• Contributors get actionable error messages instead of a generic hint when lint fails.
• The PR checklist makes it harder to accidentally introduce new unresolved FQCNs.

Type of Change

• feat: A new feature
• fix: A bug fix
• docs: Documentation changes
• style: Formatting, missing semi colons, etc; no code change
• refactor: Refactoring production code
• test: Adding missing tests, refactoring tests; no production code change
• chore: Updating configs, etc; no production code change

Pull Request Title

Note: Please ensure your PR title follows Conventional Commits.
Example: feat: add role

• I have formatted my PR title correctly.

CI Checks

Tier 1 checks (ansible-lint, pre-commit, PR title, gitleaks) run automatically on all PRs.
Full CI (Tier 2) requires maintainer approval for PRs from forks.
To run full CI before opening this PR, configure AUTOMATION_HUB_TOKEN in your fork's secrets — see Running Full CI in Your Fork.

[sabre1041]

LGTM