Symlink CLAUDE.md, add README instructions and do some README updates

Author: davegaeddert

AGENTS.md

@@ -13,7 +13,20 @@ This is the only AGENTS.md file in the repo -- you don't need to look for others
 
 Inside each top level subdirectory is a `README.md` that is a symlink to the `README.md` in the of the Python package itself. You only need to edit the `README.md` inside of the package itself.
 
-The README is the main written documentation for the package (or module). You can structure it using [`plain/assets/README.md`](/plain/plain/assets/README.md) as an example.
+The README is the main written documentation for the package (or module). You can structure it using [`plain-api/plain/api/README.md`](/plain/plain/assets/README.md) as an example.
+
+Some instructions for writing READMEs:
+
+- Underneath the h1 should be a **<short description>** (in bold) that describes the package in one sentence.
+- There should be a table of contents at the top with links to the h2s and h3s in the README.
+- When referencing specific classes or functions in code, link to them with a # fragment identifier, like this: [`AssetView`](./views.py#AssetView).
+- The first section of the README should be an **Overview** that gets straight into basic examples of how to use the package.
+- An **Installation** section should always be present but it should be the last section of the README.
+- The **Installation** section should get the user from nothing to _something_, even if _something_ is a demo/example view or code that will need additional customization.
+- The **Installation** steps will typically be run by an agent like Claude Code, but they also need to be written in a way that a human can follow them.
+- Miscellaneous notes or information about the package should be added as **FAQs** in the second to last section of the README.
+- For the **FAQs**, use h4s for the questions.
+- The most advanced usages of the package don't need to be fully documented (i.e. every possible paramater, etc.). They can be mentioned if the user otherwise wouldn't know about them, but then they can be linked to the code itself for more information.
 
 ## Verifying changes
 

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

plain-admin/plain/admin/README.md

@@ -2,100 +2,22 @@
 
 **Manage your app with a backend interface.**
 
