fix: resolve CI linting and type checking errors

README.md

@@ -1,21 +1,7 @@
 # ScaffoldForge
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://www.python.org/)
-[![Status](https://img.shields.io/badge/status-beta-green)](https://github.com/7000pctAUTO/scaffoldforge)
-
 ScaffoldForge is a CLI tool that parses GitHub issues and automatically generates project scaffolds with starter code, file structures, and TODO comments. Developers can point it at a repo and issue, and it creates a development-ready starting point with placeholders for implementation.
 
-## Features
-
-- Parse GitHub issue descriptions, checklists, and comments
-- Generate project structures from templates
-- Create starter files with TODO comments
-- Support multiple languages (Python, JavaScript, Go, Rust)
-- Custom template system
-- Preview mode before generating
-- Interactive mode with prompts
-
 ## Installation
 
 ```bash
@@ -25,7 +11,7 @@ pip install scaffoldforge
 Or from source:
 
 ```bash
-git clone https://7000pct.gitea.bloupla.net/7000pctAUTO/scaffoldforge.git
+git clone https://github.com/yourusername/scaffoldforge.git
 cd scaffoldforge
 pip install -e .
 ```
@@ -35,12 +21,34 @@ pip install -e .
 1. Set up your GitHub Personal Access Token:
    ```bash
 export GITHUB_TOKEN=your_github_token_here
-   ```
+```
 
 2. Generate a project from a GitHub issue:
    ```bash
 scaffoldforge generate https://github.com/owner/repo/issues/123
-   ```
+```
+
+## Configuration
+
+ScaffoldForge can be configured using environment variables or a configuration file.
+
+### Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `GITHUB_TOKEN` | GitHub Personal Access Token for API access | Yes |
+| `SCAFFOLD_TEMPLATE_DIR` | Default template directory path | No |
+| `SCAFFOLD_OUTPUT_DIR` | Default output directory | No |
+
+### Configuration File
+
+Copy `.env.example` to `.env` and fill in your values:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` to add your GitHub token.
 
 ## Usage
 
@@ -89,12 +97,52 @@ Interactive mode:
 scaffoldforge generate https://github.com/owner/repo/issues/123 --interactive
 ```
 
-List available templates:
+### List Available Templates
 
 ```bash
 scaffoldforge list-templates --language python
 ```
 
+## Custom Templates
+
+You can create custom templates for ScaffoldForge. Place your templates in a directory and set the `SCAFFOLD_TEMPLATE_DIR` environment variable.
+
+### Template Structure
+
+```
+custom_templates/
+├── python/
+│   ├── default/
+│   │   ├── main.py.j2
+│   │   └── utils.py.j2
+│   └── cli/
+│       └── main.py.j2
+└── javascript/
+    └── default/
+        └── index.js.j2
+```
+
+### Template Variables
+
+Templates can use the following variables:
+
+| Variable | Description |
+|----------|-------------|
+| `project_name` | Sanitized project name |
+| `project_name_kebab` | kebab-case project name |
+| `project_name_snake` | snake_case project name |
+| `project_name_pascal` | PascalCase project name |
+| `issue_number` | GitHub issue number |
+| `issue_title` | GitHub issue title |
+| `issue_url` | GitHub issue URL |
+| `repository` | Repository identifier (owner/repo) |
+| `author` | Issue author |
+| `created_date` | Issue creation date |
+| `todo_items` | List of incomplete checklist items |
+| `completed_items` | List of completed checklist items |
+| `requirements` | List of requirements |
+| `acceptance_criteria` | List of acceptance criteria |
+
 ## Supported Languages
 
 - **Python** - Generates `main.py`, `utils.py`, `models.py`, `pyproject.toml`
@@ -102,40 +150,31 @@ scaffoldforge list-templates --language python
 - **Go** - Generates `main.go`, `utils.go`, `go.mod`
 - **Rust** - Generates `main.rs`, `lib.rs`, `Cargo.toml`
 
-## Custom Templates
-
-You can create custom templates for ScaffoldForge. Place your templates in a directory and set the `SCAFFOLD_TEMPLATE_DIR` environment variable.
-
-```bash
-SCAFFOLD_TEMPLATE_DIR=./custom_templates scaffoldforge generate <issue_url>
-```
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Description | Required |
-|----------|-------------|----------|
-| `GITHUB_TOKEN` | GitHub Personal Access Token for API access | Yes |
-| `SCAFFOLD_TEMPLATE_DIR` | Default template directory path | No |
-| `SCAFFOLD_OUTPUT_DIR` | Default output directory | No |
-
-### Configuration File
-
-Copy `.env.example` to `.env` and fill in your values:
-
-```bash
-cp .env.example .env
-```
-
 ## How It Works
 
-1. **Issue Parsing**: Fetches the GitHub issue and parses title, description, checklist items, and labels
-2. **Language Detection**: Automatically detects programming language from labels or content
-3. **Template Selection**: Selects appropriate templates based on language
-4. **Context Generation**: Creates template context with issue data
-5. **File Generation**: Renders templates and writes files
-6. **Documentation**: Generates README.md and .gitignore
+1. **Issue Parsing**: ScaffoldForge fetches the GitHub issue and parses:
+   - Title and description
+   - Checklist items (converted to TODO comments)
+   - Labels (used for language detection)
+   - Requirements sections
+   - Suggested file/directory paths
+
+2. **Template Selection**: Based on the detected or specified language, appropriate templates are selected.
+
+3. **Context Generation**: A template context is created with issue data and project name.
+
+4. **File Generation**: Templates are rendered with the context and files are written to the output directory.
+
+5. **Documentation**: A `README.md` and `.gitignore` are automatically generated.
+
+## Error Handling
+
+ScaffoldForge handles common errors gracefully:
+
+- **GitHub API rate limit**: Suggests using a token
+- **Invalid URL**: Validates and provides clear error messages
+- **Template errors**: Shows syntax errors in templates
+- **Permission errors**: Validates output paths
 
 ## Contributing