docs(config[examples]): Add examples and tests for new features

why: New features need example configs and tests to verify them.
what:
- Add example YAMLs: synchronize, lifecycle hooks, templating, pane titles
- Add pytest tests for all four examples
- Update examples.md with literalinclude sections

Author: tony

docs/configuration/examples.md

@@ -785,6 +785,58 @@ windows:
 [poetry]: https://python-poetry.org/
 [uv]: https://github.com/astral-sh/uv
 
+## Synchronize panes (shorthand)
+
+The `synchronize` window-level key provides a shorthand for enabling
+`synchronize-panes` without needing `options_after`:
+
+````{tab} YAML
+```{literalinclude} ../../examples/synchronize-shorthand.yaml
+:language: yaml
+
+```
+````
+
+## Lifecycle hooks
+
+Run shell commands at different stages of the session lifecycle:
+
+````{tab} YAML
+```{literalinclude} ../../examples/lifecycle-hooks.yaml
+:language: yaml
+
+```
+````
+
+See {ref}`top-level` for full hook documentation.
+
+## Config templating
+
+Use `{{ variable }}` placeholders in workspace configs. Pass values via
+`--set KEY=VALUE`:
+
+```console
+$ tmuxp load --set project=myapp config-templating.yaml
+```
+
+````{tab} YAML
+```{literalinclude} ../../examples/config-templating.yaml
+:language: yaml
+
+```
+````
+
+## Pane titles
+
+Enable pane border titles to label individual panes:
+
+````{tab} YAML
+```{literalinclude} ../../examples/pane-titles.yaml
+:language: yaml
+
+```
+````
+
 ## Kung fu
 
 :::{note}

examples/config-templating.yaml

@@ -0,0 +1,5 @@
+session_name: "{{ project }}"
+windows:
+  - window_name: "{{ project }}-main"
+    panes:
+      - echo "Working on {{ project }}"

examples/lifecycle-hooks.yaml

@@ -0,0 +1,7 @@
+session_name: lifecycle hooks
+on_project_start: echo "project starting"
+on_project_exit: echo "project exiting"
+windows:
+  - window_name: main
+    panes:
+      -

examples/pane-titles.yaml

@@ -0,0 +1,15 @@
+session_name: pane titles
+enable_pane_titles: true
+pane_title_position: top
+pane_title_format: "#{pane_index}: #{pane_title}"
+windows:
+  - window_name: titled
+    panes:
+      - title: editor
+        shell_command:
+          - echo pane0
+      - title: runner
+        shell_command:
+          - echo pane1
+      - shell_command:
+          - echo pane2

examples/synchronize-shorthand.yaml

@@ -0,0 +1,16 @@
+session_name: synchronize shorthand
+windows:
+  - window_name: synced-before
+    synchronize: before
+    panes:
+      - echo 0
+      - echo 1
+  - window_name: synced-after
+    synchronize: after
+    panes:
+      - echo 0
+      - echo 1
+  - window_name: not-synced
+    panes:
+      - echo 0
+      - echo 1

tests/docs/examples/__init__.py

@@ -0,0 +1,87 @@
+"""Tests for example workspace YAML files."""
+
+from __future__ import annotations
+
+import functools
+import typing as t
+
+from libtmux.pane import Pane
+from libtmux.session import Session
+from libtmux.test.retry import retry_until
+
+from tests.constants import EXAMPLE_PATH
+from tmuxp._internal.config_reader import ConfigReader
+from tmuxp.workspace import loader
+from tmuxp.workspace.builder import WorkspaceBuilder
+
+
+def test_synchronize_shorthand(session: Session) -> None:
+    """Test synchronize-shorthand.yaml builds and sets synchronize-panes."""
+    config = ConfigReader._from_file(EXAMPLE_PATH / "synchronize-shorthand.yaml")
+    config = loader.expand(config)
+    builder = WorkspaceBuilder(session_config=config, server=session.server)
+    builder.build(session=session)
+
+    windows = session.windows
+    assert len(windows) == 3
+
+    synced_before = windows[0]
+    synced_after = windows[1]
+    not_synced = windows[2]
+
+    assert synced_before.show_option("synchronize-panes") is True
+    assert synced_after.show_option("synchronize-panes") is True
+    assert not_synced.show_option("synchronize-panes") is not True
+
+
+def test_lifecycle_hooks(session: Session) -> None:
+    """Test lifecycle-hooks.yaml loads without error."""
+    config = ConfigReader._from_file(EXAMPLE_PATH / "lifecycle-hooks.yaml")
+    config = loader.expand(config)
+    builder = WorkspaceBuilder(session_config=config, server=session.server)
+    builder.build(session=session)
+
+    assert len(session.windows) >= 1
+
+
+def test_config_templating(session: Session) -> None:
+    """Test config-templating.yaml renders templates and builds."""
+    config = ConfigReader._from_file(
+        EXAMPLE_PATH / "config-templating.yaml",
+        template_context={"project": "myapp"},
+    )
+    config = loader.expand(config)
+
+    assert config["session_name"] == "myapp"
+    assert config["windows"][0]["window_name"] == "myapp-main"
+
+    builder = WorkspaceBuilder(session_config=config, server=session.server)
+    builder.build(session=session)
+
+    assert len(session.windows) >= 1
+
+
+def test_pane_titles(session: Session) -> None:
+    """Test pane-titles.yaml builds with pane title options."""
+    config = ConfigReader._from_file(EXAMPLE_PATH / "pane-titles.yaml")
+    config = loader.expand(config)
+    builder = WorkspaceBuilder(session_config=config, server=session.server)
+    builder.build(session=session)
+
+    window = session.windows[0]
+    assert window.show_option("pane-border-status") == "top"
+    assert window.show_option("pane-border-format") == "#{pane_index}: #{pane_title}"
+
+    panes = window.panes
+    assert len(panes) == 3
+
+    def check_title(p: Pane, expected: str) -> bool:
+        p.refresh()
+        return p.pane_title == expected
+
+    assert retry_until(
+        functools.partial(check_title, panes[0], "editor"),
+    ), f"Expected title 'editor', got '{panes[0].pane_title}'"
+    assert retry_until(
+        functools.partial(check_title, panes[1], "runner"),
+    ), f"Expected title 'runner', got '{panes[1].pane_title}'"