How-to

Groups and families

Groups are the categories a lens sorts by, and the colours you read it with. Families are what you reach for when there are too many groups to tell apart.

Add a group

Open lens settings and add one. A group has three things: a key (lowercase, dash-separated — what a paste writes in group:), a label (what you read), and a colour.

The key is the one to think about for a second, because it is what any imported content has to match. congress is a good key; Congress & Its Committees is a label pretending to be one.

A node whose group: names a key you have not declared imports ungrouped, with a warning. Nothing is lost — grouping is a property you can set afterwards — but it is easier to declare the group first.

Assign nodes in bulk: paint mode

Assigning groups one node at a time through a panel is the slow way. From lens settings, start painting with a group selected, then click nodes on the graph to assign them. It is the fastest way to bring order to a lens that arrived as a heap — including one that just landed from an import.

Painting is a good moment to notice structure, too. Nodes that resist being painted anything usually want a group you have not created yet.

Colours, and the one that is refused

Pick anything, with one exception: grey is not available, and neither is anything washed out enough to read as grey. A dusty rose passes; a slate grey does not.

This is not fussiness about palettes. Grey means draft — a node a model wrote that you have not read — and it can only mean that if it never means anything else. One grey family would make hundreds of settled nodes read as provisional, which breaks the only signal that stands between generated content and your flashcard deck. Some of my nodes are grey.

If you do not choose a colour, one is derived from the group's key — stable, so the same key is always the same colour, and never neutral by construction.

Families

Past about ten groups, a graph stops being readable: ten hues at a glance is more than a map can carry. A family is a parent level over groups — The Investigators over Congress, the Special Prosecutor and the Press.

You do not create a family as a separate object and then fill it. A group names a family key, and the family exists because groups point at it. Same trick as macro lenses: the level is derived from the arrangement, so it cannot fall out of step with what is actually there. Move the last group out and the family stops existing.

Reading at two levels

With families in play, the graph colours nodes by family by default, which is what keeps it readable. There is a toggle that turns that off and paints each group its own colour again — worth flipping when you are working inside one family and want the detail back.

When you want to see	Colour by
The shape of the whole lens	Family. Fewer hues, legible at a glance.
Distinctions inside one family	Group. Turn families off.

Renaming and deleting

Renaming a label is free — it is what you read, and nothing points at it.
Changing a key is not the same act. Nodes reference the key, so treat it the way you would treat a slug: decide it early, and change it only deliberately.
Deleting a group does not delete its nodes. They become ungrouped, which is a visible, recoverable state — you can paint them into something else whenever you like. The app tells you how many are affected before you confirm.

Groups are not kinds

Worth keeping straight, because they look alike and behave oppositely.


Group	A decision you make about this lens. Declared in settings, carries a colour, and a node can only be in one you declared.
Kind	An observation about what a node is — person, event, document. Never declared anywhere; the lens simply has whatever kinds its nodes use. There is no settings page for them, and its absence is the design.

Lenses, nodes and links — where groups sit in the model.
Typed relations — the other half of a lens's vocabulary.
The paste format — how group: is read on the way in.