docs: align user docs with Unreleased changes for next release

A reader review flagged several drifts between the docs and the code
after the heavy Unreleased work. This commit walks through each file
and brings it back in sync.

README gets the biggest cleanup: the Quick Start no longer places the
template tag before the first build, there is now a `mkdir assets`
step so Django doesn't error out on a missing STATICFILES_DIRS entry,
the watcher autoreloader and the runserver passthrough are called out
in the command table, the requirements range is corrected from the
fictitious "Django 4.0-6.0+" to the actually supported 4.2/5.2/6.0,
and the advanced configuration example uses
TAILWIND_CLI_USE_SYSTEM_BINARY plus the new opt-in
TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS instead of a hardcoded
TAILWIND_CLI_PATH.

docs/usage.md loses its accidental duplicate `### watch` heading,
gains a tip admonition about the auto-generated `.gitignore`, and
aligns on the current default source-CSS location (which previously
contradicted settings.md). docs/installation.md picks up the new
`mkdir assets` step, mentions `--noreload`, and gets its own note
about the auto `.gitignore`. docs/settings.md rewrites the
TAILWIND_CLI_SRC_CSS entry so it agrees with usage.md on where the
default file lives and who owns it. docs/development.md now mentions
both the watch autoreloader and the runserver passthrough under
"Daily Development". docs/index.md toctree is reordered so
template_tags and base_template come before the development chapter.

Typos fixed: "seperately"/"seperate", "production built" → "build".

Author: oliverandrich

README.md

@@ -50,10 +50,15 @@ INSTALLED_APPS = [
     "django_tailwind_cli",
 ]
 
-# Configure static files directory
+# Configure static files directory — make sure it exists on disk,
+# Django raises an error at startup if it does not.
 STATICFILES_DIRS = [BASE_DIR / "assets"]
 ```
 
+```bash
+mkdir -p assets
+```
+
 ### 3. Set up your base template
 
 Create or update your base template (e.g., `templates/base.html`):
@@ -76,25 +81,23 @@ Create or update your base template (e.g., `templates/base.html`):
 </html>
 ```
 
-### 4. Interactive setup (recommended for first-time users)
-
-```bash
-python manage.py tailwind setup
-```
-
-This will guide you through the complete setup process!
-
-### 5. Start developing
+### 4. Start developing
 
 ```bash
-# Start development server with hot reload
+# Start Django's dev server with a parallel Tailwind watcher (recommended)
 python manage.py tailwind runserver
 
 # Or run build and watch separately
 python manage.py tailwind watch  # In one terminal
 python manage.py runserver       # In another terminal
 ```
 
+The watcher runs under Django's own auto-reloader, so editing `settings.py` (e.g. adding a new app) restarts it automatically and picks up the new configuration on the fly. Pass `--noreload` to opt out.
+
+First run creates a managed `<BASE_DIR>/.django_tailwind_cli/` directory for the CLI binary and an auto-generated `source.css`. The directory is automatically git-ignored — no entry in your project-level `.gitignore` needed.
+
+> **Tip:** Prefer a guided walkthrough? Run `python manage.py tailwind setup` instead for an interactive step-by-step first-time setup.
+
 ### 🎉 You're ready to go!
 
 Start adding Tailwind classes to your templates:
@@ -146,19 +149,21 @@ Start adding Tailwind classes to your templates:
 
 ### 🛠️ Management Commands
 
-| Command        | Purpose                    | Example                                  |
-| -------------- | -------------------------- | ---------------------------------------- |
-| `setup`        | Interactive setup guide    | `python manage.py tailwind setup`        |
-| `build`        | Production CSS build       | `python manage.py tailwind build`        |
-| `watch`        | Development file watcher   | `python manage.py tailwind watch`        |
-| `runserver`    | Combined server + watcher  | `python manage.py tailwind runserver`    |
-| `config`       | Show current configuration | `python manage.py tailwind config`       |
-| `troubleshoot` | Debug common issues        | `python manage.py tailwind troubleshoot` |
+| Command        | Purpose                                              | Example                                  |
+| -------------- | ---------------------------------------------------- | ---------------------------------------- |
+| `setup`        | Interactive first-time setup guide                   | `python manage.py tailwind setup`        |
+| `build`        | Production CSS build                                 | `python manage.py tailwind build`        |
+| `watch`        | Development file watcher (Django autoreload by default) | `python manage.py tailwind watch`    |
+| `runserver`    | Django dev server + watcher (forwards any runserver flag) | `python manage.py tailwind runserver` |
+| `config`       | Show current configuration                           | `python manage.py tailwind config`       |
+| `troubleshoot` | Debug common issues                                  | `python manage.py tailwind troubleshoot` |
+
+`tailwind runserver` is a transparent passthrough: every positional argument and option (apart from `--force-default-runserver`) is forwarded verbatim to the underlying `runserver` or `runserver_plus`. Every flag those commands accept works — including `runserver_plus`-only ones like `--extra-file`, `--reloader-interval`, and `--print-sql`.
 
 ## 📋 Requirements
 
 - **Python:** 3.10+
