specsmith 0.3.5__tar.gz → 0.3.6.dev170__tar.gz

{specsmith-0.3.5/src/specsmith.egg-info → specsmith-0.3.6.dev170}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: specsmith
-Version: 0.3.5
-Summary: Applied Epistemic Engineering toolkit — forge epistemically-governed scaffolds, stress-test belief systems, and run AEE pipelines.
+Version: 0.3.6.dev170
+Summary: Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands.
 Author: BitConcepts
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/BitConcepts/specsmith
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://specsmith.readthedocs.io
 Project-URL: Repository, https://github.com/BitConcepts/specsmith
 Project-URL: Changelog, https://github.com/BitConcepts/specsmith/blob/main/CHANGELOG.md
 Project-URL: Issues, https://github.com/BitConcepts/specsmith/issues
-Keywords: agentic,scaffold,governance,agents-md,cli,epistemic-engineering,belief-artifacts,stress-testing,certainty,trace-vault,aee,knowledge-engineering
+Keywords: agentic,scaffold,governance,agents-md,cli,epistemic-engineering,belief-artifacts,stress-testing,certainty,trace-vault,aee,knowledge-engineering,fpga,hdl,vhdl,execution-profiles,tool-installer,llm,ollama,requirements-management
 Classifier: Development Status :: 4 - Beta
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -66,6 +66,7 @@ Dynamic: license-file
 # specsmith
 
 [![CI](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml)
+[![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=github)](https://github.com/sponsors/BitConcepts)
 [![Docs](https://readthedocs.org/projects/specsmith/badge/?version=stable)](https://specsmith.readthedocs.io/en/stable/)
 [![PyPI](https://img.shields.io/pypi/v/specsmith?label=stable&style=flat&color=blue&cacheSeconds=60)](https://pypi.org/project/specsmith/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
@@ -122,7 +123,7 @@ specsmith phase list     # list all phases
 ```
 
 The current phase is persisted in `scaffold.yml` as `aee_phase` and displayed in the VS Code
-Governance Panel. Each phase has a checklist of file/command criteria, recommended commands,
+Settings Panel. Each phase has a checklist of file/command criteria, recommended commands,
 and a readiness percentage.
 
 ---
@@ -190,24 +191,38 @@ The **specsmith AEE Workbench** VS Code extension is the flagship client:
 ```
 # Install specsmith first, then:
 # VS Code: Ctrl+Shift+P → specsmith: New Agent Session
-# Governance Panel: Ctrl+Shift+G
+# Settings Panel: Ctrl+Shift+G
 ```
 
 **Key features:**
-- **5-tab Governance Panel** — Project / Tools / Files / Updates & System / Actions & AI
+- **6-tab Settings panel** — Project / Tools / Files / Updates / Actions / Execution
+- **Execution profiles** — safe (read-only) / standard / open / admin; custom allow/block command lists stored in `scaffold.yml`
 - **AEE phase indicator** — shows current phase with readiness %, Next Phase button, and phase selector
 - **AI agent sessions** — independent process per project, JSONL bridge, chat with file injection
 - **Live model listing** — Anthropic, OpenAI, Gemini, Mistral, local Ollama (GPU-aware)
 - **Ollama integration** — browse curated catalog, download models with progress, task-based suggestions
 - **FPGA/HDL tool support** — vivado, gtkwave, vsg, ghdl, verilator, yosys, nextpnr, and 15 more
+- **Tool installer** — scan installed tools; one-click install via winget/brew/apt for missing tools
+- **Tool rules** — curated AI context rules for 20+ tools (VSG, GHDL, Verilator, ruff, mypy, etc.) auto-injected into agent system prompt
 - **API key management** — stored in OS credential store (Windows Credential Manager / macOS Keychain)
-- **Update checker** — PyPI version check with Install Update button, system info panel
-- **Auto-open** — governance panel opens automatically when VS Code starts with a workspace
+- **Update checker** — PyPI version check, Install Update button, release channel selector (stable / pre-release)
+- **Auto-open** — Settings panel always opens alongside every new session; never a blank pane
 
 **[→ specsmith-vscode on GitHub](https://github.com/BitConcepts/specsmith-vscode)**
 
 ---
 
+## Supporting specsmith
+
+If specsmith is saving you time or helping your team ship better software, please consider:
+
+- **[Sponsoring BitConcepts](https://github.com/sponsors/BitConcepts)** — directly funds development
+- **Starring** [specsmith](https://github.com/BitConcepts/specsmith) and [specsmith-vscode](https://github.com/BitConcepts/specsmith-vscode) on GitHub
+- **Reporting bugs** and **requesting features** via [GitHub Issues](https://github.com/BitConcepts/specsmith/issues)
+- **Contributing** — see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+---
+
 ## Ollama — Local LLMs (Zero API Cost)
 
 specsmith has first-class Ollama support, including:
@@ -232,7 +247,7 @@ specsmith supports FPGA-specific project types with full governance:
 
 ```yaml
 # scaffold.yml
-type: fpga-rtl-xilinx
+type: fpga-rtl-amd          # or fpga-rtl-intel / fpga-rtl-lattice / fpga-rtl
 fpga_tools:
   - vivado
   - gtkwave
@@ -264,6 +279,8 @@ Supported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.
 
 **VCS:** `commit` `push` `sync` `branch` `pr` `status`
 
+**Tools:** `tools scan [--fpga]` `tools install <tool>` `tools rules [--tool] [--list]`
+
 **Tools:** `exec` `ps` `abort` `watch` `optimize` `credits` `self-update`
 
 **Auth:** `auth set/list/remove/check`

{specsmith-0.3.5 → specsmith-0.3.6.dev170}/README.md

@@ -1,6 +1,7 @@
 # specsmith
 
 [![CI](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml)
+[![Sponsor](https://img.shields.io/badge/sponsor-%E2%9D%A4-ea4aaa?logo=github)](https://github.com/sponsors/BitConcepts)
 [![Docs](https://readthedocs.org/projects/specsmith/badge/?version=stable)](https://specsmith.readthedocs.io/en/stable/)
 [![PyPI](https://img.shields.io/pypi/v/specsmith?label=stable&style=flat&color=blue&cacheSeconds=60)](https://pypi.org/project/specsmith/)
 [![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
@@ -57,7 +58,7 @@ specsmith phase list     # list all phases
 ```
 
 The current phase is persisted in `scaffold.yml` as `aee_phase` and displayed in the VS Code
-Governance Panel. Each phase has a checklist of file/command criteria, recommended commands,
+Settings Panel. Each phase has a checklist of file/command criteria, recommended commands,
 and a readiness percentage.
 
 ---
@@ -125,24 +126,38 @@ The **specsmith AEE Workbench** VS Code extension is the flagship client:
 ```
 # Install specsmith first, then:
 # VS Code: Ctrl+Shift+P → specsmith: New Agent Session
-# Governance Panel: Ctrl+Shift+G
+# Settings Panel: Ctrl+Shift+G
 ```
 
 **Key features:**
-- **5-tab Governance Panel** — Project / Tools / Files / Updates & System / Actions & AI
+- **6-tab Settings panel** — Project / Tools / Files / Updates / Actions / Execution
+- **Execution profiles** — safe (read-only) / standard / open / admin; custom allow/block command lists stored in `scaffold.yml`
 - **AEE phase indicator** — shows current phase with readiness %, Next Phase button, and phase selector
 - **AI agent sessions** — independent process per project, JSONL bridge, chat with file injection
 - **Live model listing** — Anthropic, OpenAI, Gemini, Mistral, local Ollama (GPU-aware)
 - **Ollama integration** — browse curated catalog, download models with progress, task-based suggestions
 - **FPGA/HDL tool support** — vivado, gtkwave, vsg, ghdl, verilator, yosys, nextpnr, and 15 more
+- **Tool installer** — scan installed tools; one-click install via winget/brew/apt for missing tools
+- **Tool rules** — curated AI context rules for 20+ tools (VSG, GHDL, Verilator, ruff, mypy, etc.) auto-injected into agent system prompt
 - **API key management** — stored in OS credential store (Windows Credential Manager / macOS Keychain)
-- **Update checker** — PyPI version check with Install Update button, system info panel
-- **Auto-open** — governance panel opens automatically when VS Code starts with a workspace
+- **Update checker** — PyPI version check, Install Update button, release channel selector (stable / pre-release)
+- **Auto-open** — Settings panel always opens alongside every new session; never a blank pane
 
 **[→ specsmith-vscode on GitHub](https://github.com/BitConcepts/specsmith-vscode)**
 
 ---
 
+## Supporting specsmith
+
+If specsmith is saving you time or helping your team ship better software, please consider:
+
+- **[Sponsoring BitConcepts](https://github.com/sponsors/BitConcepts)** — directly funds development
+- **Starring** [specsmith](https://github.com/BitConcepts/specsmith) and [specsmith-vscode](https://github.com/BitConcepts/specsmith-vscode) on GitHub
+- **Reporting bugs** and **requesting features** via [GitHub Issues](https://github.com/BitConcepts/specsmith/issues)
+- **Contributing** — see [CONTRIBUTING.md](CONTRIBUTING.md)
+
+---
+
 ## Ollama — Local LLMs (Zero API Cost)
 
 specsmith has first-class Ollama support, including:
@@ -167,7 +182,7 @@ specsmith supports FPGA-specific project types with full governance:
 
 ```yaml
 # scaffold.yml
-type: fpga-rtl-xilinx
+type: fpga-rtl-amd          # or fpga-rtl-intel / fpga-rtl-lattice / fpga-rtl
 fpga_tools:
   - vivado
   - gtkwave
@@ -199,6 +214,8 @@ Supported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.
 
 **VCS:** `commit` `push` `sync` `branch` `pr` `status`
 
+**Tools:** `tools scan [--fpga]` `tools install <tool>` `tools rules [--tool] [--list]`
+
 **Tools:** `exec` `ps` `abort` `watch` `optimize` `credits` `self-update`
 
 **Auth:** `auth set/list/remove/check`

{specsmith-0.3.5 → specsmith-0.3.6.dev170}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specsmith"
-version = "0.3.5"
-description = "Applied Epistemic Engineering toolkit — forge epistemically-governed scaffolds, stress-test belief systems, and run AEE pipelines."
+version = "0.3.6.dev170"
+description = "Applied Epistemic Engineering toolkit — AEE agent sessions, execution profiles, FPGA/HDL governance, tool installer, 50+ CLI commands."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"
@@ -16,6 +16,8 @@ keywords = [
     "agentic", "scaffold", "governance", "agents-md", "cli",
     "epistemic-engineering", "belief-artifacts", "stress-testing",
     "certainty", "trace-vault", "aee", "knowledge-engineering",
+    "fpga", "hdl", "vhdl", "execution-profiles", "tool-installer",
+    "llm", "ollama", "requirements-management",
 ]
 classifiers = [
     "Development Status :: 4 - Beta",
@@ -99,6 +101,11 @@ line-length = 100
 [tool.ruff.lint]
 select = ["E", "F", "W", "I", "UP", "B", "SIM"]
 
+[tool.ruff.lint.per-file-ignores]
+# Long rule text and install command strings in documentation modules
+"src/specsmith/toolrules.py" = ["E501"]
+"src/specsmith/tool_installer.py" = ["E501"]
+
 [tool.mypy]
 python_version = "3.10"
 strict = true
@@ -120,6 +127,8 @@ module = [
     "google.*",
     "yaml",
     "yaml.*",
+    "keyring",   # optional OS credential store; stubs not published
+    "keyring.*",
 ]
 ignore_missing_imports = true
 
@@ -140,6 +149,9 @@ module = [
     "specsmith.importer",
     "specsmith.agent.providers.gemini",
     "specsmith.agent.runner",
+    "specsmith.profiles",
+    "specsmith.toolrules",
+    "specsmith.tool_installer",
 ]
 ignore_errors = true
 

{specsmith-0.3.5 → specsmith-0.3.6.dev170}/src/specsmith/agent/providers/ollama.py

@@ -96,18 +96,32 @@ class OllamaProvider:
     ) -> CompletionResponse:
         """Complete using the native /api/chat endpoint.
 
-        Tool calling is attempted first; if the model returns an error
-        indicating no tool support (HTTP 400 etc.) we retry without tools.
+        Tool calling is attempted first; if the model returns HTTP 400
+        (tool calling not supported) we retry without tools.  If the native
+        fallback *also* returns 400 (common when the ``think`` parameter is
+        unsupported by an older Ollama server) we strip ``think`` and retry.
         """
         if tools:
             try:
                 return self._complete_with_tools(messages, tools, max_tokens)
             except Exception as exc:  # noqa: BLE001
-                if _is_tool_fallback_error(exc):
-                    # Model doesn't support tool calling — degrade gracefully
-                    return self._complete_native(messages, max_tokens)
-                raise
-        return self._complete_native(messages, max_tokens)
+                if not _is_tool_fallback_error(exc):
+                    raise
+                # Fall through to native (no-tools) completion below
+        return self._complete_native_with_fallback(messages, max_tokens)
+
+    def _complete_native_with_fallback(
+        self, messages: list[Message], max_tokens: int
+    ) -> CompletionResponse:
+        """Call _complete_native; if it fails with 400 and think is set, retry without it."""
+        try:
+            return self._complete_native(messages, max_tokens)
+        except Exception as exc:  # noqa: BLE001
+            if self._think is not None and _is_tool_fallback_error(exc):
+                # Older Ollama doesn't support 'think' — disable permanently for this session
+                self._think = None
+                return self._complete_native(messages, max_tokens)
+            raise
 
     def _complete_native(self, messages: list[Message], max_tokens: int) -> CompletionResponse:
         """Plain chat completion without tools."""

{specsmith-0.3.5 → specsmith-0.3.6.dev170}/src/specsmith/agent/runner.py

@@ -112,8 +112,10 @@ def build_system_prompt(
         lines = content.splitlines()[:200]
         agents_md = "\n".join(lines)
 
-    # Load spec version from scaffold.yml
+    # Load scaffold.yml for spec_version, project type, and FPGA tools
     spec_version = "unknown"
+    project_type = ""
+    fpga_tools: list[str] = []
     scaffold_path = root / "scaffold.yml"
     if scaffold_path.exists():
         try:
@@ -122,6 +124,8 @@ def build_system_prompt(
             with open(scaffold_path) as f:
                 raw = yaml.safe_load(f) or {}
             spec_version = raw.get("spec_version", "unknown")
+            project_type = str(raw.get("type", ""))
+            fpga_tools = list(raw.get("fpga_tools", []) or [])
         except Exception:  # noqa: BLE001
             pass
 
@@ -148,9 +152,26 @@ H13: All proposals must state their epistemic boundaries. Hidden assumptions are
         agents_md or f"Spec version: {spec_version}. AGENTS.md not found — run specsmith audit."
     )
 
+    # Load tool-specific rules for this project type
+    tool_rules_section = ""
+    if project_type:
+        try:
+            from specsmith.toolrules import get_rules_for_project
+
+            rules_text = get_rules_for_project(project_type, fpga_tools, max_chars=4000)
+            if rules_text:
+                tool_rules_section = f"\n## Tool Rules\n{rules_text}\n"
+        except Exception:  # noqa: BLE001
+            pass
+
     prompt = f"""You are an AEE-integrated specsmith agent for this project.
-ALWAYS respond in English only, regardless of the user's language or your default language.
-Do not use Chinese, Japanese, Korean, or any other non-English language at any time.
+
+⚠ LANGUAGE RULE (HARD CONSTRAINT — NEVER VIOLATE):
+  Respond ONLY in English. Every single response must be in English.
+  Never use Chinese (中文), Japanese (日本語), Korean (한국어), French, German, Spanish,
+  Arabic, or ANY other non-English language — not even a single word.
+  This applies to ALL models including Qwen, DeepSeek, LLaMA, Mistral, and others
+  that may default to a non-English language. ENGLISH ONLY, ALWAYS.
 
 ## Project Governance
 {governance_text}
@@ -164,7 +185,7 @@ Do not use Chinese, Japanese, Korean, or any other non-English language at any t
 - The ledger + accepted repo state is authority
 {aee_section}
 {skills_section}
-
+{tool_rules_section}
 ## Quick Commands
 Users may type these shortcuts:
 - `start` — new session protocol (sync + update check + load state)
@@ -213,7 +234,10 @@ class AgentRunner:
     }
 
     QUICK_COMMANDS = {
-        "start": "Run session start protocol: sync, load AGENTS.md, read last LEDGER.md entries",
+        "start": (
+            "[RESPOND IN ENGLISH ONLY] "
+            "Run session start protocol: sync, load AGENTS.md, read last LEDGER.md entries"
+        ),
         "resume": "Resume from last LEDGER.md entry — summarize state and propose next task",
         "save": "Write a ledger entry summarizing this session's work",
         "audit": "Run specsmith audit --fix",
@@ -252,6 +276,11 @@ class AgentRunner:
         self._hooks = HookRegistry()
         self._system_prompt = ""
 
+        # Execution profile — loaded from scaffold.yml at session start
+        from specsmith import profiles
+
+        self._profile = profiles.load_from_scaffold(self.project_dir)
+
         # Token / credit optimization engine (opt-in)
         self._optimizer: OptimizationEngine | None = (
             OptimizationEngine(
@@ -474,6 +503,8 @@ class AgentRunner:
         self, tool_calls: list[dict[str, Any]], silent: bool = False
     ) -> list[ToolResult]:
         """Execute tool calls and return results."""
+        from specsmith import profiles as _profiles
+
         results: list[ToolResult] = []
         for tc in tool_calls:
             name = tc.get("name", "")
@@ -486,6 +517,74 @@ class AgentRunner:
                 else:
                     self._print(f"\n[Tool: {name}]")
 
+            # ── Execution profile enforcement ──────────────────────────────────
+            tool_ok, tool_reason = _profiles.check_tool_allowed(self._profile, name)
+            if not tool_ok:
+                blocked_msg = f"[BLOCKED by profile '{self._profile.name}'] {tool_reason}"
+                if not silent:
+                    if self._json_events:
+                        self._emit_event(type="tool_blocked", name=name, reason=tool_reason)
+                    else:
+                        self._print(f"  ✗ {blocked_msg}")
+                results.append(
+                    ToolResult(
+                        tool_name=name,
+                        tool_call_id=call_id,
+                        content=blocked_msg,
+                        error=True,
+                    )
+                )
+                continue
+
+            # For run_command: check the command string
+            if name == "run_command" and "command" in inputs:
+                cmd_ok, cmd_reason = _profiles.check_command_allowed(
+                    self._profile, str(inputs["command"])
+                )
+                if not cmd_ok:
+                    blocked_msg = f"[BLOCKED by profile '{self._profile.name}'] {cmd_reason}"
+                    if not silent:
+                        if self._json_events:
+                            self._emit_event(
+                                type="tool_blocked",
+                                name=name,
+                                command=inputs["command"],
+                                reason=cmd_reason,
+                            )
+                        else:
+                            self._print(f"  ✗ {blocked_msg}")
+                    results.append(
+                        ToolResult(
+                            tool_name=name,
+                            tool_call_id=call_id,
+                            content=blocked_msg,
+                            error=True,
+                        )
+                    )
+                    continue
+
+            # For write_file: check file-write permission and size
+            if name == "write_file" and "content" in inputs:
+                write_ok, write_reason = _profiles.check_write_allowed(
+                    self._profile, str(inputs["content"])
+                )
+                if not write_ok:
+                    blocked_msg = f"[BLOCKED by profile '{self._profile.name}'] {write_reason}"
+                    if not silent:
+                        if self._json_events:
+                            self._emit_event(type="tool_blocked", name=name, reason=write_reason)
+                        else:
+                            self._print(f"  ✗ {blocked_msg}")
+                    results.append(
+                        ToolResult(
+                            tool_name=name,
+                            tool_call_id=call_id,
+                            content=blocked_msg,
+                            error=True,
+                        )
+                    )
+                    continue
+
             # Fire pre_tool hooks
             pre_ctx = HookContext(
                 trigger=HookTrigger.PRE_TOOL,

{specsmith-0.3.5 → specsmith-0.3.6.dev170}/src/specsmith/agent/tools.py

@@ -26,6 +26,16 @@ from pathlib import Path
 
 from specsmith.agent.core import Tool, ToolParam
 
+# Env vars that prevent Rich from using the Windows Console API
+# (LegacyWindowsTerm) when stdout is a captured pipe. Without these, Rich
+# crashes with 'WriteFile failed' / handle errors on every command.
+_SUBPROCESS_ENV: dict[str, str] = {
+    **os.environ,
+    "NO_COLOR": "1",  # Disables Rich colour / Windows console API path
+    "FORCE_COLOR": "0",  # Belt-and-suspenders: also suppress colour
+    "PYTHONIOENCODING": "utf-8",  # Ensure UTF-8 on pipes regardless of locale
+}
+
 
 def _run_specsmith(args: list[str], project_dir: str = ".") -> str:
     """Execute a specsmith command and return combined stdout+stderr."""
@@ -36,6 +46,7 @@ def _run_specsmith(args: list[str], project_dir: str = ".") -> str:
             capture_output=True,
             text=True,
             timeout=120,
+            env=_SUBPROCESS_ENV,
         )
         output = (result.stdout + result.stderr).strip()
         if result.returncode != 0:

{specsmith-0.3.5 → specsmith-0.3.6.dev170}/src/specsmith/cli.py

@@ -4059,6 +4059,184 @@ def tools_scan_cmd(project_dir: str, as_json: bool, fpga: bool) -> None:
         )
 
 
+@tools_group.command(name="install")
+@click.argument("tool", required=False, default="")
+@click.option(
+    "--list",
+    "list_all",
+    is_flag=True,
+    default=False,
+    help="List all known installable tools.",
+)
+@click.option(
+    "--category",
+    default="",
+    help="Filter by category (fpga, python, c, rust, go, devops, linux, doc, js, other).",
+)
+@click.option(
+    "--dry-run",
+    is_flag=True,
+    default=False,
+    help="Print the install command without running it.",
+)
+@click.option(
+    "--yes",
+    "-y",
+    is_flag=True,
+    default=False,
+    help="Run the install command without prompting.",
+)
+def tools_install_cmd(tool: str, list_all: bool, category: str, dry_run: bool, yes: bool) -> None:
+    """Show or run the install command for a development tool.
+
+    TOOL is the tool key (e.g. ghdl, ruff, verilator). Run with --list to see
+    all available tools.  The best install method for the current platform is
+    selected automatically (winget on Windows, brew on macOS, apt/dnf on Linux).
+    """
+    import subprocess
+
+    from specsmith.tool_installer import (
+        KNOWN_TOOLS,
+        ToolInstallInfo,
+        get_install_command,
+        list_tools,
+    )
+
+    if list_all or not tool:
+        items: list[ToolInstallInfo] = list_tools(category=category or None)
+        console.print(f"[bold]Known installable tools[/bold] ({len(items)})\n")
+        cats: dict[str, list[ToolInstallInfo]] = {}
+        for t in items:
+            cats.setdefault(t.category, []).append(t)
+        for cat, ts in sorted(cats.items()):
+            console.print(f"  [teal]{cat}[/teal]")
+            for t in ts:
+                console.print(f"    [dim]{t.key:<25s}[/dim]  {t.display_name}")
+        console.print()
+        console.print(
+            "  Run [bold]specsmith tools install <key>[/bold] to get the install command."
+        )
+        return
+
+    info = KNOWN_TOOLS.get(tool)
+    if info is None:
+        # Fuzzy fallback: substring match
+        matches = [k for k in KNOWN_TOOLS if tool.lower() in k.lower()]
+        if matches:
+            console.print(
+                f"[yellow]Unknown tool '{tool}'. Did you mean: {', '.join(matches[:5])}?[/yellow]"
+            )
+        else:
+            console.print(
+                f"[red]Unknown tool '{tool}'.[/red] "
+                "Run [bold]specsmith tools install --list[/bold] "
+                "to see available tools."
+            )
+        raise SystemExit(1)
+
+    cmd = get_install_command(tool)
+    if cmd is None:
+        if info.manual:
+            console.print(
+                f"[yellow]No automatic install for '{info.display_name}' on this platform.[/yellow]"
+            )
+            console.print(f"  Manual install: {info.manual}")
+        else:
+            console.print(f"[red]No install method known for '{tool}'.[/red]")
+        return
+
+    if info.notes:
+        console.print(f"[dim]Note:[/dim] {info.notes}")
+
+    if dry_run or not yes:
+        console.print(f"\n[bold]Install command for {info.display_name}:[/bold]")
+        console.print(f"  [teal]{cmd}[/teal]")
+        if not dry_run and not yes:
+            confirmed = console.input("\nRun this command now? [[bold]y[/bold]/N] ").strip().lower()
+            if confirmed not in ("y", "yes"):
+                console.print("[dim]Aborted.[/dim]")
+                return
+    if not dry_run:
+        console.print(f"[bold]Running:[/bold] {cmd}")
+        result = subprocess.run(cmd, shell=True, check=False)  # noqa: S602
+        if result.returncode != 0:
+            console.print(f"[red]Install failed (exit {result.returncode}).[/red]")
+            raise SystemExit(result.returncode)
+        console.print("[green]\u2713[/green] Done.")
+
+
+@tools_group.command(name="rules")
+@click.option("--project-dir", type=click.Path(exists=True), default=".")
+@click.option(
+    "--tool",
+    "tool_key",
+    default="",
+    help="Show rules for a specific tool key (e.g. ghdl, ruff).",
+)
+@click.option(
+    "--list",
+    "list_all",
+    is_flag=True,
+    default=False,
+    help="List all tools that have AI context rules.",
+)
+def tools_rules_cmd(project_dir: str, tool_key: str, list_all: bool) -> None:
+    """Show the AI context rules injected into the agent system prompt.
+
+    Without options, shows rules for the current project type (from scaffold.yml).
+    Use --tool to show rules for a specific tool, or --list to see all available.
+    """
+    from specsmith.toolrules import TOOL_RULES, get_rules_for_project
+
+    if list_all:
+        console.print(f"[bold]Tool rules available[/bold] ({len(TOOL_RULES)} tools):\n")
+        for key in sorted(TOOL_RULES):
+            first_line = TOOL_RULES[key].strip().splitlines()[0].lstrip("# ").strip()
+            console.print(f"  [teal]{key:<25s}[/teal]  {first_line}")
+        console.print("\n  Use [bold]specsmith tools rules --tool <key>[/bold] to view full rules.")
+        return
+
+    if tool_key:
+        if tool_key not in TOOL_RULES:
+            matches = [k for k in TOOL_RULES if tool_key.lower() in k.lower()]
+            if matches:
+                console.print(
+                    f"[yellow]No rules for '{tool_key}'. Similar: {', '.join(matches[:5])}[/yellow]"
+                )
+            else:
+                console.print(f"[red]No rules for '{tool_key}'.[/red]")
+            raise SystemExit(1)
+        console.print(TOOL_RULES[tool_key])
+        return
+
+    # Project-level rules from scaffold.yml
+    import yaml
+
+    root = Path(project_dir).resolve()
+    scaffold_path = root / "scaffold.yml"
+    if not scaffold_path.exists():
+        console.print(
+            "[yellow]No scaffold.yml found. "
+            "Run specsmith init or use --tool to view a specific tool.[/yellow]"
+        )
+        raise SystemExit(1)
+
+    with open(scaffold_path) as f:
+        raw = yaml.safe_load(f) or {}
+    project_type = str(raw.get("type", "cli-python"))
+    fpga_tools: list[str] = raw.get("fpga_tools", []) or []
+
+    rules = get_rules_for_project(project_type, fpga_tools, max_chars=20000)
+    if not rules:
+        console.print(
+            f"[yellow]No tool rules configured for project type '{project_type}'.[/yellow]"
+        )
+        return
+
+    console.print(f"[bold]Tool rules for project type:[/bold] [teal]{project_type}[/teal]\n")
+    console.print(rules)
+
+
 main.add_command(tools_group)