Update README, docs (jupyterlab#347)

* Copy edits for brevity, adds large screenshot

* Adds screenshot, adds principles to contributor docs

* Uses screenshot class for home page image

* Fix reference to screenshot

* Copy edits

* Update index.md

Styles magic command

* Copy edits based on @dlqqq's feedback

README.md

@@ -1,17 +1,45 @@
 # Jupyter AI
 
-Welcome to Jupyter AI, which brings generative AI to Jupyter. Jupyter AI provides a user-friendly
+Jupyter AI connects generative AI with Jupyter notebooks. Jupyter AI provides a user-friendly
 and powerful way to explore generative AI models in notebooks and improve your productivity
 in JupyterLab and the Jupyter Notebook. More specifically, Jupyter AI offers:
 
 * An `%%ai` magic that turns the Jupyter notebook into a reproducible generative AI playground.
   This works anywhere the IPython kernel runs (JupyterLab, Jupyter Notebook, Google Colab, VSCode, etc.).
 * A native chat UI in JupyterLab that enables you to work with generative AI as a conversational assistant.
-* Support for a wide range of generative model providers and models
-  (AI21, Anthropic, Cohere, Hugging Face, OpenAI, SageMaker, etc.).
+* Support for a wide range of generative model providers, including AI21, Anthropic, AWS, Cohere,
+  Hugging Face, and OpenAI.
 
 Documentation is available on [ReadTheDocs](https://jupyter-ai.readthedocs.io/en/latest/).
 
+![A screenshot of Jupyter AI showing the chat interface and the magic commands](docs/source/_static/jupyter-ai-screenshot.png)
+
+## Requirements
+
+You will need to have installed the following software to use Jupyter AI:
+
+- Python 3.8 - 3.11
+- JupyterLab 4
+
+In addition, you will need access to at least one model provider.
+
+## Setting Up Model Providers in a Notebook
+
+To use any AI model provider within this notebook, you'll need the appropriate credentials, such as API keys.
+
+Obtain the necessary credentials (e.g., API keys) from your model provider's platform.
+
+You can set your keys using environment variables or in a code cell in your notebook.
+In a code cell, you can use the %env magic command to set the credentials as follows:
+
+```python
+# NOTE: Replace 'PROVIDER_API_KEY' with the credential key's name,
+# and replace 'YOUR_API_KEY_HERE' with the key.
+%env PROVIDER_API_KEY=YOUR_API_KEY_HERE
+```
+
+For more specific instructions for each model provider, refer to [the model providers documentation](https://jupyter-ai.readthedocs.io/en/latest/users/index.html#model-providers).
+
 ## Installation
 
 You can use `conda` or `pip` to install Jupyter AI. If you're using macOS on an Apple Silicon-based Mac (M1, M1 Pro, M2, etc.), we strongly recommend using `conda`.
@@ -41,14 +69,9 @@ and create an environment that uses Python 3.11:
     $ conda activate jupyter-ai
     $ pip install jupyter_ai
 
-If you are not using JupyterLab and you only want to install the Jupyter AI `%%ai` magic, skip the `pip install jupyter_ai` step above, and instead, run:
-
-    $ pip install jupyter_ai_magics
-
-
 ## The `%%ai` magic command
 
-The `%%ai` magic works anywhere the IPython kernel runs (JupyterLab, Jupyter Notebook, Google Colab, Visual Studio Code, etc.).
+The `%%ai` magic works anywhere the IPython kernel runs, including JupyterLab, Jupyter Notebook, Google Colab, and Visual Studio Code.
 
 Once you have installed the `%%ai` magic, you can enable it in any notebook or the IPython shell by running:
 

docs/source/contributors/index.md

@@ -2,6 +2,18 @@
 
 This page is intended for people interested in building new or modified functionality for Jupyter AI.
 
+## Design principles
+
+Maintainers of Jupyter AI have adopted principles that contributors should also follow. These principles, which build on top of [the Zen of Python](https://peps.python.org/pep-0020/), are intended to earn users' trust by keeping their data under their control. The following list is non-exhaustive; maintainers have discretion to interpret and revise these principles.
+
+1. Jupyter AI is **vendor-agnostic**. Jupyter AI does not discriminate between available models, and gives users a choice of model providers. A feature in Jupyter AI may be specific to one model or model provider if it cannot be used with other models or providers.
+2. Jupyter AI **only responds to an explicit prompt**; it does not watch files and it does not send prompts automatically. Any change that watches user files must be opt-in only.
+3. Jupyter AI is **transparent** with its chat prompts. The chat interface and magic commands use system messages and prompt templates that are open source, so that users know what gets sent to language models.
+4. Jupyter AI is **traceable**; users know when it has been used to generate content. When Jupyter AI generates a notebook, the notebook says that it was generated by Jupyter AI. When a user runs a Jupyter AI magic command in a notebook, output cells say, in their metadata, that they were generated by Jupyter AI.
+5. Jupyter AI uses a **human-centered design**. The chat interface should look and feel like chat applications that are generally available. The magic commands should look and work like other IPython magic commands. Settings screens should be used minimally, and wherever they are used, they should be readable and understandable, even for users not fluent in the user interface language.
+
+Issues and pull requests that violate the above principles may be declined. If you are unsure about whether your idea is a good fit for Jupyter AI, please [open an issue](https://github.com/jupyterlab/jupyter-ai/issues/new/choose) so that our maintainers can discuss it with you.
+
 ## Prerequisites
 
 You can develop Jupyter AI on any system that can run a supported Python version up to and including 3.11, including recent Windows, macOS, and Linux versions.

docs/source/index.md

@@ -10,6 +10,21 @@ in JupyterLab and the Jupyter Notebook. More specifically, Jupyter AI offers:
 * Support for a wide range of generative model providers and models
   (AI21, Anthropic, Cohere, Hugging Face, OpenAI, SageMaker, etc.).
 
+<img src="_static/jupyter-ai-screenshot.png"
+    alt='A screenshot of Jupyter AI showing the chat interface and the magic commands'
+    class="screenshot" />
+
+## JupyterLab support
+
+**Each major version of Jupyter AI supports *only one* major version of JupyterLab.** Jupyter AI 1.x supports
+JupyterLab 3.x, and Jupyter AI 2.x supports JupyterLab 4.x. The feature sets of versions 1.0.0 and 2.0.0
+are the same. We will maintain support for JupyterLab 3 for as long as it remains maintained.
+
+The `main` branch of Jupyter AI targets the newest supported major version of JupyterLab. All new features and most bug fixes will be
+committed to this branch. Features and bug fixes will be backported
+to work on JupyterLab 3 only if developers determine that they will add sufficient value.
+**We recommend that JupyterLab users who want the most advanced Jupyter AI functionality upgrade to JupyterLab 4.**
+
 ## Contents
 
 ```{toctree}