quickscale-cli 0.61.0__tar.gz → 0.62.0__tar.gz

quickscale_cli-0.62.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.1
+Name: quickscale-cli
+Version: 0.62.0
+Summary: Command-line interface for QuickScale Django project generator
+Home-page: https://github.com/Experto-AI/quickscale
+License: Apache-2.0
+Keywords: django,cli,project-generator,saas
+Author: Experto AI
+Author-email: victor@experto.ai
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.0
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: click (>=8.1.0,<9.0.0)
+Requires-Dist: quickscale-core (>=0.62.0,<0.63.0)
+Project-URL: Documentation, https://github.com/Experto-AI/quickscale/tree/main/docs
+Project-URL: Repository, https://github.com/Experto-AI/quickscale

{quickscale_cli-0.61.0 → quickscale_cli-0.62.0}/pyproject.toml

@@ -1,10 +1,9 @@
 [tool.poetry]
 name = "quickscale-cli"
-version = "0.61.0"
+version = "0.62.0"
 description = "Command-line interface for QuickScale Django project generator"
 authors = ["Experto AI <victor@experto.ai>"]
 license = "Apache-2.0"
-readme = "README.md"
 keywords = ["django", "cli", "project-generator", "saas"]
 homepage = "https://github.com/Experto-AI/quickscale"
 repository = "https://github.com/Experto-AI/quickscale"
@@ -26,7 +25,7 @@ packages = [{include = "quickscale_cli", from = "src"}]
 [tool.poetry.dependencies]
 python = "^3.10"
 click = "^8.1.0"
-quickscale-core = "^0.61.0"
+quickscale-core = "^0.62.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^7.4.0"
@@ -106,4 +105,8 @@ module = "tests.*"
 disallow_untyped_defs = false
 check_untyped_defs = false
 
+[[tool.mypy.overrides]]
+module = "quickscale_core.*"
+ignore_missing_imports = true
+
 

{quickscale_cli-0.61.0 → quickscale_cli-0.62.0}/src/quickscale_cli/_version.py

@@ -1,2 +1,2 @@
 # Auto-generated by scripts/version_tool.sh
-__version__ = "0.61.0"
+__version__ = "0.62.0"

quickscale_cli-0.62.0/src/quickscale_cli/commands/module_commands.py

