cleanup

AGENTS.md

@@ -115,21 +115,39 @@ need database state use the embedded Turso engine.
 - **ISAC namespace**: `/isac` is the admin console; `/admin` redirects there
   via 308.
 
+## Long-running development processes
+
+Use the installed `pi-background-tasks` extension's `bg_run` tool for
+development servers, watchers, and other persistent commands. Do not use
+foreground shell sessions, `nohup`, `&`, or process-tree/PID discovery when a
+tracked task exists.
+
+- Use `isAgent: false` and a concise, descriptive task name.
+- Retain the returned task ID and output path. Inspect a task with `bg_status`
+  and read its output with `bg_logs`.
+- Stop a task with `bg_kill <task-id>`. To restart it, start a new `bg_run` task
+  and retain its new task ID and output path; do not search for and kill
+  processes.
+- Do not leave duplicate tracked tasks for the same development service.
+
 ## Development server lifecycle
 
 After changing source code, styles, configuration, dependencies, or routes,
 restart the development server before handing work back.
 
-1. Inspect running processes and stop only this project's development-server
-   process tree.
-2. Start one hidden `npm run dev` process from the repository root. Do not leave
-   duplicate project development servers running.
-3. Confirm the server accepts an HTTP request before completing the task.
-4. Leave the verified development server running so the project owner can review
-   the changes.
+1. Start `npm run dev` from the repository root with `bg_run`, using
+   `isAgent: false` and a descriptive task name. Retain its task ID and output
+   path.
+2. Before starting a replacement, stop the existing tracked development-server
+   task with `bg_kill <task-id>` so only one server runs.
+3. Confirm the task logs show the server started, then confirm it accepts an
+   HTTP request before completing the task.
+4. Leave the verified tracked task running so the project owner can review the
+   changes.
 
 Database maintenance may require the server to remain stopped while the embedded
-database is locked. Restart and verify the server after maintenance completes.
+database is locked. Stop its tracked task first, then restart and verify it
+after maintenance completes.
 
 ## SHD design-system maintenance
 
@@ -245,7 +263,7 @@ database. The command refuses to merge into a populated database.
 
 ## Development database maintenance
 
-1. Stop only this project's development-server process tree.
+1. Stop this project's tracked development-server task with `bg_kill <task-id>`.
 2. Run and verify `npm run db:backup`. Retain and report the backup path.
 3. Apply the migration or maintenance operation. Verify schema state, record
    counts, and critical entities.