[tajanthind]

Rebased onto main after #46 merged (resolves the conflict in tests/architecture/test_accounts_first_run.py — both tests kept) and expanded into a proper documentation update.

1. Fixes the merge conflict

#46 and this branch both edited tests/architecture/test_accounts_first_run.py; the rebase keeps both the healthcheck test and the new plugin-context test, both registered in __main__.

2. Answers "do plugins have access to accounts? can a plugin log users in via API?"

• No account access. There is no context.accounts facade. PluginContext exposes exactly library, settings, events, http, fs, ui, jobs, log — no user list, no password verification, no roles. Reaching around it would mean importing models/services.accounts, which the plugin boundary forbids.
• Yes, a plugin can authenticate users via the auth_provider type: authenticate(request_headers) -> Optional[str]. Core calls enabled providers on every request with no session and no valid M2M key; returning a username authorizes the request. Clients can therefore "log in via API" by sending the plugin's own header credential (this is how fnack.reverse-proxy-auth works). Limits: the identity is opaque — no User row, no role, no account management, not shown in the UI chip; the provider check runs before the first-run /setup gate (deliberate for SSO).
• plugins/base.py: AuthProviderPlugin docstring updated (it still said "do not implement until core auth is stable").
• docs/plugins/AUTHORING.md: new §4 subsection "Can a plugin authenticate users? (auth_provider)" with a code example.
• New test pins the boundary: PluginContext has exactly the eight facades (accounts/users/auth/login/password/roles/current_user must not exist) and authenticate takes headers only.

3. Repoints documentation at files that actually exist

The author guide and core comments referenced PLUGIN_ARCHITECTURE.md and INTEGRATION.md — neither exists in this repo. Fixed in docs/plugins/AUTHORING.md, plugins/registry.py, plugins/manager.py, plugins/api.py, app.py, services/queue_service.py, tests/run_smoke_test.py. Historical wayfinder/ tickets/research keep their original references — they are records of what was planned at the time.

4. Documents the shipped contract for plugin authors

• §3 server_extension: routes are authenticated like every other route (accounts session, or the M2M X-API-Key for machine clients; Open_PATHs listed) — you cannot host your own unauthenticated login endpoint; use auth_provider.
• §7 Versioning: states the current plugin API (1.0.1) and that ^1.0 covers minor bumps.
• §8 Publishing: new "Your id is not globally unique (multi-repository rules)" — one marketplace entry per (repository, plugin), "Also in: …" duplicate warnings, installs record their source repository and are refused when ambiguous, switching source is explicit, plus the reverse-DNS recommendation.
• §9 Trust model: fnack requires a login; plugins have no access to accounts.

Verification

• Architecture suite 27/27 pass; smoke test passes; doc-gate, plugin-boundary and accounts test files pass; code-fence balance checked. CI: smoke-test + build-and-push both SUCCESS.