From b282c8d07423d5a009794ea7a68d8d77b013ed6c Mon Sep 17 00:00:00 2001 From: kanywst Date: Sun, 24 May 2026 20:37:31 +0900 Subject: [PATCH 1/4] feat(zero-config): audit defaults vs Ghostty bar, propose overrides Adds 'docs/zeus-zero-config.md' which audits VS Code's inherited defaults and proposes Zeus overrides where the inherited setting is friction. The bar is Ghostty's: 'open it, work.' Covers welcome, telemetry, sign-in, files, editor, terminal, search, git, and Zeus-specific AI defaults. Each override documents what changes, why the VS Code default is friction, and who the override pessimizes for. Audit only. Profile JSON implementation lands in a follow-up. --- docs/zeus-zero-config.md | 88 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/zeus-zero-config.md diff --git a/docs/zeus-zero-config.md b/docs/zeus-zero-config.md new file mode 100644 index 00000000..658937a2 --- /dev/null +++ b/docs/zeus-zero-config.md @@ -0,0 +1,88 @@ +# Zero-config defaults + +Zeus's first-run experience must be "open it, work" — Ghostty's bar. This document audits VS Code's defaults and proposes Zeus overrides where the inherited default is friction. + +## Principle + +A defensible default is one that 80% of users would pick. Anything below that bar needs an override. + +For each setting we change, we say: **what** changes, **why** the inherited default is friction, and **who** the override pessimizes for (because every default trades off something). + +## Welcome / walkthrough + +- `workbench.startupEditor`: `welcomePage` → **`none`** + - Why: the welcome page gates real work. Power users dismiss it; new users get inconsistent messaging. + - Trade-off: new users miss the curated tour. Acceptable — we ship a 1-line "press Cmd+Shift+P for commands" tooltip on first launch instead. +- `workbench.welcomePage.walkthroughs.openOnInstall`: `true` → **`false`** + +## Telemetry + +- `telemetry.telemetryLevel`: `all` → **`off`** + - Why: opt-in not opt-out is the only honest position for a 2026 OSS tool. We can pop a one-shot dialog asking after first 30 days of use, but ship `off`. + +## Settings sync / accounts + +- Sign-in prompts at startup: **disabled** + - Built-in sync requires a signed-in account; we leave the feature available but never proactively prompt. + +## Files + +- `files.autoSave`: `off` → **`afterDelay`** (1s) + - Why: every junior dev's first complaint is "I lost my work." Auto-save is standard in 2026. + - Trade-off: users who script around `onDidSaveDocument` need to know files save themselves. Documented in release notes. +- `files.trimTrailingWhitespace`: `false` → **`true`** +- `files.insertFinalNewline`: `false` → **`true`** +- `files.eol`: `auto` → **`\n`** + - Trade-off: Windows-native devs may want `\r\n`. Setting is preserved so they can override. + +## Editor + +- `editor.formatOnSave`: `false` → **`true`** (only if a formatter is configured for the language) + - Implementation: a one-line activation hook checks for a formatter; if present, format-on-save is enabled. +- `editor.minimap.enabled`: `true` → **`false`** + - Why: minimap is noise for most users. The 20% who love it can flip it back. +- `editor.linkedEditing`: `false` → **`true`** +- `editor.bracketPairColorization.enabled`: `true` → **`true`** (keep) +- `editor.guides.bracketPairs`: `false` → **`"active"`** +- `editor.fontFamily`: VS Code default → **OS-native monospace stack** (SF Mono on mac, Cascadia Code on Windows, system on Linux) + - Why: VS Code defaults to Consolas / Menlo. Modern OS-native looks better in 2026. + +## Terminal + +- `terminal.integrated.copyOnSelection`: `false` → **`true`** +- `terminal.integrated.shellIntegration.enabled`: `true` → **`true`** (keep) + +## Search + +- `search.exclude`: include `**/.zeus/memory/**` so memory files don't pollute global search by default. Override is one click. + +## Git + +- `git.autofetch`: `false` → **`true`** +- `git.confirmSync`: `true` → **`false`** (just sync; if a user wants confirmation, they get a notification on first sync rather than every time) + +## AI defaults (Zeus-specific) + +- `zeus.ai.provider`: `null` → **`null`** (keep — we don't pick for the user) +- `zeus.ai.firstRunPrompt`: shown once on first launch — three-choice quick pick: + - "Use my Anthropic API key" → opens key entry + - "Use a local model (Ollama)" → opens Ollama install guide if Ollama isn't running + - "Skip — I'll set this up later" → fully usable editor, AI features dimmed + +## Implementation notes + +- These defaults are applied via a profile-shaped JSON shipped at `resources/profiles/zeus-default.json` (planned location) +- The set of overrides is auditable: this doc is the source of truth, the JSON is generated from it +- Users who reset to defaults get the Zeus defaults, not VS Code's + +## Acceptance criteria + +- [ ] Profile JSON exists and is loaded at first start +- [ ] `workbench.startupEditor` etc are set as listed above +- [ ] First-run AI prompt shows once, never re-prompts +- [ ] Reset-to-defaults restores the Zeus profile, not VS Code's +- [ ] A `docs/zeus-zero-config.md` ↔ profile JSON parity check runs in CI (no setting in JSON missing from doc, and vice versa) + +## Status + +Audit only. Implementation lands in a follow-up PR. From 54ae6b6e747d2e1fa40a3feb846f1b01dd19d479 Mon Sep 17 00:00:00 2001 From: kanywst Date: Sun, 24 May 2026 21:31:11 +0900 Subject: [PATCH 2/4] docs(zero-config): address review feedback on defaults - files.autoSave: afterDelay -> onFocusChange. afterDelay + formatOnSave rearranges code mid-typing during the 1s pause; onFocusChange saves on tab/palette/terminal focus shifts, strictly safer than 'off' without that footgun. - files.eol: '\n' -> keep 'auto'. Pinning to '\n' globally silently rewrites .bat/PowerShell/legacy CRLF files on save. Per-repo enforcement is .editorconfig's job, not the editor default. - editor.fontFamily Linux: 'system' -> 'monospace' (the actual fontconfig alias for the system's preferred fixed-width family; 'system' often resolves to a variable-width font). - git.confirmSync: revert to keep true. Sync = push + pull; one stray click can publish unfinished work, and the keystroke cost is small. --- docs/zeus-zero-config.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/zeus-zero-config.md b/docs/zeus-zero-config.md index 658937a2..48b86397 100644 --- a/docs/zeus-zero-config.md +++ b/docs/zeus-zero-config.md @@ -27,13 +27,13 @@ For each setting we change, we say: **what** changes, **why** the inherited defa ## Files -- `files.autoSave`: `off` → **`afterDelay`** (1s) - - Why: every junior dev's first complaint is "I lost my work." Auto-save is standard in 2026. - - Trade-off: users who script around `onDidSaveDocument` need to know files save themselves. Documented in release notes. +- `files.autoSave`: `off` → **`onFocusChange`** + - Why: every junior dev's first complaint is "I lost my work." `onFocusChange` saves on context switch (tab away, terminal focus, palette open) — strictly safer than `off` without the rearrange-while-typing problem `afterDelay` has when combined with `formatOnSave`. + - Trade-off: writes to disk happen at focus boundaries, slightly later than `afterDelay` but earlier than `onWindowChange`. - `files.trimTrailingWhitespace`: `false` → **`true`** - `files.insertFinalNewline`: `false` → **`true`** -- `files.eol`: `auto` → **`\n`** - - Trade-off: Windows-native devs may want `\r\n`. Setting is preserved so they can override. +- `files.eol`: `auto` → **`auto`** (keep VS Code's default) + - Why: cross-platform / Windows-native repos that mix CRLF need this. Pinning to `\n` here would silently rewrite `.bat`, PowerShell scripts, and legacy Windows-CRLF files when saved. Project-level `.editorconfig` is the right place to enforce `\n` per repo. ## Editor @@ -44,7 +44,7 @@ For each setting we change, we say: **what** changes, **why** the inherited defa - `editor.linkedEditing`: `false` → **`true`** - `editor.bracketPairColorization.enabled`: `true` → **`true`** (keep) - `editor.guides.bracketPairs`: `false` → **`"active"`** -- `editor.fontFamily`: VS Code default → **OS-native monospace stack** (SF Mono on mac, Cascadia Code on Windows, system on Linux) +- `editor.fontFamily`: VS Code default → **OS-native monospace stack** (SF Mono on macOS, Cascadia Code on Windows, `monospace` on Linux — fontconfig resolves it to the system's preferred fixed-width family) - Why: VS Code defaults to Consolas / Menlo. Modern OS-native looks better in 2026. ## Terminal @@ -59,7 +59,8 @@ For each setting we change, we say: **what** changes, **why** the inherited defa ## Git - `git.autofetch`: `false` → **`true`** -- `git.confirmSync`: `true` → **`false`** (just sync; if a user wants confirmation, they get a notification on first sync rather than every time) +- `git.confirmSync`: `true` → **`true`** (keep) + - Why: "Sync Changes" pushes and pulls in one shot, so a stray click can publish unfinished work. The confirmation is one extra return key but is what stops a category of accidents. We optimize for safety here, not for one fewer keystroke. ## AI defaults (Zeus-specific) From 7f7be2abb94a0ff6e5e2c9b5820b709a1078b520 Mon Sep 17 00:00:00 2001 From: kanywst Date: Sun, 24 May 2026 23:43:53 +0900 Subject: [PATCH 3/4] docs(zero-config): fill in Why/Trade-off, add formatOnSaveMode Address Gemini sweep across the audit doc: - Welcome / files / editor / terminal / git sections now spell out Why and Trade-off for the previously bare bullet lines, matching the doc's own intro principle (line 9). - editor.formatOnSave: pair it with editor.formatOnSaveMode = 'modifications' so legacy or messy codebases don't get one-shot formatter churn the first time they're opened in Zeus. Full-file format stays available via per-workspace override. - git.autofetch trade-off now mentions the SSH-passphrase / no-agent case, with the recommendation to fix credential setup rather than disable the default. --- docs/zeus-zero-config.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/docs/zeus-zero-config.md b/docs/zeus-zero-config.md index 48b86397..33d96e66 100644 --- a/docs/zeus-zero-config.md +++ b/docs/zeus-zero-config.md @@ -14,6 +14,8 @@ For each setting we change, we say: **what** changes, **why** the inherited defa - Why: the welcome page gates real work. Power users dismiss it; new users get inconsistent messaging. - Trade-off: new users miss the curated tour. Acceptable — we ship a 1-line "press Cmd+Shift+P for commands" tooltip on first launch instead. - `workbench.welcomePage.walkthroughs.openOnInstall`: `true` → **`false`** + - Why: same rationale as above — walkthrough overlays steal focus from the editor on first open. + - Trade-off: users who like the walkthrough have to find it in the command palette (`Open Walkthrough`). ## Telemetry @@ -31,25 +33,39 @@ For each setting we change, we say: **what** changes, **why** the inherited defa - Why: every junior dev's first complaint is "I lost my work." `onFocusChange` saves on context switch (tab away, terminal focus, palette open) — strictly safer than `off` without the rearrange-while-typing problem `afterDelay` has when combined with `formatOnSave`. - Trade-off: writes to disk happen at focus boundaries, slightly later than `afterDelay` but earlier than `onWindowChange`. - `files.trimTrailingWhitespace`: `false` → **`true`** + - Why: matches what almost every linter / formatter does anyway; the editor doing it preemptively means cleaner diffs. + - Trade-off: Markdown's "two trailing spaces = line break" convention loses on save. Users who care about that syntax can scope an override per-language. - `files.insertFinalNewline`: `false` → **`true`** + - Why: POSIX-friendly; many tools (`tail`, `cat`, `git diff`) handle file-with-trailing-newline better. + - Trade-off: noisy first-diff if a file in an existing repo previously lacked one. - `files.eol`: `auto` → **`auto`** (keep VS Code's default) - Why: cross-platform / Windows-native repos that mix CRLF need this. Pinning to `\n` here would silently rewrite `.bat`, PowerShell scripts, and legacy Windows-CRLF files when saved. Project-level `.editorconfig` is the right place to enforce `\n` per repo. ## Editor - `editor.formatOnSave`: `false` → **`true`** (only if a formatter is configured for the language) + - Why: catches forgotten formatting on every save instead of relying on pre-commit hooks. - Implementation: a one-line activation hook checks for a formatter; if present, format-on-save is enabled. + - Also: `editor.formatOnSaveMode`: `file` → **`modifications`**. Only the lines the user touched are reformatted. Saves legacy / messy codebases from one-shot formatter churn the first time they're opened in Zeus. + - Trade-off: users on green-field projects sometimes want full-file format; one-line override per workspace. - `editor.minimap.enabled`: `true` → **`false`** - Why: minimap is noise for most users. The 20% who love it can flip it back. + - Trade-off: keyboard scroll fans love the visual map; documented in the cheat sheet. - `editor.linkedEditing`: `false` → **`true`** + - Why: HTML/JSX tag renames stay in sync without a refactor command. + - Trade-off: extra mutation events some extensions don't expect. - `editor.bracketPairColorization.enabled`: `true` → **`true`** (keep) - `editor.guides.bracketPairs`: `false` → **`"active"`** + - Why: highlights the bracket nesting around the cursor without painting every line. + - Trade-off: more visual noise for users who prefer a totally clean gutter. - `editor.fontFamily`: VS Code default → **OS-native monospace stack** (SF Mono on macOS, Cascadia Code on Windows, `monospace` on Linux — fontconfig resolves it to the system's preferred fixed-width family) - Why: VS Code defaults to Consolas / Menlo. Modern OS-native looks better in 2026. ## Terminal - `terminal.integrated.copyOnSelection`: `false` → **`true`** + - Why: matches macOS Terminal / iTerm muscle memory and Linux X11 default. + - Trade-off: clobbers the system clipboard mid-task for users who rely on long-lived clipboard contents. - `terminal.integrated.shellIntegration.enabled`: `true` → **`true`** (keep) ## Search @@ -59,6 +75,8 @@ For each setting we change, we say: **what** changes, **why** the inherited defa ## Git - `git.autofetch`: `false` → **`true`** + - Why: keeps remote-aware UI (ahead/behind indicators, "Pull from main") current without manual fetch. + - Trade-off: users with credential-manager-less SSH setups (passphrase-protected keys, no agent) get repeated prompts. Documented in install notes — the answer is "set up a credential manager", not "disable autofetch". - `git.confirmSync`: `true` → **`true`** (keep) - Why: "Sync Changes" pushes and pulls in one shot, so a stray click can publish unfinished work. The confirmation is one extra return key but is what stops a category of accidents. We optimize for safety here, not for one fewer keystroke. From 332ad6866fde6e98b690d2edb6925151605acc50 Mon Sep 17 00:00:00 2001 From: kanywst Date: Mon, 25 May 2026 00:15:14 +0900 Subject: [PATCH 4/4] docs(zero-config): markdown carve-out, SCM caveat, explicit font stack, drop copyOnSelection override --- docs/zeus-zero-config.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/zeus-zero-config.md b/docs/zeus-zero-config.md index 33d96e66..e5d17708 100644 --- a/docs/zeus-zero-config.md +++ b/docs/zeus-zero-config.md @@ -32,9 +32,9 @@ For each setting we change, we say: **what** changes, **why** the inherited defa - `files.autoSave`: `off` → **`onFocusChange`** - Why: every junior dev's first complaint is "I lost my work." `onFocusChange` saves on context switch (tab away, terminal focus, palette open) — strictly safer than `off` without the rearrange-while-typing problem `afterDelay` has when combined with `formatOnSave`. - Trade-off: writes to disk happen at focus boundaries, slightly later than `afterDelay` but earlier than `onWindowChange`. -- `files.trimTrailingWhitespace`: `false` → **`true`** +- `files.trimTrailingWhitespace`: `false` → **`true`** *with a per-language carve-out for Markdown* - Why: matches what almost every linter / formatter does anyway; the editor doing it preemptively means cleaner diffs. - - Trade-off: Markdown's "two trailing spaces = line break" convention loses on save. Users who care about that syntax can scope an override per-language. + - Carve-out: the Zeus default profile also ships `"[markdown]": { "files.trimTrailingWhitespace": false }` so Markdown's "two trailing spaces = line break" convention isn't silently broken. Users get clean diffs everywhere else and standards-compliant Markdown without thinking about it. - `files.insertFinalNewline`: `false` → **`true`** - Why: POSIX-friendly; many tools (`tail`, `cat`, `git diff`) handle file-with-trailing-newline better. - Trade-off: noisy first-diff if a file in an existing repo previously lacked one. @@ -47,6 +47,7 @@ For each setting we change, we say: **what** changes, **why** the inherited defa - Why: catches forgotten formatting on every save instead of relying on pre-commit hooks. - Implementation: a one-line activation hook checks for a formatter; if present, format-on-save is enabled. - Also: `editor.formatOnSaveMode`: `file` → **`modifications`**. Only the lines the user touched are reformatted. Saves legacy / messy codebases from one-shot formatter churn the first time they're opened in Zeus. + - Caveat: `modifications` requires the file to be tracked by Git (or another supported SCM) — VS Code uses the SCM diff to know which ranges are "yours". For standalone files or projects without `git init`, the mode silently falls back to formatting nothing. Zeus's first-run flow surfaces this as a hint when the user opens an untracked folder: "Run `git init` to enable smart format-on-save." Users who don't want that behaviour can set `"editor.formatOnSaveMode": "file"` in workspace settings. - Trade-off: users on green-field projects sometimes want full-file format; one-line override per workspace. - `editor.minimap.enabled`: `true` → **`false`** - Why: minimap is noise for most users. The 20% who love it can flip it back. @@ -58,14 +59,15 @@ For each setting we change, we say: **what** changes, **why** the inherited defa - `editor.guides.bracketPairs`: `false` → **`"active"`** - Why: highlights the bracket nesting around the cursor without painting every line. - Trade-off: more visual noise for users who prefer a totally clean gutter. -- `editor.fontFamily`: VS Code default → **OS-native monospace stack** (SF Mono on macOS, Cascadia Code on Windows, `monospace` on Linux — fontconfig resolves it to the system's preferred fixed-width family) - - Why: VS Code defaults to Consolas / Menlo. Modern OS-native looks better in 2026. +- `editor.fontFamily`: VS Code default → **OS-native monospace stack** + - Concrete string shipped in the profile JSON: `'SF Mono', 'Cascadia Code', 'JetBrains Mono', 'Ubuntu Mono', 'Liberation Mono', Menlo, Monaco, Consolas, monospace` + - Why: VS Code defaults to platform-specific Consolas / Menlo only. The stack above prefers the OS-native fixed-width face when it exists (SF Mono on macOS, Cascadia on Windows, Ubuntu Mono on Ubuntu) and falls back to the generic `monospace` keyword on Linux — `monospace` is the standard CSS generic-family that fontconfig maps to the system's preferred fixed-width family, where `system` would be ambiguous and could resolve to a proportional face. ## Terminal -- `terminal.integrated.copyOnSelection`: `false` → **`true`** - - Why: matches macOS Terminal / iTerm muscle memory and Linux X11 default. - - Trade-off: clobbers the system clipboard mid-task for users who rely on long-lived clipboard contents. +- `terminal.integrated.copyOnSelection`: `false` → **`false`** (keep VS Code's default) + - Why we considered changing it: iTerm2 and X11 copy-on-select muscle memory is strong for terminal heavy users. + - Why we kept the default: stock macOS Terminal does *not* copy on selection (Cmd+C is required), so "matches macOS Terminal" is wrong, and the change clobbers the system clipboard for the select-to-replace workflow that's common when editing in the integrated terminal. Users who want it can flip the one setting. - `terminal.integrated.shellIntegration.enabled`: `true` → **`true`** (keep) ## Search