@r0kshan/cairn 1.0.0-RC11 → 1.0.0-RC13

package/README.md

@@ -31,7 +31,8 @@ Furthermore, complexe software architecture with many flows and component genera
 | **Configurable dispositions** | `slide` and `page` dispositions available to suit different presentation requirements |
 | **Spacial optimization** | Cairn aims to optimize space as much as possible (Still working on improving this functionnality) |
 | **Typed diagrams with validation.** | Each view defines its element kinds and rules; `cairn validate` reports syntax, schema, and completeness issues as source-located, coded diagnostics, with a JSON mode for CI. |
-| **Infrastructure flow matrix.** | `cairn matrix` exports the flow matrix as CSV, Markdown, or SVG. Columns split protocol from port, annotate each endpoint with its network zone, and localise via `style { lang: fr }`. |
+| **Flow matrix.** | `cairn matrix` exports the flow matrix as CSV, Markdown, or SVG — from any view, with the columns that view can fill. In infrastructure it splits protocol from port and annotates endpoints that sit in a network zone; headers localise via `style { lang: fr }`. The same table is available to embedders through `compile(source, { matrix: true })`. |
+| **Author-controlled positioning.** | Layout is automatic, with three opt-in overrides for when it gets a diagram wrong: `order: 2` sequences a top-level element along the disposition's own reading direction (left to right in `wide`, top to bottom in `tall`) and sorts siblings inside a container, `A.right -> B.left` pins which side of an element a flow leaves and arrives on, and the arrow glyph carries the line style (`->` solid, `-->` dashed, `..>` dotted). |
 | **Enterprise-view extras.** | Business objects on flows, an auto-generated legend, and a numbered-flow table via `flow-text: numbered`. |
 | **French or English output.** | `style { lang: fr }` localizes band titles, legend, and matrix headers while keeping keywords English for portable sources (open to adding other languages if you find this usefull) |
 | **In-built themes and customizable colours** | Whether using the default or a chosen in-built theme, element colours can be overriden  for all elements of a given kind in the `style` block |
@@ -56,15 +57,10 @@ As a result here's a comparaison of the same diagram done with D2 (ELK Layout) v
     </tr>
     <tr>
       <td>I encountered overlapping issues for which I couldn't find a workaround</td>
-      <td>The overlapping issues have been addressed. A caveat remains: the long-distance arrow can affect readability (still working on improvements)</td>
+      <td>The overlapping labels have been addressed.</td>
     </tr>
     </table>
 
