diff --git a/.agents/skills/setup_setup-repo/SKILL.md b/.agents/skills/setup_setup-repo/SKILL.md
new file mode 100644
index 0000000..fe826cd
--- /dev/null
+++ b/.agents/skills/setup_setup-repo/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: "setup_setup-repo"
+description: "Bootstrap this repository after clone by enabling git hooks and syncing generated skill mirrors. Use when user asks to set up the repo, bootstrap local tooling, or initialize mirrors/hooks for this clone."
+version: "1.0.0"
+---
+
+<!-- GENERATED from ai-artifacts/skills/shared/setup/setup-repo/SKILL.md. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->
+# Setup Repo
+
+Bootstraps this clone in one pass:
+
+1. Activates repo git hooks
+2. Syncs generated skill mirrors for Claude, Codex, and Copilot
+
+Implementation layout:
+
+- Canonical entrypoint: `ai-artifacts/skills/shared/setup/setup-repo/scripts/Invoke-SetupRepo.ps1`
+- Repo convenience wrapper: `scripts/setup-repo.ps1`
+
+## Applicability (capability contract)
+
+This skill needs shell + filesystem access in a local git checkout. In chat-only environments,
+provide the exact commands and explain what each command configures.
+
+## Default command
+
+```powershell
+pwsh scripts/setup-repo.ps1
+```
+
+## Common variants
+
+Project-local mirrors for one harness:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -Target Copilot -Scope Project
+```
+
+User-scope mirrors for all harnesses:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -Scope User
+```
+
+Bootstrap only missing generated mirrors (keeps existing generated files untouched):
+
+```powershell
+pwsh scripts/setup-repo.ps1 -IfMissing
+```
+
+Refresh generated mirrors without touching git hooks:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks
+```
+
+Check generated mirrors for drift:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks -Check
+pwsh scripts/setup-repo.ps1 -SkipHooks -Target Codex -Skill tdd -Check
+```
+
+Run only one phase:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks
+pwsh scripts/setup-repo.ps1 -SkipSkillSync
+```
+
+## Verify
+
+```powershell
+git config --get core.hooksPath
+Test-Path .claude/commands
+Test-Path .agents/skills
+Test-Path .github/skills
+pwsh scripts/setup-repo.ps1 -SkipHooks -Check
+```
+
+Expected:
+
+- `core.hooksPath` prints `.githooks`
+- mirror folders exist for selected targets
diff --git a/.agents/skills/setup_setup-repo/scripts/Invoke-SetupRepo.ps1 b/.agents/skills/setup_setup-repo/scripts/Invoke-SetupRepo.ps1
new file mode 100644
index 0000000..d1c0f05
--- /dev/null
+++ b/.agents/skills/setup_setup-repo/scripts/Invoke-SetupRepo.ps1
@@ -0,0 +1,584 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+
+  [ValidateSet('All', 'Claude', 'Codex', 'Copilot')]
+  [string]$Target = 'All',
+
+  [Alias('Scope')]
+  [ValidateSet('Project', 'User')]
+  [string]$MirrorScope = 'Project',
+
+  [string]$Skill = '',
+
+  [switch]$IfMissing,
+  [switch]$Check,
+  [switch]$SkipHooks,
+  [switch]$SkipSkillSync
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if ($Check -and $IfMissing) {
+  throw "-Check is read-only; do not combine it with -IfMissing."
+}
+
+function Get-UserHomePath {
+  if ($env:HOME) { return $env:HOME }
+  if ($env:USERPROFILE) { return $env:USERPROFILE }
+  throw "Cannot resolve user home path from HOME/USERPROFILE."
+}
+
+function Get-RelativePathText {
+  param(
+    [string]$BasePath,
+    [string]$TargetPath
+  )
+
+  $rel = [System.IO.Path]::GetRelativePath($BasePath, $TargetPath)
+  return $rel.TrimStart('\', '/')
+}
+
+function Get-MirrorRootPath {
+  param(
+    [ValidateSet('Claude', 'Codex', 'Copilot')]
+    [string]$TargetName,
+
+    [ValidateSet('Project', 'User')]
+    [string]$ScopeName,
+
+    [string]$ResolvedRepoRoot
+  )
+
+  switch ("$TargetName|$ScopeName") {
+    'Claude|Project' { return (Join-Path $ResolvedRepoRoot '.claude/commands') }
+    'Claude|User' { return (Join-Path (Get-UserHomePath) '.claude/commands') }
+    'Codex|Project' { return (Join-Path $ResolvedRepoRoot '.agents/skills') }
+    'Codex|User' { return (Join-Path (Get-UserHomePath) '.codex/skills') }
+    'Copilot|Project' { return (Join-Path $ResolvedRepoRoot '.github/skills') }
+    'Copilot|User' { return (Join-Path (Get-UserHomePath) '.copilot/skills') }
+    default { throw "Unsupported mirror target/scope combination: $TargetName / $ScopeName" }
+  }
+}
+
+function Get-SkillDirectories {
+  param(
+    [string]$SkillsRoot,
+    [string]$SkillName
+  )
+
+  $dirs = @(Get-ChildItem $SkillsRoot -Recurse -Filter 'SKILL.md' -File | ForEach-Object { $_.Directory })
+  if ($SkillName) {
+    $dirs = @($dirs | Where-Object { $_.Name -eq $SkillName })
+    if ($dirs.Count -eq 0) {
+      throw "No SKILL.md found for skill '$SkillName' under $SkillsRoot"
+    }
+  }
+  if ($dirs.Count -eq 0) {
+    throw "No SKILL.md files found under $SkillsRoot"
+  }
+  return $dirs
+}
+
+function Get-SyncReportEntry {
+  param(
+    [string]$Name,
+    [string]$Detail
+  )
+
+  return [PSCustomObject]@{
+    Name   = $Name
+    Detail = $Detail
+  }
+}
+
+function Write-SyncReport {
+  param(
+    [string]$Flavor,
+    [string]$TargetPath,
+    [object[]]$Entries,
+    [string]$Scope
+  )
+
+  $scopeText = if ($Scope) { " (scope=$Scope)" } else { '' }
+  Write-Output "Synced $Flavor -> $TargetPath$scopeText"
+
+  if (-not $Entries -or @($Entries).Count -eq 0) {
+    return
+  }
+
+  $nameWidth = ($Entries | ForEach-Object { $_.Name.Length } | Measure-Object -Maximum).Maximum
+  if (-not $nameWidth) { $nameWidth = 0 }
+
+  foreach ($entry in $Entries) {
+    Write-Output ("  {0}  {1}" -f $entry.Name.PadRight($nameWidth), $entry.Detail)
+  }
+}
+
+function Get-SkillResources {
+  param([string]$SkillDir)
+
+  return @(Get-ChildItem $SkillDir -Recurse -File |
+      Where-Object { $_.Name -notin @('SKILL.md', 'METADATA.md') })
+}
+
+function Copy-MirroredResources {
+  param(
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetBase
+  )
+
+  foreach ($res in $Resources) {
+    $rel = Get-RelativePathText -BasePath $SourceBase -TargetPath $res.FullName
+    $dest = Join-Path $TargetBase $rel
+    New-Item -ItemType Directory -Path (Split-Path $dest -Parent) -Force | Out-Null
+    Copy-Item $res.FullName $dest -Force
+  }
+}
+
+function Test-MirroredResourcesMatch {
+  param(
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetBase,
+    [switch]$ExcludeTargetSkillFile
+  )
+
+  foreach ($res in $Resources) {
+    $rel = Get-RelativePathText -BasePath $SourceBase -TargetPath $res.FullName
+    $dest = Join-Path $TargetBase $rel
+    if (-not (Test-Path $dest) -or
+      (Get-FileHash $res.FullName).Hash -ne (Get-FileHash $dest).Hash) {
+      return $false
+    }
+  }
+
+  $resourceCount = @($Resources).Count
+  $mirroredCount = if (Test-Path $TargetBase) {
+    @(Get-ChildItem $TargetBase -Recurse -File |
+        Where-Object { -not $ExcludeTargetSkillFile -or $_.Name -ne 'SKILL.md' }).Count
+  }
+  else {
+    0
+  }
+
+  return $mirroredCount -eq $resourceCount
+}
+
+function Get-SkillMirrorState {
+  param(
+    [string]$TargetSkillPath,
+    [string]$ExpectedSkill,
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetResourceBase,
+    [switch]$ExcludeTargetSkillFile
+  )
+
+  if (-not (Test-Path $TargetSkillPath)) { return 'MISSING' }
+  if ((Get-Content $TargetSkillPath -Raw) -cne $ExpectedSkill) { return 'STALE' }
+
+  if (-not (Test-MirroredResourcesMatch -Resources $Resources -SourceBase $SourceBase -TargetBase $TargetResourceBase -ExcludeTargetSkillFile:$ExcludeTargetSkillFile)) {
+    return 'STALE'
+  }
+
+  return 'UP-TO-DATE'
+}
+
+function Convert-ResourceLinks {
+  param(
+    [string]$Body,
+    [string]$Name,
+    [string[]]$ResourceRelPaths
+  )
+
+  foreach ($path in $ResourceRelPaths) {
+    $Body = $Body.Replace("](./$path)", "]($Name/$path)")
+    $Body = $Body.Replace("]($path)", "]($Name/$path)")
+    $Body = $Body -replace ("(?<=@)" + [regex]::Escape($path) + "\b"), "$Name/$path"
+  }
+  return $Body
+}
+
+function ConvertTo-YamlScalar {
+  param([string]$Value)
+
+  if ($null -eq $Value) { return '""' }
+  return '"' + ($Value -replace '\\', '\\' -replace '"', '\"') + '"'
+}
+
+function Get-FrontmatterValue {
+  param(
+    [string]$Document,
+    [string]$Key
+  )
+
+  if ($Document -notmatch "(?s)\A---\r?\n(.*?)\r?\n---\r?\n") { return $null }
+  $frontmatter = $Matches[1]
+  $match = [regex]::Match($frontmatter, "(?m)^$([regex]::Escape($Key)):\s*(.*)$")
+  if (-not $match.Success) { return $null }
+
+  $value = $match.Groups[1].Value.Trim()
+  if (($value.StartsWith('"') -and $value.EndsWith('"')) -or
+    ($value.StartsWith("'") -and $value.EndsWith("'"))) {
+    $value = $value.Substring(1, $value.Length - 2)
+  }
+  return $value
+}
+
+function Get-SkillBody {
+  param([string]$Document)
+
+  if ($Document -match "(?s)\A---\r?\n.*?\r?\n---\r?\n(.*)\z") {
+    return $Matches[1].TrimStart()
+  }
+  return $Document.TrimStart()
+}
+
+function ConvertTo-CodexSkill {
+  param(
+    [string]$SourceDocument,
+    [string]$CodexName,
+    [string]$SourceRelPath
+  )
+
+  $description = Get-FrontmatterValue -Document $SourceDocument -Key 'description'
+  if (-not $description) { $description = "Repo skill mirrored from $SourceRelPath." }
+  $version = Get-FrontmatterValue -Document $SourceDocument -Key 'version'
+
+  $body = Get-SkillBody -Document $SourceDocument
+  $frontmatter = @(
+    '---'
+    "name: $(ConvertTo-YamlScalar $CodexName)"
+    "description: $(ConvertTo-YamlScalar $description)"
+    $(if ($version) { "version: $(ConvertTo-YamlScalar $version)" })
+    '---'
+    ''
+    "<!-- GENERATED from $SourceRelPath. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->"
+    ''
+  ) -join "`n"
+
+  return $frontmatter + $body
+}
+
+function ConvertTo-CopilotSkill {
+  param(
+    [string]$SourceDocument,
+    [string]$SkillName,
+    [string]$SourceRelPath
+  )
+
+  $description = Get-FrontmatterValue -Document $SourceDocument -Key 'description'
+  if (-not $description) { $description = "Repo skill mirrored from $SourceRelPath." }
+  $version = Get-FrontmatterValue -Document $SourceDocument -Key 'version'
+
+  $body = Get-SkillBody -Document $SourceDocument
+  $frontmatter = @(
+    '---'
+    "name: $(ConvertTo-YamlScalar $SkillName)"
+    "description: $(ConvertTo-YamlScalar $description)"
+    $(if ($version) { "version: $(ConvertTo-YamlScalar $version)" })
+    '---'
+    ''
+    "<!-- GENERATED from $SourceRelPath. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->"
+    ''
+  ) -join "`n"
+
+  return $frontmatter + $body
+}
+
+function Invoke-InstallGitHooksInternal {
+  param([string]$ResolvedRepoRoot)
+
+  $hooksDir = Join-Path $ResolvedRepoRoot '.githooks'
+  if (Test-Path $hooksDir) {
+    $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+    Get-ChildItem -Path $hooksDir -File | ForEach-Object {
+      $raw = [System.IO.File]::ReadAllText($_.FullName)
+      $normalized = $raw -replace "`r`n", "`n" -replace "`r", "`n"
+      if ($normalized -ne $raw) {
+        [System.IO.File]::WriteAllText($_.FullName, $normalized, $utf8NoBom)
+        Write-Output "Normalized LF line endings: $($_.Name)"
+      }
+    }
+  }
+
+  Write-Output '== Git hooks =='
+  git config core.hooksPath .githooks
+  Write-Output 'Configured core.hooksPath to .githooks'
+
+  if ($IsLinux -or $IsMacOS) {
+    $preCommit = Join-Path $hooksDir 'pre-commit'
+    if (Test-Path $preCommit) {
+      & chmod +x $preCommit
+    }
+  }
+
+  Write-Output 'Git hooks are now active for this clone.'
+}
+
+function Sync-ClaudeSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck
+  )
+
+  $commandsRoot = Get-MirrorRootPath -TargetName 'Claude' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  Write-Output ''
+  Write-Output '== Claude Code skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $name = $dir.Name
+    $group = $dir.Parent.Name
+    $groupDir = Join-Path $commandsRoot $group
+    $targetMd = Join-Path $groupDir "$name.md"
+    $targetRes = Join-Path $groupDir $name
+
+    if ($OnlyIfMissing -and (Test-Path $targetMd)) {
+      $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+    $resRelPaths = $resources | ForEach-Object {
+      (Get-RelativePathText -BasePath $dir.FullName -TargetPath $_.FullName).Replace('\\', '/')
+    }
+
+    $body = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    if ($resRelPaths) {
+      $body = Convert-ResourceLinks -Body $body -Name $name -ResourceRelPaths $resRelPaths
+    }
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetMd -ExpectedSkill $body -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetRes
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetMd) { Remove-Item $targetMd -Force }
+    if (Test-Path $targetRes) { Remove-Item $targetRes -Recurse -Force }
+    New-Item -ItemType Directory -Path $groupDir -Force | Out-Null
+    Set-Content -Path $targetMd -Value $body -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetRes
+
+    $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  Write-SyncReport -Flavor 'Claude skills' -TargetPath $commandsRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+function Sync-CodexSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck,
+    [string]$SelectedSkill
+  )
+
+  $agentsRoot = Get-MirrorRootPath -TargetName 'Codex' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $expectedSkillNames = [System.Collections.Generic.HashSet[string]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  if (-not $ReadOnlyCheck -and -not $OnlyIfMissing -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
+    Remove-Item $agentsRoot -Recurse -Force
+  }
+
+  Write-Output ''
+  Write-Output '== Codex skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $sourceName = $dir.Name
+    $group = $dir.Parent.Name
+    $codexName = "$group`_$sourceName"
+    [void]$expectedSkillNames.Add($codexName)
+    $targetDir = Join-Path $agentsRoot $codexName
+    $targetSkill = Join-Path $targetDir 'SKILL.md'
+
+    if ($OnlyIfMissing -and (Test-Path $targetSkill)) {
+      $entries.Add((Get-SyncReportEntry -Name $codexName -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $sourceRelPath = "ai-artifacts/skills/shared/$group/$sourceName/SKILL.md"
+    $sourceDocument = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    $expectedSkill = ConvertTo-CodexSkill -SourceDocument $sourceDocument -CodexName $codexName -SourceRelPath $sourceRelPath
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetSkill -ExpectedSkill $expectedSkill -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetDir -ExcludeTargetSkillFile
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name $codexName -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
+    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+    Set-Content -Path $targetSkill -Value $expectedSkill -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetDir
+
+    $entries.Add((Get-SyncReportEntry -Name $codexName -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  if ($ReadOnlyCheck -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
+    foreach ($dir in Get-ChildItem $agentsRoot -Directory) {
+      if (-not $expectedSkillNames.Contains($dir.Name)) {
+        $driftCount++
+        $entries.Add((Get-SyncReportEntry -Name $dir.Name -Detail 'EXTRA'))
+      }
+    }
+  }
+
+  Write-SyncReport -Flavor 'Codex skills' -TargetPath $agentsRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+function Sync-CopilotSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck,
+    [string]$SelectedSkill
+  )
+
+  $skillsMirrorRoot = Get-MirrorRootPath -TargetName 'Copilot' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $expectedSkillNames = [System.Collections.Generic.HashSet[string]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  if (-not $ReadOnlyCheck -and -not $OnlyIfMissing -and -not $SelectedSkill -and (Test-Path $skillsMirrorRoot)) {
+    Remove-Item $skillsMirrorRoot -Recurse -Force
+  }
+
+  Write-Output ''
+  Write-Output '== Copilot skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $sourceName = $dir.Name
+    $group = $dir.Parent.Name
+    $copilotSkillName = "$group`_$sourceName"
+    [void]$expectedSkillNames.Add($copilotSkillName)
+    $targetDir = Join-Path $skillsMirrorRoot $copilotSkillName
+    $targetSkill = Join-Path $targetDir 'SKILL.md'
+
+    if ($OnlyIfMissing -and (Test-Path $targetSkill)) {
+      $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $sourceRelPath = "ai-artifacts/skills/shared/$group/$sourceName/SKILL.md"
+    $sourceDocument = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    $expectedSkill = ConvertTo-CopilotSkill -SourceDocument $sourceDocument -SkillName $copilotSkillName -SourceRelPath $sourceRelPath
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetSkill -ExpectedSkill $expectedSkill -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetDir -ExcludeTargetSkillFile
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
+    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+    Set-Content -Path $targetSkill -Value $expectedSkill -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetDir
+
+    $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  if ($ReadOnlyCheck -and -not $SelectedSkill -and (Test-Path $skillsMirrorRoot)) {
+    foreach ($dir in Get-ChildItem $skillsMirrorRoot -Directory) {
+      $skillFile = Join-Path $dir.FullName 'SKILL.md'
+      if (-not (Test-Path $skillFile)) { continue }
+      if ((Get-Content $skillFile -Raw) -notmatch '<!-- GENERATED from ai-artifacts/skills/shared/') {
+        continue
+      }
+      if (-not $expectedSkillNames.Contains($dir.Name)) {
+        $driftCount++
+        $entries.Add((Get-SyncReportEntry -Name $dir.Name -Detail 'EXTRA'))
+      }
+    }
+  }
+
+  Write-SyncReport -Flavor 'Copilot skills' -TargetPath $skillsMirrorRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+if ([string]::IsNullOrWhiteSpace($RepoRoot)) {
+  $RepoRoot = (& git -C $PSScriptRoot rev-parse --show-toplevel 2>$null)
+  if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($RepoRoot)) {
+    throw "Unable to determine repo root. Run from inside the repo or pass -RepoRoot."
+  }
+}
+
+$RepoRoot = (Resolve-Path $RepoRoot).Path
+$skillsRoot = Join-Path $RepoRoot 'ai-artifacts/skills/shared'
+$skillDirs = Get-SkillDirectories -SkillsRoot $skillsRoot -SkillName $Skill
+
+if (-not $SkipHooks) {
+  Invoke-InstallGitHooksInternal -ResolvedRepoRoot $RepoRoot
+}
+
+if (-not $SkipSkillSync) {
+  $exitCode = 0
+  switch ($Target) {
+    'All' {
+      Sync-ClaudeSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+      Sync-CodexSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+      Sync-CopilotSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+    }
+    'Claude' {
+      Sync-ClaudeSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
+      $exitCode = $script:LastSyncExitCode
+    }
+    'Codex' {
+      Sync-CodexSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = $script:LastSyncExitCode
+    }
+    'Copilot' {
+      Sync-CopilotSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = $script:LastSyncExitCode
+    }
+  }
+
+  if ($Check) {
+    if ($exitCode) {
+      Write-Output 'Generated mirrors are stale or missing. Rebuild with: pwsh scripts/setup-repo.ps1 -SkipHooks'
+      exit 1
+    }
+
+    Write-Output 'Generated mirrors are up to date.'
+  }
+}
+
+Write-Output "Repository setup completed."
diff --git a/.agents/skills/setup_setup-repo/tests/test_setup_repo.py b/.agents/skills/setup_setup-repo/tests/test_setup_repo.py
new file mode 100644
index 0000000..c2baf49
--- /dev/null
+++ b/.agents/skills/setup_setup-repo/tests/test_setup_repo.py
@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+SCRIPT_PATH = (
+    Path(__file__).resolve().parent.parent / "scripts" / "Invoke-SetupRepo.ps1"
+)
+
+
+def _pwsh_executable() -> str:
+    pwsh = shutil.which("pwsh")
+    if pwsh:
+        return pwsh
+    pytest.skip("pwsh is required for setup-repo tests")
+
+
+def _run_setup_repo(repo_root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    command = [
+        _pwsh_executable(),
+        "-NoProfile",
+        "-File",
+        str(SCRIPT_PATH),
+        "-RepoRoot",
+        str(repo_root),
+        *args,
+    ]
+    return subprocess.run(
+        command,
+        cwd=repo_root,
+        check=False,
+        text=True,
+        capture_output=True,
+    )
+
+
+def _write_minimal_skill(repo_root: Path, group: str, name: str) -> Path:
+    skill_dir = repo_root / "ai-artifacts" / "skills" / "shared" / group / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(
+        """---
+name: \"setup-repo\"
+description: \"Bootstrap repo\"
+version: \"1.0.0\"
+---
+
+# Setup Repo
+
+Body.
+""",
+        encoding="utf-8",
+    )
+    return skill_dir
+
+
+def _init_git_repo(path: Path) -> None:
+    git = shutil.which("git")
+    if not git:
+        pytest.skip("git is required for hook setup test")
+    subprocess.run([git, "init"], cwd=path, check=True, capture_output=True, text=True)
+
+
+def test_codex_mirror_uses_group_underscore_name(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    result = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks")
+
+    assert result.returncode == 0, result.stderr
+    mirror_root = tmp_path / ".agents" / "skills"
+    assert (mirror_root / "setup_setup-repo" / "SKILL.md").exists()
+    assert not (mirror_root / "setup-setup-repo").exists()
+
+
+def test_copilot_mirror_uses_group_underscore_name(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    result = _run_setup_repo(tmp_path, "-Target", "Copilot", "-SkipHooks")
+
+    assert result.returncode == 0, result.stderr
+    mirror_root = tmp_path / ".github" / "skills"
+    assert (mirror_root / "setup_setup-repo" / "SKILL.md").exists()
+    assert not (mirror_root / "setup-setup-repo").exists()
+
+
+def test_if_missing_preserves_existing_codex_skill_file(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    first = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks")
+    assert first.returncode == 0, first.stderr
+
+    target_skill = tmp_path / ".agents" / "skills" / "setup_setup-repo" / "SKILL.md"
+    target_skill.write_text("sentinel", encoding="utf-8")
+
+    second = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks", "-IfMissing")
+
+    assert second.returncode == 0, second.stderr
+    assert target_skill.read_text(encoding="utf-8") == "sentinel"
+
+
+def test_hook_setup_configures_git_hooks_path(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+    _init_git_repo(tmp_path)
+
+    hooks_dir = tmp_path / ".githooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    (hooks_dir / "pre-commit").write_text(
+        "#!/usr/bin/env sh\r\necho ok\r\n", encoding="utf-8"
+    )
+
+    result = _run_setup_repo(tmp_path, "-SkipSkillSync")
+
+    assert result.returncode == 0, result.stderr
+    git = shutil.which("git")
+    config = subprocess.run(
+        [git, "config", "core.hooksPath"],
+        cwd=tmp_path,
+        check=True,
+        text=True,
+        capture_output=True,
+    )
+    assert config.stdout.strip() == ".githooks"
diff --git a/.claude/commands/setup/setup-repo.md b/.claude/commands/setup/setup-repo.md
new file mode 100644
index 0000000..ec46f5f
--- /dev/null
+++ b/.claude/commands/setup/setup-repo.md
@@ -0,0 +1,83 @@
+---
+name: setup-repo
+version: 1.0.0
+description: Bootstrap this repository after clone by enabling git hooks and syncing generated skill mirrors. Use when user asks to set up the repo, bootstrap local tooling, or initialize mirrors/hooks for this clone.
+---
+
+# Setup Repo
+
+Bootstraps this clone in one pass:
+
+1. Activates repo git hooks
+2. Syncs generated skill mirrors for Claude, Codex, and Copilot
+
+Implementation layout:
+
+- Canonical entrypoint: `ai-artifacts/skills/shared/setup/setup-repo/scripts/Invoke-SetupRepo.ps1`
+- Repo convenience wrapper: `scripts/setup-repo.ps1`
+
+## Applicability (capability contract)
+
+This skill needs shell + filesystem access in a local git checkout. In chat-only environments,
+provide the exact commands and explain what each command configures.
+
+## Default command
+
+```powershell
+pwsh scripts/setup-repo.ps1
+```
+
+## Common variants
+
+Project-local mirrors for one harness:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -Target Copilot -Scope Project
+```
+
+User-scope mirrors for all harnesses:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -Scope User
+```
+
+Bootstrap only missing generated mirrors (keeps existing generated files untouched):
+
+```powershell
+pwsh scripts/setup-repo.ps1 -IfMissing
+```
+
+Refresh generated mirrors without touching git hooks:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks
+```
+
+Check generated mirrors for drift:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks -Check
+pwsh scripts/setup-repo.ps1 -SkipHooks -Target Codex -Skill tdd -Check
+```
+
+Run only one phase:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks
+pwsh scripts/setup-repo.ps1 -SkipSkillSync
+```
+
+## Verify
+
+```powershell
+git config --get core.hooksPath
+Test-Path .claude/commands
+Test-Path .agents/skills
+Test-Path .github/skills
+pwsh scripts/setup-repo.ps1 -SkipHooks -Check
+```
+
+Expected:
+
+- `core.hooksPath` prints `.githooks`
+- mirror folders exist for selected targets
diff --git a/.claude/commands/setup/setup-repo/scripts/Invoke-SetupRepo.ps1 b/.claude/commands/setup/setup-repo/scripts/Invoke-SetupRepo.ps1
new file mode 100644
index 0000000..d1c0f05
--- /dev/null
+++ b/.claude/commands/setup/setup-repo/scripts/Invoke-SetupRepo.ps1
@@ -0,0 +1,584 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+
+  [ValidateSet('All', 'Claude', 'Codex', 'Copilot')]
+  [string]$Target = 'All',
+
+  [Alias('Scope')]
+  [ValidateSet('Project', 'User')]
+  [string]$MirrorScope = 'Project',
+
+  [string]$Skill = '',
+
+  [switch]$IfMissing,
+  [switch]$Check,
+  [switch]$SkipHooks,
+  [switch]$SkipSkillSync
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if ($Check -and $IfMissing) {
+  throw "-Check is read-only; do not combine it with -IfMissing."
+}
+
+function Get-UserHomePath {
+  if ($env:HOME) { return $env:HOME }
+  if ($env:USERPROFILE) { return $env:USERPROFILE }
+  throw "Cannot resolve user home path from HOME/USERPROFILE."
+}
+
+function Get-RelativePathText {
+  param(
+    [string]$BasePath,
+    [string]$TargetPath
+  )
+
+  $rel = [System.IO.Path]::GetRelativePath($BasePath, $TargetPath)
+  return $rel.TrimStart('\', '/')
+}
+
+function Get-MirrorRootPath {
+  param(
+    [ValidateSet('Claude', 'Codex', 'Copilot')]
+    [string]$TargetName,
+
+    [ValidateSet('Project', 'User')]
+    [string]$ScopeName,
+
+    [string]$ResolvedRepoRoot
+  )
+
+  switch ("$TargetName|$ScopeName") {
+    'Claude|Project' { return (Join-Path $ResolvedRepoRoot '.claude/commands') }
+    'Claude|User' { return (Join-Path (Get-UserHomePath) '.claude/commands') }
+    'Codex|Project' { return (Join-Path $ResolvedRepoRoot '.agents/skills') }
+    'Codex|User' { return (Join-Path (Get-UserHomePath) '.codex/skills') }
+    'Copilot|Project' { return (Join-Path $ResolvedRepoRoot '.github/skills') }
+    'Copilot|User' { return (Join-Path (Get-UserHomePath) '.copilot/skills') }
+    default { throw "Unsupported mirror target/scope combination: $TargetName / $ScopeName" }
+  }
+}
+
+function Get-SkillDirectories {
+  param(
+    [string]$SkillsRoot,
+    [string]$SkillName
+  )
+
+  $dirs = @(Get-ChildItem $SkillsRoot -Recurse -Filter 'SKILL.md' -File | ForEach-Object { $_.Directory })
+  if ($SkillName) {
+    $dirs = @($dirs | Where-Object { $_.Name -eq $SkillName })
+    if ($dirs.Count -eq 0) {
+      throw "No SKILL.md found for skill '$SkillName' under $SkillsRoot"
+    }
+  }
+  if ($dirs.Count -eq 0) {
+    throw "No SKILL.md files found under $SkillsRoot"
+  }
+  return $dirs
+}
+
+function Get-SyncReportEntry {
+  param(
+    [string]$Name,
+    [string]$Detail
+  )
+
+  return [PSCustomObject]@{
+    Name   = $Name
+    Detail = $Detail
+  }
+}
+
+function Write-SyncReport {
+  param(
+    [string]$Flavor,
+    [string]$TargetPath,
+    [object[]]$Entries,
+    [string]$Scope
+  )
+
+  $scopeText = if ($Scope) { " (scope=$Scope)" } else { '' }
+  Write-Output "Synced $Flavor -> $TargetPath$scopeText"
+
+  if (-not $Entries -or @($Entries).Count -eq 0) {
+    return
+  }
+
+  $nameWidth = ($Entries | ForEach-Object { $_.Name.Length } | Measure-Object -Maximum).Maximum
+  if (-not $nameWidth) { $nameWidth = 0 }
+
+  foreach ($entry in $Entries) {
+    Write-Output ("  {0}  {1}" -f $entry.Name.PadRight($nameWidth), $entry.Detail)
+  }
+}
+
+function Get-SkillResources {
+  param([string]$SkillDir)
+
+  return @(Get-ChildItem $SkillDir -Recurse -File |
+      Where-Object { $_.Name -notin @('SKILL.md', 'METADATA.md') })
+}
+
+function Copy-MirroredResources {
+  param(
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetBase
+  )
+
+  foreach ($res in $Resources) {
+    $rel = Get-RelativePathText -BasePath $SourceBase -TargetPath $res.FullName
+    $dest = Join-Path $TargetBase $rel
+    New-Item -ItemType Directory -Path (Split-Path $dest -Parent) -Force | Out-Null
+    Copy-Item $res.FullName $dest -Force
+  }
+}
+
+function Test-MirroredResourcesMatch {
+  param(
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetBase,
+    [switch]$ExcludeTargetSkillFile
+  )
+
+  foreach ($res in $Resources) {
+    $rel = Get-RelativePathText -BasePath $SourceBase -TargetPath $res.FullName
+    $dest = Join-Path $TargetBase $rel
+    if (-not (Test-Path $dest) -or
+      (Get-FileHash $res.FullName).Hash -ne (Get-FileHash $dest).Hash) {
+      return $false
+    }
+  }
+
+  $resourceCount = @($Resources).Count
+  $mirroredCount = if (Test-Path $TargetBase) {
+    @(Get-ChildItem $TargetBase -Recurse -File |
+        Where-Object { -not $ExcludeTargetSkillFile -or $_.Name -ne 'SKILL.md' }).Count
+  }
+  else {
+    0
+  }
+
+  return $mirroredCount -eq $resourceCount
+}
+
+function Get-SkillMirrorState {
+  param(
+    [string]$TargetSkillPath,
+    [string]$ExpectedSkill,
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetResourceBase,
+    [switch]$ExcludeTargetSkillFile
+  )
+
+  if (-not (Test-Path $TargetSkillPath)) { return 'MISSING' }
+  if ((Get-Content $TargetSkillPath -Raw) -cne $ExpectedSkill) { return 'STALE' }
+
+  if (-not (Test-MirroredResourcesMatch -Resources $Resources -SourceBase $SourceBase -TargetBase $TargetResourceBase -ExcludeTargetSkillFile:$ExcludeTargetSkillFile)) {
+    return 'STALE'
+  }
+
+  return 'UP-TO-DATE'
+}
+
+function Convert-ResourceLinks {
+  param(
+    [string]$Body,
+    [string]$Name,
+    [string[]]$ResourceRelPaths
+  )
+
+  foreach ($path in $ResourceRelPaths) {
+    $Body = $Body.Replace("](./$path)", "]($Name/$path)")
+    $Body = $Body.Replace("]($path)", "]($Name/$path)")
+    $Body = $Body -replace ("(?<=@)" + [regex]::Escape($path) + "\b"), "$Name/$path"
+  }
+  return $Body
+}
+
+function ConvertTo-YamlScalar {
+  param([string]$Value)
+
+  if ($null -eq $Value) { return '""' }
+  return '"' + ($Value -replace '\\', '\\' -replace '"', '\"') + '"'
+}
+
+function Get-FrontmatterValue {
+  param(
+    [string]$Document,
+    [string]$Key
+  )
+
+  if ($Document -notmatch "(?s)\A---\r?\n(.*?)\r?\n---\r?\n") { return $null }
+  $frontmatter = $Matches[1]
+  $match = [regex]::Match($frontmatter, "(?m)^$([regex]::Escape($Key)):\s*(.*)$")
+  if (-not $match.Success) { return $null }
+
+  $value = $match.Groups[1].Value.Trim()
+  if (($value.StartsWith('"') -and $value.EndsWith('"')) -or
+    ($value.StartsWith("'") -and $value.EndsWith("'"))) {
+    $value = $value.Substring(1, $value.Length - 2)
+  }
+  return $value
+}
+
+function Get-SkillBody {
+  param([string]$Document)
+
+  if ($Document -match "(?s)\A---\r?\n.*?\r?\n---\r?\n(.*)\z") {
+    return $Matches[1].TrimStart()
+  }
+  return $Document.TrimStart()
+}
+
+function ConvertTo-CodexSkill {
+  param(
+    [string]$SourceDocument,
+    [string]$CodexName,
+    [string]$SourceRelPath
+  )
+
+  $description = Get-FrontmatterValue -Document $SourceDocument -Key 'description'
+  if (-not $description) { $description = "Repo skill mirrored from $SourceRelPath." }
+  $version = Get-FrontmatterValue -Document $SourceDocument -Key 'version'
+
+  $body = Get-SkillBody -Document $SourceDocument
+  $frontmatter = @(
+    '---'
+    "name: $(ConvertTo-YamlScalar $CodexName)"
+    "description: $(ConvertTo-YamlScalar $description)"
+    $(if ($version) { "version: $(ConvertTo-YamlScalar $version)" })
+    '---'
+    ''
+    "<!-- GENERATED from $SourceRelPath. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->"
+    ''
+  ) -join "`n"
+
+  return $frontmatter + $body
+}
+
+function ConvertTo-CopilotSkill {
+  param(
+    [string]$SourceDocument,
+    [string]$SkillName,
+    [string]$SourceRelPath
+  )
+
+  $description = Get-FrontmatterValue -Document $SourceDocument -Key 'description'
+  if (-not $description) { $description = "Repo skill mirrored from $SourceRelPath." }
+  $version = Get-FrontmatterValue -Document $SourceDocument -Key 'version'
+
+  $body = Get-SkillBody -Document $SourceDocument
+  $frontmatter = @(
+    '---'
+    "name: $(ConvertTo-YamlScalar $SkillName)"
+    "description: $(ConvertTo-YamlScalar $description)"
+    $(if ($version) { "version: $(ConvertTo-YamlScalar $version)" })
+    '---'
+    ''
+    "<!-- GENERATED from $SourceRelPath. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->"
+    ''
+  ) -join "`n"
+
+  return $frontmatter + $body
+}
+
+function Invoke-InstallGitHooksInternal {
+  param([string]$ResolvedRepoRoot)
+
+  $hooksDir = Join-Path $ResolvedRepoRoot '.githooks'
+  if (Test-Path $hooksDir) {
+    $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+    Get-ChildItem -Path $hooksDir -File | ForEach-Object {
+      $raw = [System.IO.File]::ReadAllText($_.FullName)
+      $normalized = $raw -replace "`r`n", "`n" -replace "`r", "`n"
+      if ($normalized -ne $raw) {
+        [System.IO.File]::WriteAllText($_.FullName, $normalized, $utf8NoBom)
+        Write-Output "Normalized LF line endings: $($_.Name)"
+      }
+    }
+  }
+
+  Write-Output '== Git hooks =='
+  git config core.hooksPath .githooks
+  Write-Output 'Configured core.hooksPath to .githooks'
+
+  if ($IsLinux -or $IsMacOS) {
+    $preCommit = Join-Path $hooksDir 'pre-commit'
+    if (Test-Path $preCommit) {
+      & chmod +x $preCommit
+    }
+  }
+
+  Write-Output 'Git hooks are now active for this clone.'
+}
+
+function Sync-ClaudeSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck
+  )
+
+  $commandsRoot = Get-MirrorRootPath -TargetName 'Claude' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  Write-Output ''
+  Write-Output '== Claude Code skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $name = $dir.Name
+    $group = $dir.Parent.Name
+    $groupDir = Join-Path $commandsRoot $group
+    $targetMd = Join-Path $groupDir "$name.md"
+    $targetRes = Join-Path $groupDir $name
+
+    if ($OnlyIfMissing -and (Test-Path $targetMd)) {
+      $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+    $resRelPaths = $resources | ForEach-Object {
+      (Get-RelativePathText -BasePath $dir.FullName -TargetPath $_.FullName).Replace('\\', '/')
+    }
+
+    $body = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    if ($resRelPaths) {
+      $body = Convert-ResourceLinks -Body $body -Name $name -ResourceRelPaths $resRelPaths
+    }
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetMd -ExpectedSkill $body -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetRes
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetMd) { Remove-Item $targetMd -Force }
+    if (Test-Path $targetRes) { Remove-Item $targetRes -Recurse -Force }
+    New-Item -ItemType Directory -Path $groupDir -Force | Out-Null
+    Set-Content -Path $targetMd -Value $body -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetRes
+
+    $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  Write-SyncReport -Flavor 'Claude skills' -TargetPath $commandsRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+function Sync-CodexSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck,
+    [string]$SelectedSkill
+  )
+
+  $agentsRoot = Get-MirrorRootPath -TargetName 'Codex' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $expectedSkillNames = [System.Collections.Generic.HashSet[string]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  if (-not $ReadOnlyCheck -and -not $OnlyIfMissing -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
+    Remove-Item $agentsRoot -Recurse -Force
+  }
+
+  Write-Output ''
+  Write-Output '== Codex skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $sourceName = $dir.Name
+    $group = $dir.Parent.Name
+    $codexName = "$group`_$sourceName"
+    [void]$expectedSkillNames.Add($codexName)
+    $targetDir = Join-Path $agentsRoot $codexName
+    $targetSkill = Join-Path $targetDir 'SKILL.md'
+
+    if ($OnlyIfMissing -and (Test-Path $targetSkill)) {
+      $entries.Add((Get-SyncReportEntry -Name $codexName -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $sourceRelPath = "ai-artifacts/skills/shared/$group/$sourceName/SKILL.md"
+    $sourceDocument = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    $expectedSkill = ConvertTo-CodexSkill -SourceDocument $sourceDocument -CodexName $codexName -SourceRelPath $sourceRelPath
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetSkill -ExpectedSkill $expectedSkill -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetDir -ExcludeTargetSkillFile
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name $codexName -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
+    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+    Set-Content -Path $targetSkill -Value $expectedSkill -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetDir
+
+    $entries.Add((Get-SyncReportEntry -Name $codexName -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  if ($ReadOnlyCheck -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
+    foreach ($dir in Get-ChildItem $agentsRoot -Directory) {
+      if (-not $expectedSkillNames.Contains($dir.Name)) {
+        $driftCount++
+        $entries.Add((Get-SyncReportEntry -Name $dir.Name -Detail 'EXTRA'))
+      }
+    }
+  }
+
+  Write-SyncReport -Flavor 'Codex skills' -TargetPath $agentsRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+function Sync-CopilotSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck,
+    [string]$SelectedSkill
+  )
+
+  $skillsMirrorRoot = Get-MirrorRootPath -TargetName 'Copilot' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $expectedSkillNames = [System.Collections.Generic.HashSet[string]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  if (-not $ReadOnlyCheck -and -not $OnlyIfMissing -and -not $SelectedSkill -and (Test-Path $skillsMirrorRoot)) {
+    Remove-Item $skillsMirrorRoot -Recurse -Force
+  }
+
+  Write-Output ''
+  Write-Output '== Copilot skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $sourceName = $dir.Name
+    $group = $dir.Parent.Name
+    $copilotSkillName = "$group`_$sourceName"
+    [void]$expectedSkillNames.Add($copilotSkillName)
+    $targetDir = Join-Path $skillsMirrorRoot $copilotSkillName
+    $targetSkill = Join-Path $targetDir 'SKILL.md'
+
+    if ($OnlyIfMissing -and (Test-Path $targetSkill)) {
+      $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $sourceRelPath = "ai-artifacts/skills/shared/$group/$sourceName/SKILL.md"
+    $sourceDocument = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    $expectedSkill = ConvertTo-CopilotSkill -SourceDocument $sourceDocument -SkillName $copilotSkillName -SourceRelPath $sourceRelPath
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetSkill -ExpectedSkill $expectedSkill -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetDir -ExcludeTargetSkillFile
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
+    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+    Set-Content -Path $targetSkill -Value $expectedSkill -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetDir
+
+    $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  if ($ReadOnlyCheck -and -not $SelectedSkill -and (Test-Path $skillsMirrorRoot)) {
+    foreach ($dir in Get-ChildItem $skillsMirrorRoot -Directory) {
+      $skillFile = Join-Path $dir.FullName 'SKILL.md'
+      if (-not (Test-Path $skillFile)) { continue }
+      if ((Get-Content $skillFile -Raw) -notmatch '<!-- GENERATED from ai-artifacts/skills/shared/') {
+        continue
+      }
+      if (-not $expectedSkillNames.Contains($dir.Name)) {
+        $driftCount++
+        $entries.Add((Get-SyncReportEntry -Name $dir.Name -Detail 'EXTRA'))
+      }
+    }
+  }
+
+  Write-SyncReport -Flavor 'Copilot skills' -TargetPath $skillsMirrorRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+if ([string]::IsNullOrWhiteSpace($RepoRoot)) {
+  $RepoRoot = (& git -C $PSScriptRoot rev-parse --show-toplevel 2>$null)
+  if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($RepoRoot)) {
+    throw "Unable to determine repo root. Run from inside the repo or pass -RepoRoot."
+  }
+}
+
+$RepoRoot = (Resolve-Path $RepoRoot).Path
+$skillsRoot = Join-Path $RepoRoot 'ai-artifacts/skills/shared'
+$skillDirs = Get-SkillDirectories -SkillsRoot $skillsRoot -SkillName $Skill
+
+if (-not $SkipHooks) {
+  Invoke-InstallGitHooksInternal -ResolvedRepoRoot $RepoRoot
+}
+
+if (-not $SkipSkillSync) {
+  $exitCode = 0
+  switch ($Target) {
+    'All' {
+      Sync-ClaudeSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+      Sync-CodexSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+      Sync-CopilotSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+    }
+    'Claude' {
+      Sync-ClaudeSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
+      $exitCode = $script:LastSyncExitCode
+    }
+    'Codex' {
+      Sync-CodexSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = $script:LastSyncExitCode
+    }
+    'Copilot' {
+      Sync-CopilotSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = $script:LastSyncExitCode
+    }
+  }
+
+  if ($Check) {
+    if ($exitCode) {
+      Write-Output 'Generated mirrors are stale or missing. Rebuild with: pwsh scripts/setup-repo.ps1 -SkipHooks'
+      exit 1
+    }
+
+    Write-Output 'Generated mirrors are up to date.'
+  }
+}
+
+Write-Output "Repository setup completed."
diff --git a/.claude/commands/setup/setup-repo/tests/test_setup_repo.py b/.claude/commands/setup/setup-repo/tests/test_setup_repo.py
new file mode 100644
index 0000000..c2baf49
--- /dev/null
+++ b/.claude/commands/setup/setup-repo/tests/test_setup_repo.py
@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+SCRIPT_PATH = (
+    Path(__file__).resolve().parent.parent / "scripts" / "Invoke-SetupRepo.ps1"
+)
+
+
+def _pwsh_executable() -> str:
+    pwsh = shutil.which("pwsh")
+    if pwsh:
+        return pwsh
+    pytest.skip("pwsh is required for setup-repo tests")
+
+
+def _run_setup_repo(repo_root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    command = [
+        _pwsh_executable(),
+        "-NoProfile",
+        "-File",
+        str(SCRIPT_PATH),
+        "-RepoRoot",
+        str(repo_root),
+        *args,
+    ]
+    return subprocess.run(
+        command,
+        cwd=repo_root,
+        check=False,
+        text=True,
+        capture_output=True,
+    )
+
+
+def _write_minimal_skill(repo_root: Path, group: str, name: str) -> Path:
+    skill_dir = repo_root / "ai-artifacts" / "skills" / "shared" / group / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(
+        """---
+name: \"setup-repo\"
+description: \"Bootstrap repo\"
+version: \"1.0.0\"
+---
+
+# Setup Repo
+
+Body.
+""",
+        encoding="utf-8",
+    )
+    return skill_dir
+
+
+def _init_git_repo(path: Path) -> None:
+    git = shutil.which("git")
+    if not git:
+        pytest.skip("git is required for hook setup test")
+    subprocess.run([git, "init"], cwd=path, check=True, capture_output=True, text=True)
+
+
+def test_codex_mirror_uses_group_underscore_name(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    result = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks")
+
+    assert result.returncode == 0, result.stderr
+    mirror_root = tmp_path / ".agents" / "skills"
+    assert (mirror_root / "setup_setup-repo" / "SKILL.md").exists()
+    assert not (mirror_root / "setup-setup-repo").exists()
+
+
+def test_copilot_mirror_uses_group_underscore_name(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    result = _run_setup_repo(tmp_path, "-Target", "Copilot", "-SkipHooks")
+
+    assert result.returncode == 0, result.stderr
+    mirror_root = tmp_path / ".github" / "skills"
+    assert (mirror_root / "setup_setup-repo" / "SKILL.md").exists()
+    assert not (mirror_root / "setup-setup-repo").exists()
+
+
+def test_if_missing_preserves_existing_codex_skill_file(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    first = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks")
+    assert first.returncode == 0, first.stderr
+
+    target_skill = tmp_path / ".agents" / "skills" / "setup_setup-repo" / "SKILL.md"
+    target_skill.write_text("sentinel", encoding="utf-8")
+
+    second = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks", "-IfMissing")
+
+    assert second.returncode == 0, second.stderr
+    assert target_skill.read_text(encoding="utf-8") == "sentinel"
+
+
+def test_hook_setup_configures_git_hooks_path(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+    _init_git_repo(tmp_path)
+
+    hooks_dir = tmp_path / ".githooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    (hooks_dir / "pre-commit").write_text(
+        "#!/usr/bin/env sh\r\necho ok\r\n", encoding="utf-8"
+    )
+
+    result = _run_setup_repo(tmp_path, "-SkipSkillSync")
+
+    assert result.returncode == 0, result.stderr
+    git = shutil.which("git")
+    config = subprocess.run(
+        [git, "config", "core.hooksPath"],
+        cwd=tmp_path,
+        check=True,
+        text=True,
+        capture_output=True,
+    )
+    assert config.stdout.strip() == ".githooks"
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
index 4b2bf00..0ada8fc 100644
--- a/.claude/settings.local.json
+++ b/.claude/settings.local.json
@@ -47,15 +47,9 @@
         "hooks": [
           {
             "type": "command",
-            "command": "pwsh -NoProfile -File scripts/sync-skills.ps1 -IfMissing",
+            "command": "pwsh -NoProfile -File .claude/commands/setup/setup-repo/scripts/Invoke-SetupRepo.ps1 -IfMissing",
             "shell": "powershell",
             "statusMessage": "Materializing skill mirror…"
-          },
-          {
-            "type": "command",
-            "command": "pwsh -NoProfile -File scripts/sync-skills.ps1 -Check",
-            "shell": "powershell",
-            "statusMessage": "Checking skill mirror for drift…"
           }
         ]
       }
diff --git a/.claudeignore b/.claudeignore
index 9ba47b5..49bd3b5 100644
--- a/.claudeignore
+++ b/.claudeignore
@@ -1,4 +1,2 @@
-.claude*
-.git*
-.gradle/
-.history/
+/.*
+!/.temp
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..72a9234
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,16 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = off
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index 22c0bd9..40b84b3 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -1,94 +1,145 @@
-#!/usr/bin/sh
-
-if ! staged="$(git diff --cached --name-only --diff-filter=ACMRTUXB)"; then
-  echo "Failed to enumerate staged files for pre-commit hook." >&2
-  exit 1
-fi
-if [ -z "${staged}" ]; then
-  exit 0
-fi
-
-failed=0
-
-# Keep scratch artifacts "as-is" for linting; safety scans still run in CI.
-filtered="$(echo "${staged}" | grep -Ev '^\.scratch/[^/]+/(artefacts|artifacts)/' || true)"
-if [ -z "${filtered}" ]; then
-  exit 0
-fi
-
-need_tool() {
-  local tool="$1"
-  local hint="$2"
-  if ! command -v "${tool}" >/dev/null 2>&1; then
-    echo "Missing required tool: ${tool}. ${hint}" >&2
-    exit 1
-  fi
+#!/usr/bin/env pwsh
+# RuntimePolicy: core-first
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$repoRoot = (& git rev-parse --show-toplevel 2>$null)
+if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($repoRoot)) {
+    throw "Unable to determine repository root for hook execution."
 }
+$repoRoot = (Resolve-Path $repoRoot).Path
 
-matches() {
-  local pattern="$1"
-  echo "${filtered}" | grep -E "${pattern}" >/dev/null 2>&1
+function Require-Tool {
+    param(
+        [string]$Name,
+        [string]$Hint
+    )
+
+    if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
+        throw "Missing required tool: $Name. $Hint"
+    }
 }
 
-if matches '\.(yml|yaml)$'; then
-  need_tool "yamllint" "Install with: pip install yamllint"
-  echo "${filtered}" | grep -E '\.(yml|yaml)$' | xargs -I{} yamllint -s "{}" || failed=1
-fi
-
-if matches '\.json$'; then
-  need_tool "python" "Install Python 3 and add it to PATH."
-  echo "${filtered}" | grep -E '\.json$' | xargs -I{} python -m json.tool "{}" >/dev/null || failed=1
-fi
-
-if matches '\.md$'; then
-  need_tool "markdownlint" "Install with: npm install -g markdownlint-cli"
-  echo "${filtered}" | grep -E '\.md$' | xargs -I{} markdownlint "{}" --config .markdownlint.json || failed=1
-fi
-
-if matches '\.(adoc|asciidoc)$'; then
-  need_tool "asciidoctor" "Install with: gem install asciidoctor asciidoctor-lint"
-  need_tool "asciidoctor-lint" "Install with: gem install asciidoctor asciidoctor-lint"
-  echo "${filtered}" | grep -E '\.(adoc|asciidoc)$' | xargs -I{} asciidoctor -o /dev/null "{}" || failed=1
-  echo "${filtered}" | grep -E '\.(adoc|asciidoc)$' | xargs -I{} asciidoctor-lint "{}" || failed=1
-fi
-
-if matches '\.py$'; then
-  need_tool "ruff" "Install with: pip install ruff"
-  py_files="$(echo "${filtered}" | grep -E '\.py$' || true)"
-  if [ -n "${py_files}" ]; then
-    echo "${py_files}" | xargs -I{} ruff check "{}" || failed=1
-    echo "${py_files}" | xargs -I{} ruff format --check "{}" || failed=1
-  fi
-fi
-
-if matches '\.(ps1|psm1|psd1)$'; then
-  need_tool "pwsh" "Install PowerShell 7 and PSScriptAnalyzer module."
-  ps_files="$(echo "${filtered}" | grep -E '\.(ps1|psm1|psd1)$' || true)"
-  if [ -n "${ps_files}" ]; then
-    while IFS= read -r file; do
-      pwsh -NoProfile -Command "
-        Set-PSRepository PSGallery -InstallationPolicy Trusted
+function Get-Matches {
+    param(
+        [string[]]$Files,
+        [string]$Pattern
+    )
+
+    return @($Files | Where-Object { $_ -match $Pattern })
+}
+
+$staged = @(& git diff --cached --name-only --diff-filter=ACMRTUXB)
+if ($LASTEXITCODE -ne 0) {
+    throw "Failed to enumerate staged files for pre-commit hook."
+}
+if (-not $staged -or $staged.Count -eq 0) {
+    exit 0
+}
+
+# Keep scratch artifacts as-is for linting; safety scans still run in CI.
+$filtered = @($staged | Where-Object { $_ -notmatch '^\.scratch/[^/]+/(artefacts|artifacts)/' })
+if (-not $filtered -or $filtered.Count -eq 0) {
+    exit 0
+}
+
+$failed = $false
+$nullDevice = if ($IsWindows) { 'NUL' } else { '/dev/null' }
+
+try {
+    # Reuse the same policy validators used in CI workflows.
+    Require-Tool -Name "python" -Hint "Install Python 3 and add it to PATH."
+    & python (Join-Path $repoRoot ".github/workflows/scripts/validate-coding-policies.py")
+    if ($LASTEXITCODE -ne 0) { $failed = $true }
+
+    & python (Join-Path $repoRoot ".github/workflows/scripts/validate-powershell-runtime.py")
+    if ($LASTEXITCODE -ne 0) { $failed = $true }
+
+    $yamlFiles = Get-Matches -Files $filtered -Pattern '\.(yml|yaml)$'
+    if ($yamlFiles.Count -gt 0) {
+        Require-Tool -Name "yamllint" -Hint "Install with: pip install yamllint"
+        & yamllint -s @yamlFiles
+        if ($LASTEXITCODE -ne 0) { $failed = $true }
+    }
+
+    $jsonFiles = Get-Matches -Files $filtered -Pattern '\.json$'
+    if ($jsonFiles.Count -gt 0) {
+        Require-Tool -Name "python" -Hint "Install Python 3 and add it to PATH."
+        foreach ($file in $jsonFiles) {
+            & python -m json.tool $file > $null
+            if ($LASTEXITCODE -ne 0) {
+                $failed = $true
+            }
+        }
+    }
+
+    $mdFiles = Get-Matches -Files $filtered -Pattern '\.md$'
+    if ($mdFiles.Count -gt 0) {
+        Require-Tool -Name "markdownlint" -Hint "Install with: npm install -g markdownlint-cli"
+        & markdownlint @mdFiles --config .markdownlint.json
+        if ($LASTEXITCODE -ne 0) { $failed = $true }
+    }
+
+    $adocFiles = Get-Matches -Files $filtered -Pattern '\.(adoc|asciidoc)$'
+    if ($adocFiles.Count -gt 0) {
+        Require-Tool -Name "asciidoctor" -Hint "Install with: gem install asciidoctor asciidoctor-lint"
+        Require-Tool -Name "asciidoctor-lint" -Hint "Install with: gem install asciidoctor asciidoctor-lint"
+        foreach ($file in $adocFiles) {
+            & asciidoctor -o $nullDevice $file
+            if ($LASTEXITCODE -ne 0) { $failed = $true }
+            & asciidoctor-lint $file
+            if ($LASTEXITCODE -ne 0) { $failed = $true }
+        }
+    }
+
+    $pyFiles = Get-Matches -Files $filtered -Pattern '\.py$'
+    if ($pyFiles.Count -gt 0) {
+        Require-Tool -Name "ruff" -Hint "Install with: pip install ruff"
+        & python -m ruff check @pyFiles
+        if ($LASTEXITCODE -ne 0) { $failed = $true }
+        & python -m ruff format --check @pyFiles
+        if ($LASTEXITCODE -ne 0) { $failed = $true }
+    }
+
+    $psFiles = Get-Matches -Files $filtered -Pattern '\.(ps1|psm1|psd1)$'
+    if ($psFiles.Count -gt 0) {
+        Require-Tool -Name "pwsh" -Hint "Install PowerShell 7 and PSScriptAnalyzer module."
         if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
-          Install-Module PSScriptAnalyzer -Scope CurrentUser -Force
+            Set-PSRepository PSGallery -InstallationPolicy Trusted
+            Install-Module PSScriptAnalyzer -Scope CurrentUser -Force
+        }
+
+        $results = Invoke-ScriptAnalyzer -Path $psFiles -Severity Warning,Error
+        if ($results) {
+            $results | Format-Table -AutoSize | Out-String | Write-Output
+            $failed = $true
         }
-        \$results = Invoke-ScriptAnalyzer -Path '${file}' -Severity Warning,Error
-        if (\$results) {
-          \$results | Format-Table -AutoSize
-          throw 'PSScriptAnalyzer found issues in ${file}.'
+    }
+
+    $shFiles = Get-Matches -Files $filtered -Pattern '\.sh$'
+    if ($shFiles.Count -gt 0) {
+        Require-Tool -Name "shellcheck" -Hint "Install shellcheck and add it to PATH."
+        & shellcheck @shFiles
+        if ($LASTEXITCODE -ne 0) { $failed = $true }
+    }
+
+    $jsFiles = Get-Matches -Files $filtered -Pattern '\.js$'
+    if ($jsFiles.Count -gt 0) {
+        Require-Tool -Name "node" -Hint "Install Node.js and add it to PATH."
+        foreach ($file in $jsFiles) {
+            & node --check $file
+            if ($LASTEXITCODE -ne 0) { $failed = $true }
         }
-      " || failed=1
-    done <<< "${ps_files}"
-  fi
-fi
-
-if matches '\.sh$'; then
-  need_tool "shellcheck" "Install shellcheck and add it to PATH."
-  echo "${filtered}" | grep -E '\.sh$' | xargs -I{} shellcheck "{}" || failed=1
-fi
-
-if matches '\.js$'; then
-  need_tool "node" "Install Node.js and add it to PATH."
-  echo "${filtered}" | grep -E '\.js$' | xargs -I{} node --check "{}" || failed=1
-fi
-
-exit $failed
+    }
+}
+catch {
+    Write-Error $_
+    exit 1
+}
+
+if ($failed) {
+    exit 1
+}
+
+exit 0
diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 13bf064..722d498 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -1,13 +1,17 @@
-# Default owner for all paths.
-* @DenWin
+# Security-boundary paths only (no global owner on purpose)
+# These paths require repo-admin review (@DenWin).
 
-# Sensitive policy and automation areas.
-.github/workflows/* @DenWin
-.github/CODEOWNERS @DenWin
-.github/pull_request_template.md @DenWin
-AGENTS.md @DenWin
-coding-policies/** @DenWin
-shared/skills/** @DenWin
-scripts/** @DenWin
-instructions/** @DenWin
-anthropic/** @DenWin
+# Governance and CI control plane
+.github/CODEOWNERS                @DenWin
+.github/workflows/**              @DenWin
+.githooks/**                      @DenWin
+
+# Runtime capability surfaces
+ai-artifacts/hooks/**             @DenWin
+ai-artifacts/mcp-config/**        @DenWin
+ai-artifacts/plugins/**           @DenWin
+
+# Executable automation and policy gates
+ai-artifacts/skills/**/scripts/** @DenWin
+coding-policies/**                @DenWin
+scripts/**                        @DenWin
diff --git a/.github/skills/setup_setup-repo/SKILL.md b/.github/skills/setup_setup-repo/SKILL.md
new file mode 100644
index 0000000..fe826cd
--- /dev/null
+++ b/.github/skills/setup_setup-repo/SKILL.md
@@ -0,0 +1,84 @@
+---
+name: "setup_setup-repo"
+description: "Bootstrap this repository after clone by enabling git hooks and syncing generated skill mirrors. Use when user asks to set up the repo, bootstrap local tooling, or initialize mirrors/hooks for this clone."
+version: "1.0.0"
+---
+
+<!-- GENERATED from ai-artifacts/skills/shared/setup/setup-repo/SKILL.md. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->
+# Setup Repo
+
+Bootstraps this clone in one pass:
+
+1. Activates repo git hooks
+2. Syncs generated skill mirrors for Claude, Codex, and Copilot
+
+Implementation layout:
+
+- Canonical entrypoint: `ai-artifacts/skills/shared/setup/setup-repo/scripts/Invoke-SetupRepo.ps1`
+- Repo convenience wrapper: `scripts/setup-repo.ps1`
+
+## Applicability (capability contract)
+
+This skill needs shell + filesystem access in a local git checkout. In chat-only environments,
+provide the exact commands and explain what each command configures.
+
+## Default command
+
+```powershell
+pwsh scripts/setup-repo.ps1
+```
+
+## Common variants
+
+Project-local mirrors for one harness:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -Target Copilot -Scope Project
+```
+
+User-scope mirrors for all harnesses:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -Scope User
+```
+
+Bootstrap only missing generated mirrors (keeps existing generated files untouched):
+
+```powershell
+pwsh scripts/setup-repo.ps1 -IfMissing
+```
+
+Refresh generated mirrors without touching git hooks:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks
+```
+
+Check generated mirrors for drift:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks -Check
+pwsh scripts/setup-repo.ps1 -SkipHooks -Target Codex -Skill tdd -Check
+```
+
+Run only one phase:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks
+pwsh scripts/setup-repo.ps1 -SkipSkillSync
+```
+
+## Verify
+
+```powershell
+git config --get core.hooksPath
+Test-Path .claude/commands
+Test-Path .agents/skills
+Test-Path .github/skills
+pwsh scripts/setup-repo.ps1 -SkipHooks -Check
+```
+
+Expected:
+
+- `core.hooksPath` prints `.githooks`
+- mirror folders exist for selected targets
diff --git a/.github/skills/setup_setup-repo/scripts/Invoke-SetupRepo.ps1 b/.github/skills/setup_setup-repo/scripts/Invoke-SetupRepo.ps1
new file mode 100644
index 0000000..d1c0f05
--- /dev/null
+++ b/.github/skills/setup_setup-repo/scripts/Invoke-SetupRepo.ps1
@@ -0,0 +1,584 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+
+  [ValidateSet('All', 'Claude', 'Codex', 'Copilot')]
+  [string]$Target = 'All',
+
+  [Alias('Scope')]
+  [ValidateSet('Project', 'User')]
+  [string]$MirrorScope = 'Project',
+
+  [string]$Skill = '',
+
+  [switch]$IfMissing,
+  [switch]$Check,
+  [switch]$SkipHooks,
+  [switch]$SkipSkillSync
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if ($Check -and $IfMissing) {
+  throw "-Check is read-only; do not combine it with -IfMissing."
+}
+
+function Get-UserHomePath {
+  if ($env:HOME) { return $env:HOME }
+  if ($env:USERPROFILE) { return $env:USERPROFILE }
+  throw "Cannot resolve user home path from HOME/USERPROFILE."
+}
+
+function Get-RelativePathText {
+  param(
+    [string]$BasePath,
+    [string]$TargetPath
+  )
+
+  $rel = [System.IO.Path]::GetRelativePath($BasePath, $TargetPath)
+  return $rel.TrimStart('\', '/')
+}
+
+function Get-MirrorRootPath {
+  param(
+    [ValidateSet('Claude', 'Codex', 'Copilot')]
+    [string]$TargetName,
+
+    [ValidateSet('Project', 'User')]
+    [string]$ScopeName,
+
+    [string]$ResolvedRepoRoot
+  )
+
+  switch ("$TargetName|$ScopeName") {
+    'Claude|Project' { return (Join-Path $ResolvedRepoRoot '.claude/commands') }
+    'Claude|User' { return (Join-Path (Get-UserHomePath) '.claude/commands') }
+    'Codex|Project' { return (Join-Path $ResolvedRepoRoot '.agents/skills') }
+    'Codex|User' { return (Join-Path (Get-UserHomePath) '.codex/skills') }
+    'Copilot|Project' { return (Join-Path $ResolvedRepoRoot '.github/skills') }
+    'Copilot|User' { return (Join-Path (Get-UserHomePath) '.copilot/skills') }
+    default { throw "Unsupported mirror target/scope combination: $TargetName / $ScopeName" }
+  }
+}
+
+function Get-SkillDirectories {
+  param(
+    [string]$SkillsRoot,
+    [string]$SkillName
+  )
+
+  $dirs = @(Get-ChildItem $SkillsRoot -Recurse -Filter 'SKILL.md' -File | ForEach-Object { $_.Directory })
+  if ($SkillName) {
+    $dirs = @($dirs | Where-Object { $_.Name -eq $SkillName })
+    if ($dirs.Count -eq 0) {
+      throw "No SKILL.md found for skill '$SkillName' under $SkillsRoot"
+    }
+  }
+  if ($dirs.Count -eq 0) {
+    throw "No SKILL.md files found under $SkillsRoot"
+  }
+  return $dirs
+}
+
+function Get-SyncReportEntry {
+  param(
+    [string]$Name,
+    [string]$Detail
+  )
+
+  return [PSCustomObject]@{
+    Name   = $Name
+    Detail = $Detail
+  }
+}
+
+function Write-SyncReport {
+  param(
+    [string]$Flavor,
+    [string]$TargetPath,
+    [object[]]$Entries,
+    [string]$Scope
+  )
+
+  $scopeText = if ($Scope) { " (scope=$Scope)" } else { '' }
+  Write-Output "Synced $Flavor -> $TargetPath$scopeText"
+
+  if (-not $Entries -or @($Entries).Count -eq 0) {
+    return
+  }
+
+  $nameWidth = ($Entries | ForEach-Object { $_.Name.Length } | Measure-Object -Maximum).Maximum
+  if (-not $nameWidth) { $nameWidth = 0 }
+
+  foreach ($entry in $Entries) {
+    Write-Output ("  {0}  {1}" -f $entry.Name.PadRight($nameWidth), $entry.Detail)
+  }
+}
+
+function Get-SkillResources {
+  param([string]$SkillDir)
+
+  return @(Get-ChildItem $SkillDir -Recurse -File |
+      Where-Object { $_.Name -notin @('SKILL.md', 'METADATA.md') })
+}
+
+function Copy-MirroredResources {
+  param(
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetBase
+  )
+
+  foreach ($res in $Resources) {
+    $rel = Get-RelativePathText -BasePath $SourceBase -TargetPath $res.FullName
+    $dest = Join-Path $TargetBase $rel
+    New-Item -ItemType Directory -Path (Split-Path $dest -Parent) -Force | Out-Null
+    Copy-Item $res.FullName $dest -Force
+  }
+}
+
+function Test-MirroredResourcesMatch {
+  param(
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetBase,
+    [switch]$ExcludeTargetSkillFile
+  )
+
+  foreach ($res in $Resources) {
+    $rel = Get-RelativePathText -BasePath $SourceBase -TargetPath $res.FullName
+    $dest = Join-Path $TargetBase $rel
+    if (-not (Test-Path $dest) -or
+      (Get-FileHash $res.FullName).Hash -ne (Get-FileHash $dest).Hash) {
+      return $false
+    }
+  }
+
+  $resourceCount = @($Resources).Count
+  $mirroredCount = if (Test-Path $TargetBase) {
+    @(Get-ChildItem $TargetBase -Recurse -File |
+        Where-Object { -not $ExcludeTargetSkillFile -or $_.Name -ne 'SKILL.md' }).Count
+  }
+  else {
+    0
+  }
+
+  return $mirroredCount -eq $resourceCount
+}
+
+function Get-SkillMirrorState {
+  param(
+    [string]$TargetSkillPath,
+    [string]$ExpectedSkill,
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetResourceBase,
+    [switch]$ExcludeTargetSkillFile
+  )
+
+  if (-not (Test-Path $TargetSkillPath)) { return 'MISSING' }
+  if ((Get-Content $TargetSkillPath -Raw) -cne $ExpectedSkill) { return 'STALE' }
+
+  if (-not (Test-MirroredResourcesMatch -Resources $Resources -SourceBase $SourceBase -TargetBase $TargetResourceBase -ExcludeTargetSkillFile:$ExcludeTargetSkillFile)) {
+    return 'STALE'
+  }
+
+  return 'UP-TO-DATE'
+}
+
+function Convert-ResourceLinks {
+  param(
+    [string]$Body,
+    [string]$Name,
+    [string[]]$ResourceRelPaths
+  )
+
+  foreach ($path in $ResourceRelPaths) {
+    $Body = $Body.Replace("](./$path)", "]($Name/$path)")
+    $Body = $Body.Replace("]($path)", "]($Name/$path)")
+    $Body = $Body -replace ("(?<=@)" + [regex]::Escape($path) + "\b"), "$Name/$path"
+  }
+  return $Body
+}
+
+function ConvertTo-YamlScalar {
+  param([string]$Value)
+
+  if ($null -eq $Value) { return '""' }
+  return '"' + ($Value -replace '\\', '\\' -replace '"', '\"') + '"'
+}
+
+function Get-FrontmatterValue {
+  param(
+    [string]$Document,
+    [string]$Key
+  )
+
+  if ($Document -notmatch "(?s)\A---\r?\n(.*?)\r?\n---\r?\n") { return $null }
+  $frontmatter = $Matches[1]
+  $match = [regex]::Match($frontmatter, "(?m)^$([regex]::Escape($Key)):\s*(.*)$")
+  if (-not $match.Success) { return $null }
+
+  $value = $match.Groups[1].Value.Trim()
+  if (($value.StartsWith('"') -and $value.EndsWith('"')) -or
+    ($value.StartsWith("'") -and $value.EndsWith("'"))) {
+    $value = $value.Substring(1, $value.Length - 2)
+  }
+  return $value
+}
+
+function Get-SkillBody {
+  param([string]$Document)
+
+  if ($Document -match "(?s)\A---\r?\n.*?\r?\n---\r?\n(.*)\z") {
+    return $Matches[1].TrimStart()
+  }
+  return $Document.TrimStart()
+}
+
+function ConvertTo-CodexSkill {
+  param(
+    [string]$SourceDocument,
+    [string]$CodexName,
+    [string]$SourceRelPath
+  )
+
+  $description = Get-FrontmatterValue -Document $SourceDocument -Key 'description'
+  if (-not $description) { $description = "Repo skill mirrored from $SourceRelPath." }
+  $version = Get-FrontmatterValue -Document $SourceDocument -Key 'version'
+
+  $body = Get-SkillBody -Document $SourceDocument
+  $frontmatter = @(
+    '---'
+    "name: $(ConvertTo-YamlScalar $CodexName)"
+    "description: $(ConvertTo-YamlScalar $description)"
+    $(if ($version) { "version: $(ConvertTo-YamlScalar $version)" })
+    '---'
+    ''
+    "<!-- GENERATED from $SourceRelPath. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->"
+    ''
+  ) -join "`n"
+
+  return $frontmatter + $body
+}
+
+function ConvertTo-CopilotSkill {
+  param(
+    [string]$SourceDocument,
+    [string]$SkillName,
+    [string]$SourceRelPath
+  )
+
+  $description = Get-FrontmatterValue -Document $SourceDocument -Key 'description'
+  if (-not $description) { $description = "Repo skill mirrored from $SourceRelPath." }
+  $version = Get-FrontmatterValue -Document $SourceDocument -Key 'version'
+
+  $body = Get-SkillBody -Document $SourceDocument
+  $frontmatter = @(
+    '---'
+    "name: $(ConvertTo-YamlScalar $SkillName)"
+    "description: $(ConvertTo-YamlScalar $description)"
+    $(if ($version) { "version: $(ConvertTo-YamlScalar $version)" })
+    '---'
+    ''
+    "<!-- GENERATED from $SourceRelPath. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->"
+    ''
+  ) -join "`n"
+
+  return $frontmatter + $body
+}
+
+function Invoke-InstallGitHooksInternal {
+  param([string]$ResolvedRepoRoot)
+
+  $hooksDir = Join-Path $ResolvedRepoRoot '.githooks'
+  if (Test-Path $hooksDir) {
+    $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+    Get-ChildItem -Path $hooksDir -File | ForEach-Object {
+      $raw = [System.IO.File]::ReadAllText($_.FullName)
+      $normalized = $raw -replace "`r`n", "`n" -replace "`r", "`n"
+      if ($normalized -ne $raw) {
+        [System.IO.File]::WriteAllText($_.FullName, $normalized, $utf8NoBom)
+        Write-Output "Normalized LF line endings: $($_.Name)"
+      }
+    }
+  }
+
+  Write-Output '== Git hooks =='
+  git config core.hooksPath .githooks
+  Write-Output 'Configured core.hooksPath to .githooks'
+
+  if ($IsLinux -or $IsMacOS) {
+    $preCommit = Join-Path $hooksDir 'pre-commit'
+    if (Test-Path $preCommit) {
+      & chmod +x $preCommit
+    }
+  }
+
+  Write-Output 'Git hooks are now active for this clone.'
+}
+
+function Sync-ClaudeSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck
+  )
+
+  $commandsRoot = Get-MirrorRootPath -TargetName 'Claude' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  Write-Output ''
+  Write-Output '== Claude Code skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $name = $dir.Name
+    $group = $dir.Parent.Name
+    $groupDir = Join-Path $commandsRoot $group
+    $targetMd = Join-Path $groupDir "$name.md"
+    $targetRes = Join-Path $groupDir $name
+
+    if ($OnlyIfMissing -and (Test-Path $targetMd)) {
+      $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+    $resRelPaths = $resources | ForEach-Object {
+      (Get-RelativePathText -BasePath $dir.FullName -TargetPath $_.FullName).Replace('\\', '/')
+    }
+
+    $body = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    if ($resRelPaths) {
+      $body = Convert-ResourceLinks -Body $body -Name $name -ResourceRelPaths $resRelPaths
+    }
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetMd -ExpectedSkill $body -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetRes
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetMd) { Remove-Item $targetMd -Force }
+    if (Test-Path $targetRes) { Remove-Item $targetRes -Recurse -Force }
+    New-Item -ItemType Directory -Path $groupDir -Force | Out-Null
+    Set-Content -Path $targetMd -Value $body -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetRes
+
+    $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  Write-SyncReport -Flavor 'Claude skills' -TargetPath $commandsRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+function Sync-CodexSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck,
+    [string]$SelectedSkill
+  )
+
+  $agentsRoot = Get-MirrorRootPath -TargetName 'Codex' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $expectedSkillNames = [System.Collections.Generic.HashSet[string]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  if (-not $ReadOnlyCheck -and -not $OnlyIfMissing -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
+    Remove-Item $agentsRoot -Recurse -Force
+  }
+
+  Write-Output ''
+  Write-Output '== Codex skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $sourceName = $dir.Name
+    $group = $dir.Parent.Name
+    $codexName = "$group`_$sourceName"
+    [void]$expectedSkillNames.Add($codexName)
+    $targetDir = Join-Path $agentsRoot $codexName
+    $targetSkill = Join-Path $targetDir 'SKILL.md'
+
+    if ($OnlyIfMissing -and (Test-Path $targetSkill)) {
+      $entries.Add((Get-SyncReportEntry -Name $codexName -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $sourceRelPath = "ai-artifacts/skills/shared/$group/$sourceName/SKILL.md"
+    $sourceDocument = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    $expectedSkill = ConvertTo-CodexSkill -SourceDocument $sourceDocument -CodexName $codexName -SourceRelPath $sourceRelPath
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetSkill -ExpectedSkill $expectedSkill -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetDir -ExcludeTargetSkillFile
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name $codexName -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
+    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+    Set-Content -Path $targetSkill -Value $expectedSkill -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetDir
+
+    $entries.Add((Get-SyncReportEntry -Name $codexName -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  if ($ReadOnlyCheck -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
+    foreach ($dir in Get-ChildItem $agentsRoot -Directory) {
+      if (-not $expectedSkillNames.Contains($dir.Name)) {
+        $driftCount++
+        $entries.Add((Get-SyncReportEntry -Name $dir.Name -Detail 'EXTRA'))
+      }
+    }
+  }
+
+  Write-SyncReport -Flavor 'Codex skills' -TargetPath $agentsRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+function Sync-CopilotSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck,
+    [string]$SelectedSkill
+  )
+
+  $skillsMirrorRoot = Get-MirrorRootPath -TargetName 'Copilot' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $expectedSkillNames = [System.Collections.Generic.HashSet[string]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  if (-not $ReadOnlyCheck -and -not $OnlyIfMissing -and -not $SelectedSkill -and (Test-Path $skillsMirrorRoot)) {
+    Remove-Item $skillsMirrorRoot -Recurse -Force
+  }
+
+  Write-Output ''
+  Write-Output '== Copilot skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $sourceName = $dir.Name
+    $group = $dir.Parent.Name
+    $copilotSkillName = "$group`_$sourceName"
+    [void]$expectedSkillNames.Add($copilotSkillName)
+    $targetDir = Join-Path $skillsMirrorRoot $copilotSkillName
+    $targetSkill = Join-Path $targetDir 'SKILL.md'
+
+    if ($OnlyIfMissing -and (Test-Path $targetSkill)) {
+      $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $sourceRelPath = "ai-artifacts/skills/shared/$group/$sourceName/SKILL.md"
+    $sourceDocument = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    $expectedSkill = ConvertTo-CopilotSkill -SourceDocument $sourceDocument -SkillName $copilotSkillName -SourceRelPath $sourceRelPath
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetSkill -ExpectedSkill $expectedSkill -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetDir -ExcludeTargetSkillFile
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
+    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+    Set-Content -Path $targetSkill -Value $expectedSkill -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetDir
+
+    $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  if ($ReadOnlyCheck -and -not $SelectedSkill -and (Test-Path $skillsMirrorRoot)) {
+    foreach ($dir in Get-ChildItem $skillsMirrorRoot -Directory) {
+      $skillFile = Join-Path $dir.FullName 'SKILL.md'
+      if (-not (Test-Path $skillFile)) { continue }
+      if ((Get-Content $skillFile -Raw) -notmatch '<!-- GENERATED from ai-artifacts/skills/shared/') {
+        continue
+      }
+      if (-not $expectedSkillNames.Contains($dir.Name)) {
+        $driftCount++
+        $entries.Add((Get-SyncReportEntry -Name $dir.Name -Detail 'EXTRA'))
+      }
+    }
+  }
+
+  Write-SyncReport -Flavor 'Copilot skills' -TargetPath $skillsMirrorRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+if ([string]::IsNullOrWhiteSpace($RepoRoot)) {
+  $RepoRoot = (& git -C $PSScriptRoot rev-parse --show-toplevel 2>$null)
+  if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($RepoRoot)) {
+    throw "Unable to determine repo root. Run from inside the repo or pass -RepoRoot."
+  }
+}
+
+$RepoRoot = (Resolve-Path $RepoRoot).Path
+$skillsRoot = Join-Path $RepoRoot 'ai-artifacts/skills/shared'
+$skillDirs = Get-SkillDirectories -SkillsRoot $skillsRoot -SkillName $Skill
+
+if (-not $SkipHooks) {
+  Invoke-InstallGitHooksInternal -ResolvedRepoRoot $RepoRoot
+}
+
+if (-not $SkipSkillSync) {
+  $exitCode = 0
+  switch ($Target) {
+    'All' {
+      Sync-ClaudeSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+      Sync-CodexSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+      Sync-CopilotSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+    }
+    'Claude' {
+      Sync-ClaudeSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
+      $exitCode = $script:LastSyncExitCode
+    }
+    'Codex' {
+      Sync-CodexSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = $script:LastSyncExitCode
+    }
+    'Copilot' {
+      Sync-CopilotSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = $script:LastSyncExitCode
+    }
+  }
+
+  if ($Check) {
+    if ($exitCode) {
+      Write-Output 'Generated mirrors are stale or missing. Rebuild with: pwsh scripts/setup-repo.ps1 -SkipHooks'
+      exit 1
+    }
+
+    Write-Output 'Generated mirrors are up to date.'
+  }
+}
+
+Write-Output "Repository setup completed."
diff --git a/.github/skills/setup_setup-repo/tests/test_setup_repo.py b/.github/skills/setup_setup-repo/tests/test_setup_repo.py
new file mode 100644
index 0000000..c2baf49
--- /dev/null
+++ b/.github/skills/setup_setup-repo/tests/test_setup_repo.py
@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+SCRIPT_PATH = (
+    Path(__file__).resolve().parent.parent / "scripts" / "Invoke-SetupRepo.ps1"
+)
+
+
+def _pwsh_executable() -> str:
+    pwsh = shutil.which("pwsh")
+    if pwsh:
+        return pwsh
+    pytest.skip("pwsh is required for setup-repo tests")
+
+
+def _run_setup_repo(repo_root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    command = [
+        _pwsh_executable(),
+        "-NoProfile",
+        "-File",
+        str(SCRIPT_PATH),
+        "-RepoRoot",
+        str(repo_root),
+        *args,
+    ]
+    return subprocess.run(
+        command,
+        cwd=repo_root,
+        check=False,
+        text=True,
+        capture_output=True,
+    )
+
+
+def _write_minimal_skill(repo_root: Path, group: str, name: str) -> Path:
+    skill_dir = repo_root / "ai-artifacts" / "skills" / "shared" / group / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(
+        """---
+name: \"setup-repo\"
+description: \"Bootstrap repo\"
+version: \"1.0.0\"
+---
+
+# Setup Repo
+
+Body.
+""",
+        encoding="utf-8",
+    )
+    return skill_dir
+
+
+def _init_git_repo(path: Path) -> None:
+    git = shutil.which("git")
+    if not git:
+        pytest.skip("git is required for hook setup test")
+    subprocess.run([git, "init"], cwd=path, check=True, capture_output=True, text=True)
+
+
+def test_codex_mirror_uses_group_underscore_name(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    result = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks")
+
+    assert result.returncode == 0, result.stderr
+    mirror_root = tmp_path / ".agents" / "skills"
+    assert (mirror_root / "setup_setup-repo" / "SKILL.md").exists()
+    assert not (mirror_root / "setup-setup-repo").exists()
+
+
+def test_copilot_mirror_uses_group_underscore_name(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    result = _run_setup_repo(tmp_path, "-Target", "Copilot", "-SkipHooks")
+
+    assert result.returncode == 0, result.stderr
+    mirror_root = tmp_path / ".github" / "skills"
+    assert (mirror_root / "setup_setup-repo" / "SKILL.md").exists()
+    assert not (mirror_root / "setup-setup-repo").exists()
+
+
+def test_if_missing_preserves_existing_codex_skill_file(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    first = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks")
+    assert first.returncode == 0, first.stderr
+
+    target_skill = tmp_path / ".agents" / "skills" / "setup_setup-repo" / "SKILL.md"
+    target_skill.write_text("sentinel", encoding="utf-8")
+
+    second = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks", "-IfMissing")
+
+    assert second.returncode == 0, second.stderr
+    assert target_skill.read_text(encoding="utf-8") == "sentinel"
+
+
+def test_hook_setup_configures_git_hooks_path(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+    _init_git_repo(tmp_path)
+
+    hooks_dir = tmp_path / ".githooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    (hooks_dir / "pre-commit").write_text(
+        "#!/usr/bin/env sh\r\necho ok\r\n", encoding="utf-8"
+    )
+
+    result = _run_setup_repo(tmp_path, "-SkipSkillSync")
+
+    assert result.returncode == 0, result.stderr
+    git = shutil.which("git")
+    config = subprocess.run(
+        [git, "config", "core.hooksPath"],
+        cwd=tmp_path,
+        check=True,
+        text=True,
+        capture_output=True,
+    )
+    assert config.stdout.strip() == ".githooks"
diff --git a/.github/workflows/config-lint.yml b/.github/workflows/config-lint.yml
index 63a0668..4a088e2 100644
--- a/.github/workflows/config-lint.yml
+++ b/.github/workflows/config-lint.yml
@@ -3,41 +3,41 @@ name: config-lint
 on:
   pull_request:
     paths:
-      - "**/*.md"
       - "**/*.adoc"
       - "**/*.asciidoc"
-      - "**/*.yml"
-      - "**/*.yaml"
       - "**/*.json"
+      - "**/*.md"
+      - "**/*.yaml"
+      - "**/*.yml"
+      - ".asciidoctor-lint.yml"
       - ".github/workflows/config-lint.yml"
+      - ".github/workflows/scripts/**"
       - ".markdownlint.json"
-      - ".asciidoctor-lint.yml"
       - "AGENTS.md"
+      - "anthropic/**"
       - "docs/**"
       - "instructions/**"
       - "shared/**"
-      - "anthropic/**"
-      - "scripts/**"
       - "!.scratch/*/artefacts/**"
       - "!.scratch/*/artifacts/**"
   push:
     branches: [main]
     paths:
-      - "**/*.md"
       - "**/*.adoc"
       - "**/*.asciidoc"
-      - "**/*.yml"
-      - "**/*.yaml"
       - "**/*.json"
+      - "**/*.md"
+      - "**/*.yaml"
+      - "**/*.yml"
+      - ".asciidoctor-lint.yml"
       - ".github/workflows/config-lint.yml"
+      - ".github/workflows/scripts/**"
       - ".markdownlint.json"
-      - ".asciidoctor-lint.yml"
       - "AGENTS.md"
+      - "anthropic/**"
       - "docs/**"
       - "instructions/**"
       - "shared/**"
-      - "anthropic/**"
-      - "scripts/**"
       - "!.scratch/*/artefacts/**"
       - "!.scratch/*/artifacts/**"
   workflow_dispatch:
@@ -62,19 +62,7 @@ jobs:
         id: diff
         shell: bash
         run: |
-          base="${{ github.event.pull_request.base.sha }}"
-          head="${{ github.event.pull_request.head.sha }}"
-          if [ -z "${base}" ]; then
-            base="${{ github.event.before }}"
-          fi
-          if [ -z "${head}" ]; then
-            head="${{ github.sha }}"
-          fi
-          if [ -z "${base}" ] || [ "${base}" = "0000000000000000000000000000000000000000" ]; then
-            base=$(git rev-list --max-parents=0 "${head}" | tail -n 1)
-          fi
-          echo "base=${base}" >> "$GITHUB_OUTPUT"
-          echo "head=${head}" >> "$GITHUB_OUTPUT"
+          bash .github/workflows/scripts/ci/determin-diff-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" "${{ github.event.before }}" "${{ github.sha }}"
 
       - name: Setup Node (for markdownlint)
         uses: actions/setup-node@v6
@@ -87,118 +75,39 @@ jobs:
           ruby-version: "3.3"
 
       - name: Install linters
+        shell: bash
         run: |
-          python -m pip install --upgrade pip
-          pip install yamllint
-          npm install -g markdownlint-cli
-          gem install asciidoctor
-          sudo apt-get update
-          sudo apt-get install -y shellcheck
+          bash .github/workflows/scripts/config-lint/install-linters.sh
 
       - name: Lint YAML
         shell: bash
         run: |
-          mkdir -p reports
-          files=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.yml' '*.yaml' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          if [ -n "${files}" ]; then
-            set +e
-            echo "$files" | xargs -I{} yamllint -s "{}" 2>&1 | tee reports/yamllint.txt
-            rc=${PIPESTATUS[1]}
-            if [ "$rc" -ne 0 ]; then
-              echo "::error::yamllint failed (rc=$rc). See reports/yamllint.txt."
-              exit "$rc"
-            fi
-          else
-            echo "No YAML files found." > reports/yamllint.txt
-          fi
+          bash .github/workflows/scripts/config-lint/lint-yaml.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Validate JSON syntax
         shell: bash
         run: |
-          mkdir -p reports
-          files=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.json' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          if [ -n "${files}" ]; then
-            set +e
-            echo "$files" | xargs -I{} python -m json.tool "{}" > /dev/null
-            rc=${PIPESTATUS[1]}
-            if [ "$rc" -ne 0 ]; then
-              echo "::error::JSON syntax validation failed (rc=$rc)."
-              exit "$rc"
-            fi
-            printf "Validated %s JSON files.\n" "$(echo "$files" | wc -l | tr -d ' ')" > reports/jsonlint.txt
-          else
-            echo "No JSON files found." > reports/jsonlint.txt
-          fi
+          bash .github/workflows/scripts/config-lint/validate-json.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Lint Markdown
         shell: bash
         run: |
-          mkdir -p reports
-          files=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.md' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          if [ -n "${files}" ]; then
-            set +e
-            echo "$files" | xargs -I{} markdownlint "{}" --config .markdownlint.json 2>&1 | tee reports/markdownlint.txt
-            rc=${PIPESTATUS[1]}
-            if [ "$rc" -ne 0 ]; then
-              echo "::error::markdownlint failed (rc=$rc). See reports/markdownlint.txt."
-              exit "$rc"
-            fi
-          else
-            echo "No Markdown files found." > reports/markdownlint.txt
-          fi
+          bash .github/workflows/scripts/config-lint/lint-markdown.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Lint AsciiDoc
         shell: bash
         run: |
-          mkdir -p reports
-          files=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.adoc' '*.asciidoc' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          if [ -n "${files}" ]; then
-            # asciidoctor validates document structure/parsing
-            set +e
-            echo "$files" | xargs -I{} asciidoctor -o /dev/null "{}" 2>&1 | tee reports/asciidoctor-parse.txt
-            parse_rc=${PIPESTATUS[1]}
-            if [ "$parse_rc" -ne 0 ]; then
-              echo "::error::asciidoctor parse validation failed (rc=$parse_rc). See reports/asciidoctor-parse.txt."
-              exit "$parse_rc"
-            fi
-            cp reports/asciidoctor-parse.txt reports/asciidoctor-lint.txt
-          else
-            echo "No AsciiDoc files found." > reports/asciidoctor-lint.txt
-          fi
+          bash .github/workflows/scripts/config-lint/lint-asciidoc.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Lint shell scripts
         shell: bash
         run: |
-          mkdir -p reports
-          files=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.sh' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          if [ -n "${files}" ]; then
-            set +e
-            echo "$files" | xargs -I{} shellcheck "{}" 2>&1 | tee reports/shellcheck.txt
-            rc=${PIPESTATUS[1]}
-            if [ "$rc" -ne 0 ]; then
-              echo "::error::shellcheck failed (rc=$rc). See reports/shellcheck.txt."
-              exit "$rc"
-            fi
-          else
-            echo "No shell scripts found." > reports/shellcheck.txt
-          fi
+          bash .github/workflows/scripts/config-lint/lint-shell.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Validate JavaScript syntax
         shell: bash
         run: |
-          mkdir -p reports
-          files=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.js' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          if [ -n "${files}" ]; then
-            set +e
-            echo "$files" | xargs -I{} node --check "{}" 2>&1 | tee reports/js-syntax.txt
-            rc=${PIPESTATUS[1]}
-            if [ "$rc" -ne 0 ]; then
-              echo "::error::JavaScript syntax validation failed (rc=$rc). See reports/js-syntax.txt."
-              exit "$rc"
-            fi
-          else
-            echo "No JavaScript files found." > reports/js-syntax.txt
-          fi
+          bash .github/workflows/scripts/config-lint/validate-js-syntax.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Upload lint reports
         if: always()
@@ -211,18 +120,4 @@ jobs:
         if: always()
         shell: bash
         run: |
-          set +e
-          {
-            echo "## config-lint summary"
-            echo "- YAML: see reports/yamllint.txt"
-            echo "- JSON: see reports/jsonlint.txt"
-            echo "- Markdown: see reports/markdownlint.txt"
-            echo "- AsciiDoc: see reports/asciidoctor-lint.txt"
-            echo "- Shell: see reports/shellcheck.txt"
-            echo "- JavaScript syntax: see reports/js-syntax.txt"
-          } >> "$GITHUB_STEP_SUMMARY"
-          rc=$?
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::Failed to write config-lint job summary (rc=$rc)."
-            exit "$rc"
-          fi
+          bash .github/workflows/scripts/config-lint/write-summary.sh
diff --git a/.github/workflows/dependabot-auto-merge.yml b/.github/workflows/dependabot-auto-merge.yml
index 59253a0..f3e854f 100644
--- a/.github/workflows/dependabot-auto-merge.yml
+++ b/.github/workflows/dependabot-auto-merge.yml
@@ -27,4 +27,6 @@ jobs:
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PR_URL: ${{ github.event.pull_request.html_url }}
-        run: gh pr merge "$PR_URL" --auto --squash
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/dependabot-auto-merge/enable-auto-merge.sh
diff --git a/.github/workflows/policy-check.yml b/.github/workflows/policy-check.yml
index f0bf973..94b98ce 100644
--- a/.github/workflows/policy-check.yml
+++ b/.github/workflows/policy-check.yml
@@ -3,49 +3,49 @@ name: policy-check
 on:
   pull_request:
     paths:
+      - "**/*.adoc"
+      - "**/*.asciidoc"
+      - "**/*.json"
+      - "**/*.md"
       - "**/*.ps1"
-      - "**/*.psm1"
       - "**/*.psd1"
+      - "**/*.psm1"
       - "**/*.py"
       - "**/*.sh"
-      - "**/*.md"
-      - "**/*.adoc"
-      - "**/*.asciidoc"
-      - "**/*.json"
-      - "**/*.yml"
       - "**/*.yaml"
+      - "**/*.yml"
       - ".github/**"
+      - ".github/workflows/scripts/**"
+      - ".scratch/**"
       - "AGENTS.md"
-      - "coding-policies/**"
-      - "shared/**"
-      - "instructions/**"
       - "anthropic/**"
-      - "scripts/**"
+      - "coding-policies/**"
       - "docs/**"
-      - ".scratch/**"
+      - "instructions/**"
+      - "shared/**"
   push:
     branches: [main]
     paths:
+      - "**/*.adoc"
+      - "**/*.asciidoc"
+      - "**/*.json"
+      - "**/*.md"
       - "**/*.ps1"
-      - "**/*.psm1"
       - "**/*.psd1"
+      - "**/*.psm1"
       - "**/*.py"
       - "**/*.sh"
-      - "**/*.md"
-      - "**/*.adoc"
-      - "**/*.asciidoc"
-      - "**/*.json"
-      - "**/*.yml"
       - "**/*.yaml"
+      - "**/*.yml"
       - ".github/**"
+      - ".github/workflows/scripts/**"
+      - ".scratch/**"
       - "AGENTS.md"
-      - "coding-policies/**"
-      - "shared/**"
-      - "instructions/**"
       - "anthropic/**"
-      - "scripts/**"
+      - "coding-policies/**"
       - "docs/**"
-      - ".scratch/**"
+      - "instructions/**"
+      - "shared/**"
   workflow_dispatch:
 
 concurrency:
@@ -61,46 +61,19 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
 
-      - name: Enforce repo guardrails
+      - name: Determine diff range
+        id: diff
         shell: bash
         run: |
-          set +e
-          mkdir -p reports
+          bash .github/workflows/scripts/ci/determin-diff-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" "${{ github.event.before }}" "${{ github.sha }}"
 
-          # 1) Block obvious hardcoded secrets in tracked repo files.
-          files=$(git ls-files)
-          list_rc=$?
-          if [ "$list_rc" -ne 0 ]; then
-            echo "::error::Failed to list tracked files for guardrails (rc=$list_rc)."
-            exit "$list_rc"
-          fi
-          if [ -n "${files}" ]; then
-            secret_matches=$(echo "${files}" | xargs -d '\n' grep -IInE "(api[_-]?key|secret|token|password)\s*[:=]\s*['\"][^'\"]+['\"]" || true)
-            if [ -n "${secret_matches}" ]; then
-              echo "${secret_matches}"
-              echo "Potential hardcoded secret detected."
-              exit 1
-            fi
-          fi
-
-          # 2) Ensure PowerShell scripts use strict mode, excluding scratch artifacts.
-          ps_files=$(git ls-files '*.ps1' '*.psm1' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          ps_list_rc=$?
-          if [ "$ps_list_rc" -ne 0 ]; then
-            echo "::error::Failed to enumerate PowerShell files for guardrails (rc=$ps_list_rc)."
-            exit "$ps_list_rc"
-          fi
-          if [ -n "${ps_files}" ]; then
-            missing=$(echo "${ps_files}" | xargs -I{} sh -c "grep -q 'Set-StrictMode' '{}' || echo '{}'")
-            if [ -n "${missing}" ]; then
-              echo "Missing Set-StrictMode in:"
-              echo "${missing}"
-              exit 1
-            fi
-          fi
-
-          echo "Policy checks passed." > reports/policy-check.txt
+      - name: Enforce repo guardrails
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/policy-check/enforce-repo-guardrails.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Setup Python (policy validation)
         uses: actions/setup-python@v6
@@ -110,25 +83,7 @@ jobs:
       - name: Validate coding policies
         shell: bash
         run: |
-          set +e
-          python -m pip install --upgrade pip
-          pip_up_rc=$?
-          if [ "$pip_up_rc" -ne 0 ]; then
-            echo "::error::pip upgrade failed (rc=$pip_up_rc)."
-            exit "$pip_up_rc"
-          fi
-          pip install pyyaml
-          pyyaml_rc=$?
-          if [ "$pyyaml_rc" -ne 0 ]; then
-            echo "::error::pyyaml installation failed (rc=$pyyaml_rc)."
-            exit "$pyyaml_rc"
-          fi
-          python scripts/validate-coding-policies.py
-          policy_rc=$?
-          if [ "$policy_rc" -ne 0 ]; then
-            echo "::error::coding policy validation failed (rc=$policy_rc)."
-            exit "$policy_rc"
-          fi
+          bash .github/workflows/scripts/policy-check/validate-coding-policies.sh
 
       - name: Upload policy reports
         if: always()
@@ -141,14 +96,4 @@ jobs:
         if: always()
         shell: bash
         run: |
-          set +e
-          {
-            echo "## policy-check summary"
-            echo "- Guardrail log: reports/policy-check.txt"
-            echo "- Coding policy log: reports/coding-policy-check.txt"
-          } >> "$GITHUB_STEP_SUMMARY"
-          rc=$?
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::Failed to write policy-check job summary (rc=$rc)."
-            exit "$rc"
-          fi
+          bash .github/workflows/scripts/policy-check/write-summary.sh
diff --git a/.github/workflows/powershell-quality.yml b/.github/workflows/powershell-quality.yml
index f12eb55..91decac 100644
--- a/.github/workflows/powershell-quality.yml
+++ b/.github/workflows/powershell-quality.yml
@@ -4,22 +4,22 @@ on:
   pull_request:
     paths:
       - "**/*.ps1"
-      - "**/*.psm1"
       - "**/*.psd1"
-      - "coding-policies/polyglot-policy.yaml"
-      - "coding-policies/languages/powershell-policy.yaml"
+      - "**/*.psm1"
       - ".github/workflows/powershell-quality.yml"
+      - "coding-policies/languages/powershell-policy.yaml"
+      - "coding-policies/polyglot-policy.yaml"
       - "!.scratch/*/artefacts/**"
       - "!.scratch/*/artifacts/**"
   push:
     branches: [main]
     paths:
       - "**/*.ps1"
-      - "**/*.psm1"
       - "**/*.psd1"
-      - "coding-policies/polyglot-policy.yaml"
-      - "coding-policies/languages/powershell-policy.yaml"
+      - "**/*.psm1"
       - ".github/workflows/powershell-quality.yml"
+      - "coding-policies/languages/powershell-policy.yaml"
+      - "coding-policies/polyglot-policy.yaml"
       - "!.scratch/*/artefacts/**"
       - "!.scratch/*/artifacts/**"
   workflow_dispatch:
@@ -44,53 +44,25 @@ jobs:
         id: diff
         shell: bash
         run: |
-          base="${{ github.event.pull_request.base.sha }}"
-          head="${{ github.event.pull_request.head.sha }}"
-          if [ -z "${base}" ]; then
-            base="${{ github.event.before }}"
-          fi
-          if [ -z "${head}" ]; then
-            head="${{ github.sha }}"
-          fi
-          if [ -z "${base}" ] || [ "${base}" = "0000000000000000000000000000000000000000" ]; then
-            base=$(git rev-list --max-parents=0 "${head}" | tail -n 1)
-          fi
-          echo "base=${base}" >> "$GITHUB_OUTPUT"
-          echo "head=${head}" >> "$GITHUB_OUTPUT"
+          bash .github/workflows/scripts/ci/determin-diff-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" "${{ github.event.before }}" "${{ github.sha }}"
 
       - name: Find PowerShell files
         id: psfiles
         shell: bash
         run: |
-          set +e
-          count=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.ps1' '*.psm1' '*.psd1' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**' | wc -l | tr -d ' ')
-          rc=${PIPESTATUS[0]}
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::Failed to enumerate PowerShell files (rc=$rc)."
-            exit "$rc"
-          fi
-          echo "count=$count" >> "$GITHUB_OUTPUT"
+          bash .github/workflows/scripts/powershell-quality/find-powershell-files.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Run PSScriptAnalyzer
         if: steps.psfiles.outputs.count != '0'
-        shell: pwsh
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/powershell-quality/run-psscriptanalyzer.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
+
+      - name: Validate PowerShell syntax (pwsh Core)
+        if: steps.psfiles.outputs.count != '0'
+        shell: bash
         run: |
-          New-Item -ItemType Directory -Force -Path reports | Out-Null
-          Set-PSRepository PSGallery -InstallationPolicy Trusted
-          Install-Module PSScriptAnalyzer -Scope CurrentUser -Force
-          $files = git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.ps1' '*.psm1' '*.psd1' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**' |
-            Where-Object { -not [string]::IsNullOrWhiteSpace($_) }
-          $results = foreach ($file in $files) {
-            Invoke-ScriptAnalyzer -Path $file -Severity Warning,Error -ExcludeRule PSUseSingularNouns,PSAvoidUsingWriteHost,PSUseBOMForUnicodeEncodedFile
-          }
-          if ($results) {
-            $formatted = $results | Format-Table -AutoSize | Out-String
-            $formatted | Tee-Object -FilePath reports/psscriptanalyzer.txt
-            throw "PSScriptAnalyzer found issues."
-          } else {
-            "No PSScriptAnalyzer issues found." | Out-File -FilePath reports/psscriptanalyzer.txt -Encoding utf8
-            Write-Host "No PSScriptAnalyzer issues found."
-          }
+          bash .github/workflows/scripts/powershell-quality/validate-powershell-syntax.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Upload PowerShell reports
         if: always() && steps.psfiles.outputs.count != '0'
@@ -103,14 +75,4 @@ jobs:
         if: always()
         shell: bash
         run: |
-          set +e
-          {
-            echo "## powershell-quality summary"
-            echo "- PowerShell files found: ${{ steps.psfiles.outputs.count }}"
-            echo "- Analyzer report: reports/psscriptanalyzer.txt"
-          } >> "$GITHUB_STEP_SUMMARY"
-          rc=$?
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::Failed to write powershell-quality job summary (rc=$rc)."
-            exit "$rc"
-          fi
+          bash .github/workflows/scripts/powershell-quality/write-summary.sh "${{ steps.psfiles.outputs.count }}"
diff --git a/.github/workflows/powershell-runtime-compat.yml b/.github/workflows/powershell-runtime-compat.yml
new file mode 100644
index 0000000..a105b88
--- /dev/null
+++ b/.github/workflows/powershell-runtime-compat.yml
@@ -0,0 +1,70 @@
+name: powershell-runtime-compat
+
+on:
+  pull_request:
+    paths:
+      - "**/*.ps1"
+      - "**/*.psd1"
+      - "**/*.psm1"
+      - ".github/workflows/powershell-runtime-compat.yml"
+      - ".github/workflows/scripts/validate-powershell-runtime.py"
+      - "coding-policies/languages/powershell-policy.yaml"
+      - "!.scratch/*/artefacts/**"
+      - "!.scratch/*/artifacts/**"
+  push:
+    branches: [main]
+    paths:
+      - "**/*.ps1"
+      - "**/*.psd1"
+      - "**/*.psm1"
+      - ".github/workflows/powershell-runtime-compat.yml"
+      - ".github/workflows/scripts/validate-powershell-runtime.py"
+      - "coding-policies/languages/powershell-policy.yaml"
+      - "!.scratch/*/artefacts/**"
+      - "!.scratch/*/artifacts/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  powershell-runtime-compat:
+    runs-on: windows-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Determine diff range
+        id: diff
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/ci/determin-diff-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" "${{ github.event.before }}" "${{ github.sha }}"
+
+      - name: Validate pwsh syntax (core-first + dual-runtime)
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/powershell-runtime-compat/validate-pwsh-syntax.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
+
+      - name: Validate Windows PowerShell syntax (dual-runtime + desktop-only)
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/powershell-runtime-compat/validate-windowsps-syntax.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
+
+      - name: Upload runtime-compat reports
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: powershell-runtime-compat-reports
+          path: reports
+
+      - name: Add job summary
+        if: always()
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/powershell-runtime-compat/write-summary.sh
diff --git a/.github/workflows/powershell-tests.yml b/.github/workflows/powershell-tests.yml
new file mode 100644
index 0000000..8c43ca4
--- /dev/null
+++ b/.github/workflows/powershell-tests.yml
@@ -0,0 +1,62 @@
+name: powershell-tests
+
+on:
+  pull_request:
+    paths:
+      - "**/*.Tests.ps1"
+      - ".github/workflows/powershell-tests.yml"
+      - "!.scratch/*/artefacts/**"
+      - "!.scratch/*/artifacts/**"
+  push:
+    branches: [main]
+    paths:
+      - "**/*.Tests.ps1"
+      - ".github/workflows/powershell-tests.yml"
+      - "!.scratch/*/artefacts/**"
+      - "!.scratch/*/artifacts/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  powershell-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Determine diff range
+        id: diff
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/ci/determin-diff-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" "${{ github.event.before }}" "${{ github.sha }}"
+
+      - name: Install Pester
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/powershell-tests/install-pester.sh
+
+      - name: Discover test files
+        id: discover
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/powershell-tests/discover-test-files.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
+
+      - name: Run Pester
+        if: steps.discover.outputs.count != '0'
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/powershell-tests/run-pester.sh "${{ steps.discover.outputs.files }}"
+
+      - name: No tests found
+        if: steps.discover.outputs.count == '0'
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/powershell-tests/no-tests-found.sh
diff --git a/.github/workflows/python-quality.yml b/.github/workflows/python-quality.yml
index 6582f06..eaf92fa 100644
--- a/.github/workflows/python-quality.yml
+++ b/.github/workflows/python-quality.yml
@@ -4,20 +4,20 @@ on:
   pull_request:
     paths:
       - "**/*.py"
+      - ".github/workflows/python-quality.yml"
       - "pyproject.toml"
       - "ruff.toml"
       - "setup.cfg"
-      - ".github/workflows/python-quality.yml"
       - "!.scratch/*/artefacts/**"
       - "!.scratch/*/artifacts/**"
   push:
     branches: [main]
     paths:
       - "**/*.py"
+      - ".github/workflows/python-quality.yml"
       - "pyproject.toml"
       - "ruff.toml"
       - "setup.cfg"
-      - ".github/workflows/python-quality.yml"
       - "!.scratch/*/artefacts/**"
       - "!.scratch/*/artifacts/**"
   workflow_dispatch:
@@ -42,19 +42,7 @@ jobs:
         id: diff
         shell: bash
         run: |
-          base="${{ github.event.pull_request.base.sha }}"
-          head="${{ github.event.pull_request.head.sha }}"
-          if [ -z "${base}" ]; then
-            base="${{ github.event.before }}"
-          fi
-          if [ -z "${head}" ]; then
-            head="${{ github.sha }}"
-          fi
-          if [ -z "${base}" ] || [ "${base}" = "0000000000000000000000000000000000000000" ]; then
-            base=$(git rev-list --max-parents=0 "${head}" | tail -n 1)
-          fi
-          echo "base=${base}" >> "$GITHUB_OUTPUT"
-          echo "head=${head}" >> "$GITHUB_OUTPUT"
+          bash .github/workflows/scripts/ci/determin-diff-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" "${{ github.event.before }}" "${{ github.sha }}"
 
       - name: Setup Python
         uses: actions/setup-python@v6
@@ -62,50 +50,27 @@ jobs:
           python-version: "3.11"
 
       - name: Install tools
+        shell: bash
         run: |
-          python -m pip install --upgrade pip
-          pip install ruff
+          bash .github/workflows/scripts/python-quality/install-tools.sh
 
       - name: Find Python files
         id: pyfiles
         shell: bash
         run: |
-          set +e
-          count=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.py' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**' | wc -l | tr -d ' ')
-          rc=${PIPESTATUS[0]}
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::Failed to enumerate Python files (rc=$rc)."
-            exit "$rc"
-          fi
-          echo "count=$count" >> "$GITHUB_OUTPUT"
+          bash .github/workflows/scripts/python-quality/find-python-files.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Ruff check
         if: steps.pyfiles.outputs.count != '0'
         shell: bash
         run: |
-          mkdir -p reports
-          files=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.py' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          set +e
-          echo "$files" | xargs -I{} ruff check "{}" 2>&1 | tee reports/ruff-check.txt
-          rc=${PIPESTATUS[1]}
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::ruff check failed (rc=$rc). See reports/ruff-check.txt."
-            exit "$rc"
-          fi
+          bash .github/workflows/scripts/python-quality/ruff-check.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Ruff format check
         if: steps.pyfiles.outputs.count != '0'
         shell: bash
         run: |
-          mkdir -p reports
-          files=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.py' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          set +e
-          echo "$files" | xargs -I{} ruff format --check "{}" 2>&1 | tee reports/ruff-format-check.txt
-          rc=${PIPESTATUS[1]}
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::ruff format check failed (rc=$rc). See reports/ruff-format-check.txt."
-            exit "$rc"
-          fi
+          bash .github/workflows/scripts/python-quality/ruff-format-check.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Upload python reports
         if: always() && steps.pyfiles.outputs.count != '0'
@@ -118,15 +83,4 @@ jobs:
         if: always()
         shell: bash
         run: |
-          set +e
-          {
-            echo "## python-quality summary"
-            echo "- Python files found: ${{ steps.pyfiles.outputs.count }}"
-            echo "- Ruff check report: reports/ruff-check.txt"
-            echo "- Ruff format report: reports/ruff-format-check.txt"
-          } >> "$GITHUB_STEP_SUMMARY"
-          rc=$?
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::Failed to write python-quality job summary (rc=$rc)."
-            exit "$rc"
-          fi
+          bash .github/workflows/scripts/python-quality/write-summary.sh "${{ steps.pyfiles.outputs.count }}"
diff --git a/.github/workflows/python-tests.yml b/.github/workflows/python-tests.yml
new file mode 100644
index 0000000..e7daf08
--- /dev/null
+++ b/.github/workflows/python-tests.yml
@@ -0,0 +1,69 @@
+name: python-tests
+
+on:
+  pull_request:
+    paths:
+      - "**/*.py"
+      - ".github/workflows/python-tests.yml"
+      - "ai-artifacts/**/tests/**"
+      - "!.scratch/*/artefacts/**"
+      - "!.scratch/*/artifacts/**"
+  push:
+    branches: [main]
+    paths:
+      - "**/*.py"
+      - ".github/workflows/python-tests.yml"
+      - "ai-artifacts/**/tests/**"
+      - "!.scratch/*/artefacts/**"
+      - "!.scratch/*/artifacts/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  python-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Determine diff range
+        id: diff
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/ci/determin-diff-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" "${{ github.event.before }}" "${{ github.sha }}"
+
+      - name: Setup Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+
+      - name: Install test dependencies
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/python-tests/install-test-dependencies.sh
+
+      - name: Discover test files
+        id: discover
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/python-tests/discover-test-files.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
+
+      - name: Run pytest
+        if: steps.discover.outputs.count != '0'
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/python-tests/run-pytest.sh "${{ steps.discover.outputs.files }}"
+
+      - name: No tests found
+        if: steps.discover.outputs.count == '0'
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/python-tests/no-tests-found.sh
diff --git a/.github/workflows/scripts/README.md b/.github/workflows/scripts/README.md
new file mode 100644
index 0000000..d912786
--- /dev/null
+++ b/.github/workflows/scripts/README.md
@@ -0,0 +1,34 @@
+# Workflow Execution Model
+
+This repository uses two complementary execution processes.
+
+## 1) GitHub Actions execution
+
+- Runs on GitHub runners.
+- Defined by workflow files in `.github/workflows/*.yml`.
+- Executes shell steps declared directly in each workflow `run:` block (for example the diff-range step that calls `Resolve-DiffRange.ps1`).
+
+## 2) Local execution
+
+- Runs on a developer machine.
+- Defined by workflow executors in `.github/workflows/scripts/execute-workflow-*.ps1`.
+- Each `execute-workflow-*` script executes the same workflow shell logic in the same order for its workflow.
+
+## Global simulator
+
+- `scripts/simulate-workflows.ps1` is the local entry point.
+- It calls `ai-artifacts/skills/shared/workflow/simulate-workflows/scripts/Invoke-LocalWorkflowSimulation.ps1`.
+- The simulator then executes `.github/workflows/scripts/execute-all-workflow-scripts.ps1`.
+- The master script runs all `execute-workflow-*` scripts in deterministic order.
+
+## Current local workflow executors
+
+- `execute-workflow-policy-check.ps1`
+- `execute-workflow-python-quality.ps1`
+- `execute-workflow-python-tests.ps1`
+- `execute-workflow-powershell-quality.ps1`
+- `execute-workflow-powershell-tests.ps1`
+- `execute-workflow-powershell-runtime-compat.ps1`
+- `execute-workflow-shell-quality.ps1`
+- `execute-workflow-shell-tests.ps1`
+- `execute-workflow-config-lint.ps1`
diff --git a/.github/workflows/scripts/ci/Get-ChangedFiles.ps1 b/.github/workflows/scripts/ci/Get-ChangedFiles.ps1
new file mode 100644
index 0000000..0c49458
--- /dev/null
+++ b/.github/workflows/scripts/ci/Get-ChangedFiles.ps1
@@ -0,0 +1,74 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Base,
+    [Parameter(Mandatory = $true)]
+    [string]$Head,
+    [string]$RepoRoot = "",
+    [string[]]$Include = @("*"),
+    [string[]]$Exclude = @(),
+    [switch]$DisableDefaultExcludes,
+    [switch]$FullScan,
+    [switch]$OutputCount
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($RepoRoot)) {
+    $RepoRoot = (& git rev-parse --show-toplevel 2>$null)
+    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($RepoRoot)) {
+        throw "Unable to resolve repo root. Run inside a git repository or pass -RepoRoot."
+    }
+}
+
+$resolvedExclude = [System.Collections.Generic.List[string]]::new()
+foreach ($pattern in $Exclude) {
+    if (-not [string]::IsNullOrWhiteSpace($pattern)) { $resolvedExclude.Add($pattern) }
+}
+
+if (-not $DisableDefaultExcludes) {
+    foreach ($pattern in @('.scratch/*/artefacts/**', '.scratch/*/artifacts/**')) {
+        if (-not $resolvedExclude.Contains($pattern)) {
+            $resolvedExclude.Add($pattern)
+        }
+    }
+}
+
+$autoFullScan = $env:GITHUB_EVENT_NAME -eq 'push' -and $env:GITHUB_REF -eq 'refs/heads/main'
+$useFullScan = $FullScan -or $autoFullScan
+
+$pathspecs = [System.Collections.Generic.List[string]]::new()
+foreach ($pattern in $Include) {
+    if (-not [string]::IsNullOrWhiteSpace($pattern)) { $pathspecs.Add($pattern) }
+}
+foreach ($pattern in $resolvedExclude) {
+    if (-not [string]::IsNullOrWhiteSpace($pattern)) { $pathspecs.Add(":(exclude)$pattern") }
+}
+
+$files = @()
+if ($useFullScan) {
+    $files = & git -C $RepoRoot ls-files -- @pathspecs
+    if ($LASTEXITCODE -ne 0) {
+        throw "Failed to enumerate tracked files via git ls-files."
+    }
+}
+else {
+    $files = & git -C $RepoRoot diff --name-only --diff-filter=ACMRTUXB $Base $Head -- @pathspecs
+    if ($LASTEXITCODE -ne 0) {
+        throw "Failed to enumerate changed files for range $Base..$Head."
+    }
+}
+
+$clean = @($files | Where-Object { -not [string]::IsNullOrWhiteSpace($_) })
+
+if ($OutputCount) {
+    $clean.Count
+    return
+}
+
+$clean
diff --git a/.github/workflows/scripts/ci/Resolve-DiffRange.ps1 b/.github/workflows/scripts/ci/Resolve-DiffRange.ps1
new file mode 100644
index 0000000..cdf3b5c
--- /dev/null
+++ b/.github/workflows/scripts/ci/Resolve-DiffRange.ps1
@@ -0,0 +1,50 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+    [string]$Base = "",
+    [string]$Head = "",
+    [string]$Before = "",
+    [string]$Sha = "",
+    [string]$RepoRoot = "",
+    [switch]$WriteGithubOutput
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+if ([string]::IsNullOrWhiteSpace($RepoRoot)) {
+    $RepoRoot = (& git rev-parse --show-toplevel 2>$null)
+    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($RepoRoot)) {
+        throw "Unable to resolve repo root. Run inside a git repository or pass -RepoRoot."
+    }
+}
+
+if ([string]::IsNullOrWhiteSpace($Base)) { $Base = $Before }
+if ([string]::IsNullOrWhiteSpace($Head)) { $Head = $Sha }
+
+if ([string]::IsNullOrWhiteSpace($Head)) {
+    throw "Head SHA is empty. Pass -Head or -Sha."
+}
+
+if ([string]::IsNullOrWhiteSpace($Base) -or $Base -eq "0000000000000000000000000000000000000000") {
+    $Base = (& git -C $RepoRoot rev-list --max-parents=0 $Head | Select-Object -Last 1)
+    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($Base)) {
+        throw "Failed to resolve fallback base commit from head '$Head'."
+    }
+}
+
+if ($WriteGithubOutput) {
+    if ([string]::IsNullOrWhiteSpace($env:GITHUB_OUTPUT)) {
+        throw "GITHUB_OUTPUT is not set; cannot write workflow outputs."
+    }
+    "base=$Base" >> $env:GITHUB_OUTPUT
+    "head=$Head" >> $env:GITHUB_OUTPUT
+}
+
+[PSCustomObject]@{
+    base = $Base
+    head = $Head
+}
diff --git a/.github/workflows/scripts/ci/WorkflowScript.Common.ps1 b/.github/workflows/scripts/ci/WorkflowScript.Common.ps1
new file mode 100644
index 0000000..cda379b
--- /dev/null
+++ b/.github/workflows/scripts/ci/WorkflowScript.Common.ps1
@@ -0,0 +1,268 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$script:WorkflowIndentLevel = 0
+$script:WorkflowCurrentFailures = [System.Collections.Generic.List[string]]::new()
+$script:WorkflowCurrentName = "workflow"
+
+function Get-WorkflowIndent {
+  return ('  ' * $script:WorkflowIndentLevel)
+}
+
+function Write-WorkflowLine {
+  param(
+    [AllowEmptyString()]
+    [string]$Text = ''
+  )
+
+  if ([string]::IsNullOrEmpty($Text)) {
+    Write-Output ''
+    return
+  }
+
+  $lines = $Text -split "`r?`n"
+  foreach ($line in $lines) {
+    Write-Output ((Get-WorkflowIndent) + $line)
+  }
+}
+
+function Assert-WorkflowCommandAvailable {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$Name,
+    [Parameter(Mandatory = $true)]
+    [string]$InstallHint
+  )
+
+  if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
+    throw "Required command '$Name' is not available. $InstallHint"
+  }
+}
+
+function Reset-WorkflowFailures {
+  param(
+    [string]$WorkflowName = "workflow"
+  )
+
+  $script:WorkflowCurrentName = $WorkflowName
+  $script:WorkflowCurrentFailures = [System.Collections.Generic.List[string]]::new()
+}
+
+function Get-WorkflowFailures {
+  return @($script:WorkflowCurrentFailures)
+}
+
+function Add-WorkflowFailure {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$Message
+  )
+
+  $script:WorkflowCurrentFailures.Add($Message) | Out-Null
+}
+
+function Get-WorkflowReportDirectory {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$RepoRoot
+  )
+
+  $envReportDir = $env:REPORTS_DIR
+  if (-not [string]::IsNullOrWhiteSpace($envReportDir)) {
+    if ([System.IO.Path]::IsPathRooted($envReportDir)) {
+      return $envReportDir
+    }
+    return (Join-Path $RepoRoot $envReportDir)
+  }
+
+  return (Join-Path $RepoRoot ".temp/Reports")
+}
+
+function Write-WorkflowStatusSummary {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$RepoRoot,
+    [string]$WorkflowName = ""
+  )
+
+  if ([string]::IsNullOrWhiteSpace($WorkflowName)) {
+    $WorkflowName = $script:WorkflowCurrentName
+  }
+
+  $reportDir = Get-WorkflowReportDirectory -RepoRoot $RepoRoot
+  New-Item -ItemType Directory -Path $reportDir -Force | Out-Null
+  $summaryPath = Join-Path $reportDir ("{0}-local-summary.txt" -f $WorkflowName)
+
+  $failures = @($script:WorkflowCurrentFailures)
+  if ($failures.Count -eq 0) {
+    @(
+      "Workflow: $WorkflowName",
+      "Status: SUCCESS",
+      "Timestamp: $(Get-Date -Format o)",
+      "No step failures recorded."
+    ) | Set-Content -Path $summaryPath -Encoding utf8
+
+    Write-WorkflowLine ("LOCAL WORKFLOW STATUS: SUCCESS ({0})" -f $WorkflowName)
+    Write-WorkflowLine ("Report: {0}" -f $summaryPath)
+    return [PSCustomObject]@{
+      WorkflowName = $WorkflowName
+      HasFailures  = $false
+      FailureCount = 0
+      ReportPath   = $summaryPath
+    }
+  }
+
+  $content = [System.Collections.Generic.List[string]]::new()
+  $content.Add("Workflow: $WorkflowName") | Out-Null
+  $content.Add("Status: FAILED") | Out-Null
+  $content.Add("Timestamp: $(Get-Date -Format o)") | Out-Null
+  $content.Add("Failure count: $($failures.Count)") | Out-Null
+  $content.Add("") | Out-Null
+  foreach ($failure in $failures) {
+    $content.Add("- $failure") | Out-Null
+  }
+  $content | Set-Content -Path $summaryPath -Encoding utf8
+
+  Write-WorkflowLine ("LOCAL WORKFLOW STATUS: FAILED ({0})" -f $WorkflowName)
+  Write-WorkflowLine ("Failure count: {0}" -f $failures.Count)
+  foreach ($failure in $failures) {
+    Write-WorkflowLine ("[FAIL] {0}" -f $failure)
+  }
+  Write-WorkflowLine ("Report: {0}" -f $summaryPath)
+
+  return [PSCustomObject]@{
+    WorkflowName = $WorkflowName
+    HasFailures  = $true
+    FailureCount = $failures.Count
+    ReportPath   = $summaryPath
+  }
+}
+
+function Invoke-WorkflowStep {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$Name,
+    [Parameter(Mandatory = $true)]
+    [scriptblock]$Action
+  )
+
+  Write-WorkflowLine "== $Name =="
+  $script:WorkflowIndentLevel++
+  try {
+    & $Action 2>&1 | ForEach-Object {
+      if ($_ -is [System.Management.Automation.ErrorRecord]) {
+        Write-WorkflowLine ($_.ToString())
+      }
+      else {
+        Write-WorkflowLine ([string]$_)
+      }
+    }
+  }
+  catch {
+    $message = "{0}: {1}" -f $Name, $_.Exception.Message
+    Add-WorkflowFailure -Message $message
+    Write-WorkflowLine ("[LOCAL FAILURE] {0}" -f $message)
+  }
+  finally {
+    $script:WorkflowIndentLevel--
+  }
+}
+
+function Resolve-WorkflowRepoRoot {
+  param(
+    [string]$RepoRoot,
+    [string]$CallerRoot
+  )
+
+  if ([string]::IsNullOrWhiteSpace($RepoRoot)) {
+    $RepoRoot = (& git -C $CallerRoot rev-parse --show-toplevel 2>$null)
+    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($RepoRoot)) {
+      throw "Unable to determine repo root. Run from inside the repo or pass -RepoRoot."
+    }
+  }
+
+  $resolved = (Resolve-Path $RepoRoot).Path
+  if (-not (Test-Path (Join-Path $resolved ".git"))) {
+    throw "Repo root is invalid: $resolved"
+  }
+  return $resolved
+}
+
+function Resolve-WorkflowDiffRange {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$RepoRoot,
+    [string]$Base,
+    [string]$Head
+  )
+
+  if ([string]::IsNullOrWhiteSpace($Head)) {
+    $Head = (& git -C $RepoRoot rev-parse HEAD)
+    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($Head)) {
+      throw "Unable to resolve HEAD commit."
+    }
+  }
+
+  if ([string]::IsNullOrWhiteSpace($Base)) {
+    $Base = (& git -C $RepoRoot rev-parse "$Head~1" 2>$null)
+    if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($Base)) {
+      $Base = (& git -C $RepoRoot rev-list --max-parents=0 $Head | Select-Object -Last 1)
+      if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($Base)) {
+        throw "Unable to resolve base commit."
+      }
+    }
+  }
+
+  return [PSCustomObject]@{
+    Base = $Base
+    Head = $Head
+  }
+}
+
+function Get-WorkflowFiles {
+  param(
+    [Parameter(Mandatory = $true)]
+    [string]$RepoRoot,
+    [Parameter(Mandatory = $true)]
+    [string]$Base,
+    [Parameter(Mandatory = $true)]
+    [string]$Head,
+    [Parameter(Mandatory = $true)]
+    [string[]]$Include,
+    [switch]$FullScan
+  )
+
+  $resolvedExclude = @('.scratch/*/artefacts/**', '.scratch/*/artifacts/**')
+  $pathspecs = [System.Collections.Generic.List[string]]::new()
+  foreach ($pattern in $Include) {
+    if (-not [string]::IsNullOrWhiteSpace($pattern)) {
+      $pathspecs.Add($pattern)
+    }
+  }
+  foreach ($pattern in $resolvedExclude) {
+    $pathspecs.Add(":(exclude)$pattern")
+  }
+
+  $autoFullScan = $env:GITHUB_EVENT_NAME -eq 'push' -and $env:GITHUB_REF -eq 'refs/heads/main'
+  $useFullScan = $FullScan -or $autoFullScan
+
+  $files = if ($useFullScan) {
+    & git -C $RepoRoot ls-files -- @pathspecs
+  }
+  else {
+    & git -C $RepoRoot diff --name-only --diff-filter=ACMRTUXB $Base $Head -- @pathspecs
+  }
+  if ($LASTEXITCODE -ne 0) {
+    throw "Failed to enumerate files for includes: $($Include -join ', ')."
+  }
+
+  return @(
+    $files |
+      Where-Object { -not [string]::IsNullOrWhiteSpace($_) } |
+      Where-Object { Test-Path -LiteralPath (Join-Path $RepoRoot $_) -PathType Leaf }
+  )
+}
diff --git a/.github/workflows/scripts/ci/determin-diff-range.sh b/.github/workflows/scripts/ci/determin-diff-range.sh
new file mode 100644
index 0000000..85fc09b
--- /dev/null
+++ b/.github/workflows/scripts/ci/determin-diff-range.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+base="${1:-}"
+head="${2:-}"
+before="${3:-}"
+sha="${4:-}"
+
+if [[ -z "${base}" ]]; then
+  base="${before}"
+fi
+
+if [[ -z "${head}" ]]; then
+  head="${sha}"
+fi
+
+if [[ -z "${head}" ]]; then
+  echo "Head SHA is empty. Pass head or sha." >&2
+  exit 1
+fi
+
+if [[ -z "${base}" || "${base}" == "0000000000000000000000000000000000000000" ]]; then
+  base="$(git rev-list --max-parents=0 "${head}" | tail -n 1)"
+  if [[ -z "${base}" ]]; then
+    echo "Failed to resolve fallback base commit from head '${head}'." >&2
+    exit 1
+  fi
+fi
+
+if [[ -z "${GITHUB_OUTPUT:-}" ]]; then
+  echo "GITHUB_OUTPUT is not set; cannot write workflow outputs." >&2
+  exit 1
+fi
+
+echo "base=${base}" >> "${GITHUB_OUTPUT}"
+echo "head=${head}" >> "${GITHUB_OUTPUT}"
diff --git a/.github/workflows/scripts/ci/get-changed-files.sh b/.github/workflows/scripts/ci/get-changed-files.sh
new file mode 100644
index 0000000..6288201
--- /dev/null
+++ b/.github/workflows/scripts/ci/get-changed-files.sh
@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+
+declare -a git_cmd=(git)
+
+base=""
+head=""
+repo_root=""
+output_count=0
+full_scan=0
+disable_default_excludes=0
+
+declare -a includes=()
+declare -a excludes=()
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --base)
+      base="${2:-}"
+      shift 2
+      ;;
+    --head)
+      head="${2:-}"
+      shift 2
+      ;;
+    --repo-root)
+      repo_root="${2:-}"
+      shift 2
+      ;;
+    --include)
+      includes+=("${2:-}")
+      shift 2
+      ;;
+    --exclude)
+      excludes+=("${2:-}")
+      shift 2
+      ;;
+    --disable-default-excludes)
+      disable_default_excludes=1
+      shift
+      ;;
+    --full-scan)
+      full_scan=1
+      shift
+      ;;
+    --output-count)
+      output_count=1
+      shift
+      ;;
+    *)
+      echo "Unknown argument: $1" >&2
+      exit 2
+      ;;
+  esac
+done
+
+if [[ -z "${base}" || -z "${head}" ]]; then
+  echo "Both --base and --head are required." >&2
+  exit 2
+fi
+
+if [[ -z "${repo_root}" ]]; then
+  repo_root="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+  if [[ -z "${repo_root}" ]]; then
+    echo "Unable to resolve repo root. Run inside a git repository or pass --repo-root." >&2
+    exit 1
+  fi
+fi
+
+if ! "${git_cmd[@]}" -C "$repo_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  if [[ -n "${WSL_DISTRO_NAME:-}" ]] && command -v git.exe >/dev/null 2>&1 && command -v wslpath >/dev/null 2>&1; then
+    repo_root_win="$(wslpath -w "$repo_root" 2>/dev/null || true)"
+    if [[ -n "$repo_root_win" ]] && git.exe -C "$repo_root_win" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+      git_cmd=(git.exe)
+      repo_root="$repo_root_win"
+    fi
+  fi
+fi
+
+if ! "${git_cmd[@]}" -C "$repo_root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  echo "Unable to resolve a working git repository from '$repo_root'." >&2
+  exit 1
+fi
+
+if [[ ${#includes[@]} -eq 0 ]]; then
+  includes=("*")
+fi
+
+if [[ "$disable_default_excludes" -ne 1 ]]; then
+  need_artefacts=1
+  need_artifacts=1
+  for pattern in "${excludes[@]}"; do
+    [[ "$pattern" == ".scratch/*/artefacts/**" ]] && need_artefacts=0
+    [[ "$pattern" == ".scratch/*/artifacts/**" ]] && need_artifacts=0
+  done
+  [[ "$need_artefacts" -eq 1 ]] && excludes+=(".scratch/*/artefacts/**")
+  [[ "$need_artifacts" -eq 1 ]] && excludes+=(".scratch/*/artifacts/**")
+fi
+
+auto_full_scan=0
+if [[ "${GITHUB_EVENT_NAME:-}" == "push" && "${GITHUB_REF:-}" == "refs/heads/main" ]]; then
+  auto_full_scan=1
+fi
+
+use_full_scan=0
+if [[ "$full_scan" -eq 1 || "$auto_full_scan" -eq 1 ]]; then
+  use_full_scan=1
+fi
+
+declare -a pathspecs=()
+for pattern in "${includes[@]}"; do
+  [[ -n "$pattern" ]] && pathspecs+=("$pattern")
+done
+for pattern in "${excludes[@]}"; do
+  [[ -n "$pattern" ]] && pathspecs+=(":(exclude)$pattern")
+done
+
+if [[ "$use_full_scan" -eq 1 ]]; then
+  mapfile -t files < <("${git_cmd[@]}" -C "$repo_root" ls-files -- "${pathspecs[@]}")
+else
+  mapfile -t files < <("${git_cmd[@]}" -C "$repo_root" diff --name-only --diff-filter=ACMRTUXB "$base" "$head" -- "${pathspecs[@]}")
+fi
+
+cleaned=()
+for f in "${files[@]}"; do
+  [[ -n "$f" ]] && cleaned+=("$f")
+done
+
+if [[ "$output_count" -eq 1 ]]; then
+  echo "${#cleaned[@]}"
+  exit 0
+fi
+
+for f in "${cleaned[@]}"; do
+  echo "$f"
+done
diff --git a/.github/workflows/scripts/config-lint/execute-workflow-config-lint.ps1 b/.github/workflows/scripts/config-lint/execute-workflow-config-lint.ps1
new file mode 100644
index 0000000..75637c3
--- /dev/null
+++ b/.github/workflows/scripts/config-lint/execute-workflow-config-lint.ps1
@@ -0,0 +1,90 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "..") "ci/WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "config-lint"
+
+Invoke-WorkflowStep -Name "config-lint: prerequisites" -Action {
+  Assert-WorkflowCommandAvailable -Name "python" -InstallHint "Install Python 3.11+ and ensure it is on PATH."
+  Assert-WorkflowCommandAvailable -Name "bash" -InstallHint "Install bash to run config-lint scripts locally."
+}
+
+$runnerDir = Join-Path $RepoRoot ".github/workflows/scripts/config-lint"
+foreach ($script in @(
+  "install-linters.sh",
+  "lint-yaml.sh",
+  "validate-json.sh",
+  "lint-markdown.sh",
+  "lint-asciidoc.sh",
+  "lint-shell.sh",
+  "validate-js-syntax.sh"
+)) {
+  $path = Join-Path $runnerDir $script
+  if (-not (Test-Path -LiteralPath $path -PathType Leaf)) {
+    Add-WorkflowFailure -Message ("Missing config-lint helper script: {0}" -f $path)
+    Write-WorkflowLine ("[LOCAL FAILURE] Missing config-lint helper script: {0}" -f $path)
+  }
+}
+
+Push-Location $RepoRoot
+try {
+  if (@(Get-WorkflowFailures).Count -gt 0) {
+    Write-Output "Skipping config-lint checks due to prerequisite failures."
+  }
+  else {
+    Invoke-WorkflowStep -Name "config-lint: install linters" -Action {
+      & bash ".github/workflows/scripts/config-lint/install-linters.sh"
+      if ($LASTEXITCODE -ne 0) { throw "install-linters.sh failed." }
+    }
+
+    Invoke-WorkflowStep -Name "config-lint: yaml" -Action {
+      & bash ".github/workflows/scripts/config-lint/lint-yaml.sh" $range.Base $range.Head
+      if ($LASTEXITCODE -ne 0) { throw "lint-yaml.sh failed." }
+    }
+
+    Invoke-WorkflowStep -Name "config-lint: json syntax" -Action {
+      & bash ".github/workflows/scripts/config-lint/validate-json.sh" $range.Base $range.Head
+      if ($LASTEXITCODE -ne 0) { throw "validate-json.sh failed." }
+    }
+
+    Invoke-WorkflowStep -Name "config-lint: markdown" -Action {
+      & bash ".github/workflows/scripts/config-lint/lint-markdown.sh" $range.Base $range.Head
+      if ($LASTEXITCODE -ne 0) { throw "lint-markdown.sh failed." }
+    }
+
+    Invoke-WorkflowStep -Name "config-lint: asciidoc parse" -Action {
+      & bash ".github/workflows/scripts/config-lint/lint-asciidoc.sh" $range.Base $range.Head
+      if ($LASTEXITCODE -ne 0) { throw "lint-asciidoc.sh failed." }
+    }
+
+    Invoke-WorkflowStep -Name "config-lint: shellcheck" -Action {
+      & bash ".github/workflows/scripts/config-lint/lint-shell.sh" $range.Base $range.Head
+      if ($LASTEXITCODE -ne 0) { throw "lint-shell.sh failed." }
+    }
+
+    Invoke-WorkflowStep -Name "config-lint: javascript syntax" -Action {
+      & bash ".github/workflows/scripts/config-lint/validate-js-syntax.sh" $range.Base $range.Head
+      if ($LASTEXITCODE -ne 0) { throw "validate-js-syntax.sh failed." }
+    }
+  }
+}
+finally {
+  Pop-Location
+}
+
+$null = Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "config-lint"
diff --git a/.github/workflows/scripts/config-lint/install-linters.sh b/.github/workflows/scripts/config-lint/install-linters.sh
new file mode 100644
index 0000000..0b3b083
--- /dev/null
+++ b/.github/workflows/scripts/config-lint/install-linters.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+warn() {
+	echo "[config-lint install] $*" >&2
+}
+
+if command -v python >/dev/null 2>&1; then
+	python -m pip install --upgrade pip
+	python -m pip install yamllint
+elif command -v python3 >/dev/null 2>&1; then
+	python3 -m pip install --upgrade pip
+	python3 -m pip install yamllint
+else
+	warn "python/python3 is not available; skipping pip/yamllint install."
+fi
+
+if command -v npm >/dev/null 2>&1; then
+	npm install -g markdownlint-cli --no-fund --no-audit
+else
+	warn "npm is not available; skipping markdownlint-cli install."
+fi
+
+if command -v gem >/dev/null 2>&1; then
+	gem install asciidoctor
+else
+	warn "gem is not available; skipping asciidoctor install."
+fi
+
+if ! command -v shellcheck >/dev/null 2>&1; then
+	if command -v apt-get >/dev/null 2>&1; then
+		if command -v sudo >/dev/null 2>&1 && sudo -n true >/dev/null 2>&1; then
+			sudo DEBIAN_FRONTEND=noninteractive apt-get update -y
+			sudo DEBIAN_FRONTEND=noninteractive apt-get install -y shellcheck
+		else
+			warn "shellcheck is missing and apt-get requires interactive sudo; skipping apt install to avoid hangs."
+		fi
+	else
+		warn "shellcheck is missing and apt-get is unavailable; skipping shellcheck install."
+	fi
+fi
diff --git a/.github/workflows/scripts/config-lint/lint-asciidoc.sh b/.github/workflows/scripts/config-lint/lint-asciidoc.sh
new file mode 100644
index 0000000..7621dcd
--- /dev/null
+++ b/.github/workflows/scripts/config-lint/lint-asciidoc.sh
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+repo_root="$(pwd)"
+reports_dir="${REPORTS_DIR:-.temp/Reports}"
+
+mkdir -p "$reports_dir"
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --repo-root "${repo_root}" --include '*.adoc' --include '*.asciidoc')
+if [ -n "${files}" ]; then
+  # asciidoctor validates document structure/parsing
+  set +e
+  echo "$files" | xargs -I{} asciidoctor -o /dev/null "{}" 2>&1 | tee "$reports_dir/asciidoctor-parse.txt"
+  parse_rc=${PIPESTATUS[1]}
+  if [ "$parse_rc" -ne 0 ]; then
+    echo "::error::asciidoctor parse validation failed (rc=$parse_rc). See $reports_dir/asciidoctor-parse.txt."
+    exit "$parse_rc"
+  fi
+  cp "$reports_dir/asciidoctor-parse.txt" "$reports_dir/asciidoctor-lint.txt"
+else
+  echo "No AsciiDoc files found." > "$reports_dir/asciidoctor-lint.txt"
+fi
diff --git a/.github/workflows/scripts/config-lint/lint-markdown.sh b/.github/workflows/scripts/config-lint/lint-markdown.sh
new file mode 100644
index 0000000..54da4d7
--- /dev/null
+++ b/.github/workflows/scripts/config-lint/lint-markdown.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+repo_root="$(pwd)"
+reports_dir="${REPORTS_DIR:-.temp/Reports}"
+
+mkdir -p "$reports_dir"
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --repo-root "${repo_root}" --include '*.md')
+if [ -n "${files}" ]; then
+  set +e
+  echo "$files" | xargs -I{} markdownlint "{}" --config .markdownlint.json 2>&1 | tee "$reports_dir/markdownlint.txt"
+  rc=${PIPESTATUS[1]}
+  if [ "$rc" -ne 0 ]; then
+    echo "::error::markdownlint failed (rc=$rc). See $reports_dir/markdownlint.txt."
+    exit "$rc"
+  fi
+else
+  echo "No Markdown files found." > "$reports_dir/markdownlint.txt"
+fi
diff --git a/.github/workflows/scripts/config-lint/lint-shell.sh b/.github/workflows/scripts/config-lint/lint-shell.sh
new file mode 100644
index 0000000..51111b0
--- /dev/null
+++ b/.github/workflows/scripts/config-lint/lint-shell.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+repo_root="$(pwd)"
+reports_dir="${REPORTS_DIR:-.temp/Reports}"
+
+mkdir -p "$reports_dir"
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --repo-root "${repo_root}" --include '*.sh')
+if [ -n "${files}" ]; then
+  set +e
+  echo "$files" | xargs -I{} shellcheck "{}" 2>&1 | tee "$reports_dir/shellcheck.txt"
+  rc=${PIPESTATUS[1]}
+  if [ "$rc" -ne 0 ]; then
+    echo "::error::shellcheck failed (rc=$rc). See $reports_dir/shellcheck.txt."
+    exit "$rc"
+  fi
+else
+  echo "No shell scripts found." > "$reports_dir/shellcheck.txt"
+fi
diff --git a/.github/workflows/scripts/config-lint/lint-yaml.sh b/.github/workflows/scripts/config-lint/lint-yaml.sh
new file mode 100644
index 0000000..edba199
--- /dev/null
+++ b/.github/workflows/scripts/config-lint/lint-yaml.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+repo_root="$(pwd)"
+reports_dir="${REPORTS_DIR:-.temp/Reports}"
+
+mkdir -p "$reports_dir"
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --repo-root "${repo_root}" --include '*.yml' --include '*.yaml')
+if [ -n "${files}" ]; then
+  set +e
+  echo "$files" | xargs -I{} yamllint -s "{}" 2>&1 | tee "$reports_dir/yamllint.txt"
+  rc=${PIPESTATUS[1]}
+  if [ "$rc" -ne 0 ]; then
+    echo "::error::yamllint failed (rc=$rc). See $reports_dir/yamllint.txt."
+    exit "$rc"
+  fi
+else
+  echo "No YAML files found." > "$reports_dir/yamllint.txt"
+fi
diff --git a/.github/workflows/scripts/config-lint/validate-js-syntax.sh b/.github/workflows/scripts/config-lint/validate-js-syntax.sh
new file mode 100644
index 0000000..9fce71c
--- /dev/null
+++ b/.github/workflows/scripts/config-lint/validate-js-syntax.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+repo_root="$(pwd)"
+reports_dir="${REPORTS_DIR:-.temp/Reports}"
+
+mkdir -p "$reports_dir"
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --repo-root "${repo_root}" --include '*.js')
+if [ -n "${files}" ]; then
+  set +e
+  echo "$files" | xargs -I{} node --check "{}" 2>&1 | tee "$reports_dir/js-syntax.txt"
+  rc=${PIPESTATUS[1]}
+  if [ "$rc" -ne 0 ]; then
+    echo "::error::JavaScript syntax validation failed (rc=$rc). See $reports_dir/js-syntax.txt."
+    exit "$rc"
+  fi
+else
+  echo "No JavaScript files found." > "$reports_dir/js-syntax.txt"
+fi
diff --git a/.github/workflows/scripts/config-lint/validate-json.sh b/.github/workflows/scripts/config-lint/validate-json.sh
new file mode 100644
index 0000000..710b0de
--- /dev/null
+++ b/.github/workflows/scripts/config-lint/validate-json.sh
@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+repo_root="$(pwd)"
+reports_dir="${REPORTS_DIR:-.temp/Reports}"
+
+if command -v python >/dev/null 2>&1; then
+  python_cmd="python"
+elif command -v python3 >/dev/null 2>&1; then
+  python_cmd="python3"
+else
+  echo "::error::python/python3 is required for JSON validation."
+  exit 127
+fi
+
+mkdir -p "$reports_dir"
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --repo-root "${repo_root}" --include '*.json')
+if [ -n "${files}" ]; then
+  set +e
+  echo "$files" | xargs -I{} "$python_cmd" -m json.tool "{}" > /dev/null
+  rc=${PIPESTATUS[1]}
+  if [ "$rc" -ne 0 ]; then
+    echo "::error::JSON syntax validation failed (rc=$rc)."
+    exit "$rc"
+  fi
+  printf "Validated %s JSON files.\n" "$(echo "$files" | wc -l | tr -d ' ')" > "$reports_dir/jsonlint.txt"
+else
+  echo "No JSON files found." > "$reports_dir/jsonlint.txt"
+fi
diff --git a/.github/workflows/scripts/config-lint/write-summary.sh b/.github/workflows/scripts/config-lint/write-summary.sh
new file mode 100644
index 0000000..b3eaa18
--- /dev/null
+++ b/.github/workflows/scripts/config-lint/write-summary.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+
+set +e
+if {
+  echo "## config-lint summary"
+  echo "- YAML: see reports/yamllint.txt"
+  echo "- JSON: see reports/jsonlint.txt"
+  echo "- Markdown: see reports/markdownlint.txt"
+  echo "- AsciiDoc: see reports/asciidoctor-lint.txt"
+  echo "- Shell: see reports/shellcheck.txt"
+  echo "- JavaScript syntax: see reports/js-syntax.txt"
+} >> "$GITHUB_STEP_SUMMARY"; then
+  :
+else
+  echo "::error::Failed to write config-lint job summary."
+  exit 1
+fi
diff --git a/.github/workflows/scripts/dependabot-auto-merge/enable-auto-merge.sh b/.github/workflows/scripts/dependabot-auto-merge/enable-auto-merge.sh
new file mode 100644
index 0000000..23c04c0
--- /dev/null
+++ b/.github/workflows/scripts/dependabot-auto-merge/enable-auto-merge.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+gh pr merge "$PR_URL" --auto --squash
diff --git a/.github/workflows/scripts/execute-all-workflow-scripts.ps1 b/.github/workflows/scripts/execute-all-workflow-scripts.ps1
new file mode 100644
index 0000000..e73513c
--- /dev/null
+++ b/.github/workflows/scripts/execute-all-workflow-scripts.ps1
@@ -0,0 +1,67 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "ci") "WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "execute-all-workflow-scripts"
+
+$reportDir = Join-Path $RepoRoot ".temp/Reports"
+New-Item -ItemType Directory -Path $reportDir -Force | Out-Null
+$env:REPORTS_DIR = $reportDir
+
+$workflowScripts = @(
+  "policy-check/execute-workflow-policy-check.ps1",
+  "python-quality/execute-workflow-python-quality.ps1",
+  "python-tests/execute-workflow-python-tests.ps1",
+  "powershell-quality/execute-workflow-powershell-quality.ps1",
+  "powershell-tests/execute-workflow-powershell-tests.ps1",
+  "powershell-runtime-compat/execute-workflow-powershell-runtime-compat.ps1",
+  "shell-quality/execute-workflow-shell-quality.ps1",
+  "shell-tests/execute-workflow-shell-tests.ps1",
+  "config-lint/execute-workflow-config-lint.ps1"
+)
+
+foreach ($scriptName in $workflowScripts) {
+  $scriptPath = Join-Path $PSScriptRoot $scriptName
+  if (-not (Test-Path -LiteralPath $scriptPath -PathType Leaf)) {
+    Add-WorkflowFailure -Message ("Missing workflow execution script: {0}" -f $scriptPath)
+    Write-WorkflowLine ("[LOCAL FAILURE] Missing workflow execution script: {0}" -f $scriptPath)
+    continue
+  }
+
+  Write-WorkflowLine ''
+  Invoke-WorkflowStep -Name "Run $scriptName" -Action {
+    if ($FullScan) {
+      & pwsh $scriptPath -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -FullScan
+    }
+    else {
+      & pwsh $scriptPath -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head
+    }
+    if ($LASTEXITCODE -ne 0) {
+      throw "$scriptName failed."
+    }
+  }
+}
+
+Write-WorkflowLine ''
+$summary = @(Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "execute-all-workflow-scripts") | Select-Object -Last 1
+if ($summary.HasFailures) {
+  Write-WorkflowLine "Local workflow script runners completed with reported issues."
+}
+else {
+  Write-WorkflowLine "All local workflow script runners completed successfully."
+}
diff --git a/.github/workflows/scripts/policy-check/enforce-repo-guardrails.sh b/.github/workflows/scripts/policy-check/enforce-repo-guardrails.sh
new file mode 100644
index 0000000..00aad8a
--- /dev/null
+++ b/.github/workflows/scripts/policy-check/enforce-repo-guardrails.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+set +e
+mkdir -p reports
+
+# 1) Block obvious hardcoded secrets in tracked repo files.
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*')
+list_rc=$?
+if [ "$list_rc" -ne 0 ]; then
+  echo "::error::Failed to list tracked files for guardrails (rc=$list_rc)."
+  exit "$list_rc"
+fi
+if [ -n "${files}" ]; then
+  secret_matches=$(echo "${files}" | xargs -d '\n' grep -IInE "(api[_-]?key|secret|token|password)\s*[:=]\s*['\"][^'\"]+['\"]" || true)
+  if [ -n "${secret_matches}" ]; then
+    echo "${secret_matches}"
+    echo "Potential hardcoded secret detected."
+    exit 1
+  fi
+fi
+
+# 2) Ensure PowerShell scripts use strict mode, excluding scratch artifacts.
+ps_files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.ps1' --include '*.psm1')
+ps_list_rc=$?
+if [ "$ps_list_rc" -ne 0 ]; then
+  echo "::error::Failed to enumerate PowerShell files for guardrails (rc=$ps_list_rc)."
+  exit "$ps_list_rc"
+fi
+if [ -n "${ps_files}" ]; then
+  missing=$(echo "${ps_files}" | xargs -I{} sh -c "grep -q 'Set-StrictMode' '{}' || echo '{}'")
+  if [ -n "${missing}" ]; then
+    echo "Missing Set-StrictMode in:"
+    echo "${missing}"
+    exit 1
+  fi
+fi
+
+echo "Policy checks passed." > reports/policy-check.txt
diff --git a/.github/workflows/scripts/policy-check/execute-workflow-policy-check.ps1 b/.github/workflows/scripts/policy-check/execute-workflow-policy-check.ps1
new file mode 100644
index 0000000..10a46f5
--- /dev/null
+++ b/.github/workflows/scripts/policy-check/execute-workflow-policy-check.ps1
@@ -0,0 +1,62 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "..") "ci/WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "policy-check"
+
+Invoke-WorkflowStep -Name "policy-check: prerequisites" -Action {
+  Assert-WorkflowCommandAvailable -Name "python" -InstallHint "Install Python 3.11+ and ensure it is on PATH."
+  Assert-WorkflowCommandAvailable -Name "pwsh" -InstallHint "Install PowerShell 7 and ensure it is on PATH."
+}
+
+Push-Location $RepoRoot
+try {
+  Invoke-WorkflowStep -Name "policy-check: enforce repo guardrails" -Action {
+    $files = Get-WorkflowFiles -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -Include @("*") -FullScan:$FullScan
+    foreach ($file in $files) {
+      if (-not (Test-Path -LiteralPath $file -PathType Leaf)) { continue }
+      $text = Get-Content -LiteralPath $file -Raw -ErrorAction SilentlyContinue
+      if ($null -eq $text) { continue }
+      if ($text -match '(?im)(api[_-]?key|secret|token|password)\s*[:=]\s*["''][^"'']+["'']') {
+        throw "Potential hardcoded secret detected in $file."
+      }
+    }
+
+    $psFiles = Get-WorkflowFiles -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -Include @("*.ps1", "*.psm1") -FullScan:$FullScan
+    foreach ($file in $psFiles) {
+      if (-not (Test-Path -LiteralPath $file -PathType Leaf)) { continue }
+      $head = Get-Content -LiteralPath $file -TotalCount 80
+      if (-not ($head -match 'Set-StrictMode')) {
+        throw "Missing Set-StrictMode in $file."
+      }
+    }
+  }
+
+  Invoke-WorkflowStep -Name "policy-check: validate coding policies" -Action {
+    & python ".github/workflows/scripts/validate-coding-policies.py"
+    if ($LASTEXITCODE -ne 0) { throw "validate-coding-policies.py failed." }
+
+    & python ".github/workflows/scripts/validate-powershell-runtime.py"
+    if ($LASTEXITCODE -ne 0) { throw "validate-powershell-runtime.py failed." }
+  }
+}
+finally {
+  Pop-Location
+}
+
+$null = Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "policy-check"
diff --git a/.github/workflows/scripts/policy-check/validate-coding-policies.sh b/.github/workflows/scripts/policy-check/validate-coding-policies.sh
new file mode 100644
index 0000000..2a617c9
--- /dev/null
+++ b/.github/workflows/scripts/policy-check/validate-coding-policies.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+set +e
+python -m pip install --upgrade pip
+pip_up_rc=$?
+if [ "$pip_up_rc" -ne 0 ]; then
+  echo "::error::pip upgrade failed (rc=$pip_up_rc)."
+  exit "$pip_up_rc"
+fi
+pip install pyyaml
+pyyaml_rc=$?
+if [ "$pyyaml_rc" -ne 0 ]; then
+  echo "::error::pyyaml installation failed (rc=$pyyaml_rc)."
+  exit "$pyyaml_rc"
+fi
+python .github/workflows/scripts/validate-coding-policies.py
+policy_rc=$?
+if [ "$policy_rc" -ne 0 ]; then
+  echo "::error::coding policy validation failed (rc=$policy_rc)."
+  exit "$policy_rc"
+fi
+
+python .github/workflows/scripts/validate-powershell-runtime.py
+ps_runtime_rc=$?
+if [ "$ps_runtime_rc" -ne 0 ]; then
+  echo "::error::PowerShell runtime policy validation failed (rc=$ps_runtime_rc)."
+  exit "$ps_runtime_rc"
+fi
diff --git a/.github/workflows/scripts/policy-check/write-summary.sh b/.github/workflows/scripts/policy-check/write-summary.sh
new file mode 100644
index 0000000..55f5d9b
--- /dev/null
+++ b/.github/workflows/scripts/policy-check/write-summary.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+set +e
+if {
+  echo "## policy-check summary"
+  echo "- Guardrail log: reports/policy-check.txt"
+  echo "- Coding policy log: reports/coding-policy-check.txt"
+  echo "- PowerShell runtime log: reports/powershell-runtime-check.txt"
+} >> "$GITHUB_STEP_SUMMARY"; then
+  :
+else
+  echo "::error::Failed to write policy-check job summary."
+  exit 1
+fi
diff --git a/.github/workflows/scripts/powershell-quality/execute-workflow-powershell-quality.ps1 b/.github/workflows/scripts/powershell-quality/execute-workflow-powershell-quality.ps1
new file mode 100644
index 0000000..04c4f7c
--- /dev/null
+++ b/.github/workflows/scripts/powershell-quality/execute-workflow-powershell-quality.ps1
@@ -0,0 +1,86 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "..") "ci/WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "powershell-quality"
+
+Push-Location $RepoRoot
+try {
+  $reportDir = Get-WorkflowReportDirectory -RepoRoot $RepoRoot
+  New-Item -ItemType Directory -Path $reportDir -Force | Out-Null
+  $scriptAnalyzerReport = Join-Path $reportDir "psscriptanalyzer-local.txt"
+  $syntaxReport = Join-Path $reportDir "powershell-syntax-local.txt"
+
+  if (@(Get-WorkflowFailures).Count -gt 0) {
+    Write-Output "Skipping powershell-quality checks due to prerequisite failures."
+  }
+  else {
+    $files = Get-WorkflowFiles -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -Include @("*.ps1", "*.psm1", "*.psd1") -FullScan:$FullScan
+    if (@($files).Count -eq 0) {
+      Write-Output "== powershell-quality ==`nNo PowerShell files found."
+    }
+    else {
+      Invoke-WorkflowStep -Name "powershell-quality: script analyzer" -Action {
+        if (-not (Get-Module -ListAvailable -Name PSScriptAnalyzer)) {
+          throw "PSScriptAnalyzer is not installed. Run simulate-workflows with -InstallTools first."
+        }
+        Import-Module PSScriptAnalyzer -ErrorAction Stop
+        $results = foreach ($file in $files) {
+          Invoke-ScriptAnalyzer -Path $file -Severity Warning, Error -ExcludeRule PSUseSingularNouns, PSAvoidUsingWriteHost, PSUseBOMForUnicodeEncodedFile
+        }
+        if ($results) {
+          $results | Format-Table Path, Line, RuleName, Severity, Message -AutoSize | Out-String | Set-Content -Path $scriptAnalyzerReport -Encoding utf8
+          Write-Output ("PSScriptAnalyzer found {0} issue(s). Report: {1}" -f @($results).Count, $scriptAnalyzerReport)
+          Get-Content -Path $scriptAnalyzerReport | Write-Output
+          throw "PSScriptAnalyzer found issues."
+        }
+
+        "No PSScriptAnalyzer issues found." | Set-Content -Path $scriptAnalyzerReport -Encoding utf8
+        Write-Output ("No PSScriptAnalyzer issues found. Report: {0}" -f $scriptAnalyzerReport)
+      }
+
+      Invoke-WorkflowStep -Name "powershell-quality: pwsh syntax parse" -Action {
+        $errors = [System.Collections.Generic.List[string]]::new()
+        foreach ($file in $files) {
+          $tokens = $null
+          $parseErrors = $null
+          [System.Management.Automation.Language.Parser]::ParseFile($file, [ref]$tokens, [ref]$parseErrors) | Out-Null
+          if ($parseErrors) {
+            foreach ($err in $parseErrors) {
+              $errors.Add(("{0}:{1}:{2}: {3}" -f $file, $err.Extent.StartLineNumber, $err.Extent.StartColumnNumber, $err.Message))
+            }
+          }
+        }
+        if ($errors.Count -gt 0) {
+          $errors | Set-Content -Path $syntaxReport -Encoding utf8
+          Write-Output ("PowerShell syntax validation found {0} issue(s). Report: {1}" -f $errors.Count, $syntaxReport)
+          Get-Content -Path $syntaxReport | Write-Output
+          throw "PowerShell syntax validation failed."
+        }
+
+        "No PowerShell syntax issues found." | Set-Content -Path $syntaxReport -Encoding utf8
+        Write-Output ("No PowerShell syntax issues found. Report: {0}" -f $syntaxReport)
+      }
+    }
+  }
+}
+finally {
+  Pop-Location
+}
+
+$null = Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "powershell-quality"
diff --git a/.github/workflows/scripts/powershell-quality/find-powershell-files.sh b/.github/workflows/scripts/powershell-quality/find-powershell-files.sh
new file mode 100644
index 0000000..88f77a2
--- /dev/null
+++ b/.github/workflows/scripts/powershell-quality/find-powershell-files.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+count=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.ps1' --include '*.psm1' --include '*.psd1' --output-count)
+echo "count=${count}" >> "$GITHUB_OUTPUT"
diff --git a/.github/workflows/scripts/powershell-quality/run-psscriptanalyzer.sh b/.github/workflows/scripts/powershell-quality/run-psscriptanalyzer.sh
new file mode 100644
index 0000000..3d064dc
--- /dev/null
+++ b/.github/workflows/scripts/powershell-quality/run-psscriptanalyzer.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+mkdir -p reports
+count=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.ps1' --include '*.psm1' --include '*.psd1' --output-count)
+
+if [[ "${count}" == "0" ]]; then
+  echo "No PowerShell files changed." > reports/psscriptanalyzer.txt
+  exit 0
+fi
+
+cat > reports/psscriptanalyzer.txt <<'EOF'
+PSScriptAnalyzer execution was skipped.
+Reason: workflows are configured for bash-only execution with no PowerShell runtime involvement.
+EOF
+
+echo "::warning::Skipped PSScriptAnalyzer because PowerShell execution is disabled for workflow scripts."
diff --git a/.github/workflows/scripts/powershell-quality/validate-powershell-syntax.sh b/.github/workflows/scripts/powershell-quality/validate-powershell-syntax.sh
new file mode 100644
index 0000000..d48755c
--- /dev/null
+++ b/.github/workflows/scripts/powershell-quality/validate-powershell-syntax.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+mkdir -p reports
+count=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.ps1' --include '*.psm1' --include '*.psd1' --output-count)
+
+if [[ "${count}" == "0" ]]; then
+  echo "No PowerShell files changed." > reports/powershell-syntax.txt
+  exit 0
+fi
+
+cat > reports/powershell-syntax.txt <<'EOF'
+PowerShell syntax validation was skipped.
+Reason: workflows are configured for bash-only execution with no PowerShell runtime involvement.
+EOF
+
+echo "::warning::Skipped PowerShell syntax validation because PowerShell execution is disabled for workflow scripts."
diff --git a/.github/workflows/scripts/powershell-quality/write-summary.sh b/.github/workflows/scripts/powershell-quality/write-summary.sh
new file mode 100644
index 0000000..3245c9b
--- /dev/null
+++ b/.github/workflows/scripts/powershell-quality/write-summary.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+set +e
+if {
+  echo "## powershell-quality summary"
+  echo "- PowerShell files found: $1"
+  echo "- Analyzer report: reports/psscriptanalyzer.txt"
+  echo "- Syntax report: reports/powershell-syntax.txt"
+} >> "$GITHUB_STEP_SUMMARY"; then
+  :
+else
+  echo "::error::Failed to write powershell-quality job summary."
+  exit 1
+fi
diff --git a/.github/workflows/scripts/powershell-runtime-compat/execute-workflow-powershell-runtime-compat.ps1 b/.github/workflows/scripts/powershell-runtime-compat/execute-workflow-powershell-runtime-compat.ps1
new file mode 100644
index 0000000..dc962e3
--- /dev/null
+++ b/.github/workflows/scripts/powershell-runtime-compat/execute-workflow-powershell-runtime-compat.ps1
@@ -0,0 +1,90 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "..") "ci/WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "powershell-runtime-compat"
+
+Push-Location $RepoRoot
+try {
+  $files = Get-WorkflowFiles -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -Include @("*.ps1") -FullScan:$FullScan
+
+  Invoke-WorkflowStep -Name "powershell-runtime-compat: pwsh syntax (core-first + dual-runtime)" -Action {
+    $targets = foreach ($file in $files) {
+      if (-not (Test-Path -LiteralPath $file -PathType Leaf)) { continue }
+      $lines = Get-Content -LiteralPath $file -TotalCount 40
+      $policyLine = $lines | Where-Object { $_ -match '^\s*#\s*RuntimePolicy:\s*' } | Select-Object -First 1
+      if (-not $policyLine) { continue }
+      $policy = ($policyLine -replace '^\s*#\s*RuntimePolicy:\s*', '').Trim().ToLowerInvariant()
+      if ($policy -in @('core-first', 'dual-runtime')) { $file }
+    }
+
+    if (-not $targets) {
+      Write-Output "No pwsh-target files found."
+      return
+    }
+
+    $errors = [System.Collections.Generic.List[string]]::new()
+    foreach ($file in $targets) {
+      $tokens = $null
+      $parseErrors = $null
+      [System.Management.Automation.Language.Parser]::ParseFile($file, [ref]$tokens, [ref]$parseErrors) | Out-Null
+      if ($parseErrors) {
+        foreach ($err in $parseErrors) {
+          $errors.Add(("{0}:{1}:{2}: {3}" -f $file, $err.Extent.StartLineNumber, $err.Extent.StartColumnNumber, $err.Message))
+        }
+      }
+    }
+
+    if ($errors.Count -gt 0) {
+      $errors | Write-Output
+      throw "pwsh syntax validation failed."
+    }
+  }
+
+  Invoke-WorkflowStep -Name "powershell-runtime-compat: windows powershell syntax (dual-runtime + desktop-only)" -Action {
+    $winPs = Get-Command powershell -ErrorAction SilentlyContinue
+    if (-not $winPs) {
+      Write-Output "Windows PowerShell executable not found; skipping desktop runtime parse step."
+      return
+    }
+
+    $targets = foreach ($file in $files) {
+      if (-not (Test-Path -LiteralPath $file -PathType Leaf)) { continue }
+      $lines = Get-Content -LiteralPath $file -TotalCount 40
+      $policyLine = $lines | Where-Object { $_ -match '^\s*#\s*RuntimePolicy:\s*' } | Select-Object -First 1
+      if (-not $policyLine) { continue }
+      $policy = ($policyLine -replace '^\s*#\s*RuntimePolicy:\s*', '').Trim().ToLowerInvariant()
+      if ($policy -in @('dual-runtime', 'desktop-only')) { $file }
+    }
+
+    if (-not $targets) {
+      Write-Output "No Windows PowerShell target files found."
+      return
+    }
+
+    foreach ($file in $targets) {
+      & powershell -NoProfile -Command "`$tokens = `$null; `$errors = `$null; [System.Management.Automation.Language.Parser]::ParseFile('$file', [ref]`$tokens, [ref]`$errors) | Out-Null; if (`$errors.Count -gt 0) { `$errors | ForEach-Object { throw (`$_.Extent.File + ':' + `$_.Extent.StartLineNumber + ':' + `$_.Extent.StartColumnNumber + ': ' + `$_.Message) } }"
+      if ($LASTEXITCODE -ne 0) { throw "Windows PowerShell syntax validation failed for $file." }
+    }
+  }
+}
+finally {
+  Pop-Location
+}
+
+$null = Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "powershell-runtime-compat"
diff --git a/.github/workflows/scripts/powershell-runtime-compat/validate-pwsh-syntax.sh b/.github/workflows/scripts/powershell-runtime-compat/validate-pwsh-syntax.sh
new file mode 100644
index 0000000..6ffed89
--- /dev/null
+++ b/.github/workflows/scripts/powershell-runtime-compat/validate-pwsh-syntax.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+mkdir -p reports
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.ps1')
+
+targets=""
+while IFS= read -r file; do
+  [[ -z "${file}" ]] && continue
+  policy=$(awk 'NR<=40 && $0 ~ /^#[[:space:]]*RuntimePolicy:[[:space:]]*/ {sub(/^#[[:space:]]*RuntimePolicy:[[:space:]]*/, ""); gsub(/[[:space:]]+$/, ""); print tolower($0); exit}' "${file}")
+  if [[ "${policy}" == "core-first" || "${policy}" == "dual-runtime" ]]; then
+    targets+="${file}"$'\n'
+  fi
+done <<< "${files}"
+
+if [[ -z "${targets}" ]]; then
+  echo "No pwsh-target files found." > reports/pwsh-syntax.txt
+  exit 0
+fi
+
+cat > reports/pwsh-syntax.txt <<'EOF'
+pwsh syntax parser check was skipped.
+Reason: workflows are configured for bash-only execution with no PowerShell runtime involvement.
+EOF
+
+echo "::warning::Skipped pwsh syntax parser check because PowerShell execution is disabled for workflow scripts."
diff --git a/.github/workflows/scripts/powershell-runtime-compat/validate-windowsps-syntax.sh b/.github/workflows/scripts/powershell-runtime-compat/validate-windowsps-syntax.sh
new file mode 100644
index 0000000..db476ad
--- /dev/null
+++ b/.github/workflows/scripts/powershell-runtime-compat/validate-windowsps-syntax.sh
@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+mkdir -p reports
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.ps1')
+
+targets=""
+while IFS= read -r file; do
+  [[ -z "${file}" ]] && continue
+  policy=$(awk 'NR<=40 && $0 ~ /^#[[:space:]]*RuntimePolicy:[[:space:]]*/ {sub(/^#[[:space:]]*RuntimePolicy:[[:space:]]*/, ""); gsub(/[[:space:]]+$/, ""); print tolower($0); exit}' "${file}")
+  if [[ "${policy}" == "dual-runtime" || "${policy}" == "desktop-only" ]]; then
+    targets+="${file}"$'\n'
+  fi
+done <<< "${files}"
+
+if [[ -z "${targets}" ]]; then
+  echo "No Windows PowerShell target files found." > reports/windowsps-syntax.txt
+  exit 0
+fi
+
+cat > reports/windowsps-syntax.txt <<'EOF'
+Windows PowerShell syntax parser check was skipped.
+Reason: workflows are configured for bash-only execution with no PowerShell runtime involvement.
+EOF
+
+echo "::warning::Skipped Windows PowerShell syntax parser check because PowerShell execution is disabled for workflow scripts."
diff --git a/.github/workflows/scripts/powershell-runtime-compat/write-summary.sh b/.github/workflows/scripts/powershell-runtime-compat/write-summary.sh
new file mode 100644
index 0000000..94c108a
--- /dev/null
+++ b/.github/workflows/scripts/powershell-runtime-compat/write-summary.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+cat <<'EOF' >> "$GITHUB_STEP_SUMMARY"
+## powershell-runtime-compat summary
+- pwsh syntax report: reports/pwsh-syntax.txt
+- Windows PowerShell syntax report: reports/windowsps-syntax.txt
+EOF
diff --git a/.github/workflows/scripts/powershell-tests/discover-test-files.sh b/.github/workflows/scripts/powershell-tests/discover-test-files.sh
new file mode 100644
index 0000000..1e310e7
--- /dev/null
+++ b/.github/workflows/scripts/powershell-tests/discover-test-files.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.Tests.ps1' | awk 'NF')
+count=$(printf "%s\n" "${files}" | sed '/^$/d' | wc -l | tr -d ' ')
+joined=$(printf "%s\n" "${files}" | paste -sd, -)
+{
+  echo "count=${count}"
+  echo "files=${joined}"
+} >> "$GITHUB_OUTPUT"
diff --git a/.github/workflows/scripts/powershell-tests/execute-workflow-powershell-tests.ps1 b/.github/workflows/scripts/powershell-tests/execute-workflow-powershell-tests.ps1
new file mode 100644
index 0000000..83ccead
--- /dev/null
+++ b/.github/workflows/scripts/powershell-tests/execute-workflow-powershell-tests.ps1
@@ -0,0 +1,48 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "..") "ci/WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "powershell-tests"
+
+Push-Location $RepoRoot
+try {
+  if (@(Get-WorkflowFailures).Count -gt 0) {
+    Write-Output "Skipping powershell-tests checks due to prerequisite failures."
+  }
+  else {
+  $files = Get-WorkflowFiles -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -Include @("*.Tests.ps1") -FullScan:$FullScan
+  if (@($files).Count -eq 0) {
+    Write-Output "== powershell-tests ==`nNo Pester tests found; skipping."
+  }
+  else {
+    Invoke-WorkflowStep -Name "powershell-tests: pester" -Action {
+      if (-not (Get-Module -ListAvailable -Name Pester)) {
+        throw "Pester is not installed. Run simulate-workflows with -InstallTools first."
+      }
+      Import-Module Pester -ErrorAction Stop
+      Invoke-Pester -Path $files -CI
+      if ($LASTEXITCODE -ne 0) { throw "Pester tests failed." }
+    }
+  }
+  }
+}
+finally {
+  Pop-Location
+}
+
+$null = Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "powershell-tests"
diff --git a/.github/workflows/scripts/powershell-tests/install-pester.sh b/.github/workflows/scripts/powershell-tests/install-pester.sh
new file mode 100644
index 0000000..60965a3
--- /dev/null
+++ b/.github/workflows/scripts/powershell-tests/install-pester.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+echo "Skipping Pester installation: workflow scripts run in bash-only mode."
diff --git a/.github/workflows/scripts/powershell-tests/no-tests-found.sh b/.github/workflows/scripts/powershell-tests/no-tests-found.sh
new file mode 100644
index 0000000..54f8f1d
--- /dev/null
+++ b/.github/workflows/scripts/powershell-tests/no-tests-found.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+echo "No Pester tests found; skipping."
diff --git a/.github/workflows/scripts/powershell-tests/run-pester.sh b/.github/workflows/scripts/powershell-tests/run-pester.sh
new file mode 100644
index 0000000..e50e000
--- /dev/null
+++ b/.github/workflows/scripts/powershell-tests/run-pester.sh
@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+joined_paths="$1"
+
+echo "Skipping Pester execution for: ${joined_paths}"
+echo "Reason: workflow scripts run in bash-only mode."
diff --git a/.github/workflows/scripts/python-quality/execute-workflow-python-quality.ps1 b/.github/workflows/scripts/python-quality/execute-workflow-python-quality.ps1
new file mode 100644
index 0000000..a06f683
--- /dev/null
+++ b/.github/workflows/scripts/python-quality/execute-workflow-python-quality.ps1
@@ -0,0 +1,53 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "..") "ci/WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "python-quality"
+
+Invoke-WorkflowStep -Name "python-quality: prerequisites" -Action {
+  Assert-WorkflowCommandAvailable -Name "python" -InstallHint "Install Python 3.11+ and ensure it is on PATH."
+}
+
+Push-Location $RepoRoot
+try {
+  if (@(Get-WorkflowFailures).Count -gt 0) {
+    Write-Output "Skipping python-quality checks due to prerequisite failures."
+  }
+  else {
+    $files = Get-WorkflowFiles -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -Include @("*.py") -FullScan:$FullScan
+    if (@($files).Count -eq 0) {
+      Write-Output "== python-quality ==`nNo Python files found."
+    }
+    else {
+      Invoke-WorkflowStep -Name "python-quality: ruff check" -Action {
+        & python -m ruff check @files
+        if ($LASTEXITCODE -ne 0) { throw "ruff check failed." }
+      }
+
+      Invoke-WorkflowStep -Name "python-quality: ruff format check" -Action {
+        & python -m ruff format --check @files
+        if ($LASTEXITCODE -ne 0) { throw "ruff format --check failed." }
+      }
+    }
+  }
+}
+finally {
+  Pop-Location
+}
+
+$null = Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "python-quality"
diff --git a/.github/workflows/scripts/python-quality/find-python-files.sh b/.github/workflows/scripts/python-quality/find-python-files.sh
new file mode 100644
index 0000000..4e42953
--- /dev/null
+++ b/.github/workflows/scripts/python-quality/find-python-files.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+count=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.py' --output-count)
+echo "count=${count}" >> "$GITHUB_OUTPUT"
diff --git a/.github/workflows/scripts/python-quality/install-tools.sh b/.github/workflows/scripts/python-quality/install-tools.sh
new file mode 100644
index 0000000..8b2e1f1
--- /dev/null
+++ b/.github/workflows/scripts/python-quality/install-tools.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+
+python -m pip install --upgrade pip
+pip install ruff
diff --git a/.github/workflows/scripts/python-quality/ruff-check.sh b/.github/workflows/scripts/python-quality/ruff-check.sh
new file mode 100644
index 0000000..b391a55
--- /dev/null
+++ b/.github/workflows/scripts/python-quality/ruff-check.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+mkdir -p reports
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.py')
+set +e
+echo "$files" | xargs -I{} ruff check "{}" 2>&1 | tee reports/ruff-check.txt
+rc=${PIPESTATUS[1]}
+if [ "$rc" -ne 0 ]; then
+  echo "::error::ruff check failed (rc=$rc). See reports/ruff-check.txt."
+  exit "$rc"
+fi
diff --git a/.github/workflows/scripts/python-quality/ruff-format-check.sh b/.github/workflows/scripts/python-quality/ruff-format-check.sh
new file mode 100644
index 0000000..1e29597
--- /dev/null
+++ b/.github/workflows/scripts/python-quality/ruff-format-check.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+mkdir -p reports
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.py')
+set +e
+echo "$files" | xargs -I{} ruff format --check "{}" 2>&1 | tee reports/ruff-format-check.txt
+rc=${PIPESTATUS[1]}
+if [ "$rc" -ne 0 ]; then
+  echo "::error::ruff format check failed (rc=$rc). See reports/ruff-format-check.txt."
+  exit "$rc"
+fi
diff --git a/.github/workflows/scripts/python-quality/write-summary.sh b/.github/workflows/scripts/python-quality/write-summary.sh
new file mode 100644
index 0000000..3180286
--- /dev/null
+++ b/.github/workflows/scripts/python-quality/write-summary.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+set +e
+if {
+  echo "## python-quality summary"
+  echo "- Python files found: $1"
+  echo "- Ruff check report: reports/ruff-check.txt"
+  echo "- Ruff format report: reports/ruff-format-check.txt"
+} >> "$GITHUB_STEP_SUMMARY"; then
+  :
+else
+  echo "::error::Failed to write python-quality job summary."
+  exit 1
+fi
diff --git a/.github/workflows/scripts/python-tests/discover-test-files.sh b/.github/workflows/scripts/python-tests/discover-test-files.sh
new file mode 100644
index 0000000..92dd862
--- /dev/null
+++ b/.github/workflows/scripts/python-tests/discover-test-files.sh
@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include 'ai-artifacts/**/tests/test_*.py')
+{
+  echo "files<<EOF"
+  echo "$files"
+  echo "EOF"
+  echo "count=$(printf "%s\n" "$files" | sed '/^$/d' | wc -l | tr -d ' ')"
+} >> "$GITHUB_OUTPUT"
diff --git a/.github/workflows/scripts/python-tests/execute-workflow-python-tests.ps1 b/.github/workflows/scripts/python-tests/execute-workflow-python-tests.ps1
new file mode 100644
index 0000000..ccc27bb
--- /dev/null
+++ b/.github/workflows/scripts/python-tests/execute-workflow-python-tests.ps1
@@ -0,0 +1,48 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "..") "ci/WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "python-tests"
+
+Invoke-WorkflowStep -Name "python-tests: prerequisites" -Action {
+  Assert-WorkflowCommandAvailable -Name "python" -InstallHint "Install Python 3.11+ and ensure it is on PATH."
+}
+
+Push-Location $RepoRoot
+try {
+  if (@(Get-WorkflowFailures).Count -gt 0) {
+    Write-Output "Skipping python-tests checks due to prerequisite failures."
+  }
+  else {
+  $files = Get-WorkflowFiles -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -Include @("ai-artifacts/**/tests/test_*.py") -FullScan:$FullScan
+  if (@($files).Count -eq 0) {
+    Write-Output "== python-tests ==`nNo Python tests found; skipping."
+  }
+  else {
+    Invoke-WorkflowStep -Name "python-tests: pytest" -Action {
+      & python -m pytest @files -q
+      if ($LASTEXITCODE -ne 0) { throw "pytest failed." }
+    }
+  }
+  }
+}
+finally {
+  Pop-Location
+}
+
+$null = Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "python-tests"
diff --git a/.github/workflows/scripts/python-tests/install-test-dependencies.sh b/.github/workflows/scripts/python-tests/install-test-dependencies.sh
new file mode 100644
index 0000000..a2b99b8
--- /dev/null
+++ b/.github/workflows/scripts/python-tests/install-test-dependencies.sh
@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+
+python -m pip install --upgrade pip
+pip install pytest
diff --git a/.github/workflows/scripts/python-tests/no-tests-found.sh b/.github/workflows/scripts/python-tests/no-tests-found.sh
new file mode 100644
index 0000000..7076378
--- /dev/null
+++ b/.github/workflows/scripts/python-tests/no-tests-found.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+echo "No Python tests found; skipping."
diff --git a/.github/workflows/scripts/python-tests/run-pytest.sh b/.github/workflows/scripts/python-tests/run-pytest.sh
new file mode 100644
index 0000000..8e31637
--- /dev/null
+++ b/.github/workflows/scripts/python-tests/run-pytest.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+
+files="$1"
+
+echo "${files}" | xargs -I{} python -m pytest "{}" -q
diff --git a/.github/workflows/scripts/shell-quality/execute-workflow-shell-quality.ps1 b/.github/workflows/scripts/shell-quality/execute-workflow-shell-quality.ps1
new file mode 100644
index 0000000..9c20249
--- /dev/null
+++ b/.github/workflows/scripts/shell-quality/execute-workflow-shell-quality.ps1
@@ -0,0 +1,49 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "..") "ci/WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "shell-quality"
+
+$shellcheckAvailable = $null -ne (Get-Command shellcheck -ErrorAction SilentlyContinue)
+if (-not $shellcheckAvailable) {
+  Write-WorkflowLine "shellcheck is not available locally; skipping shell-quality checks."
+}
+
+Push-Location $RepoRoot
+try {
+  if (-not $shellcheckAvailable) {
+    Write-Output "Skipping shell-quality checks because shellcheck is unavailable."
+  }
+  else {
+    $files = Get-WorkflowFiles -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -Include @("*.sh") -FullScan:$FullScan
+    if (@($files).Count -eq 0) {
+      Write-Output "== shell-quality ==`nNo shell files found."
+    }
+    else {
+      Invoke-WorkflowStep -Name "shell-quality: shellcheck" -Action {
+        & shellcheck @files
+        if ($LASTEXITCODE -ne 0) { throw "shellcheck failed." }
+      }
+    }
+  }
+}
+finally {
+  Pop-Location
+}
+
+$null = Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "shell-quality"
diff --git a/.github/workflows/scripts/shell-quality/find-shell-files.sh b/.github/workflows/scripts/shell-quality/find-shell-files.sh
new file mode 100644
index 0000000..d3f46e8
--- /dev/null
+++ b/.github/workflows/scripts/shell-quality/find-shell-files.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+count=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.sh' --output-count)
+echo "count=${count}" >> "$GITHUB_OUTPUT"
diff --git a/.github/workflows/scripts/shell-quality/install-shellcheck.sh b/.github/workflows/scripts/shell-quality/install-shellcheck.sh
new file mode 100644
index 0000000..980b8a7
--- /dev/null
+++ b/.github/workflows/scripts/shell-quality/install-shellcheck.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+set +e
+sudo apt-get update
+apt_update_rc=$?
+if [ "$apt_update_rc" -ne 0 ]; then
+  echo "::error::apt-get update failed (rc=$apt_update_rc)."
+  exit "$apt_update_rc"
+fi
+sudo apt-get install -y shellcheck
+install_rc=$?
+if [ "$install_rc" -ne 0 ]; then
+  echo "::error::shellcheck installation failed (rc=$install_rc)."
+  exit "$install_rc"
+fi
diff --git a/.github/workflows/scripts/shell-quality/run-shellcheck.sh b/.github/workflows/scripts/shell-quality/run-shellcheck.sh
new file mode 100644
index 0000000..beb5113
--- /dev/null
+++ b/.github/workflows/scripts/shell-quality/run-shellcheck.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+mkdir -p reports
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.sh')
+set +e
+echo "$files" | xargs -I{} shellcheck "{}" 2>&1 | tee reports/shellcheck.txt
+rc=${PIPESTATUS[1]}
+if [ "$rc" -ne 0 ]; then
+  echo "::error::shellcheck failed (rc=$rc). See reports/shellcheck.txt."
+  exit "$rc"
+fi
diff --git a/.github/workflows/scripts/shell-quality/write-summary.sh b/.github/workflows/scripts/shell-quality/write-summary.sh
new file mode 100644
index 0000000..648ab88
--- /dev/null
+++ b/.github/workflows/scripts/shell-quality/write-summary.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+set +e
+if {
+  echo "## shell-quality summary"
+  echo "- Shell files found: $1"
+  echo "- ShellCheck report: reports/shellcheck.txt"
+} >> "$GITHUB_STEP_SUMMARY"; then
+  :
+else
+  echo "::error::Failed to write shell-quality job summary."
+  exit 1
+fi
diff --git a/.github/workflows/scripts/shell-tests/execute-workflow-shell-tests.ps1 b/.github/workflows/scripts/shell-tests/execute-workflow-shell-tests.ps1
new file mode 100644
index 0000000..b8dc862
--- /dev/null
+++ b/.github/workflows/scripts/shell-tests/execute-workflow-shell-tests.ps1
@@ -0,0 +1,55 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [string]$Base = "",
+  [string]$Head = "",
+  [switch]$FullScan
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+. (Join-Path (Join-Path $PSScriptRoot "..") "ci/WorkflowScript.Common.ps1")
+
+$RepoRoot = Resolve-WorkflowRepoRoot -RepoRoot $RepoRoot -CallerRoot $PSScriptRoot
+$range = Resolve-WorkflowDiffRange -RepoRoot $RepoRoot -Base $Base -Head $Head
+Reset-WorkflowFailures -WorkflowName "shell-tests"
+
+$batsAvailable = $null -ne (Get-Command bats -ErrorAction SilentlyContinue)
+$bashAvailable = $null -ne (Get-Command bash -ErrorAction SilentlyContinue)
+if (-not $batsAvailable) {
+  Write-WorkflowLine "bats is not available locally; skipping shell-tests checks."
+}
+if (-not $bashAvailable) {
+  Write-WorkflowLine "bash is not available locally; skipping shell-tests checks."
+}
+
+Push-Location $RepoRoot
+try {
+  if (-not ($batsAvailable -and $bashAvailable)) {
+    Write-Output "Skipping shell-tests checks because bats or bash is unavailable."
+  }
+  else {
+  $files = Get-WorkflowFiles -RepoRoot $RepoRoot -Base $range.Base -Head $range.Head -Include @("*.bats") -FullScan:$FullScan
+  if (@($files).Count -eq 0) {
+    Write-Output "== shell-tests ==`nNo bats tests found; skipping."
+  }
+  else {
+    Invoke-WorkflowStep -Name "shell-tests: bats" -Action {
+      $joined = $files -join [Environment]::NewLine
+      $env:BATS_FILES = $joined
+      & bash ".github/workflows/scripts/shell/run-shell-tests.sh"
+      if ($LASTEXITCODE -ne 0) { throw "bats tests failed." }
+    }
+  }
+  }
+}
+finally {
+  Pop-Location
+}
+
+$null = Write-WorkflowStatusSummary -RepoRoot $RepoRoot -WorkflowName "shell-tests"
diff --git a/.github/workflows/scripts/shell-tests/find-bats-files.sh b/.github/workflows/scripts/shell-tests/find-bats-files.sh
new file mode 100644
index 0000000..2c4fd8b
--- /dev/null
+++ b/.github/workflows/scripts/shell-tests/find-bats-files.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+count=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.bats' --output-count)
+echo "count=${count}" >> "$GITHUB_OUTPUT"
diff --git a/.github/workflows/scripts/shell-tests/install-bats.sh b/.github/workflows/scripts/shell-tests/install-bats.sh
new file mode 100644
index 0000000..262268a
--- /dev/null
+++ b/.github/workflows/scripts/shell-tests/install-bats.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+
+set +e
+sudo apt-get update
+apt_update_rc=$?
+if [ "$apt_update_rc" -ne 0 ]; then
+  echo "::error::apt-get update failed (rc=$apt_update_rc)."
+  exit "$apt_update_rc"
+fi
+sudo apt-get install -y bats
+install_rc=$?
+if [ "$install_rc" -ne 0 ]; then
+  echo "::error::bats installation failed (rc=$install_rc)."
+  exit "$install_rc"
+fi
diff --git a/.github/workflows/scripts/shell-tests/no-tests-found.sh b/.github/workflows/scripts/shell-tests/no-tests-found.sh
new file mode 100644
index 0000000..48bbdf3
--- /dev/null
+++ b/.github/workflows/scripts/shell-tests/no-tests-found.sh
@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+
+echo "No bats tests found; skipping."
diff --git a/.github/workflows/scripts/shell-tests/run-bats.sh b/.github/workflows/scripts/shell-tests/run-bats.sh
new file mode 100644
index 0000000..d9d8209
--- /dev/null
+++ b/.github/workflows/scripts/shell-tests/run-bats.sh
@@ -0,0 +1,7 @@
+#!/usr/bin/env bash
+
+base="$1"
+head="$2"
+
+files=$(bash .github/workflows/scripts/ci/get-changed-files.sh --base "${base}" --head "${head}" --include '*.bats')
+BATS_FILES="$files" bash .github/workflows/scripts/shell/run-shell-tests.sh
diff --git a/.github/workflows/scripts/shell-tests/write-summary.sh b/.github/workflows/scripts/shell-tests/write-summary.sh
new file mode 100644
index 0000000..20aaa05
--- /dev/null
+++ b/.github/workflows/scripts/shell-tests/write-summary.sh
@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+
+set +e
+if {
+  echo "## shell-tests summary"
+  echo "- Shell test files found: $1"
+  echo "- bats report: reports/bats.txt"
+} >> "$GITHUB_STEP_SUMMARY"; then
+  :
+else
+  echo "::error::Failed to write shell-tests job summary."
+  exit 1
+fi
diff --git a/.github/workflows/scripts/shell/run-shell-tests.sh b/.github/workflows/scripts/shell/run-shell-tests.sh
new file mode 100644
index 0000000..698b721
--- /dev/null
+++ b/.github/workflows/scripts/shell/run-shell-tests.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+
+reports_dir="${REPORTS_DIR:-.temp/Reports}"
+mkdir -p "$reports_dir"
+
+if [ -z "${BATS_FILES:-}" ]; then
+  echo "No bats files found."
+  echo "No bats files found." > "$reports_dir/bats.txt"
+  exit 0
+fi
+
+set +e
+echo "$BATS_FILES" | sed '/^$/d' | xargs -I{} bats "{}" 2>&1 | tee "$reports_dir/bats.txt"
+rc=${PIPESTATUS[1]}
+if [ "$rc" -ne 0 ]; then
+  echo "::error::bats failed (rc=$rc). See $reports_dir/bats.txt."
+  exit "$rc"
+fi
+
+exit 0
diff --git a/scripts/validate-coding-policies.py b/.github/workflows/scripts/validate-coding-policies.py
similarity index 94%
rename from scripts/validate-coding-policies.py
rename to .github/workflows/scripts/validate-coding-policies.py
index 2900435..f456772 100644
--- a/scripts/validate-coding-policies.py
+++ b/.github/workflows/scripts/validate-coding-policies.py
@@ -3,15 +3,17 @@
 import re
 import subprocess
 import sys
+import os
 from pathlib import Path
 from typing import Iterable
 
 import yaml
 
-
-REPO_ROOT = Path(__file__).resolve().parent.parent
+REPO_ROOT = Path(__file__).resolve().parents[3]
 POLICY_ROOT = REPO_ROOT / "coding-policies"
-REPORTS_DIR = REPO_ROOT / "reports"
+REPORTS_DIR = Path(
+    os.environ.get("REPORTS_DIR", str(REPO_ROOT / ".temp/Reports"))
+).expanduser()
 
 
 def load_yaml(path: Path) -> dict:
@@ -70,6 +72,9 @@ def iter_shell_files() -> Iterable[Path]:
 
 def validate_bash_policy(errors: list[str]) -> None:
     for path in iter_shell_files():
+        if not path.exists():
+            # Local simulation can run in a dirty tree where tracked files were deleted.
+            continue
         lines = path.read_text(encoding="utf-8").splitlines()
         for idx, line in enumerate(lines, start=1):
             stripped = line.strip()
@@ -99,6 +104,8 @@ def validate_bash_policy(errors: list[str]) -> None:
 def validate_workflow_bash_policy(errors: list[str]) -> None:
     for rel in git_ls_files(".github/workflows/*.yml", ".github/workflows/*.yaml"):
         path = REPO_ROOT / rel
+        if not path.exists():
+            continue
         lines = path.read_text(encoding="utf-8").splitlines()
         for idx, line in enumerate(lines, start=1):
             if re.search(r"^\s*set\s+-[^\n]*[eu]", line):
diff --git a/.github/workflows/scripts/validate-powershell-runtime.py b/.github/workflows/scripts/validate-powershell-runtime.py
new file mode 100644
index 0000000..5c1a97a
--- /dev/null
+++ b/.github/workflows/scripts/validate-powershell-runtime.py
@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+import os
+from pathlib import Path
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+REPORTS_DIR = Path(
+    os.environ.get("REPORTS_DIR", str(REPO_ROOT / ".temp/Reports"))
+).expanduser()
+WINDOWS_PS_SUFFIX = "-windowsps.ps1"
+RUNTIME_POLICY_RE = re.compile(
+    r"^\s*#\s*RuntimePolicy:\s*([A-Za-z0-9_-]+)", re.IGNORECASE
+)
+RUNTIME_JUSTIFICATION_RE = re.compile(
+    r"^\s*#\s*RuntimeJustification:\s*(.+)$", re.IGNORECASE
+)
+REQUIRES_VERSION_RE = re.compile(
+    r"^\s*#requires\s+-version\s+([0-9]+(?:\.[0-9]+)?)", re.IGNORECASE
+)
+REQUIRES_EDITION_RE = re.compile(r"^\s*#requires\s+-psedition\s+(\w+)", re.IGNORECASE)
+
+
+def git_ls_files(*patterns: str) -> list[str]:
+    result = subprocess.run(
+        ["git", "ls-files", *patterns],
+        cwd=REPO_ROOT,
+        text=True,
+        capture_output=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "git ls-files failed")
+    return [line for line in result.stdout.splitlines() if line.strip()]
+
+
+def parse_headers(path: Path) -> tuple[str | None, str | None, str | None, str | None]:
+    policy = None
+    justification = None
+    version = None
+    edition = None
+    with path.open("r", encoding="utf-8") as handle:
+        for _ in range(40):
+            line = handle.readline()
+            if not line:
+                break
+            policy_match = RUNTIME_POLICY_RE.match(line)
+            if policy_match:
+                policy = policy_match.group(1).strip().lower()
+            justification_match = RUNTIME_JUSTIFICATION_RE.match(line)
+            if justification_match:
+                justification = justification_match.group(1).strip()
+            version_match = REQUIRES_VERSION_RE.match(line)
+            if version_match:
+                version = version_match.group(1)
+            edition_match = REQUIRES_EDITION_RE.match(line)
+            if edition_match:
+                edition = edition_match.group(1)
+    return policy, justification, version, edition
+
+
+def version_major(version_text: str) -> int:
+    try:
+        return int(version_text.split(".")[0])
+    except (ValueError, IndexError) as exc:
+        raise ValueError(f"invalid version '{version_text}'") from exc
+
+
+def validate_ps_files(errors: list[str]) -> None:
+    files = git_ls_files(
+        "*.ps1",
+        ":(exclude).scratch/*/artefacts/**",
+        ":(exclude).scratch/*/artifacts/**",
+    )
+    for rel in files:
+        path = REPO_ROOT / rel
+        if not path.exists():
+            continue
+        policy, justification, version, edition = parse_headers(path)
+        rel_posix = path.relative_to(REPO_ROOT).as_posix()
+        is_windows_ps = path.name.lower().endswith(WINDOWS_PS_SUFFIX)
+
+        if policy is None:
+            errors.append(
+                f"{rel_posix}: missing '# RuntimePolicy: core-first|dual-runtime|desktop-only'"
+            )
+            continue
+
+        if policy not in {"core-first", "dual-runtime", "desktop-only"}:
+            errors.append(
+                f"{rel_posix}: invalid RuntimePolicy '{policy}' "
+                "(allowed: core-first, dual-runtime, desktop-only)"
+            )
+            continue
+
+        if policy == "core-first":
+            if version is None:
+                errors.append(
+                    f"{rel_posix}: core-first scripts must declare '#Requires -Version 7.0' or higher"
+                )
+                continue
+            if edition is None:
+                errors.append(
+                    f"{rel_posix}: core-first scripts must declare '#Requires -PSEdition Core'"
+                )
+                continue
+            major = version_major(version)
+            edition_norm = edition.lower()
+            if major < 7:
+                errors.append(
+                    f"{rel_posix}: core-first requires PowerShell {version}; expected 7+"
+                )
+            if edition_norm != "core":
+                errors.append(
+                    f"{rel_posix}: core-first scripts must use '#Requires -PSEdition Core'"
+                )
+            if is_windows_ps:
+                errors.append(
+                    f"{rel_posix}: core-first scripts must not use the '{WINDOWS_PS_SUFFIX}' override suffix"
+                )
+            continue
+
+        if policy == "dual-runtime":
+            if edition is not None:
+                errors.append(
+                    f"{rel_posix}: dual-runtime scripts must not set '#Requires -PSEdition ...'"
+                )
+            if version is not None:
+                major = version_major(version)
+                if major > 5:
+                    errors.append(
+                        f"{rel_posix}: dual-runtime '#Requires -Version {version}' blocks Windows PowerShell 5.1"
+                    )
+            if is_windows_ps:
+                errors.append(
+                    f"{rel_posix}: dual-runtime scripts must not use the '{WINDOWS_PS_SUFFIX}' suffix"
+                )
+            continue
+
+        if policy == "desktop-only":
+            if not is_windows_ps:
+                errors.append(
+                    f"{rel_posix}: desktop-only scripts must be named '*{WINDOWS_PS_SUFFIX}'"
+                )
+            if not justification:
+                errors.append(
+                    f"{rel_posix}: desktop-only scripts must include '# RuntimeJustification: ...'"
+                )
+            if version is None:
+                errors.append(
+                    f"{rel_posix}: desktop-only scripts must declare '#Requires -Version 5.1'"
+                )
+                continue
+            if edition is None:
+                errors.append(
+                    f"{rel_posix}: desktop-only scripts must declare '#Requires -PSEdition Desktop'"
+                )
+                continue
+            if version != "5.1":
+                errors.append(
+                    f"{rel_posix}: desktop-only scripts must use '#Requires -Version 5.1'"
+                )
+            if edition.lower() != "desktop":
+                errors.append(
+                    f"{rel_posix}: desktop-only scripts must use '#Requires -PSEdition Desktop'"
+                )
+
+
+def write_report(errors: list[str]) -> None:
+    REPORTS_DIR.mkdir(exist_ok=True)
+    report = REPORTS_DIR / "powershell-runtime-check.txt"
+    lines = ["powershell runtime check"]
+    if errors:
+        lines.append("status: failed")
+        lines.extend(errors)
+    else:
+        lines.append("status: passed")
+        lines.append("all PowerShell scripts declare a valid runtime policy")
+    report.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def main() -> int:
+    errors: list[str] = []
+    try:
+        validate_ps_files(errors)
+    except Exception as exc:
+        errors.append(str(exc))
+
+    write_report(errors)
+    if errors:
+        for err in errors:
+            print(err)
+        return 1
+    print("PowerShell runtime checks passed")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/.github/workflows/shell-quality.yml b/.github/workflows/shell-quality.yml
index 5d71417..0dc4799 100644
--- a/.github/workflows/shell-quality.yml
+++ b/.github/workflows/shell-quality.yml
@@ -4,18 +4,18 @@ on:
   pull_request:
     paths:
       - "**/*.sh"
-      - "coding-policies/polyglot-policy.yaml"
-      - "coding-policies/languages/bash-policy.yaml"
       - ".github/workflows/shell-quality.yml"
+      - "coding-policies/languages/bash-policy.yaml"
+      - "coding-policies/polyglot-policy.yaml"
       - "!.scratch/*/artefacts/**"
       - "!.scratch/*/artifacts/**"
   push:
     branches: [main]
     paths:
       - "**/*.sh"
-      - "coding-policies/polyglot-policy.yaml"
-      - "coding-policies/languages/bash-policy.yaml"
       - ".github/workflows/shell-quality.yml"
+      - "coding-policies/languages/bash-policy.yaml"
+      - "coding-policies/polyglot-policy.yaml"
       - "!.scratch/*/artefacts/**"
       - "!.scratch/*/artifacts/**"
   workflow_dispatch:
@@ -40,64 +40,25 @@ jobs:
         id: diff
         shell: bash
         run: |
-          base="${{ github.event.pull_request.base.sha }}"
-          head="${{ github.event.pull_request.head.sha }}"
-          if [ -z "${base}" ]; then
-            base="${{ github.event.before }}"
-          fi
-          if [ -z "${head}" ]; then
-            head="${{ github.sha }}"
-          fi
-          if [ -z "${base}" ] || [ "${base}" = "0000000000000000000000000000000000000000" ]; then
-            base=$(git rev-list --max-parents=0 "${head}" | tail -n 1)
-          fi
-          echo "base=${base}" >> "$GITHUB_OUTPUT"
-          echo "head=${head}" >> "$GITHUB_OUTPUT"
+          bash .github/workflows/scripts/ci/determin-diff-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" "${{ github.event.before }}" "${{ github.sha }}"
 
       - name: Find shell files
         id: shfiles
         shell: bash
         run: |
-          set +e
-          count=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.sh' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**' | wc -l | tr -d ' ')
-          rc=${PIPESTATUS[0]}
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::Failed to enumerate shell files (rc=$rc)."
-            exit "$rc"
-          fi
-          echo "count=$count" >> "$GITHUB_OUTPUT"
+          bash .github/workflows/scripts/shell-quality/find-shell-files.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Install ShellCheck
         if: steps.shfiles.outputs.count != '0'
         shell: bash
         run: |
-          set +e
-          sudo apt-get update
-          apt_update_rc=$?
-          if [ "$apt_update_rc" -ne 0 ]; then
-            echo "::error::apt-get update failed (rc=$apt_update_rc)."
-            exit "$apt_update_rc"
-          fi
-          sudo apt-get install -y shellcheck
-          install_rc=$?
-          if [ "$install_rc" -ne 0 ]; then
-            echo "::error::shellcheck installation failed (rc=$install_rc)."
-            exit "$install_rc"
-          fi
+          bash .github/workflows/scripts/shell-quality/install-shellcheck.sh
 
       - name: Run ShellCheck
         if: steps.shfiles.outputs.count != '0'
         shell: bash
         run: |
-          mkdir -p reports
-          files=$(git diff --name-only --diff-filter=ACMRTUXB "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}" -- '*.sh' ':(exclude).scratch/*/artefacts/**' ':(exclude).scratch/*/artifacts/**')
-          set +e
-          echo "$files" | xargs -I{} shellcheck "{}" 2>&1 | tee reports/shellcheck.txt
-          rc=${PIPESTATUS[1]}
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::shellcheck failed (rc=$rc). See reports/shellcheck.txt."
-            exit "$rc"
-          fi
+          bash .github/workflows/scripts/shell-quality/run-shellcheck.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
 
       - name: Upload shell reports
         if: always() && steps.shfiles.outputs.count != '0'
@@ -110,14 +71,4 @@ jobs:
         if: always()
         shell: bash
         run: |
-          set +e
-          {
-            echo "## shell-quality summary"
-            echo "- Shell files found: ${{ steps.shfiles.outputs.count }}"
-            echo "- ShellCheck report: reports/shellcheck.txt"
-          } >> "$GITHUB_STEP_SUMMARY"
-          rc=$?
-          if [ "$rc" -ne 0 ]; then
-            echo "::error::Failed to write shell-quality job summary (rc=$rc)."
-            exit "$rc"
-          fi
+          bash .github/workflows/scripts/shell-quality/write-summary.sh "${{ steps.shfiles.outputs.count }}"
diff --git a/.github/workflows/shell-tests.yml b/.github/workflows/shell-tests.yml
new file mode 100644
index 0000000..c9e8b52
--- /dev/null
+++ b/.github/workflows/shell-tests.yml
@@ -0,0 +1,82 @@
+name: shell-tests
+
+on:
+  pull_request:
+    paths:
+      - "**/*.bats"
+      - ".github/workflows/scripts/**"
+      - ".github/workflows/shell-tests.yml"
+      - "coding-policies/languages/bash-policy.yaml"
+      - "coding-policies/polyglot-policy.yaml"
+      - "!.scratch/*/artefacts/**"
+      - "!.scratch/*/artifacts/**"
+  push:
+    branches: [main]
+    paths:
+      - "**/*.bats"
+      - ".github/workflows/scripts/**"
+      - ".github/workflows/shell-tests.yml"
+      - "coding-policies/languages/bash-policy.yaml"
+      - "coding-policies/polyglot-policy.yaml"
+      - "!.scratch/*/artefacts/**"
+      - "!.scratch/*/artifacts/**"
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  shell-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+
+      - name: Determine diff range
+        id: diff
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/ci/determin-diff-range.sh "${{ github.event.pull_request.base.sha }}" "${{ github.event.pull_request.head.sha }}" "${{ github.event.before }}" "${{ github.sha }}"
+
+      - name: Find bats files
+        id: batsfiles
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/shell-tests/find-bats-files.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
+
+      - name: Install bats-core
+        if: steps.batsfiles.outputs.count != '0'
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/shell-tests/install-bats.sh
+
+      - name: Run bats
+        if: steps.batsfiles.outputs.count != '0'
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/shell-tests/run-bats.sh "${{ steps.diff.outputs.base }}" "${{ steps.diff.outputs.head }}"
+
+      - name: No tests found
+        if: steps.batsfiles.outputs.count == '0'
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/shell-tests/no-tests-found.sh
+
+      - name: Upload shell test reports
+        if: always() && steps.batsfiles.outputs.count != '0'
+        uses: actions/upload-artifact@v7
+        with:
+          name: shell-test-reports
+          path: reports
+
+      - name: Add job summary
+        if: always()
+        shell: bash
+        run: |
+          bash .github/workflows/scripts/shell-tests/write-summary.sh "${{ steps.batsfiles.outputs.count }}"
diff --git a/.gitignore b/.gitignore
index d07bc4f..c2e63f7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,20 @@
+# OS-generated files
+.DS_Store
+.DS_Store?
+Thumbs.db
+Desktop.ini
+$RECYCLE.BIN/
+.Spotlight-V100/
+.Trashes/
+._*
+
+# Editor / IDE metadata
+/.idea/
+*.iml
+*.swp
+*.swo
+*~
+
 # VS Code Local History extension
 /.history/
 
@@ -9,13 +26,23 @@
 /.temp/*
 !/.temp/.gitkeep
 
-# Generated Claude Code skill mirror. Source of truth is shared/skills/.
-# Rebuild after clone or after editing a skill:  pwsh scripts/sync-skills.ps1
-/.claude/commands/*
-
-# Generated Codex skill mirror. Source of truth is shared/skills/.
-# Rebuild after clone or after editing a skill:  pwsh scripts/sync-skills.ps1
-/.agents/skills/*
+# Generated agent skill mirrors (Claude Code, Codex, Copilot). Source of truth is ai-artifacts/skills/shared/.
+# Rebuild after clone or after editing a skill:  pwsh scripts/setup-repo.ps1 -SkipHooks
+# One-step clone bootstrap: pwsh scripts/setup-repo.ps1
+# Claude Code skill mirrors
+/.claude/commands/**
+!/.claude/commands/setup/
+!/.claude/commands/setup/setup-repo/
+!/.claude/commands/setup/setup-repo/**
+!/.claude/commands/setup/setup-repo.md
+# Codex skill mirrors
+/.agents/skills/**
+!/.agents/skills/setup_setup-repo/
+!/.agents/skills/setup_setup-repo/**
+# Copilot skill mirrors
+/.github/skills/**
+!/.github/skills/setup_setup-repo/
+!/.github/skills/setup_setup-repo/**
 
 # Python bytecode caches (e.g. from running the mail-to-doc tool's test suite)
 __pycache__/
diff --git a/.markdownlint.json b/.markdownlint.json
index ac56578..4e75e47 100644
--- a/.markdownlint.json
+++ b/.markdownlint.json
@@ -5,7 +5,11 @@
   "MD033": false,
   "MD041": false,
 
+  "MD003": { "style": "atx" },
+  "MD004": { "style": "dash" },
+  "MD025": { "front_matter_title": "" },
+  "MD029": { "style": "ordered" },
   "MD049": { "style": "asterisk" },
   "MD050": { "style": "asterisk" },
   "MD060": { "style": "aligned" }
-}
\ No newline at end of file
+}
diff --git a/.scratch/AGENTS.md b/.scratch/AGENTS.md
index 8633784..bc3ad08 100644
--- a/.scratch/AGENTS.md
+++ b/.scratch/AGENTS.md
@@ -10,8 +10,8 @@ A **vehicle for capturing and tracking ideas** — one folder per feature
 `BACKLOG.md`. Capture with `/planning:scratch`; rank with `/planning:scratch-plan`.
 
 - Structural layout + file templates → the `scratch` skill's
-  [LAYOUT.md](../shared/skills/planning/scratch/LAYOUT.md)
-- Ranking formula → [RANKING.md](../shared/skills/planning/scratch/RANKING.md)
+  [LAYOUT.md](../ai-artifacts/skills/shared/planning/scratch/LAYOUT.md)
+- Ranking formula → [RANKING.md](../ai-artifacts/skills/shared/planning/scratch/RANKING.md)
 
 ## Working rules
 
@@ -24,18 +24,18 @@ produces — a skill or script, a report, a durable finding, any shippable outpu
 and belongs in its proper repo home, with the PRD linking to it. `artifacts/` holds only *supporting
 inputs* (upstream snapshots, prior drafts, sample inputs) — **never the deliverable**.
 
-| Deliverable | Home (not the scratch) |
-| --- | --- |
-| Skill / tool | `shared/skills/<group>/<name>/` (or a `<vendor>/<harness>/` skills dir) |
-| Report / durable finding / review | `docs/` — `docs/findings/`, `docs/reviews/`, … |
-| Instructions / settings / hooks | their harness-scoped home (`<vendor>/<harness>/…`) |
+Deliverable homes:
+
+- Skill / tool: `ai-artifacts/skills/shared/<group>/<name>/` (or `ai-artifacts/skills/<vendor>/<harness>/…`)
+- Report / durable finding / review: `docs/` — `docs/findings/`, `docs/reviews/`, …
+- Instructions / hooks: their artifact-type home (`ai-artifacts/instructions/<vendor>/<harness>/…`, `ai-artifacts/hooks/<vendor>/<harness>/…`, `ai-artifacts/mcp-config/<vendor>/<harness>/…`, `ai-artifacts/output-styles/<vendor>/<harness>/…`, `ai-artifacts/agents/<vendor>/<harness>/…`, `ai-artifacts/prompts/<vendor>/<harness>/…`, or `ai-artifacts/plugins/<vendor>/<harness>/…`)
 
 **Don't hand-maintain rankings.** `BACKLOG.md` order and scores are produced by
 `/planning:scratch-plan`; flipping a single status cell is fine, re-ranking is the skill's job.
 
 ---
 
-_This is the first per-folder `AGENTS.md` in the repo. Whether to add folder guides across other
+*This is the first per-folder `AGENTS.md` in the repo. Whether to add folder guides across other
 significant subtrees is gated on the hypothesis test in
 [`agents-md-folder-guides`](agents-md-folder-guides/PRD.md) — this file is a deliberate single
-instance (it houses a decided convention), not a rollout._
+instance (it houses a decided convention), not a rollout.*
diff --git a/.scratch/add-watch-skill/artifacts/watch/CHANGELOG.md b/.scratch/add-watch-skill/artifacts/watch/CHANGELOG.md
index 6ad03c4..7ae0020 100644
--- a/.scratch/add-watch-skill/artifacts/watch/CHANGELOG.md
+++ b/.scratch/add-watch-skill/artifacts/watch/CHANGELOG.md
@@ -24,7 +24,7 @@ All notable changes to `/watch` are documented here.
 
 ### Fixed
 - Added `commands/watch.md` shim so `/watch` is callable when installed as a Claude Code plugin. Without it, the plugin loaded but the skill wasn't exposed as a slash command.
-- `scripts/build-skill.sh` now strips `commands/` from the claude.ai `.skill` bundle alongside `hooks/` and `.claude-plugin/`.
+- `scripts/build-skill.sh` now strips `commands/` from the claude.ai `.skill` bundle alongside `ai-artifacts/hooks/` and `.claude-plugin/`.
 
 ## [0.1.0] — 2026-04-24
 
diff --git a/.scratch/agents-md-folder-guides/PRD.md b/.scratch/agents-md-folder-guides/PRD.md
index 83e30cf..ec0fcfd 100644
--- a/.scratch/agents-md-folder-guides/PRD.md
+++ b/.scratch/agents-md-folder-guides/PRD.md
@@ -26,7 +26,7 @@ in a future run."** Don't assume it's true — test it.
 
 ## Notes / open questions (for triage, not to action now)
 
-- What counts as "significant"? Threshold by depth, file count, or role (e.g. `skills/`, `shared/`,
+- What counts as "significant"? Threshold by depth, file count, or role (e.g. `ai-artifacts/skills/`, `shared/`,
   `.claude/`, `src/`, `docs/`) — not every leaf folder.
 - `AGENTS.md` as the chosen filename (cross-tool convention) vs. reusing the repo's existing
   README/CLAUDE.md pattern — pick one and be consistent.
@@ -43,4 +43,4 @@ test: does the local guide measurably help an agent working in `.scratch/` vs. r
 `AGENTS.md` + `LAYOUT.md`? Evaluate it here before any broader rollout — the mass-generation decision
 stays gated. (Also settles the filename open-question for this instance: `AGENTS.md`, cross-harness.)
 
-_Solution: Fill in (gated on the hypothesis analysis above)._
+*Solution: Fill in (gated on the hypothesis analysis above).*
diff --git a/.scratch/check-updates-detection-scope/PRD.md b/.scratch/check-updates-detection-scope/PRD.md
index 903f036..cff3326 100644
--- a/.scratch/check-updates-detection-scope/PRD.md
+++ b/.scratch/check-updates-detection-scope/PRD.md
@@ -25,7 +25,7 @@ principle **any** change inside the upstream skill directory — scripts include
   correctly when the dir was renamed/moved (PATH-NOT-FOUND path), and does it false-negative on
   changes to files the skill depends on but doesn't physically contain?
 - Hooks specifically: are hooks ever part of a skill's tracked directory in this repo's model, or do
-  they live under a separate `hooks/`/settings path that detection never looks at?
+  they live under a separate `ai-artifacts/hooks/`/settings path that detection never looks at?
 
 ## Acceptance (what "checked in detail" means)
 
@@ -34,4 +34,4 @@ principle **any** change inside the upstream skill directory — scripts include
 - Explicit call-out of any out-of-directory components that escape detection, and whether that's a
   real risk for current skills.
 
-_Solution: Fill in._
+*Solution: Fill in.*
diff --git a/.scratch/claude-code-skill-adaptation/PRD.md b/.scratch/claude-code-skill-adaptation/PRD.md
index 07f2e1e..5fcb340 100644
--- a/.scratch/claude-code-skill-adaptation/PRD.md
+++ b/.scratch/claude-code-skill-adaptation/PRD.md
@@ -2,7 +2,7 @@
 
 Status: ready-for-human
 
-The skills under `skills/` were imported from their claude.ai (chat) versions, organized by intent,
+The skills under `ai-artifacts/skills/` were imported from their claude.ai (chat) versions, organized by intent,
 and given upstream provenance. They are **invocable** but still **claude.ai-flavored**. This feature
 covers the second pass: making each one behave as a native Claude Code skill.
 
@@ -54,21 +54,21 @@ skill's intent or its local customizations — only its mechanics.
   else → conversational fallback" rather than "if Claude Code do X". Keeps the skills portable to
   Cowork/claude.ai. (Ref: handoff compatibility-matrix design principle.)
 - **Edit the source of truth only.** All edits land in `skills/<group>/<name>/SKILL.md`; re-run
-  `scripts/sync-skills.ps1` to regenerate the `.claude/commands` mirror. Never edit the mirror.
+  `scripts/setup-repo.ps1 -SkipHooks` to regenerate the `.claude/commands` mirror. Never edit the mirror.
 - **Preserve intent and local customizations.** Stack rules, the `grill-me`←`grill-with-docs` merge,
   Windows/pwsh substitutions all stay. This pass changes mechanics, not content decisions.
 - **`check-skill-updates` rework:** extract the inline PowerShell into `scripts/check-skill-updates.ps1`
   (staleness check + three-way-merge helper), and have the SKILL.md drive it. Keep the path-detection
-  already pointed at this repo's `skills/` layout.
+  already pointed at this repo's `ai-artifacts/skills/` layout.
 
 ## Testing Decisions
 
 - Verify each adapted skill loads and triggers: invoke `/group:name` and confirm the body and any
-  `!command` preprocessing resolve, and bundled resources open (after `sync-skills.ps1`).
+  `!command` preprocessing resolve, and bundled resources open (after `setup-repo.ps1 -SkipHooks`).
 - For agentic skills, exercise the tool path on a throwaway target (run a trivial probe / a trivial
   failing test / a one-route prototype) and confirm the conversational fallback still reads sensibly
   when shell is unavailable.
-- Run `scripts/sync-skills.ps1` after each skill edit and confirm the mirror's resource links resolve.
+- Run `scripts/setup-repo.ps1 -SkipHooks` after each skill edit and confirm the mirror's resource links resolve.
 - Structural review of each via `/session:write-a-skill`.
 
 ## Out of Scope
@@ -76,13 +76,13 @@ skill's intent or its local customizations — only its mechanics.
 - The **setup/init skill design** decision (monolithic vs self-configuring vs config-in-AGENTS.md vs
   minimal tracker-only) — handoff decision #5. Resolve with a `grill-me` pass in its own session; it
   shapes any future agentic skills but isn't required to adapt the existing eight.
-- Adopting **new** authors' skills, or new skills not already in `skills/`.
+- Adopting **new** authors' skills, or new skills not already in `ai-artifacts/skills/`.
 - The wider `ai-lab` repo scaffold (AGENTS.md, compatibility matrix, instructions/, mcp/, etc.) —
   tracked by the repo-structure handoff, not this feature.
 
 ## Scope note — which skills this covers
 
-The eight skills imported in pass 1 live under `skills/`. Of these, the **engineering-origin** ones —
+The eight skills imported in pass 1 live under `ai-artifacts/skills/`. Of these, the **engineering-origin** ones —
 `tdd`, `prototype` (mattpocock `engineering/`), and `grill-me` (the `productivity/grill-me` +
 `engineering/grill-with-docs` merge) — are adapted **here** (issues 01, 03, 05). The *additional*
 mattpocock engineering/misc skills not yet imported are a separate feature:
diff --git a/.scratch/claude-code-skill-adaptation/issues/01-audit-and-classify.md b/.scratch/claude-code-skill-adaptation/issues/01-audit-and-classify.md
index 8cd4a5c..021d69b 100644
--- a/.scratch/claude-code-skill-adaptation/issues/01-audit-and-classify.md
+++ b/.scratch/claude-code-skill-adaptation/issues/01-audit-and-classify.md
@@ -11,7 +11,7 @@ from the PRD against the actual bodies.
 
 ## Acceptance criteria
 
-- [ ] Every skill under `skills/` listed with its classification (conversational / agentic)
+- [ ] Every skill under `ai-artifacts/skills/` listed with its classification (conversational / agentic)
 - [ ] Per skill: concrete list of mechanics to change (or "none")
 - [ ] Any additional carried-over content bugs noted (beyond the two already known)
 
diff --git a/.scratch/claude-code-skill-adaptation/issues/02-fix-write-a-skill-resource-link.md b/.scratch/claude-code-skill-adaptation/issues/02-fix-write-a-skill-resource-link.md
index beb7528..846a8c8 100644
--- a/.scratch/claude-code-skill-adaptation/issues/02-fix-write-a-skill-resource-link.md
+++ b/.scratch/claude-code-skill-adaptation/issues/02-fix-write-a-skill-resource-link.md
@@ -13,7 +13,7 @@ somewhere; if orphaned, wire it in or remove it.
 
 - [ ] Every resource link in `write-a-skill/SKILL.md` resolves to a file that exists
 - [ ] No bundled resource is orphaned (unreferenced)
-- [ ] `scripts/sync-skills.ps1` re-run; mirror links resolve
+- [ ] `scripts/setup-repo.ps1 -SkipHooks` re-run; mirror links resolve
 
 ## Blocked by
 
diff --git a/.scratch/claude-code-skill-adaptation/issues/03-conversational-light-pass.md b/.scratch/claude-code-skill-adaptation/issues/03-conversational-light-pass.md
index 9e0e627..43d9d14 100644
--- a/.scratch/claude-code-skill-adaptation/issues/03-conversational-light-pass.md
+++ b/.scratch/claude-code-skill-adaptation/issues/03-conversational-light-pass.md
@@ -14,7 +14,7 @@ chat-only phrasing into procedural steps. Keep intent and local customizations i
 - [ ] Each skill takes `$ARGUMENTS` where it has an input, or is confirmed not to need one
 - [ ] `disable-model-invocation` set where appropriate, with a one-line rationale per decision
 - [ ] No remaining "paste this back into chat"-style phrasing where a tool path exists
-- [ ] Each verified via `/session:write-a-skill`; `sync-skills.ps1` re-run
+- [ ] Each verified via `/session:write-a-skill`; `setup-repo.ps1 -SkipHooks` re-run
 
 ## Blocked by
 
diff --git a/.scratch/claude-code-skill-adaptation/issues/04-adapt-recon-shell-probe.md b/.scratch/claude-code-skill-adaptation/issues/04-adapt-recon-shell-probe.md
index 00e0ffa..3385f85 100644
--- a/.scratch/claude-code-skill-adaptation/issues/04-adapt-recon-shell-probe.md
+++ b/.scratch/claude-code-skill-adaptation/issues/04-adapt-recon-shell-probe.md
@@ -15,7 +15,7 @@ capability contract, not a harness branch.
 - [ ] Agentic path: probe is generated, executed read-only, and its output consumed in-tool
 - [ ] Fallback path preserved for no-shell harnesses
 - [ ] Probe remains strictly read-only (no state changes)
-- [ ] `RECIPES.md` still referenced correctly; `sync-skills.ps1` re-run
+- [ ] `RECIPES.md` still referenced correctly; `setup-repo.ps1 -SkipHooks` re-run
 
 ## Blocked by
 
diff --git a/.scratch/claude-code-skill-adaptation/issues/05-adapt-tdd-prototype-tool-access.md b/.scratch/claude-code-skill-adaptation/issues/05-adapt-tdd-prototype-tool-access.md
index 39f0e7f..e4ffeb4 100644
--- a/.scratch/claude-code-skill-adaptation/issues/05-adapt-tdd-prototype-tool-access.md
+++ b/.scratch/claude-code-skill-adaptation/issues/05-adapt-tdd-prototype-tool-access.md
@@ -17,7 +17,7 @@ Both keep the capability-contract fallback for no-shell harnesses.
 - [ ] `tdd` drives a real failing→passing test cycle via shell on a trivial target
 - [ ] `prototype` builds and runs a minimal prototype end-to-end in-tool
 - [ ] Stack-specific resources still load; conversational fallback preserved
-- [ ] Each verified via `/session:write-a-skill`; `sync-skills.ps1` re-run
+- [ ] Each verified via `/session:write-a-skill`; `setup-repo.ps1 -SkipHooks` re-run
 
 ## Blocked by
 
diff --git a/.scratch/claude-md-planning-defaults/PRD.md b/.scratch/claude-md-planning-defaults/PRD.md
index b0d069f..50a40c2 100644
--- a/.scratch/claude-md-planning-defaults/PRD.md
+++ b/.scratch/claude-md-planning-defaults/PRD.md
@@ -4,7 +4,7 @@ Status: needs-triage
 
 Quick capture — iron out in scratch-planning, don't action yet. These are **general, cross-project**
 rules (not ai-lab specific). Home: the global Claude Code instructions (`~/.claude/CLAUDE.md`; repo
-copy will live at `anthropic/claude-code/instructions/CLAUDE.md` per `incorporate-global-claude-setup`).
+copy will live at `instructions/anthropic/claude-code/CLAUDE.md` per `incorporate-global-claude-setup`).
 
 Rough rules to encode (not final):
 
diff --git a/.scratch/docs-integrity-pass/PRD.md b/.scratch/docs-integrity-pass/PRD.md
index 8af7183..5dd92f2 100644
--- a/.scratch/docs-integrity-pass/PRD.md
+++ b/.scratch/docs-integrity-pass/PRD.md
@@ -8,15 +8,15 @@ Origin: fable (Claude Fable 5 repo review, 2026-07-04)
 Facts are stated in more than one place and have started to drift. Concrete instances found in the
 2026-07-04 review:
 
-1. [shared/skills/README.md](../../shared/skills/README.md) — group table lists only
+1. [ai-artifacts/skills/shared/README.md](../../ai-artifacts/skills/shared/README.md) — group table lists only
    `coding`/`session`/`setup` (missing `planning`), and body text still says `skills/<group>/…`
-   paths (actual: `shared/skills/`).
+   paths (actual: `ai-artifacts/skills/shared/`).
 2. [testing-methodologies-foundation/PRD.md](../testing-methodologies-foundation/PRD.md) — still says
    "**Blocked:** this repo is not yet a git repository"; `git init` was done 2026-06-04 per
    [repo-scaffold](../repo-scaffold/PRD.md). The blocker is stale and the issue it points at is
    unblocked.
 3. "Not the same file (common confusion)" exists near-verbatim in both
-   [instructions/README.md](../../instructions/README.md) and
+   [ai-artifacts/instructions/README.md](../../ai-artifacts/instructions/README.md) and
    [docs/repo-layout.adoc](../../docs/repo-layout.adoc) — two owners for one fact.
 4. [docs/harnesses/claude-code.md](../../docs/harnesses/claude-code.md) lacks the per-section
    confidence table and validation smoke tests that [copilot.md](../../docs/harnesses/copilot.md)
@@ -25,7 +25,7 @@ Facts are stated in more than one place and have started to drift. Concrete inst
 
 ## Solution
 
-_Proposed — refine in triage:_
+*Proposed — refine in triage:*
 
 - Single-owner rule: each fact has one canonical location; other files link instead of restating
   (e.g. repo-layout.adoc owns "Not the same file"; instructions/README links to it).
@@ -38,7 +38,7 @@ _Proposed — refine in triage:_
 
 ## Progress (2026-07-04 — all items closed)
 
-1. ✅ skills README: paths corrected to `shared/skills/…`, `planning` group added to the group
+1. ✅ skills README: paths corrected to `ai-artifacts/skills/shared/…`, `planning` group added to the group
    table, `scratch`/`scratch-plan` added to the origin map as local originals.
 2. ✅ Stale git-init blocker removed from the testing PRD **and** its issue 01 (in-place dated fix —
    consistent with the repo's existing `[RESOLVED …]` house style; the immutability question was
@@ -47,7 +47,7 @@ _Proposed — refine in triage:_
 3. ✅ "Not the same file" now owned solely by repo-layout.adoc; instructions/README links to it.
    The dedupe surfaced and resolved a real contradiction: instructions/README said the future
    CLAUDE.md repo copy goes to `instructions/claude-code/`, canon is
-   `anthropic/claude-code/instructions/` — one more instance of why single-owner matters.
+   `instructions/anthropic/claude-code/` — one more instance of why single-owner matters.
    (Same stale path still appears as a *proposal* inside `incorporate-global-claude-setup`'s
    PRD table — left for that scratch to fix when it builds.)
 4. ✅ claude-code.md gained §11 evidence metadata (per-section confidence, verified 2026-07-04 from
@@ -61,4 +61,4 @@ _Proposed — refine in triage:_
 
 - The duplication cost is exactly what [[backlog-enhancements]] concept 1 (frontmatter → generated
   BACKLOG) eliminates for status fields; this scratch covers the prose-facts side.
-- _Created by Claude Fable 5 via /planning:scratch._
+- *Created by Claude Fable 5 via /planning:scratch.*
diff --git a/.scratch/fetch-latest-claude-skills/PRD.md b/.scratch/fetch-latest-claude-skills/PRD.md
index 1492282..6a56658 100644
--- a/.scratch/fetch-latest-claude-skills/PRD.md
+++ b/.scratch/fetch-latest-claude-skills/PRD.md
@@ -14,12 +14,12 @@ process of staying current with whatever claude.ai publishes.
 
 ## Solution
 
-_Fill in — identify the claude.ai skill source (URL, API, CLI mechanism), define the fetch
-process, determine how to diff against local versions, and decide the integration/review step._
+*Fill in — identify the claude.ai skill source (URL, API, CLI mechanism), define the fetch
+process, determine how to diff against local versions, and decide the integration/review step.*
 
 **Reuse the generic import skill for the integration step.** The "place it in the repo as a
 first-class, grouped, provenance-tracked skill and adapt it" half is already solved by
-[`/setup:import-upstream-skill`](../../shared/skills/setup/import-upstream-skill/SKILL.md) (delivered
+[`/setup:import-upstream-skill`](../../ai-artifacts/skills/shared/setup/import-upstream-skill/SKILL.md) (delivered
 by `import-upstream-skills`). This scratch only needs to solve the **claude.ai-specific source half** —
 how to *discover and fetch* the latest versions — then hand each fetched skill to
 `/setup:import-upstream-skill` for placement, `upstream-*` provenance, and the capability-contract
@@ -39,4 +39,4 @@ adaptation. Don't reinvent the import mechanics.
 
 - Related: [import-upstream-skills](../import-upstream-skills/PRD.md) (mattpocock GitHub — different *source*, but its `/setup:import-upstream-skill` is the shared *integration* step to reuse)
 - Related: [check-updates-detection-scope](../check-updates-detection-scope/PRD.md)
-- _Created by /planning:scratch._
+- *Created by /planning:scratch.*
diff --git a/.scratch/import-upstream-skills/PRD.md b/.scratch/import-upstream-skills/PRD.md
index 55e0b50..cce9142 100644
--- a/.scratch/import-upstream-skills/PRD.md
+++ b/.scratch/import-upstream-skills/PRD.md
@@ -9,7 +9,7 @@ must be source-agnostic.
 
 > **Scope decision (2026-07-05):** this feature delivers **the skill that enables importing** — not
 > the actual mattpocock import run. The generic process now lives as a first-class skill,
-> `/setup:import-upstream-skill` (`shared/skills/setup/import-upstream-skill/SKILL.md`). Running the
+> `/setup:import-upstream-skill` (`ai-artifacts/skills/shared/setup/import-upstream-skill/SKILL.md`). Running the
 > concrete 9-skill mattpocock import stays as follow-up work — issues 03 (coding), 04 (planning), 05
 > (setup) — each executed by invoking the new skill.
 
@@ -19,7 +19,7 @@ must be source-agnostic.
   8-step process (snapshot → intent group → placement → `METADATA.md` provenance → capability-contract
   adaptation → verify via `write-a-skill` → origin-map update → sync). Source-agnostic; handles
   GitHub upstreams, local/global copies, and local forks (no dangling `upstream-commit`).
-- ✅ **Origin map updated:** `shared/skills/README.md` lists `import-upstream-skill` as a local original.
+- ✅ **Origin map updated:** `ai-artifacts/skills/shared/README.md` lists `import-upstream-skill` as a local original.
 - ⏳ **Actual imports remain:** issues 03/04/05 (import the coding / planning / setup clusters) are the
   first consumers of the new skill; the config-placement decision (issue 02) is only needed when the
   planning cluster is actually imported, so it stays deferred until then.
@@ -33,7 +33,7 @@ bash flavored, not adapted to Claude Code on Windows/pwsh), and one of them —
 
 ## Solution
 
-Import each missing skill into `shared/skills/<group>/<name>/` under my intent-based grouping, with
+Import each missing skill into `ai-artifacts/skills/shared/<group>/<name>/` under my intent-based grouping, with
 `METADATA.md` provenance pointing at Matt's repo/path/checkpoint, then run the Claude Code
 capability-contract adaptation pass on them. Resolve two design decisions first (grouping + the
 config-distribution question) because they shape where things land.
@@ -101,7 +101,7 @@ worth carrying into the import (especially `setup-pre-commit`, which diverges ha
   `upstream-author`, `upstream-repo`, `upstream-path`, and `upstream-commit`. Do not duplicate the
   exact upstream checkpoint in summary docs.
 - **New `planning` group** for to-issues / to-prd / triage. Update `.gitignore` (add
-  `/.claude/commands/planning/`) and re-run `scripts/sync-skills.ps1`.
+  `/.claude/commands/planning/`) and re-run `scripts/setup-repo.ps1 -SkipHooks`.
 - **Capability-contract adaptation** (same principle as pass 1): shell/tool path where available,
   conversational fallback otherwise. Convert Matt's `.sh` helpers to pwsh.
 - **Tracker default = local-markdown `.scratch/`** (this repo already uses it). The planning skills
@@ -155,7 +155,7 @@ comment, omit `upstream-commit` so the staleness check skips it (it's no longer
 
 ## Testing Decisions
 
-- After each import: `scripts/sync-skills.ps1`, then invoke `/group:name` and confirm body +
+- After each import: `scripts/setup-repo.ps1 -SkipHooks`, then invoke `/group:name` and confirm body +
   resources load and any `!command`/script paths resolve.
 - For pwsh-converted scripts (diagnose HITL loop, git-guardrails block hook): run them on a throwaway
   target and confirm they behave (and that the guardrail actually blocks a dangerous git command).
@@ -177,13 +177,11 @@ comment, omit `upstream-commit` so the staleness check skips it (it's no longer
 ## Attribution
 
 These skills derive from [mattpocock/skills](https://github.com/mattpocock/skills). Per-skill
-provenance is in `METADATA.md`; consider adding upstream's `LICENSE` to this repo
-(e.g. `THIRD-PARTY/mattpocock-skills.LICENSE`) before publishing, since the repo redistributes adapted
-copies of his work.
+provenance is in `METADATA.md`.
 
 ## Further Notes
 
 - Upstream snapshot: `.temp/github.com_mattpocock/skills`; exact checkpoints belong in each imported
   skill's `METADATA.md`.
-- Provenance convention + origin map: `shared/skills/README.md`. Update flow: the `/setup:check-skill-updates` skill.
+- Provenance convention + origin map: `ai-artifacts/skills/shared/README.md`. Update flow: the `/setup:check-skill-updates` skill.
 - Claude Code adaptation principles & pass-1 backlog: `.scratch/claude-code-skill-adaptation/`.
diff --git a/.scratch/import-upstream-skills/issues/03-import-coding-skills.md b/.scratch/import-upstream-skills/issues/03-import-coding-skills.md
index 6b642ae..51f590f 100644
--- a/.scratch/import-upstream-skills/issues/03-import-coding-skills.md
+++ b/.scratch/import-upstream-skills/issues/03-import-coding-skills.md
@@ -4,8 +4,8 @@ Status: done (all three coding skills imported + dual-mode adapted 2026-07-05)
 
 ## What to build
 
-Import these three from Matt's repo into `shared/skills/coding/` with per-skill `METADATA.md`
-provenance, copying bundled resources verbatim, then `scripts/sync-skills.ps1`:
+Import these three from Matt's repo into `ai-artifacts/skills/shared/coding/` with per-skill `METADATA.md`
+provenance, copying bundled resources verbatim, then `scripts/setup-repo.ps1 -SkipHooks`:
 
 - `diagnose` (+ `scripts/hitl-loop.template.sh` — keep the file; pwsh equivalent is an adaptation task)
 - `improve-codebase-architecture` (+ DEEPENING, INTERFACE-DESIGN, LANGUAGE, HTML-REPORT)
@@ -18,7 +18,7 @@ faithful import + grouping + provenance only.
 
 - [ ] Three skills under `skills/coding/<name>/` with correct `upstream-*` frontmatter
 - [ ] Bundled resources present; `zoom-out` retains `disable-model-invocation`
-- [ ] `sync-skills.ps1` run; `/coding:diagnose` etc. resolve; resource links rewritten correctly
+- [ ] `setup-repo.ps1 -SkipHooks` run; `/coding:diagnose` etc. resolve; resource links rewritten correctly
 - [ ] `/setup:check-skill-updates` shows them `UP-TO-DATE`
 
 ## Progress (2026-07-05)
@@ -26,13 +26,13 @@ faithful import + grouping + provenance only.
 Per the corrected scope (actually import + adapt the skills, dual-mode), import and adaptation are
 done together here rather than deferring adaptation to issue 06:
 
-- ✅ **`diagnose`** → `shared/skills/coding/diagnose/` with `upstream-*` provenance. Added a **Modes
+- ✅ **`diagnose`** → `ai-artifacts/skills/shared/coding/diagnose/` with `upstream-*` provenance. Added a **Modes
   (capability contract)** section — shell/FS present ⇒ build & run the loop; no shell (claude.ai) ⇒
   design the loop and drive the user through it, working off the signal they paste. HITL helper now
   ships **pwsh** (`scripts/hitl-loop.template.ps1`, primary) **+ bash** (`.sh`, cross-platform).
-- ✅ **`zoom-out`** → `shared/skills/coding/zoom-out/` with provenance; `disable-model-invocation`
+- ✅ **`zoom-out`** → `ai-artifacts/skills/shared/coding/zoom-out/` with provenance; `disable-model-invocation`
   preserved; added a one-line "if a filesystem is available… else work from pasted context" note.
-- ✅ **`improve-codebase-architecture`** → `shared/skills/coding/improve-codebase-architecture/` with
+- ✅ **`improve-codebase-architecture`** → `ai-artifacts/skills/shared/coding/improve-codebase-architecture/` with
   provenance + all four resources (DEEPENING / INTERFACE-DESIGN / LANGUAGE / HTML-REPORT). Added a
   **Modes** section (Explore subagent + temp-file report vs. reason over pasted code + downloadable
   report; CONTEXT/ADR edits inline vs. proposed-as-text). Repointed the two `../grill-with-docs/`
diff --git a/.scratch/import-upstream-skills/issues/04-import-planning-cluster.md b/.scratch/import-upstream-skills/issues/04-import-planning-cluster.md
index ea07d5f..736e5e5 100644
--- a/.scratch/import-upstream-skills/issues/04-import-planning-cluster.md
+++ b/.scratch/import-upstream-skills/issues/04-import-planning-cluster.md
@@ -5,7 +5,7 @@ Status: ready-for-agent
 ## What to build
 
 Import these from Matt's `engineering/` into `skills/planning/` with `upstream-*` provenance,
-copying resources (triage's AGENT-BRIEF, OUT-OF-SCOPE) verbatim, then `scripts/sync-skills.ps1`.
+copying resources (triage's AGENT-BRIEF, OUT-OF-SCOPE) verbatim, then `scripts/setup-repo.ps1 -SkipHooks`.
 Wire them to read tracker + label config from wherever issue 02 lands, defaulting to this repo's
 local-markdown `.scratch/` tracker.
 
@@ -14,7 +14,7 @@ local-markdown `.scratch/` tracker.
 - [ ] `to-issues`, `to-prd`, `triage` under `skills/planning/<name>/` with `upstream-*` frontmatter
 - [ ] triage resources present
 - [ ] Skills reference the centralized config (issue 02), not a per-skill copy
-- [ ] Default tracker = local-markdown `.scratch/`; `sync-skills.ps1` run; `/planning:*` resolve
+- [ ] Default tracker = local-markdown `.scratch/`; `setup-repo.ps1 -SkipHooks` run; `/planning:*` resolve
 - [ ] `/setup:check-skill-updates` shows them `UP-TO-DATE`
 
 ## Tracker-contract prerequisites (from `understand-scratch-skill` §3a)
diff --git a/.scratch/import-upstream-skills/issues/05-import-setup-hook-skills.md b/.scratch/import-upstream-skills/issues/05-import-setup-hook-skills.md
index eb36cee..8024990 100644
--- a/.scratch/import-upstream-skills/issues/05-import-setup-hook-skills.md
+++ b/.scratch/import-upstream-skills/issues/05-import-setup-hook-skills.md
@@ -18,11 +18,11 @@ Status: done (git-guardrails + setup-pre-commit imported 2026-07-05; setup clust
 - [ ] git-guardrails imported; bash guard has a working pwsh equivalent; hook blocks a dangerous git command in test
 - [ ] Decision 3 recorded; setup-pre-commit reflects my toolchain (pre-commit framework), lineage noted
 - [ ] Provenance correct: git-guardrails tracks upstream; setup-pre-commit marked as fork (skipped by update check)
-- [ ] `sync-skills.ps1` run; `/setup:git-guardrails`, `/setup:setup-pre-commit` resolve
+- [ ] `setup-repo.ps1 -SkipHooks` run; `/setup:git-guardrails`, `/setup:setup-pre-commit` resolve
 
 ## Progress (2026-07-05)
 
-- ✅ **git-guardrails** → `shared/skills/setup/git-guardrails/`. Imported from the **global-prior**
+- ✅ **git-guardrails** → `ai-artifacts/skills/shared/setup/git-guardrails/`. Imported from the **global-prior**
   (already localized: pwsh + bash, Windows-primary hook wiring) rather than the raw bash-only artifact.
   Wrote the **pwsh guard** `scripts/block-dangerous-git.ps1` (uses `ConvertFrom-Json`, no `jq`
   dependency; same regex pattern list as the bash guard) alongside the bash one. Added an
@@ -30,7 +30,7 @@ Status: done (git-guardrails + setup-pre-commit imported 2026-07-05; setup clust
   Provenance tracks `misc/git-guardrails-claude-code` in the skill's `METADATA.md`; README no longer
   duplicates exact upstream checkpoints. Bash guard smoke-tested: `git push` → exit 2, `git status`
   → exit 0; pwsh mirrors the same patterns.
-- ✅ **setup-pre-commit** → `shared/skills/setup/setup-pre-commit/`. **Decision 3 resolved:** imported
+- ✅ **setup-pre-commit** → `ai-artifacts/skills/shared/setup/setup-pre-commit/`. **Decision 3 resolved:** imported
   the global-prior (pre-commit framework for PS/MD/AsciiDoc/SQL) as a **local fork** — SoT = mine,
   lineage recorded in an HTML comment, **no `upstream-*` frontmatter** so `/setup:check-skill-updates`
   skips it (it shares only a name with Matt's Husky/lint-staged version). Added an Applicability note
diff --git a/.scratch/import-upstream-skills/issues/06-adapt-imported-skills.md b/.scratch/import-upstream-skills/issues/06-adapt-imported-skills.md
index 45334a2..d4884ef 100644
--- a/.scratch/import-upstream-skills/issues/06-adapt-imported-skills.md
+++ b/.scratch/import-upstream-skills/issues/06-adapt-imported-skills.md
@@ -15,7 +15,7 @@ repo/file/shell access.
 - [ ] Each imported skill classified (conversational / agentic) and adapted accordingly
 - [ ] `diagnose` HITL loop and `git-guardrails` guard exist as pwsh, not bash-only
 - [ ] Agentic skills exercise real tool access on a throwaway target; fallbacks preserved
-- [ ] Each verified via `/session:write-a-skill`; `sync-skills.ps1` run after edits
+- [ ] Each verified via `/session:write-a-skill`; `setup-repo.ps1 -SkipHooks` run after edits
 
 ## Blocked by
 
diff --git a/.scratch/incorporate-global-claude-setup/PRD.md b/.scratch/incorporate-global-claude-setup/PRD.md
index 0eb5c31..ee69464 100644
--- a/.scratch/incorporate-global-claude-setup/PRD.md
+++ b/.scratch/incorporate-global-claude-setup/PRD.md
@@ -2,7 +2,7 @@
 
 Status: ready-for-human
 
-The claude.ai profile is now repo-managed (`instructions/claude-ai/profile.md`). The **Claude Code**
+The claude.ai profile is now repo-managed (`ai-artifacts/instructions/anthropic/claude-ai/profile.md`). The **Claude Code**
 global setup (`~/.claude/`) is the other half and is not yet in the repo. Bring the relevant parts
 in as harness-scoped source-of-truth copies, the same way skills are managed.
 
@@ -26,11 +26,11 @@ instead of being maintained twice.
 
 ## What to bring in
 
-| Source (`~/.claude/`)                   | Proposed repo location                              | Notes                                                                |
-| --------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- |
-| `CLAUDE.md` (global instructions)       | `instructions/claude-code/CLAUDE.md`                | Harness-scoped; overlaps with the profile                            |
-| `settings.json` (permissions/hooks/MCP) | `settings/claude-code/settings.json` *(or similar)* | Decide: global settings vs project settings; secrets stay out        |
-| Global skills (`commands/`)             | already handled by the skills work                  | Prior-version globals captured in `import-upstream-skills` artifacts |
+| Source (`~/.claude/`)                   | Proposed repo location                                             | Notes                                                                |
+| --------------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------- |
+| `CLAUDE.md` (global instructions)       | `ai-artifacts/instructions/claude-code/CLAUDE.md`                  | Harness-scoped; overlaps with the profile                            |
+| `settings.json` (permissions/hooks/MCP) | `ai-artifacts/mcp-config/claude-code/settings.json` *(or similar)* | Decide: global settings vs project settings; secrets stay out        |
+| Global skills (`commands/`)             | already handled by the skills work                                 | Prior-version globals captured in `import-upstream-skills` artifacts |
 
 ## Pending content to fold in when hoisting `CLAUDE.md`
 
@@ -49,7 +49,7 @@ waiting to be merged into it when it lands:
 
 ## Open decisions
 
-1. **Sync direction** — repo SoT → `~/.claude/` via a sync script (like `sync-skills.ps1`), or
+1. **Sync direction** — repo SoT → `~/.claude/` via the repo setup sync path, or
    fetch-once-and-hand-maintain? Recommend repo-SoT + sync for consistency with skills.
 2. **Overlap → `AGENTS.md`** — what is identical between `profile.md` and `CLAUDE.md` and should live
    once in a root `AGENTS.md` (read by Claude Code + Codex + Copilot), leaving only harness-specific
@@ -62,7 +62,7 @@ waiting to be merged into it when it lands:
 ## Out of Scope
 
 - Credentials, chat history, sessions — never copied or versioned.
-- The claude.ai profile itself (already in `instructions/claude-ai/`).
+- The claude.ai profile itself (already in `ai-artifacts/instructions/anthropic/claude-ai/`).
 - The full instructions/settings taxonomy (vendor tag, other harnesses) — repo-scaffold handoff.
 
 ## Further Notes
diff --git a/.scratch/mail-to-doc/PRD.md b/.scratch/mail-to-doc/PRD.md
index 3fd439a..f163157 100644
--- a/.scratch/mail-to-doc/PRD.md
+++ b/.scratch/mail-to-doc/PRD.md
@@ -5,7 +5,7 @@ Status: in-progress (issue 01 markers landed 2026-07-05; issues 02/03 pending)
 ## Problem Statement
 
 The existing `mail-to-adoc` tool — now a first-class skill at
-[`shared/skills/documents/mail-to-adoc/`](../../shared/skills/documents/mail-to-adoc/) — converts
+[`ai-artifacts/skills/shared/documents/mail-to-adoc/`](../../ai-artifacts/skills/shared/documents/mail-to-adoc/) — converts
 `.eml` files to AsciiDoc but has several issues blocking a 1.0.0 release:
 
 1. The HTML→AsciiDoc conversion logic is tangled with the main orchestration code, making it hard
@@ -32,20 +32,24 @@ Reference: Mail "Scratch 'mail-to-adoc'" from 28.06.2026 (see `artifacts/` for t
 ## Solution
 
 ### 1 — Split conversion logic
+
 Extract the HTML→AsciiDoc transformation into a standalone skill or module (e.g.
 `html-to-adoc`), called by the main `mail-to-doc` orchestrator. This enables independent
 testing and future reuse.
 
 ### 2 — Rename & add Markdown target
+
 Rename the skill from `mail-to-adoc` to `mail-to-doc`. Add a `--format` / `-f` flag
 (`adoc` | `md`; default `adoc`) so users can select the output format.
 
 ### 3 — Fix image attachments (links only)
+
 When an attachment is an image, render it as a link rather than an image macro.
 Expected AsciiDoc: `* link:../../Attachments/<timestamp>-<name>[<name>]`
 Expected Markdown: `* [<name>](../../Attachments/<timestamp>-<name>)`
 
 ### 4 — Fix table row separator
+
 Diagnose and remove the spurious `+` appended after each table row. Likely an off-by-one
 in the row-close logic of the HTML table→AsciiDoc table converter.
 
@@ -67,7 +71,7 @@ in the row-close logic of the HTML table→AsciiDoc table converter.
 - **The deliverable lives outside the scratch (2026-07-05).** A scratch holds the *idea*; a working
   skill is a *deliverable* and belongs in the repo's skills tree. The tool was promoted from
   `artifacts/mail-to-adoc/` to the first-class skill
-  [`shared/skills/documents/mail-to-adoc/`](../../shared/skills/documents/mail-to-adoc/) (new
+  [`ai-artifacts/skills/shared/documents/mail-to-adoc/`](../../ai-artifacts/skills/shared/documents/mail-to-adoc/) (new
   `documents` group — no existing group fits document conversion). This scratch keeps only the
   idea + tracking; it no longer carries the code. Note: the skill's `_PROJECT_ROOT` assumes a
   `<root>/skills/<name>/` layout, so the extra `documents/` level shifts it in-repo — irrelevant here
@@ -97,4 +101,4 @@ in the row-close logic of the HTML table→AsciiDoc table converter.
   two path tests asserted the old `docs/` layout (fixed to `01_Korrespondenz/Attachments/`), and two
   referenced removed functions (`_add_hardbreaks_to_reply_headers`, `_auto_name`) now skipped pending
   a delete-vs-restore call. The zip-to-zip diff (`.temp/` originals) still needs the workstation.
-- _Created by /planning:scratch._
+- *Created by /planning:scratch.*
diff --git a/.scratch/mail-to-doc/issues/01-incorporate-latest-changes.md b/.scratch/mail-to-doc/issues/01-incorporate-latest-changes.md
index 5fc36aa..4b42cb3 100644
--- a/.scratch/mail-to-doc/issues/01-incorporate-latest-changes.md
+++ b/.scratch/mail-to-doc/issues/01-incorporate-latest-changes.md
@@ -9,7 +9,7 @@ requirements from the user.
 
 1. **Diff the two drops** — `.temp/mail-to-adoc-2026-06-28.zip` vs
    `.temp/mail-to-adoc-2026-07-05.zip` (gitignored local backups; the redacted
-   extracted working copy is `shared/skills/documents/mail-to-adoc/`). Record what changed and check whether any of the four
+   extracted working copy is `ai-artifacts/skills/shared/documents/mail-to-adoc/`). Record what changed and check whether any of the four
    problems in PRD.md (tangled HTML→AsciiDoc logic, adoc-only output, image macros
    instead of links, spurious `+` after table rows) were already fixed upstream.
    Update PRD.md accordingly.
diff --git a/.scratch/mail-to-doc/issues/02-analyse-effectiveness.md b/.scratch/mail-to-doc/issues/02-analyse-effectiveness.md
index 2b012fa..7ac799c 100644
--- a/.scratch/mail-to-doc/issues/02-analyse-effectiveness.md
+++ b/.scratch/mail-to-doc/issues/02-analyse-effectiveness.md
@@ -4,7 +4,7 @@ Status: needs-triage
 
 ## What to build
 
-A written analysis of how well the 2026-07-05 version (`shared/skills/documents/mail-to-adoc/`)
+A written analysis of how well the 2026-07-05 version (`ai-artifacts/skills/shared/documents/mail-to-adoc/`)
 actually works, as input for issue 03. Note: the artifacts copy is redacted
 (placeholder emails/party names); the unredacted original is `.temp/mail-to-adoc-2026-07-05.zip`
 (local-only). Cover:
diff --git a/.scratch/profile-improvement/PRD.md b/.scratch/profile-improvement/PRD.md
index 59e740b..6754bd7 100644
--- a/.scratch/profile-improvement/PRD.md
+++ b/.scratch/profile-improvement/PRD.md
@@ -3,9 +3,10 @@
 Status: ready-for-human
 
 The live source-of-truth is Settings → Instructions for Claude (claude.ai / Claude Desktop Chat).
-The repo copy is `instructions/claude-ai/profile.md` — edit here, paste there.
+The repo copy is `ai-artifacts/instructions/anthropic/claude-ai/profile.md` — edit here, paste there.
 
 Two versions are in `artifacts/`:
+
 - `profile-current.md` — the version refined in a claude.ai session; live as of 2026-06
 - `profile-prior.md` — the previous version; use as counterpart to identify what changed and whether
   any prior formulation was actually sharper
@@ -27,7 +28,7 @@ review; the behavioral eval is a separate session.
 Diff the two versions rule by rule. For each rule where they differ, decide: is the current
 version more precise, or did compression in the prior version lose something, or did the current
 version introduce unnecessary verbosity? Apply the better formulation back to
-`instructions/claude-ai/profile.md` and paste the final result into Settings.
+`ai-artifacts/instructions/anthropic/claude-ai/profile.md` and paste the final result into Settings.
 
 ## User Stories
 
@@ -40,7 +41,7 @@ version introduce unnecessary verbosity? Apply the better formulation back to
 
 ## Implementation Decisions
 
-- **Source of truth:** `instructions/claude-ai/profile.md`; paste into Settings when updated
+- **Source of truth:** `ai-artifacts/instructions/anthropic/claude-ai/profile.md`; paste into Settings when updated
 - **Diff axis:** per-rule comparison, not whole-file; the structure (§1–§9 + Facts) is settled
   <!-- [RE-CONFIRM] "structure is settled" was decided in a claude.ai session; confirm before the diff pass. -->
 
@@ -59,4 +60,4 @@ version introduce unnecessary verbosity? Apply the better formulation back to
 - The CLAUDE.md at `~/.claude/CLAUDE.md` is a different file (global Claude Code instructions);
   do not conflate with this profile
 - The profile header "Paste into: Settings → Instructions for Claude" should stay in
-  `instructions/claude-ai/profile.md` as a placement reminder but must be stripped before pasting
+  `ai-artifacts/instructions/anthropic/claude-ai/profile.md` as a placement reminder but must be stripped before pasting
diff --git a/.scratch/public-repo-compliance/PRD.md b/.scratch/public-repo-compliance/PRD.md
index 856f00c..a88f21a 100644
--- a/.scratch/public-repo-compliance/PRD.md
+++ b/.scratch/public-repo-compliance/PRD.md
@@ -11,12 +11,12 @@ The repo is already **PUBLIC** (`github.com/DenWin/ai-lab`), but the items gated
 publishing" never ran:
 
 1. **Third-party attribution.** [import-upstream-skills](../import-upstream-skills/PRD.md) says to
-   add upstream's LICENSE (e.g. `THIRD-PARTY/mattpocock-skills.LICENSE`) "before publishing, since
+  add upstream's LICENSE (historically tracked in a dedicated third-party attribution folder) "before publishing, since
    the repo redistributes adapted copies of his work." Vendored copies are committed (mattpocock
-   skills under `shared/skills/` + `.scratch/*/artifacts/`; MIT-licensed `claude-video` under
+   skills under `ai-artifacts/skills/shared/` + `.scratch/*/artifacts/`; MIT-licensed `claude-video` under
    `.scratch/add-watch-skill/artifacts/`), and the repo is live.
 2. **Profile exposure.** The personal behavioral profile
-   ([anthropic/claude-ai/instructions/profile.md](../../anthropic/claude-ai/instructions/profile.md))
+   ([ai-artifacts/instructions/anthropic/claude-ai/profile.md](../../ai-artifacts/instructions/anthropic/claude-ai/profile.md))
    and committed `.scratch` history are public. Probably fine — but it should be a conscious
    decision, not a side effect of `gh repo create`.
 3. **Free hardening wins.** [[harden-github-repo]] is still needs-triage, and its central open
@@ -26,9 +26,9 @@ publishing" never ran:
 
 ## Solution
 
-_Proposed — refine in triage:_
+*Proposed — refine in triage:*
 
-- Add `THIRD-PARTY/` attribution files for all vendored upstream content; audit `.scratch/*/artifacts/`
+- Add attribution files for all vendored upstream content; audit `.scratch/*/artifacts/`
   for anything else redistributed.
 - Explicit go/no-go on public visibility of the profile and scratch history (alternative: flip repo
   to private until [[harden-github-repo]] lands).
@@ -38,16 +38,17 @@ _Proposed — refine in triage:_
 ## Progress (2026-07-04)
 
 - ✅ **Item 1 — attribution:** both upstreams verified MIT.
-  [THIRD-PARTY/](../../THIRD-PARTY/README.md) created with license copies for vendored sources
-  (`mattpocock-skills.LICENSE`, `bradautomates-claude-video.LICENSE`) plus a notice map. Exact
-  upstream checkpoints for skills live in each skill's `METADATA.md`, not in summary docs.
+  Historical note: a dedicated third-party attribution folder existed when this item was first
+  completed, but those repo copies are no longer tracked after later cleanup. The remaining durable
+  provenance in this repo is each imported skill's `METADATA.md`; this entry should not be read as a
+  current inventory of committed license-copy files.
 - ✅ **Item 3 — free hardening wins:** secret scanning, push protection, and Dependabot alerts
   enabled via `gh api`. **Branch protection deliberately NOT enabled** — it would block the current
   direct-to-main workflow; decide it together with [[gated-work-prd-issue-approval]] (which wants a
   PR flow anyway) inside [[harden-github-repo]].
 - ✅ **Item 2 — decided 2026-07-05: keep public, after a scrub.** Decision: `keep-public`. Before
   confirming, a redaction audit swept the personal profile
-  ([anthropic/claude-ai/instructions/profile.md](../../anthropic/claude-ai/instructions/profile.md))
+  ([ai-artifacts/instructions/anthropic/claude-ai/profile.md](../../ai-artifacts/instructions/anthropic/claude-ai/profile.md))
   and the full `.scratch/` tree (+ the committed config artifacts) for anything personal or sensitive.
 
   **Audit scope & result (nothing required redaction):**
@@ -65,6 +66,6 @@ _Proposed — refine in triage:_
 
 ## Further Notes
 
-- Related: [[harden-github-repo]] (settings/Actions side), [[import-upstream-skills]] (where the
+- Related: [[harden-github-repo]] (GitHub Actions/settings side), [[import-upstream-skills]] (where the
   attribution requirement was first recorded).
-- _Created by Claude Fable 5 via /planning:scratch._
+- *Created by Claude Fable 5 via /planning:scratch.*
diff --git a/.scratch/repo-scaffold/PRD.md b/.scratch/repo-scaffold/PRD.md
index 858ee41..9fb28b2 100644
--- a/.scratch/repo-scaffold/PRD.md
+++ b/.scratch/repo-scaffold/PRD.md
@@ -16,8 +16,8 @@ The structure decisions were resolved via grill-me (2026-06-04) and the layout m
 > superseded. Canonical layout is now `shared/` (default) + `<vendor>/` + `<vendor>/<harness>/`,
 > most-specific-wins; **loose folders** (no plugin bundles); folders created **on demand**. See
 > [docs/repo-layout.adoc](../../docs/repo-layout.adoc) — the canonical layout reference.
-> Done so far: `git init`; skills → `shared/skills/`; profile →
-> `anthropic/claude-ai/instructions/profile.md`; `sync-skills.ps1` retargeted + re-run; layout doc
+> Done so far: `git init`; skills → `ai-artifacts/skills/shared/`; profile →
+> `ai-artifacts/instructions/anthropic/claude-ai/profile.md`; setup-repo mirror sync retargeted + re-run; layout doc
 > authored. Remaining: `AGENTS.md`, file placement, remote, initial commit.
 
 `git init` (done) unblocks the `tdd`-skill→foundation-doc git-repo reference (see
@@ -26,15 +26,15 @@ This also folded in the earlier `init-git-repo` stub.
 
 ## Scope
 
-Phase 1 of the handoff (skill adaptation) is largely done — skills live under `shared/skills/` and
+Phase 1 of the handoff (skill adaptation) is largely done — skills live under `ai-artifacts/skills/shared/` and
 remaining work is tracked in [claude-code-skill-adaptation](../claude-code-skill-adaptation/PRD.md)
 and [import-upstream-skills](../import-upstream-skills/PRD.md). This feature is **Phase 2 only**:
 
 1. ✅ `git init`, default branch `main`. `.gitignore` already reconciled (`.claude/commands/*`
    generated; `.temp/*` staged) — no change needed.
-2. ✅ Structure resolved + migrated: skills → `shared/skills/`, profile →
-   `anthropic/claude-ai/instructions/`, `sync-skills.ps1` retargeted, [docs/repo-layout.adoc](../../docs/repo-layout.adoc)
-   authored. Per-harness artifact folders (`settings/`, `mcp/`, `hooks/`, `output-styles/`) are
+2. ✅ Structure resolved + migrated: skills → `ai-artifacts/skills/shared/`, profile →
+   `ai-artifacts/instructions/anthropic/claude-ai/`, setup-repo mirror sync retargeted, [docs/repo-layout.adoc](../../docs/repo-layout.adoc)
+   authored. Per-harness artifact folders (`ai-artifacts/mcp-config/`, `ai-artifacts/hooks/`, `ai-artifacts/output-styles/`) are
    created **on demand**, not pre-scaffolded.
 3. ✅ Root `AGENTS.md` authored (2026-07-04) as an **operational stub**: cross-harness facts only
    (layout, source-of-truth/mirror rules, `.scratch` workflow, conventions). The behavioral-overlap
@@ -53,8 +53,8 @@ and [import-upstream-skills](../import-upstream-skills/PRD.md). This feature is
 ## Decisions
 
 1. **#6 Taxonomy keying — RESOLVED (grill-me 2026-06-04).** `shared/` (default) + `<vendor>/` +
-   `<vendor>/<harness>/`, most-specific-wins. Skills default to `shared/skills/`; config
-   (instructions/settings/mcp/hooks/output-styles) lives under `<vendor>/<harness>/`. claude.ai adds
+   `<vendor>/<harness>/`, most-specific-wins. Skills default to `ai-artifacts/skills/shared/`; config
+   (instructions/mcp-config/hooks/output-styles) lives under `<vendor>/<harness>/`. claude.ai adds
    a `projects/<project-name>/` layer. No vendor-only "platform" key. Ref: docs/repo-layout.adoc.
 2. **#7 Packaging — RESOLVED.** Loose folders, not plugin bundles (personal use; can be wrapped into a
    plugin later if distribution ever matters).
diff --git a/.scratch/repo-scaffold/artifacts/HANDOFF-ai-lab-repo-structure.md b/.scratch/repo-scaffold/artifacts/HANDOFF-ai-lab-repo-structure.md
index f2e25e7..1d47f8d 100644
--- a/.scratch/repo-scaffold/artifacts/HANDOFF-ai-lab-repo-structure.md
+++ b/.scratch/repo-scaffold/artifacts/HANDOFF-ai-lab-repo-structure.md
@@ -98,12 +98,15 @@ ai-lab/
 ├── instructions/
 │   ├── global/               # account-wide / cross-vendor (e.g. profile)
 │   └── <vendor>/<harness>/   # specific overrides — keying per #6
-├── skills/                   # <vendor>/<harness>/ OR nested in plugin bundles — per #6/#7
-├── agents/                   # subagents
-├── hooks/                    # hook scripts / hooks.json
-├── mcp/                      # MCP server defs (.mcp.json) — was missing
-├── output-styles/            # was missing
-├── settings/                 # settings.json / permissions — was missing
+├── ai-artifacts/
+│   ├── skills/               # <vendor>/<harness>/ OR nested in plugin bundles — per #6/#7
+│   ├── agents/               # subagents
+│   ├── hooks/                # hook scripts / hooks.json
+│   ├── mcp-config/           # MCP server defs (.mcp.json)
+│   ├── output-styles/        # reusable output styles
+│   ├── prompts/              # reusable prompt packs
+│   ├── instructions/         # harness instruction surfaces
+│   └── plugins/              # plugin packaging
 └── eval/
     └── INSTRUCTION-EVAL.md
 ```
@@ -111,10 +114,10 @@ ai-lab/
 **Design rationale:**
 
 - `AGENTS.md` at root is the broadest-compatible entrypoint; harness/vendor-specific files
-  (`CLAUDE.md`, `copilot-instructions.md`) live under `instructions/`, keyed per #6.
+  (`CLAUDE.md`, `copilot-instructions.md`) live under `ai-artifacts/instructions/`, keyed per #6.
 - The living doc maps (harness × artifact type) with vendor as a tag — not "platform × harness".
   Start minimal; grow as knowledge grows.
-- If plugins win (#7), `skills/`, `agents/`, `hooks/`, `mcp/`, `output-styles/` nest inside
+- If plugins win (#7), `ai-artifacts/skills/`, `ai-artifacts/agents/`, `ai-artifacts/hooks/`, `mcp/`, `ai-artifacts/output-styles/` nest inside
   `plugins/<name>/` rather than at top level.
 - `eval/` holds `INSTRUCTION-EVAL.md` (built) + the pending harness (separate handoff).
 - `instructions/global/` holds the account-wide profile copy (source of truth stays Settings →
@@ -129,9 +132,9 @@ ai-lab/
    and grow detail pages lazily?
 3. PowerShell-Skripte project-specific files (`02-project-instructions.md`, `CLAUDE.md`,
    `POWERSHELL.md`, `powershell.yml`) — these belong to a specific claude.ai project, not
-   the global repo. Options: (a) move under `instructions/` keyed per #6 (e.g.
+   the global repo. Options: (a) move under `ai-artifacts/instructions/` keyed per #6 (e.g.
    `…/anthropic/projects/pwsh/`); (b) leave them in the claude.ai project only; (c) both. Confirm.
-4. `skills/shared/` concept: define what makes a skill "shared" — a skill whose _intent_ is
+4. `ai-artifacts/skills/shared/` concept: define what makes a skill "shared" — a skill whose _intent_ is
    cross-vendor (logic documented once, adapted per harness), or one whose _file format_ runs on
    multiple harnesses unchanged? (Ties to the capability-contract principle below.)
 5. Setup/init skill shape: monolithic setup skill (Matt's pattern) vs self-configuring vs
@@ -140,12 +143,12 @@ ai-lab/
 6. Terminology alignment: the matrix taxonomy below settles on **harness** (primary) + **vendor**
    (tag), with **model** excluded. The structure proposal and Requirements still say "platform"
    (and list Copilot as one — it's a harness). When scaffolding, decide the folder keys
-   accordingly: e.g. `instructions/<vendor>/<harness>/`, `skills/<vendor>/<harness>/`, and rename
+   accordingly: e.g. `ai-artifacts/instructions/<vendor>/<harness>/`, `ai-artifacts/skills/<vendor>/<harness>/`, and rename
    `docs/platforms/` → `docs/harnesses/`. Don't silently keep "platform" — it's the ambiguity
    this session flagged. This includes the living doc's own filename: rename `platform-matrix.md`
    → e.g. `compatibility-matrix.md` or `harness-matrix.md`.
-7. Packaging: loose artifact folders (`skills/`, `agents/`, `hooks/`, `mcp/`, `output-styles/`,
-   `settings/`) vs Claude Code **plugin bundles** (`.claude-plugin/plugin.json` wrapping them).
+7. Packaging: loose artifact folders (`ai-artifacts/skills/`, `ai-artifacts/agents/`, `ai-artifacts/hooks/`, `mcp/`, `ai-artifacts/output-styles/`,
+  `ai-artifacts/mcp-config/`, `ai-artifacts/plugins/`) vs Claude Code **plugin bundles** (`.claude-plugin/plugin.json` wrapping them).
    Plugins are the native share/install unit and compose cleanly; loose folders are simpler but
    not directly installable. Regardless of choice, the structure currently has no home for MCP
    defs, output styles, or settings — add them.
@@ -193,7 +196,7 @@ in plugin bundles) — treat them as illustrative, not committed.
    if user wants an adversarial pass).
 8. Place existing non-skill files (profile, INSTRUCTION-EVAL, project files) per the
    artifact inventory above.
-9. Place the adapted Claude Code skills from Phase 1 into `skills/`.
+9. Place the adapted Claude Code skills from Phase 1 into `ai-artifacts/skills/`.
 10. Author `AGENTS.md` root stub and the living compatibility-matrix draft (filename per #6).
 11. Initial commit + push.
 12. (Optional) In claude.ai: Settings → Connectors → GitHub Integration → connect + add
@@ -245,7 +248,7 @@ The "artifact type" axis needs a fuller vocabulary. Claude Code (richest harness
 | Skills (slash commands now unified in)              | `skills/<name>/SKILL.md`               | Claude family; others vary                                                     |
 | Subagents                                           | `agents/*.md`                          | Claude Code                                                                    |
 | Hooks                                               | `hooks.json` / `settings.json`         | Claude Code                                                                    |
-| Output styles                                       | `output-styles/`                       | Claude Code                                                                    |
+| Output styles                                       | `ai-artifacts/output-styles/`                       | Claude Code                                                                    |
 | **MCP servers**                                     | `.mcp.json`, `~/.claude.json`          | **cross-vendor (open protocol)** — Codex, Cursor, etc.; config location varies |
 | Settings / permissions                              | `settings.json`, `settings.local.json` | Claude Code                                                                    |
 | Plugins (bundle wrapping all the above)             | `.claude-plugin/plugin.json`           | Claude Code                                                                    |
diff --git a/.scratch/repo-scope-strays/PRD.md b/.scratch/repo-scope-strays/PRD.md
index 414f830..cdd9d6c 100644
--- a/.scratch/repo-scope-strays/PRD.md
+++ b/.scratch/repo-scope-strays/PRD.md
@@ -10,7 +10,7 @@ Quick capture — iron out in scratch-planning, don't action yet.
 The repo's declared identity (AI-configuration lab: skills, harness docs, instructions, tracker) is
 being diluted by undeclared strays:
 
-- `VSCode_Extsion/` (note the folder-name typo — "Extsion") — a shipped VS Code extension at repo
+- `VSCode_Extension/` (historically created as `VSCode_Extsion/`, with the typo) — a shipped VS Code extension at repo
   root, unrelated to the lab's stated purpose, with no README tying it in.
 - [mail-to-doc](../mail-to-doc/PRD.md) — a general software project (eml→AsciiDoc converter) riding
   in the `.scratch` tracker.
@@ -21,7 +21,7 @@ doesn't account for.
 
 ## Solution
 
-_Proposed — refine in triage. Two clean options:_
+*Proposed — refine in triage. Two clean options:*
 
 1. **Declare incubation:** "the lab also incubates small tools" — give them a home
    (e.g. `tools/` or `projects/`), fix the folder-name typo, add a README per tool, and record the
@@ -35,8 +35,8 @@ Either answer is fine — the undeclared middle isn't. Renaming/moving the exten
 ## Further Notes
 
 - Touches the repo-layout doc owned by [[repo-scaffold]]; coordinate if both are in flight.
-- 2026-07-04 scratch-plan (user input): `VSCode_Extsion/` **needs a README**; it is an outlier but
+- 2026-07-04 scratch-plan (user input): `VSCode_Extension/` **needs a README**; it is an outlier but
   not unrelated — it exists to make reading AsciiDoc files in VS Code easier, in support of AI
   projects. And [[mail-to-doc]] is a **skill**, not a software project — which weakens the "stray
   software project" framing above; re-frame during triage.
-- _Created by Claude Fable 5 via /planning:scratch._
+- *Created by Claude Fable 5 via /planning:scratch.*
diff --git a/.scratch/sync-skills-drift-check/PRD.md b/.scratch/sync-skills-drift-check/PRD.md
index e4c5586..aaf273d 100644
--- a/.scratch/sync-skills-drift-check/PRD.md
+++ b/.scratch/sync-skills-drift-check/PRD.md
@@ -1,21 +1,21 @@
-# PRD — Add a drift check to sync-skills.ps1
+# PRD — Add a drift check to generated mirror sync
 
 Status: done (2026-07-04 — see Progress)
 Origin: fable (Claude Fable 5 repo review, 2026-07-04)
 
 ## Problem Statement
 
-The SessionStart hook runs `sync-skills.ps1 -IfMissing`, which by design never refreshes a skill
+The SessionStart hook runs `setup-repo.ps1 -IfMissing`, which by design never refreshes a skill
 whose target already exists. There is no drift detection between the source of truth
-(`shared/skills/`) and the generated mirror (`.claude/commands/`). Consequence: after editing a
+(`ai-artifacts/skills/shared/`) and the generated mirror (`.claude/commands/`). Consequence: after editing a
 skill, the stale-mirror failure mode is the **default** path — the hook silently skips, and the
 session keeps invoking the old version until someone remembers to re-run the sync manually.
 
 ## Solution
 
-_Proposed — refine in triage:_
+*Proposed — refine in triage:*
 
-- Add a `-Check` mode to [scripts/sync-skills.ps1](../../scripts/sync-skills.ps1): compare source
+- Add a `-Check` mode to [scripts/setup-repo.ps1](../../scripts/setup-repo.ps1): compare source
   vs. mirror content (per-skill hash over SKILL.md + resources, with the same link rewriting
   applied), list stale skills, and return a nonzero exit code / warning line.
 - Have the SessionStart hook run `-IfMissing` **plus** `-Check`, so a stale mirror produces a
@@ -26,7 +26,7 @@ _Proposed — refine in triage:_
 
 ## Progress (2026-07-04 — done)
 
-- ✅ `-Check` mode added to [scripts/sync-skills.ps1](../../scripts/sync-skills.ps1): read-only,
+- ✅ `-Check` mode added to [scripts/setup-repo.ps1](../../scripts/setup-repo.ps1): read-only,
   compares expected mirror output (link rewriting applied) against the actual tree — command-file
   content (`-cne`), per-resource hashes, and extra-files-in-mirror all count as drift. Reports
   UP-TO-DATE / STALE / MISSING per skill; exit 1 on any drift; guarded against combining with
@@ -44,4 +44,4 @@ _Proposed — refine in triage:_
 
 - Failure mode identified in the Fable repo review (2026-07-04); the `-IfMissing` limitation is
   already documented in the script's own help — this scratch makes it observable.
-- _Created by Claude Fable 5 via /planning:scratch._
+- *Created by Claude Fable 5 via /planning:scratch.*
diff --git a/.scratch/testing-methodologies-foundation/issues/01-reference-doc-from-tdd-skill.md b/.scratch/testing-methodologies-foundation/issues/01-reference-doc-from-tdd-skill.md
index 3b7d378..a916414 100644
--- a/.scratch/testing-methodologies-foundation/issues/01-reference-doc-from-tdd-skill.md
+++ b/.scratch/testing-methodologies-foundation/issues/01-reference-doc-from-tdd-skill.md
@@ -15,7 +15,7 @@ section pointing at `docs/testing-methodologies-foundation.adoc` as the canonica
 
 - `SKILL.md` names the foundation doc as its source-of-truth and links it via a git-tracked path.
 - The link resolves in the published repo (not just on this machine).
-- After the edit: re-run `scripts/sync-skills.ps1` so the synced command copy carries the reference.
+- After the edit: re-run `scripts/setup-repo.ps1 -SkipHooks` so the synced command copy carries the reference.
 
 ## Blocked by
 
diff --git a/.scratch/understand-scratch-skill/PRD.md b/.scratch/understand-scratch-skill/PRD.md
index fe22d00..308f5d8 100644
--- a/.scratch/understand-scratch-skill/PRD.md
+++ b/.scratch/understand-scratch-skill/PRD.md
@@ -16,20 +16,20 @@ its real behavior, not the one-line description. Establish ground truth before r
 - What files does quick-capture create/touch — `PRD.md`, the `BACKLOG.md` row, anything else? What
   status/ranking does a new entry get, and how is the slug chosen?
 - How does it relate to the sibling skills (`scratch-plan`, `to-issues`, `to-prd`, `triage`) and the
-  canonical [LAYOUT.md](../../shared/skills/planning/scratch/LAYOUT.md) they all reference?
+  canonical [LAYOUT.md](../../ai-artifacts/skills/shared/planning/scratch/LAYOUT.md) they all reference?
 - Does the skill's documented behavior match what's been happening in practice (e.g. the stub PRDs +
   TBD backlog rows captured this session)? Any gaps between the SKILL.md and actual effect?
 
 ## Notes
 
-- Source of truth: `shared/skills/planning/scratch/SKILL.md` (+ `LAYOUT.md`, `RANKING.md`); deployed
+- Source of truth: `ai-artifacts/skills/shared/planning/scratch/SKILL.md` (+ `LAYOUT.md`, `RANKING.md`); deployed
   mirror under `.claude/commands/planning/scratch/`.
 - Motivation seems to be calibrating trust in the scratch workflow before leaning on it more (cf.
   [[gated-work-prd-issue-approval]], [[capture-not-execute]]).
 
 ## Findings (investigation 2026-07-05)
 
-Ground truth read from `shared/skills/planning/scratch/SKILL.md` (+ `LAYOUT.md`, `RANKING.md`) and
+Ground truth read from `ai-artifacts/skills/shared/planning/scratch/SKILL.md` (+ `LAYOUT.md`, `RANKING.md`) and
 `scratch-plan/SKILL.md`, cross-checked against the actual `.scratch/` tree — and, for the sibling
 relationship, against the committed mattpocock upstream artifacts of `to-issues`/`to-prd`/`triage`
 (§3a).
@@ -72,7 +72,7 @@ does no ranking. Ranking is `scratch-plan`'s job (§3).
   runs a one-question-at-a-time interview (priority / importance / effort, with fuzzy-input bucket
   rounding), computes `P × I × E`, and **rewrites** `BACKLOG.md` sorted with a `Last updated:` line.
   Division of labour: `scratch` = capture + display; `scratch-plan` = calibrate + rank.
-- **`to-issues` / `to-prd` / `triage` aren't imported into `shared/skills/` yet** — but their
+- **`to-issues` / `to-prd` / `triage` aren't imported into `ai-artifacts/skills/shared/` yet** — but their
   mattpocock **upstream versions are committed as artifacts** under
   `import-upstream-skills/artifacts/engineering/{to-issues,to-prd,triage}/SKILL.md` (plus the config
   docs `setup-matt-pocock-skills/{issue-tracker-local,triage-labels,domain}.md`). Import into
@@ -141,7 +141,7 @@ conventions from `LAYOUT.md` directly plus a small triage-label map.
   `scratch`'s append. The LAYOUT template documents only the minimal header a fresh `BACKLOG.md` gets.
 - **Deployment caveat.** `/planning:scratch` only resolves after the generated mirror exists
   (`.claude/commands/planning/scratch.md`). On a fresh clone / non-Windows sandbox the mirror is
-  absent (gitignored; `pwsh scripts/sync-skills.ps1` not yet run) — so the *source* behavior above is
+  absent (gitignored; `pwsh scripts/setup-repo.ps1 -SkipHooks` not yet run) — so the *source* behavior above is
   authoritative, but the slash command itself may be unavailable until sync runs.
 
 ### Reevaluation (2026-07-06)
@@ -152,7 +152,7 @@ User-requested recheck of the last open question ("how does it relate to the sib
 "Tracker-contract prerequisites" checklist on
 [`import-upstream-skills` issue 04](../import-upstream-skills/issues/04-import-planning-cluster.md).
 Verified against the repo today: the three siblings are still not imported
-(`shared/skills/planning/` = `scratch` + `scratch-plan` only), so the §3a answer stands unchanged.
+(`ai-artifacts/skills/shared/planning/` = `scratch` + `scratch-plan` only), so the §3a answer stands unchanged.
 Nothing remains in this scratch; follow-up work lives in [[import-upstream-skills]] issues 02/04.
 
 ### Verdict
diff --git a/.vscode/settings.json b/.vscode/settings.json
new file mode 100644
index 0000000..08fc951
--- /dev/null
+++ b/.vscode/settings.json
@@ -0,0 +1,6 @@
+{
+  "files.associations": {
+    "**/CODEOWNERS": "plaintext"
+  },
+  "task.allowAutomaticTasks": "on"
+}
diff --git a/.vscode/tasks.json b/.vscode/tasks.json
new file mode 100644
index 0000000..b4c57b5
--- /dev/null
+++ b/.vscode/tasks.json
@@ -0,0 +1,38 @@
+{
+  "version": "2.0.0",
+  "tasks": [
+    {
+      "label": "Bootstrap repo mirrors and hooks (if missing)",
+      "type": "shell",
+      "command": "pwsh",
+      "args": [
+        "-NoProfile",
+        "-File",
+        ".github/skills/setup_setup-repo/scripts/Invoke-SetupRepo.ps1",
+        "-IfMissing"
+      ],
+      "runOptions": {
+        "runOn": "folderOpen"
+      },
+      "presentation": {
+        "reveal": "never",
+        "panel": "dedicated",
+        "focus": false,
+        "showReuseMessage": false,
+        "clear": false
+      },
+      "problemMatcher": []
+    },
+    {
+      "label": "Bootstrap repo mirrors and hooks (full refresh)",
+      "type": "shell",
+      "command": "pwsh",
+      "args": [
+        "-NoProfile",
+        "-File",
+        ".github/skills/setup_setup-repo/scripts/Invoke-SetupRepo.ps1"
+      ],
+      "problemMatcher": []
+    }
+  ]
+}
diff --git a/AGENTS.md b/AGENTS.md
index 1a7d30d..98bf42e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,8 +8,10 @@ of truth; each harness loads live copies from its own locations.
 
 Canonical reference: [docs/repo-layout.adoc](docs/repo-layout.adoc). Short version:
 
-- `shared/` — vendor- and harness-agnostic artifacts (the default home; all skills live here)
-- `<vendor>/<harness>/` — harness-specific config (e.g. `anthropic/claude-ai/instructions/`)
+- `ai-artifacts/skills/shared/` — source skills; scope-specific skills go under `ai-artifacts/skills/<vendor>/<harness>/`
+- `ai-artifacts/instructions/<vendor>/<harness>/` — repo copies of harness instruction surfaces
+- `ai-artifacts/hooks/`, `ai-artifacts/mcp-config/`, `ai-artifacts/output-styles/`, `ai-artifacts/agents/`, `ai-artifacts/prompts/`, `ai-artifacts/plugins/` — artifact-type roots, each scoped below by
+  `shared/`, `<vendor>/`, or `<vendor>/<harness>/`
 - `docs/harnesses/` — per-harness self-descriptions: instruction surfaces, load models, limits
 - `.scratch/` — committed local-markdown issue tracker (PRDs + issues + ranked `BACKLOG.md`)
 - `.temp/` — gitignored landing zone for transient local working files, downloads, and scratch output
@@ -19,14 +21,14 @@ Most-specific wins; folders are created on demand, never pre-scaffolded empty.
 
 ## Rules that prevent damage
 
-- **Never edit `.claude/commands/`** — it is a generated, gitignored mirror. Edit the source under
-  `shared/skills/<group>/<name>/`, then rebuild: `pwsh scripts/sync-skills.ps1`.
-- **Never edit `.agents/skills/`** — it is the generated Codex skill mirror. Edit the source under
-  `shared/skills/<group>/<name>/`, then rebuild: `pwsh scripts/sync-skills.ps1`.
-- On a fresh clone or a cloud/sandbox session the generated mirrors may not exist. Run the sync script once —
+- **Never edit generated skill mirrors directly** (`.claude/commands/`, `.agents/skills/`,
+  `.github/skills/`) — these are generated, gitignored harness mirrors. Edit the source under
+  `ai-artifacts/skills/shared/<group>/<name>/`, then rebuild with `pwsh scripts/setup-repo.ps1`.
+- For a fresh clone bootstrap, run `pwsh scripts/setup-repo.ps1` to enable git hooks and refresh mirrors in one pass.
+- On a fresh clone or a cloud/sandbox session the generated mirrors may not exist. Run setup once —
   the SessionStart hook that does this locally lives in machine-local settings and won't be there.
-- Files under `instructions/` and `anthropic/*/instructions/` are repo copies for editing; the live
-  version sits in each harness's own surface (see [instructions/README.md](instructions/README.md)).
+- Files under `ai-artifacts/instructions/<vendor>/<harness>/` are repo copies for editing; the live version sits
+  in each harness's own surface (see [ai-artifacts/instructions/README.md](ai-artifacts/instructions/README.md)).
   Editing the repo copy changes nothing until it is deployed there.
 - Use `git mv` when moving or renaming tracked files.
 - This repo is **public**. No secrets anywhere — including instruction files and `.scratch/`.
@@ -46,25 +48,32 @@ explicitly requested against a specific scratch.
 The working rules for agents operating in `.scratch/` — capture≠execute, **deliverables live outside
 the scratch** (`artifacts/` is supporting material only), and ranking hygiene — live in the folder
 guide [.scratch/AGENTS.md](.scratch/AGENTS.md); structural layout stays in the `scratch` skill's
-[LAYOUT.md](shared/skills/planning/scratch/LAYOUT.md).
+[LAYOUT.md](ai-artifacts/skills/shared/planning/scratch/LAYOUT.md).
 
 ## Conventions
 
 - Primary environment: Windows, PowerShell 7 (`pwsh`). Write scripts in pwsh unless the target is
   cross-platform.
+- PowerShell runtime policy: each script declares `# RuntimePolicy: core-first|dual-runtime|desktop-only`.
+  Core-first is default (`#Requires -Version 7.0` + `#Requires -PSEdition Core`), dual-runtime must run
+  in both Windows PowerShell 5.1 and pwsh 7+, and desktop-only exceptions must be named
+  `*-windowsps.ps1` with `# RuntimeJustification: ...` plus
+  `#Requires -Version 5.1` + `#Requires -PSEdition Desktop`.
 - Docs: Markdown by default; AsciiDoc (`docs/*.adoc`) where richer syntax is needed.
+- Keep `AGENTS.md` Markdown because harnesses load it directly; keep `docs/repo-layout.adoc`
+  AsciiDoc because it is the richer canonical layout reference.
 - OKF: durable markdown reference/catalog docs should follow [docs/okf-adoption.md](docs/okf-adoption.md)
   unless another local format owns the file.
 - Skills follow the **capability contract**: if shell/filesystem is available, take the full
   agentic path; otherwise degrade to a conversational fallback. Write "if shell available" —
-  never "if <harness name>".
+  never "if [harness name]".
 - AI-generated code changes must follow the coding policies in `coding-policies/`:
   load `polyglot-policy.yaml` first, then the resolved language policy from
   `coding-policies/languages/` per `usage-policy.yaml`.
 - Vendored/imported skill provenance lives in each skill's `METADATA.md`; the origin map is
-  [shared/skills/README.md](shared/skills/README.md).
+  [ai-artifacts/skills/shared/README.md](ai-artifacts/skills/shared/README.md).
 - **Single owner per fact:** each fact lives in one canonical file; other docs link to it instead
-  of restating (layout → `docs/repo-layout.adoc`, skill origins → `shared/skills/README.md`,
+  of restating (layout → `docs/repo-layout.adoc`, skill origins → `ai-artifacts/skills/shared/README.md`,
   scratch working rules → `.scratch/AGENTS.md`, scratch structural layout → the `scratch` skill's
   `LAYOUT.md`).
 
@@ -81,4 +90,4 @@ hoist (`.scratch/incorporate-global-claude-setup/`) consolidates the shared subs
 - Keep changes scoped so only relevant workflows run; avoid touching unrelated files in the same PR.
 - CI lints exclude `.scratch/*/artefacts/**` and `.scratch/*/artifacts/**` on purpose; those
   paths are treated as supporting artifacts. Safety checks (secret/policy) still apply.
-- Enable local pre-commit checks in your clone with `pwsh scripts/install-git-hooks.ps1`.
+- Run `pwsh scripts/setup-repo.ps1` to bootstrap hooks and generated mirrors.
diff --git a/CONTEXT.md b/CONTEXT.md
new file mode 100644
index 0000000..8f93312
--- /dev/null
+++ b/CONTEXT.md
@@ -0,0 +1,165 @@
+# AI Lab
+
+AI Lab is a source-of-truth repo for AI-assisted-work configuration. It organizes shared skills,
+instruction surfaces, and harness-specific support artifacts so multiple AI harnesses can work from
+one maintained repo.
+
+## Language
+
+### Core context
+
+**AI Lab**:
+The repo itself: the maintained source of truth for AI-assisted-work configuration, documentation,
+and sync tooling.
+*Avoid*: workspace, toolkit, playground
+
+**Harness**:
+A concrete AI runtime or product surface that loads instructions, tools, and config in its own
+way. Claude Code, claude.ai, Copilot, and Codex are different harnesses.
+*Avoid*: model, vendor, agent
+
+**Vendor**:
+The platform/provider namespace above a harness, used for folder scoping such as `anthropic/` or
+`openai/`.
+*Avoid*: harness, runtime
+
+**Artifact type**:
+A top-level repo family defined by what something is, not by who uses it. Examples include
+`ai-artifacts/skills/`, `ai-artifacts/instructions/`, `ai-artifacts/mcp-config/`,
+`ai-artifacts/prompts/`, and `ai-artifacts/plugins/`.
+*Avoid*: bucket, misc, catch-all
+
+**Scope tier**:
+The level at which an artifact applies: `shared/`, `<vendor>/`, or `<vendor>/<harness>/`.
+More-specific tiers override more-general ones.
+*Avoid*: environment, layer
+
+### Skill system
+
+**Skill**:
+An invocable, task-shaped instruction package with a `SKILL.md` and optional bundled resources.
+In this repo, skills are grouped by intent under `ai-artifacts/skills/shared/<group>/<name>/`.
+*Avoid*: script, prompt, command
+
+**Source skill**:
+The maintained skill definition under `ai-artifacts/skills/shared/` or another scoped source folder. This is the
+editable copy.
+*Avoid*: mirror, generated skill
+
+**Generated mirror**:
+A harness-specific build artifact produced from source skills, such as `.claude/commands/` or
+`.agents/skills/`.
+*Avoid*: source skill, canonical copy
+
+**Capability contract**:
+The rule that a skill should take the full agentic path when shell/filesystem access exists and
+degrade to a conversational fallback when it does not.
+*Avoid*: harness-specific branch, hardcoded runtime path
+
+**Sync**:
+The act of rebuilding generated mirrors from source artifacts, typically via
+`pwsh scripts/setup-repo.ps1 -SkipHooks`.
+*Avoid*: deploy, publish
+
+### Planning and work tracking
+
+**Scratch**:
+The repo's committed local-markdown work tracker under `.scratch/`, used for PRDs, issues, ranking,
+and support artifacts.
+*Avoid*: backlog file, temp folder
+
+**PRD**:
+Product Requirements Document. In this repo it is the primary planning document for a scratch
+feature folder.
+*Avoid*: issue, ADR, spec note
+
+**Issue**:
+A smaller tracked work item inside a scratch feature, usually under `issues/`.
+*Avoid*: PRD, artifact
+
+**Scratch artifact**:
+Supporting material stored under `.scratch/<feature>/artifacts/`. It exists to support planning or
+analysis, not to be the final deliverable.
+*Avoid*: deliverable, permanent home
+
+**Deliverable**:
+A finished repo output that belongs in its real artifact-type home, such as `ai-artifacts/skills/`, `docs/`, or
+`ai-artifacts/mcp-config/`, rather than inside `.scratch/`.
+*Avoid*: scratch artifact, draft input
+
+### Instruction and config surfaces
+
+**Instruction surface**:
+A file or location a harness actually reads as instructions. Repo copies are edited here, but the
+live loaded copy may exist elsewhere.
+*Avoid*: any markdown file, README
+
+**Repo copy**:
+A source-controlled editing copy of a harness-owned artifact whose live version is stored outside
+the repo.
+*Avoid*: live version, generated mirror
+
+**Live version**:
+The copy actually loaded by a harness at runtime, such as a profile field, settings location, or
+generated mirror.
+*Avoid*: repo copy, source file
+
+**MCP**:
+Model Context Protocol. In this repo, MCP-related material belongs under `ai-artifacts/mcp-config/` when it is a
+durable repo artifact.
+*Avoid*: generic tool config, extension
+
+**Output style**:
+A reusable asset that shapes how a model formats or frames its responses.
+*Avoid*: skill, instruction surface
+
+### Documentation and provenance
+
+**ADR**:
+Architecture Decision Record. It captures a hard-to-reverse, context-sensitive decision that would
+otherwise be surprising later.
+*Avoid*: PRD, issue, meeting note
+
+**OKF**:
+Open Knowledge Format. In this repo it is the lightweight metadata/documentation convention used
+where no harness-owned format already controls the file.
+*Avoid*: frontmatter in general, runtime instruction format
+
+**Origin map**:
+The human-readable summary of where skills came from, maintained in `ai-artifacts/skills/shared/README.md`.
+*Avoid*: provenance file, metadata file
+
+## Flagged ambiguities
+
+**Artifact vs scratch artifact**:
+An artifact in the broad sense is any repo asset. A scratch artifact is specifically supporting
+material inside `.scratch/<feature>/artifacts/` and is not the final home of deliverables.
+
+**Instruction vs settings**:
+Instructions tell a harness how to behave. Settings configure a harness or tool. They may overlap in
+purpose but do not belong in the same artifact-type folder by default.
+
+**Source of truth vs live version**:
+The repo is the source of truth for maintained copies, but some live harness-loaded files exist
+outside the repo. Source of truth does not mean every runtime file is read from the repo directly.
+
+**Vendor vs harness**:
+The vendor is the provider namespace; the harness is the specific runtime/product surface beneath
+it. `anthropic/claude-ai/` names both, in that order.
+
+## Example dialogue
+
+Dev: Should this Codex-specific config live in `.scratch/` until we wire it up?
+
+Domain expert: No. If it is a real deliverable, put it in its artifact-type home. For repo config,
+that means something like `ai-artifacts/mcp-config/openai/codex/`.
+
+Dev: Then what belongs in `.scratch/`?
+
+Domain expert: The PRD, any follow-up issues, and supporting artifacts used to reason about the
+change. `.scratch/` tracks the work; it is not the final home of the output.
+
+Dev: And if I need to adapt a skill for two harnesses?
+
+Domain expert: Edit the source skill first. The generated mirrors are build artifacts, so you sync
+them after the source change rather than editing `.claude/commands/` or `.agents/skills/` directly.
diff --git a/THIRD-PARTY/README.md b/THIRD-PARTY/README.md
deleted file mode 100644
index 7837e6d..0000000
--- a/THIRD-PARTY/README.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# Third-party notices
-
-This repo redistributes adapted copies and verbatim snapshots of upstream work. Each upstream's
-license is preserved here; per-skill provenance (`upstream-*` frontmatter) records the exact
-source path and pinned commit. The human-readable origin map is
-[shared/skills/README.md](../shared/skills/README.md).
-
-| Upstream | License | Pinned commit | Where used in this repo |
-|---|---|---|---|
-| [mattpocock/skills](https://github.com/mattpocock/skills) | [MIT](mattpocock-skills.LICENSE) | `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb` | Adapted skills under `shared/skills/` (tdd, prototype, caveman, grill-me, handoff, write-a-skill); verbatim snapshots under `.scratch/import-upstream-skills/artifacts/` and `.scratch/claude-code-skill-adaptation/artifacts/` |
-| [bradautomates/claude-video](https://github.com/bradautomates/claude-video) | [MIT](bradautomates-claude-video.LICENSE) | `c333c2289e57bf040b32846f18d669e3f8edad9b` | Verbatim snapshot under `.scratch/add-watch-skill/artifacts/watch/` (not yet adapted) |
-
-When vendoring a new upstream, add its license file here (`<owner>-<repo>.LICENSE`) and a row to
-this table in the same commit that lands the vendored content.
diff --git a/THIRD-PARTY/bradautomates-claude-video.LICENSE b/THIRD-PARTY/bradautomates-claude-video.LICENSE
deleted file mode 100644
index e23e30f..0000000
--- a/THIRD-PARTY/bradautomates-claude-video.LICENSE
+++ /dev/null
@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Bradley Bonanno
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
diff --git a/THIRD-PARTY/mattpocock-skills.LICENSE b/THIRD-PARTY/mattpocock-skills.LICENSE
deleted file mode 100644
index f1dd2c0..0000000
--- a/THIRD-PARTY/mattpocock-skills.LICENSE
+++ /dev/null
@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Matt Pocock
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
diff --git a/VSCode_Extsion/adoc-preview-menu-1.0.0/extension.js b/VSCode_Extension/adoc-preview-menu-1.0.0/extension.js
similarity index 100%
rename from VSCode_Extsion/adoc-preview-menu-1.0.0/extension.js
rename to VSCode_Extension/adoc-preview-menu-1.0.0/extension.js
diff --git a/VSCode_Extsion/adoc-preview-menu-1.0.0/package.json b/VSCode_Extension/adoc-preview-menu-1.0.0/package.json
similarity index 100%
rename from VSCode_Extsion/adoc-preview-menu-1.0.0/package.json
rename to VSCode_Extension/adoc-preview-menu-1.0.0/package.json
diff --git a/ai-artifacts/agents/README.md b/ai-artifacts/agents/README.md
new file mode 100644
index 0000000..5fc2376
--- /dev/null
+++ b/ai-artifacts/agents/README.md
@@ -0,0 +1,5 @@
+# Agents
+
+Agent and subagent definitions plus any durable support material they need.
+
+Use `ai-artifacts/agents/shared/`, `ai-artifacts/agents/<vendor>/`, or `ai-artifacts/agents/<vendor>/<harness>/`.
diff --git a/ai-artifacts/hooks/README.md b/ai-artifacts/hooks/README.md
new file mode 100644
index 0000000..6ce7c45
--- /dev/null
+++ b/ai-artifacts/hooks/README.md
@@ -0,0 +1,6 @@
+# Hooks
+
+Source-controlled hook definitions for AI harnesses.
+
+Use `ai-artifacts/hooks/shared/`, `ai-artifacts/hooks/<vendor>/`, or `ai-artifacts/hooks/<vendor>/<harness>/` when a hook artifact itself
+belongs in the repo. Hook-related skills remain under `ai-artifacts/skills/`.
diff --git a/ai-artifacts/instructions/README.md b/ai-artifacts/instructions/README.md
new file mode 100644
index 0000000..3f23b8d
--- /dev/null
+++ b/ai-artifacts/instructions/README.md
@@ -0,0 +1,26 @@
+# Instructions
+
+Harness-specific instruction files, keyed as `ai-artifacts/instructions/<vendor>/<harness>/` (matching
+`docs/harnesses/`). Each file here is the **repo copy for editing** — the live version lives in that
+harness's own location. These are **not interchangeable**: different harnesses read different files,
+and overlap between them is expected, not duplication to be merged.
+
+This folder is intentionally broader than the old name suggested: it holds claude.ai profile
+instructions, project instructions, global `CLAUDE.md` copies, Copilot/Codex instruction surfaces,
+and equivalent base instruction documents for other AI agents.
+
+Current tracked file:
+
+- `anthropic/claude-ai/profile.md` (claude.ai Chat tab). Live location: Settings → Instructions for Claude.
+
+## Not the same file (common confusion)
+
+Owned by [docs/repo-layout.adoc](../../docs/repo-layout.adoc) ("Not the same file" section) — not
+restated here. Note: earlier versions placed the future Claude Code `CLAUDE.md` repo copy under
+`ai-artifacts/instructions/claude-code/` or `ai-artifacts/instructions/anthropic/claude-code/`; the canonical artifact-first
+location is now `ai-artifacts/instructions/anthropic/claude-code/CLAUDE.md`.
+
+See `docs/harnesses/<harness>.md` for each harness's instruction surfaces and load model.
+
+> Remaining instructions-taxonomy questions (which shared content is hoisted into `AGENTS.md`) are
+> owned by `.scratch/incorporate-global-claude-setup/` (repo-scaffold itself is done).
diff --git a/anthropic/claude-ai/instructions/profile.md b/ai-artifacts/instructions/anthropic/claude-ai/profile.md
similarity index 99%
rename from anthropic/claude-ai/instructions/profile.md
rename to ai-artifacts/instructions/anthropic/claude-ai/profile.md
index 3e96f05..e856a33 100644
--- a/anthropic/claude-ai/instructions/profile.md
+++ b/ai-artifacts/instructions/anthropic/claude-ai/profile.md
@@ -4,6 +4,7 @@ Behavioral guidelines to reduce common LLM pitfalls.
 **Tradeoff:** Caution over speed. For trivial asks, scale down effort — not the rules.
 
 ## 1. Treat Input as Unverified
+
 **Don't assume assertions are correct. Flag wrong claims explicitly — no softening, no silent fix.**
 
 - If the input is wrong, say so. Don't absorb guesses as fact.
@@ -12,6 +13,7 @@ Behavioral guidelines to reduce common LLM pitfalls.
 - If given a hypothetical, engage with it but correct the premise: "Following your assumption the answer is …; that said, this is incorrect because …, so the correct answer should be …"
 
 ## 2. Response Hygiene
+
 **Cut the preamble: no acknowledgment, no meta, no restating my point.**
 
 - Skip acknowledgment, agreement, and self-narration — not "You're right, that fails because …", just the corrected answer.
@@ -20,6 +22,7 @@ Behavioral guidelines to reduce common LLM pitfalls.
 - Match format to payload: if a table/list carries it, don't wrap it in prose.
 
 ## 3. Think Before Answering
+
 **Don't assume. Don't hide uncertainty. Surface tradeoffs.**
 
 When a request arrives:
@@ -30,6 +33,7 @@ When a request arrives:
 - If something is unclear or missing, STOP — name what's needed and ask a focused question.
 
 ## 4. Precision Over Coverage
+
 **Answer what was asked. No uninvited adjacent topics.**
 
 - Stay on the specific question — asked about X, answer X, not the related Y you could also cover.
@@ -37,6 +41,7 @@ When a request arrives:
 - Worthwhile adjacent points go at the end, briefly — never lead with them.
 
 ## 5. Concise, Layered Answers
+
 **Answer first. Minimum that fully answers. Depth on request.**
 
 - Lead with the direct answer. Add context only if required to act, or if asked why.
@@ -45,6 +50,7 @@ When a request arrives:
 - Evaluate before sending: did I stop at the layer that answers? Did I shorten without losing meaning?
 
 ## 6. Honest & Direct
+
 **Say what you actually think. Flag uncertainty clearly.**
 
 - If unsure, say so. Don't give a plausible-sounding but constructed answer.
@@ -53,6 +59,7 @@ When a request arrives:
 - Separate facts, opinions, uncertainty.
 
 ## 7. How To Ask Clarifying Questions
+
 **Never ask cold when options require domain knowledge.**
 
 - Default to acting on low-risk, easily-reversible changes; ask first only when a change is hard to verify or costly to undo.
@@ -64,6 +71,7 @@ For non-obvious answers (skip for simple choices):
 3. Then ask for confirmation — not open-ended.
 
 ## 8. General Code Guidance
+
 **Minimum code, maximum rigor, no silent failure.**
 
 - Use the minimum code required to solve the problem.
@@ -75,6 +83,7 @@ For non-obvious answers (skip for simple choices):
 - Separate output from logging: don't mix stdout and stderr unless explicitly required; use appropriate log levels / status streams.
 
 ## 9. Surface Conventions Are Mine
+
 **Match source surface style; propose changes, don't silently apply them.**
 
 - Mirror punctuation, unicode, emoji, and formatting already in my message or the file being edited — e.g. if I write " - " and "...", don't swap them for "—" and "…". Don't normalize or "improve" it.
diff --git a/ai-artifacts/mcp-config/README.md b/ai-artifacts/mcp-config/README.md
new file mode 100644
index 0000000..67a8bbf
--- /dev/null
+++ b/ai-artifacts/mcp-config/README.md
@@ -0,0 +1,5 @@
+# MCP Config
+
+Source-controlled MCP server manifests, connection definitions, and adjacent support files.
+
+Use `ai-artifacts/mcp-config/shared/`, `ai-artifacts/mcp-config/<vendor>/`, or `ai-artifacts/mcp-config/<vendor>/<harness>/`.
diff --git a/ai-artifacts/output-styles/README.md b/ai-artifacts/output-styles/README.md
new file mode 100644
index 0000000..876ec31
--- /dev/null
+++ b/ai-artifacts/output-styles/README.md
@@ -0,0 +1,5 @@
+# Output Styles
+
+Reusable output-format and response-style assets that shape model output.
+
+Use `ai-artifacts/output-styles/shared/`, `ai-artifacts/output-styles/<vendor>/`, or `ai-artifacts/output-styles/<vendor>/<harness>/`.
diff --git a/ai-artifacts/plugins/README.md b/ai-artifacts/plugins/README.md
new file mode 100644
index 0000000..268ff0d
--- /dev/null
+++ b/ai-artifacts/plugins/README.md
@@ -0,0 +1,6 @@
+# Plugins
+
+Plugin packaging, manifests, and durable support material.
+
+Use `ai-artifacts/plugins/shared/`, `ai-artifacts/plugins/<vendor>/`, or
+`ai-artifacts/plugins/<vendor>/<harness>/`.
diff --git a/ai-artifacts/prompts/README.md b/ai-artifacts/prompts/README.md
new file mode 100644
index 0000000..ed6f3c2
--- /dev/null
+++ b/ai-artifacts/prompts/README.md
@@ -0,0 +1,5 @@
+# Prompts
+
+Reusable prompts and prompt packs that are not instruction surfaces.
+
+Use `ai-artifacts/prompts/shared/`, `ai-artifacts/prompts/<vendor>/`, or `ai-artifacts/prompts/<vendor>/<harness>/`.
diff --git a/shared/skills/README.md b/ai-artifacts/skills/shared/README.md
similarity index 86%
rename from shared/skills/README.md
rename to ai-artifacts/skills/shared/README.md
index 7a0284a..13e1ca1 100644
--- a/shared/skills/README.md
+++ b/ai-artifacts/skills/shared/README.md
@@ -6,26 +6,27 @@ the `/setup:check-skill-updates` skill, and anything about that process lives in
 
 ## Layout
 
-`shared/skills/<group>/<name>/SKILL.md` (+ bundled runtime resources) is the **single source of
-truth** for skill behavior. `shared/skills/<group>/<name>/METADATA.md` is the OKF-style catalog and
+`ai-artifacts/skills/shared/<group>/<name>/SKILL.md` (+ bundled runtime resources) is the **single source of
+truth** for skill behavior. `ai-artifacts/skills/shared/<group>/<name>/METADATA.md` is the OKF-style catalog and
 provenance file for that skill. The invocable copies under generated harness mirrors are build
 artifacts — never edit them; edit the source and re-run:
 
 ```powershell
-pwsh scripts/sync-skills.ps1
+pwsh scripts/setup-repo.ps1 -SkipHooks
 ```
 
 That updates every supported generated skill mirror. `METADATA.md` files are source catalog files and
 are not deployed as runtime skill resources:
 
 - Claude Code: `.claude/commands/<group>/<name>.md` plus resources
-- Codex: `.agents/skills/<group>-<name>/SKILL.md` plus resources
+- Codex: `.agents/skills/<group>_<name>/SKILL.md` plus resources
+- Copilot: `.github/skills/<group>_<name>/SKILL.md` plus resources
 
-Both generated trees are gitignored; never edit either directly. Use
-`pwsh scripts/sync-skills.ps1 -Target Claude` or `-Target Codex` only when you intentionally want a
+All generated trees are gitignored; never edit them directly. Use
+`pwsh scripts/setup-repo.ps1 -SkipHooks -Target Claude`, `-Target Codex`, or `-Target Copilot` only when you intentionally want a
 single mirror.
 
-Namespacing follows the directory: `shared/skills/coding/tdd/` → `/coding:tdd`.
+Namespacing follows the directory: `ai-artifacts/skills/shared/coding/tdd/` → `/coding:tdd`.
 
 | Group       | Intent                                                            |
 | ----------- | ----------------------------------------------------------------- |
@@ -33,6 +34,7 @@ Namespacing follows the directory: `shared/skills/coding/tdd/` → `/coding:tdd`
 | `planning`  | Backlog / PRD / issue workflow (the `.scratch/` tracker)          |
 | `session`   | Conversational / process skills that shape a working session      |
 | `setup`     | Repo tooling and skill maintenance                                |
+| `workflow`  | Running deterministic local workflow/CI-equivalent sequences      |
 | `documents` | Producing / converting documents (e.g. email → AsciiDoc/Markdown) |
 
 ## Skill Metadata
@@ -76,8 +78,10 @@ table is the human-readable summary.
 | `recon`                         | session   | — (local original)                                            | No upstream                                                                                                                                                                          |
 | `check-skill-updates`           | setup     | — (local original)                                            | No upstream; the update tool itself                                                                                                                                                  |
 | `import-upstream-skill`         | setup     | — (local original)                                            | No upstream; the generic import process itself                                                                                                                                       |
+| `setup-repo`                    | setup     | — (local original)                                            | Self-contained bootstrap skill for clone setup (hooks + mirror generation in one command)                                                                                            |
 | `git-guardrails`                | setup     | mattpocock `skills/misc/git-guardrails-claude-code`           | Localized from the global-prior (pwsh + bash guards); Claude-Code-hook skill, N/A in chat. Exact upstream checkpoint lives only in the skill's `METADATA.md`                         |
 | `setup-pre-commit`              | setup     | mattpocock `skills/misc/setup-pre-commit` (**local fork**)    | Diverged entirely: `pre-commit` framework for PS/MD/AsciiDoc/SQL, not Husky/lint-staged/Prettier. Carries **no** `upstream-*` (lineage in a comment); `check-skill-updates` skips it |
+| `simulate-workflows`            | workflow  | — (local original)                                            | Deterministic script that runs local CI-equivalent workflow checks (Python, PowerShell, linting)                                                                                     |
 | `scratch`                       | planning  | — (local original)                                            | The `.scratch/` tracker; owns `LAYOUT.md` / `RANKING.md`                                                                                                                             |
 | `scratch-plan`                  | planning  | — (local original)                                            | Backlog ranking companion to `scratch`                                                                                                                                               |
 | `mail-to-adoc`                  | documents | — (local original)                                            | `.msg`/`.eml` → AsciiDoc; personal-workflow tool (redacted). Rename to `mail-to-doc` + Markdown target is `.scratch/mail-to-doc` issue 03                                            |
diff --git a/shared/skills/coding/diagnose/METADATA.md b/ai-artifacts/skills/shared/coding/diagnose/METADATA.md
similarity index 95%
rename from shared/skills/coding/diagnose/METADATA.md
rename to ai-artifacts/skills/shared/coding/diagnose/METADATA.md
index 64bcb75..4ab7fe4 100644
--- a/shared/skills/coding/diagnose/METADATA.md
+++ b/ai-artifacts/skills/shared/coding/diagnose/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/engineering/diagnose/SKILL.md
 upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `coding`
@@ -19,6 +19,6 @@ upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 - Reconciled commit: `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb`
 - Notes: Dual-mode capability contract; HITL loop ships pwsh (primary) and bash templates.
 
-# Citations
+## Citations
 
-[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
\ No newline at end of file
+[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/coding/diagnose/SKILL.md b/ai-artifacts/skills/shared/coding/diagnose/SKILL.md
similarity index 96%
rename from shared/skills/coding/diagnose/SKILL.md
rename to ai-artifacts/skills/shared/coding/diagnose/SKILL.md
index 8f6de63..e0b2129 100644
--- a/shared/skills/coding/diagnose/SKILL.md
+++ b/ai-artifacts/skills/shared/coding/diagnose/SKILL.md
@@ -43,8 +43,8 @@ Spend disproportionate effort here. **Be aggressive. Be creative. Refuse to give
 7. **Property / fuzz loop.** If the bug is "sometimes wrong output", run 1000 random inputs and look for the failure mode.
 8. **Bisection harness.** If the bug appeared between two known states (commit, dataset, version), automate "boot at state X, check, repeat" so you can `git bisect run` it.
 9. **Differential loop.** Run the same input through old-version vs new-version (or two configs) and diff outputs.
-10. **HITL script.** Last resort. If a human must click, drive _them_ with a structured loop —
-    `scripts/hitl-loop.template.ps1` (pwsh, primary) or `scripts/hitl-loop.template.sh` (bash). With a
+10. **HITL script.** Last resort. If a human must click, drive *them* with a structured loop —
+    `templates/hitl-loop.template.ps1` (pwsh, primary) or `templates/hitl-loop.template.sh` (bash). With a
     shell, generate and run it; without one, hand the user the same numbered steps in chat and collect
     their answers. Captured output feeds back to you.
 
@@ -52,7 +52,7 @@ Build the right feedback loop, and the bug is 90% fixed.
 
 ### Iterate on the loop itself
 
-Treat the loop as a product. Once you have _a_ loop, ask:
+Treat the loop as a product. Once you have *a* loop, ask:
 
 - Can I make it faster? (Cache setup, skip unrelated init, narrow the test scope.)
 - Can I make the signal sharper? (Assert on the specific symptom, not "didn't crash".)
diff --git a/shared/skills/coding/diagnose/scripts/hitl-loop.template.ps1 b/ai-artifacts/skills/shared/coding/diagnose/templates/hitl-loop.template.ps1
similarity index 94%
rename from shared/skills/coding/diagnose/scripts/hitl-loop.template.ps1
rename to ai-artifacts/skills/shared/coding/diagnose/templates/hitl-loop.template.ps1
index b66e9ce..c577531 100644
--- a/shared/skills/coding/diagnose/scripts/hitl-loop.template.ps1
+++ b/ai-artifacts/skills/shared/coding/diagnose/templates/hitl-loop.template.ps1
@@ -1,3 +1,7 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
 # Human-in-the-loop reproduction loop (PowerShell 7 primary; pwsh on Windows/macOS/Linux).
 # Copy this file, edit the steps below, and run it:  pwsh hitl-loop.template.ps1
 # The agent runs the script; the user follows prompts in their terminal.
diff --git a/shared/skills/coding/diagnose/scripts/hitl-loop.template.sh b/ai-artifacts/skills/shared/coding/diagnose/templates/hitl-loop.template.sh
similarity index 100%
rename from shared/skills/coding/diagnose/scripts/hitl-loop.template.sh
rename to ai-artifacts/skills/shared/coding/diagnose/templates/hitl-loop.template.sh
diff --git a/shared/skills/coding/improve-codebase-architecture/METADATA.md b/ai-artifacts/skills/shared/coding/improve-codebase-architecture/METADATA.md
similarity index 95%
rename from shared/skills/coding/improve-codebase-architecture/METADATA.md
rename to ai-artifacts/skills/shared/coding/improve-codebase-architecture/METADATA.md
index beb1ab4..9c66f77 100644
--- a/shared/skills/coding/improve-codebase-architecture/METADATA.md
+++ b/ai-artifacts/skills/shared/coding/improve-codebase-architecture/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/engineering/improve-codebase-architecture/SKILL.md
 upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `coding`
@@ -19,6 +19,6 @@ upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 - Reconciled commit: `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb`
 - Notes: Dual-mode report workflow; grill-with-docs links repointed to session/grill-me.
 
-# Citations
+## Citations
 
-[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
\ No newline at end of file
+[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/coding/improve-codebase-architecture/SKILL.md b/ai-artifacts/skills/shared/coding/improve-codebase-architecture/SKILL.md
similarity index 87%
rename from shared/skills/coding/improve-codebase-architecture/SKILL.md
rename to ai-artifacts/skills/shared/coding/improve-codebase-architecture/SKILL.md
index cb4d800..31bb000 100644
--- a/shared/skills/coding/improve-codebase-architecture/SKILL.md
+++ b/ai-artifacts/skills/shared/coding/improve-codebase-architecture/SKILL.md
@@ -22,7 +22,7 @@ The analysis is identical; only how you gather code and deliver the report chang
 
 ## Glossary
 
-Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md).
+Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](docs/LANGUAGE.md).
 
 - **Module** — anything with an interface and an implementation (function, class, package, slice).
 - **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
@@ -33,13 +33,13 @@ Use these terms exactly in every suggestion. Consistent language is the point 
 - **Leverage** — what callers get from depth.
 - **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place.
 
-Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
+Key principles (see [LANGUAGE.md](docs/LANGUAGE.md) for the full list):
 
 - **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
 - **The interface is the test surface.**
 - **One adapter = hypothetical seam. Two adapters = real seam.**
 
-This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
+This skill is *informed* by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
 
 ## Process
 
@@ -81,11 +81,11 @@ For each candidate, render a card with:
 
 End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
 
-**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+**Use CONTEXT.md vocabulary for the domain, and [LANGUAGE.md](docs/LANGUAGE.md) vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
 
-**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: *"contradicts ADR-0007 — but worth reopening because…"*). Don't list every theoretical refactor an ADR forbids.
 
-See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+See [HTML-REPORT.md](docs/HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
 
 Do NOT propose interfaces yet. After the report is delivered, ask the user: "Which of these would you like to explore?"
 
@@ -95,7 +95,7 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des
 
 Side effects happen inline as decisions crystallize (with a filesystem: edit the files; without one: propose the exact text to add):
 
-- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/session:grill-me` (see [CONTEXT-FORMAT.md](../../session/grill-me/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md` — same discipline as `/session:grill-me` (see [CONTEXT-FORMAT.md](../../session/grill-me/docs/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist.
 - **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
-- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../../session/grill-me/ADR-FORMAT.md).
-- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md).
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: *"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"* Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones. See [ADR-FORMAT.md](../../session/grill-me/docs/ADR-FORMAT.md).
+- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](docs/INTERFACE-DESIGN.md).
diff --git a/shared/skills/coding/improve-codebase-architecture/DEEPENING.md b/ai-artifacts/skills/shared/coding/improve-codebase-architecture/docs/DEEPENING.md
similarity index 100%
rename from shared/skills/coding/improve-codebase-architecture/DEEPENING.md
rename to ai-artifacts/skills/shared/coding/improve-codebase-architecture/docs/DEEPENING.md
diff --git a/shared/skills/coding/improve-codebase-architecture/HTML-REPORT.md b/ai-artifacts/skills/shared/coding/improve-codebase-architecture/docs/HTML-REPORT.md
similarity index 100%
rename from shared/skills/coding/improve-codebase-architecture/HTML-REPORT.md
rename to ai-artifacts/skills/shared/coding/improve-codebase-architecture/docs/HTML-REPORT.md
diff --git a/shared/skills/coding/improve-codebase-architecture/INTERFACE-DESIGN.md b/ai-artifacts/skills/shared/coding/improve-codebase-architecture/docs/INTERFACE-DESIGN.md
similarity index 100%
rename from shared/skills/coding/improve-codebase-architecture/INTERFACE-DESIGN.md
rename to ai-artifacts/skills/shared/coding/improve-codebase-architecture/docs/INTERFACE-DESIGN.md
diff --git a/shared/skills/coding/improve-codebase-architecture/LANGUAGE.md b/ai-artifacts/skills/shared/coding/improve-codebase-architecture/docs/LANGUAGE.md
similarity index 94%
rename from shared/skills/coding/improve-codebase-architecture/LANGUAGE.md
rename to ai-artifacts/skills/shared/coding/improve-codebase-architecture/docs/LANGUAGE.md
index 530c276..de64f8b 100644
--- a/shared/skills/coding/improve-codebase-architecture/LANGUAGE.md
+++ b/ai-artifacts/skills/shared/coding/improve-codebase-architecture/docs/LANGUAGE.md
@@ -6,11 +6,11 @@ Shared vocabulary for every suggestion this skill makes. Use these terms exactly
 
 **Module**
 Anything with an interface and an implementation. Deliberately scale-agnostic — applies equally to a function, class, package, or tier-spanning slice.
-_Avoid_: unit, component, service.
+*Avoid*: unit, component, service.
 
 **Interface**
 Everything a caller must know to use the module correctly. Includes the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
-_Avoid_: API, signature (too narrow — those refer only to the type-level surface).
+*Avoid*: API, signature (too narrow — those refer only to the type-level surface).
 
 **Implementation**
 What's inside a module — its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
@@ -18,9 +18,9 @@ What's inside a module — its body of code. Distinct from **Adapter**: a thing
 **Depth**
 Leverage at the interface — the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface. A module is **shallow** when the interface is nearly as complex as the implementation.
 
-**Seam** _(from Michael Feathers)_
+**Seam** *(from Michael Feathers)*
 A place where you can alter behaviour without editing in that place. The *location* at which a module's interface lives. Choosing where to put the seam is its own design decision, distinct from what goes behind it.
-_Avoid_: boundary (overloaded with DDD's bounded context).
+*Avoid*: boundary (overloaded with DDD's bounded context).
 
 **Adapter**
 A concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
diff --git a/shared/skills/coding/prototype/METADATA.md b/ai-artifacts/skills/shared/coding/prototype/METADATA.md
similarity index 96%
rename from shared/skills/coding/prototype/METADATA.md
rename to ai-artifacts/skills/shared/coding/prototype/METADATA.md
index 027d232..7ebbc1a 100644
--- a/shared/skills/coding/prototype/METADATA.md
+++ b/ai-artifacts/skills/shared/coding/prototype/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/engineering/prototype/SKILL.md
 upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `coding`
@@ -19,6 +19,6 @@ upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 - Reconciled commit: `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb`
 - Notes: Localized.
 
-# Citations
+## Citations
 
-[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
\ No newline at end of file
+[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/coding/prototype/SKILL.md b/ai-artifacts/skills/shared/coding/prototype/SKILL.md
similarity index 97%
rename from shared/skills/coding/prototype/SKILL.md
rename to ai-artifacts/skills/shared/coding/prototype/SKILL.md
index a44af08..0569169 100644
--- a/shared/skills/coding/prototype/SKILL.md
+++ b/ai-artifacts/skills/shared/coding/prototype/SKILL.md
@@ -1,8 +1,8 @@
----
-name: prototype
-version: 1.0.0
-description: Build a throwaway prototype to flesh out a design before committing to it. Build a tiny interactive terminal app that drives a state model, data shape, command surface, or output format by hand — pushing it through cases that are hard to reason about on paper. Use when the user wants to prototype, sanity-check a data model or state machine, feel out an API/cmdlet surface or SQL schema, explore an idea, or says "prototype this", "let me play with it", "does this shape feel right".
----
+---
+name: prototype
+version: 1.0.0
+description: Build a throwaway prototype to flesh out a design before committing to it. Build a tiny interactive terminal app that drives a state model, data shape, command surface, or output format by hand — pushing it through cases that are hard to reason about on paper. Use when the user wants to prototype, sanity-check a data model or state machine, feel out an API/cmdlet surface or SQL schema, explore an idea, or says "prototype this", "let me play with it", "does this shape feel right".
+---
 
 # Prototype
 
@@ -22,7 +22,7 @@ Typical questions it answers:
 
 1. **Throwaway from day one, and marked as such.** Put it next to the module it's prototyping for so context is obvious, but name it so a casual reader sees it's a prototype, not production (`proto-<thing>.ps1`, `Proto<Thing>/`, `proto_<thing>.py`).
 2. **One command to run.** Via the project's existing task runner or a single documented invocation — `pwsh ./proto-<thing>.ps1`, `dotnet run --project Proto<Thing>`, `python proto_<thing>.py`. The user starts it without thinking. Don't add a new runtime or package manager just for the prototype.
-3. **No persistence by default.** State lives in memory. Persistence is usually the thing being _checked_, not depended on. If the question is specifically about persistence, hit a scratch target with an obvious throwaway name (`tempdb` table `Proto_WipeMe`, a `proto-wipe-me.db`), never a real one.
+3. **No persistence by default.** State lives in memory. Persistence is usually the thing being *checked*, not depended on. If the question is specifically about persistence, hit a scratch target with an obvious throwaway name (`tempdb` table `Proto_WipeMe`, a `proto-wipe-me.db`), never a real one.
 4. **Skip the polish.** No tests, no abstractions, no error handling beyond what makes it runnable. The point is to learn fast and delete.
 5. **Surface the state.** Re-render the full relevant state after every action so the user sees exactly what changed.
 6. **Delete or absorb when done.** Once it has answered its question, fold the validated decision into the real code or delete it — don't leave it rotting in the repo.
@@ -75,7 +75,7 @@ Add it to the project's existing task runner if there is one (`*.psd1`/build scr
 
 ### 6. Hand it over
 
-Give the run command. The user drives it; the valuable moments are "wait, that shouldn't be possible" or "huh, I assumed X would differ" — those are bugs in the _idea_, which is the whole point. If they want new actions, add them. Prototypes evolve.
+Give the run command. The user drives it; the valuable moments are "wait, that shouldn't be possible" or "huh, I assumed X would differ" — those are bugs in the *idea*, which is the whole point. If they want new actions, add them. Prototypes evolve.
 
 ### 7. Capture the answer
 
diff --git a/shared/skills/coding/tdd/METADATA.md b/ai-artifacts/skills/shared/coding/tdd/METADATA.md
similarity index 96%
rename from shared/skills/coding/tdd/METADATA.md
rename to ai-artifacts/skills/shared/coding/tdd/METADATA.md
index 1833bd0..b34ac8b 100644
--- a/shared/skills/coding/tdd/METADATA.md
+++ b/ai-artifacts/skills/shared/coding/tdd/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/engineering/tdd/SKILL.md
 upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `coding`
@@ -19,6 +19,6 @@ upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 - Reconciled commit: `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb`
 - Notes: Heavily localized: stack rules (PowerShell/SQL/Python/C#), reworked resources.
 
-# Citations
+## Citations
 
-[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
\ No newline at end of file
+[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/coding/tdd/SKILL.md b/ai-artifacts/skills/shared/coding/tdd/SKILL.md
similarity index 86%
rename from shared/skills/coding/tdd/SKILL.md
rename to ai-artifacts/skills/shared/coding/tdd/SKILL.md
index 19d8bb9..8be4104 100644
--- a/shared/skills/coding/tdd/SKILL.md
+++ b/ai-artifacts/skills/shared/coding/tdd/SKILL.md
@@ -3,86 +3,86 @@ name: tdd
 version: 1.0.0
 description: Test-driven development applied as a workflow across unit, integration, and acceptance levels, with on-demand stack-specific rules for PowerShell, SQL, Python, and C#. Use when building features or fixing bugs test-first, when writing or reviewing tests, when choosing test doubles, when picking a companion technique (property-based, mutation, contract, approval, snapshot testing), or when the user mentions TDD, red-green-refactor, BDD, acceptance tests, or mocking.
 ---
-
-# Test-Driven Development
-
-These are my operating rules for test and development work. Apply them; do
-not restate them back to me; do not soften them. When a request of mine
-conflicts with a rule, say so and ask before proceeding rather than
-silently complying.
-
-## Core Frame
-
-- Tests do three jobs: **verification**, **design feedback**, **specification**.
-  Identify which job applies before suggesting a test approach.
-- TDD's primary value is design feedback and incremental progress.
-  Verification is a side effect. Do not pitch TDD as "a way to find bugs."
-- BDD is TDD with behavior-focused vocabulary and an outside-in perspective.
-  It is not a separate methodology and not defined by Gherkin/Cucumber.
-- TDD is a **workflow** (write failing test → pass → refactor), not a scope.
-  It applies at unit, integration, acceptance, and E2E levels. Do not equate
-  TDD with unit testing, and do not reject it because something cannot be
-  unit-tested.
-- A test must **fail on behavior change and pass on structure change.** If a
-  proposed test would break on a legitimate refactor, reject it and propose a
-  behavior-level alternative.
-
-## Workflow
-
-### 1. Plan
-
-- Confirm what interface changes are needed and which behaviors matter most.
-  I cannot test everything — focus on critical paths and complex logic.
-- List behaviors to test (not implementation steps).
-- Design interfaces for testability — see [design-for-testability.md](design-for-testability.md).
-- Use the project's domain vocabulary for test names; respect existing ADRs
-  and the existing test suite's style.
-- **Load the stack file for the language in play, and only that one:**
-  [PowerShell](stacks/powershell.md) · [SQL](stacks/sql.md) ·
-  [Python](stacks/python.md) · [C#](stacks/csharp.md). Do not read stack files
-  for languages not in use.
-- Get my approval on the plan before writing code.
-
-### 2. Tracer bullet
-
-Write ONE test that confirms ONE thing end-to-end. Red → green. This proves
-the path works before you build on it.
-
-### 3. Incremental loop
-
-For each remaining behavior: red → green, one test at a time, minimal code,
-no anticipation of future tests. **Drive vertical, not horizontal** — one
-test, one implementation, learn, then the next test. Never write all tests
-first then all code (see [reviewing-and-cycle.md](reviewing-and-cycle.md)).
-
-### 4. Refactor
-
-Only once green (never while red). Look for: duplication, long methods,
-shallow modules to deepen, logic that belongs where its data lives, and what
-the new code reveals about existing code. Run tests after each step.
-Refactor is non-optional — skipping it degrades TDD into "tests plus mess."
-
-## Per-Cycle Checklist
-
-```
-[ ] Test describes behavior, not implementation
-[ ] Test uses the public interface only
-[ ] Test would survive an internal refactor
-[ ] Red was a real assertion failure, not just a compile error
-[ ] Code is minimal for this test; no speculative features
-[ ] Structural and behavioral changes are not mixed in one step
-```
-
-## Reference Files (load as needed)
-
-- [reviewing-and-cycle.md](reviewing-and-cycle.md) — rules for writing/reviewing
-  tests and the red-green-refactor cycle (strategies, what counts as red).
-- [test-doubles.md](test-doubles.md) — mock/stub/fake selection, mock at
-  boundaries, third-party wrapping, classicist vs London.
-- [companions.md](companions.md) — when to suggest property-based, mutation,
-  contract, approval, snapshot, and integration testing.
-- [behaviors.md](behaviors.md) — what not to do, how to handle ambiguous
-  requests, and output format when producing tests.
-- [design-for-testability.md](design-for-testability.md) — interface design
-  that makes tests natural.
-- `stacks/<language>.md` — stack-specific rules; load only the one in use.
+
+# Test-Driven Development
+
+These are my operating rules for test and development work. Apply them; do
+not restate them back to me; do not soften them. When a request of mine
+conflicts with a rule, say so and ask before proceeding rather than
+silently complying.
+
+## Core Frame
+
+- Tests do three jobs: **verification**, **design feedback**, **specification**.
+  Identify which job applies before suggesting a test approach.
+- TDD's primary value is design feedback and incremental progress.
+  Verification is a side effect. Do not pitch TDD as "a way to find bugs."
+- BDD is TDD with behavior-focused vocabulary and an outside-in perspective.
+  It is not a separate methodology and not defined by Gherkin/Cucumber.
+- TDD is a **workflow** (write failing test → pass → refactor), not a scope.
+  It applies at unit, integration, acceptance, and E2E levels. Do not equate
+  TDD with unit testing, and do not reject it because something cannot be
+  unit-tested.
+- A test must **fail on behavior change and pass on structure change.** If a
+  proposed test would break on a legitimate refactor, reject it and propose a
+  behavior-level alternative.
+
+## Workflow
+
+### 1. Plan
+
+- Confirm what interface changes are needed and which behaviors matter most.
+  I cannot test everything — focus on critical paths and complex logic.
+- List behaviors to test (not implementation steps).
+- Design interfaces for testability — see [design-for-testability.md](docs/design-for-testability.md).
+- Use the project's domain vocabulary for test names; respect existing ADRs
+  and the existing test suite's style.
+- **Load the stack file for the language in play, and only that one:**
+  [PowerShell](stacks/powershell.md) · [SQL](stacks/sql.md) ·
+  [Python](stacks/python.md) · [C#](stacks/csharp.md). Do not read stack files
+  for languages not in use.
+- Get my approval on the plan before writing code.
+
+### 2. Tracer bullet
+
+Write ONE test that confirms ONE thing end-to-end. Red → green. This proves
+the path works before you build on it.
+
+### 3. Incremental loop
+
+For each remaining behavior: red → green, one test at a time, minimal code,
+no anticipation of future tests. **Drive vertical, not horizontal** — one
+test, one implementation, learn, then the next test. Never write all tests
+first then all code (see [reviewing-and-cycle.md](docs/reviewing-and-cycle.md)).
+
+### 4. Refactor
+
+Only once green (never while red). Look for: duplication, long methods,
+shallow modules to deepen, logic that belongs where its data lives, and what
+the new code reveals about existing code. Run tests after each step.
+Refactor is non-optional — skipping it degrades TDD into "tests plus mess."
+
+## Per-Cycle Checklist
+
+```text
+[ ] Test describes behavior, not implementation
+[ ] Test uses the public interface only
+[ ] Test would survive an internal refactor
+[ ] Red was a real assertion failure, not just a compile error
+[ ] Code is minimal for this test; no speculative features
+[ ] Structural and behavioral changes are not mixed in one step
+```
+
+## Reference Files (load as needed)
+
+- [reviewing-and-cycle.md](docs/reviewing-and-cycle.md) — rules for writing/reviewing
+  tests and the red-green-refactor cycle (strategies, what counts as red).
+- [test-doubles.md](docs/test-doubles.md) — mock/stub/fake selection, mock at
+  boundaries, third-party wrapping, classicist vs London.
+- [companions.md](docs/companions.md) — when to suggest property-based, mutation,
+  contract, approval, snapshot, and integration testing.
+- [behaviors.md](docs/behaviors.md) — what not to do, how to handle ambiguous
+  requests, and output format when producing tests.
+- [design-for-testability.md](docs/design-for-testability.md) — interface design
+  that makes tests natural.
+- `stacks/<language>.md` — stack-specific rules; load only the one in use.
diff --git a/shared/skills/coding/tdd/behaviors.md b/ai-artifacts/skills/shared/coding/tdd/docs/behaviors.md
similarity index 100%
rename from shared/skills/coding/tdd/behaviors.md
rename to ai-artifacts/skills/shared/coding/tdd/docs/behaviors.md
diff --git a/shared/skills/coding/tdd/companions.md b/ai-artifacts/skills/shared/coding/tdd/docs/companions.md
similarity index 100%
rename from shared/skills/coding/tdd/companions.md
rename to ai-artifacts/skills/shared/coding/tdd/docs/companions.md
diff --git a/shared/skills/coding/tdd/design-for-testability.md b/ai-artifacts/skills/shared/coding/tdd/docs/design-for-testability.md
similarity index 100%
rename from shared/skills/coding/tdd/design-for-testability.md
rename to ai-artifacts/skills/shared/coding/tdd/docs/design-for-testability.md
diff --git a/shared/skills/coding/tdd/reviewing-and-cycle.md b/ai-artifacts/skills/shared/coding/tdd/docs/reviewing-and-cycle.md
similarity index 100%
rename from shared/skills/coding/tdd/reviewing-and-cycle.md
rename to ai-artifacts/skills/shared/coding/tdd/docs/reviewing-and-cycle.md
diff --git a/shared/skills/coding/tdd/test-doubles.md b/ai-artifacts/skills/shared/coding/tdd/docs/test-doubles.md
similarity index 78%
rename from shared/skills/coding/tdd/test-doubles.md
rename to ai-artifacts/skills/shared/coding/tdd/docs/test-doubles.md
index cfe3c15..ff7d04b 100644
--- a/shared/skills/coding/tdd/test-doubles.md
+++ b/ai-artifacts/skills/shared/coding/tdd/docs/test-doubles.md
@@ -45,13 +45,13 @@
 
 ## Double Taxonomy (Meszaros)
 
-| Kind | Purpose |
-| --- | --- |
-| Dummy | Fills a parameter slot; never used. |
-| Stub | Returns canned answers. Use when the code needs specific inputs from a collaborator. |
-| Spy | A stub that records how it was called. Use when verifying an interaction occurred. |
-| Mock | A spy with pre-set expectations; fails if they are not met. Strictest. |
-| Fake | A working but production-unsuitable implementation (in-memory DB/queue). |
+| Kind  | Purpose                                                                              |
+| ----- | ------------------------------------------------------------------------------------ |
+| Dummy | Fills a parameter slot; never used.                                                  |
+| Stub  | Returns canned answers. Use when the code needs specific inputs from a collaborator. |
+| Spy   | A stub that records how it was called. Use when verifying an interaction occurred.   |
+| Mock  | A spy with pre-set expectations; fails if they are not met. Strictest.               |
+| Fake  | A working but production-unsuitable implementation (in-memory DB/queue).             |
 
 Using a mock where a stub would do creates over-specified tests that fail on
 irrelevant changes. Using a stub where a mock is needed leaves interaction bugs
diff --git a/shared/skills/coding/tdd/stacks/csharp.md b/ai-artifacts/skills/shared/coding/tdd/stacks/csharp.md
similarity index 100%
rename from shared/skills/coding/tdd/stacks/csharp.md
rename to ai-artifacts/skills/shared/coding/tdd/stacks/csharp.md
diff --git a/shared/skills/coding/tdd/stacks/powershell.md b/ai-artifacts/skills/shared/coding/tdd/stacks/powershell.md
similarity index 100%
rename from shared/skills/coding/tdd/stacks/powershell.md
rename to ai-artifacts/skills/shared/coding/tdd/stacks/powershell.md
diff --git a/shared/skills/coding/tdd/stacks/python.md b/ai-artifacts/skills/shared/coding/tdd/stacks/python.md
similarity index 100%
rename from shared/skills/coding/tdd/stacks/python.md
rename to ai-artifacts/skills/shared/coding/tdd/stacks/python.md
diff --git a/shared/skills/coding/tdd/stacks/sql.md b/ai-artifacts/skills/shared/coding/tdd/stacks/sql.md
similarity index 100%
rename from shared/skills/coding/tdd/stacks/sql.md
rename to ai-artifacts/skills/shared/coding/tdd/stacks/sql.md
diff --git a/shared/skills/coding/zoom-out/METADATA.md b/ai-artifacts/skills/shared/coding/zoom-out/METADATA.md
similarity index 94%
rename from shared/skills/coding/zoom-out/METADATA.md
rename to ai-artifacts/skills/shared/coding/zoom-out/METADATA.md
index afb7a50..b328086 100644
--- a/shared/skills/coding/zoom-out/METADATA.md
+++ b/ai-artifacts/skills/shared/coding/zoom-out/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/engineering/zoom-out/SKILL.md
 upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `coding`
@@ -19,6 +19,6 @@ upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 - Reconciled commit: `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb`
 - Notes: Prompt-only; dual-mode note added.
 
-# Citations
+## Citations
 
-[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
\ No newline at end of file
+[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/coding/zoom-out/SKILL.md b/ai-artifacts/skills/shared/coding/zoom-out/SKILL.md
similarity index 100%
rename from shared/skills/coding/zoom-out/SKILL.md
rename to ai-artifacts/skills/shared/coding/zoom-out/SKILL.md
diff --git a/shared/skills/documents/mail-to-adoc/METADATA.md b/ai-artifacts/skills/shared/documents/mail-to-adoc/METADATA.md
similarity index 85%
rename from shared/skills/documents/mail-to-adoc/METADATA.md
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/METADATA.md
index 8ea06b5..e3751e7 100644
--- a/shared/skills/documents/mail-to-adoc/METADATA.md
+++ b/ai-artifacts/skills/shared/documents/mail-to-adoc/METADATA.md
@@ -6,9 +6,9 @@ resource: ./SKILL.md
 tags: [documents, skill]
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `documents`
 - Origin: local
-- Notes: Local original; personal workflow tool. Beta maturity.
\ No newline at end of file
+- Notes: Local original; personal workflow tool. Beta maturity.
diff --git a/shared/skills/documents/mail-to-adoc/README.md b/ai-artifacts/skills/shared/documents/mail-to-adoc/README.md
similarity index 100%
rename from shared/skills/documents/mail-to-adoc/README.md
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/README.md
diff --git a/shared/skills/documents/mail-to-adoc/SKILL.md b/ai-artifacts/skills/shared/documents/mail-to-adoc/SKILL.md
similarity index 94%
rename from shared/skills/documents/mail-to-adoc/SKILL.md
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/SKILL.md
index 2d3362b..dce356a 100644
--- a/shared/skills/documents/mail-to-adoc/SKILL.md
+++ b/ai-artifacts/skills/shared/documents/mail-to-adoc/SKILL.md
@@ -34,7 +34,7 @@ pip install extract-msg
 
 Add MD5 checksums of attachments to ignore (e.g. Outlook signature images) to:
 
-```
+```text
 .github/skills/mail-to-adoc/attachment-blocklist.txt
 ```
 
@@ -53,8 +53,8 @@ python '.github/skills/mail-to-adoc/scripts/mail_to_adoc.py' '<path-to-file.eml>
 python '.github/skills/mail-to-adoc/scripts/mail_to_adoc.py' '<path>' '<output.adoc>'
 ```
 
-3. Open the generated `.adoc` file to review.
-4. The source file is automatically moved to `mails/converted/`.
+1. Open the generated `.adoc` file to review.
+2. The source file is automatically moved to `mails/converted/`.
 
 ## Notes
 
diff --git a/shared/skills/documents/mail-to-adoc/attachment-blocklist.txt b/ai-artifacts/skills/shared/documents/mail-to-adoc/attachment-blocklist.txt
similarity index 100%
rename from shared/skills/documents/mail-to-adoc/attachment-blocklist.txt
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/attachment-blocklist.txt
diff --git a/shared/skills/documents/mail-to-adoc/docs/prd/PRD.md b/ai-artifacts/skills/shared/documents/mail-to-adoc/docs/prd/PRD.md
similarity index 95%
rename from shared/skills/documents/mail-to-adoc/docs/prd/PRD.md
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/docs/prd/PRD.md
index 14f3299..7b75c4f 100644
--- a/shared/skills/documents/mail-to-adoc/docs/prd/PRD.md
+++ b/ai-artifacts/skills/shared/documents/mail-to-adoc/docs/prd/PRD.md
@@ -33,18 +33,18 @@ Email formats vary by client and encoding. .msg and .eml representations of the
 - The tool shall optionally accept an explicit output .adoc path.
 - The tool shall return a clear error for unsupported extensions.
 
-2. Output naming and placement
+1. Output naming and placement
 
 - Without explicit output path, output filename shall be auto-derived from date + source stem.
 - If source is in a raw directory, output shall be placed in the parent directory.
 
-3. Metadata extraction
+1. Metadata extraction
 
 - The output shall include mail metadata table fields where available:
   - From, Sent, To, Reply-To, CC, BCC, Importance, Sensitivity, Categories.
 - Subject shall be used as document title and colon spacing shall be escaped for AsciiDoc safety.
 
-4. Body extraction and normalization
+1. Body extraction and normalization
 
 - .msg conversion shall prefer plain text body, then HTML fallback.
 - .eml conversion shall prefer HTML body, then plain text fallback.
@@ -52,7 +52,7 @@ Email formats vary by client and encoding. .msg and .eml representations of the
 - Body normalization shall remove null bytes, NBSP artifacts, invisible unicode, repeated blank lines, and Outlook-specific noise blocks.
 - Quoted header blocks shall be prefixed with [%hardbreaks] for readability.
 
-5. Attachment processing
+1. Attachment processing
 
 - All non-inline attachments shall be inspected.
 - Attachments shall be deduplicated by MD5 checksum.
@@ -61,14 +61,14 @@ Email formats vary by client and encoding. .msg and .eml representations of the
 - Image attachments shall be rendered as image:: entries with links.
 - Other attachments shall be rendered as link: entries.
 
-6. Nested mail attachment processing
+1. Nested mail attachment processing
 
 - Attached .msg/.eml files shall not be written to docs/.
 - Attached .msg/.eml files shall be written to mails/raw/.
 - Nested mail attachments shall be converted recursively to .adoc.
 - Parent document attachment list shall link to nested conversion output when available, otherwise to raw source.
 
-7. Sibling parity conversion and comparison
+1. Sibling parity conversion and comparison
 
 - If counterpart extension exists for the same stem (foo.msg + foo.eml), both shall be converted.
 - Tool shall compare generated outputs and print:
@@ -76,7 +76,7 @@ Email formats vary by client and encoding. .msg and .eml representations of the
   - Similarity ratio when different
   - Limited unified diff preview
 
-8. Source lifecycle
+1. Source lifecycle
 
 - After successful conversion run, the primary source file shall be moved to a converted subfolder unless already inside converted.
 
diff --git a/shared/skills/documents/mail-to-adoc/docs/prd/PRD_EDGE_CASES.md b/ai-artifacts/skills/shared/documents/mail-to-adoc/docs/prd/PRD_EDGE_CASES.md
similarity index 81%
rename from shared/skills/documents/mail-to-adoc/docs/prd/PRD_EDGE_CASES.md
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/docs/prd/PRD_EDGE_CASES.md
index 9b5a76c..cbc5e17 100644
--- a/shared/skills/documents/mail-to-adoc/docs/prd/PRD_EDGE_CASES.md
+++ b/ai-artifacts/skills/shared/documents/mail-to-adoc/docs/prd/PRD_EDGE_CASES.md
@@ -12,123 +12,123 @@ Define edge-case behavior required to faithfully recreate the skill.
 
 - Expected: fail fast with explicit file-not-found error.
 
-2. Unsupported extension
+1. Unsupported extension
 
 - Expected: fail fast and print supported extensions (.msg, .eml).
 
-3. Explicit output path provided
+1. Explicit output path provided
 
 - Expected: use explicit path and skip auto-name for primary file.
 
-4. Source file already in converted folder
+1. Source file already in converted folder
 
 - Expected: do not re-move source.
 
 ### Date and Naming
 
-5. Missing or unparsable date
+1. Missing or unparsable date
 
 - Expected: output name derived from stem only, no date prefix.
 
-6. Source stem already includes date prefix
+1. Source stem already includes date prefix
 
 - Expected: avoid double-prefixing by trimming known date forms.
 
-7. Filename collisions in output dirs
+1. Filename collisions in output dirs
 
 - Expected: append numeric suffix until unique.
 
 ### Metadata Normalization
 
-8. Folded headers in .eml (RFC line wrapping)
+1. Folded headers in .eml (RFC line wrapping)
 
 - Expected: unfolded values appear as single-line fields.
 
-9. Address fields with mixed display-name/email forms
+1. Address fields with mixed display-name/email forms
 
 - Expected: parsed, normalized, sorted representation.
 
-10. More than 10 recipients in a field
+1. More than 10 recipients in a field
 
 - Expected: comma-separated single-cell rendering.
 
 ### Body Extraction and Cleanup
 
-11. .msg has empty plain text but valid HTML
+1. .msg has empty plain text but valid HTML
 
 - Expected: HTML fallback used.
 
-12. .eml has both HTML and plain text
+1. .eml has both HTML and plain text
 
 - Expected: HTML chosen.
 
-13. HTML contains style/script/comment/o:p/conditional blocks
+1. HTML contains style/script/comment/o:p/conditional blocks
 
 - Expected: removed before conversion.
 
-14. Body contains null bytes, NBSP, zero-width chars
+1. Body contains null bytes, NBSP, zero-width chars
 
 - Expected: stripped or normalized.
 
-15. Body has long runs of blank lines
+1. Body has long runs of blank lines
 
 - Expected: collapsed to stable spacing.
 
-16. Reply chain header block in body
+1. Reply chain header block in body
 
 - Expected: [%hardbreaks] inserted before each header run.
 
 ### Attachment Handling
 
-17. Inline image with filename
+1. Inline image with filename
 
 - Expected: skipped as inline artifact.
 
-18. Duplicate attachment content with different names
+1. Duplicate attachment content with different names
 
 - Expected: dedupe by checksum; link to existing stored file.
 
-19. Blocklisted attachment checksum
+1. Blocklisted attachment checksum
 
 - Expected: skipped without writing file.
 
-20. Attachment filename with directory traversal pattern
+1. Attachment filename with directory traversal pattern
 
 - Expected: sanitized to basename before writing.
 
-21. Image attachment
+1. Image attachment
 
 - Expected: rendered with image:: thumbnail and click-through link.
 
-22. Non-image attachment
+1. Non-image attachment
 
 - Expected: rendered as link: entry.
 
 ### Nested Mail Attachments
 
-23. Attached .msg or .eml present
+1. Attached .msg or .eml present
 
 - Expected: write to mails/raw, convert nested mail, link to nested .adoc.
 
-24. Nested conversion fails
+1. Nested conversion fails
 
 - Expected: warning logged; parent links to raw nested source.
 
-25. Duplicate nested mail attachment by checksum
+1. Duplicate nested mail attachment by checksum
 
 - Expected: existing raw file reused.
 
 ### Sibling Pair Comparison
 
-26. Input file has sibling counterpart extension
+1. Input file has sibling counterpart extension
 
 - Expected: both converted; comparison status printed.
 
-27. Outputs differ
+1. Outputs differ
 
 - Expected: similarity percentage + bounded diff preview printed.
 
-28. Outputs identical
+1. Outputs identical
 
 - Expected: IDENTICAL status printed.
 
diff --git a/shared/skills/documents/mail-to-adoc/scripts/Invoke-MailToAdoc.ps1 b/ai-artifacts/skills/shared/documents/mail-to-adoc/scripts/Invoke-MailToAdoc.ps1
similarity index 99%
rename from shared/skills/documents/mail-to-adoc/scripts/Invoke-MailToAdoc.ps1
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/scripts/Invoke-MailToAdoc.ps1
index 05fce65..017dd4e 100644
--- a/shared/skills/documents/mail-to-adoc/scripts/Invoke-MailToAdoc.ps1
+++ b/ai-artifacts/skills/shared/documents/mail-to-adoc/scripts/Invoke-MailToAdoc.ps1
@@ -1,4 +1,6 @@
 #Requires -Version 7
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
 <#
 .SYNOPSIS
     Batch-converts .eml/.msg files in a source folder to AsciiDoc via mail_to_adoc.py.
diff --git a/shared/skills/documents/mail-to-adoc/scripts/Move-Belege.ps1 b/ai-artifacts/skills/shared/documents/mail-to-adoc/scripts/Move-Belege.ps1
similarity index 93%
rename from shared/skills/documents/mail-to-adoc/scripts/Move-Belege.ps1
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/scripts/Move-Belege.ps1
index 07a4ced..f8995fb 100644
--- a/shared/skills/documents/mail-to-adoc/scripts/Move-Belege.ps1
+++ b/ai-artifacts/skills/shared/documents/mail-to-adoc/scripts/Move-Belege.ps1
@@ -1,4 +1,6 @@
 #Requires -Version 7
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
 <#
 .SYNOPSIS
     Moves files from a staging folder to their target folder, removing duplicates.
@@ -52,8 +54,8 @@ $ErrorActionPreference = 'Stop'
 
 $Root = (Get-Location).Path
 
-if (-not $SourceDir) { $SourceDir = Join-Path $Root '.new\Abrechnungen' }
-if (-not $DestDir)   { $DestDir   = Join-Path $Root '02_Auskunft-Einkommen\Gehaltsabrechnungen' }
+if (-not $SourceDir) { $SourceDir = Join-Path (Join-Path $Root '.new') 'Abrechnungen' }
+if (-not $DestDir)   { $DestDir   = Join-Path (Join-Path $Root '02_Auskunft-Einkommen') 'Gehaltsabrechnungen' }
 
 if (-not (Test-Path $SourceDir)) { throw "SourceDir not found: $SourceDir" }
 
diff --git a/shared/skills/documents/mail-to-adoc/scripts/mail_to_adoc.py b/ai-artifacts/skills/shared/documents/mail-to-adoc/scripts/mail_to_adoc.py
similarity index 88%
rename from shared/skills/documents/mail-to-adoc/scripts/mail_to_adoc.py
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/scripts/mail_to_adoc.py
index ce62ba9..79c8c89 100644
--- a/shared/skills/documents/mail-to-adoc/scripts/mail_to_adoc.py
+++ b/ai-artifacts/skills/shared/documents/mail-to-adoc/scripts/mail_to_adoc.py
@@ -19,17 +19,17 @@
 try:
     _LOCAL_TZ = ZoneInfo("Europe/Berlin")
 except Exception:
-    raise SystemExit(
-        "Missing timezone data. Run: pip install tzdata"
-    )
+    raise SystemExit("Missing timezone data. Run: pip install tzdata")
 _LOG_DIR = _PROJECT_ROOT / ".logs"
 
 #: Dennis's own email addresses — used to determine sent vs. received direction.
 #: [REDACTED for public repo — real values in the .temp/ originals]
-_DENNIS_EMAILS: frozenset[str] = frozenset({
-    "owner@example.com",
-    "owner.alt@example.com",
-})
+_DENNIS_EMAILS: frozenset[str] = frozenset(
+    {
+        "owner@example.com",
+        "owner.alt@example.com",
+    }
+)
 
 #: Maps known email addresses to short party names for filenames.
 #: [REDACTED for public repo — real values in the .temp/ originals]
@@ -82,7 +82,6 @@
 REPLY_HEADER_PATTERN = re.compile(r"^\*([^*]+):\*\s*", re.IGNORECASE)
 
 
-
 def _log_warning(msg: str) -> None:
     """Print a warning and append it to .logs/mail_to_adoc.log."""
     print(msg)
@@ -90,6 +89,7 @@ def _log_warning(msg: str) -> None:
         _LOG_DIR.mkdir(parents=True, exist_ok=True)
         log_file = _LOG_DIR / "mail_to_adoc.log"
         from datetime import datetime
+
         timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
         with open(log_file, "a", encoding="utf-8") as f:
             f.write(f"[{timestamp}] {msg}\n")
@@ -97,11 +97,11 @@ def _log_warning(msg: str) -> None:
         pass  # log write failed silently
 
 
-
 def _decode_rfc2047(value: str) -> str:
     """Decode RFC 2047 encoded-words in email headers, e.g. =?utf-8?Q?...?="""
     from email.header import decode_header, make_header
-    if not value or '=?' not in value:
+
+    if not value or "=?" not in value:
         return value
     try:
         return str(make_header(decode_header(value)))
@@ -112,10 +112,13 @@ def _decode_rfc2047(value: str) -> str:
 def _decode_qp_body(text: str) -> str:
     """Decode any residual quoted-printable sequences (=XX) in plain text."""
     import quopri
-    if '=' not in text:
+
+    if "=" not in text:
         return text
     try:
-        return quopri.decodestring(text.encode('ascii', errors='replace')).decode('utf-8', errors='replace')
+        return quopri.decodestring(text.encode("ascii", errors="replace")).decode(
+            "utf-8", errors="replace"
+        )
     except Exception:
         return text
 
@@ -142,21 +145,24 @@ def __init__(self):
         # List rendering state — one entry per nesting level to support nested ul/ol
         self.list_depth = 0
         self.list_type_stack: list[str] = []  # 'ul' or 'ol' for each open list
-        self.list_item_stack: list[list[str]] = (
-            []
-        )  # text fragments collected for each open <li>
+        self.list_item_stack: list[
+            list[str]
+        ] = []  # text fragments collected for each open <li>
 
         # Table rendering state
         self.table_depth = 0
         self.current_cell: list[str] | None = None  # None when no <td>/<th> is open
         self.current_row_cells: list[str] = []  # cells accumulated for the current <tr>
-        self.table_rows: list[list[str]] = (
-            []
-        )  # all rows accumulated for the current <table>
+        self.table_rows: list[
+            list[str]
+        ] = []  # all rows accumulated for the current <table>
 
         # Hyperlink state — href is set on <a>, used while writing inner text, cleared on </a>
         self.open_link_href: str | None = None
 
+        # Tags whose contents should be discarded entirely.
+        self.ignored_tag_depth = 0
+
     def _write(self, text: str) -> None:
         """Append text to the innermost active context: list item, table cell, or top level."""
         if self.list_item_stack:
@@ -168,6 +174,11 @@ def _write(self, text: str) -> None:
 
     def handle_starttag(self, tag, attrs):
         tag = tag.lower()
+        if tag in ("script", "style", "o:p"):
+            self.ignored_tag_depth += 1
+            return
+        if self.ignored_tag_depth:
+            return
         attr_dict = dict(attrs)
         if tag == "table":
             self.table_depth += 1
@@ -200,6 +211,11 @@ def handle_starttag(self, tag, attrs):
 
     def handle_endtag(self, tag):
         tag = tag.lower()
+        if tag in ("script", "style", "o:p"):
+            self.ignored_tag_depth = max(0, self.ignored_tag_depth - 1)
+            return
+        if self.ignored_tag_depth:
+            return
         if tag == "table":
             if self.table_depth == 1 and self.table_rows:
                 header_row = " ".join(f"|{c}" for c in self.table_rows[0])
@@ -264,6 +280,8 @@ def handle_endtag(self, tag):
             self._write("\n")
 
     def handle_data(self, data: str) -> None:
+        if self.ignored_tag_depth:
+            return
         data = re.sub(
             r"[\u200b\u200c\u200d\ufeff\u00ad]", "", data
         )  # zero-width / soft-hyphen chars
@@ -284,12 +302,7 @@ def get_text(self) -> str:
 
 def strip_html(html: str) -> str:
     """Remove non-content HTML and convert the remainder to AsciiDoc markup."""
-    html = re.sub(r"<style[^>]*>.*?</style>", "", html, flags=re.IGNORECASE | re.DOTALL)
-    html = re.sub(
-        r"<script[^>]*>.*?</script>", "", html, flags=re.IGNORECASE | re.DOTALL
-    )
     html = re.sub(r"<!--.*?-->", "", html, flags=re.DOTALL)
-    html = re.sub(r"<o:p[^>]*>.*?</o:p>", "", html, flags=re.IGNORECASE | re.DOTALL)
     html = re.sub(
         r"<!\[if[^\]]*\]>.*?<!\[endif\]>", "", html, flags=re.IGNORECASE | re.DOTALL
     )
@@ -307,7 +320,6 @@ def normalize_body(body: str) -> str:
     return body
 
 
-
 def _load_blocklist(script_dir: Path) -> set[str]:
     """Load MD5 checksums from attachment-blocklist.txt next to the skills folder."""
     blocklist_path = script_dir.parent / "attachment-blocklist.txt"
@@ -375,7 +387,6 @@ def _write_unique_file(
     return dest
 
 
-
 def _clean_filename(subject: str) -> str:
     """Clean subject for filesystem use: 'AW: Foo' → 'AW_ Foo'.
 
@@ -390,10 +401,10 @@ def _clean_filename(subject: str) -> str:
 _STEM_SEP = " — "
 # Bracket tags appended at the end of the filename stem (replaces the older emoji
 # markers ✉/✎𓂃/📎). Order in the stem: '{name} {direction}{[CC] if cc-only}{[+] if attachments}'.
-_DIR_RECEIVED = "[FROM]"   # mail Dennis received
-_DIR_SENT     = "[TO]"     # mail Dennis sent
-_CC_FLAG      = "[CC]"     # received mail where Dennis was only in Cc (not To)
-_ATT_FLAG     = "[+]"      # mail has attachments
+_DIR_RECEIVED = "[FROM]"  # mail Dennis received
+_DIR_SENT = "[TO]"  # mail Dennis sent
+_CC_FLAG = "[CC]"  # received mail where Dennis was only in Cc (not To)
+_ATT_FLAG = "[+]"  # mail has attachments
 
 
 def _adoc_stem(mail_date, subject: str) -> str:
@@ -425,7 +436,7 @@ def _meta_field(adoc: str, label: str) -> str:
             continue
         if m.group(1) == "a":  # bulleted list continues on the following '* ' lines
             vals = []
-            for nxt in lines[i + 1:]:
+            for nxt in lines[i + 1 :]:
                 s = nxt.strip()
                 if s.startswith("* "):
                     vals.append(s[2:])
@@ -447,6 +458,7 @@ def _direction_tag(
     From/To header values extracted from the adoc metadata table; uses _DENNIS_EMAILS
     to detect sent mail and _EMAIL_NAME_MAP for party names.
     """
+
     def _extract_addr(field: str) -> str:
         m = re.search(r"<([^>]+)>", field)
         return (m.group(1) if m else field).strip().lower()
@@ -469,8 +481,7 @@ def _name_for(field: str) -> str:
     from_addr = _extract_addr(from_v)
     if from_addr in _DENNIS_EMAILS:
         others = [
-            a for a in re.findall(r"<([^>]+)>", to_v)
-            if a.lower() not in _DENNIS_EMAILS
+            a for a in re.findall(r"<([^>]+)>", to_v) if a.lower() not in _DENNIS_EMAILS
         ]
         _n = "MultipleRecipients" if len(others) > 1 else _name_for(to_v)
         return f"{_n} {_DIR_SENT}{_att}"
@@ -637,7 +648,7 @@ def _addr_table_row(label: str, addr_str: str) -> str:
     return f"|{label} a|" + "\n".join(f"* {a}" for a in addrs)
 
 
-_POSTPROCESS_LONG_LINE = 80   # lines longer than this are QP-wrapped paragraphs
+_POSTPROCESS_LONG_LINE = 80  # lines longer than this are QP-wrapped paragraphs
 _POSTPROCESS_LIST_PREFIXES = ("* ", "** ", "*** ", ". ", ".. ", "... ", "- ")
 
 
@@ -682,10 +693,22 @@ def _unwrap(m: re.Match) -> str:
     # thin rule in the rendered email.  Insert AsciiDoc ''' before them.
     _REPLY_START = re.compile(r"^\*(Von|From|De|Van):\*", re.IGNORECASE)
     # All recognised reply-header field names (German + English).
-    _REPLY_HDR_KEYS = frozenset({
-        "from", "sent", "to", "cc", "bcc", "subject", "date",
-        "von", "gesendet", "an", "betreff", "datum",
-    })
+    _REPLY_HDR_KEYS = frozenset(
+        {
+            "from",
+            "sent",
+            "to",
+            "cc",
+            "bcc",
+            "subject",
+            "date",
+            "von",
+            "gesendet",
+            "an",
+            "betreff",
+            "datum",
+        }
+    )
 
     def _is_reply_hdr(line: str) -> bool:
         m = re.match(r"^\*([^*]+):\*", line.strip(), re.IGNORECASE)
@@ -712,21 +735,23 @@ def _is_reply_hdr(line: str) -> bool:
     #   • Everything else that is followed by non-blank → add ' +'
     def _is_structural(line: str) -> bool:
         s = line.strip()
-        return (s.startswith("[")
-                or s in ("'''", "---", "***", "___")
-                or s.startswith("="))
+        return (
+            s.startswith("[") or s in ("'''", "---", "***", "___") or s.startswith("=")
+        )
 
     lines = body.split("\n")
     out = []
     for idx, line in enumerate(lines):
         raw = line.rstrip()
         next_line = lines[idx + 1] if idx + 1 < len(lines) else ""
-        if (raw
-                and next_line.strip()
-                and not raw.endswith(" +")
-                and not _is_structural(raw)
-                and not any(raw.lstrip().startswith(p) for p in _POSTPROCESS_LIST_PREFIXES)
-                and (_is_reply_hdr(raw) or len(raw) <= _POSTPROCESS_LONG_LINE)):
+        if (
+            raw
+            and next_line.strip()
+            and not raw.endswith(" +")
+            and not _is_structural(raw)
+            and not any(raw.lstrip().startswith(p) for p in _POSTPROCESS_LIST_PREFIXES)
+            and (_is_reply_hdr(raw) or len(raw) <= _POSTPROCESS_LONG_LINE)
+        ):
             out.append(raw + " +")
         else:
             out.append(line)
@@ -744,6 +769,7 @@ def _decode_thread_index(raw: str) -> str:
     Depth 0 = root message (no replies in chain yet).
     """
     import base64 as _b64
+
     raw = raw.strip()
     if not raw:
         return ""
@@ -759,18 +785,33 @@ def _decode_thread_index(raw: str) -> str:
         return raw
 
 
-
 def _build_adoc(
-    subject: str, sender: str, to: str, cc: str, date: str,
-    attachment_links: list, body: str,
-    *, reply_to: str = "", bcc: str = "", importance: str = "",
-    sensitivity: str = "", categories: str = "",
-    thread_topic: str = "", thread_index: str = "",
+    subject: str,
+    sender: str,
+    to: str,
+    cc: str,
+    date: str,
+    attachment_links: list,
+    body: str,
+    *,
+    reply_to: str = "",
+    bcc: str = "",
+    importance: str = "",
+    sensitivity: str = "",
+    categories: str = "",
+    thread_topic: str = "",
+    thread_index: str = "",
 ) -> str:
     """Assemble the final AsciiDoc document from extracted mail fields."""
     subject_escaped = subject.replace(": ", "&#58; ")
-    lines = [f"= {subject_escaped}", "", "[%autowidth]", "|===",
-             f"|From |{sender}", f"|Sent |{date}"]
+    lines = [
+        f"= {subject_escaped}",
+        "",
+        "[%autowidth]",
+        "|===",
+        f"|From |{sender}",
+        f"|Sent |{date}",
+    ]
     to_row = _addr_table_row("To  ", to)
     if to_row:
         lines.append(to_row)
@@ -799,7 +840,9 @@ def _build_adoc(
         lines += ["[NOTE]", "====", "*Attachments:*", ""]
         for orig_name, link_path, is_image in attachment_links:
             if is_image:
-                lines.append(f'image::{link_path}[{orig_name}, 120, link="{link_path}"]')
+                lines.append(
+                    f'image::{link_path}[{orig_name}, 120, link="{link_path}"]'
+                )
             else:
                 lines.append(f"* link:{link_path}[{orig_name}]")
         lines += ["", "====", ""]
@@ -831,7 +874,11 @@ def msg_to_adoc(msg_path: Path) -> str:
         # Prefer HTML (has charset) → fallback plain text
         html_bytes = msg.htmlBody
         if html_bytes:
-            html = _decode_msg_html(html_bytes) if isinstance(html_bytes, bytes) else html_bytes
+            html = (
+                _decode_msg_html(html_bytes)
+                if isinstance(html_bytes, bytes)
+                else html_bytes
+            )
             body = strip_html(html)
         else:
             body = msg.body or ""
@@ -840,8 +887,11 @@ def msg_to_adoc(msg_path: Path) -> str:
         for att in msg.attachments:
             if getattr(att, "isInline", False):
                 continue
-            name = re.sub(r"\s+", " ",
-                (att.longFilename or att.shortFilename or "").replace("\x00", "")).strip()
+            name = re.sub(
+                r"\s+",
+                " ",
+                (att.longFilename or att.shortFilename or "").replace("\x00", ""),
+            ).strip()
             if not name:
                 continue
             raw_attachments.append((name, getattr(att, "data", None) or b""))
@@ -849,28 +899,57 @@ def msg_to_adoc(msg_path: Path) -> str:
         if mail_date is not None:
             # extract_msg may return a timezone-naive UTC datetime; convert to local.
             import datetime as _dt
+
             if mail_date.tzinfo is None:
                 mail_date = mail_date.replace(tzinfo=_dt.timezone.utc)
             mail_date = mail_date.astimezone(_LOCAL_TZ)
         reply_to = re.sub(r"[ \t]+", " ", getattr(msg, "reply_to", "") or "")
         bcc = re.sub(r"[ \t]+", " ", getattr(msg, "bcc", "") or "")
-        raw_imp = getattr(msg, "importanceText", None) or getattr(msg, "importance", None)
-        importance = (IMPORTANCE_LABELS.get(raw_imp, "") if isinstance(raw_imp, int)
-                      else str(raw_imp).capitalize() if raw_imp else "")
-        raw_sens = getattr(msg, "sensitivityText", None) or getattr(msg, "sensitivity", None)
-        sensitivity = (SENSITIVITY_LABELS.get(raw_sens, "") if isinstance(raw_sens, int)
-                       else str(raw_sens).capitalize() if raw_sens else "")
+        raw_imp = getattr(msg, "importanceText", None) or getattr(
+            msg, "importance", None
+        )
+        importance = (
+            IMPORTANCE_LABELS.get(raw_imp, "")
+            if isinstance(raw_imp, int)
+            else str(raw_imp).capitalize()
+            if raw_imp
+            else ""
+        )
+        raw_sens = getattr(msg, "sensitivityText", None) or getattr(
+            msg, "sensitivity", None
+        )
+        sensitivity = (
+            SENSITIVITY_LABELS.get(raw_sens, "")
+            if isinstance(raw_sens, int)
+            else str(raw_sens).capitalize()
+            if raw_sens
+            else ""
+        )
         categories = ", ".join(str(c) for c in (getattr(msg, "categories", None) or []))
         thread_topic = (getattr(msg, "threadTopic", None) or "").strip()
         thread_index = (getattr(msg, "threadIndex", None) or "").strip()
     finally:
         msg.close()
     docs_dir = _PROJECT_ROOT / "01_Korrespondenz" / "Attachments"
-    attachment_links = process_attachments(raw_attachments, mail_date, docs_dir, msg_path)
-    return _build_adoc(subject, sender, to, cc, date, attachment_links, body,
-                       reply_to=reply_to, bcc=bcc, importance=importance,
-                       sensitivity=sensitivity, categories=categories,
-                       thread_topic=thread_topic, thread_index=thread_index)
+    attachment_links = process_attachments(
+        raw_attachments, mail_date, docs_dir, msg_path
+    )
+    return _build_adoc(
+        subject,
+        sender,
+        to,
+        cc,
+        date,
+        attachment_links,
+        body,
+        reply_to=reply_to,
+        bcc=bcc,
+        importance=importance,
+        sensitivity=sensitivity,
+        categories=categories,
+        thread_topic=thread_topic,
+        thread_index=thread_index,
+    )
 
 
 def _unfold_header(value: str) -> str:
@@ -915,16 +994,25 @@ def eml_to_adoc(eml_path: Path) -> str:
             payload = part.get_payload(decode=True)
             if isinstance(payload, (bytes, bytearray)) and payload:
                 html_body = bytes(payload).decode(
-                    part.get_content_charset() or "utf-8", errors="replace")
+                    part.get_content_charset() or "utf-8", errors="replace"
+                )
         elif content_type == "text/plain" and plain_body is None:
             payload = part.get_payload(decode=True)
             if isinstance(payload, (bytes, bytearray)) and payload:
                 raw_plain = bytes(payload).decode(
-                    part.get_content_charset() or "utf-8", errors="replace")
+                    part.get_content_charset() or "utf-8", errors="replace"
+                )
                 # Some clients embed QP-encoded text without declaring CTE
-                plain_body = _decode_qp_body(raw_plain) if "=3D" in raw_plain or "=C3" in raw_plain else raw_plain
-    body = normalize_body(strip_html(html_body)) if html_body else (
-           normalize_body(plain_body) if plain_body else "")
+                plain_body = (
+                    _decode_qp_body(raw_plain)
+                    if "=3D" in raw_plain or "=C3" in raw_plain
+                    else raw_plain
+                )
+    body = (
+        normalize_body(strip_html(html_body))
+        if html_body
+        else (normalize_body(plain_body) if plain_body else "")
+    )
     reply_to = _unfold_header(msg.get("Reply-To") or "")
     bcc = _unfold_header(msg.get("BCC") or msg.get("Bcc") or "")
     imp_hdr = msg.get("Importance") or msg.get("X-Priority") or ""
@@ -934,11 +1022,25 @@ def eml_to_adoc(eml_path: Path) -> str:
     thread_topic = _decode_rfc2047(_unfold_header(msg.get("Thread-Topic") or ""))
     thread_index = _unfold_header(msg.get("Thread-Index") or "")
     docs_dir = _PROJECT_ROOT / "01_Korrespondenz" / "Attachments"
-    attachment_links = process_attachments(raw_attachments, mail_date, docs_dir, eml_path)
-    return _build_adoc(subject, sender, to, cc, date, attachment_links, body,
-                       reply_to=reply_to, bcc=bcc, importance=importance,
-                       sensitivity=sensitivity, categories=categories,
-                       thread_topic=thread_topic, thread_index=thread_index)
+    attachment_links = process_attachments(
+        raw_attachments, mail_date, docs_dir, eml_path
+    )
+    return _build_adoc(
+        subject,
+        sender,
+        to,
+        cc,
+        date,
+        attachment_links,
+        body,
+        reply_to=reply_to,
+        bcc=bcc,
+        importance=importance,
+        sensitivity=sensitivity,
+        categories=categories,
+        thread_topic=thread_topic,
+        thread_index=thread_index,
+    )
 
 
 def main():
@@ -979,7 +1081,9 @@ def _emit(msg: str) -> None:
     _jr: dict = {}
 
     if not args:
-        print("Usage: python mail_to_adoc.py [--root <project-root>] [--overwrite] [--json] <file.msg|.eml>")
+        print(
+            "Usage: python mail_to_adoc.py [--root <project-root>] [--overwrite] [--json] <file.msg|.eml>"
+        )
         sys.exit(1)
 
     mail_path = Path(args[0])
@@ -1001,6 +1105,7 @@ def _emit(msg: str) -> None:
 
     # ── 2. Convert primary into .temp/ ────────────────────────────────────────
     import tempfile as _tempfile
+
     temp_dir = Path(_tempfile.gettempdir()) / "mail_to_adoc_temp"
     temp_dir.mkdir(parents=True, exist_ok=True)
     temp_primary = temp_dir / (stem + ".adoc")
@@ -1014,10 +1119,14 @@ def _emit(msg: str) -> None:
     final_adoc = primary_adoc
 
     if counterpart.exists():
-        import tempfile, shutil as _shutil
-        tmp_fd, tmp_name = tempfile.mkstemp(suffix=f".{counterpart_ext[1:]}.adoc",
-                                            prefix=stem + "_cmp_")
-        import os as _os; _os.close(tmp_fd)
+        import tempfile
+
+        tmp_fd, tmp_name = tempfile.mkstemp(
+            suffix=f".{counterpart_ext[1:]}.adoc", prefix=stem + "_cmp_"
+        )
+        import os as _os
+
+        _os.close(tmp_fd)
         temp_cmp = Path(tmp_name)
         _, cmp_adoc = _write_converted_mail(counterpart, temp_cmp)
         _report_adoc_comparison(temp_primary, primary_adoc, temp_cmp, cmp_adoc)
@@ -1038,7 +1147,7 @@ def _emit(msg: str) -> None:
     _fm = re.search(r"\|From\s*\|(.+)", final_adoc)
     _tm = re.search(r"\|To\s*\|(.+)", final_adoc)
     _from_v = _fm.group(1).strip() if _fm else ""
-    _to_v   = _tm.group(1).strip() if _tm else ""
+    _to_v = _tm.group(1).strip() if _tm else ""
     _has_att = "*Attachments:*" in final_adoc
     # Dennis was only CC'd when he appears in the Cc field but not in To.
     _cc_only = _dennis_in(_meta_field(final_adoc, "CC")) and not _dennis_in(
@@ -1050,6 +1159,7 @@ def _emit(msg: str) -> None:
 
     # ── 5. Copy from .temp/ to 01_Korrespondenz/{year}/{month}/ ─────────────
     import shutil as _shutil2
+
     out_dir = _PROJECT_ROOT / "01_Korrespondenz" / year / month
     out_dir.mkdir(parents=True, exist_ok=True)
     out_path = out_dir / (full_stem + ".adoc")
@@ -1057,7 +1167,9 @@ def _emit(msg: str) -> None:
     if out_path.exists():
         try:
             existing = out_path.read_text(encoding="utf-8")
-            identical = existing.replace("\r\n", "\n") == final_adoc.replace("\r\n", "\n")
+            identical = existing.replace("\r\n", "\n") == final_adoc.replace(
+                "\r\n", "\n"
+            )
         except OSError:
             identical = False  # cloud-only file — treat as needing overwrite
         if identical:
@@ -1066,7 +1178,9 @@ def _emit(msg: str) -> None:
         elif overwrite:
             # copy2 cannot open a cloud-only file for 'wb'; use rename instead:
             # write to a sibling temp file, then rename() over the cloud-only target.
-            import os as _os, tempfile as _tf
+            import os as _os
+            import tempfile as _tf
+
             tmp_fd, tmp_name = _tf.mkstemp(dir=out_dir, prefix=".tmp_")
             _os.close(tmp_fd)
             _shutil2.copy2(str(temp_primary), tmp_name)
@@ -1089,16 +1203,21 @@ def _emit(msg: str) -> None:
 
     # ── 6. Archive / rename source file ──────────────────────────────────────
     import filecmp as _filecmp
+
     _parts = [p.lower() for p in mail_path.resolve().parts]
     _in_archive = any(
-        _parts[i] == "01_korrespondenz" and i + 1 < len(_parts) and _parts[i + 1] == "original"
+        _parts[i] == "01_korrespondenz"
+        and i + 1 < len(_parts)
+        and _parts[i + 1] == "original"
         for i in range(len(_parts) - 1)
     )
     archive_ext = mail_path.suffix
     new_src_name = full_stem + archive_ext  # match adoc stem
 
     if not _in_archive:
-        archive_dir = _PROJECT_ROOT / "01_Korrespondenz" / "Original" / f"{year}-{month}"
+        archive_dir = (
+            _PROJECT_ROOT / "01_Korrespondenz" / "Original" / f"{year}-{month}"
+        )
         archive_dir.mkdir(parents=True, exist_ok=True)
         dest = archive_dir / new_src_name
 
@@ -1140,7 +1259,6 @@ def _emit(msg: str) -> None:
                 _jr["archive_status"] = "skipped_rename"
                 _emit(f"Umbenennung übersprungen (Ziel existiert): {dest.name}")
 
-
     if json_mode:
         print(_json.dumps(_jr, ensure_ascii=True))
 
diff --git a/shared/skills/documents/mail-to-adoc/tests/README.md b/ai-artifacts/skills/shared/documents/mail-to-adoc/tests/README.md
similarity index 100%
rename from shared/skills/documents/mail-to-adoc/tests/README.md
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/tests/README.md
diff --git a/shared/skills/documents/mail-to-adoc/tests/conftest.py b/ai-artifacts/skills/shared/documents/mail-to-adoc/tests/conftest.py
similarity index 100%
rename from shared/skills/documents/mail-to-adoc/tests/conftest.py
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/tests/conftest.py
diff --git a/shared/skills/documents/mail-to-adoc/tests/test_mail_to_adoc.py b/ai-artifacts/skills/shared/documents/mail-to-adoc/tests/test_mail_to_adoc.py
similarity index 93%
rename from shared/skills/documents/mail-to-adoc/tests/test_mail_to_adoc.py
rename to ai-artifacts/skills/shared/documents/mail-to-adoc/tests/test_mail_to_adoc.py
index ed7d452..3010980 100644
--- a/shared/skills/documents/mail-to-adoc/tests/test_mail_to_adoc.py
+++ b/ai-artifacts/skills/shared/documents/mail-to-adoc/tests/test_mail_to_adoc.py
@@ -92,7 +92,9 @@ def test_process_attachments_skips_blocklist_and_dedupes_existing(
         msg_path=Path("mails/sample.eml"),
     )
 
-    assert links == [("duplicate.pdf", "../../../docs/20260511_1452-evidence.pdf", False)]
+    assert links == [
+        ("duplicate.pdf", "../../../docs/20260511_1452-evidence.pdf", False)
+    ]
     assert not (docs_dir / "20260511_1452-blocked.png").exists()
 
 
@@ -130,6 +132,18 @@ def test_eml_to_adoc_prefers_html_and_writes_attachment_links(converter, tmp_pat
     assert f"* link:../../Attachments/{saved_name}[evidence.pdf]" in adoc
 
 
+def test_strip_html_removes_script_tag_with_whitespace_before_closing_bracket(
+    converter,
+):
+    html = "<p>keep</p><script>alert('x')</script ><p>also keep</p>"
+
+    text = converter.strip_html(html)
+
+    assert "alert('x')" not in text
+    assert "keep" in text
+    assert "also keep" in text
+
+
 # --- Filename direction/attachment markers (bracket tags, replacing emoji) ------
 
 _DENNIS = "Dennis <owner@example.com>"
diff --git a/shared/skills/planning/scratch-plan/METADATA.md b/ai-artifacts/skills/shared/planning/scratch-plan/METADATA.md
similarity index 94%
rename from shared/skills/planning/scratch-plan/METADATA.md
rename to ai-artifacts/skills/shared/planning/scratch-plan/METADATA.md
index 4bcf452..3ac06e2 100644
--- a/shared/skills/planning/scratch-plan/METADATA.md
+++ b/ai-artifacts/skills/shared/planning/scratch-plan/METADATA.md
@@ -6,7 +6,7 @@ resource: ./SKILL.md
 tags: [planning, skill]
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `planning`
diff --git a/shared/skills/planning/scratch-plan/SKILL.md b/ai-artifacts/skills/shared/planning/scratch-plan/SKILL.md
similarity index 88%
rename from shared/skills/planning/scratch-plan/SKILL.md
rename to ai-artifacts/skills/shared/planning/scratch-plan/SKILL.md
index 04bc500..dc003ac 100644
--- a/shared/skills/planning/scratch-plan/SKILL.md
+++ b/ai-artifacts/skills/shared/planning/scratch-plan/SKILL.md
@@ -12,7 +12,7 @@ argument-hint: "[<feature-slug>]  — omit to review all features with TBD or ou
 # Scratch Plan
 
 Reviews `.scratch/` features and keeps the backlog current. Reads the ranking formula from
-`skills/planning/scratch/RANKING.md` and the layout from `skills/planning/scratch/LAYOUT.md`.
+`skills/planning/scratch/docs/RANKING.md` and the layout from `skills/planning/scratch/docs/LAYOUT.md`.
 
 ## Process
 
@@ -41,15 +41,15 @@ If the user enters a non-standard value (e.g. "5h", "3 days"), round to the near
 midpoints between adjacent buckets (bucket hours: 4h=4, 1day=8, 2days=16, 1week=40, 2weeks=80,
 1month=160, 2months=320):
 
-| Input | Maps to |
-|-------|---------|
-| < 6h | 4h |
-| 6h – < 12h | 1day |
-| 12h – < 28h | 2days |
-| 28h – < 60h | 1week |
-| 60h – < 120h | 2weeks |
-| 120h – < 240h | 1month |
-| ≥ 240h | 2months |
+| Input         | Maps to |
+| ------------- | ------- |
+| < 6h          | 4h      |
+| 6h – < 12h    | 1day    |
+| 12h – < 28h   | 2days   |
+| 28h – < 60h   | 1week   |
+| 60h – < 120h  | 2weeks  |
+| 120h – < 240h | 1month  |
+| ≥ 240h        | 2months |
 
 Silently apply the rounding and confirm the mapped bucket to the user before continuing.
 
@@ -72,7 +72,7 @@ When the user wants to raise a feature's rank outside the normal interview:
 ### 4. Rewrite BACKLOG.md
 
 After all interviews, compute each feature's score: `P × I × E` using the numeric values in
-`skills/planning/scratch/RANKING.md`. Sort descending by score; apply tiebreakers in order:
+`skills/planning/scratch/docs/RANKING.md`. Sort descending by score; apply tiebreakers in order:
 less effort → higher importance → higher priority → alphabetical.
 
 Rewrite `.scratch/BACKLOG.md` with the updated table, numbered ranks, and a `Last updated:` line.
diff --git a/shared/skills/planning/scratch/METADATA.md b/ai-artifacts/skills/shared/planning/scratch/METADATA.md
similarity index 94%
rename from shared/skills/planning/scratch/METADATA.md
rename to ai-artifacts/skills/shared/planning/scratch/METADATA.md
index 045ce40..212cbeb 100644
--- a/shared/skills/planning/scratch/METADATA.md
+++ b/ai-artifacts/skills/shared/planning/scratch/METADATA.md
@@ -6,7 +6,7 @@ resource: ./SKILL.md
 tags: [planning, skill]
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `planning`
diff --git a/shared/skills/planning/scratch/SKILL.md b/ai-artifacts/skills/shared/planning/scratch/SKILL.md
similarity index 83%
rename from shared/skills/planning/scratch/SKILL.md
rename to ai-artifacts/skills/shared/planning/scratch/SKILL.md
index 227427e..5412c40 100644
--- a/shared/skills/planning/scratch/SKILL.md
+++ b/ai-artifacts/skills/shared/planning/scratch/SKILL.md
@@ -5,7 +5,7 @@ description: >
   Manage .scratch/ feature entries and the backlog. Two modes: with $ARGUMENTS quick-captures a new
   feature idea as a stub PRD; without arguments, lists the ranked backlog. The canonical definition
   of the .scratch/ layout — other skills (to-issues, to-prd, triage, check-skill-updates) reference
-  [LAYOUT.md](scratch/LAYOUT.md) rather than restating the conventions. For re-ranking the backlog
+  [LAYOUT.md](docs/LAYOUT.md) rather than restating the conventions. For re-ranking the backlog
   use /planning:scratch-plan.
 argument-hint: "<feature idea or slug>"
 ---
@@ -24,7 +24,7 @@ When `$ARGUMENTS` is provided:
 3. Create `.scratch/<feature-slug>/PRD.md` from the stub template below.
 4. Append the feature to `.scratch/BACKLOG.md` with all ranking fields set to `TBD` and
    score `?`. If `BACKLOG.md` does not exist, create it from the template in
-   [LAYOUT.md](scratch/LAYOUT.md).
+   [LAYOUT.md](docs/LAYOUT.md).
 5. Tell the user: `Created .scratch/<feature-slug>/. Run /planning:scratch-plan to set its rank.`
 
 ### PRD stub
@@ -54,7 +54,7 @@ say so and suggest running with an argument to capture the first feature.
 
 ## Layout and ranking conventions
 
-See [LAYOUT.md](scratch/LAYOUT.md) — the canonical `.scratch/` folder layout. Reference this from
+See [LAYOUT.md](docs/LAYOUT.md) — the canonical `.scratch/` folder layout. Reference this from
 other skills; do not restate the conventions inline.
 
-See [RANKING.md](scratch/RANKING.md) — the score formula and tiebreaker rules.
+See [RANKING.md](docs/RANKING.md) — the score formula and tiebreaker rules.
diff --git a/shared/skills/planning/scratch/LAYOUT.md b/ai-artifacts/skills/shared/planning/scratch/docs/LAYOUT.md
similarity index 99%
rename from shared/skills/planning/scratch/LAYOUT.md
rename to ai-artifacts/skills/shared/planning/scratch/docs/LAYOUT.md
index 9b45ccb..04bbd3e 100644
--- a/shared/skills/planning/scratch/LAYOUT.md
+++ b/ai-artifacts/skills/shared/planning/scratch/docs/LAYOUT.md
@@ -7,7 +7,7 @@ rather than restating the conventions.
 
 Every feature lives in its own folder: `.scratch/<feature-slug>/`
 
-```
+```text
 .scratch/
   BACKLOG.md                        ← ranked index of all features (repo-level, one file)
   <feature-slug>/
@@ -49,6 +49,7 @@ Supporting *inputs* only — reference material that feeds the work, **never the
 Deliverables (a skill, script, report, or durable finding) live in their proper repo home; the rule
 and the deliverable→home table are in the folder guide `.scratch/AGENTS.md`. No required structure;
 common sub-folders:
+
 - `artifacts/<upstream-name>/` — upstream source files (when `.temp/` is gitignored)
 - `artifacts/global-prior/` — prior installed versions to mine for local customizations
 
diff --git a/ai-artifacts/skills/shared/planning/scratch/docs/RANKING.md b/ai-artifacts/skills/shared/planning/scratch/docs/RANKING.md
new file mode 100644
index 0000000..1f1f822
--- /dev/null
+++ b/ai-artifacts/skills/shared/planning/scratch/docs/RANKING.md
@@ -0,0 +1,52 @@
+# .scratch Ranking — Formula & Tiebreakers
+
+## Score formula
+
+```text
+Score = P × I × E
+```
+
+| Axis                                                    | Value   | Numeric |
+| ------------------------------------------------------- | ------- | ------- |
+| **P** (priority)                                        | high    | 3       |
+|                                                         | medium  | 2       |
+|                                                         | low     | 1       |
+| **I** (importance)                                      | high    | 3       |
+|                                                         | medium  | 2       |
+|                                                         | low     | 1       |
+| **E** (effort, **inverted** — less effort ranks higher) | 4h      | 7       |
+|                                                         | 1day    | 6       |
+|                                                         | 2days   | 5       |
+|                                                         | 1week   | 4       |
+|                                                         | 2weeks  | 3       |
+|                                                         | 1month  | 2       |
+|                                                         | 2months | 1       |
+
+Score range: 3 (low / low / 2months) — 63 (high / high / 4h).
+Higher score = higher in the backlog.
+
+## Tiebreakers (equal score, applied in order)
+
+1. Less effort (lower E_label wins — quick wins first)
+2. Higher importance
+3. Higher priority
+4. Alphabetical by feature slug
+
+## Escalation rule (used by `/planning:scratch-plan`)
+
+When a feature's rank should be raised:
+
+- If `importance < high` → raise importance one level.
+- If `importance = high` → raise priority one level instead (if `priority < high`).
+
+This prevents phantom "super-high" rankings by routing excess urgency into priority.
+
+## Example
+
+| Feature        | P          | I          | E           | Score |
+| -------------- | ---------- | ---------- | ----------- | ----- |
+| auth-refactor  | high (3)   | high (3)   | 1week (4)   | 36    |
+| fix-flaky-test | medium (2) | high (3)   | 4h (7)      | 42    |
+| docs-overhaul  | low (1)    | medium (2) | 2months (1) | 2     |
+
+Ranked: fix-flaky-test (42) > auth-refactor (36) > docs-overhaul (2).
diff --git a/shared/skills/session/caveman/METADATA.md b/ai-artifacts/skills/shared/session/caveman/METADATA.md
similarity index 96%
rename from shared/skills/session/caveman/METADATA.md
rename to ai-artifacts/skills/shared/session/caveman/METADATA.md
index e66ffb0..6e5ef03 100644
--- a/shared/skills/session/caveman/METADATA.md
+++ b/ai-artifacts/skills/shared/session/caveman/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/productivity/caveman/SKILL.md
 upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `session`
@@ -19,6 +19,6 @@ upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 - Reconciled commit: `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb`
 - Notes: Minor edits.
 
-# Citations
+## Citations
 
 [1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/session/caveman/SKILL.md b/ai-artifacts/skills/shared/session/caveman/SKILL.md
similarity index 93%
rename from shared/skills/session/caveman/SKILL.md
rename to ai-artifacts/skills/shared/session/caveman/SKILL.md
index 0f60481..c25525f 100644
--- a/shared/skills/session/caveman/SKILL.md
+++ b/ai-artifacts/skills/shared/session/caveman/SKILL.md
@@ -27,11 +27,11 @@ Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
 
 ### Examples
 
-**"Why React component re-render?"**
+#### "Why React component re-render?"
 
 > Inline obj prop -> new ref -> re-render. `useMemo`.
 
-**"Explain database connection pooling."**
+#### "Explain database connection pooling."
 
 > Pool = reuse DB conn. Skip handshake -> fast under load.
 
diff --git a/shared/skills/session/grill-me/METADATA.md b/ai-artifacts/skills/shared/session/grill-me/METADATA.md
similarity index 96%
rename from shared/skills/session/grill-me/METADATA.md
rename to ai-artifacts/skills/shared/session/grill-me/METADATA.md
index 4bd1118..8792ba3 100644
--- a/shared/skills/session/grill-me/METADATA.md
+++ b/ai-artifacts/skills/shared/session/grill-me/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/productivity/grill-me/SKILL.md
 upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `session`
@@ -19,6 +19,6 @@ upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 - Reconciled commit: `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb`
 - Notes: Absorbed engineering/grill-with-docs; upstream path tracks grill-me lineage only.
 
-# Citations
+## Citations
 
-[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
\ No newline at end of file
+[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/session/grill-me/SKILL.md b/ai-artifacts/skills/shared/session/grill-me/SKILL.md
similarity index 97%
rename from shared/skills/session/grill-me/SKILL.md
rename to ai-artifacts/skills/shared/session/grill-me/SKILL.md
index 121fea2..244f98c 100644
--- a/shared/skills/session/grill-me/SKILL.md
+++ b/ai-artifacts/skills/shared/session/grill-me/SKILL.md
@@ -3,63 +3,64 @@ name: grill-me
 version: 1.0.0
 description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Optionally challenges the plan against the project's existing language and drafts/revises documentation (CONTEXT.md, ADRs). Use when the user wants to stress-test a plan, get grilled on a design, says "grill me", or wants a plan checked against documented decisions and terminology.
 ---
-
-<environment>
-
-This skill runs in claude.ai (chat). There is no writable repo and no autonomous codebase access: the project filesystem cannot be edited in place, and nothing persists between conversations. Existing project files are available only when attached as Project knowledge or uploaded. Any documentation is *delivered as downloadable files* the user commits themselves — never written into their repo.
-
-</environment>
-
-<mode-gate>
-
-Decide this once, at the start, before grilling — it governs the whole session:
-
-**Docs mode is OFF by default.** Run a pure grilling session: no glossary, no CONTEXT.md, no ADRs, no documentation output. Don't mention them.
-
-**Engage docs mode only if** either is true:
-1. A `CONTEXT.md`, `CONTEXT-MAP.md`, or other project documentation is attached/uploaded, or
-2. The user explicitly asks for documentation, a glossary, or ADRs, or signals it by phrasing such as "with docs", "using the docs", or "against the docs".
-
-If a documentable decision surfaces while docs mode is off, you may make **one** brief offer ("worth capturing this as an ADR?") and then drop it unless the user says yes. Never drift into glossary/ADR behavior unprompted.
-
-</mode-gate>
-
-<grilling>
-
-Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
-
-Ask the questions one at a time, waiting for feedback on each before continuing.
-
-If a question can be answered from provided files (Project knowledge or uploads), check there first instead of asking. If the relevant code isn't provided, ask me to paste/upload it — or proceed on a stated assumption and flag it as unverified.
-
-</grilling>
-
-<docs-mode>
-
-Everything below applies **only when docs mode is engaged** (see mode-gate).
-
-## Domain awareness — three input states
-
-At the start, determine which applies from the files I've provided:
-
-1. **Baseline provided** — a `CONTEXT.md` (and/or `CONTEXT-MAP.md`, existing ADRs) is attached or uploaded. Read it and treat it as the authoritative baseline. Grill against its existing glossary; continue ADR numbering from the highest provided number. You revise *a copy* and hand it back — you cannot edit the original.
-2. **Code/docs only** — source files but no glossary. Cross-reference claims against them; build a `CONTEXT.md` from scratch.
-3. **Explicit request, nothing attached** — create a `CONTEXT.md` from scratch as terms resolve, working from my stated assumptions (flag each as unverified until I confirm).
-
-If a `CONTEXT-MAP.md` is provided, the project has multiple contexts; infer which one the current topic belongs to, and ask if unclear. Otherwise assume a single context.
-
-## During the session
-
-**Challenge against the glossary.** When I use a term that conflicts with the baseline `CONTEXT.md`, call it out: "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
-
-**Sharpen fuzzy language.** When I use vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User?"
-
-**Discuss concrete scenarios.** Stress-test domain relationships with specific scenarios that probe edge cases and force precision about boundaries.
-
-**Cross-reference with provided code.** When I state how something works *and* the code is in the provided files, check whether the code agrees and surface contradictions. If the code isn't provided, don't guess — ask for it or flag the claim as unverified.
-
-**Maintain CONTEXT.md as we go.** Keep a working copy in the session. When a term resolves, update it and re-deliver the file as a download — don't wait and dump everything at the end. `CONTEXT.md` is a glossary and nothing else: no implementation details, not a spec, not a scratch pad. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md).
-
-**Offer ADRs sparingly.** Only when all three are true: (1) hard to reverse, (2) surprising without context, (3) the result of a real trade-off. If any is missing, skip it. Deliver each ADR as a `docs/adr/NNNN-slug.md` file. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md).
-
-</docs-mode>
+
+<environment>
+
+This skill runs in claude.ai (chat). There is no writable repo and no autonomous codebase access: the project filesystem cannot be edited in place, and nothing persists between conversations. Existing project files are available only when attached as Project knowledge or uploaded. Any documentation is *delivered as downloadable files* the user commits themselves — never written into their repo.
+
+</environment>
+
+<mode-gate>
+
+Decide this once, at the start, before grilling — it governs the whole session:
+
+**Docs mode is OFF by default.** Run a pure grilling session: no glossary, no CONTEXT.md, no ADRs, no documentation output. Don't mention them.
+
+**Engage docs mode only if** either is true:
+
+1. A `CONTEXT.md`, `CONTEXT-MAP.md`, or other project documentation is attached/uploaded, or
+2. The user explicitly asks for documentation, a glossary, or ADRs, or signals it by phrasing such as "with docs", "using the docs", or "against the docs".
+
+If a documentable decision surfaces while docs mode is off, you may make **one** brief offer ("worth capturing this as an ADR?") and then drop it unless the user says yes. Never drift into glossary/ADR behavior unprompted.
+
+</mode-gate>
+
+<grilling>
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one. For each question, provide your recommended answer.
+
+Ask the questions one at a time, waiting for feedback on each before continuing.
+
+If a question can be answered from provided files (Project knowledge or uploads), check there first instead of asking. If the relevant code isn't provided, ask me to paste/upload it — or proceed on a stated assumption and flag it as unverified.
+
+</grilling>
+
+<docs-mode>
+
+Everything below applies **only when docs mode is engaged** (see mode-gate).
+
+## Domain awareness — three input states
+
+At the start, determine which applies from the files I've provided:
+
+1. **Baseline provided** — a `CONTEXT.md` (and/or `CONTEXT-MAP.md`, existing ADRs) is attached or uploaded. Read it and treat it as the authoritative baseline. Grill against its existing glossary; continue ADR numbering from the highest provided number. You revise *a copy* and hand it back — you cannot edit the original.
+2. **Code/docs only** — source files but no glossary. Cross-reference claims against them; build a `CONTEXT.md` from scratch.
+3. **Explicit request, nothing attached** — create a `CONTEXT.md` from scratch as terms resolve, working from my stated assumptions (flag each as unverified until I confirm).
+
+If a `CONTEXT-MAP.md` is provided, the project has multiple contexts; infer which one the current topic belongs to, and ask if unclear. Otherwise assume a single context.
+
+## During the session
+
+**Challenge against the glossary.** When I use a term that conflicts with the baseline `CONTEXT.md`, call it out: "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
+
+**Sharpen fuzzy language.** When I use vague or overloaded terms, propose a precise canonical term. "You're saying 'account' — do you mean the Customer or the User?"
+
+**Discuss concrete scenarios.** Stress-test domain relationships with specific scenarios that probe edge cases and force precision about boundaries.
+
+**Cross-reference with provided code.** When I state how something works *and* the code is in the provided files, check whether the code agrees and surface contradictions. If the code isn't provided, don't guess — ask for it or flag the claim as unverified.
+
+**Maintain CONTEXT.md as we go.** Keep a working copy in the session. When a term resolves, update it and re-deliver the file as a download — don't wait and dump everything at the end. `CONTEXT.md` is a glossary and nothing else: no implementation details, not a spec, not a scratch pad. Use the format in [CONTEXT-FORMAT.md](docs/CONTEXT-FORMAT.md).
+
+**Offer ADRs sparingly.** Only when all three are true: (1) hard to reverse, (2) surprising without context, (3) the result of a real trade-off. If any is missing, skip it. Deliver each ADR as a `docs/adr/NNNN-slug.md` file. Use the format in [ADR-FORMAT.md](docs/ADR-FORMAT.md).
+
+</docs-mode>
diff --git a/shared/skills/session/grill-me/ADR-FORMAT.md b/ai-artifacts/skills/shared/session/grill-me/docs/ADR-FORMAT.md
similarity index 100%
rename from shared/skills/session/grill-me/ADR-FORMAT.md
rename to ai-artifacts/skills/shared/session/grill-me/docs/ADR-FORMAT.md
diff --git a/shared/skills/session/grill-me/CONTEXT-FORMAT.md b/ai-artifacts/skills/shared/session/grill-me/docs/CONTEXT-FORMAT.md
similarity index 100%
rename from shared/skills/session/grill-me/CONTEXT-FORMAT.md
rename to ai-artifacts/skills/shared/session/grill-me/docs/CONTEXT-FORMAT.md
diff --git a/shared/skills/session/handoff/METADATA.md b/ai-artifacts/skills/shared/session/handoff/METADATA.md
similarity index 94%
rename from shared/skills/session/handoff/METADATA.md
rename to ai-artifacts/skills/shared/session/handoff/METADATA.md
index ca6e0c8..2e9e955 100644
--- a/shared/skills/session/handoff/METADATA.md
+++ b/ai-artifacts/skills/shared/session/handoff/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/productivity/handoff/SKILL.md
 upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `session`
@@ -19,6 +19,6 @@ upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 - Reconciled commit: `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb`
 - Notes: Minor edits.
 
-# Citations
+## Citations
 
-[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
\ No newline at end of file
+[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/session/handoff/SKILL.md b/ai-artifacts/skills/shared/session/handoff/SKILL.md
similarity index 100%
rename from shared/skills/session/handoff/SKILL.md
rename to ai-artifacts/skills/shared/session/handoff/SKILL.md
diff --git a/shared/skills/session/recon/METADATA.md b/ai-artifacts/skills/shared/session/recon/METADATA.md
similarity index 96%
rename from shared/skills/session/recon/METADATA.md
rename to ai-artifacts/skills/shared/session/recon/METADATA.md
index 87d3ef2..fb9fa5a 100644
--- a/shared/skills/session/recon/METADATA.md
+++ b/ai-artifacts/skills/shared/session/recon/METADATA.md
@@ -6,9 +6,9 @@ resource: ./SKILL.md
 tags: [session, skill]
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `session`
 - Origin: local
-- Notes: Local original.
\ No newline at end of file
+- Notes: Local original.
diff --git a/shared/skills/session/recon/SKILL.md b/ai-artifacts/skills/shared/session/recon/SKILL.md
similarity index 97%
rename from shared/skills/session/recon/SKILL.md
rename to ai-artifacts/skills/shared/session/recon/SKILL.md
index 3d034f9..f58ef70 100644
--- a/shared/skills/session/recon/SKILL.md
+++ b/ai-artifacts/skills/shared/session/recon/SKILL.md
@@ -3,77 +3,79 @@ name: recon
 version: 1.0.0
 description: Before generating code (SQL, PowerShell, Bash, Python, or any stack) whose correctness depends on environment facts you cannot see, generate a small read-only probe script the user runs to report ground truth — schema and column names/types, server version and edition, installed modules or importable packages, available cmdlets, file paths, config values, existing object definitions. The user pastes the probe's output back, and you generate the real code against what actually exists instead of against assumptions. Use when a request targets an existing system and correctness hinges on identifiers, versions, or availability you'd otherwise guess at; when the user says "recon", "check my environment first", "confirm what you know", or "help me help you"; or any time you're about to recite a column name, version, module, or path from memory.
 ---
-
-# Recon
-
-Generating code against an existing system from memory is guessing. Column names drift, versions differ, modules aren't installed, paths move, imports aren't present. **Recon replaces the guess with a fact** via a short handshake: emit a small read-only probe, the user runs it, the real output grounds the generated code.
-
-The probe is also a **proportionality check** — writing it forces you to name exactly which facts the code depends on. If you can't say what you'd probe for, you don't yet understand the request.
-
-**Boundary vs. `prototype`:** prototype is throwaway code to explore a design you're *inventing* by driving it by hand. Recon is read-only introspection to *discover* facts that already exist. Inventing vs. discovering — no overlap.
-
-## The handshake
-
-1. **Name the dependencies.** List the exact facts the requested code hinges on — table/column names + types, version/edition, module/package availability and versions, cmdlet existence, paths, config values, existing definitions.
-2. **Emit a probe** scoped to just those facts (see contract below). Show it in chat so the user can read it before running.
-3. **User runs it, pastes the output block back.**
-4. **Generate the real code** grounded in the reported facts. Where a reported value contradicts what you'd have assumed, say so explicitly — that contradiction is the whole reason recon exists.
-
-## Scale the probe to the question
-
-Recon is not "always emit a big script." Match the probe to what's actually uncertain.
-
-- **One fact → one line.** "Which SQL Server version?" → emit `SELECT @@VERSION;`, not a sweep. A one-liner the user runs beats both guessing and a back-and-forth in chat.
-- **Several interdependent facts → a surgical probe** (default). Collect exactly the named dependencies, nothing more.
-- **First contact with an unknown environment → a broad baseline sweep is legitimate.** When you have no map at all, one wider probe to establish a baseline can be the right call. Treat it as a deliberate exception to "surgical," not the default — and still scope it to the domain in play (the relevant database, the relevant module set), not the whole machine.
-
-## Probe contract
-
-**Read-only is the high bar.** The default probe inspects structure and metadata, never the data itself — catalog/metadata views, version functions, module listings, path existence. This bar is high but **crossable when the data *is* the required fact**: distinct enum values stored in a column, an actual config-table value, row cardinality that changes the approach, the real stored format of a field. When you cross it:
-
-- Cross only for the specific value needed, never a dump. `TOP (n)`, `DISTINCT`, `COUNT`, a single keyed lookup — not `SELECT *`.
-- Mask or omit anything plausibly sensitive (PII, secrets); report shape/cardinality over raw content where shape answers the question.
-- **Flag the crossing** in the probe and again at handoff: state that the probe reads data, which data, and why metadata alone was insufficient.
-
-**Output convention** (applies to every stack):
-
-- Collect all results into one structure; flush **once** at the end as a single block. No interleaved result output scattered through execution.
-- Emit the final block as **JSON** — the consumer is the model, and exact identifiers matter. Shape: `requested fact → value`, neutral, no assumptions baked in. `null` / `"not present"` is a valid reported value, not a failure.
-- Progress and diagnostics go to a separate stream (verbose/progress/stderr), never into the result block.
-- **Fail fast on infrastructure failure** (can't connect, command not found, permission denied) with a message naming what was missing. "Object not found" when *checking for existence* is a result, not a failure.
-- Keep it short enough to read and verify as safe before running.
-
-## Probe self-check
-
-A probe whose own failures are silent is worse than no probe — it grounds code in facts that were never actually collected. Two failure modes must be prevented *structurally* (by output design, not by "being careful"):
-
-**A — a failed step vanishes.** Under `$ErrorActionPreference='Stop'` / `set -e`, a throwing step can abort before the flush, or a per-fact failure can leave its key simply absent while later facts succeed — you read the report and never notice fact 1 died. Prevent it: guard each fact probe so its failure is *recorded as a failure value*, never absent; flush the buffer in a `finally`/`trap` so a partial report always emits; include an integrity footer — `attempted` vs `captured` counts plus the names that errored. `attempted ≠ captured` means something was dropped.
-
-**B — empty and absent collapse.** Request dataA, derive dataB from it. If dataB is empty you cannot tell "dataA had no children" from "dataA was never obtained / came back malformed." Prevent it: record dataA's own outcome — obtained? row count? — *as its own fact, before* deriving dataB. Then an empty dataB has exactly one cause.
-
-This needs a **tri-state, not a bare `null`**: distinguish *present-with-value*, *present-but-empty* (0 rows is a real answer), *probed-but-errored*, and *not-probed*. `null` alone is overloaded.
-
-**Before emitting the probe, verify:**
-- [ ] Every named dependency has a fact key — nothing silently skipped.
-- [ ] Each fact carries a status; failure is a recorded value, not an absence.
-- [ ] The flush runs even if a step throws (`finally`/`trap`); a genuine precondition failure (can't connect at all) still stops hard, outside the per-fact guard.
-- [ ] Dependent facts record their source's outcome; an empty derived set is attributable.
-- [ ] Output is valid parseable JSON — depth sufficient (no silent truncation), quotes/newlines escaped, no BOM, no locale-formatted numbers (decimal comma breaks JSON).
-
-**Before generating code from the pasted-back output, verify:**
-- [ ] All expected keys present; `attempted == captured`; no errored fact you're about to build on.
-- [ ] Values match expected shape — version matches a version pattern, counts are integers ≥ 0, expected arrays are arrays.
-- [ ] A value that contradicts your assumption is surfaced; a fact that errored or is empty gets re-probed or asked about — never generate over a hole.
-
-## Stack recipes
-
-Per-stack probe anchors — what to query and how to emit it for SQL, PowerShell, Bash, and Python — live in [RECIPES.md](RECIPES.md). Load the one recipe for the stack in play; keep the probe as small as the question allows.
-
-## Anti-patterns
-
-- **Don't guess then caveat.** Emitting code with "adjust the column names if they differ" is the failure recon exists to kill. Probe first.
-- **Don't over-collect.** Surgical by default; a broad sweep is a conscious baseline exception, not a habit.
-- **Don't cross the data bar casually.** Metadata first; touch data only when the value itself is the fact, and flag it.
-- **Don't bury the result.** One JSON block at the end; progress lives in another stream.
-- **Don't continue silently on a broken probe.** Infra failure stops with a named reason; "not present" is reported, not fatal.
-- **Don't probe what's already known.** If the user stated the fact, or it's visible in context, or it's stack-invariant, skip the probe and proceed.
+
+# Recon
+
+Generating code against an existing system from memory is guessing. Column names drift, versions differ, modules aren't installed, paths move, imports aren't present. **Recon replaces the guess with a fact** via a short handshake: emit a small read-only probe, the user runs it, the real output grounds the generated code.
+
+The probe is also a **proportionality check** — writing it forces you to name exactly which facts the code depends on. If you can't say what you'd probe for, you don't yet understand the request.
+
+**Boundary vs. `prototype`:** prototype is throwaway code to explore a design you're *inventing* by driving it by hand. Recon is read-only introspection to *discover* facts that already exist. Inventing vs. discovering — no overlap.
+
+## The handshake
+
+1. **Name the dependencies.** List the exact facts the requested code hinges on — table/column names + types, version/edition, module/package availability and versions, cmdlet existence, paths, config values, existing definitions.
+2. **Emit a probe** scoped to just those facts (see contract below). Show it in chat so the user can read it before running.
+3. **User runs it, pastes the output block back.**
+4. **Generate the real code** grounded in the reported facts. Where a reported value contradicts what you'd have assumed, say so explicitly — that contradiction is the whole reason recon exists.
+
+## Scale the probe to the question
+
+Recon is not "always emit a big script." Match the probe to what's actually uncertain.
+
+- **One fact → one line.** "Which SQL Server version?" → emit `SELECT @@VERSION;`, not a sweep. A one-liner the user runs beats both guessing and a back-and-forth in chat.
+- **Several interdependent facts → a surgical probe** (default). Collect exactly the named dependencies, nothing more.
+- **First contact with an unknown environment → a broad baseline sweep is legitimate.** When you have no map at all, one wider probe to establish a baseline can be the right call. Treat it as a deliberate exception to "surgical," not the default — and still scope it to the domain in play (the relevant database, the relevant module set), not the whole machine.
+
+## Probe contract
+
+**Read-only is the high bar.** The default probe inspects structure and metadata, never the data itself — catalog/metadata views, version functions, module listings, path existence. This bar is high but **crossable when the data *is* the required fact**: distinct enum values stored in a column, an actual config-table value, row cardinality that changes the approach, the real stored format of a field. When you cross it:
+
+- Cross only for the specific value needed, never a dump. `TOP (n)`, `DISTINCT`, `COUNT`, a single keyed lookup — not `SELECT *`.
+- Mask or omit anything plausibly sensitive (PII, secrets); report shape/cardinality over raw content where shape answers the question.
+- **Flag the crossing** in the probe and again at handoff: state that the probe reads data, which data, and why metadata alone was insufficient.
+
+**Output convention** (applies to every stack):
+
+- Collect all results into one structure; flush **once** at the end as a single block. No interleaved result output scattered through execution.
+- Emit the final block as **JSON** — the consumer is the model, and exact identifiers matter. Shape: `requested fact → value`, neutral, no assumptions baked in. `null` / `"not present"` is a valid reported value, not a failure.
+- Progress and diagnostics go to a separate stream (verbose/progress/stderr), never into the result block.
+- **Fail fast on infrastructure failure** (can't connect, command not found, permission denied) with a message naming what was missing. "Object not found" when *checking for existence* is a result, not a failure.
+- Keep it short enough to read and verify as safe before running.
+
+## Probe self-check
+
+A probe whose own failures are silent is worse than no probe — it grounds code in facts that were never actually collected. Two failure modes must be prevented *structurally* (by output design, not by "being careful"):
+
+**A — a failed step vanishes.** Under `$ErrorActionPreference='Stop'` / `set -e`, a throwing step can abort before the flush, or a per-fact failure can leave its key simply absent while later facts succeed — you read the report and never notice fact 1 died. Prevent it: guard each fact probe so its failure is *recorded as a failure value*, never absent; flush the buffer in a `finally`/`trap` so a partial report always emits; include an integrity footer — `attempted` vs `captured` counts plus the names that errored. `attempted ≠ captured` means something was dropped.
+
+**B — empty and absent collapse.** Request dataA, derive dataB from it. If dataB is empty you cannot tell "dataA had no children" from "dataA was never obtained / came back malformed." Prevent it: record dataA's own outcome — obtained? row count? — *as its own fact, before* deriving dataB. Then an empty dataB has exactly one cause.
+
+This needs a **tri-state, not a bare `null`**: distinguish *present-with-value*, *present-but-empty* (0 rows is a real answer), *probed-but-errored*, and *not-probed*. `null` alone is overloaded.
+
+**Before emitting the probe, verify:**
+
+- [ ] Every named dependency has a fact key — nothing silently skipped.
+- [ ] Each fact carries a status; failure is a recorded value, not an absence.
+- [ ] The flush runs even if a step throws (`finally`/`trap`); a genuine precondition failure (can't connect at all) still stops hard, outside the per-fact guard.
+- [ ] Dependent facts record their source's outcome; an empty derived set is attributable.
+- [ ] Output is valid parseable JSON — depth sufficient (no silent truncation), quotes/newlines escaped, no BOM, no locale-formatted numbers (decimal comma breaks JSON).
+
+**Before generating code from the pasted-back output, verify:**
+
+- [ ] All expected keys present; `attempted == captured`; no errored fact you're about to build on.
+- [ ] Values match expected shape — version matches a version pattern, counts are integers ≥ 0, expected arrays are arrays.
+- [ ] A value that contradicts your assumption is surfaced; a fact that errored or is empty gets re-probed or asked about — never generate over a hole.
+
+## Stack recipes
+
+Per-stack probe anchors — what to query and how to emit it for SQL, PowerShell, Bash, and Python — live in [RECIPES.md](docs/RECIPES.md). Load the one recipe for the stack in play; keep the probe as small as the question allows.
+
+## Anti-patterns
+
+- **Don't guess then caveat.** Emitting code with "adjust the column names if they differ" is the failure recon exists to kill. Probe first.
+- **Don't over-collect.** Surgical by default; a broad sweep is a conscious baseline exception, not a habit.
+- **Don't cross the data bar casually.** Metadata first; touch data only when the value itself is the fact, and flag it.
+- **Don't bury the result.** One JSON block at the end; progress lives in another stream.
+- **Don't continue silently on a broken probe.** Infra failure stops with a named reason; "not present" is reported, not fatal.
+- **Don't probe what's already known.** If the user stated the fact, or it's visible in context, or it's stack-invariant, skip the probe and proceed.
diff --git a/shared/skills/session/recon/RECIPES.md b/ai-artifacts/skills/shared/session/recon/docs/RECIPES.md
similarity index 100%
rename from shared/skills/session/recon/RECIPES.md
rename to ai-artifacts/skills/shared/session/recon/docs/RECIPES.md
diff --git a/shared/skills/session/write-a-skill/METADATA.md b/ai-artifacts/skills/shared/session/write-a-skill/METADATA.md
similarity index 95%
rename from shared/skills/session/write-a-skill/METADATA.md
rename to ai-artifacts/skills/shared/session/write-a-skill/METADATA.md
index aea051d..e55026f 100644
--- a/shared/skills/session/write-a-skill/METADATA.md
+++ b/ai-artifacts/skills/shared/session/write-a-skill/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/productivity/write-a-skill/SKILL.md
 upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `session`
@@ -19,6 +19,6 @@ upstream-commit: aaf2453fbdfe7a15c07f11d861224f34ab4b53cb
 - Reconciled commit: `aaf2453fbdfe7a15c07f11d861224f34ab4b53cb`
 - Notes: Localized. Known issue: links REFERENCE.md but ships EXAMPLES.md.
 
-# Citations
+## Citations
 
-[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
\ No newline at end of file
+[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/session/write-a-skill/SKILL.md b/ai-artifacts/skills/shared/session/write-a-skill/SKILL.md
similarity index 90%
rename from shared/skills/session/write-a-skill/SKILL.md
rename to ai-artifacts/skills/shared/session/write-a-skill/SKILL.md
index 3f3f440..14d6bd0 100644
--- a/shared/skills/session/write-a-skill/SKILL.md
+++ b/ai-artifacts/skills/shared/session/write-a-skill/SKILL.md
@@ -3,92 +3,93 @@ name: write-a-skill
 version: 1.0.0
 description: Create, update, or improve agent skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, build, revise, update, or improve a skill or SKILL.md file.
 ---
-
-# Writing Skills
-
-## Process
-
-1. **Gather requirements** - ask user about:
-   - What task/domain does the skill cover?
-   - What specific use cases should it handle?
-   - Does it need executable scripts or just instructions?
-   - Any reference materials to include?
-
-2. **Draft the skill** - create:
-   - SKILL.md with concise instructions
-   - Additional reference files if content exceeds 500 lines
-   - Utility scripts if deterministic operations needed
-
-3. **Review with user** - present draft and ask:
-   - Does this cover your use cases?
-   - Anything missing or unclear?
-   - Should any section be more/less detailed?
-
-## Skill Structure
-
-```
-skill-name/
-├── SKILL.md           # Main instructions (required)
-├── REFERENCE.md       # Detailed docs (if needed)
-├── EXAMPLES.md        # Usage examples (if needed)
-└── scripts/           # Utility scripts (if needed)
-    └── helper.js
-```
-
-## SKILL.md Template
-
-```md
----
-name: skill-name
-description: Brief description of capability. Use when [specific triggers].
----
-
-# Skill Name
-
-## Quick start
-
-[Minimal working example]
-
-## Workflows
-
-[Step-by-step processes with checklists for complex tasks]
-
-## Advanced features
-
-[Link to separate files: See [REFERENCE.md](REFERENCE.md)]
-```
-
-## Description Requirements
-
-The description is **the only thing your agent sees** when deciding which skill to load.
-
-**Format**: max 1024 chars, third person. First sentence: what it does. Second sentence: `Use when [triggers]` — include synonym variants (create/write/build, update/revise/improve).
-
-Good: `Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.`
-
-Bad: `Helps with documents.`
-
-## Scripts
-
-If the skill needs bundled executable scripts, see [SCRIPTS.md](SCRIPTS.md)
-for when to add them and how to build them test-first.
-
-## When to Split Files
-
-Split into separate files when:
-
-- SKILL.md exceeds 100 lines
-- Content has distinct domains
-- Advanced features are rarely needed
-
-## Review Checklist
-
-After drafting, verify:
-
-- [ ] Description includes triggers ("Use when...") with synonym variants for create *and* update flows
-- [ ] SKILL.md under 100 lines (including this checklist — count before delivery)
-- [ ] No time-sensitive info
-- [ ] Consistent terminology
-- [ ] At least one complete realistic example exists (inline or in EXAMPLES.md)
-- [ ] Any bundled script was built/updated test-first via the `tdd` skill
-- [ ] References one level deep only
+
+# Writing Skills
+
+## Process
+
+1. **Gather requirements** - ask user about:
+   - What task/domain does the skill cover?
+   - What specific use cases should it handle?
+   - Does it need executable scripts or just instructions?
+   - Any reference materials to include?
+
+2. **Draft the skill** - create:
+   - SKILL.md with concise instructions
+   - Additional reference files if content exceeds 500 lines
+   - Utility scripts if deterministic operations needed
+
+3. **Review with user** - present draft and ask:
+   - Does this cover your use cases?
+   - Anything missing or unclear?
+   - Should any section be more/less detailed?
+
+## Skill Structure
+
+```text
+skill-name/
+├── docs/              # Additional markdown docs (if needed)
+│   ├── REFERENCE.md
+│   └── EXAMPLES.md
+├── SKILL.md           # Main instructions (required)
+└── scripts/           # Utility scripts (if needed)
+    └── helper.js
+```
+
+## SKILL.md Template
+
+```md
+---
+name: skill-name
+description: Brief description of capability. Use when [specific triggers].
+---
+
+# Skill Name
+
+## Quick start
+
+[Minimal working example]
+
+## Workflows
+
+[Step-by-step processes with checklists for complex tasks]
+
+## Advanced features
+
+[Link to separate files: See [REFERENCE.md](docs/REFERENCE.md)]
+```
+
+## Description Requirements
+
+The description is **the only thing your agent sees** when deciding which skill to load.
+
+**Format**: max 1024 chars, third person. First sentence: what it does. Second sentence: `Use when [triggers]` — include synonym variants (create/write/build, update/revise/improve).
+
+Good: `Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction.`
+
+Bad: `Helps with documents.`
+
+## Scripts
+
+If the skill needs bundled executable scripts, see [SCRIPTS.md](docs/SCRIPTS.md)
+for when to add them and how to build them test-first.
+
+## When to Split Files
+
+Split into separate files when:
+
+- SKILL.md exceeds 100 lines
+- Content has distinct domains
+- Advanced features are rarely needed
+
+## Review Checklist
+
+After drafting, verify:
+
+- [ ] Description includes triggers ("Use when...") with synonym variants for create *and* update flows
+- [ ] SKILL.md under 100 lines (including this checklist — count before delivery)
+- [ ] No time-sensitive info
+- [ ] Consistent terminology
+- [ ] At least one complete realistic example exists (inline or in EXAMPLES.md)
+- [ ] Any bundled script was built/updated test-first via the `tdd` skill
+- [ ] References one level deep only
diff --git a/shared/skills/session/write-a-skill/EXAMPLES.md b/ai-artifacts/skills/shared/session/write-a-skill/docs/EXAMPLES.md
similarity index 68%
rename from shared/skills/session/write-a-skill/EXAMPLES.md
rename to ai-artifacts/skills/shared/session/write-a-skill/docs/EXAMPLES.md
index f334496..54aeef0 100644
--- a/shared/skills/session/write-a-skill/EXAMPLES.md
+++ b/ai-artifacts/skills/shared/session/write-a-skill/docs/EXAMPLES.md
@@ -10,7 +10,7 @@ A realistic minimal skill covering a focused domain.
 
 ### File layout
 
-```
+```text
 csv-import/
 ├── SKILL.md
 └── EXAMPLES.md
@@ -57,10 +57,10 @@ description: Parse, validate, and import CSV files into SQL databases or datafra
 
 ### What makes this a good skill
 
-| Property | Value |
-|---|---|
-| Description discriminates | Yes — "CSV", "import", "ingestion", "tabular data" |
-| Update trigger covered | Not applicable (no update flow for this domain) |
-| Line count | 38 — well under 100 |
-| Concrete example | Checklist steps are actionable without guessing |
-| Split decision | EXAMPLES.md added because SQL sample output would push SKILL.md over limit |
+| Property                  | Value                                                                      |
+| ------------------------- | -------------------------------------------------------------------------- |
+| Description discriminates | Yes — "CSV", "import", "ingestion", "tabular data"                         |
+| Update trigger covered    | Not applicable (no update flow for this domain)                            |
+| Line count                | 38 — well under 100                                                        |
+| Concrete example          | Checklist steps are actionable without guessing                            |
+| Split decision            | EXAMPLES.md added because SQL sample output would push SKILL.md over limit |
diff --git a/shared/skills/session/write-a-skill/SCRIPTS.md b/ai-artifacts/skills/shared/session/write-a-skill/docs/SCRIPTS.md
similarity index 100%
rename from shared/skills/session/write-a-skill/SCRIPTS.md
rename to ai-artifacts/skills/shared/session/write-a-skill/docs/SCRIPTS.md
diff --git a/shared/skills/setup/check-skill-updates/METADATA.md b/ai-artifacts/skills/shared/setup/check-skill-updates/METADATA.md
similarity index 94%
rename from shared/skills/setup/check-skill-updates/METADATA.md
rename to ai-artifacts/skills/shared/setup/check-skill-updates/METADATA.md
index 132bf4d..40be5e7 100644
--- a/shared/skills/setup/check-skill-updates/METADATA.md
+++ b/ai-artifacts/skills/shared/setup/check-skill-updates/METADATA.md
@@ -6,9 +6,9 @@ resource: ./SKILL.md
 tags: [setup, skill]
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `setup`
 - Origin: local
-- Notes: Local original; reads skill METADATA.md files for upstream drift checks.
\ No newline at end of file
+- Notes: Local original; reads skill METADATA.md files for upstream drift checks.
diff --git a/shared/skills/setup/check-skill-updates/SKILL.md b/ai-artifacts/skills/shared/setup/check-skill-updates/SKILL.md
similarity index 90%
rename from shared/skills/setup/check-skill-updates/SKILL.md
rename to ai-artifacts/skills/shared/setup/check-skill-updates/SKILL.md
index b4dc6f7..651f4e1 100644
--- a/shared/skills/setup/check-skill-updates/SKILL.md
+++ b/ai-artifacts/skills/shared/setup/check-skill-updates/SKILL.md
@@ -14,8 +14,8 @@ skill — the actual update is triaged and done later (by a human or an agent pi
 item), preserving local customizations under review rather than auto-overwriting.
 
 - No local clone of any upstream is needed, and it works for **any** `upstream-repo`.
-- Source of truth is `shared/skills/<group>/<name>/SKILL.md`; generated mirrors are rebuilt by
-  `scripts/sync-skills.ps1`.
+- Source of truth is `ai-artifacts/skills/shared/<group>/<name>/SKILL.md`; generated mirrors are rebuilt by
+  `scripts/setup-repo.ps1 -SkipHooks`.
 - Skills whose `METADATA.md` has no `upstream-commit` are skipped.
 
 ## Prerequisite — GitHub CLI, authenticated
@@ -33,7 +33,7 @@ changes count, not just `SKILL.md`) and compare to `upstream-commit`.
 $ErrorActionPreference = 'Stop'
 
 $repoRoot   = Resolve-Path (Join-Path $PSScriptRoot '..\..\..')
-$skillsRoot = Join-Path $repoRoot 'shared\skills'
+$skillsRoot = Join-Path $repoRoot 'ai-artifacts\skills\shared'
 
 $results = foreach ($metadata in Get-ChildItem $skillsRoot -Recurse -Filter 'METADATA.md') {
     $content = Get-Content $metadata.FullName -Raw
@@ -92,9 +92,9 @@ Upstream has moved past the commit this skill was last reconciled to.
 ## Action
 
 Review the upstream changes and merge the worthwhile ones into
-`shared/skills/<group>/<name>/SKILL.md` (and resources), preserving local customizations, then bump
-`upstream-commit` in `shared/skills/<group>/<name>/METADATA.md` and re-run
-`scripts/sync-skills.ps1`. See "Appendix: actioning an update" in the check-skill-updates skill for
+`ai-artifacts/skills/shared/<group>/<name>/SKILL.md` (and resources), preserving local customizations, then bump
+`upstream-commit` in `ai-artifacts/skills/shared/<group>/<name>/METADATA.md` and re-run
+`scripts/setup-repo.ps1 -SkipHooks`. See "Appendix: actioning an update" in the check-skill-updates skill for
 the three-way procedure.
 ```
 
@@ -114,14 +114,14 @@ $owner = '<owner>'; $repo = '<repo>'
 $upstreamPath = '<upstream-path>'; $storedCommit = '<stored-commit>'
 
 $baseline    = (& gh api -H 'Accept: application/vnd.github.raw' "repos/$owner/$repo/contents/$upstreamPath`?ref=$storedCommit")
-$installed   = Get-Content '<repo>\shared\skills\<group>\<name>\SKILL.md' -Raw
+$installed   = Get-Content '<repo>\ai-artifacts\skills\shared\<group>\<name>\SKILL.md' -Raw
 $newUpstream = (& gh api -H 'Accept: application/vnd.github.raw' "repos/$owner/$repo/contents/$upstreamPath")
 ```
 
 `$baseline` vs `$installed` = local customizations to keep. `$baseline` vs `$newUpstream` = upstream
 changes to consider. Apply upstream fixes/improvements; keep local substitutions and intentional
 merges; skip conflicting upstream changes and note them. Then bump `upstream-commit` in
-`METADATA.md`, write to the source of truth, and re-run `scripts/sync-skills.ps1`.
+`METADATA.md`, write to the source of truth, and re-run `scripts/setup-repo.ps1 -SkipHooks`.
 
 ## Notes
 
diff --git a/shared/skills/setup/git-guardrails/METADATA.md b/ai-artifacts/skills/shared/setup/git-guardrails/METADATA.md
similarity index 95%
rename from shared/skills/setup/git-guardrails/METADATA.md
rename to ai-artifacts/skills/shared/setup/git-guardrails/METADATA.md
index 4309ec3..6ccb954 100644
--- a/shared/skills/setup/git-guardrails/METADATA.md
+++ b/ai-artifacts/skills/shared/setup/git-guardrails/METADATA.md
@@ -10,7 +10,7 @@ upstream-path: skills/misc/git-guardrails-claude-code/SKILL.md
 upstream-commit: 62f43a18177be6ec82da242e59ffbc490a4c22ea
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `setup`
@@ -19,6 +19,6 @@ upstream-commit: 62f43a18177be6ec82da242e59ffbc490a4c22ea
 - Reconciled commit: `62f43a18177be6ec82da242e59ffbc490a4c22ea`
 - Notes: Localized from the global-prior; Claude-Code-hook skill, not generally useful in chat.
 
-# Citations
+## Citations
 
-[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
\ No newline at end of file
+[1] [https://github.com/mattpocock/skills](https://github.com/mattpocock/skills)
diff --git a/shared/skills/setup/git-guardrails/SKILL.md b/ai-artifacts/skills/shared/setup/git-guardrails/SKILL.md
similarity index 100%
rename from shared/skills/setup/git-guardrails/SKILL.md
rename to ai-artifacts/skills/shared/setup/git-guardrails/SKILL.md
diff --git a/shared/skills/setup/git-guardrails/scripts/block-dangerous-git.ps1 b/ai-artifacts/skills/shared/setup/git-guardrails/scripts/block-dangerous-git.ps1
similarity index 90%
rename from shared/skills/setup/git-guardrails/scripts/block-dangerous-git.ps1
rename to ai-artifacts/skills/shared/setup/git-guardrails/scripts/block-dangerous-git.ps1
index ba082b8..435ea80 100644
--- a/shared/skills/setup/git-guardrails/scripts/block-dangerous-git.ps1
+++ b/ai-artifacts/skills/shared/setup/git-guardrails/scripts/block-dangerous-git.ps1
@@ -1,6 +1,8 @@
+#Requires -Version 5.1
+# RuntimePolicy: dual-runtime
 # PreToolUse hook: block dangerous git commands before Claude Code runs them (PowerShell).
 # Reads the tool-call JSON on stdin; on a dangerous match, writes a message to stderr and exits 2
-# (which Claude Code treats as "blocked"); otherwise exits 0. No pwsh-7-only features — runs on 5.1+.
+# (which Claude Code treats as "blocked"); otherwise exits 0.
 $ErrorActionPreference = 'Stop'
 Set-StrictMode -Version Latest
 
diff --git a/shared/skills/setup/git-guardrails/scripts/block-dangerous-git.sh b/ai-artifacts/skills/shared/setup/git-guardrails/scripts/block-dangerous-git.sh
similarity index 100%
rename from shared/skills/setup/git-guardrails/scripts/block-dangerous-git.sh
rename to ai-artifacts/skills/shared/setup/git-guardrails/scripts/block-dangerous-git.sh
diff --git a/shared/skills/setup/import-upstream-skill/METADATA.md b/ai-artifacts/skills/shared/setup/import-upstream-skill/METADATA.md
similarity index 97%
rename from shared/skills/setup/import-upstream-skill/METADATA.md
rename to ai-artifacts/skills/shared/setup/import-upstream-skill/METADATA.md
index c6087ee..0962236 100644
--- a/shared/skills/setup/import-upstream-skill/METADATA.md
+++ b/ai-artifacts/skills/shared/setup/import-upstream-skill/METADATA.md
@@ -6,7 +6,7 @@ resource: ./SKILL.md
 tags: [setup, skill]
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `setup`
diff --git a/shared/skills/setup/import-upstream-skill/SKILL.md b/ai-artifacts/skills/shared/setup/import-upstream-skill/SKILL.md
similarity index 87%
rename from shared/skills/setup/import-upstream-skill/SKILL.md
rename to ai-artifacts/skills/shared/setup/import-upstream-skill/SKILL.md
index 6b6e42c..84d2d29 100644
--- a/shared/skills/setup/import-upstream-skill/SKILL.md
+++ b/ai-artifacts/skills/shared/setup/import-upstream-skill/SKILL.md
@@ -10,9 +10,9 @@ A repeatable, **source-agnostic** process for bringing an outside skill into thi
 concrete driver was the mattpocock skills repo, but nothing here is specific to it — it works for any
 `upstream-repo` (or a local/global copy with no repo).
 
-The single source of truth is `shared/skills/<group>/<name>/SKILL.md` (+ bundled resources). The
+The single source of truth is `ai-artifacts/skills/shared/<group>/<name>/SKILL.md` (+ bundled resources). The
 `.claude/commands/` copies are a generated mirror — never edit them; rebuild with
-`pwsh scripts/sync-skills.ps1`. This skill **imports and adapts**; the sibling
+`pwsh scripts/setup-repo.ps1 -SkipHooks`. This skill **imports and adapts**; the sibling
 `/setup:check-skill-updates` is what later detects staleness against upstream.
 
 ## Process
@@ -32,7 +32,7 @@ The single source of truth is `shared/skills/<group>/<name>/SKILL.md` (+ bundled
    (conversational/process skills) · `setup` (repo tooling and skill maintenance). Create a new group
    only when none fit — a new group is a deliberate decision, not a default.
 
-3. **Place it** at `shared/skills/<group>/<name>/SKILL.md` with resources alongside. Runtime
+3. **Place it** at `ai-artifacts/skills/shared/<group>/<name>/SKILL.md` with resources alongside. Runtime
    frontmatter should contain only harness-relevant fields plus `version: <semver>`; start new local
    imports at `version: 1.0.0` unless they are explicitly experimental (`0.x.y`). Use `git mv`-style
    care if you are relocating something already tracked.
@@ -70,10 +70,10 @@ The single source of truth is `shared/skills/<group>/<name>/SKILL.md` (+ bundled
 6. **Verify** the result with `/session:write-a-skill` (structure, description triggers, progressive
    disclosure, references one level deep).
 
-7. **Update the origin map** — add a row to [shared/skills/README.md](../../README.md) (skill, group,
+7. **Update the origin map** — add a row to [ai-artifacts/skills/shared/README.md](../../README.md) (skill, group,
    upstream, notes) so the human-readable summary matches `METADATA.md`.
 
-8. **Rebuild the mirror:** `pwsh scripts/sync-skills.ps1`, then confirm `/group:name` resolves. If the
+8. **Rebuild the mirror:** `pwsh scripts/setup-repo.ps1 -SkipHooks`, then confirm `/group:name` resolves. If the
    group is new, add its `/.claude/commands/<group>/` mirror path to `.gitignore`.
 
 ## Checklist
@@ -84,5 +84,5 @@ The single source of truth is `shared/skills/<group>/<name>/SKILL.md` (+ bundled
 - [ ] `METADATA.md` has OKF `type` frontmatter and correct `upstream-*` fields — or fork/local-original rules applied (no dangling `upstream-commit`)
 - [ ] Capability-contract adaptation done; bash → pwsh; intent + local customizations preserved
 - [ ] Verified via `/session:write-a-skill`
-- [ ] `shared/skills/README.md` origin map updated
-- [ ] `scripts/sync-skills.ps1` run; `/group:name` resolves
+- [ ] `ai-artifacts/skills/shared/README.md` origin map updated
+- [ ] `scripts/setup-repo.ps1 -SkipHooks` run; `/group:name` resolves
diff --git a/shared/skills/setup/setup-pre-commit/METADATA.md b/ai-artifacts/skills/shared/setup/setup-pre-commit/METADATA.md
similarity index 88%
rename from shared/skills/setup/setup-pre-commit/METADATA.md
rename to ai-artifacts/skills/shared/setup/setup-pre-commit/METADATA.md
index 0fd87bd..44eb0f8 100644
--- a/shared/skills/setup/setup-pre-commit/METADATA.md
+++ b/ai-artifacts/skills/shared/setup/setup-pre-commit/METADATA.md
@@ -6,9 +6,9 @@ resource: ./SKILL.md
 tags: [setup, skill]
 ---
 
-# Skill Metadata
+## Skill Metadata
 
 - Runtime skill: [SKILL.md](SKILL.md)
 - Group: `setup`
 - Origin: local
-- Notes: Local fork of mattpocock skills/misc/setup-pre-commit. Diverged entirely; no upstream commit is tracked.
\ No newline at end of file
+- Notes: Local fork of mattpocock skills/misc/setup-pre-commit. Diverged entirely; no upstream commit is tracked.
diff --git a/shared/skills/setup/setup-pre-commit/SKILL.md b/ai-artifacts/skills/shared/setup/setup-pre-commit/SKILL.md
similarity index 99%
rename from shared/skills/setup/setup-pre-commit/SKILL.md
rename to ai-artifacts/skills/shared/setup/setup-pre-commit/SKILL.md
index 6fc6a14..a12e7ef 100644
--- a/shared/skills/setup/setup-pre-commit/SKILL.md
+++ b/ai-artifacts/skills/shared/setup/setup-pre-commit/SKILL.md
@@ -201,6 +201,6 @@ This will run through the new hooks — a good smoke test.
 
 - `pre-commit` caches environments; first run per hook is slow, subsequent runs are fast
 - `sqlfluff --fix` is aggressive — review its changes before committing
-- For vale, pick a style pack matching your writing style (`Microsoft`, `Google`, `Vale`) from https://vale.sh/hub/
+- For vale, pick a style pack matching your writing style (`Microsoft`, `Google`, `Vale`) from <https://vale.sh/hub/>
 - To skip hooks temporarily: `git commit --no-verify` (use sparingly)
 - To update all hooks to latest versions: `pre-commit autoupdate`
diff --git a/ai-artifacts/skills/shared/setup/setup-repo/METADATA.md b/ai-artifacts/skills/shared/setup/setup-repo/METADATA.md
new file mode 100644
index 0000000..4ebda20
--- /dev/null
+++ b/ai-artifacts/skills/shared/setup/setup-repo/METADATA.md
@@ -0,0 +1,14 @@
+---
+type: Agent Skill Metadata
+title: "setup-repo"
+description: "Bootstrap this repository after clone by enabling git hooks and syncing generated skill mirrors."
+resource: ./SKILL.md
+tags: [setup, skill]
+---
+
+## Skill Metadata
+
+- Runtime skill: [SKILL.md](SKILL.md)
+- Group: `setup`
+- Origin: local
+- Notes: Local original that combines local hook setup and mirror sync into one bootstrap entrypoint.
diff --git a/ai-artifacts/skills/shared/setup/setup-repo/SKILL.md b/ai-artifacts/skills/shared/setup/setup-repo/SKILL.md
new file mode 100644
index 0000000..ec46f5f
--- /dev/null
+++ b/ai-artifacts/skills/shared/setup/setup-repo/SKILL.md
@@ -0,0 +1,83 @@
+---
+name: setup-repo
+version: 1.0.0
+description: Bootstrap this repository after clone by enabling git hooks and syncing generated skill mirrors. Use when user asks to set up the repo, bootstrap local tooling, or initialize mirrors/hooks for this clone.
+---
+
+# Setup Repo
+
+Bootstraps this clone in one pass:
+
+1. Activates repo git hooks
+2. Syncs generated skill mirrors for Claude, Codex, and Copilot
+
+Implementation layout:
+
+- Canonical entrypoint: `ai-artifacts/skills/shared/setup/setup-repo/scripts/Invoke-SetupRepo.ps1`
+- Repo convenience wrapper: `scripts/setup-repo.ps1`
+
+## Applicability (capability contract)
+
+This skill needs shell + filesystem access in a local git checkout. In chat-only environments,
+provide the exact commands and explain what each command configures.
+
+## Default command
+
+```powershell
+pwsh scripts/setup-repo.ps1
+```
+
+## Common variants
+
+Project-local mirrors for one harness:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -Target Copilot -Scope Project
+```
+
+User-scope mirrors for all harnesses:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -Scope User
+```
+
+Bootstrap only missing generated mirrors (keeps existing generated files untouched):
+
+```powershell
+pwsh scripts/setup-repo.ps1 -IfMissing
+```
+
+Refresh generated mirrors without touching git hooks:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks
+```
+
+Check generated mirrors for drift:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks -Check
+pwsh scripts/setup-repo.ps1 -SkipHooks -Target Codex -Skill tdd -Check
+```
+
+Run only one phase:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -SkipHooks
+pwsh scripts/setup-repo.ps1 -SkipSkillSync
+```
+
+## Verify
+
+```powershell
+git config --get core.hooksPath
+Test-Path .claude/commands
+Test-Path .agents/skills
+Test-Path .github/skills
+pwsh scripts/setup-repo.ps1 -SkipHooks -Check
+```
+
+Expected:
+
+- `core.hooksPath` prints `.githooks`
+- mirror folders exist for selected targets
diff --git a/ai-artifacts/skills/shared/setup/setup-repo/scripts/Invoke-SetupRepo.ps1 b/ai-artifacts/skills/shared/setup/setup-repo/scripts/Invoke-SetupRepo.ps1
new file mode 100644
index 0000000..d1c0f05
--- /dev/null
+++ b/ai-artifacts/skills/shared/setup/setup-repo/scripts/Invoke-SetupRepo.ps1
@@ -0,0 +1,584 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+
+  [ValidateSet('All', 'Claude', 'Codex', 'Copilot')]
+  [string]$Target = 'All',
+
+  [Alias('Scope')]
+  [ValidateSet('Project', 'User')]
+  [string]$MirrorScope = 'Project',
+
+  [string]$Skill = '',
+
+  [switch]$IfMissing,
+  [switch]$Check,
+  [switch]$SkipHooks,
+  [switch]$SkipSkillSync
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if ($Check -and $IfMissing) {
+  throw "-Check is read-only; do not combine it with -IfMissing."
+}
+
+function Get-UserHomePath {
+  if ($env:HOME) { return $env:HOME }
+  if ($env:USERPROFILE) { return $env:USERPROFILE }
+  throw "Cannot resolve user home path from HOME/USERPROFILE."
+}
+
+function Get-RelativePathText {
+  param(
+    [string]$BasePath,
+    [string]$TargetPath
+  )
+
+  $rel = [System.IO.Path]::GetRelativePath($BasePath, $TargetPath)
+  return $rel.TrimStart('\', '/')
+}
+
+function Get-MirrorRootPath {
+  param(
+    [ValidateSet('Claude', 'Codex', 'Copilot')]
+    [string]$TargetName,
+
+    [ValidateSet('Project', 'User')]
+    [string]$ScopeName,
+
+    [string]$ResolvedRepoRoot
+  )
+
+  switch ("$TargetName|$ScopeName") {
+    'Claude|Project' { return (Join-Path $ResolvedRepoRoot '.claude/commands') }
+    'Claude|User' { return (Join-Path (Get-UserHomePath) '.claude/commands') }
+    'Codex|Project' { return (Join-Path $ResolvedRepoRoot '.agents/skills') }
+    'Codex|User' { return (Join-Path (Get-UserHomePath) '.codex/skills') }
+    'Copilot|Project' { return (Join-Path $ResolvedRepoRoot '.github/skills') }
+    'Copilot|User' { return (Join-Path (Get-UserHomePath) '.copilot/skills') }
+    default { throw "Unsupported mirror target/scope combination: $TargetName / $ScopeName" }
+  }
+}
+
+function Get-SkillDirectories {
+  param(
+    [string]$SkillsRoot,
+    [string]$SkillName
+  )
+
+  $dirs = @(Get-ChildItem $SkillsRoot -Recurse -Filter 'SKILL.md' -File | ForEach-Object { $_.Directory })
+  if ($SkillName) {
+    $dirs = @($dirs | Where-Object { $_.Name -eq $SkillName })
+    if ($dirs.Count -eq 0) {
+      throw "No SKILL.md found for skill '$SkillName' under $SkillsRoot"
+    }
+  }
+  if ($dirs.Count -eq 0) {
+    throw "No SKILL.md files found under $SkillsRoot"
+  }
+  return $dirs
+}
+
+function Get-SyncReportEntry {
+  param(
+    [string]$Name,
+    [string]$Detail
+  )
+
+  return [PSCustomObject]@{
+    Name   = $Name
+    Detail = $Detail
+  }
+}
+
+function Write-SyncReport {
+  param(
+    [string]$Flavor,
+    [string]$TargetPath,
+    [object[]]$Entries,
+    [string]$Scope
+  )
+
+  $scopeText = if ($Scope) { " (scope=$Scope)" } else { '' }
+  Write-Output "Synced $Flavor -> $TargetPath$scopeText"
+
+  if (-not $Entries -or @($Entries).Count -eq 0) {
+    return
+  }
+
+  $nameWidth = ($Entries | ForEach-Object { $_.Name.Length } | Measure-Object -Maximum).Maximum
+  if (-not $nameWidth) { $nameWidth = 0 }
+
+  foreach ($entry in $Entries) {
+    Write-Output ("  {0}  {1}" -f $entry.Name.PadRight($nameWidth), $entry.Detail)
+  }
+}
+
+function Get-SkillResources {
+  param([string]$SkillDir)
+
+  return @(Get-ChildItem $SkillDir -Recurse -File |
+      Where-Object { $_.Name -notin @('SKILL.md', 'METADATA.md') })
+}
+
+function Copy-MirroredResources {
+  param(
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetBase
+  )
+
+  foreach ($res in $Resources) {
+    $rel = Get-RelativePathText -BasePath $SourceBase -TargetPath $res.FullName
+    $dest = Join-Path $TargetBase $rel
+    New-Item -ItemType Directory -Path (Split-Path $dest -Parent) -Force | Out-Null
+    Copy-Item $res.FullName $dest -Force
+  }
+}
+
+function Test-MirroredResourcesMatch {
+  param(
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetBase,
+    [switch]$ExcludeTargetSkillFile
+  )
+
+  foreach ($res in $Resources) {
+    $rel = Get-RelativePathText -BasePath $SourceBase -TargetPath $res.FullName
+    $dest = Join-Path $TargetBase $rel
+    if (-not (Test-Path $dest) -or
+      (Get-FileHash $res.FullName).Hash -ne (Get-FileHash $dest).Hash) {
+      return $false
+    }
+  }
+
+  $resourceCount = @($Resources).Count
+  $mirroredCount = if (Test-Path $TargetBase) {
+    @(Get-ChildItem $TargetBase -Recurse -File |
+        Where-Object { -not $ExcludeTargetSkillFile -or $_.Name -ne 'SKILL.md' }).Count
+  }
+  else {
+    0
+  }
+
+  return $mirroredCount -eq $resourceCount
+}
+
+function Get-SkillMirrorState {
+  param(
+    [string]$TargetSkillPath,
+    [string]$ExpectedSkill,
+    [System.IO.FileInfo[]]$Resources,
+    [string]$SourceBase,
+    [string]$TargetResourceBase,
+    [switch]$ExcludeTargetSkillFile
+  )
+
+  if (-not (Test-Path $TargetSkillPath)) { return 'MISSING' }
+  if ((Get-Content $TargetSkillPath -Raw) -cne $ExpectedSkill) { return 'STALE' }
+
+  if (-not (Test-MirroredResourcesMatch -Resources $Resources -SourceBase $SourceBase -TargetBase $TargetResourceBase -ExcludeTargetSkillFile:$ExcludeTargetSkillFile)) {
+    return 'STALE'
+  }
+
+  return 'UP-TO-DATE'
+}
+
+function Convert-ResourceLinks {
+  param(
+    [string]$Body,
+    [string]$Name,
+    [string[]]$ResourceRelPaths
+  )
+
+  foreach ($path in $ResourceRelPaths) {
+    $Body = $Body.Replace("](./$path)", "]($Name/$path)")
+    $Body = $Body.Replace("]($path)", "]($Name/$path)")
+    $Body = $Body -replace ("(?<=@)" + [regex]::Escape($path) + "\b"), "$Name/$path"
+  }
+  return $Body
+}
+
+function ConvertTo-YamlScalar {
+  param([string]$Value)
+
+  if ($null -eq $Value) { return '""' }
+  return '"' + ($Value -replace '\\', '\\' -replace '"', '\"') + '"'
+}
+
+function Get-FrontmatterValue {
+  param(
+    [string]$Document,
+    [string]$Key
+  )
+
+  if ($Document -notmatch "(?s)\A---\r?\n(.*?)\r?\n---\r?\n") { return $null }
+  $frontmatter = $Matches[1]
+  $match = [regex]::Match($frontmatter, "(?m)^$([regex]::Escape($Key)):\s*(.*)$")
+  if (-not $match.Success) { return $null }
+
+  $value = $match.Groups[1].Value.Trim()
+  if (($value.StartsWith('"') -and $value.EndsWith('"')) -or
+    ($value.StartsWith("'") -and $value.EndsWith("'"))) {
+    $value = $value.Substring(1, $value.Length - 2)
+  }
+  return $value
+}
+
+function Get-SkillBody {
+  param([string]$Document)
+
+  if ($Document -match "(?s)\A---\r?\n.*?\r?\n---\r?\n(.*)\z") {
+    return $Matches[1].TrimStart()
+  }
+  return $Document.TrimStart()
+}
+
+function ConvertTo-CodexSkill {
+  param(
+    [string]$SourceDocument,
+    [string]$CodexName,
+    [string]$SourceRelPath
+  )
+
+  $description = Get-FrontmatterValue -Document $SourceDocument -Key 'description'
+  if (-not $description) { $description = "Repo skill mirrored from $SourceRelPath." }
+  $version = Get-FrontmatterValue -Document $SourceDocument -Key 'version'
+
+  $body = Get-SkillBody -Document $SourceDocument
+  $frontmatter = @(
+    '---'
+    "name: $(ConvertTo-YamlScalar $CodexName)"
+    "description: $(ConvertTo-YamlScalar $description)"
+    $(if ($version) { "version: $(ConvertTo-YamlScalar $version)" })
+    '---'
+    ''
+    "<!-- GENERATED from $SourceRelPath. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->"
+    ''
+  ) -join "`n"
+
+  return $frontmatter + $body
+}
+
+function ConvertTo-CopilotSkill {
+  param(
+    [string]$SourceDocument,
+    [string]$SkillName,
+    [string]$SourceRelPath
+  )
+
+  $description = Get-FrontmatterValue -Document $SourceDocument -Key 'description'
+  if (-not $description) { $description = "Repo skill mirrored from $SourceRelPath." }
+  $version = Get-FrontmatterValue -Document $SourceDocument -Key 'version'
+
+  $body = Get-SkillBody -Document $SourceDocument
+  $frontmatter = @(
+    '---'
+    "name: $(ConvertTo-YamlScalar $SkillName)"
+    "description: $(ConvertTo-YamlScalar $description)"
+    $(if ($version) { "version: $(ConvertTo-YamlScalar $version)" })
+    '---'
+    ''
+    "<!-- GENERATED from $SourceRelPath. Edit ai-artifacts/skills/shared and run scripts/setup-repo.ps1. -->"
+    ''
+  ) -join "`n"
+
+  return $frontmatter + $body
+}
+
+function Invoke-InstallGitHooksInternal {
+  param([string]$ResolvedRepoRoot)
+
+  $hooksDir = Join-Path $ResolvedRepoRoot '.githooks'
+  if (Test-Path $hooksDir) {
+    $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
+    Get-ChildItem -Path $hooksDir -File | ForEach-Object {
+      $raw = [System.IO.File]::ReadAllText($_.FullName)
+      $normalized = $raw -replace "`r`n", "`n" -replace "`r", "`n"
+      if ($normalized -ne $raw) {
+        [System.IO.File]::WriteAllText($_.FullName, $normalized, $utf8NoBom)
+        Write-Output "Normalized LF line endings: $($_.Name)"
+      }
+    }
+  }
+
+  Write-Output '== Git hooks =='
+  git config core.hooksPath .githooks
+  Write-Output 'Configured core.hooksPath to .githooks'
+
+  if ($IsLinux -or $IsMacOS) {
+    $preCommit = Join-Path $hooksDir 'pre-commit'
+    if (Test-Path $preCommit) {
+      & chmod +x $preCommit
+    }
+  }
+
+  Write-Output 'Git hooks are now active for this clone.'
+}
+
+function Sync-ClaudeSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck
+  )
+
+  $commandsRoot = Get-MirrorRootPath -TargetName 'Claude' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  Write-Output ''
+  Write-Output '== Claude Code skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $name = $dir.Name
+    $group = $dir.Parent.Name
+    $groupDir = Join-Path $commandsRoot $group
+    $targetMd = Join-Path $groupDir "$name.md"
+    $targetRes = Join-Path $groupDir $name
+
+    if ($OnlyIfMissing -and (Test-Path $targetMd)) {
+      $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+    $resRelPaths = $resources | ForEach-Object {
+      (Get-RelativePathText -BasePath $dir.FullName -TargetPath $_.FullName).Replace('\\', '/')
+    }
+
+    $body = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    if ($resRelPaths) {
+      $body = Convert-ResourceLinks -Body $body -Name $name -ResourceRelPaths $resRelPaths
+    }
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetMd -ExpectedSkill $body -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetRes
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetMd) { Remove-Item $targetMd -Force }
+    if (Test-Path $targetRes) { Remove-Item $targetRes -Recurse -Force }
+    New-Item -ItemType Directory -Path $groupDir -Force | Out-Null
+    Set-Content -Path $targetMd -Value $body -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetRes
+
+    $entries.Add((Get-SyncReportEntry -Name ("/{0}:{1}" -f $group, $name) -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  Write-SyncReport -Flavor 'Claude skills' -TargetPath $commandsRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+function Sync-CodexSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck,
+    [string]$SelectedSkill
+  )
+
+  $agentsRoot = Get-MirrorRootPath -TargetName 'Codex' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $expectedSkillNames = [System.Collections.Generic.HashSet[string]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  if (-not $ReadOnlyCheck -and -not $OnlyIfMissing -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
+    Remove-Item $agentsRoot -Recurse -Force
+  }
+
+  Write-Output ''
+  Write-Output '== Codex skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $sourceName = $dir.Name
+    $group = $dir.Parent.Name
+    $codexName = "$group`_$sourceName"
+    [void]$expectedSkillNames.Add($codexName)
+    $targetDir = Join-Path $agentsRoot $codexName
+    $targetSkill = Join-Path $targetDir 'SKILL.md'
+
+    if ($OnlyIfMissing -and (Test-Path $targetSkill)) {
+      $entries.Add((Get-SyncReportEntry -Name $codexName -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $sourceRelPath = "ai-artifacts/skills/shared/$group/$sourceName/SKILL.md"
+    $sourceDocument = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    $expectedSkill = ConvertTo-CodexSkill -SourceDocument $sourceDocument -CodexName $codexName -SourceRelPath $sourceRelPath
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetSkill -ExpectedSkill $expectedSkill -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetDir -ExcludeTargetSkillFile
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name $codexName -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
+    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+    Set-Content -Path $targetSkill -Value $expectedSkill -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetDir
+
+    $entries.Add((Get-SyncReportEntry -Name $codexName -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  if ($ReadOnlyCheck -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
+    foreach ($dir in Get-ChildItem $agentsRoot -Directory) {
+      if (-not $expectedSkillNames.Contains($dir.Name)) {
+        $driftCount++
+        $entries.Add((Get-SyncReportEntry -Name $dir.Name -Detail 'EXTRA'))
+      }
+    }
+  }
+
+  Write-SyncReport -Flavor 'Codex skills' -TargetPath $agentsRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+function Sync-CopilotSkillsInternal {
+  param(
+    [System.IO.DirectoryInfo[]]$SkillDirs,
+    [string]$ResolvedRepoRoot,
+    [string]$ScopeName,
+    [switch]$OnlyIfMissing,
+    [switch]$ReadOnlyCheck,
+    [string]$SelectedSkill
+  )
+
+  $skillsMirrorRoot = Get-MirrorRootPath -TargetName 'Copilot' -ScopeName $ScopeName -ResolvedRepoRoot $ResolvedRepoRoot
+  $entries = [System.Collections.Generic.List[object]]::new()
+  $expectedSkillNames = [System.Collections.Generic.HashSet[string]]::new()
+  $driftCount = 0
+  $script:LastSyncExitCode = 0
+
+  if (-not $ReadOnlyCheck -and -not $OnlyIfMissing -and -not $SelectedSkill -and (Test-Path $skillsMirrorRoot)) {
+    Remove-Item $skillsMirrorRoot -Recurse -Force
+  }
+
+  Write-Output ''
+  Write-Output '== Copilot skill mirror =='
+
+  foreach ($dir in $SkillDirs) {
+    $sourceName = $dir.Name
+    $group = $dir.Parent.Name
+    $copilotSkillName = "$group`_$sourceName"
+    [void]$expectedSkillNames.Add($copilotSkillName)
+    $targetDir = Join-Path $skillsMirrorRoot $copilotSkillName
+    $targetSkill = Join-Path $targetDir 'SKILL.md'
+
+    if ($OnlyIfMissing -and (Test-Path $targetSkill)) {
+      $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail 'present - skipped (-IfMissing)'))
+      continue
+    }
+
+    $sourceRelPath = "ai-artifacts/skills/shared/$group/$sourceName/SKILL.md"
+    $sourceDocument = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
+    $expectedSkill = ConvertTo-CopilotSkill -SourceDocument $sourceDocument -SkillName $copilotSkillName -SourceRelPath $sourceRelPath
+    $resources = Get-SkillResources -SkillDir $dir.FullName
+
+    if ($ReadOnlyCheck) {
+      $state = Get-SkillMirrorState -TargetSkillPath $targetSkill -ExpectedSkill $expectedSkill -Resources $resources -SourceBase $dir.FullName -TargetResourceBase $targetDir -ExcludeTargetSkillFile
+      if ($state -ne 'UP-TO-DATE') { $driftCount++ }
+      $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail $state))
+      continue
+    }
+
+    if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
+    New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
+    Set-Content -Path $targetSkill -Value $expectedSkill -Encoding utf8 -NoNewline
+    Copy-MirroredResources -Resources $resources -SourceBase $dir.FullName -TargetBase $targetDir
+
+    $entries.Add((Get-SyncReportEntry -Name $copilotSkillName -Detail ("{0,2} resource file(s)" -f @($resources).Count)))
+  }
+
+  if ($ReadOnlyCheck -and -not $SelectedSkill -and (Test-Path $skillsMirrorRoot)) {
+    foreach ($dir in Get-ChildItem $skillsMirrorRoot -Directory) {
+      $skillFile = Join-Path $dir.FullName 'SKILL.md'
+      if (-not (Test-Path $skillFile)) { continue }
+      if ((Get-Content $skillFile -Raw) -notmatch '<!-- GENERATED from ai-artifacts/skills/shared/') {
+        continue
+      }
+      if (-not $expectedSkillNames.Contains($dir.Name)) {
+        $driftCount++
+        $entries.Add((Get-SyncReportEntry -Name $dir.Name -Detail 'EXTRA'))
+      }
+    }
+  }
+
+  Write-SyncReport -Flavor 'Copilot skills' -TargetPath $skillsMirrorRoot -Entries $entries -Scope $ScopeName
+  if ($ReadOnlyCheck -and $driftCount) {
+    $script:LastSyncExitCode = 1
+  }
+}
+
+if ([string]::IsNullOrWhiteSpace($RepoRoot)) {
+  $RepoRoot = (& git -C $PSScriptRoot rev-parse --show-toplevel 2>$null)
+  if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($RepoRoot)) {
+    throw "Unable to determine repo root. Run from inside the repo or pass -RepoRoot."
+  }
+}
+
+$RepoRoot = (Resolve-Path $RepoRoot).Path
+$skillsRoot = Join-Path $RepoRoot 'ai-artifacts/skills/shared'
+$skillDirs = Get-SkillDirectories -SkillsRoot $skillsRoot -SkillName $Skill
+
+if (-not $SkipHooks) {
+  Invoke-InstallGitHooksInternal -ResolvedRepoRoot $RepoRoot
+}
+
+if (-not $SkipSkillSync) {
+  $exitCode = 0
+  switch ($Target) {
+    'All' {
+      Sync-ClaudeSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+      Sync-CodexSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+      Sync-CopilotSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = [Math]::Max($exitCode, $script:LastSyncExitCode)
+    }
+    'Claude' {
+      Sync-ClaudeSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
+      $exitCode = $script:LastSyncExitCode
+    }
+    'Codex' {
+      Sync-CodexSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = $script:LastSyncExitCode
+    }
+    'Copilot' {
+      Sync-CopilotSkillsInternal -SkillDirs $skillDirs -ResolvedRepoRoot $RepoRoot -ScopeName $MirrorScope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check -SelectedSkill $Skill
+      $exitCode = $script:LastSyncExitCode
+    }
+  }
+
+  if ($Check) {
+    if ($exitCode) {
+      Write-Output 'Generated mirrors are stale or missing. Rebuild with: pwsh scripts/setup-repo.ps1 -SkipHooks'
+      exit 1
+    }
+
+    Write-Output 'Generated mirrors are up to date.'
+  }
+}
+
+Write-Output "Repository setup completed."
diff --git a/ai-artifacts/skills/shared/setup/setup-repo/tests/test_setup_repo.py b/ai-artifacts/skills/shared/setup/setup-repo/tests/test_setup_repo.py
new file mode 100644
index 0000000..c2baf49
--- /dev/null
+++ b/ai-artifacts/skills/shared/setup/setup-repo/tests/test_setup_repo.py
@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+SCRIPT_PATH = (
+    Path(__file__).resolve().parent.parent / "scripts" / "Invoke-SetupRepo.ps1"
+)
+
+
+def _pwsh_executable() -> str:
+    pwsh = shutil.which("pwsh")
+    if pwsh:
+        return pwsh
+    pytest.skip("pwsh is required for setup-repo tests")
+
+
+def _run_setup_repo(repo_root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    command = [
+        _pwsh_executable(),
+        "-NoProfile",
+        "-File",
+        str(SCRIPT_PATH),
+        "-RepoRoot",
+        str(repo_root),
+        *args,
+    ]
+    return subprocess.run(
+        command,
+        cwd=repo_root,
+        check=False,
+        text=True,
+        capture_output=True,
+    )
+
+
+def _write_minimal_skill(repo_root: Path, group: str, name: str) -> Path:
+    skill_dir = repo_root / "ai-artifacts" / "skills" / "shared" / group / name
+    skill_dir.mkdir(parents=True, exist_ok=True)
+    (skill_dir / "SKILL.md").write_text(
+        """---
+name: \"setup-repo\"
+description: \"Bootstrap repo\"
+version: \"1.0.0\"
+---
+
+# Setup Repo
+
+Body.
+""",
+        encoding="utf-8",
+    )
+    return skill_dir
+
+
+def _init_git_repo(path: Path) -> None:
+    git = shutil.which("git")
+    if not git:
+        pytest.skip("git is required for hook setup test")
+    subprocess.run([git, "init"], cwd=path, check=True, capture_output=True, text=True)
+
+
+def test_codex_mirror_uses_group_underscore_name(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    result = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks")
+
+    assert result.returncode == 0, result.stderr
+    mirror_root = tmp_path / ".agents" / "skills"
+    assert (mirror_root / "setup_setup-repo" / "SKILL.md").exists()
+    assert not (mirror_root / "setup-setup-repo").exists()
+
+
+def test_copilot_mirror_uses_group_underscore_name(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    result = _run_setup_repo(tmp_path, "-Target", "Copilot", "-SkipHooks")
+
+    assert result.returncode == 0, result.stderr
+    mirror_root = tmp_path / ".github" / "skills"
+    assert (mirror_root / "setup_setup-repo" / "SKILL.md").exists()
+    assert not (mirror_root / "setup-setup-repo").exists()
+
+
+def test_if_missing_preserves_existing_codex_skill_file(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+
+    first = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks")
+    assert first.returncode == 0, first.stderr
+
+    target_skill = tmp_path / ".agents" / "skills" / "setup_setup-repo" / "SKILL.md"
+    target_skill.write_text("sentinel", encoding="utf-8")
+
+    second = _run_setup_repo(tmp_path, "-Target", "Codex", "-SkipHooks", "-IfMissing")
+
+    assert second.returncode == 0, second.stderr
+    assert target_skill.read_text(encoding="utf-8") == "sentinel"
+
+
+def test_hook_setup_configures_git_hooks_path(tmp_path: Path) -> None:
+    _write_minimal_skill(tmp_path, "setup", "setup-repo")
+    _init_git_repo(tmp_path)
+
+    hooks_dir = tmp_path / ".githooks"
+    hooks_dir.mkdir(parents=True, exist_ok=True)
+    (hooks_dir / "pre-commit").write_text(
+        "#!/usr/bin/env sh\r\necho ok\r\n", encoding="utf-8"
+    )
+
+    result = _run_setup_repo(tmp_path, "-SkipSkillSync")
+
+    assert result.returncode == 0, result.stderr
+    git = shutil.which("git")
+    config = subprocess.run(
+        [git, "config", "core.hooksPath"],
+        cwd=tmp_path,
+        check=True,
+        text=True,
+        capture_output=True,
+    )
+    assert config.stdout.strip() == ".githooks"
diff --git a/ai-artifacts/skills/shared/workflow/simulate-workflows/METADATA.md b/ai-artifacts/skills/shared/workflow/simulate-workflows/METADATA.md
new file mode 100644
index 0000000..2d400f2
--- /dev/null
+++ b/ai-artifacts/skills/shared/workflow/simulate-workflows/METADATA.md
@@ -0,0 +1,14 @@
+---
+type: Agent Skill Metadata
+title: "simulate-workflows"
+description: "Run the repository's GitHub quality workflow checks locally in a deterministic sequence with a bundled script, so no push/PR or GitHub Actions minutes are required. Use when user wants to run, simulate, reproduce, create, update, or improve local workflow checks for Python, PowerShell, and repo linting."
+resource: ./SKILL.md
+tags: [workflow, skill]
+---
+
+## Skill Metadata
+
+- Runtime skill: [SKILL.md](SKILL.md)
+- Group: `workflow`
+- Origin: local
+- Notes: Local original; deterministic script-driven local workflow simulation for CI-equivalent checks.
diff --git a/ai-artifacts/skills/shared/workflow/simulate-workflows/SKILL.md b/ai-artifacts/skills/shared/workflow/simulate-workflows/SKILL.md
new file mode 100644
index 0000000..79f6e40
--- /dev/null
+++ b/ai-artifacts/skills/shared/workflow/simulate-workflows/SKILL.md
@@ -0,0 +1,55 @@
+---
+name: simulate-workflows
+version: 1.0.0
+description: Run the repository's GitHub quality workflow checks locally in a deterministic sequence with a bundled script, so no push/PR or GitHub Actions minutes are required. Use when user wants to run, simulate, reproduce, create, update, or improve local workflow checks for Python, PowerShell, and repo linting.
+---
+
+# Simulate Workflows
+
+Run a deterministic local sequence that mirrors this repo's workflow checks for:
+
+- Python quality checks
+- PowerShell quality checks
+- Repo lint checks (YAML/Markdown/JSON)
+- Coding policy validation
+
+Execution model:
+
+- GitHub Actions execution is defined in `.github/workflows/*.yml` and runs shell `run:` blocks there.
+- Local execution is defined in `.github/workflows/scripts/execute-workflow-*.ps1`.
+- Each local `execute-workflow-*` script runs the workflow shell logic in the same order.
+- The simulator orchestrates all workflow executors via `.github/workflows/scripts/execute-all-workflow-scripts.ps1`.
+
+The script is the source of execution order and commands; the agent should invoke it, not reinterpret
+the workflow logic.
+
+## Quick start
+
+From repo root:
+
+```powershell
+pwsh scripts/simulate-workflows.ps1 -InstallTools
+```
+
+Then on later runs (without reinstalling tools each time):
+
+```powershell
+pwsh scripts/simulate-workflows.ps1
+```
+
+To run against a diff range instead of full tracked-file scan:
+
+```powershell
+pwsh scripts/simulate-workflows.ps1 -UseChangedFiles
+```
+
+## Workflow
+
+1. Run the script from the repo root (or pass `-RepoRoot`).
+2. Let the script execute checks in fixed order and fail fast on first error.
+3. Fix findings and rerun until it exits cleanly.
+
+## Capability contract
+
+- If shell/filesystem is available: execute the bundled script directly.
+- If shell is unavailable: provide the exact script path and commands for the user to run manually.
diff --git a/ai-artifacts/skills/shared/workflow/simulate-workflows/scripts/Invoke-LocalWorkflowSimulation.ps1 b/ai-artifacts/skills/shared/workflow/simulate-workflows/scripts/Invoke-LocalWorkflowSimulation.ps1
new file mode 100644
index 0000000..e0b6c32
--- /dev/null
+++ b/ai-artifacts/skills/shared/workflow/simulate-workflows/scripts/Invoke-LocalWorkflowSimulation.ps1
@@ -0,0 +1,126 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+param(
+  [string]$RepoRoot = "",
+  [switch]$InstallTools,
+  [switch]$UseChangedFiles
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$script:WorkflowIndentLevel = 0
+
+function Get-WorkflowIndent {
+  return ('  ' * $script:WorkflowIndentLevel)
+}
+
+function Write-WorkflowLine {
+  param(
+    [AllowEmptyString()]
+    [string]$Text = ''
+  )
+
+  if ([string]::IsNullOrEmpty($Text)) {
+    Write-Output ''
+    return
+  }
+
+  $lines = $Text -split "`r?`n"
+  foreach ($line in $lines) {
+    Write-Output ((Get-WorkflowIndent) + $line)
+  }
+}
+
+function Assert-CommandAvailable {
+  param(
+    [string]$Name,
+    [string]$InstallHint
+  )
+
+  if (-not (Get-Command $Name -ErrorAction SilentlyContinue)) {
+    throw "Required command '$Name' is not available. $InstallHint"
+  }
+}
+
+function Invoke-Step {
+  param(
+    [string]$Name,
+    [scriptblock]$Action
+  )
+
+  Write-WorkflowLine "== $Name =="
+  $script:WorkflowIndentLevel++
+  try {
+    & $Action 2>&1 | ForEach-Object {
+      if ($_ -is [System.Management.Automation.ErrorRecord]) {
+        Write-WorkflowLine ($_.ToString())
+      }
+      else {
+        Write-WorkflowLine ([string]$_)
+      }
+    }
+  }
+  finally {
+    $script:WorkflowIndentLevel--
+  }
+}
+
+if ([string]::IsNullOrWhiteSpace($RepoRoot)) {
+  $RepoRoot = (& git -C $PSScriptRoot rev-parse --show-toplevel 2>$null)
+  if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($RepoRoot)) {
+    throw "Unable to determine repo root. Run from inside the repo or pass -RepoRoot."
+  }
+}
+
+$RepoRoot = (Resolve-Path $RepoRoot).Path
+if (-not (Test-Path (Join-Path $RepoRoot ".git"))) {
+  throw "Repo root is invalid: $RepoRoot"
+}
+
+Assert-CommandAvailable -Name "python" -InstallHint "Install Python 3.11+ and ensure it is on PATH."
+Assert-CommandAvailable -Name "git" -InstallHint "Install Git and ensure it is on PATH."
+
+if ($InstallTools) {
+  Invoke-Step -Name "Install local toolchain" -Action {
+    & python -m pip install --upgrade pip
+    if ($LASTEXITCODE -ne 0) { throw "pip upgrade failed." }
+
+    & python -m pip install pyyaml pytest ruff yamllint
+    if ($LASTEXITCODE -ne 0) { throw "Python tooling install failed." }
+
+    Assert-CommandAvailable -Name "npm" -InstallHint "Install Node.js (npm) to run markdownlint."
+    & npm install -g markdownlint-cli
+    if ($LASTEXITCODE -ne 0) { throw "markdownlint-cli install failed." }
+
+    Set-PSRepository PSGallery -InstallationPolicy Trusted
+    Install-Module PSScriptAnalyzer -Scope CurrentUser -Force
+    Install-Module Pester -Scope CurrentUser -Force -SkipPublisherCheck
+  }
+}
+
+Assert-CommandAvailable -Name "pwsh" -InstallHint "Install PowerShell 7 and ensure it is on PATH."
+
+$runner = Join-Path $RepoRoot ".github/workflows/scripts/execute-all-workflow-scripts.ps1"
+if (-not (Test-Path -LiteralPath $runner -PathType Leaf)) {
+  throw "Missing workflow runner script: $runner"
+}
+
+$runChangedOnly = [bool]$UseChangedFiles
+
+Invoke-Step -Name "Run workflow script executors" -Action {
+  if ($runChangedOnly) {
+    & pwsh $runner -RepoRoot $RepoRoot
+  }
+  else {
+    & pwsh $runner -RepoRoot $RepoRoot -FullScan
+  }
+
+  if ($LASTEXITCODE -ne 0) {
+    Write-WorkflowLine "Local workflow script execution reported issues. Review .temp/Reports/*.txt for details."
+  }
+}
+
+Write-Output "Local workflow simulation finished. Review .temp/Reports/*.txt for per-workflow status and details."
diff --git a/ai-artifacts/skills/shared/workflow/simulate-workflows/tests/test_simulate_workflows.py b/ai-artifacts/skills/shared/workflow/simulate-workflows/tests/test_simulate_workflows.py
new file mode 100644
index 0000000..b4559bd
--- /dev/null
+++ b/ai-artifacts/skills/shared/workflow/simulate-workflows/tests/test_simulate_workflows.py
@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+SCRIPT_PATH = (
+    Path(__file__).resolve().parent.parent
+    / "scripts"
+    / "Invoke-LocalWorkflowSimulation.ps1"
+)
+
+
+def _pwsh_executable() -> str:
+    pwsh = shutil.which("pwsh")
+    if pwsh:
+        return pwsh
+    pytest.skip("pwsh is required for simulate-workflows tests")
+
+
+def _write_cmd(path: Path, body: str) -> None:
+    path.write_text(body, encoding="utf-8")
+
+
+def _prepare_fake_toolchain(tmp_path: Path, log_path: Path) -> Path:
+    bin_dir = tmp_path / "bin"
+    bin_dir.mkdir(parents=True, exist_ok=True)
+
+    _write_cmd(
+        bin_dir / "python.cmd",
+        "@echo off\r\nexit /b 0\r\n",
+    )
+    _write_cmd(
+        bin_dir / "git.cmd",
+        "@echo off\r\nexit /b 0\r\n",
+    )
+
+    return bin_dir
+
+
+def _prepare_repo_root(tmp_path: Path) -> Path:
+    repo_root = tmp_path / "repo"
+    (repo_root / ".git").mkdir(parents=True, exist_ok=True)
+    runner = (
+        repo_root
+        / ".github"
+        / "workflows"
+        / "scripts"
+        / "execute-all-workflow-scripts.ps1"
+    )
+    runner.parent.mkdir(parents=True, exist_ok=True)
+    runner.write_text(
+        "param([string]$RepoRoot, [switch]$FullScan)\n"
+        "$parts = @($PSCommandPath, '-RepoRoot', $RepoRoot)\n"
+        "if ($FullScan) { $parts += '-FullScan' }\n"
+        "$parts -join ' ' | Out-File -FilePath $env:SIM_LOG -Encoding utf8\n",
+        encoding="utf-8",
+    )
+    return repo_root
+
+
+def _run_simulation(
+    repo_root: Path, env: dict[str, str], *args: str
+) -> subprocess.CompletedProcess[str]:
+    command = [
+        _pwsh_executable(),
+        "-NoProfile",
+        "-File",
+        str(SCRIPT_PATH),
+        "-RepoRoot",
+        str(repo_root),
+        *args,
+    ]
+    return subprocess.run(
+        command,
+        check=False,
+        text=True,
+        capture_output=True,
+        env=env,
+    )
+
+
+def test_default_mode_invokes_workflow_runner_with_full_scan(tmp_path: Path) -> None:
+    log_path = tmp_path / "pwsh.log"
+    bin_dir = _prepare_fake_toolchain(tmp_path, log_path)
+    repo_root = _prepare_repo_root(tmp_path)
+
+    env = os.environ.copy()
+    env["SIM_LOG"] = str(log_path)
+    env["PATH"] = str(bin_dir) + os.pathsep + env.get("PATH", "")
+
+    result = _run_simulation(repo_root, env)
+
+    assert result.returncode == 0, result.stderr
+    logged = log_path.read_text(encoding="utf-8")
+    assert (
+        str(
+            repo_root
+            / ".github"
+            / "workflows"
+            / "scripts"
+            / "execute-all-workflow-scripts.ps1"
+        )
+        in logged
+    )
+    assert "-RepoRoot" in logged
+    assert str(repo_root) in logged
+    assert "-FullScan" in logged
+
+
+def test_use_changed_files_omits_full_scan_flag(tmp_path: Path) -> None:
+    log_path = tmp_path / "pwsh.log"
+    bin_dir = _prepare_fake_toolchain(tmp_path, log_path)
+    repo_root = _prepare_repo_root(tmp_path)
+
+    env = os.environ.copy()
+    env["SIM_LOG"] = str(log_path)
+    env["PATH"] = str(bin_dir) + os.pathsep + env.get("PATH", "")
+
+    result = _run_simulation(repo_root, env, "-UseChangedFiles")
+
+    assert result.returncode == 0, result.stderr
+    logged = log_path.read_text(encoding="utf-8")
+    assert (
+        str(
+            repo_root
+            / ".github"
+            / "workflows"
+            / "scripts"
+            / "execute-all-workflow-scripts.ps1"
+        )
+        in logged
+    )
+    assert "-RepoRoot" in logged
+    assert str(repo_root) in logged
+    assert "-FullScan" not in logged
diff --git a/coding-policies/languages/powershell-policy.yaml b/coding-policies/languages/powershell-policy.yaml
index 26b1bdf..18547ef 100644
--- a/coding-policies/languages/powershell-policy.yaml
+++ b/coding-policies/languages/powershell-policy.yaml
@@ -7,6 +7,22 @@ POWERSHELL_POLICY:
       type: tdd
       rule: "When testing scripts, assert Output stream behavior separately from Warning/Verbose/Error streams."
       rationale: "PowerShell streams are semantically distinct and should be validated independently."
+    - id: runtime-policy-classification
+      type: runtime
+      rule: "Every PowerShell script must declare one runtime policy header: '# RuntimePolicy: core-first|dual-runtime|desktop-only'."
+      rationale: "Runtime intent is explicit, reviewable, and enforceable in CI."
+    - id: core-first-default
+      type: runtime
+      rule: "Core-first scripts must declare '#Requires -Version 7.0' (or higher) and '#Requires -PSEdition Core'."
+      rationale: "Default runtime is pwsh Core 7+ for Linux/macOS compatibility."
+    - id: dual-runtime-compat
+      type: runtime
+      rule: "Dual-runtime scripts must remain compatible with both Windows PowerShell 5.1 and pwsh 7+, and must not declare '#Requires -PSEdition'."
+      rationale: "Edition pinning blocks one runtime and defeats dual compatibility."
+    - id: desktop-only-exception
+      type: runtime
+      rule: "Desktop-only scripts are exceptions: name them '*-windowsps.ps1', add '# RuntimeJustification: ...', and require '#Requires -Version 5.1' + '#Requires -PSEdition Desktop'."
+      rationale: "Windows-only behavior remains explicit, justified, and auditable."
 
   FORBIDDEN:
     - id: no_format_table_logic
diff --git a/docs/harnesses/claude-code.md b/docs/harnesses/claude-code.md
index 1261591..c1e56c1 100644
--- a/docs/harnesses/claude-code.md
+++ b/docs/harnesses/claude-code.md
@@ -26,7 +26,7 @@ Within instruction files, more-specific path wins. Managed > project > user for
 ## 2. Storage split
 
 - **Repo-scoped (committed):** `CLAUDE.md`, `AGENTS.md`, `.claude/settings.json`,
-  `shared/skills/<group>/<name>/`, `.mcp.json`
+  `ai-artifacts/skills/shared/<group>/<name>/`, `.mcp.json`
 - **Machine-local (gitignored):** `CLAUDE.local.md`, `.claude/settings.local.json`,
   `~/.claude/projects/<project>/memory/` (auto-memory)
 - **User-global (all repos):** `~/.claude/CLAUDE.md`, `~/.claude/settings.json`,
@@ -56,7 +56,7 @@ Within instruction files, more-specific path wins. Managed > project > user for
 | Subagents                                          | **Native** — `agents/*.md`                                                                              |
 | Hooks                                              | **Native** — `settings.json` (`PreToolUse`, `PostToolUse`, `SessionStart`, etc.)                        |
 | MCP servers                                        | **Native** — `.mcp.json` (project), `~/.claude.json` (global), Desktop `claude_desktop_config.json`     |
-| Output styles                                      | **Native** — `output-styles/` (referenced in settings)                                                  |
+| Output styles                                      | **Native** — `ai-artifacts/output-styles/` (referenced in settings)                                     |
 | Settings / permissions                             | **Native** — `settings.json` / `settings.local.json`                                                    |
 | Plugins / bundles                                  | **Native** — `.claude-plugin/plugin.json` wrapping skills/agents/hooks/mcp                              |
 
@@ -147,8 +147,8 @@ is loaded every turn and competes with code for context budget — keep it conci
    the first heading of each." Pass: names the repo-root `AGENTS.md` and any present `CLAUDE.md`
    tiers with real content. Fail: invents files or misses `AGENTS.md`.
 2. **Skill invocation check** — Run `/planning:scratch` with no arguments. Pass: the ranked table
-   from `.scratch/BACKLOG.md` is displayed (command body + resources resolved from the mirror).
-   Fail: skill unknown → mirror missing; run `pwsh scripts/sync-skills.ps1`.
+  from `.scratch/BACKLOG.md` is displayed (command body + resources resolved from the mirror).
+  Fail: skill unknown → mirror missing; run `pwsh scripts/setup-repo.ps1 -SkipHooks`.
 3. **Hook check** — Start a new session on a machine with the SessionStart hook configured in
    `.claude/settings.local.json`. Pass: the "Synced skills → …" hook output appears at session
    start. Fail: no output → hook not installed on this machine or script error (`--debug` for logs).
diff --git a/docs/harnesses/codex.md b/docs/harnesses/codex.md
index 570dc15..0453651 100644
--- a/docs/harnesses/codex.md
+++ b/docs/harnesses/codex.md
@@ -32,10 +32,11 @@ For repo-specific working conventions, `AGENTS.md` is the active project contrac
 ## 2. Storage split
 
 - **Repo-scoped (committed):** `AGENTS.md`, `docs/harnesses/*.md`, shared skills under
-  `shared/skills/`, repo scripts, and any future Codex-specific repo config under `openai/codex/`
-  if added.
-- **Repo-scoped generated (gitignored):** `.agents/skills/`, rebuilt from `shared/skills/` by
-  `pwsh scripts/sync-skills.ps1`.
+  `ai-artifacts/skills/shared/`, repo scripts, and any future Codex-specific repo config under
+  `ai-artifacts/mcp-config/openai/codex/`, `ai-artifacts/plugins/openai/codex/`, or instruction
+  files under `ai-artifacts/instructions/openai/codex/` if added.
+- **Repo-scoped generated (gitignored):** `.agents/skills/`, rebuilt from `ai-artifacts/skills/shared/` by
+  `pwsh scripts/setup-repo.ps1 -SkipHooks`.
 - **Machine-local:** Codex home and plugin/skill caches under the user's profile, local approval
   state, local settings, and sandbox/session metadata. These are not committed to this repo.
 - **User-global:** account/session-level Codex instructions, installed skills/plugins/connectors,
@@ -45,16 +46,14 @@ For repo-specific working conventions, `AGENTS.md` is the active project contrac
 
 ## 3. Disk locations
 
-| Tier                             | Windows                                                  | macOS / Linux                               |
-| -------------------------------- | -------------------------------------------------------- | ------------------------------------------- |
-| Repo root                        | `C:\GIT\DenWin\ai-lab` in this session                   | `<repo>`                                    |
-| Repo instruction file            | `<repo>\AGENTS.md`                                       | `<repo>/AGENTS.md`                          |
-| Repo Codex skill mirror          | `<repo>\.agents\skills\`                                 | `<repo>/.agents/skills/`                    |
-| Suggested Codex repo config home | `<repo>\openai\codex\` if needed                         | `<repo>/openai/codex/` if needed            |
-| User Codex home                  | `%USERPROFILE%\.codex\` observed from skill/plugin paths | `~/.codex/` presumed (`?`)                  |
-| User skills                      | `%USERPROFILE%\.codex\skills\` observed                  | `~/.codex/skills/` presumed (`?`)           |
-| Plugin cache                     | `%USERPROFILE%\.codex\plugins\cache\` observed           | `~/.codex/plugins/cache/` presumed (`?`)    |
-| Temporary writable area          | harness-provided temp directory (`:tmpdir`)              | harness-provided temp directory (`:tmpdir`) |
+- Repo root: Windows `C:\GIT\DenWin\ai-lab` in this session; macOS / Linux `<repo>`
+- Repo instruction file: Windows `<repo>\AGENTS.md`; macOS / Linux `<repo>/AGENTS.md`
+- Repo Codex skill mirror: Windows `<repo>\.agents\skills\`; macOS / Linux `<repo>/.agents/skills/`
+- Suggested Codex repo config home: Windows `<repo>\ai-artifacts\mcp-config\openai\codex\` if needed; macOS / Linux `<repo>/ai-artifacts/mcp-config/openai/codex/` if needed
+- User Codex home: Windows `%USERPROFILE%\.codex\` observed from skill/plugin paths; macOS / Linux `~/.codex/` presumed (`?`)
+- User skills: Windows `%USERPROFILE%\.codex\skills\` observed; macOS / Linux `~/.codex/skills/` presumed (`?`)
+- Plugin cache: Windows `%USERPROFILE%\.codex\plugins\cache\` observed; macOS / Linux `~/.codex/plugins/cache/` presumed (`?`)
+- Temporary writable area: harness-provided temp directory (`:tmpdir`) on both platforms
 
 Exact Codex settings filenames and all OS-specific config paths are `?` unless observed in a live
 session or documented by the active runtime.
@@ -64,7 +63,7 @@ session or documented by the active runtime.
 | Artifact type                                       | Support                                                                                         |
 | --------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
 | Instruction docs (`AGENTS.md`, custom instructions) | **Native** — root `AGENTS.md` is supplied as repo instructions                                  |
-| Skills / slash commands                             | **Native** — repo skills are mirrored to `.agents/skills/<group>-<name>/SKILL.md`               |
+| Skills / slash commands                             | **Native** — repo skills are mirrored to `.agents/skills/<group>_<name>/SKILL.md`               |
 | Subagents                                           | **Native / optional** — multi-agent tools may be available through deferred tool discovery      |
 | Hooks                                               | **Unsupported / ?** — no Codex lifecycle hook surface is visible in this session                |
 | MCP servers                                         | **Native / optional** — MCP resources/tools and app connectors may be available when configured |
@@ -98,19 +97,32 @@ session or documented by the active runtime.
 | ----------------------------- | ------------------------------------------------------------------------------------------------------------- |
 | System/developer instructions | Auto, every turn                                                                                              |
 | `AGENTS.md`                   | Auto-supplied for the workspace/session                                                                       |
-| Skills                        | Description-match or explicit user mention; mirrored `.agents/skills/<group>-<name>/SKILL.md` read before use |
+| Skills                        | Description-match or explicit user mention; mirrored `.agents/skills/<group>_<name>/SKILL.md` read before use |
 | Shell/filesystem tools        | Model-invoked, subject to sandbox and approval policy                                                         |
 | MCP resources/tools           | On-demand when configured and exposed                                                                         |
 | Plugins/connectors            | Available through installed capabilities or deferred tool discovery                                           |
 | Web browsing                  | On-demand, subject to browsing policy and network/tool availability                                           |
 
+There is no verified Codex-native equivalent to Claude Code's `hooks.SessionStart`. In this repo,
+the closest automatic bootstrap is the VS Code folder-open task in `.vscode/tasks.json`, which runs:
+
+```powershell
+pwsh -NoProfile -File .github/skills/setup_setup-repo/scripts/Invoke-SetupRepo.ps1 -IfMissing
+```
+
+For a non-circular fresh-clone bootstrap, prefer the source wrapper:
+
+```powershell
+pwsh scripts/setup-repo.ps1 -IfMissing
+```
+
 Context behavior observed from this session:
 
 - The active conversation, system/developer instructions, repo instructions, and tool results share
   the context budget.
 - A context compaction mechanism may summarize older conversation state when needed.
 - Skill files are not assumed to be fully loaded until selected; when selected, the relevant
-  `.agents/skills/<group>-<name>/SKILL.md` must be read before task actions.
+  `.agents/skills/<group>_<name>/SKILL.md` must be read before task actions.
 - File contents are not automatically re-read after edits unless the model uses filesystem tools.
 - Exact context window size, truncation thresholds, and prefix-caching behavior are `?`.
 
@@ -118,8 +130,8 @@ Context behavior observed from this session:
 
 - Ask the model which repo instructions are active and compare against `AGENTS.md`.
 - Read `AGENTS.md` directly with filesystem tools and verify behavior follows it.
-- For skills, run `pwsh scripts/sync-skills.ps1 -Target Codex -Check` and check that the selected
-  `.agents/skills/<group>-<name>/SKILL.md` was read before task actions.
+- For skills, run `pwsh scripts/setup-repo.ps1 -SkipHooks -Target Codex -Check` and check that the selected
+  `.agents/skills/<group>_<name>/SKILL.md` was read before task actions.
 - For shell/tool access, run a harmless command such as `Get-Content AGENTS.md` or `rg --files`.
 - For sandbox behavior, attempt an operation that should require approval and confirm the harness
   requests escalation rather than silently bypassing policy.
@@ -183,11 +195,11 @@ Codex workflow invocation patterns:
 - **Plain chat request:** primary interface. Arguments are natural-language task details, file paths,
   constraints, and follow-up corrections.
 - **Skill mention:** user names a skill or the task matches a skill description. The model reads the
-  mirrored `.agents/skills/<group>-<name>/SKILL.md` file and follows it for that turn.
+  mirrored `.agents/skills/<group>_<name>/SKILL.md` file and follows it for that turn.
 - **Tool calls:** arguments are structured by each tool schema, for example shell command, working
   directory, timeout, and escalation request.
 - **Plugin/app connectors:** discovered tools expose their own schemas when installed.
-- **Repo scripts:** invoked through shell tools, for example `pwsh scripts/sync-skills.ps1`.
+- **Repo scripts:** invoked through shell tools, for example `pwsh scripts/setup-repo.ps1 -SkipHooks`.
 
 Fallback pattern when no native command system exists: write a short prompt template with explicit
 placeholders, have the user fill it in chat, then treat the filled prompt as the workflow invocation.
@@ -267,8 +279,8 @@ Operational expectations:
 ## 16. Operational edge cases
 
 - **Generated vs source artifacts:** In this repo, `.claude/commands/` and `.agents/skills/` are
-  generated mirrors. Edit `shared/skills/<group>/<name>/`, then rebuild with
-  `pwsh scripts/sync-skills.ps1`; never edit the mirrors directly.
+  generated mirrors. Edit `ai-artifacts/skills/shared/<group>/<name>/`, then rebuild with
+  `pwsh scripts/setup-repo.ps1 -SkipHooks`; never edit the mirrors directly.
 - **Bootstrap requirements:** A fresh clone or sandbox may not have generated mirrors or local
   harness settings. Use repo scripts and docs to materialize generated state instead of inventing it.
 - **Persistence:** Files written under the repo persist in the working tree. Conversation context,
@@ -299,8 +311,9 @@ Operational expectations:
 | Hooks                               | No verified Codex equivalent                          | Use scripts, CI, or harness-specific automation elsewhere                 |
 | Plugins/connectors                  | Harness-specific packaging                            | Underlying tools may map to MCP or app connectors                         |
 
-**Design principle:** keep shared repo facts in `AGENTS.md`; keep Codex-specific behavior in a
-future `openai/codex/` subtree only when it cannot be expressed portably.
+**Design principle:** keep shared repo facts in `AGENTS.md`; keep Codex-specific behavior in
+`ai-artifacts/instructions/openai/codex/`, `ai-artifacts/mcp-config/openai/codex/`, or
+`ai-artifacts/plugins/openai/codex/` only when it cannot be expressed portably.
 
 ---
 
diff --git a/docs/harnesses/copilot-cli.md b/docs/harnesses/copilot-cli.md
index 10eafb4..9d84247 100644
--- a/docs/harnesses/copilot-cli.md
+++ b/docs/harnesses/copilot-cli.md
@@ -41,34 +41,34 @@ Precedence: platform rules > repo instructions > user messages. The `custom_inst
 
 ## 3. Disk locations
 
-| Tier                    | Windows                                                                          | macOS / Linux                                                     |
-| ----------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
-| Repo main checkout      | `%USERPROFILE%\.copilot\repos\<owner-repo>\`                                     | `~/.copilot/repos/<owner-repo>/`                                  |
-| Session worktree        | `%USERPROFILE%\.copilot\repos\copilot-worktrees\<owner-repo>\<branch>\`         | `~/.copilot/repos/copilot-worktrees/<owner-repo>/<branch>/`      |
-| Session state folder    | `%USERPROFILE%\.copilot\session-state\<session-id>\`                            | `~/.copilot/session-state/<session-id>/`                          |
-| Session artifacts       | `%USERPROFILE%\.copilot\session-state\<session-id>\files\`                      | `~/.copilot/session-state/<session-id>/files/`                    |
-| Repo instructions       | `<repo>\.github\copilot-instructions.md`                                        | `<repo>/.github/copilot-instructions.md`                         |
-| Cross-harness contract  | `<repo>\AGENTS.md`                                                               | `<repo>/AGENTS.md`                                               |
-| Project extensions      | `<repo>\.github\extensions\`                                                    | `<repo>/.github/extensions/`                                     |
-| Project prompt files    | `<repo>\.github\prompts\*.prompt.md`                                            | `<repo>/.github/prompts/*.prompt.md`                             |
-| User-scope extensions   | `?` (not exposed in-session)                                                    | `?`                                                               |
-| App settings / config   | managed by Copilot CLI app — path `?`                                           | `?`                                                               |
+| Tier                   | Windows                                                                 | macOS / Linux                                               |
+| ---------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------- |
+| Repo main checkout     | `%USERPROFILE%\.copilot\repos\<owner-repo>\`                            | `~/.copilot/repos/<owner-repo>/`                            |
+| Session worktree       | `%USERPROFILE%\.copilot\repos\copilot-worktrees\<owner-repo>\<branch>\` | `~/.copilot/repos/copilot-worktrees/<owner-repo>/<branch>/` |
+| Session state folder   | `%USERPROFILE%\.copilot\session-state\<session-id>\`                    | `~/.copilot/session-state/<session-id>/`                    |
+| Session artifacts      | `%USERPROFILE%\.copilot\session-state\<session-id>\files\`              | `~/.copilot/session-state/<session-id>/files/`              |
+| Repo instructions      | `<repo>\.github\copilot-instructions.md`                                | `<repo>/.github/copilot-instructions.md`                    |
+| Cross-harness contract | `<repo>\AGENTS.md`                                                      | `<repo>/AGENTS.md`                                          |
+| Project extensions     | `<repo>\.github\extensions\`                                            | `<repo>/.github/extensions/`                                |
+| Project prompt files   | `<repo>\.github\prompts\*.prompt.md`                                    | `<repo>/.github/prompts/*.prompt.md`                        |
+| User-scope extensions  | `?` (not exposed in-session)                                            | `?`                                                         |
+| App settings / config  | managed by Copilot CLI app — path `?`                                   | `?`                                                         |
 
 ## 4. Artifact mapping
 
-| Artifact type                  | Support                 | Notes                                                                                    |
-| ------------------------------ | ----------------------- | ---------------------------------------------------------------------------------------- |
-| Instruction docs               | **Native**              | `.github/copilot-instructions.md` + `AGENTS.md`; auto-loaded every session              |
-| Skills / slash commands        | **Emulated**            | No dedicated skill format; represented via extensions (tools) or prompt files            |
-| Subagents                      | **Native**              | `task` tool spawns typed sub-agents (explore, task, general-purpose, code-review, etc.) |
-| Hooks                          | **Partial / Emulated**  | No declarative hook config; lifecycle events handled by extensions + app runtime         |
-| MCP servers                    | **Native**              | Configured via workspace or user settings; protocol is cross-vendor                      |
-| Canvas panels                  | **Native** (unique)     | Interactive side panels (editor, browser, terminal); opened by agent or user             |
-| Output styles                  | **Emulated**            | Style contracts in instruction files; no native style primitive                          |
-| Settings / permissions         | **Native**              | App settings + extension `allow/deny` lists                                              |
-| Plugins / bundles              | **Native** (extensions) | `.github/extensions/*.{js,ts,yml}` contribute tools / canvases to the session           |
-| Scheduled workflows            | **Native**              | Built-in workflow scheduler (manual / hourly / daily / weekly / CRON)                   |
-| Session store / history        | **Native**              | Per-session SQLite (`sql` tool); cross-session DuckDB history (`session_store_sql` tool) |
+| Artifact type           | Support                 | Notes                                                                                    |
+| ----------------------- | ----------------------- | ---------------------------------------------------------------------------------------- |
+| Instruction docs        | **Native**              | `.github/copilot-instructions.md` + `AGENTS.md`; auto-loaded every session               |
+| Skills / slash commands | **Emulated**            | No dedicated skill format; represented via extensions (tools) or prompt files            |
+| Subagents               | **Native**              | `task` tool spawns typed sub-agents (explore, task, general-purpose, code-review, etc.)  |
+| Hooks                   | **Partial / Emulated**  | No declarative hook config; lifecycle events handled by extensions + app runtime         |
+| MCP servers             | **Native**              | Configured via workspace or user settings; protocol is cross-vendor                      |
+| Canvas panels           | **Native** (unique)     | Interactive side panels (editor, browser, terminal); opened by agent or user             |
+| Output styles           | **Emulated**            | Style contracts in instruction files; no native style primitive                          |
+| Settings / permissions  | **Native**              | App settings + extension `allow/deny` lists                                              |
+| Plugins / bundles       | **Native** (extensions) | `.github/extensions/*.{js,ts,yml}` contribute tools / canvases to the session            |
+| Scheduled workflows     | **Native**              | Built-in workflow scheduler (manual / hourly / daily / weekly / CRON)                    |
+| Session store / history | **Native**              | Per-session SQLite (`sql` tool); cross-session DuckDB history (`session_store_sql` tool) |
 
 ## 5. Cross-compatibility
 
@@ -93,15 +93,15 @@ Precedence: platform rules > repo instructions > user messages. The `custom_inst
 
 ## 7. Activation + load model
 
-| Surface                           | Load model                                                                            |
-| --------------------------------- | ------------------------------------------------------------------------------------- |
-| `.github/copilot-instructions.md` | Auto, every session turn (injected as `custom_instruction`)                           |
-| `AGENTS.md`                       | Auto, every session turn (base instruction layer)                                     |
-| Extensions                        | Loaded at app / session start; tools contributed are available for the full session   |
-| MCP servers                       | On-demand tool calls (not loaded into context text)                                   |
-| Canvas                            | Opened explicitly by agent (`open_canvas`) or user; persists as a side panel         |
-| Scheduled workflows               | Time-triggered or manual; spawn a new session with a configured prompt and mode       |
-| Sub-agents (task tool)            | Spawned on demand; background agents notify on completion                             |
+| Surface                           | Load model                                                                               |
+| --------------------------------- | ---------------------------------------------------------------------------------------- |
+| `.github/copilot-instructions.md` | Auto, every session turn (injected as `custom_instruction`)                              |
+| `AGENTS.md`                       | Auto, every session turn (base instruction layer)                                        |
+| Extensions                        | Loaded at app / session start; tools contributed are available for the full session      |
+| MCP servers                       | On-demand tool calls (not loaded into context text)                                      |
+| Canvas                            | Opened explicitly by agent (`open_canvas`) or user; persists as a side panel             |
+| Scheduled workflows               | Time-triggered or manual; spawn a new session with a configured prompt and mode          |
+| Sub-agents (task tool)            | Spawned on demand; background agents notify on completion                                |
 | Prompt files (`.prompt.md`)       | User-invoked (`/filename` pattern from VS Code Copilot; not natively slash-invoked here) |
 
 Instructions are **not** cached across sessions — each session starts fresh from disk.
@@ -132,9 +132,8 @@ window; keep `.github/copilot-instructions.md` and `AGENTS.md` concise.
 
 ## 10. Capability limits / notable absences
 
-- No native skill format — skills from `shared/skills/` are not auto-mirrored to a
-  Copilot CLI-specific directory (the sync script targets `.claude/commands/` and
-  `.agents/skills/` only); expose skills via extensions or prompt files
+- Skills can be loaded from skill directories (Copilot SDK `skillDirectories`), where each immediate
+  subdirectory contains `SKILL.md`. This repo mirrors to `.github/skills/<group>_<name>/SKILL.md`.
 - No declarative hook system comparable to Claude Code's `settings.json` hooks
 - No path-scoped instruction activation (`applyTo`) — all instructions apply session-wide
 - No persistent cross-session memory built into the harness (relies on session state files
@@ -149,18 +148,18 @@ window; keep `.github/copilot-instructions.md` and `AGENTS.md` concise.
 - **Harness/App:** Copilot CLI 1.0.69-0
 - **Session model:** Claude Sonnet 4.6 (multi-model; observed model at time of writing)
 
-| Section                              | Confidence | Why                                                                                                      |
-| ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------- |
-| 1. Instruction surfaces + precedence | high       | Load model visible in-session via `custom_instruction` injection; additive layer confirmed               |
-| 2. Storage split                     | high       | Session state and worktree paths are directly observable in the session context                          |
-| 3. Disk locations                    | medium     | Worktree and session paths confirmed from live context; user-scope extension path is `?`                 |
-| 4. Artifact mapping                  | high       | All tool categories exercised in this repo's sessions                                                    |
-| 5. Cross-compatibility               | high       | `AGENTS.md` and `.github/copilot-instructions.md` auto-load confirmed in-session                        |
-| 6. Composition mechanics             | medium     | Additive layering observed; exact precedence for instruction-level conflicts not systematically tested    |
-| 7. Activation + load model           | high       | Extension, MCP, canvas, and workflow load patterns all observed in-session                               |
-| 8. Validation                        | high       | Commands verified in live sessions (`extensions_manage`, `list_workflows`, etc.)                         |
-| 9. Security / secrets boundary       | high       | Follows repo-public constraint and standard env-var injection patterns                                   |
-| 10. Capability limits                | medium     | Known absences confirmed; some edge cases (cloud sessions, extension API limits) not fully tested        |
+| Section                              | Confidence | Why                                                                                                    |
+| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------ |
+| 1. Instruction surfaces + precedence | high       | Load model visible in-session via `custom_instruction` injection; additive layer confirmed             |
+| 2. Storage split                     | high       | Session state and worktree paths are directly observable in the session context                        |
+| 3. Disk locations                    | medium     | Worktree and session paths confirmed from live context; user-scope extension path is `?`               |
+| 4. Artifact mapping                  | high       | All tool categories exercised in this repo's sessions                                                  |
+| 5. Cross-compatibility               | high       | `AGENTS.md` and `.github/copilot-instructions.md` auto-load confirmed in-session                       |
+| 6. Composition mechanics             | medium     | Additive layering observed; exact precedence for instruction-level conflicts not systematically tested |
+| 7. Activation + load model           | high       | Extension, MCP, canvas, and workflow load patterns all observed in-session                             |
+| 8. Validation                        | high       | Commands verified in live sessions (`extensions_manage`, `list_workflows`, etc.)                       |
+| 9. Security / secrets boundary       | high       | Follows repo-public constraint and standard env-var injection patterns                                 |
+| 10. Capability limits                | medium     | Known absences confirmed; some edge cases (cloud sessions, extension API limits) not fully tested      |
 
 ## 12. Command + argument mapping
 
@@ -184,16 +183,16 @@ Fallback when no native command invocation exists:
 
 ## 13. Capability contract
 
-| Capability                        | Contract    | Notes                                                                           |
-| --------------------------------- | ----------- | ------------------------------------------------------------------------------- |
-| Filesystem read                   | required    | Core to codebase grounding; always available                                    |
-| Filesystem write                  | required    | Needed for code edits; always available                                         |
-| Shell / terminal execution        | required    | `powershell` tool; always available in local sessions                           |
-| Network access                    | optional    | `web_fetch` for URL retrieval; `gh` CLI for GitHub API                          |
-| External tool calls (MCP/plugins) | optional    | Available when extensions or MCP servers are configured                         |
-| Sub-agents                        | optional    | `task` tool for delegation; requires compatible model and agent type            |
-| Canvas panels                     | optional    | Available in the desktop app; degrade to text output in headless/API contexts   |
-| Background / scheduled tasks      | optional    | Workflows for scheduled; background agents for async within a session           |
+| Capability                        | Contract | Notes                                                                         |
+| --------------------------------- | -------- | ----------------------------------------------------------------------------- |
+| Filesystem read                   | required | Core to codebase grounding; always available                                  |
+| Filesystem write                  | required | Needed for code edits; always available                                       |
+| Shell / terminal execution        | required | `powershell` tool; always available in local sessions                         |
+| Network access                    | optional | `web_fetch` for URL retrieval; `gh` CLI for GitHub API                        |
+| External tool calls (MCP/plugins) | optional | Available when extensions or MCP servers are configured                       |
+| Sub-agents                        | optional | `task` tool for delegation; requires compatible model and agent type          |
+| Canvas panels                     | optional | Available in the desktop app; degrade to text output in headless/API contexts |
+| Background / scheduled tasks      | optional | Workflows for scheduled; background agents for async within a session         |
 
 Degradation rule: if an optional capability is missing, continue with the nearest equivalent
 (e.g., text output instead of canvas; inline shell command instructions if terminal is blocked).
@@ -224,6 +223,7 @@ If a required capability is missing, stop and emit explicit manual steps.
 Update it at major milestones. Skip the plan for straightforward tasks.
 
 **Modes:**
+
 - **Interactive** — step-by-step with user approval at each significant change; preferred for
   exploratory or risky work.
 - **Autopilot** — agent drives to completion autonomously; use for well-defined tasks.
@@ -251,9 +251,10 @@ edge cases where multiple equally-valid approaches exist.
   read or write files in the main checkout path.
 - **Branch naming:** the app generates an initial branch name; rename it immediately with
   `rename_branch` before the first commit (using `git branch -m` bypasses the session tracking).
-- **Generated mirrors:** `.claude/commands/` (Claude Code skill mirror) and `.agents/skills/`
-  (Codex skill mirror) are gitignored and rebuilt by `pwsh scripts/sync-skills.ps1`. Run the sync
-  script after any change to `shared/skills/`; these mirrors may not exist on a fresh clone.
+- **Generated mirrors:** `.claude/commands/` (Claude Code skill mirror), `.agents/skills/`
+  (Codex skill mirror), and `.github/skills/` (Copilot skill mirror) are gitignored
+  and rebuilt by `pwsh scripts/setup-repo.ps1 -SkipHooks`. Run the sync step after any change to
+  `ai-artifacts/skills/shared/`; these mirrors may not exist on a fresh clone.
 - **Session state persistence:** session state folder (`~/.copilot/session-state/<session-id>/`)
   persists across checkpoints but is **not** committed. Promote only durable, redacted material
   to the repo.
@@ -274,16 +275,16 @@ edge cases where multiple equally-valid approaches exist.
 
 ## Cross-compatibility
 
-| Artifact                          | Cross-compat position               | Notes                                                                          |
-| --------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------ |
-| `AGENTS.md`                       | **Primary cross-compat file**       | Read by Copilot CLI, VS Code Copilot, Claude Code, Codex                      |
-| `.github/copilot-instructions.md` | Copilot family (CLI + VS Code)      | Not read by Claude Code or Codex as a native instruction file                 |
-| `.github/extensions/`             | Copilot CLI-specific                | Extension format is not shared with other harnesses                           |
-| `.github/prompts/*.prompt.md`     | Copilot family (shared format)      | VS Code Copilot invokes as slash commands; Copilot CLI references by path     |
-| MCP (workspace/user config)       | Cross-vendor                        | Config syntax and location differ per harness; protocol is vendor-neutral     |
-| `shared/skills/`                  | Source of truth                     | Mirrored to `.claude/commands/` (Claude Code) and `.agents/skills/` (Codex); not auto-mirrored for Copilot CLI |
-| Scheduled workflows               | Copilot CLI-specific                | No equivalent native primitive in other harnesses                             |
-| Canvas panels                     | Copilot CLI-specific                | No equivalent in other harnesses                                              |
+| Artifact                          | Cross-compat position          | Notes                                                                                                          |
+| --------------------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `AGENTS.md`                       | **Primary cross-compat file**  | Read by Copilot CLI, VS Code Copilot, Claude Code, Codex                                                       |
+| `.github/copilot-instructions.md` | Copilot family (CLI + VS Code) | Not read by Claude Code or Codex as a native instruction file                                                  |
+| `.github/extensions/`             | Copilot CLI-specific           | Extension format is not shared with other harnesses                                                            |
+| `.github/prompts/*.prompt.md`     | Copilot family (shared format) | VS Code Copilot invokes as slash commands; Copilot CLI references by path                                      |
+| MCP (workspace/user config)       | Cross-vendor                   | Config syntax and location differ per harness; protocol is vendor-neutral                                      |
+| `ai-artifacts/skills/shared/`     | Source of truth                | Mirrored to Claude, Codex, and Copilot skill mirrors                                                           |
+| Scheduled workflows               | Copilot CLI-specific           | No equivalent native primitive in other harnesses                                                              |
+| Canvas panels                     | Copilot CLI-specific           | No equivalent in other harnesses                                                                               |
 
 **Cross-capability preference order for Copilot CLI authoring:**
 
diff --git a/docs/okf-adoption.md b/docs/okf-adoption.md
index 5afb12b..8fbcde3 100644
--- a/docs/okf-adoption.md
+++ b/docs/okf-adoption.md
@@ -15,7 +15,7 @@ bodies.
 
 ## Applied Now
 
-- `shared/skills/<group>/<name>/METADATA.md` is the OKF-style concept document for each skill.
+- `ai-artifacts/skills/shared/<group>/<name>/METADATA.md` is the OKF-style concept document for each skill.
 - Skill provenance (`upstream-*`) lives in `METADATA.md`, not in runtime `SKILL.md` frontmatter.
 - Runtime `SKILL.md` frontmatter keeps harness-facing fields such as `name`, `description`,
   `argument-hint`, `disable-model-invocation`, and `version`.
@@ -49,6 +49,6 @@ tags: [<tag>]
 - **Scratch tracker:** not adopted directly; `.scratch/AGENTS.md` and the scratch skill own that
   schema.
 
-# Citations
+## Citations
 
 [1] [Open Knowledge Format specification](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)
diff --git a/docs/repo-layout.adoc b/docs/repo-layout.adoc
index 21ff5c7..f1d358e 100644
--- a/docs/repo-layout.adoc
+++ b/docs/repo-layout.adoc
@@ -1,19 +1,21 @@
 = Repository Layout
 
-How artifacts (skills, instructions, settings, MCP defs, hooks, output styles, agents) are
-organized in this repo, and how they reach each harness.
+How AI-assisted-work artifacts (skills, instructions, hooks, MCP defs,
+output styles, agents, prompts, plugins, and similar harness assets) are organized in this
+repo, and how they reach each harness.
 
-== Organizing principle: specificity, keyed by who an artifact is for
+== Organizing principle: artifact type first, then specificity
 
-Every artifact lives at the *most general* level it is valid for. More-specific levels *override*
-more-general ones (most-specific wins).
+Top-level folders are keyed by *artifact type*. Beneath each artifact type, content is keyed by the
+most general scope it is valid for. More-specific levels *override* more-general ones
+(most-specific wins).
 
 [cols="1,3a",options="header"]
 |===
 | Tier | Meaning
 
 | `shared/`
-| Vendor- and harness-agnostic. Runs anywhere. The default home — almost everything lives here.
+| Vendor- and harness-agnostic. Runs anywhere. The default scope within an artifact-type folder.
 
 | `<vendor>/`
 | Specific to one vendor (e.g. `anthropic/`, `openai/`), but cross-harness within it.
@@ -22,45 +24,68 @@ more-general ones (most-specific wins).
 | Specific to one harness (e.g. `anthropic/claude-code/`, `anthropic/claude-ai/`).
 |===
 
-`shared/skills/coding/tdd` is the cross-everything copy; `anthropic/claude-code/skills/tdd` (if it
-existed) would shadow it *only* when running in Claude Code.
+`ai-artifacts/skills/shared/coding/tdd` is the cross-everything copy; `ai-artifacts/skills/anthropic/claude-code/coding/tdd`
+(if it existed) would shadow it *only* when running in Claude Code.
 
 == Top-level layout
 
 ....
 ai-lab/
-├── AGENTS.md                 # root shared cross-harness instructions (cross-vendor)
-├── shared/                   # vendor- & harness-agnostic artifacts
-│   └── skills/               # ← all current skills (intent-grouped: coding/ documents/ planning/ session/ setup/)
-├── anthropic/
-│   ├── claude-ai/
-│   │   ├── instructions/profile.md          # account-wide profile (live: Settings → Instructions for Claude)
-│   │   └── projects/<project-name>/         # per-project: project-instruction.md + knowledge files
-│   ├── claude-code/                         # settings/ mcp/ hooks/ output-styles/ instructions/ skills/  (on demand)
-│   └── claude-desktop/                      # (on demand)
-├── openai/                   # codex, etc. — added via the cross-harness review loop
-├── docs/                     # cross-cutting docs: harnesses/, reviews/, findings/, repo-layout.adoc…
-├── eval/                     # vendor-agnostic: INSTRUCTION-EVAL.md + the eval harness
-├── scripts/                  # sync-skills.ps1, …
-├── .scratch/                 # local-markdown issue tracker (PRDs + issues; committed)
-├── .temp/                    # gitignored transient local working files; keep only .gitkeep
-├── .claude/commands/         # GENERATED Claude Code skill mirror — never edit; rebuild via sync-skills.ps1
-└── .agents/skills/           # GENERATED Codex skill mirror — never edit; rebuild via sync-skills.ps1
+├── AGENTS.md                  # root shared cross-harness instructions (cross-vendor)
+├── ai-artifacts/
+│   ├── skills/
+│   │   └── shared/            # all current skills (intent-grouped: coding/ documents/ planning/ session/ setup/ workflow/)
+│   ├── instructions/
+│   │   └── anthropic/
+│   │       └── claude-ai/
+│   │           └── profile.md # account-wide profile (live: Settings → Instructions for Claude)
+│   ├── hooks/                 # hook source definitions, when added; scoped as shared/<vendor>/<harness>
+│   ├── mcp-config/            # MCP server/config definitions
+│   ├── output-styles/         # reusable output-format or style guidance assets
+│   ├── agents/                # agent/subagent definitions and related assets
+│   ├── prompts/               # reusable prompts and prompt packs
+│   └── plugins/               # plugin packaging and support material
+├── docs/                      # cross-cutting docs: harnesses/, reviews/, findings/, repo-layout.adoc…
+├── scripts/                   # setup-repo.ps1, …
+├── .scratch/                  # local-markdown issue tracker (PRDs + issues; committed)
+├── .temp/                     # gitignored transient local working files; keep only .gitkeep
+├── .claude/commands/          # GENERATED Claude Code skill mirror — never edit; rebuild via setup-repo.ps1
+├── .agents/skills/            # GENERATED Codex skill mirror — never edit; rebuild via setup-repo.ps1
+└── .github/skills/            # GENERATED Copilot skill mirror — never edit; rebuild via setup-repo.ps1
 ....
 
-Folders are created *on demand* — a `<vendor>/<harness>/<artifact-type>/` directory is materialized
-only when it has content, not pre-scaffolded empty.
+Folders are created *on demand* — a `<artifact-type>/<vendor>/<harness>/` directory is materialized
+only when it has content, not pre-scaffolded empty. The top-level artifact folders may contain a
+small `README.md` before they have scoped content so the taxonomy is visible in fresh clones.
 
 == Per-artifact-type keying
 
-* *skills* — usually `shared/` (they are methodology, not vendor-specific). Drop to `<vendor>/` or
-  `<vendor>/<harness>/` only for a skill that genuinely is specific. Skills follow the
+* *skills* — usually `ai-artifacts/skills/shared/` (they are methodology, not vendor-specific). Drop to
+  `ai-artifacts/skills/<vendor>/` or `ai-artifacts/skills/<vendor>/<harness>/` only for a skill that genuinely is specific.
+  Skills follow the
   *capability contract* (detect shell/filesystem → full path; else conversational fallback) so one
   copy works across harnesses — avoid per-harness copies unless behavior truly diverges. Each skill's
   runtime instructions live in `SKILL.md`; catalog/provenance facts live in sibling `METADATA.md`
   using the repo's OKF convention.
-* *instructions, settings, mcp, hooks, output-styles* — almost always `<vendor>/<harness>/`. A Claude
-  Code `settings.json` is meaningless to Codex; the claude-ai profile is not the Claude Code `CLAUDE.md`.
+* *instructions* — `ai-artifacts/instructions/<vendor>/<harness>/`. This folder holds repo copies of loaded
+  instruction surfaces: claude.ai profile instructions, Claude Code `CLAUDE.md`, project
+  instructions, global instruction files, Copilot instruction files, Codex instruction notes, and
+  equivalent base instruction documents for other agents.
+* *hooks* — `ai-artifacts/hooks/<vendor>/<harness>/` when hook definitions become source artifacts. Hook-related
+  skills still live under `ai-artifacts/skills/` unless the artifact itself is a hook config or script.
+* *MCP config* — `ai-artifacts/mcp-config/shared/` or `ai-artifacts/mcp-config/<vendor>/<harness>/` for MCP server manifests,
+  connection definitions, and adjacent support files.
+* *output styles* — `ai-artifacts/output-styles/shared/` or `ai-artifacts/output-styles/<vendor>/<harness>/` for reusable
+  formatting/style assets that shape model output.
+* *agents* — `ai-artifacts/agents/shared/` or `ai-artifacts/agents/<vendor>/<harness>/` for agent/subagent definitions and
+  related resources.
+* *prompts* — `ai-artifacts/prompts/shared/` or `ai-artifacts/prompts/<vendor>/<harness>/` for reusable prompts or prompt packs
+  that are not instruction surfaces.
+* *plugins* — `ai-artifacts/plugins/shared/` or `ai-artifacts/plugins/<vendor>/<harness>/` for plugin
+  packaging, manifests, and durable support files.
+* *future artifact families* — when a new class of AI repo asset appears often enough to deserve a
+  stable home, add a top-level artifact-type folder with the same `shared/`, `<vendor>/`,
+  `<vendor>/<harness>/` scoping rather than creating another catch-all bucket.
 * *temporary working files* — `.temp/` at repo root. Its contents are gitignored and may be deleted at
   any time. Promote only durable, redacted, intentionally committed support material to
   `.scratch/<feature>/artifacts/`.
@@ -70,17 +95,21 @@ only when it has content, not pre-scaffolded empty.
 The repo is the source of truth. Each harness loads artifacts from its own locations, so a sync step
 deploys from here to there.
 
-* *Default.* `scripts/sync-skills.ps1` refreshes every generated skill mirror supported by this repo.
-  Use `-Target Claude` or `-Target Codex` only when intentionally limiting the sync.
-* *Claude Code.* The Claude target mirrors `shared/skills/<group>/<name>/` to the
+* *Default.* `scripts/setup-repo.ps1` runs clone setup end-to-end: installs git hooks and then runs
+  skill mirror sync (all targets by default, with optional `-Target`, `-Scope`, and `-IfMissing`).
+* *After skill edits.* `scripts/setup-repo.ps1 -SkipHooks` refreshes generated mirrors without re-installing hooks.
+* *Claude Code.* The Claude target mirrors `ai-artifacts/skills/shared/<group>/<name>/` to the
   Claude Code command tree (`.claude/commands/<group>/<name>.md` + resources). The generated tree is
   gitignored; rebuild after editing a skill.
-* *Codex.* The Codex target mirrors `shared/skills/<group>/<name>/` to Codex's
-  repo-local skill tree (`.agents/skills/<group>-<name>/SKILL.md` + resources). The generated tree is
+* *Codex.* The Codex target mirrors `ai-artifacts/skills/shared/<group>/<name>/` to Codex's
+  repo-local skill tree (`.agents/skills/<group>_<name>/SKILL.md` + resources). The generated tree is
   gitignored; rebuild after editing a skill.
-* *Other harnesses (Copilot, ChatGPT, …)* — added incrementally through the cross-harness review loop
-  (see `docs/harnesses/`): each harness, on its turn, records where *it* expects its files; sync grows
-  to target it only then. No multi-harness sync engine is built ahead of that need.
+* *Copilot.* The Copilot target mirrors `ai-artifacts/skills/shared/<group>/<name>/` to
+  `.github/skills/<group>_<name>/SKILL.md` (+ resources in the same folder). The generated mirror is
+  gitignored; rebuild after editing a skill.
+* *Other harnesses (ChatGPT, …)* — added incrementally through the cross-harness review loop (see
+  `docs/harnesses/`): each harness, on its turn, records where *it* expects its files; sync grows to
+  target it only then. No multi-harness sync engine is built ahead of that need.
 
 == OKF metadata
 
@@ -90,12 +119,20 @@ with a harness-owned file format. The current concrete use is per-skill `METADAT
 
 == Not the same file (common confusion)
 
-* `anthropic/claude-ai/instructions/profile.md` — the claude.ai account profile. Read by the Chat
+* `ai-artifacts/instructions/anthropic/claude-ai/profile.md` — the claude.ai account profile. Read by the Chat
   harness only. Live version: Settings → Instructions for Claude (paste the whole file).
 * `~/.claude/CLAUDE.md` — Claude Code's global instructions. Different harness, different file. Expected
   to *overlap* with the profile (same behavioral preferences) but authored and loaded separately.
-  Repo copy, when added, lives at `anthropic/claude-code/instructions/CLAUDE.md`.
+  Repo copy, when added, lives at `ai-artifacts/instructions/anthropic/claude-code/CLAUDE.md`.
 * `AGENTS.md` (repo root) — the cross-harness shared layer read by Claude Code, Codex, and Copilot.
   The place for anything that should be identical across harnesses.
 
+== Format choices
+
+* `docs/repo-layout.adoc` stays AsciiDoc because it is the canonical layout reference and benefits
+  from AsciiDoc tables, examples, and richer cross-reference structure.
+* `AGENTS.md` stays Markdown because harnesses load it directly as an instruction file; portability
+  matters more than richer document syntax.
+* Artifact READMEs stay Markdown unless they need AsciiDoc-only structure.
+
 See `docs/harnesses/<harness>.md` for each harness's instruction surfaces and load model.
diff --git a/docs/reviews/2026-07-04-fable-repo-review.md b/docs/reviews/2026-07-04-fable-repo-review.md
index 27fd286..d36098c 100644
--- a/docs/reviews/2026-07-04-fable-repo-review.md
+++ b/docs/reviews/2026-07-04-fable-repo-review.md
@@ -12,7 +12,7 @@ executed the same day:
 
 | Scratch                                                                      | State after the review session                                             |
 | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
-| [sync-skills-drift-check](../../.scratch/sync-skills-drift-check/PRD.md)     | ✅ done — `-Check` mode + hook                                             |
+| [sync-skills-drift-check](../../.scratch/sync-skills-drift-check/PRD.md)     | ✅ done — drift check + hook                                               |
 | [docs-integrity-pass](../../.scratch/docs-integrity-pass/PRD.md)             | ✅ done — 4 drift fixes + decay contract                                   |
 | [public-repo-compliance](../../.scratch/public-repo-compliance/PRD.md)       | ⏳ ready-for-human — attribution + protections done; profile go/no-go open |
 | [backlog-hygiene-wip-limit](../../.scratch/backlog-hygiene-wip-limit/PRD.md) | needs-triage                                                               |
@@ -26,15 +26,15 @@ Also executed on the back of the review: `repo-scaffold` completed (root `AGENTS
 
 `ai-lab` is a personal **control plane for AI-assisted work across multiple harnesses**. Four pillars:
 
-1. **Skills as source of truth** — `shared/skills/` holds portable, provenance-tracked skills
-   (grouped by intent: coding/planning/session/setup), deployed into Claude Code's
-   `.claude/commands/` via `scripts/sync-skills.ps1`. The mirror is a gitignored build artifact.
+1. **Skills as source of truth** — `ai-artifacts/skills/shared/` holds portable, provenance-tracked skills
+  (grouped by intent: coding/planning/session/setup), deployed into Claude Code's
+  `.claude/commands/` via `scripts/setup-repo.ps1 -SkipHooks`. The mirror is a gitignored build artifact.
 2. **Harness knowledge base** — `docs/harnesses/` documents each harness *from the inside*
    (self-description via `TEMPLATE.md`): instruction surfaces, precedence, storage tiers,
    capability limits. The "capability contract" (shell available → full path; else conversational
    fallback) is the portability mechanism that lets one skill copy serve all harnesses.
-3. **Instructions as versioned artifacts** — `instructions/` +
-   `anthropic/claude-ai/instructions/profile.md` treat instruction files as repo-managed source
+3. **Instructions as versioned artifacts** — `ai-artifacts/instructions/` +
+  `ai-artifacts/instructions/anthropic/claude-ai/profile.md` treat instruction files as repo-managed source
    with harness-specific live locations, organized by the specificity tiers in
    `docs/repo-layout.adoc` (`shared/` → `<vendor>/` → `<vendor>/<harness>/`, most-specific wins).
 4. **A self-hosted tracker** — `.scratch/` is a committed local-markdown issue tracker
@@ -56,7 +56,7 @@ code is.*
   layout shift including link rewriting, has a non-clobbering `-IfMissing` bootstrap mode wired to
   a SessionStart hook, and the "never edit the mirror" rule is documented consistently.
 - **Provenance is taken seriously.** Per-skill `METADATA.md` files, an origin map in
-  `shared/skills/README.md`, explicit fork-vs-downstream decisions (the `setup-pre-commit` case),
+  `ai-artifacts/skills/shared/README.md`, explicit fork-vs-downstream decisions (the `setup-pre-commit` case),
   and license/attribution awareness in the import PRD. Exact upstream checkpoints belong in the
   individual skill metadata, not summary docs.
 - **Unusual epistemic maturity in the PRDs.** The `[RE-CONFIRM]` annotations on decisions inherited
@@ -85,16 +85,16 @@ code is.*
   near-verbatim in two places — and the copies contradicted each other on the future CLAUDE.md
   path. The skills README lacked the `planning` group and used pre-migration paths. A resolved
   git-init blocker was still marked blocking.
-- **The repo is public with hardening unranked.** *(largely fixed same day: THIRD-PARTY/ added,
+- **The repo is public with hardening unranked.** *(largely fixed same day: attribution files were added,
   secret scanning + push protection + Dependabot enabled)* Vendored upstream skill copies were
   committed without the license attribution the import PRD itself required "before publishing" —
   publishing had already happened. The personal behavioral profile is public; that should be a
   conscious decision (still open).
-- **Stray content dilutes the repo's identity.** `VSCode_Extsion/` (note the typo) is a shipped
+- **Stray content dilutes the repo's identity.** `VSCode_Extension/` is a shipped
   VS Code extension at the root of an AI-configuration repo with no README tying it in;
   `mail-to-doc` rides in the tracker as a general software project. Neither is wrong — the scope
   widening is silent (open: `repo-scope-strays`).
-- **Silent-staleness risks in the sync chain.** *(fixed same day: `-Check` mode)* `-IfMissing`
+- **Silent-staleness risks in the sync chain.** *(fixed same day: drift check)* `-IfMissing`
   never refreshes an edited skill, and it's the mode the hook runs — the failure mode was the
   default path. Harness docs describe fast-moving products with a single "verified 2026-06" stamp
   and no re-verification trigger *(fixed: decay contract in TEMPLATE.md)*.
@@ -114,7 +114,7 @@ code is.*
 4. **Close the public-repo gap** — THIRD-PARTY attribution, secret scanning, push protection,
    branch protection decision. *(done except branch protection + profile go/no-go)*
 5. **De-duplicate facts; single owner per fact.** *(done; rule codified in AGENTS.md)*
-6. **Add a `-Check` drift mode to sync-skills.ps1.** *(done)*
+6. **Add a drift check for generated mirrors.** *(done)*
 7. **Give harness docs a decay contract.** *(done)*
 8. **Decide the strays consciously** — declare incubation or evict. *(open)*
 
diff --git a/instructions/README.md b/instructions/README.md
deleted file mode 100644
index 687c4de..0000000
--- a/instructions/README.md
+++ /dev/null
@@ -1,22 +0,0 @@
-# Instructions
-
-Harness-specific instruction files, keyed by harness (matching `docs/harnesses/`). Each file here is
-the **repo copy for editing** — the live version lives in that harness's own location. These are
-**not interchangeable**: different harnesses read different files, and overlap between them is
-expected, not duplication to be merged.
-
-| File | Harness | Live location | Notes |
-|---|---|---|---|
-| `claude-ai/profile.md` | claude.ai (web / mobile / Desktop **Chat** tab) | Settings → Instructions for Claude | Account-wide profile — paste the whole file into Settings. Keep it domain-agnostic: PowerShell- or project-specific guidance belongs in the relevant claude.ai project, not here. |
-
-## Not the same file (common confusion)
-
-Owned by [docs/repo-layout.adoc](../docs/repo-layout.adoc) ("Not the same file" section) — not
-restated here. Note: an earlier version of this section placed the future Claude Code `CLAUDE.md`
-repo copy under `instructions/claude-code/`; the canonical location per the layout doc is
-`anthropic/claude-code/instructions/CLAUDE.md`.
-
-See `docs/harnesses/<harness>.md` for each harness's instruction surfaces and load model.
-
-> Remaining instructions-taxonomy questions (which shared content is hoisted into `AGENTS.md`) are
-> owned by `.scratch/incorporate-global-claude-setup/` (repo-scaffold itself is done).
diff --git a/reports/coding-policy-check.txt b/reports/coding-policy-check.txt
new file mode 100644
index 0000000..da13e61
--- /dev/null
+++ b/reports/coding-policy-check.txt
@@ -0,0 +1,3 @@
+coding policy check
+status: passed
+validated policy pack and bash policy constraints
diff --git a/reports/powershell-runtime-check.txt b/reports/powershell-runtime-check.txt
new file mode 100644
index 0000000..10c850b
--- /dev/null
+++ b/reports/powershell-runtime-check.txt
@@ -0,0 +1,3 @@
+powershell runtime check
+status: passed
+all PowerShell scripts declare a valid runtime policy
diff --git a/scripts/install-git-hooks.ps1 b/scripts/install-git-hooks.ps1
deleted file mode 100644
index 8441851..0000000
--- a/scripts/install-git-hooks.ps1
+++ /dev/null
@@ -1,24 +0,0 @@
-Set-StrictMode -Version Latest
-$ErrorActionPreference = "Stop"
-
-$repoRoot = git rev-parse --show-toplevel
-if (-not $repoRoot) {
-  throw "Unable to determine repository root."
-}
-
-$hooksDir = Join-Path $repoRoot ".githooks"
-if (Test-Path $hooksDir) {
-  $utf8NoBom = New-Object System.Text.UTF8Encoding($false)
-  Get-ChildItem -Path $hooksDir -File | ForEach-Object {
-    $raw = [System.IO.File]::ReadAllText($_.FullName)
-    $normalized = $raw -replace "`r`n", "`n" -replace "`r", "`n"
-    if ($normalized -ne $raw) {
-      [System.IO.File]::WriteAllText($_.FullName, $normalized, $utf8NoBom)
-      Write-Output "Normalized LF line endings: $($_.Name)"
-    }
-  }
-}
-
-git config core.hooksPath .githooks
-Write-Output "Configured core.hooksPath to .githooks"
-Write-Output "Git hooks are now active for this clone."
diff --git a/scripts/setup-repo.ps1 b/scripts/setup-repo.ps1
new file mode 100644
index 0000000..700d778
--- /dev/null
+++ b/scripts/setup-repo.ps1
@@ -0,0 +1,60 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+
+  [ValidateSet('All', 'Claude', 'Codex', 'Copilot')]
+  [string]$Target = 'All',
+
+  [Alias('Scope')]
+  [ValidateSet('Project', 'User')]
+  [string]$MirrorScope = 'Project',
+
+  [string]$Skill = '',
+
+  [switch]$IfMissing,
+  [switch]$Check,
+  [switch]$SkipHooks,
+  [switch]$SkipSkillSync
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$entryScript = Join-Path $PSScriptRoot '../ai-artifacts/skills/shared/setup/setup-repo/scripts/Invoke-SetupRepo.ps1'
+$entryScript = (Resolve-Path $entryScript).Path
+
+$entryParams = @{
+  Target      = $Target
+  MirrorScope = $MirrorScope
+}
+
+if ($RepoRoot) {
+  $entryParams.RepoRoot = $RepoRoot
+}
+
+if ($IfMissing) {
+  $entryParams.IfMissing = $true
+}
+
+if ($Skill) {
+  $entryParams.Skill = $Skill
+}
+
+if ($Check) {
+  $entryParams.Check = $true
+}
+
+if ($SkipHooks) {
+  $entryParams.SkipHooks = $true
+}
+
+if ($SkipSkillSync) {
+  $entryParams.SkipSkillSync = $true
+}
+
+& $entryScript @entryParams
+exit $LASTEXITCODE
diff --git a/scripts/simulate-workflows.ps1 b/scripts/simulate-workflows.ps1
new file mode 100644
index 0000000..42c1223
--- /dev/null
+++ b/scripts/simulate-workflows.ps1
@@ -0,0 +1,25 @@
+#Requires -Version 7.0
+#Requires -PSEdition Core
+# RuntimePolicy: core-first
+
+[CmdletBinding()]
+param(
+  [string]$RepoRoot = "",
+  [switch]$InstallTools,
+  [switch]$UseChangedFiles
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = "Stop"
+
+$scriptPath = Join-Path $PSScriptRoot "../ai-artifacts/skills/shared/workflow/simulate-workflows/scripts/Invoke-LocalWorkflowSimulation.ps1"
+$scriptPath = (Resolve-Path $scriptPath).Path
+
+$invokeParams = @{}
+if ($RepoRoot) { $invokeParams.RepoRoot = $RepoRoot }
+if ($InstallTools) { $invokeParams.InstallTools = $true }
+if ($UseChangedFiles) { $invokeParams.UseChangedFiles = $true }
+
+& $scriptPath @invokeParams
+
+exit $LASTEXITCODE
diff --git a/scripts/sync-skills.ps1 b/scripts/sync-skills.ps1
deleted file mode 100644
index 80c94d1..0000000
--- a/scripts/sync-skills.ps1
+++ /dev/null
@@ -1,436 +0,0 @@
-#Requires -Version 7.0
-<#
-.SYNOPSIS
-    Sync generated skill mirrors for supported local harnesses.
-
-.DESCRIPTION
-    shared/skills/ is the source of truth. This script refreshes generated harness mirrors:
-
-      Claude Code -> .claude/commands/
-      Codex       -> .agents/skills/
-
-    By default it updates both. Use -Target to limit the sync to one harness.
-
-.PARAMETER Target
-    All (default), Claude, or Codex.
-
-.PARAMETER Scope
-    Claude target only. Project (default) writes <repo>/.claude/commands; User writes
-    $env:USERPROFILE/.claude/commands. Codex is always repo-local.
-
-.PARAMETER Skill
-    Optional. Mirror only the source skill with this name (e.g. "tdd"). Default: all skills.
-
-.PARAMETER IfMissing
-    Bootstrap mode: only write a missing generated skill. Does not refresh existing generated files.
-
-.PARAMETER Check
-    Read-only drift check. Reports UP-TO-DATE / STALE / MISSING and exits 1 if any target differs.
-
-.PARAMETER RepoRoot
-    Repo root. Defaults to the parent of this script's folder.
-
-.EXAMPLE
-    pwsh scripts/sync-skills.ps1
-    Rebuild Claude Code and Codex skill mirrors from shared/skills.
-
-.EXAMPLE
-    pwsh scripts/sync-skills.ps1 -Check
-    Check every generated mirror for drift.
-
-.EXAMPLE
-    pwsh scripts/sync-skills.ps1 -Target Claude -Skill tdd -Scope User
-    Push only the tdd skill to the user-global Claude command mirror.
-#>
-[CmdletBinding()]
-param(
-    [ValidateSet('All', 'Claude', 'Codex')]
-    [string]$Target = 'All',
-
-    [ValidateSet('Project', 'User')]
-    [string]$Scope = 'Project',
-
-    [string]$Skill,
-
-    [switch]$IfMissing,
-
-    [switch]$Check,
-
-    [string]$RepoRoot = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
-)
-
-$ErrorActionPreference = 'Stop'
-Set-StrictMode -Version Latest
-if ($Check -and $IfMissing) { throw "-Check is read-only; do not combine it with -IfMissing." }
-if ($Scope -eq 'User' -and $Target -ne 'Claude') {
-    throw "-Scope User applies only to Claude. Use -Target Claude -Scope User."
-}
-
-$skillsRoot = Join-Path $RepoRoot 'shared\skills'
-if (-not (Test-Path $skillsRoot)) { throw "shared/skills root not found at: $skillsRoot" }
-$script:LastSyncExitCode = 0
-
-function Get-SkillDirectories {
-    param(
-        [string]$Root,
-        [string]$Name
-    )
-
-    $dirs = Get-ChildItem $Root -Recurse -Filter 'SKILL.md' -File |
-        ForEach-Object { $_.Directory } |
-        Where-Object { -not $Name -or $_.Name -eq $Name }
-
-    if (-not $dirs) {
-        if ($Name) { throw "No skill named '$Name' found under $Root" }
-        throw "No SKILL.md files found under $Root"
-    }
-
-    return @($dirs)
-}
-
-function Convert-ResourceLinks {
-    param(
-        [string]$Body,
-        [string]$Name,
-        [string[]]$ResourceRelPaths
-    )
-
-    foreach ($path in $ResourceRelPaths) {
-        $Body = $Body.Replace("](./$path)", "]($Name/$path)")
-        $Body = $Body.Replace("]($path)", "]($Name/$path)")
-        $Body = $Body -replace ("(?<=@)" + [regex]::Escape($path) + "\b"), "$Name/$path"
-    }
-    return $Body
-}
-
-function ConvertTo-YamlScalar {
-    param([string]$Value)
-
-    if ($null -eq $Value) { return '""' }
-    return '"' + ($Value -replace '\\', '\\' -replace '"', '\"') + '"'
-}
-
-function Get-FrontmatterValue {
-    param(
-        [string]$Document,
-        [string]$Key
-    )
-
-    if ($Document -notmatch "(?s)\A---\r?\n(.*?)\r?\n---\r?\n") { return $null }
-    $frontmatter = $Matches[1]
-    $match = [regex]::Match($frontmatter, "(?m)^$([regex]::Escape($Key)):\s*(.*)$")
-    if (-not $match.Success) { return $null }
-
-    $value = $match.Groups[1].Value.Trim()
-    if ($value -in @('>', '|', '>-', '|-', '>+', '|+')) {
-        $lines = $frontmatter -split "\r?\n"
-        $startIndex = [Array]::IndexOf($lines, $match.Value)
-        if ($startIndex -lt 0) { return $null }
-
-        $blockLines = [System.Collections.Generic.List[string]]::new()
-        for ($i = $startIndex + 1; $i -lt $lines.Count; $i++) {
-            $line = $lines[$i]
-            if ($line -match '^\S[^:]*:\s*') { break }
-            if ($line -match '^\s*$') {
-                $blockLines.Add('')
-                continue
-            }
-            $blockLines.Add(($line -replace '^\s{1,}', ''))
-        }
-
-        if ($value.StartsWith('|')) {
-            return ($blockLines -join "`n").Trim()
-        }
-        return (($blockLines | Where-Object { $_ -ne '' }) -join ' ').Trim()
-    }
-    if (($value.StartsWith('"') -and $value.EndsWith('"')) -or
-        ($value.StartsWith("'") -and $value.EndsWith("'"))) {
-        $value = $value.Substring(1, $value.Length - 2)
-    }
-    return $value
-}
-
-function Get-SkillBody {
-    param([string]$Document)
-
-    if ($Document -match "(?s)\A---\r?\n.*?\r?\n---\r?\n(.*)\z") {
-        return $Matches[1].TrimStart()
-    }
-    return $Document.TrimStart()
-}
-
-function ConvertTo-CodexSkill {
-    param(
-        [string]$SourceDocument,
-        [string]$CodexName,
-        [string]$SourceRelPath
-    )
-
-    $description = Get-FrontmatterValue -Document $SourceDocument -Key 'description'
-    if (-not $description) { $description = "Repo skill mirrored from $SourceRelPath." }
-    $version = Get-FrontmatterValue -Document $SourceDocument -Key 'version'
-
-    $body = Get-SkillBody -Document $SourceDocument
-    $frontmatter = @(
-        '---'
-        "name: $(ConvertTo-YamlScalar $CodexName)"
-        "description: $(ConvertTo-YamlScalar $description)"
-        $(if ($version) { "version: $(ConvertTo-YamlScalar $version)" })
-        '---'
-        ''
-        "<!-- GENERATED from $SourceRelPath. Edit shared/skills and run scripts/sync-skills.ps1. -->"
-        ''
-    ) -join "`n"
-
-    return $frontmatter + $body
-}
-
-function Get-CodexCompatibilityWarnings {
-    param(
-        [string]$Document,
-        [string]$SkillName
-    )
-
-    $patterns = [ordered]@{
-        'claude-path'     = '\.claude|CLAUDE_PROJECT_DIR'
-        'claude-command'  = '(^|\s)/[A-Za-z0-9_-]+:[A-Za-z0-9_-]+|\$ARGUMENTS|!command'
-        'codex-case'      = '\.Codex'
-        'old-skills-root' = 'skills/<group>/<name>|(?<!shared/)skills/'
-    }
-
-    foreach ($entry in $patterns.GetEnumerator()) {
-        if ($Document -match $entry.Value) { "$SkillName $($entry.Key)" }
-    }
-}
-
-function Sync-ClaudeSkills {
-    param(
-        [System.IO.DirectoryInfo[]]$SkillDirs,
-        [string]$Root,
-        [string]$ClaudeScope,
-        [switch]$OnlyIfMissing,
-        [switch]$ReadOnlyCheck
-    )
-
-    $commandsRoot = switch ($ClaudeScope) {
-        'Project' { Join-Path $RepoRoot '.claude\commands' }
-        'User'    { Join-Path $env:USERPROFILE '.claude\commands' }
-    }
-
-    $report = [System.Text.StringBuilder]::new()
-    $driftCount = 0
-    $script:LastSyncExitCode = 0
-
-    foreach ($dir in $SkillDirs) {
-        $name = $dir.Name
-        $group = $dir.Parent.Name
-        $groupDir = Join-Path $commandsRoot $group
-        $targetMd = Join-Path $groupDir "$name.md"
-        $targetRes = Join-Path $groupDir $name
-
-        if ($OnlyIfMissing -and (Test-Path $targetMd)) {
-            [void]$report.AppendLine(("  /{0}:{1,-18} present - skipped (-IfMissing)" -f $group, $name))
-            continue
-        }
-
-        $resources = @(Get-ChildItem $dir.FullName -Recurse -File |
-            Where-Object { $_.Name -notin @('SKILL.md', 'METADATA.md') })
-        $resRelPaths = $resources | ForEach-Object {
-            $_.FullName.Substring($dir.FullName.Length).TrimStart('\').Replace('\', '/')
-        }
-
-        $body = Get-Content (Join-Path $dir.FullName 'SKILL.md') -Raw
-        if ($resRelPaths) {
-            $body = Convert-ResourceLinks -Body $body -Name $name -ResourceRelPaths $resRelPaths
-        }
-
-        if ($ReadOnlyCheck) {
-            $state = 'UP-TO-DATE'
-            if (-not (Test-Path $targetMd)) { $state = 'MISSING' }
-            elseif ((Get-Content $targetMd -Raw) -cne $body) { $state = 'STALE' }
-            else {
-                foreach ($res in $resources) {
-                    $rel = $res.FullName.Substring($dir.FullName.Length).TrimStart('\')
-                    $dest = Join-Path $targetRes $rel
-                    if (-not (Test-Path $dest) -or
-                        (Get-FileHash $res.FullName).Hash -ne (Get-FileHash $dest).Hash) {
-                        $state = 'STALE'
-                        break
-                    }
-                }
-                if ($state -eq 'UP-TO-DATE') {
-                    $mirrored = if (Test-Path $targetRes) { @(Get-ChildItem $targetRes -Recurse -File).Count } else { 0 }
-                    if ($mirrored -ne $resources.Count) { $state = 'STALE' }
-                }
-            }
-
-            if ($state -ne 'UP-TO-DATE') { $driftCount++ }
-            [void]$report.AppendLine(("  /{0}:{1,-18} {2}" -f $group, $name, $state))
-            continue
-        }
-
-        if (Test-Path $targetMd) { Remove-Item $targetMd -Force }
-        if (Test-Path $targetRes) { Remove-Item $targetRes -Recurse -Force }
-        New-Item -ItemType Directory -Path $groupDir -Force | Out-Null
-        Set-Content -Path $targetMd -Value $body -Encoding utf8 -NoNewline
-
-        foreach ($res in $resources) {
-            $rel = $res.FullName.Substring($dir.FullName.Length).TrimStart('\')
-            $dest = Join-Path $targetRes $rel
-            New-Item -ItemType Directory -Path (Split-Path $dest -Parent) -Force | Out-Null
-            Copy-Item $res.FullName $dest -Force
-        }
-
-        [void]$report.AppendLine(("  /{0}:{1,-18} {2} resource file(s)" -f $group, $name, $resources.Count))
-    }
-
-    if ($ReadOnlyCheck) {
-        Write-Output "Drift check: $Root -> $commandsRoot (target=Claude, scope=$ClaudeScope)"
-        Write-Output $report.ToString().TrimEnd()
-        if ($driftCount) {
-            Write-Output "STALE MIRROR: $driftCount Claude skill(s) stale or missing - rebuild with: pwsh scripts/sync-skills.ps1 -Target Claude"
-            $script:LastSyncExitCode = 1
-            return
-        }
-        Write-Output "Claude skills up to date."
-        return
-    }
-
-    Write-Output "Synced Claude skills -> $commandsRoot (scope=$ClaudeScope)"
-    Write-Output $report.ToString().TrimEnd()
-    return
-}
-
-function Sync-CodexSkills {
-    param(
-        [System.IO.DirectoryInfo[]]$SkillDirs,
-        [string]$Root,
-        [string]$SelectedSkill,
-        [switch]$OnlyIfMissing,
-        [switch]$ReadOnlyCheck
-    )
-
-    $agentsRoot = Join-Path $RepoRoot '.agents\skills'
-    $report = [System.Text.StringBuilder]::new()
-    $warnings = [System.Collections.Generic.List[string]]::new()
-    $expectedSkillNames = [System.Collections.Generic.HashSet[string]]::new()
-    $driftCount = 0
-    $script:LastSyncExitCode = 0
-
-    if (-not $ReadOnlyCheck -and -not $OnlyIfMissing -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
-        Remove-Item $agentsRoot -Recurse -Force
-    }
-
-    foreach ($dir in $SkillDirs) {
-        $sourceName = $dir.Name
-        $group = $dir.Parent.Name
-        $codexName = "$group-$sourceName"
-        [void]$expectedSkillNames.Add($codexName)
-        $targetDir = Join-Path $agentsRoot $codexName
-        $targetSkill = Join-Path $targetDir 'SKILL.md'
-
-        if ($OnlyIfMissing -and (Test-Path $targetSkill)) {
-            [void]$report.AppendLine(("  {0,-36} present - skipped (-IfMissing)" -f $codexName))
-            continue
-        }
-
-        $sourceSkill = Join-Path $dir.FullName 'SKILL.md'
-        $sourceRelPath = "shared/skills/$group/$sourceName/SKILL.md"
-        $sourceDocument = Get-Content $sourceSkill -Raw
-        $expectedSkill = ConvertTo-CodexSkill -SourceDocument $sourceDocument -CodexName $codexName -SourceRelPath $sourceRelPath
-        foreach ($warning in Get-CodexCompatibilityWarnings -Document $sourceDocument -SkillName $codexName) {
-            $warnings.Add($warning)
-        }
-
-        $resources = @(Get-ChildItem $dir.FullName -Recurse -File |
-            Where-Object { $_.Name -notin @('SKILL.md', 'METADATA.md') })
-
-        if ($ReadOnlyCheck) {
-            $state = 'UP-TO-DATE'
-            if (-not (Test-Path $targetSkill)) { $state = 'MISSING' }
-            elseif ((Get-Content $targetSkill -Raw) -cne $expectedSkill) { $state = 'STALE' }
-            else {
-                foreach ($res in $resources) {
-                    $rel = $res.FullName.Substring($dir.FullName.Length).TrimStart('\')
-                    $dest = Join-Path $targetDir $rel
-                    if (-not (Test-Path $dest) -or
-                        (Get-FileHash $res.FullName).Hash -ne (Get-FileHash $dest).Hash) {
-                        $state = 'STALE'
-                        break
-                    }
-                }
-                if ($state -eq 'UP-TO-DATE') {
-                    $mirrored = @(Get-ChildItem $targetDir -Recurse -File | Where-Object { $_.Name -ne 'SKILL.md' }).Count
-                    if ($mirrored -ne $resources.Count) { $state = 'STALE' }
-                }
-            }
-
-            if ($state -ne 'UP-TO-DATE') { $driftCount++ }
-            [void]$report.AppendLine(("  {0,-36} {1}" -f $codexName, $state))
-            continue
-        }
-
-        if (Test-Path $targetDir) { Remove-Item $targetDir -Recurse -Force }
-        New-Item -ItemType Directory -Path $targetDir -Force | Out-Null
-        Set-Content -Path $targetSkill -Value $expectedSkill -Encoding utf8 -NoNewline
-
-        foreach ($res in $resources) {
-            $rel = $res.FullName.Substring($dir.FullName.Length).TrimStart('\')
-            $dest = Join-Path $targetDir $rel
-            New-Item -ItemType Directory -Path (Split-Path $dest -Parent) -Force | Out-Null
-            Copy-Item $res.FullName $dest -Force
-        }
-
-        [void]$report.AppendLine(("  {0,-36} {1} resource file(s)" -f $codexName, $resources.Count))
-    }
-
-    if ($ReadOnlyCheck -and -not $SelectedSkill -and (Test-Path $agentsRoot)) {
-        foreach ($dir in Get-ChildItem $agentsRoot -Directory) {
-            if (-not $expectedSkillNames.Contains($dir.Name)) {
-                $driftCount++
-                [void]$report.AppendLine(("  {0,-36} EXTRA" -f $dir.Name))
-            }
-        }
-    }
-
-    if ($ReadOnlyCheck) {
-        Write-Output "Drift check: $Root -> $agentsRoot (target=Codex)"
-        Write-Output $report.ToString().TrimEnd()
-        if ($warnings.Count) {
-            Write-Output "Compatibility warnings:"
-            $warnings | Sort-Object -Unique | ForEach-Object { Write-Output "  $_" }
-        }
-        if ($driftCount) {
-            Write-Output "STALE MIRROR: $driftCount Codex skill(s) stale or missing - rebuild with: pwsh scripts/sync-skills.ps1 -Target Codex"
-            $script:LastSyncExitCode = 1
-            return
-        }
-        Write-Output "Codex skills up to date."
-        return
-    }
-
-    Write-Output "Synced Codex skills -> $agentsRoot"
-    Write-Output $report.ToString().TrimEnd()
-    if ($warnings.Count) {
-        Write-Output "Compatibility warnings:"
-        $warnings | Sort-Object -Unique | ForEach-Object { Write-Output "  $_" }
-    }
-    return
-}
-
-$skillDirs = Get-SkillDirectories -Root $skillsRoot -Name $Skill
-$exitCodes = [System.Collections.Generic.List[int]]::new()
-
-if ($Target -in @('All', 'Claude')) {
-    Write-Output "== Claude Code skill mirror =="
-    Sync-ClaudeSkills -SkillDirs $skillDirs -Root $skillsRoot -ClaudeScope $Scope -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
-    $exitCodes.Add($script:LastSyncExitCode)
-}
-
-if ($Target -in @('All', 'Codex')) {
-    Write-Output "== Codex skill mirror =="
-    Sync-CodexSkills -SkillDirs $skillDirs -Root $skillsRoot -SelectedSkill $Skill -OnlyIfMissing:$IfMissing -ReadOnlyCheck:$Check
-    $exitCodes.Add($script:LastSyncExitCode)
-}
-
-if ($exitCodes | Where-Object { $_ -ne 0 }) { exit 1 }
diff --git a/shared/skills/planning/scratch/RANKING.md b/shared/skills/planning/scratch/RANKING.md
deleted file mode 100644
index a7ea4c2..0000000
--- a/shared/skills/planning/scratch/RANKING.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# .scratch Ranking — Formula & Tiebreakers
-
-## Score formula
-
-```
-Score = P × I × E
-```
-
-| Axis | Value | Numeric |
-|------|-------|---------|
-| **P** (priority) | high | 3 |
-| | medium | 2 |
-| | low | 1 |
-| **I** (importance) | high | 3 |
-| | medium | 2 |
-| | low | 1 |
-| **E** (effort, **inverted** — less effort ranks higher) | 4h | 7 |
-| | 1day | 6 |
-| | 2days | 5 |
-| | 1week | 4 |
-| | 2weeks | 3 |
-| | 1month | 2 |
-| | 2months | 1 |
-
-Score range: 3 (low / low / 2months) — 63 (high / high / 4h).
-Higher score = higher in the backlog.
-
-## Tiebreakers (equal score, applied in order)
-
-1. Less effort (lower E_label wins — quick wins first)
-2. Higher importance
-3. Higher priority
-4. Alphabetical by feature slug
-
-## Escalation rule (used by `/planning:scratch-plan`)
-
-When a feature's rank should be raised:
-- If `importance < high` → raise importance one level.
-- If `importance = high` → raise priority one level instead (if `priority < high`).
-
-This prevents phantom "super-high" rankings by routing excess urgency into priority.
-
-## Example
-
-| Feature | P | I | E | Score |
-|---------|---|---|---|-------|
-| auth-refactor | high (3) | high (3) | 1week (4) | 36 |
-| fix-flaky-test | medium (2) | high (3) | 4h (7) | 42 |
-| docs-overhaul | low (1) | medium (2) | 2months (1) | 2 |
-
-Ranked: fix-flaky-test (42) > auth-refactor (36) > docs-overhaul (2).