@codewizard-dt/bootstrap 2.11.2 → 2.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. package/README.md +9 -9
  2. package/lib/README.md +1 -1
  3. package/lib/hooks/lib/serena.js +20 -6
  4. package/lib/prompts/migrate-wiki.md +2 -2
  5. package/lib/prompts/setup-strict-typechecks.md +18 -7
  6. package/lib/scripts/README.md +8 -8
  7. package/lib/scripts/bootstrap-serena.sh +8 -6
  8. package/lib/scripts/build-mcp-guide.sh +3 -3
  9. package/lib/scripts/install-mcps.sh +71 -28
  10. package/lib/scripts/lib.sh +35 -8
  11. package/lib/scripts/merge-gitignore.sh +102 -29
  12. package/lib/scripts/migrate-project.sh +9 -2
  13. package/lib/scripts/setup-deployment.sh +9 -0
  14. package/lib/scripts/sync-wiki-scaffold.sh +145 -24
  15. package/lib/scripts/templates/CLAUDE-wiki.md +6 -2
  16. package/lib/scripts/templates/guides/stubs/serena.md +7 -7
  17. package/lib/scripts/templates/wiki/conventions.md +2 -0
  18. package/lib/scripts/templates/wiki/index.md +6 -0
  19. package/lib/skills/bug-close/SKILL.md +1 -1
  20. package/lib/skills/bug-file/SKILL.md +2 -2
  21. package/lib/skills/bug-triage/SKILL.md +1 -1
  22. package/lib/skills/debug-logs/SKILL.md +2 -2
  23. package/lib/skills/decision-create/SKILL.md +1 -1
  24. package/lib/skills/decision-finalize/SKILL.md +1 -1
  25. package/lib/skills/decision-next/SKILL.md +1 -1
  26. package/lib/skills/decision-walkthrough/SKILL.md +1 -1
  27. package/lib/skills/demo/SKILL.md +1 -1
  28. package/lib/skills/eval-create/SKILL.md +7 -3
  29. package/lib/skills/eval-gap/SKILL.md +6 -2
  30. package/lib/skills/eval-run/SKILL.md +1 -1
  31. package/lib/skills/extract-feature/SKILL.md +1 -1
  32. package/lib/skills/gap-assess/SKILL.md +1 -1
  33. package/lib/skills/git-commit/SKILL.md +1 -1
  34. package/lib/skills/lint/SKILL.md +1 -1
  35. package/lib/skills/marp-slideshow/SKILL.md +1 -1
  36. package/lib/skills/mermaid-flowchart/SKILL.md +1 -1
  37. package/lib/skills/now/SKILL.md +1 -1
  38. package/lib/skills/port-feature/SKILL.md +1 -1
  39. package/lib/skills/power-mode/SKILL.md +1 -1
  40. package/lib/skills/primer/SKILL.md +2 -2
  41. package/lib/skills/project-readme/SKILL.md +1 -1
  42. package/lib/skills/req-create/SKILL.md +1 -1
  43. package/lib/skills/req-extract-decisions/SKILL.md +1 -1
  44. package/lib/skills/req-finalize/SKILL.md +1 -1
  45. package/lib/skills/req-retire/SKILL.md +2 -2
  46. package/lib/skills/req-update/SKILL.md +1 -1
  47. package/lib/skills/research/SKILL.md +1 -1
  48. package/lib/skills/roadmap-add/SKILL.md +2 -2
  49. package/lib/skills/roadmap-create/SKILL.md +3 -3
  50. package/lib/skills/roadmap-next/SKILL.md +1 -1
  51. package/lib/skills/serena-config/SKILL.md +1 -1
  52. package/lib/skills/simplify/SKILL.md +1 -1
  53. package/lib/skills/tackle/SKILL.md +3 -3
  54. package/lib/skills/task-add/SKILL.md +1 -1
  55. package/lib/skills/task-audit/SKILL.md +2 -2
  56. package/lib/skills/task-trash/SKILL.md +1 -1
  57. package/lib/skills/task-update/SKILL.md +2 -2
  58. package/lib/skills/uat-auto/SKILL.md +1 -1
  59. package/lib/skills/uat-auto-plus/SKILL.md +1 -1
  60. package/lib/skills/uat-generate/SKILL.md +1 -1
  61. package/lib/skills/uat-skip/SKILL.md +1 -1
  62. package/lib/skills/uat-walk/SKILL.md +1 -1
  63. package/lib/skills/uat-walk/UAT-CORE.md +1 -1
  64. package/lib/skills/update-docs/SKILL.md +2 -2
  65. package/lib/skills/wiki-ingest/SKILL.md +1 -1
  66. package/lib/skills/wiki-lint/SKILL.md +1 -1
  67. package/lib/skills/wiki-query/SKILL.md +1 -1
  68. package/package.json +1 -1
  69. package/raw/guides/type-checking-templates/README.md +7 -7
  70. package/raw/guides/type-checking-templates/eslint/eslint.config.ts +1 -1
  71. package/raw/research/mcp-add-scope-writes/index.md +46 -0
  72. package/raw/research/mcp-add-scope-writes/sources.md +38 -0
  73. package/raw/research/mcp-scope-conflict-handling/index.md +61 -0
  74. package/raw/research/mcp-scope-conflict-handling/sources.md +32 -0
  75. package/.github/workflows/build.yml +0 -88
  76. package/raw/guides/mcp-tools.md +0 -335
  77. package/raw/guides/task-spec.md +0 -79
package/README.md CHANGED
@@ -35,7 +35,7 @@ At a glance, the package entry point selects a script, scripts copy or generate
35
35
  - **Responsibility:** Coordinate project setup, updates, global installs, explicit deployment scaffolding, Serena bootstrapping, wiki migration, and strict type-checking setup.
36
36
  - **Tech:** Bash, `rsync`, `find`, `grep`, `claude` CLI, npm-executed shell scripts
37
37
  - **Inputs:** Target project path, interactive prompts, CLI flags such as `--dry-run`, API keys supplied by environment variables or stdin, and optional user context for deploy/typecheck setup.
38
- - **Outputs:** Global hooks and skills, MCP registrations, project-local `wiki/`, `raw/`, `.docs/guides/`, `.mcp.json`, `.serena/project.yml`, and optional deployment or type-check configuration when those explicit commands are run.
38
+ - **Outputs:** Global hooks and skills, MCP registrations, project-local `wiki/`, `raw/`, `wiki/guides/`, `.mcp.json`, `.serena/project.yml`, and optional deployment or type-check configuration when those explicit commands are run.
39
39
  - **Depends on:** CLI Entry Point, Skills Library, Hooks Library, Wiki Scaffold Templates, Prompt Templates, Guide Stubs, Claude Code CLI, MCP servers
