> For the complete documentation index, see [llms.txt](https://codifi-fdm.gitbook.io/codifi-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://codifi-fdm.gitbook.io/codifi-docs/web-app/composition-builder/library.md).

# The Library

The **Library** is your organization's shared catalog of reusable building blocks for Compositions. Every archetype, field, value list, status workflow, and Ripple formula in your tenant lives in the Library — and any of them can be referenced by multiple Compositions.

Think of the Library as a parts bin: parts are checked out by reference, not by copy, so a single library entity might be used by ten different Project templates at the same time.

***

## What's in the Library

| Entity type           | What it is                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------- |
| **Archetypes**        | Record templates (Site, Feature, Shovel Test Probe, etc.)                                 |
| **Fields**            | Individual data inputs (text, number, date, dropdown, etc.)                               |
| **Value Lists**       | Dropdown options used by one or many fields ("Soil Type" with options Sand / Loam / Clay) |
| **Status Lists**      | Project and Record lifecycle workflows (In Progress, Ready for Review, Approved)          |
| **Ripple Formulas**   | Calculated-field formulas, visibility rules, and spatial logic                            |
| **Map Symbology**     | Point/line/polygon styling for archetypes (also stored on each archetype)                 |
| **Project Templates** | Packaged Compositions ready to spawn new Projects                                         |

You access the Library from the main web nav. Composer is the only non-admin role with edit rights — see [RBAC](/codifi-docs/cross-platform-features/roles-based-access-controls-rbac.md).

***

## Library entities are shared by reference

When two archetypes reference the same field — say, "Date Recorded" — they share the *same* field, not two copies. Updating that field in the Library (renaming, changing attributes) updates it everywhere it's used.

This is powerful but also dangerous. Some changes that propagate instantly across every archetype using a shared library entity:

* Renaming the field's label.
* Changing dropdown options on a value list.
* Editing a Ripple formula on a calculated field.
* Updating an archetype's symbology (point color, line width).

If you want to make a change that should affect **only one Composition**, **clone the library entity first**. See "When to clone" below.

> **Important:** Library entity changes propagate to *new* Projects immediately, but **not** to existing Projects already created from a template. Existing Projects keep their own snapshot of the template they were created from. See [Project Templates](/codifi-docs/web-app/composition-builder/project-templates.md).

***

## Naming conventions

Library entities are scoped per tenant, so the entity **name** must be unique across the tenant — even when many Compositions use the same human-facing label.

The convention most orgs settle on:

* **`name` field (internal, unique)** — Prefix with Composition or state code to disambiguate. Examples: `TX_HR_Title`, `UT_Site_Number`, `NE_Stratum_Depth_Below_Datum`.
* **`label` field (user-facing, displayed)** — Drop prefixes. Just the clean human-readable name: "Title," "Site Number," "Depth Below Datum." This is what crews see on chips, headers, and the form.

The internal name is for de-duping in the Library; the label is for the user.

> **Screenshot placeholder:** *A field's settings panel in the Library showing distinct `name` and `label` inputs.*

***

## When to clone a library entity

Cloning copies an entity into a new one with a fresh ID, so changes to the clone don't affect the original (and vice versa).

**Clone when:**

* A change is specific to one Composition and you'd otherwise have to modify the shared entity.
* You want to start a new Composition that's similar to an existing one — clone the whole tree (archetype + fields + relationships) and edit the copy.
* You're "promoting" a Composition from Sandbox to Projects tenant — clone everything across, then break shared references.

**Don't clone when:**

* A change should reasonably apply everywhere the entity is used (e.g., fixing a typo in a value list option).
* The entity is genuinely shared for organizational reasons (e.g., a company-wide "Project Status" workflow).

When in doubt, ask: "If I make this change, does every other Composition using this entity benefit, or does it break their expectations?"

***

## The Sandbox → Projects workflow

Many orgs run two tenants:

* **Sandbox tenant** — for authoring, testing, and training. New Compositions live here while they're under development.
* **Projects tenant** — for live client work. Compositions promoted from Sandbox after testing.

Each tenant has its own Library. Promoting a Composition between tenants means copying every entity it depends on (archetype, fields, value lists, Ripple formulas). The Web app provides cross-tenant cloning flows for this; see [Project Templates](/codifi-docs/web-app/composition-builder/project-templates.md) for the details.

***

## What a typical Composition references

A medium-sized Composition (e.g., a state CRM phase I survey) might touch:

* 1 Project Details archetype
* 5–15 Record archetypes (Site, Feature, Shovel Test, etc.)
* 1 Project Status list
* 1 Record Status list (per archetype, or shared)
* 50–200 Fields
* 5–30 Value Lists
* 10–40 Ripple formulas (calculated fields + visibility rules + spatial logic)
* 1 Project Template that wires it all together

Bigger Compositions can run 3–4× that. The Library is your organization's inventory of all the parts that any Composition can reach for.

***

## Related

* [Archetypes & Relationships](/codifi-docs/web-app/composition-builder/archetypes-and-relationships.md) — designing Record types and their parent-child structure
* [Fields & Field Types](/codifi-docs/web-app/composition-builder/fields-and-field-types.md) — picking the right field type and configuring attributes
* [Project Templates](/codifi-docs/web-app/composition-builder/project-templates.md) — packaging archetypes into a publishable template
* [Ripple](/codifi-docs/cross-platform-features/ripple.md) — the formula engine for calculated fields and visibility rules