From 1dbb8850523d8f22a2f9f4f1e2df9d994375eb63 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <codeforester@gmail.com>
Date: Fri, 29 May 2026 14:03:31 -0700
Subject: [PATCH] Document user-local IDE preference design

---
 CHANGELOG.md              |  1 +
 docs/ide-bootstrapping.md | 19 ++++++++++++++++---
 docs/local-config.md      | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 50 insertions(+), 3 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8f77b59..af7055c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and Base versions are tracked in the repo-root `VERSION` file.
 
 ### Added
 
+- Added the user-local IDE preference design for `~/.base.d/config.yaml`.
 - Added documentation guidance for using `mise` with Go and Java projects.
 - Added documentation for the boundary between `basectl onboard` and
   project-owned installers.
diff --git a/docs/ide-bootstrapping.md b/docs/ide-bootstrapping.md
index 4c2dd62..98a2a49 100644
--- a/docs/ide-bootstrapping.md
+++ b/docs/ide-bootstrapping.md
@@ -141,6 +141,22 @@ IDE checks include:
 
 `doctor` provides human-oriented fix guidance for missing or divergent state.
 
+## User-Local Preferences
+
+User-local IDE preferences live in `~/.base.d/config.yaml`; Base should not add
+a separate `~/.base.d/ide.yaml` file. The user config layer is machine-local and
+additive over project manifests:
+
+- project manifests declare project requirements
+- user config can add personal extensions and settings
+- project settings take precedence over user settings for the same key
+- user config can disable IDE handling globally or for one supported IDE on a
+  machine
+
+This lets a project keep its required IDE contract in version control while a
+developer adds local preferences without changing shared project files. See
+[local-config.md](local-config.md) for the schema and sync boundary.
+
 ## Future Work
 
 Future IDE-related work should remain inside Base's boundary: workstation
@@ -153,6 +169,3 @@ Candidate future work:
 - JetBrains support only after a clean, scriptable configuration surface is
   identified
 - extension pinning only if Base adopts a deliberate VSIX management strategy
-
-Machine-local IDE preferences live in `~/.base.d/config.yaml`. See
-[local-config.md](local-config.md) for the user config schema and sync boundary.
diff --git a/docs/local-config.md b/docs/local-config.md
index 97f25b2..480752c 100644
--- a/docs/local-config.md
+++ b/docs/local-config.md
@@ -87,6 +87,17 @@ ide:
     enabled: false
 ```
 
+The design decision is to keep IDE preferences inside the existing
+`~/.base.d/config.yaml` file instead of introducing `~/.base.d/ide.yaml`.
+IDE choices are machine-local Base configuration, and the existing config
+commands already give users a stable path, JSON inspection, and diagnostics:
+
+```bash
+basectl config path
+basectl config show
+basectl config doctor
+```
+
 The project manifest remains authoritative for project requirements. User
 settings are additive:
 
@@ -95,10 +106,32 @@ settings are additive:
 - project settings win when both layers declare the same setting
 - users can disable IDE handling for one machine with `ide.enabled: false` or
   `ide.<name>.enabled: false`
+- user `install` can opt a machine into or out of IDE app installation without
+  changing the project's extension or settings requirements
 
 If a user setting conflicts with a project setting, Base reports a warning and
 uses the project setting.
 
+Supported IDE preference keys are intentionally narrow:
+
+- `ide.enabled`
+- `ide.vscode.enabled`
+- `ide.vscode.install`
+- `ide.vscode.extra_extensions`
+- `ide.vscode.settings`
+- `ide.cursor.enabled`
+- `ide.cursor.install`
+- `ide.cursor.extra_extensions`
+- `ide.cursor.settings`
+
+Unknown IDE names and unsupported keys are rejected. Settings values must be
+JSON-serializable because Base writes them to IDE `settings.json` files.
+
+Base does not edit this file. There is no `basectl config set` or IDE preference
+editor command by design; developers can edit YAML directly, and Base keeps the
+runtime behavior inspectable through `basectl config show` and
+`basectl config doctor`.
+
 ## Sync Guidance
 
 iCloud can be useful for a single developer's multi-Mac setup, but it is not a