From 9888e89fa32419de1de551b4b0e4a97b0b6b6d48 Mon Sep 17 00:00:00 2001 From: Pieter Viljoen Date: Thu, 1 Oct 2026 16:12:42 -0700 Subject: [PATCH] State the Install-Tools JSON Report in the Host Contract add-host-tool's procedure has a report-behavior change update docs/host-setup.md beside the platform READMEs, and #2259 updated only the READMEs. The contract now names both flags, that they apply only to the report action, the shared top-level shape, and that a change to a field's meaning raises schema, and it routes to the Linux README for the shared fields and the Windows README for its one addition rather than restating them. Copilot raised it on promotion #2254. Co-Authored-By: Claude Opus 5.5 --- docs/host-setup.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/host-setup.md b/docs/host-setup.md index f8ccdbce..7a8ff7d8 100644 --- a/docs/host-setup.md +++ b/docs/host-setup.md @@ -76,6 +76,8 @@ host-setup\windows\install-tools.ps1 -Install -Repo C:\path\to\repository The report, list, dry-run, install, and upgrade actions accept the same repository option. A platform with no matching metadata reports no constrained installer for that tool. The Linux reader needs `jq`, which the fleet tools provide. Install the fleet tools first when a minimal host does not carry it. +**A report can be written for a program to read.** Both installers take a JSON flag beside their report action, `--report --json` on Linux and `-Report -Json` on Windows, and the flag applies to no other action. Each writes one object carrying a `schema` number, the `platform`, a `tools` list with one entry per tool, and a top-level `notes` list for what belongs to no tool. A change to what a field means raises `schema`, so a reader checks it before trusting any field. The [Linux README][host-setup-linux-readme] defines the fields every platform shares, and the [Windows README][host-setup-windows-readme] names the one field it adds and the values it reports differently. + ## Git Identity Configure your name and email, used for commit authorship. **The email is the committing account's GitHub `noreply` address, never a private, personal, or invented one**, per [GOVERNANCE.md "Git and Commit Rules"][governance-git-and-commit-rules], which owns the rule and states the fleet's value. A private address trips GitHub's email-privacy push protection (GH007), and an invented one pollutes history. @@ -374,7 +376,9 @@ A host that fails any row is not ready for the procedure that row names, and the [governance-git-and-commit-rules]: ../GOVERNANCE.md#git-and-commit-rules [host-gate]: ../scripts/host_gate.py [host-setup-dir]: ../host-setup/ +[host-setup-linux-readme]: ../host-setup/linux/README.md [host-setup-windows]: ../host-setup/windows/ +[host-setup-windows-readme]: ../host-setup/windows/README.md [host-tools]: ../spec/host-tools.json [install-tools-windows]: ../host-setup/windows/install-tools.ps1 [issue-483]: https://github.com/ptr727/ProjectTemplate/issues/483