docs: refresh portfolio docs

Author: Technical-1

.portfolio/qa.md

@@ -1,136 +1,97 @@
 # Project Q&A
 
-## Project Overview
+## Overview
 
-**quickforge** is a modern Python project bootstrapper that creates production-ready Python projects with a single command. It solves the problem of repetitive project setup by generating complete project structures with 2025's best toolchain already configured: uv for package management, ruff for linting/formatting, basedpyright for type checking, and pytest for testing. The target users are Python developers who want to start new projects quickly without spending hours configuring build tools, CI/CD pipelines, and development environments.
+**quickforge** is a Python CLI that bootstraps a complete, modern Python project with one command. It solves the recurring tax of wiring up a package manager, linter, formatter, type checker, test runner, CI config, and editor settings every time you start something new. The target user is a Python developer who wants a fresh project on uv + ruff + basedpyright + pytest without spending an afternoon assembling boilerplate.
 
-## Key Features
-
-### 1. One-Command Project Creation
-
-Run `quickforge new myproject` and get a complete, working project with:
-- Proper package structure (src layout)
-- All tools configured in pyproject.toml
-- GitHub Actions CI/CD pipeline
-- Pre-commit hooks ready to install
-- VS Code settings optimized for the toolchain
-- Test skeleton with pytest and coverage
-
-### 2. Multiple Project Types
-
-I support five project types tailored to different use cases:
-- **library**: PyPI-publishable packages with src layout
-- **cli**: Command-line tools with Typer integration
-- **api**: FastAPI/Flask web services
-- **app**: Standalone applications
-- **script**: Single-file scripts with PEP 723 inline dependencies
-
-### 3. Interactive and Scriptable
+## Problem Solved
 
-The CLI works in two modes:
-- **Interactive**: Prompts guide you through all options with descriptions
-- **Non-interactive**: Pass flags for CI/CD usage (`--yes` skips all prompts)
+Most Python scaffolding tools either ship outdated defaults (setup.py, black + isort + flake8, mypy) or require so much customization up front that you might as well configure things by hand. quickforge picks one opinionated stack — the one I'd configure manually in 2025 — and emits it correctly in seconds. It also goes the other direction: `audit` and `upgrade` modernize existing projects without trashing user-authored configuration.
 
-### 4. Project Auditing
+## Target Users
 
-The `quickforge audit` command analyzes existing projects and identifies:
-- Legacy tooling (black, flake8, mypy) that could be modernized
-- Missing type annotations and coverage
-- Configuration improvements
-- Security best practices
+- **Python developers starting a new project** — get a working library, CLI, FastAPI service, app, or PEP 723 script with sensible defaults already wired
+- **Maintainers of legacy projects** — migrate from Poetry/pip/setuptools to uv and from black/isort/flake8/mypy to ruff + basedpyright without rewriting pyproject.toml by hand
 
-### 5. Automated Migration
+## Key Features
 
-The `quickforge upgrade` command migrates projects from:
-- Poetry/pip/pipenv/setuptools to uv
-- black/isort/flake8 to ruff
-- mypy to basedpyright
+### One-command project creation
+`quickforge new myproject` produces a `src/` layout package, configured `pyproject.toml`, pytest skeleton, GitHub Actions CI, pre-commit hooks, and VS Code settings. Both interactive prompts and a fully scriptable `--yes` mode are supported.
 
-It preserves comments and formatting in existing configuration files.
+### Five project archetypes
+`library`, `cli` (Typer), `api` (FastAPI), `app`, and `script` (PEP 723 inline dependencies). Each archetype renders only the templates relevant to it, so a CLI project doesn't ship empty FastAPI scaffolding.
 
-### 6. Feature Addition
+### Audit and upgrade
+`quickforge audit` detects the existing toolchain by signature (lock files, pyproject sections, tool-specific configs) and scores the project from 100. `quickforge upgrade` migrates Poetry/pip/pipenv/setuptools to uv and black/isort/flake8/mypy to ruff + basedpyright, while preserving inline comments via `tomlkit`.
 
-Add optional features to existing projects with `quickforge add`:
-- github-actions: CI/CD workflow
-- docker: Dockerfile and docker-compose.yml
-- docs: MkDocs with Material theme
-- pre-commit: Git hooks configuration
-- vscode: IDE settings and extensions
-- devcontainer: Dev container for VS Code
+### Modular feature add-ons
+`quickforge add` injects Docker, GitHub Actions, MkDocs, pre-commit, VS Code settings, or a devcontainer into an existing project. Each feature has its own template set and is independently testable.
 
 ## Technical Highlights
 