40
40
 
41
41
  #### MCP Installer
@@ -72,10 +72,10 @@ At a glance, the package entry point selects a script, scripts copy or generate
72
72
 
73
73
  #### Guide Stubs
74
74
 
75
- - **Responsibility:** Builds `.docs/guides/mcp-tools.md` from only the MCP sections that apply to the target project.
75
+ - **Responsibility:** Builds `wiki/guides/mcp-tools.md` from only the MCP sections that apply to the target project.
76
76
  - **Tech:** Markdown fragments in `lib/scripts/templates/guides/stubs/`, Bash assembly in `build-mcp-guide.sh`
77
77
  - **Inputs:** Target project path and installed MCP server names.
78
- - **Outputs:** A tailored MCP tools guide in the target project's `.docs/guides/` directory.
78
+ - **Outputs:** A tailored MCP tools guide in the target project's `wiki/guides/` directory.
79
79
  - **Depends on:** MCP Installer, Setup Scripts
80
80
 
81
81
  #### Prompt Templates
@@ -135,8 +135,8 @@ flowchart LR
135
135
 
136
136
  subgraph Target ["Target Project"]
137
137
  WIKI_DIR["wiki/ + raw/"]
138
- DOCS[".docs/guides/mcp-tools.md"]
139
- MCP_JSON[".mcp.json<br/>Serena"]
138
+ DOCS["wiki/guides/mcp-tools.md"]
139
+ MCP_JSON["Serena (local scope)<br/>~/.claude.json project entry"]
140
140
  SERENA_CFG[".serena/project.yml"]
141
141
  WORKFLOWS[".github/workflows/"]
142
142
  end
@@ -205,15 +205,15 @@ sequenceDiagram
205
205
  MCP-->>MCP: docker run brave-search-mcp (http :8941, API key baked in)
206
206
  MCP-->>MCP: bootstrap playwright launchd agent (http :8931, macOS)
207
207
  MCP->>Claude: claude mcp add selected servers (http URLs for brave/playwright)
208
- MCP-->>Project: .mcp.json for Serena when selected
208
+ MCP-->>Project: serena registered at local scope (~/.claude.json) when selected
209
209
  Setup->>Global: install-global.sh --skip-mcps
210
210
  Global-->>Global: rsync skills to ~/.claude/skills/
211
211
  Global-->>Global: rsync hooks to ~/.claude/hooks/
212
212
  Global-->>Global: merge canonical deny list into ~/.claude/settings.json
213
213
  Setup->>Wiki: sync-wiki-scaffold.sh <project>
214
- Wiki-->>Project: raw/, wiki/, CLAUDE.md snippets, .docs/guides/
214
+ Wiki-->>Project: raw/, wiki/, CLAUDE.md snippets, wiki/guides/ (tiered: required + opted-in optional)
215
215
  Setup->>Guide: build-mcp-guide.sh <project> <installed-mcps>
216
- Guide-->>Project: .docs/guides/mcp-tools.md
216
+ Guide-->>Project: wiki/guides/mcp-tools.md
217
217
  Setup->>Claude: bootstrap-serena prompt
218
218
  Claude-->>Project: .serena/project.yml
219
219
  Setup-->>Dev: setup complete
@@ -440,7 +440,7 @@ npx @codewizard-dt/bootstrap@latest
440
440
  gh run list --workflow security.yml --limit 5
