Exclude AppleDouble companions from test discovery (#11)

docs/METADATA_DISCOVERY.md

@@ -0,0 +1,53 @@
+# macOS metadata and source discovery
+
+macOS can create AppleDouble companions whose path components start with `._`.
+These files contain filesystem metadata and are not application source. On the
+external-drive review checkout, the former Vitest include pattern selected
+`src/avatar/._*.test.ts` files and attempted to transform their binary contents.
+TypeScript 5.8 already skips the tested dot-prefixed paths with its existing
+`src` include. Its new explicit exclusions document the same metadata policy
+while preserving compiler options and ordinary input discovery.
+
+Shared source issue [#11](https://git.whoagland.com/phenom/healer-man/issues/11)
+owns the default discovery correction:
+
+- `vite.config.ts` retains `configDefaults.exclude` and adds `**/._*` plus
+  `**/._*/**` to the test exclusions.
+- `tsconfig.app.json` retains its compiler options and `include: ["src"]`.
+  Its exclusions retain the package-directory defaults and add the same
+  metadata patterns.
+
+The two patterns cover companion files and files inside a companion directory,
+including nested directories. A component must start with `._`; ordinary
+underscore names and names containing those characters elsewhere remain source.
+Existing metadata files are retained. This changes root input discovery;
+TypeScript's normal handling of explicit imports still applies.
+
+`tools/verify-appledouble-metadata-discovery.mjs` supplies a focused regression
+proof through actual Vitest discovery/execution and TypeScript configuration
+input parsing. It uses fresh task-owned fixtures to verify the rejection path
+and two ordinary test sentinels to verify continued execution. It does not certify
+full application typechecking, a browser production build, gameplay, balance,
+character rendering or dungeon behavior.
+
+Exact commands, input identities and observed results accompany the issue and
+`metadata-discovery-validation.json`. Shared source issue
+[#9](https://git.whoagland.com/phenom/healer-man/issues/9) still owns its separate
+browser build/live visual acceptance gap. Native checkpoint
+[#292](https://git.whoagland.com/Codex/healer-man-godot/issues/292) is already
+installed and merged. This tooling change requires no native runtime rebuild:
+the native writable source mirror is a subset without these browser configs.
+
+Run the focused proof after installing the repository dependencies:
+
+```sh
+node tools/verify-appledouble-metadata-discovery.mjs --evidence-dir /absolute/fresh-path
+```
+
+Use a fresh absolute path outside the checkout. The helper keeps its fixtures
+and reports; it refuses existing destinations, overlap and symlink paths. It
+works from another current directory and uses the Node executable that launched
+it. The final external-drive control records three binary metadata transform
+failures; fixed Vitest defaults run both ordinary tests. TypeScript API and CLI
+resolve the same two ordinary inputs, with and without the explicit metadata
+filters. The Vite/Node configuration typecheck passes.