Merge branch 'docs/direnv-project-tools'

ai/backend-context.md

@@ -92,7 +92,8 @@ pattern.
 - Rebuild the development database with:
 
   ```sh
-  php artisan migrate:fresh --seed
+  direnv exec "$(git rev-parse --show-toplevel)" \
+    php artisan migrate:fresh --seed
   ```
 
 - Once a production database exists, replace this policy with additive,
@@ -101,7 +102,12 @@ pattern.
 ## Before completing backend work
 
 - Run the focused test during development.
-- Run `php artisan test` before completion.
+- Run the full test suite before completion:
+
+  ```sh
+  direnv exec "$(git rev-parse --show-toplevel)" php artisan test
+  ```
+
 - Run the Composer static-analysis scripts.
 - Fix failures caused by the change. Report unrelated baseline failures
   precisely rather than hiding them or expanding scope without authorization.

ai/frontend-context.md

@@ -33,13 +33,14 @@ Use npm and keep `package-lock.json` committed. Run commands from
 Install dependencies in a fresh checkout or worktree:
 
 ```sh
-npm install
+direnv exec "$(git rev-parse --show-toplevel)" npm install
 ```
 
 Start the development server on the port assigned by the shell hook:
 
 ```sh
-npm run dev -- --port "$VITE_PORT"
+direnv exec "$(git rev-parse --show-toplevel)" \
+  npm run dev -- --port "$VITE_PORT"
 ```
 
 `process-compose` does not start or proxy the frontend.
@@ -47,10 +48,10 @@ npm run dev -- --port "$VITE_PORT"
 The available validation commands are:
 
 ```sh
-npm run format
-npm run lint
-npm run type-check
-npm run build
+direnv exec "$(git rev-parse --show-toplevel)" npm run format
+direnv exec "$(git rev-parse --show-toplevel)" npm run lint
+direnv exec "$(git rev-parse --show-toplevel)" npm run type-check
+direnv exec "$(git rev-parse --show-toplevel)" npm run build
 ```
 
 `npm run format` and `npm run lint` rewrite files. Review the resulting diff.

ai/shared.md

@@ -45,28 +45,43 @@ those changes with the most relevant parser, formatter, dry run, or check.
   is the user's stack. Do not start, restart, or stop it unless the user asks.
 - A worktree owns its own isolated stack. The flake shell hook assigns a
   deterministic port offset and creates worktree-local PostgreSQL state.
-- Start a worktree stack from its root with `process-compose up`. For
-  non-interactive use, run `process-compose up -D` and stop it with
-  `process-compose down`.
+- Start a worktree stack from its root. For non-interactive use, start it
+  detached and stop it when finished, as shown below.
 - Do not use `process-compose -t=false` for a detached stack. It can leave an
   orphaned PostgreSQL process holding the data directory.
-- Non-interactive agent shells do not automatically load direnv. A bare
-  `process-compose`, `php artisan`, or database command from a worktree can
-  silently use default ports and target the main checkout.
-- Prefix worktree stack and database commands with `direnv exec <worktree>`.
-  Examples:
+- Non-interactive agent shells do not automatically load direnv. Bare project
+  commands can use missing tools, default ports, or paths from the main
+  checkout.
+- Run project tooling that depends on the repository development environment
+  through direnv. This includes PHP, Composer, Artisan, npm, tests, builds,
+  database clients, and services.
+- Resolve the direnv target from the worktree containing the agent's current
+  working directory. Never target the main checkout or a different worktree:
 
   ```sh
-  direnv exec <worktree> process-compose up -D
-  direnv exec <worktree> process-compose down
-  direnv exec <worktree> php artisan migrate:fresh --seed
+  direnv exec "$(git rev-parse --show-toplevel)" <command>
+  ```
+
+- Git and environment-neutral read-only file inspection do not need the
+  direnv wrapper.
+- Worktree stack examples:
+
+  ```sh
+  direnv exec "$(git rev-parse --show-toplevel)" process-compose up -D
+  direnv exec "$(git rev-parse --show-toplevel)" process-compose down
   ```
 
 - Run backend commands from `backend/`, or explicitly change into it in the
-  command.
+  command. The direnv target remains the worktree root.
 - Run frontend commands from `frontend/website/`.
 - `process-compose` does not start the frontend. Start it separately with
-  `npm run dev -- --port "$VITE_PORT"` when needed.
+  the worktree's assigned port when needed:
+
+  ```sh
+  direnv exec "$(git rev-parse --show-toplevel)" \
+    npm run dev -- --port "$VITE_PORT"
+  ```
+
 - When a normally valid check fails because a required service is down,
   surface the environmental failure. Do not skip the check or silently switch
   to a different database or service.
@@ -143,8 +158,11 @@ those changes with the most relevant parser, formatter, dry run, or check.
   another checkout. Dependency paths and generated files must remain
   worktree-local.
 - The shell hook installs backend dependencies but does not install frontend
-  dependencies. Run `npm install` from `frontend/website/` when provisioning a
-  fresh worktree.
+  dependencies. From `frontend/website/`, provision them with:
+
+  ```sh
+  direnv exec "$(git rev-parse --show-toplevel)" npm install
+  ```
 
 Do not push anything. Make commits as the TDD workflow requires.
 
@@ -155,12 +173,17 @@ gate affected by the change.
 
 ### Backend
 
-- Run tests from `backend/` with `php artisan test`.
+- Run tests from `backend/`:
+
+  ```sh
+  direnv exec "$(git rev-parse --show-toplevel)" php artisan test
+  ```
+
 - Run the Composer checks defined by `backend/composer.json`:
 
   ```sh
-  composer types:check
-  composer test
+  direnv exec "$(git rev-parse --show-toplevel)" composer types:check
+  direnv exec "$(git rev-parse --show-toplevel)" composer test
   ```
 
 - Do not claim a green gate when a command fails. If the failure predates the
@@ -171,10 +194,10 @@ gate affected by the change.
 - Run these commands from `frontend/website/`:
 
   ```sh
-  npm run format
-  npm run lint
-  npm run type-check
-  npm run build
+  direnv exec "$(git rev-parse --show-toplevel)" npm run format
+  direnv exec "$(git rev-parse --show-toplevel)" npm run lint
+  direnv exec "$(git rev-parse --show-toplevel)" npm run type-check
+  direnv exec "$(git rev-parse --show-toplevel)" npm run build
   ```
 
 - The formatter and linters rewrite files. Review their changes before
@@ -184,8 +207,20 @@ gate affected by the change.
 
 ### Environment and integration
 
-- For Nix or shell-hook changes, run `nix fmt` and `nix flake check`.
-- For service configuration changes, run `process-compose --dry-run`.
+- For Nix or shell-hook changes, run:
+
+  ```sh
+  direnv exec "$(git rev-parse --show-toplevel)" nix fmt
+  direnv exec "$(git rev-parse --show-toplevel)" nix flake check
+  ```
+
+- For service configuration changes, run:
+
+  ```sh
+  direnv exec "$(git rev-parse --show-toplevel)" \
+    process-compose --dry-run
+  ```
+
 - When a change affects runtime wiring, start the worktree's stack and verify
   the relevant endpoint or service against that worktree.
 - If you started the stack only for validation, stop it before finishing.