refacil-sdd-ai 5.2.0 → 5.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Refacil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -51,7 +51,14 @@ In each repo where you want to use the methodology, open the IDE and run:
 /refacil:setup
 ```
 
-This generates `AGENTS.md` and the `.agents/` project index for that repo. It is the only step required per repo. Skills will prompt you to run it if it has not been done yet.
+`/refacil:setup`:
+
+1. Scaffolds **`AGENTS.md`**, **`.agents/`**, **`refacil-sdd/changes/`**, and project branch configuration (everything the methodology needs for **this codebase**).
+2. Runs **`refacil-sdd-ai sync-repo-ide`** from the **repository root** so per-repo stubs and excludes match **your IDE selection from `init`** (`~/.refacil-sdd-ai/selected-ides.json`): **`CLAUDE.md`**, **`.cursorrules`**, **`.claudeignore`**, **`.cursorignore`**, **`.opencodeignore`**, plus **`compact-guidance`** / **`testing-policy`** markers when **`AGENTS.md`** / **`.agents/testing.md`** exist (same logic as **`init`** / **`update`** for those files).
+
+You can run **`refacil-sdd-ai sync-repo-ide`** manually anytime from the repo root (e.g. after changing IDE selection). It does **not** reinstall global skills — only repo-local files driven by **`selected-ides.json`** (with the same fallback detection as **`update`** when that file is missing).
+
+Skills will prompt you to run `/refacil:setup` if the repo index is missing.
 
 ### Adding a new IDE to an existing installation
 
@@ -91,6 +98,7 @@ npm uninstall -g refacil-sdd-ai
 |---|---|
 | `refacil-sdd-ai init` | Install skills and hooks into global IDE user directories |
 | `refacil-sdd-ai update` | Re-copy skills and hooks to the latest version (global) |
+| `refacil-sdd-ai sync-repo-ide` | Repo-only: `CLAUDE.md`, `.cursorrules`, ignore files, compact-guidance + testing-policy markers — IDE list from `selected-ides.json` (same as `/refacil:setup` Step 4b–5). No global reinstall |
 | `refacil-sdd-ai migration-pending [--json]` | Same detection as hooks/`notify-update`; exit 1 if migration is pending; on exit 0 also deletes obsolete `.refacil-pending-update` (same as at the start of `check-update`) |
 | `refacil-sdd-ai clean` | Remove SDD-AI skills and hooks from global IDE user directories |
 | `refacil-sdd-ai help` | Show help |
@@ -196,7 +204,7 @@ All invoked as `/refacil:<name>` in Claude Code, Cursor, OpenCode, or Codex.
 
 | Skill | Usage |
 |---|---|
-| `/refacil:setup` | Generate AGENTS.md and the `.agents/` project index |
+| `/refacil:setup` | Generate AGENTS.md, `.agents/`, `refacil-sdd/changes/`, branch config; **`sync-repo-ide`** (stubs, ignores, session markers for IDEs chosen in **`init`**) |
 | `/refacil:guide` | Interactive guide on which command to use |
 | `/refacil:explore` | Explore the codebase without modifying anything |
 | `/refacil:propose` | Create a change proposal: proposal + specs + design + tasks |
@@ -509,15 +517,15 @@ Skills, sub-agents, and hooks are installed into the user's global IDE directori
 
 ### Per repo (generated by `/refacil:setup`)
 
-The only per-repo step is running `/refacil:setup` once per project. It generates the project index — no IDE skills or hooks are written to the repo.
+The per-repo step is **`/refacil:setup`** once per project. It generates the **project index** (**`AGENTS.md`**, **`.agents/`**, **`refacil-sdd/changes/`**) and invokes **`refacil-sdd-ai sync-repo-ide`**, which writes **stub + ignore files** according to **`~/.refacil-sdd-ai/selected-ides.json`** (no need for `.claude/` / `.cursor/` folders in the repo). **Skills and hooks remain global**, not copied into the project.
 
 ```
