diff --git a/.opencode/OPENCODE.md b/.opencode/OPENCODE.md
deleted file mode 100644
index 421b7574..00000000
--- a/.opencode/OPENCODE.md
+++ /dev/null
@@ -1,32 +0,0 @@
-# PAI-OpenCode
-
-## For OpenCode
-
-When you start in this directory, determine the installation state:
-
-### If settings.json exists and is configured:
-This is an established PAI installation. Read and follow the PAI skill:
-```
-read PAI/SKILL.md
-```
-
-### If this is a fresh installation:
-1. The default `settings.json` works out of the box
-2. Edit settings with your preferences if desired
-3. Start using PAI!
-
-## For Humans
-
-Welcome to PAI-OpenCode v1.0!
-
-1. **Just start**: `opencode` - everything works with defaults
-2. **Customize**: Edit `settings.json` for identity and preferences
-3. **Learn more**: Read `PAI/SKILL.md`
-
-For full documentation, see the README.md in the repository root.
-
----
-
-**PAI-OpenCode** - Vanilla PAI 2.4 on OpenCode
-
-Repository: [github.com/Steffen025/pai-opencode](https://github.com/Steffen025/pai-opencode)
diff --git a/.opencode/PAISYSTEM/PAI-TO-OPENCODE-MAPPING.md b/.opencode/PAISYSTEM/PAI-TO-OPENCODE-MAPPING.md
index 00f4dba5..0936549e 100644
--- a/.opencode/PAISYSTEM/PAI-TO-OPENCODE-MAPPING.md
+++ b/.opencode/PAISYSTEM/PAI-TO-OPENCODE-MAPPING.md
@@ -20,7 +20,7 @@ PAI-OpenCode is a vanilla PAI implementation adapted for OpenCode's architecture
 | **Root Directory** | `.claude/` | `.opencode/` |
 | **Lifecycle Events** | `hooks/*.hook.ts` | `plugins/handlers/*.ts` |
 | **Config Schema** | Claude Code settings.json | OpenCode settings.json |
-| **Meta File** | `CLAUDE.md` | `OPENCODE.md` |
+| **Meta File** | `CLAUDE.md` | `AGENTS.md` |
 | **Path Variable** | `$PAI_DIR` → `~/.claude` | `$PAI_DIR` → `.opencode` |
 
 ---
diff --git a/.opencode/skills/Utilities/Parser/Workflows/BatchEntityExtractionGemini3.md b/.opencode/skills/Utilities/Parser/Workflows/BatchEntityExtractionGemini3.md
index e615f765..1106f735 100755
--- a/.opencode/skills/Utilities/Parser/Workflows/BatchEntityExtractionGemini3.md
+++ b/.opencode/skills/Utilities/Parser/Workflows/BatchEntityExtractionGemini3.md
@@ -70,7 +70,7 @@ urls=$(pbpaste)
 import { isContentAlreadyParsed } from '../utils/collision-detection';
 
 const entityIndex = JSON.parse(
-  fs.readFileSync('~/.opencode/skills/parser/entity-index.json', 'utf-8')
+  fs.readFileSync('~/.opencode/skills/Utilities/Parser/entity-index.json', 'utf-8')
 );
 
 const newUrls = urls.filter(url => !isContentAlreadyParsed(url, entityIndex));
@@ -453,7 +453,7 @@ function processArticleEntities(
 }
 
 // Main processing
-const entityIndexPath = '~/.opencode/skills/parser/entity-index.json';
+const entityIndexPath = '~/.opencode/skills/Utilities/Parser/entity-index.json';
 const entityIndex: EntityIndex = JSON.parse(fs.readFileSync(entityIndexPath, 'utf-8'));
 
 const rawEntities = JSON.parse(fs.readFileSync('raw-entities.json', 'utf-8'));
@@ -484,7 +484,7 @@ const ajv = new Ajv({ strict: false });
 addFormats(ajv);
 
 const schema = JSON.parse(
-  fs.readFileSync('~/.opencode/skills/parser/schema/content-schema.json', 'utf-8')
+  fs.readFileSync('~/.opencode/skills/Utilities/Parser/schema/content-schema.json', 'utf-8')
 );
 
 const validate = ajv.compile(schema);
@@ -556,7 +556,7 @@ processedArticles.forEach((article: any, index: number) => {
   } else {
     // Save validated content
     const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
-    const filename = `~/.opencode/skills/parser/output/${timestamp}_batch-${index + 1}.json`;
+    const filename = `~/.opencode/skills/Utilities/Parser/output/${timestamp}_batch-${index + 1}.json`;
     fs.writeFileSync(filename, JSON.stringify(fullContent, null, 2));
     console.log(`Saved: ${filename}`);
   }
@@ -569,7 +569,7 @@ The entity index is automatically updated during step 5. Verify the update:
 
 ```bash
 # Check entity counts
-cat ~/.opencode/skills/parser/entity-index.json | jq '{
+cat ~/.opencode/skills/Utilities/Parser/entity-index.json | jq '{
   people_count: (.people | length),
   companies_count: (.companies | length),
   links_count: (.links | length),
@@ -596,7 +596,7 @@ if [ $# -eq 0 ]; then
 fi
 
 URLS=("$@")
-SKILL_DIR="$HOME/.claude/skills/parser"
+SKILL_DIR="$HOME/.opencode/skills/Utilities/Parser"
 OUTPUT_DIR="$SKILL_DIR/output"
 TIMESTAMP=$(date +%Y%m%d-%H%M%S)
 
@@ -659,7 +659,7 @@ if (!rawEntitiesPath) {
   process.exit(1);
 }
 
-const entityIndexPath = `${process.env.HOME}/.claude/skills/parser/entity-index.json`;
+const entityIndexPath = `${process.env.HOME}/.opencode/skills/Utilities/Parser/entity-index.json`;
 const entityIndex = JSON.parse(fs.readFileSync(entityIndexPath, 'utf-8'));
 
 const rawEntities = JSON.parse(fs.readFileSync(rawEntitiesPath, 'utf-8'));
@@ -675,7 +675,7 @@ fs.writeFileSync(entityIndexPath, JSON.stringify(entityIndex, null, 2));
 // Save processed articles
 processedArticles.forEach((article: any, index: number) => {
   const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
-  const filename = `${process.env.HOME}/.claude/skills/parser/output/${timestamp}_batch-${index + 1}.json`;
+  const filename = `${process.env.HOME}/.opencode/skills/Utilities/Parser/output/${timestamp}_batch-${index + 1}.json`;
   fs.writeFileSync(filename, JSON.stringify(article, null, 2));
   console.log(`Saved: ${filename}`);
 });
diff --git a/PAI-Install/engine/steps-migrate.ts b/PAI-Install/engine/steps-migrate.ts
index fa32fb71..bfae6955 100644
--- a/PAI-Install/engine/steps-migrate.ts
+++ b/PAI-Install/engine/steps-migrate.ts
@@ -5,7 +5,7 @@
  * 5-step migration flow with explicit user consent and backup.
  */
 
-import { existsSync, cpSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, cpSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import type { InstallState } from "./types";
@@ -224,18 +224,20 @@ exec bun "${join(paiDir, "PAI", "Tools", "pai.ts")}" "$@"
 	const aliasLine = isFish
 		? `alias pai 'bun ${escapedPath}'`
 		: `alias pai='bun ${escapedPath}'`;
-	const marker = "# PAI alias (v3)";
+	const startMarker = "# PAI shell setup — added by PAI installer";
+	const endMarker = "# end PAI shell setup";
 	
 	try {
 		let content = "";
 		if (existsSync(rcPath)) {
-			content = require("fs").readFileSync(rcPath, "utf-8");
+			content = readFileSync(rcPath, "utf-8");
+			content = content.replace(/\n?# PAI shell setup — added by PAI installer[\s\S]*?# end PAI shell setup\n?/g, "");
 			// Remove old PAI aliases
 			content = content.replace(/^#\s*(?:PAI|CORE)\s*alias.*\n.*alias pai=.*\n?/gm, "");
 			content = content.replace(/^alias pai=.*\n?/gm, "");
 			content = content.replace(/^alias pai\s+.*\n?/gm, "");
 		}
-		content = content.trimEnd() + `\n\n${marker}\n${aliasLine}\n`;
+		content = content.trimEnd() + `\n\n${startMarker}\n${aliasLine}\n${endMarker}\n`;
 		writeFileSync(rcPath, content);
 	} catch (err) {
 		console.warn("Could not update shell rc file:", err);
diff --git a/docs/specs/UPSTREAM-SYNC-v1.8.0-SPEC.md b/docs/specs/UPSTREAM-SYNC-v1.8.0-SPEC.md
index ea48bc68..6153f782 100644
--- a/docs/specs/UPSTREAM-SYNC-v1.8.0-SPEC.md
+++ b/docs/specs/UPSTREAM-SYNC-v1.8.0-SPEC.md
@@ -625,7 +625,7 @@ Two PRD creation mechanisms:
 - **Target:** `.opencode/plugins/lib/prd-template.ts`
 - **Changes:**
   - Replace `~/.claude/` → `~/.opencode/` in path construction
-  - Replace `CLAUDE.md` → `OPENCODE.md` references
+  - Replace `CLAUDE.md` → `AGENTS.md` references
   - Update file path constants to use `PAI_DIR`
 
 **Step 2: Create AutoWorkCreation Plugin Handler**