almost done

Author: ymc9

versioned_docs/version-3.x/_components/_zmodel-starter.md

@@ -1,23 +1,23 @@
   ```zmodel
   datasource db {
-    provider = 'sqlite'
-    url = "file:./dev.db"
+      provider = 'sqlite'
+      url = "file:./dev.db"
   }
 
   model User {
-    id       String @id @default(cuid())
-    email    String @unique
-    posts    Post[]
+      id       String @id @default(cuid())
+      email    String @unique
+      posts    Post[]
   }
 
   model Post {
-    id        String   @id @default(cuid())
-    createdAt DateTime @default(now())
-    updatedAt DateTime @updatedAt
-    title     String
-    content   String
-    published Boolean  @default(false)
-    author    User     @relation(fields: [authorId], references: [id])
-    authorId  String
+      id        String   @id @default(cuid())
+      createdAt DateTime @default(now())
+      updatedAt DateTime @updatedAt
+      title     String
+      content   String
+      published Boolean  @default(false)
+      author    User     @relation(fields: [authorId], references: [id])
+      authorId  String
   }
   ```

versioned_docs/version-3.x/modeling/attribute.md

@@ -28,7 +28,7 @@ model User {
 Prisma schema doesn't allow users to define custom attributes, while ZModel allows it and uses it as a key mechanism for extensibility.
 </ZModelVsPSL>
 
-ZModel comes with a rich set of attributes that you can use directly. See [ZModel Language Reference](../category/zmodel-language) for a complete list. You can also define your own custom attributes for specific purposes. Attributes are defined with a list of typed parameters. Parameters can be named (default) or positional. Positional parameters can be passed with or without an explicit name. Parameters can also be optional.
+ZModel comes with a rich set of attributes that you can use directly. See [ZModel Language Reference](../reference/zmodel/attribute#predefined-attributes) for a complete list. You can also define your own attributes for specific purposes. Attributes are defined with a list of typed parameters. Parameters can be named (default) or positional. Positional parameters can be passed with or without an explicit name. Parameters can also be optional.
 
 Here's an example of how the `@unique` attribute is defined:
 
@@ -45,3 +45,5 @@ model Foo {
     z String @unique(map: 'z_unique', length: 10) // named parameter
 }
 ```
+
+Read the [ZModel Language Reference](../reference/zmodel/attribute#syntax) for more details on how to define and use attributes.

versioned_docs/version-3.x/modeling/datasource.md

@@ -38,5 +38,5 @@ datasource db {
 Currently, only PostgreSQL and SQLite are supported. MySQL will be supported in a future release. There's no plan for other relational database types or NoSQL databases.
 
 <ZModelVsPSL>
-ZenStack's ORM runtime doesn't rely on the `url` information to connect to the database. Instead, you provide the information when constructing an ORM client — more on this in the [ORM](../orm/) section.
+ZenStack's ORM runtime doesn't rely on the `url` information to connect to the database. Instead, you provide the information when constructing an ORM client — more on this in the [ORM](../orm/) part.
 </ZModelVsPSL>

versioned_docs/version-3.x/modeling/index.md

@@ -9,13 +9,13 @@ import ZModelVsPSL from '../_components/ZModelVsPSL';
 
 ZenStack uses a schema language named **ZModel** to define data models and their related aspects. We know that designing a good schema language is difficult, and we know it's even more challenging to convince people to learn a new one. We therefore decided to design ZModel as a superset of the [Prisma Schema Language (PSL)](https://www.prisma.io/docs/orm/prisma-schema), one of the best data modeling languages available.
 
-If you're already familiar with PSL, you'll find yourself at home with ZModel. However, we recommend that you skim through this section to learn about the essential extensions we made to PSL. Please pay attention to callouts like the following one:
+If you're already familiar with PSL, you'll find yourself at home with ZModel. However, we recommend that you skim through this section to learn about the essential extensions we made to PSL. Please pay attention to callouts like the following:
 
 <ZModelVsPSL>
 ZModel allows both single quotes and double quotes for string literals.
 </ZModelVsPSL>
 
-Don't worry if you've never used Prisma before. This section will introduce all aspects of ZModel, so no prior knowledge is required.
+Don't worry if you've never used Prisma before. This part of documentation will introduce all aspects of ZModel, so no prior knowledge is required.
 
 A simplest ZModel schema looks like this:
 

versioned_docs/version-3.x/modeling/mixin.md

@@ -21,10 +21,10 @@ Very often you'll find many of your models share quite a few common fields. It's
 
 ```zmodel
 model User {
-    id        String @id
+    id        String   @id
     createdAt DateTime @default(now())
     updatedAt DateTime @updatedAt
-    email     String @unique
+    email     String   @unique
 }
 
 model Post {

versioned_docs/version-3.x/modeling/model.md

@@ -5,7 +5,7 @@ description: Models in ZModel
 
 # Model
 
-The `model` construct is the core of ZModel. It defines the structure of your data and relations. A model represents a domain entity and is mapped to a database table.
+The `model` construct is the core of ZModel. It defines the structure of your data and relations. A model represents a domain entity and is backed by a database table.
 
 ## Defining models
 
@@ -73,7 +73,7 @@ Each model field must at least have a name and a type. A field can be typed in o
    - Bytes
    - Unsupported
 
-   The `Unsupported` type is for defining fields of types not supported by the ORM; however, it lets the migration engine know how to create the field in the database.
+   The `Unsupported` type is for defining fields of types not supported by the ORM. It lets the migration engine know how to create the field in the database.
 
    ```zmodel
    // from Prisma docs
@@ -115,7 +115,7 @@ Each model field must at least have a name and a type. A field can be typed in o
     ```
 4. Custom type
    
-   ZenStack allows you to define custom types in the schema and use them to type JSON fields. This will be covered in more detail in the [Custom Types](./custom-type) section.
+   ZenStack allows you to define custom types in the schema and use them to type JSON fields. This will be covered in more detail in the [Custom Type](./custom-type) section.
 
    ```zmodel
    type Address {
@@ -174,9 +174,15 @@ model User {
 }
 ```
 
-These attributes control what data type is used when the [migration engine](../orm/migration.md) maps the schema to DDL. You can find a complete list of native type attributes in the [ZModel Language Reference](../category/zmodel-language).
+These attributes control what data type is used when the [migration engine](../orm/migration.md) maps the schema to DDL. You can find a complete list of native type attributes in the [ZModel Language Reference](../reference/zmodel/attribute#native-type-mapping-attributes).
 
 ## Name mapping
 
-Quite often, you want to use a different naming scheme for your models and fields than the database. You can achieve that with the `@map` attribute. The ORM respects the mapping when generating queries, and the migration engine uses it to generate the DDL.
+Quite often, you want to use a different naming scheme for your models and fields than the database. You can achieve that with the `@map` and `@@map` attribute. The ORM respects the mapping when generating queries, and the migration engine uses it to generate the DDL.
 
+```zmodel
+model User {
+    id Int @id @map('_id')    
+    @@map('users')
+}
+```

versioned_docs/version-3.x/modeling/plugin.md

@@ -25,7 +25,7 @@ plugin myPlugin {
 ```
 
 :::info
-In fact, the `zen generate` command is entirely implemented with plugins. The ZModel -> TypeScript generation is supported by the built-in `@core/typescript` plugin, which can be explicitly declared if you wish:
+In fact, the `zen generate` command is entirely implemented with plugins. The ZModel -> TypeScript generation is supported by the built-in `@core/typescript` plugin which runs automatically. You can explicitly declare it if you wish:
 
 ```zmodel
 plugin typescript {
@@ -40,7 +40,7 @@ Please refer to the [Plugin References](../category/plugins) for the full list o
 A plugin declaration involves three parts:
 
 1. A unique name
-2. A `provider` field that specifies where to load the plugin from. It can be a built-in plugin (like `@core/prisma` here), a local folder, or an npm package.
+2. A `provider` field that specifies where to load the plugin from. It can be a built-in plugin (like `@core/prisma` here), a local JavaScript module, or an NPM package name.
 3. Plugin-specific configuration options, such as `output` in this case.
 
 A plugin can have the following effects to ZModel:

versioned_docs/version-3.x/modeling/polymorphism.md

@@ -28,7 +28,7 @@ It may be tempting to use mixins to share the common fields, however it's not an
 A true solution involves having a in-database model of polymorphism, where we really have a `Content` table that serves as an intermediary between `User` and the concrete content types. This is what ZModel polymorphism is about.
 
 :::info
-There are [two main ways](https://www.prisma.io/docs/orm/prisma-schema/data-model/table-inheritance) to model polymorphism in relational databases: single-table inheritance (STI) and multi-table inheritance (MTI, aka. delegate types). ZModel only supports MTI.
+There are [two main ways](https://www.prisma.io/docs/orm/prisma-schema/data-model/table-inheritance) to model polymorphism in relational databases: single-table inheritance (STI) and multi-table inheritance (MTI, aka. "Delegate Types"). ZModel only supports MTI.
 :::
 
 ## Modeling polymorphism
@@ -83,17 +83,17 @@ erDiagram
     }
     User ||--o{ Content: owns
     Post {
-        id Int PK
+        id Int PK,FK
         content String
     }
     Post ||--|| Content: delegates
     Image {
-        id Int PK
+        id Int PK,FK
         data Bytes
     }
     Image ||--|| Content: delegates
     Video {
-        id Int PK
+        id Int PK,FK
         url String
     }
     Video ||--|| Content: delegates

versioned_docs/version-3.x/modeling/typed-json.md

@@ -22,7 +22,7 @@ To type a JSON field, define a custom type in ZModel, use it as the field's type
 
 ```zmodel
 model User {
-    id      Int @id
+    id      Int  @id
     address Json
 }
 ```
@@ -44,7 +44,7 @@ model User {
 ```
 
 :::info
-The `@json` attribute serves no purpose other than to indicate (for readability) that the field is a JSON field, not a relation to another model.
+The `@json` attribute serves no purpose today other than to indicate (for readability) that the field is a JSON field, not a relation to another model. We may extend it in the future for fine-tuning the JSON field's behavior.
 :::
 
 The migration engine still sees the field as a plain JSON field. However, the ORM client enforces its structure and takes care of properly typing the query results. We'll revisit this topic in the [ORM part](../orm/typed-json.md).

versioned_docs/version-3.x/orm/index.md

@@ -7,7 +7,7 @@ import ZenStackVsPrisma from '../_components/ZenStackVsPrisma';
 
 # ORM Overview
 
-ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learnt from the prior arts and strives to provide an awesome developer experience by combining the best ingredients into a cohesive package.
+ZenStack ORM is a schema-first ORM for modern TypeScript applications. It learnt from the prior arts and strives to provide an excellent developer experience and incredible flexibility by combining the best ingredients into a cohesive package.
 
 ## Key Features
 
@@ -45,7 +45,7 @@ await db.$qb
 
 ZenStack ORM comes with a powerful built-in access control system. You can define access rules right inside the schema. The rules are enforced at runtime via query injection, so it doesn't rely on any database specific row-level security features.
 
-```zmodel"
+```zmodel
 model Post {
     id        Int     @id
     title     String  @length(1, 256)
@@ -68,7 +68,7 @@ model Post {
 
 Real-world applications often involves storing polymorphic data which is notoriously complex to model and query. ZenStack does the heavy-lifting for you so you can model an inheritance hierarchy with simple annotations, and query them with perfect type safety.
 
-```zmodel title="zenstack/schema.zmodel"
+```zmodel
 model Content {
     id    Int    @id
     name  String @length(1, 256)
@@ -106,7 +106,7 @@ Compared to Prisma and previous versions of ZenStack, v3 is more straightforward
 
 ### Sample playground
 
-Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive code samples. StackBlitz's [WebContainers](https://webcontainers.io/) is an awesome technology that allows you to run a Node.js environment inside the browser. The embedded samples use the [sql.js](https://github.com/sql-js/sql.js) (a WASM implementation of SQLite) for WebContainers compatibility, which is not suitable for production use.
+Throughout the documentation we'll use [StackBlitz](https://stackblitz.com/) to provide interactive samples alongside with static code snippets. StackBlitz's [WebContainers](https://webcontainers.io/) is an awesome technology that allows you to run a Node.js environment inside the browser. The embedded samples use the [sql.js](https://github.com/sql-js/sql.js) (a WASM implementation of SQLite) for WebContainers compatibility, which is not suitable for production use. Feel free to make changes and try things out in the playground.
 
 ### If you already know Prisma