docs: update Power Pages skill list (#174)

- Document the latest Power Pages skills in README.md

- Add ALM/CI-CD and security skill descriptions

- Require future user-invocable skills to be documented

Co-authored-by: GitHub Copilot <copilot@github.com>

Author: priyanshu92

plugins/power-pages/AGENTS.md

@@ -22,6 +22,7 @@ Read `PLUGIN_DEVELOPMENT_GUIDE.md` for UX and reliability standards when creatin
 - **OAuth credential-style site settings** (ConsumerKey / ClientId / ClientSecret / etc.) are NOT excluded from solutions. `setup-solution` Phase 5 prompts per credential to choose between (a) Secret-typed env var (Key Vault per stage), (b) String-typed env var (plain text per stage), or (c) skip. The site-setting record is added to the solution and routed to an env var so secret values never ship in the solution zip. Plans generated before 2026-05-08 use the older `excluded` bucket — setup-solution's preloadedSettings handler treats those as `credentialNeedsDecision` for backward compatibility.
 - **MCP Learn grounding for ALM skills** — solution and pipeline skills (`setup-solution`, `export-solution`, `import-solution`, `diagnose-deployment`, `setup-pipeline`, `deploy-pipeline`, `ensure-pipelines-host`, `force-link-environment`) include a Phase 1.5 step that grounds the agent in current Microsoft Learn ALM docs before proceeding. The shared discovery pattern lives in `references/alm-docs-grounding.md`. Add the same Phase 1.5 + the two `mcp__plugin_power-pages_microsoft-learn__microsoft_docs_search/fetch` tools to `allowed-tools` when introducing a new ALM skill.
 - **ALM artifacts live under `docs/alm/`** — every ALM-only state file (5 plan/decision JSONs and 9 `last-*.json` skill-run markers, including `last-export.json` written by `export-solution` Phase 7.1) writes to `<projectRoot>/docs/alm/`, not the project root. Always resolve paths through `scripts/lib/alm-paths.js` (`almPath(root, 'lastDeploy')`, `almPath(root, 'planContext')`, etc.) and call `ensureAlmDir(root)` once before the first write. Never inline a raw path string. Files that intentionally stay at the project root: `.solution-manifest.json` (referenced by non-ALM skills too), `.datamodel-manifest.json` (owned by `setup-datamodel`, not ALM), `.alm-config.json` (user-authored override), `.alm-deferred` (opt-out marker), `deployment-settings.json` (Microsoft-standard schema). When you add a new ALM artifact, add the key + filename to `FILE_NAMES` in `alm-paths.js`, then write through the helper.
+- **New skills must be added to `README.md`** — Whenever you add a new user-invocable skill under `skills/`, you must also document it in [`README.md`](README.md) under the appropriate section (Site scaffolding and deployment / Data modeling / Backend integration / Security and access / ALM and CI/CD / Polish / Support), update the skill count in the `## Skills` intro, and — if the skill is part of the recommended end-to-end flow — update the **Typical Workflow** code block. The README is the user-facing source of truth for what the plugin can do; an undocumented skill is effectively invisible to users browsing the marketplace.
 
 ## Skill Development Conventions
 

plugins/power-pages/README.md

@@ -38,7 +38,7 @@ This keeps hook behavior in one place and avoids relying on skill-frontmatter ho
 
 ## Skills
 
-The plugin provides 15 skills that cover the full lifecycle of a Power Pages code site — scaffolding, deployment, data modeling, backend integration, authentication, testing, and auditing. Each skill is invoked conversationally — just describe what you want to do.
+The plugin provides 29 skills that cover the full lifecycle of a Power Pages code site — scaffolding, deployment, data modeling, backend integration, authentication, ALM and CI/CD, security review, testing, and auditing. Each skill is invoked conversationally — just describe what you want to do.
 
 ### Site scaffolding and deployment
 
@@ -75,7 +75,7 @@ Provisions a website record in your Power Platform environment so your site is a
 
 #### `/test-site`
 
-> "Test my deployed site at https://contoso.powerappsportals.com"
+> "Test my deployed site at <https://contoso.powerappsportals.com>"
 
 Runtime-tests a deployed, activated site using a real browser (via the bundled Playwright MCP). Crawls discoverable links, verifies pages render, captures network traffic for API calls, and produces a test report.
 
@@ -195,6 +195,160 @@ Audits existing table permissions on a deployed or in-progress site by analyzing
 - Cross-references code usage, web roles, and Dataverse schema
 - Suggests concrete fixes for each issue
 
+#### `/scan-site`
+
+> "Scan my production site for vulnerabilities"
+
+Runs a security scan on a deployed Power Pages site, fetches the latest scan report, and produces a plain-language summary of vulnerabilities by severity.
+
+- Scans the live site's public surface for vulnerabilities
+- Fetches and explains the latest scan report
+- Surfaces issues grouped by severity
+
+#### `/manage-firewall`
+
+> "Block traffic from a specific country and add a rate limit to /login"
+
+Inspects and configures the web application firewall (WAF) in front of a Power Pages production site. Walks you through enabling protection and managing custom rules.
+
+- Lists current WAF state and recommends enabling protection when off
+- Adds, updates, or removes custom rules — IP blocks, country blocks, path blocks, rate limits
+- Protects pages from brute-force attempts and bot traffic
+
+#### `/manage-headers`
+
+> "Fix my CSP errors and harden cookie settings"
+
+Inspects and configures the security headers a Power Pages site sends to browsers — Content Security Policy, frame and clickjacking protection, cross-origin sharing, cookie behavior, and related site settings.
+
+- Identifies gaps in browser security headers
+- Walks through fixes for CSP, CORS, cookies, and embedding policy
+- Updates the corresponding site settings
+
+#### `/security-review`
+
+> "Do a full security review before we ship"
+
+Runs a guided, end-to-end security review of a Power Pages site and consolidates every finding into one HTML report covering the live site, browser headers, firewall, authentication, and role-based permissions.
+
+- Orchestrates `/scan-site`, `/manage-headers`, `/manage-firewall`, `/audit-permissions`, and auth checks
+- Consolidates findings into a single HTML report
+- Suitable for release-readiness or live-site monitoring
+
+### ALM and CI/CD
+
+#### `/plan-alm`
+
+> "Plan how to promote this site to staging and production"
+
+Orchestrator skill that creates an ALM (Application Lifecycle Management) plan for deploying a Power Pages site across environments. Gathers your promotion strategy, target environments, and approval requirements, generates a visual HTML plan, and after your approval executes the plan by calling the right ALM skills in sequence.
+
+- Detects project state (config, manifests, current environment)
+- Branched flow for Power Platform Pipelines or manual export/import
+- Generates `docs/alm-plan.html` for review and approval
+- Dispatches to `setup-solution`, `setup-pipeline`, `export-solution`, `deploy-pipeline`, or `import-solution`
+
+> [!TIP]
+> `/plan-alm` is the front door for any ALM intent. Use it instead of jumping straight to individual ALM skills when you want to deploy to staging, ship to production, or set up CI/CD.
+
+#### `/setup-solution`
+
+> "Package my site into a solution for ALM"
+
+Creates a Dataverse publisher and solution, then adds Power Pages site components to the solution for ALM and deployment management.
+
+- Creates publisher and solution via OData API (with duplicate detection)
+- Adds website and web role components via `AddSolutionComponent`
+- Writes `.solution-manifest.json` for downstream skills
+- Publisher prefix is irreversible — requires explicit confirmation
+
+#### `/export-solution`
+
+> "Export the solution as a zip for deployment"
+
+Exports a Dataverse solution containing Power Pages site components as a zip file, ready for deployment to another environment.
+
+- Choose managed (locked for downstream environments) or unmanaged (editable)
+- Triggers `ExportSolutionAsync` and polls until complete
+- Bumps the solution version on every export so each zip is strictly increasing
+- Verifies the zip contains a valid `Solution.xml`
+
+#### `/import-solution`
+
+> "Import this solution zip into the staging environment"
+
+Imports a Dataverse solution zip into a target environment, with optional staged import for dependency checking before committing.
+
+- Optional `StageSolution` pre-flight to detect missing dependencies
+- `ImportSolutionAsync` with polling until complete
+- Writes `docs/alm/last-import.json` marker
+- Surfaces per-component import results
+
+#### `/setup-pipeline`
+
+> "Set up a Power Platform Pipeline for automated deployments"
+
+Sets up a Power Platform Pipeline for automated Power Pages deployments. Power Platform Pipelines is Microsoft's native CI/CD tool built into the platform — no external infrastructure required.
+
+- Auto-discovers host environment via `RetrieveSetting('DefaultCustomPipelinesHostEnvForTenant')`
+- Creates `deploymentenvironments`, `deploymentpipelines`, and `deploymentstages` records
+- GitHub Actions and Azure DevOps platforms show coming-soon guidance
+- Writes `docs/alm/last-pipeline.json` and `docs/pipeline-setup.md`
+
+#### `/deploy-pipeline`
+
+> "Deploy the site to staging via my pipeline"
+
+Triggers a Power Platform Pipeline deployment run for a Power Pages solution. Validates the package, optionally configures deployment settings, then deploys and polls for completion.
+
+- Pre-flight check on `blockedattachments` to proactively unblock `.js`/`.css` (saves a wasted ~60-min import)
+- `ValidatePackageAsync` before deploying surfaces validation issues early
+- Optional environment variable / connection reference overrides per stage
+- Final consent gate before the deploy actually fires
+
+#### `/ensure-pipelines-host`
+
+> "Make sure my tenant has a Power Platform Pipelines host"
+
+Ensures the tenant has a usable Power Platform Pipelines host environment before any pipeline operation runs. Detects host state via the same resolution order as the Power Apps UI; if no host is bound, provisions a new **Platform Host** (recommended, idempotent) or guides through a **Custom Host** install.
+
+- Detects host state from org-db setting, BAP env metadata, or default-custom-host setting
+- Idempotent Platform Host fast-path (~3–5 min)
+- Custom Host fast-path or manual PPAC install fallback
+- Writes a host-check artifact other ALM skills consume
+
+#### `/force-link-environment`
+
+> "This environment is already linked to another pipelines host — force-link it"
+
+Force-links a development or target environment to a Power Platform Pipelines host, overriding any existing association with a previous host. Calls the documented `ManageEnvironmentStamp` Dataverse action (the API behind the "Force Link" button in the Deployment Pipeline Configuration app).
+
+- Use when you hit "environment is already associated with another pipelines host"
+- Required explicit consent gate — destructive to the previous host (makers lose pipeline access)
+- Reversible by re-running from the previous host
+- Writes `docs/alm/last-force-link.json`
+
+#### `/configure-env-variables`
+
+> "Make these site settings environment-specific so they differ between dev and prod"
+
+Configures environment variables for Power Pages site settings to support ALM across environments. Creates environment variable definitions in Dataverse, guides you through linking site settings via the Power Pages Management app, adds the variables to the solution, and generates a `deployment-settings.json` file with per-stage override values.
+
+- Creates `environmentvariabledefinition` records (String or Secret type)
+- Generates `deployment-settings.json` ready for `deploy-pipeline` to consume
+- Routes credentials (ClientSecret, ConsumerKey, etc.) to Key Vault-backed secret env vars
+
+#### `/diagnose-deployment`
+
+> "My last deploy failed — figure out why"
+
+Surfaces PAC CLI upload errors and Dataverse async operation errors, pattern-matches against a known failure catalog, and optionally auto-fixes identified issues.
+
+- Re-runs `pac pages upload-code-site` in capture mode to surface upload errors
+- Queries recent Dataverse async operation failures
+- Pattern matches against `references/deployment-error-catalog.md`
+- Offers auto-fixes with explicit per-fix user confirmation
+
 ### Polish
 
 #### `/add-seo`
@@ -246,21 +400,24 @@ The plugin ships with two MCP servers configured in `.mcp.json` — they start a
 A common end-to-end workflow looks like this:
 
 ```
-1.  /create-site        →  Scaffold + design + build pages
-2.  /deploy-site        →  Upload to Power Pages environment
-3.  /activate-site      →  Provision a public URL
-4.  /setup-datamodel    →  Create Dataverse tables
-5.  /add-sample-data    →  Populate tables with test records
-6.  /integrate-backend  →  Pick the right backend approach (Web API / Server Logic / Cloud Flow)
-7.  /create-webroles    →  Define access roles
-8.  /setup-auth         →  Add login/logout + role-based UI
-9.  /audit-permissions  →  Verify table permissions are safe
-10. /add-seo            →  Search engine optimization
-11. /deploy-site        →  Push final changes live
-12. /test-site          →  Runtime smoke test on the live URL
+1.  /create-site            →  Scaffold + design + build pages
+2.  /deploy-site            →  Upload to Power Pages environment
+3.  /activate-site          →  Provision a public URL
+4.  /setup-datamodel        →  Create Dataverse tables
+5.  /add-sample-data        →  Populate tables with test records
+6.  /integrate-backend      →  Pick the right backend approach (Web API / Server Logic / Cloud Flow)
+7.  /create-webroles        →  Define access roles
+8.  /setup-auth             →  Add login/logout + role-based UI
+9.  /audit-permissions      →  Verify table permissions are safe
+10. /add-seo                →  Search engine optimization
+11. /deploy-site            →  Push final changes live
+12. /test-site              →  Runtime smoke test on the live URL
+13. /security-review        →  Full security review (headers, firewall, scan, permissions)
+14. /plan-alm               →  Plan multi-environment promotion
+15. /deploy-pipeline        →  Promote through staging → production
 ```
 
-Steps can be run independently — you don't need to follow this exact order. Each skill checks its own prerequisites and will tell you if something is missing. If something goes wrong, `/report-issue` opens a pre-filled GitHub issue.
+Steps can be run independently — you don't need to follow this exact order. Each skill checks its own prerequisites and will tell you if something is missing. If something goes wrong, `/diagnose-deployment` pattern-matches deployment errors and `/report-issue` opens a pre-filled GitHub issue.
 
 ## Running Without Interruption