specsmith 0.3.0.dev139__tar.gz → 0.3.6__tar.gz

specsmith-0.3.6/PKG-INFO

@@ -0,0 +1,363 @@
+Metadata-Version: 2.4
+Name: specsmith
+Version: 0.3.6
+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
+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,fpga,hdl,vhdl,execution-profiles,tool-installer,llm,ollama,requirements-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Requires-Dist: types-pyyaml>=6.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.56; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=1.0; extra == "gemini"
+Provides-Extra: mistral
+Requires-Dist: openai>=1.0; extra == "mistral"
+Provides-Extra: gui
+Requires-Dist: PySide6>=6.6; extra == "gui"
+Provides-Extra: agent
+Requires-Dist: anthropic>=0.56; extra == "agent"
+Requires-Dist: openai>=1.0; extra == "agent"
+Provides-Extra: all
+Requires-Dist: anthropic>=0.56; extra == "all"
+Requires-Dist: openai>=1.0; extra == "all"
+Requires-Dist: pytest>=7.0; extra == "all"
+Requires-Dist: pytest-cov>=4.0; extra == "all"
+Requires-Dist: ruff>=0.4; extra == "all"
+Requires-Dist: mypy>=1.10; extra == "all"
+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/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![VS Code Extension](https://img.shields.io/badge/VS%20Code-AEE%20Workbench-4ec9b0?logo=visualstudiocode)](https://github.com/BitConcepts/specsmith-vscode)
+
+**Applied Epistemic Engineering toolkit for AI-assisted development.**
+
+> Intelligence proposes. Constraints decide. The ledger remembers.
+
+specsmith treats belief systems like code: codable, testable, and deployable. It scaffolds
+epistemically-governed projects, stress-tests requirements as BeliefArtifacts, runs
+cryptographically-sealed trace vaults, and orchestrates AI agents under formal AEE governance.
+
+It also co-installs the standalone `epistemic` Python library for direct use in any project:
+
+```python
+from epistemic import AEESession         # works in any Python 3.10+ project
+from epistemic import BeliefArtifact, StressTester, CertaintyEngine
+```
+
+---
+
+## What is Applied Epistemic Engineering?
+
+AEE treats requirements, decisions, and assumptions — the beliefs your project depends on — as
+engineering artifacts subject to the same discipline as code: version control, testing, and refactoring.
+
+**The 4-step core method: Frame → Disassemble → Stress-Test → Reconstruct**
+
+**The 5 foundational axioms:**
+1. **Observability** — every belief must be inspectable
+2. **Falsifiability** — every belief must be challengeable
+3. **Irreducibility** — beliefs decompose to atomic primitives
+4. **Reconstructability** — every failed belief can be rebuilt
+5. **Convergence** — stress-test + recovery always reaches Equilibrium
+
+---
+
+## The AEE Workflow — 7 Phases
+
+specsmith tracks your project through the full AEE development cycle:
+
+```
+🌱 Inception → 🏗 Architecture → 📋 Requirements → ✅ Test Spec
+    → ⚙ Implementation → 🔬 Verification → 🚀 Release
+```
+
+```bash
+specsmith phase          # show current phase + readiness checklist
+specsmith phase next     # advance to the next phase (runs checks first)
+specsmith phase set requirements  # jump to a specific phase
+specsmith phase list     # list all phases
+```
+
+The current phase is persisted in `scaffold.yml` as `aee_phase` and displayed in the VS Code
+Settings Panel. Each phase has a checklist of file/command criteria, recommended commands,
+and a readiness percentage.
+
+---
+
+## Install
+
+**Recommended — via the VS Code extension (creates a project-isolated environment):**
+
+1. Install the [specsmith AEE Workbench](https://github.com/BitConcepts/specsmith-vscode) VS Code extension
+2. Open `Ctrl+Shift+,` (⚙ specsmith Settings)
+3. Click **🔒 Create Environment** — creates `~/.specsmith/venv/` with specsmith + your provider packages
+
+The extension uses this environment for all agent sessions and terminal commands.
+
+**Or via pipx (system-wide):**
+
+```bash
+pipx install specsmith                    # core CLI + epistemic library
+pipx inject specsmith anthropic           # + Claude support
+pipx inject specsmith openai              # + GPT / O-series support
+pipx inject specsmith google-generativeai # + Gemini support
+```
+
+**Or with pip:**
+
+```bash
+pip install specsmith                     # core
+pip install "specsmith[anthropic]"       # + Claude
+pip install "specsmith[openai]"          # + GPT/O-series
+pip install "specsmith[gemini]"          # + Gemini
+```
+
+**Update:**
+
+```bash
+pipx upgrade specsmith
+specsmith self-update
+```
+
+---
+
+## Quick Start
+
+```bash
+# New project (interactive)
+specsmith init
+
+# Adopt an existing project
+specsmith import --project-dir ./my-project
+
+# Check governance health
+specsmith audit --project-dir ./my-project
+
+# Run AEE stress-test on requirements
+specsmith stress-test --project-dir ./my-project
+
+# Full epistemic audit (certainty + logic knots + recovery proposals)
+specsmith epistemic-audit --project-dir ./my-project
+
+# Start the agentic REPL
+specsmith run --project-dir ./my-project
+
+# Check current AEE workflow phase
+specsmith phase --project-dir ./my-project
+```
+
+---
+
+## VS Code Extension
+
+The **specsmith AEE Workbench** VS Code extension is the flagship client:
+
+```
+# VS Code: Ctrl+Shift+P → specsmith: New Agent Session
+# Settings:         Ctrl+Shift+,     (⚙ specsmith Settings — global)
+# Project Settings: Ctrl+Shift+G     (⚙ Project Settings — per-project)
+```
+
+**Key features:**
+- **Dual-panel architecture** — **⚙ specsmith Settings** (global: venv, version, Ollama, system)
+  and **⚙ Project Settings** (per-project: scaffold, tools, files, actions, execution)
+- **Global environment management** — `~/.specsmith/venv/` with Create / Update / Rebuild / Delete;
+  persistent restart banner; Remove System Installs cleanup button
+- **VCS context at session start** — git status + recent commits shown in chat and in system prompt
+- **Execution profiles** — safe / standard / open / admin; custom allow/block command lists
+- **AEE phase indicator** — shows current phase with readiness %, Next Phase button, 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** — model manager (update/remove/update-all), version check, upgrade
+- **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
+- **API key management** — stored in OS credential store (Windows Credential Manager / macOS Keychain)
+- **Update checker** — PyPI version check, auto-checks on panel open, release channel selector
+
+**[→ 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:
+
+```bash
+specsmith ollama gpu                    # detect GPU and VRAM tier
+specsmith ollama available              # show catalog filtered by VRAM budget
+specsmith ollama available --task code  # filter by task type
+specsmith ollama pull qwen2.5:14b      # download a model
+specsmith ollama suggest requirements  # task-based recommendations
+specsmith ollama list                  # show installed models
+```
+
+GPU-aware context sizing in the VS Code extension: 4K/8K/16K/32K tokens based on detected VRAM.
+Override with `specsmith.ollamaContextLength` in VS Code settings.
+
+---
+
+## FPGA / HDL Projects
+
+specsmith supports FPGA-specific project types with full governance:
+
+```yaml
+# scaffold.yml
+type: fpga-rtl-amd          # or fpga-rtl-intel / fpga-rtl-lattice / fpga-rtl
+fpga_tools:
+  - vivado
+  - gtkwave
+  - vsg
+  - ghdl
+  - verilator
+```
+
+Supported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.
+**Simulation:** ghdl, iverilog, verilator, modelsim, questasim, xsim.
+**Waveform:** gtkwave, surfer. **Linting:** vsg, verible, svlint.
+**Formal:** symbiyosys. **OSS flow:** yosys, nextpnr, openFPGALoader.
+
+---
+
+## 50+ CLI Commands
+
+**Governance:** `init` `import` `audit` `validate` `diff` `upgrade` `compress` `doctor` `export` `architect`
+
+**AEE Epistemic:** `stress-test` `epistemic-audit` `belief-graph` `trace seal/verify/log` `integrate`
+
+**Workflow:** `phase show/set/next/list` `ledger add/list` `req list/add/gaps/trace`
+
+**Agent:** `run` `agent providers/tools/skills`
+
+**Ollama:** `ollama list/available/gpu/pull/suggest`
+
+**Workspace:** `workspace init/audit/export`
+
+**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`
+
+**Patent:** `patent search/prior-art`
+
+---
+
+## 35 Project Types
+
+**Software:** Python CLI/lib/web, Rust, Go, C/C++, .NET, Node.js/TypeScript, mobile, microservices, data/ML.
+
+**Hardware/Embedded:** FPGA/RTL (Xilinx, Intel, Lattice, generic), Yocto BSP, embedded C/C++.
+
+**Documents:** Technical specs, research papers, API specs, requirements management.
+
+**Business/Legal:** Business plans, patent applications, compliance frameworks.
+
+---
+
+## epistemic Library
+
+The standalone `epistemic` Python library works in any Python 3.10+ project — no specsmith coupling:
+
+```python
+from epistemic import AEESession, BeliefArtifact, StressTester
+
+session = AEESession("my-project", threshold=0.70)
+session.add_belief(
+    artifact_id="HYP-001",
+    propositions=["The API always returns valid JSON"],
+    epistemic_boundary=["Valid auth token required"],
+)
+session.accept("HYP-001")
+result = session.run()
+print(result.summary())
+# certainty=0.55, failures=2, equilibrium=False
+```
+
+Use cases: linguistics research, compliance pipelines, AI alignment, patent prosecution.
+
+---
+
+## Governance Rules (H1–H13)
+
+13 hard rules enforced by `specsmith validate`:
+
+- **H11** — Every loop or blocking wait must have a timeout, fallback exit, and diagnostic message.
+- **H12** — Windows multi-step automation goes into `.cmd` files, not inline shell invocations.
+- **H13** — Agent tools must declare epistemic contracts (what they claim and what they cannot detect).
+
+---
+
+## Documentation
+
+**[specsmith.readthedocs.io](https://specsmith.readthedocs.io)** — Full manual: AEE primer,
+command reference, project types, tool registry, governance model, Ollama guide, VS Code extension.
+
+## Links
+
+- [PyPI](https://pypi.org/project/specsmith/)
+- [Documentation](https://specsmith.readthedocs.io)
+- [Changelog](CHANGELOG.md)
+- [VS Code Extension](https://github.com/BitConcepts/specsmith-vscode)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+
+## License
+
+MIT — Copyright (c) 2026 BitConcepts, LLC.

specsmith-0.3.6/README.md

@@ -0,0 +1,298 @@
+# 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/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![VS Code Extension](https://img.shields.io/badge/VS%20Code-AEE%20Workbench-4ec9b0?logo=visualstudiocode)](https://github.com/BitConcepts/specsmith-vscode)
+
+**Applied Epistemic Engineering toolkit for AI-assisted development.**
+
+> Intelligence proposes. Constraints decide. The ledger remembers.
+
+specsmith treats belief systems like code: codable, testable, and deployable. It scaffolds
+epistemically-governed projects, stress-tests requirements as BeliefArtifacts, runs
+cryptographically-sealed trace vaults, and orchestrates AI agents under formal AEE governance.
+
+It also co-installs the standalone `epistemic` Python library for direct use in any project:
+
+```python
+from epistemic import AEESession         # works in any Python 3.10+ project
+from epistemic import BeliefArtifact, StressTester, CertaintyEngine
+```
+
+---
+
+## What is Applied Epistemic Engineering?
+
+AEE treats requirements, decisions, and assumptions — the beliefs your project depends on — as
+engineering artifacts subject to the same discipline as code: version control, testing, and refactoring.
+
+**The 4-step core method: Frame → Disassemble → Stress-Test → Reconstruct**
+
+**The 5 foundational axioms:**
+1. **Observability** — every belief must be inspectable
+2. **Falsifiability** — every belief must be challengeable
+3. **Irreducibility** — beliefs decompose to atomic primitives
+4. **Reconstructability** — every failed belief can be rebuilt
+5. **Convergence** — stress-test + recovery always reaches Equilibrium
+
+---
+
+## The AEE Workflow — 7 Phases
+
+specsmith tracks your project through the full AEE development cycle:
+
+```
+🌱 Inception → 🏗 Architecture → 📋 Requirements → ✅ Test Spec
+    → ⚙ Implementation → 🔬 Verification → 🚀 Release
+```
+
+```bash
+specsmith phase          # show current phase + readiness checklist
+specsmith phase next     # advance to the next phase (runs checks first)
+specsmith phase set requirements  # jump to a specific phase
+specsmith phase list     # list all phases
+```
+
+The current phase is persisted in `scaffold.yml` as `aee_phase` and displayed in the VS Code
+Settings Panel. Each phase has a checklist of file/command criteria, recommended commands,
+and a readiness percentage.
+
+---
+
+## Install
+
+**Recommended — via the VS Code extension (creates a project-isolated environment):**
+
+1. Install the [specsmith AEE Workbench](https://github.com/BitConcepts/specsmith-vscode) VS Code extension
+2. Open `Ctrl+Shift+,` (⚙ specsmith Settings)
+3. Click **🔒 Create Environment** — creates `~/.specsmith/venv/` with specsmith + your provider packages
+
+The extension uses this environment for all agent sessions and terminal commands.
+
+**Or via pipx (system-wide):**
+
+```bash
+pipx install specsmith                    # core CLI + epistemic library
+pipx inject specsmith anthropic           # + Claude support
+pipx inject specsmith openai              # + GPT / O-series support
+pipx inject specsmith google-generativeai # + Gemini support
+```
+
+**Or with pip:**
+
+```bash
+pip install specsmith                     # core
+pip install "specsmith[anthropic]"       # + Claude
+pip install "specsmith[openai]"          # + GPT/O-series
+pip install "specsmith[gemini]"          # + Gemini
+```
+
+**Update:**
+
+```bash
+pipx upgrade specsmith
+specsmith self-update
+```
+
+---
+
+## Quick Start
+
+```bash
+# New project (interactive)
+specsmith init
+
+# Adopt an existing project
+specsmith import --project-dir ./my-project
+
+# Check governance health
+specsmith audit --project-dir ./my-project
+
+# Run AEE stress-test on requirements
+specsmith stress-test --project-dir ./my-project
+
+# Full epistemic audit (certainty + logic knots + recovery proposals)
+specsmith epistemic-audit --project-dir ./my-project
+
+# Start the agentic REPL
+specsmith run --project-dir ./my-project
+
+# Check current AEE workflow phase
+specsmith phase --project-dir ./my-project
+```
+
+---
+
+## VS Code Extension
+
+The **specsmith AEE Workbench** VS Code extension is the flagship client:
+
+```
+# VS Code: Ctrl+Shift+P → specsmith: New Agent Session
+# Settings:         Ctrl+Shift+,     (⚙ specsmith Settings — global)
+# Project Settings: Ctrl+Shift+G     (⚙ Project Settings — per-project)
+```
+
+**Key features:**
+- **Dual-panel architecture** — **⚙ specsmith Settings** (global: venv, version, Ollama, system)
+  and **⚙ Project Settings** (per-project: scaffold, tools, files, actions, execution)
+- **Global environment management** — `~/.specsmith/venv/` with Create / Update / Rebuild / Delete;
+  persistent restart banner; Remove System Installs cleanup button
+- **VCS context at session start** — git status + recent commits shown in chat and in system prompt
+- **Execution profiles** — safe / standard / open / admin; custom allow/block command lists
+- **AEE phase indicator** — shows current phase with readiness %, Next Phase button, 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** — model manager (update/remove/update-all), version check, upgrade
+- **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
+- **API key management** — stored in OS credential store (Windows Credential Manager / macOS Keychain)
+- **Update checker** — PyPI version check, auto-checks on panel open, release channel selector
+
+**[→ 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:
+
+```bash
+specsmith ollama gpu                    # detect GPU and VRAM tier
+specsmith ollama available              # show catalog filtered by VRAM budget
+specsmith ollama available --task code  # filter by task type
+specsmith ollama pull qwen2.5:14b      # download a model
+specsmith ollama suggest requirements  # task-based recommendations
+specsmith ollama list                  # show installed models
+```
+
+GPU-aware context sizing in the VS Code extension: 4K/8K/16K/32K tokens based on detected VRAM.
+Override with `specsmith.ollamaContextLength` in VS Code settings.
+
+---
+
+## FPGA / HDL Projects
+
+specsmith supports FPGA-specific project types with full governance:
+
+```yaml
+# scaffold.yml
+type: fpga-rtl-amd          # or fpga-rtl-intel / fpga-rtl-lattice / fpga-rtl
+fpga_tools:
+  - vivado
+  - gtkwave
+  - vsg
+  - ghdl
+  - verilator
+```
+
+Supported tools: **Synthesis:** vivado, quartus, radiant, diamond, gowin.
+**Simulation:** ghdl, iverilog, verilator, modelsim, questasim, xsim.
+**Waveform:** gtkwave, surfer. **Linting:** vsg, verible, svlint.
+**Formal:** symbiyosys. **OSS flow:** yosys, nextpnr, openFPGALoader.
+
+---
+
+## 50+ CLI Commands
+
+**Governance:** `init` `import` `audit` `validate` `diff` `upgrade` `compress` `doctor` `export` `architect`
+
+**AEE Epistemic:** `stress-test` `epistemic-audit` `belief-graph` `trace seal/verify/log` `integrate`
+
+**Workflow:** `phase show/set/next/list` `ledger add/list` `req list/add/gaps/trace`
+
+**Agent:** `run` `agent providers/tools/skills`
+
+**Ollama:** `ollama list/available/gpu/pull/suggest`
+
+**Workspace:** `workspace init/audit/export`
+
+**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`
+
+**Patent:** `patent search/prior-art`
+
+---
+
+## 35 Project Types
+
+**Software:** Python CLI/lib/web, Rust, Go, C/C++, .NET, Node.js/TypeScript, mobile, microservices, data/ML.
+
+**Hardware/Embedded:** FPGA/RTL (Xilinx, Intel, Lattice, generic), Yocto BSP, embedded C/C++.
+
+**Documents:** Technical specs, research papers, API specs, requirements management.
+
+**Business/Legal:** Business plans, patent applications, compliance frameworks.
+
+---
+
+## epistemic Library
+
+The standalone `epistemic` Python library works in any Python 3.10+ project — no specsmith coupling:
+
+```python
+from epistemic import AEESession, BeliefArtifact, StressTester
+
+session = AEESession("my-project", threshold=0.70)
+session.add_belief(
+    artifact_id="HYP-001",
+    propositions=["The API always returns valid JSON"],
+    epistemic_boundary=["Valid auth token required"],
+)
+session.accept("HYP-001")
+result = session.run()
+print(result.summary())
+# certainty=0.55, failures=2, equilibrium=False
+```
+
+Use cases: linguistics research, compliance pipelines, AI alignment, patent prosecution.
+
+---
+
+## Governance Rules (H1–H13)
+
+13 hard rules enforced by `specsmith validate`:
+
+- **H11** — Every loop or blocking wait must have a timeout, fallback exit, and diagnostic message.
+- **H12** — Windows multi-step automation goes into `.cmd` files, not inline shell invocations.
+- **H13** — Agent tools must declare epistemic contracts (what they claim and what they cannot detect).
+
+---
+
+## Documentation
+
+**[specsmith.readthedocs.io](https://specsmith.readthedocs.io)** — Full manual: AEE primer,
+command reference, project types, tool registry, governance model, Ollama guide, VS Code extension.
+
+## Links
+
+- [PyPI](https://pypi.org/project/specsmith/)
+- [Documentation](https://specsmith.readthedocs.io)
+- [Changelog](CHANGELOG.md)
+- [VS Code Extension](https://github.com/BitConcepts/specsmith-vscode)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+
+## License
+
+MIT — Copyright (c) 2026 BitConcepts, LLC.