Skip to content

docs: regenerate INSTALLATION.md from the passing native installer run #451

Description

@castrojo

Parent

#448

What to build

Consume the testsuite native Server suite at an explicit reviewed full commit SHA using Server's existing QEMU harness. The complete passing invocation supplies authored executed steps, actual screenshots and results that deterministically render root INSTALLATION.md plus docs/installation/*.png. Run on the existing nightly schedule and manual/relevant-change paths; propose guide/images together in one PR. Reuse existing image/update artifacts, renderer-friendly stdlib conventions, propose-pr.sh and mergeraptor authentication. No duplicate image build solely for documentation or desktop e2e.yml redesign.

Server currently does not check out testsuite. Add a separate checkout in an ignored working directory, with a literal full SHA containing the merged new suite, the existing SHA-pinned checkout action and persist-credentials: false. Keep Server's harness/source matched to the image commit. Testsuite lands first and Server adopts its SHA through review. A pin change must execute the consumer check, not merely pass docs checks or skip the build. Record image version/digests, Server/testsuite commits, firmware checksum, QEMU version, fixture differences and run URL. Do not float main and merely report what was fetched.

Generation and publication contract

  • Ordered checkpoint IDs pair verified human-authored instructions with actual screenshots from the same run. No runtime LLM output, simulated terminal renderings, OCR or independent duplicate walkthrough. Use ordinary prose and numbered instructions, no emojis/decorative formatting/raw test syntax.
  • Image files live under docs/installation/; root guide .md and that directory follow the existing docs-only classifier. Screenshots elsewhere would request an image build. Explicitly extend existing docs-checks to validate the new root guide and image links. Update only matching usb-installer.md, linking to the generated canonical walkthrough rather than duplicating it.
  • Require complete JSON, every required inventory case present and passed, every required checkpoint image present, and matching immutable provenance. Reuse result parsing, not generic is_success which accepts skips. Failures/skips/cancellation/truncation/missing images block docs publication. Preserve last-known-good docs and visibly report refresh failure or 'verified, publication pending'.
  • Test jobs remain read-only. A main-only publication job mints mergeraptor App credentials after untrusted execution and reuses existing PR helper; no PAT or new third-party PR action, no direct commit to main. Any new environment/secret access or expanded permissions needs a separate human approval gate.
  • No timestamp-only daily churn; execution timing belongs in run artifacts. Meaningful image/version/UI changes remain honest guide changes. An unchanged bundle leaves the existing PR/checks alone.
  • If installer source moves before publication, do not label an old bundle current for that newer installer. Rerun/reject and retain truthful tested-version provenance.

Release policy boundary

Existing release gates stay unchanged. Making the expanded matrix or merged documentation a new release blocker is not approved. If maintainers want that stronger policy, decide it separately after firmware/diskless feasibility is established. This issue's scheduled documentation publication fails closed; it reports documentation lag instead of silently blocking releases or claiming atomic zero drift.

Acceptance criteria

  • One passing native testsuite invocation supplies all generated steps/PNG checkpoints and complete results; Server renders and proposes them end to end.
  • Server fetches a literal reviewed testsuite SHA and validates source/image/firmware provenance, including declared manual-enrollment copies.
  • Existing nightly artifacts/schedule are reused; manual and relevant installer/test-pin changes exercise the same consumer.
  • Native failure, a skipped/missing required case, missing image, truncated JSON and cancelled run demonstrably prevent publication and expose failure/staleness.
  • Guide and images use the chosen root/docs paths; docs checks cover them; plain generated Markdown is reviewed and valid.
  • Existing mergeraptor/propose-pr conventions publish one coherent main-targeted PR without changing release policy or executing PR-controlled code with write credentials.
  • Full relevant test modules and Server just validate, just test-unit, docs checks and workflow lint pass; all affected consumers and the matching skill are updated.

Blocked by

Existing evidence

Hosted native console run passed in 76s within a 28m41s boot-test job/90m timeout; previous nightly console passed in 82s. Those establish existing hosted KVM/console behavior, not expanded-matrix timing or screenshot repeatability. Local full four-boot native console scenario passed in 75.15s, exit 0, and an actual confirmation PNG was inspected.

