docs(installation): clean up installation steps and improve documentation copy + examples (#6)

frgfm · web-flow · commit 87591444a40e · 2025-07-10T20:34:58.000+02:00
* docs: improve installation steps and examples

* docs(changelog): update component

* docs(introduction): update copy

* ci(labeler): update labeler
diff --git a/.github/labeler.yml b/.github/labeler.yml
@@ -26,7 +26,12 @@
   - any-glob-to-any-file:
     - '.vscode/*'
 
-'ext: style':
+'ext: scripts':
+- changed-files:
+  - any-glob-to-any-file:
+    - 'scripts/*'
+
+'topic: style':
 - changed-files:
   - any-glob-to-any-file:
     - '**/.pre-commit-config.yaml'
@@ -40,6 +45,7 @@
     - '**/Makefile'
     - '**/.env.example'
     - '**/*.mdx'
+    - 'docs/*'
 
 # Orchestration
 'func: build':
diff --git a/README.md b/README.md
@@ -48,12 +48,81 @@ Relay helps builds create apps on email workflows. See it as a crossover between
 
 ## Quick Tour
 
-### Fetching your emails
+### Fetching your unread emails
 
 ```shell
-relay messages ls
+relay messages ls --limit 10 --unread
+```
+```
+Using account: piedpiper
+                            Messages from richard@piedpiper.com
+┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ UID   ┃ Timestamp                ┃ From                          ┃ Subject    ┃ Snippet    ┃
+┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ 15443 │ 2025-06-23 12:35:44 UTC  │ gilfoyle@piedpiper.com        │ Server     │ The        │
+│       │                          │                               │ migration  │ migration  │
+│       │                          │                               │ complete   │ is done... │
+│ 15467 │ 2025-06-26 12:46:09 UTC  │ dinesh@piedpiper.com          │ RE: My     │ Actually   │
+│       │                          │                               │ code is    │ Gilfoyle,  │
+│       │                          │                               │ perfect    │ your cod...│
+│ 15555 │ 2025-07-08 15:46:27 UTC  │ jared@piedpiper.com           │ Team       │ Hi guys!   │
+│       │                          │                               │ building   │ I've       │
+│       │                          │                               │ retreat    │ organized..│
+│ 15587 │ 2025-07-10 13:34:48 UTC  │ monica@raviga.com             │ Q3         │ Richard,   │
+│       │                          │                               │ metrics    │ we need to │
+│       │                          │                               │ review     │ discuss... │
+│ 15588 │ 2025-07-10 14:22:49 UTC  │ gavin@hooli.com               │ Acquisition│ Pied Piper │
+│       │                          │                               │ offer      │ team, I'm  │
+│       │                          │                               │            │ prepared...│
+└───────┴──────────────────────────┴───────────────────────────────┴────────────┴────────────┘
+Showing 5 of 5 unread messages
+```
+
+### Reading email details
+
+```shell
+relay messages cat 15443
+```
+```
+Using account: piedpiper
+
+Message Details
+UID: 15443
+Timestamp: 2025-06-23 12:35:44 UTC
+Subject: Server migration complete
+From: "Bertram Gilfoyle" <gilfoyle@piedpiper.com>
+To: richard@piedpiper.com
+CC: dinesh@piedpiper.com, jared@piedpiper.com
+BCC: N/A
+
+Message Body:
+The migration is done. Obviously.
+
+While you were all probably panicking about downtime (which never happened), 
+I successfully migrated our entire server infrastructure to the new data center.
+
+Key accomplishments:
+- Migrated 47 servers in 3.2 hours
+- Implemented redundant failsafes
+- Optimized database queries by 340%
+- Fixed 23 security vulnerabilities
+
+Richard, the system is now running at 99.97% efficiency. The remaining 0.03% 
+is due to the laws of physics, which even I cannot override.
+
+Dinesh, I've documented everything in a way that even you might comprehend, 
+though I make no guarantees.
+
+The servers are purring like a well-fed cat. You may now return to your 
+regularly scheduled mediocrity.
+
+--
+Bertram Gilfoyle
+Senior Systems Architect
+Pied Piper Inc.
+
+No attachments
 ```
-That's it!
 
 
 ## Get started 🚀
@@ -66,7 +135,7 @@ That's it!
 
 #### 1 - Install the CLI
 ```shell
-uv pip install --system relaycli
+pip install relaycli
 ```
 #### 2 - Connect your email account
 ```shell
diff --git a/docs/changelog/overview.mdx b/docs/changelog/overview.mdx
@@ -6,7 +6,7 @@ rss: true
 
 The changelog below reflects new product developments and updates on a monthly basis.
 
-<Update label="July 2025" description="v0.1.0" tags={["Relay"]}>
+<Update label="v0.0.1" description="2025-07-10" tags={["Relay", "CLI"]}>
   ### 🎉 Initial Release
 
   Welcome to Relay! Our first beta release brings you the core CLI and Python library for email management.
diff --git a/docs/documentation/getting-started/introduction.mdx b/docs/documentation/getting-started/introduction.mdx
@@ -5,27 +5,33 @@ description: "Make e-mail programmable again"
 mode: "wide"
 ---
 
-Relay is an **open-source CLI and Python library** that turns any **IMAP-compatible** inbox into a clean, developer-friendly interface in under five minutes.
-Build voice agents, auto-responders, support bots, or full-blown e-mail clients—without touching MIME, OAuth hoops, or UID gymnastics.
+Relay is an **open-source CLI and Python library** that makes email programmable again. Connect any **IMAP-compatible** inbox and build email-powered applications in minutes—without wrestling with MIME parsers, OAuth flows, or IMAP quirks.
+
+Your credentials stay local. Your data stays yours. No gatekeepers, no vendor lock-in.
 
 <CardGroup cols={2}>
   <Card title="Relay CLI" icon="terminal" href="/documentation/getting-started/quickstart">
-    Your emails, your CLI. Get started now.
+    Your emails, your terminal. Get started in 5 minutes.
   </Card>
   <Card
     title="Relay Cloud"
     icon="cloud"
-    href="/documentation/community/roadmap"
+    href="/documentation/community/roadmap#coming-soon"
   >
     Coming soon: hosted API and web interface.
   </Card>
 </CardGroup>
 
 ## Why we built it
 
-We started Relay to power a voice-first executive assistant for founders.
-Google's "CASA" quotas throttled our Gmail integration. IMAP was universal—but clunky.
-So we built a clean CLI and Python library that wraps IMAP/SMTP complexity, made it open-source, and designed it for developers who want to build on email without the headaches.
+Email is a billion-person communication protocol, but building on it sucks. 
+We hit this wall building a voice assistant for founders when we received the bill for the security audit to validate Gmail permissions. You can read the full story [here](https://relaycli.com/manifesto).
+So we built Relay: a clean, local-first CLI and Python library that handles the complexity while keeping you in control. No middlemen, no data harvesting, no artificial limits.
+
+## What you can build
+
+Parse receipts into spreadsheets. Build auto-responders that actually understand context. Create support bots that route emails intelligently. Extract attachments in bulk. Build full email clients.
+The infrastructure is here. The data is yours. The possibilities are endless.
 
 ## Where to go next
 
@@ -52,7 +58,6 @@ So we built a clean CLI and Python library that wraps IMAP/SMTP complexity, made
     icon="discord"
     href="https://discord.gg/T4zbT7RcVy"
   >
-    The **#general** Channel in our Discord server is a great place to get help
-    with all things from the team.
+    Get help and share what you're building with the community.
   </Card>
 </CardGroup>
diff --git a/docs/documentation/getting-started/quickstart.mdx b/docs/documentation/getting-started/quickstart.mdx
@@ -26,58 +26,92 @@ description: 'From zero to "Hello inbox" in under 5 minutes'
       </Tab>
     </Tabs>
   </Step>
-    <Step title="Install a Python package manager">
+  <Step title="Install the CLI">
     <Tabs>
-      <Tab title="uv">
-        #### Using the standalone installer
+      <Tab title="macOS & Linux">
         <CodeGroup>
-        ```shell title="macOS & Linux"
-        curl -LsSf https://astral.sh/uv/install.sh | sh
+        ```shell title="curl" icon="code"
+        curl -sSL https://github.com/relaycli/relay/releases/download/v0.0.1-alpha.2/install.sh | bash
         ```
-        ```shell title="Windows"
-        powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+        ```shell title="wget" icon="code"
+        wget -qO- https://github.com/relaycli/relay/releases/download/v0.0.1-alpha.2/install.sh | bash
         ```
-        </CodeGroup>
-        #### Using Pypi
-        ```shell
-        pip install uv
+        ```shell title="pip" icon="python"
+        pip install relaycli
         ```
-
-        If you encounter issues, refer to the [official documentation](https://docs.astral.sh/uv/getting-started/installation).
+        ```shell title="uv" icon="python"
+        uv pip install --system relaycli
+        ```
+        </CodeGroup>
+        If you encounter issues, please follow the installation steps for either [pip](https://pip.pypa.io/en/stable/installation/) or [uv](https://docs.astral.sh/uv/getting-started/installation) and then run the corresponding installation command.
       </Tab>
-      <Tab title="pip">
-        Follow the [official documentation](https://pip.pypa.io/en/stable/installation/).
+      <Tab title="Windows">
+        <CodeGroup>
+        ```shell title="pip" icon="python"
+        pip install relaycli
+        ```
+        ```shell title="uv" icon="python"
+        uv pip install --system relaycli
+        ```
+        </CodeGroup>
+        If you encounter issues, please follow the installation steps for either [pip](https://pip.pypa.io/en/stable/installation/) or [uv](https://docs.astral.sh/uv/getting-started/installation) and then run the corresponding installation command.
       </Tab>
     </Tabs>
   </Step>
-  <Step title="Install the CLI">
-    <CodeGroup>
-    ```shell title="uv"
-    uv pip install --system relaycli
-    ```
-    ```shell title="pip" icon="python"
-    pip install relaycli
-    ```
-    </CodeGroup>
-  </Step>
   <Step title="Connect the inbox">
     ```shell
     relay account add
     ```
   </Step>
   <Step title="Try out CLI commands">
-    <CodeGroup>
-    ```shell title="fetch recent emails"
-    relay messages ls
-    ```
-    ```shell title="search your inbox"
-    relay messages grep "Pied piper"
-    ```
-    ```shell title="read a specific message"
-    relay messages cat <message_uid>
-    ```
-    </CodeGroup>
+    <Tabs>
+      <Tab title="Fetch recent emails">
+        ```shell
+        relay messages ls
+        ```
+        ```
+        Using account: piedpiper
+                                    Messages from richard@piedpiper.com
+        ┏━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+        ┃ UID   ┃ Timestamp                ┃ From                          ┃ Subject    ┃ Snippet    ┃
+        ┡━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━┩
+        │ 15443 │ 2025-06-23 12:35:44 UTC  │ gilfoyle@piedpiper.com        │ Server     │ The        │
+        │       │                          │                               │ migration  │ migration  │
+        │       │                          │                               │ complete   │ is done... │
+        │ 15467 │ 2025-06-26 12:46:09 UTC  │ dinesh@piedpiper.com          │ RE: My     │ Actually   │
+        │       │                          │                               │ code is    │ Gilfoyle,  │
+        │       │                          │                               │ perfect    │ your cod...│
+        └───────┴──────────────────────────┴───────────────────────────────┴────────────┴────────────┘
+        Showing 2 of 2 unread messages
+        ```
+      </Tab>
+      <Tab title="Search your inbox">
+        ```shell
+        relay messages grep "Gavin Belson"
+        ```
+      </Tab>
+      <Tab title="Read a specific message">
+        ```shell
+        relay messages cat 15467
+        ```
+        ```
+        Using account: piedpiper
+
+        Message Details
+        UID: 15467
+        Timestamp: 2025-06-26 12:46:09 UTC
+        Subject: RE: My code is perfect
+        From: "Dinesh Chugtai" <dinesh@piedpiper.com>
+        To: richard@piedpiper.com
 
+        Message Body:
+        Actually Gilfoyle, your code has a memory leak in the compression algorithm.
+        I've already fixed it. You're welcome.
+
+        No attachments
+        ```
+      </Tab>
+    </Tabs>
   </Step>
   <Step title="Make something cool">
     Now it's your turn!
diff --git a/scripts/install.sh b/scripts/install.sh