-## Known limitations I'm working on
-
-* While Cairn ensures 0 label overlap, flows on large diagrams still take a longer than neccessary route to the target element - issue [#26](https://github.com/R0kshan/cairn/issues/26) created to adress this
-* At the moment Cairn doesn't give the user the possibility to control positioning - issue [#8](https://github.com/R0kshan/cairn/issues/8) created to adress this
-
 ## Usage
 
 Either use the cli or the [ playground](https://cairn-psi-five.vercel.app/).
@@ -87,6 +83,27 @@ Every image below is rendered by cairn CLI from a `.cairn` source in [`examples/
 <p align="center"><img src="examples/application-medium.svg" alt="Medium application view" width="760"></p>
 <p align="center"><img src="examples/application-large.svg" alt="Large application view" width="760"></p>
 
+#### System boundaries
+
+`system` is a C4 system boundary: it groups the applications, queues and
+datastores that belong to one system — the small example above uses one. The
+flow matrix names an endpoint's nearest container, so a module reads
+`Name (App)` and a queue sitting directly in the system reads `Name (System)`.
+From [`examples/application-system.cairn`](examples/application-system.cairn):
+
+```cairn
+system ORDERS "Order platform" {
+  application ORDER_APP "Order management" {
+    module CAPTURE "Order\ncapture"
+    module VALIDATE "Order\nvalidation"
+  }
+  queue EVENTS "Order event\nbus"
+  datastore ORDER_DB "Order\nrepository"
+}
+```
+
+<p align="center"><img src="examples/application-system.svg" alt="Application view with a system boundary" width="760"></p>
+
 ### Infrastructure view diagram examples from small to large
 
 <p align="center"><img src="examples/infrastructure-small.svg" alt="Small infrastructure view" width="760"></p>
@@ -103,7 +120,7 @@ Colours are resolved at three levels — most specific wins. From lowest to high
 
 1. **Theme defaults** — per-kind colours defined by the selected theme (fill, stroke, text for each element kind).
 2. **Diagram-level per-kind overrides** — override colours for all elements of a given kind in the `style` block:
-   ```
+   ```cairn
    style {
      fill actor-group: #eef4fb
      stroke actor-group: #7a9cc4 dashed
@@ -112,12 +129,12 @@ Colours are resolved at three levels — most specific wins. From lowest to high
    }
    ```
 3. **Inline per-element styles** — override colour for a single element:
-   ```
+   ```cairn
    block API "API gateway" { style { fill: #e8f5e9  stroke: #2e7d32  text: #1b5e20 } }
    ```
 
 Flows can also be coloured inline:
-```
+```cairn
 COM_CTR -> OBS : "Alerts…" { label: above  stroke: dashed #a33  text: #a33 }
 ```
 
@@ -125,11 +142,93 @@ See [`examples/colors-custom.cairn`](examples/colors-custom.cairn) for a full ex
 
 <p align="center"><img src="examples/colors-custom.svg" alt="Custom colours" width="620"></p>
 
+### Positioning and flow line styles
+
+**Line style** — carried by the arrow glyph:
+
+```cairn
+TRIAGE -> TASKS (MQ, JSON)                 # solid — the default
+SCORING --> REINSURER (SFTP, CSV)          # dashed
+TRIAGE ..> REINSURER (API_REST, JSON)      # dotted
+```
+
+**Attachment sides** — pin either endpoint, or both, with `left`, `right`,
+`top` or `bottom`:
+
+```cairn
+FORM.right -> TRIAGE.left (API_REST, JSON)   # both ends pinned
+SCORING -> TASKS.right (MQ, JSON)            # only the arrival pinned
+SCORING.top -> TRIAGE.top (API_REST, JSON)   # a backward flow, pinned both ends
+```
+
+<p align="center"><img src="examples/positioning-sides.svg" alt="Flow attachment sides" width="760"></p>
+
+**Element ordering** — `order:` is a statement in the element's own body, not a
+`style` entry. Lower comes first along the disposition's reading direction: left
+to right in `wide`/`slide`, top to bottom in `tall`/`page`. From
+[`examples/placement/reading-order.cairn`](examples/placement/reading-order.cairn):
+
+```cairn
+application BACKEND_L1 "Line 1 backend" {
+  order: 1
+  module MSG_L1 "Messaging\nhandler"
+}
+application BACKEND_L2 "Line 2 backend" {
+  order: 2
+  module MSG_L2 "Messaging\nhandler"
+}
+```
+
+<p align="center"><img src="examples/placement/reading-order.svg" alt="Top-level elements sequenced by order:" width="620"></p>
+
+Inside a container the axis flips: `order:` sorts the siblings sharing a layer —
+top to bottom in `wide`, left to right in `tall`. From
+[`examples/positioning.cairn`](examples/positioning.cairn):
+
+```cairn
+actor-group STAFF "Payment actors" {
+  actor OPERATOR "Payment operator" { order: 1 }
+  actor AUDITOR "Compliance auditor" { order: 2 }
+}
+```
+
+Values need not be contiguous, and the hint never moves an element into another
+band. Where a declared order contradicts a flow, the order wins and the flow is
+drawn running backwards.
+
+<p align="center"><img src="examples/positioning.svg" alt="Element ordering, pinned sides and arrow glyphs" width="760"></p>
+
+More examples: [`examples/placement/`](examples/placement/) shows one shape four
+ways (`baseline.cairn`, `sides.cairn`, `reading-order.cairn`,
+`flow-label.cairn`), and [`examples/dispositions/`](examples/dispositions/) ships
+the attachment-sides file as `wide`, `tall`, `slide` and `page` variants.
+
+**Label position** — this one *is* style, so it lives in the `style` block and
+resolves at the usual three levels (view default, diagram, inline per flow). From
+[`examples/placement/flow-label.cairn`](examples/placement/flow-label.cairn):
+
+```cairn
+style {
+  flow-label: above     # on-line (default) | above | below
+}
+
+AGENT  -> RECEIVE : "File a claim"                            # above, from the style block
+ASSIGN -> SETTLE  : "Request settlement" { label: below }     # overridden per flow
+TRACE  -> STORE   : "Archive the trace" { label: on-line }    # back to the default
+```
+
+<p align="center"><img src="examples/placement/flow-label.svg" alt="Flow label positions" width="760"></p>
+
+`on-line` centres the text on the run behind a halo; `above`/`below` lift it clear
+by a fixed offset first. Either way the label is settled afterwards, so the
+zero-overlap gate holds. Every other diagram in this README shows the `on-line`
+default.
+
 ### Dispositions
 
 Same diagram different disposition : 
-- [Slide disposition](https://cairn-psi-five.vercel.app/#src=ZGlhZ3JhbSBsb2dpY2FsICJPbmxpbmUgYXBwb2ludG1lbnQgYm9va2luZyDigJQgbG9naWNhbCB2aWV3IgpzdHlsZSB7IGRpc3Bvc2l0aW9uOiBzbGlkZSB9CgphY3Rvci1ncm91cCBVU0VSUyAiVXNlcnMiIHsKICBhY3RvciBQQVRJRU5UICJQYXRpZW50Igp9CgphY3Rvci1ncm91cCBTVEFGRiAiU3RhZmYiIHsKICBhY3RvciBTRUNSRVRBUlkgIk1lZGljYWwgc2VjcmV0YXJ5Igp9CgpzeXN0ZW0gQk9PS0lORyAiQXBwb2ludG1lbnQgYm9va2luZyBzeXN0ZW0iIHsKICBsYXllciBGUk9OVCAiUHJlc2VudGF0aW9uIGxheWVyIiB7CiAgICBibG9jayBQT1JUQUwgIkJvb2tpbmdcbnBvcnRhbCIKICB9CiAgbGF5ZXIgQlVTSU5FU1MgIkJ1c2luZXNzIGxheWVyIiB7CiAgICBibG9jayBTQ0hFRFVMRVIgIlNsb3Rcbm1hbmFnZW1lbnQiCiAgICBibG9jayBOT1RJRiAiTm90aWZpY2F0aW9ucyIKICB9Cn0KCmV4dGVybmFsIEVYVCAiRXh0ZXJuYWwgc3lzdGVtcyIgewogIGJsb2NrIFNNUyAiU01TIGdhdGV3YXkiCn0KCiMgLS0tLSBidXNpbmVzcyBvYmplY3RzIC0tLS0KYnVzaW5lc3Mtb2JqZWN0IEJPX0FQUFQgIkFwcG9pbnRtZW50IiAic2xvdCBib29rZWQgYnkgYSBwYXRpZW50IHdpdGggYSBwcmFjdGl0aW9uZXIiCmJ1c2luZXNzLW9iamVjdCBCT19TTE9UICJTbG90IiAidGltZSB3aW5kb3cgb3BlbiBmb3IgYm9va2luZyIKClBBVElFTlQgLT4gUE9SVEFMIDogIlNlYXJjaCBhIHNsb3RcbmFuZCBib29rIiBbQk9fU0xPVF0KUE9SVEFMIC0+IFNDSEVEVUxFUiA6ICJCb29raW5nIHJlcXVlc3QiIFtCT19BUFBUXQpTQ0hFRFVMRVIgLT4gTk9USUYgOiAiQXBwb2ludG1lbnQgY29uZmlybWVkIiBbQk9fQVBQVF0KTk9USUYgLT4gU01TIDogIlNlbmQgU01TIHJlbWluZGVyIgpTRUNSRVRBUlkgLT4gU0NIRURVTEVSIDogIk9wZW4gLyBibG9ja1xuc2xvdHMiIFtCT19TTE9UXQpTQ0hFRFVMRVIgLT4gUEFUSUVOVCA6ICJBcHBvaW50bWVudFxuY29uZmlybWF0aW9uIiBbQk9fQVBQVF0KCmxlZ2VuZCB7CiAgbm90ZSAiSGVhbHRoIGRhdGEgaXMgc3RvcmVkIG9uIGNlcnRpZmllZCBoZWFsdGgtZGF0YS1ob3N0aW5nIGluZnJhc3RydWN0dXJlIgp9Cg==)
-- [Page disposition](https://cairn-psi-five.vercel.app/#src=ZGlhZ3JhbSBsb2dpY2FsICJPbmxpbmUgYXBwb2ludG1lbnQgYm9va2luZyDigJQgbG9naWNhbCB2aWV3IgpzdHlsZSB7IGRpc3Bvc2l0aW9uOiBwYWdlIH0KCmFjdG9yLWdyb3VwIFVTRVJTICJVc2VycyIgewogIGFjdG9yIFBBVElFTlQgIlBhdGllbnQiCn0KCmFjdG9yLWdyb3VwIFNUQUZGICJTdGFmZiIgewogIGFjdG9yIFNFQ1JFVEFSWSAiTWVkaWNhbCBzZWNyZXRhcnkiCn0KCnN5c3RlbSBCT09LSU5HICJBcHBvaW50bWVudCBib29raW5nIHN5c3RlbSIgewogIGxheWVyIEZST05UICJQcmVzZW50YXRpb24gbGF5ZXIiIHsKICAgIGJsb2NrIFBPUlRBTCAiQm9va2luZ1xucG9ydGFsIgogIH0KICBsYXllciBCVVNJTkVTUyAiQnVzaW5lc3MgbGF5ZXIiIHsKICAgIGJsb2NrIFNDSEVEVUxFUiAiU2xvdFxubWFuYWdlbWVudCIKICAgIGJsb2NrIE5PVElGICJOb3RpZmljYXRpb25zIgogIH0KfQoKZXh0ZXJuYWwgRVhUICJFeHRlcm5hbCBzeXN0ZW1zIiB7CiAgYmxvY2sgU01TICJTTVMgZ2F0ZXdheSIKfQoKIyAtLS0tIGJ1c2luZXNzIG9iamVjdHMgLS0tLQpidXNpbmVzcy1vYmplY3QgQk9fQVBQVCAiQXBwb2ludG1lbnQiICJzbG90IGJvb2tlZCBieSBhIHBhdGllbnQgd2l0aCBhIHByYWN0aXRpb25lciIKYnVzaW5lc3Mtb2JqZWN0IEJPX1NMT1QgIlNsb3QiICJ0aW1lIHdpbmRvdyBvcGVuIGZvciBib29raW5nIgoKUEFUSUVOVCAtPiBQT1JUQUwgOiAiU2VhcmNoIGEgc2xvdFxuYW5kIGJvb2siIFtCT19TTE9UXQpQT1JUQUwgLT4gU0NIRURVTEVSIDogIkJvb2tpbmcgcmVxdWVzdCIgW0JPX0FQUFRdClNDSEVEVUxFUiAtPiBOT1RJRiA6ICJBcHBvaW50bWVudCBjb25maXJtZWQiIFtCT19BUFBUXQpOT1RJRiAtPiBTTVMgOiAiU2VuZCBTTVMgcmVtaW5kZXIiClNFQ1JFVEFSWSAtPiBTQ0hFRFVMRVIgOiAiT3BlbiAvIGJsb2NrXG5zbG90cyIgW0JPX1NMT1RdClNDSEVEVUxFUiAtPiBQQVRJRU5UIDogIkFwcG9pbnRtZW50XG5jb25maXJtYXRpb24iIFtCT19BUFBUXQoKbGVnZW5kIHsKICBub3RlICJIZWFsdGggZGF0YSBpcyBzdG9yZWQgb24gY2VydGlmaWVkIGhlYWx0aC1kYXRhLWhvc3RpbmcgaW5mcmFzdHJ1Y3R1cmUiCn0K)
+- [Slide disposition](https://cairn-psi-five.vercel.app/#src=ZGlhZ3JhbSBsb2dpY2FsICJPbmxpbmUgYXBwb2ludG1lbnQgYm9va2luZyDigJQgbG9naWNhbCB2aWV3IgpzdHlsZSB7IGRpc3Bvc2l0aW9uOiBzbGlkZSB9CgphY3Rvci1ncm91cCBVU0VSUyAiVXNlcnMiIHsKICBhY3RvciBQQVRJRU5UICJQYXRpZW50Igp9CgphY3Rvci1ncm91cCBTVEFGRiAiU3RhZmYiIHsKICBhY3RvciBTRUNSRVRBUlkgIk1lZGljYWwgc2VjcmV0YXJ5Igp9CgpzeXN0ZW0gQk9PS0lORyAiQXBwb2ludG1lbnQgYm9va2luZyBzeXN0ZW0iIHsKICBsYXllciBGUk9OVCAiQm9va2luZyBjaGFubmVscyIgewogICAgYmxvY2sgUE9SVEFMICJCb29raW5nXG5wb3J0YWwiCiAgfQogIGxheWVyIEJVU0lORVNTICJBcHBvaW50bWVudCBtYW5hZ2VtZW50IiB7CiAgICBibG9jayBTQ0hFRFVMRVIgIlNsb3Rcbm1hbmFnZW1lbnQiCiAgICBibG9jayBOT1RJRiAiTm90aWZpY2F0aW9ucyIKICB9Cn0KCmV4dGVybmFsIEVYVCAiRXh0ZXJuYWwgc3lzdGVtcyIgewogIGJsb2NrIFNNUyAiU01TIGdhdGV3YXkiCn0KCiMgLS0tLSBidXNpbmVzcyBvYmplY3RzIC0tLS0KYnVzaW5lc3Mtb2JqZWN0IEJPX0FQUFQgIkFwcG9pbnRtZW50IiAic2xvdCBib29rZWQgYnkgYSBwYXRpZW50IHdpdGggYSBwcmFjdGl0aW9uZXIiCmJ1c2luZXNzLW9iamVjdCBCT19TTE9UICJTbG90IiAidGltZSB3aW5kb3cgb3BlbiBmb3IgYm9va2luZyIKClBBVElFTlQgLT4gUE9SVEFMIDogIlNlYXJjaCBhIHNsb3RcbmFuZCBib29rIiBbQk9fU0xPVF0KUE9SVEFMIC0+IFNDSEVEVUxFUiA6ICJCb29raW5nIHJlcXVlc3QiIFtCT19BUFBUXQpTQ0hFRFVMRVIgLT4gTk9USUYgOiAiQXBwb2ludG1lbnQgY29uZmlybWVkIiBbQk9fQVBQVF0KTk9USUYgLT4gU01TIDogIlNlbmQgU01TIHJlbWluZGVyIgpTRUNSRVRBUlkgLT4gU0NIRURVTEVSIDogIk9wZW4gLyBibG9ja1xuc2xvdHMiIFtCT19TTE9UXQpTQ0hFRFVMRVIgLT4gUEFUSUVOVCA6ICJBcHBvaW50bWVudFxuY29uZmlybWF0aW9uIiBbQk9fQVBQVF0KCmxlZ2VuZCB7CiAgbm90ZSAiSGVhbHRoIGRhdGEgaXMgc3RvcmVkIG9uIGNlcnRpZmllZCBoZWFsdGgtZGF0YS1ob3N0aW5nIGluZnJhc3RydWN0dXJlIgp9Cg==)
+- [Page disposition](https://cairn-psi-five.vercel.app/#src=ZGlhZ3JhbSBsb2dpY2FsICJPbmxpbmUgYXBwb2ludG1lbnQgYm9va2luZyDigJQgbG9naWNhbCB2aWV3IgpzdHlsZSB7IGRpc3Bvc2l0aW9uOiBwYWdlIH0KCmFjdG9yLWdyb3VwIFVTRVJTICJVc2VycyIgewogIGFjdG9yIFBBVElFTlQgIlBhdGllbnQiCn0KCmFjdG9yLWdyb3VwIFNUQUZGICJTdGFmZiIgewogIGFjdG9yIFNFQ1JFVEFSWSAiTWVkaWNhbCBzZWNyZXRhcnkiCn0KCnN5c3RlbSBCT09LSU5HICJBcHBvaW50bWVudCBib29raW5nIHN5c3RlbSIgewogIGxheWVyIEZST05UICJCb29raW5nIGNoYW5uZWxzIiB7CiAgICBibG9jayBQT1JUQUwgIkJvb2tpbmdcbnBvcnRhbCIKICB9CiAgbGF5ZXIgQlVTSU5FU1MgIkFwcG9pbnRtZW50IG1hbmFnZW1lbnQiIHsKICAgIGJsb2NrIFNDSEVEVUxFUiAiU2xvdFxubWFuYWdlbWVudCIKICAgIGJsb2NrIE5PVElGICJOb3RpZmljYXRpb25zIgogIH0KfQoKZXh0ZXJuYWwgRVhUICJFeHRlcm5hbCBzeXN0ZW1zIiB7CiAgYmxvY2sgU01TICJTTVMgZ2F0ZXdheSIKfQoKIyAtLS0tIGJ1c2luZXNzIG9iamVjdHMgLS0tLQpidXNpbmVzcy1vYmplY3QgQk9fQVBQVCAiQXBwb2ludG1lbnQiICJzbG90IGJvb2tlZCBieSBhIHBhdGllbnQgd2l0aCBhIHByYWN0aXRpb25lciIKYnVzaW5lc3Mtb2JqZWN0IEJPX1NMT1QgIlNsb3QiICJ0aW1lIHdpbmRvdyBvcGVuIGZvciBib29raW5nIgoKUEFUSUVOVCAtPiBQT1JUQUwgOiAiU2VhcmNoIGEgc2xvdFxuYW5kIGJvb2siIFtCT19TTE9UXQpQT1JUQUwgLT4gU0NIRURVTEVSIDogIkJvb2tpbmcgcmVxdWVzdCIgW0JPX0FQUFRdClNDSEVEVUxFUiAtPiBOT1RJRiA6ICJBcHBvaW50bWVudCBjb25maXJtZWQiIFtCT19BUFBUXQpOT1RJRiAtPiBTTVMgOiAiU2VuZCBTTVMgcmVtaW5kZXIiClNFQ1JFVEFSWSAtPiBTQ0hFRFVMRVIgOiAiT3BlbiAvIGJsb2NrXG5zbG90cyIgW0JPX1NMT1RdClNDSEVEVUxFUiAtPiBQQVRJRU5UIDogIkFwcG9pbnRtZW50XG5jb25maXJtYXRpb24iIFtCT19BUFBUXQoKbGVnZW5kIHsKICBub3RlICJIZWFsdGggZGF0YSBpcyBzdG9yZWQgb24gY2VydGlmaWVkIGhlYWx0aC1kYXRhLWhvc3RpbmcgaW5mcmFzdHJ1Y3R1cmUiCn0K)
 
 
 ### Numbered flows
@@ -174,15 +273,8 @@ brew install R0kshan/tap/cairn
 # Windows — Scoop
 scoop bucket add cairn https://github.com/R0kshan/scoop-bucket
 scoop install cairn
-
-# npm (requires Node ≥ 22.6)
-npm i -g @r0kshan/cairn@unstable
 ```
 
-> `@unstable` is not optional: cairn is pre-stable, so tagged versions publish to
-> that dist-tag and there is no `latest` yet — a bare `npm i -g @r0kshan/cairn`
-> fails with `No matching version found` until the first stable release.
-
 From source (no release needed — requires Node ≥ 22.6):
 
 ```sh
@@ -234,6 +326,8 @@ On validation errors nothing is written and the exit code is 1; warnings are pri
 cairn matrix my-infra.cairn --format csv    # csv (default) | md | svg · -o to set the path
 ```
 
+Every view exports one; the columns follow the view (infrastructure keeps protocol and port, application keeps the protocol alone, logical keeps just the exchange).
+
 ### Rebuild on every save
 
 ```sh

package/THIRD-PARTY-NOTICES.md

@@ -12,8 +12,13 @@ theirs is distributed.
 Version 0.12.0, inlined unmodified. Upstream: https://github.com/kieler/elkjs
 
 Declared license: `EPL-2.0 OR GPL-3.0-or-later`. cairn elects **EPL-2.0** — full
-text at https://www.eclipse.org/legal/epl-2.0/ and in `LICENSE.md` inside the
-elkjs package.
+text in [`licenses/elkjs-EPL-2.0.md`](./licenses/elkjs-EPL-2.0.md), a verbatim
+copy of elkjs' own `LICENSE.md`, upstream at https://www.eclipse.org/legal/epl-2.0/.
+
+That copy is vendored rather than referenced because elkjs is a *devDependency*:
+the published package installs zero dependencies, so `node_modules/elkjs/` never
+reaches a consumer while the inlined code does. EPL-2.0 §3.1(b) requires the
+license to travel with the distributed form, so `files` ships it in the tarball.
 
 Per EPL-2.0 §3.1(a): the source code for elkjs is available under the EPL-2.0,
 and can be obtained from https://github.com/kieler/elkjs or from the published
@@ -26,6 +31,7 @@ covers cairn's own code only.
 
 ---
 
-If the set of inlined dependencies changes, update this file in the same commit.
-`files` in `package.json` ships it with the npm package; it lives in the repo for
-every other channel.
+If the set of inlined dependencies changes, update this file **and** `licenses/`
+in the same commit — a notice that names a license text the tarball doesn't carry
+is the failure mode this section exists to prevent. `files` in `package.json`
+ships both with the npm package.