<!-- docmeta
purpose: reference
audience: operator, adopter, developer, integrator
status: current
summary: Every task these docs answer, the smallest page set that answers it, and what that costs to read.
loadwith: none
-->

# Documentation index

Find the row that matches what you are about to do, read the pages in the
"Read" column, and skip everything else. That is the whole intent: these docs
are larger than any one person or agent can hold, so the only useful thing an
index can do is tell you which few pages you actually need.

**Lines** is the total size of that row's page set. It is there so you can see
the cost before you pay it. A one-page row is one page on purpose.

**Derived, not authored.** Every row comes from the `docmeta` block at the top
of the page it names - its `purpose`, `status` and `summary` - and the page
itself is the source of truth. So do not improve a row here: fix the `docmeta`
on the page and bring the row into line with it. `tests/test_docs_index.py`
fails when this file and the pages disagree, when a current page is reachable
from no task row, when a row misstates what it costs to read, and when a link
here or in START-HERE points at a file that is not there.

New to the project and not sure which row is yours: [START-HERE](START-HERE.md)
is shorter and picks for you. An agent should read [llms.txt](llms.txt) first.

## Tasks

### Run a site

Docker is the topology this product line ships, and the only one. There is no
Windows installer here and no IIS procedure to follow.

| Task | Read | Lines |
|---|---|---|
| Stand up a new site on Docker at a connected facility | [DEPLOY](DEPLOY.md) | 500 |
| Stand up a site with no internet at all | [DEPLOY-AIRGAP](DEPLOY-AIRGAP.md) | 180 |
| Build the image where npm cannot reach the registry | [DOCKER-PREBUILT-APPROACH](deployment/DOCKER-PREBUILT-APPROACH.md) | 87 |
| Try the product on a Windows box without building it | [DEV-BUILD-TEST](DEV-BUILD-TEST.md) | 56 |
| Upgrade a Docker or venv site to a newer version | [UPGRADE](UPGRADE.md) | 150 |
| Back up a site, or restore one | [BACKUP-RESTORE](BACKUP-RESTORE.md) | 202 |
| Find a setting, an environment variable or its default | [CONFIG](CONFIG.md) | 356 |
| Decide which plugins this site should carry | [PLUGINS](PLUGINS.md) | 134 |
| Answer whether this site is exposed to a published advisory | [DEPENDENCY-SECURITY](DEPENDENCY-SECURITY.md) | 108 |
| Hand somebody a password without leaving it in a chat | [SECURE-SEND](SECURE-SEND.md) | 157 |

### Fill a site with data

| Task | Read | Lines |
|---|---|---|
| Load starting data from spreadsheets, with no developer | [CSV-IMPORT](CSV-IMPORT.md) | 139 |
| Load starting data from a source database | [IMPORT-API](IMPORT-API.md) + [IMPORT-ADOPTION](IMPORT-ADOPTION.md) | 379 |
| Look up the import wire contract only | [IMPORT-API](IMPORT-API.md) | 283 |
| Load the floor plans, or move every marker onto a redrawn plan | [FLOOR-MAP](FLOOR-MAP.md) | 137 |
| Write a procedure technicians will follow on the floor | [GUIDES](GUIDES.md) | 237 |
| File several devices that share one asset number | [ASSET-COMPOSITION](ASSET-COMPOSITION.md) | 158 |

### Shop-floor PCs

| Task | Read | Lines |
|---|---|---|
| Understand what runs on a bay and which page to open next | [FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) | 144 |
| Understand what the collector is before choosing a page | [COLLECTOR-INTEGRATION](COLLECTOR-INTEGRATION.md) | 85 |
| Get the shipped reporters running on a fleet, and prove it | [COLLECTOR-CLIENT-SETUP](COLLECTOR-CLIENT-SETUP.md) + [COLLECTOR-AUTH](COLLECTOR-AUTH.md) | 439 |
| Write a client that posts to the collector API | [COLLECTOR-PAYLOADS](COLLECTOR-PAYLOADS.md) + [COLLECTOR-AUTH](COLLECTOR-AUTH.md) | 691 |
| Decide how a PC authenticates - per-PC credential or shared key | [COLLECTOR-AUTH](COLLECTOR-AUTH.md) | 292 |
| Fix a bay showing the wrong slides | [EVENTSAVER](EVENTSAVER.md) | 144 |
| Install printers from ShopDB, or read the installer endpoints | [PRINTER-INSTALLER](PRINTER-INSTALLER.md) | 140 |
| Point the shop-floor tools at a different site's ShopDB | [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md) | 290 |
| Explain why a host's backup is listed as stopped | [BACKUP-STALENESS](BACKUP-STALENESS.md) | 104 |

