Anvil Guide — doctor tools for a sick project

Plain English first. Sharp edges after.

1. What this is / is not

Anvil is a pile of Editor auditors. Each tool opens a window, scans your project, and can write a JSON report under <project>/AnvilReports/. The same tools run headless with -batchmode -executeMethod …RunBatch for CI or agents. Package: com.artchie.anvil (unity-tools). Unity 2021.3+. Editor-only. No hard deps — empty references on Anvil.Editor.

It is not Rivet (daily chores: rename, bookmarks, prefs). It is not Atlas (code map). It is not Folio (markdown viewer). Soft friend of Rivet: same RunBatch + report-folder shape (AnvilReports vs RivetReports), not compile-coupled — neither asmdef references the other.

2. Open it

Everything hangs under:

ArTchie / Anvil / …

Job	Click
Fat project snapshot (agents first)	ArTchie / Anvil / Agent Project Dump
Missing MonoBehaviours on scenes/prefabs	ArTchie / Anvil / Missing Script Hunter
Assets that look unused	ArTchie / Anvil / Unused Asset Finder
Missing object refs / unresolved YAML Unity refs	ArTchie / Anvil / Broken Reference Scanner
Who references this GUID / asset	ArTchie / Anvil / GUID Find-Usages
Asmdef directed cycles	ArTchie / Anvil / Asmdef Cycle Detector
Scene/prefab YAML hygiene	ArTchie / Anvil / Scene YAML Linter
Orphan .meta + empty folders	ArTchie / Anvil / Orphan Meta Cleaner
Fat textures / heavy audio	ArTchie / Anvil / Asset Bloat Report
Build scenes + PlayerSettings sanity	ArTchie / Anvil / Build Settings Auditor

If a README still says bare Anvil / … without the ArTchie/ prefix, the README is stale — trust the menu in Unity.

3. First five minutes

1. Make sure com.artchie.anvil is in the project (Packages/unity-tools or a file: entry in Packages/manifest.json). Open Unity. Wait for import. Check the Console for red errors.
2. Click ArTchie / Anvil / Agent Project Dump. That is the one agents and CI should hit first.
3. Click Scan. You should see Unity version, product/company, build target, scene lists, asmdefs, and a compile-error count (best-effort).
4. Click Write report. Open <project>/AnvilReports/agent-project-dump.json in any editor. That file is the dump.
5. Optional: open Missing Script Hunter, click Scan, then Write report → missing-scripts.json. Ping a row to jump to the broken object.

That is enough. Quarantine / strip buttons are extras — never required to read a report.

The Broken Reference Scanner YAML pass only matches {fileID, guid, type} object refs. A bare guid: string (Bedder BsId stickers) is not a broken ref. Empty guids and package GUIDs Unity can still find are skipped too.

4. The meat

Shared window chrome

Most tools share the same shape:

• Scan (or Find on GUID Find-Usages) — walk Assets, show rows, update status.
• Copy JSON — last result on the clipboard.
• Write report — create <project>/AnvilReports/ if needed, write the default JSON file.
• Progress bars are cancelable where the scan allows it.
• Scans skip Packages/ and Library/ unless a tool says otherwise (Asmdef can optionally include Packages in the cycle graph; package asmdefs are still indexed so refs into Packages are not “missing”).
• Empty / first-run (never scanned): title No report yet + HelpBox (click Scan, or Find on GUID Find-Usages) + miniLabel (ArTchie / Anvil / …; agents first: Agent Project Dump). Shared via AnvilEmptyGui. Reports still need Write report → AnvilReports/.

Reports on disk

Default folder: <project>/AnvilReports/ (project root — next to Assets/, not inside it).

Tool	Default JSON
Agent Project Dump	agent-project-dump.json
Missing Script Hunter	missing-scripts.json
Unused Asset Finder	unused-assets.json
Broken Reference Scanner	broken-refs.json
GUID Find-Usages	guid-usages.json
Asmdef Cycle Detector	asmdef-cycles.json
Scene YAML Linter	scene-yaml-lint.json
Orphan Meta Cleaner	orphan-metas.json
Asset Bloat Report	asset-bloat.json
Build Settings Auditor	build-settings.json

Typical JSON envelope: tool, generatedUtc, count, plus items (or a dump-shaped body for Agent Project Dump). Open the matching file under Documentation/ for field-by-field detail.

What each tool does

• Agent Project Dump — one fat snapshot: versions, build scenes, Assets scenes, asmdefs, compileErrors, anvilVersion. Hit this first from CI or an agent.
• Missing Script Hunter — scenes + prefabs with missing MonoBehaviour slots. Can Strip missing (Undo) in the window; batch only strips with -anvil-strip. Include/exclude path substrings.
• Unused Asset Finder — lists assets that look unused. Never deletes. Optional quarantine via AssetDatabase.MoveAsset to Assets/AnvilReports/quarantine/. Default ignores .cs. Optional “reachable from roots” mode.
• Broken Reference Scanner — Missing SerializedProperty refs, UnityEvent missing targets, YAML Unity refs ({fileID, guid, type}) whose guid AssetDatabase cannot resolve, missing prefab instances on scenes / prefabs / ScriptableObjects. Bare guid: scalars (Bedder BsId stickers) and empty guids are skipped. Package GUIDs that resolve are not flagged.
• GUID Find-Usages — pick an asset or paste a GUID; list every Assets path that references it (omits the target and its own .meta).
• Asmdef Cycle Detector — directed cycles in .asmdef refs + unresolved reference tokens. -anvil-fail fails on cycles only (missing refs alone do not fail).
• Scene YAML Linter — rules: unnamed, nesting-depth (>12), empty-scene, missing-prefab, duplicate-sibling.
• Orphan Meta Cleaner — orphan .meta and empty folders by walking Assets/ on disk. Default report-only. Quarantine moves to AnvilReports/quarantine (does not delete); batch needs -anvil-quarantine.
• Asset Bloat Report — TextureImporter / AudioImporter fat under Assets. Window Min Bytes; batch -anvil-min-bytes <n>.
• Build Settings Auditor — EditorBuildSettings scenes + a few PlayerSettings fields. -anvil-fail on severity: "error"; -anvil-fail-unlisted also fails on scenes under Assets not in the build list.

Soft friend: Rivet

Rivet is the daily-chore kit (ArTchie / Rivet / …, reports under RivetReports/). Same idea: Editor window + RunBatch + JSON. Anvil does not reference Rivet’s asmdef; Rivet does not reference Anvil’s. Install one, both, or neither.

Native-only lock

• Package: com.artchie.anvil · Unity 2021.3+ · asmdef Anvil.Editor (includePlatforms: Editor, references: [])
• No Node. No extra UPM deps. No Unity AI required.

5. Common stuck

1. Menus say Anvil / … without ArTchie/ — stale README or per-tool doc header. Trust Unity: ArTchie / Anvil / ….
2. I don’t see ArTchie / Anvil — package not imported, asmdef error, or wrong project. Check Console and Packages/manifest.json for com.artchie.anvil.
3. No JSON on disk after Scan — Scan fills the window; Write report (or batch RunBatch) creates AnvilReports/. Copy JSON only touches the clipboard.
4. GUID Find-Usages batch exits immediately — you must pass -anvil-guid <guid> or -anvil-asset <path>.
5. Orphan / Unused “deleted” my files — they did not. Quarantine moves (Unused → Assets/AnvilReports/quarantine/; Orphan → project AnvilReports/quarantine). Batch quarantine only with -anvil-quarantine. Default is report-only.
6. -anvil-fail exits 0 but I see missing asmdef refs — Asmdef Cycle Detector fails on cycles only. Missing refs are listed but do not fail unless you add your own check.
7. Agent dump compileErrors is -1 — Unity 2021.3 has no public compiler-message snapshot API. The dump probes LogEntries / log tail best-effort; -1 means unavailable. -anvil-fail does not fail on -1.
8. Broken refs lists Bedder BsId stickers or URP package GUIDs — it should not. YAML pass matches {fileID, guid, type} objects only. Bare guid: scalars and empty guids are skipped. A guid AssetDatabase.GUIDToAssetPath can resolve (including Packages) is not dangling.

6. For pros

Package + batch entry points

com.artchie.anvil · Anvil.Editor
Anvil.AgentProjectDump.RunBatch
Anvil.MissingScriptHunter.RunBatch
Anvil.UnusedAssetFinder.RunBatch
Anvil.BrokenRefScanner.RunBatch
Anvil.GuidFindUsages.RunBatch
Anvil.AsmdefCycleDetector.RunBatch
Anvil.SceneYamlLinter.RunBatch
Anvil.OrphanMetaCleaner.RunBatch
Anvil.AssetBloatReport.RunBatch
Anvil.BuildSettingsAuditor.RunBatch

Example:

Unity -batchmode -nographics -quit -projectPath <proj> \
  -executeMethod Anvil.AgentProjectDump.RunBatch \
  -anvil-out <file.json> -anvil-fail

RunBatch calls EditorApplication.Exit only when Application.isBatchMode is true.

Common CLI flags

Flag	Meaning
-anvil-out <file.json>	Output path (also accepts -anvil-out=file.json). Default: <project>/AnvilReports/<tool>.json
-anvil-fail	Exit 1 when the tool’s fail condition is met (usually “any findings”; Dump = compileErrors > 0; Asmdef = cycles only; Build Settings = severity error)
-anvil-guid / -anvil-asset	GUID Find-Usages (required one of)
-anvil-quarantine	Orphan Meta / Unused Asset — move after report
-anvil-strip	Missing Script Hunter — strip after scan
-anvil-include / -anvil-exclude	Repeatable path substrings (Missing Script, Unused, …)
-anvil-packages	Asmdef — include Packages in cycle graph
-anvil-min-bytes <n>	Asset Bloat — also list large files with no “reason”
-anvil-fail-unlisted	Build Settings — fail on Assets scenes not in build list
-anvil-type / -anvil-include-scripts / -anvil-reachable-roots	Unused Asset Finder options

BrokenRefScanner YAML (Fable)

• Regex GuidWithKeyRe — brace object that contains both fileID: and a 32-hex guid: (lookaheads; either order). No bare guid: <hex> alternative (Bedder BsId stickers).
• ScanYamlFile — Groups[1]=key / Groups[2]=guid; skip empty; skip IsBuiltInOrEmptyGuid; skip if GUIDToAssetPath is non-empty (package GUIDs OK).
• Window HelpBox matches: {fileID, guid, type}-only; resolvable package GUIDs ignored.

Design bounds (do not invent)

Anvil is Editor health / audit. Do not document a third kit, a required Rivet install, or Anvil-as-runtime. Per-tool deep fields live in Documentation/<Tool>.md. This Guide is the happy path + contracts.

Canonical base

artchie-RECONCILED-20260822-2107. Package README + this Guide + per-tool Documentation/*.md.

7. Related kits

Kit	When you want it
Suite Map	Which ArTchie pile does what · Guides/Guide-Suite-Map.md
Rivet	Daily Editor chores; same RunBatch/report shape; not compile-coupled
Atlas	Code map / search — not an auditor
Folio	Read markdown reports if you drop .md notes beside JSON
Scribe / Charter	Comments + game plans — not project health
Bedder	In-player IDE
ArTchie AI	Companion chat (optional Atlas map tools; not Anvil)

Open Agent Project Dump. Write the report. Then pick the hunter that matches the smell.