com.elestrago.unity.package-tools 2.2.3 → 2.4.0

package/Documentation~/manual.md

@@ -42,18 +42,18 @@ PackageTool
 
 ## Entry Points
 
-- `[MenuItem("Tools/PackageTools/PrepareDll")]` → `CIUtils.PrepareDll` at `Assets/Package/PackageTool/Editor/CIUtils.cs:197`. Maps to the **Tools/PackageTools/PrepareDll** entry in the Unity menu bar.
-- `[MenuItem("Tools/PackageTools/Init Package")]` → `PackageInitializeWindow.Open` (declared inline in `Assets/Package/PackageTool/Editor/MenuItems.cs`); opens the scaffolder window.
-- `[CreateAssetMenu(menuName = "JCMG/PackageTools/PackageManifestConfig")]` → `PackageManifestConfig` at `Assets/Package/PackageTool/Editor/PackageManifestConfig.cs:37`. Available under **Assets > Create > JCMG/PackageTools/PackageManifestConfig**.
-- `CIUtils.Generate` at `Assets/Package/PackageTool/Editor/CIUtils.cs:65` — batch-mode entry point invoked via `unity -batchmode -executeMethod PackageTool.CIUtils.Generate <key>=<value>`. Reads keys parsed by [`CommandLineTools.GetKVPCommandLineArguments`](api.md#commandlinetools); see the **CI command-line keys** section in `extension-points` for the supported keys.
-- `CIUtils.PrepareDll` at `Assets/Package/PackageTool/Editor/CIUtils.cs:197` — exits the Editor when run under CI (`CI` env var set); fixes DLL plugin platform flags first. Also available as `Tools/PackageTools/PrepareDll` for interactive use.
-- `PackageInitializeWindow.Open` at `Assets/Package/PackageTool/Editor/Utils/PackageInitialize/PackageInitializeWindow.cs:7` — opens the scaffolder via `Tools/PackageTools/Init Package`.
+- `[MenuItem("Tools/PackageTools/PrepareDll")]` -> [`CIUtils.PrepareDll`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:197`. Maps to the **Tools/PackageTools/PrepareDll** entry in the Unity menu bar.
+- `[MenuItem("Tools/PackageTools/Init Package")]` -> [`PackageInitializeWindow.Open`](api.md#packageinitializewindow) (declared inline in `Assets/Package/PackageTool/Editor/MenuItems.cs`); opens the scaffolder window.
+- `[CreateAssetMenu(menuName = "JCMG/PackageTools/PackageManifestConfig")]` -> [`PackageManifestConfig`](api.md#packagemanifestconfig) at `Assets/Package/PackageTool/Editor/PackageManifestConfig.cs:37`. Available under **Assets > Create > JCMG/PackageTools/PackageManifestConfig**.
+- [`CIUtils.Generate`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:65` — batch-mode entry point invoked via `unity -batchmode -executeMethod PackageTool.CIUtils.Generate <key>=<value>`. Reads keys parsed by [`CommandLineTools.GetKVPCommandLineArguments`](api.md#commandlinetools); see **CI command-line keys** below for the supported keys.
+- [`CIUtils.PrepareDll`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:197` — exits the Editor when run under CI (`CI` env var set); fixes DLL plugin platform flags first. Also available as `Tools/PackageTools/PrepareDll` for interactive use.
+- [`PackageInitializeWindow.Open`](api.md#packageinitializewindow) at `Assets/Package/PackageTool/Editor/Utils/PackageInitialize/PackageInitializeWindow.cs:7` — opens the scaffolder via `Tools/PackageTools/Init Package`.
 
 Inspector buttons on `PackageManifestConfig` assets (drawn by `PackageManifestConfigInspector.OnInspectorGUI`):
 
-- **Generate VersionConstants.cs** → `CodeGenTools.GenerateVersionConstants(config)` at `Assets/Package/PackageTool/Editor/Tools/CodeGenTools.cs:36`.
-- **Export Package Source** → `FileTools.CreateOrUpdatePackageSource(config)` at `Assets/Package/PackageTool/Editor/Tools/FileTools.cs:59`.
-- **Export as Legacy Package** → `UnityFileTools.CompileLegacyPackage(config)` at `Assets/Package/PackageTool/Editor/Tools/UnityFileTools.cs:36`.
+- **Generate VersionConstants.cs** -> [`CodeGenTools.GenerateVersionConstants`](api.md#codegentools)`(config)` at `Assets/Package/PackageTool/Editor/Tools/CodeGenTools.cs:36`.
+- **Export Package Source** -> [`FileTools.CreateOrUpdatePackageSource`](api.md#filetools)`(config)` at `Assets/Package/PackageTool/Editor/Tools/FileTools.cs:59`.
+- **Export as Legacy Package** -> [`UnityFileTools.CompileLegacyPackage`](api.md#unityfiletools)`(config)` at `Assets/Package/PackageTool/Editor/Tools/UnityFileTools.cs:36`.
 
 ## Data Model
 
@@ -64,20 +64,20 @@ Defined at `Assets/Package/PackageTool/Editor/PackageManifestConfig.cs:37`. Crea
 - **Package json metadata:** `homepage`, `packageName`, `displayName`, `packageVersion`, `unityVersion`, `description`, `category`, `license`, `keywords` (`string[]`), `author` (`Author`), `dependencies` (`Dependency[]`).
 - **Package content paths:** `sourcePath`, `documentationPath` (default `Documentation~`), `readmePath` (default `README.md`), `changelogPath` (default `CHANGELOG.md`), `licensePath` (default `LICENSE`), `packageIgnorePaths` (`string[]`).
 - **Export targets:** `packageDestinationPath`, `legacyPackageDestinationPath`.
-- **Staging:** `samples` ([`Sample[]`](api.md#packagemanifestconfigsample)), `copyEntries` ([`CopyEntry[]`](api.md#packagemanifestconfigcopyentry)).
+- **Staging:** `samples` ([`Sample[]`](api.md#sample)), `copyEntries` ([`CopyEntry[]`](api.md#packagemanifestconfigcopyentry)).
 - **Code generation:** `versionConstantsPath`, `versionConstantsNamespace`.
 - **Hidden:** `_id` (Guid; surfaced via `Id` property; used by `CIUtils.Generate id=<guid>` filtering).
 
 Nested `[Serializable]` types, each with a `PropertyDrawer` in `PackageTool.Drawers`:
 
-- [`Author`](api.md#packagemanifestconfigauthor) — `name`, `email`, `url` (`string`).
+- [`Author`](api.md#author) — `name`, `email`, `url` (`string`).
 - [`Dependency`](api.md#packagemanifestconfigdependency) — `packageName`, `packageVersion` (`string`); `IsEmpty()` is true when either is blank.
-- [`Sample`](api.md#packagemanifestconfigsample) — `sourcePath`, `displayName`, `description`, `folderName` (`string`); `IsEmpty()` is true when any of `displayName`/`sourcePath`/`folderName` is blank. Resulting on-disk path is `{packageDestinationPath}/Samples~/{folderName}`.
-- [`CopyEntry`](api.md#packagemanifestconfigcopyentry) — `sourcePath`, `destinationPath` (`string`); `IsEmpty()` is true when `sourcePath` is blank. See **Copy Entries staging** in the next section.
+- [`Sample`](api.md#sample) — `sourcePath`, `displayName`, `description`, `folderName` (`string`); `IsEmpty()` is true when any of `displayName`/`sourcePath`/`folderName` is blank. Resulting on-disk path is `{packageDestinationPath}/Samples~/{folderName}`.
+- [`CopyEntry`](api.md#packagemanifestconfigcopyentry) — `sourcePath`, `destinationPath` (`string`); `IsEmpty()` is true when `sourcePath` is blank. See **Copy Entries staging** below.
 
 ### Export pipeline
 
-`FileTools.CreateOrUpdatePackageSource(config)` at `Assets/Package/PackageTool/Editor/Tools/FileTools.cs:59` runs the steps below in order:
+[`FileTools.CreateOrUpdatePackageSource`](api.md#filetools)`(config)` at `Assets/Package/PackageTool/Editor/Tools/FileTools.cs:59` runs the steps below in order:
 
 1. Write `package.json` to `Assets/PackageManifest/Generated/<id>/package.json` (Unity needs a meta file to copy the meta downstream).
 2. Wipe and recreate `packageDestinationPath` (e.g. `Release/`).
@@ -85,7 +85,7 @@ Nested `[Serializable]` types, each with a `PropertyDrawer` in `PackageTool.Draw
 4. **`CopyEntriesToProject(config)`** — stage external content into the project; see below.
 5. **`CopyDocumentationToDirectory(config)`** — copy `readmePath`, `changelogPath`, `licensePath` into `sourcePath`; rebuild `sourcePath/Documentation~/` from `documentationPath`.
 6. **`RecursivelyCopyDirectoriesAndFiles(config, sourcePath, packageDestinationPath)`** — copy the package source tree, honoring `packageIgnorePaths`.
-7. **`CopySamplesToDirectory(config)`** — wipe `packageDestinationPath/Samples~/` and copy each [`Sample`](api.md#packagemanifestconfigsample)'s `sourcePath` to `Samples~/{folderName}`, skipping `.meta` files.
+7. **`CopySamplesToDirectory(config)`** — wipe `packageDestinationPath/Samples~/` and copy each [`Sample`](api.md#sample)'s `sourcePath` to `Samples~/{folderName}`, skipping `.meta` files.
 
 ### Copy Entries staging
 
@@ -97,7 +97,7 @@ Nested `[Serializable]` types, each with a `PropertyDrawer` in `PackageTool.Draw
 
 **Destination path resolution.**
 
-- Blank `destinationPath` → `EditorConstants.ProjectPath` (the repo root).
+- Blank `destinationPath` -> `EditorConstants.ProjectPath` (the repo root).
 - Non-blank `destinationPath` is resolved via `Path.GetFullPath` (so relative paths are cwd-relative — Unity Editor cwd is the project root) and **created on demand** if it doesn't yet exist.
 - A missing **source** path logs `[Package Tools] Copy entry source [...] does not exist, skipping.` and continues with the next entry.
 
@@ -116,7 +116,7 @@ IMGUI throughout — no UI Toolkit. There are no `.uxml` or `.uss` files in the
 
 ### CI command-line keys
 
-`CIUtils.Generate` reads keys parsed by [`CommandLineTools.GetKVPCommandLineArguments`](api.md#commandlinetools). Keys are case-insensitive (lowercased on parse) and values are passed as `<key>=<value>` pairs after `-executeMethod PackageTool.CIUtils.Generate`:
+[`CIUtils.Generate`](api.md#ciutils) reads keys parsed by [`CommandLineTools.GetKVPCommandLineArguments`](api.md#commandlinetools). Keys are case-insensitive (lowercased on parse) and values are passed as `<key>=<value>` pairs after `-executeMethod PackageTool.CIUtils.Generate`:
 
 - `id=<guid>[,<guid>...]` — restrict to specific `PackageManifestConfig._id`s. Omit to process all configs found by `PackageManifestTools.GetAllConfigs`.
 - `version=<semver>` — overrides `packageVersion` on every processed config (and marks the asset dirty).
@@ -127,11 +127,11 @@ To add a new key, edit `Assets/Package/PackageTool/Editor/CIUtils.cs` (constants
 
 ### VersionConstants template tokens
 
-`CodeGenTools.GenerateVersionConstants(config)` substitutes a `${token}` set into the embedded `TEMPLATE` / `GLOBAL_TEMPLATE` strings (chain at `Assets/Package/PackageTool/Editor/Tools/CodeGenTools.cs:131`) using values from the config, `DateTime`, and [`GitTools`](api.md#gittools). Adding a new token is a two-edit change: append the template line and add a `.Replace("${token}", value)` call.
+[`CodeGenTools.GenerateVersionConstants`](api.md#codegentools)`(config)` substitutes a `${token}` set into the embedded `TEMPLATE` / `GLOBAL_TEMPLATE` strings (chain at `Assets/Package/PackageTool/Editor/Tools/CodeGenTools.cs:131`) using values from the config, `DateTime`, and [`GitTools`](api.md#gittools). Adding a new token is a two-edit change: append the template line and add a `.Replace("${token}", value)` call.
 
 ### Init Package fields
 
-`PackageInitializeWindow` lays down a `PackageManifestConfig.asset`, README, CHANGELOG, LICENSE, and `Documentation~/` / `Samples~/` folders from a flat set of `DrawTextField` inputs at `Assets/Package/PackageTool/Editor/Utils/PackageInitialize/PackageInitializeWindow.cs:32`. The scaffold logic and string templates live in [`PackageInitializeUtil`](api.md#packageinitializeutil) and [`PackageInitializeTemplates`](api.md#packageinitializetemplates); changes that affect generated content must thread through both.
+[`PackageInitializeWindow`](api.md#packageinitializewindow) lays down a `PackageManifestConfig.asset`, README, CHANGELOG, LICENSE, and `Documentation~/` / `Samples~/` folders from a flat set of `DrawTextField` inputs at `Assets/Package/PackageTool/Editor/Utils/PackageInitialize/PackageInitializeWindow.cs:32`. The scaffold logic and string templates live in [`PackageInitializeUtil`](api.md#packageinitializeutil) and [`PackageInitializeTemplates`](api.md#packageinitializetemplates); changes that affect generated content must thread through both.
 
 ### Custom drawers, menu items, helpers
 

package/Documentation~/samples.md

@@ -8,15 +8,25 @@ How the sample content in this repository uses the package. Each entry maps a sa
 
 ```
 Assets/Example/Sample
-├── Prefabs
-│   └── ExamplePrefab.prefab
-└── Scene
-    └── SampleScene.unity
+├── Prefabs/ExamplePrefab.prefab
+└── Scene/SampleScene.unity
+
+Assets/Samples~/ClaudeSkills
+├── Editor/ClaudeSkillsPostImport.cs
+├── Editor/Playdarium.PackageTool.Samples.ClaudeSkills.Editor.asmdef
+├── unity-package-docs/SKILL.md
+├── unity-package-docs/assets/README.md.template
+├── unity-package-docs/assets/api-chunk.md.template
+├── unity-package-docs/assets/api-index.md.template
+├── unity-package-docs/assets/api.md.template
+├── unity-package-docs/assets/manual.md.template
+├── unity-package-docs/assets/samples.md.template
+└── unity-package-docs/scripts/scan_package.py
 ```
 
-On export, `CopySamplesToDirectory` copies this tree to `Release/Samples~/ExampleSample/`, skipping `.meta` files. The shipped sample is consumable from the Package Manager **Samples** tab on the published package.
+On export, `CopySamplesToDirectory` copies each sample root to `Release/Samples~/<folderName>/`, skipping `.meta` files. The shipped samples are consumable from the Package Manager **Samples** tab on the published package.
 
-## Sample → Package Type Mapping
+## Sample -> Package Type Mapping
 
 ### `Assets/Example/Sample/Prefabs/ExamplePrefab.prefab`
 
@@ -30,15 +40,29 @@ Kind: scene
 
 This sample asset references no scripts from the package. It exists as a structural demo (the importing user sees a working Scene/Prefab in the package's Samples tab) rather than as an API exercise.
 
+### `Assets/Samples~/ClaudeSkills/Editor/ClaudeSkillsPostImport.cs`
+
+Kind: script
+
+Editor-side post-import hook bundled with the **Claude Skills** sample. In a consumer project, after the user imports this package's Claude Skills sample, the script copies the staged `unity-package-docs/` skill folder out of the imported `Assets/Samples/<Package>/<Version>/ClaudeSkills/` location into the consumer project's `.claude/skills/` directory, then self-deletes (and cleans up empty ancestor folders) so subsequent imports do not duplicate work. It does not call into the package's runtime API — it is plumbing for the sample's primary content (`SKILL.md`, `scripts/scan_package.py`, and the `.md.template` files under `assets/`).
+
+Non-script assets that ship alongside this script (not enumerated above because the scanner only emits scripts/scenes/prefabs):
+
+- `Assets/Samples~/ClaudeSkills/unity-package-docs/SKILL.md` — the skill definition this sample exists to deliver.
+- `Assets/Samples~/ClaudeSkills/unity-package-docs/scripts/scan_package.py` — the scanner the skill invokes.
+- `Assets/Samples~/ClaudeSkills/unity-package-docs/assets/*.md.template` — the rendering templates.
+
 ## Reproducing the Sample
 
-The example sample is structural only — there are no MonoBehaviour scripts to instantiate. To reproduce from scratch:
+**Example Sample (`Assets/Example/Sample`)** — structural only, no MonoBehaviour scripts to instantiate. To reproduce from scratch:
 
 1. Create an empty Unity scene and a primitive prefab; both can live anywhere in `Assets/`.
-2. Create a `PackageManifestConfig` asset via **Assets > Create > JCMG/PackageTools/PackageManifestConfig** and configure `sourcePath`, `packageDestinationPath`, and a [`Sample`](api.md#packagemanifestconfigsample) entry whose `sourcePath` points at the folder holding the scene and prefab.
-3. Click **Export Package Source** on the inspector — `FileTools.CreateOrUpdatePackageSource` runs the export pipeline (see `manual.md` → **Export pipeline**) and the sample folder lands under `packageDestinationPath/Samples~/{folderName}`.
+2. Create a `PackageManifestConfig` asset via **Assets > Create > JCMG/PackageTools/PackageManifestConfig** and configure `sourcePath`, `packageDestinationPath`, and a [`Sample`](api.md#sample) entry whose `sourcePath` points at the folder holding the scene and prefab.
+3. Click **Export Package Source** on the inspector — [`FileTools.CreateOrUpdatePackageSource`](api.md#filetools) runs the export pipeline (see `manual.md` -> **Export pipeline**) and the sample folder lands under `packageDestinationPath/Samples~/{folderName}`.
 
-Minimal equivalent in C#:
+**Claude Skills (`Assets/Samples~/ClaudeSkills`)** — pairs a Sample with a [`CopyEntry`](api.md#packagemanifestconfigcopyentry) so the skill's canonical source lives in `.claude/skills/unity-package-docs/` (where it is editable and used directly during development) and a synchronized copy is staged into `Assets/Samples~/ClaudeSkills/unity-package-docs/` before export. The Editor-side `ClaudeSkillsPostImport.cs` script bundled with the sample handles the reverse direction in consumer projects: on import it moves the skill folder out of `Assets/Samples/<Package>/<Version>/ClaudeSkills/unity-package-docs/` into the consumer's `.claude/skills/`.
+
+Minimal equivalent in C# for either sample style:
 
 ```csharp
 using PackageTool;
@@ -63,6 +87,15 @@ config.samples = new[]
         description = "This is example for check test samples",
     },
 };
+// Optional: stage external content into a Sample's sourcePath first.
+config.copyEntries = new[]
+{
+    new PackageManifestConfig.CopyEntry
+    {
+        sourcePath = ".claude/skills/unity-package-docs",
+        destinationPath = "Assets/Samples~/ClaudeSkills/unity-package-docs",
+    },
+};
 AssetDatabase.CreateAsset(config, "Assets/Example/PackageManifestConfig.asset");
 FileTools.CreateOrUpdatePackageSource(config);
 ```
@@ -71,3 +104,4 @@ FileTools.CreateOrUpdatePackageSource(config);
 
 - The `Samples~/` folder name (trailing tilde) is a Unity convention: tilde-suffixed folders are excluded from the AssetDatabase import, so packaged samples don't pollute the consuming project until the user clicks **Import** in the Package Manager.
 - For samples that stage content from outside `Assets/` — e.g. a Claude skill folder, vendored data, or generated output — use a [`CopyEntry`](api.md#packagemanifestconfigcopyentry) with `destinationPath` pointing at the same `sourcePath` your `Sample` declares. The `CopyEntry` step runs first; `CopySamplesToDirectory` then ships the staged content into the package.
+- The `ClaudeSkillsPostImport` editor script only runs in consumer projects after they import the **Claude Skills** sample; it self-deletes after copying so a re-import does not duplicate work. It is not part of the package's primary API and is intentionally outside the `PackageTool` namespace.

package/Editor/Tools/FileTools.cs

@@ -196,11 +196,12 @@ namespace PackageTool.Tools
 
 		/// <summary>
 		/// Stages each configured <see cref="PackageManifestConfig.CopyEntry"/> into the project before the
-		/// rest of the export runs. A folder source's content is merged directly into
-		/// <see cref="PackageManifestConfig.CopyEntry.destinationPath"/> (same-named files are overwritten,
-		/// unrelated files in the destination are left alone). A file source overwrites
-		/// <c>destination/{filename}</c>. A blank destination resolves to the project root; a non-blank
-		/// destination that does not yet exist is created. Missing sources log a warning and are skipped.
+		/// rest of the export runs. A folder source replaces the destination's contents — the destination
+		/// is wiped first, then the source tree is copied in. The exception is a blank destination, which
+		/// resolves to the project root and merges instead (same-named files overwritten, unrelated files
+		/// left alone) to avoid wiping the repo. A file source overwrites <c>destination/{filename}</c>.
+		/// A non-blank destination that does not yet exist is created. Missing sources log a warning and
+		/// are skipped.
 		/// </summary>
 		public static void CopyEntriesToProject(PackageManifestConfig packageManifest)
 		{
@@ -229,6 +230,11 @@ namespace PackageTool.Tools
 
 				if (Directory.Exists(normalizedSourcePath))
 				{
+					// Skip the wipe when destination resolves to the project root — clearing the repo
+					// would be catastrophic. Blank destinations fall back to the merge behavior.
+					if (!string.IsNullOrEmpty(entry.destinationPath))
+						RecursivelyDeleteDirectoryContents(new DirectoryInfo(destinationDirectory));
+
 					CopyDirectoryRecursively(normalizedSourcePath, destinationDirectory);
 				}
 				else if (File.Exists(normalizedSourcePath))

package/README.md

@@ -1,200 +1,67 @@
-# <img src="./Documentation~/PackageManifestConfigIcon.png" alt="" width="35" height="35"/> Package Tool
+# Package Tool
 
-[![NPM package](https://img.shields.io/npm/v/com.elestrago.unity.package-tools?logo=npm&logoColor=fff&label=NPM+package&color=limegreen)](https://www.npmjs.com/package/com.elestrago.unity.package-tools)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+Tool for create unity packages
 
-## Installing
+## Requirements
 
-Using the native Unity Package Manager introduced in 2017.2, you can add this library as a package by modifying your
-`manifest.json` file found at `/ProjectName/Packages/manifest.json` to include it as a dependency. See the example below
-on how to reference it.
+- Unity 2021.3 or newer.
+- `Playdarium.PackageTool.Editor` — runs on Editor only.
 
-### Install via OpenUPM
+## Dependencies
 
-The package is available on the [npmjs](https://www.npmjs.com/package/com.elestrago.unity.package-tools)
-registry.
+| Package | Version |
+|---------|---------|
+| `com.unity.nuget.newtonsoft-json` | `3.2.1` |
 
-#### Add registry scope
+## Installation
 
-```
+Add the package to `Packages/manifest.json`:
+
+```json
 {
-  "dependencies": {
-    ...
-    "com.elestrago.unity.package-tools": "x.x.x",
-    ...
-  },
   "scopedRegistries": [
     {
-      "name": "eLeSTRaGo",
-      "url": "https://registry.npmjs.org",
+      "name": "Playdarium",
+      "url": "https://npm.playdarium.studio",
       "scopes": [
-        "com.elestrago.unity"
+        "com.elestrago"
       ]
     }
-  ]
+  ],
+  "dependencies": {
+    "com.elestrago.unity.package-tools": "2.4.0"
+  }
 }
 ```
 
-## Setting up your first package
-
-Creating your first package is a simple process that can be made more complex because information available about Unity
-Package manager is inconsistent right now. This is largely due to it not being widely and officially supported for
-end-users of Unity yet, but starting with 2019.1 will gain more official support.
-
-The first step is to create a `PackageManifestConfig` asset that we can use to define the properties and contents of our
-package. This can be done by right-clicking in the `Project` window and
-selecting `Create -> JCMG -> Package Tools -> Package
-Manifest Config`. This will create an asset named `PackageManifestConfig` in that folder.
-
-<img src="./Documentation~/Inspector.png" width="500">
-
-A `PackageManifestConfig` is broken up into two sections:
+Replace the registry URL above with your scoped registry, or remove the `scopedRegistries` block when consuming a published package.
 
-* **Package Json:** This section contains fields relating to properties of the `package.json` file that we will need to
-  have in our package root folder. It describes the minimum Unity version that it is compatible with and the version of
-  the package itself [Semantic versioning](https://docs.unity3d.com/Manual/upm-semver.html), a
-  description of the package, and any dependencies it
-  has on other packages. This last part I have the least information about, but is supposed to gain more widespread
-  support in 2019.1.
-* **Package Content and Export:** This section focuses on defining the folders/files that make up the content (including
-  code and assets) that make up the package itself and a location that the content will be published to when clicking on
-  the button labeled `Export Package Source`.
+## Getting Started
 
-For convenience sake, I have added file and folder pickers as buttons to the right of these fields that make it easier
-to add relative file/folder paths from the Assets folder for package source and export location.
+1. Create a `PackageManifestConfig` asset via **Assets > Create > JCMG/PackageTools/PackageManifestConfig**.
+2. Fill in `packageName`, `displayName`, `packageVersion`, `unityVersion`, `sourcePath` (the folder under `Assets/` that holds your package's source), and `packageDestinationPath` (where the assembled package will be written, e.g. `Release`).
+3. Optionally add `dependencies`, `samples`, and `copyEntries` rows in the inspector.
+4. Click **Export Package Source** to assemble the package; **Export as Legacy Package** to emit a `.unitypackage`; or **Generate VersionConstants.cs** to write a versions file at `versionConstantsPath`.
 
-There are also options for excluding specific files and/or folders from the package source that might otherwise be
-included. This can be useful for example, if there are unit tests or example content located within your package source
-path that you would not want to include directly or indirectly. Folders and files can be excluded by adding them to
-the **ExcludePaths** list.
-
-Recently I have found myself manually creating a `VersionConstants` static class containing versioning information about
-the package itself. This can be useful for displaying to a user or checking for updates outside of the native Unity
-PackageManager window.. Since updating this file by hand can be error-prone or easy to forget, this can now be
-configured on a `PackageManifestConfig` and generated using a new action `Generate VersionConstants.cs` on the config's
-inspector.
-
-**Example VersionConstants.cs used in JCMG.PackageTools**
+For CI, invoke `PackageTool.CIUtils.Generate` in batch mode and pass `version=<semver>` to override the asset's version on a per-run basis:
 
 ```csharp
-namespace JCMG.PackageTools.Editor
-{
-	/// <summary>
-	/// Version info for this library.
-	/// </summary>
-	internal static class VersionConstants
-	{
-		/// <summary>
-		/// The semantic version
-		/// </summary>
-		public const string VERSION = "1.3.0";
-
-		/// <summary>
-		/// The branch of GIT this package was published from.
-		/// </summary>
-		public const string GIT_BRANCH = "develop";
-
-		/// <summary>
-		/// The current GIT commit hash this package was published on.
-		/// </summary>
-		public const string GIT_COMMIT = "57aec574ed19746de42ffa5032358562fb041ebf";
-
-		/// <summary>
-		/// The UTC human-readable date this package was published at.
-		/// </summary>
-		public const string PUBLISH_DATE = "Friday, May 1, 2020";
-
-		/// <summary>
-		/// The UTC time this package was published at.
-		/// </summary>
-		public const string PUBLISH_TIME = "05/01/2020 08:26:31";
-	}
-}
-
-```
-
-The contents of this file can be configured based on the use of a text template. A default one is provided
-at `JCMG\PackageTools\Scripts\Editor\Templates\VersionConstants.txt` and a custom template can be used instead by
-providing it's meta GUID on the `PackageManifestConfig` `versionTemplateGuid` field. There is an example of this in the
-development project
+// Unity batch-mode CLI:
+// unity -batchmode -quit -projectPath . \
+//   -executeMethod PackageTool.CIUtils.Generate \
+//   version=1.2.3 generateversionconstants=true
 
-Example Template
-
-```csharp
-namespace JCMG.PackageTools.Editor
-{
-	/// <summary>
-	/// Version info for this library.
-	/// </summary>
-	internal static class VersionConstants
-	{
-		/// <summary>
-		/// The semantic version
-		/// </summary>
-		public const string VERSION = "${version}";
-
-		/// <summary>
-		/// The branch of GIT this package was published from.
-		/// </summary>
-		public const string GIT_BRANCH = "${git_branch}";
-
-		/// <summary>
-		/// The current GIT commit hash this package was published on.
-		/// </summary>
-		public const string GIT_COMMIT = "${git_commit}";
-
-		/// <summary>
-		/// The UTC human-readable date this package was published at.
-		/// </summary>
-		public const string PUBLISH_DATE = "${publish_date}";
-
-		/// <summary>
-		/// The UTC time this package was published at.
-		/// </summary>
-		public const string PUBLISH_TIME = "${publish_utc_time}";
-	}
-}
+using PackageTool;
 
+CIUtils.Generate();
 ```
 
-## Generating packages from command-line
-
-It can be desirable at times to generate legacy Unity packages and/or package source from the command-line so that they
-can be created and distributed as part of a continuous integration (CI) process. For example, you may want to trigger a
-process every time the repository is updated and source files changed so that a new package is created and made
-available to users. This can be done by launching the Unity Editor from the command line and supplying the appropriate
-arguments.
-
-**Example Command-Line Call**
-
-`"D:\Program Files\2019.4.11f1\Editor\Unity.exe" -quit -batchmode -executeMethod JCMG.PackageTools.Editor.PackageToolsCI.Generate version=1.0.1 GenerateVersionConstants=true`
-
-In this case, the `-executeMethod JCMG.PackageTools.Editor.PackageToolsCI.Generate` is the CLI argument that will
-trigger the PackageTools CI process to execute. By default, this will find all `PackageManifestConfig` instances in the
-project and if they have an appropriate output path will generate the legacy Unity package and/or package source.
-Progress will be output to the Unity Editor player log.
-
-### Arguments
-
-#### ID
-
-An optional `ID` CLI argument (case-insensitive) that can be supplied with one or more `ID` values to limit the package
-generation to a subset of `PackageManifestConfig` instances in the project if so desired. These `ID` values should
-correspond to the `ID` displayed on the `PackageManifestConfig` inspector for that instance. If not supplied, all
-
-**Example ID Argument Usage (for three ID values passed)**
-
-`id=cb87cda2-0bfa-44dc-b583-ae61ff81efcb,e1725f4a-f9f3-42c0-ac15-756f017c90ed,6a406891-59d5-430a-815d-c252deae5d5b`
-
-#### Version
+## Documentation
 
-An optional `Version` CLI argument (case-insensitive) can be supplied which will both override and set the value of the
-package version used on the `PackageManifestConfig` `packageVersion` field. This can be useful where the semantic
-package version value should be coming from an external source to the Unity project.
+- [Manual](Documentation~/manual.md) — concepts and architecture.
+- [API Reference](Documentation~/api.md) — every public type and member.
+- [Samples](Documentation~/samples.md) — how the sample project in this repo uses the package.
 
-#### GenerateVersionConstants
+## License
 
-An optional `GenerateVersionConstants` CLI argument (case-insensitive) can be supplied which will force
-the `VersionConstants` file to be written out prior to generating the package (if a path is specified for it on
-the `PackageManifestConfig`). This can be useful where this file is created as a result of a CI build and has it's
-version number set by the `version` argument.
+See [LICENSE](LICENSE).

package/Samples~/ClaudeSkills/unity-package-docs/SKILL.md

@@ -106,10 +106,14 @@ The scanner emits JSON to stdout with this shape:
   "packageDir": "Assets/Package/PackageTool",
   "asmdefs": [{"path": "...", "name": "...", "rootNamespace": "...", "includePlatforms": [...], "excludePlatforms": [...], "references": [...], "precompiledReferences": [...], "defineConstraints": [...], "autoReferenced": true}],
   "namespaces": ["PackageTool", "PackageTool.Tools", ...],
+  "files": [
+    {"path": "Assets/.../Foo.cs", "md5": "916a690462c237734b0cbceb4a8d3de1", "lines": 247}
+  ],
   "types": [
     {
       "file": "Assets/.../Foo.cs",
       "line": 37,
+      "md5": "916a690462c237734b0cbceb4a8d3de1",
       "namespace": "PackageTool",
       "name": "Foo",
       "kind": "class|struct|interface|enum",
@@ -124,12 +128,18 @@ The scanner emits JSON to stdout with this shape:
     }
   ],
   "samples": [
-    {"path": "Assets/.../Foo.cs", "kind": "script", "namespace": "...", "packageTypesReferenced": ["Foo", "Bar"]},
-    {"path": "Assets/.../Scene.unity", "kind": "scene|prefab", "scriptsReferenced": [{"guid": "...", "resolvedTo": "Assets/.../Foo.cs"}]}
+    {"path": "Assets/.../Foo.cs", "kind": "script", "namespace": "...", "packageTypesReferenced": ["Foo", "Bar"], "md5": "…", "lines": 42},
+    {"path": "Assets/.../Scene.unity", "kind": "scene|prefab", "scriptsReferenced": [{"guid": "...", "resolvedTo": "Assets/.../Foo.cs"}], "md5": "…", "lines": 85}
   ]
 }
 ```
 
+Notes on the new `md5` / `lines` / `files` fields (added in this revision):
+
+- `files[]` lists every `.cs` file under the package root that the scanner read, with the MD5 of its raw bytes and its line count. Multiple types from the same file share the same MD5, so this list is the canonical per-file view; `types[i].md5` is a denormalized convenience.
+- `md5` is over **raw bytes** (no CRLF↔LF normalization). A line-ending swap counts as a change, which is intentional — if the bytes differ at all, the doc should be regenerated.
+- `samples[]` carries `md5`/`lines` only for individual sample files (scripts, scenes, prefabs). The scanner does not roll these up into the package `files[]` list.
+
 Capture this JSON; the rest of the pipeline consumes it.
 
 ### Step 3.5 — Plan chunking
@@ -159,6 +169,30 @@ Build a **`crossRefMap`**: `{ typeAnchor → "<destination-relative-to-Documenta
 
 Print one line per file decision, e.g. `chunk-plan: api.md → chunked (12 namespaces, draft=2143 lines, threshold=800)` or `chunk-plan: samples.md → single (draft=78 lines)`.
 
+### Step 3.6 — Fast-update check (api only)
+
+Before rendering, build a **`skipSet`** of api outputs that can be left untouched because their underlying source files are bit-for-bit identical to the last run. This is an optimization, not a correctness step — skipping is always safe to opt out of (and is automatically opted out of below in well-defined situations).
+
+The check only applies to `api.md` and its chunks. `manual.md` and `samples.md` are skipped here because their content is synthesized across many files (manual) or driven by sample-side bytes already covered by `samples[i].md5` (samples — left as future work; do not skip samples in this revision).
+
+Procedure for **each** prospective api output (the single `api.md` in the single-file branch, or each `api/<Namespace>.md` in the chunked branch):
+
+1. **Identify the source files** that contribute to this output:
+   - Single-file `api.md` → every file path that appears in any `types[].file`.
+   - Chunked `api/<Namespace>.md` → every distinct `types[i].file` where `types[i].namespace == <Namespace>` (nested types use the containing type's namespace, same rule as `crossRefMap`).
+2. **Read the existing output file** if it exists AND starts with the generator marker. Skip the check (do not add to `skipSet`) if the file is absent, lacks the marker, or fails to parse.
+3. **Extract per-file md5s** from the existing file by greppping ``` `path:line` (md5: `<32-hex>`,``` (the exact shape emitted by Step 4). Build `priorMd5: {path → md5}`.
+4. **Compare**: if every source file from step 1 is present in `priorMd5` AND every value equals the current `files[i].md5` from the scanner manifest, add this output's path to `skipSet`.
+5. **Force override**: if `force=true` was passed, `skipSet` is empty (the user asked to overwrite unconditionally).
+
+Print one line per check, e.g. `fast-update: api/PackageTool.Tools.md → skipped (3 files unchanged)` or `fast-update: api/PackageTool.md → re-render (FileTools.cs md5 differs)`.
+
+Steps 4/5/6 honor `skipSet` as follows:
+
+- An output path in `skipSet` is **not rewritten** — the existing file is preserved verbatim, and `crossRefMap` (which was built in Step 3.5 from the scanner manifest, independent of the existing file) is still used for downstream links from `manual.md` and `samples.md`. This works because anchors are derived from type names, which are part of the manifest, not parsed from the existing api file.
+- Stale-chunk removal (Steps 4/5/6) still runs over the full chunk directory; `skipSet` only governs *re-rendering*, not stale cleanup.
+- The Step 8 verifier still walks every emitted `.md` (including skipped ones), so a stale api file with a missing anchor is still caught.
+
 ### Step 4 — Render `Documentation~/api.md` first
 
 Render this file first because `manual.md` and `samples.md` link into its anchors (via `crossRefMap` from Step 3.5) and you want those anchors to exist.
@@ -169,21 +203,29 @@ For each type entry:
 
 - Heading: `### {TypeName}` (stable; the anchor is `{typename-lowercase}` by default Markdown rules; for nested types use `### {ContainingType}.{TypeName}`).
 - ` ```csharp ` block with the declaration line copied verbatim from source (use the file + line in the manifest to extract the line; do not paraphrase).
-- `**Source:** ` + `path:line`.
+- `**Source:** ` + `` `path:line` `` + ` (md5: ` + `` `<32-hex>` `` + `, lines: <n>)`. The md5 comes from `types[i].md5`; the line count comes from the matching entry in `files[]`. The trailing parenthetical is the **anchor for fast-update checks** (see "Fast-update check" below) — render it on every type, in this exact shape, so a downstream grep `\(md5: \`([0-9a-f]{32})\`` reliably extracts it.
 - `**Attributes:** ` + comma-separated list (omit the line if none).
 - `**Base:** ` + comma-separated `baseList` (omit if empty).
 - Summary verbatim if present.
-- Members table: only include public/internal/protected members; omit private. Strip XML tags from member summaries.
+- Members table: only include public/internal/protected members; omit private. Strip XML tags from member summaries. The table has a **`Line`** column carrying `members[].line`; the file is the same as the type's Source line above (no need to repeat the path on every row).
+
+```
+**Members:**
+
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | Bar | `public void Bar()` | 88 | … |
+```
 
 Omit types with no public members and no XML summary unless they carry a Unity attribute (`[MenuItem]`, `[CustomEditor]`, etc.). Omit empty namespaces entirely.
 
-**Output (single-file branch, default):** if Step 3.5 decided api is single-file, write the rendered draft to `Documentation~/api.md` as-is.
+**Output (single-file branch, default):** if Step 3.5 decided api is single-file, render the draft into a buffer and — if `Documentation~/api.md` is in `skipSet` from Step 3.6 — leave the existing file in place; otherwise write the buffer to `Documentation~/api.md` as-is.
 
 **Output (chunked branch):** if Step 3.5 decided api is chunked, split the draft by namespace and emit:
 
-1. **One chunk per namespace** at `Documentation~/api/<Namespace>.md` using `${SKILL_DIR}/assets/api-chunk.md.template`. Each chunk contains the H1 (`# {{displayName}} — API Reference: \`{{namespace}}\``), the namespace's section body (same `### TypeName` blocks as the single-file form), and the generator marker on line 1. Anchors inside the chunk stay `{typename-lowercase}` — they do NOT include the namespace prefix, because cross-doc links resolve via `crossRefMap` (which carries the path-plus-anchor pair).
-2. **One index** at `Documentation~/api.md` using `${SKILL_DIR}/assets/api-index.md.template`. The index keeps the generator marker, H1, a `## Contents` Markdown table linking each chunk (`| Namespace | Description |`), and a one-line `## Notes` paragraph: `This API reference is split by namespace; see files under \`api/\`.`. The one-line description per namespace is the same blurb you would have placed in the single-file `{{namespaceContentsList}}`.
-3. **Stale chunks:** before writing, list `Documentation~/api/*.md`. For each existing file that starts with the generator marker and is NOT in the current chunk set, delete it and print `Removed stale: <path>`. (See Idempotency.)
+1. **One chunk per namespace** at `Documentation~/api/<Namespace>.md` using `${SKILL_DIR}/assets/api-chunk.md.template`. Each chunk contains the H1 (`# {{displayName}} — API Reference: \`{{namespace}}\``), the namespace's section body (same `### TypeName` blocks as the single-file form), and the generator marker on line 1. Anchors inside the chunk stay `{typename-lowercase}` — they do NOT include the namespace prefix, because cross-doc links resolve via `crossRefMap` (which carries the path-plus-anchor pair). If the chunk's path is in `skipSet` from Step 3.6, do not rewrite it — the existing file is preserved.
+2. **One index** at `Documentation~/api.md` using `${SKILL_DIR}/assets/api-index.md.template`. The index keeps the generator marker, H1, a `## Contents` Markdown table linking each chunk (`| Namespace | Description |`), and a one-line `## Notes` paragraph: `This API reference is split by namespace; see files under \`api/\`.`. The one-line description per namespace is the same blurb you would have placed in the single-file `{{namespaceContentsList}}`. The index itself is **always rewritten** (never skipped), because its content depends on the chunk set, not on the package source bytes.
+3. **Stale chunks:** before writing, list `Documentation~/api/*.md`. For each existing file that starts with the generator marker and is NOT in the current chunk set, delete it and print `Removed stale: <path>`. (See Idempotency.) Stale removal runs independently of `skipSet`.
 
 ### Step 5 — Render `Documentation~/manual.md`
 

package/Samples~/ClaudeSkills/unity-package-docs/assets/api-chunk.md.template

@@ -18,7 +18,7 @@ in shape to a per-type block in the single-file api.md template:
 {declaration line copied verbatim from source}
 ```
 
-**Source:** `{file}:{line}`
+**Source:** `{file}:{line}` (md5: `{md5}`, lines: {lines})
 **Attributes:** `[Attr1]`, `[Attr2]` (omit line if none)
 **Base:** `{baseList}` (omit if empty)
 
@@ -26,9 +26,9 @@ in shape to a per-type block in the single-file api.md template:
 
 **Members:**
 
-| Kind | Name | Signature | Summary |
-|------|------|-----------|---------|
-| method | Foo | `public void Foo()` | … |
+| Kind | Name | Signature | Line | Summary |
+|------|------|-----------|------|---------|
+| method | Foo | `public void Foo()` | 88 | … |
 
 Anchors are `{typename-lowercase}` (no namespace prefix). Cross-doc links
 from manual.md / samples.md resolve via crossRefMap, which carries the
@@ -36,6 +36,12 @@ chunk-relative path-plus-anchor pair (e.g. `api/PackageTool.Tools.md#filetools`)
 For nested types use `### {ContainingType}.{TypeName}` and anchor
 `{containingtype}.{typename}`.
 
+The Source parenthetical — `(md5: \`<32-hex>\`, lines: <n>)` — is the contract
+the Step 3.6 fast-update check greps for. Emit it on every type in this exact
+shape; otherwise a re-run cannot detect that this chunk's source files are
+unchanged and will needlessly re-render. The Members **Line** column carries
+each member's source line within the type's file.
+
 Omit types with no public members and no XML summary unless they carry a
 Unity attribute (`[MenuItem]`, `[CustomEditor]`, etc.).
 -->