From 4e767f668566d11c74088d0541054cf64e3ee6e8 Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Thu, 3 Jul 2025 17:59:58 +0400
Subject: [PATCH 1/3] improve concept docs structure

---
 docs/StardustDocs/c.list                      |   2 +-
 docs/StardustDocs/d.tree                      |  22 +--
 docs/StardustDocs/images/github-mark.svg      |   1 +
 docs/StardustDocs/topics/ColumnSelectors.md   |   8 +-
 docs/StardustDocs/topics/Home.topic           |   3 +-
 docs/StardustDocs/topics/Support.md           |  14 ++
 .../topics/{ => concepts}/DataColumn.md       |   0
 .../topics/{ => concepts}/DataFrame.md        |   0
 .../topics/{ => concepts}/DataRow.md          |   0
 .../DataSchemaGenerationGradle.md}            |   2 +-
 .../DataSchemaGenerationMethods.md}           |   2 +-
 .../topics/{ => concepts}/apiLevels.md        |   0
 docs/StardustDocs/topics/concepts/concepts.md |  62 +++++++
 .../{ => concepts}/extensionPropertiesApi.md  |   2 +-
 .../topics/{ => concepts}/hierarchical.md     |   0
 .../topics/{ => concepts}/nanAndNa.md         |   0
 .../{ => concepts}/numberUnification.md       |   0
 .../topics/{ => concepts}/schemas.md          |   0
 .../topics/{ => concepts}/schemasCustom.md    |   0
 .../{ => concepts}/schemasExternalJupyter.md  |   0
 .../topics/{ => concepts}/schemasGradle.md    |   2 +-
 .../schemasImportOpenApiGradle.md             |   0
 .../schemasImportOpenApiJupyter.md            |   0
 .../{ => concepts}/schemasImportSqlGradle.md  |   0
 .../{ => concepts}/schemasInheritance.md      |   0
 .../topics/{ => concepts}/schemasJupyter.md   |   0
 .../topics/{ => concepts}/stringApi.md        |   0
 .../topics/{ => concepts}/types.md            |   0
 docs/StardustDocs/topics/guides/quickstart.md |   2 +-
 docs/StardustDocs/topics/overview.md          | 174 ------------------
 30 files changed, 99 insertions(+), 197 deletions(-)
 create mode 100644 docs/StardustDocs/images/github-mark.svg
 create mode 100644 docs/StardustDocs/topics/Support.md
 rename docs/StardustDocs/topics/{ => concepts}/DataColumn.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/DataFrame.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/DataRow.md (100%)
 rename docs/StardustDocs/topics/{gradleReference.md => concepts/DataSchemaGenerationGradle.md} (99%)
 rename docs/StardustDocs/topics/{DataSchema-Data-Classes-Generation.md => concepts/DataSchemaGenerationMethods.md} (99%)
 rename docs/StardustDocs/topics/{ => concepts}/apiLevels.md (100%)
 create mode 100644 docs/StardustDocs/topics/concepts/concepts.md
 rename docs/StardustDocs/topics/{ => concepts}/extensionPropertiesApi.md (98%)
 rename docs/StardustDocs/topics/{ => concepts}/hierarchical.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/nanAndNa.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/numberUnification.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/schemas.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/schemasCustom.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/schemasExternalJupyter.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/schemasGradle.md (97%)
 rename docs/StardustDocs/topics/{ => concepts}/schemasImportOpenApiGradle.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/schemasImportOpenApiJupyter.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/schemasImportSqlGradle.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/schemasInheritance.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/schemasJupyter.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/stringApi.md (100%)
 rename docs/StardustDocs/topics/{ => concepts}/types.md (100%)
 delete mode 100644 docs/StardustDocs/topics/overview.md

diff --git a/docs/StardustDocs/c.list b/docs/StardustDocs/c.list
index 8339a6eb7d..c6b6e77626 100644
--- a/docs/StardustDocs/c.list
+++ b/docs/StardustDocs/c.list
@@ -2,5 +2,5 @@
 <!DOCTYPE categories
         SYSTEM "https://resources.jetbrains.com/writerside/1.0/categories.dtd">
 <categories>
-
+    <category id="related" name="Related topics" order="1"/>
 </categories>
diff --git a/docs/StardustDocs/d.tree b/docs/StardustDocs/d.tree
index df5b058681..b6d1cef5c0 100644
--- a/docs/StardustDocs/d.tree
+++ b/docs/StardustDocs/d.tree
@@ -21,12 +21,19 @@
         <toc-element topic="gettingStartedDatalore.md"/>
         <toc-element topic="gettingStartedGradleAdvanced.md"/>
     </toc-element>
-    <toc-element topic="overview.md">
+    <toc-element topic="concepts.md">
         <toc-element topic="apiLevels.md">
             <toc-element topic="stringApi.md"/>
             <toc-element topic="extensionPropertiesApi.md"/>
         </toc-element>
+        <toc-element topic="types.md">
+            <toc-element topic="DataFrame.md"/>
+            <toc-element topic="DataColumn.md"/>
+            <toc-element topic="DataRow.md"/>
+        </toc-element>
         <toc-element topic="hierarchical.md"/>
+        <toc-element topic="nanAndNa.md"/>
+        <toc-element topic="numberUnification.md"/>
         <toc-element topic="schemas.md">
             <toc-element topic="schemasGradle.md"/>
             <toc-element topic="schemasJupyter.md"/>
@@ -36,20 +43,15 @@
             <toc-element topic="schemasImportSqlGradle.md"/>
             <toc-element topic="schemasImportOpenApiGradle.md"/>
             <toc-element topic="schemasImportOpenApiJupyter.md"/>
+            <toc-element topic="DataSchemaGenerationMethods.md"/>
+            <toc-element topic="DataSchemaGenerationGradle.md"/>
         </toc-element>
     </toc-element>
-    <toc-element topic="types.md">
-        <toc-element topic="DataFrame.md"/>
-        <toc-element topic="DataColumn.md"/>
-        <toc-element topic="DataRow.md"/>
-    </toc-element>
     <toc-element topic="Compiler-Plugin.md">
         <toc-element topic="staticInterpretation.md"/>
         <toc-element topic="dataSchema.md"/>
         <toc-element topic="compilerPluginExamples.md"/>
     </toc-element>
-    <toc-element topic="nanAndNa.md"/>
-    <toc-element topic="numberUnification.md"/>
     <toc-element topic="operations.md">
         <toc-element topic="create.md">
             <toc-element topic="createColumn.md" toc-title="DataColumn"/>
@@ -199,8 +201,6 @@
             <toc-element topic="jupyterRendering.md"/>
         </toc-element>
     </toc-element>
-    <toc-element topic="DataSchema-Data-Classes-Generation.md">
-        <toc-element topic="gradleReference.md"/>
-    </toc-element>
     <toc-element topic="_shadow_resources.md" hidden="true"/>
+    <toc-element topic="Support.md"/>
 </instance-profile>
diff --git a/docs/StardustDocs/images/github-mark.svg b/docs/StardustDocs/images/github-mark.svg
new file mode 100644
index 0000000000..37fa923df3
--- /dev/null
+++ b/docs/StardustDocs/images/github-mark.svg
@@ -0,0 +1 @@
+<svg width="98" height="96" xmlns="http://www.w3.org/2000/svg"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="#24292f"/></svg>
\ No newline at end of file
diff --git a/docs/StardustDocs/topics/ColumnSelectors.md b/docs/StardustDocs/topics/ColumnSelectors.md
index 0f571f0cbc..75f91fccb1 100644
--- a/docs/StardustDocs/topics/ColumnSelectors.md
+++ b/docs/StardustDocs/topics/ColumnSelectors.md
@@ -260,7 +260,7 @@ For instance, excluding `userData.age`:
 `df.select { colsAtAnyDepth { "a" in it.name() } except userData.age }`
 
 Note that the selection of columns to exclude from column sets is always done relative to the outer scope.