-### Challenge: Comment-Preserving TOML Updates
-
-When upgrading projects, I needed to modify pyproject.toml without destroying users' carefully written comments and documentation. I solved this by using `tomlkit` instead of standard TOML libraries. tomlkit parses TOML into a document model that preserves whitespace, comments, and formatting, allowing surgical modifications.
+### Comment-preserving TOML edits during upgrades
+Standard `tomli`/`tomli-w` round-trips destroy comments and reflow whitespace, which is unacceptable when modifying a user's hand-written `pyproject.toml`. The upgrader uses `tomlkit`, which parses TOML into a document model that retains formatting, so migrations land as surgical edits rather than rewrites. See `src/quickforge/upgrader.py`.
 
-### Challenge: Cross-Platform Path Handling
+### Signature-based toolchain detection
+The auditor identifies the active package manager, linter, formatter, and type checker by looking for `poetry.lock`, `Pipfile.lock`, `[tool.black]` sections, `.flake8` files, etc. — not by asking the user. This makes audit and upgrade work on any project without configuration. Detection logic lives in `src/quickforge/auditor.py`.
 
-Template paths needed to work across macOS, Linux, and Windows. I used `pathlib.Path` throughout and carefully handled path separators in templates. The src layout path is dynamically computed based on project type.
+### Atomic generation with cleanup on failure
+Project creation is a linear pipeline (`validate -> create dirs -> render templates -> write files -> git init -> validate output`). Each stage tracks what it created; on failure, the generator unwinds and removes partial directories rather than leaving a half-formed project on disk. See `src/quickforge/generator.py`.
 
-### Challenge: Atomic Project Generation
+### Conditional template rendering
+Templates are tagged by archetype and feature flags. `cli.py.j2` is rendered only for `--type cli`; the FastAPI router only for `--type api`; Docker, MkDocs, devcontainer files only when their flags are set. The generated tree contains only files the user actually asked for.
 
-If generation fails midway, users shouldn't be left with a broken partial project. I implemented cleanup logic that removes partially created directories on failure, and validation that verifies the generated project is syntactically correct before reporting success.
+## Engineering Decisions
 
-### Innovation: Detection-Based Auditing
+### tomlkit vs tomli for upgrades
+- **Constraint**: Upgrading a project must not destroy comments or formatting in `pyproject.toml`
+- **Options**: `tomli` + `tomli-w` (lossy round-trip), regex-based edits (fragile), `tomlkit` (round-trip preserving)
+- **Choice**: `tomlkit` for the upgrader's write path; `tomli` for read-only parsing where round-tripping isn't needed
+- **Why**: `tomlkit` keeps the user's documentation intact, which is the whole point of in-place migration
 
-Rather than requiring users to declare their tooling, the auditor automatically detects what tools are in use by checking for lock files, configuration sections, and tool-specific files. This zero-configuration approach means it works on any Python project.
+### Typer vs Click vs argparse
+- **Constraint**: Need a CLI with subcommands, rich help, and good DX, without writing parser boilerplate
+- **Options**: argparse (verbose), Click (mature but decorator-heavy), Typer (Click underneath, infers from type hints)
+- **Choice**: Typer
+- **Why**: Function signatures double as the CLI definition, Rich integration is built in, and Click's ecosystem is still available underneath when needed
 
-### Innovation: Template Condition System
+### Detection-based audit vs explicit declaration
+- **Constraint**: Need to audit arbitrary user projects, not just ones generated by this tool
+- **Options**: Require a `quickforge.toml` config file, infer from `pyproject.toml` alone, fingerprint by files on disk
+- **Choice**: File fingerprinting plus `pyproject.toml` parsing
+- **Why**: Zero-configuration UX; works on projects that have never heard of quickforge, including legacy setup.py / Pipfile / Poetry repos
 
-Templates are conditionally rendered based on project configuration. For example, `cli.py.j2` is only rendered for CLI projects, while `main.py.j2` is rendered for app and API projects. This keeps the generated code minimal and relevant.
+### src/ layout for the generated default
+- **Constraint**: New projects should resist a known Python footgun (importing the in-tree package instead of the installed one during testing)
+- **Options**: Flat layout (simpler), src/ layout (industry standard, immune to in-tree shadowing)
+- **Choice**: src/ layout
+- **Why**: PyPA recommends it, tests run against the installed package, and IDE refactoring is more reliable
 
 ## Frequently Asked Questions
 
