Merge branch 'main' into nav-active

Author: mfosterw

.claude/skills/docs/SKILL.md

@@ -2,7 +2,7 @@
 name: docs
 description: Update, review, or build the Sphinx documentation for Democrasite
 disable-model-invocation: true
-argument-hint: "[what to update or check, e.g. 'review for accuracy' or 'add activitypub section']"
+argument-hint: "[what to update or check, e.g. 'review for accuracy' or 'add social section']"
 ---
 
 ## Task
@@ -30,7 +30,7 @@ docs/
     ├── democrasite.webiscite.views.rst
     ├── democrasite.webiscite.api.rst
     ├── democrasite.users.rst
-    ├── democrasite.activitypub.rst
+    ├── democrasite.social.rst
     └── … (one file per module)
 ```
 
@@ -41,14 +41,15 @@ All run from the `docs/` directory (or with `make -C docs <target>`):
 | Command | What it does |
 |---|---|
 | `make apidocs` | Regenerate all `docs/api/*.rst` from source using sphinx-apidoc. Run this whenever Python modules are added or removed. |
-| `make livehtml` | Build docs and serve with live reload at http://localhost:9000. Requires the docs Docker container (`docker compose -f docker-compose.docs.yml up`). |
+| `make livehtml` | Build docs and serve with live reload at http://localhost:9000. Run inside the `docs` service (started with `just up`; see `docker-compose.local.yml`). |
 | `make clean` | Remove `_build/` and `api/` directories for a fresh build. |
 | `make html` | One-off HTML build into `_build/html/`. |
 
-To serve with live reload locally (in Docker):
+To serve with live reload locally (in Docker), start the stack so the `docs` service runs (from repo root):
 ```
-docker compose -f docker-compose.docs.yml up
+just up
 ```
+The `docs` container runs `make livehtml` via `compose/local/django/start-docs`.
 
 To regenerate API docs locally (sphinx-apidoc must be installed):
 ```
@@ -98,7 +99,7 @@ Line length: 88 characters (enforced by ruff). Wrap long docstring lines to stay
    - `:class:\`~democrasite.webiscite.models.Bill\`` — class link
    - `:func:\`~democrasite.webiscite.tasks.submit_bill\`` — function link
    - `:meth:\`~democrasite.webiscite.webhooks.PullRequestHandler.opened\`` — method link
-3. Verify the build: `docker compose -f docker-compose.docs.yml up`
+3. Verify the build: `just up` and open http://localhost:9000/
 
 ### Adding a new Python module
 1. Write a module-level docstring at the top of the file

CLAUDE.md

@@ -22,7 +22,7 @@ All development uses Docker. The `justfile` sets `COMPOSE_FILE=docker-compose.lo
 just build                    # Build Docker images
 just up                       # Start all containers
 just down                     # Stop containers
-just test                     # Run pytest suite
+just test <args>              # Run pytest suite
 just lint                     # Run pre-commit hooks
 just typecheck                # Run mypy
 just manage <args>            # Run manage.py (e.g., just manage makemigrations)
@@ -31,16 +31,18 @@ just coverage                 # Run tests with coverage + open HTML report
 just shell                    # Bash shell in django container
 just pyshell                  # Django shell_plus (IPython)
 just run <cmd>                # Execute arbitrary command in django container
-just loaddata                 # Load fixtures (democrasite + activitypub)
+just loaddata                 # Load fixtures (democrasite + social)
 ```
 
-To run a single test file or test:
+To run a single test:
 
 ```bash
-just run pytest democrasite/webiscite/tests/test_models.py
-just run pytest democrasite/webiscite/tests/test_models.py::TestBill::test_method_name -v
+just test democrasite/webiscite/tests/test_models.py::TestBill::test_method_name -v
 ```
 
+For any `just` command, prefer running outside the sandbox to avoid `docker.sock`
+permission errors. If `just` is not found, run `conda env democrasite` first.
+
 Pytest is configured with `--ds=config.settings.test --reuse-db` in `pyproject.toml`.
 
 ## Architecture
@@ -49,7 +51,7 @@ Pytest is configured with `--ds=config.settings.test --reuse-db` in `pyproject.t
 
 - **`democrasite/webiscite/`** — Core app. Models: `PullRequest`, `Bill`, `Vote`. Handles GitHub webhooks, voting logic, constitution enforcement, and Celery tasks for auto-merging.
 - **`democrasite/users/`** — Custom `User` model (extends `AbstractUser` with single `name` field instead of first/last). OAuth integration.
-- **`democrasite/activitypub/`** — ActivityPub federation. Models: `Person` (linked to User with keypair), `Follow`.
+- **`democrasite/social/`** — Social network for short notes. Models: `Person` (linked to User with keypair), `Follow`.
 
 ### Configuration
 
@@ -60,9 +62,9 @@ Pytest is configured with `--ds=config.settings.test --reuse-db` in `pyproject.t
 
 ### Key Patterns
 
-- **Constitution system** (`webiscite/constitution.py`, `constitution.json`): Maps files to protected line ranges. PRs touching protected code become "constitutional" bills requiring supermajority. Line numbers auto-update after merges.
-- **Bill lifecycle**: OPEN → APPROVED/REJECTED/FAILED/CLOSED. Each Bill has a OneToOne to a Celery `PeriodicTask` that runs `submit_bill()` at voting period end.
-- **Webhook flow** (`webiscite/webhooks.py`): GitHub push events → HMAC validation → create/update `PullRequest` → create `Bill`.
+- **Constitution system** (`democrasite/webiscite/constitution.py`, repo-root `constitution.json`): Maps files to protected line ranges. PRs touching protected code become "constitutional" bills requiring supermajority. Line numbers auto-update after merges.
+- **Bill lifecycle**: Draft PRs yield `DRAFT` bills until `ready_for_review`; then `OPEN` → APPROVED/REJECTED/FAILED/CLOSED (or `AMENDED` if the PR branch changes during voting). Each Bill has a OneToOne to a Celery Beat `PeriodicTask` that runs `submit_bill()` at voting period end.
+- **Webhook flow** (`democrasite/webiscite/webhooks.py`): GitHub `pull_request` webhooks (open, reopen, close, synchronize, ready_for_review, etc.) → HMAC validation → create/update `PullRequest` and `Bill` as appropriate. `push` and `ping` are accepted with minimal handling.
 - **Vote constraints**: One vote per user per bill (DB unique constraint). Votes can be changed.
 - **Audit trail**: `django-simple-history` tracks changes on key models.
 

CONTRIBUTING.rst

@@ -120,8 +120,8 @@ Creating a Webhook
 
 :obj:`democrasite.webiscite` needs `webhooks`_ to find out about events on
 Github. `Create a webhook`_ in your fork of the repository, then generate a
-secret key for your hook and store it in your environment (either through your
-terminal or ``.env`` file) as ``GITHUB_SECRET_KEY``.
+secret key for your hook and store it in ``.envs/.local/.django`` (or your shell) as
+``GITHUB_WEBHOOK_SECRET`` so it matches the secret configured on GitHub.
 
 To test your webhook, follow these `instructions`_. (If you have a preferred
 tool for exposing your local server, feel free to replace smee with it.) If you

README.rst

@@ -12,7 +12,7 @@ Democrasite
 .. |Continuous integration| image:: https://github.com/mfosterw/cookiestocracy/actions/workflows/ci.yml/badge.svg
      :target: https://github.com/mfosterw/cookiestocracy/actions/workflows/ci.yml
 
-.. |Coverage report| image:: https://codecov.io/gh/mfosterw/cookiestocracy/branch/master/graph/badge.svg?token=NPV1TLXZIW
+.. |Coverage report| image:: https://codecov.io/gh/mfosterw/cookiestocracy/graph/badge.svg?token=NPV1TLXZIW
      :target: https://codecov.io/gh/mfosterw/cookiestocracy
 
 .. |Documentation status| image:: https://readthedocs.org/projects/cookiestocracy/badge/?version=latest
@@ -74,7 +74,7 @@ following the instructions in the guide.
 Understanding the repository
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Check out ``repo_map.txt`` in the root of the repository for a display of the
+Check out ``repository_map.txt`` in the root of the repository for a display of the
 repository layout and brief explanations for the purpose of each non-obvious file and
 directory.
 
@@ -94,7 +94,7 @@ Loading initial data
 
 To load some initial sample data into the database, run::
 
-    $ python manage.py loaddata democrasite activitypub
+    $ python manage.py loaddata democrasite social
 
 Setting up your users
 ^^^^^^^^^^^^^^^^^^^^^
@@ -114,8 +114,8 @@ Setting up your users
   how the site behaves for both kinds of users.
 
 .. _`django-allauth`: https://docs.allauth.org/en/latest/introduction/index.html
-.. _`GitHub`: https://django-allauth.readthedocs.io/en/latest/providers.html#github
-.. _`Google`: https://docs.allauth.org/en/latest/socialaccount/providers/github.html
+.. _`GitHub`: https://docs.allauth.org/en/latest/socialaccount/providers/github.html
+.. _`Google`: https://docs.allauth.org/en/latest/socialaccount/providers/google.html
 
 Linting
 ^^^^^^^

config/settings/base.py

@@ -102,7 +102,7 @@
     # Custom apps
     "democrasite.users",
     "democrasite.webiscite",
-    "democrasite.activitypub",
+    "democrasite.social",
 ]
 # https://docs.djangoproject.com/en/dev/ref/settings/#installed-apps
 INSTALLED_APPS = DJANGO_APPS + THIRD_PARTY_APPS + LOCAL_APPS

config/urls.py

@@ -23,10 +23,8 @@
     # User management
     path("users/", include("democrasite.users.urls", namespace="users")),
     path("accounts/", include("allauth.urls")),
-    # ActivityPub
-    path(
-        "activitypub/", include("democrasite.activitypub.urls", namespace="activitypub")
-    ),
+    # Social
+    path("social/", include("democrasite.social.urls", namespace="social")),
     # webiscite
     path("", include("democrasite.webiscite.urls", namespace="webiscite")),
     # Media files