id: intro-fragment-structure
prism: public-intro
scope: public
tags:
- introduction
- prism
- scene
- design
title: Why Fragment keeps structure, text, and behaviour in one page

Fragment in one page

Fragment is a notebook designed to bind minimal structure, narrative text, and AI behaviour in a single page.
This Fragment explains the core design philosophy across four layers: front‑matter / Prism / Scene / Markdown.

---

1. Front‑matter --- A small, stable schema

Each page maintains a compact YAML schema:

• id / title / scope / tags
• Default Prism profile (how AI should read the page)

This keeps metadata consistent, predictable, and easy for both UI and AI to use.

---

persona:
  name: "Fragment Intro Guide"
role: "explain the conceptual layers simply"
tone:
  style: "calm"
  directness: "concise"
focus:
  emphasise:
    - "small schema per page"
    - "inline YAML is structure, Markdown is narrative"
    - "AI and humans share the same text"
  avoid:
    - "implementation detail"

---

2. Inline YAML blocks --- Structure only where needed

Beyond front‑matter, you can add structured blocks only when a page demands it:

• block:config
• block:task
• block:calendar
• block:scene / block:flow (text-based diagrams)

Fragment avoids bloating front‑matter and lets you place structure exactly where it belongs.

---

3. Scene --- Diagrams as text

Instead of images or binary formats, diagrams stay in text.
They remain readable, AI‑friendly, diff‑able, and searchable.

canvas:
  width: 720
  height: 260
shapes:
  - type: rect
    x: 40
    y: 96
    w: 200
    h: 64
    text: "Front-matter\n(small schema)"

  - type: rect
    x: 280
    y: 96
    w: 200
    h: 64
    text: "Prism block\n(AI DSL)"

  - type: rect
    x: 520
    y: 96
    w: 200
    h: 64
    text: "Scene block\n(diagram DSL)"

  - type: arrow
    from: [240, 128]
    to:   [280, 128]

  - type: arrow
    from: [480, 128]
    to:   [520, 128]

---

4. Markdown --- Narrative, context, and explanation

Markdown holds the human‑readable narrative.

Fragment's philosophy is simple:

• Markdown is story and reasoning
• YAML blocks are structure
• Prism defines AI behaviour
• Scene is diagram as text
• All in one page, shared between humans and AI

---

Why this design matters

• AI becomes part of the page, not an external prompt container\
• No fragmentation between diagrams, settings, and narrative\
• Decisions stay explainable\
• Text remains portable, diff‑able, observable

Fragment's strength lies in text-first, unified pages.

---

Next steps

If you're considering restructuring your notes or workflows, start small:

• a weekly note\
• one project page\
• a lightweight decision memo

Everything---diagram, structure, behaviour, and narrative---can start on a single page.