@@ -0,0 +1,307 @@
+"""Module management commands for QuickScale CLI."""
+
+from pathlib import Path
+
+import click
+
+from quickscale_core.config import add_module, load_config, update_module_version
+from quickscale_core.utils.git_utils import (
+    GitError,
+    check_remote_branch_exists,
+    is_git_repo,
+    is_working_directory_clean,
+    run_git_subtree_add,
+    run_git_subtree_pull,
+    run_git_subtree_push,
+)
+
+# Available modules (placeholders in v0.62.0)
+AVAILABLE_MODULES = ["auth", "billing", "teams"]
+
+
+@click.command()
+@click.option(
+    "--module",
+    required=True,
+    type=click.Choice(AVAILABLE_MODULES, case_sensitive=False),
+    help="Module name to embed",
+)
+@click.option(
+    "--remote",
+    default="https://github.com/Experto-AI/quickscale.git",
+    help="Git remote URL (default: QuickScale repository)",
+)
+def embed(module: str, remote: str) -> None:
+    r"""
+    Embed a QuickScale module into your project via git subtree.
+
+    \b
+    Examples:
+      quickscale embed --module auth
+      quickscale embed --module billing
+
+    \b
+    Available modules (v0.62.0 placeholders):
+      - auth: Authentication with django-allauth (placeholder)
+      - billing: Stripe integration with dj-stripe (placeholder)
+      - teams: Multi-tenancy and team management (placeholder)
+
+    \b
+    Note: In v0.62.0, modules contain only placeholder READMEs explaining
+    they're not yet implemented. Full implementations coming in v0.63.0+.
+    """
+    try:
+        # Validate git repository
+        if not is_git_repo():
+            click.secho("❌ Error: Not a git repository", fg="red", err=True)
+            click.echo("\n💡 Tip: Run 'git init' to initialize a git repository", err=True)
+            raise click.Abort()
+
+        # Check working directory is clean
+        if not is_working_directory_clean():
+            click.secho("❌ Error: Working directory has uncommitted changes", fg="red", err=True)
+            click.echo("\n💡 Tip: Commit or stash your changes before embedding modules", err=True)
+            raise click.Abort()
+
+        # Check if module already exists
+        module_path = Path.cwd() / "modules" / module
+        if module_path.exists():
+            click.secho(
+                f"❌ Error: Module '{module}' already exists at {module_path}", fg="red", err=True
+            )
+            click.echo("\n💡 Tip: Remove the existing module directory first", err=True)
+            raise click.Abort()
+
+        # Check if branch exists on remote
+        branch = f"splits/{module}-module"
+        click.echo(f"🔍 Checking if {branch} exists on remote...")
+
+        if not check_remote_branch_exists(remote, branch):
+            click.secho(
+                f"❌ Error: Module '{module}' is not yet implemented",
+                fg="red",
+                err=True,
+            )
+            click.echo(
+                f"\n💡 The '{module}' module infrastructure is ready but contains "
+                "only placeholder files.",
+                err=True,
+            )
+            click.echo("   Full implementation coming in v0.63.0+", err=True)
+            click.echo(f"\n📖 Branch '{branch}' does not exist on remote: {remote}", err=True)
+            raise click.Abort()
+
+        # Embed module via git subtree
+        prefix = f"modules/{module}"
+        click.echo(f"\n📦 Embedding {module} module from {branch}...")
+
+        run_git_subtree_add(prefix=prefix, remote=remote, branch=branch, squash=True)
+
+        # Update configuration
+        add_module(
+            module_name=module,
+            prefix=prefix,
+            branch=branch,
+            version="v0.62.0",  # Placeholder version
+        )
+
+        # Success message
+        click.secho(f"\n✅ Module '{module}' embedded successfully!", fg="green", bold=True)
+        click.echo(f"   Location: {module_path}")
+        click.echo(f"   Branch: {branch}")
+
+        # Next steps
+        click.echo("\n📋 Next steps:")
+        click.echo(f"  1. Review the module code in modules/{module}/")
+        click.echo(f"  2. Add to INSTALLED_APPS in settings: 'modules.{module}'")
+        click.echo("  3. Run migrations: python manage.py migrate")
+        click.echo("\n💡 Note: This is a v0.62.0 placeholder. Full implementation coming soon!")
+
+    except GitError as e:
+        click.secho(f"❌ Git error: {e}", fg="red", err=True)
+        raise click.Abort()
+    except Exception as e:
+        click.secho(f"❌ Unexpected error: {e}", fg="red", err=True)
+        raise click.Abort()
+
+
+@click.command()
+@click.option(
+    "--no-preview",
+    is_flag=True,
+    help="Skip diff preview before updating",
+)
+def update(no_preview: bool) -> None:
+    r"""
+    Update all installed QuickScale modules to their latest versions.
+
+    \b
+    Examples:
+      quickscale update           # Update with diff preview
+      quickscale update --no-preview  # Update without preview
+
+    \b
+    This command:
+      - Reads installed modules from .quickscale/config.yml
+      - Updates ONLY modules you've explicitly installed
+      - Shows a diff preview before updating (unless --no-preview)
+      - Updates the installed version in config after successful update
+    """
+    try:
+        # Validate git repository
+        if not is_git_repo():
+            click.secho("❌ Error: Not a git repository", fg="red", err=True)
+            click.echo("\n💡 Tip: This command must be run from a git repository", err=True)
+            raise click.Abort()
+
+        # Check working directory is clean
+        if not is_working_directory_clean():
+            click.secho("❌ Error: Working directory has uncommitted changes", fg="red", err=True)
+            click.echo("\n💡 Tip: Commit or stash your changes before updating modules", err=True)
+            raise click.Abort()
+
+        # Load configuration
+        config = load_config()
+
+        if not config.modules:
+            click.secho("✅ No modules installed. Nothing to update.", fg="green")
+            click.echo("\n💡 Tip: Install modules with 'quickscale embed --module <name>'")
+            return
+
+        # Show installed modules
+        click.echo(f"📦 Found {len(config.modules)} installed module(s):")
+        for name, info in config.modules.items():
+            click.echo(f"  - {name} ({info.installed_version})")
+
+        if not no_preview:
+            click.echo("\n🔍 Preview mode: Changes will be shown before updating")
+
+        # Confirm update
+        if not click.confirm("\n❓ Continue with update?"):
+            click.echo("❌ Update cancelled")
+            return
+
+        # Update each module
+        for name, info in config.modules.items():
+            click.echo(f"\n📥 Updating {name} module...")
+
+            try:
+                output = run_git_subtree_pull(
+                    prefix=info.prefix,
+                    remote=config.default_remote,
+                    branch=info.branch,
+                    squash=True,
+                )
+
+                # Update version in config
+                update_module_version(name, "v0.62.0")  # Placeholder version
+
+                click.secho(f"✅ Updated {name} successfully", fg="green")
+
+                if output and not no_preview:
+                    click.echo("\n📋 Changes summary:")
+                    click.echo(output[:500])  # Show first 500 chars
+
+            except GitError as e:
+                click.secho(f"❌ Failed to update {name}: {e}", fg="red", err=True)
+                click.echo(f"💡 Tip: Check for conflicts in modules/{name}/", err=True)
+                continue
+
+        click.secho("\n🎉 Module update complete!", fg="green", bold=True)
+
+    except GitError as e:
+        click.secho(f"❌ Git error: {e}", fg="red", err=True)
+        raise click.Abort()
+    except Exception as e:
+        click.secho(f"❌ Unexpected error: {e}", fg="red", err=True)
+        raise click.Abort()
+
+
+@click.command()
+@click.option(
+    "--module",
+    required=True,
+    type=click.Choice(AVAILABLE_MODULES, case_sensitive=False),
+    help="Module name to push changes for",
+)
+@click.option(
+    "--branch",
+    help="Feature branch name (default: feature/<module>-improvements)",
+)
+@click.option(
+    "--remote",
+    default="https://github.com/Experto-AI/quickscale.git",
+    help="Git remote URL (default: QuickScale repository)",
+)
+def push(module: str, branch: str, remote: str) -> None:
+    r"""
+    Push your local module changes to a feature branch for contribution.
+
+    \b
+    Examples:
+      quickscale push --module auth
+      quickscale push --module auth --branch feature/fix-email-validation
+
+    \b
+    Workflow:
+      1. This command pushes your changes to a feature branch
+      2. You'll need to create a pull request manually on GitHub
+      3. Maintainers review and merge to main branch
+      4. Auto-split updates the module's split branch
+
+    \b
+    Note: You must have write access to the repository to push.
+    For external contributions, fork the repository first.
+    """
+    try:
+        # Validate git repository
+        if not is_git_repo():
+            click.secho("❌ Error: Not a git repository", fg="red", err=True)
+            raise click.Abort()
+
+        # Check if module is installed
+        config = load_config()
+        if module not in config.modules:
+            click.secho(f"❌ Error: Module '{module}' is not installed", fg="red", err=True)
+            click.echo(
+                f"\n💡 Tip: Install the module first with 'quickscale embed --module {module}'",
+                err=True,
+            )
+            raise click.Abort()
+
+        module_info = config.modules[module]
+
+        # Default branch name
+        if not branch:
+            branch = f"feature/{module}-improvements"
+
+        # Show what will be pushed
+        click.echo(f"📤 Preparing to push changes for module: {module}")
+        click.echo(f"   Local prefix: {module_info.prefix}")
+        click.echo(f"   Target branch: {branch}")
+        click.echo(f"   Remote: {remote}")
+
+        # Confirm push
+        if not click.confirm("\n❓ Continue with push?"):
+            click.echo("❌ Push cancelled")
+            return
+
+        # Push subtree
+        click.echo(f"\n🚀 Pushing to {branch}...")
+        run_git_subtree_push(prefix=module_info.prefix, remote=remote, branch=branch)
+
+        # Success message
+        click.secho("\n✅ Changes pushed successfully!", fg="green", bold=True)
+        click.echo("\n📋 Next steps:")
+        click.echo("  1. Create a pull request on GitHub:")
+        click.echo(f"     https://github.com/Experto-AI/quickscale/pull/new/{branch}")
+        click.echo("  2. Describe your changes and submit for review")
+        click.echo("  3. After merge, the split branch will auto-update")
+
+    except GitError as e:
+        click.secho(f"❌ Git error: {e}", fg="red", err=True)
+        click.echo("\n💡 Tip: Make sure you have write access to the repository", err=True)
+        raise click.Abort()
+    except Exception as e:
+        click.secho(f"❌ Unexpected error: {e}", fg="red", err=True)
+        raise click.Abort()

