pulseml 0.4.2__tar.gz → 0.4.3__tar.gz

{pulseml-0.4.2/src/pulseml.egg-info → pulseml-0.4.3}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: pulseml
-Version: 0.4.2
+Version: 0.4.3
 Summary: A live ML training debugger for tracking, diagnosing, verifying, and patching training runs.
 Author-email: Yash Patel <codeyash09@gmail.com>
 License: Proprietary
-Project-URL: Homepage, https://pulsedb.netlify.app/
+Project-URL: Homepage, https://residualml.com/
 Project-URL: Repository, https://github.com/codeyash09/PulseML
 Project-URL: Issues, https://github.com/codeyash09/PulseML/issues
-Project-URL: Documentation, https://pulsedb.netlify.app/
+Project-URL: Documentation, https://residualml.com/docs
 Keywords: machine-learning,deep-learning,debugging,ml-debugging,training,pytorch,tensorflow,numpy,cupy,jax,gradients,training-debugger
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -69,35 +69,8 @@ dependencies separate from other projects.
 - An AI provider is optional for monitoring. Pulse's AI agent setup can sign you in with
   OpenRouter or use a provider API key.
 
-### 1. Create and activate an environment
 
-Run these commands from your project directory.
-
-**Windows — PowerShell:**
-
-```powershell
-py -3 -m venv .venv
-.\.venv\Scripts\Activate.ps1
-```
-
-If PowerShell activation is blocked by your execution policy, use Command Prompt instead:
-
-```bat
-py -3 -m venv .venv
-.venv\Scripts\activate.bat
-```
-
-Or skip activation and use `.venv\Scripts\python.exe` in place of `python` in the
-remaining commands.
-
-**macOS / Linux:**
-
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-```
-
-### 2. Install Pulse
+### 1. Install Pulse
 
 With the environment activated:
 
@@ -110,33 +83,23 @@ Using `python -m pip` ensures Pulse is installed for the Python interpreter sele
 the active environment. If you already have a project environment, activate it and run
 the second command there instead of creating a new one.
 
-### 3. Verify and launch
+### 2. Verify and launch
 
 ```text
-pulse --version
-pulse --help
+python -m pulse --version
+python -m pulse --help
 ```
 
-Use the same `pulse` command on Windows, macOS, and Linux. If the command is not found,
-activate the environment where you installed Pulse, or add that environment's Scripts
-(Windows) or bin (macOS/Linux) directory to `PATH`.
-
-Start Pulse:
-
-```text
-pulse
-```
+`python -m pulse` works on Windows, macOS, and Linux, including when the environment's
+Scripts directory is not on `PATH`. When the environment is activated, the shorter
+`pulse` command is available too.
 
-Pulse opens its app. In the app, ask the agent to run your training script, for example:
+To open Pulse, run:
 
 ```text
-Run train.py
+python -m pulse
 ```
 
-Replace `train.py` with your script path and include any script arguments in your request.
-Pulse starts it with the active environment's Python; no source-code edits are needed.
-This is the normal workflow for both single-GPU and distributed runs.
-
 ### AI provider configuration
 
 Pulse supports cloud and local AI providers.
@@ -146,13 +109,9 @@ Pulse supports cloud and local AI providers.
 OpenRouter serves every major model behind one account and has free models. Pulse can get
 a key for you:
 
-```bash
-pulse openrouter            # sign in, or create an account, in your browser
-```
-
-or just press Enter at any API key question. Pulse asks for a key during app setup and
-when you switch agents, and every one of those offers sign-in: for an OpenRouter model
-Enter starts it directly, and for any other provider Enter
+or just press Enter at any API key question. Pulse asks for a key in `pulse run`,
+`pulse code` and when you switch agents, and every one of those offers the
+sign-in: for an OpenRouter model Enter starts it directly, and for any other provider Enter
 offers to sign you in and switch to an OpenRouter model. The dashboard asks the same thing
 in a dialog, and `pulse --model openrouter/<model>` offers it when there is no key.
 Your browser opens on OpenRouter; sign in or sign up, click Authorize, and Pulse receives
@@ -260,20 +219,7 @@ pulse_monitor.Monitor      ---stream--->  pulse_brain.Brain
   never blocks, never thinks                thinks as long as it likes
 ```
 
-Start Pulse with `pulse`, then ask its agent to run your script; no source changes are needed.
-
-```text
-pulse
-```
-
-The app launches runs with background streaming, so training does not wait for the
-agent. To open a stream brain explicitly:
-
-```text
-python -m pulse.brain                      # newest session
-python -m pulse.brain <session-dir> --model openrouter/deepseek/deepseek-v4.1-flash
-python -m pulse.brain <session-dir> --once # one pass over a finished run
-```
+Start the script through Pulse; no source changes are needed:
 
 ### What the training process pays
 
