feat: universal platform support - 12 IDEs/CLIs with format-aware patching

.gitignore

@@ -2,6 +2,6 @@ node_modules/
 dist/
 *.js.map
 
-# Research archive — lives at ../knowledgebase/ outside this repo.
+# Research archive - lives at ../knowledgebase/ outside this repo.
 # Ignored here as a safety net in case it gets re-introduced by mistake.
 knowledgebase/

docs/AGENTS.md

@@ -0,0 +1,73 @@
+# final steering doc
+
+## 1. core law
+
+* facts first.
+* no bluff.
+* no fake results.
+* no puppy talk.
+* less talk. more work.
+* evidence beats guess.
+* fast isolated test beats hypothesis.
+* suggestion is not truth. treat research hits as maybe true until verified.
+* if unsure, say so.
+* if change gives no gain, stop, alert user, suggest better path.
+
+## 2. role
+
+* role: autonomous operations agent
+* default mode: act, verify, report
+* use tools and direct evidence before making claims
+* treat local steering files as binding input when present
+
+## 3. source priority
+
+use this order:
+
+1. explicit user instruction in current task
+2. system and platform hard limits
+3. local steering docs and skill docs
+4. repository code and config
+5. tests, command output, logs, api responses
+6. docs and research notes
+7. prior belief or intuition
+
+rules:
+
+* do not impose beliefs as facts.
+* do not claim cause and effect without proof.
+* do not present hypothesis as result.
+* one verified fact beats ten plausible guesses.
+
+## 4. local steering files
+
+load and obey when present:
+
+* `~/.claude/CLAUDE.md`
+* `./skills/using-hyperstack/SKILL.md`
+* any task-specific skill doc the user points to
+* repo-local agent or steering docs
+
+rules:
+
+* if user says `recall memory`, also read `~/.claude/CLAUDE.md`.
+* if using codemode or exploring codebase, follow codemode fully. no shortcuts.
+* read files before semantic linking. no context = no real linking.
+
+## 5. tool-first execution
+
+always prefer tools over guess.
+
+## 6. deployment & project context
+
+| key | value |
+|---|---|
+| pages project | `nitrogen-orkait` |
+| production url | `nitrogen-orkait.pages.dev` |
+| mcp server | user scope in `~/.claude.json` |
+| wrangler | auth via oauth, use `npx wrangler` |
+
+```bash
+# deployment command
+wrangler pages deploy <dist-dir> --project-name nitrogen-orkait --branch main
+```

install.md

@@ -18,7 +18,7 @@ If you only remember four things, remember these:
 Three tightly-coupled pieces, installed together:
 
 1. **An internal harness** - bootstrap, internal role routing, and workflow control. Current internal roles include `main` and `website-builder`.
-2. **An MCP server** with 11 plugins and 79 tools - deterministic knowledge for React Flow v12, Motion v12, Lenis, React 19 / Next.js, Echo, Go, Rust, design tokens, UI/UX principles, shadcn/ui (Base UI edition), and the `designer` DESIGN.md pipeline.
+2. **An MCP server** with 12 plugins and 80 tools - deterministic knowledge for React Flow v12, Motion v12, Lenis, React 19 / Next.js, Echo, Go, Rust, design tokens, UI/UX principles, shadcn/ui (Base UI edition), and the `designer` DESIGN.md pipeline.
 3. **A skill system** with 21 skills including adversarial enforcement gates (`blueprint`, `designer`, `forge-plan`, `ship-gate`, `engineering-discipline`) and a SessionStart hook that force-injects the `using-hyperstack` skill at every session start.
 
 The install steps below wire the public pieces the user actually needs: the MCP
@@ -53,7 +53,9 @@ If Docker is not available, you can explicitly request the local method: `hypers
 
 ## Step 2: Install the Skills
 
-Clone the repository to a stable location on your system.
+The skills contain the adversarial enforcement gates. You must clone them to a stable central location and then link them to the specific IDE/CLI rule directory.
+
+### 1. Central Repository
 
 **macOS / Linux (Shell):**
 ```bash
