Clarify difference between tree_path and tree_ordering in documentation

[Copilot]

Enhances the documentation to clearly explain the difference between tree_path and tree_ordering fields, addressing user confusion particularly when using UUID primary keys.

Problem

Users were confused about the purpose and content of tree_path vs tree_ordering fields, especially when using UUID primary keys where both fields would contain identical UUID values by default. The existing documentation briefly mentioned these fields but didn't clearly explain their distinct purposes.

Solution

Enhanced brief description: Updated the initial explanation in the limitations section to be more descriptive about what each field contains, with specific mention of the UUID primary key case.

Added comprehensive "Understanding tree fields" section with:

• Clear definitions of each field (tree_depth, tree_path, tree_ordering)
• Concrete example showing how fields differ in practice:

  # tree_path shows the route through primary keys: Root -> Child A -> Grandchild
  assert grandchild.tree_path == [1, 2, 4]  # [root.pk, child_a.pk, grandchild.pk]
  
  # tree_ordering shows ordering values at each level
  assert grandchild.tree_ordering == [0, 10, 5]  # [root.order, child_a.order, grandchild.order]

UUID-specific guidance: Explains why UUID users see identical values in both fields (default primary key ordering) and provides a practical solution using explicit ordering fields like position.

Key clarifications

• tree_path: Array of primary keys from root to current node (like a breadcrumb trail)
• tree_ordering: Array of ordering/ranking values used for sibling ordering at each level
• With UUID PKs and no explicit ordering, both contain the same UUID values by default
• Adding a position field with ordering = ['position'] makes the distinction clear

Fixes #20.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[matthiask]

This doesn't just apply for UUID primary keys, but for all models without a sibling ordering field.

[matthiask]

The note regarding tree_path and tree_ordering containing the same values doesn't just apply to UUID fields.