@@ -594,14 +540,14 @@ rewrite git state, reach outside the project, start a background process or over
 file. So that a long run never stops to wait for you, a model answers that y/N. By default
 it is the agent's own model, asked separately: it sees only the command, why it was
 flagged, the project folder and what the agent was working on -- never the agent's
-reasoning -- so it judges the command on its own. To use a different model, set `PULSE_APPROVER=<model>` before starting Pulse (or set
-`"approver": "<model>"` in `pulse_config.json`):
+reasoning -- so it judges the command on its own. To use a different model:
 
 ```bash
-PULSE_APPROVER=openrouter/anthropic/claude-sonnet-5 pulse
+pulse run --approver openrouter/anthropic/claude-sonnet-5 train.py
 ```
 
-(To be asked yourself instead, set `"approver": "off"`.) The same commands
+(or `PULSE_APPROVER=<model>`, or `"approver": "<model>"` in `pulse_config.json`). To be
+asked yourself instead, use `--approver off` (or `"approver": "off"`). The same commands
 are flagged either way; only who answers changes. The reviewer answers the other question
 the agent otherwise stops for, too -- "apply this change?" for each edit it proposes --
 judging the diff against your request; every applied change stays one `/undo` away. The approver answers APPROVE or DENY
@@ -674,40 +620,45 @@ Commands on an open run: `/findings`, `/curve <name>`, `/vars`, `/audit`, `/audi
 watching). Everywhere: `/monitor`, `/run`, `/agent`, `/files`, `/add`, `/drop`, `/review`,
 `/undo`, `/log`, `/cloud`, `/help`, `/exit`.
 
-A run opened in the app -- started by asking the agent, picked with `/monitor`, or attached
-from outside -- gets its own session on the web dashboard: its environment, metric
-snapshots, the detectors' findings and crashes as incidents,
+A run opened in the app -- started with `/run`, picked with `/monitor`, or attached from
+outside -- gets its own session on the web dashboard, as a run started with `pulse run`
+does: its environment, metric snapshots, the detectors' findings and crashes as incidents,
 the agent's turns about it, and its uptime, synced in the background while it is watched.
 
 The agent can start, watch, restart and stop runs itself: "run it", "start training with
 --epochs 3", "restart it with the fix" are requests it carries out with its `start_run`,
 `run_status`, `restart_run` and `stop_run` tools (stopping asks you first). A request typed
-at a paused training run is likewise handled as what it is -- a question gets an answer,
-a change you asked for gets made -- instead of being read as a bug report to diagnose.
+at a paused `pulse run` is likewise handled as what it is -- a question gets an answer, a
+change you asked for gets made -- instead of being read as a bug report to diagnose.
 
 `pulse watch <run>`, `pulse <script.py>` and `pulse attach --pid N` open the same app
 directly on that run. On Windows it needs a console that understands escape sequences
 (Windows Terminal, or the console of Windows 10 and later). Without a real terminal (a
 pipe, CI), on a very small one, or with `PULSE_CLASSIC=1`, Pulse keeps the line-by-line
 screens described below. `PULSE_STREAMING=0` turns off the streaming of the model's
-replies.
+replies. `pulse run train.py` -- training with Pulse inside the script's own terminal --
+is unchanged.
 
 ---
 
 ## The `pulse` command
 
-For the normal workflow, the only command you need to enter in a terminal is `pulse`.
-Pulse does not have to be written into a script. Once the app opens, ask the agent to run
-your script or choose an existing run to monitor.
+Pulse does not have to be written into a script. Installing it puts a `pulse` command on
+the path, which starts runs and attaches to ones already going.
 
 ```bash
