docs: Improve permission checking documentation and examples

[Ref34t]

Summary

• Replace manual permission checking examples with recommended execute() pattern
• Improve documentation to align with architectural design from Fix has_permission() return type inconsistency (Issue #67) #76
• Update REST API controller permission check for consistency

Changes Made

Documentation Improvements

• docs/2.getting-started.md: Replaced 22-line manual permission checking example with clean 8-line execute() pattern
• docs/4.using-abilities.md: Eliminated manual permission checking anti-patterns, added advanced error handling section showing how to handle specific error types

REST API Controller Update

• includes/rest-api/endpoints/class-wp-rest-abilities-run-controller.php: Updated permission check to use strict comparison (true !==) for consistency with execute() pattern

Discussion Point

As @gziolo noted, this isn't a security vulnerability since each ability's execute() method already performs comprehensive permission checking. The REST API controller creates a two-layer permission model:

1. REST API layer: Pre-check via run_ability_permissions_check()
2. Ability execution layer: Full check via execute()

The controller's permission callback is architecturally unique because it dynamically checks permissions for any ability. We could consider simplifying by removing the separate permission callback and relying entirely on execute()'s error handling.

Open to feedback on this approach.

Test plan

• Verify documentation examples follow recommended execute() pattern
• Confirm no manual permission checking anti-patterns remain in docs
• Test REST API endpoint permission handling

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

Unlinked Accounts

The following contributors have not linked their GitHub and WordPress.org accounts: @mohamed.khaled@9hdigital.com.

Contributors, please read how to link your accounts to ensure your work is properly credited in WordPress releases.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Unlinked contributors: mohamed.khaled@9hdigital.com.

Co-authored-by: justlevine <justlevine@git.wordpress.org>
Co-authored-by: gziolo <gziolo@git.wordpress.org>
Co-authored-by: Ref34t <mokhaled@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 84.92%. Comparing base (80f47ee) to head (0fd3448).

Additional details and impacted files

@@             Coverage Diff              @@
##              trunk      #95      +/-   ##
============================================
- Coverage     85.69%   84.92%   -0.78%     
  Complexity      103      103              
============================================
  Files            16       16              
  Lines           776      776              
  Branches         86       85       -1     
============================================
- Hits            665      659       -6     
- Misses          111      117       +6     

Flag	Coverage Δ
javascript	92.66% <ø> (ø)
unit	81.89% <100.00%> (-1.08%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[gziolo]

REST API security vulnerability

I don't think we are really experiencing a security vulnerability here, because every ability handles permissions check individually during execution as discussed in #76 (comment). That being said, we can iterate on the handling because the run controller is unique, as its permissions check model differs for each ability.

[gziolo]

This PR needs a rebase to resolve conflicts after #94 landed. This would help to review the changes proposed in this PR.

[Ref34t]

@gziolo on it

[Ref34t]

I've updated the PR title and description - you're right that this isn't a security vulnerability.

The reason: even if the REST API permission check had the WP_Error truthiness issue, execute() on line 136 would still block unauthorized access since it performs its own permission check internally.

This update improves code correctness by using strict comparison (true !==) to properly handle all return types from check_permissions(), but it's not fixing an actual security hole due to the two-layer permission model.

[justlevine]

I've been known to misread diffs on mobile 🫣 but if all these reverted to **, then it's a leak from #96 and should be changed back to semantic

[Ref34t]

resolved 0fd3448