feat(ops): a sourceable wrapper so docker is nobody's problem

source ops/shell/ousast.sh     # bash / zsh
    . ops\shell\ousast.ps1         # powershell

    ousast scan .
    ousast scan src/api

The container becomes an implementation detail. The engine is a JVM and ~2 GB
of Joern, and a contributor evaluating this tool should not have to install
either to try it -- what they get is a command.

Path rewriting is what makes it feel local: arguments under the working
directory are mapped to their mounted equivalents, so `src/api` means what the
user expects. Anything outside the mount is passed through unchanged WITH A
WARNING rather than silently rewritten into a path the container cannot see --
a wrong path that looks like it worked is worse than one that complains.

A native install wins when it is present. Someone who installed Joern
deliberately should not be quietly routed through a container, so the wrapper
uses a local joern-parse and venv when both exist; OUSAST_PREFER_NATIVE=0
forces the container. Verified end to end from an unrelated directory.

The image builds itself on first use and says why it is pausing. A first run
that prints a wall of build output and then works is worse than one that
explains itself.

Defaults stay conservative: the working directory mounts READ-ONLY, findings go
to ./.ousast as the only writable mount, and the network is off unless
`ousast-with-judge` asks for it.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Claude-Session: https://claude.ai/code/session_01T7XD7x5KonMdmGRkp63EQG

ops/README.md

@@ -3,6 +3,37 @@
 Infrastructure for the optional engines. Nothing here is a project dependency: the core install is
 `dependencies = []` and every engine below degrades to a recorded reason when it is absent.
 
+## Use it as a command
+
+Source the wrapper once and Docker stops being something you think about:
+
+```bash
+# ~/.bashrc or ~/.zshrc
+source /path/to/OpenUltraSAST/ops/shell/ousast.sh
+```
+
+```powershell
+# $PROFILE
+. C:\path\to\OpenUltraSAST\ops\shell\ousast.ps1
+```
+
+Then, from any directory:
+
+```bash
+ousast scan .
+ousast scan src/api
+ousast-with-judge scan .     # opt into the LLM judge: needs network and a key
+```
+
+The wrapper rewrites paths under your working directory to their mounted equivalents, so `src/api` means what
+you expect. Anything outside the mount is passed through unchanged with a warning rather than silently
+rewritten into a path the container cannot see. Your directory is mounted **read-only**; findings go to
+`./.ousast`, the one writable mount. The image builds itself on first use and says so.
+
+If `joern-parse` is already on your PATH and a local venv exists, the wrapper uses those instead — someone who
+installed the engine deliberately should not be quietly routed through a container. Set
+`OUSAST_PREFER_NATIVE=0` to always containerise.
+
 ## Two ways to get the engine
 
 **Docker (recommended for contributors).** The tool and Joern ship in one image, so nothing is installed on