-pulse
+pulse run --stream train.py      # start train.py under Pulse, unmodified
+pulse                            # the app; without a terminal, attach to the run on this machine
+pulse train.py                   # attach to the run of that script
+pulse sessions                   # list the runs Pulse knows about
 ```
 
-In the app, ask the agent something like `Run train.py`. Pulse launches the script with
-background monitoring, so training continues while the agent investigates. No source
-changes are needed. This works the same way for a normal single-GPU run; multi-GPU
-instrumentation is enabled automatically when Pulse detects multiple ranks.
+`pulse run` starts a run; without it, a script name means the run that is **already
+going**. If several runs match, Pulse lists them and asks which.
+
+`--stream` puts the monitor in the training process and the agent in yours, so the run
+keeps going whether or not anyone is watching it, and attaching costs the run nothing.
+Without it the run is tracked in the terminal it was started from, as before.
 
 ### Watching a run you did not start under Pulse
 
@@ -723,7 +674,7 @@ sudo pulse attach --pid 12345    # when you already know the id
 Two limits are worth knowing before relying on it. It reads **function locals**, so a
 loop written at the top level of a script reports nothing — the values are module
 globals, which cannot be read this way. And it **samples**, about once a second, so a
-spike between two samples is not seen. A run launched from the Pulse app has neither
+spike between two samples is not seen. A run started under `pulse run` has neither
 problem, because Pulse is inside it.
 
 If `sudo pulse` says `command not found`, sudo is the reason: it replaces `PATH` with its
@@ -771,33 +722,21 @@ Pulse can pause training for investigation, allowing you to inspect the current
 
 ## Quickstart
 
-Start Pulse:
+Start an existing training script under Pulse without editing it:
 
 ```text
-pulse
+python -m pulse run train.py
 ```
 
-In the app, ask the agent to run your script, for example `Run train.py`. Pulse launches
-it with the active Python environment and instruments it in memory; your source files
-are not modified. Use the same workflow for a single-GPU run or a distributed run.
-
-### Distributed PyTorch (DDP and FSDP)
+To keep training independent of the viewer and watch the run from another terminal, use:
 
-When you ask Pulse's app agent to run a script, Pulse recognizes the common
-`torch.multiprocessing.spawn(worker, ..., nprocs=...)` pattern when `worker` is a
-top-level function and `nprocs` is an integer literal or variable name. Pulse instruments
-each spawned worker in memory, so the training script still needs no Pulse-specific code
-changes. The app launches runs in background-streaming mode; each worker is monitored in
-its own stream session rather than as one consolidated rank-0 view. The underlying model
-inspection recognizes DDP replicas and rank-local FSDP/DTensor shards.
+```text
+python -m pulse run --stream train.py
+```
 
-DDP-wrapped models are inspected through their underlying replicated model. For FSDP,
-model descriptions distinguish global DTensor shapes from local shard shapes, and
-`LAYERSTATS` reports the parameter view available on the current rank. Pulse does not
-all-gather FSDP parameters or gradients just to inspect them; these statistics are
-rank-local and are not presented as full-model norms. `SHAPETRACE`, `GRADCHECK`, and
-`REPLAY` are guarded where a rank-0-only operation could otherwise hang or desynchronize
-the distributed job.
+Pulse launches the script with its existing source code and exposes the run through its
+app and CLI. It instruments the script in memory; your files are not modified. Replace
+`train.py` with your script path and put any script arguments after it.
 
 You can then control tracking while the run is active:
 
@@ -878,7 +817,7 @@ LESS OVERHEAD
 
 Rather than collecting everything continuously, Pulse lets you decide what information is worth monitoring.
 
-Measured on a 20k-step loop started from Pulse's app with background streaming:
+Measured on a 20k-step loop started with `pulse run --stream`:
 
 | Work on the training thread | single process | stream mode |
 |---|---:|---:|

{pulseml-0.4.2 → pulseml-0.4.3}/README.md

@@ -24,35 +24,8 @@ dependencies separate from other projects.
 - An AI provider is optional for monitoring. Pulse's AI agent setup can sign you in with
   OpenRouter or use a provider API key.
 
-### 1. Create and activate an environment
 
-Run these commands from your project directory.
-
-**Windows — PowerShell:**
-
-```powershell
-py -3 -m venv .venv
-.\.venv\Scripts\Activate.ps1
-```
-
-If PowerShell activation is blocked by your execution policy, use Command Prompt instead:
-
-```bat
-py -3 -m venv .venv
-.venv\Scripts\activate.bat
-```
-
-Or skip activation and use `.venv\Scripts\python.exe` in place of `python` in the
-remaining commands.
-
-**macOS / Linux:**
-
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-```
-
-### 2. Install Pulse
+### 1. Install Pulse
 
 With the environment activated:
 
@@ -65,33 +38,23 @@ Using `python -m pip` ensures Pulse is installed for the Python interpreter sele
 the active environment. If you already have a project environment, activate it and run
 the second command there instead of creating a new one.
 
-### 3. Verify and launch
+### 2. Verify and launch
 
 ```text
-pulse --version
-pulse --help
+python -m pulse --version
+python -m pulse --help
 ```
 
-Use the same `pulse` command on Windows, macOS, and Linux. If the command is not found,
-activate the environment where you installed Pulse, or add that environment's Scripts
-(Windows) or bin (macOS/Linux) directory to `PATH`.
-
-Start Pulse:
-
-```text
-pulse
-```
+`python -m pulse` works on Windows, macOS, and Linux, including when the environment's
+Scripts directory is not on `PATH`. When the environment is activated, the shorter
+`pulse` command is available too.
 
