intraq-dev-ai · intraq-dev-ai · Jul 27, 2026 · Jul 26, 2026 · Jul 26, 2026
diff --git a/COMMERCIAL.md b/COMMERCIAL.md
@@ -9,6 +9,9 @@ implementation/operations, or use in a competing commercial analytics, BI,
 dashboard, SQL-assistant, or AI-reporting service requires an IntraQ commercial
 agreement.
 
+For commercial licensing, contact the maintainers through the commercial channel
+published for the project or through `hello@intraq.dev`.
+
 ## Included
 
 - Dashboards, Dashboard Builder, Analyzer, SQL Editor, data sources, data

diff --git a/LICENSE.md b/LICENSE.md
@@ -13,10 +13,41 @@ fork, modify, and self-host IntraQ for permitted uses while reserving commercial
 managed-service, resale, white-label, OEM, and competing-service rights for
 IntraQ.
 
+## Acceptance
+
+By using, copying, modifying, distributing, making available, or running this
+software, you agree to the terms of this license.
+
+If you do not agree to these terms, you may not use, copy, modify, distribute,
+make available, or run this software.
+
+## Definitions
+
+"Licensor" means the copyright holder or entity offering this software under
+this license.
+
+"Software" means the IntraQ source code and related files made available in this
+repository, except third-party components or files that expressly state a
+different license.
+
+"You" means the individual or legal entity exercising permissions under this
+license.
+
+"Your company" means any legal entity, sole proprietorship, or organization that
+you work for, plus any entity that controls, is controlled by, or is under common
+control with that entity.
+
+"Competing service" means a commercial product or service whose primary purpose
+is to provide analytics, business intelligence, dashboards, AI reporting, SQL
+assistant, data assistant, embedded analytics, or managed analytics
+functionality to third parties.
+
 ## Grant
 
-Subject to this license, you may use, copy, modify, fork, and run this software
-for:
+Subject to this license, the Licensor grants you a non-exclusive, royalty-free,
+worldwide, non-sublicensable, non-transferable license to use, copy, modify,
+fork, run, distribute, make available, and prepare derivative works of the
+Software only for:
 
 - internal business use;
 - personal use;
@@ -46,6 +77,14 @@ Without a separate written commercial agreement with IntraQ, you may not:
 - use IntraQ names, logos, or trademarks except to identify the original
   project and preserve notices.
 
+## Notices
+
+You must ensure that anyone who receives a copy of any part of the Software from
+you also receives this license.
+
+You may not alter, remove, or obscure any copyright, trademark, license, or
+attribution notices in the Software.
+
 ## Contributions And Modifications
 
 You may create and use modifications under this license. If you distribute
@@ -55,12 +94,42 @@ has been modified.
 Unless a separate written contributor agreement says otherwise, contributions
 submitted to this repository are provided under this same license.
 
+## Patents
+
+The Licensor grants you a license under any patent claims the Licensor can
+license, or later becomes able to license, to make, have made, use, sell, offer
+for sale, import, and have imported the Software, in each case only as permitted
+by this license.
+
+This patent license does not cover patent claims that you or your company cause
+to be infringed by modifications, additions, or combinations you make to the
+Software.
+
+If you or your company make a written claim that the Software infringes or
+contributes to infringement of any patent, your patent license under this
+license ends immediately.
+
 ## Third-Party Software
 
 This repository may depend on third-party software with separate licenses. Those
 licenses apply to the relevant third-party packages and are not changed by this
 license.
 
+## Termination
+
+If you use the Software in violation of this license, that use is not licensed
+and your license automatically terminates.
+
+If the Licensor notifies you of a violation and you stop all violation within 30
+days after receiving notice, your license is reinstated retroactively. If you
+violate this license again after reinstatement, your license terminates
+automatically and permanently.
+
+## No Other Rights
+
+This license does not grant any rights other than those expressly stated in this
+license. All rights not expressly granted are reserved by the Licensor.
+
 ## No Warranty
 
 The software is provided "as is", without warranty of any kind, express or

diff --git a/README.md b/README.md
@@ -1,50 +1,100 @@
-# intraQ
+# IntraQ – Self-hosted AI Dashboard Builder & Natural Language SQL
 
