catalog-reuse

Files (2)

• SKILL.md
• restyle-reused-card.md · references/

SKILL.md (first lines)

# Catalog Reuse

Boxel ships a **curated catalog**: apps, cards and fields as definitions you
reference where they live, components, commands, themes, assets, and Listings
packaged for installation — real, tested parts other people finished and
shipped.

**First classify what kind of thing you need. Then apply the reuse operation for
that kind.** Everything below is that one idea, made operational.

## Non-negotiable rules

1. **Never author before searching.** By the time you write the first line of
   any `.gts`, a catalog query must already have returned.
2. **Never treat a Spec as the reusable object.** A Spec is an index entry. You
   reuse what its `ref` names, or an instance from its `linkedExamples` — never
   the Spec itself.
3. **Never conclude a gap after one failed query.** Broaden once (step 5) before
   declaring anything missing.
4. **Never pass over a suitable result without recording why.** Every hit is
   adopted, or refused in writing naming what mismatched. A Listing you answered
   by referencing its parts counts as adopted — say which parts, and move on.
   A second hit that ships an export you already took is refused as a
   duplicate, not taken as well: two hits that ship the same module export are
   one decision.
5. **Never copy what you can reference.** Catalog modules import directly, so a
   definition can be used without taking a copy of it. Install or remix a
   Listing when the user wants their own bundle — and when you do take a copy,
   take it through `install` or `remix`, never by hand.
6. **Prove it at the end.** For everything you authored from scratch, be able to
   name the reuse option above it and why it was unusable. "I didn't look" means
   it needs replacing.

Reading design or pattern references is not a substitute for searching: they
tell you how to build well, not whether to build at all.

## Required workflow

1. **Enumerate** every card, field, component, command, app, theme, and asset
   the brief implies, in plain language. A noun that names an entity — "the
   venue we booked", "the supplier", "the workshop" — is one of those cards:
   enumerate the entity itself and search for it. Spelling it out as the two or
   three attributes you would otherwise type is how a card-sized need gets
   searched for as nothing at all. This holds when the brief reaches the entity
   only through its attributes — "the supplier's payment terms", "the venue's
   capacity" — a possessive names the entity as surely as a bare noun does, and
   what it owns is the card's business, not yours to re-declare.
2. **Search Specs** for each enumerated need, and reference what you find.
   One `matches` term per need. A search for the whole deliverable ("a service
   desk", "a support app") is not a search for its parts and does not replace
   one.
3. **Search Listings only when the user asked to own something**, and be able
   to quote the words that asked — "our own", "a copy we can change",
   "independent of theirs". No such words, no Listing search. That a Listing
   exists and fits is not a reason to install it: nobody asked for a copy.
4. **Search instances** when a need is content-shaped — a particular author,
   theme, config, image, or a sample to start from.
5. **Evaluate** each hit against the need; broaden once before calling anything
   a gap.
6. **Build only confirmed gaps**, and record them. When a catalog definition
   answers the brief, the build is an instance of it, not a design pass.
7. **Self-audit** before finishing.

Step 2 is the default because a catalog definition can be referenced where it
lives. Step 3 hands the user a copy — a separate thing to own, which cannot be
re-attached to the catalog later — so it answers a stated wish for their own
bundle, not a match in the search results.

## Reuse strategy: classify, then operate

**You may import catalog modules directly.** `@cardstack/catalog/` is a
registered import prefix, so a catalog module imports straight into your `.gts`
across realms — you do not have to copy the file in. That is why referencing is
the default and copying is the exception.

Every search here is a search over card instances — `Spec` and `Listing` are
ordinary card types, and so is `Author`. What differs is what a hit **denotes**.

| You need | Anchor on | A hit denotes | Operation |
|---|---|---|---|
| parts to build with | `Spec` | a module export, named by `ref` | link · contain · extend · import |
| content that exists | the card type itself | the instance | point a `linksTo` / `linksToMany` at it · or copy and edit |
| a bundle of their own | `Listing` | an installable bundle | `install` to hand it over as-is · `remix` when they will diverge from it |

Nothing exports a Listing, so no CodeRef names one: **a Spec query can never
return a Listing, and a Listing query can never return a bare definition.**
Different anchors, because they describe different kinds of thing.

**A Listing that fits is not a Listing you have to take.** What it bundles are
Specs, and referencing those answers the same need without handing over a copy —
the parts arrive wired to the catalog instead of forked from it. Choosing the
parts over the bundle is not passing over a suitable result; it is taking the
same result by the binding that keeps working.

### Parts: what each `specType` entitles you to

Take the target from the hit's `ref` (module + name) and wire **that**.

| `specType` | The export is | How you wire it |
|---|---|---|
| `card` | a **CardDef** | `linksTo` / `linksToMany` as a field · `extends` to specialize · `adoptsFrom` in an instance |
| `field` | a **FieldDef** | `contains` / `containsMany` · `extends` to specialize |
| `component` | a Glimmer component | import into your template's markup |
| `command` | a Command | import and invoke, or run through your session's command mechanism |
| `app` | an **AppCard** (the app's root CardDef) | import or `extends` it through `@cardstack/catalog/…` and link its `linkedExamples` instance; the cards it composes are `card` Specs of their own |
| `file` | an asset | an **instance** → use the instance anchor |

**How you declare the wiring is `boxel`'s call, not this skill's.** Its
Cardinal Rules own CardDef-vs-FieldDef and `contains` vs `linksTo`. Here you
decide *which* catalog unit answers the need; go there for how to write it.

`specType` crosses these rows — five values name module exports, `file` is an
instance.

Within parts, prefer more whole over less: a card over a field, a field over
hand-rolled markup. This is not a queue — a need that *is* a field starts at the
field. What it forbids is hand-building a part when a bigger unit contains it.

### Content: two different instance searches

From cardstack/boxel-skills, MIT.

More from cardstack/boxel-skills