-- **Django:** 4.0-6.0+
+- **Django:** 4.2 LTS, 5.2, or 6.0
 - **Platform:** Windows, macOS, Linux (automatic platform detection)
 
 ## ⚙️ Configuration Examples
@@ -181,9 +186,11 @@ TAILWIND_CLI_DIST_CSS = "css/app.css"
 # Enable DaisyUI
 TAILWIND_CLI_USE_DAISY_UI = True
 
-# Custom CLI path (for CI/CD)
-TAILWIND_CLI_PATH = "/usr/local/bin/tailwindcss"
-TAILWIND_CLI_AUTOMATIC_DOWNLOAD = False
+# Use an already-installed Tailwind binary (e.g. `brew install tailwindcss`)
+TAILWIND_CLI_USE_SYSTEM_BINARY = True
+
+# Auto-inject @source directives for editable-installed external apps (opt-in)
+TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS = True
 ```
 
 ### Production Settings

docs/development.md

@@ -27,6 +27,10 @@ python manage.py tailwind watch     # Terminal 1: CSS watching
 python manage.py runserver          # Terminal 2: Django server
 ```
 
+`tailwind watch` (and the inner watcher spawned by `tailwind runserver`) runs under Django's auto-reloader by default. Any change to a Python file — including `settings.py` — restarts the watcher, regenerates the source CSS file, and respawns the Tailwind CLI subprocess. Pass `--noreload` to disable.
+
+`tailwind runserver` is a transparent wrapper around the underlying Django `runserver` / `runserver_plus` command: every runserver flag is forwarded verbatim. Consult `python manage.py runserver --help` (or `runserver_plus --help` with `django-extensions` installed) for the full list of available options.
+
 ## Template Development
 
 1. **Create/Edit Template**

docs/index.md

@@ -8,8 +8,8 @@
 installation
 usage
 settings
-development
 template_tags
 base_template
+development
 changelog
 ```

docs/installation.md

@@ -35,12 +35,16 @@
    ]
    ```
 
-3. Configure the `STATICFILES_DIRS` parameter in your `settings.py` if not already configured.
+3. Configure the `STATICFILES_DIRS` parameter in your `settings.py` if not already configured, and make sure the referenced directory exists on disk — Django raises an error at startup if it doesn't.
 
    ```python
    STATICFILES_DIRS = [BASE_DIR / "assets"]
    ```
 
+   ```shell
+   mkdir -p assets
+   ```
+
 4. Add template code.
 
    ```htmldjango
@@ -65,7 +69,11 @@
    python manage.py tailwind watch
    ```
 
-   If you only start the Tailwind CLI in watch mode, you have to start the debug server with the standard command `python manage.py runserver` seperately.
+   If you only start the Tailwind CLI in watch mode, you have to start the debug server with the standard command `python manage.py runserver` separately.
+
+   `tailwind watch` runs under Django's auto-reloader by default, so editing `settings.py` restarts the watcher and respawns the Tailwind CLI with a fresh configuration. Pass `--noreload` to disable this.
+
+6. The first run creates a managed directory at `<BASE_DIR>/.django_tailwind_cli/` for the downloaded CLI binary and the auto-generated source CSS file. This directory is automatically git-ignored via a `.gitignore` file it drops on first use — you don't need to add anything to your project-level `.gitignore`.
 
 ## Optional steps
 

docs/settings.md

@@ -143,13 +143,11 @@ TAILWIND_CLI_ASSET_NAME = "tailwindcss-extra"
 
 ### TAILWIND_CLI_SRC_CSS
 
-**Default**: `".django_tailwind_cli/source.css"`
+**Default**: `".django_tailwind_cli/source.css"` (relative to `BASE_DIR`, auto-created on first use)
 
-This variable can be set to a relative path and an absolute path.
+Path to the Tailwind CSS input file. The library manages the default file itself — it writes a minimal `@import "tailwindcss";` (plus `@plugin "daisyui";` if DaisyUI is enabled) into `<BASE_DIR>/.django_tailwind_cli/source.css` on first run and updates it when the auto-generated content drifts.
 
