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

# Structural Index

> Compressed global view for structural awareness without loading the full score.

The Structural Index provides agents with global awareness of the score's structure without requiring the full content.

See: [`/MRS-Specification-RFC#9-structural-index`](/MRS-Specification-RFC#9-structural-index)

## Purpose

Agents operating on a focused region need to understand:

* Where they are in the overall form
* Key areas and tempo changes
* What instruments are active
* Rehearsal mark locations

The Structural Index provides this without loading the entire score.

## Index Structure

```clojure theme={null}
(structural-index
  :hash "sha256:abc123..."
  :source-hash "sha256:def456..."
  
  :form
    (sections
      (section :type exposition :measures #uuid "..." #uuid "..." :display [1 64])
      (section :type development :measures #uuid "..." #uuid "..." :display [65 120])
      (section :type recapitulation :measures #uuid "..." #uuid "..." :display [121 180]))
  
  :key-areas
    ((region :key C :mode minor :measures #uuid "..." #uuid "...")
     (region :key Eb :mode major :measures #uuid "..." #uuid "...")
     (region :key G :mode minor :measures #uuid "..." #uuid "..."))
  
  :tempo-map
    ((tempo :bpm 120 :measures #uuid "..." #uuid "...")
     (tempo :bpm 80 :text "Adagio" :measures #uuid "..." #uuid "..."))
  
  :players-summary
    ((player woodwind-2 :instruments [flute-2 piccolo] :active-measures [...])
     (player clarinet-1 :instruments [clarinet-bb] :active-measures [...]))
  
  :rehearsal-marks
    ((mark "A" :measure #uuid "..." :number 16)
     (mark "B" :measure #uuid "..." :number 32)
     (mark "C" :measure #uuid "..." :number 48))
  
  :total-measures 180
  :total-duration "12:34")
```

## Index Fields

### Form

```clojure theme={null}
:form
  (sections
    (section :type exposition :measures #uuid "..." #uuid "..." :display [1 64])
    (section :type development :measures #uuid "..." #uuid "..." :display [65 120]))
```

| Field       | Description                                        |
| ----------- | -------------------------------------------------- |
| `:type`     | Section type (exposition, development, coda, etc.) |
| `:measures` | UUID range                                         |
| `:display`  | Human-readable measure numbers                     |

### Key Areas

```clojure theme={null}
:key-areas
  ((region :key C :mode minor :measures #uuid "..." #uuid "...")
   (region :key Eb :mode major :measures #uuid "..." #uuid "..."))
```

### Tempo Map

```clojure theme={null}
:tempo-map
  ((tempo :bpm 120 :measures #uuid "..." #uuid "...")
   (tempo :bpm 80 :text "Adagio" :measures #uuid "..." #uuid "..."))
```

### Players Summary

```clojure theme={null}
:players-summary
  ((player woodwind-2 :instruments [flute-2 piccolo] :active-measures [...])
   (player clarinet-1 :instruments [clarinet-bb] :active-measures [...]))
```

### Rehearsal Marks

```clojure theme={null}
:rehearsal-marks
  ((mark "A" :measure #uuid "..." :number 16)
   (mark "B" :measure #uuid "..." :number 32))
```

## Index Derivation

The structural index can be:

| Source        | Description                            |
| ------------- | -------------------------------------- |
| **Derived**   | Automatically computed from the score  |
| **Enhanced**  | Enriched by analytical overlays        |
| **Annotated** | Manually labeled (form, section names) |

### Automatically Derived

* Measure count
* Key signature changes
* Tempo changes
* Rehearsal marks
* Player/instrument activity

### Requires Analysis/Annotation

* Form labels (exposition, development, etc.)
* Thematic regions
* Phrase structure

## Usage in Working Sets

Working Set Envelopes include a reference to the structural index:

```clojure theme={null}
(working-set
  ...
  :structural-index-ref "sha256:abc123..."
  ...)
```

Agents can use this to:

* Understand where they are in the form
* Check what other instruments are active
* Find rehearsal marks for reference
* Understand key and tempo context

## Index vs Context Views

| Structural Index  | Context Views        |
| ----------------- | -------------------- |
| Global overview   | Task-specific detail |
| Read-only summary | May include content  |
| Always available  | Selected per task    |
| Score-level info  | Region-level info    |

Both are used together: the index for global awareness, context views for task-specific information.