62c5454f00
The wiki had no entry point worth the name. Its Home page was hardcoded inside the generator, had drifted into recommending INSTALL-WINDOWS-IIS - the manual procedure these same docs tell you not to follow for a new site, because it produces a server the installer then refuses to upgrade - and the page carrying that warning, llms.txt, was never published at all, because the generator copied only .md files. The adoption guide had zero inbound links. START-HERE routes by what a reader came to do: stand up a site, deploy the shop-floor tools, write a plugin, integrate with the API, understand a decision, or fix something. It is the shortest correct path per role, not an index - the sidebar is already the index. FLEET-ARCHITECTURE is the page nothing else could assume. The server, GE-Enforce, the asset reporter, the backup collectors and EventSaver were each documented alone, each assuming a reader who already knew the other four. It draws the shape, states the rule that explains most of the behaviour - nothing on the server reaches out to a PC, the fleet asks - and ends with the table that says which of the five programs to open for a given symptom, since knowing that is most of the diagnosis. wikigen renders START-HERE as the landing page rather than a list maintained in a second place, and publishes llms.txt as LLM-GUIDE.
65 lines
2.8 KiB
Markdown
65 lines
2.8 KiB
Markdown
# 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).
|