Tutorial 04: Understand entities, relations, and types

Continue from Tutorial 03 with the palmerpenguins repository open and [loom_demo] loaded.

This tutorial explains Loom's Entity/Relation model: an Entity says what a fact is, while Relation edges connect facts and create reusable ways to find them across types.

Start here: make loom_demo the session default

1. Connect entities with relation edges

The inventory grouped facts by their Entity type. Now add a cross-cutting Relation edge and use that edge as the filter. This keeps the Roadmap item a Roadmap item; it only gives the fact an additional importance label.

Important items (important or critical):
  - Roadmap: publish runnable onboarding demo for new agents [important]
  - Decision: small reviewed tutorial changes before live deploys [critical]

The result contains at least these two items; if you have already run later tutorials, other marked facts (such as the critical palmerpenguins Decision from Tutorial 08) appear here too — that is expected. The query crosses Entity types because it follows the shared Has() Relation: one result is a Roadmap, the other a Decision. This is the central advantage of the Entity–Relation model: Entity types preserve what each fact is, while Relation edges provide reusable ways to connect and filter otherwise different kinds of facts.

2. Choose among the main loom-coding types

[loom_demo] ships with a small, curated catalog of declared types rather than a blank slate. Loom's ontology splits along one axis first: Record is append-only history (a superseded entry stays, a new one is appended — never overwritten), while Document is mutable, supersedable knowledge. Almost everything you will touch day-to-day is a concrete subtype of one of these two.

Choosing the right type makes future recall precise: a standing instruction should surface as a Directive, while a measured result should remain a Finding. The catalog lets agents reuse those meanings instead of inventing a new schema in every session.

Record family (parent = Record — append-only; latest supersedes for reads):
  - Directive(statement)  — a standing rule/constraint the agent must follow
  - Decision(statement)   — a decision made, with rationale
  - Proposal(statement)   — a not-yet-decided design direction
  - Goal (abstract)       — durable objectives/intents; declare a concrete
                            subtype per kind, e.g. LearningGoal("Python") <: Goal

CodeDoc family (parent = CodeDoc <: Document — mutable, supersedable knowledge):
  - Architecture(title)   — how a component is built and why
  - AreaMap(title)        — WHERE a subsystem/business-function lives
  - BusinessContext(title)— why it exists / domain model / how code maps to value
  - Deliverable(title)    — a shipped artifact (skill, server, binary)
  - Environment(title)    — setup, versions, transport, paths, where state lives
  - Finding(title)        — a measured result, benchmark outcome, or dead-end
  - Glossary(title)       — a project-vocabulary term; definition lives in content
  - Mechanism(title)      — WHAT a code unit does / the invariant it enforces (SHA-anchored)
  - Recipe(title)         — exact run/build/test how-to; commands live in content
  - Roadblocker(title)    — a CURRENT impediment; root cause + fix in content
  - Roadmap(title)        — planned-but-not-done work; execution conditions in content

Two more things worth knowing while you're browsing the catalog:

• Every fact is one Entity (the sortal above) plus edges. The three edges you'll reach for constantly are Author() (attribution; see section 2, “Resolve your GitUser identity,” in Tutorial 03), InScope() (scope; see section 3, “Build the project, workspace, and organization scope chain,” in Tutorial 03), and IsAbout() (subject — points at a declared concrete type, such as the shipped Release()/Deploy()/Publish() under the DevOps family, never a freeform string).
• Has() -> Importance("normal"|"important"|"critical") is how priority is recorded, as §1 demonstrated. It is a declared 3-level label, not a count that grows from repetition — omitting the edge means "normal".

You do not need to memorize this table. Ask Loom to show its types or suggest the closest existing types whenever you need them. The point of this tour is knowing the two families exist and roughly what each concrete type is for, so a Directive doesn't get saved as a Finding by habit.

3. Takeaways

• Entity types say what facts are; shared Relation edges add query axes across otherwise different types.
• The catalog separates append-only records from mutable, supersedable coding knowledge.
• Ask Loom to show the live catalog instead of memorizing it or inventing a type.
• Continue to Tutorial 05: Capture directives and findings.