feat: align AGENTS.md loading across provider protocols (#225)

* feat: align AGENTS.md across provider protocols

* feat: show AGENTS.md instructions in dashboard

* fix: preserve AGENTS.md turn snapshots

Author: AkiKurisu

desktop/src/main/tests/workspaceSetup.test.ts

@@ -281,21 +281,14 @@ describe('shouldRouteWorkspaceThroughSetupBeforeAppServerStart', () => {
 })
 
 describe('workspace setup bootstrap import detection', () => {
-  it('detects nearest AGENTS.md and CLAUDE.md sources in AGENTS.md-first order', () => {
+  it('detects the nearest CLAUDE.md source when the workspace has no root AGENTS.md', () => {
     const workspace = createTempWorkspace()
     const child = join(workspace, 'packages', 'app')
     mkdirSync(child, { recursive: true })
-    writeFileSync(join(workspace, 'AGENTS.md'), 'root agents', 'utf8')
-    writeFileSync(join(child, 'AGENTS.md'), 'child agents', 'utf8')
+    mkdirSync(join(workspace, '.git'))
     writeFileSync(join(workspace, 'CLAUDE.md'), 'claude', 'utf8')
 
     expect(detectWorkspaceSetupBootstrapImportSources(child)).toEqual([
-      {
-        id: 'codex',
-        fileName: 'AGENTS.md',
-        path: join(child, 'AGENTS.md'),
-        relativePath: 'AGENTS.md'
-      },
       {
         id: 'claude',
         fileName: 'CLAUDE.md',
@@ -309,7 +302,7 @@ describe('workspace setup bootstrap import detection', () => {
     const workspace = createTempWorkspace()
     const userHome = createTempWorkspace()
     const userConfigPath = join(userHome, '.craft', 'config.json')
-    writeFileSync(join(workspace, 'AGENTS.md'), 'agents', 'utf8')
+    writeFileSync(join(workspace, 'CLAUDE.md'), 'claude', 'utf8')
     writeJson(userConfigPath, {
       Providers: {
         openai: {
@@ -325,8 +318,8 @@ describe('workspace setup bootstrap import detection', () => {
         status: 'needs-setup',
         bootstrapImportSources: [
           expect.objectContaining({
-            id: 'codex',
-            fileName: 'AGENTS.md'
+            id: 'claude',
+            fileName: 'CLAUDE.md'
           })
         ]
       })
@@ -341,19 +334,58 @@ describe('workspace setup bootstrap import detection', () => {
       .not.toHaveProperty('bootstrapImportSources')
   })
 
-  it('copies the selected source over .craft/AGENTS.md and records metadata', () => {
+  it('copies the selected source to root AGENTS.md and records metadata', () => {
     const workspace = createTempWorkspace()
     writeFileSync(join(workspace, 'CLAUDE.md'), '# Claude rules\n', 'utf8')
-    mkdirSync(join(workspace, '.craft'), { recursive: true })
-    writeFileSync(join(workspace, '.craft', 'AGENTS.md'), '# DotCraft template\n', 'utf8')
 
     expect(applyWorkspaceSetupBootstrapImport(workspace, 'claude')).toEqual({
       sourceId: 'claude',
       status: 'success'
     })
-    expect(readFileSync(join(workspace, '.craft', 'AGENTS.md'), 'utf8')).toBe('# Claude rules\n')
+    expect(readFileSync(join(workspace, 'AGENTS.md'), 'utf8')).toBe('# Claude rules\n')
     expect(existsSync(join(workspace, '.craft', 'imports', 'bootstrap-import.json'))).toBe(true)
   })
+
+  it('does not search above the nearest repository root or above an unversioned workspace', () => {
+    const parent = createTempWorkspace()
+    writeFileSync(join(parent, 'CLAUDE.md'), 'outside', 'utf8')
+    const repository = join(parent, 'repository')
+    const child = join(repository, 'packages', 'app')
+    mkdirSync(join(repository, '.git'), { recursive: true })
+    mkdirSync(child, { recursive: true })
+
+    expect(detectWorkspaceSetupBootstrapImportSources(child)).toEqual([])
+
+    const worktree = join(parent, 'worktree')
+    const worktreeChild = join(worktree, 'packages', 'app')
+    mkdirSync(worktreeChild, { recursive: true })
+    writeFileSync(join(worktree, '.git'), 'gitdir: ../repository/.git/worktrees/example', 'utf8')
+    expect(detectWorkspaceSetupBootstrapImportSources(worktreeChild)).toEqual([])
+
+    const unversioned = join(parent, 'unversioned')
+    mkdirSync(unversioned)
+    expect(detectWorkspaceSetupBootstrapImportSources(unversioned)).toEqual([])
+  })
+
+  it('does not offer or overwrite a root AGENTS.md', () => {
+    const workspace = createTempWorkspace()
+    writeFileSync(join(workspace, 'CLAUDE.md'), '# Claude rules\n', 'utf8')
+    writeFileSync(join(workspace, 'AGENTS.md'), '# Existing rules\n', 'utf8')
+
+    expect(detectWorkspaceSetupBootstrapImportSources(workspace)).toEqual([])
+    expect(applyWorkspaceSetupBootstrapImport(workspace, 'claude')).toMatchObject({ status: 'failed' })
+    expect(readFileSync(join(workspace, 'AGENTS.md'), 'utf8')).toBe('# Existing rules\n')
+  })
+
+  it('does not offer or copy beside a root AGENTS.override.md', () => {
+    const workspace = createTempWorkspace()
+    writeFileSync(join(workspace, 'CLAUDE.md'), '# Claude rules\n', 'utf8')
+    writeFileSync(join(workspace, 'AGENTS.override.md'), '# Override rules\n', 'utf8')
+
+    expect(detectWorkspaceSetupBootstrapImportSources(workspace)).toEqual([])
+    expect(applyWorkspaceSetupBootstrapImport(workspace, 'claude')).toMatchObject({ status: 'failed' })
+    expect(existsSync(join(workspace, 'AGENTS.md'))).toBe(false)
+  })
 })
 
 describe('createUniqueSetupProviderId', () => {

desktop/src/main/workspaceSetup.ts

@@ -1,5 +1,5 @@
 import { execFile, spawn } from 'child_process'
-import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs'
+import { constants, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
 import { dirname, join, relative, resolve } from 'path'
 import { resolveBinaryLocation } from './AppServerManager'
@@ -417,23 +417,32 @@ function isRegularFile(path: string): boolean {
   }
 }
 
-function findNearestSetupImportFile(
-  workspacePath: string,
-  fileName: 'AGENTS.md' | 'CLAUDE.md'
-): string | null {
-  let current = resolve(workspacePath)
+function findNearestSetupImportFile(workspacePath: string, fileName: 'CLAUDE.md'): string | null {
+  const workspaceRoot = resolve(workspacePath)
+  let repositoryRoot: string | null = null
+  let current = workspaceRoot
+
+  while (true) {
+    if (existsSync(join(current, '.git'))) {
+      repositoryRoot = current
+      break
+    }
+    const parent = dirname(current)
+    if (parent === current) break
+    current = parent
+  }
+
+  current = workspaceRoot
+  const searchRoot = repositoryRoot ?? workspaceRoot
 
   while (true) {
     const candidate = join(current, fileName)
     if (isRegularFile(candidate)) {
       return candidate
     }
 
-    const parent = dirname(current)
-    if (parent === current) {
-      return null
-    }
-    current = parent
+    if (current === searchRoot) return null
+    current = dirname(current)
   }
 }
 
@@ -448,19 +457,11 @@ export function detectWorkspaceSetupBootstrapImportSources(
   const trimmed = workspacePath.trim()
   if (!trimmed) return []
 
-  const agentsPath = findNearestSetupImportFile(trimmed, 'AGENTS.md')
+  if (existsSync(join(trimmed, 'AGENTS.md')) || existsSync(join(trimmed, 'AGENTS.override.md'))) return []
+
   const claudePath = findNearestSetupImportFile(trimmed, 'CLAUDE.md')
   const sources: WorkspaceSetupBootstrapImportSource[] = []
 
-  if (agentsPath) {
-    sources.push({
-      id: 'codex',
-      fileName: 'AGENTS.md',
-      path: agentsPath,
-      relativePath: sourceRelativePath(trimmed, agentsPath)
-    })
-  }
-
   if (claudePath) {
     sources.push({
       id: 'claude',
@@ -588,11 +589,14 @@ export function applyWorkspaceSetupBootstrapImport(
   }
 
   const craftPath = join(workspacePath, '.craft')
-  const destinationPath = join(craftPath, 'AGENTS.md')
+  const destinationPath = join(workspacePath, 'AGENTS.md')
+  const overridePath = join(workspacePath, 'AGENTS.override.md')
 
   try {
-    mkdirSync(craftPath, { recursive: true })
-    copyFileSync(source.path, destinationPath)
+    if (existsSync(overridePath)) {
+      throw new Error('Workspace root instructions already exist.')
+    }
+    copyFileSync(source.path, destinationPath, constants.COPYFILE_EXCL)
   } catch (error) {
     return {
       sourceId,
@@ -614,7 +618,7 @@ export function applyWorkspaceSetupBootstrapImport(
           path: source.path,
           relativePath: source.relativePath
         },
-        destination: '.craft/AGENTS.md',
+        destination: 'AGENTS.md',
         status: 'success'
       }, null, 2)}\n`,
       'utf8'
@@ -639,11 +643,7 @@ export function runWorkspaceSetup(
   settings: AppSettings
 ): Promise<WorkspaceSetupResult> {
   const binaryPath = resolveDesktopBinary(settings)
-  const args = [
-    'setup',
-    '--profile',
-    request.profile
-  ]
+  const args = ['setup']
 
   appendProviderArgs(args, request)
   if (request.setAsUserDefault) {