From f2f4b1997429b32124ae50d714f33b9bc0ca0a4a Mon Sep 17 00:00:00 2001
From: Coldaine <coldaine@example.com>
Date: Wed, 31 Dec 2025 21:28:07 -0600
Subject: [PATCH] fix: restore agent mirror flexibility

---
 README.md                             | 22 +++++++++++
 docs/MasterDocumentationPlaybook.md   |  6 +--
 docs/dev/CI/architecture.md           |  5 +--
 scripts/ensure_agent_hardlinks.sh     | 53 ++++++++++++++++++++++-----
 scripts/install_git_hardlink_hooks.sh | 22 +++++++++--
 5 files changed, 87 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 8a3816e9..42898ffa 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,28 @@
 
 Minimal root README. Full developer & architecture guide: see [`CLAUDE.md`](CLAUDE.md). Assistants should read [`AGENTS.md`](AGENTS.md).
 
+## Quick Start
+
+Status varies by STT backend and platform. For current “what works” details, see [`docs/plans/critical-action-plan.md`](docs/plans/critical-action-plan.md).
+
+```bash
+# Main app
+just run
+
+# TUI dashboard
+just tui
+```
+
+Common Rust commands:
+
+```bash
+# Fast local feedback
+cargo check -p coldvox-app
+
+# Format check
+cargo fmt --all -- --check
+```
+
 ## Development
 
 ### Developer Git Hooks
diff --git a/docs/MasterDocumentationPlaybook.md b/docs/MasterDocumentationPlaybook.md
index 8c943274..c4c4c805 100644
--- a/docs/MasterDocumentationPlaybook.md
+++ b/docs/MasterDocumentationPlaybook.md
@@ -93,13 +93,13 @@ The following files configure AI coding agents and MUST live at standard locatio
 
 - `AGENTS.md` (root): Canonical agent instructions following the [AGENTS.md standard](https://agents.md/). This is the single source of truth for all AI agents.
 - `CLAUDE.md` (root): Claude Code configuration. Should import from or reference `AGENTS.md`.
-- `.github/copilot-instructions.md`: GitHub Copilot instructions. Must match `AGENTS.md` (locally hardlinked where possible).
-- `.kilocode/rules/agents.md`: Kilo Code rules. Must match `AGENTS.md` (locally hardlinked where possible).
+- `.github/copilot-instructions.md`: GitHub Copilot instructions. Must match `AGENTS.md` (hardlink preferred; symlink/copy acceptable where needed).
+- `.kilocode/rules/agents.md`: Kilo Code rules. Must match `AGENTS.md` (hardlink preferred; symlink/copy acceptable where needed).
 - `.gemini/settings.json`: Gemini CLI configuration. Set `"contextFileName": "AGENTS.md"` to use root AGENTS.md.
 - `.cursorrules` (root, optional): Cursor-specific rules if needed beyond `AGENTS.md`.
 - `.builderrules` (root, optional): Builder.io-specific rules if needed.
 
-**Hierarchy**: `AGENTS.md` is authoritative. Tool-specific files should either be hardlinked mirrors (preferred) or contain only tool-specific overrides that reference `AGENTS.md`.
+**Hierarchy**: `AGENTS.md` is authoritative. Tool-specific files should either mirror it (hardlink preferred; symlink/copy acceptable) or contain only tool-specific overrides that reference `AGENTS.md`.
 
 **Do NOT create** `docs/agents.md` - agent configuration lives at the root for tool discovery.
 
diff --git a/docs/dev/CI/architecture.md b/docs/dev/CI/architecture.md
index 3cabf40c..27a547b7 100644
--- a/docs/dev/CI/architecture.md
+++ b/docs/dev/CI/architecture.md
@@ -210,7 +210,7 @@ jobs:
       - run: cargo deny check
 
   # ═══════════════════════════════════════════════════════════════
-  # SELF-HOSTED: THE build, THE tests (runs immediately, no waiting)
+  # SELF-HOSTED: Hardware/display-only tests (runs immediately, no waiting)
   # ═══════════════════════════════════════════════════════════════
 
   hardware:
@@ -235,9 +235,6 @@ jobs:
           shared-key: "nobara-hardware"
           cache-on-failure: true
 
-      - name: Build (cached, incremental)
-        run: cargo build -p coldvox-text-injection -p coldvox-app --locked
-
       - name: Validate display environment
         run: |
           echo "DISPLAY=$DISPLAY"
diff --git a/scripts/ensure_agent_hardlinks.sh b/scripts/ensure_agent_hardlinks.sh
index 0b685ddb..594f92a6 100755
--- a/scripts/ensure_agent_hardlinks.sh
+++ b/scripts/ensure_agent_hardlinks.sh
@@ -2,9 +2,19 @@
 set -euo pipefail
 
 quiet=0
-if [[ "${1:-}" == "--quiet" ]]; then
-  quiet=1
-fi
+require_hardlink=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --quiet) quiet=1 ;;
+    --require-hardlink) require_hardlink=1 ;;
+    *)
+      echo "error: unknown arg: $arg" >&2
+      echo "usage: $0 [--quiet] [--require-hardlink]" >&2
+      exit 64
+      ;;
+  esac
+done
 
 repo_root="$({
   cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd
@@ -54,7 +64,7 @@ link_count_of() {
   return 1
 }
 
-link_or_copy() {
+link_or_symlink_or_copy() {
   local dst="$1"
 
   # Remove symlinks explicitly; ln -f replaces regular files but not all symlinks reliably.
@@ -62,13 +72,32 @@ link_or_copy() {
     rm -f "$dst"
   fi
 
+  # 1) Prefer hardlink.
   if ln -f "$src" "$dst" 2>/dev/null; then
     return 0
   fi
 
-  # If hardlinking fails (e.g., cross-filesystem), keep content correct but warn.
+  # 2) Fallback to symlink (works across filesystems).
+  local rel
+  rel="$(python - <<'PY'
+import os
+import sys
+src = sys.argv[1]
+dst = sys.argv[2]
+print(os.path.relpath(src, os.path.dirname(dst)))
+PY
+"$src" "$dst" 2>/dev/null || true)"
+
+  if [[ -n "$rel" ]]; then
+    if ln -sf "$rel" "$dst" 2>/dev/null; then
+      echo "warning: could not hardlink $dst; created symlink instead" >&2
+      return 0
+    fi
+  fi
+
+  # 3) Last resort: copy contents.
   cp -f "$src" "$dst"
-  echo "warning: could not hardlink $dst; copied contents instead" >&2
+  echo "warning: could not hardlink or symlink $dst; copied contents instead" >&2
   return 0
 }
 
@@ -91,7 +120,7 @@ is_hardlinked_pair() {
 ensure_pair() {
   local dst="$1"
 
-  link_or_copy "$dst"
+  link_or_symlink_or_copy "$dst"
 
   if ! cmp -s "$src" "$dst"; then
     echo "error: $dst does not match $src" >&2
@@ -99,9 +128,13 @@ ensure_pair() {
   fi
 
   if ! is_hardlinked_pair "$src" "$dst"; then
-    echo "error: $dst is not hardlinked to $src (same contents, different inode)" >&2
-    echo "hint: ensure both files are on the same filesystem; rerun scripts/ensure_agent_hardlinks.sh" >&2
-    exit 2
+    if [[ "$require_hardlink" -eq 1 ]]; then
+      echo "error: $dst is not hardlinked to $src (same contents, different inode)" >&2
+      echo "hint: ensure both files are on the same filesystem; rerun scripts/ensure_agent_hardlinks.sh" >&2
+      exit 2
+    fi
+
+    echo "warning: $dst is not hardlinked to $src (content matches)" >&2
   fi
 }
 
diff --git a/scripts/install_git_hardlink_hooks.sh b/scripts/install_git_hardlink_hooks.sh
index 97596c26..3d5ab12a 100755
--- a/scripts/install_git_hardlink_hooks.sh
+++ b/scripts/install_git_hardlink_hooks.sh
@@ -2,9 +2,19 @@
 set -euo pipefail
 
 quiet=0
-if [[ "${1:-}" == "--quiet" ]]; then
-  quiet=1
-fi
+require_hardlink=0
+
+for arg in "$@"; do
+  case "$arg" in
+    --quiet) quiet=1 ;;
+    --require-hardlink) require_hardlink=1 ;;
+    *)
+      echo "error: unknown arg: $arg" >&2
+      echo "usage: $0 [--quiet] [--require-hardlink]" >&2
+      exit 64
+      ;;
+  esac
+done
 
 repo_root="$({
   cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd
@@ -35,4 +45,8 @@ if [[ "$quiet" -eq 0 ]]; then
   fi
 fi
 
-"$repo_root/scripts/ensure_agent_hardlinks.sh" ${quiet:+--quiet}
+ensure_args=()
+if [[ "$quiet" -eq 1 ]]; then ensure_args+=(--quiet); fi
+if [[ "$require_hardlink" -eq 1 ]]; then ensure_args+=(--require-hardlink); fi
+
+"$repo_root/scripts/ensure_agent_hardlinks.sh" "${ensure_args[@]}"