We probably don't have to do that now, but maybe it's helpful to also expand the "Organize Data Into Buckets" page to mention that buckets can have metadata attached to them (like the priority YAML key or the _priority parameter of a parameter query).

That's a great catch, thanks - I'll work on that next 👍

I realize that it says the same thing in the paper doc, but I think this may be confusing for users.

When multiple parameter queries are involved, we would create multiple internal buckets for that. These internal buckets will have independent priorities based on the parameter row defining them. Considering something like this:

bucket_definitions:
  projects:
    parameters:
      - SELECT id AS project_id, 2 AS _priority FROM projects WHERE NOT important AND ...;
      - SELECT id AS project_id, 1 AS _priority FROM projects WHERE important AND ...;

Then, if there are 2 projects with important = TRUE and 3 projects with important = FALSE, we'll create 5 buckets of which 2 have the higher priority.

Oh, so that would behave as expected then - i.e. both priorities are considered and data is synced accordingly. So is the paper doc outdated on this note or is there a different nuance here that I'm missing?

I think the doc is just outdated, I don't see any nuance here either.