com.elestrago.unity.package-tools 2.0.11 → 2.1.0

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

@@ -0,0 +1,309 @@
+---
+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).
+---
+
+# unity-package-docs
+
+Generate a strict, AI-first documentation set for a Unity package at the **repository root** (cwd). The output is consumed primarily by AI agents (Claude, Copilot, Cursor) and secondarily by humans.
+
+## Output contract (strict)
+
+Files created/updated at the repository root — **never** inside the package folder:
+
+```
+<repo-root>/
+├── README.md
+└── Documentation~/
+    ├── manual.md
+    ├── api.md
+    └── samples.md
+```
+
+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.
+
+Every generated `.md` file begins with this exact marker on line 1:
+
+```
+<!-- generated by unity-package-docs; safe to regenerate -->
+```
+
+## AI-first content rules (non-negotiable, apply to every generated file)
+
+1. **Dense over decorative.** No emojis. No marketing prose. No horizontal rules (`---`) used as visual separators. Use heading hierarchy (H1 → H2 → H3) semantically, never as styling.
+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.
+
+## Skill args
+
+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.
+
+## Pipeline (execute these steps in order)
+
+### Step 1 — Locate the package
+
+From cwd, find `package.json` files via:
+
+```bash
+find . -type f -name package.json \
+  -not -path './Library/*' \
+  -not -path './Temp/*' \
+  -not -path './Logs/*' \
+  -not -path './obj/*' \
+  -not -path './Build/*' \
+  -not -path './Builds/*' \
+  -not -path './Packages/manifest.json' \
+  -not -path './Packages/packages-lock.json'
+```
+
+- **Exactly one match** → that file is the package manifest. Its containing directory is the **package root**. Read it.
+- **Zero matches but `Assets/**/PackageManifestConfig.asset` exists** (package-tool projects pre-first-export) → use the config asset as the metadata source. The `sourcePath` field is the package root. Note in `manual.md` that the `package.json` is generated to `<packageDestinationPath>/` on export.
+- **More than one match, or zero matches with no config** → abort. Print the matches found and ask the user to disambiguate via `package=<path>`.
+
+### Step 2 — Read metadata
+
+From `package.json` (preferred) or `PackageManifestConfig.asset`, extract:
+
+| Field | `package.json` key | Config key |
+|-------|-------------------|------------|
+| Package name | `name` | `packageName` |
+| Display name | `displayName` | `displayName` |
+| Version | `version` | `packageVersion` |
+| Description | `description` | `description` |
+| Unity version | `unity` | `unityVersion` |
+| Author | `author` | `author.name` |
+| Dependencies | `dependencies` (object) | `dependencies` (array of `{packageName, packageVersion}`) |
+| Keywords | `keywords` | `keywords` |
+| 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.
+
+### Step 3 — Scan source
+
+Run the bundled Python scanner. Its absolute path is `${SKILL_DIR}/scripts/scan_package.py` where `${SKILL_DIR}` is the directory containing this SKILL.md. Resolve it relative to where this skill is installed; do not hardcode.
+
+```bash
+python3 "${SKILL_DIR}/scripts/scan_package.py" \
+  --package "<package-root>" \
+  --samples "<sample-dir-1>" --samples "<sample-dir-2>" \
+  --repo-root .
+```
+
+The scanner emits JSON to stdout with this shape:
+
+```json
+{
+  "packageDir": "Assets/Package/PackageTool",
+  "asmdefs": [{"path": "...", "name": "...", "rootNamespace": "...", "includePlatforms": [...], "excludePlatforms": [...], "references": [...], "precompiledReferences": [...], "defineConstraints": [...], "autoReferenced": true}],
+  "namespaces": ["PackageTool", "PackageTool.Tools", ...],
+  "types": [
+    {
+      "file": "Assets/.../Foo.cs",
+      "line": 37,
+      "namespace": "PackageTool",
+      "name": "Foo",
+      "kind": "class|struct|interface|enum",
+      "modifiers": ["public", "sealed"],
+      "baseList": ["ScriptableObject"],
+      "attributes": ["CreateAssetMenu(...)", "Serializable"],
+      "summary": "...",
+      "containingType": null,
+      "members": [
+        {"line": 88, "kind": "method|property|field", "name": "Bar", "signature": "public string Bar()", "summary": "...", "attributes": ["MenuItem(\"Tools/...\")"]}
+      ]
+    }
+  ],
+  "samples": [
+    {"path": "Assets/.../Foo.cs", "kind": "script", "namespace": "...", "packageTypesReferenced": ["Foo", "Bar"]},
+    {"path": "Assets/.../Scene.unity", "kind": "scene|prefab", "scriptsReferenced": [{"guid": "...", "resolvedTo": "Assets/.../Foo.cs"}]}
+  ]
+}
+```
+
+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:
+
+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).
+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).
+
+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.
+
+Build a **`crossRefMap`**: `{ typeAnchor → "<destination-relative-to-Documentation~>#<anchor>" }`, populated during the api decision:
+
+- When api is single-file: every entry is `api.md#<anchor>` (identity with the legacy shape).
+- When api is chunked: each entry is `api/<Namespace>.md#<anchor>`, where `<Namespace>` is the namespace that contains the type (from `types[i].namespace`). Nested types use `containingType`'s namespace.
+
+`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)`.
+
+### 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.
+
+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.
+
+For each type entry:
+
+- Heading: `### {TypeName}` (stable; the anchor is `{typename-lowercase}` by default Markdown rules; for nested types use `### {ContainingType}.{TypeName}`).
+- ` ```csharp ` block with the declaration line copied verbatim from source (use the file + line in the manifest to extract the line; do not paraphrase).
+- `**Source:** ` + `path:line`.
+- `**Attributes:** ` + comma-separated list (omit the line if none).
+- `**Base:** ` + comma-separated `baseList` (omit if empty).
+- Summary verbatim if present.
+- Members table: only include public/internal/protected members; omit private. Strip XML tags from member summaries.
+
+Omit types with no public members and no XML summary unless they carry a Unity attribute (`[MenuItem]`, `[CustomEditor]`, etc.). Omit empty namespaces entirely.
+
+**Output (single-file branch, default):** if Step 3.5 decided api is single-file, write the rendered draft to `Documentation~/api.md` as-is.
+
+**Output (chunked branch):** if Step 3.5 decided api is chunked, split the draft by namespace and emit:
+
+1. **One chunk per namespace** at `Documentation~/api/<Namespace>.md` using `${SKILL_DIR}/assets/api-chunk.md.template`. Each chunk contains the H1 (`# {{displayName}} — API Reference: \`{{namespace}}\``), the namespace's section body (same `### TypeName` blocks as the single-file form), and the generator marker on line 1. Anchors inside the chunk stay `{typename-lowercase}` — they do NOT include the namespace prefix, because cross-doc links resolve via `crossRefMap` (which carries the path-plus-anchor pair).
+2. **One index** at `Documentation~/api.md` using `${SKILL_DIR}/assets/api-index.md.template`. The index keeps the generator marker, H1, a `## Contents` Markdown table linking each chunk (`| Namespace | Description |`), and a one-line `## Notes` paragraph: `This API reference is split by namespace; see files under \`api/\`.`. The one-line description per namespace is the same blurb you would have placed in the single-file `{{namespaceContentsList}}`.
+3. **Stale chunks:** before writing, list `Documentation~/api/*.md`. For each existing file that starts with the generator marker and is NOT in the current chunk set, delete it and print `Removed stale: <path>`. (See Idempotency.)
+
+### Step 5 — Render `Documentation~/manual.md`
+
+Read `${SKILL_DIR}/assets/manual.md.template`. Fill each placeholder:
+
+- `{{overviewProse}}` — 2–4 dense paragraphs synthesizing what the package does. Read `description` plus the XML summaries of the top 3–5 most-referenced types (highest member counts or carrying Unity attributes).
+- `{{namespaceTree}}` — Plain ASCII tree of namespaces, sorted, with no decoration.
+- `{{architectureProse}}` — One short paragraph per top-level namespace explaining its responsibility. Reference at least one representative file path per namespace.
+- `{{assembliesTableRows}}` — One Markdown table row per `.asmdef` (name, root namespace or `—`, platforms joined with `,` or `Any`, references joined with `,` or `—`).
+- `{{entryPointsList}}` — Bulleted list. One bullet per `[MenuItem]` (show menu path), one per `[CreateAssetMenu]` (show `menuName`), one per public static method on a public static class (CI/CLI candidates). Each bullet ends with `— path:line`. Include the type's XML summary if non-empty.
+- `{{dataModelList}}` — Bulleted list of every type with base `ScriptableObject` and every type with `[Serializable]`. For each, list its public fields as a sub-bulleted list with their types.
+- `{{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.
+
+**Output (single-file branch, default):** if Step 3.5 decided manual is single-file, write the rendered draft to `Documentation~/manual.md` as-is.
+
+**Output (chunked branch):** if Step 3.5 decided manual is chunked, split the draft along its H2 boundaries and emit:
+
+1. **One chunk per non-empty H2 section** at `Documentation~/manual/<slug>.md`, using the fixed slug set from Step 3.5 (`overview.md`, `architecture.md`, `assemblies.md`, `entry-points.md`, `data-model.md`, `editor-ui.md`, `extension-points.md`). Each chunk contains the generator marker on line 1, an H1 echoing the section title (`# {{displayName}} — Manual: <Section Title>`), then the section body (everything that was below the H2 in the single-file draft, with the H2 line itself dropped). Within a chunk, all `[Type](…)` link values from `crossRefMap` are prefixed with `../`.
+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`
+
+Read `${SKILL_DIR}/assets/samples.md.template`. Fill 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.
+
+**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.
+
+**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.
+
+**Output (single-file branch, default):** if Step 3.5 decided samples is single-file, write the rendered draft to `Documentation~/samples.md` as-is.
+
+**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:
+
+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>`.
+
+### Step 7 — Render `README.md`
+
+Read `${SKILL_DIR}/assets/README.md.template`. Fill placeholders:
+
+- `{{displayName}}`, `{{description}}` — from metadata.
+- `{{platformConstraintsBullets}}` — bullet per `.asmdef` with a non-empty `includePlatforms` or `excludePlatforms`. Omit the whole line if all asmdefs allow all platforms.
+- `{{dependenciesTable}}` — Markdown table (`| Package | Version |`) of dependencies. If none, write `None.`.
+- `{{installManifestSnippet}}` — JSON snippet showing the `manifest.json` edit. Include `scopedRegistries` with the URL from `publishConfig.registry` only if present in `package.json`; otherwise omit and add a one-line note in `{{scopedRegistryNote}}` reading `Replace the registry URL above with your scoped registry, or remove the scopedRegistries block when consuming a published package.` (when present, the note is empty).
+- `{{gettingStartedProse}}` — one paragraph. Identify the primary entry point:
+  1. The first type with `[CreateAssetMenu]` → describe `Assets > Create > <menuName>`.
+  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.
+- `{{licensePath}}` — path to the root `LICENSE` file (typically `LICENSE`).
+
+Write `README.md` at the repo root.
+
+### Step 8 — Verify
+
+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.
+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).
+
+Print a summary: which files were created vs updated, which were skipped (and why), and which chunks were removed as stale.
+
+## Idempotency
+
+For each output file:
+
+1. If the file does not exist → write it.
+2. If the file exists and starts with the generator marker → overwrite it.
+3. If the file exists and does NOT start with the marker → **do not overwrite** unless `force=true` was passed. Print: `Skipped <path>: marker absent (file is hand-edited or pre-existing). Re-run with force=true to overwrite.`
+
+`Documentation~/` pre-existing assets (PNG, JPG, etc.) are never touched regardless of `force`.
+
+### 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:
+
+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.
+
+The pipeline as a whole is idempotent: re-running on an unchanged repo produces a no-op diff.
+
+## Examples of correct output style
+
+Good (rule 3 — explicit paths):
+
+> The CI entry point is `CIUtils.Generate` at `Assets/Package/PackageTool/Editor/CIUtils.cs:65`. It is invoked in batch mode and reads command-line keys parsed by `CommandLineTools.GetKVPCommandLineArguments` at `Assets/Package/PackageTool/Editor/Tools/CommandLineTools.cs:43`.
+
+Bad (rule 3 violation):
+
+> The CI entry point is `CIUtils.Generate`. It reads command-line keys from a helper.
+
+Good (rule 4 — tagged, complete code blocks):
+
+````
+```csharp
+var config = ScriptableObject.CreateInstance<PackageManifestConfig>();
+config.packageName = "com.example.foo";
+FileTools.CreateOrUpdatePackageSource(config);
+```
+````
+
+Bad (rule 4 violation):
+
+````
+```
+var config = ...
+// ... fill in fields ...
+FileTools.CreateOrUpdatePackageSource(config);
+```
+````

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

