[Keith McGrane (Keithland89)]

Summary

Layer S1 of Stack A, the installer's 0.6.9 self-serve work. A non-admin in a large, locked-down tenant now sees, in prereqs and in install's and update's preflight, which roles and settings someone else must provide, who that someone is, and where to do it. Optional admin work shows as Hand-off (→), not Missing. It comes from the non-Global-Admin, large-tenant desk review: Top 5 #2; High findings B9, B10, B14 and B18; confusion points #1, #2, #12, #14, #15, #17 and #19.

Stack: based on #170, which sits on #169. This PR merges after #169, #170 and the 0.6.8 release, then retargets to main. It builds on #169's audit-ingestion row and check-audit, and on #170's preflightVerdict, reportPreflight and preflightChecks; it doesn't duplicate them.

Review fixes, in d0a6b46 on top of 13abb50 (a separate commit, so it can be reviewed on its own):

1. Preflight's --yes stop, when the only option is a workspace you're an Admin or Member of that's on a capacity, now names both ways forward. You can run without --yes and choose that workspace, or get admin or contributor rights on a capacity (or start a Fabric trial) so the installer can create a workspace. docs/TROUBLESHOOTING.md matches.
2. "The install carries on." is said once. The hand-off line adds it only when nothing needs attention.
3. The consent hand-off names who approves only in its label and "Who does it", not in its detail as well. On Fabric, the merged audit note follows the consent sentence, ahead of "Couldn't check for roles you could activate yourself."
4. This body names Installer: size for the number of people, and ask in the main flow #181's sizing overlap (under Overlaps).

A new status: handoff. Hand-off is optional admin work someone else does while you carry on. It never blocks an install, with or without --yes, and never counts as needing attention or as missing. A row becomes Hand-off when you lack the role; met and eligible are unchanged, and required rows stay missing:

• consent-role: you don't need it yourself, because the installer gives you an admin consent link to send. A Privileged Role Administrator or Global Administrator approves the app's Graph permissions from that link. An Application Administrator or Cloud Application Administrator can't.
• fabric-admin: a Fabric administrator turns on, or confirms, the tenant settings. The circular "only needed if the tenant settings below are off" is gone.
• power-platform-admin: only when you're a System Administrator in an environment, so only the flows' Power Platform API connection sign-in needs an admin. The row names which admin each flow's connection needs. Otherwise it stays missing.
• teams-admin (Azure): a Teams Administrator uploads the package. The row links the Teams admin center's Manage apps page.
• viva-analyst: now a real Entra role check for Insights Analyst (template 25df335f-…). It reads the active roles and PIM eligibility the other Entra rows already read, so there's no new permission. Met when active, eligible when PIM-eligible, otherwise Hand-off. The row says who assigns the role (a Global Administrator, or a Privileged Role Administrator with PIM), or that an analyst can share the query instead.
• audit-ingestion (Installer: check audit ingestion up front, and sign in to Viva Insights first #169): both "not granted yet" states, Fabric's and Azure's graphRoles.pending, are now Hand-off and say the audit load finds 0 records until it's granted. A failed audit check stays missing.

Preflight. preflightVerdict returns a third list, handoff. reportPreflight prints it on its own line after what needs attention: "Hand-off(s): someone else does this/these." "The install carries on." is said once: on the attention line, or on the hand-off line when nothing needs attention. With only hand-offs it says "Prerequisites: you have what you need yourself" rather than "nothing missing". On Fabric, the consent and the audit role are one ask, so they're shown once; on Azure, both. viva-analyst shows in preflight only when Cowork credits come from the Viva Insights query. power-platform-admin's Hand-off shows only when a chosen flow uses the Power Platform API connection. The full prereqs list shows every row.

Every row that isn't met says who and where. Terminal, web and the web Markdown export print "Who does it:" for a Hand-off, and "How to get it:" otherwise.

• Tenant settings, when you can't read them: you're asked to have a Fabric administrator confirm each one by its current name: Create workspaces (when the installer would create the workspace), Users can create Fabric items (Fabric), Service principals can call Fabric public APIs, Semantic Model Execute Queries REST API, Allow visuals created using the Power BI SDK and the Fabric apps setting under Fabric apps (preview). With org-scoped access, add Allow XMLA endpoints and Analyze in Excel with on-premises semantic models and the capacity's Read Write XMLA endpoint.
• Tenant settings, when you can: the row uses the API's titles.
• Elsewhere: org-access uses the XMLA setting's full name. Concealed user names name a Global Administrator and the current label, "Conceal user, group, and site names in all reports".

An existing workspace on a capacity is enough (Fabric). docs/PREREQUISITES.md already promised this; the code now keeps it.

• With no capacity you can create a workspace on, preflight looks for workspaces you're an Admin or Member of that are on a capacity, using listWorkspaces(['Admin','Member']), or getWorkspace for a recorded workspace.
• If it finds some, placement asks no capacity question. It offers only those workspaces, without "Create a new workspace", and takes the capacity from the chosen one. The plan review and the web setup's placement check handle this path too.
• If it finds none, preflight stops and names both ways forward.
• Under --yes with no recorded workspace, it stops, because the installer can't choose a workspace for you. The stop names both ways forward. You can run it without --yes and choose a workspace you're an Admin or Member of that's on a capacity. Or ask a capacity admin for admin or contributor rights, or start a Fabric trial, so the installer can create a workspace. A recorded workspace on a capacity passes.
• A 403 creating a private Key Vault's managed private endpoint now names the workspace Admin role.

UI, docs and CHANGELOG.

• The web page says "Analytics Hub installer", and the rail's sub-label says "Installer".
• The home panel counts "N to hand off".
• docs/PREREQUISITES.md:
  • explains Hand-off;
  • drops the tenant-settings counts from At a glance and gives one complete settings list with Learn links;
  • updates the capacity wording, concealed names (the anchor is kept) and who assigns Insights Analyst;
  • adds a Conditional Access note for device-code sign-in.
• docs/PERMISSIONS.md, docs/TROUBLESHOOTING.md, azure/DESIGN.md and installer/README.md are updated to match.
• The CHANGELOG bullet sits under Installer: check audit ingestion up front, and sign in to Viva Insights first #169's 0.6.9 candidate subsection, after Installer: run the prerequisite checks inside install and update #170's bullet.

Departures from the plan, for review:

1. Azure now checks Semantic Model Execute Queries REST API. The Azure web app calls executeQueries (azure/web/src/query.js:63), and the docs said the setting was needed on Azure, but the Azure check left it out because it's flagged app. POWER_BI_SETTINGS marks it web: true, and blockedSettings takes { web }; the Fabric app's own setting stays Fabric-only.
2. docs/TROUBLESHOOTING.md gains the new --yes stop and the workspace option for the no-capacity error. docs/PERMISSIONS.md also uses the XMLA setting's full name in its org-scoped access table.
3. The web rendering tests are in setup-page.test.js, which loads the real renderers. web.test.js has the header check and the canAssignDirectoryRoles check.

Scope

Parts affected (installer / app / Fabric notebooks and pipeline / Azure infra, jobs or web / core / Power BI models):

• Installer: the CLI and web setup page, in prereqs.js, steps/plan.js, setup.js, ui.js, web/app.js, web/app.css, clients/fabric.js, clients/graph.js, steps/fabric.js, steps/flows.js, steps/org-access.js and steps/run.js, with their tests.
• Docs: PREREQUISITES, PERMISSIONS, TROUBLESHOOTING, installer/README and azure/DESIGN.md (text only).
• No app, notebook, pipeline, Azure infra, jobs, web, core or Power BI model changes.

Source contracts, optional inputs, install record or deployed item names changed:

• PrereqStatus gains 'handoff'.
• preflightVerdict and reportPreflight return { block, warn, handoff }.
• Preflight gains an optional workspacesOnCapacity.
• fabricApi.listWorkspaces(roles?) adds ?roles=Admin,Member.
• POWER_BI_SETTINGS entries gain optional web and section.
• New exports: usableCapacity, workspacesOnCapacity, settingLabel, settingsToConfirm, ppApiFlows and INSIGHTS_ANALYST_ROLE.
• No install record fields, inputs or deployed item names change.

Validation

• Ran python -B -m pytest tests -q and recorded results below. (Locally, I ran the docs and release subset only; the full suite ran in CI on the head commit, see below.)
• Ran npm test (and npm run typecheck for the installer) in each changed Node project.
• Updated directly related documentation and checked changed links.
• No credentials, tenant exports, prompts or customer names are included.
• If .pbit files changed, documented the rebuild method and Desktop refresh / visual checks. (No .pbit changes.)

Results, skipped checks and limitations:

Local results on head d0a6b46 (Windows):

Command	Result
cd installer; npm test	1133 tests: 1132 passed, 1 failed
cd installer; npm run typecheck	passed (exit 0)
git diff --check	clean (exit 0)
python -B -m pytest tests/test_docs.py tests/test_consolidated_release.py -q	106 passed

CI on head d0a6b46 (tests.yml, run 39943565360, Linux). All six checks pass: app, arm-drift, installer, pytest, valuelens-web and license/cla.

Command (CI job)	Result
python -B -m pytest tests -q -ra (pytest)	1258 passed, 5 skipped, 12181 subtests passed in 6m15s
npm test (installer)	1133 tests: 1129 passed, 0 failed, 4 skipped
npm run typecheck (installer)	passed

The previous head, 13abb50, also passed all six checks (run 39940024985).

• The local npm test failure: the known script.test.js:115. This PC's PowerShell execution policy blocks it ("running scripts is disabled"), and it fails the same way on main. CI on Linux skips it. The execution policy was not bypassed.
• The full pytest suite: it takes 40+ minutes here, so it ran in CI. Its 5 skips need pyspark or Java, which the runner doesn't have.
• Skipped: there's no Bicep change, so npm run build:arm isn't needed.
• Desk and unit tests only: no live tenant, Azure, Fabric or Power Platform calls, and no sign-ins.
• Checked against Microsoft Learn on 23 Oct: the setting names, Insights Analyst's template ID and who assigns it, and the roles for admin consent, workspaces and managed private endpoints.
• Not verified: Learn says the tenant settings are moving to OneLake catalog > Govern > Configurations > Tenant settings, with Admin portal > Tenant settings as the fallback during rollout. The code and docs still say Admin portal > Tenant settings.

Overlaps:

• Built on Installer: check audit ingestion up front, and sign in to Viva Insights first #169 (the audit-ingestion row and check-audit) and Installer: run the prerequisite checks inside install and update #170 (preflightVerdict, reportPreflight and preflightChecks).
• Installer: size for the number of people, and ask in the main flow #181 (Stack B's first layer, based on main) also touches steps/plan.js, docs/PREREQUISITES.md, web/app.js, web.test.js and CHANGELOG.md. Expect line-local conflicts; whichever lands second rebases.
• Installer: size for the number of people, and ask in the main flow #181 also changes how capacity is sized. This PR's capacity-path note (steps/plan.js:526-528: "The installer can't see that capacity's size. With N Copilot seats assigned, F64 or larger is best") is keyed on pre.seats and BIG_CAPACITY_SEATS. Installer: size for the number of people, and ask in the main flow #181 renames those constants to BIG_CAPACITY_PEOPLE and LARGE_TENANT_PEOPLE and sizes by headcount (pre.headcount, headcountPhrase, sizingWarnings({ headcount })). Whichever lands second keys this note on headcount.
• Installer: recommend Azure and start new installs on it #128 (0.6.8's Azure flip) touches azure/DESIGN.md and web-session.js. This PR doesn't change web-session.js; it only adds a test that a Hand-off doesn't count for canAssignDirectoryRoles.

Compatibility

Repair or change on an existing install:

• Preflight now lists Hand-offs on their own line and never stops on them. Update still never blocks.
• A Fabric install whose capacity no longer shows in List Capacities, but whose recorded workspace is still on a capacity, carries on. Before, preflight stopped. The web setup's placement check follows the same rule.
• A recorded workspace and capacity are never changed.
• No migration is needed. No install record fields change.

Deliberately left unchanged:

• The old concealed-names label in the app, the Azure jobs and the notebooks (a listed follow-up).
• Filtering the normal workspace list by role, and the "Create workspaces" check before anything is created (S3).
• The Power Platform data policy row and Power Automate Premium (S6), and the per-admin hand-off pack (S7).
• The Azure parity findings 33, 36, 38, 39/43, 42 and 44.

ValueLens: no Power BI template or model change, so no matching change is needed there.