diff --git a/docs/building-blocks/documentation-set-navigation.md b/docs/building-blocks/documentation-set-navigation.md
index 457fb7153..215dfae91 100644
--- a/docs/building-blocks/documentation-set-navigation.md
+++ b/docs/building-blocks/documentation-set-navigation.md
@@ -168,66 +168,408 @@ When building [assembled documentation](assembled-documentation.md), the documen
 
 Named `toc` sections in `docset.yml` can be referenced and reorganized in the global `navigation.yml` file without affecting the documentation set's internal structure.
 
+## Common navigation patterns
+
+Understanding the different ways to structure navigation helps you choose the right pattern for your documentation. Each pattern serves a specific purpose and has its own trade-offs.
+
+### Pattern: Single file
+
+The simplest pattern - just reference individual markdown files:
+
+```yaml
+toc:
+  - file: index.md
+  - file: getting-started.md
+  - file: faq.md
+```
+
+**When to use**: For flat documentation with few pages or when pages don't naturally group together.
+
+**Advantages**: Simple and explicit. No hidden files or automatic inclusion.
+
+**Considerations**: Doesn't scale well for large documentation sets.
+
+### Pattern: File with children (virtual grouping)
+
+Group related files under a parent without creating a physical folder structure:
+
+```yaml
+toc:
+  - file: getting-started.md
+    children:
+      - file: installation.md
+      - file: configuration.md
+      - file: first-steps.md
+```
+
+**When to use**: When you want to create a logical grouping without reorganizing files on disk, typically for sibling files in the same directory.
+
+**Advantages**: Creates navigation hierarchy without changing the file system. Useful for grouping related pages that share a parent.
+
+**Considerations**: Children must be siblings of the parent file. The parent can't select files from different directories. Avoid deep-linking (using paths with `/` in the file reference when it has children) - the builder will emit hints suggesting you use folder structures instead.
+
+**Example scenario**: You have several setup guides at the root level that you want to group under a "Getting Started" parent page:
+
+```
+docs/
+├── getting-started.md
+├── installation.md
+├── configuration.md
+└── first-steps.md
+```
+
+### Pattern: Folder without children
+
+Let the builder automatically include all markdown files in a folder:
+
+```yaml
+toc:
+  - folder: tutorials
+  - folder: api
+```
+
+**When to use**: During active development when content is still evolving, or for folders where file order doesn't matter.
+
+**Advantages**: Zero maintenance - new files are automatically included. Perfect for development.
+
+**Considerations**: No control over file order. All markdown files in the folder will be included.
+
+### Pattern: Folder with explicit children
+
+Define exactly which files appear and in what order:
+
+```yaml
+toc:
+  - folder: api
+    children:
+      - file: index.md
+      - file: authentication.md
+      - file: endpoints.md
+      - file: errors.md
+```
+
+**When to use**: When file order matters or when you need precise control over what's included.
+
+**Advantages**: Complete control over structure and ordering. The builder validates that all files are accounted for.
+
+**Considerations**: Requires maintenance. The builder will error if files exist in the folder that aren't listed in children.
+
+### Pattern: Folder with entry file
+
+Combine a folder reference with a specific entry file:
+
+```yaml
+toc:
+  - folder: getting-started
+    file: getting-started.md
+    children:
+      - file: prerequisites.md
+      - file: installation.md
+```
+
+**When to use**: When you want a folder with a main overview file that's not named `index.md`.
+
+**Advantages**: Clear entry point. Works well when the folder name and overview file name match.
+
+**Considerations**: The builder will hint if the file name doesn't match the folder name (unless you use `index.md`). This pattern works best when names align:
+
+**Good examples**:
+```yaml
+# File name matches folder name
+- folder: getting-started
+  file: getting-started.md
+
+# Using index.md always works
+- folder: api-reference
+  file: index.md
+```
+
+**Triggers hints**:
+```yaml
+# File name doesn't match folder name
+- folder: getting-started
+  file: overview.md  # Hint: Consider naming this getting-started.md
+```
+
+### Pattern: Nested toc references
+
+Split large documentation into separate `toc.yml` files:
+
+**In `docset.yml`**:
+```yaml
+toc:
+  - file: index.md
+  - toc: getting-started
+  - toc: api-reference
+  - toc: guides
+```
+
+**In `getting-started/toc.yml`**:
+```yaml
+toc:
+  - file: index.md
+  - file: installation.md
+  - file: configuration.md
+```
+
+**When to use**: For large documentation sets, when different teams own different sections, or when you want to keep `docset.yml` focused and readable.
+
+**Advantages**: Modularity. Each section can evolve independently. Easier folder renames (the folder name isn't repeated in its own toc.yml). Better for team ownership.
+
+**Considerations**: `toc.yml` files can't nest other `toc.yml` files - only `docset.yml` can reference them.
+
+**Example scenario**: You're building product documentation with multiple major sections:
+
+```
+docs/
+├── docset.yml
+├── index.md
+├── getting-started/
+│   ├── toc.yml
+│   └── ...
+├── api-reference/
+│   ├── toc.yml
+│   └── ...
+└── guides/
+    ├── toc.yml
+    └── ...
+```
+
+### Mixing patterns
+
+In practice, you'll combine patterns based on your needs:
+
+```yaml
+toc:
+  - file: index.md                    # Single file
+  - file: quick-start.md              # Single file
+  - folder: tutorials                 # Auto-include during development
+  - folder: api
+    children:                         # Explicit control for stability
+      - file: index.md
+      - file: authentication.md
+  - toc: guides                       # Large section in separate file
+```
+
+## Suppressing diagnostic hints
+
+As you build navigation, the docs-builder may emit hints suggesting improvements to your structure. These hints help maintain best practices but can be suppressed when you have valid reasons to deviate.
+
+### Available suppressions
+
+Add a `suppress` section to either `docset.yml` or `toc.yml`:
+
+```yaml
+suppress:
+  - DeepLinkingVirtualFile
+  - FolderFileNameMismatch
+
+toc:
+  - file: index.md
+  # ... rest of your navigation
+```
+
+### DeepLinkingVirtualFile
+
+**What it detects**: Files with children that use paths containing `/`:
+
+```yaml
+toc:
+  - file: guides/advanced/performance.md
+    children:
+      - file: guides/advanced/caching.md
+      - file: guides/advanced/optimization.md
+```
+
+**Why it hints**: Virtual files (files with children) work best for grouping sibling files together. Using deep paths suggests you might benefit from proper folder structures.
+
+**When to suppress**: Rarely. This usually indicates a structural issue. Consider refactoring to use folders or nested toc files instead.
+
+**Better alternative**:
+```yaml
+toc:
+  - folder: guides
+    children:
+      - folder: advanced
+        children:
+          - file: index.md
+          - file: performance.md
+            children:
+              - file: caching.md
+              - file: optimization.md
+```
+
+### FolderFileNameMismatch
+
+**What it detects**: Folder and file combinations where names don't match:
+
+```yaml
+toc:
+  - folder: getting-started
+    file: overview.md      # Doesn't match folder name
+```
+
+**Why it hints**: Matching names create predictable, consistent navigation. When a folder is named "getting-started," readers expect the main file to be either `getting-started.md` or `index.md`.
+
+**When to suppress**: When you have legacy documentation with established naming conventions, or when the file name is intentionally different for clarity.
+
+**Better alternatives**:
+```yaml
+# Option 1: Match the names
+- folder: getting-started
+  file: getting-started.md
+
+# Option 2: Use index.md (conventional and always appropriate)
+- folder: getting-started
+  file: index.md
+
+# Option 3: Just use folder with children
+- folder: getting-started
+  children:
+    - file: index.md
+    - file: prerequisites.md
+```
+
+### When to use suppressions
+
+Suppressions are escape hatches, not defaults. Use them when:
+
+* **Migrating legacy content**: Existing documentation has established patterns that can't be changed immediately
+* **Valid architectural reasons**: Your specific use case genuinely benefits from the flagged pattern
+* **Temporary transitions**: You're in the middle of restructuring and need to suppress hints during the migration
+
+**Example of justified suppression**:
+```yaml
+# This section uses an established URL structure we can't change
+# without breaking external links. Suppressing the hint until we
+# can implement proper redirects.
+suppress:
+  - FolderFileNameMismatch
+
+toc:
+  - folder: install
+    file: setup.md  # External links point to /install/setup
+    children:
+      - file: prerequisites.md
+```
+
 ## Best practices
 
 ### Keep it organized
 
-* Group related content in folders.
-* Use descriptive folder and file names.
-* Maintain a logical hierarchy.
+* **Group related content** in folders that reflect logical sections
+* **Use descriptive names** - folder and file names become URLs
+* **Maintain hierarchy** - think about how users navigate from general to specific
+
+The folder names and hierarchy translate directly to URL structure. `folder: api/authentication` becomes `/docs/api/authentication/` in the browser.
+
+### Start simple, evolve structure
+
+Begin with automatic folder inclusion during development:
+
+```yaml
+toc:
+  - file: index.md
+  - folder: guides        # Auto-includes everything
+  - folder: api           # Auto-includes everything
+```
+
+As content stabilizes, add explicit children for control:
 
-The folder names and hierarchy are reflected directly in the URL structure.
+```yaml
+toc:
+  - file: index.md
+  - folder: guides
+    children:             # Now you control the order
+      - file: index.md
+      - file: getting-started.md
+      - file: advanced-topics.md
+  - toc: api              # Extract to separate toc.yml
+```
 
-### Use index files
+### Use index files consistently
 
-Always include an `index.md` in folders:
+Every folder should have an `index.md` that introduces the section:
 
 ```yaml
 - folder: api
   children:
-    - file: index.md      # Overview of API documentation
-    - file: endpoints.md
+    - file: index.md        # Overview of the API section
     - file: authentication.md
+    - file: endpoints.md
 ```
 
+The index file provides context before users dive into specific topics. It's also what users see when they navigate to `/docs/api/`.
+
 ### Limit nesting depth
 
-Avoid deeply nested structures (more than three to four levels) to maintain navigation clarity.
+Deep navigation hierarchies overwhelm readers. Aim for three to four levels maximum:
+
+**Good** (3 levels):
+```
+Documentation
+  └── Guides
+      └── Installation
+          └── Prerequisites
+```
+
+**Too deep** (6 levels):
+```
+Documentation
+  └── Guides
+      └── Getting Started
+          └── Installation
+              └── Linux
+                  └── Ubuntu
+                      └── Prerequisites
+```
+
+If you need more depth, consider splitting into separate documentation sets or using virtual file grouping for minor subdivisions.
 
-### Use toc.yml for large sections
+### Extract large sections to toc.yml
 
-When a section contains many files or becomes complex, extract it to a dedicated `toc.yml`:
+When a section grows beyond 5-10 files or has its own internal structure, move it to a dedicated `toc.yml`:
 
 ```
 docs/
-├── docset.yml
+├── docset.yml          # High-level structure only
 ├── index.md
-└── development/
-    ├── toc.yml           # Define development section structure here
+└── api-reference/
+    ├── toc.yml         # API section structure
     ├── index.md
-    └── link-validation/
-        └── toc.yml       # Nested TOC section
+    └── ...
 ```
 
+**Benefits**:
+* Keeps `docset.yml` focused on top-level organization
+* Teams can own their section's navigation
+* Easier to refactor individual sections
+* Folder renames don't require updating the toc.yml (since the folder name isn't repeated inside it)
+
 ### Name TOC sections meaningfully
 
