feat/pwsh templates

README.md

@@ -1,10 +1,12 @@
 # OwnerLens
 
-OwnerLens is a local Azure ownership report. It reads exported Azure resource
-and Microsoft Entra snapshot files, then helps identify likely owners for Azure
-subscriptions and resource groups using tags, cost center mappings, role
-assignments, managed identities, service principals, application registrations,
-groups, and activity-log evidence.
+OwnerLens is a local-first Azure and Microsoft Entra ownership evidence tool. It
+reads snapshots from `./data`, resolves likely accountable owners for Azure
+resources and workload identities, shows confidence and evidence trails, and
+exports owner mappings, gaps, and remediation assignments to CSV or JSON.
+
+Owner signals include Azure tags, cost center mappings, Azure RBAC, groups,
+managed identities, service principals, app registrations, and activity logs.
 
 The application is intended to: 
 
@@ -45,94 +47,89 @@ flowchart TD
 
 ## Requirements
 
-- PowerShell 7 or Windows PowerShell for snapshot export scripts
-- Azure PowerShell and Microsoft Graph PowerShell modules when exporting data
-
-## Run With npx
+- PowerShell 7 (`pwsh`) on `PATH` for the OwnerLens module and snapshot
+  collectors. Do not use Windows PowerShell (`powershell.exe`).
+- Node.js and npm for building from a source checkout.
+- Azure PowerShell and Microsoft Graph PowerShell modules when collecting data:
 
-```bash
-npx ownerlens start
+```powershell
+Install-Module Az -Scope CurrentUser
+Install-Module Az.ManagedServiceIdentity -Scope CurrentUser
+Install-Module Microsoft.Graph -Scope CurrentUser
 ```
 
-`npx ownerlens start` starts the packaged app on `127.0.0.1`, creates `./data`
-in the directory where you run the command, and reads snapshot files from that
-directory. Open the local URL printed by the command, usually
-`http://127.0.0.1:4173`. When running from a source checkout, run `npm run build`
-before `npm run start`.
-
-## Create Snapshot Files
-
-OwnerLens expects these files by default:
-
-- `data/snapshot.json` for Azure resources, role assignments, managed
-  identities, and optional Azure Monitor activity logs
-- `data/entra-snapshot.json` for Microsoft Entra service principals, application registrations, and groups
-
-Sign in to Azure:
+Run all PowerShell commands in `pwsh`.
 
-```powershell
-Connect-AzAccount
-```
+## Run
 
-Sign in to Microsoft Graph:
+Build the PowerShell module from a source checkout:
 
 ```powershell
-Connect-MgGraph -TenantId "<tenant-id>" -Scopes "Application.Read.All","Group.Read.All","Directory.Read.All"
+pwsh ./scripts/build-windows-runtime.ps1
+pwsh ./scripts/build-powershell-module.ps1
 ```
 
-Import the PowerShell module:
+Start the local app from `pwsh`:
 
 ```powershell
 Import-Module ./artifacts/OwnerLens/OwnerLens.psd1 -Force
+Start-OwnerLens -DataPath ./data
+Open-OwnerLens
 ```
 
-Start OwnerLens from PowerShell on Windows:
+`Start-OwnerLens` binds to `127.0.0.1`, chooses a free port, creates the data
+directory, and stores runtime state under `$env:LOCALAPPDATA\OwnerLens`.
+
+Use an explicit port or data directory when needed:
 
 ```powershell
-Start-OwnerLens
-Open-OwnerLens
-Get-OwnerLensStatus
-Stop-OwnerLens
+Start-OwnerLens -Port 4174 -DataPath C:\OwnerLensData
 ```
 
-`Start-OwnerLens` starts the local app on `127.0.0.1` using a free port and
-stores runtime state under `$env:LOCALAPPDATA\OwnerLens`. To use a specific data
-directory or port, pass them explicitly:
+## Create Snapshots
 
-```powershell
-Start-OwnerLens -DataPath C:\OwnerLensData -Port 4174
-```
+Collectors write these files by default:
 
-Open browser  - even localhost is secured with token
-```powershell
-Open-OwnerLens
-```
+- `data/snapshot.json` for Azure subscriptions, resource groups, resources,
+  managed identities, role assignments, and optional activity logs.
+- `data/entra-snapshot.json` for Microsoft Entra service principals,
+  application registrations, groups, and group membership facts.
 
-Create the resource snapshot:
+Sign in from `pwsh`:
 
 ```powershell
-Invoke-OwnerLensCollectAzure -SubscriptionIds "sub-id-1,sub-id-2"
+Connect-AzAccount
+Connect-MgGraph -TenantId "<tenant-id>" -Scopes "Application.Read.All","Group.Read.All","Directory.Read.All"
 ```
 
-Create the Entra snapshot:
+Collect snapshots from `pwsh`:
 
 ```powershell
+Import-Module ./artifacts/OwnerLens/OwnerLens.psd1 -Force
+Invoke-OwnerLensCollectAzure -SubscriptionIds "sub-id-1,sub-id-2"
 Invoke-OwnerLensCollectEntra -TenantId "<tenant-id>"
 ```
 
 More collector options are documented in [tools/README.md](tools/README.md).
 
-Snapshot files can contain tenant, subscription, resource, identity, group, and
-activity-log metadata. Review them before sharing. Files matching
+Snapshot files can contain sensitive tenant, subscription, identity, group,
+credential, and activity-log metadata. Review them before sharing. Files matching
 `data/*snapshot.json` are ignored by git.
 
 ## Development
 
 See [DEVELOPMENT.md](DEVELOPMENT.md) for local development, testing, dependency
-graph, project structure, and ownership rule configuration notes.
+graph, and ownership rule configuration notes. See [CONTRIBUTING.md](CONTRIBUTING.md)
+for contribution expectations.
 
-Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for local
-development expectations.
+Common checks:
+
+```powershell
+npm run build
+npm test
+npm run test:all
+npm run lint
+```
 
 ## License