### Build on the platform

| Task | Read | Lines |
|---|---|---|
| Write and install a first plugin | [PLUGIN-QUICKSTART](PLUGIN-QUICKSTART.md) + [PLUGIN-HOOKS](PLUGIN-HOOKS.md) | 1059 |
| Look up one hook, manifest field or shopdb.api import | [PLUGIN-HOOKS](PLUGIN-HOOKS.md) | 866 |
| Check a plugin against the conventions, and the traps that have bitten people | [PLUGIN-GUIDE](PLUGIN-GUIDE.md) + [PLUGIN-HOOKS](PLUGIN-HOOKS.md) | 1060 |
| Ship a plugin from its own git repository | [PLUGIN-EXTERNAL-REPO](PLUGIN-EXTERNAL-REPO.md) + [PLUGIN-HOOKS](PLUGIN-HOOKS.md) | 1152 |
| Choose how tightly to pin a sister site to the contract | [CONTRACT-STABILITY](CONTRACT-STABILITY.md) | 149 |
| Sign a plugin artifact, or make a site verify signatures | [PLUGIN-SIGNING](PLUGIN-SIGNING.md) | 149 |
| Add a backup kind to the backups plugin | [BACKUP-KINDS](BACKUP-KINDS.md) | 52 |
| Set up a dev environment and contribute a change back | [DEVELOPMENT-SETUP](DEVELOPMENT-SETUP.md) | 390 |
| Call the API: where the generated spec is, which surface owns what, how auth works | [API-REFERENCE](API-REFERENCE.md) | 89 |
| Look up current versions, plugin list or Alembic heads | [PROJECT-MAP](PROJECT-MAP.md) | 94 |
| Find out what has shipped, and what is left before 1.0 | [ROADMAP](ROADMAP.md) | 210 |
| Find which architectural decision governs a question | [adr/README](adr/README.md) | 69 |
| Find the design record behind a shipped feature | [proposals/README](proposals/README.md) | 27 |

**There is no build-along lab on this line.** The five-part tutorial was written
around a plugin this product does not carry, and a tutorial that walks a reader
through a directory they do not have is worse than none. Learn the contract from
PLUGIN-QUICKSTART and PLUGIN-HOOKS, scaffold with `flask plugin scaffold`, and
read `plugins/warranty/` - the smallest bundled plugin that owns tables,
permissions, an asset panel and a dashboard card.

Looking for one endpoint? Do not look in a page. The generated spec is served
at `GET /api/docs` on any running instance and tracked as `docs/openapi.json`;
[llms.txt](llms.txt) is the short version - auth, the response envelope, and
the recipes people get wrong. The API-REFERENCE row above is the pointer to
both, plus the surface and auth orientation a spec cannot give.

### Decisions

One ADR answers one question. Read the one row that matches and stop -
nothing here is a prerequisite for anything else. [adr/README](adr/README.md)
is the authoritative ADR index and the only place that records whether a
decision still holds; the lines below are the pages' own summaries, for
routing.