-The Plain Admin provides a combination of built-in views and the flexibility to create your own. You can use it to quickly get visibility into your app's data and to manage it.
-
-![Plain Admin user example](https://assets.plainframework.com/docs/plain-pageviews-user.png)
+- [Overview](#overview)
+- [Admin viewsets](#admin-viewsets)
+- [Admin cards](#admin-cards)
+- [Admin forms](#admin-forms)
+- [List displays](#list-displays)
+- [Toolbar](#toolbar)
+- [Impersonate](#impersonate)
+- [Installation](#installation)
 
-## Installation
-
-Install the `plain.admin` package and its dependencies.
+## Overview
 
-```console
-uv add plain.admin
-```
-
-The admin uses a combination of other Plain packages, most of which you will already have installed. Ultimately, your settings will look something like this:
-
-```python
-# app/settings.py
-INSTALLED_PACKAGES = [
-    "plain.models",
-    "plain.tailwind",
-    "plain.auth",
-    "plain.sessions",
-    "plain.htmx",
-    "plain.admin",
-    "plain.elements",
-    # other packages...
-]
-
-AUTH_USER_MODEL = "users.User"
-AUTH_LOGIN_URL = "login"
-
-MIDDLEWARE = [
-    "plain.sessions.middleware.SessionMiddleware",
-    "plain.auth.middleware.AuthenticationMiddleware",
-    "plain.admin.AdminMiddleware",
-]
-```
-
-Your User model is expected to have an `is_admin` field (or attribute) for checking who has permission to access the admin.
-
-```python
-# app/users/models.py
-from plain import models
-
-
-@models.register_model
-class User(models.Model):
-    is_admin = models.BooleanField(default=False)
-    # other fields...
-```
-
-To make the admin accessible, add the `AdminRouter` to your root URLs.
-
-```python
-# app/urls.py
-from plain.admin.urls import AdminRouter
-from plain.urls import Router, include, path
-
-from . import views
-
-
-class AppRouter(Router):
-    namespace = ""
-    urls = [
-        include("admin/", AdminRouter),
-        path("login/", views.LoginView, name="login"),
-        path("logout/", LogoutView, name="logout"),
-        # other urls...
-    ]
-
-```
-
-Optionally, you can add the admin toolbar to your base template. The toolbar will appear when `settings.DEBUG` or when `request.user.is_admin` (including in production!).
-
-```html
-<!-- app/templates/base.html -->
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>{{ html_title|default("My App") }}</title>
-    {% tailwind_css %}
-</head>
-<body>
-    {% block content required %}{% endblock %}
-
-    {% toolbar %}
-</body>
-</html>
-```
+The Plain Admin provides a combination of built-in views and the flexibility to create your own. You can use it to quickly get visibility into your app's data and to manage it.
 
-## Admin viewsets
+![Plain Admin user example](https://assets.plainframework.com/docs/plain-pageviews-user.png)
 
-The most common use of the admin is to display and manage your `plain.models`. To do this, create a viewset with a set of inner views.
+The most common use of the admin is to manage your `plain.models`. To do this, create a [viewset](./views/viewsets.py#AdminViewset) with inner/nested views:
 
 ```python
 # app/users/admin.py
@@ -140,7 +62,9 @@ class UserAdmin(AdminViewset):
         form_class = UserForm
 ```
 
-The [`AdminViewset`](./views/viewsets.py) will automatically recognize inner views named `ListView`, `CreateView`, `DetailView`, `UpdateView`, and `DeleteView`. It will interlink these views automatically in the UI and form success URLs. You can define additional views too, but you will need to implement a couple methods to hook them up.
+## Admin viewsets
+
+The [`AdminViewset`](./views/viewsets.py#AdminViewset) will automatically recognize inner views named `ListView`, `CreateView`, `DetailView`, `UpdateView`, and `DeleteView`. It will interlink these views automatically in the UI and form success URLs. You can define additional views too, but you will need to implement a couple methods to hook them up.
 
 ## Admin cards
 
@@ -150,9 +74,9 @@ TODO
 
 TODO
 
-## List `displays`
+## List displays
 
-On admin list views, you can define different `displays` to build predefined views of your data. The display choices will be shown in the UI, and you can use the current `self.display` in your view.
+On [`AdminListView`](./views/objects.py#AdminListView) and [`AdminModelListView`](./views/models.py#AdminModelListView), you can define different `displays` to build predefined views of your data. The display choices will be shown in the UI, and you can use the current `self.display` in your view logic.
 
 ```python
 # app/users/admin.py
@@ -188,3 +112,89 @@ TODO
 ## Impersonate
 
 TODO
+
+## Installation
+
+Install the `plain.admin` package from [PyPI](https://pypi.org/project/plain.admin/):
+
+```bash
+uv add plain.admin
+```
+
+The admin uses a combination of other Plain packages, most of which you will already have installed. Ultimately, your settings will look something like this:
+
+```python
+# app/settings.py
+INSTALLED_PACKAGES = [
+    "plain.models",
+    "plain.tailwind",
+    "plain.auth",
+    "plain.sessions",
+    "plain.htmx",
+    "plain.admin",
+    "plain.elements",
+    # other packages...
+]
+
+AUTH_USER_MODEL = "users.User"
+AUTH_LOGIN_URL = "login"
+
+MIDDLEWARE = [
+    "plain.sessions.middleware.SessionMiddleware",
+    "plain.auth.middleware.AuthenticationMiddleware",
+    "plain.admin.AdminMiddleware",
+]
+```
+
+Your User model is expected to have an `is_admin` field (or attribute) for checking who has permission to access the admin.
+
+```python
+# app/users/models.py
+from plain import models
+
+
+@models.register_model
+class User(models.Model):
+    is_admin = models.BooleanField(default=False)
+    # other fields...
+```
+
+To make the admin accessible, add the [`AdminRouter`](./urls.py#AdminRouter) to your root URLs.
+
+```python
+# app/urls.py
+from plain.admin.urls import AdminRouter
+from plain.urls import Router, include, path
+
+from . import views
+
+
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        include("admin/", AdminRouter),
+        path("login/", views.LoginView, name="login"),
+        path("logout/", LogoutView, name="logout"),
+        # other urls...
+    ]
+```
+
+Typically you will also want to add the admin `{% toolbar %}` to the bottom of your base template. The toolbar will appear when `settings.DEBUG` or when `request.user.is_admin` (including in production!).
+
+```html
+<!-- app/templates/base.html -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,  initial-scale=1.0">
+    <title>{{ html_title|default("My App") }}</title>
+    {% tailwind_css %}
+</head>
+<body>
+    {% block content required %}{% endblock %}
+
+    {% toolbar %}
+</body>
+</html>
+```

plain-admin/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "plain.admin"
 version = "0.37.2"
-description = "Admin dashboard and tools for Plain."
+description = "Manage your app with a backend interface."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 license = "BSD-3-Clause"
 readme = "README.md"

plain-api/plain/api/README.md

@@ -2,7 +2,18 @@
 
 **Build APIs using class-based views.**
 
-This package includes lightweight view classes for building APIs using the same patterns as regular HTML views. It also provides an [`APIKey` model](#api-keys) and support for generating [OpenAPI](#openapi) documents.
+- [Overview](#overview)
+- [Authentication and authorization](#authentication-and-authorization)
+- [`PUT`, `POST`, and `PATCH`](#put-post-and-patch)
+- [`DELETE`](#delete)
+- [API keys](#api-keys)
+- [OpenAPI](#openapi)
+    - [Deploying](#deploying)
+- [Installation](#installation)
+
+## Overview
+
+This package includes lightweight view classes for building APIs using the same patterns as regular HTML views. It also provides an [`APIKey`](./models.py#APIKey) model and support for generating [OpenAPI](#openapi) documents.
 
 Because [Views](/plain/plain/views/README.md) can convert built-in types to responses, an API view can simply return a dict or list to send a JSON response back to the client. More complex responses can use the [`JsonResponse`](/plain/plain/http/response.py#JsonResponse) class.
 
@@ -179,7 +190,7 @@ class PullRequestView(BaseAPIView):
 
 ## API keys
 
-The provided [`APIKey` model](./models.py) includes randomly generated, unique API tokens that are automatically parsed by `APIKeyView`. The tokens can optionally be named and include an `expires_at` date.
+The provided [`APIKey`](./models.py#APIKey) model includes randomly generated, unique API tokens that are automatically parsed by `APIKeyView`. The tokens can optionally be named and include an `expires_at` date.
 
 Associating an `APIKey` with a user (or team, for example) is up to you. Most likely you will want to use a `ForeignKey` or a `ManyToManyField`.
 
@@ -218,7 +229,7 @@ user.api_key = APIKey.objects.create()
 user.save()
 ```
 
-To use API keys in your views, you can inherit from `APIKeyView` and customize the [`use_api_key` method](./views.py#use_api_key) to set the `request.user` attribute (or any other attribute) to the object associated with the API key.
+To use API keys in your views, you can inherit from `APIKeyView` and customize the [`use_api_key`](./views.py#use_api_key) method to set the `request.user` attribute (or any other attribute) to the object associated with the API key.
 
 ```python
 # app/api/views.py
@@ -380,3 +391,64 @@ class APIRouter(Router):
         path("openapi.json", AssetView.as_view(asset_path="openapi.json")),
     ]
 ```
+
+## Installation
+
+Install the `plain.api` package from [PyPI](https://pypi.org/project/plain.api/):
+
+```console
+$ uv add plain.api
+```
+
+Typically you will want to create an `api` package to contain all of the views and URLs for your app's API.
+
+```console
+$ plain create api
+```
+
+The `app.api` package should be added to your app's `INSTALLED_APPS` setting in `app/settings.py`:
+
+```python
+# app/settings.py
+INSTALLED_APPS = [
+    # ...other apps
+    "app.api",
+]
+```
+
+Then create a your API URL router and your first API view.
+
+```python
+# app/api/urls.py
+from plain.urls import Router, path
+from plain.api.views import APIView
+
+
+class ExampleAPIView(APIView):
+    def get(self):
+        return {"message": "Hello, world!"}
+
+
+class APIRouter(Router):
+    namespace = "api"
+    urls = [
+        path("example/", ExampleAPIView),
+    ]
+```
+
+The `APIRouter` can then be included in your app's URLs.
+
+```python
+# app/urls.py
+from plain.urls import include, path
+
+from .api.urls import APIRouter
+
+
+class AppRouter(Router):
+    namespace = "app"
+    urls = [
+        # ...other routes
+        include("api/", APIRouter),
+    ]
+```

plain-api/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "plain.api"
 version = "0.12.0"
-description = "API for Plain."
+description = "Build APIs using class-based views."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"
 requires-python = ">=3.11"