@@ -0,0 +1,42 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# {{displayName}}
+
+{{description}}
+
+## Requirements
+
+- Unity {{unityVersion}} or newer.
+{{platformConstraintsBullets}}
+
+## Dependencies
+
+{{dependenciesTable}}
+
+## Installation
+
+Add the package to `Packages/manifest.json`:
+
+```json
+{{installManifestSnippet}}
+```
+
+{{scopedRegistryNote}}
+
+## Getting Started
+
+{{gettingStartedProse}}
+
+```csharp
+{{gettingStartedSnippet}}
+```
+
+## Documentation
+
+- [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.
+
+## License
+
+See [{{licensePath}}]({{licensePath}}).

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

@@ -0,0 +1,41 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# {{displayName}} — API Reference: `{{namespace}}`
+
+{{typeSections}}
+
+<!--
+Used only when api.md is chunked (Step 4 chunked branch).
+{{namespace}} is the literal namespace, matching the chunk filename
+(Documentation~/api/<Namespace>.md).
+
+{{typeSections}} is one section per type in this namespace, identical
+in shape to a per-type block in the single-file api.md template:
+
+### {TypeName}
+
+```csharp
+{declaration line copied verbatim from source}
+```
+
+**Source:** `{file}:{line}`
+**Attributes:** `[Attr1]`, `[Attr2]` (omit line if none)
+**Base:** `{baseList}` (omit if empty)
+
+{summary}
+
+**Members:**
+
+| Kind | Name | Signature | Summary |
+|------|------|-----------|---------|
+| method | Foo | `public void Foo()` | … |
+
+Anchors are `{typename-lowercase}` (no namespace prefix). Cross-doc links
+from manual.md / samples.md resolve via crossRefMap, which carries the
+chunk-relative path-plus-anchor pair (e.g. `api/PackageTool.Tools.md#filetools`).
+For nested types use `### {ContainingType}.{TypeName}` and anchor
+`{containingtype}.{typename}`.
+
+Omit types with no public members and no XML summary unless they carry a
+Unity attribute (`[MenuItem]`, `[CustomEditor]`, etc.).
+-->

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

@@ -0,0 +1,26 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# {{displayName}} — API Reference
+
+This API reference is split by namespace because the rendered single-file draft exceeded the chunk threshold (see `chunk-threshold-api` / `chunk-threshold-lines` in the unity-package-docs skill).
+
+## Contents
+
+| Namespace | Description |
+|-----------|-------------|
+{{namespaceTableRows}}
+
+## Notes
+
+This API reference is split by namespace; see files under `api/`. Cross-doc links from `manual.md` and `samples.md` point directly into the relevant chunk file (e.g. `api/PackageTool.Tools.md#filetools`); this index is intentionally thin and stable so external links to `Documentation~/api.md` keep resolving.
+
+<!--
+Used only when api.md is chunked (Step 4 chunked branch).
+
+{{namespaceTableRows}} is one Markdown table row per namespace:
+
+| [`PackageTool`](api/PackageTool.md) | Root namespace; holds the configuration ScriptableObject. |
+
+The description is the same one-line blurb that would have appeared in
+the single-file template's {{namespaceContentsList}}.
+-->

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

@@ -0,0 +1,43 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+
+# {{displayName}} — API Reference
+
+Comprehensive reference for every public/internal type and member. Generated from source; do not edit by hand.
+
+## Contents
+
+{{namespaceContentsList}}
+
+{{perNamespaceSections}}
+
+<!--
+Used only when api.md is single-file (Step 4 default branch). When chunking
+is active (Step 4 chunked branch), api.md becomes a Contents-table index
+rendered from api-index.md.template, and per-namespace bodies are emitted
+to Documentation~/api/<Namespace>.md from api-chunk.md.template.
+
+Each namespace section follows this exact shape:
+
+## `{namespace}`
+
+### {TypeName}
+
+```csharp
+{declaration line copied verbatim from source}
+```
+
+**Source:** `{file}:{line}`
+**Attributes:** `[Attr1]`, `[Attr2]` (omit line if none)
+**Base:** `{baseList}` (omit if empty)
+
+{summary}
+
+**Members:**
+
+| Kind | Name | Signature | Summary |
+|------|------|-----------|---------|
+| method | Foo | `public void Foo()` | … |
+
+Omit types with no public members and no XML summary unless they carry a Unity attribute.
+Omit empty namespaces entirely.
+-->

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

@@ -0,0 +1,57 @@
+<!-- generated by unity-package-docs; safe to regenerate -->
+<!--
+Chunking note (Step 5 chunked branch): when this file is split, each H2
+section below becomes Documentation~/manual/<slug>.md. The H2 → slug map
+is fixed:
+
+  ## Overview            → manual/overview.md
+  ## Architecture        → manual/architecture.md
+  ## Assemblies          → manual/assemblies.md
+  ## Entry Points        → manual/entry-points.md
+  ## Data Model          → manual/data-model.md
+  ## Editor UI Approach  → manual/editor-ui.md
+  ## Extension Points    → manual/extension-points.md
+
+Sections that render empty are omitted from the chunk set. Inside chunk
+files, every `[Type](…)` link prepends `../` to the crossRefMap value
+(because chunks live one directory deeper than Documentation~/).
+-->
+
+# {{displayName}} — Manual
+
+## Overview
+
+{{overviewProse}}
+
+Package name: `{{packageName}}`
+Package source: `{{packageDir}}`
+
+## Architecture
+
+```
+{{namespaceTree}}
+```
+
+{{architectureProse}}
+
+## Assemblies
+
+| Assembly | Root Namespace | Platforms | References |
+|----------|----------------|-----------|------------|
+{{assembliesTableRows}}
+
+## Entry Points
+
+{{entryPointsList}}
+
+## Data Model
+
+{{dataModelList}}
+
+## Editor UI Approach
+
+{{editorUiProse}}
+
+## Extension Points
+
+{{extensionPointsList}}

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

@@ -0,0 +1,56 @@
+<!-- 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}}