Shieldsmith — documentation for Power Platform solutions, straight from the export zip
Documentation for Power Platform solutions, straight from the export zip.
Shieldsmith reads solution.xml, customizations.xml and the definition folders inside a solution export, and produces the documentation nobody was otherwise going to write: every component, every table with its columns and requirement levels, every relationship with its cardinality, an entity relationship diagram, a Word document, and a real Visio .vsdx.
No environment connection, no admin rights. Just the file that got emailed to you.
The code is public and buildable today. Installer and portable downloads follow the first code-signed release.
Read the definition, not the documentation.
The solution file is what is actually true. Anything the export does not settle becomes a diagnostic note in the output rather than a plausible value, and inferred relationships are modelled separately from declared ones and always labelled as inferred.
The documentation problem
The Power Platform makes it fast to build and slow to explain. The debt is invisible until the person who built the solution leaves, or an auditor asks a question nobody can answer from the portal.
Hand-written documentation is out of date the first time someone edits a flow, and nobody ever goes back to fix it.
A flow's real order lives in runAfter, not document order. A process flow's stages exist only as workflow activities. Nobody is reading that by hand.
Business process flow stages and plugin registrations are absent from every other tool that reads an export, so they get written up from memory or not at all.
Needing a .NET runtime first, or needing to build from source, is enough friction that the documentation quietly never gets generated.
What it reads
Extracted fact, taken from the export itself. Two of these are documented here and nowhere else that reads a solution zip.
Every component in the solution, typed, with GUIDs resolved to names wherever the export allows.
Display and logical names, type, requirement level parsed from the real export tokens, primary key and primary name markers, alternate keys, forms down to tab, section and field level with their script libraries, and views with their columns.
One-to-many with the lookup column and cascade behaviour, many-to-many with the intersect table named, plus implicit lookups — owner, customer, lookups declared outside the solution — always labelled inferred rather than presented as declared fact.
Parsed from their clientdata JSON: the trigger decoded and the action tree ordered by runAfter rather than document order, including Scope, If, Switch and Foreach nesting, with connectors and connection references.
Screens, the control tree, authored formulas, data sources and derived variables, read out of the .msapp. Verified against real apps, including one of 321 controls.
Topics, trigger phrases, tools and knowledge sources, read from the bots folder and its YAML payloads.
Stages in order, and the column each step writes — read out of the Windows Workflow Foundation activities in the XAML, which is the only place that information exists.
Assemblies, types, and every registration with its message, table, stage, mode, rank and filtering columns — reconstructed from message GUIDs in customizations.xml.
Desktop flows with the Robin script parsed into subflows and steps, classic workflows, business rules and actions, choices, security roles with a privilege matrix, model-driven apps, sitemap navigation, web resources, and environment variables with definitions joined to values — secrets never printed.
What it writes
One extraction, rendered for whoever needs to read it.
Word (.docx)
Cover page, a table of contents that fills in on open, the ERD embedded, per-table detail, relationships, automations, roles and apps — plus a parsing-notes section stating anything the export did not fully settle.
Markdown
One file per table and per cloud flow plus an index, ready to drop into a GitHub or Azure DevOps wiki.
Visio (.vsdx)
A genuine OPC package Visio opens, with entity shapes and relationship connectors positioned to match the ERD.
Diagrams
An ERD and a chart per cloud flow, drawn by a built-in layered layout engine with no dependencies. Mermaid is available with --mermaid but is not the default. Above 25 tables the ERD drops to table names and says so.
Canonical JSON
The complete extraction, and the shared substrate every other output and the AI features are built on.
Claude Code docpack
A folder holding the canonical JSON, the full Markdown documentation, a CLAUDE.md with grounding rules and a question-answering skill.
AI, four ways — all on your own access
Shieldsmith never holds an API key of its own and never bills anyone. Optional, off by default, and the document is complete without it.
Your Anthropic or OpenAI key
Pick a provider in the app and paste your key once — stored encrypted with Windows DPAPI. Shieldsmith adds plain-English interpretation to the Word and Markdown output.
Your installed Claude Code
Shieldsmith detects the claude CLI and drives it headless, so there is no key to manage and no separate bill.
A docpack for your own terminal
Export for Claude Code writes a folder you can open and interrogate — the extraction, the docs, the grounding rules and a question-answering skill.
An MCP server
Shieldsmith.Mcp.exe speaks MCP over stdio and exposes load_solution, get_entity, get_flow, get_canvas_app, get_agent, get_relationships and search, so Claude Code queries a parsed solution live.
How AI content is treated
- Renders only inside visually distinct blocks captioned with provider, model and date
- Never inside a fact table, and never to fill a parser gap
- A consent dialogue shows the exact payload before anything leaves the machine
- Environment variable values redacted by default
- The document is complete with AI switched off
Three ways to run it
Desktop app
Drop a solution zip anywhere on the window and press Analyse solution. The header states what the machine can actually do before you ask it to — whether Mermaid can render, whether Graphviz is installed, whether Claude Code is on the PATH. A missing engine is a supported state, never an error.
Command line
shieldsmith generate, export-pack, diagram, analyze, json, erd, vsdx, word, validate-docx for OpenXML validation in CI, and check to report what this machine can do.
MCP server
claude mcp add shieldsmith — and Claude Code can query a parsed solution live. get_canvas_app returns the overview by default and a screen's full control tree only when you name a screen, so a large app cannot flood the context by accident.
shieldsmith generate <solution.zip> -o <dir> [--word] [--markdown] [--erd] [--vsdx] [--json]
[--ai anthropic|openai|claude-code] [--ai-model <model>]
shieldsmith export-pack <solution.zip> [outdir] folder for your own Claude Code terminal
shieldsmith check what this machine can doGetting it installed
Two ways in, both self-contained. There is no .NET runtime to install first, which is the single most common complaint against the alternatives.
Installer
About 53 MB to download, 178 MB installed. It installs for you alone, so there is no administrator prompt and it works on a locked-down work machine. Start Menu entry, optional desktop shortcut, optional PATH entry for the command line tool. Uninstall removes everything it added, including the PATH entry.
Portable zip
Unzip anywhere and run it. Nothing is written to the registry and nothing is installed. Use this if you cannot install software at all, or want to run it from a USB stick.
Neither is published yet. Both follow the first code-signed release — until then Windows would warn about an unrecognised publisher, which is exactly the friction this project set out to remove.
How it works
- 1
Export a solution
Managed or unmanaged, from the maker portal — or take the zip straight out of your source-controlled repo.
- 2
Drag it onto the window
Drop the .zip anywhere on the Shieldsmith window and press Analyse solution. Or pass it to the CLI.
- 3
Write what you need
A Word document, a Markdown set, a Visio diagram, or a docpack for Claude Code.
Compared with PowerDocu
PowerDocu is the established free tool in this space and is genuinely good, particularly on canvas apps. An honest comparison — including where it is still ahead.
 Shieldsmith | PowerDocu | |
