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

package/CAHNGELOG.md

@@ -2,6 +2,43 @@
 
 ---
 
+## [2.5.2](https://gitlab.com/elestrago-pkg/package-tool/-/tags/2.5.2)
+
+### Fixed
+
+- Fixed `unity-package-docs` scanner dropping public `readonly struct` and `ref struct` types.
+
+---
+
+## [2.5.1](https://gitlab.com/elestrago-pkg/package-tool/-/tags/2.5.1)
+
+### Changed
+
+- Broadened `unity-package-release` skill triggers to cover generic commit phrasings such as "commit all changes".
+
+---
+
+## [2.5.0](https://gitlab.com/elestrago-pkg/package-tool/-/tags/2.5.0)
+
+### Added
+
+- Added `examples` section to `unity-package-docs` driven by `[CreateAssetMenu]`/`[MenuItem]`/public-static API entry points, one chunk per entry under `Documentation~/examples/`.
+
+### Changed
+
+- Made `CommandLineTools`, `GitTools`, `PackageInitializeTemplates`, `PackageInitializeUtil`, and `GitTools.Run` non-public so the supported entry points are `CIUtils.Generate` and `Tools/PackageTools/Init Package`.
+
+### Removed
+
+- Removed `samples` section from `unity-package-docs` (replaced by `examples`).
+
+### Fixed
+
+- Fixed `unity-package-docs` scanner missing expression-bodied methods (`... => Body();`).
+- Fixed broken nested-type anchor references in `Documentation~/manual.md` (e.g. `PackageManifestConfig.CopyEntry`).
+
+---
+
 ## [2.4.0](https://gitlab.com/elestrago-pkg/package-tool/-/tags/2.4.0)
 
 ### Added

package/Documentation~/examples/ciutils-generate.md

