Arcs

An arc is a standalone construct used to explain or tell a smaller story by pointing to a curated set of existing named things.

Arcs are intentionally non-structural. They do not change organization, identity, or semantics within a universe. Instead, they provide orientation: a human-authored explanation of why certain things are worth looking at together.

What an arc is

An arc is:

• Standalone – it does not participate in the container hierarchy
• Universe-scoped – arcs exist directly within a universe
• Authored – an arc always explains why it exists
• Referential – arcs point to existing named things

An arc answers the question:

“Why should I look at these things together?”

What an arc is not

An arc is not:

• a container (it does not establish ownership or scope)
• a type or alias (it does not classify things)
• a relationship (it does not assert truth)
• workflow or status (it does not imply process or obligation)
• part of the semantic graph

Arcs do not mutate the world. They only highlight it.

Syntax

arc HenrysLeadershipJourney {
  describe {
    This arc highlights key moments and documents that shaped Henry’s
    path into a leadership role within the council.
  }

  includes {
    Henry
    CouncilCharter
    TheFirstVote
  }

  references {
    LeadershipNotes
    CouncilHistory
  }
}

This arc does not change who Henry is, where the documents live, or how they relate to each other. It simply explains why these particular things are worth looking at together.

Blocks

describe { } (required)

Explains why the arc exists.

The description is the meaning of the arc. If the description is unclear, the arc is unclear.

Arcs are intended to be readable before traversal.

includes { }

A curated set of named things that form the core touchpoints of the arc.

• accepts names only (no kinds or aliases)
• items may appear in multiple arcs
• inclusion does not imply relationships or ordering
• intended to remain small and intentional

includes represents the spine of the arc.

references { } (optional)

Pointers to named references.

This block is used to attach:

• documentation
• external sources
• background material
• bibliographic context

References expand context without bloating the arc’s core focus.

Membership semantics

• Arcs group by reference, not containment
• Membership is non-exclusive
• Arcs do not imply completeness
• Arcs do not infer meaning between included items

An arc may be useful even if it includes only a few key elements.

Scope and interaction rules

• Arcs exist at universe scope
• Arcs do not participate in aliases
• Arcs do not participate in relationships
• Arcs are not valid relationship endpoints

This ensures arcs remain pure orientation artifacts, not semantic actors.

Discoverability

Arcs are not intended to be browsed as a primary organizational structure.

They are typically discovered:

• by reading an arc directly
• from an entity that is included in or referenced by an arc

This prevents arcs from becoming an alternate hierarchy or list index.

When to use an arc

Use an arc when you want to:

• explain a smaller story inside a larger universe
• provide a guided slice across many existing things
• connect ideas across containers without restructuring them
• orient a reader without asserting new semantics

If the grouping can be explained out loud in a sentence, an arc is usually appropriate.

Design intent

Arcs exist to help humans understand a universe without changing it.

They are optional, authored lenses that support explanation, narration, and orientation—nothing more, and nothing less.