From 36ee517e1e96a882406f14f6e1a0c14611897865 Mon Sep 17 00:00:00 2001
From: Neko Ayaka <neko@ayaka.moe>
Date: Wed, 22 Apr 2026 13:54:02 +0800
Subject: [PATCH] chore(README.md): updated for more instructions

---
 .../README.md                                   | 16 ++++++++++++++++
 packages/vishot-runner-electron/README.md       | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)

diff --git a/packages/scenarios-stage-tamagotchi-electron/README.md b/packages/scenarios-stage-tamagotchi-electron/README.md
index bd82b525f..ac0797f44 100644
--- a/packages/scenarios-stage-tamagotchi-electron/README.md
+++ b/packages/scenarios-stage-tamagotchi-electron/README.md
@@ -71,3 +71,19 @@ Important:
 - Scenario entrypoints should point at `index.ts` when the workflow is organized as a section folder.
 - Keep this package focused on Electron capture flows for docs screenshots.
 - Paths in these `pnpm -F` examples are resolved from the filtered package working directory.
+
+## Electron Profile Note (Plugin Discovery)
+
+When running scenarios through `@proj-airi/vishot-runner-electron`, the built Electron app can use a different `userData` profile than `dev:tamagotchi`.
+
+- `dev:tamagotchi` plugin root commonly resolves to:
+  - `~/Library/Application Support/@proj-airi/stage-tamagotchi/plugins/v1`
+- Vishot/Electron capture runs can resolve plugin root to:
+  - `~/Library/Application Support/Electron/plugins/v1`
+
+If the chess plugin appears in dev but not in Vishot (`Discovered 0` or `Plugin manifest not found`), link the plugin `dist` directory into the Electron profile plugins root too:
+
+```bash
+mkdir -p "$HOME/Library/Application Support/Electron/plugins/v1"
+ln -sfn "/absolute/path/to/airi-plugin-game-chess/dist" "$HOME/Library/Application Support/Electron/plugins/v1/airi-plugin-game-chess"
+```
diff --git a/packages/vishot-runner-electron/README.md b/packages/vishot-runner-electron/README.md
index a88aa03c4..89e766b88 100644
--- a/packages/vishot-runner-electron/README.md
+++ b/packages/vishot-runner-electron/README.md
@@ -44,6 +44,23 @@ pnpm -F @proj-airi/scenarios-stage-tamagotchi-browser capture
 
 In this environment, the raw capture command worked end-to-end after running outside the sandbox because `tsx` pipe creation was denied inside the sandbox (`listen EPERM` on the temporary `tsx` IPC pipe).
 
+## Electron Profile Note (Plugin Host Root)
+
+`vishot-runner-electron` launches the built Electron app entrypoint. In local development this can resolve `app.getPath('userData')` to the `Electron` profile directory, which means plugin discovery happens under:
+
+- `~/Library/Application Support/Electron/plugins/v1`
+
+This may differ from `dev:tamagotchi`, which often uses:
+
+- `~/Library/Application Support/@proj-airi/stage-tamagotchi/plugins/v1`
+
+If plugin-host devtools shows `Discovered 0`, `Plugin manifest not found`, or module registration errors during Vishot scenarios, mirror your plugin symlink into the Electron profile plugins directory:
+
+```bash
+mkdir -p "$HOME/Library/Application Support/Electron/plugins/v1"
+ln -sfn "/absolute/path/to/airi-plugin-game-chess/dist" "$HOME/Library/Application Support/Electron/plugins/v1/airi-plugin-game-chess"
+```
+
 ## Additional Examples
 
 To verify the controls-island hearing button specifically: