Simplify sample structure and document extending and deploying your own solution

.gitignore

@@ -1,14 +1,23 @@
+# Generated target outputs and local deployment state
+output/
+.databricks/
+.env
+.env.*
+!.env.example
+
 # DataM8 local files
 datam8.user
 index.json
 
-# Python environment local files
-.venv
-__pycache__
-
-# Visual Studio local files
-.vs
+# Local Python/editor caches
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.vs/
+**/.pbi/localSettings.json
+**/.pbi/cache.abf
 
-# Installed source plugins remain local dependencies.
-Plugins/*
-!Plugins/.gitkeep
+# Installed custom source plugins remain local dependencies
+plugins/*
+!plugins/.gitkeep

.vscode/settings.json

@@ -1,35 +1,35 @@
 {
-    "json.schemas": [
-        {
-            "fileMatch": [
-                "/Base/**/*.json",
-            ],
-            "url": "https://raw.githubusercontent.com/oraylis/datam8-model/refs/tags/v2.0.0-beta.1/schema/base.json"
-        },
-        {
-            "fileMatch": [
-                "/Model/**/*.json",
-                "!/Model/**/.properties.json",
-            ],
-            "url": "https://raw.githubusercontent.com/oraylis/datam8-model/refs/tags/v2.0.0-beta.1/schema/model.json"
-        },
-        {
-            "fileMatch": [
-                "/Model/**/*.json",
-            ],
-            "url": "https://raw.githubusercontent.com/oraylis/datam8-model/refs/tags/v2.0.0-beta.1/schema/folder.json"
-        },
-        {
-            "fileMatch": [
-                "/*.dm8s",
-            ],
-            "url": "https://raw.githubusercontent.com/oraylis/datam8-model/refs/tags/v2.0.0-beta.1/schema/solution.json"
-        },
-        {
-            "fileMatch": [
-                "/Plugins/**/*.json",
-            ],
-            "url": "https://raw.githubusercontent.com/oraylis/datam8-model/refs/tags/v2.0.0-beta.1/schema/plugin.json"
-        },
-    ]
+  "json.schemas": [
+    {
+      "fileMatch": [
+        "/base/**/*.json"
+      ],
+      "url": "https://raw.githubusercontent.com/oraylis/datam8-model/002aa65f6f127f91d06c8dc0fc4ea50ce75616fc/schema/base.json"
+    },
+    {
+      "fileMatch": [
+        "/model/**/*.json",
+        "!/model/**/.properties.json"
+      ],
+      "url": "https://raw.githubusercontent.com/oraylis/datam8-model/002aa65f6f127f91d06c8dc0fc4ea50ce75616fc/schema/model.json"
+    },
+    {
+      "fileMatch": [
+        "/model/**/.properties.json"
+      ],
+      "url": "https://raw.githubusercontent.com/oraylis/datam8-model/002aa65f6f127f91d06c8dc0fc4ea50ce75616fc/schema/folder.json"
+    },
+    {
+      "fileMatch": [
+        "/*.dm8s"
+      ],
+      "url": "https://raw.githubusercontent.com/oraylis/datam8-model/002aa65f6f127f91d06c8dc0fc4ea50ce75616fc/schema/solution.json"
+    },
+    {
+      "fileMatch": [
+        "/plugins/**/plugin.json"
+      ],
+      "url": "https://raw.githubusercontent.com/oraylis/datam8-model/002aa65f6f127f91d06c8dc0fc4ea50ce75616fc/schema/plugin.json"
+    }
+  ]
 }

AGENTS.md

@@ -1,8 +1,9 @@
 # Working in the DataM8 Public Sample
 
-This repository owns the small AdventureWorks Base/Model example, business
+This repository owns the small AdventureWorks base/model example, business
 functions and classic Databricks, Docs and Power BI generation references.
-It supports local generation; no cloud deployment or integration runner is included.
+It supports local generation and a neutral, operator-configured Databricks bundle.
+No live integration runner is included; cloud execution requires separate authorization.
 
 - Start with [getting started](docs/getting-started.md) and the
   [local checks](docs/integration-tests.md). Read the affected target's reference

ORAYLISDatabricksSample.dm8s

@@ -1,26 +1,26 @@
 {
   "schemaVersion": "2.0.0",
-  "basePath": "Base",
-  "modelPath": "Model",
-  "pluginsPath": "Plugins",
+  "basePath": "base",
+  "modelPath": "model",
+  "pluginsPath": "plugins",
   "generatorTargets": [
     {
       "name": "databricks",
       "isDefault": true,
-      "sourcePath": "Generate/databricks-lake",
-      "outputPath": "Output/databricks-lake/generated"
+      "sourcePath": "generate/databricks-lake",
+      "outputPath": "output/databricks"
     },
     {
       "name": "powerbi",
       "isDefault": false,
-      "sourcePath": "Generate/powerbi-tabular",
-      "outputPath": "Output/powerbi-tabular/generated"
+      "sourcePath": "generate/powerbi-tabular",
+      "outputPath": "output/powerbi"
     },
     {
       "name": "docs",
       "isDefault": false,
-      "sourcePath": "Generate/docs",
-      "outputPath": "Output/docs"
+      "sourcePath": "generate/docs",
+      "outputPath": "output/docs"
     }
   ]
 }