|---|---|---|
| Runs offline from the export zip | Yes | Yes |
| Dataverse table detail | Columns, types, requirement levels, keys, forms, views | Internal column names |
| Entity relationship diagram | Yes, with implicit lookups labelled | No |
| Visio output | Real .vsdx | No |
| AI interpretation | Four options, all your own access | None |
| MCP server / Claude Code pack | Yes | No |
| Canvas app internals | Screens, control tree, authored formulas, data sources, variables | Screens, controls, properties |
| Flow diagrams as images | Yes, Mermaid or the built-in engine | Yes |
| Mermaid source you can paste anywhere | Yes | No |
| Copilot Studio agents | Topics, trigger phrases, tools, knowledge | Yes |
| Desktop flows | Robin script parsed into subflows and steps | Yes |
| Business process flows | Stages in order, and the column each step writes | No |
| Plugins | Assemblies, types, and every registration with message, table, stage, mode, rank and filtering columns | No |
| Diagrams on a large solution | Built-in engine, degrades rather than failing | Rendered per flow and app |
| AI models (AI Builder) | No | Yes |
| Runtime required | None (self-contained) | .NET runtime |
Business process flows and plugins are documented here and nowhere else that reads an export. PowerDocu remains ahead on AI Builder models, and its canvas app coverage is longer-established than Shieldsmith's.
How it's verified
Every diagram bug found so far returned success and produced a wrong picture. Trusting return values would have shipped all of them.
- 65 unit tests across Core, Outputs, Ai and Diagrams
- Word output validates clean under OpenXmlValidator, checked by a CLI verb rather than by eye
- Diagrams checked by opening the rendered image — every diagram bug so far returned success and produced a wrong picture
- The interface checked by rendering it: one PNG per tab, per diagram, and of the About and consent windows
- MCP driven end to end over stdio, sequentially, as a real client does
- The installer installed, not just compiled — silent install, run, PATH added and removed, uninstall verified byte for byte
Who it's for
Power Platform consultants
Hand over documentation that matches the build, from the same zip you were going to deliver anyway.
Centres of Excellence
A typed inventory of what a solution actually contains, including the component types nothing else reads.
Internal makers and IT teams
Answer "what does this flow actually do?" without opening the designer — useful when the person who built it has moved on.
Auditors and change boards
A dated, readable record of a solution taken from its definition rather than from someone's recollection of it.
Still open
What is honestly still missing at v0.9.0, stated rather than buried.
Code signing
The release is not signed yet, so Windows shows an unrecognised publisher warning. The signing script is ready and documents both routes; it needs a certificate.
winget
winget install Shieldsmith needs a signed installer at a public URL first, so it follows the first signed release rather than shipping with it.
AI Builder models
The one component type PowerDocu documents and Shieldsmith does not.
A readable ERD for a very large solution
Above roughly 60 tables the single overview diagram is a hairball whatever is done to it. A dense relationship graph is not a DAG and wants a different layout, or per-table neighbourhood diagrams instead of one overview.
Visio verification
The .vsdx passes structural tests, but Visio is not installed on the development machine, so a generated file wants opening in real Visio before shipping a change to the writer.
Ideas on the table
Not built, not promised — candidates for where Shieldsmith goes after the first signed release. If one of these is the thing that would make it useful to you, say so and it moves up.
Diff between two solution versions
Point Shieldsmith at two exports of the same solution and get added, removed and modified components with the properties that changed. Release notes that write themselves.
Governance and best-practice findings
Flag what reviewers always ask about: hard-coded GUIDs and URLs, missing error handling, unused components, premium connector usage and naming-convention drift.
Cross-component impact mapping
Beyond the ERD — which flows touch which tables, which apps depend on which connectors, and what breaks if a component is removed.
Interactive HTML output
A self-contained, searchable, cross-linked site alongside the Word and Markdown, shareable as a single folder.
PDF output
A fixed, signed-off snapshot for change boards and audits.
Pipeline tasks
Azure DevOps and GitHub Actions steps so documentation is regenerated and published on every release instead of going stale in a SharePoint folder.
Questions
Want it pointed at your solutions?
The code is open and the first signed release is close. Tell me what your team needs documented and I'll let you know the moment there is something to install.
- Told first when it ships
- Input into what comes next
- No tenant access, ever