@aefree/pi-unity 0.9.0 → 0.9.2

package/skills/unity-interactive-playmode-authoring/SKILL.md

@@ -1,91 +1,91 @@
----
-name: unity-interactive-playmode-authoring
-description: Inspect and temporarily tune live Unity runtime objects through a reachable exact-copy Pipeline Editor while Play Mode remains active, then deliberately translate accepted runtime values into durable source or asset changes. Use only for explicit interactive Play Mode authoring or live visual experiments; not for ordinary compile, tests, planning, or batchmode.
----
-
-# Unity Interactive Play Mode Authoring
-
-Use this skill only when the user explicitly requests inspection or temporary mutation of live runtime state in an already-running exact Unity project copy. Typical examples include moving a runtime UI element while the user watches, tuning a value interactively, or exploring which connected Pipeline interaction mode can reach a live object.
-
-Do not activate this skill for ordinary source edits, serialized-asset authoring, planning inspection, compilation, tests, screenshots alone, or opening Unity. Use the owning Unity workflow for those operations.
-
-## Preconditions
-
-1. Resolve the exact Unity project path; never route by display name or a similarly named workspace.
-2. Call `unity_project_status` and require a verified matching Editor process, a reachable exact-copy Pipeline instance, and the advertised commands needed for the intended operation.
-3. Inspect the advertised `editor_status` and require Play Mode to be active for a live-runtime experiment. If Play Mode is not active, do not enter it unless the user explicitly requested that lifecycle change.
-4. Revalidate exact project path and Editor/Pipeline process identity before each mutation. Stop on unknown, stale, unreachable, or changed identity.
-5. Establish the target object, requested temporary effect, and expected observation before mutation. Do not explore by changing unrelated live objects.
-
-## Choose the Smallest Interaction Surface
-
-Choose the smallest route that answers the question clearly:
-
-1. **Advertised typed command.** Use a purpose-built command when its validation and result shape fit the task.
-2. **One-shot connected command or `eval`.** Use advertised `eval` as the normal REPL escape hatch for project-specific properties, APIs, and operations that registered commands did not anticipate. Prefer one bounded invocation with an explicit return value over a long-lived interactive shell.
-
-Typed commands are conveniences, not exclusive gateways. Do not force repository inference or add a new wrapper merely to avoid a direct connected property inspection.
-
-GameObject transform and component commands do not operate on every runtime object. For example, UI Toolkit `VisualElement`s are not scene GameObjects, so `set_transform` is not an appropriate route for their layout styles.
-
-`unity shell` is a human interactive convenience over the same connected Pipeline surface. It is not a stronger Editor capability and is not the preferred agent automation route.
-
-## Command Discovery
-
-- Prefer the command inventory returned by `unity_project_status`; do not fan out across CLI help, shell, and trial dispatch when availability is already known.
-- If raw `unity list` is exceptionally needed, parse the outer JSON envelope and read command records from `data.tools`, not a guessed top-level `commands` field.
-- Inspect one exact command schema before dispatch rather than repeatedly trialing argument forms against the live Editor.
-- Treat outer CLI success as transport evidence only. Parse nested `success`, diagnostics, status, and result fields before claiming success.
-
-## Bounded Eval Rules
-
-Pipeline `eval` compiles C# with Roslyn and runs it on the connected Editor's main thread. It can inspect or call any reachable engine, Editor, or project API; it is not intrinsically read-only, and a static syntax/property allowlist is not a reliable side-effect boundary.
-
-- Use one bounded, target-specific snippet with an explicit return value.
-- Regular property and state inspection is allowed when it serves the active task.
-- Resolve the exact target and check for a missing target before mutation.
-- Mutations must match the user's request. Lifecycle, destructive, persistent-setting, asset, package, selection, scene-save, import, build, test, and source-file changes require the same authorization they would through a typed command.
-- Research unfamiliar Unity/C# APIs when needed, but do not add a purpose-built wrapper solely to avoid `eval`.
-- Avoid obsolete APIs; evaluator diagnostics may treat obsolete usage as a compilation failure.
-- Fully qualify APIs when extension-method or namespace ambiguity is likely.
-- Treat any compiler diagnostic, nested failure, null target, malformed result, or identity change as failure. Do not retry mutations speculatively.
-
-Use `unity_pipeline_eval` for exact-copy connected C# queries and operations. Use `unity_pipeline_inspect` when one of its package-owned purpose-built inspection commands provides better evidence.
-
-## Live Tuning Loop
-
-For each requested adjustment:
-
-1. Revalidate the exact-copy Pipeline identity and Play Mode state.
-2. Read the current live value when needed to make the requested relative or absolute adjustment.
-3. Apply one bounded temporary mutation.
-4. Return the observed before/after values and ask for the next adjustment only when user observation is required.
-5. State that the override is non-persistent and may be replaced by rendering, rebinding, a domain reload, or Play Mode exit.
-
-Do not infer that a serialized asset or source edit updates an existing runtime instance. Confirm the relevant refresh, rebind, or reconstruction path before claiming a live result.
-
-## Persisting an Accepted Runtime Result
-
-A request to persist authorizes the durable source/asset edit, but lifecycle changes remain explicit unless already authorized.
-
-1. Capture the final runtime values and the owning coordinate space, dimensions, scale, or other context needed to convert them into authored values.
-2. Identify the authoritative source or serialized field and trace how it becomes the runtime value. Do not write a visual coordinate into a guessed representation.
-3. Determine whether persistence triggers asset import, script compilation, domain reload, or runtime reconstruction, and whether the current instance can consume the change.
-4. Inspect `editor_status`. If Play Mode must stop, obtain lifecycle authorization unless already explicit (including the current session's `/unity-playmode-exit allow` toggle), dispatch the advertised `editor_stop`, and verify Play Mode exited.
-5. Apply the durable edit with the owning file/asset tool.
-6. Use the `unity-pipeline-workflows` skill for any required connected compilation and terminal status validation.
-7. Re-enter Play Mode only when requested. Report temporary live confirmation and durable verification as separate evidence.
-
-## Stop Conditions
-
-Stop and report uncertainty instead of changing routes when:
-
-- the exact-copy identity changes or cannot be revalidated;
-- Pipeline disconnects outside an expected, separately authorized compile/reload transition;
-- the target is ambiguous or disappears;
-- the required operation has no typed command and cannot be expressed as one bounded target-specific eval;
-- eval returns diagnostics, malformed output, or an unknown side effect;
-- persistence ownership or runtime conversion cannot be established;
-- a required Play Mode stop, restart, compile, save, or other lifecycle mutation is not authorized.
-
-Never launch batchmode or another Editor to continue an interactive live-authoring session.
+---
+name: unity-interactive-playmode-authoring
+description: Inspect and temporarily tune live Unity runtime objects through a reachable exact-copy Pipeline Editor while Play Mode remains active, then deliberately translate accepted runtime values into durable source or asset changes. Use only for explicit interactive Play Mode authoring or live visual experiments; not for ordinary compile, tests, planning, or batchmode.
+---
+
+# Unity Interactive Play Mode Authoring
+
+Use this skill only when the user explicitly requests inspection or temporary mutation of live runtime state in an already-running exact Unity project copy. Typical examples include moving a runtime UI element while the user watches, tuning a value interactively, or exploring which connected Pipeline interaction mode can reach a live object.
+
+Do not activate this skill for ordinary source edits, serialized-asset authoring, planning inspection, compilation, tests, screenshots alone, or opening Unity. Use the owning Unity workflow for those operations.
+
+## Preconditions
+
+1. Resolve the exact Unity project path; never route by display name or a similarly named workspace.
+2. Call `unity_project_status` and require a verified matching Editor process, a reachable exact-copy Pipeline instance, and the advertised commands needed for the intended operation.
+3. Inspect the advertised `editor_status` and require Play Mode to be active for a live-runtime experiment. If Play Mode is not active, do not enter it unless the user explicitly requested that lifecycle change.
+4. Revalidate exact project path and Editor/Pipeline process identity before each mutation. Stop on unknown, stale, unreachable, or changed identity.
+5. Establish the target object, requested temporary effect, and expected observation before mutation. Do not explore by changing unrelated live objects.
+
+## Choose the Smallest Interaction Surface
+
+Choose the smallest route that answers the question clearly:
+
+1. **Advertised typed command.** Use a purpose-built command when its validation and result shape fit the task.
+2. **One-shot connected command or `eval`.** Use advertised `eval` as the normal REPL escape hatch for project-specific properties, APIs, and operations that registered commands did not anticipate. Prefer one bounded invocation with an explicit return value over a long-lived interactive shell.
+
+Typed commands are conveniences, not exclusive gateways. Do not force repository inference or add a new wrapper merely to avoid a direct connected property inspection.
+
+GameObject transform and component commands do not operate on every runtime object. For example, UI Toolkit `VisualElement`s are not scene GameObjects, so `set_transform` is not an appropriate route for their layout styles.
+
+`unity shell` is a human interactive convenience over the same connected Pipeline surface. It is not a stronger Editor capability and is not the preferred agent automation route.
+
+## Command Discovery
+
+- Prefer the command inventory returned by `unity_project_status`; do not fan out across CLI help, shell, and trial dispatch when availability is already known.
+- If raw `unity list` is exceptionally needed, parse the outer JSON envelope and read command records from `data.tools`, not a guessed top-level `commands` field.
+- Inspect one exact command schema before dispatch rather than repeatedly trialing argument forms against the live Editor.
+- Treat outer CLI success as transport evidence only. Parse nested `success`, diagnostics, status, and result fields before claiming success.
+
+## Bounded Eval Rules
+
+Pipeline `eval` compiles C# with Roslyn and runs it on the connected Editor's main thread. It can inspect or call any reachable engine, Editor, or project API; it is not intrinsically read-only, and a static syntax/property allowlist is not a reliable side-effect boundary.
+
+- Use one bounded, target-specific snippet with an explicit return value.
+- Regular property and state inspection is allowed when it serves the active task.
+- Resolve the exact target and check for a missing target before mutation.
+- Mutations must match the user's request. Lifecycle, destructive, persistent-setting, asset, package, selection, scene-save, import, build, test, and source-file changes require the same authorization they would through a typed command.
+- Research unfamiliar Unity/C# APIs when needed, but do not add a purpose-built wrapper solely to avoid `eval`.
+- Avoid obsolete APIs; evaluator diagnostics may treat obsolete usage as a compilation failure.
+- Fully qualify APIs when extension-method or namespace ambiguity is likely.
+- Treat any compiler diagnostic, nested failure, null target, malformed result, or identity change as failure. Do not retry mutations speculatively.
+
+Use `unity_pipeline_eval` for exact-copy connected C# queries and operations. Use `unity_pipeline_inspect` when one of its package-owned purpose-built inspection commands provides better evidence.
+
+## Live Tuning Loop
+
+For each requested adjustment:
+
+1. Revalidate the exact-copy Pipeline identity and Play Mode state.
+2. Read the current live value when needed to make the requested relative or absolute adjustment.
+3. Apply one bounded temporary mutation.
+4. Return the observed before/after values and ask for the next adjustment only when user observation is required.
+5. State that the override is non-persistent and may be replaced by rendering, rebinding, a domain reload, or Play Mode exit.
+
+Do not infer that a serialized asset or source edit updates an existing runtime instance. Confirm the relevant refresh, rebind, or reconstruction path before claiming a live result.
+
+## Persisting an Accepted Runtime Result
+
+A request to persist authorizes the durable source/asset edit, but lifecycle changes remain explicit unless already authorized.
+
+1. Capture the final runtime values and the owning coordinate space, dimensions, scale, or other context needed to convert them into authored values.
+2. Identify the authoritative source or serialized field and trace how it becomes the runtime value. Do not write a visual coordinate into a guessed representation.
+3. Determine whether persistence triggers asset import, script compilation, domain reload, or runtime reconstruction, and whether the current instance can consume the change.
+4. Inspect `editor_status`. If Play Mode must stop, dispatch the advertised `editor_stop` and verify Play Mode exited.
+5. Apply the durable edit with the owning file/asset tool.
+6. Use the `unity-pipeline-workflows` skill for any required connected compilation and terminal status validation.
+7. Re-enter Play Mode only when requested. Report temporary live confirmation and durable verification as separate evidence.
+
+## Stop Conditions
+
+Stop and report uncertainty instead of changing routes when:
+
+- the exact-copy identity changes or cannot be revalidated;
+- Pipeline disconnects outside an expected, separately authorized compile/reload transition;
+- the target is ambiguous or disappears;
+- the required operation has no typed command and cannot be expressed as one bounded target-specific eval;
+- eval returns diagnostics, malformed output, or an unknown side effect;
+- persistence ownership or runtime conversion cannot be established;
+- a required Play Mode stop, restart, compile, save, or other lifecycle mutation is not authorized.
+
+Never launch batchmode or another Editor to continue an interactive live-authoring session.

package/skills/unity-pipeline-workflows/SKILL.md

@@ -1,52 +1,52 @@
----
-name: unity-pipeline-workflows
-description: Recompile code or run focused Unity tests through a reachable com.unity.pipeline Editor without launching, closing, or manually polling another Unity process.
----
-
-# Unity Pipeline Workflows
-
-Use this workflow only for an already-running exact project copy with `com.unity.pipeline` installed and reachable.
-
-## Preferred typed tools
-
-Use one typed tool call for each supported connected operation:
-
-- `unity_pipeline_recompile` for connected script compilation.
-- `unity_pipeline_run_tests` for one focused `EditMode` or `PlayMode` test-name selection.
-
-These tools resolve the exact copy, require advertised commands, inspect lifecycle state, dispatch once, validate identity, and poll internally with a fixed deadline. Do not recreate their wait loops with `bash`, `unity recompile_status`, or `unity test_status` calls.
-
-A timeout or malformed response is uncertain: the Unity operation may still be running. Do not cancel, retry, launch batchmode, close the Editor, or claim a result without a new user-authorized decision.
-
-## Preconditions and boundaries
-
-1. Pass an explicit `path` when multiple project copies may be found; paths identify copies, not display names.
-2. The typed tools require a reachable exact-copy Pipeline and advertised `editor_status` plus operation commands. A different connected client is not itself a project lock.
-3. Autonomous Play Mode exit is disallowed by default. `unity_pipeline_recompile` never sends `editor_stop` or overrides Unity's Script Changes While Playing preference: known recompile-and-continue and defer policies may proceed without exit authorization; known stop-and-recompile and unavailable policy require `/unity-playmode-exit allow` because the recompile may exit Play Mode. Pipeline 0.4 does not currently expose that preference, so absence is reported as uncertainty rather than a claim that Unity cannot compile in Play Mode. `unity_pipeline_run_tests` has separate lifecycle semantics and may dispatch advertised `editor_stop` only after that same authorization, then verifies Edit Mode. `/unity-playmode-exit disallow` restores the default. The tools never enter Play Mode, pause, save, launch, or close Unity autonomously; recompilation may perform Unity's normal asset refresh/import and script-change behavior.
-4. Test success requires a well-formed terminal result, a known positive executed count, and zero failures. An asynchronous initiation with `Total: 0` and `running` is nonterminal.
-5. Passing test records are intentionally discarded. Failures retain only a bounded set of failed/inconclusive names, messages, and stack excerpts.
-
-## Compile
-
-Call `unity_pipeline_recompile` with optional `path` and `timeoutSeconds` (default 180, maximum 3600). It reports either up-to-date scripts or a compact completion summary, including whether an explicit agent exit, Unity-policy-driven behavior, or unavailable policy applied. A defer policy can mean recompilation waits until Play Mode ends. Compiler failures, identity changes, cancellation, malformed evidence, and deadline expiry are tool errors.
-
-## Focused tests
-
-Call `unity_pipeline_run_tests` with:
-
-- required `testPlatform`: `EditMode` or `PlayMode`;
-- optional `testFilter`: one test-name filter only;
-- optional `path` and `timeoutSeconds` (default 600, maximum 3600).
-- before running PlayMode tests, check the Game View focus setting. Set it to Play Unfocused for the test run, then restore the previous setting afterward.
-
-The tool treats `no_tests`, idle, and not-started statuses as safe inactivity, detects a pre-existing active connected test before dispatch, and stops rather than claiming or replacing active work. It captures returned mode/filter/run identity fields when available and stops as uncertain if status is clearly displaced by another run.
-
-## Bounded raw CLI troubleshooting only
-
-Normally call the typed tools, not raw CLI commands. If a typed tool is unavailable in an older installed package and a user specifically authorizes troubleshooting, first use `unity_project_status` and require advertised `recompile_status` or `run_tests` and `test_status`. Use the documented asynchronous form with `--async_tests true`, one fixed deadline, and bounded backoff; parse object and stringified nested JSON. `Total: 0` with `result: running` is a valid nonterminal initiating response. Passing evidence reports successful completion, a known positive executed-test count, and zero failures; nested `success:false`, changed exact-copy identity, or polling timeout is non-passing uncertainty. Do not silently fall back to batchmode after uncertain connected dispatch. Connected work does not guarantee NUnit XML.
-
-## When not to use connected tools
-
-Use `unity_run_test_batch` for a closed project, intentional isolation/CI, category or multiple filters, or required NUnit XML/log evidence. State the reason for that route. Do not use batchmode as an automatic fallback after an uncertain connected dispatch.
-
-Use the typed compile/test tools when their polling and terminal evidence fit the task. Advertised Pipeline `eval` remains available through `unity_pipeline_eval` for bounded project-specific inspection or operations outside those typed workflows; it is an assistance surface, not a forbidden fallback or a substitute for the typed tools' completion protocol. Eval compiles arbitrary C# with Roslyn on the Editor main thread, so ordinary properties and local-variable snippets are valid; it is not expression-only or reliably statically read-only. Prefer typed tools for their stronger evidence, but let user intent and project guidance govern mutations. Lifecycle, persistent-setting, destructive, asset, scene-save, package, build, and test mutations require explicit authorization.
+---
+name: unity-pipeline-workflows
+description: Recompile code or run focused Unity tests through a reachable com.unity.pipeline Editor without launching, closing, or manually polling another Unity process.
+---
+
+# Unity Pipeline Workflows
+
+Use this workflow only for an already-running exact project copy with `com.unity.pipeline` installed and reachable.
+
+## Preferred typed tools
+
+Use one typed tool call for each supported connected operation:
+
+- `unity_pipeline_recompile` for connected script compilation.
+- `unity_pipeline_run_tests` for one focused `EditMode` or `PlayMode` test-name selection.
+
+These tools resolve the exact copy, require advertised commands, inspect lifecycle state, dispatch once, validate identity, and poll internally with a fixed deadline. Do not recreate their wait loops with `bash`, `unity recompile_status`, or `unity test_status` calls.
+
+A timeout or malformed response is uncertain: the Unity operation may still be running. Do not cancel, retry, launch batchmode, close the Editor, or claim a result without a new user-authorized decision.
+
+## Preconditions and boundaries
+
+1. Pass an explicit `path` when multiple project copies may be found; paths identify copies, not display names.
+2. The typed tools require a reachable exact-copy Pipeline and advertised `editor_status` plus operation commands. A different connected client is not itself a project lock.
+3. `unity_pipeline_recompile` never sends `editor_stop` or overrides Unity's Script Changes While Playing preference. Known recompile-and-continue, stop-and-recompile, and defer policies proceed according to Unity's configured behavior. Pipeline 0.4 does not currently expose that preference, so the tool reports the unavailable policy while allowing recompilation to proceed. `unity_pipeline_run_tests` may dispatch advertised `editor_stop` when needed, then verifies Edit Mode before running tests. The tools never enter Play Mode, pause, save, launch, or close Unity; recompilation may perform Unity's normal asset refresh/import and script-change behavior.
+4. Test success requires a well-formed terminal result, a known positive executed count, and zero failures. An asynchronous initiation with `Total: 0` and `running` is nonterminal.
+5. Passing test records are intentionally discarded. Failures retain only a bounded set of failed/inconclusive names, messages, and stack excerpts.
+
+## Compile
+
+Call `unity_pipeline_recompile` with optional `path` and `timeoutSeconds` (default 180, maximum 3600). It reports either up-to-date scripts or a compact completion summary, including whether an explicit agent exit, Unity-policy-driven behavior, or unavailable policy applied. A defer policy can mean recompilation waits until Play Mode ends. Compiler failures, identity changes, cancellation, malformed evidence, and deadline expiry are tool errors.
+
+## Focused tests
+
+Call `unity_pipeline_run_tests` with:
+
+- required `testPlatform`: `EditMode` or `PlayMode`;
+- optional `testFilter`: one test-name filter only;
+- optional `path` and `timeoutSeconds` (default 600, maximum 3600).
+- before running PlayMode tests, check the Game View focus setting. Set it to Play Unfocused for the test run, then restore the previous setting afterward.
+
+The tool treats `no_tests`, idle, and not-started statuses as safe inactivity, detects a pre-existing active connected test before dispatch, and stops rather than claiming or replacing active work. It captures returned mode/filter/run identity fields when available and stops as uncertain if status is clearly displaced by another run.
+
+## Bounded raw CLI troubleshooting only
+
+Normally call the typed tools, not raw CLI commands. If a typed tool is unavailable in an older installed package and a user specifically authorizes troubleshooting, first use `unity_project_status` and require advertised `recompile_status` or `run_tests` and `test_status`. Use the documented asynchronous form with `--async_tests true`, one fixed deadline, and bounded backoff; parse object and stringified nested JSON. `Total: 0` with `result: running` is a valid nonterminal initiating response. Passing evidence reports successful completion, a known positive executed-test count, and zero failures; nested `success:false`, changed exact-copy identity, or polling timeout is non-passing uncertainty. Do not silently fall back to batchmode after uncertain connected dispatch. Connected work does not guarantee NUnit XML.
+
+## When not to use connected tools
+
+Use `unity_run_test_batch` for a closed project, intentional isolation/CI, category or multiple filters, or required NUnit XML/log evidence. State the reason for that route. Do not use batchmode as an automatic fallback after an uncertain connected dispatch.
+
+Use the typed compile/test tools when their polling and terminal evidence fit the task. Advertised Pipeline `eval` remains available through `unity_pipeline_eval` for bounded project-specific inspection or operations outside those typed workflows; it is an assistance surface, not a forbidden fallback or a substitute for the typed tools' completion protocol. Eval compiles arbitrary C# with Roslyn on the Editor main thread, so ordinary properties and local-variable snippets are valid; it is not expression-only or reliably statically read-only. Prefer typed tools for their stronger evidence, but let user intent and project guidance govern mutations. Lifecycle, persistent-setting, destructive, asset, scene-save, package, build, and test mutations require explicit authorization.

package/src/unity-artifact-profile.ts

@@ -1,110 +1,110 @@
-import { access } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
-import * as path from "node:path";
-import type {
-  ArtifactCandidateV1,
-  ArtifactProfileV1,
-  ArtifactValidationResultV1,
-} from "@aefree/pi-project-artifacts/contracts/v1";
-
-export const UNITY_ARTIFACT_PROFILE_ID_V1 = "unity.artifacts.v1" as const;
-export const UNITY_RENDER_PIPELINES = ["builtin", "urp", "hdrp", "custom", "agnostic"] as const;
-
-const OWNER = Object.freeze({
-  packageName: "@aefree/pi-unity",
-  packageVersion: "0.8.3",
-  packageRoot: path.resolve(fileURLToPath(new URL("..", import.meta.url))),
-  registeredBy: "index.ts",
-});
-
-/**
- * Optional project-artifacts enrichment. These fields describe and validate
- * metadata but never authorize raw discovery/filtering. Artifact paths already
- * distinguish solutions from memories, while generic tags/module/component
- * metadata remains project-owned and schema-open.
- */
-export function createUnityArtifactProfileV1(): ArtifactProfileV1 {
-  return Object.freeze({
-    contractVersion: 1,
-    id: UNITY_ARTIFACT_PROFILE_ID_V1,
-    kind: "artifact-profile",
-    owner: OWNER,
-    artifactKinds: Object.freeze(["solution", "memory"]),
-    fields: Object.freeze([
-      { name: "engine", type: "string", indexed: true, filterable: true, enumValues: Object.freeze(["unity"]) },
-      { name: "unity_version", type: "string", indexed: true, filterable: true },
-      { name: "unity_packages", type: "string_list", indexed: true, filterable: true },
-      { name: "render_pipeline", type: "string", indexed: true, filterable: true, enumValues: UNITY_RENDER_PIPELINES },
-      { name: "platforms", type: "string_list", indexed: true, filterable: true },
-    ]),
-    validators: Object.freeze([{
-      id: "unity.artifact-metadata.v1",
-      async validate(_context, request) {
-        if (request.signal.aborted) return { outcome: "unavailable", code: "aborted", retryable: true };
-        return validateUnityArtifactMetadata(request.artifact);
-      },
-    }]),
-    async appliesTo(_context, request) {
-      if (request.signal.aborted) return false;
-      // A conventional docs path is not Unity authority. Require direct project
-      // evidence before contributing definitions or validation confidence.
-      try {
-        await access(path.join(request.workspaceRoot, "ProjectSettings", "ProjectVersion.txt"));
-        return true;
-      } catch {
-        return false;
-      }
-    },
-  });
-}
-
-/** Validate only declared Unity fields that are present; all fields are optional. */
-export function validateUnityArtifactMetadata(artifact: ArtifactCandidateV1): ArtifactValidationResultV1 {
-  const frontmatter = artifact.frontmatter;
-  const issues: { code: string; field: string; summary: string }[] = [];
-
-  validateEnumString(frontmatter, "engine", ["unity"], issues);
-  validateNonEmptyString(frontmatter, "unity_version", issues);
-  validateStringList(frontmatter, "unity_packages", issues);
-  validateEnumString(frontmatter, "render_pipeline", UNITY_RENDER_PIPELINES, issues);
-  validateStringList(frontmatter, "platforms", issues);
-
-  return issues.length === 0 ? { outcome: "valid" } : { outcome: "invalid", issues };
-}
-
-function validateNonEmptyString(
-  frontmatter: Readonly<Record<string, unknown>>,
-  field: string,
-  issues: { code: string; field: string; summary: string }[],
-): void {
-  const value = frontmatter[field];
-  if (value === undefined) return;
-  if (typeof value !== "string" || value.trim() === "") {
-    issues.push({ code: `unity_${field}_invalid`, field, summary: `Unity ${field} must be a non-empty string when present.` });
-  }
-}
-
-function validateEnumString(
-  frontmatter: Readonly<Record<string, unknown>>,
-  field: string,
-  values: readonly string[],
-  issues: { code: string; field: string; summary: string }[],
-): void {
-  const value = frontmatter[field];
-  if (value === undefined) return;
-  if (typeof value !== "string" || !values.includes(value)) {
-    issues.push({ code: `unity_${field}_invalid`, field, summary: `Unity ${field} must be one of: ${values.join(", ")}.` });
-  }
-}
-
-function validateStringList(
-  frontmatter: Readonly<Record<string, unknown>>,
-  field: string,
-  issues: { code: string; field: string; summary: string }[],
-): void {
-  const value = frontmatter[field];
-  if (value === undefined) return;
-  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || item.trim() === "")) {
-    issues.push({ code: `unity_${field}_invalid`, field, summary: `Unity ${field} must be a non-empty list of non-empty strings when present.` });
-  }
-}
+import { access } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+import type {
+  ArtifactCandidateV1,
+  ArtifactProfileV1,
+  ArtifactValidationResultV1,
+} from "@aefree/pi-project-artifacts/contracts/v1";
+
+export const UNITY_ARTIFACT_PROFILE_ID_V1 = "unity.artifacts.v1" as const;
+export const UNITY_RENDER_PIPELINES = ["builtin", "urp", "hdrp", "custom", "agnostic"] as const;
+
+const OWNER = Object.freeze({
+  packageName: "@aefree/pi-unity",
+  packageVersion: "0.8.3",
+  packageRoot: path.resolve(fileURLToPath(new URL("..", import.meta.url))),
+  registeredBy: "index.ts",
+});
+
+/**
+ * Optional project-artifacts enrichment. These fields describe and validate
+ * metadata but never authorize raw discovery/filtering. Artifact paths already
+ * distinguish solutions from memories, while generic tags/module/component
+ * metadata remains project-owned and schema-open.
+ */
+export function createUnityArtifactProfileV1(): ArtifactProfileV1 {
+  return Object.freeze({
+    contractVersion: 1,
+    id: UNITY_ARTIFACT_PROFILE_ID_V1,
+    kind: "artifact-profile",
+    owner: OWNER,
+    artifactKinds: Object.freeze(["solution", "memory"]),
+    fields: Object.freeze([
+      { name: "engine", type: "string", indexed: true, filterable: true, enumValues: Object.freeze(["unity"]) },
+      { name: "unity_version", type: "string", indexed: true, filterable: true },
+      { name: "unity_packages", type: "string_list", indexed: true, filterable: true },
+      { name: "render_pipeline", type: "string", indexed: true, filterable: true, enumValues: UNITY_RENDER_PIPELINES },
+      { name: "platforms", type: "string_list", indexed: true, filterable: true },
+    ]),
+    validators: Object.freeze([{
+      id: "unity.artifact-metadata.v1",
+      async validate(_context, request) {
+        if (request.signal.aborted) return { outcome: "unavailable", code: "aborted", retryable: true };
+        return validateUnityArtifactMetadata(request.artifact);
+      },
+    }]),
+    async appliesTo(_context, request) {
+      if (request.signal.aborted) return false;
+      // A conventional docs path is not Unity authority. Require direct project
+      // evidence before contributing definitions or validation confidence.
+      try {
+        await access(path.join(request.workspaceRoot, "ProjectSettings", "ProjectVersion.txt"));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+  });
+}
+
+/** Validate only declared Unity fields that are present; all fields are optional. */
+export function validateUnityArtifactMetadata(artifact: ArtifactCandidateV1): ArtifactValidationResultV1 {
+  const frontmatter = artifact.frontmatter;
+  const issues: { code: string; field: string; summary: string }[] = [];
+
+  validateEnumString(frontmatter, "engine", ["unity"], issues);
+  validateNonEmptyString(frontmatter, "unity_version", issues);
+  validateStringList(frontmatter, "unity_packages", issues);
+  validateEnumString(frontmatter, "render_pipeline", UNITY_RENDER_PIPELINES, issues);
+  validateStringList(frontmatter, "platforms", issues);
+
+  return issues.length === 0 ? { outcome: "valid" } : { outcome: "invalid", issues };
+}
+
+function validateNonEmptyString(
+  frontmatter: Readonly<Record<string, unknown>>,
+  field: string,
+  issues: { code: string; field: string; summary: string }[],
+): void {
+  const value = frontmatter[field];
+  if (value === undefined) return;
+  if (typeof value !== "string" || value.trim() === "") {
+    issues.push({ code: `unity_${field}_invalid`, field, summary: `Unity ${field} must be a non-empty string when present.` });
+  }
+}
+
+function validateEnumString(
+  frontmatter: Readonly<Record<string, unknown>>,
+  field: string,
+  values: readonly string[],
+  issues: { code: string; field: string; summary: string }[],
+): void {
+  const value = frontmatter[field];
+  if (value === undefined) return;
+  if (typeof value !== "string" || !values.includes(value)) {
+    issues.push({ code: `unity_${field}_invalid`, field, summary: `Unity ${field} must be one of: ${values.join(", ")}.` });
+  }
+}
+
+function validateStringList(
+  frontmatter: Readonly<Record<string, unknown>>,
+  field: string,
+  issues: { code: string; field: string; summary: string }[],
+): void {
+  const value = frontmatter[field];
+  if (value === undefined) return;
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+    issues.push({ code: `unity_${field}_invalid`, field, summary: `Unity ${field} must be a non-empty list of non-empty strings when present.` });
+  }
+}