-# Shared (IDE-agnostic)
-CLAUDE.md                    # Minimal index → points to AGENTS.md
-.cursorrules                 # Cursor format equivalent of CLAUDE.md
-.claudeignore                # Base exclusions (node_modules, dist, .env, *.key, etc.)
-.cursorignore                # Same content as .claudeignore
-.opencodeignore              # Same content as .claudeignore
+# Shared — project index from /refacil:setup; stubs + ignores from sync-repo-ide / selected IDE list
+CLAUDE.md                    # Minimal index → AGENTS.md (if Claude Code is in your IDE selection)
+.cursorrules                 # Same role for Cursor if Cursor is selected
+.claudeignore                # Base exclusions (node_modules, dist, .env, …) when Claude is selected
+.cursorignore                # Same template as .claudeignore when Cursor is selected
+.opencodeignore              # Same when OpenCode is selected
 AGENTS.md                    # Project index → generated by /refacil:setup
                              # Points to .agents/ + includes auto-managed blocks
                              # (compact-guidance and bus presentation)

package/bin/cli.js

@@ -37,6 +37,7 @@ const { handleBus } = require('../lib/commands/bus');
 const { handleSdd, autoMigrateOpenspec, findProjectRoot, cmdWriteConfig } = require('../lib/commands/sdd');
 const { syncIgnoreFiles } = require('../lib/ignore-files');
 const { methodologyMigrationPending } = require('../lib/methodology-migration-pending');
+const { resolveSelectedIDEsForRepo, syncRepoIdeFiles } = require('../lib/repo-ide-sync');
 
 const packageRoot = path.resolve(__dirname, '..');
 const projectRoot = findProjectRoot();