-Pulse opens its app. In the app, ask the agent to run your training script, for example:
+To open Pulse, run:
 
 ```text
-Run train.py
+python -m pulse
 ```
 
-Replace `train.py` with your script path and include any script arguments in your request.
-Pulse starts it with the active environment's Python; no source-code edits are needed.
-This is the normal workflow for both single-GPU and distributed runs.
-
 ### AI provider configuration
 
 Pulse supports cloud and local AI providers.
@@ -101,13 +64,9 @@ Pulse supports cloud and local AI providers.
 OpenRouter serves every major model behind one account and has free models. Pulse can get
 a key for you:
 
-```bash
-pulse openrouter            # sign in, or create an account, in your browser
-```
-
-or just press Enter at any API key question. Pulse asks for a key during app setup and
-when you switch agents, and every one of those offers sign-in: for an OpenRouter model
-Enter starts it directly, and for any other provider Enter
+or just press Enter at any API key question. Pulse asks for a key in `pulse run`,
+`pulse code` and when you switch agents, and every one of those offers the
+sign-in: for an OpenRouter model Enter starts it directly, and for any other provider Enter
 offers to sign you in and switch to an OpenRouter model. The dashboard asks the same thing
 in a dialog, and `pulse --model openrouter/<model>` offers it when there is no key.
 Your browser opens on OpenRouter; sign in or sign up, click Authorize, and Pulse receives
@@ -215,20 +174,7 @@ pulse_monitor.Monitor      ---stream--->  pulse_brain.Brain
   never blocks, never thinks                thinks as long as it likes
 ```
 
-Start Pulse with `pulse`, then ask its agent to run your script; no source changes are needed.
-
-```text
-pulse
-```
-
-The app launches runs with background streaming, so training does not wait for the
-agent. To open a stream brain explicitly:
-
-```text
-python -m pulse.brain                      # newest session
-python -m pulse.brain <session-dir> --model openrouter/deepseek/deepseek-v4.1-flash
-python -m pulse.brain <session-dir> --once # one pass over a finished run
-```
+Start the script through Pulse; no source changes are needed:
 
 ### What the training process pays
 
@@ -549,14 +495,14 @@ rewrite git state, reach outside the project, start a background process or over
 file. So that a long run never stops to wait for you, a model answers that y/N. By default
 it is the agent's own model, asked separately: it sees only the command, why it was
 flagged, the project folder and what the agent was working on -- never the agent's
-reasoning -- so it judges the command on its own. To use a different model, set `PULSE_APPROVER=<model>` before starting Pulse (or set
-`"approver": "<model>"` in `pulse_config.json`):
+reasoning -- so it judges the command on its own. To use a different model:
 
 ```bash
-PULSE_APPROVER=openrouter/anthropic/claude-sonnet-5 pulse
+pulse run --approver openrouter/anthropic/claude-sonnet-5 train.py
 ```
 
-(To be asked yourself instead, set `"approver": "off"`.) The same commands
+(or `PULSE_APPROVER=<model>`, or `"approver": "<model>"` in `pulse_config.json`). To be
+asked yourself instead, use `--approver off` (or `"approver": "off"`). The same commands
 are flagged either way; only who answers changes. The reviewer answers the other question
 the agent otherwise stops for, too -- "apply this change?" for each edit it proposes --
 judging the diff against your request; every applied change stays one `/undo` away. The approver answers APPROVE or DENY
@@ -629,40 +575,45 @@ Commands on an open run: `/findings`, `/curve <name>`, `/vars`, `/audit`, `/audi
 watching). Everywhere: `/monitor`, `/run`, `/agent`, `/files`, `/add`, `/drop`, `/review`,
 `/undo`, `/log`, `/cloud`, `/help`, `/exit`.
 
-A run opened in the app -- started by asking the agent, picked with `/monitor`, or attached
-from outside -- gets its own session on the web dashboard: its environment, metric
-snapshots, the detectors' findings and crashes as incidents,
+A run opened in the app -- started with `/run`, picked with `/monitor`, or attached from
+outside -- gets its own session on the web dashboard, as a run started with `pulse run`
+does: its environment, metric snapshots, the detectors' findings and crashes as incidents,
 the agent's turns about it, and its uptime, synced in the background while it is watched.
 
 The agent can start, watch, restart and stop runs itself: "run it", "start training with
 --epochs 3", "restart it with the fix" are requests it carries out with its `start_run`,
 `run_status`, `restart_run` and `stop_run` tools (stopping asks you first). A request typed
