Let apps declare their ability surface for docent:check

[jszobody]

Closes #3.

The coupling

Gate::has() only reads the abilities array that Gate::define() populates. An application that bridges authorization with a single Gate::before callback defines no gates at all, so Gate::has() returns false for every one of its real permissions and every authorize: key in its content is reported as unknown.

That's the natural shape for any enum-backed or database-backed permission system, and it currently forces the dependency the wrong way round: a docs linter driving a change to the application's authorization layer.

Pushback on the proposed mechanism

The issue suggested a closure in config:

'check' => ['abilities' => fn (): array => array_column(Permission::cases(), 'value')],

A closure in a config file breaks php artisan config:cache — "Your configuration files are not serializable". Documenting that as the hook would trade one footgun for a worse one, so this splits it by what each mechanism can actually hold.

Config, for the static case — stays cacheable:

'check' => [
    'abilities' => App\Enums\Permission::class,   // or ['a', 'b', 'c']
],

A service provider, for the dynamic case — where closures belong:

Docent::abilities(fn () => Permission::query()->pluck('name')->all());

The enum shorthand the issue asked for is supported, since that's where the permission list lives in most apps. A class-string that isn't a backed enum raises InvalidArgumentException rather than silently yielding an empty surface.

Semantics

• A declared surface replaces Gate::has() rather than augmenting it. Half-declaring would make the check quietly weaker than either source alone, and there's no way to tell "I didn't list it" from "it doesn't exist".
• Runtime registration wins over config; a site's own declaration wins over the global one, matching how every other registration in the registry composes.
• Resolved once per check run, not once per ability, since the closure may hit the database.
• Unset, nothing changes: Gate::has() remains the fallback.

Admin picker

Editor::pickerMeta() used array_keys(Gate::abilities()), so for exactly these applications the authorize: completion list was empty. It now prefers the declared surface, falling back to the defined gates.

Verification

vendor/bin/pest — 641 passed (14 new). pint --test and phpstan clean.