# Documentation

`@econ-v1/node-design-seam` lets a designer's drop — a hash-pinned folder of
`stage.html` / `stage.css` / view modules — receive live data through a write
vocabulary too narrow to carry a restyle.

These pages ship inside the published tarball, so they are readable from
`node_modules/@econ-v1/node-design-seam/docs/` as well as from the repository.

## Start here

| If you are… | Read |
| --- | --- |
| adopting the package for the first time | [Getting started](getting-started.md) |
| wondering how design and integration work at the same time | [Working in parallel](workflow.md) |
| trying to understand *why* the vocabulary is this small | [Concepts](concepts.md) |
| deciding how to express a value in a drop | [Write vocabulary](write-vocabulary.md) |
| staring at a `verify` failure | [Troubleshooting](troubleshooting.md) |
| upgrading from an older version | [CHANGELOG](../CHANGELOG.md), then [Troubleshooting](troubleshooting.md#after-a-package-upgrade) |

## Reference

- **[Getting started](getting-started.md)** — install, adopt a drop, wire a stage
  entry, gate CI. The whole loop, end to end.
- **[Working in parallel](workflow.md)** — how a designer previews with no stack and
  a developer wires with no data, the two hand-offs between them, and the two places
  the tooling is still thin.
- **[Concepts](concepts.md)** — drops, slots, the seam, why the applier is
  deliberately the least capable module in the codebase, and the two hash layers.
- **[Write vocabulary](write-vocabulary.md)** — the three forms, the seven
  allowlisted attributes, several attribute writes on one element, what the
  vocabulary cannot reach, and theme.
- **[Configuration](configuration.md)** — every key of
  `node-design-seam.config.json`, its default, and what rejects it.
- **[CLI](cli.md)** — `pin`, `bindings`, `verify`, `adopt`: flags, output, exit codes.
- **[Runtime API](api.md)** — `mountDropFragment`, `createSeam`, `wireStage`,
  `applyBindings`, `ALLOWED_ATTRIBUTES`, and the `Binding` type.
- **[Troubleshooting](troubleshooting.md)** — a decoder for every `verify` failure
  prefix, what to do after a package upgrade, and the mistakes that look reasonable.

## The role-specific guides

Most of the contract is not enforced by types — it is enforced by three documents,
each written for one side of the seam. All of them ship in the package:

- **`skills/drop-authoring/SKILL.md`** — the agent skill for the **designer**.
  Whether a request is a drop change at all, the authoring sequence, the five
  fixture states, visual verification, and the hand-off.
- **`skill/SKILL.md`** — the agent skill for the **integrator**. The runbook, the
  hard rules, the failure table, and the sanctioned alternative for every "I need a
  verb you don't have".
- **`templates/AGENTS.stage-drop.md`** — the drop contract itself, and not a skill.
  Copy it into a new drop's root as `AGENTS.md` and fill in the slot inventory; it
  carries the `contract:` line the CLI version-gates against.

A repo that both authors and integrates drops installs **both** skills. Their
descriptions are what route an agent to the right one, which matters because the
integrator's "never edit a file under the drop root" reads as a prohibition on
exactly what the author's job is.

The two skills are halves of one contract. When one gains a rule, the other usually
needs the mirror — see [CONTRIBUTING](../CONTRIBUTING.md).