How to Audit Your Revit Family Library in One Picture

Q: Why does the Health column sometimes show only "Not Scanned"?

The Health column reads the health_status field that the Family Reviser Health tab populates when you run Quick Scan or Deep Scan. If the scan has not run yet - common when you have just opened the project - every family carries an empty status and rolls into a single "Not Scanned" bucket. The Alluvial tab does not auto-trigger the scan because the scan can take two to eight seconds on a large model and would freeze the window. Instead, when the Not Scanned bucket dominates (over 80% of families), the chart shows an in-panel CTA that switches you to the Health tab and starts the scan.

Q: Can an AI agent query the family inventory through MCP?

Yes, after you opt into the Phase 4 cache. Set PYVOID_FAMILY_ALLUVIAL_ROLLUP_ENABLED=1 in the environment before launching Revit and every Family Reviser collection writes a JSON inventory snapshot to %APPDATA%\Pyvoid\cache\family_inventory\. The MCP server then exposes get_family_alluvial_payload(project_path, columns) which returns the same JSON shape the in-app chart uses. Agents can request portfolio rollups (no project_path) or per-project payloads with custom column orderings.

Open Family Reviser on a real project and the Browse tab paints 600 to 1,000 rows. You came in to answer one question - are we carrying too many in-place families this week? - and instead you are scrolling. Filter by category. Mental tally. Switch tabs. Cross-reference Health. Open a fresh email and try to summarize what you just saw. Twenty minutes evaporate before you have written a single sentence to send upstairs.

The Browse grid is the right tool to act on a family. It is the wrong tool to narrate a family library. Narration needs shape - which categories dominate, where the in-place creep lives, how much of the inventory still has open health issues. The Browse grid tells you everything and shows you nothing.

This is what the new Alluvial tab in Family Reviser solves. One picture. One screenshot. One email.

What Is the Family Reviser Alluvial Tab?

The Family Reviser Alluvial is a flow-diagram tab inside the Pyvoid Family Reviser window that visualizes a Revit project's loaded-family inventory across three dimensions - Category, Source, and Health Status - in a single screenshot-ready chart. Node widths are proportional to family counts so the dominant categories and the worst-health buckets read at a glance. Clicking any node cross-filters the Browse and Health tabs to the families flowing through it.

It ships in the existing free Pyvoid Family Reviser tool tier. There is no new ribbon button to learn, no new pushbutton to install, no new file to manage. Open the same window you already use for renames and types, click the sixth tab, and the picture is there.

The tab inherits Pyvoid's read-only safety contract. Zero Revit transactions, zero element writes, zero side effects beyond the cross-filter on sibling tabs. The persona-load-bearing concern - "if it breaks a model, I'm the one explaining it to the principal" - has a clean architectural answer here: this tab cannot break a model because it cannot write to one.

The Three Columns

The default view renders three columns left to right. Each column is a categorical dimension of the family inventory, and the ribbons between columns are weighted by the number of families flowing through each pair.

Column 1 - Category

The first column is Revit's category_name for each loaded family - Doors, Windows, Furniture, Casework, Generic Models, Specialty Equipment, Plumbing Fixtures, and so on. The widest node is the category carrying the most families. This is the answer to "where is the inventory concentrated?"

If the project carries more than 20 distinct categories - common on multi-discipline jobs - the chart caps the column at 19 individual nodes plus a single Other rollup. Hover the Other node and the tooltip lists the rolled-up category names. The cap is deterministic: same input, same set of 19 retained nodes, same rolled-up tail every time.

Column 2 - Source

The second column is derived. It splits every family into one of three buckets based on how it got into the project:

In-Place - created inside the project file via Massing & Site or model-in-place tools. These cannot be reused across projects, do not render as efficiently as loadable families, and quietly accumulate when junior modelers default to in-place geometry instead of opening the Family Editor.
Loadable - standard .rfa families loaded from a library. Editable, schedule-friendly, the default standard.
Non-Editable - loaded families the user cannot open and edit in the current project (typically system or vendor families). Surfaced separately so they do not get lost in the Loadable bucket.

A widening In-Place ribbon is the visual equivalent of "the junior modelers are creating in-place families again." You did not need a query to find it. The picture told you.

Column 3 - Health Status

The third column buckets each family by the result of the last Health tab Quick Scan: Clean, Info, Warning, Error. Families that have not been scanned land in a fifth bucket called Not Scanned.