-Use clear, descriptive names for TOC sections:
+TOC section names become part of URLs and navigation structure:
 
-**Good:**
+**Good** (clear and descriptive):
 ```yaml
 - toc: api-reference
 - toc: getting-started
 - toc: troubleshooting
+- toc: user-guide
 ```
 
-**Bad:**
+**Bad** (vague and uninformative):
 ```yaml
 - toc: section1
 - toc: misc
 - toc: other
+- toc: stuff
 ```
 
-These names will end up in the URL structure of the published documentation
+Choose names that:
+* Describe the content clearly
+* Work well in URLs (lowercase, hyphenated)
+* Match user expectations
 
 ## Related concepts
 
diff --git a/docs/configure/content-set/navigation.md b/docs/configure/content-set/navigation.md
index d4b7cac73..76f7bc26d 100644
--- a/docs/configure/content-set/navigation.md
+++ b/docs/configure/content-set/navigation.md
@@ -8,10 +8,6 @@ Example:
 
 ```yaml
 project: 'PROJECT_NAME'
-soft_line_endings: true
-
-external_hosts:
-  - EXTERNAL_LINKS_HERE
 
 exclude:
   - 'EXCLUDED_FILES'
@@ -42,23 +38,6 @@ Example:
 project: 'APM Java agent reference'
 ```
 
-### `soft_line_endings`
-
-Optional key. Defaults to `false`. When enabled turns soft line endings in the markdown to hard HTML breaks `<br />`.
-
-
-### `external_hosts`
-
-All links to external hosts must be declared in this section of `docset.yml`.
-
-Example:
-
-```yaml
-external_hosts:
-  - google.com
-  - github.com
-```
-
 ### `cross_links`
 
 Defines repositories that contain documentation sets you want to link to. The purpose of this feature is to avoid using absolute links that require time-consuming crawling and checking.
@@ -198,10 +177,196 @@ subs:
 
 See [Attributes](./attributes.md) to learn more.
 
-## `toc.yml`
+### `suppress`
+
+Optional list of diagnostic hint types to suppress for this navigation file. Available in both `docset.yml` and `toc.yml` files.
+
+Valid suppression values:
+
+- `DeepLinkingVirtualFile`
+- `FolderFileNameMismatch`
+
+Example:
+
+```yaml
+suppress:
+  - DeepLinkingVirtualFile
+  - FolderFileNameMismatch
+```
+
+#### `DeepLinkingVirtualFile`
+
+Suppresses hints about files with children that use deep-linking (path contains `/`).
+
+By default, the builder emits a hint when a file reference includes a path separator and has children:
+
+```yaml
+toc:
+  - file: a/b/c/getting-started.md
+    children:
+      - file: a/b/c/setup.md
+      - file: a/b/c/install.md
+```
+
+**Hint message**: "File 'a/b/c/getting-started.md' uses deep-linking with children. Consider using 'folder' instead of 'file' for better navigation structure. Virtual files are primarily intended to group sibling files together."
+
+**Why this is discouraged**: Virtual files (files with children) are intended to group sibling files together, not to create deep navigation hierarchies. Using `folder` structures provides clearer organization.
+
+**Preferred alternative**:
+
+```yaml
+toc:
+  - folder: a
+    children:
+      - folder: b
+        children:
+          - folder: c
+            children:
+              - file: index.md
+              - file: getting-started.md
+                children:
+                  - file: setup.md
+                  - file: install.md
+```
+
+Or use nested `toc.yml` files for better maintainability.
+
+#### `FolderFileNameMismatch`
+
+Suppresses hints about file names not matching folder names in folder+file combinations.
+
+By default, when using the folder+file pattern, the builder emits a hint if the file name doesn't match the folder name:
+
+```yaml
+toc:
+  - folder: getting-started
+    file: overview.md
+```
+
+**Hint message**: "File name 'overview.md' does not match folder name 'getting-started'. Best practice is to name the file the same as the folder (e.g., 'folder: getting-started, file: getting-started.md')."
+
+**Why this is discouraged**: Mismatched names can cause confusion about which file represents the folder's main content. Consistent naming makes navigation structure more predictable.
+
+**Preferred alternatives**:
+
+```yaml
+# Option 1: Match file name to folder name
+toc:
+  - folder: getting-started
+    file: getting-started.md
+
+# Option 2: Use index.md (always allowed)
+toc:
+  - folder: getting-started
+    file: index.md
+
+# Option 3: Use folder only with children
+toc:
+  - folder: getting-started
+    children:
+      - file: index.md
+```
+
+## Navigation configuration patterns
+
+### Single file reference
+
+Reference a standalone file:
+
+```yaml
+toc:
+  - file: index.md
+  - file: getting-started.md
+  - file: api-reference.md
+```
+
+### File with children (virtual grouping)
+
+Group related sibling files under a parent file without creating a folder on disk:
+
+```yaml
+toc:
+  - file: getting-started.md
+    children:
+      - file: installation.md
+      - file: configuration.md
+      - file: first-steps.md
+```
+
+All children must be siblings of the parent file (in the same directory). The parent file may not select files outside its own subtree.
+
+### Folder without explicit children
+
+Include all markdown files in a folder automatically:
+
+```yaml
+toc:
+  - folder: api
+```
+
+All `.md` files in the `api/` folder will be included automatically. This is useful during development when the structure is still evolving.
+
+### Folder with explicit children
+
+Define exact files and their order within a folder:
+
+```yaml
+toc:
+  - folder: api
+    children:
+      - file: index.md
+      - file: authentication.md
+      - file: endpoints.md
+      - file: errors.md
+```
+
+When `children` is defined, all markdown files in the folder must be listed. The builder will error on dangling documentation files.
+
+### Folder and file combination
+
+Specify both a folder and a file to create a folder with a non-index entry point:
+
+```yaml
+toc:
+  - folder: getting-started
+    file: overview.md
+    children:
+      - file: installation.md
+      - file: configuration.md
+```
+
+Best practice: Use `index.md` or match the file name to the folder name to avoid `FolderFileNameMismatch` hints.
+
+### Nested toc reference
 
-As a rule, each `docset.yml` file can only be included once in the assembler. This prevents us from accidentally duplicating pages in the docs. However, there are times when you want to split content sets and include them partially in different areas of the TOC. That's what `toc.yml` files are for. These files split one documentation set into multiple “sub-TOCs,” each mapped to a different navigation node.
+Include a dedicated `toc.yml` file for large sections:
 
-A `toc.yml` file may only declare a nested [TOC](#toc), other options are ignored. 
+```yaml
+toc:
+  - file: index.md
+  - toc: api-reference
+  - toc: tutorials
+  - toc: guides
+```
+
+Each `toc` reference loads the corresponding `toc.yml` file from that directory (e.g., `api-reference/toc.yml`).
+
+### Mixed patterns
+
+Combine different patterns as needed:
 
-A `toc.yml` may not link to further nested `toc.yml` files. Doing so will result in an error
+```yaml
+toc:
+  - file: index.md
+  - file: quick-start.md
+  - folder: guides
+    children:
+      - file: index.md
+      - folder: installation
+        file: installation.md
+        children:
+          - file: prerequisites.md
+          - file: steps.md
+  - toc: api-reference
+  - folder: troubleshooting
+```