README.md

@@ -10,9 +10,10 @@ semantic model. The first exercise runs locally without a database or cloud acco
 | I want to… | Begin here | First result |
 | --- | --- | --- |
 | Learn visual modeling | [Open the sample in the app](docs/getting-started.md#use-the-app) | Change a Customer description and confirm it survives reload |
-| Validate and generate from the command line | [Local CLI setup](docs/getting-started.md#use-the-cli) | Generate and inspect a fresh `Output/docs/index.md` |
+| Validate and generate from the command line | [Local CLI setup](docs/getting-started.md#use-the-cli) | Generate and inspect a fresh `output/docs/index.md` |
+| Build and deploy my own solution | [Extend the sample](docs/build-your-own-solution.md), then [deploy](docs/quickstart.md) | Extend your model, validate and generate it, then deploy to your own environment |
 | Change templates or target conventions | [Template development](docs/template-development.md) and [configured targets](docs/reference/targets.md) | Change one template and compare the generated output |
-| Understand the example | [Model documentation target](Generate/docs/README.md) and [property references](docs/model-properties.md) | Follow Customer through Stage, Core, Curated and Consumer |
+| Understand the example | [Model documentation target](generate/docs/README.md) and [property references](docs/model-properties.md) | Follow Customer through Stage, Core, Curated and Consumer |
 
 **Recommended first result:** generate `docs` and open its index. Use a disposable
 copy: autosave writes metadata, and generation can replace a target's output.
@@ -30,7 +31,7 @@ uv run datam8 validate --solution ./ORAYLISDatabricksSample.dm8s
 uv run datam8 generate docs --solution ./ORAYLISDatabricksSample.dm8s
 ```
 
-Open `Output/docs/index.md`; it should contain Customer and links to entity pages
+Open `output/docs/index.md`; it should contain Customer and links to entity pages
 and a relationship diagram. The SQL Server metadata connector is bundled with
 the pinned CLI and installed through its `sql` extra. No connector checkout,
 download token or source connection is needed for this exercise.
@@ -39,19 +40,20 @@ download token or source connection is needed for this exercise.
 
 | Target | Source | Output |
 | --- | --- | --- |
-| databricks | `Generate/databricks-lake` | `Output/databricks-lake/generated` |
-| powerbi | `Generate/powerbi-tabular` | `Output/powerbi-tabular/generated` |
-| docs | `Generate/docs` | `Output/docs` |
+| databricks | `generate/databricks-lake` | `output/databricks` |
+| powerbi | `generate/powerbi-tabular` | `output/powerbi` |
+| docs | `generate/docs` | `output/docs` |
 
 The model follows AdventureWorks customers, addresses and orders through Stage,
 Core and Curated, including DimCustomer, DimDate and FactSalesOrder. Consumer
 entities retain Customer, Date, Sales Order and Total Sales. The SQL example
 uses the standard SalesLT.Customer table; no custom language-specific views are
 required. Data endpoints and secret references are neutral placeholders.
 
-This is a generate-only example. Deployment bindings, cloud resources and live
-execution are not included. Generating notebooks or TMDL does not demonstrate
-successful deployment or processing. See [output boundaries](docs/quickstart.md).
+A neutral Databricks bundle under `deployment/` and the [own-deployment guides](docs/quickstart.md)
+cover the next steps. Supply your own identity, compute, catalog and source
+connection. Credentials and live environment bindings are not included. Local
+generation does not establish successful deployment, refresh or processing.
 
 ## Learn more and contribute
 

SECURITY.md

@@ -4,5 +4,7 @@ Use the central [private vulnerability-report route](https://github.com/oraylis/
 or DataM8@Oraylis.de if that route is unavailable. Include component versions,
 reproduction and impact; keep sensitive data out of public issues.
 
-This documentation covers DataM8 2.0.0. Follow the
-[central reporting guidance](https://github.com/oraylis/datam8/blob/codex/documentation-v2/SECURITY.md).
+Follow the [central reporting guidance](https://github.com/oraylis/datam8/blob/main/SECURITY.md).
+Versioned examples contain neutral placeholders and secret references only. Keep
+Databricks authentication profiles, Power BI credentials, `.env` files and local
+deployment state outside version control. Never add passwords, tokens or client secrets.

deployment/databricks/databricks.yml

@@ -0,0 +1,47 @@
+bundle:
+  name: datam8-sample
+
+include:
+  - ../../output/databricks/schemas/*.yml
+  - ../../output/databricks/clusters/*.yml
+  - ../../output/databricks/jobs/*.yml
+  - ../../output/databricks/jobs/*/*.yml
+
+# External paths expand the sync root to the repository root. Re-include output
+# because .gitignore intentionally excludes generated files from source control.
+sync:
+  paths:
+    - ../../output/databricks
+    - ../../utils
+  include:
+    - ../../output/databricks/**
+    - ../../utils/**
+
+variables:
+  environment:
+    default: dev
+  catalog_name:
+    description: Your isolated existing Unity Catalog catalog
+  owner:
+    description: Your own Databricks user name (table owner)
+  cluster_id:
+    description: Existing Unity Catalog compute running Databricks Runtime 18.3 or later
+  connection_prefix:
+    description: Prefix before the modeled sqlserver connection suffix
+    default: sample_
+  date_start:
+    default: "2000-01-01"
+  date_end:
+    default: "2030-12-31"
+  unpause_schedules:
+    default: PAUSED
+
+targets:
+  dev:
+    default: true
+    mode: development
+    cluster_id: ${var.cluster_id}
+    workspace:
+      root_path: /Workspace/Users/${workspace.current_user.userName}/.bundle/${bundle.name}/${bundle.target}
+    run_as:
+      user_name: ${workspace.current_user.userName}

docs/build-your-own-solution.md

@@ -0,0 +1,85 @@
+# Build Your Own Solution
+
+Start with a complete fork or copy of this repository, including `base`, `model`,
+`generate`, `plugins`, `utils`, `deployment` and the solution descriptor. Keep your
+own solution in source control and make changes on a branch. Local model editing,
+validation and generation do not require a source connection or cloud account.
+
+## Establish a reproducible starting point
+
+Follow [local setup](getting-started.md#use-the-cli), then commit your starting
+point. Keep `pyproject.toml` and `uv.lock` together: the lockfile binds the public
+CLI and schema dependencies. The editor schemas in `.vscode/settings.json` match
+that dependency. For the app, use a release compatible with the solution schema;
+its bundled runtime is independent of the uv environment. When upgrading, review
+compatibility notes and regenerate on a branch before updating these pins.
+
+```powershell
+uv sync --frozen
+uv run datam8 validate --solution ./ORAYLISDatabricksSample.dm8s
+uv run datam8 generate docs --solution ./ORAYLISDatabricksSample.dm8s --clean-output
+uv run datam8 generate databricks --solution ./ORAYLISDatabricksSample.dm8s --clean-output
+uv run datam8 generate powerbi --solution ./ORAYLISDatabricksSample.dm8s --clean-output
+```
+
+Open the generated documentation index and inspect the notebooks/jobs and TMDL
+under the [three target output folders](reference/targets.md). Each generation
+command replaces only its selected target's output, including stale artifacts.
+Save a copy of this baseline outside `output/` to compare artifacts after editing.
+
+## Extend the model
+
+Use the DataM8 app or edit the persisted JSON and function files in your editor.
+The [user handbook](https://github.com/oraylis/datam8/blob/main/docs/user-guide/README.md)
+covers the individual editors and workflows.
+
+1. Choose the layer where the change belongs. Add or modify entities and
+   attributes with the appropriate types, keys, descriptions and properties.
+   Add new entities through the app or follow the existing schema when editing
+   JSON; every entity needs a unique ID.
+2. Define where the data comes from. For an external source, configure its source
+   type and connection references. Source import and preview require your own
+   connection and credentials; stored model metadata can be edited offline.
+   For an existing modeled source, select the upstream entity and map its
+   attributes to the target attributes.
+3. Update transformations and referenced function files when the change needs
+   new logic. Maintain relationships and downstream mappings across the affected
+   layers. Expose reporting fields in the Consumer layer when report authors
+   need them.
+4. Save and reload the solution to confirm that the edits are persisted. Validate
+   before generating again.
+
+Keep credentials outside version control and use secret references in source
+settings. For property behavior and target selection, consult the
+[model properties](model-properties.md) and [target references](reference/targets.md).
+
+## Validate and review the generated changes
+
+Run the validation and generation commands above again, or select the affected
+targets in the app. Check command exit codes and review the resulting artifacts:
+
+- **Documentation:** changed entities, attributes, mappings and relationships
+  appear in the catalog and entity pages.
+- **Databricks:** affected Raw, Stage, Core and Curated notebooks and jobs reflect
+  the change, with the intended dependencies and table definitions.
+- **Power BI:** affected Consumer tables, columns, relationships and measures
+  appear in the generated TMDL.
+
+The targets cover different layers, so a model change may affect only some of
+them. Compare against your baseline and investigate unrelated differences.
+Documentation timestamps change whenever documentation is regenerated. Commit
+the authored model, template and configuration changes after review; output
+remains disposable. When changing generator code, use the contributor
+[local checks](integration-tests.md) as well.
+
+## Prepare your own environment
+
+Continue with [Databricks deployment](../generate/databricks-lake/DEPLOYMENT.md)
+to create tables and load data, then [Power BI project integration](powerbi-deployment.md)
+to build and publish your own report. For different output conventions, follow
+[template development](template-development.md).
+
+Keep your authored reports and connection parameters in a separate PBIP project,
+and maintain bundle configuration under `deployment/`. Local profiles, secrets
+and deployment state belong outside version control. Review the generated
+changes and the impact on existing data before deploying to your own environment.