90c3c3102b
Guides was shipped without an entry in PLUGINS.md or START-HERE, so a site adopting the product had no way to find out it exists. BACKUP-KINDS.md described a host's badge as coming from the most recently confirmed kind. It has not worked that way since the fleet report was reworked: the freshest revision per (host, kind) is taken, and then the STALEST of those kinds decides, because reporting the freshest would let a healthy NTLARS backup mask a part-marker capture that stopped a month ago. Stalest among kinds that can be JUDGED - a kind never confirmed is unmeasurable, not stale, and treating it as the worst value made a host with a working backup show no badge at all. The backups row also still advertised UDC and CMM kinds that do not exist. api-inventory, openapi.json and PROJECT-MAP regenerated.
3.9 KiB
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
- INSTALL-WINDOWS - one offline installer, start to finish.
- OPERATE-WINDOWS - restart, logs, backups, upgrades.
- CSV-IMPORT if the site's data is in spreadsheets, or IMPORT-API if there is a source database to script against.
- FLOOR-MAP - load the site's floor plans and place markers. Also the page to read BEFORE a plan changes: it covers moving every marker onto a redrawn plan without doing it one at a time.
Do not follow INSTALL-WINDOWS-IIS for a new site. That is the manual procedure, kept for hand-built servers that predate the installer, and following it produces a server the installer then refuses to upgrade.
I am deploying the shop-floor tools
Read FLEET-ARCHITECTURE first - it is one page and it is what makes the rest make sense.
Then ADOPTING-AT-ANOTHER-SITE, which has worked examples for Intune, GE-Enforce and manual installation, and says where each artifact comes from.
I am writing a procedure for other people to follow
Guides live in ShopDB itself: GUIDES.md. Typed blocks rather than markup, pasted screenshots, checkboxes a technician can tick as they work, and a draft/publish split so a procedure cannot change under somebody halfway through it. Use it instead of leaving a Word document on a share.
I am writing a plugin
- PLUGIN-QUICKSTART - scaffold and first run.
- PLUGIN-HOOKS - the contract. Authoritative.
- PLUGIN-LAB-PRINTEDPARTS - a real plugin built end to end, to type along with.
- PLUGIN-EXTERNAL-REPO if it lives in its own repository, and CONTRACT-STABILITY before you choose a version pin.
I am integrating with the API
- LLM-GUIDE (
docs/llms.txtin 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. GET /api/docson any running instance - the full spec, browsable.- API-REFERENCE for prose, COLLECTOR-INTEGRATION if you are feeding data in from a PC.
I have to give somebody a password
SECURE-SEND - a one-view expiring link, instead of a chat message or a sticky note. Read the "Before anybody relies on it" section first: there is one thing to test at your site before the first real credential goes through it.
I am trying to understand why something is built this way
The ADRs. 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 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, then
shopdb-admin.ps1 check -Json. - A PC or a bay: the symptom table at the end of FLEET-ARCHITECTURE says which piece to open first.
- A deploy that half-worked: UPGRADE and BACKUP-RESTORE.
I am moving a site to a different server or stack
MIGRATE-TOPOLOGY - Windows/IIS to Docker, Docker to a new host, and back. The data moves cleanly; the URL the fleet points at is the work.