docs: the operator grants are a UI flow now, not a database procedure (0.3.3)

[Weegy]

Follow-up to core PR byte5ai/omadia#824 (epic #470 C16), named in that PR's own follow-up note: this plugin's OPERATOR-GUIDE §4.1 documented the hand-INSERT workaround and stated that core ships no surface for it. #824 makes that untrue.

Do not merge before #824 lands. Nothing here breaks on an older core — the fallback path is documented and the acceptance script still drives it — but the primary path this PR documents does not exist until #824 is on main.

Documentation only. No plugin code changed. The artifact is re-cut to 0.3.3 because two of the rewritten files ship inside the ZIP: README.md, and the manifest's setup.guide, which an operator reads in the install wizard on the step before the one that now asks the question.

The problem

A permission whose only "yes" is a SQL statement is not a permission an operator gave. That was the honest reading of §4.1, and it was accurate documentation of an inaccurate situation — which is worse than it sounds, because the guide also told them to restart the middleware afterwards. An operator who has to schedule a restart to find out whether a permission was needed learns to grant everything up front.

#824 replaced both halves. The docs had not caught up, and the one that matters most is not in this repo's docs/ at all: setup.guide renders in the wizard, one step before the Permissions step now asks. A guide that says "there is no button for this yet" directly above the button is not a stale doc, it is a contradiction the operator has to resolve.

What changed

Operator Guide §4 — rewritten around the UI, keeping the heading so every existing inbound anchor still resolves.

§4.1	The install wizard's Permissions step: the SQL card naming the ledger, one row per public path, optional_requires listed as prerequisites without checkboxes. Grant & activate vs Skip, and what Skip actually leaves behind.
§4.2	The plugin page's Permissions panel (#grants): per-grant toggles, Apply, withdrawal, and the ledger-drift line.
§4.3	What is being agreed to — unchanged security reasoning, now stated once instead of split across two procedures.
§4.4	The API, reframed as for automation: `GET

Three things are now stated that were not before, each because an operator who meets them cold misreads them:

• No restart. The route re-activates in process and returns the state it read back.
• Skipping the SQL grant leaves the plugin errored — this plugin reaches for the database in activate(). Without that sentence, errored reads as a broken install rather than an unanswered question, and the recovery (grant from the panel; no reinstall) is invisible.
• Uninstall purges both grant tables, so a reinstall asks again instead of inheriting the previous package's database access and unauthenticated surface. §10 said the opposite, which was true when it was written.

Appendix A — Older cores keeps the hand INSERT rather than deleting it. A plugin release outlives the core release it was written against, and #824 bumped no @omadia/plugin-api type, so no version number distinguishes the two cores. §4 therefore gives the probe that does — GET …/grants answers 200 with a declared block on a core that has it — instead of asking the operator to guess. The appendix also explains why the restart was there (ctx.services.get is synchronous, so the grant is read once while the context is built), which is what makes it obvious that #824 removed a real constraint rather than a formality.

The same rewrite lands in README.md, the in-ZIP packages/plugin/README.md, and setup.guide en + de. The German copy uses the labels the UI actually ships — Freigeben & aktivieren, Überspringen, Übernehmen — taken from #824's de.json, not translated independently, so the guide and the buttons beside it agree.

The acceptance script

scripts/acceptance-local.mjs granted SQL with a direct INSERT because there was no alternative. Now there is one, and a run that keeps using the shortcut stops testing what an operator does.

It probes for the unified route and, when the core under test ships it, grants after install over that route — the same call Grant & activate makes — then asserts the plugin comes back active out of the PUT. That last assertion is the point: a 200 proves the write landed, not that the plugin came back up, and in-process re-activation is precisely the thing #824 added.

Without the route it falls back to the pre-#824 pair (hand INSERT before activation, …/public-paths after), and the report names which one ran — "granted" over two different mechanisms is two different claims about the system under test.

Two consequences worth stating plainly:

• The probe never concludes false from a 404. A missing route and a not-installed plugin both answer 404, and the probe runs before the clean slate, when the previous run's install may or may not still be there. Only a 200 carrying declared is treated as proof. Left undecided, the run keeps the pre-C16 ordering, which is correct on every core; the post-install PUT then settles it, where a 404 is conclusive.
• §3.9 no longer fails on the documented state. On a #824 core the harness deliberately does not pre-grant, so the install legitimately reports errored between configure and grant. That is now a PASS naming the state, with the real assertion moved to the grant PUT. Calling it a FAIL would turn the run red on the exact flow it exists to prove.

§3.15 stops being permanently undecided (acceptance.md left the grant lifecycle open; C16's B6 answered it): purged rows PASS, rows left behind FAIL on a core that promised to clear them and BLOCK on one that never did.

compat.core unchanged

Still >=1.5 <2.0. #824's own gate table records no plugin-api API-snapshot drift — no type changed, so there is no version to name. It changed how an operator answers the two permissions, not what this manifest declares. The manifest comment now records that next to the existing C11 and C15 entries, so the next person does not re-derive it, and because that comment block is the only place the floor's reasoning is written down.

Gates

Gate	Result
npm run typecheck	pass (exit 0)
npm run build	pass (exit 0)
npm test	1267 pass, 0 fail across all four workspaces (exit 0)
npm run package	omadia-dev-platform-0.3.3.zip, 538,458 bytes — version drift guard pass
manifest.yaml parses	setup.guide en 8,561 / de 9,202 chars, neither containing INSERT any more

Exit codes were captured directly, not read off a piped tail.

Not done here

• docs/ACCEPTANCE-RUN-2026-08-2*.md are dated records of what happened on those days and are left alone. The current-state claims they contained now live in §4 and Appendix A.
• No live run against a #824 core, since #824 has not merged. The script's fallback path is what runs today; the unified path is exercised on the first run after the merge.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}