From 71db71b9d47ffbeaf1d1c859fa3e3bebb7b2ea29 Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Tue, 23 Jun 2026 21:00:11 -0400
Subject: feat(install-lang): seed a neutral CLAUDE.md when a bundle ships none

install-lang only seeded CLAUDE.md if the chosen bundle shipped one. elisp and go do, python and typescript don't. A project installing a template-less bundle got no CLAUDE.md, and a multi-bundle install inherited whichever bundle shipped one. A bash project that installed elisp and python ended up headed "Elisp project," worse than no header.

I added a language-neutral default (languages/default-CLAUDE.md) that names no language, so single-language, multi-bundle, and wrong-bundle installs all get an accurate "fill this in" header instead of a false one. Per-bundle templates still win where present. The seed-on-first-install, no-overwrite logic is unchanged.

I hardened the Makefile LANGUAGES glob to directories only so the new template file doesn't show up as a selectable language. lint covers the default. The install-lang tests cover the fallback, the bundle-wins branch, and no-overwrite.

A bash bundle is still the real gap for shell-heavy projects, filed as a backlog task.
---
 scripts/install-lang.sh         | 19 ++++++++++++++++---
 scripts/lint.sh                 |  3 +++
 scripts/tests/install-lang.bats | 29 +++++++++++++++++++++++++++++
 3 files changed, 48 insertions(+), 3 deletions(-)

(limited to 'scripts')

diff --git a/scripts/install-lang.sh b/scripts/install-lang.sh
index 0fc9ea8..2f38fcd 100755
--- a/scripts/install-lang.sh
+++ b/scripts/install-lang.sh
@@ -66,13 +66,26 @@ if [ -d "$SRC/githooks" ]; then
   fi
 fi
 
-# 3. CLAUDE.md — seed on first install, don't overwrite unless FORCE=1
+# 3. CLAUDE.md — seed on first install, don't overwrite unless FORCE=1.
+#    Prefer the bundle's own template; fall back to the language-neutral
+#    default so a bundle that ships none still seeds an accurate, non-
+#    mislabeling header instead of nothing. The default names no language,
+#    so multi-bundle and wrong-bundle installs don't inherit a false header.
+CLAUDE_SRC=""
+CLAUDE_KIND=""
 if [ -f "$SRC/CLAUDE.md" ]; then
+  CLAUDE_SRC="$SRC/CLAUDE.md"
+  CLAUDE_KIND="$LANG"
+elif [ -f "$REPO_ROOT/languages/default-CLAUDE.md" ]; then
+  CLAUDE_SRC="$REPO_ROOT/languages/default-CLAUDE.md"
+  CLAUDE_KIND="language-neutral default"
+fi
+if [ -n "$CLAUDE_SRC" ]; then
   if [ -f "$PROJECT/CLAUDE.md" ] && [ "$FORCE" != "1" ]; then
     echo "  [skip] CLAUDE.md already exists (use FORCE=1 to overwrite)"
   else
-    cp "$SRC/CLAUDE.md" "$PROJECT/CLAUDE.md"
-    echo "  [ok] CLAUDE.md installed"
+    cp "$CLAUDE_SRC" "$PROJECT/CLAUDE.md"
+    echo "  [ok] CLAUDE.md installed ($CLAUDE_KIND)"
   fi
 fi
 
diff --git a/scripts/lint.sh b/scripts/lint.sh
index ae30aa5..61a27a1 100755
--- a/scripts/lint.sh
+++ b/scripts/lint.sh
@@ -99,6 +99,9 @@ for claude_md in languages/*/CLAUDE.md; do
   check_md_heading "$claude_md"
 done
 
+# Language-neutral default CLAUDE.md (install-lang's fallback when a bundle ships none)
+[ -f languages/default-CLAUDE.md ] && check_md_heading languages/default-CLAUDE.md
+
 # Hook scripts
 for h in languages/*/claude/hooks/*.sh languages/*/githooks/*; do
   [ -f "$h" ] || continue
diff --git a/scripts/tests/install-lang.bats b/scripts/tests/install-lang.bats
index ecfbe01..f790fbf 100644
--- a/scripts/tests/install-lang.bats
+++ b/scripts/tests/install-lang.bats
@@ -79,6 +79,35 @@ teardown() {
   grep -qxF "coverage/" "$PROJECT/.gitignore"
 }
 
+@test "install-lang python: seeds the language-neutral default CLAUDE.md when the bundle ships none" {
+  run bash "$INSTALL_LANG" python "$PROJECT"
+
+  [ "$status" -eq 0 ]
+  [ -f "$PROJECT/CLAUDE.md" ]
+  # The default names no language, so it can't mislabel a python (or bash, or
+  # multi-bundle) project the way inheriting elisp's "Elisp project" header did.
+  ! grep -qi "Python project" "$PROJECT/CLAUDE.md"
+  ! grep -qi "Elisp project" "$PROJECT/CLAUDE.md"
+  grep -qF "names no language" "$PROJECT/CLAUDE.md"
+  [[ "$output" == *"language-neutral default"* ]]
+}
+
+@test "install-lang elisp: seeds the bundle's own CLAUDE.md, not the default" {
+  run bash "$INSTALL_LANG" elisp "$PROJECT"
+
+  [ "$status" -eq 0 ]
+  grep -qF "Elisp project." "$PROJECT/CLAUDE.md"
+  [[ "$output" == *"CLAUDE.md installed (elisp)"* ]]
+}
+
+@test "install-lang python: does not overwrite an existing CLAUDE.md without FORCE" {
+  echo "MY OWN CLAUDE" > "$PROJECT/CLAUDE.md"
+  run bash "$INSTALL_LANG" python "$PROJECT"
+
+  [ "$status" -eq 0 ]
+  grep -qxF "MY OWN CLAUDE" "$PROJECT/CLAUDE.md"
+}
+
 @test "install-lang go: full bundle lands (rules, hook, settings, githook, CLAUDE.md, coverage)" {
   run bash "$INSTALL_LANG" go "$PROJECT"
 
-- 
cgit v1.2.3