@@ -749,33 +750,7 @@ function update() {
 
   const homeDir = os.homedir();
 
-  // Source of truth: persisted selection from init.
-  // Fall back to detection for backward compat (users who had the methodology installed
-  // before selected-ides.json existed). In that case, infer selection from IDE dirs
-  // already present in this repo and persist the result so future runs use the file.
-  let selectedIDEs = readSelectedIDEs();
-  if (!selectedIDEs) {
-    const detectedIds = detectInstalledIDEs();
-    const hasClaudeDir = detectedIds.includes('claude') ||
-      fs.existsSync(path.join(globalClaudeDir(homeDir), 'skills')) ||
-      fs.existsSync(path.join(projectRoot, '.claude'));
-    const hasCursorDir = detectedIds.includes('cursor') ||
-      fs.existsSync(path.join(globalCursorDir(homeDir), 'skills')) ||
-      fs.existsSync(path.join(projectRoot, '.cursor'));
-    const hasOpenCodeDir = detectedIds.includes('opencode') ||
-      fs.existsSync(path.join(globalOpenCodeDir(homeDir), 'skills')) ||
-      fs.existsSync(path.join(projectRoot, '.opencode'));
-    const hasCodexFallback = detectedIds.includes('codex') ||
-      fs.existsSync(path.join(globalCodexDir(homeDir), 'skills'));
-    selectedIDEs = [
-      hasClaudeDir && '.claude',
-      hasCursorDir && '.cursor',
-      hasOpenCodeDir && '.opencode',
-      hasCodexFallback && '.codex',
-    ].filter(Boolean);
-    // Persist for future runs so detection only happens once
-    if (selectedIDEs.length > 0) writeSelectedIDEs(selectedIDEs);
-  }
+  const selectedIDEs = resolveSelectedIDEsForRepo(projectRoot, homeDir);
 
   const hasClaudeDir = selectedIDEs.includes('.claude');
   const hasCursorDir = selectedIDEs.includes('.cursor');
@@ -890,6 +865,69 @@ function update() {
   console.log('\n  RESTART your IDE session to apply the changes.\n');
 }
 
+/**
+ * Per-repo CLAUDE.md, .cursorrules, ignore files, and session markers (compact-guidance, testing-policy).
+ * IDE list: ~/.refacil-sdd-ai/selected-ides.json, with the same fallback heuristics as `update`.
+ * Does not install skills or hooks (use `init` / `update`).
+ */
+function syncRepoIde() {
+  console.log('\n  refacil-sdd-ai: sync-repo-ide — per-repo files for selected IDEs...\n');
+
+  const homeDir = os.homedir();
+  const { selectedIDEs, ignoreResult, sessionOut } = syncRepoIdeFiles(packageRoot, projectRoot, homeDir);
+
+  if (selectedIDEs.length === 0) {
+    const selPath = path.join(homeDir, '.refacil-sdd-ai', 'selected-ides.json');
+    console.log('  No IDE selection found and nothing could be inferred.');
+    console.log(`  Run: refacil-sdd-ai init   (writes ${selPath})\n`);
+    return;
+  }
+
+  console.log(`  IDE selection: ${selectedIDEs.join(', ')}`);
+
+  try {
+    const IDE_TO_IGNORE = { '.claude': '.claudeignore', '.cursor': '.cursorignore', '.opencode': '.opencodeignore' };
+    const ignoreNames = selectedIDEs.map((d) => IDE_TO_IGNORE[d]).filter(Boolean).join(', ');
+    const s = ignoreResult.claude || ignoreResult.cursor || ignoreResult.opencode;
+    if (s && s.status === 'created') {
+      console.log(`  ${ignoreNames} created`);
+    } else if (s && s.status === 'updated') {
+      console.log(`  ${ignoreNames} updated (${s.added} entries added)`);
+    } else if (ignoreNames) {
+      console.log(`  ${ignoreNames} are up to date`);
+    }
+  } catch (err) {
+    console.error(`  Warning: could not sync ignore files: ${err.message}`);
+  }
+
+  if (sessionOut && !sessionOut.ok) {
+    console.error(`  Warning: session repo sync: ${sessionOut.reason || 'unknown'}`);
+  } else if (sessionOut && sessionOut.ok) {
+    try {
+      if (sessionOut.compact.status === 'error') {
+        console.error(`  Warning: could not sync compact-guidance: ${sessionOut.compact.message}`);
+      } else if (sessionOut.compact.status === 'appended') {
+        console.log('  compact-guidance block added to AGENTS.md');
+      } else if (sessionOut.compact.status === 'replaced') {
+        console.log('  compact-guidance block updated in AGENTS.md');
+      }
+      if (sessionOut.testing.status === 'error') {
+        console.error(`  Warning: could not sync testing-policy: ${sessionOut.testing.message}`);
+      } else if (sessionOut.testing.status === 'created-file') {
+        console.log('  testing-policy: created .agents/testing.md');
+      } else if (sessionOut.testing.status === 'appended' || sessionOut.testing.status === 'written-empty') {
+        console.log('  testing-policy block added to .agents/testing.md');
+      } else if (sessionOut.testing.status === 'replaced') {
+        console.log('  testing-policy block updated in .agents/testing.md');
+      }
+    } catch (err) {
+      console.error(`  Warning: session repo sync: ${err.message}`);
+    }
+  }
+
+  console.log('');
+}
+
 function clean() {
   console.log('\n  refacil-sdd-ai: Removing skills...\n');
 
@@ -983,9 +1021,11 @@ function help() {
     init          Install skills globally for Claude Code, Cursor, OpenCode and/or Codex (interactive IDE selector).
                   Use --all to install for all four IDEs without prompting.
                   Use --yes or --defaults to skip interactive branch config prompts.
-                  Creates CLAUDE.md, .cursorrules and .opencode/opencode.json as appropriate.
+                  Creates repo stubs (CLAUDE.md, .cursorrules, ignores) for selected IDEs; same logic as sync-repo-ide.
                   Migrates any project-level artifacts to global dirs automatically.
-    update        Re-copy skills for all detected IDEs to global user dirs
+    update        Re-copy skills for all selected IDEs to global user dirs
+    sync-repo-ide Same IDE list as update (selected-ides.json): CLAUDE.md, .cursorrules,
+                  ignore files, compact-guidance + testing-policy in repo (no global install)
     migration-pending  Same validation as hooks/notify-update: list migrations (exit 1 if any; --json)
     check-update   Sync skills, compact-guidance (AGENTS.md), and testing-policy block (.agents/testing.md) at session start
     notify-update  Notify methodology migration only if applicable (UserPromptSubmit hook)
@@ -1033,7 +1073,7 @@ function help() {
     1. npm install -g refacil-sdd-ai
     2. refacil-sdd-ai init
     3. RESTART your IDE session (Claude Code, Cursor, OpenCode, or Codex)
-    4. Run: /refacil:setup (generates AGENTS.md for your project)
+    4. Run: /refacil:setup (generates AGENTS.md + sync-repo-ide stubs/ignores for selected IDEs)
 
   Global installation paths (this machine):
     - Claude Code: ${claudePath}/skills/, ${claudePath}/agents/
@@ -1070,6 +1110,9 @@ switch (command) {
   case 'update':
     update();
     break;
+  case 'sync-repo-ide':
+    syncRepoIde();
+    break;
   case 'migration-pending':
     migrationPendingCmd();
     break;

package/lib/repo-ide-sync.js

@@ -0,0 +1,100 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const {
+  globalClaudeDir,
+  globalCursorDir,
+  globalOpenCodeDir,
+  globalCodexDir,
+  readSelectedIDEs,
+  writeSelectedIDEs,
+} = require('./global-paths');
+const { detectInstalledIDEs } = require('./ide-detection');
+const { createClaudeMd, createCursorRules } = require('./installer');
+const { syncIgnoreFiles } = require('./ignore-files');
+const { syncRepoSessionMarkers } = require('./session-repo-sync');
+
+/**
+ * Same resolution as `update`: persisted `~/.refacil-sdd-ai/selected-ides.json` first;
+ * if missing, heuristic detection (global skills dirs, optional project `.claude/` etc.) and persist.
+ *
+ * @param {string} projectRoot
+ * @param {string} [homeDir]
+ * @returns {string[]}
+ */
+function resolveSelectedIDEsForRepo(projectRoot, homeDir = os.homedir()) {
+  let selectedIDEs = readSelectedIDEs(homeDir);
+  if (!selectedIDEs) {
+    const detectedIds = detectInstalledIDEs();
+    const hasClaudeDir =
+      detectedIds.includes('claude') ||
+      fs.existsSync(path.join(globalClaudeDir(homeDir), 'skills')) ||
+      fs.existsSync(path.join(projectRoot, '.claude'));
+    const hasCursorDir =
+      detectedIds.includes('cursor') ||
+      fs.existsSync(path.join(globalCursorDir(homeDir), 'skills')) ||
+      fs.existsSync(path.join(projectRoot, '.cursor'));
+    const hasOpenCodeDir =
+      detectedIds.includes('opencode') ||
+      fs.existsSync(path.join(globalOpenCodeDir(homeDir), 'skills')) ||
+      fs.existsSync(path.join(projectRoot, '.opencode'));
+    const hasCodexFallback =
+      detectedIds.includes('codex') || fs.existsSync(path.join(globalCodexDir(homeDir), 'skills'));
+    selectedIDEs = [
+      hasClaudeDir && '.claude',
+      hasCursorDir && '.cursor',
+      hasOpenCodeDir && '.opencode',
+      hasCodexFallback && '.codex',
+    ].filter(Boolean);
+    if (selectedIDEs.length > 0) writeSelectedIDEs(selectedIDEs, homeDir);
+  }
+  return selectedIDEs || [];
+}
+
+/**
+ * Per-repo artifacts for the current IDE selection: CLAUDE.md, .cursorrules, ignore files,
+ * compact-guidance / testing-policy (when `AGENTS.md` / `.agents/` exist).
+ *
+ * Does not install global skills or hooks (use `init` / `update` for that).
+ *
+ * @param {string} packageRoot
+ * @param {string} projectRoot
+ * @param {string} [homeDir]
+ * @param {{ sessionMarkers?: boolean }} [options]
+ * @returns {{
+ *   selectedIDEs: string[],
+ *   claudeOk: boolean,
+ *   cursorOk: boolean,
+ *   ignoreResult: Record<string, { status: string, added?: number }|undefined>,
+ *   sessionOut: object | null
+ * }}
+ */
+function syncRepoIdeFiles(packageRoot, projectRoot, homeDir = os.homedir(), options = {}) {
+  const sessionMarkers = options.sessionMarkers !== false;
+  const selectedIDEs = resolveSelectedIDEsForRepo(projectRoot, homeDir);
+
+  const hasClaude = selectedIDEs.includes('.claude');
+  const hasCursor = selectedIDEs.includes('.cursor');
+
+  let claudeOk = false;
+  let cursorOk = false;
+  if (hasClaude) claudeOk = createClaudeMd(packageRoot, projectRoot);
+  if (hasCursor) cursorOk = createCursorRules(packageRoot, projectRoot);
+
+  const ignoreResult = syncIgnoreFiles(projectRoot, selectedIDEs);
+
+  let sessionOut = null;
+  if (sessionMarkers) {
+    try {
+      sessionOut = syncRepoSessionMarkers(projectRoot, packageRoot);
+    } catch (err) {
+      sessionOut = { ok: false, reason: err.message };
+    }
+  }
+
+  return { selectedIDEs, claudeOk, cursorOk, ignoreResult, sessionOut };
+}
+
+module.exports = { resolveSelectedIDEsForRepo, syncRepoIdeFiles };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "5.2.0",
+  "version": "5.2.1",
   "description": "SDD-AI: Specification-Driven Development with AI — development methodology using AI with Claude Code, Cursor, OpenCode and Codex",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"

package/skills/setup/SKILL.md

@@ -179,64 +179,40 @@ Produce neutral placeholders (e.g. “Stack: unknown — see README / add manife
 - The CLI (`refacil-sdd-ai check-update` on **SessionStart**, plus `update` / `init`) merges a block between **`<!-- refacil-sdd-ai:testing-policy:start -->`** and **`<!-- refacil-sdd-ai:testing-policy:end -->`** from the package template. If **`.agents/`** exists but **`testing.md`** does not, the file is **created** with a starter **Repo-specific commands** section **below** the markers (safe to edit; not overwritten on sync).
 - Put long-lived baseline/scoped command lines **outside** the markers (see template). Only the marked region is refreshed when the package updates.
 
-### Step 4b: Overwrite `CLAUDE.md` and `.cursorrules`
+### Step 4b–5: Per-repo IDE index files, ignores, and session markers (selected IDEs)
 
-Before writing IDE-specific files, detect installed IDE directories in repo root (`.claude/`, `.cursor/`, `.opencode/`).  
-Only create/update files for IDEs whose directory exists. Never create files for an IDE that is not present.
+**Source of truth for which IDEs apply to this repo** is the same as `refacil-sdd-ai init` / `update`: **`~/.refacil-sdd-ai/selected-ides.json`** (chosen during `init`). If that file is missing, the CLI falls back to detecting installed/global skill dirs — same heuristic as **`refacil-sdd-ai update`**.
 
-Rules:
-- If `.claude/` exists: overwrite `CLAUDE.md`.
-- If `.cursor/` exists: overwrite `.cursorrules`.
-- If both exist: overwrite both.
-- If neither exists: do not create either file; report that no supported IDE folder was detected and suggest running `refacil-sdd-ai init`.
+Do **not** infer IDE targets from `.claude/`, `.cursor/`, `.opencode/` folders in the repository; those dirs are optional and skills are normally **global**.
 
-When created, these files are thin indexes toward `AGENTS.md` and must not contain project detail.
+**Mandatory shell step** (repository root — same cwd rules as `init`):
 
-**`CLAUDE.md`** — minimal index, no project content:
-
-```
-# CLAUDE.md
-
-Full project context: see `AGENTS.md` (index) and `.agents/` (detail by area).
-If `AGENTS.md` does not exist, run `/refacil:setup`.
+```bash
+refacil-sdd-ai sync-repo-ide
 ```
 
-**`.cursorrules`** — identical content with header `# Cursor Rules`.
-
-All project detail, stack, rules and `refacil:*` commands live in `.agents/` and are indexed from `AGENTS.md`. Do not duplicate anything in CLAUDE.md or .cursorrules.
-
-### Step 5: Context exclusion files
-
-Sync ignore files only for detected IDE directories:
-- `.claude/` → `.claudeignore`
-- `.cursor/` → `.cursorignore`
-- `.opencode/` → `.opencodeignore`
-
-Do not create `.claudeignore`, `.cursorignore`, or `.opencodeignore` if the matching IDE directory does not exist.
+This command writes or refreshes:
 
-If the files already exist, only missing entries are added — custom content is not overwritten.
+- **`CLAUDE.md`** when Claude Code is in the IDE selection.
+- **`.cursorrules`** when Cursor is in the IDE selection (thin index toward `AGENTS.md`, same content policy as before).
+- **`.claudeignore`**, **`.cursorignore`**, **`.opencodeignore`** for the matching selected IDEs (`syncIgnoreFiles` — add missing base entries only; never overwrite custom lines).
+- **`compact-guidance`** in **`AGENTS.md`** and **`testing-policy`** block in **`.agents/testing.md`** when those files exist (same behavior as **`init`** / **`update`** tail).
 
-Inform the user of the result:
-- **Created**: the detected IDE ignore file(s) were created from scratch.
-- **Updated**: missing entries were added.
-- **No changes**: they already had all the entries.
+Report the CLI stdout to the user (created vs up to date, compact-guidance, testing-policy). If it says no IDE selection was found and nothing could be inferred, instruct **`refacil-sdd-ai init`** first, then rerun **`sync-repo-ide`** from the repo root.
 
-If the user wants to customize additional exclusions, they can edit them directly after setup.
+If the user wants extra exclusions beyond the base list, they may edit the ignore files after setup.
 
 ### Step 6: Verify skills
 
-- Refacil: verify `refacil-*` folders only under detected IDE directories:
-  - `.claude/` detected → check `.claude/skills/`
-  - `.cursor/` detected → check `.cursor/skills/`
-  - `.opencode/` detected → check `.opencode/skills/`
-  If missing for any detected IDE: run `refacil-sdd-ai init` and restart session.
+- Verify **`refacil-*`** folders under **global** IDE dirs (skills are installed per machine, not per repo): **`~/.claude/skills/`** when Claude is selected, **`~/.cursor/skills/`** when Cursor is selected (OpenCode / Codex: global dirs per upstream docs).
+  If missing: run **`refacil-sdd-ai init`** and restart the IDE session.
 - Verify `sdd` subcommand: `refacil-sdd-ai sdd 2>&1 || true` — must show subcommands `status`, `mark-reviewed`, `tasks-update`, `archive`.
 
 ### Step 7: Final summary
 
 ```
 === refacil:setup completed ===
- Node.js / refacil-sdd-ai / refacil-sdd/changes/ / branch config / AGENTS.md / IDE files (detected only) / ignore files (detected only) / skills OK
+ Node.js / refacil-sdd-ai / refacil-sdd/changes/ / branch config / AGENTS.md / sync-repo-ide (selected IDEs) / skills OK
 
  Restart Claude Code or Cursor session if this is the first skills installation.
  The next step is to review the available flow.

package/skills/setup/troubleshooting.md

@@ -17,6 +17,20 @@ Consult this file **only** if a setup step fails. It is not part of the happy pa
 - Always run `refacil-sdd-ai init` from the **repository root** (the folder that owns the codebase — commonly where `package.json`, `go.mod`, `pyproject.toml`, or `Cargo.toml` lives), not from inside a subdirectory.
 - If you accidentally ran it from a subdirectory, delete the mistakenly created `.claude/`, `.cursor/`, `.claudeignore`, `.cursorignore`, `.cursorrules`, and `CLAUDE.md` from that subdirectory, then re-run from the correct location.
 
+## `/refacil:setup` did not create `CLAUDE.md`, `.cursorignore`, etc.
+
+- Those files come from **`refacil-sdd-ai sync-repo-ide`** (run by `/refacil:setup`). Execute it yourself from the **repository root**:
+
+  ```bash
+  refacil-sdd-ai sync-repo-ide
+  ```
+
+- Requires a prior **`refacil-sdd-ai init`** so **`~/.refacil-sdd-ai/selected-ides.json`** exists (or readable global skill dirs so the CLI can infer IDEs).
+
+## Wrong directory for `sync-repo-ide`
+
+- Same rule as **`init`** / **`update`**: cwd must be the **repository root**. Otherwise stubs and ignores are written next to the wrong folder.
+
 ## AGENTS.md is missing after init
 
 - `refacil-sdd-ai init` does not generate `AGENTS.md` automatically — it is created by `/refacil:setup` inside the IDE.

package/templates/methodology-guide.md

@@ -6,7 +6,7 @@ Skills are identical in `.claude/skills/refacil-*/` (Claude Code) and `.cursor/s
 
 | Command | Description |
 |---------|-------------|
-| `/refacil:setup` | Generate `AGENTS.md`, `.agents/`, `refacil-sdd/changes/`, and IDE index files for the project |
+| `/refacil:setup` | Generate `AGENTS.md`, `.agents/`, `refacil-sdd/changes/`, branch config; runs `refacil-sdd-ai sync-repo-ide` for stubs/ignores/markers (`CLAUDE.md`, `.cursorrules`, `*.ignore`, compact-guidance) from **selected IDEs** |
 | `/refacil:guide` | Interactive guide — which command to use |
 | `/refacil:explore` | Explore the codebase without changes |
 | `/refacil:propose` | Create a change proposal |