-If it is a relative path it is assumed to be relative to `settings.BASE_DIR`. If `settings.BASE_DIR` is not defined or the file doesn't exist a `ValueError` is raised.
-
-If it is an absolute path, this path is used as the input file for Tailwind CSS CLI. If the path doesn't exist, a `ValueError` is raised.
+Set this to point at a hand-written file if you need custom CSS alongside the Tailwind import. When `TAILWIND_CLI_SRC_CSS` is set, the library only creates the file if it doesn't yet exist and never overwrites it afterwards — you own it. A relative path is resolved against `settings.BASE_DIR`, an absolute path is used as-is.
 
 ### TAILWIND_CLI_DIST_CSS
 

docs/usage.md

@@ -6,23 +6,29 @@
 **No.** The management commands of this library handle the download and installation of the Tailwind CLI. You don't have to deal with this. But you can configure the installation location and the version of the CLI you want to use. Take a look at the [settings](settings.md) section.
 :::
 
-:::{admonition} Do I have to create my own `css/source.css` for Tailwind 4.x?
+:::{admonition} Do I have to create my own `source.css` for Tailwind 4.x?
 :class: tip
 
-**No.** The management commands also take care of this step. If no `css/source.css` is present in your project, a new one with sane defaults will be created. Afterwards this file will be used and be customized by you. The default location for the file is first folder from the `STATICFILES_DIRS` of your project, but you can change this. Take a look at the [settings](settings.md) section.
+**No.** The management commands also take care of this step. If no source CSS file is present yet, one with sane defaults is created at `<BASE_DIR>/.django_tailwind_cli/source.css`. You can point at a hand-written file instead by setting [`TAILWIND_CLI_SRC_CSS`](settings.md#tailwind_cli_src_css) in your Django settings — the library leaves your file alone in that case.
+:::
+
+:::{admonition} Is `.django_tailwind_cli/` safe to commit?
+:class: tip
+
+**No, and you don't have to do anything.** On first use the library writes a `.gitignore` containing `*` into the managed directory, so the downloaded CLI binary and the auto-generated `source.css` are silently ignored by Git — no entry in your project-level `.gitignore` needed.
 :::
 
 ## Management commands
 
 ### build
 
-Run `python manage.py tailwind build` to create an optimized production built of the stylesheet. Afterwards you are ready to deploy. Take care the this command is run before `python manage.py collectstatic` in your build process.
+Run `python manage.py tailwind build` to create an optimized production build of the stylesheet. Afterwards you are ready to deploy. Make sure this command runs before `python manage.py collectstatic` in your build process.
 
 ### watch
 
-Run `python manage.py tailwind watch` to just start a tailwind watcher process if you prefer to start your debug server in a seperate shell or prefer a different solution than runserver or runserver_plus.
+Run `python manage.py tailwind watch` to start a Tailwind watcher process on its own — useful if you prefer to run your debug server in a separate shell or use a workflow other than `runserver` / `runserver_plus`.
 
-By default the watch command runs under Django's own auto-reloader (the same one `runserver` uses). Whenever you change a Python file — including `settings.py` — the watcher restarts its Python process, regenerates the default source CSS file (picking up freshly added `INSTALLED_APPS`), and restarts the Tailwind CLI subprocess. This pairs nicely with [`TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS`](settings.md#tailwind_cli_auto_source_external_apps): adding an editable-installed app and updating `INSTALLED_APPS` is enough — no manual restart needed.
+By default the watch command runs under Django's own auto-reloader (the same one `runserver` uses). Whenever you change a Python file — including `settings.py` — the watcher restarts its Python process, regenerates the default source CSS file (picking up freshly added `INSTALLED_APPS`), and respawns the Tailwind CLI subprocess. This pairs nicely with [`TAILWIND_CLI_AUTO_SOURCE_EXTERNAL_APPS`](settings.md#tailwind_cli_auto_source_external_apps): adding an editable-installed app and updating `INSTALLED_APPS` is enough — no manual restart needed.
 
 Pass `--noreload` if you want a single-process watch loop (e.g. in CI or when debugging the watcher itself):
 
@@ -114,11 +120,7 @@ Areas covered:
 
 ### remove_cli
 
-Run `python manage.py tailwind remove_cli` to remove the installed cli.
-
-### watch
-
-Run `python manage.py tailwind watch` to just start a tailwind watcher process if you prefer to start your debug server in a seperate shell or prefer a different solution than runserver or runserver_plus.
+Run `python manage.py tailwind remove_cli` to remove the installed CLI binary. This only works with the managed download; system binaries (`TAILWIND_CLI_USE_SYSTEM_BINARY = True`) are refused.
 
 ## Use with Docker Compose