Your first assessment

This walkthrough takes you from an empty app to an exported report. It assumes the app is installed and licensed, and that an AI key is configured for the two generation steps. If you just want to explore first, load the demo environment from Settings instead of importing your own data.

Step 1: Create a project

1. Open Projects in the sidebar and click New Project.
2. Give the project a name, and optionally a client name, project type, and notes.
3. Save. You land on the project page, which tracks the five workflow steps and marks each one done as you complete it.

Step 2: Add your data

Open Upload Data inside the project. There are three ways in: file upload, a live Azure connection, or manual entry.

Option A: Upload a file

Drag a file onto the dropzone or click Browse Files. Accepted formats:

• CSV (.csv), including the export produced by the Azure Portal.
• JSON (.json): a top-level array of resources, or an Azure REST style envelope with a value array.
• Excel (.xlsx or .xls).

One file at a time, up to 10 MB. The parser recognizes common column names for resource name, type, resource group, subscription, location, SKU, tags, and resource ID, so portal exports work without editing. UTF-8 and UTF-16 with a byte order mark are both handled, including PowerShell Export-Csv output.

Where to get an export from Azure:

• Azure Portal: open All resources, then use Export to CSV in the toolbar.
• Azure Resource Graph Explorer: run a resources query and download the results.
• Azure CLI: az resource list > resources.json produces a JSON array the app reads directly.

Option B: Connect live to Azure

The Azure Connection tab discovers resources directly from the Azure Resource Manager API using a service principal (an Entra ID app registration).

Minimum permissions

Reader, assigned at subscription scope. That is the whole requirement. Cloud Discovery only ever issues GET requests to Azure Resource Manager: it lists subscriptions, lists resources, and reads resource properties. It never creates, modifies, or deletes anything, so no Contributor or Owner role is needed and none should be granted.

Two points worth raising when you ask a client for access:

• It cannot read your secrets. Reader grants the ARM control plane only. For a Key Vault, that means the vault's name, region, and settings such as soft-delete and RBAC configuration. The secrets, keys, and certificates inside are data-plane objects and require separate permissions the app never requests and cannot use.
• It cannot change anything. A read-only principal cannot start, stop, resize, or delete a resource, even by accident.

Create the principal and assign the role in one command:

az ad sp create-for-rbac \
  --name "cloud-discovery-readonly" \
  --role Reader \
  --scopes /subscriptions/<SUBSCRIPTION_ID>

The output gives you the three values the connection profile needs: tenant (Tenant ID), appId (Client ID), and password (Client Secret). The secret is shown once, so capture it immediately.

If a client will not grant subscription-wide read access, scope the assignment to a single resource group instead by passing /subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<GROUP>. Discovery then covers only that group, which is enough for a scoped engagement.

With the principal created:

1. Create a connection profile with your Tenant ID, Client ID, and Client Secret. The secret is stored in the macOS Keychain, never in the database.
2. Click Test Connection to confirm the credentials can list your subscriptions.
3. Choose a scan mode: Quick Scan lists every resource with basic metadata; Deep Scan additionally inspects the configuration of common resource types (VMs, VNets, NSGs, storage accounts, Key Vaults, SQL, App Service, and more).
4. Run the discovery. A scan summary shows what was discovered, imported, and inspected.

Deep Scan is worth the extra time: the captured configuration feeds higher-confidence relationship mapping and richer findings.

Option C: Manual entry

The Manual Entry tab adds individual resources by name and type, useful for filling gaps in an incomplete export. Manual adds never clear existing data.

Step 3: Review resources and map relationships

1. Open View Resources. The page shows counts, a distribution chart by type, and a table of every resource. Click a row for details: configuration highlights from Deep Scan, tags, and per-resource findings.
2. Click Map Relationships. The app infers connections between resources from deep-scan evidence and rule-based patterns, then generates findings such as missing NSGs, public storage access, or the absence of a backup strategy.
3. Review the relationships card (grouped by confidence) and the findings list. This is deterministic output: the same data produces the same findings every time.

Step 4: Generate the summary

Open AI Summary and click Generate Summary. One AI call (typically 15 to 30 seconds) produces an environment overview: architecture, resource distribution, patterns, risks and concerns, missing documentation, and onboarding notes. You can regenerate at any time; regeneration replaces the whole summary.

Step 5: Generate documentation

Open Documentation and pick a content template. The template decides what the report says and for whom:

Generation runs section by section, and each section is saved as soon as it completes. When it finishes:

• Click any section in the sidebar to read it, edit it as Markdown, or regenerate just that section.
• Edited sections are marked so you can tell your words from the AI's.
• If a run is interrupted, completed sections are kept; regenerate the rest individually.

Step 6: Export the report

1. Open Export. The page shows which content is ready and which visual style is selected.
2. Click Change style to open the gallery: 14 visual styles grouped into Modern, Classic, Technical, and Expressive. The style changes how the report looks, not what it says.
3. Optionally set your organization name, footer text, accent color, font, and logo in the Customization panel, and toggle the cover page, findings, resource appendix, or compact mode.
4. Click Preview. The preview renders the actual PDF, so what you see is exactly what you export.
5. Export as Professional PDF or Markdown, and choose where to save in the native dialog.

Every export is recorded on the Reports page in the Library, with the file path, project, format, and date.

Where to go next

• Run a Migration Assessment to classify what can move between subscriptions or resource groups.
• Open the Topology Draft for a network diagram you can refine and export as PNG or PDF.
• Ask Scout questions about the environment: it answers from your actual data and shows every lookup it makes.