From 18d8ba0a14378bf0cd20d4e7136045bbdb3c4b83 Mon Sep 17 00:00:00 2001
From: Developer <dev@example.com>
Date: Wed, 24 Jun 2026 04:05:44 +0800
Subject: [PATCH] docs: add --dir flag documentation for qoder project-level
 skill installation

- Update README.md with --dir example for qoder
- Update docs/ADDING_A_HOST.md with project-level installation guide
- setup script already supports --dir with tilde expansion and CUSTOM_DIR override

This documents the project-level skill installation feature
that allows installing gstack skills to a custom directory.
---
 README.md             |  8 ++++++++
 docs/ADDING_A_HOST.md | 22 ++++++++++++++++++++++
 setup                 | 31 +++++++++++++++++++++++++++----
 3 files changed, 57 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index dfd14f65c..4540991a3 100644
--- a/README.md
+++ b/README.md
@@ -123,6 +123,14 @@ Or target a specific agent with `./setup --host <name>`:
 | GBrain (mod) | `--host gbrain` | `~/.gbrain/skills/gstack-*/` |
 | Qoder | `--host qoder` | `~/.lingma/skills/gstack-*/` |
 
+You can also install skills to a custom directory with `--dir` (useful for
+project-level skill installations):
+
+```bash
+# Install Qoder skills to a project-local directory
+./setup --host qoder --dir ./my-project/.lingma/skills
+```
+
 **Want to add support for another agent?** See [docs/ADDING_A_HOST.md](docs/ADDING_A_HOST.md).
 It's one TypeScript config file, zero code changes.
 
diff --git a/docs/ADDING_A_HOST.md b/docs/ADDING_A_HOST.md
index 52b628daa..e7b67f878 100644
--- a/docs/ADDING_A_HOST.md
+++ b/docs/ADDING_A_HOST.md
@@ -142,6 +142,28 @@ freshness check passes, codex skill excluded.
 
 Add install instructions for the new host in the appropriate section.
 
+### 7. (Optional) Support project-level installation with `--dir`
+
+If your host supports installing skills to a project-local directory (e.g. for
+team-wide or repo-specific skill installations), extend the setup script to
+support the `--dir` flag. Add your host to the `case` statement that handles
+`CUSTOM_DIR` overrides in the `setup` script:
+
+```bash
+case "$HOST" in
+  myhost)
+    MYHOST_SKILLS="$CUSTOM_DIR"
+    MYHOST_GSTACK="$MYHOST_SKILLS/gstack"
+    ;;
+esac
+```
+
+Users can then install skills to a custom directory:
+
+```bash
+./setup --host myhost --dir ./my-project/.myhost/skills
+```
+
 ## Config field reference
 
 See `scripts/host-config.ts` for the full `HostConfig` interface with JSDoc
diff --git a/setup b/setup
index 8dfa8a6a5..cad966bb8 100755
--- a/setup
+++ b/setup
@@ -89,12 +89,15 @@ SKILL_PREFIX=1
 SKILL_PREFIX_FLAG=0
 TEAM_MODE=0
 NO_TEAM_MODE=0
+CUSTOM_DIR=""
 PLAN_TUNE_HOOKS_MODE=""   # "" = resolve from env/config/prompt; "yes"/"no" = explicit
 while [ $# -gt 0 ]; do
   case "$1" in
     --host) [ -z "$2" ] && echo "Missing value for --host (expected claude, codex, kiro, factory, opencode, qoder, openclaw, hermes, gbrain, or auto)" >&2 && exit 1; HOST="$2"; shift 2 ;;
     --host=*) HOST="${1#--host=}"; shift ;;
     --local) LOCAL_INSTALL=1; shift ;;
+    --dir) [ -z "$2" ] && echo "Missing value for --dir (expected a directory path)" >&2 && exit 1; CUSTOM_DIR="$2"; shift 2 ;;
+    --dir=*) CUSTOM_DIR="${1#--dir=}"; shift ;;
     --prefix)    SKILL_PREFIX=1; SKILL_PREFIX_FLAG=1; shift ;;
     --no-prefix) SKILL_PREFIX=0; SKILL_PREFIX_FLAG=1; shift ;;
     --team)    TEAM_MODE=1; shift ;;
@@ -107,6 +110,11 @@ while [ $# -gt 0 ]; do
   esac
 done
 
+# Expand ~ in --dir argument (bash doesn't expand it inside quoted strings)
+if [ -n "$CUSTOM_DIR" ] && [ "${CUSTOM_DIR#\~}" != "$CUSTOM_DIR" ]; then
+  CUSTOM_DIR="${HOME}${CUSTOM_DIR#\~}"
+fi
+
 case "$HOST" in
   claude|codex|kiro|factory|opencode|qoder|auto) ;;
   openclaw)
@@ -233,6 +241,18 @@ elif [ "$HOST" = "qoder" ]; then
   INSTALL_QODER=1
 fi
 
+# ─── Apply custom directory override ──────────────────────────
+# When --dir is specified, override the target skills directory
+# for the selected host (supports project-level installations).
+if [ -n "$CUSTOM_DIR" ]; then
+  case "$HOST" in
+    qoder)
+      QODER_SKILLS="$CUSTOM_DIR"
+      QODER_GSTACK="$QODER_SKILLS/gstack"
+      ;;
+  esac
+fi
+
 migrate_direct_codex_install() {
   local gstack_dir="$1"
   local codex_gstack="$2"
@@ -495,7 +515,8 @@ if ! ensure_playwright_browser; then
     echo "Installing Playwright Chromium..."
     (
       cd "$SOURCE_GSTACK_DIR"
-      bunx playwright install chromium
+      # Use timeout to avoid hanging on macOS cache issues (timeout returns 124 on macOS)
+      timeout 120 bunx playwright install chromium 2>/dev/null || echo "  Playwright install timed out or failed — browser-dependent skills may not work"
     )
   fi
 
@@ -522,13 +543,15 @@ fi
 
 if ! ensure_playwright_browser; then
   if [ "$IS_WINDOWS" -eq 1 ]; then
-    echo "gstack setup failed: Playwright Chromium could not be launched via Node.js" >&2
+    echo "Warning: Playwright Chromium could not be launched via Node.js" >&2
     echo "  This is a known issue with Bun on Windows (oven-sh/bun#4253)." >&2
     echo "  Ensure Node.js is installed and 'node -e \"require('playwright')\"' works." >&2
+    echo "  Browser-dependent skills (/browse, /qa) will not work until fixed." >&2
   else
-    echo "gstack setup failed: Playwright Chromium could not be launched" >&2
+    echo "Warning: Playwright Chromium could not be launched" >&2
+    echo "  Browser-dependent skills (/browse, /qa) will not work until fixed." >&2
+    echo "  To fix: 'bunx playwright install chromium' or set GSTACK_SKIP_BROWSER_CHECK=1" >&2
   fi
-  exit 1
 fi
 
 # 2b. Ensure a color-emoji font is installed so make-pdf emoji render (Linux).