docs: explain grouped declarations

concepts/declaration-scopes.mdx

@@ -13,8 +13,8 @@ decide which files can access it. No TOML configuration is required.
 | Where the declaration lives | Who can use it |
 |-------------------------------------|--------------------|
 | Top-level `macros/`, `constants/`, or `enums/` | The whole project |
-| Nested `macros/`, `constants/`, or `enums/` | Files in that folder and folders below it |
-| Nested `_macros/`, `_constants/`, or `_enums/` | Files directly in that folder only |
+| Nested `_sqlbuild/macros/`, `_sqlbuild/constants/`, or `_sqlbuild/enums/` | Files in the owner folder and folders below it |
+| Nested `_sqlbuild/_macros/`, `_sqlbuild/_constants/`, or `_sqlbuild/_enums/` | Files directly in the owner folder only |
 | An underscored constant or enum inside `MODEL()` | That model and its inline SQL hooks only |
 
 Macro declarations are Python files (`.py`). Constant and enum declarations are SQL files
@@ -29,22 +29,27 @@ models/
 ├── constants/                 published throughout models/
 │   └── warehouse.sql
 └── commerce/
-    ├── macros/                published throughout commerce/
-    │   └── currency.py
-    ├── _enums/                exact commerce/ directory only
-    │   └── grain.sql
+    ├── _sqlbuild/
+    │   ├── macros/            published throughout commerce/
+    │   │   └── currency.py
+    │   └── _enums/            exact commerce/ directory only
+    │       └── grain.sql
     ├── orders.sql              sees warehouse, currency, and grain
     ├── finance/
-    │   ├── macros/            published throughout finance/
-    │   │   └── tax.py
+    │   ├── _sqlbuild/
+    │   │   └── macros/        published throughout finance/
+    │   │       └── tax.py
     │   └── revenue.sql         sees warehouse, currency, and tax
     └── fulfillment/
         └── shipments.sql       sees warehouse and currency
 ```
 
-A nested unprefixed role applies to its folder and everything below it. An underscored role applies
-only to files directly beside it. The same unprefixed role name applies to the whole project only
-when it is at the project root.
+The folder containing `_sqlbuild/` is the declaration owner. An unprefixed role applies to that
+owner and everything below it. An underscored role applies only to files directly in the owner.
+Legacy declaration roles directly below an owner remain supported.
+
+`_sqlbuild/` is reserved for the six declaration-role directories shown above. Other direct files or
+folders are rejected, and a project-root `_sqlbuild/` is invalid because it has no resource owner.
 
 | Resource | Visible from the example tree | Not visible |
 |----------|-------------------------------|-------------|
@@ -79,8 +84,8 @@ versioned JSON schema rather than parsing text labels.
 | Where the value is needed | Placement |
 |---------------------------|-----------|
 | One model only | In that model's `MODEL()` header |
-| Files directly in one folder | In an underscored role beside those files |
-| Files across one folder tree | In an unprefixed role at their nearest shared parent folder |
+| Files directly in one folder | In an underscored role under the owner's `_sqlbuild/` folder |
+| Files across one folder tree | In an unprefixed role under the nearest shared owner's `_sqlbuild/` folder |
 | Different resource trees, such as models and tests | In a top-level declaration role |
 
 SQLBuild computes the lowest common owner of every declaration's runtime consumers. A project-wide

concepts/declaration-scopes/explorer.mdx

@@ -153,7 +153,7 @@ Explanation
      Promotion impact: model:orders
 
 Diagnostics (1)
-  ERROR S008 models/commerce/macros/orders.py: Declaration 'macro:formatted_order_total' is currently descendant-public at 'models/commerce' (models/commerce/macros/orders.py); required exact-owner-private at 'models/commerce'. Consumers: model:orders. Move it to 'models/commerce/_macros/'
+  ERROR S008 models/commerce/macros/orders.py: Declaration 'macro:formatted_order_total' is currently descendant-public at 'models/commerce' (models/commerce/macros/orders.py); required exact-owner-private at 'models/commerce'. Consumers: model:orders. Move it to 'models/commerce/_sqlbuild/_macros/'
 Completeness: complete
 ```
 

concepts/declaration-scopes/placement.mdx

@@ -19,8 +19,8 @@ tree.
 | Where it is needed | Location |
 |--------------------|----------|
 | One model only | Inside that model's `MODEL()` header, for enums and constants |
-| SQL files directly in one directory | `_macros/`, `_enums/`, or `_constants/` |
-| A directory and its descendants | `macros/`, `enums/`, or `constants/` |
+| SQL files directly in one directory | `_sqlbuild/_macros/`, `_sqlbuild/_enums/`, or `_sqlbuild/_constants/` |
+| A directory and its descendants | `_sqlbuild/macros/`, `_sqlbuild/enums/`, or `_sqlbuild/constants/` |
 | Different trees, such as models and tests | Top-level `macros/`, `enums/`, or `constants/` |
 
 ## One directory
@@ -30,13 +30,14 @@ These two models use the same constant and both sit directly in `commerce/`:
 ```text
 models/
 └── commerce/
-    ├── _constants/
-    │   └── minimum_value.sql
+    ├── _sqlbuild/
+    │   └── _constants/
+    │       └── minimum_value.sql
     ├── orders.sql
     └── customers.sql
 ```
 
-Use `_constants/` because no descendant directory needs the value.
+Use `_sqlbuild/_constants/` because no descendant directory needs the value.
 
 ## One directory tree
 
@@ -45,15 +46,16 @@ These models use the same constant across two child directories:
 ```text
 models/
 └── commerce/
-    ├── constants/
-    │   └── reporting_day.sql
+    ├── _sqlbuild/
+    │   └── constants/
+    │       └── reporting_day.sql
     ├── finance/
     │   └── revenue.sql
     └── fulfillment/
         └── shipments.sql
 ```
 
-Use `constants/` in `commerce/` so both child directories can use it.
+Use `_sqlbuild/constants/` in `commerce/` so both child directories can use it.
 
 ## Different resource trees
 

concepts/declaration-scopes/visibility.mdx

@@ -5,8 +5,9 @@ description: "See which enums, constants, and macros are available to each SQL f
 
 For most SQL, the rule is simple:
 
-> A file can use declarations available to the whole project, declarations in unprefixed role
-> folders beside or above it, and declarations in an underscored role folder directly beside it.
+> A file can use declarations available to the whole project, declarations in unprefixed roles
+> under `_sqlbuild/` folders owned beside or above it, and declarations in an underscored role owned
+> directly beside it.
 
 ## Start from the SQL file
 
@@ -18,10 +19,11 @@ models/
 ├── constants/                 available throughout models/
 │   └── warehouse.sql
 └── commerce/
-    ├── enums/                 available throughout commerce/
-    │   └── order_status.sql
-    ├── _constants/       available directly in commerce/ only
-    │   └── minimum_value.sql
+    ├── _sqlbuild/
+    │   ├── enums/             available throughout commerce/
+    │   │   └── order_status.sql
+    │   └── _constants/        available directly in commerce/ only
+    │       └── minimum_value.sql
     ├── orders.sql
     └── history/
         └── archived_orders.sql
@@ -34,12 +36,12 @@ From this tree:
 | `orders.sql` | `warehouse`, `order_status`, and `minimum_value` |
 | `history/archived_orders.sql` | `warehouse` and `order_status` |
 
-`minimum_value` is not available in `history/` because `_constants/` applies only to files
-directly beside it.
+`minimum_value` is not available in `history/` because `_sqlbuild/_constants/` applies only to files
+directly in the `_sqlbuild/` owner's folder.
 
 ## Supported resource trees
 
-Scoped declaration directories can be placed below these SQL resource roots:
+Grouped declaration directories can be placed below these SQL resource roots:
 
 | Root | Contents |
 |------|----------|
@@ -57,6 +59,11 @@ when it must be available across different resource trees. Project-root `_consta
 and `_macros/` directories are invalid because there is no owner folder at the project root for
 them to be private to.
 
+Existing scoped declaration roles directly below an owner remain supported. `_sqlbuild/` is the
+preferred layout because it keeps all declarations together without changing their visibility.
+Only the six public/private declaration-role directories are valid directly under `_sqlbuild/`;
+other entries are rejected. A project-root `_sqlbuild/` is invalid because it has no resource owner.
+
 ## Which file controls visibility?
 
 | SQL being compiled | SQLBuild starts from |