Feedback from client onboarding

Author: szjanikowski

docs/configure.md

@@ -6,13 +6,24 @@ sidebar_position: 3
 
 Learn how to use Noesis DSL to set architectural patterns in your code, allowing Noesis to focus on key building blocks in your codebase.
 
+:::info Understanding the P3 Model is Key
+Understanding the [P3 model](https://github.com/NoesisVision/P3-model/blob/main/Elements.md) is crucial for effective Noesis configuration. The P3 model defines three key elements that form the foundation of how Noesis analyzes and visualizes your system architecture:
+- **[Domain Modules](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-module)** - logical groupings of related functionality
+- **[Domain Objects](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-object)** - key building blocks of your domain model
+- **[Domain Behaviors](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-behavior)** - operations or entry points in your system
+:::
+
 ## Noesis DSL Description
 
 Noesis DSL is a fluent API for configuring source code analysis. It consists of three main parts:
 
 1. **System** - defines the name of the analyzed system
 2. **Repositories** - configures code sources (local or remote Git repositories)
-3. **Conventions** - defines conventions for domain modules, domain objects, and domain behaviors
+3. **Conventions** - defines conventions for [domain modules](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-module), [domain objects](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-object), and [domain behaviors](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-behavior)
+
+:::info Important Note about Repositories
+The **Repositories** node in Noesis DSL refers to **version control repositories** (code repositories, Git repositories), not the Repository design pattern. This section configures where Noesis should look for your source code to analyze.
+:::
 
 ## Basic Configuration Examples
 
@@ -69,7 +80,7 @@ public static FullAnalysisConfig Create() => FullAnalysisConfigBuilder
 
 ## Entry Points Configuration
 
-Entry Points are a critical component of Noesis DSL configuration. The `NoesisTags.Domain.EntryPoint` tag is specially treated in the implementation and represents the main entry points into your system's business logic. These are typically methods that handle incoming requests, commands, or messages.
+Entry Points are a critical component of Noesis DSL configuration. The `NoesisTags.Domain.EntryPoint` tag is specially treated in the implementation and represents the main [domain behaviors](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-behavior) that serve as entry points into your system's business logic. These are typically methods that handle incoming requests, commands, or messages.
 
 ### Common Entry Points Patterns
 
@@ -408,7 +419,7 @@ Configures a local Git repository for analysis:
 The AnalyzersBuilder configures how Noesis identifies and categorizes different elements in your codebase. It has three main configuration areas: domain modules, domain objects, and domain behaviors.
 
 #### ForDomainModules
-Configures how domain modules are identified and created:
+Configures how [domain modules](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-module) are identified and created:
 
 ```csharp
 .ForDomainModules(convention => convention
@@ -418,7 +429,7 @@ Configures how domain modules are identified and created:
     .SkipNamespaceParts("Company", "Infrastructure"))  // Remove common prefixes
 ```
 
-**Purpose:** Domain modules represent logical groupings of related functionality in your system. They're typically created from namespace hierarchy but can be filtered and customized.
+**Purpose:** [Domain modules](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-module) represent logical groupings of related functionality in your system. They're typically created from namespace hierarchy but can be filtered and customized.
 
 **Configuration Methods:**
 - **UseNamespaceHierarchy**: Creates modules based on namespace structure
@@ -445,6 +456,12 @@ Configures how domain objects (entities, services, repositories, etc.) are ident
 
 **Purpose:** Domain objects represent the key building blocks of your domain model. They can be tagged for categorization and filtering in the generated documentation.
 
+:::info Important Note about Domain Objects
+**Domain Objects** in Noesis DSL can be **any objects from your code** - they are not limited to Domain Driven Design concepts. You can identify and tag various types of objects such as services, entities, repositories, commands, events, queries, controllers, or any other architectural components that are important in your system.
+
+For more information about the generic P3 model and its elements, see the [P3 Model Elements documentation](https://github.com/NoesisVision/P3-model/blob/main/Elements.md).
+:::
+
 **Configuration Methods:**
 - **UseTypes**: Analyzes types (classes, interfaces, etc.)
 - **OfKind**: Filters by type kind (Class, Interface, Enum, etc.)
@@ -453,7 +470,7 @@ Configures how domain objects (entities, services, repositories, etc.) are ident
 - **SetName**: Customizes the object name in documentation
 
 #### ForDomainBehaviors
-Configures how domain behaviors (entry points, operations, etc.) are identified:
+Configures how [domain behaviors](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-behavior) (entry points, operations, etc.) are identified:
 
 ```csharp
 .ForDomainBehaviors(NoesisTags.Domain.EntryPoint, convention => convention
@@ -464,7 +481,7 @@ Configures how domain behaviors (entry points, operations, etc.) are identified:
     .WithName("Handle"))  // Method name pattern
 ```
 
-**Purpose:** Domain behaviors represent operations or entry points in your system. They're typically identified by analyzing methods rather than entire types.
+**Purpose:** [Domain behaviors](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-behavior) represent operations or entry points in your system. They're typically identified by analyzing methods rather than entire types.
 
 **Configuration Methods:**
 - **UseMethods**: Analyzes individual methods

docs/quick-start.md

@@ -7,10 +7,14 @@ sidebar_position: 1
 This practical tutorial will walk you through configuring Noesis step by step. After completing it, you'll be able to **see** -  "See how your system REALLY works" 🙂
 
 What you should expect:
-- **Your system visualization** in the form of domain modules
+- **Your system visualization** in the form of [P3 model elements](https://github.com/NoesisVision/P3-model/blob/main/Elements.md)
 - **Entry points** contained in these modules - often corresponding to REST endpoints or business logic entry points
 - **Service visualization** showing which services are used by each entry point and how they're interconnected
 
+:::info Understanding the P3 Model
+Understanding the [P3 model](https://github.com/NoesisVision/P3-model/blob/main/Elements.md) is crucial for effective Noesis configuration. The P3 model defines three key elements: **domain modules**, **domain objects**, and **domain behaviors** that form the foundation of how Noesis analyzes and visualizes your system architecture.
+:::
+
 ## Prerequisites
 
 Before you begin, make sure you have:
@@ -86,7 +90,7 @@ Open your browser and navigate to `http://localhost:8088`. You should see the No
 
 Now we'll configure Noesis to analyze your repository and make the full use of directory structure presented in [Step 1](#step-1-prepare-directory-structure). 
 
-Let's start by creating a basic configuration that will detect domain modules according to namespace hierarchy.
+Let's start by creating a basic configuration that will detect [domain modules](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-module) according to namespace hierarchy.
 In order to achieve that, you are going to configure two new volumes in the container: 
 - `externalSources` - it is a root directory of all the code repositories you want to scan 
 - `externalConfig` - is a path to a new  .NET project where you will specify your scanning rules and architecture conventions, using Noesis DSL
@@ -124,7 +128,7 @@ cd noesis-config
 Now add .NET NuGet packages to the project and test that it compiles
 
 ``` bash
-dotnet add package NoesisVision.Configuration --prerelease
+dotnet add package NoesisVision.Configuration
 dotnet build
 ```
 
@@ -135,7 +139,7 @@ Open the project in your IDE and create the `ArchitectureConventions.cs` file.
 **Remember to change `../my-system-repo` to the actual path to your project.**
 
 ```csharp
-using Noesis.Parser.Configuration;
+using NoesisVision.Parser.Configuration;
 
 namespace NoesisConfig
 {
@@ -154,6 +158,10 @@ namespace NoesisConfig
 }
 ```
 
+:::info Important Note about Repositories
+The **Repositories** node in Noesis DSL refers to **version control repositories** (code repositories, Git repositories), not the Repository design pattern. This section configures where Noesis should look for your source code to analyze.
+:::
+
 Play with the DSL if you want. You should be able additional versions of methods e.g. allowing to specify repository branch (which might be useful if your primary branch is not `main`). You may add multiple configuration files - they will be recognized by Noesis as separate systems to scan. 
 
 Check if the project correctly compiles - otherwise Noesis won't be able to work with it.
@@ -205,18 +213,23 @@ docker run \
     [10:05:15 INF] Inferencing finished in 0.06s.
     [10:05:15 INF] Full analysis for system DDD Starter Dotnet finished in 62.92s.
     ```
+    :::warning
+    You may see some compilation errors in the logs - DO NOT PANIC - probably these are compilation WARNINGS which are only displayed as errors by Roslyn. Please wait patientily for the final message about success or failure of project loading.
+    :::
 3. Go back to the main page and click "Basic mode" to view the scan results. Choose your result.
 4. Click **Modules** view - you should see modules created from your project's namespaces in the tree on the left, after you expand it. Here's how it may look: 
 
     ![Modules tree view](/img/modules.png)
 
 
 
+
+
 🎉 **Second Success!** Noesis recognized your system structure and created domain modules.
 
 ## Step 5: Entry Points Configuration
 
-Now we'll add entry points configuration - entry points to your system's business logic. These often correspond to REST API endpoints or command handling methods.
+Now we'll add entry points configuration - [domain behaviors](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-behavior) that represent entry points to your system's business logic. These often correspond to REST API endpoints or command handling methods.
 
 :::info
 From now on, it might be worth knowing that **the architecture conventions examples presented in the code-snippets below were created according to the architecture of an opensource project [Grandnode2](https://github.com/grandnode/grandnode2)**. This information might help you compare what is the exact application code corresponding to the presented usages of Noesis DSL. In addition you can find a full configuration for this projects in our examples repository on [Github](https://github.com/NoesisVision/noesis-config)
@@ -227,15 +240,15 @@ From now on, it might be worth knowing that **the architecture conventions examp
 Update `ArchitectureConventions.cs`, adding entry points configuration. The configuration depends on your project patterns, but if you use typical `CommandHandlers` with method `Handle` it may look like that: 
 
 ```csharp
-using Noesis.Parser.CodeParsing.Configuration;
-using Noesis.Parser.Configuration;
-using Noesis.Tags;
+using NoesisVision.Parser.CodeParsing.Configuration;
+using NoesisVision.Parser.Configuration;
+using NoesisVision.Tags;
 
 namespace NoesisConfig
 {
     public static class Grandnode2Config
     {
-         [FullAnalysisConfigAttribute]
+        [FullAnalysisConfigAttribute]
         public static FullAnalysisConfig Create() => FullAnalysisConfigBuilder
             .System("My System")  // System name in documentation
             .Repositories(repositories => repositories
@@ -288,16 +301,16 @@ Here's how it may look:
 
 ## Step 6: Services Configuration
 
-Finally, we'll add services configuration - business components used by entry points.
+Finally, we'll add services configuration - [domain objects](https://github.com/NoesisVision/P3-model/blob/main/Elements.md#domain-object) that represent business components used by entry points.
 
 ### 6.1: Add Services Configuration
 
 Update `ArchitectureConventions.cs`, adding services configuration:
 
 ```csharp
-using Noesis.Parser.CodeParsing.Configuration;
-using Noesis.Parser.Configuration;
-using Noesis.Tags;
+using NoesisVision.Parser.CodeParsing.Configuration;
+using NoesisVision.Parser.Configuration;
+using NoesisVision.Tags;
 
 namespace NoesisConfig
 {
@@ -328,9 +341,14 @@ namespace NoesisConfig
             .Build();
     }
 }
-
 ```
 
+:::info Important Note about Domain Objects
+**Domain Objects** in Noesis DSL can be **any objects from your code** - they are not limited to Domain Driven Design concepts. You can identify and tag various types of objects such as services, entities, repositories, commands, events, queries, controllers, or any other architectural components that are important in your system.
+
+For more information about the generic P3 model and its elements, see the [P3 Model Elements documentation](https://github.com/NoesisVision/P3-model/blob/main/Elements.md).
+:::
+
 ### 6.2: Run with Full Configuration
 
 Run the container with complete configuration: