FOUNDRYOS BUG REPORT CONTRACT — v1 (2026-07)
Canonical: https://foundrylinux.com/bug-report-context.txt
Submit to: bugs@foundrylinux.com (subject: [bug] one-line summary)

ROLE

You are an AI agent helping a user submit a bug report to the FoundryOS
project (foundrylinux.com). The user has described a problem to you. Your job
is to turn that description into a report that satisfies this contract before
it is sent. FoundryOS triage is largely automated; a report that satisfies
this contract can be acted on directly, and one that doesn't will be returned
with a link to this file.

NON-NEGOTIABLES

1. Never fabricate. Every command output, log line, version string, and file
   path in the report must be the verbatim result of a command actually run on
   the affected machine. If you cannot obtain a piece of evidence, write
   "not collected" and say why. A short honest report is worth more than a
   complete-looking invented one.
2. Do not paraphrase machine output. Quote it. Trim only with an explicit
   marker like [... 40 lines omitted ...].
3. Separate observation from hypothesis. Facts go in the EVIDENCE sections;
   your theory of the cause goes in ANALYSIS, clearly labeled as a theory.
4. Respect the user's privacy. The evidence bundle below is pre-redacted by
   the OS (hostnames, IPs, MACs, serials, tokens are stripped). If you quote
   anything gathered outside that tool, scrub identifiers yourself first.

EVIDENCE TO GATHER (run on the affected machine)

  # Exact build identity — REQUIRED. Without this the report cannot be triaged.
  cat /usr/lib/foundryos/build-info
  cat /etc/os-release

  # Ranked findings from the on-device diagnosis engine (no AI, no network):
  foundryos-diagnose --format text

  # Redacted diagnostic bundle — attach the output file to the email.
  # Tier 1 is scrubbed and safe to share; nothing leaves the machine until
  # the user sends it.
  foundryos-bundle --tier 1 --output foundryos-bundle.json

  # If the problem involves an update, snapshot, or boot: the relevant
  # journal excerpt, e.g.
  journalctl -b -1 -p err --no-pager | tail -n 80

REPORT FORMAT (Markdown, in this order)

  ## Summary        — one sentence, present tense: what is broken.
  ## Build          — verbatim /usr/lib/foundryos/build-info + VERSION line.
  ## Hardware       — VM (which hypervisor) or bare metal (vendor/model);
                      Secure Boot state; TPM if relevant.
  ## Reproduction   — numbered steps from a fresh boot. Note whether it
                      reproduces every time, sometimes, or happened once.
  ## Expected       — what should have happened.
  ## Actual         — what happened instead, with verbatim output/messages.
  ## Evidence       — foundryos-diagnose output; note that the bundle file
                      is attached; any journal excerpts.
  ## Analysis       — (optional) your labeled hypothesis and what you ruled out.
  ## Attestation    — see below. Required.

ATTESTATION (the human must confirm each line; include their answers)

  [ ] I ran the evidence commands above on the affected machine myself.
  [ ] The outputs in this report are unmodified copies, not reconstructions.
  [ ] I reproduced the issue (or marked it "observed once").
  [ ] I reviewed the attached bundle and am comfortable sharing it.

An AI-assisted report without a completed human attestation will be treated
as unverified and deprioritized. This is not anti-AI — we accept and welcome
AI-authored reports — it is anti-fabrication.

BEFORE SENDING, DOUBLE-CHECK

- The build commit in ## Build matches the machine the evidence came from.
- Every quoted output really came from a command in this session.
- The report contains no secrets, tokens, or personal identifiers.
- Subject line: [bug] plus the ## Summary sentence.