{quickscale_cli-0.61.0 → quickscale_cli-0.62.0}/src/quickscale_cli/main.py

@@ -8,13 +8,14 @@ import quickscale_cli
 import quickscale_core
 from quickscale_cli.commands.deployment_commands import deploy
 from quickscale_cli.commands.development_commands import down, logs, manage, ps, shell, up
+from quickscale_cli.commands.module_commands import embed, push, update
 from quickscale_core.generator import ProjectGenerator
 
 
 class InitCommand(click.Command):
     """Custom init command with enhanced error messages."""
 
-    def parse_args(self, ctx, args):
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
         """Override parse_args to provide better error messages."""
         try:
             return super().parse_args(ctx, args)
@@ -54,6 +55,11 @@ cli.add_command(ps)
 # Register deployment commands
 cli.add_command(deploy)
 
+# Register module management commands
+cli.add_command(embed)
+cli.add_command(update)
+cli.add_command(push)
+
 
 @cli.command(cls=InitCommand)
 @click.argument("project_name", required=True, metavar="PROJECT_NAME")
@@ -64,7 +70,7 @@ cli.add_command(deploy)
     help="Theme to use for the project (default: starter_html)",
 )
 def init(project_name: str, theme: str) -> None:
-    """
+    r"""
     Generate a new Django project with production-ready configurations.
 
     \b

