fix: gstack Cursor skill discovery and naming docs

.claude/skills/README.md

@@ -101,6 +101,11 @@ Override the cache location with `GSTACK_CACHE_DIR`, the upstream ref with
 Cloud Agents: this repo's `.cursor/environment.json` runs the script during
 `install` after `npm ci`.
 
+**Cursor skill names:** After setup, flat `gstack-*` symlinks (e.g. `gstack-plan-ceo-review`)
+appear under `.claude/skills/` for Cursor discovery. Claude Code uses short slash names
+(`/plan-ceo-review`); Cursor uses the `gstack-` prefix. Nested vendored paths
+(`gstack/plan-ceo-review/`) work when you attach or invoke by path either way.
+
 **Cursor host:** Upstream [gstack#2361](https://github.com/garrytan/gstack/issues/2361) fixed `./setup --host cursor` rejection. If an older cache rejects `cursor`, run `GSTACK_REF=main bash scripts/setup-gstack-full.sh`.
 
 **Manual upstream install** (alternative):

.gitignore

@@ -49,6 +49,7 @@ coverage/
 .vitest/
 
 # gstack runtime sidecars (created by scripts/setup-gstack-full.sh; not vendored in git)
+.claude/skills/gstack-*/
 .claude/skills/gstack/bin
 .claude/skills/gstack/lib
 .claude/skills/gstack/browse/

AGENTS.md

@@ -39,6 +39,47 @@ Use **`find-skills`** to discover capabilities; do not load all ~693 skills into
 are fetched at setup time. Cloud Agents run `bash scripts/setup-gstack-full.sh` via
 `.cursor/environment.json`.
 
+### gstack in Cursor (not Claude Code)
+
+gstack is installed, but **Cursor and Claude Code use different skill names**:
+
+| Claude Code slash | Cursor skill name | Vendored path |
+| --- | --- | --- |
+| `/plan-ceo-review` | `gstack-plan-ceo-review` | `.claude/skills/gstack/plan-ceo-review/` |
+| `/office-hours` | `gstack-office-hours` | `.claude/skills/gstack/office-hours/` |
+| `/qa` | `gstack-qa` | `.claude/skills/gstack/qa/` |
+| `/ship` | `gstack-ship` | `.claude/skills/gstack/ship/` |
+
+After `bash scripts/setup-gstack-full.sh`, flat `gstack-*` symlinks also appear under
+`.claude/skills/` (and via `.cursor/skills`) for Cursor discovery. Without the setup script,
+only the nested `gstack/<skill>/` markdown is present — skills work when attached or invoked
+by name, but slash autocomplete may not list them.
+
+**One-time setup (local or Cloud Agent):**
+
+```bash
+bash scripts/setup-gstack-full.sh
+```
+
+## Skill routing
+
+When the user's request matches an available skill, invoke it via the Skill tool. When in doubt, invoke the skill.
+
+Key routing rules:
+- Product ideas/brainstorming → invoke `gstack/office-hours` or `gstack-office-hours`
+- Strategy/scope → invoke `gstack/plan-ceo-review` or `gstack-plan-ceo-review`
+- Architecture → invoke `gstack/plan-eng-review` or `gstack-plan-eng-review`
+- Design system/plan review → invoke `gstack/design-consultation` or `gstack-plan-design-review`
+- Full review pipeline → invoke `gstack/autoplan`
+- Bugs/errors → invoke `gstack/investigate`
+- QA/testing site behavior → invoke `gstack/qa` or `gstack-qa-only`
+- Code review/diff check → invoke `gstack/review`
+- Visual polish → invoke `gstack/design-review`
+- Ship/deploy/PR → invoke `gstack/ship` or `gstack/land-and-deploy`
+- Save progress → invoke `gstack/context-save`
+- Resume context → invoke `gstack/context-restore`
+- Author a backlog-ready spec/issue → invoke `gstack/spec`
+
 ## Agent skills
 
 ### Issue tracker

scripts/setup-gstack-full.sh

@@ -141,6 +141,32 @@ link_repo_and_global_sidecars() {
   link_runtime_sidecar "$GSTACK_CACHE" "$HOME/.claude/skills/gstack"
 }
 
+# Cursor discovers flat gstack-* skill dirs (e.g. gstack-plan-ceo-review), not the
+# nested gstack/plan-ceo-review/ tree used for Claude Code. Link generated cursor
+# skills into the project skill tree so .cursor/skills (→ .claude/skills) picks them up.
+link_cursor_project_skills() {
+  local cursor_src="$GSTACK_CACHE/.cursor/skills"
+  local project_skills="$REPO_ROOT/.claude/skills"
+  local skill_dir skill_name linked=0
+
+  if [ ! -d "$cursor_src" ]; then
+    log "skip cursor project skills (missing $cursor_src — re-run upstream ./setup --host cursor)"
+    return 0
+  fi
+
+  for skill_dir in "$cursor_src"/gstack-*/; do
+    [ -d "$skill_dir" ] || continue
+    [ -f "$skill_dir/SKILL.md" ] || continue
+    skill_name="$(basename "$skill_dir")"
+    link_or_replace "$skill_dir" "$project_skills/$skill_name"
+    linked=$((linked + 1))
+  done
+
+  if [ "$linked" -gt 0 ]; then
+    log "Linked $linked Cursor gstack skill(s) into $project_skills (e.g. gstack-plan-ceo-review)"
+  fi
+}
+
 verify_runtime() {
   local browse_bin="$GSTACK_CACHE/browse/dist/browse"
   local config_bin="$GSTACK_CACHE/bin/gstack-config"
@@ -164,6 +190,7 @@ main() {
   sync_gstack_cache
   run_upstream_setup
   link_repo_and_global_sidecars
+  link_cursor_project_skills
   verify_runtime
   log "Full gstack runtime is ready (cache: $GSTACK_CACHE, ref: $GSTACK_REF)"
 }