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

# Installing hugs

> Where cliqd finds a hug — the team, CLIQ_HUGS_PATH, the built-ins — and how bundles reach CliqHub.

Hugs

Hugs are found by name, like agents. A hug is installed when its built `dist/` is somewhere cliqd looks.

***

## Where cliqd looks

The first match wins:

1. **The team's own hugs** — any `hugs/<name>/` folder next to `team.yml` whose `dist/` has a `hug.json`. Nothing is
   declared in `team.yml`; the phases' `hug: { name }` say which they use. A sub-team's phases use the sub-team's hugs.
2. **`CLIQ_HUGS_PATH`** — colon-separated folders, each holding hug folders — else the `hugs.path` setting. Hugs on
   the path are used in place, not copied: the place for a hug used by several teams.
3. **`~/.cliqrc/hugs`** — the built-ins `form` and `approval`, installed by cliqd when it starts and replaced on
   upgrade. It is cliqd's folder: don't put your own hugs there.

```bash theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
cliq hug list
```

lists every hug this machine can find: its name, where it comes from (team, path, system) and its hash.

**Hugs are part of the environment, like agents.** Installing a team is refused (`TEAM_HUG_UNKNOWN`) when one of its
phases asks with a hug this daemon can't find — its own hugs count when the team carries them built, and a Hug gate
needs the built-in `approval`. Every run is checked again before it starts (`hug_unknown`), including runs CliqHub
dispatches and each sub-team before its run is set up.

***

## Team hugs

A team hug is ordinary team files: its built `dist/` travels in the team package with `team.yml` and the role briefs.

| Stage | |
| - | - |
| **Build** | `cliq hug build hugs/<name>` |
| **Publish** | `cliq team publish` includes `hugs/<name>/dist/**` — only the bundle; the hug's source stays out. It refuses a hug whose `dist/` is missing or out of date (`--build` builds first), and warns about a phase naming a hug the team doesn't carry |
| **Install** | Every install path — dispatched from CliqHub, `cliq team install`, a local folder — writes `hugs/<name>/dist/` into the installed team |
| **New version** | Replaces the team's hugs; open Hugs keep the bundle they were opened with |

Hug files count towards the team package's limits (10 MB, 1,000 files). The Builder on CliqHub can't build a hug,
but drafts and forks keep a team's hugs.

***

## How bundles reach CliqHub

Nothing is registered or uploaded ahead of time:

1. When a phase asks, cliqd finds the hug and computes its bundle's hash (`sha256` over the files of `dist/`).
2. It opens the Hug on CliqHub with `hug: { name, sha256 }`.
3. If CliqHub hasn't seen that bundle, it answers `BUNDLE_MISSING`, and cliqd opens the Hug again with the bundle's
   files. CliqHub accepts it only from a daemon of the Hug's realm, recomputes the hash and checks the rules.
4. Every later Hug with the same bundle — from any daemon — sends nothing.

The built-ins work the same way: the first `approval` Hug on a CliqHub uploads `approval`'s bundle.

**Retention:** a bundle is kept while an open Hug, or an answered one from the last 90 days, uses it. A past Hug
whose bundle is gone shows its responses as plain key-values.

***

## The page's address

CliqHub serves hug pages from a separate content host — on cliqhub.io, `content.cliqhub.io` — at
`/hb/<sha256>/…`, in a sandboxed frame on the Hug page ([Security](https://docs.getcliq.io/hugs/security.md)). A local cliqd serves
them itself, from the hug's `dist/` on disk.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.