refactor: final 100% cross-platform polish

install.md

@@ -51,14 +51,21 @@ If the directory already exists (upgrade scenario), pull the latest instead of c
 
 **Qwen Code note:** Qwen Code does not have a skill plugin system or SessionStart hook. Skills are cloned to `~/.qwen/skills/hyperstack/` and available on disk for the agent to reference manually (via `read_file` or the agent's own knowledge of the repo structure). The 21 skills are not auto-loaded at session start.
 
-To handle both cases automatically, use this one-liner (clone if missing, pull if present):
+To handle both cases automatically, use the one-liner for your platform:
 
+**macOS / Linux (Shell):**
 ```bash
 EXT_DIR="$HOME/.gemini/extensions/hyperstack" && \
   ([ -d "$EXT_DIR" ] && git -C "$EXT_DIR" pull || git clone https://github.com/orkait/hyperstack.git "$EXT_DIR")
 ```
 
-Replace `~/.claude/skills` with the correct path for the current environment (see table above). For example, on Qwen Code use `~/.qwen/skills/hyperstack`.
+**Windows (PowerShell):**
+```powershell
+$EXT_DIR = Join-Path $HOME ".gemini/extensions/hyperstack"
+if (Test-Path $EXT_DIR) { git -C $EXT_DIR pull } else { git clone https://github.com/orkait/hyperstack.git $EXT_DIR }
+```
+
+Replace `~/.claude/skills` or the path variables with the correct path for the current environment (see table above).
 
 The repository includes a `hooks/session-start.mjs` entrypoint that injects the
 generated Hyperstack bootstrap into every session automatically. This is how the
@@ -96,8 +103,12 @@ Or run the hard check manually:
 
 ```bash
 # 1. Remove ANY container based on the hyperstack image
+# macOS/Linux:
 docker ps -aq --filter "ancestor=ghcr.io/orkait/hyperstack:main" | xargs -r docker rm -f
 
+# Windows (PowerShell):
+docker ps -aq --filter "ancestor=ghcr.io/orkait/hyperstack:main" | ForEach-Object { docker rm -f $_ }
+
 # 2. Run the fresh singleton container
 docker run -d --name hyperstack-mcp --restart unless-stopped \
   --memory=512m --cpus=1 \

scripts/generate-skills-index.ts

@@ -3,17 +3,12 @@ import * as path from "path";
 import { fileURLToPath } from "url";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = path.resolve(__dirname, "..");
-const SKILLS_DIR = path.join(REPO_ROOT, "skills");
-const INDEX_FILE = path.join(SKILLS_DIR, "INDEX.md");
-
-interface SkillInfo {
-  name: string;
-  category: string;
-  description: string;
-}
 
-function generateIndex() {
+export function generateIndex() {
+  const REPO_ROOT = path.resolve(__dirname, "..");
+  const SKILLS_DIR = path.join(REPO_ROOT, "skills");
+  const INDEX_FILE = path.join(SKILLS_DIR, "INDEX.md");
+
   console.log("Generating skills index (cross-platform)...");
 
   const skills: SkillInfo[] = [];
@@ -94,4 +89,7 @@ These skills need a \`category:\` added to their frontmatter.
   console.log(`Wrote ${INDEX_FILE}`);
 }
 
-generateIndex();
+// Only run if called directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  generateIndex();
+}

skills/INDEX.md

@@ -1,7 +1,7 @@
 # Hyperstack Skills Index
 
 Auto-generated from each skill's frontmatter `category` field.
-Regenerate with: `bash scripts/generate-skills-index.sh`
+Regenerate with: `bun scripts/generate-skills-index.ts` or `npm run skills:index`
 
 Categories:
 - **core** - workflow, discipline, and gates used on every task
@@ -33,10 +33,10 @@ Categories:
 | Skill | Description |
 |---|---|
 | `behaviour-analysis` | Systematic UI/UX behaviour analysis for interactive applications. Audits every user action, state transition, view mode, |
-| `designer` | Evidence-based design decision engine. Intention gate that produces non-slop |
 | `design-patterns-skill` | Apply core programming principles and design patterns from Clean Code, The Pragmatic Programmer, Code Complete, Refactor |
+| `designer` |  |
 | `readme-writer` | Writes or rewrites project README files using repository evidence instead of generic filler. Use when creating a new REA |
-| `security-review` | Security code review for vulnerabilities. Use when asked to security review, find vulnerabilities, check for security is |
+| `security-review` | Security code review for vulnerabilities. Use when asked to "security review", "find vulnerabilities", "check for securi |
 | `shadcn-expert` | Advanced shadcn/ui architect specializing in Base UI, Tailwind v4, data-slot patterns, and component composition. Use wh |
 
 ## Meta (skills about skills)
@@ -45,3 +45,5 @@ Categories:
 |---|---|
 | `testing-skills` | Use when creating or editing Hyperstack skills, before shipping them, to verify they actually work under pressure and re |
 | `using-hyperstack` | Bootstrap - establishes Hyperstack MCP tools and skills before any technical work. Auto-loaded at session start via Sess |
+
+

skills/using-hyperstack/SKILL.md

@@ -107,7 +107,7 @@ If MCP tools fail or are unavailable:
 
 Use the `Skill` tool to load these before the relevant task type.
 
-**Full skill index:** See `skills/INDEX.md` - all skills grouped by category (core / domain / meta). Regenerate with `bash scripts/generate-skills-index.sh` after adding or editing any skill.
+**Full skill index:** See `skills/INDEX.md` - all skills grouped by category (core / domain / meta). Regenerate with `npm run skills:index` after adding or editing any skill.
 
 ### Announcement Iron Law
 

tests/skills-index-behaviour.test.ts

@@ -1,7 +1,7 @@
 import { test, expect } from "bun:test";
-import { execSync } from "node:child_process";
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { resolve, join } from "node:path";
+import { generateIndex } from "../scripts/generate-skills-index.ts";
 
 const SKILLS_DIR = resolve("skills");
 const INDEX_PATH = resolve("skills/INDEX.md");
@@ -27,7 +27,7 @@ function getSkillCategory(skillName: string): string | null {
 test("skills/INDEX.md stays in sync with actual skill directories", () => {
   const currentIndex = normalize(readFileSync(INDEX_PATH, "utf8"));
 
-  execSync("bash scripts/generate-skills-index.sh", { stdio: "pipe" });
+  generateIndex();
 
   const regenerated = normalize(readFileSync(INDEX_PATH, "utf8"));
   expect(currentIndex).toBe(regenerated);