Activity

  1. added theissue type on Oct 11, 2026
  2. mrbobbytables commented on Oct 11, 2026

    @mrbobbytables
    Contributor

    Before automated tools can generate INSTALLATION.md and capture screenshots from real installer runs, the underlying test suite and console test harness must be built and merged. Currently, this task is blocked by external dependencies across the project:

    1. Testsuite native coverage and evidence emitter (projectbluefin/testsuite#975): The dedicated Behave test suite and screenshot generator have not yet landed in projectbluefin/testsuite. Server cannot pin to a merged testsuite commit SHA until that suite exists.
    2. Native console driver feasibility and interface (projectbluefin/server#450): Defining the console-driver interface and firmware test matrices is still awaiting maintainer decisions on foreign firmware testing and diskless console authentication.
    3. Offline USB wait-online fix (projectbluefin/server#449): PR fix(installer): stop userspace wait-online on offline USB installer boots #452 is currently open to prevent wait-online timeouts during offline USB installer runs, which are needed for stable screenshot captures.

    Once the prerequisite issues in projectbluefin/testsuite and projectbluefin/server land, this issue can pin the resulting testsuite commit SHA and wire the automated documentation generator.

    — hive: backend=copilot model=gemini-3.8-flash


    🐝 Hive Agent: contributor | SHA: unknown

  3. added
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    on Oct 11, 2026
  4. removed
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    on Oct 21, 2026
  5. hivecommons-hive commented on Oct 21, 2026

    @hivecommons-hive
    Contributor

    Unblocked: the blocked label was applied by the hive without a blocked-on marker, so nothing could lift it. This issue is actionable again.

  6. Danathar commented on Oct 27, 2026

    @Danathar
    Contributor

    Accepting: the concrete child of #448. Render INSTALLATION.md and its screenshots from a passing native installer run. Pairs with projectbluefin/testsuite#975, accepted.

    /triage accepted
    /kind documentation

  7. mrbobbytables commented on Oct 27, 2026

    @mrbobbytables
    Contributor

    Summary: This task generates the installation guide and real screenshots from an automated test that runs the installer. It cannot run yet because the automated test suite and console test harness in related projects have not finished being built.


    This issue cannot proceed until external dependencies land:

    • projectbluefin/testsuite#975 ("test: cover the native Bluefin Server installer and emit verified documentation evidence"): Open. The dedicated test suite, screenshot generator, and verified evidence runner in projectbluefin/testsuite have not yet been built or merged into that repository.
    • projectbluefin/server#450 ("test: prove native installer console entry and firmware fixture coverage"): Open and parked at stage/045-needs-decision. It must deliver the native interactive console entry, firmware reachability, and console-driver contract before testsuite#975 can implement the runner and Server can pin to a reviewed testsuite commit.

    Because this issue requires pinning a real merged testsuite commit SHA containing the new suite to regenerate INSTALLATION.md and capture screenshots, work here remains blocked on projectbluefin/testsuite#975 and projectbluefin/server#450.

    — hive: backend=copilot model=gemini-3.8-flash


    🐝 Hive Agent: contributor | SHA: unknown

  8. added
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    on Oct 27, 2026
  9. 16 remaining items

  10. codebymarshall commented on Oct 28, 2026

    @codebymarshall

    Summary: The installation guide has to be built from a successful automated test of the real Bluefin Server installer, using screenshots taken during that test. That test lives in a separate test project and still hasn't been written, so there's no run to build the guide from yet.


    Still blocked by projectbluefin/testsuite#975, which is open as of 2026-10-28. On testsuite main at dadee6e22658b782ec33300eb31099693617980f, no path contains a native Server or evidence suite, and no testsuite PR (open or merged) refers to #975 or native installer work. This issue needs that suite merged so Server can pin its reviewed full commit SHA. A consumer written against a suite that doesn't exist couldn't meet the acceptance criteria.

    Server #450, which #975 depends on, is also still open at stage/045-needs-decision. The offline USB prerequisite, #449, was handled by PR #452, which has merged.

    Pick this up again once testsuite #975 merges.

    — hive: backend=claude


    🐝 Hive Agent: contributor | SHA: unknown

  11. added
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    and removed
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    on Oct 28, 2026
  12. kylerankin commented on Oct 28, 2026

    @kylerankin
    Contributor

    Summary: This issue wants the installation guide and its pictures rebuilt from an automated test that actually runs the Bluefin Server installer. That test lives in a separate test project, and as of today it has not been built or merged there, so there is still no verified installer run to generate the guide from. Nothing in this repository can be shipped until that external test exists.


    What is still missing, checked live now:

    • The blocking dependency, projectbluefin/testsuite#975 ("test: cover the native Bluefin Server installer and emit verified documentation evidence"), is still OPEN. No pull request — open or merged — references it, and no branch in that repo implements native installer coverage with screenshot checkpoints or a documentation-evidence runner.
    • The testsuite installer feature directory holds only installer_post_boot.feature, which checks an already-installed system over SSH. It does not cover a fresh native install, ordered authored instructions, or real screenshots.
    • The testsuite prerequisite, projectbluefin/server#450 (console entry and firmware fixtures), is also still OPEN, parked at stage/045-needs-decision.
    • The offline-USB prerequisite (fix: stop userspace wait-online on offline USB installer boots #449) is resolved — PR #452 merged on 2026-10-12 — but that alone does not produce a runnable evidence suite.
    • The server repo currently has no INSTALLATION.md and no native-install evidence to regenerate. A speculative, pre-pin consumer would not meet the required merged-suite SHA or passing-run evidence, so no PR was opened here.

    This is waiting on an external project to publish its test, not on a decision inside this repository. Pick this up again once projectbluefin/testsuite#975 merges and publishes the reviewed commit SHA and evidence runner this issue pins to.

    — hive: backend=pi model=lemonade/ornith-1.5-35b-a3b-gguf-q6_k


    🐝 Hive Agent: contributor | SHA: unknown

  13. added
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Oct 28, 2026
  14. mrbobbytables commented on Oct 28, 2026

    @mrbobbytables
    Contributor

    Summary: This change would create installation instructions from a successful test of the real Bluefin Server installer. That gives people steps and pictures verified against an actual installation.

    What I need from you: Decide whether tests should cover firmware that rejects the installer before it starts, and how the diskless installer test can reach its prompts without exposing a root password.


    The required native installer test and evidence generator are not available yet: testsuite #975 remains open and is blocked on Server #450. Server #450 is open at stage/045-needs-decision and asks maintainers to resolve the firmware coverage and diskless console authentication questions. Server #449 is closed.

    This issue requires instructions and screenshots from the test suite's passing native installer run, along with a reviewed full commit pin. Generating the guide before those decisions and evidence exist would not meet that requirement. Please resume after the decisions are recorded, the test suite lands, and it can produce a passing run.

    — hive: backend=copilot model=gpt-6-luna


    🐝 Hive Agent: contributor | SHA: unknown

  15. added
    stage/045-needs-decisionIssue parked on a person: needs-human or a maintainer decision is owed before the hive picks it up
    and removed
    stage/045-needs-decisionIssue parked on a person: needs-human or a maintainer decision is owed before the hive picks it up
    on Oct 28, 2026
  16. added
    stage/010-actionableTriaged; eligible for the hive to pick up
    and removed
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    on Nov 8, 2026
  17. Danathar commented on Nov 8, 2026

    @Danathar
    Contributor

    Summary: The installation guide needs instructions and screenshots from a successful test of the real Bluefin Server installer. The separate test project still lacks that test and its evidence generator, so there is no verified run from which to generate the guide.


    Blocked by projectbluefin/testsuite#975, verified open on 2026-11-08. Issue #451 explicitly requires that implementation to merge before Server adopts its reviewed full commit SHA.

    At testsuite main commit 641c09d7f531566a2848ddbf00e8288d081952f0, the existing installer feature checks an already-installed fisherman/bootc system over SSH. The current tree has no dedicated native Server suite or documentation-evidence generator. These post-install checks cannot supply the required executed instructions and actual screenshot checkpoints.

    The suite's prerequisite, Server #450, also remains open at stage/045-needs-decision. Server's refreshed main is 21b81ce04c129246b59d539d6c6d0166678e1874; it has no generated installation guide or image directory. No implementation changes or PR were created. Resume once testsuite #975 delivers the merged evidence producer and a passing native installer run.

    — hive: agent=scanner backend=codex


    🐝 Hive Agent: contributor | SHA: 21b81ce

  18. added
    blockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.
    and removed
    stage/010-actionableTriaged; eligible for the hive to pick up
    on Nov 8, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    approved-directionblockedWaiting on something outside this repository. Use `/label blocked` or `/remove-label blocked`.kind/documentationDocumentation only.triage/acceptedScope accepted; ready for work. Use `/triage accepted`.

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions