# Quick Start — your first five minutes

This is a guided first run on a real project. Follow it in order. Each step says what you click
and what you should see.

You will not change a single file until step 9, and anything you do change can be reverted in
step 11.

---

## Before you start: do not boil the ocean

Read this now, not after your first scan.

Never apply a brand-new convention to an entire legacy project on day one. Run the scan and look
at the count. If it says 400 violations, do one of these instead:

- Narrow the rule's `Path Filters` to the folders where new work happens, for example
  `Assets/_Game/**`.
- Drop the rule's `Severity` to `Info` so it reports without nagging.
- Add the legacy folders to the rule set's `Ignored Paths`.

All three are edits on the rule set asset in the Inspector. Step 4 shows you how to get there.

Then tighten it later, one folder at a time. A report with 400 red rows gets the tool turned off
in week one. A report with 12 rows gets fixed. Step 6 below is where you make this call.

---

## Step 1 — Open the window

Click `Tools ▸ Asset Naming Manager ▸ Open Window`.

**You should see:** the Asset Naming Manager window with four tabs — Report, Dashboard, Rules,
History — and a bar across the top holding a rule set field, a Theme button, Selection and Scan.
The rule set field already names `NamingRules`, because the package ships one.

The window also kicks off a scan for you as it opens, so the Report tab fills in on its own after
a moment. That is the **Scan when the window opens** preference on the
`Edit ▸ Project Settings ▸ Asset Naming Manager` page, on by default and per-machine. Read on either
way — steps 5 and 6 are about the report, not about pressing the button.

If the menu item is missing, the package has not finished compiling. Check the Console for
compile errors from the rest of your project.

---

## Step 2 — Keep the bundled rule set, or switch preset

The bundled `NamingRules.asset` is the **Unity Standard** preset: plain `PascalCase` for every asset
type, no prefixes, with scripts raised to Error because a C# file name must match its class. If that
matches how your team already works, skip to step 3 — there is nothing to create.

To use a different convention, open the **Rules** tab and click a preset in the bar across the top.
That rewrites the rules in the rule set you already have, and asks first. The presets:

| Preset | Pick this if |
|---|---|
| **Minimal** | This is an existing project with years of history. Start here. |
| **Unity Standard** | A newer project, or you want the conventions most Unity projects drift towards anyway. |
| **Unreal Style** | Your team came from Unreal and already thinks in `T_`, `M_`, `SM_`, `BP_`. |
| **Mobile 2D** | Sprites, atlases and UI dominate the project. |
| **Strict Studio** | A brand-new project with a team that has already agreed on a convention. |

If you are unsure, pick **Unity Standard**. You can load a different preset later without losing
anything else.

**You should see:** the Rules tab redraw with a card for each rule in the preset you picked, and the
bar showing which preset you are on.

To keep several conventions side by side instead of switching one, use
`Tools ▸ Asset Naming Manager ▸ Create Rule Set ▸ ‹preset›`, which creates a second rule set asset and
makes it active.

Keep **one** rule set in the project. Which one is active is remembered per machine, not in the
repository, and a checkout that has never been told falls back to the first rule set it finds by
name — so a second one in the repo is how a teammate, or your build server, quietly scans against
different rules.

Move whichever rule set you keep out of `Assets/AssetNamingManager/` before you commit it — anywhere
under your own project folders is fine. It is your convention, not part of the tool, and keeping it
outside the package means updating Asset Naming Manager can never overwrite it. Wherever you put it,
the rest of this guide calls it `NamingRules`.

---

## Step 3 — Look at what the preset is asking for

Click the **Rules** tab. Read the cards. Each one is a rule: which assets it looks at, and what it
demands of them.

Spend thirty seconds on this. You are about to run it against your project, and it is much easier
to disagree with a rule now than to disagree with 200 rows of report later.

**You should see:** a card per rule with its name, a severity pill, and a **Checks:** line that
spells out what that rule actually enforces — plus a dimmed **Not checked:** line for everything it
leaves alone. Below that: the extensions it covers, where it looks, the prefix and suffix, the
casing, the length range and the allowed folders.

With the bundled Unity Standard rules every card reads "Required prefix: none" and lists prefix
under **Not checked**. That is correct, not a bug: this preset asks for PascalCase and nothing else.

If a rule is clearly wrong for your project, switch its **enabled** toggle off — that is the one
thing the card itself can change. Do not delete it yet.

---

## Step 4 — Trim the scan scope

The Rules tab shows you the convention; it does not edit it. Every field below lives in the
Inspector, so that is where you go.

Click **Edit in Inspector** on the Rules tab. It selects `NamingRules` and pings it in the Project
window, and the Inspector then shows the whole rule set. (Clicking the asset yourself does the same
thing, as does **Show in project** on the `Edit ▸ Project Settings ▸ Asset Naming Manager` page.)

At the top of the Inspector, under **Where to look**:

- `Scan Roots` — the folders the scan walks. Leave it at `Assets` for now.
- `Ignored Paths` — paths the scan skips. It already excludes the tool's own `Editor`,
  `Documentation` and `Settings` folders, `Assets/Plugins`, `Assets/ThirdParty`,
  `Assets/StreamingAssets`, editor default resources and `.dll`, `.asmdef` and `.asmref` files.
  `Assets/AssetNamingManager/Demo` is deliberately *not* excluded — the badly named sample files in it
  are what make your first scan show something. Delete that folder, or add it here, once you have
  seen it work.

Add any folder full of imported marketplace art or third-party code to `Ignored Paths` now. Those
assets do not follow your convention and will never be renamed, so they are pure noise in the
report. A glob such as `Assets/ImportedArt/**` is enough.

**You should see:** your additions in the `Ignored Paths` list. There is no Save button — the
ScriptableObject is saved by Unity like any other asset. Go back to the Naming Manager window when you
are done; the next scan picks the change up.

---

## Step 5 — Scan

Click **Scan** in the bar across the top of the window.

**You should see:** a progress bar with the current asset path, then the Report tab filling with
rows and a summary line such as:

```
4820 assets + 512 folders scanned in 1.84s — 137 findings (12 errors, 88 warnings, 37 info). Health 97/100.
```

The scan is read-only. Nothing on disk has changed.

---

## Step 6 — Read the count and make a decision

This is the step that decides whether you still use this tool next month.

| Findings | What to do |
|---|---|
| Under about 30 | Carry on to step 7. This is a normal afternoon of cleanup. |
| 30 to 100 | Carry on, but plan to fix it folder by folder, not in one batch. |
| Over 100 | Stop. Go back to the Inspector and narrow the scope before you fix anything. |

All three of these are Inspector edits on the rule set — **Edit in Inspector** on the Rules tab
again:

1. **Scope the rules to new work.** Set `Path Filters` on the noisiest rule to the folder where new
   assets actually land, for example `Assets/_Game/**`. The rule then ignores everything older.
2. **Lower the volume.** Set the noisy rule's `Severity` to `Info`. It still reports, it just
   stops being an alarm and it will never fail CI.
3. **Ignore the past.** Add the legacy folders to `Ignored Paths`.

Then click **Scan** again and look at the new count.

The report's **Group by** already starts on `Rule`, which is exactly the view you want here. One
rule is usually responsible for most of the report, and scoping that single rule often takes the
count from 400 to 20.

---

## Step 7 — Open the Dashboard

Click the **Dashboard** tab.

**You should see:** a **Health score** gauge from 0 to 100 with a one-word verdict under it
(Spotless, Healthy, Minor drift, Needs a pass, Messy or Critical); a **Severity split** donut with
a clickable legend for Errors, Warnings and Info; and a **Worst offenders** card holding three bar
charts — findings per rule, findings per problem, and the worst folders.

Everything on this tab is a shortcut. Click a legend row or a bar and you land back on the Report
tab already filtered to it.

Note the score. It is the number you compare against next week, and it is relative to project
size, so it does not punish you for having a big project.

---

## Step 8 — Pick a small, safe batch

Go back to the **Report** tab.

1. Set **Group by** to `Folder`.
2. Pick one folder you know well, ideally one where you understand every asset.
3. Click a row. The asset pings in the Project window. Double-click to open it.
4. Read the details pane on the right: the long explanation of the problem, and the team note from
   the rule if it has one.
5. Look at the before and after on each row. The part of the name that would change is
   highlighted.

Tick the checkbox on the rows you agree with. Leave the rest alone. As soon as one box is ticked a
selection bar appears above the list, reading something like
`12 selected — 9 renames, 3 moves, 2 folders created. Nothing outside this list is touched.`

A row whose right-hand side reads "fix by hand" instead of a proposed name has no checkbox to tick
— it is greyed out. The Cop has nothing concrete to propose there, so it reports and stops.
Duplicate names, path length and pattern mismatches are always like this.

**Select fixable** in the toolbar ticks every fixable row in the current view at once. Save that
for later, when you trust it.

**Do not tick anything under `Assets/**/Resources/**`, and do not tick a `.cs` file.** Resources
are loaded by path string, and renaming a C# file does not rename the class inside it. Both will
bite you.

---

## Step 9 — Fix

Click **Preview changes** on the selection bar. Nothing is written yet.