The Not Scanned bucket is deliberate. Auto-running Quick Scan when the Alluvial tab is opened would freeze the window for two to eight seconds on a large model - a textbook violation of the preview-before-apply principle. Instead the chart renders instantly with whatever scan state already exists. If the Not Scanned bucket dominates (over 80% of the families), an in-panel CTA appears: "Health not yet scanned. Click to run Quick Scan on the Health tab." One click switches tabs and starts the scan. Re-click the Alluvial tab once it finishes and the Health column repopulates with real buckets.

This is the entire trick. Render-now, scan-later. The chart is never the thing keeping you from a screenshot.

Click-to-Triage

Once the picture is on screen, the second job is acting on it. Click the Doors node in column 1 and the Browse tab filters to only the Doors families. The search box clears (so any prior search does not silently AND with the click). A toast in the status bar reads "Filtered to Category=Doors from Alluvial." A "Clear filter" chip appears in the Browse tab header. One click to scope, one click to release.

Clicking a node in the Health column does the same thing on both the Browse tab and the Health tab simultaneously. Click Error and you land on the families that need the most attention with two filtered grids ready to delegate.

Clicking a link (the ribbon between two nodes) filters on both endpoints. The Doors → In-Place ribbon scopes Browse to in-place doors only - the exact set you would have built by hand with two sequential filter operations. The picture became a query.

The Monday Email

The export button in the tab header writes the diagram to disk via the standard SaveFileDialog. Two formats:

PNG - universal paste into Outlook, Teams, Word, or PowerPoint. No cropping, no scaling, no theme retouching. The default filename is <project>_family_alluvial_<yyyymmdd>.png so two weeks of Mondays line up alphabetically in the export folder.
SVG - scalable, embeddable in the firm wiki, and open-able in any modern browser. Use this when the artifact will end up in a printed PDF cover or a vector-friendly presentation.

Both formats embed a metadata footer at the bottom: <project> | <YYYY-MM-DD> | Generated by FamilyReviserAlluvial v<version>. When the principal forwards the screenshot to a consultant six weeks later, the date and the source are baked into the image. There is no "what project is this" exchange.

The exported PNG is the entire Monday email. Two sentences of context, one image, the principal reads it on their phone between the 8am triage and the 9am meeting. Twenty minutes of scrolling-and-narrating becomes one minute of clicking, exporting, and pasting.

Phase 2 - Customizing the View

The fixed Category → Source → Health preset is the demo-conversion artifact. The retention-feature layer underneath lets the BIM Manager who already ships the Monday PNG customize what they are looking at.

Three picker dropdowns in the toolbar swap any column to one of five dimensions:

Category - the default first column.
Source - in-place / loadable / non-editable.
Health - Not Scanned / Clean / Info / Warning / Error.
Instance Bucket - 0 / 1-10 / 11-50 / 51+ instances. Surfaces library clutter (loaded families that nobody is actually placing).
Type Bucket - 1 / 2-5 / 6-20 / 21+ types. Surfaces the parametric monsters with too many types to maintain.

A 4-column toggle inserts the Instance Bucket column between Source and Health for the deeper view used in firm-wide BIM tip emails.

Hover any node and a tooltip surfaces the family count plus its share of the total. Hover the Other rollup and the tooltip additionally lists every category collapsed into it. The picture is now also a data table.

Phase 4 - Portfolio Rollup and AI Agents

Set the environment variable PYVOID_FAMILY_ALLUVIAL_ROLLUP_ENABLED=1 before launching Revit and every Family Reviser collection writes a JSON snapshot of the inventory under %APPDATA%\Pyvoid\cache\family_inventory\. The cache strips Revit-internal element IDs and the verbose health-issue lists - it carries only what the aggregator needs to repaint a chart - so a 1,000-family project lands at well under 200 KB on disk.

Two consumers read the cache:

A future portfolio-rollup view inside the Pyvoid HealthStudio that aggregates every cached project into a Project → Category → Health flow for the BIM Director who never opens individual project files.
The MCP tool get_family_alluvial_payload(project_path, columns). Point Claude or any MCP-aware agent at it and the same payload shape that paints the in-app chart returns as JSON, ready for programmatic queries: "which projects in our portfolio are over 30% in-place families?" or "give me a 4-column alluvial of Acme HQ scoped to Generic Models with the Health column dropped."

Reads do not require the feature flag - an agent can replay snapshots produced under an earlier flag-on session. Only writes are gated. This is the deliberate retention shape: opt in to the rollup once, accumulate snapshots over the next several Mondays, then either build the portfolio dashboard or hand the data to an agent.

Where the Alluvial Sits in Model Health

