@mfjjs/ruflo-setup 0.2.7 → 0.2.9

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [0.2.9](///compare/v0.2.8...v0.2.9) (2026-03-31)
+
+### [0.2.8](///compare/v0.2.7...v0.2.8) (2026-03-31)
+
+
+### Features
+
+* **docs:** add related documentation b67343a
+* **docs:** add RuFlo enabled session notes and usage checklist bd9d96a
+* enhance setup process with .gitignore updates and cross-platform compatibility for .mcp.json 4b44558
+
+
+### Bug Fixes
+
+* update toPlatformMcpConfig to use npx instead of pnpm for cross-platform compatibility e7cf99f
+
 ### [0.2.7](///compare/v0.2.6...v0.2.7) (2026-03-20)
 
 

package/README.md

@@ -74,8 +74,9 @@ ruflo-setup
 That's it for most users. The command will:
 1. Check for a newer version of itself and offer to update before proceeding
 2. Install `ruflo@latest` globally and run `ruflo init --full` to scaffold your project
-3. Write a platform-aware `.mcp.json`
-4. Install a global Claude Code `SessionStart` hook
+3. Write a platform-aware `.mcp.json` (MCP servers use `npx` for cross-platform compatibility)
+4. Add `.mcp.json` and `.claude/settings.json` to the project's `.gitignore`
+5. Install a global Claude Code `SessionStart` hook
 
 Additional options:
 
@@ -152,7 +153,7 @@ ruflo-setup cleanup --dry-run
 - `package.json`: npm metadata, scripts, and `bin` mapping
 - `bin/ruflo-setup.js`: executable entry file the shell runs
 - `src/cli.js`: command router and argument handling
-- `src/setup.js`: setup workflow (`init`, `.mcp.json`, template copy)
+- `src/setup.js`: setup workflow (`init`, `.mcp.json`, `.gitignore`, template copy)
 - `src/status.js`: layer-by-layer feature status checker (Layers 0–8)
 - `src/hooks.js`: global `check-ruflo` hook install/status
 - `src/utils.js`: reusable filesystem and argument helpers
@@ -185,7 +186,8 @@ Flow:
 5. `src/setup.js` runs setup steps:
 	 - checks for a newer version of itself and prompts to update
 	 - optional `pnpm add -g ruflo@latest` then `ruflo init --full`
-	 - writes platform-aware `.mcp.json`
+	 - writes platform-aware `.mcp.json` (MCP servers invoked via `npx` for cross-platform compatibility)
+	 - adds `.mcp.json` and `.claude/settings.json` to the project's `.gitignore`
 	 - copies `templates/CLAUDE.md`
 	 - installs global SessionStart hook (unless skipped)
 
@@ -239,3 +241,62 @@ This tests exactly what users get from a package install.
 - `claude-hooks/check-ruflo.cjs`
 
 It merges into existing global settings instead of replacing them, and creates a backup of the settings file before writing.
+
+## 🖥️ Windows vs Linux/WSL differences
+
+`ruflo-setup` supports both Windows and Linux (including WSL), but there are important platform differences to be aware of.
+
+### Platform-specific generated files
+
+The `.mcp.json` and `.claude/settings.json` files generated by `ruflo-setup` contain **platform-specific commands and paths**. For this reason, both files are excluded from version control via `.gitignore`:
+
+```
+.mcp.json
+.claude/settings.json
+```
+
+**Practical implications:**
+
+- These files are not committed and will not be present after cloning a repository.
+- You must rerun `ruflo-setup --force` (or `ruflo-setup --yes`) after cloning into any new folder, especially when switching platforms (e.g. cloning on Windows after previously working on Linux/WSL, or vice versa).
+- Each developer generates their own local copy of these files tailored to their platform.
+
+### Git file permission changes
+
+When switching from Windows to Linux/WSL (or vice versa), you may notice that `git status` shows files as modified even though their content has not changed. This is a **file mode change**: tools such as Claude Code, git, or `ruflo-setup` may have updated the Unix permission bits of tracked files — for example from `0644` (non-executable) to `0755` (executable) — under the hood.
+
+You can confirm this with:
+
+```bash
+git diff --summary
+```
+
+Which will show lines like:
+
+```
+mode change 100644 => 100755 some/file.js
+```
+
+If these mode changes are unintentional, you can discard them with:
+
+```bash
+git checkout -- .
+```
+
+Or suppress mode tracking for the repository entirely:
+
+```bash
+git config core.fileMode false
+```
+
+Note that `core.fileMode false` is a local config setting and is not committed — each developer must set it on their own clone if needed.
+
+### Summary
+
+| Concern | Windows | Linux / WSL |
+|---|---|---|
+| `.mcp.json` commands | Windows-style paths / `cmd.exe` shims | Unix paths / shell commands |
+| `.claude/settings.json` | Windows-native format | Unix format |
+| Git mode changes (0644→0755) | Not tracked by default | May appear as unexpected diffs |
+| Git tracking | Excluded via `.gitignore` | Excluded via `.gitignore` |
+| After cloning | Rerun `ruflo-setup --force` | Rerun `ruflo-setup --force` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfjjs/ruflo-setup",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Cross-platform setup CLI for Ruflo + Claude Flow projects",
   "type": "module",
   "bin": {