# Loose Inserts

*Dowels, biscuits, & dominos as generated parts*

**Names:** `dowel` `biscuit` `domino`

## When to use

Use a `dowel`, `biscuit` or `domino` joinery (or an `edge_glue` with `biscuit_spacing`) when
two parts are joined by a loose piece glued into holes, slots or mortises cut in both. The
compiler cuts both cavities **and emits the loose piece itself**. Do not model the dowel,
wafer or domino as a `stock` part; it would be counted twice and reach the cut list.

## Syntax

No new syntax. The existing joinery nodes are unchanged:

- `joinery dowel { diameter D; count N; depth H; clearance C }` gives N round dowels, each
  D across and `2 * H` long.
- `joinery biscuit { size 0|10|20; spacing S }` gives one #0 (47 x 15), #10 (53 x 19) or #20
  (56 x 23) wafer, 4 thick, per whole `S` of the joint, at least one.
- `joinery domino { size 4|5|6|8|10; spacing S; depth H }` gives one loose tenon per whole
  `S` (size 8 is 8 x 22 x 40). `depth` defaults to half the tenon's length.
- `edge_glue` with `biscuit_spacing` and `biscuit_size` emits biscuits; without
  `biscuit_spacing` it emits nothing.

Each insert is a generated part, `role=insert`, in the male part's material, with id
`<male>@<mark>/Dowel_<i>`, `/Biscuit_<i>` or `/Domino_<i>`. It is **bought, not cut**
(ADR-0017): it appears in the scene, drawings, exploded views and clash check and in the
hardware schedule (`Dowel 8 x 24`, `Biscuit #20`, `Domino 8 x 22 x 40`, quantity summed over
every join), and in no cut list, stock list, cut card or toolpath.

## Example

```kdl
project name="Doweled rail" units=mm schema_version=1 {
    materials { material Oak type=hardwood }

    component Post {
        stock Oak 38.0 38.0 130.0
        mark Face x=38.0 y=19.0 z=-65.0 normal=pos_x
    }
    component Rail {
        stock Oak 110.0 19.0 38.0
        mark End x=0.0 y=9.5 z=-19.0 normal=neg_x
    }
    joinery dowel name=Dowels {
        diameter 8.0
        count 2.0
        depth 20.0
        clearance 0.2
    }

    assembly Joint {
        part Post instance=Post { pos x=0.0 y=0.0 z=0.0 }
        part Rail instance=Rail { pos x=38.0 y=9.5 z=-46.0 }
        join joint=Dowels male=Rail@End female=Post@Face
    }
}
```

Compiling this gives two parts, `Rail@End/Dowel_0` and `Rail@End/Dowel_1`, each a 8 x 40 round
revolve straddling the joint plane, and two hardware rows' worth of purchased dowels
(`Dowel 8 x 40`, quantity 2).

## Pitfalls and diagnostics

- **Double counting.** A hand-modelled `stock` dowel, wafer or domino beside the join is now a
  second piece; delete it.
- **`insert-fit` (domino).** `2 * depth` shorter than the tenon's length leaves the tenon
  standing out of the mortises. Raise `depth`, or pick a smaller `size`.
- **Clash.** An insert overlapping its own joint's two parts is design interference, not a
  clash (RFC-0090 section 5). An insert that meets any third part, or overlaps its own parts
  beyond the tessellation budget, is reported as a clash. Two joints whose holes cross inside
  one part (a bottom rail's dominos and a stile's alignment biscuit slot, as in
  `examples/bookcase.kdl`) show up this way: it is a real modelling overlap.
- **`clearance` is female-only** (ADR-0012): the insert is nominal, fills the male cut and sits
  shy in the female one.
- Inserts are never in the cut list: a cut list is unchanged by adding or removing these joints.
- The hardware schedule label is the nominal size, so a #20 biscuit prints `Biscuit #20`.

## See also

- `docs/KDL_AUTHORING.md` section 8, "What the compiler cuts, and what it checks"
- `docs/rfc/0140-loose-inserts.md`, `docs/adr/0023-loose-inserts.md`
- `docs/adr/0017-hardware-and-materials.md` (bought, never cut), `docs/adr/0018-turned-stock.md`
- `docs/styles/models/{dowel,biscuit,domino}-joint.kdl`: the glossary's real joints

## Names

Every name this page declares, how the example library uses it, and the shortest real use.

### `dowel`

joinery kind; value in 32 of 116 examples (54 uses).

Shortest real use, from `tall_white_cutout_cabinet.kdl`:

```kdl
joinery dowel name=TopDowel {
    diameter 8.0
    count 3
    depth 18.0
    clearance glue_clearance
}
```

### `biscuit`

joinery kind; value in 1 of 116 examples (2 uses).

Shortest real use, from `bookcase.kdl`:

```kdl
joinery biscuit name=TopEdgeGlue {
    size biscuit_size
    spacing biscuit_spacing
    clearance glue_clearance
}
```

### `domino`

joinery kind; value in 1 of 116 examples (1 uses).

Shortest real use, from `bookcase.kdl`:

```kdl
joinery domino name=FrameCorner {
    size domino_size
    spacing domino_spacing
    depth domino_depth
    clearance glue_clearance
}
```

## Related terms

- [Biscuit joint](/almanac/techniques#biscuit-joint)
- [Domino joint](/almanac/techniques#domino-joint)
- [Dowel joint](/almanac/techniques#dowel-joint)