Docs: Refocus quickstart on end users (#155)

## Description 📝

Refocuses the quickstart on end users as part of the HEP: Iterating Docs
to Re-Focus on Customer Personas.

At its current state, this is a `DRAFT` PR which works to succinctly
highlight what happens whenever a user asks a question of PromptQL
(decision-making use case). In a follow-up commit, we'll introduce the
concept of automation (our other use case) and ensure we have a
high-level overview of the two use cases, which illustrates how users
are expected to interact with the product.

## Quick Links 🚀


[Quickstart](https://robdominguez-doc-2900-redesi.promptql-docs.pages.dev/quickstart/)

---------

Co-authored-by: hasura-bot <[email protected]>

Author: robertjdominguez

docs/automation.mdx

@@ -21,7 +21,7 @@ import Thumbnail from "@site/src/components/Thumbnail";
 **Automations** allow you to transform one-time conversations into reliable, repeatable business processes. Once you've
 built and tested a workflow in the PromptQL Playground, you can deploy it as an API endpoint that can be called
 programmatically or integrated into your existing systems. That means services like Zapier, Slack, or even your internal
-systems can trigger the automation whenever it’s needed—no coding required.
+systems can trigger the automation whenever it’s needed; no coding required.
 
 This is ideal for any repetitive task that benefits from AI-powered insights, like:
 

docs/how-to-talk-to-promptql.mdx

@@ -85,8 +85,7 @@ The best way to get started is to ask something simple but real. Start with a me
 analysis you've done manually before. From there, PromptQL will learn your expectations, surface useful patterns, and
 help you turn those insights into reliable, repeatable workflows.
 
-We recommend picking up with [our overview of PromptQL's capabilities](/capabilities.mdx) but, if you're eager, jump in
-to one of these use cases:
+Jump into one of these use cases:
 
 - [Making decisions](/decision-making.mdx)
 - [Automating tasks](/automation.mdx)

docs/quickstart.mdx

@@ -1,32 +1,172 @@
 ---
 sidebar_position: 0
 sidebar_label: Quickstart
-description:
-  "Learn how to set up and deploy PromptQL. This guide covers installing prerequisites, configuring API keys, running
-  PromptQL locally, and deploying to Hasura DDN."
+description: "Learn how to get started with PromptQL by asking complex questions and building automations."
 keywords:
   - promptql
-  - hasura ddn
   - quickstart
   - getting started
   - guide
-  - quickstart
 sidebar_class_name: quickstart-icon
+toc_max_heading_level: 4
 ---
 
-import Prereqs from "@site/docs/_prereqs.mdx";
-import Quickstart from "@site/docs/_quickstart_template.mdx";
+import Thumbnail from "@site/src/components/Thumbnail";
 
 # Quickstart with PromptQL
 
-In this getting started guide, you'll deploy PromptQL and connect it to a sample dataset — a hosted PostgreSQL database
-pre-loaded with IMDb movie data. You'll start by exploring the dataset through natural language queries, discovering how
-PromptQL can reliably answer questions and assist in decision-making. Then, you'll add custom business logic that lets
-PromptQL act on your behalf — like renting a movie for a user — showing how it can go beyond answering questions to
-automating tasks.
+## Introduction
+
+This guide is designed to give you a high-level overview of PromptQL and how you can use it to make better decisions
+about your business and automate tasks; all without any coding knowledge required.
+
+:::info Prerequisites
+
+Before continuing, you'll need a [Hasura Cloud account](https://cloud.hasura.io/signup/new_user).
+
+If you have your own project, you can apply the information below to it. Otherwise, we have a
+[collection of sandboxes](/index.mdx#demos) which allow you to try PromptQL and get a feel for the experience. Below,
+we'll use the `sandbox-gtm` example.
+
+If you're looking to build a new project from scratch, check out
+[these guides](/how-to-build-with-promptql/overview.mdx).
+
+:::
+
+## Guide
+
+### Open your project
+
+Each PromptQL project can be accessed via a unique URL. You can access all your projects
+[from the PromptQL Console](https://promptql.console.hasura.io/).
+
+<Thumbnail
+  src="/img/get-started/pql-console-all-projects.png"
+  alt="The PromptQL Cloud Console with all projects."
+  width="1000px"
+/>
+
+When you navigate to a project, you're dropped into its **playground**; this is the chat interface that allows you to
+ask questions about your data and create automations.
+
+<Thumbnail src="/img/get-started/pql-playground.png" alt="The PromptQL Playground." width="1000px" />
+
+### Talk to your data
+
+Primarily, you'll interact with PromptQL in one of two ways: either by asking questions, or creating automations.
+
+#### Ask a complex question
+
+Using the `sandbox-gtm` project, we're going to ask the following question:
+
+> _Which enterprise deals are at risk of slipping this quarter based on engagement patterns?_
+
+While this question seems simple, it's complex because it requires defining what qualifies as an enterprise deal,
+identifying signals that indicate a deal is at risk—such as low engagement or delayed progress—and analyzing various
+engagement patterns, including sales activities, buyer signals, and product usage, all in comparison to historical and
+successful deal benchmarks.
+
+If you're using your own project, start by asking a similarly strategic question relevant to your data. Otherwise,
+[click here](https://promptql.console.hasura.io/share/05437507-6b31-4037-a302-0dbcec5de2ae) to be dropped into a thread
+replay.
+
+##### Query plan
+
+When you ask a question, PromptQL will respond with a **query plan**. This is a step-by-step breakdown in plain language
+of how it will process your request, including any data retrieval, filtering, or AI operations it will perform.
+
+<Thumbnail
+  src="/img/get-started/pql-query-plan.png"
+  alt="A query plan for a question detailing all steps to find the right data."
+  width="1000px"
+/>
+
+It helps make PromptQL's approach transparent by explaining what it's going to do before it does it, including any
+assumptions it's making about the data or process.
+
+Take a look at the query plan generated for your question and see how PromptQL takes a complex question and breaks it
+down into a series of steps, just like a human would.
+
+:::tip Query plans are modifiable
+
+You can edit a query plan by clicking the pencil next to a query plan.
+
+You have domain-specific expertise which you can share with PromptQL. When you modify a query plan, PromptQL remembers
+and self-corrects for future threads!
+
+:::
+
+##### Execution
+
+The query plan is then **executed** against your data.
+
+<Thumbnail src="/img/get-started/pql-execution.png" alt="A query plan's execution of Python and SQL." width="1000px" />
+
+PromptQL pulls the necessary data and uses AI to help make sense of it. Behind the scenes, it fetches information from
+your database and organizes it using Python, so you can focus on the insights, not the code.
+
+If you're curious, expand the execution in your project and see the code PromptQL is executing against your datasource.
+And, just like the query plan, if you see something that should be different, let PromptQL know!
+
+##### Artifacts
+
+Typically, the execution of a query plan will result in an **artifact**.
+
+<Thumbnail
+  src="/img/get-started/pql-artifact.png"
+  alt="A table artifact produced via the execution of a query plan."
+  width="1000px"
+/>
+
+Artifacts are structured outputs like tables, text, or visualizations that store the processed data or analysis results,
+which can be referenced later in the conversation, exported, or used to start new threads for further analysis.
+
+We have a more in-depth guide for making decisions with PromptQL; check it out [here](/decision-making.mdx).
+
+:::tip This is a conversation!
+
+Talking with PromptQL is like talking to a human. This means it's an iterative process wherein you ask a question, it
+responds, and you build on that response by refining, clarifying, or asking follow-up questions. The more context you
+provide, the better the answers become.
+
+:::
+
+#### Give it a task to automate
+
+Using the same sandbox project, we'll ask PromptQL to generate an automation for us:
+
+> I need an automation to help me identify risky opportunities in my sales pipeline. I want to input a date range and
+> get back a list of opportunities that need attention. Specifically, I want to know which deals:
+>
+> - Haven't had any recent activity
+> - Are missing important contact relationships
+> - Show low engagement from the customer
+> - Are taking longer than expected to close
+>
+> Can you create something that gives me a risk score for each opportunity and suggests specific actions I should take?
+> I'd like the results in a format that makes it easy for me to prioritize which deals need immediate attention.
+
+This task-based prompt asks PromptQL to build an **automation**: a reusable workflow that runs against your data and
+gives you consistent, structured results. Rather than just answering a one-time question, automations are designed to
+help you monitor, score, or act on key insights regularly.
+
+<Thumbnail
+  src="/img/get-started/playground-quickstart-automation.png"
+  alt="A PromptQL-generated automation."
+  width="1000px"
+/>
+
+In this example, PromptQL will identify the relevant data, define what makes a deal “risky,” build a scoring system to
+prioritize those deals, and suggest actions—all packaged in a format that’s easy to review and reuse. Just like with
+query plans, PromptQL explains each step and lets you modify the logic, so you stay in control of the process.
+
+If you're using your own project, give PromptQL a similar task to automate. Otherwise,
+[click here](https://promptql.console.hasura.io/share/88a988ff-b44b-42b8-9859-846fa4be3f9c) to be dropped into a thread
+replay.
 
-<Prereqs />
+We also have a dedicated guide to building your own automations available [here](/automation.mdx).
 
-## Build your first PromptQL app
+## Next steps
 
-<Quickstart />
+Now that you've had your first set of conversations with PromptQL, we recommend checking out these docs around its
+[core capabilities](/capabilities.mdx).

src/css/custom.css

@@ -330,6 +330,7 @@ h6 code {
 
 blockquote {
   border-left: solid 2px var(--blockquote-margin);
+  font-style: italic;
 }
 
 /* -------------- TYPOGRAPHY COLORS -------------- */
@@ -455,8 +456,8 @@ iframe {
   }
 }
 
-.theme-doc-sidebar-container [class^='sidebarLogo_'] {
   border-bottom: 1px solid var(--next-prev-border-color);
+  .theme-doc-sidebar-container [class^='sidebarLogo_'] {
   margin: 0;
 }
 
@@ -1493,6 +1494,7 @@ pre[class*='language-'] code span.token {
 /* Mobile Navigation */
 .navbar-sidebar {
   background-color: var(--main-bg-color);
+  z-index: 1000;
 }
 
 .navbar-sidebar__back {

src/theme/DocSidebar/CustomSidebar.css

@@ -3,7 +3,21 @@
   background-color: var(--sidebar-bg-color) !important;
   width: 100%;
   overflow-y: auto;
-  padding-top: 5rem;
+}
+
+.custom-sidebar__logo {
+  display: grid;
+  place-items: center;
+  padding: 1rem;
+  height: 5rem;
+  width: 100%;
+  text-align: center;
+}
+
+.custom-sidebar__logo svg {
+  max-height: 100%;
+  max-width: 80%;
+  object-fit: contain;
 }
 
 .custom-sidebar__content {

src/theme/DocSidebar/Desktop/index.tsx

@@ -1,5 +1,6 @@
 import React from 'react';
 import { useLocation } from '@docusaurus/router';
+import { useColorMode } from '@docusaurus/theme-common';
 import type { PropSidebarItem } from '@docusaurus/plugin-content-docs';
 import Link from '@docusaurus/Link';
 import {
@@ -9,6 +10,9 @@ import {
   type Category,
 } from '../utils'; 
 import '../CustomSidebar.css'; 
+import LogoLight from '@site/static/img/pql-logo-large.svg';
+import LogoDark from '@site/static/img/pql-logo-large-dark-mode.svg';
+
 
 interface ContentProps {
   path: string;
@@ -17,6 +21,7 @@ interface ContentProps {
 
 export default function Content({ sidebar }: ContentProps) {
   const location = useLocation();
+  const { colorMode } = useColorMode();
   const categories: Category[] = buildCategories(sidebar);
 
   const renderSidebarItem = (item: PropSidebarItem): React.ReactElement => {
@@ -80,6 +85,11 @@ export default function Content({ sidebar }: ContentProps) {
       role="navigation"
       aria-label="Documentation sidebar"
     >
+      <div className="custom-sidebar__logo">
+        <Link to="/index">
+           {colorMode === 'dark' ? <LogoDark /> : <LogoLight />}
+        </Link>
+      </div>
       <div className="custom-sidebar__content">
         {categories.map(renderCategory)}
       </div>