Filesystem-First Pivot: Move Org State from Strings to Files

This is not a cosmetic rename.

It is a storage boundary change. Matic's durable org state moves out of Python string constants and into markdown files under assets/templates/ and org folders on disk. That move matters because it changes what counts as the source of truth.

If the state is on disk, it can be inspected, diffed, branch-merged, reviewed, and recovered with ordinary tools. If the state lives in string constants, it can be rendered, but it is still too easy to treat the code as the record. The pivot rejects that shortcut.

Files are the source of truth

The filesystem-first rule is simple: files are the source of truth, and folders carry entity identity.

That means the durable record should be written as readable files, not buried in generated Python literals. The org root should be represented as files that a human can open directly. The structure should be obvious enough that the repository itself explains how the org exists.

For this pivot, org.md is better than a JSON record because it keeps the org legible. When structure is needed, markdown frontmatter can carry it. The body can still explain the org in human-readable prose. That is the right default for a system that wants humans and agents to reason over the same operational substrate.

What the template assets now do

The new template layer is not just a prettier scaffold. It is the materialization path for core org primitives.

Template assets now drive the creation of:

• org materialization
• agent materialization
• workflow materialization
• stage materialization
• task materialization
• routine materialization
• channel materialization

That is a meaningful change because it turns the template layer into an organizational blueprint layer. The template is no longer a loose starter kit. It is the reusable shape that can be applied consistently across new roots.

The default format has a hierarchy

The pivot also clarifies format boundaries.

• markdown is the default human-readable format
• YAML is reserved for machine-only surfaces and structured frontmatter
• JSON appears only when a third-party boundary imposes it

That hierarchy keeps the filesystem-first model honest. If a thing is primarily for humans, it should read like a file humans can understand. If a thing exists only to satisfy a machine interface, then structure can be tighter. But the exception should stay the exception.

Stable leaf files matter

The hard part of filesystem-first design is resisting the temptation to let handles leak into file names everywhere.

Stable leaf files matter more than handle-derived markdown leaves. A durable org should converge on a small set of canonical file names that mean the same thing across entities and routing. That is how a human can learn the system once and recognize it everywhere.

Good template design prefers stable leaves like:

• profile.md
• spec.md
• result.md
• history.md

Those names do more work than one-off file naming schemes ever will. They make the organization easier to inspect and easier to extend without inventing new shapes for every entity.

What this unlocks

The value of this move is not just cleaner storage.

It sets up the rest of the pivot by making the filesystem the operational substrate for later runtime work. Once org state lives on disk in a consistent markdown-first shape, routines, channels, and runtime execution can all be layered on top without reverting to hidden state.

That is the point of the pivot:

• keep the record on disk
• keep the shapes stable
• keep the defaults readable
• keep Python out of the role of durable storage

This turns the filesystem into the primary operational database for Matic's org state. Everything later depends on that decision.