Docs overhaul: rename to development-process.md, convert collapsibles to headings, add flow diagrams, add key concepts to README

Author: michaeldeongreen

README.md

@@ -44,8 +44,40 @@ Git repo (dev branch)
 
 | Document | Description |
 |---|---|
-| [Fabric CI/CD Release Options](fabric-cicd-release-options.md) | Evaluates all CI/CD release options for Fabric (Deployment Pipelines, Git-based, Build-based, Hybrid) and recommends the Hybrid approach. **Start here** if you're deciding on a strategy. |
+| [CI/CD Release Options](fabric-cicd-release-options.md) | Evaluates all CI/CD release options for Fabric (Deployment Pipelines, Git-based, Build-based, Hybrid) and recommends the Hybrid approach. **Start here** if you're deciding on a strategy. |
 | [Hybrid CI/CD Implementation Guide](hybrid-cicd-implementation-guide.md) | Deep dive into the implementation: workflow structure, sandwich pattern, configuration strategy, prerequisites, setup steps, and gotchas. |
+| [Development Process](development-process.md) | How developers work day-to-day: branch-out workflow, environment bootstrap/reset script, and PR validation. |
+
+---
+
+## Key Concepts
+
+Before choosing a CI/CD approach or development workflow, understand these two realities about Fabric items.
+
+### Item Tracking Categories
+
+Not all Fabric items can be managed the same way. From a lifecycle management perspective, items fall into three categories:
+
+| Category | Description | Examples |
+|---|---|---|
+| **Git-tracked** | Items supported by [Fabric Git integration](https://learn.microsoft.com/en-us/fabric/cicd/git-integration/intro-to-git-integration#supported-items). Their definitions are serialized to files in the repo, enabling version control, branching, and code-review workflows. | Notebooks, Semantic Models, Lakehouses, Reports, Variable Libraries, Data Pipelines, Environments |
+| **Deployment Pipeline–only** | Items not supported by Git integration but supported by [Fabric Deployment Pipelines](https://learn.microsoft.com/en-us/fabric/cicd/deployment-pipelines/intro-to-deployment-pipelines#supported-items). They can be promoted workspace-to-workspace but cannot be version-controlled in Git. | Ontologies (at the time of writing) |
+| **Manual** | Items supported by neither Git integration nor Deployment Pipelines. These must be created and configured manually in each workspace. | Varies as Microsoft continues adding support — always check the official supported items lists |
+
+> **Important:** Both supported items lists evolve as Microsoft adds capabilities. Always verify against the official documentation before assuming an item falls into a particular category.
+
+This categorization directly impacts your CI/CD strategy. The [Hybrid CI/CD Implementation Guide](hybrid-cicd-implementation-guide.md) uses the "sandwich pattern" specifically to handle the gap between git-tracked and deployment-pipeline-only items.
+
+### Variable Libraries: Dynamic vs Static Metadata
+
+Some Fabric items resolve environment-specific values **at runtime** through [Variable Libraries](https://learn.microsoft.com/en-us/fabric/cicd/variable-library/variable-library-cicd), while others have environment-specific IDs **hardcoded in their definitions**.
+
+| Type | How it works | Examples |
+|---|---|---|
+| **Dynamic (Variable Library)** | The item reads IDs from the Variable Library at runtime. Changing the active value set automatically switches the environment context — no file changes needed. | Notebooks using `notebookutils.variableLibrary.getLibrary()` |
+| **Static (hardcoded)** | The item definition contains literal workspace/lakehouse GUIDs that must be rewritten per environment — either at deploy time (via `parameter.yml`) or via script (`branch_env.py`). | Semantic Model Direct Lake URL (`expressions.tmdl`), Notebook META dependency blocks (`default_lakehouse`, `default_lakehouse_workspace_id`) |
+
+When designing your development and CI/CD processes, identify which items in your workspace are dynamic vs static. Static items need either deploy-time parameterization (`parameter.yml` for CI/CD) or script-based rewriting (`branch_env.py` for feature branches). The [Development Process](development-process.md) doc covers how this repo handles both.
 
 ---
 

assets/development-bootstrap-flow.svg

@@ -1,4 +1,4 @@
-# Feature Branch Development Process
+# Development Process
 
 This document describes the two primary approaches for feature branch development in Microsoft Fabric with Git integration, the tradeoffs of each, and how this repository implements the **Branch Out** pattern.
 
@@ -76,6 +76,8 @@ A Python script at `scripts/branch_env.py` handles the full lifecycle of feature
 
 #### Step-by-Step: Setting Up a Feature Branch
 
+![Bootstrap Flow](assets/development-bootstrap-flow.svg)
+
 1. **Branch out** from the Fabric UI Source Control panel.
 2. **Clone/pull** the feature branch locally:
    ```
@@ -108,6 +110,8 @@ A Python script at `scripts/branch_env.py` handles the full lifecycle of feature
 
 #### Step-by-Step: Reverting Before PR to Dev
 
+![Reset Flow](assets/development-reset-flow.svg)
+
 Before merging back to `dev`, all feature-specific changes must be reverted so dev IDs are restored:
 
 1. **Run the reset script** (preview first with `--dry-run`):