-Use the [Extension Properties API](extensionPropertiesApi.md) to prevent scoping issues if possible.
+Use the [Extension Properties API](concepts/extensionPropertiesApi.md) to prevent scoping issues if possible.
 
 > Special case: If a column that needs to be removed appears multiple times in the [`ColumnSet`](#column-resolvers),
 > it is excepted each time it is encountered (including inside [Column Groups](DataColumn.md#columngroup)).
@@ -392,11 +392,11 @@ This function behaves the same as [`cols {}` and `[{}]`](ColumnSelectors.md#cols
 Creates a [`ColumnSet`](#column-resolvers) containing the columns from both the left and right side of the function. This allows
 you to combine selections or simply select multiple columns at once.
 
-Any combination of [AccessApi](apiLevels.md) can be used on either side of the `and` operator.
+Any combination of [AccessApi](concepts/apiLevels.md) can be used on either side of the `and` operator.
 
 Note, while you can write `col1 and col2 and col3...`, it may be more concise to use
 [`cols(col1, col2, col3...)`](ColumnSelectors.md#cols) instead. The only downside is that you can't mix
-[Access APIs](apiLevels.md) with that notation.
+[Access APIs](concepts/apiLevels.md) with that notation.
 
 ##### Rename {collapsible="true"}
 `colA named "colB"`, `colA into namedColAccessor`
@@ -404,7 +404,7 @@ Note, while you can write `col1 and col2 and col3...`, it may be more concise to
 Renaming a column in the Columns Selection DSL is done by calling the infix functions 
 `named` or `into`.
 They behave exactly the same, so it's up to contextual preference which one to use.
-Any combination of [Access API](apiLevels.md) can be used to specify the column to rename 
+Any combination of [Access API](concepts/apiLevels.md) can be used to specify the column to rename 
 and which name should be used instead.
 
 ##### Expr (Column Expression) {collapsible="true"}
diff --git a/docs/StardustDocs/topics/Home.topic b/docs/StardustDocs/topics/Home.topic
index b38d03a630..27cec9353e 100644
--- a/docs/StardustDocs/topics/Home.topic
+++ b/docs/StardustDocs/topics/Home.topic
@@ -20,7 +20,7 @@
         <primary>
             <title>First steps</title>
             <a href="gettingStartedKotlinNotebook.md"/>
-            <a href="overview.md"/>
+            <a href="concepts.md"/>
             <a href="operations.md"/>
             <a href="read.md">Reading from files: CSV, JSON, ApacheArrow</a>
         </primary>
@@ -32,7 +32,6 @@
             <a href="readSqlDatabases.md"/>
         </secondary>
 
-
     </section-starting-page>
 
 
diff --git a/docs/StardustDocs/topics/Support.md b/docs/StardustDocs/topics/Support.md
new file mode 100644
index 0000000000..3a54fb0b61
--- /dev/null
+++ b/docs/StardustDocs/topics/Support.md
@@ -0,0 +1,14 @@
+# Support
+
+* <img src="github-mark.svg" alt="GitHub logo" height="24"/> 
+[**Issue Tracker**](https://github.com/Kotlin/dataframe/issues)
+
+   If you find a bug or have an idea for a new feature, 
+   file an issue in our [DataFrame GitHub repository](https://github.com/Kotlin/dataframe).
+
+* <img src="https://kotlinlang.org/docs/images/slack.svg" alt="Slack logo" height="24"/> 
+[**Community**](https://github.com/Kotlin/dataframe/issues)
+
+  Peer-to-peer support is available on the Kotlin Slack
+  [#datascience](https://kotlinlang.slack.com/archives/C4W52CFEZ) channel
+  ([request an invite](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up?_gl=1*1ssyqy3*_gcl_au*MTk5NzUwODYzOS4xNzQ2NzkxMDMz*FPAU*MTk5NzUwODYzOS4xNzQ2NzkxMDMz*_ga*MTE0ODQ1MzY3OS4xNzM4OTY1NzM3*_ga_9J976DJZ68*czE3NTE1NDUxODUkbzIyNyRnMCR0MTc1MTU0NTE4NSRqNjAkbDAkaDA.)).
diff --git a/docs/StardustDocs/topics/DataColumn.md b/docs/StardustDocs/topics/concepts/DataColumn.md
similarity index 100%
rename from docs/StardustDocs/topics/DataColumn.md
rename to docs/StardustDocs/topics/concepts/DataColumn.md
diff --git a/docs/StardustDocs/topics/DataFrame.md b/docs/StardustDocs/topics/concepts/DataFrame.md
similarity index 100%
rename from docs/StardustDocs/topics/DataFrame.md
rename to docs/StardustDocs/topics/concepts/DataFrame.md
diff --git a/docs/StardustDocs/topics/DataRow.md b/docs/StardustDocs/topics/concepts/DataRow.md
similarity index 100%
rename from docs/StardustDocs/topics/DataRow.md
rename to docs/StardustDocs/topics/concepts/DataRow.md
diff --git a/docs/StardustDocs/topics/gradleReference.md b/docs/StardustDocs/topics/concepts/DataSchemaGenerationGradle.md
similarity index 99%
rename from docs/StardustDocs/topics/gradleReference.md
rename to docs/StardustDocs/topics/concepts/DataSchemaGenerationGradle.md
index b5fe5f0f77..e912ebe1ae 100644
--- a/docs/StardustDocs/topics/gradleReference.md
+++ b/docs/StardustDocs/topics/concepts/DataSchemaGenerationGradle.md
@@ -1,4 +1,4 @@
-[//]: # (title: Gradle plugin reference)
+[//]: # (title: Data Shemas Generation in Gradle)
 
 This page describes the Gradle plugin that generates `@DataSchema` from data samples.
 ```Kotlin
diff --git a/docs/StardustDocs/topics/DataSchema-Data-Classes-Generation.md b/docs/StardustDocs/topics/concepts/DataSchemaGenerationMethods.md
similarity index 99%
rename from docs/StardustDocs/topics/DataSchema-Data-Classes-Generation.md
rename to docs/StardustDocs/topics/concepts/DataSchemaGenerationMethods.md
index d5faa6c626..602c66db6e 100644
--- a/docs/StardustDocs/topics/DataSchema-Data-Classes-Generation.md
+++ b/docs/StardustDocs/topics/concepts/DataSchemaGenerationMethods.md
@@ -1,4 +1,4 @@
-# Data Schemas/Data Classes Generation
+# Data Schemas Generation From Existing DataFrame
 
 <web-summary>
 Generate useful Kotlin definitions based on your DataFrame structure.
diff --git a/docs/StardustDocs/topics/apiLevels.md b/docs/StardustDocs/topics/concepts/apiLevels.md
similarity index 100%
rename from docs/StardustDocs/topics/apiLevels.md
rename to docs/StardustDocs/topics/concepts/apiLevels.md
diff --git a/docs/StardustDocs/topics/concepts/concepts.md b/docs/StardustDocs/topics/concepts/concepts.md
new file mode 100644
index 0000000000..77aa147a24
--- /dev/null
+++ b/docs/StardustDocs/topics/concepts/concepts.md
@@ -0,0 +1,62 @@
+# Concepts And Principles
+
+<web-summary>
+Learn what Kotlin DataFrame is about — its core concepts, design principles, and usage philosophy.
+</web-summary>
+
+<card-summary>
+Discover the fundamentals of the library —
+understand key concepts, motivation, and the overall structure of the library.
+</card-summary>
+
+<link-summary>
+Explore the fundamentals of Kotlin DataFrame — 
+understand key concepts, motivation, and the overall structure of the library.
+</link-summary>
+
+
+<show-structure depth="3"/>
+
+
+## What is Dataframe
+
+Dataframe is an abstraction for working with structured data. 
+Essentially, it’s a 2-dimensional table with labeled columns of potentially different types. 
+You can think of it like a spreadsheet or SQL table, or a dictionary of series objects.
+
+The handiness of this abstraction is not in the table itself but in a set of operations defined on it. 
+The Kotlin DataFrame library is an idiomatic Kotlin DSL defining such operations. 
+The process of working with dataframe is often called *data wrangling* which 
+is the process of transforming and mapping data from one "raw" data form into another format 
+that is more appropriate for analytics and visualization. 
+The goal of data wrangling is to ensure quality and useful data.
+
+## Main Features and Concepts
+
+* [**Hierarchical**](hierarchical.md) — the Kotlin DataFrame library provides an ability to read and present data from different sources, 
+including not only plain **CSV** but also **JSON** or **[SQL databases](readSqlDatabases.md)**.
+This is why it was designed to be hierarchical and allows nesting of columns and cells.
+* **Functional** — the data processing pipeline is organized in a chain of [`DataFrame`](DataFrame.md)  transformation operations.
+* **Immutable** — every operation returns a new instance of [`DataFrame`](DataFrame.md)  reusing underlying storage wherever it's possible.
+* **Readable** — data transformation operations are defined in DSL close to natural language.
+* **Practical** — provides simple solutions for common problems and the ability to perform complex tasks.
+* **Minimalistic** — simple, yet powerful data model of three [column kinds](DataColumn.md#column-kinds).
+* [**Interoperable**](collectionsInterop.md) — convertable with Kotlin data classes and collections.
+  This also means conversion to/from other libraries' data structures is usually quite straightforward!
+  See our [examples](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples) 
+  for some conversions between DataFrame and [Apache Spark](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/spark), [Multik](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/multik), and [JetBrains Exposed](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/exposed).
+* **Generic** — can store objects of any type, not only numbers or strings.
+* **Typesafe** — the Kotlin DataFrame library provides a mechanism of on-the-fly [**generation of extension properties**](extensionPropertiesApi.md) 
+that correspond to the columns of a dataframe. 
+In interactive notebooks like Jupyter or Datalore, the generation runs after each cell execution. 
+In IntelliJ IDEA there's a Gradle plugin for generation properties based on CSV file or JSON file. 
+Also, we’re working on a compiler plugin that infers and transforms [`DataFrame`](DataFrame.md) schema while typing.
+You can now clone this [project with many examples](https://github.com/koperagen/df-plugin-demo) showcasing how it allows you to reliably use our most convenient extension properties API.
+The generated properties ensure you’ll never misspell column name and don’t mess up with its type, and of course nullability is also preserved.
+* [**Polymorphic**](schemas.md) —
+  if all columns of a [`DataFrame`](DataFrame.md) instance are presented in another dataframe,
+  then the first one will be seen as a superclass for the latter. 
+This means you can define a function on an interface with some set of columns
+  and then execute it safely on any [`DataFrame`](DataFrame.md) which contains this same set of columns.
+  In notebooks, this works out-of-the-box.
+  In ordinary projects, this requires casting (for now).
diff --git a/docs/StardustDocs/topics/extensionPropertiesApi.md b/docs/StardustDocs/topics/concepts/extensionPropertiesApi.md
similarity index 98%
rename from docs/StardustDocs/topics/extensionPropertiesApi.md
rename to docs/StardustDocs/topics/concepts/extensionPropertiesApi.md
index 0df47d6aa8..41c79591eb 100644
--- a/docs/StardustDocs/topics/extensionPropertiesApi.md
+++ b/docs/StardustDocs/topics/concepts/extensionPropertiesApi.md
@@ -104,7 +104,7 @@ See the [](quickstart.md) in Kotlin Notebook with basic Extension Properties API
 <tab title="Compiler Plugin">
 
 For now, if you read [`DataFrame`](DataFrame.md) from a file or URL, you need to define its schema manually. 
-You can do it quickly with [`generate..()` methods](DataSchema-Data-Classes-Generation.md).
+You can do it quickly with [`generate..()` methods](DataSchemaGenerationMethods.md).
 
 Define schemas:
 ```kotlin
diff --git a/docs/StardustDocs/topics/hierarchical.md b/docs/StardustDocs/topics/concepts/hierarchical.md
similarity index 100%
rename from docs/StardustDocs/topics/hierarchical.md
rename to docs/StardustDocs/topics/concepts/hierarchical.md
diff --git a/docs/StardustDocs/topics/nanAndNa.md b/docs/StardustDocs/topics/concepts/nanAndNa.md
similarity index 100%
rename from docs/StardustDocs/topics/nanAndNa.md
rename to docs/StardustDocs/topics/concepts/nanAndNa.md
diff --git a/docs/StardustDocs/topics/numberUnification.md b/docs/StardustDocs/topics/concepts/numberUnification.md
similarity index 100%
rename from docs/StardustDocs/topics/numberUnification.md
rename to docs/StardustDocs/topics/concepts/numberUnification.md
diff --git a/docs/StardustDocs/topics/schemas.md b/docs/StardustDocs/topics/concepts/schemas.md
similarity index 100%
rename from docs/StardustDocs/topics/schemas.md
rename to docs/StardustDocs/topics/concepts/schemas.md
diff --git a/docs/StardustDocs/topics/schemasCustom.md b/docs/StardustDocs/topics/concepts/schemasCustom.md
similarity index 100%
rename from docs/StardustDocs/topics/schemasCustom.md
rename to docs/StardustDocs/topics/concepts/schemasCustom.md
diff --git a/docs/StardustDocs/topics/schemasExternalJupyter.md b/docs/StardustDocs/topics/concepts/schemasExternalJupyter.md
similarity index 100%
rename from docs/StardustDocs/topics/schemasExternalJupyter.md
rename to docs/StardustDocs/topics/concepts/schemasExternalJupyter.md
diff --git a/docs/StardustDocs/topics/schemasGradle.md b/docs/StardustDocs/topics/concepts/schemasGradle.md
similarity index 97%
rename from docs/StardustDocs/topics/schemasGradle.md
rename to docs/StardustDocs/topics/concepts/schemasGradle.md
index 0296bcc0f7..609d43facf 100644
--- a/docs/StardustDocs/topics/schemasGradle.md
+++ b/docs/StardustDocs/topics/concepts/schemasGradle.md
@@ -131,7 +131,7 @@ dataframes {
 }
 ```
 
-See [reference](gradleReference.md) and [examples](gradleReference.md#examples) for more details.
+See [reference](DataSchemaGenerationGradle.md) and [examples](DataSchemaGenerationGradle.md#examples) for more details.
 
 </tab>
 </tabs>
diff --git a/docs/StardustDocs/topics/schemasImportOpenApiGradle.md b/docs/StardustDocs/topics/concepts/schemasImportOpenApiGradle.md
similarity index 100%
rename from docs/StardustDocs/topics/schemasImportOpenApiGradle.md
rename to docs/StardustDocs/topics/concepts/schemasImportOpenApiGradle.md
diff --git a/docs/StardustDocs/topics/schemasImportOpenApiJupyter.md b/docs/StardustDocs/topics/concepts/schemasImportOpenApiJupyter.md
similarity index 100%
rename from docs/StardustDocs/topics/schemasImportOpenApiJupyter.md
rename to docs/StardustDocs/topics/concepts/schemasImportOpenApiJupyter.md
diff --git a/docs/StardustDocs/topics/schemasImportSqlGradle.md b/docs/StardustDocs/topics/concepts/schemasImportSqlGradle.md
similarity index 100%
rename from docs/StardustDocs/topics/schemasImportSqlGradle.md
rename to docs/StardustDocs/topics/concepts/schemasImportSqlGradle.md
diff --git a/docs/StardustDocs/topics/schemasInheritance.md b/docs/StardustDocs/topics/concepts/schemasInheritance.md
similarity index 100%
rename from docs/StardustDocs/topics/schemasInheritance.md
rename to docs/StardustDocs/topics/concepts/schemasInheritance.md
diff --git a/docs/StardustDocs/topics/schemasJupyter.md b/docs/StardustDocs/topics/concepts/schemasJupyter.md
similarity index 100%
rename from docs/StardustDocs/topics/schemasJupyter.md
rename to docs/StardustDocs/topics/concepts/schemasJupyter.md
diff --git a/docs/StardustDocs/topics/stringApi.md b/docs/StardustDocs/topics/concepts/stringApi.md
similarity index 100%
rename from docs/StardustDocs/topics/stringApi.md
rename to docs/StardustDocs/topics/concepts/stringApi.md
diff --git a/docs/StardustDocs/topics/types.md b/docs/StardustDocs/topics/concepts/types.md
similarity index 100%
rename from docs/StardustDocs/topics/types.md
rename to docs/StardustDocs/topics/concepts/types.md
diff --git a/docs/StardustDocs/topics/guides/quickstart.md b/docs/StardustDocs/topics/guides/quickstart.md
index 5b8ad63a74..06de611939 100644
--- a/docs/StardustDocs/topics/guides/quickstart.md
+++ b/docs/StardustDocs/topics/guides/quickstart.md
@@ -349,7 +349,7 @@ Ready to go deeper? Check out what’s next:
 
 - 🛠️ **[Browse the operations overview](operations.md)** to learn what Kotlin DataFrame can do.
 
-- 🧠 **Understand the design** and core concepts in the [library overview](overview.md).
+- 🧠 **Understand the design** and core concepts in the [library overview](concepts.md).
 
 - 🔤 **[Learn more about Extension Properties](extensionPropertiesApi.md)**  
   and make working with your data both convenient and type-safe.
diff --git a/docs/StardustDocs/topics/overview.md b/docs/StardustDocs/topics/overview.md
deleted file mode 100644
index d5d1cb4b89..0000000000
--- a/docs/StardustDocs/topics/overview.md
+++ /dev/null
@@ -1,174 +0,0 @@
-[//]: # (title: Library Overview)
-
-<web-summary>
-Learn what Kotlin DataFrame is about — its core concepts, design principles, and usage philosophy.
-</web-summary>
-
-<card-summary>
-Discover the fundamentals of the library —
-understand key concepts, motivation, and the overall structure of the library.
-</card-summary>
-
-<link-summary>
-Explore the fundamentals of Kotlin DataFrame — 
-understand key concepts, motivation, and the overall structure of the library.
-</link-summary>
-
-
-<show-structure depth="3"/>
-
-<tip> 
-
-This documentation is written in such a way that it could be read sequentially and in this case, it  provides all necessary information about the library, but at the same time the [Operations](operations.md) section could be used as an API reference
-
-</tip>
-
-## What is Data Frame
-
-Data frame is an abstraction for working with structured data. Essentially it’s a 2-dimensional table with labeled columns of potentially different types. You can think of it like a spreadsheet or SQL table, or a dictionary of series objects.
-
-The handiness of this abstraction is not in the table itself but in a set of operations defined on it. 
-The Kotlin DataFrame library is an idiomatic Kotlin DSL defining such operations. 
-The process of working with data frame is often called *data wrangling* which 
-is the process of transforming and mapping data from one "raw" data form into another format 
-that is more appropriate for analytics and visualization. 
-The goal of data wrangling is to assure quality and useful data.
-
-## Main Features and Concepts
-
-* [**Hierarchical**](hierarchical.md) — the Kotlin DataFrame library provides an ability to read and present data from different sources, 
-including not only plain **CSV** but also **JSON** or **[SQL databases](readSqlDatabases.md)**.
-This is why it was designed to be hierarchical and allows nesting of columns and cells.
-* **Functional** — the data processing pipeline is organized in a chain of [`DataFrame`](DataFrame.md)  transformation operations.
-* **Immutable** — every operation returns a new instance of [`DataFrame`](DataFrame.md)  reusing underlying storage wherever it's possible.
-* **Readable** — data transformation operations are defined in DSL close to natural language.
-* **Practical** — provides simple solutions for common problems and the ability to perform complex tasks.
-* **Minimalistic** — simple, yet powerful data model of three [column kinds](DataColumn.md#column-kinds).
-* [**Interoperable**](collectionsInterop.md) — convertable with Kotlin data classes and collections.
-  This also means conversion to/from other libraries' data structures is usually quite straightforward!
-  See our [examples](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples) 
-  for some conversions between DataFrame and [Apache Spark](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/spark), [Multik](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/multik), and [JetBrains Exposed](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples/unsupported-data-sources/src/main/kotlin/org/jetbrains/kotlinx/dataframe/examples/exposed).
-* **Generic** — can store objects of any type, not only numbers or strings.
-* **Typesafe** — the Kotlin DataFrame library provides a mechanism of on-the-fly [**generation of extension properties**](extensionPropertiesApi.md) 
-that correspond to the columns of a data frame. 
-In interactive notebooks like Jupyter or Datalore, the generation runs after each cell execution. 
-In IntelliJ IDEA there's a Gradle plugin for generation properties based on CSV file or JSON file. 
-Also, we’re working on a compiler plugin that infers and transforms [`DataFrame`](DataFrame.md) schema while typing.
-You can now clone this [project with many examples](https://github.com/koperagen/df-plugin-demo) showcasing how it allows you to reliably use our most convenient extension properties API.
-The generated properties ensure you’ll never misspell column name and don’t mess up with its type, and of course nullability is also preserved.
-* [**Polymorphic**](schemas.md) —
-  if all columns of a [`DataFrame`](DataFrame.md) instance are presented in another dataframe,
-  then the first one will be seen as a superclass for the latter. 
-This means you can define a function on an interface with some set of columns
-  and then execute it safely on any [`DataFrame`](DataFrame.md) which contains this same set of columns.
-  In notebooks, this works out-of-the-box.
-  In ordinary projects, this requires casting (for now).
-
-## Syntax
-
-**Basics:**
-
-```kotlin
-val df = DataFrame.readCsv("titanic.csv", delimiter = ';')
-```
-
-```kotlin
-// filter rows
-val someSurvivors = df.filter { survived && home.endsWith("NY") && age in 10..20 }
-    
-// add column
-val withBirthYearColumn = df.add("birthYear") { 1912 - age }
-
-// sort rows
-val sortedByAge = df.sortByDesc { age }
-
-// aggregate data
-val aggregated = df.groupBy { pclass }.aggregate {
-    maxBy { age }.name into "oldest person"
-    count { survived } into "survived"
-}
-```
-
-The `titanic.csv` file could be found [here](https://github.com/Kotlin/dataframe/blob/master/data/titanic.csv).
-
-**Create:**
-```kotlin
-// create columns
-val fromTo by columnOf("LoNDon_paris", "MAdrid_miLAN", "londON_StockhOlm", "Budapest_PaRis", "Brussels_londOn")
-val flightNumber by columnOf(10045.0, Double.NaN, 10065.0, Double.NaN, 10085.0)
-val recentDelays by columnOf("23,47", null, "24, 43, 87", "13", "67, 32")
-val airline by columnOf("KLM(!)", "{Air France} (12)", "(British Airways. )", "12. Air France", "'Swiss Air'")
-
-// create dataframe
-val df = dataFrameOf(fromTo, flightNumber, recentDelays, airline)
-```
-
-**Clean:**
-```kotlin
-// typed accessors for columns
-// that will appear during 
-// dataframe transformation
-val origin by column<String>()
-val destination by column<String>()
-
-val dfClean = df
-    // fill missing flight numbers
-    .fillNA { flightNumber }.with { prev()!!.flightNumber + 10 }
-
-    // convert flight numbers to int
-    .convert { flightNumber }.toInt()
-
-    // clean 'Airline' column
-    .update { airline }.with { "([a-zA-Z\\s]+)".toRegex().find(it)?.value ?: "" }
-
-    // split 'From_To' column into 'From' and 'To'
-    .split { fromTo }.by("_").into(origin, destination)
-
-    // clean 'From' and 'To' columns
-    .update { origin and destination }.with { it.lowercase().replaceFirstChar(Char::uppercase) }
-
-    // split lists of delays in 'RecentDelays' into separate columns 
-    // 'delay1', 'delay2'... and nest them inside original column `RecentDelays`
-    .split { recentDelays }.inward { "delay$it" }
-
-    // convert string values in `delay1`, `delay2` into ints
-    .parse { recentDelays }
-```
-
-**Aggregate:**
-```kotlin
-// group by flight origin
-val analysed = dfClean.groupBy { From into "origin" }.aggregate {
-    // we are in the context of single data group
-    
-    // number of flights from origin
-    count() into "count"
-    
-    // list of flight numbers
-    flightNumber into "flight numbers"
-    
-    // counts of flights per airline
-    airline.valueCounts() into "airlines"
-
-    // max delay across all delays in `delay1` and `delay2`
-    recentDelays.maxOrNull { delay1 and delay2 } into "major delay"
-
-    // separate lists of recent delays for `delay1`, `delay2` and `delay3`
-    recentDelays.implode(dropNulls = true) into "recent delays"
-    
-    // total delay per city of destination
-    pivot { To }.sum { recentDelays.intCols() } into "total delays to"
-}
-```
-
-## Contribute and give feedback
-
-If you find a bug, or have an idea for a new feature, [file an issue](https://github.com/Kotlin/dataframe/issues/new) in our DataFrame GitHub repository.
-
-Additionally, we welcome contributions. To get stared, choose an issue, and let us know that you're working on it. When you're ready, create a [pull request](https://github.com/Kotlin/dataframe/pulls).
-
-You can also contact us in the [#datascience](https://kotlinlang.slack.com/archives/C4W52CFEZ) channel of Kotlin Slack.
-
-For more information on how to contribute, see our [Contributing guidelines](https://github.com/Kotlin/dataframe/blob/master/CONTRIBUTING.md).
-
-Good luck!

From 3cfb8e788f0f4f761339f3343094268410e4e890 Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Sat, 5 Jul 2025 13:08:38 +0400
Subject: [PATCH 2/3] structure fixes

---
 docs/StardustDocs/d.tree                      |  8 +++---
 .../StardustDocs/topics/concepts/apiLevels.md |  4 +--
 .../StardustDocs/topics/concepts/stringApi.md | 26 -------------------
 .../{concepts => }/extensionPropertiesApi.md  |  0
 4 files changed, 5 insertions(+), 33 deletions(-)
 delete mode 100644 docs/StardustDocs/topics/concepts/stringApi.md
 rename docs/StardustDocs/topics/{concepts => }/extensionPropertiesApi.md (100%)

diff --git a/docs/StardustDocs/d.tree b/docs/StardustDocs/d.tree
index b6d1cef5c0..3a4ea3993b 100644
--- a/docs/StardustDocs/d.tree
+++ b/docs/StardustDocs/d.tree
@@ -22,10 +22,7 @@
         <toc-element topic="gettingStartedGradleAdvanced.md"/>
     </toc-element>
     <toc-element topic="concepts.md">
-        <toc-element topic="apiLevels.md">
-            <toc-element topic="stringApi.md"/>
-            <toc-element topic="extensionPropertiesApi.md"/>
-        </toc-element>
+        <toc-element topic="apiLevels.md"/>
         <toc-element topic="types.md">
             <toc-element topic="DataFrame.md"/>
             <toc-element topic="DataColumn.md"/>
@@ -43,10 +40,11 @@
             <toc-element topic="schemasImportSqlGradle.md"/>
             <toc-element topic="schemasImportOpenApiGradle.md"/>
             <toc-element topic="schemasImportOpenApiJupyter.md"/>
-            <toc-element topic="DataSchemaGenerationMethods.md"/>
             <toc-element topic="DataSchemaGenerationGradle.md"/>
         </toc-element>
     </toc-element>
+    <toc-element topic="extensionPropertiesApi.md"/>
+    <toc-element topic="DataSchemaGenerationMethods.md"/>
     <toc-element topic="Compiler-Plugin.md">
         <toc-element topic="staticInterpretation.md"/>
         <toc-element topic="dataSchema.md"/>
diff --git a/docs/StardustDocs/topics/concepts/apiLevels.md b/docs/StardustDocs/topics/concepts/apiLevels.md
index 1595c8c0bf..aabbe0129a 100644
--- a/docs/StardustDocs/topics/concepts/apiLevels.md
+++ b/docs/StardustDocs/topics/concepts/apiLevels.md
@@ -16,7 +16,7 @@ In the Kotlin DataFrame library, we provide two different ways to access columns
 
 Here's a list of all APIs in order of increasing safety.
 
-* [**String API**](stringApi.md) <br/>
+* **String API** <br/>
   Columns are accessed by `string` representing their name. Type-checking is done at runtime, name-checking too.
 
 * [**Extension Properties API**](extensionPropertiesApi.md) <br/>
@@ -80,7 +80,7 @@ The `titanic.csv` file can be found [here](https://github.com/Kotlin/dataframe/b
 
 # Comparing APIs
 
-The [String API](stringApi.md) is the simplest and unsafest of them all. The main advantage of it is that it can be
+The String API is the simplest and unsafest of them all. The main advantage of it is that it can be
 used at any time, including when accessing new columns in chain calls. So we can write something like:
 
 ```kotlin
diff --git a/docs/StardustDocs/topics/concepts/stringApi.md b/docs/StardustDocs/topics/concepts/stringApi.md
deleted file mode 100644
index a5fece4012..0000000000
--- a/docs/StardustDocs/topics/concepts/stringApi.md
+++ /dev/null
@@ -1,26 +0,0 @@
-[//]: # (title: String API)
-
-<!---IMPORT org.jetbrains.kotlinx.dataframe.samples.api.ApiLevels-->
-
-String column names are the easiest way to access data in [`DataFrame`](DataFrame.md):
-
-<!---FUN strings-->
-
-```kotlin
-DataFrame.read("titanic.csv")
-    .add("lastName") { "name"<String>().split(",").last() }
-    .dropNulls("age")
-    .filter {
-        "survived"<Boolean>() &&
-            "home"<String>().endsWith("NY") &&
-            "age"<Int>() in 10..20
-    }
-```
-
-<!---END-->
-
-The `titanic.csv` file could be found [here](https://github.com/Kotlin/dataframe/blob/master/data/titanic.csv).
-
-<warning>
-Note that if data frame doesn’t contain column with the string provided, or you try to cast to the wrong type it will lead to runtime exception.
-</warning>
diff --git a/docs/StardustDocs/topics/concepts/extensionPropertiesApi.md b/docs/StardustDocs/topics/extensionPropertiesApi.md
similarity index 100%
rename from docs/StardustDocs/topics/concepts/extensionPropertiesApi.md
rename to docs/StardustDocs/topics/extensionPropertiesApi.md

From 3ecde7885c3efdaf6eaa81ca90f63c57df6bfa6b Mon Sep 17 00:00:00 2001
From: "andrei.kislitsyn" <kisandy@yandex.ru>
Date: Sat, 5 Jul 2025 13:12:00 +0400
Subject: [PATCH 3/3] small concepts fixes

---
 docs/StardustDocs/d.tree                      | 2 +-
 docs/StardustDocs/topics/concepts/concepts.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/StardustDocs/d.tree b/docs/StardustDocs/d.tree
index 3a4ea3993b..4bc8dabea3 100644
--- a/docs/StardustDocs/d.tree
+++ b/docs/StardustDocs/d.tree
@@ -21,7 +21,7 @@
         <toc-element topic="gettingStartedDatalore.md"/>
         <toc-element topic="gettingStartedGradleAdvanced.md"/>
     </toc-element>
-    <toc-element topic="concepts.md">
+    <toc-element topic="concepts.md" accepts-web-file-names="overview.html">
         <toc-element topic="apiLevels.md"/>
         <toc-element topic="types.md">
             <toc-element topic="DataFrame.md"/>
diff --git a/docs/StardustDocs/topics/concepts/concepts.md b/docs/StardustDocs/topics/concepts/concepts.md
index 77aa147a24..03c521ec8f 100644
--- a/docs/StardustDocs/topics/concepts/concepts.md
+++ b/docs/StardustDocs/topics/concepts/concepts.md
@@ -18,9 +18,9 @@ understand key concepts, motivation, and the overall structure of the library.
 <show-structure depth="3"/>
 
 
-## What is Dataframe
+## What is a dataframe
 
-Dataframe is an abstraction for working with structured data. 
+A *dataframe* is an abstraction for working with structured data. 
 Essentially, it’s a 2-dimensional table with labeled columns of potentially different types. 
 You can think of it like a spreadsheet or SQL table, or a dictionary of series objects.