| Question it settles | Read | Lines |
|---|---|---|
| Why Asset, not the legacy Machine model, is the surface plugin authors may depend on | [ADR-001](adr/ADR-001-asset-as-platform-contract.md) | 200 |
| How the plugin contract is versioned and what core_version a plugin must declare | [ADR-002](adr/ADR-002-plugin-versioning.md) | 68 |
| How a plugin reaches a site: bundled in-tree, or dropped into plugins/ from its own repo | [ADR-003](adr/ADR-003-plugin-distribution.md) | 76 |
| Why every site runs its own instance instead of one multi-tenant deployment | [ADR-004](adr/ADR-004-deployment-topology.md) | 100 |
| How a plugin declares a collector schema so the framework wires the ingest endpoint and auth | [ADR-006](adr/ADR-006-collector-contract.md) | 156 |
| How the product is versioned and released, separately from the plugin contract | [ADR-007](adr/ADR-007-product-versioning-and-releases.md) | 123 |
| Why each plugin owns its own Alembic chain instead of adding tables to the core chain | [ADR-008](adr/ADR-008-plugin-migration-ownership.md) | 131 |
| Why the SPA gates plugin routes, so a disabled plugin URL redirects instead of breaking | [ADR-009](adr/ADR-009-frontend-plugin-gating.md) | 156 |
| The hook contract a plugin uses to contribute UI without hand-editing core Vue files | [ADR-010](adr/ADR-010-frontend-plugin-hooks.md) | 326 |
| Why the equipment domain was renamed to machines and machinetypes became modeltypes | [ADR-011](adr/ADR-011-machines-rename.md) | 75 |
| How a site gets only the plugins it chose, and why curation plus signing is the security model | [ADR-013](adr/ADR-013-plugin-catalog-and-lean-builds.md) | 435 |
| Why a lean site stops creating database tables for plugins it never installed | [ADR-014](adr/ADR-014-schema-lean-per-site.md) | 150 |
| Where a site's own hostnames, paths and defaults are allowed to live, and where they are not | [ADR-015](adr/ADR-015-site-specific-configuration.md) | 156 |
| Why the floor map became buildings and levels instead of one image with stacked floors | [ADR-017](adr/ADR-017-buildings-and-levels.md) | 151 |
| Why metrology instruments are machines, so this product has no measuring-tool asset class | [ADR-018](adr/ADR-018-metrology-instruments-are-machines.md) | 132 |
| Why every endpoint gets its own enrolled secret instead of one fleet-wide shared key | [ADR-019](adr/ADR-019-per-pc-endpoint-credentials.md) | 217 |
| Why enabling a plugin no longer needs a manual restart, and where it still does | [ADR-020](adr/ADR-020-worker-self-recycle-on-plugin-change.md) | 95 |

## Archive - do not follow these

Nothing below is current guidance and nothing above depends on it. A **legacy**
page is still true but superseded: do not start new work from it. A
**historical** page is a finished migration, a design proposal, or a decision
about something this product line no longer carries, kept only as the record of
why something looks the way it does.

They are listed so you can recognise one if you land on it, and so nobody has
to read one to find out it does not apply. Together they are 1,799 lines that
almost nobody needs.

| Page | Status | What it is | Lines |
|---|---|---|---|
| [IMPORT-LEGACY-ASP](IMPORT-LEGACY-ASP.md) | historical | Record of one classic-ASP shopdb migration: the fan-out routing, the judgement calls and what was left behind. | 163 |
| [ADR-005](adr/ADR-005-equipment-vs-measuringtools.md) | historical | The split of machinery from metrology tools into two plugins. Superseded by ADR-018. | 163 |
| [ADR-012](adr/ADR-012-geenforce-manifest-ownership.md) | historical | Why ShopDB owned GE-Enforce manifests as data. That plugin is not bundled here; ADR-013 and the API-token resource scopes trace back to this decision. | 137 |
| [ADR-016](adr/ADR-016-credential-delivery.md) | historical | The plan for ShopDB-resolved credential targeting. Never built; superseded by ADR-019. | 204 |
| [deployment/PRODUCTION-READINESS](deployment/PRODUCTION-READINESS.md) | historical | The 2026-09-07 assessment of why deployment was hard. Its gap list became the distributed-release item on the roadmap; its recommendation of Windows/IIS was reversed. | 372 |
| [proposals/dashboard-live-fleet](proposals/dashboard-live-fleet.md) | historical | The case for a worst-first dashboard queue. Built; kept as the record of why. | 179 |
| [proposals/device-identity](proposals/device-identity.md) | historical | One durable identity for the device a PC drives. Phase 1 is built; phases 2 and 3 are not started. | 235 |
| [proposals/printer-assignment](proposals/printer-assignment.md) | historical | The design making printers a property of the machine. Shipped, and the shipped behaviour is in PRINTER-INSTALLER. | 346 |

## What the docmeta fields mean

Every page in `docs/` opens with an HTML comment like this one, and this index
is built from those blocks:

```
<!-- docmeta
purpose: howto
audience: operator
status: current
summary: One sentence saying what question this page answers.
loadwith: PAGE-A.md
-->
```

- **purpose** - `tutorial` teaches by doing, `howto` is followed under
  pressure, `reference` is looked something up in, `explanation` says why.
- **audience** - `operator`, `adopter`, `developer`, `integrator`.
- **status** - `current`, `legacy` (true but superseded), `historical` (a
  record, not guidance).
- **summary** - what this index shows instead of the page.
- **loadwith** - the pages that page is not complete without. Usually `none`.
  Where a row above lists two pages, that is where the second one came from.