-at a paused training run is likewise handled as what it is -- a question gets an answer,
-a change you asked for gets made -- instead of being read as a bug report to diagnose.
+at a paused `pulse run` is likewise handled as what it is -- a question gets an answer, a
+change you asked for gets made -- instead of being read as a bug report to diagnose.
 
 `pulse watch <run>`, `pulse <script.py>` and `pulse attach --pid N` open the same app
 directly on that run. On Windows it needs a console that understands escape sequences
 (Windows Terminal, or the console of Windows 10 and later). Without a real terminal (a
 pipe, CI), on a very small one, or with `PULSE_CLASSIC=1`, Pulse keeps the line-by-line
 screens described below. `PULSE_STREAMING=0` turns off the streaming of the model's
-replies.
+replies. `pulse run train.py` -- training with Pulse inside the script's own terminal --
+is unchanged.
 
 ---
 
 ## The `pulse` command
 
-For the normal workflow, the only command you need to enter in a terminal is `pulse`.
-Pulse does not have to be written into a script. Once the app opens, ask the agent to run
-your script or choose an existing run to monitor.
+Pulse does not have to be written into a script. Installing it puts a `pulse` command on
+the path, which starts runs and attaches to ones already going.
 
 ```bash
-pulse
+pulse run --stream train.py      # start train.py under Pulse, unmodified
+pulse                            # the app; without a terminal, attach to the run on this machine
+pulse train.py                   # attach to the run of that script
+pulse sessions                   # list the runs Pulse knows about
 ```
 
-In the app, ask the agent something like `Run train.py`. Pulse launches the script with
-background monitoring, so training continues while the agent investigates. No source
-changes are needed. This works the same way for a normal single-GPU run; multi-GPU
-instrumentation is enabled automatically when Pulse detects multiple ranks.
+`pulse run` starts a run; without it, a script name means the run that is **already
+going**. If several runs match, Pulse lists them and asks which.
+
+`--stream` puts the monitor in the training process and the agent in yours, so the run
+keeps going whether or not anyone is watching it, and attaching costs the run nothing.
+Without it the run is tracked in the terminal it was started from, as before.
 
 ### Watching a run you did not start under Pulse
 
@@ -678,7 +629,7 @@ sudo pulse attach --pid 12345    # when you already know the id
 Two limits are worth knowing before relying on it. It reads **function locals**, so a
 loop written at the top level of a script reports nothing — the values are module
 globals, which cannot be read this way. And it **samples**, about once a second, so a
-spike between two samples is not seen. A run launched from the Pulse app has neither
+spike between two samples is not seen. A run started under `pulse run` has neither
 problem, because Pulse is inside it.
 
 If `sudo pulse` says `command not found`, sudo is the reason: it replaces `PATH` with its
@@ -726,33 +677,21 @@ Pulse can pause training for investigation, allowing you to inspect the current
 
 ## Quickstart
 
-Start Pulse:
+Start an existing training script under Pulse without editing it:
 
 ```text
-pulse
+python -m pulse run train.py
 ```
 
-In the app, ask the agent to run your script, for example `Run train.py`. Pulse launches
-it with the active Python environment and instruments it in memory; your source files
-are not modified. Use the same workflow for a single-GPU run or a distributed run.
-
-### Distributed PyTorch (DDP and FSDP)
+To keep training independent of the viewer and watch the run from another terminal, use:
 
-When you ask Pulse's app agent to run a script, Pulse recognizes the common
-`torch.multiprocessing.spawn(worker, ..., nprocs=...)` pattern when `worker` is a
-top-level function and `nprocs` is an integer literal or variable name. Pulse instruments
-each spawned worker in memory, so the training script still needs no Pulse-specific code
-changes. The app launches runs in background-streaming mode; each worker is monitored in
-its own stream session rather than as one consolidated rank-0 view. The underlying model
-inspection recognizes DDP replicas and rank-local FSDP/DTensor shards.
+```text
+python -m pulse run --stream train.py
+```
 
-DDP-wrapped models are inspected through their underlying replicated model. For FSDP,
-model descriptions distinguish global DTensor shapes from local shard shapes, and
-`LAYERSTATS` reports the parameter view available on the current rank. Pulse does not
-all-gather FSDP parameters or gradients just to inspect them; these statistics are
-rank-local and are not presented as full-model norms. `SHAPETRACE`, `GRADCHECK`, and
-`REPLAY` are guarded where a rank-0-only operation could otherwise hang or desynchronize
-the distributed job.
+Pulse launches the script with its existing source code and exposes the run through its
+app and CLI. It instruments the script in memory; your files are not modified. Replace
+`train.py` with your script path and put any script arguments after it.
 
 You can then control tracking while the run is active:
 
