usethis-python · nathanjmcdougall · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
diff --git a/docs/about-license.md → docs/about/about-license.md b/docs/about-license.md → docs/about/about-license.md
diff --git a/docs/faq.md → docs/about/faq.md b/docs/faq.md → docs/about/faq.md
diff --git a/docs/about/philosophy.md b/docs/about/philosophy.md
@@ -0,0 +1,15 @@
+# Philosophy
+
+usethis targets the Python ecosystem in a particular way. It's not trying to be a package manager: that's well covered by `uv`. It's also not trying to provide absolutely all the functionality a developer might want, e.g. CI, editor, and LLM configuration. Instead, usethis focuses on the Python-specific aspects of Python developer tooling and project configuration.
+
+One of the significant motivations for usethis is to make it easier for developers to avail themselves of the rich and powerful ecosystem of Python developer tooling. In the age of LLM-powered development, the benefits of these tools are more significant than ever.
+
+## Why not CI Configuration?
+
+Until v0.19.0, usethis provided a `usethis ci` command, but this was deprecated for removal. It's worth giving some of the rationale for why, since it helps to clarify the philosophy of usethis.
+
+- There are many different CI providers, external services, and configurations that people might want to use. That variety is in tension with the usethis philosophy of generally providing a single, opinionated way to do things. There's often an element of setting up broader infrastructure, API keys, etc. and altogether this makes it very difficult to automate effectively.
+
+- CI configuration has important security implications to consider. It's not something that is necessary sensible to try and automate compared to Python developer tooling and project configuration.
+
+- Directing dev tooling through tools for managing hooks like [prek](https://prek.j178.dev/) and [pre-commit](https://pre-commit.com/) limits the value in also configuring CI, since the CI configuration is generally just invoking these tools.
diff --git a/docs/similar-projects.md → docs/about/similar-projects.md b/docs/similar-projects.md → docs/about/similar-projects.md
diff --git a/docs/pipeweld.md b/docs/pipeweld.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -9,10 +9,14 @@ nav:
   - CLI Reference:
     - Overview: cli/overview.md
     - Reference: cli/reference.md
-  - With Other Frameworks: frameworks.md
-  - Similar Projects: similar-projects.md
-  - FAQ: faq.md
-  - License: about-license.md
+  - Usage With Other Frameworks: frameworks.md
+  - About:
+    - Philosophy: about/philosophy.md
+    - Similar Projects: about/similar-projects.md
+    - FAQ: about/faq.md
+    - License: about/about-license.md
+    - Internal Utilities:
+      - Pipeweld: pipeweld.md
 
 theme:
   name: material

diff --git a/tests/docs/test_readme.py b/tests/docs/test_readme.py
@@ -33,12 +33,14 @@ def test_assemble_readme_from_docs(usethis_dev_dir: Path):
         )
     )
     parts.append(
-        _get_doc_file(usethis_dev_dir / "docs" / "similar-projects.md").replace(
+        _get_doc_file(
+            usethis_dev_dir / "docs" / "about" / "similar-projects.md"
+        ).replace(
             "](frameworks.md)",
             "](https://usethis.readthedocs.io/en/stable/frameworks)",
         )
     )
-    parts.append(_get_doc_file(usethis_dev_dir / "docs" / "about-license.md"))
+    parts.append(_get_doc_file(usethis_dev_dir / "docs" / "about" / "about-license.md"))
 
     content = (
         (usethis_dev_dir / "README.md")