# Tasknest development notes ## AI assistant connection The Food and Kitchen API has a Streamable HTTP MCP adapter with per-user token and OAuth authentication. See [MCP.md](MCP.md) for local startup, deployment routing, client setup, and verification. ## Weather scheduling The server gets a finite 16-day daily forecast from Open-Meteo and caches each user's normalized forecast for twelve hours. No browser code, template, or model calls Open-Meteo directly. - **Dry** rejects a day with precipitation probability of 40% or more, or 0.5 mm or more precipitation. - **Sunny / mostly sunny** also requires a clear/partly-cloudy condition and at least four hours of sunshine. - **Warm** requires a maximum temperature of at least 15 °C. - **Dry and warm** requires both of the corresponding rules. If no forecast is available, a weather-dependent task remains visible rather than being treated as unsuitable. If a forecast finds an unsuitable natural occurrence, Tasknest creates a weather-owned occurrence shift to the first suitable vacancy in the finite forecast horizon. Natural recurrences and existing weather shifts are skipped, so an occurrence is never duplicated. The original recurrence anchor is not changed. Deferral precedence is: manual, missed, and Sick Day state are evaluated before weather movement. Weather never overwrites those sources. Weather shifts are stored separately in `TaskWeatherShift`, so they can be recalculated without modifying user-owned deferrals. ## Legacy ownership migration Migration `0006` assigns old unowned tasks only when the database has exactly one active user. This local development database met that condition and its two existing tasks were assigned to that account. In a multi-user deployment the migration deliberately leaves legacy rows unowned instead of guessing; claim them explicitly before making ownership non-null at the database level. ## Demo account reset Create or reset the public demonstration account and its dummy data with: ```sh /home/jorenmartijn/django/tasksnest/bin/python /home/jorenmartijn/django/main/manage.py seed_demo ``` The command resets only an account marked as a demo by `planner.UserSettings.is_demo` (the migration marks the existing non-staff `demo` account once). It refuses to reset an unmarked or privileged existing account. Existing credentials are preserved unless `TASKNEST_DEMO_PASSWORD` or `--password` is supplied; creating a new demo account requires one of these. It creates sample parent/subtasks, workouts, pain, sleep, bowel, tooth-brushing and water check-ins, a 16-hour fasting schedule, and a food diary with nutrition goals, six local foods, favourites, custom portions, a sample stress check-in and dream, and entries across several days. Food seeding makes no external API requests. It is idempotent: running it again removes demo-only edits and restores the same baseline. Use `--username` and `--password` to rotate the credential explicitly. Do not put a password in a systemd command line or committed file. The reset also removes demo-owned dreams, stress entries, draft recipes, inventory, tokens, OAuth grants, uploaded food/draft-recipe images, and active Django sessions. Published demo recipes are curated Recipe Match catalogue data: the reset preserves them and demo visitors cannot change them through recipe write routes. It keeps the demo account and its marker. Demo HTTP requests cannot issue tokens, authorize OAuth clients, send ntfy tests, use external product lookups, or upload recipe images. Demo writes are limited to 1 MiB, 60 requests per minute, and 500 requests per day per application cache instance. All visitors currently share one demo account and can see each other's edits until the reset; do not use the demo for private information. A future isolated visitor session design should address that privacy limitation. Before deploying, provision a unique `DJANGO_SECRET_KEY` of at least 50 random characters in the process environment or the ignored repository-root `.env`, and set `DJANGO_DEBUG=false`. The code refuses to start without the secret. Rotating the old public development secret invalidates existing signed sessions. Run `manage.py check --deploy` with the deployment environment and resolve any remaining warnings before exposing the service. Do not commit `.env`. A daily systemd timer template is provided in `main/deploy/systemd/`. Adjust the `User`, `WorkingDirectory`, and `ExecStart` paths in the service file if needed, then install it with: ```sh sudo cp main/deploy/systemd/tasknest-demo-seed.service /etc/systemd/system/ sudo cp main/deploy/systemd/tasknest-demo-seed.timer /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now tasknest-demo-seed.timer systemctl list-timers tasknest-demo-seed.timer ``` The supplied timer runs daily at 00:00 Europe/Amsterdam and catches up after a missed scheduled run when the host comes back online. ## Fasting phase notifications The `notify_fasting_phases` command checks each active fasting schedule and sends an ntfy notification when the current phase changes to fasting or eating. It requires a tested, enabled ntfy topic in Settings. The command records each phase boundary so repeated runs do not send duplicate notifications. A failed delivery is retried on the next run. If the host was offline across several boundaries, only the current phase is announced. The host runs Python 3.12 while the development environment uses Python 3.13. Create a separate host virtualenv so systemd does not follow a symlink to a Python executable absent from the host: ```sh cd /home/jorenmartijn/django python3 -m venv tasksnest-host tasksnest-host/bin/python -m pip install -r main/requirements.txt tasksnest-host/bin/python main/manage.py check ``` Install the provided systemd service and timer to run this check every minute: ```sh sudo cp main/deploy/systemd/tasknest-fasting-notifications.{service,timer} /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now tasknest-fasting-notifications.timer ``` Home Assistant grocery and task syncing use a separate timer. After deploying the app, install `deploy/systemd/tasknest-home-assistant-sync.service` and `deploy/systemd/tasknest-home-assistant-sync.timer` the same way. The command checks due connections every minute; users must enable an interval in settings: ```sh sudo cp main/deploy/systemd/tasknest-home-assistant-sync.{service,timer} /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable --now tasknest-home-assistant-sync.timer ``` Run database migrations before enabling the timer. Adjust the service's user and paths for your deployment. ## Gitea activity widget The main task page shows a contribution grid below Daily Workout when `GITEA_USERNAME` is set in the Django server process environment. It uses Gitea's `/api/v1/users/{username}/heatmap` endpoint, refreshes the server-side cache every 15 minutes, and keeps any token out of browser requests. Put these values in `/home/jorenmartijn/django/.env`, then restart the service that runs Django. Values set directly in the service environment take priority: ```ini GITEA_USERNAME=your-gitea-username GITEA_BASE_URL=https://git.jorendegraaf.eu # Only if the public heatmap endpoint does not show the activity you want: GITEA_TOKEN=your-read-only-token ``` The base URL already defaults to `https://git.jorendegraaf.eu`. For public activity, try without a token first. If Gitea requires authentication or you want activity visible only to your account, create a token in Gitea's **User Settings → Applications → Generate New Token** with `read:user` permission. Store it in the Django service environment, never in this repository or in browser JavaScript. The dashboard shows a short unavailable message if the endpoint cannot be reached.