-[Website](https://intraq.dev)
+[![CI](https://github.com/intraq-dev-ai/intraq/actions/workflows/ci.yml/badge.svg)](https://github.com/intraq-dev-ai/intraq/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-IntraQ%20Sustainable%20Use-blue)](LICENSE.md)
+[![Docker](https://img.shields.io/badge/docker-compose-2496ED?logo=docker&logoColor=white)](docker-compose.yml)
+[![Node](https://img.shields.io/badge/node-24.x-339933?logo=node.js&logoColor=white)](.nvmrc)
 
-intraQ is a source-available AI reporting and dashboard platform for
-self-hosted operational analytics.
+[Website](https://intraq.dev) · [Docs](docs/DEMO_GUIDE.md) · [Quickstart](QUICKSTART.md) · [Configuration](docs/CONFIGURATION.md) · [Contributing](CONTRIBUTING.md)
 
-It includes local dashboards, Analyzer, SQL models, MCP, data-source management,
-and dashboard-builder workflows.
+**IntraQ is a source-available AI business intelligence platform that lets teams query SQL-backed operational data using natural language, generate trusted SQL, and build interactive dashboards without traditional BI complexity.**
 
-AI is grounded in local metadata, data dictionary entries, SQL models,
-relationships, dashboard context, and safe result summaries. This source tree
-intentionally excludes the paid AI Studio, proprietary domain intelligence,
-control plane, paid release tooling, private operational docs, generated
-artifacts, credentials, and private operational material.
+It combines AI analytics, natural language SQL, text-to-SQL workflows, an AI dashboard builder, embedded analytics foundations, MCP tools, RAG-style context retrieval, and a semantic layer built from local metadata, data dictionary entries, SQL models, relationships, dashboard context, and safe result summaries.
 
 ![intraQ dashboard builder with AI sidebar](docs/assets/demo/00-readme-hero-ai-sidebar.png)
 
-## License
+## Why teams use intraQ
+
+- **AI business intelligence** — ask operational questions in plain English.
+- **Trusted SQL generation** — inspect SQL and evidence before publishing results.
+- **AI dashboard builder** — turn answers into reusable dashboards.
+- **Self-hosted BI** — run with Docker Compose against your own database.
+- **Semantic layer** — define tables, fields, joins, metrics, and business meaning.
+- **LLM-ready context** — ground answers in local metadata and RAG-style knowledge retrieval.
+- **Embedded analytics foundation** — use intraQ as a reporting layer for product and internal workflows.
+- **Provider-flexible AI** — configure Codex OAuth, OpenAI, or Gemini from the admin UI.
+
+## Demo flow
+
+```text
+Ask a business question
+        ↓
+AI plans against metadata and SQL models
+        ↓
+Trusted SQL is generated and executed
+        ↓
+The answer returns with evidence
+        ↓
+Save the result as a live dashboard component
+```
 
-intraQ is source-available under the IntraQ Sustainable Use License.
+Use the seeded demo to try questions such as:
+
+- `How is revenue trending by day?`
+- `Which channel has the highest revenue?`
+- `Compare revenue and gross margin by category.`
+- `Which location has the highest average order value?`
+- `Create a dashboard chart for revenue by channel.`
+
+See the full [Demo guide](docs/DEMO_GUIDE.md).
+
+## Architecture
+
+```text
+User question
+  → AI Analyzer
+  → Metadata + semantic model + saved SQL models
+  → SQL planning and validation
+  → Connected operational database
+  → Result summary + evidence
+  → Dashboard Builder
+  → Saved live dashboard
+```
+
+The public source includes local dashboards, Analyzer, SQL models, MCP, data-source management, and dashboard-builder workflows.
+
+It intentionally excludes paid AI Studio, proprietary domain intelligence, control plane, paid release tooling, private operational docs, generated artifacts, credentials, and private operational material.
+
+## Use cases and knowledge bases
 
-You may use, fork, modify, and run intraQ for internal business, personal,
-educational, evaluation, and non-commercial purposes.
+intraQ is built for operational reporting where users need more than static charts:
 
-Paid hosting, managed service use, white-label resale, OEM redistribution, paid
-third-party support/operations, or use in a competing commercial analytics, BI,
-dashboard, SQL-assistant, or AI-reporting service requires a commercial
-agreement with IntraQ.
+- **Hospitality analytics** — revenue health, covers, product mix, wastage signals, outlet performance, PMS and POS reporting.
+- **Energy retail reporting** — accounts, billing cycles, arrears, credit exposure, payments, exceptions, and customer risk.
+- **SaaS embedded analytics** — customer-facing dashboards over product data.
+- **Ecommerce analytics** — revenue, orders, products, channels, margins, and customer behavior.
 
-See [LICENSE.md](LICENSE.md) and [COMMERCIAL.md](COMMERCIAL.md).
+Explore practical question sets in [`examples/`](examples/README.md).
 
-## Public Source Scope
+## Comparisons
 
-This repository is the generalized public source package. It excludes
-non-public material, private operational docs, paid AI Studio, proprietary
-domain packs, feedback learning loops, eval pipelines, multi-tenant governance,
-billing, and managed-service code.
+intraQ is not trying to replace every enterprise reporting suite. It is focused on operational BI workflows where teams want AI-assisted SQL, local control, and dashboards from governed data models.
 
-See [docs/PUBLIC_SOURCE_SCOPE.md](docs/PUBLIC_SOURCE_SCOPE.md), [CONTRIBUTING.md](CONTRIBUTING.md),
-and [SUPPORT.md](SUPPORT.md).
+### intraQ vs Power BI
 
-## Requirements
+Power BI is a broad reporting suite. intraQ focuses on natural language SQL, evidence-backed AI answers, and turning operational questions into live dashboard components from SQL-backed models.
 
-- Node.js 24 LTS. This repo pins `24.16.0` in `.nvmrc` and `.node-version`.
-- npm 11.12+.
-- PostgreSQL 14+.
+### intraQ vs Metabase
+
+Metabase is strong for self-service querying and dashboards. intraQ adds an AI Analyzer and dashboard-builder workflow designed around plain-English questions, trusted SQL generation, and evidence review.
+
+### intraQ vs Looker
+
+Looker centers on governed semantic modeling at enterprise scale. intraQ is lighter to run locally and focuses on operational teams that want AI-assisted reporting over existing SQL data.
+
+### intraQ vs Sigma Computing
+
+Sigma provides spreadsheet-style cloud analytics. intraQ focuses on self-hosted or controlled deployments, natural language SQL, and operational dashboards grounded in local metadata and models.
 
 ## Quickstart
 
@@ -57,6 +107,12 @@ docker compose up --build
 
 Then open `http://localhost:4100`.
 
+Seeded local login:
+
+| Email | Password |
+|---|---|
+| `admin@local.intraq.test` | `intraq-demo` |
+
 For local development without Docker:
 
 ```bash
@@ -80,11 +136,9 @@ npm run db:seed
 npm run dev
 ```
 
-Seeded local login:
+More setup detail is in [QUICKSTART.md](QUICKSTART.md). Environment variables are documented in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 
-| Email | Password |
-|---|---|
-| `admin@local.intraq.test` | `intraq-demo` |
+AI provider setup for Codex OAuth, OpenAI, and Gemini is documented in [docs/AI_PROVIDER_SETUP.md](docs/AI_PROVIDER_SETUP.md). For Codex OAuth browser login, set `OPENAI_OAUTH_CLIENT_ID` in the API environment; otherwise the admin page cannot start the Codex login flow.
 
 ## Development
 
@@ -93,24 +147,31 @@ npm test
 npm run build
 ```
 
-Copy `.env.example` to `.env` for local development. Do not commit local env
-files, database passwords, provider keys, client data, or private operational
-material.
-
-More setup detail is in [QUICKSTART.md](QUICKSTART.md). Environment variables
-are documented in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
-
-AI provider setup for Codex OAuth, OpenAI, and Gemini is documented in
-[docs/AI_PROVIDER_SETUP.md](docs/AI_PROVIDER_SETUP.md).
-For Codex OAuth browser login, set `OPENAI_OAUTH_CLIENT_ID` in the API
-environment; otherwise the admin page cannot start the Codex login flow.
-
-The seeded product demo and suggested walkthrough videos are documented in
-[docs/DEMO_GUIDE.md](docs/DEMO_GUIDE.md).
+Copy `.env.example` to `.env` for local development. Do not commit local env files, database passwords, provider keys, client data, or private operational material.
 
 Focused workflow docs:
 
-- [MCP tools](docs/MCP.md)
 - [AI Analyzer](docs/AI_ANALYZER.md)
 - [Dashboard Builder](docs/DASHBOARD_BUILDER.md)
 - [SQL Editor](docs/SQL_EDITOR.md)
+- [MCP tools](docs/MCP.md)
+- [AI provider setup](docs/AI_PROVIDER_SETUP.md)
+- [Publication checklist](docs/PUBLICATION_CHECKLIST.md)
+
+## License and public source scope
+
+intraQ is source-available under the IntraQ Sustainable Use License.
+
+You may use, fork, modify, and run intraQ for internal business, personal, educational, evaluation, and non-commercial purposes.
+
+Paid hosting, managed service use, white-label resale, OEM redistribution, paid third-party support/operations, or use in a competing commercial analytics, BI, dashboard, SQL-assistant, or AI-reporting service requires a commercial agreement with IntraQ.
+
+See [LICENSE.md](LICENSE.md), [COMMERCIAL.md](COMMERCIAL.md), [docs/PUBLIC_SOURCE_SCOPE.md](docs/PUBLIC_SOURCE_SCOPE.md), [CONTRIBUTING.md](CONTRIBUTING.md), and [SUPPORT.md](SUPPORT.md).
+
+## Suggested GitHub topics
+
+Recommended repository topics:
+
+`ai-analytics`, `ai-bi`, `llm`, `rag`, `semantic-model`, `semantic-layer`, `business-intelligence`, `analytics-platform`, `ai-dashboard`, `ai-dashboard-builder`, `text-to-sql`, `dashboard-builder`, `self-hosted`, `postgres`, `sql`, `embedded-analytics`, `reporting`, `natural-language-sql`, `natural-language-query`, `operational-analytics`
+
+Use `agentic-ai` only if you want the repository positioned around autonomous multi-step AI planning. If the public source is presented mainly as governed AI reporting and dashboard generation, the topics above are more precise.