# Agent-safe local development and `spin`

`dev` (source checkout) and `spin` (installed / uvx) share the lifecycle manager.
It identifies instances by canonical checkout path (`dev`) or data directory
(`spin`). Calling the entry point twice **does not** restart a healthy stack.

```sh
uv run manage.py dev                 # start/reuse Django, Hatchet, worker, Caddy, Open WebUI
uv run manage.py dev status          # owner, health and allocated public port
uv run manage.py dev agent-info      # exhaustive instructions for agents
uv run manage.py dev down            # graceful shutdown; preserve data
uv run manage.py dev restart         # intentional full restart
uv run manage.py dev reset           # destructive; reseed and start
uv run manage.py dev uninstall       # remove owned data + scoped uv caches

uvx --from simpleaudit-studio spin status
uvx --from simpleaudit-studio spin agent-info
uvx --from simpleaudit-studio spin down
uvx --from simpleaudit-studio spin reset
uvx --from simpleaudit-studio spin uninstall
```

`reset` and `uninstall` confirm interactively; use `--yes` for explicitly
authorized noninteractive runs. `uninstall` removes managed Open WebUI state,
embedded Hatchet data, local databases, and package-scoped `uv` wheel caches.
It does **not** remove source, external result folders, shared Postgres, unrelated
uv artifacts, system Python, or a source checkout's `.venv`. `uvx` may retain
shared cached environments that cannot be safely identified by package.

## Parallel worktrees

A linked Git worktree gets isolated ports, chat storage, embedded Hatchet
PostgreSQL and Django SQLite by default. The instance manager allocates ports
before Django settings or migration start. To find the actual URL, use `status`;
never assume port 8000. The public `--port` flag also configures Caddy's public
listener, Django internal port, and the Open WebUI upstream.

Data layout:

- `dev`: checkout's `dev.sqlite3`; other services under
  `~/.local/state/simpleaudit-studio/data/dev-<hash>/`
- `spin`: `~/.simpleaudit-studio/` (compatible with existing installations)
- Registry: `${XDG_STATE_HOME:-~/.local/state}/simpleaudit-studio/instances/`

The manager refuses to destructively delete custom `SIMPLEAUDIT_DATA_DIR` or
`SIMPLEAUDIT_SQLITE_PATH` locations and never kills a PID merely because it
happens to use a preferred port. A second process sharing the same data dir is
rejected while another registered owner is alive.

## Reload behavior and agent policy

Django's existing `runserver` child autoreloads Python code. Edited Django
templates are read again on refresh; the browser is not automatically refreshed
without a separate browser-reload integration. **The embedded Hatchet worker
currently remains inside the owning parent process and is not automatically
reloaded**. Changes to worker code require a planned restart, preferably while
no audits are running. Do not pretend a Django reload updates the worker.

Always check `dev agent-info`/`spin agent-info` and `status` before attempting to
start, restart, reset, or uninstall. Never manually kill a port holder, change a
running instance's persistent data, or restart an unrelated worktree. `reset`
and `uninstall` require the user to authorize potential data loss.

## Scope and caveats

This manager supervises the **existing single-process embedded stack**; it does
not magically turn Hatchet's worker into an independently hot-reloadable process
or enable shared PostgreSQL for `dev`. Shared-database/multi-instance scenarios
need a separate Postgres-backed development mode and migration coordination.

`devctl.sh` is kept as a compatibility wrapper and must not use its former
`kill -9`/`pgrep` port-based cleanup. Running `uvx` itself may download the CLI
package again before an `uninstall` subcommand is processed; uninstalling a
uv-managed permanent tool is a distinct operation handled only if it exists.