Step 1: Begin by caramelizing the onions. In a large skillet, melt the butter and olive oil over medium-low heat. Add the thinly sliced onions, 1/4 tsp salt, and a pinch of sugar (if using). Cook slowly, stirring occasionally, for 30-45 minutes, until the onions are deeply golden brown and very soft. Set aside to cool.
Step 2: While onions caramelize, sauté the mushrooms. In a separate skillet over medium-high heat, add the sliced mushrooms. Cook, stirring occasionally, until they release their moisture and turn golden brown, about 10-12 minutes. Season with the remaining 1/4 tsp salt and black pepper. Set aside to cool.
Step 3: In a medium bowl, combine the cooled caramelized onions, sautéed mushrooms, shredded Gruyère cheese, and fresh thyme. Stir gently until well mixed. Ensure the filling is completely cool before proceeding.
Step 4: Preheat your oven to 400°F (200°C). Line a large baking sheet with parchment paper.
Step 5: On a lightly floured surface, unroll one sheet of thawed puff pastry. Trim the edges to create a neat rectangle, approximately 10x14 inches. Lightly score the pastry to mentally divide it into three equal vertical sections.
Step 6: Spoon the cooled filling down the center third of the puff pastry rectangle, leaving about an inch of border at the top and bottom.
Step 7: On the outer two sections of the pastry, use a sharp knife or pizza cutter to cut diagonal strips, about 1 inch wide, from the edge of the pastry towards the filling. Make sure you have an equal number of strips on each side.
Step 8: To braid, fold the top and bottom borders of the pastry over the filling. Then, starting from one end, alternate folding the strips from the left and right sides over the filling, overlapping them slightly to create a woven, braided pattern. Ensure the filling is sealed within the pastry.
Step 9: Carefully transfer the assembled braid to the prepared baking sheet. In a small bowl, whisk the egg with 1 tablespoon of water to make an egg wash. Brush the entire surface of the puff pastry braid with the egg wash. Optionally, sprinkle with sea salt or poppy seeds.
Step 10: Bake for 20-25 minutes, or until the pastry is puffed, golden brown, and cooked through. If it browns too quickly, loosely tent with aluminum foil.
Step 11: Let the Caramelized Onion, Mushroom & Cheese Puff Pastry Braid cool on the baking sheet for 5-10 minutes before slicing and serving. This helps the cheese set and makes for cleaner cuts.