@@ -0,0 +1,41 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: CIUtils.Generate
+
+**Kind:** static-method
+
+**Entry point:** [CIUtils](../api.md#ciutils)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/CIUtils.cs:65`
+
+## What it does
+
+The CI entry point. Reads `id=<guid>[,<guid>...]`, `version=<semver>`, `preview=<bool>`, and `generateversionconstants=<bool>` from the command line (case-insensitive `key=value` pairs), filters the [PackageManifestConfig](../api.md#packagemanifestconfig) assets to process, optionally overrides each config's `packageVersion`, optionally runs [CodeGenTools.GenerateVersionConstants](../api.md#codegentools), and exports the package source via [FileTools.CreateOrUpdatePackageSource](../api.md#filetools). Wraps the work in `LockReloadAssemblies` + `StartAssetEditing` to avoid mid-export refreshes.
+
+## Snippet
+
+```bash
+# Headless build — call from CI after PrepareDll has fixed plugin flags.
+"$UNITY_PATH" \
+  -batchmode \
+  -quit \
+  -projectPath "$PROJECT_PATH" \
+  -executeMethod PackageTool.CIUtils.Generate \
+  -id ea4351b5-3f49-4afc-8996-ec7b9eb43204 \
+  -version 2.4.1 \
+  -generateversionconstants true \
+  -logFile -
+```
+
+```csharp
+// Or invoke directly from an editor script — Generate() reads -id / -version /
+// -generateversionconstants from Environment.GetCommandLineArgs itself.
+PackageTool.CIUtils.Generate();
+```
+
+## Observable effect
+
+- `Release/<packageName>/` is created or updated with the exported package layout (sources, package.json, README, CHANGELOG, LICENSE, Samples~, Documentation~).
+- `Release/package.json` is rewritten with the version, dependencies, and samples block derived from the config.
+- If `generateversionconstants=true`, a new `VersionConstants.cs` is emitted at the configured path before export.
+- Console prints `[Package Tools]` lines summarizing what was processed; the editor does not exit (unlike `PrepareDll`).

package/Documentation~/examples/create-packagemanifestconfig.md

@@ -0,0 +1,47 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: Create a PackageManifestConfig
+
+**Kind:** create-asset
+
+**Entry point:** [PackageManifestConfig](../api.md#packagemanifestconfig)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/PackageManifestConfig.cs:37`
+
+**Create menu:** `Assets > Create > JCMG/PackageTools/PackageManifestConfig`
+
+## What it does
+
+Creates the ScriptableObject that drives every other entry point — package name, version, sources, dependencies, samples, and the destination path the **Export Package Source** inspector button and `CIUtils.Generate` both read. One config asset per Unity package; everything else (CHANGELOG, README, asmdef wiring, exported `package.json`) is derived from its fields.
+
+## Snippet
+
+```csharp
+using PackageTool;
+using UnityEditor;
+using UnityEngine;
+
+public static class CreatePackageManifestConfigExample
+{
+    [MenuItem("Tools/Examples/Create PackageManifestConfig")]
+    public static void Run()
+    {
+        var config = ScriptableObject.CreateInstance<PackageManifestConfig>();
+        config.packageName = "com.example.foo";
+        config.displayName = "Example Foo";
+        config.packageVersion = "0.1.0";
+        config.unityVersion = "2021.3";
+        config.sourcePath = "Assets/Package/Foo";
+        config.packageDestinationPath = "Release";
+
+        AssetDatabase.CreateAsset(config, "Assets/PackageManifest/PackageManifestConfig.asset");
+        AssetDatabase.SaveAssets();
+    }
+}
+```
+
+## Observable effect
+
+- A new asset appears at `Assets/PackageManifest/PackageManifestConfig.asset`.
+- Selecting it in the Project view renders the inspector with **Generate VersionConstants.cs**, **Export Package Source**, and **Export as Legacy Package** buttons.
+- The same `Assets > Create > JCMG/PackageTools/PackageManifestConfig` menu entry yields the same asset interactively if you prefer GUI.

package/Documentation~/examples/init-package.md

@@ -0,0 +1,30 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: Init Package
+
+**Kind:** menu-item
+
+**Entry point:** [MenuItems](../api.md#menuitems)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/MenuItems.cs:9`
+
+**Menu path:** `Tools/PackageTools/Init Package`
+
+## What it does
+
+Opens the **Init Package** editor window ([PackageInitializeWindow](../api.md#packageinitializewindow)), which scaffolds a new Unity package: creates `Assets/Package/<scope>/` with `Editor/` (and optionally `Runtime/`), root files (`README.md`, `CAHNGELOG.md`, `LICENSE`), `Documentation~/`, and a sibling `PackageManifestConfig.asset` populated from the form's fields. The internal helpers that do the on-disk work are intentionally not part of the public surface — the window is the supported entry point.
+
+## Snippet
+
+```csharp
+// MenuItems is internal, so other assemblies can't invoke OpenAboutModalDialog
+// directly. Open the window via PackageInitializeWindow.Open(), or use the menu.
+PackageTool.Utils.PackageInitialize.PackageInitializeWindow.Open();
+// Or interactively: Tools > PackageTools > Init Package
+```
+
+## Observable effect
+
+- The **Init Package** editor window opens. Fill in package name, display name, scope, author, license, and unity version, then click **Create**.
+- On Create: `Assets/Package/<scope>/` and `Assets/PackageManifest/PackageManifestConfig.asset` are written; the inspector for the new config asset shows the **Generate VersionConstants.cs** / **Export Package Source** / **Export as Legacy Package** buttons.
+- The project compiles after the next assembly reload.

package/Documentation~/examples/preparedll.md

@@ -0,0 +1,39 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Example: PrepareDll
+
+**Kind:** menu-item
+
+**Entry point:** [CIUtils](../api.md#ciutils)
+
+**Declared at:** `Assets/Package/PackageTool/Editor/CIUtils.cs:197`
+
+**Menu path:** `Tools/PackageTools/PrepareDll`
+
+## What it does
+
+Fixes the platform flags on every plugin (`.dll`) under the configured package source before export, so the published package's `PluginImporter` settings match what the Editor needs (no spurious `Any Platform` toggles that would otherwise leak into consumers). When the `CI` environment variable is set, the method calls `EditorApplication.Exit` with code 0 on success or 1 on failure — designed to be the final step of a batch-mode build before the export job moves on.
+
+## Snippet
+
+```bash
+# Run from CI or any shell — replace UNITY_PATH and PROJECT_PATH with your values.
+"$UNITY_PATH" \
+  -batchmode \
+  -quit \
+  -projectPath "$PROJECT_PATH" \
+  -executeMethod PackageTool.CIUtils.PrepareDll \
+  -logFile -
+# Or interactively: Tools > PackageTools > PrepareDll
+```
+
+```csharp
+// Same call from an editor script (no Exit when CI env var is unset):
+PackageTool.CIUtils.PrepareDll();
+```
+
+## Observable effect
+
+- Every `.dll` under each `PackageManifestConfig.sourcePath` has its `PluginImporter` flags normalized; meta files are rewritten as a result and may show up in `git status`.
+- Console prints `[Package Tools]` log lines for each plugin touched.
+- In CI (`CI=1` or similar), the editor exits 0 on success or 1 if any plugin processing throws — wire this into your pipeline as the gate before `CIUtils.Generate`.

package/Documentation~/examples.md

@@ -0,0 +1,25 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# Package Tool — Examples
+
+Short, focused usage examples that exercise this package's public API. Each example is independent and links into the API reference (`api.md`) for the type or member it calls. Snippets are paste-ready and use only public API — copy one into a fresh project to reach the same observable effect.
+
+## 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.
+
+## Contents
+
+| Example | Kind | Entry point |
+|---------|------|-------------|
+| [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) |
+| [CIUtils.Generate](examples/ciutils-generate.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.
+
+## Notes
+
+- 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.

package/Documentation~/manual.md

@@ -64,16 +64,16 @@ 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#packagemanifestconfigcopyentry)).
+- **Staging:** `samples` ([`Sample[]`](api.md#sample)), `copyEntries` ([`CopyEntry[]`](api.md#packagemanifestconfig-copyentry)).
 - **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#packagemanifestconfigdependency) — `packageName`, `packageVersion` (`string`); `IsEmpty()` is true when either is blank.
+- [`Dependency`](api.md#packagemanifestconfig-dependency) — `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#packagemanifestconfigcopyentry) — `sourcePath`, `destinationPath` (`string`); `IsEmpty()` is true when `sourcePath` is blank. See **Copy Entries staging** below.
+- [`CopyEntry`](api.md#packagemanifestconfig-copyentry) — `sourcePath`, `destinationPath` (`string`); `IsEmpty()` is true when `sourcePath` is blank. See **Copy Entries staging** below.
 
 ### Export pipeline
 
@@ -89,7 +89,7 @@ Nested `[Serializable]` types, each with a `PropertyDrawer` in `PackageTool.Draw
 
 ### Copy Entries staging
 
-`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`.
+`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`.
 
 **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.
 

package/Editor/Tools/CommandLineTools.cs

@@ -30,7 +30,7 @@ namespace PackageTool.Tools
 	/// <summary>
 	/// Helper methods for command-line usage
 	/// </summary>
-	public static class CommandLineTools
+	internal static class CommandLineTools
 	{
 		// Command-Line Delimiters
 		private const string ARGUMENT_DELIMITER_STR = "=";
@@ -65,4 +65,4 @@ namespace PackageTool.Tools
 			return dict;
 		}
 	}
-}
+}

package/Editor/Tools/GitTools.cs

@@ -30,11 +30,15 @@ namespace PackageTool.Tools
 	/// <summary>
 	/// Helper methods for retrieving git information
 	/// </summary>
-	public static class GitTools
+	internal static class GitTools
 	{
 		private const string GIT_APPLICATION = "git";
 
-		public static string Run(string cmd)
+		public static string GetBranch() => Run("rev-parse --abbrev-ref HEAD");
+
+		public static string GetLongHeadHash() => Run("rev-parse HEAD");
+
+		private static string Run(string cmd)
 		{
 			// NOTE: This currently expects that you have git included in your PATH.
 			var p = new Process();
@@ -52,15 +56,5 @@ namespace PackageTool.Tools
 
 			return output;
 		}
-
-		public static string GetBranch()
-		{
-			return Run("rev-parse --abbrev-ref HEAD");
-		}
-
-		public static string GetLongHeadHash()
-		{
-			return Run("rev-parse HEAD");
-		}
 	}
-}
+}

package/Editor/Utils/PackageInitialize/PackageInitializeTemplates.cs

@@ -2,7 +2,7 @@ using System;
 
 namespace PackageTool.Utils.PackageInitialize
 {
-	public static class PackageInitializeTemplates
+	internal static class PackageInitializeTemplates
 	{
 		public static string CreateChangelog(string homepage) => @$"# Changelog
 

package/Editor/Utils/PackageInitialize/PackageInitializeUtil.cs

@@ -4,7 +4,7 @@ using UnityEngine;
 
 namespace PackageTool.Utils.PackageInitialize
 {
-	public static class PackageInitializeUtil
+	internal static class PackageInitializeUtil
 	{
 		public const string ASSETS_FOLDER_NAME = "Assets";
 		public const string RELEASE_FOLDER_NAME = "Release";

package/README.md

@@ -29,7 +29,7 @@ Add the package to `Packages/manifest.json`:
     }
   ],
   "dependencies": {
-    "com.elestrago.unity.package-tools": "2.4.0"
+    "com.elestrago.unity.package-tools": "2.5.2"
   }
 }
 ```
@@ -60,7 +60,7 @@ CIUtils.Generate();
 
 - [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.
+- [Examples](Documentation~/examples.md) — short usage examples for the public API.
 
 ## License
 

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

@@ -1,6 +1,6 @@
 ---
 name: unity-package-docs
-description: Create or update AI-first documentation for a Unity package at the repository root — README.md plus Documentation~/manual.md, api.md, samples.md, all structured for dense AI ingestion with explicit file paths and explicit mapping between the package source and the sample project. Auto-chunks large API/manual/samples by namespace/section to keep navigation intact. Use when the user wants to generate or refresh Unity package docs from source. Works in any Unity package repo with one package per repo (discovered via package.json, with a fallback to PackageManifestConfig.asset for package-tool-based projects).
+description: Create or update AI-first documentation for a Unity package at the repository root — README.md plus Documentation~/manual.md, api.md, examples.md, all structured for dense AI ingestion with explicit file paths and explicit links from each usage example into the API reference. Auto-chunks large API/manual by namespace/section, and emits one chunk per public API entry point (each `[CreateAssetMenu]`, `[MenuItem]`, and public static entry-point method) under Documentation~/examples/ as a focused short snippet, so a consumer reading the published docs learns how to call the package without importing Samples~/ via Package Manager. Use when the user wants to generate or refresh Unity package docs from source. Works in any Unity package repo with one package per repo (discovered via package.json, with a fallback to PackageManifestConfig.asset for package-tool-based projects).
 ---
 
 # unity-package-docs
@@ -15,12 +15,16 @@ Files created/updated at the repository root — **never** inside the package fo
 <repo-root>/
 ├── README.md
 └── Documentation~/
-    ├── manual.md
-    ├── api.md
-    └── samples.md
+    ├── manual.md          (or manual/<slug>.md chunks when over threshold)
+    ├── api.md             (or api/<Namespace>.md chunks when over threshold)
+    ├── examples.md        (always an index — see below)
+    └── examples/
+        └── <slug>.md      (one chunk per public API entry point)
 ```
 
-The `Documentation~` folder name MUST include the trailing tilde (Unity convention — excludes it from asset import). Pre-existing files inside `Documentation~/` (e.g. screenshots) are left untouched; only the three `.md` files listed are managed.
+The `Documentation~` folder name MUST include the trailing tilde (Unity convention — excludes it from asset import). Pre-existing files inside `Documentation~/` (e.g. screenshots) are left untouched; only the managed `.md` files (and their parent dirs under `manual/`, `api/`, `examples/`) are managed.
+
+`examples.md` is always a small index linking to per-entry-point chunks. Each chunk under `examples/<slug>.md` is a short usage example (1 paragraph + ≤ ~20-line snippet) that calls into the public API documented in `api.md`. This is distinct from Unity's `Samples~/` folder, which the package author may ship for Package Manager → Samples → Import; the docs do **not** embed `Samples~/` source verbatim — examples are curated for "how do I use this API?", and `README.md` carries a one-line pointer at the available Unity samples for anyone who wants the importable content.
 
 Every generated `.md` file begins with this exact marker on line 1:
 
@@ -34,8 +38,8 @@ Every generated `.md` file begins with this exact marker on line 1:
 2. **Predictable structure.** Use the exact section names and order specified in each step below. Same anchor slugs every run so agents crawling multiple package docs can rely on the shape.
 3. **Explicit paths everywhere.** Every reference to source code uses `path/to/File.cs` relative to the repo root, with `:line` when pointing at a specific declaration. Never write "see the inspector class" — write `see Assets/Package/.../Inspectors/Foo.cs:33`.
 4. **Complete, tagged code blocks.** Every fenced block has a language tag (` ```csharp `, ` ```json `, ` ```yaml `, ` ```bash `). Snippets are paste-ready — no `// ...` elisions that lose context.
-5. **Explicit package ↔ sample mapping.** In `samples.md`, every sample file is mapped to the exact package type(s) it instantiates or extends, with file paths on both sides. An agent reading the docs must be able to write equivalent code in a fresh project.
-6. **No forward references to undocumented things.** If `manual.md` mentions a type, that type appears in `api.md` with a stable anchor. `samples.md` links into `api.md` rather than re-describing types.
+5. **Examples link into the API.** In `examples.md` and its chunks, every code example is anchored on a discoverable public API entry point (a `[CreateAssetMenu]`, `[MenuItem]`, or public static entry method) and links into the corresponding `api.md` anchor. Snippets are short, paste-ready, and call only public API. An agent reading the docs must be able to take any example, paste it into a fresh project, and reach the same observable effect.
+6. **No forward references to undocumented things.** If `manual.md` mentions a type, that type appears in `api.md` with a stable anchor. `examples.md` and chunks link into `api.md` rather than re-describing types.
 
 ## Skill args
 
@@ -44,8 +48,8 @@ Parse from the user input (default values shown):
 - `force=false` — when `true`, overwrite files even if they lack the generator marker.
 - `dry-run=false` — when `true`, print the would-be output to the conversation without writing any files.
 - `package=<path>` — override package-root auto-discovery (for repos with multiple packages or a non-standard layout).
-- `chunk-threshold-lines=800` — when a rendered Documentation~ file's draft exceeds this many lines, the file is split into chunks (see Step 3.5). Below the threshold, output is identical to today's single-file form. Set very high (e.g. `100000`) to disable chunking entirely.
-- `chunk-threshold-api=<n>`, `chunk-threshold-manual=<n>`, `chunk-threshold-samples=<n>` — per-file overrides of `chunk-threshold-lines`. Each defaults to the global value.
+- `chunk-threshold-lines=800` — when a rendered `api.md` or `manual.md` draft exceeds this many lines, the file is split into chunks (see Step 3.5). Below the threshold, output is the single-file form. Set very high (e.g. `100000`) to disable chunking for those two files. **Does not gate `examples.md`** — examples are always per-entry-point chunked (see Step 6); the granularity is fixed by the API surface, not by line count.
+- `chunk-threshold-api=<n>`, `chunk-threshold-manual=<n>` — per-file overrides of `chunk-threshold-lines`. Each defaults to the global value. `chunk-threshold-samples` and `chunk-threshold-examples` are accepted for backward compatibility but ignored.
 
 ## Pipeline (execute these steps in order)
 
@@ -86,7 +90,7 @@ From `package.json` (preferred) or `PackageManifestConfig.asset`, extract:
 | Samples | `samples` (array of `{path, displayName, description}`) | `samples` (array of `{sourcePath, folderName, displayName, description}`) |
 | Registry | `publishConfig.registry` | (not in config; omit) |
 
-For the config fallback, the **sample source paths** on disk are taken from `samples[].sourcePath`. For `package.json` projects, the on-disk sample paths are inside the package dir at `<package-root>/Samples~/<folderName>` (only present if previously exported); if absent, scan `Assets/Samples/`, `Samples/`, and `Assets/Example/` as fallback candidates.
+The `samples[]` block is read for **README only** — it drives the one-line Unity Samples~/ pointer described in Step 7 ("This package ships the following Package Manager samples: …"). It does NOT drive any content under `Documentation~/`. The docs section is `examples`, generated from the public API surface in Step 6, not from `Samples~/` files. Earlier revisions of this skill mirrored `Samples~/` source into the docs; that's been deprecated because the embedded source is duplicative of what Package Manager → Samples → Import already provides, and most `Samples~/` content (scenes, prefabs, internal post-import scripts) doesn't teach API usage.
 
 ### Step 3 — Scan source
 
@@ -95,10 +99,11 @@ Run the bundled Python scanner. Its absolute path is `${SKILL_DIR}/scripts/scan_
 ```bash
 python3 "${SKILL_DIR}/scripts/scan_package.py" \
   --package "<package-root>" \
-  --samples "<sample-dir-1>" --samples "<sample-dir-2>" \
   --repo-root .
 ```
 
+The scanner still accepts `--samples <dir>` (and emits `samples[]` in its output) for backward compatibility, but **do not pass it** in this revision — the `examples` pipeline (Step 6) derives chunks from the public API surface (`types[]`, member `attributes`), not from `samples[]`. If `samples[]` happens to be non-empty in a stale invocation, the pipeline ignores it.
+
 The scanner emits JSON to stdout with this shape:
 
 ```json
@@ -127,38 +132,47 @@ The scanner emits JSON to stdout with this shape:
       ]
     }
   ],
-  "samples": [
-    {"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}
-  ]
+  "samples": []
 }
 ```
 
-Notes on the new `md5` / `lines` / `files` fields (added in this revision):
+Notes on the `md5` / `lines` / `files` fields:
 
 - `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.
+- `samples[]` is present in the scanner's output schema but, in this revision of the skill, is not consumed by any step downstream of Step 3. Treat the field as legacy.
 
 Capture this JSON; the rest of the pipeline consumes it.
 
 ### Step 3.5 — Plan chunking
 
-For each Documentation~ file (`api.md`, `manual.md`, `samples.md`), decide whether to emit it as a single file or as a chunk index plus per-chunk files. Decision procedure:
+`api.md` and `manual.md` use a size-gated decision; `examples.md` is always chunked, one chunk per discovered entry point.
+
+**For `api.md` and `manual.md`:**
 
-1. **Render to an in-memory buffer first.** Run the full Step 4/5/6 rendering logic into a string. Count its lines (`\n`-separated, EOF-trimmed).
-2. **Resolve the threshold** for this file: use the file-specific arg if supplied (`chunk-threshold-api`, `chunk-threshold-manual`, `chunk-threshold-samples`), else the global `chunk-threshold-lines` (default 800).
+1. **Render to an in-memory buffer first.** Run the full Step 4/5 rendering logic into a string. Count its lines (`\n`-separated, EOF-trimmed).
+2. **Resolve the threshold** for this file: use the file-specific arg if supplied (`chunk-threshold-api`, `chunk-threshold-manual`), else the global `chunk-threshold-lines` (default 800).
 3. **Apply the structural floor.** Skip chunking even when the threshold is exceeded if the file is structurally unsplittable:
    - `api.md`: chunk only when `namespaces.length > 1`.
-   - `samples.md`: chunk only when the sample mapping covers more than one file (i.e. `samples.length > 1`).
    - `manual.md`: chunk only when at least one H2 section in the draft individually exceeds the threshold. (Splitting a single oversized section yields no benefit.)
-4. **Decide:** if `linesDrafted > threshold` AND the structural floor passes → **chunked**; else → **single-file** (write the draft as-is at Step 4/5/6's write step).
+4. **Decide:** if `linesDrafted > threshold` AND the structural floor passes → **chunked**; else → **single-file** (write the draft as-is at Step 4/5's write step).
+
+**For `examples.md`: always chunked, one chunk per public API entry point.** No threshold check. The chunk set is computed directly from the scanner manifest's `types[]`/members, not from any line-count heuristic.
 
 For each file decided to chunk, plan the chunk set:
 
 - `api.md` → one chunk per namespace: `Documentation~/api/<Namespace>.md` (literal namespace, no slugification — e.g. `Documentation~/api/PackageTool.Tools.md`). Do NOT sub-split a single huge namespace.
-- `samples.md` → one chunk per top-level sample folder: `Documentation~/samples/<SampleFolderName>.md`. Sanitize `<SampleFolderName>` to `[A-Za-z0-9._-]` (replace any other character with `-`).
 - `manual.md` → one chunk per H2 section using this fixed slug set: `overview.md`, `architecture.md`, `assemblies.md`, `entry-points.md`, `data-model.md`, `editor-ui.md`, `extension-points.md` (these correspond 1:1 to the H2 sections in `manual.md.template`). Sections that render empty are omitted from the chunk set.
+- `examples.md` → one chunk per discovered entry point. Enumerate, in this order (`exampleKind` shown in parens):
+  1. **`[CreateAssetMenu]` types** (`exampleKind = create-asset`). Source: every `types[i]` with `attributes` containing `CreateAssetMenu(...)`. Slug = `create-` + `<TypeName>` lowercased + sanitized to `[a-z0-9-]`.
+  2. **`[MenuItem]` methods** (`exampleKind = menu-item`). Source: every `members[]` member with an attribute matching `MenuItem("<path>")`. Slug = the last `/`-separated segment of the menu path, lowercased + sanitized to `[a-z0-9-]` (spaces collapse to `-`). Example: `Tools/PackageTools/Init Package` → `init-package`.
+  3. **Public static entry-point methods** (`exampleKind = static-method`). Source: every `members[]` method on a `public static` type, with the method itself `public static`, that is NOT also already produced by rules 1 or 2 above. Slug = `<TypeName-lower>-<MethodName-lower>` sanitized. Example: `CIUtils.Generate` → `ciutils-generate`.
+
+  Chunk paths: `Documentation~/examples/<slug>.md` (flat directory, single level — no nesting). Disambiguation: if two entry points produce the same slug, append `-2`, `-3`, … in discovery order. Print one line per discovered example, e.g. `example-plan: create-packagemanifestconfig ← PackageManifestConfig [CreateAssetMenu]`.
+
+  Cap: if more than 20 candidates result from rule 3 (rare in tightly-scoped editor tools, common in libraries with many public statics), emit the first 20 sorted by `TypeName, MethodName` and warn `example-plan: capped at 20 static-method entry points (N skipped). Hand-author additional chunks under Documentation~/examples/ as needed (marker-gated, preserved on regen).`
+
+**Sample inputs the skill should NOT promote to examples** (avoid noise): private/internal members, methods with `[Obsolete]`, partial-class internals, generated code (files under `Generated/`). Filter these out before the rules above.
 
 Build a **`crossRefMap`**: `{ typeAnchor → "<destination-relative-to-Documentation~>#<anchor>" }`, populated during the api decision:
 
@@ -167,13 +181,13 @@ Build a **`crossRefMap`**: `{ typeAnchor → "<destination-relative-to-Documenta
 
 `crossRefMap` is consumed by Steps 5 and 6 when emitting `[Type](…)` references. Renderers MUST NOT hard-code `api.md` in link destinations — always resolve via `crossRefMap`.
 
-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)`.
+Print one line per file decision. Examples: `chunk-plan: api.md → chunked (12 namespaces, draft=2143 lines, threshold=800)`, `chunk-plan: manual.md → single (draft=312 lines)`, `chunk-plan: examples.md → chunked (always: 7 entry points → 7 chunks under Documentation~/examples/)`.
 
 ### 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).
+The check only applies to `api.md` and its chunks. `manual.md` is skipped here because its content is synthesized across many files. `examples.md` and its chunks are skipped because each example chunk is small and re-deriving it from the manifest is cheap — adding fast-update for examples is left as future work.
 
 Procedure for **each** prospective api output (the single `api.md` in the single-file branch, or each `api/<Namespace>.md` in the chunked branch):
 
@@ -189,13 +203,13 @@ Print one line per check, e.g. `fast-update: api/PackageTool.Tools.md → skippe
 
 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.
+- 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 `examples.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.
+Render this file first because `manual.md` and `examples.md` link into its anchors (via `crossRefMap` from Step 3.5) and you want those anchors to exist.
 
 Read `${SKILL_DIR}/assets/api.md.template`. Replace `{{displayName}}` with the discovered value. Replace `{{namespaceContentsList}}` with a bulleted index of namespaces, each linking to its anchor. Replace `{{perNamespaceSections}}` with one section per namespace following the structure documented in the template's HTML comment block.
 
@@ -240,7 +254,14 @@ Read `${SKILL_DIR}/assets/manual.md.template`. Fill each placeholder:
 - `{{editorUiProse}}` — Detect IMGUI vs UI Toolkit by checking for `.uxml`/`.uss` files under the package root and for types inheriting `EditorWindow` / `PropertyDrawer` / `UnityEditor.Editor`. State which approach is used and list representative file paths.
 - `{{extensionPointsList}}` — Public abstract types, public virtual methods, types ending in `Base`, or those marked `partial`. If none, write `None.`.
 
-**Resolving `[Type](…)` links.** When rendering any link to a package type, look it up in `crossRefMap` (built in Step 3.5). Use the value verbatim. Do NOT hard-code `api.md#anchor`. If the link is emitted from a manual chunk file (chunked branch), the value must be prefixed with `../` (because chunks live under `manual/`); the renderer prepends `../` to every `crossRefMap` value when emitting from a chunk file, and emits the bare value when emitting from the index-level `manual.md`. Same rule applies to samples in Step 6.
+**Resolving `[Type](…)` links.** When rendering any link to a package type, look it up in `crossRefMap` (built in Step 3.5). Use the value verbatim, then prefix it based on the *depth* of the emitting file under `Documentation~/`:
+
+- Top-level index files (`Documentation~/api.md`, `Documentation~/manual.md`, `Documentation~/examples.md`): depth 0, no prefix — emit the bare `crossRefMap` value.
+- `Documentation~/manual/<slug>.md`: depth 1, prepend `../`.
+- `Documentation~/api/<Namespace>.md`: depth 1, prepend `../`.
+- `Documentation~/examples/<slug>.md`: depth 1, prepend `../`.
+
+The depth rule generalizes for any future nesting: `depth = (number of "/" segments in the chunk path under Documentation~) - 1`, and the renderer prepends `"../" * depth`. Do NOT hard-code `api.md#anchor` anywhere — always go through `crossRefMap` + depth-prefix. Same rule applies to Step 6 example chunks.
 
 **Output (single-file branch, default):** if Step 3.5 decided manual is single-file, write the rendered draft to `Documentation~/manual.md` as-is.
 
@@ -250,27 +271,58 @@ Read `${SKILL_DIR}/assets/manual.md.template`. Fill each placeholder:
 2. **One index** at `Documentation~/manual.md` containing the generator marker, the H1 (`# {{displayName}} — Manual`), a `## Contents` Markdown table (`| Section | Description |`) linking each chunk (one row per emitted slug; description = the first sentence of that section's body), and one-line `## Notes`: `This manual is split by section; see files under \`manual/\`.`
 3. **Stale chunks:** before writing, list `Documentation~/manual/*.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>`.
 
-### Step 6 — Render `Documentation~/samples.md`
+### Step 6 — Render `Documentation~/examples.md` + per-entry-point chunks
+
+`examples.md` is always emitted as a light **index**, with one chunk per public API entry point under `Documentation~/examples/<slug>.md`. The chunk set is computed in Step 3.5.
+
+**Why examples, not sample-source mirroring.** Unity's `Samples~/` is shipped via Package Manager → Samples → Import; the source is reachable that way for anyone who wants the full importable content. Embedding `Samples~/` source verbatim under `Documentation~/` is duplicative and inflates what every consumer downloads. The high-value docs content is "**how do I use this package's API**" — short snippets that exercise a single entry point and link into `api.md` for the deeper reference. That is what every chunk under `Documentation~/examples/` is: a focused, paste-ready usage example.
+
+#### Render the index — `Documentation~/examples.md`
+
+Read `${SKILL_DIR}/assets/examples.md.template` (the index template). Fill placeholders:
+
+- `{{contentsTableRows}}` — One Markdown table row per chunk: `| [<title>](examples/<slug>.md) | <exampleKind> | <entry-point> |` where:
+  - `<title>` is the human-readable title (see chunk titling below).
+  - `<exampleKind>` is `create-asset`, `menu-item`, or `static-method` from Step 3.5.
+  - `<entry-point>` is the link into `api.md` for the type or member, rendered via the bare `crossRefMap` value (depth 0).
+- `{{quickStartProse}}` — one short paragraph (≤ 4 sentences) framing how a downstream consumer should approach these examples: each one is independent, all snippets target the public API only, and every example has a single observable effect listed in its chunk. If there is exactly one `[CreateAssetMenu]` and one `[MenuItem]`-tagged entry point, mention them by name as the recommended starting points.
+- `{{samplesNote}}` — if the package declares any Unity `Samples~/` entries (`samples[]` in `package.json` or the config asset is non-empty), render a one-line paragraph: ``This package also ships Unity samples importable from Package Manager → <displayName> → Samples → `<sample1.displayName>`, `<sample2.displayName>`. Those samples are not duplicated here — import them via Package Manager if you want the full asset content.`` Otherwise omit the paragraph entirely (the placeholder expands to an empty line).
+- `{{notesList}}` — conventions worth knowing at the index level. If none, write `None.`.
+
+Type links in the index use the bare `crossRefMap` value (depth 0).
+
+Write `Documentation~/examples.md`.
+
+#### Render the per-entry-point chunks — `Documentation~/examples/<slug>.md`
+
+For each entry point from Step 3.5, read `${SKILL_DIR}/assets/examples-chunk.md.template` and fill it. The chunk path is `Documentation~/examples/<slug>.md` (flat single level).
 
-Read `${SKILL_DIR}/assets/samples.md.template`. Fill placeholders:
+Placeholders:
 
-- `{{sampleTree}}` — ASCII tree of the discovered sample dir(s), one line per file.
-- `{{sampleMappingSections}}` — One `### path` subsection per sample file, following the structure documented in the template's HTML comment. For scripts, list referenced package types as links resolved through `crossRefMap` (Step 3.5). For scenes/prefabs, list resolved script GUIDs as links resolved through `crossRefMap`.
-- `{{reproductionProse}}` — One paragraph explaining how a downstream user reproduces the sample setup from scratch.
-- `{{reproductionSnippet}}` — Paste-ready `csharp` snippet using only public API documented in api.md (or its chunks). If the sample is empty, omit the snippet section entirely and write a stub (see edge cases).
-- `{{notesList}}` — Any sample-only conventions worth knowing.
+- `{{displayName}}` — package display name.
+- `{{exampleTitle}}` — the human-readable title:
+  - `create-asset`: `Create a <TypeName>` (e.g. `Create a PackageManifestConfig`).
+  - `menu-item`: derive from the last menu-path segment, Title-Cased (e.g. `Init Package`, `Prepare DLLs`).
+  - `static-method`: `<TypeName>.<MethodName>` (e.g. `CIUtils.Generate`).
+- `{{exampleKind}}` — `create-asset` | `menu-item` | `static-method`.
+- `{{entryPointLink}}` — link into `api.md` for the target type or member, via the depth-prefixed `crossRefMap` value (depth 1, prepend `../`). For `create-asset` and `static-method`, target the **type** anchor. For `menu-item`, target the type that declares the method (the method itself doesn't get its own anchor in `api.md`, but its `Line` shows up in the type's Members table).
+- `{{sourceRef}}` — `**Declared at:** \`path:line\`` pointing at the underlying member (for menu-item) or type (for create-asset / static-method). For menu-item, also include the menu path: `**Menu path:** \`Tools/PackageTools/Init Package\``. For create-asset, include the `menuName` argument from the attribute: `**Create menu:** \`Assets > Create > <menuName>\``.
+- `{{exampleProse}}` — 1-3 short sentences: what this entry point does, what observable effect to expect, and (where relevant) which other public types it commonly composes with. Avoid restating what's in `api.md`; the link covers that. The reader should come away knowing **when** to call this entry point and **why**.
+- `{{exampleSnippet}}` — a fenced code block (`csharp` for create-asset and static-method; `csharp` or `bash` for menu-item depending on context — see below). ≤ ~20 lines. Uses **only** public API from the package and Unity. Paste-ready: complete `using` directives at the top if the snippet would not compile without them, no `// ...` elisions.
+  - `create-asset`: snippet shows the API call (`ScriptableObject.CreateInstance<T>()` + minimal field setup + `AssetDatabase.CreateAsset(...)`) as the programmatic equivalent of the menu entry. Prefer this over describing the menu click — agents need code.
+  - `menu-item`: when the menu does work the consumer might also want to script (e.g. CI/CLI), emit a `csharp` snippet calling the same method directly. When the menu is GUI-only (opens a window, runs an editor flow that requires user input), emit a `bash` snippet showing how to invoke it via Unity batch mode (`Unity -batchmode -quit -executeMethod <TypeName>.<MethodName> ...`) and a 1-line note `// Or interactively: <Menu path>`.
+  - `static-method`: snippet shows a direct call to the method with believable arguments, plus the surrounding setup needed to make the call compile.
+- `{{observableEffectList}}` — bulleted list of what the consumer will see/find after running the snippet (`- <project>/Assets/.../Foo.asset is created`, `- A new package skeleton appears at <packageDestinationPath>/<packageName>/`, `- The console prints \`[Package Tools]\` Done. lines`, etc.). 1-4 bullets.
 
-**Resolving `[Type](…)` links.** Same rule as Step 5: look up every type link in `crossRefMap`. From chunked output, prepend `../` (chunks live under `samples/`); from the index-level `samples.md`, emit the bare value.
+Type links inside chunk files use the **depth-prefixed** `crossRefMap` value per Step 5's rule (i.e. `../api.md#foo` for the single-file api branch, or `../api/PackageTool.Tools.md#foo` for the chunked branch).
 
-**Edge case — empty sample:** if no sample files exist (the dir is empty or absent), emit a single-file `Documentation~/samples.md` with the `<!-- generated -->` marker, the H1, and a single section: `## No sample content` containing one sentence: `No sample content present. Add files under \`<expected sample path>\` and re-run this skill.`. Do not fail and do not chunk.
+#### Stale chunks
 
-**Output (single-file branch, default):** if Step 3.5 decided samples is single-file, write the rendered draft to `Documentation~/samples.md` as-is.
+Before writing, list `Documentation~/examples/*.md` (flat, no recursion — examples chunks live one level deep). For each existing `.md` file that starts with the generator marker and is **not** in the current chunk set, delete it and print `Removed stale: <path>`. Files without the marker are left in place and a warning is printed; same rule as elsewhere — never silently destroy hand-edited content. Hand-authored chunks the maintainer added (without the marker) are preserved across re-runs and remain linked from the index only if they're explicitly added to `{{contentsTableRows}}` by hand — the auto-generator does not enumerate non-marker files.
 
-**Output (chunked branch):** if Step 3.5 decided samples is chunked, group sample files by their **top-level sample folder** (the first path segment under the sample root, e.g. `Assets/Example/Sample/Foo.cs` → folder `Sample`) and emit:
+#### Edge case — no entry points
 
-1. **One chunk per top-level sample folder** at `Documentation~/samples/<SampleFolderName>.md` (sanitized to `[A-Za-z0-9._-]`). Each chunk contains the generator marker on line 1, H1 `# {{displayName}} — Samples: <SampleFolderName>`, the per-sample `### path` subsections that belong to that folder, the per-folder `## Reproducing the Sample` prose + snippet, and `## Notes`. Inside chunks, `crossRefMap` link values are prefixed with `../`.
-2. **One index** at `Documentation~/samples.md` containing the generator marker, H1, the global `## Sample Layout` tree, a `## Contents` Markdown table (`| Sample | Description |`) linking each chunk, and `## Notes`: `Samples are split by sample folder; see files under \`samples/\`.`
-3. **Stale chunks:** before writing, list `Documentation~/samples/*.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>`.
+If the API surface yields zero entry points across rules 1-3 (rare; would mean no `[CreateAssetMenu]`, no `[MenuItem]`, and no public-static-method on a public type), emit only the index `Documentation~/examples.md` with the generator marker, the H1, the `{{samplesNote}}` line if applicable, and a single section `## No public entry points detected` containing one sentence: ``This package exposes no `[CreateAssetMenu]`, `[MenuItem]`, or public static entry-point methods. Hand-author example chunks under `Documentation~/examples/` describing how a downstream consumer should compose the public types in `api.md`.`` Do not create the `Documentation~/examples/` directory in this case.
 
 ### Step 7 — Render `README.md`
 
@@ -285,6 +337,7 @@ Read `${SKILL_DIR}/assets/README.md.template`. Fill placeholders:
   2. Else the first class with a `[MenuItem]` method → describe the menu path.
   3. Else the first public static method on a public type → describe a direct call.
 - `{{gettingStartedSnippet}}` — minimal `csharp` snippet exercising the primary entry point.
+- `{{unitySamplesBullets}}` — if `samples[]` (from Step 2 metadata) is non-empty, render one bullet per declared Unity sample: ``- **<displayName>** — <description>. Import via Package Manager → <package displayName> → Samples → Import.`` If `samples[]` is empty or absent, replace the entire `## Unity Samples` section's content (including the placeholder line) with the single line `None — this package does not ship importable samples.` Use the README template's `{{unitySamplesSection}}` block guard if you prefer; the goal either way is a stable, predictable shape.
 - `{{licensePath}}` — path to the root `LICENSE` file (typically `LICENSE`).
 
 Write `README.md` at the repo root.
@@ -293,10 +346,11 @@ Write `README.md` at the repo root.
 
 After all files (including any chunks) are written:
 
-1. Grep `README.md` for `Documentation~/manual.md`, `Documentation~/api.md`, `Documentation~/samples.md`. Confirm each file exists. Abort with a clear error if any link is broken. (These three top-level paths are unchanged whether the file is single or chunked — when chunked the file is a Contents-table index, but the path still resolves.)
-2. Walk every emitted `.md` under `Documentation~/` (index files and chunk files). For each `[Type](…)` link extract the destination path (relative to the link's own file) and anchor. Resolve the destination to an absolute path under `Documentation~/`; confirm the file exists and contains an `### {anchor}` heading (case-insensitive, hyphen-normalized per Markdown's auto-slug rule). Print warnings (not errors) for any broken anchors. Replaces the legacy "grep `api.md#`" check, which is no longer sufficient because anchors now live in either `api.md` or `api/<Namespace>.md`.
-3. Confirm every generated file — including every chunk under `Documentation~/api/`, `Documentation~/manual/`, `Documentation~/samples/` — starts with the generator marker on line 1.
+1. Grep `README.md` for `Documentation~/manual.md`, `Documentation~/api.md`, `Documentation~/examples.md`. Confirm each file exists. Abort with a clear error if any link is broken. (These three top-level paths are unchanged whether the file is single or chunked — when chunked the file is a Contents-table index, but the path still resolves.)
+2. Walk every emitted `.md` under `Documentation~/` (index files and chunk files: `api/<Namespace>.md`, `manual/<slug>.md`, `examples/<slug>.md`). For each `[Type](…)` link extract the destination path (relative to the link's own file) and anchor. Resolve the destination to an absolute path under `Documentation~/`; confirm the file exists and contains an `### {anchor}` heading (case-insensitive, hyphen-normalized per Markdown's auto-slug rule). Print warnings (not errors) for any broken anchors.
+3. Confirm every generated file — including every chunk under `Documentation~/api/`, `Documentation~/manual/`, and `Documentation~/examples/` — starts with the generator marker on line 1.
 4. Confirm no chunk file outside the current chunk set survived (the stale-removal in Steps 4/5/6 should have deleted them; this is a safety re-check).
+5. For each chunk in `Documentation~/examples/`, confirm the example snippet block (` ```csharp ` or ` ```bash `) is present and non-empty. This catches the regression where a chunk would be written without its snippet body.
 
 Print a summary: which files were created vs updated, which were skipped (and why), and which chunks were removed as stale.
 
@@ -312,11 +366,12 @@ For each output file:
 
 ### Stale chunks
 
-Chunk files (under `Documentation~/api/`, `Documentation~/manual/`, `Documentation~/samples/`) follow the same marker-on-line-1 contract as top-level generated files. Additionally:
+Chunk files (under `Documentation~/api/`, `Documentation~/manual/`, `Documentation~/examples/`) follow the same marker-on-line-1 contract as top-level generated files. Additionally:
 
-4. **Stale removal (marker-gated).** Before writing the chunk set for an area, list every `.md` file in that area's chunk directory. 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>`. Files without the marker are left in place and a warning is printed (matches rule 3 — never silently destroy hand-edited content).
-5. **Mode flip (single ↔ chunked).** When a Documentation~ file flips from chunked to single-file between runs (e.g. the user removes namespaces until the threshold is no longer exceeded), every file in that area's chunk directory is treated as stale by rule 4: marker-bearing chunks are deleted, marker-absent files are warned about. The chunk directory itself is left in place even when empty (Unity treats empty directories as no-ops; do not `rmdir`).
-6. **Force.** `force=true` extends rules 3 and 4 — marker-absent files are overwritten (rule 3) and marker-absent chunks are also deleted when stale (rule 4 extension), matching the existing semantics for top-level files.
+4. **Stale removal (marker-gated).** Before writing the chunk set for an area, list every `.md` file in that area's chunk directory (flat — all three chunk dirs are single-level). 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>`. Files without the marker are left in place and a warning is printed (matches rule 3 — never silently destroy hand-edited content). Hand-authored example chunks (no marker) are preserved across re-runs; they show up under `examples/` but are not linked from `examples.md`'s auto-generated Contents table unless the maintainer adds the row by hand.
+5. **Mode flip (single ↔ chunked).** Applies to `api.md` and `manual.md` only — `examples.md` is always chunked and never flips. When `api.md` or `manual.md` flips from chunked to single-file between runs (e.g. the user removes namespaces until the threshold is no longer exceeded), every file in that area's chunk directory is treated as stale by rule 4: marker-bearing chunks are deleted, marker-absent files are warned about. The chunk directory itself is left in place even when empty (Unity treats empty directories as no-ops; do not `rmdir` api/manual dirs).
+6. **Migration from the legacy samples layout.** If `Documentation~/samples.md` or any path under `Documentation~/samples/` exists at the start of a run, delete every marker-bearing file in that tree and print `Removed legacy: <path>`. After deletion, `rmdir` any emptied directories under `Documentation~/samples/` and then the dir itself if empty. Files without the marker (i.e. hand-authored content the maintainer placed under `Documentation~/samples/`) are left alone and a warning is printed; the maintainer can move them under `Documentation~/examples/` manually. This migration runs once-per-repo — once the legacy paths are gone, subsequent runs see nothing to delete.
+7. **Force.** `force=true` extends rules 3 and 4 — marker-absent files are overwritten (rule 3) and marker-absent chunks are also deleted when stale (rule 4 extension), matching the existing semantics for top-level files.
 
 The pipeline as a whole is idempotent: re-running on an unchanged repo produces a no-op diff.
 

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

@@ -0,0 +1,40 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# {{displayName}} — Example: {{exampleTitle}}
+
+**Kind:** {{exampleKind}}
+
+**Entry point:** {{entryPointLink}}
+
+{{sourceRef}}
+
+## What it does
+
+{{exampleProse}}
+
+## Snippet
+
+{{exampleSnippet}}
+
+## Observable effect
+
+{{observableEffectList}}
+
+<!--
+Slug rule (Step 3.5):
+  create-asset   → create-<TypeName-lower>          e.g. create-packagemanifestconfig
+  menu-item      → <last-menu-path-segment-slug>    e.g. init-package
+  static-method  → <TypeName-lower>-<MethodName-lower>  e.g. ciutils-generate
+
+Snippet rule (Step 6 chunk section):
+  create-asset   → ```csharp ... ScriptableObject.CreateInstance<T>() + AssetDatabase.CreateAsset(...) ...
+  menu-item      → ```csharp direct call if the method is callable from code,
+                   else ```bash with `Unity -batchmode -quit -executeMethod ...`.
+                   Add a one-line `// Or interactively: <Menu path>` comment in either case.
+  static-method  → ```csharp direct call with believable arguments + minimal compile-ready surroundings.
+
+≤ ~20 lines. No `// ...` elisions. `using` directives included when the snippet would not compile without them.
+
+Hand-edit this chunk freely — it has the generator marker, so a re-run will overwrite it.
+To preserve manual edits, delete the marker on line 1 (the regen will then skip-with-warning and your version stays).
+-->

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

@@ -0,0 +1,36 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# {{displayName}} — Examples
+
+Short, focused usage examples that exercise this package's public API. Each example is independent and links into the API reference (`api.md`) for the type or member it calls. Snippets are paste-ready and use only public API — copy one into a fresh project to reach the same observable effect.
+
+## Quick start
+
+{{quickStartProse}}
+
+## Contents
+
+| Example | Kind | Entry point |
+|---------|------|-------------|
+{{contentsTableRows}}
+
+<!--
+One row per chunk under Documentation~/examples/<slug>.md.
+Row format:
+| [<title>](examples/<slug>.md) | create-asset | menu-item | static-method | [<TypeName>](crossRefMap[TypeName]) |
+
+`<entry-point>` column links into api.md (depth 0, bare crossRefMap value).
+For menu-item, the entry-point link targets the **type** that declares the
+method (the method itself is shown in that type's Members table at the
+referenced line).
+
+Hand-authored chunks (no generator marker) are preserved across regens but
+do NOT appear in this auto-generated table — add their rows by hand if you
+want them indexed.
+-->
+
+{{samplesNote}}
+
+## Notes
+
+{{notesList}}

package/Samples~/ClaudeSkills/unity-package-docs/scripts/scan_package.py

@@ -112,7 +112,7 @@ def normalize(src: str) -> str:
 NAMESPACE_RE = re.compile(r"^\s*namespace\s+(?P<name>[\w.]+)\s*[{;]?\s*$")
 
 TYPE_DECL_RE = re.compile(
-    r"^\s*(?P<mods>(?:(?:public|internal|private|protected|sealed|static|abstract|partial|new|unsafe)\s+)*)"
+    r"^\s*(?P<mods>(?:(?:public|internal|private|protected|sealed|static|abstract|partial|new|unsafe|readonly|ref)\s+)*)"
     r"(?P<kind>class|struct|interface|enum)\s+"
     r"(?P<name>[A-Za-z_]\w*)"
     r"(?P<generic><[^>]*>)?"
@@ -128,7 +128,11 @@ METHOD_RE = re.compile(
     r"(?P<generic><[^>]*>)?\s*"
     r"\((?P<params>[^)]*)\)\s*"
     r"(?:where\s+[^{;=]+)?"
-    r"\s*(?:[{;=]|=>)?\s*$"
+    # Accept any of: nothing (open brace on next line), `;` (declaration only / abstract),
+    # `{ … }` (single-line body), or `=> …;` (expression-bodied method, possibly with the
+    # whole right-hand side on the same line). Without `=>.*`, the regex misses
+    # `internal static void X() => Y();`-style declarations.
+    r"\s*(?:\{.*|;|=>.*)?\s*$"
 )
 
 PROPERTY_RE = re.compile(

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

@@ -1,6 +1,6 @@
 ---
 name: unity-package-release
-description: Cut a release commit for any Unity package that uses the `com.elestrago.unity.package-tools` editor tool (the one that drives a `PackageManifestConfig` ScriptableObject and exports via the **Export Package Source** Inspector button). Discovers the config asset, package name, changelog filename, README install snippet, and publish flow at runtime via `scripts/discover_package.py`, so the same skill works in every package-tool consumer regardless of layout. Bumps the SO's `packageVersion`, updates the consumer-install version line in the project-root README (if one exists), prepends or appends an entry to the changelog (whatever filename the config's `changelogPath` resolves to), prompts the maintainer to run **Export Package Source** in Unity so the exported `Assets/Package/<X>/` artifacts and `Release/package.json` regenerate, stages exactly the touched files, and proposes a `V-{version} {summary}` commit. Detects the publish flow (GitLab elestrago CI, GitLab generic, GitHub Actions, or manual) and prints the matching handoff block — the skill never tags or pushes itself. Use whenever a package-tool maintainer wants to wrap pending changes into a release — phrasings like "bump the version", "cut a release", "update changelog and commit", "ship this as 2.x.y", "make a V- commit", or after a `/unity-package-tool-developer` run finishes its code edits. Refuses to run if no `PackageManifestConfig.asset` is found under `Assets/`.
+description: Cut a release commit for any Unity package that uses the `com.elestrago.unity.package-tools` editor tool (the one that drives a `PackageManifestConfig` ScriptableObject and exports via the **Export Package Source** Inspector button). Discovers the config asset, package name, changelog filename, README install snippet, and publish flow at runtime via `scripts/discover_package.py`, so the same skill works in every package-tool consumer regardless of layout. Bumps the SO's `packageVersion`, updates the consumer-install version line in the project-root README (if one exists), prepends or appends an entry to the changelog (whatever filename the config's `changelogPath` resolves to), prompts the maintainer to run **Export Package Source** in Unity so the exported `Assets/Package/<X>/` artifacts and `Release/package.json` regenerate, stages exactly the touched files, and proposes a `V-{version} {summary}` commit. Detects the publish flow (GitLab elestrago CI, GitLab generic, GitHub Actions, or manual) and prints the matching handoff block — the skill never tags or pushes itself. Use whenever a package-tool maintainer wants to wrap pending changes into a release — both release-specific phrasings ("bump the version", "cut a release", "update changelog and commit", "ship this as 2.x.y", "make a V- commit", "release this", "finalize the changes", "publish this version") and generic commit phrasings ("commit all changes", "commit changes", "commit this", "let's commit", "make a commit", "create a commit", "stage and commit", "wrap this up"), and also after a `/unity-package-tool-developer` run finishes its code edits. In a package-tool repo, treat any plain "commit" request as a release-commit request — these repos do not have non-release commits, every shipped commit is a `V-{version}` release commit, so a bare "commit" phrasing from the maintainer is the cue to run the full version-bump → changelog → Export Package Source → commit flow rather than a raw `git commit`. Refuses to run if no `PackageManifestConfig.asset` is found under `Assets/`.
 ---
 
 # unity-package-release

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "com.elestrago.unity.package-tools",
-  "version": "2.4.0",
+  "version": "2.5.2",
   "displayName": "Package Tool",
   "description": "Tool for create unity packages",
   "category": "unity",
   "unity": "2021.3",
   "homepage": "https://gitlab.com/elestrago-pkg/package-tool",
-  "documentationUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.4.0/README.md",
-  "changelogUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.4.0/CHANGELOG.md",
-  "licensesUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.4.0/LICENSE",
+  "documentationUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.5.2/README.md",
+  "changelogUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.5.2/CHANGELOG.md",
+  "licensesUrl": "https://gitlab.com/elestrago-pkg/package-tool/-/blob/2.5.2/LICENSE",
   "license": "MIT",
   "keywords": [
     "unity",

package/Documentation~/samples.md

@@ -1,107 +0,0 @@
-<!-- generated by unity-package-docs; safe to regenerate -->
-
-# Package Tool — Samples
-
-How the sample content in this repository uses the package. Each entry maps a sample file to the package types it exercises, so a reader can recreate the same setup against the public API.
-
-## Sample Layout
-
-```
-Assets/Example/Sample
-├── 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 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
-
-### `Assets/Example/Sample/Prefabs/ExamplePrefab.prefab`
-
-Kind: prefab
-
-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/Example/Sample/Scene/SampleScene.unity`
-
-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
-
-**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#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}`.
-
-**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;
-using PackageTool.Tools;
-using UnityEditor;
-using UnityEngine;
-
-var config = ScriptableObject.CreateInstance<PackageManifestConfig>();
-config.packageName = "com.example.sample";
-config.displayName = "Example Sample Package";
-config.packageVersion = "1.0.0";
-config.unityVersion = "2021.3";
-config.sourcePath = "Assets/Example/Source";
-config.packageDestinationPath = "Release";
-config.samples = new[]
-{
-    new PackageManifestConfig.Sample
-    {
-        sourcePath = "Assets/Example/Sample",
-        displayName = "Example Sample",
-        folderName = "ExampleSample",
-        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);
-```
-
-## Notes
-
-- 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/Samples~/ClaudeSkills/unity-package-docs/assets/samples.md.template

@@ -1,56 +0,0 @@
-<!-- generated by unity-package-docs; safe to regenerate -->
-
-# {{displayName}} — Samples
-
-How the sample content in this repository uses the package. Each entry maps a sample file to the package types it exercises, so a reader can recreate the same setup against the public API.
-
-## Sample Layout
-
-```
-{{sampleTree}}
-```
-
-## Sample → Package Type Mapping
-
-{{sampleMappingSections}}
-
-<!--
-Each sample entry follows this exact shape:
-
-### `{sample file path}`
-
-Kind: script | scene | prefab
-
-Package types referenced:
-
-- [`{TypeName}`]({crossRefMap[TypeName]}) — `{package source path}:{line}`
-
-For scenes/prefabs, list each MonoBehaviour script resolved via m_Script.guid:
-
-- GameObject `{name}` uses [`{TypeName}`]({crossRefMap[TypeName]}) — `{package source path}`
-
-Type links resolve through crossRefMap (Step 3.5), NOT a hard-coded
-api.md anchor — the destination may be api.md#foo (api single-file) or
-api/PackageTool.Tools.md#foo (api chunked).
-
-Omit "Package types referenced" if the file references none from this package.
-
-Chunking note (Step 6 chunked branch): when this file is split, entries
-are grouped by top-level sample folder into Documentation~/samples/<SampleFolderName>.md
-(filename sanitized to [A-Za-z0-9._-], non-matching chars replaced with `-`).
-Each chunk carries its own `## Reproducing the Sample` and `## Notes`
-sections. Inside chunk files, every `[Type](…)` link prepends `../` to
-the crossRefMap value.
--->
-
-## Reproducing the Sample
-
-{{reproductionProse}}
-
-```csharp
-{{reproductionSnippet}}
-```
-
-## Notes
-
-{{notesList}}