@@ -67,6 +69,19 @@ $EXT_DIR = Join-Path $HOME ".hyperstack"
 if (Test-Path $EXT_DIR) { git -C $EXT_DIR pull } else { git clone https://github.com/orkait/hyperstack.git $EXT_DIR }
 ```
 
+### 2. Environment-Specific Linking
+
+Based on the environment you detected in Step 1, identify the correct target directory to enable the skills:
+
+| IDE/CLI | Target Skill Path | Type |
+|---|---|---|
+| **Claude Code** | `~/.claude/skills/hyperstack` | Global |
+| **Cursor** | `.cursor/rules/` | Project-level |
+| **Roo Code** | `.roo/rules/` | Project-level |
+| **Windsurf** | `.codeium/windsurf/` | Project-level |
+
+As an agent, you should **symlink** the `~/.hyperstack/skills` directory to the target path above. This ensures updates to the central repo are immediately reflected in your active session.
+
 ## Step 3: Configure the MCP Server
 
 ```json
@@ -183,16 +198,16 @@ Once the pre-check passes, start a fresh session in the target environment (or r
 
 2. **Skills are on disk:** Confirm the skills directory exists and has content:
    ```bash
-   ls ~/.claude/skills/hyperstack/skills/   # or ~/.qwen/skills/hyperstack/skills/ for Qwen Code
+   ls ~/.hyperstack/skills/
    ```
    Should show 21 directories plus `INDEX.md`. If missing or empty, the clone failed.
 
-3. **Skills are auto-loaded (platforms with hooks only):** Ask: *"What Hyperstack skills are available?"* The agent should list skills from `skills/INDEX.md` (21 total, grouped into core / domain / meta). On platforms without hook support (e.g., Qwen Code), skip this - skills are on disk but not auto-injected.
+3. **Skills are auto-loaded (platforms with hooks only):** Ask: *"What Hyperstack skills are available?"* The agent should list skills from `skills/INDEX.md` (21 total, grouped into core / domain / meta). On platforms without hook support, skip this - skills are on disk but not auto-injected.
 
 If any of these three checks fail, do not proceed. Fix the issue first:
 - MCP tool unknown → verify config file location and JSON syntax, then restart the session
 - Skills missing → re-run the clone command and confirm the path
-- Skills not auto-loaded → check that the platform supports `.claude-plugin/hooks.json`; if not, this is expected behavior
+- Skills not auto-loaded → check if your tool (e.g. Claude Code) supports hooks/plugin auto-loading.
 
 ---
 
@@ -272,3 +287,20 @@ On Qwen Code, there is no plugin system or hook mechanism. Skills are available
 ### `bun: command not found` when using Option B
 
 Install Bun: `curl -fsSL https://bun.sh/install | bash`, then open a new shell so the path update takes effect.
+
+## Step 5: Welcome the User to Hyperstack
+
+Once all verifications pass, your final action is to explain the new reality to the user. Do not just say "installed." Explain the **Disciplined Engineering Harness**.
+
+**Recommended Success Message:**
+
+> "System Synchronized. Hyperstack is now active.
+> 
+> I have installed the **Disciplined Engineering Harness** with 12 plugins and 80 tools. I have also established your **Iron Laws** (~/.hyperstack/skills).
+> 
+> From now on:
+> - I will not refactor code without a failing test.
+> - I will not propose designs without a DESIGN.md contract.
+> - I will use the ground-truth primitives provided by the Hyperstack vault.
+> 
+> We are now operating under a professional engineering discipline. How should we begin our first high-integrity task?"

package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orkait-ai/hyperstack",
   "version": "1.0.5",
-  "description": "Disciplined MCP server + skill system. 11 plugins, 79 tools, 21 skills with adversarial enforcement. Designer/DESIGN.md pipeline, shadcn/ui, React Flow, Motion, Lenis, React 19, Echo, Go, Rust, design tokens, UI/UX.",
+  "description": "Disciplined MCP server + skill system. 12 plugins, 80 tools, 21 skills with adversarial enforcement. Designer/DESIGN.md pipeline, shadcn/ui, React Flow, Motion, Lenis, React 19, Echo, Go, Rust, design tokens, UI/UX.",
   "bin": {
     "hyperstack": "bin/hyperstack.mjs"
   },

scripts/setup.ts

@@ -6,33 +6,55 @@ async function main() {
   console.log("\n🚀 Hyperstack Autonomous Setup (CLI)");
   console.log("=====================================\n");
 
-  const platform = setup.detectEnvironment();
-  console.log(`📡 Detected platform: ${platform}`);
+  const hintedPlatform = setup.detectEnvironment();
+  console.log(`📡 Hinted platform: ${hintedPlatform}`);
+
+  const configPath = setup.findConfigFile(hintedPlatform);
 
-  const configPath = setup.findConfigFile(platform);
-
   if (!configPath) {
-    console.warn("⚠️  Could not automatically find an MCP configuration file.");
-    console.log(`Check ${platform} documentation for the correct 'mcp.json' or settings path.`);
+    console.warn("⚠️  Could not find an MCP configuration file in any known location.");
+    console.log("Tried: .claude.json, .cursor/mcp.json, .codeium/windsurf/mcp_config.json, .roo/mcp.json, .gemini/settings.json, .kiro/settings/mcp.json, .qwen/settings.json");
+    console.log("\n💡 OpenAI Codex CLI? Run: codex mcp add hyperstack -- bun ~/.hyperstack/bin/hyperstack.mjs");
+    console.log("   For any unknown IDE, use the Agentic Autopilot instead.");
     process.exit(1);
   }
 
-  console.log(`✅ Found config: ${configPath}`);
+  // Resolve the actual platform from the found config path
+  const platform = setup.detectPlatformFromConfigPath(configPath);
+  console.log(`✅ Found config: ${configPath} (${platform})`);
+
+  const skillPath = setup.findSkillPath(platform);
+  if (skillPath) {
+    const hyperstackSkills = path.join(process.cwd(), "skills");
+    const skillTarget = path.join(skillPath, "hyperstack");
+    console.log(`\n📚 Skill target: ${skillTarget}`);
+    console.log(`Run this to activate adversarial gates:`);
+    console.log(`  ln -s "${hyperstackSkills}" "${skillTarget}"`);
+  }
 
   const pluginRoot = process.cwd();
-  const patch = setup.generateMcpPatch(configPath, pluginRoot);
+  const patch = setup.generateMcpPatch(configPath, pluginRoot, platform);
 
-  console.log("\nProposed MCP Configuration Patch:");
+  console.log("\n📋 Proposed Configuration Patch:");
   console.log("---------------------------------");
-  console.log(JSON.stringify(patch, null, 2));
-  console.log("---------------------------------\n");
-
-  console.log("To apply this patch:");
-  console.log(`1. Open ${configPath}`);
-  console.log("2. Merged the 'hyperstack' entry into your 'mcpServers' or 'extensions' block.");
-  console.log("3. Restart your AI client.");
-
-  console.log("\nFor an automated autopilot installation, call the 'hyperstack_setup' tool from within your AI assistant.\n");
+
+  if (patch.format === "toml-mcp_servers") {
+    console.log("# Append this to:", configPath);
+    console.log(patch.content as string);
+    console.log("---------------------------------\n");
+    console.log("To finish manual setup:");
+    console.log(`1. Run the symlink command above (if applicable).`);
+    console.log(`2. Append the TOML block above to ${configPath}`);
+    console.log("3. Run 'codex /mcp' to verify the connection.");
+  } else {
+    console.log(JSON.stringify(patch.content, null, 2));
+    console.log("---------------------------------\n");
+    console.log("To finish manual setup:");
+    console.log(`1. Run the symlink command above (if applicable).`);
+    console.log(`2. Open ${configPath}`);
+    console.log("3. Merge the patch above into your config (deep-merge, don't replace).");
+    console.log("4. Restart your AI client.");
+  }
 }
 
 main().catch(console.error);