fix(pi): package warning-free skill mirror and docs

docs/PI-RESEARCH.md

@@ -32,7 +32,7 @@ Important discovery details from the skills docs:
 - top-level `.md` files are loaded as skills in pi-native roots like `.pi/skills/`
 - per the upstream skills docs, top-level `.md` files are ignored in `.agents/skills/`
 
-Implication for this repo: `skills/<skill>/pi/SKILL.md` fits pi's recursive discovery model cleanly, both for local copies and for package-based installs.
+Implication for this repo: `skills/<skill>/pi/SKILL.md` fits pi's recursive discovery model cleanly for source authoring and manual copies, but it is not clean for package-discovered installs because Pi requires the immediate parent directory of `SKILL.md` to match the skill frontmatter `name`.
 
 ### Package Support
 
@@ -46,7 +46,7 @@ Relevant package behaviors:
 - installed pi packages can also ship `extensions/`, `prompts/`, and `themes/`
 - when pi installs npm or git packages, it runs `npm install`
 
-Implication for this repo: a single repo-level `package.json` is a viable v1 surface for shipping only the pi resources.
+Implication for this repo: a single repo-level `package.json` is a viable v1 surface for shipping only the Pi resources, but the package-facing skill directories must be shaped like `<skill-name>/SKILL.md`. That means the repo should preserve `skills/<family>/pi/` for editing and expose a separate mirror such as `pi-package/skills/<skill-name>/` to Pi.
 
 ### Settings And Path Overrides
 
@@ -84,6 +84,7 @@ Implication for this repo:
 ## Decisions Derived From Research
 
 - Use `skills/<skill>/pi/` for all five skill families.
+- Package Pi skills through a separate mirror whose immediate directory names match the frontmatter `name` values.
 - Publish shared pi guidance in repo docs instead of burying pi assumptions inside each skill.
 - Use one repo-level pi package in v1.
 - Assess extensions explicitly, but defer them unless they provide clear v1 value beyond documentation and helper scripts.