Add a machine to this environment

Use this checklist to add a machine you are authorized to document. Follow CONTRIBUTING.md for the shared review and validation steps. A copyable handoff is available.

1 Identify the machine

Start with existing operating notes and read-only discovery. Confirm hostname, SSH path, owner and roles. Choose a stable inventory ID such as host-workshop; do not rename it when the hostname or role changes.

Reuse roles in standards/vocabulary.json. Register a new role only when needed, with the short decision page required by the contribution checklist.

2 Record useful facts

Collect access prerequisites, operating system, services and supervision, ports, data locations, reboot behavior, workflows and common failures. Record credential owners and paths, never credential values. Put pointers to notes or scripts kept elsewhere in the source map.

Copy standards/templates/host.json into inventory/hosts/. Add service and resource records only where ownership or recovery needs them. Add a host page and sanitized evidence. Mark untested behavior explicitly.

Use management: observed unless this repository manages the component; external describes software managed elsewhere. page points to the main Markdown instructions. In this repository, model identifiers use letters/underscores (for example workshop) and dots for children (workshop.simulator); inventory IDs use hyphens (service-workshop-simulator). Keep architecture_ref and model inventoryId consistent.

Name roles in the page prose so search can find them. For factual tables, use an inventory-table block as shown on an existing host page, then run npm run generate.

3 Extend the map

Add elements and known relationships in architecture/, reusing declared kinds. Add the host to the index view and update its description. Keep that view at machine level; put service details in a separate view. A terminal SSH connection can be shown as mac -[connects]-> workshop.

Document only observed or clearly labelled reported connections. Do not infer a build-to-device deployment path or camera consumer from proximity. The build derives documentation links and JSON/text views from this model and inventory; do not hand-edit generated exports.

4 Explain operation and recovery

Include normal access, the usual task, and at least one useful recovery recipe. State the target, prerequisites, checks, data effects, verification and escalation. Use the existing templates. Import only reusable, non-secret scripts that belong in this repository; application code stays in its application repository.

5 Check the result

Run the contribution checklist. Open the host page, a workflow and the changed diagram; check search finds the hostname and roles. Report missing guidance as part of the contribution.

The diagnostic script currently covers Mac and Shipyard only. Adding checks for another machine is a separate change; documentation does not require a new diagnostic implementation.