441
441
  ```
442
442
 
443
- For end-to-end validation, run `npx @codewizard-dt/bootstrap@latest setup` inside a disposable repository and confirm `wiki/`, `raw/`, `.docs/guides/`, and the selected MCP configuration files are created.
443
+ For end-to-end validation, run `npx @codewizard-dt/bootstrap@latest setup` inside a disposable repository and confirm `wiki/`, `raw/`, `wiki/guides/`, and the selected MCP configuration files are created.
444
444
 
445
445
  ### Rollback
446
446
 
package/lib/README.md CHANGED
@@ -21,7 +21,7 @@ lib/
21
21
 
22
22
  1. A user runs `npx @codewizard-dt/bootstrap <command>` (or the installed `bootstrap` bin).
23
23
  2. `bin/cli.js` resolves the command to a script in `lib/scripts/` and execs it with the target project path.
24
- 3. That script sources `lib/scripts/lib.sh` for shared helpers, then does some combination of: installing MCP servers, `rsync`-ing `lib/skills/` and `lib/hooks/` to `~/.claude/`, scaffolding `wiki/`/`raw/` from `lib/scripts/templates/wiki/`, assembling `.docs/guides/mcp-tools.md` from `lib/scripts/templates/guides/stubs/`, and/or invoking `claude --print` with a prompt from `lib/prompts/` for anything that needs project-specific judgment (CI/CD scaffolding, `.docs/`→wiki migration, strict type-check setup).
24
+ 3. That script sources `lib/scripts/lib.sh` for shared helpers, then does some combination of: installing MCP servers, `rsync`-ing `lib/skills/` and `lib/hooks/` to `~/.claude/`, scaffolding `wiki/`/`raw/` from `lib/scripts/templates/wiki/`, delivering tiered guides from `raw/guides/`, assembling `wiki/guides/mcp-tools.md` from `lib/scripts/templates/guides/stubs/`, and/or invoking `claude --print` with a prompt from `lib/prompts/` for anything that needs project-specific judgment (CI/CD scaffolding, `.docs/`→wiki migration, strict type-check setup).
25
25
  4. Once installed, the target project's Claude Code sessions pick up the copied hooks (enforcement) and skills (slash commands) automatically; the wiki scaffold and `CLAUDE.md` additions give those sessions durable, file-system-backed state.
26
26
 
27
27
  See the root [`README.md`](../README.md) for the full architecture diagram and component descriptions; this file and its children document `lib/` at the file level.
@@ -159,8 +159,9 @@ function readJsonSilent(filePath) {
159
159
  }
160
160
 
161
161
  /**
162
- * Minimal presence check: scans ~/.claude.json mcpServers for a `serena` key.
163
- * Returns true if Serena is registered as an MCP server.
162
+ * Minimal presence check: scans the known MCP config stores for a `serena` key
163
+ * — top-level mcpServers plus ~/.claude.json projects[<cwd>].mcpServers (local
164
+ * scope, the bootstrap default). Returns true if Serena is registered.
164
165
  */
165
166
  function hasSerena() {
166
167
  const candidates = [
@@ -170,12 +171,25 @@ function hasSerena() {
170
171
  path.join(HOME, '.mcp.json'),
171
172
  path.join(process.cwd(), '.mcp.json'),
172
173
  ];
174
+ const hasSerenaKey = (servers) => {
175
+ if (!servers || typeof servers !== 'object') return false;
176
+ for (const name of Object.keys(servers)) {
177
+ if (String(name).toLowerCase() === SERENA_TOKEN) return true;
178
+ }
179
+ return false;
180
+ };
173
181
  for (const p of candidates) {
174
182
  const data = readJsonSilent(p);
175
- const servers = data?.mcpServers;
176
- if (servers && typeof servers === 'object') {
177
- for (const name of Object.keys(servers)) {
178
- if (String(name).toLowerCase() === SERENA_TOKEN) return true;
183
+ if (hasSerenaKey(data?.mcpServers)) return true;
184
+ // Local-scope servers (the bootstrap default for serena) live in
185
+ // ~/.claude.json under projects[<abs path>].mcpServers, not top-level.
186
+ const projects = data?.projects;
187
+ if (projects && typeof projects === 'object') {
188
+ const cwd = process.cwd();
189
+ for (const [projPath, proj] of Object.entries(projects)) {
190
+ if ((cwd === projPath || cwd.startsWith(projPath + path.sep)) && hasSerenaKey(proj?.mcpServers)) {
191
+ return true;
192
+ }
179
193
  }
180
194
  }
181
195
  }
@@ -99,7 +99,7 @@ Migrated N tasks, N UAT files, N decisions, N requirements, N bugs, N roadmaps f
99
99
 
100
100
  1. `git rm` the old per-family `README.md` indexes (after extracting status hints).
101
101
  2. After all moves, the old family dirs (`.docs/tasks`, `.docs/uat`, `.docs/adr`, `.docs/prd`, `.docs/bugs`, `.docs/roadmaps`) must contain nothing but empty subdirectories and `.gitkeep` files — `git rm` the `.gitkeep`s and remove the empty directories.
102
- 3. **KEEP `.docs/guides/` and `.docs/company-context/`** — they are still used.
102
+ 3. Guides live in `wiki/guides/` (template-owned, delivered by the scaffold that ran before this migration) — do not create or keep a `.docs/guides/` directory. **KEEP** any skill scratch output dirs under `.docs/` (`demo/`, `MARP/`, `port/`, `extract/`) untouched; if `.docs/` ends up empty, remove it.
103
103
 
104
104
  ## Final report
105
105
 
@@ -108,4 +108,4 @@ End with a concise report:
108
108
  - Rows added to each family index
109
109
  - ID remaps performed (old → new)
110
110
  - Anything ambiguous or skipped — listed explicitly, never silently dropped
111
- - Confirmation that `.docs/` now contains only `guides/` and `company-context/`
111
+ - Confirmation that `.docs/` is now empty (and removed) or contains only skill scratch dirs (`demo/`, `MARP/`, `port/`, `extract/`)
@@ -8,19 +8,30 @@ one, note:
8
8
  - What config files already exist (tsconfig, pyproject.toml, mypy.ini, .eslintrc, etc.)
9
9
  - What package manager / toolchain is in use
10
10
 
11
- ## Phase 2 — Research best practices (per language)
11
+ ## Phase 2 — Establish strict-mode baselines (per language)
12
12
 
13
- For each language found, use Context7 (for library docs) or Brave Search (for general practices, up to 50 req/sec, parallel OK) to look up the
14
- current strict-mode recommendations:
13
+ IMPORTANT: If `wiki/guides/type-checking-templates/` exists in the project, it is the authoritative baseline — start there, not from web
14
+ research. Read its `README.md` to pick the right variant, then read the chosen template files (they carry inline annotations explaining
15
+ every non-obvious decision):
16
+ - TypeScript: `tsconfig/` (node-esm / Vite three-file split / lib) + `eslint/eslint.config.ts`
17
+ - Python: `python/pyproject.toml` (mypy strict + ruff + basedpyright companion), `python/mypy.ini`, `python/pyrightconfig.json`
18
+
19
+ Use Context7 (library docs) or Brave Search (general practices, up to 50 req/sec, parallel OK) only to fill gaps the templates do not
20
+ cover: languages with no template (Go: staticcheck, go vet; Rust: #![deny(warnings)], Clippy --deny warnings; etc.), framework-specific
21
+ plugins, or flags added since the templates were written.
22
+
23
+ If `wiki/guides/type-checking-templates/` does NOT exist, fall back to researching current strict-mode recommendations from scratch with
24
+ Context7 / Brave Search:
15
25
  - TypeScript: tsconfig strict, tseslint strictTypeChecked, stylisticTypeChecked, parserOptions.project
16
26
  - Python: mypy --strict, pyproject.toml [tool.mypy]
17
27
  - Go: staticcheck, go vet
18
28
  - Rust: #![deny(warnings)], Clippy --deny warnings
19
29
  - …and so on for any other language present
20
30
 
21
- Research what the strict flags actually enable, what the known gotchas are (e.g. type-aware ESLint rules requiring parserOptions.project;
22
- mypy needing ignore_missing_imports for third-party stubs), and what companion tools are idiomatic (e.g. ESLint for TypeScript,
23
- mypy/pyright for Python).
31
+ Either way, understand what the strict flags actually enable, the known gotchas (e.g. type-aware ESLint rules requiring
32
+ parserOptions.projectService; mypy needing per-module ignore_missing_imports for third-party stubs), and the idiomatic companion tools
33
+ (ESLint for TypeScript, mypy/pyright for Python). (The templates are an optional guide — the user can install them by re-running
34
+ `npx @codewizard-dt/bootstrap update` and answering yes for `type-checking-templates`.)
24
35
 
25
36
  ## Phase 3 — Install toolchain packages
26
37
 
@@ -100,7 +111,7 @@ user-invocable: true
100
111
 
101
112
  # Run typecheck and fix issues
102
113
 
103
- IMPORTANT: Adhere to all rules in `.docs/guides/mcp-tools.md` if it exists.
114
+ IMPORTANT: Adhere to all rules in `wiki/guides/mcp-tools.md` if it exists.
104
115
 
105
116
  ## Step 1: find the problem
106
117
 
@@ -8,11 +8,11 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
8
8
 
9
9
  | Script | `bootstrap` command | What it does |
10
10
  |--------|---------------------|---------------|
11
- | `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: MCP install (interactive), global skills/hooks install, wiki scaffold sync, `.gitignore` merge, and Serena `project.yml` bootstrap. Does **not** scaffold deployment — that's explicit via `deploy`. |
12
- | `update-project.sh` | `update` | Re-installs global skills/hooks and re-syncs the wiki scaffold + `.docs/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
11
+ | `setup-project.sh` | `setup` | Preflight-checks `claude` and `uv` are installed, then runs the full new-project sequence: MCP install (interactive), global skills/hooks install, wiki scaffold + tiered guides sync (optional guides prompted), `.gitignore` merge, and Serena `project.yml` bootstrap. Does **not** scaffold deployment — that's explicit via `deploy`. |
12
+ | `update-project.sh` | `update` | Re-installs global skills/hooks and re-syncs the wiki scaffold + tiered `wiki/guides/` into an existing project. Detects legacy `.docs/`-layout families (`tasks`, `uat`, `adr`, `prd`, `bugs`, `roadmaps`) and warns without touching them — migration is a separate, explicit step (`migrate`). Never touches `.github/`. |
13
13
  | `install-global.sh` | `install` | Installs/updates MCPs, hooks, and skills globally with **no project path** — the shared step both `setup` and `update` delegate to. Also prunes stale skill folders left over from the wiki rename (`adr-*` → `decision-*`, `prd-*` → `req-*`), and merges the canonical Bash deny list into `~/.claude/settings.json` via `merge-settings-deny.js`. Accepts `--skip-mcps` when the caller already handled MCP install interactively. |
14
- | `setup-deployment.sh` | `deploy` / `deployment` | Reads `raw/guides/deployment-strategy.md` as a prompt template and runs `claude` to scaffold `.github/workflows/`, `Makefile` Docker targets, and `.gitleaks.toml` into the target project. Deliberately **not** called by `setup`/`update` — CI files get hand-customized per project (Dockerfile paths, runner labels, deploy steps) and must never be created or clobbered implicitly. `security.yml` is always overwritten (generic); `build.yml`/`.gitleaks.toml` are copy-once; `Makefile` targets are merged. |
15
- | `migrate-project.sh` | `migrate` | Claude-driven migration of a legacy `.docs/`-layout project to the LLM Wiki structure (`wiki/knowledge/` + `wiki/work/`). Preflight requires a clean git tree; runs on a fresh `wiki-migration` branch so the whole migration is one reviewable diff. Scaffolds first via `sync-wiki-scaffold.sh`, then drives the semantic conversion (frontmatter synthesis, ID renames, link rewrites, family indexes) with the prompt at `lib/prompts/migrate-wiki.md`. `git mv` before edit, so history is preserved. `--dry-run` prints the file inventory only and does not touch anything. |
14
+ | `setup-deployment.sh` | `deploy` / `deployment` | Reads `raw/guides/deployment-strategy.md` as a prompt template, copies it into the target's `wiki/guides/` (deploy-only guide tier — the wiki sync never ships it), and runs `claude` to scaffold `.github/workflows/`, `Makefile` Docker targets, and `.gitleaks.toml` into the target project. Deliberately **not** called by `setup`/`update` — CI files get hand-customized per project (Dockerfile paths, runner labels, deploy steps) and must never be created or clobbered implicitly. `security.yml` is always overwritten (generic); `build.yml`/`.gitleaks.toml` are copy-once; `Makefile` targets are merged. |
15
+ | `migrate-project.sh` | `migrate` | Claude-driven migration of a legacy `.docs/`-layout project to the LLM Wiki structure (`wiki/knowledge/` + `wiki/work/`). Preflight requires a clean git tree; runs on a fresh `wiki-migration` branch so the whole migration is one reviewable diff. Scaffolds first via `sync-wiki-scaffold.sh --interactive`, assembles `wiki/guides/mcp-tools.md` via `build-mcp-guide.sh`, then drives the semantic conversion (frontmatter synthesis, ID renames, link rewrites, family indexes) with the prompt at `lib/prompts/migrate-wiki.md`. `git mv` before edit, so history is preserved. `--dry-run` prints the file inventory only and does not touch anything. |
16
16
  | `setup-strict-typechecks.sh` | `typechecks` | Loads `lib/prompts/setup-strict-typechecks.md`, appends an optional language list (space- or comma-separated), and runs `claude` to detect languages, research current strict-mode conventions, install toolchains, and wire `make typecheck`. |
17
17
  | `wiki-dashboard-server.js` | `dashboard` | Zero-dependency Node static file server (Node builtins only) that serves the live wiki dashboard client (`templates/wiki/dashboard.html`) at `/` and the project's `wiki/` tree read-only under `/wiki/*`, all with `no-store` cache headers so the polling client always sees current content. Runs in the foreground until Ctrl-C. Binds `http://localhost:4317` by default; pass a port to override (`bootstrap dashboard 4400`), and falls back to the next port (up to 10 tries) if the chosen one is in use. Unlike the other CLI scripts, this is Node, not Bash, and is long-running rather than one-shot. |
18
18
 
@@ -22,10 +22,10 @@ All scripts use `set -euo pipefail`. Every script that touches a target project
22
22
  |--------|---------|---------|
23
23
  | `lib.sh` | Every script above | Shared bash library: `resolve_project_dir` (path resolution + validation), `mcp_installed`/`serena_installed`/`detect_installed_mcps` (MCP state checks), `run_project_sync` (the common setup/update sequence: MCPs → skills/hooks → wiki scaffold → gitignore → Serena), and `prompt_yn`/`prompt_scope` (interactive prompt helpers). |
24
24
  | `install-mcps.sh` | `install-global.sh`, `setup-project.sh`, `update-project.sh` | Installs Brave Search, Context7, Playwright, and (when a project dir is given) Serena. Two modes: non-interactive (`install-global.sh`'s default — installs everything missing at user scope) and `--interactive --project-dir <dir>` (prompts per-MCP and asks for scope, used by `setup`/`update`). |
25
- | `sync-wiki-scaffold.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Scaffolds an **empty** wiki into the target project from `templates/wiki/`: creates `raw/` + all `wiki/` family directories, lifecycle docs, per-family `index.md`, and stub `index.md`/`log.md`. Copy-once for project-owned files; always-refreshes `conventions.md` and `lifecycle.md`. Also delivers the `## LLM Wiki` section and `.env` safety policy into the target's `CLAUDE.md` (copy-once, sentinel-guarded, from `templates/CLAUDE-wiki.md` / `templates/CLAUDE-env-safety.md`). |
26
- | `build-mcp-guide.sh` | `setup-project.sh`, `update-project.sh` | Assembles `.docs/guides/mcp-tools.md` in the target project from the per-server stub files in `templates/guides/stubs/`, including only the sections for MCPs actually installed. |
25
+ | `sync-wiki-scaffold.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Scaffolds an **empty** wiki into the target project from `templates/wiki/`: creates `raw/` + all `wiki/` family directories, lifecycle docs, per-family `index.md`, and stub `index.md`/`log.md`. Copy-once for project-owned files; always-refreshes `conventions.md` and `lifecycle.md`. Delivers guides from `raw/guides/` tier-wise into `wiki/guides/`: `command-anti-patterns.md` required (always refreshed); `evals-framework.md` + `type-checking-templates/` optional (`--interactive` prompts on first delivery, sticky refresh once present — legacy `.docs/guides/` presence counts, opt out by deleting); migrates legacy `.docs/guides/` (template-owned files removed or relocated, deprecated `task-spec.md` deleted, empty dirs pruned). Also delivers the `## LLM Wiki` section and `.env` safety policy (copy-once, sentinel-guarded, from `templates/CLAUDE-wiki.md` / `templates/CLAUDE-env-safety.md`) into the target's `CLAUDE.md` — when a `CLAUDE.md` already exists without the schema, prompts whether to modify it or write `CLAUDE.local.md` instead (non-interactive default: `CLAUDE.local.md`). |
26
+ | `build-mcp-guide.sh` | `setup-project.sh`, `update-project.sh`, `migrate-project.sh` | Assembles `wiki/guides/mcp-tools.md` in the target project from the per-server stub files in `templates/guides/stubs/`, including only the sections for MCPs actually installed. |
27
27
  | `bootstrap-serena.sh` | `setup-project.sh`, `update-project.sh` | Headlessly triggers `.serena/project.yml` creation via `claude --print` and enables the optional Serena tools needed by this template's workflow. Preflights `claude` and `python3`. |
28
- | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Copies the packaged `.gitignore` template into the target project if none exists; otherwise merges in only the missing lines, leaving the project's existing `.gitignore` content untouched. |
28
+ | `merge-gitignore.sh` | `setup-project.sh`, `update-project.sh` | Merges the packaged `.gitignore` template into the target per titled section: sections already represented in the target (any entry present) get their missing lines merged silently; new sections are offered interactively by title (`Add .gitignore section 'Node / TypeScript / JavaScript'? [y/N]`), skipped when declined or non-interactive. A missing `.gitignore` is copied wholesale when there is no tty to prompt on. Never touches existing project content. |
29
29
  | `merge-settings-deny.js` | `install-global.sh` | Zero-dependency Node script that merges the canonical Bash deny list (`templates/settings-deny.json`) into `~/.claude/settings.json` `permissions.deny`. Additive union only: missing entries are appended, user entries are never removed or reordered, all other settings keys pass through untouched. Atomic write, preserves existing indentation, and always exits 0 (warns + skips on unparseable or unexpected file shapes so an install never aborts over a settings merge). `--target`/`--source` flags exist as test seams. |
30
30
 
31
31
  ## Standalone infra scripts (not wired to the CLI)
@@ -44,7 +44,7 @@ Static and semi-static assets copied or read by the scripts above — never exec
44
44
  | Path | Read/copied by | Contents |
45
45
  |------|-----------------|----------|
46
46
  | `templates/wiki/` | `sync-wiki-scaffold.sh` | The empty wiki scaffold: `index.md`, `log.md`, `conventions.md`, and per-family `knowledge/`/`work/{tasks,uat,bugs,requirements,decisions,roadmaps}/` directories with `lifecycle.md`, `index.md`, `archive/index.md`, and `.gitkeep` placeholders. |
47
- | `templates/guides/stubs/` | `build-mcp-guide.sh` | Per-MCP-server markdown fragments (`serena.md`, `context7.md`, `brave-search.md`, `playwright.md`) plus `00-header.md` (the shared top-of-file rules), assembled into `.docs/guides/mcp-tools.md`. |
47
+ | `templates/guides/stubs/` | `build-mcp-guide.sh` | Per-MCP-server markdown fragments (`serena.md`, `context7.md`, `brave-search.md`, `playwright.md`) plus `00-header.md` (the shared top-of-file rules), assembled into `wiki/guides/mcp-tools.md`. |
48
48
  | `templates/CLAUDE-wiki.md` | `sync-wiki-scaffold.sh` | The `## LLM Wiki` schema section delivered into a target project's `CLAUDE.md` (copy-once, sentinel-guarded). |
49
49
  | `templates/CLAUDE-env-safety.md` | `sync-wiki-scaffold.sh` | The `.env` read/write safety policy prepended to a target project's `CLAUDE.md` (copy-once, never duplicated). |
50
50
  | `templates/gitignore` | `merge-gitignore.sh` | Packed copy of this repo's own `.gitignore` (dotfiles aren't included in npm packages, so it's shipped under a non-dot name and renamed on copy). |
@@ -36,10 +36,12 @@ if [ ! -f ".serena/project.yml" ]; then
36
36
  uvx --from git+https://github.com/oraios/serena serena --help >/dev/null 2>&1 || true
37
37
  fi
38
38
  echo "Triggering Claude Code to initialize Serena (.serena/ will be created)..."
39
- if [ -f ".mcp.json" ]; then
40
- # Project-scoped .mcp.json servers need one-time interactive approval that a
41
- # headless --print run can never grant; --mcp-config + --strict-mcp-config
42
- # loads serena explicitly, bypassing the approval gate.
39
+ if [ -f ".mcp.json" ] && grep -q '"serena"' .mcp.json 2>/dev/null; then
40
+ # Legacy layout: serena in the project's .mcp.json. Those servers need a
41
+ # one-time interactive approval that a headless --print run can never grant;
42
+ # --mcp-config + --strict-mcp-config loads serena explicitly, bypassing the
43
+ # gate. (The bootstrap default is local scope, which has no approval gate —
44
+ # the plain branch below covers it.)
43
45
  claude --print --mcp-config .mcp.json --strict-mcp-config "exit" >/dev/null 2>&1 || true
44
46
  else
45
47
  claude --print "exit" >/dev/null 2>&1 || true
@@ -47,8 +49,8 @@ if [ ! -f ".serena/project.yml" ]; then
47
49
  if [ ! -f ".serena/project.yml" ]; then
48
50
  echo "Error: .serena/project.yml was not created by 'claude --print'."
49
51
  echo "Ensure Serena MCP is registered for this project — run 'npx @codewizard-dt/bootstrap setup' and answer Yes to the Serena prompt,"
50
- echo "or register it manually: claude mcp add --scope project serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project \"$PROJECT_DIR\""
51
- echo "If it IS registered, open 'claude' interactively in $PROJECT_DIR once to approve the project MCP servers, then re-run 'npx @codewizard-dt/bootstrap update'."
52
+ echo "or register it manually (from the project root): claude mcp add --scope local serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project \"$PROJECT_DIR\""
53
+ echo "Then re-run 'npx @codewizard-dt/bootstrap update'."
52
54
  exit 1
53
55
  fi
54
56
  else
@@ -3,7 +3,7 @@ set -euo pipefail
3
3
 
4
4
  # build-mcp-guide.sh <project-dir> [mcp-name...]
5
5
  #
6
- # Assembles .docs/guides/mcp-tools.md in the target project from per-server stubs.
6
+ # Assembles wiki/guides/mcp-tools.md in the target project from per-server stubs.
7
7
  # Only sections for the listed MCP names are included.
8
8
  #
9
9
  # Valid MCP names: serena context7 brave-search playwright
@@ -22,7 +22,7 @@ fi
22
22
  PROJECT_DIR="$1"; shift
23
23
  INSTALLED_MCPS=("$@")
24
24
 
25
- OUT="$PROJECT_DIR/.docs/guides/mcp-tools.md"
25
+ OUT="$PROJECT_DIR/wiki/guides/mcp-tools.md"
26
26
 
27
27
  has_mcp() {
28
28
  local name="$1"
@@ -32,7 +32,7 @@ has_mcp() {
32
32
  return 1
33
33
  }
34
34
 
35
- mkdir -p "$PROJECT_DIR/.docs/guides"
35
+ mkdir -p "$PROJECT_DIR/wiki/guides"
36
36
 
37
37
  {
38
38
  # 1. Always: title + TOP RULE
@@ -34,6 +34,10 @@ BRAVE_MCP_URL="http://127.0.0.1:${BRAVE_MCP_PORT}/mcp"
34
34
  # server is started with --host 127.0.0.1) — 127.0.0.1 URLs get 403 "Access is
35
35
  # only allowed at localhost:<port>". Found by TASK-025 runtime UAT.
36
36
  PLAYWRIGHT_MCP_URL="http://localhost:${PLAYWRIGHT_MCP_PORT}/mcp"
37
+ # The bootstrap-managed server registers under its own name so it can coexist
38
+ # with a project-scoped `playwright` entry in a team's committed .mcp.json —
39
+ # we never edit that file; a distinct name avoids [Conflicting scopes] entirely.
40
+ PLAYWRIGHT_MCP_NAME="${PLAYWRIGHT_MCP_NAME:-playwright-shared}"
37
41
 
38
42
  # mcp_installed, serena_installed, prompt_yn, prompt_scope live in lib.sh.
39
43
 
@@ -50,23 +54,32 @@ mcp_add_scoped() {
50
54
  fi
51
55
  }
52
56
 
53
- # register_optional_mcp <name> <interactive-prompt> <adder-fn> [expected]
57
+ # register_optional_mcp <name> <interactive-prompt> <adder-fn> [expected] [fixed_scope]
54
58
  # Common wrapper for the optional MCPs (brave-search / context7 / playwright):
55
59
  # skip if already installed; in interactive mode gate on a y/n prompt and ask
56
60
  # for scope; otherwise install non-interactively at user scope. <adder-fn>
57
61
  # performs the actual `claude mcp add` (including any API-key prompting) and
58
62
  # receives the resolved scope ("user" | "project") as its only argument.
59
63
  # Optional [expected]: a string the existing registration must contain (checked
60
- # via mcp_matches, lib.sh). If installed but not matching, the stale
61
- # registration is removed and the adder re-run directly at user scope (upgrade
62
- # path — the server was already wanted, so no interactive gating is re-applied).
64
+ # via mcp_matches, lib.sh). If installed but not matching, a stale USER-scope
65
+ # registration is removed and the adder re-run at user scope (upgrade path).
66
+ # A project/local-scoped registration under the same name is never removed —
67
+ # it is repository/machine config we don't own; we skip and say so.
68
+ # Optional [fixed_scope]: skip the scope prompt and use this scope (for MCPs
69
+ # that only support one scope — asking and ignoring the answer is worse).
63
70
  register_optional_mcp() {
64
- local name="$1" prompt="$2" adder="$3" expected="${4:-}" scope
71
+ local name="$1" prompt="$2" adder="$3" expected="${4:-}" fixed_scope="${5:-}" scope cur_scope
65
72
  if mcp_installed "$name"; then
66
73
  if [ -z "$expected" ] || mcp_matches "$name" "$expected"; then
67
74
  echo " $name: already installed, skipping."
68
75
  return 0
69
76
  fi
77
+ cur_scope="$(mcp_scope_of "$name")"
78
+ if [ "$cur_scope" != "user" ]; then
79
+ echo " $name: registered at ${cur_scope} scope with a different config — leaving it untouched."
80
+ echo " To adopt the bootstrap-managed server instead: claude mcp remove $name -s ${cur_scope} (inside the project), then re-run 'npx @codewizard-dt/bootstrap update'."
81
+ return 0
82
+ fi
70
83
  echo " $name: upgrading registration (stdio → shared http)."
71
84
  claude mcp remove "$name" -s user 2>/dev/null || true
72
85
  "$adder" user
@@ -74,7 +87,11 @@ register_optional_mcp() {
74
87
  fi
75
88
  if [ "$INTERACTIVE" = true ]; then
76
89
  if prompt_yn "$prompt"; then
77
- scope="$(prompt_scope "$name")"
90
+ if [ -n "$fixed_scope" ]; then
91
+ scope="$fixed_scope"
92
+ else
93
+ scope="$(prompt_scope "$name")"
94
+ fi
78
95
  "$adder" "$scope"
79
96
  echo " $name MCP installed."
80
97
  fi
@@ -163,7 +180,7 @@ _playwright_bootstrap_agent() {
163
180
  _add_playwright() {
164
181
  if [ "$(uname -s)" != "Darwin" ]; then
165
182
  # Non-macOS: per-session stdio server (shared-server wiring is macOS-only for now).
166
- mcp_add_scoped "$1" playwright -- npx @playwright/mcp@latest
183
+ mcp_add_scoped "$1" "$PLAYWRIGHT_MCP_NAME" -- npx @playwright/mcp@latest
167
184
  return 0
168
185
  fi
169
186
  # macOS: one shared HTTP server per machine, run as a launchd LaunchAgent in
@@ -240,27 +257,44 @@ PLIST
240
257
  if [ "$rc" -eq 2 ]; then
241
258
  return 0
242
259
  fi
243
- # Always user scope: a project-scoped playwright entry would shadow the global one.
244
- mcp_add_scoped user playwright --transport http "$PLAYWRIGHT_MCP_URL"
245
- wait_http_up "$PLAYWRIGHT_MCP_URL" && echo " playwright: listening on $PLAYWRIGHT_MCP_URL" \
246
- || { echo " WARNING: playwright endpoint not answering — diagnostics:"; \
260
+ # Always user scope, under our own name — coexists with any project-scoped
261
+ # `playwright` a team ships in .mcp.json.
262
+ mcp_add_scoped user "$PLAYWRIGHT_MCP_NAME" --transport http "$PLAYWRIGHT_MCP_URL"
263
+ wait_http_up "$PLAYWRIGHT_MCP_URL" && echo " $PLAYWRIGHT_MCP_NAME: listening on $PLAYWRIGHT_MCP_URL" \
264
+ || { echo " WARNING: $PLAYWRIGHT_MCP_NAME endpoint not answering — diagnostics:"; \
247
265
  launchctl print "gui/${uid}/${label}" 2>/dev/null || true; \
248
266
  echo " Log: ${log_file}"; }
249
267
  }
250
268
 
251
269
  # ---------------------------------------------------------------------------
252
- # Serena (always project scope — only when --project-dir provided)
270
+ # Serena (always LOCAL scope — only when --project-dir provided)
271
+ #
272
+ # Local scope stores the entry in ~/.claude.json under this project's key:
273
+ # per-project (no serena language-config bleed) but machine-local. Project
274
+ # scope would write a machine-specific absolute --project path into the repo's
275
+ # shareable .mcp.json and force the per-user .mcp.json approval gate — both
276
+ # wrong (earlier bootstrap versions did exactly this; migration below).
253
277
  # ---------------------------------------------------------------------------
254
278
  if [ -n "$PROJECT_DIR" ]; then
279
+ # Migrate a bootstrap-written serena entry out of the repo's .mcp.json.
280
+ # Consent-gated: .mcp.json may be committed team config, so the removal is
281
+ # offered, never forced; declining keeps the existing entry working.
282
+ if [ -f "$PROJECT_DIR/.mcp.json" ] && grep -q '"serena"' "$PROJECT_DIR/.mcp.json" 2>/dev/null; then
283
+ if [ "$INTERACTIVE" = true ] && prompt_yn " serena: found in this project's .mcp.json (added by an earlier bootstrap; carries a machine-specific path). Move it to local scope in ~/.claude.json? [y/N]: "; then
284
+ ( cd "$PROJECT_DIR" && claude mcp remove serena -s project ) || true
285
+ else
286
+ echo " serena: leaving the existing .mcp.json entry in place (migrate later by re-running 'npx @codewizard-dt/bootstrap update')."
287
+ fi
288
+ fi
255
289
  if serena_installed "$PROJECT_DIR"; then
256
290
  echo " serena: already registered for this project, skipping."
257
291
  elif [ "$INTERACTIVE" = true ]; then
258
- if prompt_yn "Install Serena MCP (code exploration & editing, always project scope)? [Y/n]: "; then
292
+ if prompt_yn "Install Serena MCP (code exploration & editing, always local scope)? [Y/n]: "; then
259
293
  ( cd "$PROJECT_DIR" && \
260
- claude mcp add --scope project serena -- \
294
+ claude mcp add --scope local serena -- \
261
295
  uvx --from git+https://github.com/oraios/serena \
262
296
  serena start-mcp-server --context claude-code --project "$PROJECT_DIR" )
263
- echo " serena MCP registered."
297
+ echo " serena MCP registered (local scope — ~/.claude.json, this machine only)."
264
298
  fi
265
299
  fi
266
300
  # Non-interactive with --project-dir: skip Serena — setup-project.sh previously
@@ -271,26 +305,35 @@ fi
271
305
  # Optional MCPs (near-identical wrappers — see register_optional_mcp above)
272
306
  # ---------------------------------------------------------------------------
273
307
  register_optional_mcp brave-search \
274
- "Install Brave Search MCP globally (web research, requires API key + Docker)? [y/N]: " _add_brave "$BRAVE_MCP_URL"
308
+ "Install Brave Search MCP globally (web research, requires API key + Docker)? [y/N]: " _add_brave "$BRAVE_MCP_URL" user
275
309
 
276
310
  register_optional_mcp context7 \
277
311
  "Install Context7 MCP (library documentation lookups)? [y/N]: " _add_context7
278
312
 
313
+ # Migrate the legacy bootstrap-managed `playwright` USER-scope entry to the new
314
+ # name. Only shapes bootstrap itself created are touched (the shared-http URL
315
+ # or the old stdio `npx @playwright/mcp` form), and only at user scope — a
316
+ # project-scoped `playwright` is repository config and coexists with ours by
317
+ # name. Detection reads ~/.claude.json top-level mcpServers directly because
318
+ # `claude mcp get playwright` resolves to the project entry when one exists.
319
+ if node -e '
320
+ const p = (require(require("os").homedir() + "/.claude.json").mcpServers || {}).playwright;
321
+ if (!p) process.exit(1);
322
+ const j = JSON.stringify(p);
323
+ process.exit(j.includes(process.argv[1]) || j.includes("@playwright/mcp") ? 0 : 1);
324
+ ' "$PLAYWRIGHT_MCP_URL" 2>/dev/null; then
325
+ echo " playwright: migrating legacy bootstrap user-scope entry to '$PLAYWRIGHT_MCP_NAME'."
326
+ claude mcp remove playwright -s user 2>/dev/null || true
327
+ fi
328
+
279
329
  # Shared-http upgrade detection is darwin-only: on Linux the stdio entry is the
280
330
  # desired end state, so pass an empty expected arg there (empty = never upgrade).
331
+ # The scope prompt is skipped on darwin (the shared server is user-scope only).
281
332
  playwright_expected=""
333
+ playwright_fixed_scope=""
282
334
  if [ "$(uname -s)" = "Darwin" ]; then
283
335
  playwright_expected="$PLAYWRIGHT_MCP_URL"
336
+ playwright_fixed_scope="user"
284
337
  fi
285
- register_optional_mcp playwright \
286
- "Install Playwright MCP (browser automation & UI testing)? [y/N]: " _add_playwright "$playwright_expected"
287
-
288
- # Darwin only: a project-scoped playwright entry in the project's .mcp.json
289
- # shadows the user-scope shared HTTP server. Detection mirrors serena_installed
290
- # (lib.sh). Hint only — never edit a project's .mcp.json.
291
- if [ "$(uname -s)" = "Darwin" ] && [ -n "$PROJECT_DIR" ] \
292
- && [ -f "$PROJECT_DIR/.mcp.json" ] \
293
- && grep -q '"playwright"' "$PROJECT_DIR/.mcp.json" 2>/dev/null; then
294
- echo " WARNING: playwright is also registered in $PROJECT_DIR/.mcp.json (project scope) — it shadows the user-scope shared HTTP server."
295
- echo " Remove it with: cd \"$PROJECT_DIR\" && claude mcp remove playwright -s project"
296
- fi
338
+ register_optional_mcp "$PLAYWRIGHT_MCP_NAME" \
339
+ "Install Playwright MCP (browser automation & UI testing)? [y/N]: " _add_playwright "$playwright_expected" "$playwright_fixed_scope"
@@ -47,6 +47,26 @@ mcp_installed() {
47
47
  # ---------------------------------------------------------------------------
48
48
  mcp_matches() { claude mcp get "$1" 2>/dev/null | grep -qF "$2"; }
49
49
 
50
+ # ---------------------------------------------------------------------------
51
+ # mcp_scope_of <name>
52
+ #
53
+ # Prints the scope of the resolved registration: user | project | local |
54
+ # unknown. Parses the "Scope:" line of `claude mcp get` (no --json mode
55
+ # exists). "unknown" means the output format drifted or the server is absent —
56
+ # callers must treat it as do-not-touch (scope conflicts break OAuth/token
57
+ # storage and produce duplicate servers).
58
+ # ---------------------------------------------------------------------------
59
+ mcp_scope_of() {
60
+ local line
61
+ line="$(claude mcp get "$1" 2>/dev/null | grep -m1 'Scope:')" || { echo unknown; return 0; }
62
+ case "$line" in
63
+ *User*) echo user ;;
64
+ *[Pp]roject*) echo project ;;
65
+ *[Ll]ocal*) echo local ;;
66
+ *) echo unknown ;;
67
+ esac
68
+ }
69
+
50
70
  # ---------------------------------------------------------------------------
51
71
  # wait_http_up <url> [attempts]
52
72
  #
@@ -58,12 +78,12 @@ wait_http_up() { local i code; for i in $(seq 1 "${2:-10}"); do code="$(curl -s
58
78
  # ---------------------------------------------------------------------------
59
79
  # serena_installed <project_dir>
60
80
  #
61
- # True when Serena is already registered for <project_dir> (its project-scoped
62
- # .mcp.json names "serena").
81
+ # True when Serena is registered for <project_dir> at any scope — local
82
+ # (~/.claude.json project entry, the bootstrap default), project (.mcp.json,
83
+ # legacy bootstrap installs), or user.
63
84
  # ---------------------------------------------------------------------------
64
85
  serena_installed() {
65
- [ -n "$1" ] && [ -f "$1/.mcp.json" ] && \
66
- grep -q '"serena"' "$1/.mcp.json" 2>/dev/null
86
+ [ -n "$1" ] && ( cd "$1" 2>/dev/null && claude mcp get serena &>/dev/null )
67
87
  }
68
88
 
69
89
  # ---------------------------------------------------------------------------
@@ -82,11 +102,17 @@ detect_installed_mcps() {
82
102
  if serena_installed "$project_dir"; then
83
103
  result="serena"
84
104
  fi
85
- for mcp in context7 brave-search playwright; do
105
+ for mcp in context7 brave-search; do
86
106
  if mcp_installed "$mcp"; then
87
107
  result="${result:+$result }$mcp"
88
108
  fi
89
109
  done
110
+ # The bootstrap-managed playwright server registers as "playwright-shared" so
111
+ # it can coexist with a project-scoped "playwright"; either name enables the
112
+ # playwright guide section (guide key stays "playwright").
113
+ if mcp_installed "playwright-shared" || mcp_installed "playwright"; then
114
+ result="${result:+$result }playwright"
115
+ fi
90
116
  printf '%s\n' "$result"
91
117
  }
92
118
 
@@ -95,7 +121,8 @@ detect_installed_mcps() {
95
121
  #
96
122
  # The shared setup/update sequence run identically by setup-project.sh and
97
123
  # update-project.sh: install MCPs interactively, install skills+hooks globally,
98
- # sync the wiki scaffold, merge the .gitignore, build the MCP-tools guide for
124
+ # sync the wiki scaffold (tiered guide delivery — --interactive enables the
125
+ # optional-guide prompts), merge the .gitignore, build the MCP-tools guide for
99
126
  # the detected MCPs, then bootstrap Serena's project.yml. Prints the same
100
127
  # section headers and blank-line separators the two scripts printed inline.
101
128
  # ---------------------------------------------------------------------------
@@ -113,8 +140,8 @@ run_project_sync() {
113
140
  echo ""
114
141
 
115
142
  echo "Syncing wiki scaffold..."
116
- "$script_dir/sync-wiki-scaffold.sh" "$project_dir"
117
- "$script_dir/merge-gitignore.sh" "$project_dir"
143
+ "$script_dir/sync-wiki-scaffold.sh" --interactive "$project_dir"
144
+ "$script_dir/merge-gitignore.sh" --interactive "$project_dir"
118
145
  echo ""
119
146
 
120
147
  echo "Building MCP tools guide..."