Family inventory is one of the five dimensions of Revit model health, alongside warning hygiene, view-template discipline, workset structure, and file performance. Most BIM Managers narrate all five every Monday. Three of them already have visualization tools in Pyvoid (Warning Visualizer for warnings, ReViewer for the audit composite, HealthRollup for the portfolio view). The Alluvial closes the loop on family inventory.

It also shifts the Family Reviser tool itself from a find-and-fix surface into a triage-then-find-and-fix surface. The previous default workflow opened on the Browse tab and hoped you knew what to search for. The new workflow opens on the Alluvial tab, lets you see where the work is, then click into the Browse / Health / Types / Rename tab that owns the cleanup. The picture is the table of contents.

If you are still building your Pyvoid stack, the Family Reviser is one of the ten Pyvoid tools to learn first for exactly this reason - one tool now answers a question that previously required scrolling.

Frequently Asked Questions

What is the Pyvoid Family Reviser?

Pyvoid Family Reviser is a modeless multi-tab Revit window for browsing the project's loaded family inventory, previewing batch family-name renames, managing types from the project environment, running Quick Scan and Deep Scan health checks, and exporting inventory and review reports. The Alluvial tab is the sixth tab in that window and ships in the same free tier as the rest of the tool.

Does the Alluvial tab change anything in my Revit model?

The Alluvial tab is read-only. It executes zero Revit API write operations - no transactions, no transaction groups, no parameter writes, no element edits. The only side effects of clicking a node are UI-level filters applied to the Browse and Health tabs in the same window, both of which display a "Clear filter" chip to restore the full list with one click.

Why does the Health column sometimes show only "Not Scanned"?

The Health column reads the health_status field that the Family Reviser Health tab populates when you run Quick Scan or Deep Scan. If the scan has not run yet - common when you have just opened the project - every family carries an empty status and rolls into a single "Not Scanned" bucket. The Alluvial tab does not auto-trigger the scan because the scan can take two to eight seconds on a large model and would freeze the window. Instead, when the Not Scanned bucket dominates (over 80% of families), the chart shows an in-panel CTA that switches you to the Health tab and starts the scan.

How do I get the chart into a Monday email?

Click the "Export PNG" button in the Alluvial tab header. The SaveFileDialog suggests a default filename like <project>_family_alluvial_20260430.png. Save it, then drag the file into Outlook, Teams, Word, or any other surface that accepts pasted images. The exported image already carries a metadata footer reading <project> | <YYYY-MM-DD> | Generated by FamilyReviserAlluvial v<version> so the recipient knows which project and which week the screenshot represents without you adding a caption.

What happens when a category column has more than 20 distinct values?

The chart caps each column at 20 nodes total. When a column has more than 20 unique values - common on the Category column for multi-discipline projects - the 19 largest-by-count are rendered individually and the rest aggregate into a single "Other" rollup node at the bottom. Hover the Other node and the tooltip lists every collapsed category name. The cap is deterministic: identical input always produces the identical 19 retained nodes plus the same rolled-up tail, so re-renders never reshuffle the picture.

Can an AI agent query the family inventory through MCP?

Yes, after you opt into the Phase 4 cache. Set PYVOID_FAMILY_ALLUVIAL_ROLLUP_ENABLED=1 in the environment before launching Revit and every Family Reviser collection writes a JSON inventory snapshot to %APPDATA%\Pyvoid\cache\family_inventory\. The MCP server then exposes get_family_alluvial_payload(project_path, columns) which returns the same JSON shape the in-app chart uses. Agents can request portfolio rollups (no project_path) or per-project payloads with custom column orderings.

Summary

Family Reviser Alluvial turns a 600-row Browse grid into a single screenshot you can paste into a Monday email in under a minute.
Three default columns - Category, Source, Health - and clickable nodes cross-filter the Browse and Health tabs in the same window.
The chart never blocks on a Health scan; the Not Scanned bucket plus an in-panel CTA preserves instant render and surfaces the scan affordance.
PNG and SVG export both embed a metadata footer with project, date, and version - no caption needed when forwarding.
Phase 2 column pickers add Instance Bucket and Type Bucket dimensions plus a 4-column preset for deeper analysis.
Phase 4 opt-in cache (PYVOID_FAMILY_ALLUVIAL_ROLLUP_ENABLED=1) feeds a portfolio rollup and the get_family_alluvial_payload MCP tool for AI-agent queries.
Open Family Reviser from the Pyvoid Data panel, click the sixth tab, and the picture is there. No new pushbutton, no new ribbon real estate, no model risk.