docs(model-apps): move persona-probe detail out of SKILL.md into a reference

Asked whether adding a step to app-builder was the right place for this. The step
itself is right -- without an entry point the script is undiscoverable, and there
is no validation skill to host it (deferred by design until the loop it would wrap
actually exists). The 19 lines of prose in SKILL.md were not.

`skills/app-builder/SKILL.md` was already 508 lines against the plugin's own
"keep SKILL.md under 500 lines" guideline before this feature, and the block
pushed it to 527. The same guideline names the fix: "use progressive disclosure --
SKILL.md for workflow, reference files for details".

So the invocation and the one-line reason stay in the phase; prerequisites, how to
read `inconclusive`, why it probes the negative direction, and the scope limit move
to `references/persona-validation.md`. That page also states the two-layer split --
why the metadata check stays in the build gate and the probe does not -- which is
the actual architectural answer and had no home in either file.

Net -6 lines in SKILL.md, so this does NOT get the file under 500; it was over
budget beforehand and that is a pre-existing condition worth fixing separately.

Docs only; no behaviour change. 1522 tests still pass.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 42626da2-b66f-4162-acaa-b1127ef23d89

Author: akshay-viz

plugins/model-apps/AGENTS.md

@@ -414,6 +414,7 @@ references/                    ← Shared reference docs
   localization.md              ← Multi-language + RTL pattern (loaded conditionally)
   supported-dependencies.md    ← Versioned package list for generated pages
   troubleshooting.md           ← Deployment/runtime/env issues
+  persona-validation.md        ← app-builder: probe-persona prerequisites, reading `inconclusive`, scope limit
   verified-icons.txt           ← ~5000 Fluent UI icon names; Grep-validated by page-builder
 samples/                       ← Example .tsx files (13 samples) plus app-builder spec samples
 scripts/

plugins/model-apps/references/persona-validation.md

@@ -0,0 +1,73 @@
+# Persona validation — what each persona can actually DO
+
+Loaded on demand by `/app-builder` Phase 3. Verifying a build proves the app matches its spec; this
+page is about the separate question of whether each **persona** can actually work in it.
+
+## Two layers, deliberately separate
+
+| | `verify-model-app.js` → `role-privileges` | `probe-persona.js` |
+|---|---|---|
+| Proves | the role **holds** the declared privileges | the persona can **actually perform** the operation |
+| Also depends on | nothing | record ownership, business unit, team membership, sharing, plug-ins |
+| Cost | free — metadata reads during a verify that already runs | N × M round trips |
+| Prerequisites | none | a test user + `prvActOnBehalfOfAnotherUser` |
+| Answer shape | binary | can legitimately be **inconclusive** |
+| So it is | part of the **build gate**, always on | **opt-in**, run when you want it |
+
+They are not redundant. A role can hold every declared privilege and still leave the persona unable
+to work — depth interacts with who owns the records, which business unit they sit in, what teams the
+user belongs to, what has been shared, and what server-side plug-ins reject. `roleprivileges` shows
+none of that, so only executing a real operation answers it.
+
+Keeping the metadata check in the build gate is what makes it free and unconditional; moving it out
+would restore the hole it was added to close — a role row exists, verify reports clean, and nothing
+checks what it grants.
+
+## Running it
+
+Read-only. It changes nothing.
+
+```bash
+node "${PLUGIN_ROOT}/scripts/probe-persona.js" --env <envUrl> --spec @<working-dir>/app-spec.json
+```
+
+`--allow-mutations` additionally *plans* create/write/delete probes. It does **not** execute them —
+exercising a write to verify it needs fixture creation and cleanup, which is a separate design.
+
+## Prerequisites
+
+It reports clearly and exits rather than guessing when these are unmet:
+
+- the persona declares `assignTo.users[]` (already a `systemuserid`, which is what the impersonation
+  header takes — no directory lookup and no application user needed);
+- the signed-in user holds **`prvActOnBehalfOfAnotherUser`**, assigned **directly** — a
+  team-inherited grant does not satisfy it.
+
+## Reading the output
+
+- **`pass`** — the operation behaved as declared.
+- **`fail`** — a declared privilege did not work, or an entity the persona never declared *was*
+  readable (an over-broad role).
+- **`inconclusive`** — the probe **proved nothing either way**. It is *not* a pass. Inconclusive
+  results do not fail the run, because they are genuine unknowns and failing on them would train you
+  to ignore the tool — but they are always counted, so an all-inconclusive run cannot look clean.
+
+The most common inconclusive is an empty `200` on a negative probe: Dataverse answers *"no privilege"*
+with `403` but *"narrower scope"* with a filtered `200`, which is indistinguishable from an authorized
+read of an empty table. Seed a row owned by another user to disambiguate.
+
+## Why it probes the negative direction
+
+For each persona it also reads an entity that **another** persona declares and this one does not.
+
+An over-broad role is invisible from the inside: every operation the user tries simply succeeds. It
+can only be detected by trying something that *should* fail. `appmodule` is never probed negatively —
+the build injects it for every persona, so it would report a failure on every run.
+
+## What a green run does NOT mean
+
+This exercises the **Web API**. It says nothing about UCI navigation, which form opens, field or
+control visibility, client-side script, the command bar, layout, or accessibility.
+
+**A green run means the data operations are authorized — not that the app works.** Those still need a
+browser pass or a human.

plugins/model-apps/skills/app-builder/SKILL.md

@@ -309,23 +309,17 @@ node "${PLUGIN_ROOT}/scripts/verify-model-app.js" --env <envUrl> --spec @<workin
 ```
 
 **Optional — probe what each persona can actually DO.** Verify's `role-privileges` check is a
-*metadata* comparison: it proves the deployed role HOLDS the declared privileges. It cannot prove the
-persona can perform the operation, because that also depends on record ownership, business-unit
-placement, team membership, sharing, and server-side plug-ins. To check that, run real reads **as each
-persona** using Dataverse impersonation (read-only; it changes nothing):
+*metadata* comparison; it cannot prove the persona can perform the operation, which also depends on
+record ownership, business unit, team membership, sharing and plug-ins. To check that, run read-only
+authorization probes **as each persona** via Dataverse impersonation:
 
 ```bash
 node "${PLUGIN_ROOT}/scripts/probe-persona.js" --env <envUrl> --spec @<working-dir>/app-spec.json
 ```
 
-It also probes the **negative** direction — reading an entity another persona declares and this one
-does not — which is the only way to catch an over-broad role, since from the inside every operation
-the user tries simply succeeds. Prerequisites (it reports clearly and exits rather than guessing when
-they are unmet): the persona declares `assignTo.users[]`, and the signed-in user holds
-`prvActOnBehalfOfAnotherUser` assigned **directly**. Results marked *inconclusive* proved nothing
-either way and are **not** passes. It exercises the Web API, so a green run means the data operations
-are authorized — **not** that the app works: navigation, form and control visibility, client script
-and layout still need a human or a browser pass.
+Prerequisites, how to read `inconclusive` (it is **not** a pass), and the scope limit — a green run
+means the data operations are authorized, **not** that the app works — are in
+[persona-validation.md](../../references/persona-validation.md).
 
 Then open the app in the browser. Refine `app-spec.json` and re-run Phase 2 to iterate.