Docs: Refocus docs

.gitignore

@@ -15,6 +15,7 @@ node_modules/
 .env.test.local
 .env.production.local
 .secrets
+notes.txt
 
 .direnv
 

docs/how-to-build-with-promptql/with-automation.mdx → docs/automation.mdx

@@ -1,6 +1,6 @@
 ---
-sidebar_position: 51
-sidebar_label: With Automation
+sidebar_position: 1.8
+sidebar_label: Build Automations
 description:
   "Learn how to build automated workflows and processes with PromptQL for reliable, repeatable business tasks."
 keywords:
@@ -14,14 +14,14 @@ toc_max_heading_level: 4
 
 import Thumbnail from "@site/src/components/Thumbnail";
 
-# Building Automations with PromptQL
+# Build Automations with PromptQL
 
 ## Introduction
 
 **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:
 
@@ -140,7 +140,7 @@ https://promptql.ddn.hasura.app/playground/automations/v1/box_office_analyzer/ru
 
 :::
 
-## Best practices
+## Best Practices
 
 1. **Start simple** - Begin with a straightforward use case to learn the process
 2. **Iterate and improve** - Refine your automation based on initial results

docs/capabilities.mdx

@@ -0,0 +1,117 @@
+---
+sidebar_position: 1.5
+sidebar_label: Capabilities
+description:
+  "Learn what PromptQL can do to help you make decisions quicker or automate tasks with relability and accuracy."
+keywords:
+  - promptql
+  - accurate
+  - reliable
+  - capabilities
+toc_max_heading_level: 4
+---
+
+import Thumbnail from "@site/src/components/Thumbnail";
+
+# What can PromptQL do?
+
+## Introduction
+
+PromptQL combines data analysis, AI capabilities, and automation tools into a conversational interface. It's designed to
+help you explore data, make decisions, and create reliable workflows—all through natural dialogue.
+
+## Core features
+
+### Agentic Semantic Metadata Layer
+
+PromptQL doesn't just execute queries—it builds and maintains a dynamic understanding of your data landscape. This
+"semantic metadata layer" grows more sophisticated with each interaction, learning your business terminology, data
+relationships, and analytical patterns.
+
+When you correct a definition or clarify a business rule, PromptQL remembers. It uses this knowledge to:
+
+- Translate natural language to precise queries
+- Apply consistent business rules across analyses
+- Suggest relevant connections between datasets
+- Self-correct based on feedback
+
+Think of it as an intelligent layer between you and your data that learns and adapts. It remembers that "active users"
+means something specific in your business, or that certain metrics should always be filtered in particular ways.
+
+:::info Learn more
+
+You can learn more about PromptQL's semantic understanding [here](/data-modeling/overview.mdx).
+
+:::
+
+### AI Primitives
+
+At its core, PromptQL works with data and AI functions, which we call **AI primitives**. It's helpful to think of these
+as tools in PromptQL's toolbox.
+
+For data, PromptQL can run complex SQL queries with built-in safety checks and optimization. It handles joins, and
+aggregations naturally, with automatic error handling and self-correction.
+
+The AI functions extend these capabilities beyond pure data analysis:
+
+| Primitive | Description                                  |
+| --------- | -------------------------------------------- |
+| Classify  | Sort text into dynamic categories.           |
+| Summarize | Create concise summaries of longer text.     |
+| Extract   | Pull structured data from unstructured text. |
+| Visualize | Create interactive data visualizations.      |
+
+By combining these primitives, PromptQL can tackle complex analytical tasks. For example, it might extract structured
+data from a batch of documents, classify the results, and visualize the patterns...all in a single workflow. Or it could
+summarize a large dataset, then extract key metrics from those summaries for deeper analysis.
+
+These combinations aren't just powerful, they're precise. Each primitive builds on the others, with error checking and
+validation at every step. The result is reliable, reproducible analysis that can be turned into automated workflows.
+
+:::info Learn more
+
+You can learn more about these primitives [here](/promptql-apis/execute-program-api.mdx#introduction).
+
+:::
+
+### Artifacts
+
+Think of artifacts as PromptQL's memory system. When you're exploring data or building workflows, artifacts help
+maintain context and enable reuse.
+
+| Type          | Purpose                                  |
+| ------------- | ---------------------------------------- |
+| Table         | Store and reference structured data      |
+| Text          | Preserve documents and long-form content |
+| Visualization | Interactive charts and graphs            |
+| Automation    | Reusable, parameterized workflows        |
+
+:::info Learn more
+
+You can learn more about artifacts [here](/promptql-playground/artifacts.mdx).
+
+:::
+
+## Use cases
+
+### Make decisions
+
+When it comes to decision-making, PromptQL acts as your analytical partner. It can explore data, detect patterns,
+visualize trends, and run comparisons. Each analysis can be saved for future reference, shared with your team, or used
+as part of your audit trail.
+
+The key is that PromptQL doesn't just show you numbers: it helps you understand them. Ask it to explain its methodology,
+break down complex metrics, or look at the same data from different angles. It's built to clarify, not just calculate.
+
+[Learn more](/decision-making.mdx) about making decisions with PromptQL.
+
+### Automate tasks
+
+Once you've found a valuable analysis pattern, PromptQL can turn it into a reliable automation. These aren't just saved
+queries, but full workflows that can process new data, generate reports, monitor metrics, or alert on conditions.
+
+Each automation comes with built-in error handling and can be parameterized to handle different inputs. Chain them
+together for more complex operations, or schedule them to run regularly. The goal is to turn your one-off analyses into
+reliable, repeatable processes.
+
+[Learn more](/automation.mdx) about automating tasks with PromptQL.

docs/decision-making.mdx

@@ -0,0 +1,136 @@
+---
+sidebar_position: 1.7
+sidebar_label: Make Decisions
+description: "Learn how you can use PrompQL for accurate AI in your decision-making processes."
+keywords:
+  - promptql
+  - accurate
+  - reliable
+  - decision making
+toc_max_heading_level: 4
+---
+
+import Thumbnail from "@site/src/components/Thumbnail";
+
+# Make Decisions with PromptQL
+
+## Introduction
+
+**Decision making** with PromptQL supports deeper analysis and structured exploration across your data. You can ask
+complex, layered questions and get responses that adapt to your systems and terminology. PromptQL helps you drill into
+root causes, compare across categories, and evaluate tradeoffs without being limited by context windows or informal
+language.
+
+This is useful for scenarios that require exploration and judgment, such as:
+
+- Investigating anomalies
+- Comparing performance across teams or regions
+- Understanding contributing factors behind trends
+
+## Guides
+
+Below, we've split out a few different use cases as examples. You can run these against the `sandbox-movie-studio`
+[project](https://promptql.console.hasura.io/public/sandbox-movie-studio/playground).
+
+### Q&A
+
+Take this example:
+
+> _How did our PG-13 portfolio perform against R-rated titles during the streaming transition period?_
+
+It would seem that asking questions about data is simple, but this is difficult because business terms often map to
+multiple systems or concepts. For example, "performance" might refer to revenue, engagement, or critical ratings,
+depending on who’s asking. Systems don’t always agree on how those values are calculated, either.
+
+PromptQL solves this by mapping ambiguous terms to precise system definitions and building a plan that retrieves data
+from the right sources in the correct form. The generated plan accounts for relevant time windows, content ratings, and
+distribution channels, producing a structured answer tailored to your domain.
+
+<Thumbnail src="/img/get-started/playground-dm-streaming-results.png" alt="Details of a deployed automation." />
+
+**Use this when you want direct answers that reflect your business logic and definitions.**
+
+### Interrogation
+
+PromptQL allows you to interrogate your data by following up naturally, asking for more detail, and adjusting the scope
+as you go. The system preserves your analysis trail and ensures consistency across steps.
+
+> _Looking at our 2015–2020 release slate, what's the correlation between our talent investment strategy and audience
+> retention metrics?_
+
+PromptQL solves this by generating a multi-step plan that fetches relevant datasets, applies statistical methods, and
+structures results in a way that's easy to pivot or extend. You can modify thresholds, change groupings, or backtrack to
+explore a different angle—all without losing context.
+
+<Thumbnail src="/img/get-started/playground-interrogation.png" alt="Details of a deployed automation." />
+
+**Use this when a surface-level answer isn't enough and you need to go deeper with confidence.**
+
+:::tip Edit the query plan
+
+Most AI tools are a black box: you don't know what's happening under the hood, how answers were arrived upon, or what
+data was used.
+
+With PromptQL, every response is backed by a transparent query plan that you can inspect, modify, and re-run. This gives
+you full control over the logic, data sources, and assumptions behind each result—so you can refine, extend, or validate
+the analysis as needed.
+
+:::
+
+### Deep Research
+
+You can perform deep research that explores multiple hypotheses, benchmarks external data, and evaluates internal
+patterns across time or categories.
+
+> _Can you analyze the ROI patterns of our genre-blending titles compared to pure-genre releases between 2010–2020?_
+
+PromptQL is unique because it treats research as a process and not just a query. It generates a plan that defines
+discovery phases, collects and segments relevant data, and evaluates each hypothesis systematically.
+
+<Thumbnail src="/img/get-started/playground-deep-research.png" alt="Details of a deployed automation." />
+
+**Use this when you're trying to answer open-ended questions that require context and exploration.**
+
+### Cross-Source Intelligence
+
+Since you can join any source using your semantic metadata layer, PromptQL can resolve data across structured,
+semi-structured, and unstructured systems in a single plan.
+
+> _What's the risk profile of working with first-time directors who came from our star talent pool?_
+
+PromptQL builds a plan that pulls structured records (e.g., director metadata), aggregates historical performance
+metrics, and layers in qualitative signals from reviews or production notes. Relationships that span systems—like
+casting history, sentiment, and audience reception—are captured and evaluated together.
+
+<Thumbnail src="/img/get-started/playground-cross-source.png" alt="Details of a deployed automation." />
+
+**Use this when your answers require stitching together multiple systems and surfacing insights that aren't visible in
+any single source.**
+
+### Smart Visualizations
+
+Visualizations make it easy to understand complex patterns or communicate findings across stakeholders. PromptQL
+automatically selects appropriate formats—charts, tables, or graphs—based on the type and scale of your analysis.
+
+<Thumbnail src="/img/get-started/playground-visualization-rosling.png" alt="Details of a deployed automation." />
+
+**Use this when you want to share findings with others or spot trends across segments or time periods.**
+
+## Best Practices
+
+- **Start specific, then expand.** Narrow, well-defined questions help PromptQL build better initial plans. You can
+  always widen scope through follow-ups.
+- **Use your own terms.** PromptQL is designed to understand your internal terminology, so write queries as you would
+  naturally ask a colleague.
+- **Follow the thread.** PromptQL preserves your reasoning trail—feel free to pivot, rewind, or dig deeper without
+  losing previous steps.
+- **Review the plan.** Each result is backed by a structured plan. Reviewing it helps validate how PromptQL interprets
+  your intent.
+- **Use visualizations for communication.** When sharing results, use PromptQL’s built-in visualization capabilities to
+  highlight key insights clearly.
+
+## Next Steps
+
+It's great to be able to ask questions and get accurate, reliable responses. But, what if you could turn these into
+automations? Check out how easy PromptQL makes it to [automate tasks](/automation.mdx) with the same level of accuracy
+and reliability 🚀

docs/how-to-build-with-promptql/_category_.json

@@ -1,6 +1,6 @@
 {
   "label": "Build with PromptQL",
-  "position": 1,
+  "position": 2,
   "className": "basics-icon",
   "customProps": {
     "sidebar_pathname": "how-to-build-with-promptql"

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

@@ -0,0 +1,91 @@
+---
+sidebar_position: 1.6
+sidebar_label: Talk to PromptQL
+description: "Learn how to talk with your data via PromptQL."
+keywords:
+  - promptql
+  - accurate
+  - reliable
+  - how to
+toc_max_heading_level: 4
+---
+
+import Thumbnail from "@site/src/components/Thumbnail";
+
+# How to Talk to PromptQL
+
+## Introduction
+
+Talking to PromptQL is like onboarding a new teammate. It starts with limited knowledge—your Day-0 analyst, engineer, or
+ops assistant—and learns quickly through the questions you ask and the feedback you provide. The more you interact with
+it, the sharper and more context-aware it becomes. Your conversations aren't just about getting answers—they’re also
+shaping how PromptQL thinks about your business, your data, and your language.
+
+## Do's
+
+PromptQL works best when you treat it like a collaborator. Ask specific questions in natural language. There's no need
+to speak in SQL or use exact technical phrases. Just describe what you’re curious about.
+
+Examples:
+
+```plaintext
+Compare signups this quarter to last.
+Show me churn by region.
+Break this down by customer type.
+```
+
+It helps to add context, especially for company-specific terms, business rules, or timeframes. PromptQL will do its best
+to infer meaning, but your clarification speeds things up and improves accuracy.
+
+As you go, don’t hold back feedback. If an answer is off, say so. Corrections make it smarter. You can say:
+
+```plaintext
+That’s not what I meant.
+Can you explain how you got this?
+Try grouping it by year instead.
+Our fiscal year starts in February.
+```
+
+The more you interact, the better PromptQL gets at understanding your definitions, your patterns, and your expectations.
+It remembers what you correct. It learns how you ask.
+
+You can also ask for visualizations, request alternate views of the same data, or specify how you'd like results
+returned:
+
+```plaintext
+Show a chart of the trend.
+Group by location and limit to the top 10.
+```
+
+If you're unsure about terminology, just ask. PromptQL can define terms or explain metrics. It’s built to clarify, not
+confuse.
+
+## Don'ts
+
+Don’t expect one-shot perfection in the beginning. PromptQL thrives in back-and-forth exchanges. It doesn't retain prior
+conversation context unless you reference it, so always restate key details when continuing a line of inquiry or use an
+artifact to start a new chat.
+
+Avoid assuming it can access anything outside of your connected schema. It can’t pull in external files, ping APIs, or
+generate real-world updates from news or financial markets...unless you've added this functionality!
+
+You _should_ use niche or complex domain terms—just be ready to explain them the first time. This helps PromptQL learn
+your vocabulary and makes future conversations smoother. If it gets something wrong:
+
+```plaintext
+That’s not what “churn risk” means for us.
+In our case, “premium” refers to the paid tier only.
+```
+
+This is how PromptQL builds context over time, adapting to your business.
+
+## Next Steps
+
+The best way to get started is to ask something simple but real. Start with a metric you track regularly, or recreate an
+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.
+
+Jump into one of these use cases:
+
+- [Making decisions](/decision-making.mdx)
+- [Automating tasks](/automation.mdx)