@@ -833,7 +772,7 @@ LESS OVERHEAD
 
 Rather than collecting everything continuously, Pulse lets you decide what information is worth monitoring.
 
-Measured on a 20k-step loop started from Pulse's app with background streaming:
+Measured on a 20k-step loop started with `pulse run --stream`:
 
 | Work on the training thread | single process | stream mode |
 |---|---:|---:|
@@ -988,4 +927,4 @@ Can that fix be verified?
 
 Proprietary. See `LICENSE`.
 
-Use of this software is governed by the terms in that file. Copying, redistribution, and reverse engineering are not permitted.
+Use of this software is governed by the terms in that file. Copying, redistribution, and reverse engineering are not permitted.

{pulseml-0.4.2 → pulseml-0.4.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pulseml"
-version = "0.4.2"
+version = "0.4.3"
 description = "A live ML training debugger for tracking, diagnosing, verifying, and patching training runs."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -79,10 +79,10 @@ jax = [
 ]
 
 [project.urls]
-Homepage = "https://pulsedb.netlify.app/"
+Homepage = "https://residualml.com/"
 Repository = "https://github.com/codeyash09/PulseML"
 Issues = "https://github.com/codeyash09/PulseML/issues"
-Documentation = "https://pulsedb.netlify.app/"
+Documentation = "https://residualml.com/docs"
 
 [tool.setuptools.packages.find]
 where = ["src"]

{pulseml-0.4.2 → pulseml-0.4.3/src/pulseml.egg-info}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: pulseml
-Version: 0.4.2
+Version: 0.4.3
 Summary: A live ML training debugger for tracking, diagnosing, verifying, and patching training runs.
 Author-email: Yash Patel <codeyash09@gmail.com>
 License: Proprietary
-Project-URL: Homepage, https://pulsedb.netlify.app/
+Project-URL: Homepage, https://residualml.com/
 Project-URL: Repository, https://github.com/codeyash09/PulseML
 Project-URL: Issues, https://github.com/codeyash09/PulseML/issues
-Project-URL: Documentation, https://pulsedb.netlify.app/
+Project-URL: Documentation, https://residualml.com/docs
 Keywords: machine-learning,deep-learning,debugging,ml-debugging,training,pytorch,tensorflow,numpy,cupy,jax,gradients,training-debugger
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -69,35 +69,8 @@ dependencies separate from other projects.
 - An AI provider is optional for monitoring. Pulse's AI agent setup can sign you in with
   OpenRouter or use a provider API key.
 
-### 1. Create and activate an environment
 
-Run these commands from your project directory.
-
-**Windows — PowerShell:**
-
-```powershell
-py -3 -m venv .venv
-.\.venv\Scripts\Activate.ps1
-```
-
-If PowerShell activation is blocked by your execution policy, use Command Prompt instead:
-
-```bat
-py -3 -m venv .venv
-.venv\Scripts\activate.bat
-```
-
-Or skip activation and use `.venv\Scripts\python.exe` in place of `python` in the
-remaining commands.
-
-**macOS / Linux:**
-
-```bash
-python3 -m venv .venv
-source .venv/bin/activate
-```
-
-### 2. Install Pulse
+### 1. Install Pulse
 
 With the environment activated:
 
@@ -110,33 +83,23 @@ Using `python -m pip` ensures Pulse is installed for the Python interpreter sele
 the active environment. If you already have a project environment, activate it and run
 the second command there instead of creating a new one.
 
-### 3. Verify and launch
+### 2. Verify and launch
 
 ```text
-pulse --version
-pulse --help
+python -m pulse --version
+python -m pulse --help
 ```
 
-Use the same `pulse` command on Windows, macOS, and Linux. If the command is not found,
-activate the environment where you installed Pulse, or add that environment's Scripts
-(Windows) or bin (macOS/Linux) directory to `PATH`.
-
-Start Pulse:
-
-```text
-pulse
-```
+`python -m pulse` works on Windows, macOS, and Linux, including when the environment's
+Scripts directory is not on `PATH`. When the environment is activated, the shorter
+`pulse` command is available too.
 
-Pulse opens its app. In the app, ask the agent to run your training script, for example:
+To open Pulse, run:
 
 ```text
-Run train.py
+python -m pulse
 ```
 
-Replace `train.py` with your script path and include any script arguments in your request.
-Pulse starts it with the active environment's Python; no source-code edits are needed.
-This is the normal workflow for both single-GPU and distributed runs.
-
 ### AI provider configuration
 
 Pulse supports cloud and local AI providers.
@@ -146,13 +109,9 @@ Pulse supports cloud and local AI providers.
 OpenRouter serves every major model behind one account and has free models. Pulse can get
 a key for you:
 
-```bash
-pulse openrouter            # sign in, or create an account, in your browser
-```
-
-or just press Enter at any API key question. Pulse asks for a key during app setup and
-when you switch agents, and every one of those offers sign-in: for an OpenRouter model
-Enter starts it directly, and for any other provider Enter
+or just press Enter at any API key question. Pulse asks for a key in `pulse run`,
+`pulse code` and when you switch agents, and every one of those offers the
+sign-in: for an OpenRouter model Enter starts it directly, and for any other provider Enter
 offers to sign you in and switch to an OpenRouter model. The dashboard asks the same thing
 in a dialog, and `pulse --model openrouter/<model>` offers it when there is no key.
 Your browser opens on OpenRouter; sign in or sign up, click Authorize, and Pulse receives
@@ -260,20 +219,7 @@ pulse_monitor.Monitor      ---stream--->  pulse_brain.Brain
   never blocks, never thinks                thinks as long as it likes
 ```
 
-Start Pulse with `pulse`, then ask its agent to run your script; no source changes are needed.
-
-```text
-pulse
-```
-
-The app launches runs with background streaming, so training does not wait for the
-agent. To open a stream brain explicitly:
-
-```text
-python -m pulse.brain                      # newest session
-python -m pulse.brain <session-dir> --model openrouter/deepseek/deepseek-v4.1-flash
-python -m pulse.brain <session-dir> --once # one pass over a finished run
-```
+Start the script through Pulse; no source changes are needed:
 
 ### What the training process pays
 
@@ -594,14 +540,14 @@ rewrite git state, reach outside the project, start a background process or over
 file. So that a long run never stops to wait for you, a model answers that y/N. By default
 it is the agent's own model, asked separately: it sees only the command, why it was
 flagged, the project folder and what the agent was working on -- never the agent's
-reasoning -- so it judges the command on its own. To use a different model, set `PULSE_APPROVER=<model>` before starting Pulse (or set
-`"approver": "<model>"` in `pulse_config.json`):
+reasoning -- so it judges the command on its own. To use a different model:
 
 ```bash
-PULSE_APPROVER=openrouter/anthropic/claude-sonnet-5 pulse
+pulse run --approver openrouter/anthropic/claude-sonnet-5 train.py
 ```
 
-(To be asked yourself instead, set `"approver": "off"`.) The same commands
+(or `PULSE_APPROVER=<model>`, or `"approver": "<model>"` in `pulse_config.json`). To be
+asked yourself instead, use `--approver off` (or `"approver": "off"`). The same commands
 are flagged either way; only who answers changes. The reviewer answers the other question
 the agent otherwise stops for, too -- "apply this change?" for each edit it proposes --
 judging the diff against your request; every applied change stays one `/undo` away. The approver answers APPROVE or DENY
@@ -674,40 +620,45 @@ Commands on an open run: `/findings`, `/curve <name>`, `/vars`, `/audit`, `/audi
 watching). Everywhere: `/monitor`, `/run`, `/agent`, `/files`, `/add`, `/drop`, `/review`,
 `/undo`, `/log`, `/cloud`, `/help`, `/exit`.
 
