# Start here

ShopDB is a per-site asset platform: one instance per plant, plugins for what
each site tracks. These pages document the server, the plugin contract, and the
tools that run on shop-floor PCs.

Find yourself below. Each row is the shortest correct path, not everything that
exists.

## I am standing up ShopDB at a new site

1. [INSTALL-WINDOWS](INSTALL-WINDOWS.md) - one offline installer, start to finish.
2. [OPERATE-WINDOWS](OPERATE-WINDOWS.md) - restart, logs, backups, upgrades.
3. [CSV-IMPORT](CSV-IMPORT.md) if the site's data is in spreadsheets, or
   [IMPORT-API](IMPORT-API.md) if there is a source database to script against.

**Do not** follow INSTALL-WINDOWS-IIS or DEPLOY-WINDOWS-IIS for a new site.
Those are the manual procedure, kept for hand-built servers that predate the
installer, and following them produces a server the installer then refuses to
upgrade.

## I am deploying the shop-floor tools

Read [FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) first - it is one page and it
is what makes the rest make sense.

Then [ADOPTING-AT-ANOTHER-SITE](ADOPTING-AT-ANOTHER-SITE.md), which has worked
examples for Intune, GE-Enforce and manual installation, and says where each
artifact comes from.

## I am writing a plugin

1. [PLUGIN-QUICKSTART](PLUGIN-QUICKSTART.md) - scaffold and first run.
2. [PLUGIN-HOOKS](PLUGIN-HOOKS.md) - the contract. Authoritative.
3. [PLUGIN-LAB-PRINTEDPARTS](PLUGIN-LAB-PRINTEDPARTS.md) - a real plugin built
   end to end, to type along with.
4. [PLUGIN-EXTERNAL-REPO](PLUGIN-EXTERNAL-REPO.md) if it lives in its own
   repository, and [CONTRACT-STABILITY](CONTRACT-STABILITY.md) before you choose
   a version pin.

## I am integrating with the API

1. [LLM-GUIDE](LLM-GUIDE.md) (`docs/llms.txt` in the repo, also served at
   `/api/docs/llms.txt`) - auth, the response envelope, common recipes.
   Short, and the envelope section is the part people get wrong.
2. `GET /api/docs` on any running instance - the full spec, browsable.
3. [API-REFERENCE](API-REFERENCE.md) for prose, [COLLECTOR-INTEGRATION](COLLECTOR-INTEGRATION.md)
   if you are feeding data in from a PC.

## I am trying to understand why something is built this way

[The ADRs](ADR-001-asset-as-platform-contract.md). They are the decision record,
they say what was rejected and why, and they are the fastest way to avoid
relitigating a settled question. [PROJECT-MAP](PROJECT-MAP.md) lists them all
with their status, along with the current versions and every migration head -
it is generated, so it is never stale.

## Something is broken

- Server: [OPERATE-WINDOWS](OPERATE-WINDOWS.md), then `shopdb-admin.ps1 check -Json`.
- A PC or a bay: the symptom table at the end of
  [FLEET-ARCHITECTURE](FLEET-ARCHITECTURE.md) says which piece to open first.
- A deploy that half-worked: [UPGRADE](UPGRADE.md) and
  [BACKUP-RESTORE](BACKUP-RESTORE.md).