com.elestrago.unity.package-tools 2.5.1 → 2.5.3

package/Documentation~/examples/packagetoolapi-exportpackagesource.md

@@ -0,0 +1,40 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: PackageToolApi.ExportPackageSource
+
+**Kind:** static-method
+
+**Entry point:** [PackageToolApi](../api.md#packagetoolapi)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/PackageToolApi.cs:94`
+
+## What it does
+
+Exports a package's source layout to the config's `packageDestinationPath` and returns the path of the written `package.json`. This is the programmatic equivalent of the **Export Package Source** inspector button, and the method the button itself calls. Pass `version` to stamp a new `packageVersion` onto the config asset before exporting; leave it null to keep the version already on the asset. Failures throw — wrap the call when the surrounding flow should continue.
+
+## Snippet
+
+```csharp
+using PackageTool;
+using UnityEditor;
+using UnityEngine;
+
+internal static class ExportExample
+{
+	[MenuItem("Tools/Examples/Export Package Source")]
+	private static void Export()
+	{
+		var config = PackageToolApi.GetConfig("com.elestrago.unity.package-tools");
+		var packageJsonPath = PackageToolApi.ExportPackageSource(config, version: "2.6.0");
+
+		Debug.Log($"Exported package manifest to {packageJsonPath}");
+	}
+}
+```
+
+## Observable effect
+
+- `Release/` (the config's `packageDestinationPath`) is wiped and rebuilt with the exported package layout: sources, `package.json`, README, CHANGELOG, LICENSE, `Documentation~/`, `Samples~/`.
+- `Assets/Package/PackageTool/package.json` is rewritten from the config and imported so Unity creates its meta file.
+- The config asset is marked dirty when a `version` is passed, so the new version is saved with the project.
+- The console prints `[Package Tools] Successfully updated package source for [<packageName>].`

package/Documentation~/examples/packagetoolapi-findconfig.md

@@ -0,0 +1,46 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: PackageToolApi.FindConfig
+
+**Kind:** static-method
+
+**Entry point:** [PackageToolApi](../api.md#packagetoolapi)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/PackageToolApi.cs:26` (and the array overload at `Assets/Package/PackageTool/Editor/PackageToolApi.cs:35`)
+
+## What it does
+
+Resolves a selector to a single [PackageManifestConfig](../api.md#packagemanifestconfig), returning null when nothing matches. The selector is compared case-insensitively against the config id (the guid), then the `packageName`, then the config asset name — first match wins — so a caller that knows the package name from `package.json` never has to look up the guid first. A selector matching more than one config throws rather than picking one. The second overload takes a pre-fetched config array, so resolving many selectors costs a single AssetDatabase lookup.
+
+## Snippet
+
+```csharp
+using PackageTool;
+using UnityEditor;
+using UnityEngine;
+
+internal static class FindConfigExample
+{
+	[MenuItem("Tools/Examples/Find Package Config")]
+	private static void Find()
+	{
+		var config = PackageToolApi.FindConfig("com.elestrago.unity.package-tools");
+		if (config == null)
+		{
+			Debug.LogWarning("No config matched the selector.");
+			return;
+		}
+
+		// Resolve several selectors against one lookup of the project.
+		var all = PackageToolApi.GetConfigs();
+		var byAssetName = PackageToolApi.FindConfig("PackageManifestConfig", all);
+
+		Debug.Log($"{config.packageName} / {byAssetName?.name}", config);
+	}
+}
+```
+
+## Observable effect
+
+- The console prints the resolved package name, or a warning when the selector matches nothing.
+- An ambiguous selector throws an `InvalidOperationException` naming every candidate config and its id.

package/Documentation~/examples/packagetoolapi-generateversionconstants.md

@@ -0,0 +1,42 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: PackageToolApi.GenerateVersionConstants
+
+**Kind:** static-method
+
+**Entry point:** [PackageToolApi](../api.md#packagetoolapi)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/PackageToolApi.cs:78`
+
+## What it does
+
+Writes a `VersionConstants.cs` file at the config's `versionConstantsPath`, stamped with the package version, the current git branch and commit, and the UTC publish time, and returns the path it wrote. Returns null (and logs a warning) when the config has no `versionConstantsPath` set, so a caller can treat "not configured" differently from a failure. Run it before an export when the shipped code needs to report its own version.
+
+## Snippet
+
+```csharp
+using PackageTool;
+using UnityEditor;
+using UnityEngine;
+
+internal static class VersionConstantsExample
+{
+	[MenuItem("Tools/Examples/Generate Version Constants")]
+	private static void Generate()
+	{
+		var config = PackageToolApi.GetConfig("com.elestrago.unity.package-tools");
+		var path = PackageToolApi.GenerateVersionConstants(config);
+
+		if (string.IsNullOrEmpty(path))
+			Debug.LogWarning("No versionConstantsPath is set on the config.");
+		else
+			Debug.Log($"Wrote {path}");
+	}
+}
+```
+
+## Observable effect
+
+- `<versionConstantsPath>/VersionConstants.cs` is created or overwritten with `VERSION`, `GIT_BRANCH`, `GIT_COMMIT` and `PUBLISH_TIME` constants.
+- The file is imported into the AssetDatabase, so Unity recompiles the assembly that contains it.
+- Nothing happens beyond a console warning when the config leaves `versionConstantsPath` blank.

package/Documentation~/examples/packagetoolapi-getconfig.md

@@ -0,0 +1,37 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: PackageToolApi.GetConfig
+
+**Kind:** static-method
+
+**Entry point:** [PackageToolApi](../api.md#packagetoolapi)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/PackageToolApi.cs:63`
+
+## What it does
+
+The throwing counterpart of [PackageToolApi.FindConfig](../api.md#packagetoolapi): resolves a selector the same way (config id, then `packageName`, then asset name) but raises an `InvalidOperationException` instead of returning null when nothing matches. Use it in scripted flows where a missing package is a bug and a null check would only push the failure further down.
+
+## Snippet
+
+```csharp
+using PackageTool;
+using UnityEditor;
+
+internal static class GetConfigExample
+{
+	[MenuItem("Tools/Examples/Export By Package Name")]
+	private static void Export()
+	{
+		// Throws with a readable message when no config matches the selector.
+		var config = PackageToolApi.GetConfig("com.elestrago.unity.package-tools");
+
+		PackageToolApi.ExportPackageSource(config);
+	}
+}
+```
+
+## Observable effect
+
+- The package source is exported when the selector resolves.
+- An unmatched selector throws `[Package Tools] No PackageManifestConfig matches [<selector>]. Selectors match the config id, the package name or the asset name.`

package/Documentation~/examples/packagetoolapi-getconfigs.md

@@ -0,0 +1,36 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: PackageToolApi.GetConfigs
+
+**Kind:** static-method
+
+**Entry point:** [PackageToolApi](../api.md#packagetoolapi)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/PackageToolApi.cs:18`
+
+## What it does
+
+Returns every [PackageManifestConfig](../api.md#packagemanifestconfig) asset in the project. Use it to enumerate the packages a project can export — for a custom editor window, a batch action across a multi-package repo, or to resolve several selectors against a single lookup by passing the array to the [PackageToolApi.FindConfig](../api.md#packagetoolapi) overload that accepts one.
+
+## Snippet
+
+```csharp
+using PackageTool;
+using UnityEditor;
+using UnityEngine;
+
+internal static class ListConfigsExample
+{
+	[MenuItem("Tools/Examples/Log Package Configs")]
+	private static void LogConfigs()
+	{
+		foreach (var config in PackageToolApi.GetConfigs())
+			Debug.Log($"{config.packageName} {config.packageVersion} -> {config.packageDestinationPath}", config);
+	}
+}
+```
+
+## Observable effect
+
+- The console lists one line per config asset in the project, each pingable back to the asset it came from.
+- Nothing is written to disk — this is a pure lookup over the AssetDatabase.

package/Documentation~/examples/preparedll.md

@@ -6,7 +6,7 @@
 
 **Entry point:** [CIUtils](../api.md#ciutils)
 
-**Declared at:** `Assets/Package/PackageTool/Editor/CIUtils.cs:197`
+**Declared at:** `Assets/Package/PackageTool/Editor/CIUtils.cs:319`
 
 **Menu path:** `Tools/PackageTools/PrepareDll`
 

package/Documentation~/examples.md

@@ -6,7 +6,7 @@ Short, focused usage examples that exercise this package's public API. Each exam
 
 ## Quick start
 
-Start with **Create a PackageManifestConfig** to produce the config asset that drives every other entry point, then run **Tools > PackageTools > Init Package** (`init-package`) to scaffold a new package skeleton against it. For automated builds, **CIUtils.Generate** is the batch-mode entry point and **Tools > PackageTools > PrepareDll** (`preparedll`) is the DLL platform-flag fix-up step that typically runs immediately before it.
+Start with **Create a PackageManifestConfig** to produce the config asset that drives every other entry point, then run **Tools > PackageTools > Init Package** (`init-package`) to scaffold a new package skeleton against it. To export from your own editor code, call [PackageToolApi](api.md#packagetoolapi) — it is the supported in-process surface and every inspector button routes through it. For automated builds, the [CIUtils](api.md#ciutils) methods are the batch-mode entry points (`Generate` for both outputs, `ExportPackageSource` / `ExportLegacyPackage` for one of them, `ListConfigs` for discovery) and **Tools > PackageTools > PrepareDll** (`preparedll`) is the DLL platform-flag fix-up step that typically runs immediately before them.
 
 ## Contents
 
@@ -15,7 +15,16 @@ Start with **Create a PackageManifestConfig** to produce the config asset that d
 | [Create a PackageManifestConfig](examples/create-packagemanifestconfig.md) | create-asset | [PackageManifestConfig](api.md#packagemanifestconfig) |
 | [Init Package](examples/init-package.md) | menu-item | [MenuItems](api.md#menuitems) |
 | [PrepareDll](examples/preparedll.md) | menu-item | [CIUtils](api.md#ciutils) |
+| [PackageToolApi.GetConfigs](examples/packagetoolapi-getconfigs.md) | static-method | [PackageToolApi](api.md#packagetoolapi) |
+| [PackageToolApi.FindConfig](examples/packagetoolapi-findconfig.md) | static-method | [PackageToolApi](api.md#packagetoolapi) |
+| [PackageToolApi.GetConfig](examples/packagetoolapi-getconfig.md) | static-method | [PackageToolApi](api.md#packagetoolapi) |
+| [PackageToolApi.GenerateVersionConstants](examples/packagetoolapi-generateversionconstants.md) | static-method | [PackageToolApi](api.md#packagetoolapi) |
+| [PackageToolApi.ExportPackageSource](examples/packagetoolapi-exportpackagesource.md) | static-method | [PackageToolApi](api.md#packagetoolapi) |
+| [PackageToolApi.ExportLegacyPackage](examples/packagetoolapi-exportlegacypackage.md) | static-method | [PackageToolApi](api.md#packagetoolapi) |
 | [CIUtils.Generate](examples/ciutils-generate.md) | static-method | [CIUtils](api.md#ciutils) |
+| [CIUtils.ExportPackageSource](examples/ciutils-exportpackagesource.md) | static-method | [CIUtils](api.md#ciutils) |
+| [CIUtils.ExportLegacyPackage](examples/ciutils-exportlegacypackage.md) | static-method | [CIUtils](api.md#ciutils) |
+| [CIUtils.ListConfigs](examples/ciutils-listconfigs.md) | static-method | [CIUtils](api.md#ciutils) |
 
 This package also ships Unity samples importable from Package Manager → Package Tool → Samples → `Example Sample`, `Claude Skills`. Those samples are not duplicated here — import them via Package Manager if you want the full asset content.
 
@@ -23,3 +32,5 @@ This package also ships Unity samples importable from Package Manager → Packag
 
 - The `PackageTool.Tools.*` (`CommandLineTools`, `GitTools`) and `PackageTool.Utils.PackageInitialize.*` (`PackageInitializeTemplates`, `PackageInitializeUtil`) helpers were public in earlier revisions and dropped to `internal` to make the public surface intentional. They still exist and are used by `CIUtils.Generate`/`Init Package` internally; they're just no longer documented as consumer-facing entry points.
 - All entry points listed here are editor-only (single asmdef `Playdarium.PackageTool.Editor`, `includePlatforms: ["Editor"]`); call them from editor scripts or batch mode, not from runtime code.
+- Both `FindConfig` overloads share one example chunk; the array overload exists so several selectors can be resolved against a single AssetDatabase lookup.
+- The `id=` selector on every `CIUtils` entry point accepts a config guid, a `packageName`, or a config asset name, so a caller that only knows the published package name does not have to discover the guid first.

package/Documentation~/manual.md

@@ -24,13 +24,13 @@ PackageTool
     └── PackageInitialize
 ```
 
-`PackageTool` (root) holds the configuration ScriptableObject [`PackageManifestConfig`](api.md#packagemanifestconfig) at `Assets/Package/PackageTool/Editor/PackageManifestConfig.cs:37`, the user-facing string table [`EditorConstants`](api.md#editorconstants) at `Assets/Package/PackageTool/Editor/EditorConstants.cs:32`, the CI batch entry point [`CIUtils`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:14`, and [`MenuItems`](api.md#menuitems) at `Assets/Package/PackageTool/Editor/MenuItems.cs:6`.
+`PackageTool` (root) holds the configuration ScriptableObject [`PackageManifestConfig`](api.md#packagemanifestconfig) at `Assets/Package/PackageTool/Editor/PackageManifestConfig.cs:37`, the user-facing string table [`EditorConstants`](api.md#editorconstants) at `Assets/Package/PackageTool/Editor/EditorConstants.cs:32`, the CI batch entry point [`CIUtils`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:16`, the public export facade [`PackageToolApi`](api.md#packagetoolapi) at `Assets/Package/PackageTool/Editor/PackageToolApi.cs:13`, and [`MenuItems`](api.md#menuitems) at `Assets/Package/PackageTool/Editor/MenuItems.cs:6`.
 
 `PackageTool.Drawers` contains `PropertyDrawer` subclasses for the nested data types on `PackageManifestConfig`: [`AuthorPropertyDrawer`](api.md#authorpropertydrawer) (`Assets/Package/PackageTool/Editor/Drawers/AuthorPropertyDrawer.cs:34`), [`DependencyPropertyDrawer`](api.md#dependencypropertydrawer), [`SamplePropertyDrawer`](api.md#samplepropertydrawer), and [`CopyEntryPropertyDrawer`](api.md#copyentrypropertydrawer). All four are IMGUI drawers with manual `Rect` math.
 
 `PackageTool.Inspectors` has a single class, [`PackageManifestConfigInspector`](api.md#packagemanifestconfiginspector) at `Assets/Package/PackageTool/Editor/Inspectors/PackageManifestConfigInspector.cs:33` — a tab-based `UnityEditor.Editor` that drives every export button and renders the reorderable lists (keywords, dependencies, samples, copy entries).
 
-`PackageTool.Tools` is the helpers layer. [`FileTools`](api.md#filetools) owns the export pipeline (`CreateOrUpdatePackageSource`); [`CodeGenTools`](api.md#codegentools) emits `VersionConstants.cs`; [`PackageManifestTools`](api.md#packagemanifesttools) discovers configs and serializes `package.json`; [`GitTools`](api.md#gittools) probes branch/HEAD for the version token chain; [`CommandLineTools`](api.md#commandlinetools) parses CI key/value args; [`GUILayoutTools`](api.md#guilayouttools) provides reusable file/folder picker drawers; [`UnityFileTools`](api.md#unityfiletools) handles legacy `.unitypackage` compilation; and [`PackageJsonModel`](api.md#packagejsonmodel) is the JSON DTO with its `Author`/`Repository`/`Bugs`/`Sample` sub-models.
+`PackageTool.Tools` is the helpers layer. [`FileTools`](api.md#filetools) owns the export pipeline (`CreateOrUpdatePackageSource`); [`CodeGenTools`](api.md#codegentools) emits `VersionConstants.cs`; [`PackageManifestTools`](api.md#packagemanifesttools) discovers configs and serializes `package.json`; [`GitTools`](api.md#gittools) probes branch/HEAD for the version token chain; [`CommandLineTools`](api.md#commandlinetools) parses CI key/value args; [`GUILayoutTools`](api.md#guilayouttools) provides reusable file/folder picker drawers; [`UnityFileTools`](api.md#unityfiletools) handles legacy `.unitypackage` compilation; [`PackageJsonModel`](api.md#packagejsonmodel) is the JSON DTO with its `Author`/`Repository`/`Bugs`/`Sample` sub-models; and [`CIResultModel`](api.md#ciresultmodel)/[`CIConfigModel`](api.md#ciconfigmodel)/[`CIResultTools`](api.md#ciresulttools) serialize the result file written by the command-line entry points.
 
 `PackageTool.Utils.PackageInitialize` is the Init Package flow: [`PackageInitializeWindow`](api.md#packageinitializewindow) is the `EditorWindow`, [`PackageInitializeUtil`](api.md#packageinitializeutil) creates folders and the config asset, and [`PackageInitializeTemplates`](api.md#packageinitializetemplates) holds the README/CHANGELOG/LICENSE string templates.
 
@@ -42,18 +42,22 @@ PackageTool
 
 ## Entry Points
 
-- `[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/PrepareDll")]` -> [`CIUtils.PrepareDll`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:319`. 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.
+- [`CIUtils.Generate`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:73` — batch-mode entry point invoked via `unity -batchmode -executeMethod PackageTool.CIUtils.Generate <key>=<value>`. Exports both the package source and the legacy package for every selected config. Reads keys parsed by [`CommandLineTools.GetKVPCommandLineArguments`](api.md#commandlinetools); see **CI command-line keys** below for the supported keys.
+- [`CIUtils.ExportPackageSource`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:213` — batch-mode entry point that exports only the package source of the selected configs.
+- [`CIUtils.ExportLegacyPackage`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:218` — batch-mode entry point that exports only the legacy `.unitypackage` of the selected configs.
+- [`CIUtils.ListConfigs`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:196` — batch-mode entry point that writes every config in the project to the `resultpath` file so a caller can discover which selectors are valid.
+- [`CIUtils.PrepareDll`](api.md#ciutils) at `Assets/Package/PackageTool/Editor/CIUtils.cs:319` — 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.
+- [`PackageToolApi`](api.md#packagetoolapi) at `Assets/Package/PackageTool/Editor/PackageToolApi.cs:13` — the in-process facade every other entry point (Inspector buttons and command-line methods alike) is built on: `GetConfigs`, `FindConfig`/`GetConfig`, `GenerateVersionConstants`, `ExportPackageSource`, `ExportLegacyPackage`. Call these from your own editor code instead of the `internal` helpers in `PackageTool.Tools`.
 - [`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`](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`.
+- **Generate VersionConstants.cs** -> [`PackageToolApi.GenerateVersionConstants`](api.md#packagetoolapi)`(config)` at `Assets/Package/PackageTool/Editor/PackageToolApi.cs:78`.
+- **Export Package Source** -> [`PackageToolApi.ExportPackageSource`](api.md#packagetoolapi)`(config)` at `Assets/Package/PackageTool/Editor/PackageToolApi.cs:94`.
+- **Export as Legacy Package** -> [`PackageToolApi.ExportLegacyPackage`](api.md#packagetoolapi)`(config)` at `Assets/Package/PackageTool/Editor/PackageToolApi.cs:112`.
 
 ## Data Model
 
@@ -64,32 +68,33 @@ 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#sample)), `copyEntries` ([`CopyEntry[]`](api.md#packagemanifestconfig-copyentry)).
+- **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#author) — `name`, `email`, `url` (`string`).
-- [`Dependency`](api.md#packagemanifestconfig-dependency) — `packageName`, `packageVersion` (`string`); `IsEmpty()` is true when either is blank.
+- [`Dependency`](api.md#packagemanifestconfigdependency) — `packageName`, `packageVersion` (`string`); `IsEmpty()` is true when either is blank.
 - [`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#packagemanifestconfig-copyentry) — `sourcePath`, `destinationPath` (`string`); `IsEmpty()` is true when `sourcePath` is blank. See **Copy Entries staging** below.
+- [`CopyEntry`](api.md#packagemanifestconfigcopyentry) — `sourcePath`, `destinationPath` (`string`); `IsEmpty()` is true when `sourcePath` is blank. See **Copy Entries staging** below.
 
 ### Export pipeline
 
-[`FileTools.CreateOrUpdatePackageSource`](api.md#filetools)`(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:60` (and its throwing twin `CreateOrUpdatePackageSourceOrThrow` at line 79, which is what [`PackageToolApi.ExportPackageSource`](api.md#packagetoolapi) calls) 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).
+1. **`WritePackageJsonToSource(config)`** — write `package.json` into `sourcePath` (e.g. `Assets/Package/PackageTool/package.json`) and import it so Unity creates its meta file. The manifest lives in the package source folder so that both this export and the legacy `.unitypackage` export pick it up along with the rest of the source.
 2. Wipe and recreate `packageDestinationPath` (e.g. `Release/`).
-3. Copy `package.json` and its meta into `packageDestinationPath`.
-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#sample)'s `sourcePath` to `Samples~/{folderName}`, skipping `.meta` files.
+3. **`CopyEntriesToProject(config)`** — stage external content into the project; see below.
+4. **`CopyDocumentationToDirectory(config)`** — copy `readmePath`, `changelogPath`, `licensePath` into `sourcePath`; rebuild `sourcePath/Documentation~/` from `documentationPath`.
+5. **`RecursivelyCopyDirectoriesAndFiles(config, sourcePath, packageDestinationPath)`** — copy the package source tree (`package.json` and its meta included), honoring `packageIgnorePaths`.
+6. **`CopySamplesToDirectory(config)`** — wipe `packageDestinationPath/Samples~/` and copy each [`Sample`](api.md#sample)'s `sourcePath` to `Samples~/{folderName}`, skipping `.meta` files.
+
+[`UnityFileTools.CompileLegacyPackage`](api.md#unityfiletools)`(config)` at `Assets/Package/PackageTool/Editor/Tools/UnityFileTools.cs:45` calls the same `WritePackageJsonToSource` before gathering asset paths, so the exported `.unitypackage` ships the manifest too.
 
 ### Copy Entries staging
 
-`copyEntries` is a `PackageManifestConfig` field added in 2.0.12. Each [`CopyEntry`](api.md#packagemanifestconfig-copyentry) names a source path and a destination folder; entries run **first** in the export pipeline (step 4 above) so downstream steps — including the recursive source copy and the `CopySamplesToDirectory` step — can pick up the staged content and ship it into `packageDestinationPath`.
+`copyEntries` is a `PackageManifestConfig` field added in 2.0.12. Each [`CopyEntry`](api.md#packagemanifestconfigcopyentry) names a source path and a destination folder; entries run **first** in the export pipeline (step 4 above) so downstream steps — including the recursive source copy and the `CopySamplesToDirectory` step — can pick up the staged content and ship it into `packageDestinationPath`.
 
 **Folder source.** The folder's *content* is merged directly into `destinationPath` (no `destinationPath/{sourceName}` wrapper). Same-named files are overwritten via `File.Copy(..., overwrite: true)`; unrelated files already in the destination are left in place. This is the merge semantics needed to chain into a `Sample` whose `sourcePath` is the same folder.
 
@@ -116,14 +121,24 @@ IMGUI throughout — no UI Toolkit. There are no `.uxml` or `.uss` files in the
 
 ### CI command-line keys
 
-[`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`:
+Every [`CIUtils`](api.md#ciutils) entry point (`Generate`, `ExportPackageSource`, `ExportLegacyPackage`, `ListConfigs`) 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.<Method>`:
 
-- `id=<guid>[,<guid>...]` — restrict to specific `PackageManifestConfig._id`s. Omit to process all configs found by `PackageManifestTools.GetAllConfigs`.
+- `id=<selector>[,<selector>...]` — restrict to specific configs. Each selector is matched case-insensitively against `PackageManifestConfig.Id` (the guid), then `packageName` (e.g. `com.elestrago.unity.package-tools`), then the config asset name — first match wins, and a selector matching more than one config is an error. Omit the key to process all configs found by `PackageManifestTools.GetAllConfigs`.
 - `version=<semver>` — overrides `packageVersion` on every processed config (and marks the asset dirty).
-- `preview=<bool>` — parsed but not currently applied.
+- `preview=<bool>` — parsed by `Generate` but not currently applied.
 - `generateversionconstants=<bool>` — when true, runs `CodeGenTools.GenerateVersionConstants` before export.
+- `resultpath=<file>` — writes a JSON report of the run to that path so callers do not have to scrape the Unity log. `Generate`, `ExportPackageSource` and `ExportLegacyPackage` write an array of [`CIResultModel`](api.md#ciresultmodel) entries (`selector`, `configId`, `configName`, `packageName`, `packageVersion`, `success`, `packageSourcePath`, `legacyPackagePath`, `versionConstantsPath`, `error`); `ListConfigs` writes an array of [`CIConfigModel`](api.md#ciconfigmodel) entries. The file is always written before the editor exits.
+- `exitonfinish=<bool>` — when true, exits the editor with `0` on success and `1` on failure. Exiting is automatic when the `CI` environment variable is set.
+
+An unresolved selector is a warning in `Generate` (which keeps its historical warn-and-continue behavior) and a failure in `ExportPackageSource`/`ExportLegacyPackage`, where a caller asking for a specific package and getting nothing is an error.
+
+```bash
+Unity -batchmode -quit -projectPath . \
+  -executeMethod PackageTool.CIUtils.ExportPackageSource \
+  id=com.elestrago.unity.package-tools version=2.6.0 resultpath=/tmp/result.json
+```
 
-To add a new key, edit `Assets/Package/PackageTool/Editor/CIUtils.cs` (constants block at lines 17–20, parsing pattern in `Generate()` lines 91–113); do **not** touch `CommandLineTools.cs` — its parsing already handles arbitrary keys.
+To add a new key, edit `Assets/Package/PackageTool/Editor/CIUtils.cs` (constants block at lines 19–24, argument helpers `GetStringArgument`/`GetBoolArgument` at lines 419–427); do **not** touch `CommandLineTools.cs` — its parsing already handles arbitrary keys.
 
 ### VersionConstants template tokens
 
@@ -138,3 +153,4 @@ To add a new key, edit `Assets/Package/PackageTool/Editor/CIUtils.cs` (constants
 - New `PropertyDrawer`: add `Assets/Package/PackageTool/Editor/Drawers/{Type}PropertyDrawer.cs`, mark `internal sealed class : PropertyDrawer`, override `OnGUI(Rect, ...)` + `GetPropertyHeight`.
 - New `MenuItem`: add to `Editor/MenuItems.cs` (or alongside the class that owns the action, as `CIUtils.PrepareDll` does).
 - New helper: add `Editor/Tools/{Name}.cs`, mark `internal static class`, namespace `PackageTool.Tools`. Mirror [`FileTools`](api.md#filetools) or [`GitTools`](api.md#gittools) for shape.
+- New public entry point: add it to [`PackageToolApi`](api.md#packagetoolapi) rather than widening a `PackageTool.Tools` helper to `public` — the helpers stay `internal` on purpose and the facade is the package's supported surface.