quickscale_cli-0.61.0/PKG-INFO

@@ -1,206 +0,0 @@
-Metadata-Version: 2.1
-Name: quickscale-cli
-Version: 0.61.0
-Summary: Command-line interface for QuickScale Django project generator
-Home-page: https://github.com/Experto-AI/quickscale
-License: Apache-2.0
-Keywords: django,cli,project-generator,saas
-Author: Experto AI
-Author-email: victor@experto.ai
-Requires-Python: >=3.10,<4.0
-Classifier: Development Status :: 3 - Alpha
-Classifier: Framework :: Django
-Classifier: Framework :: Django :: 4.2
-Classifier: Framework :: Django :: 5.0
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: click (>=8.1.0,<9.0.0)
-Requires-Dist: quickscale-core (>=0.61.0,<0.62.0)
-Project-URL: Documentation, https://github.com/Experto-AI/quickscale/tree/main/docs
-Project-URL: Repository, https://github.com/Experto-AI/quickscale
-Description-Content-Type: text/markdown
-
-# 🚀 QuickScale
-
-<!-- 
-README.md - User-Focused Introduction
-
-PURPOSE: This file serves as the first contact point for users, developers, and evaluators visiting the QuickScale project.
-
-CONTENT GUIDELINES:
-- Keep content user-facing and accessible to newcomers
-- Focus on "what" and "how to get started" rather than "why" or technical details  
-- Include quick examples and development workflows
-- Avoid deep architectural explanations (those belong in DECISIONS.md)
-- Avoid competitive analysis or strategic context (those belong in QUICKSCALE.md)
-- Maximum length: ~200 lines to ensure quick readability
-- Link to other documents for detailed information
-
-TARGET AUDIENCE: New users, potential adopters, GitHub visitors, developers evaluating QuickScale
--->
-
----
-
-## QuickScale: Compose your Django SaaS.
-
-QuickScale is a **composable Django framework** for building client SaaS applications. Start with a stable core, add reusable modules, customize themes, and deploy faster—while maintaining the flexibility to create commercial extensions and build a community ecosystem.
-
----
-
-## What is QuickScale?
-
-QuickScale is a **Django project generator** that creates production-ready SaaS applications with one command. Designed for **solo developers and development agencies**, it gives you:
-
-- **Production-ready foundations**: Docker, PostgreSQL, testing, CI/CD, and security out-of-the-box
-- **One-command deployment**: Deploy to Railway with `quickscale deploy railway`
-- **Full ownership**: Generated projects are 100% yours to customize—no vendor lock-in
-- **Standardized stack**: Build multiple client projects faster with consistent best practices
-
-🧭 **Future Vision**: QuickScale will evolve to support reusable modules and themes. Today it's a personal toolkit; tomorrow it becomes a community platform when demand emerges. [Read the full evolution strategy](./docs/overview/quickscale.md#evolution-strategy-personal-toolkit-first).
-
-## Documentation Guide
-
-**Start here for your needs:**
-- 📖 **New user?** You're in the right place. This README shows you what QuickScale is and how to get started.
-- 🔧 **Need commands?** See [user_manual.md](./docs/technical/user_manual.md) for all commands and workflows
-- 🚀 **Deploying to Railway?** See [railway.md](./docs/deployment/railway.md) for Railway deployment guide
-- 📋 **Planning a feature?** Check [decisions.md](./docs/technical/decisions.md) for the authoritative MVP scope and technical rules
-- 🗓️ **Timeline & tasks?** See [roadmap.md](./docs/technical/roadmap.md)
-- 🏗️ **Project structure?** See [scaffolding.md](./docs/technical/scaffolding.md) for complete directory layouts
-- 🎯 **Why QuickScale?** See [quickscale.md](./docs/overview/quickscale.md) for competitive positioning
-
-**Quick Reference:**
-- **MVP** = Phase 1 (Personal Toolkit)
-- **Post-MVP** = Phase 2+ (Modules & Themes)
-- **Generated Project** = Output of `quickscale init`
-
-See [decisions.md - Glossary section](./docs/technical/decisions.md#document-responsibilities-short) for complete terminology and Single Source of Truth reference
-
-
-### Primary Use Cases (MVP):
-- **Solo Developer**: Build client projects faster with production-ready foundations
-- **Development Agency**: Standardize your tech stack across client engagements
-
-### Future Use Cases (Post-MVP):
-- **Commercial Extension Developer**: Create and sell premium modules/themes
-- **Open Source Contributor**: Extend the ecosystem with modules and themes
-
-### Development Flow (MVP)
-1. `quickscale init myapp`
-  - Generates the minimal Django starter described in the MVP Feature Matrix
-  - Ships with standalone `settings.py` by default; there is NO automatic settings inheritance. Advanced users who manually embed `quickscale_core` via git subtree may opt-in to inherit from `quickscale_core.settings` (see [decisions.md](./docs/technical/decisions.md#mvp-feature-matrix-authoritative)).
-  - **Optional**: Embed `quickscale_core` via git subtree after generation; follow the [Personal Toolkit workflow](./docs/technical/decisions.md#integration-note-personal-toolkit-git-subtree) for canonical commands and helper roadmap
-2. Add your custom Django apps and features
-3. Adopt optional inheritance or module extraction patterns only when you embed the core; the rules and best practices stay centralized in `DECISIONS.md`
-4. Build your unique client application
-5. Deploy to Railway with `quickscale deploy railway` (or use standard Django deployment)
-
-ℹ️ QuickScale's MVP centers on the personal toolkit workflow. Extraction patterns, module packaging, and subtree helper command plans stay documented in `docs/technical/decisions.md` so this README can stay concise.
-
-🔎 **Scope note**: The [MVP Feature Matrix](./docs/technical/decisions.md#mvp-feature-matrix-authoritative) is the single source of truth for what's in or out.
-
-### What You Get
-
-Running `quickscale init myapp` generates a **production-ready Django project** with:
-
-- ✅ **Docker** setup (development + production)
-- ✅ **PostgreSQL** configuration
-- ✅ **Environment-based** settings (dev/prod split)
-- ✅ **Security** best practices (SECRET_KEY, ALLOWED_HOSTS, etc.)
-- ✅ **Testing** infrastructure (pytest + factory_boy)
-- ✅ **CI/CD** pipeline (GitHub Actions)
-- ✅ **Code quality** hooks (ruff format + ruff check)
-- ✅ **Poetry** for dependency management
-- ✅ **One-Command Deployment**: Deploy to Railway with `quickscale deploy railway` - fully automated setup
-
-**See the complete project structure:** [scaffolding.md - Generated Project Output](./docs/technical/scaffolding.md#5-generated-project-output)
-
-The generated project is **yours to own and modify** - no vendor lock-in, just Django best practices.
-
-## Why QuickScale vs. Alternatives?
-
-✅ **Faster than Cookiecutter** - One command vs. 30+ interactive prompts
-✅ **More flexible than SaaS Pegasus** - Open source with full code ownership ($0 vs. $349+)
-✅ **Simpler than building from scratch** - Production-ready in 5 minutes vs. days of setup
-✅ **Railway deployment automation** - Competitors require manual platform configuration
-
-**QuickScale is a development accelerator**, not a complete solution. You start with production-ready foundations and build your unique client application on top.
-
-See [competitive_analysis.md](./docs/overview/competitive_analysis.md) for detailed comparison with SaaS Pegasus and Cookiecutter.
-
----
-
-
-## Quick Start
-
-```bash
-# Install QuickScale globally
-./scripts/install_global.sh
-
-# Create your first project
-quickscale init myapp
-cd myapp
-
-# Or choose a specific theme (v0.61.0+)
-# quickscale init myapp --theme starter_html  # Default HTML theme
-# quickscale init myapp --theme starter_htmx  # HTMX theme (coming in v0.67.0)
-# quickscale init myapp --theme starter_react # React theme (coming in v0.68.0)
-```
-
-**Choose your development workflow:**
-
-### Option 1: Docker (Recommended for production parity)
-
-```bash
-# Start all services (web + database)
-quickscale up
-
-# Run migrations
-quickscale manage migrate
-
-# Create superuser
-quickscale manage createsuperuser
-
-# View logs
-quickscale logs -f web
-
-# Open a shell in the container
-quickscale shell
-
-# Stop services
-quickscale down
-```
-
-**Visit http://localhost:8000** - Your app is running in Docker with PostgreSQL!
-
-### Option 2: Native Poetry (Simpler for quick testing)
-
-```bash
-# Install dependencies
-poetry install
-
-# Run migrations
-poetry run python manage.py migrate
-
-# Start development server
-poetry run python manage.py runserver
-```
-
-**Visit http://localhost:8000** - Your app is running natively!
-
-**For complete command reference and workflows**, see the [user_manual.md](./docs/technical/user_manual.md).
-
-## Learn More
-
-- **[decisions.md](./docs/technical/decisions.md)** - Technical specifications and implementation rules
-- **[quickscale.md](./docs/overview/quickscale.md)** - Strategic vision and competitive positioning
-- **[competitive_analysis.md](./docs/overview/competitive_analysis.md)** - Comparison vs SaaS Pegasus and alternatives
-- **[roadmap.md](./docs/technical/roadmap.md)** - Development roadmap and implementation plan
-- **[user_manual.md](./docs/technical/user_manual.md)** - Commands and workflows
-- **[contributing.md](./docs/contrib/contributing.md)** - Development workflow and coding standards
-
-

quickscale_cli-0.61.0/README.md

@@ -1,179 +0,0 @@
-# 🚀 QuickScale
-
-<!-- 
-README.md - User-Focused Introduction
-
-PURPOSE: This file serves as the first contact point for users, developers, and evaluators visiting the QuickScale project.
-
-CONTENT GUIDELINES:
-- Keep content user-facing and accessible to newcomers
-- Focus on "what" and "how to get started" rather than "why" or technical details  
-- Include quick examples and development workflows
-- Avoid deep architectural explanations (those belong in DECISIONS.md)
-- Avoid competitive analysis or strategic context (those belong in QUICKSCALE.md)
-- Maximum length: ~200 lines to ensure quick readability
-- Link to other documents for detailed information
-
-TARGET AUDIENCE: New users, potential adopters, GitHub visitors, developers evaluating QuickScale
--->
-
----
-
-## QuickScale: Compose your Django SaaS.
-
-QuickScale is a **composable Django framework** for building client SaaS applications. Start with a stable core, add reusable modules, customize themes, and deploy faster—while maintaining the flexibility to create commercial extensions and build a community ecosystem.
-
----
-
-## What is QuickScale?
-
-QuickScale is a **Django project generator** that creates production-ready SaaS applications with one command. Designed for **solo developers and development agencies**, it gives you:
-
-- **Production-ready foundations**: Docker, PostgreSQL, testing, CI/CD, and security out-of-the-box
-- **One-command deployment**: Deploy to Railway with `quickscale deploy railway`
-- **Full ownership**: Generated projects are 100% yours to customize—no vendor lock-in
-- **Standardized stack**: Build multiple client projects faster with consistent best practices
-
-🧭 **Future Vision**: QuickScale will evolve to support reusable modules and themes. Today it's a personal toolkit; tomorrow it becomes a community platform when demand emerges. [Read the full evolution strategy](./docs/overview/quickscale.md#evolution-strategy-personal-toolkit-first).
-
-## Documentation Guide
-
-**Start here for your needs:**
-- 📖 **New user?** You're in the right place. This README shows you what QuickScale is and how to get started.
-- 🔧 **Need commands?** See [user_manual.md](./docs/technical/user_manual.md) for all commands and workflows
-- 🚀 **Deploying to Railway?** See [railway.md](./docs/deployment/railway.md) for Railway deployment guide
-- 📋 **Planning a feature?** Check [decisions.md](./docs/technical/decisions.md) for the authoritative MVP scope and technical rules
-- 🗓️ **Timeline & tasks?** See [roadmap.md](./docs/technical/roadmap.md)
-- 🏗️ **Project structure?** See [scaffolding.md](./docs/technical/scaffolding.md) for complete directory layouts
-- 🎯 **Why QuickScale?** See [quickscale.md](./docs/overview/quickscale.md) for competitive positioning
-
-**Quick Reference:**
-- **MVP** = Phase 1 (Personal Toolkit)
-- **Post-MVP** = Phase 2+ (Modules & Themes)
-- **Generated Project** = Output of `quickscale init`
-
-See [decisions.md - Glossary section](./docs/technical/decisions.md#document-responsibilities-short) for complete terminology and Single Source of Truth reference
-
-
-### Primary Use Cases (MVP):
-- **Solo Developer**: Build client projects faster with production-ready foundations
-- **Development Agency**: Standardize your tech stack across client engagements
-
-### Future Use Cases (Post-MVP):
-- **Commercial Extension Developer**: Create and sell premium modules/themes
-- **Open Source Contributor**: Extend the ecosystem with modules and themes
-
-### Development Flow (MVP)
-1. `quickscale init myapp`
-  - Generates the minimal Django starter described in the MVP Feature Matrix
-  - Ships with standalone `settings.py` by default; there is NO automatic settings inheritance. Advanced users who manually embed `quickscale_core` via git subtree may opt-in to inherit from `quickscale_core.settings` (see [decisions.md](./docs/technical/decisions.md#mvp-feature-matrix-authoritative)).
-  - **Optional**: Embed `quickscale_core` via git subtree after generation; follow the [Personal Toolkit workflow](./docs/technical/decisions.md#integration-note-personal-toolkit-git-subtree) for canonical commands and helper roadmap
-2. Add your custom Django apps and features
-3. Adopt optional inheritance or module extraction patterns only when you embed the core; the rules and best practices stay centralized in `DECISIONS.md`
-4. Build your unique client application
-5. Deploy to Railway with `quickscale deploy railway` (or use standard Django deployment)
-
-ℹ️ QuickScale's MVP centers on the personal toolkit workflow. Extraction patterns, module packaging, and subtree helper command plans stay documented in `docs/technical/decisions.md` so this README can stay concise.
-
-🔎 **Scope note**: The [MVP Feature Matrix](./docs/technical/decisions.md#mvp-feature-matrix-authoritative) is the single source of truth for what's in or out.
-
-### What You Get
-
-Running `quickscale init myapp` generates a **production-ready Django project** with:
-
-- ✅ **Docker** setup (development + production)
-- ✅ **PostgreSQL** configuration
-- ✅ **Environment-based** settings (dev/prod split)
-- ✅ **Security** best practices (SECRET_KEY, ALLOWED_HOSTS, etc.)
-- ✅ **Testing** infrastructure (pytest + factory_boy)
-- ✅ **CI/CD** pipeline (GitHub Actions)
-- ✅ **Code quality** hooks (ruff format + ruff check)
-- ✅ **Poetry** for dependency management
-- ✅ **One-Command Deployment**: Deploy to Railway with `quickscale deploy railway` - fully automated setup
-
-**See the complete project structure:** [scaffolding.md - Generated Project Output](./docs/technical/scaffolding.md#5-generated-project-output)
-
-The generated project is **yours to own and modify** - no vendor lock-in, just Django best practices.
-
-## Why QuickScale vs. Alternatives?
-
-✅ **Faster than Cookiecutter** - One command vs. 30+ interactive prompts
-✅ **More flexible than SaaS Pegasus** - Open source with full code ownership ($0 vs. $349+)
-✅ **Simpler than building from scratch** - Production-ready in 5 minutes vs. days of setup
-✅ **Railway deployment automation** - Competitors require manual platform configuration
-
-**QuickScale is a development accelerator**, not a complete solution. You start with production-ready foundations and build your unique client application on top.
-
-See [competitive_analysis.md](./docs/overview/competitive_analysis.md) for detailed comparison with SaaS Pegasus and Cookiecutter.
-
----
-
-
-## Quick Start
-
-```bash
-# Install QuickScale globally
-./scripts/install_global.sh
-
-# Create your first project
-quickscale init myapp
-cd myapp
-
-# Or choose a specific theme (v0.61.0+)
-# quickscale init myapp --theme starter_html  # Default HTML theme
-# quickscale init myapp --theme starter_htmx  # HTMX theme (coming in v0.67.0)
-# quickscale init myapp --theme starter_react # React theme (coming in v0.68.0)
-```
-
-**Choose your development workflow:**
-
-### Option 1: Docker (Recommended for production parity)
-
-```bash
-# Start all services (web + database)
-quickscale up
-
-# Run migrations
-quickscale manage migrate
-
-# Create superuser
-quickscale manage createsuperuser
-
-# View logs
-quickscale logs -f web
-
-# Open a shell in the container
-quickscale shell
-
-# Stop services
-quickscale down
-```
-
-**Visit http://localhost:8000** - Your app is running in Docker with PostgreSQL!
-
-### Option 2: Native Poetry (Simpler for quick testing)
-
-```bash
-# Install dependencies
-poetry install
-
-# Run migrations
-poetry run python manage.py migrate
-
-# Start development server
-poetry run python manage.py runserver
-```
-
-**Visit http://localhost:8000** - Your app is running natively!
-
-**For complete command reference and workflows**, see the [user_manual.md](./docs/technical/user_manual.md).
-
-## Learn More
-
-- **[decisions.md](./docs/technical/decisions.md)** - Technical specifications and implementation rules
-- **[quickscale.md](./docs/overview/quickscale.md)** - Strategic vision and competitive positioning
-- **[competitive_analysis.md](./docs/overview/competitive_analysis.md)** - Comparison vs SaaS Pegasus and alternatives
-- **[roadmap.md](./docs/technical/roadmap.md)** - Development roadmap and implementation plan
-- **[user_manual.md](./docs/technical/user_manual.md)** - Commands and workflows
-- **[contributing.md](./docs/contrib/contributing.md)** - Development workflow and coding standards
-