Update the org card

cc

@victor

README.md

@@ -18,25 +18,79 @@ pinned: false
 
 # Spaces Dev Mode (feature preview)
 
+## About Spaces
 
-If Dev mode is enabled on your Space, you can connect to it using SSH or VS Code.  
-You can make changes to your application code, run some debug tools, ...
+Spaces offer a simple way to host ML demos and apps on your profile or your organization's profile.
+In essence, a Space is a Docker container that runs your application.
+
+Learn more about Spaces here: <a href="https://huggingface.co/docs/hub/spaces" target="_blank">https://huggingface.co/docs/hub/spaces</a>.
+
+## Spaces dev mode
+
+
+Whenever your commit some changes to your Space repo, the underlying Docker image gets rebuilt, and then a new virtual machine is provisioned to host the new container.
+
+The dev mode allows you to update your Space much quicker by overriding the Docker image.
+
+The dev mode Docker image starts your application as a sub-process, allowing you to restart it without stopping the Space container itself.
+It also starts a VS Code server and a SSH server in the background for you to connect to the Space.
+
+The ability to connect to the running Space unlocks several use cases:
+- You can make changes to the app code without the Space rebuilding everytime
+- You can debug a running application and monitor resources live
+
+Overall it makes developing and experimenting with Spaces much faster by skipping the Docker image rebuild phase.
+
+## Interface
+
+Once the dev mode is enabled on your Space, you should see a modal like the following.
 
 <img src="https://cdn-uploads.huggingface.co/production/uploads/5f17f0a0925b9863e28ad517/wSfCELm8WoY_EFhj8l1MM.png" style="max-width: 500px;">
 
-Changes will be reflected in your space after you hit the refresh button.  
-When you are done, you can persist your changes using `git' as you would normally do when developing locally.
+The application does not restart automatically when you change the code. For your changes to appear in the Space, you need to use the `Refresh` button that will restart the app.
+
+<div class="alert alert-warning">
+  If you're using the Streamlit or Gradio SDK, or if your application is Pyhton-based, note that requirements are not installed automatically.
+  You will need to manually run `pip install` from VS Code or SSH.
+</div>
+
+### Persisting changes
+
+The changes you make when the dev mode is enabled are not persisted to the Space repo automatically, and by default they will be discarded when the dev mode is disabled or when the Space goes to sleep.
 
+If you wish to persist changes made while the dev mode is enabled, you need to use `git` from inside the Space container (using VS Code or SSH). For example:
 
-## How to enable the dev mode
+```shell
+# Add changes and commit them
+git add .
+git commit -m "Persist changes from dev mode"
+
+# Push the commit to persist them in the repo
+git push
+```
+
+The modal will display a warning if you have uncommitted or unpushed changes in the Space:
+
+
+![image/png](https://cdn-uploads.huggingface.co/production/uploads/5fcfb7c407408029ba3577e2/r6Uk1YyvE2-hzsKTSRvnR.png)
+
+### How to enable the dev mode
 
 Go to your Space's settings and click on "Enable dev mode".
 
-![image/png](https://cdn-uploads.huggingface.co/production/uploads/5fcfb7c407408029ba3577e2/QvLqvKxEzq8v0cpxQQ5An.png)
+
+![image/png](https://cdn-uploads.huggingface.co/production/uploads/5fcfb7c407408029ba3577e2/31fExSYIPyxgXm-B9uL4d.png)
+
+
+You can also enable the dev mode from the quick actions dropdown.
+
+
+![image/png](https://cdn-uploads.huggingface.co/production/uploads/5fcfb7c407408029ba3577e2/t2nQI_5kXY53QIVqBkIx6.png)
+
 
 ## Limitations
 
-The dev mode is currently not available for static Spaces.
+The dev mode is currently not available for static Spaces. Docker Spaces also have some additional requirements.
 
 ### Docker Spaces
 
@@ -54,6 +108,10 @@ Dev mode is supported for Docker Spaces. However, your Space needs to comply wit
 
 4. The Dockerfile must contain a `CMD` instruction for startup. Checkout [Docker's documentation](https://docs.docker.com/reference/dockerfile/#cmd) about the `CMD` instruction for more details.
 
+The Dev Mode works well when the base image is debian-based (eg, ubuntu).
+
+More exotic linux distros (eg, alpine) are not tested and the dev mode is not guaranteed to work on them.
+
 ### Example of a compatible Dockerfile
 
 This is an example of a Dockerfile compatible with Spaces dev mode.