-A run opened in the app -- started by asking the agent, picked with `/monitor`, or attached
-from outside -- gets its own session on the web dashboard: its environment, metric
-snapshots, the detectors' findings and crashes as incidents,
+A run opened in the app -- started with `/run`, picked with `/monitor`, or attached from
+outside -- gets its own session on the web dashboard, as a run started with `pulse run`
+does: its environment, metric snapshots, the detectors' findings and crashes as incidents,
 the agent's turns about it, and its uptime, synced in the background while it is watched.
 
 The agent can start, watch, restart and stop runs itself: "run it", "start training with
 --epochs 3", "restart it with the fix" are requests it carries out with its `start_run`,
 `run_status`, `restart_run` and `stop_run` tools (stopping asks you first). A request typed
-at a paused training run is likewise handled as what it is -- a question gets an answer,
-a change you asked for gets made -- instead of being read as a bug report to diagnose.
+at a paused `pulse run` is likewise handled as what it is -- a question gets an answer, a
+change you asked for gets made -- instead of being read as a bug report to diagnose.
 
 `pulse watch <run>`, `pulse <script.py>` and `pulse attach --pid N` open the same app
 directly on that run. On Windows it needs a console that understands escape sequences
 (Windows Terminal, or the console of Windows 10 and later). Without a real terminal (a
 pipe, CI), on a very small one, or with `PULSE_CLASSIC=1`, Pulse keeps the line-by-line
 screens described below. `PULSE_STREAMING=0` turns off the streaming of the model's