-### Q1: Why create another project scaffolding tool?
-
-I found that existing tools either generate outdated structures (using setup.py, black, mypy) or require significant configuration. I wanted a tool that embodies 2025 best practices out of the box, with zero configuration needed for the common case. quickforge generates exactly what I would set up manually for a new project.
-
-### Q2: Why uv instead of Poetry or pip?
-
-uv is 10-100x faster than pip and Poetry because it's written in Rust. It handles dependency resolution, virtual environments, and Python version management in one tool. The speed difference is noticeable on every operation, making development more pleasant.
-
-### Q3: Why ruff instead of black and flake8?
-
-ruff combines linting (flake8, pylint) and formatting (black, isort) into one tool that's 10-100x faster. Having one configuration section instead of three separate tools simplifies maintenance. ruff also has more rules and better autofix capabilities.
-
-### Q4: Why basedpyright instead of mypy?
-
-basedpyright is faster (3-5x), has better error messages, and integrates seamlessly with VS Code. It's stricter by default, which catches more bugs. The "based" fork adds additional checks beyond standard pyright.
-
-### Q5: Can I customize the generated templates?
-
-Currently, templates are bundled with the package and not user-customizable. This is intentional to ensure consistency and correctness. If you need significant customization, you can use quickforge as a starting point and modify the generated files, or fork the project.
-
-### Q6: Does quickforge support monorepos?
-
-Not currently. Each invocation creates a single project. For monorepos, I'd recommend using uv workspaces directly. This might be added in a future version.
-
-### Q7: How does the audit scoring work?
-
-The audit starts at 100 points and deducts based on findings:
-- Critical issues: -20 points
-- Errors: -10 points
-- Warnings: -5 points
-- Info: -1 point
+### Why another Python scaffolder?
+Most existing tools encode a 2018-era stack (setup.py, black, isort, flake8, mypy, pip) and treat modern tools as add-ons. quickforge inverts that: uv, ruff, basedpyright, and pytest are the defaults; legacy tools are not options. The generated project is what I'd produce manually if I had unlimited time on day one.
 
-A score above 80 is considered healthy, 60-80 needs attention, and below 60 indicates significant technical debt.
+### Why uv instead of Poetry or pip?
+uv is written in Rust and resolves dependencies an order of magnitude faster, manages Python versions itself, and produces a portable `uv.lock`. It also accepts the same `pyproject.toml` standards that Poetry helped establish, so the migration cost is small.
 
-### Q8: What happens if the upgrade fails?
+### Why ruff instead of black + isort + flake8?
+One tool replaces three, with a single config block in `pyproject.toml` and substantially faster runs. The autofix surface is wider, and rule coverage is broader than the combined set it replaces.
 
-Before making any changes, `quickforge upgrade` creates a timestamped backup of all configuration files in `.quickforge_backup_TIMESTAMP/`. If something goes wrong, you can restore from this backup. The upgrade also supports `--dry-run` to preview changes without applying them.
+### Why basedpyright instead of mypy?
+basedpyright (a fork of pyright) is significantly faster, stricter by default, and produces clearer error messages with better editor integration. For new projects starting fresh, the stricter defaults catch bugs the day they're written.
 
-### Q9: Why is the coverage requirement set at 80%?
+### Can I customize the generated templates?
+Not at the moment — templates are bundled with the package. The intent is that the generated output is opinionated. If you need a different stack, fork the project or modify the generated files after creation.
 
-I believe 80% is a pragmatic target that encourages good testing habits without becoming burdensome. It allows for untested edge cases and configuration code while ensuring core functionality is covered. The threshold is configurable in the generated pyproject.toml.
+### Does it support monorepos?
+No. Each `quickforge new` invocation produces a single project. For monorepos, use uv workspaces directly on top of the generated projects.
 
-### Q10: How do I contribute to quickforge?
+### How does the audit score work?
+The auditor starts at 100 and deducts per finding by severity (critical -20, error -10, warning -5, info -1). 80+ is healthy, 60–80 needs attention, under 60 indicates real technical debt. The threshold is configurable.
 
-The project is open source on GitHub. To contribute:
-1. Clone the repository
-2. Run `uv sync --extra dev` to install dependencies
-3. Run `uv run pre-commit install` to set up hooks
-4. Make changes and ensure `uv run pytest` passes
-5. Submit a pull request
+### What happens if an upgrade fails partway?
+`quickforge upgrade` writes a timestamped backup to `.quickforge_backup_<timestamp>/` before changing anything. `--dry-run` prints the planned changes without writing. If the migration aborts mid-way, the backup is the recovery path.
 
-I welcome contributions for new project types, additional features, and bug fixes.
+### Why 80% as the default coverage gate?
+80% is the inflection point where coverage starts catching real regressions without becoming theater. It leaves room for untested edge cases and config glue while requiring meaningful tests for core paths. The number lives in the generated `pyproject.toml` and is easy to change.

README.md

@@ -8,7 +8,7 @@
 
 **Modern Python project bootstrapper with 2025's best toolchain.**
 
-🚀 **Zero Config** • ⚡ **Blazing Fast** • 🔧 **Modern Tools** • 🎯 **Production Ready**
+Zero Config • Modern Tools • One Command
 
 [Installation](#-installation) • [Quick Start](#-quick-start) • [Project Types](#-project-types) • [Commands](#-commands)
 
@@ -18,7 +18,7 @@
 
 ## ✨ What quickforge Does
 
-One command creates a complete, production-ready Python project with modern tooling:
+One command creates a complete Python project with modern tooling:
 
 ```bash
 quickforge new myproject