> ## Documentation Index
> Fetch the complete documentation index at: https://musicready.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get started with MRS-S and MRS-Ops for AI-assisted composition.

## One Semantic Model, Multiple Representations

MRS is a semantic score model plus protocols for safe, bounded editing. It is commonly represented in two complementary forms:

| Representation | Purpose                                                      | Who Uses It                                               |
| -------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
| **MRS-S**      | Complete score semantics for reading, audit, and interchange | Humans review; agents read; orchestrator can export/store |
| **MRS-Ops**    | Typed mutations (explicit edits)                             | Agents write; orchestrator validates/applies              |

An implementation may keep canonical state in a database/graph form for performance, then export MRS-S as needed.

Agents read MRS-S content in Working Set Envelopes. Agents write MRS-Ops operations. The orchestrator validates and applies operations to canonical state.

## File Types

* **MRS-S**: `.mrs` or `.mrs-s` — `application/vnd.mrs+sexpr`
* **MRS-Ops**: `.mrs-ops` — `application/vnd.mrs-ops+sexpr`
* **Encoding**: UTF-8 (no BOM)

See: [`/MRS-Specification-RFC#16-mime-types-and-file-extensions`](/MRS-Specification-RFC#16-mime-types-and-file-extensions)

## Minimal MRS-S Score

```clojure theme={null}
(mrs-s 1.0
  (meta
    :title "Untitled")
  
  (players
    (player violin-player
      :name "Violin"
      :instruments [violin-1]
      :default violin-1))
  
  (instruments
    (instrument violin-1
      :name "Violin"
      :abbr "Vln."
      :family strings
      :staves [treble]
      :transposition none
      :range [G3 E7]))
  
  (measures
    (measure 
      :id #uuid "018c3f40-0001-7890-abcd-ef1234567890"
      :number 1
      :beat-start 0
      :time 4/4
      (violin-1
        (v1
          (: 0 C4.q :id #uuid "018c3f2a-0001-...")
          (: 1 D4.q :id #uuid "018c3f2a-0002-...")
          (: 2 E4.q :id #uuid "018c3f2a-0003-...")
          (: 3 F4.q :id #uuid "018c3f2a-0004-...")))))
  
  (spans))
```

Key points:

* Every measure has `:id` (UUID) and `:number` (display)
* Every event has `:id` (UUID) — no `:at` required in storage (orchestrator computes it)
* Players own instruments; instruments appear in measure content

## Working Set Envelope

For agent tasks, the orchestrator extracts a Working Set Envelope:

```clojure theme={null}
(working-set
  :version 1.0
  :source-hash "sha256:..."
  
  :scope
    (:measures #uuid "018c3f40-0001-..." #uuid "018c3f40-0008-...")
    (:instruments [clarinet-bb])
  :display-hint (:measures 1 8)
  
  :bundle orchestrate
  :allowed-ops [create-event update-event delete-event create-span]
  
  :task "Add clarinet countermelody"
  
  :content
    (meta :time 4/4 :key C :mode minor :tempo 132)
    (instruments
      (instrument clarinet-bb :name "Clarinet in Bb" :abbr "Cl." 
                  :staves [treble] :transposition (down M2)))
    (measures
      (measure 
        :id #uuid "018c3f40-0001-..."
        :number 1
        :beat-start 0
        (clarinet-bb (v1))))  ; Empty — target for agent
    (spans)
  
  :context-views
    (context-view melodic-reference
      :instruments [violin-1]
      :content (measures ...))
    (context-view harmonic-context
      :content (harmony-events ...))
  
  :structural-index-ref "sha256:...")
```

Key features:

* **Scope uses UUIDs** — not measure numbers
* **`:bundle`** grants lane permissions
* **`:context-views`** provide task-relevant information
* **`:content`** is valid MRS-S the agent can read

## Agent Output: MRS-Ops

Agents write typed operations, not complete fragments:

```clojure theme={null}
(mrs-ops
  :version 1.0
  :scope-hash "sha256:..."
  
  :ops
    ((create-event :tmp-id "e1" :measure #uuid "018c3f40-0001-..." 
                   :instrument clarinet-bb :voice v1
                   :beat 0 :pitch Eb4 :duration q :dyn mp)
     (create-event :tmp-id "e2" :measure #uuid "018c3f40-0001-..."
                   :instrument clarinet-bb :voice v1
                   :beat 1 :pitch D4 :duration q)
     (create-event :tmp-id "e3" :measure #uuid "018c3f40-0001-..."
                   :instrument clarinet-bb :voice v1
                   :beat 2 :pitch Eb4 :duration e)
     (create-event :tmp-id "e4" :measure #uuid "018c3f40-0001-..."
                   :instrument clarinet-bb :voice v1
                   :beat 2+1/2 :pitch F4 :duration e)
     (create-event :tmp-id "e5" :measure #uuid "018c3f40-0001-..."
                   :instrument clarinet-bb :voice v1
                   :beat 3 :pitch G4 :duration q)
     
     (create-span :tmp-id "s1" :type slur :from "e1" :to "e5")))
```

Key features:

* **Explicit operations**: `create-event`, not "here's the whole fragment"
* **Temporary IDs**: `"e1"`, `"s1"` — orchestrator assigns UUIDs
* **No derived fields**: No `:at` required — orchestrator computes it
* **Spans reference tmp-ids**: `"e1"` in same envelope is valid

## Orchestrator Response

```clojure theme={null}
(mrs-ops-result
  :status success
  :id-mapping
    (("e1" #uuid "019b2c3d-0001-...")
     ("e2" #uuid "019b2c3d-0002-...")
     ("e3" #uuid "019b2c3d-0003-...")
     ("e4" #uuid "019b2c3d-0004-...")
     ("e5" #uuid "019b2c3d-0005-...")
     ("s1" #uuid "019b2c3d-0010-..."))
  :applied 6
  :revision "rev:def456")
```

## The Workflow

```
1. Orchestrator extracts Working Set Envelope
   (MRS-S fragment + task-adaptive context + permissions)

2. Agent reads MRS-S content and context views
   
3. Agent produces MRS-Ops (typed operations with tmp-ids)

4. Orchestrator validates progressively:
   - Syntax → References → Permissions → Musical Rules

5. Orchestrator applies:
   - Maps tmp-ids to UUIDs
   - Computes derived fields
   - Updates canonical state

6. Orchestrator returns result (success or specific errors)
```

## Why This Works

| Failure Mode        | How MRS-Ops Eliminates It       |
| ------------------- | ------------------------------- |
| Accidental deletion | Explicit delete-event required  |
| Calculation errors  | Orchestrator computes :at       |
| Hallucinated IDs    | Orchestrator validates all refs |
| UUID collisions     | Orchestrator mints all UUIDs    |

See: [`/MRS-Specification-RFC#5-mrs-ops-the-mutation-protocol`](/MRS-Specification-RFC#5-mrs-ops-the-mutation-protocol)