-replies.
+replies. `pulse run train.py` -- training with Pulse inside the script's own terminal --
+is unchanged.
 
 ---
 
 ## The `pulse` command
 
-For the normal workflow, the only command you need to enter in a terminal is `pulse`.
-Pulse does not have to be written into a script. Once the app opens, ask the agent to run
-your script or choose an existing run to monitor.
+Pulse does not have to be written into a script. Installing it puts a `pulse` command on
+the path, which starts runs and attaches to ones already going.
 
 ```bash
-pulse
+pulse run --stream train.py      # start train.py under Pulse, unmodified
+pulse                            # the app; without a terminal, attach to the run on this machine
+pulse train.py                   # attach to the run of that script
+pulse sessions                   # list the runs Pulse knows about
 ```
 
-In the app, ask the agent something like `Run train.py`. Pulse launches the script with
-background monitoring, so training continues while the agent investigates. No source
-changes are needed. This works the same way for a normal single-GPU run; multi-GPU
-instrumentation is enabled automatically when Pulse detects multiple ranks.
+`pulse run` starts a run; without it, a script name means the run that is **already
+going**. If several runs match, Pulse lists them and asks which.
+
+`--stream` puts the monitor in the training process and the agent in yours, so the run
+keeps going whether or not anyone is watching it, and attaching costs the run nothing.
+Without it the run is tracked in the terminal it was started from, as before.
 
 ### Watching a run you did not start under Pulse
 
@@ -723,7 +674,7 @@ sudo pulse attach --pid 12345    # when you already know the id
 Two limits are worth knowing before relying on it. It reads **function locals**, so a
 loop written at the top level of a script reports nothing — the values are module
 globals, which cannot be read this way. And it **samples**, about once a second, so a
-spike between two samples is not seen. A run launched from the Pulse app has neither
+spike between two samples is not seen. A run started under `pulse run` has neither
 problem, because Pulse is inside it.
 
 If `sudo pulse` says `command not found`, sudo is the reason: it replaces `PATH` with its
@@ -771,33 +722,21 @@ Pulse can pause training for investigation, allowing you to inspect the current
 
 ## Quickstart
 
-Start Pulse:
+Start an existing training script under Pulse without editing it:
 
 ```text
-pulse
+python -m pulse run train.py
 ```
 
-In the app, ask the agent to run your script, for example `Run train.py`. Pulse launches
-it with the active Python environment and instruments it in memory; your source files
-are not modified. Use the same workflow for a single-GPU run or a distributed run.
-
-### Distributed PyTorch (DDP and FSDP)
+To keep training independent of the viewer and watch the run from another terminal, use:
 
-When you ask Pulse's app agent to run a script, Pulse recognizes the common
-`torch.multiprocessing.spawn(worker, ..., nprocs=...)` pattern when `worker` is a
-top-level function and `nprocs` is an integer literal or variable name. Pulse instruments
-each spawned worker in memory, so the training script still needs no Pulse-specific code
-changes. The app launches runs in background-streaming mode; each worker is monitored in
-its own stream session rather than as one consolidated rank-0 view. The underlying model
-inspection recognizes DDP replicas and rank-local FSDP/DTensor shards.
+```text
+python -m pulse run --stream train.py
+```
 
-DDP-wrapped models are inspected through their underlying replicated model. For FSDP,
-model descriptions distinguish global DTensor shapes from local shard shapes, and
-`LAYERSTATS` reports the parameter view available on the current rank. Pulse does not
-all-gather FSDP parameters or gradients just to inspect them; these statistics are
-rank-local and are not presented as full-model norms. `SHAPETRACE`, `GRADCHECK`, and
-`REPLAY` are guarded where a rank-0-only operation could otherwise hang or desynchronize
-the distributed job.
+Pulse launches the script with its existing source code and exposes the run through its
+app and CLI. It instruments the script in memory; your files are not modified. Replace
+`train.py` with your script path and put any script arguments after it.
 
 You can then control tracking while the run is active:
 
@@ -878,7 +817,7 @@ LESS OVERHEAD
 
 Rather than collecting everything continuously, Pulse lets you decide what information is worth monitoring.
 
-Measured on a 20k-step loop started from Pulse's app with background streaming:
+Measured on a 20k-step loop started with `pulse run --stream`:
 
 | Work on the training thread | single process | stream mode |
 |---|---:|---:|