docs: update README and USAGE to describe uv-first workflow, Makefile, pre-commit and wheelhouse guidance

Author: Magic-Man-us

README.md

@@ -5,11 +5,11 @@ A modern scaffolding tool for creating new Python packages with best practices b
 ## Features
 
 -  **Fast Setup**: Create fully-configured Python packages in seconds
--  **uv Integration**: Modern dependency management with `uv`
+-  **uv Integration**: Modern dependency & venv management using `uv`
 -  **Testing Ready**: Pre-configured `pytest` with coverage
--  **Documentation**: Sphinx docs with `furo` theme
--  **CI/CD**: GitHub Actions workflow included
--  **Best Practices**: PEP 8 compliant, type hints, proper structure
+-  **Documentation**: Sphinx docs included
+-  **CI/CD**: uv-first GitHub Actions workflow (single canonical `ci.yml`)
+-  **Best Practices**: PEP 8 compliant, type hints, pre-commit hooks, type checking
 
 ## Installation
 
@@ -58,10 +58,11 @@ The tool automatically:
 1. ✅ Validates inputs
 2. ✅ Creates project structure
 3. ✅ Initializes git repository
-4. ✅ Sets up `uv` virtual environment
+4. ✅ Sets up `uv` virtual environment (preferred)
 5. ✅ Installs dev dependencies
 6. ✅ Runs initial tests
-7. ✅ Builds documentation
+7. ✅ Installs and runs `pre-commit` hooks
+8. ✅ Builds documentation
 
 ## Example
 
@@ -82,32 +83,55 @@ pytest
 sphinx-build -b html docs docs/_build/html
 ```
 
-## Development
+# Development
+
+Local development is uv-first. Use the provided Makefile for convenience or run uv directly.
+
+Using the Makefile (recommended):
 
 ```bash
-# Clone the repository
-git clone https://github.com/Magic-Man-us/PythonProjectDeployment.git
-cd python-project-deployment
+# Create or refresh a uv venv and install dev deps
+make install
+
+# Run the test suite
+make test
 
-# Install in development mode
+# Run linters and type checks
+make lint
+make type
+
+# Apply formatting (Black/isort)
+make format
+
+# Run pre-commit hooks locally
+make precommit
+```
+
+Direct uv commands:
+
+```bash
+# Create a venv and install dev extras
 uv venv
 uv pip install -e ".[dev]"
 
 # Run tests
-pytest
+uv run pytest
 
-# Format code
-black .
-isort .
+# Run linters
+uv run ruff check .
+uv run mypy python_project_deployment
 
-# Type check
-mypy python_project_deployment
+# Run pre-commit
+uv run pre-commit install
+uv run pre-commit run --all-files
 ```
 
 ## Requirements
 
-- Python 3.10+
-- uv (recommended) or pip
+- Python 3.11+ (recommended)
+- uv (strongly recommended) — the scaffolder / CI are uv-first
+
+If `uv` is not available, the tool will try to fall back to `pip`, but behaviour and reproducibility are better with `uv`.
 
 ## License
 

USAGE.md

@@ -44,6 +44,17 @@ scaffold-python data_analyzer /home/user/projects \
 
 ### Verbose Mode
 
+  ## Installation
+
+  The tool is installed in editable mode and ready to use (uv-first):
+
+  ```bash
+  # Create or refresh a uv venv
+  uv venv
+
+  # Install in editable mode with development extras
+  uv pip install -e ".[dev]"
+  ```
 See detailed progress:
 
 ```bash
@@ -80,29 +91,55 @@ After creating your package:
 
 ```bash
 # Navigate to the project
+  ### Post-Creation Workflow
+
+  After creating your package follow this uv-first workflow:
+
+  ```bash
+  # Navigate to the project
+  cd /path/to/your/my_package
+
+  # Use uv for any command (preferred)
+  uv run python -c "import my_package; print(my_package.hello())"
+
+  # Run tests
+  uv run pytest
+
+  # Run tests with coverage
+  uv run pytest --cov=my_package
+
+  # View coverage report (HTML)
+  open htmlcov/index.html
+
+  # Build documentation (Sphinx)
+  uv run python -m sphinx -b html docs docs/_build/html
+  open docs/_build/html/index.html
+
+  # Format code
+  uv run python -m black .
+  uv run isort .
+
+  # Type checking
+  uv run mypy my_package
+
+  # Linting
+  uv run ruff check my_package
+
+  # Run pre-commit hooks
+  uv run pre-commit install
+  uv run pre-commit run --all-files
+  ```
 cd /path/to/your/my_package
 
 # Activate virtual environment
-source .venv/bin/activate
-
-# Or use uv run for any command
 uv run python -c "import my_package; print(my_package.hello())"
 
-# Run tests
-pytest
-
 # Run tests with coverage
 pytest --cov=my_package
-
-# View coverage report
-open htmlcov/index.html
-
 # Build documentation
 sphinx-build -b html docs docs/_build/html
-open docs/_build/html/index.html
 
-# Format code
-black .
+  Our CI is uv-first and now uses a single canonical workflow: `.github/workflows/ci.yml`. It sets up `uv`, installs Python versions, syncs dependencies, and runs linters, mypy, pre-commit, tests and security scans.
 isort .
 
 # Type check