fix(paths): findMarkdownFilesRecursive follows symlinks (closes #1501)

`Dirent.isFile()` returns false for symlinks, so symlinked `.md`
files in the search root were silently skipped. This made
team-shared command directories that get exposed to Archon via
symlinks (a `~/.archon/commands/foo.md` → `/path/to/team-repo/...`
pattern) unusable — workflow nodes referencing those commands
failed with `Command prompt not found` even though the file was
present and readable.

Workflow discovery in `loadWorkflowsFromDir` already handles this
correctly by stat()-ing each entry; this brings command discovery
in line.

Implementation: when a `Dirent` is a symlink, follow it with
`stat()` and use the target's `isFile()` / `isDirectory()` for the
branch decision. Broken symlinks are skipped silently (matches the
existing tolerance for missing search dirs at the top of the
function).

Tests cover: symlinked file in the search root, mixed regular +
symlinked entries in the same dir, symlinked subdirectory, broken
symlink. All four exercise the new branch.

Author: blankse

packages/paths/src/archon-paths.test.ts

@@ -36,7 +36,9 @@ import {
   resolveProjectRootFromCwd,
   ensureProjectStructure,
   createProjectSourceSymlink,
+  findMarkdownFilesRecursive,
 } from './archon-paths';
+import { symlink as fsSymlink } from 'fs/promises';
 
 /** All env vars that path functions depend on */
 const ENV_VARS = ['WORKSPACE_PATH', 'WORKTREE_BASE', 'ARCHON_HOME', 'ARCHON_DOCKER', 'HOME'];
@@ -776,3 +778,69 @@ describe('createProjectSourceSymlink', () => {
     expect(stats.isSymbolicLink()).toBe(true);
   });
 });
+
+// ─────────────────────────────────────────────────────────────────────────
+// findMarkdownFilesRecursive — symlink handling
+//
+// Regression tests for #1501: symlinked .md files (e.g. team-shared
+// commands made available via `~/.archon/commands/foo.md` → repo path)
+// must be discovered, not silently ignored.
+// ─────────────────────────────────────────────────────────────────────────
+
+describe.skipIf(isWindows)('findMarkdownFilesRecursive — symlinks', () => {
+  let tempRoot: string;
+  let realRepo: string;
+
+  beforeEach(async () => {
+    const ts = Date.now() + Math.random();
+    tempRoot = join(tmpdir(), `archon-find-md-${ts}`);
+    realRepo = join(tmpdir(), `archon-find-md-source-${ts}`);
+    await mkdir(tempRoot, { recursive: true });
+    await mkdir(realRepo, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await rm(tempRoot, { recursive: true, force: true });
+    await rm(realRepo, { recursive: true, force: true });
+  });
+
+  test('finds .md file reached via symlink in the search root', async () => {
+    // Real source file in a "team repo"-shaped location
+    await writeFile(join(realRepo, 'team-cmd.md'), '# team command');
+
+    // Symlink it into the search root (same shape as sync-to-archon.sh)
+    await fsSymlink(join(realRepo, 'team-cmd.md'), join(tempRoot, 'team-cmd.md'));
+
+    const found = await findMarkdownFilesRecursive(tempRoot);
+    expect(found.map(e => e.commandName)).toContain('team-cmd');
+  });
+
+  test('mixes regular files and symlinks in the same directory', async () => {
+    await writeFile(join(tempRoot, 'plain.md'), '# plain');
+    await writeFile(join(realRepo, 'linked.md'), '# linked');
+    await fsSymlink(join(realRepo, 'linked.md'), join(tempRoot, 'linked.md'));
+
+    const found = await findMarkdownFilesRecursive(tempRoot);
+    const names = found.map(e => e.commandName).sort();
+    expect(names).toEqual(['linked', 'plain']);
+  });
+
+  test('descends into a symlinked directory of .md files', async () => {
+    const realSubdir = join(realRepo, 'group');
+    await mkdir(realSubdir, { recursive: true });
+    await writeFile(join(realSubdir, 'inside.md'), '# inside');
+
+    await fsSymlink(realSubdir, join(tempRoot, 'group'));
+
+    const found = await findMarkdownFilesRecursive(tempRoot);
+    expect(found.map(e => e.commandName)).toContain('inside');
+  });
+
+  test('skips broken symlinks silently', async () => {
+    await writeFile(join(tempRoot, 'real.md'), '# real');
+    await fsSymlink(join(realRepo, 'gone.md'), join(tempRoot, 'broken.md'));
+
+    const found = await findMarkdownFilesRecursive(tempRoot);
+    expect(found.map(e => e.commandName)).toEqual(['real']);
+  });
+});

packages/paths/src/archon-paths.ts

@@ -16,7 +16,7 @@
 
 import { join, dirname, normalize, basename } from 'path';
 import { homedir } from 'os';
-import { access, mkdir, symlink, lstat, readdir, readlink, rm } from 'fs/promises';
+import { access, mkdir, symlink, lstat, readdir, readlink, rm, stat } from 'fs/promises';
 import { createLogger } from './logger';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
@@ -238,7 +238,28 @@ export async function findMarkdownFilesRecursive(
       continue;
     }
 
-    if (entry.isDirectory()) {
+    // Resolve the entry's actual type, following symlinks so that team-shared
+    // command/workflow files made available via symlink (e.g. `~/.archon/commands/foo.md`
+    // → `/path/to/team-repo/commands/foo.md`) are picked up. `Dirent.isFile()` /
+    // `Dirent.isDirectory()` both return false for symlinks, so without the
+    // stat() they would be silently skipped.
+    let isDir: boolean;
+    let isFile: boolean;
+    if (entry.isSymbolicLink()) {
+      try {
+        const targetStat = await stat(join(fullPath, entry.name));
+        isDir = targetStat.isDirectory();
+        isFile = targetStat.isFile();
+      } catch {
+        // Broken symlink — skip silently
+        continue;
+      }
+    } else {
+      isDir = entry.isDirectory();
+      isFile = entry.isFile();
+    }
+
+    if (isDir) {
       // Skip descending if we're already at the depth cap — files at deeper
       // levels are silently ignored (matches the convention that `.archon/*/`
       // folders support one level of grouping like `defaults/`).
@@ -249,7 +270,7 @@ export async function findMarkdownFilesRecursive(
         options
       );
       results.push(...subResults);
-    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+    } else if (isFile && entry.name.endsWith('.md')) {
       results.push({
         commandName: basename(entry.name, '.md'),
         relativePath: join(relativePath, entry.name),