feat: multi-language detection, self-update command

- Importer detects primary + secondary languages (threshold: 5 files or 5%)
- CLI import shows all languages: 'verilog + python, c, vhdl'
- Architecture and AGENTS.md overlay include full language list
- New 'specsmith self-update' command: auto-detects channel (stable/dev),
  supports --channel override and --version pinning
- updater.run_self_update accepts target_version for pinned installs

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

CHANGELOG.md

@@ -9,10 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 - **Dynamic versioning**: `__version__` now reads from `importlib.metadata` at runtime instead of hardcoded strings. Docs use `{{ version }}` placeholders resolved by MkDocs hook. Tests are version-agnostic.
+- **Multi-language detection**: importer now detects and reports all significant languages (primary + secondary). Architecture, AGENTS.md, and CLI display show the full language mix.
+- **`specsmith self-update`** command: auto-detects channel (stable/dev), supports `--channel` override and `--version` pinning.
 - **Dev-release workflow for managed projects** (#35): `specsmith init` with gitflow + GitHub + Python now generates `.github/workflows/dev-release.yml`.
 - **No-hardcoded-versions rule** (H10): governance template and WARP rule enforce `pyproject.toml` as single version source of truth.
 - **Separate PyPI badges**: README shows both stable (blue) and dev (orange) version badges.
 
+### Fixed
+- **Import with large AGENTS.md** (#46): extraction now uses broader keyword matching, unmatched sections go to rules.md, oversized AGENTS.md is backed up and replaced with a hub.
+
 ### Changed
 - RTD default version set to `stable`, default branch set to `develop` (`latest` now builds from develop).
 - Docs version references use dynamic `{{ version }}` instead of hardcoded strings.

src/specsmith/cli.py

@@ -478,7 +478,10 @@ def import_project(project_dir: str, force: bool, guided: bool, dry_run: bool) -
     result = detect_project(root)
 
     console.print(f"  Files: {result.file_count}")
-    console.print(f"  Language: [cyan]{result.primary_language or 'unknown'}[/cyan]")
+    lang_display = result.primary_language or "unknown"
+    if result.secondary_languages:
+        lang_display += f" + {', '.join(result.secondary_languages)}"
+    console.print(f"  Languages: [cyan]{lang_display}[/cyan]")
     console.print(f"  Build system: {result.build_system or 'not detected'}")
     console.print(f"  Test framework: {result.test_framework or 'not detected'}")
     console.print(f"  CI: {result.existing_ci or 'not detected'}")
@@ -1205,6 +1208,50 @@ def update_cmd(check_only: bool, auto_yes: bool, project_dir: str) -> None:
                 console.print(f"  [green]\u2713[/green] {a}")
 
 
+@main.command(name="self-update")
+@click.option(
+    "--channel",
+    type=click.Choice(["stable", "dev"]),
+    default=None,
+    help="Force channel (default: auto-detect from installed version).",
+)
+@click.option("--version", "target_version", default="", help="Install a specific version.")
+def self_update_cmd(channel: str | None, target_version: str) -> None:
+    """Update specsmith to the latest version.
+
+    Auto-detects channel: stable builds upgrade to latest stable,
+    dev builds upgrade to latest dev. Use --channel to override.
+    Use --version to pin a specific version.
+    """
+    from specsmith.updater import check_latest_version, get_update_channel, run_self_update
+
+    current_channel = get_update_channel()
+    effective_channel = channel or current_channel
+
+    if target_version:
+        console.print(f"[bold]Installing specsmith {target_version}...[/bold]")
+        success, msg = run_self_update(target_version=target_version)
+    else:
+        current, latest, effective_channel = check_latest_version(channel=effective_channel)
+        if not latest:
+            console.print("[yellow]Could not reach PyPI.[/yellow]")
+            return
+        if current == latest:
+            console.print(
+                f"[green]\u2713[/green] specsmith {current} is up to date ({effective_channel})."
+            )
+            return
+        console.print(f"  Current: {current} ({current_channel})")
+        console.print(f"  Latest:  {latest} ({effective_channel})")
+        success, msg = run_self_update(channel=effective_channel)
+
+    if success:
+        console.print("[green]\u2713[/green] Updated successfully.")
+        console.print("  Restart your shell to use the new version.")
+    else:
+        console.print(f"[red]\u2717[/red] Update failed: {msg}")
+
+
 @main.command(name="migrate-project")
 @click.option("--project-dir", type=click.Path(exists=True), default=".")
 @click.option("--dry-run", is_flag=True, default=False, help="Show changes without writing.")

src/specsmith/importer.py

@@ -101,6 +101,7 @@ class DetectionResult:
     root: Path
     languages: dict[str, int] = field(default_factory=dict)
     primary_language: str = ""
+    secondary_languages: list[str] = field(default_factory=list)
     build_system: str = ""
     test_framework: str = ""
     vcs_platform: str = ""
@@ -183,6 +184,14 @@ def detect_project(root: Path) -> DetectionResult:
     result.languages = dict(lang_counter.most_common())
     if lang_counter:
         result.primary_language = lang_counter.most_common(1)[0][0]
+        # Secondary languages: all others above a minimum threshold (5 files or 5%)
+        total = sum(lang_counter.values())
+        threshold = max(5, int(total * 0.05))
+        result.secondary_languages = [
+            lang
+            for lang, count in lang_counter.most_common()
+            if lang != result.primary_language and count >= threshold
+        ]
 
     # Build system — check root AND first-level subdirectories
     for indicator, system in _BUILD_SYSTEMS.items():
@@ -847,6 +856,8 @@ def _write(rel_path: str, content: str) -> None:
 
     name = result.root.name
     lang = result.primary_language or "unknown"
+    all_langs = [lang] + (result.secondary_languages or [])
+    lang_display = ", ".join(all_langs) if len(all_langs) > 1 else lang
     today = date.today().isoformat()
     ptype = result.inferred_type.value if result.inferred_type else "unknown"
 
@@ -857,7 +868,7 @@ def _write(rel_path: str, content: str) -> None:
         "This project was imported by specsmith. The governance files contain "
         "detected structure. Review and enrich with your agent.\n\n"
         "## Project Summary\n"
-        f"- **Language**: {lang}\n"
+        f"- **Languages**: {lang_display}\n"
         f"- **Build system**: {result.build_system or 'not detected'}\n"
         f"- **Test framework**: {result.test_framework or 'not detected'}\n"
         f"- **Files detected**: {result.file_count}\n"
@@ -915,7 +926,7 @@ def _write(rel_path: str, content: str) -> None:
         f"# Architecture — {name}\n\n"
         "Architecture auto-generated from project detection.\n\n"
         "## Overview\n"
-        f"- **Language**: {lang}\n"
+        f"- **Languages**: {lang_display}\n"
         f"- **Build system**: {result.build_system or 'not detected'}\n"
         f"- **Test framework**: {result.test_framework or 'not detected'}\n\n"
     )

src/specsmith/updater.py

@@ -59,17 +59,22 @@ def is_outdated() -> bool:
     return current != latest
 
 
-def run_self_update(*, channel: str = "") -> tuple[bool, str]:
+def run_self_update(
+    *, channel: str = "", target_version: str = "",
+) -> tuple[bool, str]:
     """Update specsmith via pip.
 
-    Uses --pre flag for dev channel.
+    If target_version is set, installs that exact version.
+    Otherwise uses --pre flag for dev channel, plain upgrade for stable.
     """
-    if not channel:
-        channel = get_update_channel()
-
-    cmd = ["pip", "install", "--upgrade", "specsmith"]
-    if channel == "dev":
-        cmd.insert(2, "--pre")
+    if target_version:
+        cmd = ["pip", "install", f"specsmith=={target_version}"]
+    else:
+        if not channel:
+            channel = get_update_channel()
+        cmd = ["pip", "install", "--upgrade", "specsmith"]
+        if channel == "dev":
+            cmd.insert(2, "--pre")
 
     try:
         result = subprocess.run(

tests/sandbox/test_sandbox_import.py

@@ -13,7 +13,6 @@
 
 import yaml
 from click.testing import CliRunner
-
 from specsmith.cli import main
 
 

tests/sandbox/test_sandbox_new.py

@@ -12,7 +12,6 @@
 
 import yaml
 from click.testing import CliRunner
-
 from specsmith.cli import main
 
 

tests/sandbox/test_sandbox_types.py

@@ -8,7 +8,6 @@
 
 import yaml
 from click.testing import CliRunner
-
 from specsmith.cli import main
 
 

tests/test_auditor.py

@@ -7,7 +7,6 @@
 from pathlib import Path
 
 import pytest
-
 from specsmith.auditor import run_audit
 
 

tests/test_cli.py

@@ -8,7 +8,6 @@
 
 import yaml
 from click.testing import CliRunner
-
 from specsmith.cli import main
 from specsmith.config import ProjectConfig, ProjectType
 from specsmith.scaffolder import scaffold_project

tests/test_integrations.py

@@ -7,7 +7,6 @@
 from pathlib import Path
 
 import pytest
-
 from specsmith.config import ProjectConfig, ProjectType
 from specsmith.integrations import get_adapter, list_adapters
 from specsmith.integrations.claude_code import ClaudeCodeAdapter