**You should see:** a sheet slide over the window, headed `Apply 17 changes?`, listing every
rename as a before-and-after with the changed part highlighted, and tagging the ones that are
moves. Read it. This is your last look.

Two buttons at the bottom: **Cancel**, and **Apply 17 changes** — the count is in the button text,
so there is no way to press it without knowing how many files you are about to touch.

Click **Apply 17 changes**.

**You should see:** a cancelable progress bar naming each file, then a line in the status bar at
the bottom of the window:

```
14 renamed, 3 moved, 0 skipped, 0 failed.
```

and an undo bar with a **Revert that batch** button, because Unity's own undo does not cover asset
moves.

Behind that, every change went through `AssetDatabase.MoveAsset`, so the GUIDs — and therefore
every prefab, scene and script reference — are intact. Missing destination folders were created for
you. Where two assets wanted the same corrected name, the first one kept it and the next got `_01`.

If anything failed, a second sheet opens listing what could not be done and why, one line per
asset. The rest of the batch still applied.

There is a one-click route for a single row too: select a finding and click **Fix this one** in the
details pane. It skips the preview sheet, so use it when you are fixing exactly one thing.

---

## Step 10 — Check your work

1. Click **Scan** again. The rows you fixed should be gone and the Health Score should be higher.
2. Open a scene or prefab that used one of the renamed assets. It should look exactly as it did.
   If it does not, go straight to step 11.

---

## Step 11 — Practise the revert

Do this once now, while the batch is small and you know what it contained. You want to have used
this before the day you need it.

Click the **History** tab.

**You should see:** your batch, headed with what it did — `14 renamed, 3 moved` — and below that a
local timestamp such as `14 Mar 2026, 16:20` and the batch id. Next to it, a **Show** button that
lists the individual renames, and a **Revert** button.

Click **Revert**, then confirm in the dialog that tells you how many assets are about to move. Every
asset goes back to where it came from, newest change first. Anything that has been renamed again
since is skipped and reported in the Console rather than guessed at. Scan again and the old findings
return.

Now redo the fix from step 9 if you were happy with it.

Two things to know about the journal:

- It keeps the last **20** batches, in `UserSettings/AssetNamingManager/FixJournal.json`.
- That folder is per-machine and is already excluded by Unity's default `.gitignore`, so your
  teammates cannot revert your batch, and the journal never ends up in a commit.

---

## Step 12 — Commit the convention

Commit your rule set asset — `NamingRules.asset`, wherever you moved it in step 2 — along with the
renamed assets.

That file is the convention. It stops being something one person remembers and becomes something
the project enforces. Everyone who pulls now scans against the same rules.

One thing the commit does **not** carry: *which* rule set is active. That choice lives in
`EditorPrefs`, per machine and per checkout, and it is not committable. It only ever matters when a
project holds more than one rule set, because a machine that has never chosen simply takes the
first one it finds by name. Keep one rule set in the repository and the question never comes up.

---

## What to do next

| Goal | Where to go |
|---|---|
| Write rules for your own project | `RuleCookbook.md` — 17 copy-paste recipes with exact field values |
| Stop new mistakes at import time | Turn on **Check assets on import** in `Edit ▸ Project Settings ▸ Asset Naming Manager` |
| See problems in the Project browser | The overlay is already on — the dots appear after the first scan. Its toggle is on the same Project Settings page |
| Fail a pull request on bad names | `CI-Integration.md` — start the gate at Error, tighten later |
| Fix one folder at a time | Right-click the folder, `Assets ▸ Asset Naming Manager ▸ Fix Selected` |
| Check a folder without fixing it | Right-click it, `Assets ▸ Asset Naming Manager ▸ Check Selected` — results go to the Console |
| Scan from the keyboard | `Ctrl+Shift+N`, or `Tools ▸ Asset Naming Manager ▸ Scan Project`. Both open the window and scan |
| Understand the full API | The Public API section of `README.md` |

---

## A sensible rollout over two weeks

| When | What |
|---|---|
| Day 1 | Keep the bundled rule set or switch its preset, scope it to the folders where new work happens, commit it. |
| Day 1 | Fix one folder. Commit separately from any feature work, so the diff is reviewable. |
| Week 1 | Turn on **Check assets on import** so new mistakes get caught as they arrive. |
| Week 1 | Add the CI job with `-namingManagerFailOn none`. It scans, it publishes the report, it never fails. |
| Week 2 | Fix the remaining folders, one commit each. |
| Week 2 | Move the CI gate to `error`, then to `warning` once the report is clean. `info` is the strictest setting, not the loosest — see `CI-Integration.md`. |

The whole point is that nobody ever sees a 400-row report. Ten rows, ten times, is a convention
that survives.
